@kitn.ai/ui 0.17.0 → 0.18.0

package/src/elements/search.tsx

@@ -0,0 +1,180 @@
+import { createEffect, createSignal, untrack, Show } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Input } from '../ui/input';
+import { Kbd } from '../ui/kbd';
+import { Loader } from '../components/loader';
+import { renderIcon } from '../ui/icon';
+
+interface Props extends Record<string, unknown> {
+  /** Controlled query — settable and reflected to the `value` attribute. Read
+   *  `el.value` for live state. */
+  value?: string;
+  /** Placeholder. Defaults to `Search…`. */
+  placeholder?: string;
+  /** Leading icon-NAME string (a curated name, URL, or text), resolved to a glyph
+   *  the same way `kai-button`'s `icon` is. Defaults to `search`. */
+  icon?: string;
+  /** Debounce window for `kai-search`, in ms. Defaults to `200`. */
+  debounce?: number;
+  /** Show a spinner in place of the leading icon while results load. */
+  loading?: boolean;
+  /** Optional shortcut hint shown (as a `kai-kbd`) while the field is empty,
+   *  e.g. `Mod+K`. Display only; it does not bind the key. */
+  shortcut?: string;
+}
+
+/** Events fired by `<kai-search>`. */
+interface Events {
+  /** The query changed (debounced live, and on clear). */
+  'kai-search': { value: string };
+  /** Enter was pressed. */
+  'kai-submit': { value: string };
+  /** The field committed (blur). */
+  'kai-change': { value: string };
+}
+
+/**
+ * `<kai-search>` — a debounced filter field built on `kai-input`. Type to fire a
+ * debounced `kai-search`, press Enter for `kai-submit`. A clear (×) button shows
+ * once there's a value; an optional `shortcut` renders a `kai-kbd` hint while the
+ * field is empty.
+ *
+ * ```html
+ * <kai-search placeholder="Search docs" shortcut="Mod+K"></kai-search>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const s = document.querySelector('kai-search');
+ *   s.addEventListener('kai-search', (e) => filter(e.detail.value));
+ *   s.addEventListener('kai-submit', (e) => go(e.detail.value));
+ * </script>
+ * ```
+ *
+ * Drive/read the query with the `value` property (reflected to the attribute).
+ * Restyle via `::part(field)`, `::part(input)`, and `::part(clear)`.
+ */
+defineWebComponent<Props, Events>('kai-search', {
+  value: undefined,
+  placeholder: 'Search…',
+  icon: 'search',
+  debounce: 200,
+  loading: false,
+  shortcut: undefined,
+}, (props, ctx) => {
+  const { element, dispatch, flag, expose } = ctx;
+
+  // Lift the query into the facade and drive Input CONTROLLED so the host can read
+  // it (`el.value` / `:host([value])`) and set it after mount. Mirrors kai-segmented.
+  const [value, setValue] = createSignal(
+    (props.value as string | undefined) ?? element.getAttribute('value') ?? '',
+  );
+
+  const coerce = (v: unknown): string =>
+    v == null ? (element.getAttribute('value') ?? '') : String(v);
+
+  // Reads return LIVE state; host writes (`el.value = …`) drive it WITHOUT firing
+  // events. The equality guard kills the reflect write-back loop.
+  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 → `[value]` host attribute (for `:host([value])`).
+  createEffect(() => {
+    const v = value();
+    if (v) {
+      if (element.getAttribute('value') !== v) element.setAttribute('value', v);
+    } else if (element.hasAttribute('value')) {
+      element.removeAttribute('value');
+    }
+  });
+
+  // Debounced kai-search: each keystroke resets the timer; it fires once after the
+  // window. Clearing fires immediately (timer cancelled).
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const debounceMs = () => {
+    const ms = Number(props.debounce ?? 200);
+    return Number.isFinite(ms) && ms >= 0 ? ms : 200;
+  };
+  const scheduleSearch = (next: string) => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => dispatch('kai-search', { value: next }), debounceMs());
+  };
+
+  const getInput = (): HTMLInputElement | null =>
+    element.shadowRoot?.querySelector<HTMLInputElement>('input') ?? null;
+
+  const onInput = (next: string) => {
+    setValue(next);
+    scheduleSearch(next);
+  };
+
+  // Empty the field, fire kai-search '' immediately (cancelling any pending), refocus.
+  const clear = () => {
+    if (timer) clearTimeout(timer);
+    setValue('');
+    dispatch('kai-search', { value: '' });
+    getInput()?.focus();
+  };
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'Enter') dispatch('kai-submit', { value: untrack(value) });
+  };
+
+  expose({
+    focus: () => getInput()?.focus(),
+    clear,
+  });
+
+  // Leading: a spinner while loading, otherwise the resolved icon glyph.
+  const leading = (
+    <Show
+      when={flag('loading')}
+      fallback={renderIcon((props.icon as string) ?? 'search', {
+        class: 'size-4 shrink-0',
+        imgClass: 'size-4 shrink-0',
+        spanClass: 'inline-flex size-4 shrink-0 items-center justify-center',
+        ariaHidden: true,
+      })}
+    >
+      <Loader variant="circular" size="sm" />
+    </Show>
+  );
+
+  // Trailing: a clear button once there's a value, else a shortcut hint if set.
+  const trailing = (
+    <>
+      <Show when={value()}>
+        <button
+          type="button"
+          part="clear"
+          aria-label="Clear"
+          class="inline-flex size-5 shrink-0 items-center justify-center rounded text-muted-foreground transition-colors hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          onClick={clear}
+        >
+          {renderIcon('x', { class: 'size-4', imgClass: 'size-4' })}
+        </button>
+      </Show>
+      <Show when={!value() && props.shortcut}>
+        <Kbd keys={props.shortcut as string} size="sm" class="opacity-80" />
+      </Show>
+    </>
+  );
+
+  return (
+    <>
+      <style>{':host{display:block}'}</style>
+      <Input
+        type="search"
+        value={value()}
+        placeholder={(props.placeholder as string) ?? 'Search…'}
+        leading={leading}
+        trailing={trailing}
+        onValueInput={onInput}
+        onValueChange={(v) => dispatch('kai-change', { value: v })}
+        onKeyDown={onKeyDown}
+      />
+    </>
+  );
+});

