@lostgradient/cinder 0.1.1 → 0.2.0

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

@@ -0,0 +1,152 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/**
+ * Feedback state for a choice grid item. Neutral means no feedback applied.
+ * Correct / incorrect / pending communicate quiz or assessment results.
+ */
+export type ChoiceGridItemState = 'neutral' | 'correct' | 'incorrect' | 'pending';
+
+/**
+ * Column layout for the grid. 'responsive' uses auto-fill with a minimum cell
+ * width. A number sets a fixed column count.
+ */
+export type ChoiceGridColumns = 'responsive' | 1 | 2 | 3 | 4;
+
+/**
+ * Shape of the context object provided to ChoiceGridItem children.
+ *
+ * All members are getter properties on the context object so reads remain
+ * reactive inside `$derived` expressions in the children. Destructuring the
+ * context breaks reactivity; always access via `context.field`.
+ */
+export type ChoiceGridContext = {
+  /**
+   * The currently selected value (single-select mode) or null when nothing
+   * is selected. In multi-select mode this field is unused — children check
+   * `isSelected` instead.
+   */
+  readonly value: string | null;
+
+  /** True when the grid allows multiple simultaneous selections. */
+  readonly multiple: boolean;
+
+  /** True when ALL items are disabled (the grid-level disabled prop). */
+  readonly disabled: boolean;
+
+  /**
+   * True when `candidate` is currently selected (works for both single- and
+   * multi-select modes).
+   */
+  isSelected: (candidate: string) => boolean;
+
+  /**
+   * Select or toggle `candidate`. In single-select mode this sets the value;
+   * in multi-select mode this toggles the candidate in the values set.
+   */
+  select: (candidate: string) => void;
+
+  /**
+   * Register an item element with the parent so the parent can drive roving
+   * tabindex focus. `disabled` is tracked so disabled items are skipped by both
+   * the roving-tabindex computation and arrow-key navigation.
+   */
+  register: (value: string, element: HTMLElement, disabled: boolean) => void;
+
+  /** Update the tracked disabled state for an already-registered item. */
+  setItemDisabled: (value: string, disabled: boolean) => void;
+
+  /** Remove an item from the registry on unmount. */
+  unregister: (value: string) => void;
+
+  /**
+   * Whether `candidate` should hold `tabindex="0"`. Must be called inside
+   * a `$derived` to remain reactive.
+   */
+  isFocusable: (candidate: string) => boolean;
+
+  /** Items forward `keydown` here for shared arrow-key navigation. */
+  handleKeydown: (event: KeyboardEvent) => void;
+};
+
+/**
+ * Props for the `<ChoiceGrid>` parent component.
+ */
+export type ChoiceGridProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'role' | 'aria-label' | 'aria-labelledby'
+> & {
+  /**
+   * The currently selected value (single-select mode). Bindable.
+   * Pass `null` or omit to start with no selection.
+   */
+  value?: string | null;
+
+  /**
+   * Currently selected values (multi-select mode). Bindable. Only used when
+   * `multiple` is `true` — set `multiple` explicitly to switch modes; binding
+   * `values` alone does NOT enable multi-select.
+   */
+  values?: string[];
+
+  /**
+   * When true the grid allows multiple simultaneous selections and reads/writes
+   * `values` instead of `value`. The ARIA role switches to `group` (items become
+   * `checkbox`); single-select uses `radiogroup` (items become `radio`).
+   */
+  multiple?: boolean;
+
+  /**
+   * Column layout.
+   * - `'responsive'` — `auto-fill` at a minimum cell width (default).
+   * - `1 | 2 | 3 | 4` — fixed number of columns.
+   */
+  columns?: ChoiceGridColumns;
+
+  /**
+   * Minimum cell width for `columns="responsive"`. Accepts any CSS
+   * `<length>` (e.g. `"12rem"`, `"200px"`). Default: `"10rem"`.
+   */
+  minColumnWidth?: string;
+
+  /** Accessible label for the grid (required unless `ariaLabelledby` is set). */
+  ariaLabel?: string;
+
+  /** Id of an external element that labels this grid. */
+  ariaLabelledby?: string;
+
+  /** Disables all items in the grid. */
+  disabled?: boolean;
+
+  /** Additional class names merged with `.cinder-choice-grid`. */
+  class?: string;
+
+  /** `ChoiceGridItem` children. */
+  children: Snippet;
+};
+
+/**
+ * Props for the `<ChoiceGridItem>` leaf component.
+ */
+export type ChoiceGridItemProps = {
+  /**
+   * The value this item represents. Used as the key for selection state,
+   * roving tabindex registration, and ARIA attributes.
+   */
+  value: string;
+
+  /**
+   * Feedback state for assessment / quiz usage. Defaults to `'neutral'`.
+   * Layout dimensions do NOT change across states (stable cell sizing guarantee).
+   */
+  state?: ChoiceGridItemState;
+
+  /** When true this item cannot be selected or focused. */
+  disabled?: boolean;
+
+  /** Additional class names merged with `.cinder-choice-grid-item`. */
+  class?: string;
+
+  /** Item content — label text, an icon, or richer markup. */
+  children: Snippet;
+};

