@openbrf/plugin-sdk 0.0.0-stage → 1.2.0

package/dist/blocks.d.ts

@@ -0,0 +1,310 @@
+import { z } from "zod";
+import type { PluginAbortSignal } from "./abort-signal.ts";
+import type { PluginSettingsValues } from "./settings-schema.ts";
+/**
+ * Blocks a plugin adds to the association's website.
+ *
+ * A page on the website is a list of blocks, never markup (ADR 0006), and a
+ * plugin's block is one more type in that list. The manifest declares it - its
+ * name, how the page editor offers it and the settings the board fills in - and
+ * the server bundle registers the function that renders it. The host does the
+ * rest: it offers the block in the editor, validates the settings on every
+ * save, calls the render function while it renders the page, and decides what
+ * of the answer reaches the visitor's browser.
+ *
+ * What the render function returns is a small tree of elements rather than a
+ * string of HTML. The host reads it against a short list of elements and
+ * attributes and prints what passes through the same renderer as the rest of
+ * the page, so a script, a stylesheet, an event handler or a picture from
+ * another host has no way into the markup however the tree was built. The
+ * website's content security policy refuses all four as well; the list is what
+ * keeps the page from carrying them at all.
+ */
+/**
+ * The name of one block, unique within its plugin.
+ *
+ * The block's type id is composed by the host as `<plugin id>/<name>`, which is
+ * what a page stores, so two plugins cannot claim one type and no plugin can
+ * claim one of the core's. The name has a core block's own shape: a
+ * lowerCamelCase word of at most 32 characters.
+ */
+export declare const PLUGIN_BLOCK_NAME_PATTERN: RegExp;
+/** The type id a page stores a plugin's block under. */
+export declare function pluginBlockType(pluginId: string, name: string): string;
+/**
+ * The pictures the page editor can show beside a plugin's block.
+ *
+ * A name rather than an image, as for the core's blocks: the editor draws each
+ * one in the theme's own colours, and a manifest carries no markup. `plugin` is
+ * the one to choose when none of the others says what the block is.
+ */
+export declare const PLUGIN_BLOCK_ICONS: readonly ["plugin", "paragraph", "heading", "image", "form", "news", "calendar", "documents", "people", "facts", "contact", "questions"];
+export type PluginBlockIcon = (typeof PLUGIN_BLOCK_ICONS)[number];
+/**
+ * Where the page editor files a plugin's block.
+ *
+ * The core's categories, less `layout`: a layout block arranges other blocks,
+ * and a plugin's block holds none.
+ */
+export declare const PLUGIN_BLOCK_CATEGORIES: readonly ["text", "media", "association"];
+export type PluginBlockCategory = (typeof PLUGIN_BLOCK_CATEGORIES)[number];
+/**
+ * One block a plugin declares, as the manifest carries it.
+ *
+ * `labelKey` is an i18n key in the plugin's own namespace, like every other
+ * label a manifest names. The settings are the same declaration the plugin's
+ * own settings form is made of, and the page editor renders them as a form on
+ * the block: one set of values per block on a page, validated by the host on
+ * every save.
+ */
+export declare const pluginBlockSchema: z.ZodObject<{
+    name: z.ZodString;
+    labelKey: z.ZodString;
+    icon: z.ZodDefault<z.ZodEnum<{
+        calendar: "calendar";
+        contact: "contact";
+        documents: "documents";
+        facts: "facts";
+        form: "form";
+        heading: "heading";
+        image: "image";
+        news: "news";
+        paragraph: "paragraph";
+        people: "people";
+        plugin: "plugin";
+        questions: "questions";
+    }>>;
+    category: z.ZodDefault<z.ZodEnum<{
+        association: "association";
+        media: "media";
+        text: "text";
+    }>>;
+    settingsSchema: z.ZodDefault<z.ZodObject<{
+        fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"text">;
+            default: z.ZodOptional<z.ZodString>;
+            minLength: z.ZodOptional<z.ZodInt>;
+            maxLength: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"number">;
+            default: z.ZodOptional<z.ZodNumber>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            integer: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"boolean">;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"select">;
+            default: z.ZodOptional<z.ZodString>;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                labelKey: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"secret">;
+            minLength: z.ZodOptional<z.ZodInt>;
+            maxLength: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+export type PluginBlockDeclaration = z.infer<typeof pluginBlockSchema>;
+/**
+ * The blocks a manifest declares. At most sixteen, each name once.
+ *
+ * A name appearing twice would be one type id with two renderers, and a page
+ * that holds it would render with whichever registered last.
+ */
+export declare const pluginBlocksSchema: z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    labelKey: z.ZodString;
+    icon: z.ZodDefault<z.ZodEnum<{
+        calendar: "calendar";
+        contact: "contact";
+        documents: "documents";
+        facts: "facts";
+        form: "form";
+        heading: "heading";
+        image: "image";
+        news: "news";
+        paragraph: "paragraph";
+        people: "people";
+        plugin: "plugin";
+        questions: "questions";
+    }>>;
+    category: z.ZodDefault<z.ZodEnum<{
+        association: "association";
+        media: "media";
+        text: "text";
+    }>>;
+    settingsSchema: z.ZodDefault<z.ZodObject<{
+        fields: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"text">;
+            default: z.ZodOptional<z.ZodString>;
+            minLength: z.ZodOptional<z.ZodInt>;
+            maxLength: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"number">;
+            default: z.ZodOptional<z.ZodNumber>;
+            min: z.ZodOptional<z.ZodNumber>;
+            max: z.ZodOptional<z.ZodNumber>;
+            integer: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"boolean">;
+            default: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"select">;
+            default: z.ZodOptional<z.ZodString>;
+            options: z.ZodArray<z.ZodObject<{
+                value: z.ZodString;
+                labelKey: z.ZodString;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            labelKey: z.ZodString;
+            hintKey: z.ZodOptional<z.ZodString>;
+            required: z.ZodDefault<z.ZodBoolean>;
+            type: z.ZodLiteral<"secret">;
+            minLength: z.ZodOptional<z.ZodInt>;
+            maxLength: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>>;
+}, z.core.$strict>>;
+/**
+ * The elements a rendered block may contain.
+ *
+ * Text and its structure, and nothing that loads, runs or styles anything. An
+ * element outside this list is left out together with everything inside it,
+ * because what an unknown element holds is not text the plugin meant a reader
+ * to see: the body of a script, a stylesheet, a template.
+ *
+ * Headings start at the second level, as a page's own blocks do: the page's
+ * title is its first-level heading.
+ */
+export declare const PLUGIN_BLOCK_ELEMENTS: readonly ["p", "h2", "h3", "h4", "ul", "ol", "li", "dl", "dt", "dd", "strong", "em", "small", "code", "blockquote", "a", "br", "span", "div", "section", "table", "caption", "thead", "tbody", "tfoot", "tr", "th", "td", "time"];
+export type PluginBlockElementName = (typeof PLUGIN_BLOCK_ELEMENTS)[number];
+/**
+ * The attributes an element may carry, by element. Every other one is left out.
+ *
+ *   href      on `a`: http, https, mailto or a path on this instance. Any other
+ *             address - `javascript:` above all - leaves the link out and keeps
+ *             its text. A link to another host is given noopener and
+ *             noreferrer by the host.
+ *   dateTime  on `time`: the machine-readable date beside the one shown.
+ *   scope     on `th`: `row`, `col`, `rowgroup` or `colgroup`.
+ *
+ * No `class`, no `style` and no `id`: the theme decides how the website looks,
+ * and the host wraps every plugin's block in one element the theme can style.
+ */
+export declare const PLUGIN_BLOCK_ATTRIBUTES: Readonly<Partial<Record<PluginBlockElementName, readonly string[]>>>;
+/** One element of a rendered block. */
+export interface PluginBlockElement {
+    readonly tag: PluginBlockElementName;
+    readonly attributes?: Readonly<Record<string, string>>;
+    readonly children?: readonly PluginBlockNode[];
+}
+/**
+ * A piece of a rendered block: text, or an element.
+ *
+ * Text is text. It is escaped as it is printed, so `"<b>"` reads as the three
+ * characters and is never an element.
+ */
+export type PluginBlockNode = string | PluginBlockElement;
+/** What a render function answers with. Null, or nothing, renders nothing. */
+export type PluginBlockContent = PluginBlockNode | readonly PluginBlockNode[] | null | undefined;
+/**
+ * What a block's render function is told.
+ *
+ * The block's own settings, already validated against its declaration with
+ * the declared defaults applied, and the reader's language with a translation
+ * function in the plugin's own namespace. Nothing about the reader: the same
+ * page is rendered for a visitor with no account and for a member, and what a
+ * block may say must not depend on who is reading it.
+ */
+export interface PluginBlockRenderContext {
+    /** The block's type id, `<plugin id>/<name>`. */
+    readonly type: string;
+    readonly settings: PluginSettingsValues;
+    /** The language the page is being rendered in: `sv` or `en`. */
+    readonly locale: string;
+    /** Translates a key from the plugin's own locale files. */
+    readonly t: (key: string, values?: Readonly<Record<string, string | number>>) => string;
+    /**
+     * Aborted when the host stops waiting for this block.
+     *
+     * A render that has not answered within PLUGIN_BLOCK_RENDER_TIMEOUT_MS is
+     * left off the page, and the page is sent without it. The host cannot stop
+     * the plugin's code, so a render doing slow work of its own should hand this
+     * on to whatever it is waiting for.
+     */
+    readonly signal: PluginBlockAbortSignal;
+}
+/**
+ * The `AbortSignal` a render function is given. See {@link PluginAbortSignal}.
+ */
+export type PluginBlockAbortSignal = PluginAbortSignal;
+/**
+ * How long the host waits for one block to render, in milliseconds.
+ *
+ * Every block on a page renders at the same time, so this is also about the
+ * longest a plugin can add to a page's answer. A website's front page has to
+ * answer quickly for a visitor with no account, and a block that cannot is
+ * left off rather than waited for.
+ */
+export declare const PLUGIN_BLOCK_RENDER_TIMEOUT_MS = 2000;
+/** What a plugin hands the host for one block its manifest declared. */
+export interface PluginBlockRegistration {
+    /** The block's name as the manifest declares it, not its type id. */
+    readonly name: string;
+    readonly render: (context: PluginBlockRenderContext) => PluginBlockContent | Promise<PluginBlockContent>;
+}
+export interface PluginBlocks {
+    /**
+     * Registers the render function of a block the manifest declared.
+     *
+     * Callable from the module factory onwards, as `host.actions.register` is: a
+     * call made before the application exists is kept until it does. A name the
+     * manifest does not declare stops the plugin serving and is reported as
+     * `block-refused`. A declared block with no render function registered is
+     * not offered in the page editor, and a page that already holds one shows
+     * nothing in its place.
+     */
+    register: (registration: PluginBlockRegistration) => void;
+}
+//# sourceMappingURL=blocks.d.ts.map

package/dist/blocks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.d.ts","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}

package/dist/blocks.js

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import { pluginSettingsSchema } from "./settings-schema.js";
+/**
+ * Blocks a plugin adds to the association's website.
+ *
+ * A page on the website is a list of blocks, never markup (ADR 0006), and a
+ * plugin's block is one more type in that list. The manifest declares it - its
+ * name, how the page editor offers it and the settings the board fills in - and
+ * the server bundle registers the function that renders it. The host does the
+ * rest: it offers the block in the editor, validates the settings on every
+ * save, calls the render function while it renders the page, and decides what
+ * of the answer reaches the visitor's browser.
+ *
+ * What the render function returns is a small tree of elements rather than a
+ * string of HTML. The host reads it against a short list of elements and
+ * attributes and prints what passes through the same renderer as the rest of
+ * the page, so a script, a stylesheet, an event handler or a picture from
+ * another host has no way into the markup however the tree was built. The
+ * website's content security policy refuses all four as well; the list is what
+ * keeps the page from carrying them at all.
+ */
+/**
+ * The name of one block, unique within its plugin.
+ *
+ * The block's type id is composed by the host as `<plugin id>/<name>`, which is
+ * what a page stores, so two plugins cannot claim one type and no plugin can
+ * claim one of the core's. The name has a core block's own shape: a
+ * lowerCamelCase word of at most 32 characters.
+ */
+export const PLUGIN_BLOCK_NAME_PATTERN = /^[a-z][a-zA-Z0-9]{0,31}$/;
+/** The type id a page stores a plugin's block under. */
+export function pluginBlockType(pluginId, name) {
+    return `${pluginId}/${name}`;
+}
+/**
+ * The pictures the page editor can show beside a plugin's block.
+ *
+ * A name rather than an image, as for the core's blocks: the editor draws each
+ * one in the theme's own colours, and a manifest carries no markup. `plugin` is
+ * the one to choose when none of the others says what the block is.
+ */
+export const PLUGIN_BLOCK_ICONS = [
+    "plugin",
+    "paragraph",
+    "heading",
+    "image",
+    "form",
+    "news",
+    "calendar",
+    "documents",
+    "people",
+    "facts",
+    "contact",
+    "questions",
+];
+/**
+ * Where the page editor files a plugin's block.
+ *
+ * The core's categories, less `layout`: a layout block arranges other blocks,
+ * and a plugin's block holds none.
+ */
+export const PLUGIN_BLOCK_CATEGORIES = [
+    "text",
+    "media",
+    "association",
+];
+/**
+ * One block a plugin declares, as the manifest carries it.
+ *
+ * `labelKey` is an i18n key in the plugin's own namespace, like every other
+ * label a manifest names. The settings are the same declaration the plugin's
+ * own settings form is made of, and the page editor renders them as a form on
+ * the block: one set of values per block on a page, validated by the host on
+ * every save.
+ */
+export const pluginBlockSchema = z.strictObject({
+    name: z
+        .string()
+        .regex(PLUGIN_BLOCK_NAME_PATTERN, "must be a lowerCamelCase word of at most 32 characters"),
+    labelKey: z.string().min(1).max(200),
+    icon: z.enum(PLUGIN_BLOCK_ICONS).default("plugin"),
+    category: z.enum(PLUGIN_BLOCK_CATEGORIES).default("association"),
+    /*
+     * No secret field. A block's values are stored in the page that holds it
+     * and are read by whoever renders the page, so a credential there would be
+     * published with it.
+     */
+    settingsSchema: pluginSettingsSchema
+        .refine((schema) => schema.fields.every((field) => field.type !== "secret"), {
+        message: "a block's settings may not declare a secret field: they are published with the page",
+    })
+        .default({ fields: [] }),
+});
+/**
+ * The blocks a manifest declares. At most sixteen, each name once.
+ *
+ * A name appearing twice would be one type id with two renderers, and a page
+ * that holds it would render with whichever registered last.
+ */
+export const pluginBlocksSchema = z
+    .array(pluginBlockSchema)
+    .max(16)
+    .superRefine((blocks, ctx) => {
+    const seen = new Set();
+    for (const [index, block] of blocks.entries()) {
+        if (seen.has(block.name)) {
+            ctx.addIssue({
+                code: "custom",
+                path: [index, "name"],
+                message: `two blocks are declared with the name "${block.name}"`,
+            });
+        }
+        seen.add(block.name);
+    }
+});
+/**
+ * The elements a rendered block may contain.
+ *
+ * Text and its structure, and nothing that loads, runs or styles anything. An
+ * element outside this list is left out together with everything inside it,
+ * because what an unknown element holds is not text the plugin meant a reader
+ * to see: the body of a script, a stylesheet, a template.
+ *
+ * Headings start at the second level, as a page's own blocks do: the page's
+ * title is its first-level heading.
+ */
+export const PLUGIN_BLOCK_ELEMENTS = [
+    "p",
+    "h2",
+    "h3",
+    "h4",
+    "ul",
+    "ol",
+    "li",
+    "dl",
+    "dt",
+    "dd",
+    "strong",
+    "em",
+    "small",
+    "code",
+    "blockquote",
+    "a",
+    "br",
+    "span",
+    "div",
+    "section",
+    "table",
+    "caption",
+    "thead",
+    "tbody",
+    "tfoot",
+    "tr",
+    "th",
+    "td",
+    "time",
+];
+/**
+ * The attributes an element may carry, by element. Every other one is left out.
+ *
+ *   href      on `a`: http, https, mailto or a path on this instance. Any other
+ *             address - `javascript:` above all - leaves the link out and keeps
+ *             its text. A link to another host is given noopener and
+ *             noreferrer by the host.
+ *   dateTime  on `time`: the machine-readable date beside the one shown.
+ *   scope     on `th`: `row`, `col`, `rowgroup` or `colgroup`.
+ *
+ * No `class`, no `style` and no `id`: the theme decides how the website looks,
+ * and the host wraps every plugin's block in one element the theme can style.
+ */
+export const PLUGIN_BLOCK_ATTRIBUTES = {
+    a: ["href"],
+    time: ["dateTime"],
+    th: ["scope"],
+};
+/**
+ * How long the host waits for one block to render, in milliseconds.
+ *
+ * Every block on a page renders at the same time, so this is also about the
+ * longest a plugin can add to a page's answer. A website's front page has to
+ * answer quickly for a visitor with no account, and a block that cannot is
+ * left off rather than waited for.
+ */
+export const PLUGIN_BLOCK_RENDER_TIMEOUT_MS = 2000;
+//# sourceMappingURL=blocks.js.map

package/dist/blocks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks.js","sourceRoot":"","sources":["../src/blocks.ts"],"names":[],"mappings":"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"}