@hjmds/design-contracts 0.8.2

package/dist/evidence.js

@@ -0,0 +1,133 @@
+import { designSystemVersion } from "./version.js";
+import { createShowcaseCoverage, showcaseManifest, showcaseScenarios, } from "./showcase.js";
+export const designSystemEvidenceSchemaVersion = 1;
+const scenarioIds = new Set(showcaseScenarios.map(({ id }) => id));
+const evidenceSourceKinds = new Set([
+    "storybook",
+    "interaction-test",
+    "accessibility-audit",
+    "visual-regression",
+    "device-test",
+    "contract-test",
+]);
+const surfaces = new Set(["contract", "web", "native"]);
+function requireNonEmptyString(value, field) {
+    if (value.trim().length === 0)
+        throw new Error(`${field} must not be empty`);
+}
+/**
+ * Returns the canonical component story ids that currently require evidence on
+ * one surface. Consumers use this instead of maintaining hard-coded lists.
+ */
+export function getShowcaseStoryIdsForSurface(surface, manifest = showcaseManifest) {
+    return manifest
+        .filter(({ requirements }) => requirements.some((requirement) => requirement.surface === surface))
+        .map(({ storyId }) => storyId);
+}
+/** Compares a product Storybook inventory with the pinned contract package. */
+export function compareShowcaseStoryIds(surface, storyIds, manifest = showcaseManifest) {
+    const expected = getShowcaseStoryIdsForSurface(surface, manifest);
+    const expectedSet = new Set(expected);
+    const actual = [...new Set(storyIds)];
+    const counts = new Map();
+    for (const storyId of storyIds)
+        counts.set(storyId, (counts.get(storyId) ?? 0) + 1);
+    const missing = expected.filter((storyId) => !actual.includes(storyId));
+    const unexpected = actual.filter((storyId) => !expectedSet.has(storyId));
+    const duplicates = [...counts]
+        .filter(([, count]) => count > 1)
+        .map(([storyId]) => storyId)
+        .sort();
+    return {
+        surface,
+        expected,
+        actual,
+        missing,
+        unexpected,
+        duplicates,
+        complete: missing.length === 0 && unexpected.length === 0 && duplicates.length === 0,
+    };
+}
+export function assertShowcaseStoryIds(surface, storyIds, manifest = showcaseManifest) {
+    const result = compareShowcaseStoryIds(surface, storyIds, manifest);
+    if (result.complete)
+        return;
+    throw new Error([
+        `${surface} Storybook inventory does not match the design contract manifest.`,
+        `Missing: ${result.missing.join(", ") || "none"}`,
+        `Unexpected: ${result.unexpected.join(", ") || "none"}`,
+        `Duplicates: ${result.duplicates.join(", ") || "none"}`,
+    ].join("\n"));
+}
+/** Runtime validation for evidence artifacts submitted by product repositories. */
+export function defineDesignSystemEvidence(input, manifest = showcaseManifest) {
+    if (input.schemaVersion !== designSystemEvidenceSchemaVersion) {
+        throw new Error(`Unsupported evidence schema version: ${input.schemaVersion}`);
+    }
+    requireNonEmptyString(input.designSystemVersion, "designSystemVersion");
+    if (input.designSystemVersion !== designSystemVersion) {
+        throw new Error(`Evidence designSystemVersion ${input.designSystemVersion} does not match current ${designSystemVersion}`);
+    }
+    requireNonEmptyString(input.source.id, "source.id");
+    requireNonEmptyString(input.source.product, "source.product");
+    if (!surfaces.has(input.source.surface)) {
+        throw new Error(`Unknown evidence surface: ${input.source.surface}`);
+    }
+    if (!evidenceSourceKinds.has(input.source.kind)) {
+        throw new Error(`Unknown evidence source kind: ${input.source.kind}`);
+    }
+    if (input.source.revision !== undefined)
+        requireNonEmptyString(input.source.revision, "source.revision");
+    const requirementsForSurface = new Map();
+    for (const item of manifest) {
+        const requirement = item.requirements.find(({ surface }) => surface === input.source.surface);
+        if (requirement) {
+            requirementsForSurface.set(item.storyId, new Set(requirement.scenarios));
+        }
+    }
+    const seen = new Set();
+    for (const entry of input.entries) {
+        requireNonEmptyString(entry.storyId, "entries[].storyId");
+        const requiredScenarios = requirementsForSurface.get(entry.storyId);
+        if (!requiredScenarios) {
+            throw new Error(`Evidence ${input.source.id} contains unsupported ${input.source.surface} story: ${entry.storyId}`);
+        }
+        if (seen.has(entry.storyId)) {
+            throw new Error(`Evidence ${input.source.id} contains duplicate story: ${entry.storyId}`);
+        }
+        seen.add(entry.storyId);
+        if (entry.scenarios.length === 0) {
+            throw new Error(`Evidence ${input.source.id}/${entry.storyId} must include at least one scenario`);
+        }
+        const entryScenarios = new Set();
+        for (const scenario of entry.scenarios) {
+            if (!scenarioIds.has(scenario))
+                throw new Error(`Unknown evidence scenario: ${scenario}`);
+            if (!requiredScenarios.has(scenario)) {
+                throw new Error(`Evidence ${input.source.id}/${entry.storyId} scenario ${scenario} is not required for ${input.source.surface}`);
+            }
+            if (entryScenarios.has(scenario)) {
+                throw new Error(`Evidence ${input.source.id}/${entry.storyId} repeats scenario: ${scenario}`);
+            }
+            entryScenarios.add(scenario);
+        }
+    }
+    return input;
+}
+export function createDesignSystemEvidence(source, entries) {
+    return defineDesignSystemEvidence({
+        schemaVersion: designSystemEvidenceSchemaVersion,
+        designSystemVersion,
+        source,
+        entries,
+    });
+}
+export function toShowcaseEvidenceEntries(evidence) {
+    return evidence.flatMap(({ source, entries }) => entries.map(({ storyId, scenarios }) => ({ storyId, surface: source.surface, scenarios })));
+}
+export function createDesignSystemEvidenceCoverage(evidence, manifest = showcaseManifest) {
+    for (const item of evidence)
+        defineDesignSystemEvidence(item, manifest);
+    return createShowcaseCoverage(toShowcaseEvidenceEntries(evidence), manifest);
+}
+//# sourceMappingURL=evidence.js.map

