@exegia/corpora-ui 0.19.0 → 0.21.0

package/src/components/blocks/shell/shell-metrics.ts

@@ -0,0 +1,79 @@
+/**
+ * The shell's layout arithmetic, as plain functions over px.
+ *
+ * Nothing here touches React or the DOM. This module IS the contract of who
+ * gets which column, which keeps the rule unit-testable on its own and lets
+ * the shell-fit atoms (`shellFitFitsAtom`, `shellFitPanelWidthAtom`) call it
+ * without restating it: `useShellFit` only supplies the measurements.
+ */
+
+/** The px the shell lays itself out with. Every field is measured from a CSS
+ * variable (see `SHELL_WIDTHS`), never hard-coded, so a consumer's override
+ * flows straight through the rule. */
+export interface ShellMetrics {
+  /** What the left rail occupies right now — its expanded width, its icon
+   * width, or 0 when there is no rail at all (or it is off canvas). */
+  rail: number
+  /** The floor the body refuses to go below. */
+  insetMin: number
+  /** The secondary panel's floor, which is also the width it opens at. */
+  panelMin: number
+  /** The viewport all three columns share. */
+  viewport: number
+  /** px the shell's own frame eats before any column gets a share: its
+   * padding, plus the gap between columns.
+   *
+   * Deliberately absent from `fitsPanel` — that rule is stated against the raw
+   * viewport — but subtracted from the resize ceiling, where ignoring it lets
+   * a full-width drag push the row past the shell by exactly this much. */
+  chrome: number
+}
+
+/** px the shell needs before a secondary panel can exist: the rail as it
+ * stands, plus the body and the panel at their own floors. */
+export function requiredWidth({ rail, insetMin, panelMin }: ShellMetrics) {
+  return rail + insetMin + panelMin
+}
+
+/**
+ * Whether the shell can hold a secondary panel at all. Strictly `<`: a shell
+ * that fits its columns exactly has no room left to give one.
+ *
+ * An unmeasurable shell fails open. A server render, a `display: none` host
+ * or a test environment with no layout engine all report 0, and a panel must
+ * never disappear over a reading the layout could not produce.
+ */
+export function fitsPanel(metrics: ShellMetrics) {
+  if (metrics.viewport <= 0 || metrics.panelMin <= 0) return true
+  return requiredWidth(metrics) < metrics.viewport
+}
+
+/** How wide the secondary panel may be: never under its own floor, never past
+ * the slack the body holds above its floor. `max` never drops below `min`, so
+ * a shell that does not fit reports a degenerate range instead of an inverted
+ * one — `fitsPanel` is what hides the panel, not a negative bound. */
+export function panelBounds(metrics: ShellMetrics) {
+  const { chrome, insetMin, panelMin, rail, viewport } = metrics
+  return {
+    min: panelMin,
+    max: Math.max(panelMin, viewport - chrome - rail - insetMin),
+  }
+}
+
+export function clampPanelWidth(width: number, metrics: ShellMetrics) {
+  const { min, max } = panelBounds(metrics)
+  return Math.min(Math.max(width, min), max)
+}
+
+/** Resizes fire per pointer move and per resize event, most of them landing
+ * on the same numbers — comparing fields keeps those from re-rendering the
+ * whole shell. */
+export function metricsEqual(a: ShellMetrics, b: ShellMetrics) {
+  return (
+    a.rail === b.rail &&
+    a.insetMin === b.insetMin &&
+    a.panelMin === b.panelMin &&
+    a.viewport === b.viewport &&
+    a.chrome === b.chrome
+  )
+}

