@ai-matrx/design-system 0.22.0 → 0.26.0

package/dist/data-table/facets.cjs

@@ -0,0 +1,118 @@
+"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/facets.ts
+var facets_exports = {};
+__export(facets_exports, {
+  FACETS_LOADING_NOTICE: () => FACETS_LOADING_NOTICE,
+  MAX_LISTABLE_FACET_LENGTH: () => MAX_LISTABLE_FACET_LENGTH,
+  computeColumnFacets: () => computeColumnFacets,
+  describeFacetFailure: () => describeFacetFailure,
+  describeFacetSource: () => describeFacetSource,
+  localFacetsAreComplete: () => localFacetsAreComplete
+});
+module.exports = __toCommonJS(facets_exports);
+var MAX_LISTABLE_FACET_LENGTH = 300;
+var DEFAULT_FACET_LIMIT = 200;
+var MAX_FACET_LIMIT = 500;
+function facetText(raw) {
+  if (raw === null || raw === void 0) return "";
+  if (typeof raw === "object") {
+    try {
+      return JSON.stringify(raw);
+    } catch {
+      return String(raw);
+    }
+  }
+  return String(raw);
+}
+function computeColumnFacets(args) {
+  const { columnId, rows, readValue } = args;
+  const limit = Math.min(Math.max(args.limit ?? DEFAULT_FACET_LIMIT, 1), MAX_FACET_LIMIT);
+  const counts = /* @__PURE__ */ new Map();
+  const longValues = /* @__PURE__ */ new Set();
+  let blank = 0;
+  let maxLength = 0;
+  for (const row of rows) {
+    let raw;
+    try {
+      raw = readValue(row, columnId);
+    } catch {
+      raw = void 0;
+    }
+    const trimmed = facetText(raw).trim();
+    if (trimmed === "") {
+      blank += 1;
+      continue;
+    }
+    if (trimmed.length > maxLength) maxLength = trimmed.length;
+    if (trimmed.length > MAX_LISTABLE_FACET_LENGTH) {
+      longValues.add(trimmed);
+      continue;
+    }
+    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+  }
+  const values = [...counts.entries()].map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count || a.value.localeCompare(b.value)).slice(0, limit);
+  return {
+    columnId,
+    totalRows: rows.length,
+    filled: rows.length - blank,
+    blank,
+    distinctCount: counts.size + longValues.size,
+    maxLength,
+    unlistable: longValues.size,
+    limit,
+    truncated: counts.size > limit,
+    values,
+    answeredBy: "local",
+    complete: args.complete ?? true
+  };
+}
+function localFacetsAreComplete(loadedRowCount, total) {
+  if (total === void 0 || !Number.isFinite(total) || total < 0) return false;
+  return loadedRowCount >= total;
+}
+var NUMBERS = new Intl.NumberFormat("en-US");
+function n(value) {
+  try {
+    return NUMBERS.format(value);
+  } catch {
+    return String(value);
+  }
+}
+function describeFacetSource(facets, noun = "row") {
+  if (!facets) return "";
+  const plural = `${noun}s`;
+  if (!facets.complete) {
+    return `These counts cover the ${n(facets.totalRows)} ${plural} loaded here, not the whole table.`;
+  }
+  if (facets.truncated) {
+    return `Showing the ${n(facets.values.length)} most common of ${n(facets.distinctCount)} values.`;
+  }
+  if (facets.unlistable > 0) {
+    return `${n(facets.unlistable)} ${facets.unlistable === 1 ? "value is" : "values are"} too long to list. Match text instead to reach ${facets.unlistable === 1 ? "it" : "them"}.`;
+  }
+  return "";
+}
+var FACETS_LOADING_NOTICE = "Counting values\u2026";
+function describeFacetFailure(error) {
+  const detail = error instanceof Error ? error.message : String(error ?? "");
+  return detail ? `The values in this column could not be counted: ${detail} Match text instead.` : "The values in this column could not be counted. Match text instead.";
+}
+//# sourceMappingURL=facets.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/facets.ts"],"sourcesContent":["/**\n * @ai-matrx/design-system/data-table — COLUMN FACETS: the values a column\n * actually holds, and how many rows carry each one.\n *\n * A filter box that says \"Contains…\" asks the reader to already know what is in\n * the column. A checklist of the real values, each with its count, tells them —\n * and the values that surprise you (the one-off typo, the stray casing, the\n * blank nobody filled in) are exactly the ones a text box hides.\n *\n * THE TWO LAWS this module exists to keep:\n *\n * 1. **Counts are computed locally ONLY when the browser holds every row the\n *    counts describe.** `localFacetsAreComplete` is the test, and it compares\n *    the loaded row count against the total AFTER the active search, because\n *    that is the population the counts claim to describe. One page of rows\n *    would produce counts that look authoritative and are not. When the browser\n *    does not hold them all, the consumer's `source` answers from the database.\n *\n * 2. **A partial answer says so, in a sentence.** `describeFacetSource` writes\n *    the one line the popover shows. There is no silent fallback: if the\n *    database could not be asked, or answered only part of the truth, the\n *    reader is told before they act on the list.\n *\n * Pure: no React, no DOM, no network. Nothing here throws on any input.\n */\n\n/** One distinct value of a column and how many rows carry it. */\nexport interface ColumnFacetValue {\n  value: string;\n  count: number;\n}\n\n/**\n * What one column holds. `values` is the top slice by frequency; the counts\n * that describe the WHOLE column — `totalRows`, `filled`, `blank`,\n * `distinctCount` — are always about every row considered, never about the\n * slice, which is what makes `truncated` meaningful rather than decorative.\n */\nexport interface ColumnFacets {\n  columnId: string;\n  /** Rows considered (after the active search, if any). */\n  totalRows: number;\n  /** Rows whose cell is non-empty. */\n  filled: number;\n  /** Rows whose cell is null or whitespace-only — a real filter target. */\n  blank: number;\n  /** Distinct non-empty values across EVERY row, not just `values`. */\n  distinctCount: number;\n  /** Longest value; a caller refuses a picker on a column of long prose. */\n  maxLength: number;\n  /** Distinct values too long to offer as options. */\n  unlistable: number;\n  limit: number;\n  /** True when `values` does not carry every listable distinct value. */\n  truncated: boolean;\n  /** Top values by frequency, descending; ties broken by the value itself. */\n  values: ColumnFacetValue[];\n  /** Who counted. \"source\" is the database; \"local\" is the rows in the browser. */\n  answeredBy: \"source\" | \"local\";\n  /**\n   * True when the counts describe every row of the column. False means the\n   * reader is looking at a partial answer and the popover must say so.\n   */\n  complete: boolean;\n}\n\n/** A value longer than this is real data, not a pickable option. */\nexport const MAX_LISTABLE_FACET_LENGTH = 300;\n\nconst DEFAULT_FACET_LIMIT = 200;\nconst MAX_FACET_LIMIT = 500;\n\nfunction facetText(raw: unknown): string {\n  if (raw === null || raw === undefined) return \"\";\n  if (typeof raw === \"object\") {\n    try {\n      return JSON.stringify(raw);\n    } catch {\n      return String(raw);\n    }\n  }\n  return String(raw);\n}\n\n/**\n * Compute a column's facets from rows already in memory.\n *\n * `rows` MUST be every row the facets are meant to describe — the caller\n * decides that with `localFacetsAreComplete`. `complete` carries the caller's\n * verdict through to the popover so a partial answer can never be printed as a\n * whole one.\n */\nexport function computeColumnFacets(args: {\n  columnId: string;\n  rows: readonly unknown[];\n  readValue: (row: unknown, columnId: string) => unknown;\n  limit?: number | undefined;\n  complete?: boolean | undefined;\n}): ColumnFacets {\n  const { columnId, rows, readValue } = args;\n  const limit = Math.min(Math.max(args.limit ?? DEFAULT_FACET_LIMIT, 1), MAX_FACET_LIMIT);\n\n  const counts = new Map<string, number>();\n  const longValues = new Set<string>();\n  let blank = 0;\n  let maxLength = 0;\n\n  for (const row of rows) {\n    let raw: unknown;\n    try {\n      raw = readValue(row, columnId);\n    } catch {\n      raw = undefined;\n    }\n    const trimmed = facetText(raw).trim();\n    if (trimmed === \"\") {\n      blank += 1;\n      continue;\n    }\n    if (trimmed.length > maxLength) maxLength = trimmed.length;\n    if (trimmed.length > MAX_LISTABLE_FACET_LENGTH) {\n      longValues.add(trimmed);\n      continue;\n    }\n    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);\n  }\n\n  const values: ColumnFacetValue[] = [...counts.entries()]\n    .map(([value, count]) => ({ value, count }))\n    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value))\n    .slice(0, limit);\n\n  return {\n    columnId,\n    totalRows: rows.length,\n    filled: rows.length - blank,\n    blank,\n    distinctCount: counts.size + longValues.size,\n    maxLength,\n    unlistable: longValues.size,\n    limit,\n    truncated: counts.size > limit,\n    values,\n    answeredBy: \"local\",\n    complete: args.complete ?? true,\n  };\n}\n\n/**\n * May facets be computed from these rows, or must the source be asked?\n *\n * The ONLY safe condition is holding every row the facets describe. `total` is\n * the row count AFTER the active search, which is exactly what the loaded rows\n * also reflect — so comparing counts is a true completeness test, not a guess.\n * An unknown total is never treated as \"small enough\".\n */\nexport function localFacetsAreComplete(\n  loadedRowCount: number,\n  total: number | undefined,\n): boolean {\n  if (total === undefined || !Number.isFinite(total) || total < 0) return false;\n  return loadedRowCount >= total;\n}\n\nconst NUMBERS = new Intl.NumberFormat(\"en-US\");\n\nfunction n(value: number): string {\n  try {\n    return NUMBERS.format(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * The one sentence under the value list. Empty when the answer is whole and\n * nothing needs saying — the popover never nags a reader whose counts are\n * exact.\n */\nexport function describeFacetSource(\n  facets: ColumnFacets | null | undefined,\n  noun = \"row\",\n): string {\n  if (!facets) return \"\";\n  const plural = `${noun}s`;\n  if (!facets.complete) {\n    return `These counts cover the ${n(facets.totalRows)} ${plural} loaded here, not the whole table.`;\n  }\n  if (facets.truncated) {\n    return `Showing the ${n(facets.values.length)} most common of ${n(facets.distinctCount)} values.`;\n  }\n  if (facets.unlistable > 0) {\n    return `${n(facets.unlistable)} ${facets.unlistable === 1 ? \"value is\" : \"values are\"} too long to list. Match text instead to reach ${facets.unlistable === 1 ? \"it\" : \"them\"}.`;\n  }\n  return \"\";\n}\n\n/** The sentence shown while the source is being asked, and when it refuses. */\nexport const FACETS_LOADING_NOTICE = \"Counting values…\";\nexport function describeFacetFailure(error: unknown): string {\n  const detail = error instanceof Error ? error.message : String(error ?? \"\");\n  return detail\n    ? `The values in this column could not be counted: ${detail} Match text instead.`\n    : \"The values in this column could not be counted. Match text instead.\";\n}\n"],"mappings":"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","names":[]}

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

