oihana-next-ui 0.1.47 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oihana-next-ui",
-  "version": "0.1.47",
+  "version": "0.2.0",
   "private": false,
   "description": "Oihana Next.js UI component library — reusable components, hooks and utilities built with React 19, Next.js, Tailwind CSS and DaisyUI",
   "author": {

package/src/app/lab/@tabs/menus/page.js

@@ -1,9 +1,10 @@
 'use client' ;
 
-import FlagMenuDemo       from '@/demo/menus/FlagMenuDemo';
-import MenuNavigationDemo from '@/demo/menus/MenuNavigationDemo';
-import Container          from '@/display/Container' ;
-import Page               from '@/display/Page' ;
+import CollapsePersistenceDemo from '@/demo/menus/CollapsePersistenceDemo';
+import FlagMenuDemo            from '@/demo/menus/FlagMenuDemo';
+import MenuNavigationDemo      from '@/demo/menus/MenuNavigationDemo';
+import Container               from '@/display/Container' ;
+import Page                    from '@/display/Page' ;
 
 /**
  * Toasts showcase page.
@@ -39,6 +40,15 @@ const ToastsShowcase = ({ path = 'app.test' }) =>
                 </div>
             </Container>
 
+            {/* Collapse persistence Demo */}
+            <Container className="flex flex-col gap-4">
+                <h2 className="text-2xl font-bold">Collapse persistence</h2>
+                <p className="opacity-70">
+                    NavigationProvider — defaultMode and storageKey props.
+                </p>
+                <CollapsePersistenceDemo />
+            </Container>
+
         </Page>
     ) ;
 } ;

package/src/components/buttons/RefreshButton.jsx

@@ -38,13 +38,13 @@ import MotionButton from './MotionButton' ;
  */
 const RefreshButton =
 ({
-     color       = 'secondary' ,
-     icon        = MdRefresh ,
-     motion      = Jump ,
+     color = 'secondary' ,
+     icon = MdRefresh ,
+     motion = Jump ,
      motionProps = { delay: 0.3 } ,
-     path        = 'components.buttons.refresh' ,
-     shape       = 'circle' ,
-     size        = 'md' ,
+     path = 'components.buttons.refresh' ,
+     shape = 'circle' ,
+     size = 'md' ,
      ...rest
  }) =>
 (

package/src/components/modals/Modal.jsx

@@ -232,7 +232,7 @@ const Modal =
                     </div>
                 )}
 
-                <div className={`overflow-y-auto h-full p-2 py-4 ${ contentClassName || '' }`}>
+                <div className={ cn( 'overflow-y-auto h-full p-2 py-4' , contentClassName ) }>
                     { children }
                 </div>
 

package/src/contexts/navigation/context.js

@@ -4,6 +4,19 @@ import { createContext } from 'react' ;
  * @typedef {Object} NavigationContextValue
  * @property {Object[] | null} navigation - Current navigation items.
  * @property {(value: Object[]) => void} setNavigation - Function to update navigation.
