basalt-ui 2.0.1 → 2.0.3

package/src/cli/sync.ts

@@ -101,6 +101,12 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
     return 0
   }
 
+  const appError = resolvePlacement(cwd).appError
+  if (appError !== null) {
+    console.error(`✖ basalt-ui sync: ${appError}`)
+    return 1
+  }
+
   // Refuse BEFORE reconcileRoots, which writes `basalt.roots` into package.json.
   if (!existsSync(resolve(cwd, MANIFEST_PATH))) {
     const elsewhere = findManifestAbove(cwd)

package/src/provider/index.tsx

@@ -41,6 +41,7 @@ import type { Telemetry } from '../telemetry'
 import type { BasaltDevDockTool } from '../dev-dock'
 import type { BasaltRouter, BasaltRouterContext } from './create-router'
 import { useRegistryHotkeys } from './hotkeys'
+import type { FlatNavItem } from '../router-tanstack/nav'
 import { buildSpotlightActions } from './spotlight-actions'
 
 export type BasaltProviderProps = {
@@ -79,6 +80,12 @@ export type BasaltProviderProps = {
    * can answer. Default `'compact'`. SSR only; an SSR desktop app SHOULD pass it.
    */
   sizeClassHint?: SizeClass
+  /**
+   * Label for the `nav.<id>` Spotlight entries generated from `defineNav`, e.g.
+   * `(item) => `Go to ${item.label}``. Default: the destination's own label. A `defineCommands`
+   * entry with id `nav.<id>` replaces the generated one outright.
+   */
+  navCommandLabel?: (item: FlatNavItem) => string
 } & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>
 
 // ── Root error boundary ───────────────────────────────────────────────────────────────────────────
@@ -408,6 +415,7 @@ export function BasaltProvider({
   defaultColorScheme = 'dark',
   nonce,
   sizeClassHint = 'compact',
+  navCommandLabel,
   ...rest
 }: BasaltProviderProps) {
   useDuplicateProviderGuard()
@@ -432,8 +440,8 @@ export function BasaltProvider({
   // appears, not frozen at mount — and `detectMac` (inside the builder) never runs during render.
   const [actions, setActions] = useState<SpotlightActionData[]>([])
   const refreshActions = useCallback(
-    () => setActions(buildSpotlightActions(router, setDevTool)),
-    [router],
+    () => setActions(buildSpotlightActions(router, setDevTool, navCommandLabel)),
+    [router, navCommandLabel],
   )
   useEffect(refreshActions, [refreshActions])
 

package/src/provider/spotlight-actions.tsx

@@ -1,6 +1,6 @@
 /**
  * The provider's Spotlight list: the `defineCommands` registry, then the `defineNav` destinations
- * (via `flattenNav`), then the three dev-dock commands in dev. A snapshot rebuilt each time Spotlight
+ * (via `flattenNav`, skipping any id a registered `nav.<id>` command already owns), then the three dev-dock commands in dev. A snapshot rebuilt each time Spotlight
  * opens, so a command's `when()` is current. Not for use during render (`detectMac` reads `navigator`).
  */
 import type { SpotlightActionData } from '@mantine/spotlight'
@@ -8,6 +8,7 @@ import type { AnyRouter } from '@tanstack/react-router'
 import { getActiveCommands } from '../commands/define-commands'
 import { detectMac, formatShortcutDisplay } from '../commands/shortcut-format'
 import { flattenNav, getActiveNav } from '../router-tanstack/nav'
+import type { FlatNavItem } from '../router-tanstack/nav'
 import type { BasaltDevDockTool } from '../dev-dock'
 import { runCommandSafely } from './hotkeys'
 
@@ -20,10 +21,12 @@ const DEV_TOOLS: ReadonlyArray<{ tool: BasaltDevDockTool; label: string }> = [
 export function buildSpotlightActions(
   router: AnyRouter,
   openDevTool: (tool: BasaltDevDockTool) => void,
+  navCommandLabel?: (item: FlatNavItem) => string,
 ): SpotlightActionData[] {
   const actions: SpotlightActionData[] = []
+  const commands = getActiveCommands()
 
-  for (const [id, cmd] of Object.entries(getActiveCommands())) {
+  for (const [id, cmd] of Object.entries(commands)) {
     if (cmd.when !== undefined && !cmd.when()) continue
     actions.push({
       id,
@@ -42,9 +45,11 @@ export function buildSpotlightActions(
   if (nav !== undefined) {
     for (const item of flattenNav(nav)) {
       if (item.disabled === true) continue
+      // A registered `nav.<id>` command owns that destination: the consumer wins, no duplicate.
+      if (`nav.${item.id}` in commands) continue
       actions.push({
         id: `nav.${item.id}`,
-        label: item.label,
+        label: navCommandLabel?.(item) ?? item.label,
         group: item.groupLabel,
         leftSection: item.icon,
         // `link` is the destination's own `linkOptions`, so a store-backed `search` thunk restores

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

@@ -472,6 +472,12 @@
   box-shadow: 0 0 0 2px var(--mantine-color-body);
 }
 
+/* Host for a nav row's rail dot: the dot anchors on the icon itself, not the 48px row. */
+.navIconDotHost {
+  position: relative;
+  display: inline-flex;
+}
+
 .blockItems {
   display: flex;
   flex-direction: column;

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

@@ -29,6 +29,7 @@ declare const classes: {
   readonly blockHeaderButton: string
   readonly blockIcon: string
   readonly blockDot: string
+  readonly navIconDotHost: string
   readonly blockItems: string
   readonly blockRow: string
   readonly blockRowStatic: string

package/src/shell/app-sidebar.tsx

@@ -207,14 +207,28 @@ function NavLinkBody({
   collapsed?: boolean
 }) {
   const Anchor = item.Anchor
+  const icon = iconOrInitial(item.icon, item.label)
+  // The rail hides the right section (where the badge lives), so a badged row keeps a dot on its
+  // icon instead — the count rides the accessible name since the number itself has no room.
+  const railDot =
+    collapsed && ((item.badge !== undefined && item.badge !== null) || Boolean(item.count))
   const shared = {
     classNames: { root: classes.link },
     label: item.label,
-    leftSection: iconOrInitial(item.icon, item.label),
+    leftSection: railDot ? (
+      <span className={classes.navIconDotHost}>
+        {icon}
+        <span className={classes.blockDot} data-basalt-rail-dot aria-hidden />
+      </span>
+    ) : (
+      icon
+    ),
     // 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 }),
+    ...(collapsed && {
+      'aria-label': item.count ? `${item.label}, ${item.count}` : 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

package/src/tokens/core.ts

@@ -820,15 +820,23 @@ export function defineSeries<const T extends SeriesMap>(map: T): T {
 /** Runtime key of the {@link SeriesGroup} brand. */
 const SERIES_GROUP: unique symbol = Symbol('basalt.series-group')
 
-/**
- * The brand `groupTokens` puts on its return value. `BuildPaletteOpts.groups` takes these, so the
- * `${name}-` key that emits the variables and the one that references them come from one call and
- * cannot be spelled two ways.
- */
-export type SeriesGroup = {
+type GroupPayload = {
   readonly [SERIES_GROUP]: { readonly prefix: string; readonly map: SeriesMap }
 }
 
+declare const GROUP_REF: unique symbol
+
+/** A `var(--vx-<name>-<key>)` ref minted by `groupTokens`. The brand lives on the VALUES, so it never shows up in `keyof` the group. */
+export type GroupRef = string & { readonly [GROUP_REF]: true }
+
+/**
+ * What `groupTokens` returns. `BuildPaletteOpts.groups` takes these, so the `${name}-` key that
+ * emits the variables and the one that references them come from one call and cannot be spelled
+ * two ways. A bare series map (object values) and a plain string record (unbranded values) are
+ * both rejected; the runtime payload sits under the non-enumerable {@link SERIES_GROUP} symbol.
+ */
+export type SeriesGroup = { readonly [key: string]: GroupRef }
+
 /**
  * Build a single namespaced group's token refs (`var(--vx-<name>-<key>)`).
  *
@@ -838,12 +846,12 @@ export type SeriesGroup = {
 export function groupTokens<const T extends SeriesMap>(
   name: string,
   map: T,
-): { [K in keyof T]: string } & SeriesGroup {
+): { readonly [K in keyof T]: GroupRef } {
   const refs = seriesTokens(map, `${name}-`)
   // Non-enumerable, symbol-keyed: a series key can never collide with the brand, and
   // `Object.keys(refs)` still lists exactly the series.
   Object.defineProperty(refs, SERIES_GROUP, { value: { prefix: `${name}-`, map } })
-  return refs as { [K in keyof T]: string } & SeriesGroup
+  return refs as { readonly [K in keyof T]: GroupRef }
 }
 
 /**
@@ -1024,7 +1032,15 @@ export function buildPaletteCss(
   const derived = extraDerived ? `${derivedBlock}\n${extraDerived}` : derivedBlock
   const side = (s: Side): string => {
     const extra = groups
-      .map((group) => groupSide(group[SERIES_GROUP].prefix, group[SERIES_GROUP].map, s))
+      .map((group) => {
+        const payload = (group as unknown as Partial<GroupPayload>)[SERIES_GROUP]
+        if (!payload) {
+          throw new Error(
+            'BuildPaletteOpts.groups: every group must come from groupTokens(name, map)',
+          )
+        }
+        return groupSide(payload.prefix, payload.map, s)
+      })
       .join('\n')
     const framework = frameworkPrimitives(s, data, legacyAliases)
     return extra ? `${framework}\n${extra}` : framework