@drhomet/mithaq 0.0.0-stage → 0.2.0

package/dist/screen/react.d.ts

@@ -0,0 +1,97 @@
+import type { AccessReport, AnyRouter, ClientKayan, FetchClient, NavEntry, Row, ScreenClient, Translate } from './client.ts';
+/** Copy in the viewer's locale, and the direction that locale is written in. */
+export type LocaleState = {
+    locale: string;
+    dir: 'ltr' | 'rtl';
+    t: Translate;
+};
+/** What a screen's host provides around every page it draws, and what each hook below reads one part of. */
+export type ScreenState = LocaleState & {
+    screen: ScreenClient;
+    /** Who is signed in, and the screens of another app the host links for this actor, each a whole URL. */
+    user: {
+        /** The signed-in person's own id, which a page compares with an id a row names, such as the actor of an audit entry. */
+        id?: string;
+        name: string;
+        email: string;
+        screens?: readonly {
+            name: string;
+            path: string;
+        }[];
+        /** `names` is each locale's name, the JSON the project's auth setup writes; `name` is the default locale's. */
+        organizations?: readonly {
+            id: string;
+            name: string;
+            slug?: string;
+            names?: string;
+        }[];
+        activeOrganizationId?: string | null;
+    };
+    access: AccessReport;
+    client: FetchClient;
+    kayan?: ClientKayan;
+    record?: Row | null;
+    /** The page's path joined to the screen's, set on a page of the screen's own. */
+    path?: string;
+};
+/** The form a component sits in. */
+export type FormState = {
+    /** The values the form holds now. */
+    getData: () => Readonly<Row>;
+    /** Changes one field. A field set here is saved even where the page names no leaf for it. */
+    setValue: (path: string, value: unknown) => void;
+    /** Whether the form is busy saving, when nothing may change. */
+    disabled: boolean;
+    /** How many saves have landed since the form was seeded. A draft save never bumps the row's `updatedAt`, so watch this instead. */
+    saves: number;
+    /** The operations beside `update` that take the `expectedUpdatedAt` step's key. */
+    expectedUpdatedAtOn?: readonly string[];
+};
+/** What a list hands whatever draws it: one page of rows, and where a row and a new row go. */
+export type ListState = {
+    page: {
+        docs: readonly Row[];
+        totalDocs: number;
+        page: number;
+        totalPages: number;
+    };
+    /** Whether this actor may create a row, off the report. */
+    creates?: boolean;
+    href: (id: string) => string;
+    newHref: string;
+};
+/** The one context a screen's host provides. */
+export declare const ScreenContext: import("react").Context<ScreenState | null>;
+/** The form a component sits in, which each form item provides around the page it draws. */
+export declare const FormContext: import("react").Context<FormState | null>;
+/** The list a component draws, which the host provides around a list node. */
+export declare const ListContext: import("react").Context<ListState | null>;
+/** The screen as this actor may see it. */
+export declare const useScreen: () => ScreenClient;
+/** The screen's nav, already cut to the entries this actor may open (`navOf`). */
+export declare const useNav: () => NavEntry[];
+/** Who is signed in. */
+export declare const useUser: () => ScreenState['user'];
+/** What the access report lets this actor do, cut to the screen's kayan. */
+export declare const useAccess: () => AccessReport;
+/** The viewer's locale, its direction and the copy in it. */
+export declare const useLocale: () => LocaleState;
+/** The client posting this screen's operations: `useClient<typeof asas.router>()` types each call. */
+export declare const useClient: <R = AnyRouter>() => FetchClient<R>;
+/** The row the page draws, and `null` where it draws none. */
+export declare const useRecord: () => Row | null;
+/** The kayan the page belongs to. */
+export declare const useKayan: () => ClientKayan;
+/** The form a component sits in; throws outside one. */
+export declare const useForm: () => FormState;
+/** One field of the form a component sits in, by its path: `path`, `value`, `setValue` and `disabled`. */
+export declare const useField: <Value = unknown>({ path }: {
+    path: string;
+}) => {
+    path: string;
+    value: Value;
+    setValue: (value: unknown) => void;
+    disabled: boolean;
+};
+/** The list a component draws in place of the registry's list. */
+export declare const useList: () => ListState;

