@hjmds/design-contracts 0.8.2

package/dist/showcase.js

@@ -0,0 +1,210 @@
+import { componentCatalog, getComponentSurfaceStatus, } from "./catalog.js";
+/**
+ * A small, deliberate environment matrix catches the high-risk differences
+ * without multiplying every story into an unreadable Cartesian product.
+ */
+export const showcaseEnvironmentMatrix = [
+    {
+        id: "default",
+        label: "Light · LTR · 100%",
+        theme: "light",
+        direction: "ltr",
+        textScale: 1,
+        motion: "full",
+    },
+    {
+        id: "dark",
+        label: "Dark · LTR · 100%",
+        theme: "dark",
+        direction: "ltr",
+        textScale: 1,
+        motion: "full",
+    },
+    {
+        id: "large-text",
+        label: "Light · LTR · 200%",
+        theme: "light",
+        direction: "ltr",
+        textScale: 2,
+        motion: "full",
+    },
+    {
+        id: "rtl",
+        label: "Light · RTL · 100%",
+        theme: "light",
+        direction: "rtl",
+        textScale: 1,
+        motion: "full",
+    },
+    {
+        id: "reduced-motion",
+        label: "Light · LTR · Reduced motion",
+        theme: "light",
+        direction: "ltr",
+        textScale: 1,
+        motion: "reduced",
+    },
+];
+/** Bridges documentation fixtures to the same environment contract products consume. */
+export function getShowcaseEnvironmentInput(environment) {
+    const textScale = environment.textScale;
+    return {
+        theme: environment.theme,
+        direction: environment.direction,
+        textScale,
+        reducedMotion: environment.motion === "reduced",
+    };
+}
+export const showcaseScenarios = [
+    {
+        id: "contract",
+        label: "Contract",
+        description: "Anatomy, defaults, supported axes, platform and maturity are visible.",
+    },
+    {
+        id: "default",
+        label: "Default",
+        description: "The normal state renders using recipe defaults without product overrides.",
+    },
+    {
+        id: "dark",
+        label: "Dark",
+        description: "Semantic colors remain legible on the dark theme.",
+    },
+    {
+        id: "long-copy",
+        label: "Long copy",
+        description: "Long Korean and English copy wraps without clipping or hiding meaning.",
+    },
+    {
+        id: "large-text",
+        label: "200% text",
+        description: "Text can grow to 200% without truncating required information.",
+    },
+    {
+        id: "rtl",
+        label: "RTL",
+        description: "Logical start/end layout and directional icons mirror correctly.",
+    },
+    {
+        id: "reduced-motion",
+        label: "Reduced motion",
+        description: "Motion follows the recipe reduced-motion fallback.",
+    },
+    {
+        id: "accessibility",
+        label: "Accessibility",
+        description: "Names, states, relationships, contrast and touch targets are inspectable.",
+    },
+    {
+        id: "keyboard",
+        label: "Keyboard",
+        description: "Focus order and documented keyboard behavior run as interaction tests.",
+    },
+    {
+        id: "platform-parity",
+        label: "Web / Native parity",
+        description: "Adaptive renderers preserve intent while using platform-native behavior.",
+    },
+];
+const plannedRequirements = ["contract"];
+const rendererRequirements = [
+    "default",
+    "dark",
+    "long-copy",
+    "large-text",
+    "rtl",
+    "reduced-motion",
+    "accessibility",
+];
+export function getShowcaseStoryId(entry) {
+    const slug = entry.name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .replace(/[^a-zA-Z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase();
+    return `${entry.category}/${slug}`;
+}
+export function getRequiredShowcaseScenarios(entry) {
+    const activeSurfaces = ["web", "native"].filter((surface) => isRendererMaturity(getComponentSurfaceStatus(entry, surface)));
+    if (activeSurfaces.length === 0)
+        return plannedRequirements;
+    return ["contract", ...getRendererShowcaseScenarios(entry, activeSurfaces)];
+}
+function isRendererMaturity(status) {
+    return status === "stable" || status === "beta";
+}
+function getRendererShowcaseScenarios(entry, activeSurfaces) {
+    const requirements = [...rendererRequirements];
+    if (entry.behavior) {
+        requirements.push("keyboard");
+    }
+    if (entry.platform === "adaptive" &&
+        activeSurfaces.includes("web") &&
+        activeSurfaces.includes("native")) {
+        requirements.push("platform-parity");
+    }
+    return requirements;
+}
+export function getRequiredShowcaseSurfaces(entry) {
+    return getRequiredShowcaseEvidence(entry).map(({ surface }) => surface);
+}
+export function getRequiredShowcaseEvidence(entry) {
+    const requirements = [
+        { surface: "contract", scenarios: ["contract"] },
+    ];
+    const activeSurfaces = ["web", "native"].filter((surface) => isRendererMaturity(getComponentSurfaceStatus(entry, surface)));
+    const rendererScenarios = getRendererShowcaseScenarios(entry, activeSurfaces);
+    for (const surface of activeSurfaces) {
+        requirements.push({ surface, scenarios: rendererScenarios });
+    }
+    return requirements;
+}
+export function createShowcaseManifest(entries = componentCatalog) {
+    return entries.map((component) => ({
+        storyId: getShowcaseStoryId(component),
+        component,
+        surfaceMaturity: {
+            web: getComponentSurfaceStatus(component, "web"),
+            native: getComponentSurfaceStatus(component, "native"),
+        },
+        requirements: getRequiredShowcaseEvidence(component),
+        requiredScenarios: getRequiredShowcaseScenarios(component),
+        requiredSurfaces: getRequiredShowcaseSurfaces(component),
+    }));
+}
+export const showcaseManifest = createShowcaseManifest();
+export function createShowcaseCoverage(evidence, manifest = showcaseManifest) {
+    return manifest.map(({ storyId, component, requirements }) => {
+        const componentEvidence = evidence.filter((entry) => entry.storyId === storyId);
+        const missingEvidence = requirements.flatMap(({ surface, scenarios }) => scenarios
+            .filter((scenario) => !componentEvidence.some((entry) => entry.surface === surface && entry.scenarios.includes(scenario)))
+            .map((scenario) => ({ surface, scenario })));
+        const missingSurfaces = [...new Set(missingEvidence.map(({ surface }) => surface))];
+        const missingScenarios = [...new Set(missingEvidence.map(({ scenario }) => scenario))];
+        return {
+            storyId,
+            component,
+            missingEvidence,
+            missingSurfaces,
+            missingScenarios,
+            complete: missingSurfaces.length === 0 && missingScenarios.length === 0,
+        };
+    });
+}
+export function assertShowcaseCoverage(evidence, manifest = showcaseManifest) {
+    const missing = createShowcaseCoverage(evidence, manifest).filter(({ complete }) => !complete);
+    if (missing.length === 0)
+        return;
+    const details = missing
+        .map(({ storyId, missingEvidence }) => `${storyId} (${missingEvidence.map(({ surface, scenario }) => `${surface}/${scenario}`).join(", ") || "none"})`)
+        .join("\n");
+    throw new Error(`Showcase evidence is incomplete:\n${details}`);
+}
+export function summarizeShowcaseMaturity(entries = componentCatalog) {
+    return entries.reduce((summary, entry) => {
+        summary[entry.status] += 1;
+        return summary;
+    }, { stable: 0, beta: 0, planned: 0, deprecated: 0 });
+}
+//# sourceMappingURL=showcase.js.map

package/dist/showcase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"showcase.js","sourceRoot":"","sources":["../src/showcase.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  componentCatalog,\n  getComponentSurfaceStatus,\n  type ComponentCatalogEntry,\n  type ComponentStatus,\n  type ComponentSurface,\n  type ComponentSurfaceMaturity,\n  type ComponentSurfaceStatus,\n} from \"./catalog.js\";\nimport type { ResolvedTheme } from \"./colors.js\";\nimport type {\n  DesignSystemDirection,\n  DesignSystemEnvironmentInput,\n  DesignSystemTextScale,\n} from \"./design-system-provider.js\";\n\nexport type ShowcaseTheme = ResolvedTheme;\nexport type ShowcaseDirection = DesignSystemDirection;\n/** Closed fixture subset of the Provider's continuous text-scale signal. */\nexport type ShowcaseTextScale = 1 | 1.5 | 2;\nexport type ShowcaseMotionPreference = \"full\" | \"reduced\";\n\nexport type ShowcaseEnvironment = Readonly<{\n  id: \"default\" | \"dark\" | \"large-text\" | \"rtl\" | \"reduced-motion\";\n  label: string;\n  theme: ShowcaseTheme;\n  direction: ShowcaseDirection;\n  textScale: ShowcaseTextScale;\n  motion: ShowcaseMotionPreference;\n}>;\n\n/**\n * A small, deliberate environment matrix catches the high-risk differences\n * without multiplying every story into an unreadable Cartesian product.\n */\nexport const showcaseEnvironmentMatrix = [\n  {\n    id: \"default\",\n    label: \"Light · LTR · 100%\",\n    theme: \"light\",\n    direction: \"ltr\",\n    textScale: 1,\n    motion: \"full\",\n  },\n  {\n    id: \"dark\",\n    label: \"Dark · LTR · 100%\",\n    theme: \"dark\",\n    direction: \"ltr\",\n    textScale: 1,\n    motion: \"full\",\n  },\n  {\n    id: \"large-text\",\n    label: \"Light · LTR · 200%\",\n    theme: \"light\",\n    direction: \"ltr\",\n    textScale: 2,\n    motion: \"full\",\n  },\n  {\n    id: \"rtl\",\n    label: \"Light · RTL · 100%\",\n    theme: \"light\",\n    direction: \"rtl\",\n    textScale: 1,\n    motion: \"full\",\n  },\n  {\n    id: \"reduced-motion\",\n    label: \"Light · LTR · Reduced motion\",\n    theme: \"light\",\n    direction: \"ltr\",\n    textScale: 1,\n    motion: \"reduced\",\n  },\n] as const satisfies readonly ShowcaseEnvironment[];\n\n/** Bridges documentation fixtures to the same environment contract products consume. */\nexport function getShowcaseEnvironmentInput(\n  environment: ShowcaseEnvironment,\n): DesignSystemEnvironmentInput {\n  const textScale: DesignSystemTextScale = environment.textScale;\n  return {\n    theme: environment.theme,\n    direction: environment.direction,\n    textScale,\n    reducedMotion: environment.motion === \"reduced\",\n  };\n}\n\nexport type ShowcaseScenarioId =\n  | \"contract\"\n  | \"default\"\n  | \"dark\"\n  | \"long-copy\"\n  | \"large-text\"\n  | \"rtl\"\n  | \"reduced-motion\"\n  | \"accessibility\"\n  | \"keyboard\"\n  | \"platform-parity\";\n\nexport type ShowcaseSurface = \"contract\" | \"web\" | \"native\";\n\nexport type ShowcaseScenario = Readonly<{\n  id: ShowcaseScenarioId;\n  label: string;\n  description: string;\n}>;\n\nexport const showcaseScenarios = [\n  {\n    id: \"contract\",\n    label: \"Contract\",\n    description: \"Anatomy, defaults, supported axes, platform and maturity are visible.\",\n  },\n  {\n    id: \"default\",\n    label: \"Default\",\n    description: \"The normal state renders using recipe defaults without product overrides.\",\n  },\n  {\n    id: \"dark\",\n    label: \"Dark\",\n    description: \"Semantic colors remain legible on the dark theme.\",\n  },\n  {\n    id: \"long-copy\",\n    label: \"Long copy\",\n    description: \"Long Korean and English copy wraps without clipping or hiding meaning.\",\n  },\n  {\n    id: \"large-text\",\n    label: \"200% text\",\n    description: \"Text can grow to 200% without truncating required information.\",\n  },\n  {\n    id: \"rtl\",\n    label: \"RTL\",\n    description: \"Logical start/end layout and directional icons mirror correctly.\",\n  },\n  {\n    id: \"reduced-motion\",\n    label: \"Reduced motion\",\n    description: \"Motion follows the recipe reduced-motion fallback.\",\n  },\n  {\n    id: \"accessibility\",\n    label: \"Accessibility\",\n    description: \"Names, states, relationships, contrast and touch targets are inspectable.\",\n  },\n  {\n    id: \"keyboard\",\n    label: \"Keyboard\",\n    description: \"Focus order and documented keyboard behavior run as interaction tests.\",\n  },\n  {\n    id: \"platform-parity\",\n    label: \"Web / Native parity\",\n    description: \"Adaptive renderers preserve intent while using platform-native behavior.\",\n  },\n] as const satisfies readonly ShowcaseScenario[];\n\nconst plannedRequirements = [\"contract\"] as const satisfies readonly ShowcaseScenarioId[];\nconst rendererRequirements = [\n  \"default\",\n  \"dark\",\n  \"long-copy\",\n  \"large-text\",\n  \"rtl\",\n  \"reduced-motion\",\n  \"accessibility\",\n] as const satisfies readonly Exclude<ShowcaseScenarioId, \"contract\">[];\n\nexport type ShowcaseComponentEntry = Readonly<{\n  storyId: string;\n  component: ComponentCatalogEntry;\n  /** Resolved Web/Native renderer maturity, including legacy catalog inputs. */\n  surfaceMaturity: ComponentSurfaceMaturity;\n  requirements: readonly ShowcaseEvidenceRequirement[];\n  requiredScenarios: readonly ShowcaseScenarioId[];\n  requiredSurfaces: readonly ShowcaseSurface[];\n}>;\n\nexport type ShowcaseEvidenceRequirement = Readonly<{\n  surface: ShowcaseSurface;\n  scenarios: readonly ShowcaseScenarioId[];\n}>;\n\nexport type ShowcaseEvidenceEntry = Readonly<{\n  storyId: string;\n  surface: ShowcaseSurface;\n  scenarios: readonly ShowcaseScenarioId[];\n}>;\n\nexport type ShowcaseCoverageEntry = Readonly<{\n  storyId: string;\n  component: ComponentCatalogEntry;\n  missingEvidence: readonly Readonly<{\n    surface: ShowcaseSurface;\n    scenario: ShowcaseScenarioId;\n  }>[];\n  missingSurfaces: readonly ShowcaseSurface[];\n  missingScenarios: readonly ShowcaseScenarioId[];\n  complete: boolean;\n}>;\n\nexport function getShowcaseStoryId(entry: ComponentCatalogEntry): string {\n  const slug = entry.name\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    .replace(/[^a-zA-Z0-9]+/g, \"-\")\n    .replace(/^-|-$/g, \"\")\n    .toLowerCase();\n  return `${entry.category}/${slug}`;\n}\n\nexport function getRequiredShowcaseScenarios(\n  entry: ComponentCatalogEntry,\n): readonly ShowcaseScenarioId[] {\n  const activeSurfaces = ([\"web\", \"native\"] as const).filter((surface) =>\n    isRendererMaturity(getComponentSurfaceStatus(entry, surface)),\n  );\n  if (activeSurfaces.length === 0) return plannedRequirements;\n\n  return [\"contract\", ...getRendererShowcaseScenarios(entry, activeSurfaces)];\n}\n\nfunction isRendererMaturity(\n  status: ComponentSurfaceStatus,\n): status is Extract<ComponentStatus, \"stable\" | \"beta\"> {\n  return status === \"stable\" || status === \"beta\";\n}\n\nfunction getRendererShowcaseScenarios(\n  entry: ComponentCatalogEntry,\n  activeSurfaces: readonly ComponentSurface[],\n): readonly Exclude<ShowcaseScenarioId, \"contract\">[] {\n  const requirements: Exclude<ShowcaseScenarioId, \"contract\">[] = [...rendererRequirements];\n  if (entry.behavior) {\n    requirements.push(\"keyboard\");\n  }\n  if (\n    entry.platform === \"adaptive\" &&\n    activeSurfaces.includes(\"web\") &&\n    activeSurfaces.includes(\"native\")\n  ) {\n    requirements.push(\"platform-parity\");\n  }\n  return requirements;\n}\n\nexport function getRequiredShowcaseSurfaces(\n  entry: ComponentCatalogEntry,\n): readonly ShowcaseSurface[] {\n  return getRequiredShowcaseEvidence(entry).map(({ surface }) => surface);\n}\n\nexport function getRequiredShowcaseEvidence(\n  entry: ComponentCatalogEntry,\n): readonly ShowcaseEvidenceRequirement[] {\n  const requirements: ShowcaseEvidenceRequirement[] = [\n    { surface: \"contract\", scenarios: [\"contract\"] },\n  ];\n  const activeSurfaces = ([\"web\", \"native\"] as const).filter((surface) =>\n    isRendererMaturity(getComponentSurfaceStatus(entry, surface)),\n  );\n  const rendererScenarios = getRendererShowcaseScenarios(entry, activeSurfaces);\n  for (const surface of activeSurfaces) {\n    requirements.push({ surface, scenarios: rendererScenarios });\n  }\n  return requirements;\n}\n\nexport function createShowcaseManifest(\n  entries: readonly ComponentCatalogEntry[] = componentCatalog,\n): readonly ShowcaseComponentEntry[] {\n  return entries.map((component) => ({\n    storyId: getShowcaseStoryId(component),\n    component,\n    surfaceMaturity: {\n      web: getComponentSurfaceStatus(component, \"web\"),\n      native: getComponentSurfaceStatus(component, \"native\"),\n    },\n    requirements: getRequiredShowcaseEvidence(component),\n    requiredScenarios: getRequiredShowcaseScenarios(component),\n    requiredSurfaces: getRequiredShowcaseSurfaces(component),\n  }));\n}\n\nexport const showcaseManifest = createShowcaseManifest();\n\nexport function createShowcaseCoverage(\n  evidence: readonly ShowcaseEvidenceEntry[],\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): readonly ShowcaseCoverageEntry[] {\n  return manifest.map(({ storyId, component, requirements }) => {\n    const componentEvidence = evidence.filter((entry) => entry.storyId === storyId);\n    const missingEvidence = requirements.flatMap(({ surface, scenarios }) =>\n      scenarios\n        .filter(\n          (scenario) =>\n            !componentEvidence.some(\n              (entry) => entry.surface === surface && entry.scenarios.includes(scenario),\n            ),\n        )\n        .map((scenario) => ({ surface, scenario })),\n    );\n    const missingSurfaces = [...new Set(missingEvidence.map(({ surface }) => surface))];\n    const missingScenarios = [...new Set(missingEvidence.map(({ scenario }) => scenario))];\n    return {\n      storyId,\n      component,\n      missingEvidence,\n      missingSurfaces,\n      missingScenarios,\n      complete: missingSurfaces.length === 0 && missingScenarios.length === 0,\n    };\n  });\n}\n\nexport function assertShowcaseCoverage(\n  evidence: readonly ShowcaseEvidenceEntry[],\n  manifest: readonly ShowcaseComponentEntry[] = showcaseManifest,\n): void {\n  const missing = createShowcaseCoverage(evidence, manifest).filter(({ complete }) => !complete);\n  if (missing.length === 0) return;\n  const details = missing\n    .map(({ storyId, missingEvidence }) =>\n      `${storyId} (${missingEvidence.map(({ surface, scenario }) => `${surface}/${scenario}`).join(\", \") || \"none\"})`,\n    )\n    .join(\"\\n\");\n  throw new Error(`Showcase evidence is incomplete:\\n${details}`);\n}\n\nexport function summarizeShowcaseMaturity(\n  entries: readonly ComponentCatalogEntry[] = componentCatalog,\n): Readonly<Record<ComponentStatus, number>> {\n  return entries.reduce<Record<ComponentStatus, number>>(\n    (summary, entry) => {\n      summary[entry.status] += 1;\n      return summary;\n    },\n    { stable: 0, beta: 0, planned: 0, deprecated: 0 },\n  );\n}\n"]}

package/dist/side-panel.d.ts

@@ -0,0 +1,199 @@
+/** Logical, RTL-aware docking side. `top`/`bottom` stay Sheet's job — see docs/side-panel.md. */
+export type SidePanelEdge = "start" | "end";
+/**
+ * No `"back"`/`"swipe"`: SidePanel is Web-only (no hardware back, no
+ * measured demand for a swipe-to-dismiss drawer). Everything else mirrors
+ * `SheetDismissReason` (`src/sheet.ts`) because the *reasons* a panel closes
+ * are the same on Web; only which reasons are *permitted* differs by `modal`.
+ */
+export type SidePanelDismissReason = "close-action" | "escape" | "outside" | "programmatic";
+export type SidePanelOpenChangeDetails = Readonly<{
+    reason: "trigger" | SidePanelDismissReason;
+}>;
+export type SidePanelOpenState = Readonly<{
+    open: boolean;
+    defaultOpen?: never;
+    onOpenChange(open: boolean, detail: SidePanelOpenChangeDetails): void;
+}> | Readonly<{
+    open?: never;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean, detail: SidePanelOpenChangeDetails) => void;
+}>;
+/**
+ * `modal` is the axis Sheet does not need (Sheet is always modal). A
+ * non-modal panel has no backdrop to click "outside" of — the rest of the
+ * page stays live and interactive — so `outsideDismiss` is not merely
+ * defaulted to `false` there, the type forbids it from existing at all.
+ * This is the same "make the invalid combination unrepresentable" move as
+ * `SheetOpenState`'s controlled/uncontrolled split.
+ */
+export type SidePanelDismissPolicy = Readonly<{
+    modal: true;
+    dismissible: boolean;
+    dismissWhileBusy: boolean;
+    escapeDismiss: boolean;
+    outsideDismiss: boolean;
+}> | Readonly<{
+    modal: false;
+    dismissible: boolean;
+    dismissWhileBusy: boolean;
+    escapeDismiss: boolean;
+    outsideDismiss?: never;
+}>;
+export declare const sidePanelBehaviorDefaults: {
+    readonly modal: true;
+    readonly dismissible: true;
+    readonly dismissWhileBusy: false;
+    readonly escapeDismiss: true;
+    readonly outsideDismiss: true;
+};
+/**
+ * Same shape and role as `canDismissSheet`, kept as a separate function
+ * because the two owning types are not generic over each other (`sheet.ts`
+ * is a shared file this module must not edit) and the `modal` branch is
+ * genuine new logic, not a copy.
+ */
+export declare function canDismissSidePanel(reason: SidePanelDismissReason, busy: boolean, policy?: SidePanelDismissPolicy): boolean;
+export type SidePanelSize = "compact" | "regular" | "wide";
+/**
+ * No `createSidePanelLifecycle` counterpart to `createSheetLifecycle`: that
+ * machinery exists solely to make Android's persistently-mounted native
+ * Modal settle one visible cycle at a time. SidePanel is Web-only, where a
+ * plain CSS `transitionend`/exit-callback (the same pattern `sheetRecipe`
+ * and `dialogRecipe` already assume for Web) is the whole story — adding a
+ * cycle counter here would solve a problem this platform does not have.
+ */
+export declare const sidePanelRecipe: {
+    readonly slots: readonly ["backdrop", "positioner", "content", "header", "title", "body", "footer", "close"];
+    readonly defaults: {
+        readonly edge: "end";
+        readonly size: "regular";
+    };
+    readonly sizes: {
+        readonly compact: 320;
+        readonly regular: 400;
+        readonly wide: 560;
+    };
+    readonly backdrop: {
+        readonly color: "#000000";
+        readonly opacity: 0.6;
+    };
+    readonly content: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "bg";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "border";
+            alpha?: number;
+        }>;
+        readonly borderWidth: 1;
+        /** Flush to the viewport edge it docks to — unlike Sheet's floating `xl` radius. */
+        readonly radius: null;
+        readonly shadow: {
+            readonly color: "#000000";
+            readonly opacity: 0.16;
+            readonly radius: 24;
+            readonly offsetY: 8;
+        };
+        readonly paddingHorizontal: 20;
+        readonly paddingTop: 12;
+        readonly paddingBottom: 12;
+    };
+    readonly header: {
+        readonly minHeight: 44;
+        readonly gap: 12;
+    };
+    readonly title: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "text";
+            alpha?: number;
+        }>;
+        readonly textVariant: "title";
+        readonly fontWeight: "700";
+    };
+    readonly body: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly textVariant: "body";
+        readonly gap: 16;
+    };
+    readonly footer: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly textVariant: "body";
+        readonly gap: 12;
+        readonly paddingTop: 12;
+    };
+    readonly transition: {
+        readonly enter: {
+            readonly duration: 200;
+            readonly easing: "enter";
+            readonly reducedMotion: "opacity";
+        };
+        readonly exit: {
+            readonly duration: 120;
+            readonly easing: "exit";
+            readonly reducedMotion: "instant";
+        };
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+    };
+};
+/**
+ * `web.focus` can only hold one value, but the real behavior branches on
+ * `modal`: `"trap"` (default, modal) vs. no trap at all when `modal: false`.
+ * The field records the default configuration; the non-modal case is a
+ * documented exception in `docs/side-panel.md`, the same way this contract
+ * records one representative value elsewhere and pushes edge cases to
+ * `scenarios`.
+ */
+export declare const sidePanelBehavior: {
+    readonly controlled: readonly ["open", "defaultOpen", "onOpenChange", "dismissPolicy"];
+    readonly defaults: {
+        readonly modal: true;
+        readonly dismissible: true;
+        readonly dismissWhileBusy: false;
+        readonly escapeDismiss: true;
+        readonly outsideDismiss: true;
+    };
+    readonly configuration: {
+        readonly edge: readonly ["start", "end"];
+        readonly modal: readonly ["true", "false"];
+    };
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "busy"];
+        readonly value: readonly ["open"];
+    };
+    readonly web: {
+        readonly roles: readonly ["dialog"];
+        readonly keyboard: readonly ["Tab", "Escape"];
+        readonly focus: "trap";
+        readonly dismiss: readonly ["escape", "outside"];
+    };
+    readonly native: {
+        readonly roles: readonly [];
+        readonly states: readonly [];
+        readonly actions: readonly [];
+    };
+    readonly scenarios: readonly ["edge-is-a-logical-start-or-end-direction-never-left-or-right", "modal-panels-trap-focus-and-lock-scroll-non-modal-panels-do-neither", "non-modal-panels-never-expose-outside-dismiss-the-type-forbids-it", "single-dismiss-callback-reports-the-concrete-reason", "busy-blocks-user-dismiss-programmatic-owner-close-is-always-allowed", "escape-dismisses-in-both-modal-and-non-modal-panels", "no-back-or-swipe-dismiss-reason-exists-on-this-web-only-platform", "reduced-motion-still-completes-the-exit-callback-once"];
+};
+//# sourceMappingURL=side-panel.d.ts.map

