@owlmeans/client-panel 0.1.18-rc.6 → 0.1.18-rc.9

package/README.md

@@ -1,6 +1,7 @@
 # @owlmeans/client-panel
 
-Schema-driven React form components with react-hook-form integration, i18n, and action buttons.
+Schema-driven React form components with react-hook-form integration, i18n, action buttons, and the
+headless navigation model.
 
 ## Overview
 
@@ -9,6 +10,7 @@ Schema-driven React form components with react-hook-form integration, i18n, and
 - `InputCtrl` — labeled input field component backed by react-hook-form
 - `useFormRef()` — hook to get a ref for programmatic form operations
 - `FormOnSubmit` — type for form submission handler functions
+- `usePanelNav()` — the model behind a two-layer navigation menu (no JSX)
 - Platform-agnostic: used by React web and React Native frontends
 
 ## Installation
@@ -81,6 +83,62 @@ type FormOnSubmit<T> = (data: T) => void | Promise<void>
 
 Derives default form values from an AJV schema's `default` fields.
 
+## Navigation model
+
+Navigation is declared as data and rendered by the platform package
+(`@owlmeans/web-panel` ships `NavLayout` / `TopNav` / `SideNav` / `Footer`). This package holds only
+the model, so both levels of the menu agree on what is active.
+
+```typescript
+import { usePanelNav } from '@owlmeans/client-panel'
+import type { PanelNavConfig } from '@owlmeans/client-panel'
+
+const config: PanelNavConfig = {
+  sections: [
+    { name: 'home', label: 'Home', items: [{ alias: HOME, label: 'Overview' }] },
+    { name: 'demo', items: [{ alias: web.session }, { alias: web.about }] },
+  ],
+}
+
+const model = usePanelNav(config)
+```
+
+### Types
+
+- `PanelNavItem` — `{ alias, label?, Icon?, hidden? }`; one screen, addressed by entrypoint alias,
+  never by URL.
+- `PanelNavSection` — `{ name, label?, items, hidden? }`; the first menu level. Pressing it goes to
+  the first visible item.
+- `PanelNavConfig` — `{ sections }`.
+- `PanelNavLink` — `{ alias? | href?, label?, open? }`; a footer link.
+- `NavTranslate` — `(key, defaultValue) => string`.
+
+### `usePanelNav(config): PanelNavModel`
+
+Returns `sections` (with `hidden` filtered out), `current` (the active screen's alias or null),
+`active` (its section), `showSide`, `isSectionActive` / `isItemActive`, `goSection` / `goItem`
+(each returning a handler), and `hrefOf(target)`.
+
+- `showSide` is false when the active section holds a single screen — that is where the "one screen,
+  no second level" rule lives; a renderer asks the model rather than counting items.
+- The current screen resolves from the router's `location.state.alias` when present, and otherwise
+  from the pathname matched against resolved entrypoint paths — exact first, then longest prefix.
+  Both are needed: `state` is `window.history.state`, so it is empty on a hard load or deep link. A
+  screen listed in no section resolves its section by walking `getParentAlias()` upward.
+- `hrefOf` resolves a real URL synchronously so a menu entry can be a proper link (focusable,
+  keyboard-operable, openable in a new tab). It returns `undefined` for a path carrying route
+  parameters.
+
+### `resolveNavLabel(translate, label, key, alias)`
+
+Resolves a label as literal `label` → `translate(key, defaultNavLabel(alias))` → the humanized
+alias. `translate` always reaches a component as a **prop**, defaulting to `defaultNavTranslate`
+(which returns the fallback) — a menu must never read an i18n context implicitly, because an app
+mounted without an i18n provider throws inside render and blanks the page. `defaultNavLabel`
+humanizes the last alias segment
+(`my-app:web:user-list` → `User list`). Default key families are `nav.<section>` and
+`modules.<alias>`.
+
 ## Related Packages
 
 - [`@owlmeans/client`](../client) — `useContext`, `useNavigate` used within form components

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/client-panel",
-  "version": "0.1.18-rc.6",
-  "generatedAt": "2026-08-18T14:48:00.543Z",
+  "version": "0.1.18-rc.9",
+  "generatedAt": "2026-08-24T21:14:00.134Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/client-panel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: client-panel
-description: How to use @owlmeans/client-panel — reusable cross-platform UI panel + form components (auth screens, layouts) shared by web-panel and native-panel. Auto-invoked when importing panel components.
+description: How to use @owlmeans/client-panel — reusable cross-platform UI panel + form components (auth screens, layouts) and the headless navigation model (usePanelNav) shared by web-panel and native-panel. Auto-invoked when importing panel components or building a navigation menu.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,13 +8,16 @@ user-invocable: false
 # @owlmeans/client-panel
 
 **Layer:** Client
-**Install:** `"@owlmeans/client-panel": "^0.1.18-rc.6"` in `dependencies`
+**Install:** `"@owlmeans/client-panel": "^0.1.18-rc.9"` in `dependencies`
 
 ## Key Exports
 
 | Export | Description |
 |--------|-------------|
 | `components` submodule | Cross-platform panel/form components |
+| `usePanelNav(config)` | Headless navigation model behind a two-layer menu |
+| `resolveNavLabel`, `defaultNavLabel`, `defaultNavTranslate` | Label resolution helpers |
+| `PanelNavConfig`, `PanelNavSection`, `PanelNavItem`, `PanelNavLink`, `PanelNavModel`, `NavTranslate` | Navigation types |
 | `helpers` submodule | Layout / form helpers |
 
 ## Subpath Exports
@@ -29,9 +32,63 @@ import { Panel } from '@owlmeans/client-panel'
 import { LoginPanel } from '@owlmeans/client-panel/auth'
 ```
 
-`@owlmeans/web-panel` re-exports these and provides the Material-UI implementations.
+`@owlmeans/web-panel` re-exports these and provides the rendered implementations.
+
+## Navigation model — `usePanelNav`
+
+The **model lives here, the JSX lives in the platform package** — the same split the form and panel
+components already use. `usePanelNav` is headless and cross-platform; `@owlmeans/web-panel` renders
+it as `TopNav`/`SideNav`/`NavLayout`. Never put a rendered menu in this package, and never
+re-derive active state in a renderer.
+
+Navigation is declared as data. A **section** is the first menu level; its **items** are the screens
+the second level offers while that section is active. An item addresses a frontend entrypoint by
+`alias` and never carries a URL — the router resolves it, so a path that changes shape stays correct
+everywhere it is rendered.
+
+```ts
+import { usePanelNav } from '@owlmeans/client-panel'
+import type { PanelNavConfig } from '@owlmeans/client-panel'
+
+const config: PanelNavConfig = {
+  sections: [
+    { name: 'home', label: 'Home', items: [{ alias: HOME, label: 'Overview' }] },
+    { name: 'demo', items: [{ alias: web.session }, { alias: web.about }] },
+  ],
+}
+
+const model = usePanelNav(config)
+```
+
+`PanelNavModel` carries `sections` (with `hidden` filtered out), `current` (the active screen's
+alias, or null), `active` (its section), `showSide`, `isSectionActive` / `isItemActive`,
+`goSection` / `goItem` (each returning a handler), and `hrefOf`.
+
+- **`showSide` owns the one-screen rule.** It is false when the active section holds a single
+  screen — a second level offering the page you are already on is noise. A renderer asks the model;
+  it does not count items itself.
+- **Label resolution never touches i18n implicitly.** `NavTranslate` is a `(key, defaultValue) =>
+  string` **prop**, defaulting to `defaultNavTranslate`, which returns the fallback. An app mounted
+  without an i18n provider (`renderApp` from `@owlmeans/web-client` mounts none) crashes if a menu
+  reaches for the panel i18n context: the hook dereferences `i18n.options` on the empty object
+  `react-i18next` returns without an instance, and a throw inside render blanks the whole app.
+  `resolveNavLabel(translate, label, key, alias)` applies the order — literal `label` →
+  `translate(key, humanized)` → `defaultNavLabel(alias)`, which humanizes the last alias segment
+  (`my-app:web:user-list` → `User list`). Default key families: `nav.<name>` for sections,
+  `modules.<alias>` for items and footer links.
+- **Resolving the current screen needs two sources.** The router's `location.state.alias` is
+  authoritative but is `window.history.state`, so it is null until the first in-app navigation — on
+  a hard page load or a deep link a menu keyed on it alone highlights nothing, on exactly the entry
+  that matters most. The pathname is the fallback: resolved entrypoint paths are matched exactly
+  first, then by longest prefix, so a detail screen under a listed one still belongs to its section.
+  A screen listed in no section resolves its section by walking `getParentAlias()` upward.
+- **`hrefOf` gives a menu entry a real URL**, resolved synchronously from
+  `context.entrypoint(alias).getPath()`. It returns undefined for a path carrying route parameters
+  (`:id`) — there is no honest URL for a screen whose address is not known yet. An alias the app
+  never elevated resolves to null and is skipped rather than taking the menu down.
 
 ## Depends On
 
-- `@owlmeans/client`, `@owlmeans/client-auth`, `@owlmeans/client-i18n`
+- `@owlmeans/client`, `@owlmeans/client-i18n`, `@owlmeans/client-entrypoint`, `@owlmeans/client-route`,
+  `@owlmeans/entrypoint`, `@owlmeans/error`
 - `react` (peer)

package/build/components/index.d.ts

@@ -1,6 +1,7 @@
 export type * from './types.js';
 export * from './form/index.js';
 export * from './layout/index.js';
+export * from './nav/index.js';
 export * from './context.js';
 export * from './consts.js';
 export * from './status.js';

package/build/components/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/components/index.js

@@ -1,5 +1,6 @@
 export * from './form/index.js';
 export * from './layout/index.js';
+export * from './nav/index.js';
 export * from './context.js';
 export * from './consts.js';
 export * from './status.js';

package/build/components/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAEA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAEA,cAAc,iBAAiB,CAAA;AAC/B,cAAc,mBAAmB,CAAA;AACjC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,cAAc,CAAA;AAC5B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA"}

package/build/components/nav/helper.d.ts

@@ -0,0 +1,21 @@
+import type { NavTranslate, PanelNavConfig, PanelNavModel } from './types.js';
+/** Default resolver: no i18n, the caller's fallback wins. See {@link NavTranslate}. */
+export declare const defaultNavTranslate: NavTranslate;
+/**
+ * Turn an alias into something readable — `my-app:web:user-list` becomes `User list`.
+ * The last segment is the meaningful one; the prefixes address the app, not the screen.
+ */
+export declare const defaultNavLabel: (alias: string) => string;
+export declare const resolveNavLabel: (translate: NavTranslate, label: string | undefined, key: string, alias?: string) => string;
+/**
+ * The navigation model behind both menus.
+ *
+ * Resolving the CURRENT screen has two sources, and both are needed. The router carries the
+ * alias in `location.state`, which is authoritative — but `state` is `window.history.state`,
+ * so it is null until the first in-app navigation: on a hard page load or a deep link there
+ * is nothing there, and a menu keyed on it alone highlights nothing on exactly the entry that
+ * matters most. The pathname is the fallback: entrypoint paths are resolved by the time the
+ * router renders, so matching them is a lookup, not a guess.
+ */
+export declare const usePanelNav: (config: PanelNavConfig) => PanelNavModel;
+//# sourceMappingURL=helper.d.ts.map

package/build/components/nav/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../src/components/nav/helper.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,cAAc,EAAgB,aAAa,EAAmB,MAAM,YAAY,CAAA;AAE5G,uFAAuF;AACvF,eAAO,MAAM,mBAAmB,EAAE,YAAmD,CAAA;AAErF;;;GAGG;AACH,eAAO,MAAM,eAAe,UAAW,MAAM,KAAG,MAK/C,CAAA;AAED,eAAO,MAAM,eAAe,cACf,YAAY,SAAS,MAAM,GAAG,SAAS,OAAO,MAAM,UAAU,MAAM,KAC9E,MAAgE,CAAA;AAQnE;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,WAAY,cAAc,KAAG,aA6FpD,CAAA"}

package/build/components/nav/helper.js

@@ -0,0 +1,111 @@
+import { useMemo } from 'react';
+import { useContext, useNavigate } from '@owlmeans/client';
+/** Default resolver: no i18n, the caller's fallback wins. See {@link NavTranslate}. */
+export const defaultNavTranslate = (_key, defaultValue) => defaultValue;
+/**
+ * Turn an alias into something readable — `my-app:web:user-list` becomes `User list`.
+ * The last segment is the meaningful one; the prefixes address the app, not the screen.
+ */
+export const defaultNavLabel = (alias) => {
+    const segment = alias.split(/[:.]/).filter(part => part !== '').pop() ?? alias;
+    const words = segment.replace(/[-_]+/g, ' ').trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+};
+export const resolveNavLabel = (translate, label, key, alias) => label ?? translate(key, defaultNavLabel(alias ?? key));
+const visibleItems = (section) => section.items.filter(item => item.hidden !== true);
+const normalizePath = (path) => path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+/**
+ * The navigation model behind both menus.
+ *
+ * Resolving the CURRENT screen has two sources, and both are needed. The router carries the
+ * alias in `location.state`, which is authoritative — but `state` is `window.history.state`,
+ * so it is null until the first in-app navigation: on a hard page load or a deep link there
+ * is nothing there, and a menu keyed on it alone highlights nothing on exactly the entry that
+ * matters most. The pathname is the fallback: entrypoint paths are resolved by the time the
+ * router renders, so matching them is a lookup, not a guess.
+ */
+export const usePanelNav = (config) => {
+    const context = useContext();
+    const nav = useNavigate();
+    const location = context.router().useLocation();
+    const state = location.state;
+    const pathname = location.pathname;
+    return useMemo(() => {
+        const sections = config.sections
+            .filter(section => section.hidden !== true)
+            .map(section => ({ ...section, items: visibleItems(section) }));
+        const pathOf = (alias) => {
+            try {
+                return normalizePath(context.entrypoint(alias).getPath());
+            }
+            catch {
+                // An alias the app never elevated addresses nothing — it cannot be the current screen,
+                // and it must not take the menu down with it.
+                return null;
+            }
+        };
+        const all = sections.flatMap(section => section.items);
+        let current = state?.alias ?? null;
+        if (current == null) {
+            const here = normalizePath(pathname);
+            const exact = all.find(item => pathOf(item.alias) === here);
+            if (exact != null) {
+                current = exact.alias;
+            }
+            else {
+                // Longest prefix: a detail screen under a listed one still belongs to its section.
+                const prefixed = all
+                    .map(item => ({ item, path: pathOf(item.alias) }))
+                    .filter((entry) => entry.path != null && entry.path !== '/' && here.startsWith(`${entry.path}/`))
+                    .sort((a, b) => b.path.length - a.path.length)[0];
+                current = prefixed?.item.alias ?? null;
+            }
+        }
+        const sectionOf = (alias) => alias == null ? null : sections.find(section => section.items.some(item => item.alias === alias)) ?? null;
+        let active = sectionOf(current);
+        if (active == null && current != null) {
+            // The current screen is not listed anywhere — walk up to the ancestor that is, so a
+            // nested screen keeps its section (and its side menu) rather than clearing the chrome.
+            let alias = current;
+            const seen = new Set();
+            while (alias != null && !seen.has(alias)) {
+                seen.add(alias);
+                try {
+                    alias = context.entrypoint(alias).getParentAlias() ?? null;
+                }
+                catch {
+                    alias = null;
+                }
+                const found = sectionOf(alias);
+                if (found != null) {
+                    active = found;
+                    break;
+                }
+            }
+        }
+        const isItemActive = (item) => item.alias === current;
+        const isSectionActive = (section) => active != null && section.name === active.name;
+        return {
+            sections,
+            current,
+            active,
+            showSide: active != null && active.items.length > 1,
+            isSectionActive,
+            isItemActive,
+            goSection: section => {
+                const first = section.items[0];
+                return first != null ? nav.press(first.alias) : () => { };
+            },
+            goItem: item => nav.press(item.alias),
+            hrefOf: target => {
+                const alias = 'alias' in target ? target.alias : target.items[0]?.alias;
+                if (alias == null) {
+                    return undefined;
+                }
+                const path = pathOf(alias);
+                return path == null || path.includes(':') ? undefined : path;
+            },
+        };
+    }, [config, pathname, state?.alias, context, nav]);
+};
+//# sourceMappingURL=helper.js.map

package/build/components/nav/helper.js.map

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

package/build/components/nav/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './types.js';
+export * from './helper.js';
+//# sourceMappingURL=index.d.ts.map

package/build/components/nav/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/nav/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA"}

package/build/components/nav/index.js

@@ -0,0 +1,2 @@
+export * from './helper.js';
+//# sourceMappingURL=index.js.map

package/build/components/nav/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/components/nav/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA"}

package/build/components/nav/types.d.ts

@@ -0,0 +1,76 @@
+import type { ComponentType } from 'react';
+/**
+ * One screen in the navigation — the second menu level.
+ *
+ * `alias` addresses a frontend entrypoint, so an item never carries a URL: the router
+ * resolves it, and a path that changes shape stays correct everywhere it is rendered.
+ */
+export interface PanelNavItem {
+    alias: string;
+    /** Literal label. Absent, the label is resolved through `translate` and falls back to a humanized alias. */
+    label?: string;
+    Icon?: ComponentType<{
+        className?: string;
+    }>;
+    hidden?: boolean;
+}
+/**
+ * One section — the first menu level. Its items are the screens the side menu offers
+ * while the section is active.
+ */
+export interface PanelNavSection {
+    /** Stable key. Also the default translation key (`nav.<name>`). */
+    name: string;
+    label?: string;
+    /** Ordered. The first visible item is where pressing the section navigates. */
+    items: PanelNavItem[];
+    hidden?: boolean;
+}
+export interface PanelNavConfig {
+    sections: PanelNavSection[];
+}
+/** A footer link: exactly one of `alias` (an entrypoint) or `href` (anything else). */
+export interface PanelNavLink {
+    alias?: string;
+    href?: string;
+    label?: string;
+    /** Open in a new tab. */
+    open?: boolean;
+}
+/**
+ * Resolves a label from a translation key.
+ *
+ * It is a PROP, never an implicit context read: an app that mounts without an i18n provider
+ * (`renderApp` from `@owlmeans/web-client` does) must still render a menu, and reaching for
+ * the panel i18n context there throws inside the render tree and blanks the whole app.
+ * The default returns the fallback, so literal labels work with no i18n at all.
+ */
+export interface NavTranslate {
+    (key: string, defaultValue: string): string;
+}
+export interface PanelNavModel {
+    /** Sections and items with `hidden` filtered out. */
+    sections: PanelNavSection[];
+    /** Alias of the screen currently rendered, when it could be resolved. */
+    current: string | null;
+    active: PanelNavSection | null;
+    /**
+     * Whether the side menu carries anything worth showing — false when the active section
+     * holds a single screen, which is the whole point: one screen needs no second level.
+     */
+    showSide: boolean;
+    isSectionActive: (section: PanelNavSection) => boolean;
+    isItemActive: (item: PanelNavItem) => boolean;
+    goSection: (section: PanelNavSection) => () => void;
+    goItem: (item: PanelNavItem) => () => void;
+    /**
+     * The resolved URL of a section's landing screen, when it has one.
+     *
+     * A menu entry navigates through `nav.press`, but it still has to BE a link: an `<a>`
+     * without `href` is not focusable, does not answer the keyboard, and cannot be opened in a
+     * new tab. Undefined for a path carrying route parameters — there is no honest URL to show
+     * for a screen whose address is not known yet.
+     */
+    hrefOf: (target: PanelNavItem | PanelNavSection) => string | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/components/nav/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/nav/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,4GAA4G;IAC5G,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,aAAa,CAAC;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC5C,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+EAA+E;IAC/E,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B;AAED,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yBAAyB;IACzB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAA;CAC5C;AAED,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,QAAQ,EAAE,eAAe,EAAE,CAAA;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,MAAM,EAAE,eAAe,GAAG,IAAI,CAAA;IAC9B;;;OAGG;IACH,QAAQ,EAAE,OAAO,CAAA;IACjB,eAAe,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAA;IACtD,YAAY,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAA;IAC7C,SAAS,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,IAAI,CAAA;IACnD,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,IAAI,CAAA;IAC1C;;;;;;;OAOG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,KAAK,MAAM,GAAG,SAAS,CAAA;CACvE"}

package/build/components/nav/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/components/nav/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/components/nav/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/client-panel",
-  "version": "0.1.18-rc.6",
+  "version": "0.1.18-rc.9",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -36,16 +36,16 @@
   },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
-    "@owlmeans/client": "^0.1.18-rc.6",
-    "@owlmeans/client-i18n": "^0.1.18-rc.6",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.6",
-    "@owlmeans/client-route": "^0.1.18-rc.6",
+    "@owlmeans/client": "^0.1.18-rc.8",
+    "@owlmeans/client-i18n": "^0.1.18-rc.7",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.7",
+    "@owlmeans/client-route": "^0.1.18-rc.7",
     "@owlmeans/error": "^0.1.18-rc.6",
-    "@owlmeans/entrypoint": "^0.1.18-rc.6"
+    "@owlmeans/entrypoint": "^0.1.18-rc.7"
   },
   "peerDependencies": {
     "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/client-auth": "^0.1.18-rc.6",
+    "@owlmeans/client-auth": "^0.1.18-rc.9",
     "@owlmeans/i18n": "^0.1.18-rc.6",
     "@owlmeans/router": "^0.1.18-rc.6",
     "ajv": "*",
@@ -63,7 +63,7 @@
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
     "@owlmeans/auth": "^0.1.18-rc.6",
-    "@owlmeans/client-auth": "^0.1.18-rc.6",
+    "@owlmeans/client-auth": "^0.1.18-rc.9",
     "@types/react": "^19.2.17",
     "nodemon": "^3.1.14",
     "react-hook-form": "^7.53.0",

package/src/components/index.ts

@@ -2,6 +2,7 @@ export type * from './types.js'
 
 export * from './form/index.js'
 export * from './layout/index.js'
+export * from './nav/index.js'
 export * from './context.js'
 export * from './consts.js'
 export * from './status.js'

package/src/components/nav/helper.ts

@@ -0,0 +1,136 @@
+import { useMemo } from 'react'
+import type { ClientRoute } from '@owlmeans/client-route'
+import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import type { Location } from '@owlmeans/router'
+import { useContext, useNavigate } from '@owlmeans/client'
+
+import type { NavTranslate, PanelNavConfig, PanelNavItem, PanelNavModel, PanelNavSection } from './types.js'
+
+/** Default resolver: no i18n, the caller's fallback wins. See {@link NavTranslate}. */
+export const defaultNavTranslate: NavTranslate = (_key, defaultValue) => defaultValue
+
+/**
+ * Turn an alias into something readable — `my-app:web:user-list` becomes `User list`.
+ * The last segment is the meaningful one; the prefixes address the app, not the screen.
+ */
+export const defaultNavLabel = (alias: string): string => {
+  const segment = alias.split(/[:.]/).filter(part => part !== '').pop() ?? alias
+  const words = segment.replace(/[-_]+/g, ' ').trim()
+
+  return words.charAt(0).toUpperCase() + words.slice(1)
+}
+
+export const resolveNavLabel = (
+  translate: NavTranslate, label: string | undefined, key: string, alias?: string
+): string => label ?? translate(key, defaultNavLabel(alias ?? key))
+
+const visibleItems = (section: PanelNavSection): PanelNavItem[] =>
+  section.items.filter(item => item.hidden !== true)
+
+const normalizePath = (path: string): string =>
+  path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path
+
+/**
+ * The navigation model behind both menus.
+ *
+ * Resolving the CURRENT screen has two sources, and both are needed. The router carries the
+ * alias in `location.state`, which is authoritative — but `state` is `window.history.state`,
+ * so it is null until the first in-app navigation: on a hard page load or a deep link there
+ * is nothing there, and a menu keyed on it alone highlights nothing on exactly the entry that
+ * matters most. The pathname is the fallback: entrypoint paths are resolved by the time the
+ * router renders, so matching them is a lookup, not a guess.
+ */
+export const usePanelNav = (config: PanelNavConfig): PanelNavModel => {
+  const context = useContext()
+  const nav = useNavigate()
+  const location: Location<ClientRoute> = context.router().useLocation()
+
+  const state = location.state as ClientRoute | null
+  const pathname = location.pathname
+
+  return useMemo(() => {
+    const sections = config.sections
+      .filter(section => section.hidden !== true)
+      .map(section => ({ ...section, items: visibleItems(section) }))
+
+    const pathOf = (alias: string): string | null => {
+      try {
+        return normalizePath(context.entrypoint<ClientEntrypoint<string>>(alias).getPath())
+      } catch {
+        // An alias the app never elevated addresses nothing — it cannot be the current screen,
+        // and it must not take the menu down with it.
+        return null
+      }
+    }
+
+    const all = sections.flatMap(section => section.items)
+
+    let current: string | null = state?.alias ?? null
+    if (current == null) {
+      const here = normalizePath(pathname)
+      const exact = all.find(item => pathOf(item.alias) === here)
+      if (exact != null) {
+        current = exact.alias
+      } else {
+        // Longest prefix: a detail screen under a listed one still belongs to its section.
+        const prefixed = all
+          .map(item => ({ item, path: pathOf(item.alias) }))
+          .filter((entry): entry is { item: PanelNavItem, path: string } =>
+            entry.path != null && entry.path !== '/' && here.startsWith(`${entry.path}/`))
+          .sort((a, b) => b.path.length - a.path.length)[0]
+        current = prefixed?.item.alias ?? null
+      }
+    }
+
+    const sectionOf = (alias: string | null): PanelNavSection | null =>
+      alias == null ? null : sections.find(section => section.items.some(item => item.alias === alias)) ?? null
+
+    let active = sectionOf(current)
+    if (active == null && current != null) {
+      // The current screen is not listed anywhere — walk up to the ancestor that is, so a
+      // nested screen keeps its section (and its side menu) rather than clearing the chrome.
+      let alias: string | null = current
+      const seen = new Set<string>()
+      while (alias != null && !seen.has(alias)) {
+        seen.add(alias)
+        try {
+          alias = context.entrypoint<ClientEntrypoint<string>>(alias).getParentAlias() ?? null
+        } catch {
+          alias = null
+        }
+        const found = sectionOf(alias)
+        if (found != null) {
+          active = found
+          break
+        }
+      }
+    }
+
+    const isItemActive = (item: PanelNavItem): boolean => item.alias === current
+    const isSectionActive = (section: PanelNavSection): boolean =>
+      active != null && section.name === active.name
+
+    return {
+      sections,
+      current,
+      active,
+      showSide: active != null && active.items.length > 1,
+      isSectionActive,
+      isItemActive,
+      goSection: section => {
+        const first = section.items[0]
+        return first != null ? nav.press(first.alias) : () => {}
+      },
+      goItem: item => nav.press(item.alias),
+      hrefOf: target => {
+        const alias = 'alias' in target ? target.alias : target.items[0]?.alias
+        if (alias == null) {
+          return undefined
+        }
+        const path = pathOf(alias)
+
+        return path == null || path.includes(':') ? undefined : path
+      },
+    }
+  }, [config, pathname, state?.alias, context, nav])
+}

package/src/components/nav/index.ts

@@ -0,0 +1,3 @@
+export type * from './types.js'
+
+export * from './helper.js'

package/src/components/nav/types.ts

@@ -0,0 +1,79 @@
+import type { ComponentType } from 'react'
+
+/**
+ * One screen in the navigation — the second menu level.
+ *
+ * `alias` addresses a frontend entrypoint, so an item never carries a URL: the router
+ * resolves it, and a path that changes shape stays correct everywhere it is rendered.
+ */
+export interface PanelNavItem {
+  alias: string
+  /** Literal label. Absent, the label is resolved through `translate` and falls back to a humanized alias. */
+  label?: string
+  Icon?: ComponentType<{ className?: string }>
+  hidden?: boolean
+}
+
+/**
+ * One section — the first menu level. Its items are the screens the side menu offers
+ * while the section is active.
+ */
+export interface PanelNavSection {
+  /** Stable key. Also the default translation key (`nav.<name>`). */
+  name: string
+  label?: string
+  /** Ordered. The first visible item is where pressing the section navigates. */
+  items: PanelNavItem[]
+  hidden?: boolean
+}
+
+export interface PanelNavConfig {
+  sections: PanelNavSection[]
+}
+
+/** A footer link: exactly one of `alias` (an entrypoint) or `href` (anything else). */
+export interface PanelNavLink {
+  alias?: string
+  href?: string
+  label?: string
+  /** Open in a new tab. */
+  open?: boolean
+}
+
+/**
+ * Resolves a label from a translation key.
+ *
+ * It is a PROP, never an implicit context read: an app that mounts without an i18n provider
+ * (`renderApp` from `@owlmeans/web-client` does) must still render a menu, and reaching for
+ * the panel i18n context there throws inside the render tree and blanks the whole app.
+ * The default returns the fallback, so literal labels work with no i18n at all.
+ */
+export interface NavTranslate {
+  (key: string, defaultValue: string): string
+}
+
+export interface PanelNavModel {
+  /** Sections and items with `hidden` filtered out. */
+  sections: PanelNavSection[]
+  /** Alias of the screen currently rendered, when it could be resolved. */
+  current: string | null
+  active: PanelNavSection | null
+  /**
+   * Whether the side menu carries anything worth showing — false when the active section
+   * holds a single screen, which is the whole point: one screen needs no second level.
+   */
+  showSide: boolean
+  isSectionActive: (section: PanelNavSection) => boolean
+  isItemActive: (item: PanelNavItem) => boolean
+  goSection: (section: PanelNavSection) => () => void
+  goItem: (item: PanelNavItem) => () => void
+  /**
+   * The resolved URL of a section's landing screen, when it has one.
+   *
+   * A menu entry navigates through `nav.press`, but it still has to BE a link: an `<a>`
+   * without `href` is not focusable, does not answer the keyboard, and cannot be opened in a
+   * new tab. Undefined for a path carrying route parameters — there is no honest URL to show
+   * for a screen whose address is not known yet.
+   */
+  hrefOf: (target: PanelNavItem | PanelNavSection) => string | undefined
+}