@exegia/corpora-ui 3.0.0 → 4.0.0

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

@@ -1,361 +0,0 @@
-import type { ReactNode, RefObject } from "react"
-
-import {
-  type ButtonHTMLAttributes,
-  type CSSProperties,
-  type HTMLAttributes,
-} from "react"
-import type { HTMLMotionProps } from "motion/react"
-
-import type { IShellMetrics, IShellSidebarFit } 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 TShellFitInstanceId = string
-
-/** The range a secondary-panel resize may land in, in px. */
-export interface IShellFitPanelBounds {
-  min: number
-  max: number
-}
-
-/** What the shell measured of itself — readable by id through
- * `useShellFitState`. */
-export interface IShellFitState {
-  /** Actual rail layout after applying container constraints. */
-  sidebar: IShellSidebarFit | null
-  /** The px the shell last measured, or null before its first measurement
-   * (a server render, a host with no layout). */
-  metrics: IShellMetrics | 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: IShellFitPanelBounds
-}
-
-/** Writes only — drive a shell's secondary panel by id through
- * `useShellFitActions` without re-rendering when it moves. */
-export interface IShellFitActions {
-  /** 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 IShellFitController extends IShellFitState, IShellFitActions {
-  defaultPanelWidth: number | null
-  shellId: TShellFitInstanceId
-}
-
-export interface IUseShellFitOptions {
-  /** File the fit under this id so it can be read elsewhere and outlive the
-   * shell. Generated (and dropped on unmount) when omitted. */
-  shellId?: TShellFitInstanceId
-  /** 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 IShellFitSeed {
-  /** The requested panel width at mount — null for `--panel-width`. */
-  panelWidth: number | null
-}
-
-export interface IShellAction {
-  id: string
-  label: string
-  icon: ReactNode
-  badge?: ReactNode
-  onSelect?: () => void
-}
-
-export interface IShellWorkspace {
-  name: string
-  logo?: ReactNode
-  meta?: ReactNode
-}
-
-export interface IPanel {
-  id: string
-  name: string
-  component: ReactNode
-  /** Replaces the default icon inside the panel's header trigger. The shell
-   * keeps the trigger button itself (toggle wiring, aria-label) — this only
-   * swaps what renders inside it. */
-  trigger?: ReactNode
-  open: boolean
-  defaultOpen?: boolean
-  side: "left" | "bottom" | "right" | "sidebar"
-}
-
-/** The side a panel docks to, as a value union (`IPanel["side"]`).
- * `Pick<IPanel, "side">` would be the object type `{ side: ... }`, which can
- * neither key a Record nor travel as a plain callback argument. */
-export type TPanelSide = IPanel["side"]
-
-/** Panel content keyed by the side it docks to. `Side` narrows the map to
- * the sides a surface actually renders (the shell renders left and right).
- * Entries are optional — a shell with no bottom dock simply has no `bottom`
- * key. Where an entry's own `side` field disagrees with its key, the key
- * wins. */
-export type TPanelMap<Side extends TPanelSide = TPanelSide> = Partial<
-  Record<Side, IPanel>
->
-
-/** Dynamic panel content keyed by side — filled by
- * `useShellPanels().openPanel(side, component)` and read by ShellLayout,
- * where a side's entry wins over the static `panels` map's `component`. */
-export type TSidebarComponentMap = Partial<Record<TSidebarSide, ReactNode>>
-
-/** The open/close surface of the shell's panels, lifted straight from
- * AnimatedPanelProvider — every prop is keyed by side, there are no
- * explicit per-side props. `useShellPanels` produces the controlled subset
- * of these as `providerProps`. */
-export type TShellPanelControlProps = Pick<
-  IAnimatedSidebarProviderProps,
-  | "open"
-  | "defaultOpen"
-  | "onOpenChange"
-  | "openMobile"
-  | "defaultOpenMobile"
-  | "onOpenMobileChange"
-  | "shellId"
-  | "defaultPanelWidth"
-  | "panelComponents"
->
-
-export interface IUseShellPanelsOptions {
-  /** 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?: TShellFitInstanceId
-  /** Initial desktop open state per side, merged over
-   * `{ left: true, right: false }`. */
-  defaultOpen?: IAnimatedSidebarProviderProps["defaultOpen"]
-  /** Initial mobile overlay state per side — every side starts closed. */
-  defaultOpenMobile?: IAnimatedSidebarProviderProps["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. */
-  onPanelChange?: (open: boolean, side: TPanelSide) => void
-}
-
-export interface IShellPanelControls {
-  /** Rendered rail width and whether it can expand in the current container. */
-  sidebar: IShellSidebarFit | null
-  sidebarWidth: number | null
-  resizeSidebar: (width: number) => void
-  /** The id the shell's fit state is filed under — hand it to
-   * `useShellFitState` / `useShellFitActions` anywhere below `ExegiaProvider`. */
-  shellId: TShellFitInstanceId
-  /** 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
-  /** Requested open state. `sidebar` reports the responsive rail layout. */
-  open: Record<TSidebarSide, boolean>
-  /** Live mobile overlay state, keyed by side. */
-  openMobile: Record<TSidebarSide, 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: TSidebarSide) => void
-  setOpenMobile: (open: boolean, side: TSidebarSide) => void
-  /** Desktop-only convenience — the in-shell triggers already pick the
-   * mobile state themselves when the viewport is narrow. Carries the same
-   * `isNarrow` refusal as `setOpen`. */
-  toggle: (side: TSidebarSide) => void
-  /** Open a side's panel and, when given, swap in the content it shows.
-   * The component travels through `providerProps.panelComponents` into
-   * ShellLayout, where it wins over the static `panels` entry for that
-   * side, and sticks until the next `openPanel(side, component)` replaces
-   * it — closing the panel leaves it in place for the exit animation and
-   * the next open. Carries the same `isNarrow` refusal as `setOpen`. */
-  openPanel: (side: TSidebarSide, component?: ReactNode) => void
-  /** Spread onto ShellLayout (or AnimatedPanelProvider directly). */
-  providerProps: TShellPanelControlProps
-}
-
-export interface IShellLayoutProps extends TShellPanelControlProps {
-  children?: ReactNode
-  /** Content for the shell's panels, keyed by the side. The shell renders
-   * the `left` rail and the `right` drawer; other sides are reserved. */
-  panels?: TPanelMap
-  header?: ReactNode
-  /** Actions pinned to the header's right edge, rendered just before the
-   * right panel's trigger. The cluster hugs the trailing edge no matter
-   * which of `header` / the left rail / the right panel are present. */
-  trailing?: ReactNode
-  className?: string
-  variant?: "web" | "desktop"
-}
-
-export type TSidebarSide = "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. */
-export type TSidebarOpenState = Partial<Record<TSidebarSide, boolean>>
-export type TSidebarVariant = "sidebar" | "floating" | "inset"
-export type TSidebarCollapsible = "offcanvas" | "icon" | "none"
-
-export interface IAnimatedSidebarContextValue {
-  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: IShellFitController
-  layoutId: string
-  /** Desktop open state, keyed by side. */
-  open: Record<TSidebarSide, boolean>
-  /** Mobile overlay open state, keyed by side. */
-  openMobile: Record<TSidebarSide, boolean>
-  reduce: boolean
-  setOpen: (open: boolean, side: TSidebarSide) => void
-  setOpenMobile: (open: boolean, side: TSidebarSide) => void
-  /** Toggle the docked panel when the container can accommodate it. */
-  toggleSidebar: (side: TSidebarSide) => void
-  triggerRefs: Record<TSidebarSide, React.RefObject<HTMLButtonElement | null>>
-}
-
-export interface IAnimatedSidebarProviderProps 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?: TShellFitInstanceId
-  /** 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?: TSidebarOpenState
-  /** Initial desktop open state, merged over `{ left: true, right: false }`. */
-  defaultOpen?: TSidebarOpenState
-  onOpenChange?: (open: boolean, side: TSidebarSide) => void
-  /** Controlled mobile overlay state, keyed by side. */
-  openMobile?: TSidebarOpenState
-  /** Initial mobile overlay state — every side starts closed. */
-  defaultOpenMobile?: TSidebarOpenState
-  onOpenMobileChange?: (open: boolean, side: TSidebarSide) => void
-  /** Content pushed into a side's panel by `useShellPanels().openPanel`. It
-   * rides along in `providerProps` so the record can be spread on either
-   * surface: ShellLayout renders it in that side's panel; the bare provider
-   * renders no panels, so it only swallows the prop to keep it off the DOM. */
-  panelComponents?: TSidebarComponentMap
-  /** 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?: TSidebarProviderStyle
-}
-
-export type TSidebarProviderStyle = CSSProperties & {
-  /** Left rail, expanded. */
-  "--sidebar-width"?: string
-  /** Minimum expanded rail width before it folds to icons. Default 180px. */
-  "--sidebar-min-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 TAnimatedSidebarInsetProps = HTMLMotionProps<"main">
-
-export interface IAnimatedSidebarTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  side?: TSidebarSide
-}
-
-export interface IAnimatedSidebarPanelContextValue {
-  collapsed: boolean
-  collapsible: TSidebarCollapsible
-  side: TSidebarSide
-}
-
-export interface IAnimatedSidebarProps extends Omit<
-  HTMLMotionProps<"aside">,
-  "children"
-> {
-  children?: ReactNode
-  side?: TSidebarSide
-  variant?: TSidebarVariant
-  collapsible?: TSidebarCollapsible
-  ariaLabel?: string
-  panelClassName?: string
-}
-
-export interface IAnimatedSidebarMenuSubProps extends Omit<
-  HTMLMotionProps<"ul">,
-  "children"
-> {
-  open: boolean
-  children?: ReactNode
-}
-
-export interface IAnimatedSidebarMenuSubButtonProps {
-  children: ReactNode
-  icon?: ReactNode
-  href?: string
-  isActive?: boolean
-  disabled?: boolean
-  closeOnSelect?: boolean
-  target?: "_blank" | "_self" | "_parent" | "_top"
-  rel?: string
-  onSelect?: () => void
-  className?: string
-}
-
-export interface IAnimatedSidebarMenuButtonProps {
-  children: ReactNode
-  icon?: ReactNode
-  badge?: ReactNode
-  href?: string
-  isActive?: boolean
-  ariaExpanded?: boolean
-  disabled?: boolean
-  closeOnSelect?: boolean
-  target?: "_blank" | "_self" | "_parent" | "_top"
-  rel?: string
-  onSelect?: () => void
-  className?: string
-}

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

