@kitn.ai/ui 0.17.0 → 0.18.0

package/src/ui/segmented.tsx

@@ -0,0 +1,109 @@
+import { type JSX, For, Show, mergeProps } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface SegmentedOption {
+  value: string;
+  label: string;
+  /** Optional leading icon (a JSX node, e.g. a lucide-solid icon). */
+  icon?: JSX.Element;
+}
+
+export interface SegmentedProps {
+  /** The selectable segments, left to right. */
+  options: SegmentedOption[];
+  /** The selected segment's `value` (controlled). */
+  value: string;
+  /** Fires with the next `value` when a segment is chosen. */
+  onChange: (value: string) => void;
+  /** Control density. Defaults to `md`. */
+  size?: 'sm' | 'md';
+  class?: string;
+}
+
+const SIZE: Record<'sm' | 'md', string> = {
+  sm: 'h-7 px-2 text-xs',
+  md: 'h-8 px-3 text-sm',
+};
+
+/**
+ * `Segmented`: a single-select pill track (a.k.a. segmented / toggle-group). A
+ * recessed `bg-surface-sunken` rail of segment buttons where the selected segment
+ * lifts onto a raised `bg-background` chip. Token-driven, light + dark.
+ *
+ * a11y: `role="group"` of real `<button>`s, each carrying `aria-pressed`; a roving
+ * tabindex (only the selected segment is in the tab order) with Arrow / Home / End
+ * key navigation that moves selection between segments.
+ */
+export function Segmented(props: SegmentedProps): JSX.Element {
+  const merged = mergeProps({ size: 'md' as const }, props);
+  const buttons: HTMLButtonElement[] = [];
+
+  const currentIndex = () => merged.options.findIndex((o) => o.value === merged.value);
+
+  const select = (i: number) => {
+    const opt = merged.options[i];
+    if (!opt) return;
+    merged.onChange(opt.value);
+    buttons[i]?.focus();
+  };
+
+  const onKeyDown = (e: KeyboardEvent) => {
+    const count = merged.options.length;
+    if (count === 0) return;
+    const cur = currentIndex();
+    if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+      e.preventDefault();
+      select((Math.max(cur, 0) + 1) % count);
+    } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
+      e.preventDefault();
+      select((Math.max(cur, 0) - 1 + count) % count);
+    } else if (e.key === 'Home') {
+      e.preventDefault();
+      select(0);
+    } else if (e.key === 'End') {
+      e.preventDefault();
+      select(count - 1);
+    }
+  };
+
+  return (
+    <div
+      role="group"
+      part="track"
+      onKeyDown={onKeyDown}
+      class={cn('inline-flex items-center gap-0.5 rounded-lg bg-surface-sunken p-0.5', merged.class)}
+    >
+      <For each={merged.options}>
+        {(opt, i) => {
+          const selected = () => opt.value === merged.value;
+          // Roving tabindex: the selected segment is tabbable; if nothing matches,
+          // the first segment falls back to tabbable so the group is reachable.
+          const focusable = () => selected() || (currentIndex() === -1 && i() === 0);
+          return (
+            <button
+              type="button"
+              part="segment"
+              ref={(el) => { buttons[i()] = el; }}
+              aria-pressed={selected()}
+              tabindex={focusable() ? 0 : -1}
+              onClick={() => merged.onChange(opt.value)}
+              class={cn(
+                'inline-flex items-center justify-center gap-1.5 rounded-md font-medium transition-colors',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                SIZE[merged.size],
+                selected()
+                  ? 'bg-background text-foreground shadow-sm'
+                  : 'text-muted-foreground hover:text-foreground',
+              )}
+            >
+              <Show when={opt.icon}>
+                <span class="inline-flex shrink-0 items-center" aria-hidden="true">{opt.icon}</span>
+              </Show>
+              <span>{opt.label}</span>
+            </button>
+          );
+        }}
+      </For>
+    </div>
+  );
+}

package/src/ui/settings-group.tsx

