@hjmds/design-contracts 0.8.2

package/dist/number-field.js

@@ -0,0 +1,247 @@
+import { fieldFrameContract, focusIndicatorContract, formSupportContract, } from "./component-contracts.js";
+import { control, opacity, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const numericRangeDefaults = {
+    step: 1,
+};
+export function assertFiniteNumber(value, field) {
+    if (typeof value !== "number" || Number.isNaN(value) || !Number.isFinite(value)) {
+        throw new TypeError(`${field} must be a finite number`);
+    }
+}
+export function validateNumericRangeConfig(config) {
+    assertFiniteNumber(config.min, "min");
+    assertFiniteNumber(config.max, "max");
+    if (config.min >= config.max) {
+        throw new RangeError("min must be less than max");
+    }
+    const step = config.step ?? numericRangeDefaults.step;
+    assertFiniteNumber(step, "step");
+    if (step <= 0) {
+        throw new RangeError("step must be greater than 0");
+    }
+    if (step > config.max - config.min) {
+        throw new RangeError("step must not exceed the min–max span");
+    }
+}
+/** Number of decimal digits a finite numeric boundary carries. */
+function decimalPrecision(value) {
+    const [coefficient = "", exponentText] = value.toString().toLowerCase().split("e");
+    const dotIndex = coefficient.indexOf(".");
+    const fractionDigits = dotIndex === -1 ? 0 : coefficient.length - dotIndex - 1;
+    const exponent = exponentText === undefined ? 0 : Number(exponentText);
+    return Math.max(0, fractionDigits - exponent);
+}
+/**
+ * A step grid is anchored at `min`, so its exact decimal precision comes from
+ * both the origin and the increment. Looking only at `step` turns the valid
+ * sequence 0.05, 0.15, 0.25… into 0.1, 0.2, 0.3… after the first operation.
+ */
+function roundToStepGridPrecision(value, min, step) {
+    const decimals = Math.max(decimalPrecision(min), decimalPrecision(step));
+    if (decimals === 0)
+        return Math.round(value);
+    const shift = (number, places) => {
+        const [coefficient = "0", exponentText] = number.toString().toLowerCase().split("e");
+        const exponent = exponentText === undefined ? 0 : Number(exponentText);
+        return Number(`${coefficient}e${exponent + places}`);
+    };
+    return shift(Math.round(shift(value, decimals)), -decimals);
+}
+export function clampToRange(value, config) {
+    validateNumericRangeConfig(config);
+    assertFiniteNumber(value, "value");
+    return Math.min(config.max, Math.max(config.min, value));
+}
+/** Snaps to the nearest step from `min`, then clamps into [min, max]. */
+export function snapToStep(value, config) {
+    validateNumericRangeConfig(config);
+    assertFiniteNumber(value, "value");
+    const step = config.step ?? numericRangeDefaults.step;
+    const steps = Math.round((value - config.min) / step);
+    const snapped = roundToStepGridPrecision(config.min + steps * step, config.min, step);
+    return clampToRange(snapped, config);
+}
+/** Move to the next valid grid boundary in the requested direction. */
+export function stepNumericValue(value, config, direction) {
+    const snapped = snapToStep(value, config);
+    if (direction === "increment" && snapped > value)
+        return snapped;
+    if (direction === "decrement" && snapped < value)
+        return snapped;
+    const step = config.step ?? numericRangeDefaults.step;
+    const delta = direction === "increment" ? step : -step;
+    return snapToStep(value + delta, config);
+}
+/**
+ * Parses the renderer's editable text without guessing at locale, currency,
+ * or unit formatting. Empty text is a first-class `null` value; `undefined`
+ * means the draft is not a complete finite decimal number yet.
+ *
+ * Exponent notation is accepted because `String(number)` may produce it for
+ * very small or large finite values. Renderers keep incomplete drafts such as
+ * `-` or `1e` locally and only commit once this parser succeeds.
+ */
+export function parseNumberFieldInput(input) {
+    const normalized = input.trim();
+    if (normalized.length === 0)
+        return null;
+    if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(normalized)) {
+        return undefined;
+    }
+    const value = Number(normalized);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Turns an editable draft into a model value at blur/submit boundaries.
+ * Direct input is clamped and snapped with the same range math used by the
+ * steppers and Slider. Invalid/incomplete text remains `undefined`, allowing a
+ * renderer to restore the last committed value without inventing an error.
+ */
+export function commitNumberFieldInput(input, config) {
+    validateNumericRangeConfig(config);
+    const parsed = parseNumberFieldInput(input);
+    if (parsed === undefined || parsed === null)
+        return parsed;
+    return snapToStep(parsed, config);
+}
+export function validateNumberFieldDescriptor(descriptor) {
+    validateNumericRangeConfig(descriptor);
+    if (descriptor.value !== null) {
+        assertFiniteNumber(descriptor.value, "value");
+        if (descriptor.value < descriptor.min || descriptor.value > descriptor.max) {
+            throw new RangeError("NumberField value must be within min and max");
+        }
+    }
+}
+export function resolveNumberFieldDescriptor(descriptor) {
+    validateNumberFieldDescriptor(descriptor);
+    return { ...descriptor, step: descriptor.step ?? numericRangeDefaults.step };
+}
+/** Empty has no boundary yet, so neither stepper direction is disabled. */
+export function resolveNumberFieldStepperState(descriptor) {
+    validateNumberFieldDescriptor(descriptor);
+    if (descriptor.value === null) {
+        return { incrementDisabled: false, decrementDisabled: false };
+    }
+    return {
+        incrementDisabled: descriptor.value >= descriptor.max,
+        decrementDisabled: descriptor.value <= descriptor.min,
+    };
+}
+/** Resolve stepper availability from the visible draft, falling back safely. */
+export function resolveNumberFieldInputStepperState(input, descriptor) {
+    validateNumberFieldDescriptor(descriptor);
+    const parsed = parseNumberFieldInput(input);
+    if (parsed === undefined)
+        return resolveNumberFieldStepperState(descriptor);
+    if (parsed === null) {
+        return resolveNumberFieldStepperState({ ...descriptor, value: null });
+    }
+    return resolveNumberFieldStepperState({
+        ...descriptor,
+        value: clampToRange(parsed, descriptor),
+    });
+}
+/** Stepping from empty lands on the boundary you are moving toward. */
+export function stepNumberFieldValue(descriptor, direction) {
+    validateNumberFieldDescriptor(descriptor);
+    if (descriptor.value === null) {
+        return direction === "increment" ? descriptor.min : descriptor.max;
+    }
+    return stepNumericValue(descriptor.value, descriptor, direction);
+}
+/**
+ * Resolves a step action from the editable draft without first snapping and
+ * then stepping a second time. Off-grid drafts move to the next valid boundary
+ * in the requested direction; invalid drafts fall back to the committed model.
+ */
+export function stepNumberFieldInput(input, descriptor, direction) {
+    validateNumberFieldDescriptor(descriptor);
+    const parsed = parseNumberFieldInput(input);
+    if (parsed === undefined)
+        return stepNumberFieldValue(descriptor, direction);
+    if (parsed === null) {
+        return stepNumberFieldValue({ ...descriptor, value: null }, direction);
+    }
+    return stepNumericValue(parsed, descriptor, direction);
+}
+/**
+ * Reuses the Field frame (`fieldFrameContract`) and form support copy
+ * (`formSupportContract`) verbatim — a second field frame would drift from
+ * Field the first time either one's border or height changes.
+ */
+export const numberFieldRecipe = {
+    slots: [
+        "root",
+        "frame",
+        "input",
+        "decrement",
+        "increment",
+        "description",
+        "error",
+    ],
+    defaults: { size: "medium" },
+    frame: fieldFrameContract,
+    support: formSupportContract,
+    sizes: {
+        medium: {
+            minHeight: fieldFrameContract.minHeight,
+            paddingHorizontal: fieldFrameContract.paddingHorizontal,
+            textVariant: "body",
+            stepperDiameter: control.minTouchTarget,
+        },
+        large: {
+            minHeight: control.buttonHeight.large,
+            paddingHorizontal: spacing.lg,
+            textVariant: "bodyLarge",
+            stepperDiameter: control.minTouchTarget,
+        },
+    },
+    value: {
+        color: semanticColors.content.body,
+        numericVariant: "tabular",
+    },
+    stepper: {
+        color: semanticColors.content.secondary,
+        minTarget: control.minTouchTarget,
+    },
+    states: {
+        focus: focusIndicatorContract,
+        invalidBorder: semanticColors.border.danger,
+        disabledOpacity: opacity.disabled,
+    },
+};
+/**
+ * Held-repeat on the stepper buttons is deliberately not part of this
+ * contract: no product using NumberField has measured demand for press-and-
+ * hold, and adding it now would mean guessing at a repeat-rate/acceleration
+ * curve nobody has validated. A single activation per press only.
+ */
+export const numberFieldBehavior = {
+    controlled: ["value", "defaultValue", "onValueChange"],
+    stateAxes: {
+        availability: ["enabled", "disabled", "readOnly"],
+        value: ["empty", "filled"],
+        validation: ["valid", "invalid"],
+    },
+    web: {
+        roles: ["spinbutton"],
+        keyboard: ["Tab", "ArrowUp", "ArrowDown"],
+        focus: "native",
+    },
+    native: {
+        roles: ["text", "button"],
+        states: ["disabled"],
+        actions: ["focus", "setText", "increment", "decrement"],
+    },
+    scenarios: [
+        "value-and-range-are-independent-controlled-inputs",
+        "stepper-buttons-disable-at-min-and-max",
+        "empty-disables-neither-stepper-direction",
+        "keyboard-arrow-up-down-step-like-the-stepper-buttons",
+        "invalid-is-a-numberfield-only-axis-independent-of-range",
+        "held-repeat-is-not-part-of-the-contract",
+    ],
+};
+//# sourceMappingURL=number-field.js.map

package/dist/number-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"number-field.js","sourceRoot":"","sources":["../src/number-field.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { BehaviorContract } from \"./behaviors.js\";\nimport {\n  fieldFrameContract,\n  focusIndicatorContract,\n  formSupportContract,\n} from \"./component-contracts.js\";\nimport { control, opacity, spacing, type TextVariant } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Shared by NumberField and Slider: both solve \"pick a number within a range.\"\n * Keeping min/max/step/value judgment in one place keeps the two components\n * from drifting into two different meanings of the same numeric domain.\n */\nexport type NumericRangeConfig = Readonly<{\n  min: number;\n  max: number;\n  step?: number;\n}>;\n\nexport const numericRangeDefaults = {\n  step: 1,\n} as const satisfies Readonly<{ step: number }>;\n\nexport function assertFiniteNumber(value: number, field: string): void {\n  if (typeof value !== \"number\" || Number.isNaN(value) || !Number.isFinite(value)) {\n    throw new TypeError(`${field} must be a finite number`);\n  }\n}\n\nexport function validateNumericRangeConfig(config: NumericRangeConfig): void {\n  assertFiniteNumber(config.min, \"min\");\n  assertFiniteNumber(config.max, \"max\");\n  if (config.min >= config.max) {\n    throw new RangeError(\"min must be less than max\");\n  }\n  const step = config.step ?? numericRangeDefaults.step;\n  assertFiniteNumber(step, \"step\");\n  if (step <= 0) {\n    throw new RangeError(\"step must be greater than 0\");\n  }\n  if (step > config.max - config.min) {\n    throw new RangeError(\"step must not exceed the min–max span\");\n  }\n}\n\n/** Number of decimal digits a finite numeric boundary carries. */\nfunction decimalPrecision(value: number): number {\n  const [coefficient = \"\", exponentText] = value.toString().toLowerCase().split(\"e\");\n  const dotIndex = coefficient.indexOf(\".\");\n  const fractionDigits = dotIndex === -1 ? 0 : coefficient.length - dotIndex - 1;\n  const exponent = exponentText === undefined ? 0 : Number(exponentText);\n  return Math.max(0, fractionDigits - exponent);\n}\n\n/**\n * A step grid is anchored at `min`, so its exact decimal precision comes from\n * both the origin and the increment. Looking only at `step` turns the valid\n * sequence 0.05, 0.15, 0.25… into 0.1, 0.2, 0.3… after the first operation.\n */\nfunction roundToStepGridPrecision(value: number, min: number, step: number): number {\n  const decimals = Math.max(decimalPrecision(min), decimalPrecision(step));\n  if (decimals === 0) return Math.round(value);\n  const shift = (number: number, places: number): number => {\n    const [coefficient = \"0\", exponentText] = number.toString().toLowerCase().split(\"e\");\n    const exponent = exponentText === undefined ? 0 : Number(exponentText);\n    return Number(`${coefficient}e${exponent + places}`);\n  };\n  return shift(Math.round(shift(value, decimals)), -decimals);\n}\n\nexport function clampToRange(value: number, config: NumericRangeConfig): number {\n  validateNumericRangeConfig(config);\n  assertFiniteNumber(value, \"value\");\n  return Math.min(config.max, Math.max(config.min, value));\n}\n\n/** Snaps to the nearest step from `min`, then clamps into [min, max]. */\nexport function snapToStep(value: number, config: NumericRangeConfig): number {\n  validateNumericRangeConfig(config);\n  assertFiniteNumber(value, \"value\");\n  const step = config.step ?? numericRangeDefaults.step;\n  const steps = Math.round((value - config.min) / step);\n  const snapped = roundToStepGridPrecision(config.min + steps * step, config.min, step);\n  return clampToRange(snapped, config);\n}\n\n/** Move to the next valid grid boundary in the requested direction. */\nexport function stepNumericValue(\n  value: number,\n  config: NumericRangeConfig,\n  direction: \"increment\" | \"decrement\",\n): number {\n  const snapped = snapToStep(value, config);\n  if (direction === \"increment\" && snapped > value) return snapped;\n  if (direction === \"decrement\" && snapped < value) return snapped;\n  const step = config.step ?? numericRangeDefaults.step;\n  const delta = direction === \"increment\" ? step : -step;\n  return snapToStep(value + delta, config);\n}\n\n/**\n * `null` means no value has been entered yet — distinct from any in-range\n * number, including `min`. Products decide whether empty is allowed to submit.\n */\nexport type NumberFieldValue = number | null;\n\n/**\n * Parses the renderer's editable text without guessing at locale, currency,\n * or unit formatting. Empty text is a first-class `null` value; `undefined`\n * means the draft is not a complete finite decimal number yet.\n *\n * Exponent notation is accepted because `String(number)` may produce it for\n * very small or large finite values. Renderers keep incomplete drafts such as\n * `-` or `1e` locally and only commit once this parser succeeds.\n */\nexport function parseNumberFieldInput(input: string): NumberFieldValue | undefined {\n  const normalized = input.trim();\n  if (normalized.length === 0) return null;\n  if (!/^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?$/.test(normalized)) {\n    return undefined;\n  }\n  const value = Number(normalized);\n  return Number.isFinite(value) ? value : undefined;\n}\n\n/**\n * Turns an editable draft into a model value at blur/submit boundaries.\n * Direct input is clamped and snapped with the same range math used by the\n * steppers and Slider. Invalid/incomplete text remains `undefined`, allowing a\n * renderer to restore the last committed value without inventing an error.\n */\nexport function commitNumberFieldInput(\n  input: string,\n  config: NumericRangeConfig,\n): NumberFieldValue | undefined {\n  validateNumericRangeConfig(config);\n  const parsed = parseNumberFieldInput(input);\n  if (parsed === undefined || parsed === null) return parsed;\n  return snapToStep(parsed, config);\n}\n\nexport type NumberFieldDescriptor = Readonly<{\n  value: NumberFieldValue;\n  min: number;\n  max: number;\n  step?: number;\n}>;\n\nexport type ResolvedNumberFieldDescriptor = Omit<NumberFieldDescriptor, \"step\"> &\n  Readonly<{ step: number }>;\n\nexport function validateNumberFieldDescriptor(descriptor: NumberFieldDescriptor): void {\n  validateNumericRangeConfig(descriptor);\n  if (descriptor.value !== null) {\n    assertFiniteNumber(descriptor.value, \"value\");\n    if (descriptor.value < descriptor.min || descriptor.value > descriptor.max) {\n      throw new RangeError(\"NumberField value must be within min and max\");\n    }\n  }\n}\n\nexport function resolveNumberFieldDescriptor(\n  descriptor: NumberFieldDescriptor,\n): ResolvedNumberFieldDescriptor {\n  validateNumberFieldDescriptor(descriptor);\n  return { ...descriptor, step: descriptor.step ?? numericRangeDefaults.step };\n}\n\nexport type NumberFieldStepperState = Readonly<{\n  incrementDisabled: boolean;\n  decrementDisabled: boolean;\n}>;\n\n/** Empty has no boundary yet, so neither stepper direction is disabled. */\nexport function resolveNumberFieldStepperState(\n  descriptor: NumberFieldDescriptor,\n): NumberFieldStepperState {\n  validateNumberFieldDescriptor(descriptor);\n  if (descriptor.value === null) {\n    return { incrementDisabled: false, decrementDisabled: false };\n  }\n  return {\n    incrementDisabled: descriptor.value >= descriptor.max,\n    decrementDisabled: descriptor.value <= descriptor.min,\n  };\n}\n\n/** Resolve stepper availability from the visible draft, falling back safely. */\nexport function resolveNumberFieldInputStepperState(\n  input: string,\n  descriptor: NumberFieldDescriptor,\n): NumberFieldStepperState {\n  validateNumberFieldDescriptor(descriptor);\n  const parsed = parseNumberFieldInput(input);\n  if (parsed === undefined) return resolveNumberFieldStepperState(descriptor);\n  if (parsed === null) {\n    return resolveNumberFieldStepperState({ ...descriptor, value: null });\n  }\n  return resolveNumberFieldStepperState({\n    ...descriptor,\n    value: clampToRange(parsed, descriptor),\n  });\n}\n\n/** Stepping from empty lands on the boundary you are moving toward. */\nexport function stepNumberFieldValue(\n  descriptor: NumberFieldDescriptor,\n  direction: \"increment\" | \"decrement\",\n): number {\n  validateNumberFieldDescriptor(descriptor);\n  if (descriptor.value === null) {\n    return direction === \"increment\" ? descriptor.min : descriptor.max;\n  }\n  return stepNumericValue(descriptor.value, descriptor, direction);\n}\n\n/**\n * Resolves a step action from the editable draft without first snapping and\n * then stepping a second time. Off-grid drafts move to the next valid boundary\n * in the requested direction; invalid drafts fall back to the committed model.\n */\nexport function stepNumberFieldInput(\n  input: string,\n  descriptor: NumberFieldDescriptor,\n  direction: \"increment\" | \"decrement\",\n): number {\n  validateNumberFieldDescriptor(descriptor);\n  const parsed = parseNumberFieldInput(input);\n  if (parsed === undefined) return stepNumberFieldValue(descriptor, direction);\n  if (parsed === null) {\n    return stepNumberFieldValue({ ...descriptor, value: null }, direction);\n  }\n  return stepNumericValue(parsed, descriptor, direction);\n}\n\nexport type NumberFieldSize = \"medium\" | \"large\";\n\n/**\n * Reuses the Field frame (`fieldFrameContract`) and form support copy\n * (`formSupportContract`) verbatim — a second field frame would drift from\n * Field the first time either one's border or height changes.\n */\nexport const numberFieldRecipe = {\n  slots: [\n    \"root\",\n    \"frame\",\n    \"input\",\n    \"decrement\",\n    \"increment\",\n    \"description\",\n    \"error\",\n  ] as const,\n  defaults: { size: \"medium\" },\n  frame: fieldFrameContract,\n  support: formSupportContract,\n  sizes: {\n    medium: {\n      minHeight: fieldFrameContract.minHeight,\n      paddingHorizontal: fieldFrameContract.paddingHorizontal,\n      textVariant: \"body\",\n      stepperDiameter: control.minTouchTarget,\n    },\n    large: {\n      minHeight: control.buttonHeight.large,\n      paddingHorizontal: spacing.lg,\n      textVariant: \"bodyLarge\",\n      stepperDiameter: control.minTouchTarget,\n    },\n  },\n  value: {\n    color: semanticColors.content.body,\n    numericVariant: \"tabular\",\n  },\n  stepper: {\n    color: semanticColors.content.secondary,\n    minTarget: control.minTouchTarget,\n  },\n  states: {\n    focus: focusIndicatorContract,\n    invalidBorder: semanticColors.border.danger,\n    disabledOpacity: opacity.disabled,\n  },\n} as const satisfies {\n  slots: readonly [\n    \"root\",\n    \"frame\",\n    \"input\",\n    \"decrement\",\n    \"increment\",\n    \"description\",\n    \"error\",\n  ];\n  defaults: { size: NumberFieldSize };\n  frame: typeof fieldFrameContract;\n  support: typeof formSupportContract;\n  sizes: Record<\n    NumberFieldSize,\n    {\n      minHeight: number;\n      paddingHorizontal: number;\n      textVariant: TextVariant;\n      stepperDiameter: number;\n    }\n  >;\n  value: { color: ColorReference; numericVariant: \"tabular\" };\n  stepper: { color: ColorReference; minTarget: number };\n  states: {\n    focus: typeof focusIndicatorContract;\n    invalidBorder: ColorReference;\n    disabledOpacity: number;\n  };\n};\n\n/**\n * Held-repeat on the stepper buttons is deliberately not part of this\n * contract: no product using NumberField has measured demand for press-and-\n * hold, and adding it now would mean guessing at a repeat-rate/acceleration\n * curve nobody has validated. A single activation per press only.\n */\nexport const numberFieldBehavior = {\n  controlled: [\"value\", \"defaultValue\", \"onValueChange\"],\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\", \"readOnly\"],\n    value: [\"empty\", \"filled\"],\n    validation: [\"valid\", \"invalid\"],\n  },\n  web: {\n    roles: [\"spinbutton\"],\n    keyboard: [\"Tab\", \"ArrowUp\", \"ArrowDown\"],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"text\", \"button\"],\n    states: [\"disabled\"],\n    actions: [\"focus\", \"setText\", \"increment\", \"decrement\"],\n  },\n  scenarios: [\n    \"value-and-range-are-independent-controlled-inputs\",\n    \"stepper-buttons-disable-at-min-and-max\",\n    \"empty-disables-neither-stepper-direction\",\n    \"keyboard-arrow-up-down-step-like-the-stepper-buttons\",\n    \"invalid-is-a-numberfield-only-axis-independent-of-range\",\n    \"held-repeat-is-not-part-of-the-contract\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/otp-field.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Numeric-only, matching the domain the brief describes (인증번호). An
+ * alphanumeric OTP is out of scope until a real product needs one — adding
+ * a configurable character set now would mean guessing at a pattern nobody
+ * has validated. See docs/otp-field.md.
+ */
+export type OtpFieldDescriptor = Readonly<{
+    /** Number of visible slots. At least two — a single slot is not the multi-slot problem this component solves (Steps applies the same floor to its own step count for the same reason). */
+    length: number;
+    /** The one logical value, always dense — index i is filled iff i < value.length. Never sparse; see docs/otp-field.md. */
+    value: string;
+}>;
+export declare function validateOtpFieldDescriptor(descriptor: OtpFieldDescriptor): void;
+/** One entry per slot: the digit at that position, or "" for an unfilled slot. Always dense — no gaps. */
+export declare function getOtpFieldSlotValues(descriptor: OtpFieldDescriptor): readonly string[];
+export type ResolvedOtpFieldDescriptor = OtpFieldDescriptor & Readonly<{
+    slots: readonly string[];
+    complete: boolean;
+}>;
+export declare function resolveOtpFieldDescriptor(descriptor: OtpFieldDescriptor): ResolvedOtpFieldDescriptor;
+/**
+ * The single hard accessibility judgment this contract makes: OtpField is
+ * ONE focusable, one accessible-name-and-value text control, not N separate
+ * focusable slots. N separate real inputs is the well-documented
+ * accessibility anti-pattern the brief names directly — a screen reader
+ * announcing "slot 3 of 6" tells the user nothing about what they are
+ * entering. The N visible boxes are a decorative rendering of one control's
+ * characters (`getOtpFieldSlotValues`), the same way a styled `<input>` with
+ * letter-spacing can look segmented while remaining one field. See
+ * docs/otp-field.md.
+ *
+ * Because there is one real control, typing, backspacing, and pasting
+ * (anywhere, including mid-string) are the platform's own native text
+ * editing — insertion, deletion, and paste-over-a-selection are not
+ * reimplemented here. The only judgment HJM owns is what happens to the
+ * resulting raw string: keep digits only, never exceed `length`. This is
+ * intentionally the one function this module needs for every edit path.
+ */
+export declare function resolveOtpFieldValue(length: number, rawText: string): string;
+export type OtpFieldSize = "medium" | "large";
+/**
+ * The `slot` boxes reuse Field's own border/focus/invalid colors
+ * (`fieldFrameContract`) instead of inventing a new palette — each is a
+ * small Field-frame look-alike, not a new visual language.
+ */
+export declare const otpFieldRecipe: {
+    readonly slots: readonly ["root", "input", "slot", "description", "error"];
+    readonly defaults: {
+        readonly size: "medium";
+    };
+    readonly support: {
+        readonly label: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly textVariant: "body";
+            readonly fontWeight: "600";
+        };
+        readonly hint: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textMuted";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly error: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "danger";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly gap: 8;
+    };
+    readonly sizes: {
+        readonly medium: {
+            readonly slotSize: 44;
+            readonly gap: 8;
+            readonly textVariant: "title";
+        };
+        readonly large: {
+            readonly slotSize: 52;
+            readonly gap: 12;
+            readonly textVariant: "titleLarge";
+        };
+    };
+    readonly slot: {
+        readonly border: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly focusBorder: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly invalidBorder: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+        readonly filledBorder: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly radius: "md";
+        readonly borderWidth: 1;
+        readonly content: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly disabledOpacity: 0.5;
+    };
+};
+export declare const otpFieldBehavior: {
+    readonly controlled: readonly ["value", "defaultValue", "onValueChange"];
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled", "readOnly", "busy"];
+        readonly value: readonly ["empty", "filled"];
+        readonly validation: readonly ["valid", "invalid"];
+    };
+    readonly web: {
+        readonly roles: readonly ["textbox"];
+        readonly keyboard: readonly ["Tab", "ArrowLeft", "ArrowRight", "Home", "End"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["text"];
+        readonly states: readonly ["disabled", "busy"];
+        readonly actions: readonly ["focus", "setText"];
+    };
+    readonly scenarios: readonly ["one-accessible-name-and-value-for-the-whole-field-never-per-slot-announcement", "one-tab-stop-native-text-editing-owns-typing-backspacing-and-paste", "paste-anywhere-in-the-value-is-sanitized-to-digits-and-clamped-to-length", "non-digit-characters-are-stripped-not-rejected-outright", "resolveOtpFieldValue-truncates-typed-or-pasted-overflow-instead-of-throwing", "a-too-long-committed-descriptor-still-throws-as-malformed-state", "alphanumeric-otp-is-out-of-scope-until-a-real-product-need-exists"];
+};
+//# sourceMappingURL=otp-field.d.ts.map

package/dist/otp-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otp-field.d.ts","sourceRoot":"","sources":["../src/otp-field.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,0LAA0L;IAC1L,MAAM,EAAE,MAAM,CAAC;IACf,yHAAyH;IACzH,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAU/E;AAED,0GAA0G;AAC1G,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,kBAAkB,GAC7B,SAAS,MAAM,EAAE,CAGnB;AAED,MAAM,MAAM,0BAA0B,GAAG,kBAAkB,GACzD,QAAQ,CAAC;IACP,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC,CAAC;AAEL,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,kBAAkB,GAC7B,0BAA0B,CAO5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAQ5E;AAED,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkD1B,CAAC;AAEF,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;CA0BQ,CAAC"}

package/dist/otp-field.js

@@ -0,0 +1,117 @@
+import { fieldFrameContract, focusIndicatorContract, formSupportContract, } from "./component-contracts.js";
+import { control, opacity, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export function validateOtpFieldDescriptor(descriptor) {
+    if (!Number.isInteger(descriptor.length) || descriptor.length < 2) {
+        throw new RangeError("OtpField length must be an integer of at least two slots");
+    }
+    if (typeof descriptor.value !== "string" || !/^\d*$/.test(descriptor.value)) {
+        throw new TypeError("OtpField value must be a string of digits only");
+    }
+    if (descriptor.value.length > descriptor.length) {
+        throw new RangeError("OtpField value must not be longer than length");
+    }
+}
+/** One entry per slot: the digit at that position, or "" for an unfilled slot. Always dense — no gaps. */
+export function getOtpFieldSlotValues(descriptor) {
+    validateOtpFieldDescriptor(descriptor);
+    return Array.from({ length: descriptor.length }, (_, index) => descriptor.value[index] ?? "");
+}
+export function resolveOtpFieldDescriptor(descriptor) {
+    validateOtpFieldDescriptor(descriptor);
+    return {
+        ...descriptor,
+        slots: getOtpFieldSlotValues(descriptor),
+        complete: descriptor.value.length === descriptor.length,
+    };
+}
+/**
+ * The single hard accessibility judgment this contract makes: OtpField is
+ * ONE focusable, one accessible-name-and-value text control, not N separate
+ * focusable slots. N separate real inputs is the well-documented
+ * accessibility anti-pattern the brief names directly — a screen reader
+ * announcing "slot 3 of 6" tells the user nothing about what they are
+ * entering. The N visible boxes are a decorative rendering of one control's
+ * characters (`getOtpFieldSlotValues`), the same way a styled `<input>` with
+ * letter-spacing can look segmented while remaining one field. See
+ * docs/otp-field.md.
+ *
+ * Because there is one real control, typing, backspacing, and pasting
+ * (anywhere, including mid-string) are the platform's own native text
+ * editing — insertion, deletion, and paste-over-a-selection are not
+ * reimplemented here. The only judgment HJM owns is what happens to the
+ * resulting raw string: keep digits only, never exceed `length`. This is
+ * intentionally the one function this module needs for every edit path.
+ */
+export function resolveOtpFieldValue(length, rawText) {
+    if (!Number.isInteger(length) || length < 2) {
+        throw new RangeError("OtpField length must be an integer of at least two slots");
+    }
+    if (typeof rawText !== "string") {
+        throw new TypeError("OtpField rawText must be a string");
+    }
+    return rawText.replace(/\D/g, "").slice(0, length);
+}
+/**
+ * The `slot` boxes reuse Field's own border/focus/invalid colors
+ * (`fieldFrameContract`) instead of inventing a new palette — each is a
+ * small Field-frame look-alike, not a new visual language.
+ */
+export const otpFieldRecipe = {
+    slots: ["root", "input", "slot", "description", "error"],
+    defaults: { size: "medium" },
+    support: formSupportContract,
+    sizes: {
+        medium: {
+            slotSize: control.minTouchTarget,
+            gap: spacing.xs,
+            textVariant: "title",
+        },
+        large: {
+            slotSize: control.buttonHeight.large,
+            gap: spacing.sm,
+            textVariant: "titleLarge",
+        },
+    },
+    slot: {
+        border: fieldFrameContract.border,
+        focusBorder: fieldFrameContract.focusBorder,
+        invalidBorder: fieldFrameContract.invalidBorder,
+        filledBorder: semanticColors.content.brand,
+        radius: fieldFrameContract.radius,
+        borderWidth: fieldFrameContract.borderWidth,
+        content: semanticColors.content.primary,
+    },
+    states: {
+        focus: focusIndicatorContract,
+        disabledOpacity: opacity.disabled,
+    },
+};
+export const otpFieldBehavior = {
+    controlled: ["value", "defaultValue", "onValueChange"],
+    stateAxes: {
+        availability: ["enabled", "disabled", "readOnly", "busy"],
+        value: ["empty", "filled"],
+        validation: ["valid", "invalid"],
+    },
+    web: {
+        roles: ["textbox"],
+        keyboard: ["Tab", "ArrowLeft", "ArrowRight", "Home", "End"],
+        focus: "native",
+    },
+    native: {
+        roles: ["text"],
+        states: ["disabled", "busy"],
+        actions: ["focus", "setText"],
+    },
+    scenarios: [
+        "one-accessible-name-and-value-for-the-whole-field-never-per-slot-announcement",
+        "one-tab-stop-native-text-editing-owns-typing-backspacing-and-paste",
+        "paste-anywhere-in-the-value-is-sanitized-to-digits-and-clamped-to-length",
+        "non-digit-characters-are-stripped-not-rejected-outright",
+        "resolveOtpFieldValue-truncates-typed-or-pasted-overflow-instead-of-throwing",
+        "a-too-long-committed-descriptor-still-throws-as-malformed-state",
+        "alphanumeric-otp-is-out-of-scope-until-a-real-product-need-exists",
+    ],
+};
+//# sourceMappingURL=otp-field.js.map

package/dist/otp-field.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otp-field.js","sourceRoot":"","sources":["../src/otp-field.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport {\n  fieldFrameContract,\n  focusIndicatorContract,\n  formSupportContract,\n} from \"./component-contracts.js\";\nimport { control, opacity, spacing, type TextVariant } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Numeric-only, matching the domain the brief describes (인증번호). An\n * alphanumeric OTP is out of scope until a real product needs one — adding\n * a configurable character set now would mean guessing at a pattern nobody\n * has validated. See docs/otp-field.md.\n */\nexport type OtpFieldDescriptor = Readonly<{\n  /** Number of visible slots. At least two — a single slot is not the multi-slot problem this component solves (Steps applies the same floor to its own step count for the same reason). */\n  length: number;\n  /** The one logical value, always dense — index i is filled iff i < value.length. Never sparse; see docs/otp-field.md. */\n  value: string;\n}>;\n\nexport function validateOtpFieldDescriptor(descriptor: OtpFieldDescriptor): void {\n  if (!Number.isInteger(descriptor.length) || descriptor.length < 2) {\n    throw new RangeError(\"OtpField length must be an integer of at least two slots\");\n  }\n  if (typeof descriptor.value !== \"string\" || !/^\\d*$/.test(descriptor.value)) {\n    throw new TypeError(\"OtpField value must be a string of digits only\");\n  }\n  if (descriptor.value.length > descriptor.length) {\n    throw new RangeError(\"OtpField value must not be longer than length\");\n  }\n}\n\n/** One entry per slot: the digit at that position, or \"\" for an unfilled slot. Always dense — no gaps. */\nexport function getOtpFieldSlotValues(\n  descriptor: OtpFieldDescriptor,\n): readonly string[] {\n  validateOtpFieldDescriptor(descriptor);\n  return Array.from({ length: descriptor.length }, (_, index) => descriptor.value[index] ?? \"\");\n}\n\nexport type ResolvedOtpFieldDescriptor = OtpFieldDescriptor &\n  Readonly<{\n    slots: readonly string[];\n    complete: boolean;\n  }>;\n\nexport function resolveOtpFieldDescriptor(\n  descriptor: OtpFieldDescriptor,\n): ResolvedOtpFieldDescriptor {\n  validateOtpFieldDescriptor(descriptor);\n  return {\n    ...descriptor,\n    slots: getOtpFieldSlotValues(descriptor),\n    complete: descriptor.value.length === descriptor.length,\n  };\n}\n\n/**\n * The single hard accessibility judgment this contract makes: OtpField is\n * ONE focusable, one accessible-name-and-value text control, not N separate\n * focusable slots. N separate real inputs is the well-documented\n * accessibility anti-pattern the brief names directly — a screen reader\n * announcing \"slot 3 of 6\" tells the user nothing about what they are\n * entering. The N visible boxes are a decorative rendering of one control's\n * characters (`getOtpFieldSlotValues`), the same way a styled `<input>` with\n * letter-spacing can look segmented while remaining one field. See\n * docs/otp-field.md.\n *\n * Because there is one real control, typing, backspacing, and pasting\n * (anywhere, including mid-string) are the platform's own native text\n * editing — insertion, deletion, and paste-over-a-selection are not\n * reimplemented here. The only judgment HJM owns is what happens to the\n * resulting raw string: keep digits only, never exceed `length`. This is\n * intentionally the one function this module needs for every edit path.\n */\nexport function resolveOtpFieldValue(length: number, rawText: string): string {\n  if (!Number.isInteger(length) || length < 2) {\n    throw new RangeError(\"OtpField length must be an integer of at least two slots\");\n  }\n  if (typeof rawText !== \"string\") {\n    throw new TypeError(\"OtpField rawText must be a string\");\n  }\n  return rawText.replace(/\\D/g, \"\").slice(0, length);\n}\n\nexport type OtpFieldSize = \"medium\" | \"large\";\n\n/**\n * The `slot` boxes reuse Field's own border/focus/invalid colors\n * (`fieldFrameContract`) instead of inventing a new palette — each is a\n * small Field-frame look-alike, not a new visual language.\n */\nexport const otpFieldRecipe = {\n  slots: [\"root\", \"input\", \"slot\", \"description\", \"error\"] as const,\n  defaults: { size: \"medium\" },\n  support: formSupportContract,\n  sizes: {\n    medium: {\n      slotSize: control.minTouchTarget,\n      gap: spacing.xs,\n      textVariant: \"title\",\n    },\n    large: {\n      slotSize: control.buttonHeight.large,\n      gap: spacing.sm,\n      textVariant: \"titleLarge\",\n    },\n  },\n  slot: {\n    border: fieldFrameContract.border,\n    focusBorder: fieldFrameContract.focusBorder,\n    invalidBorder: fieldFrameContract.invalidBorder,\n    filledBorder: semanticColors.content.brand,\n    radius: fieldFrameContract.radius,\n    borderWidth: fieldFrameContract.borderWidth,\n    content: semanticColors.content.primary,\n  },\n  states: {\n    focus: focusIndicatorContract,\n    disabledOpacity: opacity.disabled,\n  },\n} as const satisfies {\n  slots: readonly string[];\n  defaults: { size: OtpFieldSize };\n  support: typeof formSupportContract;\n  sizes: Record<\n    OtpFieldSize,\n    { slotSize: number; gap: number; textVariant: TextVariant }\n  >;\n  slot: {\n    border: ColorReference;\n    focusBorder: ColorReference;\n    invalidBorder: ColorReference;\n    filledBorder: ColorReference;\n    radius: typeof fieldFrameContract.radius;\n    borderWidth: number;\n    content: ColorReference;\n  };\n  states: {\n    focus: typeof focusIndicatorContract;\n    disabledOpacity: number;\n  };\n};\n\nexport const otpFieldBehavior = {\n  controlled: [\"value\", \"defaultValue\", \"onValueChange\"],\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\", \"readOnly\", \"busy\"],\n    value: [\"empty\", \"filled\"],\n    validation: [\"valid\", \"invalid\"],\n  },\n  web: {\n    roles: [\"textbox\"],\n    keyboard: [\"Tab\", \"ArrowLeft\", \"ArrowRight\", \"Home\", \"End\"],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"text\"],\n    states: [\"disabled\", \"busy\"],\n    actions: [\"focus\", \"setText\"],\n  },\n  scenarios: [\n    \"one-accessible-name-and-value-for-the-whole-field-never-per-slot-announcement\",\n    \"one-tab-stop-native-text-editing-owns-typing-backspacing-and-paste\",\n    \"paste-anywhere-in-the-value-is-sanitized-to-digits-and-clamped-to-length\",\n    \"non-digit-characters-are-stripped-not-rejected-outright\",\n    \"resolveOtpFieldValue-truncates-typed-or-pasted-overflow-instead-of-throwing\",\n    \"a-too-long-committed-descriptor-still-throws-as-malformed-state\",\n    \"alphanumeric-otp-is-out-of-scope-until-a-real-product-need-exists\",\n  ],\n} as const satisfies BehaviorContract;\n"]}