@protobase/layout 0.19.16 → 0.20.0

package/dist/block-specs.js

@@ -102,6 +102,23 @@ const blockSpecs = {
 			span: optional("span")
 		}
 	},
+	Chart: {
+		children: false,
+		props: {
+			...heading,
+			resource: required("text"),
+			filter: optional("text"),
+			groupBy: required("text"),
+			type: optional("chartType"),
+			sum: optional("text"),
+			average: optional("text"),
+			granularity: optional("bucket"),
+			range: optional("range"),
+			limit: optional("integer"),
+			empty: optional("text"),
+			span: optional("span")
+		}
+	},
 	Progress: {
 		children: false,
 		props: {
@@ -159,6 +176,26 @@ const variants = [
 	"danger",
 	"ghost"
 ];
+const chartTypes = [
+	"bar",
+	"line",
+	"donut"
+];
+const buckets = [
+	"hour",
+	"day",
+	"week",
+	"month",
+	"year"
+];
+const ranges = [
+	"7d",
+	"30d",
+	"90d",
+	"1y",
+	"all"
+];
+const oneOf = (values) => [(value) => typeof value === "string" && values.includes(value), values.join(", ")];
 const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const checks = {
 	text: [(value) => typeof value === "string", "text"],
@@ -174,6 +211,9 @@ const checks = {
 	label: [(value) => typeof value === "string" || value === false, "text, or false for none"],
 	amount: [(value) => typeof value === "string" || typeof value === "number" && Number.isFinite(value), "a number or a field name"],
 	scalar: [(value) => typeof value === "string" || typeof value === "number", "text or a number"],
+	chartType: oneOf(chartTypes),
+	bucket: oneOf(buckets),
+	range: oneOf(ranges),
 	address: [(value) => isObject(value) && !isLayoutNode(value) && typeof value.kind === "string", "an address, such as { kind: 'list', resource: 'orders' }"]
 };
 /** Problems with one element's props and children against its block's spec. */

package/dist/blocks.d.ts

@@ -83,6 +83,34 @@ export type RecordRowProps = DataProps & Heading & {
   empty?: string;
   span?: GridSpan;
 };
+/** How a chart draws its groups: bars, a line through a date field's buckets, or a donut of a field's values. */
+export type ChartType = 'bar' | 'line' | 'donut';
+/** How long each bucket of a chart over a date or timestamp field is. */
+export type ChartBucket = 'hour' | 'day' | 'week' | 'month' | 'year';
+/**
+ * Records of `resource` matching `filter`, grouped and added up as a chart: how many have each value of `groupBy`, or
+ * fall in each bucket of it when it is a date or timestamp field, or with `sum` or `average` that of a numeric field.
+ */
+export type ChartProps = Heading & {
+  resource: string;
+  filter?: string;
+  /** A filterable field, such as an enum, a boolean or a relation; an index must serve it. */
+  groupBy: string;
+  /** Default `bar`; `line` is for a date `groupBy`, `donut` for one of values. */
+  type?: ChartType;
+  /** A numeric field each group adds up, instead of counting its records. */
+  sum?: string;
+  /** A numeric field each group averages, instead of counting its records. */
+  average?: string;
+  /** A date `groupBy`'s bucket; default `day`. */
+  granularity?: ChartBucket;
+  /** How far back a date `groupBy` reaches; default `30d`. */
+  range?: '7d' | '30d' | '90d' | '1y' | 'all';
+  /** How many values a chart of values shows, the largest; default 10. */
+  limit?: number;
+  empty?: string;
+  span?: GridSpan;
+};
 export type ProgressProps = {
   /** A number, or a field of the record around it. */
   value: number | string;
@@ -137,6 +165,7 @@ export declare const Field: Block<FieldProps>;
 export declare const Table: Block<TableProps>;
 export declare const CardRow: Block<CardRowProps>;
 export declare const RecordRow: Block<RecordRowProps>;
+export declare const Chart: Block<ChartProps>;
 export declare const Progress: Block<ProgressProps>;
 export declare const ModalForm: Block<ModalFormProps>;
 export declare const Action: Block<ActionProps>;

package/dist/blocks.js

@@ -9,10 +9,11 @@ const Field = defineBlock("Field", false);
 const Table = defineBlock("Table", false);
 const CardRow = defineBlock("CardRow", false);
 const RecordRow = defineBlock("RecordRow", false);
+const Chart = defineBlock("Chart", false);
 const Progress = defineBlock("Progress", false);
 const ModalForm = defineBlock("ModalForm", false);
 const Action = defineBlock("Action", false);
 const Show = defineBlock("Show", false);
 const Link = defineBlock("Link", false);
 //#endregion
-export { Action, Card, CardRow, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, RecordRow, Show, Stat, Table };
+export { Action, Card, CardRow, Chart, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, RecordRow, Show, Stat, Table };

package/dist/check-chart.js

@@ -0,0 +1,51 @@
+//#region src/check-chart.ts
+const numericTypes = [
+	"integer",
+	"bigint",
+	"decimal"
+];
+const ungroupable = ["json", "file"];
+const text = (value) => typeof value === "string" ? value : void 0;
+/** Whether a chart's `groupBy` is a date or timestamp field, which it buckets, rather than a field of values. */
+const isDatedGroup = (field) => field?.type === "date" || field?.type === "timestamp";
+/** The fields a chart reads: the one it groups by, and the one it adds up when it has `sum` or `average`. */
+const chartFields = (node) => [text(node.props.groupBy), text(node.props.sum) ?? text(node.props.average)].filter((name) => name !== void 0);
+const fieldOf = (model, name) => Object.hasOwn(model.fields, name) ? model.fields[name] : void 0;
+const groupProblems = (model, name) => {
+	const field = fieldOf(model, name);
+	if (!field) return [`groupBy: unknown field "${name}" on ${model.name}`];
+	if (field.sensitive) return [`groupBy: "${name}" is sensitive, so a chart cannot show its values`];
+	if (ungroupable.includes(field.type)) return [`groupBy: "${name}" is a ${field.type} field, which has no values to group by`];
+	return field.filterable ? [] : [`groupBy: "${name}" is not filterable, so the API refuses to group by it: mark "${name}" .filterable()`];
+};
+const measureProblems = (model, prop, name) => {
+	const field = fieldOf(model, name);
+	if (!field) return [`${prop}: unknown field "${name}" on ${model.name}`];
+	if (field.sensitive) return [`${prop}: "${name}" is sensitive, so a chart cannot add it up`];
+	return numericTypes.includes(field.type) ? [] : [`${prop}: "${name}" is ${field.type}, and only a number can be added up`];
+};
+const shapeProblems = (node, dated) => {
+	const type = text(node.props.type) ?? "bar";
+	const given = (names) => names.filter((name) => node.props[name] !== void 0);
+	if (dated) return [...type === "donut" ? ["a donut shares out values, so it needs a groupBy of values, not dates"] : [], ...given(["limit"]).map((name) => `"${name}" is for a groupBy of values, not dates`)];
+	return [
+		...type === "line" ? ["a line runs through time, so it needs a date or timestamp groupBy"] : [],
+		...type === "donut" && node.props.average !== void 0 ? ["a donut shares out a total, and averages add up to none: count or sum instead"] : [],
+		...given(["granularity", "range"]).map((name) => `"${name}" is for a date or timestamp groupBy`)
+	];
+};
+/** What a chart names that its resource does not allow: the field it groups by, the one it adds up, and its shape. */
+const chartProblems = (node, model) => {
+	const groupBy = String(node.props.groupBy);
+	const sum = text(node.props.sum);
+	const average = text(node.props.average);
+	const grouped = groupProblems(model, groupBy);
+	return [
+		...grouped,
+		...sum !== void 0 ? measureProblems(model, "sum", sum) : [],
+		...average !== void 0 ? measureProblems(model, "average", average) : [],
+		...grouped.length === 0 ? shapeProblems(node, isDatedGroup(fieldOf(model, groupBy))) : []
+	];
+};
+//#endregion
+export { chartFields, chartProblems, isDatedGroup };

package/dist/check-page.js

@@ -1,6 +1,7 @@
 import { dataProps } from "./node.js";
 import { countedResource, parseCondition } from "./condition.js";
 import { walkTree } from "./walk.js";
+import { chartProblems } from "./check-chart.js";
 import { resolveFieldPath } from "./field-path.js";
 import { checkFilter, checkOrderBy, parseFilter, parseOrderBy } from "@protobase/schema";
 import { addressErrors, fieldRefsIn } from "@protobase/schema/internal";
@@ -49,6 +50,9 @@ const nodeProblems = (node, scope, { models, actions, pages }) => {
 		case "Stat":
 			if (text(node.props.field) !== void 0) path(String(node.props.field));
 			break;
+		case "Chart":
+			if (model) problems.push(...chartProblems(node, model));
+			break;
 		case "Progress":
 			for (const name of [node.props.value, node.props.max]) if (typeof name === "string") path(name);
 			break;

package/dist/check-structure.js

@@ -25,6 +25,7 @@ const statProblems = ({ props }) => {
 	].filter((name) => props[name] !== void 0).length !== 1) return ["takes exactly one of \"value\", \"resource\" (a count) and \"field\""];
 	return props.filter !== void 0 && props.resource === void 0 ? ["\"filter\" needs \"resource\""] : [];
 };
+const chartStructureProblems = ({ props }) => props.sum !== void 0 && props.average !== void 0 ? ["takes \"sum\" or \"average\", not both"] : [];
 const linkProblems = ({ props }) => {
 	if (props.to === void 0 === (props.href === void 0)) return ["takes exactly one of \"to\" (an address in the app) and \"href\" (a link that leaves it)"];
 	const error = typeof props.href === "string" ? appHrefError(props.href) : void 0;
@@ -47,6 +48,7 @@ const structureProblems = (tree) => {
 		propProblems(spec, node.props, node.children.length).forEach(report);
 		recordProblems(node, scope).forEach(report);
 		if (node.type === "Stat") statProblems(node).forEach(report);
+		if (node.type === "Chart") chartStructureProblems(node).forEach(report);
 		if (node.type === "Link") linkProblems(node).forEach(report);
 		if (node.type === "Show" && typeof node.props.when === "string") {
 			const parsed = parseCondition(node.props.when);

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { Block, LayoutChild, LayoutChildren, LayoutNode, LayoutValue, isLayoutNode } from "./node.js";
-import { Action, ActionProps, ButtonVariant, Card, CardProps, CardRow, CardRowProps, DataProps, Elements, Field, FieldProps, Grid, GridProps, GridSpan, Link, LinkProps, ModalForm, ModalFormProps, Page, PageProps, Progress, ProgressProps, RecordCard, RecordCardProps, RecordRow, RecordRowProps, Show, ShowProps, Stat, StatProps, Table, TableProps } from "./blocks.js";
+import { Action, ActionProps, ButtonVariant, Card, CardProps, CardRow, CardRowProps, Chart, ChartBucket, ChartProps, ChartType, DataProps, Elements, Field, FieldProps, Grid, GridProps, GridSpan, Link, LinkProps, ModalForm, ModalFormProps, Page, PageProps, Progress, ProgressProps, RecordCard, RecordCardProps, RecordRow, RecordRowProps, Show, ShowProps, Stat, StatProps, Table, TableProps } from "./blocks.js";
 import { ComponentOptions, component } from "./component.js";
 import { PageDefinition, PageModel, PageOptions, isPageDefinition, page } from "./page.js";
 import { Location, walkTree } from "./walk.js";
@@ -9,4 +9,4 @@ import { countedResource, evaluateCondition, parseCondition } from "./condition.
 import { PathStep, resolveFieldPath } from "./field-path.js";
 import { jsx_runtime_d_exports } from "./jsx-runtime.js";
 import { FieldRefValue, fieldRef } from "@protobase/schema";
-export { Action, type ActionProps, type Block, type ButtonVariant, Card, type CardProps, CardRow, type CardRowProps, type ComponentOptions, type DataProps, type Elements, Field, type FieldProps, type FieldRefValue, Grid, type GridProps, type GridSpan, type LayoutChild, type LayoutChildren, type LayoutNode, type LayoutValue, Link, type LinkProps, type Location, ModalForm, type ModalFormProps, Page, type PageDefinition, type PageModel, type PageOptions, type PageProps, type PathStep, Progress, type ProgressProps, RecordCard, type RecordCardProps, RecordRow, type RecordRowProps, Show, type ShowProps, Stat, type StatProps, Table, type TableProps, checkPages, component, countedResource, evaluateCondition, fieldRef, isLayoutNode, isPageDefinition, jsx_runtime_d_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath, walkTree };
+export { Action, type ActionProps, type Block, type ButtonVariant, Card, type CardProps, CardRow, type CardRowProps, Chart, type ChartBucket, type ChartProps, type ChartType, type ComponentOptions, type DataProps, type Elements, Field, type FieldProps, type FieldRefValue, Grid, type GridProps, type GridSpan, type LayoutChild, type LayoutChildren, type LayoutNode, type LayoutValue, Link, type LinkProps, type Location, ModalForm, type ModalFormProps, Page, type PageDefinition, type PageModel, type PageOptions, type PageProps, type PathStep, Progress, type ProgressProps, RecordCard, type RecordCardProps, RecordRow, type RecordRowProps, Show, type ShowProps, Stat, type StatProps, Table, type TableProps, checkPages, component, countedResource, evaluateCondition, fieldRef, isLayoutNode, isPageDefinition, jsx_runtime_d_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath, walkTree };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { isLayoutNode } from "./node.js";
-import { Action, Card, CardRow, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, RecordRow, Show, Stat, Table } from "./blocks.js";
+import { Action, Card, CardRow, Chart, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, RecordRow, Show, Stat, Table } from "./blocks.js";
 import { component } from "./component.js";
 import { countedResource, evaluateCondition, parseCondition } from "./condition.js";
 import { walkTree } from "./walk.js";
@@ -9,4 +9,4 @@ import { checkPages } from "./check-page.js";
 import { prunePage } from "./prune-page.js";
 import { jsx_runtime_exports } from "./jsx-runtime.js";
 import { fieldRef } from "@protobase/schema";
-export { Action, Card, CardRow, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, RecordRow, Show, Stat, Table, checkPages, component, countedResource, evaluateCondition, fieldRef, isLayoutNode, isPageDefinition, jsx_runtime_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath, walkTree };
+export { Action, Card, CardRow, Chart, Field, Grid, Link, ModalForm, Page, Progress, RecordCard, RecordRow, Show, Stat, Table, checkPages, component, countedResource, evaluateCondition, fieldRef, isLayoutNode, isPageDefinition, jsx_runtime_exports as jsxRuntime, page, parseCondition, prunePage, resolveFieldPath, walkTree };

package/dist/prune-page.js

@@ -1,6 +1,7 @@
 import { dataProps } from "./node.js";
 import { countedResource, parseCondition } from "./condition.js";
 import { mapTree } from "./walk.js";
+import { chartFields } from "./check-chart.js";
 import { resolveFieldPath } from "./field-path.js";
 import { elementResource, linkSource } from "./check-page.js";
 import { checkFilter, checkOrderBy, parseFilter, parseOrderBy } from "@protobase/schema";
@@ -37,6 +38,7 @@ const prune = (node, scope, access) => {
 	switch (node.type) {
 		case "Field": return readable(String(node.props.name)) ? node : null;
 		case "Stat": return text(node.props.field) === void 0 || readable(String(node.props.field)) ? node : null;
+		case "Chart": return model && chartFields(node).every((name) => Object.hasOwn(model.fields, name)) ? node : null;
 		case "Progress": return [node.props.value, node.props.max].every((name) => typeof name !== "string" || readable(name)) ? node : null;
 		case "Table": {
 			const columns = node.props.columns;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protobase/layout",
-  "version": "0.19.16",
+  "version": "0.20.0",
   "description": "Composed pages for Protobase, written as JSX that compiles to plain data, with its JSX runtime.",
   "license": "Apache-2.0",
   "repository": {
@@ -31,7 +31,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@protobase/schema": "0.19.16",
+    "@protobase/schema": "0.20.0",
     "aip-parsers": "^1.0.0"
   }
 }