@doneisbetter/gds-core 2.6.6 → 3.0.0

package/dist/{chunk-4YTMKBGW.mjs → chunk-NBCULITN.mjs}

@@ -7,7 +7,7 @@ import {
   StateBlock,
   getSemanticActionLabel,
   resolveSemanticActionConfig
-} from "./chunk-IAP3JU55.mjs";
+} from "./chunk-P7ICTEEB.mjs";
 
 // src/SemanticButton.tsx
 import { useEffect, useState } from "react";
@@ -141,42 +141,77 @@ import {
   gdsTheme
 } from "@doneisbetter/gds-theme";
 import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
+function resolvePreviewColorScheme(presetId, requestedScheme) {
+  if (presetId === "dark-public") {
+    return "dark";
+  }
+  return requestedScheme;
+}
 var themePresetCatalog = {
   default: {
     label: "Default runtime theme",
     bestFor: "Balanced multi-surface products that need the baseline GDS system.",
     summary: "The default shared runtime lane for most adopters.",
-    themeKey: "gdsTheme"
+    themeKey: "gdsTheme",
+    supportedUse: "Starter products, hybrid public/admin apps, and teams adopting all canonical contracts.",
+    avoidFor: "Avoid for products requiring a distinct editorial voice or guaranteed dark-first brand contrast."
   },
   "dark-public": {
     label: "Dark public theme",
     bestFor: "Dark-first public experiences and campaign-style landing surfaces.",
     summary: "A darker public presentation lane with the shipped runtime rhythm intact.",
-    themeKey: "gdsDarkPublicTheme"
+    themeKey: "gdsDarkPublicTheme",
+    supportedUse: "Products with a deliberate dark visual baseline, low-light UX, or premium media-first surfaces.",
+    avoidFor: "Avoid when mixed mode and editorial readability are core requirements."
   },
   "flat-surface": {
     label: "Flat surface theme",
     bestFor: "Operational products that prefer quieter elevation and flatter surface contrast.",
     summary: "Removes some visual weight without creating a second token authority.",
-    themeKey: "gdsFlatSurfaceTheme"
+    themeKey: "gdsFlatSurfaceTheme",
+    supportedUse: "Dashboards, admin surfaces, and dense content where elevation becomes distracting.",
+    avoidFor: "Avoid for brand-first storytelling or high-expressiveness hero-first pages."
   },
   editorial: {
     label: "Editorial serif theme",
     bestFor: "Documentation, editorial, and content-led experiences.",
     summary: "Adds a more expressive public reading tone while staying inside GDS contracts.",
-    themeKey: "gdsEditorialPublicTheme"
+    themeKey: "gdsEditorialPublicTheme",
+    supportedUse: "Guides, docs, and catalog content where reading comfort matters more than impact.",
+    avoidFor: "Avoid for dense transactional or data-first workflows with strict minimal contrast."
   },
   brand: {
     label: "Brand theme generator",
     bestFor: "Consumer teams that need controlled brand expression without forking the system.",
     summary: "Composes the shipped helpers into a governed product-authored theme lane.",
-    themeKey: "createPublicBrandTheme(...)"
+    themeKey: "createPublicBrandTheme(...)",
+    supportedUse: "Whitelisted public branding programs with narrow product-authored intent and policy guardrails.",
+    avoidFor: "Avoid for local style experiments or temporary visual fixes without compliance approval."
   }
 };
+var colorSchemeProof = [
+  {
+    id: "light",
+    label: "Light",
+    description: "Validates readable default surfaces, controls, badges, and focus states against light backgrounds."
+  },
+  {
+    id: "dark",
+    label: "Dark",
+    description: "Validates contrast for public, operational, and feedback surfaces when dark mode is active."
+  },
+  {
+    id: "auto",
+    label: "Auto",
+    description: "Documents the adopter path for OS-controlled schemes while keeping the provider contract unchanged."
+  }
+];
 function ThemePreviewSurface({
   preset,
-  colorScheme
+  colorScheme,
+  requestedColorScheme
 }) {
+  const forcedScheme = requestedColorScheme && requestedColorScheme !== colorScheme;
   return /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "xl", p: "lg", children: /* @__PURE__ */ jsxs2(Stack, { gap: "lg", children: [
     /* @__PURE__ */ jsxs2(Group2, { justify: "space-between", align: "flex-start", wrap: "wrap", children: [
       /* @__PURE__ */ jsxs2(Stack, { gap: 4, children: [
@@ -191,7 +226,12 @@ function ThemePreviewSurface({
           /* @__PURE__ */ jsx4("strong", { children: "Color scheme:" }),
           " ",
           colorScheme
-        ] })
+        ] }),
+        /* @__PURE__ */ jsxs2(Text2, { size: "sm", children: [
+          /* @__PURE__ */ jsx4("strong", { children: "Accessibility proof:" }),
+          " status uses text, badge label, and placement, not color alone."
+        ] }),
+        forcedScheme ? /* @__PURE__ */ jsx4(Text2, { size: "sm", c: "dimmed", children: "This lane always previews in dark mode so the runtime stays inside its sanctioned contrast contract." }) : null
       ] }),
       /* @__PURE__ */ jsx4(ThemeToggle, {})
     ] }),
