@hjmds/design-contracts 0.8.2

package/dist/tooltip.d.ts

@@ -0,0 +1,44 @@
+export type TooltipPlacement = "top" | "bottom" | "start" | "end";
+export type TooltipAlign = "start" | "center" | "end";
+export type TooltipOpenChangeReason = "pointer" | "focus" | "pointer-leave" | "blur" | "escape" | "trigger-activation" | "another-tooltip";
+export type TooltipOpenChangeDetails = Readonly<{
+    reason: TooltipOpenChangeReason;
+}>;
+/** Tooltip copy is intentionally plain text and never owns an action. */
+export type TooltipDescriptor = Readonly<{
+    content: string;
+    placement?: TooltipPlacement;
+    align?: TooltipAlign;
+}>;
+export type ResolvedTooltipDescriptor = Readonly<{
+    content: string;
+    placement: TooltipPlacement;
+    align: TooltipAlign;
+}>;
+export type ControlledTooltipOpenState = Readonly<{
+    open: boolean;
+    defaultOpen?: never;
+    onOpenChange(open: boolean, details: TooltipOpenChangeDetails): void;
+}>;
+export type UncontrolledTooltipOpenState = Readonly<{
+    open?: never;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, details: TooltipOpenChangeDetails) => void;
+}>;
+export type TooltipOpenState = ControlledTooltipOpenState | UncontrolledTooltipOpenState;
+export declare const tooltipDescriptorDefaults: {
+    readonly placement: "top";
+    readonly align: "center";
+};
+export declare const tooltipBehaviorDefaults: {
+    readonly pointerOpenDelayMs: 500;
+    readonly focusOpenDelayMs: 0;
+    readonly skipDelayMs: 300;
+    readonly hoverable: true;
+    readonly touchHover: false;
+    readonly oneVisiblePerProvider: true;
+};
+export declare function validateTooltipDescriptor(descriptor: TooltipDescriptor): void;
+export declare function resolveTooltipDescriptor(descriptor: TooltipDescriptor): ResolvedTooltipDescriptor;
+export declare function validateTooltipOpenState(state: TooltipOpenState): void;
+//# sourceMappingURL=tooltip.d.ts.map

package/dist/tooltip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.d.ts","sourceRoot":"","sources":["../src/tooltip.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAC;AAClE,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtD,MAAM,MAAM,uBAAuB,GAC/B,SAAS,GACT,OAAO,GACP,eAAe,GACf,MAAM,GACN,QAAQ,GACR,oBAAoB,GACpB,iBAAiB,CAAC;AAEtB,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,MAAM,EAAE,uBAAuB,CAAC;CACjC,CAAC,CAAC;AAEH,yEAAyE;AACzE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,gBAAgB,CAAC;IAC7B,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB,CAAC,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,KAAK,EAAE,YAAY,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,wBAAwB,GAAG,IAAI,CAAC;CACtE,CAAC,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,CACb,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,wBAAwB,KAC9B,IAAI,CAAC;CACX,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GACxB,0BAA0B,GAC1B,4BAA4B,CAAC;AAEjC,eAAO,MAAM,yBAAyB;;;CAMpC,CAAC;AAEH,eAAO,MAAM,uBAAuB;;;;;;;CAO1B,CAAC;AA4BX,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,iBAAiB,GAC5B,IAAI,CA6BN;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,iBAAiB,GAC5B,yBAAyB,CAO3B;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAoCtE"}

package/dist/tooltip.js

@@ -0,0 +1,88 @@
+export const tooltipDescriptorDefaults = {
+    placement: "top",
+    align: "center",
+};
+export const tooltipBehaviorDefaults = {
+    pointerOpenDelayMs: 500,
+    focusOpenDelayMs: 0,
+    skipDelayMs: 300,
+    hoverable: true,
+    touchHover: false,
+    oneVisiblePerProvider: true,
+};
+const placements = new Set([
+    "top",
+    "bottom",
+    "start",
+    "end",
+]);
+const alignments = new Set(["start", "center", "end"]);
+const descriptorKeys = new Set(["content", "placement", "align"]);
+const openStateKeys = new Set(["open", "defaultOpen", "onOpenChange"]);
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, field) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`Unsupported Tooltip ${field} field: ${key}`);
+        }
+    }
+}
+export function validateTooltipDescriptor(descriptor) {
+    if (!isObject(descriptor)) {
+        throw new TypeError("Tooltip descriptor must be an object");
+    }
+    rejectUnknownKeys(descriptor, descriptorKeys, "descriptor");
+    if (typeof descriptor.content !== "string" ||
+        descriptor.content.trim().length === 0) {
+        throw new TypeError("Tooltip content must not be empty");
+    }
+    if (descriptor.content !== descriptor.content.trim()) {
+        throw new TypeError("Tooltip content must not start or end with whitespace");
+    }
+    if (descriptor.placement !== undefined &&
+        !placements.has(descriptor.placement)) {
+        throw new TypeError(`Unsupported Tooltip placement: ${String(descriptor.placement)}`);
+    }
+    if (descriptor.align !== undefined && !alignments.has(descriptor.align)) {
+        throw new TypeError(`Unsupported Tooltip align: ${String(descriptor.align)}`);
+    }
+}
+export function resolveTooltipDescriptor(descriptor) {
+    validateTooltipDescriptor(descriptor);
+    return {
+        content: descriptor.content,
+        placement: descriptor.placement ?? tooltipDescriptorDefaults.placement,
+        align: descriptor.align ?? tooltipDescriptorDefaults.align,
+    };
+}
+export function validateTooltipOpenState(state) {
+    if (!isObject(state)) {
+        throw new TypeError("Tooltip open state must be an object");
+    }
+    rejectUnknownKeys(state, openStateKeys, "open state");
+    const runtime = state;
+    const hasOpen = Object.prototype.hasOwnProperty.call(runtime, "open");
+    const hasDefaultOpen = Object.prototype.hasOwnProperty.call(runtime, "defaultOpen");
+    if (hasOpen) {
+        if (typeof runtime.open !== "boolean") {
+            throw new TypeError("Tooltip open must be a boolean");
+        }
+        if (hasDefaultOpen) {
+            throw new TypeError("Controlled Tooltip must not provide defaultOpen");
+        }
+        if (typeof runtime.onOpenChange !== "function") {
+            throw new TypeError("Controlled Tooltip must provide onOpenChange");
+        }
+        return;
+    }
+    if (hasDefaultOpen && typeof runtime.defaultOpen !== "boolean") {
+        throw new TypeError("Tooltip defaultOpen must be a boolean");
+    }
+    if (runtime.onOpenChange !== undefined &&
+        typeof runtime.onOpenChange !== "function") {
+        throw new TypeError("Tooltip onOpenChange must be a function");
+    }
+}
+//# sourceMappingURL=tooltip.js.map

