@kitn.ai/ui 0.16.0 → 0.18.0

package/src/elements/resizable.tsx

@@ -1,6 +1,6 @@
 import { createSignal, createEffect, on, onMount, onCleanup, For, Show, type JSX } from 'solid-js';
 import { defineWebComponent } from './define';
-import { ResizableHandle, normalizeSize } from '../ui/resizable';
+import { ResizableHandle, normalizeSize, clampBasis } from '../ui/resizable';
 
 type Orientation = 'horizontal' | 'vertical';
 
@@ -34,6 +34,7 @@ interface ItemInfo {
   max?: string;
   locked: boolean;
   hidden: boolean;
+  collapsed: boolean;
 }
 
 /** Max number of panels a single group lays out (nest for more). */
@@ -100,6 +101,13 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         el.setAttribute('data-kai-default-size', el.getAttribute('size') ?? '');
       }
       const defaultSize = el.getAttribute('data-kai-default-size') || undefined;
+      // The `collapsed` boolean prop is reflected to a `collapsed` attribute by the
+      // item facade (see kai-resizable-item), so reading the attribute here works
+      // at INITIAL render from any framework — unlike the bare `hidden` boolean,
+      // whose JSX form sets neither the attribute nor the IDL property on a custom
+      // element. Treated as hidden-for-layout, independently of `hidden` so the
+      // back-compat hidden path (and maximize, which drives `hidden`) is untouched.
+      const collapsed = el.hasAttribute('collapsed') && el.getAttribute('collapsed') !== 'false';
       return {
         el,
         size: el.getAttribute('size') ?? undefined,
@@ -111,14 +119,15 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         // (and direct `el.hidden = true`) set the property, which doesn't reflect
         // to the attribute on a custom element.
         hidden: el.hidden || (el.hasAttribute('hidden') && el.getAttribute('hidden') !== 'false'),
+        collapsed,
       };
     });
 
     // Assign each visible item to its panel slot by visible order; clear the
