@ai-matrx/design-system 0.22.0 → 0.26.0

package/dist/data-table/coverage.cjs

@@ -0,0 +1,116 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/data-table/coverage.ts
+var coverage_exports = {};
+__export(coverage_exports, {
+  JARGON_WORDS: () => JARGON_WORDS,
+  PARTIAL_BADGE: () => PARTIAL_BADGE,
+  UNKNOWN_TOTAL_BADGE: () => UNKNOWN_TOTAL_BADGE,
+  describeCoverage: () => describeCoverage
+});
+module.exports = __toCommonJS(coverage_exports);
+var PARTIAL_BADGE = "Partial";
+var UNKNOWN_TOTAL_BADGE = "Unknown total";
+var NUMBERS = new Intl.NumberFormat("en-US");
+function formatNumber(value) {
+  try {
+    return NUMBERS.format(value);
+  } catch {
+    return String(value);
+  }
+}
+function pluralize(noun) {
+  const word = noun.trim();
+  if (!word) return "rows";
+  const lower = word.toLowerCase();
+  if (/[^aeiou]y$/.test(lower)) return `${word.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/.test(lower)) return `${word}es`;
+  return `${word}s`;
+}
+function quantity(value, noun) {
+  return `${formatNumber(value)} ${value === 1 ? noun.trim() || "row" : pluralize(noun)}`;
+}
+function toWhole(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function toOptionalWhole(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return void 0;
+  return Math.floor(value);
+}
+function describeCoverage(input) {
+  const safe = input && typeof input === "object" ? input : { loaded: 0, answeredBy: "client" };
+  const loaded = toWhole(safe.loaded);
+  const matched = toOptionalWhole(safe.matched);
+  const total = toOptionalWhole(safe.total);
+  const cap = toOptionalWhole(safe.cap);
+  const answeredBy = safe.answeredBy === "source" ? "source" : "client";
+  const noun = typeof safe.noun === "string" && safe.noun.trim() ? safe.noun.trim() : "row";
+  const reference = matched ?? total;
+  const capReached = cap !== void 0 && cap > 0 && loaded >= cap;
+  if (reference !== void 0 && loaded >= reference) {
+    return {
+      scope: "all",
+      complete: true,
+      count: { value: matched ?? reference, exact: true },
+      notice: "",
+      badge: ""
+    };
+  }
+  if (answeredBy === "source" && matched !== void 0 && !capReached) {
+    return { scope: "all", complete: true, count: { value: matched, exact: true }, notice: "", badge: "" };
+  }
+  if (capReached && cap !== void 0) {
+    const rest = reference !== void 0 ? `${quantity(reference, noun)} in this table; the rest were not looked at.` : "Anything past that was not looked at.";
+    return {
+      scope: "capped",
+      complete: false,
+      count: { value: loaded, exact: false },
+      notice: `This filter searched the first ${quantity(cap, noun)} only. ${rest}`,
+      badge: PARTIAL_BADGE
+    };
+  }
+  if (answeredBy === "client" && reference !== void 0) {
+    return {
+      scope: "loaded",
+      complete: false,
+      count: { value: loaded, exact: false },
+      notice: `Filtering the ${quantity(loaded, noun)} loaded so far, not all ${quantity(reference, noun)} in this table.`,
+      badge: PARTIAL_BADGE
+    };
+  }
+  if (answeredBy === "source" && total !== void 0) {
+    return {
+      scope: "all",
+      complete: false,
+      count: { value: loaded, exact: false },
+      notice: `Showing the ${quantity(loaded, noun)} loaded so far out of ${quantity(total, noun)} in this table.`,
+      badge: PARTIAL_BADGE
+    };
+  }
+  return {
+    scope: answeredBy === "source" ? "all" : "loaded",
+    complete: false,
+    count: { value: loaded, exact: false },
+    notice: `Showing the ${quantity(loaded, noun)} loaded so far. The total number of ${pluralize(noun)} in this table is not known.`,
+    badge: UNKNOWN_TOTAL_BADGE
+  };
+}
+var JARGON_WORDS = ["cap", "limit", "fetch", "query", "client", "source"];
+//# sourceMappingURL=coverage.cjs.map

package/dist/data-table/coverage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/coverage.ts"],"sourcesContent":["/**\n * Honest coverage for the canonical data table.\n *\n * A table that filters over the rows it happens to hold and then prints a count\n * beside them is telling the reader that the count is the answer. When the rows\n * it holds are only part of the table, that is a lie on screen. This module is\n * the model that decides which of the three things is true — the answer covers\n * everything, the answer covers only what is loaded, or a ceiling cut the\n * answer short — and writes the one plain sentence that says so.\n *\n * Pure: no React, no DOM, no formatting beyond `Intl.NumberFormat`. Nothing here\n * throws on any input.\n */\n\nexport type CoverageScope = \"all\" | \"loaded\" | \"capped\";\n\nexport interface CoverageInput {\n  /** Rows the table currently holds. */\n  loaded: number;\n  /** Total rows the source says match the query, when it can say. */\n  matched?: number | undefined;\n  /** Total rows in the table irrespective of the query, when known. */\n  total?: number | undefined;\n  /** Hard ceiling the source imposed on this answer, if any (e.g. a 5,000-row fetch cap). */\n  cap?: number | undefined;\n  /** Whether the SOURCE answered the filters/sort, or the client did over loaded rows. */\n  answeredBy: \"source\" | \"client\";\n  /** What a row is called, for the sentence. Default \"row\". */\n  noun?: string;\n}\n\nexport interface CoverageResult {\n  scope: CoverageScope;\n  /** True only when the answer provably covers every matching row AND the count is exact. */\n  complete: boolean;\n  /** The count to show beside the table, and whether it is exact. */\n  count: { value: number; exact: boolean };\n  /** One plain-English sentence. Empty string when scope is \"all\" and there is nothing to warn about. */\n  notice: string;\n  /** Short label for a badge, e.g. \"Partial\". Empty when complete. */\n  badge: string;\n}\n\n/** Badge for an answer that covers only part of the data. */\nexport const PARTIAL_BADGE = \"Partial\";\n/** Badge for an answer whose own size cannot be stated. */\nexport const UNKNOWN_TOTAL_BADGE = \"Unknown total\";\n\n/* ------------------------------------------------------------------ */\n/* words and numbers                                                   */\n/* ------------------------------------------------------------------ */\n\nconst NUMBERS = new Intl.NumberFormat(\"en-US\");\n\nfunction formatNumber(value: number): string {\n  try {\n    return NUMBERS.format(value);\n  } catch {\n    return String(value);\n  }\n}\n\nfunction pluralize(noun: string): string {\n  const word = noun.trim();\n  if (!word) return \"rows\";\n  const lower = word.toLowerCase();\n  if (/[^aeiou]y$/.test(lower)) return `${word.slice(0, -1)}ies`;\n  if (/(s|x|z|ch|sh)$/.test(lower)) return `${word}es`;\n  return `${word}s`;\n}\n\n/** \"1 row\" / \"84,312 rows\". */\nfunction quantity(value: number, noun: string): string {\n  return `${formatNumber(value)} ${value === 1 ? noun.trim() || \"row\" : pluralize(noun)}`;\n}\n\n/* ------------------------------------------------------------------ */\n/* clamping — nothing here throws                                      */\n/* ------------------------------------------------------------------ */\n\nfunction toWhole(value: unknown): number {\n  return typeof value === \"number\" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n}\n\nfunction toOptionalWhole(value: unknown): number | undefined {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) return undefined;\n  return Math.floor(value);\n}\n\n/* ------------------------------------------------------------------ */\n\n/**\n * Decide what the table is allowed to claim about the answer it is showing.\n *\n * Order of reasoning:\n *  1. If a known figure says everything is already here, the answer is complete\n *     — even when a ceiling exists, because the ceiling was never reached.\n *  2. A source that answered the filters and can state how many rows match is\n *     complete: source-side paging does not make the count a guess.\n *  3. A ceiling the loaded count has reached means part of the data was never\n *     looked at. This is the sentence that replaces the silent lie.\n *  4. A client filtering fewer rows than exist is answering over part of them.\n *  5. When the size of the data is not known at all, say so rather than letting\n *     the loaded count pose as the total.\n */\nexport function describeCoverage(input: CoverageInput): CoverageResult {\n  const safe: CoverageInput = input && typeof input === \"object\" ? input : { loaded: 0, answeredBy: \"client\" };\n  const loaded = toWhole(safe.loaded);\n  const matched = toOptionalWhole(safe.matched);\n  const total = toOptionalWhole(safe.total);\n  const cap = toOptionalWhole(safe.cap);\n  const answeredBy = safe.answeredBy === \"source\" ? \"source\" : \"client\";\n  const noun = typeof safe.noun === \"string\" && safe.noun.trim() ? safe.noun.trim() : \"row\";\n\n  const reference = matched ?? total;\n  const capReached = cap !== undefined && cap > 0 && loaded >= cap;\n\n  // 1. Everything that exists is already here.\n  if (reference !== undefined && loaded >= reference) {\n    return {\n      scope: \"all\",\n      complete: true,\n      count: { value: matched ?? reference, exact: true },\n      notice: \"\",\n      badge: \"\",\n    };\n  }\n\n  // 2. The source answered the filters and stated the size of the answer.\n  if (answeredBy === \"source\" && matched !== undefined && !capReached) {\n    return { scope: \"all\", complete: true, count: { value: matched, exact: true }, notice: \"\", badge: \"\" };\n  }\n\n  // 3. A ceiling cut the answer short.\n  if (capReached && cap !== undefined) {\n    const rest =\n      reference !== undefined\n        ? `${quantity(reference, noun)} in this table; the rest were not looked at.`\n        : \"Anything past that was not looked at.\";\n    return {\n      scope: \"capped\",\n      complete: false,\n      count: { value: loaded, exact: false },\n      notice: `This filter searched the first ${quantity(cap, noun)} only. ${rest}`,\n      badge: PARTIAL_BADGE,\n    };\n  }\n\n  // 4. The client is filtering over fewer rows than exist.\n  if (answeredBy === \"client\" && reference !== undefined) {\n    return {\n      scope: \"loaded\",\n      complete: false,\n      count: { value: loaded, exact: false },\n      notice: `Filtering the ${quantity(loaded, noun)} loaded so far, not all ${quantity(reference, noun)} in this table.`,\n      badge: PARTIAL_BADGE,\n    };\n  }\n\n  // 5a. The source answered everything but cannot say how big the answer is.\n  if (answeredBy === \"source\" && total !== undefined) {\n    return {\n      scope: \"all\",\n      complete: false,\n      count: { value: loaded, exact: false },\n      notice: `Showing the ${quantity(loaded, noun)} loaded so far out of ${quantity(total, noun)} in this table.`,\n      badge: PARTIAL_BADGE,\n    };\n  }\n\n  // 5b. Nothing is known beyond what is on screen.\n  return {\n    scope: answeredBy === \"source\" ? \"all\" : \"loaded\",\n    complete: false,\n    count: { value: loaded, exact: false },\n    notice: `Showing the ${quantity(loaded, noun)} loaded so far. The total number of ${pluralize(noun)} in this table is not known.`,\n    badge: UNKNOWN_TOTAL_BADGE,\n  };\n}\n\n/** Words a sentence for a non-technical reader must never contain. */\nexport const JARGON_WORDS = [\"cap\", \"limit\", \"fetch\", \"query\", \"client\", \"source\"] as const;\n"],"mappings":"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","names":[]}

