PSA/ee/docs/plans/2026-02-04-ui-kit-showcase-extension/SCRATCHPAD.md

SCRATCHPAD: UI Kit Showcase Extension

Key Discoveries

Extension Structure (from softwareone-ext)

• Extensions live in ee/extensions/ directory
• Sample extensions go in ee/extensions/samples/
• Manifest requires: name, publisher, version, runtime: "wasm-js@1", ui config
• UI iframe entry point: ui/index.html
• Build output goes to ui/dist/iframe/main.js

UI Kit Location

• Package: packages/ui-kit/
• Import as: @alga/ui-kit (via vite alias)
• Vite alias required: '@alga/ui-kit': path.resolve(__dirname, '..', '..', 'server', 'packages', 'ui-kit', 'src')

Theme Variable Inconsistency (CRITICAL)

UI Kit uses --alga-* variables, but main app uses --color-* variables:

UI Kit Variable	Main App Equivalent
--alga-bg	--color-background
--alga-fg	--color-text-900
--alga-border	--color-border-200
--alga-primary	--color-primary-500
--alga-muted	--color-border-100
--alga-muted-fg	--color-text-500
--alga-danger	--color-accent-red or similar
--alga-warning	--color-accent-orange
--alga-success	--color-accent-green
--alga-radius	Hardcoded in app (typically 6-8px)

Solution: Create a ThemeBridge component that injects <style> with CSS variable mappings.

Components to Showcase (22 total)

Core (8):

• Button (variants: primary/secondary/ghost/danger, sizes: sm/md/lg)
• Input
• CustomSelect
• Card
• Alert (tones: info/success/warning/danger)
• Text (as, size, weight)
• Stack (direction, gap, align, justify)
• Badge (tones: default/success/warning/danger/info)

Data (1):

• DataTable (columns, pagination, sorting, responsiveColumns, custom render)

Dialogs (2):

• Dialog
• ConfirmDialog (danger variant)

Feedback (5):

• Spinner (sizes)
• LoadingIndicator
• Tooltip (positions: top/bottom/left/right)
• Progress (variants: default/striped/animated, sizes, indeterminate)
• Skeleton, SkeletonText, SkeletonCircle, SkeletonRectangle

Form (5):

• Checkbox (indeterminate, label, disabled)
• Switch (sizes: sm/md/lg, disabled)
• TextArea (rows, resize)
• Label (required, sizes)
• SearchInput (debounce, loading, showClear, sizes)

Navigation (3):

• Tabs (variants: default/pills/underline, disabled tabs)
• Drawer (positions: left/right/top/bottom, sizes: sm/md/lg/full)
• DropdownMenu (items, dividers, disabled, danger, align)

Vite Config Notes (from softwareone-ext)

// Key settings for iframe bundle
build: {
  lib: {
    entry: 'src/iframe/main.tsx',
    formats: ['es'],
    fileName: () => 'main.js',
  },
  rollupOptions: {
    external: [], // Bundle everything including React
    output: {
      inlineDynamicImports: true,
    },
  },
  outDir: 'ui/dist/iframe',
}

// React deduplication
resolve: {
  alias: {
    'react': path.resolve(__dirname, 'node_modules/react'),
    'react-dom': path.resolve(__dirname, 'node_modules/react-dom'),
    '@alga/ui-kit': path.resolve(__dirname, '..', '..', 'server', 'packages', 'ui-kit', 'src'),
  },
  dedupe: ['react', 'react-dom'],
}

Package.json Dependencies

{
  "dependencies": {
    "react": "^19.2.3",
    "react-dom": "^19.2.3",
    "@alga/ui-kit": "file:../../server/packages/ui-kit"
  }
}

Decisions

1. Extension location: ee/extensions/samples/ui-kit-showcase/ (alongside other samples)
2. Theme bridge approach: Inject CSS variables via <style> element in ThemeBridge component
3. Navigation: Use UI Kit's own Tabs component for category navigation
4. No routing needed: Single-page demo, tabs handle navigation
5. Demo data: Inline mock data for DataTable, no API calls needed

Commands

# Create extension directory
mkdir -p ee/extensions/samples/ui-kit-showcase/{src/{iframe,components,demos},ui}

