basalt-ui 1.33.0 → 1.34.1

package/src/index.ts

@@ -85,8 +85,6 @@ export {
   PageAside,
   type PageAsideProps,
   type PageAsideSlot,
-  useBreakpoint,
-  type BreakpointName,
   useSizeClass,
   type SizeClass,
   PageTitle,

package/src/shell/app-mobile-nav.module.css

@@ -69,6 +69,18 @@
   height: var(--vx-space-mobile-nav-icon-size);
 }
 
+/* The first-letter fallback for an icon-less slot (`nav-glyph.tsx`) sits in the same icon-size box
+ * an svg gets, so the pill's height does not depend on the glyph's line box. */
+.tabIcon > [data-nav-glyph] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--vx-space-mobile-nav-icon-size);
+  height: var(--vx-space-mobile-nav-icon-size);
+  line-height: 1;
+  font-weight: 600;
+}
+
 .tab:active .tabIcon {
   transform: scale(0.9);
 }

package/src/shell/app-mobile-nav.tsx

@@ -39,6 +39,7 @@ import type {
 import type { BasaltAccountProps } from './account-types'
 import type { SettingsMenuItem } from './index'
 import { NavCountBadge } from './nav-count-badge'
+import { hasIcon, initialGlyph } from './nav-glyph'
 import { SidebarBlockToneDot } from './sidebar-blocks'
 import { sidebarBlockMobile } from './sidebar-block-model'
 import { useBasaltSpacing } from '../theme'
@@ -456,7 +457,13 @@ export function MobileNav({
   const tabInner = (slot: MobileNavSlot) => (
     <>
       <span className={classes.tabIcon}>
-        {slot.icon ?? (slot.kind !== 'link' && slot.isMore ? <IconMore /> : null)}
+        {hasIcon(slot.icon) ? (
+          slot.icon
+        ) : slot.kind !== 'link' && slot.isMore ? (
+          <IconMore />
+        ) : (
+          initialGlyph(slot.short)
+        )}
         {hasCount(slot) ? <span className={classes.tabDot} aria-hidden /> : null}
       </span>
       <Text className={classes.label}>{slot.short}</Text>

package/src/shell/app-sidebar.module.css

@@ -47,6 +47,12 @@
   margin-inline-end: var(--vx-space-nav-icon-gap);
 }
 
+/* The first-letter fallback for an icon-less row (`nav-glyph.tsx`) — a glyph, not a text run. */
+.link :global(.mantine-NavLink-section[data-position='left']) > [data-nav-glyph] {
+  line-height: 1;
+  font-weight: 600;
+}
+
 /* Inactive rows: muted text + faint icon. Active rows keep the theme's ink text (via `--nl-color`)
  * untouched — this selector only ever matches when `data-active` is absent. `aria-current` is no
  * longer part of the exclusion: `use-nav.ts` is the sole authority on active, stamping exactly one

package/src/shell/app-sidebar.tsx

@@ -39,6 +39,7 @@ import { assertRequiredProps } from '../common/validate'
 import type { BrandConfig, SettingsMenuItem } from './index'
 import type { SidebarBlock, SidebarItem, SidebarSection } from './nav-types'
 import { NavCountBadge } from './nav-count-badge'
+import { iconOrInitial } from './nav-glyph'
 import { SidebarAccount } from './app-sidebar-account'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
 import { SidebarSearch } from './sidebar-search'
@@ -190,12 +191,24 @@ function hasActiveDescendant(item: SidebarItem): boolean {
  * element. That is what replaced the old render callback — a callback had to re-derive basalt's
  * own styling to look right, and every consumer got it subtly wrong.
  */
-function NavLinkBody({ item, active }: { item: SidebarItem; active: boolean }) {
+function NavLinkBody({
+  item,
+  active,
+  collapsed = false,
+}: {
+  item: SidebarItem
+  active: boolean
+  collapsed?: boolean
+}) {
   const Anchor = item.Anchor
   const shared = {
     classNames: { root: classes.link },
     label: item.label,
-    leftSection: item.icon,
+    leftSection: iconOrInitial(item.icon, item.label),
+    // Only the collapsed rail hides the label (CSS), leaving the icon alone — name the link there.
+    // Expanded, the visible text IS the name and carries the count badge; an `aria-label` would
+    // override both and drop the count ("Inbox 5" → "Inbox").
+    ...(collapsed && { 'aria-label': item.label }),
     rightSection: item.badge ?? (item.count ? <NavCountBadge count={item.count} /> : undefined),
     active,
     // Basalt is the one that stamps `aria-current`, not the theme and not a router `<Link>`'s own
@@ -215,6 +228,32 @@ function NavLinkBody({ item, active }: { item: SidebarItem; active: boolean }) {
   return <NavLink component="a" {...(item.href !== undefined && { href: item.href })} {...shared} />
 }
 
+/**
+ * One child row, shared by the inline child list and the hover popover. Never in the rail (the
+ * inline list is hidden there and the popover shows labels), so it carries no `aria-label`.
+ */
+function ChildRow({ child }: { child: SidebarItem }) {
+  if (!child.disabled) {
+    return (
+      <Box>
+        <NavLinkBody item={child} active={Boolean(child.active)} />
+      </Box>
+    )
+  }
+  return (
+    <Tooltip label="Coming soon" position="right" withArrow>
+      <Box>
+        <NavLink
+          classNames={{ root: classes.link }}
+          label={child.label}
+          leftSection={iconOrInitial(child.icon, child.label)}
+          data-disabled
+        />
+      </Box>
+    </Tooltip>
+  )
+}
+
 /**
  * Group label — a micro-label (docs/DESIGN-SPEC.md §3: mono, uppercase, tracked, faint). Typography
  * lives entirely in `.sectionLabel` (app-sidebar.module.css), not Mantine `Text` props, since the
@@ -304,7 +343,8 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
             <NavLink
               classNames={{ root: classes.link }}
               label={item.label}
-              leftSection={item.icon}
+              leftSection={iconOrInitial(item.icon, item.label)}
+              {...(collapsed && { 'aria-label': item.label })}
               data-disabled
             />
           </Box>
@@ -316,7 +356,7 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
     return (
       <Tooltip key={item.key} label={item.label} position="right" withArrow disabled={!collapsed}>
         <Box className={classes.navItem}>
-          <NavLinkBody item={item} active={active} />
+          <NavLinkBody item={item} active={active} collapsed={collapsed} />
         </Box>
       </Tooltip>
     )
@@ -331,32 +371,13 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
       <Box key={item.key}>
         <Tooltip label={item.label} position="right" withArrow disabled={!collapsed}>
           <Box className={classes.navItem}>
-            <NavLinkBody item={item} active={active} />
+            <NavLinkBody item={item} active={active} collapsed={collapsed} />
           </Box>
         </Tooltip>
         <Stack gap={0} className={classes.childList}>
-          {item.children!.map((child) => {
-            if (child.disabled) {
-              return (
-                <Tooltip key={child.key} label="Coming soon" position="right" withArrow>
-                  <Box>
-                    <NavLink
-                      classNames={{ root: classes.link }}
-                      label={child.label}
-                      leftSection={child.icon}
-                      data-disabled
-                    />
-                  </Box>
-                </Tooltip>
-              )
-            }
-            const childActive = Boolean(child.active)
-            return (
-              <Box key={child.key}>
-                <NavLinkBody item={child} active={childActive} />
-              </Box>
-            )
-          })}
+          {item.children!.map((child) => (
+            <ChildRow key={child.key} child={child} />
+          ))}
         </Stack>
       </Box>
     )
@@ -383,7 +404,7 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
             onFocus={scheduleOpen}
             onBlur={scheduleClose}
           >
-            <NavLinkBody item={item} active={active} />
+            <NavLinkBody item={item} active={active} collapsed={collapsed} />
           </Box>
         </Tooltip>
       </Popover.Target>
@@ -397,28 +418,9 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
         onBlur={scheduleClose}
       >
         <Stack gap={0}>
-          {item.children!.map((child) => {
-            if (child.disabled) {
-              return (
-                <Tooltip key={child.key} label="Coming soon" position="right" withArrow>
-                  <Box>
-                    <NavLink
-                      classNames={{ root: classes.link }}
-                      label={child.label}
-                      leftSection={child.icon}
-                      data-disabled
-                    />
-                  </Box>
-                </Tooltip>
-              )
-            }
-            const childActive = Boolean(child.active)
-            return (
-              <Box key={child.key}>
-                <NavLinkBody item={child} active={childActive} />
-              </Box>
-            )
-          })}
+          {item.children!.map((child) => (
+            <ChildRow key={child.key} child={child} />
+          ))}
         </Stack>
       </Popover.Dropdown>
 

package/src/shell/index.tsx

@@ -84,7 +84,6 @@ export {
 export { AppBreadcrumbs, type AppBreadcrumbsProps } from './app-breadcrumbs'
 export { PageBar, type PageBarProps, type PageBarSlot } from './page-bar'
 export { PageAside, type PageAsideProps, type PageAsideSlot } from './page-aside'
-export { useBreakpoint, type BreakpointName } from './use-breakpoint'
 export { useSizeClass, type SizeClass } from './use-size-class'
 export { PageTitle, type PageTitleProps, type PageTitleSlot } from './page-title'
 

package/src/shell/nav-glyph.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react'
+
+/** `Intl.Segmenter` is in every supported runtime; the code-point split is the belt-and-braces fallback. */
+const segmenter =
+  typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function'
+    ? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
+    : undefined
+
+/** The first grapheme of a label — the fallback body for an item or action shipping no icon. */
+export function initial(label: string): string {
+  const first = segmenter
+    ? segmenter.segment(label)[Symbol.iterator]().next().value?.segment
+    : [...label][0]
+  return first?.toUpperCase() ?? '?'
+}
+
+/** False for everything React renders as nothing — `cond && <Icon />` yields `false`, not `null`. */
+export function hasIcon(icon: ReactNode): boolean {
+  return icon !== null && icon !== undefined && typeof icon !== 'boolean' && icon !== ''
+}
+
+/**
+ * The label's first grapheme as a decorative glyph. The collapsed rail and the landscape tab bar
+ * show the icon ALONE, so an absent icon would render a nameless, empty target. `aria-hidden`: the
+ * accessible name comes from the label, never the glyph.
+ */
+export function initialGlyph(label: string): ReactNode {
+  return (
+    <span aria-hidden data-nav-glyph>
+      {initial(label)}
+    </span>
+  )
+}
+
+/** A nav item's icon, or its label's first-letter glyph when it ships none. */
+export function iconOrInitial(icon: ReactNode, label: string): ReactNode {
+  return hasIcon(icon) ? icon : initialGlyph(label)
+}

package/src/shell/nav-types.ts

@@ -31,6 +31,7 @@ export type SidebarItem = {
   short?: string
   /** Mobile placement. `true` ≡ `'tab'`, `false` ≡ `'hidden'`. @default 'more' */
   mobile?: boolean | NavMobilePlacement
+  /** The collapsed rail and landscape tab bar show the icon alone; `null` falls back to the label's first letter. */
   icon: ReactNode
   /**
    * The router seam. basalt renders every pixel of chrome (desktop row, 56px slot, 44px sheet

package/src/shell/sidebar-search.tsx

@@ -13,6 +13,7 @@ import { OverflowMenu } from '../controls/actions'
 import type { BarAction } from '../controls/actions'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
+import { initial } from './nav-glyph'
 import classes from './sidebar-search.module.css'
 
 /**
@@ -55,11 +56,6 @@ function IconSearch() {
   )
 }
 
-/** The first grapheme of a label — the fallback body for an action shipping no icon. */
-function initial(label: string): string {
-  return [...label][0]?.toUpperCase() ?? '?'
-}
-
 /**
  * One trailing action as an icon-only button. `size="icon"` is EXPLICIT here, not inherited: the
  * search row is chrome, not a control home, so no `CtlSlot` wraps it and nothing else would resolve

package/src/surfaces.ts

@@ -299,7 +299,7 @@ export const SURFACES = {
       "no second cssVariablesResolver — don't hand-build createTheme or re-add the resolver basalt already installs",
     ],
     description:
-      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass (useBreakpoint on notice), NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
+      'BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, PageBar, PageAside, useSizeClass, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, WidgetHeader, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, QueryState/LoadingState/ErrorState, SettingsSection/SettingsRow/DangerZone), ConnectivityProvider/useConnectivity/ConnectivityIndicator (auto-mounted, C1: absorbed from the dropped ./connectivity), createBasaltQueryClient/unwrap/BasaltQueryDevtools (C1: absorbed from the dropped ./query), BasaltDevDock (C5: lazy Router/Query devtools + theme lab in one dock)',
     optionalPeers: [
       'react-markdown',
       'remark-gfm',
@@ -662,7 +662,7 @@ export const SURFACES = {
     kind: 'tooling',
     layer: 'non-js-asset',
     description:
-      'Raw toolchain presets for consumer extends: oxlint.json, oxfmt.json, tsconfig.*.json, lefthook.yml, check.yml',
+      'Raw toolchain presets for consumer extends: oxlint.json (or the guards-only oxlint-basalt.json), oxfmt.json, tsconfig.*.json, lefthook.yml, check.yml',
     forbiddenImports: [],
   },
   './llms.txt': {

package/src/tokens/index.ts

@@ -22,6 +22,8 @@ import {
 import type { PaletteData, RadiusValues, SpaceValues } from './palette'
 import { SIZE_CLASSES, sizeClassMaxEm } from './size-classes'
 import { HIT_COARSE, HIT_FINE } from '../common/hit-floor'
+import { BASALT_VX_FAMILIES } from '../common/vx-families'
+import { vxFamilyOf } from '../common/vx-family'
 
 // The raw hue families + pair-picker — the building blocks a consumer's series module composes
 // (`hrv: p(BP.blue)`). The doctrine sends every consumer here, so they are public surface, not
@@ -57,6 +59,7 @@ export type { SpaceValues } from './palette'
 export {
   CONTAINER_CLASSES,
   CONTAINER_GRID_BREAKPOINTS,
+  CONTAINER_KEYS,
   resolveContainerClass,
   SIZE_CLASSES,
 } from './size-classes'
@@ -805,6 +808,26 @@ function frameworkDerived(data: PaletteData, only: 'core' | 'all', legacyAliases
   return legacyAliases ? `${canonical}\n${frameworkDerivedAliases(data)}` : canonical
 }
 
+const warnedVxNames = new Set<string>()
+
+/**
+ * Warn, once per name, on a consumer series/group name inside a basalt-owned `--vx-*` family
+ * (`surface`, `space`, `ink`, …): `check-theme`'s `unknown-vx-token` judges every name there against
+ * what basalt emits, which is sound only while no consumer REF points there. A WARNING for the
+ * minor that kind is graced in (1.34.x), dev builds only; `grace.test.ts` pins the message's
+ * version to the ledger's `promote` and requires a throw once the kind promotes.
+ * The families are the guard's own generated `BASALT_VX_FAMILIES`. Checked on the refs, not in
+ * `buildPaletteCss`, which runs on every first paint.
+ */
+function warnConsumerVxName(name: string): void {
+  const family = vxFamilyOf(name)
+  if (!BASALT_VX_FAMILIES.includes(family) || warnedVxNames.has(name)) return
+  warnedVxNames.add(name)
+  console.warn(
+    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)). Throws from 1.35.0.`,
+  )
+}
+
 /**
  * Wrap a map of `{ name: ColorPair }` into `var(--vx-<prefix><name>)` token refs — the runtime
  * companion to `buildPaletteCss`. Lets a consumer define its own series and read stable refs.
@@ -817,7 +840,11 @@ export function seriesTokens<const T extends SeriesMap>(
   prefix = '',
 ): { [K in keyof T]: string } {
   const out = {} as { [K in keyof T]: string }
-  for (const key of Object.keys(map) as (keyof T)[]) out[key] = `var(--vx-${prefix}${String(key)})`
+  for (const key of Object.keys(map) as (keyof T)[]) {
+    // Literal read at the branch, so a production bundle drops the check (common/dev-gate.test.ts).
+    if (process.env.NODE_ENV !== 'production') warnConsumerVxName(`--vx-${prefix}${String(key)}`)
+    out[key] = `var(--vx-${prefix}${String(key)})`
+  }
   return out
 }
 

package/src/tokens/size-classes.ts

@@ -14,6 +14,19 @@ export const CONTAINER_CLASSES = { micro: 0, compact: 240, regular: 480, wide: 8
 
 export type ContainerClass = keyof typeof CONTAINER_CLASSES
 
+/**
+ * `CONTAINER_CLASSES` as the CSS lengths `<SimpleGrid type="container">` keys take — Mantine writes
+ * each key verbatim into `@container simple-grid (min-width: <key>)`, so a theme name (`sm`) is a
+ * dead query and the key has to be a px length: `cols={{ base: 1, [CONTAINER_KEYS.regular]: 2 }}`.
+ * `micro` has no key — `base` is that class. `basalt/raw-breakpoint` judges theme names only, so a
+ * computed key is green.
+ */
+export const CONTAINER_KEYS = {
+  compact: `${CONTAINER_CLASSES.compact}px`,
+  regular: `${CONTAINER_CLASSES.regular}px`,
+  wide: `${CONTAINER_CLASSES.wide}px`,
+} as const
+
 /**
  * `CONTAINER_CLASSES` as the five-key map `<Grid type="container" breakpoints={…}>` takes (Mantine
  * types it `Record<MantineSize, string>`), so `Grid.Col` keys resolve onto the grid's own width:
@@ -21,11 +34,11 @@ export type ContainerClass = keyof typeof CONTAINER_CLASSES
  * by name (from `basalt-ui/tokens`) — any other imported map is unreadable to it and flagged.
  */
 export const CONTAINER_GRID_BREAKPOINTS = {
-  xs: `${CONTAINER_CLASSES.compact}px`,
-  sm: `${CONTAINER_CLASSES.regular}px`,
-  md: `${CONTAINER_CLASSES.wide}px`,
-  lg: `${CONTAINER_CLASSES.wide}px`,
-  xl: `${CONTAINER_CLASSES.wide}px`,
+  xs: CONTAINER_KEYS.compact,
+  sm: CONTAINER_KEYS.regular,
+  md: CONTAINER_KEYS.wide,
+  lg: CONTAINER_KEYS.wide,
+  xl: CONTAINER_KEYS.wide,
 } as const
 
 /** The class a MEASURED inline size falls in (`px` is a min-width boundary, so 240 is `compact`). */

package/dist/shell/use-breakpoint.d.ts

@@ -1,10 +0,0 @@
-export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-/**
- * @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).
- */
-export declare function useBreakpoint(name: BreakpointName, edge?: 'min' | 'max', options?: {
-    fallback?: boolean;
-}): boolean;
-//# sourceMappingURL=use-breakpoint.d.ts.map

package/dist/shell/use-breakpoint.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-breakpoint.d.ts","sourceRoot":"","sources":["../../src/shell/use-breakpoint.ts"],"names":[],"mappings":"AAoBA,MAAM,MAAM,cAAc,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAE7D;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,cAAc,EACpB,IAAI,GAAE,KAAK,GAAG,KAAa,EAC3B,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/B,OAAO,CAKT"}

package/dist/shell/use-breakpoint.js

@@ -1,11 +0,0 @@
-import { useMantineTheme } from "@mantine/core";
-import { useMediaQuery } from "../common/use-media-query.js";
-function useBreakpoint(name, edge = "min", options) {
-  const theme = useMantineTheme();
-  const bp = theme.breakpoints[name];
-  const fallback = options?.fallback ?? edge === "max";
-  return useMediaQuery(`(${edge}-width: ${bp})`, fallback);
-}
-export {
-  useBreakpoint
-};

package/src/shell/use-breakpoint.ts

@@ -1,37 +0,0 @@
-/**
- * `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.
- *
- * `edge` defaults to `'min'` (`"at least this wide"`); pass `'max'` for `"narrower than"`. The
- * `fallback` (what the server, and a shim with no `matchMedia`, sees) defaults to the answer that
- * assumes the NARROW side of the query — `false` for `min`, `true` for `max` — since a component
- * library cannot know a consumer's real device mix; `options.fallback` overrides it.
- *
- * @example
- * import { useBreakpoint } from 'basalt-ui'
- *
- * const isDesktop = useBreakpoint('sm')            // >= theme.breakpoints.sm
- * const isNarrow = !useBreakpoint('sm')             // < theme.breakpoints.sm
- * const isWide = useBreakpoint('lg')                // >= theme.breakpoints.lg
- */
-import { useMantineTheme } from '@mantine/core'
-import { useMediaQuery } from '../common/use-media-query'
-
-export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
-
-/**
- * @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).
- */
-export function useBreakpoint(
-  name: BreakpointName,
-  edge: 'min' | 'max' = 'min',
-  options?: { fallback?: boolean },
-): boolean {
-  const theme = useMantineTheme()
-  const bp = theme.breakpoints[name]
-  const fallback = options?.fallback ?? edge === 'max'
-  return useMediaQuery(`(${edge}-width: ${bp})`, fallback)
-}