@womp/kookie-ui 0.3.23 → 0.3.25

package/src/components/shell.tsx

@@ -36,6 +36,7 @@ import { omitPaneProps, extractPaneDomProps, mapResponsiveBooleanToPaneMode } fr
 import { Sidebar } from './_internal/shell-sidebar.js';
 import { Bottom } from './_internal/shell-bottom.js';
 import { Inspector } from './_internal/shell-inspector.js';
+import { _BREAKPOINTS } from './shell.types.js';
 import type { PresentationValue, ResponsivePresentation, PaneMode, SidebarMode, PaneSizePersistence, Breakpoint, PaneTarget, Responsive, PaneBaseProps, CSSPropertiesWithVars } from './shell.types.js';
 import { normalizeToPx } from '../helpers/normalize-to-px.js';
 import { useBreakpoint } from '../hooks/use-breakpoint.js';
@@ -222,114 +223,143 @@ interface ShellRootProps extends React.ComponentPropsWithoutRef<'div'> {
   height?: 'full' | 'auto' | string | number;
 }
 
-const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', ...props }, ref) => {
-  const { breakpoint: currentBreakpoint, ready: currentBreakpointReady } = useBreakpoint();
-
-  // Store hasPanelDefaultOpen for use in passthrough props (computed once during lazy init)
-  const hasPanelDefaultOpenRef = React.useRef<boolean>(false);
+/**
+ * Read the pane modes a set of Shell children asks for.
+ *
+ * Runs once at mount, for the reducer's initial state, and again whenever a
+ * pane family enters after mount. Pure - it only reads the children's props.
+ */
+/**
+ * Pick the entry of a responsive map that applies at `breakpoint`, falling
+ * back down the scale the way useResponsiveValue does. With no breakpoint it
+ * takes `initial`, which is what the mount path has always done.
+ */
+function pickResponsive<T>(map: Partial<Record<Breakpoint, T>>, breakpoint?: Breakpoint): T | undefined {
+  if (breakpoint === undefined) return (map.initial ?? Object.values(map)[0]) as T | undefined;
+  if (map[breakpoint] !== undefined) return map[breakpoint];
+
+  const bpKeys = Object.keys(_BREAKPOINTS) as Array<keyof typeof _BREAKPOINTS>;
+  const order: Breakpoint[] = ([...bpKeys].reverse() as Breakpoint[]).concat('initial' as Breakpoint);
+  for (let i = order.indexOf(breakpoint) + 1; i < order.length; i++) {
+    if (map[order[i]] !== undefined) return map[order[i]];
+  }
+  return undefined;
+}
 
