@hjmds/design-contracts 1.1.1 → 1.2.0

package/dist/agreement.d.ts

@@ -0,0 +1,183 @@
+import { type CheckboxSelectionItem, type CheckboxState } from "./selection-helpers.js";
+/**
+ * 가입·결제 앞에 서는 "약관 동의" 묶음이다. CheckboxGroup으로 매번 조립하던 것을
+ * 계약으로 올리는 이유는 세 가지가 **체크박스 목록이 아니라 법적 절차**이기 때문이다.
+ *
+ * 1. 필수/선택이 제출 가능 여부를 결정한다 — CheckboxGroup은 그 판정을 갖지 않는다.
+ * 2. 전체 동의는 자식의 합이지 별도 항목이 아니다(DataTable 머리글·TreeSelect 부모와
+ *    같은 파생 관계). 저장되는 것은 개별 항목뿐이다.
+ * 3. 각 항목은 "읽을 수 있어야" 한다 — 상세 보기 경로가 없는 동의는 동의가 아니다.
+ *    그래서 `detail`은 renderer가 장식으로 넣는 화살표가 아니라 계약된 행동이다.
+ *
+ * 문구·링크 주소·법적 유효성은 제품이 소유한다. 이 계약은 판정과 배치만 갖는다.
+ */
+export type AgreementItemDescriptor<Id extends string = string> = CheckboxSelectionItem<Id> & Readonly<{
+    /** 필수 항목은 하나라도 비면 제출을 막는다. 기본값은 선택(false). */
+    required?: boolean;
+    /**
+     * 전문을 여는 경로. 제품이 링크(`href`)로 열지 시트로 열지는 renderer 밖의
+     * 결정이라 여기서는 "열 수 있다"는 사실만 계약한다.
+     */
+    detail?: Readonly<{
+        label: string;
+        href?: string;
+    }>;
+}>;
+export type AgreementDescriptor<Id extends string = string> = Readonly<{
+    /** 묶음 전체의 접근성 이름. "약관 동의"처럼 제품이 현지화한다. */
+    accessibilityLabel: string;
+    /** 전체 동의 행의 라벨. 필수이므로 renderer가 임의 문구를 만들지 않는다. */
+    allLabel: string;
+    items: readonly AgreementItemDescriptor<Id>[];
+}>;
+export declare function validateAgreementDescriptor<Id extends string>(descriptor: AgreementDescriptor<Id>): void;
+export type AgreementState<Id extends string = string> = Readonly<{
+    /** 전체 동의 행이 그릴 tri-state. 개별 항목의 합에서만 나온다. */
+    all: CheckboxState;
+    /** 필수 항목이 모두 체크됐는가 — 제품의 제출 버튼이 읽는 값. */
+    satisfied: boolean;
+    /** 아직 체크되지 않은 필수 항목. 제품이 "무엇이 남았는지" 문장을 만든다. */
+    missingRequiredIds: readonly Id[];
+}>;
+/**
+ * 비활성 항목은 분모에서 뺀다 — 사용자가 바꿀 수 없는 것을 "덜 동의했다"고 셀 수
+ * 없기 때문이다(`resolveDataTableSelectAllState`·`resolveTreeCheckedStates`와 같은 규칙).
+ * 필수 항목은 비활성일 수 없으므로(위 validate) `satisfied` 판정에는 이 예외가 없다.
+ */
+export declare function resolveAgreementState<Id extends string>(descriptor: AgreementDescriptor<Id>, checkedIds: ReadonlySet<Id>): AgreementState<Id>;
+/** 개별 항목 토글. 비활성 항목 보호는 공용 helper가 이미 갖고 있다. */
+export declare function toggleAgreementItem<Id extends string>(descriptor: AgreementDescriptor<Id>, checkedIds: ReadonlySet<Id>, id: Id): ReadonlySet<Id>;
+/**
+ * 전체 동의는 "모두 체크됨"의 반대로 간다 — mixed에서 누르면 채운다(공용
+ * `getCheckboxNextState`의 기본값과 같은 관습). 비활성 항목의 현재 상태는 건드리지
+ * 않는다: 그 값은 사용자가 만든 것이 아니라 제품이 고정한 것이다.
+ */
+export declare function toggleAgreementAll<Id extends string>(descriptor: AgreementDescriptor<Id>, checkedIds: ReadonlySet<Id>): ReadonlySet<Id>;
+/** 목록에서 사라진 항목의 동의는 남기지 않는다. */
+export declare function reconcileAgreementSelection<Id extends string>(descriptor: AgreementDescriptor<Id>, checkedIds: ReadonlySet<Id>): ReadonlySet<Id>;
+/**
+ * 전체 동의 행은 개별 행보다 시각적으로 무겁다 — 목록의 제목 역할을 하기 때문이다.
+ * 나머지는 `collectionItemContract`를 그대로 쓴다(Menu·Tree·ListRow와 같은 행 chrome).
+ */
+export declare const agreementRecipe: {
+    readonly slots: readonly ["root", "all", "list", "item", "label", "detail"];
+    readonly all: {
+        readonly minHeight: 44;
+        readonly gap: 12;
+        readonly paddingHorizontal: 16;
+        readonly paddingVertical: 12;
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surfaceAlt";
+            alpha?: number;
+        }>;
+        readonly radius: "md";
+        readonly textVariant: "bodyLarge";
+        readonly color: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+    };
+    readonly item: {
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 12;
+        readonly gap: 12;
+        readonly radius: "md";
+        readonly label: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly textVariant: "body";
+        };
+        readonly description: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textMuted";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly highlightedBackground: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly selectedBackground: Readonly<{
+            source: "theme";
+            key: "primary";
+            alpha?: number;
+        }>;
+        readonly selectedIndicator: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly danger: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+    };
+    readonly detail: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+        readonly minHeight: 44;
+    };
+    readonly required: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+    };
+    readonly gap: 8;
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+    };
+};
+export declare const agreementBehavior: {
+    readonly controlled: readonly ["checkedIds", "defaultCheckedIds", "onCheckedIdsChange"];
+    readonly inputs: readonly ["items", "allLabel", "accessibilityLabel"];
+    readonly events: readonly ["onDetail"];
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled"];
+        readonly value: readonly ["unchecked", "checked", "mixed"];
+    };
+    readonly web: {
+        readonly roles: readonly ["group", "checkbox", "link", "button"];
+        readonly keyboard: readonly ["Tab", "Space", "Enter"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["checkbox", "link", "button"];
+        readonly states: readonly ["checked", "disabled"];
+        readonly actions: readonly ["toggle", "toggleAll", "openDetail"];
+    };
+    readonly scenarios: readonly ["all-agree-is-derived-from-the-items-never-stored-as-its-own-value", "checking-all-checks-every-enabled-item-and-leaves-disabled-ones-untouched", "required-items-alone-decide-whether-the-product-may-submit", "a-required-item-can-never-be-disabled-the-descriptor-is-rejected", "every-item-may-open-its-full-text-and-that-control-is-a-separate-tab-stop", "the-detail-control-never-toggles-the-agreement-it-only-opens-the-text", "optional-items-never-block-submission-and-are-announced-as-optional", "removing-an-item-drops-its-consent-instead-of-keeping-an-orphan-id"];
+};
+//# sourceMappingURL=agreement.d.ts.map