+ * @property {'open' | 'closed' | 'auto'} defaultMode - Default open/closed
+ *   mode applied to collapse items that have no persisted state and no
+ *   per-item `defaultOpen` override.
+ * @property {Record<string, boolean>} collapses - Per-id open/closed map
+ *   reflecting explicit user choices (post-hydration).
+ * @property {(id: string, open: boolean) => void} setCollapse - Records an
+ *   explicit user choice for a single collapse and persists it when a
+ *   `storageKey` was supplied to the provider.
+ * @property {(id: string, item?: Object) => boolean} getCollapseOpen -
+ *   Returns the effective open state for a collapse, applying the
+ *   priority chain: persisted → auto(pathname) → item.defaultOpen → defaultMode.
+ * @property {string | null} pathname - Current pathname, captured by the
+ *   provider so consumers (e.g. `Collapse`) don't have to read it again.
  */
 
 /**
@@ -15,4 +28,4 @@ const NavigationContext = createContext(
 
 NavigationContext.displayName = 'NavigationContext' ;
 
-export default NavigationContext ;
+export default NavigationContext ;

package/src/contexts/navigation/helpers/collapseStorage.js

@@ -0,0 +1,129 @@
+/**
+ * localStorage helpers for the navigation collapse state.
+ *
+ * @module contexts/navigation/helpers/collapseStorage
+ */
+
+import notEmpty from 'vegas-js-core/src/strings/notEmpty' ;
+
+import {
+    COLLAPSE_STATE_ITEMS_KEY ,
+    COLLAPSE_STATE_VERSION ,
+    COLLAPSE_STATE_VERSION_KEY ,
+} from './constants' ;
+
+/**
+ * Returns true when `window.localStorage` can be read or written.
+ * Catches SSR (no `window`), Safari private mode, disabled storage,
+ * and any other host-thrown error.
+ *
+ * @returns {boolean}
+ */
+const isStorageAvailable = () =>
+{
+    try
+    {
+        return typeof window !== 'undefined'
+            && typeof window.localStorage !== 'undefined' ;
+    }
+    catch
+    {
+        return false ;
+    }
+} ;
+
+/**
+ * Reads the persisted collapse state for a given storage key.
+ *
+ * Returns an empty object when the key is missing/empty, when storage is
+ * unavailable (SSR, private mode, quota errors), when the payload is not
+ * JSON, or when the schema version does not match the current one.
+ *
+ * Never throws.
+ *
+ * @param {string} [key] - Opaque storage key chosen by the consumer.
+ * @returns {Record<string, boolean>} Per-id open/closed map (may be empty).
+ *
+ * @example
+ * ```js
+ * const state = loadCollapseState( 'my-app:nav:v1' ) ;
+ * // → { lab: true, layouts: false }
+ * ```
+ */
+export const loadCollapseState = ( key ) =>
+{
+    if ( !notEmpty( key ) || !isStorageAvailable() )
+    {
+        return {} ;
+    }
+
+    try
+    {
+        const raw = window.localStorage.getItem( key ) ;
+
+        if ( !raw )
+        {
+            return {} ;
+        }
+
+        const parsed = JSON.parse( raw ) ;
+
+        if ( !parsed || typeof parsed !== 'object' )
+        {
+            return {} ;
+        }
+
+        if ( parsed[ COLLAPSE_STATE_VERSION_KEY ] !== COLLAPSE_STATE_VERSION )
+        {
+            return {} ;
+        }
+
+        const items = parsed[ COLLAPSE_STATE_ITEMS_KEY ] ;
+
+        return ( items && typeof items === 'object' ) ? items : {} ;
+    }
+    catch
+    {
+        return {} ;
+    }
+} ;
+
+/**
+ * Persists the per-id open/closed map under the given storage key.
+ *
+ * Silently no-ops when the key is empty, when storage is unavailable, or
+ * when the write fails (quota, locked storage, etc.). Never throws.
+ *
+ * @param {string} [key] - Opaque storage key chosen by the consumer.
+ * @param {Record<string, boolean>} [state] - Per-id open/closed map.
+ * @returns {boolean} `true` when the write succeeded, `false` otherwise.
+ *
+ * @example
+ * ```js
+ * persistCollapseState( 'my-app:nav:v1' , { lab: true } ) ;
+ * ```
+ */
+export const persistCollapseState = ( key , state ) =>
+{
+    if ( !notEmpty( key ) || !isStorageAvailable() )
+    {
+        return false ;
+    }
+
+    try
+    {
+        const payload =
+        {
+            [ COLLAPSE_STATE_VERSION_KEY ] : COLLAPSE_STATE_VERSION ,
+            [ COLLAPSE_STATE_ITEMS_KEY   ] : state ?? {} ,
+        } ;
+
+        window.localStorage.setItem( key , JSON.stringify( payload ) ) ;
+
+        return true ;
+    }
+    catch
+    {
+        return false ;
+    }
+} ;

package/src/contexts/navigation/helpers/constants.js

@@ -0,0 +1,59 @@
+/**
+ * Navigation collapse persistence constants.
+ *
+ * @module contexts/navigation/helpers/constants
+ */
+
+/**
+ * Default-mode identifiers for collapse open/closed state.
+ *
+ * - `OPEN`   — every collapse starts open (current legacy behaviour).
+ * - `CLOSED` — every collapse starts closed.
+ * - `AUTO`   — open when a descendant matches the current pathname,
+ *              closed otherwise.
+ *
+ * @type {Readonly<{ OPEN: 'open', CLOSED: 'closed', AUTO: 'auto' }>}
+ */
+export const COLLAPSE_MODES = Object.freeze
+({
+    OPEN   : 'open' ,
+    CLOSED : 'closed' ,
+    AUTO   : 'auto' ,
+}) ;
+
+/**
+ * Allowed values for the `defaultMode` prop of `NavigationProvider`.
+ *
+ * @type {ReadonlyArray<'open' | 'closed' | 'auto'>}
+ */
+export const COLLAPSE_MODE_VALUES = Object.freeze
+([
+    COLLAPSE_MODES.OPEN ,
+    COLLAPSE_MODES.CLOSED ,
+    COLLAPSE_MODES.AUTO ,
+]) ;
+
+/**
+ * Default mode used when `NavigationProvider` does not receive an explicit
+ * `defaultMode`. Matches the legacy behaviour of `<details open>`.
+ */
+export const DEFAULT_COLLAPSE_MODE = COLLAPSE_MODES.OPEN ;
+
+/**
+ * Schema version of the payload written to `localStorage`.
+ * Bump when the on-disk shape changes — older payloads are then ignored
+ * silently rather than throwing or surfacing stale state.
+ */
+export const COLLAPSE_STATE_VERSION = 1 ;
+
+/**
+ * Key inside the persisted JSON payload that holds the per-id boolean map.
+ * Centralised here so the storage helpers and any future migration code
+ * agree on the same string.
+ */
+export const COLLAPSE_STATE_ITEMS_KEY = 'items' ;
+
+/**
+ * Key inside the persisted JSON payload that holds the schema version.
+ */
+export const COLLAPSE_STATE_VERSION_KEY = 'v' ;

package/src/contexts/navigation/helpers/containsActivePath.js