package/dist/screen/react.js

@@ -0,0 +1,58 @@
+// Apart from `mithaq/admin`, so that entry, the CLI and a host of another framework load no React.
+import { createContext, use } from 'react';
+/** The one context a screen's host provides. */
+export const ScreenContext = createContext(null);
+/** The form a component sits in, which each form item provides around the page it draws. */
+export const FormContext = createContext(null);
+/** The list a component draws, which the host provides around a list node. */
+export const ListContext = createContext(null);
+const screenState = (hook) => {
+    const state = use(ScreenContext);
+    if (!state)
+        throw new Error(`${hook}() reads what a screen's host provides, and nothing above this component provides it: draw it inside a screen's page.`);
+    return state;
+};
+/** The screen as this actor may see it. */
+export const useScreen = () => screenState('useScreen').screen;
+/** The screen's nav, already cut to the entries this actor may open (`navOf`). */
+export const useNav = () => screenState('useNav').screen.nav;
+/** Who is signed in. */
+export const useUser = () => screenState('useUser').user;
+/** What the access report lets this actor do, cut to the screen's kayan. */
+export const useAccess = () => screenState('useAccess').access;
+/** The viewer's locale, its direction and the copy in it. */
+export const useLocale = () => {
+    const { locale, dir, t } = screenState('useLocale');
+    return { locale, dir, t };
+};
+/** The client posting this screen's operations: `useClient<typeof asas.router>()` types each call. */
+export const useClient = () => screenState('useClient').client;
+/** The row the page draws, and `null` where it draws none. */
+export const useRecord = () => screenState('useRecord').record ?? null;
+/** The kayan the page belongs to. */
+export const useKayan = () => {
+    const kayan = screenState('useKayan').kayan;
+    if (!kayan)
+        throw new Error('useKayan() reads the kayan a page belongs to, and this page belongs to none: a page of the screen\'s own has no kayan.');
+    return kayan;
+};
+/** The form a component sits in; throws outside one. */
+export const useForm = () => {
+    const form = use(FormContext);
+    if (!form) {
+        throw new Error('useForm() reads the form a component sits in, and this component sits in none: only a component a form draws, such as one a form node names, can read or write its values.');
+    }
+    return form;
+};
+/** One field of the form a component sits in, by its path: `path`, `value`, `setValue` and `disabled`. */
+export const useField = ({ path }) => {
+    const form = useForm();
+    return { path, value: form.getData()[path], setValue: (value) => form.setValue(path, value), disabled: form.disabled };
+};
+/** The list a component draws in place of the registry's list. */
+export const useList = () => {
+    const list = use(ListContext);
+    if (!list)
+        throw new Error('useList() reads the list a component draws, and this component draws none: only a component a list node names can read its rows.');
+    return list;
+};

package/dist/screen/studio.d.ts

@@ -0,0 +1,24 @@
+import type { LeafClient, NodeClient, RegionsClient, ScreenClient } from './index.ts';
+/** One line of the tree, and the lines under it. */
+export type StudioNode = {
+    label: string;
+    /** Which level decided what a leaf draws. */
+    decided?: LeafClient['decided'];
+    children?: StudioNode[];
+};
+/**
+ * Every kind of node a page's tree holds, in the order a walk asks for them. Every walk
+ * goes through a map keyed by these, so TypeScript refuses one that leaves a kind out.
+ */
+export declare const nodeKinds: readonly ['layout', 'field', 'form', 'list', 'button', 'title', 'nav', 'controls', 'component', 'row', 'separator', 'tabs', 'accordion', 'section'];
+export type NodeKind = (typeof nodeKinds)[number];
+/** The node of one kind. */
+export type NodeOf<Kind extends NodeKind> = Extract<NodeClient, Record<Kind, unknown>>;
+/** Which kind a node is: the first kind whose key it holds. A bare name is a leaf. */
+export declare const kindOf: (node: unknown) => NodeKind | undefined;
+/** The regions a shell or a layout fills, each with its nodes. */
+export declare const regionsIn: (frame: RegionsClient) => [string, NodeClient[]][];
+/** One screen as the tree `mithaq screens` prints. */
+export declare const studioTree: (name: string, screen: ScreenClient) => StudioNode;
+/** The tree as text, two spaces a level, which is what `mithaq screens` prints. */
+export declare const studioText: (node: StudioNode, depth?: number) => string;