package/dist/evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.js","sourceRoot":"","sources":["../src/evidence.ts"],"names":[],"mappings":"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","sourcesContent":["import { designSystemVersion } from \"./version.js\";\nimport {\n  createShowcaseCoverage,\n  showcaseManifest,\n  showcaseScenarios,\n  type ShowcaseComponentEntry,\n  type ShowcaseCoverageEntry,\n  type ShowcaseEvidenceEntry,\n  type ShowcaseScenarioId,\n  type ShowcaseSurface,\n} from \"./showcase.js\";\n\nexport const designSystemEvidenceSchemaVersion = 1 as const;\n\nexport type DesignSystemEvidenceSourceKind =\n  | \"storybook\"\n  | \"interaction-test\"\n  | \"accessibility-audit\"\n  | \"visual-regression\"\n  | \"device-test\"\n  | \"contract-test\";\n\nexport type DesignSystemEvidenceSource = Readonly<{\n  /** Stable repository or product identifier, for example `burntok-web`. */\n  id: string;\n  /** Human-readable owner shown in generated reports. */\n  product: string;\n  surface: ShowcaseSurface;\n  kind: DesignSystemEvidenceSourceKind;\n  /** Optional immutable Git revision or release identifier. */\n  revision?: string;\n}>;\n\nexport type DesignSystemEvidenceItem = Readonly<{\n  /** Canonical `category/component-id` from `showcaseManifest`. */\n  storyId: string;\n  scenarios: readonly ShowcaseScenarioId[];\n  /** Product Storybook id when it differs from the canonical HJM id. */\n  storybookStoryId?: string;\n}>;\n\nexport type DesignSystemEvidenceManifest = Readonly<{\n  schemaVersion: typeof designSystemEvidenceSchemaVersion;\n  designSystemVersion: string;\n  source: DesignSystemEvidenceSource;\n  entries: readonly DesignSystemEvidenceItem[];\n}>;\n\nexport type ShowcaseStoryIdComparison = Readonly<{\n  surface: ShowcaseSurface;\n  expected: readonly string[];\n  actual: readonly string[];\n  missing: readonly string[];\n  unexpected: readonly string[];\n  duplicates: readonly string[];\n  complete: boolean;\n}>;\n\nconst scenarioIds = new Set<ShowcaseScenarioId>(showcaseScenarios.map(({ id }) => id));\nconst evidenceSourceKinds = new Set<DesignSystemEvidenceSourceKind>([\n  \"storybook\",\n  \"interaction-test\",\n  \"accessibility-audit\",\n  \"visual-regression\",\n  \"device-test\",\n  \"contract-test\",\n]);\nconst surfaces = new Set<ShowcaseSurface>([\"contract\", \"web\", \"native\"]);\n\nfunction requireNonEmptyString(value: string, field: string): void {\n  if (value.trim().length === 0) throw new Error(`${field} must not be empty`);\n}\n\n/**\n * Returns the canonical component story ids that currently require evidence on\n * one surface. Consumers use this instead of maintaining hard-coded lists.\n */\nexport function getShowcaseStoryIdsForSurface(\n  surface: ShowcaseSurface,\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): readonly string[] {\n  return manifest\n    .filter(({ requirements }) => requirements.some((requirement) => requirement.surface === surface))\n    .map(({ storyId }) => storyId);\n}\n\n/** Compares a product Storybook inventory with the pinned contract package. */\nexport function compareShowcaseStoryIds(\n  surface: ShowcaseSurface,\n  storyIds: readonly string[],\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): ShowcaseStoryIdComparison {\n  const expected = getShowcaseStoryIdsForSurface(surface, manifest);\n  const expectedSet = new Set(expected);\n  const actual = [...new Set(storyIds)];\n  const counts = new Map<string, number>();\n  for (const storyId of storyIds) counts.set(storyId, (counts.get(storyId) ?? 0) + 1);\n  const missing = expected.filter((storyId) => !actual.includes(storyId));\n  const unexpected = actual.filter((storyId) => !expectedSet.has(storyId));\n  const duplicates = [...counts]\n    .filter(([, count]) => count > 1)\n    .map(([storyId]) => storyId)\n    .sort();\n  return {\n    surface,\n    expected,\n    actual,\n    missing,\n    unexpected,\n    duplicates,\n    complete: missing.length === 0 && unexpected.length === 0 && duplicates.length === 0,\n  };\n}\n\nexport function assertShowcaseStoryIds(\n  surface: ShowcaseSurface,\n  storyIds: readonly string[],\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): void {\n  const result = compareShowcaseStoryIds(surface, storyIds, manifest);\n  if (result.complete) return;\n  throw new Error(\n    [\n      `${surface} Storybook inventory does not match the design contract manifest.`,\n      `Missing: ${result.missing.join(\", \") || \"none\"}`,\n      `Unexpected: ${result.unexpected.join(\", \") || \"none\"}`,\n      `Duplicates: ${result.duplicates.join(\", \") || \"none\"}`,\n    ].join(\"\\n\"),\n  );\n}\n\n/** Runtime validation for evidence artifacts submitted by product repositories. */\nexport function defineDesignSystemEvidence(\n  input: DesignSystemEvidenceManifest,\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): DesignSystemEvidenceManifest {\n  if (input.schemaVersion !== designSystemEvidenceSchemaVersion) {\n    throw new Error(`Unsupported evidence schema version: ${input.schemaVersion}`);\n  }\n  requireNonEmptyString(input.designSystemVersion, \"designSystemVersion\");\n  if (input.designSystemVersion !== designSystemVersion) {\n    throw new Error(\n      `Evidence designSystemVersion ${input.designSystemVersion} does not match current ${designSystemVersion}`,\n    );\n  }\n  requireNonEmptyString(input.source.id, \"source.id\");\n  requireNonEmptyString(input.source.product, \"source.product\");\n  if (!surfaces.has(input.source.surface)) {\n    throw new Error(`Unknown evidence surface: ${input.source.surface}`);\n  }\n  if (!evidenceSourceKinds.has(input.source.kind)) {\n    throw new Error(`Unknown evidence source kind: ${input.source.kind}`);\n  }\n  if (input.source.revision !== undefined) requireNonEmptyString(input.source.revision, \"source.revision\");\n\n  const requirementsForSurface = new Map<string, ReadonlySet<ShowcaseScenarioId>>();\n  for (const item of manifest) {\n    const requirement = item.requirements.find(({ surface }) => surface === input.source.surface);\n    if (requirement) {\n      requirementsForSurface.set(item.storyId, new Set(requirement.scenarios));\n    }\n  }\n  const seen = new Set<string>();\n  for (const entry of input.entries) {\n    requireNonEmptyString(entry.storyId, \"entries[].storyId\");\n    const requiredScenarios = requirementsForSurface.get(entry.storyId);\n    if (!requiredScenarios) {\n      throw new Error(\n        `Evidence ${input.source.id} contains unsupported ${input.source.surface} story: ${entry.storyId}`,\n      );\n    }\n    if (seen.has(entry.storyId)) {\n      throw new Error(`Evidence ${input.source.id} contains duplicate story: ${entry.storyId}`);\n    }\n    seen.add(entry.storyId);\n    if (entry.scenarios.length === 0) {\n      throw new Error(`Evidence ${input.source.id}/${entry.storyId} must include at least one scenario`);\n    }\n    const entryScenarios = new Set<ShowcaseScenarioId>();\n    for (const scenario of entry.scenarios) {\n      if (!scenarioIds.has(scenario)) throw new Error(`Unknown evidence scenario: ${scenario}`);\n      if (!requiredScenarios.has(scenario)) {\n        throw new Error(\n          `Evidence ${input.source.id}/${entry.storyId} scenario ${scenario} is not required for ${input.source.surface}`,\n        );\n      }\n      if (entryScenarios.has(scenario)) {\n        throw new Error(`Evidence ${input.source.id}/${entry.storyId} repeats scenario: ${scenario}`);\n      }\n      entryScenarios.add(scenario);\n    }\n  }\n  return input;\n}\n\nexport function createDesignSystemEvidence(\n  source: DesignSystemEvidenceSource,\n  entries: readonly DesignSystemEvidenceItem[],\n): DesignSystemEvidenceManifest {\n  return defineDesignSystemEvidence({\n    schemaVersion: designSystemEvidenceSchemaVersion,\n    designSystemVersion,\n    source,\n    entries,\n  });\n}\n\nexport function toShowcaseEvidenceEntries(\n  evidence: readonly DesignSystemEvidenceManifest[],\n): readonly ShowcaseEvidenceEntry[] {\n  return evidence.flatMap(({ source, entries }) =>\n    entries.map(({ storyId, scenarios }) => ({ storyId, surface: source.surface, scenarios })),\n  );\n}\n\nexport function createDesignSystemEvidenceCoverage(\n  evidence: readonly DesignSystemEvidenceManifest[],\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): readonly ShowcaseCoverageEntry[] {\n  for (const item of evidence) defineDesignSystemEvidence(item, manifest);\n  return createShowcaseCoverage(toShowcaseEvidenceEntries(evidence), manifest);\n}\n"]}