-  // Pane state management via reducer with lazy initialization
-  // This computation only runs once on mount, not on every render
-  const [paneState, dispatchPane] = React.useReducer(paneReducer, children, (initialChildren) => {
-    const childArray = React.Children.toArray(initialChildren) as React.ReactElement[];
+function readPaneStateFromChildren(initialChildren: React.ReactNode, breakpoint?: Breakpoint): PaneState & { hasPanelDefaultOpen: boolean } {
+  const childArray = React.Children.toArray(initialChildren) as React.ReactElement[];
 
-    // Compute initial defaults from immediate children (one-time, uncontrolled defaults)
-    const hasPanelDefaultOpen = childArray.some(
-      (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Panel' && Boolean((el as any).props?.defaultOpen),
-    );
-    // Store for use in passthrough props
-    hasPanelDefaultOpenRef.current = hasPanelDefaultOpen;
+  // Compute initial defaults from immediate children (one-time, uncontrolled defaults)
+  const hasPanelDefaultOpen = childArray.some(
+    (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Panel' && Boolean((el as any).props?.defaultOpen),
+  );
 
-    // Rail defaults to open (true) unless explicitly set to false
-    // Supports responsive objects: { initial: false, md: true }
-    const railEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Rail');
-    const railDefaultOpen = railEl ? (railEl as any).props?.defaultOpen : undefined;
-    const hasRailDefaultOpen = (() => {
-      if (!railEl) return false;
-      if (railDefaultOpen === undefined) return true; // Default to open
-      if (typeof railDefaultOpen === 'boolean') return railDefaultOpen;
-      // Responsive object - use 'initial' value, or first defined value, or default true
-      if (typeof railDefaultOpen === 'object') {
-        return railDefaultOpen.initial ?? Object.values(railDefaultOpen)[0] ?? true;
-      }
-      return true;
-    })();
+  // Rail defaults to open (true) unless explicitly set to false
+  // Supports responsive objects: { initial: false, md: true }
+  const railEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Rail');
+  const railDefaultOpen = railEl ? (railEl as any).props?.defaultOpen : undefined;
+  const hasRailDefaultOpen = (() => {
+    if (!railEl) return false;
+    if (railDefaultOpen === undefined) return true; // Default to open
+    if (typeof railDefaultOpen === 'boolean') return railDefaultOpen;
+    // Responsive object - use 'initial' value, or first defined value, or default true
+    if (typeof railDefaultOpen === 'object') {
+      return railDefaultOpen.initial ?? Object.values(railDefaultOpen)[0] ?? true;
+    }
+    return true;
+  })();
 
-    const hasInspectorDefaultOpen = childArray.some(
-      (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Inspector' && Boolean((el as any).props?.defaultOpen),
-    );
-    const hasInspectorOpenControlled = childArray.some(
-      (el) =>
-        React.isValidElement(el) &&
-        (el as any).type?.displayName === 'Shell.Inspector' &&
-        typeof (el as any).props?.open !== 'undefined' &&
-        Boolean((el as any).props?.open),
-    );
+  const hasInspectorDefaultOpen = childArray.some(
+    (el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Inspector' && Boolean((el as any).props?.defaultOpen),
+  );
+  const hasInspectorOpenControlled = childArray.some(
+    (el) =>
+      React.isValidElement(el) &&
+      (el as any).type?.displayName === 'Shell.Inspector' &&
+      typeof (el as any).props?.open !== 'undefined' &&
+      Boolean((el as any).props?.open),
+  );
 
-    // Detect Panel controlled open state for initial reducer state
-    const hasPanelOpenControlled = childArray.some((el) => {
-      if (!React.isValidElement(el) || (el as any).type?.displayName !== 'Shell.Panel') return false;
-      const openProp = (el as any).props?.open;
-      if (typeof openProp === 'undefined') return false;
-      if (typeof openProp === 'boolean') return openProp;
-      // Responsive object - check 'initial' or first truthy value
-      if (typeof openProp === 'object' && openProp !== null) {
-        return openProp.initial ?? Object.values(openProp)[0] ?? false;
-      }
-      return false;
-    });
+  // Detect Panel controlled open state for initial reducer state
+  const hasPanelOpenControlled = childArray.some((el) => {
+    if (!React.isValidElement(el) || (el as any).type?.displayName !== 'Shell.Panel') return false;
+    const openProp = (el as any).props?.open;
+    if (typeof openProp === 'undefined') return false;
+    if (typeof openProp === 'boolean') return openProp;
+    // Responsive object - check 'initial' or first truthy value
+    if (typeof openProp === 'object' && openProp !== null) {
+      return openProp.initial ?? Object.values(openProp)[0] ?? false;
+    }
+    return false;
+  });
 
-    // Detect Sidebar initial state from props
-    const getSidebarInitialState = (): SidebarMode => {
-      const sidebarEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Sidebar');
-      if (!sidebarEl) return 'expanded';
-      const sidebarProps = (sidebarEl as any).props;
-      // Check controlled state first
-      if (typeof sidebarProps?.state !== 'undefined') {
-        if (typeof sidebarProps.state === 'string') return sidebarProps.state as SidebarMode;
-        // Responsive object - use 'initial' breakpoint or first defined value
-        if (typeof sidebarProps.state === 'object') {
-          return (sidebarProps.state.initial ?? Object.values(sidebarProps.state)[0] ?? 'expanded') as SidebarMode;
-        }
+  // Detect Sidebar initial state from props
+  const getSidebarInitialState = (): SidebarMode => {
+    const sidebarEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Sidebar');
+    if (!sidebarEl) return 'expanded';
+    const sidebarProps = (sidebarEl as any).props;
+    // Check controlled state first
+    if (typeof sidebarProps?.state !== 'undefined') {
+      if (typeof sidebarProps.state === 'string') return sidebarProps.state as SidebarMode;
+      // Responsive object - use 'initial' breakpoint or first defined value
+      if (typeof sidebarProps.state === 'object') {
+        return (pickResponsive<SidebarMode>(sidebarProps.state, breakpoint) ?? 'expanded') as SidebarMode;
       }
-      // Check defaultState
-      if (typeof sidebarProps?.defaultState !== 'undefined') {
-        if (typeof sidebarProps.defaultState === 'string') return sidebarProps.defaultState as SidebarMode;
-        if (typeof sidebarProps.defaultState === 'object') {
-          return (sidebarProps.defaultState.initial ?? Object.values(sidebarProps.defaultState)[0] ?? 'expanded') as SidebarMode;
-        }
+    }
+    // Check defaultState
+    if (typeof sidebarProps?.defaultState !== 'undefined') {
+      if (typeof sidebarProps.defaultState === 'string') return sidebarProps.defaultState as SidebarMode;
+      if (typeof sidebarProps.defaultState === 'object') {
+        return (pickResponsive<SidebarMode>(sidebarProps.defaultState, breakpoint) ?? 'expanded') as SidebarMode;
       }
-      return 'expanded';
-    };
+    }
+    return 'expanded';
+  };
 
-    // Detect Bottom initial state from props
-    const getBottomInitialState = (): PaneMode => {
-      const bottomEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Bottom');
-      if (!bottomEl) return 'collapsed';
-      const bottomProps = (bottomEl as any).props;
-      // Check controlled open first
-      if (typeof bottomProps?.open !== 'undefined') {
-        if (typeof bottomProps.open === 'boolean') return bottomProps.open ? 'expanded' : 'collapsed';
-        // Responsive object - use 'initial' breakpoint or first defined value
-        if (typeof bottomProps.open === 'object') {
-          const val = bottomProps.open.initial ?? Object.values(bottomProps.open)[0];
-          return val ? 'expanded' : 'collapsed';
-        }
+  // Detect Bottom initial state from props
+  const getBottomInitialState = (): PaneMode => {
+    const bottomEl = childArray.find((el) => React.isValidElement(el) && (el as any).type?.displayName === 'Shell.Bottom');
+    if (!bottomEl) return 'collapsed';
+    const bottomProps = (bottomEl as any).props;
+    // Check controlled open first
+    if (typeof bottomProps?.open !== 'undefined') {
+      if (typeof bottomProps.open === 'boolean') return bottomProps.open ? 'expanded' : 'collapsed';
+      // Responsive object - use 'initial' breakpoint or first defined value
+      if (typeof bottomProps.open === 'object') {
+        const val = bottomProps.open.initial ?? Object.values(bottomProps.open)[0];
+        return val ? 'expanded' : 'collapsed';
       }
-      // Check defaultOpen
-      if (typeof bottomProps?.defaultOpen !== 'undefined') {
-        return bottomProps.defaultOpen ? 'expanded' : 'collapsed';
-      }
-      return 'collapsed';
-    };
+    }
+    // Check defaultOpen
+    if (typeof bottomProps?.defaultOpen !== 'undefined') {
+      return bottomProps.defaultOpen ? 'expanded' : 'collapsed';
+    }
+    return 'collapsed';
+  };
 
-    return {
-      leftMode: hasPanelDefaultOpen || hasPanelOpenControlled || hasRailDefaultOpen ? 'expanded' : ('collapsed' as PaneMode),
-      panelMode: hasPanelDefaultOpen || hasPanelOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
-      sidebarMode: getSidebarInitialState(),
-      inspectorMode: hasInspectorDefaultOpen || hasInspectorOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
-      bottomMode: getBottomInitialState(),
-    };
+  return {
+    hasPanelDefaultOpen,
+    leftMode: hasPanelDefaultOpen || hasPanelOpenControlled || hasRailDefaultOpen ? 'expanded' : ('collapsed' as PaneMode),
+    panelMode: hasPanelDefaultOpen || hasPanelOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
+    sidebarMode: getSidebarInitialState(),
+    inspectorMode: hasInspectorDefaultOpen || hasInspectorOpenControlled ? 'expanded' : ('collapsed' as PaneMode),
+    bottomMode: getBottomInitialState(),
+  };
+}
+
+const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', ...props }, ref) => {
+  const { breakpoint: currentBreakpoint, ready: currentBreakpointReady } = useBreakpoint();
+
+  // Store hasPanelDefaultOpen for use in passthrough props (computed once during lazy init)
+  const hasPanelDefaultOpenRef = React.useRef<boolean>(false);
+
+  // Pane state management via reducer with lazy initialization
+  // This computation only runs once on mount, not on every render
+  const [paneState, dispatchPane] = React.useReducer(paneReducer, children, (initialChildren) => {
+    const { hasPanelDefaultOpen, ...modes } = readPaneStateFromChildren(initialChildren);
+    // Store for use in passthrough props
+    hasPanelDefaultOpenRef.current = hasPanelDefaultOpen;
+    return modes;
   });
   const setLeftMode = React.useCallback((mode: PaneMode) => dispatchPane({ type: 'SET_LEFT_MODE', mode }), []);
   const setPanelMode = React.useCallback((mode: PaneMode) => dispatchPane({ type: 'SET_PANEL_MODE', mode }), []);
@@ -381,6 +411,47 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
     return childArray.some((el) => isShellComponentType(el, Sidebar));
   }, [children]);
 
+  // Re-read the defaults when a pane family enters after mount.
+  //
+  // The initial modes are computed once, from the children present at mount.
+  // That is right until an app swaps families at runtime - a Sidebar giving
+  // way to Rail+Panel on one route, and back on the next. The entering pane
+  // then renders against the mode left behind by the family that just went:
+  // a Rail mounting 'collapsed', at width 0, with its content faded out, put
+  // right one layout effect later. The reader sees a flicker in place where
+  // the pane should have been there already.
+  //
+  // Adjusting state during render keeps this out of the paint: React re-runs
+  // Root before the children render, so the entering pane never sees the
+  // mode of the family it replaced. The ref guard is what makes the update
+  // terminate - it fires only on the edge, never on a steady render.
+  const enteredFamilyRef = React.useRef({ left: hasLeftChildren, sidebar: hasSidebarChildren });
+  if (enteredFamilyRef.current.left !== hasLeftChildren || enteredFamilyRef.current.sidebar !== hasSidebarChildren) {
+    const leftEntered = hasLeftChildren && !enteredFamilyRef.current.left;
+    const sidebarEntered = hasSidebarChildren && !enteredFamilyRef.current.sidebar;
+    enteredFamilyRef.current = { left: hasLeftChildren, sidebar: hasSidebarChildren };
+
+    if (leftEntered || sidebarEntered) {
+      // The live breakpoint, not the mount default: a responsive
+      // defaultState like { initial: 'collapsed', md: 'expanded' } must be
+      // read for the width the reader is on. Taking `initial` would send a
+      // desktop sidebar in collapsed and let its own start-up effect open it
+      // again after the paint, which is the blink this whole block exists to
+      // remove.
+      const { hasPanelDefaultOpen, ...modes } = readPaneStateFromChildren(children, currentBreakpoint as Breakpoint);
+      if (leftEntered) {
+        hasPanelDefaultOpenRef.current = hasPanelDefaultOpen;
+        // Only when the mode actually differs, so a family that enters
+        // already in the right mode dispatches nothing.
+        if (modes.leftMode !== paneState.leftMode) dispatchPane({ type: 'SET_LEFT_MODE', mode: modes.leftMode });
+        if (modes.panelMode !== paneState.panelMode) dispatchPane({ type: 'SET_PANEL_MODE', mode: modes.panelMode });
+      }
+      if (sidebarEntered && modes.sidebarMode !== paneState.sidebarMode) {
+        dispatchPane({ type: 'SET_SIDEBAR_MODE', mode: modes.sidebarMode });
+      }
+    }
+  }
+
   // Keep a ref to sidebar mode so togglePane doesn't depend on it,
   // preventing ActionsContext churn on every sidebar mode change
   const sidebarModeRef = React.useRef(paneState.sidebarMode);