@kitn.ai/ui 0.14.1

package/src/elements/file-tree.stories.tsx

@@ -0,0 +1,134 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { FileTreeFile } from '../components/file-tree';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-file-tree': JSX.HTMLAttributes<HTMLElement> & {
+        'active-file'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+const FILES: FileTreeFile[] = [
+  { path: 'index.html', type: 'html' },
+  { path: 'about.html', type: 'html' },
+  { path: 'css/site.css', type: 'other', language: 'css' },
+  { path: 'src/app.ts', type: 'other', language: 'ts' },
+  { path: 'src/lib/format.ts', type: 'other', language: 'ts' },
+  { path: 'src/lib/parse.ts', type: 'other', language: 'ts' },
+  { path: 'assets/logo.svg', type: 'image' },
+  { path: 'assets/report.pdf', type: 'pdf' },
+];
+
+/** A bordered, sized box the tree fills + scrolls within. */
+function Frame(props: { children: JSX.Element }) {
+  return (
+    <div
+      style={{
+        height: '320px',
+        width: '280px',
+        border: '1px solid var(--color-border, #e4e4e7)',
+        'border-radius': '10px',
+        overflow: 'hidden',
+      }}
+    >
+      {props.children}
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-file-tree style="display:block;height:320px"></kai-file-tree>
+
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+
+  const tree = document.querySelector('kai-file-tree');
+  // \`files\` is a JS property (array). Folders are derived from \`/\` in each path.
+  tree.files = [
+    { path: 'index.html', type: 'html' },
+    { path: 'src/app.ts', type: 'other' },
+    { path: 'src/lib/format.ts', type: 'other' },
+    { path: 'assets/logo.svg', type: 'image' },
+  ];
+  tree.setAttribute('active-file', 'src/app.ts');
+  tree.addEventListener('kai-select', (e) => console.log('selected', e.detail.path));
+</script>`;
+
+const meta = {
+  title: 'Components/FileTree',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-file-tree'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-file-tree', [
+        '`<kai-file-tree>` is the framework-agnostic **web component** for a collapsible, keyboard-navigable **file explorer** built from a flat list of `/`-delimited paths (nested folders are derived automatically). ARIA `tree`/`treeitem`. Isolated in **Shadow DOM**.',
+        '**When to use:** any time you need a file/folder tree — the Code tab of `<kai-artifact>` uses it, but it ships public so you can reuse it standalone (a project explorer, an attachments browser, a doc outline).',
+        "**How to use:** register once with `import '@kitn.ai/ui/elements'`, then set the `files` **property** (a JS array of `{ path, url?, code?, language?, type? }`). Folders come from the `/` in each `path`; `type` picks the icon. Set `active-file` to highlight a row, `default-expanded` to control which folders open. Listen for **`select`** (`detail.path`). Arrow keys navigate; Enter/Space selects or toggles.",
+        '**Anatomy:** a scrollable ARIA `tree` of **folder nodes** (collapsible `treeitem` groups, derived from `/`-delimited path segments) and **file leaf nodes** (selectable `treeitem` rows with a type icon; the `active-file` row is highlighted). Folders auto-expand on first render; click or arrow-key to collapse/expand.',
+        '**Placement:** a sidebar/explorer column — inside `<kai-artifact>`, a `<kai-resizable>` panel, or any file-picker surface. It **fills** its container, so give the parent (or the element) a height.',
+        'See the **Code** tab for HTML usage.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Interactive playground — click rows, use arrow keys / Enter to navigate. */
+export const Playground: Story = {
+  render: () => {
+    const [selected, setSelected] = createSignal('src/app.ts');
+    let el: HTMLElement & { files?: FileTreeFile[] };
+    onMount(() => {
+      if (!el) return;
+      el.files = FILES;
+      el.addEventListener('kai-select', (e) => {
+        const path = (e as CustomEvent).detail.path as string;
+        setSelected(path);
+        el.setAttribute('active-file', path);
+      });
+    });
+    return (
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <Frame>
+          <kai-file-tree
+            ref={(e) => (el = e as HTMLElement & { files?: FileTreeFile[] })}
+            active-file={selected()}
+          />
+        </Frame>
+        <span style={{ 'font-size': '13px', color: 'var(--color-muted-foreground, #71717a)' }}>
+          Selected: <code>{selected()}</code>
+        </span>
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A deeper, nested layout with mixed file types. */
+export const Nested: Story = {
+  render: () => {
+    let el: HTMLElement & { files?: FileTreeFile[] };
+    onMount(() => {
+      if (el) el.files = FILES;
+    });
+    return (
+      <Frame>
+        <kai-file-tree
+          ref={(e) => (el = e as HTMLElement & { files?: FileTreeFile[] })}
+          active-file="src/lib/format.ts"
+        />
+      </Frame>
+    );
+  },
+};

package/src/elements/file-tree.tsx

@@ -0,0 +1,52 @@
+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? }`). */
+  files: FileTreeFile[];
+  /** Selected file path — highlighted in the tree. */
+  activeFile?: string;
+  /** Folder paths expanded initially. Omit to start with all folders open. */
+  defaultExpanded?: string[];
+}
+
+interface Events extends Record<string, unknown> {
+  /** Fired when a file is selected. `detail.path` = the file's path. */
+  'kai-select': { path: string };
+}
+
+/**
+ * `<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.
+ */
+defineWebComponent<Props, Events>('kai-file-tree', {
+  files: [],
+  activeFile: undefined,
+  defaultExpanded: undefined,
+}, (props, { dispatch }) => (
+  <>
+    {/* 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
+        sibling portal-mount div can't steal a grid track). */}
+    <style>{':host{display:block;height:100%;min-height:0}'}</style>
+    <div
+      style={{
+        display: 'grid',
+        'grid-template-rows': 'minmax(0, 1fr)',
+        'grid-template-columns': 'minmax(0, 1fr)',
+        height: '100%',
+        'min-height': '0',
+      }}
+    >
+      <div class="overflow-auto scrollbar-thin py-1.5" style={{ 'min-height': '0' }}>
+        <FileTree
+          files={props.files}
+          activeFile={props.activeFile}
+          defaultExpanded={props.defaultExpanded}
+          onSelect={(path) => dispatch('kai-select', { path })}
+        />
+      </div>
+    </div>
+  </>
+));