package/src/components/choice-grid/choice-grid.variables.json

@@ -0,0 +1 @@
+[]

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

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

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

@@ -0,0 +1,22 @@
+import ChoiceGridItem from '../choice-grid-item/choice-grid-item.svelte';
+import './choice-grid.css';
+import ChoiceGridRoot from './choice-grid.svelte';
+
+/**
+ * `ChoiceGrid` is the parent compound component. It is also a namespace whose
+ * `Item` property exposes the compose-only leaf under its idiomatic name:
+ * `ChoiceGrid.Item`. The leaf remains importable individually from
+ * `@lostgradient/cinder/choice-grid-item`.
+ */
+const ChoiceGrid = Object.assign(ChoiceGridRoot, {
+  Item: ChoiceGridItem,
+});
+
+export default ChoiceGrid;
+export type {
+  ChoiceGridColumns,
+  ChoiceGridContext,
+  ChoiceGridItemState,
+  ChoiceGridProps,
+} from './choice-grid.types.ts';
+export { ChoiceGrid };

package/src/components/choice-grid-item/README.md

@@ -0,0 +1,41 @@
+# ChoiceGridItem
+
+Selectable answer tile used inside a ChoiceGrid; carries selected, disabled, correct, incorrect, and pending states without shifting cell dimensions.
+
+## Usage
+
+`ChoiceGridItem` is a compose-only leaf of [`ChoiceGrid`](../choice-grid/README.md).
+The idiomatic API is `ChoiceGrid.Item`, reached through the parent
+namespace — see the [ChoiceGrid README](../choice-grid/README.md#usage) for the
+composed snippet. The flat `@lostgradient/cinder/choice-grid-item` subpath remains exported for
+à-la-carte builds that import the leaf directly.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop       | Type                                                       | Required | Default | Description                                                                                                                                        |
+| ---------- | ---------------------------------------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `class`    | `string`                                                   | no       | —       | Additional class names merged with `.cinder-choice-grid-item`.                                                                                     |
+| `disabled` | `boolean`                                                  | no       | —       | When true this item cannot be selected or focused.                                                                                                 |
+| `state`    | `"neutral"` \| `"correct"` \| `"incorrect"` \| `"pending"` | no       | —       | Feedback state for assessment / quiz usage. Defaults to `'neutral'`. Layout dimensions do NOT change across states (stable cell sizing guarantee). |
+| `value`    | `string`                                                   | yes      | —       | The value this item represents. Used as the key for selection state, roving tabindex registration, and ARIA attributes.                            |
+| `children` | `(opaque)`                                                 | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature.                         |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->

package/src/components/choice-grid-item/choice-grid-item.css

@@ -0,0 +1,139 @@
+@layer cinder.tokens, cinder.foundation, cinder.components, cinder.utilities;
+
+@layer cinder.components {
+  /* ========================================
+   * CHOICE GRID ITEM — selectable answer tile
+   * ======================================== */
+
+  .cinder-choice-grid-item {
+    /* Stable sizing: min-height ensures cells never shrink when feedback state
+     * text/icons appear. Width is determined by the parent grid track. */
+    min-block-size: 4rem;
+
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    padding: var(--cinder-space-4) var(--cinder-space-3);
+    border-radius: var(--cinder-radius-lg);
+    border: 2px solid var(--cinder-border-muted);
+    background: var(--cinder-surface);
+    color: var(--cinder-text);
+    cursor: pointer;
+    user-select: none;
+    transition:
+      background 120ms ease,
+      border-color 120ms ease,
+      box-shadow 120ms ease;
+    outline: none; /* Focus ring provided via box-shadow below. */
+
+    /* Touch target: ensure at least 44px for mobile accessibility. */
+    touch-action: manipulation;
+  }
+
+  /* Item content wrapper — prevents the flex alignment from collapsing the
+   * children when they are shorter than the min-height baseline. */
+  .cinder-choice-grid-item__content {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--cinder-space-1);
+    font-size: var(--cinder-text-base);
+    font-weight: var(--cinder-font-medium);
+    line-height: var(--cinder-leading-snug);
+    pointer-events: none; /* Clicks bubble to the item div. */
+  }
+
+  /* ----------------------------------------
+   * Hover (non-touch devices only)
+   * ---------------------------------------- */
+
+  @media (hover: hover) {
+    /* Neutral hover only. Excludes selected and graded (correct/incorrect/
+     * pending) tiles so their accent/feedback colors aren't clobbered to a
+     * neutral raised fill on hover — those states own their own hover rules
+     * (or intentionally stay flat). */
+    .cinder-choice-grid-item:not([data-cinder-disabled]):not([data-cinder-selected]):not(
+        [data-cinder-state]
+      ):hover {
+      border-color: var(--cinder-border);
+      background: var(--cinder-surface-raised);
+    }
+  }
+
+  /* ----------------------------------------
+   * Focus ring
+   * ---------------------------------------- */
+
+  .cinder-choice-grid-item:focus-visible {
+    border-color: var(--cinder-accent);
+    box-shadow: var(--_cinder-focus-ring-shadow);
+  }
+
+  /* Forced Colors Mode — box-shadow rings are invisible; use a real outline. */
+  @media (forced-colors: active) {
+    .cinder-choice-grid-item:focus-visible {
+      outline: var(--cinder-ring-width) solid ButtonText;
+      outline-offset: 2px;
+    }
+  }
+
+  /* ----------------------------------------
+   * Selected state
+   * ---------------------------------------- */
+
+  /* Selected uses accent border + accent text with no filled background,
+   * matching the segmented-control convention. */
+  .cinder-choice-grid-item[data-cinder-selected] {
+    border-color: var(--cinder-accent);
+    color: var(--cinder-accent-text);
+  }
+
+  @media (hover: hover) {
+    /* Excludes graded tiles (a wrong pick can be both selected AND
+     * data-cinder-state) so hover doesn't flip their feedback border to accent
+     * — the feedback border must keep dominating on hover as it does at rest.
+     * Mirrors the neutral-hover guard above. */
+    .cinder-choice-grid-item[data-cinder-selected]:not([data-cinder-disabled]):not(
+        [data-cinder-state]
+      ):hover {
+      border-color: var(--cinder-accent-hover);
+    }
+  }
+
+  /* ----------------------------------------
+   * Disabled state
+   * ---------------------------------------- */
+
+  .cinder-choice-grid-item[data-cinder-disabled] {
+    cursor: not-allowed;
+    opacity: 0.45;
+  }
+
+  /* ----------------------------------------
+   * Feedback states — correct / incorrect / pending
+   * Dimensions are IDENTICAL to the neutral state (stable cell sizing guarantee).
+   * Only color / border / text change.
+   * ---------------------------------------- */
+
+  /* Correct */
+  .cinder-choice-grid-item[data-cinder-state='correct'] {
+    border-color: var(--cinder-color-success-border);
+    background: var(--cinder-color-success-bg);
+    color: var(--cinder-color-success-fg);
+  }
+
+  /* Incorrect */
+  .cinder-choice-grid-item[data-cinder-state='incorrect'] {
+    border-color: var(--cinder-color-danger-border);
+    background: var(--cinder-color-danger-bg);
+    color: var(--cinder-color-danger-fg);
+  }
+
+  /* Pending */
+  .cinder-choice-grid-item[data-cinder-state='pending'] {
+    border-color: var(--cinder-color-warning-border);
+    background: var(--cinder-color-warning-bg);
+    color: var(--cinder-color-warning-fg);
+  }
+}

