@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/aggregate.d.ts

@@ -0,0 +1,83 @@
+import { type Row } from '@protoyard/core';
+import type { Aggregate, BlueprintEntity, BlueprintScreenFilter } from './schema.ts';
+import type { EntityServices } from './services.ts';
+/**
+ * Aggregates for dashboards, boards, analytics and calendars, computed in
+ * one pass over entity rows. Pure and framework-agnostic: screens wrap
+ * `createAggregateQuery` in `liveQuery`. Buckets are UTC (days start at
+ * midnight, weeks on Monday, months on the 1st), so results never depend on
+ * the viewer's time zone.
+ */
+export type BucketUnit = 'day' | 'week' | 'month';
+export interface AggregateSpec {
+    /** Default `count`. */
+    aggregate?: Aggregate;
+    /** Required for every aggregate except `count`. */
+    field?: string;
+    /** One series entry per value; array fields (tags, many-relations) count once per item. */
+    groupBy?: string;
+    /** Time buckets over a date or datetime field (or `createdAt` / `updatedAt`). */
+    bucket?: {
+        field: string;
+        unit: BucketUnit;
+    };
+    filter?: BlueprintScreenFilter;
+    /** Buckets to fill when bucketing (inclusive); defaults to the data's first and last bucket. */
+    range?: {
+        from: string | Date;
+        to: string | Date;
+    };
+}
+/** One cell: a bucket × group combination (either may be null when not used). */
+export interface AggregateCell {
+    /** `<bucket|*>|<group|*>`, stable across runs. */
+    key: string;
+    /** Bucket start (ISO, UTC) or null without `bucket`. */
+    bucket: string | null;
+    /** Group value or null without `groupBy`; `NO_GROUP` collects rows without a value. */
+    group: string | null;
+    /** Rows that matched (after filter). */
+    count: number;
+    /** null for avg/min/max over no values. */
+    value: number | null;
+}
+export interface AggregateResult {
+    aggregate: Aggregate;
+    /**
+     * How to format `value`: `money` is integer cents, `date` is epoch
+     * milliseconds (min/max over date fields), `number` otherwise.
+     */
+    valueKind: 'number' | 'money' | 'date';
+    /** Over every matching row. */
+    total: AggregateCell;
+    /** Ordered: buckets ascending, then groups (enum order, else sorted, `NO_GROUP` last). */
+    series: AggregateCell[];
+    /** Group order used in `series`. */
+    groups: string[];
+    /** Bucket starts used in `series`, contiguous. */
+    buckets: string[];
+}
+/** Group key for rows whose groupBy value is empty. */
+export declare const NO_GROUP = "__none__";
+/** Upper bound on filled buckets, so a typo in a range cannot allocate millions of cells. */
+export declare const MAX_BUCKETS = 5000;
+/** UTC start of the bucket containing `ms`. */
+export declare function bucketStartUtc(ms: number, unit: BucketUnit): number;
+/**
+ * Aggregates `rows` (soft-deleted rows are skipped). Pass the blueprint
+ * entity so relation fields map to their `<name>Id` columns, enum groups keep
+ * their declared order (every value appears, even at zero), and money and
+ * dates are typed. Money sums stay integer cents; money and integer averages
+ * are rounded to integers.
+ */
+export declare function aggregate(rows: readonly Row[], spec: AggregateSpec, entity?: BlueprintEntity): AggregateResult;
+/** A spec bound to an entity, as dashboard widgets and analytics measures declare it. */
+export type AggregateQuerySpec = AggregateSpec & {
+    entity: string;
+};
+/**
+ * A querier for `liveQuery`: reads through the entity service (so
+ * `session.assert(<entity>:read)` applies) and resolves to null when the
+ * active persona cannot read the entity, like the generated Home counts.
+ */
+export declare function createAggregateQuery(services: EntityServices, spec: AggregateQuerySpec): () => Promise<AggregateResult | null>;

package/dist/aggregate.js

