@lyeve-labs/ui-kit 0.35.2 → 0.37.0

package/README.md

@@ -175,7 +175,7 @@ in `styles.css` beside the palette:
 
 | Token                 | Value                            | For                                                                                                            |
 | --------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| `--duration-fast`     | 120ms                            | a state change in place: color, opacity, border, shadow, focus                                                |
+| `--duration-fast`     | 120ms                            | a state change in place: color, opacity, border, shadow, focus                                                 |
 | `--duration-base`     | 200ms                            | movement in place (a knob, a chevron, a collapse) and a small surface arriving (menu, popover, tooltip, toast) |
 | `--duration-slow`     | 320ms                            | a large surface arriving (dialog, drawer)                                                                      |
 | `--duration-progress` | 500ms                            | a value moving (a progress bar's width)                                                                        |
@@ -236,6 +236,116 @@ the fields the panel actually rendered, re-read when the form reveals more, and
 a radio or checkbox group counts as the one question it asks. Name a rung and
 it is kept.
 
+## Component notes
+
+What a component does beyond its props table.
+
+### A filter kept in the URL
+
+`SegmentedControl` and `FilterChips` take an `href` on each option. When every
+option carries one, the options render as plain links: the current one carries
+`aria-current="page"`, no change is reported, and the row works before the page
+hydrates. Every option carries an `href` or none does, and a row that mixes the
+two throws.
+
+```svelte
+<FilterChips
+  label="Status"
+  value={status}
+  options={[
+    { value: 'all', label: 'All', href: '?status=all' },
+    { value: 'open', label: 'Open', count: 7, href: '?status=open' },
+  ]}
+/>
+```
+
+### Copying
+
+`CopyButton` takes `text` for words beside its icon, such as "Copy all codes",
+and the words then name the button. A control the kit does not ship copies
+through the same write and confirms on the same clock with `CopyState`. Create
+one while the component initializes, read `status` in markup, and dispose of it
+when the component unmounts.
+
+```svelte
+<script lang="ts">
+  import { Button, CopyState } from '@lyeve-labs/ui-kit';
+
+  let { id }: { id: string } = $props();
+  const copy = new CopyState();
+  $effect(() => () => copy.dispose());
+</script>
+
+<Button variant="ghost" size="sm" onclick={() => copy.copy(id)}>
+  {copy.status === 'copied' ? 'Copied' : 'Copy ID'}
+</Button>
+```
+
+`copyToClipboard(text)` is the write alone. It resolves to whether the copy
+worked and never throws. Where the async clipboard is missing, as it is on an
+origin without TLS, it falls back to the legacy copy command.
+
+### Page titles
+
+`PageShell` renders the document title once an app states its format, in its
+root layout. A page then drops its own title element, which would otherwise
+race the shell's. `documentTitle` gives the tab other words than the heading.
+A format that reads reactive state, such as a tenant's name, follows it. An app
+that states no format gets no title element from the kit.
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script lang="ts">
+  import { setDocumentTitleFormat } from '@lyeve-labs/ui-kit';
+
+  let { children } = $props();
+  setDocumentTitleFormat((title) => `${title} | Acme`);
+</script>
+
+{@render children()}
+```
+
+```svelte
+<PageShell title="Edit entry" documentTitle={entry.name}>...</PageShell>
+```
+
+### A sign-in page in a tenant's colors
+
+`AuthShell` takes a `lockup` snippet that replaces the product mark above the
+heading, and passes `class` and `style` to its outer element. Custom properties
+set there scope to the page, so a tenant's accent repaints the brand tokens for
+everything on it. Inside the `href` link the lockup names the link, so give it
+words or an image with alt text.
+
+```svelte
+<AuthShell title="Sign in" href="/" style="--color-brand: {tenant.accent}">
+  {#snippet lockup()}
+    <span class="inline-flex items-center gap-2 text-xl font-semibold text-fg">
+      <img src={tenant.logo} alt="" class="size-9" />
+      {tenant.name}
+    </span>
+  {/snippet}
+  <form method="POST">...</form>
+</AuthShell>
+```
+
+### Tone names
+
+`StatusTone` is the tone `Alert`, `Banner` and `Stat` take. `AccentTone` adds
+`violet` and is the tone `Badge`, `Tag`, `Indicator` and `Progress` take. An app
+that maps its own states onto tones types the map with them.
+
+```ts
+import type { StatusTone } from '@lyeve-labs/ui-kit';
+
+const JOB_TONE: Record<JobState, StatusTone> = {
+  queued: 'neutral',
+  running: 'brand',
+  failed: 'danger',
+  done: 'success',
+};
+```
+
 ## Local development
 
 ```bash

package/dist/components/AuthShell.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  import { cn } from '../utils/cn.js';
   import Card from './Card.svelte';
   import Logo from './Logo.svelte';
 
@@ -13,10 +14,23 @@
     href?: string;
     /** `md` is a form. `lg` is a walkthrough with more than one column. */
     width?: Width;
+    /**
+     * Drawn above the heading in place of the product mark, such as a
+     * tenant's logo and name. Inside the `href` link it names that link, so
+     * it carries words or an image with alt text.
+     */
+    lockup?: Snippet;
     /** Controls at the top end of the column: a theme toggle, a language switch. */
     actions?: Snippet;
     /** Under the card: the one link that leads off the page, such as "Create an account". */
     footer?: Snippet;
+    /** Added to the page's outer element. */
+    class?: string;
+    /**
+     * Set on the page's outer element, so custom properties scope to the
+     * page: a tenant's accent repaints the brand tokens for everything inside.
+     */
+    style?: string;
     children: Snippet;
   }
 
@@ -25,8 +39,11 @@
     description = undefined,
     href = undefined,
     width = 'md',
+    lockup = undefined,
     actions = undefined,
     footer = undefined,
+    class: klass = '',
+    style = undefined,
     children,
   }: Props = $props();
 
