@hjmds/design-contracts 1.1.1 → 1.3.4

package/dist/tags-input.js

@@ -0,0 +1,108 @@
+import { fieldFrameContract, focusIndicatorContract } from "./component-contracts.js";
+import { control, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+/**
+ * 활성 후보를 방향키로 옮긴 결과. 목록 끝에서 순환한다 — 후보가 보통 짧아서 끝에
+ * 막히면 반대 끝까지 다시 내려가야 한다.
+ */
+export function resolveTagsInputActiveSuggestion(suggestions, currentId, direction) {
+    const enabled = suggestions.filter((item) => item.disabled !== true);
+    if (enabled.length === 0)
+        return null;
+    const index = enabled.findIndex((item) => item.id === currentId);
+    if (index === -1)
+        return direction === "next" ? enabled[0].id : enabled.at(-1).id;
+    const next = direction === "next" ? index + 1 : index - 1;
+    return enabled[(next + enabled.length) % enabled.length].id;
+}
+export const tagsInputBehaviorDefaults = {
+    /**
+     * Enter만 기본이다. 쉼표·공백은 언어에 따라 값의 일부다(한국어 태그에 공백이 흔하다).
+     * 제품이 자기 도메인을 알 때 켠다.
+     */
+    commitKeys: ["Enter"],
+    /** 빈 입력에서 Backspace는 마지막 태그를 **선택**만 한다. 한 번 더 눌러야 지운다. */
+    backspaceRemovesLastTag: false,
+};
+/**
+ * 태그 하나를 확정할 수 있는지 판정한다. 값을 바꾸지 않고 결과만 돌려준다 —
+ * 실제 상태 갱신은 renderer가, 사용자에게 보여 줄 문장은 제품이 만든다.
+ */
+export function resolveTagsInputCommit(current, rawValue, policy = {}) {
+    const value = rawValue.trim();
+    if (value.length === 0)
+        return { accepted: false, value, reason: "empty" };
+    if (policy.allowDuplicates !== true && current.includes(value)) {
+        return { accepted: false, value, reason: "duplicate" };
+    }
+    if (policy.maxTags !== undefined && current.length >= policy.maxTags) {
+        return { accepted: false, value, reason: "limit" };
+    }
+    if (policy.isValid !== undefined && !policy.isValid(value)) {
+        return { accepted: false, value, reason: "invalid" };
+    }
+    return { accepted: true, value };
+}
+/** 태그 하나를 뺀 목록. 같은 값이 여러 개면 해당 위치 하나만 지운다. */
+export function removeTagAt(current, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= current.length) {
+        throw new RangeError(`TagsInput index out of range: ${String(index)}`);
+    }
+    return [...current.slice(0, index), ...current.slice(index + 1)];
+}
+export const tagsInputRecipe = {
+    slots: ["root", "frame", "tag", "remove", "input"],
+    defaults: { commitKeys: tagsInputBehaviorDefaults.commitKeys },
+    frame: {
+        minHeight: fieldFrameContract.minHeight,
+        paddingHorizontal: fieldFrameContract.paddingHorizontal,
+        paddingVertical: spacing.xxs,
+        gap: spacing.xs,
+        border: fieldFrameContract.border,
+        background: fieldFrameContract.background,
+    },
+    tag: {
+        minHeight: 28,
+        paddingHorizontal: spacing.xs,
+        gap: spacing.xxs,
+        background: semanticColors.surface.sunken,
+        color: semanticColors.content.body,
+    },
+    /** 삭제 버튼은 태그보다 작아도 되지만 포인터 타깃은 공용 최소값을 지킨다. */
+    remove: { minTouchTarget: control.minTouchTarget, color: semanticColors.content.secondary },
+    selectedTagOutline: semanticColors.border.focus,
+    states: { focus: focusIndicatorContract },
+};
+export const tagsInputBehavior = {
+    controlled: ["tags", "defaultTags", "onTagsChange"],
+    inputs: ["policy", "commitKeys", "label", "removeLabel"],
+    /**
+     * `onDraftChange`가 없으면 제품이 후보를 거를 수 없다 — 무엇을 입력 중인지 모르기
+     * 때문이다. 후보 목록을 계약에 넣는 순간 이 이벤트도 함께 필요하다.
+     */
+    events: ["onReject", "onDraftChange"],
+    defaults: { backspaceRemovesLastTag: tagsInputBehaviorDefaults.backspaceRemovesLastTag },
+    stateAxes: {
+        availability: ["enabled", "disabled"],
+        value: ["empty", "filled"],
+        validation: ["valid", "invalid"],
+    },
+    web: {
+        roles: ["combobox", "listbox", "option", "button", "list", "listitem"],
+        keyboard: ["Enter", "Backspace", "ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Escape", "Tab"],
+        focus: "native",
+    },
+    native: { roles: ["button"], states: ["disabled"], actions: ["commit", "remove"] },
+    scenarios: [
+        "enter-commits-the-trimmed-value-and-clears-the-input",
+        "an-empty-or-whitespace-only-value-is-never-committed",
+        "duplicates-are-rejected-by-default-and-the-reason-is-reported-not-swallowed",
+        "backspace-in-an-empty-input-selects-the-last-tag-before-a-second-press-removes-it",
+        "every-tag-carries-its-own-remove-control-with-a-localized-name",
+        "the-policy-judges-and-the-product-writes-the-sentence-the-user-reads",
+        "a-candidate-list-lives-in-this-field-because-the-value-shape-is-this-fields-not-comboboxs",
+        "enter-commits-the-active-candidate-when-one-is-highlighted-and-the-typed-text-otherwise",
+        "candidate-filtering-belongs-to-the-product-the-contract-only-commits-the-choice",
+    ],
+};
+//# sourceMappingURL=tags-input.js.map

