@womp/kookie-ui 0.7.0 → 0.8.0

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

@@ -0,0 +1,283 @@
+'use client';
+
+import * as React from 'react';
+import { readBreakpoint, useBreakpoint } from '../../hooks/use-breakpoint.js';
+import type { Breakpoint, PaneName, PresentationValue } from '../shell.types.js';
+import {
+  constantOf,
+  notifyShellStore,
+  tableAttributes,
+  tableOf,
+  usePeeking,
+  useShellStore,
+  useStableKey,
+  warnOnce,
+  type OpenChangeReason,
+  type PaneEntry,
+  type PaneValue,
+  type Table,
+} from './shell-store.js';
+
+type ResponsiveValue = PaneValue | Partial<Record<Breakpoint, PaneValue>>;
+
+export type UsePaneOptions = {
+  name: PaneName;
+  /** The component's display name, for warnings: `Inspector`, `Sidebar`, … */
+  label: string;
+  /** The prop names a warning should use: `open`/`defaultOpen`, or `state`/`defaultState`. */
+  propNames: { controlled: string; default: string };
+  id: string | undefined;
+  /** The controlled value. A responsive object is deprecated: it is resolved against the current breakpoint. */
+  controlled: ResponsiveValue | undefined;
+  /**
+   * The uncontrolled default. A single value fixes where the pane starts. A
+   * responsive object leaves the pane untouched (`auto`), with that object as
+   * what it shows at each breakpoint.
+   */
+  defaultValue: ResponsiveValue | undefined;
+  /** The pane's presentation at every breakpoint. Pass a memoised table. */
+  presentationTable: Table<PresentationValue>;
+  /** What an untouched pane shows where no default says otherwise. Pass a module-level function. */
+  builtIn: (presentation: PresentationValue) => PaneValue;
+  /** Reports a change a user made. Never called on mount or on a resize. */
+  onChange: ((value: PaneValue, reason: OpenChangeReason) => void) | undefined;
+  /** The value a toggle moves to. Defaults to open and closed in turn. */
+  toggleNext?: (current: PaneValue, defaultHere: PaneValue | undefined) => PaneValue;
+  onExpand: (() => void) | undefined;
+  onCollapse: (() => void) | undefined;
+  /** The pane's designed open width, published for the panes beside it. */
+  size: number;
+};
+
+export type PaneController = ReturnType<typeof usePane>;
+
+const isMap = (value: ResponsiveValue | undefined): value is Partial<Record<Breakpoint, PaneValue>> => typeof value === 'object' && value !== null;
+
+/** The first value a responsive object states, smallest breakpoint first. */
+function firstStated(map: Partial<Record<Breakpoint, PaneValue>>): PaneValue {
+  for (const bp of ['initial', 'xs', 'sm', 'md', 'lg', 'xl'] as const) {
+    const value = map[bp];
+    if (value !== undefined) return value;
+  }
+  return 'closed';
+}
+
+/** Everything the togglable panes share: their state, their registry entry and their callbacks. */
+export function usePane(options: UsePaneOptions) {
+  const { name, label, propNames, presentationTable, builtIn } = options;
+  const store = useShellStore(`Shell.${label}`);
+  const generatedId = React.useId();
+  const id = options.id ?? `shell-${name}${generatedId}`;
+
+  const controlled = options.controlled !== undefined;
+  const controlledIsMap = isMap(options.controlled);
+  if (controlledIsMap) {
+    warnOnce(
+      `Shell.${label}: a responsive \`${propNames.controlled}\` is deprecated and is removed in 1.0. ` +
+        `Pass a boolean and decide it from your own state, or use \`${propNames.default}\` with a responsive object.`,
+    );
+  }
+
+  // A responsive controlled value is resolved the way a responsive default
+  // is: it becomes the table an untouched pane follows, so the stylesheet
+  // answers it at each breakpoint (right in the server HTML, with no
+  // callback on a crossing) and the app's prop is still the only writer.
+  const controlledMap = controlledIsMap ? (options.controlled as Partial<Record<Breakpoint, PaneValue>>) : undefined;
+  const autoSource = controlledMap ?? (isMap(options.defaultValue) ? options.defaultValue : undefined);
+  const autoKey = useStableKey(autoSource);
+  const [inner, setInner] = React.useState<'auto' | PaneValue>(() => (typeof options.defaultValue === 'string' ? options.defaultValue : 'auto'));
+
+  // What an untouched pane shows at each breakpoint: a responsive default
+  // where it states one, the pane's own default where it does not.
+  const autoTable = React.useMemo(
+    () => (controlledMap ? tableOf<PaneValue>(controlledMap, () => firstStated(controlledMap)) : tableOf<PaneValue>(autoSource, (bp) => builtIn(presentationTable[bp]))),
+    // `autoKey` stands for the responsive object, which is usually a new literal each render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [autoKey, controlledIsMap, presentationTable, builtIn],
+  );
+
+  let state: 'auto' | PaneValue = inner;
+  if (controlled) state = controlledMap ? 'auto' : (options.controlled as PaneValue);
+
+  // Only a pane whose answer depends on the window subscribes to it, so a
+  // pane with one presentation and one default never re-renders on a resize.
+  const needsBreakpoint = constantOf(presentationTable) === undefined || (state === 'auto' && constantOf(autoTable) === undefined);
+  const { breakpoint, ready } = useBreakpoint(needsBreakpoint);
+
+  /** A table's value now: known without the window when it holds one value, else once the breakpoint is known. */
+  const now = <T,>(table: Table<T>): T | undefined => {
+    const constant = constantOf(table);
+    if (constant !== undefined) return constant;
+    return ready ? table[breakpoint] : undefined;
+  };
+
+  const value: PaneValue | undefined = state === 'auto' ? now(autoTable) : state;
+  const presentation = now(presentationTable);
+  const overlaying = presentation === 'overlay';
+  const shown = value === undefined ? undefined : value !== 'closed';
+  const overlayLive = shown === true && overlaying;
+
+  // Stable actions over the latest values, so the registry entry changes only
+  // when a fact it carries changes.
+  const defaultValue = options.defaultValue;
+  const latest = React.useRef({ state, value, autoTable, defaultValue, controlled, onChange: options.onChange, toggleNext: options.toggleNext });
+  React.useLayoutEffect(() => {
+    latest.current = { state, value, autoTable, defaultValue, controlled, onChange: options.onChange, toggleNext: options.toggleNext };
+  });
+
+  /**
+   * What the pane shows, and its default, at the window's breakpoint right
+   * now. Asked at the moment of an action rather than taken from the last
+   * render: a touched pane no longer follows the window, and a click can land
+   * before the mirror has resolved after hydration.
+   */
+  const valueNow = React.useCallback((): PaneValue | undefined => {
+    const current = latest.current;
+    if (current.value !== undefined) return current.value;
+    return current.state === 'auto' ? current.autoTable[readBreakpoint()] : undefined;
+  }, []);
+  const defaultHereNow = React.useCallback((): PaneValue | undefined => {
+    const current = latest.current;
+    if (typeof current.defaultValue === 'string') return current.defaultValue;
+    return isMap(current.defaultValue) ? current.autoTable[readBreakpoint()] : undefined;
+  }, []);
+
+  const setValue = React.useCallback(
+    (next: PaneValue, reason: OpenChangeReason) => {
+      const current = latest.current;
+      if (valueNow() === next) return;
+      current.onChange?.(next, reason);
+      if (!current.controlled) setInner(next);
+    },
+    [valueNow],
+  );
+
+  const toggle = React.useCallback(
+    (reason: OpenChangeReason) => {
+      const current = latest.current;
+      const from = valueNow() ?? 'closed';
+      const next = current.toggleNext ? current.toggleNext(from, defaultHereNow()) : from === 'closed' ? 'open' : 'closed';
+      setValue(next, reason);
+    },
+    [setValue, valueNow, defaultHereNow],
+  );
+
+  // The pane's element, for the Root's containment and focus.
+  const elementRef = React.useRef<HTMLElement | null>(null);
+  const setElement = React.useCallback((node: HTMLElement | null) => {
+    elementRef.current = node;
+  }, []);
+
+  // Registration. A layout effect so a Trigger's aria attributes and the
+  // Root's containment are right before the browser paints.
+  React.useLayoutEffect(() => {
+    const entry: PaneEntry = {
+      name,
+      id,
+      el: elementRef.current,
+      value,
+      presentation,
+      presentationTable,
+      overlayLive,
+      size: options.size,
+      setValue,
+      toggle,
+    };
+    store.entries.set(name, entry);
+    notifyShellStore(store);
+    return () => {
+      if (store.entries.get(name) === entry) {
+        store.entries.delete(name);
+        notifyShellStore(store);
+      }
+    };
+  }, [store, name, id, value, presentation, presentationTable, overlayLive, options.size, setValue, toggle]);
+
+  // onExpand/onCollapse fire when the pane's state changes and that changes
+  // whether it is shown: a user's toggle, or a controlled prop. Never on
+  // mount, and never because the window crossed a breakpoint.
+  const callbacks = React.useRef({ onExpand: options.onExpand, onCollapse: options.onCollapse });
+  React.useLayoutEffect(() => {
+    callbacks.current = { onExpand: options.onExpand, onCollapse: options.onCollapse };
+  });
+  const previous = React.useRef({ state, shown });
+  React.useEffect(() => {
+    const before = previous.current;
+    if (before.state !== state && before.shown !== undefined && shown !== undefined && before.shown !== shown) {
+      if (shown) callbacks.current.onExpand?.();
+      else callbacks.current.onCollapse?.();
+    }
+    previous.current = { state, shown };
+  }, [state, shown]);
+
+  // Development guards. Once per mount, not once per render.
+  React.useLayoutEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (options.controlled !== undefined && options.defaultValue !== undefined) {
+      console.error(`Shell.${label}: Do not pass both \`${propNames.controlled}\` and \`${propNames.default}\`. Choose one.`);
+    }
+    // Mount only: this is the once-per-mount guard.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const wasControlled = React.useRef(controlled);
+  React.useEffect(() => {
+    if (process.env.NODE_ENV === 'production') return;
+    if (wasControlled.current !== controlled) {
+      console.warn(`Shell.${label}: Switching between controlled and uncontrolled \`${propNames.controlled}\` is not supported.`);
+      wasControlled.current = controlled;
+    }
+  }, [controlled, label, propNames.controlled]);
+
+  const peeking = usePeeking(store, name) && shown === false && !overlaying;
+
+  return {
+    store,
+    id,
+    state,
+    value,
+    shown,
+    presentation,
+    overlaying,
+    overlayLive,
+    peeking,
+    ready,
+    breakpoint,
+    autoTable,
+    setValue,
+    toggle,
+    defaultHereNow,
+    setElement,
+  };
+}
+
+/** The data attributes every togglable pane renders. */
+export function paneAttributes(pane: PaneController, presentationAttributes: Record<string, string>) {
+  const { state, value, presentation, shown } = pane;
+  return {
+    ...presentationAttributes,
+    'data-state': state === 'thin' ? 'open' : state,
+    'data-thin': state === 'thin' ? '' : undefined,
+    ...(state === 'auto' ? tableAttributes('auto', pane.autoTable) : {}),
+    'data-presentation': presentation,
+    'data-mode': value === undefined ? undefined : value === 'closed' ? 'collapsed' : value === 'thin' ? 'thin' : 'expanded',
+    // Kept for stylesheets written against 0.7: set while a stacked pane is open.
+    'data-open': presentation === 'stacked' && shown ? '' : undefined,
+    'data-peek': pane.peeking ? '' : undefined,
+  } as const;
+}
+
+/** A pane's own presentation, as a table and as the attributes the stylesheet reads. */
+export function usePresentationTable(presentation: Parameters<typeof tableOf<PresentationValue>>[0], fallback: PresentationValue) {
+  const key = useStableKey(presentation);
+  const table = React.useMemo(
+    () => tableOf<PresentationValue>(presentation, () => fallback),
+    // `key` stands for `presentation`, which is usually a new literal each render.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [key, fallback],
+  );
+  // One value is the plain `data-presentation` the pane renders anyway; several
+  // are written per breakpoint, so the stylesheet can place the pane before
+  // any script runs.
+  const attributes = React.useMemo(() => (constantOf(table) === undefined ? tableAttributes('presentation', table) : ({} as Record<string, string>)), [table]);
+  return { table, attributes };
+}

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

