@canonical/utils 0.29.0-experimental.0 → 0.30.0

package/dist/esm/lib/navigation/annotateTree.js

@@ -20,7 +20,7 @@ export function annotateTree(root, parentUrl = null, depth = 0) {
     };
     if (items) {
         // The tree is homogeneous: every node is the same item type `T`. The base
-        // `Item<C>.items` is typed `Item<C>[]`, so narrow children back to `T`
+        // `Item.items` is typed `Item[]`, so narrow children back to `T`
         // (enhanced item types like `NavItem` already declare `items?: NavItem[]`).
         annotated.items = items.map((child) => annotateTree(child, getItemId(root), depth + 1));
     }

package/dist/esm/lib/navigation/annotateTree.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotateTree.js","sourceRoot":"","sources":["../../../../src/lib/navigation/annotateTree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAO,EACP,YAA2B,IAAI,EAC/B,KAAK,GAAG,CAAC;IAET,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAChC,6EAA6E;IAC7E,gFAAgF;IAChF,MAAM,SAAS,GAAG;QAChB,GAAG,IAAI;QACP,SAAS;QACT,KAAK;KACM,CAAC;IACd,IAAI,KAAK,EAAE,CAAC;QACV,0EAA0E;QAC1E,uEAAuE;QACvE,4EAA4E;QAC5E,SAAS,CAAC,KAAK,GAAI,KAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC7C,YAAY,CAAI,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"annotateTree.js","sourceRoot":"","sources":["../../../../src/lib/navigation/annotateTree.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAC1B,IAAO,EACP,YAA2B,IAAI,EAC/B,KAAK,GAAG,CAAC;IAET,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IAChC,6EAA6E;IAC7E,gFAAgF;IAChF,MAAM,SAAS,GAAG;QAChB,GAAG,IAAI;QACP,SAAS;QACT,KAAK;KACM,CAAC;IACd,IAAI,KAAK,EAAE,CAAC;QACV,0EAA0E;QAC1E,iEAAiE;QACjE,4EAA4E;QAC5E,SAAS,CAAC,KAAK,GAAI,KAAa,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC7C,YAAY,CAAI,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/esm/lib/navigation/createCrossGroupStateReducer.js

@@ -0,0 +1,128 @@
+import getFirstEnabledChild from "./getFirstEnabledChild.js";
+import getLastEnabledChild from "./getLastEnabledChild.js";
+import { NavigationActionType, } from "./navigationTypes.js";
+/**
+ * Scan the groups adjacent to `group` (skipping disabled or empty ones) and
+ * return the group to land in, in the given direction.
+ * @param groups The sibling groups (children of the menu root).
+ * @param group The current group being left.
+ * @param direction 1 for the next group, -1 for the previous.
+ * @returns [adjacentGroup, landingItem] or undefined at the tree's edge.
+ */
+const findAdjacentLanding = (groups, group, direction) => {
+    let cursor = groups.indexOf(group) + direction;
+    while (cursor >= 0 && cursor < groups.length) {
+        const candidate = groups.at(cursor);
+        if (candidate && !candidate.disabled) {
+            // Enter a forward group at its first item, a backward group at its last.
+            const landing = direction === 1
+                ? getFirstEnabledChild(candidate)
+                : getLastEnabledChild(candidate);
+            if (landing)
+                return [candidate, landing];
+        }
+        cursor += direction;
+    }
+    return undefined;
+};
+/**
+ * Create a `stateReducer` for `useNavigationTree` that lets vertical arrow keys
+ * cross group boundaries. Within a group, {@link createNavigationReducer}
+ * already moves between items; at a group edge its `getSibling` finds no sibling
+ * and leaves the highlight unchanged. This reducer detects that edge structurally
+ * (the highlighted item is the first/last enabled child of its group) and moves
+ * the highlight to the adjacent group's boundary item.
+ *
+ * It operates purely on `state.highlightedItems` — the ancestor path
+ * `[root, group, item]` — so it uses the same annotated item instances the
+ * navigation tree holds internally. It needs no external index, which avoids the
+ * instance-mismatch that would arise from re-annotating the tree separately.
+ *
+ * The group boundary logic lives entirely here, so the base navigation reducer
+ * stays group-agnostic. It suits any grouped, vertically-navigated widget
+ * (contextual menus, sectioned side navigation) built on a
+ * root -> group -> item tree.
+ *
+ * @returns A `(state, action) => state` reducer to pass as `stateReducer`.
+ */
+/**
+ * Type-ahead across group boundaries. The base reducer only searches the
+ * current item's siblings (one group), so typing a letter that matches an item
+ * in ANOTHER group finds nothing. This searches every group's items — from just
+ * after the current item, wrapping — for the first enabled item whose label
+ * matches `keysSoFar`, and moves the highlight there.
+ * @returns The updated state, or the input state if there is no match.
+ */
+const handleCrossGroupTypeAhead = (state) => {
+    const path = state.highlightedItems;
+    const current = path.at(-1);
+    const group = path.at(-2);
+    const root = path.at(-3);
+    if (!current || !group || !root?.items)
+        return state;
+    const search = state.keysSoFar.toLowerCase();
+    if (!search)
+        return state;
+    // If the current item already matches, the base reducer handled it in-group.
+    if (current.label?.toLowerCase().startsWith(search))
+        return state;
+    // Flatten every group's enabled items into one ordered list, remembering each
+    // item's group so the highlight path can be rebuilt from the tree's instances.
+    const entries = [];
+    for (const g of root.items) {
+        if (g.disabled)
+            continue;
+        for (const it of g.items ?? []) {
+            if (!it.disabled)
+                entries.push({ group: g, item: it });
+        }
+    }
+    const currentIndex = entries.findIndex((e) => e.item === current);
+    const start = currentIndex + 1;
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[(start + i) % entries.length];
+        if (entry.item.label?.toLowerCase().startsWith(search)) {
+            return {
+                ...state,
+                highlightedItems: [...path.slice(0, -2), entry.group, entry.item],
+                currentDepth: entry.item.depth,
+            };
+        }
+    }
+    return state;
+};
+const createCrossGroupStateReducer = () => (state, action) => {
+    if (action.type === NavigationActionType.TYPE_AHEAD) {
+        return handleCrossGroupTypeAhead(state);
+    }
+    const isDown = action.type === NavigationActionType.ARROW_DOWN;
+    const isUp = action.type === NavigationActionType.ARROW_UP;
+    if (!isDown && !isUp)
+        return state;
+    // The highlighted path is [root, group, item] for a grouped menu.
+    const path = state.highlightedItems;
+    const current = path.at(-1);
+    const group = path.at(-2);
+    const root = path.at(-3);
+    // Only items nested inside a group (root -> group -> item) can cross groups.
+    if (!current || !group || !root?.items)
+        return state;
+    const boundaryChild = isDown
+        ? getLastEnabledChild(group)
+        : getFirstEnabledChild(group);
+    // Not at the group edge — the base reducer already moved within the group.
+    if (boundaryChild !== current)
+        return state;
+    const landing = findAdjacentLanding(root.items, group, isDown ? 1 : -1);
+    if (!landing)
+        return state;
+    const [adjacentGroup, target] = landing;
+    return {
+        ...state,
+        // Build the path from the known chain — same instances the tree holds.
+        highlightedItems: [...path.slice(0, -2), adjacentGroup, target],
+        currentDepth: target.depth,
+    };
+};
+export default createCrossGroupStateReducer;
+//# sourceMappingURL=createCrossGroupStateReducer.js.map