@@ -1,49 +0,0 @@
-"use client"
-
-import { useMemo } from "react"
-import { useAtomValueRawSync, useSetAtom } from "jotai"
-
-import {
-  resetShellPanelWidthAtom,
-  resizeShellPanelAtom,
-  shellFitStateAtom,
-} from "./shell-fit-atom"
-import type { IShellFitActions, TShellFitInstanceId, IShellFitState } 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: TShellFitInstanceId): IShellFitState {
-  return useAtomValueRawSync(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: TShellFitInstanceId
-): IShellFitActions {
-  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

@@ -1,153 +0,0 @@
-"use client"
-
-import { useEffect, useId, useMemo, useRef, useState } from "react"
-import { useAtomValueRawSync, useSetAtom } from "jotai"
-import { useIsomorphicLayoutEffect } from "motion/react"
-
-import {
-  measureShellFitAtom,
-  mountShellFitAtom,
-  removeShellFitInstance,
-  resetShellPanelWidthAtom,
-  resizeShellPanelAtom,
-  shellFitStateAtom,
-} from "./shell-fit-atom"
-import { fitsPanel, fitSidebar, type IShellMetrics } from "./shell-metrics"
-import type {
-  IShellFitController,
-  IShellFitSeed,
-  IUseShellFitOptions,
-} from "./type"
-import { shellPanelAtoms } from "./shell-panel-atom"
-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): IShellMetrics {
-  // 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 frame = getComputedStyle(host)
-  const gap = Number.parseFloat(frame.columnGap) || 0
-  const padding =
-    (Number.parseFloat(frame.paddingLeft) || 0) +
-    (Number.parseFloat(frame.paddingRight) || 0)
-  const width = host.clientWidth || host.getBoundingClientRect().width
-  const insetMin = resolveLength(host, "var(--inset-min-width)")
-  const sidebar = fitSidebar({
-    width,
-    padding,
-    gap,
-    insetMin,
-    expanded: resolveLength(host, "var(--sidebar-width)") || 256,
-    icon: resolveLength(host, "var(--sidebar-width-icon)") || 56,
-    minimum: resolveLength(host, "var(--sidebar-min-width)") || 180,
-    open: railOpen,
-    collapsible: rail?.dataset.collapsible ?? "icon",
-    present: Boolean(rail),
-  })
-  return {
-    rail: sidebar.width,
-    sidebar,
-    insetMin,
-    panelMin: resolveLength(host, "var(--panel-width)"),
-    viewport: width,
-    // Measure the space a prospective inspector needs, even while absent.
-    chrome: padding + gap * (sidebar.width > 0 ? 2 : 1),
-  }
-}
-
-/**
- * Measures the shell and decides what the secondary panel may do: whether it
- * exists at all, and how wide it may be dragged.
- *
- * Container resizing, rail folding, and user resizing are observed here,
- * so embedded shells obey the same bounds as full-page layouts. 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,
-}: IUseShellFitOptions): IShellFitController {
-  // 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
-  const railWidth = useAtomValueRawSync(shellPanelAtoms(shellId).railWidth)
-
-  // Read once: `defaultPanelWidth` describes the mount, not every render.
-  const [seed] = useState<IShellFitSeed>(() => ({
-    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?.()
-    }
-
-    // Observe the host, including changes from a split view or surrounding
-    // navigation that never trigger a window resize.
-    takeMeasurement()
-    const observer = new ResizeObserver(takeMeasurement)
-    observer.observe(host)
-    window.addEventListener("resize", takeMeasurement)
-    return () => {
-      observer.disconnect()
-      window.removeEventListener("resize", takeMeasurement)
-    }
-  }, [hostRef, railOpen, railWidth, 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 = useAtomValueRawSync(shellFitStateAtom(shellId))
-
-  return useMemo<IShellFitController>(
-    () => ({
-      shellId,
-      ...state,
-      defaultPanelWidth: seed.panelWidth,
-      resizePanel,
-      resetPanelWidth,
-    }),
-    [shellId, state, seed.panelWidth, resizePanel, resetPanelWidth]
-  )
-}

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

@@ -1,126 +0,0 @@
-"use client"
-
-import { useCallback, useEffect, useId, useMemo } from "react"
-import type { ReactNode } from "react"
-import { shellPanelAtoms } from "./shell-panel-atom"
-import { useAtomValueRawSync, useSetAtom } from "jotai"
-
-import {
-  removeShellFitInstance,
-  resizeShellPanelAtom,
-  shellFitFitsAtom,
-  shellFitStateAtom,
-  shellFitPanelWidthAtom,
-} from "./shell-fit-atom"
-import type {
-  TShellPanelControlProps,
-  IShellPanelControls,
-  TSidebarSide,
-  IUseShellPanelsOptions,
-} from "./type"
-
-/**
- * Owns the open/close state of the shell's panels, keyed by side, and
- * reports every change through a single `onPanelChange(open, side)`
- * 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,
-}: IUseShellPanelsOptions = {}): IShellPanelControls {
-  // 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 atoms = shellPanelAtoms(shellId)
-  const sidebarWidth = useAtomValueRawSync(atoms.railWidth)
-  const resizeSidebar = useSetAtom(atoms.resizeSidebar)
-  const open = useAtomValueRawSync(atoms.open)
-  const openMobile = useAtomValueRawSync(atoms.mobile)
-  const setOpen = useSetAtom(atoms.setOpen)
-  const setOpenMobile = useSetAtom(atoms.setOpenMobile)
-  const toggle = useSetAtom(atoms.toggle)
-  const panelComponents = useAtomValueRawSync(atoms.components)
-  const setPanelComponents = useSetAtom(atoms.components)
-
-  // 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 = useAtomValueRawSync(shellFitFitsAtom(shellId))
-  const isNarrow = !fits
-  const { sidebar } = useAtomValueRawSync(shellFitStateAtom(shellId))
-  const panelWidth = useAtomValueRawSync(shellFitPanelWidthAtom(shellId))
-  const resizePanel = useSetAtom(resizeShellPanelAtom(shellId))
-
-  const openPanel = useCallback(
-    (side: TSidebarSide, component?: ReactNode) => {
-      if (component !== undefined) {
-        setPanelComponents((prev) =>
-          prev[side] === component ? prev : { ...prev, [side]: component }
-        )
-      }
-      setOpen(true, side)
-    },
-    [setOpen, setPanelComponents]
-  )
-
-  const providerProps = useMemo<TShellPanelControlProps>(
-    () => ({
-      shellId,
-      defaultPanelWidth,
-      defaultOpen,
-      defaultOpenMobile,
-      onOpenChange: onPanelChange,
-      onOpenMobileChange: onPanelChange,
-      panelComponents,
-    }),
-    [
-      shellId,
-      defaultPanelWidth,
-      defaultOpen,
-      defaultOpenMobile,
-      onPanelChange,
-      panelComponents,
-    ]
-  )
-
-  return {
-    shellId,
-    sidebar,
-    sidebarWidth,
-    resizeSidebar,
-    isNarrow,
-    panelWidth,
-    resizePanel,
-    open,
-    openMobile,
-    setOpen,
-    setOpenMobile,
-    toggle,
-    openPanel,
-    providerProps,
-  }
-}