basalt-ui 1.23.1 → 1.24.0

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. One import
+replaced 204 hand-rolled lines across 10 call sites there.
+
+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 (3 of image-share's 10 call sites are), 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"}

package/dist/dashboard/query-state.js

@@ -0,0 +1,123 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Alert, Button, Center, Group, Loader, Stack, Text } from "@mantine/core";
+import { toErrorMessage } from "../query/error-message.js";
+import { EmptyState } from "./empty-state.js";
+function LoadingState({
+  variant = "page",
+  label = "Loading"
+}) {
+  const loader = /* @__PURE__ */ jsx(Loader, { size: "sm", "aria-label": label });
+  if (variant === "section") return loader;
+  return /* @__PURE__ */ jsx(Center, { py: 64, children: loader });
+}
+function ErrorState({
+  error,
+  title = "Something went wrong",
+  fallback = "The request failed.",
+  onRetry,
+  retrying = false,
+  variant = "page",
+  action
+}) {
+  const alert = /* @__PURE__ */ jsx(Alert, { color: "red", variant: "light", title, children: /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
+    /* @__PURE__ */ jsx(Text, { size: "sm", children: toErrorMessage(error, fallback) }),
+    (onRetry ?? action) !== void 0 && /* @__PURE__ */ jsxs(Group, { gap: "xs", children: [
+      onRetry && /* @__PURE__ */ jsx(Button, { size: "xs", variant: "default", loading: retrying, onClick: onRetry, children: "Retry" }),
+      action
+    ] })
+  ] }) });
+  if (variant === "section") return alert;
+  return /* @__PURE__ */ jsx(Stack, { py: "md", children: alert });
+}
+function defaultIsEmpty(data) {
+  if (data === null || data === void 0) return true;
+  if (Array.isArray(data)) return data.length === 0;
+  if (typeof data === "object" && Array.isArray(data.data)) {
+    return data.data.length === 0;
+  }
+  return false;
+}
+const FETCH_STATUSES = /* @__PURE__ */ new Set(["fetching", "paused", "idle"]);
+function assertQueryStateLike(query) {
+  const bad = (detail) => {
+    throw new Error(
+      `QueryState: \`query\` ${detail}. It must carry { data, isError, error, fetchStatus, refetch } \u2014 a TanStack UseQueryResult does; a hand-composed one must spell every field, because a missing branch flag renders a false claim about the data instead of an error.`
+    );
+  };
+  if (query === null || typeof query !== "object")
+    bad(`is ${query === null ? "null" : typeof query}`);
+  const q = query;
+  if (!("data" in q)) bad("has no `data` key");
+  if (typeof q["isError"] !== "boolean") bad("has no boolean `isError`");
+  if (typeof q["fetchStatus"] !== "string" || !FETCH_STATUSES.has(q["fetchStatus"]))
+    bad(`has fetchStatus=${JSON.stringify(q["fetchStatus"])}, not 'fetching' | 'paused' | 'idle'`);
+  if (typeof q["refetch"] !== "function") bad("has no `refetch()`");
+}
+function QueryState({
+  query,
+  children,
+  empty,
+  isEmpty,
+  errorTitle = "Could not load",
+  errorFallback = "The request failed.",
+  errorAction,
+  variant = "page",
+  loading
+}) {
+  assertQueryStateLike(query);
+  const { data, isError, error, fetchStatus } = query;
+  const retrying = fetchStatus === "fetching";
+  const retry = () => void query.refetch();
+  if (isError && data === void 0) {
+    return /* @__PURE__ */ jsx(
+      ErrorState,
+      {
+        error,
+        title: errorTitle,
+        fallback: errorFallback,
+        onRetry: retry,
+        retrying,
+        variant,
+        ...errorAction !== void 0 && { action: errorAction }
+      }
+    );
+  }
+  if (data === void 0) {
+    if (fetchStatus === "idle" && !isError) return empty ? renderEmpty(empty, variant) : null;
+    return loading ?? /* @__PURE__ */ jsx(LoadingState, { variant });
+  }
+  const emptyNow = isEmpty ? isEmpty(data) : defaultIsEmpty(data);
+  const body = emptyNow ? empty ? renderEmpty(empty, variant) : null : typeof children === "function" ? children(data) : children;
+  if (!isError) return body;
+  return /* @__PURE__ */ jsxs(Stack, { gap: "sm", children: [
+    /* @__PURE__ */ jsx(
+      ErrorState,
+      {
+        error,
+        title: "Showing cached data",
+        fallback: "The last refresh failed.",
+        onRetry: retry,
+        retrying,
+        variant: "section"
+      }
+    ),
+    body
+  ] });
+}
+function renderEmpty(empty, variant) {
+  return /* @__PURE__ */ jsx(
+    EmptyState,
+    {
+      title: empty.title,
+      variant,
+      ...empty.description !== void 0 && { description: empty.description },
+      ...empty.icon !== void 0 && { icon: empty.icon },
+      ...empty.action !== void 0 && { action: empty.action }
+    }
+  );
+}
+export {
+  ErrorState,
+  LoadingState,
+  QueryState
+};

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=query-state.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query-state.test.d.ts","sourceRoot":"","sources":["../../src/dashboard/query-state.test.tsx"],"names":[],"mappings":""}