package/dist/screen/studio.js

@@ -0,0 +1,68 @@
+import { referencesIn } from './client.js';
+const named = (label, reference) => ({ label: `${label} ${reference}` });
+const group = (label, children) => ({ label, ...(children.length && { children }) });
+/**
+ * Every kind of node a page's tree holds, in the order a walk asks for them. Every walk
+ * goes through a map keyed by these, so TypeScript refuses one that leaves a kind out.
+ */
+export const nodeKinds = ['layout', 'field', 'form', 'list', 'button', 'title', 'nav', 'controls', 'component', 'row', 'separator', 'tabs', 'accordion', 'section'];
+/** Which kind a node is: the first kind whose key it holds. A bare name is a leaf. */
+export const kindOf = (node) => typeof node === 'string' ? 'field' : node && typeof node === 'object' ? nodeKinds.find((kind) => kind in node) : undefined;
+/** The regions a shell or a layout fills, each with its nodes. */
+export const regionsIn = (frame) => Object.entries(frame).filter((entry) => !['shell', 'layout', 'when'].includes(entry[0]));
+const leafOf = (leaf) => {
+    const [place, reference] = leaf.component !== undefined ? ['control', leaf.component] : ['cell', leaf.cell ?? ''];
+    return { ...named(`${leaf.field}: ${place}`, reference), ...(leaf.decided && { decided: leaf.decided }) };
+};
+const frameOf = (label, reference, frame) => ({
+    ...named(label, reference),
+    children: regionsIn(frame).map(([region, nodes]) => group(`region ${region}`, nodes.map(nodeOf))),
+});
+const drawnBy = (node) => (node.component !== undefined ? [named('component', node.component)] : []);
+const studioOf = {
+    layout: (node) => frameOf('layout', node.layout, node),
+    field: (node) => leafOf(node),
+    form: (node) => group('form', [...drawnBy(node), ...node.form.map(nodeOf)]),
+    list: (node) => {
+        const { columns, filters, search, empty, menu, sort, limit, of, where } = node.list;
+        return group(of ? `list of ${of} where ${where}` : 'list', [
+            ...drawnBy(node),
+            ...columns.map(leafOf),
+            ...(filters ? [{ label: `filters ${filters.join(', ')}` }] : []),
+            ...(search ? [{ label: `search ${search.join(', ')}` }] : []),
+            ...(empty !== undefined ? [named('empty', empty)] : []),
+            ...(menu !== undefined ? [named('menu', menu)] : []),
+            ...(sort !== undefined ? [{ label: `sort ${sort}` }] : []),
+            ...(limit !== undefined ? [{ label: `limit ${limit}` }] : []),
+            ...['toolbar', 'bulk', 'row'].flatMap((region) => (node.list[region] ? [group(`region ${region}`, node.list[region].map(nodeOf))] : [])),
+        ]);
+    },
+    button: (node) => group(`button operation ${node.button}${node.confirm ? ' (confirm)' : ''}`, drawnBy(node)),
+    title: () => ({ label: 'title' }),
+    nav: () => ({ label: 'nav' }),
+    controls: () => ({ label: 'controls' }),
+    component: (node) => named('component', node.component),
+    row: (node) => group(node.resizable ? 'row resizable' : 'row', node.row.map(nodeOf)),
+    separator: () => ({ label: 'separator' }),
+    tabs: (node) => group('tabs', node.tabs.map((tab) => group(`tab ${tab.tab}`, tab.fields.map(nodeOf)))),
+    accordion: (node) => group('accordion', node.accordion.map((item) => group(`item ${item.item}`, item.fields.map(nodeOf)))),
+    section: (node) => group(`section ${node.section}`, node.fields.map(nodeOf)),
+};
+const nodeOf = (node) => {
+    const line = studioOf[kindOf(node)](node);
+    return node.when ? { ...line, label: `${line.label} when ${JSON.stringify(node.when)}` } : line;
+};
+const filesOf = (value) => new Set(referencesIn(value).map((reference) => reference.slice(0, reference.indexOf('#'))));
+/** One screen as the tree `mithaq screens` prints. */
+export const studioTree = (name, screen) => ({
+    label: `screen ${name} ${screen.path}`,
+    children: [
+        group('providers', screen.providers.map((one) => named('provider', one))),
+        group('pages', Object.entries(screen.pages).map(([page, one]) => group(`page ${page} ${one.path}`, [named('component', one.component)]))),
+        group('nav', screen.nav.map((entry) => ({ label: `${entry.kayan ?? 'screen'} ${entry.page} ${entry.path}${entry.permission ? ` (${entry.permission})` : ''}` }))),
+        group('kayan', Object.values(screen.kayan).map((kayan) => group(kayan.name, Object.entries(kayan.pages).map(([page, one]) => group(`page ${page} ${one.path}${'mode' in one && one.mode ? ` (${one.mode})` : ''}`, 'component' in one ? [named('component', one.component)] : [frameOf('shell', one.page.shell, one.page)]))))),
+        group('files', [...filesOf(screen)].sort().map((file) => ({ label: file }))),
+    ],
+});
+/** The tree as text, two spaces a level, which is what `mithaq screens` prints. */
+export const studioText = (node, depth = 0) => [`${'  '.repeat(depth)}${node.label}${node.decided ? ` (${node.decided})` : ''}`, ...(node.children ?? []).map((child) => studioText(child, depth + 1))].join('\n');