@@ -0,0 +1,54 @@
+/**
+ * Recursive matcher: tells whether a navigation item (typically a
+ * `COLLAPSE`) contains a descendant `LINK` whose `path` matches the
+ * current pathname.
+ *
+ * @module contexts/navigation/helpers/containsActivePath
+ */
+
+import notEmpty   from 'vegas-js-core/src/strings/notEmpty' ;
+import startsWith from 'vegas-js-core/src/strings/startsWith' ;
+
+/**
+ * Walks the `items` tree under the given navigation node and returns
+ * `true` as soon as one descendant has a `path` that matches `pathname`
+ * with `startsWith`. The match semantics are intentionally identical to
+ * the active-link rule used in `Link.jsx`.
+ *
+ * Pure, no React, no side effects. Safe on `null`/`undefined`.
+ *
+ * @param {Object} [item] - Navigation node (collapse or link).
+ * @param {Object[]} [item.items] - Children of a collapse node.
+ * @param {string} [item.path] - Path of a link node.
+ * @param {string} [pathname] - Current pathname (e.g. from `usePathname`).
+ * @returns {boolean}
+ *
+ * @example
+ * ```js
+ * containsActivePath(
+ *     { items: [ { path: '/lab/grid' } ] } ,
+ *     '/lab/grid'
+ * ) ; // → true
+ * ```
+ */
+const containsActivePath = ( item , pathname ) =>
+{
+    if ( !item || !notEmpty( pathname ) )
+    {
+        return false ;
+    }
+
+    if ( notEmpty( item.path ) && startsWith( pathname , item.path ) )
+    {
+        return true ;
+    }
+
+    if ( !Array.isArray( item.items ) || item.items.length === 0 )
+    {
+        return false ;
+    }
+
+    return item.items.some( ( child ) => containsActivePath( child , pathname ) ) ;
+} ;
+
+export default containsActivePath ;

package/src/contexts/navigation/helpers/findActiveAncestorIds.js

@@ -0,0 +1,78 @@
+/**
+ * Finds the ids of every collapse whose subtree contains the current
+ * pathname.
+ *
+ * @module contexts/navigation/helpers/findActiveAncestorIds
+ */
+
+import notEmpty from 'vegas-js-core/src/strings/notEmpty' ;
+
+import { COLLAPSE } from '../types' ;
+import containsActivePath from './containsActivePath' ;
+
+/**
+ * Walks the navigation tree and returns the id of every `COLLAPSE` node
+ * whose subtree contains a `LINK` matching `pathname`. Order is
+ * outer-first (root collapses come before their nested ones), which is
+ * convenient for callers that want to open ancestors top-down.
+ *
+ * Pure, no React, no side effects. Safe on `null`/`undefined`.
+ *
+ * @param {Object[]} [items] - Navigation tree (typically the provider's
+ *   internal `navigation` array).
+ * @param {string} [pathname] - Current pathname.
+ * @returns {string[]} Array of collapse ids; empty when nothing matches.
+ *
+ * @example
+ * ```js
+ * findActiveAncestorIds(
+ *     [{ id: 'lab', type: 'collapse', items: [
+ *         { id: 'navigation', type: 'collapse', items: [
+ *             { type: 'link', path: '/lab/menus' }
+ *         ] }
+ *     ] }],
+ *     '/lab/menus'
+ * ) ; // → [ 'lab' , 'navigation' ]
+ * ```
+ */
+const findActiveAncestorIds = ( items , pathname ) =>
+{
+    const ids = [] ;
+
+    if ( !Array.isArray( items ) || items.length === 0 || !notEmpty( pathname ) )
+    {
+        return ids ;
+    }
+
+    const walk = ( list ) =>
+    {
+        for ( const item of list )
+        {
+            if ( !item || item.type !== COLLAPSE )
+            {
+                continue ;
+            }
+
+            if ( !containsActivePath( item , pathname ) )
+            {
+                continue ;
+            }
+
+            if ( notEmpty( item.id ) )
+            {
+                ids.push( item.id ) ;
+            }
+
+            if ( Array.isArray( item.items ) && item.items.length > 0 )
+            {
+                walk( item.items ) ;
+            }
+        }
+    } ;
+
+    walk( items ) ;
+
+    return ids ;
+} ;
+
+export default findActiveAncestorIds ;

package/src/contexts/navigation/helpers/mapI18nItem.js

@@ -15,6 +15,8 @@ import mapI18nBadge from './mapI18nBadge'
  * @param {React.ComponentType} [item.Icon] - Icon component.
  * @param {Object} [item.badge] - Badge configuration.
  * @param {Object[]} [item.items] - Child items (for collapse type).
+ * @param {boolean} [item.defaultOpen] - Per-item override for the
+ *   collapse open/closed default. Only meaningful when `type === 'collapse'`.
  * @param {Object} locale - Locale data.
  *
  * @returns {Object} Mapped navigation item with localized label.
@@ -51,7 +53,7 @@ import mapI18nBadge from './mapI18nBadge'
  */
 const mapI18nItem = ( item , locale ) =>
 {
-    const { badge , className , Icon , id , items , label , path , type } = item ;
+    const { badge , className , defaultOpen , Icon , id , items , label , path , type } = item ;
 
     const mappedItems = type === COLLAPSE && items?.length > 0
         ? items.map( ( child ) => mapI18nItem( child , locale ) )
@@ -64,14 +66,15 @@ const mapI18nItem = ( item , locale ) =>
     const mappedLabel = locale?.[ id ] ?? label ?? '' ;
 
     return {
-        badge     : mappedBadge ,
-        className ,
-        Icon      ,
-        id        ,
-        items     : mappedItems ,
-        label     : mappedLabel ,
-        path      ,
-        type      ,
+        badge       : mappedBadge ,
+        className   ,
+        defaultOpen ,
+        Icon        ,
+        id          ,
+        items       : mappedItems ,
+        label       : mappedLabel ,
+        path        ,
+        type        ,
     } ;
 } ;
 

