@lyeve-labs/ui-kit 0.12.1 → 0.13.0

package/dist/components/Autocomplete.svelte

@@ -1,4 +1,36 @@
+<script lang="ts" module>
+  import type { ListboxItem } from '../internal/listbox.svelte.js';
+
+  /**
+   * One row of a filterable option list.
+   *
+   * Declared here and imported by MultiSelect, which carried the same interface
+   * written out character for character. Two declarations are two chances to
+   * answer the same question differently, and these two had already drifted
+   * apart in what they let a consumer say: neither could describe a row by
+   * anything but its label, so an option a user knows by a code or a synonym
+   * could not be found by typing it.
+   */
+  export interface ListOption extends ListboxItem {
+    /**
+     * Extra words the default matcher searches alongside the label. Absent on
+     * every option that ships today, so adopting it narrows no existing list.
+     */
+    keywords?: readonly string[];
+  }
+</script>
+
 <script lang="ts">
+  /**
+   * A combobox: type to narrow the list, arrow through what is left, Enter to
+   * choose.
+   *
+   * The open state, the active row, the keyboard model and the dismissal come
+   * from internal/listbox, the matching from internal/filter and every class in
+   * the panel from internal/panel. What stays here is the one thing a combobox
+   * owns: whether the input is showing a query being typed or the label of the
+   * row already chosen.
+   */
   import {
     CONTROL_BASE,
     FIELD_ERROR,
@@ -8,12 +40,31 @@
     controlBorder,
     describedBy,
   } from '../internal/field.js';
-  // Autocomplete (combobox): type to filter a list, navigate with ↑/↓, select with
-  // Enter. Binds `value` to the chosen option's value; shows its label in the input.
-  interface Option {
-    value: string;
-    label: string;
+  import { applyFilter, type FilterInput } from '../internal/filter.js';
+  import { createListbox } from '../internal/listbox.svelte.js';
+  import { PANEL_EMPTY, PANEL_LIST, PANEL_SURFACE, panelOption } from '../internal/panel.js';
+
+  interface Props {
+    /** The chosen option's value. Empty for none. */
+    value?: string;
+    options: ListOption[];
+    label?: string;
+    hint?: string;
+    error?: string;
+    placeholder?: string;
     disabled?: boolean;
+    required?: boolean;
+    id?: string;
+    name?: string;
+    /** Offers a button that empties the field. */
+    allowClear?: boolean;
+    /**
+     * Replaces the default matcher, or false to switch local filtering off
+     * because the list arrived already narrowed, by a server query for instance.
+     */
+    filter?: FilterInput<ListOption>;
+    class?: string;
+    onchange?: (value: string) => void;
   }
 
   let {
@@ -28,126 +79,123 @@
     id = undefined,
     name = undefined,
     allowClear = true,
+    filter = undefined,
     class: cls = '',
     onchange = undefined,
-  }: {
-    value?: string;
-    options: Option[];
-    label?: string;
-    hint?: string;
-    error?: string;
-    placeholder?: string;
-    disabled?: boolean;
-    required?: boolean;
-    id?: string;
-    name?: string;
-    allowClear?: boolean;
-    class?: string;
-    onchange?: (value: string) => void;
-  } = $props();
+  }: Props = $props();
 
-  const uid = `ac-${Math.random().toString(36).slice(2, 9)}`;
-  const listId = $derived(id ? `${id}-list` : uid);
+  /*
+   * $props.id() and not a random string: a random id differs between the server
+   * render and hydration, so the aria-controls this field emitted named an
+   * element the client had never rendered and the relationship was dropped in
+   * silence. Every idref in the panel is built from this one.
+   */
+  const uid = $props.id();
+  const fieldId = $derived(id ?? uid);
 
-  let open = $state(false);
   let query = $state('');
