basalt-ui 1.41.0 → 2.0.1

package/src/commands/projectors.ts

@@ -1,183 +1,9 @@
 /**
- * projectors — project the active command registry into Mantine Spotlight actions, a shortcut list,
- * and a @tanstack/react-hotkeys bindings array.
- *
- * All functions read the runtime stash (populated by defineCommands) — they do NOT read the
- * type-erased BasaltRegister slot. They are safe to call before any commands are registered
- * (returns empty array).
- *
- * @example
- * // In BasaltOverlays, pass toSpotlightActions() to Spotlight:
- * <Spotlight store={basaltSpotlight[0]} actions={toSpotlightActions()} shortcut="mod + K" />
- *
- * // Render a shortcut reference list:
- * const shortcuts = toShortcutList()  // [{ id, label, shortcut, group? }, ...]
- *
- * // Opt-in: drive your own useHotkeys() call (useCommandHotkeys uses the imperative manager API instead):
- * const bindings = toHotkeyBindings()
- * useHotkeys(bindings)
- */
-import type { SpotlightActionData } from '@mantine/spotlight'
-import type { ReactNode } from 'react'
-import { getActiveCommands, runCommand } from './define-commands'
-import type { CommandId } from './define-commands'
-import { formatShortcutDisplay, detectMac } from './shortcut-format'
-
-// ── UseHotkeyDefinition (re-typed locally to avoid peer import at module level) ──
-
-/**
- * Shape of a single entry in the array passed to useHotkeys().
- * Mirrors UseHotkeyDefinition from @tanstack/react-hotkeys — typed locally so
- * projectors.ts has no hard import on the optional peer.
- */
-export type HotkeyBinding = {
-  hotkey: string
-  /**
-   * Callback invoked when the hotkey fires. Widened to match @tanstack/react-hotkeys'
-   * HotkeyCallback signature — `(event: KeyboardEvent, context?: unknown) => void` — so
-   * consumers can pass toHotkeyBindings() directly to useHotkeys() without a tsc error.
-   * The implementations produced by toHotkeyBindings() only use the zero-arg form internally.
-   */
-  callback: (event: KeyboardEvent, context?: unknown) => void
-}
-
-// ── toSpotlightActions ────────────────────────────────────────────────────────
-
-/**
- * Project the active command registry into a Mantine Spotlight `SpotlightActionData[]` array.
- * Commands where `when()` returns false are excluded from the list.
- *
- * Reads a one-time snapshot of the runtime command stash at call time — commands registered AFTER
- * this is called (lazy/code-split) won't appear. Register all commands at module load before
- * mounting <BasaltOverlays>.
- *
- * When onTrigger is provided it is called INSTEAD OF runCommand (put runCommand(id) inside your
- * onTrigger if you want it to fire); without onTrigger, runCommand(id) fires directly.
- *
- * @example
- * // Close the palette then run the command:
- * const actions = toSpotlightActions((id) => { spotlight.close(); runCommand(id) })
- *
- * // Default: just runs the command directly
- * const actions = toSpotlightActions()
- */
-export function toSpotlightActions(onTrigger?: (id: CommandId) => void): SpotlightActionData[] {
-  const cmds = getActiveCommands()
-  const actions: SpotlightActionData[] = []
-
-  for (const [id, cmd] of Object.entries(cmds)) {
-    // Skip commands gated behind a false when() predicate
-    if (cmd.when !== undefined && !cmd.when()) continue
-
-    const action: SpotlightActionData = {
-      id,
-      label: cmd.label,
-      leftSection: cmd.icon,
-      keywords: [cmd.group ?? '', id].join(' ').trim(),
-      onClick: () => {
-        // id is the actual stash key (string from Object.entries), narrowed to CommandId for the typed callback
-        if (onTrigger !== undefined) {
-          onTrigger(id as CommandId)
-        } else {
-          runCommand(id as CommandId)
-        }
-      },
-    }
-    if (cmd.shortcut !== undefined) {
-      // detectMac() is SSR-safe (returns false when navigator is unavailable)
-      action.description = formatShortcutDisplay(cmd.shortcut, detectMac())
-    }
-    if (cmd.group !== undefined) action.group = cmd.group
-    actions.push(action)
-  }
-
-  return actions
-}
-
-// ── toRouteActions ────────────────────────────────────────────────────────────
-
-export type RouteActionItem = {
-  label: string
-  href?: string
-  icon?: ReactNode
-  disabled?: boolean
-  children?: RouteActionItem[]
-}
-
-export type RouteActionSection = {
-  /** Section label — the root segment of each item's breadcrumb-trail label. */
-  label: string
-  /** Section icon — inherited as the leftSection by items/children that have no icon of their own. */
-  icon?: ReactNode
-  items: RouteActionItem[]
-}
-
-export type ToRouteActionsOptions = {
-  /** Navigate to a route href — e.g. `(href) => router.navigate({ to: href })`. */
-  onNavigate: (href: string) => void
-  /** Prefix for generated action ids so they never collide with command ids. Default 'route:'. */
-  idPrefix?: string
-  /**
-   * Spotlight group for every produced action (e.g. 'Pages'). Omit for an ungrouped, flat list.
-   * Unlike the nav section (which becomes part of the breadcrumb label), this is a single kind
-   * bucket across all routes.
-   */
-  group?: string
-  /** Separator between breadcrumb segments in the action label. Default ' › '. */
-  separator?: string
-  /**
-   * Node rendered on the right of every action — e.g. a kind badge (`<Badge>Page</Badge>`). Lets
-   * the palette distinguish pages from commands at a glance regardless of grouping.
-   */
-  rightSection?: ReactNode
-}
-
-/**
- * Project a nav model (sections → items → nested children) into Mantine Spotlight
- * page-navigation actions. Pass the result to <BasaltOverlays spotlightActions={…}> so the palette
- * lists Pages alongside Commands.
- *
- * Each action's label is the full breadcrumb trail from the section down to the item
- * (e.g. `Overview › Dashboard › Sessions`), so a result is self-describing. Disabled items and
- * items without an href are skipped. An item/child without its own icon inherits the nearest
- * ancestor's (section → parent item), so sub-routes carry the parent's icon in the palette while
- * staying icon-less in a sidebar that renders them against a rail. Optionally assign one `group`
- * (a kind bucket like 'Pages') and a `rightSection` (a kind badge) to every action. Reads a static
- * snapshot — routes are static, so build it once.
- *
- * Structurally compatible with the shell's SidebarSection[] — pass your existing nav model directly.
+ * projectors — project the active command registry into the shortcut reference list that
+ * `ShortcutsHelp` renders. Reads the runtime stash (populated by `defineCommands`), not the
+ * type-erased `BasaltRegister` slot; safe to call before any commands are registered.
  */
