@lostgradient/cinder 0.5.0 → 0.6.0

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

@@ -1,80 +0,0 @@
-/**
- * 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/index.ts

@@ -1,6 +0,0 @@
-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.svelte

@@ -1,144 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category action
-   * @status stable
-   * @purpose Single selectable row inside a command palette or inline command menu that registers itself with the parent command list.
-   * @tag action
-   * @tag command
-   * @useWhen Declaring an individual command, action, or result row inside a command-palette or command-menu.
-   * @useWhen Composing a custom palette layout via children rather than the items prop.
-   * @avoidWhen Used outside a command-palette or command-menu ancestor — the component throws at construction.
-   * @avoidWhen Rendering a generic dropdown choice — use dropdown-item instead.
-   * @related command-palette, command-menu, dropdown-item
-   */
-  export type { CommandItemProps } from './command-item.types.ts';
-</script>
-
-<script lang="ts">
-  import type { CommandItemProps } from './command-item.types.ts';
-  import { untrack } from 'svelte';
-  import type { Attachment } from 'svelte/attachments';
-
-  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,
-  }: CommandItemProps = $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<string | null>(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: Attachment<HTMLElement> = (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: string | undefined): string | undefined {
-    const trimmed = value?.trim();
-    return trimmed ? trimmed : undefined;
-  }
-
-  function handlePointerEnter() {
-    if (!disabled && itemId !== null) {
-      commandList.setActiveById(itemId);
-    }
-  }
-
-  function handlePointerDown(event: PointerEvent) {
-    // 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

@@ -1,42 +0,0 @@
-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/index.ts

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

package/src/components/command-menu/caret-rect.svelte.ts

@@ -1,93 +0,0 @@
-const MIRROR_STYLE_PROPERTIES = [
-  'box-sizing',
-  'width',
-  'height',
-  'min-height',
-  'max-height',
-  'border-block-start-style',
-  'border-block-end-style',
-  'border-inline-start-style',
-  'border-inline-end-style',
-  'border-top-style',
-  'border-right-style',
-  'border-bottom-style',
-  'border-left-style',
-  'border-block-start-width',
-  'border-block-end-width',
-  'border-inline-start-width',
-  'border-inline-end-width',
-  'border-top-width',
-  'border-right-width',
-  'border-bottom-width',
-  'border-left-width',
-  'padding-block-start',
-  'padding-block-end',
-  'padding-inline-start',
-  'padding-inline-end',
-  'font-family',
-  'font-size',
-  'font-weight',
-  'font-style',
-  'font-variant',
-  'line-height',
-  'letter-spacing',
-  'word-spacing',
-  'text-indent',
-  'text-transform',
-  'text-align',
-  'text-rendering',
-  'overflow-wrap',
-  'word-break',
-  'word-wrap',
-  'tab-size',
-  'direction',
-  'writing-mode',
-] as const;
-
-export function getCaretRect(
-  field: HTMLInputElement | HTMLTextAreaElement | null,
-  caretIndex: number,
-): DOMRect | null {
-  if (!field || typeof document === 'undefined' || typeof getComputedStyle === 'undefined') {
-    return null;
-  }
-
-  const fieldRect = field.getBoundingClientRect();
-  if (fieldRect.width === 0 || fieldRect.height === 0 || !field.isConnected) return null;
-
-  const computedStyle = getComputedStyle(field);
-  const mirror = document.createElement('div');
-  const marker = document.createElement('span');
-  const normalizedCaretIndex = Math.max(0, Math.min(caretIndex, field.value.length));
-
-  mirror.setAttribute('data-cinder-command-menu-caret-mirror', '');
-  mirror.style.position = 'fixed';
-  mirror.style.visibility = 'hidden';
-  mirror.style.pointerEvents = 'none';
-  mirror.style.whiteSpace = field instanceof HTMLTextAreaElement ? 'pre-wrap' : 'pre';
-  mirror.style.overflow = computedStyle.overflow;
-  mirror.style.left = `${fieldRect.left}px`;
-  mirror.style.top = `${fieldRect.top}px`;
-
-  for (const property of MIRROR_STYLE_PROPERTIES) {
-    mirror.style.setProperty(property, computedStyle.getPropertyValue(property));
-  }
-
-  mirror.textContent = field.value.slice(0, normalizedCaretIndex);
-  marker.textContent = '\u200b';
-  mirror.append(marker);
-  document.body.append(mirror);
-  mirror.scrollLeft = field.scrollLeft;
-  mirror.scrollTop = field.scrollTop;
-
-  const markerRect = marker.getBoundingClientRect();
-  const rect = new DOMRect(
-    markerRect.left,
-    markerRect.top,
-    Math.max(markerRect.width, 1),
-    Math.max(markerRect.height, Number.parseFloat(computedStyle.lineHeight) || 16),
-  );
-
-  mirror.remove();
-  return rect;
-}

package/src/components/command-menu/command-menu-trigger.ts

@@ -1,41 +0,0 @@
-import type { CommandMenuTriggerMatch } from './command-menu.types.ts';
-
-export type DetectCommandMenuTriggerOptions = {
-  text: string;
-  selectionStart: number;
-  selectionEnd: number;
-  triggerChar?: string;
-};
-
-function isSingleNonWhitespaceCodePoint(value: string): boolean {
-  return Array.from(value).length === 1 && !/\s/u.test(value);
-}
-
-export function detectTrigger({
-  text,
-  selectionStart,
-  selectionEnd,
-  triggerChar = '/',
-}: DetectCommandMenuTriggerOptions): CommandMenuTriggerMatch | null {
-  if (selectionStart !== selectionEnd) return null;
-  if (!isSingleNonWhitespaceCodePoint(triggerChar)) return null;
-
-  const caretIndex = Math.max(0, Math.min(selectionEnd, text.length));
-  if (caretIndex === 0) return null;
-
-  const triggerStart = text.lastIndexOf(triggerChar, caretIndex - 1);
-  if (triggerStart < 0) return null;
-
-  const beforeTrigger = triggerStart === 0 ? '' : text[triggerStart - 1];
-  if (beforeTrigger && !/\s/u.test(beforeTrigger)) return null;
-
-  const query = text.slice(triggerStart + triggerChar.length, caretIndex);
-  if (/\s/u.test(query)) return null;
-
-  return {
-    active: true,
-    query,
-    start: triggerStart,
-    end: caretIndex,
-  };
-}

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

@@ -1,179 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category overlay
-   * @status stable
-   * @purpose Inline caret-anchored slash-command list for textareas and single-line text inputs.
-   * @tag overlay
-   * @tag command
-   * @useWhen Showing a contextual command list at the caret while a user types in a textarea or input.
-   * @useWhen Building slash-command insertion flows where the host owns text replacement.
-   * @avoidWhen Exposing a global app launcher — use command-palette instead.
-   * @avoidWhen Selecting from a static form option list — use combobox instead.
-   * @related command-palette, command-item, popover, combobox
-   */
-  export type {
-    CommandMenuProps,
-    CommandMenuSelection,
-    CommandMenuState,
-    CommandMenuTriggerMatch,
-  } from './command-menu.types.ts';
-  export { detectTrigger } from './command-menu-trigger.ts';
-</script>
-
-<script lang="ts">
-  import type { CommandMenuProps } from './command-menu.types.ts';
-  import { getCaretRect } from './caret-rect.svelte.ts';
-  import type { Placement, VirtualElement } from '@floating-ui/dom';
-  import { on } from 'svelte/events';
-
-  import { createAnchoredOverlay } from '../../_internal/anchored-overlay.svelte.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import { setCommandListContext } from '../_internal/command-list-context.ts';
-  import { createCommandListState } from '../_internal/create-command-list-state.svelte.ts';
-  import { createPortalAttachment } from '../portal/index.ts';
-
-  const listboxId = $props.id();
-
-  let {
-    open = $bindable(false),
-    anchor,
-    caretIndex,
-    query = $bindable(''),
-    items,
-    empty,
-    placement = 'bottom-start',
-    offset = 6,
-    label = 'Commands',
-    onselect,
-    ondismiss,
-    onstatechange,
-    class: className,
-  }: CommandMenuProps = $props();
-
-  const portalAttachment = createPortalAttachment({
-    target: () => document.body,
-    inheritAttributes: true,
-    source: () => anchor,
-  });
-
-  let mounted = $state(false);
-  let listElement: HTMLElement | undefined = $state();
-  const commandList = createCommandListState(listboxId);
-
-  const showEmpty = $derived(
-    mounted && open && commandList.registrationsReady && commandList.registrations.length === 0,
-  );
-  const caretAnchor = $derived.by<VirtualElement | null>(() => {
-    const anchorElement = anchor;
-    const currentCaretIndex = caretIndex;
-    if (!anchorElement) return null;
-    return {
-      getBoundingClientRect() {
-        return (
-          getCaretRect(anchorElement, currentCaretIndex) ?? anchorElement.getBoundingClientRect()
-        );
-      },
-    };
-  });
-
-  const anchoredOverlay = createAnchoredOverlay({
-    open: () => open,
-    anchor: () => caretAnchor,
-    panel: () => listElement,
-    placement: () => placement as Placement,
-    offset: () => offset,
-    widthMode: () => 'content',
-  });
-
-  $effect(() => {
-    mounted = true;
-  });
-
-  $effect(() => {
-    if (!open) {
-      commandList.resetActiveItem();
-      return;
-    }
-  });
-
-  $effect(() => {
-    void query;
-    commandList.refreshRegistrationsReady();
-  });
-
-  $effect(() => {
-    onstatechange?.({ listboxId, activeItemId: open ? commandList.activeItemId : null });
-  });
-
-  $effect(() => {
-    commandList.scrollActiveItemIntoView();
-  });
-
-  function activateItemById(id: string) {
-    const record = commandList.activateItemById(id);
-    if (!record) return;
-    // The command list activates the item callback first; the menu-level
-    // `onselect` prop then receives the committed value and query.
-    onselect?.({ value: record.getValue(), query });
-  }
-
-  setCommandListContext(commandList.createContext(activateItemById));
-
-  function dismiss() {
-    if (!open) return;
-    open = false;
-    ondismiss?.();
-  }
-
-  function handleKeydown(event: KeyboardEvent) {
-    if (!open) return;
-    commandList.handleKeydown({
-      event,
-      onEnter: activateItemById,
-      onEscape: dismiss,
-      ignoreModifiedNavigation: true,
-    });
-  }
-
-  function handleDocumentPointerdown(event: PointerEvent) {
-    const target = event.target;
-    if (!(target instanceof Node)) return;
-    if (anchor?.contains(target)) return;
-    if (listElement?.contains(target)) return;
-    dismiss();
-  }
-
-  $effect(() => {
-    if (!open || !anchor) return;
-    const stopKeydown = on(anchor, 'keydown', handleKeydown);
-    const stopPointerdown = on(document, 'pointerdown', handleDocumentPointerdown, {
-      capture: true,
-    });
-
-    return () => {
-      stopKeydown();
-      stopPointerdown();
-    };
-  });
-</script>
-
-{#if mounted && open && anchor}
-  <div
-    bind:this={listElement}
-    {@attach portalAttachment}
-    aria-hidden={anchoredOverlay.positionReady ? undefined : 'true'}
-    class={classNames('cinder-_floating-surface', 'cinder-command-menu', className)}
-    data-cinder-position-ready={anchoredOverlay.positionReady}
-    style={anchoredOverlay.positionStyle}
-  >
-    <ul id={listboxId} role="listbox" aria-label={label} class="cinder-command-menu__listbox">
-      {@render items({ query })}
-    </ul>
-    {#if showEmpty && empty}
-      <div class="cinder-command-menu__empty" role="status">
-        {@render empty()}
-      </div>
-    {/if}
-  </div>
-{/if}

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

@@ -1,49 +0,0 @@
-import type { Snippet } from 'svelte';
-
-import type { PopoverPlacement } from '../popover/popover.types.ts';
-
-export type CommandMenuTriggerMatch = {
-  active: true;
-  query: string;
-  start: number;
-  end: number;
-};
-
-export type CommandMenuSelection = {
-  value: string;
-  query: string;
-};
-
-export type CommandMenuState = {
-  listboxId: string;
-  activeItemId: string | null;
-};
-
-export type CommandMenuProps = {
-  /** Open state. Bindable. Default `false`. */
-  open?: boolean;
-  /** Text field used as the caret-position anchor. */
-  anchor: HTMLInputElement | HTMLTextAreaElement | null;
-  /** Caret offset within the anchor value. */
-  caretIndex: number;
-  /** Query text after the trigger character. Bindable. Default `''`. */
-  query?: string;
-  /** Render command items for the current query. */
-  items: Snippet<[{ query: string }]>;
-  /** Optional empty state rendered after item registration settles. */
-  empty?: Snippet;
-  /** Caret-relative placement. Default `'bottom-start'`. */
-  placement?: PopoverPlacement;
-  /** Distance in px between the caret and menu. Default `6`. */
-  offset?: number;
-  /** Accessible listbox label. Default `'Commands'`. */
-  label?: string;
-  /** Invoked when an enabled command is activated. */
-  onselect?: (detail: CommandMenuSelection) => void;
-  /** Invoked when Escape or outside pointerdown dismisses the menu. */
-  ondismiss?: () => void;
-  /** One-way state output for host-owned field ARIA. */
-  onstatechange?: (state: CommandMenuState) => void;
-  /** Class merged with `.cinder-command-menu`. */
-  class?: string;
-};

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

@@ -1,12 +0,0 @@
-import './command-menu.css';
-import CommandMenu from './command-menu.svelte';
-
-export default CommandMenu;
-export { detectTrigger } from './command-menu-trigger.ts';
-export type {
-  CommandMenuProps,
-  CommandMenuSelection,
-  CommandMenuState,
-  CommandMenuTriggerMatch,
-} from './command-menu.types.ts';
-export { CommandMenu };