@metaobjectsdev/tanstack 0.5.0-rc.1

package/LICENSE

@@ -0,0 +1,189 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of recording and
+      discussing modifications to the Work, but excluding communication that
+      is conspicuously marked or designated in writing by the copyright owner
+      as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, reproduce, modify,
+      prepare derivative works of, distribute, and sublicense such modifications,
+      as an additional requirement of this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR
+      PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer
+      only obligations consistent to this License provided that the
+      obligations are consistent with this License.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format in question. Also add information
+      on how to contact you electronically and/or by mail.
+
+      Copyright 2026 MetaObjects Contributors
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,13 @@
+# @metaobjectsdev/tanstack
+
+TanStack runtime for metaobjects: `EntityFetcherProvider`, `<EntityGrid>`, `CellRendererProvider`, and `defaultCellRenderers`. Pairs with `@metaobjectsdev/codegen-ts-tanstack`, which generates `<Entity>.hooks.ts` and `<Entity>.columns.tsx` files that import from this package.
+
+## Install
+
+```bash
+pnpm add @metaobjectsdev/tanstack
+```
+
+## License
+
+Apache-2.0.

package/dist/cell-renderer-provider.d.ts

@@ -0,0 +1,10 @@
+import { type ReactNode } from "react";
+import { type CellRenderer } from "./cell-renderers.js";
+export interface CellRendererProviderProps {
+    /** Overrides merged on top of the inherited renderers. */
+    value: Partial<Record<string, CellRenderer>>;
+    children: ReactNode;
+}
+export declare function CellRendererProvider({ value, children }: CellRendererProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useCellRenderers(): Record<string, CellRenderer>;
+//# sourceMappingURL=cell-renderer-provider.d.ts.map

package/dist/cell-renderer-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-renderer-provider.d.ts","sourceRoot":"","sources":["../src/cell-renderer-provider.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAsC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAC3E,OAAO,EAAwB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAI9E,MAAM,WAAW,yBAAyB;IACxC,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC;IAC7C,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,yBAAyB,2CAIlF;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAE/D"}

package/dist/cell-renderer-provider.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { defaultCellRenderers } from "./cell-renderers.js";
+const CellRendererContext = createContext(defaultCellRenderers);
+export function CellRendererProvider({ value, children }) {
+    const inherited = useContext(CellRendererContext);
+    const merged = useMemo(() => ({ ...inherited, ...value }), [inherited, value]);
+    return _jsx(CellRendererContext.Provider, { value: merged, children: children });
+}
+export function useCellRenderers() {
+    return useContext(CellRendererContext);
+}
+//# sourceMappingURL=cell-renderer-provider.js.map

package/dist/cell-renderer-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-renderer-provider.js","sourceRoot":"","sources":["../src/cell-renderer-provider.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,OAAO,EAAkB,MAAM,OAAO,CAAC;AAC3E,OAAO,EAAE,oBAAoB,EAAqB,MAAM,qBAAqB,CAAC;AAE9E,MAAM,mBAAmB,GAAG,aAAa,CAA+B,oBAAoB,CAAC,CAAC;AAQ9F,MAAM,UAAU,oBAAoB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAA6B;IACjF,MAAM,SAAS,GAAG,UAAU,CAAC,mBAAmB,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,SAAS,EAAE,GAAG,KAAK,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,CAAiC,CAAC;IAC/G,OAAO,KAAC,mBAAmB,CAAC,QAAQ,IAAC,KAAK,EAAE,MAAM,YAAG,QAAQ,GAAgC,CAAC;AAChG,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC;AACzC,CAAC"}

package/dist/cell-renderers.d.ts

@@ -0,0 +1,9 @@
+import type { CellContext } from "@tanstack/react-table";
+import type { ReactNode } from "react";
+export type CellRenderer = (ctx: CellContext<any, any>) => ReactNode;
+/**
+ * Default cell renderers keyed by field `view` subtype.
+ * Apps override per-key via <CellRendererProvider>.
+ */
+export declare const defaultCellRenderers: Record<string, CellRenderer>;
+//# sourceMappingURL=cell-renderers.d.ts.map

package/dist/cell-renderers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-renderers.d.ts","sourceRoot":"","sources":["../src/cell-renderers.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,MAAM,MAAM,YAAY,GAAG,CAAC,GAAG,EAAE,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,SAAS,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA0B7D,CAAC"}

package/dist/cell-renderers.js

@@ -0,0 +1,35 @@
+import { formatCurrency } from "@metaobjectsdev/runtime-web";
+/**
+ * Default cell renderers keyed by field `view` subtype.
+ * Apps override per-key via <CellRendererProvider>.
+ */
+export const defaultCellRenderers = {
+    text: (ctx) => String(ctx.getValue() ?? ""),
+    textarea: (ctx) => String(ctx.getValue() ?? ""),
+    number: (ctx) => String(ctx.getValue() ?? ""),
+    date: (ctx) => {
+        const v = ctx.getValue();
+        return v ? new Date(v).toLocaleDateString() : "";
+    },
+    datetime: (ctx) => {
+        const v = ctx.getValue();
+        return v ? new Date(v).toLocaleString() : "";
+    },
+    boolean: (ctx) => (ctx.getValue() ? "Yes" : "No"),
+    currency: (ctx) => {
+        const value = ctx.getValue();
+        if (value == null || !Number.isFinite(Number(value)))
+            return "";
+        const meta = (ctx.column.columnDef.meta ?? {});
+        try {
+            return formatCurrency(value, meta.currency, meta.locale);
+        }
+        catch {
+            // Invalid currency code or unsupported locale — fall back to raw value
+            return String(value);
+        }
+    },
+    dropdown: (ctx) => String(ctx.getValue() ?? ""),
+    password: () => "•••••",
+};
+//# sourceMappingURL=cell-renderers.js.map

package/dist/cell-renderers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-renderers.js","sourceRoot":"","sources":["../src/cell-renderers.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAI7D;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAiC;IAChE,IAAI,EAAM,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/C,MAAM,EAAI,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/C,IAAI,EAAM,CAAC,GAAG,EAAE,EAAE;QAChB,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QACzB,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAW,CAAC,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,CAAC;IACD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;QAChB,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QACzB,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAW,CAAC,CAAC,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzD,CAAC;IACD,OAAO,EAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAClD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE;QAChB,MAAM,KAAK,GAAG,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC7B,IAAI,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAE,OAAO,EAAE,CAAC;QAChE,MAAM,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,IAAI,EAAE,CAA2C,CAAC;QACzF,IAAI,CAAC;YACH,OAAO,cAAc,CAAC,KAAe,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;IACH,CAAC;IACD,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC/C,QAAQ,EAAE,GAAG,EAAE,CAAC,OAAO;CACxB,CAAC"}

package/dist/entity-fetcher.d.ts

@@ -0,0 +1,11 @@
+import { type ReactNode } from "react";
+import type { EntityFetcher } from "@metaobjectsdev/runtime-web";
+export interface EntityFetcherProviderProps {
+    value: EntityFetcher;
+    children: ReactNode;
+}
+/** Wrap your app (or admin subtree) to supply a fetcher to generated hooks. */
+export declare function EntityFetcherProvider({ value, children }: EntityFetcherProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Reads the fetcher from context. Throws if not provided. */
+export declare function useEntityFetcher(): EntityFetcher;
+//# sourceMappingURL=entity-fetcher.d.ts.map

package/dist/entity-fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-fetcher.d.ts","sourceRoot":"","sources":["../src/entity-fetcher.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAIjE,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,aAAa,CAAC;IACrB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,0BAA0B,2CAEpF;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,IAAI,aAAa,CAShD"}

package/dist/entity-fetcher.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const EntityFetcherContext = createContext(null);
+/** Wrap your app (or admin subtree) to supply a fetcher to generated hooks. */
+export function EntityFetcherProvider({ value, children }) {
+    return _jsx(EntityFetcherContext.Provider, { value: value, children: children });
+}
+/** Reads the fetcher from context. Throws if not provided. */
+export function useEntityFetcher() {
+    const fetcher = useContext(EntityFetcherContext);
+    if (!fetcher) {
+        throw new Error("useEntityFetcher() called outside <EntityFetcherProvider>. " +
+            "Wrap your app (or the relevant subtree) with EntityFetcherProvider value={...}.");
+    }
+    return fetcher;
+}
+//# sourceMappingURL=entity-fetcher.js.map

package/dist/entity-fetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-fetcher.js","sourceRoot":"","sources":["../src/entity-fetcher.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAkB,MAAM,OAAO,CAAC;AAGlE,MAAM,oBAAoB,GAAG,aAAa,CAAuB,IAAI,CAAC,CAAC;AAOvE,+EAA+E;AAC/E,MAAM,UAAU,qBAAqB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAA8B;IACnF,OAAO,KAAC,oBAAoB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAiC,CAAC;AACjG,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACjD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CACb,6DAA6D;YAC3D,iFAAiF,CACpF,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/entity-grid.d.ts

@@ -0,0 +1,47 @@
+import { type ReactNode } from "react";
+import { type ColumnDef, type SortingState, type PaginationState, type ColumnFiltersState, type OnChangeFn } from "@tanstack/react-table";
+import type { GridConfig } from "@metaobjectsdev/runtime-web";
+export interface EntityGridState {
+    sorting: SortingState;
+    pagination: PaginationState;
+    columnFilters: ColumnFiltersState;
+}
+export interface EntityGridProps<T> {
+    columns: ColumnDef<T>[];
+    grid: GridConfig;
+    /** The single server page of rows. */
+    data: T[];
+    /** Total rows matching the filter (server-supplied; drives page count). */
+    rowCount: number;
+    /** Controlled state — owned by the parent / generated grid hook. */
+    state: EntityGridState;
+    onSortingChange: OnChangeFn<SortingState>;
+    onPaginationChange: OnChangeFn<PaginationState>;
+    onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
+    /** Optional free-text search — input renders iff onSearchChange is supplied. */
+    search?: string;
+    onSearchChange?: (value: string) => void;
+    isLoading?: boolean;
+    error?: Error | null;
+    emptyState?: ReactNode;
+    onRowClick?: (row: T) => void;
+    actions?: (row: T) => ReactNode;
+    className?: string;
+    headerClassName?: string;
+    rowClassName?: string;
+    cellClassName?: string;
+    paginationClassName?: string;
+    searchClassName?: string;
+}
+/**
+ * Controlled, server-driven data grid. All filter/sort/pagination state lives
+ * outside; on-change callbacks fire so the parent re-queries. The component
+ * renders `data` as-is — no client-side sort/paginate/filter row models.
+ *
+ * Cell rendering routes through the CellRendererProvider registry, keyed by
+ * `column.meta.view`. Per-column `cell` always wins if set.
+ */
+export declare function EntityGrid<T extends {
+    id?: number | string;
+}>(props: EntityGridProps<T>): ReactNode;
+//# sourceMappingURL=entity-grid.d.ts.map

package/dist/entity-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-grid.d.ts","sourceRoot":"","sources":["../src/entity-grid.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAChD,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,eAAe,CAAC;IAC5B,aAAa,EAAE,kBAAkB,CAAC;CACnC;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,OAAO,EAAG,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IACzB,IAAI,EAAM,UAAU,CAAC;IACrB,sCAAsC;IACtC,IAAI,EAAM,CAAC,EAAE,CAAC;IACd,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,KAAK,EAAK,eAAe,CAAC;IAC1B,eAAe,EAAQ,UAAU,CAAC,YAAY,CAAC,CAAC;IAChD,kBAAkB,EAAK,UAAU,CAAC,eAAe,CAAC,CAAC;IACnD,qBAAqB,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC;IACtD,gFAAgF;IAChF,MAAM,CAAC,EAAU,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,SAAS,CAAC,EAAG,OAAO,CAAC;IACrB,KAAK,CAAC,EAAO,KAAK,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAC9B,OAAO,CAAC,EAAK,CAAC,GAAG,EAAE,CAAC,KAAK,SAAS,CAAC;IACnC,SAAS,CAAC,EAAY,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAM,MAAM,CAAC;IAC7B,YAAY,CAAC,EAAS,MAAM,CAAC;IAC7B,aAAa,CAAC,EAAQ,MAAM,CAAC;IAC7B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAM,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS;IAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,EAC3D,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,GACxB,SAAS,CAoGX"}

package/dist/entity-grid.js

@@ -0,0 +1,57 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useReactTable, getCoreRowModel, flexRender, } from "@tanstack/react-table";
+import { useCellRenderers } from "./cell-renderer-provider.js";
+/**
+ * Controlled, server-driven data grid. All filter/sort/pagination state lives
+ * outside; on-change callbacks fire so the parent re-queries. The component
+ * renders `data` as-is — no client-side sort/paginate/filter row models.
+ *
+ * Cell rendering routes through the CellRendererProvider registry, keyed by
+ * `column.meta.view`. Per-column `cell` always wins if set.
+ */
+export function EntityGrid(props) {
+    const renderers = useCellRenderers();
+    const columns = useMemo(() => {
+        const base = props.columns.map((col) => {
+            if (col.cell)
+                return col;
+            const viewKey = col.meta?.view;
+            const renderer = viewKey ? renderers[viewKey] : undefined;
+            if (!renderer)
+                return col;
+            return { ...col, cell: renderer };
+        });
+        if (props.actions) {
+            base.push({
+                id: "__actions",
+                header: "",
+                cell: ({ row }) => props.actions(row.original),
+            });
+        }
+        return base;
+    }, [props.columns, props.actions, renderers]);
+    const table = useReactTable({
+        data: props.data,
+        columns,
+        rowCount: props.rowCount,
+        state: props.state,
+        onSortingChange: props.onSortingChange,
+        onPaginationChange: props.onPaginationChange,
+        onColumnFiltersChange: props.onColumnFiltersChange,
+        manualSorting: true,
+        manualPagination: true,
+        manualFiltering: true,
+        getCoreRowModel: getCoreRowModel(),
+    });
+    if (!props.isLoading && props.data.length === 0 && props.emptyState) {
+        return _jsx(_Fragment, { children: props.emptyState });
+    }
+    return (_jsxs("div", { children: [props.onSearchChange !== undefined && (_jsx("div", { className: props.searchClassName, children: _jsx("input", { type: "search", placeholder: "Search", value: props.search ?? "", onChange: (e) => props.onSearchChange(e.target.value) }) })), _jsxs("table", { className: props.className, children: [_jsx("thead", { className: props.headerClassName, children: table.getHeaderGroups().map((hg) => (_jsx("tr", { children: hg.headers.map((h) => {
+                                const meta = h.column.columnDef.meta;
+                                const sortable = meta?.sortable !== false && h.column.getCanSort();
+                                const sortDir = h.column.getIsSorted();
+                                return (_jsxs("th", { style: meta?.width ? { width: meta.width } : undefined, onClick: sortable ? h.column.getToggleSortingHandler() : undefined, "aria-sort": sortDir === "asc" ? "ascending" : sortDir === "desc" ? "descending" : "none", children: [flexRender(h.column.columnDef.header, h.getContext()), sortDir === "asc" ? " ↑" : sortDir === "desc" ? " ↓" : ""] }, h.id));
+                            }) }, hg.id))) }), _jsx("tbody", { children: table.getRowModel().rows.map((row) => (_jsx("tr", { className: props.rowClassName, onClick: props.onRowClick ? () => props.onRowClick(row.original) : undefined, style: props.onRowClick ? { cursor: "pointer" } : undefined, children: row.getVisibleCells().map((cell) => (_jsx("td", { className: props.cellClassName, children: flexRender(cell.column.columnDef.cell, cell.getContext()) }, cell.id))) }, row.id))) })] }), table.getPageCount() > 1 && (_jsxs("div", { className: props.paginationClassName, children: [_jsx("button", { onClick: () => table.previousPage(), disabled: !table.getCanPreviousPage(), children: "Prev" }), _jsxs("span", { children: ["Page ", table.getState().pagination.pageIndex + 1, " of ", table.getPageCount()] }), _jsx("button", { onClick: () => table.nextPage(), disabled: !table.getCanNextPage(), children: "Next" })] }))] }));
+}
+//# sourceMappingURL=entity-grid.js.map

package/dist/entity-grid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-grid.js","sourceRoot":"","sources":["../src/entity-grid.tsx"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { EntityFetcherProvider, useEntityFetcher } from "./entity-fetcher.js";
+export type { EntityFetcherProviderProps } from "./entity-fetcher.js";
+export type { EntityFetcher, GridConfig } from "@metaobjectsdev/runtime-web";
+export { defaultCellRenderers, type CellRenderer } from "./cell-renderers.js";
+export { CellRendererProvider, useCellRenderers, type CellRendererProviderProps, } from "./cell-renderer-provider.js";
+export { EntityGrid, type EntityGridProps, type EntityGridState } from "./entity-grid.js";
+export { buildFilterQs } from "@metaobjectsdev/runtime-web";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,YAAY,EAAE,0BAA0B,EAAE,MAAM,qBAAqB,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,yBAAyB,GAC/B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+// Public API surface for @metaobjectsdev/tanstack.
+export { EntityFetcherProvider, useEntityFetcher } from "./entity-fetcher.js";
+export { defaultCellRenderers } from "./cell-renderers.js";
+export { CellRendererProvider, useCellRenderers, } from "./cell-renderer-provider.js";
+export { EntityGrid } from "./entity-grid.js";
+export { buildFilterQs } from "@metaobjectsdev/runtime-web";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG9E,OAAO,EAAE,oBAAoB,EAAqB,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EACL,oBAAoB,EACpB,gBAAgB,GAEjB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,UAAU,EAA8C,MAAM,kBAAkB,CAAC;AAC1F,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@metaobjectsdev/tanstack",
+  "version": "0.5.0-rc.1",
+  "description": "TanStack runtime for metaobjects: EntityFetcherProvider, EntityGrid, default cell renderers.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "src", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "bun test"
+  },
+  "license": "Apache-2.0",
+  "author": "Doug Mealing <doug@dougmealing.com>",
+  "homepage": "https://metaobjects.dev",
+  "bugs": {
+  "url": "https://github.com/metaobjectsdev/metaobjects/issues"
+},
+"repository": {
+  "type": "git",
+  "url": "https://github.com/metaobjectsdev/metaobjects.git",
+  "directory": "client/web/packages/tanstack"
+},
+"keywords": ["metaobjects", "tanstack", "react-query", "react-table", "entity-grid"],
+"publishConfig": {
+"access": "public"
+},
+"dependencies": {
+  "@metaobjectsdev/runtime-web": "0.5.0",
+  "@metaobjectsdev/react": "0.5.0"
+},
+"peerDependencies": {
+  "@tanstack/react-query": ">=5.90.0",
+  "@tanstack/react-table": ">=8.20.0",
+  "react": ">=18.0.0"
+},
+"peerDependenciesMeta": {
+  "@tanstack/react-query": {
+  "optional": true
+},
+"@tanstack/react-table": {
+"optional": true
+},
+"react": {
+"optional": true
+}
+},
+"devDependencies": {
+  "@tanstack/react-query": "^5.90.0",
+  "@tanstack/react-table": "^8.20.0",
+  "@testing-library/react": "^16.0.0",
+  "@testing-library/dom": "^10.0.0",
+  "@types/react": "^19.0.0",
+  "bun-types": "latest",
+  "jsdom": "^29.1.1",
+  "react": "^19.0.0",
+  "react-dom": "^19.0.0",
+  "typescript": "^5.6.0"
+}
+}