package/dist/side-panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"side-panel.d.ts","sourceRoot":"","sources":["../src/side-panel.ts"],"names":[],"mappings":"AAeA,iGAAiG;AACjG,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,KAAK,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAAG,cAAc,GAAG,QAAQ,GAAG,SAAS,GAAG,cAAc,CAAC;AAE5F,MAAM,MAAM,0BAA0B,GAAG,QAAQ,CAAC;IAChD,MAAM,EAAE,SAAS,GAAG,sBAAsB,CAAC;CAC5C,CAAC,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,CAAC;IACP,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,KAAK,CAAC;IACpB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;CACvE,CAAC,GACF,QAAQ,CAAC;IACP,IAAI,CAAC,EAAE,KAAK,CAAC;IACb,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,0BAA0B,KAAK,IAAI,CAAC;CAC5E,CAAC,CAAC;AAEP;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAC9B,QAAQ,CAAC;IACP,KAAK,EAAE,IAAI,CAAC;IACZ,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,EAAE,OAAO,CAAC;CACzB,CAAC,GACF,QAAQ,CAAC;IACP,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,KAAK,CAAC;CACxB,CAAC,CAAC;AAEP,eAAO,MAAM,yBAAyB;;;;;;CAM+B,CAAC;AAEtE;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,sBAAsB,EAC9B,IAAI,EAAE,OAAO,EACb,MAAM,GAAE,sBAAkD,GACzD,OAAO,CAOT;AAED,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;QASxB,oFAAoF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+CvF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BO,CAAC"}