package/dist/tooltip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip.js","sourceRoot":"","sources":["../src/tooltip.ts"],"names":[],"mappings":"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","sourcesContent":["export type TooltipPlacement = \"top\" | \"bottom\" | \"start\" | \"end\";\nexport type TooltipAlign = \"start\" | \"center\" | \"end\";\n\nexport type TooltipOpenChangeReason =\n  | \"pointer\"\n  | \"focus\"\n  | \"pointer-leave\"\n  | \"blur\"\n  | \"escape\"\n  | \"trigger-activation\"\n  | \"another-tooltip\";\n\nexport type TooltipOpenChangeDetails = Readonly<{\n  reason: TooltipOpenChangeReason;\n}>;\n\n/** Tooltip copy is intentionally plain text and never owns an action. */\nexport type TooltipDescriptor = Readonly<{\n  content: string;\n  placement?: TooltipPlacement;\n  align?: TooltipAlign;\n}>;\n\nexport type ResolvedTooltipDescriptor = Readonly<{\n  content: string;\n  placement: TooltipPlacement;\n  align: TooltipAlign;\n}>;\n\nexport type ControlledTooltipOpenState = Readonly<{\n  open: boolean;\n  defaultOpen?: never;\n  onOpenChange(open: boolean, details: TooltipOpenChangeDetails): void;\n}>;\n\nexport type UncontrolledTooltipOpenState = Readonly<{\n  open?: never;\n  defaultOpen?: boolean;\n  onOpenChange?: (\n    open: boolean,\n    details: TooltipOpenChangeDetails,\n  ) => void;\n}>;\n\nexport type TooltipOpenState =\n  | ControlledTooltipOpenState\n  | UncontrolledTooltipOpenState;\n\nexport const tooltipDescriptorDefaults = {\n  placement: \"top\",\n  align: \"center\",\n} as const satisfies Readonly<{\n  placement: TooltipPlacement;\n  align: TooltipAlign;\n}>;\n\nexport const tooltipBehaviorDefaults = {\n  pointerOpenDelayMs: 500,\n  focusOpenDelayMs: 0,\n  skipDelayMs: 300,\n  hoverable: true,\n  touchHover: false,\n  oneVisiblePerProvider: true,\n} as const;\n\nconst placements = new Set<TooltipPlacement>([\n  \"top\",\n  \"bottom\",\n  \"start\",\n  \"end\",\n]);\nconst alignments = new Set<TooltipAlign>([\"start\", \"center\", \"end\"]);\nconst descriptorKeys = new Set([\"content\", \"placement\", \"align\"]);\nconst openStateKeys = new Set([\"open\", \"defaultOpen\", \"onOpenChange\"]);\n\nfunction isObject(value: unknown): value is Readonly<Record<string, unknown>> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction rejectUnknownKeys(\n  value: Readonly<Record<string, unknown>>,\n  allowed: ReadonlySet<string>,\n  field: string,\n): void {\n  for (const key of Object.keys(value)) {\n    if (!allowed.has(key)) {\n      throw new TypeError(`Unsupported Tooltip ${field} field: ${key}`);\n    }\n  }\n}\n\nexport function validateTooltipDescriptor(\n  descriptor: TooltipDescriptor,\n): void {\n  if (!isObject(descriptor)) {\n    throw new TypeError(\"Tooltip descriptor must be an object\");\n  }\n  rejectUnknownKeys(descriptor, descriptorKeys, \"descriptor\");\n  if (\n    typeof descriptor.content !== \"string\" ||\n    descriptor.content.trim().length === 0\n  ) {\n    throw new TypeError(\"Tooltip content must not be empty\");\n  }\n  if (descriptor.content !== descriptor.content.trim()) {\n    throw new TypeError(\n      \"Tooltip content must not start or end with whitespace\",\n    );\n  }\n  if (\n    descriptor.placement !== undefined &&\n    !placements.has(descriptor.placement)\n  ) {\n    throw new TypeError(\n      `Unsupported Tooltip placement: ${String(descriptor.placement)}`,\n    );\n  }\n  if (descriptor.align !== undefined && !alignments.has(descriptor.align)) {\n    throw new TypeError(\n      `Unsupported Tooltip align: ${String(descriptor.align)}`,\n    );\n  }\n}\n\nexport function resolveTooltipDescriptor(\n  descriptor: TooltipDescriptor,\n): ResolvedTooltipDescriptor {\n  validateTooltipDescriptor(descriptor);\n  return {\n    content: descriptor.content,\n    placement: descriptor.placement ?? tooltipDescriptorDefaults.placement,\n    align: descriptor.align ?? tooltipDescriptorDefaults.align,\n  };\n}\n\nexport function validateTooltipOpenState(state: TooltipOpenState): void {\n  if (!isObject(state)) {\n    throw new TypeError(\"Tooltip open state must be an object\");\n  }\n  rejectUnknownKeys(state, openStateKeys, \"open state\");\n  const runtime = state as Readonly<Record<string, unknown>>;\n  const hasOpen = Object.prototype.hasOwnProperty.call(runtime, \"open\");\n  const hasDefaultOpen = Object.prototype.hasOwnProperty.call(\n    runtime,\n    \"defaultOpen\",\n  );\n  if (hasOpen) {\n    if (typeof runtime.open !== \"boolean\") {\n      throw new TypeError(\"Tooltip open must be a boolean\");\n    }\n    if (hasDefaultOpen) {\n      throw new TypeError(\n        \"Controlled Tooltip must not provide defaultOpen\",\n      );\n    }\n    if (typeof runtime.onOpenChange !== \"function\") {\n      throw new TypeError(\n        \"Controlled Tooltip must provide onOpenChange\",\n      );\n    }\n    return;\n  }\n  if (hasDefaultOpen && typeof runtime.defaultOpen !== \"boolean\") {\n    throw new TypeError(\"Tooltip defaultOpen must be a boolean\");\n  }\n  if (\n    runtime.onOpenChange !== undefined &&\n    typeof runtime.onOpenChange !== \"function\"\n  ) {\n    throw new TypeError(\"Tooltip onOpenChange must be a function\");\n  }\n}\n"]}

