@panneau/protocol 5.0.0-alpha.4 → 5.0.0-alpha.5

package/dist/search.js

@@ -0,0 +1,53 @@
+//#region src/search.ts
+/** Shortest search, in characters once trimmed: shorter is a `422`. */
+var SEARCH_MIN_LENGTH = 2;
+/** Longest search, in characters. */
+var SEARCH_MAX_LENGTH = 255;
+/** Items per resource without a `limit`. */
+var SEARCH_DEFAULT_LIMIT = 5;
+/** Highest `limit`, and most items of a response, every resource together. */
+var SEARCH_MAX_LIMIT = 20;
+/**
+* Whether a resource is in the global search: its `features.search`, or, without it, whether its
+* list has a search (`list.search`), so one setting serves both (decision 0029).
+*/
+function isSearchableResource(resource) {
+	return resource.features?.search ?? resource.list?.search ?? false;
+}
+/** Serializes a search query: `q=été&limit=20&resources=pages,articles`. */
+function toSearchQueryParams(query) {
+	const params = new URLSearchParams({ q: query.q });
+	if (query.limit !== void 0) params.set("limit", String(query.limit));
+	if (query.resources !== void 0 && query.resources.length > 0) params.set("resources", query.resources.join(","));
+	return params;
+}
+/**
+* Reads the query string of `GET /search`: the reference of how a backend validates it. `q` is
+* trimmed and needs 2 characters; `limit` is an integer from 1 to 20; `resources` lists searchable
+* resources of the definition. Invalid parameters are a `422`, with `errors` keyed by parameter.
+* Without `resources`, every searchable resource is searched, in the order of the definition.
+*/
+function readSearchQuery(params, definition) {
+	const errors = {};
+	const q = (params.get("q") ?? "").trim();
+	if (q.length < 2) errors.q = [`The search must have at least 2 characters.`];
+	else if (q.length > 255) errors.q = [`The search must have at most 255 characters.`];
+	const rawLimit = params.get("limit");
+	const limit = rawLimit === null ? 5 : Number(rawLimit);
+	if (rawLimit !== null && (!/^\d+$/.test(rawLimit) || limit < 1 || limit > 20)) errors.limit = [`The limit must be an integer from 1 to 20.`];
+	const searchable = definition.resources.filter(isSearchableResource).map((resource) => resource.id);
+	const rawResources = params.get("resources");
+	const asked = rawResources === null ? searchable : rawResources.split(",").map((id) => id.trim()).filter((id) => id !== "");
+	const unknown = asked.filter((id) => !searchable.includes(id));
+	if (rawResources !== null && (asked.length === 0 || unknown.length > 0)) errors.resources = [unknown.length > 0 ? `These resources are not searchable: ${unknown.join(", ")}.` : "List at least one resource."];
+	if (Object.keys(errors).length > 0) return { errors };
+	return { query: {
+		q,
+		limit,
+		resources: searchable.filter((id) => asked.includes(id))
+	} };
+}
+//#endregion
+export { SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LENGTH, SEARCH_MAX_LIMIT, SEARCH_MIN_LENGTH, isSearchableResource, readSearchQuery, toSearchQueryParams };
+
+//# sourceMappingURL=search.js.map