package/src/components/choice-grid-item/choice-grid-item.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "value": {
+      "type": "string",
+      "description": "The value this item represents. Used as the key for selection state,\nroving tabindex registration, and ARIA attributes."
+    },
+    "state": {
+      "enum": ["neutral", "correct", "incorrect", "pending"],
+      "description": "Feedback state for assessment / quiz usage. Defaults to `'neutral'`.\nLayout dimensions do NOT change across states (stable cell sizing guarantee)."
+    },
+    "disabled": {
+      "type": "boolean",
+      "description": "When true this item cannot be selected or focused."
+    },
+    "class": {
+      "type": "string",
+      "description": "Additional class names merged with `.cinder-choice-grid-item`."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["value"],
+  "metadata": {
+    "unsupportedProps": [
+      {
+        "name": "children",
+        "reason": "function-or-snippet"
+      }
+    ]
+  }
+}

package/src/components/choice-grid-item/choice-grid-item.schema.ts

@@ -0,0 +1,38 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description:
+        'The value this item represents. Used as the key for selection state,\nroving tabindex registration, and ARIA attributes.',
+    },
+    state: {
+      enum: ['neutral', 'correct', 'incorrect', 'pending'],
+      description:
+        "Feedback state for assessment / quiz usage. Defaults to `'neutral'`.\nLayout dimensions do NOT change across states (stable cell sizing guarantee).",
+    },
+    disabled: {
+      type: 'boolean',
+      description: 'When true this item cannot be selected or focused.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-choice-grid-item`.',
+    },
+  },
+  additionalProperties: false,
+  required: ['value'],
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

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

