basalt-ui 1.27.0 → 1.29.0

package/src/shell/page-aside.tsx

@@ -0,0 +1,327 @@
+/**
+ * `PageAside` — the right-hand aside REGION (`docs/ASIDE-SPEC.md` §0, wave 1). One per page, and
+ * it is the page that decides the region exists at all: `BasaltShell` always renders an
+ * `AppShell.Aside`, but with a width of 0 and `collapsed.desktop` until a route mounts a
+ * `PageAside` to CLAIM it — an empty home renders nothing (law C14), so no route pays for a
+ * reserved column. There is deliberately no `BasaltShellProps` prop for it.
+ *
+ * The mechanism is `PageBar` row 1's, one region over: an internal provider owns the portal target
+ * plus the claim, an internal outlet publishes the node, and the public component portals its own
+ * chrome into it. What the aside adds on top of the claim is the FOLD state — the shell needs it to
+ * size the region, so `PageAside` publishes it back through the same provider.
+ *
+ * WHERE it renders is decided by context and viewport, never by a prop:
+ *
+ * - **Inside `BasaltShell`, from `sm` up** the panel portals into `AppShell.Aside`, folding to a
+ *   `appShellAsideRailWidth` rail with one expand button.
+ * - **Below `sm`, with a `PageBar` that renders a row 2**, the panel PROJECTS into that row: it
+ *   registers its title and glyph with the page-bar slot, renders no node of its own, and row 2
+ *   draws one `Panel` pill opening a `FilterSheet` its children portal into. One node at a time —
+ *   never the in-flow block AND the sheet.
+ * - **Below `sm` with no such row, and in a shell-less app**, it renders IN-FLOW exactly where it
+ *   is written — one node, no `visibleFrom` twin, no second mount (law C9) — with no fold chrome,
+ *   because there is no region to fold into. A page therefore writes it after its main column and
+ *   gets the stacked mobile order for free.
+ *
+ * **The body is the `panel` filter surface.** Children mount under `FilterSetScope surface="panel"`
+ * with a `null` registry, so every basalt control in an aside renders its inspector/facet ROW form
+ * rather than a pill (`docs/ASIDE-SPEC.md` §3), and none of them counts toward a `Filters (n)` that
+ * does not exist here. In the mobile projection the same children mount under `surface="sheet"` —
+ * the sheet's own row form, not a panel row squeezed into a drawer.
+ *
+ * **This component is law C9's ONE declared exception, and the exception is the point of the law.**
+ * Every other responsive twin in the package is CSS (`visibleFrom`/`hiddenFrom` in `actions.tsx`,
+ * `view-tabs.tsx`), because there the two forms are two RENDERINGS of one stateless control and
+ * mounting both costs a hidden box. Here they are not. The desktop form lives inside
+ * `AppShell.Aside` and the phone form inside a `FilterSheet` whose Drawer UNMOUNTS its body when
+ * closed — two portal targets, never one node CSS could reposition between them — and the two
+ * mount their children under DIFFERENT filter surfaces (`panel` vs `sheet`), which is a React
+ * context value no media query in CSS can express. A CSS-only twin would therefore have to render
+ * the children TWICE, and an aside's children are stateful: every bound control in there would
+ * subscribe to its field twice, which is the same defect the shell already refuses for live
+ * indicators in the More sheet. Single-mounting a stateful panel beats a CSS twin, so the viewport
+ * read stays in JS — through `useSyncExternalStore`, so SSR, hydration and the first paint agree.
+ * Recorded in `docs/CONTROLS-SPEC.md` §1 (C9) and `docs/ASIDE-SPEC.md` §0.
+ */
+import { createContext, useCallback, useContext, useMemo, useState } from 'react'
+import type { ReactNode } from 'react'
+import { createPortal } from 'react-dom'
+import { useMantineTheme } from '@mantine/core'
+import { cx } from '../common/props'
+import type { BasaltProps, SlotStylesProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+import { usePersistedOrLocal } from '../state/persisted-or-local'
+import { FilterSetScope } from '../controls/filter-context'
+import { useAsidePanelSlot } from './page-bar'
+import { useIsomorphicLayoutEffect } from './isomorphic-layout-effect'
+import { useMediaQueryMatches } from './use-breakpoint'
+import classes from './page-aside.module.css'
+
+type AsideRegion = {
+  /** The node inside `AppShell.Aside` the panel portals into. `null` outside a shell, and until
+   * the outlet mounts. */
+  target: HTMLElement | null
+  setTarget: (el: HTMLElement | null) => void
+  /** True only under `BasaltShell` — the provider is shell-internal, so the context IS the probe. */
+  inShell: boolean
+  /** A page is rendering a `PageAside` into the region; until then it has zero width. */
+  claimed: boolean
+  /** The claiming page's fold state, published back so the shell can size the region. */
+  folded: boolean
+  claim: () => () => void
+  publishFolded: (folded: boolean) => void
+}
+
+const NO_REGION: AsideRegion = {
+  target: null,
+  setTarget: () => {},
+  inShell: false,
+  claimed: false,
+  folded: false,
+  claim: () => () => {},
+  publishFolded: () => {},
+}
+
+const AsideContext = createContext<AsideRegion>(NO_REGION)
+
+/**
+ * Internal — mounted by `BasaltShell` inside `PageBarProvider`. Owns the portal target, the claim
+ * that turns the region on, and the mirrored fold flag the shell reads for `aside.width`.
+ */
+export function AsideProvider({ children }: { children: ReactNode }): ReactNode {
+  const [target, setTarget] = useState<HTMLElement | null>(null)
+  const [claims, setClaims] = useState(0)
+  const [folded, setFolded] = useState(false)
+
+  const claim = useCallback(() => {
+    setClaims((n) => n + 1)
+    return () => {
+      setClaims((n) => n - 1)
+      // A route that leaves folded must not hand the next one a folded, unclaimed region.
+      setFolded(false)
+    }
+  }, [])
+
+  const value: AsideRegion = {
+    target,
+    setTarget,
+    inShell: true,
+    claimed: claims > 0,
+    folded,
+    claim,
+    publishFolded: setFolded,
+  }
+
+  return <AsideContext.Provider value={value}>{children}</AsideContext.Provider>
+}
+
+/** Internal — the region's state, read by `BasaltShell` to size `AppShell.Aside`. */
+export function useAsideRegion(): Pick<AsideRegion, 'claimed' | 'folded'> {
+  const { claimed, folded } = useContext(AsideContext)
+  return { claimed, folded }
+}
+
+/** Internal — the node inside `AppShell.Aside` the active page's panel portals into. */
+export function AsideOutlet({ className }: { className?: string }) {
+  const { setTarget } = useContext(AsideContext)
+  return <div ref={setTarget} className={className} />
+}
+
+/** The three boxes `PageAside` paints, in every projection (`common/props.ts`). */
+export type PageAsideSlot = 'root' | 'header' | 'body'
+
+export type PageAsideProps = BasaltProps &
+  SlotStylesProps<PageAsideSlot> & {
+    /** Header label; also the accessible name of the region. */
+    title: string
+    /** Persists the fold at `basalt:aside:<persistKey>`. Omit for an unpersisted fold. */
+    persistKey?: string
+    /** Fold state on first render, respected only while nothing is persisted. @default false */
+    defaultFolded?: boolean
+    children: ReactNode
+  }
+
+/** The fold glyph — `app-sidebar.tsx`'s `IconCollapse`, mirrored onto the right-hand edge, so the
+ * two shell folds read as one family. Inline, because basalt ships no icon dependency. */
+function IconAsideFold({ folded }: { folded: boolean }) {
+  return (
+    <svg
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M4 4h16v16H4z" />
+      <path d="M15 4v16" />
+      {folded ? <path d="M10 9l-3 3l3 3" /> : <path d="M8 9l3 3l-3 3" />}
+    </svg>
+  )
+}
+
+/**
+ * The aside's own glyph for the mobile `Panel` pill — {@link IconAsideFold}'s box and divider with
+ * no chevron, because a pill that OPENS a panel is not folding one. Deliberately not a funnel: a
+ * funnel is `Filters (n)`, and an aside is not a filter set.
+ *
+ * It travels to `PageBar` as part of the claim rather than being imported there, which is what
+ * keeps `page-bar.tsx` free of any import back into this module.
+ */
+function IconAsidePanel() {
+  return (
+    <svg
+      width={16}
+      height={16}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M4 4h16v16H4z" />
+      <path d="M15 4v16" />
+    </svg>
+  )
+}
+
+/** The fold toggle — a plain control sized to the `ctl` tier by hand, exactly like `Section`'s own
+ * chevron (`section/section.module.css`) and for the same reason: wrapping one glyph in a
+ * `CtlSlot` would nest a theme provider around it. */
+function FoldButton({ folded, onToggle }: { folded: boolean; onToggle: () => void }) {
+  return (
+    <button
+      type="button"
+      className={classes.fold}
+      aria-expanded={!folded}
+      aria-label={folded ? 'Expand panel' : 'Collapse panel'}
+      onClick={onToggle}
+    >
+      <IconAsideFold folded={folded} />
+    </button>
+  )
+}
+
+export function PageAside(props: PageAsideProps): ReactNode {
+  // F-ERR-1, and here it is an ACCESSIBILITY fault rather than a crash: `title` is both the visible
+  // header and the region's `aria-label`, so a missing one ships a landmark with no name and a
+  // header row with nothing in it — silently, on the branch a screen reader depends on.
+  assertRequiredProps('PageAside', props, ['title'], {
+    title: 'it names the region — it is the header text AND the `aria-label` on the landmark.',
+  })
+  const { title, persistKey, defaultFolded = false, children, className, style, classNames } = props
+  const { target, inShell, claim, publishFolded } = useContext(AsideContext)
+  // Destructured, not held as one object: the hook returns a fresh literal every render, and the
+  // claim effect below would then re-run (claim → release → claim) forever. `claimPanel` is a
+  // `useCallback` on the provider, so it is the stable half.
+  const { host: panelHost, claim: claimPanel, target: panelTarget } = useAsidePanelSlot()
+  const theme = useMantineTheme()
+  // `sm` is the only breakpoint (`docs/CONTROLS-SPEC.md` §2), read off the theme so a consumer that
+  // retunes it moves the aside with it. THE declared C9 exception (see this file's header): the
+  // read is JS because the two projections are two portal targets under two filter surfaces, and a
+  // CSS twin would double-mount stateful children. `useSyncExternalStore` is what keeps SSR, the
+  // hydration pass and the first client paint agreeing on which single node exists.
+  const desktop = useMediaQueryMatches(`(min-width: ${theme.breakpoints.sm})`, true)
+  const [folded, setFolded] = usePersistedOrLocal({
+    scope: 'aside',
+    persistKey,
+    initial: defaultFolded,
+  })
+
+  const portalled = inShell && desktop
+  // Below `sm` the panel goes into the page bar's row 2 IF there is one. Without a row 2 there is
+  // nowhere to put a trigger, so the honest in-flow form (wave 1) stays.
+  const projected = !portalled && panelHost
+  // WHETHER there is a row 2 is published by a LAYOUT EFFECT inside `PageBar`, and React runs
+  // layout effects after the whole commit — so on a phone's FIRST render pass `panelHost` is
+  // always false, whatever the page contains. Rendering the in-flow form on that pass therefore
+  // mounted the children, ran their effects, and unmounted them one commit later on every page
+  // that does project: MEASURED at 2 mounts of one probe subtree for one sheet (real Chrome,
+  // 390x844). Invisible — a layout-effect state flip is flushed before paint — but every bound
+  // control in the aside subscribed to its field, tore the subscription down and rebuilt it, and
+  // any child holding state lost it. Deferring ONE commit is what makes "exactly one mount at
+  // each width" true, which is the promise law C9's exception for this component is granted on.
+  //
+  // Scoped to the shell branch on purpose: a shell-less app has no row 2 to wait for, so it keeps
+  // rendering in flow on its first pass with nothing deferred.
+  const [settled, setSettled] = useState(false)
+  // Memoized on `title` alone: the claim goes into the provider's state, so an object rebuilt every
+  // render would re-run the effect, re-set the state and re-render this component forever.
+  const panelClaim = useMemo(() => ({ title, icon: <IconAsidePanel /> }), [title])
+
+  useIsomorphicLayoutEffect(() => {
+    setSettled(true)
+  }, [])
+
+  useIsomorphicLayoutEffect(() => {
+    if (!portalled) return
+    return claim()
+  }, [portalled, claim])
+
+  useIsomorphicLayoutEffect(() => {
+    if (!portalled) return
+    publishFolded(folded)
+  }, [portalled, folded, publishFolded])
+
+  useIsomorphicLayoutEffect(() => {
+    if (!projected) return
+    return claimPanel(panelClaim)
+  }, [projected, panelClaim, claimPanel])
+
+  const panel = (
+    <section
+      className={cx(classes.panel, classNames?.root, className)}
+      data-basalt-page-aside={portalled ? 'shell' : 'standalone'}
+      aria-label={title}
+      {...(style !== undefined && { style })}
+    >
+      {portalled && folded ? (
+        <div className={classes.rail}>
+          <FoldButton folded onToggle={() => setFolded(false)} />
+        </div>
+      ) : (
+        <>
+          <div className={cx(classes.header, classNames?.header)} data-basalt-page-aside-header="">
+            <span className={classes.title}>{title}</span>
+            {portalled && <FoldButton folded={false} onToggle={() => setFolded(true)} />}
+          </div>
+          <div className={cx(classes.body, classNames?.body)}>
+            {/* The aside body IS a home (law C1) and a filter surface: `panel` is what turns every
+                bound control inside into an inspector row. `registry: null` because there is no
+                census here — no `Filters (n)`, no `Reset all`. */}
+            <FilterSetScope surface="panel" registry={null}>
+              {children}
+            </FilterSetScope>
+          </div>
+        </>
+      )}
+    </section>
+  )
+
+  // Projected: the node lives in the page bar's sheet, so this position renders NOTHING. The
+  // children go through the outlet the bar publishes, under the SHEET surface — a 300px inspector
+  // row in a full-width drawer would be a panel drawn in the wrong place.
+  if (projected) {
+    if (panelTarget === null) return null
+    return createPortal(
+      <FilterSetScope surface="sheet" registry={null}>
+        {children}
+      </FilterSetScope>,
+      panelTarget,
+    )
+  }
+
+  // In flow: below `sm` with no page bar to project into, and in every shell-less app. One node,
+  // written where the page put it — and inside a shell, not until the row-2 claim has had its one
+  // commit to arrive (see `settled` above), so a page that DOES project never mounts these
+  // children just to throw them away.
+  if (!portalled) return inShell && !settled ? null : panel
+  // `target` is null for the first commit only — the outlet's ref sets it.
+  if (target === null) return null
+  return createPortal(panel, target)
+}

package/src/shell/page-bar.module.css

@@ -5,6 +5,10 @@
  * scrolls sideways hides its own controls; the fold is computed instead — `More` for actions
  * (`ActionGroup`), a `Filters (n)` sheet for filters (`FilterSet`'s job, wave 4). The filter
  * container below only supplies `min-width: 0` so that fold has a box to measure against.
+ *
+ * Below `sm`, row 2 is a COLUMN of two declared lines — tabs, then pills (the tabs' phone form is
+ * full-width by contract). That is not a wrap: the line count is decided by what is mounted, never
+ * by width (law C14 for a phone form).
  */
 
 /* The shell-less bar: both rows, sticky at the top of the document. One layer under the AppShell
@@ -22,16 +26,23 @@
 }
 
 /*
- * Row 2 inside a shell: in the page flow, sticky under the 48px header. `--app-shell-header-height`
- * is Mantine's own AppShell variable, so the offset tracks the header at any density with no React
- * state and no measurement. `z-index` sits one layer below the header itself (see `.bar` above) —
- * high enough to stay above ordinary page content, never above the AppShell header.
+ * Row 2 inside a shell — the CONTENT of the shell's band, not a band of its own.
+ *
+ * Nothing positional here on purpose. `BasaltShell` renders the band
+ * (`app-main.module.css`'s `.band`) as a sibling of the scrollport, between the header and Main,
+ * and row 2 portals into it (`page-bar.tsx`). The band owns the width, the inset and the single
+ * `--vx-divider` seam under it; this rule only has to fill it.
+ *
+ * There is deliberately no `position: sticky` left. When row 2 lived in the page flow it stuck to
+ * whatever scrollport contained it, which made its resting position depend on the consumer's own
+ * DOM: nested one `Stack` deep — every real page — the sticky constraint rectangle was that
+ * wrapper, so the band sat one `--app-shell-padding` below the header seam, while a bar written as
+ * Main's direct child sat flush. Outside the scrollport there is nothing to stick to and nothing to
+ * be clamped by.
  */
-.row2Sticky {
-  position: sticky;
-  top: var(--app-shell-header-height, 0px);
-  z-index: calc(var(--app-shell-header-z-index, 100) - 1);
-  background-color: var(--vx-surface-bg);
+.row2Band {
+  width: 100%;
+  min-width: 0;
 }
 
 .row1 {
@@ -108,9 +119,16 @@
  * `min-height: var(--vx-space-page-bar-row-height)` (40px) left a 30px pill floating inside a 40px
  * box with the 5px above and below it belonging to nothing — and because the row sat in a `Stack`
  * that already spaced it, the visible gap between the header and the pills read as ~19px while the
- * gap from the pills to the first card read as ~19px too. Symmetric padding on the row itself is the
- * same total height (46px vs 40px) with both halves owned by one declaration, so the sticky bar's
- * published height covers exactly the band it paints.
+ * gap from the pills to the first card read as ~19px too. Symmetric padding on the row itself is
+ * one declaration owning both halves, so the sticky bar's published height covers exactly the band
+ * it paints — including below `sm`, where `.row2` becomes a COLUMN of `.tabs` then `.pills` and
+ * `padding-block` still owns both edges of the taller band.
+ *
+ * `stackXs` and not `stackSm`: the row sits inside the shell's own bordered band
+ * (`app-main.module.css`'s `.band`), so it no longer has to carry the visual separation in
+ * whitespace — 4px above and below a 30px `ctl` pill still clears it (38px total) and buys back 8px
+ * of content on every page.
+ * Row 1's 40px `--vx-space-page-bar-row-height` is untouched: it is a HEIGHT token, not padding.
  */
 .row2 {
   display: flex;
@@ -118,7 +136,29 @@
   align-items: center;
   gap: var(--vx-space-control-gap);
   min-width: 0;
-  padding-block: var(--vx-space-stack-sm);
+  padding-block: var(--vx-space-stack-xs);
+}
+
+/* The tabs' own line — a direct flex child so a `fullWidth` `ViewTabs` gets the whole row instead
+ * of sharing it with the pills (the row-2 defect: `CtlSlot` is `display: contents`, so an unwrapped
+ * `ViewTabs` used to shrink alongside `.filters` and clip). `flex: none` above `sm`, where the row
+ * is one line and the tabs sit at their intrinsic width beside the pills. */
+.tabs {
+  display: flex;
+  flex: none;
+  min-width: 0;
+}
+
+/* The rest of row 2 — filters, the aside's `Panel` pill, `filtersEnd` — as one line so `.filters`'s
+ * `flex: 1 1 auto` and the trailing auto-margins keep working unchanged; they now measure against
+ * this box instead of `.row2` directly. */
+.pills {
+  display: flex;
+  flex-wrap: nowrap;
+  align-items: center;
+  gap: var(--vx-space-control-gap);
+  flex: 1 1 auto;
+  min-width: 0;
 }
 
 .filters {
@@ -175,4 +215,58 @@
     min-width: var(--vx-space-touch-control-height);
     min-height: var(--vx-space-touch-control-height);
   }
+
+  /*
+   * Row 2's phone form: two declared lines, tabs then pills — not a wrap (law C7). `.pills` folds
+   * every overflow into `Filters (n)` at any width, EXCEPT when it holds nothing visible: below `sm`
+   * `filtersEnd` renders only in the row-1 kebab (`BarActionRow viewport="desktop"` mounts a
+   * `visibleFrom="sm"` group and nothing else), so `tabs` + `filtersEnd` with no `filters`/`panel`
+   * would otherwise mount an empty `.pills` box and its column `gap` still reserves the line's height
+   * — the exact reserved-row case law C14 forbids. `:has()` is already load-bearing elsewhere in this
+   * package (`controls.module.css`'s `.sheetOption`/`.facetOption` focus rules).
+   */
+  .row2 {
+    flex-direction: column;
+    align-items: stretch;
+    gap: var(--vx-space-stack-xs);
+  }
+
+  .pills:not(:has(> .filters, > .panelPill)) {
+    display: none;
+  }
+
+  .tabs {
+    width: 100%;
+  }
+
+  /*
+   * `CtlSlot` (`theme/ctl-theme.tsx`) wraps `tabs` in a `<Box data-basalt-tier style="display:
+   * contents">` — a box-less element, so a bare `.tabs > *` matches ONLY that inert wrapper and never
+   * reaches `ViewTabs`' actual `SegmentedControl`/`Select` root. `display: contents` still promotes
+   * its children to be `.tabs`' real flex items for LAYOUT while leaving them `.tabs`' grandchildren
+   * for the DOM the `>` combinator walks — so the selector has to name the slot's own attribute to
+   * reach past it.
+   */
+  .tabs > [data-basalt-tier] > * {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  /* The phone `Select` past three tab options keeps its own bounded `.phoneSelect` max-width
+   * (`controls.module.css`) and stays left-aligned rather than stretching to fill the line. More
+   * specific than the catch-all above by one class either way, so source order does not matter. */
+  .tabs > [data-basalt-tier] > :global(.mantine-Select-root) {
+    flex: none;
+  }
+}
+
+/*
+ * The aside's mobile trigger (`docs/ASIDE-SPEC.md` §0). Trailing, incompressible, and it exists
+ * only below `sm` — but the gate is JS, not a media query: `PageAside` claims the slot only when it
+ * is NOT portalled into the region, so on a desktop viewport there is no pill to hide. A second,
+ * CSS-side gate here would be a second answer to the same question.
+ */
+.panelPill {
+  margin-inline-start: auto;
+  flex-shrink: 0;
 }

package/src/shell/page-bar.module.css.d.ts

@@ -4,14 +4,17 @@
  */
 declare const classes: {
   readonly bar: string
-  readonly row2Sticky: string
+  readonly row2Band: string
   readonly row1: string
   readonly lead: string
   readonly icon: string
   readonly title: string
   readonly row2: string
   readonly row1End: string
+  readonly tabs: string
+  readonly pills: string
   readonly filters: string
   readonly filtersEnd: string
+  readonly panelPill: string
 }
 export default classes