# Install dependencies
cd ee/extensions/samples/ui-kit-showcase && npm install

# Build extension
npm run build

# Check build output
ls -la ui/dist/iframe/

Open Items

• Verify exact color mappings from globals.css
• Test theme bridge in both light and dark modes
• Confirm iframe sandbox doesn't block injected styles

Updates

• F001: Added extension manifest at ee/extensions/samples/ui-kit-showcase/manifest.json with iframe UI entry and app menu hook for UI Kit Showcase.

• F002: Added ee/extensions/samples/ui-kit-showcase/package.json with React + @alga/ui-kit dependencies and build script.

• F003: Added ee/extensions/samples/ui-kit-showcase/vite.iframe.config.ts to bundle iframe UI into ui/dist/iframe/main.js with @alga/ui-kit aliasing.

• F004: Added ee/extensions/samples/ui-kit-showcase/ui/index.html with root div and iframe bundle script.

• F005: Added ee/extensions/samples/ui-kit-showcase/tsconfig.json with React JSX and module settings for the iframe app.

• F006: Added ee/extensions/samples/ui-kit-showcase/src/components/ThemeBridge.tsx to inject CSS variable bridge for --alga-* tokens.

• F007: ThemeBridge defines light-mode --color-* defaults and maps them to --alga-* tokens.

• F008: ThemeBridge includes dark-mode overrides via data-alga-theme="dark" selector.

• F009: Implemented theme toggle button in src/iframe/App.tsx to switch light/dark modes.

• F010: Header layout with title and theme toggle in App.

• F011: Tabbed navigation for categories uses UI kit Tabs in App.

• F012: Content area renders category demo panels via Tabs content.

• F013: DemoSection wrapper provides title, description, and demo container styling.

• F014: Button demo shows primary/secondary/ghost/danger variants in .

• F015: Button demo includes sm/md/lg size examples.

• F016: Button demo includes disabled state example.

• F017: Input demo renders basic input with placeholder.

• F018: Input demo renders disabled input state.

• F019: CustomSelect demo renders options with placeholder and selection state.

• F020: CustomSelect demo includes disabled state example.

• F021: Card demo shows card container with content and actions.

• F022: Alert demo shows info/success/warning/danger tones.

• F023: Text demo shows size and weight variants.

• F024: Text demo renders as h1/h2/p/span elements.

• F025: Stack demo shows row and column layouts.

• F026: Stack demo shows gap and alignment options.

• F027: Badge demo shows default/info/success/warning/danger tones.

• F028: DataTable demo enables sortable columns.

• F029: DataTable demo enables pagination and page size selection.

• F030: DataTable demo enables responsive column hiding.

• F031: DataTable demo renders status cells with Badge.

• F032: Dialog demo opens/closes with trigger button.

• F033: Dialog demo includes title and footer actions.

• F034: ConfirmDialog demo shows confirm/cancel actions.

• F035: ConfirmDialog demo includes danger variant.

• F036: Spinner demo renders multiple sizes.

• F037: LoadingIndicator demo shows spinner with text.

• F038: Tooltip demo shows top/bottom/left/right positions.

• F039: Progress demo shows 0/50/100 values.

• F040: Progress demo includes default, striped overlay, and animated examples.

• F041: Progress demo includes sm/md/lg size examples.

• F042: Progress demo includes indeterminate mode example.

• F043: Skeleton demo includes base skeleton block.

• F044: Skeleton demo includes SkeletonText lines.

• F045: Skeleton demo includes SkeletonCircle example.

• F046: Skeleton demo includes SkeletonRectangle example.

• F047: Checkbox demo includes checked/unchecked states.

• F048: Checkbox demo includes indeterminate example.

• F049: Checkbox demo includes labeled checkbox.

• F050: Checkbox demo includes disabled checkbox.

• F051: Switch demo includes on/off states.

• F052: Switch demo includes sm/md/lg sizes.

• F053: Switch demo includes disabled state.

• F054: TextArea demo includes basic textarea.

• F055: TextArea demo includes multiple row counts.

• F056: TextArea demo includes resize options.

• F057: TextArea demo includes disabled state.

