@ai-matrx/design-system 0.21.14 → 0.25.0

package/dist/data-table/validation.js

@@ -0,0 +1,209 @@
+
+// src/data-table/validation.ts
+var OK = { ok: true };
+var STORED_KEYS = [
+  "min",
+  "max",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "patternHint",
+  "allowedValues",
+  "unique"
+];
+function finiteNumber(raw) {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : void 0;
+  if (typeof raw === "string" && raw.trim() !== "") {
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : void 0;
+  }
+  return void 0;
+}
+function nonNegativeInteger(raw) {
+  const n = finiteNumber(raw);
+  if (n === void 0) return void 0;
+  const i = Math.trunc(n);
+  return i >= 0 ? i : void 0;
+}
+function parseValidationRules(raw) {
+  let source = raw;
+  if (typeof source === "string") {
+    const text = source.trim();
+    if (text === "") return {};
+    try {
+      source = JSON.parse(text);
+    } catch {
+      return {};
+    }
+  }
+  if (!source || typeof source !== "object" || Array.isArray(source)) return {};
+  const obj = source;
+  const out = {};
+  const min = finiteNumber(obj.min);
+  if (min !== void 0) out.min = min;
+  const max = finiteNumber(obj.max);
+  if (max !== void 0) out.max = max;
+  const minLength = nonNegativeInteger(obj.minLength);
+  if (minLength !== void 0) out.minLength = minLength;
+  const maxLength = nonNegativeInteger(obj.maxLength);
+  if (maxLength !== void 0) out.maxLength = maxLength;
+  if (typeof obj.pattern === "string" && obj.pattern.trim() !== "") {
+    out.pattern = obj.pattern;
+    if (typeof obj.patternHint === "string" && obj.patternHint.trim() !== "") {
+      out.patternHint = obj.patternHint.trim();
+    }
+  }
+  if (Array.isArray(obj.allowedValues)) {
+    const values = obj.allowedValues.filter(
+      (v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean"
+    ).map((v) => String(v).trim()).filter((v) => v !== "");
+    const seen = /* @__PURE__ */ new Set();
+    const unique = values.filter((v) => {
+      const key = v.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+    if (unique.length > 0) out.allowedValues = unique;
+  }
+  if (obj.unique === true) out.unique = true;
+  return out;
+}
+function hasValidationRules(rules) {
+  if (!rules) return false;
+  return STORED_KEYS.some((key) => rules[key] !== void 0);
+}
+function serializeValidationRules(rules) {
+  const out = {};
+  if (!rules) return out;
+  for (const key of STORED_KEYS) {
+    const value = rules[key];
+    if (value === void 0) continue;
+    if (key === "allowedValues" && (!Array.isArray(value) || value.length === 0)) continue;
+    if (key === "unique" && value !== true) continue;
+    if ((key === "pattern" || key === "patternHint") && String(value).trim() === "") continue;
+    out[key] = value;
+  }
+  if (out.patternHint !== void 0 && out.pattern === void 0) delete out.patternHint;
+  return out;
+}
+function describeValidationRules(rules) {
+  const out = [];
+  if (rules.min !== void 0 && rules.max !== void 0) {
+    out.push(`Between ${rules.min} and ${rules.max}`);
+  } else if (rules.min !== void 0) {
+    out.push(`At least ${rules.min}`);
+  } else if (rules.max !== void 0) {
+    out.push(`At most ${rules.max}`);
+  }
+  if (rules.minLength !== void 0 && rules.maxLength !== void 0) {
+    out.push(`${rules.minLength}\u2013${rules.maxLength} characters`);
+  } else if (rules.minLength !== void 0) {
+    out.push(`At least ${rules.minLength} characters`);
+  } else if (rules.maxLength !== void 0) {
+    out.push(`At most ${rules.maxLength} characters`);
+  }
+  if (rules.pattern) {
+    out.push(rules.patternHint ? `Pattern ${rules.patternHint}` : `Matches ${rules.pattern}`);
+  }
+  if (rules.allowedValues?.length) {
+    out.push(`One of: ${rules.allowedValues.join(", ")}`);
+  }
+  if (rules.unique) out.push("Unique across rows");
+  return out;
+}
+var CHOICE_FORMATS = /* @__PURE__ */ new Set(["choice", "multi_choice"]);
+function isEmptyValue(value) {
+  if (value === null || value === void 0) return true;
+  if (typeof value === "string" && value.trim() === "") return true;
+  if (Array.isArray(value) && value.length === 0) return true;
+  return false;
+}
+function asText(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value.map((v) => String(v)).join(", ");
+  if (value !== null && typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return String(value);
+    }
+  }
+  return String(value);
+}
+function validateCellValue(args) {
+  const { rules, dataType, format, value, existingValues } = args;
+  if (!rules || !hasValidationRules(rules)) return OK;
+  if (isEmptyValue(value)) return OK;
+  const text = asText(value);
+  const numeric = finiteNumber(value);
+  if (numeric !== void 0) {
+    if (rules.min !== void 0 && numeric < rules.min) {
+      return { ok: false, reason: `Must be at least ${rules.min}` };
+    }
+    if (rules.max !== void 0 && numeric > rules.max) {
+      return { ok: false, reason: `Must be at most ${rules.max}` };
+    }
+  }
+  if (rules.minLength !== void 0 && text.length < rules.minLength) {
+    return {
+      ok: false,
+      reason: `Must be at least ${rules.minLength} character${rules.minLength === 1 ? "" : "s"} (this is ${text.length})`
+    };
+  }
+  if (rules.maxLength !== void 0 && text.length > rules.maxLength) {
+    return {
+      ok: false,
+      reason: `Must be at most ${rules.maxLength} character${rules.maxLength === 1 ? "" : "s"} (this is ${text.length})`
+    };
+  }
+  if (rules.pattern) {
+    let re = null;
+    try {
+      re = new RegExp(rules.pattern);
+    } catch {
+      re = null;
+    }
+    if (re && !re.test(text)) {
+      return {
+        ok: false,
+        reason: rules.patternHint ? `Must match the pattern ${rules.patternHint}` : `Must match the pattern ${rules.pattern}`
+      };
+    }
+  }
+  const isChoiceColumn = format ? CHOICE_FORMATS.has(format.id) : false;
+  if (rules.allowedValues?.length && !isChoiceColumn) {
+    const target = text.trim();
+    const hit = rules.allowedValues.some(
+      (v) => v === target || v.toLowerCase() === target.toLowerCase()
+    );
+    if (!hit) {
+      return {
+        ok: false,
+        reason: `Must be one of: ${rules.allowedValues.join(", ")}`
+      };
+    }
+  }
+  if (rules.unique && existingValues && existingValues.length > 0) {
+    const target = text.trim().toLowerCase();
+    const clash = existingValues.some(
+      (other) => !isEmptyValue(other) && asText(other).trim().toLowerCase() === target
+    );
+    if (clash) {
+      return {
+        ok: false,
+        reason: `Must be unique \u2014 another row already has "${text}"`
+      };
+    }
+  }
+  void dataType;
+  return OK;
+}
+export {
+  describeValidationRules,
+  hasValidationRules,
+  parseValidationRules,
+  serializeValidationRules,
+  validateCellValue
+};
+//# sourceMappingURL=validation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/validation.ts"],"sourcesContent":["/**\n * Column validation rules for user data tables — THE one rule model.\n *\n * A rule lives on `workbench.udt_dataset_fields.validation_rules` (jsonb) and\n * answers one question: may this value be written into this column? The\n * champions are Excel's data validation (a rule per column; an invalid entry is\n * refused WITH the reason) and Airtable (type-level only). We take Excel's\n * posture: the reason is the product.\n *\n * THREE LAWS this module exists to keep:\n *\n * 1. **`required` is NOT stored here.** The column already declares it as\n *    `is_required`, and a second copy is a second truth. `ValidationRules.required`\n *    is a read-only MIRROR for callers that want one object to reason about —\n *    `parseValidationRules` never invents it and the editor never writes it.\n *\n * 2. **A rule judges a value the user MEANT to write; it never judges what is\n *    already stored.** Existing values that violate a rule are legal, are never\n *    rewritten, and render in the SAME amber the format system already uses for\n *    a mismatch (`<FormattedFieldValue validationRules>`). Declaring a rule is\n *    how a user FINDS the stray values in their data, exactly as declaring a\n *    choice column's options is.\n *\n * 3. **An empty value is never a rule violation.** Emptiness is `is_required`'s\n *    question, asked once, by the callers that own the whole row. A `min: 0`\n *    rule that refused an empty cell would make every optional number column\n *    mandatory by accident.\n *\n * `unique` is the one rule this module cannot answer alone: it is a statement\n * about the OTHER rows, so the caller passes `existingValues` (the loaded rows'\n * values for that column) when it holds them. Without them the rule is skipped\n * rather than guessed — and it is deliberately NOT enforced by the database\n * trigger, because a cross-row check inside a per-row BEFORE trigger is the\n * wrong shape (it cannot see concurrent inserts and it walks the table on every\n * write). See `migrations/udt_validation_rules_strict_enforcement.sql`.\n *\n * Moved here from the app (`@ai-matrx/design-system/data-table/validation`) so\n * every table in the product enforces and explains validation the same way.\n */\n\nimport type { FieldFormatConfig } from \"../field-formats/types\";\n\nexport type ValidationRules = {\n  /**\n   * MIRROR of the column's `is_required`. Never stored in `validation_rules`,\n   * never written by the editor — present so a caller can carry one object.\n   */\n  required?: boolean;\n  /** Smallest number accepted. Number-ish columns only. */\n  min?: number;\n  /** Largest number accepted. Number-ish columns only. */\n  max?: number;\n  /** Fewest characters accepted. Text-ish columns only. */\n  minLength?: number;\n  /** Most characters accepted. Text-ish columns only. */\n  maxLength?: number;\n  /**\n   * A regular expression the value must match. Written in the dialect BOTH\n   * JavaScript and Postgres understand, and **anchored by the author** — an\n   * unanchored `\\d{3}` matches \"abc123def\" in both engines, which is almost\n   * never what a person drawing a rule means.\n   */\n  pattern?: string;\n  /** Plain-English shape shown when `pattern` refuses, e.g. `###-####`. */\n  patternHint?: string;\n  /**\n   * The exact values accepted. Only for a column that is NOT a choice column —\n   * a choice column already carries its options in its format, and a second\n   * list would be a second vocabulary for the same column.\n   */\n  allowedValues?: string[];\n  /** No two rows may carry the same value. Checked by the caller, never by the trigger. */\n  unique?: boolean;\n};\n\nexport type ValidationOk = { ok: true };\nexport type ValidationFailure = { ok: false; reason: string };\nexport type ValidationResult = ValidationOk | ValidationFailure;\n\nconst OK: ValidationOk = { ok: true };\n\n/** Keys the editor may write. `required` is deliberately absent — law 1. */\nconst STORED_KEYS = [\n  \"min\",\n  \"max\",\n  \"minLength\",\n  \"maxLength\",\n  \"pattern\",\n  \"patternHint\",\n  \"allowedValues\",\n  \"unique\",\n] as const;\n\nfunction finiteNumber(raw: unknown): number | undefined {\n  if (typeof raw === \"number\") return Number.isFinite(raw) ? raw : undefined;\n  if (typeof raw === \"string\" && raw.trim() !== \"\") {\n    const n = Number(raw);\n    return Number.isFinite(n) ? n : undefined;\n  }\n  return undefined;\n}\n\nfunction nonNegativeInteger(raw: unknown): number | undefined {\n  const n = finiteNumber(raw);\n  if (n === undefined) return undefined;\n  const i = Math.trunc(n);\n  return i >= 0 ? i : undefined;\n}\n\n/**\n * Read whatever is stored on the column into the rule model. TOLERANT by\n * design: this reads a jsonb column that predates the feature, that an agent or\n * an import may have written, and that a future version may extend. Anything it\n * cannot understand is dropped, never thrown on — a column with a garbled rule\n * must still be editable.\n */\nexport function parseValidationRules(raw: unknown): ValidationRules {\n  let source: unknown = raw;\n  if (typeof source === \"string\") {\n    const text = source.trim();\n    if (text === \"\") return {};\n    try {\n      source = JSON.parse(text);\n    } catch {\n      return {};\n    }\n  }\n  if (!source || typeof source !== \"object\" || Array.isArray(source)) return {};\n  const obj = source as Record<string, unknown>;\n  const out: ValidationRules = {};\n\n  const min = finiteNumber(obj.min);\n  if (min !== undefined) out.min = min;\n  const max = finiteNumber(obj.max);\n  if (max !== undefined) out.max = max;\n\n  const minLength = nonNegativeInteger(obj.minLength);\n  if (minLength !== undefined) out.minLength = minLength;\n  const maxLength = nonNegativeInteger(obj.maxLength);\n  if (maxLength !== undefined) out.maxLength = maxLength;\n\n  if (typeof obj.pattern === \"string\" && obj.pattern.trim() !== \"\") {\n    out.pattern = obj.pattern;\n    if (typeof obj.patternHint === \"string\" && obj.patternHint.trim() !== \"\") {\n      out.patternHint = obj.patternHint.trim();\n    }\n  }\n\n  if (Array.isArray(obj.allowedValues)) {\n    const values = obj.allowedValues\n      .filter(\n        (v): v is string | number | boolean =>\n          typeof v === \"string\" || typeof v === \"number\" || typeof v === \"boolean\",\n      )\n      .map((v) => String(v).trim())\n      .filter((v) => v !== \"\");\n    // De-duplicate, keeping the author's order.\n    const seen = new Set<string>();\n    const unique = values.filter((v) => {\n      const key = v.toLowerCase();\n      if (seen.has(key)) return false;\n      seen.add(key);\n      return true;\n    });\n    if (unique.length > 0) out.allowedValues = unique;\n  }\n\n  if (obj.unique === true) out.unique = true;\n\n  return out;\n}\n\n/** True when the column actually constrains anything. */\nexport function hasValidationRules(rules: ValidationRules | null | undefined): boolean {\n  if (!rules) return false;\n  return STORED_KEYS.some((key) => rules[key] !== undefined);\n}\n\n/**\n * The object to STORE. Strips `required` (law 1) and every empty key, so a\n * column whose rules were all cleared stores `{}` rather than a husk of nulls\n * — which also matters because `update_user_table_config` COALESCEs the column,\n * so `{}` is the only way to clear it.\n */\nexport function serializeValidationRules(\n  rules: ValidationRules | null | undefined,\n): Record<string, unknown> {\n  const out: Record<string, unknown> = {};\n  if (!rules) return out;\n  for (const key of STORED_KEYS) {\n    const value = rules[key];\n    if (value === undefined) continue;\n    if (key === \"allowedValues\" && (!Array.isArray(value) || value.length === 0)) continue;\n    if (key === \"unique\" && value !== true) continue;\n    if ((key === \"pattern\" || key === \"patternHint\") && String(value).trim() === \"\") continue;\n    out[key] = value;\n  }\n  // A hint with no pattern says nothing; drop it rather than store a dangling half-rule.\n  if (out.patternHint !== undefined && out.pattern === undefined) delete out.patternHint;\n  return out;\n}\n\n/** Plain-English list of what a column requires — for tooltips and for agents. */\nexport function describeValidationRules(rules: ValidationRules): string[] {\n  const out: string[] = [];\n  if (rules.min !== undefined && rules.max !== undefined) {\n    out.push(`Between ${rules.min} and ${rules.max}`);\n  } else if (rules.min !== undefined) {\n    out.push(`At least ${rules.min}`);\n  } else if (rules.max !== undefined) {\n    out.push(`At most ${rules.max}`);\n  }\n  if (rules.minLength !== undefined && rules.maxLength !== undefined) {\n    out.push(`${rules.minLength}–${rules.maxLength} characters`);\n  } else if (rules.minLength !== undefined) {\n    out.push(`At least ${rules.minLength} characters`);\n  } else if (rules.maxLength !== undefined) {\n    out.push(`At most ${rules.maxLength} characters`);\n  }\n  if (rules.pattern) {\n    out.push(rules.patternHint ? `Pattern ${rules.patternHint}` : `Matches ${rules.pattern}`);\n  }\n  if (rules.allowedValues?.length) {\n    out.push(`One of: ${rules.allowedValues.join(\", \")}`);\n  }\n  if (rules.unique) out.push(\"Unique across rows\");\n  return out;\n}\n\nconst CHOICE_FORMATS = new Set([\"choice\", \"multi_choice\"]);\n\nfunction isEmptyValue(value: unknown): boolean {\n  if (value === null || value === undefined) return true;\n  if (typeof value === \"string\" && value.trim() === \"\") return true;\n  if (Array.isArray(value) && value.length === 0) return true;\n  return false;\n}\n\n/** The value as the user reads it — the basis for every text rule. */\nfunction asText(value: unknown): string {\n  if (typeof value === \"string\") return value;\n  if (Array.isArray(value)) return value.map((v) => String(v)).join(\", \");\n  if (value !== null && typeof value === \"object\") {\n    try {\n      return JSON.stringify(value);\n    } catch {\n      return String(value);\n    }\n  }\n  return String(value);\n}\n\nexport type ValidateCellArgs = {\n  rules: ValidationRules | null | undefined;\n  /** The column's storage type (`string` | `number` | `integer` | …). */\n  dataType: string;\n  /** The column's declared display format, when it has one. */\n  format?: FieldFormatConfig | null;\n  /** The value the user is trying to write, already type-normalized. */\n  value: unknown;\n  /**\n   * Every OTHER row's value for this column, when the caller holds them. Only\n   * `unique` reads this; omit it and `unique` is skipped rather than guessed.\n   */\n  existingValues?: unknown[];\n};\n\n/**\n * Judge one value against one column's rules.\n *\n * Returns the FIRST reason it fails, in the order a person would check them\n * (range, length, shape, membership, uniqueness) — a wall of five complaints\n * about one cell is not more helpful than the first one.\n */\nexport function validateCellValue(args: ValidateCellArgs): ValidationResult {\n  const { rules, dataType, format, value, existingValues } = args;\n  if (!rules || !hasValidationRules(rules)) return OK;\n\n  // Law 3 — emptiness belongs to `is_required`, not to a rule.\n  if (isEmptyValue(value)) return OK;\n\n  const text = asText(value);\n  const numeric = finiteNumber(value);\n\n  // ── range ───────────────────────────────────────────────────────────────\n  // Applied only when a number can honestly be read out of the value. A\n  // non-numeric value in a number column is a TYPE problem, already reported by\n  // the format layer and by strict mode; saying \"Must be at least 0\" about the\n  // word \"pending\" would be a second, worse answer to a question already asked.\n  if (numeric !== undefined) {\n    if (rules.min !== undefined && numeric < rules.min) {\n      return { ok: false, reason: `Must be at least ${rules.min}` };\n    }\n    if (rules.max !== undefined && numeric > rules.max) {\n      return { ok: false, reason: `Must be at most ${rules.max}` };\n    }\n  }\n\n  // ── length ──────────────────────────────────────────────────────────────\n  if (rules.minLength !== undefined && text.length < rules.minLength) {\n    return {\n      ok: false,\n      reason: `Must be at least ${rules.minLength} character${rules.minLength === 1 ? \"\" : \"s\"} (this is ${text.length})`,\n    };\n  }\n  if (rules.maxLength !== undefined && text.length > rules.maxLength) {\n    return {\n      ok: false,\n      reason: `Must be at most ${rules.maxLength} character${rules.maxLength === 1 ? \"\" : \"s\"} (this is ${text.length})`,\n    };\n  }\n\n  // ── shape ───────────────────────────────────────────────────────────────\n  if (rules.pattern) {\n    let re: RegExp | null = null;\n    try {\n      re = new RegExp(rules.pattern);\n    } catch {\n      // An unparseable pattern is the AUTHOR's defect, not this value's. It is\n      // reported where it is written (the editor refuses to save one); here it\n      // must never turn into a refusal the typist cannot act on.\n      re = null;\n    }\n    if (re && !re.test(text)) {\n      return {\n        ok: false,\n        reason: rules.patternHint\n          ? `Must match the pattern ${rules.patternHint}`\n          : `Must match the pattern ${rules.pattern}`,\n      };\n    }\n  }\n\n  // ── membership ──────────────────────────────────────────────────────────\n  // Skipped on a choice column by construction: its options are its format's\n  // job, they are offered in the picker, and an off-list value there is legal\n  // and amber by design. A second list here would contradict that.\n  const isChoiceColumn = format ? CHOICE_FORMATS.has(format.id) : false;\n  if (rules.allowedValues?.length && !isChoiceColumn) {\n    const target = text.trim();\n    const hit = rules.allowedValues.some(\n      (v) => v === target || v.toLowerCase() === target.toLowerCase(),\n    );\n    if (!hit) {\n      return {\n        ok: false,\n        reason: `Must be one of: ${rules.allowedValues.join(\", \")}`,\n      };\n    }\n  }\n\n  // ── uniqueness ──────────────────────────────────────────────────────────\n  if (rules.unique && existingValues && existingValues.length > 0) {\n    const target = text.trim().toLowerCase();\n    const clash = existingValues.some(\n      (other) => !isEmptyValue(other) && asText(other).trim().toLowerCase() === target,\n    );\n    if (clash) {\n      return {\n        ok: false,\n        reason: `Must be unique — another row already has \"${text}\"`,\n      };\n    }\n  }\n\n  // `dataType` is not read by any rule today: every rule above is answered by\n  // the VALUE, and the storage type is already enforced by strict mode and by\n  // the format layer. It stays in the signature because it is the one fact a\n  // future rule (a date range, say) cannot be written without, and adding it\n  // later would change every callsite.\n  void dataType;\n\n  return OK;\n}\n"],"mappings":";;AA+EA,IAAM,KAAmB,EAAE,IAAI,KAAK;AAGpC,IAAM,cAAc;AAAA,EAClB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,SAAS,aAAa,KAAkC;AACtD,MAAI,OAAO,QAAQ,SAAU,QAAO,OAAO,SAAS,GAAG,IAAI,MAAM;AACjE,MAAI,OAAO,QAAQ,YAAY,IAAI,KAAK,MAAM,IAAI;AAChD,UAAM,IAAI,OAAO,GAAG;AACpB,WAAO,OAAO,SAAS,CAAC,IAAI,IAAI;AAAA,EAClC;AACA,SAAO;AACT;AAEA,SAAS,mBAAmB,KAAkC;AAC5D,QAAM,IAAI,aAAa,GAAG;AAC1B,MAAI,MAAM,OAAW,QAAO;AAC5B,QAAM,IAAI,KAAK,MAAM,CAAC;AACtB,SAAO,KAAK,IAAI,IAAI;AACtB;AASO,SAAS,qBAAqB,KAA+B;AAClE,MAAI,SAAkB;AACtB,MAAI,OAAO,WAAW,UAAU;AAC9B,UAAM,OAAO,OAAO,KAAK;AACzB,QAAI,SAAS,GAAI,QAAO,CAAC;AACzB,QAAI;AACF,eAAS,KAAK,MAAM,IAAI;AAAA,IAC1B,QAAQ;AACN,aAAO,CAAC;AAAA,IACV;AAAA,EACF;AACA,MAAI,CAAC,UAAU,OAAO,WAAW,YAAY,MAAM,QAAQ,MAAM,EAAG,QAAO,CAAC;AAC5E,QAAM,MAAM;AACZ,QAAM,MAAuB,CAAC;AAE9B,QAAM,MAAM,aAAa,IAAI,GAAG;AAChC,MAAI,QAAQ,OAAW,KAAI,MAAM;AACjC,QAAM,MAAM,aAAa,IAAI,GAAG;AAChC,MAAI,QAAQ,OAAW,KAAI,MAAM;AAEjC,QAAM,YAAY,mBAAmB,IAAI,SAAS;AAClD,MAAI,cAAc,OAAW,KAAI,YAAY;AAC7C,QAAM,YAAY,mBAAmB,IAAI,SAAS;AAClD,MAAI,cAAc,OAAW,KAAI,YAAY;AAE7C,MAAI,OAAO,IAAI,YAAY,YAAY,IAAI,QAAQ,KAAK,MAAM,IAAI;AAChE,QAAI,UAAU,IAAI;AAClB,QAAI,OAAO,IAAI,gBAAgB,YAAY,IAAI,YAAY,KAAK,MAAM,IAAI;AACxE,UAAI,cAAc,IAAI,YAAY,KAAK;AAAA,IACzC;AAAA,EACF;AAEA,MAAI,MAAM,QAAQ,IAAI,aAAa,GAAG;AACpC,UAAM,SAAS,IAAI,cAChB;AAAA,MACC,CAAC,MACC,OAAO,MAAM,YAAY,OAAO,MAAM,YAAY,OAAO,MAAM;AAAA,IACnE,EACC,IAAI,CAAC,MAAM,OAAO,CAAC,EAAE,KAAK,CAAC,EAC3B,OAAO,CAAC,MAAM,MAAM,EAAE;AAEzB,UAAM,OAAO,oBAAI,IAAY;AAC7B,UAAM,SAAS,OAAO,OAAO,CAAC,MAAM;AAClC,YAAM,MAAM,EAAE,YAAY;AAC1B,UAAI,KAAK,IAAI,GAAG,EAAG,QAAO;AAC1B,WAAK,IAAI,GAAG;AACZ,aAAO;AAAA,IACT,CAAC;AACD,QAAI,OAAO,SAAS,EAAG,KAAI,gBAAgB;AAAA,EAC7C;AAEA,MAAI,IAAI,WAAW,KAAM,KAAI,SAAS;AAEtC,SAAO;AACT;AAGO,SAAS,mBAAmB,OAAoD;AACrF,MAAI,CAAC,MAAO,QAAO;AACnB,SAAO,YAAY,KAAK,CAAC,QAAQ,MAAM,GAAG,MAAM,MAAS;AAC3D;AAQO,SAAS,yBACd,OACyB;AACzB,QAAM,MAA+B,CAAC;AACtC,MAAI,CAAC,MAAO,QAAO;AACnB,aAAW,OAAO,aAAa;AAC7B,UAAM,QAAQ,MAAM,GAAG;AACvB,QAAI,UAAU,OAAW;AACzB,QAAI,QAAQ,oBAAoB,CAAC,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,GAAI;AAC9E,QAAI,QAAQ,YAAY,UAAU,KAAM;AACxC,SAAK,QAAQ,aAAa,QAAQ,kBAAkB,OAAO,KAAK,EAAE,KAAK,MAAM,GAAI;AACjF,QAAI,GAAG,IAAI;AAAA,EACb;AAEA,MAAI,IAAI,gBAAgB,UAAa,IAAI,YAAY,OAAW,QAAO,IAAI;AAC3E,SAAO;AACT;AAGO,SAAS,wBAAwB,OAAkC;AACxE,QAAM,MAAgB,CAAC;AACvB,MAAI,MAAM,QAAQ,UAAa,MAAM,QAAQ,QAAW;AACtD,QAAI,KAAK,WAAW,MAAM,GAAG,QAAQ,MAAM,GAAG,EAAE;AAAA,EAClD,WAAW,MAAM,QAAQ,QAAW;AAClC,QAAI,KAAK,YAAY,MAAM,GAAG,EAAE;AAAA,EAClC,WAAW,MAAM,QAAQ,QAAW;AAClC,QAAI,KAAK,WAAW,MAAM,GAAG,EAAE;AAAA,EACjC;AACA,MAAI,MAAM,cAAc,UAAa,MAAM,cAAc,QAAW;AAClE,QAAI,KAAK,GAAG,MAAM,SAAS,SAAI,MAAM,SAAS,aAAa;AAAA,EAC7D,WAAW,MAAM,cAAc,QAAW;AACxC,QAAI,KAAK,YAAY,MAAM,SAAS,aAAa;AAAA,EACnD,WAAW,MAAM,cAAc,QAAW;AACxC,QAAI,KAAK,WAAW,MAAM,SAAS,aAAa;AAAA,EAClD;AACA,MAAI,MAAM,SAAS;AACjB,QAAI,KAAK,MAAM,cAAc,WAAW,MAAM,WAAW,KAAK,WAAW,MAAM,OAAO,EAAE;AAAA,EAC1F;AACA,MAAI,MAAM,eAAe,QAAQ;AAC/B,QAAI,KAAK,WAAW,MAAM,cAAc,KAAK,IAAI,CAAC,EAAE;AAAA,EACtD;AACA,MAAI,MAAM,OAAQ,KAAI,KAAK,oBAAoB;AAC/C,SAAO;AACT;AAEA,IAAM,iBAAiB,oBAAI,IAAI,CAAC,UAAU,cAAc,CAAC;AAEzD,SAAS,aAAa,OAAyB;AAC7C,MAAI,UAAU,QAAQ,UAAU,OAAW,QAAO;AAClD,MAAI,OAAO,UAAU,YAAY,MAAM,KAAK,MAAM,GAAI,QAAO;AAC7D,MAAI,MAAM,QAAQ,KAAK,KAAK,MAAM,WAAW,EAAG,QAAO;AACvD,SAAO;AACT;AAGA,SAAS,OAAO,OAAwB;AACtC,MAAI,OAAO,UAAU,SAAU,QAAO;AACtC,MAAI,MAAM,QAAQ,KAAK,EAAG,QAAO,MAAM,IAAI,CAAC,MAAM,OAAO,CAAC,CAAC,EAAE,KAAK,IAAI;AACtE,MAAI,UAAU,QAAQ,OAAO,UAAU,UAAU;AAC/C,QAAI;AACF,aAAO,KAAK,UAAU,KAAK;AAAA,IAC7B,QAAQ;AACN,aAAO,OAAO,KAAK;AAAA,IACrB;AAAA,EACF;AACA,SAAO,OAAO,KAAK;AACrB;AAwBO,SAAS,kBAAkB,MAA0C;AAC1E,QAAM,EAAE,OAAO,UAAU,QAAQ,OAAO,eAAe,IAAI;AAC3D,MAAI,CAAC,SAAS,CAAC,mBAAmB,KAAK,EAAG,QAAO;AAGjD,MAAI,aAAa,KAAK,EAAG,QAAO;AAEhC,QAAM,OAAO,OAAO,KAAK;AACzB,QAAM,UAAU,aAAa,KAAK;AAOlC,MAAI,YAAY,QAAW;AACzB,QAAI,MAAM,QAAQ,UAAa,UAAU,MAAM,KAAK;AAClD,aAAO,EAAE,IAAI,OAAO,QAAQ,oBAAoB,MAAM,GAAG,GAAG;AAAA,IAC9D;AACA,QAAI,MAAM,QAAQ,UAAa,UAAU,MAAM,KAAK;AAClD,aAAO,EAAE,IAAI,OAAO,QAAQ,mBAAmB,MAAM,GAAG,GAAG;AAAA,IAC7D;AAAA,EACF;AAGA,MAAI,MAAM,cAAc,UAAa,KAAK,SAAS,MAAM,WAAW;AAClE,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,QAAQ,oBAAoB,MAAM,SAAS,aAAa,MAAM,cAAc,IAAI,KAAK,GAAG,aAAa,KAAK,MAAM;AAAA,IAClH;AAAA,EACF;AACA,MAAI,MAAM,cAAc,UAAa,KAAK,SAAS,MAAM,WAAW;AAClE,WAAO;AAAA,MACL,IAAI;AAAA,MACJ,QAAQ,mBAAmB,MAAM,SAAS,aAAa,MAAM,cAAc,IAAI,KAAK,GAAG,aAAa,KAAK,MAAM;AAAA,IACjH;AAAA,EACF;AAGA,MAAI,MAAM,SAAS;AACjB,QAAI,KAAoB;AACxB,QAAI;AACF,WAAK,IAAI,OAAO,MAAM,OAAO;AAAA,IAC/B,QAAQ;AAIN,WAAK;AAAA,IACP;AACA,QAAI,MAAM,CAAC,GAAG,KAAK,IAAI,GAAG;AACxB,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,QAAQ,MAAM,cACV,0BAA0B,MAAM,WAAW,KAC3C,0BAA0B,MAAM,OAAO;AAAA,MAC7C;AAAA,IACF;AAAA,EACF;AAMA,QAAM,iBAAiB,SAAS,eAAe,IAAI,OAAO,EAAE,IAAI;AAChE,MAAI,MAAM,eAAe,UAAU,CAAC,gBAAgB;AAClD,UAAM,SAAS,KAAK,KAAK;AACzB,UAAM,MAAM,MAAM,cAAc;AAAA,MAC9B,CAAC,MAAM,MAAM,UAAU,EAAE,YAAY,MAAM,OAAO,YAAY;AAAA,IAChE;AACA,QAAI,CAAC,KAAK;AACR,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,QAAQ,mBAAmB,MAAM,cAAc,KAAK,IAAI,CAAC;AAAA,MAC3D;AAAA,IACF;AAAA,EACF;AAGA,MAAI,MAAM,UAAU,kBAAkB,eAAe,SAAS,GAAG;AAC/D,UAAM,SAAS,KAAK,KAAK,EAAE,YAAY;AACvC,UAAM,QAAQ,eAAe;AAAA,MAC3B,CAAC,UAAU,CAAC,aAAa,KAAK,KAAK,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,MAAM;AAAA,IAC5E;AACA,QAAI,OAAO;AACT,aAAO;AAAA,QACL,IAAI;AAAA,QACJ,QAAQ,kDAA6C,IAAI;AAAA,MAC3D;AAAA,IACF;AAAA,EACF;AAOA,OAAK;AAEL,SAAO;AACT;","names":[]}

package/dist/data-table/virtual-window.cjs

@@ -0,0 +1,203 @@
+"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/virtual-window.ts
+var virtual_window_exports = {};
+__export(virtual_window_exports, {
+  DEFAULT_OVERSCAN: () => DEFAULT_OVERSCAN,
+  computeVariableWindow: () => computeVariableWindow,
+  computeWindow: () => computeWindow,
+  scrollOffsetForIndex: () => scrollOffsetForIndex
+});
+module.exports = __toCommonJS(virtual_window_exports);
+var DEFAULT_OVERSCAN = 6;
+function isNum(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function toCount(value) {
+  return isNum(value) && value > 0 ? Math.floor(value) : 0;
+}
+function toLength(value) {
+  return isNum(value) && value > 0 ? value : 0;
+}
+function toOverscan(value) {
+  if (!isNum(value)) return DEFAULT_OVERSCAN;
+  return value > 0 ? Math.floor(value) : 0;
+}
+function toPinned(value, count) {
+  if (!isNum(value) || value <= 0) return 0;
+  return Math.min(Math.floor(value), count);
+}
+function assemble(args) {
+  const { pinnedCount, start, end, padStart, body, total } = args;
+  let padEnd = total - (padStart + body);
+  if (!Number.isFinite(padEnd)) padEnd = 0;
+  const sum = padStart + body + padEnd;
+  if (sum !== total) padEnd = padEnd + (total - sum);
+  const pinned = [];
+  for (let i = 0; i < pinnedCount; i += 1) pinned.push(i);
+  return { start, end, padStart, padEnd, total, pinned };
+}
+function emptyWindow(pinnedCount) {
+  const pinned = [];
+  for (let i = 0; i < pinnedCount; i += 1) pinned.push(i);
+  return { start: pinnedCount, end: pinnedCount, padStart: 0, padEnd: 0, total: 0, pinned };
+}
+function band(firstVisible, lastVisible, scrollCount, overscan) {
+  let first = firstVisible;
+  if (first > scrollCount - 1) first = scrollCount - 1;
+  if (first < 0) first = 0;
+  let last = lastVisible;
+  if (last < first + 1) last = first + 1;
+  if (last > scrollCount) last = scrollCount;
+  const start = Math.max(0, first - overscan);
+  let end = Math.min(scrollCount, last + overscan);
+  if (end < start) end = start;
+  return { start, end };
+}
+function computeWindow(input) {
+  const count = toCount(input?.count);
+  const pinnedCount = toPinned(input?.pinnedStart, count);
+  if (count <= 0) return emptyWindow(0);
+  const itemSize = toLength(input?.itemSize);
+  const viewport = toLength(input?.viewport);
+  const overscan = toOverscan(input?.overscan);
+  const scrollCount = count - pinnedCount;
+  if (scrollCount <= 0) return emptyWindow(pinnedCount);
+  if (itemSize <= 0) {
+    return assemble({ pinnedCount, start: pinnedCount, end: count, padStart: 0, body: 0, total: 0 });
+  }
+  const total = scrollCount * itemSize;
+  const maxOffset = Math.max(0, total - viewport);
+  const offset = Math.min(toLength(input?.offset), maxOffset);
+  const { start: relStart, end: relEnd } = band(
+    Math.floor(offset / itemSize),
+    Math.ceil((offset + viewport) / itemSize),
+    scrollCount,
+    overscan
+  );
+  return assemble({
+    pinnedCount,
+    start: pinnedCount + relStart,
+    end: pinnedCount + relEnd,
+    padStart: relStart * itemSize,
+    body: (relEnd - relStart) * itemSize,
+    total
+  });
+}
+var PREFIX_CACHE = /* @__PURE__ */ new WeakMap();
+function prefixFor(sizeAt, count) {
+  let byCount = PREFIX_CACHE.get(sizeAt);
+  if (!byCount) {
+    byCount = /* @__PURE__ */ new Map();
+    PREFIX_CACHE.set(sizeAt, byCount);
+  }
+  const cached = byCount.get(count);
+  if (cached) return cached;
+  const prefix = new Float64Array(count + 1);
+  let running = 0;
+  for (let i = 0; i < count; i += 1) {
+    let size = 0;
+    try {
+      size = sizeAt(i);
+    } catch {
+      size = 0;
+    }
+    running += isNum(size) && size > 0 ? size : 0;
+    prefix[i + 1] = running;
+  }
+  byCount.set(count, prefix);
+  return prefix;
+}
+function at(prefix, index) {
+  return prefix[index] ?? 0;
+}
+function lastAtOrBefore(prefix, lo, hi, target) {
+  let a = lo;
+  let b = hi;
+  while (a < b) {
+    const mid = a + Math.ceil((b - a) / 2);
+    if (at(prefix, mid) <= target) a = mid;
+    else b = mid - 1;
+  }
+  return a;
+}
+function firstAtOrAfter(prefix, lo, hi, target) {
+  let a = lo;
+  let b = hi;
+  while (a < b) {
+    const mid = a + Math.floor((b - a) / 2);
+    if (at(prefix, mid) >= target) b = mid;
+    else a = mid + 1;
+  }
+  return a;
+}
+function computeVariableWindow(input) {
+  const count = toCount(input?.count);
+  const pinnedCount = toPinned(input?.pinnedStart, count);
+  if (count <= 0) return emptyWindow(0);
+  const sizeAt = typeof input?.sizeAt === "function" ? input.sizeAt : () => 0;
+  const viewport = toLength(input?.viewport);
+  const overscan = toOverscan(input?.overscan);
+  const scrollCount = count - pinnedCount;
+  if (scrollCount <= 0) return emptyWindow(pinnedCount);
+  const prefix = prefixFor(sizeAt, count);
+  const pinnedLength = at(prefix, pinnedCount);
+  const total = at(prefix, count) - pinnedLength;
+  if (total <= 0) {
+    return assemble({ pinnedCount, start: pinnedCount, end: count, padStart: 0, body: 0, total: total > 0 ? total : 0 });
+  }
+  const maxOffset = Math.max(0, total - viewport);
+  const offset = Math.min(toLength(input?.offset), maxOffset);
+  const firstVisible = lastAtOrBefore(prefix, pinnedCount, count, pinnedLength + offset) - pinnedCount;
+  const lastVisible = firstAtOrAfter(prefix, pinnedCount, count, pinnedLength + offset + viewport) - pinnedCount;
+  const { start: relStart, end: relEnd } = band(firstVisible, lastVisible, scrollCount, overscan);
+  const absStart = pinnedCount + relStart;
+  const absEnd = pinnedCount + relEnd;
+  return assemble({
+    pinnedCount,
+    start: absStart,
+    end: absEnd,
+    padStart: at(prefix, absStart) - pinnedLength,
+    body: at(prefix, absEnd) - at(prefix, absStart),
+    total
+  });
+}
+function scrollOffsetForIndex(input) {
+  const count = toCount(input?.count);
+  if (count <= 0) return null;
+  const pinnedCount = toPinned(input?.pinnedStart, count);
+  const itemSize = toLength(input?.itemSize);
+  const viewport = toLength(input?.viewport);
+  const scrollCount = count - pinnedCount;
+  if (scrollCount <= 0 || itemSize <= 0) return null;
+  const rawIndex = isNum(input?.index) ? Math.floor(input.index) : 0;
+  const index = Math.min(Math.max(rawIndex, 0), count - 1);
+  if (index < pinnedCount) return null;
+  const total = scrollCount * itemSize;
+  const maxOffset = Math.max(0, total - viewport);
+  const offset = Math.min(toLength(input?.offset), maxOffset);
+  const itemStart = (index - pinnedCount) * itemSize;
+  const itemEnd = itemStart + itemSize;
+  if (itemStart >= offset && itemEnd <= offset + viewport) return null;
+  const next = itemStart < offset ? itemStart : itemEnd - viewport;
+  const clamped = Math.min(Math.max(next, 0), maxOffset);
+  return clamped === offset ? null : clamped;
+}
+//# sourceMappingURL=virtual-window.cjs.map

package/dist/data-table/virtual-window.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/virtual-window.ts"],"sourcesContent":["/**\n * Row / column windowing math for the canonical data table.\n *\n * Pure arithmetic: no React, no DOM, no measurement. The table hands in what it\n * knows (how many items, how big they are, how much of them the viewport shows,\n * where the scroller is) and gets back the slice it should actually render plus\n * the two spacers that keep the scrollbar honest.\n *\n * THE INVARIANT this module exists to hold:\n *\n *     padStart + (end - start) * itemSize + padEnd === total\n *\n * exactly, for every input. A scrollbar whose thumb size disagrees with the\n * content it can reach is a lie on screen, so `padEnd` is computed as the\n * residual of `total` rather than as an independent multiplication, and the\n * sum is re-checked and corrected once against floating-point drift.\n *\n * PINNED ITEMS (frozen columns) live OUTSIDE the scrollable length. They are\n * always rendered, they are never counted in `padStart`, and the scrollable\n * `total` covers only the items after them. `offset` is therefore measured\n * inside the scrollable region: offset 0 shows item index `pinnedStart`.\n */\n\n/** Items rendered outside the viewport on each side when the caller says nothing. */\nexport const DEFAULT_OVERSCAN = 6;\n\nexport interface WindowInput {\n  /** Total item count. */\n  count: number;\n  /** Fixed item size in px (row height, or column width when windowing columns). */\n  itemSize: number;\n  /** Visible viewport length in px along the windowed axis. */\n  viewport: number;\n  /** Current scroll offset in px along that axis. */\n  offset: number;\n  /** Extra items rendered outside the viewport on each side. Default 6. */\n  overscan?: number;\n  /** Items pinned at the start that never leave the DOM (frozen columns). Default 0. */\n  pinnedStart?: number;\n}\n\nexport interface WindowResult {\n  /** First rendered index, inclusive. */\n  start: number;\n  /** Last rendered index, EXCLUSIVE. */\n  end: number;\n  /** Spacer length in px before `start` (excluding pinned items). */\n  padStart: number;\n  /** Spacer length in px after `end`. */\n  padEnd: number;\n  /** Total scrollable length in px. */\n  total: number;\n  /** Indexes pinned at the start that are always rendered, ascending. */\n  pinned: number[];\n}\n\nexport interface VariableWindowInput extends Omit<WindowInput, \"itemSize\"> {\n  /** Size in px of the item at `index`. Must be pure and stable for a given index. */\n  sizeAt: (index: number) => number;\n}\n\n/* ------------------------------------------------------------------ */\n/* clamping — nothing here throws, every hostile number is flattened   */\n/* ------------------------------------------------------------------ */\n\nfunction isNum(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value);\n}\n\n/** Whole, non-negative item count. NaN / Infinity / negatives collapse to 0. */\nfunction toCount(value: number): number {\n  return isNum(value) && value > 0 ? Math.floor(value) : 0;\n}\n\n/** Non-negative px length. NaN / Infinity / negatives collapse to 0. */\nfunction toLength(value: number): number {\n  return isNum(value) && value > 0 ? value : 0;\n}\n\nfunction toOverscan(value: number | undefined): number {\n  if (!isNum(value)) return DEFAULT_OVERSCAN;\n  return value > 0 ? Math.floor(value) : 0;\n}\n\nfunction toPinned(value: number | undefined, count: number): number {\n  if (!isNum(value) || value <= 0) return 0;\n  return Math.min(Math.floor(value), count);\n}\n\n/**\n * Assemble the result, deriving `padEnd` as the residual of `total` so the\n * invariant holds bit-for-bit, then correcting one rounding step if the sum\n * the caller will compute still drifts.\n */\nfunction assemble(args: {\n  pinnedCount: number;\n  start: number;\n  end: number;\n  padStart: number;\n  body: number;\n  total: number;\n}): WindowResult {\n  const { pinnedCount, start, end, padStart, body, total } = args;\n  let padEnd = total - (padStart + body);\n  if (!Number.isFinite(padEnd)) padEnd = 0;\n  const sum = padStart + body + padEnd;\n  if (sum !== total) padEnd = padEnd + (total - sum);\n  const pinned: number[] = [];\n  for (let i = 0; i < pinnedCount; i += 1) pinned.push(i);\n  return { start, end, padStart, padEnd, total, pinned };\n}\n\n/** A window that renders nothing but still names whatever is pinned. */\nfunction emptyWindow(pinnedCount: number): WindowResult {\n  const pinned: number[] = [];\n  for (let i = 0; i < pinnedCount; i += 1) pinned.push(i);\n  return { start: pinnedCount, end: pinnedCount, padStart: 0, padEnd: 0, total: 0, pinned };\n}\n\n/**\n * The visible band, in RELATIVE indexes inside the scrollable region, widened\n * by overscan and clamped by both ends. Shared by the fixed and variable paths\n * so the two agree exactly when sizes are constant.\n */\nfunction band(firstVisible: number, lastVisible: number, scrollCount: number, overscan: number): { start: number; end: number } {\n  let first = firstVisible;\n  if (first > scrollCount - 1) first = scrollCount - 1;\n  if (first < 0) first = 0;\n  let last = lastVisible;\n  if (last < first + 1) last = first + 1;\n  if (last > scrollCount) last = scrollCount;\n  const start = Math.max(0, first - overscan);\n  let end = Math.min(scrollCount, last + overscan);\n  if (end < start) end = start;\n  return { start, end };\n}\n\n/* ------------------------------------------------------------------ */\n/* fixed-size windowing                                                */\n/* ------------------------------------------------------------------ */\n\n/**\n * The slice to render for uniformly sized items.\n *\n * O(1). Never returns `start < 0`, `end > count`, or `end < start`.\n */\nexport function computeWindow(input: WindowInput): WindowResult {\n  const count = toCount(input?.count as number);\n  const pinnedCount = toPinned(input?.pinnedStart, count);\n  if (count <= 0) return emptyWindow(0);\n\n  const itemSize = toLength(input?.itemSize as number);\n  const viewport = toLength(input?.viewport as number);\n  const overscan = toOverscan(input?.overscan);\n  const scrollCount = count - pinnedCount;\n\n  if (scrollCount <= 0) return emptyWindow(pinnedCount);\n\n  if (itemSize <= 0) {\n    // Zero-height items: nothing to scroll, so render the whole scrollable run.\n    return assemble({ pinnedCount, start: pinnedCount, end: count, padStart: 0, body: 0, total: 0 });\n  }\n\n  const total = scrollCount * itemSize;\n  const maxOffset = Math.max(0, total - viewport);\n  const offset = Math.min(toLength(input?.offset as number), maxOffset);\n\n  const { start: relStart, end: relEnd } = band(\n    Math.floor(offset / itemSize),\n    Math.ceil((offset + viewport) / itemSize),\n    scrollCount,\n    overscan,\n  );\n\n  return assemble({\n    pinnedCount,\n    start: pinnedCount + relStart,\n    end: pinnedCount + relEnd,\n    padStart: relStart * itemSize,\n    body: (relEnd - relStart) * itemSize,\n    total,\n  });\n}\n\n/* ------------------------------------------------------------------ */\n/* variable-size windowing                                             */\n/* ------------------------------------------------------------------ */\n\n/**\n * Prefix sums keyed by the `sizeAt` identity and the item count, so repeated\n * calls during a scroll do NOT walk the list again. `sizeAt` must be pure:\n * a different measurement for the same index needs a new function identity.\n */\nconst PREFIX_CACHE = new WeakMap<(index: number) => number, Map<number, Float64Array>>();\n\nfunction prefixFor(sizeAt: (index: number) => number, count: number): Float64Array {\n  let byCount = PREFIX_CACHE.get(sizeAt);\n  if (!byCount) {\n    byCount = new Map<number, Float64Array>();\n    PREFIX_CACHE.set(sizeAt, byCount);\n  }\n  const cached = byCount.get(count);\n  if (cached) return cached;\n  const prefix = new Float64Array(count + 1);\n  let running = 0;\n  for (let i = 0; i < count; i += 1) {\n    let size = 0;\n    try {\n      size = sizeAt(i);\n    } catch {\n      size = 0;\n    }\n    running += isNum(size) && size > 0 ? size : 0;\n    prefix[i + 1] = running;\n  }\n  byCount.set(count, prefix);\n  return prefix;\n}\n\nfunction at(prefix: Float64Array, index: number): number {\n  return prefix[index] ?? 0;\n}\n\n/** Largest `i` in `[lo, hi]` whose prefix is <= `target`. */\nfunction lastAtOrBefore(prefix: Float64Array, lo: number, hi: number, target: number): number {\n  let a = lo;\n  let b = hi;\n  while (a < b) {\n    const mid = a + Math.ceil((b - a) / 2);\n    if (at(prefix, mid) <= target) a = mid;\n    else b = mid - 1;\n  }\n  return a;\n}\n\n/** Smallest `j` in `[lo, hi]` whose prefix is >= `target`. */\nfunction firstAtOrAfter(prefix: Float64Array, lo: number, hi: number, target: number): number {\n  let a = lo;\n  let b = hi;\n  while (a < b) {\n    const mid = a + Math.floor((b - a) / 2);\n    if (at(prefix, mid) >= target) b = mid;\n    else a = mid + 1;\n  }\n  return a;\n}\n\n/**\n * The slice to render for items whose size varies by index.\n *\n * Agrees with `computeWindow` exactly when `sizeAt` is constant. The prefix-sum\n * array is built once per `(sizeAt, count)` pair and then binary-searched, so a\n * scroll costs O(log count) per call after the first O(count) build.\n */\nexport function computeVariableWindow(input: VariableWindowInput): WindowResult {\n  const count = toCount(input?.count as number);\n  const pinnedCount = toPinned(input?.pinnedStart, count);\n  if (count <= 0) return emptyWindow(0);\n\n  const sizeAt = typeof input?.sizeAt === \"function\" ? input.sizeAt : () => 0;\n  const viewport = toLength(input?.viewport as number);\n  const overscan = toOverscan(input?.overscan);\n  const scrollCount = count - pinnedCount;\n\n  if (scrollCount <= 0) return emptyWindow(pinnedCount);\n\n  const prefix = prefixFor(sizeAt, count);\n  const pinnedLength = at(prefix, pinnedCount);\n  const total = at(prefix, count) - pinnedLength;\n\n  if (total <= 0) {\n    return assemble({ pinnedCount, start: pinnedCount, end: count, padStart: 0, body: 0, total: total > 0 ? total : 0 });\n  }\n\n  const maxOffset = Math.max(0, total - viewport);\n  const offset = Math.min(toLength(input?.offset as number), maxOffset);\n\n  const firstVisible = lastAtOrBefore(prefix, pinnedCount, count, pinnedLength + offset) - pinnedCount;\n  const lastVisible = firstAtOrAfter(prefix, pinnedCount, count, pinnedLength + offset + viewport) - pinnedCount;\n\n  const { start: relStart, end: relEnd } = band(firstVisible, lastVisible, scrollCount, overscan);\n  const absStart = pinnedCount + relStart;\n  const absEnd = pinnedCount + relEnd;\n\n  return assemble({\n    pinnedCount,\n    start: absStart,\n    end: absEnd,\n    padStart: at(prefix, absStart) - pinnedLength,\n    body: at(prefix, absEnd) - at(prefix, absStart),\n    total,\n  });\n}\n\n/* ------------------------------------------------------------------ */\n/* scroll-to-index                                                     */\n/* ------------------------------------------------------------------ */\n\nexport interface ScrollToIndexInput extends WindowInput {\n  /** The item to bring into view. */\n  index: number;\n}\n\n/**\n * The scroll offset that brings `index` fully into view, or `null` when it is\n * already fully visible (pinned items are always visible, so they return\n * `null` too). Moves the minimum distance: up to the item's own start when it\n * sits above the viewport, down until its end meets the viewport end when it\n * sits below.\n */\nexport function scrollOffsetForIndex(input: ScrollToIndexInput): number | null {\n  const count = toCount(input?.count as number);\n  if (count <= 0) return null;\n  const pinnedCount = toPinned(input?.pinnedStart, count);\n  const itemSize = toLength(input?.itemSize as number);\n  const viewport = toLength(input?.viewport as number);\n  const scrollCount = count - pinnedCount;\n  if (scrollCount <= 0 || itemSize <= 0) return null;\n\n  const rawIndex = isNum(input?.index) ? Math.floor(input.index) : 0;\n  const index = Math.min(Math.max(rawIndex, 0), count - 1);\n  if (index < pinnedCount) return null; // pinned: never leaves the DOM\n\n  const total = scrollCount * itemSize;\n  const maxOffset = Math.max(0, total - viewport);\n  const offset = Math.min(toLength(input?.offset as number), maxOffset);\n\n  const itemStart = (index - pinnedCount) * itemSize;\n  const itemEnd = itemStart + itemSize;\n\n  if (itemStart >= offset && itemEnd <= offset + viewport) return null;\n\n  const next = itemStart < offset ? itemStart : itemEnd - viewport;\n  const clamped = Math.min(Math.max(next, 0), maxOffset);\n  return clamped === offset ? null : clamped;\n}\n"],"mappings":"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","names":[]}

package/dist/data-table/virtual-window.d.cts

@@ -0,0 +1,84 @@
+/**
+ * Row / column windowing math for the canonical data table.
+ *
+ * Pure arithmetic: no React, no DOM, no measurement. The table hands in what it
+ * knows (how many items, how big they are, how much of them the viewport shows,
+ * where the scroller is) and gets back the slice it should actually render plus
+ * the two spacers that keep the scrollbar honest.
+ *
+ * THE INVARIANT this module exists to hold:
+ *
+ *     padStart + (end - start) * itemSize + padEnd === total
+ *
+ * exactly, for every input. A scrollbar whose thumb size disagrees with the
+ * content it can reach is a lie on screen, so `padEnd` is computed as the
+ * residual of `total` rather than as an independent multiplication, and the
+ * sum is re-checked and corrected once against floating-point drift.
+ *
+ * PINNED ITEMS (frozen columns) live OUTSIDE the scrollable length. They are
+ * always rendered, they are never counted in `padStart`, and the scrollable
+ * `total` covers only the items after them. `offset` is therefore measured
+ * inside the scrollable region: offset 0 shows item index `pinnedStart`.
+ */
+/** Items rendered outside the viewport on each side when the caller says nothing. */
+declare const DEFAULT_OVERSCAN = 6;
+interface WindowInput {
+    /** Total item count. */
+    count: number;
+    /** Fixed item size in px (row height, or column width when windowing columns). */
+    itemSize: number;
+    /** Visible viewport length in px along the windowed axis. */
+    viewport: number;
+    /** Current scroll offset in px along that axis. */
+    offset: number;
+    /** Extra items rendered outside the viewport on each side. Default 6. */
+    overscan?: number;
+    /** Items pinned at the start that never leave the DOM (frozen columns). Default 0. */
+    pinnedStart?: number;
+}
+interface WindowResult {
+    /** First rendered index, inclusive. */
+    start: number;
+    /** Last rendered index, EXCLUSIVE. */
+    end: number;
+    /** Spacer length in px before `start` (excluding pinned items). */
+    padStart: number;
+    /** Spacer length in px after `end`. */
+    padEnd: number;
+    /** Total scrollable length in px. */
+    total: number;
+    /** Indexes pinned at the start that are always rendered, ascending. */
+    pinned: number[];
+}
+interface VariableWindowInput extends Omit<WindowInput, "itemSize"> {
+    /** Size in px of the item at `index`. Must be pure and stable for a given index. */
+    sizeAt: (index: number) => number;
+}
+/**
+ * The slice to render for uniformly sized items.
+ *
+ * O(1). Never returns `start < 0`, `end > count`, or `end < start`.
+ */
+declare function computeWindow(input: WindowInput): WindowResult;
+/**
+ * The slice to render for items whose size varies by index.
+ *
+ * Agrees with `computeWindow` exactly when `sizeAt` is constant. The prefix-sum
+ * array is built once per `(sizeAt, count)` pair and then binary-searched, so a
+ * scroll costs O(log count) per call after the first O(count) build.
+ */
+declare function computeVariableWindow(input: VariableWindowInput): WindowResult;
+interface ScrollToIndexInput extends WindowInput {
+    /** The item to bring into view. */
+    index: number;
+}
+/**
+ * The scroll offset that brings `index` fully into view, or `null` when it is
+ * already fully visible (pinned items are always visible, so they return
+ * `null` too). Moves the minimum distance: up to the item's own start when it
+ * sits above the viewport, down until its end meets the viewport end when it
+ * sits below.
+ */
+declare function scrollOffsetForIndex(input: ScrollToIndexInput): number | null;
+
+export { DEFAULT_OVERSCAN, type ScrollToIndexInput, type VariableWindowInput, type WindowInput, type WindowResult, computeVariableWindow, computeWindow, scrollOffsetForIndex };

package/dist/data-table/virtual-window.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Row / column windowing math for the canonical data table.
+ *
+ * Pure arithmetic: no React, no DOM, no measurement. The table hands in what it
+ * knows (how many items, how big they are, how much of them the viewport shows,
+ * where the scroller is) and gets back the slice it should actually render plus
+ * the two spacers that keep the scrollbar honest.
+ *
+ * THE INVARIANT this module exists to hold:
+ *
+ *     padStart + (end - start) * itemSize + padEnd === total
+ *
+ * exactly, for every input. A scrollbar whose thumb size disagrees with the
+ * content it can reach is a lie on screen, so `padEnd` is computed as the
+ * residual of `total` rather than as an independent multiplication, and the
+ * sum is re-checked and corrected once against floating-point drift.
+ *
+ * PINNED ITEMS (frozen columns) live OUTSIDE the scrollable length. They are
+ * always rendered, they are never counted in `padStart`, and the scrollable
+ * `total` covers only the items after them. `offset` is therefore measured
+ * inside the scrollable region: offset 0 shows item index `pinnedStart`.
+ */
+/** Items rendered outside the viewport on each side when the caller says nothing. */
+declare const DEFAULT_OVERSCAN = 6;
+interface WindowInput {
+    /** Total item count. */
+    count: number;
+    /** Fixed item size in px (row height, or column width when windowing columns). */
+    itemSize: number;
+    /** Visible viewport length in px along the windowed axis. */
+    viewport: number;
+    /** Current scroll offset in px along that axis. */
+    offset: number;
+    /** Extra items rendered outside the viewport on each side. Default 6. */
+    overscan?: number;
+    /** Items pinned at the start that never leave the DOM (frozen columns). Default 0. */
+    pinnedStart?: number;
+}
+interface WindowResult {
+    /** First rendered index, inclusive. */
+    start: number;
+    /** Last rendered index, EXCLUSIVE. */
+    end: number;
+    /** Spacer length in px before `start` (excluding pinned items). */
+    padStart: number;
+    /** Spacer length in px after `end`. */
+    padEnd: number;
+    /** Total scrollable length in px. */
+    total: number;
+    /** Indexes pinned at the start that are always rendered, ascending. */
+    pinned: number[];
+}
+interface VariableWindowInput extends Omit<WindowInput, "itemSize"> {
+    /** Size in px of the item at `index`. Must be pure and stable for a given index. */
+    sizeAt: (index: number) => number;
+}
+/**
+ * The slice to render for uniformly sized items.
+ *
+ * O(1). Never returns `start < 0`, `end > count`, or `end < start`.
+ */
+declare function computeWindow(input: WindowInput): WindowResult;
+/**
+ * The slice to render for items whose size varies by index.
+ *
+ * Agrees with `computeWindow` exactly when `sizeAt` is constant. The prefix-sum
+ * array is built once per `(sizeAt, count)` pair and then binary-searched, so a
+ * scroll costs O(log count) per call after the first O(count) build.
+ */
+declare function computeVariableWindow(input: VariableWindowInput): WindowResult;
+interface ScrollToIndexInput extends WindowInput {
+    /** The item to bring into view. */
+    index: number;
+}
+/**
+ * The scroll offset that brings `index` fully into view, or `null` when it is
+ * already fully visible (pinned items are always visible, so they return
+ * `null` too). Moves the minimum distance: up to the item's own start when it
+ * sits above the viewport, down until its end meets the viewport end when it
+ * sits below.
+ */
+declare function scrollOffsetForIndex(input: ScrollToIndexInput): number | null;
+
+export { DEFAULT_OVERSCAN, type ScrollToIndexInput, type VariableWindowInput, type WindowInput, type WindowResult, computeVariableWindow, computeWindow, scrollOffsetForIndex };