package/dist/agreement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agreement.d.ts","sourceRoot":"","sources":["../src/agreement.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,uBAAuB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAC5D,qBAAqB,CAAC,EAAE,CAAC,GACvB,QAAQ,CAAC;IACP,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD,CAAC,CAAC;AAEP,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IACrE,0CAA0C;IAC1C,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,SAAS,uBAAuB,CAAC,EAAE,CAAC,EAAE,CAAC;CAC/C,CAAC,CAAC;AAQH,wBAAgB,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAC3D,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,GAClC,IAAI,CAyBN;AAED,MAAM,MAAM,cAAc,CAAC,EAAE,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IAChE,8CAA8C;IAC9C,GAAG,EAAE,aAAa,CAAC;IACnB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,kBAAkB,EAAE,SAAS,EAAE,EAAE,CAAC;CACnC,CAAC,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,SAAS,MAAM,EACrD,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,EACnC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,GAC1B,cAAc,CAAC,EAAE,CAAC,CAapB;AAED,gDAAgD;AAChD,wBAAgB,mBAAmB,CAAC,EAAE,SAAS,MAAM,EACnD,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,EACnC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,EAC3B,EAAE,EAAE,EAAE,GACL,WAAW,CAAC,EAAE,CAAC,CAGjB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAClD,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,EACnC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,GAC1B,WAAW,CAAC,EAAE,CAAC,CASjB;AAED,gCAAgC;AAChC,wBAAgB,2BAA2B,CAAC,EAAE,SAAS,MAAM,EAC3D,UAAU,EAAE,mBAAmB,CAAC,EAAE,CAAC,EACnC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,GAC1B,WAAW,CAAC,EAAE,CAAC,CAGjB;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsC3B,CAAC;AAEF,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;CA4BO,CAAC"}

package/dist/agreement.js

