@hjmds/design-contracts 0.8.2

package/dist/pagination.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Web-only by roadmap decision, not an oversight: "Native 긴 목록에는 페이지
+ * 번호보다 LoadMore/infinite loading을 사용한다" (docs/load-more.md). Numbered
+ * pages assume a stable total and a pointing device/keyboard that can jump
+ * around; a touch list scrolling through hundreds of rows has neither. The two
+ * contracts do not need to know about each other — LoadMore never becomes
+ * Pagination and vice versa — but a product choosing between them should pick
+ * Pagination for a bounded, page-addressable result set (search results,
+ * admin tables) and LoadMore for an open-ended feed the user just keeps
+ * scrolling.
+ */
+export type PaginationByCount = Readonly<{
+    currentPage: number;
+    totalCount: number;
+    pageSize: number;
+    totalPages?: never;
+    siblingCount?: number;
+    boundaryCount?: number;
+}>;
+export type PaginationByPageCount = Readonly<{
+    currentPage: number;
+    totalPages: number;
+    totalCount?: never;
+    pageSize?: never;
+    siblingCount?: number;
+    boundaryCount?: number;
+}>;
+/**
+ * Required contract is exactly current page + (total count or total page
+ * count) + page size — nothing else. A page-size changer and a "jump to page"
+ * input are intentionally absent: neither has measured product demand, and
+ * both add a second way to reach the same currentPage/totalPages state this
+ * module already owns. If a product needs them, they compose as separate
+ * controls that call the same onPageChange — they are not missing API surface
+ * here, they are a deliberate exclusion (see docs/pagination.md).
+ */
+export type PaginationDescriptor = PaginationByCount | PaginationByPageCount;
+export type PaginationLabels = Readonly<{
+    previous: string;
+    next: string;
+}>;
+export declare const paginationDescriptorDefaults: {
+    readonly siblingCount: 1;
+    readonly boundaryCount: 1;
+};
+export type PaginationItem = Readonly<{
+    type: "page";
+    page: number;
+}> | Readonly<{
+    type: "ellipsis";
+}>;
+export type PaginationWindowOptions = Readonly<{
+    siblingCount?: number;
+    boundaryCount?: number;
+}>;
+export type PaginationAccessibleNameInfo = Readonly<{
+    page: number;
+    totalPages: number;
+    current: boolean;
+}>;
+/**
+ * Products own the exact phrase order, same reason as Steps'
+ * composeAccessibleName: Korean "5 페이지 중 3 페이지" and an English "page 3
+ * of 5" have different word order, and every page button gets its own
+ * composed name (not just a landmark summary) because ellipsis gaps mean a
+ * bare visible number ("7") does not by itself convey how many pages exist.
+ */
+export type ComposePaginationAccessibleName = (info: PaginationAccessibleNameInfo) => string;
+export type ResolvedPaginationItem = Readonly<{
+    type: "page";
+    page: number;
+    current: boolean;
+    accessibleName: string;
+}> | Readonly<{
+    type: "ellipsis";
+}>;
+export type ResolvedPaginationDescriptor = Readonly<{
+    currentPage: number;
+    totalPages: number;
+    hasPrevious: boolean;
+    hasNext: boolean;
+    labels: PaginationLabels;
+    items: readonly ResolvedPaginationItem[];
+}>;
+export type ResolvePaginationOptions = Readonly<{
+    labels: PaginationLabels;
+    composeAccessibleName: ComposePaginationAccessibleName;
+}>;
+/** Why a page change was requested — analytics and controllers key off this, not the target page alone. */
+export type PaginationChangeReason = "previous" | "next" | "page";
+export type PaginationChangeHandler = (page: number, reason: PaginationChangeReason) => void;
+export declare function validatePaginationDescriptor(descriptor: PaginationDescriptor): void;
+export declare function validatePaginationLabels(labels: PaginationLabels): void;
+/**
+ * Pure page-window function, independent of accessibility naming, so its
+ * boundary inputs (total 1 page, total 2 pages, current at the first/last
+ * page) can be locked with tests without wiring a composer. Builds the set of
+ * pages that must always be visible (both boundaries + the sibling window
+ * around currentPage) and inserts a single ellipsis marker for any gap larger
+ * than one page — never a lone hidden page, never two consecutive ellipses.
+ */
+export declare function computePaginationItems(totalPages: number, currentPage: number, options?: PaginationWindowOptions): readonly PaginationItem[];
+/**
+ * Attaches per-button accessible names and current-page derivation on top of
+ * computePaginationItems. Ellipsis items intentionally carry no
+ * accessibleName — they are decoration ("..."), not content, and must be
+ * `aria-hidden`/excluded from the announcement.
+ */
+export declare function resolvePaginationDescriptor(descriptor: PaginationDescriptor, options: ResolvePaginationOptions): ResolvedPaginationDescriptor;
+/**
+ * Visual recipe only covers chrome (size, gap, focus, current-item tone).
+ * Following identity.md's "primary fill은 주요 행동에, contentBrand는 ...
+ * 현재 위치에" rule and Steps' own current-step treatment
+ * (stepsRecipe.indicator: border + content color, no background fill), the
+ * current page is marked with a `border.focus`/`content.brand` outline, not a
+ * filled `action.brand` pill — a page number is a location, not a command.
+ */
+export declare const paginationRecipe: {
+    readonly slots: readonly ["root", "item", "ellipsis", "previous", "next"];
+    readonly gap: 4;
+    readonly item: {
+        readonly minSize: 44;
+        readonly radius: "md";
+        readonly color: {
+            readonly default: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly current: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+        };
+        readonly background: {
+            readonly hover: Readonly<{
+                source: "theme";
+                key: "text";
+                alpha?: number;
+            }>;
+        };
+        readonly border: {
+            readonly current: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+        };
+    };
+    readonly ellipsis: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly icon: "more";
+    };
+    readonly navIcon: {
+        readonly previous: "chevronStart";
+        readonly next: "chevronEnd";
+    };
+    readonly focus: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly width: 2;
+        readonly offset: 2;
+    };
+    readonly states: {
+        readonly disabledOpacity: 0.5;
+    };
+};
+/**
+ * Literal scenario names for behaviorRegistry.pagination (lead wires into
+ * src/behaviors.ts).
+ */
+export declare const paginationBehaviorScenarios: readonly ["current-page-marked-and-announced-without-a-composed-live-region-spam", "ellipsis-is-decorative-and-excluded-from-the-accessible-tree", "previous-disabled-on-first-page-next-disabled-on-last-page", "single-page-renders-no-ellipsis-and-no-disabled-dead-buttons", "page-window-never-produces-two-consecutive-ellipses", "nav-landmark-present-with-a-localized-accessible-name"];
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

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

