@kitn.ai/ui 0.28.0 → 0.29.0

package/src/elements/select.tsx

@@ -1,165 +0,0 @@
-import { createEffect, createSignal, untrack } from 'solid-js';
-import { defineWebComponent } from './define';
-import { Select } from '../ui/select';
-// Public shape of the `options` prop; lives in ./element-data-types so the ROOT
-// entry can re-export it (see that file's header).
-import type { KaiSelectOption } from './element-data-types';
-
-interface Props extends Record<string, unknown> {
-  /** The choices, in display order. Set as a JS PROPERTY (array), never an attribute.
-   *  Rendered in full: the kit never truncates, re-orders or de-duplicates them. */
-  options: KaiSelectOption[];
-  /** Controlled selected value. Settable and reflected to the `value` attribute.
-   *  `el.value = 'high'` drives it; choosing an option updates it and fires
-   *  `kai-change`. Read `el.value` for live state; for a `multiple` select read
-   *  `el.values` instead. */
-  value?: string;
-  /** Text for a leading, disabled, empty option: the "nothing chosen yet" row.
-   *  Omitted means no such row at all; there is no default wording, because inventing
-   *  one would put words in your UI. */
-  placeholder?: string;
-  /** Allow more than one selection. Turns the control into the platform's list box, so
-   *  the kit's chevron is not drawn. */
-  multiple?: boolean;
-  /** Force the invalid (destructive-border) state. */
-  invalid?: boolean;
-  /** Disable interaction. */
-  disabled?: boolean;
-  /** Set the native `required` attribute, and nothing more. Whether an empty select is
-   *  an error is the application's rule, not the kit's. */
-  required?: boolean;
-  /** Accessible label for the control. */
-  label?: string;
-  /** Form-control name, for a native form submit. */
-  name?: string;
-}
-
-/** Events fired by `<kai-select>`. */
-interface Events {
-  /** A choice was made. `value` is the first selected option (empty when nothing is
-   *  selected); `values` is every selected option, which is what a `multiple` select
-   *  needs. Both are always present, so neither shape silently loses the other. */
-  'kai-change': { value: string; values: string[] };
-}
-
-/**
- * `<kai-select>` — a select over a REAL native `<select>`, in the kit's field box with
- * the kit's own chevron. Native, not a hand-built listbox: that is what keeps the
- * platform picker on mobile, type-ahead on desktop, form participation and the OS
- * accessibility tree.
- *
- * The dropdown list itself stays OS chrome — it renders outside the page and no
- * stylesheet reaches it. What the element does do is make it follow the kit's
- * light/dark mode rather than the OS's.
- *
- * Feed it `options` (a JS-property array of `{ value, label?, disabled? }`), drive and
- * read the selection with the `value` property (settable + reflected to the `value`
- * attribute, so `:host([value])` and `el.value` see live state), and listen for
- * `kai-change`.
- *
- * Re-rendering follows the kit's reactivity contract: hand it a NEW array reference,
- * and a new object for any option whose content changed — the list is
- * reference-keyed, so mutating an option in place changes nothing on screen.
- *
- * ```html
- * <kai-select value="high" placeholder="Choose a severity…" label="Severity"></kai-select>
- * <script type="module">
- *   import '@kitn.ai/ui/elements';
- *   const select = document.querySelector('kai-select');
- *   // ARRAY prop — a JS property, never an attribute.
- *   select.options = [
- *     { value: 'low', label: 'Low' },
- *     { value: 'high', label: 'High priority' },
- *     { value: 'legacy', label: 'Legacy', disabled: true },
- *   ];
- *   select.addEventListener('kai-change', (e) => console.log(e.detail.value, e.detail.values));
- *   select.value = 'low';   // drive it (no kai-change — the host already knows)
- * </script>
- * ```
- */
-defineWebComponent<Props, Events>('kai-select', {
-  options: [],
-  value: undefined,
-  placeholder: undefined,
-  multiple: undefined,
-  invalid: undefined,
-  disabled: undefined,
-  required: undefined,
-  label: undefined,
-  name: undefined,
-}, (props, ctx) => {
-  const { element, dispatch, flag, expose } = ctx;
-
-  // Lift the selection into the facade and drive Select CONTROLLED so the host can read
-  // it (`el.value` / `:host([value])`) and set it after mount. Seed from the `value`
-  // property/attribute present on mount; nothing is auto-selected, because `options`
-  // normally arrives as a property AFTER upgrade (kai-radio-group's structure).
-  const seed = (props.value as string | undefined) ?? element.getAttribute('value') ?? '';
-  const [values, setValues] = createSignal<string[]>(seed ? [seed] : []);
-  const first = () => values()[0] ?? '';
-
-  // Coerce anything arriving through the `value` setter (a JS assignment, or the
-  // attributeChangedCallback write-back the reflect effect below triggers) to a string,
-  // falling back to the live attribute when nullish so the write-back equals the signal
-  // and the guards absorb it — no attr⇄prop feedback loop.
-  const coerce = (v: unknown): string =>
-    v == null ? (element.getAttribute('value') ?? '') : String(v);
-
-  // Apply a new selection and fire kai-change once (the user-choice path).
-  const apply = (next: string[]) => {
-    const prev = untrack(values);
-    if (prev.length === next.length && prev.every((v, i) => v === next[i])) return;
-    setValues(next);
-    dispatch('kai-change', { value: next[0] ?? '', values: next });
-  };
-
-  Object.defineProperty(element, 'value', {
-    get: () => first(),
-    set: (v: unknown) => {
-      const next = coerce(v);
-      if (untrack(first) !== next) setValues(next ? [next] : []);
-    },
-    configurable: true,
-    enumerable: true,
-  });
-
-  // The multi-selection read/write side. `value` alone cannot represent it, and
-  // returning only the first option from a `multiple` select would be a silent drop.
-  Object.defineProperty(element, 'values', {
-    get: () => values(),
-    set: (v: unknown) => setValues(Array.isArray(v) ? v.map(String) : []),
-    configurable: true,
-    enumerable: true,
-  });
-
-  // Reflect the primary value → the `[value]` host attribute (for `:host([value])`).
-  createEffect(() => {
-    const v = first();
-    if (v) {
-      if (element.getAttribute('value') !== v) element.setAttribute('value', v);
-    } else if (element.hasAttribute('value')) {
-      element.removeAttribute('value');
-    }
-  });
-
-  expose({
-    /** Focus the inner select (the host element can't reach it). */
-    focus: (options?: FocusOptions) =>
-      element.shadowRoot?.querySelector<HTMLSelectElement>('select')?.focus(options),
-  });
-
-  return (
-    <Select
-      options={(props.options ?? []) as KaiSelectOption[]}
-      value={values()}
-      placeholder={props.placeholder as string | undefined}
-      multiple={flag('multiple')}
-      invalid={flag('invalid')}
-      disabled={flag('disabled')}
-      required={flag('required')}
-      aria-label={props.label as string | undefined}
-      name={props.name as string | undefined}
-      onChange={(e) => apply([...e.currentTarget.selectedOptions].map((o) => o.value))}
-    />
-  );
-});