package/dist/file-picker.d.ts

@@ -0,0 +1,183 @@
+export type FilePickerMode = "single" | "multiple";
+/**
+ * MIME pattern ("image/png", "image" + wildcard subtype, or wildcard/wildcard)
+ * or extension (".pdf"). Extensions exist because native pickers do not
+ * always resolve a MIME type.
+ */
+export type FilePickerAcceptPattern = string;
+export type FilePickerDescriptor = Readonly<{
+    mode?: FilePickerMode;
+    accept?: readonly FilePickerAcceptPattern[];
+    maxSizeBytes?: number;
+    /** Only meaningful when `mode` is `"multiple"` — single mode is always capped at one. */
+    maxCount?: number;
+}>;
+export type ResolvedFilePickerDescriptor = Readonly<{
+    mode: FilePickerMode;
+    accept?: readonly FilePickerAcceptPattern[];
+    maxSizeBytes?: number;
+    maxCount?: number;
+}>;
+export declare const filePickerDefaults: {
+    readonly mode: "single";
+};
+/** A file the platform picker or drop target produced, before FilePicker judges it. */
+export type FilePickerCandidate = Readonly<{
+    id: string;
+    name: string;
+    /** `""` when the platform could not resolve a MIME type. */
+    mimeType: string;
+    sizeBytes: number;
+}>;
+export type FilePickerRejectionReason = "unsupported-type" | "too-large" | "count-exceeded";
+export type FilePickerRejection = Readonly<{
+    file: FilePickerCandidate;
+    reason: "unsupported-type";
+    accept: readonly FilePickerAcceptPattern[];
+}> | Readonly<{
+    file: FilePickerCandidate;
+    reason: "too-large";
+    maxSizeBytes: number;
+}> | Readonly<{
+    file: FilePickerCandidate;
+    reason: "count-exceeded";
+    maxCount: number;
+}>;
+/**
+ * `accepted` and `rejected` are reported together on purpose: a rejection
+ * never has to be inferred by diffing two lists, and the rest of the batch
+ * staying selected is visible in the same result (identity.md's "what broke
+ * + what stayed fine").
+ */
+export type FilePickerSelectionResult = Readonly<{
+    accepted: readonly FilePickerCandidate[];
+    rejected: readonly FilePickerRejection[];
+}>;
+export declare function validateFilePickerDescriptor(descriptor: FilePickerDescriptor): void;
+export declare function resolveFilePickerDescriptor(descriptor: FilePickerDescriptor): ResolvedFilePickerDescriptor;
+export declare function validateFilePickerCandidate(candidate: FilePickerCandidate): void;
+/**
+ * `undefined`/empty `accept` means unrestricted. Exported so a Web renderer's
+ * live drag-over preview and the post-drop judgment share one rule.
+ */
+export declare function matchesFilePickerAccept(candidate: FilePickerCandidate, accept: readonly FilePickerAcceptPattern[] | undefined): boolean;
+/**
+ * Judges one selection batch against the descriptor. `existingCount` is a
+ * read-only input — like Select's `selectedItem` — for products that let
+ * users add files across repeated picks; FilePicker never accumulates a
+ * selection list itself.
+ */
+export declare function resolveFilePickerSelection(candidates: readonly FilePickerCandidate[], descriptor: FilePickerDescriptor, existingCount?: number): FilePickerSelectionResult;
+export type FilePickerTriggerPlatform = "web" | "native";
+export type FilePickerTrigger = "button" | "dropzone";
+/**
+ * Drag-and-drop is a Web-only enhancement. `validateFilePickerTriggers`
+ * enforces the roadmap's adaptive gate: Native never gets a dropzone, and no
+ * platform may ship a dropzone without an always-reachable button — the same
+ * "automatic mode keeps a manual fallback" principle as LoadMore
+ * (`src/load-more.ts`).
+ */
+export declare const filePickerTriggerDefaults: {
+    readonly web: readonly ["button", "dropzone"];
+    readonly native: readonly ["button"];
+};
+export declare function validateFilePickerTriggers(platform: FilePickerTriggerPlatform, triggers: readonly FilePickerTrigger[]): void;
+export type FilePickerDensity = "compact" | "regular";
+export declare const filePickerRecipe: {
+    readonly slots: readonly ["root", "trigger", "dropzone", "hint", "error"];
+    readonly defaults: {
+        readonly density: "regular";
+    };
+    readonly trigger: {
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 16;
+        readonly radius: "md";
+        readonly color: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly textVariant: "label";
+        readonly fontWeight: "700";
+    };
+    readonly dropzone: {
+        readonly borderStyle: "dashed";
+        readonly borderWidth: 1;
+        readonly borderColor: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly activeBorderColor: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly activeBackground: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly radius: "lg";
+        readonly padding: 24;
+    };
+    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 states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly disabledOpacity: 0.5;
+    };
+};
+/**
+ * No `open`/dismiss axis: the platform picker sheet is transient OS chrome
+ * FilePicker does not model, unlike Select/Sheet which own their surface.
+ */
+export declare const filePickerBehavior: {
+    readonly controlled: readonly [];
+    readonly inputs: readonly ["descriptor", "existingCount"];
+    readonly events: readonly ["onSelect"];
+    readonly configuration: {
+        readonly mode: readonly ["single", "multiple"];
+    };
+    readonly defaults: {
+        readonly mode: "single";
+    };
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled"];
+        readonly interaction: readonly ["idle", "hover", "focusVisible", "pressed", "dragged"];
+    };
+    readonly web: {
+        readonly roles: readonly ["button"];
+        readonly keyboard: readonly ["Tab", "Enter", "Space"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["button"];
+        readonly states: readonly ["disabled"];
+        readonly actions: readonly ["activate"];
+    };
+    readonly scenarios: readonly ["selecting-files-never-mutates-already-accepted-items", "rejected-files-report-a-reason-without-blocking-the-rest-of-the-batch", "type-and-size-are-judged-at-selection-time-not-upload-time", "count-cap-accounts-for-already-selected-items-across-repeated-picks", "single-mode-behaves-as-an-implicit-one-file-count-cap", "web-dropzone-is-always-paired-with-a-reachable-button-trigger", "native-never-exposes-a-dropzone-trigger", "rejection-is-announced-without-relying-on-color-alone"];
+};
+//# sourceMappingURL=file-picker.d.ts.map