@@ -220,7 +260,8 @@ function ThemePreviewSurface({
           description: "This preview uses the real shipped design-system runtime rather than a docs-only styling lane.",
           metadata: [
             { id: "runtime", label: "Runtime lane", value: preset.themeKey },
-            { id: "scheme", label: "Color scheme", value: colorScheme }
+            { id: "scheme", label: "Color scheme", value: colorScheme },
+            { id: "focus", label: "A11y proof", value: "Keyboard + readable states" }
           ],
           primaryAction: /* @__PURE__ */ jsx4(Button2, { size: "sm", children: "Inspect route" })
         }
@@ -258,8 +299,10 @@ function ReferenceThemeExplorer() {
   const comparisonSummary = themePresetCatalog[comparisonPreset];
   const selectedTheme = useMemo(() => resolveTheme(preset), [preset, brandPrimary, brandFlatSurfaces, brandEditorialSerif]);
   const comparedTheme = useMemo(() => resolveTheme(comparisonPreset), [comparisonPreset, brandPrimary, brandFlatSurfaces, brandEditorialSerif]);
-  const previewKey = `${preset}-${colorScheme}-${brandPrimary}-${brandFlatSurfaces}-${brandEditorialSerif}`;
-  const comparisonPreviewKey = `${comparisonPreset}-${colorScheme}-${brandPrimary}-${brandFlatSurfaces}-${brandEditorialSerif}`;
+  const effectiveColorScheme = resolvePreviewColorScheme(preset, colorScheme);
+  const effectiveComparisonScheme = resolvePreviewColorScheme(comparisonPreset, colorScheme);
+  const previewKey = `${preset}-${effectiveColorScheme}-${brandPrimary}-${brandFlatSurfaces}-${brandEditorialSerif}`;
+  const comparisonPreviewKey = `${comparisonPreset}-${effectiveComparisonScheme}-${brandPrimary}-${brandFlatSurfaces}-${brandEditorialSerif}`;
   const reset = () => {
     setPreset("default");
     setColorScheme("light");
@@ -335,7 +378,7 @@ function ReferenceThemeExplorer() {
             ),
             /* @__PURE__ */ jsx4(Text2, { size: "sm", c: "dimmed", children: "The generator composes shipped helpers instead of creating a second theme authority inside the website." })
           ] }) }),
-          /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "xl", p: "lg", children: /* @__PURE__ */ jsxs2(Stack, { gap: "md", children: [
+          /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "xl", p: "lg", children: /* @__PURE__ */ jsxs2(Stack, { gap: "md", role: "status", "aria-live": "polite", children: [
             /* @__PURE__ */ jsx4(Title, { order: 4, children: "Current selection summary" }),
             /* @__PURE__ */ jsxs2(Stack, { gap: 6, children: [
               /* @__PURE__ */ jsx4(Text2, { fw: 700, children: selectionSummary.label }),
@@ -354,7 +397,8 @@ function ReferenceThemeExplorer() {
                 /* @__PURE__ */ jsx4("strong", { children: "Color scheme:" }),
                 " ",
                 colorScheme
-              ] })
+              ] }),
+              preset === "dark-public" && colorScheme !== effectiveColorScheme ? /* @__PURE__ */ jsx4(Text2, { size: "sm", c: "dimmed", children: "gdsDarkPublicTheme always renders in dark mode inside the live preview." }) : null
             ] }),
             /* @__PURE__ */ jsx4(
               Checkbox,
@@ -387,18 +431,47 @@ function ReferenceThemeExplorer() {
         children: /* @__PURE__ */ jsx4(SimpleGrid, { cols: { base: 1, md: 2, xl: 5 }, spacing: "md", children: Object.values(themePresetCatalog).map((lane) => /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "lg", p: "md", children: /* @__PURE__ */ jsxs2(Stack, { gap: 6, children: [
           /* @__PURE__ */ jsx4(Text2, { fw: 700, size: "sm", children: lane.label }),
           /* @__PURE__ */ jsx4(Text2, { size: "sm", c: "dimmed", children: lane.summary }),
-          /* @__PURE__ */ jsx4(Code, { block: true, fz: "10px", children: lane.themeKey })
+          /* @__PURE__ */ jsxs2(Text2, { size: "xs", children: [
+            /* @__PURE__ */ jsx4("strong", { children: "Best for:" }),
+            " ",
+            lane.supportedUse
+          ] }),
+          /* @__PURE__ */ jsx4(Code, { block: true, fz: "10px", children: lane.themeKey }),
+          /* @__PURE__ */ jsxs2(Text2, { size: "xs", c: "dimmed", children: [
+            /* @__PURE__ */ jsx4("strong", { children: "Avoid for:" }),
+            " ",
+            lane.avoidFor ?? "No special exclusion noted for this lane."
+          ] })
         ] }) }, lane.themeKey)) })
       }
     ),