package/src/cell-renderer-provider.tsx

@@ -0,0 +1,20 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import { defaultCellRenderers, type CellRenderer } from "./cell-renderers.js";
+
+const CellRendererContext = createContext<Record<string, CellRenderer>>(defaultCellRenderers);
+
+export interface CellRendererProviderProps {
+  /** Overrides merged on top of the inherited renderers. */
+  value: Partial<Record<string, CellRenderer>>;
+  children: ReactNode;
+}
+
+export function CellRendererProvider({ value, children }: CellRendererProviderProps) {
+  const inherited = useContext(CellRendererContext);
+  const merged = useMemo(() => ({ ...inherited, ...value }), [inherited, value]) as Record<string, CellRenderer>;
+  return <CellRendererContext.Provider value={merged}>{children}</CellRendererContext.Provider>;
+}
+
+export function useCellRenderers(): Record<string, CellRenderer> {
+  return useContext(CellRendererContext);
+}

package/src/cell-renderers.tsx

@@ -0,0 +1,37 @@
+import type { CellContext } from "@tanstack/react-table";
+import type { ReactNode } from "react";
+import { formatCurrency } from "@metaobjectsdev/runtime-web";
+
+export type CellRenderer = (ctx: CellContext<any, any>) => ReactNode;
+
+/**
+ * Default cell renderers keyed by field `view` subtype.
+ * Apps override per-key via <CellRendererProvider>.
+ */
+export const defaultCellRenderers: Record<string, CellRenderer> = {
+  text:     (ctx) => String(ctx.getValue() ?? ""),
+  textarea: (ctx) => String(ctx.getValue() ?? ""),
+  number:   (ctx) => String(ctx.getValue() ?? ""),
+  date:     (ctx) => {
+    const v = ctx.getValue();
+    return v ? new Date(v as string).toLocaleDateString() : "";
+  },
+  datetime: (ctx) => {
+    const v = ctx.getValue();
+    return v ? new Date(v as string).toLocaleString() : "";
+  },
+  boolean:  (ctx) => (ctx.getValue() ? "Yes" : "No"),
+  currency: (ctx) => {
+    const value = ctx.getValue();
+    if (value == null || !Number.isFinite(Number(value))) return "";
+    const meta = (ctx.column.columnDef.meta ?? {}) as { currency?: string; locale?: string };
+    try {
+      return formatCurrency(value as number, meta.currency, meta.locale);
+    } catch {
+      // Invalid currency code or unsupported locale — fall back to raw value
+      return String(value);
+    }
+  },
+  dropdown: (ctx) => String(ctx.getValue() ?? ""),
+  password: () => "•••••",
+};