package/dist/tour.d.ts

@@ -0,0 +1,218 @@
+/**
+ * Tour has no substitute in this package. Unlike FloatingActionButton
+ * (BottomCTA already owns the full-width conclusion) or ConfirmPopover
+ * (Popover + AlertDialog already cover its space), walking a user through
+ * several distinct screen elements in sequence is not already solved by any
+ * existing contract.
+ *
+ * The hardest boundary: this package knows nothing about the DOM or RN view
+ * tree. A step names its target with an opaque `anchorId` the product already
+ * uses to identify that element; measuring it, scrolling it into view, and
+ * drawing any highlight/cutout is entirely the renderer's job. This module
+ * never accepts a ref, node, or coordinate.
+ */
+export type TourPlacement = "top" | "bottom" | "start" | "end";
+export type TourAlign = "start" | "center" | "end";
+export type TourStepDescriptor<Id extends string = string> = Readonly<{
+    id: Id;
+    /** Opaque product-owned key; never a DOM node, RN ref, or measured rect. */
+    anchorId: string;
+    title: string;
+    description: string;
+    placement?: TourPlacement;
+    align?: TourAlign;
+}>;
+export type TourLabels = Readonly<{
+    next: string;
+    previous: string;
+    skip: string;
+    /** Shown instead of `next` on the last step. */
+    done: string;
+}>;
+/**
+ * A single stable cursor (`currentStepId`) is the source of truth, same
+ * reasoning as Steps: no per-step status array that could represent two
+ * "current" steps at once. Unlike Steps, `anchorId` values are not required
+ * to be unique — a product may legitimately explain one element across two
+ * consecutive steps ("tap here" / "now hold to reorder").
+ */
+export type TourDescriptor<Id extends string = string> = Readonly<{
+    /** Announced once when the tour opens, before any step content. */
+    accessibilityLabel: string;
+    steps: readonly TourStepDescriptor<Id>[];
+    currentStepId: Id;
+    labels: TourLabels;
+}>;
+export type TourAdvanceReason = "next" | "previous";
+/**
+ * `skip`/`escape` are the user backing out early, `complete` is finishing the
+ * last step, `programmatic` is the controlled owner closing directly, and
+ * `interrupted` is an unmount or route replace settling the tour without any
+ * of the above — mirroring AlertDialog's cancel-reason vocabulary. There is
+ * deliberately no `outside` reason: unlike Popover, an accidental pointer
+ * outside the card must not silently end a walkthrough the user did not ask
+ * to leave.
+ */
+export type TourCloseReason = "skip" | "escape" | "complete" | "programmatic" | "interrupted";
+/**
+ * `onOpenChange`는 여는 것과 닫는 것을 모두 보고하는데 `TourCloseReason`에는 여는
+ * 사유가 없었다. 타입 이름이 약속하는 것과 내용이 어긋나 있었고, 오버레이 어휘를
+ * 보고하는 다른 일곱 모듈은 전부 `"trigger"`를 쓴다(`docs/architecture.md`의
+ * 「오버레이 어휘 규칙」). 여기만 예외로 둘 이유가 없어 같은 이름을 들인다.
+ */
+export type TourOpenReason = "trigger" | TourCloseReason;
+export type TourOpenChangeDetail = Readonly<{
+    reason: TourOpenReason;
+}>;
+export type ControlledTourOpenState = Readonly<{
+    open: boolean;
+    defaultOpen?: never;
+    onOpenChange(open: boolean, detail: TourOpenChangeDetail): void;
+}>;
+export type UncontrolledTourOpenState = Readonly<{
+    open?: never;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, detail: TourOpenChangeDetail) => void;
+}>;
+export type TourOpenState = ControlledTourOpenState | UncontrolledTourOpenState;
+export type TourStepChangeHandler<Id extends string = string> = (stepId: Id, reason: TourAdvanceReason) => void;
+export type TourStepAnnouncementInfo = Readonly<{
+    position: number;
+    total: number;
+    title: string;
+    description: string;
+}>;
+/**
+ * Products compose the exact phrase order (Korean "5단계 중 2단계" does not
+ * translate structurally to "step 2 of 5"), same reasoning as Steps'
+ * `composeAccessibleName`. The composed string is what a renderer moves
+ * accessibility focus to and announces on every step change — it is the
+ * entire answer to "what does a screen reader user get instead of a visual
+ * pointer": the same title, description, and position a sighted user reads.
+ */
+export type ComposeTourStepAnnouncement = (info: TourStepAnnouncementInfo) => string;
+export type ResolveTourOptions = Readonly<{
+    composeAnnouncement: ComposeTourStepAnnouncement;
+}>;
+export type ResolvedTourStepDescriptor<Id extends string = string> = TourStepDescriptor<Id> & Readonly<{
+    /** 1-indexed so position and title both preserve reading order for renderers. */
+    position: number;
+    total: number;
+    announcement: string;
+}>;
+export type ResolvedTourDescriptor<Id extends string = string> = Readonly<{
+    accessibilityLabel: string;
+    steps: readonly ResolvedTourStepDescriptor<Id>[];
+    currentStep: ResolvedTourStepDescriptor<Id>;
+    isFirstStep: boolean;
+    isLastStep: boolean;
+}>;
+export type TourAdvanceOutcome<Id extends string = string> = Readonly<{
+    type: "step";
+    stepId: Id;
+}> | Readonly<{
+    type: "close";
+    reason: "complete";
+}> | Readonly<{
+    type: "no-op";
+}>;
+/**
+ * The only fixed policy this contract has: outside dismiss is never allowed.
+ * There is no `dismissible`/`escapeDismiss` bag to configure, unlike Popover
+ * — Escape and the Skip action always work (the brief's "탈출" requirement is
+ * non-negotiable), so there is nothing left to make optional.
+ */
+export declare const tourBehaviorDefaults: {
+    readonly outsideDismiss: false;
+};
+export declare function validateTourStepDescriptor<Id extends string>(step: TourStepDescriptor<Id>): void;
+export declare function validateTourLabels(labels: TourLabels): void;
+/**
+ * Duplicate `anchorId` values across steps are accepted on purpose (see the
+ * type doc above) — only `id` must be unique. A validator that rejected
+ * repeated anchors would block a legitimate two-part explanation of one
+ * element.
+ */
+export declare function validateTourDescriptor<Id extends string>(descriptor: TourDescriptor<Id>): void;
+export declare function validateTourOpenState(state: TourOpenState): void;
+/**
+ * Resolves every step eagerly (not just the current one) so a renderer can
+ * pre-render adjacent step cards without re-deriving position/total, mirroring
+ * `resolveStepsDescriptor`. Throws if the composer returns an empty
+ * announcement instead of silently leaving screen reader users with nothing.
+ */
+export declare function resolveTourDescriptor<Id extends string>(descriptor: TourDescriptor<Id>, options: ResolveTourOptions): ResolvedTourDescriptor<Id>;
+/**
+ * Pure decision, no stateful session: Tour has no async side effect to guard
+ * (unlike AlertDialog's confirm), so there is no busy/error phase to own —
+ * only "what step comes next," which is exactly what a renderer needs to call
+ * `onStepChange`/`onOpenChange` itself. This follows Popover's lighter
+ * pattern rather than AlertDialog's session, since nothing here needs
+ * exactly-once side-effect guarding, only the ordinary exactly-once event
+ * delivery a renderer's own callback already provides.
+ */
+export declare function resolveTourAdvance<Id extends string>(descriptor: TourDescriptor<Id>, reason: TourAdvanceReason): TourAdvanceOutcome<Id>;
+/**
+ * The step card reuses the same anchored floating-surface anatomy as
+ * Tooltip/Popover instead of declaring new chrome. The backdrop reuses the
+ * stronger `backdrop.modal` veil (not `backdrop.veil`) because Tour, like
+ * Dialog/Sheet, blocks background interaction while open — `veil` is used
+ * where the surface underneath stays reachable, which Tour's fixed
+ * `outsideDismiss: false` policy says it does not.
+ */
+export declare const tourRecipe: {
+    readonly slots: readonly ["backdrop", "card", "title", "description", "counter", "previousAction", "nextAction", "skipAction"];
+    readonly card: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "bg";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly borderWidth: 1;
+        readonly radius: "md";
+        readonly shadow: {
+            readonly color: "#000000";
+            readonly opacity: 0.12;
+            readonly radius: 12;
+            readonly offsetY: 4;
+        };
+        readonly padding: 8;
+    };
+    readonly backdrop: {
+        readonly color: "#000000";
+        readonly opacity: 0.6;
+    };
+    readonly maxWidth: 320;
+    readonly gap: 12;
+    readonly sideOffset: 8;
+    /**
+     * `context` (320ms, opacity under Reduce Motion): moving from one step's
+     * card/highlight to the next is a jump between unrelated parts of the
+     * screen, the same "큰 화면 요소와 맥락 전환" tier Sheet/Dialog use, not a
+     * small in-place state change.
+     */
+    readonly transition: {
+        readonly enter: {
+            readonly duration: 320;
+            readonly easing: "emphasized";
+            readonly reducedMotion: "opacity";
+        };
+        readonly exit: {
+            readonly duration: 120;
+            readonly easing: "exit";
+            readonly reducedMotion: "instant";
+        };
+    };
+};
+/**
+ * Literal scenario names for behaviorRegistry.tour (lead wires into
+ * src/behaviors.ts). Kept here, not there, so this module stays
+ * self-contained per the authoring brief.
+ */
+export declare const tourBehaviorScenarios: readonly ["focus-moves-to-the-step-card-on-every-step-change-not-the-anchor", "background-is-inert-while-a-tour-is-open", "escape-and-skip-always-exit-regardless-of-step", "outside-pointer-does-not-dismiss", "next-on-the-last-step-closes-with-reason-complete", "previous-on-the-first-step-is-a-no-op", "controlled-owner-programmatic-close-always-wins", "unmount-or-route-change-settles-as-interrupted-exactly-once", "reduced-motion-crossfades-the-card-without-traveling-between-anchors"];
+//# sourceMappingURL=tour.d.ts.map