package/dist/data-table/coverage.d.cts

@@ -0,0 +1,65 @@
+/**
+ * Honest coverage for the canonical data table.
+ *
+ * A table that filters over the rows it happens to hold and then prints a count
+ * beside them is telling the reader that the count is the answer. When the rows
+ * it holds are only part of the table, that is a lie on screen. This module is
+ * the model that decides which of the three things is true — the answer covers
+ * everything, the answer covers only what is loaded, or a ceiling cut the
+ * answer short — and writes the one plain sentence that says so.
+ *
+ * Pure: no React, no DOM, no formatting beyond `Intl.NumberFormat`. Nothing here
+ * throws on any input.
+ */
+type CoverageScope = "all" | "loaded" | "capped";
+interface CoverageInput {
+    /** Rows the table currently holds. */
+    loaded: number;
+    /** Total rows the source says match the query, when it can say. */
+    matched?: number | undefined;
+    /** Total rows in the table irrespective of the query, when known. */
+    total?: number | undefined;
+    /** Hard ceiling the source imposed on this answer, if any (e.g. a 5,000-row fetch cap). */
+    cap?: number | undefined;
+    /** Whether the SOURCE answered the filters/sort, or the client did over loaded rows. */
+    answeredBy: "source" | "client";
+    /** What a row is called, for the sentence. Default "row". */
+    noun?: string;
+}
+interface CoverageResult {
+    scope: CoverageScope;
+    /** True only when the answer provably covers every matching row AND the count is exact. */
+    complete: boolean;
+    /** The count to show beside the table, and whether it is exact. */
+    count: {
+        value: number;
+        exact: boolean;
+    };
+    /** One plain-English sentence. Empty string when scope is "all" and there is nothing to warn about. */
+    notice: string;
+    /** Short label for a badge, e.g. "Partial". Empty when complete. */
+    badge: string;
+}
+/** Badge for an answer that covers only part of the data. */
+declare const PARTIAL_BADGE = "Partial";
+/** Badge for an answer whose own size cannot be stated. */
+declare const UNKNOWN_TOTAL_BADGE = "Unknown total";
+/**
+ * Decide what the table is allowed to claim about the answer it is showing.
+ *
+ * Order of reasoning:
+ *  1. If a known figure says everything is already here, the answer is complete
+ *     — even when a ceiling exists, because the ceiling was never reached.
+ *  2. A source that answered the filters and can state how many rows match is
+ *     complete: source-side paging does not make the count a guess.
+ *  3. A ceiling the loaded count has reached means part of the data was never
+ *     looked at. This is the sentence that replaces the silent lie.
+ *  4. A client filtering fewer rows than exist is answering over part of them.
+ *  5. When the size of the data is not known at all, say so rather than letting
+ *     the loaded count pose as the total.
+ */
+declare function describeCoverage(input: CoverageInput): CoverageResult;
+/** Words a sentence for a non-technical reader must never contain. */
+declare const JARGON_WORDS: readonly ["cap", "limit", "fetch", "query", "client", "source"];
+
+export { type CoverageInput, type CoverageResult, type CoverageScope, JARGON_WORDS, PARTIAL_BADGE, UNKNOWN_TOTAL_BADGE, describeCoverage };

