@urbicon-ui/blocks 6.36.0 → 6.37.1

package/dist/components/PinInput/PinInput.svelte

@@ -0,0 +1,325 @@
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { useBlocksI18n } from '../..';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
+  import { getTierContext } from '../../utils';
+  import type { PinInputProps } from './index';
+  import { pinInputVariants, type PinInputVariants } from './pin-input.variants';
+
+  const bt = useBlocksI18n();
+
+  let {
+    value = $bindable(''),
+    length = 6,
+    type = 'numeric',
+    mask = false,
+    placeholder = '',
+    uppercase = false,
+    autoFocus = false,
+    separator,
+    groupSize = 3,
+    tier,
+    variant = 'outlined',
+    size = 'md',
+    intent = 'default',
+    disabled = false,
+    readonly = false,
+    required = false,
+    label,
+    helper,
+    error,
+    onValueChange,
+    onComplete,
+    name,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    id: idProp,
+    'aria-label': ariaLabel
+  }: PinInputProps = $props();
+
+  const tierCtx = getTierContext();
+  const effectiveTier = $derived(tier ?? tierCtx?.tier ?? 'modify');
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+
+  const propsId = $props.id();
+  const fieldId = $derived(idProp ?? `pininput-${propsId}`);
+  const labelId = $derived(`${fieldId}-label`);
+  const messageId = $derived(`${fieldId}-message`);
+  const describedBy = $derived(error || helper ? messageId : undefined);
+
+  // Allowed-character filter. `numeric` keeps digits; `alphanumeric` also keeps
+  // ASCII letters and (optionally) uppercases them. Applied to typed input,
+  // pasted text, and externally-set values alike, so the model never holds a
+  // character a cell could not have produced.
+  function sanitize(raw: string): string {
+    const re = type === 'numeric' ? /[^0-9]/g : /[^0-9a-zA-Z]/g;
+    const cleaned = raw.replace(re, '');
+    return uppercase && type !== 'numeric' ? cleaned.toUpperCase() : cleaned;
+  }
+
+  function toCells(raw: string): string[] {
+    const chars = sanitize(raw).slice(0, length).split('');
+    return Array.from({ length }, (_, i) => chars[i] ?? '');
+  }
+
+  // `cells` is the DOM source of truth; `value` (bindable) mirrors its join.
+  // Empty cells collapse in the join — fine for OTP, where the value is the
+  // sequence of entered characters, not a positional map.
+  let cells = $state<string[]>(toCells(value ?? ''));
+  let inputs = $state<(HTMLInputElement | undefined)[]>([]);
+  let wasComplete = $state(false);
+
+  // External value / length / filter changes re-seed the buffer. Writing back a
+  // normalized `value` keeps an out-of-range or unsanitized prop honest without
+  // firing onValueChange (the parent set it deliberately).
+  $effect(() => {
+    const normalized = toCells(value ?? '').join('');
+    if (normalized !== untrack(() => cells.join(''))) {
+      cells = toCells(normalized);
+    }
+    if (normalized !== (value ?? '')) {
+      value = normalized;
+    }
+    // Completeness must track the (possibly externally reset) value — a stale
+    // `true` after a parent-side clear would swallow the onComplete of the next
+    // single-emit fill (paste/autofill), the standard wrong-code retry flow.
+    wasComplete = normalized.length === length;
+  });
+
+  // Stable per-position keys — the index IS the cell identity, but a derived id
+  // keeps `{#each}` off a bare index key.
+  const cellKeys = $derived(Array.from({ length }, (_, i) => `${fieldId}-cell-${i}`));
+
+  const variantProps: PinInputVariants = $derived({
+    tier: effectiveTier,
+    variant,
+    size,
+    intent,
+    disabled: disabled || undefined,
+    readonly: readonly || undefined,
+    error: !!error || undefined,
+    required: required || undefined,
+    messageType: error ? 'error' : 'helper'
+  });
+
+  const styles = $derived(pinInputVariants(variantProps));
+
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'PinInput', preset, variantProps, slotClassesProp)
+  );
+
+  function cellClass() {
+    return unstyled ? (slotClasses?.cell ?? '') : styles.cell({ class: slotClasses?.cell });
+  }
+
+  function focusCell(index: number) {
+    const el = inputs[index];
+    if (el) {
+      el.focus();
+      el.select();
+    }
+  }
+
+  function emit() {
+    const joined = cells.join('');
+    if (joined !== value) {
+      value = joined;
+      onValueChange?.(joined);
+    }
+    const complete = cells.every((c) => c !== '');
+    if (complete && !wasComplete) onComplete?.(joined);
+    wasComplete = complete;
+  }
+
+  // Distribute a run of characters across cells starting at `start` (typing more
+  // than one char, autofill, or paste). Focus lands on the cell after the last
+  // one written, or the final cell when the run fills to the end.
+  function fill(start: number, raw: string) {
+    const chars = sanitize(raw).split('');
+    if (chars.length === 0) return;
+    let idx = start;
+    for (const ch of chars) {
+      if (idx >= length) break;
+      cells[idx] = ch;
+      idx++;
+    }
+    emit();
+    focusCell(Math.min(idx, length - 1));
+  }
+
+  function handleInput(index: number, event: Event) {
+    const el = event.currentTarget as HTMLInputElement;
+    const sanitized = sanitize(el.value);
+    if (sanitized.length <= 1) {
+      const ch = sanitized;
+      // A rejected character (a letter in numeric mode) sanitizes to '' while the
+      // raw field is non-empty. Restore the existing digit instead of erasing it —
+      // a bad keystroke must not destroy a filled cell.
+      if (ch === '' && el.value !== '') {
+        el.value = cells[index];
+        return;
+      }
+      // Force the DOM to the sanitized single char so a rejected glyph can never
+      // linger in an otherwise-empty cell (the model may not have changed).
+      el.value = ch;
+      if (cells[index] !== ch) {
+        cells[index] = ch;
+        emit();
+      }
+      if (ch && index < length - 1) focusCell(index + 1);
+    } else {
+      fill(index, sanitized);
+      el.value = cells[index];
+    }
+  }
+
+  function handleKeydown(index: number, event: KeyboardEvent) {
+    if (disabled) return;
+    switch (event.key) {
+      case 'Backspace':
+        if (readonly) break;
+        event.preventDefault();
+        if (cells[index]) {
+          cells[index] = '';
+          if (inputs[index]) inputs[index]!.value = '';
+          emit();
+        } else if (index > 0) {
+          cells[index - 1] = '';
+          if (inputs[index - 1]) inputs[index - 1]!.value = '';
+          emit();
+          focusCell(index - 1);
+        }
+        break;
+      case 'Delete':
+        if (readonly) break;
+        event.preventDefault();
+        if (cells[index]) {
+          cells[index] = '';
+          if (inputs[index]) inputs[index]!.value = '';
+          emit();
+        }
+        break;
+      case 'ArrowLeft':
+        event.preventDefault();
+        if (index > 0) focusCell(index - 1);
+        break;
+      case 'ArrowRight':
+        event.preventDefault();
+        if (index < length - 1) focusCell(index + 1);
+        break;
+      case 'Home':
+        event.preventDefault();
+        focusCell(0);
+        break;
+      case 'End':
+        event.preventDefault();
+        focusCell(length - 1);
+        break;
+    }
+  }
+
+  function handlePaste(index: number, event: ClipboardEvent) {
+    event.preventDefault();
+    if (disabled || readonly) return;
+    fill(index, event.clipboardData?.getData('text') ?? '');
+  }
+
+  function handleFocus(event: FocusEvent) {
+    (event.currentTarget as HTMLInputElement).select();
+  }
+
+  // Focus the first empty cell on mount when requested. Runs once — autoFocus is
+  // stable — and untracks `cells` so a later edit does not re-steal focus.
+  $effect(() => {
+    if (!autoFocus) return;
+    untrack(() => {
+      const firstEmpty = cells.findIndex((c) => !c);
+      focusCell(firstEmpty === -1 ? length - 1 : firstEmpty);
+    });
+  });
+</script>
+
+<div
+  class={unstyled
+    ? [slotClasses?.root, className].filter(Boolean).join(' ')
+    : styles.root({ class: [slotClasses?.root, className] })}
+>
+  {#if label}
+    <span
+      id={labelId}
+      class={unstyled ? (slotClasses?.label ?? '') : styles.label({ class: slotClasses?.label })}
+    >
+      {label}
+    </span>
+  {/if}
+
+  <div
+    role="group"
+    aria-labelledby={label ? labelId : undefined}
+    aria-label={label ? undefined : ariaLabel}
+    class={unstyled ? (slotClasses?.group ?? '') : styles.group({ class: slotClasses?.group })}
+  >
+    {#each cellKeys as key, i (key)}
+      {#if separator && i > 0 && i % groupSize === 0}
+        <span
+          aria-hidden="true"
+          class={unstyled
+            ? (slotClasses?.separator ?? '')
+            : styles.separator({ class: slotClasses?.separator })}
+        >
+          {separator}
+        </span>
+      {/if}
+      <input
+        bind:this={inputs[i]}
+        id={i === 0 ? fieldId : undefined}
+        value={cells[i]}
+        type={mask ? 'password' : 'text'}
+        inputmode={type === 'numeric' ? 'numeric' : 'text'}
+        autocomplete={i === 0 ? 'one-time-code' : 'off'}
+        pattern={type === 'numeric' ? '[0-9]*' : undefined}
+        maxlength="1"
+        placeholder={placeholder || undefined}
+        {disabled}
+        {readonly}
+        aria-label={bt('accessibility.pinInputCell', { index: i + 1, total: length })}
+        aria-invalid={error ? 'true' : undefined}
+        aria-describedby={describedBy}
+        class={cellClass()}
+        oninput={(e) => handleInput(i, e)}
+        onkeydown={(e) => handleKeydown(i, e)}
+        onpaste={(e) => handlePaste(i, e)}
+        onfocus={handleFocus}
+      />
+    {/each}
+  </div>
+
+  {#if error}
+    <div
+      id={messageId}
+      role="alert"
+      class={unstyled
+        ? (slotClasses?.message ?? '')
+        : styles.message({ class: slotClasses?.message })}
+    >
+      {error}
+    </div>
+  {:else if helper}
+    <div
+      id={messageId}
+      class={unstyled
+        ? (slotClasses?.message ?? '')
+        : styles.message({ class: slotClasses?.message })}
+    >
+      {helper}
+    </div>
+  {/if}
+
+  {#if name}
+    <input type="hidden" {name} {value} />
+  {/if}
+</div>

package/dist/components/PinInput/PinInput.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { PinInputProps } from './index.js';
+declare const PinInput: import("svelte").Component<PinInputProps, {}, "value">;
+type PinInput = ReturnType<typeof PinInput>;
+export default PinInput;

package/dist/components/PinInput/index.d.ts

@@ -0,0 +1,98 @@
+import type { PinInputSlots, PinInputVariants } from './pin-input.variants.js';
+/**
+ * @description Segmented one-time-code / PIN entry — a row of single-character
+ * cells with auto-advance, backspace-to-previous, paste-to-fill, and optional
+ * masking. Purpose-built for the 2FA/OTP flow the auth package's
+ * `TwoFactorManager` drives (pair it with `autoComplete="one-time-code"` for
+ * iOS SMS autofill). The value is the concatenated string; `onComplete` fires
+ * once every cell is filled.
+ *
+ * @tag form
+ * @related Input
+ * @related NumberInput
+ * @stability beta
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   let code = $state('');
+ * </script>
+ * <PinInput bind:value={code} length={6} onComplete={(v) => verify(v)} />
+ * ```
+ *
+ * @example Masked, alphanumeric, grouped with a separator
+ * ```svelte
+ * <PinInput length={8} type="alphanumeric" mask separator="-" groupSize={4} />
+ * ```
+ */
+export interface PinInputProps extends Omit<PinInputVariants, 'error'> {
+    /** Current value — the concatenated cell characters. Supports `bind:value`. */
+    value?: string;
+    /** Number of cells. @default 6 */
+    length?: number;
+    /**
+     * Allowed characters and keyboard hint. `numeric` accepts `0-9` and sets a
+     * numeric inputmode; `alphanumeric` also accepts `A-Z`/`a-z`. @default 'numeric'
+     */
+    type?: 'numeric' | 'alphanumeric';
+    /** Render each filled cell as a masked dot (password style). @default false */
+    mask?: boolean;
+    /** Placeholder character shown in every empty cell. @default '' */
+    placeholder?: string;
+    /**
+     * Uppercase alphanumeric input as it is entered — keeps a code like `ABCD`
+     * visually consistent regardless of caps lock. Ignored for `numeric`.
+     * @default false
+     */
+    uppercase?: boolean;
+    /** Focus the first empty cell on mount. @default false */
+    autoFocus?: boolean;
+    /**
+     * Render a separator between groups of `groupSize` cells (e.g. `123-456`).
+     * A string is shown verbatim; omit for no separator.
+     */
+    separator?: string;
+    /** Cells per group when `separator` is set. @default 3 */
+    groupSize?: number;
+    /** @default false */
+    disabled?: boolean;
+    /** @default false */
+    readonly?: boolean;
+    /** Adds a required asterisk to the label. @default false */
+    required?: boolean;
+    /** Group label rendered above the cells and linked via `aria-labelledby`. */
+    label?: string;
+    /** Helper text below the cells — hidden when `error` is present. */
+    helper?: string;
+    /**
+     * Error message below the cells. When set it overrides `helper`, colours the
+     * cells danger, and sets `aria-invalid` on every cell.
+     */
+    error?: string;
+    /** Fires after any change (typing, paste, backspace) with the full value. */
+    onValueChange?: (value: string) => void;
+    /** Fires once when the last empty cell is filled, with the complete value. */
+    onComplete?: (value: string) => void;
+    /** Shared `name` for a hidden input, for native form submission. */
+    name?: string;
+    /** Extra classes merged onto the root element. */
+    class?: string;
+    /** Remove all default tv() classes — only user-provided classes apply. */
+    unstyled?: boolean;
+    /**
+     * Per-slot class overrides merged with tv() styles. Slots: root (what `class`
+     * also targets) | label | group | cell | separator | message.
+     */
+    slotClasses?: Partial<Record<PinInputSlots, string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ PinInput: {...} }}>`. */
+    preset?: string;
+    /**
+     * Accessible name for the cell group when no visible `label` is set. Each
+     * cell additionally announces its position ("digit 2 of 6").
+     */
+    'aria-label'?: string;
+    /** Root id; the cells derive their ids and ARIA wiring from it. */
+    id?: string;
+}
+export { default as PinInput } from './PinInput.svelte';
+export { type PinInputVariants, pinInputVariants } from './pin-input.variants.js';

package/dist/components/PinInput/index.js

@@ -0,0 +1,2 @@
+export { default as PinInput } from './PinInput.svelte';
+export { pinInputVariants } from './pin-input.variants.js';

package/dist/components/PinInput/pin-input.variants.d.ts

@@ -0,0 +1,96 @@
+import { type SlotNames, type VariantProps } from '../../utils/variants.js';
+export declare const pinInputVariants: ((props?: {
+    tier?: "commit" | "modify" | undefined;
+    variant?: "ghost" | "filled" | "outlined" | undefined;
+    size?: "sm" | "md" | "lg" | undefined;
+    intent?: "default" | "success" | "warning" | "danger" | undefined;
+    disabled?: boolean | undefined;
+    readonly?: boolean | undefined;
+    messageType?: "error" | "helper" | undefined;
+    error?: boolean | undefined;
+    required?: boolean | undefined;
+} | undefined) => {
+    root: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        intent?: "default" | "success" | "warning" | "danger" | undefined;
+        disabled?: boolean | undefined;
+        readonly?: boolean | undefined;
+        messageType?: "error" | "helper" | undefined;
+        error?: boolean | undefined;
+        required?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    label: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        intent?: "default" | "success" | "warning" | "danger" | undefined;
+        disabled?: boolean | undefined;
+        readonly?: boolean | undefined;
+        messageType?: "error" | "helper" | undefined;
+        error?: boolean | undefined;
+        required?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    group: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        intent?: "default" | "success" | "warning" | "danger" | undefined;
+        disabled?: boolean | undefined;
+        readonly?: boolean | undefined;
+        messageType?: "error" | "helper" | undefined;
+        error?: boolean | undefined;
+        required?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    cell: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        intent?: "default" | "success" | "warning" | "danger" | undefined;
+        disabled?: boolean | undefined;
+        readonly?: boolean | undefined;
+        messageType?: "error" | "helper" | undefined;
+        error?: boolean | undefined;
+        required?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    separator: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        intent?: "default" | "success" | "warning" | "danger" | undefined;
+        disabled?: boolean | undefined;
+        readonly?: boolean | undefined;
+        messageType?: "error" | "helper" | undefined;
+        error?: boolean | undefined;
+        required?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    message: (props?: ({
+        tier?: "commit" | "modify" | undefined;
+        variant?: "ghost" | "filled" | "outlined" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+        intent?: "default" | "success" | "warning" | "danger" | undefined;
+        disabled?: boolean | undefined;
+        readonly?: boolean | undefined;
+        messageType?: "error" | "helper" | undefined;
+        error?: boolean | undefined;
+        required?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+}) & {
+    readonly config: import("../../utils/variants.js").TVConfig;
+};
+export type PinInputVariants = VariantProps<typeof pinInputVariants>;
+/** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
+export type PinInputSlots = SlotNames<typeof pinInputVariants>;

package/dist/components/PinInput/pin-input.variants.js

@@ -0,0 +1,111 @@
+import { tv } from '../../utils/variants.js';
+export const pinInputVariants = tv({
+    slots: {
+        root: ['flex flex-col gap-1.5'],
+        label: ['block font-medium text-text-secondary text-sm'],
+        group: ['flex items-center'],
+        cell: [
+            'box-border text-center font-medium tabular-nums caret-primary',
+            'border text-text-primary bg-surface-base',
+            'transition-[color,background-color,border-color,box-shadow] duration-[var(--blocks-duration-fast)] ease-out',
+            'focus-visible:outline-none focus-visible:border-primary focus-visible:ring-2 focus-visible:ring-primary/20 focus-visible:z-10',
+            'hover:border-border-default',
+            'disabled:opacity-50 disabled:cursor-not-allowed disabled:bg-surface-subtle',
+            'read-only:bg-surface-subtle read-only:cursor-default'
+        ],
+        separator: ['text-text-tertiary select-none'],
+        message: ['text-xs']
+    },
+    variants: {
+        // 3-tier semantic radius. Default `modify` (soft) — pin cells read as fields.
+        // Inherited from a wrapping <Toolbar tier="commit"> via TierContext.
+        tier: {
+            modify: { cell: 'rounded-modify' },
+            commit: { cell: 'rounded-commit' }
+        },
+        variant: {
+            outlined: { cell: 'border-border-subtle' },
+            filled: {
+                cell: 'bg-surface-interactive border-transparent hover:bg-surface-hover focus-visible:bg-surface-base'
+            },
+            ghost: {
+                cell: 'bg-transparent hover:bg-surface-subtle focus-visible:bg-surface-base focus-visible:border-border-subtle'
+            }
+        },
+        size: {
+            sm: {
+                // `pointer-coarse:text-base` floors the font to 16px on touch-primary
+                // devices — below 16px iOS Safari auto-zooms the field on focus.
+                cell: 'h-9 w-9 text-sm pointer-coarse:text-base',
+                group: 'gap-1.5',
+                separator: 'mx-0.5 text-sm'
+            },
+            md: {
+                cell: 'h-11 w-11 text-lg',
+                group: 'gap-2',
+                separator: 'mx-1 text-lg'
+            },
+            lg: {
+                cell: 'h-14 w-14 text-2xl',
+                group: 'gap-2.5',
+                separator: 'mx-1.5 text-2xl'
+            }
+        },
+        intent: {
+            default: {},
+            success: {
+                cell: 'border-success focus-visible:border-success focus-visible:ring-success/20'
+            },
+            warning: {
+                cell: 'border-warning focus-visible:border-warning focus-visible:ring-warning/20'
+            },
+            danger: {
+                cell: 'border-danger focus-visible:border-danger focus-visible:ring-danger/20'
+            }
+        },
+        disabled: {
+            true: {
+                cell: 'opacity-50 cursor-not-allowed bg-surface-disabled pointer-events-none',
+                label: 'text-text-disabled'
+            }
+        },
+        readonly: {
+            true: { cell: 'bg-surface-subtle cursor-default' }
+        },
+        // Declared BEFORE `error` so the error tone wins the message-color bucket
+        // in every call shape — `{ error: true }` alone must read red.
+        messageType: {
+            error: { message: 'text-danger' },
+            helper: { message: 'text-text-tertiary' }
+        },
+        error: {
+            true: {
+                cell: 'border-danger focus-visible:border-danger focus-visible:ring-danger/20',
+                message: 'text-danger'
+            }
+        },
+        required: {
+            true: { label: "after:content-['*'] after:ml-1 after:text-danger" }
+        }
+    },
+    compoundVariants: [
+        // Ghost keeps a transparent border at rest — even under an intent. The error
+        // state drops this so validation feedback (border-danger) stays visible.
+        {
+            variant: 'ghost',
+            error: false,
+            class: { cell: 'border-transparent' }
+        }
+    ],
+    defaultVariants: {
+        tier: 'modify',
+        variant: 'outlined',
+        size: 'md',
+        intent: 'default',
+        disabled: false,
+        readonly: false,
+        error: false,
+        required: false,
+        messageType: 'helper'
+    }
+});