@exegia/corpora-ui 3.0.0 → 3.1.0

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

@@ -1,30 +0,0 @@
-import { ShellLayout } from "./shell-layout"
-
-export type * from "./type"
-export * from "./shell-metrics"
-export * from "./use-shell-panels"
-export { useShellFit } from "./use-shell-fit"
-export { useShellFitActions, useShellFitState } from "./use-shell-fit-state"
-// The public atom surface. `@internal` atoms (measure, mount) stay unexported
-// on purpose — `export *` would make every internal a breaking-change surface
-// for consumer apps.
-export {
-  removeShellFitInstance,
-  resetShellPanelWidthAtom,
-  resizeShellPanelAtom,
-  shellFitFitsAtom,
-  shellFitMeasuredAtom,
-  shellFitMetricsAtom,
-  shellFitPanelBoundsAtom,
-  shellFitPanelWidthAtom,
-  shellFitRequestedWidthAtom,
-  shellFitStateAtom,
-} from "./shell-fit-atom"
-export * from "./utils"
-
-export * from "./animated-panel"
-export * from "./animated-panel-inset"
-export * from "./animated-panel-provider"
-export * from "./animated-panel-trigger"
-
-export { ShellLayout as default }

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

@@ -1,246 +0,0 @@
-import { removeShellPanelInstance } from "./shell-panel-atom"
-/**
- * Per-instance Jotai state for the shell's layout fit.
- *
- * Every atom is a module-level family keyed by a shell id, so one
- * `ExegiaProvider` at the app root is enough: several shells coexist in one
- * store without a provider each, and a title bar, a command palette or a
- * layout test can drive one by id without holding its controller.
- *
- * Unlike the tree, this feature has no controlled props — the shell measures
- * itself, nobody hands it a viewport. So, like `blocks/auth`'s coordination
- * layer, there is no config atom, no projection and no owned-* loop guard.
- * `useShellFit` is the only writer of `metrics`, and that write is silent by
- * design: a resize is not an event an app subscribed to.
- *
- * The rule itself lives in `shell-metrics.ts` and is called from here, so the
- * arithmetic has one home whether it is read through a hook or a store.
- */
-import { atom } from "jotai"
-import type { Getter, Setter } from "jotai"
-
-import {
-  clampPanelWidth,
-  fitsPanel,
-  metricsEqual,
-  panelBounds,
-  type IShellMetrics,
-} from "./shell-metrics"
-import type {
-  TShellFitInstanceId,
-  IShellFitPanelBounds,
-  IShellFitSeed,
-  IShellFitState,
-} from "./type"
-
-/** An unmeasured shell. Zeroes read as "no layout yet", which the rule fails
- * open on rather than hiding a panel over a reading it never took. */
-const NO_METRICS: IShellMetrics = {
-  rail: 0,
-  insetMin: 0,
-  panelMin: 0,
-  viewport: 0,
-  chrome: 0,
-}
-
-/** A panel that mounts at `--panel-width`. */
-const DEFAULT_SHELL_FIT_SEED: IShellFitSeed = { panelWidth: null }
-
-const NO_BOUNDS: IShellFitPanelBounds = { min: 0, max: 0 }
-
-/**
- * A string-keyed atom family.
- *
- * `jotai/utils`' `atomFamily` is deprecated for Jotai v3, and we need only
- * the string-keyed case with a `remove` — so this stays in-house rather than
- * adding `jotai-family` as a second Jotai package to keep version-aligned.
- * Dropping a key lets the store's WeakMap release that instance's state.
- */
-type TFamily<AtomType> = ((id: TShellFitInstanceId) => AtomType) & {
-  remove: (id: TShellFitInstanceId) => void
-}
-
-/** Every family, so `removeShellFitInstance` can drop an id from all of them. */
-const families: { remove: (id: TShellFitInstanceId) => void }[] = []
-
-function keyed<AtomType>(create: (id: TShellFitInstanceId) => AtomType) {
-  const cache = new Map<TShellFitInstanceId, AtomType>()
-  const family = ((id: TShellFitInstanceId) => {
-    let instance = cache.get(id)
-    if (instance === undefined) {
-      instance = create(id)
-      cache.set(id, instance)
-    }
-    return instance
-  }) as TFamily<AtomType>
-  family.remove = (id: TShellFitInstanceId) => {
-    cache.delete(id)
-  }
-  families.push(family)
-  return family
-}
-
-function stateFamily<Value>(name: string, initialValue: Value) {
-  return keyed((id) => {
-    const instance = atom(initialValue)
-    instance.debugLabel = `shell-fit/${id}/${name}`
-    return instance
-  })
-}
-
-function readFamily<Value>(
-  name: string,
-  read: (get: Getter, id: TShellFitInstanceId) => Value
-) {
-  return keyed((id) => {
-    const instance = atom((get) => read(get, id))
-    instance.debugLabel = `shell-fit/${id}/${name}`
-    return instance
-  })
-}
-
-function actionFamily<Args extends unknown[]>(
-  name: string,
-  write: (
-    get: Getter,
-    set: Setter,
-    id: TShellFitInstanceId,
-    ...args: Args
-  ) => void
-) {
-  return keyed((id) => {
-    const instance = atom(null, (get, set, ...args: Args) =>
-      write(get, set, id, ...args)
-    )
-    instance.debugLabel = `shell-fit/${id}/${name}`
-    return instance
-  })
-}
-
-/** The shell's own measurement of its columns. `useShellFit` is the only
- * writer; read `shellFitMeasuredAtom` to get it with the "no layout yet" case
- * already resolved. */
-export const shellFitMetricsAtom = stateFamily<IShellMetrics>(
-  "metrics",
-  NO_METRICS
-)
-
-/** The width the user dragged to, before clamping — null while the panel sits
- * at `--panel-width`. Read `shellFitPanelWidthAtom` for the width the panel
- * actually renders at: clamping on read is what lets a narrowing viewport
- * pull the panel down without forgetting the width they asked for. */
-export const shellFitRequestedWidthAtom = stateFamily<number | null>(
-  "requestedWidth",
-  null
-)
-
-const shellFitSeedAtom = stateFamily<IShellFitSeed>(
-  "seed",
-  DEFAULT_SHELL_FIT_SEED
-)
-const shellFitInitializedAtom = stateFamily<boolean>("initialized", false)
-
-/** The metrics, or null when the shell has no layout to report — a server
- * render, a `display: none` host, a test with no layout engine. A zero is not
- * a width, and treating it as one would pin the panel to nothing. */
-export const shellFitMeasuredAtom = readFamily<IShellMetrics | null>(
-  "measured",
-  (get, id) => {
-    const metrics = get(shellFitMetricsAtom(id))
-    return metrics.panelMin > 0 ? metrics : null
-  }
-)
-
-/** Whether the shell can hold a secondary panel at all. */
-export const shellFitFitsAtom = readFamily("fits", (get, id) =>
-  fitsPanel(get(shellFitMetricsAtom(id)))
-)
-
-/** The range a resize may land in. */
-export const shellFitPanelBoundsAtom = readFamily<IShellFitPanelBounds>(
-  "panelBounds",
-  (get, id) => {
-    const measured = get(shellFitMeasuredAtom(id))
-    return measured ? panelBounds(measured) : NO_BOUNDS
-  }
-)
-
-/** The width the secondary panel renders at, or null before the first
- * measurement, where the caller falls back to `--panel-width`. */
-export const shellFitPanelWidthAtom = readFamily<number | null>(
-  "panelWidth",
-  (get, id) => {
-    const measured = get(shellFitMeasuredAtom(id))
-    if (!measured) return null
-    const requested = get(shellFitRequestedWidthAtom(id))
-    return clampPanelWidth(requested ?? measured.panelMin, measured)
-  }
-)
-
-/** The whole fit of one shell. This changes on every measurement, so a
- * component that reads one field should subscribe to that field's atom
- * instead: `useAtomValue(shellFitFitsAtom("app-shell"))`. */
-export const shellFitStateAtom = readFamily<IShellFitState>(
-  "state",
-  (get, id) => ({
-    sidebar: get(shellFitMetricsAtom(id)).sidebar ?? null,
-    metrics: get(shellFitMeasuredAtom(id)),
-    fits: get(shellFitFitsAtom(id)),
-    panelWidth: get(shellFitPanelWidthAtom(id)),
-    bounds: get(shellFitPanelBoundsAtom(id)),
-  })
-)
-
-/** @internal The measurement's way in. Silent, and inert when the numbers did
- * not move — a resize event that changes nothing must not re-render a shell. */
-export const measureShellFitAtom = actionFamily<[metrics: IShellMetrics]>(
-  "measure",
-  (get, set, id, metrics) => {
-    if (metricsEqual(get(shellFitMetricsAtom(id)), metrics)) return
-    set(shellFitMetricsAtom(id), metrics)
-  }
-)
-
-/** 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 —
- * and a caller with no idea how wide the shell is can still ask for 900. */
-export const resizeShellPanelAtom = actionFamily<[width: number]>(
-  "resizePanel",
-  (get, set, id, width) => {
-    const measured = get(shellFitMeasuredAtom(id))
-    set(
-      shellFitRequestedWidthAtom(id),
-      measured ? clampPanelWidth(width, measured) : width
-    )
-  }
-)
-
-/** Back to the width the shell mounted with — `defaultPanelWidth`, or
- * `--panel-width` when there was none. */
-export const resetShellPanelWidthAtom = actionFamily<[]>(
-  "resetPanelWidth",
-  (get, set, id) => {
-    set(shellFitRequestedWidthAtom(id), get(shellFitSeedAtom(id)).panelWidth)
-  }
-)
-
-/** @internal Seed the instance once. A seed describes the mount, not every
- * render, so a `defaultPanelWidth` that arrives later never overwrites a
- * width the user dragged to. */
-export const mountShellFitAtom = actionFamily<[seed: IShellFitSeed]>(
-  "mount",
-  (get, set, id, seed) => {
-    if (get(shellFitInitializedAtom(id))) return
-    set(shellFitInitializedAtom(id), true)
-    set(shellFitSeedAtom(id), seed)
-    set(shellFitRequestedWidthAtom(id), seed.panelWidth)
-  }
-)
-
-/** Drop every atom for `id`. `useShellFit` calls this on unmount for shells it
- * keyed itself; an explicit `shellId` is the app's key and outlives its
- * component, so a resized panel survives a route change. */
-export function removeShellFitInstance(id: TShellFitInstanceId): void {
-  removeShellPanelInstance(id)
-  for (const family of families) family.remove(id)
-}