@@ -0,0 +1,100 @@
+/**
+ * @ai-matrx/design-system/data-table — COLUMN FACETS: the values a column
+ * actually holds, and how many rows carry each one.
+ *
+ * A filter box that says "Contains…" asks the reader to already know what is in
+ * the column. A checklist of the real values, each with its count, tells them —
+ * and the values that surprise you (the one-off typo, the stray casing, the
+ * blank nobody filled in) are exactly the ones a text box hides.
+ *
+ * THE TWO LAWS this module exists to keep:
+ *
+ * 1. **Counts are computed locally ONLY when the browser holds every row the
+ *    counts describe.** `localFacetsAreComplete` is the test, and it compares
+ *    the loaded row count against the total AFTER the active search, because
+ *    that is the population the counts claim to describe. One page of rows
+ *    would produce counts that look authoritative and are not. When the browser
+ *    does not hold them all, the consumer's `source` answers from the database.
+ *
+ * 2. **A partial answer says so, in a sentence.** `describeFacetSource` writes
+ *    the one line the popover shows. There is no silent fallback: if the
+ *    database could not be asked, or answered only part of the truth, the
+ *    reader is told before they act on the list.
+ *
+ * Pure: no React, no DOM, no network. Nothing here throws on any input.
+ */
+/** One distinct value of a column and how many rows carry it. */
+interface ColumnFacetValue {
+    value: string;
+    count: number;
+}
+/**
+ * What one column holds. `values` is the top slice by frequency; the counts
+ * that describe the WHOLE column — `totalRows`, `filled`, `blank`,
+ * `distinctCount` — are always about every row considered, never about the
+ * slice, which is what makes `truncated` meaningful rather than decorative.
+ */
+interface ColumnFacets {
+    columnId: string;
+    /** Rows considered (after the active search, if any). */
+    totalRows: number;
+    /** Rows whose cell is non-empty. */
+    filled: number;
+    /** Rows whose cell is null or whitespace-only — a real filter target. */
+    blank: number;
+    /** Distinct non-empty values across EVERY row, not just `values`. */
+    distinctCount: number;
+    /** Longest value; a caller refuses a picker on a column of long prose. */
+    maxLength: number;
+    /** Distinct values too long to offer as options. */
+    unlistable: number;
+    limit: number;
+    /** True when `values` does not carry every listable distinct value. */
+    truncated: boolean;
+    /** Top values by frequency, descending; ties broken by the value itself. */
+    values: ColumnFacetValue[];
+    /** Who counted. "source" is the database; "local" is the rows in the browser. */
+    answeredBy: "source" | "local";
+    /**
+     * True when the counts describe every row of the column. False means the
+     * reader is looking at a partial answer and the popover must say so.
+     */
+    complete: boolean;
+}
+/** A value longer than this is real data, not a pickable option. */
+declare const MAX_LISTABLE_FACET_LENGTH = 300;
+/**
+ * Compute a column's facets from rows already in memory.
+ *
+ * `rows` MUST be every row the facets are meant to describe — the caller
+ * decides that with `localFacetsAreComplete`. `complete` carries the caller's
+ * verdict through to the popover so a partial answer can never be printed as a
+ * whole one.
+ */
+declare function computeColumnFacets(args: {
+    columnId: string;
+    rows: readonly unknown[];
+    readValue: (row: unknown, columnId: string) => unknown;
+    limit?: number | undefined;
+    complete?: boolean | undefined;
+}): ColumnFacets;
+/**
+ * May facets be computed from these rows, or must the source be asked?
+ *
+ * The ONLY safe condition is holding every row the facets describe. `total` is
+ * the row count AFTER the active search, which is exactly what the loaded rows
+ * also reflect — so comparing counts is a true completeness test, not a guess.
+ * An unknown total is never treated as "small enough".
+ */
+declare function localFacetsAreComplete(loadedRowCount: number, total: number | undefined): boolean;
+/**
+ * The one sentence under the value list. Empty when the answer is whole and
+ * nothing needs saying — the popover never nags a reader whose counts are
+ * exact.
+ */
+declare function describeFacetSource(facets: ColumnFacets | null | undefined, noun?: string): string;
+/** The sentence shown while the source is being asked, and when it refuses. */
+declare const FACETS_LOADING_NOTICE = "Counting values\u2026";
+declare function describeFacetFailure(error: unknown): string;
+
+export { type ColumnFacetValue, type ColumnFacets, FACETS_LOADING_NOTICE, MAX_LISTABLE_FACET_LENGTH, computeColumnFacets, describeFacetFailure, describeFacetSource, localFacetsAreComplete };

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