package/dist/tags-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tags-input.js","sourceRoot":"","sources":["../src/tags-input.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACtF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAmCtD;;;GAGG;AACH,MAAM,UAAU,gCAAgC,CAC9C,WAA2C,EAC3C,SAAwB,EACxB,SAA8B;IAE9B,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;IACrE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC;IACjE,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;IACpF,MAAM,IAAI,GAAG,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC;IAC1D,OAAO,OAAO,CAAC,CAAC,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAE,CAAC,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,CAAkC;IACtD,2DAA2D;IAC3D,uBAAuB,EAAE,KAAK;CACtB,CAAC;AAmBX;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAA0B,EAC1B,QAAgB,EAChB,SAA0B,EAAE;IAE5B,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAC3E,IAAI,MAAM,CAAC,eAAe,KAAK,IAAI,IAAI,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACzD,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACrE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IACrD,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACnC,CAAC;AAED,8CAA8C;AAC9C,MAAM,UAAU,WAAW,CAAC,OAA0B,EAAE,KAAa;IACnE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACrE,MAAM,IAAI,UAAU,CAAC,iCAAiC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAU;IAC3D,QAAQ,EAAE,EAAE,UAAU,EAAE,yBAAyB,CAAC,UAAU,EAAE;IAC9D,KAAK,EAAE;QACL,SAAS,EAAE,kBAAkB,CAAC,SAAS;QACvC,iBAAiB,EAAE,kBAAkB,CAAC,iBAAiB;QACvD,eAAe,EAAE,OAAO,CAAC,GAAG;QAC5B,GAAG,EAAE,OAAO,CAAC,EAAE;QACf,MAAM,EAAE,kBAAkB,CAAC,MAAM;QACjC,UAAU,EAAE,kBAAkB,CAAC,UAAU;KAC1C;IACD,GAAG,EAAE;QACH,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,OAAO,CAAC,EAAE;QAC7B,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM;QACzC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;KACnC;IACD,+CAA+C;IAC/C,MAAM,EAAE,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS,EAAE;IAC3F,kBAAkB,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK;IAC/C,MAAM,EAAE,EAAE,KAAK,EAAE,sBAAsB,EAAE;CAgB1C,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,UAAU,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,cAAc,CAAC;IACnD,MAAM,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,CAAC;IACxD;;;OAGG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,EAAE,EAAE,uBAAuB,EAAE,yBAAyB,CAAC,uBAAuB,EAAE;IACxF,SAAS,EAAE;QACT,YAAY,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;QACrC,KAAK,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC1B,UAAU,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC;KACjC;IACD,GAAG,EAAE;QACH,KAAK,EAAE,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC;QACtE,QAAQ,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,KAAK,CAAC;QACpG,KAAK,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE;IAClF,SAAS,EAAE;QACT,sDAAsD;QACtD,sDAAsD;QACtD,6EAA6E;QAC7E,mFAAmF;QACnF,gEAAgE;QAChE,sEAAsE;QACtE,2FAA2F;QAC3F,yFAAyF;QACzF,iFAAiF;KAClF;CACkC,CAAC","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport { fieldFrameContract, focusIndicatorContract } from \"./component-contracts.js\";\nimport { control, spacing } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * 자유 입력으로 여러 값을 모으는 필드 — 해시태그, 초대할 사람, 검색 필터.\n *\n * Combobox와 다르다. Combobox는 **주어진 목록에서 고른다**. TagsInput은 목록이 없거나\n * 있어도 목록 밖의 값을 만들 수 있다. 그래서 Combobox에 `multiple` 축을 붙이는 대신\n * 별도로 둔다 — 합치면 \"목록에 없는 값을 고를 수 있는 Select\"라는 모순이 생긴다.\n * (제품이 후보 목록을 함께 보여 주고 싶으면 이 필드와 Combobox의 listbox를 조합한다.)\n *\n * 이 계약이 소유하는 것은 **언제 태그가 확정되는가**와 **빈 입력에서 지우면 무엇이\n * 지워지는가** 둘이다. 중복 허용 여부·최대 개수·글자 규칙은 제품 정책이라 판정 결과를\n * 받기만 한다.\n */\nexport type TagsInputCommitKey = \"Enter\" | \"Comma\" | \"Space\" | \"Blur\";\n\n/**\n * 후보 목록. Combobox의 listbox 계약을 **이 필드 안에서** 쓰는 형태다.\n *\n * \"Combobox에 multiple을 붙이자\"가 아니라 여기로 온 이유: Combobox의 값은 목록 안의\n * 키 하나이고 이 필드의 값은 문자열 배열이다. 값 모양이 다른 둘을 한 컴포넌트에 넣으면\n * 모든 소비자가 매번 좁히기를 해야 한다. 자유 입력이 이미 여기 있으므로 후보를 여기에\n * 더하는 쪽이 값 하나로 끝난다.\n *\n * 필터링은 제품이 한다 — 이 계약은 \"무엇을 보여줄지\"가 아니라 \"고른 것을 어떻게\n * 확정할지\"만 안다.\n */\nexport type TagsInputSuggestion = Readonly<{\n  id: string;\n  label: string;\n  /** 확정될 문자열. 생략하면 `label`. */\n  value?: string;\n  disabled?: boolean;\n}>;\n\n/**\n * 활성 후보를 방향키로 옮긴 결과. 목록 끝에서 순환한다 — 후보가 보통 짧아서 끝에\n * 막히면 반대 끝까지 다시 내려가야 한다.\n */\nexport function resolveTagsInputActiveSuggestion(\n  suggestions: readonly TagsInputSuggestion[],\n  currentId: string | null,\n  direction: \"next\" | \"previous\",\n): string | null {\n  const enabled = suggestions.filter((item) => item.disabled !== true);\n  if (enabled.length === 0) return null;\n  const index = enabled.findIndex((item) => item.id === currentId);\n  if (index === -1) return direction === \"next\" ? enabled[0]!.id : enabled.at(-1)!.id;\n  const next = direction === \"next\" ? index + 1 : index - 1;\n  return enabled[(next + enabled.length) % enabled.length]!.id;\n}\n\nexport const tagsInputBehaviorDefaults = {\n  /**\n   * Enter만 기본이다. 쉼표·공백은 언어에 따라 값의 일부다(한국어 태그에 공백이 흔하다).\n   * 제품이 자기 도메인을 알 때 켠다.\n   */\n  commitKeys: [\"Enter\"] as readonly TagsInputCommitKey[],\n  /** 빈 입력에서 Backspace는 마지막 태그를 **선택**만 한다. 한 번 더 눌러야 지운다. */\n  backspaceRemovesLastTag: false,\n} as const;\n\nexport type TagsInputRejectionReason = \"empty\" | \"duplicate\" | \"limit\" | \"invalid\";\n\nexport type TagsInputCommitResult = Readonly<{\n  accepted: boolean;\n  /** 정리된 값(앞뒤 공백 제거). 거절돼도 제품이 문구에 쓸 수 있게 돌려준다. */\n  value: string;\n  reason?: TagsInputRejectionReason;\n}>;\n\nexport type TagsInputPolicy = Readonly<{\n  /** 같은 값을 다시 넣을 수 있는가. 기본은 막는다. */\n  allowDuplicates?: boolean;\n  maxTags?: number;\n  /** 제품 도메인 규칙. 실패 사유는 `invalid` 하나로 합쳐 돌려준다. */\n  isValid?: (value: string) => boolean;\n}>;\n\n/**\n * 태그 하나를 확정할 수 있는지 판정한다. 값을 바꾸지 않고 결과만 돌려준다 —\n * 실제 상태 갱신은 renderer가, 사용자에게 보여 줄 문장은 제품이 만든다.\n */\nexport function resolveTagsInputCommit(\n  current: readonly string[],\n  rawValue: string,\n  policy: TagsInputPolicy = {},\n): TagsInputCommitResult {\n  const value = rawValue.trim();\n  if (value.length === 0) return { accepted: false, value, reason: \"empty\" };\n  if (policy.allowDuplicates !== true && current.includes(value)) {\n    return { accepted: false, value, reason: \"duplicate\" };\n  }\n  if (policy.maxTags !== undefined && current.length >= policy.maxTags) {\n    return { accepted: false, value, reason: \"limit\" };\n  }\n  if (policy.isValid !== undefined && !policy.isValid(value)) {\n    return { accepted: false, value, reason: \"invalid\" };\n  }\n  return { accepted: true, value };\n}\n\n/** 태그 하나를 뺀 목록. 같은 값이 여러 개면 해당 위치 하나만 지운다. */\nexport function removeTagAt(current: readonly string[], index: number): readonly string[] {\n  if (!Number.isInteger(index) || index < 0 || index >= current.length) {\n    throw new RangeError(`TagsInput index out of range: ${String(index)}`);\n  }\n  return [...current.slice(0, index), ...current.slice(index + 1)];\n}\n\nexport const tagsInputRecipe = {\n  slots: [\"root\", \"frame\", \"tag\", \"remove\", \"input\"] as const,\n  defaults: { commitKeys: tagsInputBehaviorDefaults.commitKeys },\n  frame: {\n    minHeight: fieldFrameContract.minHeight,\n    paddingHorizontal: fieldFrameContract.paddingHorizontal,\n    paddingVertical: spacing.xxs,\n    gap: spacing.xs,\n    border: fieldFrameContract.border,\n    background: fieldFrameContract.background,\n  },\n  tag: {\n    minHeight: 28,\n    paddingHorizontal: spacing.xs,\n    gap: spacing.xxs,\n    background: semanticColors.surface.sunken,\n    color: semanticColors.content.body,\n  },\n  /** 삭제 버튼은 태그보다 작아도 되지만 포인터 타깃은 공용 최소값을 지킨다. */\n  remove: { minTouchTarget: control.minTouchTarget, color: semanticColors.content.secondary },\n  selectedTagOutline: semanticColors.border.focus,\n  states: { focus: focusIndicatorContract },\n} as const satisfies {\n  slots: readonly [\"root\", \"frame\", \"tag\", \"remove\", \"input\"];\n  defaults: { commitKeys: readonly TagsInputCommitKey[] };\n  frame: {\n    minHeight: number;\n    paddingHorizontal: number;\n    paddingVertical: number;\n    gap: number;\n    border: ColorReference;\n    background: ColorReference;\n  };\n  tag: { minHeight: number; paddingHorizontal: number; gap: number; background: ColorReference; color: ColorReference };\n  remove: { minTouchTarget: number; color: ColorReference };\n  selectedTagOutline: ColorReference;\n  states: { focus: typeof focusIndicatorContract };\n};\n\nexport const tagsInputBehavior = {\n  controlled: [\"tags\", \"defaultTags\", \"onTagsChange\"],\n  inputs: [\"policy\", \"commitKeys\", \"label\", \"removeLabel\"],\n  /**\n   * `onDraftChange`가 없으면 제품이 후보를 거를 수 없다 — 무엇을 입력 중인지 모르기\n   * 때문이다. 후보 목록을 계약에 넣는 순간 이 이벤트도 함께 필요하다.\n   */\n  events: [\"onReject\", \"onDraftChange\"],\n  defaults: { backspaceRemovesLastTag: tagsInputBehaviorDefaults.backspaceRemovesLastTag },\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\"],\n    value: [\"empty\", \"filled\"],\n    validation: [\"valid\", \"invalid\"],\n  },\n  web: {\n    roles: [\"combobox\", \"listbox\", \"option\", \"button\", \"list\", \"listitem\"],\n    keyboard: [\"Enter\", \"Backspace\", \"ArrowUp\", \"ArrowDown\", \"ArrowLeft\", \"ArrowRight\", \"Escape\", \"Tab\"],\n    focus: \"native\",\n  },\n  native: { roles: [\"button\"], states: [\"disabled\"], actions: [\"commit\", \"remove\"] },\n  scenarios: [\n    \"enter-commits-the-trimmed-value-and-clears-the-input\",\n    \"an-empty-or-whitespace-only-value-is-never-committed\",\n    \"duplicates-are-rejected-by-default-and-the-reason-is-reported-not-swallowed\",\n    \"backspace-in-an-empty-input-selects-the-last-tag-before-a-second-press-removes-it\",\n    \"every-tag-carries-its-own-remove-control-with-a-localized-name\",\n    \"the-policy-judges-and-the-product-writes-the-sentence-the-user-reads\",\n    \"a-candidate-list-lives-in-this-field-because-the-value-shape-is-this-fields-not-comboboxs\",\n    \"enter-commits-the-active-candidate-when-one-is-highlighted-and-the-typed-text-otherwise\",\n    \"candidate-filtering-belongs-to-the-product-the-contract-only-commits-the-choice\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/text-formats.d.ts