package/src/components/blocks/shell/shell-layout.tsx

@@ -1,139 +0,0 @@
-"use client"
-
-import { MotionIcon } from "motion-icons-react"
-import * as React from "react"
-import { useAtomValueRawSync } from "jotai"
-import { removeShellFitInstance } from "./shell-fit-atom"
-import { shellPanelAtoms } from "./shell-panel-atom"
-
-import { AnimatedPanel } from "./animated-panel.tsx"
-import { cn } from "@/lib/utils"
-import type { IShellLayoutProps, TShellPanelControlProps } from "./type"
-import { SHELL_BEZEL_CLASSES, TITLE_BAR_HEIGHT } from "./utils"
-import type { ClassNameValue } from "tailwind-merge"
-import { AnimatedPanelProvider } from "./animated-panel-provider.tsx"
-import { AnimatedPanelTrigger } from "./animated-panel-trigger.tsx"
-import { AnimatedPanelInset } from "./animated-panel-inset.tsx"
-
-export function ShellLayout({
-  children,
-  variant = "desktop",
-  panels,
-  className,
-  header,
-  trailing,
-  defaultOpen,
-  panelComponents,
-  ...panelControlProps
-}: IShellLayoutProps): React.ReactElement {
-  const background: ClassNameValue = `bg-linear-to-tr/increasing from-neutral-200 via-neutral-100 to-stone-200 dark:from-neutral-900 dark:via-neutral-950 dark:to-stone-950`
-
-  const generatedId = React.useId()
-  const shellId = panelControlProps.shellId ?? generatedId
-  React.useEffect(() => {
-    if (panelControlProps.shellId !== undefined) return
-    return () => removeShellFitInstance(shellId)
-  }, [shellId, panelControlProps.shellId])
-  const sharedComponents = useAtomValueRawSync(
-    shellPanelAtoms(shellId).components
-  )
-
-  // Content pushed through `openPanel(side, component)` wins over the static
-  // `panels` entry; a side renders its panel when either supplies content.
-  const leftContent =
-    sharedComponents.left ?? panelComponents?.left ?? panels?.left?.component
-  const rightContent =
-    sharedComponents.right ?? panelComponents?.right ?? panels?.right?.component
-
-  // Each panel seeds its own side's initial state (`defaultOpen ?? open`);
-  // an explicit `defaultOpen` record — usually from useShellPanels — wins
-  // per side.
-  const initialOpen: TShellPanelControlProps["defaultOpen"] = {
-    ...(panels?.left && {
-      left: panels.left.defaultOpen ?? true,
-    }),
-    ...(panels?.right && {
-      right: panels.right.defaultOpen ?? false,
-    }),
-    ...defaultOpen,
-  }
-
-  return (
-    <AnimatedPanelProvider
-      {...panelControlProps}
-      shellId={shellId}
-      defaultOpen={initialOpen}
-      className={cn(
-        "min-h-0 px-2 pb-2 relative h-full",
-        variant === "web" && "pt-2",
-        className,
-        background
-      )}
-      style={{
-        paddingTop: variant === "desktop" ? TITLE_BAR_HEIGHT : 0,
-      }}
-    >
-      {leftContent && (
-        <AnimatedPanel
-          ariaLabel="Primary navigation"
-          collapsible="icon"
-          role="navigation"
-          variant="inset"
-        >
-          {leftContent}
-        </AnimatedPanel>
-      )}
-
-      <AnimatedPanelInset>
-        <header className="h-12 gap-2 px-2 flex flex-row! items-center justify-between border-b">
-          {leftContent && (
-            <div className="min-w-0 gap-2 flex shrink-0 items-center justify-start">
-              <AnimatedPanelTrigger side="left">
-                <MotionIcon name="PanelLeft" size={24} animation="press" />
-              </AnimatedPanelTrigger>
-            </div>
-          )}
-          {header && (
-            <div className="min-w-0 flex flex-1 items-center">{header}</div>
-          )}
-          {(trailing || rightContent) && (
-            // ml-auto, not flex-fill: the cluster hugs the trailing edge even
-            // when there is no header (or left trigger) to push against.
-            <div className="gap-2 ml-auto flex shrink-0 items-center justify-end">
-              {trailing}
-              {rightContent && (
-                <AnimatedPanelTrigger aria-label="Toggle panel" side="right">
-                  <MotionIcon
-                    className="opacity-70"
-                    name="PanelRight"
-                    size={24}
-                  />
-                </AnimatedPanelTrigger>
-              )}
-            </div>
-          )}
-        </header>
-        <div className="min-h-24 flex-1 overflow-auto">{children}</div>
-      </AnimatedPanelInset>
-
-      {rightContent && (
-        <AnimatedPanel
-          ariaLabel={panels?.right?.name ?? "Secondary panel"}
-          // Below md the panel is portal led over the page, so it carries the
-          // surface itself; the desktop rail keeps it on the inner panel.
-          className={cn(
-            "bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-900",
-            "rounded-md",
-            SHELL_BEZEL_CLASSES
-          )}
-          collapsible="offcanvas"
-          role="complementary"
-          side="right"
-          variant="inset"
-        >
-          {rightContent}
-        </AnimatedPanel>
-      )}
-    </AnimatedPanelProvider>
-  )
-}

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