@@ -0,0 +1,137 @@
+import { collectionItemContract, focusIndicatorContract } from "./component-contracts.js";
+import { control, 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(`Agreement ${field} must not be empty`);
+    }
+}
+export function validateAgreementDescriptor(descriptor) {
+    assertNonEmpty(descriptor.accessibilityLabel, "accessibilityLabel");
+    assertNonEmpty(descriptor.allLabel, "allLabel");
+    if (!Array.isArray(descriptor.items) || descriptor.items.length === 0) {
+        throw new RangeError("Agreement 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 Agreement item id: ${item.id}`);
+        ids.add(item.id);
+        if (item.detail !== undefined) {
+            assertNonEmpty(item.detail.label, `item ${item.id} detail label`);
+        }
+        if (item.required === true && item.disabled === true) {
+            /*
+              비활성 필수 항목은 사용자가 영원히 제출할 수 없는 화면을 만든다. 조용히
+              허용하면 "버튼이 왜 안 눌리는지" 알 수 없는 상태가 되므로 여기서 막는다.
+            */
+            throw new TypeError(`Agreement item ${item.id} cannot be both required and disabled`);
+        }
+    }
+}
+/**
+ * 비활성 항목은 분모에서 뺀다 — 사용자가 바꿀 수 없는 것을 "덜 동의했다"고 셀 수
+ * 없기 때문이다(`resolveDataTableSelectAllState`·`resolveTreeCheckedStates`와 같은 규칙).
+ * 필수 항목은 비활성일 수 없으므로(위 validate) `satisfied` 판정에는 이 예외가 없다.
+ */
+export function resolveAgreementState(descriptor, checkedIds) {
+    validateAgreementDescriptor(descriptor);
+    const selectable = descriptor.items.filter((item) => !item.disabled);
+    const checkedCount = selectable.filter((item) => checkedIds.has(item.id)).length;
+    const all = selectable.length === 0 || checkedCount === 0
+        ? false
+        : checkedCount === selectable.length
+            ? true
+            : "mixed";
+    const missingRequiredIds = descriptor.items
+        .filter((item) => item.required === true && !checkedIds.has(item.id))
+        .map((item) => item.id);
+    return { all, satisfied: missingRequiredIds.length === 0, missingRequiredIds };
+}
+/** 개별 항목 토글. 비활성 항목 보호는 공용 helper가 이미 갖고 있다. */
+export function toggleAgreementItem(descriptor, checkedIds, id) {
+    validateAgreementDescriptor(descriptor);
+    return toggleCheckboxSelection(descriptor.items, checkedIds, id);
+}
+/**
+ * 전체 동의는 "모두 체크됨"의 반대로 간다 — mixed에서 누르면 채운다(공용
+ * `getCheckboxNextState`의 기본값과 같은 관습). 비활성 항목의 현재 상태는 건드리지
+ * 않는다: 그 값은 사용자가 만든 것이 아니라 제품이 고정한 것이다.
+ */
+export function toggleAgreementAll(descriptor, checkedIds) {
+    const { all } = resolveAgreementState(descriptor, checkedIds);
+    const next = new Set(checkedIds);
+    for (const item of descriptor.items) {
+        if (item.disabled)
+            continue;
+        if (all === true)
+            next.delete(item.id);
+        else
+            next.add(item.id);
+    }
+    return next;
+}
+/** 목록에서 사라진 항목의 동의는 남기지 않는다. */
+export function reconcileAgreementSelection(descriptor, checkedIds) {
+    validateAgreementDescriptor(descriptor);
+    return reconcileCheckboxSelection(descriptor.items, checkedIds);
+}
+/**
+ * 전체 동의 행은 개별 행보다 시각적으로 무겁다 — 목록의 제목 역할을 하기 때문이다.
+ * 나머지는 `collectionItemContract`를 그대로 쓴다(Menu·Tree·ListRow와 같은 행 chrome).
+ */
+export const agreementRecipe = {
+    slots: ["root", "all", "list", "item", "label", "detail"],
+    all: {
+        minHeight: control.minTouchTarget,
+        gap: spacing.sm,
+        paddingHorizontal: spacing.md,
+        paddingVertical: spacing.sm,
+        background: semanticColors.surface.sunken,
+        radius: "md",
+        textVariant: "bodyLarge",
+        color: semanticColors.content.primary,
+    },
+    item: collectionItemContract,
+    detail: {
+        color: semanticColors.content.secondary,
+        textVariant: "label",
+        minHeight: control.minTouchTarget,
+    },
+    required: { color: semanticColors.content.brand, textVariant: "label" },
+    gap: spacing.xs,
+    states: { focus: focusIndicatorContract },
+};
+export const agreementBehavior = {
+    controlled: ["checkedIds", "defaultCheckedIds", "onCheckedIdsChange"],
+    inputs: ["items", "allLabel", "accessibilityLabel"],
+    events: ["onDetail"],
+    stateAxes: {
+        availability: ["enabled", "disabled"],
+        value: ["unchecked", "checked", "mixed"],
+    },
+    web: {
+        roles: ["group", "checkbox", "link", "button"],
+        keyboard: ["Tab", "Space", "Enter"],
+        focus: "native",
+    },
+    native: {
+        roles: ["checkbox", "link", "button"],
+        states: ["checked", "disabled"],
+        actions: ["toggle", "toggleAll", "openDetail"],
+    },
+    scenarios: [
+        "all-agree-is-derived-from-the-items-never-stored-as-its-own-value",
+        "checking-all-checks-every-enabled-item-and-leaves-disabled-ones-untouched",
+        "required-items-alone-decide-whether-the-product-may-submit",
+        "a-required-item-can-never-be-disabled-the-descriptor-is-rejected",
+        "every-item-may-open-its-full-text-and-that-control-is-a-separate-tab-stop",
+        "the-detail-control-never-toggles-the-agreement-it-only-opens-the-text",
+        "optional-items-never-block-submission-and-are-announced-as-optional",
+        "removing-an-item-drops-its-consent-instead-of-keeping-an-orphan-id",
+    ],
+};
+//# sourceMappingURL=agreement.js.map

package/dist/agreement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agreement.js","sourceRoot":"","sources":["../src/agreement.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, spacing } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\nimport {\n  reconcileCheckboxSelection,\n  toggleCheckboxSelection,\n  type CheckboxSelectionItem,\n  type CheckboxState,\n} from \"./selection-helpers.js\";\n\n/**\n * 가입·결제 앞에 서는 \"약관 동의\" 묶음이다. CheckboxGroup으로 매번 조립하던 것을\n * 계약으로 올리는 이유는 세 가지가 **체크박스 목록이 아니라 법적 절차**이기 때문이다.\n *\n * 1. 필수/선택이 제출 가능 여부를 결정한다 — CheckboxGroup은 그 판정을 갖지 않는다.\n * 2. 전체 동의는 자식의 합이지 별도 항목이 아니다(DataTable 머리글·TreeSelect 부모와\n *    같은 파생 관계). 저장되는 것은 개별 항목뿐이다.\n * 3. 각 항목은 \"읽을 수 있어야\" 한다 — 상세 보기 경로가 없는 동의는 동의가 아니다.\n *    그래서 `detail`은 renderer가 장식으로 넣는 화살표가 아니라 계약된 행동이다.\n *\n * 문구·링크 주소·법적 유효성은 제품이 소유한다. 이 계약은 판정과 배치만 갖는다.\n */\nexport type AgreementItemDescriptor<Id extends string = string> =\n  CheckboxSelectionItem<Id> &\n    Readonly<{\n      /** 필수 항목은 하나라도 비면 제출을 막는다. 기본값은 선택(false). */\n      required?: boolean;\n      /**\n       * 전문을 여는 경로. 제품이 링크(`href`)로 열지 시트로 열지는 renderer 밖의\n       * 결정이라 여기서는 \"열 수 있다\"는 사실만 계약한다.\n       */\n      detail?: Readonly<{ label: string; href?: string }>;\n    }>;\n\nexport type AgreementDescriptor<Id extends string = string> = Readonly<{\n  /** 묶음 전체의 접근성 이름. \"약관 동의\"처럼 제품이 현지화한다. */\n  accessibilityLabel: string;\n  /** 전체 동의 행의 라벨. 필수이므로 renderer가 임의 문구를 만들지 않는다. */\n  allLabel: string;\n  items: readonly AgreementItemDescriptor<Id>[];\n}>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`Agreement ${field} must not be empty`);\n  }\n}\n\nexport function validateAgreementDescriptor<Id extends string>(\n  descriptor: AgreementDescriptor<Id>,\n): void {\n  assertNonEmpty(descriptor.accessibilityLabel, \"accessibilityLabel\");\n  assertNonEmpty(descriptor.allLabel, \"allLabel\");\n  if (!Array.isArray(descriptor.items) || descriptor.items.length === 0) {\n    throw new RangeError(\"Agreement 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 Agreement item id: ${item.id}`);\n    ids.add(item.id);\n    if (item.detail !== undefined) {\n      assertNonEmpty(item.detail.label, `item ${item.id} detail label`);\n    }\n    if (item.required === true && item.disabled === true) {\n      /*\n        비활성 필수 항목은 사용자가 영원히 제출할 수 없는 화면을 만든다. 조용히\n        허용하면 \"버튼이 왜 안 눌리는지\" 알 수 없는 상태가 되므로 여기서 막는다.\n      */\n      throw new TypeError(\n        `Agreement item ${item.id} cannot be both required and disabled`,\n      );\n    }\n  }\n}\n\nexport type AgreementState<Id extends string = string> = Readonly<{\n  /** 전체 동의 행이 그릴 tri-state. 개별 항목의 합에서만 나온다. */\n  all: CheckboxState;\n  /** 필수 항목이 모두 체크됐는가 — 제품의 제출 버튼이 읽는 값. */\n  satisfied: boolean;\n  /** 아직 체크되지 않은 필수 항목. 제품이 \"무엇이 남았는지\" 문장을 만든다. */\n  missingRequiredIds: readonly Id[];\n}>;\n\n/**\n * 비활성 항목은 분모에서 뺀다 — 사용자가 바꿀 수 없는 것을 \"덜 동의했다\"고 셀 수\n * 없기 때문이다(`resolveDataTableSelectAllState`·`resolveTreeCheckedStates`와 같은 규칙).\n * 필수 항목은 비활성일 수 없으므로(위 validate) `satisfied` 판정에는 이 예외가 없다.\n */\nexport function resolveAgreementState<Id extends string>(\n  descriptor: AgreementDescriptor<Id>,\n  checkedIds: ReadonlySet<Id>,\n): AgreementState<Id> {\n  validateAgreementDescriptor(descriptor);\n  const selectable = descriptor.items.filter((item) => !item.disabled);\n  const checkedCount = selectable.filter((item) => checkedIds.has(item.id)).length;\n  const all: CheckboxState = selectable.length === 0 || checkedCount === 0\n    ? false\n    : checkedCount === selectable.length\n      ? true\n      : \"mixed\";\n  const missingRequiredIds = descriptor.items\n    .filter((item) => item.required === true && !checkedIds.has(item.id))\n    .map((item) => item.id);\n  return { all, satisfied: missingRequiredIds.length === 0, missingRequiredIds };\n}\n\n/** 개별 항목 토글. 비활성 항목 보호는 공용 helper가 이미 갖고 있다. */\nexport function toggleAgreementItem<Id extends string>(\n  descriptor: AgreementDescriptor<Id>,\n  checkedIds: ReadonlySet<Id>,\n  id: Id,\n): ReadonlySet<Id> {\n  validateAgreementDescriptor(descriptor);\n  return toggleCheckboxSelection(descriptor.items, checkedIds, id);\n}\n\n/**\n * 전체 동의는 \"모두 체크됨\"의 반대로 간다 — mixed에서 누르면 채운다(공용\n * `getCheckboxNextState`의 기본값과 같은 관습). 비활성 항목의 현재 상태는 건드리지\n * 않는다: 그 값은 사용자가 만든 것이 아니라 제품이 고정한 것이다.\n */\nexport function toggleAgreementAll<Id extends string>(\n  descriptor: AgreementDescriptor<Id>,\n  checkedIds: ReadonlySet<Id>,\n): ReadonlySet<Id> {\n  const { all } = resolveAgreementState(descriptor, checkedIds);\n  const next = new Set(checkedIds);\n  for (const item of descriptor.items) {\n    if (item.disabled) continue;\n    if (all === true) next.delete(item.id);\n    else next.add(item.id);\n  }\n  return next;\n}\n\n/** 목록에서 사라진 항목의 동의는 남기지 않는다. */\nexport function reconcileAgreementSelection<Id extends string>(\n  descriptor: AgreementDescriptor<Id>,\n  checkedIds: ReadonlySet<Id>,\n): ReadonlySet<Id> {\n  validateAgreementDescriptor(descriptor);\n  return reconcileCheckboxSelection(descriptor.items, checkedIds);\n}\n\n/**\n * 전체 동의 행은 개별 행보다 시각적으로 무겁다 — 목록의 제목 역할을 하기 때문이다.\n * 나머지는 `collectionItemContract`를 그대로 쓴다(Menu·Tree·ListRow와 같은 행 chrome).\n */\nexport const agreementRecipe = {\n  slots: [\"root\", \"all\", \"list\", \"item\", \"label\", \"detail\"] as const,\n  all: {\n    minHeight: control.minTouchTarget,\n    gap: spacing.sm,\n    paddingHorizontal: spacing.md,\n    paddingVertical: spacing.sm,\n    background: semanticColors.surface.sunken,\n    radius: \"md\" as const,\n    textVariant: \"bodyLarge\" as const,\n    color: semanticColors.content.primary,\n  },\n  item: collectionItemContract,\n  detail: {\n    color: semanticColors.content.secondary,\n    textVariant: \"label\" as const,\n    minHeight: control.minTouchTarget,\n  },\n  required: { color: semanticColors.content.brand, textVariant: \"label\" as const },\n  gap: spacing.xs,\n  states: { focus: focusIndicatorContract },\n} as const satisfies {\n  slots: readonly [\"root\", \"all\", \"list\", \"item\", \"label\", \"detail\"];\n  all: {\n    minHeight: number;\n    gap: number;\n    paddingHorizontal: number;\n    paddingVertical: number;\n    background: ColorReference;\n    radius: \"md\";\n    textVariant: \"bodyLarge\";\n    color: ColorReference;\n  };\n  item: typeof collectionItemContract;\n  detail: { color: ColorReference; textVariant: \"label\"; minHeight: number };\n  required: { color: ColorReference; textVariant: \"label\" };\n  gap: number;\n  states: { focus: typeof focusIndicatorContract };\n};\n\nexport const agreementBehavior = {\n  controlled: [\"checkedIds\", \"defaultCheckedIds\", \"onCheckedIdsChange\"],\n  inputs: [\"items\", \"allLabel\", \"accessibilityLabel\"],\n  events: [\"onDetail\"],\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\"],\n    value: [\"unchecked\", \"checked\", \"mixed\"],\n  },\n  web: {\n    roles: [\"group\", \"checkbox\", \"link\", \"button\"],\n    keyboard: [\"Tab\", \"Space\", \"Enter\"],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"checkbox\", \"link\", \"button\"],\n    states: [\"checked\", \"disabled\"],\n    actions: [\"toggle\", \"toggleAll\", \"openDetail\"],\n  },\n  scenarios: [\n    \"all-agree-is-derived-from-the-items-never-stored-as-its-own-value\",\n    \"checking-all-checks-every-enabled-item-and-leaves-disabled-ones-untouched\",\n    \"required-items-alone-decide-whether-the-product-may-submit\",\n    \"a-required-item-can-never-be-disabled-the-descriptor-is-rejected\",\n    \"every-item-may-open-its-full-text-and-that-control-is-a-separate-tab-stop\",\n    \"the-detail-control-never-toggles-the-agreement-it-only-opens-the-text\",\n    \"optional-items-never-block-submission-and-are-announced-as-optional\",\n    \"removing-an-item-drops-its-consent-instead-of-keeping-an-orphan-id\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/anchor.d.ts