package/src/contexts/navigation/helpers/resolveCollapseOpen.js

@@ -0,0 +1,62 @@
+/**
+ * Pure resolver for the open/closed state of a single collapse node.
+ *
+ * @module contexts/navigation/helpers/resolveCollapseOpen
+ */
+
+import notEmpty from 'vegas-js-core/src/strings/notEmpty' ;
+
+import { COLLAPSE_MODES , DEFAULT_COLLAPSE_MODE } from './constants' ;
+import containsActivePath from './containsActivePath' ;
+
+/**
+ * Resolves the effective open state for a collapse, in this priority
+ * order:
+ *
+ * 1. Persisted user choice (`persisted[id]`) — explicit win.
+ * 2. Auto-mode pathname match — only when `defaultMode === 'auto'`.
+ * 3. Per-item `defaultOpen` — author override on the item.
+ * 4. Global `defaultMode` — `'open'` truthy, anything else falsy.
+ *
+ * Pure: no React, no DOM, no storage access. Safe to call during render.
+ *
+ * @param {Object} params
+ * @param {string} [params.id] - Item id (used to look up `persisted`).
+ * @param {Object} [params.item] - The collapse item itself (read for
+ *   `defaultOpen` and walked for the auto-mode pathname match).
+ * @param {Record<string, boolean>} [params.persisted] - Map loaded from
+ *   storage; missing keys mean "no user choice yet".
+ * @param {string} [params.pathname] - Current pathname. Only consulted
+ *   in `auto` mode.
+ * @param {'open' | 'closed' | 'auto'} [params.defaultMode] - Global
+ *   provider mode. Defaults to `'open'`.
+ * @returns {boolean} Effective open state.
+ */
+const resolveCollapseOpen = (
+{
+    id ,
+    item ,
+    persisted ,
+    pathname ,
+    defaultMode = DEFAULT_COLLAPSE_MODE ,
+} = {} ) =>
+{
+    if ( notEmpty( id ) && persisted && Object.hasOwn( persisted , id ) )
+    {
+        return Boolean( persisted[ id ] ) ;
+    }
+
+    if ( defaultMode === COLLAPSE_MODES.AUTO && containsActivePath( item , pathname ) )
+    {
+        return true ;
+    }
+
+    if ( item && typeof item.defaultOpen === 'boolean' )
+    {
+        return item.defaultOpen ;
+    }
+
+    return defaultMode === COLLAPSE_MODES.OPEN ;
+} ;
+
+export default resolveCollapseOpen ;

package/src/contexts/navigation/provider.js

@@ -1,32 +1,51 @@
 'use client' ;
 
-import { useState } from 'react' ;
+import { useCallback , useEffect , useMemo , useRef , useState } from 'react' ;
+
+import { usePathname } from 'next/navigation' ;
 
 import useI18n from '../locale/useI18n' ;
 
+import {
+    loadCollapseState ,
+    persistCollapseState ,
+} from './helpers/collapseStorage' ;
+import {
+    COLLAPSE_MODES ,
+    COLLAPSE_MODE_VALUES ,
+    DEFAULT_COLLAPSE_MODE ,
+} from './helpers/constants' ;
+import findActiveAncestorIds from './helpers/findActiveAncestorIds' ;
 import mapI18nItem from './helpers/mapI18nItem' ;