@@ -0,0 +1,100 @@
+/**
+ * @ai-matrx/design-system/data-table — COLUMN FACETS: the values a column
+ * actually holds, and how many rows carry each one.
+ *
+ * A filter box that says "Contains…" asks the reader to already know what is in
+ * the column. A checklist of the real values, each with its count, tells them —
+ * and the values that surprise you (the one-off typo, the stray casing, the
+ * blank nobody filled in) are exactly the ones a text box hides.
+ *
+ * THE TWO LAWS this module exists to keep:
+ *
+ * 1. **Counts are computed locally ONLY when the browser holds every row the
+ *    counts describe.** `localFacetsAreComplete` is the test, and it compares
+ *    the loaded row count against the total AFTER the active search, because
+ *    that is the population the counts claim to describe. One page of rows
+ *    would produce counts that look authoritative and are not. When the browser
+ *    does not hold them all, the consumer's `source` answers from the database.
+ *
+ * 2. **A partial answer says so, in a sentence.** `describeFacetSource` writes
+ *    the one line the popover shows. There is no silent fallback: if the
+ *    database could not be asked, or answered only part of the truth, the
+ *    reader is told before they act on the list.
+ *
+ * Pure: no React, no DOM, no network. Nothing here throws on any input.
+ */
+/** One distinct value of a column and how many rows carry it. */
+interface ColumnFacetValue {
+    value: string;
+    count: number;
+}
+/**
+ * What one column holds. `values` is the top slice by frequency; the counts
+ * that describe the WHOLE column — `totalRows`, `filled`, `blank`,
+ * `distinctCount` — are always about every row considered, never about the
+ * slice, which is what makes `truncated` meaningful rather than decorative.
+ */
+interface ColumnFacets {
+    columnId: string;
+    /** Rows considered (after the active search, if any). */
+    totalRows: number;
+    /** Rows whose cell is non-empty. */
+    filled: number;
+    /** Rows whose cell is null or whitespace-only — a real filter target. */
+    blank: number;
+    /** Distinct non-empty values across EVERY row, not just `values`. */
+    distinctCount: number;
+    /** Longest value; a caller refuses a picker on a column of long prose. */
+    maxLength: number;
+    /** Distinct values too long to offer as options. */
+    unlistable: number;
+    limit: number;
+    /** True when `values` does not carry every listable distinct value. */
+    truncated: boolean;
+    /** Top values by frequency, descending; ties broken by the value itself. */
+    values: ColumnFacetValue[];
+    /** Who counted. "source" is the database; "local" is the rows in the browser. */
+    answeredBy: "source" | "local";
+    /**
+     * True when the counts describe every row of the column. False means the
+     * reader is looking at a partial answer and the popover must say so.
+     */
+    complete: boolean;
+}
+/** A value longer than this is real data, not a pickable option. */
+declare const MAX_LISTABLE_FACET_LENGTH = 300;
+/**
+ * Compute a column's facets from rows already in memory.
+ *
+ * `rows` MUST be every row the facets are meant to describe — the caller
+ * decides that with `localFacetsAreComplete`. `complete` carries the caller's
+ * verdict through to the popover so a partial answer can never be printed as a
+ * whole one.
+ */
+declare function computeColumnFacets(args: {
+    columnId: string;
+    rows: readonly unknown[];
+    readValue: (row: unknown, columnId: string) => unknown;
+    limit?: number | undefined;
+    complete?: boolean | undefined;
+}): ColumnFacets;
+/**
+ * May facets be computed from these rows, or must the source be asked?
+ *
+ * The ONLY safe condition is holding every row the facets describe. `total` is
+ * the row count AFTER the active search, which is exactly what the loaded rows
+ * also reflect — so comparing counts is a true completeness test, not a guess.
+ * An unknown total is never treated as "small enough".
+ */
+declare function localFacetsAreComplete(loadedRowCount: number, total: number | undefined): boolean;
+/**
+ * The one sentence under the value list. Empty when the answer is whole and
+ * nothing needs saying — the popover never nags a reader whose counts are
+ * exact.
+ */
+declare function describeFacetSource(facets: ColumnFacets | null | undefined, noun?: string): string;
+/** The sentence shown while the source is being asked, and when it refuses. */
+declare const FACETS_LOADING_NOTICE = "Counting values\u2026";
+declare function describeFacetFailure(error: unknown): string;
+
+export { type ColumnFacetValue, type ColumnFacets, FACETS_LOADING_NOTICE, MAX_LISTABLE_FACET_LENGTH, computeColumnFacets, describeFacetFailure, describeFacetSource, localFacetsAreComplete };