@@ -0,0 +1,62 @@
+/** IDs refer to same-document sections, never arbitrary external destinations. */
+export type AnchorItem = Readonly<{
+    id: string;
+    label: string;
+}>;
+export declare function resolveAnchorItems(items: readonly AnchorItem[]): any[];
+/** Positions use one viewport's coordinates. DOM reads and scroll ownership stay in the renderer. */
+export declare function getAnchorCurrentId(positions: readonly Readonly<{
+    id: string;
+    top: number;
+}>[], offset?: number, atEnd?: boolean): string | undefined;
+export declare const anchorRecipe: {
+    readonly slots: readonly ["root", "list", "link", "indicator"];
+    readonly gap: 4;
+    readonly link: {
+        readonly padding: 8;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+    };
+    readonly current: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly width: 2;
+    };
+    readonly focus: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly width: 2;
+        readonly offset: 2;
+    };
+};
+export declare const anchorBehavior: {
+    readonly controlled: readonly [];
+    readonly inputs: readonly ["items", "offset", "container", "historyMode"];
+    readonly stateAxes: {};
+    readonly web: {
+        readonly roles: readonly ["navigation", "list", "listitem", "link"];
+        readonly keyboard: readonly ["Tab", "Enter"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly [];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["scroll-position-selects-one-current-location", "activation-focuses-target-and-preserves-offset", "reduced-motion-jumps-instantly", "browser-history-restores-a-section", "missing-targets-are-not-current"];
+};
+//# sourceMappingURL=anchor.d.ts.map

package/dist/anchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.d.ts","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAKA,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AACjE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,SAU9D;AAED,qGAAqG;AACrG,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,SAAS,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,EAAE,EAAE,MAAM,SAAI,EAAE,KAAK,UAAQ,GAAG,MAAM,GAAG,SAAS,CAM7I;AAED,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAMf,CAAC;AACX,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;CAKU,CAAC"}

package/dist/anchor.js

@@ -0,0 +1,43 @@
+import { spacing, stroke } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+import { focusIndicatorContract } from "./component-contracts.js";
+export function resolveAnchorItems(items) {
+    if (!Array.isArray(items) || items.length === 0)
+        throw new TypeError("Anchor items must not be empty");
+    const ids = new Set();
+    return items.map((item) => {
+        if (!item || typeof item.id !== "string" || !item.id || /\s/u.test(item.id))
+            throw new TypeError("Anchor id must be a non-empty HTML id without whitespace");
+        if (typeof item.label !== "string" || !item.label.trim())
+            throw new TypeError("Anchor label must not be empty");
+        if (ids.has(item.id))
+            throw new TypeError(`Duplicate Anchor id: ${item.id}`);
+        ids.add(item.id);
+        return { ...item, href: `#${encodeURIComponent(item.id)}` };
+    });
+}
+/** Positions use one viewport's coordinates. DOM reads and scroll ownership stay in the renderer. */
+export function getAnchorCurrentId(positions, offset = 0, atEnd = false) {
+    if (!Number.isFinite(offset) || offset < 0)
+        throw new RangeError("Anchor offset must be non-negative");
+    if (positions.some(({ top }) => !Number.isFinite(top)))
+        throw new TypeError("Anchor positions must be finite");
+    const ordered = [...positions].sort((a, b) => a.top - b.top);
+    if (atEnd)
+        return ordered.at(-1)?.id;
+    return ordered.filter(({ top }) => top <= offset).at(-1)?.id ?? ordered[0]?.id;
+}
+export const anchorRecipe = {
+    slots: ["root", "list", "link", "indicator"],
+    gap: spacing.xxs,
+    link: { padding: spacing.xs, color: semanticColors.content.secondary },
+    current: { color: semanticColors.content.brand, border: semanticColors.border.focus, width: stroke.strong },
+    focus: focusIndicatorContract,
+};
+export const anchorBehavior = {
+    controlled: [], inputs: ["items", "offset", "container", "historyMode"], stateAxes: {},
+    web: { roles: ["navigation", "list", "listitem", "link"], keyboard: ["Tab", "Enter"], focus: "native" },
+    native: { roles: [], states: [], actions: [] },
+    scenarios: ["scroll-position-selects-one-current-location", "activation-focuses-target-and-preserves-offset", "reduced-motion-jumps-instantly", "browser-history-restores-a-section", "missing-targets-are-not-current"],
+};
+//# sourceMappingURL=anchor.js.map

package/dist/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAIlE,MAAM,UAAU,kBAAkB,CAAC,KAA4B;IAC7D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;IACvG,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACxB,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;QAC7J,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE;YAAE,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;QAChH,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,wBAAwB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7E,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,kBAAkB,CAAC,SAA2D,EAAE,MAAM,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK;IACvH,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,oCAAoC,CAAC,CAAC;IACvG,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,SAAS,CAAC,iCAAiC,CAAC,CAAC;IAC/G,MAAM,OAAO,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7D,IAAI,KAAK;QAAE,OAAO,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACrC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACjF,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,CAAU;IACrD,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,IAAI,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS,EAAE;IACtE,OAAO,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;IAC3G,KAAK,EAAE,sBAAsB;CACrB,CAAC;AACX,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,CAAC,EAAE,SAAS,EAAE,EAAE;IACtF,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE;IACvG,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IAC9C,SAAS,EAAE,CAAC,8CAA8C,EAAE,gDAAgD,EAAE,gCAAgC,EAAE,oCAAoC,EAAE,iCAAiC,CAAC;CACrL,CAAC","sourcesContent":["import type { BehaviorContract } from \"./behaviors.js\";\nimport { spacing, stroke } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\n\n/** IDs refer to same-document sections, never arbitrary external destinations. */\nexport type AnchorItem = Readonly<{ id: string; label: string }>;\nexport function resolveAnchorItems(items: readonly AnchorItem[]) {\n  if (!Array.isArray(items) || items.length === 0) throw new TypeError(\"Anchor items must not be empty\");\n  const ids = new Set<string>();\n  return items.map((item) => {\n    if (!item || typeof item.id !== \"string\" || !item.id || /\\s/u.test(item.id)) throw new TypeError(\"Anchor id must be a non-empty HTML id without whitespace\");\n    if (typeof item.label !== \"string\" || !item.label.trim()) throw new TypeError(\"Anchor label must not be empty\");\n    if (ids.has(item.id)) throw new TypeError(`Duplicate Anchor id: ${item.id}`);\n    ids.add(item.id);\n    return { ...item, href: `#${encodeURIComponent(item.id)}` };\n  });\n}\n\n/** Positions use one viewport's coordinates. DOM reads and scroll ownership stay in the renderer. */\nexport function getAnchorCurrentId(positions: readonly Readonly<{ id: string; top: number }>[], offset = 0, atEnd = false): string | undefined {\n  if (!Number.isFinite(offset) || offset < 0) throw new RangeError(\"Anchor offset must be non-negative\");\n  if (positions.some(({ top }) => !Number.isFinite(top))) throw new TypeError(\"Anchor positions must be finite\");\n  const ordered = [...positions].sort((a, b) => a.top - b.top);\n  if (atEnd) return ordered.at(-1)?.id;\n  return ordered.filter(({ top }) => top <= offset).at(-1)?.id ?? ordered[0]?.id;\n}\n\nexport const anchorRecipe = {\n  slots: [\"root\", \"list\", \"link\", \"indicator\"] as const,\n  gap: spacing.xxs,\n  link: { padding: spacing.xs, color: semanticColors.content.secondary },\n  current: { color: semanticColors.content.brand, border: semanticColors.border.focus, width: stroke.strong },\n  focus: focusIndicatorContract,\n} as const;\nexport const anchorBehavior = {\n  controlled: [], inputs: [\"items\", \"offset\", \"container\", \"historyMode\"], stateAxes: {},\n  web: { roles: [\"navigation\", \"list\", \"listitem\", \"link\"], keyboard: [\"Tab\", \"Enter\"], focus: \"native\" },\n  native: { roles: [], states: [], actions: [] },\n  scenarios: [\"scroll-position-selects-one-current-location\", \"activation-focuses-target-and-preserves-offset\", \"reduced-motion-jumps-instantly\", \"browser-history-restores-a-section\", \"missing-targets-are-not-current\"],\n} as const satisfies BehaviorContract;\n"]}