package/src/elements/separator.tsx

@@ -1,36 +0,0 @@
-import { Separator } from '../ui/separator';
-import { defineWebComponent } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** `horizontal` (default, block + full-width) or `vertical` (a rule inside a
-   *  flex/grid row, stretching to the row height). */
-  orientation?: 'horizontal' | 'vertical';
-}
-
-/**
- * `<kai-separator>` — a themed divider between groups of content (toolbar
- * sections, menu groups, header/sidebar splits). Carries `role="separator"`.
- * Restyle via `::part(separator)`.
- *
- * ```html
- * <kai-separator></kai-separator>
- * <div style="display:flex; gap:.5rem">
- *   <span>A</span><kai-separator orientation="vertical"></kai-separator><span>B</span>
- * </div>
- * ```
- */
-defineWebComponent<Props>('kai-separator', {
-  orientation: 'horizontal',
-}, (props) => {
-  const vertical = () => props.orientation === 'vertical';
-  return (
-    <>
-      {/* The host owns its layout box: a horizontal rule is block + full-width;
-          a vertical rule is an inline-block flex item that stretches to the row. */}
-      <style>{vertical()
-        ? ':host{display:inline-block;align-self:stretch}'
-        : ':host{display:block}'}</style>
-      <Separator orientation={vertical() ? 'vertical' : 'horizontal'} part="separator" />
-    </>
-  );
-});

