port-from-bslib by posit-dev

---
name: port-from-bslib
description: Comprehensive guide for porting UI components from R's bslib package to py-shiny. Use this skill when: (1) User asks to "port this feature" or "port a component" and mentions bslib or links to a bslib PR (e.g., github.com/rstudio/bslib/pull/...), (2) Porting a new component from bslib to py-shiny, (3) Adding a new input, output, or UI component that exists in bslib, (4) Implementing feature parity with bslib, (5) Working on bslib-related features or components. Covers the complete workflow including understanding source implementation, creating Python equivalents, vendoring assets (SCSS, CSS, JavaScript), creating tests, documentation, and all necessary project files.
---

# Porting Components from bslib to py-shiny

This guide explains how to port new UI components from the R bslib package to py-shiny. It assumes you're an experienced developer familiar with Python, R, and JavaScript/TypeScript, but may be new to the specifics of these repositories.

## Background

The bslib R package serves as the primary development location for new Bootstrap 5 components in the Shiny ecosystem. Components developed in bslib are then ported to py-shiny to maintain feature parity between Shiny for R and Shiny for Python.

**Key relationship**: bslib provides both the R implementation and the compiled JavaScript/CSS assets that py-shiny vendors and uses directly.

## Overview of the Porting Process

The porting process involves three main phases:

1. **Understanding the source** - Study the bslib implementation (R, TypeScript, SCSS)
2. **Implementing the port** - Create Python equivalents and add client-side bindings
3. **Testing and documentation** - Ensure correctness with unit and end-to-end tests

## Phase 1: Understanding the Source Implementation

### Step 1.1: Locate the bslib PR

Find the bslib PR that introduced the feature. The py-shiny PR description should reference it (e.g., `Related https://github.com/rstudio/bslib/pull/...`).

**Checklist:**
- [ ] Located the bslib PR
- [ ] Reviewed the PR description and any design discussions

### Step 1.2: Identify the core source files

In the bslib PR, locate these key files:

1. **R implementation**: `R/[feature-name].R` - The main component function(s)
2. **TypeScript bindings**: `srcts/src/components/[featureName].ts` - Client-side behavior
3. **SCSS styles**: `inst/components/scss/[feature_name].scss` - Component styles
4. **Unit tests**: `tests/testthat/test-[feature-name].R` - R unit tests

**Note**: Generated files (compiled JS/CSS, documentation) can be ignored - focus on source files.

**Checklist:**
- [ ] Found the R implementation file(s)
- [ ] Found the TypeScript source file(s)
- [ ] Found the SCSS source file
- [ ] Found the unit test file(s)
- [ ] Reviewed how TypeScript is registered in `srcts/src/components/index.ts`

### Step 1.3: Understand the component structure

Study the bslib implementation to understand:

1. **API design**: Function signature, parameters, defaults
2. **HTML structure**: The DOM elements created by the R function
3. **Client-side behavior**: How the TypeScript binding handles interactions
4. **Shiny communication**: How the component sends/receives values from the server
5. **Dependencies**: What other components or utilities it relies on

**Key patterns to note:**
- Is the component an input binding? If so, how does the binding register (typically via a CSS class)?
- What markup structure does it generate on the server side?
- How does the component integrate with Bootstrap classes?
- How are configuration options passed from R to JavaScript -- data attributes, embedded JSON, etc.?
- How does the component receive data from the server -- via `sendInputMessage()` or `sendCustomMessage()`?
- How does the component receive data from the client -- via `receiveMessage()` or small inputs set with `Shiny.setInputValue()`?

**Checklist:**
- [ ] Documented the component's API surface
- [ ] Understood the HTML structure and CSS classes
- [ ] Identified client-side event handlers and state management
- [ ] Noted any dependencies on other components

## Phase 2: Implementing the Port

### Step 2.1: Create the Python implementation

Create a new file in `shiny/ui/` for the component implementation.

**File naming**: Use snake_case matching the R function name:
- R: `input_submit_textarea()` → Python: `_input_submit_textarea.py`

