chore: sweep ui fixes

Author: MohamedH1998

.changeset/sweep-ui-fixes.md

@@ -0,0 +1,12 @@
+---
+"@cloudflare/create-nimbus-docs": patch
+---
+
+Fix a batch of UI stress-sweep defects in the starter components:
+
+- **TOC scroll-spy** no longer desyncs when a heading slugs to an empty id (e.g. an emoji-only `## 🎉`). The active-heading index now stays aligned with the full link/rail set instead of a resolvable-only subset, so every section below an unresolvable heading highlights correctly.
+- **Mobile sidebar** hamburger survives client-side navigation — the toggle re-binds on `astro:page-load` and tears down on `astro:before-swap` (via `mount()`), fixing a dead button after the first view transition, with the scroll lock balanced on a mid-open swap.
+- **Dialog** content taller than the cap now scrolls inside the panel (`overflow-y-auto`) so the close button stays reachable.
+- **Banner** long unbroken strings (including the framework deprecation banner's version URL) wrap instead of overflowing.
+- **PackageManagers** blocks with identical props on one page now get unique, incremental-build-stable DOM ids (per-page counter), fixing duplicate `id`/`aria-controls`.
+- Dev-only warnings: `<Steps>` around a bullet list, and duplicate labels within a `<Tabs syncKey>` group.

AGENT.md

@@ -68,6 +68,8 @@ The architecture splits into three tiers, one test per tier:
 
 **When in doubt, default to framework; the starter should grow slowly.**
 
+**The sharper cut — when a test above is ambiguous, or a single file mixes both:** *one correct answer → framework; a user might reasonably want a different answer → their repo.* A scroll-spy's active-heading math has exactly one right answer (framework); the rail's *look* does not (starter). When a `.client.ts` inlines both mechanism and taste, split it at that line — expose the mechanism as a `nimbus-docs/client` primitive and keep the taste in the user file — rather than filing the whole file under one tier. `tabs.client.ts` (thin glue over `initTabs`) is the target shape; a fat, all-mechanism `.client.ts` in the starter is the smell.
+
 ## Derived templates
 
 **Drift discipline: canonical source → generator → orphan branch → tagged.** Hand-edits happen in one place, `packages/nimbus-starter-source/`. The generator (`packages/create-nimbus-docs/scripts/copy-template.mjs`) emits one directory per variant from that source plus the manifest. The CLI tarball carries **no templates**; distribution lives in this repo — the variants live on an orphan `templates` branch (no shared history with `main`), synced and **tagged `templates-v<create-nimbus-docs version>`** by the release job. At scaffold time `create-nimbus-docs` fetches its matching tag via giget (`github:cloudflare/nimbus/<variant>#templates-v<version>`); the tag's tree is templates-only, so the tarball stays small even though the repo also holds all of `main`. A starter edit therefore still produces a diff touching only `packages/nimbus-starter-source/**`; the `templates` branch is sync output, never hand-edited (a branch ruleset rejects human pushes, and `templates-v*` tags are immutable for everyone — including the bot).

CLAUDE.md

@@ -68,6 +68,8 @@ The architecture splits into three tiers, one test per tier:
 
 **When in doubt, default to framework; the starter should grow slowly.**
 
+**The sharper cut — when a test above is ambiguous, or a single file mixes both:** *one correct answer → framework; a user might reasonably want a different answer → their repo.* A scroll-spy's active-heading math has exactly one right answer (framework); the rail's *look* does not (starter). When a `.client.ts` inlines both mechanism and taste, split it at that line — expose the mechanism as a `nimbus-docs/client` primitive and keep the taste in the user file — rather than filing the whole file under one tier. `tabs.client.ts` (thin glue over `initTabs`) is the target shape; a fat, all-mechanism `.client.ts` in the starter is the smell.
+
 ## Derived templates
 
 **Drift discipline: canonical source → generator → orphan branch → tagged.** Hand-edits happen in one place, `packages/nimbus-starter-source/`. The generator (`packages/create-nimbus-docs/scripts/copy-template.mjs`) emits one directory per variant from that source plus the manifest. The CLI tarball carries **no templates**; distribution lives in this repo — the variants live on an orphan `templates` branch (no shared history with `main`), synced and **tagged `templates-v<create-nimbus-docs version>`** by the release job. At scaffold time `create-nimbus-docs` fetches its matching tag via giget (`github:cloudflare/nimbus/<variant>#templates-v<version>`); the tag's tree is templates-only, so the tarball stays small even though the repo also holds all of `main`. A starter edit therefore still produces a diff touching only `packages/nimbus-starter-source/**`; the `templates` branch is sync output, never hand-edited (a branch ruleset rejects human pushes, and `templates-v*` tags are immutable for everyone — including the bot).

apps/www/src/components/ui/banner/Banner.astro

@@ -67,6 +67,7 @@ const safeContent = sanitizeBannerHtml(content);
     background: var(--_t);
   }
 
+  .banner-card-body { min-width: 0; overflow-wrap: break-word; }
   .banner-card-body :global(p) { margin: 0; }
   .banner-card-body :global(p + p) { margin-top: 0.375rem; }
   .banner-card-body :global(a) { text-decoration: underline; text-underline-offset: 2px; }

apps/www/src/components/ui/dialog/DialogContent.astro

@@ -13,7 +13,7 @@ const { class: className, ...attrs } = Astro.props;
 
 <div class="flex items-start justify-center pt-[10vh] px-4 pointer-events-none">
   <div
