basalt-ui 1.26.0 → 1.28.0

package/src/connectivity/use-connectivity.ts

@@ -1,8 +1,9 @@
 /**
  * useConnectivity — reads the aggregated connectivity status from ConnectivityContext.
  *
- * Throws if used outside a ConnectivityProvider. For the provider-less simple boolean,
- * use the deprecated `useOnlineStatus` from `basalt-ui/state`.
+ * Throws if used outside a ConnectivityProvider. `BasaltProvider` auto-mounts
+ * `ConnectivityProvider`, so this hook works with zero setup in the common case; the removed
+ * `useOnlineStatus` (formerly `basalt-ui/state`) is replaced by this hook (see MIGRATING.md).
  *
  * @example
  * const { status, details } = useConnectivity()

package/src/content/article-layout.module.css

@@ -17,6 +17,11 @@
   grid-template-columns: minmax(0, var(--vx-prose-measure));
 }
 
+/* The literal below MUST equal `BREAKPOINTS.article` (src/tokens/index.ts) — a `@media`
+ * condition is resolved before custom properties exist, so `max-width: var(--x)` is invalid CSS
+ * and a stylesheet with a responsive rule has no choice but to write the number. The token is the
+ * readable half; `article-layout.breakpoint.test.ts` asserts the two agree, the same
+ * "literal must match the token" idiom as `styles.floor.test.ts`. Change both or neither. */
 @media (max-width: 1200px) {
   .root {
     grid-template-columns: minmax(0, var(--vx-prose-measure));
@@ -72,10 +77,12 @@
 .tocRail {
   grid-column: 2;
   position: sticky;
-  /* DESKTOP-only value on purpose (no `< sm` override needed): the rail is already `display: none`
-   * below the 1200px `@media` breakpoint just above, well above the `sm` (48em/768px) breakpoint
-   * that switches BasaltShell's header — and, by extension, this clearance — to its mobile value
-   * (see `content/prose.module.css` for the responsive split; docs/CONTENT-SPEC.md §5). */
+  /* The rail sticks inside whatever scrolls it — `AppShell.Main` in a shell, the document without
+   * one — and NOTHING overhangs that box: the app header and `PageBar` row 2's band are both shell
+   * regions rendered outside the scrollport (`shell/app-main.module.css`). So the offset is
+   * `--vx-space-sticky-header-clearance` and nothing else, which is exactly what that token means
+   * since it stopped carrying a header height (tokens/palette.ts, `deriveSpacing`;
+   * docs/CONTENT-SPEC.md §5). */
   top: var(--vx-space-sticky-header-clearance);
   align-self: start;
 }

package/src/content/callout.tsx

@@ -8,20 +8,25 @@
  *   <p>This endpoint is rate-limited to 60 requests/minute.</p>
  * </Callout>
  */
-import type { CSSProperties, ReactNode } from 'react'
+import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
 import classes from './callout.module.css'
 
+/**
+ * One of the five `Tone` forks (`common/props.ts`) — kept as its own type because `info` has no
+ * `Tone` equivalent: `good`/`warn`/`bad` line up with `Tone` exactly, `info` is the extra kind a
+ * callout needs that a status badge does not.
+ */
 export type CalloutKind = 'info' | 'good' | 'warn' | 'bad'
 
-export type CalloutProps = {
+export type CalloutProps = BasaltProps & {
   /** Semantic kind — drives the rail/tint color and the default icon. Default `'info'`. */
   readonly kind?: CalloutKind
   readonly title?: string
   /** Overrides the default per-kind icon. Only rendered alongside a `title`. */
   readonly icon?: ReactNode
   readonly children: ReactNode
-  readonly className?: string
-  readonly style?: CSSProperties
 }
 
 const KIND_CLASS: Record<CalloutKind, string> = {
@@ -80,10 +85,11 @@ const DEFAULT_ICON: Record<CalloutKind, ReactNode> = {
 }
 
 export function Callout({ kind = 'info', title, icon, children, className, style }: CalloutProps) {
-  const rootClass = [classes.root, KIND_CLASS[kind], className].filter(Boolean).join(' ')
-
   return (
-    <div className={rootClass} {...(style !== undefined && { style })}>
+    <div
+      className={cx(classes.root, KIND_CLASS[kind], className)}
+      {...(style !== undefined && { style })}
+    >
       {title !== undefined && (
         <div className={classes.titleRow}>
           <span className={classes.icon}>{icon ?? DEFAULT_ICON[kind]}</span>

package/src/content/guide.tsx

@@ -18,6 +18,8 @@ import type { ReactNode } from 'react'
 import { ActionIcon, Button, Drawer } from '@mantine/core'
 import type { DrawerProps } from '@mantine/core'
 import { useDisclosure } from '@mantine/hooks'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import classes from './guide.module.css'
 import type { ArticleNavTarget } from './article-layout'
 import { Markdown } from './markdown'
@@ -54,7 +56,7 @@ function GuideGlyph() {
   )
 }
 
-export type GuideDrawerProps = {
+export type GuideDrawerProps = BasaltProps & {
   readonly opened: boolean
   readonly onClose: () => void
   readonly title: string
@@ -78,6 +80,8 @@ export function GuideDrawer({
   fullPageHref,
   renderLink = defaultRenderLink,
   size = 440,
+  className,
+  style,
 }: GuideDrawerProps) {
   return (
     <Drawer
@@ -86,6 +90,8 @@ export function GuideDrawer({
       position="right"
       size={size}
       title={<span className={classes.drawerTitle}>{title}</span>}
+      {...(className !== undefined && { className })}
+      {...(style !== undefined && { style })}
     >
       <div className={classes.body}>
         {markdown !== undefined ? (
@@ -111,7 +117,7 @@ export function GuideDrawer({
   )
 }
 
-export type GuideLinkProps = {
+export type GuideLinkProps = BasaltProps & {
   /** Trigger label. Default `'Guide'`. */
   readonly label?: string
   readonly title: string
@@ -131,6 +137,8 @@ export function GuideLink({
   fullPageHref,
   renderLink,
   iconOnly = false,
+  className,
+  style,
 }: GuideLinkProps) {
   const [opened, { open, close }] = useDisclosure(false)
 
@@ -141,9 +149,10 @@ export function GuideLink({
           variant="subtle"
           color="gray"
           size="sm"
-          className={classes.trigger}
+          className={cx(classes.trigger, className)}
           onClick={open}
           aria-label={label}
+          {...(style !== undefined && { style })}
         >
           <GuideGlyph />
         </ActionIcon>
@@ -152,9 +161,10 @@ export function GuideLink({
           variant="subtle"
           color="gray"
           size="compact-xs"
-          className={classes.trigger}
+          className={cx(classes.trigger, className)}
           leftSection={<GuideGlyph />}
           onClick={open}
+          {...(style !== undefined && { style })}
         >
           <span className={classes.triggerLabel}>{label}</span>
         </Button>

package/src/content/heading-anchor.tsx

@@ -19,18 +19,25 @@
  *   <h2 id={id}>Setup<HeadingAnchor id={id} /></h2>
  * </Prose>
  */
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
 import { CopyAction } from './copy-action'
 import { LinkGlyph } from './glyphs'
 import classes from './prose.module.css'
 
-export type HeadingAnchorProps = {
+export type HeadingAnchorProps = BasaltProps & {
   /** The heading's `id` — the fragment the copied URL points at. */
   readonly id: string
   /** Accessible name for the trigger. */
   readonly label?: string
 }
 
-export function HeadingAnchor({ id, label = 'Copy link to section' }: HeadingAnchorProps) {
+export function HeadingAnchor({
+  id,
+  label = 'Copy link to section',
+  className,
+  style,
+}: HeadingAnchorProps) {
   // Resolved at click time, never at render: the component is SSR-rendered (no `window`), and the
   // live search/pathname is the honest basis for the link a reader is asking to share.
   const resolveUrl = () => {
@@ -41,7 +48,11 @@ export function HeadingAnchor({ id, label = 'Copy link to section' }: HeadingAnc
   // The span owns placement + the hover reveal; CopyAction owns the affordance itself. It also
   // carries `data-heading-anchor`, which `TableOfContents` strips when reading a heading's label.
   return (
-    <span className={classes.headingAnchor} data-heading-anchor>
+    <span
+      className={cx(classes.headingAnchor, className)}
+      data-heading-anchor
+      {...(style !== undefined && { style })}
+    >
       <CopyAction
         value={resolveUrl}
         label="Copy link"

package/src/content/index.ts

@@ -27,6 +27,8 @@ export type { TableOfContentsProps, TocItem } from './toc'
 export { ReadingProgress } from './reading-progress'
 export type { ReadingProgressProps } from './reading-progress'
 
+// `SlugTracker` is a PascalCase utility class, not a component — see its own JSDoc `@remarks`
+// (isomorphic harness finding F-DET-1). `new SlugTracker()`, never `<SlugTracker />`.
 export { headingSlug, readingTime, SlugTracker } from './slug'
 export type { ReadingTime } from './slug'
 

package/src/content/markdown.tsx

@@ -394,6 +394,7 @@ const LazyReactMarkdown = lazy(() =>
     })
     .catch(() => ({ default: ({ text }: BridgeProps) => <PlainTextFallback text={text} /> })),
 )
+Object.assign(LazyReactMarkdown, { displayName: 'LazyReactMarkdown' })
 
 // ── Streaming block rendering ──────────────────────────────────────────────────────────────────
 
@@ -443,6 +444,7 @@ function BlockRenderer({
 // Referential stability of `components`/`urlTransform` (both memoized by the caller) is what makes
 // this memo skip re-rendering an unchanged settled block — see the module JSDoc.
 const MemoizedBlock = memo(BlockRenderer)
+MemoizedBlock.displayName = 'MemoizedBlock'
 
 // ── Lazy-loaded remend ─────────────────────────────────────────────────────────────────────────
 

package/src/content/prose.module.css

@@ -32,16 +32,18 @@
   margin-bottom: 0;
 }
 
-/* Sticky-header clearance for in-page anchors. One value on every viewport: since the
- * controls waves the AppShell header is `appShellHeaderHeight` (48px) on phones too — the two-row
- * mobile header and its `-mobile` clearance token are gone (docs/CONTROLS-SPEC.md §2.1, law C14).
- * `--basalt-page-bar-h` (a sticky PageBar row 2, published by the shell) is added on top so a
- * heading never lands under the filter row. A `./content` consumer rendering Prose standalone (no
- * BasaltShell) overrides `--vx-space-sticky-header-clearance` itself. */
+/* Anchor clearance. One value on every viewport, and NO chrome height in it: an anchor scroll
+ * happens inside the scrollport, and since `BasaltShell` made `AppShell.Main` that box both the
+ * AppShell header and `PageBar` row 2's band are regions rendered OUTSIDE it
+ * (`shell/app-main.module.css`) — the `--basalt-page-bar-h` term this rule used to add would now
+ * push every heading a band below where it belongs, and an `--app-shell-header-height` term (gone
+ * since the controls waves) would add a header on top of that. What is left is breathing room,
+ * which is precisely what `--vx-space-sticky-header-clearance` means now (tokens/palette.ts). A
+ * `./content` consumer with its OWN fixed chrome above the scrollport overrides that token. */
 .root h2,
 .root h3,
 .root h4 {
-  scroll-margin-top: calc(var(--vx-space-sticky-header-clearance) + var(--basalt-page-bar-h, 0px));
+  scroll-margin-top: var(--vx-space-sticky-header-clearance);
 }
 
 /* Headings share family/weight/color across densities; size + margin differ below. */

package/src/content/reading-progress.tsx

@@ -1,9 +1,14 @@
 /**
  * ReadingProgress — an opt-in, scroll-driven 2px top bar (docs/CONTENT-SPEC.md §3/§7).
  *
- * Progress is how far `target` (default: the whole document) has been scrolled through the
+ * Progress is how far `target` (default: the whole scrollport) has been scrolled through the
  * viewport — 0 at the top of `target`, 1 once its bottom edge has cleared the viewport.
  *
+ * WHICH BOX SCROLLS is resolved, never assumed: inside `BasaltShell` the scroller is
+ * `AppShell.Main` (`shell/app-main.module.css`), where `window.scrollY` is pinned at 0 and a
+ * `scroll` listener on `window` never fires. `scrollParentOf` answers `null` for a shell-less app
+ * and this falls back to the window unchanged.
+ *
  * @example
  * import { ReadingProgress } from 'basalt-ui/content'
  *
@@ -13,35 +18,50 @@
  */
 import type { RefObject } from 'react'
 import { useEffect, useRef, useState } from 'react'
+import type { BasaltProps } from '../common/props'
+import { cx } from '../common/props'
+import { scrollParentOf } from '../common/scroll-parent'
 import classes from './reading-progress.module.css'
 
-export type ReadingProgressProps = {
-  /** The element to track scroll progress through. Default: the whole document. */
+export type ReadingProgressProps = BasaltProps & {
+  /** The element to track scroll progress through. Default: the whole scrollport. */
   readonly target?: RefObject<HTMLElement | null>
 }
 
-function computeProgress(target: HTMLElement | null | undefined): number {
-  const viewport = window.innerHeight
-  const scrollTop = window.scrollY
+/**
+ * `port` is the resolved scrollport, or `null` for "the document scrolls". The only thing that
+ * changes between the two is where the four numbers come from — `target`'s offset is measured
+ * against the SCROLLER's own top edge rather than the viewport's, which for the window case is the
+ * same edge and reduces to the original arithmetic.
+ */
+function computeProgress(target: HTMLElement | null | undefined, port: HTMLElement | null): number {
+  const viewport = port ? port.clientHeight : window.innerHeight
+  const scrollTop = port ? port.scrollTop : window.scrollY
+  const originTop = port ? port.getBoundingClientRect().top : 0
+  const scrollable = port ? port.scrollHeight : document.documentElement.scrollHeight
 
-  const start = target ? target.getBoundingClientRect().top + scrollTop : 0
-  const total = target
-    ? target.offsetHeight - viewport
-    : document.documentElement.scrollHeight - viewport
+  const start = target ? target.getBoundingClientRect().top - originTop + scrollTop : 0
+  const total = target ? target.offsetHeight - viewport : scrollable - viewport
 
   if (total <= 0) return 0
   const ratio = (scrollTop - start) / total
   return Math.min(1, Math.max(0, ratio))
 }
 
-export function ReadingProgress({ target }: ReadingProgressProps = {}) {
+export function ReadingProgress({ target, className, style }: ReadingProgressProps = {}) {
   const [progress, setProgress] = useState(0)
   const frame = useRef<number | null>(null)
+  const rootRef = useRef<HTMLDivElement | null>(null)
 
   useEffect(() => {
+    // The bar itself is a fine probe when there is no `target`: it is mounted inside whatever
+    // region the reader is scrolling, which is the box this is measuring.
+    const port = scrollParentOf(target?.current ?? rootRef.current)
+    const scroller: Window | HTMLElement = port ?? window
+
     const tick = () => {
       frame.current = null
-      setProgress(computeProgress(target?.current))
+      setProgress(computeProgress(target?.current, port))
     }
 
     const onScroll = () => {
@@ -50,17 +70,22 @@ export function ReadingProgress({ target }: ReadingProgressProps = {}) {
     }
 
     tick()
-    window.addEventListener('scroll', onScroll, { passive: true })
+    scroller.addEventListener('scroll', onScroll, { passive: true })
     window.addEventListener('resize', onScroll, { passive: true })
     return () => {
-      window.removeEventListener('scroll', onScroll)
+      scroller.removeEventListener('scroll', onScroll)
       window.removeEventListener('resize', onScroll)
       if (frame.current !== null) cancelAnimationFrame(frame.current)
     }
   }, [target])
 
   return (
-    <div className={classes.root} aria-hidden>
+    <div
+      ref={rootRef}
+      className={cx(classes.root, className)}
+      aria-hidden
+      {...(style !== undefined && { style })}
+    >
       <div className={classes.fill} style={{ transform: `scaleX(${progress})` }} />
     </div>
   )

package/src/content/slug.ts

@@ -28,6 +28,10 @@ export function headingSlug(text: string): string {
  * Dedupes repeated slugs within one document — the second occurrence of a slug gets `-1`, the
  * third `-2`, and so on (matches github-slugger's own collision behavior). Create one instance
  * per document/render pass; it carries no global state.
+ *
+ * @remarks not a component — an ordinary PascalCase utility class on the `content` barrel
+ * (isomorphic harness finding F-DET-1). It carries no `prototype.isReactComponent` marker, so
+ * `new SlugTracker()`, not `<SlugTracker />`.
  */
 export class SlugTracker {
   private readonly counts = new Map<string, number>()

package/src/content/toc.tsx

@@ -6,6 +6,17 @@
  * `headingSlug`/`SlugTracker` when authoring the headings. Sticky positioning is the consumer's
  * job; this component is just the rail.
  *
+ * The spy resolves WHICH BOX SCROLLS (`scrollParentOf`) instead of assuming the window: inside
+ * `BasaltShell` that is `AppShell.Main` (`shell/app-main.module.css`), so both the observer's root
+ * and the bottom-edge arithmetic have to be that element — a window listener there never fires and
+ * a viewport-rooted observer measures the wrong band. `null` means the document scrolls, which is
+ * the shell-less case and behaves exactly as before.
+ *
+ * The active rail item carries `aria-current="location"` (WAI-ARIA APG's own recommendation for a
+ * link set that navigates within one page, rather than `"page"`/`"true"`) — both a genuine a11y fix
+ * (previously `activeId` drove `classes.active` alone, so a screen reader had no signal at all) and
+ * the one DOM-observable hook for `activeId` that does not depend on a CSS Modules class hash.
+ *
  * @example
  * import { TableOfContents, headingSlug } from 'basalt-ui/content'
  *
@@ -18,6 +29,7 @@
 import type { MouseEvent, RefObject } from 'react'
 import { useEffect, useRef, useState } from 'react'
 import { useReducedMotion } from '@mantine/hooks'
+import { scrollParentOf } from '../common/scroll-parent'
 import classes from './toc.module.css'
 
 export type TocItem = {
@@ -79,6 +91,11 @@ export function TableOfContents({
   // Set while a clicked item owns the rail; `resolve` stands down until it's released.
   const pinnedRef = useRef<string | null>(null)
   const releasePinRef = useRef<(() => void) | null>(null)
+  // The rail's own node — the probe `scrollParentOf` walks from when there is no `containerRef`.
+  const navRef = useRef<HTMLElement | null>(null)
+  // The resolved scrollport (`null` = the document), published by the spy effect so the click-pin
+  // release below listens for `scrollend` on the same box the spy is watching.
+  const portRef = useRef<HTMLElement | null>(null)
 
   useEffect(() => {
     return () => releasePinRef.current?.()
@@ -108,6 +125,10 @@ export function TableOfContents({
       .filter((el): el is HTMLElement => el !== null)
     if (elements.length === 0) return
 
+    const port = scrollParentOf(containerRef?.current ?? navRef.current)
+    portRef.current = port
+    const scroller: Window | HTMLElement = port ?? window
+
     const intersecting = new Set<string>()
 
     const resolve = () => {
@@ -118,8 +139,9 @@ export function TableOfContents({
       // Bottom edge: the last sections are usually shorter than the observer's 70% dead zone, so
       // their headings can NEVER reach the activation band — the rail would stall on whichever
       // section last made it in. Once the page bottoms out, the final item is the honest answer.
-      const doc = document.documentElement
-      if (window.innerHeight + window.scrollY >= doc.scrollHeight - 2) {
+      const box = port ?? document.documentElement
+      const seen = port ? port.clientHeight + port.scrollTop : window.innerHeight + window.scrollY
+      if (seen >= box.scrollHeight - 2) {
         const last = elements[elements.length - 1]
         if (last) setActiveId(last.id)
         return
@@ -134,7 +156,9 @@ export function TableOfContents({
       // Nothing intersecting — the last heading already scrolled past, or (above the first one,
       // i.e. at the very top of the article) the first heading, so the rail always marks where the
       // reader actually is instead of showing nothing until the first heading reaches the band.
-      const passed = elements.filter((el) => el.getBoundingClientRect().top < 0)
+      // "Past" is measured against the SCROLLER's top edge, which for the window case is 0.
+      const originTop = port ? port.getBoundingClientRect().top : 0
+      const passed = elements.filter((el) => el.getBoundingClientRect().top < originTop)
       const current = passed[passed.length - 1] ?? elements[0]
       if (current) setActiveId(current.id)
     }
@@ -147,19 +171,22 @@ export function TableOfContents({
         }
         resolve()
       },
-      { rootMargin: '-80px 0px -70% 0px' },
+      // `root: null` IS the viewport — the shell-less case, unchanged. Inside a shell the root has
+      // to be the scrollport or the `-70%` dead zone is measured against a box nothing scrolls.
+      { root: port, rootMargin: '-80px 0px -70% 0px' },
     )
 
     for (const el of elements) observer.observe(el)
     // The observer only fires when an intersection CHANGES; the bottom edge above resolves on
     // scroll position alone, so it needs a scroll signal too. Re-setting the same id is a no-op
     // for React, so this stays free on every frame that doesn't move the rail.
-    window.addEventListener('scroll', resolve, { passive: true })
+    scroller.addEventListener('scroll', resolve, { passive: true })
     return () => {
       observer.disconnect()
-      window.removeEventListener('scroll', resolve)
+      scroller.removeEventListener('scroll', resolve)
+      portRef.current = null
     }
-  }, [resolvedItems])
+  }, [resolvedItems, containerRef])
 
   if (resolvedItems.length === 0) return null
 
@@ -174,15 +201,18 @@ export function TableOfContents({
     setActiveId(id)
     pinnedRef.current = id
 
+    // The same box the spy watches — `scrollend` on `window` never fires for a scroll that happened
+    // inside `AppShell.Main`, which would leave the rail pinned for the full `CLICK_PIN_MAX_MS`.
+    const scroller: Window | HTMLElement = portRef.current ?? window
     let timer: ReturnType<typeof setTimeout> | null = null
     const release = () => {
       pinnedRef.current = null
       if (timer !== null) clearTimeout(timer)
-      window.removeEventListener('scrollend', release)
+      scroller.removeEventListener('scrollend', release)
       releasePinRef.current = null
     }
     timer = setTimeout(release, CLICK_PIN_MAX_MS)
-    window.addEventListener('scrollend', release, { once: true })
+    scroller.addEventListener('scrollend', release, { once: true })
     releasePinRef.current = release
   }
 
@@ -200,7 +230,7 @@ export function TableOfContents({
   const navClass = [classes.root, className].filter(Boolean).join(' ')
 
   return (
-    <nav className={navClass} aria-label={title}>
+    <nav ref={navRef} className={navClass} aria-label={title}>
       <div className={classes.header}>{title}</div>
       <ul className={classes.list}>
         {resolvedItems.map((item) => (
@@ -214,6 +244,13 @@ export function TableOfContents({
               ]
                 .filter(Boolean)
                 .join(' ')}
+              // `classes.active` alone used to be the ONLY signal of which item the spy picked —
+              // both a real a11y gap (nothing here told assistive tech which section is current)
+              // and, incidentally, the reason a consumer/test could not observe `activeId` without
+              // reading CSS. `location` (not `page`/`true`) is the value WAI-ARIA's Authoring
+              // Practices call out BY NAME for exactly this widget: a set of links navigating
+              // within a single page, as opposed to a set of links to different pages.
+              aria-current={activeId === item.id ? 'location' : undefined}
               onClick={handleClick(item.id)}
             >
               {item.label}