@declarion/react 0.1.84 → 0.1.86

package/dist-lib/lib/format-count.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Row-count formatting for list views. Display precision MUST match data
+ * accuracy (docs/plans/2026-05-18-declarative-row-count.md, Principle 3):
+ *
+ *   - an exact count renders to the unit with thousands separators
+ *     (3,613,711) - it is known precisely;
+ *   - an estimate renders coarse (~3.6M) - showing an estimate to the unit
+ *     is false precision and is wrong.
+ *
+ * This is the single shared count formatter; the SDK has no other. Field
+ * cell factories that call `toLocaleString` for per-cell numbers are a
+ * separate concern and are not routed through here.
+ */
+/**
+ * formatEstimatedCount renders a coarse estimate: a `~` prefix, ~2
+ * significant figures, and a magnitude suffix (K/M/B).
+ *
+ *   3_613_711 -> "~3.6M"
+ *     850_000 -> "~850K"
+ *      12_000 -> "~12K"
+ *         940 -> "~940"   (below 1000: no suffix, the ~ still signals an estimate)
+ *
+ * Two significant figures: a value's first 2 digits are kept and the rest
+ * collapse to the magnitude suffix. 3_613_711 -> 3.6M (one decimal because
+ * the leading digit is single); 12_000 -> 12K (no decimal because 2 leading
+ * digits already give 2 sig figs).
+ */
+export declare function formatEstimatedCount(total: number): string;
+/**
+ * formatExactCount renders an exact count to the unit with locale thousands
+ * separators: 3613711 -> "3,613,711".
+ */
+export declare function formatExactCount(total: number): string;
+/**
+ * formatCount picks the rendering by the count strategy actually used to
+ * produce `total` (the server's `meta.count_mode`), NOT the entity schema:
+ * a forced exact count must render exact even on a `count: estimated`
+ * entity.
+ */
+export declare function formatCount(total: number, mode: "exact" | "estimated"): string;

package/dist-lib/types/api.d.ts

@@ -1,10 +1,27 @@
 import type { AccentDef, LocalizedString } from "./schema";
 import type { HydratedFile } from "./files";
 export interface ListMeta {
-    total: number;
+    /**
+     * Total matching rows. Present only when the request asked for a count
+     * (`count=with` / `count=only` / `count=exact`). Absent (undefined) on a
+     * window-only response (`count` omitted) - the page of rows arrives
+     * without ever blocking on the count. Treat `count_mode === undefined` as
+     * "no count yet" and ignore `total` then.
+     */
+    total?: number;
     page: number;
     per_page: number;
-    total_pages: number;
+    /** Present only when a count was computed (see `total`). */
+    total_pages?: number;
+    has_more?: boolean;
+    /**
+     * How `total` was produced: "exact" (an exact COUNT(*)) or "estimated"
+     * (an O(1) query-planner estimate). Absent when no count was computed.
+     * The SDK keys display precision on this, NOT on the entity schema, so a
+     * forced exact count renders precisely even on a `count: estimated`
+     * entity.
+     */
+    count_mode?: "exact" | "estimated";
 }
 export interface ListResponse<T = Record<string, unknown>> {
     data: T[];
@@ -206,6 +223,16 @@ export interface ListParams {
      * every column (default, backwards-compatible).
      */
     select?: string[];
+    /**
+     * Row-count strategy for this request. Maps to the `?count=` query param.
+     *   omitted / "window" - rows only, no total (the page-window request;
+     *                        the table never blocks on a count).
+     *   "only"             - total only, no rows (the follow-up count request).
+     *   "with"             - rows + total, using the entity's declared strategy.
+     *   "exact"            - rows + forced exact total.
+     * See docs/plans/2026-05-18-declarative-row-count.md.
+     */
+    count?: "window" | "only" | "with" | "exact";
 }
 /** Minimal filter node type for API params (matches backend FilterNode). */
 export interface FilterNodeParam {

package/dist-lib/types/schema.d.ts

@@ -284,6 +284,16 @@ export interface Entity {
      * docs/plans/completed/2026-05-18-realtime-cdc-redesign.md.
      */
     realtime?: boolean;
+    /**
+     * Per-entity row-count strategy for list views. "exact" (default, also
+     * the meaning of absent) shows an exact total; "estimated" shows an
+     * O(1) query-planner estimate, rendered coarse (~3.6M) for high-volume
+     * tables. Independent of `realtime`. The SDK keys list-view count
+     * precision on the response `meta.count_mode`, not this field, so a
+     * forced exact count still renders precisely. See
+     * docs/plans/2026-05-18-declarative-row-count.md.
+     */
+    count?: "exact" | "estimated";
 }
 export interface ExportConfig {
     enabled?: boolean;