oihana-next-ui 0.1.47 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oihana-next-ui",
-  "version": "0.1.47",
+  "version": "0.2.1",
   "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

@@ -19,73 +19,185 @@ import
 }
 from '../../themes/components/modal' ;
 
-const Modal =
-({
-    // Header
-    closeClassName ,
-    closeIcon= <CloseIcon size={20}/>,
-    closeTitle = 'Close' ,
-    title,
-    icon,
-    showHeader = true,
-    showTitle = true,
-    showIcon = true,
-    showCloseButton = true,
-    headerClassName,
-    headerOptions,
-
-    // Footer
-    agree = 'OK',
-    disagree = 'Cancel',
-    agreeColor = 'primary',
-    disagreeColor = 'neutral',
-    agreeIcon,
-    disagreeIcon,
-    agreeDisabled,
-    disagreeDisabled,
-    showFooter = true,
-    showAgree = true,
-    showDisagree = true,
-    footerReverse = false,
-    footerClassName,
-    footerOptions,
-    onAgree,
-    onCancel,
-
-    // Layout
-    placement = 'middle',
-    responsivePlacement,
-    maxWidth = 'max-w-2xl',
-    fullScreen,
-    fullScreenBreakpoint,
-    fullWidth,
-
-    // Backdrop
-    showBackdrop = true,
-    disableBackdropClick = false,
-    backdropClassName,
-
-    // Behavior
-    disableEscapeKeyDown = false,
-    disabled,
-    onClose,
-
-    // Content
-    children,
-
-    // Styling
-    className,
-    modalBoxClassName,
-    contentClassName,
-    titleClassName,
-
-    // Ref
-    ref,
-}) =>
+const FOOTER_NODE_OVERRIDE_PROPS =
+[
+    'agree',
+    'disagree',
+    'agreeColor',
+    'disagreeColor',
+    'agreeIcon',
+    'disagreeIcon',
+    'agreeDisabled',
+    'disagreeDisabled',
+    'showAgree',
+    'showDisagree',
+    'showFooter',
+    'footerReverse',
+    'footerClassName',
+    'footerOptions',
+    'onAgree',
+    'onCancel',
+] ;
+
+/**
+ * Accessible dialog primitive built on top of the native `<dialog>` element and DaisyUI's `modal` styles.
+ *
+ * Two layout modes:
+ *
+ * 1. **Standard mode** (default) — header (sticky top), free-flow content area, optional footer
+ *    rendered as a `modal-action` row with `agree` / `disagree` buttons (sticky bottom). The whole
+ *    modal-box is the scroll container, header and footer stick to its edges as the user scrolls.
+ *
+ * 2. **Custom-footer mode** — activated by passing a `footerNode`. The modal-box becomes a vertical
+ *    flex column: the content area grows and scrolls internally, while `footerNode` is rendered
+ *    in a dedicated, non-scrollable, border-topped slot at the bottom. Use this for forms with
+ *    a status text + custom action buttons, or any case where the standard footer is too rigid.
+ *
+ * When `footerNode` is provided, the standard footer (`agree`, `disagree`, `footerOptions`,
+ * `showFooter`, `footerReverse`, `footerClassName`, `onAgree`, `onCancel`, etc.) is **fully
+ * ignored** — `footerNode` wins. A `console.warn` is emitted in development if overlapping
+ * props are passed alongside.
+ *
+ * @example Standard usage with agree / disagree
+ * ```jsx
+ * <Modal
+ *     ref      = { modalRef }
+ *     title    = "Save changes?"
+ *     agree    = "Save"
+ *     disagree = "Cancel"
+ *     onAgree  = { handleSave }
+ * >
+ *     <p>Your unsaved changes will be lost.</p>
+ * </Modal>
+ * ```
+ *
+ * @example Custom footer with scrollable form (no `!important` overrides)
+ * ```jsx
+ * <Modal
+ *     ref        = { modalRef }
+ *     title      = "Edit profile"
+ *     footerNode = {
+ *         <div className="flex items-center gap-3 px-4 py-3">
+ *             <span className="text-sm text-base-content/60">Saved 2s ago</span>
+ *             <div className="ml-auto flex gap-2">
+ *                 <Button color="neutral" onClick={ handleCancel }>Cancel</Button>
+ *                 <Button color="primary" onClick={ handleSave }>Save</Button>
+ *             </div>
+ *         </div>
+ *     }
+ * >
+ *     <form className="flex flex-col gap-4">
+ *         { /* many fields, the form scrolls — footer stays visible *\/ }
+ *     </form>
+ * </Modal>
+ * ```
+ *
+ * @param {Object} props
+ * @param {React.ReactNode} [props.title] - Modal title (rendered in the header).
+ * @param {React.ReactNode} [props.icon] - Icon shown left of the title.
+ * @param {React.ReactNode} [props.headerOptions] - Extra nodes injected in the header row.
+ * @param {React.ReactNode} [props.footerOptions] - Extra nodes rendered alongside agree/disagree (standard mode only).
+ * @param {React.ReactNode} [props.footerNode] - **Custom footer** that fully replaces the standard footer. Activates the flex-column layout (sticky footer + internal content scroll). When set, all `agree*`/`disagree*`/`footer*`/`onAgree`/`onCancel`/`showFooter` props are ignored.
+ * @param {React.ReactNode} [props.children] - Modal body content.
+ * @param {string} [props.maxWidth='max-w-2xl'] - Tailwind max-width class for the modal-box.
+ * @param {boolean} [props.fullScreen] - Force full-screen modal.
+ * @param {string}  [props.fullScreenBreakpoint] - Tailwind breakpoint below which the modal becomes full-screen (e.g. `'md'`).
+ * @param {string}  [props.placement='middle'] - `'top'` | `'middle'` | `'bottom'` | `'start'` | `'end'`.
+ * @param {string}  [props.responsivePlacement] - Responsive placement (e.g. `'sm:modal-middle'`).
+ * @param {boolean} [props.disableBackdropClick=false] - Prevent close on backdrop click.
+ * @param {boolean} [props.disableEscapeKeyDown=false] - Prevent close on `Escape`.
+ * @param {string}  [props.contentClassName] - Extra classes on the content wrapper. In custom-footer mode, the default is `flex-1 min-h-0 overflow-y-auto p-2 py-4`; in standard mode, `overflow-y-auto h-full p-2 py-4`.
+ * @param {string}  [props.modalBoxClassName] - Extra classes on the modal-box.
+ *
+ * @see https://daisyui.com/components/modal
+ */
+const Modal = ( props ) =>
 {
+    const
+    {
+        // Header
+        closeClassName ,
+        closeIcon= <CloseIcon size={20}/>,
+        closeTitle = 'Close' ,
+        title,
+        icon,
+        showHeader = true,
+        showTitle = true,
+        showIcon = true,
+        showCloseButton = true,
+        headerClassName,
+        headerOptions,
+
+        // Footer (standard mode)
+        agree = 'OK',
+        disagree = 'Cancel',
+        agreeColor = 'primary',
+        disagreeColor = 'neutral',
+        agreeIcon,
+        disagreeIcon,
+        agreeDisabled,
+        disagreeDisabled,
+        showFooter = true,
+        showAgree = true,
+        showDisagree = true,
+        footerReverse = false,
+        footerClassName,
+        footerOptions,
+        onAgree,
+        onCancel,
+
+        // Footer (custom mode)
+        footerNode,
+
+        // Layout
+        placement = 'middle',
+        responsivePlacement,
+        maxWidth = 'max-w-2xl',
+        fullScreen,
+        fullScreenBreakpoint,
+        fullWidth,
+
+        // Backdrop
+        showBackdrop = true,
+        disableBackdropClick = false,
+        backdropClassName,
+
+        // Behavior
+        disableEscapeKeyDown = false,
+        disabled,
+        onClose,
+
+        // Content
+        children,
+
+        // Styling
+        className,
+        modalBoxClassName,
+        contentClassName,
+        titleClassName,
+
+        // Ref
+        ref,
+    }
+    = props ;
+
     const dialogRef = useRef( null ) ;
     const titleId   = useId() ;
 
+    const hasCustomFooter = footerNode !== undefined && footerNode !== null ;
+
+    if ( process.env.NODE_ENV !== 'production' && hasCustomFooter )
+    {
+        const overlap = FOOTER_NODE_OVERRIDE_PROPS.filter( key => key in props && props[ key ] !== undefined ) ;
+        if ( overlap.length > 0 )
+        {
+            console.warn(
+                `[Modal] \`footerNode\` is set, the following overlapping prop(s) are ignored: ${ overlap.join( ', ' ) }. ` +
+                `Move this content into \`footerNode\` itself.`
+            ) ;
+        }
+    }
+
     const isAboveBreakpoint = fullScreenBreakpoint
                             ? useBreakpoint( fullScreenBreakpoint )
                             : true ;
@@ -165,6 +277,7 @@ const Modal =
         fullScreen : isFullScreen,
         fullWidth,
         placement  : responsivePlacement || placement,
+        flexLayout : hasCustomFooter,
         className  : modalBoxClassName,
     }) ;
 