package/dist/data-table/coverage.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Honest coverage for the canonical data table.
+ *
+ * A table that filters over the rows it happens to hold and then prints a count
+ * beside them is telling the reader that the count is the answer. When the rows
+ * it holds are only part of the table, that is a lie on screen. This module is
+ * the model that decides which of the three things is true — the answer covers
+ * everything, the answer covers only what is loaded, or a ceiling cut the
+ * answer short — and writes the one plain sentence that says so.
+ *
+ * Pure: no React, no DOM, no formatting beyond `Intl.NumberFormat`. Nothing here
+ * throws on any input.
+ */
+type CoverageScope = "all" | "loaded" | "capped";
+interface CoverageInput {
+    /** Rows the table currently holds. */
+    loaded: number;
+    /** Total rows the source says match the query, when it can say. */
+    matched?: number | undefined;
+    /** Total rows in the table irrespective of the query, when known. */
+    total?: number | undefined;
+    /** Hard ceiling the source imposed on this answer, if any (e.g. a 5,000-row fetch cap). */
+    cap?: number | undefined;
+    /** Whether the SOURCE answered the filters/sort, or the client did over loaded rows. */
+    answeredBy: "source" | "client";
+    /** What a row is called, for the sentence. Default "row". */
+    noun?: string;
+}
+interface CoverageResult {
+    scope: CoverageScope;
+    /** True only when the answer provably covers every matching row AND the count is exact. */
+    complete: boolean;
+    /** The count to show beside the table, and whether it is exact. */
+    count: {
+        value: number;
+        exact: boolean;
+    };
+    /** One plain-English sentence. Empty string when scope is "all" and there is nothing to warn about. */
+    notice: string;
+    /** Short label for a badge, e.g. "Partial". Empty when complete. */
+    badge: string;
+}
+/** Badge for an answer that covers only part of the data. */
+declare const PARTIAL_BADGE = "Partial";
+/** Badge for an answer whose own size cannot be stated. */
+declare const UNKNOWN_TOTAL_BADGE = "Unknown total";
+/**
+ * Decide what the table is allowed to claim about the answer it is showing.
+ *
+ * Order of reasoning:
+ *  1. If a known figure says everything is already here, the answer is complete
+ *     — even when a ceiling exists, because the ceiling was never reached.
+ *  2. A source that answered the filters and can state how many rows match is
+ *     complete: source-side paging does not make the count a guess.
+ *  3. A ceiling the loaded count has reached means part of the data was never
+ *     looked at. This is the sentence that replaces the silent lie.
+ *  4. A client filtering fewer rows than exist is answering over part of them.
+ *  5. When the size of the data is not known at all, say so rather than letting
+ *     the loaded count pose as the total.
+ */
+declare function describeCoverage(input: CoverageInput): CoverageResult;
+/** Words a sentence for a non-technical reader must never contain. */
+declare const JARGON_WORDS: readonly ["cap", "limit", "fetch", "query", "client", "source"];
+
+export { type CoverageInput, type CoverageResult, type CoverageScope, JARGON_WORDS, PARTIAL_BADGE, UNKNOWN_TOTAL_BADGE, describeCoverage };

