@adula/kit 1.0.0 → 1.2.0

package/build/src/admin/controller.js

@@ -4,7 +4,13 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
     return class ResourcesController {
         async create(ctx) {
             return this.#execute(ctx, async ({ resources, actor }, resource) => {
-                const editor = await resources.editor(resource.name, actor);
+                // `?defaults[field]=value` pre-fills the form; the service authorizes each value.
+                const defaults = ctx.request.qs().defaults;
+                const editor = await resources.editor(resource.name, actor, undefined, {
+                    defaults: defaults && typeof defaults === 'object' && !Array.isArray(defaults)
+                        ? defaults
+                        : undefined,
+                });
                 return renderForm && ctx.request.accepts(['html', 'json']) === 'html'
                     ? renderForm(ctx, resource, editor)
                     : editor;
@@ -50,8 +56,47 @@ export function createResourceController(resolveRuntime, renderList, renderForm,
                     : this.#positiveId(ctx.request.input('id')),
                 search: ctx.request.input('search'),
                 cursor: ctx.request.input('cursor'),
+                orgUnitId: ctx.request.input('orgUnitId') === undefined || ctx.request.input('orgUnitId') === ''
+                    ? undefined
+                    : this.#positiveId(ctx.request.input('orgUnitId')),
+                purpose: ctx.request.input('purpose') === 'filter' ? 'filter' : 'form',
             }));
         }
