@kitn.ai/ui 0.28.0 → 0.29.0

package/src/primitives/field-mask.ts

@@ -1,256 +0,0 @@
-// src/primitives/field-mask.ts
-// The pure format engine behind masked form fields: compile a `format` + display guide,
-// normalize arbitrary input to raw, format raw back, and map caret positions between the
-// two. No DOM, no Solid, no state -- the stateful masker (tier 2) and the widgets sit on
-// top of this. Spec: docs/superpowers/specs/2026-08-24-form-field-formats-design.md
-// (§2 tier 2, §3, deltas §5.4 and §5.7).
-//
-// Token vocabulary (a public contract, deliberately adopted rather than reinvented):
-//   `#` one digit  ·  `@` one alphanumeric  ·  `*` one alphanumeric, obscurable in display
-//   every OTHER character is a literal, identified by POSITION and not by character class.
-// That last clause is the load-bearing part: it is why `V-***` works, where a
-// character-class strip reads the literal `V` as user input (see normalizeToRaw).
-
-/** How `normalizeToRaw` folds accepted characters. */
-export type CaseMode = 'preserve' | 'upper' | 'lower';
-
-/** Why an edit was refused. Rejection decides LOUDLY: the stateful layer
- *  surfaces this on a callback and, on the element facade, as `kai-input-rejected`. */
-export type RejectReason = 'full' | 'wrong-class' | 'over-capacity';
-
-/** A compiled `format` + aligned display guide. Fill positions are `#` `@` `*`;
- *  every other index is a literal. */
-export interface MaskPattern {
-  readonly format: string;
-  readonly guide: string;          // same length as `format`
-  readonly fillIndexes: readonly number[];
-  readonly capacity: number;       // === fillIndexes.length
-}
-
-/** Thrown by `compileMask` only. Every other function in this module is total: it clamps
- *  or discards rather than throwing, because it runs on every keystroke. */
-export class MaskError extends Error {}
-
-/** Formats longer than this are refused. A mask is a field format, not a document; the cap
- *  bounds the per-keystroke walks below and makes a pasted "format" from an untrusted model
- *  a loud failure instead of a slow one. Refused, NOT truncated -- silently shortening a
- *  format changes what the field means (CLAUDE.md: decide loudly). */
-const MAX_FORMAT_LENGTH = 64;
-
-const DIGIT = /[0-9]/u;
-const ALPHANUMERIC = /[\p{L}\p{N}]/u;
-
-/** True when `token` is a fill position rather than a literal. */
-function isFillToken(token: string): boolean {
-  return token === '#' || token === '@' || token === '*';
-}
-
-/** The class test for a fill token. `*` is `@` for INPUT purposes -- the two differ only in
- *  how the display layer renders what was typed, never in what is accepted. */
-function matchesToken(token: string, ch: string): boolean {
-  return token === '#' ? DIGIT.test(ch) : ALPHANUMERIC.test(ch);
-}
-
-/** Compile a format string, with an optional aligned display guide.
- *
- *  Without a guide, one is derived: literals keep their own character and every fill
- *  position becomes a space, which is the alignment the display layer needs and is exactly
- *  the `V-   ` a consumer would have written by hand for `V-***`. */
-export function compileMask(format: string, guide?: string): MaskPattern {
-  if (format.length > MAX_FORMAT_LENGTH) {
-    throw new MaskError(
-      `format is ${format.length} characters; the maximum is ${MAX_FORMAT_LENGTH}`,
-    );
-  }
-  if (guide !== undefined && guide.length !== format.length) {
-    throw new MaskError(
-      `guide is ${guide.length} characters but format is ${format.length}; they must align position for position`,
-    );
-  }
-
-  const fillIndexes: number[] = [];
-  let derivedGuide = '';
-  for (let i = 0; i < format.length; i += 1) {
-    const token = format[i]!;
-    if (isFillToken(token)) {
-      fillIndexes.push(i);
-      derivedGuide += ' ';
-    } else {
-      derivedGuide += token;
-    }
-  }
-
-  return {
-    format,
-    guide: guide ?? derivedGuide,
-    fillIndexes,
-    capacity: fillIndexes.length,
-  };
-}
-
-/** True when `ch` may occupy raw position `rawIndex`.
- *
- *  `ch` must be exactly one UTF-16 code unit. Astral code points (a lone surrogate half
- *  cannot satisfy `\p{L}`) are outside this engine's model: one fill position holds one
- *  code unit, which is what keeps `format`, `guide`, the formatted text and the caret
- *  offsets a DOM input reports all in the same units. The target field family -- phone,
- *  SSN, ticket numbers, names, postal codes -- is BMP. */
-export function acceptsAt(p: MaskPattern, rawIndex: number, ch: string): boolean {
-  if (rawIndex < 0 || rawIndex >= p.capacity) return false;
-  if (ch.length !== 1) return false;
-  return matchesToken(p.format[p.fillIndexes[rawIndex]!]!, ch);
-}
-
-function fold(ch: string, caseMode: CaseMode): string {
-  if (caseMode === 'upper') return ch.toUpperCase();
-  if (caseMode === 'lower') return ch.toLowerCase();
-  return ch;
-}
-
-/** Raw (fill-position-only) characters extracted from arbitrary input, with
- *  positional literal consumption and case folding: literals are matched leniently.
- *
- *  LITERALS ARE MATCHED WHERE THEY SIT -- this is the fix for a real defect, and both halves
- *  of it are watched failing in the test file. A strip-then-fill normalizer (drop every
- *  non-alphanumeric, then fill positions in order) turns a pasted `V-123` under `V-***` into
- *  raw `V12`, rendered `V-V12`: the literal `V` is alphanumeric, survives the strip, is eaten
- *  by the first fill position, and the `3` falls off the end -- silently. Consuming only a
- *  leading literal RUN fixes that one case and leaves the same shape alive one level deeper:
- *  under `*-V-*`, `A-V-B` puts the interior literal `V` into the second fill position and
- *  drops the `B`. So the walk below advances over the FORMAT, not over a stripped string,
- *  and every literal -- leading, interior or trailing -- gets its chance to claim the input
- *  character sitting in front of it.
- *
- *  The two branches, and why lenience is safe here:
- *  - At a LITERAL, an input character equal to it (case-insensitively) is consumed as that
- *    literal. A character that is not equal means the input simply omitted the literal, so
- *    the format advances and the input does not -- which is what lets `chg4821`, `v123` and
- *    a bare `AB` all normalize correctly.
- *  - At a FILL, an input character of the right class is taken (folded per `caseMode`) and
- *    both advance. One of the wrong class is discarded and the position WAITS for the next
- *    one -- that is what absorbs separators, spaces and the browser's autofill formatting
- *    (`chg 4821`, `CHG-4821`, `chg4821` all give the same raw).
- *
- *  Every iteration either consumes an input character or advances the format, so it
- *  terminates. Input past the last fill position is clipped -- the caller compares lengths
- *  to report `over-capacity`. */
-export function normalizeToRaw(p: MaskPattern, input: string, caseMode: CaseMode = 'preserve'): string {
-  let raw = '';
-  let read = 0;
-  let index = 0;
-
-  while (index < p.format.length && read < input.length) {
-    const token = p.format[index]!;
-    if (!isFillToken(token)) {
-      if (input[read]!.toLowerCase() === token.toLowerCase()) read += 1;
-      index += 1;
-      continue;
-    }
-    const folded = fold(input[read]!, caseMode);
-    if (matchesToken(token, folded)) {
-      raw += folded;
-      index += 1;
-    }
-    read += 1;
-  }
-  return raw;
-}
-
-/** Raw formatted for DATA purposes -- the canonical value a `custom` mask submits:
- *  formatted, with trailing placeholders trimmed. Literals are re-inserted at their positions
- *  and the string is cut at the first UNFILLED position, because that placeholder and
- *  everything after it is not yet content.
- *
- *  A trailing literal run is NOT a placeholder, so a raw at capacity carries it: `##-END`
- *  with raw `12` is `12-END`, the same way the literals of `CHG-4821` are part of the ticket
- *  id rather than presentation. Cutting at `raw.length` instead would silently drop a fixed
- *  suffix from the submitted datum.
- *
- *  Empty raw is `''`, never the bare skeleton (`V-`): an empty field submits `''`, never
- *  the bare mask template. `formatForDisplay` is the other call site. */
-export function formatRaw(p: MaskPattern, raw: string): string {
-  if (raw.length === 0) return '';
-  let out = '';
-  let pending = ''; // a literal run whose content, if any, is still to come
-  let cursor = 0;
-  for (let i = 0; i < p.format.length; i += 1) {
-    if (!isFillToken(p.format[i]!)) {
-      pending += p.format[i]!;
-    } else if (cursor < raw.length) {
-      out += pending + raw[cursor]!;
-      pending = '';
-      cursor += 1;
-    } else {
-      return out; // an unfilled placeholder: trim it, and the literal run in front of it
-    }
-  }
-  // The format ran out with every position filled, so a literal run still pending is the
-  // format's trailing suffix and belongs to a COMPLETE value (`##-END` + `12` -> `12-END`).
-  return out + pending;
-}
-
-/** Raw formatted for DISPLAY purposes: every unfilled position shows its guide character,
- *  so the text is always `format.length` long and stays aligned. Empty raw shows the guide
- *  in full (`mm/dd/yyyy`, `V-   `). */
-export function formatForDisplay(p: MaskPattern, raw: string): string {
-  let out = '';
-  let cursor = 0;
-  for (let i = 0; i < p.format.length; i += 1) {
-    if (isFillToken(p.format[i]!) && cursor < raw.length) {
-      out += raw[cursor]!;
-      cursor += 1;
-    } else {
-      out += p.guide[i] ?? '';
-    }
-  }
-  return out;
-}
-
-/** Raw read back out of formatted text BY POSITION, which is what makes an alphanumeric
- *  literal safe: the `V` of `V-123` sits at a literal index and is never read as content.
- *  Stops at the first unfilled position, so a display string's guide characters -- which do
- *  not satisfy their position's class -- are not mistaken for input. */
-export function rawFromFormatted(p: MaskPattern, formatted: string): string {
-  let raw = '';
-  for (const index of p.fillIndexes) {
-    const ch = formatted[index];
-    if (ch === undefined || !matchesToken(p.format[index]!, ch)) break;
-    raw += ch;
-  }
-  return raw;
-}
-
-/** Caret position in `formatted` -> caret position in raw: the number of FILLED fill
- *  positions strictly before `pos`. */
-export function formattedToRawIndex(p: MaskPattern, formatted: string, pos: number): number {
-  const clamped = Math.max(0, Math.min(pos, formatted.length));
-  let rawPos = 0;
-  for (const index of p.fillIndexes) {
-    if (index >= clamped) break;
-    const ch = formatted[index];
-    if (ch === undefined || !matchesToken(p.format[index]!, ch)) break;
-    rawPos += 1;
-  }
-  return rawPos;
-}
-
-/** Caret position in raw -> caret position in `formatted`.
- *
- *  Raw 0 maps to the FIRST fill index, so the caret never lands inside a leading literal
- *  prefix. Otherwise it lands just after the last consumed fill position and is then pulled
- *  forward over any literal run that follows, so it rests where the next character will go
- *  rather than in front of a separator -- finally clamped to the text that actually exists.
- *
- *  The pull-forward is why this is a left inverse of `formattedToRawIndex` on every caret
- *  position EXCEPT the one immediately before a literal run: that position and the one after
- *  it map to the same raw index by definition, and only one of the two can come back. The
- *  post-literal one is canonical: the caret never rests inside a literal run. */
-export function rawToFormattedIndex(p: MaskPattern, formatted: string, rawPos: number): number {
-  if (p.capacity === 0) return Math.min(p.format.length, formatted.length);
-  const clamped = Math.max(0, Math.min(rawPos, p.capacity));
-  if (clamped === 0) return Math.min(p.fillIndexes[0]!, formatted.length);
-
-  let index = p.fillIndexes[clamped - 1]! + 1;
-  while (index < p.format.length && !isFillToken(p.format[index]!)) index += 1;
-  return Math.min(index, formatted.length);
-}

