@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/combobox/combobox.svelte

@@ -0,0 +1,376 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts" generics="T extends string = string">
+import { untrack } from 'svelte';
+import { resolveFieldControl } from '../../_internal/field-control.ts';
+import { getFormFieldContext } from '../../_internal/form-field-context.ts';
+import { pushEscapeHandler } from '../../_internal/overlay.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import Popover from '../popover/popover.svelte';
+let { id, value = $bindable(''), name, inputValue = $bindable(''), options, label, placeholder, filter, description, error, disabled, required, maxVisibleOptions = 200, class: className, 'aria-describedby': consumerDescribedBy, } = $props();
+const context = getFormFieldContext();
+const field = $derived(resolveFieldControl({
+    id,
+    generatedId: id,
+    context,
+    hasDescription: !!description,
+    hasError: !!error,
+    localIdNamespace: 'combobox',
+    consumerDescribedBy,
+    required,
+    disabled,
+}));
+const resolvedDisabled = $derived(field.disabled);
+const resolvedRequired = $derived(field.required);
+const describedBy = $derived(field.describedBy);
+const listboxId = $derived(`${id}-listbox`);
+const descriptionId = $derived(field.ownDescriptionId);
+// Stable id for the always-in-DOM error live region when no error is active.
+// Mirrors Select: avoids colliding with a wrapping FormField's error id.
+const stableLocalErrorId = $derived(context?.errorId === `${field.id}-error` ? `${field.id}-combobox-error` : `${field.id}-error`);
+const defaultFilter = (option, query) => {
+    if (!query)
+        return true;
+    const q = query.toLowerCase();
+    return (option.label.toLowerCase().includes(q) ||
+        (option.description?.toLowerCase().includes(q) ?? false));
+};
+const filteredOptions = $derived.by(() => {
+    const fn = filter ?? defaultFilter;
+    const matches = [];
+    for (const option of options) {
+        if (fn(option, inputValue)) {
+            matches.push(option);
+            if (matches.length >= maxVisibleOptions)
+                break;
+        }
+    }
+    return matches;
+});
+let open = $state(false);
+let activeIndex = $state(-1);
+let inputElement = $state(null);
+let hiddenInputElement = $state(null);
+let listboxElement = $state(null);
+let committedLabel = $state('');
+let resetSyncTimeout;
+const initialValue = untrack(() => value);
+const initialInputValue = untrack(() => inputValue);
+// Reset active index whenever the filtered set changes so we don't point
+// at a stale option.
+$effect(() => {
+    void filteredOptions;
+    if (activeIndex >= filteredOptions.length) {
+        activeIndex = filteredOptions.length > 0 ? 0 : -1;
+    }
+});
+// When a value is provided externally, mirror its label in the input box.
+// The current input text is read untracked so typing can keep driving filtering.
+$effect(() => {
+    if (!value) {
+        // Clearing the value (deselect/reset) must also clear the visible text;
+        // otherwise the input keeps showing the previously selected option's label.
+        if (untrack(() => inputValue))
+            inputValue = '';
+        committedLabel = '';
+        return;
+    }
+    const matched = options.find((option) => option.value === value);
+    if (matched) {
+        // `committedLabel` tracks the committed `value`'s label and must stay in
+        // sync whenever a match exists — even when `inputValue` already shows that
+        // label. Gating it behind the `inputValue !== matched.label` check left
+        // `committedLabel` stale (''), so a later Escape restored to empty text.
+        committedLabel = matched.label;
+        if (untrack(() => inputValue) !== matched.label) {
+            inputValue = matched.label;
+        }
+    }
+});
+// Escape ownership.
+//
+// The combobox is the single Escape owner for the whole time it is open. The
+// option Popover is told `closeOnEscape={false}`, so it never registers its
+// own escape-stack handler — otherwise, while options are visible, the
+// Popover's handler would sit on top of the shared LIFO stack and shadow this
+// one. With the Popover opting out, this combobox's handler is the top-most
+// Escape consumer for the entire open session, including the empty-filter gap
+// (`open && filteredOptions.length === 0`) where the Popover is unmounted.
+//
+// That matters most when the combobox is nested inside a Modal/Sheet: the
+// shared escape stack's window listener is capture-phase and invokes ONLY its
+// top handler, so this combobox consumes Escape and `preventDefault()`s it
+// before the parent overlay ever sees the key — Escape dismisses just the
+// combobox, never the enclosing overlay.
+function handleEscape(event = undefined) {
+    const wasOpen = open;
+    open = false;
+    // Restore the committed label whenever the live text drifted from it.
+    if (inputValue !== committedLabel) {
+        inputValue = committedLabel;
+        if (inputElement)
+            inputElement.value = committedLabel;
+    }
+    // Swallow the key if the combobox actually consumed this Escape (it was
+    // open) so the same keystroke doesn't also dismiss an enclosing overlay or
+    // trigger a page-level default.
+    if (wasOpen)
+        event?.preventDefault();
+}
+$effect(() => {
+    if (!open)
+        return;
+    const releaseEscape = pushEscapeHandler(handleEscape);
+    return releaseEscape;
+});
+const activeOptionId = $derived(activeIndex >= 0 && activeIndex < filteredOptions.length
+    ? `${id}-option-${activeIndex}`
+    : undefined);
+function handleInput(event) {
+    const target = event.target;
+    inputValue = target.value;
+    open = true;
+    activeIndex = filteredOptions.length > 0 ? 0 : -1;
+}
+function handleFocus() {
+    if (!resolvedDisabled)
+        open = true;
+}
+function handleBlur(event) {
+    // Defer close so a click on a listbox option can complete first. Use a DOM
+    // containment check rather than a `#${listboxId}` selector so ids with
+    // CSS-special characters (colons, dots, leading digits) don't throw.
+    const next = event.relatedTarget;
+    if (next && listboxElement?.contains(next))
+        return;
+    open = false;
+    // Restore the committed label if the live text drifted from it. Leaving the
+    // field on a stale edit (without selecting an option) would desync the
+    // visible text from the unchanged `value` — the same mismatch Escape fixes.
+    if (inputValue !== committedLabel) {
+        inputValue = committedLabel;
+        if (inputElement)
+            inputElement.value = committedLabel;
+    }
+}
+function selectOption(option) {
+    if (option.disabled)
+        return;
+    value = option.value;
+    inputValue = option.label;
+    committedLabel = option.label;
+    open = false;
+}
+function resetToInitialValue(event) {
+    if (resetSyncTimeout !== undefined)
+        clearTimeout(resetSyncTimeout);
+    resetSyncTimeout = setTimeout(() => {
+        resetSyncTimeout = undefined;
+        if (event.defaultPrevented)
+            return;
+        value = initialValue;
+        const matched = options.find((option) => option.value === initialValue);
+        const nextInputValue = matched?.label ?? initialInputValue;
+        inputValue = nextInputValue;
+        committedLabel = matched?.label ?? '';
+        open = false;
+        activeIndex = -1;
+        if (inputElement)
+            inputElement.value = nextInputValue;
+        if (hiddenInputElement)
+            hiddenInputElement.value = initialValue;
+    }, 0);
+}
+$effect(() => {
+    const input = hiddenInputElement;
+    if (input === null)
+        return;
+    const form = input.form;
+    form?.addEventListener('reset', resetToInitialValue);
+    return () => {
+        form?.removeEventListener('reset', resetToInitialValue);
+        if (resetSyncTimeout !== undefined) {
+            clearTimeout(resetSyncTimeout);
+            resetSyncTimeout = undefined;
+        }
+    };
+});
+$effect(() => {
+    inputElement?.setCustomValidity((resolvedRequired && !value) || inputValue !== committedLabel
+        ? 'Please select an option.'
+        : '');
+});
+function handleKeydown(event) {
+    if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        open = true;
+        if (filteredOptions.length === 0)
+            return;
+        activeIndex = (activeIndex + 1) % filteredOptions.length;
+    }
+    else if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        open = true;
+        if (filteredOptions.length === 0)
+            return;
+        activeIndex = activeIndex <= 0 ? filteredOptions.length - 1 : activeIndex - 1;
+    }
+    else if (event.key === 'Home') {
+        if (!open)
+            return;
+        event.preventDefault();
+        activeIndex = filteredOptions.length > 0 ? 0 : -1;
+    }
+    else if (event.key === 'End') {
+        if (!open)
+            return;
+        event.preventDefault();
+        activeIndex = filteredOptions.length - 1;
+    }
+    else if (event.key === 'Enter' && open) {
+        const option = filteredOptions[activeIndex];
+        if (option) {
+            event.preventDefault();
+            selectOption(option);
+        }
+    }
+    else if (event.key === 'Escape') {
+        // Fallback path. In a real browser the capture-phase escape-stack listener
+        // (installed by the $effect's pushEscapeHandler) runs first and has
+        // already closed + restored + preventDefault'd; `defaultPrevented` is true
+        // here and we bail. This branch only does real work when the stack
+        // listener never ran — SSR/no-window environments where `window` is
+        // absent so `pushEscapeHandler` installed nothing.
+        if (event.defaultPrevented)
+            return;
+        handleEscape(event);
+    }
+}
+</script>
+
+<div class={classNames('cinder-combobox', className)}>
+  {#if label}
+    <label for={id} class="cinder-combobox__label" data-disabled={resolvedDisabled || undefined}>
+      {label}
+      {#if resolvedRequired}
+        <span class="cinder-_required-marker" aria-hidden="true">*</span>
+      {/if}
+    </label>
+  {/if}
+
+  <div class="cinder-combobox__control" data-cinder-open={open || undefined}>
+    <input
+      bind:this={inputElement}
+      {id}
+      type="text"
+      role="combobox"
+      class="cinder-combobox__input"
+      autocomplete="off"
+      autocorrect="off"
+      spellcheck="false"
+      disabled={resolvedDisabled}
+      required={resolvedRequired}
+      {placeholder}
+      value={inputValue}
+      aria-autocomplete="list"
+      aria-expanded={open}
+      aria-controls={listboxId}
+      aria-activedescendant={activeOptionId}
+      aria-invalid={field.ariaInvalid}
+      aria-required={resolvedRequired || undefined}
+      aria-describedby={describedBy}
+      oninput={handleInput}
+      onfocus={handleFocus}
+      onblur={handleBlur}
+      onkeydown={handleKeydown}
+    />
+  </div>
+
+  {#if name}
+    <input
+      bind:this={hiddenInputElement}
+      type="hidden"
+      {name}
+      {value}
+      disabled={resolvedDisabled}
+    />
+  {/if}
+
+  {#if open && filteredOptions.length > 0}
+    <Popover
+      bind:open
+      id={listboxId}
+      triggerRef={inputElement}
+      role="listbox"
+      focusManagement="preserve"
+      wireTriggerAria={false}
+      closeOnEscape={false}
+      widthMode="match-anchor"
+      class="cinder-combobox__panel"
+    >
+      <ul bind:this={listboxElement} role="presentation" class="cinder-combobox__listbox">
+        {#each filteredOptions as option, index (option.value)}
+          <li
+            id="{id}-option-{index}"
+            role="option"
+            class="cinder-_option-row cinder-combobox__option"
+            aria-selected={value === option.value}
+            aria-disabled={option.disabled || undefined}
+            aria-label={option.description ? `${option.label}, ${option.description}` : undefined}
+            data-cinder-active={index === activeIndex || undefined}
+            onmousedown={(event) => {
+              // mousedown rather than click so the option fires before the
+              // input's blur cancels the popover.
+              event.preventDefault();
+              selectOption(option);
+            }}
+            onmouseenter={() => {
+              activeIndex = index;
+            }}
+          >
+            {#if option.avatar?.trim()}
+              <img
+                class="cinder-combobox__option-avatar"
+                src={option.avatar}
+                alt=""
+                loading="lazy"
+              />
+            {/if}
+            <span class="cinder-combobox__option-text">
+              <span class="cinder-combobox__option-label">{option.label}</span>
+              {#if option.description}
+                <span class="cinder-combobox__option-description">{option.description}</span>
+              {/if}
+            </span>
+          </li>
+        {/each}
+      </ul>
+    </Popover>
+  {/if}
+
+  <!-- Always in DOM so screen readers hear "No results" when text is injected.
+       Freshly-mounted role="status" nodes are not reliably announced by NVDA/JAWS. -->
+  <div
+    class="cinder-combobox__empty"
+    role="status"
+    data-cinder-active={(open && filteredOptions.length === 0) || undefined}
+  >
+    {open && filteredOptions.length === 0 ? 'No results' : ''}
+  </div>
+
+  {#if description}
+    <p id={descriptionId} class="cinder-combobox__description">{description}</p>
+  {/if}
+
+  <!-- Always in DOM for the same reason — live region must pre-exist before text is injected. -->
+  <p
+    id={field.ownErrorId ?? stableLocalErrorId}
+    class="cinder-combobox__error"
+    aria-live="polite"
+    data-cinder-error={!!error || undefined}
+  >
+    {error ?? ''}
+  </p>
+</div>

package/src/components/combobox/combobox.types.ts

@@ -0,0 +1,80 @@
+/**
+ * One option in a Combobox.
+ */
+export type ComboboxOption<T extends string = string> = {
+  /** Submitted value. */
+  value: T;
+  /** Visible label (primary line). */
+  label: string;
+  /** Optional secondary description rendered beneath the label inside the option. */
+  description?: string;
+  /**
+   * Optional avatar image URL rendered to the left of the label.
+   * The avatar is decorative — its alt text is empty because the
+   * option's accessible name already includes the label.
+   */
+  avatar?: string;
+  /** When true, the option is non-selectable. */
+  disabled?: boolean;
+};
+
+/**
+ * Props for the Combobox component.
+ *
+ * v1 scope (deliberately small):
+ * - Single-select only.
+ * - Synchronous local filtering — consumer supplies a `filter` callback,
+ *   or the default substring-on-label match runs.
+ * - No async / remote loading; no debounced fetch.
+ * - No virtualization. Visible options are capped at 200; consumers with
+ *   larger lists must paginate or pre-filter externally.
+ * - No multi-select, no token chips, no "create new" / free-text submission.
+ *
+ * Bigger Combobox patterns will live as separate components or as an
+ * extension once consumer needs justify them.
+ */
+export type ComboboxProps<T extends string = string> = {
+  /** Unique identifier — required for label association and ARIA wiring. */
+  id: string;
+  /** Currently selected value. Bindable. `''` when nothing is selected. */
+  value?: NoInfer<T> | '';
+  /** Native form field name. Renders a hidden input carrying the selected value. */
+  name?: string | undefined;
+  /** Free-text input value (the text the user has typed). Bindable. */
+  inputValue?: string;
+  /** Full set of options to filter. The sole inference source for T. */
+  options: readonly ComboboxOption<T>[];
+  /** Visible label rendered in a `<label>` associated via `for`. */
+  label?: string;
+  /** Placeholder when no value is selected. */
+  placeholder?: string;
+  /**
+   * Custom synchronous filter. Receives an option and the current input
+   * value; returns true to keep. Defaults to case-insensitive substring
+   * match on label.
+   */
+  filter?: (option: ComboboxOption<T>, query: string) => boolean;
+  /** Helper text displayed below the input; wired via aria-describedby. */
+  description?: string;
+  /** Validation error message; sets aria-invalid="true". */
+  error?: string;
+  /** Disables the combobox. Inherited from a wrapping FormField when unset. */
+  disabled?: boolean;
+  /**
+   * Marks the field required: renders the required marker on the label and
+   * sets `aria-required` on the input. Inherited from a wrapping FormField
+   * when unset.
+   */
+  required?: boolean;
+  /** Hard cap on visible filtered options. Default 200. */
+  maxVisibleOptions?: number;
+  /**
+   * External element id(s) to compose into `aria-describedby`. Composed
+   * after the component-generated description and error ids, matching the
+   * field-control contract in Select. Useful for tooltip ids, counter ids,
+   * or any external hint.
+   */
+  'aria-describedby'?: string;
+  /** Additional class names merged with `.cinder-combobox`. */
+  class?: string;
+};

package/src/components/combobox/combobox.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/combobox/index.ts

@@ -0,0 +1,6 @@
+import './combobox.css';
+import Combobox from './combobox.svelte';
+
+export default Combobox;
+export type { ComboboxOption, ComboboxProps } from './combobox.types.ts';
+export { Combobox };

package/src/components/command-item/command-item.schema.ts

@@ -0,0 +1,66 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description: 'Submitted value; surfaced through the registration record.',
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'When true, the item is skipped by arrow keys and cannot be activated.',
+    },
+    description: {
+      type: 'string',
+      description: 'Optional secondary text shown below the main label.',
+    },
+    accessibleLabel: {
+      type: 'string',
+      description:
+        'Accessible name for the option when the rendered row contains secondary text or rich content.',
+    },
+    keyboardShortcut: {
+      type: 'string',
+      description: 'Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`.',
+    },
+    class: {
+      type: 'string',
+      description: 'Class merged with `.cinder-command-item`.',
+    },
+    selectionMode: {
+      enum: ['item', 'parent'],
+      description: 'The item owns activation. This is the default CommandPalette mode.',
+    },
+  },
+  additionalProperties: false,
+  required: ['value'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Main label content.',
+      },
+      {
+        name: 'leading',
+        reason: 'function-or-snippet',
+        description: 'Leading content (icon, avatar). Rendered with aria-hidden.',
+      },
+      {
+        name: 'onselect',
+        reason: 'function-or-snippet',
+        description: 'Invoked when the item is activated inside CommandPalette.',
+      },
+      {
+        name: 'trailing',
+        reason: 'function-or-snippet',
+        description: 'Trailing content (kbd hint, badge). Rendered with aria-hidden.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/command-item/command-item.svelte

@@ -0,0 +1,100 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { classNames } from '../../utilities/class-names.ts';
+import { getCommandListContext, hasCommandListContext, } from '../_internal/command-list-context.ts';
+if (!hasCommandListContext()) {
+    throw new Error('CommandItem must be used within a CommandPalette or CommandMenu.');
+}
+let { value, onselect = () => { }, selectionMode = 'item', disabled = false, description, accessibleLabel, keyboardShortcut, leading, trailing, children, class: className, } = $props();
+const commandList = getCommandListContext();
+// Type-level mode marker: CommandPalette items own activation, while
+// CommandMenu items can opt into parent-owned activation. Read untracked
+// because this is a one-time discard, not a reactive dependency.
+void untrack(() => selectionMode);
+// Stable id assigned by the palette on registration.
+let itemId = $state(null);
+// Register with the palette at attach time, unregister on detach. Using an
+// attachment (rather than onMount) means the DOM node is available at
+// registration, so the palette can sort items by document order for
+// keyboard navigation even when middle items remount via {#if}.
+const registerWithPalette = (node) => {
+    // Attachments run inside a tracked $effect. Without untrack, the register
+    // call mutates the palette's $state registrations list, which feeds derived
+    // values the attachment indirectly depends on — producing an update cycle.
+    return untrack(() => {
+        const { id, unregister } = commandList.register({
+            getValue: () => value,
+            getOnselect: () => onselect,
+            getDisabled: () => disabled,
+        }, node);
+        itemId = id;
+        return () => {
+            unregister();
+            itemId = null;
+        };
+    });
+};
+const isActive = $derived(itemId !== null && commandList.activeItemId === itemId);
+const normalizedAccessibleLabel = $derived(normalizeOptionalAttribute(accessibleLabel));
+const normalizedKeyboardShortcut = $derived(normalizeOptionalAttribute(keyboardShortcut));
+function normalizeOptionalAttribute(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function handlePointerEnter() {
+    if (!disabled && itemId !== null) {
+        commandList.setActiveById(itemId);
+    }
+}
+function handlePointerDown(event) {
+    // Prevent the input from losing focus when the user clicks an item.
+    event.preventDefault();
+}
+function handleClick() {
+    if (!disabled && itemId !== null) {
+        commandList.activateItemById(itemId);
+    }
+}
+</script>
+
+<!-- svelte-ignore a11y_click_events_have_key_events -->
+<li
+  {@attach registerWithPalette}
+  id={itemId ?? undefined}
+  role="option"
+  class={classNames('cinder-command-item', className)}
+  aria-selected={isActive}
+  aria-disabled={disabled || undefined}
+  aria-label={normalizedAccessibleLabel}
+  aria-keyshortcuts={normalizedKeyboardShortcut}
+  data-cinder-active={isActive ? '' : undefined}
+  data-cinder-disabled={disabled || undefined}
+  onpointerenter={handlePointerEnter}
+  onpointerdown={handlePointerDown}
+  onclick={handleClick}
+>
+  {#if leading}
+    <span class="cinder-command-item__leading" aria-hidden="true">
+      {@render leading()}
+    </span>
+  {/if}
+
+  <span class="cinder-command-item__content">
+    <span class="cinder-command-item__label cinder-_truncate">
+      {@render children()}
+    </span>
+    {#if description}
+      <span class="cinder-command-item__description cinder-_truncate">{description}</span>
+    {/if}
+  </span>
+
+  {#if trailing}
+    <span class="cinder-command-item__trailing" aria-hidden="true">
+      {@render trailing()}
+    </span>
+  {/if}
+</li>

package/src/components/command-item/command-item.types.ts

@@ -0,0 +1,42 @@
+import type { Snippet } from 'svelte';
+
+type CommandItemBaseProps = {
+  /** Submitted value; surfaced through the registration record. */
+  value: string;
+  /** When true, the item is skipped by arrow keys and cannot be activated. */
+  disabled?: boolean;
+  /** Optional secondary text shown below the main label. */
+  description?: string;
+  /** Accessible name for the option when the rendered row contains secondary text or rich content. */
+  accessibleLabel?: string | undefined;
+  /** Keyboard shortcut exposed through `aria-keyshortcuts`, e.g. `Meta+N`. */
+  keyboardShortcut?: string | undefined;
+  /** Leading content (icon, avatar). Rendered with aria-hidden. */
+  leading?: Snippet;
+  /** Trailing content (kbd hint, badge). Rendered with aria-hidden. */
+  trailing?: Snippet;
+  /** Main label content. */
+  children: Snippet;
+  /** Class merged with `.cinder-command-item`. */
+  class?: string;
+};
+
+type CommandItemOwnsSelectionProps = {
+  /** Invoked when the item is activated inside CommandPalette. */
+  onselect: () => void;
+  /** The item owns activation. This is the default CommandPalette mode. */
+  selectionMode?: 'item';
+};
+
+type CommandItemParentOwnsSelectionProps = {
+  /**
+   * Lets a parent list own activation, such as CommandMenu's menu-level
+   * onselect callback.
+   */
+  selectionMode: 'parent';
+  /** Optional fallback for custom parent integrations. */
+  onselect?: () => void;
+};
+
+export type CommandItemProps = CommandItemBaseProps &
+  (CommandItemOwnsSelectionProps | CommandItemParentOwnsSelectionProps);

package/src/components/command-item/command-item.variables.ts

@@ -0,0 +1,3 @@
+const variables: readonly string[] = [];
+
+export default variables;

package/src/components/command-item/index.ts

@@ -0,0 +1,6 @@
+import './command-item.css';
+import CommandItem from './command-item.svelte';
+
+export default CommandItem;
+export type { CommandItemProps } from './command-item.types.ts';
+export { CommandItem };