@@ -177,6 +290,14 @@ const Modal =
         className : backdropClassName,
     }) ;
 
+    const contentClasses = hasCustomFooter
+        ? cn( 'flex-1 min-h-0 overflow-y-auto p-2 py-4' , contentClassName )
+        : cn( 'overflow-y-auto h-full p-2 py-4'         , contentClassName ) ;
+
+    const headerClasses = hasCustomFooter
+        ? cn( 'shrink-0 bg-base-100 border-b border-base-300/60 z-10 p-2 pb-3' , headerClassName )
+        : cn( 'sticky top-0 bg-base-100 border-b border-base-300/60 z-10 p-2 pb-3' , headerClassName ) ;
+
     return (
         <dialog
             aria-labelledby = { showTitle && title ? titleId : undefined }
@@ -197,7 +318,7 @@ const Modal =
             <div className={ modalBoxClasses }>
 
                 { showHeader && (
-                    <div className={`sticky top-0 bg-base-100 border-b border-base-300/60 z-10 p-2 pb-3 ${ headerClassName || '' }`}>
+                    <div className={ headerClasses }>
                         <div className="flex items-center gap-3">
 
                             { showIcon && icon && (
@@ -232,11 +353,15 @@ const Modal =
                     </div>
                 )}
 
-                <div className={`overflow-y-auto h-full p-2 py-4 ${ contentClassName || '' }`}>
+                <div className={ contentClasses }>
                     { children }
                 </div>
 
-                { showFooter && (
+                { hasCustomFooter ? (
+                    <div className="shrink-0 bg-base-100 border-t border-base-300/60">
+                        { footerNode }
+                    </div>
+                ) : showFooter && (
                     <div className={`sticky bottom-0 bg-base-100 border-t border-base-300/60 p-0 ${ footerClassName || '' }`}>
 
                         <div className={ modalActionClasses }>
@@ -274,4 +399,4 @@ const Modal =
 
 Modal.displayName = 'Modal' ;
 
-export default Modal ;
+export default Modal ;

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 ;