@lyeve-labs/ui-kit 0.36.0 → 0.38.0

package/dist/components/FilterChips.svelte

@@ -11,6 +11,14 @@
     count?: number;
     /** A lucide component before the label. */
     icon?: Component<{ size?: number; class?: string }>;
+    /**
+     * Renders the chip as a link to this URL instead of a button. Every chip
+     * carries one or none does. The modes cannot be mixed in one row. The
+     * current chip is still the one whose value matches `value`, and it
+     * carries aria-current="page", so a page can keep its filter in the URL
+     * and the row works before any script has loaded.
+     */
+    href?: string;
   }
 </script>
 
@@ -23,19 +31,43 @@
    * scrolls, hiding categories past the edge, or squeezes each label onto two
    * lines inside its segment. Chips wrap instead, so every category is in
    * sight at every width. One is always pressed.
+   *
+   * With an href on every chip the row is a set of links instead, for a
+   * filter the page keeps in its URL.
    */
   import { cn } from '../utils/cn.js';
+  import { FIELD_ERROR, FIELD_HINT, describedBy, joinIds } from '../internal/field.js';
+  import { safeHref } from '../internal/href.js';
   import { HIT_AREA } from '../internal/touch.js';
 
   interface Props {
-    /** The pressed chip's value. */
+    /** The pressed chip's value. In link mode, the value of the current chip. */
     value: T;
     options: FilterChip<T>[];
     /** Names the group for assistive technology. The chips name themselves. */
     label: string;
     /** Read after the count, so "3" is heard as "3 on sale". */
     countLabel?: string;
+    /**
+     * The group's id. The hint and the error take theirs from it. Left unset,
+     * the group carries no id and the messages take a generated one.
+     */
+    id?: string;
+    /** Shown under the row while there is no error. */
+    hint?: string;
+    /**
+     * Replaces the hint while it is set. The group points at it and is not
+     * marked invalid, because ARIA refuses that attribute on a group.
+     */
+    error?: string;
+    /**
+     * Ids of other elements that describe the group, separated by spaces, such
+     * as the message a wrapping Field renders. They are read after the group's
+     * own hint or error.
+     */
+    describedBy?: string;
     class?: string;
+    /** Button mode only. A link chip reports nothing. The page it opens does. */
     onchange?: (value: T) => void;
   }
 
@@ -44,43 +76,117 @@
     options,
     label,
     countLabel = '',
+    id = undefined,
+    hint = undefined,
+    error = undefined,
+    describedBy: callerIds = undefined,
     class: klass = '',
     onchange = undefined,
   }: Props = $props();
 
+  /*
+   * Link mode when every chip carries an href. A row that mixes the two is
+   * refused outright, for the reason SegmentedControl refuses one: a button
+   * beside two links would report a choice that the URL never learns about,
+   * and the caller has no way to see that from the screen.
+   */
+  const linked = $derived.by(() => {
+    const count = options.filter((o) => o.href !== undefined).length;
+    if (count !== 0 && count !== options.length) {
+      throw new Error(
+        `FilterChips: every option carries href or none does, ${count} of ${options.length} did`,
+      );
+    }
+    return count !== 0;
+  });
+
+  /*
+   * $props.id() and not Math.random(), so the message ids match between the
+   * server render and hydration. The group carries an id only when the caller
+   * names one, so a row given none keeps the attributes it had.
+   */
+  const uid = $props.id();
+  const messageBase = $derived(id ?? uid);
+  const describedByIds = $derived(joinIds(describedBy(messageBase, error, hint), callerIds));
+
   function pick(next: T): void {
     if (next === value) return;
     value = next;
     onchange?.(next);
   }
+
+  /** One treatment for both modes, so a current link reads as a pressed chip. */
+  function chipClass(pressed: boolean): string {
+    return cn(
+      HIT_AREA,
+      'inline-flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium whitespace-nowrap transition-colors',
+      'focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand',
+      pressed
+        ? 'border-brand bg-brand/10 text-fg'
+        : 'border-line text-muted hover:border-line-strong hover:text-fg',
+    );
+  }
 </script>
 