@@ -0,0 +1,67 @@
+import { type JSX, Show } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface SettingsGroupProps {
+  /** Small section heading shown above the card. */
+  heading: string;
+  /** Optional muted description under the heading. */
+  description?: string;
+  /** The stacked `SettingItem` rows. */
+  children: JSX.Element;
+  class?: string;
+}
+
+/**
+ * A settings section: a small heading + optional muted description over a bordered,
+ * rounded card that stacks `SettingItem` rows with hairline dividers between them.
+ * Host-agnostic chrome: the SAME group drops into a modal or a full settings page;
+ * only the content (the rows) changes per app.
+ */
+export function SettingsGroup(props: SettingsGroupProps): JSX.Element {
+  return (
+    <section class={cn('flex flex-col gap-2', props.class)}>
+      <div part="header" class="flex flex-col gap-0.5 px-1">
+        <h3 class="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+          {props.heading}
+        </h3>
+        <Show when={props.description}>
+          <p class="text-xs text-muted-foreground">{props.description}</p>
+        </Show>
+      </div>
+      <div part="body" class="divide-y divide-border overflow-hidden rounded-xl border border-border bg-surface">
+        {props.children}
+      </div>
+    </section>
+  );
+}
+
+export interface SettingItemProps {
+  /** Row label (primary text). */
+  label: string;
+  /** Optional secondary description under the label. */
+  description?: string;
+  /** The control on the right (a `Switch`, `Segmented`, select, ...). Omit for a
+   *  plain label row. */
+  control?: JSX.Element;
+  class?: string;
+}
+
+/**
+ * One row inside a `SettingsGroup`: a left label/description block and an optional
+ * right-aligned `control`, vertically centered with comfortable padding.
+ */
+export function SettingItem(props: SettingItemProps): JSX.Element {
+  return (
+    <div class={cn('flex items-center justify-between gap-4 px-4 py-3', props.class)}>
+      <div part="label" class="flex min-w-0 flex-col gap-0.5">
+        <span class="text-sm text-foreground">{props.label}</span>
+        <Show when={props.description}>
+          <span class="text-xs leading-snug text-muted-foreground">{props.description}</span>
+        </Show>
+      </div>
+      <Show when={props.control}>
+        <div part="control" class="shrink-0">{props.control}</div>
+      </Show>
+    </div>
+  );
+}

package/src/ui/skeleton.tsx

@@ -1,16 +1,73 @@
-import { type JSX, splitProps } from 'solid-js';
+import { type JSX, splitProps, For, Show } from 'solid-js';
 import { cn } from '../utils/cn';
 
-export interface SkeletonProps extends JSX.HTMLAttributes<HTMLDivElement> {}
+export type SkeletonVariant = 'text' | 'rect' | 'circle';
+
+export interface SkeletonProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  /** Shape preset. `text` = one or more lines; `rect` = a block; `circle` =
+   *  round. Omit for the bare, class-driven block (size it with utility classes
+   *  yourself — the original low-level usage). */
+  variant?: SkeletonVariant;
+  /** CSS width (a number is treated as px). With a `variant` and no width it
+   *  fills its container (responsive); for `circle` it is the diameter. */
+  width?: string | number;
+  /** CSS height (a number is treated as px). Defaults per variant. */
+  height?: string | number;
+  /** `text` only: how many lines to render (the last is shorter). Default 1. */
+  lines?: number;
+}
+
+const len = (v?: string | number) => (typeof v === 'number' ? `${v}px` : v);
+
+const rounding = (variant?: SkeletonVariant) =>
+  variant === 'circle' ? 'rounded-full' : variant === 'text' ? 'rounded' : 'rounded-md';
 
 function Skeleton(props: SkeletonProps) {
-  const [local, rest] = splitProps(props, ['class']);
-  return (
+  const [local, rest] = splitProps(props, ['class', 'variant', 'width', 'height', 'lines', 'style']);
+
+  const hasWidth = () => local.width != null;
+  const hasHeight = () => local.height != null;
+  // The responsive default applies only to the variant API; bare class-driven
+  // usage is left untouched so `<Skeleton class="h-4 w-64" />` keeps working.
+  const fills = () => !hasWidth() && local.variant != null && local.variant !== 'circle';
+
+  const blockStyle = (shortLast: boolean): JSX.CSSProperties => {
+    const style: JSX.CSSProperties = typeof local.style === 'object' && local.style ? { ...local.style } : {};
+    if (local.variant === 'circle') {
+      const d = len(local.width) ?? len(local.height) ?? '2.5rem';
+      style.width = d;
+      style.height = d;
+      return style;
+    }
+    if (shortLast) style.width = '70%';
+    else if (hasWidth()) style.width = len(local.width);
+    if (hasHeight()) style.height = len(local.height);
+    else if (local.variant === 'text') style.height = '0.75rem';
+    return style;
+  };
+
+  const block = (shortLast = false) => (
     <div
-      class={cn('animate-pulse rounded-md bg-muted', local.class)}
+      part="skeleton"
+      // `bg-foreground/10` tints from the theme foreground, so it keeps a visible
+      // ~10% contrast against the background in BOTH light and dark (the old
+      // `bg-muted` was nearly invisible on a light surface). Recolor / restyle
+      // opacity from outside via `::part(skeleton)`.
+      class={cn('animate-pulse bg-foreground/10', rounding(local.variant), fills() && 'w-full', local.class)}
+      style={blockStyle(shortLast)}
       {...rest}
     />
   );
+
+  const lineCount = () => (local.variant === 'text' ? Math.max(1, local.lines ?? 1) : 1);
+
+  return (
+    <Show when={lineCount() > 1} fallback={block()}>
+      <div class="flex w-full flex-col gap-2">
+        <For each={Array.from({ length: lineCount() })}>{(_, i) => block(i() === lineCount() - 1)}</For>
+      </div>
+    </Show>
+  );
 }
 
 export { Skeleton };

package/src/ui/stat.tsx

@@ -0,0 +1,41 @@
+import { Show, type JSX, splitProps } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface StatProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  /** The small muted caption above the value. */
+  label?: string;
+  /** The big value. A default-slot / `children` override wins over this. */
+  value?: string;
+  /** A small caption below the value. */
+  hint?: string;
+}
+
+/**
+ * A single metric / KPI tile: a muted label on top, a large value below, and an
+ * optional hint caption. The consumer arranges tiles in their own CSS grid — this
+ * is ONE cell. `children` (the default slot in the element) override `value` for
+ * rich content.
+ */
+export function Stat(props: StatProps) {
+  const [local, rest] = splitProps(props, ['label', 'value', 'hint', 'class', 'children']);
+  return (
+    <div
+      part="stat"
+      class={cn('flex flex-col gap-1 rounded-lg bg-surface p-3', local.class)}
+      {...rest}
+    >
+      <Show when={local.label}>
+        <span part="label" class="text-xs text-muted-foreground">{local.label}</span>
+      </Show>
+      <span part="value" class="text-2xl font-semibold leading-tight text-foreground">
+        {local.children ?? local.value}
+      </span>
+      {/* When used directly (no slot), `value` renders; the element facade
+          passes a <slot>{value}</slot> as `children`, so projected light-DOM
+          content overrides `value` while `value` remains the slot's fallback. */}
+      <Show when={local.hint}>
+        <span class="text-xs text-muted-foreground">{local.hint}</span>
+      </Show>
+    </div>
+  );
+}

