timetracker/docs/superpowers/specs/2026-06-20-onswap-to-custom-elements-design.md

Convert Remaining onSwap Widgets to Custom Elements

Date: 2026-06-20
Issue: #18
Relates to: #17 (TS migration), spec 2026-06-13-html-js-authoring-design.md

Context

PR #16 established the custom-element pattern (TypeScript custom elements, connectedCallback lifecycle, codegen'd typed prop contracts) and converted three components. Four interactive widgets still use the old pattern: a hand-written .ts file registered with onSwap(selector, fn) + data-* attributes.

Goal: Migrate all four remaining widgets to the custom-element pattern so the whole interactive surface uses one model.

Widgets and Dependency Order

Convert in this order (least-to-most dependent):

1. range-slider — no cross-widget deps
2. date-range-picker — no cross-widget deps
3. search-select — no deps; exports readSearchSelect() consumed by filter-bar
4. filter-bar — imports readSearchSelect; removes all window.* globals

onSwap is NOT retired by this issue — year_picker.ts and add_purchase.ts still use it (see #17).

Per-Widget Conversion Pattern

Each widget follows the same steps:

Python side

1. Add XxxProps(TypedDict) to common/components/custom_elements.py
2. Call register_element("xxx", "Xxx", XxxProps) immediately after
3. Create _Xxx = custom_element_builder("xxx")
4. Update the Python component (in filters.py, search_select.py, or date_range_picker.py) to use the builder; remove old _XXX_MEDIA and .with_media(...) calls

TypeScript side

5. Create ts/elements/xxx.ts (move logic from ts/xxx.ts)
6. Replace IIFE + onSwap(selector, fn) with class XxxElement extends HTMLElement { connectedCallback() { ... } }
7. Read typed props via generated readXxxProps(this) instead of el.getAttribute("data-xxx")
8. Add disconnectedCallback() to remove any document-level event listeners
9. End with customElements.define("xxx", XxxElement)

Build

10. uv run manage.py gen_element_types — regenerates ts/generated/props.ts
11. make ts — compiles all TypeScript
12. make check — linting + type-check + tests

E2E

13. Update Playwright locators to match new element tags and attribute names

Widget Specifics

range-slider

Props:

class RangeSliderProps(TypedDict):
    min: int
    max: int
    step: int
    mode: str  # "range" | "point"

Structural change: <range-slider> replaces the outer .range-slider-block wrapper div AND the inner .range-slider div. The mode toggle button and the track/handles all become light-DOM children of <range-slider>. This eliminates slider.closest(".range-slider-block") — the TS can use this.querySelector(".range-mode-toggle") directly.

The data-mode attribute becomes the typed mode prop (attribute mode on the element). The JS updates this attribute on toggle: this.setAttribute("mode", newMode).

E2E: .range-slider-block → range-slider; slider[data-mode] → range-slider[mode].

date-range-picker

Props:

class DateRangePickerProps(TypedDict):
    input_name_prefix: str

Structural change: <date-range-picker> replaces the outer <div data-date-range-picker data-input-name-prefix="...">. DateRangeField and DateRangeCalendar remain unchanged as light-DOM children.

The data-input-name-prefix attribute on DateRangeCalendar can be removed since the prefix is now a typed prop on the element itself, readable as readDateRangePickerProps(this).inputNamePrefix.

search-select

Props:

class SearchSelectProps(TypedDict):
    name: str
    search_url: str      # empty string when no URL
    multi: bool
    filter_mode: bool    # true for FilterSelect; replaces data-search-select-mode="filter"
    free_text: bool
    always_visible: bool
    prefetch: int
    sync_url: bool

Structural change: <search-select> replaces the outer <div data-search-select ...>. All internal child elements ([data-search-select-search], [data-search-select-options], etc.) remain unchanged.

readSearchSelect export: Remove window.readSearchSelect = .... Export as a named module function:

export function readSearchSelect(scope: HTMLElement): void { ... }

filter_bar.ts will import it. Update the function to query search-select[filter-mode="true"] instead of [data-search-select][data-search-select-mode="filter"].

E2E: [data-search-select][data-name="status"] → search-select[name="status"].

filter-bar

Props:

class FilterBarProps(TypedDict):
    preset_list_url: str
    preset_save_url: str

Structural change: <filter-bar> wraps the entire filter bar structure (collapse toggle + form + action row). The Python _FilterBarBase.render() wraps its output in the builder.

Window globals removed: applyFilterBar, clearFilterBar, toggleStringFilterInput, showPresetNameInput, savePreset are no longer assigned to window. connectedCallback wires all handlers:

• this.querySelector("form") → submit listener (replaces onsubmit)
• this.querySelector("[data-filter-bar-clear]") → click listener
• this.querySelector("[data-filter-bar-save]") → click listener
• this.querySelector("[data-filter-bar-confirm-save]") → click listener
• this.querySelectorAll("[data-string-modifier-radio]") → change listeners

Python changes in filters.py:

• Remove onsubmit="return applyFilterBar(event)" from form
• Replace onclick="clearFilterBar(...)" → data-filter-bar-clear
• Replace onclick="showPresetNameInput()" → data-filter-bar-save
• Replace onclick="savePreset(...)" → data-filter-bar-confirm-save
• Replace onclick="toggleStringFilterInput(this)" → data-string-modifier-radio (already present)
• Move preset_list_url from data-preset-list-url on #preset-dropdown to a typed prop on <filter-bar>
• Preset dropdown: this.querySelector("[data-preset-dropdown]") (add this attr)

Import: filter-bar.ts imports { readSearchSelect } from ./search-select.js.

globals.d.ts: Remove all entries except fetchWithHtmxTriggers and toast (which remain as globals).

Verification

uv run manage.py gen_element_types   # codegen passes
make ts                              # tsc --noEmit passes
make test                            # unit tests pass
make test-e2e                        # e2e tests pass (after locator updates)
make check                           # full CI gate

Manual visual check each widget after conversion (per issue requirement).