@@ -0,0 +1,85 @@
+/**
+ * `Text` 하나로는 만들 수 없는 **의미 있는 글자 조각들**이다 — 단축키, 코드, 인용.
+ * 도움말·개발자 문서·약관 본문이 반복해서 필요로 하고, 지금까지는 제품이 `<kbd>`에
+ * 직접 CSS를 붙여 만들었다.
+ *
+ * 왜 `Text`의 variant가 아닌가: 이들은 **크기가 아니라 요소**다. `<kbd>`, `<code>`,
+ * `<blockquote>`는 각자 의미를 가진 HTML 요소이고 보조기기가 다르게 읽는다. variant로
+ * 두면 `<span>`에 코드처럼 보이는 스타일만 입히게 되고, 그 차이가 사라진다.
+ */
+export type TextFormatKind = "kbd" | "code" | "quote";
+export declare const textFormatRecipe: {
+    readonly slots: readonly ["root"];
+    readonly kbd: {
+        readonly fontFamily: readonly ["ui-monospace", "SFMono-Regular", "Consolas", "Liberation Mono", "monospace"];
+        readonly textVariant: "label";
+        readonly paddingHorizontal: 4;
+        readonly radius: 8;
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surfaceAlt";
+            alpha?: number;
+        }>;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+    };
+    readonly code: {
+        readonly fontFamily: readonly ["ui-monospace", "SFMono-Regular", "Consolas", "Liberation Mono", "monospace"];
+        readonly textVariant: "body";
+        readonly paddingHorizontal: 4;
+        readonly radius: 8;
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surfaceAlt";
+            alpha?: number;
+        }>;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+    };
+    readonly quote: {
+        readonly textVariant: "body";
+        readonly paddingInlineStart: 16;
+        readonly borderWidth: 2;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+    };
+};
+export declare const textFormatBehavior: {
+    readonly controlled: readonly [];
+    readonly inputs: readonly ["kind"];
+    readonly configuration: {
+        readonly kind: readonly ["kbd", "code", "quote"];
+    };
+    readonly stateAxes: {};
+    readonly web: {
+        readonly roles: readonly [];
+        readonly keyboard: readonly [];
+        readonly focus: "none";
+    };
+    readonly native: {
+        readonly roles: readonly [];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["each-kind-emits-its-own-html-element-so-assistive-technology-reads-it-as-what-it-is", "these-are-elements-not-text-sizes-which-is-why-they-are-not-a-text-variant", "a-key-name-is-product-copy-because-the-same-key-is-called-different-things-per-platform"];
+};
+//# sourceMappingURL=text-formats.d.ts.map

package/dist/text-formats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-formats.d.ts","sourceRoot":"","sources":["../src/text-formats.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;AAEtD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoD5B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;CAYM,CAAC"}

package/dist/text-formats.js

@@ -0,0 +1,43 @@
+import { fontFamily, radius, spacing, typography } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const textFormatRecipe = {
+    slots: ["root"],
+    kbd: {
+        fontFamily: fontFamily.code,
+        textVariant: "label",
+        paddingHorizontal: spacing.xxs,
+        radius: radius.sm,
+        background: semanticColors.surface.sunken,
+        color: semanticColors.content.body,
+        border: semanticColors.border.default,
+    },
+    code: {
+        fontFamily: fontFamily.code,
+        textVariant: "body",
+        paddingHorizontal: spacing.xxs,
+        radius: radius.sm,
+        background: semanticColors.surface.sunken,
+        color: semanticColors.content.primary,
+    },
+    quote: {
+        textVariant: "body",
+        paddingInlineStart: spacing.md,
+        borderWidth: 2,
+        border: semanticColors.border.default,
+        color: semanticColors.content.body,
+    },
+};
+export const textFormatBehavior = {
+    controlled: [],
+    inputs: ["kind"],
+    configuration: { kind: ["kbd", "code", "quote"] },
+    stateAxes: {},
+    web: { roles: [], keyboard: [], focus: "none" },
+    native: { roles: [], states: [], actions: [] },
+    scenarios: [
+        "each-kind-emits-its-own-html-element-so-assistive-technology-reads-it-as-what-it-is",
+        "these-are-elements-not-text-sizes-which-is-why-they-are-not-a-text-variant",
+        "a-key-name-is-product-copy-because-the-same-key-is-called-different-things-per-platform",
+    ],
+};
+//# sourceMappingURL=text-formats.js.map

package/dist/text-formats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-formats.js","sourceRoot":"","sources":["../src/text-formats.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAatD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,CAAU;IACxB,GAAG,EAAE;QACH,UAAU,EAAE,UAAU,CAAC,IAAI;QAC3B,WAAW,EAAE,OAAgB;QAC7B,iBAAiB,EAAE,OAAO,CAAC,GAAG;QAC9B,MAAM,EAAE,MAAM,CAAC,EAAE;QACjB,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM;QACzC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;QAClC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO;KACtC;IACD,IAAI,EAAE;QACJ,UAAU,EAAE,UAAU,CAAC,IAAI;QAC3B,WAAW,EAAE,MAAe;QAC5B,iBAAiB,EAAE,OAAO,CAAC,GAAG;QAC9B,MAAM,EAAE,MAAM,CAAC,EAAE;QACjB,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM;QACzC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,OAAO;KACtC;IACD,KAAK,EAAE;QACL,WAAW,EAAE,MAAe;QAC5B,kBAAkB,EAAE,OAAO,CAAC,EAAE;QAC9B,WAAW,EAAE,CAAC;QACd,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO;QACrC,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;KACnC;CA2BF,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,CAAC,MAAM,CAAC;IAChB,aAAa,EAAE,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IACjD,SAAS,EAAE,EAAE;IACb,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;IAC/C,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IAC9C,SAAS,EAAE;QACT,qFAAqF;QACrF,4EAA4E;QAC5E,yFAAyF;KAC1F;CACkC,CAAC","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport { fontFamily, radius, spacing, typography } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * `Text` 하나로는 만들 수 없는 **의미 있는 글자 조각들**이다 — 단축키, 코드, 인용.\n * 도움말·개발자 문서·약관 본문이 반복해서 필요로 하고, 지금까지는 제품이 `<kbd>`에\n * 직접 CSS를 붙여 만들었다.\n *\n * 왜 `Text`의 variant가 아닌가: 이들은 **크기가 아니라 요소**다. `<kbd>`, `<code>`,\n * `<blockquote>`는 각자 의미를 가진 HTML 요소이고 보조기기가 다르게 읽는다. variant로\n * 두면 `<span>`에 코드처럼 보이는 스타일만 입히게 되고, 그 차이가 사라진다.\n */\nexport type TextFormatKind = \"kbd\" | \"code\" | \"quote\";\n\nexport const textFormatRecipe = {\n  slots: [\"root\"] as const,\n  kbd: {\n    fontFamily: fontFamily.code,\n    textVariant: \"label\" as const,\n    paddingHorizontal: spacing.xxs,\n    radius: radius.sm,\n    background: semanticColors.surface.sunken,\n    color: semanticColors.content.body,\n    border: semanticColors.border.default,\n  },\n  code: {\n    fontFamily: fontFamily.code,\n    textVariant: \"body\" as const,\n    paddingHorizontal: spacing.xxs,\n    radius: radius.sm,\n    background: semanticColors.surface.sunken,\n    color: semanticColors.content.primary,\n  },\n  quote: {\n    textVariant: \"body\" as const,\n    paddingInlineStart: spacing.md,\n    borderWidth: 2,\n    border: semanticColors.border.default,\n    color: semanticColors.content.body,\n  },\n} as const satisfies {\n  slots: readonly [\"root\"];\n  kbd: {\n    fontFamily: typeof fontFamily.code;\n    textVariant: keyof typeof typography;\n    paddingHorizontal: number;\n    radius: number;\n    background: ColorReference;\n    color: ColorReference;\n    border: ColorReference;\n  };\n  code: {\n    fontFamily: typeof fontFamily.code;\n    textVariant: keyof typeof typography;\n    paddingHorizontal: number;\n    radius: number;\n    background: ColorReference;\n    color: ColorReference;\n  };\n  quote: {\n    textVariant: keyof typeof typography;\n    paddingInlineStart: number;\n    borderWidth: number;\n    border: ColorReference;\n    color: ColorReference;\n  };\n};\n\nexport const textFormatBehavior = {\n  controlled: [],\n  inputs: [\"kind\"],\n  configuration: { kind: [\"kbd\", \"code\", \"quote\"] },\n  stateAxes: {},\n  web: { roles: [], keyboard: [], focus: \"none\" },\n  native: { roles: [], states: [], actions: [] },\n  scenarios: [\n    \"each-kind-emits-its-own-html-element-so-assistive-technology-reads-it-as-what-it-is\",\n    \"these-are-elements-not-text-sizes-which-is-why-they-are-not-a-text-variant\",\n    \"a-key-name-is-product-copy-because-the-same-key-is-called-different-things-per-platform\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/toggle-group.d.ts

@@ -0,0 +1,111 @@
+import { type CheckboxSelectionItem } from "./selection-helpers.js";
+/**
+ * 여러 개를 동시에 켜고 끄는 버튼 묶음이다 — 굵게/기울임/밑줄, 필터 칩 여러 개처럼.
+ *
+ * `SegmentedControl`과 경계가 분명하다. Segmented는 **하나를 고른다**(어떤 화면을 볼지),
+ * ToggleGroup은 **여러 개를 켠다**(무엇을 적용할지). 그래서 Segmented에는 "선택 없음"이
+ * 없고 ToggleGroup에는 있다. 둘을 한 컴포넌트의 `mode` 축으로 합치면 그 차이가 사라지고,
+ * "아무것도 선택되지 않은 Segmented"라는 표현 불가능한 상태가 타입에 생긴다.
+ *
+ * `CheckboxGroup`과도 다르다. CheckboxGroup은 목록 안의 동의/선택이라 각 항목이 자기
+ * 줄과 설명을 갖는다. ToggleGroup은 도구 모음이라 한 줄에 붙어 있고 라벨이 짧다.
+ * 판정(무엇을 켤 수 있고 비활성은 어떻게 되는가)은 같은 helper를 공유한다.
+ */
+export type ToggleGroupItemDescriptor<Id extends string = string> = CheckboxSelectionItem<Id>;
+export type ToggleGroupDescriptor<Id extends string = string> = Readonly<{
+    /** 묶음 전체의 접근성 이름. 개별 버튼 이름으로 대체할 수 없다. */
+    accessibilityLabel: string;
+    items: readonly ToggleGroupItemDescriptor<Id>[];
+}>;
+export type ToggleGroupSize = "small" | "medium";
+export declare function validateToggleGroupDescriptor<Id extends string>(descriptor: ToggleGroupDescriptor<Id>): void;
+/** 하나를 켜고 끈다. 비활성 보호는 공용 helper가 이미 갖고 있다. */
+export declare function toggleGroupSelection<Id extends string>(descriptor: ToggleGroupDescriptor<Id>, pressedIds: ReadonlySet<Id>, id: Id): ReadonlySet<Id>;
+/** 목록에서 사라진 항목의 눌림 상태는 남기지 않는다. */
+export declare function reconcileToggleGroupSelection<Id extends string>(descriptor: ToggleGroupDescriptor<Id>, pressedIds: ReadonlySet<Id>): ReadonlySet<Id>;
+export declare const toggleGroupRecipe: {
+    readonly slots: readonly ["root", "item", "label"];
+    readonly defaults: {
+        readonly size: ToggleGroupSize;
+    };
+    readonly sizes: {
+        readonly small: {
+            readonly minHeight: 44;
+            readonly paddingHorizontal: 12;
+            readonly textVariant: "label";
+        };
+        readonly medium: {
+            readonly minHeight: 44;
+            readonly paddingHorizontal: 16;
+            readonly textVariant: "body";
+        };
+    };
+    readonly radius: 12;
+    readonly gap: 4;
+    readonly idle: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surface";
+            alpha?: number;
+        }>;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "borderControl";
+            alpha?: number;
+        }>;
+    };
+    readonly pressed: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "primary";
+            alpha?: number;
+        }>;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+    };
+};
+export declare const toggleGroupBehavior: {
+    readonly controlled: readonly ["pressedIds", "defaultPressedIds", "onPressedIdsChange"];
+    readonly inputs: readonly ["items", "accessibilityLabel", "size"];
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled"];
+        readonly value: readonly ["pressed", "unpressed"];
+    };
+    readonly web: {
+        readonly roles: readonly ["group", "button"];
+        readonly keyboard: readonly ["Tab", "Enter", "Space"];
+        /** Toolbar-style roving focus is not used: each toggle is its own tab stop, like a row of checkboxes. */
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["button"];
+        readonly states: readonly ["selected", "disabled"];
+        readonly actions: readonly ["toggle"];
+    };
+    readonly scenarios: readonly ["several-items-can-be-pressed-at-once-and-none-is-a-valid-state", "pressed-state-rides-on-aria-pressed-not-on-color-alone", "a-disabled-item-never-toggles-and-never-enters-the-pressed-set", "removing-an-item-drops-its-pressed-state-instead-of-keeping-an-orphan-id", "single-choice-belongs-to-segmented-control-this-contract-never-adds-a-single-mode", "the-group-carries-its-own-accessible-name-separate-from-each-buttons-name"];
+};
+//# sourceMappingURL=toggle-group.d.ts.map