+import resolveCollapseOpen from './helpers/resolveCollapseOpen' ;
 
 import NavigationContext from './context' ;
 
 /**
- * Provides navigation context with i18n support.
+ * Provides navigation context with i18n support and optional collapse
+ * state persistence.
  *
  * @param {Object} props
  * @param {React.ReactNode} props.children - Child components.
  * @param {Object[]} props.defaultNavigation - Default navigation items.
  * @param {string} [props.i18nPath='navigation'] - Locale path for navigation labels.
+ * @param {'open' | 'closed' | 'auto'} [props.defaultMode='open'] - Open/closed
+ *   default applied to collapse items. `'auto'` opens collapses whose
+ *   subtree contains the current pathname.
+ * @param {string} [props.storageKey] - Opt-in localStorage key. When
+ *   omitted, collapse state lives only in memory and resets on reload.
+ *   Choose a namespaced, versioned key in your app (e.g. `'my-app:nav:v1'`)
+ *   to avoid cross-app collisions and to allow future schema bumps.
  *
  * @returns {React.ReactElement} The provider component.
  *
  * @example
  * ```jsx
- * const navigation =
- * [
- *     { id: 'home' , path: '/' , Icon: HomeIcon } ,
- *     { id: 'about' , path: '/about' , Icon: InfoIcon } ,
- * ] ;
- *
- * <NavigationProvider defaultNavigation={ navigation }>
+ * <NavigationProvider
+ *     defaultNavigation = { navigation }
+ *     defaultMode       = "auto"
+ *     storageKey        = "my-app:nav:v1"
+ * >
  *     { children }
  * </NavigationProvider>
  * ```
@@ -36,9 +55,16 @@ const NavigationProvider =
     children ,
     defaultNavigation ,
     i18nPath = 'navigation' ,
+    defaultMode : defaultModeProp = DEFAULT_COLLAPSE_MODE ,
+    storageKey ,
 } ) =>
 {
-    const locale = useI18n( i18nPath ) ;
+    const defaultMode = COLLAPSE_MODE_VALUES.includes( defaultModeProp )
+                      ? defaultModeProp
+                      : DEFAULT_COLLAPSE_MODE ;
+
+    const locale   = useI18n( i18nPath ) ;
+    const pathname = usePathname() ;
 
     const [ _navigation , setNavigation ] = useState( defaultNavigation ) ;
 
@@ -46,11 +72,137 @@ const NavigationProvider =
                      ? _navigation.map( ( item ) => mapI18nItem( item , locale ) )
                      : null ;
 
+    // Collapse state is initialised empty so the first server render is
+    // deterministic (no localStorage on the server). Hydration happens in
+    // the effect below, after mount, which never causes a hydration
+    // mismatch because `<details>` is forgiving of an `open` flip.
+    const [ collapses , setCollapses ] = useState( {} ) ;
+
+    const hydratedRef = useRef( false ) ;
+
+    useEffect( () =>
+    {
+        if ( hydratedRef.current )
+        {
+            return ;
+        }
+
+        hydratedRef.current = true ;
+
+        const loaded = loadCollapseState( storageKey ) ;
+
+        if ( loaded && Object.keys( loaded ).length > 0 )
+        {
+            setCollapses( loaded ) ;
+        }
+    }
+    , [ storageKey ] ) ;
+
+    // Auto-mode "follow the route" behaviour: on every real pathname
+    // transition (not on the initial mount, not on reload), force-open
+    // every collapse whose subtree contains the new pathname and
+    // persist the change. This mirrors what VS Code / GitHub sidebars
+    // do — navigating into a nested page reveals the hosting branch
+    // even if the user had collapsed it earlier. The user can still
+    // collapse it back; the override only kicks in on the next real
+    // pathname change. The initial mount is skipped on purpose so that
+    // a refresh on the current page respects the persisted choice.
+    const previousPathnameRef = useRef( null ) ;
+
+    useEffect( () =>
+    {
+        const previous = previousPathnameRef.current ;
+        previousPathnameRef.current = pathname ;
+
+        if ( defaultMode !== COLLAPSE_MODES.AUTO || !pathname || previous === null || previous === pathname )
+        {
+            return ;
+        }
+
+        const ancestorIds = findActiveAncestorIds( _navigation , pathname ) ;
+
+        if ( ancestorIds.length === 0 )
+        {
+            return ;
+        }
+
+        setCollapses( ( previous ) =>
+        {
+            let changed = false ;
+            const next = { ...previous } ;
+
+            for ( const id of ancestorIds )
+            {
+                if ( next[ id ] !== true )
+                {
+                    next[ id ] = true ;
+                    changed    = true ;
+                }
+            }
+
+            if ( !changed )
+            {
+                return previous ;
+            }
+
+            persistCollapseState( storageKey , next ) ;
+
+            return next ;
+        } ) ;
+    }
+    , [ pathname , defaultMode , storageKey , _navigation ] ) ;
+
+    const setCollapse = useCallback( ( id , open ) =>
+    {
+        if ( !id )
+        {
+            return ;
+        }
+
+        setCollapses( ( previous ) =>
+        {
+            if ( previous[ id ] === open )
+            {
+                return previous ;
+            }
+
+            const next = { ...previous , [ id ] : open } ;
+
+            persistCollapseState( storageKey , next ) ;
+
+            return next ;
+        } ) ;
+    }
+    , [ storageKey ] ) ;
+
+    const getCollapseOpen = useCallback( ( id , item ) =>
+        resolveCollapseOpen
+        ({
+            id ,
+            item ,
+            persisted : collapses ,
+            pathname ,
+            defaultMode ,
+        })
+    , [ collapses , pathname , defaultMode ] ) ;
+
+    const value = useMemo( () =>
+    ({
+        navigation ,
+        setNavigation ,
+        defaultMode ,
+        collapses ,
+        setCollapse ,
+        getCollapseOpen ,
+        pathname ,
+    })
+    , [ navigation , defaultMode , collapses , setCollapse , getCollapseOpen , pathname ] ) ;
+
     return (
-        <NavigationContext value={ { navigation , setNavigation } }>
+        <NavigationContext value={ value }>
             { children }
         </NavigationContext>
     ) ;
 } ;
 
-export default NavigationProvider ;
+export default NavigationProvider ;

package/src/contexts/navigation/useNavigationCollapse.js

@@ -0,0 +1,63 @@
+'use client' ;
+
+import { useCallback } from 'react' ;
+
+import useNavigation from './useNavigation' ;
+
+/**
+ * React hook that exposes the open/closed state and toggle helpers for a
+ * single collapse, identified by `id`.
+ *
+ * Useful for building custom UIs on top of the navigation tree (for
+ * instance an "expand all / collapse all" control, or a custom collapse
+ * skin that does not reuse `<Collapse>`). Inside the standard
+ * `<Collapse>` component the same wiring happens internally — you only
+ * need this hook for bespoke views.
+ *
+ * @param {string} id - Stable item id matching the navigation config.
+ * @param {Object} [item] - Optional item reference. When provided, the
+ *   `auto` mode and the per-item `defaultOpen` override are honoured;
+ *   when omitted, only persisted state and the global `defaultMode` are
+ *   considered.
+ *
+ * @returns {{
+ *   open: boolean,
+ *   toggle: () => void,
+ *   set: (open: boolean) => void
+ * }}
+ *
+ * @throws {Error} If used outside `NavigationProvider`.
+ *
+ * @example
+ * ```jsx
+ * const { open , toggle } = useNavigationCollapse( 'lab' ) ;
+ *
+ * return (
+ *     <button type="button" onClick={ toggle }>
+ *         { open ? 'Hide lab' : 'Show lab' }
+ *     </button>
+ * ) ;
+ * ```
+ */
+const useNavigationCollapse = ( id , item ) =>
+{
+    const { getCollapseOpen , setCollapse } = useNavigation() ;
+
+    const open = getCollapseOpen( id , item ) ;
+
+    const set = useCallback( ( next ) =>
+    {
+        setCollapse( id , Boolean( next ) ) ;
+    }
+    , [ id , setCollapse ] ) ;
+
+    const toggle = useCallback( () =>
+    {
+        setCollapse( id , !open ) ;
+    }
+    , [ id , open , setCollapse ] ) ;
+
+    return { open , toggle , set } ;
+} ;
+
+export default useNavigationCollapse ;

