@eifi1/ui-kit 0.16.1 → 0.18.0

package/dist/lib/server-wake.d.ts

@@ -0,0 +1,130 @@
+/**
+ * "Is the server asleep, or is the app broken?" — the cold-start watchdog, lifted
+ * from keksdose (feedback #199) so kastlan and Kurvenschmiede get it too.
+ *
+ * All three backends run on Cloud Run with `--min-instances=0`: after an idle
+ * period the container is gone and the first request has to start it, which takes
+ * several seconds and occasionally more. Nothing in the UI said so, and none of the
+ * axios instances has a timeout, so the honest experience was a spinner that looked
+ * stuck. This counts the in-flight requests a cold start would actually delay and
+ * escalates in two steps, so a merely slow response says "still loading" and only a
+ * genuinely long wait blames the sleeping server.
+ *
+ * Framework-free on purpose (no zustand, no axios, no React): a counter, two timers
+ * and a listener set, read by `useServerWakeStage` through `useSyncExternalStore`.
+ * The adapters below take the app's axios instance / fetch as an ARGUMENT, so the
+ * kit never imports either.
+ *
+ * WHAT ARMS IT, and why the default is narrow:
+ *   - reads (GET) — what every page does on open — always;
+ *   - writes only when the app says so (`watchReadsAnd(/\/auth\/login\b/)`): the
+ *     auth POSTs that gate the app are the only writes a user waits on before the
+ *     app exists at all, so a cold start there looks exactly like a broken login.
+ * An UPLOAD must never be watched — a statement PDF or a photo takes seconds on a
+ * perfectly warm server, and "the server is waking up" during a 4 s upload would
+ * simply be false. With the default that holds by itself (an upload is a POST);
+ * an app widening `shouldWatch` keeps its upload routes out of it.
+ *
+ * It never arms while the browser is offline, whatever `shouldWatch` says: that state
+ * has its own, truthful indicator, and a request that never left the device is not
+ * evidence of anything about the server.
+ */
+/** `slow` = longer than a warm server ever takes; `waking` = long enough that a cold
+ *  start is the only sensible explanation. */
+type ServerWakeStage = "idle" | "slow" | "waking";
+/** Decides which requests count. `method` arrives lower-cased (`"get"` when the
+ *  request named none — axios's and fetch's default); `url` as the client had it. */
+type ServerWakeFilter = (method: string, url: string) => boolean;
+interface ServerWakeOptions {
+    /** Past this, a warm round trip is out of the question (a cold database query on a
+     *  free tier can still take a second, so it is not tighter). Default 2000 ms. */
+    slowMs?: number;
+    /** Past this, the container was almost certainly scaled to zero. Default 7000 ms. */
+    wakingMs?: number;
+    /** Which requests count. Default {@link watchReadsAnd}`()` — GETs only. The offline
+     *  guard runs before it and cannot be overridden. */
+    shouldWatch?: ServerWakeFilter;
+}
+/** What a request is, for {@link ServerWakeWatcher.track}. */
+interface ServerWakeRequest {
+    method?: string;
+    url?: string;
+}
+interface ServerWakeWatcher {
+    /**
+     * Count a request that is going out, and arm the escalation if it is the first.
+     * Returns whether it was counted — the caller MUST call {@link end} exactly once
+     * for every `true`, or the counter never returns to zero and the notice sticks.
+     * (The axios adapter stashes it on the request config for that reason.)
+     */
+    start(method?: string, url?: string): boolean;
+    /** A counted request settled — either way: an error still proves the server
+     *  answered or gave up. When the last one does, the notice goes away. Never takes
+     *  the counter below zero. */
+    end(): void;
+    /** `start` + `end` around a promise (or a function returning one), for a request
+     *  that does not go through an adapter. Resolves and rejects as the work does. */
+    track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request?: ServerWakeRequest): Promise<T>;
+    /** Back to a pristine watchdog — for tests, which share an instance across cases. */
+    reset(): void;
+    /** `useSyncExternalStore`'s pair. Listeners hear stage changes only. */
+    subscribe(listener: () => void): () => void;
+    getStage(): ServerWakeStage;
+    /** Counted requests currently outstanding. */
+    getInFlight(): number;
+}
+/**
+ * The usual filter: every GET, plus any other request whose URL matches `writes` —
+ * keksdose's `/\/auth\/(login|register|demo-session)\b/`. Keep upload routes out of
+ * the pattern (see the module comment).
+ */
+declare function watchReadsAnd(writes?: RegExp): ServerWakeFilter;
+declare function createServerWake({ slowMs, wakingMs, shouldWatch, }?: ServerWakeOptions): ServerWakeWatcher;
+/**
+ * The shared instance: what `<ServerWakeNotice />`, `useServerWakeStage()`,
+ * {@link attachServerWake} and {@link wrapFetch} use when no watcher is passed. GETs
+ * only, default timings — an app that also watches its login POST creates its own
+ * with {@link createServerWake} and passes it to both ends.
+ */
+declare const serverWake: ServerWakeWatcher;
+/** The two config fields the watchdog reads — what axios's request config has. */
+interface ServerWakeAxiosConfig {
+    method?: string;
+    url?: string;
+}
+/** The slice of an interceptor manager the adapter uses. A method (not a function
+ *  property) so axios's wider `use(onFulfilled?, onRejected?, options?)` fits it. */
+interface InterceptorManagerLike<V> {
+    use(onFulfilled: (value: V) => V | Promise<V>, onRejected: (error: unknown) => unknown): number;
+    eject(id: number): void;
+}
+/** An axios instance, structurally — so the kit types the adapter without importing
+ *  axios. `axios.create()`'s result fits it as is. */
+interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends {
+    config: C;
+}> {
+    interceptors: {
+        request: InterceptorManagerLike<C>;
+        response: InterceptorManagerLike<R>;
+    };
+}
+/**
+ * Drive a watcher from an axios instance's interceptors: `attachServerWake(api)`.
+ * Returns a function that ejects both interceptors again.
+ *
+ * Attach it BEFORE the app's own response interceptors: axios runs those in the order
+ * they were added, so the wake one ends the wait before a 401 handler awaits a token
+ * refresh — otherwise the notice would keep counting a request that has already been
+ * answered. (Request-side order does not matter.)
+ */
+declare function attachServerWake<C extends ServerWakeAxiosConfig, R extends {
+    config: C;
+}>(instance: AxiosLikeInstance<C, R>, watcher?: ServerWakeWatcher): () => void;
+/**
+ * A `fetch` that drives a watcher: `const apiFetch = wrapFetch(fetch)`. The wait ends
+ * when the response's HEADERS arrive (or the call fails) — the server is awake by then,
+ * however long the body takes.
+ */
+declare function wrapFetch(fetchImpl?: typeof fetch, watcher?: ServerWakeWatcher): typeof fetch;
+
+export { type AxiosLikeInstance, type ServerWakeAxiosConfig, type ServerWakeFilter, type ServerWakeOptions, type ServerWakeRequest, type ServerWakeStage, type ServerWakeWatcher, attachServerWake, createServerWake, serverWake, watchReadsAnd, wrapFetch };

