@hjmds/design-contracts 1.1.1 → 1.2.0

package/dist/bottom-info.js

@@ -0,0 +1,48 @@
+import { spacing, typography } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export function validateBottomInfoDescriptor(descriptor) {
+    if (descriptor === null || typeof descriptor !== "object") {
+        throw new TypeError("BottomInfo descriptor must be an object");
+    }
+    if (!Array.isArray(descriptor.items) || descriptor.items.length === 0) {
+        throw new RangeError("BottomInfo must contain at least one item");
+    }
+    for (const item of descriptor.items) {
+        if (typeof item !== "string" || item.trim().length === 0) {
+            throw new TypeError("BottomInfo items must not be empty");
+        }
+    }
+    if (descriptor.tone !== undefined &&
+        descriptor.tone !== "muted" &&
+        descriptor.tone !== "emphasis") {
+        throw new TypeError(`Unsupported BottomInfo tone: ${String(descriptor.tone)}`);
+    }
+}
+export const bottomInfoRecipe = {
+    slots: ["root", "item"],
+    defaults: { tone: "muted" },
+    tones: {
+        muted: semanticColors.content.secondary,
+        /** 법적 고지처럼 놓치면 안 되는 문장. 여전히 상태가 아니라 조건이다. */
+        emphasis: semanticColors.content.body,
+    },
+    textVariant: "caption",
+    gap: spacing.xxs,
+    paddingTop: spacing.sm,
+    /** 여러 줄일 때만 목록 표식을 쓴다 — 한 줄에 점을 찍으면 오히려 시끄럽다. */
+    listMarkerFrom: 2,
+};
+export const bottomInfoBehavior = {
+    controlled: [],
+    inputs: ["items", "tone"],
+    stateAxes: {},
+    web: { roles: ["list", "listitem"], keyboard: [], focus: "none" },
+    native: { roles: [], states: [], actions: [] },
+    scenarios: [
+        "it-states-a-standing-condition-not-a-state-change-so-it-has-no-tone-of-alarm",
+        "a-single-line-renders-without-a-list-marker-and-several-lines-render-as-a-list",
+        "the-text-wraps-and-is-never-truncated-because-it-is-usually-a-legal-notice",
+        "links-inside-the-copy-belong-to-the-product-not-to-this-contract",
+    ],
+};
+//# sourceMappingURL=bottom-info.js.map

