@lyeve-labs/ui-kit 0.11.2 → 0.13.0

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

@@ -0,0 +1,34 @@
+/**
+   * Key and value pairs, as a real description list.
+   *
+   * Detail pages laid these out with ad hoc grids of divs, which broke
+   * alignment between two pages showing the same record and, more importantly,
+   * conveyed nothing: a grid of divs has no relationship between a label and
+   * the value under it, so a screen reader reads a run of unattached strings
+   * and the listener has to infer which value belongs to which term. `dl`,
+   * `dt` and `dd` state that relationship in the markup, and it is the whole
+   * reason this component exists.
+   *
+   * A long value wraps. It is never truncated, because a clipped identifier
+   * cannot be read out, cannot be selected and cannot be copied, and an id or
+   * a key is exactly the kind of value a detail page is opened for. `break-words`
+   * covers the unbroken ones, so a token or a hash wraps instead of pushing the
+   * page sideways.
+   */
+import type { Snippet } from 'svelte';
+interface Item {
+    term: string;
+    value: string;
+    /** Rendered instead of value when present. */
+    detail?: Snippet;
+}
+type Layout = 'inline' | 'stacked';
+interface Props {
+    items: Item[];
+    /** 'inline' puts the term and value on one row, 'stacked' puts the value under the term. */
+    layout?: Layout;
+    class?: string;
+}
+declare const DescriptionList: import("svelte").Component<Props, {}, "">;
+type DescriptionList = ReturnType<typeof DescriptionList>;
+export default DescriptionList;

package/dist/components/Drawer.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  import { overlay } from '../internal/overlay.js';
 
   type Side = 'left' | 'right';
   type Size = 'sm' | 'md' | 'lg' | 'xl';
@@ -33,6 +34,9 @@
     xl: 'w-[480px]',
   };
 
