@lyeve-labs/ui-kit 0.12.1 → 0.13.1

package/dist/components/Checkbox.svelte

@@ -1,20 +1,37 @@
 <script lang="ts">
-  import { FIELD_HINT } from '../internal/field.js';
-  let {
-    checked = $bindable(false),
-    label,
-    hint,
-    required = false,
-    disabled = false,
-    id,
-    name,
-    value,
-    class: cls = '',
-    onchange,
-  }: {
+  import type { Component } from 'svelte';
+  import { FIELD_ERROR, FIELD_HINT, FIELD_WRAP } from '../internal/field.js';
+  import {
+    CHOICE_DESCRIPTION,
+    CHOICE_FOCUS,
+    CHOICE_ICON_PX,
+    CHOICE_INPUT,
+    CHOICE_LABEL_STACK,
+    CHOICE_MARK,
+    choiceBox,
+    choiceIcon,
+    choiceLabel,
+    choiceWrap,
+    type ChoiceSize,
+    type ChoiceVariant,
+  } from '../internal/choice.js';
+
+  interface Props {
     checked?: boolean;
+    /** Partly checked. Announced as aria-checked="mixed". */
+    indeterminate?: boolean;
     label?: string;
+    /** Screen-reader-only label, for a checkbox in a table cell whose column header is the visible name. */
+    labelHidden?: boolean;
+    /** Secondary line under the label. */
+    description?: string;
     hint?: string;
+    error?: string;
+    /** Drawn before the label. */
+    icon?: Component<{ size?: number; class?: string }>;
+    size?: ChoiceSize;
+    /** 'card' draws a bordered option whose whole surface is the target. */
+    variant?: ChoiceVariant;
     required?: boolean;
     disabled?: boolean;
     id?: string;
@@ -22,66 +39,160 @@
     value?: string;
     class?: string;
     onchange?: (checked: boolean) => void;
-  } = $props();
+  }
+
+  let {
+    checked = $bindable(false),
+    indeterminate = $bindable(false),
+    label = undefined,
+    labelHidden = false,
+    description = undefined,
+    hint = undefined,
+    error = undefined,
+    icon: Icon = undefined,
+    size = 'md',
+    variant = 'inline',
+    required = false,
+    disabled = false,
+    id = undefined,
+    name = undefined,
+    value = undefined,
+    class: cls = '',
+    onchange = undefined,
+  }: Props = $props();
+
+  // $props.id() and not a random string: a random id differs between the server
+  // render and hydration, so every aria-describedby built from it points at an
+  // element that does not exist on the client.
+  const uid = $props.id();
+  const fieldId = $derived(id ?? uid);
+
+  // Error, then hint, then description. A screen reader announces one message,
+  // so the most urgent one has to win rather than the last one rendered.
+  const messageId = $derived(
+    error
+      ? `${fieldId}-error`
+      : hint
+        ? `${fieldId}-hint`
+        : description
+          ? `${fieldId}-description`
+          : undefined,
+  );
+
+  // A part-checked box is on, not a third colour, so it paints the filled box
+  // and tints the card exactly as a checked one does.
+  const on = $derived(checked || indeterminate);
+
+  // A card fills its column. An inline option must not: stretched to the full
+  // width of the field wrapper, the label swallows the empty space beside it
+  // and a stray click far from the box toggles the value.
+  const rootClass = $derived(variant === 'card' ? FIELD_WRAP : `${FIELD_WRAP} items-start`);
 
   function handleChange(e: Event & { currentTarget: HTMLInputElement }) {
+    // Disabled is enforced here as well as on the input. The native attribute
+    // is what stops a real click, and it is the only thing that does, so a
+    // change arriving any other way - a synthetic event, a script driving the
+    // node - would still move the bound value with nothing on screen to say so.
+    if (disabled) return;
+    // The DOM clears indeterminate on the first click. Leaving the prop set
+    // would repaint the mixed bar over a box the user has just ticked.
+    indeterminate = false;
     checked = e.currentTarget.checked;
     onchange?.(checked);
   }
 </script>
 