package/src/ui/status.tsx

@@ -0,0 +1,48 @@
+import { type JSX, Show, splitProps } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export type StatusKind = 'new' | 'online' | 'busy' | 'away' | 'offline';
+
+/** status → background hue utility (backed by the kit's tool-* / muted tokens). */
+export const STATUS_BG: Record<StatusKind, string> = {
+  new: 'bg-tool-blue',
+  online: 'bg-tool-green',
+  busy: 'bg-tool-red',
+  away: 'bg-tool-amber',
+  offline: 'bg-muted-foreground',
+};
+
+const SIZE: Record<'sm' | 'md', string> = { sm: 'size-2', md: 'size-2.5' };
+
+export interface StatusProps extends JSX.HTMLAttributes<HTMLSpanElement> {
+  status?: StatusKind;
+  size?: 'sm' | 'md';
+  /** Add an animated ping ring (disabled under prefers-reduced-motion). */
+  pulse?: boolean;
+  /** Accessible name. With it, the dot is announced; without it, it is decorative. */
+  label?: string;
+}
+
+export function Status(props: StatusProps) {
+  const [local, rest] = splitProps(props, ['status', 'size', 'pulse', 'label', 'class']);
+  const kind = () => local.status ?? 'new';
+  return (
+    <span
+      class={cn('relative inline-flex', local.class)}
+      role={local.label ? 'status' : undefined}
+      aria-label={local.label}
+      aria-hidden={local.label ? undefined : 'true'}
+    >
+      <Show when={local.pulse}>
+        <span
+          aria-hidden="true"
+          class={cn(
+            'absolute inline-flex h-full w-full animate-ping rounded-full opacity-75 motion-reduce:hidden',
+            STATUS_BG[kind()],
+          )}
+        />
+      </Show>
+      <span {...rest} class={cn('relative inline-block rounded-full', STATUS_BG[kind()], SIZE[local.size ?? 'sm'])} />
+    </span>
+  );
+}

package/src/ui/switch.tsx