**Implementation notes:**
- Translate R's htmltools to Python's htmltools
- Use `@add_example()` decorator for documentation examples (examples are created in a later step)
- Follow existing patterns for parameter validation
- Use `resolve_id()` for module namespace support
- Use `restore_input()` for bookmarking support
- Include both the main component function and any `update_*()` functions

**Common translations:**
- R `tags$div()` → Python `div()` or `tags.div()`
- R `!!!args` (splicing) → Python `*args`+`**kwargs`
- R `NULL` → Python `None`
- R lists → Python dicts or lists as appropriate
- R `paste0()` → Python f-strings or `.format()`

**Checklist:**
- [ ] Created `shiny/ui/_[component_name].py`
- [ ] Implemented the main component function with full docstring
- [ ] Implemented any `update_*()` functions
- [ ] Added parameter validation
- [ ] Added support for modules (`resolve_id`)
- [ ] Added support for bookmarking (`restore_input`)
- [ ] Used `components_dependencies()` for client-side deps

### Step 2.2: Export the new functions

Update `shiny/ui/__init__.py` to export the new component:

```python
from ._input_submit_textarea import input_submit_textarea, update_submit_textarea

__all__ = (
    # ... existing exports ...
    "input_submit_textarea",
    "update_submit_textarea",
)
```

If the component is suitable for express mode, also export from `shiny/express/ui/__init__.py`.

**Checklist:**
- [ ] Added imports to `shiny/ui/__init__.py`
- [ ] Added to `__all__` tuple in `shiny/ui/__init__.py`
- [ ] (If applicable) Exported from `shiny/express/ui/__init__.py`

### Step 2.3: Vendor assets from bslib

The TypeScript in bslib is compiled to JavaScript and bundled, and SCSS is compiled to CSS. Py-shiny vendors these compiled assets along with the SCSS source files from bslib.

**Process:**
1. Ensure bslib PR is merged and the feature is in the branch referenced in `scripts/_pkg-sources.R` (usually `@main`)
2. If vendoring from a non-default branch or specific commit, update `scripts/_pkg-sources.R` temporarily
3. Run `make upgrade-html-deps` to vendor the latest assets from bslib, shiny, sass, and htmltools

**What `make upgrade-html-deps` does:**
- Copies SCSS source files from bslib to `shiny/www/shared/sass/bslib/components/scss/`
- Updates all theme preset `_04_rules.scss` files to import the new SCSS
- Compiles SCSS to CSS for all themes
- Vendors compiled JavaScript bundles (`components.min.js`, etc.)
- Updates other shared assets from upstream packages

**Files updated by this process** (examples):
- `shiny/www/shared/sass/bslib/components/scss/[feature_name].scss` (SCSS source)
- `shiny/www/shared/sass/preset/*/04_rules.scss` (27 theme preset files with new imports)
- `shiny/www/shared/bslib/components/components.min.js` (compiled JavaScript)
- `shiny/www/shared/bslib/components/components.min.js.map` (source map)
- `shiny/www/shared/bslib/components/components.css` (compiled CSS)
- Other theme-specific CSS files

**Note**: This is a manual process that's not part of CI. The vendored files are committed to the repository.

**Checklist:**
- [ ] Verified bslib PR is merged (or adjusted `scripts/_pkg-sources.R` if needed)
- [ ] Ran `make upgrade-html-deps`
- [ ] Reviewed changes to vendored files (SCSS, CSS, JS)
- [ ] Verified new SCSS imports in theme preset files
- [ ] Restored `scripts/_pkg-sources.R` if temporarily modified

### Step 2.4: Create API examples

Create example applications demonstrating the component's usage.

**Location**: `shiny/api-examples/[component_name]/`

**Files to create**:
- `app-core.py` - Core mode example
- `app-express.py` - Express mode example (if applicable)

**Example structure**:
```python
# app-express.py
from shiny.express import input, render, ui

ui.input_submit_textarea("text", placeholder="Enter some input...")

@render.text
def value():
    if "text" in input:
        return f"You entered: {input.text()}"
    else:
        return "Submit some input to see it here."
```