package/dist/lib/server-wake.js

@@ -0,0 +1,121 @@
+"use client";
+function watchReadsAnd(writes) {
+  return (method, url) => method === "get" || writes !== void 0 && writes.test(url);
+}
+function isOffline() {
+  return typeof navigator !== "undefined" && navigator.onLine === false;
+}
+function createServerWake({
+  slowMs = 2e3,
+  wakingMs = 7e3,
+  shouldWatch = watchReadsAnd()
+} = {}) {
+  let inFlight = 0;
+  let stage = "idle";
+  let slowTimer = null;
+  let wakingTimer = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const setStage = (next) => {
+    if (next === stage) return;
+    stage = next;
+    for (const listener of listeners) listener();
+  };
+  const clearTimers = () => {
+    if (slowTimer !== null) clearTimeout(slowTimer);
+    if (wakingTimer !== null) clearTimeout(wakingTimer);
+    slowTimer = null;
+    wakingTimer = null;
+  };
+  const start = (method, url) => {
+    if (isOffline()) return false;
+    if (!shouldWatch((method ?? "get").toLowerCase(), url ?? "")) return false;
+    inFlight += 1;
+    if (inFlight === 1) {
+      clearTimers();
+      slowTimer = setTimeout(() => setStage("slow"), slowMs);
+      wakingTimer = setTimeout(() => setStage("waking"), wakingMs);
+    }
+    return true;
+  };
+  const end = () => {
+    inFlight = Math.max(0, inFlight - 1);
+    if (inFlight > 0) return;
+    clearTimers();
+    setStage("idle");
+  };
+  return {
+    start,
+    end,
+    track(work, request = {}) {
+      const counted = start(request.method, request.url);
+      let promise;
+      try {
+        promise = Promise.resolve(typeof work === "function" ? work() : work);
+      } catch (error) {
+        promise = Promise.reject(error);
+      }
+      return counted ? promise.finally(end) : promise;
+    },
+    reset() {
+      inFlight = 0;
+      clearTimers();
+      setStage("idle");
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getStage: () => stage,
+    getInFlight: () => inFlight
+  };
+}
+const serverWake = createServerWake();
+const COUNTED = "_serverWake";
+function attachServerWake(instance, watcher = serverWake) {
+  const settle = (config) => {
+    const marked = config;
+    if (marked?.[COUNTED]) {
+      marked[COUNTED] = false;
+      watcher.end();
+    }
+  };
+  const request = instance.interceptors.request.use(
+    (config) => {
+      config[COUNTED] = watcher.start(config.method, config.url);
+      return config;
+    },
+    (error) => Promise.reject(error)
+  );
+  const response = instance.interceptors.response.use(
+    (res) => {
+      settle(res.config);
+      return res;
+    },
+    (error) => {
+      settle(error?.config);
+      return Promise.reject(error);
+    }
+  );
+  return () => {
+    instance.interceptors.request.eject(request);
+    instance.interceptors.response.eject(response);
+  };
+}
+function wrapFetch(fetchImpl = globalThis.fetch, watcher = serverWake) {
+  return (input, init) => {
+    const request = typeof Request !== "undefined" && input instanceof Request ? input : void 0;
+    const method = init?.method ?? request?.method;
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : request?.url ?? "";
+    return watcher.track(() => fetchImpl(input, init), { method, url });
+  };
+}
+export {
+  attachServerWake,
+  createServerWake,
+  serverWake,
+  watchReadsAnd,
+  wrapFetch
+};
+//# sourceMappingURL=server-wake.js.map

package/dist/lib/server-wake.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/server-wake.ts"],"sourcesContent":["/**\n * \"Is the server asleep, or is the app broken?\" — the cold-start watchdog, lifted\n * from keksdose (feedback #199) so kastlan and Kurvenschmiede get it too.\n *\n * All three backends run on Cloud Run with `--min-instances=0`: after an idle\n * period the container is gone and the first request has to start it, which takes\n * several seconds and occasionally more. Nothing in the UI said so, and none of the\n * axios instances has a timeout, so the honest experience was a spinner that looked\n * stuck. This counts the in-flight requests a cold start would actually delay and\n * escalates in two steps, so a merely slow response says \"still loading\" and only a\n * genuinely long wait blames the sleeping server.\n *\n * Framework-free on purpose (no zustand, no axios, no React): a counter, two timers\n * and a listener set, read by `useServerWakeStage` through `useSyncExternalStore`.\n * The adapters below take the app's axios instance / fetch as an ARGUMENT, so the\n * kit never imports either.\n *\n * WHAT ARMS IT, and why the default is narrow:\n *   - reads (GET) — what every page does on open — always;\n *   - writes only when the app says so (`watchReadsAnd(/\\/auth\\/login\\b/)`): the\n *     auth POSTs that gate the app are the only writes a user waits on before the\n *     app exists at all, so a cold start there looks exactly like a broken login.\n * An UPLOAD must never be watched — a statement PDF or a photo takes seconds on a\n * perfectly warm server, and \"the server is waking up\" during a 4 s upload would\n * simply be false. With the default that holds by itself (an upload is a POST);\n * an app widening `shouldWatch` keeps its upload routes out of it.\n *\n * It never arms while the browser is offline, whatever `shouldWatch` says: that state\n * has its own, truthful indicator, and a request that never left the device is not\n * evidence of anything about the server.\n */\n\n/** `slow` = longer than a warm server ever takes; `waking` = long enough that a cold\n *  start is the only sensible explanation. */\nexport type ServerWakeStage = \"idle\" | \"slow\" | \"waking\";\n\n/** Decides which requests count. `method` arrives lower-cased (`\"get\"` when the\n *  request named none — axios's and fetch's default); `url` as the client had it. */\nexport type ServerWakeFilter = (method: string, url: string) => boolean;\n\nexport interface ServerWakeOptions {\n  /** Past this, a warm round trip is out of the question (a cold database query on a\n   *  free tier can still take a second, so it is not tighter). Default 2000 ms. */\n  slowMs?: number;\n  /** Past this, the container was almost certainly scaled to zero. Default 7000 ms. */\n  wakingMs?: number;\n  /** Which requests count. Default {@link watchReadsAnd}`()` — GETs only. The offline\n   *  guard runs before it and cannot be overridden. */\n  shouldWatch?: ServerWakeFilter;\n}\n\n/** What a request is, for {@link ServerWakeWatcher.track}. */\nexport interface ServerWakeRequest {\n  method?: string;\n  url?: string;\n}\n\nexport interface ServerWakeWatcher {\n  /**\n   * Count a request that is going out, and arm the escalation if it is the first.\n   * Returns whether it was counted — the caller MUST call {@link end} exactly once\n   * for every `true`, or the counter never returns to zero and the notice sticks.\n   * (The axios adapter stashes it on the request config for that reason.)\n   */\n  start(method?: string, url?: string): boolean;\n  /** A counted request settled — either way: an error still proves the server\n   *  answered or gave up. When the last one does, the notice goes away. Never takes\n   *  the counter below zero. */\n  end(): void;\n  /** `start` + `end` around a promise (or a function returning one), for a request\n   *  that does not go through an adapter. Resolves and rejects as the work does. */\n  track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request?: ServerWakeRequest): Promise<T>;\n  /** Back to a pristine watchdog — for tests, which share an instance across cases. */\n  reset(): void;\n  /** `useSyncExternalStore`'s pair. Listeners hear stage changes only. */\n  subscribe(listener: () => void): () => void;\n  getStage(): ServerWakeStage;\n  /** Counted requests currently outstanding. */\n  getInFlight(): number;\n}\n\n/**\n * The usual filter: every GET, plus any other request whose URL matches `writes` —\n * keksdose's `/\\/auth\\/(login|register|demo-session)\\b/`. Keep upload routes out of\n * the pattern (see the module comment).\n */\nexport function watchReadsAnd(writes?: RegExp): ServerWakeFilter {\n  return (method, url) => method === \"get\" || (writes !== undefined && writes.test(url));\n}\n\nfunction isOffline(): boolean {\n  return typeof navigator !== \"undefined\" && navigator.onLine === false;\n}\n\nexport function createServerWake({\n  slowMs = 2000,\n  wakingMs = 7000,\n  shouldWatch = watchReadsAnd(),\n}: ServerWakeOptions = {}): ServerWakeWatcher {\n  let inFlight = 0;\n  let stage: ServerWakeStage = \"idle\";\n  let slowTimer: ReturnType<typeof setTimeout> | null = null;\n  let wakingTimer: ReturnType<typeof setTimeout> | null = null;\n  const listeners = new Set<() => void>();\n\n  const setStage = (next: ServerWakeStage) => {\n    if (next === stage) return;\n    stage = next;\n    for (const listener of listeners) listener();\n  };\n\n  const clearTimers = () => {\n    if (slowTimer !== null) clearTimeout(slowTimer);\n    if (wakingTimer !== null) clearTimeout(wakingTimer);\n    slowTimer = null;\n    wakingTimer = null;\n  };\n\n  const start = (method?: string, url?: string): boolean => {\n    if (isOffline()) return false;\n    if (!shouldWatch((method ?? \"get\").toLowerCase(), url ?? \"\")) return false;\n    inFlight += 1;\n    // The clock runs from the FIRST outstanding request: a page firing a second read\n    // at 1.9 s is still waiting on the same sleeping server, not starting afresh.\n    if (inFlight === 1) {\n      clearTimers();\n      slowTimer = setTimeout(() => setStage(\"slow\"), slowMs);\n      wakingTimer = setTimeout(() => setStage(\"waking\"), wakingMs);\n    }\n    return true;\n  };\n\n  const end = () => {\n    inFlight = Math.max(0, inFlight - 1);\n    if (inFlight > 0) return;\n    clearTimers();\n    setStage(\"idle\");\n  };\n\n  return {\n    start,\n    end,\n    track<T>(work: PromiseLike<T> | (() => PromiseLike<T>), request: ServerWakeRequest = {}) {\n      const counted = start(request.method, request.url);\n      let promise: Promise<T>;\n      try {\n        promise = Promise.resolve(typeof work === \"function\" ? work() : work);\n      } catch (error) {\n        // A thunk that throws before it returns a promise settled too.\n        promise = Promise.reject(error);\n      }\n      return counted ? promise.finally(end) : promise;\n    },\n    reset() {\n      inFlight = 0;\n      clearTimers();\n      setStage(\"idle\");\n    },\n    subscribe(listener) {\n      listeners.add(listener);\n      return () => {\n        listeners.delete(listener);\n      };\n    },\n    getStage: () => stage,\n    getInFlight: () => inFlight,\n  };\n}\n\n/**\n * The shared instance: what `<ServerWakeNotice />`, `useServerWakeStage()`,\n * {@link attachServerWake} and {@link wrapFetch} use when no watcher is passed. GETs\n * only, default timings — an app that also watches its login POST creates its own\n * with {@link createServerWake} and passes it to both ends.\n */\nexport const serverWake: ServerWakeWatcher = createServerWake();\n\n// ── axios ─────────────────────────────────────────────────────────────────────\n\n/** The two config fields the watchdog reads — what axios's request config has. */\nexport interface ServerWakeAxiosConfig {\n  method?: string;\n  url?: string;\n}\n\n/** The slice of an interceptor manager the adapter uses. A method (not a function\n *  property) so axios's wider `use(onFulfilled?, onRejected?, options?)` fits it. */\ninterface InterceptorManagerLike<V> {\n  use(onFulfilled: (value: V) => V | Promise<V>, onRejected: (error: unknown) => unknown): number;\n  eject(id: number): void;\n}\n\n/** An axios instance, structurally — so the kit types the adapter without importing\n *  axios. `axios.create()`'s result fits it as is. */\nexport interface AxiosLikeInstance<C extends ServerWakeAxiosConfig, R extends { config: C }> {\n  interceptors: {\n    request: InterceptorManagerLike<C>;\n    response: InterceptorManagerLike<R>;\n  };\n}\n\n/** Whether the watchdog counted this request — the response side owes a matching\n *  `end()` only then. On the config, as keksdose's `_wake` was: it travels with the\n *  request onto the response and onto an error. Cleared once settled, so a 401 replay\n *  of the same config re-enters the request interceptor and is counted afresh — the\n *  pairing stays balanced. */\nconst COUNTED = \"_serverWake\";\ntype Marked = { [COUNTED]?: boolean };\n\n/**\n * Drive a watcher from an axios instance's interceptors: `attachServerWake(api)`.\n * Returns a function that ejects both interceptors again.\n *\n * Attach it BEFORE the app's own response interceptors: axios runs those in the order\n * they were added, so the wake one ends the wait before a 401 handler awaits a token\n * refresh — otherwise the notice would keep counting a request that has already been\n * answered. (Request-side order does not matter.)\n */\nexport function attachServerWake<C extends ServerWakeAxiosConfig, R extends { config: C }>(\n  instance: AxiosLikeInstance<C, R>,\n  watcher: ServerWakeWatcher = serverWake,\n): () => void {\n  const settle = (config: unknown) => {\n    const marked = config as Marked | undefined;\n    if (marked?.[COUNTED]) {\n      marked[COUNTED] = false;\n      watcher.end();\n    }\n  };\n  const request = instance.interceptors.request.use(\n    (config) => {\n      (config as C & Marked)[COUNTED] = watcher.start(config.method, config.url);\n      return config;\n    },\n    (error) => Promise.reject(error),\n  );\n  const response = instance.interceptors.response.use(\n    (res) => {\n      settle(res.config);\n      return res;\n    },\n    (error) => {\n      settle((error as { config?: unknown } | null)?.config);\n      return Promise.reject(error);\n    },\n  );\n  return () => {\n    instance.interceptors.request.eject(request);\n    instance.interceptors.response.eject(response);\n  };\n}\n\n// ── fetch ─────────────────────────────────────────────────────────────────────\n\n/**\n * A `fetch` that drives a watcher: `const apiFetch = wrapFetch(fetch)`. The wait ends\n * when the response's HEADERS arrive (or the call fails) — the server is awake by then,\n * however long the body takes.\n */\nexport function wrapFetch(\n  fetchImpl: typeof fetch = globalThis.fetch,\n  watcher: ServerWakeWatcher = serverWake,\n): typeof fetch {\n  return (input, init) => {\n    const request = typeof Request !== \"undefined\" && input instanceof Request ? input : undefined;\n    const method = init?.method ?? request?.method;\n    const url = typeof input === \"string\" ? input : input instanceof URL ? input.href : (request?.url ?? \"\");\n    return watcher.track(() => fetchImpl(input, init), { method, url });\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/rhf/fields.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, ReactElement } from 'react';
 import { FieldValues, FieldPath, ControllerProps, ControllerRenderProps, ControllerFieldState } from 'react-hook-form';
-import { aN as SelectProps, aC as InputProps, aW as TextareaProps } from '../kit-labels-DE--LmCk.js';
+import { aQ as SelectProps, aE as InputProps, b9 as TextareaProps } from '../kit-labels-CPbsjlXr.js';
 import { NumberFieldProps } from '../components/number-field.js';
 import { DatePickerProps } from '../components/date-picker.js';
 import { CheckboxProps } from '../components/checkbox.js';
@@ -58,6 +58,15 @@ import '../components/authed-image.js';
 import '../hooks/use-authed-src.js';
 import '../components/image-grid.js';
 import '../components/lightbox.js';
+import '../components/write-lock.js';
+import '../components/account-chips.js';
+import '../lib/format.js';
+import '../data-table-3mi2R3so.js';
+import '../components/data-table-sort.js';
+import '../components/swipeable-row.js';
+import '../components/reauth-dialog.js';
+import '../components/server-wake.js';
+import '../lib/server-wake.js';
 import '../components/number-input.js';
 import '../components/calculator.js';
 import '../components/numpad-sheet.js';

package/dist/rhf/form.d.ts

@@ -2,7 +2,7 @@ import * as react from 'react';
 import { ReactElement, ComponentProps } from 'react';
 import * as react_hook_form from 'react-hook-form';
 import { FieldValues, FieldPath, ControllerProps } from 'react-hook-form';
-import { aH as LabelProps } from '../kit-labels-DE--LmCk.js';
+import { aJ as LabelProps } from '../kit-labels-CPbsjlXr.js';
 import '../components/data-table-labels.js';
 import '../components/mini-calendar.js';
 import '../components/calendar-heatmap.js';
@@ -53,6 +53,15 @@ import '../components/authed-image.js';
 import '../hooks/use-authed-src.js';
 import '../components/image-grid.js';
 import '../components/lightbox.js';
+import '../components/write-lock.js';
+import '../components/account-chips.js';
+import '../lib/format.js';
+import '../data-table-3mi2R3so.js';
+import '../components/data-table-sort.js';
+import '../components/swipeable-row.js';
+import '../components/reauth-dialog.js';
+import '../components/server-wake.js';
+import '../lib/server-wake.js';
 
 /** The form's `useForm()` return, spread in: `<Form {...form}>`. react-hook-form's own
  *  `FormProvider`, under the name the shadcn file gave it. */

package/dist/rhf/line-items.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/rhf/line-items.tsx"],"sourcesContent":["/**\n * {@link LineItems} over react-hook-form's `useFieldArray`. `@eifi1/ui-kit/rhf`.\n *\n * ```tsx\n * <RhfLineItems\n *   name=\"components\"\n *   newItem={() => ({ type: \"net_rent\", amount: null, validFrom: \"\" })}\n *   minItems={1}\n *   columns={[\n *     { key: \"type\", header: \"Type\", render: ({ name, label }) => (\n *       <RhfSelect name={`${name}.type`} options={TYPES} aria-label={label} />\n *     ) },\n *     { key: \"amount\", header: \"Amount\", width: \"8rem\", align: \"end\", render: ({ name, label }) => (\n *       <RhfMoneyField name={`${name}.amount`} ariaLabel={label} />\n *     ) },\n *   ]}\n *   totals={{ amount: formatMoney(total) }}\n * />\n * ```\n *\n * The rows are the array's `fields` (keyed by their `id`, as react-hook-form asks),\n * Add appends `newItem()`, remove is `remove(index)`, and an error on the array\n * itself — the `rules` here, or a resolver's `lines: \"At least two lines\"` — is the\n * list's `error`. Each cell's `render` gets `name`, the row's path\n * (`\"components.2\"`), to bind its field to.\n *\n * `summary`, `fieldLabels` and `narrowColumns` pass through to {@link LineItems}. With\n * `fieldLabels=\"floating\"` a cell's `fieldLabel` is the column's name; the bound\n * fields' own `label` is a `FormLabel` ABOVE the control, so for the floating\n * one render the kit field through `RhfField`:\n * `render={({ field, invalid }) => <Input label={fieldLabel} aria-label={label} {...field} invalid={invalid} />}`.\n */\nimport type { ReactNode } from \"react\";\nimport {\n  useFieldArray,\n  useFormState,\n  type FieldArray,\n  type FieldArrayPath,\n  type FieldArrayWithId,\n  type FieldValues,\n  type UseFieldArrayProps,\n} from \"react-hook-form\";\nimport {\n  LineItems,\n  type LineItemCellContext,\n  type LineItemsColumn,\n  type LineItemsProps,\n} from \"../components/line-items\";\n\n/** A cell's context, with the row's path in the form. */\nexport interface RhfLineItemCellContext<TItem, TArrayName extends string>\n  extends LineItemCellContext<TItem> {\n  /** The row's path: `${name}.${index}` — bind the cell's field to\n   *  `` `${name}.amount` ``. */\n  name: `${TArrayName}.${number}`;\n}\n\nexport interface RhfLineItemsColumn<TItem, TArrayName extends string>\n  extends Omit<LineItemsColumn<TItem>, \"render\"> {\n  render: (ctx: RhfLineItemCellContext<TItem, TArrayName>) => ReactNode;\n}\n\nexport interface RhfLineItemsProps<\n  TFieldValues extends FieldValues = FieldValues,\n  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,\n  TTransformed = TFieldValues,\n> extends Omit<\n    LineItemsProps<FieldArrayWithId<TFieldValues, TArrayName, \"id\">>,\n    \"items\" | \"columns\" | \"onAdd\" | \"onRemove\" | \"getKey\"\n  > {\n  name: TArrayName;\n  /** `form.control`. Optional under `<Form {...form}>`. */\n  control?: UseFieldArrayProps<TFieldValues, TArrayName, \"id\", TTransformed>[\"control\"];\n  /** `useFieldArray`'s `rules` (`minLength`, `validate` …); its message is the list's\n   *  error. */\n  rules?: UseFieldArrayProps<TFieldValues, TArrayName, \"id\", TTransformed>[\"rules\"];\n  columns: readonly RhfLineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, \"id\">, TArrayName>[];\n  /** A new row's values. Omitted: no add button. */\n  newItem?: () => FieldArray<TFieldValues, TArrayName>;\n  /** `false`: no remove buttons. Default `true`. */\n  removable?: boolean;\n}\n\n/** The message of an error at `path` in react-hook-form's errors tree: the array's\n *  own (`root`, from `rules`) or one a resolver put on the array. */\nfunction arrayError(errors: unknown, path: string): string | undefined {\n  let node: unknown = errors;\n  for (const key of path.split(\".\")) {\n    if (node === null || typeof node !== \"object\") return undefined;\n    node = (node as Record<string, unknown>)[key];\n  }\n  if (node === null || typeof node !== \"object\") return undefined;\n  const { root, message } = node as { root?: { message?: unknown }; message?: unknown };\n  const text = root?.message ?? message;\n  return typeof text === \"string\" && text !== \"\" ? text : undefined;\n}\n\n/** {@link LineItems} bound to a field array. See the module note. */\nexport function RhfLineItems<\n  TFieldValues extends FieldValues = FieldValues,\n  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,\n  TTransformed = TFieldValues,\n>({\n  name,\n  control,\n  rules,\n  columns,\n  newItem,\n  removable = true,\n  error,\n  ...rest\n}: RhfLineItemsProps<TFieldValues, TArrayName, TTransformed>) {\n  const { fields, append, remove } = useFieldArray<TFieldValues, TArrayName, \"id\", TTransformed>({\n    control,\n    name,\n    rules,\n  });\n  const { errors } = useFormState({ control, name: name as never });\n  const bound: LineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, \"id\">>[] = columns.map(\n    ({ render, ...column }) => ({\n      ...column,\n      render: (ctx) => render({ ...ctx, name: `${name}.${ctx.index}` as `${TArrayName}.${number}` }),\n    }),\n  );\n  return (\n    <LineItems\n      {...rest}\n      items={fields}\n      columns={bound}\n      getKey={(field) => field.id}\n      onAdd={newItem ? () => append(newItem()) : undefined}\n      onRemove={removable ? (index) => remove(index) : undefined}\n      error={error ?? arrayError(errors, name)}\n    />\n  );\n}\n"],"mappings":";AA6HI;AA5FJ;AAAA,EACE;AAAA,EACA;AAAA,OAMK;AACP;AAAA,EACE;AAAA,OAIK;AAsCP,SAAS,WAAW,QAAiB,MAAkC;AACrE,MAAI,OAAgB;AACpB,aAAW,OAAO,KAAK,MAAM,GAAG,GAAG;AACjC,QAAI,SAAS,QAAQ,OAAO,SAAS,SAAU,QAAO;AACtD,WAAQ,KAAiC,GAAG;AAAA,EAC9C;AACA,MAAI,SAAS,QAAQ,OAAO,SAAS,SAAU,QAAO;AACtD,QAAM,EAAE,MAAM,QAAQ,IAAI;AAC1B,QAAM,OAAO,MAAM,WAAW;AAC9B,SAAO,OAAO,SAAS,YAAY,SAAS,KAAK,OAAO;AAC1D;AAGO,SAAS,aAId;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA,GAAG;AACL,GAA8D;AAC5D,QAAM,EAAE,QAAQ,QAAQ,OAAO,IAAI,cAA4D;AAAA,IAC7F;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACD,QAAM,EAAE,OAAO,IAAI,aAAa,EAAE,SAAS,KAAoB,CAAC;AAChE,QAAM,QAA6E,QAAQ;AAAA,IACzF,CAAC,EAAE,QAAQ,GAAG,OAAO,OAAO;AAAA,MAC1B,GAAG;AAAA,MACH,QAAQ,CAAC,QAAQ,OAAO,EAAE,GAAG,KAAK,MAAM,GAAG,IAAI,IAAI,IAAI,KAAK,GAAgC,CAAC;AAAA,IAC/F;AAAA,EACF;AACA,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,OAAO;AAAA,MACP,SAAS;AAAA,MACT,QAAQ,CAAC,UAAU,MAAM;AAAA,MACzB,OAAO,UAAU,MAAM,OAAO,QAAQ,CAAC,IAAI;AAAA,MAC3C,UAAU,YAAY,CAAC,UAAU,OAAO,KAAK,IAAI;AAAA,MACjD,OAAO,SAAS,WAAW,QAAQ,IAAI;AAAA;AAAA,EACzC;AAEJ;","names":[]}
+{"version":3,"sources":["../../src/rhf/line-items.tsx"],"sourcesContent":["/**\n * {@link LineItems} over react-hook-form's `useFieldArray`. `@eifi1/ui-kit/rhf`.\n *\n * ```tsx\n * <RhfLineItems\n *   name=\"components\"\n *   newItem={() => ({ type: \"net_rent\", amount: null, validFrom: \"\" })}\n *   minItems={1}\n *   columns={[\n *     { key: \"type\", header: \"Type\", render: ({ name, label }) => (\n *       <RhfSelect name={`${name}.type`} options={TYPES} aria-label={label} />\n *     ) },\n *     { key: \"amount\", header: \"Amount\", width: \"8rem\", align: \"end\", render: ({ name, label }) => (\n *       <RhfMoneyField name={`${name}.amount`} ariaLabel={label} />\n *     ) },\n *   ]}\n *   totals={{ amount: formatMoney(total) }}\n * />\n * ```\n *\n * The rows are the array's `fields` (keyed by their `id`, as react-hook-form asks),\n * Add appends `newItem()`, remove is `remove(index)`, and an error on the array\n * itself — the `rules` here, or a resolver's `lines: \"At least two lines\"` — is the\n * list's `error`. Each cell's `render` gets `name`, the row's path\n * (`\"components.2\"`), to bind its field to.\n *\n * `summary`, `fieldLabels`, `narrowColumns`, `removePlacement` and `removeAlign` pass\n * through to {@link LineItems}. With\n * `fieldLabels=\"floating\"` a cell's `fieldLabel` is the column's name; the bound\n * fields' own `label` is a `FormLabel` ABOVE the control, so for the floating\n * one render the kit field through `RhfField`:\n * `render={({ field, invalid }) => <Input label={fieldLabel} aria-label={label} {...field} invalid={invalid} />}`.\n */\nimport type { ReactNode } from \"react\";\nimport {\n  useFieldArray,\n  useFormState,\n  type FieldArray,\n  type FieldArrayPath,\n  type FieldArrayWithId,\n  type FieldValues,\n  type UseFieldArrayProps,\n} from \"react-hook-form\";\nimport {\n  LineItems,\n  type LineItemCellContext,\n  type LineItemsColumn,\n  type LineItemsProps,\n} from \"../components/line-items\";\n\n/** A cell's context, with the row's path in the form. */\nexport interface RhfLineItemCellContext<TItem, TArrayName extends string>\n  extends LineItemCellContext<TItem> {\n  /** The row's path: `${name}.${index}` — bind the cell's field to\n   *  `` `${name}.amount` ``. */\n  name: `${TArrayName}.${number}`;\n}\n\nexport interface RhfLineItemsColumn<TItem, TArrayName extends string>\n  extends Omit<LineItemsColumn<TItem>, \"render\"> {\n  render: (ctx: RhfLineItemCellContext<TItem, TArrayName>) => ReactNode;\n}\n\nexport interface RhfLineItemsProps<\n  TFieldValues extends FieldValues = FieldValues,\n  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,\n  TTransformed = TFieldValues,\n> extends Omit<\n    LineItemsProps<FieldArrayWithId<TFieldValues, TArrayName, \"id\">>,\n    \"items\" | \"columns\" | \"onAdd\" | \"onRemove\" | \"getKey\"\n  > {\n  name: TArrayName;\n  /** `form.control`. Optional under `<Form {...form}>`. */\n  control?: UseFieldArrayProps<TFieldValues, TArrayName, \"id\", TTransformed>[\"control\"];\n  /** `useFieldArray`'s `rules` (`minLength`, `validate` …); its message is the list's\n   *  error. */\n  rules?: UseFieldArrayProps<TFieldValues, TArrayName, \"id\", TTransformed>[\"rules\"];\n  columns: readonly RhfLineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, \"id\">, TArrayName>[];\n  /** A new row's values. Omitted: no add button. */\n  newItem?: () => FieldArray<TFieldValues, TArrayName>;\n  /** `false`: no remove buttons. Default `true`. */\n  removable?: boolean;\n}\n\n/** The message of an error at `path` in react-hook-form's errors tree: the array's\n *  own (`root`, from `rules`) or one a resolver put on the array. */\nfunction arrayError(errors: unknown, path: string): string | undefined {\n  let node: unknown = errors;\n  for (const key of path.split(\".\")) {\n    if (node === null || typeof node !== \"object\") return undefined;\n    node = (node as Record<string, unknown>)[key];\n  }\n  if (node === null || typeof node !== \"object\") return undefined;\n  const { root, message } = node as { root?: { message?: unknown }; message?: unknown };\n  const text = root?.message ?? message;\n  return typeof text === \"string\" && text !== \"\" ? text : undefined;\n}\n\n/** {@link LineItems} bound to a field array. See the module note. */\nexport function RhfLineItems<\n  TFieldValues extends FieldValues = FieldValues,\n  TArrayName extends FieldArrayPath<TFieldValues> = FieldArrayPath<TFieldValues>,\n  TTransformed = TFieldValues,\n>({\n  name,\n  control,\n  rules,\n  columns,\n  newItem,\n  removable = true,\n  error,\n  ...rest\n}: RhfLineItemsProps<TFieldValues, TArrayName, TTransformed>) {\n  const { fields, append, remove } = useFieldArray<TFieldValues, TArrayName, \"id\", TTransformed>({\n    control,\n    name,\n    rules,\n  });\n  const { errors } = useFormState({ control, name: name as never });\n  const bound: LineItemsColumn<FieldArrayWithId<TFieldValues, TArrayName, \"id\">>[] = columns.map(\n    ({ render, ...column }) => ({\n      ...column,\n      render: (ctx) => render({ ...ctx, name: `${name}.${ctx.index}` as `${TArrayName}.${number}` }),\n    }),\n  );\n  return (\n    <LineItems\n      {...rest}\n      items={fields}\n      columns={bound}\n      getKey={(field) => field.id}\n      onAdd={newItem ? () => append(newItem()) : undefined}\n      onRemove={removable ? (index) => remove(index) : undefined}\n      error={error ?? arrayError(errors, name)}\n    />\n  );\n}\n"],"mappings":";AA8HI;AA5FJ;AAAA,EACE;AAAA,EACA;AAAA,OAMK;AACP;AAAA,EACE;AAAA,OAIK;AAsCP,SAAS,WAAW,QAAiB,MAAkC;AACrE,MAAI,OAAgB;AACpB,aAAW,OAAO,KAAK,MAAM,GAAG,GAAG;AACjC,QAAI,SAAS,QAAQ,OAAO,SAAS,SAAU,QAAO;AACtD,WAAQ,KAAiC,GAAG;AAAA,EAC9C;AACA,MAAI,SAAS,QAAQ,OAAO,SAAS,SAAU,QAAO;AACtD,QAAM,EAAE,MAAM,QAAQ,IAAI;AAC1B,QAAM,OAAO,MAAM,WAAW;AAC9B,SAAO,OAAO,SAAS,YAAY,SAAS,KAAK,OAAO;AAC1D;AAGO,SAAS,aAId;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA,YAAY;AAAA,EACZ;AAAA,EACA,GAAG;AACL,GAA8D;AAC5D,QAAM,EAAE,QAAQ,QAAQ,OAAO,IAAI,cAA4D;AAAA,IAC7F;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AACD,QAAM,EAAE,OAAO,IAAI,aAAa,EAAE,SAAS,KAAoB,CAAC;AAChE,QAAM,QAA6E,QAAQ;AAAA,IACzF,CAAC,EAAE,QAAQ,GAAG,OAAO,OAAO;AAAA,MAC1B,GAAG;AAAA,MACH,QAAQ,CAAC,QAAQ,OAAO,EAAE,GAAG,KAAK,MAAM,GAAG,IAAI,IAAI,IAAI,KAAK,GAAgC,CAAC;AAAA,IAC/F;AAAA,EACF;AACA,SACE;AAAA,IAAC;AAAA;AAAA,MACE,GAAG;AAAA,MACJ,OAAO;AAAA,MACP,SAAS;AAAA,MACT,QAAQ,CAAC,UAAU,MAAM;AAAA,MACzB,OAAO,UAAU,MAAM,OAAO,QAAQ,CAAC,IAAI;AAAA,MAC3C,UAAU,YAAY,CAAC,UAAU,OAAO,KAAK,IAAI;AAAA,MACjD,OAAO,SAAS,WAAW,QAAQ,IAAI;AAAA;AAAA,EACzC;AAEJ;","names":[]}

