@lyeve-labs/ui-kit 0.11.2 → 0.13.0

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

@@ -1,8 +1,23 @@
+import type { Component } from 'svelte';
+import { type ChoiceSize, type ChoiceVariant } from '../internal/choice.js';
 interface Props {
     value: string;
     group?: string;
     label?: string;
+    /** Screen-reader-only label, for a radio in a table cell whose column header is the visible name. */
+    labelHidden?: boolean;
+    /** Secondary line under the label. */
+    description?: string;
     hint?: string;
+    error?: string;
+    /** Drawn before the label. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    size?: ChoiceSize;
+    /** 'card' draws a bordered option whose whole surface is the target. */
+    variant?: ChoiceVariant;
     required?: boolean;
     disabled?: boolean;
     id?: string;
@@ -10,6 +25,6 @@ interface Props {
     class?: string;
     onchange?: (value: string) => void;
 }
-declare const Radio: import("svelte").Component<Props, {}, "group">;
+declare const Radio: Component<Props, {}, "group">;
 type Radio = ReturnType<typeof Radio>;
 export default Radio;

package/dist/components/RadioGroup.svelte

@@ -1,97 +1,144 @@
-<script lang="ts">
-  import { FIELD_ERROR, FIELD_HINT, FIELD_LABEL } from '../internal/field.js';
-  // RadioGroup renders a managed set of radio options bound to a single value.
-  // Matches the visual of Radio.svelte; use this when you have a fixed option list.
-  interface Option {
+<script lang="ts" module>
+  import type { Component } from 'svelte';
+
+  /**
+   * One option in a choice group.
+   *
+   * CheckboxGroup declares this interface in the same words, so a consumer who
+   * has written one option list can write the other without rereading the
+   * types. A colocated test compares the two declarations character for
+   * character, because the group and the single control had already drifted
+   * apart once.
+   */
+  export interface ChoiceOption {
+    /** The submitted value, and the key the option is rendered under. */
     value: string;
+    /** Names this one choice. The group is named by the legend instead. */
     label: string;
+    /** A second line under the label, carrying what the label leaves out. */
+    description?: string;
+    /** A lucide component. The group sizes it, so the caller does not guess. */
+    icon?: Component<{ size?: number; class?: string }>;
+    /** Blocks this option alone. A disabled group blocks every option. */
+    disabled?: boolean;
+  }
+</script>
+
+<script lang="ts">
+  import {
+    CHOICE_GROUP,
+    choiceGroupList,
+    type ChoiceOrientation,
+    type ChoiceSize,
+    type ChoiceVariant,
+  } from '../internal/choice.js';
+  import { FIELD_ERROR, FIELD_HINT, FIELD_LABEL, describedBy } from '../internal/field.js';
+  import Radio from './Radio.svelte';
+
+  interface Props {
+    /** The selected value. One of the option values, or empty for none. */
+    value?: string;
+    options: ChoiceOption[];
+    /**
+     * The group's accessible name, rendered as a legend. Required because an
+     * unnamed group announces as a bare set of controls, which leaves a reader
+     * to infer what the set is for from the options alone.
+     */
+    label: string;
+    /** Keeps the legend for a screen reader and takes it off the screen. */
+    labelHidden?: boolean;
     hint?: string;
+    error?: string;
+    name?: string;
+    orientation?: ChoiceOrientation;
+    size?: ChoiceSize;
+    variant?: ChoiceVariant;
+    required?: boolean;
     disabled?: boolean;
+    class?: string;
+    onchange?: (value: string) => void;
   }
 
   let {
     value = $bindable(''),
     options,
-    name = undefined,
-    label = undefined,
+    label,
+    labelHidden = false,
     hint = undefined,
     error = undefined,
+    name = undefined,
+    orientation = 'vertical',
+    size = 'md',
+    variant = 'inline',
     required = false,
     disabled = false,
-    orientation = 'vertical',
     class: cls = '',
     onchange = undefined,
-  }: {
-    value?: string;
-    options: Option[];
-    name?: string;
-    label?: string;
-    hint?: string;
-    error?: string;
-    required?: boolean;
-    disabled?: boolean;
-    orientation?: 'vertical' | 'horizontal';
-    class?: string;
-    onchange?: (value: string) => void;
-  } = $props();
+  }: Props = $props();
 
-  const fallbackName = `rg-${Math.random().toString(36).slice(2, 9)}`;
-  const groupName = $derived(name ?? fallbackName);
-
-  function select(opt: Option) {
-    if (disabled || opt.disabled) return;
-    value = opt.value;
-    onchange?.(opt.value);
-  }
+  /*
+   * The instance id, and through it the shared name, comes from $props.id().
+   * This group built its name from `rg-${Math.random()}`, which produces one
+   * value on the server and a different one on hydration, so every id and every
+   * name derived from it changed under the client on first paint. Two radios
+   * that disagree about their name are two groups, and selecting one no longer
+   * clears the other.
+   */
+  const uid = $props.id();
+  const groupName = $derived(name ?? uid);
 </script>
 
-<fieldset class="flex flex-col gap-2 {cls}" {disabled}>
-  {#if label}
-    <legend class="{FIELD_LABEL} mb-0.5">
-      {label}{#if required}<span class="text-danger ml-0.5">*</span>{/if}
-    </legend>
-  {/if}
+<!--
+  role="radiogroup" over the fieldset's implicit "group". A set of radios is a
+  radiogroup, and that is the role ARIA lets carry aria-invalid and
+  aria-required, so the group can report its own validity rather than leaving a
+  reader to find the message paragraph on their own.
+-->
+<fieldset
+  class="{CHOICE_GROUP} {cls}"
+  role="radiogroup"
+  {disabled}
+  aria-invalid={error ? 'true' : undefined}
+  aria-required={required ? 'true' : undefined}
+  aria-describedby={describedBy(uid, error, hint)}
+>
+  <!--
+    The legend stays a legend when it is hidden. Swapping it for an aria-label
+    on the fieldset would name the group and drop it out of the reading order,
+    so a reader moving through the page would meet the options with nothing
+    ahead of them saying what the set is for.
+  -->
+  <legend class="{FIELD_LABEL} {labelHidden ? 'sr-only' : ''}">
+    {label}{#if required}<span class="text-danger ml-0.5" aria-hidden="true">*</span>{/if}
+  </legend>
 
-  <div
-    class="flex gap-x-5 gap-y-2 {orientation === 'horizontal' ? 'flex-row flex-wrap' : 'flex-col'}"
-  >
-    {#each options as opt (opt.value)}
-      <label
-        class="inline-flex cursor-pointer select-none items-start gap-2.5
-          {disabled || opt.disabled ? 'cursor-not-allowed opacity-50' : ''}"
-      >
-        <span class="relative mt-0.5 flex shrink-0 items-center justify-center">
-          <input
-            type="radio"
-            name={groupName}
-            value={opt.value}
-            disabled={disabled || opt.disabled}
-            checked={value === opt.value}
-            onchange={() => select(opt)}
-            class="peer absolute inset-0 m-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-not-allowed"
-          />
-          <span
-            class="pointer-events-none flex h-4 w-4 items-center justify-center rounded-full border-2 transition-colors duration-150
-              {value === opt.value
-              ? 'border-brand bg-surface-2'
-              : 'border-line bg-surface-2 peer-focus-visible:border-brand'}"
-          >
-            {#if value === opt.value}
-              <span class="h-2 w-2 rounded-full bg-brand"></span>
-            {/if}
-          </span>
-        </span>
-        <span class="flex flex-col gap-0.5">
-          <span class="text-sm text-fg">{opt.label}</span>
-          {#if opt.hint}<span class={FIELD_HINT}>{opt.hint}</span>{/if}
-        </span>
-      </label>
+  <div class={choiceGroupList(orientation)}>
+    {#each options as option (option.value)}
+      <!--
+        The option renders through Radio rather than through a copy of it. The
+        copy is what let this group rest its circle on border-line, at 1.25:1,
+        and keep its focus ring inside the selected branch, so choosing an
+        option deleted the only indicator a keyboard user had. Radio had been
+        fixed for both defects while the group still carried them.
+      -->
+      <Radio
+        bind:group={value}
+        value={option.value}
+        label={option.label}
+        description={option.description}
+        icon={option.icon}
+        name={groupName}
+        {size}
+        {variant}
+        disabled={disabled || option.disabled === true}
+        {onchange}
+      />
     {/each}
   </div>
 
   {#if error}
-    <p class={FIELD_ERROR}>{error}</p>
+    <p id="{uid}-error" class={FIELD_ERROR}>{error}</p>
   {:else if hint}
-    <p class={FIELD_HINT}>{hint}</p>
+    <p id="{uid}-hint" class={FIELD_HINT}>{hint}</p>
   {/if}
 </fieldset>

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

@@ -1,22 +1,52 @@
-interface Option {
+import type { Component } from 'svelte';
+/**
+ * One option in a choice group.
+ *
+ * CheckboxGroup declares this interface in the same words, so a consumer who
+ * has written one option list can write the other without rereading the
+ * types. A colocated test compares the two declarations character for
+ * character, because the group and the single control had already drifted
+ * apart once.
+ */
+export interface ChoiceOption {
+    /** The submitted value, and the key the option is rendered under. */
     value: string;
+    /** Names this one choice. The group is named by the legend instead. */
     label: string;
-    hint?: string;
+    /** A second line under the label, carrying what the label leaves out. */
+    description?: string;
+    /** A lucide component. The group sizes it, so the caller does not guess. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    /** Blocks this option alone. A disabled group blocks every option. */
     disabled?: boolean;
 }
-type $$ComponentProps = {
+import { type ChoiceOrientation, type ChoiceSize, type ChoiceVariant } from '../internal/choice.js';
+interface Props {
+    /** The selected value. One of the option values, or empty for none. */
     value?: string;
-    options: Option[];
-    name?: string;
-    label?: string;
+    options: ChoiceOption[];
+    /**
+     * The group's accessible name, rendered as a legend. Required because an
+     * unnamed group announces as a bare set of controls, which leaves a reader
+     * to infer what the set is for from the options alone.
+     */
+    label: string;
+    /** Keeps the legend for a screen reader and takes it off the screen. */
+    labelHidden?: boolean;
     hint?: string;
     error?: string;
+    name?: string;
+    orientation?: ChoiceOrientation;
+    size?: ChoiceSize;
+    variant?: ChoiceVariant;
     required?: boolean;
     disabled?: boolean;
-    orientation?: 'vertical' | 'horizontal';
     class?: string;
     onchange?: (value: string) => void;
-};
-declare const RadioGroup: import("svelte").Component<$$ComponentProps, {}, "value">;
+}
+declare const RadioGroup: Component<Props, {}, "value">;
 type RadioGroup = ReturnType<typeof RadioGroup>;
 export default RadioGroup;

package/dist/components/SectionHeading.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+  /**
+   * A heading for a section of a page, with an optional row of controls beside
+   * it.
+   *
+   * Fourteen distinct class strings serve this role across one app, so two
+   * sections on the same page render at different sizes and weights, and some
+   * of them are a styled `div` that no heading query can find. Taking the level
+   * rather than a free-form class means the type treatment cannot disagree with
+   * the element, and the element is always a real heading.
+   */
+  import type { Snippet } from 'svelte';
+  import { sectionHeading } from '../internal/layout.js';
+
+  interface Props {
+    /** 2 under a page title, 3 inside a card. */
+    level?: 2 | 3;
+    actions?: Snippet;
+    class?: string;
+    children: Snippet;
+  }
+
+  let { level = 2, actions, class: klass = '', children }: Props = $props();
+</script>
+
+<div class="flex flex-wrap items-center justify-between gap-4 {klass}">
+  <!-- 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 it can produce. -->
+  {#if level === 2}
+    <h2 class={sectionHeading(2)}>{@render children()}</h2>
+  {:else}
+    <h3 class={sectionHeading(3)}>{@render children()}</h3>
+  {/if}
+
+  {#if actions}
+    <div class="flex shrink-0 items-center gap-2">{@render actions()}</div>
+  {/if}
+</div>

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

@@ -0,0 +1,21 @@
+/**
+   * A heading for a section of a page, with an optional row of controls beside
+   * it.
+   *
+   * Fourteen distinct class strings serve this role across one app, so two
+   * sections on the same page render at different sizes and weights, and some
+   * of them are a styled `div` that no heading query can find. Taking the level
+   * rather than a free-form class means the type treatment cannot disagree with
+   * the element, and the element is always a real heading.
+   */
+import type { Snippet } from 'svelte';
+interface Props {
+    /** 2 under a page title, 3 inside a card. */
+    level?: 2 | 3;
+    actions?: Snippet;
+    class?: string;
+    children: Snippet;
+}
+declare const SectionHeading: import("svelte").Component<Props, {}, "">;
+type SectionHeading = ReturnType<typeof SectionHeading>;
+export default SectionHeading;

package/dist/components/SegmentedControl.svelte

@@ -0,0 +1,194 @@
+<script lang="ts" module>
+  import type { Component } from 'svelte';
+
+  /** One segment of the row. */
+  export interface SegmentOption<T extends string = string> {
+    /** The chosen value, and the key the segment is rendered under. */
+    value: T;
+    /** Names this one segment. The group is named by `label`. */
+    label: string;
+    /** A lucide component. The control sizes it, so the caller does not guess. */
+    icon?: Component<{ size?: number; class?: string }>;
+  }
+</script>
+
+<script lang="ts" generics="T extends string">
+  import { FIELD_LABEL, FIELD_WRAP } from '../internal/field.js';
+
+  type Size = 'sm' | 'md';
+
+  interface Props {
+    /** The chosen value. One of the option values. */
+    value: T;
+    options: SegmentOption<T>[];
+    /**
+     * The group's accessible name. Required because an unnamed group announces
+     * as a bare set of controls, which leaves a reader to work out what the set
+     * is for from the segments alone.
+     */
+    label: string;
+    /** Drops the caption above the row. The group keeps its accessible name. */
+    labelHidden?: boolean;
+    /** Submits the value with the surrounding form, through a hidden input. */
+    name?: string;
+    size?: Size;
+    disabled?: boolean;
+    class?: string;
+    onchange?: (value: T) => void;
+  }
+
+  let {
+    value = $bindable(),
+    options,
+    label,
+    labelHidden = false,
+    name = undefined,
+    size = 'md',
+    disabled = false,
+    class: klass = '',
+    onchange = undefined,
+  }: Props = $props();
+
+  /**
+   * The row height comes from the control token, so a segmented control and an
+   * Input in the same row line up. The segments stretch inside it rather than
+   * setting their own height, which would add the row's padding and border on
+   * top and stand the control two pixels proud of everything beside it.
+   */
+  const SIZES: Record<Size, { row: string; segment: string; icon: number }> = {
+    sm: { row: 'h-8', segment: 'gap-1.5 px-2.5 text-xs', icon: 14 },
+    md: { row: 'h-control', segment: 'gap-2 px-3 text-sm', icon: 16 },
+  };
+
+  let rootEl: HTMLDivElement | undefined = $state();
+
+  const selectedIndex = $derived(options.findIndex((o) => o.value === value));
+
+  /*
+   * The group holds ONE tab stop, which is the whole reason this is not a row
+   * of buttons: a picker of five themes cost five presses of Tab to step over.
+   *
+   * A value matching no option would leave every segment at tabindex -1 and
+   * drop the control out of the tab order entirely, so the first segment holds
+   * the stop until something is chosen.
+   */
+  const tabStop = $derived(selectedIndex === -1 ? 0 : selectedIndex);
+
+  function segmentAt(index: number): HTMLElement | undefined {
+    return rootEl?.querySelectorAll<HTMLElement>('[role="radio"]')[index];
+  }
+
+  function choose(index: number) {
+    // Disabled is enforced here as well as on each button. The native attribute
+    // is what stops a real press, and it is the only thing that does, so a
+    // change arriving any other way would still move the bound value with
+    // nothing on screen to say so.
+    if (disabled) return;
+    const next = options[index];
+    if (!next) return;
+    if (next.value !== value) {
+      value = next.value;
+      onchange?.(next.value);
+    }
+    // The roving stop follows the pointer too. A press does not focus a button
+    // in every browser, so without this a later Tab re-enters the group on
+    // whichever segment the keyboard last left.
+    segmentAt(index)?.focus();
+  }
+
+  /**
+   * The radio keyboard pattern: the arrows move the selection and wrap, Home
+   * and End go to the ends, and focus travels with the choice.
+   */
+  function onSegmentKeydown(e: KeyboardEvent, index: number) {
+    const last = options.length - 1;
+    let next: number;
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+        next = index === last ? 0 : index + 1;
+        break;
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        next = index === 0 ? last : index - 1;
+        break;
+      case 'Home':
+        next = 0;
+        break;
+      case 'End':
+        next = last;
+        break;
+      default:
+        return;
+    }
+    // The arrows scroll the page, and Home and End jump it to the ends.
+    e.preventDefault();
+    choose(next);
+  }
+</script>
+
+<div class="{FIELD_WRAP} items-start {klass}">
+  {#if !labelHidden}
+    <!-- A caption, not a label element. The group is named by aria-label, and a
+         label has nothing to point at here: role="radiogroup" is not a form
+         control that `for` can name. -->
+    <span class={FIELD_LABEL}>{label}</span>
+  {/if}
+
+  <div
+    bind:this={rootEl}
+    role="radiogroup"
+    aria-label={label}
+    class="inline-flex items-stretch rounded-lg border 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}
+      {@const Icon = option.icon}
+      <!--
+        Each segment is a radio, and aria-checked is what a screen reader reads.
+        The theme picker this replaces was a row of plain buttons whose choice
+        was carried by a background colour alone, so a screen reader user was
+        told nothing and a colour-blind user saw nothing. The selected segment
+        also sits at a heavier weight, so the state survives a palette a reader
+        cannot separate.
+      -->
+      <button
+        type="button"
+        role="radio"
+        aria-checked={selected}
+        tabindex={i === tabStop ? 0 : -1}
+        {disabled}
+        onclick={() => choose(i)}
+        onkeydown={(e) => onSegmentKeydown(e, i)}
+        class="inline-flex items-center justify-center rounded-md outline-none transition-colors duration-150 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand disabled:cursor-not-allowed {SIZES[
+          size
+        ].segment} {selected ? 'bg-surface text-fg shadow-sm' : 'text-muted hover:text-fg'}"
+      >
+        {#if Icon}
+          <Icon size={SIZES[size].icon} class="shrink-0" />
+        {/if}
+        <span class="grid text-center">
+          <!-- The bold copy holds the width of the heaviest state in every
+               segment. Weight alone would resize the segment the selection
+               lands on, and the whole row would shuffle under the pointer as
+               the user moved along it. -->
+          <span class="invisible col-start-1 row-start-1 font-semibold" aria-hidden="true"
+            >{option.label}</span
+          >
+          <span class="col-start-1 row-start-1 {selected ? 'font-semibold' : 'font-normal'}"
+            >{option.label}</span
+          >
+        </span>
+      </button>
+    {/each}
+  </div>
+
+  {#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
+         would each post their own. -->
+    <input type="hidden" {name} {value} />
+  {/if}
+</div>

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

@@ -0,0 +1,55 @@
+import type { Component } from 'svelte';
+/** One segment of the row. */
+export interface SegmentOption<T extends string = string> {
+    /** The chosen value, and the key the segment is rendered under. */
+    value: T;
+    /** Names this one segment. The group is named by `label`. */
+    label: string;
+    /** A lucide component. The control sizes it, so the caller does not guess. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+}
+declare function $$render<T extends string>(): {
+    props: {
+        /** The chosen value. One of the option values. */
+        value: T;
+        options: SegmentOption<T>[];
+        /**
+         * The group's accessible name. Required because an unnamed group announces
+         * as a bare set of controls, which leaves a reader to work out what the set
+         * is for from the segments alone.
+         */
+        label: string;
+        /** Drops the caption above the row. The group keeps its accessible name. */
+        labelHidden?: boolean;
+        /** Submits the value with the surrounding form, through a hidden input. */
+        name?: string;
+        size?: "sm" | "md";
+        disabled?: boolean;
+        class?: string;
+        onchange?: (value: T) => void;
+    };
+    exports: {};
+    bindings: "value";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends string> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "value";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends string>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends string>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SegmentedControl: $$IsomorphicComponent;
+type SegmentedControl<T extends string> = InstanceType<typeof SegmentedControl<T>>;
+export default SegmentedControl;