ra-steward 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 catdarick
+
+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,96 @@
-# Temporary Holding Version
+# ra-steward
 
-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.
+Pages, tables, forms and actions for [React Admin](https://marmelab.com/react-admin/),
+described by a steward backend. Add it to an existing admin alongside your own resources.
+
+## Install
+
+```sh
+npm install ra-steward react-admin react react-dom @mui/material @mui/icons-material \
+  @emotion/react @emotion/styled @tanstack/react-query react-router-dom react-hook-form
+```
+
+Use React Admin 5.15+, React 18 or 19, MUI 7 or 9, React Router 6.28.1+ or 7,
+TanStack Query 5 and React Hook Form 7.66+. Keep a single compatible installation of each
+peer so the library shares the host's contexts. The package contains ESM JavaScript and
+TypeScript declarations; no TypeScript or JSX compilation of the library is needed.
+It targets ES2022 and is intended for React apps using a bundler, such as Vite or webpack.
+
+## A standalone admin
+
+```tsx
+import { Admin, CustomRoutes } from "react-admin";
+import { createSteward } from "ra-steward";
+
+// Create once, outside the component, to keep contexts and version state stable.
+const steward = createSteward({ baseUrl: "/admin" });
+
+export const App = () => (
+  <Admin dataProvider={steward.dataProvider} layout={steward.Layout}>
+    <CustomRoutes>{steward.routes}</CustomRoutes>
+  </Admin>
+);
+```
+
+The default routes are `/s/:service/:page` and `/s/:service/:page/:key`. Use
+`routePrefix` to place them elsewhere. `baseUrl` points at the backend's service root,
+not the frontend route. A development proxy or your server must route that path to steward.
+
+## An existing React Admin app
+
+```tsx
+import {
+  Admin, combineDataProviders, CustomRoutes, Layout, Menu, Resource,
+  type LayoutProps,
+} from "react-admin";
+import { createSteward, StewardMenuItems, StewardPanel } from "ra-steward";
+import { authProvider, hostDataProvider, PostList, readToken } from "./host";
+
+const steward = createSteward({
+  baseUrl: "/admin",
+  routePrefix: "/services",
+  headers: () => ({ Authorization: `Bearer ${readToken()}` }),
+});
+
+const dataProvider = combineDataProviders(resource =>
+  resource === "posts" ? hostDataProvider : steward.dataProvider
+);
+
+const HostMenu = () => (
+  <Menu>
+    <Menu.ResourceItem name="posts" />
+    <StewardMenuItems />
+  </Menu>
+);
+
+const HostLayout = (props: LayoutProps) => (
+  <steward.Provider>
+    <Layout {...props} menu={HostMenu} />
+    <StewardPanel />
+  </steward.Provider>
+);
+
+export const App = () => (
+  <Admin dataProvider={dataProvider} authProvider={authProvider} layout={HostLayout}>
+    <Resource name="posts" list={PostList} />
+    <CustomRoutes>{steward.routes}</CustomRoutes>
+  </Admin>
+);
+```
+
+The host owns authentication, theme, query client and routing. `headers` is called for each
+request so it can read the current token. `StewardMenuItems` adds service navigation;
+`StewardPanel` handles record previews and action navigation. Every steward data-provider
+request carries its location in `meta.steward`; select providers so steward resources reach
+`steward.dataProvider`.
+
+For custom widgets and cells, pass `components` and `cells` to `createSteward`. Their props
+are described by the exported `WidgetComponent` and `CellComponent` types. `services`
+optionally limits the services shown; otherwise the backend supplies the list. Protocol
+types, `StewardClient`, `StewardPage`, `StewardTable`, navigation hooks and row metadata
+helpers are also exported from `ra-steward`.
+
+Steward's backend `docs/protocol.md` defines the HTTP contract. The backend must provide
+the describe, page, widget, picker and action endpoints used by its pages. Browser apps
+using an absolute backend URL also need the backend's CORS configuration to allow the
+frontend origin and authentication headers.

package/dist/actions.d.ts

@@ -0,0 +1,38 @@
+import { type ReactNode } from "react";
+import { type RaRecord } from "react-admin";
+import type { ActionDesc, ActionStates, ButtonDesc, FormErrors, Width } from "./protocol.js";
+/** Where a button stands: on the record of its page, in a row, or in a toolbar of no record. */
+export type Origin = "page" | "row" | "toolbar";
+/** Runs an action and what its answer says; resolves to the errors of the form when it is invalid. */
+export declare const useRunAction: (origin: Origin) => (service: string, action: string, key: string | null | undefined, payload: unknown) => Promise<FormErrors | undefined>;
+/** A button of an action or a link, as the server described it, in its place. */
+export declare const ActionButton: ({ service, button, record, states, origin, size, }: {
+    service: string;
+    button: ButtonDesc;
+    record?: RaRecord;
+    states?: ActionStates;
+    origin: Origin;
+    size?: "small" | "medium";
+}) => import("react").JSX.Element | null;
+/** The dialog of a form: the one thing that opens over the panel, for doing, not for looking. */
+export declare const FormDialog: ({ width, title, onClose, children }: {
+    width: Width;
+    title: ReactNode;
+    onClose: () => void;
+    children: ReactNode;
+}) => import("react").JSX.Element;
+/** The form of an action, with its initial values; the server's errors go next to the inputs. */
+export declare const ActionForm: ({ service, action, label, recordKey, width, origin, onClose, }: {
+    service: string;
+    action: ActionDesc;
+    label: string;
+    recordKey: string | null;
+    width: Width;
+    origin: Origin;
+    onClose: () => void;
+}) => import("react").JSX.Element;
+export declare const SubmitAction: ({ label, icon, busy }: {
+    label: string;
+    icon?: string;
+    busy: boolean;
+}) => import("react").JSX.Element;

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+import type { FormErrors } from "./protocol.js";
+export interface ClientOptions {
+    /** The base path of the services: "/admin". */
+    baseUrl: string;
+    /** Headers of every request: the user's token, for one. */
+    headers?: () => Record<string, string>;
+    /** Called with the version every answer carries, to read describe again when it changes. */
+    onVersion?: (service: string, version: string) => void;
+}
+/** An answer that is not a success: its status, its message and, for 422, the errors of fields. */
+export declare class StewardError extends Error {
+    readonly status: number;
+    readonly errors?: FormErrors | undefined;
+    constructor(status: number, message: string, errors?: FormErrors | undefined);
+}
+export type Query = Record<string, string | number | undefined | null>;
+/** Requests to the services. */
+export declare class StewardClient {
+    readonly options: ClientOptions;
+    constructor(options: ClientOptions);
+    url(service: string | null, path: string[], query?: Query): string;
+    request<T>(service: string | null, path: string[], init?: {
+        query?: Query;
+        body?: unknown;
+        method?: string;
+    }): Promise<T>;
+    /** A request with the headers of the options; the version of the answer is reported. */
+    fetch(url: string, init?: RequestInit): Promise<Response>;
+    private serviceOf;
+    /** Downloads a file an action produced and gives it to the user to save. */
+    download(url: string, filename: string): Promise<void>;
+}

package/dist/context.d.ts

@@ -0,0 +1,102 @@
+import { type ComponentType, type ReactNode } from "react";
+import { type RaRecord } from "react-admin";
+import type { StewardClient } from "./client.js";
+import { type PageRef } from "./peek.js";
+import type { Describe, Target } from "./protocol.js";
+export { parsePeek, PEEK, withPeek, type PageRef } from "./peek.js";
+/** A component of the admin's registry drawing a widget: given the data the server loads for it. */
+export type WidgetComponent = ComponentType<{
+    data: unknown;
+    record?: RaRecord;
+}>;
+/** A component of the admin's registry drawing a value: given the value and the props of its kind. */
+export type CellComponent = ComponentType<{
+    value: unknown;
+    props: unknown;
+    record: RaRecord;
+}>;
+export interface StewardConfig {
+    /** The base path of the services: "/admin". */
+    baseUrl: string;
+    /** Headers of every request. */
+    headers?: () => Record<string, string>;
+    /** The services shown; by default those the server names. */
+    services?: string[];
+    /** The widgets of the admin's registry (`component @"SalesChart"`), by name. */
+    components?: Record<string, WidgetComponent>;
+    /** The cells of the admin's registry (`customKind @"MapPoint"`), by name. */
+    cells?: Record<string, CellComponent>;
+    /** The routes of the pages: `${routePrefix}/:service/:page/:key?`; "/s" by default. */
+    routePrefix?: string;
+}
+/** The version of describe each answer carries, by service. */
+export declare class Versions {
+    private versions;
+    private listeners;
+    set(service: string, version: string): void;
+    get: (service: string) => string | undefined;
+    subscribe: (l: () => void) => () => boolean;
+}
+interface StewardValue {
+    config: StewardConfig;
+    client: StewardClient;
+    versions: Versions;
+}
+export declare const StewardProvider: ({ config, client, versions, children }: {
+    config: StewardConfig;
+    client: StewardClient;
+    versions: Versions;
+    children: ReactNode;
+}) => import("react").JSX.Element;
+export declare const useSteward: () => StewardValue;
+export declare const describeKey: (service: string) => string[];
+/** The describe of a service: read once, and again when an answer carries a newer version. */
+export declare const useDescribe: (service: string) => import("@tanstack/react-query").UseQueryResult<Describe, Error>;
+/** The services shown: those of the config, or those the server names. */
+export declare const useServices: () => string[];
+export declare const pagePath: (prefix: string, service: string, page: string, key?: string | null) => string;
+/** The place a page is shown in: its service, page and key, whether in the panel, how to close it. */
+export interface PagePlace {
+    service: string;
+    page: string;
+    key: string | null;
+    inPanel: boolean;
+    close: () => void;
+}
+export declare const PagePlaceContext: import("react").Context<PagePlace | null>;
+export declare const usePagePlace: () => PagePlace | null;
+/** The URL of a route of the app, for a link or a new tab: with the hash of a hash router. */
+export declare const routeHref: (path: string) => string;
+/** Whether a click asks for a new tab: with Ctrl, Cmd or Shift, or with the middle button. */
+export declare const wantsNewTab: (e: {
+    ctrlKey: boolean;
+    metaKey: boolean;
+    shiftKey: boolean;
+    button: number;
+}) => boolean;
+/**
+ * The panel over the page: the pages it has opened, the last one shown, and its moves. Its pages
+ * are in the URL, so the browser's Back goes back in it and a reload keeps it; the history entry
+ * tells how many of its pages were opened by entries of their own, which its Back and close undo.
+ */
+export declare const usePanel: () => {
+    pages: PageRef[];
+    /** Opens the panel on a page: from the page under it. */
+    open: (page: PageRef) => void;
+    /** Opens a page in the panel, after the one shown: from the panel. */
+    push: (page: PageRef) => void;
+    /** Back to the page before in the panel, or closes it when there is none. */
+    back: () => void;
+    close: () => void;
+    /** Opens the page shown as a page of its own, closing the panel. */
+    expand: () => void;
+};
+/**
+ * Opens a page from a link, a row, a button or an action's result: always in the panel — after the
+ * page shown when it is opened from the panel. Only the menu opens pages in place.
+ */
+export declare const useOpenPage: () => (service: string, page: string, key: string | null) => void;
+/** The URL of a page, for a link or a new tab. */
+export declare const usePageHref: () => (service: string, page: string, key: string | null) => string;
+/** The key a target opens, from the record of its place. */
+export declare const targetKey: (target: Target, record?: RaRecord) => string | null;

package/dist/dataProvider.d.ts

@@ -0,0 +1,41 @@
+import type { DataProvider, RaRecord } from "react-admin";
+import type { StewardClient } from "./client.js";
+import type { ActionStates, RowMeta } from "./protocol.js";
+/**
+ * Where a list or a record comes from, passed as React Admin's `meta`: every answer is the
+ * projection of one place of a page.
+ */
+export type Place = {
+    service: string;
+    widget: string;
+    of?: string;
+} | {
+    service: string;
+    widget: string;
+    filterOptions: string;
+} | {
+    service: string;
+    picker: {
+        action: string;
+        field: string;
+        key?: string;
+    };
+} | {
+    service: string;
+    page: string;
+};
+/** The meta of a row, kept in the record under this key (no field of a model is named so). */
+export declare const ROW_META = "__steward";
+/** The meta of the record of a record page: its actions, title, global actions and cards. */
+export interface PageRecordMeta extends RowMeta {
+    toolbar?: ActionStates;
+    cards?: Record<string, RowMeta>;
+}
+export declare const rowMeta: (record: RaRecord | undefined) => PageRecordMeta;
+/**
+ * The data provider of steward services. Every call names the place it is for in `meta.steward`:
+ * a table (`{service, widget}`), a related table (`of`), a picker of a form, the options of a
+ * reference filter, or a record page (`{service, page}`). Creating, changing and deleting are
+ * actions.
+ */
+export declare const stewardDataProvider: (client: StewardClient) => DataProvider;

package/dist/feedback.d.ts

@@ -0,0 +1,4 @@
+export declare const QueryError: ({ error, retry }: {
+    error: unknown;
+    retry: () => unknown;
+}) => import("react").JSX.Element;

package/dist/forms.d.ts

@@ -0,0 +1,9 @@
+import type { ActionDesc, FormFieldDesc } from "./protocol.js";
+/** The inputs of the fields of a form (or of a record embedded in it, under @prefix@). */
+export declare const FormInputs: ({ service, action, recordKey, fields, prefix, }: {
+    service: string;
+    action: ActionDesc;
+    recordKey: string | null;
+    fields: FormFieldDesc[];
+    prefix: string;
+}) => import("react").JSX.Element;

package/dist/icons.generated.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentType } from "react";
+import type { SvgIconProps } from "@mui/material";
+type Loader = () => Promise<{
+    default: ComponentType<SvgIconProps>;
+}>;
+export declare const iconLoaders: Record<string, Loader>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from "react";
+import type { DataProvider, LayoutProps } from "react-admin";
+import { StewardClient } from "./client.js";
+import { type StewardConfig } from "./context.js";
+export interface Steward {
+    client: StewardClient;
+    /** The data provider of the services; combine it with the admin's own for other resources. */
+    dataProvider: DataProvider;
+    /** React Admin's layout with the services' menu; or wrap a layout of the admin's own in Provider. */
+    Layout: (props: LayoutProps) => ReactNode;
+    /** Gives the components of the services their context, around a layout of the admin's own. */
+    Provider: (props: {
+        children: ReactNode;
+    }) => ReactNode;
+    /** The routes of the pages, for `<CustomRoutes>`. */
+    routes: ReactNode;
+}
+/**
+ * The frontend of steward services for a React Admin app:
+ *
+ *     const steward = createSteward({ baseUrl: "/admin", components: { SalesChart } });
+ *
+ *     <Admin dataProvider={steward.dataProvider} layout={steward.Layout}>
+ *       <CustomRoutes>{steward.routes}</CustomRoutes>
+ *     </Admin>
+ */
+export declare const createSteward: (config: StewardConfig) => Steward;
+export { StewardClient, StewardError, type ClientOptions, type Query } from "./client.js";
+export { pagePath, parsePeek, PEEK, useDescribe, useOpenPage, usePanel, useServices, useSteward, withPeek, type CellComponent, type PageRef, type StewardConfig, type WidgetComponent } from "./context.js";
+export { ROW_META, rowMeta, stewardDataProvider, type PageRecordMeta, type Place } from "./dataProvider.js";
+export { StewardMenu, StewardMenuItems, StewardPanel } from "./layout.js";
+export { StewardPage } from "./page.js";
+export type * from "./protocol.js";
+export { StewardTable } from "./table.js";
+export { Icon } from "./values.js";