@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/screen/index.d.ts

@@ -0,0 +1,496 @@
+import { builtInScreenKinds, registryCells, registryControls } from './client.ts';
+import { type Localized, type LocalesOf, type ResolvedKayan, type RuntimeField } from '../mithaq/types.ts';
+import { defaultKinds } from '../base/kinds.ts';
+import { type Where } from '../mithaq/where.ts';
+/** What one kind is drawn by on a screen: its form control and its list cell, each a name or a `ui()` reference. */
+export type ScreenKind = {
+    readonly cell: string | Ui;
+    readonly control: string | Ui;
+};
+/** What the shipped registry draws each shipped kind with. A screen's `controls` spreads it and adds or rewrites rows. */
+export declare const screenKinds: {
+    readonly text: {
+        cell: "text";
+        control: "text";
+    };
+    readonly email: {
+        cell: "email";
+        control: "email";
+    };
+    readonly number: {
+        cell: "number";
+        control: "number";
+    };
+    readonly integer: {
+        cell: "integer";
+        control: "integer";
+    };
+    readonly decimal: {
+        cell: "decimal";
+        control: "decimal";
+    };
+    readonly checkbox: {
+        cell: "checkbox";
+        control: "checkbox";
+    };
+    readonly datetime: {
+        cell: "datetime";
+        control: "datetime";
+    };
+    readonly date: {
+        cell: "date";
+        control: "date";
+    };
+    readonly textArray: {
+        cell: "textArray";
+        control: "textArray";
+    };
+    readonly uuid: {
+        cell: "uuid";
+        control: "uuid";
+    };
+    readonly relationship: {
+        cell: "relationship";
+        control: "relationship";
+    };
+    readonly json: {
+        cell: "json";
+        control: "json";
+    };
+    readonly join: {
+        cell: "join";
+        control: "join";
+    };
+};
+type OwnScreenNames<Kinds> = {
+    [Name in keyof Kinds]: Kinds[Name] extends {
+        targets: {
+            screen: {
+                control: infer Control;
+                cell: infer Cell;
+            };
+        };
+    } ? Extract<Control, (typeof registryControls)[number]> | Extract<Cell, (typeof registryCells)[number]> : never;
+}[keyof Kinds];
+declare const uiBrand: unique symbol;
+/** One export of one file, as a URL whose hash is the export's name: `ui('dashboard.tsx#Dashboard')`. */
+export type Ui<Path extends string = string> = URL & {
+    readonly [uiBrand]: Path;
+};
+/**
+ * The folder a project's screen files sit in, handed back as `ui`:
+ * `const ui = folderOf(new URL('./ui-dashboard/', import.meta.url))`. A missing file or export fails the build.
+ */
+export declare const folderOf: (folder: URL) => <const Path extends `${string}#${string}`>(path: Path) => Ui<Path>;
+/** A component named where a screen draws one: a name the screen registered, a bare built-in the registry ships, or a `ui()` reference. */
+export type ScreenRef<Registered extends string = string> = Registered | Ui;
+/** A page of the screen's own, which belongs to no kayan: one component drawing the whole page. */
+export type ScreenOwnPage<Locale extends string = string, Ref extends string | Ui = string | Ui> = {
+    readonly path: string;
+    readonly component: Ref;
+    /** A nav entry for this page, under this label. */
+    readonly nav?: {
+        readonly label: Localized<Locale>;
+    };
+    /** The catalog key an actor needs for the nav to list this page. */
+    readonly permission?: string;
+};
+/** The screen as a target, `capability: 'screen'`. */
+export type ScreenTarget<Controls extends Record<string, ScreenKind> = Record<string, ScreenKind>, Layouts extends Record<string, Ui> = Record<string, Ui>, Components extends Record<string, Ui> = Record<string, Ui>> = {
+    readonly capability: 'screen';
+    readonly type: 'screen';
+    /** Where the screen mounts. */
+    readonly path: string;
+    /** Every kayan the screen draws, by name. A kayan it does not list writes no `targets.<screen>`. */
+    readonly kayan: readonly string[];
+    /** One row per kind of the language: what draws its value in a form and in a list. */
+    readonly controls: Controls;
+    /** Outermost first, each handed `{ children }`. */
+    readonly providers: readonly ScreenRef<keyof Components & string>[];
+    /** The pages that belong to no kayan, each drawn whole by one component. One of them is at `/`. */
+    readonly pages: Readonly<Record<string, ScreenOwnPage<string, ScreenRef<keyof Components & string>>>>;
+    /** The shells and layouts a page tree names, by a short name. */
+    readonly layouts: Layouts;
+    /** The components a page names, by a short name. */
+    readonly components: Components;
+};
+export declare const screenTarget: <const Controls extends Record<string, ScreenKind>, const Layouts extends Record<string, Ui>, const Components extends Record<string, Ui>>(target: Omit<ScreenTarget<Controls, Layouts, Components>, 'capability' | 'type'>) => ScreenTarget<Controls, Layouts, Components>;
+/** What `targets.<screen>` on a field may say: how it is drawn, never what it holds. */
+export type ScreenField<Ref extends string | Ui = string | Ui> = {
+    readonly component?: Ref;
+    readonly cell?: Ref;
+    readonly width?: string;
+    readonly filter?: true;
+    readonly searchable?: true;
+    readonly sortable?: false;
+};
+/** When a node is drawn: a `Where` over the form's values, the loaded row under `record.` and the access report under `$user.`. */
+export type When = {
+    readonly when?: Where;
+};
+/** A field on one page: its name, or its name with what this page alone draws it with. */
+export type ScreenLeaf<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> = FieldName | ({
+    readonly field: FieldName;
+    readonly component?: Ref;
+    readonly cell?: Ref;
+    readonly placeholder?: Localized<Locale>;
+    readonly description?: Localized<Locale>;
+    readonly readOnly?: boolean;
+    readonly width?: string;
+} & When);
+type ScreenGroup<Locale extends string, Ref extends string | Ui, FieldName extends string> = {
+    readonly label: Localized<Locale>;
+    readonly description?: Localized<Locale>;
+    readonly fields: readonly ScreenNode<Locale, Ref, FieldName>[];
+};
+/** The regions of a shell or a layout, each a list of nodes, by the names its file exports. */
+export interface ScreenRegions<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> {
+    readonly [region: string]: readonly ScreenNode<Locale, Ref, FieldName>[] | Ref | Where | undefined;
+}
+/** A page's tree: a shell by name at its root, whose regions hold nodes. */
+export interface ScreenFrame<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> extends ScreenRegions<Locale, Ref, FieldName> {
+    readonly shell: Ref;
+}
+/** A layout nested in a region, with regions of its own. */
+export interface ScreenLayout<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> extends ScreenRegions<Locale, Ref, FieldName> {
+    readonly layout: Ref;
+    readonly when?: Where;
+}
+/**
+ * One node of a page's region. A layout's regions are keys of its own, so a
+ * walk rules out `layout` before it asks for any other key.
+ */
+export type ScreenNode<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> = ScreenLeaf<Locale, Ref, FieldName> | ({
+    readonly form: readonly ScreenNode<Locale, Ref, FieldName>[];
+    readonly component?: Ref;
+} & When) | ({
+    readonly list: ScreenList<Locale, Ref, FieldName> | (ScreenList<Locale, Ref, string> & {
+        /** Another kayan of the screen, whose rows this list draws, each column one of its fields. */
+        readonly of: string;
+        /** `of`'s relationship holding this page's row, which scopes the list to the rows pointing here. */
+        readonly where: string;
+    });
+    readonly component?: Ref;
+} & When) | ({
+    readonly component: Ref;
+} & When) | ScreenLayout<Locale, Ref, FieldName> | ScreenButton<Locale, Ref> | ({
+    readonly title: Readonly<Record<string, never>>;
+} & When) | ({
+    readonly nav: Readonly<Record<string, never>>;
+} & When)
+/** The form's controls: where the row stands, the last save and the save buttons. */
+ | ({
+    readonly controls: Readonly<Record<string, never>>;
+} & When) | ({
+    readonly row: readonly ScreenNode<Locale, Ref, FieldName>[];
+    readonly resizable?: true;
+} & When) | ({
+    readonly separator: true;
+} & When) | ({
+    readonly section: string;
+    readonly collapsed?: boolean;
+    readonly width?: number;
+    /** A CSS height the section's body scrolls within, shadcn's `scroll-area`. */
+    readonly scroll?: string;
+} & ScreenGroup<Locale, Ref, FieldName> & When) | ({
+    readonly tabs: readonly ({
+        readonly tab: string;
+    } & ScreenGroup<Locale, Ref, FieldName>)[];
+} & When) | ({
+    readonly accordion: readonly ({
+        readonly item: string;
+    } & ScreenGroup<Locale, Ref, FieldName>)[];
+} & When);
+/** A list node's own keys: its columns, what it filters, searches and opens with, and its buttons. */
+export type ScreenList<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> = {
+    readonly columns: readonly ScreenLeaf<Locale, Ref, FieldName>[];
+    readonly filters?: readonly FieldName[];
+    /** The fields a search box runs over: a field of this kayan, or one hop to a text field of a kayan it points at, `userId.email`. */
+    readonly search?: readonly (FieldName | `${FieldName}.${string}`)[];
+    readonly empty?: Ref;
+    /** What each row's menu offers after the list's own items: a component handed the row (`MenuProps`). */
+    readonly menu?: Ref;
+    /** Buttons above the table, which run over no row. */
+    readonly toolbar?: readonly ScreenButton<Locale, Ref>[];
+    /** Buttons over the ticked rows, each an `updateMany` or a `deleteMany`. */
+    readonly bulk?: readonly ScreenButton<Locale, Ref>[];
+    /** Buttons on each row, each an `update` or a `remove` over that row, drawn where its `when` holds. */
+    readonly row?: readonly ScreenButton<Locale, Ref>[];
+    /** The order a list opens in, which the URL's own `sort` overrides. */
+    readonly sort?: FieldName | `-${FieldName}`;
+    /** The page size a list opens with, which the URL's own `limit` overrides. */
+    readonly limit?: number;
+    /** The list's tabs, each a `where` it holds every page to; the first is the one it opens on. */
+    readonly tabs?: readonly {
+        readonly tab: string;
+        readonly label: Localized<Locale>;
+        readonly where?: Where;
+    }[];
+};
+/** A button that runs one of the kayan's operations, wherever it sits: `button` names the operation. */
+export type ScreenButton<Locale extends string = string, Ref extends string | Ui = string | Ui> = {
+    readonly button: string;
+    readonly label: Localized<Locale>;
+    readonly fields?: readonly string[];
+    readonly reload?: boolean;
+    readonly component?: Ref;
+    /** What the button asks before it runs. */
+    readonly confirm?: {
+        readonly title: Localized<Locale>;
+        readonly body: Localized<Locale>;
+    };
+    readonly when?: Where;
+};
+/** One page: `list`, `create` and `edit` by name, any other name a custom page. Declared as one tree, or drawn whole by one component. */
+export type ScreenPage<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> = {
+    readonly path: string;
+    readonly page: ScreenFrame<Locale, Ref, FieldName>;
+    /** `create` and `edit` only: the record opens over the list, in shadcn's dialog or sheet, or a full-page drawer as Payload's document drawer. */
+    readonly mode?: 'dialog' | 'drawer' | 'sheet';
+    readonly component?: never;
+} | {
+    readonly path: string;
+    readonly component: Ref;
+    readonly page?: never;
+    readonly mode?: never;
+};
+/** What `targets.<screen>` on a kayan says, complete for that screen. */
+export type ScreenKayan<Locale extends string = string, Ref extends string | Ui = string | Ui, FieldName extends string = string> = {
+    readonly useAsTitle?: FieldName;
+    readonly description?: Localized<Locale>;
+    /** The rows this screen lists of the kayan, ANDed with whatever a list asks. A list filter, not access: a row it leaves out is still read by its id. */
+    readonly baseFilter?: Where;
+    readonly pages?: Readonly<Record<string, ScreenPage<Locale, Ref, FieldName>>>;
+};
+/** The screen keys of a build's targets. */
+export type ScreenKeys<Targets> = {
+    [Name in keyof Targets]: Targets[Name] extends {
+        capability: 'screen';
+    } ? Name : never;
+}[keyof Targets] & string;
+/** Every reference a declaration may write on one screen of a build. */
+export type RefOf<Target, Kinds = {}> = Target extends {
+    layouts: infer Layouts;
+    components: infer Components;
+} ? ScreenRef<(keyof Layouts | keyof Components | keyof typeof builtInScreenKinds | keyof typeof defaultKinds | OwnScreenNames<Kinds>) & string> : string | Ui;
+type FieldData = {
+    name: string;
+    kind: string;
+    label?: Localized;
+    rules: Readonly<Record<string, unknown>>;
+    /** Relationship and join only: the name of the kayan this field points at. */
+    relationTo?: string;
+    /** Join only: the child's relationship that holds this row's id. */
+    on?: string;
+    /** Relationship only: whether this field holds a set of rows rather than one. */
+    hasMany?: true;
+    /** Relationship only: whether its picker reads `for` this field, so the server holds the rows to its `filterOptions`. */
+    filterOptions?: true;
+};
+/** One field as a screen draws it: the data a browser needs, and this screen's drawing facts decided. */
+export type ClientField = FieldData & {
+    options?: readonly {
+        value: string;
+        label: Localized;
+    }[];
+    placeholder?: Localized;
+    prefix?: Localized;
+    suffix?: Localized;
+    description?: Localized;
+    /** The control the form draws it with where a page names nothing else, resolved. */
+    component: string;
+    /** The cell the list draws it with where a page names nothing else, resolved. */
+    cell: string;
+} & Omit<ScreenField, 'component' | 'cell'>;
+/** A leaf as `screen.json` prints it: the field, and what this page decided it is drawn with. */
+export type LeafClient = {
+    field: string;
+    component?: string;
+    cell?: string;
+    /** Which level decided what this leaf draws: the `leaf`, the `field`'s own `targets.<screen>`, or the screen's `controls` `table`. */
+    decided?: 'field' | 'leaf' | 'table';
+    placeholder?: Localized;
+    description?: Localized;
+    readOnly?: boolean;
+    width?: string;
+    when?: Where;
+};
+type GroupClient = {
+    label: Localized;
+    description?: Localized;
+    fields: NodeClient[];
+};
+/** A shell's or a layout's regions as `screen.json` prints them. */
+export type RegionsClient = {
+    [region: string]: NodeClient[] | string | Where | undefined;
+};
+/** A button node as `screen.json` prints it. */
+export type ButtonClient = {
+    button: string;
+    label: Localized;
+    fields?: string[];
+    reload?: boolean;
+    component?: string;
+    confirm?: {
+        title: Localized;
+        body: Localized;
+    };
+    when?: Where;
+};
+/** A list node's own keys as `screen.json` prints them. */
+export type ListClient = {
+    columns: LeafClient[];
+    filters?: string[];
+    search?: string[];
+    empty?: string;
+    menu?: string;
+    toolbar?: ButtonClient[];
+    bulk?: ButtonClient[];
+    row?: ButtonClient[];
+    sort?: string;
+    limit?: number;
+    tabs?: {
+        tab: string;
+        label: Localized;
+        where?: Where;
+    }[];
+    /** A list of another kayan: its name, and its relationship holding this page's row. */
+    of?: string;
+    where?: string;
+};
+/** A node as `screen.json` prints it, every reference resolved, and its `when` where it has one. */
+export type NodeClient = LeafClient | ButtonClient | (({
+    form: NodeClient[];
+    component?: string;
+} | {
+    list: ListClient;
+    component?: string;
+} | {
+    component: string;
+} | ({
+    layout: string;
+} & RegionsClient) | {
+    title: Record<string, never>;
+} | {
+    nav: Record<string, never>;
+} | {
+    controls: Record<string, never>;
+} | {
+    row: NodeClient[];
+    resizable?: true;
+} | {
+    separator: true;
+} | ({
+    section: string;
+    collapsed?: boolean;
+    width?: number;
+    scroll?: string;
+} & GroupClient) | {
+    tabs: ({
+        tab: string;
+    } & GroupClient)[];
+} | {
+    accordion: ({
+        item: string;
+    } & GroupClient)[];
+}) & {
+    when?: Where;
+});
+/** A page's tree as `screen.json` prints it: the shell at the root, and its regions. */
+export type FrameClient = {
+    shell: string;
+} & RegionsClient;
+/** A kayan's page: its tree, or the one component drawing it whole. */
+export type PageClient = {
+    path: string;
+    page: FrameClient;
+    mode?: 'dialog' | 'drawer' | 'sheet';
+} | {
+    path: string;
+    component: string;
+};
+/** A page of the screen's own, drawn whole by one component. */
+export type ScreenPageClient = {
+    path: string;
+    component: string;
+    nav?: {
+        label: Localized;
+    };
+    permission?: string;
+};
+/** One entry of the screen's nav: a kayan's page or a page of the screen's own, and the catalog key an actor needs to see it. */
+export type NavEntry = {
+    path: string;
+    page: string;
+    kayan?: string;
+    label?: Localized;
+    permission?: string;
+};
+export type ClientKayan<Pages extends string = string> = {
+    name: string;
+    single: boolean;
+    fields: ClientField[];
+    operations: {
+        name: string;
+        effect: string;
+        fields?: ClientField[];
+        updatesMany?: true;
+    }[];
+    useAsTitle?: string;
+    description?: Localized;
+    /** The rows every list of this kayan on the screen is held to (`ScreenKayan` `baseFilter`). */
+    baseFilter?: Where;
+    /** Whether the kayan keeps drafts, and its autosave interval where it does. */
+    drafts?: {
+        autosave?: {
+            interval: number;
+        };
+    };
+    /** The types a kayan holding files takes and its largest file in bytes, so the upload control refuses a file before sending it. */
+    storage?: {
+        mimeTypes: readonly string[];
+        fileSize: number;
+    };
+    pages: Record<Pages, PageClient>;
+};
+/** What `asas.targets.<screen>.client` holds and `screen.json` prints, with every reference resolved. */
+export type ScreenClient<Pages extends Record<string, string> = Record<string, string>> = {
+    path: string;
+    providers: string[];
+    pages: Record<string, ScreenPageClient>;
+    nav: NavEntry[];
+    layouts: Record<string, string>;
+    components: Record<string, string>;
+    controls: Record<string, {
+        control: string;
+        cell: string;
+    }>;
+    kayan: {
+        [Name in keyof Pages]: ClientKayan<Pages[Name]>;
+    };
+    /** The most rows a served read answers, so a page paging through every row holds to the project's number. */
+    maxLimit: number;
+};
+export declare const clientFieldOf: (name: string, field: RuntimeField & {
+    target?: {
+        name: string;
+    };
+}) => FieldData;
+/** The folder holding the nearest `package.json` above a file; references print relative to it, so `screen.json` names no absolute path. */
+export declare const packageOf: (file: URL) => URL | undefined;
+/** Every screen of a build, checked and projected in one walk. Each refusal names the screen, kayan, page and node. */
+export declare const screensOf: (language: {
+    kinds: Record<string, {
+        targets?: Readonly<Record<string, unknown>>;
+    }>;
+    locales?: readonly string[];
+    targets: Record<string, unknown>;
+}, resolved: readonly ResolvedKayan[]) => Record<string, ScreenClient>;
+declare module '../mithaq/rukn.ts' {
+    interface KayanConfigs<L, F, T> {
+        screen: ScreenKayan<LocalesOf<L>, RefOf<T, L extends {
+            kinds: infer Kinds;
+        } ? Kinds : {}>, keyof F & string>;
+    }
+}
+export {};