package/dist/data-table/facets.js

@@ -0,0 +1,98 @@
+
+// src/data-table/facets.ts
+var MAX_LISTABLE_FACET_LENGTH = 300;
+var DEFAULT_FACET_LIMIT = 200;
+var MAX_FACET_LIMIT = 500;
+function facetText(raw) {
+  if (raw === null || raw === void 0) return "";
+  if (typeof raw === "object") {
+    try {
+      return JSON.stringify(raw);
+    } catch {
+      return String(raw);
+    }
+  }
+  return String(raw);
+}
+function computeColumnFacets(args) {
+  const { columnId, rows, readValue } = args;
+  const limit = Math.min(Math.max(args.limit ?? DEFAULT_FACET_LIMIT, 1), MAX_FACET_LIMIT);
+  const counts = /* @__PURE__ */ new Map();
+  const longValues = /* @__PURE__ */ new Set();
+  let blank = 0;
+  let maxLength = 0;
+  for (const row of rows) {
+    let raw;
+    try {
+      raw = readValue(row, columnId);
+    } catch {
+      raw = void 0;
+    }
+    const trimmed = facetText(raw).trim();
+    if (trimmed === "") {
+      blank += 1;
+      continue;
+    }
+    if (trimmed.length > maxLength) maxLength = trimmed.length;
+    if (trimmed.length > MAX_LISTABLE_FACET_LENGTH) {
+      longValues.add(trimmed);
+      continue;
+    }
+    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+  }
+  const values = [...counts.entries()].map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count || a.value.localeCompare(b.value)).slice(0, limit);
+  return {
+    columnId,
+    totalRows: rows.length,
+    filled: rows.length - blank,
+    blank,
+    distinctCount: counts.size + longValues.size,
+    maxLength,
+    unlistable: longValues.size,
+    limit,
+    truncated: counts.size > limit,
+    values,
+    answeredBy: "local",
+    complete: args.complete ?? true
+  };
+}
+function localFacetsAreComplete(loadedRowCount, total) {
+  if (total === void 0 || !Number.isFinite(total) || total < 0) return false;
+  return loadedRowCount >= total;
+}
+var NUMBERS = new Intl.NumberFormat("en-US");
+function n(value) {
+  try {
+    return NUMBERS.format(value);
+  } catch {
+    return String(value);
+  }
+}
+function describeFacetSource(facets, noun = "row") {
+  if (!facets) return "";
+  const plural = `${noun}s`;
+  if (!facets.complete) {
+    return `These counts cover the ${n(facets.totalRows)} ${plural} loaded here, not the whole table.`;
+  }
+  if (facets.truncated) {
+    return `Showing the ${n(facets.values.length)} most common of ${n(facets.distinctCount)} values.`;
+  }
+  if (facets.unlistable > 0) {
+    return `${n(facets.unlistable)} ${facets.unlistable === 1 ? "value is" : "values are"} too long to list. Match text instead to reach ${facets.unlistable === 1 ? "it" : "them"}.`;
+  }
+  return "";
+}
+var FACETS_LOADING_NOTICE = "Counting values\u2026";
+function describeFacetFailure(error) {
+  const detail = error instanceof Error ? error.message : String(error ?? "");
+  return detail ? `The values in this column could not be counted: ${detail} Match text instead.` : "The values in this column could not be counted. Match text instead.";
+}
+export {
+  FACETS_LOADING_NOTICE,
+  MAX_LISTABLE_FACET_LENGTH,
+  computeColumnFacets,
+  describeFacetFailure,
+  describeFacetSource,
+  localFacetsAreComplete
+};
+//# sourceMappingURL=facets.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/facets.ts"],"sourcesContent":["/**\n * @ai-matrx/design-system/data-table — COLUMN FACETS: the values a column\n * actually holds, and how many rows carry each one.\n *\n * A filter box that says \"Contains…\" asks the reader to already know what is in\n * the column. A checklist of the real values, each with its count, tells them —\n * and the values that surprise you (the one-off typo, the stray casing, the\n * blank nobody filled in) are exactly the ones a text box hides.\n *\n * THE TWO LAWS this module exists to keep:\n *\n * 1. **Counts are computed locally ONLY when the browser holds every row the\n *    counts describe.** `localFacetsAreComplete` is the test, and it compares\n *    the loaded row count against the total AFTER the active search, because\n *    that is the population the counts claim to describe. One page of rows\n *    would produce counts that look authoritative and are not. When the browser\n *    does not hold them all, the consumer's `source` answers from the database.\n *\n * 2. **A partial answer says so, in a sentence.** `describeFacetSource` writes\n *    the one line the popover shows. There is no silent fallback: if the\n *    database could not be asked, or answered only part of the truth, the\n *    reader is told before they act on the list.\n *\n * Pure: no React, no DOM, no network. Nothing here throws on any input.\n */\n\n/** One distinct value of a column and how many rows carry it. */\nexport interface ColumnFacetValue {\n  value: string;\n  count: number;\n}\n\n/**\n * What one column holds. `values` is the top slice by frequency; the counts\n * that describe the WHOLE column — `totalRows`, `filled`, `blank`,\n * `distinctCount` — are always about every row considered, never about the\n * slice, which is what makes `truncated` meaningful rather than decorative.\n */\nexport interface ColumnFacets {\n  columnId: string;\n  /** Rows considered (after the active search, if any). */\n  totalRows: number;\n  /** Rows whose cell is non-empty. */\n  filled: number;\n  /** Rows whose cell is null or whitespace-only — a real filter target. */\n  blank: number;\n  /** Distinct non-empty values across EVERY row, not just `values`. */\n  distinctCount: number;\n  /** Longest value; a caller refuses a picker on a column of long prose. */\n  maxLength: number;\n  /** Distinct values too long to offer as options. */\n  unlistable: number;\n  limit: number;\n  /** True when `values` does not carry every listable distinct value. */\n  truncated: boolean;\n  /** Top values by frequency, descending; ties broken by the value itself. */\n  values: ColumnFacetValue[];\n  /** Who counted. \"source\" is the database; \"local\" is the rows in the browser. */\n  answeredBy: \"source\" | \"local\";\n  /**\n   * True when the counts describe every row of the column. False means the\n   * reader is looking at a partial answer and the popover must say so.\n   */\n  complete: boolean;\n}\n\n/** A value longer than this is real data, not a pickable option. */\nexport const MAX_LISTABLE_FACET_LENGTH = 300;\n\nconst DEFAULT_FACET_LIMIT = 200;\nconst MAX_FACET_LIMIT = 500;\n\nfunction facetText(raw: unknown): string {\n  if (raw === null || raw === undefined) return \"\";\n  if (typeof raw === \"object\") {\n    try {\n      return JSON.stringify(raw);\n    } catch {\n      return String(raw);\n    }\n  }\n  return String(raw);\n}\n\n/**\n * Compute a column's facets from rows already in memory.\n *\n * `rows` MUST be every row the facets are meant to describe — the caller\n * decides that with `localFacetsAreComplete`. `complete` carries the caller's\n * verdict through to the popover so a partial answer can never be printed as a\n * whole one.\n */\nexport function computeColumnFacets(args: {\n  columnId: string;\n  rows: readonly unknown[];\n  readValue: (row: unknown, columnId: string) => unknown;\n  limit?: number | undefined;\n  complete?: boolean | undefined;\n}): ColumnFacets {\n  const { columnId, rows, readValue } = args;\n  const limit = Math.min(Math.max(args.limit ?? DEFAULT_FACET_LIMIT, 1), MAX_FACET_LIMIT);\n\n  const counts = new Map<string, number>();\n  const longValues = new Set<string>();\n  let blank = 0;\n  let maxLength = 0;\n\n  for (const row of rows) {\n    let raw: unknown;\n    try {\n      raw = readValue(row, columnId);\n    } catch {\n      raw = undefined;\n    }\n    const trimmed = facetText(raw).trim();\n    if (trimmed === \"\") {\n      blank += 1;\n      continue;\n    }\n    if (trimmed.length > maxLength) maxLength = trimmed.length;\n    if (trimmed.length > MAX_LISTABLE_FACET_LENGTH) {\n      longValues.add(trimmed);\n      continue;\n    }\n    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);\n  }\n\n  const values: ColumnFacetValue[] = [...counts.entries()]\n    .map(([value, count]) => ({ value, count }))\n    .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value))\n    .slice(0, limit);\n\n  return {\n    columnId,\n    totalRows: rows.length,\n    filled: rows.length - blank,\n    blank,\n    distinctCount: counts.size + longValues.size,\n    maxLength,\n    unlistable: longValues.size,\n    limit,\n    truncated: counts.size > limit,\n    values,\n    answeredBy: \"local\",\n    complete: args.complete ?? true,\n  };\n}\n\n/**\n * May facets be computed from these rows, or must the source be asked?\n *\n * The ONLY safe condition is holding every row the facets describe. `total` is\n * the row count AFTER the active search, which is exactly what the loaded rows\n * also reflect — so comparing counts is a true completeness test, not a guess.\n * An unknown total is never treated as \"small enough\".\n */\nexport function localFacetsAreComplete(\n  loadedRowCount: number,\n  total: number | undefined,\n): boolean {\n  if (total === undefined || !Number.isFinite(total) || total < 0) return false;\n  return loadedRowCount >= total;\n}\n\nconst NUMBERS = new Intl.NumberFormat(\"en-US\");\n\nfunction n(value: number): string {\n  try {\n    return NUMBERS.format(value);\n  } catch {\n    return String(value);\n  }\n}\n\n/**\n * The one sentence under the value list. Empty when the answer is whole and\n * nothing needs saying — the popover never nags a reader whose counts are\n * exact.\n */\nexport function describeFacetSource(\n  facets: ColumnFacets | null | undefined,\n  noun = \"row\",\n): string {\n  if (!facets) return \"\";\n  const plural = `${noun}s`;\n  if (!facets.complete) {\n    return `These counts cover the ${n(facets.totalRows)} ${plural} loaded here, not the whole table.`;\n  }\n  if (facets.truncated) {\n    return `Showing the ${n(facets.values.length)} most common of ${n(facets.distinctCount)} values.`;\n  }\n  if (facets.unlistable > 0) {\n    return `${n(facets.unlistable)} ${facets.unlistable === 1 ? \"value is\" : \"values are\"} too long to list. Match text instead to reach ${facets.unlistable === 1 ? \"it\" : \"them\"}.`;\n  }\n  return \"\";\n}\n\n/** The sentence shown while the source is being asked, and when it refuses. */\nexport const FACETS_LOADING_NOTICE = \"Counting values…\";\nexport function describeFacetFailure(error: unknown): string {\n  const detail = error instanceof Error ? error.message : String(error ?? \"\");\n  return detail\n    ? `The values in this column could not be counted: ${detail} Match text instead.`\n    : \"The values in this column could not be counted. Match text instead.\";\n}\n"],"mappings":"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","names":[]}