@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/dist/catalog.js

@@ -1,316 +1,596 @@
-import { Pane } from './chunk-JRKSK2HX.js';
-import { Toolbar } from './chunk-SYDMYBPG.js';
-import { ToolbarControlGroup } from './chunk-5VTB2BKP.js';
-import { ListHeader } from './chunk-PSKN344N.js';
-import { ListItem } from './chunk-FEAMR7S4.js';
-import { List } from './chunk-J5BFYY7Q.js';
-import { filterDataAttributes } from './chunk-SRSJO5QE.js';
+import { Workbench } from './chunk-PYBBYSZ3.js';
+import { uxReviewCaptureUrl } from './chunk-6C6DLP3W.js';
+export { UX_REVIEW_PROJECT_PATH, loadUxReviewProject, uxReviewCaptureUrl } from './chunk-6C6DLP3W.js';
 
 
-import { LucideIcon } from './chunk-W2FK7ZNY.js';
-import { PanelLeftClose, Waypoints, ExternalLink, Moon, Sun, PanelLeftOpen } from 'lucide';
-import { jsxs, jsx, Fragment } from 'kerfjs/jsx-runtime';
+import { TokenSearchField } from './chunk-MF6ZUUJZ.js';
+import { Row } from './chunk-YQ2AC4E2.js';
+import { ToolbarText } from './chunk-HGV7J4T6.js';
+
+import { PopupMenu } from './chunk-HQZYKJ56.js';
+import { ListHeader } from './chunk-T4WJ5VGP.js';
+import { ListInsetControl } from './chunk-AN5IWMTM.js';
+import { ListInsetText } from './chunk-S4Y3YTAI.js';
+import { ListItem } from './chunk-3GLYIIFR.js';
+
+
+
+import { Text } from './chunk-LL45C7BB.js';
+
+
+
+
+import { ToolbarControlGroup, ToolbarActionLink } from './chunk-QIG4IGUP.js';
+import { Toolbar } from './chunk-CMLPFIC5.js';
+import { List } from './chunk-HZPHCSCS.js';
+
+
+import { ensureSunkenTexture } from './chunk-IKS72C6P.js';
+import { LucideIcon } from './chunk-LOSRXZAH.js';
+
+
+
+import { filterDataAttributes } from './chunk-KH4KEMSP.js';
+import { Contrast, ZapOff, Moon, Sun, X, Waypoints, ExternalLink, Scan } from 'lucide';
+import { jsx, jsxs, Fragment } from 'kerfjs/jsx-runtime';
 