package/src/elements/file-upload.stories.tsx

@@ -0,0 +1,82 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-file-upload': JSX.HTMLAttributes<HTMLElement> & {
+        multiple?: boolean | string;
+        accept?: string;
+        disabled?: boolean | string;
+        label?: string;
+        'on:kai-files-added'?: (e: CustomEvent<{ files: File[] }>) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-file-upload accept="image/*" label="Drop images here"></kai-file-upload>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  document.querySelector('kai-file-upload')
+    .addEventListener('kai-files-added', (e) =>
+      console.log(e.detail.files.map((f) => f.name)));
+</script>`;
+
+const meta = {
+  title: 'Components/FileUpload',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-file-upload'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-file-upload', [
+          '`<kai-file-upload>` is the framework-agnostic **web component** for a click / drag-and-drop file dropzone — isolated in **Shadow DOM**.',
+          '**When to use:** accepting file or image uploads in a non-Solid app. In SolidJS, compose the `FileUpload` primitives.',
+          '**Placement:** above or replacing the prompt input, or in a dedicated upload panel; fills its container width (set a `max-width` on the parent to constrain the dropzone).',
+          "**How to use:** register once with `import '@kitn.ai/ui/elements'`, set the `accept` / `multiple` / `label` attributes, and listen for the `kai-files-added` **CustomEvent** (`e.detail.files` is a `File[]`). The default dropzone label can be replaced with your own markup via the default `<slot>`.",
+          'See the **Code** tab for HTML usage.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A dropzone accepting any files. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kai-file-upload
+        on:kai-files-added={(e: CustomEvent<{ files: File[] }>) =>
+          console.log(e.detail.files.map((f) => f.name))}
+      />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Restricted to images, single file, with a custom label. */
+export const ImagesOnly: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kai-file-upload accept="image/*" multiple={false} label="Click or drop an image" />
+    </div>
+  ),
+};
+
+/** A disabled dropzone (non-interactive). */
+export const Disabled: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'max-width': '480px' }}>
+      <kai-file-upload disabled label="Uploads are disabled" />
+    </div>
+  ),
+};

package/src/elements/file-upload.tsx

@@ -0,0 +1,44 @@
+import { defineWebComponent } from './define';
+import { FileUpload, FileUploadTrigger } from '../components/file-upload';
+import { Upload } from 'lucide-solid';
+
+interface Props extends Record<string, unknown> {
+  /** Allow selecting multiple files (default true). */
+  multiple?: boolean;
+  /** `accept` attribute for the file picker (e.g. `image/*`). */
+  accept?: string;
+  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  disabled?: boolean;
+  /** Default dropzone label (overridable via the default slot). */
+  label?: string;
+}
+
+/** Events fired by `<kai-file-upload>`. */
+interface Events {
+  /** Files were picked or dropped. */
+  'kai-files-added': { files: File[] };
+}
+
+/**
+ * `<kai-file-upload>` — a click/drag-drop dropzone. Emits `filesadded`. The
+ * default dropzone label can be replaced with your own markup via the default
+ * `<slot>` (a "Route 2" custom-content slot).
+ */
+defineWebComponent<Props, Events>('kai-file-upload', {
+  multiple: true,
+  accept: undefined,
+  disabled: false,
+  label: 'Click or drop files to upload',
+}, (props, { dispatch, flag }) => (
+  <FileUpload
+    multiple={flag('multiple')}
+    accept={props.accept}
+    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">
+      <Upload class="size-5" />
+      <slot>{props.label}</slot>
+    </FileUploadTrigger>
+  </FileUpload>
+));