package/dist/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","names":[],"sources":["../src/search.ts"],"sourcesContent":["/** Shortest search, in characters once trimmed: shorter is a `422`. */\nexport const SEARCH_MIN_LENGTH = 2;\n/** Longest search, in characters. */\nexport const SEARCH_MAX_LENGTH = 255;\n/** Items per resource without a `limit`. */\nexport const SEARCH_DEFAULT_LIMIT = 5;\n/** Highest `limit`, and most items of a response, every resource together. */\nexport const SEARCH_MAX_LIMIT = 20;\n\n/** What the global search reads of a resource. */\nexport interface SearchableResource {\n    id: string;\n    features?: { search?: boolean | undefined } | undefined;\n    list?: { search?: boolean | undefined } | undefined;\n}\n\n/** Query of the global search (`GET /search`). */\nexport interface SearchQuery {\n    q: string;\n    /** Items per resource, from 1 to 20. Defaults to 5. */\n    limit?: number;\n    /** Ids of the searchable resources to search. Defaults to every one. */\n    resources?: readonly string[];\n}\n\n/**\n * Whether a resource is in the global search: its `features.search`, or, without it, whether its\n * list has a search (`list.search`), so one setting serves both (decision 0029).\n */\nexport function isSearchableResource(resource: Omit<SearchableResource, 'id'>): boolean {\n    return resource.features?.search ?? resource.list?.search ?? false;\n}\n\n/** Serializes a search query: `q=été&limit=20&resources=pages,articles`. */\nexport function toSearchQueryParams(query: SearchQuery): URLSearchParams {\n    const params = new URLSearchParams({ q: query.q });\n    if (query.limit !== undefined) {\n        params.set('limit', String(query.limit));\n    }\n    if (query.resources !== undefined && query.resources.length > 0) {\n        params.set('resources', query.resources.join(','));\n    }\n    return params;\n}\n\n/** A search query as a backend reads it: valid, or the messages of its invalid parameters. */\nexport type ReadSearchQueryResult =\n    | { query: Required<SearchQuery>; errors?: undefined }\n    | { query?: undefined; errors: Record<string, string[]> };\n\n/**\n * Reads the query string of `GET /search`: the reference of how a backend validates it. `q` is\n * trimmed and needs 2 characters; `limit` is an integer from 1 to 20; `resources` lists searchable\n * resources of the definition. Invalid parameters are a `422`, with `errors` keyed by parameter.\n * Without `resources`, every searchable resource is searched, in the order of the definition.\n */\nexport function readSearchQuery(\n    params: URLSearchParams,\n    definition: { resources: readonly SearchableResource[] },\n): ReadSearchQueryResult {\n    const errors: Record<string, string[]> = {};\n    const q = (params.get('q') ?? '').trim();\n    if (q.length < SEARCH_MIN_LENGTH) {\n        errors.q = [`The search must have at least ${SEARCH_MIN_LENGTH} characters.`];\n    } else if (q.length > SEARCH_MAX_LENGTH) {\n        errors.q = [`The search must have at most ${SEARCH_MAX_LENGTH} characters.`];\n    }\n\n    const rawLimit = params.get('limit');\n    const limit = rawLimit === null ? SEARCH_DEFAULT_LIMIT : Number(rawLimit);\n    if (rawLimit !== null && (!/^\\d+$/.test(rawLimit) || limit < 1 || limit > SEARCH_MAX_LIMIT)) {\n        errors.limit = [`The limit must be an integer from 1 to ${SEARCH_MAX_LIMIT}.`];\n    }\n\n    const searchable = definition.resources\n        .filter(isSearchableResource)\n        .map((resource) => resource.id);\n    const rawResources = params.get('resources');\n    const asked =\n        rawResources === null\n            ? searchable\n            : rawResources\n                  .split(',')\n                  .map((id) => id.trim())\n                  .filter((id) => id !== '');\n    const unknown = asked.filter((id) => !searchable.includes(id));\n    if (rawResources !== null && (asked.length === 0 || unknown.length > 0)) {\n        errors.resources = [\n            unknown.length > 0\n                ? `These resources are not searchable: ${unknown.join(', ')}.`\n                : 'List at least one resource.',\n        ];\n    }\n\n    if (Object.keys(errors).length > 0) {\n        return { errors };\n    }\n    // The order of the definition, without duplicates\n    const resources = searchable.filter((id) => asked.includes(id));\n    return { query: { q, limit, resources } };\n}\n"],"mappings":";;AACA,IAAa,oBAAoB;;AAEjC,IAAa,oBAAoB;;AAEjC,IAAa,uBAAuB;;AAEpC,IAAa,mBAAmB;;;;;AAsBhC,SAAgB,qBAAqB,UAAmD;CACpF,OAAO,SAAS,UAAU,UAAU,SAAS,MAAM,UAAU;AACjE;;AAGA,SAAgB,oBAAoB,OAAqC;CACrE,MAAM,SAAS,IAAI,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAAC;CACjD,IAAI,MAAM,UAAU,KAAA,GAChB,OAAO,IAAI,SAAS,OAAO,MAAM,KAAK,CAAC;CAE3C,IAAI,MAAM,cAAc,KAAA,KAAa,MAAM,UAAU,SAAS,GAC1D,OAAO,IAAI,aAAa,MAAM,UAAU,KAAK,GAAG,CAAC;CAErD,OAAO;AACX;;;;;;;AAaA,SAAgB,gBACZ,QACA,YACqB;CACrB,MAAM,SAAmC,CAAC;CAC1C,MAAM,KAAK,OAAO,IAAI,GAAG,KAAK,GAAA,CAAI,KAAK;CACvC,IAAI,EAAE,SAAA,GACF,OAAO,IAAI,CAAC,6CAAgE;MACzE,IAAI,EAAE,SAAA,KACT,OAAO,IAAI,CAAC,8CAA+D;CAG/E,MAAM,WAAW,OAAO,IAAI,OAAO;CACnC,MAAM,QAAQ,aAAa,OAAA,IAA8B,OAAO,QAAQ;CACxE,IAAI,aAAa,SAAS,CAAC,QAAQ,KAAK,QAAQ,KAAK,QAAQ,KAAK,QAAA,KAC9D,OAAO,QAAQ,CAAC,4CAA6D;CAGjF,MAAM,aAAa,WAAW,UACzB,OAAO,oBAAoB,CAAC,CAC5B,KAAK,aAAa,SAAS,EAAE;CAClC,MAAM,eAAe,OAAO,IAAI,WAAW;CAC3C,MAAM,QACF,iBAAiB,OACX,aACA,aACK,MAAM,GAAG,CAAC,CACV,KAAK,OAAO,GAAG,KAAK,CAAC,CAAC,CACtB,QAAQ,OAAO,OAAO,EAAE;CACvC,MAAM,UAAU,MAAM,QAAQ,OAAO,CAAC,WAAW,SAAS,EAAE,CAAC;CAC7D,IAAI,iBAAiB,SAAS,MAAM,WAAW,KAAK,QAAQ,SAAS,IACjE,OAAO,YAAY,CACf,QAAQ,SAAS,IACX,uCAAuC,QAAQ,KAAK,IAAI,EAAE,KAC1D,6BACV;CAGJ,IAAI,OAAO,KAAK,MAAM,CAAC,CAAC,SAAS,GAC7B,OAAO,EAAE,OAAO;CAIpB,OAAO,EAAE,OAAO;EAAE;EAAG;EAAO,WADV,WAAW,QAAQ,OAAO,MAAM,SAAS,EAAE,CACjC;CAAU,EAAE;AAC5C"}

package/dist/transforms.d.ts

@@ -0,0 +1,17 @@
+import type { MediaTransform } from './schemas/api';
+/** The ratio of `width:height` (`16:9` gives 1.777…), or null when it isn't one. */
+export declare function parseRatio(ratio: string): number | null;
+/**
+ * Whether a size has a ratio (decision 0031): its height is within one pixel of its width divided
+ * by the ratio, since crops are in whole pixels.
+ */
+export declare function matchesRatio(width: number, height: number, ratio: number | string): boolean;
+/**
+ * The size of the crop of a transform as it is rendered: a quarter turn swaps its width and its
+ * height. Null without a crop.
+ */
+export declare function renderedCropSize(transform: Pick<MediaTransform, 'crop' | 'rotate'>): {
+    width: number;
+    height: number;
+} | null;
+//# sourceMappingURL=transforms.d.ts.map

package/dist/transforms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.d.ts","sourceRoot":"","sources":["../src/transforms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAGpD,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAG3F;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC5B,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC,GACnD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ1C"}

package/dist/transforms.js

@@ -0,0 +1,34 @@
+import { isRecord } from "./values.js";
+//#region src/transforms.ts
+/** The ratio of `width:height` (`16:9` gives 1.777…), or null when it isn't one. */
+function parseRatio(ratio) {
+	const match = /^([1-9][0-9]*):([1-9][0-9]*)$/.exec(ratio);
+	return match === null ? null : Number(match[1]) / Number(match[2]);
+}
+/**
+* Whether a size has a ratio (decision 0031): its height is within one pixel of its width divided
+* by the ratio, since crops are in whole pixels.
+*/
+function matchesRatio(width, height, ratio) {
+	const value = typeof ratio === "number" ? ratio : parseRatio(ratio);
+	return value !== null && value > 0 && Math.abs(width / value - height) <= 1;
+}
+/**
+* The size of the crop of a transform as it is rendered: a quarter turn swaps its width and its
+* height. Null without a crop.
+*/
+function renderedCropSize(transform) {
+	const crop = transform.crop;
+	if (!isRecord(crop) || typeof crop.width !== "number" || typeof crop.height !== "number") return null;
+	return transform.rotate === 90 || transform.rotate === 270 ? {
+		width: crop.height,
+		height: crop.width
+	} : {
+		width: crop.width,
+		height: crop.height
+	};
+}
+//#endregion
+export { matchesRatio, parseRatio, renderedCropSize };
+
+//# sourceMappingURL=transforms.js.map

package/dist/transforms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transforms.js","names":[],"sources":["../src/transforms.ts"],"sourcesContent":["import type { MediaTransform } from './schemas/api';\nimport { isRecord } from './values';\n\n/** The ratio of `width:height` (`16:9` gives 1.777…), or null when it isn't one. */\nexport function parseRatio(ratio: string): number | null {\n    const match = /^([1-9][0-9]*):([1-9][0-9]*)$/.exec(ratio);\n    return match === null ? null : Number(match[1]) / Number(match[2]);\n}\n\n/**\n * Whether a size has a ratio (decision 0031): its height is within one pixel of its width divided\n * by the ratio, since crops are in whole pixels.\n */\nexport function matchesRatio(width: number, height: number, ratio: number | string): boolean {\n    const value = typeof ratio === 'number' ? ratio : parseRatio(ratio);\n    return value !== null && value > 0 && Math.abs(width / value - height) <= 1;\n}\n\n/**\n * The size of the crop of a transform as it is rendered: a quarter turn swaps its width and its\n * height. Null without a crop.\n */\nexport function renderedCropSize(\n    transform: Pick<MediaTransform, 'crop' | 'rotate'>,\n): { width: number; height: number } | null {\n    const crop = transform.crop;\n    if (!isRecord(crop) || typeof crop.width !== 'number' || typeof crop.height !== 'number') {\n        return null;\n    }\n    return transform.rotate === 90 || transform.rotate === 270\n        ? { width: crop.height, height: crop.width }\n        : { width: crop.width, height: crop.height };\n}\n"],"mappings":";;;AAIA,SAAgB,WAAW,OAA8B;CACrD,MAAM,QAAQ,gCAAgC,KAAK,KAAK;CACxD,OAAO,UAAU,OAAO,OAAO,OAAO,MAAM,EAAE,IAAI,OAAO,MAAM,EAAE;AACrE;;;;;AAMA,SAAgB,aAAa,OAAe,QAAgB,OAAiC;CACzF,MAAM,QAAQ,OAAO,UAAU,WAAW,QAAQ,WAAW,KAAK;CAClE,OAAO,UAAU,QAAQ,QAAQ,KAAK,KAAK,IAAI,QAAQ,QAAQ,MAAM,KAAK;AAC9E;;;;;AAMA,SAAgB,iBACZ,WACwC;CACxC,MAAM,OAAO,UAAU;CACvB,IAAI,CAAC,SAAS,IAAI,KAAK,OAAO,KAAK,UAAU,YAAY,OAAO,KAAK,WAAW,UAC5E,OAAO;CAEX,OAAO,UAAU,WAAW,MAAM,UAAU,WAAW,MACjD;EAAE,OAAO,KAAK;EAAQ,QAAQ,KAAK;CAAM,IACzC;EAAE,OAAO,KAAK;EAAO,QAAQ,KAAK;CAAO;AACnD"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@panneau/protocol",
-    "version": "5.0.0-alpha.4",
+    "version": "5.0.0-alpha.5",
     "description": "The Panneau protocol: definition schema, HTTP API spec and conformance kit",
     "type": "module",
     "license": "MIT",

package/schema/boot.schema.json

@@ -200,6 +200,12 @@
                 "itemTitle": {
                     "type": "string"
                 },
+                "itemSubtitle": {
+                    "type": "string"
+                },
+                "itemImage": {
+                    "type": "string"
+                },
                 "fields": {
                     "type": "array",
                     "items": {
@@ -306,7 +312,20 @@
                     "type": "boolean"
                 },
                 "resource": {
-                    "type": "string"
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        {
+                            "minItems": 1,
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "minLength": 1
+                            }
+                        }
+                    ]
                 },
                 "accept": {
                     "type": "array",
@@ -314,9 +333,33 @@
                         "type": "string"
                     }
                 },