**Best practices**:
- Keep examples simple and focused
- Demonstrate the primary use case
- Show server-side value handling patterns
- Include any important parameter variations
- Re-use examples from bslib where possible
- Always include an Express version unless there's a strong reason not to
- A human reviewer should test the examples locally

**Checklist:**
- [ ] Created `shiny/api-examples/[component]/app-core.py`
- [ ] Created `shiny/api-examples/[component]/app-express.py` (unless not warranted)
- [ ] Tested examples locally

### Step 2.5: Add Playwright controller (if input component)

If the component is an input component, create a Playwright controller for end-to-end testing.

**Location**: `shiny/playwright/controller/_input_fields.py` (or create new file if needed)

**Implementation**:
1. Create a new class inheriting from appropriate mixins
2. Implement required methods: `__init__`, `set`, interaction methods
3. Add expectation methods for testing (e.g., `expect_value`, `expect_placeholder`)
4. Follow existing patterns for locator initialization

**Example pattern**:
```python
class InputSubmitTextarea(
    _SetTextM,
    WidthContainerStyleM,
    _ExpectTextInputValueM,
    _ExpectPlaceholderAttrM,
    _ExpectRowsAttrM,
    UiWithLabel,
):
    """Controller for :func:`shiny.ui.input_submit_textarea`."""

    loc_button: Locator

    def __init__(self, page: Page, id: str) -> None:
        super().__init__(
            page,
            id=id,
            loc=f"textarea#{id}.form-control",
        )
        self.loc_button = self.loc_container.locator(".bslib-submit-textarea-btn")

    def set(self, value: str, *, submit: bool = False, timeout: Timeout = None) -> None:
        # Implementation
        pass
```

**Don't forget to export**: Update `shiny/playwright/controller/__init__.py` to export the new controller class.

**Checklist:**
- [ ] Created Playwright controller class
- [ ] Implemented core interaction methods
- [ ] Implemented expectation methods for testing
- [ ] Exported from `shiny/playwright/controller/__init__.py`
- [ ] Added to `__all__` in the same file

## Phase 3: Testing and Documentation

### Step 3.1: Port unit tests from bslib

Port the relevant unit tests from bslib's testthat tests to pytest.

**Translation patterns**:
- R `test_that()` → Python `def test_[name]():`
- R `expect_snapshot()` → Python snapshot testing (if applicable)
- R `expect_error()` → Python `with pytest.raises()`

**Focus on**:
- Parameter validation
- Error messages
- Edge cases
- HTML structure (snapshot tests if helpful)

**Note**: Python has better tooling for end-to-end tests, so unit tests here focus on correctness of the Python API and generated markup.

**Checklist:**
- [ ] Ported relevant unit tests
- [ ] Tests pass locally (`pytest tests/`)

### Step 3.2: Create end-to-end Playwright tests

Create comprehensive end-to-end tests using Playwright. It is likely that these tests do not exist in the R package, so you will need to use your knowledge of the component and its documented behavior to create them. Collaborate with the human reviewer if there are any uncertainties around expected behavior.

**Location**: `tests/playwright/shiny/inputs/[component_name]/`

**Files to create**:
- `app.py` - Test application with multiple variants
- `test_[component_name].py` - Playwright test cases

**Test coverage should include**:
- Initial state verification
- User interactions (typing, clicking, keyboard shortcuts)
- Server updates (via `update_*()` functions)
- Edge cases (empty values, disabled states, etc.)
- Multiple submissions and state changes

**Example test structure**:
```python
def test_input_submit_textarea_initial_state(page: Page, local_app: ShinyAppProc):
    page.goto(local_app.url)

    basic = controller.InputSubmitTextarea(page, "basic")
    basic.expect_label("Enter text")
    basic.expect_placeholder("Type something here...")
    basic.expect_value("Initial value")

    value_output = controller.OutputCode(page, "basic_value")
    value_output.expect_value("No value submitted yet")
```

**Best practices**:
- Use the Playwright controller for interactions
- Test both user interactions and programmatic updates
- Use clear, descriptive test names
- Verify both input state and output state
- Output state can be checked by rendering text outputs in the test app

