@lyeve-labs/ui-kit 0.36.0 → 0.38.0

package/README.md

@@ -236,6 +236,153 @@ 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' },
+  ]}
+/>
+```
+
+### Hints and errors on a choice row
+
+`SegmentedControl` and `FilterChips` take `id`, `hint`, `error` and
+`describedBy`, the field props `Input`, `Select` and `RadioGroup` take. The
+hint shows under the row, and an error replaces it. The group points
+`aria-describedby` at whichever is on screen, then at the ids in
+`describedBy`, so a row inside a `Field` reads that field's message too. A
+segmented row of radios carries `aria-invalid` while it shows an error. ARIA
+does not allow that attribute on a group, so a row of chips or links reports
+its error through the description alone. Both link modes take the same props.
+
+`SegmentedControl` draws its own caption from `label`. Inside a `Field`, which
+draws the label already, pass `labelHidden` so the name shows once and the
+group keeps it for a screen reader. `FilterChips` draws no caption, and its
+`label` only names the group.
+
+```svelte
+<SegmentedControl
+  label="Billing period"
+  options={periods}
+  bind:value={period}
+  hint="Charged at the start of each period."
+  error={form?.errors?.period}
+/>
+```
+
+### Empty states
+
+`EmptyState` renders its title as an h3, for a list inside a section. On a
+page whose only other heading is its h1, pass `level={2}` so the outline does
+not skip a level. The title looks the same at either level.
+
+### Copying
+
+`CopyButton` takes `text` for words beside its icon, such as "Copy all codes",
+and the words then name the button. `title` adds a tooltip, shown on hover and
+on keyboard focus. It never renames the button, and when it says more than the
+name it becomes the button's description. `CopyField` shows its value on one
+truncated line, and `wrap` shows the whole value across as many lines as it
+takes, breaking anywhere, for a key the reader has to check end to end.
+
+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/CopyButton.svelte

@@ -2,12 +2,29 @@
   import { HIT_AREA } from '../internal/touch.js';
   import CopyGlyph from '../internal/CopyGlyph.svelte';
   import { COPY_FAILED_MESSAGE, CopyState } from '../internal/copy.svelte.js';
+  import Tooltip from './Tooltip.svelte';
 
   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;
+    /**
+     * A tooltip on the button, shown on hover and on keyboard focus, such as
+     * "Copy the signing key". It never renames the button: the name stays
+     * `text`, or `label` on an icon alone. When it says more than the name, it
+     * becomes the button's accessible description.
+     */
+    title?: string;
     /** Announced and shown after a successful copy. */
     copiedLabel?: string;
     /** Icon size in px. */
@@ -18,11 +35,21 @@
   let {
     value,
     label = 'Copy',
+    text = undefined,
+    title = 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(() => {
@@ -32,6 +59,14 @@
   });
 
   $effect(() => () => copier.dispose());
+
+  /*
+   * A tooltip in the same words as the name would be announced twice, as
+   * "Copy, Copy", so it is described only when it adds something. Case and
+   * outer spaces change nothing a reader hears, so neither counts.
+   */
+  const spoken = (words: string) => words.trim().toLowerCase();
+  const describes = $derived(spoken(title ?? '') !== spoken(text || label));
 </script>
 
 <!--
@@ -44,20 +79,11 @@
   of its icon and a row of them lines up.
 -->
 <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.
-  -->
-  <button
-    type="button"
-    aria-label={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"
-  >
-    <CopyGlyph copied={copier.status === 'copied'} {size} />
-  </button>
+  {#if title}
+    <Tooltip text={title} describe={describes}>{@render button()}</Tooltip>
+  {:else}
+    {@render button()}
+  {/if}
 
   <span
     role="status"
@@ -66,3 +92,20 @@
     class="text-xs {copier.status === 'failed' ? 'text-danger' : 'text-success'}">{message}</span
   >
 </span>
+
+{#snippet button()}
+  <!--
+    The accessible name stays the same through the copied state, whether it
+    comes from `label` or from `text`. The live region beside it 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={text ? undefined : label}
+    onclick={() => copier.copy(value)}
+    class={text ? WITH_TEXT : ICON_ONLY}
+  >
+    <CopyGlyph copied={copier.status === 'copied'} {size} />{#if text}{text}{/if}
+  </button>
+{/snippet}

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

@@ -1,8 +1,24 @@
 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;
+    /**
+     * A tooltip on the button, shown on hover and on keyboard focus, such as
+     * "Copy the signing key". It never renames the button: the name stays
+     * `text`, or `label` on an icon alone. When it says more than the name, it
+     * becomes the button's accessible description.
+     */
+    title?: string;
     /** Announced and shown after a successful copy. */
     copiedLabel?: string;
     /** Icon size in px. */

package/dist/components/CopyField.svelte

@@ -18,6 +18,9 @@
    * `actions` adds the caller's own controls in the same row, before the
    * reveal and the copy: a rotate, a regenerate, a link out. They sit in the
    * field's own row, so any number of them fits without covering the value.
+   *
+   * `wrap` shows the whole value over as many lines as it takes, for a key or
+   * an address the reader has to check end to end rather than recognize.
    */
   import type { Snippet } from 'svelte';
   import { Eye, EyeOff } from '@lucide/svelte';
@@ -43,6 +46,13 @@
     mono?: boolean;
     /** Mask the value and offer a control that reveals it. */
     secret?: boolean;
+    /**
+     * Wraps the whole value across lines instead of showing one truncated
+     * line. It breaks anywhere, since a key or a token has no spaces to break
+     * at. A masked secret stays on one line, because its dots carry nothing
+     * to read, and wraps once revealed.
+     */
+    wrap?: boolean;
     /** Extra controls inside the field's end, before the reveal and the copy. */
     actions?: Snippet;
     /** The copy control's accessible name. Defaults to "Copy" and the label. */
@@ -60,6 +70,7 @@
     hint = undefined,
     mono = true,
     secret = false,
+    wrap = false,
     actions = undefined,
     copyLabel = undefined,
     copiedLabel = 'Copied',
@@ -73,6 +84,7 @@
   const copier = new CopyState();
   let revealed = $state(false);
   const masked = $derived(secret && !revealed);
+  const wrapped = $derived(wrap && !masked);
   const failed = $derived(copier.status === 'failed');
 
   $effect(() => () => copier.dispose());
@@ -86,23 +98,54 @@
   <!-- The frame is the control: the value and its buttons sit in one row
        inside it, so the caller's actions, the reveal and the copy all fit
        without the value running under them and without measuring anything.
-       The frame takes the focus ring and the brand border from the input
-       inside it. A focused button draws its own ring and not the frame's. -->
+       The frame takes the focus ring and the brand border from the input or
+       the textarea inside it. A focused button draws its own ring and not the frame's. -->
   <div
-    class="flex h-control w-full items-center gap-0.5 rounded-lg border bg-surface-2 pe-1 transition-colors border-line-strong has-[input:focus]:border-brand has-[input:focus-visible]:ring-2 has-[input:focus-visible]:ring-inset has-[input:focus-visible]:ring-brand"
+    class="flex w-full gap-0.5 rounded-lg border bg-surface-2 pe-1 transition-colors border-line-strong {wrapped
+      ? 'min-h-control items-start py-1 has-[textarea:focus]:border-brand has-[textarea:focus-visible]:ring-2 has-[textarea:focus-visible]:ring-inset has-[textarea:focus-visible]:ring-brand'
+      : 'h-control items-center has-[input:focus]:border-brand has-[input:focus-visible]:ring-2 has-[input:focus-visible]:ring-inset has-[input:focus-visible]:ring-brand'}"
   >
-    <input
-      id={fieldId}
-      type={masked ? 'password' : 'text'}
-      autocomplete="off"
-      readonly
-      {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'
-        : ''}"
-    />
+    {#if wrapped}
+      <!-- An input holds one line, so the wrapped value is a read-only
+           textarea. A textarea does not grow with its text, so it sits in one
+           grid cell with an invisible copy of the value, and the copy sets the
+           height. The padding and the frame's together keep one line at the
+           control height. -->
+      <div class="grid min-w-0 flex-1">
+        <span
+          aria-hidden="true"
+          class="invisible col-start-1 row-start-1 px-3 py-1 text-sm break-all whitespace-pre-wrap {mono
+            ? 'font-mono'
+            : ''}">{value}</span
+        >
+        <textarea
+          id={fieldId}
+          rows={1}
+          autocomplete="off"
+          spellcheck="false"
+          readonly
+          {value}
+          onfocus={(e) => e.currentTarget.select()}
+          aria-describedby={describedBy(fieldId, failed ? COPY_FAILED_MESSAGE : undefined, hint)}
+          class="col-start-1 row-start-1 resize-none overflow-hidden bg-transparent px-3 py-1 text-sm break-all whitespace-pre-wrap text-fg outline-none {mono
+            ? 'font-mono'
+            : ''}"
+        ></textarea>
+      </div>
+    {:else}
+      <input
+        id={fieldId}
+        type={masked ? 'password' : 'text'}
+        autocomplete="off"
+        readonly
+        {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'
+          : ''}"
+      />
+    {/if}
     {@render actions?.()}
     {#if secret}
       <button

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

@@ -17,6 +17,9 @@
    * `actions` adds the caller's own controls in the same row, before the
    * reveal and the copy: a rotate, a regenerate, a link out. They sit in the
    * field's own row, so any number of them fits without covering the value.
+   *
+   * `wrap` shows the whole value over as many lines as it takes, for a key or
+   * an address the reader has to check end to end rather than recognize.
    */
 import type { Snippet } from 'svelte';
 interface Props {
@@ -30,6 +33,13 @@ interface Props {
     mono?: boolean;
     /** Mask the value and offer a control that reveals it. */
     secret?: boolean;
+    /**
+     * Wraps the whole value across lines instead of showing one truncated
+     * line. It breaks anywhere, since a key or a token has no spaces to break
+     * at. A masked secret stays on one line, because its dots carry nothing
+     * to read, and wraps once revealed.
+     */
+    wrap?: boolean;
     /** Extra controls inside the field's end, before the reveal and the copy. */
     actions?: Snippet;
     /** The copy control's accessible name. Defaults to "Copy" and the label. */

package/dist/components/EmptyState.svelte

@@ -5,6 +5,12 @@
     icon?: string;
     iconSnippet?: Snippet;
     title: string;
+    /**
+     * The title's heading level. 3 by default, for a list inside a section. 2
+     * on a page whose only other heading is its title, so a screen reader does
+     * not meet a jump from h1 to h3.
+     */
+    level?: 2 | 3;
     description?: string;
     class?: string;
     action?: Snippet;
@@ -15,6 +21,7 @@
     icon = undefined,
     iconSnippet = undefined,
     title,
+    level = 3,
     description = undefined,
     class: klass = '',
     action,
@@ -40,7 +47,13 @@
       {icon}
     </div>
   {/if}
-  <h3 class="text-base font-semibold text-fg">{title}</h3>
+  <!-- Two branches rather than one dynamic element, as in SectionHeading:
+       a reader of this file can see both headings it can produce. -->
+  {#if level === 2}
+    <h2 class="text-base font-semibold text-fg">{title}</h2>
+  {:else}
+    <h3 class="text-base font-semibold text-fg">{title}</h3>
+  {/if}
   {#if description}
     <p class="mt-1 max-w-sm text-sm text-muted">{description}</p>
   {/if}

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

@@ -3,6 +3,12 @@ interface Props {
     icon?: string;
     iconSnippet?: Snippet;
     title: string;
+    /**
+     * The title's heading level. 3 by default, for a list inside a section. 2
+     * on a page whose only other heading is its title, so a screen reader does
+     * not meet a jump from h1 to h3.
+     */
+    level?: 2 | 3;
     description?: string;
     class?: string;
     action?: Snippet;