basalt-ui 2.0.1 → 2.0.3

package/dist/provider/index.d.ts

@@ -5,6 +5,7 @@ import type { BuildPaletteOpts } from '../tokens/core.js';
 import type { SizeClass } from '../shell/use-size-class.js';
 import type { Telemetry } from '../telemetry.js';
 import type { BasaltRouter } from './create-router.js';
+import type { FlatNavItem } from '../router-tanstack/nav.js';
 export type BasaltProviderProps = {
     /** From `createBasaltRouter`; the provider mounts it and reads its `queryClient`. */
     router: BasaltRouter;
@@ -41,6 +42,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'>;
 type RootBoundaryProps = {
     children: ReactNode;
@@ -76,6 +83,6 @@ export declare function composeInjectedCss(base: string, fontsCss: string, radiu
  * closes the gap between hydration and the next client paint.
  */
 export declare function useHostAttribute(): void;
-export declare function BasaltProvider({ router, theme, telemetry, fallback, injectPalette, paletteOptions, defaultColorScheme, nonce, sizeClassHint, ...rest }: BasaltProviderProps): import("react").JSX.Element;
+export declare function BasaltProvider({ router, theme, telemetry, fallback, injectPalette, paletteOptions, defaultColorScheme, nonce, sizeClassHint, navCommandLabel, ...rest }: BasaltProviderProps): import("react").JSX.Element;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/provider/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AASzD,OAAO,EAAE,SAAS,EAAqE,MAAM,OAAO,CAAA;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAStD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,iBAAiB,CAAA;AAIxE,MAAM,MAAM,mBAAmB,GAAG;IAChC,qFAAqF;IACrF,MAAM,EAAE,YAAY,CAAA;IACpB,qFAAqF;IACrF,KAAK,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAA;IACrC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC,CAAA;IACtD;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAA;IACjC,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,oBAAoB,CAAC,oBAAoB,CAAC,CAAA;IAC/D;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,CAAA;CAC1B,GAAG,IAAI,CAAC,oBAAoB,EAAE,UAAU,GAAG,OAAO,GAAG,oBAAoB,GAAG,sBAAsB,CAAC,CAAA;AAIpG,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,SAAS,CAAA;IACnB,IAAI,EAAE,SAAS,CAAA;IACf,QAAQ,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAA;CAC1C,CAAA;AAED,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAwB1D,mGAAmG;AACnG,qBAAa,YAAa,SAAQ,SAAS,CAAC,iBAAiB,EAAE,aAAa,CAAC;gBAC/D,KAAK,EAAE,iBAAiB;IAKpC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa;IAIrD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAczD,MAAM,IAAI,SAAS;CAO7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAYD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAmBvC;AAqMD,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,SAAS,EACT,QAAQ,EACR,aAAoB,EACpB,cAAc,EACd,kBAA2B,EAC3B,KAAK,EACL,aAAyB,EACzB,GAAG,IAAI,EACR,EAAE,mBAAmB,+BA6ErB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/provider/index.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AASzD,OAAO,EAAE,SAAS,EAAqE,MAAM,OAAO,CAAA;AACpG,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAKjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAStD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAE7C,OAAO,KAAK,EAAE,YAAY,EAAuB,MAAM,iBAAiB,CAAA;AAExE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAGzD,MAAM,MAAM,mBAAmB,GAAG;IAChC,qFAAqF;IACrF,MAAM,EAAE,YAAY,CAAA;IACpB,qFAAqF;IACrF,KAAK,CAAC,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAA;IACrC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC,CAAA;IACtD;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAA;IACjC,8CAA8C;IAC9C,kBAAkB,CAAC,EAAE,oBAAoB,CAAC,oBAAoB,CAAC,CAAA;IAC/D;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,SAAS,CAAA;IACzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,CAAA;CAChD,GAAG,IAAI,CAAC,oBAAoB,EAAE,UAAU,GAAG,OAAO,GAAG,oBAAoB,GAAG,sBAAsB,CAAC,CAAA;AAIpG,KAAK,iBAAiB,GAAG;IACvB,QAAQ,EAAE,SAAS,CAAA;IACnB,IAAI,EAAE,SAAS,CAAA;IACf,QAAQ,EAAE,mBAAmB,CAAC,UAAU,CAAC,CAAA;CAC1C,CAAA;AAED,KAAK,aAAa,GAAG;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAA;AAwB1D,mGAAmG;AACnG,qBAAa,YAAa,SAAQ,SAAS,CAAC,iBAAiB,EAAE,aAAa,CAAC;gBAC/D,KAAK,EAAE,iBAAiB;IAKpC,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,aAAa;IAIrD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI;IAczD,MAAM,IAAI,SAAS;CAO7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAYD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAmBvC;AAqMD,wBAAgB,cAAc,CAAC,EAC7B,MAAM,EACN,KAAK,EACL,SAAS,EACT,QAAQ,EACR,aAAoB,EACpB,cAAc,EACd,kBAA2B,EAC3B,KAAK,EACL,aAAyB,EACzB,eAAe,EACf,GAAG,IAAI,EACR,EAAE,mBAAmB,+BA6ErB"}

package/dist/provider/index.js

@@ -242,6 +242,7 @@ function BasaltProvider({
   defaultColorScheme = "dark",
   nonce,
   sizeClassHint = "compact",
+  navCommandLabel,
   ...rest
 }) {
   useDuplicateProviderGuard();
@@ -259,8 +260,8 @@ function BasaltProvider({
   const [devTool, setDevTool] = useState(null);
   const [actions, setActions] = useState([]);
   const refreshActions = useCallback(
-    () => setActions(buildSpotlightActions(router, setDevTool)),
-    [router]
+    () => setActions(buildSpotlightActions(router, setDevTool, navCommandLabel)),
+    [router, navCommandLabel]
   );
   useEffect(refreshActions, [refreshActions]);
   const resolvedTheme = useLabTheme(theme);

package/dist/provider/spotlight-actions.d.ts

@@ -1,10 +1,11 @@
 /**
  * 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';
 import type { AnyRouter } from '@tanstack/react-router';
+import type { FlatNavItem } from '../router-tanstack/nav.js';
 import type { BasaltDevDockTool } from '../dev-dock.js';
-export declare function buildSpotlightActions(router: AnyRouter, openDevTool: (tool: BasaltDevDockTool) => void): SpotlightActionData[];
+export declare function buildSpotlightActions(router: AnyRouter, openDevTool: (tool: BasaltDevDockTool) => void, navCommandLabel?: (item: FlatNavItem) => string): SpotlightActionData[];
 //# sourceMappingURL=spotlight-actions.d.ts.map

package/dist/provider/spotlight-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spotlight-actions.d.ts","sourceRoot":"","sources":["../../src/provider/spotlight-actions.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAIvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AASpD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,GAC7C,mBAAmB,EAAE,CA8CvB"}
+{"version":3,"file":"spotlight-actions.d.ts","sourceRoot":"","sources":["../../src/provider/spotlight-actions.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAA;AAIvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AASpD,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,CAAC,IAAI,EAAE,iBAAiB,KAAK,IAAI,EAC9C,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAC9C,mBAAmB,EAAE,CAiDvB"}

package/dist/provider/spotlight-actions.js

@@ -7,9 +7,10 @@ const DEV_TOOLS = [
   { tool: "query", label: "Query devtools" },
   { tool: "theme", label: "Theme lab" }
 ];
-function buildSpotlightActions(router, openDevTool) {
+function buildSpotlightActions(router, openDevTool, navCommandLabel) {
   const actions = [];
-  for (const [id, cmd] of Object.entries(getActiveCommands())) {
+  const commands = getActiveCommands();
+  for (const [id, cmd] of Object.entries(commands)) {
     if (cmd.when !== void 0 && !cmd.when()) continue;
     actions.push({
       id,
@@ -27,9 +28,10 @@ function buildSpotlightActions(router, openDevTool) {
   if (nav !== void 0) {
     for (const item of flattenNav(nav)) {
       if (item.disabled === true) continue;
+      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/dist/shell/app-sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAe,cAAc,EAAE,MAAM,aAAa,CAAA;AAI5E,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAgBjF,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C;;;;OAIG;IACH,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IACjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CACxB,CAAA;AAmTD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA2KhD"}
+{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAe,cAAc,EAAE,MAAM,aAAa,CAAA;AAI5E,OAAO,KAAK,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAE1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAgBjF,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C;;;;OAIG;IACH,KAAK,EAAE,WAAW,GAAG;QAAE,IAAI,CAAC,EAAE,eAAe,EAAE,CAAA;KAAE,CAAA;IACjD,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAA;IACvC;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;;OAIG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG;QAAE,OAAO,CAAC,EAAE,oBAAoB,CAAA;KAAE,CAAA;IACjE;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CACxB,CAAA;AAiUD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,+BA2KhD"}

package/dist/shell/app-sidebar.js

@@ -88,14 +88,21 @@ function NavLinkBody({
   collapsed = false
 }) {
   const Anchor = item.Anchor;
+  const icon = iconOrInitial(item.icon, item.label);
+  const railDot = collapsed && (item.badge !== void 0 && item.badge !== null || Boolean(item.count));
   const shared = {
     classNames: { root: classes.link },
     label: item.label,
-    leftSection: iconOrInitial(item.icon, item.label),
+    leftSection: railDot ? /* @__PURE__ */ jsxs("span", { className: classes.navIconDotHost, children: [
+      icon,
+      /* @__PURE__ */ jsx("span", { className: classes.blockDot, "data-basalt-rail-dot": true, "aria-hidden": true })
+    ] }) : 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 ? /* @__PURE__ */ jsx(NavCountBadge, { count: item.count }) : void 0),
     active,
     // Basalt is the one that stamps `aria-current`, not the theme and not a router `<Link>`'s own

package/dist/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/dist/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/dist/tokens/core.d.ts

@@ -190,18 +190,19 @@ export declare function seriesTokens<const T extends SeriesMap>(map: T, prefix?:
  * not the widened SeriesMap, enabling downstream exact-key checks in groupTokens / seriesTokens).
  */
 export declare function defineSeries<const T extends SeriesMap>(map: T): T;
-/** Runtime key of the {@link SeriesGroup} brand. */
-declare const SERIES_GROUP: unique symbol;
+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;
+};
 /**
- * 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.
+ * 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 [SERIES_GROUP]: {
-        readonly prefix: string;
-        readonly map: SeriesMap;
-    };
+    readonly [key: string]: GroupRef;
 };
 /**
  * Build a single namespaced group's token refs (`var(--vx-<name>-<key>)`).
@@ -210,8 +211,8 @@ export type SeriesGroup = {
  * error at the call site rather than a silent `Record<string, string>` widening.
  */
 export declare function groupTokens<const T extends SeriesMap>(name: string, map: T): {
-    [K in keyof T]: string;
-} & SeriesGroup;
+    readonly [K in keyof T]: GroupRef;
+};
 /**
  * The attribute + values the per-scheme blocks key off. Defaults reproduce Mantine's own toggle
  * (`data-mantine-color-scheme` = `dark` / `light`), so a consumer only names the axis it differs

package/dist/tokens/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/tokens/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/tokens/core.ts"],"names":[],"mappings":"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"}

package/dist/tokens/core.js

@@ -596,7 +596,15 @@ function buildPaletteCss(opts = {}, data = buildPaletteData()) {
   const derived = extraDerived ? `${derivedBlock}
 ${extraDerived}` : derivedBlock;
   const side = (s) => {
-    const extra = groups.map((group) => groupSide(group[SERIES_GROUP].prefix, group[SERIES_GROUP].map, s)).join("\n");
+    const extra = groups.map((group) => {
+      const payload = group[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}
 ${extra}` : framework;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v2.0.1
+# basalt-ui v2.0.3
 # Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets
 #
 # Entry points: use the exact import specifier below; do not guess.
@@ -13,7 +13,7 @@
 # A subpath's `Install:` line is its required peers; `OptionalPeers:` are import()-only, install on use.
 
 Package: basalt-ui
-Version: 2.0.1
+Version: 2.0.3
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, TanStack Charts, toolchain presets",
   "keywords": [
     "charts",

package/src/cli/config.ts

@@ -4,6 +4,16 @@ import type { GuardKind, GuardSeverity } from '../guard'
 
 /** Shape of the optional `"basalt"` key in a consumer's package.json. */
 export type BasaltConfig = {
+  /**
+   * The Vite app's directory relative to the install root, for a workspace monorepo whose manifest,
+   * `.claude/` and AGENTS block live at the root. App-scoped checks (`tsconfig-base`, `app-wiring`)
+   * and the router seeds target it. Default: the single workspace package that depends on basalt-ui
+   * and has a Vite entry, else the root itself.
+   *
+   * @example
+   * { app: 'apps/dashboard' }
+   */
+  app?: string
   /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
   roots?: string[]
   /** Files exempt from the scan (they ARE the palette source). Default: argo's exempt set. */
@@ -181,7 +191,7 @@ export function resolveRoots(cfg: BasaltConfig): string[] {
 
 /** Every `BasaltConfig` key, as data for `doctor`'s `config-keys` (a test pins it to the type). */
 export const BASALT_CONFIG_KEYS = (
-  'roots exempt profile include spacingSteps severity forbiddenAccents accentHue rawRadius rawSurface ' +
+  'app roots exempt profile include spacingSteps severity forbiddenAccents accentHue rawRadius rawSurface ' +
   'cardWithBorder offSystemSurfaceVar mantineShadeIndex rawHtmlLayout inlineSpacing inlineDisplay ' +
   'rawMotionValue rawFormControl sub16InputFont seriesModulePath exemptRules aiMajorSkewReason'
 ).split(' ') as (keyof BasaltConfig)[]

package/src/cli/doctor-upgrade.ts

@@ -352,9 +352,53 @@ function registersRouterPlugin(src: string): boolean {
   })
 }
 
+const RELATIVE_IMPORT =
+  /(?:\b(?:import|export)\b[^'";]*?\bfrom|\bimport)\s*['"](\.{1,2}\/[^'"]+)['"]/g
+
+/** The source file a relative specifier names: as written, `.ts`/`.tsx` appended, or a directory index. */
+function resolveRelative(from: string, spec: string): string | null {
+  const base = resolve(dirname(from), spec.replace(/\.[jt]sx?$/, ''))
+  return (
+    [
+      resolve(dirname(from), spec),
+      `${base}.ts`,
+      `${base}.tsx`,
+      `${base}/index.ts`,
+      `${base}/index.tsx`,
+    ].find((f) => /\.[jt]sx?$/.test(f) && existsSync(f)) ?? null
+  )
+}
+
+/**
+ * Whether a module the entry imports (relative imports, three deep) calls `createBasaltRouter` —
+ * the router often lives in a singleton module other code also imports.
+ */
+function routerCreatedInImports(cwd: string, entry: string): boolean {
+  const seen = new Set([resolve(cwd, entry)])
+  let frontier = [...seen]
+  for (let depth = 0; depth < 3 && frontier.length > 0; depth++) {
+    const next: string[] = []
+    for (const file of frontier) {
+      for (const m of (readIfExists(file) ?? '').matchAll(RELATIVE_IMPORT)) {
+        const dep = resolveRelative(file, m[1] ?? '')
+        if (dep === null || seen.has(dep)) continue
+        seen.add(dep)
+        const { code, inLiteral } = tokenize(readIfExists(dep) ?? '')
+        const called = [...code.matchAll(/\bcreateBasaltRouter\b/g)].some(
+          (c) => !inLiteral(c.index),
+        )
+        if (called) return true
+        next.push(dep)
+      }
+    }
+    frontier = next
+  }
+  return false
+}
+
 /**
  * `app-wiring`: the entry module `index.html` loads (default src/main.tsx) mounts `BasaltProvider`
- * on a `createBasaltRouter` router, and the router tree is generated: the vite config calls a
+ * on a `createBasaltRouter` router (called in the entry or a module it imports), and the router tree is generated: the vite config calls a
  * binding imported from `@tanstack/router-plugin` in `plugins`, or a `routeTree.gen.*` already sits
  * beside the entry (or in src/). `basaltViteConfig` does not register that plugin, so naming it
  * proves nothing.
@@ -371,7 +415,10 @@ export function appWiringCheck(cwd: string): Check {
     const { code, inLiteral } = tokenize(text)
     const used = (name: string): boolean =>
       [...code.matchAll(new RegExp(`\\b${name}\\b`, 'g'))].some((m) => !inLiteral(m.index))
-    const missing = ['BasaltProvider', 'createBasaltRouter'].filter((name) => !used(name))
+    const missing = ['BasaltProvider', 'createBasaltRouter'].filter(
+      (name) =>
+        !used(name) && !(name === 'createBasaltRouter' && routerCreatedInImports(cwd, entry)),
+    )
     if (missing.length > 0) {
       return {
         fail:

package/src/cli/doctor.ts

@@ -26,7 +26,9 @@ import {
   readBasaltConfig,
   readIfExists,
   readManifest,
+  resolveAppDir,
   resolveProjectDir,
+  ROUTER_SEED_DESTS,
   sameFile,
   scannableFiles,
   scanBlock,
@@ -135,7 +137,18 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
 export function doctor(invocationCwd: string = process.cwd(), flags: string[] = []): number {
   if (conflictingProfileFlags('doctor', flags)) return 1
   const project = resolveProjectDir(invocationCwd)
-  const cwd = project.dir
+  // Inside the app package of a monorepo the manifest is above: read the install root instead.
+  const aboveRoot =
+    project.relocatedFrom === null && !existsSync(resolve(project.dir, MANIFEST_PATH))
+      ? findManifestAbove(project.dir)
+      : null
+  const insideApp =
+    aboveRoot !== null &&
+    (() => {
+      const app = resolveAppDir(aboveRoot)
+      return !('error' in app) && app.dir === project.dir
+    })()
+  const cwd = insideApp && aboveRoot !== null ? aboveRoot : project.dir
   const cfg = readBasaltConfig(cwd)
   const result: DoctorResult = { hardFailures: 0, warnings: 0, skipped: 0 }
   const lines: string[] = [`\nbasalt-ui doctor — ${cwd}\n`]
@@ -160,6 +173,11 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     lines.push(`  → BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.\n`)
   }
 
+  if (insideApp)
+    lines.push(`  → ${project.dir} is the app package; checking the install root ${cwd}.\n`)
+
+  const app = resolveAppDir(cwd)
+  const appDir = 'error' in app ? cwd : app.dir
   const profile = declaredProfile(cfg, flags)
   if (profile === 'tokens-only') {
     lines.push(
@@ -192,6 +210,22 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
 
   const install = findBasaltInstall(cwd)
 
+  // ── App placement: the agent layer is at the root, the app is where `resolveAppDir` says ────
+  if ('error' in app) {
+    fail(`app-dir: ${app.error}`)
+  } else if (app.rel !== '') {
+    pass(`app-dir: the app is ${app.rel} (agent layer and manifest stay at the install root)`)
+    const ledger = readManifest(cwd).files
+    for (const seed of Object.values(ROUTER_SEED_DESTS)) {
+      if (ledger[seed] !== undefined && existsSync(resolve(cwd, seed))) {
+        warn(
+          `app-dir: ${seed} was seeded at the install root by an earlier \`sync\`, but the app is ` +
+            `${app.rel} — it is dead code there. Delete it (\`sync\` seeds ${app.rel}/${seed} instead).`,
+        )
+      }
+    }
+  }
+
   // ── Hard check 2: install matches the manifest, and doctor says WHERE (the AGENTS-block's claim)
   const manifestVersion = profile === 'tokens-only' ? undefined : readManifest(cwd).basaltVersion
   const at = install.dir === null ? '' : `${relative(cwd, install.dir)} (${install.version})`
@@ -380,7 +414,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     )
   } else {
     const upgrade: [string, Check][] = [
-      ['tsconfig-base: tsconfig.json extends the shipped preset', tsconfigBaseCheck(cwd)],
+      ['tsconfig-base: tsconfig.json extends the shipped preset', tsconfigBaseCheck(appDir)],
       [
         'retired-lint-rules: .oxlintrc.json sets no retired basalt/* rule',
         retiredLintRulesCheck(cwd, install),
@@ -391,7 +425,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
       ],
       [
         'app-wiring: the entry mounts BasaltProvider and the router tree is generated',
-        appWiringCheck(cwd),
+        appWiringCheck(appDir),
       ],
       ['exact-peers: installed exact-pinned peers match basalt-ui', exactPeersCheck(cwd, install)],
       [

package/src/cli/index.ts

@@ -474,6 +474,8 @@ type TemplateVars = {
    * `bunx basalt-ui` only as the pre-install fallback.
    */
   BASALT_BIN: string
+  /** The CI gate steps after install: `make check` when the repo owns one, else the built-in set. */
+  GATE_STEPS: string
 }
 
 // The block markers the AGENTS.md template emits. The begin marker carries the framework version
@@ -536,6 +538,26 @@ export function basaltBinCommand(install: BasaltInstall, cwd: string): string {
   return `${relativePosix(cwd, binDir).replace(/^\.\//, '')}/basalt-ui`
 }
 
+/**
+ * The consumer owns the CI gate when its Makefile has a `check:` target: `doctor` and `sync --check`
+ * stay as steps of their own (drift is never skippable), then `make check` replaces the built-in
+ * lint/theme/format steps. Without one, the built-in steps run. Rendered at `{{GATE_STEPS}}`.
+ */
+export function ciGateSteps(cwd: string): string {
+  const owned = /^check\s*:/m.test(readIfExists(resolve(cwd, 'Makefile')) ?? '')
+  const drift = ["- run: '{{BASALT_BIN}} doctor'", "- run: '{{BASALT_BIN}} sync --check'"]
+  const steps = owned
+    ? [...drift, '- run: make check']
+    : [
+        '- run: bunx oxlint .',
+        drift[0],
+        "- run: '{{BASALT_BIN}} check-theme'",
+        drift[1],
+        "- run: bunx oxfmt {{ROOTS_GLOBS}} '!**/dist/**' --check",
+      ]
+  return steps.join('\n      ')
+}
+
 /** Build the template-variable map from the framework root + consumer cwd/config. */
 function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): TemplateVars {
   const install = findBasaltInstall(cwd)
@@ -548,15 +570,20 @@ function buildTemplateVars(pkgRoot: string, cwd: string, cfg: BasaltConfig): Tem
     OXLINT_PRESET_PATH: shippedAssetPath(install, cwd, OXLINT_FILES.preset),
     LEFTHOOK_PRESET_PATH: shippedAssetPath(install, cwd, 'configs/lefthook.yml'),
     BASALT_BIN: basaltBinCommand(install, cwd),
+    GATE_STEPS: ciGateSteps(cwd),
   }
 }
 
 /** Substitute every `{{KEY}}` placeholder from the variable map; unknown keys are left verbatim. */
 function fillTemplate(tpl: string, vars: TemplateVars): string {
-  return tpl.replace(/\{\{(\w+)\}\}/g, (m, key: string) => {
-    const v = (vars as Record<string, string>)[key]
-    return v ?? m
-  })
+  const fill = (text: string): string =>
+    text.replace(/\{\{(\w+)\}\}/g, (m, key: string) => {
+      const v = (vars as Record<string, string>)[key]
+      return v ?? m
+    })
+  // The marker is a YAML comment so the template stays valid YAML; GATE_STEPS itself carries
+  // placeholders, so it expands before the generic pass.
+  return fill(tpl.replace('# {{GATE_STEPS}}', vars.GATE_STEPS))
 }
 
 /**
@@ -654,6 +681,56 @@ export const ROUTER_SEED_DESTS = {
   main: 'src/main.tsx',
 } as const
 
+/** A router seed's dest, relative to the install root: under the app dir when it is not the root. */
+export function routerSeedDest(appRel: string, seed: keyof typeof ROUTER_SEED_DESTS): string {
+  return appRel === '' ? ROUTER_SEED_DESTS[seed] : `${appRel}/${ROUTER_SEED_DESTS[seed]}`
+}
+
+/** The app directory a command's app-scoped half targets: `rel` is '' when it is the install root. */
+export type AppResolution = { dir: string; rel: string } | { error: string }
+
+/** `dir` relative to `root` without relativePosix's leading `./` ('' for the root itself). */
+const appRelative = (root: string, dir: string): string =>
+  relativePosix(root, dir).replace(/^\.\/?/, '')
+
+const hasViteEntry = (dir: string): boolean =>
+  existsSync(resolve(dir, 'src/main.tsx')) || existsSync(resolve(dir, 'index.html'))
+
+/**
+ * Where the Vite app lives relative to the install root `root` (manifest, `.claude/`, AGENTS block).
+ * ONE resolution for `doctor`, `sync` and `init`, in order: `basalt.app` in the root package.json;
+ * else the single workspace package that depends on basalt-ui AND has a Vite entry; else `root`
+ * itself (a single-package app). Two such packages is an error — the choice is not inferable.
+ */
+export function resolveAppDir(root: string): AppResolution {
+  const self = { dir: root, rel: '' }
+  const explicit = readBasaltConfig(root).app
+  if (explicit !== undefined) {
+    const dir = resolve(root, explicit)
+    const rel = appRelative(root, dir)
+    if (rel.startsWith('..') || !existsSync(resolve(dir, 'package.json'))) {
+      return {
+        error: `basalt.app "${explicit}" must be a directory with a package.json inside ${root}.`,
+      }
+    }
+    return dir === root ? self : { dir, rel }
+  }
+  const candidates = collectWorkspacePackages(root).packages.filter(
+    (pkg) => pkg.dir !== root && hasDependency(pkg.dir, 'basalt-ui') && hasViteEntry(pkg.dir),
+  )
+  if (candidates.length === 0) return self
+  const [only] = candidates
+  if (candidates.length === 1 && only !== undefined) {
+    return { dir: only.dir, rel: appRelative(root, only.dir) }
+  }
+  const names = candidates.map((pkg) => appRelative(root, pkg.dir)).join(', ')
+  return {
+    error:
+      `${candidates.length} workspace packages depend on basalt-ui and have a Vite entry (${names}) — ` +
+      'cannot tell which is the app. Set `basalt.app` (e.g. `"basalt": { "app": "apps/web" }`) in the root package.json.',
+  }
+}
+
 /** True when `pkgName` appears in the consumer's dependencies, devDependencies, or peerDependencies. */
 function hasDependency(cwd: string, pkgName: string): boolean {
   try {
@@ -687,12 +764,18 @@ export type PlacementFlags = {
   /** Absolute path of the detected repo root. Meaningful only when `isPackageRepoRoot` is false —
    *  otherwise it equals the package dir and is never read. */
   repoRoot: string
+  /** The app directory relative to the install root ('' = the root itself); see {@link resolveAppDir}. */
+  appRel: string
+  /** Non-null when the app directory is ambiguous or invalid: commands refuse rather than guess. */
+  appError: string | null
 }
 
 /** The default placement — today's single-package-at-repo-root behaviour, unconditionally. */
 export const ROOT_PLACEMENT: PlacementFlags = {
   isPackageRepoRoot: true,
   repoRoot: '',
+  appRel: '',
+  appError: null,
 }
 
 /**
@@ -725,9 +808,12 @@ export function oxlintBinResolves(dir: string): boolean {
 /** Resolve a run's placement flags once, from the consumer cwd. */
 export function resolvePlacement(cwd: string): PlacementFlags {
   const repoRoot = findRepoRoot(cwd)
+  const app = resolveAppDir(cwd)
   return {
     isPackageRepoRoot: repoRoot === cwd,
     repoRoot,
+    appRel: 'error' in app ? '' : app.rel,
+    appError: 'error' in app ? app.error : null,
   }
 }
 
@@ -854,7 +940,7 @@ export function managedFiles(placement: PlacementFlags = ROOT_PLACEMENT): Manage
 
   /** TanStack Router root route with QueryClient context wiring (seed — consumer-owned after init). */
   const rootRoute: ManagedFile = {
-    dest: ROUTER_SEED_DESTS.root,
+    dest: routerSeedDest(placement.appRel, 'root'),
     mode: 'seed',
     source: 'agent/templates/__root.tpl',
     render: (ctx) => {
@@ -866,7 +952,7 @@ export function managedFiles(placement: PlacementFlags = ROOT_PLACEMENT): Manage
 
   /** The leaf `NAV` module `__root.tsx` imports (seed — consumer-owned after init). */
   const navModule: ManagedFile = {
-    dest: ROUTER_SEED_DESTS.nav,
+    dest: routerSeedDest(placement.appRel, 'nav'),
     mode: 'seed',
     source: 'agent/templates/nav.tpl',
     render: (ctx) => readSource(ctx.pkgRoot, 'agent/templates/nav.tpl'),
@@ -874,7 +960,7 @@ export function managedFiles(placement: PlacementFlags = ROOT_PLACEMENT): Manage
 
   /** The 2.0 entry: mounts the router and declares the `Register` augmentation `defineNav` needs. */
   const mainEntry: ManagedFile = {
-    dest: ROUTER_SEED_DESTS.main,
+    dest: routerSeedDest(placement.appRel, 'main'),
     mode: 'seed',
     source: 'agent/templates/main.tpl',
     render: (ctx) => readSource(ctx.pkgRoot, 'agent/templates/main.tpl'),

package/src/cli/init.ts

@@ -13,6 +13,7 @@ import {
   declaredProfile,
   readBasaltConfig,
   ROUTER_SEED_DESTS,
+  routerSeedDest,
   findBasaltInstall,
   managedFiles,
   mergeOxlintExtends,
@@ -82,6 +83,12 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
     )
   }
 
+  const appError = resolvePlacement(cwd).appError
+  if (appError !== null) {
+    console.error(`✖ basalt-ui init: ${appError}`)
+    return 1
+  }
+
   const rootsState = reconcileRoots(cwd, { write: true })
 
   // Built AFTER the roots patch — every roots-derived template variable reads the key just written.
@@ -120,7 +127,9 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   const placement = resolvePlacement(cwd)
   // A tokens-only consumer has no use for the Mantine/React scaffolds (doctor skips them there too).
   const tokensOnly = declaredProfile(readBasaltConfig(cwd), []) === 'tokens-only'
-  const routerSeeds: string[] = Object.values(ROUTER_SEED_DESTS)
+  const routerSeeds: string[] = (
+    Object.keys(ROUTER_SEED_DESTS) as (keyof typeof ROUTER_SEED_DESTS)[]
+  ).map((seed) => routerSeedDest(placement.appRel, seed))
   const files = managedFiles(placement).filter((f) => !(tokensOnly && routerSeeds.includes(f.dest)))
 
   const writtenFiles: string[] = []