-  let active = $state(0); // highlighted index
-  let containerEl: HTMLDivElement | undefined = $state();
-  let dirty = $state(false); // user is editing the query vs. showing the selected label
+  /** Whether the input holds a query being typed or the chosen row's label. */
+  let dirty = $state(false);
+  let inputEl = $state<HTMLInputElement | undefined>();
+  let fieldEl = $state<HTMLDivElement | undefined>();
 
-  const selectedLabel = $derived(options.find((o) => o.value === value)?.label ?? '');
+  const selectedLabel = $derived(options.find((option) => option.value === value)?.label ?? '');
   const display = $derived(dirty ? query : selectedLabel);
-  const filtered = $derived(
-    dirty && query.trim()
-      ? options.filter((o) => o.label.toLowerCase().includes(query.trim().toLowerCase()))
-      : options,
-  );
-
-  function choose(opt: Option) {
-    if (opt.disabled) return;
-    value = opt.value;
-    onchange?.(opt.value);
-    query = '';
-    dirty = false;
-    open = false;
+  // Not narrowed until the user types: opening the field shows the whole list,
+  // with the row already chosen under the ring.
+  const rows = $derived(applyFilter(options, dirty ? query : '', filter));
+
+  // No typeahead: every letter here is query text, and a second matcher jumping
+  // the active row would fight the filter for the same keys.
+  const box = createListbox<ListOption>({
+    items: () => rows,
+    baseId: () => fieldId,
+    onSelect: (option) => choose(option),
+    onClose: () => {
+      // The input goes back to showing what is chosen. A dismissed query left
+      // on screen reads as a value the field does not hold.
+      query = '';
+      dirty = false;
+    },
+  });
+
+  const anchor = box.anchor;
+  const panel = box.panel;
+
+  function choose(option: ListOption): void {
+    if (option.disabled === true) return;
+    value = option.value;
+    onchange?.(option.value);
+    // The factory leaves the list open, because a multi-value control collects
+    // several picks in one pass. This one takes a single value.
+    box.close('select');
   }
 
-  function clear() {
+  function clear(): void {
     value = '';
     query = '';
     dirty = false;
     onchange?.('');
+    // The button is about to unmount with focus on it, which would drop focus
+    // to the body and leave a keyboard user at the top of the page.
+    inputEl?.focus();
   }
 
-  function onInput(e: Event & { currentTarget: HTMLInputElement }) {
-    query = e.currentTarget.value;
+  function search(event: Event & { currentTarget: HTMLInputElement }): void {
+    query = event.currentTarget.value;
     dirty = true;
-    open = true;
-    active = 0;
+    // The keyboard must not rest on a row the new query pushed out from under
+    // it: aria-activedescendant would name one option while the ring is drawn
+    // on another. Cleared first, so openList lands on the first row that still
+    // matches rather than on whatever now sits at the old index.
+    box.setActive(-1);
+    box.openList();
   }
 
-  function onKeydown(e: KeyboardEvent) {
-    if (e.key === 'ArrowDown') {
-      e.preventDefault();
-      open = true;
-      active = Math.min(active + 1, filtered.length - 1);
-    } else if (e.key === 'ArrowUp') {
-      e.preventDefault();
-      active = Math.max(active - 1, 0);
-    } else if (e.key === 'Enter') {
-      if (open && filtered[active]) {
-        e.preventDefault();
-        choose(filtered[active]);
-      }
-    } else if (e.key === 'Escape') {
-      open = false;
-      dirty = false;
-      query = '';
-    }
-  }
+  function onFocus(event: FocusEvent): void {
+    // Focus arriving from inside the field is focus coming back, not the user
+    // entering it. Escape hands focus from a row to the input, and reopening on
+    // that would undo the dismissal the user had just asked for.
+    const from = event.relatedTarget;
+    if (from instanceof Node && fieldEl?.contains(from) === true) return;
 
-  function handleOutside(e: MouseEvent) {
-    if (containerEl && !containerEl.contains(e.target as Node)) {
-      open = false;
-      dirty = false;
-      query = '';
-    }
+    // Opening on the row the field already holds, so the first ArrowDown moves
+    // from the current value rather than from the top of the list.
+    const index = rows.findIndex((option) => option.value === value);
+    box.openList(index >= 0 ? index : undefined);
   }
-
-  $effect(() => {
-    if (open) document.addEventListener('click', handleOutside, { capture: true });
-    return () => document.removeEventListener('click', handleOutside, { capture: true });
-  });
 </script>
 
-<div class="{FIELD_WRAP} {cls}" bind:this={containerEl}>
+<div class="{FIELD_WRAP} {cls}">
   {#if label}
-    <label for={id} class={FIELD_LABEL}>
-      {label}{#if required}<span class="text-danger ml-0.5" aria-label="required">*</span>{/if}
+    <label for={fieldId} class={FIELD_LABEL}>
+      {label}{#if required}<span class="ml-0.5 text-danger" aria-hidden="true">*</span>{/if}
     </label>
   {/if}
 
-  <div class="relative">
+  <div class="relative" bind:this={fieldEl} use:anchor>
     <input
-      {id}
+      bind:this={inputEl}
+      id={fieldId}
       {name}
       {placeholder}
       {disabled}
       {required}
       role="combobox"
-      aria-expanded={open}
-      aria-controls={listId}
       aria-autocomplete="list"
       autocomplete="off"
       value={display}
-      oninput={onInput}
-      onkeydown={onKeydown}
-      onfocus={() => (open = true)}
-      onblur={() => setTimeout(() => (open = false), 150)}
+      oninput={search}
+      onfocus={onFocus}
+      onkeydown={(event) => {
+        box.onkeydown(event);
+      }}
       aria-invalid={error ? 'true' : undefined}
-      aria-describedby={describedBy(id, error, hint)}
+      aria-describedby={describedBy(fieldId, error, hint)}
+      {...box.triggerAttrs}
       class="{CONTROL_BASE} {controlBorder(!!error)} {allowClear && value ? 'pr-8' : 'pr-3'}"
     />
+
     {#if allowClear && value && !disabled}
       <button
         type="button"
@@ -170,49 +218,67 @@
       </button>
     {/if}
 
-    {#if open}
-      <div
-        id={listId}
-        role="listbox"
-        class="absolute z-50 mt-1 w-full max-h-60 overflow-y-auto rounded-xl border border-line
-          bg-surface shadow-2xl py-1"
-      >
-        {#each filtered as opt, i (opt.value)}
-          <button
-            type="button"
-            role="option"
-            aria-selected={opt.value === value}
-            disabled={opt.disabled}
-            onmouseenter={() => (active = i)}
-            onclick={() => choose(opt)}
-            class="w-full flex items-center justify-between px-3 py-2 text-sm text-left transition-colors duration-150
-              disabled:opacity-40 disabled:cursor-not-allowed
-              {i === active ? 'bg-surface-2' : ''}
-              {opt.value === value ? 'text-brand' : 'text-fg'}"
-          >
-            <span>{opt.label}</span>
-            {#if opt.value === value}
-              <svg width="12" height="10" viewBox="0 0 12 10" fill="none" aria-hidden="true">
-                <path
-                  d="M1 5l3.5 3.5L11 1.5"
-                  stroke="currentColor"
-                  stroke-width="1.5"
-                  stroke-linecap="round"
-                  stroke-linejoin="round"
-                />
-              </svg>
-            {/if}
-          </button>
-        {:else}
-          <p class="px-3 py-2 text-sm text-faint">No matches</p>
-        {/each}
+    {#if box.open}
+      <div class="{PANEL_SURFACE} w-full">
+        <div class={PANEL_LIST} use:panel {...box.listAttrs}>
+          {#each rows as option, index (option.value)}
+            {@const isSelected = option.value === value}
+            <!--
+              role is stated here as well as spread. The compiler checks
+              aria-selected against the role it can see in the source and it
+              cannot see into a spread, so without this the row reads to it as a
+              plain button carrying an attribute a button does not support.
+            -->
+            <button
+              type="button"
+              role="option"
+              onclick={() => choose(option)}
+              onmouseenter={() => box.setActive(index)}
+              onmousedown={(event) => {
+                // Pressing a row must not pull focus out of the input: the
+                // caret stays where the user is typing, and the field never
+                // has to be given focus back after a pick.
+                event.preventDefault();
+              }}
+              aria-selected={isSelected ? 'true' : 'false'}
+              {...box.optionAttrs(index)}
+              class={panelOption({
+                active: box.activeIndex === index,
+                selected: isSelected,
+                disabled: option.disabled === true,
+              })}
+            >
+              <span class="min-w-0 truncate">{option.label}</span>
+              {#if isSelected}
+                <svg
+                  width="12"
+                  height="10"
+                  viewBox="0 0 12 10"
+                  fill="none"
+                  class="ml-auto shrink-0"
+                  aria-hidden="true"
+                >
+                  <path
+                    d="M1 5l3.5 3.5L11 1.5"
+                    stroke="currentColor"
+                    stroke-width="1.5"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  />
+                </svg>
+              {/if}
+            </button>
+          {:else}
+            <p class={PANEL_EMPTY}>No matches</p>
+          {/each}
+        </div>
       </div>
     {/if}
   </div>
 
   {#if error}
-    <p id={id ? `${id}-error` : undefined} class={FIELD_ERROR}>{error}</p>
+    <p id="{fieldId}-error" class={FIELD_ERROR}>{error}</p>
   {:else if hint}
-    <p id={id ? `${id}-hint` : undefined} class={FIELD_HINT}>{hint}</p>
+    <p id="{fieldId}-hint" class={FIELD_HINT}>{hint}</p>
   {/if}
 </div>

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

@@ -1,11 +1,26 @@
-interface Option {
-    value: string;
-    label: string;
-    disabled?: boolean;
+import type { ListboxItem } from '../internal/listbox.svelte.js';
+/**
+ * One row of a filterable option list.
+ *
+ * Declared here and imported by MultiSelect, which carried the same interface
+ * written out character for character. Two declarations are two chances to
+ * answer the same question differently, and these two had already drifted
+ * apart in what they let a consumer say: neither could describe a row by
+ * anything but its label, so an option a user knows by a code or a synonym
+ * could not be found by typing it.
+ */
+export interface ListOption extends ListboxItem {
+    /**
+     * Extra words the default matcher searches alongside the label. Absent on
+     * every option that ships today, so adopting it narrows no existing list.
+     */
+    keywords?: readonly string[];
 }
-type $$ComponentProps = {
+import { type FilterInput } from '../internal/filter.js';
+interface Props {
+    /** The chosen option's value. Empty for none. */
     value?: string;
-    options: Option[];
+    options: ListOption[];
     label?: string;
     hint?: string;
     error?: string;
@@ -14,10 +29,16 @@ type $$ComponentProps = {
     required?: boolean;
     id?: string;
     name?: string;
+    /** Offers a button that empties the field. */
     allowClear?: boolean;
+    /**
+     * Replaces the default matcher, or false to switch local filtering off
+     * because the list arrived already narrowed, by a server query for instance.
+     */
+    filter?: FilterInput<ListOption>;
     class?: string;
     onchange?: (value: string) => void;
-};
-declare const Autocomplete: import("svelte").Component<$$ComponentProps, {}, "value">;
+}
+declare const Autocomplete: import("svelte").Component<Props, {}, "value">;
 type Autocomplete = ReturnType<typeof Autocomplete>;
 export default Autocomplete;

package/dist/components/Card.svelte

@@ -1,11 +1,31 @@
 <script lang="ts">
-  import type { Snippet } from 'svelte';
+  import type { Component, Snippet } from 'svelte';
+  import { sectionHeading } from '../internal/layout.js';
 
   type Pad = 'none' | 'sm' | 'md' | 'lg';
 
   interface Props {
     title?: string;
     description?: string;
+    /**
+     * The card's own section heading.
+     *
+     * The header band has three ways in, and they resolve in this order:
+     * `header` wins over everything, then `heading`, then `title`. A caller who
+     * hands a snippet has already decided what the band contains, so the
+     * component adds nothing to it. `heading` renders the icon, a real heading
+     * element at the level the caller names, and the meta row that seven
+     * hand-rolled section shells wrote out for themselves. `title` predates it
+     * and still renders exactly what it always did, so the cards already
+     * shipping do not move. Set one of the three.
+     */
+    heading?: string;
+    /** 2 under a page title, 3 inside another card. */
+    headingLevel?: 2 | 3;
+    /** Drawn before the heading. Decorative, so it carries no name of its own. */
+    icon?: Component<{ size?: number; class?: string }>;
+    /** A count, a status or a timestamp, at the end of the heading row. */
+    meta?: string;
     pad?: Pad;
     hover?: boolean;
     class?: string;
@@ -19,6 +39,10 @@
   let {
     title = undefined,
     description = undefined,
+    heading = undefined,
+    headingLevel = 3,
+    icon = undefined,
+    meta = undefined,
     pad = 'md',
     hover = false,
     class: klass = '',
@@ -66,10 +90,27 @@
   {onclick}
   onkeydown={onclick ? activate : onkeydown}
 >
-  {#if header || title}
+  {#if header || heading || title}
     <div class="px-5 py-4 border-b border-line">
       {#if header}
         {@render header()}
+      {:else if heading}
+        <div class="flex items-center gap-2">
+          {#if icon}
+            {@const Icon = icon}
+            <Icon size={16} class="shrink-0 text-faint" />
+          {/if}
+          <!-- Two branches rather than one dynamic element: the level is a
+               document structure decision, and a reader of this file should be
+               able to see both headings the card can produce. -->
+          {#if headingLevel === 2}
+            <h2 class={sectionHeading(2)}>{heading}</h2>
+          {:else}
+            <h3 class={sectionHeading(3)}>{heading}</h3>
+          {/if}
+          {#if meta}<span class="ml-auto shrink-0 text-xs text-faint">{meta}</span>{/if}
+        </div>
+        {#if description}<p class="text-sm text-muted mt-0.5">{description}</p>{/if}
       {:else}
         <h3 class="font-semibold text-fg">{title}</h3>
         {#if description}<p class="text-sm text-muted mt-0.5">{description}</p>{/if}

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

@@ -1,8 +1,30 @@
-import type { Snippet } from 'svelte';
+import type { Component, Snippet } from 'svelte';
 type Pad = 'none' | 'sm' | 'md' | 'lg';
 interface Props {
     title?: string;
     description?: string;
+    /**
+     * The card's own section heading.
+     *
+     * The header band has three ways in, and they resolve in this order:
+     * `header` wins over everything, then `heading`, then `title`. A caller who
+     * hands a snippet has already decided what the band contains, so the
+     * component adds nothing to it. `heading` renders the icon, a real heading
+     * element at the level the caller names, and the meta row that seven
+     * hand-rolled section shells wrote out for themselves. `title` predates it
+     * and still renders exactly what it always did, so the cards already
+     * shipping do not move. Set one of the three.
+     */
+    heading?: string;
+    /** 2 under a page title, 3 inside another card. */
+    headingLevel?: 2 | 3;
+    /** Drawn before the heading. Decorative, so it carries no name of its own. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    /** A count, a status or a timestamp, at the end of the heading row. */
+    meta?: string;
     pad?: Pad;
     hover?: boolean;
     class?: string;
@@ -12,6 +34,6 @@ interface Props {
     onkeydown?: (e: KeyboardEvent) => void;
     children: Snippet;
 }
-declare const Card: import("svelte").Component<Props, {}, "">;
+declare const Card: Component<Props, {}, "">;
 type Card = ReturnType<typeof Card>;
 export default Card;