+    /* @__PURE__ */ jsx4(
+      ReferenceSection,
+      {
+        title: "Light, dark, and auto proof",
+        description: "Every official lane must remain usable across explicit light, explicit dark, and OS-controlled auto modes. The dark-public lane is intentionally forced to dark in preview to preserve its contrast contract.",
+        children: /* @__PURE__ */ jsx4(SimpleGrid, { cols: { base: 1, md: 3 }, spacing: "md", children: colorSchemeProof.map((item) => /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "lg", p: "md", children: /* @__PURE__ */ jsxs2(Stack, { gap: 6, children: [
+          /* @__PURE__ */ jsx4(Badge, { variant: "light", color: item.id === "dark" ? "violet" : item.id === "auto" ? "teal" : "blue", w: "fit-content", children: item.label }),
+          /* @__PURE__ */ jsx4(Text2, { size: "sm", children: item.description }),
+          /* @__PURE__ */ jsx4(Text2, { size: "xs", c: "dimmed", children: "Required proof: semantic text, visible focus, and contrast-safe state treatment." })
+        ] }) }, item.id)) })
+      }
+    ),
     /* @__PURE__ */ jsx4(
       ReferenceSection,
       {
         title: "Live Theme Preview",
         description: "Visitors can test the shipped presets, compare lanes, and inspect actual GDS surfaces under each theme.",
         children: /* @__PURE__ */ jsxs2(SimpleGrid, { cols: { base: 1, xl: comparisonEnabled ? 2 : 1 }, spacing: "lg", children: [
-          /* @__PURE__ */ jsx4(GdsProvider, { theme: selectedTheme, defaultColorScheme: colorScheme, children: /* @__PURE__ */ jsx4(ThemePreviewSurface, { preset: selectionSummary, colorScheme }) }, previewKey),
-          comparisonEnabled ? /* @__PURE__ */ jsx4(GdsProvider, { theme: comparedTheme, defaultColorScheme: colorScheme, children: /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "xl", p: "lg", children: /* @__PURE__ */ jsxs2(Stack, { gap: "md", children: [
+          /* @__PURE__ */ jsx4(GdsProvider, { theme: selectedTheme, defaultColorScheme: effectiveColorScheme, children: /* @__PURE__ */ jsx4(
+            ThemePreviewSurface,
+            {
+              preset: selectionSummary,
+              colorScheme: effectiveColorScheme,
+              requestedColorScheme: colorScheme
+            }
+          ) }, previewKey),
+          comparisonEnabled ? /* @__PURE__ */ jsx4(GdsProvider, { theme: comparedTheme, defaultColorScheme: effectiveComparisonScheme, children: /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "xl", p: "lg", children: /* @__PURE__ */ jsxs2(Stack, { gap: "md", children: [
             /* @__PURE__ */ jsxs2(Group2, { justify: "space-between", align: "flex-start", wrap: "wrap", children: [
               /* @__PURE__ */ jsxs2(Stack, { gap: 4, children: [
                 /* @__PURE__ */ jsx4(Text2, { fw: 700, children: "Comparison Preview Surface" }),
@@ -406,7 +479,14 @@ function ReferenceThemeExplorer() {
               ] }),
               /* @__PURE__ */ jsx4(Badge, { color: "violet", variant: "light", children: comparisonSummary.label })
             ] }),
-            /* @__PURE__ */ jsx4(ThemePreviewSurface, { preset: comparisonSummary, colorScheme })
+            /* @__PURE__ */ jsx4(
+              ThemePreviewSurface,
+              {
+                preset: comparisonSummary,
+                colorScheme: effectiveComparisonScheme,
+                requestedColorScheme: colorScheme
+              }
+            )
           ] }) }) }, comparisonPreviewKey) : null
         ] })
       }
@@ -414,18 +494,34 @@ function ReferenceThemeExplorer() {
     /* @__PURE__ */ jsx4(
       ReferenceSection,
       {
-        title: "Creator-Authored Experience Boundary",
-        description: "Creator-authored expression is allowed only through the sanctioned theme helpers and narrow exception process.",
+        title: "Unsupported lane boundary",
+        description: "Unsupported local theme lanes are blocked by policy and compliance because they create parallel design-system authority.",
         tone: "supporting",
-        children: /* @__PURE__ */ jsx4(
-          StateBlock,
-          {
-            variant: "info",
-            title: "Shipped first, custom second",
-            description: "The official site uses shipped presets and the public brand generator first. Product-authored overrides must stay reviewable, testable, and scoped.",
-            compact: true
-          }
-        )
+        children: /* @__PURE__ */ jsxs2(Stack, { gap: "md", children: [
+          /* @__PURE__ */ jsx4(
+            StateBlock,
+            {
+              variant: "permission",
+              title: "Do not create local branding-layer helpers",
+              description: "If a consumer needs brand expression, use createPublicBrandTheme(...). If a lane is missing, request it for GDS instead of building extendGdsTheme(...), createTheme(...), or mergeMantineTheme(...) ownership locally.",
+              compact: true
+            }
+          ),
+          /* @__PURE__ */ jsxs2(SimpleGrid, { cols: { base: 1, md: 2 }, spacing: "md", children: [
+            /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "lg", p: "md", children: /* @__PURE__ */ jsxs2(Stack, { gap: 6, children: [
+              /* @__PURE__ */ jsx4(Text2, { fw: 700, size: "sm", children: "Approved remediation" }),
+              /* @__PURE__ */ jsxs2(Code, { block: true, children: [
+                "createPublicBrandTheme(",
+                `{ flatSurfaces: true, overrides: { primaryColor: 'blue' } }`,
+                ")"
+              ] })
+            ] }) }),
+            /* @__PURE__ */ jsx4(Paper, { withBorder: true, radius: "lg", p: "md", children: /* @__PURE__ */ jsxs2(Stack, { gap: 6, children: [
+              /* @__PURE__ */ jsx4(Text2, { fw: 700, size: "sm", children: "Prohibited ownership" }),
+              /* @__PURE__ */ jsx4(Code, { block: true, children: "extendGdsTheme(...) / createTheme(...) / mergeMantineTheme(...)" })
+            ] }) })
+          ] })
+        ] })
       }
     )
   ] });
@@ -529,18 +625,94 @@ function DiscoveryShell({
   );
 }
 
+// src/DocsShell.tsx
+import { useState as useState3 } from "react";
+import { Box as Box2, Burger as Burger2, Container, Divider, Group as Group4, Stack as Stack2, Text as Text4, Transition } from "@mantine/core";
+import { Fragment, jsx as jsx7, jsxs as jsxs4 } from "react/jsx-runtime";
+function DocsShellSidebar({ primaryNavigation, secondaryNavigation }) {
+  return /* @__PURE__ */ jsxs4(Stack2, { gap: "md", h: "100%", children: [
+    primaryNavigation ? /* @__PURE__ */ jsxs4(Stack2, { gap: "xs", children: [
+      /* @__PURE__ */ jsx7(Text4, { size: "xs", fw: 700, c: "dimmed", children: "Primary" }),
+      primaryNavigation
+    ] }) : null,
+    secondaryNavigation ? /* @__PURE__ */ jsxs4(Fragment, { children: [
+      /* @__PURE__ */ jsx7(Divider, {}),
+      /* @__PURE__ */ jsxs4(Stack2, { gap: "xs", children: [
+        /* @__PURE__ */ jsx7(Text4, { size: "xs", fw: 700, c: "dimmed", children: "More" }),
+        secondaryNavigation
+      ] })
+    ] }) : null
+  ] });
+}
+function resolveContentContainerSize(value) {
+  if (value === "full") {
+    return "100%";
+  }
+  return value ?? "lg";
+}
+function DocsShell({
+  brand,
+  primaryNavigation,
+  secondaryNavigation,
+  headerContext,
+  actions,
+  mobileNavigation,
+  mobileNavigationMode = "drawer",
+  footer,
+  children,
+  contentWidth = "full"
+}) {
+  const [mobileNavOpen, setMobileNavOpen] = useState3(false);
+  return /* @__PURE__ */ jsx7(
+    DiscoveryShell,
+    {
+      header: /* @__PURE__ */ jsxs4(Group4, { h: "100%", justify: "space-between", align: "center", wrap: "nowrap", gap: "md", children: [
+        /* @__PURE__ */ jsxs4(Group4, { gap: "sm", align: "center", wrap: "nowrap", style: { minWidth: 0 }, children: [
+          mobileNavigationMode === "inline-collapse" && mobileNavigation ? /* @__PURE__ */ jsxs4(Fragment, { children: [
+            /* @__PURE__ */ jsx7(
+              Burger2,
+              {
+                opened: mobileNavOpen,
+                onClick: () => setMobileNavOpen((value) => !value),
+                hiddenFrom: "sm",
+                size: "sm",
+                "aria-label": "Toggle docs navigation"
+              }
+            ),
+            /* @__PURE__ */ jsx7(Transition, { mounted: mobileNavOpen, transition: "pop", duration: 120, children: (styles) => /* @__PURE__ */ jsx7(Box2, { style: styles, children: /* @__PURE__ */ jsx7(Box2, { mt: "xs", p: "sm", style: { borderRadius: 8, border: "1px solid var(--mantine-color-default-border)" }, children: mobileNavigation }) }) })
+          ] }) : null,
+          /* @__PURE__ */ jsx7(Box2, { style: { minWidth: 0 }, children: brand }),
+          headerContext ? /* @__PURE__ */ jsx7(Text4, { size: "sm", c: "dimmed", lineClamp: 1, children: headerContext }) : null
+        ] }),
+        /* @__PURE__ */ jsx7(Group4, { gap: "sm", wrap: "nowrap", style: { minWidth: 0 }, children: actions })
+      ] }),
+      sidebar: /* @__PURE__ */ jsx7(
+        DocsShellSidebar,
+        {
+          primaryNavigation,
+          secondaryNavigation
+        }
+      ),
+      footer,
+      mobileNavigationLabel: "Open docs navigation",
+      headerHeight: 72,
+      children: /* @__PURE__ */ jsx7(Container, { size: resolveContentContainerSize(contentWidth), px: "md", py: "lg", w: "100%", children })
+    }
+  );
+}
+
 // src/SidebarNav.tsx
 import { forwardRef } from "react";
-import { Box as Box2, NavLink, Stack as Stack2, Text as Text4, createPolymorphicComponent } from "@mantine/core";
+import { Box as Box3, NavLink, Stack as Stack3, Text as Text5, createPolymorphicComponent } from "@mantine/core";
 import { useGdsTranslation as useGdsTranslation3 } from "@doneisbetter/gds-theme";
-import { jsx as jsx7, jsxs as jsxs4 } from "react/jsx-runtime";
+import { jsx as jsx8, jsxs as jsxs5 } from "react/jsx-runtime";
 function SidebarNav({ children, ariaLabel = "Primary navigation", gap = "md" }) {
-  return /* @__PURE__ */ jsx7(Stack2, { component: "nav", "aria-label": ariaLabel, gap, h: "100%", children });
+  return /* @__PURE__ */ jsx8(Stack3, { component: "nav", "aria-label": ariaLabel, gap, h: "100%", children });
 }
 function SidebarNavSection({ label, children, pushToBottom = false }) {
-  return /* @__PURE__ */ jsxs4(Stack2, { gap: "xs", mt: pushToBottom ? "auto" : void 0, children: [
-    label ? /* @__PURE__ */ jsx7(Text4, { size: "xs", fw: 700, c: "dimmed", children: label }) : null,
-    /* @__PURE__ */ jsx7(Stack2, { gap: 4, children })
+  return /* @__PURE__ */ jsxs5(Stack3, { gap: "xs", mt: pushToBottom ? "auto" : void 0, children: [
+    label ? /* @__PURE__ */ jsx8(Text5, { size: "xs", fw: 700, c: "dimmed", children: label }) : null,
+    /* @__PURE__ */ jsx8(Stack3, { gap: 4, children })
   ] });
 }
 var _SidebarNavItem = forwardRef(
@@ -559,14 +731,14 @@ var _SidebarNavItem = forwardRef(
     const config = action ? resolveSemanticActionConfig(action, vocabularyPacks) : null;
     const Icon = config?.icon;
     const resolvedLabel = label ?? (action ? getSemanticActionLabel(action, t, vocabularyPacks) : void 0);
-    return /* @__PURE__ */ jsx7(
+    return /* @__PURE__ */ jsx8(
       NavLink,
       {
         ref,
         label: resolvedLabel,
         description,
-        leftSection: icon ?? (Icon ? /* @__PURE__ */ jsx7(Icon, { size: "1rem", stroke: 1.5 }) : void 0),
-        rightSection: badge ? /* @__PURE__ */ jsx7(Box2, { children: badge }) : props.rightSection,
+        leftSection: icon ?? (Icon ? /* @__PURE__ */ jsx8(Icon, { size: "1rem", stroke: 1.5 }) : void 0),
+        rightSection: badge ? /* @__PURE__ */ jsx8(Box3, { children: badge }) : props.rightSection,
         "aria-label": ariaLabel ?? (typeof resolvedLabel === "string" ? resolvedLabel : void 0),
         "aria-current": props.active ? "page" : ariaCurrent,
         ...props
@@ -577,11 +749,11 @@ var _SidebarNavItem = forwardRef(
 var SidebarNavItem = createPolymorphicComponent(_SidebarNavItem);
 
 // src/DocsCodeBlock.tsx
-import { useState as useState3 } from "react";
-import { ActionIcon as ActionIcon2, Code as Code2, Group as Group4, Paper as Paper3, Stack as Stack3, Text as Text5 } from "@mantine/core";
-import { jsx as jsx8, jsxs as jsxs5 } from "react/jsx-runtime";
+import { useState as useState4 } from "react";
+import { ActionIcon as ActionIcon2, Code as Code2, Group as Group5, Paper as Paper3, Stack as Stack4, Text as Text6 } from "@mantine/core";
+import { jsx as jsx9, jsxs as jsxs6 } from "react/jsx-runtime";
 function DocsCodeBlock({ code, language, title, withCopy = true }) {
-  const [copied, setCopied] = useState3(false);
+  const [copied, setCopied] = useState4(false);
   const handleCopy = async () => {
     if (!navigator?.clipboard) {
       return;
@@ -590,13 +762,13 @@ function DocsCodeBlock({ code, language, title, withCopy = true }) {
     setCopied(true);
     window.setTimeout(() => setCopied(false), 1200);
   };
-  return /* @__PURE__ */ jsx8(Paper3, { withBorder: true, radius: "lg", p: "md", children: /* @__PURE__ */ jsxs5(Stack3, { gap: "sm", children: [
-    title || withCopy ? /* @__PURE__ */ jsxs5(Group4, { justify: "space-between", align: "center", children: [
-      /* @__PURE__ */ jsxs5(Stack3, { gap: 0, children: [
-        title ? /* @__PURE__ */ jsx8(Text5, { fw: 600, children: title }) : null,
-        language ? /* @__PURE__ */ jsx8(Text5, { size: "xs", c: "dimmed", children: language }) : null
+  return /* @__PURE__ */ jsx9(Paper3, { withBorder: true, radius: "lg", p: "md", children: /* @__PURE__ */ jsxs6(Stack4, { gap: "sm", children: [
+    title || withCopy ? /* @__PURE__ */ jsxs6(Group5, { justify: "space-between", align: "center", children: [
+      /* @__PURE__ */ jsxs6(Stack4, { gap: 0, children: [
+        title ? /* @__PURE__ */ jsx9(Text6, { fw: 600, children: title }) : null,
+        language ? /* @__PURE__ */ jsx9(Text6, { size: "xs", c: "dimmed", children: language }) : null
       ] }),
-      withCopy ? /* @__PURE__ */ jsx8(
+      withCopy ? /* @__PURE__ */ jsx9(
         ActionIcon2,
         {
           variant: "subtle",
@@ -604,18 +776,18 @@ function DocsCodeBlock({ code, language, title, withCopy = true }) {
           onClick: () => {
             void handleCopy();
           },
-          children: /* @__PURE__ */ jsx8(GdsIcons.Copy, { size: "1rem" })
+          children: /* @__PURE__ */ jsx9(GdsIcons.Copy, { size: "1rem" })
         }
       ) : null
     ] }) : null,
-    /* @__PURE__ */ jsx8(Code2, { block: true, children: code })
+    /* @__PURE__ */ jsx9(Code2, { block: true, children: code })
   ] }) });
 }
 
 // src/ShareButtonGroup.tsx
-import { useState as useState4 } from "react";
-import { ActionIcon as ActionIcon3, Button as Button3, Group as Group5, Stack as Stack4, Text as Text6 } from "@mantine/core";
-import { jsx as jsx9, jsxs as jsxs6 } from "react/jsx-runtime";
+import { useState as useState5 } from "react";
+import { ActionIcon as ActionIcon3, Button as Button3, Group as Group6, Stack as Stack5, Text as Text7 } from "@mantine/core";
+import { jsx as jsx10, jsxs as jsxs7 } from "react/jsx-runtime";
 var channelLabels = {
   native: "Share",
   copy: "Copy link",
@@ -650,9 +822,9 @@ function ShareAction({
   const label = channelLabels[channel];
   const Icon = channel === "copy" ? GdsIcons.Copy : channel === "mail" ? GdsIcons.Mail : channel === "message" ? GdsIcons.Message : GdsIcons.Refer;
   if (compact) {
-    return href ? /* @__PURE__ */ jsx9(ActionIcon3, { component: "a", href, target: "_blank", rel: "noreferrer", variant: "subtle", size: "lg", "aria-label": label, children: /* @__PURE__ */ jsx9(Icon, { size: "1rem", stroke: 1.75 }) }) : /* @__PURE__ */ jsx9(ActionIcon3, { variant: "subtle", size: "lg", "aria-label": label, onClick, children: /* @__PURE__ */ jsx9(Icon, { size: "1rem", stroke: 1.75 }) });
+    return href ? /* @__PURE__ */ jsx10(ActionIcon3, { component: "a", href, target: "_blank", rel: "noreferrer", variant: "subtle", size: "lg", "aria-label": label, children: /* @__PURE__ */ jsx10(Icon, { size: "1rem", stroke: 1.75 }) }) : /* @__PURE__ */ jsx10(ActionIcon3, { variant: "subtle", size: "lg", "aria-label": label, onClick, children: /* @__PURE__ */ jsx10(Icon, { size: "1rem", stroke: 1.75 }) });
   }
-  return href ? /* @__PURE__ */ jsx9(Button3, { component: "a", href, target: "_blank", rel: "noreferrer", variant: "default", leftSection: /* @__PURE__ */ jsx9(Icon, { size: "1rem", stroke: 1.75 }), children: label }) : /* @__PURE__ */ jsx9(Button3, { variant: "default", leftSection: /* @__PURE__ */ jsx9(Icon, { size: "1rem", stroke: 1.75 }), onClick, children: label });
+  return href ? /* @__PURE__ */ jsx10(Button3, { component: "a", href, target: "_blank", rel: "noreferrer", variant: "default", leftSection: /* @__PURE__ */ jsx10(Icon, { size: "1rem", stroke: 1.75 }), children: label }) : /* @__PURE__ */ jsx10(Button3, { variant: "default", leftSection: /* @__PURE__ */ jsx10(Icon, { size: "1rem", stroke: 1.75 }), onClick, children: label });
 }
 function ShareButtonGroup({
   url,
@@ -663,8 +835,8 @@ function ShareButtonGroup({
   label = "Share this",
   description
 }) {
-  const [copied, setCopied] = useState4(false);
-  const [shared, setShared] = useState4(false);
+  const [copied, setCopied] = useState5(false);
+  const [shared, setShared] = useState5(false);
   const hrefs = encodeShare(url, title, text);
   async function handleCopy() {
     await navigator.clipboard?.writeText?.(url);
@@ -680,52 +852,67 @@ function ShareButtonGroup({
     }
     await handleCopy();
   }
-  return /* @__PURE__ */ jsxs6(Stack4, { gap: "sm", children: [
-    /* @__PURE__ */ jsxs6(Stack4, { gap: 2, children: [
-      /* @__PURE__ */ jsx9(Text6, { fw: 600, children: label }),
-      description ? /* @__PURE__ */ jsx9(Text6, { size: "sm", c: "dimmed", children: description }) : null
+  return /* @__PURE__ */ jsxs7(Stack5, { gap: "sm", children: [
+    /* @__PURE__ */ jsxs7(Stack5, { gap: 2, children: [
+      /* @__PURE__ */ jsx10(Text7, { fw: 600, children: label }),
+      description ? /* @__PURE__ */ jsx10(Text7, { size: "sm", c: "dimmed", children: description }) : null
     ] }),
-    /* @__PURE__ */ jsx9(Group5, { gap: "sm", wrap: "wrap", children: channels.map((channel) => {
+    /* @__PURE__ */ jsx10(Group6, { gap: "sm", wrap: "wrap", children: channels.map((channel) => {
       if (channel === "copy") {
-        return /* @__PURE__ */ jsx9(ShareAction, { channel, compact, onClick: () => void handleCopy() }, channel);
+        return /* @__PURE__ */ jsx10(ShareAction, { channel, compact, onClick: () => void handleCopy() }, channel);
       }
       if (channel === "native") {
-        return /* @__PURE__ */ jsx9(ShareAction, { channel, compact, onClick: () => void handleNativeShare() }, channel);
+        return /* @__PURE__ */ jsx10(ShareAction, { channel, compact, onClick: () => void handleNativeShare() }, channel);
       }
-      return /* @__PURE__ */ jsx9(ShareAction, { channel, compact, href: hrefs[channel] }, channel);
+      return /* @__PURE__ */ jsx10(ShareAction, { channel, compact, href: hrefs[channel] }, channel);
     }) }),
-    copied ? /* @__PURE__ */ jsx9(Text6, { size: "sm", c: "teal", children: "Link copied." }) : null,
-    shared ? /* @__PURE__ */ jsx9(Text6, { size: "sm", c: "teal", children: "Share sheet opened." }) : null
+    copied ? /* @__PURE__ */ jsx10(Text7, { size: "sm", c: "teal", children: "Link copied." }) : null,
+    shared ? /* @__PURE__ */ jsx10(Text7, { size: "sm", c: "teal", children: "Share sheet opened." }) : null
   ] });
 }
 
 // src/UploadDropzone.tsx
-import { useRef, useState as useState5 } from "react";
-import { Box as Box3, Button as Button4, Group as Group6, Stack as Stack5, Text as Text7 } from "@mantine/core";
-import { jsx as jsx10, jsxs as jsxs7 } from "react/jsx-runtime";
+import { useRef, useState as useState6 } from "react";
+import { Badge as Badge2, Box as Box4, Button as Button4, Group as Group7, Stack as Stack6, Text as Text8 } from "@mantine/core";
+import { jsx as jsx11, jsxs as jsxs8 } from "react/jsx-runtime";
 function UploadDropzone({
   title,
   description,
   onFilesSelected,
   accept,
+  acceptedTypesLabel,
+  maxSizeLabel,
   multiple = true,
   actionLabel = "Choose files",
-  mode = "panel"
+  mode = "panel",
+  state = "idle",
+  selectedFiles = [],
+  error,
+  policyText,
+  retryAction,
+  removeAction,
+  readonly = false
 }) {
   const inputRef = useRef(null);
-  const [dragging, setDragging] = useState5(false);
+  const [dragging, setDragging] = useState6(false);
   const UploadIcon = GdsIcons.Upload;
+  const effectiveState = readonly ? "readonly" : dragging ? "drag-active" : state;
+  const isDisabled = readonly || effectiveState === "upload-pending";
+  const isError = ["upload-failed", "unsupported-type", "too-large"].includes(effectiveState);
   const forwardFiles = (files) => {
-    if (!files?.length || !onFilesSelected) {
+    if (isDisabled || !files?.length || !onFilesSelected) {
       return;
     }
     onFilesSelected(Array.from(files));
   };
-  return /* @__PURE__ */ jsxs7(
-    Box3,
+  return /* @__PURE__ */ jsxs8(
+    Box4,
     {
       onDragOver: (event) => {
         event.preventDefault();
+        if (isDisabled) {
+          return;
+        }
         setDragging(true);
       },
       onDragLeave: () => setDragging(false),
@@ -736,12 +923,13 @@ function UploadDropzone({
       },
       p: mode === "inline" ? "md" : "xl",
       style: {
-        border: `1px dashed var(${dragging ? "--mantine-color-violet-6" : "--mantine-color-default-border"})`,
+        border: `1px dashed var(${effectiveState === "drag-active" ? "--mantine-color-violet-6" : isError ? "--mantine-color-red-6" : "--mantine-color-default-border"})`,
         borderRadius: "var(--mantine-radius-lg)",
-        background: dragging ? "var(--mantine-color-violet-light)" : "transparent"
+        background: effectiveState === "drag-active" ? "var(--mantine-color-violet-light)" : "transparent"
       },
+      "aria-invalid": isError || void 0,
       children: [
-        /* @__PURE__ */ jsx10(
+        /* @__PURE__ */ jsx11(
           "input",
           {
             ref: inputRef,
@@ -749,14 +937,30 @@ function UploadDropzone({
             hidden: true,
             accept,
             multiple,
+            disabled: isDisabled,
             onChange: (event) => forwardFiles(event.currentTarget.files)
           }
         ),
-        /* @__PURE__ */ jsxs7(Stack5, { align: mode === "inline" ? "flex-start" : "center", ta: mode === "inline" ? "left" : "center", gap: "sm", children: [
-          /* @__PURE__ */ jsx10(UploadIcon, { size: "1.5rem" }),
-          /* @__PURE__ */ jsx10(Text7, { fw: 600, children: title }),
-          description ? /* @__PURE__ */ jsx10(Text7, { size: "sm", c: "dimmed", children: description }) : null,
-          /* @__PURE__ */ jsx10(Group6, { children: /* @__PURE__ */ jsx10(Button4, { variant: "light", onClick: () => inputRef.current?.click(), children: actionLabel }) })
+        /* @__PURE__ */ jsxs8(Stack6, { align: mode === "inline" ? "flex-start" : "center", ta: mode === "inline" ? "left" : "center", gap: "sm", children: [
+          /* @__PURE__ */ jsx11(UploadIcon, { size: "1.5rem" }),
+          /* @__PURE__ */ jsx11(Badge2, { variant: "light", color: isError ? "red" : effectiveState === "selected" ? "blue" : effectiveState === "upload-pending" ? "violet" : "gray", children: effectiveState.replace("-", " ") }),
+          /* @__PURE__ */ jsx11(Text8, { fw: 600, children: title }),
+          description ? /* @__PURE__ */ jsx11(Text8, { size: "sm", c: "dimmed", children: description }) : null,
+          acceptedTypesLabel || maxSizeLabel ? /* @__PURE__ */ jsxs8(Group7, { gap: "xs", justify: mode === "inline" ? "flex-start" : "center", children: [
+            acceptedTypesLabel ? /* @__PURE__ */ jsx11(Badge2, { variant: "outline", color: "gray", children: acceptedTypesLabel }) : null,
+            maxSizeLabel ? /* @__PURE__ */ jsx11(Badge2, { variant: "outline", color: "gray", children: maxSizeLabel }) : null
+          ] }) : null,
+          selectedFiles.length ? /* @__PURE__ */ jsxs8(Text8, { size: "sm", children: [
+            "Selected: ",
+            selectedFiles.join(", ")
+          ] }) : null,
+          policyText ? /* @__PURE__ */ jsx11(Text8, { size: "sm", c: isError ? "red.7" : "dimmed", children: policyText }) : null,
+          error ? /* @__PURE__ */ jsx11(Text8, { size: "sm", c: "red.7", role: "alert", children: error }) : null,
+          /* @__PURE__ */ jsxs8(Group7, { children: [
+            /* @__PURE__ */ jsx11(Button4, { variant: "light", onClick: () => inputRef.current?.click(), disabled: isDisabled, children: actionLabel }),
+            retryAction,
+            removeAction
+          ] })
         ] })
       ]
     }
@@ -764,12 +968,13 @@ function UploadDropzone({
 }
 
 // src/AccessRecoveryPanel.tsx
-import { Group as Group7 } from "@mantine/core";
+import { Group as Group8 } from "@mantine/core";
 import { useGdsTranslation as useGdsTranslation4 } from "@doneisbetter/gds-theme";
-import { jsx as jsx11 } from "react/jsx-runtime";
+import { jsx as jsx12 } from "react/jsx-runtime";
 var stateBlockVariantByState = {
   unauthenticated: "permission",
   "expired-session": "info",
+  timeout: "error",
   forbidden: "permission",
   missing: "error",
   unavailable: "error"
@@ -783,6 +988,10 @@ var defaultCopyByState = {
     title: "Session expired",
     description: "Sign in again or retry to continue where you left off."
   },
+  timeout: {
+    title: "Request timed out",
+    description: "The recovery action took too long. Retry or choose a safe destination."
+  },
   forbidden: {
     title: "You do not have access",
     description: "This content is outside your current permissions or scope."
@@ -814,6 +1023,12 @@ function defaultActionsForState(state, {
         secondary: retryAction && signInAction ? retryAction : backAction,
         tertiary: supportAction ?? null
       };
+    case "timeout":
+      return {
+        primary: retryAction ?? backAction,
+        secondary: retryAction && backAction ? backAction : supportAction ?? null,
+        tertiary: retryAction && backAction ? supportAction ?? null : null
+      };
     case "forbidden":
       return { primary: backAction, secondary: supportAction ?? null, tertiary: null };
     case "missing":
@@ -835,7 +1050,7 @@ function ActionGroup({
   if (actions.length === 0) {
     return null;
   }
-  return /* @__PURE__ */ jsx11(Group7, { gap: "sm", justify: "center", wrap: "wrap", children: actions.map((actionConfig, index) => /* @__PURE__ */ jsx11(
+  return /* @__PURE__ */ jsx12(Group8, { gap: "sm", justify: "center", wrap: "wrap", children: actions.map((actionConfig, index) => /* @__PURE__ */ jsx12(
     SemanticButton,
     {
       action: actionConfig.action,
@@ -869,14 +1084,14 @@ function AccessRecoveryPanel({
     onBack,
     supportAction
   });
-  return /* @__PURE__ */ jsx11(
+  return /* @__PURE__ */ jsx12(
     StateBlock,
     {
       variant: stateBlockVariantByState[state],
       compact,
       title: title ?? t(`gds.accessRecovery.${state}.title`, defaultCopy.title),
       description: description ?? t(`gds.accessRecovery.${state}.description`, defaultCopy.description),
-      action: /* @__PURE__ */ jsx11(
+      action: /* @__PURE__ */ jsx12(
         ActionGroup,
         {
           primaryAction: primaryAction ?? defaults.primary,
@@ -895,6 +1110,7 @@ export {
   ReferenceThemeExplorer,
   GameBoardTile,
   DiscoveryShell,
+  DocsShell,
   SidebarNav,
   SidebarNavSection,
   SidebarNavItem,