+                "ratios": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[1-9][0-9]*:[1-9][0-9]*$"
+                    }
+                },
+                "rotate": {
+                    "type": "boolean"
+                },
+                "focalPoint": {
+                    "type": "boolean"
+                },
+                "transformBase": {
+                    "type": "string",
+                    "enum": [
+                        "media",
+                        "original",
+                        "choose"
+                    ]
+                },
                 "from": {
                     "type": "string"
                 },
+                "check": {
+                    "type": "boolean"
+                },
                 "display": {
                     "type": "string"
                 },
@@ -542,6 +585,39 @@
                     ],
                     "additionalProperties": {}
                 },
+                {
+                    "type": "object",
+                    "properties": {
+                        "rule": {
+                            "type": "string",
+                            "const": "crop"
+                        },
+                        "value": {
+                            "type": "object",
+                            "properties": {
+                                "ratios": {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "string",
+                                        "pattern": "^[1-9][0-9]*:[1-9][0-9]*$"
+                                    }
+                                },
+                                "required": {
+                                    "type": "boolean"
+                                }
+                            },
+                            "additionalProperties": {}
+                        },
+                        "message": {
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "rule",
+                        "value"
+                    ],
+                    "additionalProperties": {}
+                },
                 {
                     "type": "object",
                     "properties": {
@@ -1463,6 +1539,9 @@
                 },
                 "abilities": {
                     "$ref": "#/$defs/Abilities"
+                },
+                "resource": {
+                    "type": "string"
                 }
             },
             "required": [

package/schema/definition.schema.json

@@ -166,6 +166,12 @@
                 "itemTitle": {
                     "type": "string"
                 },
+                "itemSubtitle": {
+                    "type": "string"
+                },
+                "itemImage": {
+                    "type": "string"
+                },
                 "fields": {
                     "type": "array",
                     "items": {
@@ -272,7 +278,20 @@
                     "type": "boolean"
                 },
                 "resource": {
-                    "type": "string"
+                    "anyOf": [
+                        {
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        {
+                            "minItems": 1,
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "minLength": 1
+                            }
+                        }
+                    ]
                 },
                 "accept": {
                     "type": "array",
@@ -280,9 +299,33 @@
                         "type": "string"
                     }
                 },
+                "ratios": {
+                    "type": "array",
+                    "items": {
+                        "type": "string",
+                        "pattern": "^[1-9][0-9]*:[1-9][0-9]*$"
+                    }
+                },
+                "rotate": {
+                    "type": "boolean"
+                },
+                "focalPoint": {
+                    "type": "boolean"
+                },
+                "transformBase": {
+                    "type": "string",
+                    "enum": [
+                        "media",
+                        "original",
+                        "choose"
+                    ]
+                },
                 "from": {
                     "type": "string"
                 },
+                "check": {
+                    "type": "boolean"
+                },
                 "display": {
                     "type": "string"
                 },
@@ -508,6 +551,39 @@
                     ],
                     "additionalProperties": {}
                 },
+                {
+                    "type": "object",
+                    "properties": {
+                        "rule": {
+                            "type": "string",
+                            "const": "crop"
+                        },
+                        "value": {
+                            "type": "object",
+                            "properties": {
+                                "ratios": {
+                                    "type": "array",
+                                    "items": {
+                                        "type": "string",
+                                        "pattern": "^[1-9][0-9]*:[1-9][0-9]*$"
+                                    }
+                                },
+                                "required": {
+                                    "type": "boolean"
+                                }
+                            },
+                            "additionalProperties": {}
+                        },
+                        "message": {
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "rule",
+                        "value"
+                    ],
+                    "additionalProperties": {}
+                },
                 {
                     "type": "object",
                     "properties": {
@@ -1429,6 +1505,9 @@
                 },
                 "abilities": {
                     "$ref": "#/$defs/Abilities"
+                },
+                "resource": {
+                    "type": "string"
                 }
             },
             "required": [