package/dist/rhf.d.ts

@@ -4,7 +4,7 @@ export { RhfCheckbox, RhfCheckboxProps, RhfCombobox, RhfComboboxProps, RhfDateFi
 export { RhfLineItemCellContext, RhfLineItems, RhfLineItemsColumn, RhfLineItemsProps } from './rhf/line-items.js';
 import 'react';
 import 'react-hook-form';
-import './kit-labels-DE--LmCk.js';
+import './kit-labels-CPbsjlXr.js';
 import './components/data-table-labels.js';
 import './components/mini-calendar.js';
 import './components/calendar-heatmap.js';
@@ -55,6 +55,15 @@ import './components/authed-image.js';
 import './hooks/use-authed-src.js';
 import './components/image-grid.js';
 import './components/lightbox.js';
+import './components/write-lock.js';
+import './components/account-chips.js';
+import './lib/format.js';
+import './data-table-3mi2R3so.js';
+import './components/data-table-sort.js';
+import './components/swipeable-row.js';
+import './components/reauth-dialog.js';
+import './components/server-wake.js';
+import './lib/server-wake.js';
 import './components/number-field.js';
 import './components/number-input.js';
 import './components/calculator.js';

package/dist/search/global-search.d.ts

@@ -26,8 +26,22 @@ declare const DEFAULT_GLOBAL_SEARCH_LABELS: GlobalSearchLabels;
 interface GlobalSearchSource {
     /** Stable key — the effect that runs the source is keyed by it, not by identity. */
     id: string;
-    /** The group its results are shown under (an entry's own `group` is ignored). */
+    /** The group its results are shown under (an entry's own `group` is ignored) — unless
+     *  `groups` is set, where it is only the home of entries that name no declared group.
+     *  If every entry names a declared group, it is never shown: a catch-all heading such
+     *  as "Other" is the honest value, so a stray type would still surface, labelled. */
     group: string;
+    /**
+     * Split ONE request into several groups — kastlan's record search answers with
+     * properties, units, contacts, leases and invoices at once, and one source per group
+     * meant a dedupe layer so the network still saw one request. Each entry is then shown
+     * under the group its own `group` names: a declared `key` (shown by its `label`) or a
+     * plain string (key and heading at once). The groups appear in THIS order whatever the
+     * answer's order, each kept to `limit` rows; an entry naming no declared group falls
+     * under `group`. While the request runs, or when it fails, the source shows one status
+     * line under its first group, not one per group. Unset: one group, as before.
+     */
+    groups?: readonly (string | GlobalSearchSourceGroup)[];
     /** Called with the trimmed query. Its results are shown AS GIVEN — the source ranked
      *  them — and never re-filtered by the index's matcher. `signal` aborts when the query
      *  moves on or the palette closes; a stale answer is dropped either way. */
@@ -36,7 +50,7 @@ interface GlobalSearchSource {
     minChars?: number;
     /** Quiet period after the last keystroke before it is asked. Default 200ms. */
     debounceMs?: number;
-    /** Rows kept. Default: `indexOptions.groupLimit` (8). */
+    /** Rows kept — per group, when `groups` is set. Default: `indexOptions.groupLimit` (8). */
     limit?: number;
     /** Mask every row of this source for session replay, hints (amounts) included. An
      *  entry's own `redact` still wins. */
@@ -45,6 +59,12 @@ interface GlobalSearchSource {
      *  shows the palette's `error` line instead of rows. */
     onError?: (error: unknown) => void;
 }
+/** One of a multi-group source's groups: the `key` its entries name in `group`, and the
+ *  heading shown — so a server's type ("unit") need not be translated per entry. */
+interface GlobalSearchSourceGroup {
+    key: string;
+    label: string;
+}
 /** What a custom trigger gets: everything the default button uses. */
 interface GlobalSearchTriggerProps {
     open: () => void;
@@ -73,7 +93,7 @@ interface GlobalSearchProps {
      * neither re-indexes nor loops, and the icons and handlers used are always the latest.
      */
     entries?: readonly SearchEntry[];
-    /** The async sources, each streamed into its own group. */
+    /** The async sources, each streamed into its own group — or several (`groups`). */
     sources?: readonly GlobalSearchSource[];
     /** What the empty query shows, under the `suggestions` heading. */
     suggestions?: readonly GlobalSearchSuggestion[];
@@ -163,4 +183,4 @@ interface GlobalSearchProps {
  */
 declare function GlobalSearch(props: GlobalSearchProps): react.JSX.Element;
 
-export { DEFAULT_GLOBAL_SEARCH_LABELS, GlobalSearch, type GlobalSearchLabels, type GlobalSearchProps, type GlobalSearchSource, type GlobalSearchSuggestion, type GlobalSearchTriggerProps };
+export { DEFAULT_GLOBAL_SEARCH_LABELS, GlobalSearch, type GlobalSearchLabels, type GlobalSearchProps, type GlobalSearchSource, type GlobalSearchSourceGroup, type GlobalSearchSuggestion, type GlobalSearchTriggerProps };

package/dist/search/global-search.js

@@ -111,7 +111,17 @@ function GlobalSearchImpl({
   const groupLimit = indexOptions?.groupLimit ?? 8;
   const index = useMemo(() => createSearchIndex(list, indexOptions), [sig, optionsKey]);
   const byId = useMemo(() => new Map(list.map((e) => [e.id, e])), [sig]);
-  const sourceKey = (sources ?? []).map((s) => [s.id, s.group, s.minChars ?? 2, s.debounceMs ?? 200, s.limit, s.redact].join("
")).join("");
+  const sourceKey = (sources ?? []).map(
+    (s) => [
+      s.id,
+      s.group,
+      (s.groups ?? []).map((g) => typeof g === "string" ? g : `${g.key}${g.label}`).join(""),
+      s.minChars ?? 2,
+      s.debounceMs ?? 200,
+      s.limit,
+      s.redact
+    ].join("
")
+  ).join("");
   const sourceList = useMemo(() => sources ?? [], [sourceKey]);
   const suggestionsKey = (suggestions ?? []).map((s) => typeof s === "string" ? `i:${s}` : "query" in s ? `q:${s.query}` : `e:${signature([s])}`).join("");
   const suggestionList = useMemo(() => suggestions ?? [], [suggestionsKey]);
@@ -204,10 +214,12 @@ function GlobalSearchImpl({
     for (const source of sourceList) {
       if (q.length < (source.minChars ?? 2)) continue;
       const result = sourceResults[source.id];
+      const declared = (source.groups ?? []).map((g) => typeof g === "string" ? { key: g, label: g } : g);
       const status = (label, icon) => ({
         id: `src:${source.id}:status`,
         label,
-        group: source.group,
+        // One line for the one request, under the group that will head its answer.
+        group: declared[0]?.label ?? source.group,
         icon,
         kind: "status",
         onSelect: noop
@@ -216,10 +228,26 @@ function GlobalSearchImpl({
         out.push(status(pl.loading, /* @__PURE__ */ jsx(Loader2, { className: "size-3.5 animate-spin" })));
       } else if (result.status === "error") {
         out.push(status(pl.error ?? DEFAULT_COMMAND_PALETTE_LABELS.error, /* @__PURE__ */ jsx(AlertCircle, { className: "size-3.5" })));
-      } else {
+      } else if (!declared.length) {
         for (const entry of result.entries.slice(0, source.limit ?? groupLimit)) {
           out.push(toItem(`src:${source.id}:`, entry, source.group, source.redact ?? redactLabels));
         }
+      } else {
+        const buckets = /* @__PURE__ */ new Map();
+        for (const g of declared) buckets.set(g.key, { label: g.label, entries: [] });
+        const rest = [];
+        for (const entry of result.entries) {
+          const bucket = entry.group === void 0 ? void 0 : buckets.get(entry.group);
+          (bucket ? bucket.entries : rest).push(entry);
+        }
+        const limit = source.limit ?? groupLimit;
+        const emit = (key, label, list2) => {
+          for (const entry of list2.slice(0, limit)) {
+            out.push(toItem(`src:${source.id}:${key}:`, entry, label, source.redact ?? redactLabels));
+          }
+        };
+        for (const [key, { label, entries: list2 }] of buckets) emit(key, label, list2);
+        emit("~", source.group, rest);
       }
     }
     return ordered(out);