@reddb-io/ui-kit 0.3.4 → 0.3.6

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

@@ -0,0 +1,172 @@
+<!-- A named slide set with canonical controls and opt-in pausable rotation. -->
+<script module lang="ts">
+  import type { Snippet } from "svelte";
+  import type { CarouselSlideContract } from "./core/carousel";
+  import type { ImageAsset } from "./image.variants";
+
+  export interface CarouselSlide extends CarouselSlideContract {
+    /** Visible meaning included in the slide's accessible position label. */
+    label: string;
+    /** Caller-owned slide content. Omitted, the slide renders its `image`. */
+    content?: Snippet;
+    /**
+     * The slide as an image the app's pipeline produced, rendered through the Base Image (lazy
+     * unless it opens the Carousel with `priority`); ignored when `content` is given.
+     */
+    image?: ImageAsset;
+  }
+
+  export interface CarouselViewportContext {
+    /** Slides in caller-owned document order. */
+    slides: readonly CarouselSlide[];
+    /** Current zero-based index; zero for an empty carousel. */
+    active: number;
+    /** Whether automatic rotation is running. */
+    playing: boolean;
+    /** Initial slide index, used to prioritize its image. */
+    firstIndex: number;
+  }
+</script>
+
+<script lang="ts">
+  import type { CarouselContract } from "./core/contracts/carousel";
+  import { untrack } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import Button from "./Button.svelte";
+  import Image from "./Image.svelte";
+  import { warnDeprecated } from "./deprecation";
+  import { carousel } from "./carousel.variants";
+  import { useReducedMotion } from "./reduced-motion.svelte";
+
+  interface Props extends CarouselContract, Omit<HTMLAttributes<HTMLDivElement>, "children" | "class" | "onchange"> {
+    /** Caller-owned slides in stable document order. */
+    slides: readonly CarouselSlide[];
+    /** Replaces the default slide drawing while keeping canonical navigation and rotation. The renderer owns slide semantics, inactive content exclusion and image priority. */
+    viewport?: Snippet<[CarouselViewportContext]>;
+    /** Called with the selected zero-based index after a user or timer selects a slide. */
+    onvaluechange?: (index: number) => void;
+    /** @deprecated Renamed `onvaluechange` (ADR 0026); removed next release. */
+    onchange?: (index: number) => void;
+    /** Extra classes merged onto the carousel region. */
+    class?: string;
+  }
+
+  let {
+    label,
+    slides,
+    viewport,
+    initialIndex = 0,
+    autoplay = false,
+    interval = 5_000,
+    onvaluechange,
+    onchange,
+    priority = false,
+    class: className,
+    viewportClass,
+    slideClass,
+    controlsClass,
+    ...rest
+  }: Props = $props();
+
+  const reducedMotion = useReducedMotion();
+  let requestedIndex = $state(untrack(() => Math.max(0, Math.trunc(initialIndex) || 0)));
+  const active = $derived(Math.max(0, Math.min(requestedIndex, slides.length - 1)));
+  const firstIndex = untrack(() => active);
+  let rotationRequested = $state(untrack(() => autoplay && slides.length > 1));
+  const isPlaying = $derived(rotationRequested && !reducedMotion.current);
+  const styles = carousel();
+
+  function select(index: number): void {
+    if (slides.length < 1) return;
+    requestedIndex = (index + slides.length) % slides.length;
+    onvaluechange?.(requestedIndex);
+    onchange?.(requestedIndex);
+  }
+
+  $effect(() => {
+    if (onchange) warnDeprecated("Carousel", "onchange", "onvaluechange");
+  });
+
+  function pauseForInteraction(event: FocusEvent | MouseEvent): void {
+    if (!autoplay || !isPlaying) return;
+    const target = event.target;
+    if (target instanceof Element && target.closest("[data-carousel-rotation]")) return;
+    rotationRequested = false;
+  }
+
+  $effect(() => {
+    if (!isPlaying || slides.length < 2) return;
+    const timer = window.setInterval(() => select(active + 1), Math.max(1, interval));
+    return () => window.clearInterval(timer);
+  });
+</script>
+
+<div
+  {...rest}
+  data-carousel
+  role="region"
+  aria-roledescription="carousel"
+  aria-label={label}
+  class={styles.root({ class: className })}
+  onfocusin={pauseForInteraction}
+  onmouseenter={pauseForInteraction}
+>
+  <div
+    data-carousel-viewport
+    aria-live={isPlaying ? "off" : "polite"}
+    class={styles.viewport({ class: viewportClass })}
+  >
+    {#if viewport}
+      {@render viewport({slides, active, playing: isPlaying, firstIndex})}
+    {:else}
+    {#each slides as slide, index (slide)}
+      <div
+        data-carousel-slide
+        role="group"
+        aria-roledescription="slide"
+        aria-label={`${index + 1} of ${slides.length} — ${slide.label}`}
+        hidden={index !== active}
+        class={styles.slide({ class: slideClass })}
+      >
+        {#if slide.content}
+          {@render slide.content()}
+        {:else if slide.image}
+          <Image {...slide.image} priority={priority && index === firstIndex} class="w-full" />
+        {/if}
+      </div>
+    {/each}
+    {/if}
+  </div>
+
+  <div data-carousel-controls class={styles.controls({ class: controlsClass })}>
+    <Button
+      variant="secondary"
+      size="sm"
+      aria-label="Previous slide"
+      disabled={slides.length < 2}
+      onclick={() => select(active - 1)}
+    >Previous</Button>
+    <span data-carousel-position aria-live="off" class={styles.position()}>
+      {slides.length === 0 ? "0 of 0" : `${active + 1} of ${slides.length}`}
+    </span>
+    <Button
+      variant="secondary"
+      size="sm"
+      aria-label="Next slide"
+      disabled={slides.length < 2}
+      onclick={() => select(active + 1)}
+    >Next</Button>
+    {#if autoplay}
+      <Button
+        data-carousel-rotation
+        variant="secondary"
+        size="sm"
+        aria-label={isPlaying ? "Pause slide rotation" : "Resume slide rotation"}
+        aria-pressed={isPlaying}
+        class={styles.rotation()}
+        disabled={slides.length < 2 || reducedMotion.current}
+        onclick={() => (rotationRequested = !rotationRequested)}
+      >{isPlaying ? "Pause" : "Resume"}</Button>
+    {/if}
+  </div>
+</div>

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

@@ -0,0 +1,99 @@
+<!--
+  A visibly named native checkbox composed with the canonical Field contract.
+  The input stays native and is the pointer target; the box and check beside
+  it are drawn from tokens (see checkbox.variants).
+-->
+<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 { checkbox } from "./checkbox.variants";
+
+  interface Props extends Omit<HTMLInputAttributes, "checked" | "children" | "class" | "id" | "required" | "type"> {
+    /** The required visible accessible name supplied through Field. */
+    label: string;
+    /** Supporting text announced with the checkbox. */
+    help?: string;
+    /** Current validation error announced with the checkbox. */
+    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 checkbox. */
+    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);
+  const styles = checkbox();
+  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)}
+    <span class={styles.root()} data-choice-control>
+      <input
+        {...rest}
+        {...control}
+        defaultChecked={initial}
+        checked={initial}
+        bind:this={element}
+        onchange={handleChange}
+        type="checkbox"
+        class={styles.control({ class: className })}
+      />
+      <span class={styles.box()} aria-hidden="true" data-choice-box></span>
+      <span class={styles.mark()} aria-hidden="true" data-choice-mark></span>
+    </span>
+  {/snippet}
+</Field>

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

@@ -0,0 +1,113 @@
+<!-- Preformatted source with a canonical Button copy affordance. -->
+<script lang="ts">
+  import type { HTMLAttributes } from "svelte/elements";
+  import Button from "./Button.svelte";
+  import { copyCodeSource, observeCodeOverflow } from "./core/code-block";
+  import {
+    CODE_TOKEN_CLASSES,
+    codeBlock,
+    codeTokens,
+    type CodeTokenizer,
+  } from "./code-block.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** Exact source shown and copied; whitespace is never normalised. */
+    code: string;
+    /** Optional human-readable language label. */
+    language?: string;
+    /**
+     * A synchronous tokenizer (a Data Kit `CodeFieldGrammar` fits) that highlights the code into
+     * token spans during render — on the server too, so the prerendered HTML is already highlighted.
+     * Omitted, the code renders as plain text.
+     */
+    grammar?: CodeTokenizer;
+    /** Accessible and visible copy labels. */
+    copyLabel?: string;
+    /** Label shown and announced after the code is copied. Defaults to `Copied`. */
+    copiedLabel?: string;
+    /** Retry label announced if clipboard access fails. Defaults to `Copy failed. Try again.`. */
+    copyErrorLabel?: string;
+    /**
+     * Accessible name of the scrolling code region, announced when a keyboard user tabs into a
+     * block too wide to show at once. Defaults to `<language> code`, or `Code sample` without one.
+     */
+    regionLabel?: string;
+    /** Extra classes merged onto the code block root. */
+    class?: string;
+  }
+
+  const {
+    code,
+    language,
+    grammar,
+    copyLabel = "Copy code",
+    copiedLabel = "Copied",
+    copyErrorLabel = "Copy failed. Try again.",
+    regionLabel,
+    class: className,
+    ...rest
+  }: Props = $props();
+
+  let copyState = $state<"idle" | "copied" | "failed">("idle");
+  let request = 0;
+  const copyText = $derived(copyState === "copied" ? copiedLabel : copyState === "failed" ? copyErrorLabel : copyLabel);
+  const slots = $derived(codeBlock());
+  const tokens = $derived(codeTokens(code, grammar));
+
+  // A block wider than its column scrolls, and a keyboard user can only scroll
+  // what they can focus (WCAG 2.1.1). The <pre> becomes a named, focusable
+  // region only while it overflows, so a block that fits adds no tab stop. The
+  // server renders the fitting state and the measurement runs after hydration,
+  // so the markup never mismatches.
+  let pre = $state<HTMLPreElement>();
+  let overflowing = $state(false);
+  const name = $derived(regionLabel ?? (language ? `${language} code` : "Code sample"));
+
+  $effect(() => {
+    code;
+    copyState = "idle";
+    request++;
+    return () => { request++; };
+  });
+
+  $effect(() => {
+    code;
+    grammar;
+    const element = pre;
+    if (!element) return;
+    return observeCodeOverflow(element, value => { overflowing = value; });
+  });
+
+  async function copyCode(): Promise<void> {
+    const current = ++request;
+    const copied = await copyCodeSource(code);
+    if (current === request) copyState = copied ? "copied" : "failed";
+  }
+</script>
+
+<div {...rest} data-code-block class={slots.root({ class: className })}>
+  <div class={slots.toolbar()}>
+    {#if language}
+      <span data-code-block-language class={slots.language()}>{language}</span>
+    {:else}
+      <span aria-hidden="true"></span>
+    {/if}
+    <Button
+      data-code-block-copy
+      variant="secondary"
+      size="sm"
+      aria-label={copyText}
+      onclick={copyCode}
+    >
+      <span aria-live="polite">{copyText}</span>
+    </Button>
+  </div>
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex (an overflowing block is a named region that must be keyboard-scrollable) -->
+  <pre
+    bind:this={pre}
+    class={slots.pre()}
+    tabindex={overflowing ? 0 : undefined}
+    role={overflowing ? "region" : undefined}
+    aria-label={overflowing ? name : undefined}
+    data-code-block-overflowing={overflowing ? "true" : undefined}><code class={slots.code()}>{#if grammar}{#each tokens as token, index (index)}<span data-code-token={token.kind} class={CODE_TOKEN_CLASSES[token.kind]}>{token.value}</span>{/each}{:else}{code}{/if}</code></pre>
+</div>

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

@@ -0,0 +1,124 @@
+<!-- A Field-bound typeahead whose input retains focus while Bits UI owns listbox semantics. -->
+<script lang="ts">
+  import { portalAppearance } from "./portal-appearance.svelte";
+  import type { ComboboxContract } from "./core/contracts/combobox";
+  import { Combobox as Bits } from "bits-ui";
+  import Field from "./Field.svelte";
+  import { input } from "./input.variants";
+  import { combobox, type ComboboxOption, type ComboboxSize } from "./combobox.variants";
+  import { popover } from "./popover.variants";
+
+  interface Props extends ComboboxContract {
+    /** Extra classes merged onto the Field root that wraps the label, input and messages. */
+    class?: string;
+    /** Called with the option's `value` when the user selects an option. */
+    onvaluechange?: (value: string) => void;
+    /**
+     * Called with the input text as the user types, and with the option's label after a selection.
+     */
+    oninputvaluechange?: (value: string) => void;
+    /** Called with the next open state when the listbox opens or closes. */
+    onopenchange?: (open: boolean) => void;
+  }
+
+  let {
+    label,
+    options,
+    name,
+    value = $bindable(""),
+    inputValue = $bindable(options.find((option) => option.value === value)?.label ?? ""),
+    help,
+    error,
+    required = false,
+    disabled = false,
+    placeholder,
+    open = $bindable(false),
+    controlSize = "md",
+    class: className,
+    inputClass,
+    contentClass,
+    itemClass,
+    onvaluechange,
+    oninputvaluechange,
+    onopenchange,
+  }: Props = $props();
+
+  const styles = $derived(combobox({ size: controlSize }));
+  const normalizedInput = $derived(inputValue.trim().toLocaleLowerCase());
+  const filteredOptions = $derived(
+    normalizedInput === ""
+      ? options
+      : options.filter((option) => option.label.toLocaleLowerCase().includes(normalizedInput)),
+  );
+
+  function handleInput(event: Event): void {
+    inputValue = (event.currentTarget as HTMLInputElement).value;
+    oninputvaluechange?.(inputValue);
+  }
+
+  function handleValueChange(nextValue: string): void {
+    value = nextValue;
+    inputValue = options.find((option) => option.value === nextValue)?.label ?? "";
+    onvaluechange?.(nextValue);
+    oninputvaluechange?.(inputValue);
+  }
+  const portal = portalAppearance(() => open);
+</script>
+
+<Field {label} {help} {error} {required} class={styles.root({ class: className })}>
+  {#snippet children(control)}
+    <Bits.Root
+      type="single"
+      items={[...options]}
+      {name}
+      {required}
+      {disabled}
+      {inputValue}
+      bind:value
+      bind:open
+      onValueChange={handleValueChange}
+      onOpenChange={onopenchange}
+    >
+      <div class={styles.control()} data-combobox>
+        <Bits.Input
+          {...portal.anchor}
+          {...control}
+          {placeholder}
+          oninput={handleInput}
+          class={input({ size: controlSize, class: styles.input({ class: inputClass }) })}
+        />
+      </div>
+
+      <Bits.Portal to={portal.container}>
+        <Bits.Content
+          sideOffset={8}
+          collisionPadding={8}
+          avoidCollisions={true}
+          {...portal.attributes}
+          data-combobox-surface
+          data-avoid-collisions="true"
+          class={popover({ class: styles.content({ class: contentClass }) })}
+        >
+          <Bits.Viewport>
+            {#each filteredOptions as option (option.value)}
+              <Bits.Item
+                value={option.value}
+                label={option.label}
+                disabled={option.disabled}
+                class={styles.item({ class: itemClass })}
+              >
+                <span class="min-w-0 break-words">{option.label}</span>
+                {#if option.value === value}
+                  <span class={styles.indicator()} aria-hidden="true">✓</span>
+                  <span class="sr-only">Selected</span>
+                {/if}
+              </Bits.Item>
+            {:else}
+              <span class={styles.empty()} data-combobox-empty>No matching options</span>
+            {/each}
+          </Bits.Viewport>
+        </Bits.Content>
+      </Bits.Portal>
+    </Bits.Root>
+  {/snippet}
+</Field>

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

@@ -0,0 +1,29 @@
+<!--
+  A universal content boundary at a DS-named width (ADR 0021) whose inline
+  inset follows local Density.
+-->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import { container, type ContainerSize } from "./container.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** The DS-named maximum width: `prose`, `content`, `wide` (the default) or `full`. */
+    size?: ContainerSize;
+    /** Extra classes merged onto the canonical content boundary. */
+    class?: string;
+    /** Page or section content held inside the width-limited boundary. */
+    children?: Snippet;
+  }
+
+  const { size = "wide", class: className, children, ...rest }: Props = $props();
+</script>
+
+<div
+  {...(rest as Record<string, unknown>)}
+  data-container
+  data-container-size={size}
+  class={container({ size, class: className })}
+>
+  {@render children?.()}
+</div>

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

@@ -0,0 +1,32 @@
+<!-- A presentation-only clip around caller-owned content. The wrapper adds no
+     name, role, keyboard stop, or appearance-axis selection of its own. -->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import {
+    CONTENT_MASK_CLIP_PATHS,
+    contentMask,
+    type ContentMaskShape,
+  } from "./content-mask.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** The named geometry that clips the caller-owned content. */
+    shape: ContentMaskShape;
+    /** Content keeps its own semantics, accessible name, and interaction. */
+    children: Snippet;
+    /** Extra classes merged onto the structural boundary. */
+    class?: string;
+  }
+
+  const { shape, children, class: className, style, ...rest }: Props = $props();
+</script>
+
+<div
+  {...rest}
+  data-content-mask
+  data-shape={shape}
+  style={`${style ?? ""}; clip-path: ${CONTENT_MASK_CLIP_PATHS[shape]}`}
+  class={contentMask({ class: className })}
+>
+  {@render children()}
+</div>

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

@@ -0,0 +1,42 @@
+<!-- A named arrangement boundary for related caller-owned controls. -->
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import {
+    controlGroup,
+    type ControlGroupOrientation,
+  } from "./control-group.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "class" | "role"> {
+    /** The accessible name for the related controls. */
+    label: string;
+    /** Visual flow without changing keyboard order. */
+    orientation?: ControlGroupOrientation;
+    /** The group element for rare imperative access. */
+    ref?: HTMLDivElement;
+    /** Extra classes merged onto the group. */
+    class?: string;
+    /** The related controls to arrange together; `label` names them as one group. */
+    children?: Snippet;
+  }
+
+  let {
+    label,
+    orientation = "horizontal",
+    ref = $bindable(),
+    class: className,
+    children,
+    ...rest
+  }: Props = $props();
+</script>
+
+<div
+  {...rest}
+  bind:this={ref}
+  role="group"
+  aria-label={label}
+  data-orientation={orientation}
+  class={controlGroup({ orientation, class: className })}
+>
+  {@render children?.()}
+</div>

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

@@ -0,0 +1,55 @@
+<script lang="ts">
+  import type { HTMLAttributes } from "svelte/elements";
+  import {
+    durationAttribute,
+    formatDuration,
+    normalizeRemaining,
+  } from "./countdown.behavior";
+  import { countdown } from "./countdown.variants";
+
+  interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** Caller-controlled remaining time in seconds. */
+    remaining: number;
+    /**
+     * Visible text naming what is counting down, shown beside the time. Defaults to `Time
+     * remaining`.
+     */
+    label?: string;
+    /** Text shown in place of the time once `remaining` reaches zero. Defaults to `Complete`. */
+    completeLabel?: string;
+    /**
+     * Formats the remaining whole seconds for display. Defaults to a clock such as `1:05` or
+     * `1:02:05`.
+     */
+    formatValue?: (remaining: number) => string;
+    /** Extra classes merged onto the countdown root. */
+    class?: string;
+  }
+
+  let {
+    remaining,
+    label = "Time remaining",
+    completeLabel = "Complete",
+    formatValue = formatDuration,
+    class: className,
+    ...rest
+  }: Props = $props();
+  const seconds = $derived(normalizeRemaining(remaining));
+  const complete = $derived(seconds === 0);
+  const slots = $derived(countdown());
+</script>
+
+<div
+  {...(rest as Record<string, unknown>)}
+  data-countdown
+  data-state={complete ? "complete" : "running"}
+  role={complete ? "status" : "timer"}
+  aria-live={complete ? "polite" : "off"}
+  aria-atomic="true"
+  class={slots.root({ class: className })}
+>
+  <span data-countdown-label class={slots.label()}>{label}</span>
+  <time datetime={durationAttribute(seconds)} class={slots.value()}>
+    {complete ? completeLabel : formatValue(seconds)}
+  </time>
+</div>