-<label
-  class="inline-flex items-start gap-2.5 cursor-pointer select-none {disabled
-    ? 'opacity-50 cursor-not-allowed'
-    : ''} {cls}"
->
-  <span class="relative flex items-center justify-center mt-0.5 shrink-0">
-    <input
-      type="checkbox"
-      {id}
-      {name}
-      {value}
-      {required}
-      {disabled}
-      {checked}
-      onchange={handleChange}
-      class="peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed"
-    />
-    <!-- The focus ring is stated once, outside the checked branch. It used to
-         live only on the unchecked classes, so ticking a box removed the only
-         indicator a keyboard user had; in a permissions matrix of a hundred
-         boxes that loses your place entirely. A ring rather than a border
-         colour, because when checked the border is already brand. -->
-    <span
-      class="pointer-events-none w-4 h-4 rounded border transition-colors duration-150 flex items-center justify-center
-        peer-focus-visible:outline peer-focus-visible:outline-2 peer-focus-visible:outline-brand peer-focus-visible:outline-offset-2
-        {checked ? 'bg-brand border-brand' : 'bg-surface-2 border-line-strong'}"
-    >
-      {#if checked}
-        <svg width="10" height="8" viewBox="0 0 10 8" fill="none" aria-hidden="true">
-          <path
-            d="M1 4l3 3 5-6"
-            stroke="currentColor"
-            stroke-width="1.5"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            class="text-ink"
-          />
-        </svg>
-      {/if}
-    </span>
+{#snippet control()}
+  <input
+    type="checkbox"
+    id={fieldId}
+    {name}
+    {value}
+    {required}
+    {disabled}
+    {checked}
+    {indeterminate}
+    aria-checked={indeterminate ? 'mixed' : undefined}
+    aria-invalid={error ? 'true' : undefined}
+    aria-labelledby={label ? `${fieldId}-label` : undefined}
+    aria-describedby={messageId}
+    onchange={handleChange}
+    class={CHOICE_INPUT}
+  />
+{/snippet}
+
+{#snippet mark()}
+  <span class="{choiceBox('checkbox', size, checked, indeterminate)} mt-0.5">
+    {#if on}
+      <!-- Both marks are stroked paths on one 10 by 8 grid. A Unicode check
+           lands at whatever weight the reader's font gives it, visibly lighter
+           than every other icon in the kit, and the mixed bar has no glyph that
+           is not a minus sign standing in for one. -->
+      <svg width="10" height="8" viewBox="0 0 10 8" fill="none" aria-hidden="true">
+        <path
+          d={indeterminate ? CHOICE_MARK.mixed : CHOICE_MARK.check}
+          stroke="currentColor"
+          stroke-width="1.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    {/if}
   </span>
-  {#if label || hint}
-    <span class="flex flex-col gap-0.5">
-      {#if label}
-        <span class="text-sm text-fg">
-          {label}
-          {#if required}<span class="text-danger ml-0.5" aria-label="required">*</span>{/if}
+{/snippet}
+
+{#snippet body()}
+  {#if label || description || Icon}
+    <span class={CHOICE_LABEL_STACK}>
+      {#if label || Icon}
+        <span class="flex items-center gap-2">
+          {#if Icon}
+            <span class={choiceIcon(size)}><Icon size={CHOICE_ICON_PX[size]} /></span>
+          {/if}
+          {#if label}
+            <!-- Named by aria-labelledby rather than by the wrapping label, so
+                 the description below stays a description. Read as the label's
+                 own text it became part of the name, and the reader heard the
+                 whole paragraph before it reached the checked state. -->
+            <span id="{fieldId}-label" class="{choiceLabel(size)} {labelHidden ? 'sr-only' : ''}">
+              {label}{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span>{/if}
+            </span>
+          {/if}
         </span>
       {/if}
-      {#if hint}
-        <span class={FIELD_HINT}>{hint}</span>
+      {#if description}
+        <span id="{fieldId}-description" class={CHOICE_DESCRIPTION}>{description}</span>
       {/if}
     </span>
   {/if}
-</label>
+{/snippet}
+
+<div class="{rootClass} {cls}">
+  {#if variant === 'card'}
+    <!-- The input covers the whole card, so the card surface is the element the
+         peer ring can reach and the box inside it is not. That is deliberate:
+         one control gets one focus indicator, and a ring on the box drawn
+         inside a ring on the card reads as two separate things to focus. -->
+    <label class="relative block">
+      {@render control()}
+      <span class="{choiceWrap('card', on, disabled)} {CHOICE_FOCUS}">
+        {@render mark()}
+        {@render body()}
+      </span>
+    </label>
+  {:else}
+    <label class={choiceWrap('inline', on, disabled)}>
+      <span class="relative flex shrink-0 items-center justify-center">
+        {@render control()}
+        {@render mark()}
+      </span>
+      {@render body()}
+    </label>
+  {/if}
+
+  {#if error}
+    <p id="{fieldId}-error" class={FIELD_ERROR}>{error}</p>
+  {:else if hint}
+    <p id="{fieldId}-hint" class={FIELD_HINT}>{hint}</p>
+  {/if}
+</div>

package/dist/components/Checkbox.svelte.d.ts

@@ -1,7 +1,24 @@
-type $$ComponentProps = {
+import type { Component } from 'svelte';
+import { type ChoiceSize, type ChoiceVariant } from '../internal/choice.js';
+interface Props {
     checked?: boolean;
+    /** Partly checked. Announced as aria-checked="mixed". */
+    indeterminate?: boolean;
     label?: string;
+    /** Screen-reader-only label, for a checkbox in a table cell whose column header is the visible name. */
+    labelHidden?: boolean;
+    /** Secondary line under the label. */
+    description?: string;
     hint?: string;
+    error?: string;
+    /** Drawn before the label. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    size?: ChoiceSize;
+    /** 'card' draws a bordered option whose whole surface is the target. */
+    variant?: ChoiceVariant;
     required?: boolean;
     disabled?: boolean;
     id?: string;
@@ -9,7 +26,7 @@ type $$ComponentProps = {
     value?: string;
     class?: string;
     onchange?: (checked: boolean) => void;
-};
-declare const Checkbox: import("svelte").Component<$$ComponentProps, {}, "checked">;
+}
+declare const Checkbox: Component<Props, {}, "checked" | "indeterminate">;
 type Checkbox = ReturnType<typeof Checkbox>;
 export default Checkbox;

package/dist/components/CheckboxGroup.svelte

@@ -0,0 +1,162 @@
+<script lang="ts" module>
+  import type { Component } from 'svelte';
+
+  /**
+   * One option in a choice group.
+   *
+   * RadioGroup declares this interface in the same words, so a consumer who has
+   * written one option list can write the other without rereading the types. A
+   * colocated test compares the two declarations character for character,
+   * because the group and the single control had already drifted apart once.
+   */
+  export interface ChoiceOption {
+    /** The submitted value, and the key the option is rendered under. */
+    value: string;
+    /** Names this one choice. The group is named by the legend instead. */
+    label: string;
+    /** A second line under the label, carrying what the label leaves out. */
+    description?: string;
+    /** A lucide component. The group sizes it, so the caller does not guess. */
+    icon?: Component<{ size?: number; class?: string }>;
+    /** Blocks this option alone. A disabled group blocks every option. */
+    disabled?: boolean;
+  }
+</script>
+
+<script lang="ts">
+  import {
+    CHOICE_GROUP,
+    choiceGroupList,
+    type ChoiceOrientation,
+    type ChoiceSize,
+    type ChoiceVariant,
+  } from '../internal/choice.js';
+  import { FIELD_ERROR, FIELD_HINT, FIELD_LABEL, describedBy } from '../internal/field.js';
+  import Checkbox from './Checkbox.svelte';
+
+  interface Props {
+    /** The chosen values, ordered by `options` rather than by click order. */
+    value?: string[];
+    options: ChoiceOption[];
+    /**
+     * The group's accessible name, rendered as a legend. Required because an
+     * unnamed group announces as a bare set of controls, which leaves a reader
+     * to infer what the set is for from the options alone.
+     */
+    label: string;
+    /** Keeps the legend for a screen reader and takes it off the screen. */
+    labelHidden?: boolean;
+    hint?: string;
+    error?: string;
+    name?: string;
+    orientation?: ChoiceOrientation;
+    size?: ChoiceSize;
+    variant?: ChoiceVariant;
+    required?: boolean;
+    disabled?: boolean;
+    class?: string;
+    onchange?: (value: string[]) => void;
+  }
+
+  let {
+    value = $bindable([]),
+    options,
+    label,
+    labelHidden = false,
+    hint = undefined,
+    error = undefined,
+    name = undefined,
+    orientation = 'vertical',
+    size = 'md',
+    variant = 'inline',
+    required = false,
+    disabled = false,
+    class: cls = '',
+    onchange = undefined,
+  }: Props = $props();
+
+  /*
+   * The instance id, and through it the shared name, comes from $props.id().
+   * RadioGroup built its name from Math.random(), which produces one value on
+   * the server and a different one on hydration, so every id and every name
+   * derived from it changed under the client on first paint.
+   */
+  const uid = $props.id();
+  const groupName = $derived(name ?? uid);
+
+  const chosen = $derived(new Set(value));
+
+  function toggle(option: string, on: boolean) {
+    const next = new Set(value);
+    if (on) {
+      next.add(option);
+    } else {
+      next.delete(option);
+    }
+    // Filtered out of `options` rather than appended on click, so ticking C
+    // and then A submits the same value as ticking A and then C.
+    value = options.filter((o) => next.has(o.value)).map((o) => o.value);
+    onchange?.(value);
+  }
+</script>
+
+<!--
+  No aria-invalid here, where RadioGroup carries one. ARIA supports the
+  attribute on radiogroup and not on group, which is the role a fieldset of
+  checkboxes has and the only role that fits it, so the kit's a11y gate rejects
+  it outright. The error still reaches a reader through aria-describedby, which
+  is global and points at the message paragraph below.
+
+  aria-required is gone for the same reason and is not replaced by `required` on
+  each box, which would demand every option be ticked instead of one of them.
+  The requirement is in the group's name instead: a group's name comes from its
+  legend, so the legend says "(required)" and the set announces as "Interests
+  (required), group". Naming a group that way is accurate, where naming a single
+  control that way puts a word into what a voice user has to speak at it. The
+  asterisk stays decoration, and the hint, when the caller writes one, says what
+  is required and reaches the reader through aria-describedby.
+-->
+<fieldset class="{CHOICE_GROUP} {cls}" {disabled} aria-describedby={describedBy(uid, error, hint)}>
+  <!--
+    The legend stays a legend when it is hidden. Swapping it for an aria-label
+    on the fieldset would name the group and drop it out of the reading order,
+    so a reader moving through the page would meet the options with nothing
+    ahead of them saying what the set is for.
+  -->
+  <legend class="{FIELD_LABEL} {labelHidden ? 'sr-only' : ''}">
+    {label}{#if required}<span class="text-danger ml-0.5" aria-hidden="true">*</span><span
+        class="sr-only"
+      >
+        (required)</span
+      >{/if}
+  </legend>
+
+  <div class={choiceGroupList(orientation)}>
+    {#each options as option (option.value)}
+      <!--
+        The option renders through Checkbox rather than through a copy of it.
+        A group that paints its own box is how RadioGroup came to rest on
+        border-line and to keep its focus ring inside the selected branch while
+        the single control had been fixed for both.
+      -->
+      <Checkbox
+        checked={chosen.has(option.value)}
+        value={option.value}
+        label={option.label}
+        description={option.description}
+        icon={option.icon}
+        name={groupName}
+        {size}
+        {variant}
+        disabled={disabled || option.disabled === true}
+        onchange={(on) => toggle(option.value, on)}
+      />
+    {/each}
+  </div>
+
+  {#if error}
+    <p id="{uid}-error" class={FIELD_ERROR}>{error}</p>
+  {:else if hint}
+    <p id="{uid}-hint" class={FIELD_HINT}>{hint}</p>
+  {/if}
+</fieldset>

package/dist/components/CheckboxGroup.svelte.d.ts

@@ -0,0 +1,51 @@
+import type { Component } from 'svelte';
+/**
+ * One option in a choice group.
+ *
+ * RadioGroup declares this interface in the same words, so a consumer who has
+ * written one option list can write the other without rereading the types. A
+ * colocated test compares the two declarations character for character,
+ * because the group and the single control had already drifted apart once.
+ */
+export interface ChoiceOption {
+    /** The submitted value, and the key the option is rendered under. */
+    value: string;
+    /** Names this one choice. The group is named by the legend instead. */
+    label: string;
+    /** A second line under the label, carrying what the label leaves out. */
+    description?: string;
+    /** A lucide component. The group sizes it, so the caller does not guess. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    /** Blocks this option alone. A disabled group blocks every option. */
+    disabled?: boolean;
+}
+import { type ChoiceOrientation, type ChoiceSize, type ChoiceVariant } from '../internal/choice.js';
+interface Props {
+    /** The chosen values, ordered by `options` rather than by click order. */
+    value?: string[];
+    options: ChoiceOption[];
+    /**
+     * The group's accessible name, rendered as a legend. Required because an
+     * unnamed group announces as a bare set of controls, which leaves a reader
+     * to infer what the set is for from the options alone.
+     */
+    label: string;
+    /** Keeps the legend for a screen reader and takes it off the screen. */
+    labelHidden?: boolean;
+    hint?: string;
+    error?: string;
+    name?: string;
+    orientation?: ChoiceOrientation;
+    size?: ChoiceSize;
+    variant?: ChoiceVariant;
+    required?: boolean;
+    disabled?: boolean;
+    class?: string;
+    onchange?: (value: string[]) => void;
+}
+declare const CheckboxGroup: Component<Props, {}, "value">;
+type CheckboxGroup = ReturnType<typeof CheckboxGroup>;
+export default CheckboxGroup;

package/dist/components/Collapsible.svelte

@@ -0,0 +1,142 @@
+<script lang="ts">
+  /**
+   * One disclosure that owns nothing but itself: an advanced-options block, a
+   * long log line, a stack trace folded under an error.
+   *
+   * Not the native `details` element. Its open state cannot be animated, so the
+   * content snaps in and out in a single frame, and it cannot be driven from
+   * outside: a page that wants to open the block from a deep link or a search
+   * hit has no way in. `open` here is bindable, so the page and the trigger
+   * share one value.
+   *
+   * Accordion is the component for a set of these. It decides which of its
+   * items is open, and an item asks it; this decides nothing beyond itself.
+   */
+  import type { Component, Snippet } from 'svelte';
+
+  interface Props {
+    open?: boolean;
+    /** The clickable summary. */
+    label: string;
+    /** Drawn before the label. */
+    icon?: Component<{ size?: number; class?: string }>;
+    /** A count or status beside the label. */
+    badge?: string | number;
+    disabled?: boolean;
+    class?: string;
+    children: Snippet;
+  }
+
+  let {
+    open = $bindable(false),
+    label,
+    icon = undefined,
+    badge = undefined,
+    disabled = false,
+    class: klass = '',
+    children,
+  }: Props = $props();
+
+  // $props.id() and not a random string: a random id differs between the server
+  // render and hydration, so aria-controls points at nothing for the first
+  // paint and the two halves of the disclosure are wired to different names.
+  const uid = $props.id();
+  const triggerId = `${uid}-trigger`;
+  const panelId = `${uid}-panel`;
+
+  /**
+   * The disabled attribute stops a user press and not a dispatched one. A click
+   * sent from script reaches the handler on a disabled button, so the state
+   * change is guarded here as well as on the element.
+   */
+  function toggle() {
+    if (disabled) return;
+    open = !open;
+  }
+</script>
+
+<div class={klass}>
+  <!-- The focus ring is inset. The trigger spans the full width of whatever
+       holds it, so the global 2px outset outline is cropped by the first
+       ancestor that clips.
+       The hover background is dropped rather than overridden when the trigger
+       is disabled: :hover still matches a disabled button, and a second
+       background utility on the same element would resolve by the order
+       Tailwind emits it rather than the order it was written. -->
+  <button
+    id={triggerId}
+    type="button"
+    {disabled}
+    aria-expanded={open}
+    aria-controls={panelId}
+    onclick={toggle}
+    class="flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-left text-sm font-medium
+      text-fg transition-colors duration-150 outline-none focus-visible:ring-2
+      focus-visible:ring-inset focus-visible:ring-brand disabled:cursor-not-allowed
+      disabled:opacity-50 {disabled ? '' : 'hover:bg-surface-2'}"
+  >
+    <!-- The chevron points along the axis the content moves on: right while the
+         block is closed, down once it is open. -->
+    <svg
+      width="16"
+      height="16"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class="shrink-0 text-faint transition-transform duration-200 ease-out {open
+        ? ''
+        : '-rotate-90'}"
+      aria-hidden="true"
+    >
+      <path d="M6 9l6 6 6-6" />
+    </svg>
+
+    {#if icon}
+      {@const Icon = icon}
+      <Icon size={16} class="shrink-0 text-faint" />
+    {/if}
+
+    <span class="truncate">{label}</span>
+
+    {#if badge !== undefined}
+      <span class="ml-auto shrink-0 rounded-full bg-surface-2 px-2 py-0.5 text-xs text-muted">
+        {badge}
+      </span>
+    {/if}
+  </button>
+
+  <!--
+    A block opens to the height of its own content, which no fixed value knows.
+    Animating grid-template-rows from 0fr to 1fr resolves to that height in CSS
+    alone: no measuring, no reflow per frame, and nothing to correct when the
+    content changes. The inner element carries the overflow so the content is
+    clipped rather than spilling while the row grows.
+  -->
+  <div
+    class="grid transition-[grid-template-rows] duration-200 ease-out {open
+      ? 'grid-rows-[1fr]'
+      : 'grid-rows-[0fr]'}"
+  >
+    <div class="overflow-hidden">
+      <!--
+        inert, not height alone. The content stays mounted so the row can
+        animate to its height, and a subtree that is only zero pixels tall is
+        still in the accessibility tree and still in the tab order: Tab lands on
+        a control the reader cannot see and the page appears to lose focus.
+        inert is what takes the whole subtree out of both.
+      -->
+      <div
+        id={panelId}
+        role="region"
+        aria-labelledby={triggerId}
+        inert={!open}
+        class="px-2 pt-2 text-sm"
+      >
+        {@render children()}
+      </div>
+    </div>
+  </div>
+</div>

package/dist/components/Collapsible.svelte.d.ts

@@ -0,0 +1,32 @@
+/**
+   * One disclosure that owns nothing but itself: an advanced-options block, a
+   * long log line, a stack trace folded under an error.
+   *
+   * Not the native `details` element. Its open state cannot be animated, so the
+   * content snaps in and out in a single frame, and it cannot be driven from
+   * outside: a page that wants to open the block from a deep link or a search
+   * hit has no way in. `open` here is bindable, so the page and the trigger
+   * share one value.
+   *
+   * Accordion is the component for a set of these. It decides which of its
+   * items is open, and an item asks it; this decides nothing beyond itself.
+   */
+import type { Component, Snippet } from 'svelte';
+interface Props {
+    open?: boolean;
+    /** The clickable summary. */
+    label: string;
+    /** Drawn before the label. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    /** A count or status beside the label. */
+    badge?: string | number;
+    disabled?: boolean;
+    class?: string;
+    children: Snippet;
+}
+declare const Collapsible: Component<Props, {}, "open">;
+type Collapsible = ReturnType<typeof Collapsible>;
+export default Collapsible;