package/dist/service/index.d.ts

@@ -0,0 +1,63 @@
+import type { AuditHandler, ContextOf, ProjectStep, Step } from '../asas/runner/steps.ts';
+import type { Authorize } from '../asas/runner/write.ts';
+export { write } from '../asas/runner/write.ts';
+export { bulk } from '../asas/runner/bulk.ts';
+export { readers as read } from '../asas/runner/read.ts';
+/** The runner as a target, `capability: 'service'`: the steps every write runs, its limits, its access evaluator and its defaults. */
+export type ServiceTarget = {
+    readonly capability: 'service';
+    readonly type?: 'service';
+    /** Not a key of the runner: a kayan declares its own operations, spreading `defaultOperations`. */
+    readonly operations?: never;
+    /** The steps every write runs inside its transaction, after the row is loaded and before the operation's own list. */
+    readonly beforeSteps?: readonly ProjectStep[];
+    /** The steps every write runs inside its transaction after the list, before the commit: `afterSteps: [audit]`. An operation may write its own. */
+    readonly afterSteps?: readonly ProjectStep[];
+    /** The steps every write runs after the commit, where the row is durable and visible to every connection. */
+    readonly afterCommit?: readonly ProjectStep[];
+    /** The keys this project adds to every step's `ctx.context`, as a type: `context: {} as { requestId: string }`. */
+    readonly context?: Record<string, unknown>;
+    /** The sink explicit audit steps call before commit. */
+    readonly audit?: AuditHandler<never>;
+    /** The deepest a read or a write may nest another before it is refused. */
+    readonly depth: number;
+    /** The page a `find` or `findVersions` answers when its caller names no `limit`. */
+    readonly defaultLimit: number;
+    /** The most rows a served `find` or `findVersions` may ask for; a larger `limit` is a 400. Local calls are not held to it. */
+    readonly maxLimit: number;
+    /** How many of a child's rows one populated `join` carries where the join field names no `defaultLimit`. */
+    readonly joinLimit: number;
+    /** The most rows one bulk write may match; a larger match is refused before any row is written. */
+    readonly bulkLimit: number;
+    /** The access evaluator every operation uses before application steps. */
+    readonly authorize: Authorize;
+    /**
+     * The field that marks a row deleted, for the whole project. A kayan that declares it is
+     * soft-deleted: `delete` writes the moment there and every managed read leaves the row out.
+     */
+    readonly softDelete?: string;
+    /** The default store, the database a write lands in when a kayan names none. */
+    readonly store: string;
+    /** The default schema target, what a write is validated against when a kayan names none. */
+    readonly schema: string;
+};
+/** The template's depth cap: 8. A larger cap only delays the throw and holds the transaction open longer. */
+export declare const defaultDepth = 8;
+/** The template's page size: 10. */
+export declare const defaultLimit = 10;
+/** The template's largest served page: 100. A `limit` outside 1 to the maximum is refused, never clamped. */
+export declare const defaultMaxLimit = 100;
+/** The template's join page: 10. */
+export declare const defaultJoinLimit = 10;
+/** The template's bulk ceiling: 1000. */
+export declare const defaultBulkLimit = 1000;
+type ServiceLists<Extra extends Record<string, unknown>> = {
+    readonly beforeSteps?: readonly Step<Record<string, unknown>, Record<string, unknown>, unknown, unknown, unknown, Extra>[];
+    readonly afterSteps?: readonly Step<Record<string, unknown>, Record<string, unknown>, unknown, unknown, unknown, Extra>[];
+    readonly afterCommit?: readonly Step<Record<string, unknown>, Record<string, unknown>, unknown, unknown, unknown, Extra>[];
+};
+/** Core's runner as the service target of a build. */
+export declare const serviceTarget: <const Service extends Omit<ServiceTarget, 'capability' | 'type'>>(service: Service & NoInfer<ServiceLists<ContextOf<Service>>>) => Service & {
+    readonly capability: 'service';
+    readonly type: 'service';
+};