• F058: Label demo includes basic label.

• F059: Label demo includes required indicator.

• F060: Label demo includes size variants.

• F061: SearchInput demo includes basic search input.

• F062: SearchInput demo includes clear button behavior.

• F063: SearchInput demo includes loading state example.

• F064: SearchInput demo includes size variants.

• F065: SearchInput demo includes debounce example.

• F066: Tabs demo includes default variant.

• F067: Tabs demo includes pills variant.

• F068: Tabs demo includes underline variant.

• F069: Tabs demo includes disabled tab example.

• F070: Drawer demo supports right position.

• F071: Drawer demo supports left position.

• F072: Drawer demo supports bottom position.

• F073: Drawer demo supports sm/md/lg/full sizes.

• F074: Drawer demo renders title and content.

• F075: DropdownMenu demo includes basic menu items.

• F076: DropdownMenu demo includes divider items.

• F077: DropdownMenu demo includes disabled items.

• F078: DropdownMenu demo includes danger items.

• F079: DropdownMenu demo shows left/right alignment.

• T001: Added vitest setup and scaffolding tests covering manifest required fields.

• T002: Scaffold tests assert iframe UI entry in manifest.

• T003: Scaffold tests assert appMenu hook presence.

• T004: Scaffold tests assert ui-kit dependency in package.json.

• T005: Scaffold tests assert react and react-dom dependencies.

• T006: Scaffold tests assert iframe bundle output path in vite config.

• T007: Scaffold tests assert ui-kit alias in vite config.

• T008: Scaffold tests assert index.html root div and bundle script.

• T009: Theme bridge tests assert alga background mapping.

• T010: Theme bridge tests assert alga foreground mapping.

• T011: Theme bridge tests assert alga primary mapping.

• T012: Theme bridge tests assert alga border mapping.

• T013: Theme bridge tests assert alga danger mapping.

• T014: Theme bridge tests assert dark mode token overrides.

• T015: Theme toggle test asserts mode switch on click.

• T016: Theme change test asserts document theme attribute updates.

• T017: Layout tests assert header title text.

• T018: Layout tests assert theme toggle visibility.

• T019: Layout tests assert six category tabs.

• T020: Layout tests assert tab switching updates content.

• T021: Layout tests assert default tab is Core.

• T022: DemoSection test asserts title render.

• T023: DemoSection test asserts description render.

• T024: DemoSection test asserts children render.

• T025: Button tests assert primary background mapping.

• T026: Button tests assert secondary background mapping.

• T027: Button tests assert ghost button transparency.

• T028: Button tests assert danger background mapping.

• T029: Button tests compare small vs medium sizes.

• T030: Button tests compare large vs medium sizes.

• T031: Button tests assert disabled opacity and disabled attribute.

• T032: Input tests assert text entry.

• T033: Input tests assert placeholder visibility.

• T034: Input tests assert disabled input cannot focus.

• T035: CustomSelect tests assert dropdown opens.

• T036: CustomSelect tests assert selected option shows.

• T037: CustomSelect tests assert disabled select doesn't open.

• T038: Card tests assert border and padding.

• T039: Card tests assert content rendering.

• T040: Alert tests assert info styling.

• T041: Alert tests assert success styling.

• T042: Alert tests assert warning styling.

• T043: Alert tests assert danger styling.

• T044: Text tests assert size changes.

• T045: Text tests assert weight changes.

• T046: Text tests assert element rendering.

• T047: Stack tests assert row direction.

• T048: Stack tests assert column direction.

• T049: Stack tests assert gap spacing.

• T050: Badge tests assert default tone styling.

• T051: Badge tests assert success tone styling.

• T052: Badge tests assert warning/danger styling.

• T053: DataTable tests assert headers render.

• T054: DataTable tests assert sortable header changes order.

• T055: DataTable tests assert pagination controls visible.

• T056: DataTable tests assert page size selector updates row count.

• T057: DataTable tests assert responsive column hiding when narrow.

• T058: DataTable tests assert badge render in custom cell.

• T059: Dialog tests assert open on trigger.

• T060: Dialog tests assert close on cancel.

• T061: Dialog tests assert title render.

