@kitn.ai/ui 0.26.0 → 0.28.0

package/src/ui/input.tsx

@@ -1,5 +1,13 @@
-import { type JSX, Show, splitProps, createUniqueId } from 'solid-js';
+import { type JSX, Show, splitProps, createUniqueId, createEffect, onCleanup, untrack } from 'solid-js';
 import { cn } from '../utils/cn';
+import type { CaseMode } from '../primitives/field-mask';
+import { fieldSemantics, type FieldSemanticType } from '../primitives/field-semantics';
+import {
+  createInputMask,
+  type CopyPolicy,
+  type InputMask,
+  type InputMaskRejectReason,
+} from '../primitives/input-mask';
 
 export interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'onInput' | 'onChange' | 'size'> {
   /** Field label rendered above the control and linked via `for`/`id`. */
@@ -16,12 +24,58 @@ export interface InputProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElemen
   leading?: JSX.Element;
   /** Trailing affix (icon, inline button). Rendered inside the field row, after the input. */
   trailing?: JSX.Element;
-  /** Fires per keystroke with the current value. */
+  /** Fires per keystroke with the current value — the CANONICAL value when a mask is
+   *  active (digits for `tel`/`ssn`/`credit-card`, the formatted text for
+   *  `custom`), and the raw text of the field otherwise. */
   onValueInput?: (value: string) => void;
-  /** Fires on commit (blur) with the current value. */
+  /** Fires on commit (blur) with the current value; canonical when a mask is active. */
   onValueChange?: (value: string) => void;
+
+  // --- Form-field formats (spec §7.2). All five are SCALARS, which is what lets them
+  // survive as HTML attributes on the `<kai-input>` facade. Absent `format` AND absent
+  // `semantic` is the behavior of today, byte for byte (owner decision 1 / spec §1.1): no mask,
+  // no extra attributes, nothing.
+
+  /** Tier-2 mask pattern: `#` a digit, `@` an alphanumeric, `*` an obscurable
+   *  alphanumeric, everything else a positional literal (`@@@-####`).
+   *
+   *  The literal `default` is the OPT-IN sentinel: it resolves to the default format of
+   *  `semantic` (`tel` → `###-###-####`). It cannot collide with a real pattern — `default`
+   *  as a format is eight literals with no fill position, i.e. a field that can hold
+   *  nothing — and an opt-in token is needed because decision 1 forbids a bare semantic
+   *  type from starting to mask on its own. */
+  format?: string;
+  /** The placeholder guide shown at unfilled positions, aligned position-for-position
+   *  with `format` (`   -   -    `, `mm/dd/yyyy`). Without it the field shows only up
+   *  to the last typed character. */
+  guide?: string;
+  /** Tier-1 semantic type. On its own it applies `inputmode` / `autocomplete` /
+   *  `spellcheck` / `autocorrect` / `autocapitalize` and decides the canonical value —
+   *  it never starts masking by itself. */
+  semantic?: FieldSemanticType;
+  /** Case folding applied to typed and pasted text. Defaults to `preserve`. */
+  caseMode?: CaseMode;
+  /** What a copy or cut of a masked field puts on the clipboard. Defaults to `canonical`. */
+  copyPolicy?: CopyPolicy;
+  /** A mask refused, or partly refused, some content — `full`, `wrong-class`,
+   *  `over-capacity`, or `format-change-clipped`. Not a scalar and therefore not an
+   *  attribute: the facade projects this onto its `kai-input-rejected` event.
+   *
+   *  NOT an error state. `format-change-clipped` in particular fires on a routine
+   *  reactive `format` change, so this widget deliberately does not touch `invalid` —
+   *  validity belongs to the consumer, and stays there. */
+  onMaskReject?: (detail: { reason: InputMaskRejectReason; data: string }) => void;
 }
 