-<div class={cn('flex flex-wrap gap-1.5', klass)} role="group" aria-label={label}>
+<!--
+  The row is rendered once and the message follows it as a sibling. A column
+  wrapped round the two only while a message showed rebuilt the row each time
+  an error arrived or cleared, and a chip that held focus dropped it to the
+  page. The row carries the field marker while it reports a message, so a
+  panel sizing itself to its form counts it as the one field it then is.
+
+  The row carries no aria-invalid. ARIA does not allow it on a group, or on
+  the buttons and links inside one, so an error reaches a reader through
+  aria-describedby, which reads the message itself.
+-->
+<div
+  data-field={error || hint ? '' : undefined}
+  {id}
+  class={cn('flex flex-wrap gap-1.5', klass)}
+  role="group"
+  aria-label={label}
+  aria-describedby={describedByIds}
+>
   {#each options as chip (chip.value)}
     {@const pressed = chip.value === value}
-    <button
-      type="button"
-      aria-pressed={pressed}
-      class={cn(
-        HIT_AREA,
-        'inline-flex items-center gap-1.5 rounded-full border px-3 py-1 text-xs font-medium whitespace-nowrap transition-colors',
-        'focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-brand',
-        pressed
-          ? 'border-brand bg-brand/10 text-fg'
-          : 'border-line text-muted hover:border-line-strong hover:text-fg',
-      )}
-      onclick={() => pick(chip.value)}
-    >
-      {#if chip.icon}
-        {@const Icon = chip.icon}
-        <Icon size={12} class="shrink-0" />
-      {/if}
-      {chip.label}
-      {#if chip.count !== undefined}
-        <span class="font-mono text-[10px] text-faint"
-          >{chip.count}{#if countLabel}<span class="sr-only"> {countLabel}</span>{/if}</span
-        >
-      {/if}
-    </button>
+    {#if linked}
+      <!-- A plain anchor with no click handler, so choosing a chip is a
+           navigation the browser performs on its own, before the page has
+           hydrated as well as after. -->
+      <a
+        href={safeHref(chip.href)}
+        aria-current={pressed ? 'page' : undefined}
+        class={chipClass(pressed)}
+      >
+        {@render face(chip)}
+      </a>
+    {:else}
+      <button
+        type="button"
+        aria-pressed={pressed}
+        class={chipClass(pressed)}
+        onclick={() => pick(chip.value)}
+      >
+        {@render face(chip)}
+      </button>
+    {/if}
   {/each}
 </div>
+{#if error}
+  <p id="{messageBase}-error" class="{FIELD_ERROR} mt-1.5">{error}</p>
+{:else if hint}
+  <p id="{messageBase}-hint" class="{FIELD_HINT} mt-1.5">{hint}</p>
+{/if}
+
+{#snippet face(chip: FilterChip<T>)}
+  {#if chip.icon}
+    {@const Icon = chip.icon}
+    <Icon size={12} class="shrink-0" />
+  {/if}
+  {chip.label}
+  {#if chip.count !== undefined}
+    <span class="font-mono text-[10px] text-faint"
+      >{chip.count}{#if countLabel}<span class="sr-only"> {countLabel}</span>{/if}</span
+    >
+  {/if}
+{/snippet}

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

@@ -12,17 +12,44 @@ export interface FilterChip<T extends string = string> {
         size?: number;
         class?: string;
     }>;
+    /**
+     * Renders the chip as a link to this URL instead of a button. Every chip
+     * carries one or none does. The modes cannot be mixed in one row. The
+     * current chip is still the one whose value matches `value`, and it
+     * carries aria-current="page", so a page can keep its filter in the URL
+     * and the row works before any script has loaded.
+     */
+    href?: string;
 }
 declare function $$render<T extends string>(): {
     props: {
-        /** The pressed chip's value. */
+        /** The pressed chip's value. In link mode, the value of the current chip. */
         value: T;
         options: FilterChip<T>[];
         /** Names the group for assistive technology. The chips name themselves. */
         label: string;
         /** Read after the count, so "3" is heard as "3 on sale". */
         countLabel?: string;
+        /**
+         * The group's id. The hint and the error take theirs from it. Left unset,
+         * the group carries no id and the messages take a generated one.
+         */
+        id?: string;
+        /** Shown under the row while there is no error. */
+        hint?: string;
+        /**
+         * Replaces the hint while it is set. The group points at it and is not
+         * marked invalid, because ARIA refuses that attribute on a group.
+         */
+        error?: string;
+        /**
+         * Ids of other elements that describe the group, separated by spaces, such
+         * as the message a wrapping Field renders. They are read after the group's
+         * own hint or error.
+         */
+        describedBy?: string;
         class?: string;
+        /** Button mode only. A link chip reports nothing. The page it opens does. */
         onchange?: (value: T) => void;
     };
     exports: {};

package/dist/components/Input.svelte

@@ -7,6 +7,7 @@
     FIELD_WRAP,
     controlBorder,
     describedBy,
+    joinIds,
   } from '../internal/field.js';
   import type { HTMLInputAttributes } from 'svelte/elements';
 
@@ -27,6 +28,12 @@
     placeholder?: string;
     hint?: string;
     error?: string;
+    /**
+     * Ids of other elements that describe the input, separated by spaces, such
+     * as the message a wrapping Field renders. They are read after the input's
+     * own hint or error.
+     */
+    describedBy?: string;
     disabled?: boolean;
     required?: boolean;
     id?: string;
@@ -47,6 +54,7 @@
     placeholder = '',
     hint = undefined,
     error = undefined,
+    describedBy: callerIds = undefined,
     disabled = false,
     required = false,
     id = undefined,
@@ -73,7 +81,7 @@
     {required}
     bind:value
     aria-invalid={error ? 'true' : undefined}
-    aria-describedby={describedBy(fieldId, error, hint)}
+    aria-describedby={joinIds(describedBy(fieldId, error, hint), callerIds)}
     class="{CONTROL_BASE} {controlBorder(!!error)} {mono ? 'font-mono' : ''}"
     {...rest}
   />

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

@@ -12,6 +12,12 @@ interface Props extends Forwarded {
     placeholder?: string;
     hint?: string;
     error?: string;
+    /**
+     * Ids of other elements that describe the input, separated by spaces, such
+     * as the message a wrapping Field renders. They are read after the input's
+     * own hint or error.
+     */
+    describedBy?: string;
     disabled?: boolean;
     required?: boolean;
     id?: string;

package/dist/components/NumberInput.svelte

@@ -7,6 +7,7 @@
     controlBorder,
     describedBy,
   } from '../internal/field.js';
+  import { HIT_AREA } from '../internal/touch.js';
 
   interface Props {
     value?: number;
@@ -70,8 +71,13 @@
   // line-strong, not line: the stepper buttons and the number between them read
   // as one control, and line sits at 1.25:1, so the caps of that control were
   // the part a low-vision user could not find.
+  //
+  // Under a finger the control token grows to 44px, and steppers as wide as the
+  // token left the number 40px inside a 128px field. They narrow instead and
+  // take a hit box of the control size, so the number keeps its room and each
+  // stepper is still a 44px target.
   const step_ =
-    'flex w-control shrink-0 items-center justify-center border-line-strong bg-surface-2 text-muted ' +
+    `${HIT_AREA} flex w-control shrink-0 items-center justify-center border-line-strong bg-surface-2 text-muted coarse:w-8 ` +
     'transition-colors hover:bg-line hover:text-fg ' +
     'disabled:opacity-50 disabled:cursor-not-allowed';
 </script>

package/dist/components/PageShell.svelte

@@ -13,17 +13,32 @@
    * The shell renders no landmark of its own. An app shell already owns `main`,
    * `nav` and the rest, and a second `main` changes what a landmark query
    * matches for every assistive technology reading the page.
+   *
+   * The browser tab follows the page title once the app states a format with
+   * setDocumentTitleFormat. Until it does, the shell renders no title element,
+   * so a page that renders its own keeps it.
    */
   import type { Snippet } from 'svelte';
   import { ArrowLeft } from '@lucide/svelte';
+  import { getDocumentTitleFormat } from '../internal/document-title.js';
   import { safeHref } from '../internal/href.js';
   import { PAGE_PAD, PAGE_STACK, PAGE_WIDTH, type PageWidth } from '../internal/layout.js';
   import { HIT_AREA } from '../internal/touch.js';
   import PageHeader from './PageHeader.svelte';
 
   interface Props {
-    /** The page's only h1, rendered through PageHeader. */
+    /**
+     * The page's only h1, rendered through PageHeader. Also the browser tab's
+     * title, once the app states a format.
+     */
     title: string;
+    /**
+     * What the browser tab shows when it should read differently from
+     * `title`, such as a record's name on a page whose heading says what is
+     * done to it. Read only once the app states a format with
+     * setDocumentTitleFormat.
+     */
+    documentTitle?: string;
     description?: string;
     /** Content cap. narrow, default, wide, full. */
     width?: PageWidth;
@@ -77,6 +92,7 @@
 
   let {
     title,
+    documentTitle = undefined,
     description = undefined,
     width = 'default',
     fill = false,
@@ -89,6 +105,11 @@
     children,
   }: Props = $props();
 
+  const format = getDocumentTitleFormat();
+
+  /** The tab's words, or nothing at all while the app has stated no format. */
+  const tabTitle = $derived(format === undefined ? undefined : format(documentTitle ?? title));
+
   /**
    * A fill page owns the viewport instead of sitting in it: the content takes
    * no cap and reaches the edges, and the height the title row leaves goes to
@@ -132,6 +153,12 @@
     'focus-visible:ring-2 focus-visible:ring-brand';
 </script>
 
+<svelte:head>
+  {#if tabTitle !== undefined}
+    <title>{tabTitle}</title>
+  {/if}
+</svelte:head>
+
 <div class="{frame} {klass}">
   {#if titleHidden}
     <h1 data-testid="page-title" class="sr-only">{title}</h1>

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

@@ -12,12 +12,26 @@
    * The shell renders no landmark of its own. An app shell already owns `main`,
    * `nav` and the rest, and a second `main` changes what a landmark query
    * matches for every assistive technology reading the page.
+   *
+   * The browser tab follows the page title once the app states a format with
+   * setDocumentTitleFormat. Until it does, the shell renders no title element,
+   * so a page that renders its own keeps it.
    */
 import type { Snippet } from 'svelte';
 import { type PageWidth } from '../internal/layout.js';
 interface Props {
-    /** The page's only h1, rendered through PageHeader. */
+    /**
+     * The page's only h1, rendered through PageHeader. Also the browser tab's
+     * title, once the app states a format.
+     */
     title: string;
+    /**
+     * What the browser tab shows when it should read differently from
+     * `title`, such as a record's name on a page whose heading says what is
+     * done to it. Read only once the app states a format with
+     * setDocumentTitleFormat.
+     */
+    documentTitle?: string;
     description?: string;
     /** Content cap. narrow, default, wide, full. */
     width?: PageWidth;

package/dist/components/RadioGroup.svelte

@@ -33,7 +33,7 @@
     type ChoiceSize,
     type ChoiceVariant,
   } from '../internal/choice.js';
-  import { FIELD_ERROR, FIELD_HINT, describedBy } from '../internal/field.js';
+  import { FIELD_ERROR, FIELD_HINT, describedBy, joinIds } from '../internal/field.js';
   import Radio from './Radio.svelte';
 
   interface Props {
@@ -48,8 +48,19 @@
     label: string;
     /** Keeps the legend for a screen reader and takes it off the screen. */
     labelHidden?: boolean;
+    /**
+     * The fieldset's id. The hint and the error take theirs from it. Left
+     * unset, the fieldset carries no id and the messages take a generated one.
+     */
+    id?: string;
     hint?: string;
     error?: string;
+    /**
+     * Ids of other elements that describe the group, separated by spaces, such
+     * as the message a wrapping Field renders. They are read after the group's
+     * own hint or error.
+     */
+    describedBy?: string;
     name?: string;
     orientation?: ChoiceOrientation;
     size?: ChoiceSize;
@@ -65,8 +76,10 @@
     options,
     label,
     labelHidden = false,
+    id = undefined,
     hint = undefined,
     error = undefined,
+    describedBy: callerIds = undefined,
     name = undefined,
     orientation = 'vertical',
     size = 'md',
@@ -87,6 +100,7 @@
    */
   const uid = $props.id();
   const groupName = $derived(name ?? uid);
+  const messageBase = $derived(id ?? uid);
 </script>
 
 <!--
@@ -97,12 +111,13 @@
 -->
 <fieldset
   data-field
+  {id}
   class="{CHOICE_GROUP} {cls}"
   role="radiogroup"
   {disabled}
   aria-invalid={error ? 'true' : undefined}
   aria-required={required ? 'true' : undefined}
-  aria-describedby={describedBy(uid, error, hint)}
+  aria-describedby={joinIds(describedBy(messageBase, error, hint), callerIds)}
 >
   <!--
     The legend stays a legend when it is hidden. Swapping it for an aria-label
@@ -139,8 +154,8 @@
   </div>
 
   {#if error}
-    <p id="{uid}-error" class={FIELD_ERROR}>{error}</p>
+    <p id="{messageBase}-error" class={FIELD_ERROR}>{error}</p>
   {:else if hint}
-    <p id="{uid}-hint" class={FIELD_HINT}>{hint}</p>
+    <p id="{messageBase}-hint" class={FIELD_HINT}>{hint}</p>
   {/if}
 </fieldset>

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

@@ -36,8 +36,19 @@ interface Props {
     label: string;
     /** Keeps the legend for a screen reader and takes it off the screen. */
     labelHidden?: boolean;
+    /**
+     * The fieldset's id. The hint and the error take theirs from it. Left
+     * unset, the fieldset carries no id and the messages take a generated one.
+     */
+    id?: string;
     hint?: string;
     error?: string;
+    /**
+     * Ids of other elements that describe the group, separated by spaces, such
+     * as the message a wrapping Field renders. They are read after the group's
+     * own hint or error.
+     */
+    describedBy?: string;
     name?: string;
     orientation?: ChoiceOrientation;
     size?: ChoiceSize;

package/dist/components/SegmentedControl.svelte

@@ -21,8 +21,16 @@
 </script>
 
 <script lang="ts" generics="T extends string">
-  import { FIELD_LABEL, FIELD_WRAP } from '../internal/field.js';
+  import {
+    FIELD_ERROR,
+    FIELD_HINT,
+    FIELD_LABEL,
+    FIELD_WRAP,
+    describedBy,
+    joinIds,
+  } from '../internal/field.js';
   import { safeHref } from '../internal/href.js';
+  import { HIT_AREA } from '../internal/touch.js';
 
   type Size = 'sm' | 'md';
 
@@ -38,6 +46,24 @@
     label: string;
     /** Drops the caption above the row. The group keeps its accessible name. */
     labelHidden?: boolean;
+    /**
+     * The group's id. The hint and the error take theirs from it. Left unset,
+     * the group carries no id and the messages take a generated one.
+     */
+    id?: string;
+    /** Shown under the row while there is no error. */
+    hint?: string;
+    /**
+     * Replaces the hint while it is set. A row of radios is marked invalid
+     * with it. A row of links is not, because ARIA refuses the attribute there.
+     */
+    error?: string;
+    /**
+     * Ids of other elements that describe the group, separated by spaces, such
+     * as the message a wrapping Field renders. They are read after the group's
+     * own hint or error.
+     */
+    describedBy?: string;
     /** Submits the value with the surrounding form, through a hidden input. */
     name?: string;
     size?: Size;
@@ -52,6 +78,10 @@
     options,
     label,
     labelHidden = false,
+    id = undefined,
+    hint = undefined,
+    error = undefined,
+    describedBy: callerIds = undefined,
     name = undefined,
     size = 'md',
     disabled = false,
@@ -64,12 +94,26 @@
    * Input in the same row line up. The segments stretch inside it rather than
    * setting their own height, which would add the row's padding and border on
    * top and stand the control two pixels proud of everything beside it.
+   *
+   * Under a finger the small row grows to the control height, as a small
+   * Button does, and each segment keeps its visual inside the track and takes
+   * a hit box of the control size. A segment that grew instead would stand
+   * the track six pixels proud of the Input beside it.
    */
   const SIZES: Record<Size, { row: string; segment: string; icon: number }> = {
-    sm: { row: 'h-8', segment: 'gap-1.5 px-2.5 text-xs', icon: 14 },
+    sm: { row: 'h-8 coarse:min-h-control', segment: 'gap-1.5 px-2.5 text-xs', icon: 14 },
     md: { row: 'h-control', segment: 'gap-2 px-3 text-sm', icon: 16 },
   };
 
+  /*
+   * $props.id() and not Math.random(), so the message ids match between the
+   * server render and hydration. The group carries an id only when the caller
+   * names one, so a control given none keeps the attributes it had.
+   */
+  const uid = $props.id();
+  const messageBase = $derived(id ?? uid);
+  const describedByIds = $derived(joinIds(describedBy(messageBase, error, hint), callerIds));
+
   let rootEl: HTMLDivElement | undefined = $state();
 
   /*
@@ -182,21 +226,26 @@
 
   <!-- A set of links is a group, not a radiogroup: a link is not a radio and
        carries no aria-checked, and what marks the current one is aria-current,
-       the attribute a reader already knows from navigation. -->
+       the attribute a reader already knows from navigation. ARIA allows
+       aria-invalid on a radiogroup and not on a group, so a row of links
+       reports an error through aria-describedby alone. -->
   <div
     bind:this={rootEl}
+    {id}
     role={linked ? 'group' : 'radiogroup'}
     aria-label={label}
+    aria-invalid={error && !linked ? 'true' : undefined}
+    aria-describedby={describedByIds}
     onfocusout={linked ? onGroupFocusOut : undefined}
-    class="inline-flex items-stretch rounded-lg border border-line-strong bg-surface-2 p-0.5 {SIZES[
-      size
-    ].row} {disabled ? 'opacity-50' : ''}"
+    class="inline-flex items-stretch rounded-lg border {error
+      ? 'border-danger'
+      : 'border-line-strong'} bg-surface-2 p-0.5 {SIZES[size].row} {disabled ? 'opacity-50' : ''}"
   >
     {#each options as option, i (option.value)}
       {@const selected = option.value === value}
       {@const Icon = option.icon}
       {@const segment =
-        'inline-flex items-center justify-center rounded-md outline-none transition-colors focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand disabled:cursor-not-allowed ' +
+        `${HIT_AREA} inline-flex items-center justify-center rounded-md outline-none transition-colors focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand disabled:cursor-not-allowed ` +
         SIZES[size].segment +
         (selected
           ? ' bg-surface text-brand shadow-sm ring-1 ring-inset ring-brand/40'
@@ -261,6 +310,12 @@
     {/each}
   </div>
 
+  {#if error}
+    <p id="{messageBase}-error" class={FIELD_ERROR}>{error}</p>
+  {:else if hint}
+    <p id="{messageBase}-hint" class={FIELD_HINT}>{hint}</p>
+  {/if}
+
   {#if name}
     <!-- A div with role="radiogroup" submits nothing. The value reaches a form
          post through this and not through the segments, which are buttons and

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

@@ -32,6 +32,24 @@ declare function $$render<T extends string>(): {
         label: string;
         /** Drops the caption above the row. The group keeps its accessible name. */
         labelHidden?: boolean;
+        /**
+         * The group's id. The hint and the error take theirs from it. Left unset,
+         * the group carries no id and the messages take a generated one.
+         */
+        id?: string;
+        /** Shown under the row while there is no error. */
+        hint?: string;
+        /**
+         * Replaces the hint while it is set. A row of radios is marked invalid
+         * with it. A row of links is not, because ARIA refuses the attribute there.
+         */
+        error?: string;
+        /**
+         * Ids of other elements that describe the group, separated by spaces, such
+         * as the message a wrapping Field renders. They are read after the group's
+         * own hint or error.
+         */
+        describedBy?: string;
         /** Submits the value with the surrounding form, through a hidden input. */
         name?: string;
         size?: "sm" | "md";