feat: `input_code_editor()` Component #1274

gadenbuie · 2025-12-31T14:07:47Z

Overview

input_code_editor() is a Shiny input that provides a lightweight code editor with syntax highlighting, powered by prism-code-editor. It supports 20+ languages (a subset of those supported by prism-code-editor), multiple themes, and automatic light/dark mode switching.

File Layout

bslib/
├── R/
│   └── input-code-editor.R          # R API: input_code_editor(), update_code_editor()
├── srcts/
│   └── src/components/
│       └── codeEditor.ts            # BslibCodeEditor web component
├── inst/
│   ├── lib/
│   │   └── prism-code-editor/       # Vendored prism-code-editor library
│   ├── components/scss
│   │   └── input_code_editor.scss   # Shiny code editor styles, compiled with other bslib component styles
│   └── examples-shiny/
│       └── code-editor/app.R        # Demo application
│
└── tests/testthat/
    └── test-input-code-editor.R     # Unit tests

Architecture

Key Design Decisions

Custom Element: The editor is a web component (<bslib-code-editor>) extending HTMLElement. This provides standard lifecycle hooks and attribute reflection, simplifying Shiny integration via the shared makeInputBinding() helper.
Separate Bundle: code-editor.js is NOT bundled into components.min.js. It's loaded only when input_code_editor() is used, keeping the main bslib bundle small.
ES Modules: The code-editor bundle uses ESM format to support dynamic imports of language grammars at runtime.
Lazy Loading: Language grammars and themes are loaded on-demand when the editor initializes (connectedCallback()) or when receiving an update messages from the server, not upfront.
Theme Watching: Each editor instance creates a MutationObserver that watches <html data-bs-theme> to automatically switch between light/dark themes. Theme stylesheets are shared across all instances and never unloaded.

R API (`R/input-code-editor.R`)

Exported Functions

Function	Purpose
`input_code_editor()`	Create a code editor input
`update_code_editor()`	Update editor from server
`code_editor_themes()`	List available themes

Internal Functions

Function	Purpose
`code_editor_dependencies()`	Returns all HTML dependencies
`code_editor_dependency_prism()`	Prism library dependency
`code_editor_dependency_js()`	bslib binding JS dependency
`arg_match_language()`	Validate language parameter
`arg_match_theme()`	Validate theme parameter
`check_value_line_count()`	Warn if >1000 lines

HTML Output Structure

The component uses a custom element <bslib-code-editor> with kebab-case attributes:

<bslib-code-editor
    id="{id}"
    language="{language}"
    value="{value}"
    theme-light="{theme_light}"
    theme-dark="{theme_dark}"
    readonly="{read_only}"
    line-numbers="{line_numbers}"
    word-wrap="{word_wrap}"
    tab-size="{tab_size}"
    insert-spaces="{insert_spaces}">
  <label for="{id}">{label}</label>
  <div class="code-editor"></div>  <!-- Editor mounts here -->
</bslib-code-editor>

TypeScript Web Component (`srcts/src/components/codeEditor.ts`)

The editor is implemented as a custom element (<bslib-code-editor>) that extends HTMLElement and implements CustomElementInputGetValue<string> for Shiny integration.

Class: `BslibCodeEditor`

Static Properties:

tagName = "bslib-code-editor": Custom element tag name
isShinyInput = true: Marks this as a Shiny input for makeInputBinding()
observedAttributes: List of attributes that trigger attributeChangedCallback()

Static Methods (shared across all instances):

#getBasePath(): Locates and caches path to prism-code-editor assets
#loadLanguage(): Dynamically imports language grammars (cached)
#loadTheme(): Loads theme stylesheets (cached, never unloaded)

Instance Properties (reflect to/from HTML attributes):

language, readonly, lineNumbers, wordWrap, tabSize, insertSpaces
themeLight, themeDark
value: Current editor content (get/set on prismEditor)

Lifecycle Methods:

connectedCallback(): Initializes editor when element is added to DOM
disconnectedCallback(): Cleans up MutationObserver when removed
attributeChangedCallback(): Responds to attribute changes by updating prism-code-editor

Key Instance Methods:

getValue(): Returns current content (for Shiny input binding)
receiveMessage(): Handles update_code_editor() calls from R
_initializeEditor(): Creates prism-code-editor instance, sets up Ctrl+Enter and blur handlers
_setupThemeWatcher(): Watches data-bs-theme on <html> to switch themes
_handleLanguageChange(): Loads new grammar and updates editor

Shiny Integration

The Shiny input binding is created via the shared makeInputBinding() helper:

customElements.define(BslibCodeEditor.tagName, BslibCodeEditor);

if (window.Shiny) {
  makeInputBinding<string>(BslibCodeEditor.tagName);
}

The makeInputBinding() helper (from webcomponents/_makeInputBinding.ts) creates a standard Shiny input binding that:

Finds elements by tag name
Delegates getValue() and receiveMessage() to the custom element instance
Uses the element's onChangeCallback for value updates

tsconfig.json Note

The module: esnext setting is required for dynamic imports. The ts-node section overrides this to commonjs for the build script only.

Vendoring (`tools/yarn_install.R`)

How It Works

inst/package.json declares prism-code-editor-full dependency (aliased from prism-code-editor-lightweight)
yarn install in inst/ downloads to node_modules/
node_modules/ is moved to lib/
Script copies needed files from prism-code-editor-full/dist/ to prism-code-editor/
Full package is deleted, only selective files remain
Version is written to R/versions.R

Updating prism-code-editor

Update version in inst/package.json:

"prism-code-editor-full": "npm:prism-code-editor-lightweight@X.Y.Z"

Run Rscript tools/yarn_install.R or Rscript tools/main.R
Verify R/versions.R has updated version
Run tests: devtools::test(filter = "code-editor")

Adding New Languages

Languages are loaded dynamically from inst/lib/prism-code-editor/prism/languages/. To add a new language:

Verify the grammar file exists in prism/languages/{lang}.js
Add to code_editor_bundled_languages in tools/yarn_install.R and re-run the yarn install script.
Verify code_editor_bundled_languages in R/versions.R is updated.
Update @param language documentation in R/input-code-editor.R.

Adding New Themes

Themes are CSS files in inst/lib/prism-code-editor/themes/. Available themes are auto-discovered by code_editor_themes().

To add a custom theme:

Add {theme-name}.css to inst/lib/prism-code-editor/themes/
It will automatically appear in code_editor_themes() output

Testing

Unit tests of input_code_editor() are in tests/testthat/test-input-code-editor.R and can be run with devtools::test(filter = "code-editor").

An example Shiny app demonstrating the editor is in inst/examples-shiny/code-editor/app.R and can be run with:

shiny::runApp("inst/examples-shiny/code-editor")

# For package users:
shiny::runExample("code-editor", package = "bslib")

CSS Customization

The editor uses CSS variables for Bootstrap integration. Key selectors:

bslib-code-editor - Custom element (outer container)
.code-editor - Inner editor container where prism-code-editor mounts
.code-editor-submit-flash - Flash animation on Ctrl+Enter

See inst/components/scss/input_code_editor.scss for full styles.

Each theme is wrapped with attribute selectors that match the editor's `data-theme-light`/`data-theme-dark` attributes, combined with the page's `data-bs-theme` attribute, using CSS nesting (supported in all modern browsers since late 2023).

R/input-code-editor.R