package/src/demo/menus/CollapsePersistenceDemo.jsx

@@ -0,0 +1,210 @@
+'use client' ;
+
+/**
+ * CollapsePersistenceDemo — three side-by-side `NavigationProvider`
+ * instances showcasing the `defaultMode` and `storageKey` props.
+ *
+ * Each card mounts its own provider with a tiny three-item tree and
+ * mirrors its `localStorage` payload, so the persistence and
+ * follow-the-route behaviours can be exercised without leaving the
+ * page. The cards intentionally use distinct storage keys to avoid
+ * cross-talk.
+ *
+ * @module demo/menus/CollapsePersistenceDemo
+ */
+
+import { useEffect , useState } from 'react' ;
+
+import {
+    MdFolder      as GroupIcon  ,
+    MdInsertLink  as LinkIcon   ,
+    MdSubdirectoryArrowRight as ChildIcon ,
+} from 'react-icons/md' ;
+
+import NavigationProvider from '@/contexts/navigation/provider' ;
+import useNavigation      from '@/contexts/navigation/useNavigation' ;
+import { COLLAPSE , LINK } from '@/contexts/navigation/types' ;
+
+import Menu from '@/display/ui/navigation/Menu' ;
+
+const STORAGE_KEY_CLOSED = 'oihana-next-ui:demo:collapses:closed' ;
+const STORAGE_KEY_AUTO   = 'oihana-next-ui:demo:collapses:auto'   ;
+
+const demoItems =
+[
+    {
+        id    : 'group-a' ,
+        type  : COLLAPSE  ,
+        label : 'Group A' ,
+        Icon  : GroupIcon ,
+        items :
+        [
+            { id : 'a-menus' , type : LINK , label : 'Menus page' , path : '/lab/menus' , Icon : LinkIcon } ,
+            { id : 'a-other' , type : LINK , label : 'Fictive page' , path : '/demo/a/other' , Icon : LinkIcon } ,
+        ] ,
+    } ,
+    {
+        id          : 'group-b' ,
+        type        : COLLAPSE  ,
+        label       : 'Group B (defaultOpen=false)' ,
+        Icon        : GroupIcon ,
+        defaultOpen : false     ,
+        items       :
+        [
+            { id : 'b-one' , type : LINK , label : 'B1' , path : '/demo/b/one' , Icon : ChildIcon } ,
+            { id : 'b-two' , type : LINK , label : 'B2' , path : '/demo/b/two' , Icon : ChildIcon } ,
+        ] ,
+    } ,
+] ;
+
+/**
+ * Reads `useNavigation()` and forwards its tree to the standard `Menu`,
+ * so each card renders a proper sidebar-style menu without depending
+ * on the global `<Sidebar>` chrome.
+ */
+const DemoMenu = () =>
+{
+    const { navigation } = useNavigation() ;
+
+    return (
+        <Menu
+            className = "menu w-full bg-base-100 rounded-box gap-2 p-2 border border-base-300"
+            items     = { navigation }
+        />
+    ) ;
+} ;
+
+/**
+ * Live inspector that mirrors the JSON payload at the given storage key.
+ * Refreshes on a low-frequency interval — accurate enough for a demo,
+ * cheap enough to ignore.
+ */
+const StorageInspector = ( { storageKey } ) =>
+{
+    const [ value , setValue ] = useState( null ) ;
+
+    useEffect( () =>
+    {
+        if ( !storageKey )
+        {
+            return undefined ;
+        }
+
+        const refresh = () =>
+        {
+            try
+            {
+                setValue( window.localStorage.getItem( storageKey ) ) ;
+            }
+            catch
+            {
+                setValue( null ) ;
+            }
+        } ;
+
+        refresh() ;
+
+        const id = window.setInterval( refresh , 500 ) ;
+
+        return () => window.clearInterval( id ) ;
+    }
+    , [ storageKey ] ) ;
+
+    return (
+        <pre className="text-xs font-mono whitespace-pre-wrap break-all bg-base-200 rounded p-2 min-h-12">
+            { value || <span className="opacity-60">(empty)</span> }
+        </pre>
+    ) ;
+} ;
+
+const DemoCard = ( { title , description , defaultMode , storageKey } ) =>
+{
+    const handleClear = () =>
+    {
+        if ( storageKey )
+        {
+            try
+            {
+                window.localStorage.removeItem( storageKey ) ;
+            }
+            catch
+            {
+                /* ignore */
+            }
+        }
+
+        window.location.reload() ;
+    } ;
+
+    return (
+        <div className="card bg-base-200 shadow-xl">
+            <div className="card-body gap-3">
+                <div>
+                    <h3 className="card-title text-sm">{ title }</h3>
+                    <p className="text-xs opacity-70">{ description }</p>
+                </div>
+
+                <NavigationProvider
+                    defaultNavigation = { demoItems }
+                    defaultMode       = { defaultMode }
+                    storageKey        = { storageKey }
+                    i18nPath          = "demo.collapsePersistence"
+                >
+                    <DemoMenu />
+                </NavigationProvider>
+
+                { storageKey
+                    ? (
+                        <>
+                            <div className="text-xs opacity-70">
+                                <code className="font-mono">{ storageKey }</code>
+                            </div>
+                            <StorageInspector storageKey={ storageKey } />
+                            <button
+                                type      = "button"
+                                className = "btn btn-xs btn-outline self-start"
+                                onClick   = { handleClear }
+                            >
+                                Clear &amp; reload
+                            </button>
+                        </>
+                    )
+                    : (
+                        <div className="text-xs italic opacity-60">
+                            No storageKey — collapse state lives only in memory.
+                        </div>
+                    )
+                }
+            </div>
+        </div>
+    ) ;
+} ;
+
+const CollapsePersistenceDemo = () =>
+(
+    <div className="grid grid-cols-1 md:grid-cols-2 xl:grid-cols-3 gap-4">
+
+        <DemoCard
+            title       = "defaultMode = 'open'"
+            description = "Legacy behaviour — every collapse starts open. No storageKey, no persistence."
+            defaultMode = "open"
+        />
+
+        <DemoCard
+            title       = "defaultMode = 'closed' + storageKey"
+            description = "All collapses start closed. Toggles persist across reloads. Group B's defaultOpen=false has no visible effect (already closed)."
+            defaultMode = "closed"
+            storageKey  = { STORAGE_KEY_CLOSED }
+        />
+
+        <DemoCard
+            title       = "defaultMode = 'auto' + storageKey"
+            description = "Group A opens automatically on /lab/menus (its 'Menus page' link matches the current pathname). Group B starts closed via per-item defaultOpen=false override."
+            defaultMode = "auto"
+            storageKey  = { STORAGE_KEY_AUTO }
+        />
+
+    </div>
+) ;
+
+export default CollapsePersistenceDemo ;

