@reddb-io/ui-kit 0.3.4 → 0.3.6

package/vendor/ds/kits/base/src/Stack.svelte

@@ -0,0 +1,57 @@
+<!--
+  Token-backed flow that inherits the nearest Density scope. The Stack owns the
+  rhythm between its own children (ADR 0024); its direction, alignment and
+  wrapping are props, so a caller never overrides the flow with classes.
+-->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import {
+    stack,
+    type StackAlign,
+    type StackDirection,
+    type StackGap,
+    type StackJustify,
+  } from "./stack.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /**
+     * Space between children. Each value names a Density-owned role: the
+     * component tier (`sm`, `md`, `lg`), the layout tier (`layout-sm`,
+     * `layout-md`, `layout-lg`) or the section tier (`section`), or `none` for contiguous children. Defaults to `layout-md`.
+     */
+    gap?: StackGap;
+    /** The main axis: `column` (the default) or `row`. */
+    direction?: StackDirection;
+    /** Cross-axis alignment. Defaults to `stretch`. */
+    align?: StackAlign;
+    /** Main-axis distribution. Defaults to `start`. */
+    justify?: StackJustify;
+    /** Wrap children onto new lines when they run out of room. */
+    wrap?: boolean;
+    /** Extra classes merged onto the flow. */
+    class?: string;
+    /** The items the flow arranges, spaced by `gap`. */
+    children?: Snippet;
+  }
+
+  const {
+    gap = "layout-md",
+    direction = "column",
+    align = "stretch",
+    justify = "start",
+    wrap = false,
+    class: className,
+    children,
+    ...rest
+  }: Props = $props();
+</script>
+
+<div
+  {...(rest as Record<string, unknown>)}
+  data-stack
+  data-stack-direction={direction}
+  class={stack({ gap, direction, align, justify, wrap, class: className })}
+>
+  {@render children?.()}
+</div>

