@ai-matrx/records-ui 0.107.5 → 0.108.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog — @ai-matrx/records-ui
 
+## 0.108.0
+### PAGE-BUNDLE-2: the grid's first page, asked before the grid exists
+
+NEW ENTRY `@ai-matrx/records-ui/first-page` (server-safe, no React): `firstGridPageRequest(client, tableId)` and the pure `firstGridPageArgs({ tableId, table, fields, shown })` build the EXACT `custom.read_records_page` arguments the table page's grid sends on open (the bar's default view with the person's look over it, the view's sort else the table's `default_sort`, page size 100). Null for a grouped, drilled, filtered, hand-ordered, Rule or non-grid view. A test renders the grid and holds the two byte-equal.
+
+**Consumer action:** none (additive). A server-rendered host seeds the first page by door name + these arguments.
+
 ## 0.107.5
 
 TYPEFORM-2: no keystroke is lost while the store works out a branching form's route. Keys typed after Enter are held and land in the next question (appended to a text answer, replayed as keys on a choice so a letter picks). Walk: type straight on after Enter.

package/dist/first-page.cjs

@@ -0,0 +1,487 @@
+"use client";
+"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/firstPage.ts
+var firstPage_exports = {};
+__export(firstPage_exports, {
+  TABLE_PAGE_SIZE: () => TABLE_PAGE_SIZE,
+  firstGridPageArgs: () => firstGridPageArgs,
+  firstGridPageRequest: () => firstGridPageRequest
+});
+module.exports = __toCommonJS(firstPage_exports);
+
+// src/parity.ts
+var import_records = require("@ai-matrx/records");
+var import_text_case = require("@ai-matrx/kit/text-case");
+var kernelId = (name) => import_records.KERNEL_TABLES.find((t) => t.name === name)?.id ?? "";
+var KERNEL_FILE_TABLE = kernelId("File");
+var KERNEL_PERSON_TABLE = kernelId("Person");
+var PARITY_MADE_OF = Object.fromEntries(
+  import_records.PARITY_FIELD_TYPES.map((p) => [p.parity_type, p.made_of])
+);
+var KERNEL = { file: KERNEL_FILE_TABLE, person: KERNEL_PERSON_TABLE };
+function editorKindFor(field) {
+  return (0, import_records.fieldKindFor)(field, KERNEL);
+}
+
+// src/gridLook.ts
+function defaultSortOf(table, fields) {
+  const raw = table?.default_sort ?? null;
+  const first = Array.isArray(raw) ? raw[0] : raw;
+  let name = null;
+  let direction = "asc";
+  if (typeof first === "string") {
+    const trimmed = first.trim();
+    if (trimmed === "") return null;
+    if (trimmed.startsWith("-")) {
+      name = trimmed.slice(1).trim();
+      direction = "desc";
+    } else {
+      const [head, tail] = trimmed.split(/\s+/);
+      name = head ?? null;
+      if (tail && tail.toLowerCase() === "desc") direction = "desc";
+    }
+  } else if (first && typeof first === "object") {
+    const entry = first;
+    const named = entry["field"] ?? entry["key"] ?? entry["id"];
+    name = typeof named === "string" ? named : null;
+    if (String(entry["direction"] ?? "").toLowerCase() === "desc") direction = "desc";
+  }
+  if (!name) return null;
+  const field = fields.find((f) => f.key === name) ?? fields.find((f) => f.id === name);
+  return field ? { id: field.key, direction } : null;
+}
+
+// src/gridPage.ts
+var import_records2 = require("@ai-matrx/records");
+var import_data_table = require("@ai-matrx/design-system/data-table");
+function holdsNumbers(field) {
+  const kind = String(editorKindFor(field));
+  if (kind === "number" || kind === "currency" || kind === "percent") return true;
+  return String((field.config ?? {})["system"] ?? "") === "autonumber";
+}
+function sortAsFor(field) {
+  const kind = String(editorKindFor(field));
+  if (holdsNumbers(field)) return "number";
+  if (kind === "datetime") return "date";
+  return "text";
+}
+function pageSortFor(fields, sort) {
+  if (!sort) return [];
+  const field = fields.find((f) => f.key === sort.id);
+  if (!field) return [];
+  return [{ field: field.key, direction: sort.direction === "desc" ? "desc" : "asc", as: sortAsFor(field) }];
+}
+
+// src/presentation.ts
+var import_data_table2 = require("@ai-matrx/design-system/data-table");
+var import_field_formats = require("@ai-matrx/design-system/field-formats");
+var import_records3 = require("@ai-matrx/records");
+var MIN_ROW_HEIGHT = 24;
+var MAX_ROW_HEIGHT = 96;
+var AGGREGATE_KINDS = [
+  "count",
+  "sum",
+  "average",
+  "min",
+  "max",
+  "empty",
+  "filled",
+  "unique",
+  "checked",
+  "unchecked",
+  "percentFilled"
+];
+var GROUP_ORDERS = [
+  "value-asc",
+  "value-desc",
+  "count-desc",
+  "first-seen"
+];
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function parseGridPresentation(raw) {
+  let value = raw;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed === "") return {};
+    try {
+      value = JSON.parse(trimmed);
+    } catch {
+      return {};
+    }
+  }
+  if (!isRecord(value)) return {};
+  const out = {};
+  const style = (0, import_data_table2.parseTableStyle)(value["style"]);
+  if (!(0, import_data_table2.tableStyleIsEmpty)(style)) out.style = style;
+  if (isRecord(value["formats"])) {
+    const formats = {};
+    for (const [key, cfg] of Object.entries(value["formats"])) {
+      if (!isRecord(cfg)) continue;
+      const id = cfg["id"];
+      if (typeof id !== "string") continue;
+      const options = cfg["options"];
+      formats[key] = isRecord(options) ? {
+        id,
+        options
+      } : { id };
+    }
+    if (Object.keys(formats).length > 0) out.formats = formats;
+  }
+  if (Array.isArray(value["frozen"])) {
+    const frozen = value["frozen"].filter((k) => typeof k === "string");
+    if (frozen.length > 0) out.frozen = frozen;
+  }
+  const grouping = parseGrouping(value["grouping"]);
+  if (grouping) out.grouping = grouping;
+  if (isRecord(value["widths"])) {
+    const widths = {};
+    for (const [key, raw2] of Object.entries(value["widths"])) {
+      if (typeof raw2 !== "number" || !Number.isFinite(raw2) || raw2 <= 0) continue;
+      widths[key] = Math.round(raw2);
+    }
+    if (Object.keys(widths).length > 0) out.widths = widths;
+  }
+  const rowHeight = value["rowHeight"];
+  if (typeof rowHeight === "number" && Number.isFinite(rowHeight) && rowHeight >= MIN_ROW_HEIGHT && rowHeight <= MAX_ROW_HEIGHT) {
+    out.rowHeight = Math.round(rowHeight);
+  }
+  if (Array.isArray(value["hiddenFields"])) {
+    const hiddenFields = value["hiddenFields"].filter((k) => typeof k === "string");
+    if (hiddenFields.length > 0) out.hiddenFields = hiddenFields;
+  }
+  if (Array.isArray(value["cardHidden"])) {
+    out.cardHidden = value["cardHidden"].filter((k) => typeof k === "string");
+  }
+  if (Array.isArray(value["columnOrder"])) {
+    const columnOrder = value["columnOrder"].filter((k) => typeof k === "string");
+    if (columnOrder.length > 0) out.columnOrder = columnOrder;
+  }
+  const gallerySize = value["gallerySize"];
+  if (gallerySize === "small" || gallerySize === "medium" || gallerySize === "large") {
+    out.gallerySize = gallerySize;
+  }
+  if (typeof value["wrap"] === "boolean") out.wrap = value["wrap"];
+  if (Array.isArray(value["wrapColumns"])) {
+    const wrapColumns = value["wrapColumns"].filter((k) => typeof k === "string");
+    if (wrapColumns.length > 0) out.wrapColumns = wrapColumns;
+  }
+  const fit = value["fit"];
+  if (fit === "auto" || fit === "fit" || fit === "scroll") out.fit = fit;
+  if (typeof value["freezeFirst"] === "boolean") out.freezeFirst = value["freezeFirst"];
+  const footer = value["footer"];
+  if (footer === "sticky" || footer === "inline") out.footer = footer;
+  if (isRecord(value["summaries"])) {
+    const summaries = {};
+    for (const [key, op] of Object.entries(value["summaries"])) {
+      if (typeof op === "string" && op.trim() !== "") summaries[key] = op;
+    }
+    if (Object.keys(summaries).length > 0) out.summaries = summaries;
+  }
+  return out;
+}
+function parseGrouping(raw) {
+  if (!isRecord(raw)) return void 0;
+  const field = raw["field"];
+  if (typeof field !== "string" || field.trim() === "") return void 0;
+  const out = { field };
+  if (isRecord(raw["aggregates"])) {
+    const aggregates = {};
+    for (const [key, spec] of Object.entries(raw["aggregates"])) {
+      if (!isRecord(spec)) continue;
+      const kind = spec["kind"];
+      if (typeof kind !== "string") continue;
+      if (!AGGREGATE_KINDS.includes(kind)) continue;
+      const label = spec["label"];
+      aggregates[key] = typeof label === "string" ? { kind, label } : { kind };
+    }
+    if (Object.keys(aggregates).length > 0) out.aggregates = aggregates;
+  }
+  const order = raw["order"];
+  if (typeof order === "string" && GROUP_ORDERS.includes(order)) {
+    out.order = order;
+  }
+  if (Array.isArray(raw["collapsed"])) {
+    const collapsed = raw["collapsed"].filter((k) => typeof k === "string");
+    if (collapsed.length > 0) out.collapsed = collapsed;
+  }
+  if (raw["showColumn"] === true) out.showColumn = true;
+  if (Array.isArray(raw["then"])) {
+    const then = [];
+    for (const level of raw["then"]) {
+      if (!isRecord(level)) continue;
+      const sub = level["field"];
+      if (typeof sub !== "string" || sub.trim() === "") continue;
+      const subOrder = level["order"];
+      const subGrain = level["grain"];
+      then.push({
+        field: sub,
+        ...typeof subOrder === "string" && GROUP_ORDERS.includes(subOrder) ? { order: subOrder } : {},
+        ...typeof subGrain === "string" && subGrain !== "" ? { grain: subGrain } : {}
+      });
+    }
+    if (then.length > 0) out.then = then.slice(0, 2);
+  }
+  const grain = raw["grain"];
+  if (typeof grain === "string" && grain !== "") out.grain = grain;
+  const across = raw["across"];
+  if (typeof across === "string" && across.trim() !== "") out.across = across;
+  if (Array.isArray(raw["show"])) {
+    const show = raw["show"].filter((k) => typeof k === "string" && k !== "");
+    if (show.length > 0) out.show = show;
+  }
+  if (Array.isArray(raw["trail"])) {
+    const trail = [];
+    for (const step of raw["trail"]) {
+      if (!isRecord(step) || typeof step["dim"] !== "string" || step["dim"] === "") continue;
+      const value = step["value"];
+      if (value !== null && typeof value !== "string") continue;
+      trail.push({ dim: step["dim"], value });
+    }
+    if (trail.length > 0) out.trail = trail;
+  }
+  return out;
+}
+
+// src/viewKeys.ts
+var STORE_KEEPS_TIMELINE = true;
+var ALL = ["grid", "kanban", "calendar", "gallery", ...STORE_KEEPS_TIMELINE ? ["timeline"] : [], "list"];
+var HIDES = ["grid", "gallery", "kanban", "calendar", ...STORE_KEEPS_TIMELINE ? ["timeline"] : [], "list"];
+var GRIDS = ["grid"];
+var VIEW_KEYS = [
+  { path: "layout", shape: "kind", layouts: ALL, writer: "caller" },
+  { path: "filters", shape: "filter", layouts: ALL, writer: "caller" },
+  { path: "where", shape: "rule", layouts: ALL, writer: "caller" },
+  { path: "group_field", shape: "field", layouts: ["kanban", ...STORE_KEEPS_TIMELINE ? ["timeline"] : []], writer: "caller" },
+  { path: "swimlane_field", shape: "field:lane", layouts: ["kanban"], writer: "caller" },
+  { path: "collapsed_columns", shape: "values", layouts: ["kanban"], writer: "caller" },
+  { path: "measure", shape: "field:number", layouts: ["kanban"], writer: "caller" },
+  { path: "date_field", shape: "field:date", layouts: ["calendar"], writer: "caller" },
+  ...STORE_KEEPS_TIMELINE ? [
+    { path: "start_field", shape: "field:date", layouts: ["timeline"], writer: "caller" },
+    { path: "end_field", shape: "field:date", layouts: ["calendar", "timeline"], writer: "caller" }
+  ] : [],
+  { path: "image_field", shape: "field", layouts: ["gallery"], writer: "caller" },
+  { path: "sorts", shape: "sorts", layouts: ALL, writer: "caller" },
+  { path: "rule_id", shape: "uuid", layouts: ALL, writer: "caller" },
+  { path: "is_default", shape: "boolean", layouts: ALL, writer: "caller" },
+  { path: "presentation", shape: "presentation", layouts: ALL, writer: "caller" },
+  { path: "presentation.style", shape: "style", layouts: ALL, writer: "caller" },
+  { path: "presentation.formats", shape: "object", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.frozen", shape: "fields", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.grouping", shape: "grouping", layouts: ["grid", "gallery", "list"], writer: "caller" },
+  { path: "presentation.widths", shape: "widths", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.rowHeight", shape: "row_height", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.hiddenFields", shape: "fields", layouts: HIDES, writer: "caller" },
+  { path: "presentation.cardHidden", shape: "fields", layouts: ["kanban", "calendar", ...STORE_KEEPS_TIMELINE ? ["timeline"] : [], "list", "gallery"], writer: "caller" },
+  { path: "presentation.columnOrder", shape: "fields", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.gallerySize", shape: "gallery_size", layouts: ["gallery"], writer: "caller" },
+  { path: "presentation.wrap", shape: "boolean", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.wrapColumns", shape: "fields", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.fit", shape: "fit", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.freezeFirst", shape: "boolean", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.footer", shape: "footer", layouts: GRIDS, writer: "caller" },
+  { path: "presentation.summaries", shape: "summaries", layouts: GRIDS, writer: "caller" },
+  { path: "grid", shape: "grid", layouts: GRIDS, writer: "caller" },
+  { path: "hidden_fields", shape: "input", layouts: HIDES, writer: "input" },
+  { path: "table_id", shape: "server", layouts: ALL, writer: "server" },
+  { path: "order", shape: "server", layouts: GRIDS, writer: "server" },
+  { path: "moved_from", shape: "server", layouts: ALL, writer: "server" }
+];
+var STORE_KEPT_LAYOUTS = ["grid", "kanban", "calendar", "gallery", ...STORE_KEEPS_TIMELINE ? ["timeline"] : [], "list"];
+var KINDS = STORE_KEPT_LAYOUTS;
+function viewSettings(definition, rowFilters) {
+  const data = definition ?? {};
+  const text = (key) => {
+    const v = data[key];
+    return typeof v === "string" && v !== "" ? v : null;
+  };
+  const layout = String(data["layout"] ?? "grid");
+  const flat = rowFilters ?? (isObject(data["filters"]) ? data["filters"] : null);
+  const moved = data["moved_from"];
+  return {
+    layout: KINDS.includes(layout) ? layout : "grid",
+    filters: flat && Object.keys(flat).length > 0 ? flat : null,
+    where: isRule(data["where"]) ? data["where"] : null,
+    groupField: text("group_field"),
+    swimlaneField: text("swimlane_field"),
+    collapsedColumns: Array.isArray(data["collapsed_columns"]) ? data["collapsed_columns"].filter((v) => ["string", "number", "boolean"].includes(typeof v)).map(String) : [],
+    measure: text("measure"),
+    dateField: text("date_field"),
+    startField: text("start_field"),
+    endField: text("end_field"),
+    imageField: text("image_field"),
+    sorts: parseSorts(data["sorts"]),
+    ruleId: text("rule_id"),
+    isDefault: data["is_default"] === true || data["is_default"] === "true",
+    presentation: parseGridPresentation(data["presentation"]),
+    movedFrom: isObject(moved) ? moved : null
+  };
+}
+function isObject(raw) {
+  return Boolean(raw) && typeof raw === "object" && !Array.isArray(raw);
+}
+function isRule(raw) {
+  if (!isObject(raw)) return false;
+  const node = raw;
+  return typeof node.op === "string" && Array.isArray(node.args);
+}
+function parseSorts(raw) {
+  let list = raw;
+  if (typeof raw === "string") {
+    try {
+      list = raw.trim() === "" ? [] : JSON.parse(raw);
+    } catch {
+      return [];
+    }
+  }
+  if (!Array.isArray(list)) return [];
+  return list.filter((s) => isObject(s) && typeof s.field === "string").map((s) => ({ field: s.field, direction: s.direction === "desc" ? "desc" : "asc" }));
+}
+
+// src/views.ts
+var VIEW_LAYOUTS = ["grid", "kanban", "calendar", "gallery", "timeline", "list"];
+var LAYOUT_LABEL = {
+  grid: "Grid",
+  kanban: "Kanban",
+  calendar: "Calendar",
+  gallery: "Gallery",
+  timeline: "Timeline",
+  list: "List"
+};
+function viewOrderOf(definition) {
+  const raw = definition?.["order"];
+  return raw === "manual" ? "manual" : raw === "sorted" ? "sorted" : null;
+}
+function defaultViewOf(views) {
+  return views.find((v) => v.isDefault);
+}
+var PAGE_VIEWS = [...VIEW_LAYOUTS, "dashboards", "archived"];
+var PAGE_VIEW_LABEL = {
+  ...LAYOUT_LABEL,
+  dashboards: "Dashboards",
+  archived: "Archived"
+};
+function viewFromRow(row) {
+  const data = row.definition ?? {};
+  const k = viewSettings(data, row.filters && Object.keys(row.filters).length > 0 ? row.filters : null);
+  const tableFromDefinition = typeof data["table_id"] === "string" && data["table_id"] !== "" ? data["table_id"] : null;
+  return {
+    id: row.view_id,
+    name: row.name || "Untitled view",
+    subject: row.table_id ?? tableFromDefinition ?? "",
+    layout: k.layout,
+    groupField: k.groupField,
+    swimlaneField: k.swimlaneField,
+    collapsedColumns: k.collapsedColumns,
+    measure: k.measure,
+    dateField: k.dateField,
+    startField: k.startField,
+    endField: k.endField,
+    imageField: k.imageField,
+    sorts: k.sorts,
+    order: viewOrderOf(data),
+    ruleId: k.ruleId,
+    ...k.filters ? { filters: k.filters } : {},
+    where: k.where,
+    // The older table's own default view, carried in by the mover, IS this table's default —
+    // the mover wrote the row's column, which `custom.views` does not return. Read as anything
+    // else, the page would seed a second "All records" beside it and open on that.
+    isDefault: k.isDefault || k.movedFrom?.["kind"] === "default_view",
+    presentation: k.presentation,
+    movedFrom: k.movedFrom
+  };
+}
+
+// src/viewLook.ts
+function lookFromDocument(doc) {
+  const data = doc ?? {};
+  const read = viewSettings(data);
+  const out = {};
+  const has = (key) => Object.prototype.hasOwnProperty.call(data, key);
+  if (has("layout") && VIEW_LAYOUTS.includes(String(data["layout"]))) {
+    out.layout = data["layout"];
+  }
+  if (has("group_field")) out.groupField = read.groupField;
+  if (has("swimlane_field")) out.swimlaneField = read.swimlaneField;
+  if (has("collapsed_columns")) out.collapsedColumns = read.collapsedColumns;
+  if (has("measure")) out.measure = read.measure;
+  if (has("date_field")) out.dateField = read.dateField;
+  if (has("start_field")) out.startField = read.startField;
+  if (has("end_field")) out.endField = read.endField;
+  if (has("image_field")) out.imageField = read.imageField;
+  if (has("sorts")) out.sorts = read.sorts;
+  if (has("where")) out.where = read.where;
+  if (has("presentation")) out.presentation = parseGridPresentation(data["presentation"]);
+  return out;
+}
+function applyLook(view, look) {
+  if (!look) return view;
+  return { ...view, ...look };
+}
+async function readLooks(client, tableId) {
+  const answered = await client.viewLookRead({ table_id: tableId });
+  if (!answered.ok) return answered;
+  const out = {};
+  for (const [viewId, row] of Object.entries(answered.data ?? {})) {
+    out[viewId] = lookFromDocument(row?.look ?? null);
+  }
+  return { ok: true, data: out };
+}
+
+// src/firstPage.ts
+var TABLE_PAGE_SIZE = 100;
+function firstGridPageArgs(input) {
+  const { shown, fields } = input;
+  if (!shown) return null;
+  if ((shown.layout ?? "grid") !== "grid") return null;
+  if (shown.ruleId) return null;
+  if (shown.order === "manual") return null;
+  if (shown.filters && Object.keys(shown.filters).length > 0) return null;
+  if (shown.presentation?.grouping) return null;
+  const first = (shown.sorts ?? [])[0];
+  const viewSort = first && fields.some((f) => f.key === first.field) ? { id: first.field, direction: first.direction } : null;
+  const opening = viewSort ?? defaultSortOf(input.table, fields);
+  return {
+    p_table_id: input.tableId,
+    p_filter: {},
+    p_search: null,
+    p_sort: pageSortFor(fields, opening),
+    p_view_id: null,
+    p_limit: input.pageSize ?? TABLE_PAGE_SIZE,
+    p_offset: 0
+  };
+}
+async function firstGridPageRequest(client, tableId, options = {}) {
+  const [table, fields, views, looks] = await Promise.all([
+    client.tableRead({ table_id: tableId }),
+    client.fields({ table_id: tableId }),
+    client.views({ table_id: tableId }),
+    readLooks(client, tableId)
+  ]);
+  if (!table.ok || !fields.ok || !views.ok || !looks.ok) return null;
+  const mine = views.data.map(viewFromRow).filter((v) => v.subject === tableId);
+  const view = defaultViewOf(mine) ?? mine[0] ?? null;
+  const shown = view ? applyLook(view, looks.data[view.id]) : null;
+  return firstGridPageArgs({ tableId, table: table.data, fields: fields.data, shown, ...options.pageSize ? { pageSize: options.pageSize } : {} });
+}
+//# sourceMappingURL=first-page.cjs.map