package/src/display/Application.jsx

@@ -64,7 +64,11 @@ const Application = ( { children , initialLang } ) =>
                     <ThemeProvider>
                         <ApplicationProvider>
                             <FullScreenProvider>
-                                <NavigationProvider defaultNavigation={ navigation } >
+                                <NavigationProvider
+                                    defaultNavigation = { navigation }
+                                    defaultMode       = "auto"
+                                    storageKey        = "oihana-next-ui:lab:nav"
+                                >
                                     <LoadingProvider>
                                         <ToastProvider>
                                             <SelectProvider>

package/src/display/ui/navigation/Collapse.jsx

@@ -1,16 +1,55 @@
+'use client' ;
+
 /**
  * Collapse component for nested navigation menus.
  *
  * @module display/ui/navigation/Collapse
  */
 
+import { use , useCallback , useMemo } from 'react' ;
+
+import cn from '../../../themes/helpers/cn' ;
+
+import NavigationContext from '../../../contexts/navigation/context' ;
+import containsActivePath from '../../../contexts/navigation/helpers/containsActivePath' ;
+
 import Menu from './Menu' ;
 
+/**
+ * Default style applied to the `<summary>` of a collapse whose subtree
+ * contains the current pathname (active-ancestor marker, option A —
+ * minimal). Consumers can override via `activeAncestorClassName`.
+ */
+const DEFAULT_ACTIVE_ANCESTOR_CLASSNAME = 'text-base-content font-semibold' ;
+
 /**
  * Renders a collapsible navigation group with nested items.
  *
+ * The component supports three usage modes:
+ *
+ * 1. **Legacy / uncontrolled** — when no `id`, `open`, `defaultOpen` or
+ *    `onToggle` is provided, renders `<details open>` exactly as before.
+ * 2. **Context-driven** — when `id` is provided and the component sits
+ *    under a `NavigationProvider`, the open state is read from the
+ *    provider (persisted choice → auto(pathname) → `defaultOpen` → mode)
+ *    and toggle events are written back, persisting to `localStorage`
+ *    when the provider received a `storageKey`.
+ * 3. **Controlled** — when `open` is provided, the component is fully
+ *    controlled by the parent and ignores the provider for its own
+ *    open/closed state. `onToggle` is fired with the next boolean.
+ *
  * @param {Object} props
+ * @param {string} [props.id] - Stable item id used by the provider for
+ *   persistence and for the active-ancestor calculation.
+ * @param {boolean} [props.open] - Controlled open state. When provided,
+ *   the component ignores the provider for its own state.
+ * @param {boolean} [props.defaultOpen] - Per-item override of the
+ *   provider's `defaultMode`, used when no persisted choice exists.
+ * @param {(open: boolean) => void} [props.onToggle] - Called with the
+ *   next open value whenever the native `<details>` toggles.
  * @param {string} [props.className] - Additional class names for the inner menu.
+ * @param {string} [props.activeAncestorClassName] - Override for the
+ *   default active-ancestor style applied to the `<summary>`.
  * @param {React.ComponentType<{ size?: number }>} [props.Icon] - Icon component.
  * @param {number} [props.iconSize=20] - Icon size in pixels.
  * @param {Object[]} [props.items] - Nested navigation items.
@@ -21,17 +60,82 @@ import Menu from './Menu' ;
  */
 const Collapse =
 ({
-     className ,
-     Icon ,
-     iconSize = 20 ,
-     items ,
-     label ,
-     onAction ,
- }) =>
+    id ,
+    open : openProp ,
+    defaultOpen ,
+    onToggle ,
+    activeAncestorClassName ,
+    className ,
+    Icon ,
+    iconSize = 20 ,
+    items ,
+    label ,
+    onAction ,
+}) =>
+{
+    // Defensive read: a consumer may render <Collapse> without a
+    // NavigationProvider (legacy / standalone usage). In that case the
+    // context is null and we silently fall back to the legacy behaviour.
+    const navigation = use( NavigationContext ) ;
+
+    const isControlled       = typeof openProp === 'boolean' ;
+    const isProviderManaged  = !isControlled && navigation !== null && typeof id === 'string' && id.length > 0 ;
+
+    const item = useMemo( () => ({ id , defaultOpen , items , path : undefined })
+                        , [ id , defaultOpen , items ] ) ;
+
+    let open ;
+    if ( isControlled )
+    {
+        open = openProp ;
+    }
+    else if ( isProviderManaged )
+    {
+        open = navigation.getCollapseOpen( id , item ) ;
+    }
+    else
+    {
+        // Legacy fallback: behave like <details open> when nothing is
+        // wired up, preserving 100% backward compatibility.
+        open = true ;
+    }
+
+    const pathname = navigation?.pathname ?? null ;
+
+    const isActiveAncestor = useMemo( () =>
+        containsActivePath( { items } , pathname )
+    , [ items , pathname ] ) ;
+
+    const handleToggle = useCallback( ( event ) =>
+    {
+        const next = Boolean( event.currentTarget.open ) ;
+
+        if ( onToggle )
+        {
+            onToggle( next ) ;
+        }
+
+        if ( !isControlled && isProviderManaged )
+        {
+            navigation.setCollapse( id , next ) ;
+        }
+    }
+    , [ id , isControlled , isProviderManaged , navigation , onToggle ] ) ;
+
+    const summaryClassName = cn
     (
+        isActiveAncestor && ( activeAncestorClassName ?? DEFAULT_ACTIVE_ANCESTOR_CLASSNAME ) ,
+    ) ;
+
+    return (
         <li>
-            <details open>
-                <summary>
+            <details
+                open      = { open }
+                onToggle  = { handleToggle }
+                data-nav-id = { id }
+                data-active-ancestor = { isActiveAncestor || undefined }
+            >
+                <summary className={ summaryClassName }>
                     { Icon && <Icon size={ iconSize } /> }
                     { label }
                 </summary>
@@ -43,5 +147,6 @@ const Collapse =
             </details>
         </li>
     ) ;
+} ;
 