@@ -3,7 +3,7 @@ import { cn } from '../utils/cn';
 
 export interface SwitchProps {
   /** Controlled checked state. When set, the component defers state to the
-   *  parent — drive it from `onChange`. Omit for uncontrolled (internal) state. */
+   *  parent; drive it from `onChange`. Omit for uncontrolled (internal) state. */
   checked?: boolean;
   /** Initial checked state when uncontrolled. */
   defaultChecked?: boolean;
@@ -11,8 +11,15 @@ export interface SwitchProps {
   disabled?: boolean;
   /** Accessible label for the control. */
   label?: string;
+  /** Form-control name. When set (paired with `value`), a hidden checkbox carries
+   *  the on/off value for serialization. */
+  name?: string;
+  /** Submitted value when checked (paired with `name`). Defaults to `'on'`. */
+  value?: string;
   /** Fires with the next checked state on toggle. */
   onChange?: (checked: boolean) => void;
+  /** Receives the inner `role="switch"` button so a parent can focus it. */
+  buttonRef?: (el: HTMLButtonElement) => void;
   class?: string;
 }
 
@@ -33,30 +40,49 @@ export function Switch(props: SwitchProps) {
   };
 
   return (
-    <button
-      type="button"
-      role="switch"
-      aria-checked={isOn()}
-      aria-label={props.label}
-      disabled={props.disabled}
-      onClick={toggle}
-      onKeyDown={(e) => {
-        if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); toggle(); }
-      }}
-      class={cn(
-        'relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full transition-colors',
-        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
-        'disabled:cursor-not-allowed disabled:opacity-50',
-        isOn() ? 'bg-primary' : 'bg-muted',
-        props.class,
+    <>
+      {props.name != null && (
+        <input
+          type="checkbox"
+          name={props.name}
+          value={props.value ?? 'on'}
+          checked={isOn()}
+          disabled={props.disabled}
+          aria-hidden="true"
+          tabindex={-1}
+          style={{ position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', clip: 'rect(0 0 0 0)', 'white-space': 'nowrap' }}
+          onChange={() => { /* driven by the button; keep the input in sync only */ }}
+        />
       )}
-    >
-      <span
+      <button
+        type="button"
+        role="switch"
+        ref={props.buttonRef}
+        aria-checked={isOn()}
+        aria-label={props.label}
+        disabled={props.disabled}
+        onClick={toggle}
+        onKeyDown={(e) => {
+          if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); toggle(); }
+        }}
         class={cn(
-          'inline-block h-4 w-4 rounded-full bg-white shadow transition-transform',
-          isOn() ? 'translate-x-[1.125rem]' : 'translate-x-0.5',
+          'relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full transition-colors',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          isOn() ? 'bg-primary' : 'bg-muted',
+          props.class,
         )}
-      />
-    </button>
+      >
+        <span
+          class={cn(
+            'inline-block h-4 w-4 rounded-full shadow transition-transform',
+            // On the `primary` track use `primary-foreground` so the thumb stays
+            // visible in both themes (in dark mode `primary` is light, where a
+            // hard-coded white thumb vanished). Off-track stays white over `muted`.
+            isOn() ? 'translate-x-[1.125rem] bg-primary-foreground' : 'translate-x-0.5 bg-white',
+          )}
+        />
+      </button>
+    </>
   );
 }

package/src/ui/tabs.tsx