-export function toRouteActions(
-  sections: RouteActionSection[],
-  options: ToRouteActionsOptions,
-): SpotlightActionData[] {
-  const { onNavigate, idPrefix = 'route:', separator = ' › ', group, rightSection } = options
-  const actions: SpotlightActionData[] = []
-
-  const walk = (items: RouteActionItem[], trail: string[], inheritedIcon?: ReactNode): void => {
-    for (const item of items) {
-      const itemTrail = [...trail, item.label]
-      const icon = item.icon ?? inheritedIcon
-      if (!item.disabled && item.href !== undefined) {
-        const href = item.href
-        const action: SpotlightActionData = {
-          id: `${idPrefix}${href}`,
-          label: itemTrail.join(separator),
-          leftSection: icon,
-          keywords: [...itemTrail, href].join(' '),
-          onClick: () => onNavigate(href),
-        }
-        if (group !== undefined) action.group = group
-        if (rightSection !== undefined) action.rightSection = rightSection
-        actions.push(action)
-      }
-      if (item.children !== undefined) walk(item.children, itemTrail, icon)
-    }
-  }
-
-  for (const section of sections) walk(section.items, [section.label], section.icon)
-  return actions
-}
+import { getActiveCommands } from './define-commands'
 
 // ── ShortcutEntry ─────────────────────────────────────────────────────────────
 