**Checklist:**
- [ ] Created test app with multiple component variations
- [ ] Created comprehensive test cases
- [ ] Tests pass locally (`pytest tests/playwright/`)
- [ ] Covered key interaction patterns and edge cases

### Step 3.3: Update CHANGELOG

Add an entry to `CHANGELOG.md` under the `[UNRELEASED]` section.

**Format**:
```markdown
### New features

* Added `input_new_feature()` [description of function, new features and salient details in 1-3 sentences]. (#[PR_NUMBER])
```

**Checklist:**
- [ ] Added CHANGELOG entry under appropriate section
- [ ] Entry includes clear description and PR reference

### Step 3.4: Run quality checks

Run the various quality checks to ensure your code meets project standards.

**Recommended workflow**:
1. `make formatting` - Fix formatting and linting issues automatically
2. `make check-types` - Run type checking (pyright)
3. `make check-tests` - Run the test suite
4. `make playwright` - Run Playwright end-to-end tests (see `Makefile` for alternate make commands to run subsets of tests)
5. `make check` - Comprehensive checks (slower, runs everything)

**Common issues**:
- Type errors: Ensure proper type hints on all functions
- Format errors: Run `make format` to auto-fix
- Missing imports: Ensure all new modules are properly imported
- Test failures: Debug and fix any failing tests

**Checklist:**
- [ ] `make format` applied successfully
- [ ] `make check-types` passes
- [ ] `make check-tests` passes (or at least your new tests pass)
- [ ] `make playwright` passes (or at least new end-to-end tests pass)
- [ ] Addressed any other linting/quality issues

### Step 3.5: Update API reference configuration

Add the new component functions to the quartodoc YAML configuration files so they appear in the generated documentation.

**Files to update**:
- `docs/_quartodoc-core.yml` - Add component function and update function (if applicable)
- `docs/_quartodoc-express.yml` - Add express versions (if applicable)
- `docs/_quartodoc-testing.yml` - Add Playwright controller (if applicable)

**Where to add entries**:
- Find the appropriate section (e.g., "Inputs" for input components, "Update" for update functions)
- Add entries in alphabetical order within the section
- Use the full module path (e.g., `ui.input_submit_textarea`)

**Example additions**:
```yaml
# In _quartodoc-core.yml under inputs section:
- ui.input_submit_textarea

# In _quartodoc-core.yml under update section:
- ui.update_submit_textarea

# In _quartodoc-express.yml:
- express.ui.input_submit_textarea
- express.ui.update_submit_textarea

# In _quartodoc-testing.yml:
- playwright.controller.InputSubmitTextarea
```

**Checklist:**
- [ ] Added entries to `docs/_quartodoc-core.yml`
- [ ] Added entries to `docs/_quartodoc-express.yml` (if applicable)
- [ ] Added entries to `docs/_quartodoc-testing.yml` (if applicable)
- [ ] Verified alphabetical ordering within sections

### Step 3.6: Build documentation (final step)

Only build documentation at the very end, as it's slow and resource-intensive.

**Command**: `make docs`

**This will**:
- Generate API reference documentation from the quartodoc YAML files
- Build example applications
- Create the documentation website

**Note**: You don't need to run this frequently during development. It's primarily for final verification before PR submission. A human reviewer can handle this entire step, just remind them to run it before merging.

**Checklist:**
- [ ] `make docs` completes successfully
- [ ] Reviewed the generated documentation for your component
- [ ] API reference appears correctly in the appropriate sections
- [ ] Examples are properly linked

## Phase 4: Final Review and Submission

### Step 4.1: Self-review the changes

Before submitting, review all changes:

**Python code**:
- [ ] Functions have comprehensive docstrings
- [ ] Parameter types and defaults match or improve on bslib's API
- [ ] Code follows existing project patterns
- [ ] Error messages are clear and helpful

**Tests**:
- [ ] Unit tests cover parameter validation and edge cases
- [ ] End-to-end tests cover user workflows
- [ ] All tests pass locally

**Styles**:
- [ ] SCSS is imported in all theme presets
- [ ] Styles match the bslib implementation

