@colixsystems/widget-sdk 0.196.0 → 0.197.0

package/README.md

@@ -77,7 +77,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.196.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.197.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.197.0 (contract 1.157.0)
+
+**Host navigation: a page's sidebar menu can be opened from any page.** `resolveSidebarUnfold({ entries, active, sections })` used to answer only the section being viewed, so a host could draw a section's menu only while the visitor was inside it. The result now also carries `trees`: one `{ under, items, standalone, inside }` for every sidebar entry that carries a local menu, in menu order. `inside` is true for the section being viewed, which a host draws open; the others it draws folded behind the entry's arrow. `under`, `items` and `standalone` still describe the viewed section, so existing callers keep working. Widgets are unaffected: this is the host surface (`@colixsystems/widget-sdk/host`), and the widget contract version does not change.
 
 ### What's new in 0.196.0 (contract 1.157.0)
 

package/dist/host.d.ts

@@ -254,14 +254,26 @@ export interface SidebarUnfoldItem {
   [field: string]: unknown;
 }
 
+/** One section's local menu and the sidebar entry it hangs beneath. `inside`
+ *  marks the section the visitor is in — the one that starts unfolded. */
+export interface SidebarUnfoldTree {
+  under: string;
+  items: Array<SidebarUnfoldItem & { current: boolean }>;
+  standalone: boolean;
+  inside: boolean;
+}
+
 /** Where a page's `SIDEBAR` local menu unfolds (REQ-NAV-LOCAL, sc-7696).
- *  `under` is the global menu entry the items hang beneath, or null when
- *  nothing unfolds. `standalone` marks the case where the global menu does not
- *  list the page, so the page itself is the entry. */
+ *  `under` is the global menu entry the visitor's own section hangs beneath,
+ *  or null when they are in none. `standalone` marks the case where the global
+ *  menu does not list the page, so the page itself is the entry. `trees` is
+ *  every section an entry carries, in menu order, so an entry can offer its
+ *  menu from any page; a `standalone` tree comes last. */
 export interface SidebarUnfold {
   under: string | null;
   items: Array<SidebarUnfoldItem & { current: boolean }>;
   standalone: boolean;
+  trees: SidebarUnfoldTree[];
 }
 
 /** Resolve where the viewed page's local menu unfolds in the sidebar and the

package/dist/navigation.cjs

@@ -636,21 +636,25 @@ function resolveTopBarTokens(theme) {
  * inside it, so the menu is never lost — a section off the menu is exactly
  * the case that would otherwise render blank.
  *
+ * sc-10693: `trees` answers EVERY section, not only the visitor's own, so a
+ * section's entry can offer its menu from any page. `under` / `items` /
+ * `standalone` still name the one the visitor is inside.
+ *
  * @param {{ entries?: unknown, active?: unknown, sections?: unknown }} input
  *   `entries` — the global menu's keys, in menu order.
  *   `active` — the key of the page being viewed.
  *   `sections` — `{ [key]: { menu, items } }` for pages whose local nav is
  *   `SIDEBAR`; `menu` identifies the saved menu, `items` carry their own key.
- * @returns {{ under: string|null, items: Array<object>, standalone: boolean }}
- *   `under` is null when nothing unfolds; when `standalone` it names the
- *   section's own page, which the host draws as the entry. Each item is
- *   returned with a `current` flag rather than leaving each host to
- *   recompute it.
+ * @returns {{ under: string|null, items: Array<object>, standalone: boolean, trees: Array<object> }}
+ *   `under` is null when the visitor is in no section; when `standalone` it
+ *   names the section's own page, which the host draws as the entry. Each
+ *   item is returned with a `current` flag rather than leaving each host to
+ *   recompute it. `trees` lists `{ under, items, standalone, inside }` in menu
+ *   order, a `standalone` one last; `inside` marks the visitor's own.
  */
 function resolveSidebarUnfold(input) {
   const { entries, active, sections } = isPlainObject(input) ? input : {};
-  const nothing = { under: null, items: [], standalone: false };
-  if (typeof active !== "string" || !active) return nothing;
+  const viewed = typeof active === "string" && active ? active : null;
   const bank = isPlainObject(sections) ? sections : {};
   const order = Array.isArray(entries) ? entries : [];
   const sectionAt = (key) => {
@@ -663,31 +667,60 @@ function resolveSidebarUnfold(input) {
     return (
       Boolean(candidate) &&
       candidate.items.some(
-        (item) => isPlainObject(item) && item.key === active,
+        (item) => isPlainObject(item) && item.key === viewed,
       )
     );
   };
   // The page's own section wins; otherwise the section whose menu lists it,
   // preferring one a global entry carries so the tree hangs where it always
   // does. Both are the same section from the visitor's side.
-  const section =
-    sectionAt(active) ||
-    sectionAt(order.find(lists)) ||
-    sectionAt(Object.keys(bank).find(lists));
-  if (!section) return nothing;
-  const marked = section.items.map((item) => ({
-    ...(isPlainObject(item) ? item : {}),
-    current:
-      isPlainObject(item) && typeof item.key === "string" && item.key === active,
-  }));
-  const owner = order.find((key) => {
-    const candidate = isPlainObject(bank[key]) ? bank[key] : null;
-    return Boolean(candidate) && candidate.menu === section.menu;
-  });
-  if (typeof owner === "string" && owner) {
-    return { under: owner, items: marked, standalone: false };
+  const section = viewed
+    ? sectionAt(viewed) ||
+      sectionAt(order.find(lists)) ||
+      sectionAt(Object.keys(bank).find(lists))
+    : null;
+  const mark = (items) =>
+    items.map((item) => ({
+      ...(isPlainObject(item) ? item : {}),
+      current:
+        viewed !== null &&
+        isPlainObject(item) &&
+        typeof item.key === "string" &&
+        item.key === viewed,
+    }));
+  // A saved menu hangs under the FIRST global entry carrying it, so two
+  // entries sharing one menu never draw it twice.
+  const claimed = [];
+  const trees = [];
+  for (const key of order) {
+    if (!isPlainObject(bank[key])) continue;
+    const { menu } = bank[key];
+    if (claimed.includes(menu)) continue;
+    claimed.push(menu);
+    // An unusable key still owns its menu: nothing may hang it elsewhere.
+    if (typeof key !== "string" || !key) continue;
+    const inside = Boolean(section) && menu === section.menu;
+    const own = inside ? section : sectionAt(key);
+    if (!own) continue;
+    trees.push({ under: key, items: mark(own.items), standalone: false, inside });
+  }
+  if (!section) return { under: null, items: [], standalone: false, trees };
+  const owned = trees.find((tree) => tree.inside);
+  if (owned) {
+    return { under: owned.under, items: owned.items, standalone: false, trees };
   }
-  return { under: section.key, items: marked, standalone: true };
+  const alone = {
+    under: section.key,
+    items: mark(section.items),
+    standalone: true,
+    inside: true,
+  };
+  return {
+    under: alone.under,
+    items: alone.items,
+    standalone: true,
+    trees: [...trees, alone],
+  };
 }
 
 /**

package/dist/navigation.js

@@ -627,21 +627,25 @@ export function resolveTopBarTokens(theme) {
  * inside it, so the menu is never lost — a section off the menu is exactly
  * the case that would otherwise render blank.
  *
+ * sc-10693: `trees` answers EVERY section, not only the visitor's own, so a
+ * section's entry can offer its menu from any page. `under` / `items` /
+ * `standalone` still name the one the visitor is inside.
+ *
  * @param {{ entries?: unknown, active?: unknown, sections?: unknown }} input
  *   `entries` — the global menu's keys, in menu order.
  *   `active` — the key of the page being viewed.
  *   `sections` — `{ [key]: { menu, items } }` for pages whose local nav is
  *   `SIDEBAR`; `menu` identifies the saved menu, `items` carry their own key.
- * @returns {{ under: string|null, items: Array<object>, standalone: boolean }}
- *   `under` is null when nothing unfolds; when `standalone` it names the
- *   section's own page, which the host draws as the entry. Each item is
- *   returned with a `current` flag rather than leaving each host to
- *   recompute it.
+ * @returns {{ under: string|null, items: Array<object>, standalone: boolean, trees: Array<object> }}
+ *   `under` is null when the visitor is in no section; when `standalone` it
+ *   names the section's own page, which the host draws as the entry. Each
+ *   item is returned with a `current` flag rather than leaving each host to
+ *   recompute it. `trees` lists `{ under, items, standalone, inside }` in menu
+ *   order, a `standalone` one last; `inside` marks the visitor's own.
  */
 export function resolveSidebarUnfold(input) {
   const { entries, active, sections } = isPlainObject(input) ? input : {};
-  const nothing = { under: null, items: [], standalone: false };
-  if (typeof active !== "string" || !active) return nothing;
+  const viewed = typeof active === "string" && active ? active : null;
   const bank = isPlainObject(sections) ? sections : {};
   const order = Array.isArray(entries) ? entries : [];
   const sectionAt = (key) => {
@@ -654,31 +658,60 @@ export function resolveSidebarUnfold(input) {
     return (
       Boolean(candidate) &&
       candidate.items.some(
-        (item) => isPlainObject(item) && item.key === active,
+        (item) => isPlainObject(item) && item.key === viewed,
       )
     );
   };
   // The page's own section wins; otherwise the section whose menu lists it,
   // preferring one a global entry carries so the tree hangs where it always
   // does. Both are the same section from the visitor's side.
-  const section =
-    sectionAt(active) ||
-    sectionAt(order.find(lists)) ||
-    sectionAt(Object.keys(bank).find(lists));
-  if (!section) return nothing;
-  const marked = section.items.map((item) => ({
-    ...(isPlainObject(item) ? item : {}),
-    current:
-      isPlainObject(item) && typeof item.key === "string" && item.key === active,
-  }));
-  const owner = order.find((key) => {
-    const candidate = isPlainObject(bank[key]) ? bank[key] : null;
-    return Boolean(candidate) && candidate.menu === section.menu;
-  });
-  if (typeof owner === "string" && owner) {
-    return { under: owner, items: marked, standalone: false };
+  const section = viewed
+    ? sectionAt(viewed) ||
+      sectionAt(order.find(lists)) ||
+      sectionAt(Object.keys(bank).find(lists))
+    : null;
+  const mark = (items) =>
+    items.map((item) => ({
+      ...(isPlainObject(item) ? item : {}),
+      current:
+        viewed !== null &&
+        isPlainObject(item) &&
+        typeof item.key === "string" &&
+        item.key === viewed,
+    }));
+  // A saved menu hangs under the FIRST global entry carrying it, so two
+  // entries sharing one menu never draw it twice.
+  const claimed = [];
+  const trees = [];
+  for (const key of order) {
+    if (!isPlainObject(bank[key])) continue;
+    const { menu } = bank[key];
+    if (claimed.includes(menu)) continue;
+    claimed.push(menu);
+    // An unusable key still owns its menu: nothing may hang it elsewhere.
+    if (typeof key !== "string" || !key) continue;
+    const inside = Boolean(section) && menu === section.menu;
+    const own = inside ? section : sectionAt(key);
+    if (!own) continue;
+    trees.push({ under: key, items: mark(own.items), standalone: false, inside });
+  }
+  if (!section) return { under: null, items: [], standalone: false, trees };
+  const owned = trees.find((tree) => tree.inside);
+  if (owned) {
+    return { under: owned.under, items: owned.items, standalone: false, trees };
   }
-  return { under: section.key, items: marked, standalone: true };
+  const alone = {
+    under: section.key,
+    items: mark(section.items),
+    standalone: true,
+    inside: true,
+  };
+  return {
+    under: alone.under,
+    items: alone.items,
+    standalone: true,
+    trees: [...trees, alone],
+  };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.196.0",
+  "version": "0.197.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",