@hjmds/design-contracts 0.8.2

package/dist/upload-item.d.ts

@@ -0,0 +1,173 @@
+export type UploadItemStatus = "pending" | "uploading" | "success" | "error";
+export type UploadItemPendingState = Readonly<{
+    status: "pending";
+}>;
+export type UploadItemUploadingState = Readonly<{
+    status: "uploading";
+    /** Product-measured transfer fraction. `null` means indeterminate — size unknown. */
+    progress: number | null;
+    /** Product-formatted announcement, e.g. "1.6MB / 3.2MB 업로드 중". */
+    progressLabel?: string;
+}>;
+export type UploadItemSuccessState = Readonly<{
+    status: "success";
+}>;
+export type UploadItemErrorState = Readonly<{
+    status: "error";
+    /** States the problem and the next action, e.g. "네트워크 오류입니다. 다시 시도해주세요." */
+    message: string;
+}>;
+/**
+ * Cancel and retry are never stored as separate booleans: deriving them from
+ * `status` (see `getUploadItemAvailableAction`) makes "cancel while error" or
+ * "retry while uploading" unrepresentable, the same way `SheetOpenState` and
+ * `LoadMoreState` close off invalid combinations by construction.
+ */
+export type UploadItemState = UploadItemPendingState | UploadItemUploadingState | UploadItemSuccessState | UploadItemErrorState;
+export type UploadItemDescriptor = Readonly<{
+    id: string;
+    name: string;
+    /** Product-formatted size, e.g. "1.2 MB" — HJM does not format bytes. */
+    sizeLabel?: string;
+    state: UploadItemState;
+}>;
+export type UploadItemLabels = Readonly<{
+    pending: string;
+    /** Fallback when `progress` is `null` or `progressLabel` is absent. */
+    uploading: string;
+    success: string;
+    cancel: string;
+    retry: string;
+}>;
+export declare function validateUploadItemState(state: UploadItemState): void;
+export declare function validateUploadItemDescriptor(descriptor: UploadItemDescriptor): void;
+export declare function validateUploadItemLabels(labels: UploadItemLabels): void;
+/** Rejects duplicate stable ids so a rendered list never desyncs a row's identity. */
+export declare function validateUploadItemList(items: readonly UploadItemDescriptor[]): void;
+export type UploadItemAction = "cancel" | "retry";
+/**
+ * The only place cancel/retry availability is computed. Renderers must not
+ * keep their own copy of this rule — it would drift from `status` the first
+ * time a new state is added.
+ */
+export declare function getUploadItemAvailableAction(state: UploadItemState): UploadItemAction | null;
+export type UploadItemAnnouncement = Readonly<{
+    /** Accessible name — the file name, kept independent of status (Statistic precedent). */
+    label: string;
+    /** Accessible description/live-region text. Never color-only. */
+    description: string;
+}>;
+/**
+ * Falls back to a rounded percent when a product supplies numeric `progress`
+ * but no `progressLabel` — the one place this module computes visible copy
+ * itself, mirroring Slider's raw-value fallback rather than Statistic's
+ * strict "product always formats" rule, because an uploading row with no
+ * numeric feedback at all is a worse default than a plain percentage.
+ */
+export declare function resolveUploadItemAnnouncement(descriptor: UploadItemDescriptor, labels: UploadItemLabels): UploadItemAnnouncement;
+export declare const uploadItemRecipe: {
+    readonly slots: readonly ["root", "icon", "name", "meta", "progress", "statusText", "cancel", "retry"];
+    readonly defaults: {
+        readonly size: "medium";
+    };
+    readonly row: {
+        readonly minHeight: 68;
+        readonly paddingHorizontal: 16;
+        readonly gap: 12;
+        readonly radius: "md";
+    };
+    readonly name: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly textVariant: "body";
+    };
+    readonly meta: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+    };
+    readonly statusTones: {
+        readonly pending: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly uploading: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly success: Readonly<{
+            source: "accent";
+            key: "success";
+            alpha?: number;
+        }>;
+        readonly error: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+    };
+    /** Reuses `progressRecipe` verbatim — no second progress bar. */
+    readonly progress: {
+        readonly size: "medium";
+        readonly tone: "brand";
+        readonly errorTone: "danger";
+    };
+    readonly action: {
+        readonly minTarget: 44;
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly dangerColor: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly disabledOpacity: 0.5;
+    };
+};
+/**
+ * `stateAxes.content` maps status onto the common axis
+ * (pending→idle, uploading→loading, success→complete, error→error).
+ * `loadingMore`/`empty` do not apply — one row is never paginated.
+ */
+export declare const uploadItemBehavior: {
+    readonly controlled: readonly [];
+    readonly inputs: readonly ["descriptor", "labels"];
+    readonly events: readonly ["onCancel", "onRetry"];
+    readonly stateAxes: {
+        readonly content: readonly ["idle", "loading", "complete", "error"];
+    };
+    readonly web: {
+        readonly roles: readonly ["group", "progressbar", "button"];
+        readonly keyboard: readonly ["Tab", "Enter", "Space"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["progressbar", "button"];
+        readonly states: readonly ["busy"];
+        readonly actions: readonly ["cancel", "retry"];
+    };
+    readonly scenarios: readonly ["progress-is-announced-as-a-sentence-not-only-a-filled-bar", "cancel-is-reachable-only-while-uploading", "retry-is-reachable-only-while-error", "pending-and-success-expose-no-destructive-or-retry-action", "indeterminate-progress-falls-back-to-a-static-uploading-label", "reuses-the-shared-progress-recipe-instead-of-a-new-bar", "duplicate-ids-in-a-rendered-list-are-rejected"];
+};
+//# sourceMappingURL=upload-item.d.ts.map

package/dist/upload-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-item.d.ts","sourceRoot":"","sources":["../src/upload-item.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAE7E,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAErE,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,MAAM,EAAE,WAAW,CAAC;IACpB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAErE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB,sBAAsB,GACtB,wBAAwB,GACxB,sBAAsB,GACtB,oBAAoB,CAAC;AAEzB,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,eAAe,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAQH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CAoBpE;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAKnF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAIvE;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,GAAG,IAAI,CASnF;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,GAAG,IAAI,CAI5F;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,oBAAoB,EAChC,MAAM,EAAE,gBAAgB,GACvB,sBAAsB,CAmBxB;AAED,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAiB3B,iEAAiE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkClE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;CA0BM,CAAC"}

package/dist/upload-item.js

@@ -0,0 +1,156 @@
+import { focusIndicatorContract } from "./component-contracts.js";
+import { progressRecipe, } from "./progress-recipe.js";
+import { control, layout, opacity, radius, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`UploadItem ${field} must not be empty`);
+    }
+}
+export function validateUploadItemState(state) {
+    const status = state.status;
+    if (status !== "pending" &&
+        status !== "uploading" &&
+        status !== "success" &&
+        status !== "error") {
+        throw new TypeError(`Unsupported UploadItem status: ${String(status)}`);
+    }
+    if (status === "uploading") {
+        const { progress, progressLabel } = state;
+        if (progress !== null && (!Number.isFinite(progress) || progress < 0 || progress > 1)) {
+            throw new RangeError("UploadItem progress must be null or a number between 0 and 1");
+        }
+        if (progressLabel !== undefined)
+            assertNonEmpty(progressLabel, "progressLabel");
+    }
+    if (status === "error") {
+        assertNonEmpty(state.message, "error state message");
+    }
+}
+export function validateUploadItemDescriptor(descriptor) {
+    assertNonEmpty(descriptor.id, "id");
+    assertNonEmpty(descriptor.name, "name");
+    if (descriptor.sizeLabel !== undefined)
+        assertNonEmpty(descriptor.sizeLabel, "sizeLabel");
+    validateUploadItemState(descriptor.state);
+}
+export function validateUploadItemLabels(labels) {
+    for (const field of ["pending", "uploading", "success", "cancel", "retry"]) {
+        assertNonEmpty(labels[field], `labels.${field}`);
+    }
+}
+/** Rejects duplicate stable ids so a rendered list never desyncs a row's identity. */
+export function validateUploadItemList(items) {
+    const ids = new Set();
+    for (const item of items) {
+        validateUploadItemDescriptor(item);
+        if (ids.has(item.id)) {
+            throw new TypeError(`Duplicate UploadItem id: ${item.id}`);
+        }
+        ids.add(item.id);
+    }
+}
+/**
+ * The only place cancel/retry availability is computed. Renderers must not
+ * keep their own copy of this rule — it would drift from `status` the first
+ * time a new state is added.
+ */
+export function getUploadItemAvailableAction(state) {
+    if (state.status === "uploading")
+        return "cancel";
+    if (state.status === "error")
+        return "retry";
+    return null;
+}
+/**
+ * Falls back to a rounded percent when a product supplies numeric `progress`
+ * but no `progressLabel` — the one place this module computes visible copy
+ * itself, mirroring Slider's raw-value fallback rather than Statistic's
+ * strict "product always formats" rule, because an uploading row with no
+ * numeric feedback at all is a worse default than a plain percentage.
+ */
+export function resolveUploadItemAnnouncement(descriptor, labels) {
+    validateUploadItemDescriptor(descriptor);
+    validateUploadItemLabels(labels);
+    const { state } = descriptor;
+    if (state.status === "pending") {
+        return { label: descriptor.name, description: labels.pending };
+    }
+    if (state.status === "uploading") {
+        if (state.progressLabel) {
+            return { label: descriptor.name, description: state.progressLabel };
+        }
+        const description = state.progress === null ? labels.uploading : `${Math.round(state.progress * 100)}%`;
+        return { label: descriptor.name, description };
+    }
+    if (state.status === "success") {
+        return { label: descriptor.name, description: labels.success };
+    }
+    return { label: descriptor.name, description: state.message };
+}
+export const uploadItemRecipe = {
+    slots: ["root", "icon", "name", "meta", "progress", "statusText", "cancel", "retry"],
+    defaults: { size: "medium" },
+    row: {
+        minHeight: layout.rowHeight.twoLine,
+        paddingHorizontal: spacing.md,
+        gap: spacing.sm,
+        radius: "md",
+    },
+    name: { color: semanticColors.content.body, textVariant: "body" },
+    meta: { color: semanticColors.content.secondary, textVariant: "label" },
+    statusTones: {
+        pending: semanticColors.content.secondary,
+        uploading: semanticColors.content.brand,
+        success: semanticColors.feedback.success.foreground,
+        error: semanticColors.content.danger,
+    },
+    /** Reuses `progressRecipe` verbatim — no second progress bar. */
+    progress: {
+        size: progressRecipe.defaults.size,
+        tone: progressRecipe.defaults.tone,
+        errorTone: "danger",
+    },
+    action: {
+        minTarget: control.minTouchTarget,
+        color: semanticColors.content.brand,
+        dangerColor: semanticColors.content.danger,
+    },
+    states: {
+        focus: focusIndicatorContract,
+        disabledOpacity: opacity.disabled,
+    },
+};
+/**
+ * `stateAxes.content` maps status onto the common axis
+ * (pending→idle, uploading→loading, success→complete, error→error).
+ * `loadingMore`/`empty` do not apply — one row is never paginated.
+ */
+export const uploadItemBehavior = {
+    controlled: [],
+    inputs: ["descriptor", "labels"],
+    events: ["onCancel", "onRetry"],
+    stateAxes: {
+        content: ["idle", "loading", "complete", "error"],
+    },
+    web: {
+        roles: ["group", "progressbar", "button"],
+        keyboard: ["Tab", "Enter", "Space"],
+        focus: "native",
+    },
+    native: {
+        roles: ["progressbar", "button"],
+        states: ["busy"],
+        actions: ["cancel", "retry"],
+    },
+    scenarios: [
+        "progress-is-announced-as-a-sentence-not-only-a-filled-bar",
+        "cancel-is-reachable-only-while-uploading",
+        "retry-is-reachable-only-while-error",
+        "pending-and-success-expose-no-destructive-or-retry-action",
+        "indeterminate-progress-falls-back-to-a-static-uploading-label",
+        "reuses-the-shared-progress-recipe-instead-of-a-new-bar",
+        "duplicate-ids-in-a-rendered-list-are-rejected",
+    ],
+};
+//# sourceMappingURL=upload-item.js.map

