@takazudo/zudo-doc 5.9.0 → 5.11.0

package/dist/theme-packs/sakura/pack.css

@@ -250,6 +250,12 @@ html[data-theme-pack="sakura"] #desktop-sidebar a,
 html[data-theme-pack="sakura"] aside[data-zd-mobile-sidebar] a {
   border-radius: 9999px;
 }
+/* Non-pill current rows stay square in both sidebar surfaces; the
+   data-nav-active rule below owns Sakura's nested petal shape. */
+html[data-theme-pack="sakura"] #desktop-sidebar a[aria-current="page"]:not([data-nav-active]),
+html[data-theme-pack="sakura"] aside[data-zd-mobile-sidebar] a[aria-current="page"]:not([data-nav-active]) {
+  border-radius: 0;
+}
 html[data-theme-pack="sakura"] #desktop-sidebar a:not([data-nav-active]):hover,
 html[data-theme-pack="sakura"] aside[data-zd-mobile-sidebar] a:not([data-nav-active]):hover {
   text-decoration: none;

package/dist/theme-packs/scandi/pack.css

@@ -2,7 +2,7 @@
    Scandi — zudo-doc theme pack (ADR docs/adr/theme-packs.md)
 
    Hygge minimalism: an oat/ecru room with sage and clay accents,
-   pill-shaped nav actives, an even 8px radius discipline, and a
+   pill-shaped nested nav actives, an even 8px radius discipline, and a
    linen-subtle weave on the page body (two cheap repeating
    gradients at ~2% ink — text backdrops stay effectively solid).
    Light = a Scandinavian interior at midday; dark = hygge night —
@@ -180,12 +180,12 @@ html[data-theme-pack="scandi"] aside[data-zd-mobile-sidebar] a:hover:not([data-n
   background: color-mix(in srgb, var(--zd-accent) 10%, transparent);
   color: var(--zd-accent-hover);
 }
-/* root-level actives carry aria-current="page" but not
-   data-nav-active — round their default ink fill to the 8px
-   discipline so no squared default remnant survives. */
-html[data-theme-pack="scandi"] #desktop-sidebar a[aria-current="page"],
-html[data-theme-pack="scandi"] aside[data-zd-mobile-sidebar] a[aria-current="page"] {
-  border-radius: 8px;
+/* Non-pill current rows keep the structural full-width band square in
+   both sidebar surfaces. The data-nav-active rule below owns the flat
+   nested pill. */
+html[data-theme-pack="scandi"] #desktop-sidebar a[aria-current="page"]:not([data-nav-active]),
+html[data-theme-pack="scandi"] aside[data-zd-mobile-sidebar] a[aria-current="page"]:not([data-nav-active]) {
+  border-radius: 0;
 }
 /* active leaf item: THE signature — a full pill in deep sage
    (candle amber at night), oat text, flat as painted wood. Fill

package/dist/theme-packs/timberline/pack.css

@@ -243,6 +243,11 @@ html[data-theme-pack="timberline"] #desktop-sidebar a {
     background-color 0.15s ease,
     color 0.15s ease;
 }
+/* Keep the structural current-row plank square; data-nav-active is the
+   explicit hook for Timberline's nested chamfer. */
+html[data-theme-pack="timberline"] #desktop-sidebar a[aria-current="page"]:not([data-nav-active]) {
+  border-radius: 0;
+}
 html[data-theme-pack="timberline"] #desktop-sidebar a:hover:not([data-nav-active]):not([aria-current="page"]) {
   color: var(--zd-accent);
   text-decoration: none;

package/eject/doc-pager/index.tsx

@@ -12,11 +12,18 @@ import { ChevronLeft, ChevronRight } from "../icons/index.js";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
+import { formatDate } from "../format-date/index.js";
 
 // NavNode is a superset; we only need the fields the pager uses.
 interface PagerNode {
   href?: string;
   label: string;
+  shape?: "note-tray";
+  noteTrayDated?: boolean;
+  noteTraySidebar?: "index" | "year" | "month";
+  date?: string;
+  updated?: string;
+  rank?: number;
 }
 
 export interface DocPagerProps {
@@ -63,6 +70,7 @@ export function createDocPager<S extends Settings = Settings>(
             <p class="text-small font-semibold underline group-hover:text-accent">
               {prev.label}
             </p>
+            {prev.date && <p class="text-caption text-muted">{formatDate(prev.date, locale)}</p>}
           </a>
         ) : (
           <div />
@@ -79,6 +87,7 @@ export function createDocPager<S extends Settings = Settings>(
             <p class="text-small font-semibold underline group-hover:text-accent">
               {next.label}
             </p>
+            {next.date && <p class="text-caption text-muted">{formatDate(next.date, locale)}</p>}
           </a>
         ) : (
           <div />

package/eject/header/header.tsx

@@ -282,7 +282,14 @@ export function Header(props: HeaderProps): JSX.Element {
 
   const isNonDefaultLocale = lang != null && lang !== i18n.defaultLocale;
   const pathWithoutBase = urlHelpers.stripBase(currentPath);
-  const matchPath = pathForMatch(pathWithoutBase, lang, i18n.defaultLocale);
+  // `navHref` adds the active version prefix to rendered links, but the
+  // configured header paths are intentionally unversioned. Remove the
+  // version segment before locale normalization so SSR active state agrees
+  // with those configured paths on archived pages too. Keep this local to
+  // the renderer: `nav-active.ts` is embedded verbatim in the frozen
+  // overflow script and must remain unchanged.
+  const pathWithoutVersion = stripCurrentVersionPrefix(pathWithoutBase, currentVersion);
+  const matchPath = pathForMatch(pathWithoutVersion, lang, i18n.defaultLocale);
 
   const activeNavPath = computeActiveNavPath(headerNav, matchPath);
   const rightItemDispatch = createRightItemDispatch(headerRightComponents);
@@ -542,6 +549,24 @@ function renderNavItem(
   );
 }
 
+/**
+ * Remove the active `/v/{version}` route prefix from a pathname.
+ *
+ * Version slugs are a path segment, so `/v/1.0` must not strip a path such as
+ * `/v/1.01/...`. The equality branch also keeps the route root normalized to
+ * `/` instead of returning an empty string. This helper deliberately lives in
+ * `header.tsx`; `nav-active.ts` is copied into the CSP-hash-pinned overflow
+ * script and is not part of the SSR-only version normalization seam.
+ */
+function stripCurrentVersionPrefix(path: string, currentVersion?: string): string {
+  if (currentVersion == null || currentVersion === "") return path;
+
+  const prefix = `/v/${currentVersion}`;
+  if (path === prefix) return "/";
+  if (path.startsWith(`${prefix}/`)) return path.slice(prefix.length);
+  return path;
+}
+
 type RightItemContext = Omit<HeaderRightComponentProps, "item" | "index">;
 
 /**

package/eject/sidebar/types.ts

@@ -35,6 +35,12 @@ export interface SidebarNavNode {
   children: SidebarNavNode[];
   sortOrder?: "asc" | "desc";
   collapsed?: boolean;
+  shape?: "note-tray";
+  noteTrayDated?: boolean;
+  noteTraySidebar?: "index" | "year" | "month";
+  date?: string;
+  updated?: string;
+  rank?: number;
 }
 
 /**

package/eject/sidebar-tree-island/index.tsx

@@ -20,6 +20,14 @@ import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
 import { CURRENT_PATH_DATASET_KEY, readCurrentPath } from "../current-path/index.js";
 import { ensureSidebarScrollPreserve } from "./sidebar-scroll-preserve.js";
+import {
+  formatYearMonthLabel,
+  getNoteTrayItems,
+  groupItems,
+  rankWidth,
+  type NoteTrayGroup,
+} from "../note-tray-model/index.js";
+import { formatMonthDay } from "../format-date/index.js";
 
 // The persisted aside can transiently tear down and re-mount its SidebarTree
 // effect during a body swap. Keep navigation snapshot ownership at browser
@@ -36,6 +44,7 @@ function ToggleChevron({ isExpanded, className }: { isExpanded: boolean; classNa
 }
 
 const STORAGE_KEY = "zd-sidebar-open";
+const GROUPED_TRAY_ITEM_DEPTH = 3;
 
 function padLeft(depth: number, forCategory: boolean): string {
   if (depth === 0) return `calc(${BASE_PAD} + ${forCategory ? "0.15rem" : "0rem"})`;
@@ -235,6 +244,12 @@ export function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, ba
     [localeLinks, themeDefaultMode],
   );
 
+  const noteTrayRoot = nodes.length === 1 && nodes[0]?.shape === "note-tray" ? nodes[0] : undefined;
+  const filteredNoteTrayRoot = noteTrayRoot
+    ? filteredNodes.find((node) => node.slug === noteTrayRoot.slug)
+    : undefined;
+  const locale = localeLinks?.find((link) => link.active)?.code ?? "en";
+
   // Root menu view: show headerNav items as a simple list (Docusaurus-style)
   if (showingRootMenu && rootMenuItems) {
     return (
@@ -293,18 +308,238 @@ export function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, ba
           />
         </div>
       </div>
-      <NodeList
-        nodes={filteredNodes}
-        currentSlug={activeSlug}
-        depth={0}
-        forceOpen={!!query}
-      />
+      {noteTrayRoot ? (
+        filteredNoteTrayRoot && (
+          <TrayList
+            tray={filteredNoteTrayRoot}
+            itemCount={getNoteTrayItems(noteTrayRoot).length}
+            currentSlug={activeSlug}
+            forceOpen={!!query}
+            locale={locale}
+          />
+        )
+      ) : (
+        <NodeList
+          nodes={filteredNodes}
+          currentSlug={activeSlug}
+          depth={0}
+          forceOpen={!!query}
+        />
+      )}
       {footer}
     </nav>
   );
 }
 SidebarTree.displayName = "SidebarTree";
 
+function TrayList({
+  tray,
+  itemCount,
+  currentSlug,
+  forceOpen,
+  locale,
+}: {
+  tray: SidebarNavNode;
+  itemCount: number;
+  currentSlug?: string;
+  forceOpen: boolean;
+  locale: string;
+}) {
+  const items = getNoteTrayItems(tray);
+  const sidebarStyle = tray.noteTraySidebar ?? "index";
+  const width = rankWidth(itemCount);
+
+  return (
+    <>
+      <LeafNode node={tray} currentSlug={currentSlug} depth={0} isLast={items.length === 0} />
+      {sidebarStyle === "index" ? (
+        items.map((item, index) => (
+          <TrayItem
+            key={item.slug}
+            item={item}
+            currentSlug={currentSlug}
+            rankDigits={width}
+            isLast={index === items.length - 1}
+          />
+        ))
+      ) : (
+        groupItems(items, sidebarStyle, tray.sortOrder ?? "asc").map((group, index, groups) => (
+          <TrayGroupNode
+            key={group.key}
+            traySlug={tray.slug}
+            group={group}
+            grouping={sidebarStyle}
+            locale={locale}
+            currentSlug={currentSlug}
+            forceOpen={forceOpen}
+            isLast={index === groups.length - 1}
+          />
+        ))
+      )}
+    </>
+  );
+}
+
+function TrayItem({
+  item,
+  currentSlug,
+  rankDigits,
+  isLast,
+  showDate = false,
+  depth = 1,
+}: {
+  item: SidebarNavNode;
+  currentSlug?: string;
+  rankDigits?: number;
+  isLast: boolean;
+  showDate?: boolean;
+  depth?: number;
+}) {
+  if (!item.href) return null;
+  const isActive = item.slug === currentSlug;
+  const labelHtml = smartBreakToHtml(item.label);
+  const shortDate = item.date ? formatMonthDay(item.date) : undefined;
+
+  return (
+    <div className={isLast ? "pb-vsp-md" : ""}>
+      <div className="relative">
+        <ConnectorLines depth={depth} isLast={isLast} topPad="var(--spacing-vsp-2xs)" />
+        <a
+          href={item.href}
+          aria-current={isActive ? "page" : undefined}
+          data-nav-active={isActive ? "" : undefined}
+          className={`flex items-start gap-hsp-xs py-vsp-2xs pr-[4px] text-small break-words ${
+            isActive
+              ? "bg-fg font-medium text-bg"
+              : "text-muted hover:text-accent hover:underline focus:underline focus:text-accent"
+          }`}
+          style={{ paddingLeft: padLeft(depth, false) }}
+        >
+          {rankDigits !== undefined && (
+            <span className={`shrink-0 tabular-nums${isActive ? "" : " text-muted"}`}>
+              {item.rank === undefined ? "" : String(item.rank).padStart(rankDigits, "0")}
+            </span>
+          )}
+          <span className="min-w-0 flex-1" dangerouslySetInnerHTML={{ __html: labelHtml }} />
+          {showDate && shortDate && (
+            <span className={`shrink-0 tabular-nums${isActive ? "" : " text-muted"}`}>
+              {shortDate}
+            </span>
+          )}
+        </a>
+      </div>
+    </div>
+  );
+}
+
+function noteTrayGroupStorageKey(traySlug: string, groupKey: string): string {
+  return `${traySlug}#${groupKey}`;
+}
+
+function TrayGroupNode({
+  traySlug,
+  group,
+  grouping,
+  locale,
+  currentSlug,
+  forceOpen,
+  isLast,
+}: {
+  traySlug: string;
+  group: NoteTrayGroup<SidebarNavNode>;
+  grouping: "year" | "month";
+  locale: string;
+  currentSlug?: string;
+  forceOpen: boolean;
+  isLast: boolean;
+}) {
+  const containsCurrent = group.items.some((item) => item.slug === currentSlug);
+  const [open, setOpen] = useState(containsCurrent);
+  const storageKey = noteTrayGroupStorageKey(traySlug, group.key);
+  const label = grouping === "year" ? group.key : formatYearMonthLabel(group.key, locale);
+
+  useEffect(() => {
+    const stored = getOpenSet();
+    if (stored.has(storageKey) && !open) setOpen(true);
+  }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (containsCurrent && !open) {
+      setOpen(true);
+      const stored = getOpenSet();
+      stored.add(storageKey);
+      saveOpenSet(stored);
+    }
+  }, [containsCurrent]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (open) {
+      const stored = getOpenSet();
+      if (!stored.has(storageKey)) {
+        stored.add(storageKey);
+        saveOpenSet(stored);
+      }
+    }
+  }, [open, storageKey]);
+
+  const toggle = useCallback(() => {
+    setOpen((previous) => {
+      const next = !previous;
+      const stored = getOpenSet();
+      if (next) stored.add(storageKey);
+      else stored.delete(storageKey);
+      saveOpenSet(stored);
+      return next;
+    });
+  }, [storageKey]);
+
+  const isExpanded = forceOpen || open;
+
+  return (
+    <div className={!isLast && isExpanded ? "relative" : ""}>
+      {!isLast && isExpanded && (
+        <div
+          className="absolute border-l border-solid border-muted z-local-1"
+          style={{ left: connectorLeft(1), top: 0, bottom: 0 }}
+        />
+      )}
+      <div className="relative">
+        <ConnectorLines depth={1} isLast={isLast} topPad="var(--spacing-vsp-xs)" />
+        <button
+          type="button"
+          onClick={toggle}
+          className="flex w-full items-center gap-hsp-md py-vsp-xs text-left text-small font-semibold text-fg hover:text-accent hover:underline focus:underline focus:text-accent break-words"
+          style={{ paddingLeft: padLeft(1, true) }}
+          aria-expanded={isExpanded}
+          aria-label={isExpanded ? `Collapse ${label}` : `Expand ${label}`}
+          data-zd-sidebar-open-key={storageKey}
+        >
+          <span className="aspect-square flex items-center justify-center w-[1.5rem] shrink-0 border border-muted">
+            <ToggleChevron isExpanded={isExpanded} className="text-muted" />
+          </span>
+          <span>{label}</span>
+        </button>
+      </div>
+      {isExpanded && (
+        <div>
+          {group.items.map((item, index) => (
+            <TrayItem
+              key={item.slug}
+              item={item}
+              currentSlug={currentSlug}
+              isLast={index === group.items.length - 1}
+              showDate
+              // Leave one visual indentation step between the group branch
+              // and its dated child branch so the hierarchy reads clearly.
+              depth={GROUPED_TRAY_ITEM_DEPTH}
+            />
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
 // NodeList is memo-wrapped so that when only the filter query changes but
 // a subtree's nodes/currentSlug/depth/forceOpen are unchanged, Preact can
 // skip re-rendering the whole subtree.

package/eject/site-tree-nav-island/index.tsx

@@ -6,8 +6,21 @@
 // lets us consume React-typed components in this Preact app.
 import { useState } from "preact/hooks";
 import type { SidebarNavNode } from "../sidebar/types.js";
-import { INDENT, connectorLeft, ConnectorLines, CategoryLinkIcon } from "../tree-nav-shared/index.js";
+import {
+  INDENT,
+  connectorLeft,
+  ConnectorLines,
+  CategoryLinkIcon,
+} from "../tree-nav-shared/index.js";
 import { ChevronRight } from "../icons/index.js";
+import {
+  formatDate,
+  formatYearMonthLabel,
+  getNoteTrayItems,
+  groupItems,
+  rankWidth,
+} from "../note-tray-model/index.js";
+import { formatMonthDay } from "../format-date/index.js";
 import { initialCategoryOpenState, toggleCategoryOpenState } from "./state.js";
 
 // site-tree-nav uses wider padding than the narrow sidebar
@@ -42,6 +55,10 @@ export interface SiteTreeNavProps {
   categoryIgnore?: string[];
   /** Root-category slugs that should start collapsed. */
   initiallyCollapsedCategorySlugs?: string[];
+  /** Locale used by dated note-tray rows. */
+  locale?: string;
+  /** Localized label shown before an item's updated date. */
+  updatedLabel?: string;
 }
 
 export function SiteTreeNav({
@@ -50,6 +67,8 @@ export function SiteTreeNav({
   categoryOrder,
   categoryIgnore,
   initiallyCollapsedCategorySlugs,
+  locale = "en",
+  updatedLabel = "Updated",
 }: SiteTreeNavProps) {
   let processedTree = tree;
   if (categoryIgnore) {
@@ -69,20 +88,27 @@ export function SiteTreeNav({
         gridTemplateColumns: "repeat(auto-fill, minmax(min(18rem, 100%), 1fr))",
       }}
     >
-      {processedTree.map((node) => (
-        <div key={node.slug} className="min-w-0 border border-muted pl-hsp-sm py-vsp-2xs">
-          {node.children.length > 0 ? (
-            <CategoryNode
-              node={node}
-              depth={0}
-              isLast={true}
-              initiallyCollapsed={initiallyCollapsed.has(node.slug)}
-            />
-          ) : (
-            <LeafNode node={node} depth={0} isLast={true} />
-          )}
-        </div>
-      ))}
+      {processedTree.map((node) => {
+        if (node.shape === "note-tray" && getNoteTrayItems(node).length === 0) {
+          return null;
+        }
+        return (
+          <div key={node.slug} className="min-w-0 border border-muted pl-hsp-sm py-vsp-2xs">
+            {node.children.length > 0 ? (
+              <CategoryNode
+                node={node}
+                depth={0}
+                isLast={true}
+                initiallyCollapsed={initiallyCollapsed.has(node.slug)}
+                locale={locale}
+                updatedLabel={updatedLabel}
+              />
+            ) : (
+              <LeafNode node={node} depth={0} isLast={true} />
+            )}
+          </div>
+        );
+      })}
     </nav>
   );
 }
@@ -118,11 +144,15 @@ function CategoryNode({
   depth,
   isLast,
   initiallyCollapsed = false,
+  locale = "en",
+  updatedLabel = "Updated",
 }: {
   node: SidebarNavNode;
   depth: number;
   isLast: boolean;
   initiallyCollapsed?: boolean;
+  locale?: string;
+  updatedLabel?: string;
 }) {
   const [open, setOpen] = useState(() => initialCategoryOpenState(initiallyCollapsed));
   const toggle = () => setOpen(toggleCategoryOpenState);
@@ -185,13 +215,133 @@ function CategoryNode({
       </div>
       {open && (
         <div>
-          <NodeList nodes={node.children} depth={depth + 1} />
+          {node.shape === "note-tray" && depth === 0 ? (
+            <NoteTrayNodeList node={node} locale={locale} updatedLabel={updatedLabel} />
+          ) : (
+            <NodeList nodes={node.children} depth={depth + 1} />
+          )}
         </div>
       )}
     </div>
   );
 }
 
+function NoteTrayNodeList({
+  node,
+  locale,
+  updatedLabel,
+}: {
+  node: SidebarNavNode;
+  locale: string;
+  updatedLabel: string;
+}) {
+  const items = getNoteTrayItems(node);
+  const width = rankWidth(items);
+  const showDate = node.noteTrayDated === true;
+  const grouping =
+    showDate && node.noteTraySidebar !== "index"
+      ? node.noteTraySidebar
+      : undefined;
+
+  if (grouping === "year" || grouping === "month") {
+    return (
+      <div className="pl-hsp-md">
+        {groupItems(items, grouping, node.sortOrder ?? "asc").map((group) => (
+          <div key={group.key} data-note-tray-group={group.key}>
+            <div className="pt-vsp-sm pb-vsp-2xs text-micro tracking-wide uppercase text-muted">
+              {grouping === "year"
+                ? group.key
+                : formatYearMonthLabel(group.key, locale)}
+            </div>
+            {group.items.map((item) => (
+              <NoteTrayRow
+                key={item.slug}
+                item={item}
+                locale={locale}
+                updatedLabel={updatedLabel}
+                rankWidth={width}
+                showDate={showDate}
+                groupedDate={true}
+              />
+            ))}
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  return (
+    <div className="pl-hsp-md">
+      {items.map((item) => (
+        <NoteTrayRow
+          key={item.slug}
+          item={item}
+          locale={locale}
+          updatedLabel={updatedLabel}
+          rankWidth={width}
+          showDate={showDate}
+          groupedDate={false}
+        />
+      ))}
+    </div>
+  );
+}
+
+function NoteTrayRow({
+  item,
+  locale,
+  updatedLabel,
+  rankWidth: width,
+  showDate,
+  groupedDate,
+}: {
+  item: SidebarNavNode;
+  locale: string;
+  updatedLabel: string;
+  rankWidth: number;
+  showDate: boolean;
+  groupedDate: boolean;
+}) {
+  if (!item.href) return null;
+  const dateLabel = showDate && item.date
+    ? groupedDate
+      ? formatMonthDay(item.date)
+      : formatDate(item.date, locale)
+    : undefined;
+
+  return (
+    <a
+      href={item.href}
+      data-note-tray-row
+      className="flex items-start gap-hsp-sm py-vsp-2xs text-small text-fg hover:text-accent hover:underline focus:underline"
+    >
+      {dateLabel ? (
+        <time
+          dateTime={item.date}
+          className="shrink-0 font-mono tabular-nums text-caption text-muted"
+        >
+          {dateLabel}
+        </time>
+      ) : (
+        <span
+          className="shrink-0 font-mono tabular-nums text-caption text-muted"
+          style={{ width: `${width}ch` }}
+        >
+          {item.rank === undefined ? "" : String(item.rank).padStart(width, "0")}
+        </span>
+      )}
+      <span className="min-w-0">
+        <span>{item.label}</span>
+        {item.updated && (
+          <span className="block text-micro text-muted">
+            {updatedLabel} {formatDate(item.updated, locale)}
+          </span>
+        )}
+      </span>
+    </a>
+  );
+}
+
 function LeafNode({
   node,
   depth,