package/dist/side-panel.js

@@ -0,0 +1,111 @@
+import { floatingSurfaceContract, focusIndicatorContract } from "./component-contracts.js";
+import { backdrop, control, fontWeight, motionPreset, shadow, spacing, } from "./foundations.js";
+import { semanticColors } from "./semantic-colors.js";
+export const sidePanelBehaviorDefaults = {
+    modal: true,
+    dismissible: true,
+    dismissWhileBusy: false,
+    escapeDismiss: true,
+    outsideDismiss: true,
+};
+/**
+ * Same shape and role as `canDismissSheet`, kept as a separate function
+ * because the two owning types are not generic over each other (`sheet.ts`
+ * is a shared file this module must not edit) and the `modal` branch is
+ * genuine new logic, not a copy.
+ */
+export function canDismissSidePanel(reason, busy, policy = sidePanelBehaviorDefaults) {
+    if (reason === "programmatic")
+        return true;
+    if (!policy.dismissible)
+        return false;
+    if (busy && !policy.dismissWhileBusy)
+        return false;
+    if (reason === "outside")
+        return policy.modal ? policy.outsideDismiss : false;
+    if (reason === "escape")
+        return policy.escapeDismiss;
+    return true;
+}
+/**
+ * No `createSidePanelLifecycle` counterpart to `createSheetLifecycle`: that
+ * machinery exists solely to make Android's persistently-mounted native
+ * Modal settle one visible cycle at a time. SidePanel is Web-only, where a
+ * plain CSS `transitionend`/exit-callback (the same pattern `sheetRecipe`
+ * and `dialogRecipe` already assume for Web) is the whole story — adding a
+ * cycle counter here would solve a problem this platform does not have.
+ */
+export const sidePanelRecipe = {
+    slots: ["backdrop", "positioner", "content", "header", "title", "body", "footer", "close"],
+    defaults: { edge: "end", size: "regular" },
+    sizes: { compact: 320, regular: 400, wide: 560 },
+    backdrop: backdrop.modal,
+    content: {
+        background: semanticColors.canvas,
+        border: semanticColors.border.default,
+        borderWidth: floatingSurfaceContract.borderWidth,
+        /** Flush to the viewport edge it docks to — unlike Sheet's floating `xl` radius. */
+        radius: null,
+        shadow: shadow.overlay,
+        paddingHorizontal: spacing.lg,
+        paddingTop: spacing.sm,
+        paddingBottom: spacing.sm,
+    },
+    header: { minHeight: control.minTouchTarget, gap: spacing.sm },
+    title: {
+        color: semanticColors.content.primary,
+        textVariant: "title",
+        fontWeight: fontWeight.bold,
+    },
+    body: {
+        color: semanticColors.content.body,
+        textVariant: "body",
+        gap: spacing.md,
+    },
+    footer: {
+        color: semanticColors.content.body,
+        textVariant: "body",
+        gap: spacing.sm,
+        paddingTop: spacing.sm,
+    },
+    transition: { enter: motionPreset.enter, exit: motionPreset.exit },
+    states: { focus: focusIndicatorContract },
+};
+/**
+ * `web.focus` can only hold one value, but the real behavior branches on
+ * `modal`: `"trap"` (default, modal) vs. no trap at all when `modal: false`.
+ * The field records the default configuration; the non-modal case is a
+ * documented exception in `docs/side-panel.md`, the same way this contract
+ * records one representative value elsewhere and pushes edge cases to
+ * `scenarios`.
+ */
+export const sidePanelBehavior = {
+    controlled: ["open", "defaultOpen", "onOpenChange", "dismissPolicy"],
+    defaults: sidePanelBehaviorDefaults,
+    configuration: {
+        edge: ["start", "end"],
+        modal: ["true", "false"],
+    },
+    stateAxes: {
+        availability: ["enabled", "busy"],
+        value: ["open"],
+    },
+    web: {
+        roles: ["dialog"],
+        keyboard: ["Tab", "Escape"],
+        focus: "trap",
+        dismiss: ["escape", "outside"],
+    },
+    native: { roles: [], states: [], actions: [] },
+    scenarios: [
+        "edge-is-a-logical-start-or-end-direction-never-left-or-right",
+        "modal-panels-trap-focus-and-lock-scroll-non-modal-panels-do-neither",
+        "non-modal-panels-never-expose-outside-dismiss-the-type-forbids-it",
+        "single-dismiss-callback-reports-the-concrete-reason",
+        "busy-blocks-user-dismiss-programmatic-owner-close-is-always-allowed",
+        "escape-dismisses-in-both-modal-and-non-modal-panels",
+        "no-back-or-swipe-dismiss-reason-exists-on-this-web-only-platform",
+        "reduced-motion-still-completes-the-exit-callback-once",
+    ],
+};
+//# sourceMappingURL=side-panel.js.map