package/vendor/ds/kits/base/src/Statistic.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+  import type { HTMLAttributes } from "svelte/elements";
+  import DescriptionList from "./DescriptionList.svelte";
+  import { statistic } from "./statistic.variants";
+
+  import { valuePresentation } from "./core/operational-motion";
+  interface Props extends Omit<HTMLAttributes<HTMLDListElement>, "class"> {
+    /** Caller-owned name for the measured value. */
+    label: string;
+    /** Machine-readable scalar; formatting changes only its visible form. */
+    value: number | string;
+    /**
+     * Formats `value` for the visible reading; the machine-readable `data` value is unchanged.
+     * Defaults to `String`.
+     */
+    formatValue?: (value: number | string) => string;
+    /** Optional supporting text shown beside the value, such as a period or comparison. */
+    description?: string;
+    /** Brief paint-only feedback on value changes; semantic readings update immediately. */
+    animate?: boolean;
+    /** Extra classes, merged over the root slot's own. */
+    class?: string;
+  }
+
+  let {
+    label,
+    value,
+    formatValue = String,
+    description,
+    animate = false,
+    class: className,
+    ...rest
+  }: Props = $props();
+  const slots = $derived(statistic());
+  const formatted = $derived(formatValue(value));
+  function feedback(
+    node: HTMLDataElement,
+    initial: { value: number | string; enabled: boolean },
+  ) {
+    const p = valuePresentation(node);
+    p.update(initial.value, initial.enabled);
+    return {
+      update(next: { value: number | string; enabled: boolean }) {
+        p.update(next.value, next.enabled);
+      },
+      destroy() {
+        p.destroy();
+      },
+    };
+  }
+</script>
+
+{#snippet detail()}
+  <span class={slots.detail()}>
+    <data
+      use:feedback={{ value, enabled: animate }}
+      data-statistic-value
+      value={String(value)}
+      class={slots.value()}>{formatted}</data
+    >
+    {#if description !== undefined}
+      <span data-statistic-description class={slots.description()}
+        >{description}</span
+      >
+    {/if}
+  </span>
+{/snippet}
+
+<DescriptionList
+  {...rest as Record<string, unknown>}
+  data-statistic
+  items={[{ term: label, detail }]}
+  class={slots.root({ class: className })}
+/>

package/vendor/ds/kits/base/src/StatusIndicator.svelte

@@ -0,0 +1,52 @@
+<!--
+  StatusIndicator — a Base Primitive for status at a glance.
+
+  Colour decorates the status; it never carries it. The required label always
+  remains in the document, and showLabel only decides whether sighted readers
+  see that text beside the decorative mark.
+-->
+<script lang="ts">
+  import type { HTMLAttributes } from "svelte/elements";
+  import { warnDeprecated } from "./deprecation";
+  import { statusIndicator } from "./status-indicator.variants";
+  import type { Tone } from "./tone";
+
+  interface Props extends Omit<HTMLAttributes<HTMLSpanElement>, "class"> {
+    /** Consumer-owned status text; this is the semantic carrier. */
+    label: string;
+    /** What the status means: the shared tone vocabulary (ADR 0026). Defaults to `neutral`. */
+    tone?: Tone;
+    /** @deprecated Renamed `tone` (ADR 0026); removed next release. */
+    status?: Tone;
+    /** Draw the label beside the mark. Hidden labels remain screen-reader text. */
+    showLabel?: boolean;
+    /** Extra classes, merged over the root slot. */
+    class?: string;
+  }
+
+  const {
+    label,
+    tone,
+    status,
+    showLabel = true,
+    class: className,
+    ...rest
+  }: Props = $props();
+  const resolvedTone = $derived<Tone>(tone ?? status ?? "neutral");
+  const slots = $derived(statusIndicator({ tone: resolvedTone, labelled: showLabel }));
+
+  $effect(() => {
+    if (status !== undefined) warnDeprecated("StatusIndicator", `status="${status}"`, `tone="${status}"`);
+  });
+</script>
+
+<span
+  {...rest}
+  class={slots.root({ class: className })}
+  data-status-indicator
+  data-tone={resolvedTone}
+  data-status={resolvedTone}
+>
+  <span class={slots.mark()} data-status-mark aria-hidden="true"></span>
+  <span class={slots.label()} data-status-label>{label}</span>
+</span>

package/vendor/ds/kits/base/src/Steps.svelte

@@ -0,0 +1,51 @@
+<script module lang="ts">
+  export type { StepItem, StepState } from "./core/steps";
+</script>
+
+<script lang="ts">
+  import type { StepItem, StepState } from "./core/steps";
+  import Link from "./Link.svelte";
+  import { steps } from "./steps.variants";
+
+  interface Props {
+    /**
+     * The steps in order; each has an `id`, a `label`, a `state` of `complete`, `current` or
+     * `upcoming`, and an optional `href` that makes a non-current step a link.
+     */
+    items: readonly StepItem[];
+    /** Accessible name of the navigation landmark; defaults to `Progress`. */
+    label?: string;
+    /** Extra classes, merged over the root slot's own. */
+    class?: string;
+  }
+
+  let { items, label = "Progress", class: className }: Props = $props();
+  const styles = steps();
+</script>
+
+<nav aria-label={label} data-steps class={styles.root({ class: className })}>
+  <ol class={styles.list()}>
+    {#each items as item, index (item.id)}
+      <li data-step-state={item.state} class={styles.item()}>
+        {#if item.state === "current"}
+          <span aria-current="step" class={styles.content()}>
+            <span aria-hidden="true" class={styles.marker()}>{index + 1}</span>
+            <span class={styles.current()}>{item.label}</span>
+          </span>
+        {:else if item.href !== undefined}
+          <Link href={item.href} class={styles.content()}>
+            <span aria-hidden="true" class={styles.marker()}>{item.state === "complete" ? "✓" : index + 1}</span>
+            <span>{item.label}</span>
+            {#if item.state === "complete"}<span class={styles.status()}>Completed</span>{/if}
+          </Link>
+        {:else}
+          <span class={styles.content()}>
+            <span aria-hidden="true" class={styles.marker()}>{item.state === "complete" ? "✓" : index + 1}</span>
+            <span>{item.label}</span>
+            {#if item.state === "complete"}<span class={styles.status()}>Completed</span>{/if}
+          </span>
+        {/if}
+      </li>
+    {/each}
+  </ol>
+</nav>

package/vendor/ds/kits/base/src/Swap.svelte

@@ -0,0 +1,85 @@
+<!-- Two caller-owned faces over the canonical ToggleButton pressed contract. -->
+<script lang="ts">
+  import { untrack, type Snippet } from "svelte";
+  import type { HTMLButtonAttributes } from "svelte/elements";
+  import ToggleButton from "./ToggleButton.svelte";
+  import { warnDeprecated } from "./deprecation";
+  import { swap, swapFace } from "./swap.variants";
+
+  interface Props extends Omit<HTMLButtonAttributes, "aria-pressed" | "children" | "class" | "onclick" | "onchange" | "type"> {
+    /**
+     * Stable accessible name; changing faces never changes the control's purpose. A face that shows
+     * words shows words of `label`, in order, ideally its first ones (WCAG 2.5.3, Label in Name):
+     * swap a glyph or an emphasis, not the words. A control whose words change is a Button.
+     */
+    label: string;
+    /** Which face is visible, bindable for controlled consumers. */
+    swapped?: boolean;
+    /** Initial uncontrolled face; later changes do not replace the user's choice. */
+    defaultSwapped?: boolean;
+    /** Content shown in the initial, unpressed state. Defaults to `label`. */
+    off?: Snippet;
+    /** Content shown in the swapped, pressed state. Defaults to `label`. */
+    on?: Snippet;
+    /** Disables the control, so activation neither swaps the face nor reports a change. */
+    disabled?: boolean;
+    /**
+     * Extra classes merged onto the underlying ToggleButton, over the Swap's own one-cell layout.
+     */
+    class?: string;
+    /** Called with the click event on activation, before `onswappedchange`. */
+    onclick?: HTMLButtonAttributes["onclick"];
+    /** Reports the next state after activation (ADR 0026: `on<state>change` for `bind:<state>`). */
+    onswappedchange?: (swapped: boolean) => void;
+    /** @deprecated Renamed `onswappedchange` (ADR 0026); removed next release. */
+    onchange?: (swapped: boolean) => void;
+  }
+
+  let {
+    label,
+    swapped = $bindable(),
+    defaultSwapped = false,
+    off,
+    on,
+    disabled = false,
+    class: className,
+    onclick,
+    onswappedchange,
+    onchange,
+    ...rest
+  }: Props = $props();
+
+  const initial = untrack(() => defaultSwapped);
+  let local = $state(initial);
+  const current = $derived(swapped ?? local);
+
+  function activate(event: MouseEvent): void {
+    const next = current;
+    onclick?.(event as Parameters<NonNullable<HTMLButtonAttributes["onclick"]>>[0]);
+    onswappedchange?.(next);
+    onchange?.(next);
+  }
+
+  $effect(() => {
+    if (onchange) warnDeprecated("Swap", "onchange", "onswappedchange");
+  });
+</script>
+
+<ToggleButton
+  {...rest}
+  {label}
+  {disabled}
+  pressed={current}
+  onpressedchange={next => { local = next; swapped = next; }}
+  class={swap({ class: className })}
+  data-swap
+  onclick={activate}
+>
+  <span class={swapFace()}>
+  {#if current}
+    {#if on}{@render on()}{:else}{label}{/if}
+  {:else}
+    {#if off}{@render off()}{:else}{label}{/if}
+  {/if}
+  </span>
+</ToggleButton>

package/vendor/ds/kits/base/src/Switch.svelte

@@ -0,0 +1,91 @@
+<!-- A visibly named native binary input exposed with switch semantics. -->
+<script lang="ts">
+  import { afterFormReset } from "./core/native-controls";
+  import { untrack } from "svelte";
+  import type { HTMLInputAttributes } from "svelte/elements";
+  import Field from "./Field.svelte";
+  import { switchControl } from "./switch.variants";
+
+  interface Props extends Omit<HTMLInputAttributes, "checked" | "children" | "class" | "id" | "required" | "role" | "type"> {
+    /** The required visible accessible name supplied through Field. */
+    label: string;
+    /** Supporting text announced with the switch. */
+    help?: string;
+    /** Current validation error announced with the switch. */
+    error?: string;
+    /** Makes the requirement visible and native. */
+    required?: boolean;
+    /** Explicit control id; otherwise Field supplies a stable generated one. */
+    id?: string;
+    /** Whether it is checked. Bindable: `bind:checked` follows every toggle. */
+    checked?: boolean;
+    /**
+     * Called with the next checked state after every toggle (ADR 0026). The
+     * native `onchange` still receives the Event.
+     */
+    oncheckedchange?: (checked: boolean) => void;
+    /** The native input element for rare imperative access. */
+    ref?: HTMLInputElement;
+    /** Extra classes merged onto the native switch. */
+    class?: string;
+    /** Extra classes merged onto the containing Field. */
+    fieldClass?: string;
+  }
+
+  let {
+    label,
+    help,
+    error,
+    required = false,
+    id,
+    ref = $bindable(),
+    checked = $bindable(),
+    class: className,
+    fieldClass,
+    onchange,
+    oncheckedchange,
+    ...rest
+  }: Props = $props();
+
+  // The element owns its checked state; `checked` follows every toggle and is
+  // written back only when a caller supplies one (see Input).
+  const initial = untrack(() => checked ?? rest.defaultChecked);
+  let element: HTMLInputElement | undefined = $state();
+
+  function handleChange(event: Event & { currentTarget: EventTarget & HTMLInputElement }): void {
+    const next = event.currentTarget.checked;
+    checked = next;
+    onchange?.(event);
+    oncheckedchange?.(next);
+  }
+
+  $effect(() => {
+    const next = checked;
+    if (!element || next === undefined || next === null) return;
+    if (next !== element.checked) element.checked = next;
+  });
+
+  $effect(() => {
+    if (ref !== element) ref = element;
+  });
+  $effect(() => {
+    rest.form;
+    return afterFormReset(element?.form, () => { if (element) checked = element.checked; });
+  });
+</script>
+
+<Field {label} {help} {error} {required} {id} layout="inline" class={fieldClass}>
+  {#snippet children(control)}
+    <input
+      {...rest}
+      {...control}
+      defaultChecked={initial}
+      checked={initial}
+      bind:this={element}
+      onchange={handleChange}
+      type="checkbox"
+      role="switch"
+      class={switchControl({ class: className })}
+    />
+  {/snippet}
+</Field>

package/vendor/ds/kits/base/src/Table.svelte

@@ -0,0 +1,96 @@
+<!-- Native tabular relationships over caller-owned labels and data. -->
+<script module lang="ts">
+  export type { TableCellValue, TableColumn, TableRow, TableCellContext } from "./core/table";
+</script>
+
+<script lang="ts">
+  import type { TableCellValue, TableColumn, TableRow, TableCellContext } from "./core/table";
+  import type { Snippet } from "svelte";
+  import type { HTMLTableAttributes } from "svelte/elements";
+  import { table as tableAppearance } from "./table.variants";
+
+  const uid = $props.id();
+
+  interface Props extends Omit<HTMLTableAttributes, "children" | "class"> {
+    /** Required visible name for the table. */
+    caption: string;
+    /** Columns rendered in this order with native column-header scope. */
+    columns: readonly TableColumn[];
+    /** Caller-owned tabular values. */
+    rows: readonly TableRow[];
+    /** Column key whose body cells are native row headers. Defaults to the first column. */
+    rowHeader?: string;
+    /** Caller-owned rendering for each cell; native cell relationships remain Table-owned. */
+    cell?: Snippet<[TableCellContext]>;
+    /** Extra classes merged onto the native table. */
+    class?: string;
+    /** Extra classes merged onto the responsive scroll region. */
+    containerClass?: string;
+    /** Extra classes merged onto the `<caption>`, over its own. */
+    captionClass?: string;
+    /** Extra classes merged onto the `<thead>`, over its own. */
+    headerClass?: string;
+    /** Extra classes merged onto every row, the header row and each body row. */
+    rowClass?: string;
+    /** Extra classes merged onto each column header cell. */
+    headClass?: string;
+    /** Extra classes merged onto each body cell, row-header cells included. */
+    cellClass?: string;
+  }
+
+  let {
+    caption,
+    columns,
+    rows,
+    rowHeader = columns[0]?.key,
+    cell,
+    class: className,
+    containerClass,
+    captionClass,
+    headerClass,
+    rowClass,
+    headClass,
+    cellClass,
+    ...rest
+  }: Props = $props();
+  const captionId = `${uid}-caption`;
+  const styles = tableAppearance();
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_tabindex (wide tables need a keyboard-scrollable region.) -->
+<div
+  data-table-scroll
+  role="region"
+  aria-labelledby={captionId}
+  tabindex="0"
+  class={styles.root({ class: containerClass })}
+>
+  <table {...rest} data-table class={styles.table({ class: className })}>
+    <caption id={captionId} class={styles.caption({ class: captionClass })}>{caption}</caption>
+    <thead class={styles.header({ class: headerClass })}>
+      <tr class={styles.row({ class: rowClass })}>
+        {#each columns as column (column.key)}
+          <th scope="col" class={styles.head({ class: headClass })}>{column.header}</th>
+        {/each}
+      </tr>
+    </thead>
+    <tbody>
+      {#each rows as row, rowIndex}
+        <tr class={styles.row({ class: rowClass })}>
+          {#each columns as column (column.key)}
+            {@const value = row[column.key]}
+            {#if column.key === rowHeader}
+              <th scope="row" class={styles.cell({ class: cellClass })}>
+                {#if cell}{@render cell({ column, row, value, rowIndex })}{:else}{value}{/if}
+              </th>
+            {:else}
+              <td class={styles.cell({ class: cellClass })}>
+                {#if cell}{@render cell({ column, row, value, rowIndex })}{:else}{value}{/if}
+              </td>
+            {/if}
+          {/each}
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>

package/vendor/ds/kits/base/src/Tabs.svelte

@@ -0,0 +1,131 @@
+<!-- Accessible tab selection and keyboard navigation over caller-owned panel content. -->
+<script lang="ts">
+  import type { TabsContract } from "./core/contracts/tabs";
+  import { tick, type Snippet } from "svelte";
+  import { Tabs as Bits } from "bits-ui";
+  import Button from "./Button.svelte";
+  import { warnDeprecated } from "./deprecation";
+  import { tabs, type TabItem } from "./tabs.variants";
+
+  interface Props extends TabsContract {
+    /** Called with the newly selected value (ADR 0026's value dialect). */
+    onvaluechange?: (value: string) => void;
+    /** @deprecated Renamed `onvaluechange` (ADR 0026); removed next release. */
+    onchange?: (value: string) => void;
+    /**
+     * Panel content, rendered once per item inside that tab's panel; receives `{ value }`, the
+     * tab's value, to choose what to show.
+     */
+    children?: Snippet<[{ value: string }]>;
+    /** Extra classes, merged over the root slot's own. */
+    class?: string;
+  }
+
+  let {
+    label,
+    items,
+    value = $bindable(""),
+    orientation = "horizontal",
+    disabled = false,
+    followHash = false,
+    onvaluechange,
+    onchange,
+    children,
+    class: className,
+    listClass,
+    triggerClass,
+    contentClass,
+  }: Props = $props();
+
+  const styles = tabs();
+  const ownerId = $props.id();
+  let root = $state<HTMLElement>();
+  const selected = $derived(
+    items.some((item) => !item.disabled && item.value === value)
+      ? value
+      : (items.find((item) => !item.disabled)?.value ?? ""),
+  );
+
+  function select(next: string): void {
+    if (next === selected) return;
+    value = next;
+    onvaluechange?.(next);
+    onchange?.(next);
+  }
+
+  $effect(() => {
+    if (onchange) warnDeprecated("Tabs", "onchange", "onvaluechange");
+  });
+
+  async function selectFragment(): Promise<void> {
+    if (!root || !location.hash) return;
+    const targetId = decodeURIComponent(location.hash.slice(1));
+    const target = document.getElementById(targetId);
+    if (!target || !root.contains(target)) return;
+    const panel = [...root.querySelectorAll<HTMLElement>("[data-tabs-owner]")]
+      .filter((candidate) => candidate.dataset.tabsOwner === ownerId)
+      .find((candidate) => candidate.contains(target));
+    const next = panel?.dataset.tabValue;
+    if (!next || !items.some((item) => item.value === next && !item.disabled)) return;
+    select(next);
+    await tick();
+    await new Promise<void>((resolve) => setTimeout(resolve));
+    const visibleTarget = document.getElementById(targetId);
+    visibleTarget?.focus({ preventScroll: true });
+    if (typeof visibleTarget?.scrollIntoView === "function") {
+      visibleTarget.scrollIntoView({ block: "nearest" });
+    }
+  }
+
+  $effect(() => {
+    if (!followHash || !root || typeof window === "undefined") return;
+    const handleHash = () => void selectFragment();
+    handleHash();
+    window.addEventListener("hashchange", handleHash);
+    return () => window.removeEventListener("hashchange", handleHash);
+  });
+</script>
+
+<div
+  bind:this={root}
+  data-tabs
+  aria-label={label}
+  class={styles.root({ class: className })}
+>
+  <Bits.Root
+    value={selected}
+    onValueChange={select}
+    {orientation}
+    activationMode="automatic"
+    loop={true}
+    {disabled}
+    aria-label={label}
+  >
+    <Bits.List aria-label={label} class={styles.list({ class: listClass })}>
+      {#each items as item (item.value)}
+        <Bits.Trigger value={item.value} disabled={item.disabled}>
+          {#snippet child({ props })}
+            <Button
+              {...props}
+              variant="ghost"
+              size="sm"
+              class={styles.trigger({ class: triggerClass })}
+            >{item.label}</Button>
+          {/snippet}
+        </Bits.Trigger>
+      {/each}
+    </Bits.List>
+
+    {#each items as item (item.value)}
+      <Bits.Content
+        value={item.value}
+        class={styles.content({ class: contentClass })}
+        tabindex={0}
+        data-tabs-owner={ownerId}
+        data-tab-value={item.value}
+      >
+        {@render children?.({ value: item.value })}
+      </Bits.Content>
+    {/each}
+  </Bits.Root>
+</div>

package/vendor/ds/kits/base/src/Text.svelte

@@ -0,0 +1,45 @@
+<!-- Running copy in a Theme reading role: body or caption (ADR 0025). -->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import { warnDeprecated } from "./deprecation";
+  import {
+    defaultTextInk,
+    text,
+    type TextElement,
+    type TextInk,
+    type TextRole,
+  } from "./text.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLElement>, "class" | "role"> {
+    /** The Theme reading role. */
+    role?: TextRole;
+    /** Ink or secondary ink; a caption defaults to muted. */
+    ink?: TextInk;
+    /** @deprecated Renamed `ink` (ADR 0026: `tone` is the semantic vocabulary); removed next release. */
+    tone?: TextInk;
+    /** The element rendered: `p` (default), `span`, `div` or `small`. */
+    as?: TextElement;
+    /** Extra classes merged onto the rendered element, over its role styles. */
+    class?: string;
+    /** The copy rendered inside the element. */
+    children: Snippet;
+  }
+
+  const { role = "body", ink, tone, as = "p", class: className, children, ...rest }: Props = $props();
+
+  // `ink` wins; the deprecated `tone` is honoured for one release.
+  const resolvedInk = $derived(ink ?? tone ?? defaultTextInk(role));
+  const classes = $derived(text({ role, ink: resolvedInk, class: className }));
+  $effect(() => {
+    if (tone !== undefined) warnDeprecated("Text", `tone="${tone}"`, `ink="${tone}"`);
+  });
+</script>
+
+<!-- Static elements, never `<svelte:element>`: see Heading — a dynamic element
+     is re-inserted while it hydrates (before Svelte 5.57.2), repainting a lede
+     that is the page's Largest Contentful Paint. -->
+{#if as === "span"}<span {...rest} data-text data-type-role={role} class={classes}>{@render children()}</span>
+{:else if as === "div"}<div {...rest} data-text data-type-role={role} class={classes}>{@render children()}</div>
+{:else if as === "small"}<small {...rest} data-text data-type-role={role} class={classes}>{@render children()}</small>
+{:else}<p {...rest} data-text data-type-role={role} class={classes}>{@render children()}</p>{/if}