@kushagradhawan/kookie-ui 0.1.49 → 0.1.51

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

@@ -3,7 +3,7 @@ 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 { InspectorHandle, PaneHandle } from './shell-handles.js';
 import { BREAKPOINTS } from '../shell.types.js';
@@ -11,9 +11,7 @@ import type { Breakpoint, PaneMode, PaneSizePersistence, ResponsivePresentation
 
 interface PaneProps extends React.ComponentPropsWithoutRef<'div'> {
   presentation?: ResponsivePresentation;
-  mode?: PaneMode;
-  defaultMode?: any;
-  onModeChange?: (mode: PaneMode) => void;
+  // legacy mode removed
   expandedSize?: number;
   minSize?: number;
   maxSize?: number;
@@ -32,16 +30,29 @@ interface PaneProps extends React.ComponentPropsWithoutRef<'div'> {
   persistence?: PaneSizePersistence;
 }
 
-type InspectorComponent = React.ForwardRefExoticComponent<PaneProps & React.RefAttributes<HTMLDivElement>> & { Handle: typeof InspectorHandle };
+type InspectorOpenChangeMeta = { reason: 'init' | 'toggle' | 'responsive' };
+type InspectorControlledProps = { open: boolean | Partial<Record<Breakpoint, boolean>>; onOpenChange?: (open: boolean, meta: InspectorOpenChangeMeta) => void; defaultOpen?: never };
+type InspectorUncontrolledProps = { defaultOpen?: boolean | Partial<Record<Breakpoint, boolean>>; onOpenChange?: (open: boolean, meta: InspectorOpenChangeMeta) => void; open?: never };
+type InspectorSizeChangeMeta = { reason: 'init' | 'resize' | 'controlled' };
+type InspectorPublicProps = PaneProps &
+  (InspectorControlledProps | InspectorUncontrolledProps) & {
+    onSizeChange?: (size: number, meta: InspectorSizeChangeMeta) => void;
+    sizeUpdate?: 'throttle' | 'debounce';
+    sizeUpdateMs?: number;
+  };
 
-export const Inspector = React.forwardRef<HTMLDivElement, PaneProps>(
+type InspectorComponent = React.ForwardRefExoticComponent<InspectorPublicProps & React.RefAttributes<HTMLDivElement>> & { Handle: typeof InspectorHandle };
+
+export const Inspector = React.forwardRef<HTMLDivElement, InspectorPublicProps>(
   (
     {
       className,
       presentation = { initial: 'overlay', lg: 'fixed' },
-      mode,
-      defaultMode = 'collapsed',
-      onModeChange,
+      // removed legacy props
+      // new API
+      defaultOpen,
+      open,
+      onOpenChange,
       expandedSize = 320,
       minSize = 200,
       maxSize = 500,
@@ -80,47 +91,104 @@ export const Inspector = React.forwardRef<HTMLDivElement, PaneProps>(
     const handleChildren = childArray.filter((el: React.ReactElement) => React.isValidElement(el) && el.type === InspectorHandle);
     const contentChildren = childArray.filter((el: React.ReactElement) => !(React.isValidElement(el) && el.type === InspectorHandle));
 
-    const resolveResponsiveMode = React.useCallback((): PaneMode => {
-      if (typeof defaultMode === 'string') return defaultMode as PaneMode;
-      const dm = defaultMode as Partial<Record<Breakpoint, PaneMode>> | undefined;
-      if (dm && dm[shell.currentBreakpoint as Breakpoint]) {
-        return dm[shell.currentBreakpoint as Breakpoint] as PaneMode;
+    // Throttled/debounced emitter for onSizeChange
+    const emitSizeChange = React.useMemo(() => {
+      const cb = (props as any).onSizeChange as undefined | ((s: number, meta: InspectorSizeChangeMeta) => 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: InspectorSizeChangeMeta) => {
+          if (t) clearTimeout(t);
+          t = setTimeout(() => {
+            cb(s, meta);
+          }, ms);
+        };
       }
-      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 PaneMode;
-        }
+      if (strategy === 'throttle') {
+        let last = 0;
+        return (s: number, meta: InspectorSizeChangeMeta) => {
+          const now = Date.now();
+          if (now - last >= ms) {
+            last = now;
+            cb(s, meta);
+          }
+        };
       }
-      return 'collapsed';
-    }, [defaultMode, shell.currentBreakpoint]);
+      return (s: number, meta: InspectorSizeChangeMeta) => cb(s, meta);
+    }, [(props as any).onSizeChange, (props as any).sizeUpdate, (props as any).sizeUpdateMs]);
 
-    const lastInspectorBpRef = React.useRef<Breakpoint | null>(null);
-    React.useEffect(() => {
-      if (mode !== undefined) return;
-      if (!shell.currentBreakpointReady) return;
-      if (lastInspectorBpRef.current === shell.currentBreakpoint) return;
-      lastInspectorBpRef.current = shell.currentBreakpoint as Breakpoint;
-      const next = resolveResponsiveMode();
-      if (next !== shell.inspectorMode) {
-        shell.setInspectorMode(next);
+    // Dev guards
+    const wasControlledRef = React.useRef<boolean | null>(null);
+    if (process.env.NODE_ENV !== 'production') {
+      if (typeof open !== 'undefined' && typeof defaultOpen !== 'undefined') {
+        // eslint-disable-next-line no-console
+        console.error('Shell.Inspector: Do not pass both `open` and `defaultOpen`. Choose one.');
       }
-    }, [mode, shell.currentBreakpoint, shell.currentBreakpointReady, resolveResponsiveMode, shell.inspectorMode, shell.setInspectorMode]);
+    }
 
+    // Warn on controlled/uncontrolled mode switch
     React.useEffect(() => {
-      if (mode !== undefined && shell.inspectorMode !== mode) {
-        shell.setInspectorMode(mode);
+      const isControlled = typeof open !== 'undefined';
+      if (wasControlledRef.current === null) {
+        wasControlledRef.current = isControlled;
+        return;
+      }
+      if (wasControlledRef.current !== isControlled) {
+        // eslint-disable-next-line no-console
+        console.warn('Shell.Inspector: Switching between controlled and uncontrolled `open` is not supported.');
+        wasControlledRef.current = isControlled;
       }
-    }, [mode, shell]);
+    }, [open]);
+
+    const responsiveNotifiedRef = React.useRef(false);
+    const didInitFromDefaultOpenRef = React.useRef(false);
+    const resolvedDefaultOpen = useResponsiveValue(defaultOpen);
+    React.useEffect(() => {
+      if (!shell.currentBreakpointReady) return;
+      if (didInitFromDefaultOpenRef.current) return;
+      if (typeof open !== 'undefined') return; // controlled ignores default
+      if (typeof defaultOpen === 'undefined') return;
+      const initialOpen = Boolean(resolvedDefaultOpen);
+      shell.setInspectorMode(initialOpen ? 'expanded' : 'collapsed');
+      if (initialOpen) onOpenChange?.(true, { reason: 'init' });
+      didInitFromDefaultOpenRef.current = true;
+    }, [shell.currentBreakpointReady, resolvedDefaultOpen, defaultOpen, open, onOpenChange]);
 
+    // Controlled responsive open
+    const resolvedOpen = useResponsiveValue(open);
     React.useEffect(() => {
-      if (mode === undefined) {
-        onModeChange?.(shell.inspectorMode);
+      if (typeof resolvedOpen === 'undefined') return;
+      const shouldExpand = Boolean(resolvedOpen);
+      if (shouldExpand && shell.inspectorMode !== 'expanded') shell.setInspectorMode('expanded');
+      if (!shouldExpand && shell.inspectorMode !== 'collapsed') shell.setInspectorMode('collapsed');
+    }, [resolvedOpen, shell.inspectorMode]);
+
+    // Removed boolean-only mount init; handled in responsive init effect above
+
+    // Removed: boolean-only controlled sync. Use responsive-resolved effect below instead.
+
+    const initNotifiedRef = React.useRef(false);
+    const lastInspectorModeRef = React.useRef<PaneMode | null>(null);
+    React.useEffect(() => {
+      // Notify init open
+      if (!initNotifiedRef.current && typeof open === 'undefined' && defaultOpen && shell.inspectorMode === 'expanded') {
+        onOpenChange?.(true, { reason: 'init' });
+        initNotifiedRef.current = true;
       }
-    }, [shell.inspectorMode, mode, onModeChange]);
+
+      // Notify toggles when uncontrolled (avoid double-notify after responsive change)
+      if (typeof open === 'undefined') {
+        if (lastInspectorModeRef.current !== null && lastInspectorModeRef.current !== shell.inspectorMode) {
+          if (!responsiveNotifiedRef.current) {
+            onOpenChange?.(shell.inspectorMode === 'expanded', { reason: 'toggle' });
+          }
+          responsiveNotifiedRef.current = false;
+        }
+        lastInspectorModeRef.current = shell.inspectorMode;
+      }
+    }, [shell.inspectorMode, open, defaultOpen, onOpenChange]);
 
     React.useEffect(() => {
       if (shell.inspectorMode === 'expanded') {
@@ -184,6 +252,7 @@ export const Inspector = React.forwardRef<HTMLDivElement, PaneProps>(
             onResizeStart,
             onResizeEnd: (size) => {
               onResizeEnd?.(size);
+              emitSizeChange(size, { reason: 'resize' });
               persistenceAdapter?.save?.(size);
             },
             target: 'inspector',
@@ -199,6 +268,56 @@ export const Inspector = React.forwardRef<HTMLDivElement, PaneProps>(
         </PaneResizeContext.Provider>
       ) : null;
 
+    // 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;
+      if (typeof (props as any).size === 'undefined' && typeof (props as any).defaultSize !== 'undefined') {
+        const px = normalizeToPx((props as any).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('--inspector-size', `${clamped}px`);
+          emitSizeChange(clamped, { reason: 'init' });
+        }
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // Controlled size sync
+    React.useEffect(() => {
+      if (!localRef.current) return;
+      if (typeof (props as any).size === 'undefined') return;
+      const px = normalizeToPx((props as any).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('--inspector-size', `${clamped}px`);
+        emitSizeChange(clamped, { reason: 'controlled' });
+      }
+    }, [(props as any).size, minSize, maxSize, normalizeToPx, emitSizeChange]);
+
     if (isOverlay) {
       const open = shell.inspectorMode === 'expanded';
       return (
@@ -213,15 +332,28 @@ export const Inspector = React.forwardRef<HTMLDivElement, PaneProps>(
       );
     }
 
+    // Strip control/size props from DOM spread
+    const {
+      defaultOpen: _inspectorDefaultOpenIgnored,
+      open: _inspectorOpenIgnored,
+      onOpenChange: _inspectorOnOpenChangeIgnored,
+      size: _sz,
+      defaultSize: _dsz,
+      onSizeChange: _osc,
+      sizeUpdate: _szu,
+      sizeUpdateMs: _szums,
+      ...inspectorDomProps
+    } = props as any;
+
     return (
       <div
-        {...props}
+        {...inspectorDomProps}
         ref={setRef}
         className={classNames('rt-ShellInspector', className)}
         data-mode={shell.inspectorMode}
         data-peek={shell.peekTarget === 'inspector' || undefined}
-        data-presentation={resolvedPresentation}
-        data-open={(isStacked && isExpanded) || undefined}
+        data-presentation={shell.currentBreakpointReady ? resolvedPresentation : undefined}
+        data-open={(shell.currentBreakpointReady && isStacked && isExpanded) || undefined}
         style={{
           ...style,
           ['--inspector-size' as any]: `${expandedSize}px`,

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,6 +86,7 @@ export const Sidebar = React.forwardRef<
     const resolvedPresentation = useResponsivePresentation(presentation);
     const isOverlay = resolvedPresentation === 'overlay';
     const isStacked = resolvedPresentation === 'stacked';
+    // Phase sequencing is now CSS-driven; no JS-managed phase
     const localRef = React.useRef<HTMLDivElement | null>(null);
     const setRef = React.useCallback(
       (node: HTMLDivElement | null) => {
@@ -99,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(() => {
@@ -108,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(() => {
@@ -178,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;
@@ -231,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' ? (
@@ -261,6 +313,7 @@ export const Sidebar = React.forwardRef<
             onResizeStart,
             onResizeEnd: (size) => {
               onResizeEnd?.(size);
+              emitSizeChange(size, { reason: 'resize' });
               persistenceAdapter?.save?.(size);
             },
             target: 'sidebar',
@@ -276,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 (
@@ -288,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`,