basalt-ui 1.23.1 → 1.25.0

package/agent/rules/basalt-data.md

@@ -59,6 +59,34 @@ const columns = [
 | `initialSorting`   | `SortingState`              | `[]`     | Initial sort state; drives `useState` initializer      |
 | `onSortingChange`  | `(s: SortingState) => void` | —        | Called whenever sorting changes; omit for uncontrolled |
 
+Body chrome — all conditional pass-throughs to Mantine `Table` except `withTableBorder`, which
+basalt defaults to `true`:
+
+| Prop                                    | Type                            | Notes                                                                |
+| --------------------------------------- | ------------------------------- | -------------------------------------------------------------------- |
+| `maxHeight`                             | `number \| string`              | Caps the body height — renders `Table.ScrollContainer type="native"` |
+| `minWidth`                              | `number \| string`              | Same container; `maxHeight` alone passes `minWidth={0}`              |
+| `stickyHeader` / `stickyHeaderOffset`   | `boolean` / `number \| string`  | Forwarded to Mantine; pair with `maxHeight`                          |
+| `verticalSpacing` / `horizontalSpacing` | `MantineSpacing`                | Cell padding                                                         |
+| `withRowBorders` / `withTableBorder`    | `boolean`                       | `withTableBorder` defaults `true` here, overriding Mantine's `false` |
+| `meta: { align }` (per column)          | `'left' \| 'center' \| 'right'` | Sets `textAlign` on BOTH the `th` and the `td`                       |
+| `meta: { numeral: false }` (per column) | `boolean`                       | Opts a numeric cell OUT of the mono-numeral style. Opt-out only      |
+
+`meta.align` is a `ColumnMeta` module augmentation, so a typo'd key is a tsc error and a value
+outside the union **throws** naming the column — a money column never silently left-aligns. Set it
+once on the column def instead of repeating `textAlign: 'right'` on the header and the cell.
+
+**`meta.numeral: false` is needed less often than it looks.** The auto style sets `fontFamily`,
+`fontSize`, `fontWeight`, `fontVariantNumeric` and `color` on the `<td>` whenever the raw value is a
+number — but a child `Text` sets its own `color` and `fontWeight` and wins those, and never sets a
+`fontFamily`. **Only `fontFamily` leaks.** So `c="dimmed"` is not a reason to opt out (and on a
+percentage column the mono figures are what you want); `fw={600}` on an accent figure is, because
+the `<td>`'s monospace still overrides the family the `Text` inherited. One consumer measured this
+across three tables: **3 columns** genuinely needed the opt-out, not the 4 that were assumed. Reach
+for it when the cell renders its own chrome — a coloured `Text`, a `Badge`, a sparkline — and check
+what actually leaked before adding it. `null` is worth a thought too: `typeof null === 'object'`, so
+a `number | null` column goes mono only on its non-null rows, which is worse than uniformly wrong.
+
 ### Controlled sorting and URL sync
 
 `initialSorting` seeds the internal `useState` and `onSortingChange` is called on every sort
@@ -122,18 +150,57 @@ col.display({ id: 'actions', header: 'Actions', cell: (ctx) => <Button>Delete {c
 `ColumnDef<T>` defaults `TValue` to `unknown`, not `any`. Never cast column defs to `any` — use
 the correct `ColumnDef<T>` type or `ColumnDef<T, unknown>`.
 
-### Deferred for later versions
+### Also shipped, and easy to miss
+
+Global search (`enableGlobalFilter`, `globalFilterPlaceholder`, `searchIcon`,
+`initialGlobalFilter`, `onGlobalFilterChange`), faceted filters (`facets`), a toolbar slot
+(`toolbarActions`), pagination client- or server-side (`enablePagination`, `pageSizeOptions`,
+`initialPagination`, `onPaginationChange`, `manualPagination`, `rowCount`, `pageCount`) and column
+pinning (`enablePinning`, `initialColumnPinning`). **Don't hand-roll any of these** — read the props
+on the type, they are all there.
+
+### `manualPagination` imposes a contract on the rest of the props
+
+Adopting it makes `data` **one server page** while the bar still reads `Showing 1–25 of 412`. Every
+other client-side control then becomes a claim about 412 rows it can only make about 25 — a sort
+that reorders one page under a header chevron that says it sorted all of them is a plausible, wrong
+answer with nothing on screen to give it away. So each control has to be resolved explicitly; there
+is no safe default, because only the call site knows whether the server does the work.
+
+| With `manualPagination`   | Resolve it with                                                                     |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| the pagination bar itself | `enablePagination` (without it `manualPagination` is inert) + `rowCount`            |
+| sorting                   | `manualSorting` + sort in the `onSortingChange` request, or `enableSorting={false}` |
+| `enableGlobalFilter`      | `manualFiltering` + filter in the `onGlobalFilterChange` request                    |
+| `facets`                  | `manualFiltering` + `onColumnFiltersChange`                                         |
+
+```tsx
+<BasaltDataTable
+  data={page.rows}
+  columns={columns}
+  enablePagination
+  manualPagination
+  rowCount={page.total}
+  manualSorting
+  onSortingChange={(s) => refetch({ sort: s[0] })}
+  onPaginationChange={(p) => refetch({ page: p })}
+/>
+```
 
-The 1.0 table ships sorting only. Natural extensions are **not** in scope yet:
+`manualSorting` / `manualFiltering` don't switch the controls off — the headers and inputs stay
+live and keep reporting through their `on*Change` callbacks. They stop the table from _recomputing_
+the answer locally, so what renders is the order and the selection the server sent.
 
-- Filtering (column or global search)
-- Pagination (client-side or server-side)
-- Row selection (checkboxes)
-- Row expansion / sub-rows
+**Unresolved, it is not silent.** A contradiction throws in dev naming every breach at once, and a
+production bundle (where the throw is constant-folded away) degrades to the honest table instead:
+no sort headers, no filter controls, no `of N` it cannot stand behind, plus one `console.error`.
+You will never get the plausible wrong answer, but you also won't get sorting you thought you had —
+so read the throw, don't work around it.
 
-Add them when a concrete consumer need arises; keep the API additive. Controlled (fully external)
-sorting for `BasaltDataTable` itself is likewise deferred — `onSortingChange` above is the current
-sync seam.
+Still deferred: row selection, row expansion / sub-rows, and fully controlled (external) sorting
+STATE — `manualSorting` hands the _work_ to the server, but the table still owns the `SortingState`
+and reports it through `onSortingChange`. Add them when a concrete consumer need arises; keep the API
+additive.
 
 ### The blessed lane vs the raw escape hatch
 
@@ -166,9 +233,34 @@ const table = useReactTable({ data: rows, columns, getCoreRowModel: getCoreRowMo
 // table.getHeaderGroups() / table.getRowModel().rows, rendered with flexRender(...) and your own markup
 ```
 
-Reach for the escape hatch only when `BasaltDataTable`'s props genuinely can't express the shape —
-grid feature growth (pagination, server-side data, column visibility, filtering) is consumer-pulled
-future work, not a reason to bypass the blessed lane by default.
+Reach for the escape hatch only when `BasaltDataTable`'s props genuinely can't express the shape.
+Pagination, server-side data and filtering are **not** among those cases any more — see above.
+
+**Both lanes scroll through the same node.** An escape-hatch table that needs a capped body wraps
+it in `<Table.ScrollContainer type="native" minWidth={0} maxHeight={320}>` — and that is byte for
+byte what `BasaltDataTable`'s `maxHeight`/`minWidth` render. The blessed lane and the escape cannot
+contradict each other on scrolling, and neither should reach for `type="scrollarea"`: `ScrollArea`'s
+custom viewport is the positioning context a sticky `<thead>` resolves against, so the default type
+pins the header to the page viewport instead of the table's box. (`basalt/raw-scroll-container`
+takes no view here — it steers raw `overflow: auto`, and `Table.ScrollContainer` is a Mantine
+component, not a raw scroll box.)
+
+**Adopt the blessed lane for ownership, not for a line count.** Porting one consumer's three tables
+onto these props made them 341 → **370–379** lines, **29–38 longer**: a scratch port measured the
+low end, the consumer's own shipped port the high end, because it kept the comment blocks
+justifying each table's `numeral` opt-outs and its `enableSorting` decision. Accessor blocks at
+4–6 lines each cost more than an eight-`<Table.Td>` row at ~3 when every cell is bespoke, and the
+opt-outs are lines the hand-rolled version never had to write. Budget the high end. What the port
+bought was the `type="native"` footgun, alignment stated once instead of on both `th` and `td` —
+**4 literals in one table alone, 6 across the two that had alignment to state** — and
+sorting/filtering/pagination no longer being yours to maintain. Expect that trade, not a shrink.
+
+That consumer deliberately left the third table hand-rolled, and the reason generalises: four of
+its six columns would have needed `enableSorting: false` (three sparkline cells over `number[]`
+accessors, one status enum), and a numeric column rendering its own coloured `Text` would have
+needed a `numeral: false` it did not need before. A table with no sorting, no pagination, no filter
+and no alignment to declare is a layout grid that happens to use `<table>` — adopting the component
+there buys nothing and taxes you to switch off things you never asked for.
 
 ## BasaltVirtualList
 

package/agent/rules/basalt-query.md

@@ -76,6 +76,63 @@ const { data } = useSuspenseQuery(resourceQueries.summary())
   router's `ensureQueryData` (see basalt-router.md).
 - Wrap pages or panels in `<Suspense fallback={…}>` at the route level.
 
+## Rendering a query — use `QueryState`, don't write the switch
+
+```tsx
+import { QueryState } from 'basalt-ui' // NOT basalt-ui/query — it renders Mantine
+
+function Library() {
+  const q = useQuery(imageQueries.list())
+  return (
+    <QueryState
+      query={q}
+      variant="page" // or "section" for a panel inside a page
+      errorTitle="Could not load images"
+      empty={{ title: 'No images yet', description: 'Upload one to get started.' }}
+      isEmpty={(d) => d.items.length === 0}
+    >
+      {(data) => <ImageGrid items={data.items} />}
+    </QueryState>
+  )
+}
+```
+
+**Rendering only the empty branch is the bug this retires.** A consumer's library showed
+`No images` on a **500**, and a share detail showed `Share not found` on a dropped connection —
+"nothing here" is what an app renders when nobody wrote the other three branches. Swapping the
+import replaced 204 hand-rolled lines across 10 call sites there, with no prop or JSX change.
+
+Precedence, in evaluation order:
+
+| Condition                           | Renders                                                                   |
+| ----------------------------------- | ------------------------------------------------------------------------- |
+| `isError`, no `data`                | `ErrorState` — `errorTitle` / `errorFallback` / `errorAction`, with Retry |
+| no `data`, `fetchStatus === 'idle'` | the `empty` copy (nothing, if `empty` is omitted)                         |
+| no `data`                           | `loading`, else `LoadingState`                                            |
+| `data`, `isEmpty(data)`             | the `empty` copy                                                          |
+| `data`                              | `children` — a node, or `(data) => node`                                  |
+| `data` **and** `isError`            | a fixed _Showing cached data_ banner above `children`                     |
+
+`errorTitle` / `errorFallback` / `errorAction` reach the no-data error branch only; the stale-data
+banner carries its own copy. `empty` is `{ title, description?, icon?, action? }` — `description`
+is optional, so a compact panel needs no invented second sentence.
+
+**`useQuery`, not `useSuspenseQuery`.** A suspense read never hands you an undefined `data` or an
+error branch — it throws to the nearest boundary — so `QueryState` has nothing to decide there.
+Suspense + an error boundary and `QueryState` are the two ways to render a query; pick one per read.
+
+`LoadingState` and `ErrorState` ship beside it as the escape hatch for a page that must place its
+branches in different DOM positions.
+
+**`query` is a structural subset, checked at runtime.** It needs `{ data, isError, error,
+fetchStatus, refetch }` — a TanStack `UseQueryResult` satisfies it, and a hand-composed object is
+legal. Because the subset gives up the compiler's help, a missing `isError` **throws** naming the
+field rather than rendering a false claim about the data.
+
+Decoding an unknown error into copy is `toErrorMessage(err, fallback?)` from `basalt-ui/query`,
+with `errorStatus(err)` for the status; `toErrorMessage` folds the status into the fallback when the
+body decodes to nothing readable, so an opaque envelope never renders as `{}`.
+
 ## Mutations
 
 ```ts

package/agent/skills/basalt-app/SKILL.md

@@ -149,6 +149,13 @@ the single guard-exempt palette source — see `/basalt-charts`.
 - `sync --check` makes no changes and exits non-zero on drift — wire it as a CI freshness gate so a
   consumer can't silently fall behind the shipped rules.
 
+**Run it anywhere in the repo.** `sync`, `check-theme` and `doctor` share one resolver:
+`BASALT_CWD` → the cwd → declared workspace packages → a two-level descend → an **ascend** to the
+nearest ancestor carrying a basalt project, bounded by the repo root. Both directions announce the
+relocation in one sentence. From a sub-package `sync` now refreshes the parent install rather than
+refusing — but it still **exits 1 rather than scaffolding a second consumer** where the resolved
+project has no `.basalt/manifest.json`. Creating an install stays `basalt-ui init`'s decision.
+
 Seeds (`DESIGN.md`, the toolchain files, the scaffolds) are never reconciled or drift-reported —
 they are yours. The managed files (rules, skills, the CLAUDE block) are framework-owned and meant
 to be overwritten; the sync diff is where you review a doctrine change before committing it.

package/dist/cli/index.d.ts

@@ -454,8 +454,10 @@ type DoctorResult = {
  *      demonstrably not the installed package — see the check).
  *   5. The running CLI's own version matches the installed basalt-ui (catches a stale
  *      `bunx basalt-ui` npm fetch; best-effort, skipped if node_modules is absent).
- *   9. `basaltAppPlugin`'s (basalt-ui/vite) default icon filenames exist under public/ (only when
- *      a public/ dir exists at all — skipped otherwise).
+ *   9. The icon files `basaltAppPlugin` (basalt-ui/vite) references exist under the app package's
+ *      public/ — the package found via `basalt.roots`, not just cwd, so a root-invoked run still
+ *      reaches it. Never silently omitted: no plugin call anywhere is a pass that says so, a
+ *      plugin call with no public/ beside it is a SKIPPED.
  *   10 (second half). A declared `basalt.aiMajorSkewReason` when the ai majors currently AGREE — the
  *      exemption is stale and can be deleted; an exemption nobody revisits is how a real, later
  *      skew slips through unnoticed.

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

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

package/dist/cli/index.js

@@ -89,7 +89,7 @@ function readBasaltConfig(cwd) {
     return {};
   }
 }
-const SCANNABLE_EXT = /\.(?:tsx?|css|html?|webmanifest)$/;
+const SCANNABLE_EXT = /\.(?:tsx?|jsx|astro|vue|css|html?|webmanifest)$/;
 function walkSourceFiles(dir, out = []) {
   let entries;
   try {
@@ -170,6 +170,18 @@ function descendantProjects(cwd, depth = 2) {
   }
   return out;
 }
+function ascendantProject(cwd) {
+  const repoRoot = findRepoRoot(cwd);
+  if (repoRoot === cwd) return null;
+  let current = dirname(cwd);
+  for (; ; ) {
+    if (hasBasaltProject(current)) return current;
+    if (current === repoRoot) return null;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
 function resolveProjectDir(cwd) {
   const override = process.env["BASALT_CWD"];
   if (override !== void 0 && override.length > 0) {
@@ -183,6 +195,8 @@ function resolveProjectDir(cwd) {
     return { dir: candidates[0], relocatedFrom: cwd, ambiguous: null };
   }
   if (candidates.length > 1) return { dir: cwd, relocatedFrom: null, ambiguous: candidates };
+  const above = ascendantProject(cwd);
+  if (above !== null) return { dir: above, relocatedFrom: cwd, ambiguous: null };
   return { dir: cwd, relocatedFrom: null, ambiguous: null };
 }
 function declaredProfile(cfg, flags) {
@@ -1883,28 +1897,37 @@ basalt-ui doctor \u2014 ${cwd}
       `${lefthookGate.file} names no basalt gate and \`lefthook dump\` could not be run here, so this check cannot tell a missing gate from one wired through an \`include:\` or a remote config it never read \u2014 treat it as advisory. If the guard really is unwired, add "extends: [${lefthookCorrect}]" or your own command running \`${basaltBinCommand(install, cwd)} check-theme\`.`
     );
   }
-  const publicDir = resolve(cwd, "public");
-  if (profile === "framework" && existsSync(publicDir)) {
-    const icons = readAppIconsOption(cwd);
-    if (icons.kind === "none") {
+  if (profile === "framework") {
+    const appDir = findAppPluginDir(cwd, cfg);
+    const iconsIn = appDir ?? cwd;
+    const icons = readAppIconsOption(iconsIn);
+    const here = appDir === null || appDir === cwd ? "" : `${relativePosix(cwd, appDir)}/`;
+    const publicDir = resolve(iconsIn, "public");
+    if (appDir === null && !existsSync(publicDir)) {
+      pass("app icons: no `basaltAppPlugin(` under this project and no public/ \u2014 nothing to check");
+    } else if (icons.kind === "none") {
       pass("basaltAppPlugin is configured with no icons \u2014 nothing to check");
+    } else if (!existsSync(publicDir)) {
+      skip(
+        `app icons \u2014 ${here === "" ? "this package" : here.replace(/\/$/, "")} configures basaltAppPlugin, but there is no \`public/\` beside its vite config, so the files it references cannot be located. Use Vite's public-dir convention, or set \`icons: false\` if this app ships none.`
+      );
     } else if (icons.kind === "explicit") {
       const missing = icons.sources.filter(
         (src) => !existsSync(resolve(publicDir, src.replace(/^\//, "")))
       );
       if (missing.length > 0) {
         warn(
-          `basaltAppPlugin declares icon(s) that are not in public/: ${missing.join(", ")} \u2014 the manifest and the head links will point at a 404. Place them, or drop them from the \`icons\` array.`
+          `basaltAppPlugin declares icon(s) that are not in ${here}public/: ${missing.join(", ")} \u2014 the manifest and the head links will point at a 404. Place them, or drop them from the \`icons\` array.`
         );
       } else {
         pass(
-          `public/ has all ${icons.sources.length} icon file(s) basaltAppPlugin's \`icons\` option names`
+          `${here}public/ has all ${icons.sources.length} icon file(s) basaltAppPlugin's \`icons\` option names`
         );
       }
     } else {
       const dir = icons.kind === "default" ? icons.dir : null;
       const iconRoot = dir === null ? publicDir : resolve(publicDir, dir.replace(/^\//, ""));
-      const shown = dir === null ? "public/" : `public/${dir.replace(/^\//, "")}`;
+      const shown = dir === null ? `${here}public/` : `${here}public/${dir.replace(/^\//, "")}`;
       const missingIcons = DEFAULT_APP_ICON_FILES.filter((f) => !existsSync(resolve(iconRoot, f)));
       if (missingIcons.length > 0) {
         warn(
@@ -2049,6 +2072,31 @@ const VITE_CONFIG_FILES = [
   "vite.config.mjs",
   "vite.config.cjs"
 ];
+function findAppPluginDir(cwd, cfg) {
+  const seen = /* @__PURE__ */ new Set();
+  const candidates = [];
+  const add = (dir) => {
+    if (seen.has(dir)) return;
+    seen.add(dir);
+    candidates.push(dir);
+  };
+  add(cwd);
+  for (const root of resolveRoots(cfg)) {
+    let current = resolve(cwd, root);
+    while (current !== cwd && !relative(cwd, current).startsWith("..")) {
+      add(current);
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  }
+  for (const dir of candidates) {
+    const configPath = VITE_CONFIG_FILES.map((f) => resolve(dir, f)).find((f) => existsSync(f));
+    if (configPath === void 0) continue;
+    if (readIfExists(configPath)?.includes("basaltAppPlugin(") === true) return dir;
+  }
+  return null;
+}
 function balancedSpan(text, open) {
   const pairs = { "(": ")", "{": "}", "[": "]" };
   const closer = pairs[text[open]];
@@ -2108,12 +2156,36 @@ function generatedHeader(version, command, flags) {
 /* basalt-ui ${version} \u2014 \`basalt-ui ${invocation}\` */
 `;
 }
-function withoutProvenanceLine(css) {
+const PROVENANCE_VERSION = /^(\/\* basalt-ui )(\d+\.\d+\.\d+\S*)( — `basalt-ui (?:tokens:css|fonts:css)[^`]*` \*\/)$/;
+function provenanceVersion(css) {
+  const match = PROVENANCE_VERSION.exec(css.split("\n")[1] ?? "");
+  return match === null ? null : match[2];
+}
+function withoutProvenanceVersion(css) {
   const lines = css.split("\n");
-  if (lines.length < 2) return css;
-  lines[1] = "";
+  const line = lines[1];
+  if (line === void 0) return css;
+  const match = PROVENANCE_VERSION.exec(line);
+  if (match === null) return css;
+  lines[1] = `${match[1]}<version>${match[3]}`;
   return lines.join("\n");
 }
+function versionTriple(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(version);
+  return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function describeVersionSkew(onDisk, current) {
+  const a = versionTriple(onDisk);
+  const b = versionTriple(current);
+  if (a === null || b === null) return "a different";
+  for (let i = 0; i < 3; i++) {
+    const left = a[i];
+    const right = b[i];
+    if (left < right) return "an older";
+    if (left > right) return "a newer";
+  }
+  return "a different";
+}
 function normalizeColorFunctions(css) {
   return css.replace(/\b(rgba?|hsla?)\(([^()]*)\)/g, (_match, fn, args) => {
     const parts = args.split(",").map((part) => normalizeCssNumber(part.trim()));
@@ -2148,15 +2220,27 @@ function emitGeneratedCss(content, flags, cwd, command) {
       );
       return 1;
     }
-    if (withoutProvenanceLine(onDisk) === withoutProvenanceLine(content)) {
-      const staleProvenance = onDisk.split("\n")[1] !== content.split("\n")[1];
-      console.log(
-        `\u2713 ${command} --check: ${shown} is up to date.` + (staleProvenance ? " (Its provenance line still names an older basalt-ui; that line is deliberately not gated \u2014 re-run without --check whenever you want it refreshed.)" : "")
-      );
+    if (withoutProvenanceVersion(onDisk) === withoutProvenanceVersion(content)) {
+      const diskVersion = provenanceVersion(onDisk);
+      const currentVersion = provenanceVersion(content);
+      const skew = diskVersion !== null && currentVersion !== null && diskVersion !== currentVersion ? ` (Its provenance line names basalt-ui ${diskVersion}, ${describeVersionSkew(diskVersion, currentVersion)} release than the ${currentVersion} that just ran \u2014 only that version token is excluded from the comparison. Re-run without --check whenever you want it refreshed.)` : "";
+      console.log(`\u2713 ${command} --check: ${shown} is up to date.${skew}`);
       return 0;
     }
+    const diskLines = onDisk.split("\n");
+    const wantLines = content.split("\n");
+    const provenanceOnly = diskLines.length === wantLines.length && diskLines.every((line, i) => i === 1 || line === wantLines[i]) && diskLines[1] !== wantLines[1];
+    if (provenanceOnly) {
+      console.error(
+        `\u2716 ${command} --check: ${shown}'s \`@generated\` provenance line does not match the command that produced this content \u2014 the token values agree, line 2 does not.
+  on disk: ${diskLines[1]}
+  emitted: ${wantLines[1]}
+Line 1 tells the reader to regenerate with line 2, so line 2 is gated: run the emitted invocation without --check and commit the result, or change the flags this check runs with to the ones the file was really built from. Only the version token is exempt.`
+      );
+      return 1;
+    }
     console.error(
-      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${onDisk.split("\n").length} lines, emitted ${content.split("\n").length}) \u2014 re-run the same command without --check and commit the result. The \`@generated\` header's provenance line is excluded from this comparison, so a version bump alone never trips it.`
+      `\u2716 ${command} --check: ${shown} differs from what \`basalt-ui ${command}\` emits today (on disk ${diskLines.length} lines, emitted ${wantLines.length}) \u2014 re-run the same command without --check and commit the result. Only the \`@generated\` provenance line's VERSION token is excluded from this comparison, so a release alone never trips it \u2014 but its flags do.`
     );
     return 1;
   }

package/dist/dashboard/empty-state.d.ts

@@ -4,8 +4,12 @@ export type EmptyStateProps = {
     icon?: ReactNode;
     /** Head-font title (18px, weight 550, ink). */
     title: string;
-    /** Muted 15px description, capped at ~360px so it reads as a short explanation. */
-    description: string;
+    /**
+     * Muted 15px description, capped at ~360px so it reads as a short explanation. Optional: a
+     * compact panel ("No data yet") should not have to invent a second sentence, and five argo
+     * features wrapped this component solely to avoid doing so.
+     */
+    description?: string;
     /** Optional call-to-action rendered below the description. */
     action?: ReactNode;
     /** `'page'` (default) = generous padding for a full-page state; `'section'` = compact. */

package/dist/dashboard/empty-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/empty-state.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb,mFAAmF;IACnF,WAAW,EAAE,MAAM,CAAA;IACnB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAgB,GACjB,EAAE,eAAe,+BA0BjB"}
+{"version":3,"file":"empty-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/empty-state.tsx"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,MAAM,MAAM,eAAe,GAAG;IAC5B,uFAAuF;IACvF,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B,CAAA;AAED,wBAAgB,UAAU,CAAC,EACzB,IAAI,EACJ,KAAK,EACL,WAAW,EACX,MAAM,EACN,OAAgB,GACjB,EAAE,eAAe,+BA4BjB"}

package/dist/dashboard/empty-state.js

@@ -32,7 +32,7 @@ function EmptyState({
             children: title
           }
         ),
-        /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }, children: description }),
+        description !== void 0 && /* @__PURE__ */ jsx("span", { style: { fontSize: VX.text.md, color: VX.muted, maxWidth: 360 }, children: description }),
         action
       ]
     }

package/dist/dashboard/index.d.ts

@@ -2,4 +2,5 @@ export { DeltaBadge, type DeltaBadgeProps } from './delta-badge.js';
 export { StatCard, type StatCardProps, type StatCardTone } from './stat-card.js';
 export { EmptyState, type EmptyStateProps } from './empty-state.js';
 export { SettingsSection, type SettingsSectionProps, SettingsRow, type SettingsRowProps, DangerZone, type DangerZoneProps, } from './settings-section.js';
+export { QueryState, type QueryStateProps, type QueryStateLike, type QueryStateVariant, type QueryEmptyCopy, LoadingState, type LoadingStateProps, ErrorState, type ErrorStateProps, } from './query-state.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dashboard/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7E,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAA;AAChE,OAAO,EACL,eAAe,EACf,KAAK,oBAAoB,EACzB,WAAW,EACX,KAAK,gBAAgB,EACrB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,YAAY,EACZ,KAAK,iBAAiB,EACtB,UAAU,EACV,KAAK,eAAe,GACrB,MAAM,eAAe,CAAA"}

package/dist/dashboard/index.js

@@ -6,10 +6,18 @@ import {
   SettingsRow,
   DangerZone
 } from "./settings-section.js";
+import {
+  QueryState,
+  LoadingState,
+  ErrorState
+} from "./query-state.js";
 export {
   DangerZone,
   DeltaBadge,
   EmptyState,
+  ErrorState,
+  LoadingState,
+  QueryState,
   SettingsRow,
   SettingsSection,
   StatCard

package/dist/dashboard/query-state.d.ts

@@ -0,0 +1,96 @@
+import type { ReactNode } from 'react';
+/** `'page'` = a full route body (generous padding). `'section'` = a card/panel region (compact). */
+export type QueryStateVariant = 'page' | 'section';
+/**
+ * The structural subset of a TanStack `UseQueryResult` these components read.
+ *
+ * Typed as a SUBSET rather than as `UseQueryResult<T>` on purpose: a composed, derived or
+ * hand-rolled result must be passable without a cast, and
+ * these components stay independent of which `@tanstack/react-query` major a consumer pins. This
+ * is NOT a claim that the root barrel is free of that package — `./connectivity` imports
+ * `onlineManager` as a value and is re-exported from `src/index.ts`. The cost of the subset is
+ * that the compiler stops policing the shape — which is why {@link QueryState} asserts it at
+ * runtime.
+ */
+export type QueryStateLike<TData> = {
+    data: TData | undefined;
+    isError: boolean;
+    error: unknown;
+    fetchStatus: 'fetching' | 'paused' | 'idle';
+    refetch: () => unknown;
+};
+/** Copy for the empty branch. Rendered through `EmptyState`, so it looks like every other one. */
+export type QueryEmptyCopy = {
+    title: string;
+    /** Optional — a one-word empty panel should not have to invent a sentence. */
+    description?: string;
+    /** Optional glyph slot, rendered faint. */
+    icon?: ReactNode;
+    /** Call-to-action below the copy (e.g. "Reset filters"). */
+    action?: ReactNode;
+};
+export type LoadingStateProps = {
+    variant?: QueryStateVariant;
+    /** Accessible name for the spinner. Say what is loading. */
+    label?: string;
+};
+/** A spinner on its own — `variant="page"` centres it in a generous block, `'section'` is bare. */
+export declare function LoadingState({ variant, label, }: LoadingStateProps): ReactNode;
+export type ErrorStateProps = {
+    /** Whatever was thrown — the raw Eden/fetch envelope is fine, it gets decoded. */
+    error: unknown;
+    /** Alert heading. Say what failed, e.g. `Could not load images`. */
+    title?: string;
+    /** Shown only when the server body carries no readable message. */
+    fallback?: string;
+    onRetry?: () => void;
+    /** Disables/spins the retry button while a refetch is in flight. */
+    retrying?: boolean;
+    variant?: QueryStateVariant;
+    /** Extra controls beside Retry (e.g. a "Back to shares" link). */
+    action?: ReactNode;
+};
+/**
+ * The error branch: the REAL server message (via `toErrorMessage`) plus a retry. Usable on its own,
+ * outside a query — an auth gate or a boundary fallback renders it directly.
+ */
+export declare function ErrorState({ error, title, fallback, onRetry, retrying, variant, action, }: ErrorStateProps): ReactNode;
+export type QueryStateProps<TData> = {
+    query: QueryStateLike<TData>;
+    /** A render function gets `data` narrowed to non-undefined; a plain node also works. */
+    children: ReactNode | ((data: TData) => ReactNode);
+    /** Omit to render nothing when the result is empty. */
+    empty?: QueryEmptyCopy;
+    /** Override the default `[]` / `{ data: [] }` emptiness test — `() => false` disables it. */
+    isEmpty?: (data: TData) => boolean;
+    /** Alert heading on the error branch — say what failed. */
+    errorTitle?: string;
+    /** Shown only when the server body carries no readable message. */
+    errorFallback?: string;
+    /** Extra controls beside Retry on the error branch. */
+    errorAction?: ReactNode;
+    variant?: QueryStateVariant;
+    /** Replace the default spinner (e.g. with a skeleton grid). */
+    loading?: ReactNode;
+};
+/**
+ * Renders loading / error-with-retry / empty / children for a query result, in that order.
+ * Branch precedence is the whole point, and it is deliberate:
+ *
+ *  - error AND no cached data → the full error state (the page cannot render)
+ *  - error WITH cached data   → children, plus a compact "showing cached data" banner on top
+ *    (a background refetch failing must not blank a page that already works)
+ *  - no data, fetch idle      → empty (this is an `enabled: false` query, not a pending one)
+ *  - no data, fetching        → `loading` (or the default spinner)
+ *
+ * @example
+ * <QueryState
+ *   query={q}
+ *   errorTitle="Could not load images"
+ *   empty={{ title: 'No images match', description: 'Widen the capture dates.' }}
+ * >
+ *   {(data) => <ImageGrid images={data.rows} />}
+ * </QueryState>
+ */
+export declare function QueryState<TData>({ query, children, empty, isEmpty, errorTitle, errorFallback, errorAction, variant, loading, }: QueryStateProps<TData>): ReactNode;
+//# sourceMappingURL=query-state.d.ts.map

package/dist/dashboard/query-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-state.d.ts","sourceRoot":"","sources":["../../src/dashboard/query-state.tsx"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAItC,oGAAoG;AACpG,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAAA;AAElD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,IAAI;IAClC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAA;IACvB,OAAO,EAAE,OAAO,CAAA;IAChB,KAAK,EAAE,OAAO,CAAA;IACd,WAAW,EAAE,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC3C,OAAO,EAAE,MAAM,OAAO,CAAA;CACvB,CAAA;AAED,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG;IAC3B,KAAK,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAID,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,4DAA4D;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,mGAAmG;AACnG,wBAAgB,YAAY,CAAC,EAC3B,OAAgB,EAChB,KAAiB,GAClB,EAAE,iBAAiB,GAAG,SAAS,CAI/B;AAID,MAAM,MAAM,eAAe,GAAG;IAC5B,kFAAkF;IAClF,KAAK,EAAE,OAAO,CAAA;IACd,oEAAoE;IACpE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,kEAAkE;IAClE,MAAM,CAAC,EAAE,SAAS,CAAA;CACnB,CAAA;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAA8B,EAC9B,QAAgC,EAChC,OAAO,EACP,QAAgB,EAChB,OAAgB,EAChB,MAAM,GACP,EAAE,eAAe,GAAG,SAAS,CAoB7B;AAyCD,MAAM,MAAM,eAAe,CAAC,KAAK,IAAI;IACnC,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,CAAA;IAC5B,wFAAwF;IACxF,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAA;IAClD,uDAAuD;IACvD,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAA;IAClC,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,SAAS,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,EAChC,KAAK,EACL,QAAQ,EACR,KAAK,EACL,OAAO,EACP,UAA6B,EAC7B,aAAqC,EACrC,WAAW,EACX,OAAgB,EAChB,OAAO,GACR,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,SAAS,CAiDpC"}