+/** The `format` value that means: resolve the default format of the semantic type.
+ *
+ *  EXPORTED because `src/elements/input.tsx` has to recognise the same sentinel when it
+ *  resolves a seeded value ahead of the masker, and a restated literal there would fail
+ *  SILENTLY if this string ever changed: `format === 'default'` would simply go false and
+ *  `compileMask('default')` would compile seven literals, garbling the seed with no error
+ *  anywhere. One exported constant instead of two copies of a magic string. */
+export const DEFAULT_FORMAT = 'default';
+
 // The single source of the field shell styling — lifted verbatim from the
 // `inputBase` constant that used to live in `src/components/form-widgets.tsx`.
 // `Input` now owns it; the form widgets render `Input` rather than re-pasting it.
@@ -37,7 +91,12 @@ const ROW_INPUT =
   'min-w-0 flex-1 bg-transparent text-sm text-foreground placeholder:text-muted-foreground focus-visible:outline-none disabled:cursor-not-allowed';
 
 const SIZE_SM = 'px-2.5 py-1';
-const INVALID = 'border-destructive dark:border-red-400/70';
+// The invalid-state border, EXPORTED because `src/ui/select.tsx` renders the same
+// field box and a second hand-typed copy of this string is exactly the kind of
+// restatement that rots (`docs/coupling-map.md` §4). `INVALID` stays as the local
+// alias so the three call sites below read unchanged.
+export const FIELD_INVALID = 'border-destructive dark:border-red-400/70';
+const INVALID = FIELD_INVALID;
 
 // Suppress the native search affordances Chrome/WebKit render for `type="search"`.
 // Without this the browser's `::-webkit-search-cancel-button` (×) stacks on top of