**Documentation**:
- [ ] CHANGELOG is updated
- [ ] API examples are clear and working
- [ ] Docstrings are complete

### Step 4.2: Create the PR

Create a pull request with:

1. **Title**: `feat: Add [component_name]` or similar
2. **Description**:
   - Link to the source bslib PR
   - Brief description of the component
   - Any implementation notes or decisions
   - Example usage

**PR description template**:
```markdown
Related https://github.com/rstudio/bslib/pull/[NUMBER]

Adds `[component_name]`, a new [input/output/UI] component that [brief description].

## Example

Here is a hello world example:

[code block with example]

## Implementation notes

[Any important notes about the implementation, decisions made, etc. or open questions for reviewers.]
```

**Checklist:**
- [ ] PR title follows project conventions
- [ ] PR description links to bslib source
- [ ] PR description includes example usage
- [ ] All quality checks pass in CI

---

## Quick Reference Checklist

Use this high-level checklist to track your progress through the porting process:

### Preparation
- [ ] Located and reviewed the bslib PR
- [ ] Identified all source files (R, TypeScript, SCSS, tests)
- [ ] Understood the component's API and behavior

### Implementation
- [ ] Created Python implementation in `shiny/ui/_[name].py`
- [ ] Exported from `shiny/ui/__init__.py` (and express if applicable)
- [ ] Ran `make upgrade-html-deps` to vendor assets from bslib (SCSS, CSS, JavaScript)
- [ ] Created API examples (core and express)
- [ ] Created Playwright controller (if input component)

### Testing
- [ ] Ported unit tests from bslib
- [ ] Created comprehensive Playwright tests
- [ ] Updated CHANGELOG

### Documentation
- [ ] Updated quartodoc YAML files to include new functions
- [ ] Ran `make format`
- [ ] Passed `make check-types`
- [ ] Passed `make check-tests`
- [ ] Built docs with `make docs`

### Submission
- [ ] Self-reviewed all changes
- [ ] Created PR with proper description
- [ ] All CI checks passing

---

## Common Patterns and Tips

### Handling component dependencies

If the component depends on other components:
- Use `components_dependencies()` for bslib components (automatic)
- For other dependencies, add them explicitly in the component function

### Testing with different themes

The component should work with all Bootstrap themes. The `make upgrade-html-deps` process ensures SCSS is properly imported across all theme presets, but you may want to spot-check a few themes manually during development.

### Parameter naming conventions

Python style guide preferences:
- Use `snake_case` for parameter names
- Match bslib's parameter names when possible
- Use `Optional[T]` for user-facing parameters that can be `None`
- Use `Literal` rather than `Enum` for parameters with specific allowed values

### Working with htmltools

Key patterns:
- `Tag` objects are mutable by default, use `copy.copy()` if you need to modify
- Use `.add_class()`, `.add_style()`, `.attrs` to add CSS classes, styles, and HTML attributes
- Create new tags with `ui.tags` and add attributes and children directly, e.g. `ui.tags.div(class_="fw-bold", ...)`
- Use `css()` helper for inline styles
- Tag children can be strings, Tags, TagLists, or None

---

## Troubleshooting

### "Tests fail with 'element not found'"

- Verify Playwright selectors match the actual HTML structure
- Check that the component is properly rendered before interaction
- Use `page.wait_for_selector()` if there are timing issues

### "SCSS not taking effect"

- Check that `make upgrade-html-deps` was run to vendor and compile SCSS/CSS
- Verify the SCSS file exists in `shiny/www/shared/sass/bslib/components/scss/`
- Verify the imports were added to preset `_04_rules.scss` files (should be automatic)
- Clear browser cache when testing

---

## Additional Resources

- **bslib repository**: https://github.com/rstudio/bslib
- **py-shiny repository**: https://github.com/posit-dev/py-shiny
- **Example PR (bslib)**: https://github.com/rstudio/bslib/pull/1204
- **Example PR (py-shiny)**: https://github.com/posit-dev/py-shiny/pull/2099

For questions or clarifications, consult with the Shiny team or reference previous component ports for patterns.