@lyeve-labs/ui-kit 0.37.0 → 0.38.1

package/README.md

@@ -259,13 +259,50 @@ two throws.
 />
 ```
 
+### 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. 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.
+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">

package/dist/components/CopyButton.svelte

@@ -2,6 +2,7 @@
   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. */
@@ -17,6 +18,13 @@
      * 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. */
@@ -28,6 +36,7 @@
     value,
     label = 'Copy',
     text = undefined,
+    title = undefined,
     copiedLabel = 'Copied',
     size = 14,
     class: klass = '',
@@ -50,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>
 
 <!--
@@ -62,11 +79,26 @@
   of its icon and a row of them lines up.
 -->
 <span class="inline-flex items-center {message ? 'gap-1.5' : ''} {klass}">
+  {#if title}
+    <Tooltip text={title} describe={describes}>{@render button()}</Tooltip>
+  {:else}
+    {@render button()}
+  {/if}
+
+  <span
+    role="status"
+    aria-live="polite"
+    aria-atomic="true"
+    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 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.
+    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"
@@ -76,11 +108,4 @@
   >
     <CopyGlyph copied={copier.status === 'copied'} {size} />{#if text}{text}{/if}
   </button>
-
-  <span
-    role="status"
-    aria-live="polite"
-    aria-atomic="true"
-    class="text-xs {copier.status === 'failed' ? 'text-danger' : 'text-success'}">{message}</span
-  >
-</span>
+{/snippet}

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

@@ -12,6 +12,13 @@ interface Props {
      * 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;

package/dist/components/FileInput.svelte

@@ -90,7 +90,7 @@
     <div class="text-sm">
       <span class="{error ? 'text-danger' : 'text-brand'} font-medium">Click to upload</span>
       <span class="text-muted"> or drag & drop</span>
-      {#if accept}<p class="mt-0.5 text-xs text-faint">{accept}</p>{/if}
+      {#if accept}<p class="mt-0.5 text-xs text-faint [overflow-wrap:anywhere]">{accept}</p>{/if}
     </div>
     <input
       type="file"

package/dist/components/FilterChips.svelte

@@ -36,6 +36,7 @@
    * 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';
 
@@ -47,6 +48,24 @@
     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;
@@ -57,6 +76,10 @@
     options,
     label,
     countLabel = '',
+    id = undefined,
+    hint = undefined,
+    error = undefined,
+    describedBy: callerIds = undefined,
     class: klass = '',
     onchange = undefined,
   }: Props = $props();
@@ -77,6 +100,15 @@
     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;
@@ -96,7 +128,25 @@
   }
 </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}
     {#if linked}
@@ -122,6 +172,11 @@
     {/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}

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

@@ -30,6 +30,24 @@ declare function $$render<T extends string>(): {
         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;

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

@@ -62,12 +62,16 @@
       Each size token names its own leading and tracking. A `text-*` token
       built from `--text-*` alone sets font-size and leaves line-height to
       whatever it inherits, which is not the ratio the ramp specifies.
+
+      A title can be a user value with no spaces, such as a tenant slug. It
+      breaks anywhere only when a word does not fit the line, so a title with
+      spaces still wraps at them, and a long slug no longer widens the page.
     -->
     <h1
       data-testid="page-title"
-      class={compact
+      class="[overflow-wrap:anywhere] {compact
         ? 'text-sm font-semibold text-fg'
-        : 'text-h2 leading-h2 tracking-h2 font-bold text-fg'}
+        : 'text-h2 leading-h2 tracking-h2 font-bold text-fg'}"
     >
       {title}
     </h1>

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,7 +21,14 @@
 </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';
 
@@ -39,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;
@@ -53,6 +78,10 @@
     options,
     label,
     labelHidden = false,
+    id = undefined,
+    hint = undefined,
+    error = undefined,
+    describedBy: callerIds = undefined,
     name = undefined,
     size = 'md',
     disabled = false,
@@ -76,6 +105,15 @@
     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();
 
   /*
@@ -188,15 +226,20 @@
 
   <!-- 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}
@@ -267,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";

package/dist/components/Select.svelte

@@ -53,6 +53,7 @@
     FIELD_WRAP,
     controlBorder,
     describedBy,
+    joinIds,
   } from '../internal/field.js';
   import { createListbox } from '../internal/listbox.svelte.js';
   import {
@@ -75,6 +76,12 @@
     required?: boolean;
     disabled?: boolean;
     error?: string;
+    /**
+     * Ids of other elements that describe the control, separated by spaces,
+     * such as the message a wrapping Field renders. They are read after the
+     * control's own hint or error.
+     */
+    describedBy?: string;
     class?: string;
     /** The rows, as data. */
     options?: SelectOption[];
@@ -102,6 +109,7 @@
     required = false,
     disabled = false,
     error,
+    describedBy: callerIds,
     class: cls = '',
     options = [],
     searchable = false,
@@ -312,7 +320,7 @@
       }}
       aria-invalid={error ? 'true' : undefined}
       aria-required={required ? 'true' : undefined}
-      aria-describedby={describedBy(fieldId, error, hint)}
+      aria-describedby={joinIds(describedBy(fieldId, error, hint), callerIds)}
       {...box.triggerAttrs}
       class="{CONTROL_BASE} {controlBorder(!!error)} flex cursor-pointer items-center gap-2 pe-8
           text-start"

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

@@ -53,6 +53,12 @@ interface Props {
     required?: boolean;
     disabled?: boolean;
     error?: string;
+    /**
+     * Ids of other elements that describe the control, separated by spaces,
+     * such as the message a wrapping Field renders. They are read after the
+     * control's own hint or error.
+     */
+    describedBy?: string;
     class?: string;
     /** The rows, as data. */
     options?: SelectOption[];

package/dist/index.d.ts

@@ -103,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.37.0";
+export declare const VERSION = "0.38.1";

package/dist/index.js

@@ -116,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.37.0';
+export const VERSION = '0.38.1';

package/dist/internal/field.d.ts

@@ -105,3 +105,11 @@ export declare function segmentedBorder(error: boolean): string;
  * by the wrapper's own rounding.
  */
 export declare const CONTROL_SEGMENT: string;
+/**
+ * Joins a control's own message id with the ids its caller names.
+ *
+ * A control inside a Field, or explained by text elsewhere on the page, has to
+ * point at that text as well as at its own hint or error. Returns undefined
+ * when there is nothing to point at, for the reason describedBy does.
+ */
+export declare function joinIds(...ids: (string | undefined)[]): string | undefined;

package/dist/internal/field.js

@@ -134,3 +134,13 @@ export function segmentedBorder(error) {
 export const CONTROL_SEGMENT = 'shrink-0 rounded-sm border-0 bg-transparent p-0 text-center text-sm text-fg tabular-nums ' +
     'outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand ' +
     'disabled:cursor-not-allowed';
+/**
+ * Joins a control's own message id with the ids its caller names.
+ *
+ * A control inside a Field, or explained by text elsewhere on the page, has to
+ * point at that text as well as at its own hint or error. Returns undefined
+ * when there is nothing to point at, for the reason describedBy does.
+ */
+export function joinIds(...ids) {
+    return ids.filter(Boolean).join(' ') || undefined;
+}

package/package.json

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