package/dist/bottom-info.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bottom-info.js","sourceRoot":"","sources":["../src/bottom-info.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAoBtD,MAAM,UAAU,4BAA4B,CAAC,UAAgC;IAC3E,IAAI,UAAU,KAAK,IAAI,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1D,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;IACpE,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzD,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,IACE,UAAU,CAAC,IAAI,KAAK,SAAS;QAC7B,UAAU,CAAC,IAAI,KAAK,OAAO;QAC3B,UAAU,CAAC,IAAI,KAAK,UAAU,EAC9B,CAAC;QACD,MAAM,IAAI,SAAS,CAAC,gCAAgC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAU;IAChC,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAyB,EAAE;IAC7C,KAAK,EAAE;QACL,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;QACvC,6CAA6C;QAC7C,QAAQ,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;KACtC;IACD,WAAW,EAAE,SAAkB;IAC/B,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,UAAU,EAAE,OAAO,CAAC,EAAE;IACtB,iDAAiD;IACjD,cAAc,EAAE,CAAC;CASlB,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,EAAE;IACb,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;IACjE,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IAC9C,SAAS,EAAE;QACT,8EAA8E;QAC9E,gFAAgF;QAChF,4EAA4E;QAC5E,kEAAkE;KACnE;CACkC,CAAC","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport { spacing, typography } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * 주 행동 **아래** 붙는 작은 안내 — \"가입하면 약관에 동의하는 것으로 봅니다\",\n * \"수수료는 결제 시점에 확정됩니다\" 같은 문장. 토스 TDS의 BottomInfo와 같은 자리다.\n *\n * `Notice`와 다르다. Notice는 **지금 생긴 상태**를 알린다(오류·성공·경고). BottomInfo는\n * 화면에 늘 있는 **조건**이라 tone도 아이콘도 없고 사라지지도 않는다. Notice로 쓰면\n * 사용자가 매번 \"무슨 문제가 생겼나\" 하고 읽게 된다.\n *\n * 문단 하나 이상을 담을 수 있고, 각 문단 안의 링크(약관·자세히 보기)는 제품이 넣는다.\n */\nexport type BottomInfoTone = \"muted\" | \"emphasis\";\n\nexport type BottomInfoDescriptor = Readonly<{\n  /** 목록으로 읽히는 여러 줄. 한 줄이면 배열 하나. */\n  items: readonly string[];\n  tone?: BottomInfoTone;\n}>;\n\nexport function validateBottomInfoDescriptor(descriptor: BottomInfoDescriptor): void {\n  if (descriptor === null || typeof descriptor !== \"object\") {\n    throw new TypeError(\"BottomInfo descriptor must be an object\");\n  }\n  if (!Array.isArray(descriptor.items) || descriptor.items.length === 0) {\n    throw new RangeError(\"BottomInfo must contain at least one item\");\n  }\n  for (const item of descriptor.items) {\n    if (typeof item !== \"string\" || item.trim().length === 0) {\n      throw new TypeError(\"BottomInfo items must not be empty\");\n    }\n  }\n  if (\n    descriptor.tone !== undefined &&\n    descriptor.tone !== \"muted\" &&\n    descriptor.tone !== \"emphasis\"\n  ) {\n    throw new TypeError(`Unsupported BottomInfo tone: ${String(descriptor.tone)}`);\n  }\n}\n\nexport const bottomInfoRecipe = {\n  slots: [\"root\", \"item\"] as const,\n  defaults: { tone: \"muted\" as BottomInfoTone },\n  tones: {\n    muted: semanticColors.content.secondary,\n    /** 법적 고지처럼 놓치면 안 되는 문장. 여전히 상태가 아니라 조건이다. */\n    emphasis: semanticColors.content.body,\n  },\n  textVariant: \"caption\" as const,\n  gap: spacing.xxs,\n  paddingTop: spacing.sm,\n  /** 여러 줄일 때만 목록 표식을 쓴다 — 한 줄에 점을 찍으면 오히려 시끄럽다. */\n  listMarkerFrom: 2,\n} as const satisfies {\n  slots: readonly [\"root\", \"item\"];\n  defaults: { tone: BottomInfoTone };\n  tones: Record<BottomInfoTone, ColorReference>;\n  textVariant: keyof typeof typography;\n  gap: number;\n  paddingTop: number;\n  listMarkerFrom: number;\n};\n\nexport const bottomInfoBehavior = {\n  controlled: [],\n  inputs: [\"items\", \"tone\"],\n  stateAxes: {},\n  web: { roles: [\"list\", \"listitem\"], keyboard: [], focus: \"none\" },\n  native: { roles: [], states: [], actions: [] },\n  scenarios: [\n    \"it-states-a-standing-condition-not-a-state-change-so-it-has-no-tone-of-alarm\",\n    \"a-single-line-renders-without-a-list-marker-and-several-lines-render-as-a-list\",\n    \"the-text-wraps-and-is-never-truncated-because-it-is-usually-a-legal-notice\",\n    \"links-inside-the-copy-belong-to-the-product-not-to-this-contract\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/carousel.d.ts

@@ -1,6 +1,6 @@
 /**
- * Ant Design Carousel's infinite loop and default autoplay are intentionally
- * not reproduced — both remove the one thing this contract treats as
+ * Ant Design Carousel's default infinite loop is intentionally not reproduced;
+ * autoplay remains opt-in in both libraries — automatic movement can obscure what this contract treats as
  * non-negotiable: a reliable answer to "where am I, and where does it end".
  * See docs/carousel.md for the accessibility rationale on every point below.
  */