+        /**
+         * GET …/aggregate?groupBy=status,priority&sum=total&filters[x]=…&where={json}
+         * Counts and totals over the records the actor may view (ResourceService.aggregate).
+         */
+        async aggregate(ctx) {
+            return this.#execute(ctx, async ({ resources, actor }, resource) => {
+                const list = (value) => value === undefined || value === ''
+                    ? []
+                    : Array.isArray(value)
+                        ? value.map(String)
+                        : String(value).split(',').filter(Boolean);
+                let where;
+                const raw = ctx.request.input('where');
+                if (typeof raw === 'string' && raw) {
+                    try {
+                        where = JSON.parse(raw);
+                    }
+                    catch {
+                        throw new KitError(422, 'E_FILTER', 'where must be a JSON object');
+                    }
+                }
+                else if (raw && typeof raw === 'object')
+                    where = raw;
+                return {
+                    data: await resources.aggregate(resource.name, actor, {
+                        groupBy: list(ctx.request.input('groupBy')),
+                        sum: list(ctx.request.input('sum')),
+                        count: ctx.request.input('count') !== 'false',
+                        filters: ctx.request.input('filters'),
+                        where: where,
+                        search: ctx.request.input('search'),
+                    }),
+                };
+            });
+        }
         async store(ctx) {
             return this.#execute(ctx, async ({ resources, actor }, resource) => ctx.response.created({
                 data: await resources.save(resource.name, actor, ctx.request.body()),

package/build/src/admin/presentation.d.ts

@@ -6,6 +6,10 @@ export type RecordPermissions = Partial<Record<Action, boolean>>;
 export type ResourceDescription = {
     name: string;
     label: string;
+    /** Singular record noun in Arabic, or null when the resource does not declare one. */
+    recordLabel: string | null;
+    /** Arabic create-button text, or null to derive «إضافة <recordLabel>» (or «إضافة سجل»). */
+    createLabel: string | null;
     fields: ResourceField[];
     list: string[];
     show: string[];
@@ -19,4 +23,6 @@ export type ResourceNavigation = {
     label: string;
     href: string;
     module: string;
+    /** Arabic module label, for grouping the navigation by module (1.2; optional for compatibility). */
+    moduleLabel?: string;
 }[];

package/build/src/admin/record_title.d.ts

@@ -0,0 +1,14 @@
+import type { Resource, SerializedRecord } from '../resource/types.js';
+/**
+ * The fields that name a record wherever it is referenced (#47, #32): the resource's
+ * `title`, or else its first sequence field and its first text field in `list`. Lookup
+ * keys are never shown raw; declared lookup fields are shown by their Arabic label.
+ */
+export declare function titleFields(resource: Pick<Resource, 'fields' | 'list' | 'title'>): string[];
+/** Definition check: title fields exist, are readable and have a displayable type. */
+export declare function assertTitle(resource: Pick<Resource, 'name' | 'fields' | 'list' | 'show' | 'serialize' | 'title'>): void;
+/**
+ * The title of one serialized record, read after field-level filtering so it never shows
+ * a value the viewer may not read. Returns null when no title field has a value.
+ */
+export declare function formatTitle(resource: Pick<Resource, 'fields' | 'list' | 'title'>, record: SerializedRecord, lookupLabel: (group: string, key: string) => string | undefined): string | null;

package/build/src/admin/record_title.js

@@ -0,0 +1,50 @@
+const TITLE_TYPES = new Set(['string', 'text', 'integer', 'money', 'date', 'datetime', 'lookup']);
+/**
+ * The fields that name a record wherever it is referenced (#47, #32): the resource's
+ * `title`, or else its first sequence field and its first text field in `list`. Lookup
+ * keys are never shown raw; declared lookup fields are shown by their Arabic label.
+ */
+export function titleFields(resource) {
+    if (resource.title)
+        return [...resource.title];
+    const sequence = Object.keys(resource.fields).find((key) => resource.fields[key].sequence);
+    const text = resource.list.find((key) => {
+        const field = resource.fields[key];
+        return (field.type === 'string' || field.type === 'text') && !field.sequence;
+    });
+    return [sequence, text].filter((key) => key !== undefined);
+}
+/** Definition check: title fields exist, are readable and have a displayable type. */
+export function assertTitle(resource) {
+    if (!resource.title)
+        return;
+    if (!resource.title.length)
+        throw new Error(`${resource.name}: title needs at least one field`);
+    const readable = new Set(resource.serialize ?? [...resource.list, ...resource.show]);
+    for (const key of resource.title) {
+        const field = resource.fields[key];
+        if (!field)
+            throw new Error(`Unknown field: ${key}`);
+        if (!TITLE_TYPES.has(field.type))
+            throw new Error(`${resource.name}: title field ${key} cannot be a ${field.type}`);
+        if (!readable.has(key))
+            throw new Error(`${resource.name}: title field ${key} must be serialized`);
+    }
+}
+/**
+ * The title of one serialized record, read after field-level filtering so it never shows
+ * a value the viewer may not read. Returns null when no title field has a value.
+ */
+export function formatTitle(resource, record, lookupLabel) {
+    const parts = [];
+    for (const key of titleFields(resource)) {
+        const value = record[key];
+        if (value === null || value === undefined || value === '')
+            continue;
+        const field = resource.fields[key];
+        parts.push(field.type === 'lookup'
+            ? (lookupLabel(field.group, String(value)) ?? String(value))
+            : String(value));
+    }
+    return parts.length ? parts.join(' · ') : null;
+}

package/build/src/admin/resource_service.d.ts

@@ -1,8 +1,27 @@
 import type { Knex } from 'knex';
 import type { ResourceRegistry } from '../resource/registry.js';
-import type { Action, RecordData, Resource, SerializedRecord } from '../resource/types.js';
+import type { Action, JsonValue, RecordData, Resource, SerializedRecord } from '../resource/types.js';
 import { type Actor, type KitAbility } from '../auth/ability.js';
+import { type Conditions } from '../auth/conditions.js';
 import type { ResourceDescription, ResourceNavigation, ResourceField } from './presentation.js';
+export type AggregateOptions = {
+    /** Up to three queryable fields (docStatus and orgUnitId are also accepted). */
+    groupBy?: string[];
+    /** Count rows per group (default true). */
+    count?: boolean;
+    /** Integer or money fields to total per group; money totals are decimal strings. */
+    sum?: string[];
+    /** Equality filters, as in list(). */
+    filters?: Record<string, unknown>;
+    /** Role-rule style conditions ($eq, $ne, $in, $lt, $gt, $like, "$actor.id"). */
+    where?: Conditions;
+    search?: string;
+};
+export type AggregateRow = {
+    group: Record<string, JsonValue>;
+    count?: number;
+    sum?: Record<string, string | null>;
+};
 export type ListOptions = {
     limit?: number;
     cursor?: string;
@@ -19,6 +38,24 @@ export type ListOptions = {
  * indirectly, so it needs unconditional view access at the field's level.
  */
 export declare function canQueryField(resource: Resource, actor: Actor, ability: KitAbility, key: string): boolean;
+/** Options of ResourceService.systemSave. */
+export type SystemSaveOptions = {
+    /** The user recorded as the author: created/updated by, activity and events. */
+    actorId: number;
+    /** Write inside the module's transaction. */
+    trx?: Knex.Transaction;
+    /** Why module code wrote the record; stored with the activity entry. */
+    reason?: string;
+    /** Optimistic lock: when given, it must match the stored version. */
+    version?: number;
+    /**
+     * The person who chose the values, when module code writes a choice made by a user,
+     * such as a supervisor reassigning a record. A new value of a user field must then be
+     * eligible for them as in a user save; without it, any active member qualifies on
+     * unscoped resources.
+     */
+    chooser?: Actor;
+};
 export declare class ResourceService {
     private db;
     private registry;
@@ -37,6 +74,8 @@ export declare class ResourceService {
     private scopedQuery;
     private columns;
     private find;
+    /** A live record regardless of any actor's scope, for system writes. */
+    private findAny;
     private requireRecord;
     /**
      * Authorizes one record for collaboration features (comments, tags, assignments...).
@@ -62,7 +101,24 @@ export declare class ResourceService {
         related: Record<string, SerializedRecord[]>;
     }>;
     private canQueryField;
+    /**
+     * Counts and totals over the records the actor may view, grouped by queryable fields,
+     * for dashboards. Authorization is list()'s: the same rules, organization scope and
+     * soft-delete filter apply, and every grouped, totalled or filtered field must be one
+     * the actor may query (E_FIELD_FORBIDDEN otherwise), so no hidden value leaks.
+     */
+    aggregate(name: string, actor: Actor, options?: AggregateOptions): Promise<{
+        rows: AggregateRow[];
+        truncated: boolean;
+    }>;
     private preload;
+    /** Formats record titles of one resource, loading the labels of its title lookups once. */
+    private titler;
+    /**
+     * Titles of records the actor may view, read under the actor's field access (#32).
+     * Records the actor cannot view are left out; callers fall back to the record id.
+     */
+    titles(name: string, ids: readonly number[], actor: Actor): Promise<Map<number, string>>;
     show(name: string, id: number, actor: Actor): Promise<{
         data: SerializedRecord;
         permissions: Partial<Record<Action, boolean>>;
@@ -72,6 +128,10 @@ export declare class ResourceService {
         id?: number;
         search?: string;
         cursor?: string;
+        /** User fields: the organization unit chosen in the form. */
+        orgUnitId?: number;
+        /** User fields: choices for a list filter instead of a form. */
+        purpose?: 'form' | 'filter';
     }): Promise<{
         data: {
             value: string;
@@ -79,11 +139,25 @@ export declare class ResourceService {
         }[];
         nextCursor: string | null;
     }>;
+    /**
+     * Choices for a user field. A form lists active members of the record's unit or its
+     * ancestors (the users the record is visible to through membership); a filter lists
+     * active users who share organization scope with the actor. Only names are returned.
+     */
+    private userOptions;
+    /**
+     * Active users eligible for a user field: members of the unit at `path` or of one of
+     * its ancestors, or (without a path) users sharing organization scope with the actor.
+     * A system write on an unscoped resource passes no actor: any active member qualifies.
+     */
+    private eligibleUsers;
     /** Deferred relation reads re-authorize the parent and each child on every request. */
     children(name: string, id: number, actor: Actor): Promise<Record<string, {
         rows: SerializedRecord[];
         hasMore: boolean;
     }>>;
+    /** Inline children of an already authorized parent record. */
+    private childrenOf;
     /** Active lookup labels for the lookup fields the actor may read on this resource. */
     lookups(name: string, actor: Actor): Promise<Record<string, {
         value: string;
@@ -103,10 +177,66 @@ export declare class ResourceService {
         actorEmail: string | null;
         createdAt: string;
     }[]>;
-    editor(name: string, actor: Actor, id?: number): Promise<{
+    /**
+     * Inline children and recent activity of one record, authorized with a single record
+     * read (for deferred page props that would otherwise read the record twice).
+     */
+    details(name: string, id: number, actor: Actor): Promise<{
+        children: Record<string, {
+            rows: SerializedRecord[];
+            hasMore: boolean;
+        }>;
+        activity: {
+            id: number;
+            action: Action;
+            fields: string[];
+            actorId: number;
+            actorName: string | null;
+            /**
+             * @deprecated Always null. Kept so project-owned copies of resource-show from
+             * earlier releases still compile; they fall back to the actor id.
+             */
+            actorEmail: string | null;
+            createdAt: string;
+        }[];
+    }>;
+    /** show(), children() and activity() of one record from a single record read. */
+    record(name: string, id: number, actor: Actor): Promise<{
+        data: SerializedRecord;
+        permissions: Partial<Record<Action, boolean>>;
+        related: Record<string, SerializedRecord[]>;
+        children: Record<string, {
+            rows: SerializedRecord[];
+            hasMore: boolean;
+        }>;
+        activity: {
+            id: number;
+            action: Action;
+            fields: string[];
+            actorId: number;
+            actorName: string | null;
+            /**
+             * @deprecated Always null. Kept so project-owned copies of resource-show from
+             * earlier releases still compile; they fall back to the actor id.
+             */
+            actorEmail: string | null;
+            createdAt: string;
+        }[];
+    }>;
+    private activityOf;
+    /**
+     * The form description for create (no id) or update. `defaults` pre-fills a create form
+     * (#48), for example `?defaults[violation]=13`: only visible form fields are used, a
+     * related record must be viewable by the actor and a lookup must be active. Anything else
+     * is dropped. Defaults are only initial values; saving validates as usual.
+     */
+    editor(name: string, actor: Actor, id?: number, request?: {
+        defaults?: Record<string, unknown>;
+    }): Promise<{
         mode: string;
         name: string;
         label: string;
+        recordLabel: string | null;
         fields: ({
             label: import("../resource/types.js").Label;
             column?: string;
@@ -146,6 +276,18 @@ export declare class ResourceService {
             type: "belongsTo";
             resource: string;
             key: string;
+        } | {
+            label: import("../resource/types.js").Label;
+            column?: string;
+            required?: boolean;
+            unique?: boolean;
+            sortable?: boolean;
+            searchable?: boolean;
+            filterable?: boolean;
+            permissionLevel?: number;
+            sequence?: string;
+            type: "user";
+            key: string;
         } | {
             label: import("../resource/types.js").Label;
             column?: string;
@@ -175,6 +317,8 @@ export declare class ResourceService {
             group: string;
             key: string;
         })[];
+        /** Initial values of a create form, already checked against the actor's access. */
+        defaults: SerializedRecord;
         inline: Record<string, {
             rows: SerializedRecord[];
             hasMore: boolean;
@@ -197,9 +341,26 @@ export declare class ResourceService {
             label: string;
         }[];
         scoped: boolean;
+        /** The belongsTo field whose record decides the unit; the form shows no unit picker. */
+        scopeFrom: string | null;
         record: SerializedRecord | null;
     }>;
     save(name: string, actor: Actor, input: RecordData, id?: number, transaction?: Knex.Transaction): Promise<SerializedRecord>;
+    /**
+     * A write decided by module code rather than by a user's role rules: state transitions,
+     * snapshots and listener updates. It runs the validator, hooks, lookup, relation and
+     * attachment checks, versioning and the audit trail exactly like save(), and skips only
+     * the actor's role rules and organization scope. Values may set any stored field except
+     * sequences and inline children. Updates merge the given values into the stored record.
+     * Returns the full stored record; module code must not send it to users unfiltered.
+     */
+    systemSave(name: string, values: RecordData, id: number | undefined, options: SystemSaveOptions): Promise<RecordData>;
+    /**
+     * Moves the records whose scope follows this parent (`scope: { from }`) to the parent's
+     * current organization unit, through systemSave. Call it from a listener on the parent's
+     * `updated` event, or right after moving the parent. Returns the number of moved records.
+     */
+    rehome(parentName: string, parentId: number, options: Omit<SystemSaveOptions, 'version'>): Promise<number>;
     private persist;
     private requireVersion;
     /** Inline children share the parent's draft state, organization and update authority. */