@rcarls/rc-listbox 0.2.0 → 0.3.0

package/dist/types/packages/rc-listbox/src/rc-listbox.d.ts

@@ -1,43 +1,67 @@
 import { LitElement } from 'lit';
-export interface ListboxOption {
-    value: string;
-    label: string;
-    disabled?: boolean;
+import { ActiveDescendantController, ItemsCollectionController, ItemsCollectionActionOption, ItemsCollectionOption, ItemsCollectionSelectableOption, ItemsCollectionFilterStrategy } from '@rcarls/rc-common';
+declare global {
+    interface HTMLElementTagNameMap {
+        'rc-listbox': RCListbox;
+    }
 }
+/** Option shape accepted by `rc-listbox`. */
+export type ListboxOption = ItemsCollectionOption;
+export type ListboxSelectableOption = ItemsCollectionSelectableOption;
+export type ListboxActionOption<Action extends string = string> = ItemsCollectionActionOption & {
+    action: Action;
+};
 /**
- * Determines how `filterOptions()` matches option labels against the query string.
+ * Listbox that keeps option DOM in light DOM for aria-activedescendant navigation,
+ * following the WAI-ARIA Listbox pattern.
  *
- * - `'prefix'` — label must start with the query (default, matches native `<select>` type-ahead).
- * - `'contains'` — label must contain the query anywhere.
- * - `function` — custom predicate; receives lowercased label and query, return `true` to show the option.
+ * - `'prefix'`: label must start with the query (default, matches native `<select>` type-ahead).
+ * - `'contains'`:  label must contain the query anywhere.
+ * - `function`:  custom predicate; receives lowercased label and query, return `true` to show the option.
  */
-export type FilterStrategy = 'prefix' | 'contains' | ((label: string, query: string) => boolean);
-export interface RCListboxChangeEvent {
+export type FilterStrategy = ItemsCollectionFilterStrategy;
+export interface RCListboxSelectChangeEvent {
+    reason: 'select';
     /** Canonical selected value for single mode, or selected values for multi mode. */
     value: string | string[];
     /** Whether the option was selected (false means it was deselected). */
     selected: boolean;
-    /** The option value that was activated. `'__create__'` for the create option. */
+    /** The option value that was activated. */
     optionValue: string;
     /** The option that was activated. */
-    option: ListboxOption | null;
-    /** Selected values as a consistently-array-shaped convenience value. */
+    option: ListboxSelectableOption;
+    /** Selected values array (length=1 for single-selection mode). */
     selectedValues: string[];
-    /** Selected option objects. */
-    selectedOptions: ListboxOption[];
+    /** Selected options. */
+    selectedOptions: ListboxSelectableOption[];
 }
-declare global {
-    interface HTMLElementTagNameMap {
-        'rc-listbox': RCListbox;
-    }
+export interface RCListboxActionChangeEvent<Action extends string = string> {
+    reason: 'action';
+    /** Current canonical selected value; action rows do not mutate selection. */
+    value: string | string[];
+    /** Action activations never select the action row. */
+    selected: false;
+    /** The action option value that was activated. */
+    optionValue: string;
+    /** The action option that was activated. */
+    option: ListboxActionOption<Action>;
+    /** The activated action command. */
+    action: Action;
+    /** Selected values array (length=1 for single-selection mode). */
+    selectedValues: string[];
+    /** Selected options. */
+    selectedOptions: ListboxSelectableOption[];
 }
+export type RCListboxChangeEvent = RCListboxSelectChangeEvent | RCListboxActionChangeEvent;
 /**
- * A headless listbox popup component following the WAI-ARIA listbox pattern.
+ * A WAI-ARIA listbox component that renders a `<ul role="presentation">`
+ * + `<li role="option">` subtree directly into its own light DOM to facilitate
+ * `aria-activedescendant` virtual navigation with IDs inside the same document
+ * or shadow root.
  *
- * Renders into its own light DOM (no shadow root) so that when placed inside
- * another component's shadow root, option element IDs resolve within that same
- * shadow root — enabling `aria-activedescendant` and `aria-controls` IDREFs to
- * work correctly from the parent trigger.
+ * Pre-rendered `<ul>/<li>` children are accepted as a progressive enhancement
+ * baseline. The component reads them on first connect if no `options` setter
+ * has been called.
  *
  * Consumers drive this component via its JS API:
  *   - Set `options` to populate the list
@@ -46,54 +70,78 @@ declare global {
  *   - Call `filterOptions()` to filter visible options
  *   - Read `navigableItems` to feed `ActiveDescendantController`
  *
- * @slot — No slots; options are rendered programmatically from the `options` property.
+ * @see {@link https://richardcarls.github.io/rc-webcomponents/components/rc-listbox rc-listbox docs}
+ * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/listbox/ WAI-ARIA Listbox pattern}
+ *
+ * @slot — Accepts pre-rendered `<ul>` with `<li>` children for progressive enhancement.
+ *
  * @fires rc-listbox-change - Fired when an option is activated (clicked or Enter/Space)
- * @csspart option - Individual option elements
- * @csspart option-checkmark - The checkmark indicator inside each option
- * @csspart option-label - The label text span inside each option
+ *
+ * @csspart option - Individual `<li role="option">` elements
+ * @csspart option-checkmark - The checkmark `<span>` inside each option (when `checkmark` is true)
  * @csspart create-option - The "Create" option when allow-create is active
+ *
+ * @cssprop [--rc-listbox-option-gap=0.25rem] - Gap between the checkmark and option label.
+ * @cssprop [--rc-listbox-option-min-block-size=0px] - Minimum block size (height) of each option row.
+ * @cssprop [--rc-listbox-option-padding-block=2px] - Block-axis padding of each option row.
+ * @cssprop [--rc-listbox-option-padding-inline=4px] - Inline-axis padding of each option row.
+ * @cssprop [--rc-listbox-option-transition] - CSS transition applied to each option row.
+ * @cssprop [--rc-listbox-hover-bg] - Background of a hovered option.
+ * @cssprop [--rc-listbox-hover-color] - Text color of a hovered option.
+ * @cssprop [--rc-listbox-active-bg] - Background of the keyboard-active option.
+ * @cssprop [--rc-listbox-active-color] - Text color of the keyboard-active option.
+ * @cssprop [--rc-listbox-selected-bg] - Background of a selected option.
+ * @cssprop [--rc-listbox-selected-color] - Text color of a selected option.
+ * @cssprop [--rc-listbox-disabled-color] - Text color of a disabled option.
+ * @cssprop [--rc-listbox-disabled-opacity] - Opacity of a disabled option.
  */
 export declare class RCListbox extends LitElement {
-    /** Renders into the host element — no shadow root — so option IDs resolve in the parent shadow root. */
-    createRenderRoot(): this;
+    static styles: import('lit').CSSResult;
+    private static readonly _styledRoots;
+    private static _ensureBaseStyles;
     /** Allow multiple selection. Reflected as `aria-multiselectable` on the host. */
     multiple: boolean;
     /**
      * Render a checkmark indicator inside each option element.
+     *
      * Hidden by default; enable for combobox / select patterns where the
      * consumer's CSS shows it conditionally via `[aria-selected='true']`.
      */
     checkmark: boolean;
     /**
      * How option labels are matched against the active filter text.
+     *
      * Defaults to `'contains'` (substring). Set to `'prefix'` for starts-with
      * matching, or pass a custom predicate for full control.
      * Function values are JS-only; string values may be set via the
      * `filter-strategy` attribute.
      */
     filterStrategy: FilterStrategy;
-    private _options;
-    private _selectedValues;
-    private _filterText;
-    private _createLabel;
     private _defaultValue;
     private _value;
     private _selectionInitialized;
-    private readonly _uid;
-    private readonly _adc;
+    private _filterText;
+    /** Unique ID prefix for all rendered option elements in this instance. */
+    protected readonly _uid: string;
+    /** Manages the `<ul>/<li>` option DOM subtree in the component's light DOM. */
+    protected readonly _itemsCollectionCtrl: ItemsCollectionController;
+    /** Active-descendant controller; tracks keyboard focus within the option list. */
+    protected readonly _activeDescendantCtrl: ActiveDescendantController;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    updated(): void;
+    updated(changed: Map<PropertyKey, unknown>): void;
+    protected render(): import('lit').TemplateResult<1>;
     /** All options regardless of filter state. */
     get allOptions(): readonly ListboxOption[];
     /** Options currently passing the active filter. */
     get filteredOptions(): readonly ListboxOption[];
-    /** Replace the full options list. Triggers a re-render. */
+    /** Replace the full options list. */
     get options(): ListboxOption[];
-    /** Replace the full options list. Triggers a re-render. */
-    set options(opts: ListboxOption[]);
+    /** Replace the full options list. */
+    set options(options: ListboxOption[]);
     /** Append a single option without replacing the list. */
-    appendOption(opt: ListboxOption): void;
+    appendOption(option: ListboxOption): void;
+    /** Current selection as a consistently-array-shaped read-only view. */
     get selectedValues(): string[];
     /** Current selection. Host writes update silently. */
     get value(): string | string[];
@@ -107,40 +155,72 @@ export declare class RCListbox extends LitElement {
     setSelectedValues(values: string[]): void;
     /**
      * Toggle the selected state of the option with `value`.
-     * In single-select mode, toggleing a selected item deselects it (and selects
+     * In single-select mode, toggling a selected item deselects it (and selects
      * the new item). Fires `rc-listbox-change`.
      */
     toggleOption(value: string): void;
+    /** Clears all selected values without firing `rc-listbox-change`. */
     clearSelection(): void;
-    /** Filter visible options to those whose label starts with `text` (case-insensitive). */
+    /** Filter visible options to those whose label matches `text` (case-insensitive). */
     filterOptions(text: string): void;
+    /** Removes any active filter, making all options visible. */
     clearFilter(): void;
     /**
-     * Ordered list of option elements currently navigable: visible and not disabled.
+     * Ordered list of currently navigable option elements (visible and not disabled).
+     *
      * Feed this to `ActiveDescendantController.items` in the parent component.
      * Includes the create option element when one is set.
      */
     get navigableItems(): Element[];
     /**
      * Show or hide the "Create" option at the end of the list.
-     * Pass `null` to hide it, or a non-empty string to show "Create '{label}'".
-     * Fires `rc-listbox-change` with `value: '__create__'` when activated.
+     *
+     * Pass `null` to hide it, or a non-empty string to show `Create "{label}"`.
+     * Fires `rc-listbox-change` with `reason: 'action'` and `action: 'create'`
+     * when activated.
      */
     setCreateOption(label: string | null): void;
-    protected render(): import('lit').TemplateResult<1>;
-    private _onBlur;
-    private _onKeydown;
+    /** Clears the active descendant when focus leaves the listbox. */
+    protected _onBlur: () => void;
     /**
-     * Selects the active-descendant item without toggling (single-select safe).
+     * Handles arrow-key navigation and Enter/Space activation.
+     *
+     * Passes modifier-key combos through to parent handlers unchanged.
+     */
+    protected _onKeydown: (e: KeyboardEvent) => void;
+    /** Routes pointer activations from the controller. */
+    private _handleActivate;
+    /**
+     * Selects the active-descendant item without toggling.
+     *
      * Used by arrow-key navigation so the item under the cursor is always selected.
      */
-    private _selectActiveItem;
-    private _optId;
-    private _isVisible;
-    private _applySelection;
-    private _applySelectionFromSource;
-    private _normalizeValue;
-    private _dispatchChange;
-    private _selectedOptionsFor;
+    protected _selectActiveItem(): void;
+    /**
+     * Returns `true` when `opt` passes the current `_filterText` and `filterStrategy`.
+     */
+    protected _isVisible(option: ListboxOption): boolean;
+    /**
+     * Directly replaces the selection without firing an event.
+     *
+     * Enforces the single-select limit when `multiple` is false.
+     */
+    protected _applySelection(values: string[]): void;
+    /**
+     * Re-applies `_value` or `_defaultValue` after `options` or DOM bootstrap changes.
+     */
+    protected _applySelectionFromSource(): void;
+    /** Coerces a `string | string[]` value to `string[]`. */
+    protected _normalizeValue(value: string | string[]): string[];
+    protected _activeOption(): ListboxOption | null;
+    /** Fires `rc-listbox-change` for a command/action row without mutating selection. */
+    protected _dispatchAction(option: ListboxActionOption): void;
+    /** Fires `rc-listbox-change` with a fully-populated detail object. */
+    protected _dispatchChange(option: ListboxSelectableOption, selected: boolean): void;
+    /**
+     * Maps value strings to their `ListboxOption` objects.
+     * Creates synthetic `{ value, label: value }` entries for values not in the list.
+     */
+    protected _selectedOptionsFor(values: string[]): ListboxSelectableOption[];
 }
 export default RCListbox;

package/package.json

@@ -3,14 +3,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.2.0",
-  "description": "Headless WAI-ARIA listbox web component built with Lit",
+  "version": "0.3.0",
+  "description": "Listbox that keeps option DOM in light DOM for aria-activedescendant navigation.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/richardcarls/rc-webcomponents.git",
     "directory": "packages/rc-listbox"
   },
-  "homepage": "https://github.com/richardcarls/rc-webcomponents#readme",
+  "homepage": "https://richardcarls.github.io/rc-webcomponents/components/rc-listbox",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -37,21 +37,18 @@
   ],
   "customElements": "dist/custom-elements.json",
   "scripts": {
-    "dev": "vite",
     "build": "tsc && vite build && cem analyze",
     "cem:analyze": "cem analyze",
     "preview": "vite preview",
-    "test:browser": "vitest",
-    "test:browser:chrome": "vitest --project=chromium",
-    "test:browser:firefox": "vitest --project=firefox",
-    "yalc:publish": "yalc publish --push"
+    "test:browser": "vitest --run",
+    "test:browser:chrome": "vitest --run --project=chromium",
+    "test:browser:firefox": "vitest --run --project=firefox"
   },
   "dependencies": {
-    "@rcarls/rc-common": "workspace:^"
+    "@rcarls/rc-common": "workspace:*"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "0.11.0",
-    "@guanghechen/rollup-plugin-copy": "^6.0.9",
     "@vitest/browser-playwright": "4.1.5",
     "lit": "^3.0.0",
     "playwright": "^1.56.0",

package/dist/demo.css

@@ -1,85 +0,0 @@
-*, *::before, *::after {
-  box-sizing: border-box;
-}
-
-:root {
-  color-scheme: light dark;
-  --rc-accent: Highlight; /* Chrome doesn't support AccentColor on the open web */
-}
-
-@supports (color: AccentColor) {
-  :root {
-    --rc-accent: AccentColor;
-  }
-}
-
-[data-theme="light"] { color-scheme: light; }
-[data-theme="dark"]  { color-scheme: dark;  }
-
-[data-theme="solarized-light"] {
-  color-scheme: light;
-  --rc-surface: #fdf6e3;
-  --rc-text:    #657b83;
-  --rc-border:  1px solid #93a1a1;
-  --rc-shadow:  0 2px 8px rgba(0, 0, 0, .12);
-}
-
-[data-theme="solarized-dark"] {
-  color-scheme: dark;
-  --rc-surface: #002b36;
-  --rc-text:    #839496;
-  --rc-border:  1px solid #586e75;
-  --rc-shadow:  0 2px 8px rgba(0, 0, 0, .3);
-}
-
-body {
-  font-family: system-ui, sans-serif;
-  margin: 0;
-}
-
-.demo-page {
-  max-width: 60rem;
-  margin: 0 auto;
-  padding: 2rem 1.5rem;
-}
-
-.demo-controls {
-  display: flex;
-  align-items: center;
-  gap: 1rem;
-  margin-bottom: 2rem;
-  padding-bottom: 1rem;
-  border-bottom: 1px solid ButtonBorder;
-}
-
-.demo-controls .demo-title {
-  flex: 1;
-}
-
-.demo-controls h1 {
-  margin: 0 0 0.15rem;
-  font-size: 1.5rem;
-}
-
-.demo-controls a {
-  font-size: 0.8rem;
-}
-
-.demo-section {
-  margin-bottom: 2rem;
-}
-
-.demo-section h2 {
-  margin: 0 0 0.5rem;
-}
-
-.theme-picker {
-  padding: 0.35em 0.75em;
-  font-family: inherit;
-  font-size: 0.8rem;
-  cursor: pointer;
-  border: 1px solid ButtonBorder;
-  border-radius: 4px;
-  background: Canvas;
-  color: CanvasText;
-}

package/dist/demo.js

@@ -1,40 +0,0 @@
-const THEMES = ['', 'light', 'dark', 'solarized-light', 'solarized-dark'];
-const LABELS = ['Auto', 'Light', 'Dark', 'Solarized ☀', 'Solarized ☾'];
-
-const stored = localStorage.getItem('rc-demo-theme') ?? '';
-applyTheme(stored);
-
-function applyTheme(theme) {
-  if (theme) {
-    document.documentElement.dataset.theme = theme;
-  } else {
-    delete document.documentElement.dataset.theme;
-  }
-}
-
-function currentIndex() {
-  const current = document.documentElement.dataset.theme ?? '';
-  const idx = THEMES.indexOf(current);
-  return idx === -1 ? 0 : idx;
-}
-
-function updateButtons() {
-  const label = LABELS[currentIndex()];
-  document.querySelectorAll('.theme-picker').forEach((btn) => {
-    btn.textContent = label;
-  });
-}
-
-window.cycleTheme = function () {
-  const next = THEMES[(currentIndex() + 1) % THEMES.length];
-  applyTheme(next);
-  localStorage.setItem('rc-demo-theme', next);
-  updateButtons();
-};
-
-document.addEventListener('DOMContentLoaded', () => {
-  updateButtons();
-  document.querySelectorAll('.theme-picker').forEach((btn) => {
-    btn.addEventListener('click', window.cycleTheme);
-  });
-});