package/dist/asset.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 아이콘·이미지·Lottie·비디오를 **같은 액자**에 넣는 자리.
+ *
+ * Icon·Image·Avatar가 이미 있는데 왜 또 두는가: 세 컴포넌트는 각자 다른 모양 규칙을 갖고
+ * 있고(아이콘은 정사각, Avatar는 원, Image는 비율), 화면에서 이들이 **같은 줄에 섞여**
+ * 나올 때 크기와 모서리가 어긋난다. Diairy의 `LottieArt`·`AnimalArt`가 그 어긋남을
+ * 제품 안에서 다시 맞추고 있었다. Asset은 그 액자 규칙만 갖고, **무엇을 그릴지는 슬롯으로
+ * 받는다** — Lottie와 비디오 재생기를 이 패키지가 의존하지 않기 위해서다.
+ *
+ * 그래서 이 계약에 재생 상태(play/pause/seek)가 없다. 재생기는 제품 것이고, 여기서
+ * 정하는 것은 액자·크기·겹침·보조 표식뿐이다.
+ */
+export type AssetMediaKind = "icon" | "image" | "lottie" | "video";
+export type AssetShape = "square" | "rounded" | "circle";
+export type AssetSize = "small" | "medium" | "large" | "xlarge";
+export type AssetDescriptor = Readonly<{
+    kind: AssetMediaKind;
+    size?: AssetSize;
+    shape?: AssetShape;
+    /**
+     * 장식이면 `true`. 장식이 아닌데 이름이 없으면 거절한다 — 움직이는 그림일수록
+     * "무엇을 뜻하는지"가 화면에 없으면 보조기기에서 사라진다.
+     */
+    decorative?: boolean;
+    accessibilityLabel?: string;
+}>;
+export declare function validateAssetDescriptor(descriptor: AssetDescriptor): void;
+/**
+ * 움직이는 자산은 `reducedMotion`에서 **첫 프레임(또는 포스터)로 정지**한다. 숨기지
+ * 않는 이유: 그 자리에 그림이 있다는 사실 자체가 화면의 뜻인 경우가 많다(에어리의 동물).
+ * 정지 화면을 제품이 주지 못하면 재생을 멈추기만 한다.
+ */
+export declare function shouldAnimateAsset(kind: AssetMediaKind, reducedMotion: boolean): boolean;
+export declare const assetRecipe: {
+    readonly slots: readonly ["root", "frame", "media", "accessory", "group"];
+    readonly kinds: readonly ["icon", "image", "lottie", "video"];
+    readonly defaults: {
+        readonly size: "medium";
+        readonly shape: "rounded";
+    };
+    readonly sizes: {
+        readonly small: 32;
+        readonly medium: 48;
+        readonly large: 72;
+        readonly xlarge: 120;
+    };
+    readonly shapes: {
+        readonly square: 0;
+        readonly rounded: 12;
+        readonly circle: 999;
+    };
+    readonly background: Readonly<{
+        source: "theme";
+        key: "surfaceAlt";
+        alpha?: number;
+    }>;
+    readonly border: Readonly<{
+        source: "theme";
+        key: "border";
+        alpha?: number;
+    }>;
+    /** 묶음으로 겹칠 때의 비율. Avatar와 같은 값을 쓴다 — 한 줄에 섞여 나오기 때문이다. */
+    readonly overlapRatio: 0.3;
+    /** 보조 표식(재생 아이콘·상태 점)은 액자 **바깥 모서리**에 붙어 매체를 가리지 않는다. */
+    readonly accessory: {
+        readonly offset: 4;
+        readonly gap: 4;
+    };
+};
+export declare const assetBehavior: {
+    /** 상태가 없다 — 액자는 값을 갖지 않고 슬롯만 받는다. */
+    readonly controlled: readonly [];
+    readonly inputs: readonly ["kind", "size", "shape", "decorative", "accessibilityLabel"];
+    readonly configuration: {
+        readonly kind: readonly ["icon", "image", "lottie", "video"];
+        readonly shape: readonly ["square", "rounded", "circle"];
+        readonly size: readonly ["small", "medium", "large", "xlarge"];
+    };
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled"];
+    };
+    readonly web: {
+        readonly roles: readonly ["img", "presentation"];
+        readonly keyboard: readonly [];
+        readonly focus: "none";
+    };
+    readonly native: {
+        readonly roles: readonly ["image"];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["one-frame-rule-covers-icon-image-lottie-and-video-so-a-mixed-row-lines-up", "the-package-never-depends-on-a-player-the-media-arrives-as-a-slot", "a-meaningful-asset-without-a-name-is-rejected-instead-of-silently-decorative", "reduced-motion-freezes-the-frame-rather-than-removing-the-asset", "an-accessory-sits-on-the-frames-outer-corner-and-never-covers-the-media"];
+};
+//# sourceMappingURL=asset.d.ts.map