package/dist/tour.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour.d.ts","sourceRoot":"","sources":["../src/tour.ts"],"names":[],"mappings":"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"}

package/dist/tour.js

@@ -0,0 +1,211 @@
+import { backdrop, motionPreset, spacing } from "./foundations.js";
+import { floatingSurfaceContract } from "./component-contracts.js";
+/**
+ * The only fixed policy this contract has: outside dismiss is never allowed.
+ * There is no `dismissible`/`escapeDismiss` bag to configure, unlike Popover
+ * — Escape and the Skip action always work (the brief's "탈출" requirement is
+ * non-negotiable), so there is nothing left to make optional.
+ */
+export const tourBehaviorDefaults = {
+    outsideDismiss: false,
+};
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`Tour ${field} must not be empty`);
+    }
+}
+const placements = new Set(["top", "bottom", "start", "end"]);
+const aligns = new Set(["start", "center", "end"]);
+export function validateTourStepDescriptor(step) {
+    assertNonEmpty(step.id, "step id");
+    if (step.id !== step.id.trim()) {
+        throw new TypeError("Tour step id must not start or end with whitespace");
+    }
+    assertNonEmpty(step.anchorId, "step anchorId");
+    assertNonEmpty(step.title, "step title");
+    assertNonEmpty(step.description, "step description");
+    if (step.placement !== undefined && !placements.has(step.placement)) {
+        throw new TypeError(`Unsupported Tour step placement: ${String(step.placement)}`);
+    }
+    if (step.align !== undefined && !aligns.has(step.align)) {
+        throw new TypeError(`Unsupported Tour step align: ${String(step.align)}`);
+    }
+}
+export function validateTourLabels(labels) {
+    if (labels === null || typeof labels !== "object") {
+        throw new TypeError("Tour labels must be an object");
+    }
+    for (const field of ["next", "previous", "skip", "done"]) {
+        const value = labels[field];
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new TypeError(`Tour labels.${field} must not be empty`);
+        }
+    }
+}
+/**
+ * Duplicate `anchorId` values across steps are accepted on purpose (see the
+ * type doc above) — only `id` must be unique. A validator that rejected
+ * repeated anchors would block a legitimate two-part explanation of one
+ * element.
+ */
+export function validateTourDescriptor(descriptor) {
+    assertNonEmpty(descriptor.accessibilityLabel, "accessibilityLabel");
+    if (!Array.isArray(descriptor.steps) || descriptor.steps.length === 0) {
+        throw new RangeError("Tour must contain at least one step");
+    }
+    validateTourLabels(descriptor.labels);
+    const ids = new Set();
+    for (const step of descriptor.steps) {
+        validateTourStepDescriptor(step);
+        if (ids.has(step.id)) {
+            throw new TypeError(`Duplicate Tour step id: ${step.id}`);
+        }
+        ids.add(step.id);
+    }
+    if (!ids.has(descriptor.currentStepId)) {
+        throw new RangeError(`Tour currentStepId does not match any step id: ${String(descriptor.currentStepId)}`);
+    }
+}
+const openStateKeys = new Set(["open", "defaultOpen", "onOpenChange"]);
+export function validateTourOpenState(state) {
+    if (state === null || typeof state !== "object") {
+        throw new TypeError("Tour open state must be an object");
+    }
+    const runtime = state;
+    for (const key of Object.keys(runtime)) {
+        if (!openStateKeys.has(key)) {
+            throw new TypeError(`Unsupported Tour open state field: ${key}`);
+        }
+    }
+    const hasOpen = Object.prototype.hasOwnProperty.call(runtime, "open");
+    const hasDefaultOpen = Object.prototype.hasOwnProperty.call(runtime, "defaultOpen");
+    if (hasOpen) {
+        if (typeof runtime.open !== "boolean") {
+            throw new TypeError("Tour open must be a boolean");
+        }
+        if (hasDefaultOpen) {
+            throw new TypeError("Controlled Tour must not provide defaultOpen");
+        }
+        if (typeof runtime.onOpenChange !== "function") {
+            throw new TypeError("Controlled Tour must provide onOpenChange");
+        }
+        return;
+    }
+    if (hasDefaultOpen && typeof runtime.defaultOpen !== "boolean") {
+        throw new TypeError("Tour defaultOpen must be a boolean");
+    }
+    if (runtime.onOpenChange !== undefined && typeof runtime.onOpenChange !== "function") {
+        throw new TypeError("Tour onOpenChange must be a function");
+    }
+}
+/**
+ * Resolves every step eagerly (not just the current one) so a renderer can
+ * pre-render adjacent step cards without re-deriving position/total, mirroring
+ * `resolveStepsDescriptor`. Throws if the composer returns an empty
+ * announcement instead of silently leaving screen reader users with nothing.
+ */
+export function resolveTourDescriptor(descriptor, options) {
+    validateTourDescriptor(descriptor);
+    if (typeof options.composeAnnouncement !== "function") {
+        throw new TypeError("Tour composeAnnouncement must be a function");
+    }
+    const total = descriptor.steps.length;
+    const cursorIndex = descriptor.steps.findIndex((step) => step.id === descriptor.currentStepId);
+    const steps = descriptor.steps.map((step, index) => {
+        const position = index + 1;
+        const announcement = options.composeAnnouncement({
+            position,
+            total,
+            title: step.title,
+            description: step.description,
+        });
+        if (typeof announcement !== "string" || announcement.trim().length === 0) {
+            throw new TypeError("Tour composeAnnouncement must return a non-empty string");
+        }
+        return { ...step, position, total, announcement };
+    });
+    return {
+        accessibilityLabel: descriptor.accessibilityLabel,
+        steps,
+        // Safe: validateTourDescriptor already confirmed currentStepId matches a step.
+        currentStep: steps[cursorIndex],
+        isFirstStep: cursorIndex === 0,
+        isLastStep: cursorIndex === total - 1,
+    };
+}
+/**
+ * Pure decision, no stateful session: Tour has no async side effect to guard
+ * (unlike AlertDialog's confirm), so there is no busy/error phase to own —
+ * only "what step comes next," which is exactly what a renderer needs to call
+ * `onStepChange`/`onOpenChange` itself. This follows Popover's lighter
+ * pattern rather than AlertDialog's session, since nothing here needs
+ * exactly-once side-effect guarding, only the ordinary exactly-once event
+ * delivery a renderer's own callback already provides.
+ */
+export function resolveTourAdvance(descriptor, reason) {
+    validateTourDescriptor(descriptor);
+    if (reason !== "next" && reason !== "previous") {
+        throw new TypeError(`Unsupported Tour advance reason: ${String(reason)}`);
+    }
+    const cursorIndex = descriptor.steps.findIndex((step) => step.id === descriptor.currentStepId);
+    if (reason === "previous") {
+        if (cursorIndex === 0)
+            return { type: "no-op" };
+        // Safe: cursorIndex > 0 here, so cursorIndex - 1 is always in bounds.
+        return { type: "step", stepId: descriptor.steps[cursorIndex - 1].id };
+    }
+    if (cursorIndex === descriptor.steps.length - 1) {
+        return { type: "close", reason: "complete" };
+    }
+    // Safe: cursorIndex is not the last index here, so cursorIndex + 1 is in bounds.
+    return { type: "step", stepId: descriptor.steps[cursorIndex + 1].id };
+}
+/**
+ * The step card reuses the same anchored floating-surface anatomy as
+ * Tooltip/Popover instead of declaring new chrome. The backdrop reuses the
+ * stronger `backdrop.modal` veil (not `backdrop.veil`) because Tour, like
+ * Dialog/Sheet, blocks background interaction while open — `veil` is used
+ * where the surface underneath stays reachable, which Tour's fixed
+ * `outsideDismiss: false` policy says it does not.
+ */
+export const tourRecipe = {
+    slots: [
+        "backdrop",
+        "card",
+        "title",
+        "description",
+        "counter",
+        "previousAction",
+        "nextAction",
+        "skipAction",
+    ],
+    card: floatingSurfaceContract,
+    backdrop: backdrop.modal,
+    maxWidth: 320,
+    gap: spacing.sm,
+    sideOffset: spacing.xs,
+    /**
+     * `context` (320ms, opacity under Reduce Motion): moving from one step's
+     * card/highlight to the next is a jump between unrelated parts of the
+     * screen, the same "큰 화면 요소와 맥락 전환" tier Sheet/Dialog use, not a
+     * small in-place state change.
+     */
+    transition: { enter: motionPreset.context, exit: motionPreset.exit },
+};
+/**
+ * Literal scenario names for behaviorRegistry.tour (lead wires into
+ * src/behaviors.ts). Kept here, not there, so this module stays
+ * self-contained per the authoring brief.
+ */
+export const tourBehaviorScenarios = [
+    "focus-moves-to-the-step-card-on-every-step-change-not-the-anchor",
+    "background-is-inert-while-a-tour-is-open",
+    "escape-and-skip-always-exit-regardless-of-step",
+    "outside-pointer-does-not-dismiss",
+    "next-on-the-last-step-closes-with-reason-complete",
+    "previous-on-the-first-step-is-a-no-op",
+    "controlled-owner-programmatic-close-always-wins",
+    "unmount-or-route-change-settles-as-interrupted-exactly-once",
+    "reduced-motion-crossfades-the-card-without-traveling-between-anchors",
+];
+//# sourceMappingURL=tour.js.map