package/src/elements/setting-item.tsx

@@ -1,50 +0,0 @@
-import { createSignal, onCleanup, onMount } from 'solid-js';
-import { SettingItem } from '../ui/settings-group';
-import { defineWebComponent } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** Row label (primary text). Attribute: `label`. */
-  label?: string;
-  /** Optional secondary description under the label. Attribute: `description`. */
-  description?: string;
-}
-
-/**
- * `<kai-setting-item>` — one row inside a `<kai-settings-group>`: a left
- * label/description block and an optional right-aligned control. Slot the control
- * (a `<kai-switch>`, segmented control, select, …) into `slot="control"`; omit it
- * for a plain label row.
- *
- * Themeable `::part`s: `label` (the label/description block) and `control`.
- *
- * ```html
- * <kai-setting-item label="Reduce motion" description="Minimize animations.">
- *   <kai-switch slot="control"></kai-switch>
- * </kai-setting-item>
- * ```
- */
-defineWebComponent<Props>('kai-setting-item', {
-  label: '',
-  description: undefined,
-}, (props, { element }) => {
-  // The control region only renders when `slot="control"` is actually filled, so
-  // a plain label row has no stray right-side wrapper. An empty `<slot>` is always
-  // a truthy node, so we track occupancy and gate on it (the kai-card approach).
-  // Re-read on child/attribute mutations so a late-slotted control lights up.
-  const [hasControl, setHasControl] = createSignal(false);
-  onMount(() => {
-    const read = () => setHasControl(!!element.querySelector(':scope > [slot="control"]'));
-    read();
-    const observer = new MutationObserver(read);
-    observer.observe(element, { childList: true, attributes: true, subtree: true });
-    onCleanup(() => observer.disconnect());
-  });
-
-  return (
-    <SettingItem
-      label={props.label ?? ''}
-      description={props.description}
-      control={hasControl() ? <slot name="control" /> : undefined}
-    />
-  );
-});

package/src/elements/settings-group.tsx

@@ -1,37 +0,0 @@
-import { SettingsGroup } from '../ui/settings-group';
-import { defineWebComponent } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** Small section heading shown above the card. Attribute: `heading`. */
-  heading?: string;
-  /** Optional muted description under the heading. Attribute: `description`. */
-  description?: string;
-}
-
-/**
- * `<kai-settings-group>` — a settings section: a small heading + optional muted
- * description over a bordered, rounded card that stacks `<kai-setting-item>` rows
- * with hairline dividers. Put the rows as light-DOM children (the default slot).
- *
- * Host-agnostic chrome: the SAME group drops into a modal or a full settings
- * page; only the rows change per app.
- *
- * Themeable `::part`s: `header` (the heading/description block) and `body` (the
- * rows card).
- *
- * ```html
- * <kai-settings-group heading="Appearance" description="How the app looks.">
- *   <kai-setting-item label="Theme">
- *     <kai-switch slot="control"></kai-switch>
- *   </kai-setting-item>
- * </kai-settings-group>
- * ```
- */
-defineWebComponent<Props>('kai-settings-group', {
-  heading: '',
-  description: undefined,
-}, (props) => (
-  <SettingsGroup heading={props.heading ?? ''} description={props.description}>
-    <slot />
-  </SettingsGroup>
-));

package/src/elements/skeleton.tsx

