@zoobzio/table 0.0.0-stage → 0.0.1

package/.dist/index.d.mts

@@ -0,0 +1,328 @@
+import { Entry, Filter, Service as Service$1 } from "@zoobzio/query";
+import { Change as Change$1, Changers as Changers$1, Changes as Changes$1, Listener as Listener$1, Middleware as Middleware$1, Options as Options$1 } from "@zoobzio/kit";
+/**
+ * Column data type — drives cell rendering and sort behavior.
+ */
+export type ColumnType = "text" | "number" | "date" | "datetime" | "boolean" | "enum" | "currency" | "filesize" | "url" | "image" | "action";
+export interface DataTableColumn<T> {
+  key: keyof T;
+  label: string;
+  type?: ColumnType;
+  align?: "left" | "center" | "right";
+  sortable?: boolean;
+  sortKey?: string;
+  enumValues?: string[];
+  /**
+   * Whether the column appears in the search autocomplete. Defaults by
+   * type: everything except `action` and `image` is filterable.
+   */
+  filterable?: boolean;
+}
+/**
+ * A committed column filter, as the query holds it. Keys are strings,
+ * matching the `sortField` / `columnOrder` convention; `op` is present for
+ * operator columns (date/datetime: before/after/on, number/currency:
+ * over/under/is).
+ */
+export type TableFilter = Filter;
+export type SortDirection = "asc" | "desc";
+/**
+ * The serializable half of a row/bulk action: how it renders. The behavior
+ * half is a handler registered under the same key in `Actions`.
+ */
+export interface ActionDescriptor {
+  label: string;
+}
+/**
+ * Row action — the live shape the service exposes: descriptor joined with
+ * its handler, under the config key. `runAction(key, row)` dispatches by
+ * key.
+ */
+export interface RowAction<T> {
+  key: string;
+  label: string;
+  action: (row: T) => void;
+}
+/**
+ * Bulk action — the live shape the service exposes: descriptor joined with
+ * its handler, under the config key. `runBulkAction(key)` dispatches by key
+ * over the service's selection.
+ */
+export interface BulkAction {
+  key: string;
+  label: string;
+  action: (selected: Set<string>) => void;
+}
+/**
+ * Parameters passed to the fetch action. The table owns paging and sort;
+ * its query owns the search: `query` is the committed free text, `filters`
+ * the committed column filters.
+ */
+export interface DataTableFetchParams {
+  page: number;
+  pageSize: number;
+  sortField: string | null;
+  sortDirection: SortDirection;
+  query: string;
+  filters: TableFilter[];
+}
+export interface DataTableFetchResult<T> {
+  data: T[];
+  total: number;
+  pageCount: number;
+}
+/**
+ * Config the consumer provides — pure serializable data. Actions are
+ * descriptor records: the key is the action's identity, shared with the
+ * handler record in `Actions`.
+ */
+export type Config<T> = {
+  columns: DataTableColumn<T>[];
+  rowKey: keyof T;
+  actions?: Record<string, ActionDescriptor>;
+  bulkActions?: Record<string, ActionDescriptor>;
+  pinnedColumns?: (keyof T)[];
+  defaultColumnOrder?: (keyof T)[];
+  /**
+   * Whether a UI renders the toolbar search. Defaults to `true`. A hint for
+   * the view layer only — the search surface on the service (`query`,
+   * `filters`, mutators, fetch params) stays live for imperative use.
+   */
+  searchable?: boolean;
+  /**
+   * The BCP 47 locale cells format in. Defaults to `en-US`.
+   */
+  locale?: string;
+  /**
+   * The ISO 4217 code currency cells format in. Defaults to `USD`.
+   */
+  currency?: string;
+};
+/**
+ * The state container the service reads and writes: paging, sort,
+ * selection, column order, and the query's slice. The container can be a
+ * plain object or a reactive proxy. The service replaces each member as a
+ * whole, so a proxy tracks every change. `entries` and `draft` belong to
+ * the table's `query` machine, its only writer.
+ */
+export type State<T> = {
+  data: T[];
+  loading: boolean;
+  initialized: boolean;
+  page: number;
+  pageSize: number;
+  total: number;
+  pageCount: number;
+  sortField: string | null;
+  sortDirection: SortDirection;
+  selected: Set<string>;
+  columnOrder: string[];
+  entries: Entry[];
+  draft: string;
+};
+export type StateKey = keyof State<unknown>;
+/**
+ * The kit's state mechanisms bound to this service's container: per-field
+ * middleware, the read/write options, and the change objects.
+ */
+export type Middleware<T> = Middleware$1<State<T>>;
+export type Options<T> = Options$1<State<T>>;
+export type Changes<T> = Changes$1<State<T>>;
+export type Change<T, K extends StateKey = StateKey> = Change$1<State<T>, K>;
+export type Changers<T> = Changers$1<State<T>>;
+/**
+ * The consumer-supplied behavior: the fetch mechanism plus handlers keyed
+ * like the config's descriptor records.
+ */
+export type Actions<T> = {
+  fetch: (params: DataTableFetchParams, service: Service<T>) => Promise<DataTableFetchResult<T>>;
+  actions?: Record<string, (row: T) => void>;
+  bulkActions?: Record<string, (selected: Set<string>) => void>;
+};
+/**
+ * The events of a table service, keyed by name. Each value is the argument
+ * list of a listener. The service emits after the write lands, so a listener
+ * reads the new state.
+ *
+ * - `change`: any field of the container was written.
+ * - `updated`: a fetch settled, success or failure. `total` is the stored total.
+ * - `filtered`: the query's entries changed.
+ */
+export type Events<T> = {
+  change: [change: Change<T>];
+  updated: [event: {
+    id: string;
+    total: number;
+  }];
+  filtered: [event: {
+    id: string;
+    query: string;
+    filters: TableFilter[];
+  }];
+};
+export type Event<T> = keyof Events<T>;
+export type Listener<T, E extends Event<T>> = Listener$1<Events<T>, E>;
+export type Service<T> = {
+  readonly id: string;
+  readonly config: Config<T>;
+  readonly columns: DataTableColumn<T>[];
+  readonly rowKey: keyof T;
+  readonly actions: RowAction<T>[];
+  readonly bulkActions: BulkAction[];
+  readonly pinnedColumns: (keyof T)[];
+  readonly searchable: boolean;
+  readonly locale: string;
+  readonly currency: string;
+  /**
+   * The query machine over the filterable columns: one field per column,
+   * with the operators of its type and the values of an enum or boolean
+   * column. A change to its entries refetches from the first page.
+   */
+  readonly query: Service$1;
+  readonly data: T[];
+  readonly loading: boolean;
+  readonly initialized: boolean;
+  readonly page: number;
+  readonly pageSize: number;
+  readonly total: number;
+  readonly pageCount: number;
+  readonly sortField: string | null;
+  readonly sortDirection: SortDirection;
+  readonly selected: Set<string>;
+  readonly columnOrder: string[];
+  readonly visibleColumns: DataTableColumn<T>[];
+  readonly filterableColumns: DataTableColumn<T>[];
+  readonly isAllSelected: boolean;
+  readonly isIndeterminate: boolean;
+  readonly selectAllState: boolean | "indeterminate";
+  readonly colSpan: number;
+  readonly hasSelection: boolean;
+  readonly isSelectable: boolean;
+  readonly hasActions: boolean;
+  goToPage(page: number): void;
+  setPageSize(size: number): void;
+  sortBy(field: string): void;
+  sortFieldFor(col: DataTableColumn<T>): string;
+  isSorted(col: DataTableColumn<T>): boolean;
+  keyOf(row: T): string;
+  toggleRow(key: string): void;
+  toggleAll(): void;
+  clearSelection(): void;
+  isRowSelected(row: T): boolean;
+  toggleColumn(key: keyof T): void;
+  setVisibleColumns(keys: Iterable<string>): void;
+  moveColumn(key: string, toKey: string): void;
+  reorderColumns(order: string[]): void;
+  resetColumns(): void;
+  isColumnPinned(key: keyof T): boolean;
+  isColumnVisible(key: keyof T): boolean;
+  runAction(key: string, row: T): void;
+  runBulkAction(key: string): void;
+  init(): Promise<boolean>;
+  fetch(): Promise<void>;
+  /**
+   * Subscribes a listener to an event. Listeners run in subscription order.
+   * An error in a listener propagates to the caller of the write. Returns a
+   * function that removes the listener.
+   */
+  on<E extends Event<T>>(event: E, listener: Listener<T, E>): () => void;
+};
+export declare const TABLE_DEFAULT_PAGE_SIZE = 25;
+export declare const TABLE_DEFAULT_SORT_DIRECTION: SortDirection;
+export declare const TABLE_DEFAULT_LOCALE = "en-US";
+export declare const TABLE_DEFAULT_CURRENCY = "USD";
+export declare const TABLE_DATE_OPERATORS: readonly ["before", "after", "on"];
+export declare const TABLE_NUMBER_OPERATORS: readonly ["over", "under", "is"];
+/**
+ * The operators a column type accepts on a filter. A type absent here has
+ * no operator stage: its filters carry no `op`.
+ */
+export declare const TABLE_OPERATORS: Partial<Record<ColumnType, readonly string[]>>;
+/**
+ * The operator a filter takes when the caller names none, by column type.
+ */
+export declare const TABLE_DEFAULT_OPERATORS: Partial<Record<ColumnType, string>>;
+/**
+ * The fields of the container, for key-driven iteration independent of a
+ * container's runtime keys.
+ */
+export declare const TABLE_STATE_FIELDS: Record<StateKey, null>;
+/**
+ * Builds the initial state container from config defaults. The result is a
+ * plain object. Wrap it in a reactive proxy to track reads and writes.
+ */
+export declare const createTableState: <T>(config: Config<T>) => State<T>;
+/**
+ * The headless table machine. Owns paging, sort, selection, column order,
+ * and the query over its columns; delegates data loading to `wiring.fetch`.
+ *
+ * The service reads and writes the `state` container through the `options`
+ * middleware. The container can be a plain object or a reactive proxy; the
+ * service replaces each member as a whole. Each write emits `change`, and
+ * the domain methods emit `updated` and `filtered`. `on` subscribes.
+ */
+export declare class TableService<T> implements Service<T> {
+  readonly id: string;
+  readonly config: Config<T>;
+  private readonly wiring;
+  readonly columns: DataTableColumn<T>[];
+  readonly rowKey: keyof T;
+  readonly actions: Service<T>["actions"];
+  readonly bulkActions: Service<T>["bulkActions"];
+  readonly pinnedColumns: (keyof T)[];
+  readonly query: Service$1;
+  private readonly state;
+  private readonly emitter;
+  private readonly columnMap;
+  private readonly definitionIndex;
+  private readonly pinnedSet;
+  private readonly defaultColumnKeys;
+  constructor(id: string, config: Config<T>, state: State<T>, wiring: Actions<T>, options?: Options<T>);
+  on<E extends Event<T>>(event: E, listener: Listener<T, E>): () => void;
+  get data(): T[];
+  get loading(): boolean;
+  get initialized(): boolean;
+  get page(): number;
+  get pageSize(): number;
+  get total(): number;
+  get pageCount(): number;
+  get sortField(): string | null;
+  get sortDirection(): SortDirection;
+  get selected(): Set<string>;
+  get columnOrder(): string[];
+  get searchable(): boolean;
+  get locale(): string;
+  get currency(): string;
+  get filterableColumns(): DataTableColumn<T>[];
+  get visibleColumns(): DataTableColumn<T>[];
+  get isAllSelected(): boolean;
+  get isIndeterminate(): boolean;
+  get selectAllState(): boolean | "indeterminate";
+  get colSpan(): number;
+  get hasSelection(): boolean;
+  get isSelectable(): boolean;
+  get hasActions(): boolean;
+  keyOf(row: T): string;
+  goToPage(page: number): void;
+  setPageSize(size: number): void;
+  sortBy(field: string): void;
+  sortFieldFor(col: DataTableColumn<T>): string;
+  isSorted(col: DataTableColumn<T>): boolean;
+  toggleRow(key: string): void;
+  toggleAll(): void;
+  clearSelection(): void;
+  isRowSelected(row: T): boolean;
+  isColumnPinned(key: keyof T): boolean;
+  isColumnVisible(key: keyof T): boolean;
+  toggleColumn(key: keyof T): void;
+  setVisibleColumns(keys: Iterable<string>): void;
+  moveColumn(key: string, toKey: string): void;
+  reorderColumns(order: string[]): void;
+  private insertAtDefinition;
+  runAction(key: string, row: T): void;
+  runBulkAction(key: string): void;
+  resetColumns(): void;
+  private refilter;
+  init(): Promise<boolean>;
+  fetch(): Promise<void>;
+}