package/dist/upload-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload-item.js","sourceRoot":"","sources":["../src/upload-item.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { BehaviorContract } from \"./behaviors.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport {\n  progressRecipe,\n  type ProgressSize,\n  type ProgressTone,\n} from \"./progress-recipe.js\";\nimport { control, layout, opacity, radius, spacing, type TextVariant } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\nexport type UploadItemStatus = \"pending\" | \"uploading\" | \"success\" | \"error\";\n\nexport type UploadItemPendingState = Readonly<{ status: \"pending\" }>;\n\nexport type UploadItemUploadingState = Readonly<{\n  status: \"uploading\";\n  /** Product-measured transfer fraction. `null` means indeterminate — size unknown. */\n  progress: number | null;\n  /** Product-formatted announcement, e.g. \"1.6MB / 3.2MB 업로드 중\". */\n  progressLabel?: string;\n}>;\n\nexport type UploadItemSuccessState = Readonly<{ status: \"success\" }>;\n\nexport type UploadItemErrorState = Readonly<{\n  status: \"error\";\n  /** States the problem and the next action, e.g. \"네트워크 오류입니다. 다시 시도해주세요.\" */\n  message: string;\n}>;\n\n/**\n * Cancel and retry are never stored as separate booleans: deriving them from\n * `status` (see `getUploadItemAvailableAction`) makes \"cancel while error\" or\n * \"retry while uploading\" unrepresentable, the same way `SheetOpenState` and\n * `LoadMoreState` close off invalid combinations by construction.\n */\nexport type UploadItemState =\n  | UploadItemPendingState\n  | UploadItemUploadingState\n  | UploadItemSuccessState\n  | UploadItemErrorState;\n\nexport type UploadItemDescriptor = Readonly<{\n  id: string;\n  name: string;\n  /** Product-formatted size, e.g. \"1.2 MB\" — HJM does not format bytes. */\n  sizeLabel?: string;\n  state: UploadItemState;\n}>;\n\nexport type UploadItemLabels = Readonly<{\n  pending: string;\n  /** Fallback when `progress` is `null` or `progressLabel` is absent. */\n  uploading: string;\n  success: string;\n  cancel: string;\n  retry: string;\n}>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`UploadItem ${field} must not be empty`);\n  }\n}\n\nexport function validateUploadItemState(state: UploadItemState): void {\n  const status = (state as Readonly<{ status?: unknown }>).status;\n  if (\n    status !== \"pending\" &&\n    status !== \"uploading\" &&\n    status !== \"success\" &&\n    status !== \"error\"\n  ) {\n    throw new TypeError(`Unsupported UploadItem status: ${String(status)}`);\n  }\n  if (status === \"uploading\") {\n    const { progress, progressLabel } = state as UploadItemUploadingState;\n    if (progress !== null && (!Number.isFinite(progress) || progress < 0 || progress > 1)) {\n      throw new RangeError(\"UploadItem progress must be null or a number between 0 and 1\");\n    }\n    if (progressLabel !== undefined) assertNonEmpty(progressLabel, \"progressLabel\");\n  }\n  if (status === \"error\") {\n    assertNonEmpty((state as UploadItemErrorState).message, \"error state message\");\n  }\n}\n\nexport function validateUploadItemDescriptor(descriptor: UploadItemDescriptor): void {\n  assertNonEmpty(descriptor.id, \"id\");\n  assertNonEmpty(descriptor.name, \"name\");\n  if (descriptor.sizeLabel !== undefined) assertNonEmpty(descriptor.sizeLabel, \"sizeLabel\");\n  validateUploadItemState(descriptor.state);\n}\n\nexport function validateUploadItemLabels(labels: UploadItemLabels): void {\n  for (const field of [\"pending\", \"uploading\", \"success\", \"cancel\", \"retry\"] as const) {\n    assertNonEmpty(labels[field], `labels.${field}`);\n  }\n}\n\n/** Rejects duplicate stable ids so a rendered list never desyncs a row's identity. */\nexport function validateUploadItemList(items: readonly UploadItemDescriptor[]): void {\n  const ids = new Set<string>();\n  for (const item of items) {\n    validateUploadItemDescriptor(item);\n    if (ids.has(item.id)) {\n      throw new TypeError(`Duplicate UploadItem id: ${item.id}`);\n    }\n    ids.add(item.id);\n  }\n}\n\nexport type UploadItemAction = \"cancel\" | \"retry\";\n\n/**\n * The only place cancel/retry availability is computed. Renderers must not\n * keep their own copy of this rule — it would drift from `status` the first\n * time a new state is added.\n */\nexport function getUploadItemAvailableAction(state: UploadItemState): UploadItemAction | null {\n  if (state.status === \"uploading\") return \"cancel\";\n  if (state.status === \"error\") return \"retry\";\n  return null;\n}\n\nexport type UploadItemAnnouncement = Readonly<{\n  /** Accessible name — the file name, kept independent of status (Statistic precedent). */\n  label: string;\n  /** Accessible description/live-region text. Never color-only. */\n  description: string;\n}>;\n\n/**\n * Falls back to a rounded percent when a product supplies numeric `progress`\n * but no `progressLabel` — the one place this module computes visible copy\n * itself, mirroring Slider's raw-value fallback rather than Statistic's\n * strict \"product always formats\" rule, because an uploading row with no\n * numeric feedback at all is a worse default than a plain percentage.\n */\nexport function resolveUploadItemAnnouncement(\n  descriptor: UploadItemDescriptor,\n  labels: UploadItemLabels,\n): UploadItemAnnouncement {\n  validateUploadItemDescriptor(descriptor);\n  validateUploadItemLabels(labels);\n  const { state } = descriptor;\n  if (state.status === \"pending\") {\n    return { label: descriptor.name, description: labels.pending };\n  }\n  if (state.status === \"uploading\") {\n    if (state.progressLabel) {\n      return { label: descriptor.name, description: state.progressLabel };\n    }\n    const description =\n      state.progress === null ? labels.uploading : `${Math.round(state.progress * 100)}%`;\n    return { label: descriptor.name, description };\n  }\n  if (state.status === \"success\") {\n    return { label: descriptor.name, description: labels.success };\n  }\n  return { label: descriptor.name, description: state.message };\n}\n\nexport const uploadItemRecipe = {\n  slots: [\"root\", \"icon\", \"name\", \"meta\", \"progress\", \"statusText\", \"cancel\", \"retry\"] as const,\n  defaults: { size: \"medium\" },\n  row: {\n    minHeight: layout.rowHeight.twoLine,\n    paddingHorizontal: spacing.md,\n    gap: spacing.sm,\n    radius: \"md\",\n  },\n  name: { color: semanticColors.content.body, textVariant: \"body\" },\n  meta: { color: semanticColors.content.secondary, textVariant: \"label\" },\n  statusTones: {\n    pending: semanticColors.content.secondary,\n    uploading: semanticColors.content.brand,\n    success: semanticColors.feedback.success.foreground,\n    error: semanticColors.content.danger,\n  },\n  /** Reuses `progressRecipe` verbatim — no second progress bar. */\n  progress: {\n    size: progressRecipe.defaults.size,\n    tone: progressRecipe.defaults.tone,\n    errorTone: \"danger\",\n  },\n  action: {\n    minTarget: control.minTouchTarget,\n    color: semanticColors.content.brand,\n    dangerColor: semanticColors.content.danger,\n  },\n  states: {\n    focus: focusIndicatorContract,\n    disabledOpacity: opacity.disabled,\n  },\n} as const satisfies {\n  slots: readonly [\n    \"root\",\n    \"icon\",\n    \"name\",\n    \"meta\",\n    \"progress\",\n    \"statusText\",\n    \"cancel\",\n    \"retry\",\n  ];\n  defaults: { size: \"medium\" };\n  row: { minHeight: number; paddingHorizontal: number; gap: number; radius: keyof typeof radius };\n  name: { color: ColorReference; textVariant: TextVariant };\n  meta: { color: ColorReference; textVariant: TextVariant };\n  statusTones: Record<UploadItemStatus, ColorReference>;\n  progress: { size: ProgressSize; tone: ProgressTone; errorTone: ProgressTone };\n  action: { minTarget: number; color: ColorReference; dangerColor: ColorReference };\n  states: { focus: typeof focusIndicatorContract; disabledOpacity: number };\n};\n\n/**\n * `stateAxes.content` maps status onto the common axis\n * (pending→idle, uploading→loading, success→complete, error→error).\n * `loadingMore`/`empty` do not apply — one row is never paginated.\n */\nexport const uploadItemBehavior = {\n  controlled: [],\n  inputs: [\"descriptor\", \"labels\"],\n  events: [\"onCancel\", \"onRetry\"],\n  stateAxes: {\n    content: [\"idle\", \"loading\", \"complete\", \"error\"],\n  },\n  web: {\n    roles: [\"group\", \"progressbar\", \"button\"],\n    keyboard: [\"Tab\", \"Enter\", \"Space\"],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"progressbar\", \"button\"],\n    states: [\"busy\"],\n    actions: [\"cancel\", \"retry\"],\n  },\n  scenarios: [\n    \"progress-is-announced-as-a-sentence-not-only-a-filled-bar\",\n    \"cancel-is-reachable-only-while-uploading\",\n    \"retry-is-reachable-only-while-error\",\n    \"pending-and-success-expose-no-destructive-or-retry-action\",\n    \"indeterminate-progress-falls-back-to-a-static-uploading-label\",\n    \"reuses-the-shared-progress-recipe-instead-of-a-new-bar\",\n    \"duplicate-ids-in-a-rendered-list-are-rejected\",\n  ],\n} as const satisfies BehaviorContract;\n"]}