@@ -0,0 +1,268 @@
+import { PermissionDeniedError } from '@protoyard/core';
+import { inputProperty } from "./validation.js";
+/** Group key for rows whose groupBy value is empty. */
+export const NO_GROUP = '__none__';
+/** Upper bound on filled buckets, so a typo in a range cannot allocate millions of cells. */
+export const MAX_BUCKETS = 5000;
+const MS_PER_DAY = 86_400_000;
+const MANAGED_DATES = new Set(['createdAt', 'updatedAt']);
+/** UTC start of the bucket containing `ms`. */
+export function bucketStartUtc(ms, unit) {
+    const day = Math.floor(ms / MS_PER_DAY) * MS_PER_DAY;
+    if (unit === 'day')
+        return day;
+    if (unit === 'week')
+        return day - ((new Date(day).getUTCDay() + 6) % 7) * MS_PER_DAY;
+    const date = new Date(day);
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), 1);
+}
+function nextBucket(start, unit) {
+    if (unit === 'day')
+        return start + MS_PER_DAY;
+    if (unit === 'week')
+        return start + 7 * MS_PER_DAY;
+    const date = new Date(start);
+    return Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 1);
+}
+/** Epoch ms for a date-like value; NaN when it is not one. */
+function toMs(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    return typeof value === 'string' && value !== '' ? Date.parse(value) : Number.NaN;
+}
+function fieldOf(entity, name) {
+    return entity?.fields.find((f) => f.name === name);
+}
+/** Row property that stores a field (`customer` → `customerId`). */
+function propertyOf(entity, name) {
+    const field = fieldOf(entity, name);
+    return field ? inputProperty(field) : name;
+}
+function groupKeys(value) {
+    if (Array.isArray(value)) {
+        const keys = value.filter((v) => v !== null && v !== undefined && v !== '').map(String);
+        return keys.length > 0 ? [...new Set(keys)] : [NO_GROUP];
+    }
+    return value === null || value === undefined || value === '' ? [NO_GROUP] : [String(value)];
+}
+function makeFilter(entity, filter) {
+    if (!filter)
+        return () => true;
+    const prop = propertyOf(entity, filter.field);
+    const kind = MANAGED_DATES.has(filter.field) ? 'datetime' : fieldOf(entity, filter.field)?.kind;
+    const isDate = kind === 'date' || kind === 'datetime';
+    const comparable = (v) => {
+        if (v === null || v === undefined)
+            return null;
+        if (isDate)
+            return toMs(v);
+        return typeof v === 'number' || typeof v === 'boolean' ? v : String(v);
+    };
+    const wanted = (Array.isArray(filter.value) ? filter.value : [filter.value]).map(comparable);
+    const matchOne = (v) => {
+        const c = comparable(v);
+        if (c === null)
+            return false;
+        if (filter.op === 'eq' || filter.op === 'in')
+            return wanted.includes(c);
+        const bound = wanted[0];
+        if (bound === null || bound === undefined)
+            return false;
+        return filter.op === 'gte' ? c >= bound : c <= bound;
+    };
+    return (row) => {
+        const value = row[prop];
+        return Array.isArray(value) ? value.some(matchOne) : matchOne(value);
+    };
+}
+const newAcc = () => ({
+    count: 0,
+    n: 0,
+    sum: 0,
+    min: Number.POSITIVE_INFINITY,
+    max: Number.NEGATIVE_INFINITY,
+});
+function add(acc, value) {
+    acc.count++;
+    if (value === null)
+        return;
+    acc.n++;
+    acc.sum += value;
+    if (value < acc.min)
+        acc.min = value;
+    if (value > acc.max)
+        acc.max = value;
+}
+function finish(acc, aggregate, roundAvg) {
+    switch (aggregate) {
+        case 'count':
+            return acc.count;
+        case 'sum':
+            return acc.sum;
+        case 'avg':
+            if (acc.n === 0)
+                return null;
+            return roundAvg ? Math.round(acc.sum / acc.n) : acc.sum / acc.n;
+        case 'min':
+            return acc.n === 0 ? null : acc.min;
+        case 'max':
+            return acc.n === 0 ? null : acc.max;
+    }
+}
+/**
+ * Aggregates `rows` (soft-deleted rows are skipped). Pass the blueprint
+ * entity so relation fields map to their `<name>Id` columns, enum groups keep
+ * their declared order (every value appears, even at zero), and money and
+ * dates are typed. Money sums stay integer cents; money and integer averages
+ * are rounded to integers.
+ */
+export function aggregate(rows, spec, entity) {
+    const kind = spec.aggregate ?? 'count';
+    if (kind !== 'count' && !spec.field) {
+        throw new RangeError(`aggregate(): "${kind}" needs a field`);
+    }
+    const valueField = spec.field ? fieldOf(entity, spec.field) : undefined;
+    const valueIsDate = valueField?.kind === 'date' ||
+        valueField?.kind === 'datetime' ||
+        (spec.field !== undefined && MANAGED_DATES.has(spec.field));
+    const valueKind = kind === 'count'
+        ? 'number'
+        : valueField?.kind === 'money'
+            ? 'money'
+            : valueIsDate
+                ? 'date'
+                : 'number';
+    const roundAvg = valueField?.kind === 'money' || valueField?.kind === 'integer';
+    const valueProp = spec.field ? propertyOf(entity, spec.field) : null;
+    const readValue = (row) => {
+        if (valueProp === null)
+            return null;
+        const raw = row[valueProp];
+        if (valueIsDate) {
+            const ms = toMs(raw);
+            return Number.isNaN(ms) ? null : ms;
+        }
+        return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+    };
+    const groupProp = spec.groupBy ? propertyOf(entity, spec.groupBy) : null;
+    const bucketProp = spec.bucket ? propertyOf(entity, spec.bucket.field) : null;
+    const unit = spec.bucket?.unit;
+    const keep = makeFilter(entity, spec.filter);
+    const total = newAcc();
+    const cells = new Map();
+    const seenGroups = new Set();
+    let firstBucket = Number.POSITIVE_INFINITY;
+    let lastBucket = Number.NEGATIVE_INFINITY;
+    for (const row of rows) {
+        if (row.deletedAt || !keep(row))
+            continue;
+        const value = readValue(row);
+        add(total, value);
+        let bucket = null;
+        if (bucketProp !== null && unit) {
+            const ms = toMs(row[bucketProp]);
+            if (Number.isNaN(ms))
+                continue; // no date: counted in total, not in a bucket
+            bucket = bucketStartUtc(ms, unit);
+            if (bucket < firstBucket)
+                firstBucket = bucket;
+            if (bucket > lastBucket)
+                lastBucket = bucket;
+        }
+        const groups = groupProp === null ? [null] : groupKeys(row[groupProp]);
+        for (const group of groups) {
+            if (group !== null)
+                seenGroups.add(group);
+            const key = `${bucket === null ? '*' : bucket}|${group ?? '*'}`;
+            let acc = cells.get(key);
+            if (!acc) {
+                acc = newAcc();
+                cells.set(key, acc);
+            }
+            add(acc, value);
+        }
+    }
+    // Group order: enum values as declared (all of them), then other seen values sorted.
+    let groups = [];
+    if (groupProp !== null) {
+        const declared = fieldOf(entity, spec.groupBy)?.kind === 'enum'
+            ? fieldOf(entity, spec.groupBy).values
+            : [];
+        const rest = [...seenGroups]
+            .filter((g) => g !== NO_GROUP && !declared.includes(g))
+            .sort((a, b) => a.localeCompare(b));
+        groups = [...declared, ...rest, ...(seenGroups.has(NO_GROUP) ? [NO_GROUP] : [])];
+    }
+    // Contiguous buckets over the range, or the data's span.
+    const buckets = [];
+    if (unit) {
+        let from = firstBucket;
+        let to = lastBucket;
+        if (spec.range) {
+            from = bucketStartUtc(toMs(spec.range.from), unit);
+            to = bucketStartUtc(toMs(spec.range.to), unit);
+            if (Number.isNaN(from) || Number.isNaN(to))
+                throw new RangeError('aggregate(): invalid range');
+        }
+        for (let b = from; b <= to; b = nextBucket(b, unit)) {
+            buckets.push(b);
+            if (buckets.length > MAX_BUCKETS) {
+                throw new RangeError(`aggregate(): more than ${MAX_BUCKETS} buckets`);
+            }
+        }
+    }
+    const cell = (bucket, group) => {
+        const key = `${bucket === null ? '*' : bucket}|${group ?? '*'}`;
+        const iso = bucket === null ? null : new Date(bucket).toISOString();
+        return {
+            key: `${iso ?? '*'}|${group ?? '*'}`,
+            bucket: iso,
+            group,
+            count: cells.get(key)?.count ?? 0,
+            value: finish(cells.get(key) ?? newAcc(), kind, roundAvg),
+        };
+    };
+    const series = [];
+    const bucketList = unit ? buckets : [null];
+    const groupList = groupProp === null ? [null] : groups;
+    for (const bucket of bucketList) {
+        for (const group of groupList)
+            series.push(cell(bucket, group));
+    }
+    return {
+        aggregate: kind,
+        valueKind,
+        total: {
+            key: '*|*',
+            bucket: null,
+            group: null,
+            count: total.count,
+            value: finish(total, kind, roundAvg),
+        },
+        series,
+        groups,
+        buckets: buckets.map((b) => new Date(b).toISOString()),
+    };
+}
+/**
+ * A querier for `liveQuery`: reads through the entity service (so
+ * `session.assert(<entity>:read)` applies) and resolves to null when the
+ * active persona cannot read the entity, like the generated Home counts.
+ */
+export function createAggregateQuery(services, spec) {
+    const service = services[spec.entity];
+    if (!service)
+        throw new RangeError(`createAggregateQuery(): unknown entity "${spec.entity}"`);
+    return async () => {
+        let rows;
+        try {
+            rows = await service.list();
+        }
+        catch (error) {
+            if (error instanceof PermissionDeniedError)
+                return null;
+            throw error;
+        }
+        return aggregate(rows, spec, service.entity);
+    };
+}