-export default Collapse ;
+export default Collapse ;

package/src/display/ui/navigation/Link.jsx

@@ -47,10 +47,21 @@ const getBadge = ( badge ) =>
  * @property {boolean} [outline] - Outline style.
  */
 
+/**
+ * Default active-link style — neutral, transparent darkening that works
+ * in both light and dark themes through DaisyUI semantic tokens. Subtle
+ * by design: relies on the `font-medium` weight bump as a secondary cue
+ * so the active state stays readable without competing visually with
+ * the page content.
+ */
+const DEFAULT_ACTIVE_CLASSNAME = 'bg-base-content/10 font-medium' ;
+
 /**
  * @typedef {Object} LinkProps
  * @property {string|BadgeProps} [badge] - Badge label or configuration object.
  * @property {string} [className] - Additional class names.
+ * @property {string} [activeClassName] - Override for the default
+ *   active-link style applied when the current pathname matches `path`.
  * @property {React.ComponentType<{ size?: number }>} [Icon] - Icon component.
  * @property {number} [iconSize=20] - Icon size in pixels.
  * @property {string} [label] - Link text content.
@@ -85,6 +96,7 @@ const Link =
 ({
      badge ,
      className ,
+     activeClassName ,
      Icon ,
      iconSize = 20 ,
      label ,
@@ -99,7 +111,7 @@ const Link =
     const classNames = cn
     (
         'space-x-4' ,
-        { active } ,
+        active && ( activeClassName ?? DEFAULT_ACTIVE_CLASSNAME ) ,
         className ,
     ) ;
 
@@ -125,17 +137,19 @@ const Link =
         { path
             ? (
                 <NextLink
-                    className = { classNames }
-                    href      = { path }
-                    onClick   = { handleClick }
+                    className   = { classNames }
+                    href        = { path }
+                    onClick     = { handleClick }
+                    data-active = { active || undefined }
                 >
                     { content }
                 </NextLink>
             )
             : (
                 <a
-                    className = { classNames }
-                    onClick   = { handleClick }
+                    className   = { classNames }
+                    onClick     = { handleClick }
+                    data-active = { active || undefined }
                 >
                     { content }
                 </a>

package/src/version.js

@@ -1,3 +1,3 @@
-const version = "0.1.47" ;
+const version = "0.2.0" ;
 
 export default version ;