package/dist/version.d.ts

@@ -0,0 +1,3 @@
+/** Package release shown by documentation surfaces. Kept in sync by a test. */
+export declare const designSystemVersion: "0.8.2";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,EAAG,OAAgB,CAAC"}

package/dist/version.js

@@ -0,0 +1,3 @@
+/** Package release shown by documentation surfaces. Kept in sync by a test. */
+export const designSystemVersion = "0.8.2";
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAgB,CAAC","sourcesContent":["/** Package release shown by documentation surfaces. Kept in sync by a test. */\nexport const designSystemVersion = \"0.8.2\" as const;\n"]}

package/docs/affix.md

@@ -0,0 +1,63 @@
+# Affix — 계약을 만들지 않는다
+
+## 문제로 제기된 것
+
+Ant Design `Affix`는 스크롤이 특정 지점을 지나면 임의 요소를 화면에 고정합니다. 검토
+관찰은 두 가지였습니다 — `TopBar`가 이미 있고(`src/layout.ts:9`, RN `native`, beta), Web
+CSS `position: sticky`가 대부분을 푼다면, 이것이 컴포넌트인지 아니면 레이아웃 기법인지
+확인하라는 것과, `docs/expansion-roadmap.md`의 `Stack` 판정("반복되는 내부 flex를 감싸는
+것만으로 제품 의미나 접근성 계약이 생기지 않는다")이 그대로 적용될 가능성이 높다는
+것이었습니다.
+
+## 판정: 만들지 않는다
+
+### 1. 관찰된 모든 실사용은 이미 다른 컴포넌트나 CSS 한 줄이 소유한다
+
+- **BurnTok** 웹 헤더(`apps/web/src/app/page.tsx:118`, `messages/page.tsx:27`,
+  `u/[id]/ProfileClient.tsx:80`, `c/[id]/StoryClient.tsx:287`,
+  `notifications/page.tsx:44`)는 모두 `<header className="sticky top-0 ...">`로 상단바를
+  고정합니다. 이는 정확히 `TopBar`의 자리이고, `position: sticky` 한 줄로 끝나는
+  문제입니다 — 스크롤 진행률 계산, 고정 해제 조건 분기, 별도 controlled 상태 없이 CSS가
+  전부 해결합니다.
+- **Yajalal RN**에도 이미 `TopBar` 구현(`modules/app-rn/src/components/ui/AppTopBar.tsx`)이
+  있습니다. Native는애초에 헤더가 화면 최상단에 고정 마운트되는 것이 기본값이라
+  "스크롤 임계값을 지나면 고정"이라는 Affix 특유의 조건 자체가 성립하지 않습니다.
+- 그 외 "고정" 관련 코드는 각 컴포넌트가 이미 소유한 문제입니다: `StatTable`의 첫 열
+  고정(`stickyFirstColumn`, `stat-table-contract.ts:23`)은 표 내부 anatomy이고,
+  `BottomCTA`의 하단 고정 영역(`AppBottomCTA.tsx:39` "Safe-area-aware sticky action
+  area")은 이미 별도 컴포넌트로 계약돼 있습니다. 둘 다 "임의 요소를 고정하는 범용
+  wrapper"를 필요로 하지 않습니다.
+
+### 2. 임의 콘텐츠를 고정하는 범용 요구 자체가 관측되지 않는다
+
+antd `Affix`의 핵심 사용법 — 헤더도 테이블도 아닌 **임의 콘텐츠**(플로팅 목차, 사이드
+액션 카드 등)를 스크롤 중간에 고정 — 는 두 제품 어디에도 없습니다. 있는 모든 "고정"
+사례는 위처럼 헤더(TopBar) 아니면 특정 컴포넌트 내부 anatomy(StatTable, BottomCTA)로
+이미 이름이 있습니다.
+
+### 3. 계약할 상태 축이 없다
+
+Affix가 컴포넌트가 되려면 "Web과 Native가 각자 다른 기법으로 같은 결과를 낸다"는 공유
+semantic이 있어야 합니다(`docs/architecture.md`의 `adaptive` 정의). 그런데 Web은 CSS
+`position: sticky`(레이아웃 엔진이 처리, JS 상태 없음), Native는 애초에 스크롤에 따라
+고정/해제되는 개념 자체가 드뭅니다(헤더는 기본 고정, 그 외에는 `stickyHeaderIndices`처럼
+리스트 컴포넌트가 소유). 이는 `docs/virtual-list.md`가 항목 높이 추정을 판정한 것과 같은
+모양입니다 — 이름도 단위도 의미도 대응하지 않는 렌더러 힌트일 뿐, 공유할 사용자 의미가
+없습니다.
+
+`Stack`의 판정과 같은 자리입니다: 반복되는 CSS 속성 하나를 감싸는 것만으로 제품 의미나
+접근성 계약이 생기지 않습니다.
+
+## 만들지 않은 것
+
+`src/affix.ts`, `test/affix.test.ts`는 없습니다. `componentCatalog`의
+`{ name: "Affix", category: "utility", platform: "web", status: "planned" }` 행과
+crosswalk의 `Affix → Affix` direct 관계(`src/component-references.ts:125`)는 건드리지
+않습니다.
+
+## 뒤집힐 조건
+
+1. 헤더도 테이블도 CTA도 아닌 **임의 콘텐츠**를 스크롤 중간 지점부터 고정해야 하는 실제
+   화면(예: 긴 폼 옆의 플로팅 요약 카드)이 두 제품 중 하나에 나타난다.
+2. 그 화면에서 CSS `position: sticky`만으로 부족한 요구(예: 여러 sticky 요소의 겹침
+   순서 조정, 고정 해제 시점의 접근성 발표)가 측정된다.

package/docs/anchor.md

@@ -0,0 +1,59 @@
+# Anchor — 계약을 만들지 않는다
+
+## 문제로 제기된 것
+
+Ant Design `Anchor`는 긴 문서 안의 목차 링크를 스크롤 위치와 동기화합니다. 검토
+관찰은, 진짜 계약은 **현재 위치 표시**(`aria-current`), **스크롤 동기화**,
+**reduced motion에서 부드러운 스크롤을 끄는 것**이라는 것과, 두 제품에 긴 문서 화면이
+있는지 확인하라는 것이었습니다.
+
+## 판정: 만들지 않는다
+
+### 1. 두 제품 중 어디에도 목차가 필요한 긴 단일 문서 화면이 없다
+
+- **Yajalal RN**: `약관`/`개인정보처리방침`/`이용약관` 류 화면, 또는 섹션이 여럿인 긴
+  스크롤 문서 화면을 전수 검색했지만 찾지 못했습니다. `modules/app-rn/src/lib/copy/terms.ts`는
+  이름과 달리 법적 약관이 아니라 "같은 개념에는 하나의 단어"를 강제하는 **카피 용어
+  단일 출처**(구단·경기차 표기 등)일 뿐, 목차 내비게이션이 필요한 문서가 아닙니다.
+  화면 구조도 DESIGN_SYSTEM.md가 "48pt 상단바 + overline·대형 제목·설명 문장으로 이루어진
+  페이지 헤더는 쓰지 않는다"로 규정해, 애초에 스크롤 목차가 붙는 긴 article 레이아웃을
+  피하는 방향입니다.
+- **BurnTok**: `apps/web/src/app`의 최상위 라우트(`feed`, `messages`, `notifications`,
+  `u/[id]`, `c/[id]`, `create`, `ideas`, `run` 등)를 전수 확인했지만 약관·도움말·블로그
+  같은 긴 문서 페이지 자체가 없습니다. 앱의 성격(피드형 소셜/영상)상 스크롤 목차가
+  붙을 만한 단일 긴 문서 화면이 없습니다.
+- `anchor`로 두 저장소를 검색했을 때 나온 유일한 실제 코드 매치는 BurnTok
+  `AppTooltip.tsx`/`anchored-overlay.ts`의 "anchor element"였는데, 이는 툴팁이 붙는
+  기준 요소를 뜻하는 **오버레이 위치 계산 용어**로, antd `Anchor`(문서 내 목차)와는
+  이름만 같고 완전히 다른 개념입니다.
+
+### 2. 계약할 상태 축은 유효하지만, 지금 채울 화면이 없다
+
+관찰이 짚은 세 계약(`aria-current` 현재 위치, 스크롤 동기화, reduced motion에서 smooth
+scroll 끄기)은 실제로 새로운 플랫폼 중립 개념입니다 — `BottomNavigation`의
+`aria-current="page"`(`docs/architecture.md` BottomNavigation 절)와 다른 종류의 "현재
+위치" 표시이고, `Toast`/`Sheet`의 Reduce Motion 처리와도 다른 대상(스크롤 애니메이션)에
+적용됩니다. `Notification`/`Dropdown`/`VirtualList`처럼 "문제가 이미 다른 컴포넌트에
+흡수됐다"는 판정은 아닙니다 — 흡수할 곳이 없고, 처음부터 이 문제를 푸는 컴포넌트가
+없다는 뜻입니다.
+
+그럼에도 만들지 않는 이유는 순전히 **측정된 수요 부재**입니다. 목차와 동기화할 긴
+문서 자체가 없는 상태에서 스크롤 동기화 로직을 먼저 설계하면, 실제 문서 구조(섹션
+개수, 중첩 깊이, 모바일에서 세로 목차를 어떻게 접을지)를 모른 채 API를 고정하게 됩니다.
+`docs/authoring-brief.md`와 로드맵이 반복해서 요구하는 "실제 제품 vertical slice 없이
+승격하지 않는다"는 gate 이전에, **애초에 계약을 검증할 화면이 없는** 상태입니다.
+
+## 만들지 않은 것
+
+`src/anchor.ts`, `test/anchor.test.ts`는 없습니다. `componentCatalog`의
+`{ name: "Anchor", category: "navigation", platform: "web", status: "planned" }` 행과
+crosswalk의 `Anchor → Anchor` direct 관계(`src/component-references.ts:64`)는 건드리지
+않습니다.
+
+## 뒤집힐 조건
+
+1. BurnTok 또는 Yajalal(Web 우선, `platform: "web"` 그대로 유지 가능)에 여러 섹션을 가진
+   긴 단일 문서 화면(약관, 도움말, 가이드 등)이 실제로 생긴다.
+2. 그 화면에서 `aria-current` 기반 현재 섹션 표시, 스크롤 동기화, reduced motion의 즉시
+   이동(auto) 전환이 실제로 요구되는 vertical slice가 측정된다 — 그때 이 세 축을 공개
+   상태 축으로 계약한다.

package/docs/ant-design-coverage.md

@@ -0,0 +1,119 @@
+# Ant Design Coverage Benchmark
+
+HJM은 Ant Design을 런타임 의존성이나 호환 API로 사용하지 않습니다. 넓은 컴포넌트 범위를
+놓치지 않기 위한 **reference inventory**로만 사용하며, 각 문제를 HJM의 플랫폼 중립 의미,
+접근성 계약, Web/Native renderer 경계로 다시 번역합니다.
+
+## 고정 기준
+
+- source: [Ant Design Components Overview](https://ant.design/components/overview/)
+- captured: 2026-08-20
+- version: 6.6.1
+- core scope: 73 entries
+- category counts: General 4, Layout 7, Navigation 7, Data Entry 18,
+  Data Display 21, Feedback 11, Other 5
+
+별도 패키지인 Pro Components는 core 73개에 포함하지 않습니다. 이후 page pattern benchmark로
+추가하더라도 별도의 inventory로 관리합니다.
+
+## 기계 판독 가능한 crosswalk
+
+`src/component-references.ts`의 `antDesignReferenceComponents`가 73개 source entry와 rename에
+영향받지 않는 HJM canonical `ComponentId` target을 연결합니다.
+
+- `direct`: 같은 사용자 문제를 거의 같은 component boundary로 해결
+- `adapted`: 같은 문제를 HJM의 명명·플랫폼 의미로 번역
+- `decomposed`: 하나의 Web-first component를 여러 HJM 계약으로 분리
+
+예를 들어 Ant Design `Input`은 `Field`, `SearchField`, `TextArea`, `PasswordField`,
+`OtpField`로 분해하고, `Drawer`는 adaptive `Sheet`와 Web `SidePanel`로 분해합니다. `Message`와 `Notification`은 **둘 다** HJM `Toast`로,
+`Spin`은 `Spinner`, `Table`은 `DataTable`로 연결합니다.
+
+`Notification`이 별도 target을 갖지 않는 이유는 `docs/notification.md`에 있습니다 — antd가
+message와 notification을 가르는 축(정보 층, 지속 시간, 동시 개수, 위치, 긴급도)이 전부
+이미 Toast의 **설정 값**이라, 새 상태 축도 새 접근성 개념도 생기지 않았습니다. 그래서
+`Toast`의 alias로 흡수하고 catalog 행을 따로 두지 않습니다. 그 문서에는 이 판정이 뒤집힐
+조건(화면 밖 push, 별도 알림함 이력처럼 Toast로 표현할 수 없는 요구)도 함께 적혀 있습니다.
+
+`Dropdown`도 같은 판정으로 `Menu`에 흡수했습니다(`docs/dropdown.md`). antd는 Dropdown을
+"트리거에 붙는 오버레이", Menu를 "그 안의 항목 목록"으로 가르지만 HJM `Menu`는 트리거·표면·
+항목을 **모두 소유**합니다. "임의 콘텐츠를 담는 표면"으로 재해석하는 길도 검토했으나 그
+문제는 `Popover`가 이미 점유하고 있어, 측정된 수요 없이 겹치는 두 표면을 만들지 않았습니다.
+
+여러 source entry가 한 target을 가리키는 것은 허용됩니다 — 73개 추적은 **antd의 범위를
+빠짐없이 보는 것**이 목적이지 1:1 대응을 만드는 것이 아닙니다. 반대로 **HJM에 새 컴포넌트를
+만들지 않기로 한 판정도 산출물**입니다. 그 이유와 **판정이 뒤집힐 조건**을 문서로 남기면,
+다음 사람이 같은 질문을 처음부터 다시 하지 않습니다. 이는 import나 prop 호환성을 의미하지 않습니다.
+
+### 「만들지 않는다」에는 네 종류가 있다
+
+판정 문서가 늘어나면서, 같은 결론이 서로 다른 이유에서 나온다는 것이 드러났습니다. 결론이
+같아도 **다음 사람이 재검토할 조건이 다르므로** 문서에서 구별합니다.
+
+| 종류 | 뜻 | 예 | 재검토 신호 |
+|---|---|---|---|
+| **흡수됨** | 그 문제를 이미 다른 컴포넌트가 완결한다 | `Notification`→Toast, `Dropdown`→Menu, `ContextPanel`→SidePanel/Sheet, `Flex`→Stack, `TimePicker`→Select 조합, `Rating`→Slider/Statistic | 흡수한 쪽이 못 푸는 요구가 나올 때 |
+| **검증할 화면이 없음** | 계약 자체는 유효하나 이를 확인할 제품 화면이 없다 | `Anchor`, `Calendar` | 그 화면이 실제로 생길 때 |
+| **거절됨** | 계약도 유효하고 화면이 생겨도 만들지 않는다 | `BorderBeam`(장식), `AppProvider`(런타임뿐), `Utility`(실체 없음) | 정체성이나 아키텍처 경계가 바뀔 때만 |
+| **흡수 대기** | 흡수 판정은 끝났으나 **선결 축이 아직 없다** | `Cascader`(TreeSelect에 `valueMode`/`commitAt`가 추가돼야 성립) | 그 축이 실제로 추가될 때 |
+
+둘을 섞으면 안 됩니다. **흡수됨**은 설계 판단이라 제품이 늘어나도 웬만해선 뒤집히지 않지만,
+**검증할 화면이 없음**은 사실 관찰이라 **커밋 하나로 낡습니다**. 실제로 그런 일이 있었습니다
+(`docs/expansion-roadmap.md`의 「vertical slice가 없는 계약」).
+
+**거절됨**은 넷 중 가장 안정적입니다 — 제품이 아무리 늘어나도 뒤집히지 않고, 정체성이나 계층 경계가 바뀔 때만 재검토합니다.
+
+catalog 행 처리도 여기서 갈립니다. **흡수됨**은 행을 지우고 흡수한 쪽에 `aliases`로 이름을
+남깁니다 — 남겨 두면 "아직 만들 계획"으로 잘못 읽힙니다. **검증할 화면이 없음**은 행을
+그대로 둡니다. 계약은 유효하고 언젠가 채워질 자리이기 때문입니다. **거절됨**은 행을 지울 수 없습니다 — crosswalk의 `targets`가 가리키고 있고 흡수할 다른 이름이 없기 때문입니다. 대신 `ComponentCatalogEntry.declinedReason`에 사유를 적습니다.
+
+**흡수됨은 다시 두 갈래입니다.** 흡수한 대상이 **정확히 하나**면(`Notification`→Toast,
+`Dropdown`→Menu, `Flex`·`Space`→Stack) 행을 지우고 그 하나에 `aliases`로 이름을 남깁니다.
+대상이 **둘 이상의 조합**이면(`TimePicker`→Select 둘, `Rating`→Slider/Statistic,
+`ConfirmPopover`→Popover/AlertDialog) alias를 걸 단일 이름이 없으므로 **행을 그대로 둡니다.**
+이 저장소는 이 답을 세 번 반복해서 냈고, 우연이 아니라 규칙입니다.
+
+**흡수 대기**는 행과 crosswalk를 **둘 다 건드리지 않습니다.** 흡수를 지금 적용하면 아직 만들지
+않은 해결책을 완료로 표시하게 됩니다 — `planned`이 거짓말하던 문제와 방향만 반대인 같은 문제입니다.
+결과는 「검증할 화면이 없음」과 같지만 재검토 신호가 다릅니다: 제품 화면이 아니라 **엔지니어링
+선행 조건**이 신호입니다. `status`는 구현 성숙도 축이고 "만들 것인가"는 다른 질문이라 상태값을 늘리지 않고 직교 필드를 두었습니다 — 그 결정의 영향 범위 비교는 `docs/catalog-decision-status.md`에 있습니다.
+
+## 범위와 구현을 분리한다
+
+crosswalk의 target이 catalog에 존재하면 `tracked`입니다. 아래 분포는 target의
+`stable | beta | planned` **maturity만** 계산하며 renderer 존재 여부는 별도의 Showcase
+evidence registry로 판단합니다.
+
+- fully mature: 모든 target이 stable 또는 beta
+- partial maturity: decomposed target 중 일부만 stable 또는 beta
+- planned only: 모든 target이 planned
+
+2026-08-27 snapshot의 status 기반 분포는 **fully mature 45 / partial maturity 1 /
+planned only 27**입니다. 따라서 73/73 tracking은 73개 구현 완료를 의미하지 않습니다.
+홈과 Component Explorer는 이 수치를 분리해 표시합니다. 이 숫자는 source inventory 수가
+아니라 HJM target의 maturity에서 계산하므로 catalog status가 바뀌면 함께 갱신합니다.
+
+## lifecycle
+
+Ant Design 6.6.1은 기존 `List`를 deprecated로 표시하고 `Listy`를 successor로 추가했습니다.
+reference inventory는 `List.lifecycle = deprecated`, `Listy.lifecycle = new`로 보존하지만 HJM
+`List`를 자동으로 deprecated 처리하지 않습니다. HJM은 기존 비가상 `List`와 planned
+`VirtualList`를 서로 다른 사용 문제로 유지합니다.
+
+## 업데이트 규칙
+
+Ant Design 기준 버전을 올릴 때는 다음을 한 변경 세트에서 수행합니다.
+
+1. 공식 Overview의 version과 category counts 확인
+2. source name 중복과 총합 테스트 갱신
+3. 새 source entry를 canonical HJM target에 연결
+4. 제거·deprecated·new lifecycle 기록
+5. `pnpm check`와 `pnpm showcase:web:build`로 public export와 정적 문서 검증
+
+`pnpm reference:antd:verify`는 npm registry의 현재 `latest`와 고정 version을 비교합니다.
+이 검사는 외부 네트워크와 upstream release 시점에 따라 결과가 달라지므로 일반 `push`/
+`pull_request` 또는 예약 CI 게이트에 넣지 않습니다. 기준 버전을 검토할 때만 로컬에서 명시적으로
+실행합니다. drift를 찾더라도 pin을 자동으로 바꾸지 않고 실패해, 위 다섯 항목을 한 변경 세트로
+검토하게 합니다.
+
+외부 시스템의 외형, token 값, prop 이름, 전용 아이콘·자산은 복사하지 않습니다.