package/src/primitives/field-semantics.ts

@@ -1,115 +0,0 @@
-// src/primitives/field-semantics.ts
-// Tier 1: semantic input types. A semantic type derives the attributes a browser and an
-// assistive technology already know how to use -- `inputmode`, `autocomplete`,
-// `spellcheck`, `autocorrect`, `autocapitalize` -- and the canonical (submitted) form of
-// the field's value. No DOM, no Solid, no state. Spec:
-// docs/superpowers/specs/2026-08-24-form-field-formats-design.md (§2 tier 1, §4).
-//
-// `postal` is DROPPED from the spec's tier-1 table per decided O-2: the enum here is the
-// binding one, exported ONCE and read by the schema, the element facade and the tool
-// projection (CLAUDE.md "derive it, don't type it") -- no second copy of these four
-// strings anywhere else in the tree.
-import { formatRaw, rawFromFormatted, type MaskPattern } from './field-mask';
-
-export const FIELD_SEMANTIC_TYPES = ['tel', 'ssn', 'credit-card', 'custom'] as const;
-export type FieldSemanticType = (typeof FIELD_SEMANTIC_TYPES)[number];
-
-/** The tier-1 attribute bag for one semantic type. */
-export interface FieldSemantics {
-  readonly inputmode?: 'tel' | 'numeric';
-  readonly autocomplete?: string; // `ssn` sends 'off' -- no standard token, so this is a
-                                   // defensive marker against wrong autofill, not an omission
-  readonly spellcheck: false;
-  readonly autocorrect: 'off';
-  readonly autocapitalize: 'off';
-  /** The default tier-2 mask for this type, resolved only when the consumer opts in
-   *  (`mask="default"` / the form card's `x-kai-format`) -- NOT applied automatically
-   *  by a bare semantic type (decision 1). */
-  readonly defaultFormat?: string;
-  /** What the field submits: digit-only types strip separators, `custom`
-   *  keeps its formatted/literal value, `as-typed` is the unmasked fallback. */
-  readonly canonical: 'digits' | 'formatted' | 'as-typed';
-}
-
-const UNMASKED_FALLBACK: FieldSemantics = {
-  spellcheck: false,
-  autocorrect: 'off',
-  autocapitalize: 'off',
-  canonical: 'as-typed',
-};
-
-/** Resolve the tier-1 attribute bag for a semantic type.
- *
- *  Passing anything outside `FIELD_SEMANTIC_TYPES` is a TypeScript error at a typed call
- *  site; a value crossing an untyped boundary (JSON Schema, model output) that turns out
- *  not to be one of the four falls back to plain unmasked-text behavior at runtime, loudly
- *  -- `console.warn`, never a silent guess. */
-export function fieldSemantics(type: FieldSemanticType): FieldSemantics {
-  switch (type) {
-    case 'tel':
-      return {
-        inputmode: 'tel',
-        autocomplete: 'tel',
-        spellcheck: false,
-        autocorrect: 'off',
-        autocapitalize: 'off',
-        defaultFormat: '###-###-####',
-        canonical: 'digits',
-      };
-    case 'ssn':
-      return {
-        inputmode: 'numeric',
-        // 'off' -- no standard autocomplete token exists for a Social Security number, and
-        // an absent attribute invites wrong autofill; 'off' is the defensive marker even
-        // where a browser honors it unevenly (spec §2 tier 1 table).
-        autocomplete: 'off',
-        spellcheck: false,
-        autocorrect: 'off',
-        autocapitalize: 'off',
-        defaultFormat: '###-##-####',
-        canonical: 'digits',
-      };
-    case 'credit-card':
-      return {
-        inputmode: 'numeric',
-        autocomplete: 'cc-number',
-        spellcheck: false,
-        autocorrect: 'off',
-        autocapitalize: 'off',
-        defaultFormat: '#### #### #### ####',
-        canonical: 'digits',
-      };
-    case 'custom':
-      // inputmode/autocomplete are INHERITED -- the consumer sets them directly, since a
-      // custom mask carries no semantic of its own. No default format: `mask` IS the format.
-      return {
-        spellcheck: false,
-        autocorrect: 'off',
-        autocapitalize: 'off',
-        canonical: 'formatted',
-      };
-    default: {
-      const unknown: string = type;
-      console.warn(
-        `fieldSemantics: unrecognized semantic type ${JSON.stringify(unknown)}; falling back to unmasked text`,
-      );
-      return UNMASKED_FALLBACK;
-    }
-  }
-}
-
-/** The canonical (submitted) value for a field, given its compiled mask, the current
- *  FORMATTED text (`input.value`), and its semantic type.
- *
- *  Reads the raw value back out of `formatted` by position first -- an empty field is
- *  always `''`, never the bare guide. From there the two canonical shapes are read, not
- *  re-derived, per Task 1's handoff: `tel`/`ssn`/`credit-card` want the raw digits
- *  directly (their formats carry no letters, so raw IS the digit string); `custom` wants
- *  `formatRaw`, because a literal-terminated custom format (`##-END`) only carries its
- *  trailing literal once every fill position is full, and `formatRaw` is what tracks that
- *  -- `rawFromFormatted` gives raw characters only, with no literal reinsertion. */
-export function canonicalize(p: MaskPattern, formatted: string, type: FieldSemanticType): string {
-  const raw = rawFromFormatted(p, formatted);
-  if (raw.length === 0) return '';
-  return type === 'custom' ? formatRaw(p, raw) : raw;
-}