package/dist/side-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"side-panel.js","sourceRoot":"","sources":["../src/side-panel.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAC3F,OAAO,EACL,QAAQ,EACR,OAAO,EACP,UAAU,EACV,YAAY,EACZ,MAAM,EACN,OAAO,GAGR,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAqDtD,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,KAAK,EAAE,IAAI;IACX,WAAW,EAAE,IAAI;IACjB,gBAAgB,EAAE,KAAK;IACvB,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,IAAI;CAC+C,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA8B,EAC9B,IAAa,EACb,SAAiC,yBAAyB;IAE1D,IAAI,MAAM,KAAK,cAAc;QAAE,OAAO,IAAI,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB;QAAE,OAAO,KAAK,CAAC;IACnD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC;IAC9E,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC,aAAa,CAAC;IACrD,OAAO,IAAI,CAAC;AACd,CAAC;AAID;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,KAAK,EAAE,CAAC,UAAU,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAU;IACnG,QAAQ,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE;IAC1C,KAAK,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE;IAChD,QAAQ,EAAE,QAAQ,CAAC,KAAK;IACxB,OAAO,EAAE;QACP,UAAU,EAAE,cAAc,CAAC,MAAM;QACjC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,OAAO;QACrC,WAAW,EAAE,uBAAuB,CAAC,WAAW;QAChD,oFAAoF;QACpF,MAAM,EAAE,IAAI;QACZ,MAAM,EAAE,MAAM,CAAC,OAAO;QACtB,iBAAiB,EAAE,OAAO,CAAC,EAAE;QAC7B,UAAU,EAAE,OAAO,CAAC,EAAE;QACtB,aAAa,EAAE,OAAO,CAAC,EAAE;KAC1B;IACD,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,CAAC,cAAc,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE;IAC9D,KAAK,EAAE;QACL,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,OAAO;QACrC,WAAW,EAAE,OAAO;QACpB,UAAU,EAAE,UAAU,CAAC,IAAI;KAC5B;IACD,IAAI,EAAE;QACJ,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;QAClC,WAAW,EAAE,MAAM;QACnB,GAAG,EAAE,OAAO,CAAC,EAAE;KAChB;IACD,MAAM,EAAE;QACN,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,IAAI;QAClC,WAAW,EAAE,MAAM;QACnB,GAAG,EAAE,OAAO,CAAC,EAAE;QACf,UAAU,EAAE,OAAO,CAAC,EAAE;KACvB;IACD,UAAU,EAAE,EAAE,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE;IAClE,MAAM,EAAE,EAAE,KAAK,EAAE,sBAAsB,EAAE;CAsB1C,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,UAAU,EAAE,CAAC,MAAM,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,CAAC;IACpE,QAAQ,EAAE,yBAAyB;IACnC,aAAa,EAAE;QACb,IAAI,EAAE,CAAC,OAAO,EAAE,KAAK,CAAC;QACtB,KAAK,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC;KACzB;IACD,SAAS,EAAE;QACT,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC;QACjC,KAAK,EAAE,CAAC,MAAM,CAAC;KAChB;IACD,GAAG,EAAE;QACH,KAAK,EAAE,CAAC,QAAQ,CAAC;QACjB,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC3B,KAAK,EAAE,MAAM;QACb,OAAO,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC;KAC/B;IACD,MAAM,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE;IAC9C,SAAS,EAAE;QACT,8DAA8D;QAC9D,qEAAqE;QACrE,mEAAmE;QACnE,qDAAqD;QACrD,qEAAqE;QACrE,qDAAqD;QACrD,kEAAkE;QAClE,uDAAuD;KACxD;CACkC,CAAC","sourcesContent":["import type { ColorReference } from \"./color-references.js\";\nimport type { BehaviorContract } from \"./behaviors.js\";\nimport { floatingSurfaceContract, focusIndicatorContract } from \"./component-contracts.js\";\nimport {\n  backdrop,\n  control,\n  fontWeight,\n  motionPreset,\n  shadow,\n  spacing,\n  type FontWeightValue,\n  type TextVariant,\n} from \"./foundations.js\";\nimport { semanticColors } from \"./semantic-colors.js\";\n\n/** Logical, RTL-aware docking side. `top`/`bottom` stay Sheet's job — see docs/side-panel.md. */\nexport type SidePanelEdge = \"start\" | \"end\";\n\n/**\n * No `\"back\"`/`\"swipe\"`: SidePanel is Web-only (no hardware back, no\n * measured demand for a swipe-to-dismiss drawer). Everything else mirrors\n * `SheetDismissReason` (`src/sheet.ts`) because the *reasons* a panel closes\n * are the same on Web; only which reasons are *permitted* differs by `modal`.\n */\nexport type SidePanelDismissReason = \"close-action\" | \"escape\" | \"outside\" | \"programmatic\";\n\nexport type SidePanelOpenChangeDetails = Readonly<{\n  reason: \"trigger\" | SidePanelDismissReason;\n}>;\n\nexport type SidePanelOpenState =\n  | Readonly<{\n      open: boolean;\n      defaultOpen?: never;\n      onOpenChange(open: boolean, detail: SidePanelOpenChangeDetails): void;\n    }>\n  | Readonly<{\n      open?: never;\n      defaultOpen?: boolean;\n      onOpenChange?: (open: boolean, detail: SidePanelOpenChangeDetails) => void;\n    }>;\n\n/**\n * `modal` is the axis Sheet does not need (Sheet is always modal). A\n * non-modal panel has no backdrop to click \"outside\" of — the rest of the\n * page stays live and interactive — so `outsideDismiss` is not merely\n * defaulted to `false` there, the type forbids it from existing at all.\n * This is the same \"make the invalid combination unrepresentable\" move as\n * `SheetOpenState`'s controlled/uncontrolled split.\n */\nexport type SidePanelDismissPolicy =\n  | Readonly<{\n      modal: true;\n      dismissible: boolean;\n      dismissWhileBusy: boolean;\n      escapeDismiss: boolean;\n      outsideDismiss: boolean;\n    }>\n  | Readonly<{\n      modal: false;\n      dismissible: boolean;\n      dismissWhileBusy: boolean;\n      escapeDismiss: boolean;\n      outsideDismiss?: never;\n    }>;\n\nexport const sidePanelBehaviorDefaults = {\n  modal: true,\n  dismissible: true,\n  dismissWhileBusy: false,\n  escapeDismiss: true,\n  outsideDismiss: true,\n} as const satisfies Extract<SidePanelDismissPolicy, { modal: true }>;\n\n/**\n * Same shape and role as `canDismissSheet`, kept as a separate function\n * because the two owning types are not generic over each other (`sheet.ts`\n * is a shared file this module must not edit) and the `modal` branch is\n * genuine new logic, not a copy.\n */\nexport function canDismissSidePanel(\n  reason: SidePanelDismissReason,\n  busy: boolean,\n  policy: SidePanelDismissPolicy = sidePanelBehaviorDefaults,\n): boolean {\n  if (reason === \"programmatic\") return true;\n  if (!policy.dismissible) return false;\n  if (busy && !policy.dismissWhileBusy) return false;\n  if (reason === \"outside\") return policy.modal ? policy.outsideDismiss : false;\n  if (reason === \"escape\") return policy.escapeDismiss;\n  return true;\n}\n\nexport type SidePanelSize = \"compact\" | \"regular\" | \"wide\";\n\n/**\n * No `createSidePanelLifecycle` counterpart to `createSheetLifecycle`: that\n * machinery exists solely to make Android's persistently-mounted native\n * Modal settle one visible cycle at a time. SidePanel is Web-only, where a\n * plain CSS `transitionend`/exit-callback (the same pattern `sheetRecipe`\n * and `dialogRecipe` already assume for Web) is the whole story — adding a\n * cycle counter here would solve a problem this platform does not have.\n */\nexport const sidePanelRecipe = {\n  slots: [\"backdrop\", \"positioner\", \"content\", \"header\", \"title\", \"body\", \"footer\", \"close\"] as const,\n  defaults: { edge: \"end\", size: \"regular\" },\n  sizes: { compact: 320, regular: 400, wide: 560 },\n  backdrop: backdrop.modal,\n  content: {\n    background: semanticColors.canvas,\n    border: semanticColors.border.default,\n    borderWidth: floatingSurfaceContract.borderWidth,\n    /** Flush to the viewport edge it docks to — unlike Sheet's floating `xl` radius. */\n    radius: null,\n    shadow: shadow.overlay,\n    paddingHorizontal: spacing.lg,\n    paddingTop: spacing.sm,\n    paddingBottom: spacing.sm,\n  },\n  header: { minHeight: control.minTouchTarget, gap: spacing.sm },\n  title: {\n    color: semanticColors.content.primary,\n    textVariant: \"title\",\n    fontWeight: fontWeight.bold,\n  },\n  body: {\n    color: semanticColors.content.body,\n    textVariant: \"body\",\n    gap: spacing.md,\n  },\n  footer: {\n    color: semanticColors.content.body,\n    textVariant: \"body\",\n    gap: spacing.sm,\n    paddingTop: spacing.sm,\n  },\n  transition: { enter: motionPreset.enter, exit: motionPreset.exit },\n  states: { focus: focusIndicatorContract },\n} as const satisfies {\n  slots: readonly [\"backdrop\", \"positioner\", \"content\", \"header\", \"title\", \"body\", \"footer\", \"close\"];\n  defaults: { edge: SidePanelEdge; size: SidePanelSize };\n  sizes: Record<SidePanelSize, number>;\n  backdrop: typeof backdrop.modal;\n  content: {\n    background: ColorReference;\n    border: ColorReference;\n    borderWidth: number;\n    radius: null;\n    shadow: typeof shadow.overlay;\n    paddingHorizontal: number;\n    paddingTop: number;\n    paddingBottom: number;\n  };\n  header: { minHeight: number; gap: number };\n  title: { color: ColorReference; textVariant: TextVariant; fontWeight: FontWeightValue };\n  body: { color: ColorReference; textVariant: TextVariant; gap: number };\n  footer: { color: ColorReference; textVariant: TextVariant; gap: number; paddingTop: number };\n  transition: { enter: typeof motionPreset.enter; exit: typeof motionPreset.exit };\n  states: { focus: typeof focusIndicatorContract };\n};\n\n/**\n * `web.focus` can only hold one value, but the real behavior branches on\n * `modal`: `\"trap\"` (default, modal) vs. no trap at all when `modal: false`.\n * The field records the default configuration; the non-modal case is a\n * documented exception in `docs/side-panel.md`, the same way this contract\n * records one representative value elsewhere and pushes edge cases to\n * `scenarios`.\n */\nexport const sidePanelBehavior = {\n  controlled: [\"open\", \"defaultOpen\", \"onOpenChange\", \"dismissPolicy\"],\n  defaults: sidePanelBehaviorDefaults,\n  configuration: {\n    edge: [\"start\", \"end\"],\n    modal: [\"true\", \"false\"],\n  },\n  stateAxes: {\n    availability: [\"enabled\", \"busy\"],\n    value: [\"open\"],\n  },\n  web: {\n    roles: [\"dialog\"],\n    keyboard: [\"Tab\", \"Escape\"],\n    focus: \"trap\",\n    dismiss: [\"escape\", \"outside\"],\n  },\n  native: { roles: [], states: [], actions: [] },\n  scenarios: [\n    \"edge-is-a-logical-start-or-end-direction-never-left-or-right\",\n    \"modal-panels-trap-focus-and-lock-scroll-non-modal-panels-do-neither\",\n    \"non-modal-panels-never-expose-outside-dismiss-the-type-forbids-it\",\n    \"single-dismiss-callback-reports-the-concrete-reason\",\n    \"busy-blocks-user-dismiss-programmatic-owner-close-is-always-allowed\",\n    \"escape-dismisses-in-both-modal-and-non-modal-panels\",\n    \"no-back-or-swipe-dismiss-reason-exists-on-this-web-only-platform\",\n    \"reduced-motion-still-completes-the-exit-callback-once\",\n  ],\n} as const satisfies BehaviorContract;\n"]}