package/.dist/index.mjs

@@ -0,0 +1,322 @@
+import { entries } from "objectively";
+import { QueryService } from "@zoobzio/query";
+import { makeEmitter, makeProxy } from "@zoobzio/kit";
+const TABLE_DEFAULT_PAGE_SIZE = 25;
+const TABLE_DEFAULT_SORT_DIRECTION = "asc";
+const TABLE_DEFAULT_LOCALE = "en-US";
+const TABLE_DEFAULT_CURRENCY = "USD";
+const TABLE_DATE_OPERATORS = [
+	"before",
+	"after",
+	"on"
+];
+const TABLE_NUMBER_OPERATORS = [
+	"over",
+	"under",
+	"is"
+];
+const TABLE_OPERATORS = {
+	date: TABLE_DATE_OPERATORS,
+	datetime: TABLE_DATE_OPERATORS,
+	number: TABLE_NUMBER_OPERATORS,
+	currency: TABLE_NUMBER_OPERATORS,
+	filesize: TABLE_NUMBER_OPERATORS
+};
+const TABLE_DEFAULT_OPERATORS = {
+	date: "on",
+	datetime: "on",
+	number: "is",
+	currency: "is",
+	filesize: "is"
+};
+const TABLE_STATE_FIELDS = {
+	data: null,
+	loading: null,
+	initialized: null,
+	page: null,
+	pageSize: null,
+	total: null,
+	pageCount: null,
+	sortField: null,
+	sortDirection: null,
+	selected: null,
+	columnOrder: null,
+	entries: null,
+	draft: null
+};
+const createTableState = (config) => ({
+	data: [],
+	loading: false,
+	initialized: false,
+	page: 1,
+	pageSize: 25,
+	total: 0,
+	pageCount: 0,
+	sortField: null,
+	sortDirection: "asc",
+	selected: /* @__PURE__ */ new Set(),
+	columnOrder: (config.defaultColumnOrder ?? config.columns.map((c) => c.key)).map(String),
+	entries: [],
+	draft: ""
+});
+const fields = (columns) => Object.fromEntries(columns.map((c) => {
+	const operators = c.type ? TABLE_OPERATORS[c.type] : void 0;
+	const defaultOperator = c.type ? TABLE_DEFAULT_OPERATORS[c.type] : void 0;
+	const values = c.type === "boolean" ? ["true", "false"] : c.enumValues;
+	return [String(c.key), {
+		label: c.label,
+		...operators && { operators },
+		...defaultOperator && { defaultOperator },
+		...values && { values }
+	}];
+}));
+var TableService = class {
+	id;
+	config;
+	wiring;
+	columns;
+	rowKey;
+	actions;
+	bulkActions;
+	pinnedColumns;
+	query;
+	state;
+	emitter = makeEmitter();
+	columnMap;
+	definitionIndex;
+	pinnedSet;
+	defaultColumnKeys;
+	constructor(id, config, state, wiring, options = {}) {
+		this.id = id;
+		this.config = config;
+		this.wiring = wiring;
+		this.state = makeProxy(state, TABLE_STATE_FIELDS, options, this.emitter);
+		this.columns = config.columns;
+		this.rowKey = config.rowKey;
+		this.actions = entries(config.actions ?? {}).map(([key, descriptor]) => ({
+			...descriptor,
+			key,
+			action: (row) => this.runAction(key, row)
+		}));
+		this.bulkActions = entries(config.bulkActions ?? {}).map(([key, descriptor]) => ({
+			...descriptor,
+			key,
+			action: (selected) => wiring.bulkActions?.[key]?.(selected)
+		}));
+		this.pinnedColumns = config.pinnedColumns ?? [];
+		this.columnMap = new Map(config.columns.map((c) => [String(c.key), c]));
+		this.definitionIndex = new Map(config.columns.map((c, i) => [String(c.key), i]));
+		this.pinnedSet = new Set(this.pinnedColumns.map(String));
+		this.defaultColumnKeys = (config.defaultColumnOrder ?? config.columns.map((c) => c.key)).map(String);
+		this.query = new QueryService(`${id}-query`, { fields: fields(this.filterableColumns) }, this.state);
+		this.query.on("changed", () => this.refilter());
+	}
+	on(event, listener) {
+		return this.emitter.on(event, listener);
+	}
+	get data() {
+		return this.state.data;
+	}
+	get loading() {
+		return this.state.loading;
+	}
+	get initialized() {
+		return this.state.initialized;
+	}
+	get page() {
+		return this.state.page;
+	}
+	get pageSize() {
+		return this.state.pageSize;
+	}
+	get total() {
+		return this.state.total;
+	}
+	get pageCount() {
+		return this.state.pageCount;
+	}
+	get sortField() {
+		return this.state.sortField;
+	}
+	get sortDirection() {
+		return this.state.sortDirection;
+	}
+	get selected() {
+		return this.state.selected;
+	}
+	get columnOrder() {
+		return this.state.columnOrder;
+	}
+	get searchable() {
+		return this.config.searchable ?? true;
+	}
+	get locale() {
+		return this.config.locale ?? "en-US";
+	}
+	get currency() {
+		return this.config.currency ?? "USD";
+	}
+	get filterableColumns() {
+		return this.columns.filter((c) => c.filterable ?? (c.type !== "action" && c.type !== "image"));
+	}
+	get visibleColumns() {
+		return this.columnOrder.map((key) => this.columnMap.get(key)).filter((c) => c !== void 0);
+	}
+	get isAllSelected() {
+		if (!this.data.length) return false;
+		return this.data.every((row) => this.selected.has(this.keyOf(row)));
+	}
+	get isIndeterminate() {
+		if (!this.selected.size) return false;
+		return !this.isAllSelected;
+	}
+	get selectAllState() {
+		if (this.isIndeterminate) return "indeterminate";
+		return this.isAllSelected;
+	}
+	get colSpan() {
+		return this.visibleColumns.length + (this.hasActions ? 1 : 0) + (this.isSelectable ? 1 : 0);
+	}
+	get hasSelection() {
+		return this.selected.size > 0;
+	}
+	get isSelectable() {
+		return this.bulkActions.length > 0;
+	}
+	get hasActions() {
+		return this.actions.length > 0;
+	}
+	keyOf(row) {
+		return String(row[this.config.rowKey]);
+	}
+	goToPage(page) {
+		if (page < 1 || page > this.pageCount) return;
+		this.state.page = page;
+		this.fetch();
+	}
+	setPageSize(size) {
+		this.state.pageSize = size;
+		this.state.page = 1;
+		this.fetch();
+	}
+	sortBy(field) {
+		if (this.sortField === field) this.state.sortDirection = this.sortDirection === "asc" ? "desc" : "asc";
+		else {
+			this.state.sortField = field;
+			this.state.sortDirection = "asc";
+		}
+		this.state.page = 1;
+		this.fetch();
+	}
+	sortFieldFor(col) {
+		return col.sortKey ?? String(col.key);
+	}
+	isSorted(col) {
+		return this.sortField === this.sortFieldFor(col);
+	}
+	toggleRow(key) {
+		const next = new Set(this.selected);
+		if (next.has(key)) next.delete(key);
+		else next.add(key);
+		this.state.selected = next;
+	}
+	toggleAll() {
+		if (this.isAllSelected) this.state.selected = /* @__PURE__ */ new Set();
+		else this.state.selected = new Set(this.data.map((row) => this.keyOf(row)));
+	}
+	clearSelection() {
+		this.state.selected = /* @__PURE__ */ new Set();
+	}
+	isRowSelected(row) {
+		return this.selected.has(this.keyOf(row));
+	}
+	isColumnPinned(key) {
+		return this.pinnedSet.has(String(key));
+	}
+	isColumnVisible(key) {
+		return this.columnOrder.includes(String(key));
+	}
+	toggleColumn(key) {
+		const k = String(key);
+		if (this.pinnedSet.has(k)) return;
+		if (this.columnOrder.includes(k)) this.state.columnOrder = this.columnOrder.filter((c) => c !== k);
+		else this.state.columnOrder = this.insertAtDefinition(this.columnOrder, k);
+	}
+	setVisibleColumns(keys) {
+		const wanted = new Set(keys);
+		for (const k of this.pinnedSet) wanted.add(k);
+		let order = this.columnOrder.filter((k) => wanted.has(k));
+		for (const k of wanted) {
+			if (!this.columnMap.has(k) || order.includes(k)) continue;
+			order = this.insertAtDefinition(order, k);
+		}
+		this.state.columnOrder = order;
+	}
+	moveColumn(key, toKey) {
+		if (key === toKey) return;
+		const order = [...this.columnOrder];
+		const from = order.indexOf(key);
+		const to = order.indexOf(toKey);
+		if (from === -1 || to === -1) return;
+		order.splice(from, 1);
+		order.splice(to, 0, key);
+		this.state.columnOrder = order;
+	}
+	reorderColumns(order) {
+		this.state.columnOrder = order;
+	}
+	insertAtDefinition(order, key) {
+		const index = this.definitionIndex.get(key) ?? Infinity;
+		const at = order.findIndex((k) => (this.definitionIndex.get(k) ?? Infinity) > index);
+		const next = [...order];
+		next.splice(at === -1 ? next.length : at, 0, key);
+		return next;
+	}
+	runAction(key, row) {
+		this.wiring.actions?.[key]?.(row);
+	}
+	runBulkAction(key) {
+		this.wiring.bulkActions?.[key]?.(this.selected);
+	}
+	resetColumns() {
+		this.state.columnOrder = this.defaultColumnKeys;
+	}
+	refilter() {
+		this.state.page = 1;
+		this.fetch();
+		this.emitter.emit("filtered", {
+			id: this.id,
+			query: this.query.text,
+			filters: this.query.filters
+		});
+	}
+	async init() {
+		if (this.initialized) return true;
+		this.state.initialized = true;
+		await this.fetch();
+		return true;
+	}
+	async fetch() {
+		this.state.loading = true;
+		try {
+			const result = await this.wiring.fetch({
+				page: this.page,
+				pageSize: this.pageSize,
+				sortField: this.sortField,
+				sortDirection: this.sortDirection,
+				query: this.query.text,
+				filters: this.query.filters
+			}, this);
+			this.state.data = result.data;
+			this.state.total = result.total;
+			this.state.pageCount = result.pageCount;
+		} finally {
+			this.state.loading = false;
+			this.emitter.emit("updated", {
+				id: this.id,
+				total: this.total
+			});
+		}
+	}
+};
+export { TABLE_DATE_OPERATORS, TABLE_DEFAULT_CURRENCY, TABLE_DEFAULT_LOCALE, TABLE_DEFAULT_OPERATORS, TABLE_DEFAULT_PAGE_SIZE, TABLE_DEFAULT_SORT_DIRECTION, TABLE_NUMBER_OPERATORS, TABLE_OPERATORS, TABLE_STATE_FIELDS, TableService, createTableState };

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alexander Thorwaldson
+
+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,79 @@
-# Temporary Holding Version
+# @zoobzio/table
 