@@ -1,45 +0,0 @@
-import { Skeleton, type SkeletonVariant } from '../ui/skeleton';
-import { defineWebComponent } from './define';
-
-interface Props extends Record<string, unknown> {
-  /** `text` (one or more lines), `rect` (a block), or `circle` (round).
-   *  Defaults to `text`. */
-  variant?: SkeletonVariant;
-  /** CSS width (e.g. `'12rem'`, `'60%'`). Defaults to full width (responsive);
-   *  for `circle` it is the diameter. */
-  width?: string;
-  /** CSS height. Defaults per variant (a text line height; circle = width). */
-  height?: string;
-  /** `text` only: number of lines; the last is shorter. Defaults to 1. */
-  lines?: number;
-}
-
-/**
- * `<kai-skeleton>` — a pulsing loading placeholder that preserves layout while
- * content arrives. Responsive by default (fills its container's width). It is
- * prop-driven because utility classes can't cross the shadow boundary: pick a
- * `variant` and optionally set `width` / `height` / `lines`.
- *
- * ```html
- * <kai-skeleton variant="text" lines="3"></kai-skeleton>
- * <kai-skeleton variant="circle" width="2.5rem"></kai-skeleton>
- * <kai-skeleton variant="rect" height="10rem"></kai-skeleton>
- * ```
- * Recolor by overriding the `--color-muted` token.
- */
-defineWebComponent<Props>('kai-skeleton', {
-  variant: 'text',
-  width: undefined,
-  height: undefined,
-  lines: undefined,
-}, (props) => (
-  <>
-    <style>{':host{display:block}'}</style>
-    <Skeleton
-      variant={props.variant ?? 'text'}
-      width={props.width}
-      height={props.height}
-      lines={props.lines != null ? Number(props.lines) : undefined}
-    />
-  </>
-));

package/src/elements/slider.tsx

