oihana-next-ui 0.1.46 → 0.2.0

package/README.md

@@ -100,50 +100,72 @@ Open [http://localhost:3666](http://localhost:3666) to browse the component demo
 - [Day.js](https://day.js.org/) — Lightweight date library
 - [Chroma.js](https://www.vis4.net/chromajs/) — Color manipulation library
 
-### Build the library
+## Release
 
-```bash
-bun run build:lib
-```
+The package publishes the raw `src/` tree (no build step) — see the `files` and `exports` fields in [`package.json`](./package.json).
 
-### Watch mode
+### Versioning
 
-```bash
-bun run build:lib:watch
-```
+This project follows [Semantic Versioning](https://semver.org/) — `MAJOR.MINOR.PATCH` (e.g. `1.2.3`).
 
-## Release
+| Type  | Command                 | Example             | When to use                                   |
+|-------|-------------------------|---------------------|-----------------------------------------------|
+| Patch | `bun run release:patch` | `0.1.46` → `0.1.47` | Bug fix, small tweak                          |
+| Minor | `bun run release:minor` | `0.1.46` → `0.2.0`  | New component or feature, backward compatible |
+| Major | `bun run release:major` | `0.1.46` → `1.0.0`  | Breaking change                               |
 
-### Versioning
+### Prerequisites
 
-This project follows [Semantic Versioning](https://semver.org/) — `MAJOR.MINOR.PATCH` (e.g. `1.2.3`).
+- Logged in to npm — `npm whoami` should print your username (otherwise `npm login`).
+- A git remote named `origin-ssh` configured (the `release` script pushes there with `--follow-tags`).
+- A clean working tree, ideally — `release:*` will otherwise commit any pending change as `chore: prepare release` before bumping the version.
+
+### Patch release walkthrough — e.g. `0.1.46` → `0.1.47`
+
+1. **Update [`CHANGELOG.md`](./CHANGELOG.md)** — add a new section under `[Unreleased]` with the new version and date :
+
+   ~~~markdown
+   ## [0.1.47] — 2026-04-27
+
+   **Components**
+   - `XYZ` — what changed and why.
+   ~~~
 
-| Type | Command | Example | When to use |
-|------|---------|---------|-------------|
-| Patch | `bun run release:patch` | `0.1.0` → `0.1.1` | Bug fix, minor tweak |
-| Minor | `bun run release:minor` | `0.1.0` → `0.2.0` | New component or feature, backward compatible |
-| Major | `bun run release:major` | `0.1.0` → `1.0.0` | Breaking change |
+2. **Run the release script** :
 
-Each script automatically bumps the version, builds the library, publishes to npm, and pushes the commit and tag to GitHub.
+   ```bash
+   bun run release:patch
+   ```
 
-You can also set a specific version manually :
+   What happens, in order — all of this is automatic :
+
+   1. `stage` — commits any pending change as `chore: prepare release` (skipped if the working tree is clean).
+   2. `npm version patch` — bumps `0.1.46` → `0.1.47` in `package.json`.
+   3. `version` script (auto-run by `npm version`) :
+      - `inject-version` writes the new version into `src/version.js` and `public/sw.js`,
+      - `generate-exports` refreshes the `exports` field in `package.json`,
+      - then stages `src/version.js`, `public/sw.js` and `package.json` for the version commit.
+   4. `npm version` creates the release commit (`0.1.47`) and the matching git tag.
+   5. `postversion` script (auto-run by `npm version`) → `release` :
+      - `npm publish --access public` publishes to npm,
+      - `git push origin-ssh --follow-tags` pushes the commit and the tag to GitHub.
+
+### Manual / pre-release version
+
+Set a specific version manually — `version` + `postversion` still run as above :
 
 ```bash
 npm version 1.0.0
-bun run release
 ```
 
-Or a pre-release version :
+Pre-release versions :
 
 ```bash
-npm version prerelease --preid=alpha   # 0.1.0 → 0.1.1-alpha.0
-npm version prerelease --preid=beta    # 0.1.0 → 0.1.1-beta.0
-npm version prerelease --preid=rc      # 0.1.0 → 0.1.1-rc.0
-bun run release
+npm version prerelease --preid=alpha   # 0.1.46 → 0.1.47-alpha.0
+npm version prerelease --preid=beta    # 0.1.46 → 0.1.47-beta.0
+npm version prerelease --preid=rc      # 0.1.46 → 0.1.47-rc.0
 ```
 
-`npm version` automatically updates `package.json`, creates a Git commit and a Git tag.
-
 ## License
 
 [Mozilla Public License 2.0](./LICENSE) — © Marc Alcaraz

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oihana-next-ui",
-  "version": "0.1.46",
+  "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/app/lab/@tabs/modals/page.js

@@ -1,10 +1,11 @@
 'use client' ;
 
-import CRUDDemo       from '@/demo/modals/CRUDModalDemo';
-import InputModalDemo from '@/demo/modals/InputModalDemo';
-import ModalDemo      from '@/demo/modals/ModalDemo';
-import Container from '@/display/Container';
-import Page           from '@/display/Page' ;
+import CRUDDemo           from '@/demo/modals/CRUDModalDemo';
+import InputModalDemo     from '@/demo/modals/InputModalDemo';
+import ModalDemo          from '@/demo/modals/ModalDemo';
+import ToastOverModalDemo from '@/demo/modals/ToastOverModalDemo';
+import Container          from '@/display/Container';
+import Page               from '@/display/Page' ;
 
 /**
  * Modal showcase page.
@@ -26,6 +27,8 @@ const ModalShowcase = ({ path = 'app.test' }) =>
 
             <ModalDemo />
 
+            <ToastOverModalDemo />
+
             <CRUDDemo />
 
             <InputModalDemo />

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 ;