package/dist/tour.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour.js","sourceRoot":"","sources":["../src/tour.ts"],"names":[],"mappings":"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","sourcesContent":["import { backdrop, motionPreset, spacing } from \"./foundations.js\";\nimport { floatingSurfaceContract } from \"./component-contracts.js\";\n\n/**\n * Tour has no substitute in this package. Unlike FloatingActionButton\n * (BottomCTA already owns the full-width conclusion) or ConfirmPopover\n * (Popover + AlertDialog already cover its space), walking a user through\n * several distinct screen elements in sequence is not already solved by any\n * existing contract.\n *\n * The hardest boundary: this package knows nothing about the DOM or RN view\n * tree. A step names its target with an opaque `anchorId` the product already\n * uses to identify that element; measuring it, scrolling it into view, and\n * drawing any highlight/cutout is entirely the renderer's job. This module\n * never accepts a ref, node, or coordinate.\n */\nexport type TourPlacement = \"top\" | \"bottom\" | \"start\" | \"end\";\nexport type TourAlign = \"start\" | \"center\" | \"end\";\n\nexport type TourStepDescriptor<Id extends string = string> = Readonly<{\n  id: Id;\n  /** Opaque product-owned key; never a DOM node, RN ref, or measured rect. */\n  anchorId: string;\n  title: string;\n  description: string;\n  placement?: TourPlacement;\n  align?: TourAlign;\n}>;\n\nexport type TourLabels = Readonly<{\n  next: string;\n  previous: string;\n  skip: string;\n  /** Shown instead of `next` on the last step. */\n  done: string;\n}>;\n\n/**\n * A single stable cursor (`currentStepId`) is the source of truth, same\n * reasoning as Steps: no per-step status array that could represent two\n * \"current\" steps at once. Unlike Steps, `anchorId` values are not required\n * to be unique — a product may legitimately explain one element across two\n * consecutive steps (\"tap here\" / \"now hold to reorder\").\n */\nexport type TourDescriptor<Id extends string = string> = Readonly<{\n  /** Announced once when the tour opens, before any step content. */\n  accessibilityLabel: string;\n  steps: readonly TourStepDescriptor<Id>[];\n  currentStepId: Id;\n  labels: TourLabels;\n}>;\n\nexport type TourAdvanceReason = \"next\" | \"previous\";\n\n/**\n * `skip`/`escape` are the user backing out early, `complete` is finishing the\n * last step, `programmatic` is the controlled owner closing directly, and\n * `interrupted` is an unmount or route replace settling the tour without any\n * of the above — mirroring AlertDialog's cancel-reason vocabulary. There is\n * deliberately no `outside` reason: unlike Popover, an accidental pointer\n * outside the card must not silently end a walkthrough the user did not ask\n * to leave.\n */\nexport type TourCloseReason =\n  | \"skip\"\n  | \"escape\"\n  | \"complete\"\n  | \"programmatic\"\n  | \"interrupted\";\n\n/**\n * `onOpenChange`는 여는 것과 닫는 것을 모두 보고하는데 `TourCloseReason`에는 여는\n * 사유가 없었다. 타입 이름이 약속하는 것과 내용이 어긋나 있었고, 오버레이 어휘를\n * 보고하는 다른 일곱 모듈은 전부 `\"trigger\"`를 쓴다(`docs/architecture.md`의\n * 「오버레이 어휘 규칙」). 여기만 예외로 둘 이유가 없어 같은 이름을 들인다.\n */\nexport type TourOpenReason = \"trigger\" | TourCloseReason;\n\nexport type TourOpenChangeDetail = Readonly<{ reason: TourOpenReason }>;\n\nexport type ControlledTourOpenState = Readonly<{\n  open: boolean;\n  defaultOpen?: never;\n  onOpenChange(open: boolean, detail: TourOpenChangeDetail): void;\n}>;\n\nexport type UncontrolledTourOpenState = Readonly<{\n  open?: never;\n  defaultOpen?: boolean;\n  onOpenChange?: (open: boolean, detail: TourOpenChangeDetail) => void;\n}>;\n\nexport type TourOpenState = ControlledTourOpenState | UncontrolledTourOpenState;\n\nexport type TourStepChangeHandler<Id extends string = string> = (\n  stepId: Id,\n  reason: TourAdvanceReason,\n) => void;\n\nexport type TourStepAnnouncementInfo = Readonly<{\n  position: number;\n  total: number;\n  title: string;\n  description: string;\n}>;\n\n/**\n * Products compose the exact phrase order (Korean \"5단계 중 2단계\" does not\n * translate structurally to \"step 2 of 5\"), same reasoning as Steps'\n * `composeAccessibleName`. The composed string is what a renderer moves\n * accessibility focus to and announces on every step change — it is the\n * entire answer to \"what does a screen reader user get instead of a visual\n * pointer\": the same title, description, and position a sighted user reads.\n */\nexport type ComposeTourStepAnnouncement = (info: TourStepAnnouncementInfo) => string;\n\nexport type ResolveTourOptions = Readonly<{\n  composeAnnouncement: ComposeTourStepAnnouncement;\n}>;\n\nexport type ResolvedTourStepDescriptor<Id extends string = string> =\n  TourStepDescriptor<Id> &\n    Readonly<{\n      /** 1-indexed so position and title both preserve reading order for renderers. */\n      position: number;\n      total: number;\n      announcement: string;\n    }>;\n\nexport type ResolvedTourDescriptor<Id extends string = string> = Readonly<{\n  accessibilityLabel: string;\n  steps: readonly ResolvedTourStepDescriptor<Id>[];\n  currentStep: ResolvedTourStepDescriptor<Id>;\n  isFirstStep: boolean;\n  isLastStep: boolean;\n}>;\n\nexport type TourAdvanceOutcome<Id extends string = string> =\n  | Readonly<{ type: \"step\"; stepId: Id }>\n  | Readonly<{ type: \"close\"; reason: \"complete\" }>\n  | Readonly<{ type: \"no-op\" }>;\n\n/**\n * The only fixed policy this contract has: outside dismiss is never allowed.\n * There is no `dismissible`/`escapeDismiss` bag to configure, unlike Popover\n * — Escape and the Skip action always work (the brief's \"탈출\" requirement is\n * non-negotiable), so there is nothing left to make optional.\n */\nexport const tourBehaviorDefaults = {\n  outsideDismiss: false,\n} as const satisfies Readonly<{ outsideDismiss: false }>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`Tour ${field} must not be empty`);\n  }\n}\n\nconst placements = new Set<TourPlacement>([\"top\", \"bottom\", \"start\", \"end\"]);\nconst aligns = new Set<TourAlign>([\"start\", \"center\", \"end\"]);\n\nexport function validateTourStepDescriptor<Id extends string>(\n  step: TourStepDescriptor<Id>,\n): void {\n  assertNonEmpty(step.id, \"step id\");\n  if (step.id !== step.id.trim()) {\n    throw new TypeError(\"Tour step id must not start or end with whitespace\");\n  }\n  assertNonEmpty(step.anchorId, \"step anchorId\");\n  assertNonEmpty(step.title, \"step title\");\n  assertNonEmpty(step.description, \"step description\");\n  if (step.placement !== undefined && !placements.has(step.placement)) {\n    throw new TypeError(`Unsupported Tour step placement: ${String(step.placement)}`);\n  }\n  if (step.align !== undefined && !aligns.has(step.align)) {\n    throw new TypeError(`Unsupported Tour step align: ${String(step.align)}`);\n  }\n}\n\nexport function validateTourLabels(labels: TourLabels): void {\n  if (labels === null || typeof labels !== \"object\") {\n    throw new TypeError(\"Tour labels must be an object\");\n  }\n  for (const field of [\"next\", \"previous\", \"skip\", \"done\"] as const) {\n    const value = labels[field];\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n      throw new TypeError(`Tour labels.${field} must not be empty`);\n    }\n  }\n}\n\n/**\n * Duplicate `anchorId` values across steps are accepted on purpose (see the\n * type doc above) — only `id` must be unique. A validator that rejected\n * repeated anchors would block a legitimate two-part explanation of one\n * element.\n */\nexport function validateTourDescriptor<Id extends string>(\n  descriptor: TourDescriptor<Id>,\n): void {\n  assertNonEmpty(descriptor.accessibilityLabel, \"accessibilityLabel\");\n  if (!Array.isArray(descriptor.steps) || descriptor.steps.length === 0) {\n    throw new RangeError(\"Tour must contain at least one step\");\n  }\n  validateTourLabels(descriptor.labels);\n\n  const ids = new Set<Id>();\n  for (const step of descriptor.steps) {\n    validateTourStepDescriptor(step);\n    if (ids.has(step.id)) {\n      throw new TypeError(`Duplicate Tour step id: ${step.id}`);\n    }\n    ids.add(step.id);\n  }\n  if (!ids.has(descriptor.currentStepId)) {\n    throw new RangeError(\n      `Tour currentStepId does not match any step id: ${String(descriptor.currentStepId)}`,\n    );\n  }\n}\n\nconst openStateKeys = new Set([\"open\", \"defaultOpen\", \"onOpenChange\"]);\n\nexport function validateTourOpenState(state: TourOpenState): void {\n  if (state === null || typeof state !== \"object\") {\n    throw new TypeError(\"Tour open state must be an object\");\n  }\n  const runtime = state as Readonly<Record<string, unknown>>;\n  for (const key of Object.keys(runtime)) {\n    if (!openStateKeys.has(key)) {\n      throw new TypeError(`Unsupported Tour open state field: ${key}`);\n    }\n  }\n  const hasOpen = Object.prototype.hasOwnProperty.call(runtime, \"open\");\n  const hasDefaultOpen = Object.prototype.hasOwnProperty.call(runtime, \"defaultOpen\");\n  if (hasOpen) {\n    if (typeof runtime.open !== \"boolean\") {\n      throw new TypeError(\"Tour open must be a boolean\");\n    }\n    if (hasDefaultOpen) {\n      throw new TypeError(\"Controlled Tour must not provide defaultOpen\");\n    }\n    if (typeof runtime.onOpenChange !== \"function\") {\n      throw new TypeError(\"Controlled Tour must provide onOpenChange\");\n    }\n    return;\n  }\n  if (hasDefaultOpen && typeof runtime.defaultOpen !== \"boolean\") {\n    throw new TypeError(\"Tour defaultOpen must be a boolean\");\n  }\n  if (runtime.onOpenChange !== undefined && typeof runtime.onOpenChange !== \"function\") {\n    throw new TypeError(\"Tour onOpenChange must be a function\");\n  }\n}\n\n/**\n * Resolves every step eagerly (not just the current one) so a renderer can\n * pre-render adjacent step cards without re-deriving position/total, mirroring\n * `resolveStepsDescriptor`. Throws if the composer returns an empty\n * announcement instead of silently leaving screen reader users with nothing.\n */\nexport function resolveTourDescriptor<Id extends string>(\n  descriptor: TourDescriptor<Id>,\n  options: ResolveTourOptions,\n): ResolvedTourDescriptor<Id> {\n  validateTourDescriptor(descriptor);\n  if (typeof options.composeAnnouncement !== \"function\") {\n    throw new TypeError(\"Tour composeAnnouncement must be a function\");\n  }\n\n  const total = descriptor.steps.length;\n  const cursorIndex = descriptor.steps.findIndex(\n    (step) => step.id === descriptor.currentStepId,\n  );\n\n  const steps = descriptor.steps.map((step, index) => {\n    const position = index + 1;\n    const announcement = options.composeAnnouncement({\n      position,\n      total,\n      title: step.title,\n      description: step.description,\n    });\n    if (typeof announcement !== \"string\" || announcement.trim().length === 0) {\n      throw new TypeError(\"Tour composeAnnouncement must return a non-empty string\");\n    }\n    return { ...step, position, total, announcement };\n  });\n\n  return {\n    accessibilityLabel: descriptor.accessibilityLabel,\n    steps,\n    // Safe: validateTourDescriptor already confirmed currentStepId matches a step.\n    currentStep: steps[cursorIndex]!,\n    isFirstStep: cursorIndex === 0,\n    isLastStep: cursorIndex === total - 1,\n  };\n}\n\n/**\n * Pure decision, no stateful session: Tour has no async side effect to guard\n * (unlike AlertDialog's confirm), so there is no busy/error phase to own —\n * only \"what step comes next,\" which is exactly what a renderer needs to call\n * `onStepChange`/`onOpenChange` itself. This follows Popover's lighter\n * pattern rather than AlertDialog's session, since nothing here needs\n * exactly-once side-effect guarding, only the ordinary exactly-once event\n * delivery a renderer's own callback already provides.\n */\nexport function resolveTourAdvance<Id extends string>(\n  descriptor: TourDescriptor<Id>,\n  reason: TourAdvanceReason,\n): TourAdvanceOutcome<Id> {\n  validateTourDescriptor(descriptor);\n  if (reason !== \"next\" && reason !== \"previous\") {\n    throw new TypeError(`Unsupported Tour advance reason: ${String(reason)}`);\n  }\n\n  const cursorIndex = descriptor.steps.findIndex(\n    (step) => step.id === descriptor.currentStepId,\n  );\n\n  if (reason === \"previous\") {\n    if (cursorIndex === 0) return { type: \"no-op\" };\n    // Safe: cursorIndex > 0 here, so cursorIndex - 1 is always in bounds.\n    return { type: \"step\", stepId: descriptor.steps[cursorIndex - 1]!.id };\n  }\n  if (cursorIndex === descriptor.steps.length - 1) {\n    return { type: \"close\", reason: \"complete\" };\n  }\n  // Safe: cursorIndex is not the last index here, so cursorIndex + 1 is in bounds.\n  return { type: \"step\", stepId: descriptor.steps[cursorIndex + 1]!.id };\n}\n\n/**\n * The step card reuses the same anchored floating-surface anatomy as\n * Tooltip/Popover instead of declaring new chrome. The backdrop reuses the\n * stronger `backdrop.modal` veil (not `backdrop.veil`) because Tour, like\n * Dialog/Sheet, blocks background interaction while open — `veil` is used\n * where the surface underneath stays reachable, which Tour's fixed\n * `outsideDismiss: false` policy says it does not.\n */\nexport const tourRecipe = {\n  slots: [\n    \"backdrop\",\n    \"card\",\n    \"title\",\n    \"description\",\n    \"counter\",\n    \"previousAction\",\n    \"nextAction\",\n    \"skipAction\",\n  ] as const,\n  card: floatingSurfaceContract,\n  backdrop: backdrop.modal,\n  maxWidth: 320,\n  gap: spacing.sm,\n  sideOffset: spacing.xs,\n  /**\n   * `context` (320ms, opacity under Reduce Motion): moving from one step's\n   * card/highlight to the next is a jump between unrelated parts of the\n   * screen, the same \"큰 화면 요소와 맥락 전환\" tier Sheet/Dialog use, not a\n   * small in-place state change.\n   */\n  transition: { enter: motionPreset.context, exit: motionPreset.exit },\n} as const;\n\n/**\n * Literal scenario names for behaviorRegistry.tour (lead wires into\n * src/behaviors.ts). Kept here, not there, so this module stays\n * self-contained per the authoring brief.\n */\nexport const tourBehaviorScenarios = [\n  \"focus-moves-to-the-step-card-on-every-step-change-not-the-anchor\",\n  \"background-is-inert-while-a-tour-is-open\",\n  \"escape-and-skip-always-exit-regardless-of-step\",\n  \"outside-pointer-does-not-dismiss\",\n  \"next-on-the-last-step-closes-with-reason-complete\",\n  \"previous-on-the-first-step-is-a-no-op\",\n  \"controlled-owner-programmatic-close-always-wins\",\n  \"unmount-or-route-change-settles-as-interrupted-exactly-once\",\n  \"reduced-motion-crossfades-the-card-without-traveling-between-anchors\",\n] as const;\n"]}