-    class={cn("pointer-events-auto flex max-h-[70vh] w-full flex-col overflow-hidden rounded-lg bg-muted shadow-lg ring-1 ring-border", className)}
+    class={cn("pointer-events-auto flex max-h-[70vh] w-full flex-col overflow-y-auto rounded-lg bg-muted shadow-lg ring-1 ring-border", className)}
     {...attrs}
   >
     <slot />

apps/www/src/components/ui/embed/Embed.astro

@@ -30,6 +30,24 @@ const {
   class: className,
   ...attrs
 } = Astro.props;
+
+// `title` is typed as required, but MDX doesn't enforce prop types — a missing
+// title would ship a nameless iframe (WCAG 4.1.2). Fall back to an honest
+// host-derived name and warn the author in dev.
+let resolvedTitle = title;
+if (!resolvedTitle) {
+  let host = "";
+  try {
+    host = new URL(src).hostname.replace(/^www\./, "");
+  } catch {}
+  resolvedTitle = host ? `Embedded content from ${host}` : "Embedded content";
+  if (import.meta.env.DEV) {
+    console.warn(
+      `[nimbus] <Embed src="${src}"> has no title; using a fallback accessible ` +
+        "name. Set `title` to describe the embed.",
+    );
+  }
+}
 ---
 
 <div
@@ -38,7 +56,7 @@ const {
 >
   <iframe
     src={src}
-    title={title}
+    title={resolvedTitle}
     loading="lazy"
     allow={allow}
     allowfullscreen={allowfullscreen}

apps/www/src/components/ui/frame/Frame.astro

@@ -92,17 +92,20 @@ const sizes = "(min-width: 768px) 768px, 100vw";
     border-radius: 0.5rem;
   }
 
-  /* Aspect-locked variant — locks the media box to the given ratio and
-     absolutely positions any direct child so it fills (img / video /
-     iframe / svg / div / etc). */
+  /* Aspect-locked variant — locks the media box to the given ratio. `aspect`
+     is single-media by design: only replaced media (img/video/iframe/svg) is
+     filled, so a stray non-media child isn't stretched or stacked. */
   .frame[data-frame-aspect] .frame-media {
     position: relative;
     display: block;
     width: 100%;
     aspect-ratio: var(--frame-aspect);
   }
 
-  .frame[data-frame-aspect] .frame-media > :global(*) {
+  .frame[data-frame-aspect] .frame-media > :global(img),
+  .frame[data-frame-aspect] .frame-media > :global(video),
+  .frame[data-frame-aspect] .frame-media > :global(iframe),
+  .frame[data-frame-aspect] .frame-media > :global(svg) {
     position: absolute;
     inset: 0;
     width: 100%;

apps/www/src/components/ui/package-managers/PackageManagers.astro

@@ -17,15 +17,23 @@ interface Props extends CommandOptions {
 
 const { pkg, type = "add", args, dev, comment } = Astro.props;
 const tabs = getTabs(type, pkg, { args, dev, comment });
-// Deterministic ID — hash the props so two builds with identical content
-// produce identical IDs. Required for incremental builds: a per-render
-// `crypto.randomUUID()` would make warm output differ from cold.
+// Prop hash + a per-page counter (on Astro.locals) so two blocks with
+// identical props still get distinct ids. Counter order is stable within a
+// render, so incremental/warm builds match cold — unlike crypto.randomUUID().
+const localsAny = Astro.locals as Record<string, unknown>;
+const counters =
+  (localsAny.__nbCounters as Map<string, number>) ??
+  (localsAny.__nbCounters = new Map<string, number>());
+const n = (counters.get("package-managers") ?? 0) + 1;
+counters.set("package-managers", n);
 const uid =
   "pm-" +
   createHash("sha256")
     .update(JSON.stringify({ pkg, type, args, dev, comment }))
     .digest("hex")
-    .slice(0, 12);
+    .slice(0, 12) +
+  "-" +
+  n.toString(16).padStart(4, "0");
 ---
 
 <script is:inline>

apps/www/src/components/ui/popover/PopoverContent.astro

@@ -34,5 +34,10 @@ const { placement = "bottom-start", class: className, ...attrs } = Astro.props;
     position: fixed;
     margin: 0;
     inset: auto;
+    /* Never exceed the viewport (16px = 2× the anchor's 8px pad, absorbing
+       the scrollbar width); overflow scrolls inside the panel. */
+    max-width: calc(100vw - 16px);
+    max-height: calc(100vh - 16px);
+    overflow: auto;
   }
 </style>

apps/www/src/components/ui/steps/steps.client.ts

@@ -10,6 +10,18 @@ import { mount } from "@cloudflare/nimbus-docs/client";
 
 function initSteps(root: HTMLElement): () => void {
   const lists = root.querySelectorAll<HTMLOListElement>("ol");
+  if (
+    import.meta.env.DEV &&
+    lists.length === 0 &&
+    root.querySelector("[data-step]") === null &&
+    root.children.length > 0
+  ) {
+    console.warn(
+      "[nimbus] <Steps> expects an ordered list (`1.` items) or <Step> " +
+        "children. A bullet list renders with no numbers or connectors — " +
+        "use an ordered list.",
+    );
+  }
   lists.forEach((ol) => ol.setAttribute("role", "list"));
 
   return () => {