package/dist/app-model.d.ts

@@ -0,0 +1,76 @@
+import type { LayoutId } from '@protoyard/core';
+import { type Blueprint, type BlueprintEntity, type BlueprintScreen, type ScreenNavIcon, type ScreenType } from './schema.ts';
+interface AppRouteBase {
+    /** Stable route name (`home`, `deal-list`, `screen-BoardDeal`, `members`). */
+    readonly name: string;
+    /** Hash route path, with `:param` segments. */
+    readonly path: string;
+    readonly title: string;
+    readonly description: string;
+}
+/**
+ * What a route renders:
+ * - `home`: the built-in overview with a count per entity;
+ * - `members`: workspace people and their simulated roles;
+ * - `entity`: the entity page (list, create and edit), optionally claimed by
+ *   a `list`, `form` or tab-less `detail` screen;
+ * - `screen`: a blueprint screen with its own view component.
+ */
+export type AppRoute = (AppRouteBase & {
+    readonly view: 'home';
+}) | (AppRouteBase & {
+    readonly view: 'members';
+}) | (AppRouteBase & {
+    readonly view: 'entity';
+    readonly entity: string;
+    readonly screenIndex?: number;
+    readonly screenType?: ScreenType;
+}) | (AppRouteBase & {
+    readonly view: 'screen';
+    readonly screenIndex: number;
+    readonly screenType: ScreenType;
+    readonly entity?: string;
+    /** Unique component id for the screen (`Dashboard1Screen`, `BoardDealScreen`). */
+    readonly component: string;
+});
+/** What a route renders, without its name, path and labels. */
+export type AppRouteTarget = AppRoute extends infer R ? R extends AppRoute ? Omit<R, keyof AppRouteBase> : never : never;
+export interface AppNavItem {
+    readonly path: string;
+    readonly label: string;
+    readonly icon: ScreenNavIcon;
+    /** Active only on an exact path match (the home row). */
+    readonly exact?: true;
+}
+export interface AppNavGroup {
+    readonly label: string;
+    readonly paths: readonly string[];
+}
+export interface AppLayout {
+    readonly id: LayoutId;
+    readonly mobile?: LayoutId;
+}
+export interface AppModel {
+    /** Every route, in router order. */
+    readonly routes: readonly AppRoute[];
+    /** Sidebar rows: home, entities without a list screen, visible screens by nav order, members. */
+    readonly nav: readonly AppNavItem[];
+    /** Sectioned navigation (Overview, Records, Views, Workspace); empty groups are dropped. */
+    readonly navGroups: readonly AppNavGroup[];
+    readonly layout: AppLayout;
+    /** Every icon id the navigation may reference, in first-use order. */
+    readonly icons: readonly ScreenNavIcon[];
+}
+/** `support-tickets` → `Support tickets`, unless the entity sets `label`. */
+export declare function entityLabel(entity: Pick<BlueprintEntity, 'label' | 'plural'>): string;
+/** The icon a screen shows in navigation: its `nav.icon`, or the default for its kind. */
+export declare function screenNavIcon(screen: BlueprintScreen): ScreenNavIcon;
+/** True when a screen renders through its own component rather than the entity page. */
+export declare function screenHasOwnView(screen: BlueprintScreen): boolean;
+/**
+ * Derives the app model from a parsed blueprint. Pure and deterministic: the
+ * same blueprint always yields the same model, which matches what
+ * `protoyard generate` writes to `routes.ts` and `layout.ts`.
+ */
+export declare function deriveAppModel(blueprint: Blueprint): AppModel;
+export {};