package/dist/toggle-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-group.d.ts","sourceRoot":"","sources":["../src/toggle-group.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,yBAAyB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAC9D,qBAAqB,CAAC,EAAE,CAAC,CAAC;AAE5B,MAAM,MAAM,qBAAqB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IACvE,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,SAAS,yBAAyB,CAAC,EAAE,CAAC,EAAE,CAAC;CACjD,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,QAAQ,CAAC;AAQjD,wBAAgB,6BAA6B,CAAC,EAAE,SAAS,MAAM,EAC7D,UAAU,EAAE,qBAAqB,CAAC,EAAE,CAAC,GACpC,IAAI,CAYN;AAED,8CAA8C;AAC9C,wBAAgB,oBAAoB,CAAC,EAAE,SAAS,MAAM,EACpD,UAAU,EAAE,qBAAqB,CAAC,EAAE,CAAC,EACrC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,EAC3B,EAAE,EAAE,EAAE,GACL,WAAW,CAAC,EAAE,CAAC,CAGjB;AAED,mCAAmC;AACnC,wBAAgB,6BAA6B,CAAC,EAAE,SAAS,MAAM,EAC7D,UAAU,EAAE,qBAAqB,CAAC,EAAE,CAAC,EACrC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,GAC1B,WAAW,CAAC,EAAE,CAAC,CAGjB;AAED,eAAO,MAAM,iBAAiB;;;uBAEE,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2B9C,CAAC;AAEF,eAAO,MAAM,mBAAmB;;;;;;;;;;QAU5B,yGAAyG;;;;;;;;;CAYxE,CAAC"}

