@rcarls/rc-combobox 0.0.0-next-20260921045401

package/CHANGELOG.md

@@ -0,0 +1,212 @@
+# @rcarls/rc-combobox
+
+## 0.0.0-next-20260921045401
+
+### Minor Changes
+
+- 079e025: Standardize component styling contracts for the breaking 0.7 release.
+
+  BREAKING CHANGE: Rename the Markdown editor's `--rme-*` properties to
+  `--rc-markdown-editor-*`, `--rc-app-bar-background` to `--rc-app-bar-bg`,
+  `--rc-textarea-radius` to `--rc-textarea-border-radius`, the transfer-list
+  `--rc-transfer-list-panel-*` properties to `--rc-transfer-list-listbox-*`,
+  `--rc-chip-group-webkit-scrollbar-display` to
+  `--rc-chip-group-scrollbar-display`, and `--rc-text` to `--rc-field-text`.
+  Compatibility aliases are intentionally not provided.
+
+  BREAKING CHANGE: Replace `--rc-select-chip-padding-inline` and
+  `--rc-combobox-chip-padding-inline` with explicit `*-padding-inline-start` and
+  `*-padding-inline-end` tokens. Generated removable chips now reserve the full
+  remove target and its edge offset, so their indicator cannot overlap label text.
+
+  Add canonical app-bar elevation, transfer-list listbox radius, and textarea
+  line-action tokens. Add logical `rc-chip` inline-padding properties so themes
+  can implement Material's icon-aware spacing without overriding authored child
+  styles. Make `rc-field` consume the shared semantic token layer,
+  and place the `rc-chip` and `rc-search-bar` light-DOM structural styles in the
+  `rc-base` cascade layer so normal consumer rules override them.
+
+  Prevent decorative, `aria-hidden` trailing list content from intercepting a
+  whole-row action target, and keep segmented-list item geometry from leaking
+  into nested standard lists.
+
+  Remove unused Material navigation-rail toggle tokens and obsolete list-item
+  theme tokens. Register the segmented-button private theme seam and enforce
+  token ownership, documentation, removed-name, selector-budget, and cascade
+  layer contracts through the component architecture audit.
+
+- 4341311: Add reusable fullscreen dialogs and declarative dialog popup mode to `rc-select` and
+  `rc-combobox`. Dialog selection and creation are staged until Done, while close and Escape
+  discard the draft. Fullscreen surfaces follow the visual viewport under browser zoom and
+  software keyboards, and anchored popups now clamp to the visual viewport.
+- 94dc987: `rc-menu-button`'s, `rc-select`'s, and `rc-combobox`'s popup/listbox now fade
+  in and out through CSS alone, using `@starting-style` and a discrete
+  `display`/`overlay` transition, driven by new `--rc-menu-button-popup-duration`,
+  `--rc-select-listbox-duration`, and `--rc-combobox-listbox-duration`
+  properties. `showPopover()`/`hidePopover()` (via `openPopup()`/`closePopup()`)
+  stay synchronous, and nothing waits on the transition finishing.
+
+  These animate opacity only, not a scale or slide transform: all three
+  position their popup with the shared `AnchorController`, which applies its
+  own viewport-clamping `translate` and reads `getBoundingClientRect()` to
+  compute the next correction. A second, CSS-driven transform on the same
+  element and property would fight that positioning math on every open, not
+  only during an edge case.
+
+  `rc-fab-menu` already had a scale-based entrance for its popup (verified safe
+  here: unlike the general `AnchorController` case, this popup isn't
+  collision-clamped), but no exit animation at all and no directional easing.
+  Both are added: the popup now fades and scales back out on close, and enter
+  uses a decelerating curve while exit uses an accelerating one.
+
+### Patch Changes
+
+- 011f3c6: Keep combobox chips clear of their trailing toggle, reset native selects inside
+  `rc-field`, keep controlled carousel accessibility state synchronized, and align
+  Material chips, menus, lists, disclosures, nested editors, and bottom-sheet
+  motion with their MD3 defaults.
+- 8363cb8: Fix a real user-driven "create new option" selection not dispatching native `input`/`change` on
+  the slotted `<select>` (`focus()`/`blur()` forwarding and `required` mirroring were already
+  correct through inheritance from `rc-select`'s new control-provider support). `aria-required`
+  now reflects on the input trigger.
+- Updated dependencies [50d5610]
+- Updated dependencies [079e025]
+- Updated dependencies [4341311]
+- Updated dependencies [94dc987]
+- Updated dependencies [8a30e96]
+  - @rcarls/rc-common@0.0.0-next-20260921045401
+  - @rcarls/rc-chip-group@0.0.0-next-20260921045401
+  - @rcarls/rc-select@0.0.0-next-20260921045401
+  - @rcarls/rc-listbox@0.0.0-next-20260921045401
+
+## 0.6.0
+
+### Minor Changes
+
+- ffcbf11: Add adaptive chip-group layouts, native-backed filter chips, and shared
+  input-chip rendering. Native-backed chips preserve controlled host state,
+  follow form resets when uncontrolled, and accept native link actions. Groups
+  restore author-owned chip variants when coordination ends. Keep search input
+  chrome inside the search surface and align contextual icon sizes with Material 3.
+
+### Patch Changes
+
+- Updated dependencies [ffcbf11]
+- Updated dependencies [6683eb9]
+- Updated dependencies [ee7ba6c]
+- Updated dependencies [30eb232]
+  - @rcarls/rc-chip-group@0.6.0
+  - @rcarls/rc-select@0.6.0
+  - @rcarls/rc-common@0.6.0
+  - @rcarls/rc-listbox@0.6.0
+
+## 0.5.0
+
+### Patch Changes
+
+- Updated dependencies [4ae2ef0]
+- Updated dependencies [689340c]
+  - @rcarls/rc-common@0.5.0
+  - @rcarls/rc-listbox@0.5.0
+  - @rcarls/rc-select@0.5.0
+
+## 0.4.2
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.2
+- @rcarls/rc-listbox@0.4.2
+- @rcarls/rc-select@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.4.1
+- @rcarls/rc-listbox@0.4.1
+- @rcarls/rc-select@0.4.1
+
+## 0.4.0
+
+### Patch Changes
+
+- acc913e: Document the `chips` and `listbox` CSS parts, the `filter-strategy` attribute, and the
+  `--rc-combobox-chip-gap`, `--rc-combobox-chip-border`, `--rc-combobox-listbox-border`, and
+  `--rc-combobox-shadow` custom properties in the generated API reference. Also correct the
+  `allow-create` attribute tag to non-bracket form (it has a real settable `allowCreate`
+  property) and fix stale README/docs prose that claimed a `default-value` HTML attribute exists
+  for the inherited `defaultValue` property, which has no attribute mapping.
+- fa9bed0: Fix the toggle button's size custom property so it is `--rc-combobox-toggle-size`, matching
+  every other `--rc-combobox-*` token in the package. It previously reused rc-select's
+  `--rc-select-toggle-indicator-size`, so setting `--rc-combobox-toggle-size` on `<rc-combobox>`
+  silently did nothing.
+- Updated dependencies [e57277f]
+- Updated dependencies [8944083]
+- Updated dependencies [ccca8e2]
+- Updated dependencies [9c3bc6f]
+- Updated dependencies [037b1b3]
+  - @rcarls/rc-common@0.4.0
+  - @rcarls/rc-listbox@0.4.0
+  - @rcarls/rc-select@0.4.0
+
+## 0.3.2
+
+### Patch Changes
+
+- Updated dependencies [88b4086]
+  - @rcarls/rc-common@0.3.2
+  - @rcarls/rc-select@0.3.2
+  - @rcarls/rc-listbox@0.3.2
+
+## 0.3.1
+
+### Patch Changes
+
+- @rcarls/rc-common@0.3.1
+- @rcarls/rc-listbox@0.3.1
+- @rcarls/rc-select@0.3.1
+
+## 0.3.0
+
+### Added
+
+- Add typed action option support for `allow-create` flows.
+
+### Changed
+
+- Change the required native `<select>` child to the default slot.
+- Normalize embedded listbox option styling around `--rc-listbox-*` custom properties.
+- Replace the text chevron with an inline SVG chevron.
+- Update package metadata, README intro, and docs links.
+
+### Fixed
+
+- Reflect `allowCreate` as the `allow-create` attribute instead of `allowcreate`.
+
+### Migration
+
+- Rename the `allowcreate` attribute to `allow-create`.
+
+```diff
+- <rc-combobox allowcreate>
++ <rc-combobox allow-create>
+```
+
+- Remove `slot="select"` from the native `<select>` child.
+
+```diff
+- <rc-combobox><select slot="select" name="tags">...</select></rc-combobox>
++ <rc-combobox><select name="tags">...</select></rc-combobox>
+```
+
+### Dependencies
+
+- Sync internal dependencies to 0.3.0.
+
+## 0.2.0
+
+### Patch Changes
+
+- @rcarls/rc-common@0.2.0
+- @rcarls/rc-listbox@0.2.0
+- @rcarls/rc-select@0.2.0

package/README.md

@@ -0,0 +1,212 @@
+# `@rcarls/rc-combobox`
+
+Editable combobox with filtering and optional allow-create behavior, configured
+from native option data and following the
+[WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+
+Docs:
+[https://richardcarls.github.io/rc-webcomponents/components/rc-combobox](https://richardcarls.github.io/rc-webcomponents/components/rc-combobox).
+
+Extends `rc-select` with a text input and wraps a native slotted `<select>`.
+
+## Installation
+
+PowerShell:
+
+```powershell
+yarn.cmd add @rcarls/rc-combobox
+```
+
+Bash/zsh:
+
+```bash
+yarn add @rcarls/rc-combobox
+```
+
+## Import
+
+```ts
+import '@rcarls/rc-combobox/define';
+```
+
+## Basic Usage
+
+```html
+<label>
+  Fruit
+  <rc-combobox placeholder="Search fruit">
+    <select name="fruit">
+      <option value="apple">Apple</option>
+      <option value="banana">Banana</option>
+      <option value="cherry">Cherry</option>
+    </select>
+  </rc-combobox>
+</label>
+```
+
+## Allow Create
+
+Add `allow-create` to show a **"Create 'X'"** option when the typed text has no exact match.
+Selecting it inserts the new option into the native `<select>`, selects it, and
+fires `rc-combobox-create`.
+
+```html
+<rc-combobox allow-create placeholder="Add tag">
+  <select name="tags" multiple></select>
+</rc-combobox>
+```
+
+## Dialog Popup
+
+Use `popup-mode="dialog"` when an anchored option list would leave too little usable
+viewport, such as on a phone with the software keyboard open. The trigger opens a native modal
+dialog with the current chips, a dedicated search input, the option list, and a Done action.
+Selections and newly created values are staged while the dialog is open. Done commits them in
+one selection change; the leading close action, Escape, and imperative close discard them.
+
+```html
+<rc-combobox popup-mode="dialog" allow-create placeholder="Add categories">
+  <select name="categories" multiple>
+    <option value="quick">Quick meal</option>
+    <option value="vegetarian">Vegetarian</option>
+  </select>
+</rc-combobox>
+```
+
+Choose the mode declaratively from your application’s viewport policy. The component latches
+the mode for an open interaction, so changing `popupMode` does not replace an active popup.
+
+### Validation
+
+`rc-combobox-create` is cancelable. Call `event.preventDefault()` to block insertion when the
+text fails validation. In dialog mode the event is deferred until Done, before the selection
+commit. The default behavior (insert + select) runs otherwise.
+
+```js
+combobox.addEventListener('rc-combobox-create', (event) => {
+  if (event.detail.text.trim().length < 2) {
+    event.preventDefault();
+    showError('Tag must be at least 2 characters.');
+  }
+});
+```
+
+### React: managing options as state
+
+Call `preventDefault()` and add the new item to your React state instead. After React renders
+the new `<option>`, set `el.value` in a `useEffect` to select it:
+
+```tsx
+const [options, setOptions] = useState(initialOptions);
+const pendingValue = useRef<string | null>(null);
+const comboRef = useRef<HTMLElement & { value: string | string[] | undefined }>(null);
+
+useEffect(() => {
+  const el = comboRef.current;
+  if (!el) return;
+  const handleCreate = (e: Event) => {
+    e.preventDefault();
+    const { text } = (e as CustomEvent<{ text: string }>).detail;
+    const value = text.trim().toLowerCase().replace(/\s+/g, '-');
+    setOptions((prev) => [...prev, { value, label: text.trim() }]);
+    pendingValue.current = value;
+  };
+  el.addEventListener('rc-combobox-create', handleCreate);
+  return () => el.removeEventListener('rc-combobox-create', handleCreate);
+}, []);
+
+// Runs after React renders the new <option>; component has already processed slotchange.
+useEffect(() => {
+  const value = pendingValue.current;
+  if (!value || !comboRef.current) return;
+  pendingValue.current = null;
+  const el = comboRef.current;
+  const current = Array.isArray(el.value) ? el.value : el.value ? [el.value] : [];
+  if (!current.includes(value)) {
+    el.value = [...current, value];
+  }
+}, [options]);
+```
+
+### Form usage: ephemeral options until committed
+
+By default, created options are added to the native `<select>` and appear in `FormData` on submit
+but are discarded on page reload. To persist them on submit, track them alongside the option list:
+
+```js
+const pending = new Set();
+
+combobox.addEventListener('rc-combobox-create', (event) => {
+  pending.add(event.detail.text.trim());
+  // Default runs, so the option is inserted and selected.
+});
+
+form.addEventListener('submit', (event) => {
+  event.preventDefault();
+  const data = new FormData(form);
+  const selected = data.getAll('tags');
+  const newValues = selected.filter((v) => pending.has(v));
+  // Save newValues to the server; they become persisted options next load.
+});
+```
+
+## Controlled vs Uncontrolled
+
+**Uncontrolled (default):** set `<option selected>` or the `defaultValue` property for the
+initial value; the component owns selection thereafter. Listen to `rc-select-change` to observe
+changes. `defaultValue` accepts `string | string[]` and has no HTML attribute form; set it as a
+JS property.
+
+**Controlled:** write `el.value` (the property) to drive selection programmatically. Writes are
+silent, so no `rc-select-change` is dispatched. Update `el.value` in response to `rc-select-change`
+to keep external state in sync.
+
+```js
+combobox.value = 'banana'; // single
+combobox.value = ['apple', 'cherry']; // multiple
+```
+
+For `allow-create`, the same split applies to options:
+
+- **Uncontrolled options:** let the default behavior add the new `<option>` to
+  the native `<select>`.
+- **Controlled options:** call `event.preventDefault()` on
+  `rc-combobox-create` and manage `<option>` elements yourself (for example, in
+  React state), then set `el.value` to include the new value.
+
+## API
+
+| Property         | Type                                 | Description                                                                |
+| ---------------- | ------------------------------------ | -------------------------------------------------------------------------- |
+| `allowCreate`    | `boolean`                            | Shows a create option for unmatched input.                                 |
+| `filterStrategy` | `'prefix' \| 'contains' \| function` | Controls option filtering.                                                 |
+| `popupMode`      | `'popover' \| 'dialog'`              | Chooses an anchored popup or modal dialog. Defaults to `'popover'`.        |
+| `open`           | `boolean`                            | Inherited from `rc-select`; reflects whether the popup is open.            |
+| `multiple`       | `boolean`                            | Inherited from `rc-select`; enables multiple selection and chip rendering. |
+| `disabled`       | `boolean`                            | Inherited from `rc-select`; disables the input and popup trigger.          |
+| `placeholder`    | `string`                             | Inherited from `rc-select`; input placeholder when no value is selected.   |
+| `display`        | `'auto' \| 'chips' \| 'compact'`     | Inherited from `rc-select`; controls multiple-value presentation.          |
+| `value`          | `string \| string[]`                 | Inherited committed selection. Host writes are silent.                     |
+| `defaultValue`   | `string \| string[] \| undefined`    | Inherited JS-only initial value for uncontrolled usage.                    |
+| `options`        | `ListboxOption[] \| undefined`       | Inherited JS-only option-data override.                                    |
+| `selectedValues` | `string[]`                           | Inherited read-only snapshot of selected values.                           |
+
+The inherited `openPopup()` and `closePopup()` methods control the popup
+imperatively. Like other host-driven writes, these calls do not dispatch a
+selection-change event.
+
+## Events
+
+| Event                | Detail                          | Description                                             |
+| -------------------- | ------------------------------- | ------------------------------------------------------- |
+| `rc-combobox-create` | `{ text: string }`              | Cancelable event fired before a new option is inserted. |
+| `rc-select-change`   | `{ value: string \| string[] }` | Inherited selection-change event.                       |
+| `rc-select-open`     | none                            | Inherited event fired when the popup opens.             |
+| `rc-select-close`    | none                            | Inherited event fired when the popup closes.            |
+
+## Accessibility
+
+- Input uses `role="combobox"` with `aria-autocomplete="list"`.
+- Dialog mode exposes a dialog-valued combobox trigger and moves filtering into the modal.
+- Popup navigation uses `aria-activedescendant`.
+- The slotted native `<select>` remains the form value source.