package/src/entity-fetcher.tsx

@@ -0,0 +1,26 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { EntityFetcher } from "@metaobjectsdev/runtime-web";
+
+const EntityFetcherContext = createContext<EntityFetcher | null>(null);
+
+export interface EntityFetcherProviderProps {
+  value: EntityFetcher;
+  children: ReactNode;
+}
+
+/** Wrap your app (or admin subtree) to supply a fetcher to generated hooks. */
+export function EntityFetcherProvider({ value, children }: EntityFetcherProviderProps) {
+  return <EntityFetcherContext.Provider value={value}>{children}</EntityFetcherContext.Provider>;
+}
+
+/** Reads the fetcher from context. Throws if not provided. */
+export function useEntityFetcher(): EntityFetcher {
+  const fetcher = useContext(EntityFetcherContext);
+  if (!fetcher) {
+    throw new Error(
+      "useEntityFetcher() called outside <EntityFetcherProvider>. " +
+        "Wrap your app (or the relevant subtree) with EntityFetcherProvider value={...}.",
+    );
+  }
+  return fetcher;
+}

package/src/entity-grid.tsx

@@ -0,0 +1,159 @@
+import { useMemo, type ReactNode } from "react";
+import {
+  useReactTable,
+  getCoreRowModel,
+  flexRender,
+  type ColumnDef,
+  type SortingState,
+  type PaginationState,
+  type ColumnFiltersState,
+  type OnChangeFn,
+} from "@tanstack/react-table";
+import type { GridConfig } from "@metaobjectsdev/runtime-web";
+import { useCellRenderers } from "./cell-renderer-provider.js";
+
+export interface EntityGridState {
+  sorting: SortingState;
+  pagination: PaginationState;
+  columnFilters: ColumnFiltersState;
+}
+
+export interface EntityGridProps<T> {
+  columns:  ColumnDef<T>[];
+  grid:     GridConfig;
+  /** The single server page of rows. */
+  data:     T[];
+  /** Total rows matching the filter (server-supplied; drives page count). */
+  rowCount: number;
+  /** Controlled state — owned by the parent / generated grid hook. */
+  state:    EntityGridState;
+  onSortingChange:       OnChangeFn<SortingState>;
+  onPaginationChange:    OnChangeFn<PaginationState>;
+  onColumnFiltersChange: OnChangeFn<ColumnFiltersState>;
+  /** Optional free-text search — input renders iff onSearchChange is supplied. */
+  search?:         string;
+  onSearchChange?: (value: string) => void;
+  isLoading?:  boolean;
+  error?:      Error | null;
+  emptyState?: ReactNode;
+  onRowClick?: (row: T) => void;
+  actions?:    (row: T) => ReactNode;
+  className?:           string;
+  headerClassName?:     string;
+  rowClassName?:        string;
+  cellClassName?:       string;
+  paginationClassName?: string;
+  searchClassName?:     string;
+}
+
+/**
+ * Controlled, server-driven data grid. All filter/sort/pagination state lives
+ * outside; on-change callbacks fire so the parent re-queries. The component
+ * renders `data` as-is — no client-side sort/paginate/filter row models.
+ *
+ * Cell rendering routes through the CellRendererProvider registry, keyed by
+ * `column.meta.view`. Per-column `cell` always wins if set.
+ */
+export function EntityGrid<T extends { id?: number | string }>(
+  props: EntityGridProps<T>,
+): ReactNode {
+  const renderers = useCellRenderers();
+
+  const columns = useMemo<ColumnDef<T>[]>(() => {
+    const base: ColumnDef<T>[] = props.columns.map((col): ColumnDef<T> => {
+      if (col.cell) return col;
+      const viewKey = (col.meta as { view?: string } | undefined)?.view;
+      const renderer = viewKey ? renderers[viewKey] : undefined;
+      if (!renderer) return col;
+      return { ...col, cell: renderer } as ColumnDef<T>;
+    });
+    if (props.actions) {
+      base.push({
+        id: "__actions",
+        header: "",
+        cell: ({ row }) => props.actions!(row.original),
+      });
+    }
+    return base;
+  }, [props.columns, props.actions, renderers]);
+
+  const table = useReactTable<T>({
+    data: props.data,
+    columns,
+    rowCount: props.rowCount,
+    state: props.state,
+    onSortingChange:       props.onSortingChange,
+    onPaginationChange:    props.onPaginationChange,
+    onColumnFiltersChange: props.onColumnFiltersChange,
+    manualSorting:    true,
+    manualPagination: true,
+    manualFiltering:  true,
+    getCoreRowModel:  getCoreRowModel(),
+  });
+
+  if (!props.isLoading && props.data.length === 0 && props.emptyState) {
+    return <>{props.emptyState}</>;
+  }
+
+  return (
+    <div>
+      {props.onSearchChange !== undefined && (
+        <div className={props.searchClassName}>
+          <input
+            type="search"
+            placeholder="Search"
+            value={props.search ?? ""}
+            onChange={(e) => props.onSearchChange!(e.target.value)}
+          />
+        </div>
+      )}
+      <table className={props.className}>
+        <thead className={props.headerClassName}>
+          {table.getHeaderGroups().map((hg) => (
+            <tr key={hg.id}>
+              {hg.headers.map((h) => {
+                const meta = h.column.columnDef.meta as { sortable?: boolean; width?: number } | undefined;
+                const sortable = meta?.sortable !== false && h.column.getCanSort();
+                const sortDir = h.column.getIsSorted();
+                return (
+                  <th
+                    key={h.id}
+                    style={meta?.width ? { width: meta.width } : undefined}
+                    onClick={sortable ? h.column.getToggleSortingHandler() : undefined}
+                    aria-sort={sortDir === "asc" ? "ascending" : sortDir === "desc" ? "descending" : "none"}
+                  >
+                    {flexRender(h.column.columnDef.header, h.getContext())}
+                    {sortDir === "asc" ? " ↑" : sortDir === "desc" ? " ↓" : ""}
+                  </th>
+                );
+              })}
+            </tr>
+          ))}
+        </thead>
+        <tbody>
+          {table.getRowModel().rows.map((row) => (
+            <tr
+              key={row.id}
+              className={props.rowClassName}
+              onClick={props.onRowClick ? () => props.onRowClick!(row.original) : undefined}
+              style={props.onRowClick ? { cursor: "pointer" } : undefined}
+            >
+              {row.getVisibleCells().map((cell) => (
+                <td key={cell.id} className={props.cellClassName}>
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </td>
+              ))}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+      {table.getPageCount() > 1 && (
+        <div className={props.paginationClassName}>
+          <button onClick={() => table.previousPage()} disabled={!table.getCanPreviousPage()}>Prev</button>
+          <span>Page {table.getState().pagination.pageIndex + 1} of {table.getPageCount()}</span>
+          <button onClick={() => table.nextPage()} disabled={!table.getCanNextPage()}>Next</button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// Public API surface for @metaobjectsdev/tanstack.
+export { EntityFetcherProvider, useEntityFetcher } from "./entity-fetcher.js";
+export type { EntityFetcherProviderProps } from "./entity-fetcher.js";
+export type { EntityFetcher, GridConfig } from "@metaobjectsdev/runtime-web";
+export { defaultCellRenderers, type CellRenderer } from "./cell-renderers.js";
+export {
+  CellRendererProvider,
+  useCellRenderers,
+  type CellRendererProviderProps,
+} from "./cell-renderer-provider.js";
+export { EntityGrid, type EntityGridProps, type EntityGridState } from "./entity-grid.js";
+export { buildFilterQs } from "@metaobjectsdev/runtime-web";