package/dist/service/index.js

@@ -0,0 +1,15 @@
+export { write } from '../asas/runner/write.js';
+export { bulk } from '../asas/runner/bulk.js';
+export { readers as read } from '../asas/runner/read.js';
+/** The template's depth cap: 8. A larger cap only delays the throw and holds the transaction open longer. */
+export const defaultDepth = 8;
+/** The template's page size: 10. */
+export const defaultLimit = 10;
+/** The template's largest served page: 100. A `limit` outside 1 to the maximum is refused, never clamped. */
+export const defaultMaxLimit = 100;
+/** The template's join page: 10. */
+export const defaultJoinLimit = 10;
+/** The template's bulk ceiling: 1000. */
+export const defaultBulkLimit = 1000;
+/** Core's runner as the service target of a build. */
+export const serviceTarget = (service) => ({ capability: 'service', type: 'service', ...service });

package/dist/storage/allowed-type.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Whether a type is one a kayan takes: `image/*` takes every `image/` type except
+ * SVG, a document that runs script, which is taken only where the list names it.
+ */
+export declare const allowedType: (type: string, mimeTypes: readonly string[]) => boolean;

package/dist/storage/allowed-type.js

@@ -0,0 +1,7 @@
+// No imports, so `mithaq/admin` hands it to the browser without the server's crypto.
+const svg = 'image/svg+xml';
+/**
+ * Whether a type is one a kayan takes: `image/*` takes every `image/` type except
+ * SVG, a document that runs script, which is taken only where the list names it.
+ */
+export const allowedType = (type, mimeTypes) => type === svg ? mimeTypes.includes(svg) : mimeTypes.some((one) => type.startsWith(one.replace('*', '')));

package/dist/storage/index.d.ts