@@ -198,7 +24,7 @@ export type ShortcutEntry = {
  *
  * Reads a one-time snapshot of the runtime command stash at call time — commands registered AFTER
  * this is called (lazy/code-split) won't appear. Register all commands at module load before
- * mounting <BasaltOverlays>.
+ * rendering `ShortcutsHelp`.
  *
  * @example
  * const shortcuts = toShortcutList()
@@ -219,49 +45,3 @@ export function toShortcutList(): ShortcutEntry[] {
 
   return result
 }
-
-// ── toHotkeyBindings ──────────────────────────────────────────────────────────
-
-/**
- * Project the active command registry into a `UseHotkeyDefinition[]` bindings array — the exact
- * shape accepted by `useHotkeys` from `@tanstack/react-hotkeys`.
- *
- * Commands without a `shortcut` field are skipped. Commands where `when()` returns false are
- * included in the bindings but their callback is a no-op (the command is gated at call time, not
- * at registration time — this avoids hook-count churn when `when()` toggles).
- *
- * Reads a one-time snapshot of the runtime command stash.
- *
- * NOTE: the built-in useCommandHotkeys() does NOT call this function. It uses the imperative
- * getHotkeyManager() API from @tanstack/react-hotkeys directly (register/unregister per
- * mount/unmount cycle). toHotkeyBindings() is an opt-in convenience projector for consumers
- * who want to drive their own useHotkeys([...]) call — it is not on the path that
- * useCommandHotkeys() takes.
- *
- * @example
- * import { useHotkeys } from '@tanstack/react-hotkeys'
- * import { toHotkeyBindings } from 'basalt-ui/commands'
- *
- * function MyHotkeys() {
- *   useHotkeys(toHotkeyBindings())
- * }
- */
-export function toHotkeyBindings(): HotkeyBinding[] {
-  const cmds = getActiveCommands()
-  const bindings: HotkeyBinding[] = []
-
-  for (const [id, cmd] of Object.entries(cmds)) {
-    if (cmd.shortcut === undefined) continue
-
-    bindings.push({
-      hotkey: cmd.shortcut,
-      callback: () => {
-        // Respect the when() gate at execution time (not registration time)
-        if (cmd.when !== undefined && !cmd.when()) return
-        void runCommand(id as CommandId)
-      },
-    })
-  }
-
-  return bindings
-}

package/src/commands/shell-bridge.ts

@@ -15,7 +15,7 @@
  *
  * basalt registers BOTH setters itself — `BasaltProvider` calls {@link registerColorSchemeSetter}
  * from inside `MantineProvider` (`provider/index.tsx`'s `BasaltBridge`), `BasaltShell` calls
- * {@link registerSidebarToggle} (`shell/index.tsx`'s `ShellFrame`) — so a consumer's own
+ * {@link registerSidebarToggle} (`shell/index.tsx`'s `ShellBody`) — so a consumer's own
  * `commands.tsx` needs no `__root.tsx` wiring at all, unlike argo's hand-rolled version: mount
  * `BasaltProvider`/`BasaltShell` once, and `setColorScheme`/`toggleSidebar` just work.
  *
@@ -50,8 +50,8 @@ export function registerSidebarToggle(toggle: SidebarToggle | null): void {
 
 /**
  * Set the color scheme from outside the React tree. A no-op (with a dev-only console warning)
- * when no `BasaltProvider` is mounted yet — the same "not wired" shape `runCommand`/
- * `overlays.open` already use for an unregistered id.
+ * when no `BasaltProvider` is mounted yet — the same "not wired" shape
+ * `overlays.open` already uses for an unregistered id.
  *
  * @example
  * setColorScheme('dark')
@@ -59,7 +59,7 @@ export function registerSidebarToggle(toggle: SidebarToggle | null): void {
 export function setColorScheme(scheme: ColorScheme): void {
   if (colorSchemeSetterRef === null) {
     if (process.env['NODE_ENV'] !== 'production') {
-      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      // eslint-disable-next-line no-console -- dev-only diagnostic
       console.warn('[basalt] setColorScheme: no BasaltProvider is mounted yet')
     }
     return
@@ -77,7 +77,7 @@ export function setColorScheme(scheme: ColorScheme): void {
 export function toggleSidebar(): void {
   if (sidebarToggleRef === null) {
     if (process.env['NODE_ENV'] !== 'production') {
-      // eslint-disable-next-line no-console -- dev-only diagnostic, mirrors runCommand's own
+      // eslint-disable-next-line no-console -- dev-only diagnostic
       console.warn('[basalt] toggleSidebar: no BasaltShell is mounted yet')
     }
     return

package/src/commands/shortcut-format.ts

@@ -18,7 +18,8 @@
 /**
  * Returns true when running on macOS. SSR-safe — returns false when navigator is unavailable.
  * Uses userAgentData.platform when available; falls back to userAgent string regex.
- * Never call during render — use only inside useEffect to avoid hydration mismatches.
+ * Reads the client's platform, so during SSR/hydration render it through `useSyncExternalStore`
+ * with a `false` server snapshot (as `ShortcutsHelp` does) rather than calling it bare in render.
  */
 export function detectMac(): boolean {
   if (typeof navigator === 'undefined') return false
@@ -64,14 +65,14 @@ function plainKey(key: string): string {
 /**
  * Convert a shortcut string to a list of Kbd-friendly tokens.
  * 'Mod+S' → ['⌘', 'S'] (mac) or ['Ctrl', 'S'] (other).
- * 'Shift+Mod+P' → ['⇧', '⌘', 'P'] (mac) or ['Shift', 'Ctrl', 'P'] (other).
+ * 'Mod+Shift+P' → ['⌘', '⇧', 'P'] (mac) or ['Ctrl', 'Shift', 'P'] (other).
  * Named keys read as glyphs on mac and Title-case words elsewhere:
  * 'Mod+Backspace' → ['⌘', '⌫'] (mac) or ['Ctrl', 'Backspace'] (other).
  * isMac is the post-mount platform flag; defaults false on SSR / first render.
  *
  * @example
  * parseShortcut('Mod+S', true)         // ['⌘', 'S']
- * parseShortcut('Shift+Mod+P', false)  // ['Shift', 'Ctrl', 'P']
+ * parseShortcut('Mod+Shift+P', false)  // ['Ctrl', 'Shift', 'P']
  * parseShortcut('ArrowLeft', true)     // ['←']
  */
 export function parseShortcut(shortcut: string, isMac: boolean): string[] {
@@ -114,7 +115,7 @@ export function parseShortcut(shortcut: string, isMac: boolean): string[] {
  * formatShortcutDisplay('Mod+S', true)          // '⌘S'
  * formatShortcutDisplay('Mod+Backspace', true)  // '⌘⌫'
  * formatShortcutDisplay('Mod+S', false)         // 'Ctrl+S'
- * formatShortcutDisplay('Shift+Mod+P', true)    // '⇧⌘P'
+ * formatShortcutDisplay('Mod+Shift+P', true)    // '⌘⇧P'
  */
 export function formatShortcutDisplay(shortcut: string, isMac: boolean): string {
   const tokens = parseShortcut(shortcut, isMac)

package/src/common/errors.ts

@@ -3,7 +3,7 @@
  * here, so the prefix, the `Component: …` shape and the em-dash-then-remedy rhythm are one decision
  * instead of 60. It is the generalisation of `assertQueryStateLike`, which was the ONLY component
  * in the library naming itself in its own failure (isomorphic finding F-ERR-1: the other 54 fail as
- * raw `TypeError`s that `BasaltErrorBoundary` swallows into a blank subtree).
+ * raw `TypeError`s that `RootBoundary` swallows into a blank subtree).
  *
  * Every builder returns a string; nothing here throws or logs. The caller decides which it is —
  * `assertRequiredProps` throws, `useValidateProps` logs, the mount guards log.
@@ -62,8 +62,8 @@ export function deprecatedProp(
  *
  * Distinct from {@link deprecatedProp} (still read, going away) and {@link oneOf} (read, and the
  * value is out of range): this one renders something the caller did not ask for and nothing in the
- * type system, the linter or the console says so. `ChartFrame`'s `height` under `fill` is the
- * reference case — meteo passed both for the life of the file and never learnt that eight height
+ * type system, the linter or the console says so. A 1.x chart's `height` under `fill` was the
+ * reference case — weatherorb passed both for the life of the file and never learnt that eight height
  * constants and a whole `compact` branch changed no pixel.
  */
 export function ignoredProp(component: string, prop: string, because: string): string {

package/src/common/use-measured-widths.ts

@@ -44,11 +44,14 @@ export function useMeasuredWidths(options: UseMeasuredWidthsOptions): UseMeasure
 
   // Read through refs so a fresh closure each render does not re-run the effect.
   const resolveRef = useRef(resolveRoot)
-  resolveRef.current = resolveRoot
   const extraRef = useRef(extra)
-  extraRef.current = extra
   const onMeasureRef = useRef(onMeasure)
-  onMeasureRef.current = onMeasure
+  // Declared before the measuring effect, so the refs are current by the time it reads them.
+  useIsomorphicLayoutEffect(() => {
+    resolveRef.current = resolveRoot
+    extraRef.current = extra
+    onMeasureRef.current = onMeasure
+  })
 
   useIsomorphicLayoutEffect(() => {
     if (signatureRef.current !== signature) {

package/src/common/validate.ts

@@ -60,7 +60,7 @@ export function useValidateProps(
 /**
  * The same once-per-`(component, message)` dev diagnostic {@link useValidateProps} logs, for a
  * caller that already owns the effect a check would otherwise race — a decision made synchronously
- * inside a `useLayoutEffect` (e.g. `ChartFrame`'s header-slot claim, P2-9) has no business waiting a
+ * inside a `useLayoutEffect` (e.g. a card's header-slot claim, P2-9) has no business waiting a
  * further render for a REACTIVE check on state that effect itself just set: that state update lags
  * one commit behind the decision, and a passive-effect check racing it warns about instances that
  * are about to win in the very next render.
@@ -83,7 +83,7 @@ export function resetValidatedProps(): void {
  *
  * This is the F-ERR-1 remedy, and the reason it is not dev-gated: the component was going to crash
  * either way (`undefined is not an object (evaluating 'field.use')`), so the only thing in question
- * is whether the stack reaching `BasaltErrorBoundary` names the component and the prop. It does
+ * is whether the stack reaching `RootBoundary` names the component and the prop. It does
  * now. A prop that is merely questionable belongs in `useValidateProps`, not here.
  *
  * @example

package/src/content/article-layout.tsx

@@ -129,9 +129,9 @@ export function ArticleLayout({
   // THIS component, not the Popover, so crossing back below the breakpoint would otherwise remount
   // it already open with no user action. Adjusted during render (React's own pattern for resetting
   // state when a derived value changes), not an effect, so there is no open-then-close flash.
-  const prevShowTocRailRef = useRef(showTocRail)
-  if (prevShowTocRailRef.current !== showTocRail) {
-    prevShowTocRailRef.current = showTocRail
+  const [prevShowTocRail, setPrevShowTocRail] = useState(showTocRail)
+  if (prevShowTocRail !== showTocRail) {
+    setPrevShowTocRail(showTocRail)
     if (tocOpen) setTocOpen(false)
   }
 
@@ -167,41 +167,40 @@ export function ArticleLayout({
         </div>
       )}
 
-      {toc &&
-        !showTocRail && (
-          // `.tocTrigger`'s `grid-row: 2` (article-layout.module.css) is EXPLICIT, matching
-          // `.content`'s own row — not left to CSS Grid's auto-placement, which used to land this
-          // in its own row below the content instead of at its top (both are `grid-column: 1`, and
-          // the auto-placement cursor moves past row 2 once `.content` claims it).
-          <Popover
-            opened={tocOpen}
-            onChange={setTocOpen}
-            onDismiss={() => setTocOpen(false)}
-            position="bottom-end"
-            withinPortal
-            shadow="md"
-            radius="sm"
-            trapFocus
-          >
-            <Popover.Target>
-              <Button
-                variant="subtle"
-                color="gray"
-                size="compact-xs"
-                className={classes.tocTrigger}
-                classNames={{ label: classes.tocTriggerLabel }}
-                onClick={() => setTocOpen((current) => !current)}
-              >
-                On this page
-              </Button>
-            </Popover.Target>
-            <Popover.Dropdown className={classes.tocDropdown}>
-              <ScrollArea.Autosize mah="calc(100vh - 108px)" type="hover">
-                <TableOfContents containerRef={articleRef} onNavigate={() => setTocOpen(false)} />
-              </ScrollArea.Autosize>
-            </Popover.Dropdown>
-          </Popover>
-        )}
+      {toc && !showTocRail && (
+        // `.tocTrigger`'s `grid-row: 2` (article-layout.module.css) is EXPLICIT, matching
+        // `.content`'s own row — not left to CSS Grid's auto-placement, which used to land this
+        // in its own row below the content instead of at its top (both are `grid-column: 1`, and
+        // the auto-placement cursor moves past row 2 once `.content` claims it).
+        <Popover
+          opened={tocOpen}
+          onChange={setTocOpen}
+          onDismiss={() => setTocOpen(false)}
+          position="bottom-end"
+          withinPortal
+          shadow="md"
+          radius="sm"
+          trapFocus
+        >
+          <Popover.Target>
+            <Button
+              variant="subtle"
+              color="gray"
+              size="compact-xs"
+              className={classes.tocTrigger}
+              classNames={{ label: classes.tocTriggerLabel }}
+              onClick={() => setTocOpen((current) => !current)}
+            >
+              On this page
+            </Button>
+          </Popover.Target>
+          <Popover.Dropdown className={classes.tocDropdown}>
+            <ScrollArea.Autosize mah="calc(100vh - 108px)" type="hover">
+              <TableOfContents containerRef={articleRef} onNavigate={() => setTocOpen(false)} />
+            </ScrollArea.Autosize>
+          </Popover.Dropdown>
+        </Popover>
+      )}
 
       {(prev !== undefined || next !== undefined) && (
         <footer className={classes.footer}>

package/src/content/article-model.ts

@@ -1,87 +1,4 @@
-/**
- * Article — the structured data model behind `ArticleCard`/`ArticleLayout` (docs/CONTENT-SPEC.md).
- * Pure data + pure functions: no React, no `@mantine/*`. Sortable/filterable article metadata
- * replaces the old preformatted `meta` string so a consumer can build a filter bar or a Spotlight
- * projector on top of it (both are a later stage — this module only ships the model).
- */
-
-export type Article<C extends string = string, T extends string = string> = {
-  readonly slug: string
-  readonly title: string
-  readonly description?: string
-  /** ISO 8601 — sortable. Articles without a date sort last regardless of `ArticleOrder`. */
-  readonly date?: string
-  readonly category?: C
-  readonly tags?: readonly T[]
-  /** Minutes. */
-  readonly readingTime?: number
-}
-
-export type ArticleOrder = 'date-desc' | 'date-asc' | 'title'
-
-/**
- * Sorts articles. Pure — never mutates `articles`, always returns a new array.
- *
- * - `'date-desc'` (default) / `'date-asc'` — compares `date` lexicographically (ISO 8601 sorts
- *   chronologically as a string, so no `Date` parsing is needed). Articles missing a `date` sort
- *   LAST in both directions — a missing date is not "oldest", it's unranked.
- * - `'title'` — `localeCompare` with a PINNED `'en-US'` locale, not the runtime default, so sort
- *   order doesn't drift between environments.
- *
- * Stable: articles that compare equal keep their input order (native `toSorted` is a stable sort).
- */
-export function sortArticles<A extends Article>(
-  articles: readonly A[],
-  order: ArticleOrder = 'date-desc',
-): readonly A[] {
-  if (order === 'title') {
-    return articles.toSorted((a, b) => a.title.localeCompare(b.title, 'en-US'))
-  }
-
-  const direction = order === 'date-asc' ? 1 : -1
-  return articles.toSorted((a, b) => {
-    if (a.date === undefined && b.date === undefined) return 0
-    if (a.date === undefined) return 1
-    if (b.date === undefined) return -1
-    if (a.date === b.date) return 0
-    return a.date < b.date ? -direction : direction
-  })
-}
-
-export type ArticleFilterQuery = {
-  readonly category?: string
-  readonly tags?: readonly string[]
-}
-
-/**
- * Filters articles. Pure — never mutates `articles`.
- *
- * - `category` — exact match. `undefined`/`''` applies no constraint.
- * - `tags` — ANY-OF (OR): an article matches if it carries at least one queried tag.
- *   `undefined`/`[]` applies no constraint.
- * - Both axes given: AND between category and tags, OR within tags — matches the multi-facet
- *   `filterFn` semantics in `data/data-table.tsx`.
- *
- * An empty query (`{}`, or a query where both axes are unset) returns `articles` unchanged.
- */
-export function filterArticles<A extends Article>(
-  articles: readonly A[],
-  query: ArticleFilterQuery,
-): readonly A[] {
-  const { category, tags } = query
-  const hasCategory = category !== undefined && category !== ''
-  const hasTags = tags !== undefined && tags.length > 0
-
-  if (!hasCategory && !hasTags) return articles
-
-  return articles.filter((article) => {
-    if (hasCategory && article.category !== category) return false
-    if (hasTags && tags !== undefined && !tags.some((tag) => article.tags?.includes(tag))) {
-      return false
-    }
-    return true
-  })
-}
+/** Article date formatting for `ArticleLayout` — pure, no React, no `@mantine/*`. */
 
 /**
  * Formats an ISO 8601 date string via `Intl.DateTimeFormat` → `'Jul 16, 2026'`.

package/src/content/index.ts

@@ -1,91 +1,20 @@
 /**
- * `basalt-ui/content` — the content/prose surface (docs/CONTENT-SPEC.md).
+ * `basalt-ui/content` — prose, markdown and the docs-page frame (docs/CONTENT-SPEC.md).
  *
- * Mantine-coupled (like `./forms`/`./notifications`/`./data`): prose typography, a shiki-backed
- * code block (optional peer, lazy singleton), a semantic callout, a scroll-spy TOC rail, a
- * scroll-driven reading-progress bar, a streaming-aware `Markdown` renderer (react-markdown +
- * remark-gfm + rehype-sanitize + remend, all optional peers) with its fence-renderer registry,
- * `MermaidDiagram` (beautiful-mermaid, optional peer), the MDX
- * component map, the docs-page frame (`ArticleLayout`), overview cards (`ArticleCard`/
- * `ArticleGrid`), the contextual-help drawer (`GuideLink`/`GuideDrawer`), and a re-export of the
- * three `basalt-ui/controls` filters an article list needs (`FilterSet`/`ViewTabs`/
- * `MultiSelectFilter`, which replaced the controlled `ArticleFilterBar`). See
- * `agent/rules/basalt-content.md` for the full doctrine + the content-collections recipe.
+ * Mantine-coupled. `Markdown` renders code and mermaid fences itself (`CodeBlock` and
+ * `MermaidDiagram` are internal); `fenceRenderers` is the extension point. Optional peers
+ * (shiki, react-markdown stack, beautiful-mermaid) load lazily; the sanitizer is always on.
  */
-export { Prose } from './prose'
-export type { ProseDensity, ProseProps } from './prose'
-
-export { CodeBlock } from './code-block'
-export type { CodeBlockProps } from './code-block'
 
+export { Prose } from './prose'
 export { Callout } from './callout'
-export type { CalloutKind, CalloutProps } from './callout'
-
+export type { CalloutKind } from './callout'
 export { TableOfContents } from './toc'
-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'
-
-export { HeadingAnchor } from './heading-anchor'
-export type { HeadingAnchorProps } from './heading-anchor'
-
+export type { TocItem } from './toc'
 export { Markdown, settledOnly } from './markdown'
-export type {
-  FenceRenderContext,
-  FenceRenderer,
-  FenceRenderers,
-  MarkdownComponents,
-  MarkdownContentTrust,
-  MarkdownProps,
-} from './markdown'
-
-export { BASALT_SANITIZE_SCHEMA, mergeSanitizeSchema } from './sanitize'
-export type {
-  SanitizePropertyDefinition,
-  SanitizeSchema,
-  SanitizeSchemaExtension,
-  SanitizeSchemaInput,
-} from './sanitize'
-
-export { MermaidDiagram } from './mermaid'
-export type { MermaidDiagramProps } from './mermaid'
-
-export { blockSplit } from './block-split'
-
-export { createMdxComponents, mdxComponents } from './mdx'
-export type { CreateMdxComponentsOptions } from './mdx'
-
+export type { FenceRenderer, FenceRenderers, MarkdownComponents, MarkdownProps } from './markdown'
+export { mergeSanitizeSchema } from './sanitize'
+export type { SanitizeSchemaExtension, SanitizeSchemaInput } from './sanitize'
 export { ArticleLayout } from './article-layout'
-export type { ArticleLayoutMeta, ArticleLayoutProps, ArticleNavTarget } from './article-layout'
-
-export { ArticleCard, ArticleGrid } from './article-card'
-export type { ArticleCardProps, ArticleGridProps } from './article-card'
-
-export { filterArticles, formatArticleDate, sortArticles } from './article-model'
-export type { Article, ArticleFilterQuery, ArticleOrder } from './article-model'
-
-export { toArticleActions } from './article-actions'
-export type { ToArticleActionsOptions } from './article-actions'
-
-// The article filter UI is no longer content's own: `ArticleFilterBar` (controlled,
-// `value`/`onChange`, its own responsive twin) was replaced by the store-bound controls of
-// `basalt-ui/controls` (`docs/CONTROLS-SPEC.md` §3, C2/C9). Re-exported here — not merely
-// documented as moved — so a content-only consumer that never imports `./controls` still gets the
-// three it needs from the surface it was already using. Both spellings are the same module: one
-// component, two import paths.
-export { FilterSet, MultiSelectFilter, ViewTabs } from '../controls'
-export type {
-  FilterSetProps,
-  MultiSelectFilterProps,
-  ViewTabsOption,
-  ViewTabsProps,
-} from '../controls'
-
-export { GuideDrawer, GuideLink } from './guide'
-export type { GuideDrawerProps, GuideLinkProps } from './guide'
+export type { ArticleLayoutMeta } from './article-layout'
+export { GuideLink } from './guide'