@kitn.ai/ui 0.17.0 → 0.18.0

package/src/elements/file-tree.tsx

@@ -2,12 +2,14 @@ import { defineWebComponent } from './define';
 import { FileTree, type FileTreeFile } from '../components/file-tree';
 
 interface Props extends Record<string, unknown> {
-  /** The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type? }`). */
+  /** The files to render. Set as a JS property (array of `{ path, url?, code?, language?, type?, additions?, deletions?, status? }`). */
   files: FileTreeFile[];
   /** Selected file path — highlighted in the tree. */
   activeFile?: string;
   /** Folder paths expanded initially. Omit to start with all folders open. */
   defaultExpanded?: string[];
+  /** Show a changed-files summary header (file count + summed `+/-` + Collapse-all). Attribute: `summary`. Off by default. */
+  summary?: boolean;
 }
 
 interface Events extends Record<string, unknown> {
@@ -19,12 +21,19 @@ interface Events extends Record<string, unknown> {
  * `<kai-file-tree>` — a collapsible, keyboard-navigable file explorer built from a
  * flat list of `/`-delimited paths (folders are derived). ARIA `tree`/`treeitem`.
  * Selecting a file fires a `select` event (`detail.path`). Fills its container.
+ *
+ * For a changed-files / diff view, give each file `additions`/`deletions`/`status`
+ * (rendered as trailing `+N`/`-N` stats and a colored status letter), and set the
+ * `summary` attribute for a header with the changed-file count, summed `+/-`, and a
+ * Collapse-all toggle. Restyle the diff bits via `::part(summary | status |
+ * stat-additions | stat-deletions)`.
  */
 defineWebComponent<Props, Events>('kai-file-tree', {
   files: [],
   activeFile: undefined,
   defaultExpanded: undefined,
-}, (props, { dispatch }) => (
+  summary: false,
+}, (props, { dispatch, flag }) => (
   <>
     {/* Fill the container + own the scroll (see resizable.tsx fill technique:
         a definite `1fr` grid cell scoped to a wrapper, NOT :host, so the facade's
@@ -44,6 +53,7 @@ defineWebComponent<Props, Events>('kai-file-tree', {
           files={props.files}
           activeFile={props.activeFile}
           defaultExpanded={props.defaultExpanded}
+          summary={flag('summary')}
           onSelect={(path) => dispatch('kai-select', { path })}
         />
       </div>

package/src/elements/file-upload.tsx

@@ -36,7 +36,7 @@ defineWebComponent<Props, Events>('kai-file-upload', {
     disabled={flag('disabled')}
     onFilesAdded={(files) => dispatch('kai-files-added', { files })}
   >
-    <FileUploadTrigger class="border-border bg-muted/30 hover:bg-muted/60 text-muted-foreground flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-xl border border-dashed px-6 py-8 text-sm transition-colors">
+    <FileUploadTrigger class="border-border bg-surface hover:bg-muted/60 text-muted-foreground flex w-full cursor-pointer flex-col items-center justify-center gap-2 rounded-xl border border-dashed px-6 py-8 text-sm transition-colors">
       <Upload class="size-5" />
       <slot>{props.label}</slot>
     </FileUploadTrigger>

package/src/elements/form.tsx

@@ -1,5 +1,5 @@
 import { defineWebComponent } from './define';
-import { Form, type FormDefinition } from '../components/form';
+import { Form, type FormController, type FormDefinition } from '../components/form';
 import type { CardResolution } from '../primitives/card-contract';
 
 interface Props extends Record<string, unknown> {
@@ -15,6 +15,20 @@ interface Props extends Record<string, unknown> {
   /** Set when the user resolved this card; renders the read-only view. Property:
    *  `el.resolution = { kind:'submit', data:{…} }`. */
   resolution?: Record<string, unknown>;
+  /** Controlled field values (JS property). When set, it wins over local edits. */
+  values?: Record<string, unknown>;
+  /** Initial values overlaying the schema defaults (uncontrolled seed; JS property). */
+  defaultValues?: Record<string, unknown>;
+  /** Disable all fields + submit. Attribute: `disabled`. */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-form>`. (Resolution still flows up the bubbling `kai-card`
+ *  contract event — `kai-values-change` is the live change signal, distinct from the
+ *  terminal submit.) */
+interface Events {
+  /** The form's values changed on input — current coerced values + validity. */
+  'kai-values-change': { values: Record<string, unknown>; valid: boolean };
 }
 
 /**
@@ -27,17 +41,46 @@ interface Props extends Record<string, unknown> {
  * else the bubbling `kai-card` event (so a bare `<kai-form>` works without a host).
  * Isolated in Shadow DOM; theme-aware via the shared kit tokens.
  */
-defineWebComponent<Props>('kai-form', {
+defineWebComponent<Props, Events>('kai-form', {
   data: undefined,
   cardId: undefined,
   heading: undefined,
   resolution: undefined,
-}, (props, { element }) => (
-  <Form
-    data={props.data as FormDefinition | undefined}
-    cardId={props.cardId ?? (element.id || 'kai-form')}
-    heading={props.heading}
-    resolution={props.resolution as CardResolution | undefined}
-    hostElement={element}
-  />
-));
+  values: undefined,
+  defaultValues: undefined,
+  disabled: false,
+}, (props, { element, dispatch, flag, expose }) => {
+  // Pattern C: the Form component owns the value store + validation and hands up a
+  // controller; the facade captures it and exposes delegating instance methods.
+  let controller: FormController | undefined;
+  expose({
+    /** Focus the first control, or the first INVALID control after a failed validation. */
+    focus: (options?: FocusOptions) => controller?.focus(options),
+    /** Validate + submit programmatically — focus the first invalid field on failure,
+     *  else emit the `submit` CardEvent and resolve. Named `send`, not `submit`. */
+    send: () => controller?.send(),
+    /** Run client-side validation now and return `{ valid, errors? }` WITHOUT submitting. */
+    validate: () => controller?.validate() ?? { valid: false },
+    /** Re-seed the form from each field's `default` and clear errors. */
+    reset: () => controller?.reset(),
+    /** Trigger the dismiss path (emit `dismiss` + collapse to the re-openable stub). */
+    dismiss: () => controller?.dismiss(),
+    /** Re-open a dismissed card from its stub (emit `reopen`). */
+    reopen: () => controller?.reopen(),
+  });
+
+  return (
+    <Form
+      data={props.data as FormDefinition | undefined}
+      cardId={props.cardId ?? (element.id || 'kai-form')}
+      heading={props.heading}
+      resolution={props.resolution as CardResolution | undefined}
+      values={props.values as Record<string, unknown> | undefined}
+      defaultValues={props.defaultValues as Record<string, unknown> | undefined}
+      disabled={flag('disabled')}
+      onValuesChange={(payload) => dispatch('kai-values-change', payload)}
+      controllerRef={(c) => (controller = c)}
+      hostElement={element}
+    />
+  );
+});

package/src/elements/hover-card.tsx

@@ -0,0 +1,80 @@
+import { type Placement } from '@floating-ui/dom';
+import { HoverCardRoot, HoverCardTrigger, HoverCardContent, type HoverCardController } from '../ui/hover-card';
+import { defineWebComponent } from './define';
+import { wireDisclosure } from './disclosure';
+
+interface Props extends Record<string, unknown> {
+  /** Delay (ms) before the card opens on hover. Defaults to 0 (focus opens it
+   *  immediately too). */
+  openDelay?: number;
+  /** Delay (ms) before it closes after the pointer leaves. Defaults to 300. */
+  closeDelay?: number;
+  /** Preferred placement: `'top' | 'bottom' | 'left' | 'right'` (+ optional
+   *  `-start`/`-end`). Defaults to `'bottom'`; flips to stay in view. */
+  placement?: string;
+  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
+   *  attribute, the element still self-manages on hover). Set `el.open = true`,
+   *  or `<kai-hover-card open>`; listen for `kai-open-change`. */
+  open?: boolean;
+  /** Initial open state on mount (uncontrolled seed). */
+  defaultOpen?: boolean;
+  /** Suppress the hover behavior entirely without unmounting. */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kai-hover-card>`. */
+interface Events {
+  /** The card opened or closed (by hover/focus, outside-click, or a method). */
+  'kai-open-change': { open: boolean };
+}
+
+/**
+ * `<kai-hover-card>` — reveals RICH content on hover/focus of a trigger (the
+ * markup-carrying sibling of the text-only `<kai-tooltip>`). Put the trigger as
+ * default light-DOM content and the card body in `slot="card"`. The card is
+ * portaled + positioned inside the shadow root, with a transparent hover bridge
+ * so the pointer can travel into it.
+ *
+ * ```html
+ * <kai-hover-card>
+ *   <a href="#">@acme</a>
+ *   <div slot="card">
+ *     <strong>Acme Corp</strong>
+ *     <p>Workspace · 24 members</p>
+ *   </div>
+ * </kai-hover-card>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-hover-card', {
+  openDelay: undefined,
+  closeDelay: undefined,
+  placement: undefined,
+  open: undefined,
+  defaultOpen: undefined,
+  disabled: undefined,
+}, (props, ctx) => {
+  const { flag } = ctx;
+  let api: HoverCardController | undefined;
+
+  // The standard overlay surface: settable+reflecting `open`, kai-open-change,
+  // show/hide/toggle, disabled-gating. See ./disclosure.
+  wireDisclosure(ctx, () => api, () => props.open);
+
+  return (
+    <>
+      <style>{':host{display:inline-block}'}</style>
+      <HoverCardRoot
+        openDelay={props.openDelay != null ? Number(props.openDelay) : undefined}
+        closeDelay={props.closeDelay != null ? Number(props.closeDelay) : undefined}
+        defaultOpen={flag('defaultOpen')}
+        disabled={flag('disabled')}
+        controllerRef={(a) => (api = a)}
+      >
+        <HoverCardTrigger><slot /></HoverCardTrigger>
+        <HoverCardContent placement={(props.placement as Placement | undefined) ?? undefined}>
+          <slot name="card" />
+        </HoverCardContent>
+      </HoverCardRoot>
+    </>
+  );
+});

package/src/elements/icon-names.json

@@ -0,0 +1,48 @@
+[
+  "archive",
+  "arrow-left",
+  "arrow-up",
+  "audio-lines",
+  "book-open",
+  "bookmark",
+  "box",
+  "briefcase",
+  "chevron-down",
+  "chevron-left",
+  "circle",
+  "clock",
+  "code",
+  "copy",
+  "ellipsis",
+  "external-link",
+  "file-text",
+  "flag",
+  "folder",
+  "git-branch",
+  "git-pull-request",
+  "github",
+  "globe",
+  "home",
+  "image",
+  "list-filter",
+  "lock",
+  "message-circle",
+  "message-square",
+  "mic",
+  "monitor",
+  "more-horizontal",
+  "panel-left",
+  "paperclip",
+  "pencil",
+  "plus",
+  "rotate-cw",
+  "search",
+  "settings",
+  "share",
+  "sliders-horizontal",
+  "smile",
+  "sparkles",
+  "square-pen",
+  "workflow",
+  "x"
+]

package/src/elements/icon.tsx

@@ -0,0 +1,41 @@
+import { renderIcon } from '../ui/icon';
+import { cn } from '../utils/cn';
+import { defineWebComponent } from './define';
+
+const SIZE: Record<string, string> = { sm: 'size-3.5', md: 'size-4', lg: 'size-5' };
+
+interface Props extends Record<string, unknown> {
+  /** A curated icon name (e.g. `"mic"`, `"globe"`), an image URL/data-URI, or
+   *  plain text. */
+  name?: string;
+  /** Size token: `sm` | `md` (default) | `lg`. */
+  size?: 'sm' | 'md' | 'lg';
+}
+
+/**
+ * `<kai-icon>` — render one of the kit's curated icons (inline SVG) in your own
+ * markup, so surrounding UI can match the kit without pulling in an icon library.
+ * `name` also accepts a URL/data-URI or text. Renders in the theme's foreground by
+ * default; recolor with `kai-icon::part(icon){ color: … }`.
+ *
+ * Scope: the kit's small, *curated* icon set — not a general icon library. For
+ * anything outside it, drop your own inline SVG into an element's `icon` slot.
+ *
+ * ```html
+ * <kai-icon name="globe"></kai-icon>
+ * <kai-icon name="sparkles" size="lg"></kai-icon>
+ * ```
+ */
+defineWebComponent<Props>('kai-icon', {
+  name: '',
+  size: 'md',
+}, (props) => (
+  <>
+    {/* Base sets `:host{display:block}`; an inline icon must flow with surrounding
+        text (and not force a line break), so inline-flex like kai-button. */}
+    <style>{':host{display:inline-flex}'}</style>
+    <span part="icon" class={cn('inline-flex shrink-0', SIZE[props.size ?? 'md'] ?? SIZE.md)}>
+      {renderIcon(props.name, { class: 'size-full', imgClass: 'size-full', spanClass: 'size-full' })}
+    </span>
+  </>
+));

package/src/elements/input.tsx

@@ -0,0 +1,203 @@
+import { createEffect, createSignal, onCleanup, onMount, untrack } from 'solid-js';
+import { defineWebComponent } from './define';
+import { Input, type InputProps } from '../ui/input';
+
+interface Props extends Record<string, unknown> {
+  /** Native input type: `text` (default) · `email` · `url` · `search` · `tel` ·
+   *  `password` · `number`. Single-line only. */
+  type?: string;
+  /** Controlled value — settable and reflected to the `value` attribute. `el.value
+   *  = 'hi'` drives it (no event); typing updates it and fires `kai-input`. Read
+   *  `el.value` for live state. */
+  value?: string;
+  /** Placeholder shown when empty. */
+  placeholder?: string;
+  /** Field label, linked to the input. */
+  label?: string;
+  /** Helper text below the control. */
+  hint?: string;
+  /** Error text; flips the field invalid (`aria-invalid` + destructive border). */
+  error?: string;
+  /** Control density: `sm` or `md`. Defaults to `md`. */
+  size?: 'sm' | 'md';
+  /** Disable interaction. */
+  disabled?: boolean;
+  /** Make the input read-only. */
+  readonly?: boolean;
+  /** Mark the input required. */
+  required?: boolean;
+  /** Force the invalid state without an `error` string. */
+  invalid?: boolean;
+  /** Form-control name. */
+  name?: string;
+  /** Autofill hint forwarded to the inner input (e.g. `email`, `current-password`). */
+  autocomplete?: string;
+  /** Virtual-keyboard hint forwarded to the inner input (e.g. `numeric`, `email`). */
+  inputmode?: string;
+  // NOTE: `autocapitalize` is forwarded too, but NOT as a declared prop — see the
+  // attribute read in the facade body (it is a global reflected HTMLElement IDL
+  // attribute and would break the element constructor as a component-register prop).
+}
+
+/** Events fired by `<kai-input>`. */
+interface Events {
+  /** The value changed per keystroke. */
+  'kai-input': { value: string };
+  /** The value was committed (blur). */
+  'kai-change': { value: string };
+}
+
+/** Named slots whose occupancy gates an affix. An empty `<slot>` is always a
+ *  truthy node, so the facade tracks which are actually filled and only hands a
+ *  `<slot>` to the primitive when content is assigned — otherwise the primitive
+ *  would switch to the affix-row layout for an empty slot. */
+const SLOT_NAMES = ['leading', 'trailing'] as const;
+type SlotName = (typeof SLOT_NAMES)[number];
+
+/**
+ * `<kai-input>` — the kit's single-line text field. Drive/read the value with the
+ * `value` property (settable + reflected to the `value` attribute, so
+ * `:host([value])` and `el.value` see live state); listen for `kai-input` (per
+ * keystroke) and `kai-change` (commit/blur). A `label`, `hint`, and `error` wrap
+ * the control; `leading`/`trailing` slots take an icon, unit, or inline button.
+ *
+ * ```html
+ * <kai-input label="Workspace" placeholder="Acme Inc."></kai-input>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const field = document.querySelector('kai-input');
+ *   field.addEventListener('kai-input', (e) => console.log(e.detail.value));
+ *   field.value = 'Acme';   // drive it (no event — the host already knows)
+ *   field.focus();          // focus the inner input
+ * </script>
+ * ```
+ *
+ * Methods: `focus()`, `select()`, `clear()`. Restyle via `::part(field)`,
+ * `::part(input)`, `::part(label)`, `::part(hint)`.
+ */
+defineWebComponent<Props, Events>('kai-input', {
+  type: 'text',
+  value: undefined,
+  placeholder: undefined,
+  label: undefined,
+  hint: undefined,
+  error: undefined,
+  size: 'md',
+  disabled: undefined,
+  readonly: undefined,
+  required: undefined,
+  invalid: undefined,
+  name: undefined,
+  autocomplete: undefined,
+  inputmode: undefined,
+}, (props, ctx) => {
+  const { element, dispatch, flag, expose } = ctx;
+
+  // Lift the value into the facade and drive Input 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.
+  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 nullish so the reflect write-back equals the signal and
+  // the equality guards absorb it (no attr⇄prop feedback loop; mirrors kai-segmented).
+  const coerce = (v: unknown): string =>
+    v == null ? (element.getAttribute('value') ?? '') : String(v);
+
+  // Set the value WITHOUT firing an event (programmatic / reflect write-back).
+  const setQuiet = (next: string) => { if (untrack(value) !== next) setValue(next); };
+
+  // Override `value` so reads return LIVE state and host writes (`el.value = …`)
+  // drive it WITHOUT firing events — distinct from the typing path.
+  Object.defineProperty(element, 'value', {
+    get: () => value(),
+    set: (v: unknown) => setQuiet(coerce(v)),
+    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');
+    }
+  });
+
+  // `autocapitalize` is forwarded by reading the host attribute rather than as a
+  // declared prop: it is a global reflected HTMLElement IDL attribute (lowercase,
+  // like the reserved `lang`/`title`), so component-register's constructor
+  // `this.autocapitalize = undefined` would reflect an attribute and throw
+  // "must not have attributes". Seeded now; kept in sync by the observer in onMount.
+  const [autocapitalize, setAutocapitalize] = createSignal<string | undefined>(
+    element.getAttribute('autocapitalize') ?? undefined,
+  );
+
+  // Track which affix slots are filled; re-read on child mutations so late/streamed
+  // content lights up its affix. An empty slot is never passed to the primitive.
+  const [filled, setFilled] = createSignal<Record<SlotName, boolean>>({ leading: false, trailing: false });
+  onMount(() => {
+    const read = () => {
+      const next = {} as Record<SlotName, boolean>;
+      for (const name of SLOT_NAMES) next[name] = !!element.querySelector(`:scope > [slot="${name}"]`);
+      setFilled(next);
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, subtree: false });
+    onCleanup(() => observer.disconnect());
+
+    // Keep the forwarded `autocapitalize` in sync with the host attribute.
+    const syncAutocapitalize = () => setAutocapitalize(element.getAttribute('autocapitalize') ?? undefined);
+    syncAutocapitalize();
+    const attrObserver = new MutationObserver(syncAutocapitalize);
+    attrObserver.observe(element, { attributes: true, attributeFilter: ['autocapitalize'] });
+    onCleanup(() => attrObserver.disconnect());
+  });
+  const region = (name: SlotName) => (filled()[name] ? <slot name={name} /> : undefined);
+
+  const innerInput = () => element.shadowRoot?.querySelector<HTMLInputElement>('input') ?? null;
+
+  expose({
+    /** Focus the inner input (the host can't reach into the shadow root). */
+    focus: (options?: FocusOptions) => innerInput()?.focus(options),
+    /** Select the inner input's text. */
+    select: () => innerInput()?.select(),
+    /** Empty the value and fire `kai-change` with `''`. */
+    clear: () => { setValue(''); dispatch('kai-change', { value: '' }); },
+  });
+
+  return (
+    <>
+      <style>{':host{display:block}'}</style>
+      <Input
+        type={(props.type as string) ?? 'text'}
+        value={value()}
+        placeholder={props.placeholder as string | undefined}
+        label={props.label as string | undefined}
+        hint={props.hint as string | undefined}
+        error={props.error as string | undefined}
+        size={(props.size as 'sm' | 'md' | undefined) ?? 'md'}
+        invalid={flag('invalid')}
+        disabled={flag('disabled')}
+        readonly={flag('readonly')}
+        required={flag('required')}
+        name={props.name as string | undefined}
+        autocomplete={props.autocomplete as InputProps['autocomplete']}
+        inputmode={props.inputmode as InputProps['inputmode']}
+        autocapitalize={autocapitalize() as InputProps['autocapitalize']}
+        leading={region('leading')}
+        trailing={region('trailing')}
+        onValueInput={(v) => { setValue(v); dispatch('kai-input', { value: v }); }}
+        onValueChange={(v) => { setQuiet(v); dispatch('kai-change', { value: v }); }}
+      />
+    </>
+  );
+});

package/src/elements/kbd.tsx

@@ -0,0 +1,45 @@
+import { defineWebComponent } from './define';
+import { Kbd, type KbdPlatform } from '../ui/kbd';
+
+interface Props extends Record<string, unknown> {
+  /** Shortcut spec — tokens joined by `+` (e.g. `Mod+Shift+K`). Omit it to show
+   *  default-slot content instead. Display only; the element does not bind keys. */
+  keys?: string;
+  /** `mac` uses ⌘/⌥, `other` uses Ctrl. `auto` (default) sniffs the OS. */
+  platform?: KbdPlatform;
+  /** Cap size: `sm` or `md`. Defaults to `md`. */
+  size?: 'sm' | 'md';
+}
+
+/**
+ * `<kai-kbd>` — a keyboard-shortcut display. Feed it `keys` (tokens joined by
+ * `+`) and it renders one inset cap per token, mapping each to a platform glyph
+ * (`Mod` → ⌘ on mac else Ctrl, `Shift` → ⇧, `ArrowUp` → ↑, `Enter` → ⏎, …).
+ * Display only — it does not bind keys.
+ *
+ * ```html
+ * <kai-kbd keys="Mod+K"></kai-kbd>
+ * <kai-kbd keys="Mod+Shift+ArrowUp" platform="mac"></kai-kbd>
+ * <kai-kbd>Esc</kai-kbd> <!-- omit keys to show your own content -->
+ * ```
+ *
+ * `platform="auto"` (default) sniffs the OS for ⌘ vs Ctrl. Restyle the caps via
+ * `::part(key)` and the gaps via `::part(separator)`.
+ */
+defineWebComponent<Props>('kai-kbd', {
+  keys: undefined,
+  platform: 'auto',
+  size: 'md',
+}, (props) => (
+  <>
+    {/* Base sets `:host{display:block}`; a shortcut hint flows inline like a chip. */}
+    <style>{':host{display:inline-flex}'}</style>
+    <Kbd
+      keys={props.keys as string | undefined}
+      platform={(props.platform as KbdPlatform) ?? 'auto'}
+      size={(props.size as 'sm' | 'md') ?? 'md'}
+    >
+      <slot />
+    </Kbd>
+  </>
+));