package/dist/pagination.js

@@ -0,0 +1,226 @@
+import { focusIndicatorContract } from "./component-contracts.js";
+import { control, opacity, spacing } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const paginationDescriptorDefaults = {
+    siblingCount: 1,
+    boundaryCount: 1,
+};
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 1;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+const descriptorKeys = new Set([
+    "currentPage",
+    "totalCount",
+    "pageSize",
+    "totalPages",
+    "siblingCount",
+    "boundaryCount",
+]);
+function rejectUnknownKeys(value, allowed, field) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw new TypeError(`Unsupported Pagination ${field} field: ${key}`);
+        }
+    }
+}
+function resolveTotalPages(runtime) {
+    const hasTotalPages = Object.prototype.hasOwnProperty.call(runtime, "totalPages");
+    const hasTotalCount = Object.prototype.hasOwnProperty.call(runtime, "totalCount");
+    const hasPageSize = Object.prototype.hasOwnProperty.call(runtime, "pageSize");
+    if (hasTotalPages) {
+        if (hasTotalCount || hasPageSize) {
+            throw new TypeError("Pagination descriptor must not combine totalPages with totalCount/pageSize");
+        }
+        if (!isPositiveInteger(runtime.totalPages)) {
+            throw new RangeError("Pagination totalPages must be a positive integer");
+        }
+        return runtime.totalPages;
+    }
+    if (!hasTotalCount || !hasPageSize) {
+        throw new TypeError("Pagination descriptor requires either totalPages or totalCount with pageSize");
+    }
+    if (!isNonNegativeInteger(runtime.totalCount)) {
+        throw new RangeError("Pagination totalCount must be a non-negative integer");
+    }
+    if (!isPositiveInteger(runtime.pageSize)) {
+        throw new RangeError("Pagination pageSize must be a positive integer");
+    }
+    return Math.max(1, Math.ceil(runtime.totalCount / runtime.pageSize));
+}
+export function validatePaginationDescriptor(descriptor) {
+    if (!isObject(descriptor)) {
+        throw new TypeError("Pagination descriptor must be an object");
+    }
+    rejectUnknownKeys(descriptor, descriptorKeys, "descriptor");
+    const runtime = descriptor;
+    const totalPages = resolveTotalPages(runtime);
+    if (!isPositiveInteger(runtime.currentPage)) {
+        throw new RangeError("Pagination currentPage must be a positive integer");
+    }
+    if (runtime.currentPage > totalPages) {
+        throw new RangeError(`Pagination currentPage ${String(runtime.currentPage)} exceeds totalPages ${totalPages}`);
+    }
+    if (runtime.siblingCount !== undefined &&
+        !isNonNegativeInteger(runtime.siblingCount)) {
+        throw new RangeError("Pagination siblingCount must be a non-negative integer");
+    }
+    if (runtime.boundaryCount !== undefined &&
+        !isNonNegativeInteger(runtime.boundaryCount)) {
+        throw new RangeError("Pagination boundaryCount must be a non-negative integer");
+    }
+}
+export function validatePaginationLabels(labels) {
+    if (!isObject(labels)) {
+        throw new TypeError("Pagination labels must be an object");
+    }
+    for (const field of ["previous", "next"]) {
+        const value = labels[field];
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new TypeError(`Pagination labels.${field} must not be empty`);
+        }
+    }
+}
+/**
+ * Pure page-window function, independent of accessibility naming, so its
+ * boundary inputs (total 1 page, total 2 pages, current at the first/last
+ * page) can be locked with tests without wiring a composer. Builds the set of
+ * pages that must always be visible (both boundaries + the sibling window
+ * around currentPage) and inserts a single ellipsis marker for any gap larger
+ * than one page — never a lone hidden page, never two consecutive ellipses.
+ */
+export function computePaginationItems(totalPages, currentPage, options = {}) {
+    if (!isPositiveInteger(totalPages)) {
+        throw new RangeError("Pagination totalPages must be a positive integer");
+    }
+    if (!isPositiveInteger(currentPage) || currentPage > totalPages) {
+        throw new RangeError(`Pagination currentPage must be an integer between 1 and ${totalPages}`);
+    }
+    const siblingCount = options.siblingCount ?? paginationDescriptorDefaults.siblingCount;
+    const boundaryCount = options.boundaryCount ?? paginationDescriptorDefaults.boundaryCount;
+    if (!isNonNegativeInteger(siblingCount)) {
+        throw new RangeError("Pagination siblingCount must be a non-negative integer");
+    }
+    if (!isNonNegativeInteger(boundaryCount)) {
+        throw new RangeError("Pagination boundaryCount must be a non-negative integer");
+    }
+    const shown = new Set();
+    for (let page = 1; page <= Math.min(boundaryCount, totalPages); page += 1) {
+        shown.add(page);
+    }
+    for (let page = Math.max(1, totalPages - boundaryCount + 1); page <= totalPages; page += 1) {
+        shown.add(page);
+    }
+    for (let page = Math.max(1, currentPage - siblingCount); page <= Math.min(totalPages, currentPage + siblingCount); page += 1) {
+        shown.add(page);
+    }
+    const sortedPages = [...shown].sort((a, b) => a - b);
+    const items = [];
+    let previousPage = null;
+    for (const page of sortedPages) {
+        if (previousPage !== null) {
+            const gap = page - previousPage;
+            // A gap of exactly 2 hides a single page — showing that number costs no
+            // more space than "..." and is more useful, so ellipsis is reserved for
+            // two or more genuinely hidden pages.
+            if (gap === 2) {
+                items.push({ type: "page", page: previousPage + 1 });
+            }
+            else if (gap > 2) {
+                items.push({ type: "ellipsis" });
+            }
+        }
+        items.push({ type: "page", page });
+        previousPage = page;
+    }
+    return items;
+}
+/**
+ * Attaches per-button accessible names and current-page derivation on top of
+ * computePaginationItems. Ellipsis items intentionally carry no
+ * accessibleName — they are decoration ("..."), not content, and must be
+ * `aria-hidden`/excluded from the announcement.
+ */
+export function resolvePaginationDescriptor(descriptor, options) {
+    validatePaginationDescriptor(descriptor);
+    validatePaginationLabels(options.labels);
+    if (typeof options.composeAccessibleName !== "function") {
+        throw new TypeError("Pagination composeAccessibleName must be a function");
+    }
+    const runtime = descriptor;
+    const totalPages = resolveTotalPages(runtime);
+    const currentPage = descriptor.currentPage;
+    const rawItems = computePaginationItems(totalPages, currentPage, {
+        siblingCount: descriptor.siblingCount ?? paginationDescriptorDefaults.siblingCount,
+        boundaryCount: descriptor.boundaryCount ?? paginationDescriptorDefaults.boundaryCount,
+    });
+    const items = rawItems.map((item) => {
+        if (item.type === "ellipsis")
+            return item;
+        const current = item.page === currentPage;
+        const accessibleName = options.composeAccessibleName({
+            page: item.page,
+            totalPages,
+            current,
+        });
+        if (typeof accessibleName !== "string" || accessibleName.trim().length === 0) {
+            throw new TypeError("Pagination composeAccessibleName must return a non-empty string");
+        }
+        return { type: "page", page: item.page, current, accessibleName };
+    });
+    return {
+        currentPage,
+        totalPages,
+        hasPrevious: currentPage > 1,
+        hasNext: currentPage < totalPages,
+        labels: options.labels,
+        items,
+    };
+}
+/**
+ * Visual recipe only covers chrome (size, gap, focus, current-item tone).
+ * Following identity.md's "primary fill은 주요 행동에, contentBrand는 ...
+ * 현재 위치에" rule and Steps' own current-step treatment
+ * (stepsRecipe.indicator: border + content color, no background fill), the
+ * current page is marked with a `border.focus`/`content.brand` outline, not a
+ * filled `action.brand` pill — a page number is a location, not a command.
+ */
+export const paginationRecipe = {
+    slots: ["root", "item", "ellipsis", "previous", "next"],
+    gap: spacing.xxs,
+    item: {
+        minSize: control.minTouchTarget,
+        radius: "md",
+        color: {
+            default: semanticColors.content.body,
+            current: semanticColors.content.brand,
+        },
+        background: { hover: semanticColors.interaction.hover },
+        border: { current: semanticColors.border.focus },
+    },
+    ellipsis: {
+        color: semanticColors.content.secondary,
+        icon: "more",
+    },
+    navIcon: { previous: "chevronStart", next: "chevronEnd" },
+    focus: focusIndicatorContract,
+    states: { disabledOpacity: opacity.disabled },
+};
+/**
+ * Literal scenario names for behaviorRegistry.pagination (lead wires into
+ * src/behaviors.ts).
+ */
+export const paginationBehaviorScenarios = [
+    "current-page-marked-and-announced-without-a-composed-live-region-spam",
+    "ellipsis-is-decorative-and-excluded-from-the-accessible-tree",
+    "previous-disabled-on-first-page-next-disabled-on-last-page",
+    "single-page-renders-no-ellipsis-and-no-disabled-dead-buttons",
+    "page-window-never-produces-two-consecutive-ellipses",
+    "nav-landmark-present-with-a-localized-accessible-name",
+];
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA+CtD,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,YAAY,EAAE,CAAC;IACf,aAAa,EAAE,CAAC;CAC4D,CAAC;AA0D/E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,aAAa;IACb,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,cAAc;IACd,eAAe;CAChB,CAAC,CAAC;AAEH,SAAS,iBAAiB,CACxB,KAAwC,EACxC,OAA4B,EAC5B,KAAa;IAEb,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC,0BAA0B,KAAK,WAAW,GAAG,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,OAA0C;IACnE,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAClF,MAAM,aAAa,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAClF,MAAM,WAAW,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IAE9E,IAAI,aAAa,EAAE,CAAC;QAClB,IAAI,aAAa,IAAI,WAAW,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,4EAA4E,CAC7E,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,UAAU,CAAC,kDAAkD,CAAC,CAAC;QAC3E,CAAC;QACD,OAAO,OAAO,CAAC,UAAU,CAAC;IAC5B,CAAC;IAED,IAAI,CAAC,aAAa,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CACjB,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,UAAU,CAAC,sDAAsD,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,UAAU,CAAC,gDAAgD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,UAAgC;IAEhC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,yCAAyC,CAAC,CAAC;IACjE,CAAC;IACD,iBAAiB,CAAC,UAAU,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,UAA+C,CAAC;IAChE,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,UAAU,CAAC,mDAAmD,CAAC,CAAC;IAC5E,CAAC;IACD,IAAI,OAAO,CAAC,WAAW,GAAG,UAAU,EAAE,CAAC;QACrC,MAAM,IAAI,UAAU,CAClB,0BAA0B,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,uBAAuB,UAAU,EAAE,CACzF,CAAC;IACJ,CAAC;IACD,IACE,OAAO,CAAC,YAAY,KAAK,SAAS;QAClC,CAAC,oBAAoB,CAAC,OAAO,CAAC,YAAY,CAAC,EAC3C,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,wDAAwD,CAAC,CAAC;IACjF,CAAC;IACD,IACE,OAAO,CAAC,aAAa,KAAK,SAAS;QACnC,CAAC,oBAAoB,CAAC,OAAO,CAAC,aAAa,CAAC,EAC5C,CAAC;QACD,MAAM,IAAI,UAAU,CAAC,yDAAyD,CAAC,CAAC;IAClF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,MAAwB;IAC/D,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,SAAS,CAAC,qCAAqC,CAAC,CAAC;IAC7D,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,MAAM,CAAU,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3D,MAAM,IAAI,SAAS,CAAC,qBAAqB,KAAK,oBAAoB,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,WAAmB,EACnB,UAAmC,EAAE;IAErC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,UAAU,CAAC,kDAAkD,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,UAAU,EAAE,CAAC;QAChE,MAAM,IAAI,UAAU,CAClB,2DAA2D,UAAU,EAAE,CACxE,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,4BAA4B,CAAC,YAAY,CAAC;IACvF,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,4BAA4B,CAAC,aAAa,CAAC;IAC1F,IAAI,CAAC,oBAAoB,CAAC,YAAY,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,UAAU,CAAC,wDAAwD,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,CAAC,oBAAoB,CAAC,aAAa,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,UAAU,CAAC,yDAAyD,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC;QAC1E,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,KACE,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,GAAG,aAAa,GAAG,CAAC,CAAC,EACtD,IAAI,IAAI,UAAU,EAClB,IAAI,IAAI,CAAC,EACT,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,KACE,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,GAAG,YAAY,CAAC,EAClD,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAAC,EACxD,IAAI,IAAI,CAAC,EACT,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,IAAI,YAAY,GAAkB,IAAI,CAAC;IACvC,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,IAAI,GAAG,YAAY,CAAC;YAChC,wEAAwE;YACxE,wEAAwE;YACxE,sCAAsC;YACtC,IAAI,GAAG,KAAK,CAAC,EAAE,CAAC;gBACd,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,CAAC,EAAE,CAAC,CAAC;YACvD,CAAC;iBAAM,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;gBACnB,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,YAAY,GAAG,IAAI,CAAC;IACtB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CACzC,UAAgC,EAChC,OAAiC;IAEjC,4BAA4B,CAAC,UAAU,CAAC,CAAC;IACzC,wBAAwB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,IAAI,OAAO,OAAO,CAAC,qBAAqB,KAAK,UAAU,EAAE,CAAC;QACxD,MAAM,IAAI,SAAS,CAAC,qDAAqD,CAAC,CAAC;IAC7E,CAAC;IAED,MAAM,OAAO,GAAG,UAA+C,CAAC;IAChE,MAAM,UAAU,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;IAC3C,MAAM,QAAQ,GAAG,sBAAsB,CAAC,UAAU,EAAE,WAAW,EAAE;QAC/D,YAAY,EACV,UAAU,CAAC,YAAY,IAAI,4BAA4B,CAAC,YAAY;QACtE,aAAa,EACX,UAAU,CAAC,aAAa,IAAI,4BAA4B,CAAC,aAAa;KACzE,CAAC,CAAC;IAEH,MAAM,KAAK,GAA6B,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC5D,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,OAAO,IAAI,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,WAAW,CAAC;QAC1C,MAAM,cAAc,GAAG,OAAO,CAAC,qBAAqB,CAAC;YACnD,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,UAAU;YACV,OAAO;SACR,CAAC,CAAC;QACH,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7E,MAAM,IAAI,SAAS,CACjB,iEAAiE,CAClE,CAAC;QACJ,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;IACpE,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,WAAW;QACX,UAAU;QACV,WAAW,EAAE,WAAW,GAAG,CAAC;QAC5B,OAAO,EAAE,WAAW,GAAG,UAAU;QACjC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,KAAK;KACN,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,CAAU;IAChE,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,IAAI,EAAE;QACJ,OAAO,EAAE,OAAO,CAAC,cAAc;QAC/B,MAAM,EAAE,IAAa;QACrB,KAAK,EAAE;YACL,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;YACpC,OAAO,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK;SACtC;QACD,UAAU,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK,EAAE;QACvD,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,EAAE;KACjD;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;QACvC,IAAI,EAAE,MAAe;KACtB;IACD,OAAO,EAAE,EAAE,QAAQ,EAAE,cAAuB,EAAE,IAAI,EAAE,YAAqB,EAAE;IAC3E,KAAK,EAAE,sBAAsB;IAC7B,MAAM,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,QAAQ,EAAE;CAe9C,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG;IACzC,uEAAuE;IACvE,8DAA8D;IAC9D,4DAA4D;IAC5D,8DAA8D;IAC9D,qDAAqD;IACrD,uDAAuD;CAC/C,CAAC","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { SemanticIconName } from \"./icon.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport { control, opacity, spacing } from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/**\n * Web-only by roadmap decision, not an oversight: \"Native 긴 목록에는 페이지\n * 번호보다 LoadMore/infinite loading을 사용한다\" (docs/load-more.md). Numbered\n * pages assume a stable total and a pointing device/keyboard that can jump\n * around; a touch list scrolling through hundreds of rows has neither. The two\n * contracts do not need to know about each other — LoadMore never becomes\n * Pagination and vice versa — but a product choosing between them should pick\n * Pagination for a bounded, page-addressable result set (search results,\n * admin tables) and LoadMore for an open-ended feed the user just keeps\n * scrolling.\n */\nexport type PaginationByCount = Readonly<{\n  currentPage: number;\n  totalCount: number;\n  pageSize: number;\n  totalPages?: never;\n  siblingCount?: number;\n  boundaryCount?: number;\n}>;\n\nexport type PaginationByPageCount = Readonly<{\n  currentPage: number;\n  totalPages: number;\n  totalCount?: never;\n  pageSize?: never;\n  siblingCount?: number;\n  boundaryCount?: number;\n}>;\n\n/**\n * Required contract is exactly current page + (total count or total page\n * count) + page size — nothing else. A page-size changer and a \"jump to page\"\n * input are intentionally absent: neither has measured product demand, and\n * both add a second way to reach the same currentPage/totalPages state this\n * module already owns. If a product needs them, they compose as separate\n * controls that call the same onPageChange — they are not missing API surface\n * here, they are a deliberate exclusion (see docs/pagination.md).\n */\nexport type PaginationDescriptor = PaginationByCount | PaginationByPageCount;\n\nexport type PaginationLabels = Readonly<{\n  previous: string;\n  next: string;\n}>;\n\nexport const paginationDescriptorDefaults = {\n  siblingCount: 1,\n  boundaryCount: 1,\n} as const satisfies Readonly<{ siblingCount: number; boundaryCount: number }>;\n\nexport type PaginationItem =\n  | Readonly<{ type: \"page\"; page: number }>\n  | Readonly<{ type: \"ellipsis\" }>;\n\nexport type PaginationWindowOptions = Readonly<{\n  siblingCount?: number;\n  boundaryCount?: number;\n}>;\n\nexport type PaginationAccessibleNameInfo = Readonly<{\n  page: number;\n  totalPages: number;\n  current: boolean;\n}>;\n\n/**\n * Products own the exact phrase order, same reason as Steps'\n * composeAccessibleName: Korean \"5 페이지 중 3 페이지\" and an English \"page 3\n * of 5\" have different word order, and every page button gets its own\n * composed name (not just a landmark summary) because ellipsis gaps mean a\n * bare visible number (\"7\") does not by itself convey how many pages exist.\n */\nexport type ComposePaginationAccessibleName = (\n  info: PaginationAccessibleNameInfo,\n) => string;\n\nexport type ResolvedPaginationItem =\n  | Readonly<{\n      type: \"page\";\n      page: number;\n      current: boolean;\n      accessibleName: string;\n    }>\n  | Readonly<{ type: \"ellipsis\" }>;\n\nexport type ResolvedPaginationDescriptor = Readonly<{\n  currentPage: number;\n  totalPages: number;\n  hasPrevious: boolean;\n  hasNext: boolean;\n  labels: PaginationLabels;\n  items: readonly ResolvedPaginationItem[];\n}>;\n\nexport type ResolvePaginationOptions = Readonly<{\n  labels: PaginationLabels;\n  composeAccessibleName: ComposePaginationAccessibleName;\n}>;\n\n/** Why a page change was requested — analytics and controllers key off this, not the target page alone. */\nexport type PaginationChangeReason = \"previous\" | \"next\" | \"page\";\nexport type PaginationChangeHandler = (\n  page: number,\n  reason: PaginationChangeReason,\n) => void;\n\nfunction isObject(value: unknown): value is Readonly<Record<string, unknown>> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction isPositiveInteger(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isInteger(value) && value >= 1;\n}\n\nfunction isNonNegativeInteger(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isInteger(value) && value >= 0;\n}\n\nconst descriptorKeys = new Set([\n  \"currentPage\",\n  \"totalCount\",\n  \"pageSize\",\n  \"totalPages\",\n  \"siblingCount\",\n  \"boundaryCount\",\n]);\n\nfunction rejectUnknownKeys(\n  value: Readonly<Record<string, unknown>>,\n  allowed: ReadonlySet<string>,\n  field: string,\n): void {\n  for (const key of Object.keys(value)) {\n    if (!allowed.has(key)) {\n      throw new TypeError(`Unsupported Pagination ${field} field: ${key}`);\n    }\n  }\n}\n\nfunction resolveTotalPages(runtime: Readonly<Record<string, unknown>>): number {\n  const hasTotalPages = Object.prototype.hasOwnProperty.call(runtime, \"totalPages\");\n  const hasTotalCount = Object.prototype.hasOwnProperty.call(runtime, \"totalCount\");\n  const hasPageSize = Object.prototype.hasOwnProperty.call(runtime, \"pageSize\");\n\n  if (hasTotalPages) {\n    if (hasTotalCount || hasPageSize) {\n      throw new TypeError(\n        \"Pagination descriptor must not combine totalPages with totalCount/pageSize\",\n      );\n    }\n    if (!isPositiveInteger(runtime.totalPages)) {\n      throw new RangeError(\"Pagination totalPages must be a positive integer\");\n    }\n    return runtime.totalPages;\n  }\n\n  if (!hasTotalCount || !hasPageSize) {\n    throw new TypeError(\n      \"Pagination descriptor requires either totalPages or totalCount with pageSize\",\n    );\n  }\n  if (!isNonNegativeInteger(runtime.totalCount)) {\n    throw new RangeError(\"Pagination totalCount must be a non-negative integer\");\n  }\n  if (!isPositiveInteger(runtime.pageSize)) {\n    throw new RangeError(\"Pagination pageSize must be a positive integer\");\n  }\n  return Math.max(1, Math.ceil(runtime.totalCount / runtime.pageSize));\n}\n\nexport function validatePaginationDescriptor(\n  descriptor: PaginationDescriptor,\n): void {\n  if (!isObject(descriptor)) {\n    throw new TypeError(\"Pagination descriptor must be an object\");\n  }\n  rejectUnknownKeys(descriptor, descriptorKeys, \"descriptor\");\n  const runtime = descriptor as Readonly<Record<string, unknown>>;\n  const totalPages = resolveTotalPages(runtime);\n  if (!isPositiveInteger(runtime.currentPage)) {\n    throw new RangeError(\"Pagination currentPage must be a positive integer\");\n  }\n  if (runtime.currentPage > totalPages) {\n    throw new RangeError(\n      `Pagination currentPage ${String(runtime.currentPage)} exceeds totalPages ${totalPages}`,\n    );\n  }\n  if (\n    runtime.siblingCount !== undefined &&\n    !isNonNegativeInteger(runtime.siblingCount)\n  ) {\n    throw new RangeError(\"Pagination siblingCount must be a non-negative integer\");\n  }\n  if (\n    runtime.boundaryCount !== undefined &&\n    !isNonNegativeInteger(runtime.boundaryCount)\n  ) {\n    throw new RangeError(\"Pagination boundaryCount must be a non-negative integer\");\n  }\n}\n\nexport function validatePaginationLabels(labels: PaginationLabels): void {\n  if (!isObject(labels)) {\n    throw new TypeError(\"Pagination labels must be an object\");\n  }\n  for (const field of [\"previous\", \"next\"] as const) {\n    const value = labels[field];\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n      throw new TypeError(`Pagination labels.${field} must not be empty`);\n    }\n  }\n}\n\n/**\n * Pure page-window function, independent of accessibility naming, so its\n * boundary inputs (total 1 page, total 2 pages, current at the first/last\n * page) can be locked with tests without wiring a composer. Builds the set of\n * pages that must always be visible (both boundaries + the sibling window\n * around currentPage) and inserts a single ellipsis marker for any gap larger\n * than one page — never a lone hidden page, never two consecutive ellipses.\n */\nexport function computePaginationItems(\n  totalPages: number,\n  currentPage: number,\n  options: PaginationWindowOptions = {},\n): readonly PaginationItem[] {\n  if (!isPositiveInteger(totalPages)) {\n    throw new RangeError(\"Pagination totalPages must be a positive integer\");\n  }\n  if (!isPositiveInteger(currentPage) || currentPage > totalPages) {\n    throw new RangeError(\n      `Pagination currentPage must be an integer between 1 and ${totalPages}`,\n    );\n  }\n  const siblingCount = options.siblingCount ?? paginationDescriptorDefaults.siblingCount;\n  const boundaryCount = options.boundaryCount ?? paginationDescriptorDefaults.boundaryCount;\n  if (!isNonNegativeInteger(siblingCount)) {\n    throw new RangeError(\"Pagination siblingCount must be a non-negative integer\");\n  }\n  if (!isNonNegativeInteger(boundaryCount)) {\n    throw new RangeError(\"Pagination boundaryCount must be a non-negative integer\");\n  }\n\n  const shown = new Set<number>();\n  for (let page = 1; page <= Math.min(boundaryCount, totalPages); page += 1) {\n    shown.add(page);\n  }\n  for (\n    let page = Math.max(1, totalPages - boundaryCount + 1);\n    page <= totalPages;\n    page += 1\n  ) {\n    shown.add(page);\n  }\n  for (\n    let page = Math.max(1, currentPage - siblingCount);\n    page <= Math.min(totalPages, currentPage + siblingCount);\n    page += 1\n  ) {\n    shown.add(page);\n  }\n\n  const sortedPages = [...shown].sort((a, b) => a - b);\n  const items: PaginationItem[] = [];\n  let previousPage: number | null = null;\n  for (const page of sortedPages) {\n    if (previousPage !== null) {\n      const gap = page - previousPage;\n      // A gap of exactly 2 hides a single page — showing that number costs no\n      // more space than \"...\" and is more useful, so ellipsis is reserved for\n      // two or more genuinely hidden pages.\n      if (gap === 2) {\n        items.push({ type: \"page\", page: previousPage + 1 });\n      } else if (gap > 2) {\n        items.push({ type: \"ellipsis\" });\n      }\n    }\n    items.push({ type: \"page\", page });\n    previousPage = page;\n  }\n  return items;\n}\n\n/**\n * Attaches per-button accessible names and current-page derivation on top of\n * computePaginationItems. Ellipsis items intentionally carry no\n * accessibleName — they are decoration (\"...\"), not content, and must be\n * `aria-hidden`/excluded from the announcement.\n */\nexport function resolvePaginationDescriptor(\n  descriptor: PaginationDescriptor,\n  options: ResolvePaginationOptions,\n): ResolvedPaginationDescriptor {\n  validatePaginationDescriptor(descriptor);\n  validatePaginationLabels(options.labels);\n  if (typeof options.composeAccessibleName !== \"function\") {\n    throw new TypeError(\"Pagination composeAccessibleName must be a function\");\n  }\n\n  const runtime = descriptor as Readonly<Record<string, unknown>>;\n  const totalPages = resolveTotalPages(runtime);\n  const currentPage = descriptor.currentPage;\n  const rawItems = computePaginationItems(totalPages, currentPage, {\n    siblingCount:\n      descriptor.siblingCount ?? paginationDescriptorDefaults.siblingCount,\n    boundaryCount:\n      descriptor.boundaryCount ?? paginationDescriptorDefaults.boundaryCount,\n  });\n\n  const items: ResolvedPaginationItem[] = rawItems.map((item) => {\n    if (item.type === \"ellipsis\") return item;\n    const current = item.page === currentPage;\n    const accessibleName = options.composeAccessibleName({\n      page: item.page,\n      totalPages,\n      current,\n    });\n    if (typeof accessibleName !== \"string\" || accessibleName.trim().length === 0) {\n      throw new TypeError(\n        \"Pagination composeAccessibleName must return a non-empty string\",\n      );\n    }\n    return { type: \"page\", page: item.page, current, accessibleName };\n  });\n\n  return {\n    currentPage,\n    totalPages,\n    hasPrevious: currentPage > 1,\n    hasNext: currentPage < totalPages,\n    labels: options.labels,\n    items,\n  };\n}\n\n/**\n * Visual recipe only covers chrome (size, gap, focus, current-item tone).\n * Following identity.md's \"primary fill은 주요 행동에, contentBrand는 ...\n * 현재 위치에\" rule and Steps' own current-step treatment\n * (stepsRecipe.indicator: border + content color, no background fill), the\n * current page is marked with a `border.focus`/`content.brand` outline, not a\n * filled `action.brand` pill — a page number is a location, not a command.\n */\nexport const paginationRecipe = {\n  slots: [\"root\", \"item\", \"ellipsis\", \"previous\", \"next\"] as const,\n  gap: spacing.xxs,\n  item: {\n    minSize: control.minTouchTarget,\n    radius: \"md\" as const,\n    color: {\n      default: semanticColors.content.body,\n      current: semanticColors.content.brand,\n    },\n    background: { hover: semanticColors.interaction.hover },\n    border: { current: semanticColors.border.focus },\n  },\n  ellipsis: {\n    color: semanticColors.content.secondary,\n    icon: \"more\" as const,\n  },\n  navIcon: { previous: \"chevronStart\" as const, next: \"chevronEnd\" as const },\n  focus: focusIndicatorContract,\n  states: { disabledOpacity: opacity.disabled },\n} as const satisfies {\n  slots: readonly string[];\n  gap: number;\n  item: {\n    minSize: number;\n    radius: \"md\";\n    color: Record<\"default\" | \"current\", ColorReference>;\n    background: Record<\"hover\", ColorReference>;\n    border: Record<\"current\", ColorReference>;\n  };\n  ellipsis: { color: ColorReference; icon: SemanticIconName };\n  navIcon: Record<\"previous\" | \"next\", SemanticIconName>;\n  focus: typeof focusIndicatorContract;\n  states: { disabledOpacity: number };\n};\n\n/**\n * Literal scenario names for behaviorRegistry.pagination (lead wires into\n * src/behaviors.ts).\n */\nexport const paginationBehaviorScenarios = [\n  \"current-page-marked-and-announced-without-a-composed-live-region-spam\",\n  \"ellipsis-is-decorative-and-excluded-from-the-accessible-tree\",\n  \"previous-disabled-on-first-page-next-disabled-on-last-page\",\n  \"single-page-renders-no-ellipsis-and-no-disabled-dead-buttons\",\n  \"page-window-never-produces-two-consecutive-ellipses\",\n  \"nav-landmark-present-with-a-localized-accessible-name\",\n] as const;\n"]}

