@lostgradient/cinder 0.6.0 → 0.7.0

package/src/components/table-row/table-row.svelte

@@ -0,0 +1,94 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { untrack } from 'svelte';
+import { tryGetTableContext, tryGetTableHeaderSelectionContext, tryGetTableSectionContext, } from '../table/table.context.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { devWarn } from '../../utilities/dev-warn.ts';
+let { class: className, children, selected, onselectedchange, selectionLabel, selectionDisabled, ...rest } = $props();
+const table = tryGetTableContext();
+const selectionEnabled = table?.selectionEnabled ?? false;
+const section = tryGetTableSectionContext();
+const headerSelection = tryGetTableHeaderSelectionContext();
+// Validate body rows when selection is enabled. This is a one-time mount-time
+// guard, so the prop reads are untracked.
+if (selectionEnabled && section === 'body') {
+    untrack(() => {
+        const hasDisabled = selectionDisabled === true;
+        if (!hasDisabled) {
+            // All three must be present — reject partial trios.
+            const hasSelected = selected !== undefined;
+            const hasOnChange = onselectedchange !== undefined;
+            const hasLabel = selectionLabel !== undefined;
+            if (!hasSelected || !hasOnChange || !hasLabel) {
+                throw new Error('[Cinder] TableRow: when Table.selectable is true, each body row must supply ' +
+                    'selected + onselectedchange + selectionLabel together, or set selectionDisabled={true}. ' +
+                    `Missing: ${[!hasSelected && 'selected', !hasOnChange && 'onselectedchange', !hasLabel && 'selectionLabel'].filter(Boolean).join(', ')}.`);
+            }
+        }
+    });
+}
+// Warn when a row is rendered directly under Table (no section context) with selection on.
+if (selectionEnabled && section === undefined) {
+    devWarn('[Cinder] TableRow: rendered outside TableHeader or TableBody while Table.selectable is true. ' +
+        'The leading selection cell will not be rendered.');
+}
+function handleSelectAllChange(event) {
+    const input = event.currentTarget;
+    headerSelection?.onselectall(input.checked);
+}
+function handleRowChange(event) {
+    const input = event.currentTarget;
+    onselectedchange?.(input.checked);
+}
+const shouldRenderHeaderSelectionCell = selectionEnabled && section === 'header' && headerSelection !== undefined;
+if (shouldRenderHeaderSelectionCell) {
+    headerSelection?.claimSelectionHeaderCell();
+}
+</script>
+
+<tr {...rest} class={classNames('cinder-table__row', className)}>
+  {#if shouldRenderHeaderSelectionCell && headerSelection}
+    <th scope="col" class="cinder-table__header-cell cinder-table__header-cell--selection">
+      <input
+        type="checkbox"
+        class="cinder-table__selection-checkbox"
+        checked={headerSelection.allSelected}
+        aria-label={headerSelection.selectAllLabel}
+        onchange={handleSelectAllChange}
+        {@attach (node: HTMLInputElement) => {
+          $effect(() => {
+            node.indeterminate = headerSelection.someSelected && !headerSelection.allSelected;
+          });
+        }}
+      />
+    </th>
+  {/if}
+  {#if selectionEnabled && section === 'body'}
+    {#if selectionDisabled}
+      <td
+        class="cinder-table__cell cinder-table__cell--selection cinder-table__cell--selection-disabled"
+      >
+        <input
+          type="checkbox"
+          class="cinder-table__selection-checkbox"
+          disabled
+          aria-label={selectionLabel ?? 'Selection not allowed for this row'}
+        />
+      </td>
+    {:else}
+      <td class="cinder-table__cell cinder-table__cell--selection">
+        <input
+          type="checkbox"
+          class="cinder-table__selection-checkbox"
+          checked={selected}
+          aria-label={selectionLabel}
+          onchange={handleRowChange}
+        />
+      </td>
+    {/if}
+  {/if}
+  {@render children()}
+</tr>

package/src/components/table-row/table-row.types.ts

@@ -0,0 +1,51 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+
+/**
+ * Discriminated union for row selection props.
+ *
+ * - Active branch: supply `selected` + `onselectedchange` + `selectionLabel`.
+ * - Opt-out branch: supply `selectionDisabled: true` — renders an empty alignment cell.
+ * - Inert branch: supply nothing — only valid when `Table.selectable` is false or
+ *   the row is inside `TableHeader`.
+ *
+ * Note: Svelte 5's `$props()` merges discriminated union branches into a flat
+ * object at destructuring time. TypeScript cannot narrow the active vs inert
+ * branch after destructuring. Runtime validation enforces the contract when
+ * `Table.selectable` is true — both `selected` and `selectionLabel` are
+ * required together and `onselectedchange` must be present.
+ */
+export type TableRowSelectionProps =
+  | {
+      /** Whether the row's selection checkbox is checked. Required in selectable tables alongside `onselectedchange` and `selectionLabel`. */
+      selected: boolean;
+      onselectedchange: (next: boolean) => void;
+      selectionLabel: string;
+      selectionDisabled?: false;
+    }
+  | {
+      /** When true, renders a disabled selection checkbox for this row, preventing selection while keeping the alignment cell. */
+      selectionDisabled: true;
+      selected?: undefined;
+      onselectedchange?: undefined;
+      /**
+       * Accessible name for the disabled selection checkbox. Provide a localised
+       * string to override the English default ("Selection not allowed for this
+       * row"). The library cannot localise on the consumer's behalf, so this is
+       * the seam for non-English applications or custom phrasing.
+       */
+      selectionLabel?: string;
+    }
+  | {
+      selected?: undefined;
+      onselectedchange?: undefined;
+      selectionLabel?: undefined;
+      selectionDisabled?: undefined;
+    };
+
+export type TableRowProps = Omit<HTMLAttributes<HTMLTableRowElement>, 'class'> & {
+  /** Additional class names merged with `.cinder-table__row`. */
+  class?: string;
+  /** Cell children (TableCell or TableHeaderCell). */
+  children: Snippet;
+} & TableRowSelectionProps;

package/src/components/table-row/table-row.variables.ts

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

package/src/components/tabs/index.ts

@@ -0,0 +1,24 @@
+import TabList from '../tab-list/tab-list.svelte';
+import TabPanel from '../tab-panel/tab-panel.svelte';
+import Tab from '../tab/tab.svelte';
+import './tabs.css';
+import TabsRoot from './tabs.svelte';
+
+/**
+ * `Tabs` is the parent compound component. It is also a namespace whose
+ * properties expose the compose-only leaves under their idiomatic names:
+ * `Tabs.List`, `Tabs.Trigger`, and `Tabs.Panel`. The leaves remain importable
+ * individually from `@lostgradient/cinder/tab-list`, `@lostgradient/cinder/tab`, and `@lostgradient/cinder/tab-panel`.
+ */
+const Tabs = Object.assign(TabsRoot, {
+  List: TabList,
+  Trigger: Tab,
+  Panel: TabPanel,
+});
+
+export default Tabs;
+export type { TabListProps } from '../tab-list/tab-list.types.ts';
+export type { TabPanelProps } from '../tab-panel/tab-panel.types.ts';
+export type { TabProps } from '../tab/tab.types.ts';
+export type { TabsContext, TabsOrientation, TabsProps } from './tabs.types.ts';
+export { Tab, TabList, TabPanel, Tabs };

package/src/components/tabs/tabs-context.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared context contract between Tabs (producer) and Tab, TabList, and
+ * TabPanel (consumers).
+ *
+ * Kept inside `tabs/` so the handles are co-located with the type definition
+ * in `tabs.types.ts` and reachable by the leaf components without being part
+ * of the package's public surface.
+ *
+ * The context is *required* — a Tab, TabList, or TabPanel outside a Tabs
+ * provider is a programmer error. The `getTabsContext` getter therefore throws
+ * (via Svelte 5's `createContext`) when no ancestor has called `setTabsContext`.
+ */
+
+import { createContext } from 'svelte';
+
+import type { TabsContext } from './tabs.types.ts';
+
+export type { TabsContext };
+
+const [getTabsContextStrict, setTabsContext] = createContext<TabsContext>();
+
+export { setTabsContext };
+
+/**
+ * Read the nearest enclosing `<Tabs>` context. Throws when no `<Tabs>`
+ * ancestor exists — using Tab, TabList, or TabPanel outside a provider is a
+ * programmer error.
+ */
+export const getTabsContext = getTabsContextStrict;

package/src/components/tabs/tabs.schema.ts

@@ -0,0 +1,49 @@
+import type { ComponentSchema } from '../../schema-types';
+
+const schema = {
+  $schema: 'https://json-schema.org/draft/2020-12/schema',
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description: 'Bound active tab value.',
+    },
+    orientation: {
+      enum: ['horizontal', 'vertical'],
+      description: 'Layout orientation. Affects which arrow keys move between tabs.',
+    },
+    fill: {
+      type: 'boolean',
+      description:
+        'Fill the available space when Tabs is placed inside a bounded flex parent,\nletting the active TabPanel occupy the remaining height.',
+    },
+    activateOnFocus: {
+      type: 'boolean',
+      description:
+        'When true (default for horizontal), focusing a tab also activates it\n(the panel updates immediately). Vertical defaults to manual activation\n— the user moves focus with arrows, then presses Enter or Space.',
+    },
+    class: {
+      type: 'string',
+      description: 'Additional class names merged with `.cinder-tabs`.',
+    },
+  },
+  additionalProperties: false,
+  metadata: {
+    unsupportedProps: [
+      {
+        name: 'children',
+        reason: 'function-or-snippet',
+        required: true,
+        description: 'Tab and TabPanel children.',
+      },
+      {
+        name: 'onValueChange',
+        reason: 'function-or-snippet',
+        description:
+          'Intercept a proposed tab value before the bindable value is written. Return a replacement value to transform it.',
+      },
+    ],
+  },
+} satisfies ComponentSchema;
+
+export default schema as ComponentSchema;

package/src/components/tabs/tabs.svelte

@@ -0,0 +1,216 @@
+<script lang="ts" module>
+export {};
+</script>
+
+<script lang="ts">
+import { setTabsContext } from './tabs-context.ts';
+import { handleRovingKeydown, isRovingKey } from '../../utilities/roving-tabindex.ts';
+import { classNames } from '../../utilities/class-names.ts';
+import { commitValue } from '../../utilities/value-change.ts';
+const baseId = $props.id();
+let { value = $bindable(''), onValueChange, orientation = 'horizontal', fill = false, activateOnFocus, class: className, children, } = $props();
+// Default activation behavior follows the WAI-ARIA tabs pattern: horizontal
+// tablists activate on focus (left/right are dedicated to tab navigation),
+// vertical tablists activate on Enter/Space (down/up commonly belong to the
+// panel content too).
+const effectiveActivateOnFocus = $derived(activateOnFocus ?? orientation === 'horizontal');
+/**
+ * Registry of tab buttons keyed by their `value`. Order of registration
+ * determines navigation order — children register in mount order.
+ *
+ * In-place mutation of an entry's `disabled` field does not trigger Svelte
+ * reactivity on its own, so every mutation path also bumps `version`. Any
+ * `$derived` that reads from the registry must also read `version` to
+ * re-run when entries change.
+ */
+const buttons = new Map();
+let version = $state(0);
+const focusableValue = $derived.by(() => {
+    void version;
+    for (const [registeredValue, entry] of buttons) {
+        if (!entry.disabled)
+            return registeredValue;
+    }
+    return undefined;
+});
+function focusValue(target) {
+    const entry = buttons.get(target);
+    if (entry)
+        entry.button.focus();
+}
+function resolveFocusedIndex(active) {
+    const entries = [...buttons.values()];
+    return entries.findIndex(({ button }) => button === active);
+}
+function readActiveElement(event) {
+    // Prefer the event target if it is itself a registered tab button —
+    // that is the most local, most reliable signal. Fall back to
+    // ownerDocument.activeElement when the target is not a tab (e.g., when
+    // the handler is attached at a higher level).
+    const target = event.target instanceof HTMLElement ? event.target : null;
+    if (target) {
+        for (const { button } of buttons.values()) {
+            if (button === target)
+                return target;
+        }
+    }
+    const currentTarget = event.currentTarget instanceof HTMLElement ? event.currentTarget : null;
+    return currentTarget?.ownerDocument.activeElement ?? null;
+}
+function resolveStartingIndex(event) {
+    const entries = [...buttons.values()];
+    if (entries.length === 0)
+        return -1;
+    const focused = resolveFocusedIndex(readActiveElement(event));
+    if (focused !== -1)
+        return focused;
+    // Fallback: active tab if enabled, else first enabled. Returns -1 only
+    // when every entry is disabled — the caller's guard handles that case.
+    const order = [...buttons.keys()];
+    const activeIdx = order.indexOf(value);
+    if (activeIdx !== -1 && !entries[activeIdx]?.disabled)
+        return activeIdx;
+    return entries.findIndex((entry) => !entry.disabled);
+}
+/**
+ * Whether the given key is one this orientation handles. Home/End are
+ * always relevant; Arrow keys are orientation-specific. Mirrors the
+ * `horizontal`/`vertical` filtering inside `handleRovingKeydown` so the
+ * all-disabled no-op path does not preventDefault on keys we would
+ * otherwise have let bubble (e.g., ArrowUp on a horizontal tablist).
+ */
+function isOrientedKey(key, isHorizontal) {
+    if (!isRovingKey(key))
+        return false;
+    if (key === 'Home' || key === 'End')
+        return true;
+    if (isHorizontal)
+        return key === 'ArrowLeft' || key === 'ArrowRight';
+    return key === 'ArrowUp' || key === 'ArrowDown';
+}
+function handleKeydown(event) {
+    const entries = [...buttons.values()];
+    const order = [...buttons.keys()];
+    if (event.key === 'Enter' || event.key === ' ') {
+        // Manual activation: activate the focused tab if it is enabled.
+        const focused = resolveFocusedIndex(readActiveElement(event));
+        if (focused === -1)
+            return;
+        if (entries[focused]?.disabled !== false)
+            return;
+        const focusedValue = order[focused];
+        if (focusedValue === undefined)
+            return;
+        event.preventDefault();
+        commitValue(focusedValue, onValueChange, (next) => {
+            value = next;
+        });
+        return;
+    }
+    const isHorizontal = orientation === 'horizontal';
+    if (!isOrientedKey(event.key, isHorizontal))
+        return;
+    if (entries.length === 0)
+        return;
+    const currentIndex = resolveStartingIndex(event);
+    if (currentIndex === -1) {
+        // All entries disabled — prevent default so arrow/Home/End do not leak
+        // page scroll, but otherwise no-op.
+        event.preventDefault();
+        return;
+    }
+    const nextIdx = handleRovingKeydown(event, currentIndex, entries.length, {
+        isDisabled: (i) => entries[i]?.disabled ?? false,
+        horizontal: isHorizontal,
+        vertical: !isHorizontal,
+    });
+    if (nextIdx === null)
+        return;
+    event.preventDefault();
+    if (nextIdx === currentIndex)
+        return;
+    const nextValue = order[nextIdx];
+    if (nextValue === undefined)
+        return;
+    focusValue(nextValue);
+    if (effectiveActivateOnFocus) {
+        commitValue(nextValue, onValueChange, (next) => {
+            value = next;
+        });
+    }
+}
+setTabsContext({
+    get value() {
+        return value;
+    },
+    get orientation() {
+        return orientation;
+    },
+    get activateOnFocus() {
+        return effectiveActivateOnFocus;
+    },
+    get baseId() {
+        return baseId;
+    },
+    select(next) {
+        commitValue(next, onValueChange, (nextValue) => {
+            value = nextValue;
+        });
+    },
+    isActive(candidate) {
+        return value === candidate;
+    },
+    register(target, button, disabled = false) {
+        const existing = buttons.get(target);
+        if (existing) {
+            existing.button = button;
+            existing.disabled = disabled;
+        }
+        else {
+            buttons.set(target, { button, disabled });
+        }
+        version += 1;
+    },
+    unregister(target) {
+        if (buttons.delete(target)) {
+            version += 1;
+        }
+    },
+    setDisabled(target, disabled) {
+        const existing = buttons.get(target);
+        if (!existing)
+            return;
+        if (existing.disabled === disabled)
+            return;
+        existing.disabled = disabled;
+        version += 1;
+    },
+    isFocusable(candidate) {
+        // Force reads of every reactive input up front, regardless of which
+        // branch the predicate ultimately takes. The calling $derived in
+        // tab.svelte needs to subscribe to `value` AND `version` for any
+        // possible code path — early-returning before reading one of them
+        // would leave the derived under-subscribed and stale when only the
+        // unread input changes. Must be called inside a $derived/$effect.
+        void value;
+        void version;
+        const selectedEntry = buttons.get(value);
+        const selectedIsEnabled = selectedEntry !== undefined && !selectedEntry.disabled;
+        const entry = buttons.get(candidate);
+        if (!entry || entry.disabled)
+            return false;
+        if (selectedIsEnabled)
+            return value === candidate;
+        return focusableValue === candidate;
+    },
+    handleKeydown,
+});
+</script>
+
+<div
+  class={classNames('cinder-tabs', className)}
+  data-cinder-orientation={orientation}
+  data-cinder-fill={fill ? '' : undefined}
+>
+  {@render children()}
+</div>

package/src/components/tabs/tabs.types.ts

@@ -0,0 +1,80 @@
+import type { Snippet } from 'svelte';
+/** Orientation of the tab list. */
+export type TabsOrientation = 'horizontal' | 'vertical';
+/**
+ * Shape of the context object provided to Tab and TabPanel children.
+ *
+ * The contract is split between selection (the bound `value`, exposed via
+ * `select` and `isActive`) and roving-tabindex focus management (`register`,
+ * `unregister`, `setDisabled`, `isFocusable`). Decoupling lets a
+ * selected-but-disabled tab keep `aria-selected="true"` while the tab stop
+ * (`tabindex="0"`) shifts to the first enabled tab — so the tablist always
+ * has a reachable entry point.
+ */
+export type TabsContext = {
+  /** The currently active tab value. */
+  readonly value: string;
+  /** Layout orientation, forwarded to TabList for `aria-orientation`. */
+  readonly orientation: TabsOrientation;
+  /** Whether focus movement also activates a tab (per WAI-ARIA pattern). */
+  readonly activateOnFocus: boolean;
+  /**
+   * Per-root base id used to namespace tab and panel ids so that two Tabs
+   * instances sharing the same tab value do not produce duplicate DOM ids.
+   * Derived ids take the form `${baseId}-tab-${value}` and
+   * `${baseId}-panel-${value}`.
+   */
+  readonly baseId: string;
+  /** Activate a tab by value. */
+  select: (next: string) => void;
+  /** True when `candidate` is the active tab. */
+  isActive: (candidate: string) => boolean;
+  /**
+   * Announce a tab to the parent registry on mount. Registry order is the
+   * navigation order. Re-registering an existing value updates its button
+   * reference in place; insertion order is preserved. The `disabled` argument
+   * seeds the registry entry's initial state so first paint reflects the
+   * tab's current `disabled` prop without waiting for `setDisabled` to run.
+   */
+  register: (value: string, button: HTMLButtonElement, disabled?: boolean) => void;
+  /** Remove a tab from the registry on unmount. */
+  unregister: (value: string) => void;
+  /**
+   * Sync the disabled state for a registered tab. Safe no-op when called
+   * before `register` has run (e.g., during the first paint of a Tab whose
+   * disabled-sync effect fires before its registration effect).
+   */
+  setDisabled: (value: string, disabled: boolean) => void;
+  /**
+   * Whether `candidate` should currently hold `tabindex="0"`. Reads
+   * reactive registry state, so callers MUST invoke this inside a
+   * `$derived` or `$effect` to stay current — a plain assignment captures
+   * a stale snapshot.
+   */
+  isFocusable: (candidate: string) => boolean;
+  /** Tab buttons forward `keydown` here for shared arrow-key navigation. */
+  handleKeydown: (event: KeyboardEvent) => void;
+};
+export type TabsProps = {
+  /** Bound active tab value. */
+  value?: string;
+  /** Intercept a proposed tab value before the bindable value is written. Return a replacement value to transform it. */
+  onValueChange?: (next: string) => string | void;
+  /** Layout orientation. Affects which arrow keys move between tabs. */
+  orientation?: TabsOrientation;
+  /**
+   * Fill the available space when Tabs is placed inside a bounded flex parent,
+   * letting the active TabPanel occupy the remaining height.
+   */
+  fill?: boolean;
+  /**
+   * When true (default for horizontal), focusing a tab also activates it
+   * (the panel updates immediately). Vertical defaults to manual activation
+   * — the user moves focus with arrows, then presses Enter or Space.
+   */
+  activateOnFocus?: boolean;
+  /** Additional class names merged with `.cinder-tabs`. */
+  class?: string;
+  /** Tab and TabPanel children. */
+  children: Snippet;
+};

package/src/components/tabs/tabs.variables.ts

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

package/src/components/tag-input/index.ts

@@ -0,0 +1,6 @@
+import './tag-input.css';
+import TagInput from './tag-input.svelte';
+
+export default TagInput;
+export type { TagInputProps } from './tag-input.types.ts';
+export { TagInput };