@takazudo/zudo-doc 5.28.2 → 6.0.0

package/dist/sidebar-tree-island/scope-state.d.ts

@@ -0,0 +1,38 @@
+import { type ReadonlySignal, type Ref } from "@takazudo/zfb/zudo-react";
+import type { SidebarNavNode, SidebarNavigationContext } from "../sidebar/types.js";
+export interface ScopeControls {
+    focus: (node: SidebarNavNode) => void;
+    focusLabel: string;
+    expansion: {
+        value: Record<string, boolean>;
+    };
+    reveal: ReadonlySignal<number>;
+    save: () => void;
+    defaultOpen: (node: SidebarNavNode) => boolean;
+    defaultGroupOpen: (items: SidebarNavNode[]) => boolean;
+}
+/** One controller shared by the real desktop tree and mobile drawer. SSR always
+ * starts with configured roots; session state is applied only on activation. */
+export declare function useSidebarScope({ nodes, navigation, activeSlug, query, locale }: {
+    nodes: SidebarNavNode[];
+    navigation?: SidebarNavigationContext;
+    activeSlug: ReadonlySignal<string | undefined>;
+    query: {
+        value: string;
+    };
+    locale: string;
+}): {
+    selected: import("@takazudo/zfb/zudo-react").Signal<string | null>;
+    selectedNodes: ReadonlySignal<SidebarNavNode[]>;
+    broader: ReadonlySignal<string | null>;
+    labels: {
+        broaden: string;
+        restore: string;
+        focus: string;
+    };
+    canRestore: ReadonlySignal<boolean>;
+    changeScope: (id: string | null) => void;
+    save: () => void;
+    navRef: Ref<HTMLElement>;
+    scopeControls: ScopeControls | undefined;
+};

package/dist/sidebar-tree-island/scope-state.js

