@rcarls/rc-listbox 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,100 @@
+# @rcarls/rc-listbox
+
+## 0.0.0-next-20260921045401
+
+### Patch Changes
+
+- Updated dependencies [50d5610]
+- Updated dependencies [4341311]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Patch Changes
+
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+  - @rcarls/rc-common@0.6.0
+
+## 0.5.0
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- 8944083: Document the `multiple`, `checkmark`, and `filter-strategy` attributes, add
+  real defaults to the eight `--rc-listbox-*` option-styling custom properties
+  that already had one in code but not in the JSDoc, add `@example` blocks to
+  the `options` setter and `appendOption()`, and add the missing `checkmark`,
+  `value`, and `defaultValue` rows to the README's API table.
+- Updated dependencies [e57277f]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [037b1b3]
+  - @rcarls/rc-common@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [88b4086]
+  - @rcarls/rc-common@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.3.1
+
+## 0.3.0
+
+### Breaking
+
+- Render options as `<li role="option">` instead of `<div role="option">`.
+- Remove `part="option-label"`.
+- Move the component-owned structure into shadow DOM.
+
+### Added
+
+- Add typed action option rows and discriminated `rc-listbox-change` details.
+- Add progressive enhancement from a pre-rendered `<ul>` with `<li>` options.
+
+### Changed
+
+- Normalize option styling around `--rc-listbox-*` custom properties.
+- Inject base listbox styles into the component root.
+- Update package metadata, README intro, and docs links.
+
+### Migration
+
+- Update CSS selectors from `div[role="option"]` to `li[role="option"]`.
+- Replace `part="option-label"` styling with selectors for the option text structure now exposed by the component.
+- Query light-DOM option data from the host; do not query the component shadow root for consumer option DOM.
+
+### Dependencies
+
+- Sync internal dependencies to 0.3.0.
+
+## 0.2.0
+
+### Patch Changes
+
+- @rcarls/rc-common@0.2.0

package/README.md

@@ -0,0 +1,96 @@
+# `@rcarls/rc-listbox`
+
+Listbox that keeps option DOM in light DOM for `aria-activedescendant` navigation, following the [WAI-ARIA Listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).
+
+Docs: [https://richardcarls.github.io/rc-webcomponents/components/rc-listbox](https://richardcarls.github.io/rc-webcomponents/components/rc-listbox).
+
+`rc-listbox` is primarily an infrastructure component that can be used
+directly when an application or component controls option data and selection state.
+
+## Installation
+
+PowerShell:
+
+```powershell
+yarn.cmd add @rcarls/rc-listbox
+```
+
+Bash/zsh:
+
+```bash
+yarn add @rcarls/rc-listbox
+```
+
+## Import
+
+```ts
+import '@rcarls/rc-listbox/define';
+```
+
+## Basic Usage
+
+```ts
+const listbox = document.querySelector('rc-listbox');
+
+listbox.options = [
+  { value: 'apple', label: 'Apple' },
+  { value: 'banana', label: 'Banana' },
+  { value: 'cherry', label: 'Cherry', disabled: true },
+];
+
+listbox.setSelectedValues(['apple']);
+```
+
+Options may also represent actions instead of selectable values:
+
+```ts
+listbox.options = [
+  { value: 'none', label: 'None' },
+  { kind: 'action', action: 'clear', value: 'clear', label: 'Clear selection' },
+];
+
+listbox.addEventListener('rc-listbox-change', (event) => {
+  if (event.detail.reason === 'action') {
+    // event.detail.option is narrowed to ListboxActionOption
+    return;
+  }
+
+  // event.detail.option is narrowed to ListboxSelectableOption
+});
+```
+
+## API
+
+| Property / method           | Type                                 | Description                                                  |
+| --------------------------- | ------------------------------------ | ------------------------------------------------------------ |
+| `multiple`                  | `boolean`                            | Enables multi-selection and reflects `aria-multiselectable`. |
+| `checkmark`                 | `boolean`                            | Renders a checkmark indicator inside each option element.    |
+| `filterStrategy`            | `'prefix' \| 'contains' \| function` | Controls how `filterOptions()` matches labels.               |
+| `value`                     | `string \| string[]`                 | Current selection. Host writes update silently.              |
+| `defaultValue`              | `string \| string[] \| undefined`    | Initial uncontrolled selection.                              |
+| `options`                   | `ListboxOption[]`                    | Replaces the rendered option list.                           |
+| `allOptions`                | `readonly ListboxOption[]`           | All configured options.                                      |
+| `filteredOptions`           | `readonly ListboxOption[]`           | Options currently passing the filter.                        |
+| `selectedValues`            | `string[]`                           | Current selected values.                                     |
+| `appendOption(opt)`         | `void`                               | Adds one option.                                             |
+| `setSelectedValues(values)` | `void`                               | Replaces selection without firing an event.                  |
+| `toggleOption(value)`       | `void`                               | Toggles selection and fires `rc-listbox-change`.             |
+| `clearSelection()`          | `void`                               | Clears selected values.                                      |
+| `filterOptions(text)`       | `void`                               | Filters visible options.                                     |
+| `clearFilter()`             | `void`                               | Clears the active filter.                                    |
+| `navigableItems`            | `Element[]`                          | Visible, enabled options for active-descendant navigation.   |
+| `setCreateOption(label)`    | `void`                               | Shows or hides the synthetic create option.                  |
+
+## Events
+
+| Event               | Detail                                                                                  | Description                                      |
+| ------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `rc-listbox-change` | `{ reason: 'select'; value; selected; option } \| { reason: 'action'; action; option }` | Fires when an option or action row is activated. |
+
+## Accessibility
+
+- Host role defaults to `listbox`.
+- Options render with `role="option"` and `aria-selected`.
+- Disabled options render with `aria-disabled="true"` and are omitted from
+  `navigableItems`.
+- Multi-select mode reflects `aria-multiselectable="true"`.