@@ -0,0 +1,42 @@
+import type { StandardSchemaV1 } from '../mithaq/standard-schema.ts';
+import type { ResolvedField } from '../mithaq/types.ts';
+import { type StorageConfig } from './storage.ts';
+/** A relationship to a kayan that holds files, drawn as a file picker. */
+export declare const upload: import("../base/kinds.ts").Kind<string | number, "defaultValue" | "index" | "onDelete" | "providedBy" | "required" | "unique"> & {
+    targets: {
+        readonly drizzle: import("../targets.ts").ColumnBuilder;
+        readonly zod: (field: ResolvedField) => import("zod").ZodArray<import("zod").ZodGUID | import("zod").ZodInt32 | import("zod").ZodString> | import("zod").ZodGUID | import("zod").ZodInt32 | import("zod").ZodString;
+        readonly standardSchema: (field: ResolvedField) => StandardSchemaV1<unknown, number | string>;
+        readonly screen: {
+            readonly control: "upload";
+            readonly cell: "upload";
+        };
+    };
+} & {
+    pointsAtRow: true;
+};
+/**
+ * The rukn a project lays down for files: `arkan: [base, storage(storageConfig)]`.
+ * The config holds the signing secret, so the module that builds the language stays on the server.
+ */
+export declare const storage: (config: StorageConfig) => {
+    readonly name: "storage";
+    readonly kinds: {
+        readonly upload: import("../base/kinds.ts").Kind<string | number, "defaultValue" | "index" | "onDelete" | "providedBy" | "required" | "unique"> & {
+            targets: {
+                readonly drizzle: import("../targets.ts").ColumnBuilder;
+                readonly zod: (field: ResolvedField) => import("zod").ZodArray<import("zod").ZodGUID | import("zod").ZodInt32 | import("zod").ZodString> | import("zod").ZodGUID | import("zod").ZodInt32 | import("zod").ZodString;
+                readonly standardSchema: (field: ResolvedField) => StandardSchemaV1<unknown, number | string>;
+                readonly screen: {
+                    readonly control: "upload";
+                    readonly cell: "upload";
+                };
+            };
+        } & {
+            pointsAtRow: true;
+        };
+    };
+    readonly targets: {
+        storage: import("./storage.ts").StorageTarget;
+    };
+};

package/dist/storage/index.js

@@ -0,0 +1,43 @@
+import { kind } from '../base/kinds.js';
+import { defineRukn } from '../mithaq/rukn.js';
+import { kinds as drizzleKinds } from '../drizzle/kinds.js';
+import { kinds as zodKinds } from '../zod/kinds.js';
+import { storageTarget } from './storage.js';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const received = (value) => (value === null ? 'null' : typeof value);
+const notAnId = ({ kind, value }) => {
+    if (kind === 'number')
+        return typeof value === 'number' && Number.isFinite(value) ? undefined : `Invalid input: expected number, received ${received(value)}`;
+    if (typeof value !== 'string')
+        return `Invalid input: expected string, received ${received(value)}`;
+    return kind === 'uuid' && !uuid.test(value) ? 'Invalid GUID' : undefined;
+};
+/** A relationship to a kayan that holds files, drawn as a file picker. */
+export const upload = kind((value) => typeof value === 'number' || typeof value === 'string')({
+    label: { en: 'Upload', ar: 'ملف مرفوع' },
+    message: { en: 'Pick one of the listed files.', ar: 'اختر ملفا من القائمة.' },
+    rules: ['providedBy', 'required', 'unique', 'index', 'defaultValue', 'onDelete'],
+    pointsAtRow: true,
+    // A file a row still names is never deleted from under it, whether or not the field is required.
+    onDelete: 'restrict',
+    targets: {
+        drizzle: drizzleKinds.relationship,
+        zod: zodKinds.relationship,
+        standardSchema: (field) => ({
+            '~standard': {
+                version: 1,
+                vendor: 'mithaq',
+                validate: (value) => {
+                    const message = notAnId({ kind: field.target?.fields.id?.kind, value });
+                    return message ? { issues: [{ message }] } : { value: value };
+                },
+            },
+        }),
+        screen: { control: 'upload', cell: 'upload' },
+    },
+});
+/**
+ * The rukn a project lays down for files: `arkan: [base, storage(storageConfig)]`.
+ * The config holds the signing secret, so the module that builds the language stays on the server.
+ */
+export const storage = (config) => defineRukn({ name: 'storage', kinds: { upload }, targets: { storage: storageTarget(config) } });