@hjmds/design-contracts 0.8.2

package/dist/form.js

@@ -0,0 +1,206 @@
+import { spacing } from "./foundations.js";
+function assertCopy(value, field) {
+    if (value.trim().length === 0) {
+        throw new TypeError(`Form ${field} must not be empty`);
+    }
+}
+export function validateFormSubmitSessionOptions(options) {
+    if (typeof options.onSubmit !== "function") {
+        throw new TypeError("Form onSubmit must be a function");
+    }
+    assertCopy(options.fallbackErrorMessage, "fallbackErrorMessage");
+}
+function resolveFailureMessage(options, error) {
+    try {
+        const resolved = options.resolveErrorMessage?.(error)?.trim();
+        return resolved || options.fallbackErrorMessage;
+    }
+    catch {
+        return options.fallbackErrorMessage;
+    }
+}
+/**
+ * Owns submit re-entrancy and exactly-once settlement. Does not own field
+ * values (the caller passes `values` at call time), field-level validation,
+ * or when submission is allowed to start (the product decides that from its
+ * own dirty/valid state before calling `submit`).
+ */
+export function createFormSubmitSession(options) {
+    validateFormSubmitSessionOptions(options);
+    let phase = { status: "idle" };
+    let disposed = false;
+    let interruptCurrentAttempt = null;
+    const listeners = new Set();
+    const notify = () => {
+        for (const listener of listeners)
+            listener();
+    };
+    const transition = (next) => {
+        phase = next;
+        notify();
+    };
+    return {
+        getSnapshot: () => phase,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        submit(values) {
+            if (disposed)
+                throw new Error("Cannot use a disposed Form submit session");
+            if (phase.status === "submitting") {
+                return Promise.resolve({ outcome: "blocked", reason: "already-submitting" });
+            }
+            transition({ status: "submitting" });
+            return new Promise((resolve) => {
+                let settled = false;
+                const settleOnce = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    interruptCurrentAttempt = null;
+                    resolve(outcome);
+                };
+                interruptCurrentAttempt = settleOnce;
+                (async () => {
+                    try {
+                        await options.onSubmit(values);
+                        if (settled)
+                            return;
+                        transition({ status: "succeeded" });
+                        settleOnce({ outcome: "succeeded" });
+                    }
+                    catch (error) {
+                        if (settled)
+                            return;
+                        const message = resolveFailureMessage(options, error);
+                        transition({ status: "failed", message });
+                        settleOnce({ outcome: "failed", message });
+                    }
+                })();
+            });
+        },
+        reset() {
+            if (disposed)
+                return false;
+            if (phase.status === "idle" || phase.status === "submitting")
+                return false;
+            transition({ status: "idle" });
+            return true;
+        },
+        dispose() {
+            if (disposed)
+                return false;
+            disposed = true;
+            interruptCurrentAttempt?.({ outcome: "interrupted" });
+            interruptCurrentAttempt = null;
+            return true;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Submit-failure focus
+// ---------------------------------------------------------------------------
+/**
+ * Form does not register fields or run validation, so it cannot find the
+ * first invalid field on its own. The product supplies its own field render
+ * order and the ids it currently considers invalid (e.g. React Hook Form's
+ * `formState.errors` keys); Form only fixes which one wins the race — first
+ * in render order — so every product answers this the same way.
+ */
+export function validateFormFieldOrder(fieldOrder) {
+    const seen = new Set();
+    fieldOrder.forEach((fieldId, index) => {
+        if (fieldId.trim().length === 0) {
+            throw new TypeError(`Form field id at index ${index} must not be empty`);
+        }
+        if (seen.has(fieldId)) {
+            throw new TypeError(`Duplicate Form field id: ${fieldId}`);
+        }
+        seen.add(fieldId);
+    });
+}
+/**
+ * Web renderers call `.focus()` on the resolved field's control; React Native
+ * renderers move accessibility focus to it (e.g. `AccessibilityInfo.sendAccessibilityEvent`
+ * or a focus-trap ref). Returns `null` when there are no fields yet or none
+ * are invalid, in which case a failed submit has no field to focus and the
+ * form-level error slot below owns the announcement instead.
+ */
+export function resolveFirstInvalidFieldFocusTarget(fieldOrder, invalidFieldIds) {
+    validateFormFieldOrder(fieldOrder);
+    const invalid = invalidFieldIds instanceof Set ? invalidFieldIds : new Set(invalidFieldIds);
+    for (const fieldId of fieldOrder) {
+        if (invalid.has(fieldId))
+            return fieldId;
+    }
+    return null;
+}
+export const formDefaults = {
+    density: "comfortable",
+};
+/**
+ * Anatomy is fixed, not a configurable prop: fields, then the form-level
+ * error, then actions. `field` frame styling (background, border, its own
+ * label/hint/error gap) belongs to `fieldRecipe`; this recipe only sets the
+ * gap *between* one field and the next. `formError` renders as the existing
+ * Notice `tone="danger"` contract — Form fixes only its slot position, it
+ * does not redeclare Notice's colors. `actions` has no dedicated layout here;
+ * composing Button/Stack in that slot is the product's job, same reasoning
+ * the roadmap already applies to Stack.
+ */
+export const formRecipe = {
+    slots: ["root", "field", "formError", "actions"],
+    defaults: formDefaults,
+    density: {
+        compact: { fieldGap: spacing.sm },
+        comfortable: { fieldGap: spacing.lg },
+    },
+    formError: {
+        position: "beforeActions",
+        gap: spacing.sm,
+    },
+};
+// ---------------------------------------------------------------------------
+// Behavior — source for the shared behaviorRegistry wiring
+// ---------------------------------------------------------------------------
+export const formBehaviorDefaults = {
+    /** Reuses Toast's own `normal | high` vocabulary: a blocked submission is `high`/assertive. */
+    errorAnnouncementPriority: "high",
+};
+/**
+ * Kept beside the Form contract as the source value wired by
+ * `behaviorRegistry.form`; this lets the registry reuse the contract without
+ * redeclaring Form's inputs, events, states, or scenarios.
+ */
+export const formBehaviorSpec = {
+    /*
+      값은 제품이 소유하므로 controlled prop이 없다. 대신 renderer가 반드시 배선해야 하는
+      것을 `inputs`/`events`로 선언한다 — 공유 불변식이 "controlled + inputs + events가
+      하나도 없는 behavior는 renderer 테스트가 구동할 대상이 없다"고 요구하고, 그 지적이
+      옳다. 같은 형태(컨트롤러가 상태를 소유하고 renderer가 구동)인 `loadMore`가 이미
+      `controlled: []` + `inputs` + `events`로 선언한 선례를 따른다.
+    */
+    controlled: [],
+    inputs: ["status", "formError", "fieldOrder"],
+    events: ["onSubmit"],
+    defaults: formBehaviorDefaults,
+    stateAxes: {
+        availability: ["enabled", "busy"],
+        content: ["idle", "loading", "error"],
+    },
+    web: { roles: ["alert"], keyboard: ["Tab", "Enter"], focus: "native" },
+    native: { roles: ["alert"], states: ["busy"], actions: ["submit"] },
+    scenarios: [
+        "submitting-blocks-every-concurrent-submit-attempt",
+        "each-submit-attempt-settles-its-result-exactly-once",
+        "failed-submit-returns-to-a-resting-state-that-still-allows-retry",
+        "succeeded-submit-remains-resting-and-allows-resubmission",
+        "dispose-during-submit-settles-the-pending-attempt-as-interrupted",
+        "disposed-session-rejects-further-submit-attempts",
+        "form-level-error-never-carries-a-per-field-message",
+        "first-invalid-field-in-render-order-receives-focus-on-submit-failure",
+        "form-level-error-is-announced-when-no-field-target-exists",
+    ],
+};
+//# sourceMappingURL=form.js.map

package/dist/form.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"form.js","sourceRoot":"","sources":["../src/form.ts"],"names":[],"mappings":"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","sourcesContent":["import { spacing } from \"./foundations.js\";\n\n/**\n * Form owns two things only: the vertical rhythm between already-framed\n * Fields, and the repeatable submit session (idle → submitting →\n * succeeded/failed). Field values, registration, dependencies, validateTrigger\n * policy and Form.List-style repeating groups stay product-owned (React Hook\n * Form or equivalent) — see docs/form.md for the full boundary.\n */\n\n// ---------------------------------------------------------------------------\n// Submit session\n// ---------------------------------------------------------------------------\n\nexport type FormSubmitStatus = \"idle\" | \"submitting\" | \"succeeded\" | \"failed\";\n\nexport type FormSubmitPhase =\n  | Readonly<{ status: \"idle\" }>\n  | Readonly<{ status: \"submitting\" }>\n  | Readonly<{ status: \"succeeded\" }>\n  | Readonly<{ status: \"failed\"; message: string }>;\n\nexport type FormSubmitOutcome =\n  | Readonly<{ outcome: \"succeeded\" }>\n  | Readonly<{ outcome: \"failed\"; message: string }>\n  | Readonly<{ outcome: \"blocked\"; reason: \"already-submitting\" }>\n  | Readonly<{ outcome: \"interrupted\" }>;\n\n/** Rejects to report a submission failure; resolving never implies success. */\nexport type FormSubmitHandler<Values> = (values: Values) => void | Promise<void>;\n\nexport type FormSubmitSessionOptions<Values> = Readonly<{\n  onSubmit: FormSubmitHandler<Values>;\n  /** Localized fallback shown when `resolveErrorMessage` is absent, throws, or returns empty copy. */\n  fallbackErrorMessage: string;\n  resolveErrorMessage?: (error: unknown) => string;\n}>;\n\n/**\n * A single submit session is reused across many attempts — unlike\n * AlertDialog's one-shot confirm, a form typically stays mounted and gets\n * resubmitted (edit → retry, or a settings screen saved again later). Each\n * attempt still settles its own returned Promise exactly once, and\n * `submitting` blocks every concurrent attempt the same way AlertDialog's\n * `busy` blocks a second confirm.\n */\nexport type FormSubmitSession<Values> = Readonly<{\n  getSnapshot(): FormSubmitPhase;\n  subscribe(listener: () => void): () => void;\n  submit(values: Values): Promise<FormSubmitOutcome>;\n  /** Moves a resting `succeeded`/`failed` phase back to `idle`. No-op while submitting. */\n  reset(): boolean;\n  dispose(): boolean;\n}>;\n\nfunction assertCopy(value: string, field: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`Form ${field} must not be empty`);\n  }\n}\n\nexport function validateFormSubmitSessionOptions<Values>(\n  options: FormSubmitSessionOptions<Values>,\n): void {\n  if (typeof options.onSubmit !== \"function\") {\n    throw new TypeError(\"Form onSubmit must be a function\");\n  }\n  assertCopy(options.fallbackErrorMessage, \"fallbackErrorMessage\");\n}\n\nfunction resolveFailureMessage<Values>(\n  options: FormSubmitSessionOptions<Values>,\n  error: unknown,\n): string {\n  try {\n    const resolved = options.resolveErrorMessage?.(error)?.trim();\n    return resolved || options.fallbackErrorMessage;\n  } catch {\n    return options.fallbackErrorMessage;\n  }\n}\n\n/**\n * Owns submit re-entrancy and exactly-once settlement. Does not own field\n * values (the caller passes `values` at call time), field-level validation,\n * or when submission is allowed to start (the product decides that from its\n * own dirty/valid state before calling `submit`).\n */\nexport function createFormSubmitSession<Values>(\n  options: FormSubmitSessionOptions<Values>,\n): FormSubmitSession<Values> {\n  validateFormSubmitSessionOptions(options);\n\n  let phase: FormSubmitPhase = { status: \"idle\" };\n  let disposed = false;\n  let interruptCurrentAttempt: ((outcome: FormSubmitOutcome) => void) | null = null;\n  const listeners = new Set<() => void>();\n\n  const notify = () => {\n    for (const listener of listeners) listener();\n  };\n  const transition = (next: FormSubmitPhase) => {\n    phase = next;\n    notify();\n  };\n\n  return {\n    getSnapshot: () => phase,\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => listeners.delete(listener);\n    },\n    submit(values) {\n      if (disposed) throw new Error(\"Cannot use a disposed Form submit session\");\n      if (phase.status === \"submitting\") {\n        return Promise.resolve({ outcome: \"blocked\", reason: \"already-submitting\" });\n      }\n\n      transition({ status: \"submitting\" });\n\n      return new Promise<FormSubmitOutcome>((resolve) => {\n        let settled = false;\n        const settleOnce = (outcome: FormSubmitOutcome) => {\n          if (settled) return;\n          settled = true;\n          interruptCurrentAttempt = null;\n          resolve(outcome);\n        };\n        interruptCurrentAttempt = settleOnce;\n\n        (async () => {\n          try {\n            await options.onSubmit(values);\n            if (settled) return;\n            transition({ status: \"succeeded\" });\n            settleOnce({ outcome: \"succeeded\" });\n          } catch (error) {\n            if (settled) return;\n            const message = resolveFailureMessage(options, error);\n            transition({ status: \"failed\", message });\n            settleOnce({ outcome: \"failed\", message });\n          }\n        })();\n      });\n    },\n    reset() {\n      if (disposed) return false;\n      if (phase.status === \"idle\" || phase.status === \"submitting\") return false;\n      transition({ status: \"idle\" });\n      return true;\n    },\n    dispose() {\n      if (disposed) return false;\n      disposed = true;\n      interruptCurrentAttempt?.({ outcome: \"interrupted\" });\n      interruptCurrentAttempt = null;\n      return true;\n    },\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Submit-failure focus\n// ---------------------------------------------------------------------------\n\n/**\n * Form does not register fields or run validation, so it cannot find the\n * first invalid field on its own. The product supplies its own field render\n * order and the ids it currently considers invalid (e.g. React Hook Form's\n * `formState.errors` keys); Form only fixes which one wins the race — first\n * in render order — so every product answers this the same way.\n */\nexport function validateFormFieldOrder(fieldOrder: readonly string[]): void {\n  const seen = new Set<string>();\n  fieldOrder.forEach((fieldId, index) => {\n    if (fieldId.trim().length === 0) {\n      throw new TypeError(`Form field id at index ${index} must not be empty`);\n    }\n    if (seen.has(fieldId)) {\n      throw new TypeError(`Duplicate Form field id: ${fieldId}`);\n    }\n    seen.add(fieldId);\n  });\n}\n\n/**\n * Web renderers call `.focus()` on the resolved field's control; React Native\n * renderers move accessibility focus to it (e.g. `AccessibilityInfo.sendAccessibilityEvent`\n * or a focus-trap ref). Returns `null` when there are no fields yet or none\n * are invalid, in which case a failed submit has no field to focus and the\n * form-level error slot below owns the announcement instead.\n */\nexport function resolveFirstInvalidFieldFocusTarget(\n  fieldOrder: readonly string[],\n  invalidFieldIds: ReadonlySet<string> | readonly string[],\n): string | null {\n  validateFormFieldOrder(fieldOrder);\n  const invalid =\n    invalidFieldIds instanceof Set ? invalidFieldIds : new Set(invalidFieldIds);\n  for (const fieldId of fieldOrder) {\n    if (invalid.has(fieldId)) return fieldId;\n  }\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Visual recipe — inter-field rhythm only\n// ---------------------------------------------------------------------------\n\nexport type FormDensity = \"compact\" | \"comfortable\";\n\nexport const formDefaults = {\n  density: \"comfortable\",\n} as const satisfies Readonly<{ density: FormDensity }>;\n\n/**\n * Anatomy is fixed, not a configurable prop: fields, then the form-level\n * error, then actions. `field` frame styling (background, border, its own\n * label/hint/error gap) belongs to `fieldRecipe`; this recipe only sets the\n * gap *between* one field and the next. `formError` renders as the existing\n * Notice `tone=\"danger\"` contract — Form fixes only its slot position, it\n * does not redeclare Notice's colors. `actions` has no dedicated layout here;\n * composing Button/Stack in that slot is the product's job, same reasoning\n * the roadmap already applies to Stack.\n */\nexport const formRecipe = {\n  slots: [\"root\", \"field\", \"formError\", \"actions\"] as const,\n  defaults: formDefaults,\n  density: {\n    compact: { fieldGap: spacing.sm },\n    comfortable: { fieldGap: spacing.lg },\n  },\n  formError: {\n    position: \"beforeActions\",\n    gap: spacing.sm,\n  },\n} as const satisfies Readonly<{\n  slots: readonly [\"root\", \"field\", \"formError\", \"actions\"];\n  defaults: Readonly<{ density: FormDensity }>;\n  density: Record<FormDensity, Readonly<{ fieldGap: number }>>;\n  formError: Readonly<{ position: \"beforeActions\"; gap: number }>;\n}>;\n\n// ---------------------------------------------------------------------------\n// Behavior — source for the shared behaviorRegistry wiring\n// ---------------------------------------------------------------------------\n\nexport const formBehaviorDefaults = {\n  /** Reuses Toast's own `normal | high` vocabulary: a blocked submission is `high`/assertive. */\n  errorAnnouncementPriority: \"high\",\n} as const satisfies Readonly<{ errorAnnouncementPriority: \"normal\" | \"high\" }>;\n\n/**\n * Kept beside the Form contract as the source value wired by\n * `behaviorRegistry.form`; this lets the registry reuse the contract without\n * redeclaring Form's inputs, events, states, or scenarios.\n */\nexport const formBehaviorSpec = {\n  /*\n    값은 제품이 소유하므로 controlled prop이 없다. 대신 renderer가 반드시 배선해야 하는\n    것을 `inputs`/`events`로 선언한다 — 공유 불변식이 \"controlled + inputs + events가\n    하나도 없는 behavior는 renderer 테스트가 구동할 대상이 없다\"고 요구하고, 그 지적이\n    옳다. 같은 형태(컨트롤러가 상태를 소유하고 renderer가 구동)인 `loadMore`가 이미\n    `controlled: []` + `inputs` + `events`로 선언한 선례를 따른다.\n  */\n  controlled: [],\n  inputs: [\"status\", \"formError\", \"fieldOrder\"],\n  events: [\"onSubmit\"],\n  defaults: formBehaviorDefaults,\n  stateAxes: {\n    availability: [\"enabled\", \"busy\"],\n    content: [\"idle\", \"loading\", \"error\"],\n  },\n  web: { roles: [\"alert\"], keyboard: [\"Tab\", \"Enter\"], focus: \"native\" },\n  native: { roles: [\"alert\"], states: [\"busy\"], actions: [\"submit\"] },\n  scenarios: [\n    \"submitting-blocks-every-concurrent-submit-attempt\",\n    \"each-submit-attempt-settles-its-result-exactly-once\",\n    \"failed-submit-returns-to-a-resting-state-that-still-allows-retry\",\n    \"succeeded-submit-remains-resting-and-allows-resubmission\",\n    \"dispose-during-submit-settles-the-pending-attempt-as-interrupted\",\n    \"disposed-session-rejects-further-submit-attempts\",\n    \"form-level-error-never-carries-a-per-field-message\",\n    \"first-invalid-field-in-render-order-receives-focus-on-submit-failure\",\n    \"form-level-error-is-announced-when-no-field-target-exists\",\n  ],\n} as const;\n"]}

package/dist/foundations.d.ts

@@ -0,0 +1,300 @@
+/** Numeric units are consumed as CSS pixels on web and density-independent points on native. */
+export declare const spacing: {
+    readonly xxs: 4;
+    readonly xs: 8;
+    readonly sm: 12;
+    readonly md: 16;
+    readonly lg: 20;
+    readonly xl: 24;
+    readonly xxl: 32;
+    readonly xxxl: 40;
+};
+export declare const radius: {
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+    readonly xl: 24;
+    readonly full: 999;
+};
+/**
+ * Ordered fallbacks keep the contract platform-neutral: Web renderers join
+ * the list as a CSS stack, while native renderers select the first family
+ * available on the device instead of receiving a CSS-only string.
+ */
+export declare const fontFamily: {
+    readonly ui: readonly ["Inter", "Pretendard", "-apple-system", "BlinkMacSystemFont", "Segoe UI", "sans-serif"];
+    readonly code: readonly ["ui-monospace", "SFMono-Regular", "Consolas", "Liberation Mono", "monospace"];
+};
+export type FontFamily = keyof typeof fontFamily;
+/** String weights translate unchanged to CSS and React Native text styles. */
+export declare const fontWeight: {
+    readonly regular: "400";
+    readonly medium: "500";
+    readonly semibold: "600";
+    readonly bold: "700";
+    readonly heavy: "800";
+};
+export type FontWeight = keyof typeof fontWeight;
+export type FontWeightValue = (typeof fontWeight)[FontWeight];
+/** Numeric tracking uses CSS pixels on Web and density-independent points on Native. */
+export declare const letterSpacing: {
+    readonly tight: -0.2;
+    readonly normal: 0;
+    readonly wide: 0.2;
+};
+export type LetterSpacing = keyof typeof letterSpacing;
+/** Renderers map the shared intent to `font-variant-numeric` / `fontVariant`. */
+export declare const numeric: {
+    readonly proportional: "proportional-nums";
+    readonly tabular: "tabular-nums";
+};
+export type NumericVariant = keyof typeof numeric;
+export declare const typography: {
+    readonly caption: {
+        readonly fontSize: 11;
+        readonly lineHeight: 16;
+        readonly fontWeight: "400";
+    };
+    readonly label: {
+        readonly fontSize: 12;
+        readonly lineHeight: 18;
+        readonly fontWeight: "600";
+    };
+    readonly body: {
+        readonly fontSize: 14;
+        readonly lineHeight: 20;
+        readonly fontWeight: "400";
+    };
+    readonly bodyLarge: {
+        readonly fontSize: 16;
+        readonly lineHeight: 24;
+        readonly fontWeight: "400";
+    };
+    readonly title: {
+        readonly fontSize: 18;
+        readonly lineHeight: 26;
+        readonly fontWeight: "700";
+    };
+    readonly titleLarge: {
+        readonly fontSize: 20;
+        readonly lineHeight: 28;
+        readonly fontWeight: "800";
+    };
+    readonly heading: {
+        readonly fontSize: 24;
+        readonly lineHeight: 32;
+        readonly fontWeight: "800";
+    };
+};
+export type TextVariant = keyof typeof typography;
+/**
+ * Document heading hierarchy without widening the established `TextVariant`
+ * union. Levels 3–5 reuse the existing semantic styles; larger levels are
+ * additive display roles for dense product pages and documentation.
+ */
+export declare const heading: {
+    readonly level1: {
+        readonly fontSize: 40;
+        readonly lineHeight: 48;
+        readonly fontWeight: "800";
+    };
+    readonly level2: {
+        readonly fontSize: 32;
+        readonly lineHeight: 40;
+        readonly fontWeight: "800";
+    };
+    readonly level3: {
+        readonly fontSize: 24;
+        readonly lineHeight: 32;
+        readonly fontWeight: "800";
+    };
+    readonly level4: {
+        readonly fontSize: 20;
+        readonly lineHeight: 28;
+        readonly fontWeight: "800";
+    };
+    readonly level5: {
+        readonly fontSize: 18;
+        readonly lineHeight: 26;
+        readonly fontWeight: "700";
+    };
+};
+export type HeadingLevel = keyof typeof heading;
+/** Glyphs include icons and avatars; they do not inherit paragraph line-height. */
+export declare const glyph: {
+    readonly xs: 14;
+    readonly sm: 20;
+    readonly md: 24;
+    readonly lg: 28;
+    readonly xl: 32;
+    readonly xxl: 44;
+    readonly xxxl: 48;
+};
+export type GlyphSize = keyof typeof glyph;
+export declare const motion: {
+    readonly fast: 120;
+    readonly normal: 200;
+    readonly slow: 320;
+};
+/**
+ * Curves are stored as normalized cubic-bezier tuples so CSS and native
+ * animation drivers can translate the same motion intent without sharing a
+ * renderer dependency.
+ */
+export declare const easing: {
+    readonly standard: readonly [0.2, 0, 0, 1];
+    readonly enter: readonly [0, 0, 0, 1];
+    readonly exit: readonly [0.3, 0, 1, 1];
+    readonly emphasized: readonly [0.2, 0, 0, 1];
+};
+export type ReducedMotionBehavior = "instant" | "opacity" | "static";
+/** Shared transition intent; renderers translate easing tuples to their animation API. */
+export declare const motionPreset: {
+    readonly micro: {
+        readonly duration: 120;
+        readonly easing: "standard";
+        readonly reducedMotion: "instant";
+    };
+    readonly enter: {
+        readonly duration: 200;
+        readonly easing: "enter";
+        readonly reducedMotion: "opacity";
+    };
+    readonly exit: {
+        readonly duration: 120;
+        readonly easing: "exit";
+        readonly reducedMotion: "instant";
+    };
+    readonly context: {
+        readonly duration: 320;
+        readonly easing: "emphasized";
+        readonly reducedMotion: "opacity";
+    };
+};
+/** Native renderers may use these values directly; web renderers use easing. */
+export declare const spring: {
+    readonly responsive: {
+        readonly stiffness: 760;
+        readonly damping: 52;
+        readonly mass: 1;
+    };
+    readonly expressive: {
+        readonly stiffness: 520;
+        readonly damping: 38;
+        readonly mass: 1;
+    };
+};
+/** Reusable state strengths. Components still decide which states are valid. */
+export declare const opacity: {
+    readonly disabled: 0.5;
+    readonly muted: 0.72;
+    readonly pressed: 0.86;
+    readonly dragged: 0.64;
+};
+/** Overlaying the content color at these strengths creates predictable states. */
+export declare const stateLayer: {
+    readonly hover: 0.06;
+    readonly focus: 0.08;
+    readonly pressed: 0.1;
+    readonly selected: 0.1;
+};
+export declare const stroke: {
+    readonly subtle: 1;
+    readonly default: 1;
+    readonly strong: 2;
+    readonly focus: 2;
+};
+export declare const control: {
+    readonly minTouchTarget: 44;
+    readonly buttonHeight: {
+        readonly small: 36;
+        readonly medium: 44;
+        readonly large: 52;
+    };
+    readonly buttonHitSlop: {
+        readonly small: 4;
+        readonly medium: 0;
+        readonly large: 0;
+    };
+    readonly fieldHeight: 44;
+    readonly chipHeight: {
+        readonly small: 36;
+        readonly medium: 44;
+    };
+    readonly selectionIndicator: 24;
+};
+/** Product renderers may narrow these widths, but should not invent new rhythm. */
+export declare const layout: {
+    readonly pagePadding: {
+        readonly compact: 16;
+        readonly regular: 20;
+        readonly spacious: 24;
+    };
+    readonly sectionGap: 24;
+    readonly contentGap: 16;
+    readonly rowHeight: {
+        readonly singleLine: 56;
+        readonly twoLine: 68;
+    };
+    readonly readingMaxWidth: 720;
+    readonly contentMaxWidth: 1200;
+};
+/** Width thresholds use CSS pixels on Web and density-independent points on Native. */
+export declare const breakpoint: {
+    readonly compact: 0;
+    readonly medium: 600;
+    readonly expanded: 960;
+    readonly wide: 1280;
+};
+/** Shared stacking intent. Values remain sparse to leave room for app layers. */
+export declare const layer: {
+    readonly base: 0;
+    readonly sticky: 100;
+    readonly dropdown: 400;
+    readonly overlay: 800;
+    readonly modal: 900;
+    readonly tooltip: 950;
+    readonly toast: 1000;
+};
+export declare const overlay: {
+    readonly scrim: 0.6;
+    readonly veil: 0.25;
+};
+export type BackdropReference = Readonly<{
+    color: "#000000";
+    opacity: number;
+}>;
+/** Fixed backdrop contracts avoid renderer-specific names such as CSS `scrim`. */
+export declare const backdrop: {
+    readonly modal: {
+        readonly color: "#000000";
+        readonly opacity: 0.6;
+    };
+    readonly veil: {
+        readonly color: "#000000";
+        readonly opacity: 0.25;
+    };
+};
+export declare const scrim: string;
+/** Renderers translate this contract to box-shadow or native shadow/elevation properties. */
+export declare const shadow: {
+    readonly raised: {
+        readonly color: "#000000";
+        readonly opacity: 0.08;
+        readonly radius: 4;
+        readonly offsetY: 1;
+    };
+    readonly floating: {
+        readonly color: "#000000";
+        readonly opacity: 0.12;
+        readonly radius: 12;
+        readonly offsetY: 4;
+    };
+    readonly overlay: {
+        readonly color: "#000000";
+        readonly opacity: 0.16;
+        readonly radius: 24;
+        readonly offsetY: 8;
+    };
+};
+//# sourceMappingURL=foundations.d.ts.map

package/dist/foundations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundations.d.ts","sourceRoot":"","sources":["../src/foundations.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,eAAO,MAAM,OAAO;;;;;;;;;CASV,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,UAAU;;;CAgBb,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AAEjD,8EAA8E;AAC9E,eAAO,MAAM,UAAU;;;;;;CAMb,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AACjD,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,UAAU,CAAC,CAAC;AAE9D,wFAAwF;AACxF,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,aAAa,CAAC;AAEvD,iFAAiF;AACjF,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,OAAO,CAAC;AAElD,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAQb,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,UAAU,CAAC;AAElD;;;;GAIG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;CAMV,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,OAAO,CAAC;AAEhD,mFAAmF;AACnF,eAAO,MAAM,KAAK;;;;;;;;CAQR,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,KAAK,CAAC;AAE3C,eAAO,MAAM,MAAM;;;;CAIT,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErE,0FAA0F;AAC1F,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;CA4BxB,CAAC;AAEF,gFAAgF;AAChF,eAAO,MAAM,MAAM;;;;;;;;;;;CAGT,CAAC;AAEX,gFAAgF;AAChF,eAAO,MAAM,OAAO;;;;;CAKV,CAAC;AAEX,kFAAkF;AAClF,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAEX,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AAEX,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;CAkBV,CAAC;AAEX,mFAAmF;AACnF,eAAO,MAAM,MAAM;;;;;;;;;;;;;;CAcT,CAAC;AAEX,uFAAuF;AACvF,eAAO,MAAM,UAAU;;;;;CAKb,CAAC;AAEX,iFAAiF;AACjF,eAAO,MAAM,KAAK;;;;;;;;CAQR,CAAC;AAEX,eAAO,MAAM,OAAO;;;CAGV,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,kFAAkF;AAClF,eAAO,MAAM,QAAQ;;;;;;;;;CAG2C,CAAC;AAEjE,eAAO,MAAM,KAAK,QAAoC,CAAC;AAEvD,6FAA6F;AAC7F,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;CAmBT,CAAC"}