package/dist/password-field.d.ts

@@ -0,0 +1,187 @@
+/**
+ * PasswordField is Field's existing frame plus exactly one new problem: a
+ * reveal toggle. It does not redeclare Field's own `value`/`onValueChange` —
+ * a password's value is a plain string, identical to Field's, so there is
+ * nothing new to contract there (unlike NumberField, whose value is a parsed
+ * number). See docs/password-field.md.
+ */
+export type PasswordFieldAutofillHint = "current" | "new";
+export type PasswordFieldDescriptor = Readonly<{
+    revealed: boolean;
+    /**
+     * Which password-manager autofill bucket this field is for. Required, not
+     * inferred — HJM cannot tell a login screen from a signup screen from the
+     * descriptor alone, and guessing wrong actively harms the browser/OS
+     * autofill suggestion. See docs/password-field.md for the platform
+     * translation (Web autocomplete token, iOS textContentType, Android
+     * autofill hint) — the exact attribute values are a renderer concern, not
+     * asserted here.
+     */
+    autofillHint: PasswordFieldAutofillHint;
+}>;
+export declare function validatePasswordFieldDescriptor(descriptor: PasswordFieldDescriptor): void;
+export type PasswordToggleAccessibleNameInfo = Readonly<{
+    /**
+     * The action pressing the toggle will perform — not whether the password
+     * is currently masked. See docs/password-field.md for why the name must
+     * describe the action.
+     */
+    willReveal: boolean;
+}>;
+export type ComposePasswordToggleAccessibleName = (info: PasswordToggleAccessibleNameInfo) => string;
+export type ResolvedPasswordFieldDescriptor = PasswordFieldDescriptor & Readonly<{
+    toggleAccessibleName: string;
+    webInputType: "text" | "password";
+    nativeSecureTextEntry: boolean;
+}>;
+export type ResolvePasswordFieldOptions = Readonly<{
+    composeToggleAccessibleName: ComposePasswordToggleAccessibleName;
+}>;
+/**
+ * Toggling `revealed` only ever changes how the value is displayed — it
+ * never touches the value itself. That guarantee is why this resolver takes
+ * no value parameter at all: there is nothing here that could reach into it.
+ */
+export declare function resolvePasswordFieldDescriptor(descriptor: PasswordFieldDescriptor, options: ResolvePasswordFieldOptions): ResolvedPasswordFieldDescriptor;
+export type PasswordFieldSize = "medium" | "large";
+/**
+ * Reuses Field's frame and form support copy verbatim — the same judgment
+ * NumberField already made (see src/number-field.ts) — and adds only the
+ * toggle slot, styled like SearchField's trailing clear button (same
+ * diameter/hit-slop convention) but with the visibility icon pair instead.
+ */
+export declare const passwordFieldRecipe: {
+    readonly slots: readonly ["root", "frame", "input", "toggle", "description", "error"];
+    readonly defaults: {
+        readonly size: "medium";
+    };
+    readonly frame: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surface";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly focusBorder: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly invalidBorder: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+        readonly radius: "md";
+        readonly borderWidth: 1;
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 16;
+    };
+    readonly support: {
+        readonly label: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly textVariant: "body";
+            readonly fontWeight: "600";
+        };
+        readonly hint: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textMuted";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly error: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "danger";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly gap: 8;
+    };
+    readonly sizes: {
+        readonly medium: {
+            readonly minHeight: 44;
+            readonly paddingHorizontal: 16;
+            readonly textVariant: "body";
+            readonly toggleDiameter: 44;
+        };
+        readonly large: {
+            readonly minHeight: 52;
+            readonly paddingHorizontal: 20;
+            readonly textVariant: "bodyLarge";
+            readonly toggleDiameter: 44;
+        };
+    };
+    readonly value: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+    };
+    readonly toggle: {
+        /**
+         * Icon mirrors the same action-not-state judgment as the accessible
+         * name: concealed shows the "eye" (pressing reveals), revealed shows the
+         * "eye-off" (pressing conceals).
+         */
+        readonly icons: {
+            readonly concealed: "visibility";
+            readonly revealed: "visibilityOff";
+        };
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly invalidBorder: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+        readonly disabledOpacity: 0.5;
+    };
+};
+export declare const passwordFieldBehavior: {
+    readonly controlled: readonly ["value", "defaultValue", "onValueChange", "revealed", "defaultRevealed", "onRevealedChange"];
+    readonly inputs: readonly ["autofillHint"];
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled", "readOnly"];
+        readonly value: readonly ["empty", "filled"];
+        readonly validation: readonly ["valid", "invalid"];
+    };
+    readonly web: {
+        readonly roles: readonly ["textbox", "button"];
+        readonly keyboard: readonly ["Tab", "Enter", "Space"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["text", "button"];
+        readonly states: readonly ["disabled"];
+        readonly actions: readonly ["focus", "setText", "toggleReveal"];
+    };
+    readonly scenarios: readonly ["toggle-never-changes-the-controlled-value", "toggle-and-value-are-independent-controlled-axes", "toggle-accessible-name-describes-the-action-not-the-current-state", "toggle-icon-mirrors-the-same-action-not-state-judgment", "toggle-is-its-own-tab-stop-after-the-field-like-searchfields-clear-button", "autofill-hint-is-a-required-product-decision-not-a-renderer-guess", "strength-meter-is-out-of-scope-product-policy"];
+};
+//# sourceMappingURL=password-field.d.ts.map