@@ -0,0 +1,168 @@
+import { For, type JSX, splitProps } from 'solid-js';
+import { renderIcon } from './icon';
+import { cn } from '../utils/cn';
+
+/** One tab in a `Tabs` strip. `id` is the selected `value` throughout. */
+export interface KaiTabItem {
+  /** Stable id, emitted as the selected `value`. Also useful for `aria-controls`. */
+  id: string;
+  label?: string;
+  /** Named icon (e.g. "code"), image URL / data-URI, or plain text. */
+  icon?: string;
+  disabled?: boolean;
+}
+
+export type TabsVariant = 'segmented' | 'underline';
+
+/** variant → tablist container utilities. */
+export const TABLIST_CLASS: Record<TabsVariant, string> = {
+  segmented: 'inline-flex items-center gap-1 rounded-lg bg-muted p-1',
+  underline: 'inline-flex items-center gap-1 border-b border-border',
+};
+
+/** variant → per-tab utilities, given whether the tab is active. */
+export function tabClass(variant: TabsVariant, active: boolean): string {
+  const base =
+    'inline-flex items-center gap-1.5 whitespace-nowrap text-sm font-medium transition-colors ' +
+    'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring ' +
+    'disabled:pointer-events-none disabled:opacity-50';
+  if (variant === 'underline') {
+    return cn(
+      base,
+      'border-b-2 px-3 py-2 -mb-px',
+      active
+        ? 'border-primary text-foreground'
+        : 'border-transparent text-muted-foreground hover:text-foreground',
+    );
+  }
+  return cn(
+    base,
+    'rounded-md px-3 py-1.5',
+    active
+      ? 'bg-background text-foreground shadow-sm'
+      : 'text-muted-foreground hover:text-foreground',
+  );
+}
+
+export interface TabsProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  items?: KaiTabItem[];
+  /** Selected item id. */
+  value?: string;
+  variant?: TabsVariant;
+  /** Stretch the strip to full width, each tab sharing the space equally. */
+  block?: boolean;
+  /** Disable the whole strip. */
+  disabled?: boolean;
+  /** Fired with the newly-selected item's id. */
+  onChange?: (value: string) => void;
+  /** Capture the tablist node (so the facade's `focus()` can target the active tab). */
+  ref?: (el: HTMLDivElement) => void;
+}
+
+/**
+ * Accessible tab strip. Selection only (emits the selected id via `onChange`);
+ * the consumer renders each tab's content. Roving tabindex, Arrow/Home/End
+ * keyboard nav, disabled items skipped.
+ */
+export function Tabs(props: TabsProps) {
+  const [local, rest] = splitProps(props, [
+    'items', 'value', 'variant', 'block', 'disabled', 'onChange', 'ref', 'class',
+  ]);
+  const items = () => local.items ?? [];
+  const variant = (): TabsVariant => local.variant ?? 'segmented';
+
+  const tabEls: Record<string, HTMLButtonElement> = {};
+
+  const enabled = () => items().filter((it) => !it.disabled);
+  const activeId = () => local.value;
+
+  // Roving tabindex needs exactly one tab in the tab order. The active tab gets
+  // it; if nothing is selected, the first enabled tab does, so the strip is still
+  // reachable by Tab.
+  const rovingId = () => {
+    if (activeId() !== undefined && enabled().some((it) => it.id === activeId())) return activeId();
+    return enabled()[0]?.id;
+  };
+
+  const select = (item: KaiTabItem) => {
+    if (local.disabled || item.disabled) return;
+    if (item.id === local.value) return;
+    local.onChange?.(item.id);
+  };
+
+  // Roving focus: move focus to the target tab and emit selection (activate on focus move).
+  const focusId = (id: string) => {
+    const el = tabEls[id];
+    if (el) el.focus();
+  };
+
+  const onKeyDown = (e: KeyboardEvent, item: KaiTabItem) => {
+    const list = enabled();
+    if (list.length === 0) return;
+    const i = list.findIndex((it) => it.id === item.id);
+    let next: KaiTabItem | undefined;
+    switch (e.key) {
+      case 'ArrowRight':
+      case 'ArrowDown':
+        next = list[(i + 1) % list.length];
+        break;
+      case 'ArrowLeft':
+      case 'ArrowUp':
+        next = list[(i - 1 + list.length) % list.length];
+        break;
+      case 'Home':
+        next = list[0];
+        break;
+      case 'End':
+        next = list[list.length - 1];
+        break;
+      case 'Enter':
+      case ' ':
+        e.preventDefault();
+        select(item);
+        return;
+      default:
+        return;
+    }
+    if (next) {
+      e.preventDefault();
+      select(next);
+      focusId(next.id);
+    }
+  };
+
+  return (
+    <div
+      {...rest}
+      ref={(el) => local.ref?.(el)}
+      role="tablist"
+      part="tablist"
+      aria-disabled={local.disabled ? 'true' : undefined}
+      class={cn(TABLIST_CLASS[variant()], local.block && 'flex w-full', local.class)}
+    >
+      <For each={items()}>
+        {(item) => {
+          const active = () => item.id === activeId();
+          return (
+            <button
+              ref={(el) => { tabEls[item.id] = el; }}
+              type="button"
+              part="tab"
+              role="tab"
+              data-active={active() ? '' : undefined}
+              aria-selected={active() ? 'true' : 'false'}
+              tabindex={item.id === rovingId() ? 0 : -1}
+              disabled={local.disabled || item.disabled}
+              class={cn(tabClass(variant(), active()), local.block && 'flex-1 justify-center')}
+              onClick={() => select(item)}
+              onKeyDown={(e) => onKeyDown(e, item)}
+            >
+              {renderIcon(item.icon, { class: 'size-4 shrink-0' })}
+              {item.label}
+            </button>
+          );
+        }}
+      </For>
+    </div>
+  );
+}