@@ -0,0 +1,263 @@
+'use client';
+
+import * as React from 'react';
+import { normalizeToPx } from '../../helpers/normalize-to-px.js';
+import type { PaneName, PaneSizePersistence } from '../shell.types.js';
+import type { PaneResizeContextValue } from './shell-resize.js';
+
+export type SizeChangeMeta = { reason: 'init' | 'resize' | 'controlled' };
+
+export type ResizableOptions = {
+  name: PaneName;
+  /** The pane's element id, which the handle names in `aria-controls`. */
+  elementId: string;
+  elementRef: React.RefObject<HTMLElement | null>;
+  cssVarName: string;
+  orientation: 'vertical' | 'horizontal';
+  edge: 'start' | 'end';
+  growth: (isRtl: boolean) => 1 | -1;
+  expandedSize: number;
+  minSize: number;
+  maxSize: number;
+  resizable: boolean;
+  collapsible: boolean;
+  size: number | string | undefined;
+  defaultSize: number | string | undefined;
+  onSizeChange: ((size: number, meta: SizeChangeMeta) => void) | undefined;
+  sizeUpdate: 'throttle' | 'debounce' | undefined;
+  sizeUpdateMs: number;
+  onResize: ((size: number) => void) | undefined;
+  onResizeStart: ((size: number) => void) | undefined;
+  onResizeEnd: ((size: number) => void) | undefined;
+  snapPoints: number[] | undefined;
+  snapTolerance: number | undefined;
+  collapseThreshold: number | undefined;
+  paneId: string | undefined;
+  persistence: PaneSizePersistence | undefined;
+  /** Whether the pane is presented as an overlay right now. An overlay keeps its designed size and persists nothing. */
+  overlaying: boolean;
+  /** The same question asked at effect time, for a pane whose presentation is learnt after its first render. */
+  overlayingNow: () => boolean;
+  requestCollapse: () => void;
+  requestToggle: () => void;
+};
+
+/**
+ * Clamps to [min, max]. When the two cross (an app passing a maximum computed
+ * from a narrow window below its fixed minimum), the minimum wins, as it did
+ * in 0.7.
+ */
+const clampTo = (value: number, min: number | undefined, max: number | undefined) => Math.max(min ?? value, Math.min(max ?? value, value));
+
+/** Everything a resizable pane shares: size props, persistence, and the handle's context. */
+export function useResizablePane(options: ResizableOptions): PaneResizeContextValue {
+  const { name, elementRef, cssVarName, orientation, minSize, maxSize, resizable, size, defaultSize, paneId, persistence } = options;
+
+  // The latest callbacks, so the size emitter does not change identity when a
+  // consumer passes an inline function. A controlled `size` is reported again
+  // only when the size, the minimum or the maximum changes.
+  const latest = React.useRef(options);
+  React.useLayoutEffect(() => {
+    latest.current = options;
+  });
+
+  const debounceRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+  const throttleRef = React.useRef(0);
+  React.useEffect(
+    () => () => {
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+    },
+    [],
+  );
+  const emitSizeChange = React.useCallback((value: number, meta: SizeChangeMeta) => {
+    const { onSizeChange, sizeUpdate, sizeUpdateMs } = latest.current;
+    if (!onSizeChange) return;
+    if (sizeUpdate === 'debounce') {
+      if (debounceRef.current) clearTimeout(debounceRef.current);
+      debounceRef.current = setTimeout(() => {
+        debounceRef.current = null;
+        latest.current.onSizeChange?.(value, meta);
+      }, sizeUpdateMs);
+      return;
+    }
+    if (sizeUpdate === 'throttle') {
+      const now = Date.now();
+      if (now - throttleRef.current < sizeUpdateMs) return;
+      throttleRef.current = now;
+    }
+    onSizeChange(value, meta);
+  }, []);
+
+  const toPx = React.useCallback((value: number | string | undefined) => normalizeToPx(value, orientation === 'vertical' ? 'horizontal' : 'vertical'), [orientation]);
+
+  /**
+   * The one way a size reaches the pane: the size variable, and the value
+   * every handle of this pane announces. Once anything but `expandedSize` has
+   * written a size (a default, a controlled value, a persisted value or a
+   * resize), the pane owns that size and a new `expandedSize` leaves it alone.
+   */
+  const ownedRef = React.useRef(false);
+  const writeSize = React.useCallback(
+    (value: number, own: boolean) => {
+      const el = elementRef.current;
+      if (!el) return;
+      el.style.setProperty(cssVarName, `${value}px`);
+      for (const handle of el.querySelectorAll(':scope > .rt-ShellResizer')) handle.setAttribute('aria-valuenow', String(Math.round(value)));
+      if (own) ownedRef.current = true;
+    },
+    [elementRef, cssVarName],
+  );
+
+  // expandedSize: the size until something else sets one. Declared first, so
+  // the effects below win on mount.
+  React.useLayoutEffect(() => {
+    if (!ownedRef.current) writeSize(options.expandedSize, false);
+  }, [options.expandedSize, writeSize]);
+
+  // defaultSize: applied once, on mount.
+  React.useLayoutEffect(() => {
+    if (size !== undefined || defaultSize === undefined) return;
+    const px = toPx(defaultSize);
+    if (typeof px !== 'number' || !Number.isFinite(px)) return;
+    const clamped = clampTo(px, minSize, maxSize);
+    writeSize(clamped, true);
+    emitSizeChange(clamped, { reason: 'init' });
+    // An uncontrolled initial value: applied on mount and never re-applied.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Controlled size. A drag stands until the app passes a different value.
+  // Not while the pane is an overlay: an overlay keeps its designed size, and
+  // an app's frame-sized limits (a maximum taken from the window) would
+  // otherwise squeeze the drawer and report the squeezed size back. The size
+  // is applied again when the pane returns to the frame.
+  React.useLayoutEffect(() => {
+    if (size === undefined || latest.current.overlayingNow()) return;
+    const px = toPx(size);
+    if (typeof px !== 'number' || !Number.isFinite(px)) return;
+    const clamped = clampTo(px, minSize, maxSize);
+    writeSize(clamped, true);
+    emitSizeChange(clamped, { reason: 'controlled' });
+  }, [size, minSize, maxSize, options.overlaying, toPx, writeSize, emitSizeChange]);
+
+  // A persistence adapter from `paneId` when none is given.
+  const adapter = React.useMemo<PaneSizePersistence | undefined>(() => {
+    if (!paneId || persistence) return persistence;
+    const key = `kookie-ui:shell:${name}:${paneId}`;
+    return {
+      load: () => {
+        if (typeof window === 'undefined') return undefined;
+        try {
+          const stored = window.localStorage.getItem(key);
+          return stored ? Number(stored) : undefined;
+        } catch (err) {
+          if (process.env.NODE_ENV !== 'production') console.warn(`Shell.${name}: failed to load persisted size`, err);
+          return undefined;
+        }
+      },
+      save: (value: number) => {
+        if (typeof window === 'undefined') return;
+        try {
+          window.localStorage.setItem(key, String(value));
+        } catch (err) {
+          if (process.env.NODE_ENV !== 'production') console.warn(`Shell.${name}: failed to save persisted size`, err);
+        }
+      },
+    };
+  }, [name, paneId, persistence]);
+
+  // Persisted size, loaded in a layout effect and clamped, so a reload does
+  // not paint the default and then jump. Only where the pane is in the frame:
+  // an overlay keeps its designed size.
+  React.useLayoutEffect(() => {
+    if (!resizable || !adapter?.load || latest.current.overlayingNow()) return undefined;
+    let mounted = true;
+    const apply = (value: number | undefined) => {
+      if (!mounted || typeof value !== 'number' || !Number.isFinite(value)) return;
+      const clamped = clampTo(value, minSize, maxSize);
+      writeSize(clamped, true);
+      latest.current.onResize?.(clamped);
+    };
+    const loaded = adapter.load();
+    if (loaded instanceof Promise) {
+      loaded.then(apply).catch((err) => {
+        if (process.env.NODE_ENV !== 'production') console.warn(`Shell.${name}: failed to load persisted size`, err);
+      });
+    } else {
+      apply(loaded);
+    }
+    return () => {
+      mounted = false;
+    };
+  }, [resizable, adapter, options.overlaying, writeSize, minSize, maxSize, name]);
+
+  const onResize = React.useCallback((value: number) => latest.current.onResize?.(value), []);
+  const onResizeStart = React.useCallback((value: number) => {
+    // A resize makes the size the user's: a new expandedSize no longer moves it.
+    ownedRef.current = true;
+    latest.current.onResizeStart?.(value);
+  }, []);
+  const onResizeEnd = React.useCallback(
+    (value: number) => {
+      latest.current.onResizeEnd?.(value);
+      emitSizeChange(value, { reason: 'resize' });
+      adapter?.save?.(value);
+    },
+    [emitSizeChange, adapter],
+  );
+  const requestCollapse = React.useCallback(() => latest.current.requestCollapse(), []);
+  const requestToggle = React.useCallback(() => latest.current.requestToggle(), []);
+
+  return React.useMemo(
+    () => ({
+      containerRef: elementRef,
+      controls: options.elementId,
+      cssVarName,
+      minSize,
+      maxSize,
+      defaultSize: options.expandedSize,
+      orientation,
+      edge: options.edge,
+      growth: options.growth,
+      onResize,
+      onResizeStart,
+      onResizeEnd,
+      target: name,
+      collapsible: options.collapsible,
+      snapPoints: options.snapPoints,
+      snapTolerance: options.snapTolerance ?? 8,
+      collapseThreshold: options.collapseThreshold,
+      requestCollapse,
+      requestToggle,
+    }),
+    [
+      elementRef,
+      options.elementId,
+      cssVarName,
+      minSize,
+      maxSize,
+      options.expandedSize,
+      orientation,
+      options.edge,
+      options.growth,
+      onResize,
+      onResizeStart,
+      onResizeEnd,
+      name,
+      options.collapsible,
+      options.snapPoints,
+      options.snapTolerance,
+      options.collapseThreshold,
+      requestCollapse,
+      requestToggle,
+    ],
+  );
+}
+
+/** Splits a pane's children into its handles and the rest. */
+export function splitHandles(children: React.ReactNode, handleType: React.ElementType) {
+  const all = React.Children.toArray(children);
+  const handles = all.filter((el) => React.isValidElement(el) && el.type === handleType) as React.ReactElement[];
+  const content = all.filter((el) => !(React.isValidElement(el) && el.type === handleType));
+  return { handles, content };
+}

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

@@ -1,18 +1,26 @@
 import * as React from 'react';
+import type { PaneName } from '../shell.types.js';
 
 export interface PaneResizeContextValue {
-  containerRef: React.RefObject<HTMLDivElement | null>;
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** The pane the handle resizes, for `aria-controls`. */
+  controls: string;
   cssVarName: string;
   minSize: number;
   maxSize: number;
   defaultSize: number;
   orientation: 'vertical' | 'horizontal';
   edge: 'start' | 'end';
-  computeNext: (clientPos: number, startClientPos: number, startSize: number) => number;
+  /**
+   * +1 when moving the pointer toward the end of its axis grows the pane, -1
+   * when it shrinks it. Read once when a drag starts, with the pane's
+   * resolved direction, so no move pays for a style read.
+   */
+  growth: (isRtl: boolean) => 1 | -1;
   onResize?: (size: number) => void;
   onResizeStart?: (size: number) => void;
   onResizeEnd?: (size: number) => void;
-  target: 'left' | 'rail' | 'panel' | 'sidebar' | 'inspector' | 'bottom';
+  target: PaneName;
   collapsible: boolean;
   snapPoints?: number[];
   snapTolerance: number;

package/src/components/_internal/shell-rest.ts

@@ -0,0 +1,45 @@
+import type { Breakpoint, PresentationValue } from '../shell.types.js';
+import type { PaneValue } from './shell-store.js';
+
+type ResponsiveBoolean = boolean | Partial<Record<Breakpoint, boolean>>;
+
+/** `open`/`defaultOpen` as the pane's own value type. */
+export function toPaneValue(value: ResponsiveBoolean | undefined): PaneValue | Partial<Record<Breakpoint, PaneValue>> | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === 'boolean') return value ? 'open' : 'closed';
+  const map: Partial<Record<Breakpoint, PaneValue>> = {};
+  for (const [bp, open] of Object.entries(value) as Array<[Breakpoint, boolean | undefined]>) {
+    if (typeof open === 'boolean') map[bp] = open ? 'open' : 'closed';
+  }
+  return map;
+}
+
+/**
+ * Where an untouched navigation column rests: open in the frame or stacked
+ * over it, closed where it would be an overlay. An overlay is summoned,
+ * never ambient.
+ */
+export const navigationRest = (presentation: PresentationValue): PaneValue => (presentation === 'overlay' ? 'closed' : 'open');
+
+/** Where an untouched detail pane rests: closed. Detail is asked for. */
+export const detailRest = (): PaneValue => 'closed';
+
+/** A pane anchored at the inline start grows as its end edge moves toward the inline end. */
+export const startAnchoredGrowth = (isRtl: boolean): 1 | -1 => (isRtl ? -1 : 1);
+
+/** A pane anchored at the inline end grows as its start edge moves toward the inline start. */
+export const endAnchoredGrowth = (isRtl: boolean): 1 | -1 => (isRtl ? 1 : -1);
+
+/** A pane anchored at the block end grows as its top edge moves up. */
+export const bottomAnchoredGrowth = (): 1 | -1 => -1;
+
+/**
+ * `height` and `resizer` left PaneBaseProps in 0.8.0: no pane ever read them.
+ * A call site written against 0.7 can still pass them, so they are dropped
+ * here rather than reaching the DOM as invalid attributes.
+ */
+export function withoutRemovedPaneProps<T extends object>(props: T): T {
+  if (!('height' in props) && !('resizer' in props)) return props;
+  const { height: _height, resizer: _resizer, ...rest } = props as T & { height?: unknown; resizer?: unknown };
+  return rest as T;
+}