Ports the `input_code_editor()` component from bslib PR #1274 to py-shiny. ## Overview `input_code_editor()` is a lightweight code editor input with syntax highlighting powered by prism-code-editor. It supports 20+ languages, multiple themes, and automatic light/dark mode switching. ## Added - `input_code_editor()` - Create a code editor input - `update_code_editor()` - Update editor from server - `code_editor_themes()` - List available themes ## Key decisions for human review 1. **Dependency structure**: The code editor uses two HTML dependencies: - `prism-code-editor` (vendored library for syntax highlighting) - `bslib-code-editor-js` (the Shiny input binding) 2. **Themes list**: Manually hardcoded the theme list to match the vendored CSS files. The R version discovers these dynamically, but Python doesn't have easy access to the vendored directory at runtime. 3. **Language validation**: Using a hardcoded tuple of supported languages instead of dynamic discovery, matching the R implementation's approach. 4. **Manual vendoring**: Due to issues with the automated vendoring script (ionRangeSlider CSS step fails), assets were manually copied from the bslib feat/input-code branch. Updated htmlDependencies.R to include the prism-code-editor copy for future runs once bslib PR is merged. 5. **Value handling**: The `value` parameter accepts either a string or a sequence of strings (lines), matching Python idioms. 6. **Fill behavior**: Added `html-fill-container` and `html-fill-item` classes for fillable layout support, similar to other fill components. Related: rstudio/bslib#1274 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

gadenbuie and others added 26 commits December 29, 2025 15:35

feat: Add input_code_editor()

7dac6ac

feat: revisit bundled languages

3c529a8

refactor: review and refactor code

ac5115d

chore: adjust examples

bd8173e

chore: update docs

111f6df

tests: Update assertion (html -> markup)

b40aa81

tests: refactor and clean up a bit

07be220

chore: Use shiny dev console messages

c29790f

refactor: Simplify input validation, allow attrs in ...

a689a5d

docs: Add to pkgdown reference index

a85ae95

chore: slimmer bundle by removing unused theme js files

85302a3

refactor: now it's a custom element web component

1254a0b

chore: Upgrade to prism-code-editor@4.2.0

fdb5ea3

chore(example): Improve sample code loading

6257236

tests: update snapshots

f638355

chore: Don't need to conditionally load themes

aa18f99

chore: Fix editor styles when dark/light not set on <html>

2b0f92c

chore: Accept character vector for value, default language to plain

a743806

chore: small style edits to example app

0c958b2

chore: Don't export code_editor_themes()

d7567a3

chore: Bump warning to 1,000 lines exactly

26115ca

tests: fix defaults test

f04b362

tests: simplify a bit

f37bf16

air format (GitHub Actions)

a5d689b

chore: remove temp querychat submodule

b545b50

gadenbuie commented Dec 31, 2025

View reviewed changes

R/input-code-editor.R Show resolved Hide resolved

gadenbuie commented Dec 31, 2025

View reviewed changes

R/input-code-editor.R Outdated Show resolved Hide resolved

gadenbuie added 2 commits December 31, 2025 12:53

feat: Allow updating label, standardize function signature

8a1ca00

chore: Add NEWS bullet

34b71af

devtools::document() (GitHub Actions)

8b83372

gadenbuie mentioned this pull request Dec 31, 2025

feat: input_code_editor() posit-dev/py-shiny#2128

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: `input_code_editor()` Component #1274

feat: `input_code_editor()` Component #1274

Uh oh!

gadenbuie commented Dec 31, 2025

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: input_code_editor() Component #1274

Are you sure you want to change the base?

feat: input_code_editor() Component #1274

Uh oh!

Conversation

gadenbuie commented Dec 31, 2025

Overview

File Layout

Architecture

Key Design Decisions

R API (R/input-code-editor.R)

Exported Functions

Internal Functions

HTML Output Structure

TypeScript Web Component (srcts/src/components/codeEditor.ts)

Class: BslibCodeEditor

Shiny Integration

tsconfig.json Note

Vendoring (tools/yarn_install.R)

How It Works

Updating prism-code-editor

Adding New Languages

Adding New Themes

Testing

CSS Customization

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat: `input_code_editor()` Component #1274

feat: `input_code_editor()` Component #1274

R API (`R/input-code-editor.R`)

TypeScript Web Component (`srcts/src/components/codeEditor.ts`)

Class: `BslibCodeEditor`

Vendoring (`tools/yarn_install.R`)