package/src/components/blocks/shell/type.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react"
+import type { ReactNode, RefObject } from "react"
 
 import {
   type ButtonHTMLAttributes,
@@ -7,6 +7,83 @@ import {
 } from "react"
 import type { HTMLMotionProps } from "motion/react"
 
+import type { ShellMetrics } from "./shell-metrics"
+
+// ---------------------------------------------------------------------------
+// Shell fit — the shell's measurement of itself, kept in Jotai atoms keyed by
+// `shellId` (see `shell-fit-atom.ts`). No atom imports here: this file stays
+// dependency-free so the types can travel without the store.
+// ---------------------------------------------------------------------------
+
+/** The key a shell's fit state is filed under. Pass your own to reach it from
+ * anywhere (`useShellFitState("app-shell")`); leave it out and the provider
+ * generates one that dies with it. */
+export type ShellFitInstanceId = string
+
+/** The range a secondary-panel resize may land in, in px. */
+export interface ShellFitPanelBounds {
+  min: number
+  max: number
+}
+
+/** What the shell measured of itself — readable by id through
+ * `useShellFitState`. */
+export interface ShellFitState {
+  /** The px the shell last measured, or null before its first measurement
+   * (a server render, a host with no layout). */
+  metrics: ShellMetrics | null
+  /** Whether the shell can hold a secondary panel. True while unmeasured, so
+   * a panel never flickers out over a reading that has not happened yet. */
+  fits: boolean
+  /** The secondary panel's width in px, already clamped to `bounds` — null
+   * before the first measurement, where the panel falls back to
+   * `--panel-width`. */
+  panelWidth: number | null
+  /** The range a resize may land in. */
+  bounds: ShellFitPanelBounds
+}
+
+/** Writes only — drive a shell's secondary panel by id through
+ * `useShellFitActions` without re-rendering when it moves. */
+export interface ShellFitActions {
+  /** Resize the secondary panel. Clamped on the way in, so a drag past the
+   * gutter parks at the bound instead of banking travel it has to give back. */
+  resizePanel: (width: number) => void
+  /** Back to the width the shell mounted with — `defaultPanelWidth`, or
+   * `--panel-width` when there was none. */
+  resetPanelWidth: () => void
+}
+
+/** What `useShellFit` hands the provider: the state, the actions and the id
+ * they are filed under. */
+export interface ShellFitController extends ShellFitState, ShellFitActions {
+  shellId: ShellFitInstanceId
+}
+
+export interface UseShellFitOptions {
+  /** File the fit under this id so it can be read elsewhere and outlive the
+   * shell. Generated (and dropped on unmount) when omitted. */
+  shellId?: ShellFitInstanceId
+  /** The element the shell's CSS variables live on (the provider wrapper). */
+  hostRef: RefObject<HTMLElement | null>
+  /** Whether the left rail is expanded right now — a render input, so a fold
+   * counts the moment React commits it rather than a frame later when the
+   * width animation has moved. */
+  railOpen: boolean
+  /** The width the secondary panel opens at, in px, instead of
+   * `--panel-width`. Read once, on mount. */
+  defaultPanelWidth?: number
+  /** Fired whenever a measurement lands on "no room": the shell uses it to
+   * retire the panel's open state instead of parking it. */
+  onUnfit?: () => void
+}
+
+/** @internal What an instance starts from, restored by `resetShellPanelWidthAtom`. */
+export interface ShellFitSeed {
+  /** The requested panel width at mount — null for `--panel-width`. */
+  panelWidth: number | null
+}
+
 export interface ShellAction {
   id: string
   label: string
@@ -60,14 +137,24 @@ export type ShellPanelControlProps = Pick<
   | "openMobile"
   | "defaultOpenMobile"
   | "onOpenMobileChange"
+  | "shellId"
+  | "defaultPanelWidth"
 >
 
 export interface UseShellPanelsOptions {
+  /** The id the shell's fit state is filed under. Name it to read the same
+   * shell from elsewhere (`useShellFitState("app-shell")`) and to keep a
+   * dragged panel width across a route change; otherwise the hook generates
+   * one that dies with it. */
+  shellId?: ShellFitInstanceId
   /** Initial desktop open state per side, merged over
    * `{ left: true, right: false }`. */
   defaultOpen?: AnimatedSidebarProviderProps["defaultOpen"]
   /** Initial mobile overlay state per side — every side starts closed. */
   defaultOpenMobile?: AnimatedSidebarProviderProps["defaultOpenMobile"]
+  /** The width the secondary panel opens at, in px, instead of
+   * `--panel-width`. */
+  defaultPanelWidth?: number
   /** Panel change event returning both the next open state and the side of
    * the panel the change comes from. Mobile overlay changes report the same
    * side as their desktop counterpart. */
@@ -75,14 +162,32 @@ export interface UseShellPanelsOptions {
 }
 
 export interface ShellPanelControls {
+  /** The id the shell's fit state is filed under — hand it to
+   * `useShellFitState` / `useShellFitActions` anywhere below `ExegiaProvider`. */
+  shellId: ShellFitInstanceId
+  /** The viewport cannot hold the secondary panel beside the rail and the
+   * body at their floors, so the shell has dropped the right panel and its
+   * trigger — UI outside the shell should stand down with them. Read straight
+   * out of the shell's fit atoms; it is only ever `true` once the shell is
+   * mounted and measured. */
+  isNarrow: boolean
+  /** The secondary panel's current width in px, or null until the shell has
+   * measured itself (the panel then sits at `--panel-width`). */
+  panelWidth: number | null
+  /** Resize the secondary panel from outside the shell — clamped to the room
+   * the shell has. */
+  resizePanel: (width: number) => void
   /** Live desktop open state, keyed by side. */
   open: Record<SidebarSide, boolean>
   /** Live mobile overlay state, keyed by side. */
   openMobile: Record<SidebarSide, boolean>
+  /** Refuses to OPEN the right panel while `isNarrow` — there is nothing on
+   * screen to open. Closing it always goes through. */
   setOpen: (open: boolean, side: SidebarSide) => void
   setOpenMobile: (open: boolean, side: SidebarSide) => void
   /** Desktop-only convenience — the in-shell triggers already pick the
-   * mobile state themselves when the viewport is narrow. */
+   * mobile state themselves when the viewport is narrow. Carries the same
+   * `isNarrow` refusal as `setOpen`. */
   toggle: (side: SidebarSide) => void
   /** Spread onto ShellLayout (or AnimatedPanelProvider directly). */
   providerProps: ShellPanelControlProps
@@ -98,7 +203,6 @@ export interface ShellLayoutProps extends ShellPanelControlProps {
   variant?: "web" | "desktop"
 }
 
-
 export type SidebarSide = "left" | "right"
 /** Open flags keyed by the side. Sides left out stay uncontrolled / at their
  * default — there is no per-side prop, the record IS the API. */
@@ -108,6 +212,10 @@ export type SidebarCollapsible = "offcanvas" | "icon" | "none"
 
 export interface AnimatedSidebarContextValue {
   isMobile: boolean
+  /** What the shell measured of itself: whether it can hold a secondary panel
+   * at all, how wide that panel is, and the range a resize may land in. The
+   * right panel and its trigger stand down when `fit.fits` is false. */
+  fit: ShellFitController
   layoutId: string
   /** Desktop open state, keyed by side. */
   open: Record<SidebarSide, boolean>
@@ -122,6 +230,14 @@ export interface AnimatedSidebarContextValue {
 }
 
 export interface AnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElement> {
+  /** The id this shell's fit state (whether a secondary panel fits, how wide
+   * it is) is filed under in the store. Name it to read or drive the shell
+   * from elsewhere and to keep a dragged width across a route change; omit it
+   * and the provider generates one that is dropped on unmount. */
+  shellId?: ShellFitInstanceId
+  /** The width the secondary panel opens at, in px, instead of
+   * `--panel-width`. Read once, on mount. */
+  defaultPanelWidth?: number
   /** Controlled desktop open state, keyed by the side. A side left undefined
    * stays uncontrolled. */
   open?: SidebarOpenState
@@ -133,13 +249,24 @@ export interface AnimatedSidebarProviderProps extends HTMLAttributes<HTMLDivElem
   /** Initial mobile overlay state — every side starts closed. */
   defaultOpenMobile?: SidebarOpenState
   onOpenMobileChange?: (open: boolean, side: SidebarSide) => void
+  /** Fires when the shell crosses the width a secondary panel needs (rail +
+   * body + panel at their floors). An imperative escape hatch for a consumer
+   * that mounts the provider on its own; anything under `ExegiaProvider` can
+   * subscribe by id instead with `useShellFitState(shellId).fits`. */
+  onNarrowChange?: (isNarrow: boolean) => void
   style?: SidebarProviderStyle
 }
 
 export type SidebarProviderStyle = CSSProperties & {
+  /** Left rail, expanded. */
   "--sidebar-width"?: string
+  /** Left rail, folded to icons. */
   "--sidebar-width-icon"?: string
   "--sidebar-width-mobile"?: string
+  /** The secondary panel's floor, and the width it opens at. */
+  "--panel-width"?: string
+  /** The body's floor — the secondary panel may never squeeze it past this. */
+  "--inset-min-width"?: string
 }
 
 export type AnimatedSidebarInsetProps = HTMLMotionProps<"main">

package/src/components/blocks/shell/use-shell-fit-state.ts

@@ -0,0 +1,49 @@
+"use client"
+
+import { useMemo } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+
+import {
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
+import type { ShellFitActions, ShellFitInstanceId, ShellFitState } from "./type"
+
+/**
+ * Read the fit of the shell registered under `shellId` from anywhere below
+ * `ExegiaProvider` — no controller, no props, no provider of its own.
+ *
+ * ```tsx
+ * const { fits, panelWidth } = useShellFitState("app-shell")
+ * ```
+ *
+ * This returns the whole state object, so the caller re-renders on every
+ * measurement. A component that reads one field should subscribe to that
+ * field's atom instead: `useAtomValue(shellFitFitsAtom("app-shell"))`.
+ */
+export function useShellFitState(shellId: ShellFitInstanceId): ShellFitState {
+  return useAtomValue(shellFitStateAtom(shellId))
+}
+
+/**
+ * Drive the secondary panel of the shell registered under `shellId` from
+ * anywhere. Writes only — the caller never re-renders when the shell moves,
+ * so this is what a command palette or a keyboard shortcut should reach for.
+ *
+ * ```tsx
+ * const shell = useShellFitActions("app-shell")
+ * <Button onClick={() => shell.resizePanel(480)}>Wide inspector</Button>
+ * ```
+ */
+export function useShellFitActions(
+  shellId: ShellFitInstanceId
+): ShellFitActions {
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+  const resetPanelWidth = useSetAtom(resetShellPanelWidthAtom(shellId))
+
+  return useMemo(
+    () => ({ resizePanel, resetPanelWidth }),
+    [resizePanel, resetPanelWidth]
+  )
+}

package/src/components/blocks/shell/use-shell-fit.ts

@@ -0,0 +1,135 @@
+"use client"
+
+import { useEffect, useId, useMemo, useRef, useState } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
+import { useIsomorphicLayoutEffect } from "motion/react"
+
+import {
+  measureShellFitAtom,
+  mountShellFitAtom,
+  removeShellFitInstance,
+  resetShellPanelWidthAtom,
+  resizeShellPanelAtom,
+  shellFitStateAtom,
+} from "./shell-fit-atom"
+import { fitsPanel, type ShellMetrics } from "./shell-metrics"
+import type {
+  ShellFitController,
+  ShellFitSeed,
+  UseShellFitOptions,
+} from "./type"
+import { resolveLength } from "./utils"
+
+/** Read the shell's columns out of the DOM. The widths come from CSS
+ * variables; the rail's share comes from its own state, not its box, so a
+ * fold counts the moment React commits it rather than a frame later when the
+ * width animation has moved. */
+function readMetrics(host: HTMLElement, railOpen: boolean): ShellMetrics {
+  // Whether a shell has a rail at all is the caller's composition, so it is
+  // read off the DOM rather than tracked in state.
+  const rail = host.querySelector<HTMLElement>(
+    '[data-slot="sidebar"][data-side="left"]'
+  )
+  const collapsible = rail?.dataset.collapsible
+
+  const frame = getComputedStyle(host)
+  const gap = Number.parseFloat(frame.columnGap) || 0
+
+  return {
+    rail: !rail
+      ? 0
+      : railOpen || collapsible === "none"
+        ? resolveLength(host, "var(--sidebar-width)")
+        : collapsible === "offcanvas"
+          ? 0
+          : resolveLength(host, "var(--sidebar-width-icon)"),
+    insetMin: resolveLength(host, "var(--inset-min-width)"),
+    panelMin: resolveLength(host, "var(--panel-width)"),
+    viewport: window.innerWidth,
+    chrome:
+      (Number.parseFloat(frame.paddingLeft) || 0) +
+      (Number.parseFloat(frame.paddingRight) || 0) +
+      gap * Math.max(0, host.children.length - 1),
+  }
+}
+
+/**
+ * Measures the shell and decides what the secondary panel may do: whether it
+ * exists at all, and how wide it may be dragged.
+ *
+ * The three things that move the answer are all observed here — the viewport
+ * (`resize`), the rail's fold (`railOpen`, a render input) and the user's own
+ * drag (`resizePanel`) — so no caller has to re-derive it. The measurement is
+ * the only thing this hook keeps to itself: the numbers land in the shell-fit
+ * atoms keyed by `shellId`, so anything under `ExegiaProvider` can read the
+ * verdict (`useShellFitState`) or move the panel (`useShellFitActions`)
+ * without holding this controller.
+ */
+export function useShellFit({
+  shellId: explicitId,
+  hostRef,
+  railOpen,
+  defaultPanelWidth,
+  onUnfit,
+}: UseShellFitOptions): ShellFitController {
+  // A generated key isolates unnamed shells from each other; an explicit
+  // `shellId` is the app's handle on this one.
+  const generatedId = useId()
+  const shellId = explicitId ?? generatedId
+
+  // Read once: `defaultPanelWidth` describes the mount, not every render.
+  const [seed] = useState<ShellFitSeed>(() => ({
+    panelWidth: defaultPanelWidth ?? null,
+  }))
+
+  const mount = useSetAtom(mountShellFitAtom(shellId))
+  const measure = useSetAtom(measureShellFitAtom(shellId))
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+  const resetPanelWidth = useSetAtom(resetShellPanelWidthAtom(shellId))
+
+  // Before paint, and before the first measurement below, so a seeded width
+  // is in the store by the time the panel first reads its width.
+  useIsomorphicLayoutEffect(() => {
+    mount(seed)
+  }, [mount, seed])
+
+  // The listener below is bound once per fold, so the callback rides a ref
+  // rather than rebinding it whenever a consumer passes a fresh arrow.
+  const onUnfitRef = useRef(onUnfit)
+  useIsomorphicLayoutEffect(() => {
+    onUnfitRef.current = onUnfit
+  })
+
+  useIsomorphicLayoutEffect(() => {
+    const host = hostRef.current
+    if (!host) return
+
+    const takeMeasurement = () => {
+      const next = readMetrics(host, railOpen)
+      measure(next)
+      if (!fitsPanel(next)) onUnfitRef.current?.()
+    }
+
+    // Measured before paint so a shell that cannot hold the panel never
+    // flashes one, and re-measured on every fold because the rail's column is
+    // part of the room the panel needs.
+    takeMeasurement()
+    window.addEventListener("resize", takeMeasurement)
+    return () => window.removeEventListener("resize", takeMeasurement)
+  }, [hostRef, railOpen, measure])
+
+  // A shell the hook keyed is scrap once its component goes. An explicit
+  // `shellId` is the app's key and outlives the mount — that is what lets a
+  // dragged width survive a route change.
+  useEffect(() => {
+    if (explicitId !== undefined) return
+    return () => removeShellFitInstance(shellId)
+  }, [shellId, explicitId])
+
+  const state = useAtomValue(shellFitStateAtom(shellId))
+
+  return useMemo<ShellFitController>(
+    () => ({ shellId, ...state, resizePanel, resetPanelWidth }),
+    [shellId, state, resizePanel, resetPanelWidth]
+  )
+}

package/src/components/blocks/shell/use-shell-panels.ts

@@ -1,7 +1,14 @@
 "use client"
 
-import { useCallback, useMemo, useState } from "react"
+import { useCallback, useEffect, useId, useMemo, useState } from "react"
+import { useAtomValue, useSetAtom } from "jotai"
 
+import {
+  removeShellFitInstance,
+  resizeShellPanelAtom,
+  shellFitFitsAtom,
+  shellFitPanelWidthAtom,
+} from "./shell-fit-atom"
 import type {
   ShellPanelControlProps,
   ShellPanelControls,
@@ -15,12 +22,36 @@ import type {
  * callback. Spread the returned `providerProps` onto ShellLayout; the
  * setters and `toggle` are for UI that lives outside the shell (title-bar
  * buttons, command palette, shortcuts).
+ *
+ * The way back down is the store: `providerProps` carries a `shellId`, the
+ * shell files its measurement under it, and this hook reads `isNarrow` and
+ * `panelWidth` straight out of those atoms — so outside UI stands down with
+ * the panel instead of measuring `--sidebar-width` a second time. Name the
+ * `shellId` and any component below `ExegiaProvider` can do the same with
+ * `useShellFitState(shellId)`.
+ *
+ * Call it under the same `ExegiaProvider` as the shell it drives (or under
+ * none at all, on both sides): mounted above the provider it would read
+ * Jotai's default store while the shell writes to the provider's.
  */
 export function useShellPanels({
+  shellId: explicitId,
   defaultOpen,
   defaultOpenMobile,
+  defaultPanelWidth,
   onPanelChange,
 }: UseShellPanelsOptions = {}): ShellPanelControls {
+  // The hook, not the provider, keys the shell: it renders above the provider
+  // and has to read the same atoms the provider writes. Whoever generates the
+  // key drops it — the provider treats a passed-in id as the app's and leaves
+  // it alone on unmount.
+  const generatedId = useId()
+  const shellId = explicitId ?? generatedId
+  useEffect(() => {
+    if (explicitId !== undefined) return
+    return () => removeShellFitInstance(shellId)
+  }, [shellId, explicitId])
+
   const [open, setOpenState] = useState<Record<SidebarSide, boolean>>(() => ({
     left: defaultOpen?.left ?? true,
     right: defaultOpen?.right ?? false,
@@ -32,24 +63,40 @@ export function useShellPanels({
     right: defaultOpenMobile?.right ?? false,
   }))
 
+  // Reads false until the shell has measured itself — an unmeasured shell
+  // fails open, so nothing out here stands down over a reading that has not
+  // happened yet.
+  const fits = useAtomValue(shellFitFitsAtom(shellId))
+  const isNarrow = !fits
+  const panelWidth = useAtomValue(shellFitPanelWidthAtom(shellId))
+  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
+
+  // The shell drops the right panel when the viewport cannot hold it, so
+  // opening it from out here would only surface later as a panel nobody
+  // asked for. Closing always goes through — that is how state left over
+  // from a wider viewport clears.
   const setOpen = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && isNarrow) return
+
       setOpenState((prev) =>
         prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
       )
       onPanelChange?.(nextOpen, side)
     },
-    [onPanelChange]
+    [isNarrow, onPanelChange]
   )
 
   const setOpenMobile = useCallback(
     (nextOpen: boolean, side: SidebarSide) => {
+      if (nextOpen && side === "right" && isNarrow) return
+
       setOpenMobileState((prev) =>
         prev[side] === nextOpen ? prev : { ...prev, [side]: nextOpen }
       )
       onPanelChange?.(nextOpen, side)
     },
-    [onPanelChange]
+    [isNarrow, onPanelChange]
   )
 
   const toggle = useCallback(
@@ -59,15 +106,21 @@ export function useShellPanels({
 
   const providerProps = useMemo<ShellPanelControlProps>(
     () => ({
+      shellId,
+      defaultPanelWidth,
       open,
       onOpenChange: setOpen,
       openMobile,
       onOpenMobileChange: setOpenMobile,
     }),
-    [open, openMobile, setOpen, setOpenMobile]
+    [shellId, defaultPanelWidth, open, openMobile, setOpen, setOpenMobile]
   )
 
   return {
+    shellId,
+    isNarrow,
+    panelWidth,
+    resizePanel,
     open,
     openMobile,
     setOpen,

package/src/components/blocks/shell/utils.ts

@@ -92,6 +92,49 @@ export const FOCUSABLE_SELECTOR = [
 export const MOBILE_QUERY = "(max-width: 767px)"
 export const SIDEBAR_KEYBOARD_SHORTCUT = "b"
 
+/**
+ * The shell's layout contract, in px. Every entry lands on the provider's
+ * wrapper as a CSS variable, so a consumer overrides a column by restyling it
+ * rather than by passing a prop:
+ *
+ * | variable               | column                                    |
+ * | ---------------------- | ----------------------------------------- |
+ * | `--sidebar-width`      | left rail, expanded                       |
+ * | `--sidebar-width-icon` | left rail, folded to icons                |
+ * | `--panel-width`        | secondary panel: its floor AND its default |
+ * | `--inset-min-width`    | the body's floor                          |
+ *
+ * These are only the defaults. Every measurement resolves the live variable,
+ * so an override wins over the value written here.
+ */
+export const SHELL_WIDTHS = {
+  "--sidebar-width": "256px",
+  "--sidebar-width-icon": "56px",
+  "--sidebar-width-mobile": "18rem",
+  "--panel-width": "320px",
+  "--inset-min-width": "360px",
+} as const
+
+/** The expanded width of a panel docked to `side`: the secondary panel opens
+ * at `--panel-width`, the primary rail at `--sidebar-width`. */
+export function expandedWidthVar(side: "left" | "right") {
+  return side === "right" ? "var(--panel-width)" : "var(--sidebar-width)"
+}
+
+/** Resolve a CSS length — `var()` included — to px inside `host`'s cascade.
+ * Custom properties inherit, so a throwaway probe mounted in `host` reads the
+ * very `--sidebar-width` the shell lays out with, including a value a
+ * consumer overrode on the provider. Returns 0 when `host` has no layout
+ * (server render, `display: none`), so callers must fail open on 0 rather
+ * than treat it as a real measurement. */
+export function resolveLength(host: HTMLElement, value: string) {
+  const probe = document.createElement("div")
+  probe.style.cssText = `position:absolute;visibility:hidden;pointer-events:none;width:${value}`
+  host.appendChild(probe)
+  const px = probe.getBoundingClientRect().width
+  probe.remove()
+  return px
+}
 
 export const AnimatedSidebarContext =
   createContext<AnimatedSidebarContextValue | null>(null)
@@ -131,13 +174,10 @@ export function useIsMobile() {
   )
 }
 
-
 export function useAnimatedSidebarPanel() {
   const context = useContext(AnimatedSidebarPanelContext)
   if (!context) {
-    throw new Error(
-      "Animated Sidebar parts must be used inside AnimatedPanel."
-    )
+    throw new Error("Animated Sidebar parts must be used inside AnimatedPanel.")
   }
   return context
 }