package/src/elements/form.stories.tsx

@@ -0,0 +1,248 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal, onMount, type JSX } from 'solid-js';
+import './form';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+import type { FormDefinition } from '../components/form';
+import type { CardEvent } from '../primitives/card-contract';
+
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-form': JSX.HTMLAttributes<HTMLElement> & {
+        heading?: string;
+        'card-id'?: string;
+        ref?: (el: HTMLElement) => void;
+      };
+    }
+  }
+}
+
+type FormEl = HTMLElement & { data?: FormDefinition; resolution?: Record<string, unknown> };
+
+/** A bordered box the form sits inside. */
+function Frame(props: { children: JSX.Element }) {
+  return <div style={{ 'max-width': '460px' }}>{props.children}</div>;
+}
+
+/** Mounts a <kai-form>, sets `.data`, logs the emitted CardEvent under the render. */
+function FormDemo(props: { def: FormDefinition; cardId: string }) {
+  const [log, setLog] = createSignal<CardEvent[]>([]);
+  let el: FormEl | undefined;
+  onMount(() => {
+    if (!el) return;
+    el.data = props.def;
+    el.addEventListener('kai-card', (e) => {
+      const detail = (e as CustomEvent<CardEvent>).detail;
+      setLog((prev) => [...prev, detail]);
+    });
+  });
+  return (
+    <Frame>
+      <div style={{ display: 'flex', 'flex-direction': 'column', gap: '12px' }}>
+        <kai-form ref={(e) => (el = e as FormEl)} card-id={props.cardId} />
+        <pre
+          style={{
+            margin: 0,
+            'max-height': '180px',
+            overflow: 'auto',
+            background: 'var(--color-muted, #f4f4f5)',
+            'border-radius': '8px',
+            padding: '8px',
+            'font-size': '12px',
+          }}
+        >
+          {log().length === 0 ? '// emitted CardEvents appear here' : JSON.stringify(log(), null, 2)}
+        </pre>
+      </div>
+    </Frame>
+  );
+}
+
+const FEEDBACK: FormDefinition = {
+  type: 'object',
+  title: 'How did we do?',
+  description: 'Two quick questions.',
+  required: ['rating', 'contactOk'],
+  'x-kai-order': ['rating', 'comments', 'plan', 'contactOk'],
+  'x-kai-submitLabel': 'Send feedback',
+  'x-kai-actions': [{ id: 'skip', label: 'Skip', variant: 'ghost' }],
+  properties: {
+    rating: { type: 'integer', title: 'Overall rating', minimum: 1, maximum: 5, 'x-kai-widget': 'rating' },
+    comments: {
+      type: 'string',
+      title: 'Comments',
+      maxLength: 500,
+      'x-kai-widget': 'textarea',
+      'x-kai-placeholder': "What worked, what didn't…",
+    },
+    plan: { type: 'string', title: 'Your plan', enum: ['free', 'pro', 'team'], default: 'free' },
+    contactOk: { type: 'boolean', title: 'OK to contact me about this', default: false },
+  },
+};
+
+const ALL_WIDGETS: FormDefinition = {
+  type: 'object',
+  title: 'Every widget',
+  'x-kai-submitLabel': 'Submit all',
+  properties: {
+    name: { type: 'string', title: 'Name' },
+    bio: { type: 'string', title: 'Bio', maxLength: 300 },
+    email: { type: 'string', title: 'Email', format: 'email' },
+    website: { type: 'string', title: 'Website', format: 'uri' },
+    birthday: { type: 'string', title: 'Birthday', format: 'date' },
+    secret: { type: 'string', title: 'Password', 'x-kai-widget': 'password' },
+    size: { type: 'string', title: 'Size', enum: ['S', 'M', 'L'] },
+    country: { type: 'string', title: 'Country', enum: ['US', 'UK', 'DE', 'FR', 'JP'] },
+    age: { type: 'integer', title: 'Age', minimum: 0, maximum: 120 },
+    volume: { type: 'integer', title: 'Volume', minimum: 0, maximum: 11, 'x-kai-widget': 'slider' },
+    stars: { type: 'integer', title: 'Stars', minimum: 1, maximum: 5, 'x-kai-widget': 'rating' },
+    notify: { type: 'boolean', title: 'Email me updates' },
+    agree: { type: 'boolean', title: 'I agree', 'x-kai-widget': 'checkbox' },
+    tags: { type: 'array', title: 'Tags', items: { type: 'string' } },
+    topics: { type: 'array', title: 'Topics', items: { enum: ['news', 'sports', 'tech'] } },
+    contacts: {
+      type: 'array',
+      title: 'Contacts',
+      items: {
+        type: 'object',
+        properties: { label: { type: 'string', title: 'Label' }, phone: { type: 'string', title: 'Phone' } },
+      },
+    },
+    address: {
+      type: 'object',
+      title: 'Address',
+      properties: { street: { type: 'string', title: 'Street' }, city: { type: 'string', title: 'City' } },
+    },
+  },
+};
+
+const VALIDATION: FormDefinition = {
+  type: 'object',
+  title: 'Create account',
+  required: ['username', 'email', 'age'],
+  properties: {
+    username: { type: 'string', title: 'Username', minLength: 3, maxLength: 12 },
+    email: { type: 'string', title: 'Email', format: 'email' },
+    age: { type: 'integer', title: 'Age', minimum: 13, maximum: 120 },
+  },
+};
+
+const HTML_SNIPPET = (def: FormDefinition) => `<kai-form></kai-form>
+<script type="module">
+  import '@kitn.ai/ui/elements'; // registers the custom elements
+
+  const form = document.querySelector('kai-form');
+  // \`data\` is the CardEnvelope.data — a JSON Schema + x-kai-* UI hints (set as a property).
+  form.data = ${JSON.stringify(def, null, 2)};
+
+  // Cards bubble ONE \`kai-card\` CustomEvent carrying a typed CardEvent.
+  form.addEventListener('kai-card', (e) => {
+    const ev = e.detail; // { kind:'submit', cardId, data } | { kind:'action', ... } | ...
+    if (ev.kind === 'submit') console.log('submission', ev.data);
+  });
+</script>`;
+
+const meta = {
+  title: 'Generative UI/Cards/kai-form',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-form'),
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: specDescription('kai-form', [
+        '`<kai-form>` turns an agent\'s **JSON Schema** "shape" (set via the `data` **property**) into a themed, accessible, validated form inside `<kai-card>` chrome. A valid submission is emitted **up the Card contract** as a bubbling **`kai-card`** CustomEvent of `{ kind: \'submit\', cardId, data }`.',
+        '**Anatomy:** `<kai-card>` chrome (optional heading from `data.title` or `heading` attr) → **field rows** (one per schema property in `x-kai-order` / key order: label + widget; `object` properties become a `<fieldset>`, `array` items become a repeater/checkbox-group/tag-list) → **card footer** (`x-kai-submitLabel` submit `<Button>` + optional `x-kai-actions` secondary buttons; replaced by a read-only `<dl>` summary after a resolved submission).',
+        '**The mapping is deterministic:** `string`→text, `string`+`enum`→radio/select, `string`+`format`→typed inputs, `number`/`integer`→number (or `slider`/`rating` via `x-kai-widget`), `boolean`→switch, `array`→checkbox-group / multi-select / repeater / tag-list, nested `object`→fieldset. `x-kai-*` hints (`x-kai-widget`, `x-kai-order`, `x-kai-submitLabel`, `x-kai-actions`, `x-kai-dismissible`, …) refine the UI and live **inside** the schema, so one source of truth drives both the form and validation.',
+        "**Events** (all frozen Card-contract verbs): `ready` on mount, `submit` on a valid submit, `action` for secondary buttons (`x-kai-actions`), `dismiss` when dismissible, `error` for a malformed definition (renders the inline `kai-card` error). It **never invents events**.",
+        '**The same `CardEnvelope`/`CardEvent` shapes flow over the remote iframe transport unchanged** — this is the *native* card. See the **Code** tab for the full envelope JSON + the HTML wiring.',
+      ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The worked example: a rating + textarea + enum radio + switch, with a Skip action. */
+export const Feedback: Story = {
+  render: () => <FormDemo def={FEEDBACK} cardId="card-feedback-7f3" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(FEEDBACK), language: 'html' } } },
+};
+
+/** One form exercising every row of the mapping table. */
+export const AllWidgets: Story = {
+  render: () => <FormDemo def={ALL_WIDGETS} cardId="card-all" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(ALL_WIDGETS), language: 'html' } } },
+};
+
+/** Required + min/max + format: try submitting empty (inline errors), then fill it in. */
+export const Validation: Story = {
+  render: () => <FormDemo def={VALIDATION} cardId="card-signup" />,
+  parameters: { docs: { source: { code: HTML_SNIPPET(VALIDATION), language: 'html' } } },
+};
+
+const RESOLVED_FORM: FormDefinition = {
+  type: 'object',
+  title: 'Book a demo',
+  'x-kai-order': ['name', 'optIn'],
+  properties: {
+    name: { type: 'string', title: 'Full name' },
+    optIn: { type: 'boolean', title: 'Email me' },
+  },
+};
+
+/** The form after a valid submission — read-only `<dl>` summary + "✓ Submitted", no inputs. */
+export const Resolved: Story = {
+  name: 'Resolved (read-only)',
+  render: () => {
+    let el: FormEl | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.data = RESOLVED_FORM;
+      el.resolution = { kind: 'submit', data: { name: 'Jane Cooper', optIn: true } };
+    });
+    return (
+      <Frame>
+        <kai-form ref={(e) => (el = e as FormEl)} card-id="card-resolved-form" />
+      </Frame>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `<kai-form></kai-form>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const form = document.querySelector('kai-form');
+  form.data = ${JSON.stringify(RESOLVED_FORM, null, 2)};
+  // Setting .resolution renders the chromed read-only summary — no inputs or submit button.
+  form.resolution = { kind: 'submit', data: { name: 'Jane Cooper', optIn: true } };
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};
+
+/** A malformed `data` → the inline error state + an `error` event (no form rendered). */
+export const InvalidEnvelope: Story = {
+  render: () => <FormDemo def={{ type: 'array' } as unknown as FormDefinition} cardId="card-bad" />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<kai-form></kai-form>
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const form = document.querySelector('kai-form');
+  // A definition that isn't a JSON-Schema object → inline error + an \`error\` event.
+  form.data = { type: 'array' };
+  form.addEventListener('kai-card', (e) => {
+    if (e.detail.kind === 'error') console.warn('form error:', e.detail.message);
+  });
+</script>`,
+        language: 'html',
+      },
+    },
+  },
+};