@@ -42,7 +59,7 @@
   on some pages, a theme control on others, and one class that named no
   token at all. Stated once here, the way AppShell states the signed-in frame.
 -->
-<main class="flex min-h-screen items-center justify-center bg-ink px-4 py-10">
+<main class={cn('flex min-h-screen items-center justify-center bg-ink px-4 py-10', klass)} {style}>
   <div class="w-full {widths[width]}">
     {#if actions}
       <div class="mb-4 flex justify-end">{@render actions()}</div>
@@ -54,8 +71,14 @@
           {href}
           class="mb-5 inline-flex rounded-lg outline-none focus-visible:ring-2 focus-visible:ring-brand"
         >
-          <Logo size="lg" />
+          {#if lockup}
+            {@render lockup()}
+          {:else}
+            <Logo size="lg" />
+          {/if}
         </a>
+      {:else if lockup}
+        <div class="mb-5 flex justify-center">{@render lockup()}</div>
       {:else}
         <Logo size="lg" class="mb-5" />
       {/if}

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

@@ -8,10 +8,23 @@ interface Props {
     href?: string;
     /** `md` is a form. `lg` is a walkthrough with more than one column. */
     width?: Width;
+    /**
+     * Drawn above the heading in place of the product mark, such as a
+     * tenant's logo and name. Inside the `href` link it names that link, so
+     * it carries words or an image with alt text.
+     */
+    lockup?: Snippet;
     /** Controls at the top end of the column: a theme toggle, a language switch. */
     actions?: Snippet;
     /** Under the card: the one link that leads off the page, such as "Create an account". */
     footer?: Snippet;
+    /** Added to the page's outer element. */
+    class?: string;
+    /**
+     * Set on the page's outer element, so custom properties scope to the
+     * page: a tenant's accent repaints the brand tokens for everything inside.
+     */
+    style?: string;
     children: Snippet;
 }
 declare const AuthShell: import("svelte").Component<Props, {}, "">;

package/dist/components/Button.svelte

@@ -7,7 +7,7 @@
   import { TOUCH_GROW } from '../internal/touch.js';
 
   type Variant = 'primary' | 'secondary' | 'danger' | 'ghost' | 'outline' | 'violet';
-  type Size = 'sm' | 'md' | 'lg';
+  type Size = 'sm' | 'md' | 'lg' | 'icon';
 
   /**
    * Attributes forwarded to whichever element renders. Naming them, rather than
@@ -96,10 +96,18 @@
       'border border-line-strong text-fg hover:border-brand hover:text-brand active:bg-brand/10',
   };
 
+  /*
+   * `icon` is a square for a button whose only content is an icon: the icon
+   * sets the size and the box adds 8px round it, so a 16px icon makes the 32px
+   * square the header controls use. Without it, an icon-only control beside
+   * ThemeToggle had to copy ThemeToggle's classes, and every copy drifted on
+   * its own. Name the button with `aria-label`, which also becomes its hint.
+   */
   const sizes: Record<Size, string> = {
     sm: 'px-3 py-1.5 text-sm gap-1.5 rounded-md',
     md: 'px-4 py-2 text-sm gap-2 rounded-lg',
     lg: 'px-5 py-2.5 text-base gap-2 rounded-lg',
+    icon: 'p-2 rounded-lg',
   };
 
   const spinnerSize = $derived(size === 'lg' ? 18 : 15);
@@ -113,7 +121,8 @@
    *
    * TOUCH_GROW: under a coarse pointer the button takes the control height,
    * which is 44px there, so a button and the input beside it grow together.
-   * A mouse sees 36px, 32px and 44px by size, as before.
+   * A mouse sees 36px, 32px and 44px by size, as before, and an icon-only
+   * button its icon plus 16px.
    */
   const cls = $derived(
     `inline-flex items-center justify-center font-medium whitespace-nowrap transition-colors ` +

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

@@ -1,7 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAnchorAttributes, HTMLButtonAttributes } from 'svelte/elements';
 type Variant = 'primary' | 'secondary' | 'danger' | 'ghost' | 'outline' | 'violet';
-type Size = 'sm' | 'md' | 'lg';
+type Size = 'sm' | 'md' | 'lg' | 'icon';
 /**
  * Attributes forwarded to whichever element renders. Naming them, rather than
  * accepting an open index signature, means a prop the component does not

package/dist/components/CopyButton.svelte

@@ -6,8 +6,17 @@
   interface Props {
     /** The text written to the clipboard. */
     value: string;
-    /** The button's accessible name. */
+    /**
+     * The accessible name of a button that shows only its icon. A button with
+     * `text` takes its name from that text instead.
+     */
     label?: string;
+    /**
+     * Words shown beside the icon, such as "Copy all codes". They name the
+     * button, so the name a voice-control user speaks is the one on screen.
+     * Left unset, the button is the icon alone.
+     */
+    text?: string;
     /** Announced and shown after a successful copy. */
     copiedLabel?: string;
     /** Icon size in px. */
@@ -18,11 +27,20 @@
   let {
     value,
     label = 'Copy',
+    text = undefined,
     copiedLabel = 'Copied',
     size = 14,
     class: klass = '',
   }: Props = $props();
 
+  /*
+   * The icon alone sits at the faint step beside the text it copies. Words
+   * read as an action of their own, so they take the muted step the kit sets
+   * other text actions in, and the padding a word needs around it.
+   */
+  const ICON_ONLY = `${HIT_AREA} inline-flex items-center justify-center rounded-md p-1 text-faint outline-none transition-colors hover:text-fg active:bg-surface-2 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand`;
+  const WITH_TEXT = `${HIT_AREA} inline-flex items-center justify-center gap-1.5 rounded-md px-2 py-1 text-sm text-muted outline-none transition-colors hover:text-fg active:bg-surface-2 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand`;
+
   const copier = new CopyState();
 
   const message = $derived.by(() => {
@@ -45,18 +63,18 @@
 -->
 <span class="inline-flex items-center {message ? 'gap-1.5' : ''} {klass}">
   <!--
-    The accessible name stays `label` through the copied copier. The live region
-    below is what reports the result, and renaming the button as well would
-    announce the same word twice and then leave a control called "Copied" that
-    copies.
+    The accessible name stays the same through the copied state, whether it
+    comes from `label` or from `text`. The live region below is what reports the
+    result, and renaming the button as well would announce the same word twice
+    and then leave a control called "Copied" that copies.
   -->
   <button
     type="button"
-    aria-label={label}
+    aria-label={text ? undefined : label}
     onclick={() => copier.copy(value)}
-    class="{HIT_AREA} inline-flex items-center justify-center rounded-md p-1 text-faint outline-none transition-colors hover:text-fg active:bg-surface-2 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand"
+    class={text ? WITH_TEXT : ICON_ONLY}
   >
-    <CopyGlyph copied={copier.status === 'copied'} {size} />
+    <CopyGlyph copied={copier.status === 'copied'} {size} />{#if text}{text}{/if}
   </button>
 
   <span

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

@@ -1,8 +1,17 @@
 interface Props {
     /** The text written to the clipboard. */
     value: string;
-    /** The button's accessible name. */
+    /**
+     * The accessible name of a button that shows only its icon. A button with
+     * `text` takes its name from that text instead.
+     */
     label?: string;
+    /**
+     * Words shown beside the icon, such as "Copy all codes". They name the
+     * button, so the name a voice-control user speaks is the one on screen.
+     * Left unset, the button is the icon alone.
+     */
+    text?: string;
     /** Announced and shown after a successful copy. */
     copiedLabel?: string;
     /** Icon size in px. */

package/dist/components/CopyField.svelte

@@ -99,7 +99,9 @@
       {value}
       onfocus={(e) => e.currentTarget.select()}
       aria-describedby={describedBy(fieldId, failed ? COPY_FAILED_MESSAGE : undefined, hint)}
-      class="h-full min-w-0 flex-1 truncate bg-transparent px-3 text-sm text-fg outline-none {mono ? 'font-mono' : ''}"
+      class="h-full min-w-0 flex-1 truncate bg-transparent px-3 text-sm text-fg outline-none {mono
+        ? 'font-mono'
+        : ''}"
     />
     {@render actions?.()}
     {#if secret}

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,12 +31,16 @@
    * 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 { 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. */
@@ -36,6 +48,7 @@
     /** Read after the count, so "3" is heard as "3 on sale". */
     countLabel?: string;
     class?: string;
+    /** Button mode only. A link chip reports nothing. The page it opens does. */
     onchange?: (value: T) => void;
   }
 
@@ -48,39 +61,77 @@
     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;
+  });
+
   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}>
   {#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>
+
+{#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,10 +12,18 @@ 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. */
@@ -23,6 +31,7 @@ declare function $$render<T extends string>(): {
         /** Read after the count, so "3" is heard as "3 on sale". */
         countLabel?: string;
         class?: string;
+        /** Button mode only. A link chip reports nothing. The page it opens does. */
         onchange?: (value: T) => void;
     };
     exports: {};

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/SegmentedControl.svelte

@@ -23,6 +23,7 @@
 <script lang="ts" generics="T extends string">
   import { FIELD_LABEL, FIELD_WRAP } from '../internal/field.js';
   import { safeHref } from '../internal/href.js';
+  import { HIT_AREA } from '../internal/touch.js';
 
   type Size = 'sm' | 'md';
 
@@ -64,9 +65,14 @@
    * 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 },
   };
 
@@ -196,7 +202,7 @@
       {@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'

package/dist/components/SidebarNav.svelte

@@ -166,7 +166,14 @@
         {@render body(node)}
       </span>
     {:else if node.href && branch}
-      <div class="flex items-center gap-1">
+      <!--
+        The rail stacks the disclosure under the link, under a mouse and under
+        a finger alike, so the link keeps the rail's width. Side by side the two
+        did not fit. Under a finger the pair took 92px and scrolled the nav
+        sideways. Under a mouse the link shrank to its own padding with its icon
+        under the chevron, and a rail with a gutter scrolled as well.
+      -->
+      <div class={collapsed ? 'flex flex-col items-start gap-1' : 'flex items-center gap-1'}>
         <a
           href={node.href}
           aria-current={current ? 'page' : undefined}

package/dist/components/Textarea.svelte

@@ -76,7 +76,9 @@
     {placeholder}
     aria-invalid={error ? 'true' : undefined}
     aria-describedby={describedBy(fieldId, error, hint)}
-    class="{CONTROL_MULTILINE} {controlBorder(!!error)} {resize ? 'resize-y' : 'resize-none'} {mono ? 'font-mono' : ''}"
+    class="{CONTROL_MULTILINE} {controlBorder(!!error)} {resize ? 'resize-y' : 'resize-none'} {mono
+      ? 'font-mono'
+      : ''}"
     bind:value
     {oninput}
     {onblur}

package/dist/components/ThemeToggle.svelte

@@ -15,7 +15,7 @@
    * implies the state.
    */
   import { Monitor, Moon, Sun } from '@lucide/svelte';
-  import { TOUCH_GROW } from '../internal/touch.js';
+  import Button from './Button.svelte';
   import {
     THEME_PREFERENCES,
     getThemePreference,
@@ -81,13 +81,17 @@
   }
 </script>
 
-<button
-  type="button"
+<!-- The kit's icon-only Button, so a control set beside this one takes the
+     same box by naming the same size, and the name shows on hover as well as
+     to a screen reader. -->
+<Button
+  variant="ghost"
+  size="icon"
   onclick={advance}
   data-print="hide"
   data-theme-preference={preference}
   aria-label="Theme: {LABEL[preference]}. Switch to {LABEL[upcoming]}."
-  class="{TOUCH_GROW} rounded-lg p-2 text-faint transition-colors hover:bg-surface-2 hover:text-fg active:bg-line active:text-fg {klass}"
+  class={klass}
 >
   <!-- The icon shows the state the control is in, not the one it moves to. It
        showed the destination while the label named the same destination, which
@@ -99,4 +103,4 @@
   {:else}
     <Sun size={16} aria-hidden="true" />
   {/if}
-</button>
+</Button>

package/dist/components/dialog/ConfirmDialog.svelte

@@ -44,7 +44,9 @@
   );
   // An identifier the message refers to. Set apart in monospace on its own
   // line rather than inside the sentence, where a UUID wraps mid-string.
-  let detail = $derived(typeof entry.meta?.confirmDetail === 'string' ? entry.meta.confirmDetail : '');
+  let detail = $derived(
+    typeof entry.meta?.confirmDetail === 'string' ? entry.meta.confirmDetail : '',
+  );
 
   async function handleConfirm() {
     if (loading) return;

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export type { CellFit } from './components/Table.svelte';
 export type { SidebarState } from './components/AppShell.svelte';
 export type { PageWidth, SectionVariant } from './internal/layout.js';
 export type { TreeNode, TriState } from './internal/tree.js';
+export { setDocumentTitleFormat, type DocumentTitleFormat } from './internal/document-title.js';
 export { default as Button } from './components/Button.svelte';
 export { default as ButtonGroup } from './components/ButtonGroup.svelte';
 export { default as Input } from './components/Input.svelte';
@@ -79,10 +80,12 @@ export { default as CheckoutSteps } from './components/CheckoutSteps.svelte';
 export { default as PluginCart } from './components/PluginCart.svelte';
 export type { QuickPick } from './components/PluginCart.svelte';
 export { billedCount, formatCents, ladderRows, ladderState, type BillingPeriod, type CartCatalog, type CartPlugin, type CartQuote, type CartQuoteItem, type DiscountBracket, type LadderState, } from './internal/pricing.js';
+export type { AccentTone, StatusTone } from './internal/tone.js';
 export { default as Stat } from './components/Stat.svelte';
 export { default as Kbd } from './components/Kbd.svelte';
 export { default as CopyButton } from './components/CopyButton.svelte';
 export { default as CopyField } from './components/CopyField.svelte';
+export { CopyState, copyToClipboard, type CopyStatus } from './internal/copy.svelte.js';
 export { default as Avatar } from './components/Avatar.svelte';
 export { default as AvatarGroup } from './components/AvatarGroup.svelte';
 export { default as Logo } from './components/Logo.svelte';
@@ -100,4 +103,4 @@ export { cn, type ClassValue } from './utils/cn.js';
 export { getTheme, getThemePreference, nextThemePreference, resolveTheme, setTheme, setThemePreference, systemTheme, themeBootScript, watchThemePreference, toggleTheme, watchSystemTheme, THEME_PREFERENCES, type Theme, type ThemePreference, } from './utils/theme.js';
 export * as motion from './motion.js';
 export type { Rung as MotionRung, Curve as MotionCurve } from './motion.js';
-export declare const VERSION = "0.35.2";
+export declare const VERSION = "0.37.0";

package/dist/index.js

@@ -22,6 +22,10 @@ export { default as Table } from './components/Table.svelte';
 export { default as DescriptionList } from './components/DescriptionList.svelte';
 export { default as Toolbar } from './components/Toolbar.svelte';
 export { default as TreeView } from './components/TreeView.svelte';
+// Stated once in an app's root layout, the format turns every PageShell's
+// title into the browser tab's. An app that never states one gets no title
+// element from the kit.
+export { setDocumentTitleFormat } from './internal/document-title.js';
 // ── Forms & inputs ─────────────────────────────────────────────────────────
 export { default as Button } from './components/Button.svelte';
 export { default as ButtonGroup } from './components/ButtonGroup.svelte';
@@ -79,6 +83,10 @@ export { default as Stat } from './components/Stat.svelte';
 export { default as Kbd } from './components/Kbd.svelte';
 export { default as CopyButton } from './components/CopyButton.svelte';
 export { default as CopyField } from './components/CopyField.svelte';
+// The clipboard write and the confirmation both copy controls run on, for a
+// control the kit does not ship. A menu item that copies then falls back the
+// same way on an insecure origin and confirms on the same clock.
+export { CopyState, copyToClipboard } from './internal/copy.svelte.js';
 // ── Media ──────────────────────────────────────────────────────────────────
 export { default as Avatar } from './components/Avatar.svelte';
 export { default as AvatarGroup } from './components/AvatarGroup.svelte';
@@ -108,4 +116,4 @@ export * as motion from './motion.js';
 // ── Version ────────────────────────────────────────────────────────────────
 // Generated from package.json by `pnpm version:sync`. Bump package.json, never
 // this line. The build and the test suite fail when the two disagree.
-export const VERSION = '0.35.2';
+export const VERSION = '0.37.0';

package/dist/internal/CopyGlyph.svelte

@@ -20,10 +20,19 @@
   const HIDDEN = 'scale-50 opacity-0 duration-fast ease-exit';
 </script>
 
-<span class="grid place-items-center" data-copy-state={copied ? 'copied' : 'idle'} aria-hidden="true">
-  <Copy {size} class="col-start-1 row-start-1 transition-[opacity,transform] {copied ? HIDDEN : SHOWN}" />
+<span
+  class="grid place-items-center"
+  data-copy-state={copied ? 'copied' : 'idle'}
+  aria-hidden="true"
+>
+  <Copy
+    {size}
+    class="col-start-1 row-start-1 transition-[opacity,transform] {copied ? HIDDEN : SHOWN}"
+  />
   <Check
     {size}
-    class="col-start-1 row-start-1 text-success transition-[opacity,transform] {copied ? SHOWN : HIDDEN}"
+    class="col-start-1 row-start-1 text-success transition-[opacity,transform] {copied
+      ? SHOWN
+      : HIDDEN}"
   />
 </span>

package/dist/internal/copy.svelte.d.ts

@@ -3,7 +3,10 @@
  *
  * Both controls report the same three states on the same clock, so a value
  * copied from a field and one copied from a code block confirm the same way.
+ * The package entry point exports the write and the state too, so a control
+ * the kit does not ship confirms the same way as well.
  */
+/** Where the last copy stands: at rest, confirmed, or refused. */
 export type CopyStatus = 'idle' | 'copied' | 'failed';
 /** How long the confirmation holds before the control returns to rest. */
 export declare const COPY_REVERT_MS = 1500;
@@ -16,9 +19,17 @@ export declare const COPY_FAILED_MESSAGE = "Copy failed";
  * writeText rejects while the document is not focused. Either way the value
  * goes through a selected, off-screen textarea and the legacy copy command,
  * which the browser still honors inside the click. Only when that also
- * refuses is it a failure the control reports. It never throws.
+ * refuses does it resolve to false. It never throws.
+ */
+export declare function copyToClipboard(value: string): Promise<boolean>;
+/**
+ * A copy and its outcome, on the clock CopyButton and CopyField confirm on.
+ *
+ * `status` reads `copied` or `failed` for 1.5 seconds after `copy` and `idle`
+ * otherwise. It is reactive, so markup that reads it follows it. Create one
+ * per control while the component initializes, and call `dispose` when that
+ * component unmounts, so the revert timer cannot fire after it.
  */
-export declare function writeClipboard(value: string): Promise<boolean>;
 export declare class CopyState {
     #private;
     status: CopyStatus;

package/dist/internal/copy.svelte.js

@@ -3,6 +3,8 @@
  *
  * Both controls report the same three states on the same clock, so a value
  * copied from a field and one copied from a code block confirm the same way.
+ * The package entry point exports the write and the state too, so a control
+ * the kit does not ship confirms the same way as well.
  */
 /** How long the confirmation holds before the control returns to rest. */
 export const COPY_REVERT_MS = 1500;
@@ -15,9 +17,9 @@ export const COPY_FAILED_MESSAGE = 'Copy failed';
  * writeText rejects while the document is not focused. Either way the value
  * goes through a selected, off-screen textarea and the legacy copy command,
  * which the browser still honors inside the click. Only when that also
- * refuses is it a failure the control reports. It never throws.
+ * refuses does it resolve to false. It never throws.
  */
-export async function writeClipboard(value) {
+export async function copyToClipboard(value) {
     const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
     if (clipboard) {
         try {
@@ -50,6 +52,14 @@ function legacyCopy(value) {
         area.remove();
     }
 }
+/**
+ * A copy and its outcome, on the clock CopyButton and CopyField confirm on.
+ *
+ * `status` reads `copied` or `failed` for 1.5 seconds after `copy` and `idle`
+ * otherwise. It is reactive, so markup that reads it follows it. Create one
+ * per control while the component initializes, and call `dispose` when that
+ * component unmounts, so the revert timer cannot fire after it.
+ */
 export class CopyState {
     status = $state('idle');
     #timer;
@@ -57,7 +67,7 @@ export class CopyState {
         // A second press restarts the window. Without this the first press's timer
         // reverts the second copy part way through its own.
         clearTimeout(this.#timer);
-        this.status = (await writeClipboard(value)) ? 'copied' : 'failed';
+        this.status = (await copyToClipboard(value)) ? 'copied' : 'failed';
         this.#timer = setTimeout(() => (this.status = 'idle'), COPY_REVERT_MS);
     }
     dispose() {

package/dist/internal/document-title.d.ts

@@ -0,0 +1,11 @@
+/** Turns a page's name into the words its browser tab shows. */
+export type DocumentTitleFormat = (title: string) => string;
+/**
+ * States the format every PageShell below the calling component renders its
+ * document title in. Call it while a layout initializes, the way any context
+ * is set. A format that reads reactive state is run again when that state
+ * changes.
+ */
+export declare function setDocumentTitleFormat(format: DocumentTitleFormat): void;
+/** The format a layout above stated, or undefined when none did. */
+export declare function getDocumentTitleFormat(): DocumentTitleFormat | undefined;

package/dist/internal/document-title.js

@@ -0,0 +1,28 @@
+/**
+ * The words a browser tab shows for a page, stated once for a whole app.
+ *
+ * A console rendered its own title element on every page, and each page spelled
+ * the suffix after the page name for itself. PageShell already holds the page's
+ * name, so an app that states the format once in its root layout gets every
+ * PageShell page titled the same way. An app that states none gets no title
+ * from the kit at all, and its pages keep whatever they render themselves.
+ *
+ * Context rather than a module variable: one server process renders pages for
+ * every visitor, and a format that reads the request (a tenant's name, say)
+ * would otherwise leak from one render into the next.
+ */
+import { getContext, setContext } from 'svelte';
+const FORMAT = Symbol('document-title-format');
+/**
+ * States the format every PageShell below the calling component renders its
+ * document title in. Call it while a layout initializes, the way any context
+ * is set. A format that reads reactive state is run again when that state
+ * changes.
+ */
+export function setDocumentTitleFormat(format) {
+    setContext(FORMAT, format);
+}
+/** The format a layout above stated, or undefined when none did. */
+export function getDocumentTitleFormat() {
+    return getContext(FORMAT);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lyeve-labs/ui-kit",
-  "version": "0.35.2",
+  "version": "0.37.0",
   "description": "A clean, accessible, palette-aware Svelte 5 component library. The design system behind LyEve.",
   "license": "MIT",
   "author": "LyEve Labs <hello@lyeve.com>",