-    // rest so hidden/extra items don't leak into a slot.
+    // rest so hidden/extra/collapsed items don't leak into a slot.
     let visIdx = 0;
     for (const info of parsed) {
-      if (info.hidden) {
+      if (info.hidden || info.collapsed) {
         info.el.removeAttribute('slot');
       } else {
         info.el.setAttribute('slot', `p${visIdx}`);
@@ -153,12 +162,12 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
       const b = next[i];
       if (a.el !== b.el) return true;
       if (a.size !== b.size || a.min !== b.min || a.max !== b.max) return true;
-      if (a.locked !== b.locked || a.hidden !== b.hidden) return true;
+      if (a.locked !== b.locked || a.hidden !== b.hidden || a.collapsed !== b.collapsed) return true;
     }
     return false;
   }
 
-  const visible = () => items().filter((i) => !i.hidden);
+  const visible = () => items().filter((i) => !i.hidden && !i.collapsed);
 
   /** Compute current panel sizes (percent of container) from the rendered DOM. */
   function currentSizes(): number[] {
@@ -358,9 +367,11 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         // maximized item is still present and visible.
         const maximizedEl = stash.item;
         const isConnected = maximizedEl.isConnected && element.contains(maximizedEl);
-        const isVisible = isConnected && !(maximizedEl.hidden || maximizedEl.hasAttribute('hidden'));
+        const isVisible = isConnected
+          && !(maximizedEl.hidden || maximizedEl.hasAttribute('hidden'))
+          && !(maximizedEl.hasAttribute('collapsed') && maximizedEl.getAttribute('collapsed') !== 'false');
         if (!isConnected || !isVisible) {
-          // The maximized item was removed or hidden out from under us → restore.
+          // The maximized item was removed or hidden/collapsed out from under us → restore.
           restore();
           return;
         }
@@ -375,7 +386,7 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
       // the host's own attributes.
       subtree: true,
       attributes: true,
-      attributeFilter: ['size', 'locked', 'min', 'max', 'hidden'],
+      attributeFilter: ['size', 'locked', 'min', 'max', 'hidden', 'collapsed'],
     });
     onCleanup(() => {
       mo.disconnect();
@@ -432,7 +443,9 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
           const min = boundAttrs(info.min);
           const max = boundAttrs(info.max);
           const def = boundAttrs(info.defaultSize);
-          const basis = normalizeSize(info.size);
+          // Clamp the INITIAL basis into [min, max] so a % size on a wide
+          // container never paints past a px max and then snaps on first drag.
+          const basis = clampBasis(normalizeSize(info.size), normalizeSize(info.min), normalizeSize(info.max));
           const prev = () => visible()[i() - 1];
           const isStatic = () => !!(info.locked || prev()?.locked);
           return (
@@ -514,6 +527,16 @@ interface ItemProps extends Record<string, unknown> {
   locked?: boolean;
   /** Hide this panel; its divider is dropped and the rest reflow. */
   hidden?: boolean;
+  /**
+   * Collapse this panel — same layout effect as `hidden` (divider dropped, the
+   * rest reflow), but it WORKS as a bare boolean from framework JSX. A plain
+   * `<kai-resizable-item collapsed>` in React/Solid/Vue/Svelte collapses the panel
+   * at the first render; `hidden` does not, because a JSX boolean sets neither the
+   * `hidden` attribute nor the IDL property on a custom element, so the parent never
+   * sees it. The facade reflects `collapsed` to a `collapsed` attribute the parent
+   * reads. Prefer this over `hidden` for declarative collapse.
+   */
+  collapsed?: boolean;
 }
 
 /**
@@ -527,7 +550,20 @@ defineWebComponent<ItemProps>('kai-resizable-item', {
   max: undefined,
   locked: false,
   hidden: false,
-}, () => (
+  collapsed: false,
+}, (_props, { element, flag }) => {
+  // Reflect the reactive `collapsed` prop to the `collapsed` ATTRIBUTE the parent
+  // <kai-resizable> reads (and observes). This is what makes a bare JSX boolean
+  // collapse the panel at INITIAL render from any framework: component-register
+  // parses `<kai-resizable-item collapsed>` to `undefined` (not `true`), and a JSX
+  // boolean sets neither `hidden` nor the IDL property — so `flag('collapsed')`
+  // (which also honours the attribute) is the reliable source, and toggleAttribute
+  // mirrors it back so the parent's readItems()/MutationObserver lay it out. Same
+  // pattern as <kai-chat>'s `loading` reflection. We touch only `collapsed`, never
+  // `hidden`, so the back-compat hidden path and maximize (which drive `hidden`)
+  // are untouched.
+  createEffect(() => { element.toggleAttribute('collapsed', flag('collapsed')); });
+  return (
   <>
     {/* The item host fills the panel's single grid cell (the panel stretches it on
         both axes) and OWNS the scroll: `display:block; width/height:100%;
@@ -550,4 +586,5 @@ defineWebComponent<ItemProps>('kai-resizable-item', {
       <slot />
     </div>
   </>
-) as unknown as JSX.Element);
+  ) as unknown as JSX.Element;
+});

package/src/elements/screen.tsx

@@ -0,0 +1,90 @@
+import { defineWebComponent } from './define';
+import { Screen, type ScreenController } from '../components/screen';
+import { wireDisclosure } from './disclosure';
+
+interface Props extends Record<string, unknown> {
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute; the element still self-manages). Set `el.open = true`, or
+   *  `<kai-screen open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Header title text. A projected `title` slot overrides it. (Named `headline`
+   *  because `title` collides with the global `HTMLElement.title` attribute.) */
+  headline?: string;
+  /** Show the back button (default true). */
+  back?: boolean;
+  /** Opt out of marking sibling elements inert/aria-hidden while open (for unusual layouts). */
+  noInert?: boolean;
+}
+
+/** Events fired by `<kai-screen>`. */
+interface Events {
+  /** Back navigation intent: the back button or Escape. The consumer flips their
+   *  own routing in response (the screen knows nothing about the trigger). */
+  'kai-back': Record<string, never>;
+  /** The screen opened or closed (a method, `Escape` close, or driven `open`). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-screen>` is a developer-swapped, full-bleed overlay destination: the
+ * push/drill-in surface that takes over its mount point under a back-header. The
+ * developer owns the swap (their own routing flips `open` in response to their
+ * trigger button and the screen's `kai-back`); the screen owns being the takeover.
+ *
+ * It fills whatever it is mounted in (mount at the app root for a full takeover,
+ * in a positioned region for a scoped one), marks sibling elements `inert` while
+ * open (the standard modal pattern; opt out with `no-inert`), moves focus in on
+ * open and restores it on close, and runs an enter/exit transition that honors
+ * `prefers-reduced-motion`. `Escape` fires `kai-back`.
+ *
+ * ```html
+ * <kai-screen headline="Design">
+ *   <button slot="actions"><kai-avatar></kai-avatar></button>
+ *   <div>…your surface…</div>
+ * </kai-screen>
+ * ```
+ *
+ * Open state is the standard disclosure surface: settable+reflecting `open`,
+ * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
+ * Parts: `header` · `back` · `title` · `body`.
+ */
+defineWebComponent<Props, Events>('kai-screen', {
+  open: undefined,
+  defaultOpen: undefined,
+  headline: undefined,
+  back: undefined,
+  noInert: undefined,
+}, (props, ctx) => {
+  const { flag, element, dispatch, expose } = ctx;
+  let api: ScreenController | undefined;
+  let surface: HTMLElement | undefined;
+
+  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle. See ./disclosure. This is the SOLE emitter of kai-open-change.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  // focus() shadows the host's native focus so it targets the screen surface
+  // inside the shadow root (the WebAwesome/Shoelace convention).
+  expose({
+    /** Move focus to the screen surface (no-op while closed). */
+    focus: (options?: FocusOptions) => surface?.focus(options),
+  });
+
+  return (
+    <Screen
+      defaultOpen={flag('defaultOpen')}
+      back={!(props.back === false || element.getAttribute('back') === 'false')}
+      noInert={flag('noInert')}
+      host={() => element}
+      titleSlot={<slot name="title">{props.headline as string | undefined}</slot>}
+      actions={<slot name="actions" />}
+      onBack={() => { dispatch('kai-back', {}); }}
+      controllerRef={(a) => (api = a)}
+      surfaceRef={(el) => (surface = el)}
+    >
+      <slot />
+    </Screen>
+  );
+});

package/src/elements/scroll-area.tsx

@@ -0,0 +1,33 @@
+import { ScrollArea, type ScrollOrientation } from '../ui/scroll-area';
+import { defineWebComponent } from './define';
+
+interface Props extends Record<string, unknown> {
+  /** Which axis scrolls. `vertical` (default) · `horizontal` · `both`. The cross
+   *  axis is clamped so content can't overflow it. */
+  orientation?: ScrollOrientation;
+}
+
+/**
+ * `<kai-scroll-area>` — a scroll container with a themed, thin, cross-browser
+ * scrollbar and a keyboard-reachable region. Project the scrollable content as
+ * light-DOM children and give the element a bounded size in your layout; the
+ * content then scrolls inside. Use `orientation` to pick the axis. Restyle the
+ * container via `::part(viewport)`; the scrollbar follows the
+ * `--color-scrollbar-thumb` token.
+ *
+ * ```html
+ * <kai-scroll-area style="height: 16rem">…long content…</kai-scroll-area>
+ * <kai-scroll-area orientation="horizontal" style="max-width: 24rem">…wide row…</kai-scroll-area>
+ * ```
+ */
+defineWebComponent<Props>('kai-scroll-area', {
+  orientation: 'vertical',
+}, (props) => (
+  <>
+    {/* The element is a block box; the consumer sets its size, the viewport fills it. */}
+    <style>{':host{display:block;min-height:0}'}</style>
+    <ScrollArea class="h-full max-h-full w-full max-w-full" part="viewport" orientation={props.orientation as ScrollOrientation}>
+      <slot />
+    </ScrollArea>
+  </>
+));

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}
+    />
+  );
+});