basalt-ui 1.31.0 → 1.32.0

package/src/notifications/center.tsx

@@ -205,6 +205,9 @@ export function NotificationCenter({ maxHeight = 320, className, style }: Notifi
       </Group>
 
       {/* View switch */}
+      {/* theme-allow control-outside-home — the center's own inbox/all view, rendered inside
+          `NotificationBell`'s Popover (an overlay, a declared non-home the AST cannot see across
+          the component boundary). */}
       <SegmentedControl
         fullWidth
         size="xs"

package/src/provider/index.tsx

@@ -242,8 +242,13 @@ export function composeInjectedCss(
 
 // ── Host attribute ────────────────────────────────────────────────────────────────────────────────
 
-/** Mount count backing `useHostAttribute`'s ref-counted removal — see that function's doc. */
-let hostAttributeCount = 0
+/** A module-level mount count across every `BasaltProvider`; each call returns the new count. */
+function createMountCounter(): { mount: () => number; unmount: () => number } {
+  let count = 0
+  return { mount: () => ++count, unmount: () => --count }
+}
+
+const hostAttributeMounts = createMountCounter()
 
 /**
  * `data-basalt-host` on `<html>` — the one place a `display-mode` query is read; CSS keys off it.
@@ -261,17 +266,16 @@ export function useHostAttribute(): void {
     document.documentElement.setAttribute('data-basalt-host', isPwa ? 'pwa' : 'web')
   }, [isPwa])
 
-  // Ref-counted across every mounted `BasaltProvider` — mirrors `useDuplicateProviderGuard`'s own
-  // module-level counter just below. A second provider (a nested route wrapping its own, two trees
-  // on one page) unmounting must not rip the attribute out from under a first one still mounted;
-  // only the LAST unmount removes it. Deliberately a SEPARATE effect from the one above: sharing one
-  // effect keyed on `[isPwa]` would decrement (and possibly zero out) this counter on every
-  // `isPwa` change, not only on a genuine unmount.
+  // Ref-counted across every mounted `BasaltProvider`: a second provider (a nested route wrapping
+  // its own, two trees on one page) unmounting must not rip the attribute out from under a first
+  // one still mounted; only the LAST unmount removes it. Deliberately a SEPARATE effect from the one
+  // above: sharing one keyed on `[isPwa]` would decrement this counter on every `isPwa` change.
   useIsomorphicLayoutEffect(() => {
-    hostAttributeCount++
+    hostAttributeMounts.mount()
     return () => {
-      hostAttributeCount--
-      if (hostAttributeCount === 0) document.documentElement.removeAttribute('data-basalt-host')
+      if (hostAttributeMounts.unmount() === 0) {
+        document.documentElement.removeAttribute('data-basalt-host')
+      }
     }
   }, [])
 }
@@ -374,21 +378,18 @@ function BasaltBridge({
  * misuse, not a false positive from React 18 StrictMode's double-invoke (that mounts/unmounts the
  * SAME instance in sequence, so the count returns to 0 before a second instance could ever exist).
  */
-let mountedProviderCount = 0
+const providerMounts = createMountCounter()
 
 function useDuplicateProviderGuard(): void {
   useEffect(() => {
-    mountedProviderCount++
-    if (mountedProviderCount > 1 && isDev()) {
+    if (providerMounts.mount() > 1 && isDev()) {
       console.warn(
         '[basalt] BasaltProvider: more than one instance is mounted at once — nested/duplicate ' +
           'BasaltProviders double-mount MantineProvider, the palette <style> and ' +
           'ConnectivityProvider. Mount exactly one, at the app root.',
       )
     }
-    return () => {
-      mountedProviderCount--
-    }
+    return () => void providerMounts.unmount()
   }, [])
 }
 

package/src/shell/aside-docking.ts

@@ -0,0 +1,54 @@
+/**
+ * Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — the pure decision `ShellFrame`
+ * sizes `AppShell.Aside` from. An open aside pushes main only in `expanded` while main keeps
+ * `MAIN_MIN_WIDTH` beside the navbar; otherwise the region reserves just its rail and an open panel
+ * overlays main. Unclaimed, the region is zero-wide.
+ */
+import { toEm } from '../tokens/size-classes'
+import type { SizeClass } from './use-size-class'
+
+/**
+ * Main keeps at least this much width, or an open aside overlays it instead of docking. Not
+ * derived from a token: it is the readable floor for a page body, independent of density.
+ */
+const MAIN_MIN_WIDTH = 720
+
+export type AsideDockingInput = {
+  claimed: boolean
+  folded: boolean
+  sizeClass: SizeClass
+  /** The `asideDockQuery` media query's result. */
+  roomToDock: boolean
+  asideWidth: number
+  asideRailWidth: number
+}
+
+export type AsideDocking = {
+  /** An open aside pushes main rather than overlaying it. */
+  docks: boolean
+  /** An open aside renders over main (reserving only its rail). */
+  overlay: boolean
+  /** The width `AppShell` reserves for the region. */
+  width: number
+}
+
+/** The `min-width` query that holds while navbar + open aside + `MAIN_MIN_WIDTH` fit side by side. */
+export function asideDockQuery(input: { navbarWidth: number; asideWidth: number }): string {
+  return `(min-width: ${toEm(input.navbarWidth + input.asideWidth + MAIN_MIN_WIDTH)})`
+}
+
+/**
+ * The room-to-dock query's SSR/no-`matchMedia` fallback — an `'expanded'` `sizeClassHint` means the
+ * server already believes there is room, matching `useSizeClass`'s own hint-seeded guard
+ * (`use-size-class.ts`), so the first client paint doesn't fold a default-open aside for one commit.
+ */
+export function roomToDockServerFallback(sizeClassHint: SizeClass | undefined): boolean {
+  return sizeClassHint === 'expanded'
+}
+
+export function resolveAsideDocking(input: AsideDockingInput): AsideDocking {
+  const docks = input.sizeClass === 'expanded' && input.roomToDock
+  const open = input.claimed && !input.folded
+  const reserved = open && docks ? input.asideWidth : input.asideRailWidth
+  return { docks, overlay: open && !docks, width: input.claimed ? reserved : 0 }
+}

package/src/shell/index.tsx

@@ -34,6 +34,7 @@ import { blockRowCount, projectMobileNav } from './mobile-nav-model'
 import { AppBreadcrumbs } from './app-breadcrumbs'
 import { PageBarBandOutlet, PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
 import { AsideDocksContext, AsideOutlet, AsideProvider, useAsideRegion } from './page-aside'
+import { asideDockQuery, resolveAsideDocking, roomToDockServerFallback } from './aside-docking'
 import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from '../controls/actions'
 import type { GlobalAction } from '../controls/actions'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -47,9 +48,7 @@ import type {
 } from './nav-types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedStore } from '../state/persisted'
-import { toEm } from '../tokens/size-classes'
 import { SizeClassHintContext, useSizeClass } from './use-size-class'
-import type { SizeClass } from './use-size-class'
 import brandClasses from './app-brand.module.css'
 import headerClasses from './app-header.module.css'
 import mainClasses from './app-main.module.css'
@@ -303,25 +302,6 @@ function collapseStore(key: string): CollapseStore {
   return store
 }
 
-/**
- * Main keeps at least this much width, or an open aside overlays it instead of docking. Not
- * derived from a token: it is the readable floor for a page body, independent of density.
- */
-const MAIN_MIN_WIDTH = 720
-
-/**
- * The room-to-dock `min-width` query's SSR/no-`matchMedia` fallback — an `'expanded'`
- * `sizeClassHint` means the server already believes there is room, matching `useSizeClass`'s own
- * hint-seeded guard one level up (`use-size-class.ts`). Extracted as its own pure function (rather
- * than the inline `sizeClassHint === 'expanded'` it replaces) purely so `index.test.tsx` can pin it
- * without needing to render `BasaltShell` through a real SSR pass — `AppShell`'s + `PageAside`'s own
- * effects/refs/portals make that path unobservable through rendered markup, and the previous
- * hardcoded `false` fallback here shipped with no test at all for exactly that reason.
- */
-export function roomToDockServerFallback(sizeClassHint: SizeClass | undefined): boolean {
-  return sizeClassHint === 'expanded'
-}
-
 /**
  * The shell's two page-level regions are providers, and both wrap the frame rather than living
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
@@ -395,25 +375,23 @@ function ShellFrame({
   const isCollapseControlled = collapsedProp !== undefined
   const uncontrolledCollapsed = collapseIsSet ? storedCollapsed : sizeClass === 'medium'
   const collapsed = isCollapseControlled ? collapsedProp : uncontrolledCollapsed
-  // Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes): an open aside pushes main only in
-  // `expanded` while main keeps `MAIN_MIN_WIDTH` beside this navbar; otherwise the region reserves
-  // just its rail and an open panel overlays main. Provided through `AsideDocksContext` in the SAME
-  // render, so `PageAside` defaults its fold from the right value on its first pass.
+  // Aside docking (`aside-docking.ts`), provided through `AsideDocksContext` in the SAME render so
+  // `PageAside` defaults its fold from the right value on its first pass.
   const navbarWidth = collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth
-  // The SSR/first-paint fallback mirrors `useSizeClass`'s own hint-seeded guard: an `expanded` hint
-  // from `<BasaltProvider sizeClassHint>` means the server already believes there is room to dock, so
-  // the first client paint agrees instead of defaulting to "cannot dock" and folding a default-open
-  // aside for one commit.
   const sizeClassHint = useContext(SizeClassHintContext)
   const roomToDock = useMediaQuery(
-    `(min-width: ${toEm(navbarWidth + step.appShellAsideWidth + MAIN_MIN_WIDTH)})`,
+    asideDockQuery({ navbarWidth, asideWidth: step.appShellAsideWidth }),
     roomToDockServerFallback(sizeClassHint),
   )
-  const docks = sizeClass === 'expanded' && roomToDock
-  const asideOpen = aside.claimed && !aside.folded
-  const asideOverlay = asideOpen && !docks
-  const asideReserved = asideOpen && docks ? step.appShellAsideWidth : step.appShellAsideRailWidth
-  const asideWidth = aside.claimed ? asideReserved : 0
+  const docking = resolveAsideDocking({
+    claimed: aside.claimed,
+    folded: aside.folded,
+    sizeClass,
+    roomToDock,
+    asideWidth: step.appShellAsideWidth,
+    asideRailWidth: step.appShellAsideRailWidth,
+  })
+  const asideOverlay = docking.overlay
   // Keyboard escape hatch for the overlay form only — the docked form never blocks content, so
   // there is nothing to escape out of. `requestClose` is a stable callback from `AsideProvider`
   // (destructured, not read as `aside.requestClose`, so the effect deps name it directly rather
@@ -460,7 +438,7 @@ function ShellFrame({
   )
 
   return (
-    <AsideDocksContext.Provider value={docks}>
+    <AsideDocksContext.Provider value={docking.docks}>
       <AppShell
         h="100dvh"
         // Mantine's DEFAULT layout, not `alt`: the header spans the full viewport width on top and
@@ -484,7 +462,7 @@ function ShellFrame({
         // prop for it on purpose; the ROUTE decides, the same way it decides its page bar.
         aside={{
           // An overlay reserves the rail only — `<AppShell.Aside>` below widens itself over main.
-          width: asideWidth,
+          width: docking.width,
           breakpoint: 'sm',
           // Below `sm` there is no region at all — `PageAside` renders its content in the page
           // flow instead, one node, no responsive twin (law C9).

package/src/shell/use-breakpoint.ts

@@ -1,5 +1,5 @@
 /**
- * `useBreakpoint` — DEPRECATED (on notice in `MIGRATING.md`, removed next minor): use
+ * `useBreakpoint` — DEPRECATED (on notice in `MIGRATING.md`, removed in 1.33.0): use
  * `useSizeClass` from `./use-size-class`. One media-query hook over the theme's own breakpoints,
  * built on the shared `useMediaQuery` (`common/use-media-query`) — SSR/hydration-safe.
  *
@@ -21,7 +21,7 @@ import { useMediaQuery } from '../common/use-media-query'
 export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 
 /**
- * @deprecated Use `useSizeClass` — removed next minor (see `MIGRATING.md`). `theme.breakpoints` is
+ * @deprecated Use `useSizeClass` — removed in 1.33.0 (see `MIGRATING.md`). `theme.breakpoints` is
  * now derived: `sm` moved 48em → 52.5em and `md`/`lg`/`xl` all sit at 75em (`xs`/`sm` collapse,
  * `md`/`lg`/`xl` collapse).
  */

package/src/theme/floating.module.css

@@ -42,6 +42,7 @@
  * `.sheetBody` is the Modal body; it reaches the trailing button row `overlays.confirm`
  * renders (Mantine `Group`), stretching the buttons to full width at the `--vx-hit` floor.
  */
+/* theme-allow raw-media-query — the bottom sheet IS the compact size class's overlay form */
 @media (max-width: 52.49375em) {
   .sheetInner {
     align-items: flex-end;

package/src/theme-lab/derive-controls.tsx

@@ -178,6 +178,8 @@ export function DeriveControls({ resetIcon }: DeriveControlsProps) {
         <Text size="xs" fw={500} mb={4}>
           Neutral family
         </Text>
+        {/* theme-allow control-outside-home — a theme-lab setting (a settings row, a declared
+            non-home), not a page filter: it edits the derive config, never page data. */}
         <SegmentedControl
           size="xs"
           fullWidth