@@ -0,0 +1,151 @@
+import { computed, getScope, signal } from "@takazudo/zfb/zudo-react";
+import { broaderSidebarScope, sidebarScopeNodes, reconcileSidebarScope, indexSidebarOccurrences, sidebarInitialExpansion, sidebarBaselineOpen, SIDEBAR_FOREST_SCOPE } from "../sidebar-utils/index.js";
+import { getNoteTrayItems, groupItems } from "../note-tray-model/index.js";
+import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
+function useSidebarScope({ nodes, navigation, activeSlug, query, locale }) {
+  const selected = signal(null);
+  const expansion = signal({});
+  const reveal = signal(0);
+  let lastPage = activeSlug.value;
+  const navRef = { current: null };
+  const stateKey = "zd-sidebar-scope";
+  const syncEvent = "zd:sidebar-scope";
+  const labels = locale === "ja" ? {
+    broaden: "\u30C4\u30EA\u30FC\u3092\u5E83\u3052\u308B",
+    restore: "\u73FE\u5728\u306E\u30DA\u30FC\u30B8\u306E\u30C4\u30EA\u30FC\u306B\u623B\u3059",
+    focus: "\u3053\u306E\u679D\u3060\u3051\u3092\u8868\u793A"
+  } : {
+    broaden: "Broaden tree",
+    restore: "Restore current page\u2019s local tree",
+    focus: "Show only this branch"
+  };
+  const selectedNodes = computed(() => navigation ? sidebarScopeNodes(navigation, nodes, selected.value) : nodes);
+  const broader = computed(() => navigation ? broaderSidebarScope(navigation, nodes, selected.value) : null);
+  const occurrenceIndex = navigation ? indexSidebarOccurrences(navigation.roots) : /* @__PURE__ */ new Map();
+  const trayGroups = [...occurrenceIndex].flatMap(([id, node]) => {
+    const grouping = node.noteTraySidebar;
+    if (node.shape !== "note-tray" || !grouping || grouping === "index") return [];
+    return groupItems(getNoteTrayItems(node), grouping, node.sortOrder ?? "asc").map((group) => ({ key: `${id}#${group.key}`, items: group.items }));
+  });
+  const groupKeys = new Set(trayGroups.map((group) => group.key));
+  const defaultOpen = (node) => sidebarBaselineOpen(node, navigation ? sidebarInitialExpansion(navigation, activeSlug.value) : void 0, activeSlug.value);
+  const defaultGroupOpen = (items) => items.some((item) => item.slug === activeSlug.value) || !!navigation && sidebarInitialExpansion(navigation, activeSlug.value) === "expanded";
+  const canRestore = computed(() => {
+    if (JSON.stringify(selectedNodes.value) !== JSON.stringify(nodes)) return true;
+    for (const [id, node] of occurrenceIndex) {
+      if (node.children.length && (expansion.value[id] ?? defaultOpen(node)) !== defaultOpen(node)) return true;
+    }
+    return trayGroups.some((group) => (expansion.value[group.key] ?? defaultGroupOpen(group.items)) !== defaultGroupOpen(group.items));
+  });
+  const revealPath = (id) => {
+    if (!navigation) return;
+    const next = { ...expansion.value };
+    for (const [key, node] of occurrenceIndex) {
+      if (node.slug !== activeSlug.value && key !== id) continue;
+      let ancestor = key;
+      while (ancestor) {
+        next[ancestor] = true;
+        ancestor = navigation.parents[ancestor];
+      }
+    }
+    for (const group of trayGroups) {
+      if (group.items.some((item) => item.slug === activeSlug.value)) next[group.key] = true;
+    }
+    expansion.value = next;
+    reveal.value++;
+  };
+  const save = () => {
+    if (!navigation) return;
+    try {
+      sessionStorage.setItem(stateKey, JSON.stringify({ context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value }));
+    } catch {
+    }
+    document.dispatchEvent(new CustomEvent(syncEvent, { detail: { context: navigation.id, page: activeSlug.value, selected: selected.value, query: query.value, expansion: expansion.value } }));
+  };
+  const changeScope = (id) => {
+    const previous = selected.value;
+    selected.value = navigation && JSON.stringify(sidebarScopeNodes(navigation, nodes, id)) === JSON.stringify(nodes) ? null : id;
+    if (id === null) {
+      expansion.value = {};
+      revealPath();
+    } else {
+      revealPath(previous);
+      revealPath(id);
+    }
+    save();
+    queueMicrotask(() => {
+      const nav = navRef.current;
+      const controls = [...nav?.querySelectorAll("[data-sidebar-focus]") ?? []];
+      const activeBranch = controls.reverse().find((button) => {
+        const node = occurrenceIndex.get(button.dataset.sidebarFocusScope ?? "");
+        const contains = (n) => n.slug === activeSlug.value || n.children.some(contains);
+        return node && contains(node);
+      });
+      const rootLink = id && id !== SIDEBAR_FOREST_SCOPE && broader.value !== null ? nav?.querySelector("[data-sidebar-tree-root] a") : null;
+      const currentLink = nav?.querySelector('[aria-current="page"]');
+      const control = (id === null ? currentLink : rootLink) ?? nav?.querySelector("[data-sidebar-broaden]") ?? activeBranch ?? currentLink ?? nav?.querySelector("[data-sidebar-focus], [data-sidebar-tree-root] a, input");
+      const target = control;
+      let viewport = nav?.parentElement;
+      while (viewport && viewport !== document.body && viewport.scrollHeight <= viewport.clientHeight) viewport = viewport.parentElement;
+      if (target && viewport && viewport !== document.body) {
+        const row = target.getBoundingClientRect();
+        const bounds = viewport.getBoundingClientRect();
+        if (row.top < bounds.top) viewport.scrollTop += row.top - bounds.top - 8;
+        else if (row.bottom > bounds.bottom) viewport.scrollTop += row.bottom - bounds.bottom + 8;
+      }
+      control?.focus({ preventScroll: true });
+    });
+  };
+  const scopeControls = navigation ? {
+    focus: (node) => {
+      if (node.occurrenceId) changeScope(node.occurrenceId);
+    },
+    focusLabel: labels.focus,
+    expansion,
+    reveal,
+    defaultOpen,
+    defaultGroupOpen,
+    save
+  } : void 0;
+  getScope().onActivate(() => {
+    if (!navigation) return;
+    lastPage = activeSlug.value;
+    try {
+      const stored = JSON.parse(sessionStorage.getItem(stateKey) ?? "null");
+      if (stored?.context === navigation.id) {
+        const candidate = typeof stored.selected === "string" ? stored.selected : null;
+        const valid = candidate === SIDEBAR_FOREST_SCOPE || candidate !== null && occurrenceIndex.has(candidate) ? candidate : null;
+        selected.value = stored.page === activeSlug.value ? valid : reconcileSidebarScope(navigation, nodes, valid, activeSlug.value);
+        query.value = typeof stored.query === "string" ? stored.query : "";
+        if (stored.expansion && typeof stored.expansion === "object") expansion.value = Object.fromEntries(Object.entries(stored.expansion).filter(([id, value]) => (occurrenceIndex.has(id) || groupKeys.has(id)) && typeof value === "boolean"));
+        if (stored.page !== activeSlug.value) revealPath(selected.value);
+      }
+    } catch {
+    }
+    save();
+    const sync = (event) => {
+      const state = event.detail;
+      if (state?.context !== navigation.id || state.page !== activeSlug.value) return;
+      selected.value = state.selected;
+      query.value = state.query;
+      expansion.value = state.expansion;
+    };
+    const navigate = () => {
+      if (lastPage === activeSlug.value) return;
+      lastPage = activeSlug.value;
+      selected.value = reconcileSidebarScope(navigation, nodes, selected.value, activeSlug.value);
+      revealPath(selected.value);
+      save();
+    };
+    document.addEventListener(syncEvent, sync);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, navigate);
+    return () => {
+      document.removeEventListener(syncEvent, sync);
+      document.removeEventListener(AFTER_NAVIGATE_EVENT, navigate);
+    };
+  });
+  return { selected, selectedNodes, broader, labels, canRestore, changeScope, save, navRef, scopeControls };
+}
+export {
+  useSidebarScope
+};

