@x12i/data 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,52 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @x12i/data
+
+Data grid contracts for the Unified UI Kit.
+
+> **Status: foundation.** This package ships the types that apps, reports and
+> charts will depend on. The `Table` and `DataGrid` components are not built yet.
+
+```ts
+import { defineColumns, type ServerDataSource } from "@x12i/data";
+
+type Order = { id: string; customer: string; total: number };
+
+export const columns = defineColumns<Order>([
+  { id: "customer", header: "Customer", field: "customer", sortable: true },
+  { id: "total", header: "Total", field: "total", cellType: "currency" },
+]);
+
+export const orders: ServerDataSource<Order> = {
+  async getRows({ startRow, endRow, sort, filter }, { signal } = {}) {
+    // Call your API and return { rows, total }.
+    return { rows: [], total: 0 };
+  },
+};
+```
+
+## Saved views
+
+`SavedView` is versioned JSON. `parseSavedView(value)` reads one from untrusted
+storage (local storage, a URL, a server) and returns `null` for anything this
+version does not understand, so a bad or newer record is ignored instead of
+crashing the grid. `SavedViewStore` is the small interface an app implements to
+keep views: `list`, `load`, `save`, `delete`.
+
+`@x12i/flowix-ui` has one that keeps views as Flowix facts, so they follow the
+user across devices and keep a revision history:
+
+```ts
+import { createFlowixSavedViewStore } from "@x12i/flowix-ui/stores";
+
+const views = createFlowixSavedViewStore(flowix, { namespace: "grid-views" });
+```
+
+`@x12i/records` turns the same column definitions into a Fieldkit `FieldMap`
+(`fieldMapFromColumns`), so the detail view of a row uses the grid's headers.
+
+## Planned engine
+
+Headless: TanStack Table and TanStack Virtual (both MIT). Grouping, pivot, editing
+UX, saved views and cell types are built on top, so no feature depends on a
+commercial license.
+
+`SavedView` is already versioned JSON, so views saved today stay readable.

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Contracts for the kit's DataGrid (spec section 7). The grid is built on
+ * TanStack Table and TanStack Virtual; these types are the stable surface that
+ * apps, reports and charts depend on.
+ */
+type SortDirection = "asc" | "desc";
+interface SortModelItem {
+    field: string;
+    direction: SortDirection;
+}
+type FilterOperator = "contains" | "not-contains" | "starts-with" | "equals" | "not-equals" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "before" | "after" | "is-empty" | "is-not-empty";
+interface FilterModelItem {
+    field: string;
+    operator: FilterOperator;
+    /** Absent for `is-empty` and `is-not-empty`. An array for `in` and `between`. */
+    value?: unknown;
+}
+interface GroupModelItem {
+    field: string;
+}
+/** What the grid asks a server for. Row indexes are zero-based and `endRow` is exclusive. */
+interface GetRowsRequest {
+    startRow: number;
+    endRow: number;
+    sort: SortModelItem[];
+    filter: FilterModelItem[];
+    group: GroupModelItem[];
+}
+interface GetRowsResult<Row> {
+    rows: Row[];
+    /** Total rows matching the filter, so the grid can size its scrollbar. */
+    total: number;
+}
+interface GetRowsOptions {
+    /** Aborted when the grid no longer needs the answer, for example after a new sort. */
+    signal?: AbortSignal;
+}
+/** The server data source: `getRows({ startRow, endRow, sort, filter, group })` returns `{ rows, total }`. */
+interface ServerDataSource<Row> {
+    getRows(request: GetRowsRequest, options?: GetRowsOptions): Promise<GetRowsResult<Row>>;
+}
+/** Cell renderers the grid ships (spec section 7). */
+type CellType = "text" | "number" | "currency" | "percent" | "date" | "status" | "avatar" | "progress" | "sparkline" | "link" | "actions";
+/** Logical sides, so a pinned column follows the reading direction in RTL. */
+type ColumnPin = "start" | "end";
+interface ColumnDef<Row> {
+    /** Stable identifier, also used in saved views. */
+    id: string;
+    /** Header text. Pass a translated string. */
+    header: string;
+    /** Property of the row to read. */
+    field?: Extract<keyof Row, string>;
+    cellType?: CellType;
+    /** An `Intl`-based format name or options key, by cell type. */
+    format?: string;
+    width?: number;
+    minWidth?: number;
+    pinned?: ColumnPin;
+    sortable?: boolean;
+    filterable?: boolean;
+    resizable?: boolean;
+    editable?: boolean;
+}
+/** Identity helper that infers `Row` for column authoring. */
+declare function defineColumns<Row>(columns: ColumnDef<Row>[]): ColumnDef<Row>[];
+interface ColumnState {
+    id: string;
+    width?: number;
+    hidden?: boolean;
+    pinned?: ColumnPin;
+}
+declare const SAVED_VIEW_VERSION = 1;
+/** Column state, filters and sort, serialized to JSON. */
+interface SavedView {
+    version: typeof SAVED_VIEW_VERSION;
+    name?: string;
+    columns: ColumnState[];
+    sort: SortModelItem[];
+    filter: FilterModelItem[];
+    group?: GroupModelItem[];
+}
+/** Every filter operator, as a runtime list for validation and pickers. */
+declare const FILTER_OPERATORS: readonly ["contains", "not-contains", "starts-with", "equals", "not-equals", "gt", "gte", "lt", "lte", "between", "in", "before", "after", "is-empty", "is-not-empty"];
+/**
+ * Reads a saved view from untrusted JSON (storage, a URL, a server). Returns
+ * `null` when the value is not a view this version understands, so a bad or
+ * newer record is ignored instead of crashing the grid.
+ */
+declare function parseSavedView(value: unknown): SavedView | null;
+/** One saved view in a list, without loading its body. */
+interface SavedViewSummary {
+    id: string;
+    name?: string;
+}
+/**
+ * Where an app keeps saved views. The grid does not care: pass any
+ * implementation (local storage, your API, `@x12i/flowix-ui`'s Flowix adapter).
+ */
+interface SavedViewStore {
+    list(): Promise<SavedViewSummary[]>;
+    /** `null` when the id does not exist or holds something `parseSavedView` rejects. */
+    load(id: string): Promise<SavedView | null>;
+    save(id: string, view: SavedView): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+
+export { FILTER_OPERATORS, SAVED_VIEW_VERSION, defineColumns, parseSavedView };
+export type { CellType, ColumnDef, ColumnPin, ColumnState, FilterModelItem, FilterOperator, GetRowsOptions, GetRowsRequest, GetRowsResult, GroupModelItem, SavedView, SavedViewStore, SavedViewSummary, ServerDataSource, SortDirection, SortModelItem };

package/dist/index.js

@@ -0,0 +1,55 @@
+// src/index.ts
+function defineColumns(columns) {
+  return columns;
+}
+var SAVED_VIEW_VERSION = 1;
+var FILTER_OPERATORS = [
+  "contains",
+  "not-contains",
+  "starts-with",
+  "equals",
+  "not-equals",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+  "in",
+  "before",
+  "after",
+  "is-empty",
+  "is-not-empty"
+];
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var isOptionalNumber = (value) => value === void 0 || typeof value === "number" && Number.isFinite(value);
+function parseSavedView(value) {
+  if (!isRecord(value) || value.version !== SAVED_VIEW_VERSION) return null;
+  if (value.name !== void 0 && typeof value.name !== "string") return null;
+  const { columns, sort, filter, group } = value;
+  if (!Array.isArray(columns) || !Array.isArray(sort) || !Array.isArray(filter)) return null;
+  if (group !== void 0 && !Array.isArray(group)) return null;
+  for (const column of columns) {
+    if (!isRecord(column) || typeof column.id !== "string") return null;
+    if (!isOptionalNumber(column.width)) return null;
+    if (column.hidden !== void 0 && typeof column.hidden !== "boolean") return null;
+    if (column.pinned !== void 0 && column.pinned !== "start" && column.pinned !== "end") {
+      return null;
+    }
+  }
+  for (const item of sort) {
+    if (!isRecord(item) || typeof item.field !== "string") return null;
+    if (item.direction !== "asc" && item.direction !== "desc") return null;
+  }
+  for (const item of filter) {
+    if (!isRecord(item) || typeof item.field !== "string") return null;
+    if (!FILTER_OPERATORS.includes(item.operator)) return null;
+  }
+  for (const item of group ?? []) {
+    if (!isRecord(item) || typeof item.field !== "string") return null;
+  }
+  return value;
+}
+
+export { FILTER_OPERATORS, SAVED_VIEW_VERSION, defineColumns, parseSavedView };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":";AAuGO,SAAS,cAAmB,OAAA,EAA6C;AAC9E,EAAA,OAAO,OAAA;AACT;AASO,IAAM,kBAAA,GAAqB;AAa3B,IAAM,gBAAA,GAAmB;AAAA,EAC9B,UAAA;AAAA,EACA,cAAA;AAAA,EACA,aAAA;AAAA,EACA,QAAA;AAAA,EACA,YAAA;AAAA,EACA,IAAA;AAAA,EACA,KAAA;AAAA,EACA,IAAA;AAAA,EACA,KAAA;AAAA,EACA,SAAA;AAAA,EACA,IAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF;AASA,IAAM,QAAA,GAAW,CAAC,KAAA,KAChB,OAAO,KAAA,KAAU,QAAA,IAAY,KAAA,KAAU,IAAA,IAAQ,CAAC,KAAA,CAAM,OAAA,CAAQ,KAAK,CAAA;AAErE,IAAM,gBAAA,GAAmB,CAAC,KAAA,KACxB,KAAA,KAAU,MAAA,IAAc,OAAO,KAAA,KAAU,QAAA,IAAY,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA;AAOrE,SAAS,eAAe,KAAA,EAAkC;AAC/D,EAAA,IAAI,CAAC,QAAA,CAAS,KAAK,KAAK,KAAA,CAAM,OAAA,KAAY,oBAAoB,OAAO,IAAA;AACrE,EAAA,IAAI,MAAM,IAAA,KAAS,MAAA,IAAa,OAAO,KAAA,CAAM,IAAA,KAAS,UAAU,OAAO,IAAA;AAEvE,EAAA,MAAM,EAAE,OAAA,EAAS,IAAA,EAAM,MAAA,EAAQ,OAAM,GAAI,KAAA;AACzC,EAAA,IAAI,CAAC,KAAA,CAAM,OAAA,CAAQ,OAAO,KAAK,CAAC,KAAA,CAAM,OAAA,CAAQ,IAAI,KAAK,CAAC,KAAA,CAAM,OAAA,CAAQ,MAAM,GAAG,OAAO,IAAA;AACtF,EAAA,IAAI,UAAU,MAAA,IAAa,CAAC,MAAM,OAAA,CAAQ,KAAK,GAAG,OAAO,IAAA;AAEzD,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,IAAA,IAAI,CAAC,SAAS,MAAM,CAAA,IAAK,OAAO,MAAA,CAAO,EAAA,KAAO,UAAU,OAAO,IAAA;AAC/D,IAAA,IAAI,CAAC,gBAAA,CAAiB,MAAA,CAAO,KAAK,GAAG,OAAO,IAAA;AAC5C,IAAA,IAAI,OAAO,MAAA,KAAW,MAAA,IAAa,OAAO,MAAA,CAAO,MAAA,KAAW,WAAW,OAAO,IAAA;AAC9E,IAAA,IAAI,MAAA,CAAO,WAAW,MAAA,IAAa,MAAA,CAAO,WAAW,OAAA,IAAW,MAAA,CAAO,WAAW,KAAA,EAAO;AACvF,MAAA,OAAO,IAAA;AAAA,IACT;AAAA,EACF;AACA,EAAA,KAAA,MAAW,QAAQ,IAAA,EAAM;AACvB,IAAA,IAAI,CAAC,SAAS,IAAI,CAAA,IAAK,OAAO,IAAA,CAAK,KAAA,KAAU,UAAU,OAAO,IAAA;AAC9D,IAAA,IAAI,KAAK,SAAA,KAAc,KAAA,IAAS,IAAA,CAAK,SAAA,KAAc,QAAQ,OAAO,IAAA;AAAA,EACpE;AACA,EAAA,KAAA,MAAW,QAAQ,MAAA,EAAQ;AACzB,IAAA,IAAI,CAAC,SAAS,IAAI,CAAA,IAAK,OAAO,IAAA,CAAK,KAAA,KAAU,UAAU,OAAO,IAAA;AAC9D,IAAA,IAAI,CAAE,gBAAA,CAAwC,QAAA,CAAS,IAAA,CAAK,QAAQ,GAAG,OAAO,IAAA;AAAA,EAChF;AACA,EAAA,KAAA,MAAW,IAAA,IAAQ,KAAA,IAAS,EAAC,EAAG;AAC9B,IAAA,IAAI,CAAC,SAAS,IAAI,CAAA,IAAK,OAAO,IAAA,CAAK,KAAA,KAAU,UAAU,OAAO,IAAA;AAAA,EAChE;AAEA,EAAA,OAAO,KAAA;AACT","file":"index.js","sourcesContent":["/**\r\n * Contracts for the kit's DataGrid (spec section 7). The grid is built on\r\n * TanStack Table and TanStack Virtual; these types are the stable surface that\r\n * apps, reports and charts depend on.\r\n */\r\n\r\nexport type SortDirection = \"asc\" | \"desc\";\r\n\r\nexport interface SortModelItem {\r\n  field: string;\r\n  direction: SortDirection;\r\n}\r\n\r\nexport type FilterOperator =\r\n  | \"contains\"\r\n  | \"not-contains\"\r\n  | \"starts-with\"\r\n  | \"equals\"\r\n  | \"not-equals\"\r\n  | \"gt\"\r\n  | \"gte\"\r\n  | \"lt\"\r\n  | \"lte\"\r\n  | \"between\"\r\n  | \"in\"\r\n  | \"before\"\r\n  | \"after\"\r\n  | \"is-empty\"\r\n  | \"is-not-empty\";\r\n\r\nexport interface FilterModelItem {\r\n  field: string;\r\n  operator: FilterOperator;\r\n  /** Absent for `is-empty` and `is-not-empty`. An array for `in` and `between`. */\r\n  value?: unknown;\r\n}\r\n\r\nexport interface GroupModelItem {\r\n  field: string;\r\n}\r\n\r\n/** What the grid asks a server for. Row indexes are zero-based and `endRow` is exclusive. */\r\nexport interface GetRowsRequest {\r\n  startRow: number;\r\n  endRow: number;\r\n  sort: SortModelItem[];\r\n  filter: FilterModelItem[];\r\n  group: GroupModelItem[];\r\n}\r\n\r\nexport interface GetRowsResult<Row> {\r\n  rows: Row[];\r\n  /** Total rows matching the filter, so the grid can size its scrollbar. */\r\n  total: number;\r\n}\r\n\r\nexport interface GetRowsOptions {\r\n  /** Aborted when the grid no longer needs the answer, for example after a new sort. */\r\n  signal?: AbortSignal;\r\n}\r\n\r\n/** The server data source: `getRows({ startRow, endRow, sort, filter, group })` returns `{ rows, total }`. */\r\nexport interface ServerDataSource<Row> {\r\n  getRows(request: GetRowsRequest, options?: GetRowsOptions): Promise<GetRowsResult<Row>>;\r\n}\r\n\r\n/** Cell renderers the grid ships (spec section 7). */\r\nexport type CellType =\r\n  | \"text\"\r\n  | \"number\"\r\n  | \"currency\"\r\n  | \"percent\"\r\n  | \"date\"\r\n  | \"status\"\r\n  | \"avatar\"\r\n  | \"progress\"\r\n  | \"sparkline\"\r\n  | \"link\"\r\n  | \"actions\";\r\n\r\n/** Logical sides, so a pinned column follows the reading direction in RTL. */\r\nexport type ColumnPin = \"start\" | \"end\";\r\n\r\nexport interface ColumnDef<Row> {\r\n  /** Stable identifier, also used in saved views. */\r\n  id: string;\r\n  /** Header text. Pass a translated string. */\r\n  header: string;\r\n  /** Property of the row to read. */\r\n  field?: Extract<keyof Row, string>;\r\n  cellType?: CellType;\r\n  /** An `Intl`-based format name or options key, by cell type. */\r\n  format?: string;\r\n  width?: number;\r\n  minWidth?: number;\r\n  pinned?: ColumnPin;\r\n  sortable?: boolean;\r\n  filterable?: boolean;\r\n  resizable?: boolean;\r\n  editable?: boolean;\r\n}\r\n\r\n/** Identity helper that infers `Row` for column authoring. */\r\nexport function defineColumns<Row>(columns: ColumnDef<Row>[]): ColumnDef<Row>[] {\r\n  return columns;\r\n}\r\n\r\nexport interface ColumnState {\r\n  id: string;\r\n  width?: number;\r\n  hidden?: boolean;\r\n  pinned?: ColumnPin;\r\n}\r\n\r\nexport const SAVED_VIEW_VERSION = 1;\r\n\r\n/** Column state, filters and sort, serialized to JSON. */\r\nexport interface SavedView {\r\n  version: typeof SAVED_VIEW_VERSION;\r\n  name?: string;\r\n  columns: ColumnState[];\r\n  sort: SortModelItem[];\r\n  filter: FilterModelItem[];\r\n  group?: GroupModelItem[];\r\n}\r\n\n/** Every filter operator, as a runtime list for validation and pickers. */\nexport const FILTER_OPERATORS = [\n  \"contains\",\n  \"not-contains\",\n  \"starts-with\",\n  \"equals\",\n  \"not-equals\",\n  \"gt\",\n  \"gte\",\n  \"lt\",\n  \"lte\",\n  \"between\",\n  \"in\",\n  \"before\",\n  \"after\",\n  \"is-empty\",\n  \"is-not-empty\",\n] as const satisfies readonly FilterOperator[];\n\n// Compile-time guard: adding an operator to `FilterOperator` without listing it\n// above makes this line fail to type-check.\nconst _everyOperatorListed: Exclude<FilterOperator, (typeof FILTER_OPERATORS)[number]> extends never\n  ? true\n  : never = true;\nvoid _everyOperatorListed;\n\nconst isRecord = (value: unknown): value is Record<string, unknown> =>\n  typeof value === \"object\" && value !== null && !Array.isArray(value);\n\nconst isOptionalNumber = (value: unknown) =>\n  value === undefined || (typeof value === \"number\" && Number.isFinite(value));\n\n/**\n * Reads a saved view from untrusted JSON (storage, a URL, a server). Returns\n * `null` when the value is not a view this version understands, so a bad or\n * newer record is ignored instead of crashing the grid.\n */\nexport function parseSavedView(value: unknown): SavedView | null {\n  if (!isRecord(value) || value.version !== SAVED_VIEW_VERSION) return null;\n  if (value.name !== undefined && typeof value.name !== \"string\") return null;\n\n  const { columns, sort, filter, group } = value;\n  if (!Array.isArray(columns) || !Array.isArray(sort) || !Array.isArray(filter)) return null;\n  if (group !== undefined && !Array.isArray(group)) return null;\n\n  for (const column of columns) {\n    if (!isRecord(column) || typeof column.id !== \"string\") return null;\n    if (!isOptionalNumber(column.width)) return null;\n    if (column.hidden !== undefined && typeof column.hidden !== \"boolean\") return null;\n    if (column.pinned !== undefined && column.pinned !== \"start\" && column.pinned !== \"end\") {\n      return null;\n    }\n  }\n  for (const item of sort) {\n    if (!isRecord(item) || typeof item.field !== \"string\") return null;\n    if (item.direction !== \"asc\" && item.direction !== \"desc\") return null;\n  }\n  for (const item of filter) {\n    if (!isRecord(item) || typeof item.field !== \"string\") return null;\n    if (!(FILTER_OPERATORS as readonly unknown[]).includes(item.operator)) return null;\n  }\n  for (const item of group ?? []) {\n    if (!isRecord(item) || typeof item.field !== \"string\") return null;\n  }\n\n  return value as unknown as SavedView;\n}\n\n/** One saved view in a list, without loading its body. */\nexport interface SavedViewSummary {\n  id: string;\n  name?: string;\n}\n\n/**\n * Where an app keeps saved views. The grid does not care: pass any\n * implementation (local storage, your API, `@x12i/flowix-ui`'s Flowix adapter).\n */\nexport interface SavedViewStore {\n  list(): Promise<SavedViewSummary[]>;\n  /** `null` when the id does not exist or holds something `parseSavedView` rejects. */\n  load(id: string): Promise<SavedView | null>;\n  save(id: string, view: SavedView): Promise<void>;\n  delete(id: string): Promise<void>;\n}\n"]}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@x12i/data",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Data grid contracts for the Unified UI Kit: server data source, column definitions and saved views. The DataGrid itself (on TanStack Table) is planned.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/unified-ui-kit.git",
+    "directory": "packages/data"
+  },
+  "homepage": "https://github.com/x12i/unified-ui-kit/tree/main/packages/data#readme",
+  "bugs": {
+    "url": "https://github.com/x12i/unified-ui-kit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
 }