@@ -0,0 +1,139 @@
+<script lang="ts" module>
+  /**
+   * @cinder
+   * @category form
+   * @status alpha
+   * @purpose Selectable answer tile used inside a ChoiceGrid; carries selected, disabled, correct, incorrect, and pending states without shifting cell dimensions.
+   * @tag form
+   * @tag selection
+   * @tag quiz
+   * @useWhen Composing individual answer choices inside a ChoiceGrid parent.
+   * @avoidWhen Used outside a ChoiceGrid — this leaf requires the parent context.
+   * @related choice-grid
+   */
+  export type {
+    ChoiceGridItemProps,
+    ChoiceGridItemState,
+  } from '../choice-grid/choice-grid.types.ts';
+</script>
+
+<script lang="ts">
+  import type { ChoiceGridItemProps } from './choice-grid-item.types.ts';
+  import { untrack } from 'svelte';
+  import { getChoiceGridContext } from '../choice-grid/choice-grid-context.ts';
+  import { classNames } from '../../utilities/class-names.ts';
+  import { rovingTabIndex } from '../../_internal/collection.ts';
+  import { devWarn } from '../../utilities/dev-warn.ts';
+
+  const ITEM_STATES = ['neutral', 'correct', 'incorrect', 'pending'] as const;
+
+  let {
+    value,
+    // Renamed off `state` to avoid svelte-check treating the bare identifier as
+    // the `$state` rune; the public prop name is still `state`.
+    state: stateProp = 'neutral',
+    disabled = false,
+    class: className,
+    children,
+  }: ChoiceGridItemProps = $props();
+
+  // Validate the public `state` against the allowed union so a plain-JS or
+  // dynamic value can't emit an unsupported `data-cinder-state`. Invalid values
+  // fall back to neutral (no data attribute) with a dev warning.
+  const feedbackState = $derived(
+    (ITEM_STATES as readonly string[]).includes(stateProp) ? stateProp : 'neutral',
+  );
+  $effect(() => {
+    if (!(ITEM_STATES as readonly string[]).includes(stateProp)) {
+      devWarn(
+        `ChoiceGridItem: invalid state "${String(stateProp)}". Expected one of ${ITEM_STATES.join(', ')}. Falling back to "neutral".`,
+      );
+    }
+  });
+
+  const context = getChoiceGridContext();
+
+  // `value` is the registry key and is fixed for the item's lifetime. Captured
+  // via untrack so a runtime mutation does not silently re-key the parent
+  // registry. EVERY ChoiceGrid interaction (selection, focusability, click)
+  // routes through `registeredValue`, never the live `value` prop, so a changing
+  // `value` can't desync the registry key from the selection/focus key. A
+  // changing `value` is unsupported and warned in development.
+  const registeredValue = untrack(() => value);
+  $effect(() => {
+    if (value !== registeredValue) {
+      devWarn(
+        `ChoiceGridItem: \`value\` changed from "${registeredValue}" to "${value}" after mount. ChoiceGridItem.value must be stable — give the item a fixed value (use {#key} to remount if the value must change). The grid keeps using the original value.`,
+      );
+    }
+  });
+
+  const isSelected = $derived(context.isSelected(registeredValue));
+  const isDisabled = $derived(disabled || context.disabled);
+  const isFocusable = $derived(context.isFocusable(registeredValue));
+  const tabIndex = $derived(rovingTabIndex(isFocusable));
+
+  // In single-select mode, the item acts as a radio button (role="radio").
+  // In multi-select mode, the item acts as a checkbox (role="checkbox").
+  const role = $derived(context.multiple ? 'checkbox' : 'radio');
+
+  let elementRef: HTMLElement | null = $state(null);
+
+  // Effect A — mount/unmount registration. Uses untrack to avoid creating a
+  // reactive cycle: register/unregister write to a reactive version counter,
+  // reading that inside an effect would self-trigger an infinite loop.
+  $effect(() => {
+    const el = elementRef;
+    if (!el) return;
+    untrack(() => {
+      context.register(registeredValue, el, isDisabled);
+    });
+    return () => {
+      untrack(() => {
+        context.unregister(registeredValue);
+      });
+    };
+  });
+
+  // Effect B — keep the parent's tracked disabled state in sync when this item's
+  // effective disabled state changes, so roving navigation and the focusable
+  // computation skip it. Reading isDisabled subscribes us; the write is untracked
+  // to stay out of the version-counter cycle.
+  $effect(() => {
+    const nextDisabled = isDisabled;
+    untrack(() => {
+      context.setItemDisabled(registeredValue, nextDisabled);
+    });
+  });
+
+  function handleClick(): void {
+    if (isDisabled) return;
+    context.select(registeredValue);
+  }
+
+  function handleKeydown(event: KeyboardEvent): void {
+    // Always forward to the parent so arrow/Home/End navigation works even when
+    // this tile is disabled (a disabled tile that holds focus must not trap the
+    // keyboard). The parent's `select()` already refuses to activate a disabled
+    // item, so Space/Enter on a disabled tile is a safe no-op.
+    context.handleKeydown(event);
+  }
+</script>
+
+<div
+  bind:this={elementRef}
+  {role}
+  aria-checked={isSelected}
+  aria-disabled={isDisabled || undefined}
+  tabindex={tabIndex}
+  class={classNames('cinder-choice-grid-item', className)}
+  data-cinder-selected={isSelected || undefined}
+  data-cinder-disabled={isDisabled || undefined}
+  data-cinder-state={feedbackState !== 'neutral' ? feedbackState : undefined}
+  onclick={handleClick}
+  onkeydown={handleKeydown}
+>
+  <span class="cinder-choice-grid-item__content">
+    {@render children()}
+  </span>
+</div>