package/dist/toggle-group.js

@@ -0,0 +1,78 @@
+import { collectionItemContract, focusIndicatorContract } from "./component-contracts.js";
+import { control, radius, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+import { reconcileCheckboxSelection, toggleCheckboxSelection, } from "./selection-helpers.js";
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`ToggleGroup ${field} must not be empty`);
+    }
+}
+export function validateToggleGroupDescriptor(descriptor) {
+    assertNonEmpty(descriptor.accessibilityLabel, "accessibilityLabel");
+    if (!Array.isArray(descriptor.items) || descriptor.items.length === 0) {
+        throw new RangeError("ToggleGroup must contain at least one item");
+    }
+    const ids = new Set();
+    for (const item of descriptor.items) {
+        assertNonEmpty(item.id, "item id");
+        assertNonEmpty(item.label, "item label");
+        if (ids.has(item.id))
+            throw new TypeError(`Duplicate ToggleGroup item id: ${item.id}`);
+        ids.add(item.id);
+    }
+}
+/** 하나를 켜고 끈다. 비활성 보호는 공용 helper가 이미 갖고 있다. */
+export function toggleGroupSelection(descriptor, pressedIds, id) {
+    validateToggleGroupDescriptor(descriptor);
+    return toggleCheckboxSelection(descriptor.items, pressedIds, id);
+}
+/** 목록에서 사라진 항목의 눌림 상태는 남기지 않는다. */
+export function reconcileToggleGroupSelection(descriptor, pressedIds) {
+    validateToggleGroupDescriptor(descriptor);
+    return reconcileCheckboxSelection(descriptor.items, pressedIds);
+}
+export const toggleGroupRecipe = {
+    slots: ["root", "item", "label"],
+    defaults: { size: "medium" },
+    sizes: {
+        small: { minHeight: control.minTouchTarget, paddingHorizontal: spacing.sm, textVariant: "label" },
+        medium: { minHeight: 44, paddingHorizontal: spacing.md, textVariant: "body" },
+    },
+    radius: radius.md,
+    gap: spacing.xxs,
+    idle: {
+        background: semanticColors.surface.default,
+        color: semanticColors.content.body,
+        border: semanticColors.border.control,
+    },
+    pressed: {
+        background: collectionItemContract.selectedBackground,
+        color: semanticColors.content.brand,
+        border: semanticColors.border.focus,
+    },
+    states: { focus: focusIndicatorContract },
+};
+export const toggleGroupBehavior = {
+    controlled: ["pressedIds", "defaultPressedIds", "onPressedIdsChange"],
+    inputs: ["items", "accessibilityLabel", "size"],
+    stateAxes: {
+        availability: ["enabled", "disabled"],
+        value: ["pressed", "unpressed"],
+    },
+    web: {
+        roles: ["group", "button"],
+        keyboard: ["Tab", "Enter", "Space"],
+        /** Toolbar-style roving focus is not used: each toggle is its own tab stop, like a row of checkboxes. */
+        focus: "native",
+    },
+    native: { roles: ["button"], states: ["selected", "disabled"], actions: ["toggle"] },
+    scenarios: [
+        "several-items-can-be-pressed-at-once-and-none-is-a-valid-state",
+        "pressed-state-rides-on-aria-pressed-not-on-color-alone",
+        "a-disabled-item-never-toggles-and-never-enters-the-pressed-set",
+        "removing-an-item-drops-its-pressed-state-instead-of-keeping-an-orphan-id",
+        "single-choice-belongs-to-segmented-control-this-contract-never-adds-a-single-mode",
+        "the-group-carries-its-own-accessible-name-separate-from-each-buttons-name",
+    ],
+};
+//# sourceMappingURL=toggle-group.js.map