package/dist/data-table/coverage.js

@@ -0,0 +1,96 @@
+
+// src/data-table/coverage.ts
+var PARTIAL_BADGE = "Partial";
+var UNKNOWN_TOTAL_BADGE = "Unknown total";
+var NUMBERS = new Intl.NumberFormat("en-US");
+function formatNumber(value) {
+  try {
+    return NUMBERS.format(value);
+  } catch {
+    return String(value);
+  }
+}
+function pluralize(noun) {
+  const word = noun.trim();
+  if (!word) return "rows";
+  const lower = word.toLowerCase();
+  if (/[^aeiou]y$/.test(lower)) return `${word.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/.test(lower)) return `${word}es`;
+  return `${word}s`;
+}
+function quantity(value, noun) {
+  return `${formatNumber(value)} ${value === 1 ? noun.trim() || "row" : pluralize(noun)}`;
+}
+function toWhole(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+}
+function toOptionalWhole(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return void 0;
+  return Math.floor(value);
+}
+function describeCoverage(input) {
+  const safe = input && typeof input === "object" ? input : { loaded: 0, answeredBy: "client" };
+  const loaded = toWhole(safe.loaded);
+  const matched = toOptionalWhole(safe.matched);
+  const total = toOptionalWhole(safe.total);
+  const cap = toOptionalWhole(safe.cap);
+  const answeredBy = safe.answeredBy === "source" ? "source" : "client";
+  const noun = typeof safe.noun === "string" && safe.noun.trim() ? safe.noun.trim() : "row";
+  const reference = matched ?? total;
+  const capReached = cap !== void 0 && cap > 0 && loaded >= cap;
+  if (reference !== void 0 && loaded >= reference) {
+    return {
+      scope: "all",
+      complete: true,
+      count: { value: matched ?? reference, exact: true },
+      notice: "",
+      badge: ""
+    };
+  }
+  if (answeredBy === "source" && matched !== void 0 && !capReached) {
+    return { scope: "all", complete: true, count: { value: matched, exact: true }, notice: "", badge: "" };
+  }
+  if (capReached && cap !== void 0) {
+    const rest = reference !== void 0 ? `${quantity(reference, noun)} in this table; the rest were not looked at.` : "Anything past that was not looked at.";
+    return {
+      scope: "capped",
+      complete: false,
+      count: { value: loaded, exact: false },
+      notice: `This filter searched the first ${quantity(cap, noun)} only. ${rest}`,
+      badge: PARTIAL_BADGE
+    };
+  }
+  if (answeredBy === "client" && reference !== void 0) {
+    return {
+      scope: "loaded",
+      complete: false,
+      count: { value: loaded, exact: false },
+      notice: `Filtering the ${quantity(loaded, noun)} loaded so far, not all ${quantity(reference, noun)} in this table.`,
+      badge: PARTIAL_BADGE
+    };
+  }
+  if (answeredBy === "source" && total !== void 0) {
+    return {
+      scope: "all",
+      complete: false,
+      count: { value: loaded, exact: false },
+      notice: `Showing the ${quantity(loaded, noun)} loaded so far out of ${quantity(total, noun)} in this table.`,
+      badge: PARTIAL_BADGE
+    };
+  }
+  return {
+    scope: answeredBy === "source" ? "all" : "loaded",
+    complete: false,
+    count: { value: loaded, exact: false },
+    notice: `Showing the ${quantity(loaded, noun)} loaded so far. The total number of ${pluralize(noun)} in this table is not known.`,
+    badge: UNKNOWN_TOTAL_BADGE
+  };
+}
+var JARGON_WORDS = ["cap", "limit", "fetch", "query", "client", "source"];
+export {
+  JARGON_WORDS,
+  PARTIAL_BADGE,
+  UNKNOWN_TOTAL_BADGE,
+  describeCoverage
+};
+//# sourceMappingURL=coverage.js.map

package/dist/data-table/coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/coverage.ts"],"sourcesContent":["/**\n * Honest coverage for the canonical data table.\n *\n * A table that filters over the rows it happens to hold and then prints a count\n * beside them is telling the reader that the count is the answer. When the rows\n * it holds are only part of the table, that is a lie on screen. This module is\n * the model that decides which of the three things is true — the answer covers\n * everything, the answer covers only what is loaded, or a ceiling cut the\n * answer short — and writes the one plain sentence that says so.\n *\n * Pure: no React, no DOM, no formatting beyond `Intl.NumberFormat`. Nothing here\n * throws on any input.\n */\n\nexport type CoverageScope = \"all\" | \"loaded\" | \"capped\";\n\nexport interface CoverageInput {\n  /** Rows the table currently holds. */\n  loaded: number;\n  /** Total rows the source says match the query, when it can say. */\n  matched?: number | undefined;\n  /** Total rows in the table irrespective of the query, when known. */\n  total?: number | undefined;\n  /** Hard ceiling the source imposed on this answer, if any (e.g. a 5,000-row fetch cap). */\n  cap?: number | undefined;\n  /** Whether the SOURCE answered the filters/sort, or the client did over loaded rows. */\n  answeredBy: \"source\" | \"client\";\n  /** What a row is called, for the sentence. Default \"row\". */\n  noun?: string;\n}\n\nexport interface CoverageResult {\n  scope: CoverageScope;\n  /** True only when the answer provably covers every matching row AND the count is exact. */\n  complete: boolean;\n  /** The count to show beside the table, and whether it is exact. */\n  count: { value: number; exact: boolean };\n  /** One plain-English sentence. Empty string when scope is \"all\" and there is nothing to warn about. */\n  notice: string;\n  /** Short label for a badge, e.g. \"Partial\". Empty when complete. */\n  badge: string;\n}\n\n/** Badge for an answer that covers only part of the data. */\nexport const PARTIAL_BADGE = \"Partial\";\n/** Badge for an answer whose own size cannot be stated. */\nexport const UNKNOWN_TOTAL_BADGE = \"Unknown total\";\n\n/* ------------------------------------------------------------------ */\n/* words and numbers                                                   */\n/* ------------------------------------------------------------------ */\n\nconst NUMBERS = new Intl.NumberFormat(\"en-US\");\n\nfunction formatNumber(value: number): string {\n  try {\n    return NUMBERS.format(value);\n  } catch {\n    return String(value);\n  }\n}\n\nfunction pluralize(noun: string): string {\n  const word = noun.trim();\n  if (!word) return \"rows\";\n  const lower = word.toLowerCase();\n  if (/[^aeiou]y$/.test(lower)) return `${word.slice(0, -1)}ies`;\n  if (/(s|x|z|ch|sh)$/.test(lower)) return `${word}es`;\n  return `${word}s`;\n}\n\n/** \"1 row\" / \"84,312 rows\". */\nfunction quantity(value: number, noun: string): string {\n  return `${formatNumber(value)} ${value === 1 ? noun.trim() || \"row\" : pluralize(noun)}`;\n}\n\n/* ------------------------------------------------------------------ */\n/* clamping — nothing here throws                                      */\n/* ------------------------------------------------------------------ */\n\nfunction toWhole(value: unknown): number {\n  return typeof value === \"number\" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;\n}\n\nfunction toOptionalWhole(value: unknown): number | undefined {\n  if (typeof value !== \"number\" || !Number.isFinite(value) || value < 0) return undefined;\n  return Math.floor(value);\n}\n\n/* ------------------------------------------------------------------ */\n\n/**\n * Decide what the table is allowed to claim about the answer it is showing.\n *\n * Order of reasoning:\n *  1. If a known figure says everything is already here, the answer is complete\n *     — even when a ceiling exists, because the ceiling was never reached.\n *  2. A source that answered the filters and can state how many rows match is\n *     complete: source-side paging does not make the count a guess.\n *  3. A ceiling the loaded count has reached means part of the data was never\n *     looked at. This is the sentence that replaces the silent lie.\n *  4. A client filtering fewer rows than exist is answering over part of them.\n *  5. When the size of the data is not known at all, say so rather than letting\n *     the loaded count pose as the total.\n */\nexport function describeCoverage(input: CoverageInput): CoverageResult {\n  const safe: CoverageInput = input && typeof input === \"object\" ? input : { loaded: 0, answeredBy: \"client\" };\n  const loaded = toWhole(safe.loaded);\n  const matched = toOptionalWhole(safe.matched);\n  const total = toOptionalWhole(safe.total);\n  const cap = toOptionalWhole(safe.cap);\n  const answeredBy = safe.answeredBy === \"source\" ? \"source\" : \"client\";\n  const noun = typeof safe.noun === \"string\" && safe.noun.trim() ? safe.noun.trim() : \"row\";\n\n  const reference = matched ?? total;\n  const capReached = cap !== undefined && cap > 0 && loaded >= cap;\n\n  // 1. Everything that exists is already here.\n  if (reference !== undefined && loaded >= reference) {\n    return {\n      scope: \"all\",\n      complete: true,\n      count: { value: matched ?? reference, exact: true },\n      notice: \"\",\n      badge: \"\",\n    };\n  }\n\n  // 2. The source answered the filters and stated the size of the answer.\n  if (answeredBy === \"source\" && matched !== undefined && !capReached) {\n    return { scope: \"all\", complete: true, count: { value: matched, exact: true }, notice: \"\", badge: \"\" };\n  }\n\n  // 3. A ceiling cut the answer short.\n  if (capReached && cap !== undefined) {\n    const rest =\n      reference !== undefined\n        ? `${quantity(reference, noun)} in this table; the rest were not looked at.`\n        : \"Anything past that was not looked at.\";\n    return {\n      scope: \"capped\",\n      complete: false,\n      count: { value: loaded, exact: false },\n      notice: `This filter searched the first ${quantity(cap, noun)} only. ${rest}`,\n      badge: PARTIAL_BADGE,\n    };\n  }\n\n  // 4. The client is filtering over fewer rows than exist.\n  if (answeredBy === \"client\" && reference !== undefined) {\n    return {\n      scope: \"loaded\",\n      complete: false,\n      count: { value: loaded, exact: false },\n      notice: `Filtering the ${quantity(loaded, noun)} loaded so far, not all ${quantity(reference, noun)} in this table.`,\n      badge: PARTIAL_BADGE,\n    };\n  }\n\n  // 5a. The source answered everything but cannot say how big the answer is.\n  if (answeredBy === \"source\" && total !== undefined) {\n    return {\n      scope: \"all\",\n      complete: false,\n      count: { value: loaded, exact: false },\n      notice: `Showing the ${quantity(loaded, noun)} loaded so far out of ${quantity(total, noun)} in this table.`,\n      badge: PARTIAL_BADGE,\n    };\n  }\n\n  // 5b. Nothing is known beyond what is on screen.\n  return {\n    scope: answeredBy === \"source\" ? \"all\" : \"loaded\",\n    complete: false,\n    count: { value: loaded, exact: false },\n    notice: `Showing the ${quantity(loaded, noun)} loaded so far. The total number of ${pluralize(noun)} in this table is not known.`,\n    badge: UNKNOWN_TOTAL_BADGE,\n  };\n}\n\n/** Words a sentence for a non-technical reader must never contain. */\nexport const JARGON_WORDS = [\"cap\", \"limit\", \"fetch\", \"query\", \"client\", \"source\"] as const;\n"],"mappings":"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","names":[]}