package/dist/sidebar-tree-island/sidebar-scroll-preserve.js

@@ -1,4 +1,7 @@
-import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
+import {
+  AFTER_NAVIGATE_EVENT,
+  BEFORE_NAVIGATE_EVENT
+} from "../transitions/index.js";
 const installedControllers = /* @__PURE__ */ new WeakMap();
 function installSidebarScrollPreserve({
   document: document2,
@@ -45,7 +48,8 @@ function ensureSidebarScrollPreserve(options) {
   );
 }
 function resolveBrowserOptions() {
-  if (typeof document === "undefined" || typeof window === "undefined") return void 0;
+  if (typeof document === "undefined" || typeof window === "undefined")
+    return void 0;
   return {
     document,
     requestAnimationFrame: window.requestAnimationFrame.bind(window),

package/dist/sidebar-utils/index.d.ts

@@ -25,28 +25,20 @@ export interface SidebarAutogenerated {
  * A sidebar item — string shorthand is equivalent to `{ type: "doc", id: slug }`.
  */
 export type SidebarItem = SidebarDoc | SidebarLink | SidebarCategory | SidebarAutogenerated | string;
+/** An explicit editorial tree with an optional local view of a category's children. */
+export interface SidebarDefinition {
+    items: SidebarItem[];
+    /** Resolved occurrence indexes from the forest to a category (not URL segments). */
+    initialPath?: number[];
+    /** Share across sections using the same editorial tree. Locale/version are added by chrome. */
+    contextId?: string;
+}
 /** Sidebar config keyed by section (categoryMatch value). */
 export type SidebarsConfig = {
-    [sectionKey: string]: SidebarItem[] | undefined;
+    [sectionKey: string]: SidebarItem[] | SidebarDefinition | undefined;
 };
-/** Minimal nav node shape required by sidebar-utils functions. */
-export interface SidebarNavNode {
-    slug: string;
-    label: string;
-    description?: string;
-    position: number;
-    href?: string;
-    hasPage: boolean;
-    children: SidebarNavNode[];
-    sortOrder?: "asc" | "desc";
-    collapsed?: boolean;
-    shape?: "note-tray";
-    noteTrayDated?: boolean;
-    noteTraySidebar?: "index" | "year" | "month";
-    date?: string;
-    updated?: string;
-    rank?: number;
-}
+export type { SidebarNavNode, SidebarNavigationContext } from "../sidebar/types.js";
+import type { SidebarNavNode, SidebarNavigationContext } from "../sidebar/types.js";
 /** Category metadata shape (mirrors host's CategoryMeta). */
 export interface SidebarCategoryMeta {
     label?: string;
@@ -68,3 +60,9 @@ export interface SidebarCategoryMeta {
  * values from headerNav, used for the `"!"` fallback category filter.
  */
 export declare function buildSidebarForSection(docs: unknown[], lang: string, categoryMatch: string | undefined, categoryMeta: Map<string, SidebarCategoryMeta> | undefined, sidebars: SidebarsConfig, buildNavTree: (docs: unknown[], lang: string, categoryMeta?: Map<string, SidebarCategoryMeta>) => SidebarNavNode[], explicitCategoryPrefixes: string[]): SidebarNavNode[];
+/** Builder-owned provenance keeps omitted autogenerated roots and duplicate links distinct. */
+export declare function buildSidebarNavigation(...args: Parameters<typeof buildSidebarForSection>): {
+    nodes: SidebarNavNode[];
+    navigation: SidebarNavigationContext;
+};
+export { sidebarInitialExpansion, sidebarBaselineOpen, SIDEBAR_FOREST_SCOPE, indexSidebarOccurrences, sidebarScopeNodes, broaderSidebarScope, reconcileSidebarScope } from "./scope.js";

package/dist/sidebar-utils/index.js

@@ -78,11 +78,108 @@ function buildSidebarForSection(docs, lang, categoryMatch, categoryMeta, sidebar
   const tree = buildNavTree(docs, lang, categoryMeta);
   const sectionKey = categoryMatch ?? "default";
   const config = sidebars[sectionKey];
-  if (!config || config.length === 0) {
+  if (!config || (Array.isArray(config) ? config.length === 0 : config.items.length === 0)) {
     return filterByCategory(tree, categoryMatch, explicitCategoryPrefixes);
   }
-  return resolveItems(config, tree, lang);
+  if (Array.isArray(config)) return resolveItems(config, tree, lang);
+  let nodes = resolveItems(config.items, tree, lang);
+  for (const index of config.initialPath ?? []) {
+    if (!Number.isInteger(index) || index < 0 || !nodes[index]) throw new Error(`Invalid sidebar initialPath for ${sectionKey}`);
+    nodes = nodes[index].children;
+  }
+  return nodes;
+}
+function buildSidebarNavigation(...args) {
+  const [docs, lang, categoryMatch, meta, sidebars, buildTree, prefixes] = args;
+  const initialExpansion = {};
+  for (const entry of docs) {
+    const doc = entry;
+    const value = doc.data?.sidebar_initial_expansion;
+    if (typeof doc.slug === "string" && (value === "collapsed" || value === "expanded")) {
+      const slug = doc.data?.slug ?? (doc.slug === "index" ? "" : doc.slug.replace(/\/index$/, ""));
+      initialExpansion[slug] = value;
+    }
+  }
+  const tree = buildTree(docs, lang, meta);
+  const config = sidebars[categoryMatch ?? "default"];
+  const definition = config && !Array.isArray(config) ? config : void 0;
+  const items = Array.isArray(config) ? config : definition?.items;
+  const parents = {};
+  function identify(nodes2, prefix, parent) {
+    return nodes2.map((node, index) => {
+      const occurrenceId = `${prefix}/${index}`;
+      parents[occurrenceId] = parent;
+      return { ...node, occurrenceId, children: identify(node.children, occurrenceId, occurrenceId) };
+    });
+  }
+  const automatic = identify(tree, "auto", null);
+  let roots;
+  let nodes;
+  if (!items?.length) {
+    roots = automatic;
+    nodes = filterByCategory(roots, categoryMatch, prefixes);
+  } else if (items.length === 1 && typeof items[0] !== "string" && items[0]?.type === "autogenerated") {
+    roots = automatic;
+    nodes = items[0].dirName ? findNode(roots, items[0].dirName)?.children ?? [] : roots;
+  } else {
+    let resolve2 = function(entries, prefix, parent) {
+      const canonical = [];
+      const visible = [];
+      entries.forEach((item, index) => {
+        const id = `${prefix}/${index}`;
+        if (typeof item !== "string" && item.type === "category") {
+          const children = resolve2(item.items, id, id);
+          if (item.sortOrder === "desc") {
+            children.canonical.reverse();
+            children.visible.reverse();
+          }
+          const node = { occurrenceId: id, slug: `__category__${item.label}`, label: item.label, position: 0, hasPage: false, collapsed: item.collapsed, sortOrder: item.sortOrder, children: children.canonical };
+          parents[id] = parent;
+          canonical.push(node);
+          visible.push({ ...node, children: children.visible });
+        } else if (typeof item !== "string" && item.type === "autogenerated" && item.dirName) {
+          const source = findNode(tree, item.dirName);
+          if (source) {
+            const identified = identify([source], id, parent)[0];
+            canonical.push(identified);
+            visible.push(...identified.children);
+          }
+        } else {
+          const resolved = identify(resolveItem(item, tree, lang), id, parent);
+          canonical.push(...resolved);
+          visible.push(...resolved);
+        }
+      });
+      return { canonical, visible };
+    };
+    var resolve = resolve2;
+    for (const id of Object.keys(parents)) delete parents[id];
+    const result = resolve2(items, "custom", null);
+    roots = result.canonical;
+    nodes = result.visible;
+  }
+  let localParentId;
+  for (const index of definition?.initialPath ?? []) {
+    const node = nodes[index];
+    if (!Number.isInteger(index) || index < 0 || !node) throw new Error(`Invalid sidebar initialPath for ${categoryMatch ?? "default"}`);
+    localParentId = node.occurrenceId;
+    nodes = node.children;
+  }
+  let hash = 2166136261;
+  const serialized = JSON.stringify(Object.keys(initialExpansion).length ? [roots, initialExpansion] : roots);
+  for (let i = 0; i < serialized.length; i++) hash = Math.imul(hash ^ serialized.charCodeAt(i), 16777619);
+  const kind = !items?.length || items.length === 1 && typeof items[0] !== "string" && items[0]?.type === "autogenerated" ? "automatic" : definition?.contextId ?? categoryMatch ?? "default";
+  return { nodes, navigation: { id: `${lang}:${kind}:${hash >>> 0}`, roots, parents, ...Object.keys(initialExpansion).length ? { initialExpansion } : {}, ...localParentId ? { localParentId } : {} } };
 }
+import { sidebarInitialExpansion, sidebarBaselineOpen, SIDEBAR_FOREST_SCOPE, indexSidebarOccurrences, sidebarScopeNodes, broaderSidebarScope, reconcileSidebarScope } from "./scope.js";
 export {
-  buildSidebarForSection
+  SIDEBAR_FOREST_SCOPE,
+  broaderSidebarScope,
+  buildSidebarForSection,
+  buildSidebarNavigation,
+  indexSidebarOccurrences,
+  reconcileSidebarScope,
+  sidebarBaselineOpen,
+  sidebarInitialExpansion,
+  sidebarScopeNodes
 };

package/dist/sidebar-utils/scope.d.ts

@@ -0,0 +1,11 @@
+import type { SidebarNavNode, SidebarNavigationContext } from "../sidebar/types.js";
+export declare const SIDEBAR_FOREST_SCOPE = "@forest";
+export declare function indexSidebarOccurrences(roots: SidebarNavNode[]): Map<string, SidebarNavNode>;
+export declare function sidebarScopeNodes(context: SidebarNavigationContext, baseline: SidebarNavNode[], selected: string | null): SidebarNavNode[];
+/** Only an actual shared parent can enclose a configured forest. */
+export declare function broaderSidebarScope(context: SidebarNavigationContext, baseline: SidebarNavNode[], selected: string | null): string | null;
+/** On navigation, widen only to the nearest common editorial ancestor. */
+export declare function reconcileSidebarScope(context: SidebarNavigationContext, baseline: SidebarNavNode[], selected: string | null, slug?: string): string | null;
+/** Leaf override, nearest index default, then legacy undefined behavior. */
+export declare function sidebarInitialExpansion(context: SidebarNavigationContext, slug?: string): "collapsed" | "expanded" | undefined;
+export declare function sidebarBaselineOpen(node: SidebarNavNode, mode: "collapsed" | "expanded" | undefined, currentSlug?: string): boolean;

package/dist/sidebar-utils/scope.js

@@ -0,0 +1,67 @@
+const SIDEBAR_FOREST_SCOPE = "@forest";
+function indexSidebarOccurrences(roots) {
+  const result = /* @__PURE__ */ new Map();
+  const visit = (nodes) => nodes.forEach((node) => {
+    if (node.occurrenceId) result.set(node.occurrenceId, node);
+    visit(node.children);
+  });
+  visit(roots);
+  return result;
+}
+function sidebarScopeNodes(context, baseline, selected) {
+  if (selected === null) return baseline;
+  if (selected === SIDEBAR_FOREST_SCOPE) return context.roots;
+  const node = indexSidebarOccurrences(context.roots).get(selected);
+  return node ? [node] : baseline;
+}
+function broaderSidebarScope(context, baseline, selected) {
+  if (selected === SIDEBAR_FOREST_SCOPE) return null;
+  if (selected !== null) {
+    const parent = context.parents[selected];
+    if (parent) return parent;
+    if (context.roots.length === 1 && context.roots[0]?.occurrenceId === selected) return null;
+    return SIDEBAR_FOREST_SCOPE;
+  }
+  if (!baseline.length) return null;
+  const parents = baseline.map((node) => node.occurrenceId ? context.parents[node.occurrenceId] : void 0);
+  if (parents.some((parent) => parent === void 0 || parent !== parents[0])) return context.localParentId ?? null;
+  if (parents[0]) return parents[0];
+  const rootIds = context.roots.map((node) => node.occurrenceId);
+  return baseline.length === rootIds.length && baseline.every((node, i) => node.occurrenceId === rootIds[i]) ? null : SIDEBAR_FOREST_SCOPE;
+}
+function reconcileSidebarScope(context, baseline, selected, slug) {
+  if (selected === null || slug === void 0) return selected;
+  const index = indexSidebarOccurrences(context.roots);
+  if (selected !== SIDEBAR_FOREST_SCOPE && !index.has(selected)) return null;
+  const contains = (nodes) => nodes.some((node) => node.slug === slug || contains(node.children));
+  if (!contains(context.roots)) return null;
+  let candidate = selected;
+  while (candidate !== null) {
+    if (contains(sidebarScopeNodes(context, baseline, candidate))) return candidate;
+    candidate = broaderSidebarScope(context, baseline, candidate);
+  }
+  return null;
+}
+function sidebarInitialExpansion(context, slug = "") {
+  let candidate = slug;
+  while (true) {
+    const value = context.initialExpansion?.[candidate];
+    if (value) return value;
+    if (!candidate) return void 0;
+    const slash = candidate.lastIndexOf("/");
+    candidate = slash < 0 ? "" : candidate.slice(0, slash);
+  }
+}
+function sidebarBaselineOpen(node, mode, currentSlug) {
+  const contains = (n) => currentSlug !== void 0 && (n.slug === currentSlug || n.children.some(contains));
+  return contains(node) || (node.collapsed !== void 0 ? !node.collapsed : mode !== "collapsed");
+}
+export {
+  SIDEBAR_FOREST_SCOPE,
+  broaderSidebarScope,
+  indexSidebarOccurrences,
+  reconcileSidebarScope,
+  sidebarBaselineOpen,
+  sidebarInitialExpansion,
+  sidebarScopeNodes
+};

package/dist/sidebar-with-defaults/index.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { SidebarNavNode, SidebarRootMenuItem } from "../sidebar/types.js";
 import type { ChromeContext } from "../factory-context/index.js";
 import type { Settings } from "../settings.js";

package/dist/sidebar-with-defaults/index.js

@@ -1,15 +1,16 @@
-import { jsx } from "preact/jsx-runtime";
+import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { SidebarTree } from "../sidebar-tree-island/index.js";
 import { themeToggleLabels } from "../theme-toggle/labels.js";
 import { deriveDateFormats, deriveNavDataPrep } from "../chrome/derive.js";
+import { normalizeIslandData } from "../chrome/island-data.js";
 import { assertChromeContext } from "../chrome/assert-chrome-context.js";
 function createSidebarWithDefaults(ctx) {
   assertChromeContext(ctx, "createSidebarWithDefaults");
   const defaultLocale = ctx.defaultLocale;
   const localeCount = ctx.locales.length;
   const t = ctx.t;
-  const { buildRootMenuItems, buildLocaleLinksForNav, buildSidebarNodes, getThemeDefaultMode } = deriveNavDataPrep(ctx);
+  const { buildRootMenuItems, buildLocaleLinksForNav, buildSidebarContext, getThemeDefaultMode } = deriveNavDataPrep(ctx);
   const dateFormatsFor = deriveDateFormats(ctx);
   function SidebarWithDefaults(props) {
     const {
@@ -21,25 +22,25 @@ function createSidebarWithDefaults(ctx) {
     } = props;
     const rootMenuItems = buildRootMenuItems(lang, currentVersion);
     const backToMenuLabel = navSection ? t("nav.backToMenu", lang) : void 0;
-    const nodes = buildSidebarNodes(lang, navSection, currentVersion, false);
+    const { nodes, navigation } = buildSidebarContext(lang, navSection, currentVersion, false);
     const localeLinks = buildLocaleLinksForNav(currentPath, lang, localeCount);
+    const themeDefaultMode = getThemeDefaultMode();
+    const treeProps = normalizeIslandData({
+      nodes,
+      navigation,
+      ...currentSlug !== void 0 ? { currentSlug } : {},
+      rootMenuItems,
+      ...backToMenuLabel !== void 0 ? { backToMenuLabel } : {},
+      locale: lang,
+      ...localeLinks !== void 0 ? { localeLinks } : {},
+      ...themeDefaultMode !== void 0 ? { themeDefaultMode } : {},
+      themeLabels: themeToggleLabels(t, lang),
+      themeRespectSystem: (ctx.settings.colorMode && ctx.settings.colorMode.respectPrefersColorScheme) ?? true,
+      dateFormats: dateFormatsFor(lang)
+    });
     return Island({
       when: "load",
-      children: /* @__PURE__ */ jsx(
-        SidebarTree,
-        {
-          nodes,
-          currentSlug,
-          rootMenuItems,
-          backToMenuLabel,
-          locale: lang,
-          localeLinks,
-          themeDefaultMode: getThemeDefaultMode(),
-          themeLabels: themeToggleLabels(t, lang),
-          themeRespectSystem: (ctx.settings.colorMode && ctx.settings.colorMode.respectPrefersColorScheme) ?? true,
-          dateFormats: dateFormatsFor(lang)
-        }
-      )
+      children: /* @__PURE__ */ jsx(SidebarTree, { ...treeProps })
     });
   }
   return SidebarWithDefaults;

package/dist/site-schema/nav-tree.js

@@ -7,18 +7,18 @@ function toNavNode(node) {
   return {
     slug: node.id,
     label: node.label,
-    description: node.description,
+    ...node.description !== void 0 ? { description: node.description } : {},
     position: node.sidebar_position ?? 999,
-    href: node.href,
+    ...node.href !== void 0 ? { href: node.href } : {},
     hasPage: node.hasPage,
     children: node.children.map(toNavNode),
     sortOrder: node.sortOrder ?? "asc",
-    shape: node.shape,
-    noteTrayDated: node.noteTrayDated,
-    noteTraySidebar: node.noteTraySidebar,
-    date: node.date,
-    updated: node.updated,
-    rank: node.rank
+    ...node.shape !== void 0 ? { shape: node.shape } : {},
+    ...node.noteTrayDated !== void 0 ? { noteTrayDated: node.noteTrayDated } : {},
+    ...node.noteTraySidebar !== void 0 ? { noteTraySidebar: node.noteTraySidebar } : {},
+    ...node.date !== void 0 ? { date: node.date } : {},
+    ...node.updated !== void 0 ? { updated: node.updated } : {},
+    ...node.rank !== void 0 ? { rank: node.rank } : {}
   };
 }
 function findRootIndexDoc(docs) {
@@ -36,17 +36,17 @@ function toRootNavNode(doc, locale, buildHref, categoryMeta) {
   return {
     slug: "",
     label: doc.data.sidebar_label ?? doc.data.title ?? meta?.label ?? "",
-    description: doc.data.description ?? meta?.description,
+    ...(doc.data.description ?? meta?.description) !== void 0 ? { description: doc.data.description ?? meta?.description } : {},
     position: doc.data.sidebar_position ?? meta?.position ?? 999,
-    href: noPage ? void 0 : buildHref("", locale),
+    ...noPage ? {} : { href: buildHref("", locale) },
     hasPage: noPage !== true,
     children: [],
     sortOrder,
-    shape: doc.data.category_shape,
-    noteTrayDated: doc.data.note_tray_dated,
-    noteTraySidebar: doc.data.note_tray_sidebar,
-    date: doc.data.date,
-    updated: doc.data.updated,
+    ...doc.data.category_shape !== void 0 ? { shape: doc.data.category_shape } : {},
+    ...doc.data.note_tray_dated !== void 0 ? { noteTrayDated: doc.data.note_tray_dated } : {},
+    ...doc.data.note_tray_sidebar !== void 0 ? { noteTraySidebar: doc.data.note_tray_sidebar } : {},
+    ...doc.data.date !== void 0 ? { date: doc.data.date } : {},
+    ...doc.data.updated !== void 0 ? { updated: doc.data.updated } : {},
     rank: 1
   };
 }

package/dist/site-schema/types.d.ts

@@ -46,6 +46,7 @@ export interface DocPageFrontmatter {
     standalone?: boolean;
     sidebar_position?: number;
     sidebar_label?: string;
+    sidebar_initial_expansion?: "collapsed" | "expanded";
     category_no_page?: boolean;
     category_sort_order?: "asc" | "desc";
     category_shape?: "note-tray";

package/dist/site-tree-nav/index.d.ts

@@ -1,6 +1,5 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-import type { JSX } from "preact";
+import type { JSX } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import type { SidebarNavNode } from "../sidebar/types.js";
 import type { DateFormatSetting } from "../settings.js";
 /**
@@ -21,7 +20,7 @@ export interface SiteTreeNavWrapperProps {
     lang?: string;
     /**
      * Optional aria-label for the wrapping <nav> element.
-     * Forwarded to the v2 SiteTreeNavDemo component.
+     * Forwarded to the interactive SiteTreeNav island.
      */
     ariaLabel?: string;
     /**

package/dist/site-tree-nav/index.js

@@ -1,8 +1,9 @@
-import { jsx } from "preact/jsx-runtime";
+import { jsx } from "@takazudo/zfb/zudo-react/jsx-runtime";
 import { Island } from "@takazudo/zfb";
 import { SiteTreeNav } from "../site-tree-nav-island/index.js";
 import { remapVersionedHrefs } from "../nav-data-prep/index.js";
 import { resolveDateFormats } from "../date-format-resolve/index.js";
+import { normalizeSiteTreeNavProps } from "./normalize-island-props.js";
 function createSiteTreeNavWrapper(deps) {
   const {
     defaultLocale,
@@ -38,19 +39,17 @@ function createSiteTreeNavWrapper(deps) {
       }
     }
     if (tree.length === 0) return null;
+    const islandProps = normalizeSiteTreeNavProps({
+      tree,
+      categoryOrder,
+      ...categoryIgnore !== void 0 ? { categoryIgnore } : {},
+      ...ariaLabel !== void 0 ? { ariaLabel } : {},
+      locale,
+      dateFormats: resolveDateFormats(dateFormat, locale)
+    });
     return Island({
       when: "idle",
-      children: /* @__PURE__ */ jsx(
-        SiteTreeNav,
-        {
-          tree,
-          categoryOrder,
-          categoryIgnore,
-          ariaLabel,
-          locale,
-          dateFormats: resolveDateFormats(dateFormat, locale)
-        }
-      )
+      children: /* @__PURE__ */ jsx(SiteTreeNav, { ...islandProps })
     });
   }
   return SiteTreeNavWrapper;

package/dist/site-tree-nav/normalize-island-props.d.ts

@@ -0,0 +1,16 @@
+import type { ResolvedDateFormats } from "../settings.js";
+import type { SidebarNavNode } from "../sidebar/types.js";
+export interface SiteTreeNavIslandProps {
+    tree: SidebarNavNode[];
+    categoryOrder: string[];
+    categoryIgnore?: string[];
+    ariaLabel?: string;
+    locale: string;
+    dateFormats: ResolvedDateFormats;
+}
+/**
+ * Copy the host nav payload through the island's finite JSON shape. Optional
+ * fields are added only when present, so neither node records nor top-level
+ * props carry own `undefined` values across SSR and hydration.
+ */
+export declare function normalizeSiteTreeNavProps(input: SiteTreeNavIslandProps): SiteTreeNavIslandProps;