@kushagradhawan/kookie-ui 0.1.50 → 0.1.52

package/src/components/_internal/shell-sidebar.tsx

@@ -3,10 +3,10 @@ import classNames from 'classnames';
 import * as Sheet from '../sheet.js';
 import { VisuallyHidden } from '../visually-hidden.js';
 import { useShell } from '../shell.context.js';
-import { useResponsivePresentation } from '../shell.hooks.js';
+import { useResponsivePresentation, useResponsiveValue } from '../shell.hooks.js';
 import { PaneResizeContext } from './shell-resize.js';
 import { SidebarHandle, PaneHandle } from './shell-handles.js';
-import type { Breakpoint, PaneMode, PaneSizePersistence, PresentationValue, ResponsivePresentation, ResponsiveSidebarMode, SidebarMode } from '../shell.types.js';
+import type { Breakpoint, PaneMode, PaneSizePersistence, PresentationValue, ResponsivePresentation, ResponsiveSidebarMode, SidebarMode, Responsive } from '../shell.types.js';
 import { BREAKPOINTS } from '../shell.types.js';
 
 interface PaneProps extends React.ComponentPropsWithoutRef<'div'> {
@@ -32,33 +32,29 @@ interface PaneProps extends React.ComponentPropsWithoutRef<'div'> {
   persistence?: PaneSizePersistence;
 }
 
-type SidebarComponent = React.ForwardRefExoticComponent<
-  Omit<PaneProps, 'mode' | 'defaultMode' | 'onModeChange'> & {
-    mode?: SidebarMode;
-    defaultMode?: ResponsiveSidebarMode;
-    onModeChange?: (mode: SidebarMode) => void;
-    thinSize?: number;
-    toggleModes?: 'both' | 'single';
-  } & React.RefAttributes<HTMLDivElement>
-> & { Handle: typeof SidebarHandle };
+type SidebarStateChangeMeta = { reason: 'init' | 'toggle' | 'responsive' };
+type SidebarControlledProps = { state: Responsive<SidebarMode>; onStateChange?: (state: SidebarMode, meta: SidebarStateChangeMeta) => void; defaultState?: never };
+type SidebarUncontrolledProps = { defaultState?: SidebarMode | Partial<Record<Breakpoint, SidebarMode>>; onStateChange?: (state: SidebarMode, meta: SidebarStateChangeMeta) => void; state?: never };
+type SidebarPublicProps = Omit<PaneProps, 'mode' | 'defaultMode' | 'onModeChange'> & {
+  // removed legacy mode props
+  thinSize?: number;
+  toggleModes?: 'both' | 'single';
+  // size API (width when expanded)
+  size?: number | string;
+  defaultSize?: number | string;
+  onSizeChange?: (size: number, meta: { reason: 'init' | 'resize' | 'controlled' }) => void;
+  sizeUpdate?: 'throttle' | 'debounce';
+  sizeUpdateMs?: number;
+} & (SidebarControlledProps | SidebarUncontrolledProps);
 
-export const Sidebar = React.forwardRef<
-  HTMLDivElement,
-  Omit<PaneProps, 'mode' | 'defaultMode' | 'onModeChange'> & {
-    mode?: SidebarMode;
-    defaultMode?: ResponsiveSidebarMode;
-    onModeChange?: (mode: SidebarMode) => void;
-    thinSize?: number;
-    toggleModes?: 'both' | 'single';
-  }
->(
+type SidebarComponent = React.ForwardRefExoticComponent<SidebarPublicProps & React.RefAttributes<HTMLDivElement>> & { Handle: typeof SidebarHandle };
+
+export const Sidebar = React.forwardRef<HTMLDivElement, SidebarPublicProps>(
   (
     {
       className,
       presentation = { initial: 'overlay', md: 'fixed' },
-      mode,
-      defaultMode = 'expanded',
-      onModeChange,
+      // removed legacy props
       expandedSize = 288,
       minSize = 200,
       maxSize = 400,
@@ -78,6 +74,10 @@ export const Sidebar = React.forwardRef<
       style,
       thinSize = 64,
       toggleModes,
+      // new state props (XOR)
+      state,
+      defaultState,
+      onStateChange,
       ...props
     },
     ref,
@@ -86,29 +86,7 @@ export const Sidebar = React.forwardRef<
     const resolvedPresentation = useResponsivePresentation(presentation);
     const isOverlay = resolvedPresentation === 'overlay';
     const isStacked = resolvedPresentation === 'stacked';
-    // Use library-managed phase for thin ↔ expanded sequencing
-    const transitionPhase = (shell as any).sidebarPhase as 'idle' | 'hiding' | 'resizing' | 'showing' | undefined;
-    React.useLayoutEffect(() => {
-      if (isOverlay) return;
-      const containerEl = localRef.current;
-      if (!containerEl) return;
-      if (transitionPhase === 'hiding') {
-        // Freeze width while we fade out
-        try {
-          const rect = containerEl.getBoundingClientRect();
-          containerEl.style.width = `${Math.round(rect.width)}px`;
-        } catch {}
-      } else if (transitionPhase === 'resizing') {
-        // Release width so the CSS width transition happens
-        try {
-          containerEl.style.removeProperty('width');
-        } catch {}
-      } else if (transitionPhase === 'idle') {
-        try {
-          containerEl.style.removeProperty('width');
-        } catch {}
-      }
-    }, [transitionPhase, isOverlay]);
+    // Phase sequencing is now CSS-driven; no JS-managed phase
     const localRef = React.useRef<HTMLDivElement | null>(null);
     const setRef = React.useCallback(
       (node: HTMLDivElement | null) => {
@@ -122,6 +100,34 @@ export const Sidebar = React.forwardRef<
     const handleChildren = childArray.filter((el: React.ReactElement) => React.isValidElement(el) && el.type === SidebarHandle);
     const contentChildren = childArray.filter((el: React.ReactElement) => !(React.isValidElement(el) && el.type === SidebarHandle));
 
+    // Throttled/debounced emitter for onSizeChange
+    const emitSizeChange = React.useMemo(() => {
+      const cb = (props as any).onSizeChange as undefined | ((s: number, meta: { reason: 'init' | 'resize' | 'controlled' }) => void);
+      const strategy = (props as any).sizeUpdate as undefined | 'throttle' | 'debounce';
+      const ms = (props as any).sizeUpdateMs ?? 50;
+      if (!cb) return () => {};
+      if (strategy === 'debounce') {
+        let t: any = null;
+        return (s: number, meta: { reason: 'init' | 'resize' | 'controlled' }) => {
+          if (t) clearTimeout(t);
+          t = setTimeout(() => {
+            cb(s, meta);
+          }, ms);
+        };
+      }
+      if (strategy === 'throttle') {
+        let last = 0;
+        return (s: number, meta: { reason: 'init' | 'resize' | 'controlled' }) => {
+          const now = Date.now();
+          if (now - last >= ms) {
+            last = now;
+            cb(s, meta);
+          }
+        };
+      }
+      return (s: number, meta: { reason: 'init' | 'resize' | 'controlled' }) => cb(s, meta);
+    }, [(props as any).onSizeChange, (props as any).sizeUpdate, (props as any).sizeUpdateMs]);
+
     // Register with shell
     const sidebarId = React.useId();
     React.useEffect(() => {
@@ -131,30 +137,78 @@ export const Sidebar = React.forwardRef<
       };
     }, [shell, sidebarId]);
 
-    // Honor defaultMode on mount when uncontrolled
+    // Dev guards
+    const wasControlledRef = React.useRef<boolean | null>(null);
+    if (process.env.NODE_ENV !== 'production') {
+      if (typeof state !== 'undefined' && typeof defaultState !== 'undefined') {
+        // eslint-disable-next-line no-console
+        console.error('Shell.Sidebar: Do not pass both `state` and `defaultState`. Choose one.');
+      }
+      if (typeof (props as any).size !== 'undefined' && typeof (props as any).defaultSize !== 'undefined') {
+        // eslint-disable-next-line no-console
+        console.error('Shell.Sidebar: Do not pass both `size` and `defaultSize`. Choose one.');
+      }
+    }
+
+    // Warn on mode switch between controlled/uncontrolled
+    React.useEffect(() => {
+      const isControlled = typeof state !== 'undefined';
+      if (wasControlledRef.current === null) {
+        wasControlledRef.current = isControlled;
+        return;
+      }
+      if (wasControlledRef.current !== isControlled) {
+        // eslint-disable-next-line no-console
+        console.warn('Shell.Sidebar: Switching between controlled and uncontrolled `state` is not supported.');
+        wasControlledRef.current = isControlled;
+      }
+    }, [state]);
+
+    // Resolve responsive controlled state at top level
+    const resolvedState = useResponsiveValue(state);
+    const resolvedDefaultState = useResponsiveValue(defaultState as any);
+
+    // Honor state/defaultState on mount when uncontrolled
     const didInitRef = React.useRef(false);
     React.useEffect(() => {
       if (didInitRef.current) return;
+      if (!shell.currentBreakpointReady) return;
       didInitRef.current = true;
-      if (mode === undefined && shell.sidebarMode !== (defaultMode as SidebarMode)) {
-        shell.setSidebarMode(defaultMode as SidebarMode);
+      // Controlled state may be responsive; use resolved value
+      if (typeof state !== 'undefined' && resolvedState) {
+        if (shell.sidebarMode !== resolvedState) shell.setSidebarMode(resolvedState);
+        return;
+      }
+      if (typeof defaultState !== 'undefined') {
+        const initialState = (resolvedDefaultState ?? defaultState) as SidebarMode;
+        if (shell.sidebarMode !== initialState) {
+          shell.setSidebarMode(initialState);
+        }
+        onStateChange?.(initialState, { reason: 'init' });
+        return;
       }
       // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
+    }, [shell.currentBreakpointReady, resolvedDefaultState, resolvedState, state, defaultState]);
 
-    // Sync controlled mode
+    // Sync controlled state (responsive-aware)
     React.useEffect(() => {
-      if (mode !== undefined && shell.sidebarMode !== mode) {
-        shell.setSidebarMode(mode);
-      }
-    }, [mode, shell]);
+      if (resolvedState === undefined) return;
+      if (shell.sidebarMode !== resolvedState) shell.setSidebarMode(resolvedState);
+    }, [resolvedState, shell.sidebarMode]);
 
     // Emit mode changes
+    const lastNotifyModeRef = React.useRef<SidebarMode | null>(null);
     React.useEffect(() => {
-      if (mode === undefined) {
-        onModeChange?.(shell.sidebarMode);
+      // notify new API when uncontrolled; skip first run to avoid masking init
+      if (typeof state === 'undefined') {
+        if (lastNotifyModeRef.current === null) {
+          lastNotifyModeRef.current = shell.sidebarMode as SidebarMode;
+        } else if (lastNotifyModeRef.current !== shell.sidebarMode) {
+          lastNotifyModeRef.current = shell.sidebarMode as SidebarMode;
+          onStateChange?.(shell.sidebarMode as SidebarMode, { reason: 'toggle' });
+        }
       }
-    }, [shell.sidebarMode, mode, onModeChange]);
+    }, [shell.sidebarMode, state, onStateChange]);
 
     // Emit expand/collapse events
     React.useEffect(() => {
@@ -201,29 +255,12 @@ export const Sidebar = React.forwardRef<
       };
     }, [resizable, persistenceAdapter, onResize, isOverlay]);
 
-    // Always-follow responsive defaultMode for uncontrolled Sidebar (on breakpoint change only)
-    const resolveResponsiveMode = React.useCallback((): SidebarMode => {
-      if (typeof defaultMode === 'string') return defaultMode as SidebarMode;
-      const dm = defaultMode as Partial<Record<Breakpoint, SidebarMode>> | undefined;
-      if (dm && dm[shell.currentBreakpoint as Breakpoint]) {
-        return dm[shell.currentBreakpoint as Breakpoint] as SidebarMode;
-      }
-      const bpKeys = Object.keys(BREAKPOINTS) as Array<keyof typeof BREAKPOINTS>;
-      const order: Breakpoint[] = ([...bpKeys].reverse() as Breakpoint[]).concat('initial' as Breakpoint);
-      const startIdx = order.indexOf(shell.currentBreakpoint as Breakpoint);
-      for (let i = startIdx + 1; i < order.length; i++) {
-        const bp = order[i];
-        if (dm && dm[bp]) return dm[bp] as SidebarMode;
-      }
-      return 'collapsed';
-    }, [defaultMode, shell.currentBreakpoint]);
-
     // Register custom toggle behavior based on toggleModes (both|single)
     const shellForToggle = useShell();
     const resolveDefaultSidebarMode = React.useCallback((): SidebarMode => {
-      const resolved = resolveResponsiveMode();
+      const resolved = defaultState ?? 'expanded';
       return resolved === 'thin' || resolved === 'expanded' ? resolved : 'expanded';
-    }, [resolveResponsiveMode]);
+    }, [defaultState]);
 
     React.useEffect(() => {
       if (!shellForToggle.setSidebarToggleComputer) return;
@@ -254,15 +291,7 @@ export const Sidebar = React.forwardRef<
       }
     }, [shell.sidebarMode, thinSize, expandedSize]);
 