+  const headingId = $props.id();
+  const descriptionId = `${headingId}-description`;
+
   function close() {
     open = false;
     onclose?.();
@@ -52,25 +56,32 @@
   <div class="fixed inset-0 z-50 flex {side === 'right' ? 'justify-end' : 'justify-start'}">
     <button
       type="button"
+      tabindex="-1"
+      aria-hidden="true"
       class="absolute inset-0 bg-black/60 backdrop-blur-sm cursor-default"
-      aria-label="Close"
       onclick={close}
     ></button>
 
     <div
-      class="relative flex h-full flex-col {widths[size]} bg-surface shadow-2xl
+      use:overlay
+      class="relative flex h-full max-w-full flex-col {widths[size]} bg-surface shadow-2xl
         {side === 'right' ? 'border-l' : 'border-r'} border-line
         {side === 'right'
         ? 'animate-[drawer-in-right_150ms_ease-out]'
         : 'animate-[drawer-in-left_150ms_ease-out]'}"
       role="dialog"
       aria-modal="true"
+      aria-labelledby={title ? headingId : undefined}
+      aria-describedby={description ? descriptionId : undefined}
+      aria-label={title ? undefined : 'Panel'}
     >
       {#if title}
         <div class="flex shrink-0 items-start justify-between gap-4 border-b border-line px-5 py-4">
           <div>
-            <h2 class="font-semibold text-fg">{title}</h2>
-            {#if description}<p class="mt-0.5 text-sm text-muted">{description}</p>{/if}
+            <h2 id={headingId} class="font-semibold text-fg">{title}</h2>
+            {#if description}
+              <p id={descriptionId} class="mt-0.5 text-sm text-muted">{description}</p>
+            {/if}
           </div>
           <button
             type="button"

package/dist/components/Field.svelte

@@ -0,0 +1,104 @@
+<script lang="ts" module>
+  /**
+   * What Field hands the control it wraps.
+   *
+   * The wiring is the whole point of the component. A consumer building a
+   * control the kit does not ship - a colour well, a code editor, a third
+   * party map picker - cannot reach internal/field.ts, so it hand-copies the
+   * class strings and stops there: a form in a consuming app spelled
+   * `class="flex flex-col gap-1.5"` inline, which is the literal value of
+   * FIELD_WRAP, and then wired nothing. The control had no id, the label had
+   * no `for`, and the error paragraph under it was never announced.
+   */
+  export interface FieldWiring {
+    /** The id the control must carry. The label's `for` already points at it. */
+    id: string;
+    /**
+     * The id of whichever message is on screen, for the control's
+     * `aria-describedby`. Undefined when there is neither a hint nor an error,
+     * so the attribute is left off rather than pointing at nothing.
+     */
+    describedBy: string | undefined;
+    /** True while an error is showing, for the control's `aria-invalid`. */
+    invalid: boolean;
+  }
+</script>
+
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import {
+    FIELD_ERROR,
+    FIELD_HINT,
+    FIELD_LABEL,
+    FIELD_WRAP,
+    describedBy,
+  } from '../internal/field.js';
+
+  interface Props {
+    /** Overrides the generated id, for a control the caller has to address by name. */
+    id?: string;
+    label?: string;
+    /** Screen-reader-only label, for a control whose visible name is a table column header. */
+    labelHidden?: boolean;
+    hint?: string;
+    /** Replaces the hint while it is set, and marks the wiring invalid. */
+    error?: string;
+    /**
+     * Draws the marker beside the label. Set `required` on the control as well:
+     * the marker is decorative and the control's own attribute is what a screen
+     * reader reports.
+     */
+    required?: boolean;
+    class?: string;
+    /** Receives what the control must carry so the message row actually reaches a screen reader. */
+    children: Snippet<[FieldWiring]>;
+  }
+
+  let {
+    id = undefined,
+    label = undefined,
+    labelHidden = false,
+    hint = undefined,
+    error = undefined,
+    required = false,
+    class: klass = '',
+    children,
+  }: Props = $props();
+
+  /*
+   * $props.id(), never Math.random(). A random id is one value in the server
+   * render and a different one on hydration, so the label's `for` and the id
+   * the control was given stop matching the moment the client takes over, and
+   * clicking the label focuses nothing.
+   */
+  const uid = $props.id();
+  const fieldId = $derived(id ?? uid);
+
+  const wiring: FieldWiring = $derived({
+    id: fieldId,
+    describedBy: describedBy(fieldId, error, hint),
+    invalid: !!error,
+  });
+</script>
+
+<div class="{FIELD_WRAP} {klass}">
+  {#if label}
+    <!--
+      A hidden label stays a real label with a real `for`. Swapping it for an
+      aria-label on the control would name the control and drop the name out of
+      the reading order, so a reader moving through a row of them would meet
+      the controls with nothing ahead of them saying what each one is.
+    -->
+    <label for={fieldId} class="{FIELD_LABEL} {labelHidden ? 'sr-only' : ''}">
+      {label}{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span>{/if}
+    </label>
+  {/if}
+
+  {@render children(wiring)}
+
+  {#if error}
+    <p id="{fieldId}-error" class={FIELD_ERROR}>{error}</p>
+  {:else if hint}
+    <p id="{fieldId}-hint" class={FIELD_HINT}>{hint}</p>
+  {/if}
+</div>

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

@@ -0,0 +1,46 @@
+/**
+ * What Field hands the control it wraps.
+ *
+ * The wiring is the whole point of the component. A consumer building a
+ * control the kit does not ship - a colour well, a code editor, a third
+ * party map picker - cannot reach internal/field.ts, so it hand-copies the
+ * class strings and stops there: a form in a consuming app spelled
+ * `class="flex flex-col gap-1.5"` inline, which is the literal value of
+ * FIELD_WRAP, and then wired nothing. The control had no id, the label had
+ * no `for`, and the error paragraph under it was never announced.
+ */
+export interface FieldWiring {
+    /** The id the control must carry. The label's `for` already points at it. */
+    id: string;
+    /**
+     * The id of whichever message is on screen, for the control's
+     * `aria-describedby`. Undefined when there is neither a hint nor an error,
+     * so the attribute is left off rather than pointing at nothing.
+     */
+    describedBy: string | undefined;
+    /** True while an error is showing, for the control's `aria-invalid`. */
+    invalid: boolean;
+}
+import type { Snippet } from 'svelte';
+interface Props {
+    /** Overrides the generated id, for a control the caller has to address by name. */
+    id?: string;
+    label?: string;
+    /** Screen-reader-only label, for a control whose visible name is a table column header. */
+    labelHidden?: boolean;
+    hint?: string;
+    /** Replaces the hint while it is set, and marks the wiring invalid. */
+    error?: string;
+    /**
+     * Draws the marker beside the label. Set `required` on the control as well:
+     * the marker is decorative and the control's own attribute is what a screen
+     * reader reports.
+     */
+    required?: boolean;
+    class?: string;
+    /** Receives what the control must carry so the message row actually reaches a screen reader. */
+    children: Snippet<[FieldWiring]>;
+}
+declare const Field: import("svelte").Component<Props, {}, "">;
+type Field = ReturnType<typeof Field>;
+export default Field;

package/dist/components/FileInput.svelte

@@ -51,7 +51,10 @@
     <label for={id} class={FIELD_LABEL}>{label}</label>
   {/if}
 
-  <!-- svelte-ignore a11y_no_static_element_interactions -->
+  <!-- The dashed border is the only thing marking this region as a control, so
+       it rests on line-strong: line reads 1.25:1 and failed SC 1.4.11. The
+       hover is full-strength brand, because a focus-adjacent colour dropped to
+       half alpha reads as a weaker affordance for no reason a user can infer. -->
   <label
     class="flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-xl
       border-2 border-dashed px-4 py-8 text-center transition-colors duration-150
@@ -59,7 +62,7 @@
       ? 'border-danger bg-danger/5 hover:bg-danger/8'
       : dragOver
         ? 'border-brand bg-brand/8'
-        : 'border-line bg-surface-2/40 hover:border-brand/50 hover:bg-brand/5'}
+        : 'border-line-strong bg-surface-2/40 hover:border-brand hover:bg-brand/5'}
       {disabled ? 'cursor-not-allowed opacity-50' : ''}"
     ondragover={(e) => {
       e.preventDefault();

package/dist/components/FormMessage.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+  import { TONE_GLYPH } from '../internal/tone.js';
+
+  /** The two outcomes a submit has. Anything else is a hint, not a result. */
+  type Tone = 'danger' | 'success';
+
+  interface Props {
+    tone?: Tone;
+    class?: string;
+    children: Snippet;
+  }
+
+  let { tone = 'danger', class: klass = '', children }: Props = $props();
+
+  /**
+   * The message colour, stated once.
+   *
+   * Eleven pages rendered a submit outcome into a bare paragraph and picked
+   * their own size and colour for it, so the same failure read as three
+   * different things depending on which settings page the user was on.
+   */
+  const tones: Record<Tone, string> = {
+    danger: 'text-danger',
+    success: 'text-success',
+  };
+
+  /**
+   * A live region reports a CHANGE to what it holds. A region that arrives in
+   * the document with its text already inside it is not a change, and nothing
+   * is read out: that is why every toast was silent while each toast carried
+   * its own role="status". Toaster fixed it by keeping one region mounted for
+   * the life of the app and moving each toast into it.
+   *
+   * A submit outcome has no such permanent host, because the page mounts this
+   * component at the moment the submit resolves. So the region goes in empty
+   * and the message is placed inside it on the next frame, which is the same
+   * shape of change a toast makes.
+   *
+   * The server runs no effect and has no frames, so it renders the message
+   * straight away: a page delivered without its client bundle still carries
+   * the outcome of the submit, which matters more than announcing it.
+   */
+  let filled = $state(typeof window === 'undefined');
+
+  $effect(() => {
+    const frame = requestAnimationFrame(() => (filled = true));
+    return () => cancelAnimationFrame(frame);
+  });
+</script>
+
+<!--
+  The tones differ in more than colour. A failure takes role="alert", which
+  interrupts whatever the reader is doing, because the submit did not go
+  through and the user has to act on it. A confirmation takes aria-live
+  "polite" and waits for a pause, because the work is done and nothing is being
+  asked of anyone.
+-->
+<div
+  class="flex items-start gap-2 text-sm {tones[tone]} {klass}"
+  role={tone === 'danger' ? 'alert' : 'status'}
+  aria-live={tone === 'danger' ? 'assertive' : 'polite'}
+>
+  {#if filled}
+    <!-- Stroked SVG, not a literal cross or tick: a font glyph lands at
+         whatever weight the reader's font gives it, which sat visibly lighter
+         than every other icon in the library. Colour alone would also be the
+         only thing telling a failure from a confirmation. -->
+    <svg
+      class="mt-0.5 shrink-0"
+      width="15"
+      height="15"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2.5"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path d={TONE_GLYPH[tone]} />
+    </svg>
+    <p class="min-w-0 flex-1">{@render children()}</p>
+  {/if}
+</div>

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

@@ -0,0 +1,11 @@
+import type { Snippet } from 'svelte';
+/** The two outcomes a submit has. Anything else is a hint, not a result. */
+type Tone = 'danger' | 'success';
+interface Props {
+    tone?: Tone;
+    class?: string;
+    children: Snippet;
+}
+declare const FormMessage: import("svelte").Component<Props, {}, "">;
+type FormMessage = ReturnType<typeof FormMessage>;
+export default FormMessage;

package/dist/components/Input.svelte

@@ -54,7 +54,7 @@
 <div class="{FIELD_WRAP} {klass}">
   {#if label}
     <label for={fieldId} class={FIELD_LABEL}>
-      {label}{#if required}<span class="text-danger ml-0.5" aria-label="required">*</span>{/if}
+      {label}{#if required}<span class="text-danger ml-0.5" aria-hidden="true">*</span>{/if}
     </label>
   {/if}
 

package/dist/components/Label.svelte

@@ -9,6 +9,12 @@
     children,
   }: {
     for?: string;
+    /**
+     * Draws the marker beside the text. Set `required` on the control this
+     * label points at as well: the marker is decorative, and the control's own
+     * attribute is what a screen reader reports. A label is read in full to
+     * name what it points at, so anything said here lands in that name.
+     */
     required?: boolean;
     hint?: string;
     class?: string;
@@ -22,7 +28,7 @@
 >
   {@render children()}
   {#if required}
-    <span class="text-danger font-bold leading-none" aria-label="required">*</span>
+    <span class="text-danger font-bold leading-none" aria-hidden="true">*</span>
   {/if}
   {#if hint}
     <span class="text-faint normal-case font-normal ml-0.5">({hint})</span>

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

@@ -1,6 +1,12 @@
 import type { Snippet } from 'svelte';
 type $$ComponentProps = {
     for?: string;
+    /**
+     * Draws the marker beside the text. Set `required` on the control this
+     * label points at as well: the marker is decorative, and the control's own
+     * attribute is what a screen reader reports. A label is read in full to
+     * name what it points at, so anything said here lands in that name.
+     */
     required?: boolean;
     hint?: string;
     class?: string;

package/dist/components/Modal.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
   import type { Snippet } from 'svelte';
+  import { overlay } from '../internal/overlay.js';
 
   type Size = 'sm' | 'md' | 'lg';
 
@@ -29,6 +30,11 @@
     lg: 'max-w-2xl',
   };
 
+  // aria-labelledby needs an id that is unique per instance, because two modals
+  // can be mounted at once while one animates out.
+  const headingId = $props.id();
+  const descriptionId = `${headingId}-description`;
+
   function close() {
     open = false;
     onclose?.();
@@ -48,27 +54,38 @@
   <div class="fixed inset-0 z-50 flex items-center justify-center p-4">
     <button
       type="button"
+      tabindex="-1"
+      aria-hidden="true"
       class="absolute inset-0 bg-black/60 backdrop-blur-sm cursor-default"
-      aria-label="Close"
       onclick={close}
     ></button>
 
     <div
-      class="relative w-full {widths[size]} rounded-xl border border-line bg-surface shadow-2xl
+      use:overlay
+      class="relative flex max-h-[calc(100dvh-2rem)] w-full {widths[size]} flex-col
+             overflow-hidden rounded-xl border border-line bg-surface shadow-2xl
              animate-[modal-in_120ms_ease-out]"
       role="dialog"
       aria-modal="true"
+      aria-labelledby={title ? headingId : undefined}
+      aria-describedby={description ? descriptionId : undefined}
+      aria-label={title ? undefined : 'Dialog'}
     >
       {#if title}
-        <div class="flex items-start justify-between gap-4 px-5 py-4 border-b border-line">
+        <div
+          class="flex shrink-0 items-start justify-between gap-4 px-5 py-4 border-b border-line"
+        >
           <div>
-            <h2 class="font-semibold text-fg">{title}</h2>
-            {#if description}<p class="text-sm text-muted mt-0.5">{description}</p>{/if}
+            <h2 id={headingId} class="font-semibold text-fg">{title}</h2>
+            {#if description}
+              <p id={descriptionId} class="text-sm text-muted mt-0.5">{description}</p>
+            {/if}
           </div>
           <button
             type="button"
             onclick={close}
-            class="shrink-0 text-faint transition-colors duration-150 hover:text-fg"
+            class="shrink-0 rounded text-faint transition-colors duration-150 hover:text-fg
+                   outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand"
             aria-label="Close"
           >
             <svg
@@ -85,13 +102,13 @@
         </div>
       {/if}
 
-      <div class="px-5 py-4">
+      <div class="min-h-0 flex-1 overflow-y-auto px-5 py-4">
         {@render children()}
       </div>
 
       {#if footer}
         <div
-          class="flex items-center justify-end gap-2 px-5 py-3 border-t border-line bg-surface-2/40"
+          class="flex shrink-0 items-center justify-end gap-2 px-5 py-3 border-t border-line bg-surface-2/40"
         >
           {@render footer()}
         </div>