@@ -1,171 +0,0 @@
-import { createEffect, createSignal, untrack } from 'solid-js';
-import { defineWebComponent } from './define';
-import { Slider } from '../ui/slider';
-
-interface Props extends Record<string, unknown> {
-  /** Lowest selectable value. Required: a range with no bounds is a guess, and the
-   *  guess belongs to whoever knows what the number means. */
-  min?: number;
-  /** Highest selectable value. Required, for the same reason as `min`. */
-  max?: number;
-  /** Granularity. Omitted means the native default of 1; `any` means continuous. */
-  step?: number | 'any';
-  /** Controlled value. Settable and reflected to the `value` attribute. `el.value = 40`
-   *  drives it; dragging updates it and fires `kai-input` per step, `kai-change` on
-   *  release. Read `el.value` for live state. */
-  value?: number;
-  /** Disable interaction. */
-  disabled?: boolean;
-  /** Accessible label for the slider. */
-  label?: string;
-  /** Form-control name, for a native form submit. */
-  name?: string;
-  /** Show the current value beside the track. Off by default.
-   *
-   *  Two ways in, because one of them is not a scalar. As a bare ATTRIBUTE
-   *  (`<kai-slider value-label>`) it renders the raw number. As a JS PROPERTY it also
-   *  accepts a formatter function (`el.valueLabel = (v) => v + '%'`), for a slider that
-   *  is not counting bare numbers. A function cannot survive an attribute, so that half
-   *  is property-only.
-   *
-   *  The readout is hidden from assistive tech: the slider already reports the same
-   *  number, and an exposed copy would be announced twice. */
-  valueLabel?: boolean | ((value: number) => string);
-}
-
-/** Events fired by `<kai-slider>`. */
-interface Events {
-  /** The thumb moved. Fires per step during a drag or a key press. */
-  'kai-input': { value: number };
-  /** The value was committed: pointer released, or a key press finished. */
-  'kai-change': { value: number };
-}
-
-/**
- * `<kai-slider>` — a slider over a real `<input type="range">`, with the kit's filled
- * track and thumb. Arrows, Home, End and PageUp/PageDown all work because the control
- * underneath is the browser's, not a reimplementation.
- *
- * Give it `min` and `max` (there are no defaults on purpose), drive and read the
- * position with the `value` property, and listen for `kai-input` while dragging or
- * `kai-change` on release.
- *
- * ```html
- * <kai-slider min="0" max="100" step="5" value="40" label="Temperature"></kai-slider>
- * <script type="module">
- *   import '@kitn.ai/ui/elements';
- *   const slider = document.querySelector('kai-slider');
- *   slider.addEventListener('kai-input', (e) => console.log(e.detail.value));
- *   slider.value = 70;   // drive it (no event — the host already knows)
- * </script>
- * ```
- */
-defineWebComponent<Props, Events>('kai-slider', {
-  min: undefined,
-  max: undefined,
-  step: undefined,
-  value: undefined,
-  disabled: undefined,
-  label: undefined,
-  name: undefined,
-  valueLabel: undefined,
-}, (props, ctx) => {
-  const { element, dispatch, flag, expose } = ctx;
-
-  // `Number(null)` is 0 and `Number('')` is 0, both FINITE, so a naive
-  // `Number.isFinite(Number(v))` treats a missing attribute as a real zero and the
-  // fallbacks below never fire. Reject the empty cases before coercing.
-  const num = (v: unknown, fallback: number): number => {
-    if (v == null || (typeof v === 'string' && v.trim() === '')) return fallback;
-    const n = Number(v);
-    return Number.isFinite(n) ? n : fallback;
-  };
-  // No invented bounds: these mirror the native `<input type="range">` defaults, which
-  // is what an author who wrote neither attribute is already going to get.
-  const min = () => num(props.min, 0);
-  const max = () => num(props.max, 100);
-
-  // Lift the position into the facade and drive Slider CONTROLLED so the host can read
-  // it (`el.value` / `:host([value])`) and set it after mount. Seed from the `value`
-  // property/attribute present on mount, falling back to the midpoint — HTML's own rule
-  // for a range with no value. kai-checkbox / kai-radio-group's structure, deliberately.
-  const [value, setValue] = createSignal(
-    props.value != null
-      ? num(props.value, (min() + max()) / 2)
-      : num(element.getAttribute('value'), (min() + max()) / 2),
-  );
-
-  // Coerce anything arriving through the `value` setter (a JS assignment, or the
-  // write-back `attributeChangedCallback` fires when the reflect effect below writes the
-  // attribute) to a number, falling back to the live attribute when nullish so the
-  // write-back equals the signal and the guard absorbs it — no attr⇄prop feedback loop.
-  const coerce = (v: unknown): number =>
-    v == null ? num(element.getAttribute('value'), untrack(value)) : num(v, untrack(value));
-
-  // Apply a new value and fire once (the user path). No-op while disabled.
-  const apply = (next: number, type: 'kai-input' | 'kai-change') => {
-    if (flag('disabled')) return;
-    // kai-change fires on commit EVEN IF the value equals the last one this element
-    // reported, because "you let go here" is information the host cannot derive; the
-    // equality guard applies to the per-step stream only.
-    if (type === 'kai-input' && untrack(value) === next) return;
-    setValue(next);
-    dispatch(type, { value: next });
-  };
-
-  // Reads return LIVE state; host writes drive it WITHOUT firing an event — the host
-  // already knows what it set. The equality guard kills the reflect write-back.
-  Object.defineProperty(element, 'value', {
-    get: () => value(),
-    set: (v: unknown) => { const next = coerce(v); if (untrack(value) !== next) setValue(next); },
-    configurable: true,
-    enumerable: true,
-  });
-
-  // Reflect internal value → the `[value]` host attribute (for `:host([value])`).
-  createEffect(() => {
-    const v = String(value());
-    if (element.getAttribute('value') !== v) element.setAttribute('value', v);
-  });
-
-  expose({
-    /** Focus the inner range input (the host element can't reach it). */
-    focus: (options?: FocusOptions) =>
-      element.shadowRoot?.querySelector<HTMLInputElement>('input[type="range"]')?.focus(options),
-  });
-
-  // `step` arrives as a string when it came from an attribute. Resolve the one literal
-  // the spec allows (`any`, continuous) and treat everything else as a number.
-  const step = (): number | 'any' | undefined => {
-    const raw = props.step;
-    if (raw == null) return undefined;
-    if (String(raw) === 'any') return 'any';
-    const n = Number(raw);
-    return Number.isFinite(n) ? n : undefined;
-  };
-
-  // `valueLabel` arrives either as a bare attribute (the boolean half) or as a property
-  // holding a formatter (the half an attribute cannot carry). `flag` handles the first,
-  // a typeof check the second.
-  const valueLabel = (): boolean | ((v: number) => string) => {
-    const raw = props.valueLabel;
-    if (typeof raw === 'function') return raw as (v: number) => string;
-    return flag('valueLabel');
-  };
-
-  // Base sets `:host{display:block}`, which is right for a full-width track.
-  return (
-    <Slider
-      min={min()}
-      max={max()}
-      step={step()}
-      value={value()}
-      disabled={flag('disabled')}
-      aria-label={props.label as string | undefined}
-      name={props.name as string | undefined}
-      valueLabel={valueLabel()}
-      onInput={(e) => apply(e.currentTarget.valueAsNumber, 'kai-input')}
-      onChange={(e) => apply(e.currentTarget.valueAsNumber, 'kai-change')}
-    />
-  );
-});