package/dist/file-picker.d.ts.map

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

package/dist/file-picker.js

@@ -0,0 +1,224 @@
+import { focusIndicatorContract } from "./component-contracts.js";
+import { control, fontWeight, opacity, radius, spacing, stroke, } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const filePickerDefaults = {
+    mode: "single",
+};
+const ACCEPT_PATTERN = /^(\*\/\*|[a-z0-9.+-]+\/(?:\*|[a-z0-9.+-]+)|\.[a-z0-9]+)$/i;
+function assertNonEmpty(value, field) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`FilePicker ${field} must not be empty`);
+    }
+}
+export function validateFilePickerDescriptor(descriptor) {
+    const mode = descriptor.mode ?? filePickerDefaults.mode;
+    if (mode !== "single" && mode !== "multiple") {
+        throw new TypeError(`Unsupported FilePicker mode: ${String(mode)}`);
+    }
+    if (descriptor.accept !== undefined) {
+        if (descriptor.accept.length === 0) {
+            throw new TypeError("FilePicker accept must not be empty when provided");
+        }
+        const seen = new Set();
+        for (const pattern of descriptor.accept) {
+            if (!ACCEPT_PATTERN.test(pattern)) {
+                throw new TypeError(`Unsupported FilePicker accept pattern: ${pattern}`);
+            }
+            const normalized = pattern.toLowerCase();
+            if (seen.has(normalized)) {
+                throw new TypeError(`Duplicate FilePicker accept pattern: ${pattern}`);
+            }
+            seen.add(normalized);
+        }
+    }
+    if (descriptor.maxSizeBytes !== undefined) {
+        if (!Number.isFinite(descriptor.maxSizeBytes) || descriptor.maxSizeBytes <= 0) {
+            throw new RangeError("FilePicker maxSizeBytes must be a positive finite number");
+        }
+    }
+    if (descriptor.maxCount !== undefined) {
+        if (mode !== "multiple") {
+            throw new TypeError("FilePicker maxCount only applies when mode is \"multiple\"");
+        }
+        if (!Number.isInteger(descriptor.maxCount) || descriptor.maxCount < 1) {
+            throw new RangeError("FilePicker maxCount must be a positive integer");
+        }
+    }
+}
+export function resolveFilePickerDescriptor(descriptor) {
+    validateFilePickerDescriptor(descriptor);
+    return { ...descriptor, mode: descriptor.mode ?? filePickerDefaults.mode };
+}
+export function validateFilePickerCandidate(candidate) {
+    assertNonEmpty(candidate.id, "candidate id");
+    assertNonEmpty(candidate.name, "candidate name");
+    if (typeof candidate.mimeType !== "string") {
+        throw new TypeError('FilePicker candidate mimeType must be a string (use "" when unknown)');
+    }
+    if (!Number.isFinite(candidate.sizeBytes) || candidate.sizeBytes < 0) {
+        throw new RangeError("FilePicker candidate sizeBytes must be a non-negative finite number");
+    }
+}
+/** Splits `"type/subtype"` into a fixed-length tuple so both sides are always `string`. */
+function splitOnSlash(value) {
+    const slash = value.indexOf("/");
+    if (slash === -1)
+        return [value, ""];
+    return [value.slice(0, slash), value.slice(slash + 1)];
+}
+function fileExtension(name) {
+    const dot = name.lastIndexOf(".");
+    return dot === -1 ? "" : name.slice(dot).toLowerCase();
+}
+function matchesPattern(candidate, pattern) {
+    if (pattern.startsWith(".")) {
+        return fileExtension(candidate.name) === pattern.toLowerCase();
+    }
+    if (pattern === "*/*")
+        return true;
+    if (!candidate.mimeType)
+        return false;
+    const [patternType, patternSubtype] = splitOnSlash(pattern.toLowerCase());
+    const [fileType, fileSubtype] = splitOnSlash(candidate.mimeType.toLowerCase());
+    if (patternType !== "*" && patternType !== fileType)
+        return false;
+    return patternSubtype === "*" || patternSubtype === fileSubtype;
+}
+/**
+ * `undefined`/empty `accept` means unrestricted. Exported so a Web renderer's
+ * live drag-over preview and the post-drop judgment share one rule.
+ */
+export function matchesFilePickerAccept(candidate, accept) {
+    if (accept === undefined || accept.length === 0)
+        return true;
+    return accept.some((pattern) => matchesPattern(candidate, pattern));
+}
+/**
+ * Judges one selection batch against the descriptor. `existingCount` is a
+ * read-only input — like Select's `selectedItem` — for products that let
+ * users add files across repeated picks; FilePicker never accumulates a
+ * selection list itself.
+ */
+export function resolveFilePickerSelection(candidates, descriptor, existingCount = 0) {
+    const resolved = resolveFilePickerDescriptor(descriptor);
+    for (const candidate of candidates)
+        validateFilePickerCandidate(candidate);
+    if (!Number.isInteger(existingCount) || existingCount < 0) {
+        throw new RangeError("FilePicker existingCount must be a non-negative integer");
+    }
+    const accepted = [];
+    const rejected = [];
+    for (const candidate of candidates) {
+        if (!matchesFilePickerAccept(candidate, resolved.accept)) {
+            rejected.push({ file: candidate, reason: "unsupported-type", accept: resolved.accept ?? [] });
+            continue;
+        }
+        if (resolved.maxSizeBytes !== undefined && candidate.sizeBytes > resolved.maxSizeBytes) {
+            rejected.push({ file: candidate, reason: "too-large", maxSizeBytes: resolved.maxSizeBytes });
+            continue;
+        }
+        accepted.push(candidate);
+    }
+    const effectiveMaxCount = resolved.mode === "single" ? 1 : resolved.maxCount;
+    if (effectiveMaxCount !== undefined) {
+        const room = Math.max(0, effectiveMaxCount - existingCount);
+        if (accepted.length > room) {
+            const overflow = accepted.splice(room);
+            for (const candidate of overflow) {
+                rejected.push({ file: candidate, reason: "count-exceeded", maxCount: effectiveMaxCount });
+            }
+        }
+    }
+    return { accepted, rejected };
+}
+/**
+ * Drag-and-drop is a Web-only enhancement. `validateFilePickerTriggers`
+ * enforces the roadmap's adaptive gate: Native never gets a dropzone, and no
+ * platform may ship a dropzone without an always-reachable button — the same
+ * "automatic mode keeps a manual fallback" principle as LoadMore
+ * (`src/load-more.ts`).
+ */
+export const filePickerTriggerDefaults = {
+    web: ["button", "dropzone"],
+    native: ["button"],
+};
+export function validateFilePickerTriggers(platform, triggers) {
+    if (triggers.length === 0) {
+        throw new TypeError("FilePicker triggers must not be empty");
+    }
+    if (!triggers.includes("button")) {
+        throw new TypeError("FilePicker must always expose a button trigger, even with a dropzone");
+    }
+    if (platform === "native" && triggers.includes("dropzone")) {
+        throw new TypeError("FilePicker dropzone trigger is a Web-only enhancement");
+    }
+}
+export const filePickerRecipe = {
+    slots: ["root", "trigger", "dropzone", "hint", "error"],
+    defaults: { density: "regular" },
+    trigger: {
+        minHeight: control.minTouchTarget,
+        paddingHorizontal: spacing.md,
+        radius: "md",
+        color: semanticColors.content.brand,
+        textVariant: "label",
+        fontWeight: fontWeight.bold,
+    },
+    dropzone: {
+        borderStyle: "dashed",
+        borderWidth: stroke.default,
+        borderColor: semanticColors.border.default,
+        activeBorderColor: semanticColors.border.focus,
+        activeBackground: semanticColors.interaction.focus,
+        radius: "lg",
+        padding: spacing.xl,
+    },
+    hint: {
+        color: semanticColors.content.secondary,
+        textVariant: "label",
+    },
+    error: {
+        color: semanticColors.content.danger,
+        textVariant: "label",
+    },
+    states: {
+        focus: focusIndicatorContract,
+        disabledOpacity: opacity.disabled,
+    },
+};
+/**
+ * No `open`/dismiss axis: the platform picker sheet is transient OS chrome
+ * FilePicker does not model, unlike Select/Sheet which own their surface.
+ */
+export const filePickerBehavior = {
+    controlled: [],
+    inputs: ["descriptor", "existingCount"],
+    events: ["onSelect"],
+    configuration: { mode: ["single", "multiple"] },
+    defaults: filePickerDefaults,
+    stateAxes: {
+        availability: ["enabled", "disabled"],
+        interaction: ["idle", "hover", "focusVisible", "pressed", "dragged"],
+    },
+    web: {
+        roles: ["button"],
+        keyboard: ["Tab", "Enter", "Space"],
+        focus: "native",
+    },
+    native: {
+        roles: ["button"],
+        states: ["disabled"],
+        actions: ["activate"],
+    },
+    scenarios: [
+        "selecting-files-never-mutates-already-accepted-items",
+        "rejected-files-report-a-reason-without-blocking-the-rest-of-the-batch",
+        "type-and-size-are-judged-at-selection-time-not-upload-time",
+        "count-cap-accounts-for-already-selected-items-across-repeated-picks",
+        "single-mode-behaves-as-an-implicit-one-file-count-cap",
+        "web-dropzone-is-always-paired-with-a-reachable-button-trigger",
+        "native-never-exposes-a-dropzone-trigger",
+        "rejection-is-announced-without-relying-on-color-alone",
+    ],
+};
+//# sourceMappingURL=file-picker.js.map