package/dist/password-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-field.d.ts","sourceRoot":"","sources":["../src/password-field.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GAAG,SAAS,GAAG,KAAK,CAAC;AAE1D,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB;;;;;;;;OAQG;IACH,YAAY,EAAE,yBAAyB,CAAC;CACzC,CAAC,CAAC;AAQH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,uBAAuB,GAClC,IAAI,CAON;AAED,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC;IACtD;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC,CAAC;AAEH,MAAM,MAAM,mCAAmC,GAAG,CAChD,IAAI,EAAE,gCAAgC,KACnC,MAAM,CAAC;AAEZ,MAAM,MAAM,+BAA+B,GAAG,uBAAuB,GACnE,QAAQ,CAAC;IACP,oBAAoB,EAAE,MAAM,CAAC;IAC7B,YAAY,EAAE,MAAM,GAAG,UAAU,CAAC;IAClC,qBAAqB,EAAE,OAAO,CAAC;CAChC,CAAC,CAAC;AAEL,MAAM,MAAM,2BAA2B,GAAG,QAAQ,CAAC;IACjD,2BAA2B,EAAE,mCAAmC,CAAC;CAClE,CAAC,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,uBAAuB,EACnC,OAAO,EAAE,2BAA2B,GACnC,+BAA+B,CAwBjC;AAED,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAuB5B;;;;WAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCN,CAAC;AAEF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;CAkCG,CAAC"}