@dogsbay/ui 0.2.0-beta.12 → 0.2.0-beta.120

package/src/sidebar/SidebarNavTree.astro

@@ -1,4 +1,5 @@
 ---
+import SidebarNavMark from "./SidebarNavMark.astro";
 /**
  * Recursive sidebar navigation tree.
  * Renders a data-driven tree with native <details>/<summary> for zero-JS expand/collapse.
@@ -8,11 +9,18 @@
  *   <SidebarNavTree items={navItems} currentPath={Astro.url.pathname} />
  */
 
+interface NavMark {
+  kind: "added" | "changed" | "removed" | "moved";
+  label?: string;
+  subtree?: boolean;
+}
+
 interface NavItem {
   label: string;
   href?: string;
   icon?: string;         // Raw SVG string (rendered via set:html)
   children?: NavItem[];
+  mark?: NavMark;
 }
 
 interface Props {
@@ -24,6 +32,13 @@ interface Props {
 
 const { items, currentPath, level = 0, class: className } = Astro.props;
 
+/**
+ * Markers are rendered by SidebarNavMark, which owns the accessibility
+ * contract (distinct glyph so colour is never the sole channel,
+ * visually-hidden text so the row announces "MySQL, changed",
+ * forced-colors survival). See that component.
+ */
+
 const normalizedPath = currentPath.replace(/\/$/, "") || "/";
 
 function isActive(href: string) {
@@ -54,24 +69,78 @@ const paddingLeft = `${8 + level * 12}px`;
     const active = item.href ? isActive(item.href) : false;
     const hasChildren = item.children && item.children.length > 0;
     const shouldOpen = hasChildren && hasActiveDescendant(item);
+    const open = shouldOpen || active;
+    // A branch that is ALSO a page (has an href) is a section landing
+    // page; it uses the button-driven disclosure below and needs a
+    // stable id linking its toggle button to its submenu.
+    const submenuId = item.href
+      ? `nav-sub-${item.href.replace(/[^a-z0-9]+/gi, "-")}-${level}`
+      : undefined;
 
     return (
       <li data-sidebar="nav-tree-item">
-        {hasChildren ? (
+        {hasChildren && item.href ? (
+          /*
+            Section landing page: APG "disclosure navigation" pattern — a
+            real link (navigates) + a SEPARATE toggle <button> (expands),
+            as siblings. Nesting a focusable <a> inside the interactive
+            <summary> is an axe `nested-interactive` violation, and native
+            <details> can't show a header link when collapsed without that
+            nesting. Progressive enhancement: the submenu's server state
+            (hidden unless open) is correct with no JS — the link still
+            works and the active section is expanded — and the inline
+            script wires the toggle button when JS is available.
+          */
+          <Fragment>
+            <div
+              class:list={[
+                "flex w-full min-w-0 items-center gap-2 rounded-md text-sm text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-accent-foreground",
+                level === 0 ? "h-8" : "h-7",
+                active && "bg-sidebar-accent font-medium text-sidebar-accent-foreground",
+              ]}
+              style={`padding-left: ${paddingLeft};`}
+            >
+              <button
+                type="button"
+                data-nav-toggle
+                aria-controls={submenuId}
+                aria-expanded={open ? "true" : "false"}
+                aria-label={`Toggle ${item.label} section`}
+                class="shrink-0 rounded outline-none ring-sidebar-ring focus-visible:ring-2"
+              >
+                <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6" /></svg>
+              </button>
+              {item.icon && <span class="shrink-0 [&>svg]:size-4" set:html={item.icon} />}
+              <a
+                href={item.href}
+                class="min-w-0 flex-1 truncate text-inherit no-underline outline-none ring-sidebar-ring focus-visible:ring-2"
+                data-nav-href={item.href}
+                data-active={active || undefined}
+                data-nav-mark-row={item.mark?.subtree ? undefined : item.mark?.kind}
+              >{item.label}</a>
+              {item.mark && (
+                <SidebarNavMark kind={item.mark.kind} label={item.mark.label} subtree={item.mark.subtree} />
+              )}
+            </div>
+            <div id={submenuId} data-nav-submenu hidden={!open}>
+              <Astro.self items={item.children!} currentPath={currentPath} level={level + 1} />
+            </div>
+          </Fragment>
+        ) : hasChildren ? (
           <details open={shouldOpen || active}>
             <summary
               class:list={[
                 "flex w-full min-w-0 cursor-pointer items-center gap-2 rounded-md text-sm text-sidebar-foreground outline-none [list-style:none] ring-sidebar-ring hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 [&::-webkit-details-marker]:hidden",
                 level === 0 ? "h-8" : "h-7",
-                active && "bg-sidebar-accent font-medium text-sidebar-accent-foreground",
               ]}
               style={`padding-left: ${paddingLeft};`}
-              data-nav-href={item.href || undefined}
-              data-active={active || undefined}
             >
               <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 transition-transform duration-200" data-chevron aria-hidden="true"><polyline points="9 18 15 12 9 6" /></svg>
               {item.icon && <span class="shrink-0 [&>svg]:size-4" set:html={item.icon} />}
-              <span class="truncate">{item.label}</span>
+              <span class="min-w-0 flex-1 truncate">{item.label}</span>
+              {item.mark && (
+                <SidebarNavMark kind={item.mark.kind} label={item.mark.label} subtree={item.mark.subtree} />
+              )}
             </summary>
             <Astro.self items={item.children!} currentPath={currentPath} level={level + 1} />
           </details>
@@ -86,12 +155,22 @@ const paddingLeft = `${8 + level * 12}px`;
             style={`padding-left: ${paddingLeft};`}
             data-active={active || undefined}
             data-nav-href={item.href}
+            {/*
+              A SUBTREE mark is a claim about descendants, never about
+              this row — striking through a surviving group because one
+              child was deleted tells the reader the whole section is
+              gone (code review, 2026-07-13).
+            */}
+            data-nav-mark-row={item.mark?.subtree ? undefined : item.mark?.kind}
           >
             {/* Spacer to align with chevron in branch items */}
             <span class="size-4 shrink-0" />
             {/* Icon (level 0 only) */}
             {item.icon && <span class="shrink-0 [&>svg]:size-4" set:html={item.icon} />}
-            <span class="truncate">{item.label}</span>
+            <span class="min-w-0 flex-1 truncate">{item.label}</span>
+            {item.mark && (
+              <SidebarNavMark kind={item.mark.kind} label={item.mark.label} subtree={item.mark.subtree} />
+            )}
           </a>
         )}
       </li>
@@ -100,7 +179,32 @@ const paddingLeft = `${8 + level * 12}px`;
 </ul>
 
 <style is:global>
-  details[open] > summary [data-chevron] {
+  details[open] > summary [data-chevron],
+  [data-nav-toggle][aria-expanded="true"] [data-chevron] {
     transform: rotate(90deg);
   }
 </style>
+
+<script>
+  // Wire the section-landing disclosure toggles (APG disclosure-nav).
+  // The link navigates on its own; this button just expands/collapses
+  // the sibling submenu. Server-rendered state is already correct, so
+  // with no JS the link still works and the active section is open.
+  // Idempotent + re-run after view transitions.
+  function wireNavToggles() {
+    document
+      .querySelectorAll<HTMLButtonElement>("[data-nav-toggle]:not([data-wired])")
+      .forEach((btn) => {
+        btn.dataset.wired = "1";
+        const id = btn.getAttribute("aria-controls");
+        const submenu = id ? document.getElementById(id) : null;
+        btn.addEventListener("click", () => {
+          const isOpen = btn.getAttribute("aria-expanded") === "true";
+          btn.setAttribute("aria-expanded", String(!isOpen));
+          if (submenu) submenu.hidden = isOpen;
+        });
+      });
+  }
+  wireNavToggles();
+  document.addEventListener("astro:page-load", wireNavToggles);
+</script>

package/src/sidebar/sidebar.ts

@@ -202,7 +202,7 @@ function openMobile(provider: HTMLElement) {
   }
 
   // Lock scroll
-  ScrollLock.lock();
+  ScrollLock.activate();
 
   // Focus first focusable element in sidebar
   requestAnimationFrame(() => {
@@ -237,7 +237,7 @@ function closeMobile(provider: HTMLElement) {
   }
 
   // Unlock scroll
-  ScrollLock.unlock();
+  ScrollLock.deactivate();
 
   // Return focus to trigger
   const trigger = instance.provider.querySelector(

package/src/table/Table.astro

@@ -6,19 +6,33 @@ const tableContainer = tv({
 });
 
 const table = tv({
-  base: "w-full caption-bottom text-sm",
+  base: "w-full caption-top text-sm",
 });
 
 interface Props {
   class?: string;
+  /**
+   * Optional table caption, rendered as a `<caption>`: the table's title,
+   * above it and left-aligned.
+   * For a caption with markup, use the `caption` slot instead.
+   */
+  caption?: string;
   [key: string]: unknown;
 }
 
-const { class: className, ...rest } = Astro.props;
+const { class: className, caption, ...rest } = Astro.props;
+
+// A table's caption is its title: above the table, left-aligned, in the body color
+const captionClass = "mb-2 text-left text-sm font-medium text-foreground";
 ---
 
 <div class={tableContainer()}>
   <table class={table({ class: className })} {...rest}>
+    {Astro.slots.has("caption") ? (
+      <caption class={captionClass}><slot name="caption" /></caption>
+    ) : (
+      caption && <caption class={captionClass}>{caption}</caption>
+    )}
     <slot />
   </table>
 </div>

package/src/table/TableCell.astro

@@ -2,7 +2,7 @@
 import { tv } from "tailwind-variants";
 
 const tableCell = tv({
-  base: "p-2 align-middle whitespace-nowrap [&:has([role=checkbox])]:pr-0",
+  base: "p-2 align-top [&:has([role=checkbox])]:pr-0",
 });
 
 interface Props {

package/src/table/TableHead.astro

@@ -2,7 +2,7 @@
 import { tv } from "tailwind-variants";
 
 const tableHead = tv({
-  base: "h-10 px-2 text-left align-middle font-semibold text-muted-foreground whitespace-nowrap [&:has([role=checkbox])]:pr-0",
+  base: "px-2 py-2 text-left align-bottom font-semibold text-muted-foreground [&:has([role=checkbox])]:pr-0",
 });
 
 interface Props {

package/src/toc/TableOfContents.astro

@@ -99,40 +99,40 @@ const filtered = headings.filter(
     line-height: 1.4;
   }
   .toc-kind-class {
-    background-color: oklch(0.55 0.18 265 / 0.15);
-    color: oklch(0.55 0.18 265);
+    background-color: oklch(0.44 0.18 265 / 0.15);
+    color: oklch(0.44 0.18 265);
   }
   :global(.dark) .toc-kind-class {
     background-color: oklch(0.7 0.15 265 / 0.2);
     color: oklch(0.7 0.15 265);
   }
   .toc-kind-meth {
-    background-color: oklch(0.55 0.15 155 / 0.15);
-    color: oklch(0.55 0.15 155);
+    background-color: oklch(0.44 0.15 155 / 0.15);
+    color: oklch(0.44 0.15 155);
   }
   :global(.dark) .toc-kind-meth {
     background-color: oklch(0.7 0.15 155 / 0.2);
     color: oklch(0.7 0.15 155);
   }
   .toc-kind-attr {
-    background-color: oklch(0.6 0.15 55 / 0.15);
-    color: oklch(0.6 0.15 55);
+    background-color: oklch(0.44 0.15 55 / 0.15);
+    color: oklch(0.44 0.15 55);
   }
   :global(.dark) .toc-kind-attr {
     background-color: oklch(0.75 0.15 55 / 0.2);
     color: oklch(0.75 0.15 55);
   }
   .toc-kind-func {
-    background-color: oklch(0.55 0.18 330 / 0.15);
-    color: oklch(0.55 0.18 330);
+    background-color: oklch(0.44 0.18 330 / 0.15);
+    color: oklch(0.44 0.18 330);
   }
   :global(.dark) .toc-kind-func {
     background-color: oklch(0.7 0.15 330 / 0.2);
     color: oklch(0.7 0.15 330);
   }
   .toc-kind-module {
-    background-color: oklch(0.5 0.12 200 / 0.15);
-    color: oklch(0.5 0.12 200);
+    background-color: oklch(0.44 0.12 200 / 0.15);
+    color: oklch(0.44 0.12 200);
   }
   :global(.dark) .toc-kind-module {
     background-color: oklch(0.65 0.12 200 / 0.2);