@@ -61,6 +120,7 @@ export function Input(props: InputProps): JSX.Element {
   const [local, rest] = splitProps(props, [
     'class', 'label', 'hint', 'error', 'size', 'invalid',
     'leading', 'trailing', 'onValueInput', 'onValueChange', 'onBlur', 'id', 'disabled',
+    'format', 'guide', 'semantic', 'caseMode', 'copyPolicy', 'onMaskReject',
   ]);
 
   const id = local.id ?? createUniqueId();
@@ -69,6 +129,138 @@ export function Input(props: InputProps): JSX.Element {
   const hasHint = () => !!local.error || !!local.hint;
   const hasAffix = () => local.leading != null || local.trailing != null;
 
+  // -------------------------------------------------------------------------------
+  // Form-field formats (spec §7.2). Tier 1 is a handful of attributes; tier 2 is one
+  // `createInputMask` bound to whichever `<input>` node is currently mounted.
+  // -------------------------------------------------------------------------------
+
+  const semantics = () => (local.semantic === undefined ? undefined : fieldSemantics(local.semantic));
+
+  // Both warn paths below run from a TRACKED accessor or from a reconfigure, i.e. from a
+  // routine reactive render, and both interpolate a value that reaches this widget from
+  // the form card and therefore from MODEL output. So: report each distinct bad value
+  // ONCE per widget, and clip what gets interpolated. The console is not a sink — this is
+  // about a 500-character pattern printing 500 characters on every keystroke, not about
+  // injection.
+  const warned = new Set<string>();
+  const warnOnce = (key: string, message: string): void => {
+    if (warned.has(key)) return;
+    warned.add(key);
+    console.warn(message);
+  };
+  const clip = (text: string): string =>
+    text.length <= 32 ? text : `${text.slice(0, 32)}… (${text.length} chars)`;
+
+  /** The pattern to mask with, or `undefined` for no mask at all. */
+  const maskFormat = (): string | undefined => {
+    const format = local.format;
+    if (format === undefined || format === '') return undefined;
+    if (format !== DEFAULT_FORMAT) return format;
+    const resolved = semantics()?.defaultFormat;
+    if (resolved === undefined) {
+      // Loud, never a silent no-mask: the consumer asked for a mask and is not getting
+      // one. `custom` has no default by design (its `format` IS the pattern), and a
+      // semantic type that never arrived is the more likely mistake.
+      warnOnce(
+        `default:${String(local.semantic)}`,
+        `Input: format=${DEFAULT_FORMAT} resolves the default format of a semantic type, and ` +
+          `semantic=${JSON.stringify(local.semantic)} has none. Rendering unmasked.`,
+      );
+    }
+    return resolved;
+  };
+
+  let plainEl: HTMLInputElement | undefined;
+  let rowEl: HTMLInputElement | undefined;
+  let mask: InputMask | undefined;
+  /** The node `mask` is bound to. The affix toggle is the one thing that changes it. */
+  let maskedEl: HTMLInputElement | undefined;
+
+  const detachMask = (): void => {
+    mask?.detach();
+    mask = undefined;
+    maskedEl = undefined;
+  };
+
+  const warnBadFormat = (format: string, err: unknown, kept: boolean): void => {
+    const reason = err instanceof Error ? err.message : String(err);
+    warnOnce(
+      `format:${format}`,
+      `Input: format ${JSON.stringify(clip(format))} did not compile (${reason}); ` +
+        (kept ? 'the field keeps its previous format.' : 'rendering unmasked.'),
+    );
+  };
+
+  createEffect(() => {
+    // Everything reactive is read HERE, so the effect re-runs on a config change or an
+    // affix toggle and on nothing else.
+    const format = maskFormat();
+    const config = {
+      guide: local.guide,
+      semantic: local.semantic,
+      caseMode: local.caseMode,
+      copyPolicy: local.copyPolicy,
+    };
+    // WHICH NODE IS MOUNTED. `Input` caches two `<input>`s and `<Show>` swaps between
+    // them when a leading/trailing affix appears or disappears — the one legitimate node
+    // change in this file (spec §8.1). The `ref` of a node fires only when it is BUILT, and
+    // the cached node is built once, so a toggle back to an existing node notifies
+    // nobody. Re-attachment therefore has to be explicit, and this read is what makes it
+    // happen. Everything else about this widget is pinned to keeping the SAME node alive
+    // (`tests/ui/input-node-identity.test.tsx`), which is the only reason a long-lived
+    // masker on it is safe at all.
+    //
+    // THE ASSUMPTION THIS RELIES ON, stated: `plainEl`/`rowEl` are plain mutable refs, so
+    // this reads a node only because Solid runs the `<Show>` render effect that BUILDS it
+    // (and its `ref`) before this user effect. If that ever stopped holding, `el` would be
+    // `undefined` on the toggle and the branch below would detach with nothing queued to
+    // re-attach — silently. The affix tests in the node-identity file are what would catch it.
+    const el = hasAffix() ? rowEl : plainEl;
+
+    untrack(() => {
+      if (format === undefined || el === undefined) {
+        detachMask();
+        return;
+      }
+
+      if (mask !== undefined && maskedEl === el) {
+        // Same node, new configuration: RE-CONFIGURE. Re-creating would drop the undo
+        // stack and re-seed from the DOM text. `update()` is atomic — a format that
+        // fails to compile leaves the masker exactly as it was — so a half-typed
+        // reactive pattern cannot corrupt the field.
+        try {
+          mask.update({ format, ...config });
+        } catch (err) {
+          warnBadFormat(format, err, true);
+        }
+        return;
+      }
+
+      // First attach, or the affix toggle. Carry the value across: the incoming node is
+      // a different element and knows nothing about what the user typed into the old one.
+      const carried = mask?.getFormattedValue() ?? el.value;
+      detachMask();
+      try {
+        mask = createInputMask(el, {
+          ...config,
+          format,
+          initialValue: carried,
+          // The callback of the masker, not the DOM `input` event, is the emission point: a
+          // canceled `beforeinput` means a real browser never fires `input` at all for a
+          // typed character.
+          onInput: ({ canonical }) => local.onValueInput?.(canonical),
+          onReject: (detail) => local.onMaskReject?.(detail),
+        });
+        maskedEl = el;
+      } catch (err) {
+        // A bad pattern falls back to a plain text field, loudly (spec §7.3).
+        warnBadFormat(format, err, false);
+      }
+    });
+  });
+
+  onCleanup(detachMask);
+
   // The class arrives as an ACCESSOR, not a string, and this is load-bearing.
   //
   // Solid evaluates a `<Show>` `fallback` inside the Show's own memo. When the
@@ -83,20 +275,57 @@ export function Input(props: InputProps): JSX.Element {
   // Solid compiles it into a nested effect that sets the attribute on the
   // EXISTING node. Same reason the affix branch was always fine: it inserts the
   // input through a function. Pinned by `tests/ui/input-node-identity.test.tsx`.
-  const inputEl = (cls: () => string, part: string): JSX.Element => (
+  // Tier-1 attributes (spec §2). Each is a DEFAULT the semantic type supplies: an
+  // explicit prop always wins, because the consumer knows something the enum does not.
+  // With no `semantic` every one of these is `undefined` — the attribute is simply not
+  // set, which is what byte-for-byte parity with the behavior of today means here.
+  const inputmodeAttr = () => rest.inputmode ?? semantics()?.inputmode;
+  const autocompleteAttr = () =>
+    (rest.autocomplete ?? semantics()?.autocomplete) as JSX.InputHTMLAttributes<HTMLInputElement>['autocomplete'];
+  const spellcheckAttr = () => {
+    const explicit = rest.spellcheck;
+    // Normalized to the attribute spelling so both forms land as an attribute rather
+    // than one of them as a property: `spellcheck={false}` is a real value, not an
+    // absent one, and it must stay visible in the DOM.
+    if (explicit !== undefined) return explicit === true || explicit === 'true' ? 'true' : 'false';
+    const semantic = semantics();
+    if (semantic === undefined) return undefined;
+    return semantic.spellcheck ? 'true' : 'false';
+  };
+  const autocorrectAttr = () => rest.autocorrect ?? semantics()?.autocorrect;
+  const autocapitalizeAttr = () => rest.autocapitalize ?? semantics()?.autocapitalize;
+
+  const inputEl = (
+    cls: () => string,
+    part: string,
+    register: (el: HTMLInputElement) => void,
+  ): JSX.Element => (
     <input
       {...rest}
+      ref={register}
       id={id}
       part={part}
       disabled={local.disabled}
       aria-invalid={isInvalid() ? 'true' : undefined}
       aria-describedby={hasHint() ? hintId : undefined}
+      inputmode={inputmodeAttr()}
+      autocomplete={autocompleteAttr()}
+      spellcheck={spellcheckAttr()}
+      autocorrect={autocorrectAttr()}
+      autocapitalize={autocapitalizeAttr()}
       class={cn(SEARCH_RESET, cls())}
-      onInput={(e) => local.onValueInput?.(e.currentTarget.value)}
+      // When a mask is active the masker owns the emission (see its `onInput` above) and
+      // this handler stands down — otherwise a jsdom-style `input` event, which reaches
+      // both, would emit twice, and the raw text it reads is the FORMATTED value rather
+      // than the canonical one.
+      onInput={(e) => {
+        if (mask !== undefined) return;
+        local.onValueInput?.(e.currentTarget.value);
+      }}
       onBlur={(e) => {
         const handler = local.onBlur;
         if (typeof handler === 'function') handler(e);
-        local.onValueChange?.(e.currentTarget.value);
+        local.onValueChange?.(mask?.getCanonicalValue() ?? e.currentTarget.value);
       }}
     />
   );
@@ -107,10 +336,21 @@ export function Input(props: InputProps): JSX.Element {
   // Created on first use and then REUSED, so toggling an affix on or off does
   // not discard a focused input either. The lazy cache also keeps the unused
   // branch's node (and its effects) from being built at all.
+  //
+  // KEEP PROSE IN THIS FILE FREE OF STRAY QUOTE CHARACTERS. The part-name guard in
+  // `src/elements/slots.test.ts` scans this source with a naive quote regex, so one
+  // apostrophe in a comment shifts its parity and swallows the part literals below —
+  // that guard then reddens over a comment, naming a part that is still right there.
+  //
+  // Each branch registers its node so the mask effect above can find whichever one is
+  // mounted; `ref` fires once per node, at construction, which is exactly when a node
+  // first becomes findable.
   let plainNode: JSX.Element;
-  const plainInput = () => (plainNode ??= inputEl(fieldClass, 'field input'));
+  const plainInput = () =>
+    (plainNode ??= inputEl(fieldClass, 'field input', (el) => (plainEl = el)));
   let rowNode: JSX.Element;
-  const rowInput = () => (rowNode ??= inputEl(() => ROW_INPUT, 'input'));
+  const rowInput = () =>
+    (rowNode ??= inputEl(() => ROW_INPUT, 'input', (el) => (rowEl = el)));
 
   return (
     <div class="flex w-full flex-col gap-1.5">

package/src/ui/kbd.tsx

@@ -70,7 +70,7 @@ function glyph(token: string, mac: boolean): string {
 }
 
 const SIZE: Record<'sm' | 'md', string> = {
-  sm: 'h-5 min-w-5 px-1 text-[11px]',
+  sm: 'h-5 min-w-5 px-1 text-caption',
   md: 'h-6 min-w-6 px-1.5 text-xs',
 };
 

package/src/ui/nav.tsx

@@ -221,7 +221,7 @@ function NavRows(props: NavRowsProps) {
                   </span>
                 </Show>
                 <Show when={item.badge}>
-                  <Badge variant="default" class="px-1.5 py-0 text-[0.625rem] font-medium uppercase tracking-wide">{item.badge}</Badge>
+                  <Badge variant="default" class="px-1.5 py-0 text-micro font-medium uppercase tracking-wide">{item.badge}</Badge>
                 </Show>
                 <Show when={item.trailing}>{renderIcon(item.trailing, { class: 'size-4 shrink-0 opacity-0 transition-opacity group-hover:opacity-60' })}</Show>
               </button>

package/src/ui/pane-group.tsx

@@ -201,7 +201,7 @@ export function PaneGroup(props: PaneGroupProps) {
             </Show>
             <span
               class={cn(
-                'relative flex size-[18px] items-center justify-center rounded text-[11px] font-bold leading-none tabular-nums',
+                'relative flex size-[18px] items-center justify-center rounded text-caption font-bold leading-none tabular-nums',
                 TONE_BG[tone()],
                 TONE_BADGE_FG[tone()],
               )}
@@ -215,7 +215,7 @@ export function PaneGroup(props: PaneGroupProps) {
           <Show when={tab().status?.label}>
             <span
               class={cn(
-                'truncate text-[10px] font-medium',
+                'truncate text-micro font-medium',
                 TONE_TEXT[tone()],
                 alwaysWord() ? 'inline' : 'hidden group-hover/tab:inline',
               )}

package/src/ui/radio.tsx

@@ -0,0 +1,150 @@
+import { type JSX, For, Show, splitProps, createUniqueId } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface RadioProps extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> {}
+
+/**
+ * A single radio button. A REAL `<input type="radio">` behind `appearance: none`,
+ * styled by the kit's `.kai-radio` rule, never a `<div role="radio">`.
+ *
+ * The native element is what makes a set of radios a GROUP: browsers give same-`name`
+ * radios one tab stop, arrow-key navigation between them, mutual exclusion and form
+ * participation, and screen readers announce "2 of 4". None of that is reimplementable
+ * for free, and every hand-rolled radio in this kit's control audit had lost some of it.
+ *
+ * Use {@link RadioGroup} for a set. Reach for a bare `Radio` when you are laying the
+ * group out yourself — give every member the same `name`.
+ *
+ * Everything not listed in `RadioProps` is forwarded to the input, so `id`, `name`,
+ * `value`, `required`, `disabled`, `aria-*` and any `data-*` hook behave exactly as
+ * they do on a plain `<input>`. No validation is applied: `required` reaches the
+ * native attribute and stops there.
+ */
+export function Radio(props: RadioProps): JSX.Element {
+  const [local, rest] = splitProps(props, ['class']);
+  return <input {...rest} type="radio" class={cn('kai-radio', local.class)} />;
+}
+
+/** One choice in a {@link RadioGroup}. */
+export interface RadioOption<T = string> {
+  /** The value this row selects. Compared to the group's `value` by identity. */
+  value: T;
+  /** The row's visible label. */
+  label: JSX.Element;
+  /** Optional second line under the label. */
+  description?: JSX.Element;
+  /** Disable this row alone (the group's `disabled` disables all of them). */
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps<T = string>
+  extends Omit<JSX.HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+  /** The choices, in display order. */
+  options: readonly RadioOption<T>[];
+  /** The selected value. Matched against each option's `value` by identity. */
+  value?: T;
+  /**
+   * The shared form-control name every radio in the group carries — what makes the
+   * browser treat them as one control. Defaults to a generated id, so the group is
+   * exclusive and keyboard-navigable even when nothing is being submitted.
+   */
+  name?: string;
+  /** Disable every row. */
+  disabled?: boolean;
+  /** Accessible name for the group. Rendered as `aria-label` on the `radiogroup`. */
+  label?: string;
+  /** Fires with the newly selected value (and its option) on selection. */
+  onChange?: (value: T, option: RadioOption<T>) => void;
+  /** Fires when a radio loses focus — the commit point for a form field. */
+  onOptionBlur?: () => void;
+  /** Extra classes for each row. */
+  itemClass?: string;
+  /**
+   * Presentation slot. Replaces the default label/description column with whatever
+   * you return, so a row can carry media, a badge or a price without a second radio
+   * component existing. The control, the row chrome and the group semantics stay ours.
+   */
+  children?: (option: RadioOption<T>, state: { checked: boolean; disabled: boolean }) => JSX.Element;
+}
+
+/**
+ * A vertical set of radio rows in a bordered, divided list — the kit's standard
+ * "pick exactly one" control.
+ *
+ * The group is a `role="radiogroup"` wrapper around real `<input type="radio">`s that
+ * share a `name`, so the keyboard behaviour (one tab stop, arrows to move) is the
+ * browser's and not a reimplementation. Clicking anywhere on a row selects it, because
+ * each row is a `<label>`.
+ *
+ * Everything not listed in `RadioGroupProps` is forwarded to the group element, so
+ * `id`, `aria-*` and any `data-*` hook land where a form expects them.
+ *
+ * ```tsx
+ * <RadioGroup
+ *   label="Severity"
+ *   options={[{ value: 'blocking', label: 'Blocking' }, { value: 'cosmetic', label: 'Cosmetic' }]}
+ *   value={severity()}
+ *   onChange={setSeverity}
+ * />
+ * ```
+ */
+export function RadioGroup<T = string>(props: RadioGroupProps<T>): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'options', 'value', 'name', 'disabled', 'label', 'onChange', 'onOptionBlur', 'itemClass', 'children', 'class',
+  ]);
+  const fallbackName = createUniqueId();
+  const groupName = () => local.name ?? fallbackName;
+  return (
+    <div
+      {...rest}
+      role="radiogroup"
+      aria-label={local.label}
+      class={cn('divide-y divide-border overflow-hidden rounded-lg border border-border', local.class)}
+    >
+      <For each={local.options}>
+        {(opt) => {
+          const checked = () => local.value === opt.value;
+          const rowDisabled = () => !!(local.disabled || opt.disabled);
+          return (
+            <label
+              class={cn(
+                'flex cursor-pointer items-center gap-3 px-3 py-2.5 text-sm transition-colors',
+                opt.description !== undefined && 'items-start',
+                checked()
+                  ? 'bg-accent font-medium text-accent-foreground'
+                  : 'text-foreground hover:bg-muted/50',
+                local.itemClass,
+              )}
+            >
+              <Radio
+                name={groupName()}
+                value={String(opt.value)}
+                checked={checked()}
+                disabled={rowDisabled()}
+                class={opt.description === undefined ? undefined : 'mt-0.5'}
+                onChange={() => local.onChange?.(opt.value, opt)}
+                onBlur={() => local.onOptionBlur?.()}
+              />
+              <Show
+                when={local.children}
+                fallback={
+                  // No description → a bare <span>, byte for byte what every call site
+                  // rendered before this component existed. The two-line column only
+                  // appears when there is a second line to put in it.
+                  <Show when={opt.description !== undefined} fallback={<span>{opt.label}</span>}>
+                    <span class="flex flex-col gap-0.5">
+                      <span>{opt.label}</span>
+                      <span class="text-xs font-normal text-muted-foreground">{opt.description}</span>
+                    </span>
+                  </Show>
+                }
+              >
+                {(render) => render()(opt, { checked: checked(), disabled: rowDisabled() })}
+              </Show>
+            </label>
+          );
+        }}
+      </For>
+    </div>
+  );
+}