-function findEntry(sections, id) {
-  for (const section of sections) {
-    for (const entry of section.entries) if (entry.id === id) return entry;
-  }
-  return void 0;
-}
-function catalogEntryTags(tags) {
-  if (!tags?.length) return void 0;
-  return /* @__PURE__ */ jsx("span", { class: "kui-catalog__tags", children: tags.map((tag) => /* @__PURE__ */ jsx("span", { class: "kui-catalog__tag", children: tag })) });
-}
 function relatedMenuItems(related, selectAction) {
   const groups = [];
   for (const entry of related)
     if (!groups.includes(entry.group)) groups.push(entry.group);
-  const nodes = [];
+  const items = [];
   groups.forEach((group, index) => {
-    if (index > 0) nodes.push(/* @__PURE__ */ jsx("wa-divider", {}));
-    nodes.push(/* @__PURE__ */ jsx("small", { class: "kui-catalog__related-heading", children: group }));
-    for (const entry of related) {
+    if (index > 0) items.push({ kind: "divider" });
+    items.push({ kind: "heading", label: group });
+    for (const entry of related)
       if (entry.group === group)
-        nodes.push(
-          /* @__PURE__ */ jsx("wa-dropdown-item", { "data-action": selectAction, "data-item-id": entry.id, children: entry.name })
-        );
-    }
+        items.push({
+          label: entry.name,
+          action: selectAction,
+          attributes: { "data-item-id": entry.id }
+        });
   });
-  return nodes;
+  return items;
+}
+function CatalogResourceFooter({
+  name,
+  resources,
+  related,
+  status,
+  selectAction,
+  toolbar
+}) {
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    status ? /* @__PURE__ */ jsx(
+      Row,
+      {
+        hAlign: "space-between",
+        vAlign: "baseline",
+        gap: "xs",
+        wrap: true,
+        textInsets: "trl",
+        children: status
+      }
+    ) : null,
+    /* @__PURE__ */ jsx(
+      Toolbar,
+      {
+        position: "footer",
+        label: `${name} Resources`,
+        density: toolbar?.density,
+        dividerSides: toolbar?.dividerSides,
+        centerAlign: toolbar?.centerAlign,
+        responsive: toolbar?.responsive ?? "stack",
+        responsiveAt: toolbar?.responsiveAt ?? "narrow",
+        safeAreaEdges: toolbar?.safeAreaEdges,
+        leading: resources.length > 0 ? /* @__PURE__ */ jsx(
+          ToolbarControlGroup,
+          {
+            label: `${name} Resources`,
+            content: "mixed",
+            size: "compact",
+            overflow: "wrap",
+            children: resources.map((resource) => /* @__PURE__ */ jsx(
+              ToolbarActionLink,
+              {
+                href: resource.href,
+                label: resource.label,
+                detail: resource.detail,
+                ariaLabel: `${name}: ${resource.label} (opens in new tab)`,
+                external: true,
+                icon: /* @__PURE__ */ jsx(LucideIcon, { icon: ExternalLink, name: "external-link" })
+              }
+            ))
+          }
+        ) : null,
+        trailing: related.length > 0 ? /* @__PURE__ */ jsx(
+          ToolbarControlGroup,
+          {
+            single: true,
+            content: "mixed",
+            nestedDropdown: true,
+            menuInset: "compact",
+            size: "compact",
+            label: "Related Entries",
+            children: /* @__PURE__ */ jsx(
+              PopupMenu,
+              {
+                text: "Components",
+                icon: /* @__PURE__ */ jsx(LucideIcon, { icon: Waypoints, name: "waypoints" }),
+                placement: "top-end",
+                items: relatedMenuItems(related, selectAction),
+                rootAttributes: { "data-catalog-related": "" }
+              }
+            )
+          }
+        ) : null
+      }
+    )
+  ] });
+}
+function CatalogSectionEntries({
+  section,
+  active,
+  selectAction
+}) {
+  return /* @__PURE__ */ jsxs(List, { rootAttributes: { "data-catalog-section": section.category }, children: [
+    /* @__PURE__ */ jsx(ListHeader, { label: section.category }),
+    /* @__PURE__ */ jsx(List, { gap: "2xs", children: section.entries.map((entry) => /* @__PURE__ */ jsx(
+      ListItem,
+      {
+        action: selectAction,
+        itemId: entry.id,
+        label: entry.name,
+        status: entry.tags?.join(" \xB7 "),
+        selected: active === entry.id,
+        title: entry.description,
+        multiline: true,
+        rootAttributes: { "data-catalog-entry-name": entry.name }
+      }
+    )) })
+  ] });
+}
+function CatalogSecondarySections({
+  group,
+  active,
+  selectAction,
+  toggleAction
+}) {
+  const open = !group.collapsible || Boolean(group.expanded);
+  return /* @__PURE__ */ jsxs(
+    List,
+    {
+      dividerSides: "t",
+      controlInsets: "t",
+      rootAttributes: { "data-catalog-secondary-group": group.label },
+      children: [
+        group.collapsible ? /* @__PURE__ */ jsx(
+          ListHeader,
+          {
+            label: group.label,
+            toggle: true,
+            expanded: open,
+            action: toggleAction
+          }
+        ) : /* @__PURE__ */ jsx(ListHeader, { label: group.label }),
+        /* @__PURE__ */ jsx(
+          List,
+          {
+            gap: "m",
+            rootAttributes: {
+              "data-catalog-secondary": "",
+              "data-catalog-secondary-collapsed": String(!open)
+            },
+            children: group.sections.map((section) => /* @__PURE__ */ jsx(
+              CatalogSectionEntries,
+              {
+                section,
+                active,
+                selectAction
+              }
+            ))
+          }
+        )
+      ]
+    }
+  );
+}
+function CatalogSectionList({
+  sections,
+  active,
+  selectAction
+}) {
+  return /* @__PURE__ */ jsx(Fragment, { children: sections.map((section) => /* @__PURE__ */ jsx(
+    CatalogSectionEntries,
+    {
+      section,
+      active,
+      selectAction
+    }
+  )) });
+}
+function CatalogSidebar({
+  brand,
+  sections,
+  active,
+  secondarySections,
+  footer,
+  selectAction,
+  toggleSecondaryAction
+}) {
+  return /* @__PURE__ */ jsx("nav", { "aria-label": `${brand.title} Components`, "data-catalog-sidebar": true, children: /* @__PURE__ */ jsxs(List, { gap: "m", controlInsets: "b", children: [
+    brand.subtitle ? /* @__PURE__ */ jsx(ListInsetText, { sides: "rl", children: /* @__PURE__ */ jsx(Text, { variant: "span", size: "compact", tone: "quiet", children: brand.subtitle }) }) : null,
+    /* @__PURE__ */ jsx(
+      CatalogSectionList,
+      {
+        sections,
+        active,
+        selectAction
+      }
+    ),
+    secondarySections ? /* @__PURE__ */ jsx(
+      CatalogSecondarySections,
+      {
+        group: secondarySections,
+        active,
+        selectAction,
+        toggleAction: toggleSecondaryAction
+      }
+    ) : null,
+    /* @__PURE__ */ jsx(
+      ListInsetText,
+      {
+        sides: "rl",
+        rootAttributes: { "data-catalog-filter-empty": "" },
+        children: /* @__PURE__ */ jsx(Text, { variant: "span", tone: "quiet", children: "No matching items" })
+      }
+    ),
+    footer
+  ] }) });
+}
+var protectedAttributes = /* @__PURE__ */ new Set([
+  "data-catalog-stage",
+  "data-background-style"
+]);
+function CatalogStage({
+  name,
+  content,
+  backgroundStyle = "checkerboard",
+  rootAttributes = {}
+}) {
+  const safeRootAttributes = filterDataAttributes(
+    rootAttributes,
+    protectedAttributes
+  );
+  return /* @__PURE__ */ jsx(
+    "section",
+    {
+      ...safeRootAttributes,
+      class: "kui-catalog__stage",
+      "data-catalog-stage": true,
+      "data-background-style": backgroundStyle,
+      "aria-label": `${name} Preview`,
+      children: /* @__PURE__ */ jsx("div", { class: "kui-catalog__canvas", children: content })
+    }
+  );
+}
+function CatalogUxReviewLink({
+  uxReview: { projectDirectory, name },
+  entry,
+  category
+}) {
+  return /* @__PURE__ */ jsx(
+    ToolbarControlGroup,
+    {
+      appearance: "borderless",
+      single: true,
+      size: "compact",
+      content: "mixed",
+      buttonAppearance: "push",
+      children: /* @__PURE__ */ jsx(
+        ToolbarActionLink,
+        {
+          href: uxReviewCaptureUrl({
+            projectDirectory,
+            title: `${name}: ${entry.name}`,
+            context: `${name} catalog
+Selected ${category}: ${entry.name} (${entry.id})`
+          }),
+          label: "Capture Region",
+          ariaLabel: `Capture ${entry.name} in UX Review`,
+          icon: /* @__PURE__ */ jsx(LucideIcon, { icon: Scan, name: "scan" })
+        }
+      )
+    }
+  );
+}
+function findEntry(sections, id) {
+  for (const section of sections) {
+    for (const entry of section.entries)
+      if (entry.id === id) return { entry, category: section.category };
+  }
+  return void 0;
 }
 function Catalog({
+  id = "kui-catalog",
   brand,
   sections,
   active,
   content,
   collapsed = false,
   theme,
+  increasedContrast,
+  reducedMotion,
+  backgroundControl = false,
   headerActions,
+  settings,
+  settingsCollapsed = false,
+  settingsPanel = {},
+  uxReview,
   secondarySections,
   sidebarFooter,
   status,
-  geometryOverlay,
+  backgroundStyle,
+  stageRootAttributes,
   selectAction = "catalog-select",
   toggleSidebarAction = "catalog-toggle-sidebar",
   toggleThemeAction = "catalog-toggle-theme",
+  toggleContrastAction = "catalog-toggle-contrast",
+  toggleMotionAction = "catalog-toggle-motion",
+  selectBackgroundAction = "catalog-select-background",
   toggleSecondaryAction = "catalog-toggle-secondary",
-  className = ""
+  toggleSettingsAction = "catalog-toggle-settings",
+  headerPlacement = "auto",
+  footerPlacement = "auto",
+  sidebar = {},
+  mainToolbar,
+  footerToolbar,
+  className = "",
+  slot
 }) {
-  const selected = findEntry(sections, active) ?? (secondarySections ? findEntry(secondarySections.sections, active) : void 0);
+  const found = findEntry(sections, active) ?? (secondarySections ? findEntry(secondarySections.sections, active) : void 0);
+  const selected = found?.entry;
   const name = selected?.name ?? "";
   const nextTheme = theme === "dark" ? "light" : "dark";
-  const resources = selected?.resources ?? [];
-  const related = selected?.related ?? [];
-  return /* @__PURE__ */ jsxs(
+  const catalogName = `${brand.title} Catalog`;
+  const displayControls = increasedContrast !== void 0 || reducedMotion !== void 0 || backgroundControl || theme !== void 0;
+  const hasSettings = settings !== void 0 && settings !== null && settings !== false;
+  const settingsTitle = settingsPanel.title ?? "Settings";
+  return /* @__PURE__ */ jsx(
     "main",
     {
       class: `kui-catalog ${className}`.trim(),
       "data-component": "catalog",
       "data-sidebar-collapsed": String(collapsed),
-      "data-geometry-overlay": geometryOverlay === void 0 ? void 0 : String(geometryOverlay),
-      children: [
-        /* @__PURE__ */ jsx(
-          Pane,
-          {
-            element: "aside",
-            className: "kui-catalog__sidebar",
-            label: `${brand.title} catalog`,
-            contentElement: "nav",
-            contentLabel: `${brand.title} components`,
-            separators: ["inline-end"],
-            headerClassName: "kui-catalog__brand",
-            header: /* @__PURE__ */ jsxs(Fragment, { children: [
-              /* @__PURE__ */ jsx(
-                Toolbar,
-                {
-                  label: `${brand.title} catalog header`,
-                  dividerSides: "",
-                  leading: /* @__PURE__ */ jsxs(
-                    ToolbarControlGroup,
-                    {
-                      appearance: "borderless",
-                      className: "kui-catalog__identity",
-                      children: [
-                        brand.logoUrl ? /* @__PURE__ */ jsx("img", { class: "kui-catalog__mark", src: brand.logoUrl, alt: "" }) : /* @__PURE__ */ jsx(Fragment, {}),
-                        /* @__PURE__ */ jsx("h1", { children: brand.title })
-                      ]
-                    }
-                  ),
-                  trailing: /* @__PURE__ */ jsx(ToolbarControlGroup, { appearance: "borderless", single: true, children: /* @__PURE__ */ jsx(
-                    "button",
-                    {
-                      type: "button",
-                      "data-action": toggleSidebarAction,
-                      "aria-label": `Collapse ${brand.title} catalog`,
-                      children: /* @__PURE__ */ jsx(LucideIcon, { icon: PanelLeftClose, name: "panel-left-close" })
-                    }
-                  ) })
-                }
-              ),
-              brand.subtitle ? /* @__PURE__ */ jsx("p", { class: "kui-catalog__subtitle", children: brand.subtitle }) : /* @__PURE__ */ jsx(Fragment, {})
-            ] }),
-            children: /* @__PURE__ */ jsxs(Fragment, { children: [
-              sections.map((section) => /* @__PURE__ */ jsxs("section", { class: "kui-catalog__group", children: [
-                /* @__PURE__ */ jsx(ListHeader, { label: section.category }),
-                /* @__PURE__ */ jsx(List, { className: "kui-catalog__items", children: section.entries.map((entry) => /* @__PURE__ */ jsx(
-                  ListItem,
-                  {
-                    action: selectAction,
-                    itemId: entry.id,
-                    label: entry.name,
-                    trailing: catalogEntryTags(entry.tags),
-                    selected: active === entry.id,
-                    title: entry.description,
-                    multiline: true
-                  }
-                )) })
-              ] })),
-              secondarySections ? /* @__PURE__ */ jsxs("section", { class: "kui-catalog__group kui-catalog__group--secondary", children: [
-                secondarySections.collapsible ? /* @__PURE__ */ jsx(
-                  ListHeader,
+      "data-settings-collapsed": hasSettings ? String(settingsCollapsed) : void 0,
+      slot,
+      children: /* @__PURE__ */ jsx(
+        Workbench,
+        {
+          id,
+          label: catalogName,
+          leftRail: {
+            label: catalogName,
+            size: sidebar.size ?? 288,
+            resizable: sidebar.resizable,
+            separator: sidebar.separator,
+            collapseMotion: sidebar.collapseMotion,
+            presentation: sidebar.presentation,
+            responsiveOverlayAt: sidebar.responsiveOverlayAt,
+            compactOverlay: sidebar.compactOverlay,
+            collapsed,
+            toolbar: {
+              ...sidebar.toolbar,
+              label: `${catalogName} Header`,
+              title: /* @__PURE__ */ jsxs(Fragment, { children: [
+                brand.logoUrl ? /* @__PURE__ */ jsx(
+                  ToolbarControlGroup,
                   {
-                    label: secondarySections.label,
-                    toggle: true,
-                    expanded: Boolean(secondarySections.expanded),
-                    action: toggleSecondaryAction
+                    appearance: "borderless",
+                    content: "avatar",
+                    shape: "rounded",
+                    single: true,
+                    avatarImage: brand.logoUrl,
+                    children: null
                   }
-                ) : /* @__PURE__ */ jsx(ListHeader, { label: secondarySections.label }),
-                !secondarySections.collapsible || secondarySections.expanded ? /* @__PURE__ */ jsx("div", { class: "kui-catalog__secondary", "data-catalog-secondary": true, children: secondarySections.sections.map((section) => /* @__PURE__ */ jsxs("section", { class: "kui-catalog__secondary-group", children: [
-                  /* @__PURE__ */ jsx("h3", { class: "kui-catalog__secondary-heading", children: section.category }),
-                  /* @__PURE__ */ jsx(List, { className: "kui-catalog__items", children: section.entries.map((entry) => /* @__PURE__ */ jsx(
-                    ListItem,
-                    {
-                      action: selectAction,
-                      itemId: entry.id,
-                      label: entry.name,
-                      trailing: catalogEntryTags(entry.tags),
-                      selected: active === entry.id,
-                      title: entry.description,
-                      multiline: true
-                    }
-                  )) })
-                ] })) }) : /* @__PURE__ */ jsx(Fragment, {})
-              ] }) : /* @__PURE__ */ jsx(Fragment, {}),
-              sidebarFooter ?? /* @__PURE__ */ jsx(Fragment, {})
-            ] })
-          }
-        ),
-        /* @__PURE__ */ jsx(
-          Pane,
-          {
-            element: "article",
-            className: "kui-catalog__detail",
-            contentElement: "section",
-            contentLabel: `${name} preview`,
-            contentClassName: "kui-catalog__stage",
-            headerClassName: "kui-catalog__header",
-            header: /* @__PURE__ */ jsxs(Fragment, { children: [
-              /* @__PURE__ */ jsx(
-                Toolbar,
+                ) : null,
+                /* @__PURE__ */ jsx(ToolbarText, { text: brand.title, size: "large", headingLevel: 1 })
+              ] }),
+              toggle: { action: toggleSidebarAction, name: catalogName }
+            },
+            header: /* @__PURE__ */ jsx(ListInsetControl, { sides: "rbl", children: /* @__PURE__ */ jsx(
+              TokenSearchField,
+              {
+                id: `${id}-filter`,
+                label: "Filter Catalog",
+                placeholder: "Filter items or headings",
+                editorAttributes: { "data-catalog-filter": "" },
+                trailingAction: {
+                  icon: /* @__PURE__ */ jsx(LucideIcon, { icon: X, name: "x" }),
+                  label: "Clear Filter",
+                  action: "catalog-clear-filter"
+                }
+              }
+            ) }),
+            content: /* @__PURE__ */ jsx(
+              CatalogSidebar,
+              {
+                brand,
+                sections,
+                active,
+                secondarySections,
+                footer: sidebarFooter,
+                selectAction,
+                toggleSecondaryAction
+              }
+            )
+          },
+          rightRail: hasSettings ? {
+            label: name ? `${name} ${settingsTitle}` : settingsTitle,
+            size: settingsPanel.size ?? 288,
+            resizable: settingsPanel.resizable,
+            separator: settingsPanel.separator,
+            collapseMotion: settingsPanel.collapseMotion,
+            presentation: settingsPanel.presentation,
+            responsiveOverlayAt: settingsPanel.responsiveOverlayAt,
+            compactOverlay: settingsPanel.compactOverlay,
+            collapsed: settingsCollapsed,
+            toolbar: {
+              ...settingsPanel.toolbar,
+              label: `${settingsTitle} Header`,
+              // A peripheral rail beside the xl entry title takes the
+              // default title size, so it never truncates at 288px.
+              title: /* @__PURE__ */ jsx(ToolbarText, { text: settingsTitle, headingLevel: 2 }),
+              toggle: {
+                action: toggleSettingsAction,
+                name: settingsTitle
+              }
+            },
+            content: settings
+          } : void 0,
+          mainToolbar: {
+            ...mainToolbar,
+            label: `${name} Header`,
+            // The entry title stays whole; actions wrap below it when narrow.
+            responsive: mainToolbar?.responsive ?? "wrap",
+            title: /* @__PURE__ */ jsx(ToolbarText, { text: name, size: "xlarge", headingLevel: 2 }),
+            trailing: /* @__PURE__ */ jsxs(Fragment, { children: [
+              headerActions,
+              uxReview && found ? /* @__PURE__ */ jsx(
+                CatalogUxReviewLink,
                 {
-                  label: `${name} header`,
-                  dividerSides: "",
-                  leading: /* @__PURE__ */ jsxs(Fragment, { children: [
-                    collapsed ? /* @__PURE__ */ jsx(ToolbarControlGroup, { appearance: "borderless", single: true, children: /* @__PURE__ */ jsx(
+                  uxReview: { ...uxReview, name: uxReview.name ?? brand.title },
+                  entry: found.entry,
+                  category: found.category
+                }
+              ) : null,
+              displayControls ? /* @__PURE__ */ jsxs(
+                ToolbarControlGroup,
+                {
+                  appearance: "borderless",
+                  content: "mixed",
+                  size: "compact",
+                  overflow: "wrap",
+                  buttonAppearance: "push",
+                  label: "Catalog Display Settings",
+                  children: [
+                    increasedContrast !== void 0 ? /* @__PURE__ */ jsxs(
                       "button",
                       {
                         type: "button",
-                        "data-action": toggleSidebarAction,
-                        "aria-label": `Expand ${brand.title} catalog`,
-                        children: /* @__PURE__ */ jsx(
-                          LucideIcon,
-                          {
-                            icon: PanelLeftOpen,
-                            name: "panel-left-open"
-                          }
-                        )
+                        "data-action": toggleContrastAction,
+                        "aria-pressed": String(increasedContrast),
+                        children: [
+                          /* @__PURE__ */ jsx(LucideIcon, { icon: Contrast, name: "contrast" }),
+                          /* @__PURE__ */ jsx("span", { children: "Contrast" })
+                        ]
                       }
-                    ) }) : /* @__PURE__ */ jsx(Fragment, {}),
-                    /* @__PURE__ */ jsx(
-                      ToolbarControlGroup,
+                    ) : null,
+                    reducedMotion !== void 0 ? /* @__PURE__ */ jsxs(
+                      "button",
                       {
-                        appearance: "borderless",
-                        className: "kui-catalog__title",
-                        children: /* @__PURE__ */ jsx("h2", { children: name })
+                        type: "button",
+                        "data-action": toggleMotionAction,
+                        "aria-pressed": String(reducedMotion),
+                        children: [
+                          /* @__PURE__ */ jsx(LucideIcon, { icon: ZapOff, name: "zap-off" }),
+                          /* @__PURE__ */ jsx("span", { children: "Reduce Motion" })
+                        ]
                       }
-                    )
-                  ] }),
-                  trailing: /* @__PURE__ */ jsxs("div", { class: "kui-catalog__header-actions", children: [
-                    headerActions,
-                    theme ? /* @__PURE__ */ jsx(
-                      ToolbarControlGroup,
+                    ) : null,
+                    backgroundControl ? /* @__PURE__ */ jsx(
+                      PopupMenu,
                       {
-                        className: "kui-catalog__settings",
-                        label: "Catalog display",
-                        children: /* @__PURE__ */ jsxs(
-                          "button",
+                        text: "Background",
+                        rootAttributes: { "data-catalog-background-menu": "" },
+                        items: [
+                          { value: "checkerboard", label: "Checkerboard" },
                           {
-                            type: "button",
-                            "data-action": toggleThemeAction,
-                            "aria-label": `Use ${nextTheme} theme`,
-                            "data-theme-preview": theme,
-                            children: [
-                              nextTheme === "dark" ? /* @__PURE__ */ jsx(LucideIcon, { icon: Moon, name: "moon" }) : /* @__PURE__ */ jsx(LucideIcon, { icon: Sun, name: "sun" }),
-                              /* @__PURE__ */ jsx("span", { children: nextTheme === "dark" ? "Dark" : "Light" })
-                            ]
-                          }
-                        )
+                            value: "vertical-stripes",
+                            label: "Vertical Stripes"
+                          },
+                          { value: "layout-guide", label: "Layout Guide" },
+                          { value: "surface", label: "Surface" },
+                          { value: "sunken", label: "Sunken" }
+                        ].map(({ value, label }) => ({
+                          label,
+                          action: selectBackgroundAction,
+                          checked: (backgroundStyle ?? "checkerboard") === value,
+                          attributes: { "data-background-choice": value }
+                        }))
                       }
-                    ) : /* @__PURE__ */ jsx(Fragment, {})
-                  ] })
-                }
-              ),
-              selected?.description ? /* @__PURE__ */ jsx("p", { class: "kui-catalog__description kui-content-item", children: selected.description }) : /* @__PURE__ */ jsx(Fragment, {})
-            ] }),
-            footerClassName: "kui-catalog__footer",
-            footer: /* @__PURE__ */ jsxs(Fragment, { children: [
-              status ? /* @__PURE__ */ jsx("div", { class: "kui-catalog__status", children: status }) : /* @__PURE__ */ jsx(Fragment, {}),
-              /* @__PURE__ */ jsx(
-                Toolbar,
-                {
-                  label: `${name} resources`,
-                  dividerSides: "",
-                  leading: resources.length > 0 ? /* @__PURE__ */ jsx(
-                    "nav",
-                    {
-                      class: "kui-catalog__resources",
-                      "aria-label": `${name} resources`,
-                      children: /* @__PURE__ */ jsx(
-                        ToolbarControlGroup,
-                        {
-                          className: "kui-catalog__resource-group",
-                          label: `${name} resources`,
-                          children: resources.map((resource) => /* @__PURE__ */ jsxs(
-                            "a",
-                            {
-                              class: "kui-catalog__resource",
-                              href: resource.href,
-                              target: "_blank",
-                              rel: "noopener noreferrer",
-                              "aria-label": `${name}: ${resource.label} (opens in new tab)`,
-                              children: [
-                                /* @__PURE__ */ jsx(
-                                  LucideIcon,
-                                  {
-                                    icon: ExternalLink,
-                                    name: "external-link"
-                                  }
-                                ),
-                                /* @__PURE__ */ jsx("span", { children: resource.label }),
-                                resource.detail ? /* @__PURE__ */ jsx("code", { children: resource.detail }) : /* @__PURE__ */ jsx(Fragment, {})
-                              ]
-                            }
-                          ))
-                        }
-                      )
-                    }
-                  ) : /* @__PURE__ */ jsx(Fragment, {}),
-                  trailing: related.length > 0 ? /* @__PURE__ */ jsx("div", { class: "kui-catalog__related", "data-catalog-related": true, children: /* @__PURE__ */ jsx(
-                    ToolbarControlGroup,
-                    {
-                      single: true,
-                      className: "kui-catalog__related-group",
-                      label: "Related entries",
-                      children: /* @__PURE__ */ jsxs(
-                        "wa-dropdown",
-                        {
-                          class: "kui-catalog__related-menu",
-                          placement: "top-end",
-                          "data-key": `kui-catalog-related-${active}`,
-                          "data-morph-skip-children": true,
-                          children: [
-                            /* @__PURE__ */ jsx("wa-button", { slot: "trigger", appearance: "plain", "with-caret": true, children: /* @__PURE__ */ jsxs("span", { class: "kui-catalog__related-trigger", children: [
-                              /* @__PURE__ */ jsx(LucideIcon, { icon: Waypoints, name: "waypoints" }),
-                              /* @__PURE__ */ jsx("span", { class: "kui-catalog__related-label", children: "Component" })
-                            ] }) }),
-                            relatedMenuItems(related, selectAction)
-                          ]
-                        }
-                      )
-                    }
-                  ) }) : /* @__PURE__ */ jsx(Fragment, {})
-                }
-              )
-            ] }),
-            children: /* @__PURE__ */ jsxs("div", { class: "kui-catalog__canvas", children: [
-              content,
-              geometryOverlay !== void 0 ? /* @__PURE__ */ jsx(
-                "div",
-                {
-                  class: "kui-catalog__geometry-overlay",
-                  "data-catalog-geometry-overlay": true,
-                  "data-morph-skip-children": true,
-                  "aria-hidden": "true"
+                    ) : null,
+                    theme ? /* @__PURE__ */ jsxs(
+                      "button",
+                      {
+                        type: "button",
+                        "data-action": toggleThemeAction,
+                        "aria-label": `Use ${nextTheme === "dark" ? "Dark" : "Light"} Theme`,
+                        "data-theme-preview": theme,
+                        children: [
+                          nextTheme === "dark" ? /* @__PURE__ */ jsx(LucideIcon, { icon: Moon, name: "moon" }) : /* @__PURE__ */ jsx(LucideIcon, { icon: Sun, name: "sun" }),
+                          /* @__PURE__ */ jsx("span", { children: nextTheme === "dark" ? "Dark" : "Light" })
+                        ]
+                      }
+                    ) : null
+                  ]
                 }
-              ) : /* @__PURE__ */ jsx(Fragment, {})
+              ) : null
             ] })
-          }
-        )
-      ]
+          },
+          mainPane: { appearance: "sunken" },
+          mainFooter: /* @__PURE__ */ jsx(
+            CatalogResourceFooter,
+            {
+              name,
+              resources: selected?.resources ?? [],
+              related: selected?.related ?? [],
+              status,
+              selectAction,
+              toolbar: footerToolbar
+            }
+          ),
+          mainHeader: selected?.description ? /* @__PURE__ */ jsx(
+            ListInsetText,
+            {
+              sides: "trbl",
+              rootAttributes: { "data-catalog-description": "" },
+              children: /* @__PURE__ */ jsx(Text, { variant: "span", children: selected.description })
+            }
+          ) : null,
+          mainHeaderPlacement: headerPlacement,
+          mainFooterPlacement: footerPlacement,
+          main: /* @__PURE__ */ jsx(
+            CatalogStage,
+            {
+              name,
+              content,
+              backgroundStyle,
+              rootAttributes: stageRootAttributes
+            }
+          )
+        }
+      )
     }
   );
 }
-var catalogExampleProtectedAttributes = /* @__PURE__ */ new Set([
+var dashedIdent = /^--[\w\-\u0080-\u{10FFFF}]+$/u;
+function viewportStyleOf(viewport) {
+  if (viewport === void 0) return void 0;
+  const declarations = Object.entries(viewport.tokens ?? {}).map(
+    ([name, value]) => `${name}:${value}`
+  );
+  const { anchorName } = viewport;
+  if (anchorName !== void 0) {
+    if (!dashedIdent.test(anchorName))
+      throw new TypeError(
+        `CatalogExample viewport.anchorName must be a CSS dashed-ident such as "--app-shell-main"; received ${JSON.stringify(anchorName)}`
+      );
+    declarations.push(`anchor-name:${anchorName}`);
+  }
+  return declarations.length > 0 ? declarations.join(";") : void 0;
+}
+var protectedAttributes2 = /* @__PURE__ */ new Set([
   "data-catalog-example",
   "data-catalog-example-stack",
   "data-catalog-example-label",
@@ -321,14 +601,39 @@ function CatalogExample({
   label,
   note,
   align = "none",
+  viewport,
+  compactFallback,
   rootAttributes = {},
   className = "",
-  children
+  children,
+  slot
 }) {
   const safeRootAttributes = filterDataAttributes(
     rootAttributes,
-    catalogExampleProtectedAttributes
+    protectedAttributes2
   );
+  const viewportStyle = viewportStyleOf(viewport);
+  if (viewport?.surface === "lowered") ensureSunkenTexture();
+  const specimen = viewport ? /* @__PURE__ */ jsx(
+    "div",
+    {
+      class: "kui-catalog-example__viewport",
+      "data-catalog-example-viewport": true,
+      "data-layout": viewport.layout,
+      "data-width": viewport.width,
+      "data-height": viewport.height,
+      "data-min-height": viewport.minHeight,
+      "data-frame": viewport.frame,
+      "data-surface": viewport.surface,
+      "data-overflow": viewport.overflow,
+      "data-responsive": viewport.responsive,
+      "data-shadow": viewport.shadow ? "true" : void 0,
+      "data-content-width": viewport.contentWidth,
+      "data-content-align": viewport.contentWidth === void 0 ? void 0 : viewport.contentAlign,
+      style: viewportStyle,
+      children
+    }
+  ) : children;
   return /* @__PURE__ */ jsxs(
     "section",
     {
@@ -336,29 +641,51 @@ function CatalogExample({
       class: `kui-catalog-example ${className}`.trim(),
       "data-catalog-example": true,
       "data-align": align,
+      "aria-label": label,
+      slot,
       children: [
         label !== void 0 ? /* @__PURE__ */ jsx(
           ListHeader,
           {
             label,
+            width: "content",
             rootAttributes: { "data-catalog-example-label": "" }
           }
-        ) : /* @__PURE__ */ jsx(Fragment, {}),
-        note !== void 0 ? /* @__PURE__ */ jsx("p", { class: "kui-catalog-example__note", "data-catalog-example-note": true, children: note }) : /* @__PURE__ */ jsx(Fragment, {}),
-        children
+        ) : null,
+        note !== void 0 ? /* @__PURE__ */ jsx(
+          ListInsetText,
+          {
+            sides: "rl",
+            className: "kui-catalog-example__note",
+            rootAttributes: { "data-catalog-example-note": "" },
+            children: /* @__PURE__ */ jsx(Text, { variant: "span", size: "compact", tone: "quiet", children: note })
+          }
+        ) : null,
+        compactFallback !== void 0 ? /* @__PURE__ */ jsx(Text, { tone: "quiet", className: "kui-catalog-example__compact-fallback", children: compactFallback }) : null,
+        specimen
       ]
     }
   );
 }
+var protectedAttributes3 = /* @__PURE__ */ new Set([
+  "data-catalog-example",
+  "data-catalog-example-stack",
+  "data-catalog-example-label",
+  "data-catalog-example-note",
+  "data-align",
+  "data-width"
+]);
 function CatalogExampleStack({
   label,
+  width = "reading",
   rootAttributes = {},
   className = "",
-  children
+  children,
+  slot
 }) {
   const safeRootAttributes = filterDataAttributes(
     rootAttributes,
-    catalogExampleProtectedAttributes
+    protectedAttributes3
   );
   return /* @__PURE__ */ jsx(
     "section",
@@ -366,7 +693,9 @@ function CatalogExampleStack({
       ...safeRootAttributes,
       class: `kui-catalog-example-stack ${className}`.trim(),
       "data-catalog-example-stack": true,
+      "data-width": width === "full" ? "full" : void 0,
       "aria-label": label,
+      slot,
       children
     }
   );