@lostgradient/cinder 0.5.0 → 0.6.0

package/src/components/chip/chip.svelte

@@ -1,194 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category data-display
-   * @status stable
-   * @purpose Compact pill for metadata labels, applied filters, selected entities, and tag-like tokens, with optional removal or toggle interactions via its mode prop.
-   * @tag tag
-   * @tag filter
-   * @useWhen Representing issue labels, free-form tags, applied filters, selected entities, or other metadata tokens.
-   * @useWhen Offering a small toggleable option inside a group of choices.
-   * @avoidWhen Showing a numeric count, short status, or compact category annotation next to another element — use badge instead.
-   * @avoidWhen Picking one of a small fixed set — use segmented-control instead.
-   * @related badge, status-dot
-   */
-  export type {
-    ChipDensity,
-    ChipDisplayProps,
-    ChipMode,
-    ChipProps,
-    ChipRemovableProps,
-    ChipSize,
-    ChipToggleProps,
-    ChipVariant,
-  } from './chip.types.ts';
-</script>
-
-<script lang="ts">
-  import type { ChipProps, ChipRemovableProps, ChipToggleProps } from './chip.types.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-
-  // `ChipProps` is a discriminated union across three variants with different underlying HTML
-  // element types (<button> for toggle, <span> for display/removable). Destructuring the union
-  // directly is not possible for mode-specific props. Instead, `props` is kept as the raw typed
-  // value and bespoke props are accessed via `$derived` with narrowing casts per mode.
-  //
-  // Native HTML attributes pass through via `rest`: we strip the known bespoke prop keys at
-  // runtime and spread the remainder onto the rendered element BEFORE controlled attrs, so that
-  // component-owned attrs (data-cinder-*, aria-pressed, aria-label for toggle) always win.
-  //
-  // `onclick` for the toggle button is read via a cast so it can be wrapped — the wrapper calls
-  // the consumer's handler first, then fires `onpressedchange` unless `defaultPrevented`.
-  //
-  // `aria-label` for toggle is read via a cast so empty strings can be suppressed (an empty
-  // aria-label overrides the accessible-name computation per ARIA spec §4.3 without providing
-  // a name). Display/removable modes forward `aria-label` unchanged through `rest`.
-  let props: ChipProps = $props();
-  const mode = $derived(props.mode ?? 'display');
-  const label = $derived(props.label);
-  const variant = $derived(props.variant ?? 'neutral');
-  const size = $derived(props.size ?? 'md');
-  const density = $derived(props.density);
-  const customClassName = $derived(props.class);
-  const leadingIcon = $derived(props.leadingIcon);
-  const pressed = $derived(mode === 'toggle' ? (props as ChipToggleProps).pressed : false);
-  const onpressedchange = $derived(
-    mode === 'toggle' ? (props as ChipToggleProps).onpressedchange : undefined,
-  );
-  const disabled = $derived(
-    mode !== 'display' ? (props as ChipToggleProps | ChipRemovableProps).disabled : undefined,
-  );
-  const consumerOnClick = $derived(
-    mode === 'toggle' ? (props as ChipToggleProps).onclick : undefined,
-  );
-  const ariaLabelRaw = $derived(
-    mode === 'toggle' ? (props as ChipToggleProps)['aria-label'] : undefined,
-  );
-  const ariaLabel = $derived(
-    typeof ariaLabelRaw === 'string' && ariaLabelRaw.trim().length > 0 ? ariaLabelRaw : undefined,
-  );
-  const onremove = $derived(
-    mode === 'removable' ? (props as ChipRemovableProps).onremove : undefined,
-  );
-  const removeAriaLabel = $derived.by(() => {
-    if (mode !== 'removable') return undefined;
-    const raw = (props as ChipRemovableProps).removeAriaLabel;
-    return typeof raw === 'string' && raw.trim().length > 0 ? raw : undefined;
-  });
-
-  // Compute `rest` by stripping all known bespoke prop keys from the raw props object.
-  // Whatever remains is a set of native HTML attributes the consumer intends to forward.
-  // This achieves the same effect as `const { a, b, c, ...rest } = $props()` but works
-  // across the discriminated union where not all keys are common to every variant.
-  // `onclick` is intentionally NOT in this set: for display/removable modes it should flow
-  // through `rest` unchanged. For toggle mode, the explicit `onclick={wrapper}` on the <button>
-  // appears after the spread and overrides `rest`'s value; the wrapper reads `consumerOnClick`
-  // (captured via $derived cast above) and calls it first.
-  //
-  // `aria-label` is also NOT stripped: display/removable modes forward it through `rest`.
-  // For toggle mode, the explicit `aria-label={ariaLabel}` (empty-string-filtered) overrides.
-  const BESPOKE_KEYS = new Set([
-    'mode',
-    'label',
-    'variant',
-    'size',
-    'density',
-    'leadingIcon',
-    'class',
-    'pressed',
-    'onpressedchange',
-    'disabled',
-    'onremove',
-    'removeAriaLabel',
-  ]);
-
-  const rest = $derived.by(() => {
-    const result: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(props as Record<string, unknown>)) {
-      if (!BESPOKE_KEYS.has(key)) {
-        result[key] = value;
-      }
-    }
-    return result;
-  });
-
-  // A bare `role="group"` needs an accessible name, so removable mode names the
-  // group with its `label` by default. But `aria-label` flows through `rest` for
-  // display/removable modes (see above), so a consumer-supplied `aria-label`
-  // must win. Resolve to the consumer's value when present, falling back to
-  // `label` — and apply it explicitly so it can't be clobbered by the spread.
-  const removableAriaLabel = $derived.by(() => {
-    const forwarded = rest['aria-label'];
-    return typeof forwarded === 'string' && forwarded.trim().length > 0 ? forwarded : label;
-  });
-</script>
-
-{#if mode === 'toggle'}
-  <button
-    {...rest}
-    type="button"
-    data-cinder-mode="toggle"
-    data-cinder-variant={variant}
-    data-cinder-size={size}
-    data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
-    class={classNames('cinder-chip', customClassName)}
-    aria-pressed={pressed}
-    aria-label={ariaLabel}
-    {disabled}
-    onclick={(event) => {
-      if (disabled) return;
-      consumerOnClick?.(event);
-      if (!event.defaultPrevented) {
-        onpressedchange?.(!pressed);
-      }
-    }}
-  >
-    {#if leadingIcon}
-      <span class="cinder-chip__icon" aria-hidden="true">{@render leadingIcon()}</span>
-    {/if}
-    <span class="cinder-chip__label">{label}</span>
-  </button>
-{:else if mode === 'removable'}
-  <span
-    {...rest}
-    role="group"
-    aria-label={removableAriaLabel}
-    data-cinder-mode="removable"
-    data-cinder-variant={variant}
-    data-cinder-size={size}
-    data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
-    data-cinder-disabled={disabled || undefined}
-    aria-disabled={disabled || undefined}
-    class={classNames('cinder-chip', customClassName)}
-  >
-    {#if leadingIcon}
-      <span class="cinder-chip__icon" aria-hidden="true">{@render leadingIcon()}</span>
-    {/if}
-    <span class="cinder-chip__label">{label}</span>
-    <button
-      type="button"
-      class="cinder-chip__remove"
-      aria-label={removeAriaLabel ?? `Remove ${label}`}
-      {disabled}
-      onclick={() => {
-        if (!disabled) onremove?.();
-      }}
-    >
-      <span aria-hidden="true">×</span>
-    </button>
-  </span>
-{:else}
-  <span
-    {...rest}
-    data-cinder-mode="display"
-    data-cinder-variant={variant}
-    data-cinder-size={size}
-    data-cinder-density={density === 'toolbar' ? 'toolbar' : undefined}
-    class={classNames('cinder-chip', customClassName)}
-  >
-    {#if leadingIcon}
-      <span class="cinder-chip__icon" aria-hidden="true">{@render leadingIcon()}</span>
-    {/if}
-    <span class="cinder-chip__label">{label}</span>
-  </span>
-{/if}

package/src/components/chip/chip.types.ts

@@ -1,89 +0,0 @@
-import type { Snippet } from 'svelte';
-import type { HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
-import type { BadgeVariant } from '../badge/badge.types.ts';
-export type ChipVariant = BadgeVariant;
-export type ChipSize = 'sm' | 'md';
-export type ChipMode = 'display' | 'toggle' | 'removable';
-/**
- * Opt the chip into a shared toolbar height (via `--cinder-control-height-sm`)
- * so it lines up with sibling Button (size="sm") and SegmentedControl
- * (density="toolbar"). Default rendering is unchanged.
- */
-export type ChipDensity = 'toolbar';
-export type ChipDisplayProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
-  /** Rendering and interaction mode. Default `"display"`. */
-  mode?: 'display';
-  /** Visible text content of the chip. */
-  label: string;
-  /** Color variant applied to the chip. Default `"neutral"`. */
-  variant?: ChipVariant;
-  /** Size of the chip. Default `"md"`. */
-  size?: ChipSize;
-  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
-  density?: ChipDensity;
-  leadingIcon?: Snippet;
-  /** Additional class names merged onto the chip element. */
-  class?: string;
-  // Cross-variant sentinel props: present as `never` so the union is destructurable in chip.svelte,
-  // and consumers get a compile-time error if they pass toggle/removable-only props to display mode.
-  pressed?: never;
-  disabled?: never;
-  onpressedchange?: never;
-  onremove?: never;
-  removeAriaLabel?: never;
-};
-// `aria-pressed` is owned (set from the `pressed` prop) and `type` is always `"button"`
-// (a toggle chip must never become a form submitter), so both are Omit-ted — a consumer
-// value would be silently overridden. `onclick` and `aria-label` are intentionally NOT
-// omitted: the component consumes them (wraps onclick, suppresses empty aria-label)
-// rather than discarding them.
-export type ChipToggleProps = Omit<
-  HTMLButtonAttributes,
-  'class' | 'disabled' | 'aria-pressed' | 'type'
-> & {
-  /** Rendering and interaction mode. Must be `"toggle"` for this variant. */
-  mode: 'toggle';
-  /** Visible text content of the chip. */
-  label: string;
-  /** Color variant applied to the chip. Default `"neutral"`. */
-  variant?: ChipVariant;
-  /** Size of the chip. Default `"md"`. */
-  size?: ChipSize;
-  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
-  density?: ChipDensity;
-  leadingIcon?: Snippet;
-  /** Additional class names merged onto the chip element. */
-  class?: string;
-  /** Toggle mode only. Whether the chip is currently in the pressed (selected) state. Reflected as `aria-pressed`. */
-  pressed: boolean;
-  onpressedchange?: (pressed: boolean) => void;
-  /** Toggle mode only. When true, disables the toggle button and prevents interaction. */
-  disabled?: boolean;
-  // Cross-variant sentinel props
-  onremove?: never;
-  removeAriaLabel?: never;
-};
-export type ChipRemovableProps = Omit<HTMLAttributes<HTMLSpanElement>, 'class'> & {
-  /** Rendering and interaction mode. Must be `"removable"` for this variant. */
-  mode: 'removable';
-  /** Visible text content of the chip and fallback accessible name for the remove button. */
-  label: string;
-  /** Color variant applied to the chip. Default `"neutral"`. */
-  variant?: ChipVariant;
-  /** Size of the chip. Default `"md"`. */
-  size?: ChipSize;
-  /** When set to `"toolbar"`, opts the chip into compact toolbar sizing to align with sibling toolbar controls. */
-  density?: ChipDensity;
-  leadingIcon?: Snippet;
-  /** Additional class names merged onto the chip element. */
-  class?: string;
-  onremove?: () => void;
-  /** Removable mode only. When true, disables the remove button and prevents removal. */
-  disabled?: boolean;
-  /** Removable mode only. Accessible label for the remove button. Defaults to `Remove` followed by the chip's `label`. */
-  removeAriaLabel?: string;
-  // Cross-variant sentinel props
-  pressed?: never;
-  onpressedchange?: never;
-};
-export type ChipProps = ChipDisplayProps | ChipToggleProps | ChipRemovableProps;

package/src/components/chip/index.ts

@@ -1,15 +0,0 @@
-import './chip.css';
-import Chip from './chip.svelte';
-
-export default Chip;
-export type {
-  ChipDensity,
-  ChipDisplayProps,
-  ChipMode,
-  ChipProps,
-  ChipRemovableProps,
-  ChipSize,
-  ChipToggleProps,
-  ChipVariant,
-} from './chip.types.ts';
-export { Chip };

package/src/components/choice-grid/choice-grid-context.ts

@@ -1,30 +0,0 @@
-import { createContext } from 'svelte';
-
-import type { ChoiceGridContext } from './choice-grid.types.ts';
-
-export type { ChoiceGridContext };
-
-/**
- * Context published by `<ChoiceGrid>` for descendant `<ChoiceGridItem>` children.
- *
- * All members are getter properties on the context object so reads stay
- * reactive — when a consumer reads `context.value` inside a `$derived`,
- * the read flows through the getter which returns a value recomputed from
- * ChoiceGrid's `$derived` internals. Destructuring breaks reactivity;
- * getter reads preserve it.
- *
- * The context is *required* — a `<ChoiceGridItem>` outside a `<ChoiceGrid>` is a
- * programmer error. The `getChoiceGridContext` getter therefore throws
- * (via Svelte 5's `createContext`) when no provider exists.
- */
-
-const [getChoiceGridContextStrict, setChoiceGridContext] = createContext<ChoiceGridContext>();
-
-export { setChoiceGridContext };
-
-/**
- * Read the enclosing `<ChoiceGrid>` context. Throws via Svelte 5's
- * `createContext` when no provider exists — a `<ChoiceGridItem>` rendered
- * outside a `<ChoiceGrid>` is a programmer error.
- */
-export const getChoiceGridContext = getChoiceGridContextStrict;

package/src/components/choice-grid/choice-grid.svelte

@@ -1,272 +0,0 @@
-<script lang="ts" module>
-  /**
-   * @cinder
-   * @category form
-   * @status alpha
-   * @purpose Responsive grid of large selectable choices with roving keyboard focus, selection state, and optional correct/incorrect/pending feedback for quiz and assessment surfaces.
-   * @tag form
-   * @tag selection
-   * @tag quiz
-   * @tag assessment
-   * @useWhen Presenting a small fixed set of large selectable answers where all options should stay visible (quiz or assessment surfaces).
-   * @useWhen Building a touch-friendly selector grid with stable cell dimensions that must not shift when feedback states are applied.
-   * @avoidWhen Selecting from a long dynamic list — use combobox or select instead.
-   * @avoidWhen Choosing one of two to five short values in a compact inline context — use segmented-control instead.
-   * @related choice-grid-item, segmented-control, radio-group, checkbox-group
-   */
-  export type {
-    ChoiceGridColumns,
-    ChoiceGridContext,
-    ChoiceGridItemState,
-    ChoiceGridProps,
-  } from './choice-grid.types.ts';
-</script>
-
-<script lang="ts">
-  import type { ChoiceGridProps } from './choice-grid.types.ts';
-  import { setChoiceGridContext } from './choice-grid-context.ts';
-  import { classNames } from '../../utilities/class-names.ts';
-  import { createSingleSelection, createMultiSelection } from '../../_internal/collection.ts';
-  import { handleRovingKeydown } from '../../utilities/roving-tabindex.ts';
-  import { devWarn } from '../../utilities/dev-warn.ts';
-
-  let {
-    value = $bindable(null),
-    values = $bindable([]),
-    multiple = false,
-    columns = 'responsive',
-    minColumnWidth = '10rem',
-    ariaLabel,
-    ariaLabelledby,
-    disabled = false,
-    class: className,
-    children,
-    ...rest
-  }: ChoiceGridProps = $props();
-
-  // Registry of items keyed by value. Insertion order determines navigation
-  // order (linear roving through the visual grid). `disabled` is tracked so both
-  // the roving-tabindex computation and arrow-key navigation skip disabled items.
-  type RegisteredItem = { element: HTMLElement; disabled: boolean };
-  const items: Map<string, RegisteredItem> = new Map();
-  let version = $state(0);
-
-  const singleSelection = $derived(
-    createSingleSelection(
-      () => value ?? null,
-      (next) => {
-        value = next;
-      },
-    ),
-  );
-
-  const multiSelection = $derived(
-    createMultiSelection(
-      () => values,
-      (next) => {
-        values = next;
-      },
-    ),
-  );
-
-  function isSelected(candidate: string): boolean {
-    if (multiple) {
-      return multiSelection.isSelected(candidate);
-    }
-    return singleSelection.isSelected(candidate);
-  }
-
-  function select(candidate: string): void {
-    // Refuse to activate when the grid is disabled OR the specific item is
-    // disabled — items forward keydown unconditionally (so navigation isn't
-    // trapped), which means Space/Enter can reach here for a disabled item.
-    if (isItemDisabled(candidate)) return;
-    if (multiple) {
-      multiSelection.toggle(candidate);
-    } else {
-      singleSelection.select(candidate);
-    }
-  }
-
-  function isItemDisabled(candidate: string): boolean {
-    if (disabled) return true;
-    return items.get(candidate)?.disabled ?? false;
-  }
-
-  // Item values ordered by their RENDERED DOM position, not Map-insertion order.
-  // Reordering keyed `{#each}` children reorders the DOM without re-registering,
-  // so roving navigation and the default tabindex target must follow the visual
-  // order — otherwise focus moves along the wrong sequence.
-  function orderedKeys(): string[] {
-    return [...items.entries()]
-      .sort(([, a], [, b]) => {
-        const position = a.element.compareDocumentPosition(b.element);
-        if (position & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
-        if (position & Node.DOCUMENT_POSITION_PRECEDING) return 1;
-        return 0;
-      })
-      .map(([key]) => key);
-  }
-
-  // The single ENABLED value that should hold `tabindex="0"`. Disabled items are
-  // never focusable: prefer the (enabled) selected value, else the first enabled
-  // registered item. Returns null when every item is disabled.
-  const focusableValue = $derived.by(() => {
-    void version;
-    void value;
-    void values;
-    const ordered = orderedKeys();
-    if (ordered.length === 0) return null;
-
-    if (!multiple && value !== null && value !== undefined) {
-      if (items.has(value) && !isItemDisabled(value)) return value;
-    }
-    if (multiple && values.length > 0) {
-      for (const selected of values) {
-        if (items.has(selected) && !isItemDisabled(selected)) return selected;
-      }
-    }
-    // First enabled item in DOM order.
-    for (const key of ordered) {
-      if (!isItemDisabled(key)) return key;
-    }
-    return null;
-  });
-
-  function isFocusable(candidate: string): boolean {
-    // Subscribe to reactive inputs so this stays current inside $derived.
-    void version;
-    void value;
-    void values;
-    return focusableValue === candidate;
-  }
-
-  function register(itemValue: string, element: HTMLElement, itemDisabled: boolean): void {
-    items.set(itemValue, { element, disabled: itemDisabled });
-    version += 1;
-  }
-
-  function setItemDisabled(itemValue: string, itemDisabled: boolean): void {
-    const existing = items.get(itemValue);
-    if (existing && existing.disabled !== itemDisabled) {
-      items.set(itemValue, { element: existing.element, disabled: itemDisabled });
-      version += 1;
-    }
-  }
-
-  function unregister(itemValue: string): void {
-    if (items.delete(itemValue)) {
-      version += 1;
-    }
-  }
-
-  function handleKeydown(event: KeyboardEvent): void {
-    const keys = orderedKeys();
-    const currentIndex = keys.findIndex((key) => {
-      const entry = items.get(key);
-      return entry?.element === event.currentTarget || entry?.element === event.target;
-    });
-
-    if (currentIndex === -1) return;
-
-    // Space/Enter: activate the currently focused item.
-    if (event.key === ' ' || event.key === 'Enter') {
-      event.preventDefault();
-      const focusedValue = keys[currentIndex];
-      if (focusedValue !== undefined) {
-        select(focusedValue);
-      }
-      return;
-    }
-
-    // Arrow keys: LINEAR roving through the visual grid in DOM order (the
-    // responsive column count is layout-dependent, so v1 uses linear roving
-    // rather than measured 2D movement). Disabled items are skipped.
-    const nextIndex = handleRovingKeydown(event, currentIndex, keys.length, {
-      horizontal: true,
-      vertical: true,
-      isDisabled: (index) => {
-        const key = keys[index];
-        return key === undefined ? true : isItemDisabled(key);
-      },
-    });
-
-    if (nextIndex === null || nextIndex === currentIndex) return;
-    event.preventDefault();
-
-    const nextValue = keys[nextIndex];
-    if (nextValue === undefined) return;
-    items.get(nextValue)?.element.focus();
-
-    // WAI-ARIA radiogroup pattern: arrow navigation also moves the selection in
-    // single-select mode. Multi-select (checkbox semantics) only moves focus —
-    // selection toggles on Space/Enter/click.
-    if (!multiple) {
-      select(nextValue);
-    }
-  }
-
-  setChoiceGridContext({
-    get value() {
-      return value ?? null;
-    },
-    get multiple() {
-      return multiple;
-    },
-    get disabled() {
-      return disabled;
-    },
-    isSelected,
-    select,
-    register,
-    setItemDisabled,
-    unregister,
-    isFocusable,
-    handleKeydown,
-  });
-
-  // Empty strings are normalized to `undefined` so `aria-label=""` does not
-  // suppress the accessible-name fallback and leave the group unnamed.
-  const resolvedAriaLabel = $derived(ariaLabel?.trim() ? ariaLabel : undefined);
-  const resolvedAriaLabelledby = $derived(ariaLabelledby?.trim() ? ariaLabelledby : undefined);
-
-  // Dev-time guardrails for the two easy-to-miss API contracts.
-  $effect(() => {
-    if (values.length > 0 && !multiple) {
-      devWarn(
-        'ChoiceGrid: `values` was provided without `multiple`. Binding `values` does not enable multi-select — set `multiple` explicitly. The grid is operating in single-select mode and ignoring `values`.',
-      );
-    }
-    // Check the resolved (non-empty) names so `ariaLabel=""` / `ariaLabelledby=""`
-    // still warn — an empty string leaves the control unnamed.
-    if (!resolvedAriaLabel && !resolvedAriaLabelledby) {
-      devWarn(
-        'ChoiceGrid: no `ariaLabel` or `ariaLabelledby` provided. The radiogroup/group has no accessible name — pass one.',
-      );
-    }
-  });
-
-  // Grid template columns CSS.
-  const gridTemplateColumns = $derived(
-    columns === 'responsive'
-      ? `repeat(auto-fill, minmax(min(${minColumnWidth}, 100%), 1fr))`
-      : `repeat(${columns}, 1fr)`,
-  );
-
-  // ARIA role: radiogroup for single-select, group for multi-select.
-  const role = $derived(multiple ? 'group' : 'radiogroup');
-</script>
-
-<div
-  {...rest}
-  {role}
-  class={classNames('cinder-choice-grid', className)}
-  aria-label={resolvedAriaLabel}
-  aria-labelledby={resolvedAriaLabelledby}
-  aria-disabled={disabled || undefined}
-  data-cinder-multiple={multiple || undefined}
-  data-cinder-disabled={disabled || undefined}
-  style:--cinder-choice-grid-columns={gridTemplateColumns}
->
-  {@render children()}
-</div>