package/dist/asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset.d.ts","sourceRoot":"","sources":["../src/asset.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AACnE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC;AACzD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC,CAAC;AAEH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,eAAe,GAAG,IAAI,CAazE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,cAAc,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAExF;AAED,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAUtB,0DAA0D;;IAE1D,yDAAyD;;;;;CAEjD,CAAC;AAEX,eAAO,MAAM,aAAa;IACxB,qCAAqC;;;;;;;;;;;;;;;;;;;;;;CAkBF,CAAC"}

package/dist/asset.js

@@ -0,0 +1,60 @@
+import { radius, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export function validateAssetDescriptor(descriptor) {
+    if (!assetRecipe.kinds.includes(descriptor.kind)) {
+        throw new TypeError(`Unsupported Asset kind: ${String(descriptor.kind)}`);
+    }
+    const decorative = descriptor.decorative ?? false;
+    const label = descriptor.accessibilityLabel?.trim() ?? "";
+    if (!decorative && label.length === 0) {
+        throw new TypeError("A meaningful Asset must provide accessibilityLabel");
+    }
+    if (decorative && label.length > 0) {
+        // 둘 다 주면 어느 쪽이 참인지 화면이 모른다. 조용히 무시하면 이름을 지운 줄 모른다.
+        throw new TypeError("A decorative Asset must not provide accessibilityLabel");
+    }
+}
+/**
+ * 움직이는 자산은 `reducedMotion`에서 **첫 프레임(또는 포스터)로 정지**한다. 숨기지
+ * 않는 이유: 그 자리에 그림이 있다는 사실 자체가 화면의 뜻인 경우가 많다(에어리의 동물).
+ * 정지 화면을 제품이 주지 못하면 재생을 멈추기만 한다.
+ */
+export function shouldAnimateAsset(kind, reducedMotion) {
+    return (kind === "lottie" || kind === "video") && !reducedMotion;
+}
+export const assetRecipe = {
+    slots: ["root", "frame", "media", "accessory", "group"],
+    kinds: ["icon", "image", "lottie", "video"],
+    defaults: { size: "medium", shape: "rounded" },
+    sizes: { small: 32, medium: 48, large: 72, xlarge: 120 },
+    // 정사각은 모서리 0이다 — radius 토큰에 0이 없는 이유는 "모서리 없음"이 토큰이 아니라
+    // 값의 부재이기 때문이다.
+    shapes: { square: 0, rounded: radius.md, circle: radius.full },
+    background: semanticColors.surface.sunken,
+    border: semanticColors.border.default,
+    /** 묶음으로 겹칠 때의 비율. Avatar와 같은 값을 쓴다 — 한 줄에 섞여 나오기 때문이다. */
+    overlapRatio: 0.3,
+    /** 보조 표식(재생 아이콘·상태 점)은 액자 **바깥 모서리**에 붙어 매체를 가리지 않는다. */
+    accessory: { offset: spacing.xxs, gap: spacing.xxs },
+};
+export const assetBehavior = {
+    /** 상태가 없다 — 액자는 값을 갖지 않고 슬롯만 받는다. */
+    controlled: [],
+    inputs: ["kind", "size", "shape", "decorative", "accessibilityLabel"],
+    configuration: {
+        kind: ["icon", "image", "lottie", "video"],
+        shape: ["square", "rounded", "circle"],
+        size: ["small", "medium", "large", "xlarge"],
+    },
+    stateAxes: { availability: ["enabled"] },
+    web: { roles: ["img", "presentation"], keyboard: [], focus: "none" },
+    native: { roles: ["image"], states: [], actions: [] },
+    scenarios: [
+        "one-frame-rule-covers-icon-image-lottie-and-video-so-a-mixed-row-lines-up",
+        "the-package-never-depends-on-a-player-the-media-arrives-as-a-slot",
+        "a-meaningful-asset-without-a-name-is-rejected-instead-of-silently-decorative",
+        "reduced-motion-freezes-the-frame-rather-than-removing-the-asset",
+        "an-accessory-sits-on-the-frames-outer-corner-and-never-covers-the-media",
+    ],
+};
+//# sourceMappingURL=asset.js.map