package/dist/esm/lib/navigation/createCrossGroupStateReducer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCrossGroupStateReducer.js","sourceRoot":"","sources":["../../../../src/lib/navigation/createCrossGroupStateReducer.ts"],"names":[],"mappings":"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"}

package/dist/esm/lib/navigation/getFirstEnabledLeaf.js

@@ -0,0 +1,42 @@
+/**
+ * Descend to the first enabled LEAF of a subtree — the first enabled node that
+ * has no enabled children of its own.
+ *
+ * The point of difference from {@link getFirstEnabledChild} is the structural
+ * group layer of a contextual menu. A menu is a `root -> group -> item` tree:
+ * the root's direct children are GROUPS (rendered `role="group"`, never
+ * focusable), and the real `role="menuitem"` nodes live one level deeper.
+ * Highlighting the first *child* of the root lands on a group, so no item
+ * becomes the roving tab stop and arrow keys have no current item to move from.
+ * Descending to the first leaf lands on the first real menuitem instead.
+ *
+ * For a flat `root -> item` tree (e.g. a simple menu with no groups) the first
+ * child is already a leaf, so this returns exactly what
+ * {@link getFirstEnabledChild} would — no behaviour change.
+ *
+ * @param item The subtree root to descend from (typically the menu root).
+ * @returns The first enabled leaf, or `undefined` if the subtree has none.
+ */
+export default function getFirstEnabledLeaf(item) {
+    // Walk the enabled children in order; recurse into any that themselves have
+    // children (a group), and backtrack to the next sibling if a branch dead-ends
+    // (e.g. a group whose items are all disabled). An enabled child with no
+    // children of its own IS the leaf we want.
+    for (const child of item.items ?? []) {
+        if (child.disabled)
+            continue;
+        if (child.items?.length) {
+            // A container (group / submenu parent): descend, but keep scanning
+            // siblings if this branch has no enabled leaf (e.g. all items disabled).
+            const leaf = getFirstEnabledLeaf(child);
+            if (leaf)
+                return leaf;
+        }
+        else {
+            // An enabled node with no children of its own — the first real leaf.
+            return child;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=getFirstEnabledLeaf.js.map

package/dist/esm/lib/navigation/getFirstEnabledLeaf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFirstEnabledLeaf.js","sourceRoot":"","sources":["../../../../src/lib/navigation/getFirstEnabledLeaf.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,UAAU,mBAAmB,CACzC,IAAc;IAEd,4EAA4E;IAC5E,8EAA8E;IAC9E,wEAAwE;IACxE,2CAA2C;IAC3C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,QAAQ;YAAE,SAAS;QAC7B,IAAI,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;YACxB,mEAAmE;YACnE,yEAAyE;YACzE,MAAM,IAAI,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;YACxC,IAAI,IAAI;gBAAE,OAAO,IAAI,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,qEAAqE;YACrE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/esm/lib/navigation/index.js

@@ -1,7 +1,9 @@
 export { annotateTree } from "./annotateTree.js";
+export { default as createCrossGroupStateReducer } from "./createCrossGroupStateReducer.js";
 export { default as createNavigationReducer } from "./createNavigationReducer.js";
 export { default as findAncestorPath } from "./findAncestorPath.js";
 export { default as getFirstEnabledChild } from "./getFirstEnabledChild.js";
+export { default as getFirstEnabledLeaf } from "./getFirstEnabledLeaf.js";
 export { getItemId } from "./getItemId.js";
 export { default as getLastEnabledChild } from "./getLastEnabledChild.js";
 export { default as getParentItem } from "./getParentItem.js";

package/dist/esm/lib/navigation/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,OAAO,IAAI,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AAE5F,OAAO,EAAE,OAAO,IAAI,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAQ9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/esm/lib/navigation/prepareIndex.js

@@ -8,8 +8,10 @@ import { getItemId } from "./getItemId.js";
 export function prepareIndex(root) {
     const index = {};
     const stack = [root];
-    while (stack.length > 0) {
-        const item = stack.pop();
+    // Drain the stack by popping into the loop condition: `item` narrows to a
+    // defined `_Item<T>` inside the loop with no non-null assertion, and the
+    // only exit is the empty-stack `undefined` — no unreachable guard branch.
+    for (let item = stack.pop(); item !== undefined; item = stack.pop()) {
         const id = getItemId(item);
         index[id] = item;
         if (item.items) {

package/dist/esm/lib/navigation/prepareIndex.js.map

@@ -1 +1 @@
-{"version":3,"file":"prepareIndex.js","sourceRoot":"","sources":["../../../../src/lib/navigation/prepareIndex.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAwB,IAAc;IAChE,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAe,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAG,CAAC;QAC1B,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"prepareIndex.js","sourceRoot":"","sources":["../../../../src/lib/navigation/prepareIndex.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAwB,IAAc;IAChE,MAAM,KAAK,GAAc,EAAE,CAAC;IAC5B,MAAM,KAAK,GAAe,CAAC,IAAI,CAAC,CAAC;IACjC,0EAA0E;IAC1E,yEAAyE;IACzE,0EAA0E;IAC1E,KAAK,IAAI,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,KAAK,SAAS,EAAE,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC;QACpE,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3B,KAAK,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;QACjB,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAChD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types/lib/navigation/createCrossGroupStateReducer.d.ts

@@ -0,0 +1,5 @@
+import type { Item } from "@canonical/ds-types";
+import { type NavigationAction, type NavigationState } from "./navigationTypes.js";
+declare const createCrossGroupStateReducer: <T extends Item = Item>() => (state: NavigationState<T>, action: NavigationAction<T>) => NavigationState<T>;
+export default createCrossGroupStateReducer;
+//# sourceMappingURL=createCrossGroupStateReducer.d.ts.map

package/dist/types/lib/navigation/createCrossGroupStateReducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCrossGroupStateReducer.d.ts","sourceRoot":"","sources":["../../../../src/lib/navigation/createCrossGroupStateReducer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAS,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAGvD,OAAO,EACL,KAAK,gBAAgB,EAErB,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAmG9B,QAAA,MAAM,4BAA4B,GAC/B,CAAC,SAAS,IAAI,GAAG,IAAI,QAEpB,OAAO,eAAe,CAAC,CAAC,CAAC,EACzB,QAAQ,gBAAgB,CAAC,CAAC,CAAC,KAC1B,eAAe,CAAC,CAAC,CAiCnB,CAAC;AAEJ,eAAe,4BAA4B,CAAC"}

package/dist/types/lib/navigation/getFirstEnabledLeaf.d.ts

@@ -0,0 +1,22 @@
+import type { _Item, Item } from "@canonical/ds-types";
+/**
+ * Descend to the first enabled LEAF of a subtree — the first enabled node that
+ * has no enabled children of its own.
+ *
+ * The point of difference from {@link getFirstEnabledChild} is the structural
+ * group layer of a contextual menu. A menu is a `root -> group -> item` tree:
+ * the root's direct children are GROUPS (rendered `role="group"`, never
+ * focusable), and the real `role="menuitem"` nodes live one level deeper.
+ * Highlighting the first *child* of the root lands on a group, so no item
+ * becomes the roving tab stop and arrow keys have no current item to move from.
+ * Descending to the first leaf lands on the first real menuitem instead.
+ *
+ * For a flat `root -> item` tree (e.g. a simple menu with no groups) the first
+ * child is already a leaf, so this returns exactly what
+ * {@link getFirstEnabledChild} would — no behaviour change.
+ *
+ * @param item The subtree root to descend from (typically the menu root).
+ * @returns The first enabled leaf, or `undefined` if the subtree has none.
+ */
+export default function getFirstEnabledLeaf<T extends Item = Item>(item: _Item<T>): _Item<T> | undefined;
+//# sourceMappingURL=getFirstEnabledLeaf.d.ts.map

package/dist/types/lib/navigation/getFirstEnabledLeaf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFirstEnabledLeaf.d.ts","sourceRoot":"","sources":["../../../../src/lib/navigation/getFirstEnabledLeaf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,EAC/D,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,GACb,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,CAkBtB"}

package/dist/types/lib/navigation/index.d.ts

@@ -1,8 +1,10 @@
 export { annotateTree } from "./annotateTree.js";
+export { default as createCrossGroupStateReducer } from "./createCrossGroupStateReducer.js";
 export type { NavigationReducerOptions } from "./createNavigationReducer.js";
 export { default as createNavigationReducer } from "./createNavigationReducer.js";
 export { default as findAncestorPath } from "./findAncestorPath.js";
 export { default as getFirstEnabledChild } from "./getFirstEnabledChild.js";
+export { default as getFirstEnabledLeaf } from "./getFirstEnabledLeaf.js";
 export { getItemId } from "./getItemId.js";
 export { default as getLastEnabledChild } from "./getLastEnabledChild.js";
 export { default as getParentItem } from "./getParentItem.js";

package/dist/types/lib/navigation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,OAAO,IAAI,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,WAAW,EACX,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,4BAA4B,EAAE,MAAM,mCAAmC,CAAC;AAC5F,YAAY,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,OAAO,IAAI,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAClF,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAC5E,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,OAAO,IAAI,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,WAAW,EACX,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,OAAO,IAAI,kBAAkB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/types/lib/navigation/prepareIndex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prepareIndex.d.ts","sourceRoot":"","sources":["../../../../src/lib/navigation/prepareIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAc7E"}
+{"version":3,"file":"prepareIndex.d.ts","sourceRoot":"","sources":["../../../../src/lib/navigation/prepareIndex.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAG/D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAgB7E"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/utils",
   "description": "Standard utility functions for Canonical's Web Engineering team",
-  "version": "0.29.0-experimental.0",
+  "version": "0.30.0",
   "type": "module",
   "module": "dist/esm/index.js",
   "types": "dist/types/index.d.ts",
@@ -45,18 +45,18 @@
     "test:vitest:watch": "vitest"
   },
   "dependencies": {
-    "@canonical/ds-types": "^0.29.0-experimental.0"
+    "@canonical/ds-types": "^0.30.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.28.0",
-    "@canonical/typescript-config": "^0.28.0",
-    "@canonical/webarchitect": "^0.29.0-experimental.0",
+    "@canonical/biome-config": "^0.30.0",
+    "@canonical/typescript-config": "^0.30.0",
+    "@canonical/webarchitect": "^0.30.0",
     "@types/node": "^24.12.0",
     "globals": "^17.4.0",
     "typescript": "^5.9.3",
     "vite": "^8.0.1",
     "vitest": "^4.0.18"
   },
-  "gitHead": "eda67fea634a79b9f77910d3106219efc9b30136"
+  "gitHead": "40fe86ac955473536ac14f074812a9821f5b65c0"
 }