• T062: ConfirmDialog tests assert confirm action.

• T063: ConfirmDialog tests assert cancel action.

• T064: ConfirmDialog tests assert danger button styling.

• T065: Spinner tests assert animation present.

• T066: Spinner tests assert size variants.

• T067: LoadingIndicator tests assert text renders.

• T068: Tooltip tests assert hover shows tooltip.

• T069: Tooltip tests assert multiple positions render.

• T070: Progress tests assert fill width for values.

• T071: Progress tests assert striped overlay style.

• T072: Progress tests assert animated transition.

• T073: Progress tests assert size height changes.

• T074: Progress tests assert indeterminate animation.

• T075: Skeleton tests assert pulse animation.

• T076: Skeleton tests assert multiple text lines.

• T077: Skeleton tests assert circular shape.

• T078: Skeleton tests assert rectangle dimensions.

• T079: Checkbox tests assert toggling state.

• T080: Checkbox tests assert indeterminate property.

• T081: Checkbox tests assert label click toggles.

• T082: Checkbox tests assert disabled checkbox doesn't toggle.

• T083: Switch tests assert toggle behavior.

• T084: Switch tests assert size variants.

• T085: Switch tests assert disabled switch doesn't toggle.

• T086: TextArea tests assert multi-line input.

• T087: TextArea tests assert rows prop.

• T088: TextArea tests assert resize styles.

• T089: TextArea tests assert disabled behavior.

• T090: Label tests assert label text rendering.

• T091: Label tests assert required indicator.

• T092: Label tests assert size variants.

• T093: SearchInput tests assert search icon.

• T094: SearchInput tests assert clear button appears.

• T095: SearchInput tests assert clear button clears value.

• T096: SearchInput tests assert loading spinner state.

• T097: SearchInput tests assert size variants.

• T098: SearchInput tests assert debounce behavior.

• T099: Tabs tests assert default indicator.

• T100: Tabs tests assert pills variant style.

• T101: Tabs tests assert underline variant style.

• T102: Tabs tests assert disabled tab state.

• T103: Tabs tests assert content changes on selection.

• T104: Drawer tests assert right position.

• T105: Drawer tests assert left position.

• T106: Drawer tests assert bottom position.

• T107: Drawer tests assert size changes.

• T108: Drawer tests assert title renders.

• T109: Drawer tests assert close button closes drawer.

• T110: Drawer tests assert escape closes drawer.

• T111: Drawer tests assert overlay click closes drawer.

• T112: DropdownMenu tests assert menu opens.

• T113: DropdownMenu tests assert item clicks update state.

• T114: DropdownMenu tests assert divider elements present.

• T115: DropdownMenu tests assert disabled items not clickable.

• T116: DropdownMenu tests assert danger item styling.

• T117: DropdownMenu tests assert right alignment.

• T118: DropdownMenu tests assert menu closes on item click.

• T119: DropdownMenu tests assert menu closes on outside click.

• F080: Fixed ui-kit path aliases and dependency, then ran npm run build successfully for iframe bundle.

• F081: Added iframe integration checks and ensured App renders all component demos without runtime errors.

Test Stabilization Updates (2026-02-04)

• Fixed React hook errors in Vitest by aliasing react/react-dom to extension-local node_modules, enabling preserveSymlinks, and installing @radix-ui/react-select locally.
• Added JSDOM polyfills for Radix Select (hasPointerCapture, setPointerCapture, releasePointerCapture, scrollIntoView).
• Updated CustomSelect tests to use role-based queries (combobox, option) and avoid duplicate text matches.
• Adjusted layout/integration tests to target tab roles and navigate categories before asserting component titles.
• Tightened DataTable, Progress, Spinner, and Skeleton test queries to reflect actual DOM structure and inline styles.
• Full vitest --run completes with passing assertions but the process can linger (open handles); per-file runs exit cleanly.

Commands

• npx vitest -c vitest.config.ts --run test/core-demos.test.tsx
• npx vitest -c vitest.config.ts --run test/data-dialog-feedback.test.tsx
• npx vitest -c vitest.config.ts --run (times out after completion; see note above)
• Marked T120-T124 as implemented after build/integration coverage was stabilized.