@@ -1,133 +0,0 @@
-/**
- * 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 IShellSidebarFit {
-  width: number
-  minWidth: number
-  maxWidth: number
-  canExpand: boolean
-  mode: "expanded" | "icon" | "hidden"
-}
-
-/** Reserve the body first, then shrink, fold, or hide the navigation rail.
- * The requested width/open state is retained so widening restores it. */
-export function fitSidebar({
-  width,
-  padding,
-  gap,
-  insetMin,
-  expanded,
-  icon,
-  minimum,
-  open,
-  collapsible,
-  present,
-}: {
-  width: number
-  padding: number
-  gap: number
-  insetMin: number
-  expanded: number
-  icon: number
-  minimum: number
-  open: boolean
-  collapsible: string
-  present: boolean
-}): IShellSidebarFit {
-  const room = width > 0 ? Math.max(0, width - padding - gap - insetMin) : 480
-  const canExpand = present && room >= minimum
-  const isExpanded = canExpand && (open || collapsible === "none")
-  const railWidth = !present
-    ? 0
-    : isExpanded
-      ? Math.min(expanded, room)
-      : collapsible === "offcanvas" || room < icon
-        ? 0
-        : icon
-  return {
-    width: railWidth,
-    minWidth: minimum,
-    maxWidth: Math.max(minimum, Math.min(480, room)),
-    canExpand,
-    mode: railWidth === 0 ? "hidden" : isExpanded ? "expanded" : "icon",
-  }
-}
-
-export interface IShellMetrics {
-  sidebar?: IShellSidebarFit
-  /** 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
-  /** Available shell container width (legacy field name). */
-  viewport: number
-  /** px the shell's own frame eats before any column gets a share: its
-   * padding, plus the gap between columns.
-   */
-  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 }: IShellMetrics) {
-  return rail + insetMin + panelMin
-}
-
-/**
- * Whether the shell can hold a secondary panel, including padding and gaps.
- *
- * 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: IShellMetrics) {
-  if (metrics.viewport <= 0 || metrics.panelMin <= 0) return true
-  return requiredWidth(metrics) + metrics.chrome <= 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: IShellMetrics) {
-  const { chrome, insetMin, panelMin, rail, viewport } = metrics
-  return {
-    min: panelMin,
-    max: Math.max(panelMin, viewport - chrome - rail - insetMin),
-  }
-}
-
-export function clampPanelWidth(width: number, metrics: IShellMetrics) {
-  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: IShellMetrics, b: IShellMetrics) {
-  return (
-    a.rail === b.rail &&
-    a.insetMin === b.insetMin &&
-    a.panelMin === b.panelMin &&
-    a.viewport === b.viewport &&
-    a.chrome === b.chrome &&
-    a.sidebar?.width === b.sidebar?.width &&
-    a.sidebar?.minWidth === b.sidebar?.minWidth &&
-    a.sidebar?.maxWidth === b.sidebar?.maxWidth &&
-    a.sidebar?.canExpand === b.sidebar?.canExpand &&
-    a.sidebar?.mode === b.sidebar?.mode
-  )
-}

package/src/components/blocks/shell/shell-panel-atom.ts

@@ -1,74 +0,0 @@
-import { atom } from "jotai"
-import type { TSidebarComponentMap, TSidebarSide } from "./type"
-
-type OpenState = Record<TSidebarSide, boolean>
-type Handlers = {
-  setOpen: (open: boolean, side: TSidebarSide) => void
-  setOpenMobile: (open: boolean, side: TSidebarSide) => void
-}
-function createState() {
-  const railWidth = atom<number | null>(null)
-  const resizeSidebar = atom(null, (_get, set, width: number) => {
-    if (Number.isFinite(width))
-      set(railWidth, Math.max(180, Math.min(480, width)))
-  })
-  const open = atom<OpenState>({ left: true, right: false })
-  const mobile = atom<OpenState>({ left: false, right: false })
-  const components = atom<TSidebarComponentMap>({})
-  const handlers = atom<Handlers | null>(null)
-  const seeded = atom(false)
-  const setOpen = atom(null, (get, set, value: boolean, side: TSidebarSide) => {
-    const host = get(handlers)
-    if (host) host.setOpen(value, side)
-    else set(open, { ...get(open), [side]: value })
-  })
-  const setOpenMobile = atom(
-    null,
-    (get, set, value: boolean, side: TSidebarSide) => {
-      const host = get(handlers)
-      if (host) host.setOpenMobile(value, side)
-      else set(mobile, { ...get(mobile), [side]: value })
-    }
-  )
-  const toggle = atom(null, (get, set, side: TSidebarSide) =>
-    set(setOpen, !get(open)[side], side)
-  )
-  const seed = atom(
-    null,
-    (
-      get,
-      set,
-      initial?: Partial<OpenState>,
-      initialMobile?: Partial<OpenState>
-    ) => {
-      if (get(seeded)) return
-      set(seeded, true)
-      set(open, { ...get(open), ...initial })
-      set(mobile, { ...get(mobile), ...initialMobile })
-    }
-  )
-  return {
-    railWidth,
-    resizeSidebar,
-    open,
-    mobile,
-    components,
-    handlers,
-    setOpen,
-    setOpenMobile,
-    toggle,
-    seed,
-  }
-}
-const instances = new Map<string, ReturnType<typeof createState>>()
-export function shellPanelAtoms(id: string) {
-  let state = instances.get(id)
-  if (!state) {
-    state = createState()
-    instances.set(id, state)
-  }
-  return state
-}
-export function removeShellPanelInstance(id: string) {
-  instances.delete(id)
-}