@kitn.ai/ui 0.26.0 → 0.27.0

package/src/elements/styles.css

@@ -1,5 +1,18 @@
-/* Element-bundle stylesheet. Compiled to compiled.css and injected into each
-   custom element's shadow root. Mirrors .storybook/styles.css but scans src/. */
+/* Element-bundle stylesheet, and the SOURCE OF TRUTH for element CSS. Compiled to
+   compiled.css and injected into each custom element's shadow root;
+   .storybook/styles.css @imports this file rather than restating it, so a rule
+   added here reaches the shadow roots AND the light-DOM Solid stories at once.
+
+   It used to be the other way round — Storybook hand-copied a few of these rules
+   under "Mirror the shipped ..." comments. Nothing enforced the copy, so
+   .kai-radio, .kai-checkbox, .kai-range and .kai-focus-inset were simply missing
+   there: three form controls rendered as raw OS chrome in every story while the
+   shipped element rendered them fully designed, and an agent and the owner each
+   concluded the kit had unstyled controls. Never copy a rule from here into the
+   Storybook sheet; add it here.
+
+   The one thing that cannot cross is :host, which selects nothing in the light
+   DOM. Its defaults are re-stated on `body` in the Storybook sheet's shim. */
 @import "tailwindcss";
 /* tw-animate-css supplies the animate-in/animate-out + slide/fade/zoom utilities
    the kit uses for every overlay enter/exit (toast, popover, tooltip, dropdown,
@@ -16,10 +29,19 @@
   /* Base typography is token-driven so a theme can restyle it. --kai-font-base is
      the family for ALL text/UI (named "base", not "sans", so a serif body works);
      --kai-tracking is global letter-spacing. Both pierce the Shadow DOM via the
-     var() fallback, exactly like the --kai-color-* tokens. */
+     var() fallback, exactly like the --kai-color-* tokens.
+
+     font-size is the third: without it every shadow root inherited the DOCUMENT's
+     size (16px in a stock page), so any surface that never set an explicit text-*
+     class rendered a step larger than the rest of the kit and looked like a bug in
+     that one component. --text-body is the scale's primary reading size and itself
+     resolves through --kai-text-body, so overriding that one token still moves the
+     default. The literal fallback matches theme.css's --text-body so the rule is
+     still correct if this sheet is ever used without the @theme block. */
   :host {
     display: block;
     font-family: var(--kai-font-base, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);
+    font-size: var(--text-body, var(--kai-text-body, 0.875rem));
     letter-spacing: var(--kai-tracking, normal);
   }
   /* Code/monospace surfaces use --kai-font-code (named for its ROLE — code — not
@@ -83,6 +105,40 @@
   *::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
   *::-webkit-scrollbar-corner { background: transparent; }
 
+  /* SELECTED text, kit-owned. Scoped to the shadow root — deliberately, and this
+     is the whole design decision, so read it before "simplifying" it into
+     theme.css.
+
+     WHY THE KIT OWNS IT AT ALL: left to the UA, the browser's blue selection was
+     visually stronger than the kit's OWN deliberate emphasis (the composer's
+     --color-highlight mark), so an incidental drag-select outranked a keyword the
+     app had flagged on purpose. How selected text reads is a fact about the
+     medium, which is the kit's call.
+
+     WHY ONLY HERE, AND NOT IN theme.css: theme.css is imported into a CONSUMER's
+     Tailwind build, so a bare ::selection there would restyle every paragraph on
+     their page — the kit deciding for the app's own content, which is not ours to
+     decide. The shadow root IS the kit's DOM, so the same rule is unambiguous
+     here. Identical reasoning to the scrollbar and :focus-visible rules above,
+     which are scoped the same way and for the same reason. theme.css therefore
+     carries the TOKENS only, and a Solid-layer consumer rendering our components
+     into their own light DOM opts in with one rule of their own:
+     `.my-chat ::selection { background-color: var(--color-selection); … }`.
+
+     WHY THE RULE MUST BE IN THIS SHEET AND NOT INHERITED: ::selection does NOT
+     cross the shadow boundary the way ordinary inherited properties do — a
+     document-level ::selection leaves shadow content on the UA default. The
+     --kai-color-selection TOKEN does pierce (custom properties inherit normally),
+     which is what keeps a consumer override working.
+
+     Both background AND color are set; see the theme.css note for why the
+     foreground is load-bearing rather than cosmetic (coloured text falls under
+     WCAG AA on this fill if it keeps its own colour). */
+  ::selection {
+    background-color: var(--color-selection);
+    color: var(--color-selection-foreground);
+  }
+
   /* Respect a user's reduced-motion preference: disable the tw-animate-css
      enter/exit keyframe animations (toasts, overlays, cards) so they appear and
      disappear instantly instead of sliding/fading. Targets the utility classes
@@ -169,6 +225,36 @@
   .kai-checkbox:checked {
     box-shadow: 0 1px 4px color-mix(in srgb, var(--color-primary) 26%, transparent);
   }
+  /* The mixed state ("some of the children below are ticked"). `indeterminate` is a
+     DOM property with no HTML attribute, so a rule is the ONLY way it can be seen —
+     without one a mixed box paints pixel-identically to an unchecked one and lies
+     about its state. That was live: `<kai-tasks>` in `select` mode puts an
+     indeterminate select-all above a partial selection, and it read as "none
+     selected".
+
+     Same fill and the same masked `::after` as `:checked`, with the tick mask
+     swapped for a bar, so the two states are siblings of one technique rather than
+     two: the bar is `--color-primary-foreground` on `--color-primary`, exactly the
+     pair the tick already uses, so it themes and contrasts identically in both
+     themes and stays consumer-themable through the same tokens.
+
+     Ordered AFTER the `:checked` rules on purpose. `indeterminate` is independent of
+     `checked`, so a box can be both; specificity is equal, so source order decides,
+     and mixed-wins is what the browser's own native rendering does.
+
+     Scoped to `.kai-checkbox` on purpose: `:indeterminate` also matches every radio
+     in a group with nothing selected, and an empty radio group must go on reading as
+     empty rather than sprouting a third state. */
+  .kai-checkbox:indeterminate {
+    background-color: var(--color-primary);
+    border-color: var(--color-primary);
+    box-shadow: 0 1px 4px color-mix(in srgb, var(--color-primary) 26%, transparent);
+  }
+  .kai-checkbox:indeterminate::after {
+    transform: scale(1);
+    -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14'/%3E%3C/svg%3E") center / contain no-repeat;
+    mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23000' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M5 12h14'/%3E%3C/svg%3E") center / contain no-repeat;
+  }
   .kai-radio:disabled,
   .kai-checkbox:disabled { opacity: 0.5; cursor: not-allowed; }
 