package/src/elements/segmented.tsx

@@ -0,0 +1,135 @@
+import { createEffect, createSignal, untrack } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Segmented, type SegmentedOption } from '../ui/segmented';
+import { renderIcon } from '../ui/icon';
+
+/** A single segment. `icon` is an icon-NAME string (web-component-friendly) —
+ *  a curated name (e.g. `"code"`), a URL/data-URI, or plain text — resolved to a
+ *  glyph via the kit's icon renderer (the same path `kai-button`'s `icon` uses). */
+interface Option {
+  value: string;
+  label: string;
+  icon?: string;
+}
+
+interface Props extends Record<string, unknown> {
+  /** The selectable segments, left to right. Set as a JS property (array). */
+  options: Option[];
+  /** Controlled selected `value` — settable and reflected to the `value`
+   *  attribute. `el.value = 'preview'` drives it; choosing a segment updates it
+   *  and fires `kai-change`. Read `el.value` for live state. */
+  value?: string;
+  /** Control density: `sm` or `md`. Defaults to `md`. */
+  size?: 'sm' | 'md';
+}
+
+/** Events fired by `<kai-segmented>`. */
+interface Events {
+  /** A segment was chosen. */
+  'kai-change': { value: string };
+}
+
+/**
+ * `<kai-segmented>` — a single-select pill track (segmented / toggle group).
+ * Feed it `options` (a JS-property array), drive/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`.
+ *
+ * ```html
+ * <kai-segmented value="preview"></kai-segmented>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const seg = document.querySelector('kai-segmented');
+ *   seg.options = [
+ *     { value: 'code', label: 'Code', icon: 'code' },
+ *     { value: 'preview', label: 'Preview', icon: 'monitor' },
+ *   ];
+ *   seg.addEventListener('kai-change', (e) => console.log(e.detail.value));
+ *   seg.value = 'code'; // drive it (no kai-change — the host already knows)
+ * </script>
+ * ```
+ *
+ * Each option's `icon` is an icon-name string resolved to a glyph (curated name,
+ * URL, or text). Restyle via `::part(track)` and `::part(segment)`.
+ */
+defineWebComponent<Props, Events>('kai-segmented', {
+  options: [],
+  value: undefined,
+  size: 'md',
+}, (props, ctx) => {
+  const { element, dispatch } = ctx;
+
+  // Lift the selected value into the facade and drive Segmented 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 (options usually arrive
+  // as a property after upgrade, so we don't auto-select the first segment here).
+  const [value, setValue] = createSignal(
+    (props.value as string | undefined) ?? element.getAttribute('value') ?? '',
+  );
+
+  // Coerce any value coming through the `value` setter (a JS assignment, or the
+  // write-back from `attributeChangedCallback`) to a string — falling back to the
+  // live attribute when it's nullish, so the reflect write-back equals the signal
+  // and the equality guards below absorb it (no attr⇄prop feedback loop; mirrors
+  // kai-switch's `checked`).
+  const coerce = (v: unknown): string =>
+    v == null ? (element.getAttribute('value') ?? '') : String(v);
+
+  // Apply a new value and fire kai-change once (the user-choice path).
+  const apply = (next: string) => {
+    if (untrack(value) === next) return;
+    setValue(next);
+    dispatch('kai-change', { value: next });
+  };
+
+  // Override the `value` property so reads return LIVE state (the signal) and host
+  // writes (`el.value = …`) drive it WITHOUT firing kai-change — distinct from the
+  // user-choice path. The equality guard kills the reflect write-back loop.
+  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])`).
+  // The guard against the live attribute keeps the write-back the reflect triggers
+  // (attributeChangedCallback → setter) from looping.
+  createEffect(() => {
+    const v = value();
+    if (v) {
+      if (element.getAttribute('value') !== v) element.setAttribute('value', v);
+    } else if (element.hasAttribute('value')) {
+      element.removeAttribute('value');
+    }
+  });
+
+  // Resolve each option's icon-NAME string into a rendered glyph, the same path
+  // kai-button uses for its `icon` prop, and hand the primitive `{value,label,icon:JSX}`.
+  const resolved = (): SegmentedOption[] =>
+    (props.options ?? []).map((o) => ({
+      value: o.value,
+      label: o.label,
+      icon: o.icon
+        ? renderIcon(o.icon, {
+            class: 'size-4 shrink-0',
+            imgClass: 'size-4 shrink-0',
+            spanClass: 'inline-flex size-4 shrink-0 items-center justify-center',
+            ariaHidden: true,
+          })
+        : undefined,
+    }));
+
+  return (
+    <>
+      {/* Base sets `:host{display:block}`; the track flows inline like a pill. */}
+      <style>{':host{display:inline-flex}'}</style>
+      <Segmented
+        options={resolved()}
+        value={value()}
+        size={(props.size as 'sm' | 'md' | undefined) ?? 'md'}
+        onChange={(next) => apply(next)}
+      />
+    </>
+  );
+});

package/src/elements/separator.tsx

@@ -0,0 +1,36 @@
+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 — it stretches 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

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,45 @@
+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}
+    />
+  </>
+));