package/dist/file-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-picker.js","sourceRoot":"","sources":["../src/file-picker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,EACL,OAAO,EACP,UAAU,EACV,OAAO,EACP,MAAM,EACN,OAAO,EACP,MAAM,GAGP,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AA0BtD,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,IAAI,EAAE,QAAQ;CACuC,CAAC;AA6BxD,MAAM,cAAc,GAAG,2DAA2D,CAAC;AAEnF,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa;IAClD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,SAAS,CAAC,cAAc,KAAK,oBAAoB,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,UAAgC;IAC3E,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,IAAI,kBAAkB,CAAC,IAAI,CAAC;IACxD,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAC7C,MAAM,IAAI,SAAS,CAAC,gCAAgC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,UAAU,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACpC,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAC;QAC3E,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,KAAK,MAAM,OAAO,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;YACxC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,SAAS,CAAC,0CAA0C,OAAO,EAAE,CAAC,CAAC;YAC3E,CAAC;YACD,MAAM,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YACzC,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBACzB,MAAM,IAAI,SAAS,CAAC,wCAAwC,OAAO,EAAE,CAAC,CAAC;YACzE,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,IAAI,UAAU,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,UAAU,CAAC,YAAY,IAAI,CAAC,EAAE,CAAC;YAC9E,MAAM,IAAI,UAAU,CAAC,0DAA0D,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACtC,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;YACxB,MAAM,IAAI,SAAS,CAAC,4DAA4D,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;YACtE,MAAM,IAAI,UAAU,CAAC,gDAAgD,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,UAAgC;IAEhC,4BAA4B,CAAC,UAAU,CAAC,CAAC;IACzC,OAAO,EAAE,GAAG,UAAU,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,kBAAkB,CAAC,IAAI,EAAE,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,SAA8B;IACxE,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;IAC7C,cAAc,CAAC,SAAS,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IACjD,IAAI,OAAO,SAAS,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC3C,MAAM,IAAI,SAAS,CAAC,sEAAsE,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,SAAS,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,UAAU,CAAC,qEAAqE,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC;AAED,2FAA2F;AAC3F,SAAS,YAAY,CAAC,KAAa;IACjC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,CAAC,CAAC;QAAE,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;AACzD,CAAC;AAED,SAAS,cAAc,CAAC,SAA8B,EAAE,OAAe;IACrE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,WAAW,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IACnC,IAAI,CAAC,SAAS,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtC,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1E,MAAM,CAAC,QAAQ,EAAE,WAAW,CAAC,GAAG,YAAY,CAAC,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/E,IAAI,WAAW,KAAK,GAAG,IAAI,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClE,OAAO,cAAc,KAAK,GAAG,IAAI,cAAc,KAAK,WAAW,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAA8B,EAC9B,MAAsD;IAEtD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7D,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;AACtE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CACxC,UAA0C,EAC1C,UAAgC,EAChC,aAAa,GAAG,CAAC;IAEjB,MAAM,QAAQ,GAAG,2BAA2B,CAAC,UAAU,CAAC,CAAC;IACzD,KAAK,MAAM,SAAS,IAAI,UAAU;QAAE,2BAA2B,CAAC,SAAS,CAAC,CAAC;IAC3E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,UAAU,CAAC,yDAAyD,CAAC,CAAC;IAClF,CAAC;IAED,MAAM,QAAQ,GAA0B,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAA0B,EAAE,CAAC;IAE3C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC,uBAAuB,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,CAAC;YAC9F,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS,IAAI,SAAS,CAAC,SAAS,GAAG,QAAQ,CAAC,YAAY,EAAE,CAAC;YACvF,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,EAAE,CAAC,CAAC;YAC7F,SAAS;QACX,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,iBAAiB,GAAG,QAAQ,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAC7E,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAAC,CAAC;QAC5D,IAAI,QAAQ,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACvC,KAAK,MAAM,SAAS,IAAI,QAAQ,EAAE,CAAC;gBACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC;YAC5F,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC;AAKD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,GAAG,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC3B,MAAM,EAAE,CAAC,QAAQ,CAAC;CACgE,CAAC;AAErF,MAAM,UAAU,0BAA0B,CACxC,QAAmC,EACnC,QAAsC;IAEtC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,SAAS,CAAC,sEAAsE,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,SAAS,CAAC,uDAAuD,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAID,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,KAAK,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAU;IAChE,QAAQ,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE;IAChC,OAAO,EAAE;QACP,SAAS,EAAE,OAAO,CAAC,cAAc;QACjC,iBAAiB,EAAE,OAAO,CAAC,EAAE;QAC7B,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK;QACnC,WAAW,EAAE,OAAO;QACpB,UAAU,EAAE,UAAU,CAAC,IAAI;KAC5B;IACD,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ;QACrB,WAAW,EAAE,MAAM,CAAC,OAAO;QAC3B,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO;QAC1C,iBAAiB,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK;QAC9C,gBAAgB,EAAE,cAAc,CAAC,WAAW,CAAC,KAAK;QAClD,MAAM,EAAE,IAAI;QACZ,OAAO,EAAE,OAAO,CAAC,EAAE;KACpB;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,SAAS;QACvC,WAAW,EAAE,OAAO;KACrB;IACD,KAAK,EAAE;QACL,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,MAAM;QACpC,WAAW,EAAE,OAAO;KACrB;IACD,MAAM,EAAE;QACN,KAAK,EAAE,sBAAsB;QAC7B,eAAe,EAAE,OAAO,CAAC,QAAQ;KAClC;CAwBF,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;IAChC,UAAU,EAAE,EAAE;IACd,MAAM,EAAE,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,MAAM,EAAE,CAAC,UAAU,CAAC;IACpB,aAAa,EAAE,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE;IAC/C,QAAQ,EAAE,kBAAkB;IAC5B,SAAS,EAAE;QACT,YAAY,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;QACrC,WAAW,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,CAAC;KACrE;IACD,GAAG,EAAE;QACH,KAAK,EAAE,CAAC,QAAQ,CAAC;QACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC;QACnC,KAAK,EAAE,QAAQ;KAChB;IACD,MAAM,EAAE;QACN,KAAK,EAAE,CAAC,QAAQ,CAAC;QACjB,MAAM,EAAE,CAAC,UAAU,CAAC;QACpB,OAAO,EAAE,CAAC,UAAU,CAAC;KACtB;IACD,SAAS,EAAE;QACT,sDAAsD;QACtD,uEAAuE;QACvE,4DAA4D;QAC5D,qEAAqE;QACrE,uDAAuD;QACvD,+DAA+D;QAC/D,yCAAyC;QACzC,uDAAuD;KACxD;CACkC,CAAC","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { BehaviorContract } from \"./behaviors.js\";\nimport { focusIndicatorContract } from \"./component-contracts.js\";\nimport {\n  control,\n  fontWeight,\n  opacity,\n  radius,\n  spacing,\n  stroke,\n  type FontWeightValue,\n  type TextVariant,\n} from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\nexport type FilePickerMode = \"single\" | \"multiple\";\n\n/**\n * MIME pattern (\"image/png\", \"image\" + wildcard subtype, or wildcard/wildcard)\n * or extension (\".pdf\"). Extensions exist because native pickers do not\n * always resolve a MIME type.\n */\nexport type FilePickerAcceptPattern = string;\n\nexport type FilePickerDescriptor = Readonly<{\n  mode?: FilePickerMode;\n  accept?: readonly FilePickerAcceptPattern[];\n  maxSizeBytes?: number;\n  /** Only meaningful when `mode` is `\"multiple\"` — single mode is always capped at one. */\n  maxCount?: number;\n}>;\n\nexport type ResolvedFilePickerDescriptor = Readonly<{\n  mode: FilePickerMode;\n  accept?: readonly FilePickerAcceptPattern[];\n  maxSizeBytes?: number;\n  maxCount?: number;\n}>;\n\nexport const filePickerDefaults = {\n  mode: \"single\",\n} as const satisfies Readonly<{ mode: FilePickerMode }>;\n\n/** A file the platform picker or drop target produced, before FilePicker judges it. */\nexport type FilePickerCandidate = Readonly<{\n  id: string;\n  name: string;\n  /** `\"\"` when the platform could not resolve a MIME type. */\n  mimeType: string;\n  sizeBytes: number;\n}>;\n\nexport type FilePickerRejectionReason = \"unsupported-type\" | \"too-large\" | \"count-exceeded\";\n\nexport type FilePickerRejection =\n  | Readonly<{ file: FilePickerCandidate; reason: \"unsupported-type\"; accept: readonly FilePickerAcceptPattern[] }>\n  | Readonly<{ file: FilePickerCandidate; reason: \"too-large\"; maxSizeBytes: number }>\n  | Readonly<{ file: FilePickerCandidate; reason: \"count-exceeded\"; maxCount: number }>;\n\n/**\n * `accepted` and `rejected` are reported together on purpose: a rejection\n * never has to be inferred by diffing two lists, and the rest of the batch\n * staying selected is visible in the same result (identity.md's \"what broke\n * + what stayed fine\").\n */\nexport type FilePickerSelectionResult = Readonly<{\n  accepted: readonly FilePickerCandidate[];\n  rejected: readonly FilePickerRejection[];\n}>;\n\nconst ACCEPT_PATTERN = /^(\\*\\/\\*|[a-z0-9.+-]+\\/(?:\\*|[a-z0-9.+-]+)|\\.[a-z0-9]+)$/i;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (typeof value !== \"string\" || value.trim().length === 0) {\n    throw new TypeError(`FilePicker ${field} must not be empty`);\n  }\n}\n\nexport function validateFilePickerDescriptor(descriptor: FilePickerDescriptor): void {\n  const mode = descriptor.mode ?? filePickerDefaults.mode;\n  if (mode !== \"single\" && mode !== \"multiple\") {\n    throw new TypeError(`Unsupported FilePicker mode: ${String(mode)}`);\n  }\n  if (descriptor.accept !== undefined) {\n    if (descriptor.accept.length === 0) {\n      throw new TypeError(\"FilePicker accept must not be empty when provided\");\n    }\n    const seen = new Set<string>();\n    for (const pattern of descriptor.accept) {\n      if (!ACCEPT_PATTERN.test(pattern)) {\n        throw new TypeError(`Unsupported FilePicker accept pattern: ${pattern}`);\n      }\n      const normalized = pattern.toLowerCase();\n      if (seen.has(normalized)) {\n        throw new TypeError(`Duplicate FilePicker accept pattern: ${pattern}`);\n      }\n      seen.add(normalized);\n    }\n  }\n  if (descriptor.maxSizeBytes !== undefined) {\n    if (!Number.isFinite(descriptor.maxSizeBytes) || descriptor.maxSizeBytes <= 0) {\n      throw new RangeError(\"FilePicker maxSizeBytes must be a positive finite number\");\n    }\n  }\n  if (descriptor.maxCount !== undefined) {\n    if (mode !== \"multiple\") {\n      throw new TypeError(\"FilePicker maxCount only applies when mode is \\\"multiple\\\"\");\n    }\n    if (!Number.isInteger(descriptor.maxCount) || descriptor.maxCount < 1) {\n      throw new RangeError(\"FilePicker maxCount must be a positive integer\");\n    }\n  }\n}\n\nexport function resolveFilePickerDescriptor(\n  descriptor: FilePickerDescriptor,\n): ResolvedFilePickerDescriptor {\n  validateFilePickerDescriptor(descriptor);\n  return { ...descriptor, mode: descriptor.mode ?? filePickerDefaults.mode };\n}\n\nexport function validateFilePickerCandidate(candidate: FilePickerCandidate): void {\n  assertNonEmpty(candidate.id, \"candidate id\");\n  assertNonEmpty(candidate.name, \"candidate name\");\n  if (typeof candidate.mimeType !== \"string\") {\n    throw new TypeError('FilePicker candidate mimeType must be a string (use \"\" when unknown)');\n  }\n  if (!Number.isFinite(candidate.sizeBytes) || candidate.sizeBytes < 0) {\n    throw new RangeError(\"FilePicker candidate sizeBytes must be a non-negative finite number\");\n  }\n}\n\n/** Splits `\"type/subtype\"` into a fixed-length tuple so both sides are always `string`. */\nfunction splitOnSlash(value: string): readonly [string, string] {\n  const slash = value.indexOf(\"/\");\n  if (slash === -1) return [value, \"\"];\n  return [value.slice(0, slash), value.slice(slash + 1)];\n}\n\nfunction fileExtension(name: string): string {\n  const dot = name.lastIndexOf(\".\");\n  return dot === -1 ? \"\" : name.slice(dot).toLowerCase();\n}\n\nfunction matchesPattern(candidate: FilePickerCandidate, pattern: string): boolean {\n  if (pattern.startsWith(\".\")) {\n    return fileExtension(candidate.name) === pattern.toLowerCase();\n  }\n  if (pattern === \"*/*\") return true;\n  if (!candidate.mimeType) return false;\n  const [patternType, patternSubtype] = splitOnSlash(pattern.toLowerCase());\n  const [fileType, fileSubtype] = splitOnSlash(candidate.mimeType.toLowerCase());\n  if (patternType !== \"*\" && patternType !== fileType) return false;\n  return patternSubtype === \"*\" || patternSubtype === fileSubtype;\n}\n\n/**\n * `undefined`/empty `accept` means unrestricted. Exported so a Web renderer's\n * live drag-over preview and the post-drop judgment share one rule.\n */\nexport function matchesFilePickerAccept(\n  candidate: FilePickerCandidate,\n  accept: readonly FilePickerAcceptPattern[] | undefined,\n): boolean {\n  if (accept === undefined || accept.length === 0) return true;\n  return accept.some((pattern) => matchesPattern(candidate, pattern));\n}\n\n/**\n * Judges one selection batch against the descriptor. `existingCount` is a\n * read-only input — like Select's `selectedItem` — for products that let\n * users add files across repeated picks; FilePicker never accumulates a\n * selection list itself.\n */\nexport function resolveFilePickerSelection(\n  candidates: readonly FilePickerCandidate[],\n  descriptor: FilePickerDescriptor,\n  existingCount = 0,\n): FilePickerSelectionResult {\n  const resolved = resolveFilePickerDescriptor(descriptor);\n  for (const candidate of candidates) validateFilePickerCandidate(candidate);\n  if (!Number.isInteger(existingCount) || existingCount < 0) {\n    throw new RangeError(\"FilePicker existingCount must be a non-negative integer\");\n  }\n\n  const accepted: FilePickerCandidate[] = [];\n  const rejected: FilePickerRejection[] = [];\n\n  for (const candidate of candidates) {\n    if (!matchesFilePickerAccept(candidate, resolved.accept)) {\n      rejected.push({ file: candidate, reason: \"unsupported-type\", accept: resolved.accept ?? [] });\n      continue;\n    }\n    if (resolved.maxSizeBytes !== undefined && candidate.sizeBytes > resolved.maxSizeBytes) {\n      rejected.push({ file: candidate, reason: \"too-large\", maxSizeBytes: resolved.maxSizeBytes });\n      continue;\n    }\n    accepted.push(candidate);\n  }\n\n  const effectiveMaxCount = resolved.mode === \"single\" ? 1 : resolved.maxCount;\n  if (effectiveMaxCount !== undefined) {\n    const room = Math.max(0, effectiveMaxCount - existingCount);\n    if (accepted.length > room) {\n      const overflow = accepted.splice(room);\n      for (const candidate of overflow) {\n        rejected.push({ file: candidate, reason: \"count-exceeded\", maxCount: effectiveMaxCount });\n      }\n    }\n  }\n\n  return { accepted, rejected };\n}\n\nexport type FilePickerTriggerPlatform = \"web\" | \"native\";\nexport type FilePickerTrigger = \"button\" | \"dropzone\";\n\n/**\n * Drag-and-drop is a Web-only enhancement. `validateFilePickerTriggers`\n * enforces the roadmap's adaptive gate: Native never gets a dropzone, and no\n * platform may ship a dropzone without an always-reachable button — the same\n * \"automatic mode keeps a manual fallback\" principle as LoadMore\n * (`src/load-more.ts`).\n */\nexport const filePickerTriggerDefaults = {\n  web: [\"button\", \"dropzone\"],\n  native: [\"button\"],\n} as const satisfies Record<FilePickerTriggerPlatform, readonly FilePickerTrigger[]>;\n\nexport function validateFilePickerTriggers(\n  platform: FilePickerTriggerPlatform,\n  triggers: readonly FilePickerTrigger[],\n): void {\n  if (triggers.length === 0) {\n    throw new TypeError(\"FilePicker triggers must not be empty\");\n  }\n  if (!triggers.includes(\"button\")) {\n    throw new TypeError(\"FilePicker must always expose a button trigger, even with a dropzone\");\n  }\n  if (platform === \"native\" && triggers.includes(\"dropzone\")) {\n    throw new TypeError(\"FilePicker dropzone trigger is a Web-only enhancement\");\n  }\n}\n\nexport type FilePickerDensity = \"compact\" | \"regular\";\n\nexport const filePickerRecipe = {\n  slots: [\"root\", \"trigger\", \"dropzone\", \"hint\", \"error\"] as const,\n  defaults: { density: \"regular\" },\n  trigger: {\n    minHeight: control.minTouchTarget,\n    paddingHorizontal: spacing.md,\n    radius: \"md\",\n    color: semanticColors.content.brand,\n    textVariant: \"label\",\n    fontWeight: fontWeight.bold,\n  },\n  dropzone: {\n    borderStyle: \"dashed\",\n    borderWidth: stroke.default,\n    borderColor: semanticColors.border.default,\n    activeBorderColor: semanticColors.border.focus,\n    activeBackground: semanticColors.interaction.focus,\n    radius: \"lg\",\n    padding: spacing.xl,\n  },\n  hint: {\n    color: semanticColors.content.secondary,\n    textVariant: \"label\",\n  },\n  error: {\n    color: semanticColors.content.danger,\n    textVariant: \"label\",\n  },\n  states: {\n    focus: focusIndicatorContract,\n    disabledOpacity: opacity.disabled,\n  },\n} as const satisfies {\n  slots: readonly [\"root\", \"trigger\", \"dropzone\", \"hint\", \"error\"];\n  defaults: { density: FilePickerDensity };\n  trigger: {\n    minHeight: number;\n    paddingHorizontal: number;\n    radius: keyof typeof radius;\n    color: ColorReference;\n    textVariant: TextVariant;\n    fontWeight: FontWeightValue;\n  };\n  dropzone: {\n    borderStyle: \"dashed\";\n    borderWidth: number;\n    borderColor: ColorReference;\n    activeBorderColor: ColorReference;\n    activeBackground: ColorReference;\n    radius: keyof typeof radius;\n    padding: number;\n  };\n  hint: { color: ColorReference; textVariant: TextVariant };\n  error: { color: ColorReference; textVariant: TextVariant };\n  states: { focus: typeof focusIndicatorContract; disabledOpacity: number };\n};\n\n/**\n * No `open`/dismiss axis: the platform picker sheet is transient OS chrome\n * FilePicker does not model, unlike Select/Sheet which own their surface.\n */\nexport const filePickerBehavior = {\n  controlled: [],\n  inputs: [\"descriptor\", \"existingCount\"],\n  events: [\"onSelect\"],\n  configuration: { mode: [\"single\", \"multiple\"] },\n  defaults: filePickerDefaults,\n  stateAxes: {\n    availability: [\"enabled\", \"disabled\"],\n    interaction: [\"idle\", \"hover\", \"focusVisible\", \"pressed\", \"dragged\"],\n  },\n  web: {\n    roles: [\"button\"],\n    keyboard: [\"Tab\", \"Enter\", \"Space\"],\n    focus: \"native\",\n  },\n  native: {\n    roles: [\"button\"],\n    states: [\"disabled\"],\n    actions: [\"activate\"],\n  },\n  scenarios: [\n    \"selecting-files-never-mutates-already-accepted-items\",\n    \"rejected-files-report-a-reason-without-blocking-the-rest-of-the-batch\",\n    \"type-and-size-are-judged-at-selection-time-not-upload-time\",\n    \"count-cap-accounts-for-already-selected-items-across-repeated-picks\",\n    \"single-mode-behaves-as-an-implicit-one-file-count-cap\",\n    \"web-dropzone-is-always-paired-with-a-reachable-button-trigger\",\n    \"native-never-exposes-a-dropzone-trigger\",\n    \"rejection-is-announced-without-relying-on-color-alone\",\n  ],\n} as const satisfies BehaviorContract;\n"]}