feat: `input_code_editor()` Component by gadenbuie · Pull Request #1274 · rstudio/bslib

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
│   └── codeEditor.css               # BslibCodeEditor styles
├── inst/
│   ├── lib/
│   │   └── prism-code-editor/       # Vendored prism-code-editor library
│   └── 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 srcts/src/components/codeEditor.css 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>

inst/examples-shiny/code-editor/examples/r.r

R/input-code-editor.R

tools/yarn_install.R

srcts/src/components/codeEditor.ts

cpsievert

Well done and nice feature! 👏

One slight concern I have is that it makes the problem in posit-dev/py-shiny#2125 slightly worse (will add ~100 new files to shiny wheel). That said, I think we could cut ~300 (about 25%) by moving Theme to a separate package, so maybe that's the more worthwhile cost saving?

cpsievert · 2026-01-06T00:21:40Z

inst/components/scss/input_code_editor.scss

I'm tempted to say that, because this doesn't depend on Bootstrap Sass, it should get compiled separately and brought in with the code editor dependency instead.

I think this would simply things on the py-shiny end, but not sure if it's actually worth it or not -- your call

Yeah this is how I set it up initially and I'd be okay with moving back to it. I was trying to integrate everything into the existing build process a little more, but there's not too far you can go if we want to keep the code editor dependencies separate.

I'll switch it back. We don't really gain anything by keeping them together, but separating them would untangle the code editor enough that it would help us move it into a separate package if we ever needed to. It just wasn't super clear where I'd put that .css file: I had it in inst/components/dist/ initially, but didn't like that dist/ sounds like something you can delete and have re-built. Maybe could just be a file in components/...

I moved it into a static file that lives in srcts/src/components/codeEditor.css and gets moved into inst/components/dist during the build process.

cpsievert · 2026-01-06T00:44:56Z

tools/yarn_install.R

+    Sys.glob(file.path(src, "*.css"))
+  )
+  core_files <- core_files[!grepl(theme_js_pattern, basename(core_files))]
+  file.copy(core_files, dest)


I feel like it's maybe worth removing some of the CSS/JS that isn't needed? Here's a handful that Claude identified:

- autocomplete*.css, code-block.css, folding.css, guides.css - extensions/cursor.js, extensions/guides.js, extensions/matchTags.js

Agreed we could probably cut more of these. I was thinking we might want to turn some of these on or enable them behind flags, which gets harder to do when the files aren't around.

I'll take a pass at slimming this down tomorrow in a way that would be easy for us to unroll later if we want to add extensions.

I went through and aggressively removed extensions and files we don't need. There might be one or two that we don't fully use, but it's significantly slimmer now.

While looking into this, I learned about a built-in method for adding tooltips to the editor, so I updated the editor to give decent visual feedback when you try to modify a read-only editor

cpsievert · 2026-01-07T16:07:58Z

srcts/build/index.ts

+
+      build.onEnd(() => {
+        copyFileSync(source, dest);
+        console.log("√ -", "code-editor.css", "-", new Date().toJSON());


I think you meant to log source or dest here?

thanks, fixed it over here: 93422f5

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

Merged

gadenbuie and others added 2 commits January 5, 2026 13:16

chore: small tweaks to examples

3e72c85

yarn build (GitHub Actions)

ba7706d

gadenbuie requested a review from cpsievert January 5, 2026 19:31

chore: completely remove temp git module

65b88c0