package/src/elements/slot-text.ts

@@ -1,73 +0,0 @@
-import { createSignal, type Accessor } from 'solid-js';
-
-/**
- * Track whether a `<slot>` is projecting VISIBLE TEXT, so a facade can tell
- * "this control shows its own name" from "this control is icon-only and needs
- * one".
- *
- * WHY IT EXISTS. Slotted light-DOM text is part of the flattened tree, so it
- * names the shadow `<button>` all by itself — measured, not assumed:
- * `scripts/probe-button-accessible-name.mjs` reads chromium's AX tree and
- * `<kai-button>Save</kai-button>` computes the name "Save" from `contents`,
- * with no `aria-label` anywhere. An `aria-label` on top of that does not add a
- * name, it REPLACES one, and a replacement that disagrees with the visible text
- * is a WCAG 2.5.3 (Label in Name) failure: speech-input users say what they
- * see, so a button reading "Save" whose accessible name is "Submit" cannot be
- * activated by voice at all. `kai-checkpoint` already resolved this the same
- * way; this is the reusable form of that decision.
- *
- * WHY A SIGNAL AND NOT A ONE-OFF READ. The facade renders while the HTML parser
- * is still inside the element's own tag, so the light DOM is usually EMPTY at
- * that moment and any synchronous read of `element.childNodes` reports "no text"
- * for the most common case there is. `slotchange` is the event that tells the
- * truth, and it fires on the initial assignment too.
- *
- * The initial value is therefore `false`, meaning "assume icon-only", which
- * makes the pre-`slotchange` frame emit the `aria-label`. That direction is
- * deliberate: an overridden name is a defect, an ABSENT name is a worse one, so
- * the transient state is the named one. `slotchange` is queued as a mutation
- * observer microtask, so it lands before paint and no assistive technology
- * observes the transient.
- */
-export function createSlotText(options: {
-  /**
-   * Follow `assignedNodes({ flatten: true })`, which descends into nested
-   * light-DOM `<slot>` elements (a consumer wrapping the element in their OWN
-   * component and forwarding a slot) — and, when nothing is assigned, returns
-   * the slot's FALLBACK content.
-   *
-   * Only safe on a slot whose fallback is exactly the visible label. Do NOT set
-   * it on a slot whose fallback can render a non-name (an icon that happens to
-   * be plain text, say): the fallback would count as visible text and suppress
-   * the very `aria-label` that names the control. `kai-button`'s default slot
-   * has no fallback at all, so flatten there only buys the nested case;
-   * `kai-menu`'s trigger slot falls back to an icon, so it must not use it.
-   */
-  flatten?: boolean;
-} = {}): {
-  /** Whether the slot is currently showing text. */
-  hasText: Accessor<boolean>;
-  /** `ref` for the `<slot>`. Re-reads on every `slotchange`. */
-  ref: (slot: HTMLSlotElement) => void;
-} {
-  const [hasText, setHasText] = createSignal(false);
-
-  const read = (slot: HTMLSlotElement) => {
-    const nodes = slot.assignedNodes({ flatten: options.flatten ?? false });
-    setHasText(nodes.some((node) => (node.textContent ?? '').trim() !== ''));
-  };
-
-  return {
-    hasText,
-    ref: (slot: HTMLSlotElement) => {
-      // A slot outside a shadow root assigns nothing, and this ref runs before
-      // solid inserts it — so this first read is normally `false` and the
-      // slotchange below is what carries the answer. It is here for the case
-      // where the element is created with its children already in place
-      // (`el.textContent = 'Save'` then appended), where no assignment CHANGE
-      // happens after insertion and slotchange may never fire.
-      read(slot);
-      slot.addEventListener('slotchange', () => read(slot));
-    },
-  };
-}