package/src/components/choice-grid-item/choice-grid-item.types.ts

@@ -0,0 +1,30 @@
+import type { Snippet } from 'svelte';
+import type { ChoiceGridItemState } from '../choice-grid/choice-grid.types.ts';
+
+export type { ChoiceGridItemState };
+
+/**
+ * Props for the `<ChoiceGridItem>` leaf component.
+ */
+export type ChoiceGridItemProps = {
+  /**
+   * The value this item represents. Used as the key for selection state,
+   * roving tabindex registration, and ARIA attributes.
+   */
+  value: string;
+
+  /**
+   * Feedback state for assessment / quiz usage. Defaults to `'neutral'`.
+   * Layout dimensions do NOT change across states (stable cell sizing guarantee).
+   */
+  state?: ChoiceGridItemState;
+
+  /** When true this item cannot be selected or focused. */
+  disabled?: boolean;
+
+  /** Additional class names merged with `.cinder-choice-grid-item`. */
+  class?: string;
+
+  /** Item content — label text, an icon, or richer markup. */
+  children: Snippet;
+};

package/src/components/choice-grid-item/choice-grid-item.variables.json

@@ -0,0 +1 @@
+[]

package/src/components/choice-grid-item/choice-grid-item.variables.ts

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

package/src/components/choice-grid-item/index.ts

@@ -0,0 +1,6 @@
+import './choice-grid-item.css';
+import ChoiceGridItem from './choice-grid-item.svelte';
+
+export default ChoiceGridItem;
+export type { ChoiceGridItemProps, ChoiceGridItemState } from './choice-grid-item.types.ts';
+export { ChoiceGridItem };

package/src/components/click-away-listener/README.md

@@ -0,0 +1,50 @@
+# ClickAwayListener
+
+Headless utility that calls a function when the user clicks or taps outside a subtree.
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ClickAwayListener } from '@lostgradient/cinder/click-away-listener';
+</script>
+```
+
+## Guidance
+
+### Use When
+
+- Building a custom inline-edit field, custom dropdown, or any overlay that should close on outside interaction.
+
+### Avoid When
+
+- Using Popover, Dropdown, or Modal — those handle click-away internally.
+
+## Props
+
+<!-- generated:props:start -->
+
+| Prop          | Type       | Required | Default | Description                                                                                                                |
+| ------------- | ---------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `class`       | `string`   | no       | —       | Additional class names merged with the root element.                                                                       |
+| `enabled`     | `boolean`  | no       | —       | When false the document listener is detached and `onClickAway` is never called. Defaults to `true`.                        |
+| `children`    | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+| `onClickAway` | `(opaque)` | no       | —       | A function or snippet prop. Its shape is not captured by the JSON schema; see the component types for the exact signature. |
+
+<!-- generated:props:end -->
+
+## CSS Variables
+
+<!-- generated:variables:start -->
+
+This component does not declare any local CSS variables.
+
+<!-- generated:variables:end -->
+
+## Subcomponents
+
+<!-- generated:subcomponents:start -->
+
+None.
+
+<!-- generated:subcomponents:end -->