package/dist/toggle-group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-group.js","sourceRoot":"","sources":["../src/toggle-group.ts"],"names":[],"mappings":"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","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport type { ColorReference } from \"./color-references.js\";\nimport { collectionItemContract, focusIndicatorContract } from \"./component-contracts.js\";\nimport { control, radius, spacing } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\nimport {\n  reconcileCheckboxSelection,\n  toggleCheckboxSelection,\n  type CheckboxSelectionItem,\n} from \"./selection-helpers.js\";\n\n/**\n * 여러 개를 동시에 켜고 끄는 버튼 묶음이다 — 굵게/기울임/밑줄, 필터 칩 여러 개처럼.\n *\n * `SegmentedControl`과 경계가 분명하다. Segmented는 **하나를 고른다**(어떤 화면을 볼지),\n * ToggleGroup은 **여러 개를 켠다**(무엇을 적용할지). 그래서 Segmented에는 \"선택 없음\"이\n * 없고 ToggleGroup에는 있다. 둘을 한 컴포넌트의 `mode` 축으로 합치면 그 차이가 사라지고,\n * \"아무것도 선택되지 않은 Segmented\"라는 표현 불가능한 상태가 타입에 생긴다.\n *\n * `CheckboxGroup`과도 다르다. CheckboxGroup은 목록 안의 동의/선택이라 각 항목이 자기\n * 줄과 설명을 갖는다. ToggleGroup은 도구 모음이라 한 줄에 붙어 있고 라벨이 짧다.\n * 판정(무엇을 켤 수 있고 비활성은 어떻게 되는가)은 같은 helper를 공유한다.\n */\nexport type ToggleGroupItemDescriptor<Id extends string = string> =\n  CheckboxSelectionItem<Id>;\n\nexport type ToggleGroupDescriptor<Id extends string = string> = Readonly<{\n  /** 묶음 전체의 접근성 이름. 개별 버튼 이름으로 대체할 수 없다. */\n  accessibilityLabel: string;\n  items: readonly ToggleGroupItemDescriptor<Id>[];\n}>;\n\nexport type ToggleGroupSize = \"small\" | \"medium\";\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`ToggleGroup ${field} must not be empty`);\n  }\n}\n\nexport function validateToggleGroupDescriptor<Id extends string>(\n  descriptor: ToggleGroupDescriptor<Id>,\n): void {\n  assertNonEmpty(descriptor.accessibilityLabel, \"accessibilityLabel\");\n  if (!Array.isArray(descriptor.items) || descriptor.items.length === 0) {\n    throw new RangeError(\"ToggleGroup must contain at least one item\");\n  }\n  const ids = new Set<Id>();\n  for (const item of descriptor.items) {\n    assertNonEmpty(item.id, \"item id\");\n    assertNonEmpty(item.label, \"item label\");\n    if (ids.has(item.id)) throw new TypeError(`Duplicate ToggleGroup item id: ${item.id}`);\n    ids.add(item.id);\n  }\n}\n\n/** 하나를 켜고 끈다. 비활성 보호는 공용 helper가 이미 갖고 있다. */\nexport function toggleGroupSelection<Id extends string>(\n  descriptor: ToggleGroupDescriptor<Id>,\n  pressedIds: ReadonlySet<Id>,\n  id: Id,\n): ReadonlySet<Id> {\n  validateToggleGroupDescriptor(descriptor);\n  return toggleCheckboxSelection(descriptor.items, pressedIds, id);\n}\n\n/** 목록에서 사라진 항목의 눌림 상태는 남기지 않는다. */\nexport function reconcileToggleGroupSelection<Id extends string>(\n  descriptor: ToggleGroupDescriptor<Id>,\n  pressedIds: ReadonlySet<Id>,\n): ReadonlySet<Id> {\n  validateToggleGroupDescriptor(descriptor);\n  return reconcileCheckboxSelection(descriptor.items, pressedIds);\n}\n\nexport const toggleGroupRecipe = {\n  slots: [\"root\", \"item\", \"label\"] as const,\n  defaults: { size: \"medium\" as ToggleGroupSize },\n  sizes: {\n    small: { minHeight: control.minTouchTarget, paddingHorizontal: spacing.sm, textVariant: \"label\" as const },\n    medium: { minHeight: 44, paddingHorizontal: spacing.md, textVariant: \"body\" as const },\n  },\n  radius: radius.md,\n  gap: spacing.xxs,\n  idle: {\n    background: semanticColors.surface.default,\n    color: semanticColors.content.body,\n    border: semanticColors.border.control,\n  },\n  pressed: {\n    background: collectionItemContract.selectedBackground,\n    color: semanticColors.content.brand,\n    border: semanticColors.border.focus,\n  },\n  states: { focus: focusIndicatorContract },\n} as const satisfies {\n  slots: readonly [\"root\", \"item\", \"label\"];\n  defaults: { size: ToggleGroupSize };\n  sizes: Record<ToggleGroupSize, { minHeight: number; paddingHorizontal: number; textVariant: \"label\" | \"body\" }>;\n  radius: number;\n  gap: number;\n  idle: { background: ColorReference; color: ColorReference; border: ColorReference };\n  pressed: { background: ColorReference; color: ColorReference; border: ColorReference };\n  states: { focus: typeof focusIndicatorContract };\n};\n\nexport const toggleGroupBehavior = {\n  controlled: [\"pressedIds\", \"defaultPressedIds\", \"onPressedIdsChange\"],\n  inputs: [\"items\", \"accessibilityLabel\", \"size\"],\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\"],\n    value: [\"pressed\", \"unpressed\"],\n  },\n  web: {\n    roles: [\"group\", \"button\"],\n    keyboard: [\"Tab\", \"Enter\", \"Space\"],\n    /** Toolbar-style roving focus is not used: each toggle is its own tab stop, like a row of checkboxes. */\n    focus: \"native\",\n  },\n  native: { roles: [\"button\"], states: [\"selected\", \"disabled\"], actions: [\"toggle\"] },\n  scenarios: [\n    \"several-items-can-be-pressed-at-once-and-none-is-a-valid-state\",\n    \"pressed-state-rides-on-aria-pressed-not-on-color-alone\",\n    \"a-disabled-item-never-toggles-and-never-enters-the-pressed-set\",\n    \"removing-an-item-drops-its-pressed-state-instead-of-keeping-an-orphan-id\",\n    \"single-choice-belongs-to-segmented-control-this-contract-never-adds-a-single-mode\",\n    \"the-group-carries-its-own-accessible-name-separate-from-each-buttons-name\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/top.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 화면 본문의 **첫 블록**이다. `TopBar`(상단 내비게이션 바)와 다른 자리이고, 그 차이가
+ * 이 계약의 존재 이유다.
+ *
+ * - `TopBar`는 화면에 고정된 크롬이다 — 뒤로가기, 화면 이름, 액션. 스크롤과 무관하게
+ *   붙어 있고 safe area를 다룬다.
+ * - `Top`은 본문이다 — 스크롤과 함께 올라가고, 사용자가 "이 화면이 무엇을 묻는지"
+ *   읽는 문장이 여기 있다. 토스 TDS가 "Top과 ListRow로 화면 대부분을 만든다"고
+ *   말하는 그 Top이고, 지금까지 BurnTok `AppScreenHeader`·Taground `screen-shell`·
+ *   Diairy `DetailPanel`이 각자 다시 만들던 블록이다.
+ *
+ * `Section`과도 다르다. Section은 본문 **중간**의 묶음 제목이라 heading level이 화면
+ * 구조에 종속되지만, Top은 화면당 하나뿐인 첫 제목이라 기본이 `h1`이다. 그래서 두
+ * 계약을 합치지 않았다 — 합치면 "이 Section이 화면의 h1인가"를 매번 물어야 한다.
+ */
+export type TopSize = "medium" | "large";
+export type TopDescriptor = Readonly<{
+    title: string;
+    /** 제목 위 한 줄. 카테고리·단계처럼 제목을 한정하는 짧은 말. */
+    eyebrow?: string;
+    /** 제목 아래 보조 문장. 길면 줄바꿈되며 잘리지 않는다. */
+    description?: string;
+    size?: TopSize;
+    /**
+     * 문서 구조상의 제목 단계. 화면당 하나인 Top은 `1`이 기본이지만, 한 라우트가
+     * 여러 화면을 담는 경우(시트 안의 화면 등) 제품이 낮출 수 있다.
+     */
+    headingLevel?: 1 | 2 | 3;
+}>;
+export declare const topDefaults: {
+    readonly size: "large";
+    readonly headingLevel: 1;
+};
+export declare function validateTopDescriptor(descriptor: TopDescriptor): void;
+/**
+ * `large`는 화면의 첫 제목, `medium`은 시트·모달 안의 첫 제목이다. 두 단계뿐인 이유는
+ * 세 번째가 필요해지는 자리가 곧 `Section`이기 때문이다 — 크기를 더 늘리는 대신 다른
+ * 컴포넌트를 쓰라는 신호로 둔다.
+ */
+export declare const topRecipe: {
+    readonly slots: readonly ["root", "eyebrow", "title", "description", "trailing"];
+    readonly defaults: {
+        readonly size: "large";
+    };
+    readonly sizes: {
+        readonly medium: {
+            readonly title: {
+                readonly fontSize: 20;
+                readonly lineHeight: 28;
+                readonly fontWeight: "800";
+            };
+            readonly paddingTop: 16;
+            readonly paddingBottom: 12;
+        };
+        readonly large: {
+            readonly title: {
+                readonly fontSize: 32;
+                readonly lineHeight: 40;
+                readonly fontWeight: "800";
+            };
+            readonly paddingTop: 24;
+            readonly paddingBottom: 16;
+        };
+    };
+    readonly eyebrow: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+        readonly marginBottom: 4;
+    };
+    readonly title: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+    };
+    readonly description: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly textVariant: "body";
+        readonly marginTop: 8;
+    };
+    /** 제목 줄 오른쪽 보조 행동. 본문이므로 TopBar처럼 아이콘 전용을 강제하지 않는다. */
+    readonly trailing: {
+        readonly gap: 8;
+    };
+    readonly gap: 8;
+};
+export declare const topBehavior: {
+    /** 상태 축이 없다 — 화면이 제목을 바꾸면 그냥 다른 문자열을 넘긴다. */
+    readonly controlled: readonly [];
+    readonly inputs: readonly ["title", "eyebrow", "description", "size", "headingLevel"];
+    readonly stateAxes: {};
+    readonly web: {
+        readonly roles: readonly ["heading"];
+        readonly keyboard: readonly [];
+        readonly focus: "none";
+    };
+    readonly native: {
+        readonly roles: readonly ["header"];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["the-title-is-a-real-heading-element-at-the-declared-level-not-styled-text", "top-is-body-content-that-scrolls-away-while-topbar-is-fixed-chrome", "description-wraps-instead-of-truncating-so-large-text-never-hides-the-question", "a-trailing-action-shares-the-title-row-and-drops-below-it-when-space-runs-out", "eyebrow-never-carries-information-the-title-does-not-repeat-in-some-form"];
+};
+//# sourceMappingURL=top.d.ts.map

package/dist/top.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"top.d.ts","sourceRoot":"","sources":["../src/top.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;CAC1B,CAAC,CAAC;AAEH,eAAO,MAAM,WAAW;;;CAGiD,CAAC;AAQ1E,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,aAAa,GAAG,IAAI,CAkBrE;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAkBpB,uDAAuD;;;;;CAexD,CAAC;AAEF,eAAO,MAAM,WAAW;IACtB,6CAA6C;;;;;;;;;;;;;;;CAaV,CAAC"}