-    const lastSidebarBpRef = React.useRef<Breakpoint | null>(null);
-    React.useEffect(() => {
-      if (mode !== undefined) return;
-      if (!shell.currentBreakpointReady) return;
-      if (lastSidebarBpRef.current === shell.currentBreakpoint) return;
-      lastSidebarBpRef.current = shell.currentBreakpoint as Breakpoint;
-      const next = resolveResponsiveMode();
-      if (next !== shell.sidebarMode) shell.setSidebarMode(next);
-    }, [mode, shell.currentBreakpoint, shell.currentBreakpointReady, resolveResponsiveMode, shell.sidebarMode, shell.setSidebarMode]);
+    // Remove responsive default mode behavior entirely
 
     const handleEl =
       resizable && !isOverlay && shell.sidebarMode === 'expanded' ? (
@@ -284,6 +313,7 @@ export const Sidebar = React.forwardRef<
             onResizeStart,
             onResizeEnd: (size) => {
               onResizeEnd?.(size);
+              emitSizeChange(size, { reason: 'resize' });
               persistenceAdapter?.save?.(size);
             },
             target: 'sidebar',
@@ -299,6 +329,61 @@ export const Sidebar = React.forwardRef<
         </PaneResizeContext.Provider>
       ) : null;
 
+    // Strip new API props from DOM
+    const { state: _s, defaultState: _ds, onStateChange: _osc, size: _sz, defaultSize: _dsz, onSizeChange: _onsc, sizeUpdate: _szu, sizeUpdateMs: _szums, ...domProps } = props as any;
+
+    // Normalize CSS lengths to px
+    const normalizeToPx = React.useCallback((value: number | string | undefined): number | undefined => {
+      if (value == null) return undefined;
+      if (typeof value === 'number' && Number.isFinite(value)) return value;
+      const str = String(value).trim();
+      if (!str) return undefined;
+      if (str.endsWith('px')) return Number.parseFloat(str);
+      if (str.endsWith('rem')) {
+        const rem = Number.parseFloat(getComputedStyle(document.documentElement).fontSize || '16') || 16;
+        return Number.parseFloat(str) * rem;
+      }
+      if (str.endsWith('%')) {
+        const pct = Number.parseFloat(str);
+        const base = document.documentElement.clientWidth || window.innerWidth || 0;
+        return (pct / 100) * base;
+      }
+      const n = Number.parseFloat(str);
+      return Number.isFinite(n) ? n : undefined;
+    }, []);
+
+    // Apply defaultSize on mount when uncontrolled
+    React.useEffect(() => {
+      if (!localRef.current) return;
+      const { size, defaultSize } = props as any;
+      if (typeof size === 'undefined' && typeof defaultSize !== 'undefined') {
+        const px = normalizeToPx(defaultSize);
+        if (typeof px === 'number' && Number.isFinite(px)) {
+          const minPx = typeof minSize === 'number' ? minSize : undefined;
+          const maxPx = typeof maxSize === 'number' ? maxSize : undefined;
+          const clamped = Math.min(maxPx ?? px, Math.max(minPx ?? px, px));
+          localRef.current.style.setProperty('--sidebar-size', `${clamped}px`);
+          emitSizeChange(clamped, { reason: 'init' });
+        }
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // Controlled size sync
+    React.useEffect(() => {
+      if (!localRef.current) return;
+      const { size } = props as any;
+      if (typeof size === 'undefined') return;
+      const px = normalizeToPx(size);
+      if (typeof px === 'number' && Number.isFinite(px)) {
+        const minPx = typeof minSize === 'number' ? minSize : undefined;
+        const maxPx = typeof maxSize === 'number' ? maxSize : undefined;
+        const clamped = Math.min(maxPx ?? px, Math.max(minPx ?? px, px));
+        localRef.current.style.setProperty('--sidebar-size', `${clamped}px`);
+        emitSizeChange(clamped, { reason: 'controlled' });
+      }
+    }, [(props as any).size, minSize, maxSize, normalizeToPx, emitSizeChange]);
+
     if (isOverlay) {
       const open = shell.sidebarMode !== 'collapsed';
       return (
@@ -311,23 +396,22 @@ export const Sidebar = React.forwardRef<
             }}
           >
             <VisuallyHidden>
-              <Sheet.Title>Sidebar</Sheet.Title>
+              <Sheet.Title>Navigation</Sheet.Title>
             </VisuallyHidden>
             {contentChildren}
           </Sheet.Content>
         </Sheet.Root>
       );
     }
-
     return (
       <div
-        {...props}
+        {...domProps}
         ref={setRef}
         className={classNames('rt-ShellSidebar', className)}
         data-mode={shell.sidebarMode}
         data-peek={shell.peekTarget === 'sidebar' || undefined}
-        data-presentation={resolvedPresentation}
-        data-open={(isStacked && isContentVisible) || undefined}
+        data-presentation={shell.currentBreakpointReady ? resolvedPresentation : undefined}
+        data-open={(shell.currentBreakpointReady && isStacked && isContentVisible) || undefined}
         style={{
           ...style,
           ['--sidebar-size' as any]: `${expandedSize}px`,
@@ -357,7 +441,7 @@ export const Sidebar = React.forwardRef<
             : {}),
         }}
       >
-        <div className="rt-ShellSidebarContent" data-visible={isContentVisible || undefined} data-phase={transitionPhase && transitionPhase !== 'idle' ? transitionPhase : undefined}>
+        <div className="rt-ShellSidebarContent" data-visible={isContentVisible || undefined}>
           {contentChildren}
         </div>
         {handleEl}