-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.
+Headless data table service. Pure TypeScript, no framework dependency.
+
+Owns: paging, sort, row selection, column order, and the query over its
+columns (`@zoobzio/query`).
+Delegates: data loading (`fetch`) and state storage (the container).
+
+## Usage
+
+```ts
+import { TableService, createTableState } from "@zoobzio/table";
+
+const config = { columns: [{ key: "name", label: "Name" }], rowKey: "id" };
+
+const table = new TableService("users", config, createTableState(config), {
+  fetch: async (params) => api.users(params),
+});
+
+await table.init();
+table.sortBy("name");
+table.query.add({ kind: "filter", key: "status", value: "active" });
+```
+
+## Query
+
+`table.query` is a query service over the filterable columns: one field per
+column, with the operators and default operator of its type and the values
+of an enum or boolean column. Any view drives it: `add`, `remove`, `clear`,
+or the draft a text view composes through. A change to its entries resets
+the page, refetches, and emits `filtered`. The fetch params carry its `text`
+as `query` and its `filters`.
+
+```ts
+table.query.add({ kind: "filter", key: "status", value: "Active" });
+table.query.setDraft("Amount: over: 40");
+table.query.submit();
+table.query.filters; // [{ key: "status", value: "Active" }, { key: "amount", op: "over", value: "40" }]
+```
+
+## The state container
+
+The service reads and writes the `state` container: paging, sort, selection,
+column order, and the query's entries and draft. The container can be a
+plain object or a reactive proxy. The service replaces each member as a
+whole, so a proxy tracks every change.
+
+```ts
+createTableState(config); // plain: tests, Node
+reactive(createTableState(config)); // Vue
+useState(`table-${id}`, () => createTableState(config)).value; // Nuxt, shared by id
+```
+
+## Middleware
+
+`options.get.state.<field>` and `options.set.state.<field>` receive the value
+of the field and return the value the service uses. A missing slot passes the
+value on.
+
+```ts
+new TableService(id, config, state, wiring, {
+  set: { state: { query: (query) => query.trim() } },
+});
+```
+
+## Events
+
+`on(event, listener)` subscribes. Listeners run in subscription order, after
+the write lands. The return value removes the listener.
+
+- `change`: a field of the container was written. `{ field, before, after }`, narrowed by `field`.
+- `updated`: a fetch settled. `{ id, total }`.
+- `filtered`: the query's entries changed. `{ id, query, filters }`.
+
+```ts
+const off = table.on("change", (change) => {
+  if (change.field === "page") track(change.after);
+});
+```

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@zoobzio/table",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Headless data table service: paging, sort, selection, column order, and a query over the columns. No framework dependency.",
+  "license": "MIT",
+  "author": {
+    "name": "Alex Thorwaldson",
+    "email": "alex@zoobz.io",
+    "url": "https://zoobz.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zoobzio/foundation.git",
+    "directory": "packages/table"
+  },
+  "files": [
+    ".dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./.dist/index.mjs",
+  "types": "./.dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./.dist/index.d.mts",
+      "import": "./.dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "objectively": "^0.3.0",
+    "@zoobzio/kit": "0.0.1",
+    "@zoobzio/query": "0.0.1"
+  },
+  "scripts": {
+    "build": "obuild",
+    "stub": "obuild --stub",
+    "lint": "oxlint",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }