@rsc-kit/press 0.0.0-stage → 0.30.42

package/dist/resource.d.ts

@@ -0,0 +1,320 @@
+/**
+ * A resource, described once: what its table shows, what its form takes, and
+ * where its rows come from. The panel renders every page from this - nothing
+ * per resource is written as a page.
+ *
+ * The form is a schema, not a list of widgets: the same object validates the
+ * save on the server and is read for the fields it has, so a field cannot be
+ * on the form and missing from the check, or the other way round. Any
+ * Standard Schema validates; one that also describes itself as JSON Schema
+ * (Standard JSON Schema - zod 4.2+, and others as they add it) gives its
+ * fields too, and any other says them in `fields`.
+ */
+import type { ComponentType, ReactNode } from 'react';
+import type { StandardSchemaV1 } from '@rsc-kit/core/standardSchema';
+import type { Storage } from './uploads.js';
+/** What the form validates with: any Standard Schema - zod, valibot, arktype, effect. */
+export type FormSchema = StandardSchemaV1<any, Record<string, unknown>>;
+/** What a schema's save hands the data source. */
+export type ValuesOf<Schema extends FormSchema> = NonNullable<Schema['~standard']['types']>['output'];
+export type Format = 'text' | 'money' | 'badge' | 'boolean' | 'date' | 'relation';
+export interface Column {
+    key: string;
+    label: string;
+    format: Format;
+    sortable: boolean;
+    searchable: boolean;
+    /** Shown until the visitor hides it from the Columns menu. */
+    visible: boolean;
+    /** Draws the cell instead of the format. Runs on the server, so it may be async and read anything. */
+    cell?: (value: any, row: any) => ReactNode | Promise<ReactNode>;
+    /** For a relation column: the resource whose row the value names, shown by its title. */
+    relation?: string;
+}
+/** A column, chained: text('name').searchable().sortable(). */
+export declare class ColumnBuilder {
+    #private;
+    constructor(column: Column);
+    sortable(): this;
+    searchable(): this;
+    label(label: string): this;
+    /** In the Columns menu, unticked until the visitor shows it. */
+    hidden(): this;
+    /** Draw the cell yourself: .cell((value, row) => <Avatar src={row.photo} />). */
+    cell(render: NonNullable<Column['cell']>): this;
+    build(): Column;
+}
+/** The column helpers, typed to the row so a misspelt key fails the typecheck. */
+export interface Columns<Row> {
+    text(key: keyof Row & string): ColumnBuilder;
+    money(key: keyof Row & string): ColumnBuilder;
+    badge(key: keyof Row & string): ColumnBuilder;
+    boolean(key: keyof Row & string): ColumnBuilder;
+    date(key: keyof Row & string): ColumnBuilder;
+    /**
+     * A belongsTo: the value is another resource's key, shown as that row's
+     * title - col.relation('categoryId', 'categories') shows "Lighting", not 3.
+     */
+    relation(key: keyof Row & string, resource: string): ColumnBuilder;
+}
+export type FieldType = 'text' | 'textarea' | 'number' | 'select' | 'toggle' | 'email' | 'date' | 'blocks' | 'file' | 'image';
+/** A kind of block a blocks field offers, as the form needs it: plain data. */
+export interface BlockSpec {
+    name: string;
+    label: string;
+    fields: Field[];
+}
+/** One choice of a select: what is saved, and what the visitor reads. */
+export interface Option {
+    value: string;
+    label: string;
+}
+/** What the form renders. Plain data: it crosses to the client component. */
+export interface Field {
+    name: string;
+    label: string;
+    type: FieldType;
+    required: boolean;
+    options?: Option[];
+    /**
+     * A belongsTo: the options are another resource's rows, its key saved and
+     * its title shown, read when the form is drawn and scoped to the tenant.
+     */
+    relation?: string;
+    /** A select whose schema wants a number: its value is converted, as a number field's is. */
+    numeric?: boolean;
+    /** Help under the control. */
+    description?: string;
+    /**
+     * What the browser checks before a submit, from the schema: the native
+     * constraints, so a mistake is caught without a round trip and without the
+     * schema in the browser. A courtesy only - the server validates every save.
+     */
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    /** Whole-value, as the pattern attribute matches. */
+    pattern?: string;
+    step?: number | 'any';
+    /**
+     * A blocks field's kinds of block. Its value is a list of { type, data },
+     * each block's data checked by its own schema; in a form, block i's field
+     * is named `name.i.field`, which is also where its errors are.
+     */
+    blocks?: BlockSpec[];
+    /**
+     * A file or image field's types, as the accept attribute says them:
+     * `image/*`, `application/pdf`, `.csv`. Checked by the browser when the
+     * file is chosen and by the server when it arrives.
+     */
+    accept?: string;
+    /** A file or image field's largest file, in bytes. */
+    maxSize?: number;
+    /** The schema allows null: a file field that is emptied saves null, so the source clears it. */
+    nullable?: boolean;
+}
+export interface Filter {
+    key: string;
+    label: string;
+    options: Option[];
+}
+export interface ListQuery {
+    q?: string;
+    sort?: string;
+    dir: 'asc' | 'desc';
+    page: number;
+    /**
+     * Null asks for every row: a resource whose table works in the browser
+     * (mode: 'client') is loaded whole, and searched, sorted and paged there.
+     */
+    perPage: number | null;
+    /** Only the resource's declared filters, each with a value. */
+    filters: Record<string, string>;
+    /** The columns marked searchable: what q is matched against. */
+    searchable: string[];
+}
+/** Whoever's records these are, in a panel with tenants. */
+export interface Tenant {
+    id: string;
+    name: string;
+    /** A second line under the name in the switcher: a plan, a role. */
+    description?: string;
+    /** An image url for the switcher. Without one the first letter is shown. */
+    avatar?: string;
+}
+/** What every call to a data source is told besides its arguments. */
+export interface SourceContext {
+    /** The tenant the visitor is working in, or null in a panel without tenants. */
+    tenant: Tenant | null;
+}
+/**
+ * Where a resource's rows live: five functions, and nothing about how. A
+ * database (Drizzle, Prisma, SQL), a REST or GraphQL API, a Laravel app through
+ * rpc(), a file, memory - the panel calls these and never anything else.
+ *
+ * In a panel with tenants, a source answers only for context.tenant. find()
+ * returning null for another tenant's record is what makes its url a 404.
+ */
+export interface DataSource<Row, Values> {
+    list(query: ListQuery, context: SourceContext): Promise<{
+        rows: Row[];
+        total: number;
+    }>;
+    find(id: string, context: SourceContext): Promise<Row | null>;
+    create(values: Values, context: SourceContext): Promise<Row>;
+    update(id: string, values: Values, context: SourceContext): Promise<Row>;
+    delete(id: string, context: SourceContext): Promise<void>;
+}
+/**
+ * Where a table's search, filters, sort and paging happen.
+ *
+ *   'server'  each change is a request; the source is asked for one page.
+ *             For a table that grows: orders, users, an API with millions.
+ *   'client'  the source is asked once for every row (perPage: null) and the
+ *             browser does the rest, with no request per keystroke. For a
+ *             table that stays small: categories, settings, team members.
+ */
+export type TableMode = 'server' | 'client';
+/**
+ * Something done to the rows ticked in the table: publish, archive, export.
+ * `run` is given the rows themselves, each found by the source as the
+ * visitor - an id the browser sent that is not theirs never reaches it.
+ */
+export interface BulkAction<Row = any> {
+    /** Identifies it in the call; 'delete' is the panel's own. */
+    name: string;
+    label: string;
+    /** Asked about first, as a delete is. */
+    destructive?: boolean;
+    /** What happened to the rows, for the toast: 'published' says "3 products published.", as Delete says "deleted". */
+    done?: string;
+    /** Returns its own words for the toast, or leaves them to `done`. */
+    run: (rows: Row[], context: SourceContext) => void | string | Promise<void | string>;
+}
+export interface Resource<Row = any, Schema extends FormSchema = FormSchema> {
+    name: string;
+    label: string;
+    singular: string;
+    key: keyof Row & string;
+    title: keyof Row & string;
+    source: DataSource<Row, ValuesOf<Schema>>;
+    columns: Column[];
+    filters: Filter[];
+    schema: Schema;
+    fields: Field[];
+    perPage: number;
+    mode: TableMode;
+    /** Listed and searched, never created, edited or deleted from the panel. */
+    readOnly: boolean;
+    bulkActions: BulkAction<Row>[];
+    /** The sidebar's icon: a lucide icon, or any component. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    description?: string;
+}
+export interface ResourceDefinition<Row, Schema extends FormSchema> {
+    /** The url segment: /admin/products. */
+    name: string;
+    label?: string;
+    singular?: string;
+    /** The field that identifies a row in the url. */
+    key: keyof Row & string;
+    /** The field an edit page's heading shows. */
+    title: keyof Row & string;
+    source: DataSource<Row, ValuesOf<Schema>>;
+    table: (col: Columns<Row>) => ColumnBuilder[];
+    /** Enum fields of the form, offered as a select above the table. */
+    filters?: (keyof Row & string)[];
+    /** Any Standard Schema of an object: z.object(), v.object(), type({...}). */
+    form: Schema;
+    /**
+     * What the schema cannot say: a long string is a textarea, a label, help.
+     * The whole list, for a schema that does not describe itself as JSON
+     * Schema - a field missing here is then missing from the form.
+     */
+    fields?: Partial<Record<keyof ValuesOf<Schema> & string, FieldOverride>>;
+    perPage?: number;
+    /** Where search, filters, sort and paging happen. 'server' unless said. */
+    mode?: TableMode;
+    /** Listed and searched, never created, edited or deleted from the panel: a log, a feed, a plugin's own records. */
+    readOnly?: boolean;
+    /** Offered when rows are ticked, beside the panel's own Delete. */
+    bulkActions?: BulkAction<Row>[];
+    /** The sidebar's icon: import { Package } from 'lucide-react'. */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Under the page's heading. */
+    description?: string;
+}
+/**
+ * Two calls so the row is named and the schema is inferred:
+ * defineResource<Product>()({ ... }).
+ */
+export declare function defineResource<Row>(): <Schema extends FormSchema>(definition: ResourceDefinition<Row, Schema>) => Resource<Row, Schema>;
+/** A field as the app says it, over what the schema said. */
+export type FieldOverride = Partial<Pick<Field, 'type' | 'label' | 'description' | 'required' | 'relation'>> & {
+    /** A bare value is labelled by humanizing it: 'in_stock' reads "In stock". */
+    options?: (string | Option)[];
+    /** The kinds a blocks field offers: { type: 'blocks', blocks: [hero, features] }. */
+    blocks?: BlockLike[];
+    /** Where a file or image field keeps what is uploaded. Required for one. */
+    storage?: Storage;
+    /** A file or image field's types. An image field takes PNG, JPEG, WebP, GIF and AVIF unless it says. */
+    accept?: string;
+    /** A file or image field's largest file, in bytes. */
+    maxSize?: number;
+};
+/** What a blocks field needs of a block: its name, label, fields and schema. */
+interface BlockLike {
+    name: string;
+    label: string;
+    fields: Field[];
+    schema: FormSchema;
+}
+type Overrides = Record<string, FieldOverride | undefined>;
+/**
+ * The fields a schema describes: the type of each property, whether it is
+ * required, an enum's options. From its JSON Schema when it has one; from
+ * `overrides` alone when it does not, which must then list every field.
+ */
+export declare function fieldsOf(schema: FormSchema, overrides?: Overrides): Field[];
+/**
+ * A submitted form's values as the schema expects them, by its fields: a
+ * resource's, a public form's, a block's. A checkbox that is off is not in
+ * FormData at all, so a toggle is whether its name arrived; an empty optional
+ * field is left out rather than sent as "".
+ */
+export declare function valuesFrom(target: {
+    fields: Field[];
+}, form: FormData): Record<string, unknown>;
+export type Parsed<Values> = {
+    ok: true;
+    values: Values;
+} | {
+    ok: false;
+    errors: Record<string, string[]>;
+};
+export interface ParseOptions {
+    /** The record being edited, as it was: the values a file field may keep without uploading again. */
+    current?: Record<string, unknown> | null;
+    /** Handed to storage with each upload. */
+    tenant?: Tenant | null;
+}
+/**
+ * A submitted form checked against its schema, with each refusal under its
+ * field. Uploads are kept last: the form is checked with them still files,
+ * and only when nothing else is wrong is each one stored and the form
+ * checked again with what storage answered - so a refused save leaves no
+ * file behind.
+ */
+export declare function parse<Schema extends FormSchema>(target: {
+    schema: Schema;
+    fields: Field[];
+}, form: FormData, options?: ParseOptions): Promise<Parsed<ValuesOf<Schema>>>;
+export declare function humanize(key: string): string;
+/** What a bulk action's toast says: "3 products published." with `done`, else "Publish: 3 products.". */
+export declare function bulkToast(bulk: Pick<BulkAction, 'label' | 'done'>, count: number, noun: string): string;
+export {};