basalt-ui 1.34.1 → 1.36.0

package/src/shell/nav-types.ts

@@ -139,9 +139,10 @@ export type SidebarProgressBlock = {
 }
 
 /**
- * DESKTOP ONLY — arbitrary consumer content (a tree, a filter panel) that no set of rows can
- * express. Replaced `BasaltShellProps.sidebarNavExtra`; hidden on the collapsed rail and absent
- * from mobile for the same reason that prop was.
+ * Arbitrary consumer content (a tree, a filter panel) that no set of rows can express. Replaced
+ * `BasaltShellProps.sidebarNavExtra`. By default desktop-only and hidden on the collapsed rail,
+ * exactly as that prop was; `icon` + `label` opt it into the rail (as an icon opening the node in a
+ * popover) and `mobile: 'more'` into the More sheet.
  */
 export type SidebarCustomBlock = {
   kind: 'custom'
@@ -149,6 +150,21 @@ export type SidebarCustomBlock = {
   node: ReactNode
   /** @default 'nav' */
   placement?: 'nav' | 'bottom'
+  /** The rail icon. Needs `label` too: an icon-only trigger must be nameable. */
+  icon?: ReactNode
+  /** The rail icon's accessible name, the popover heading and the More row / sheet title. */
+  label?: string
+  /**
+   * Collapsed-rail projection: `'icon'` swaps the node for `icon`, which opens it in a popover.
+   * @default 'icon' when both `icon` and `label` are set, `'hidden'` otherwise
+   */
+  rail?: 'icon' | 'hidden'
+  /**
+   * Below `sm` there is no sidebar: `'more'` makes one More row, labelled `label`, that opens the
+   * node in a sheet. Needs `label`.
+   * @default 'hidden'
+   */
+  mobile?: 'more' | 'hidden'
 }
 
 /**

package/src/shell/sidebar-block-model.ts

@@ -26,11 +26,17 @@ export function sidebarBlockPlacement(block: SidebarBlock): 'nav' | 'bottom' {
 /**
  * The collapsed-rail projection. A list block earns a dot only when it carries a `count` — a rail
  * icon with no number behind it is a dot that means nothing — and a progress block a ring on the
- * settings row. A `custom` block has no rail representation at all (arbitrary content in ~48px of
- * icon column), which is exactly what `sidebarNavExtra` did before it.
+ * settings row. A `custom` block has a rail form only when it opts in (see below), which is
+ * `sidebarNavExtra`'s old hidden-in-the-rail behaviour otherwise.
  */
-export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'hidden' {
-  if (block.kind === 'custom') return 'hidden'
+export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'icon' | 'hidden' {
+  // A `custom` block is arbitrary content with no icon-column form of its own, so it is hidden
+  // unless the consumer supplied the icon AND the name that make a rail trigger. Like a list's dot,
+  // that overrides an explicit `rail: 'icon'` without them.
+  if (block.kind === 'custom') {
+    if (block.icon === undefined || block.label === undefined) return 'hidden'
+    return block.rail ?? 'icon'
+  }
   if (block.kind === 'progress') return block.rail ?? 'ring'
   // A dot has to sit ON something. With no `icon` there is no rail node to badge, and with no
   // `count` there is no number behind the dot — either way the block leaves the rail rather than
@@ -47,7 +53,9 @@ export function sidebarBlockRail(block: SidebarBlock): 'dot' | 'ring' | 'hidden'
  * threshold is measured against.
  */
 export function sidebarBlockMobile(block: SidebarBlock): 'more' | 'hidden' {
-  if (block.kind === 'custom') return 'hidden'
+  // A custom block's More row is named by `label`; without one there is nothing to name it.
+  if (block.kind === 'custom')
+    return block.mobile === 'more' && block.label !== undefined ? 'more' : 'hidden'
   if (block.kind === 'progress') return block.mobile ?? 'hidden'
   return block.mobile ?? 'more'
 }

package/src/shell/sidebar-blocks.tsx

@@ -12,7 +12,7 @@
  * module's class. A second CSS module would hash `.block*` into a different name than the rail
  * rules could ever select.
  */
-import { Collapse, NavLink, Progress, Text, UnstyledButton } from '@mantine/core'
+import { Collapse, NavLink, Popover, Progress, Text, UnstyledButton } from '@mantine/core'
 import { useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
@@ -280,10 +280,33 @@ function ProgressBlock({ block }: { block: SidebarProgressBlock }) {
   )
 }
 
-/** A `kind: 'custom'` block — consumer content, hidden on the rail exactly as `navExtra` was. */
-function CustomBlock({ block }: { block: SidebarCustomBlock }) {
+/**
+ * A `kind: 'custom'` block — consumer content. Without `icon` + `label` it is hidden on the rail
+ * exactly as `navExtra` was (CSS only, the node stays mounted). With them the rail swaps the node
+ * for its icon, which opens the node in a popover: that swap is JS-gated on `collapsed`, because
+ * the trigger is a different element and nothing in the node's own subtree could express it. The
+ * popover mounts only while open, so the inline node is never duplicated.
+ */
+function CustomBlock({ block, collapsed }: { block: SidebarCustomBlock; collapsed: boolean }) {
+  const rail = sidebarBlockRail(block)
+  if (collapsed && rail === 'icon') {
+    return (
+      <div className={classes.block} data-rail="icon">
+        <Popover position="right-start" withArrow={false} offset={4} withinPortal zIndex={400}>
+          <Popover.Target>
+            <UnstyledButton className={classes.blockRailTrigger} aria-label={block.label}>
+              <IconSlot>{block.icon}</IconSlot>
+            </UnstyledButton>
+          </Popover.Target>
+          <Popover.Dropdown p="xs" className={classes.blockRailPopover}>
+            {block.node}
+          </Popover.Dropdown>
+        </Popover>
+      </div>
+    )
+  }
   return (
-    <div className={classes.block} data-rail="hidden">
+    <div className={classes.block} data-rail={rail}>
       {block.node}
     </div>
   )
@@ -292,10 +315,12 @@ function CustomBlock({ block }: { block: SidebarCustomBlock }) {
 /** One block, whichever kind it is. `AppSidebar` places it; this decides nothing but the paint. */
 export function SidebarBlockView({
   block,
+  collapsed = false,
 }: {
   block: SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock
+  collapsed?: boolean
 }) {
   if (block.kind === 'list') return <ListBlock block={block} />
   if (block.kind === 'progress') return <ProgressBlock block={block} />
-  return <CustomBlock block={block} />
+  return <CustomBlock block={block} collapsed={collapsed} />
 }

package/src/shell/use-size-class.ts

@@ -4,10 +4,12 @@
  * `'compact' | 'medium' | 'expanded'`, for the JS reads CSS cannot express (portal targets,
  * mount-one-of-two branches). Shell-only — components size by container, not by this.
  *
- * Built on `useMediaQuery` (`common/use-media-query`), one call per class boundary. The server
- * snapshot is `<BasaltProvider sizeClassHint>` (default `'compact'`), so SSR, the hydration pass
- * and the first client paint agree, and the real class lands one commit later — no first-frame
- * flash from a `matchMedia` read inside a `useState` initializer.
+ * Built on `useMediaQuery` (`common/use-media-query`), one call per class boundary. A
+ * client-rendered app (`createRoot`) reads `matchMedia` on its FIRST render — no hint, no flash, so
+ * a mount-one-of-two branch on this hook is flash-free in a CSR SPA (`use-size-class.test.tsx`
+ * pins it). Only SSR and the `hydrateRoot` pass read the server snapshot,
+ * `<BasaltProvider sizeClassHint>` (default `'compact'`), so server HTML and hydration agree and the
+ * real class lands one commit later.
  */
 import { createContext, useContext } from 'react'
 import { useMediaQuery } from '../common/use-media-query'

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, 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, useCoarsePointer, 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',
@@ -443,7 +443,7 @@ export const SURFACES = {
     // consumer ships today (`PLUGIN_RULE_GRACE`).
     pluginRules: ['forms-field-key'],
     description:
-      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), the FormSection/FormRow/FormGroup/FormActions layout (FormRow is law C1’s form row), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema)',
+      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0',
     optionalPeers: ['@mantine/form'],
     forbiddenImports: [],
   },
@@ -564,8 +564,8 @@ export const SURFACES = {
     layer: 'mantine-coupled',
     rule: 'controls',
     skill: ['basalt-design'],
-    // The text lane of law C1 — the plugin's `control-outside-home` seen through a 12-line host-tag
-    // window, since a regex scan has no ancestry. Same law, same wave, same promotion.
+    // The text lane of law C1 — the plugin's `control-outside-home` seen through a host-tag nesting
+    // count, since a regex scan has no AST. Same law, same wave, same promotion.
     guardKinds: ['raw-selection-control'],
     // The control tier itself (laws C1/C3/C5/C9). `hand-rolled-filter`, `control-size-literal` and
     // `responsive-twin` all ship `error`; the two C1 placement rules are the grace entries in
@@ -589,7 +589,7 @@ export const SURFACES = {
       'C12 — one shape for refresh/sync (SyncButton); only the alias table sees a renamed copy',
     ],
     description:
-      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, and the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
+      'The control tier (docs/CONTROLS-SPEC.md §3): FilterSet (nowrap row + measured +N fold + the mobile Filters (n) sheet), RangeFilter/CompareFilter/SelectFilter/MultiSelectFilter/NumberFilter/SearchFilter/ToggleFilter (each bound to a FieldHandle — no value/onChange/size, law C2/C5; NumberFilter is the field.number lane, a radio list over `options` or a stepper without), ViewTabs, the action/sync family (ActionGroup, OverflowMenu, SyncButton, BarAction/GlobalAction), and the form layout FormSection/FormRow/FormGroup/FormActions (moved here from ./forms in 1.36.0 — FormRow is law C1’s form row and needs no @mantine/form). THREE surfaces, picked by the home and never by a prop (useFilterSurface): pill in a PageBar row, sheet in the mobile Filters (n) drawer, panel in a PageAside body — where every control renders an inspector/facet ROW instead of a chip (docs/ASIDE-SPEC.md §3). PanelRow is that row primitive (label above, hint, mono readout, an `end` control on the label line) and SliderControl is the one bound control with no pill form at all; the counts/max props on MultiSelectFilter render the Foundry facet list there. Every control owns its own desktop/mobile swap in CSS (C9) and renders size="ctl" internally. Resolves and renders with NO @mantine/dates installed — the custom date picker is injected through RangeFilter.customPicker from ./controls-dates.',
     optionalPeers: [],
     // `@mantine/dates` is an optional peer basaltViteConfig pre-bundles the whole @mantine scope
     // for — a consumer without the peer (linewatch) must never resolve it through this surface.
@@ -608,6 +608,14 @@ export const SURFACES = {
         '@mantine/dates/*',
         '@mantine/dates is an OPTIONAL peer (docs/CONTROLS-SPEC.md §3) — ./controls must resolve with no @mantine/dates installed. The one reach lives in src/controls-dates/, injected into range-filter.tsx’s customPicker seam.',
       ),
+      v(
+        '@mantine/form',
+        '@mantine/form is an OPTIONAL peer — ./controls (which owns the form layout since 1.36.0) must resolve with no @mantine/form installed. Only ./forms needs it.',
+      ),
+      vg(
+        '@mantine/form/*',
+        '@mantine/form is an OPTIONAL peer — ./controls (which owns the form layout since 1.36.0) must resolve with no @mantine/form installed. Only ./forms needs it.',
+      ),
     ],
   },
   './controls-dates': {

package/src/tokens/index.ts

@@ -808,23 +808,20 @@ 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.
+ * Throw 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. Dev builds only (the call sits behind a
+ * literal NODE_ENV read); `unknown-vx-token` left the grace ledger at 1.36.0, which is when this
+ * went from a once-per-name warning to a throw. 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 {
+function assertConsumerVxName(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.`,
+  if (!BASALT_VX_FAMILIES.includes(family)) return
+  throw new Error(
+    `[basalt] ${name} is inside basalt's own --vx-${family} family — name your series group something basalt does not own (groupTokens('app', …)).`,
   )
 }
 
@@ -842,7 +839,7 @@ export function seriesTokens<const T extends SeriesMap>(
   const out = {} as { [K in keyof T]: string }
   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)}`)
+    if (process.env.NODE_ENV !== 'production') assertConsumerVxName(`--vx-${prefix}${String(key)}`)
     out[key] = `var(--vx-${prefix}${String(key)})`
   }
   return out

package/dist/forms/form-layout.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"form-layout.d.ts","sourceRoot":"","sources":["../../src/forms/form-layout.tsx"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAGnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAyC1D,gEAAgE;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAExD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GACxC,eAAe,CAAC,eAAe,CAAC,GAChC,sBAAsB,GAAG;IACvB,0DAA0D;IAC1D,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAoBlD;AAID,4DAA4D;AAC5D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;AAEtD,MAAM,MAAM,YAAY,GAAG,WAAW,GACpC,eAAe,CAAC,WAAW,CAAC,GAAG;IAC7B,4FAA4F;IAC5F,KAAK,EAAE,MAAM,CAAA;IACb,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,oGAAoG;IACpG,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4FAA4F;IAC5F,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,+BA0B1C;AAID,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACzC,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAA;IACb,mCAAmC;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,KAAK,CAAC,EAAE,SAAS,CAAA;IACjB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,QAAQ,CAAA;IAC5B,+CAA+C;IAC/C,QAAQ,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,+BAsB9C;AAID,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IAC3C;;;;;;;;OAQG;IACH,OAAO,EAAE,WAAW,CAAA;CACrB,CAAA;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,+BAgBlD"}