package/src/primitives/highlighter.ts

@@ -1,157 +0,0 @@
-// On-demand code highlighter built on Shiki's fine-grained core.
-//
-// Nothing here loads until `highlight()` is first called with highlighting
-// enabled — so a component set that never renders a code block ships and runs
-// with ZERO Shiki bytes. When a code block does appear, only the core, the
-// JavaScript regex engine (no WASM), the one theme, and the one language grammar
-// it needs are dynamically imported, each as its own small lazy chunk.
-//
-// Hosts extend or disable this via `configureCodeHighlighting()`.
-
-import type { HighlighterCore } from 'shiki/core';
-
-type Loader = () => Promise<unknown>;
-
-/**
- * Minimal default language set — each a separate lazy chunk, loaded only on use.
- * Kept deliberately small to keep the bundle lean; hosts add more at runtime via
- * `configureCodeHighlighting({ languages })` (no rebuild needed — see that fn).
- */
-const DEFAULT_LANGUAGES: Record<string, Loader> = {
-  bash: () => import('@shikijs/langs/bash'),
-  javascript: () => import('@shikijs/langs/javascript'),
-  typescript: () => import('@shikijs/langs/typescript'),
-  tsx: () => import('@shikijs/langs/tsx'),
-  html: () => import('@shikijs/langs/html'),
-  css: () => import('@shikijs/langs/css'),
-  json: () => import('@shikijs/langs/json'),
-  vue: () => import('@shikijs/langs/vue'),
-  svelte: () => import('@shikijs/langs/svelte'),
-};
-
-const DEFAULT_THEMES: Record<string, Loader> = {
-  'github-dark-dimmed': () => import('@shikijs/themes/github-dark-dimmed'),
-  'github-light': () => import('@shikijs/themes/github-light'),
-};
-
-const DEFAULT_ALIASES: Record<string, string> = {
-  js: 'javascript',
-  ts: 'typescript',
-  jsx: 'tsx',
-  sh: 'bash',
-  shell: 'bash',
-};
-
-const FALLBACK_THEME = 'github-dark-dimmed';
-
-export interface CodeHighlightingOptions {
-  /** Turn highlighting on/off globally. When false, code renders as plain text. */
-  enabled?: boolean;
-  /** Register/override language loaders, e.g. `{ ruby: () => import('@shikijs/langs/ruby') }`. */
-  languages?: Record<string, Loader>;
-  /** Register/override theme loaders. */
-  themes?: Record<string, Loader>;
-  /** Map short names to canonical language keys, e.g. `{ vue: 'html' }`. */
-  aliases?: Record<string, string>;
-}
-
-let enabled = true;
-let langLoaders: Record<string, Loader> = { ...DEFAULT_LANGUAGES };
-let themeLoaders: Record<string, Loader> = { ...DEFAULT_THEMES };
-let aliases: Record<string, string> = { ...DEFAULT_ALIASES };
-
-let highlighterPromise: Promise<HighlighterCore> | null = null;
-const loadedLangs = new Set<string>();
-const loadedThemes = new Set<string>();
-
-function getHighlighter(): Promise<HighlighterCore> {
-  if (!highlighterPromise) {
-    highlighterPromise = (async () => {
-      const [{ createHighlighterCore }, { createJavaScriptRegexEngine }] = await Promise.all([
-        import('shiki/core'),
-        import('shiki/engine/javascript'),
-      ]);
-      return createHighlighterCore({
-        themes: [],
-        langs: [],
-        engine: createJavaScriptRegexEngine(),
-      });
-    })();
-  }
-  return highlighterPromise;
-}
-
-function resolveLang(lang: string): string {
-  return aliases[lang] ?? lang;
-}
-
-async function ensureLang(hl: HighlighterCore, lang: string): Promise<boolean> {
-  const name = resolveLang(lang);
-  if (loadedLangs.has(name)) return true;
-  const loader = langLoaders[name];
-  if (!loader) return false;
-  await hl.loadLanguage(loader() as never);
-  loadedLangs.add(name);
-  return true;
-}
-
-async function ensureTheme(hl: HighlighterCore, theme: string): Promise<boolean> {
-  if (loadedThemes.has(theme)) return true;
-  const loader = themeLoaders[theme];
-  if (!loader) return false;
-  await hl.loadTheme(loader() as never);
-  loadedThemes.add(theme);
-  return true;
-}
-
-function escapeHtml(s: string): string {
-  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
-function plain(code: string): string {
-  return `<pre><code>${escapeHtml(code)}</code></pre>`;
-}
-
-/**
- * Highlight `code` as `lang` with `theme`, returning HTML. Loads only what's
- * needed, on demand. Falls back to escaped plain `<pre><code>` when highlighting
- * is disabled, the language has no registered loader, or anything fails.
- */
-export async function highlight(code: string, lang: string, theme: string): Promise<string> {
-  if (!enabled || !code) return plain(code);
-  try {
-    const hl = await getHighlighter();
-    const hasLang = await ensureLang(hl, lang);
-    if (!hasLang) return plain(code);
-    const useTheme = (await ensureTheme(hl, theme))
-      ? theme
-      : (await ensureTheme(hl, FALLBACK_THEME)) ? FALLBACK_THEME : null;
-    if (!useTheme) return plain(code);
-    return hl.codeToHtml(code, { lang: resolveLang(lang), theme: useTheme });
-  } catch {
-    return plain(code);
-  }
-}
-
-/** Register additional languages/themes/aliases, or disable highlighting entirely. */
-export function configureCodeHighlighting(options: CodeHighlightingOptions): void {
-  if (options.enabled !== undefined) enabled = options.enabled;
-  if (options.languages) langLoaders = { ...langLoaders, ...options.languages };
-  if (options.themes) themeLoaders = { ...themeLoaders, ...options.themes };
-  if (options.aliases) aliases = { ...aliases, ...options.aliases };
-}
-
-export function isCodeHighlightingEnabled(): boolean {
-  return enabled;
-}
-
-/** Test helper — reset the singleton and registries to defaults. */
-export function __resetCodeHighlightingForTests(): void {
-  enabled = true;
-  langLoaders = { ...DEFAULT_LANGUAGES };
-  themeLoaders = { ...DEFAULT_THEMES };
-  aliases = { ...DEFAULT_ALIASES };
-  highlighterPromise = null;
-  loadedLangs.clear();
-  loadedThemes.clear();
-}