package/src/elements/thread.tsx

@@ -128,6 +128,8 @@ defineWebComponent<Props, Events>('kai-thread', {
         scrollButton={props.scrollButton !== false}
         cardTypes={cardComponentsFromTags(props.cardTypes as Record<string, string> | undefined, (props as { theme?: string }).theme)}
         cardSchemas={props.cardSchemas as Record<string, object> | undefined}
+        /* F-26: card parts emit off THIS element as the bubbling `kai-card` event. */
+        cardHostElement={element}
         empty={slots()['empty'] ? <slot name="empty" /> : undefined}
         onMessageAction={(detail) => dispatch('kai-message-action', detail)}
         controllerRef={(c) => (controller = c)}

package/src/elements/toast.tsx

@@ -5,7 +5,11 @@ import { toast as toastStore, type ToastItem } from '../primitives/toast-store';
 interface Props extends Record<string, unknown> {
   /** The toasts to render. Newest is shown on top. Set as a JS property (array);
    *  pass a new array reference to update. Omit for an empty region, which is
-   *  the normal resting state and how the imperative `toast()` API starts. */
+   *  the normal resting state and how the imperative `toast()` API starts.
+   *  Note the handover: the first `toast()` call ADOPTS a region you placed in
+   *  markup (no second region mounts) and binds the imperative store to this
+   *  property, replacing any array you set. Drive a region as data OR via
+   *  `toast()`, not both at once. */
   toasts?: ToastItem[];
   /** Stack anchor: `'top-center'` (default), `'top-right'`, `'bottom-center'`, … */
   position?: ToastPosition;
@@ -41,6 +45,15 @@ interface Events {
  * also usable declaratively — set `el.toasts = [...]` (a JS property, never an
  * attribute) and listen for `kai-dismiss` / `kai-action`.
  *
+ * The two modes meet gracefully: `toast()` ADOPTS the first connected
+ * `<kai-toast-region>` already in the document instead of mounting a second
+ * one, and creates its own on `document.body` only when none exists. Adoption
+ * keeps your authored attributes (position/stack/appearance) but binds the
+ * imperative store to `toasts`, replacing an array you were driving as data —
+ * so within one app, either own the array or call `toast()`, not both. With
+ * two or more regions placed, the first in document order is adopted and a
+ * one-time console.warn flags the ambiguity.
+ *
  * Because it is a real `kai-*` element it carries its own shadow root + the
  * shared kit stylesheet, so it is viewport-positioned AND kit-styled.
  *

package/src/index.ts

@@ -419,7 +419,8 @@ export type { KaiTabItem } from './ui/tabs';
 export type { PaneStatus } from './ui/pane';
 export type { PaneTab } from './ui/pane-group';
 export type {
-  KaiCommandItem, KaiContextUsage, KaiMenuItem, KaiSegmentedOption, KaiSourceItem,
+  KaiCheckboxOption, KaiCommandItem, KaiContextUsage, KaiMenuItem, KaiRadioOption, KaiSegmentedOption, KaiSelectOption,
+  KaiSourceItem,
 } from './elements/element-data-types';
 // `kai-audio-visualizer.shader` takes a ShaderSpec. The element arrived from main
 // after this block was written, and prop-types-exported.test.ts caught it, which

package/src/primitives/card-data-types.ts

@@ -207,6 +207,55 @@ export type FormField = {
     | 'switch';
   'x-kai-placeholder'?: string;
   'x-kai-step'?: number;
+  /**
+   * Display format for a string field. `tel` / `ssn` / `credit-card`
+   * apply that type's standard mask and submit digits only; `custom` masks with
+   * `x-kai-mask` and submits the formatted value.
+   *
+   * NOT the JSON Schema `format` keyword, and deliberately not an extension of it:
+   * `format` has a registered vocabulary with assertion semantics, `widgetFor()`
+   * already switches on it to pick a widget, and `toJsonSchema()` turns it into a
+   * validation pattern. This is a UI hint, so it lives in the `x-kai-*` namespace
+   * with the other UI hints — and it selects FORMATTING, never a widget.
+   *
+   * Typed as the semantic-type union for a consumer authoring a form definition by
+   * hand. A value arriving from a MODEL is untrusted and may be anything at all;
+   * `resolveFieldMask()` degrades an unrecognised one to an unmasked text field with
+   * a console warning rather than trusting this declaration.
+   *
+   * SPELLED OUT HERE RATHER THAN IMPORTED, and that is not laziness. `FieldSemanticType`
+   * is declared in `./field-semantics`, which carries the semantics TABLE and its
+   * `console.warn` — and this file's whole reason for existing is that a Node/no-DOM
+   * backend can name a card payload with `lib: ["ESNext"]` and `types: []`, where
+   * `console` does not exist (measured: TS2584, by
+   * `tests/schemas/card-data-types-node-safe.test.ts`, which is what caught the import).
+   * A type import still has to RESOLVE, so importing the union would drag the engine into
+   * the server-safe entry's graph.
+   *
+   * AN APP CANNOT PIN THIS ON THE MODEL TODAY.
+   * `cardTools({ require })` narrows a projected tool schema by dot-path, but there is
+   * no path that reaches a form FIELD: a form card's payload is itself a JSON Schema, so
+   * `form.schema.json` describes `properties` as a map of field definitions rather than
+   * as a node per field, and `require: { form: [{ path: 'properties.ticketId' }] }` is a
+   * TypeError naming a path that does not resolve. "Force the model to mask the ticket
+   * field" is therefore not expressible; the enum above is what makes it LIKELY, and an
+   * app that needs a guarantee validates the arriving envelope itself.
+   *
+   * It is therefore a REGISTERED COPY of `FIELD_SEMANTIC_TYPES`: the two are pinned
+   * mutually assignable at compile time in
+   * `tests/components/form-field-formats.test.tsx`, so adding a fifth token to the enum
+   * without adding it here fails `nx typecheck ui` rather than shipping a form card that
+   * cannot name it.
+   */
+  'x-kai-format'?: 'tel' | 'ssn' | 'credit-card' | 'custom';
+  /** The mask pattern, read only when `x-kai-format` is `custom`: `#` a digit, `@` an
+   *  alphanumeric, `*` an obscurable alphanumeric, everything else a literal
+   *  (`CHG-####`). Capped at the mask engine's own limit; a longer one is refused. */
+  'x-kai-mask'?: string;
+  /** Placeholder text for the mask's unfilled positions, aligned character for
+   *  character with the pattern (`mm/dd/yyyy`). Derived from the pattern when absent;
+   *  a misaligned one is dropped, loudly, and the mask survives. */
+  'x-kai-mask-guide'?: string;
 };
 
 /** The form definition = CardEnvelope.data for type:'form'. */

package/src/primitives/card-host.tsx

@@ -1,8 +1,10 @@
 // src/primitives/card-host.tsx
 // The native transport: a Solid context exposing a CardHost (context() + emit()).
 // emit() routes through the contract policy via the shared routeCardEvent. Cards
-// inside <kai-chat>/<CardProvider> use this; bare cards fall back to the bubbling
-// kai-card event (see card-routing.listenForCardEvents).
+// inside a <CardProvider> use this; cards inside <kai-chat>/<kai-message>/
+// <kai-thread> (and bare cards given a hostElement) fall back to the bubbling
+// kai-card event off the host element (see card-routing.listenForCardEvents and
+// CardRenderer's hostElement prop).
 import { createContext, useContext, type JSX } from 'solid-js';
 import type { CardContext, CardEvent, CardHost, CardPolicy } from './card-contract';
 import { routeCardEvent } from './card-routing';

package/src/primitives/card-routing.ts

@@ -3,6 +3,13 @@
 // policy router (used by BOTH the native listener and the remote transport), and a
 // host-side listener helper for the bare-element path.
 import type { CardEvent, CardPolicy } from './card-contract';
+// isSafeUrl/isScriptUrl live in their own DOM-free file so schema.ts
+// (agent-tooling/construct, checked under tsconfig.mcp.json's Node-only pass)
+// can import isSafeUrl without dragging this file's HTMLElement/window/
+// CustomEvent references into a no-DOM-lib compile. Re-exported here so this
+// module's own public surface is unchanged.
+import { isSafeUrl, isScriptUrl } from './url-scheme-policy';
+export { isSafeUrl, isScriptUrl } from './url-scheme-policy';
 
 /** The single contract event name. */
 export const CARD_EVENT_NAME = 'kai-card';
@@ -16,62 +23,6 @@ export function emitCardEvent(element: HTMLElement, event: CardEvent): void {
   );
 }
 
-const SAFE_SCHEMES = ['http:', 'https:', 'mailto:'];
-const SCRIPT_SCHEMES = ['javascript:', 'vbscript:'];
-
-/** The scheme the WHATWG parser reads out of `url`, resolved against a base so a
- *  relative input inherits `http:`. `undefined` when it will not parse at all.
- *
- *  ONE parser for the two questions below, deliberately: the parsing is where
- *  the subtlety lives (it strips embedded tabs/newlines and trims surrounding
- *  whitespace before reading the scheme, so `java\nscript:` and
- *  `  javascript:...  ` are both read as `javascript:` -- which a regex over the
- *  raw string would miss). Two predicates over one parse cannot drift on that;
- *  two hand-rolled parsers would. */
-function schemeOf(url: string): string | undefined {
-  try { return new URL(url, 'http://_invalid_base').protocol; } catch { return undefined; }
-}
-
-/** True when `url` is safe to put in an href / hand to `window.open`.
- *
- *  Exported so the MARKDOWN renderer and the ARTIFACT viewer reuse this exact
- *  guard rather than growing a second scheme list that can drift from this one.
- *
- *  Resolving against a base is deliberate and is what makes it correct for
- *  markdown: a relative or fragment link (`/docs`, `#section`, `./rel`) is
- *  ordinary markdown, and resolving it inherits the base's `http:` so it
- *  passes, while `javascript:`/`data:`/`vbscript:` keep their own protocol and
- *  fail. It is correct for the artifact viewer for the same reason: a file with
- *  no `src` to resolve against yields a bare relative path (`docs/report.pdf`),
- *  which is a legitimate artifact address. Contrast `isRenderableLink` in
- *  `primitives/link-preview.ts`, which takes NO base and so demands an absolute
- *  http(s) URL: that is the right guard for a model-supplied citation -- a
- *  reference to a page on the public web -- this one for markdown body links and
- *  artifact file addresses. */
-export function isSafeUrl(url: string): boolean {
-  const scheme = schemeOf(url);
-  return scheme !== undefined && SAFE_SCHEMES.includes(scheme);
-}
-
-/** True when navigating to `url` would EXECUTE it as script in the initiating
- *  document's origin.
- *
- *  Strictly narrower than `!isSafeUrl(url)`, and not a competing policy: it
- *  answers a different question, for the one sink where the allowlist is the
- *  wrong tool. An `<iframe src>` legitimately takes `data:` and `blob:` (a
- *  `data:` blob artifact is a documented `<kai-artifact>` use -- it is what
- *  `displayUrl` exists for) and both get an OPAQUE origin in every modern
- *  browser, so neither can reach the host page. `javascript:`/`vbscript:` are
- *  the schemes that run in the EMBEDDER's origin, and they are the whole risk:
- *  the default sandbox (no `allow-same-origin`) already makes the browser refuse
- *  them, but a consumer who sets `allow-same-origin` turns a model-supplied
- *  `src` into host-origin script execution. The artifact viewer used to suggest
- *  that setting for "an artifact you trust"; it no longer does, and this guard
- *  is what protects the consumers who took the old advice. */
-export function isScriptUrl(url: string): boolean {
-  const scheme = schemeOf(url);
-  return scheme !== undefined && SCRIPT_SCHEMES.includes(scheme);
-}
 function warnNoHandler(kind: string): void {
   // eslint-disable-next-line no-console
   console.warn(`[kai-card] no policy handler for "${kind}"`);

package/src/primitives/card-schemas/form.schema.json

@@ -11,7 +11,27 @@
     "description": { "type": "string" },
     "required": { "type": "array", "items": { "type": "string" } },
     "properties": {
-      "type": "object"
+      "type": "object",
+      "description": "The fields to collect, keyed by property name. Each value is a JSON Schema field definition (type, title, description, enum, minimum/maximum, minLength/maxLength, pattern, items) plus optional x-kai-* UI hints. Only the display-format hints are spelled out below; the rest of a field definition is ordinary JSON Schema.",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "x-kai-format": {
+            "description": "Display format for a string field. `tel`, `ssn` and `credit-card` apply that type's standard mask and submit digits only; `custom` masks with `x-kai-mask` and submits the formatted value. Omit it for a plain text field.",
+            "enum": ["tel", "ssn", "credit-card", "custom"]
+          },
+          "x-kai-mask": {
+            "description": "The mask pattern, used only with `x-kai-format: \"custom\"`: `#` one digit, `@` one letter or digit, `*` one letter or digit that may be obscured; every other character is a literal shown as typed, e.g. `CHG-####`.",
+            "type": "string",
+            "maxLength": 64
+          },
+          "x-kai-mask-guide": {
+            "description": "Placeholder text shown at the unfilled positions of the mask, aligned character for character with the pattern (`mm/dd/yyyy` for `##/##/####`). Derived from the pattern when omitted.",
+            "type": "string",
+            "maxLength": 64
+          }
+        }
+      }
     },
     "x-kai-order": { "type": "array", "items": { "type": "string" } },
     "x-kai-inlineMax": { "type": "integer", "minimum": 1 },

package/src/primitives/card-validate.ts

@@ -6,8 +6,16 @@
 export interface JsonSchema {
   type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
   const?: unknown;
-  enum?: unknown[];
-  required?: string[];
+  // `readonly`: a construct's card schema is emitted `as const` (codegen.ts,
+  // emitCardsRegistry) so its literal types survive into CardTools' input —
+  // that turns array-valued fields into readonly tuples, which a mutable
+  // `T[]` does not structurally accept even under a `Readonly<Record<...>>`
+  // wrapper. JsonSchema is read-only data everywhere it is consumed (no
+  // caller mutates `.required`/`.enum` in place — see the callers in
+  // tool-defs.ts and form.tsx, which all build a fresh array via spread/
+  // filter/Set before assigning), so widening these two costs nothing.
+  enum?: readonly unknown[];
+  required?: readonly string[];
   properties?: Record<string, JsonSchema>;
   items?: JsonSchema;
   minimum?: number; maximum?: number;

package/src/primitives/chat-config.tsx

@@ -55,22 +55,49 @@ export function useChatConfig(): ChatConfigValue {
   return useContext(ChatConfigContext)!;
 }
 
-/** Maps prose size to Tailwind prose class */
+/**
+ * Maps prose size to the Tailwind Typography *size modifier* for consumers who
+ * render their own `prose` block.
+ *
+ * The `prose-*` names are deliberately NOT re-pointed at the --kai-text-* scale.
+ * They are not font sizes: each is a plugin-generated bundle of proportional
+ * margins, list indents, heading ratios and line-heights for every nested
+ * element, keyed to hardcoded rems, and they only do anything alongside `prose`
+ * itself. There is no `prose-body` to alias them to, and collapsing them to a
+ * bare font-size would throw away the vertical rhythm that is their whole job.
+ * The kit's own markdown does not go through them at all — it renders through
+ * `.chat-markdown` (theme.css), which is em-relative and therefore already
+ * scales off whatever `textClass` sets.
+ *
+ * The one raw font-size here (`xs`) DOES join the semantic scale, so it stays in
+ * step with `textClass('xs')`.
+ */
 export function proseClass(size: ProseSize): string {
   switch (size) {
-    case 'xs': return 'prose-sm text-xs';
+    case 'xs': return 'prose-sm text-meta';
     case 'sm': return 'prose-sm';
     case 'base': return '';
     case 'lg': return 'prose-lg';
   }
 }
 
-/** Maps prose size to a text class for non-prose elements (sidebar, input) */
+/**
+ * Maps prose size to a text class for message content, markdown, and non-prose
+ * chrome (sidebar, input).
+ *
+ * These are the kit's SEMANTIC type-scale utilities, not Tailwind's raw scale:
+ * each resolves through a namespaced --kai-text-* token in theme.css, so a
+ * consumer setting `--kai-text-body` moves the reading text. The public
+ * `proseSize` strings ('xs' | 'sm' | 'base' | 'lg') are unchanged — this is an
+ * internal re-point only. Sizes are byte-identical to the Tailwind classes they
+ * replace (text-meta ≡ text-xs, text-body ≡ text-sm, text-title ≡ text-base),
+ * so nothing moves until a token is actually overridden.
+ */
 export function textClass(size: ProseSize): string {
   switch (size) {
-    case 'xs': return 'text-xs';
-    case 'sm': return 'text-sm';
-    case 'base': return 'text-base';
+    case 'xs': return 'text-meta';
+    case 'sm': return 'text-body';
+    case 'base': return 'text-title';
     case 'lg': return 'text-lg';
   }
 }