package/src/elements/form.tsx

@@ -0,0 +1,43 @@
+import { defineWebComponent } from './define';
+import { Form, type FormDefinition } from '../components/form';
+import type { CardResolution } from '../primitives/card-contract';
+
+interface Props extends Record<string, unknown> {
+  /** The form definition — a JSON Schema (`type:'object'`) + `x-kai-*` UI hints
+   *  (the CardEnvelope.data). Set as a JS PROPERTY: `el.data = { type:'object',
+   *  properties:{…} }`. Import the `FormDefinition` type from `@kitn.ai/ui` for
+   *  the full shape (it is self-referential, so the element types it loosely). */
+  data?: Record<string, unknown>;
+  /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
+  cardId?: string;
+  /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
+  heading?: string;
+  /** Set when the user resolved this card; renders the read-only view. Property:
+   *  `el.resolution = { kind:'submit', data:{…} }`. */
+  resolution?: Record<string, unknown>;
+}
+
+/**
+ * `<kai-form>` — renders a JSON-Schema **form definition** (set via the `data`
+ * property) into themed, accessible widgets inside `<kai-card>` chrome, validates
+ * input client-side, and emits the collected, coerced, validated object up the
+ * Card contract as a bubbling **`kai-card`** CustomEvent of `{ kind:'submit' }`.
+ * It also emits `ready` on mount, `action`/`dismiss` for secondary affordances, and
+ * `error` for a malformed definition. Routes through a `CardProvider` when present,
+ * 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', {
+  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}
+  />
+));