@doneisbetter/gds-core 2.6.6 → 2.6.7

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

@@ -7,7 +7,7 @@ import {
   StateBlock,
   getSemanticActionLabel,
   resolveSemanticActionConfig
-} from "./chunk-IAP3JU55.mjs";
+} from "./chunk-LH2KMMXT.mjs";
 
 // src/SemanticButton.tsx
 import { useEffect, useState } from "react";
@@ -141,42 +141,60 @@ 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."
   }
 };
 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 +209,8 @@ function ThemePreviewSurface({
           /* @__PURE__ */ jsx4("strong", { children: "Color scheme:" }),
           " ",
           colorScheme
-        ] })
+        ] }),
+        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, {})
     ] }),
@@ -258,8 +277,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");
@@ -354,7 +375,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,7 +409,17 @@ 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)) })
       }
     ),
@@ -397,8 +429,15 @@ function ReferenceThemeExplorer() {
         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 +445,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
         ] })
       }
@@ -529,18 +575,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 +681,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 +699,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 +712,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 +726,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 +772,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 +785,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,29 +802,29 @@ 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 { 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,
@@ -713,7 +835,7 @@ function UploadDropzone({
   mode = "panel"
 }) {
   const inputRef = useRef(null);
-  const [dragging, setDragging] = useState5(false);
+  const [dragging, setDragging] = useState6(false);
   const UploadIcon = GdsIcons.Upload;
   const forwardFiles = (files) => {
     if (!files?.length || !onFilesSelected) {
@@ -721,8 +843,8 @@ function UploadDropzone({
     }
     onFilesSelected(Array.from(files));
   };
-  return /* @__PURE__ */ jsxs7(
-    Box3,
+  return /* @__PURE__ */ jsxs8(
+    Box4,
     {
       onDragOver: (event) => {
         event.preventDefault();
@@ -741,7 +863,7 @@ function UploadDropzone({
         background: dragging ? "var(--mantine-color-violet-light)" : "transparent"
       },
       children: [
-        /* @__PURE__ */ jsx10(
+        /* @__PURE__ */ jsx11(
           "input",
           {
             ref: inputRef,
@@ -752,11 +874,11 @@ function UploadDropzone({
             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(Text8, { fw: 600, children: title }),
+          description ? /* @__PURE__ */ jsx11(Text8, { size: "sm", c: "dimmed", children: description }) : null,
+          /* @__PURE__ */ jsx11(Group7, { children: /* @__PURE__ */ jsx11(Button4, { variant: "light", onClick: () => inputRef.current?.click(), children: actionLabel }) })
         ] })
       ]
     }
@@ -764,9 +886,9 @@ 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",
@@ -835,7 +957,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 +991,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 +1017,7 @@ export {
   ReferenceThemeExplorer,
   GameBoardTile,
   DiscoveryShell,
+  DocsShell,
   SidebarNav,
   SidebarNavSection,
   SidebarNavItem,