@@ -109,7 +109,7 @@ export declare const carouselBehavior: {
     readonly web: {
         readonly roles: readonly ["region", "group"];
         readonly keyboard: readonly ["Tab", "Enter", "Space", "ArrowLeft", "ArrowRight"];
-        readonly focus: "roving";
+        readonly focus: "native";
     };
     readonly native: {
         readonly roles: readonly ["adjustable"];

package/dist/carousel.js

@@ -107,7 +107,7 @@ export const carouselBehavior = {
     web: {
         roles: ["region", "group"],
         keyboard: ["Tab", "Enter", "Space", "ArrowLeft", "ArrowRight"],
-        focus: "roving",
+        focus: "native",
     },
     native: {
         roles: ["adjustable"],

package/dist/carousel.js.map

@@ -1 +1 @@
-{"version":3,"file":"carousel.js","sourceRoot":"","sources":["../src/carousel.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport type { SemanticIconName } from \"./icon.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport { control, motionPreset, opacity, spacing } from \"./foundations.js\";\nimport { assertFiniteNumber } from \"./number-field.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Ant Design Carousel's infinite loop and default autoplay are intentionally\n * not reproduced — both remove the one thing this contract treats as\n * non-negotiable: a reliable answer to \"where am I, and where does it end\".\n * See docs/carousel.md for the accessibility rationale on every point below.\n */\nexport type CarouselSlideDescriptor<Id extends string = string> = Readonly<{\n  id: Id;\n  /** Accessible name for the slide, e.g. \"8/19 두산 vs LG\". The slide's visual content is product-owned. */\n  label: string;\n}>;\n\nexport type CarouselAutoplayConfig = Readonly<{\n  /** Minimum time a slide stays current before an automatic advance. */\n  intervalMs: number;\n}>;\n\n/**\n * Renderer-facing prop shape only — mirrors SelectSelection's controlled/\n * uncontrolled duality, but the resolver below always takes a concrete,\n * already-resolved `currentKey` (see CarouselDescriptor) so validation and\n * position math never have to branch on which mode the product chose.\n */\nexport type ControlledCarouselSelection<Id extends string = string> = Readonly<{\n  currentKey: Id;\n  defaultCurrentKey?: never;\n  onCurrentKeyChange(key: Id): void;\n}>;\n\nexport type UncontrolledCarouselSelection<Id extends string = string> = Readonly<{\n  currentKey?: never;\n  defaultCurrentKey?: Id;\n  onCurrentKeyChange?: (key: Id) => void;\n}>;\n\nexport type CarouselSelection<Id extends string = string> =\n  | ControlledCarouselSelection<Id>\n  | UncontrolledCarouselSelection<Id>;\n\nexport type CarouselDescriptor<Id extends string = string> = Readonly<{\n  slides: readonly CarouselSlideDescriptor<Id>[];\n  currentKey: Id;\n  /** Absent by default. Autoplay is opt-in — see docs/carousel.md. */\n  autoplay?: CarouselAutoplayConfig;\n}>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`Carousel ${field} must not be empty`);\n  }\n}\n\nexport function validateCarouselSlide<Id extends string>(\n  slide: CarouselSlideDescriptor<Id>,\n): void {\n  assertNonEmpty(slide.id, \"slide id\");\n  if (slide.id !== slide.id.trim()) {\n    throw new TypeError(\"Carousel slide id must not start or end with whitespace\");\n  }\n  assertNonEmpty(slide.label, \"slide label\");\n}\n\nexport function validateCarouselAutoplayConfig(\n  autoplay: CarouselAutoplayConfig,\n): void {\n  assertFiniteNumber(autoplay.intervalMs, \"autoplay.intervalMs\");\n  if (autoplay.intervalMs <= 0) {\n    throw new RangeError(\"Carousel autoplay.intervalMs must be greater than zero\");\n  }\n}\n\nexport function validateCarouselDescriptor<Id extends string>(\n  descriptor: CarouselDescriptor<Id>,\n): void {\n  if (descriptor.slides.length === 0) {\n    throw new RangeError(\"Carousel must contain at least one slide\");\n  }\n  const ids = new Set<Id>();\n  for (const slide of descriptor.slides) {\n    validateCarouselSlide(slide);\n    if (ids.has(slide.id)) {\n      throw new TypeError(`Duplicate Carousel slide id: ${slide.id}`);\n    }\n    ids.add(slide.id);\n  }\n  if (!ids.has(descriptor.currentKey)) {\n    throw new RangeError(\n      `Carousel currentKey does not match any slide id: ${String(descriptor.currentKey)}`,\n    );\n  }\n  if (descriptor.autoplay) {\n    validateCarouselAutoplayConfig(descriptor.autoplay);\n  }\n}\n\nexport type CarouselAccessibleNameInfo = Readonly<{\n  position: number;\n  total: number;\n  label: string;\n}>;\n\n/**\n * Same reason Steps and Timeline do not assemble their own accessible name:\n * counter-word grammar and phrase order are product-owned copy decisions.\n */\nexport type ComposeCarouselAccessibleName = (\n  info: CarouselAccessibleNameInfo,\n) => string;\n\nexport type ResolvedCarouselSlideDescriptor<Id extends string = string> =\n  CarouselSlideDescriptor<Id> &\n    Readonly<{\n      /** 1-indexed so position and label both preserve reading order for renderers. */\n      position: number;\n      total: number;\n      current: boolean;\n      /**\n       * True for every slide but the current one. A renderer must exclude an\n       * inert slide's interactive content from both focus and the\n       * accessibility tree — a hidden slide whose link can still receive\n       * focus is worse than one that is simply unreachable until the user\n       * advances to it (see docs/carousel.md).\n       */\n      inert: boolean;\n      accessibleName: string;\n    }>;\n\nexport type ResolveCarouselOptions = Readonly<{\n  composeAccessibleName: ComposeCarouselAccessibleName;\n}>;\n\n/**\n * Attaches order, current/inert, and the composed accessible name used by\n * both the slide group and its indicator dot — one composer, reused for\n * every render target, the same way Steps reuses a single composer.\n */\nexport function resolveCarouselDescriptor<Id extends string>(\n  descriptor: CarouselDescriptor<Id>,\n  options: ResolveCarouselOptions,\n): readonly ResolvedCarouselSlideDescriptor<Id>[] {\n  validateCarouselDescriptor(descriptor);\n  if (typeof options.composeAccessibleName !== \"function\") {\n    throw new TypeError(\"Carousel composeAccessibleName must be a function\");\n  }\n\n  const total = descriptor.slides.length;\n  return descriptor.slides.map((slide, index) => {\n    const position = index + 1;\n    const current = slide.id === descriptor.currentKey;\n    const accessibleName = options.composeAccessibleName({\n      position,\n      total,\n      label: slide.label,\n    });\n    if (typeof accessibleName !== \"string\" || accessibleName.trim().length === 0) {\n      throw new TypeError(\n        \"Carousel composeAccessibleName must return a non-empty string\",\n      );\n    }\n    return { ...slide, position, total, current, inert: !current, accessibleName };\n  });\n}\n\nexport type CarouselNavigationIntent = \"next\" | \"previous\" | \"first\" | \"last\";\n\n/**\n * Clamps at the first/last slide instead of wrapping — infinite loop is out\n * of scope (see docs/carousel.md), so there is no modulo here at all, unlike\n * getCollectionNavigationTarget's `loop` parameter elsewhere in this package.\n */\nexport function getCarouselNavigationTarget<Id extends string>(\n  descriptor: CarouselDescriptor<Id>,\n  intent: CarouselNavigationIntent,\n): Id {\n  validateCarouselDescriptor(descriptor);\n  const { slides, currentKey } = descriptor;\n  if (intent === \"first\") return slides[0]!.id;\n  if (intent === \"last\") return slides.at(-1)!.id;\n  const currentIndex = slides.findIndex((slide) => slide.id === currentKey);\n  const delta = intent === \"next\" ? 1 : -1;\n  const clampedIndex = Math.min(\n    Math.max(currentIndex + delta, 0),\n    slides.length - 1,\n  );\n  return slides[clampedIndex]!.id;\n}\n\nexport type CarouselAutoplayInputs = Readonly<{\n  /** True whenever a platform reduce-motion preference is active. */\n  reducedMotion: boolean;\n  /** Renderer-combined pointer hover, focus-within, and drag signal. */\n  paused: boolean;\n}>;\n\n/**\n * Autoplay is never active without an explicit config, under reduce motion,\n * or while the user is hovering, focusing, or dragging the carousel — the\n * three guards the brief requires are one function so a renderer cannot wire\n * an autoplay timer that forgets one of them.\n */\nexport function isCarouselAutoplayActive(\n  autoplay: CarouselAutoplayConfig | undefined,\n  inputs: CarouselAutoplayInputs,\n): boolean {\n  if (!autoplay) return false;\n  validateCarouselAutoplayConfig(autoplay);\n  return !inputs.reducedMotion && !inputs.paused;\n}\n\nexport const carouselBehaviorDefaults = {\n  autoplay: false,\n} as const satisfies Readonly<{ autoplay: boolean }>;\n\nexport const carouselBehavior = {\n  controlled: [\"currentKey\", \"defaultCurrentKey\", \"onCurrentKeyChange\"],\n  inputs: [\"autoplay\", \"reducedMotion\", \"dragged\"],\n  defaults: carouselBehaviorDefaults,\n  stateAxes: {\n    interaction: [\"idle\", \"dragged\"],\n    value: [\"selected\"],\n  },\n  web: {\n    roles: [\"region\", \"group\"],\n    keyboard: [\"Tab\", \"Enter\", \"Space\", \"ArrowLeft\", \"ArrowRight\"],\n    focus: \"roving\",\n  },\n  native: {\n    roles: [\"adjustable\"],\n    states: [\"selected\"],\n    actions: [\"increment\", \"decrement\"],\n  },\n  scenarios: [\n    \"current-position-is-announced-with-a-readable-name-not-dots-alone\",\n    \"inactive-slide-content-is-excluded-from-focus-and-the-accessibility-tree\",\n    \"previous-next-and-dot-controls-stay-in-tab-order-regardless-of-current-slide\",\n    \"arrow-keys-move-one-slide-on-web-swipe-moves-one-slide-on-native\",\n    \"boundary-slides-clamp-instead-of-wrapping-because-loop-is-out-of-scope\",\n    \"autoplay-is-opt-in-and-off-by-default\",\n    \"autoplay-never-runs-when-reduced-motion-is-active\",\n    \"autoplay-pauses-on-hover-focus-or-drag-and-does-not-announce-automatic-transitions\",\n  ],\n} as const satisfies BehaviorContract;\n\nexport type CarouselSize = \"medium\";\n\nexport const carouselRecipe = {\n  slots: [\n    \"root\",\n    \"track\",\n    \"slide\",\n    \"dots\",\n    \"dot\",\n    \"previousControl\",\n    \"nextControl\",\n  ] as const,\n  defaults: { size: \"medium\" },\n  sizes: {\n    medium: {\n      gap: spacing.sm,\n      controlHitTarget: control.minTouchTarget,\n      controlIcon: \"sm\",\n    },\n  },\n  dot: {\n    diameter: 8,\n    hitTarget: control.minTouchTarget,\n    color: {\n      inactive: semanticColors.border.strong,\n      current: semanticColors.content.brand,\n    },\n  },\n  /** Previous/next chrome is composed from IconButton (ghost tone) rather than owning new button visuals. */\n  control: {\n    icons: {\n      previous: \"chevronStart\",\n      next: \"chevronEnd\",\n    } as const satisfies Readonly<{ previous: SemanticIconName; next: SemanticIconName }>,\n  },\n  states: {\n    focus: focusIndicatorContract,\n    draggedOpacity: opacity.dragged,\n  },\n  /**\n   * Manual slide-to-slide movement crossfades rather than snapping under\n   * Reduce Motion, reusing the existing \"context\" preset instead of a new\n   * token — autoplay itself simply does not run at all (isCarouselAutoplayActive).\n   */\n  transition: motionPreset.context,\n} as const satisfies {\n  slots: readonly string[];\n  defaults: { size: CarouselSize };\n  sizes: Record<\n    CarouselSize,\n    { gap: number; controlHitTarget: number; controlIcon: string }\n  >;\n  dot: {\n    diameter: number;\n    hitTarget: number;\n    color: Record<\"inactive\" | \"current\", ColorReference>;\n  };\n  control: {\n    icons: Readonly<{ previous: SemanticIconName; next: SemanticIconName }>;\n  };\n  states: {\n    focus: typeof focusIndicatorContract;\n    draggedOpacity: number;\n  };\n  transition: typeof motionPreset.context;\n};\n"]}
+{"version":3,"file":"carousel.js","sourceRoot":"","sources":["../src/carousel.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport type { SemanticIconName } from \"./icon.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport { control, motionPreset, opacity, spacing } from \"./foundations.js\";\nimport { assertFiniteNumber } from \"./number-field.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Ant Design Carousel's default infinite loop is intentionally not reproduced;\n * autoplay remains opt-in in both libraries — automatic movement can obscure what this contract treats as\n * non-negotiable: a reliable answer to \"where am I, and where does it end\".\n * See docs/carousel.md for the accessibility rationale on every point below.\n */\nexport type CarouselSlideDescriptor<Id extends string = string> = Readonly<{\n  id: Id;\n  /** Accessible name for the slide, e.g. \"8/19 두산 vs LG\". The slide's visual content is product-owned. */\n  label: string;\n}>;\n\nexport type CarouselAutoplayConfig = Readonly<{\n  /** Minimum time a slide stays current before an automatic advance. */\n  intervalMs: number;\n}>;\n\n/**\n * Renderer-facing prop shape only — mirrors SelectSelection's controlled/\n * uncontrolled duality, but the resolver below always takes a concrete,\n * already-resolved `currentKey` (see CarouselDescriptor) so validation and\n * position math never have to branch on which mode the product chose.\n */\nexport type ControlledCarouselSelection<Id extends string = string> = Readonly<{\n  currentKey: Id;\n  defaultCurrentKey?: never;\n  onCurrentKeyChange(key: Id): void;\n}>;\n\nexport type UncontrolledCarouselSelection<Id extends string = string> = Readonly<{\n  currentKey?: never;\n  defaultCurrentKey?: Id;\n  onCurrentKeyChange?: (key: Id) => void;\n}>;\n\nexport type CarouselSelection<Id extends string = string> =\n  | ControlledCarouselSelection<Id>\n  | UncontrolledCarouselSelection<Id>;\n\nexport type CarouselDescriptor<Id extends string = string> = Readonly<{\n  slides: readonly CarouselSlideDescriptor<Id>[];\n  currentKey: Id;\n  /** Absent by default. Autoplay is opt-in — see docs/carousel.md. */\n  autoplay?: CarouselAutoplayConfig;\n}>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`Carousel ${field} must not be empty`);\n  }\n}\n\nexport function validateCarouselSlide<Id extends string>(\n  slide: CarouselSlideDescriptor<Id>,\n): void {\n  assertNonEmpty(slide.id, \"slide id\");\n  if (slide.id !== slide.id.trim()) {\n    throw new TypeError(\"Carousel slide id must not start or end with whitespace\");\n  }\n  assertNonEmpty(slide.label, \"slide label\");\n}\n\nexport function validateCarouselAutoplayConfig(\n  autoplay: CarouselAutoplayConfig,\n): void {\n  assertFiniteNumber(autoplay.intervalMs, \"autoplay.intervalMs\");\n  if (autoplay.intervalMs <= 0) {\n    throw new RangeError(\"Carousel autoplay.intervalMs must be greater than zero\");\n  }\n}\n\nexport function validateCarouselDescriptor<Id extends string>(\n  descriptor: CarouselDescriptor<Id>,\n): void {\n  if (descriptor.slides.length === 0) {\n    throw new RangeError(\"Carousel must contain at least one slide\");\n  }\n  const ids = new Set<Id>();\n  for (const slide of descriptor.slides) {\n    validateCarouselSlide(slide);\n    if (ids.has(slide.id)) {\n      throw new TypeError(`Duplicate Carousel slide id: ${slide.id}`);\n    }\n    ids.add(slide.id);\n  }\n  if (!ids.has(descriptor.currentKey)) {\n    throw new RangeError(\n      `Carousel currentKey does not match any slide id: ${String(descriptor.currentKey)}`,\n    );\n  }\n  if (descriptor.autoplay) {\n    validateCarouselAutoplayConfig(descriptor.autoplay);\n  }\n}\n\nexport type CarouselAccessibleNameInfo = Readonly<{\n  position: number;\n  total: number;\n  label: string;\n}>;\n\n/**\n * Same reason Steps and Timeline do not assemble their own accessible name:\n * counter-word grammar and phrase order are product-owned copy decisions.\n */\nexport type ComposeCarouselAccessibleName = (\n  info: CarouselAccessibleNameInfo,\n) => string;\n\nexport type ResolvedCarouselSlideDescriptor<Id extends string = string> =\n  CarouselSlideDescriptor<Id> &\n    Readonly<{\n      /** 1-indexed so position and label both preserve reading order for renderers. */\n      position: number;\n      total: number;\n      current: boolean;\n      /**\n       * True for every slide but the current one. A renderer must exclude an\n       * inert slide's interactive content from both focus and the\n       * accessibility tree — a hidden slide whose link can still receive\n       * focus is worse than one that is simply unreachable until the user\n       * advances to it (see docs/carousel.md).\n       */\n      inert: boolean;\n      accessibleName: string;\n    }>;\n\nexport type ResolveCarouselOptions = Readonly<{\n  composeAccessibleName: ComposeCarouselAccessibleName;\n}>;\n\n/**\n * Attaches order, current/inert, and the composed accessible name used by\n * both the slide group and its indicator dot — one composer, reused for\n * every render target, the same way Steps reuses a single composer.\n */\nexport function resolveCarouselDescriptor<Id extends string>(\n  descriptor: CarouselDescriptor<Id>,\n  options: ResolveCarouselOptions,\n): readonly ResolvedCarouselSlideDescriptor<Id>[] {\n  validateCarouselDescriptor(descriptor);\n  if (typeof options.composeAccessibleName !== \"function\") {\n    throw new TypeError(\"Carousel composeAccessibleName must be a function\");\n  }\n\n  const total = descriptor.slides.length;\n  return descriptor.slides.map((slide, index) => {\n    const position = index + 1;\n    const current = slide.id === descriptor.currentKey;\n    const accessibleName = options.composeAccessibleName({\n      position,\n      total,\n      label: slide.label,\n    });\n    if (typeof accessibleName !== \"string\" || accessibleName.trim().length === 0) {\n      throw new TypeError(\n        \"Carousel composeAccessibleName must return a non-empty string\",\n      );\n    }\n    return { ...slide, position, total, current, inert: !current, accessibleName };\n  });\n}\n\nexport type CarouselNavigationIntent = \"next\" | \"previous\" | \"first\" | \"last\";\n\n/**\n * Clamps at the first/last slide instead of wrapping — infinite loop is out\n * of scope (see docs/carousel.md), so there is no modulo here at all, unlike\n * getCollectionNavigationTarget's `loop` parameter elsewhere in this package.\n */\nexport function getCarouselNavigationTarget<Id extends string>(\n  descriptor: CarouselDescriptor<Id>,\n  intent: CarouselNavigationIntent,\n): Id {\n  validateCarouselDescriptor(descriptor);\n  const { slides, currentKey } = descriptor;\n  if (intent === \"first\") return slides[0]!.id;\n  if (intent === \"last\") return slides.at(-1)!.id;\n  const currentIndex = slides.findIndex((slide) => slide.id === currentKey);\n  const delta = intent === \"next\" ? 1 : -1;\n  const clampedIndex = Math.min(\n    Math.max(currentIndex + delta, 0),\n    slides.length - 1,\n  );\n  return slides[clampedIndex]!.id;\n}\n\nexport type CarouselAutoplayInputs = Readonly<{\n  /** True whenever a platform reduce-motion preference is active. */\n  reducedMotion: boolean;\n  /** Renderer-combined pointer hover, focus-within, and drag signal. */\n  paused: boolean;\n}>;\n\n/**\n * Autoplay is never active without an explicit config, under reduce motion,\n * or while the user is hovering, focusing, or dragging the carousel — the\n * three guards the brief requires are one function so a renderer cannot wire\n * an autoplay timer that forgets one of them.\n */\nexport function isCarouselAutoplayActive(\n  autoplay: CarouselAutoplayConfig | undefined,\n  inputs: CarouselAutoplayInputs,\n): boolean {\n  if (!autoplay) return false;\n  validateCarouselAutoplayConfig(autoplay);\n  return !inputs.reducedMotion && !inputs.paused;\n}\n\nexport const carouselBehaviorDefaults = {\n  autoplay: false,\n} as const satisfies Readonly<{ autoplay: boolean }>;\n\nexport const carouselBehavior = {\n  controlled: [\"currentKey\", \"defaultCurrentKey\", \"onCurrentKeyChange\"],\n  inputs: [\"autoplay\", \"reducedMotion\", \"dragged\"],\n  defaults: carouselBehaviorDefaults,\n  stateAxes: {\n    interaction: [\"idle\", \"dragged\"],\n    value: [\"selected\"],\n  },\n  web: {\n    roles: [\"region\", \"group\"],\n    keyboard: [\"Tab\", \"Enter\", \"Space\", \"ArrowLeft\", \"ArrowRight\"],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"adjustable\"],\n    states: [\"selected\"],\n    actions: [\"increment\", \"decrement\"],\n  },\n  scenarios: [\n    \"current-position-is-announced-with-a-readable-name-not-dots-alone\",\n    \"inactive-slide-content-is-excluded-from-focus-and-the-accessibility-tree\",\n    \"previous-next-and-dot-controls-stay-in-tab-order-regardless-of-current-slide\",\n    \"arrow-keys-move-one-slide-on-web-swipe-moves-one-slide-on-native\",\n    \"boundary-slides-clamp-instead-of-wrapping-because-loop-is-out-of-scope\",\n    \"autoplay-is-opt-in-and-off-by-default\",\n    \"autoplay-never-runs-when-reduced-motion-is-active\",\n    \"autoplay-pauses-on-hover-focus-or-drag-and-does-not-announce-automatic-transitions\",\n  ],\n} as const satisfies BehaviorContract;\n\nexport type CarouselSize = \"medium\";\n\nexport const carouselRecipe = {\n  slots: [\n    \"root\",\n    \"track\",\n    \"slide\",\n    \"dots\",\n    \"dot\",\n    \"previousControl\",\n    \"nextControl\",\n  ] as const,\n  defaults: { size: \"medium\" },\n  sizes: {\n    medium: {\n      gap: spacing.sm,\n      controlHitTarget: control.minTouchTarget,\n      controlIcon: \"sm\",\n    },\n  },\n  dot: {\n    diameter: 8,\n    hitTarget: control.minTouchTarget,\n    color: {\n      inactive: semanticColors.border.strong,\n      current: semanticColors.content.brand,\n    },\n  },\n  /** Previous/next chrome is composed from IconButton (ghost tone) rather than owning new button visuals. */\n  control: {\n    icons: {\n      previous: \"chevronStart\",\n      next: \"chevronEnd\",\n    } as const satisfies Readonly<{ previous: SemanticIconName; next: SemanticIconName }>,\n  },\n  states: {\n    focus: focusIndicatorContract,\n    draggedOpacity: opacity.dragged,\n  },\n  /**\n   * Manual slide-to-slide movement crossfades rather than snapping under\n   * Reduce Motion, reusing the existing \"context\" preset instead of a new\n   * token — autoplay itself simply does not run at all (isCarouselAutoplayActive).\n   */\n  transition: motionPreset.context,\n} as const satisfies {\n  slots: readonly string[];\n  defaults: { size: CarouselSize };\n  sizes: Record<\n    CarouselSize,\n    { gap: number; controlHitTarget: number; controlIcon: string }\n  >;\n  dot: {\n    diameter: number;\n    hitTarget: number;\n    color: Record<\"inactive\" | \"current\", ColorReference>;\n  };\n  control: {\n    icons: Readonly<{ previous: SemanticIconName; next: SemanticIconName }>;\n  };\n  states: {\n    focus: typeof focusIndicatorContract;\n    draggedOpacity: number;\n  };\n  transition: typeof motionPreset.context;\n};\n"]}