@antelopejs/interface-dms 0.3.5 → 0.4.0

package/dist/base/banner.d.ts

@@ -0,0 +1,111 @@
+import { ComponentBuilder } from "../component";
+import { z } from "zod";
+import { type BlockLinkAction } from "./display";
+import type { BaseComponentProps } from "./types";
+import type { Tone } from "./types/tone";
+/** The tones a banner washes with. */
+export declare const BANNER_TONES: readonly ["info", "success", "warning", "error", "primary"];
+export type BannerTone = Extract<Tone, (typeof BANNER_TONES)[number]>;
+/** The sizes of a banner. */
+export declare const BANNER_SIZES: readonly ["md", "sm"];
+/** `md` boxed banner; `sm` compact one-line banner, for cards and panels. */
+export type BannerSize = (typeof BANNER_SIZES)[number];
+/** The options `Banner` takes. */
+export interface BannerProps extends BaseComponentProps {
+    /** `$`-prefixed for an i18n key, like every text of the block. */
+    title?: string;
+    description?: string;
+    tone?: BannerTone;
+    /** Overrides the tone's icon. */
+    icon?: string;
+    size?: BannerSize;
+    actions?: BlockLinkAction[];
+    /** Adds a close button; the dismissal is remembered. */
+    dismissible?: boolean;
+    /**
+     * Key the dismissal is remembered under (a cookie, one year). Defaults to
+     * the block's id on its page (`.child("welcome", Banner(…))` → `welcome`),
+     * which holds when blocks are added or moved; change it to show the banner
+     * again.
+     */
+    dismissKey?: string;
+}
+/**
+ * Banner — a notice across the top of a page or a card: a tinted wash, a
+ * boxed icon, a title and a line of explanation, with link actions and an
+ * optional dismiss that is remembered.
+ *
+ * Distinct from `RegisterLayoutBanner` (the dashboard-wide strip under the
+ * header): this one is a block placed on one page.
+ *
+ * @example
+ * ```typescript
+ * Banner({
+ *   tone: "warning",
+ *   title: "Beta",
+ *   description: "Numbers refresh every 15 minutes.",
+ *   dismissible: true,
+ *   dismissKey: "sales-beta-2026",
+ * })
+ * ```
+ */
+export declare function Banner(options?: BannerProps): ComponentBuilder<BannerProps>;
+/** The options `Banner` accepts. */
+export declare const BannerSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    actions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        to: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        variant: z.ZodOptional<z.ZodEnum<["solid", "outline", "soft", "subtle", "ghost", "link"]>>;
+        color: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+    }, "strip", z.ZodTypeAny, {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }, {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }>, "many">>;
+    tone: z.ZodDefault<z.ZodEnum<["primary" | "success" | "info" | "warning" | "error", ...("primary" | "success" | "info" | "warning" | "error")[]]>>;
+    icon: z.ZodOptional<z.ZodString>;
+    size: z.ZodDefault<z.ZodEnum<["md", "sm"]>>;
+    dismissible: z.ZodOptional<z.ZodBoolean>;
+    dismissKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    size: "sm" | "md";
+    tone: "primary" | "success" | "info" | "warning" | "error";
+    description?: string | undefined;
+    title?: string | undefined;
+    icon?: string | undefined;
+    actions?: {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }[] | undefined;
+    dismissible?: boolean | undefined;
+    dismissKey?: string | undefined;
+}, {
+    description?: string | undefined;
+    size?: "sm" | "md" | undefined;
+    title?: string | undefined;
+    icon?: string | undefined;
+    actions?: {
+        label: string;
+        to: string;
+        icon?: string | undefined;
+        variant?: "link" | "solid" | "outline" | "soft" | "ghost" | "subtle" | undefined;
+        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }[] | undefined;
+    tone?: "primary" | "success" | "info" | "warning" | "error" | undefined;
+    dismissible?: boolean | undefined;
+    dismissKey?: string | undefined;
+}>;

package/dist/base/banner.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BannerSchema = exports.BANNER_SIZES = exports.BANNER_TONES = void 0;
+exports.Banner = Banner;
+const component_1 = require("../component");
+const zod_1 = require("zod");
+const block_registry_1 = require("./block-registry");
+const display_1 = require("./display");
+const display_2 = require("./internal/display");
+/** The tones a banner washes with. */
+exports.BANNER_TONES = [
+    "info",
+    "success",
+    "warning",
+    "error",
+    "primary",
+];
+/** The sizes of a banner. */
+exports.BANNER_SIZES = ["md", "sm"];
+const BANNER_COMPONENT_NAME = "dms-banner-block";
+const BANNER_ICON = "i-ph-megaphone";
+const BANNER_DEFAULTS = { tone: "info", size: "md" };
+/**
+ * Banner — a notice across the top of a page or a card: a tinted wash, a
+ * boxed icon, a title and a line of explanation, with link actions and an
+ * optional dismiss that is remembered.
+ *
+ * Distinct from `RegisterLayoutBanner` (the dashboard-wide strip under the
+ * header): this one is a block placed on one page.
+ *
+ * @example
+ * ```typescript
+ * Banner({
+ *   tone: "warning",
+ *   title: "Beta",
+ *   description: "Numbers refresh every 15 minutes.",
+ *   dismissible: true,
+ *   dismissKey: "sales-beta-2026",
+ * })
+ * ```
+ */
+function Banner(options) {
+    return new component_1.ComponentBuilder(BANNER_COMPONENT_NAME)
+        .options({ ...BANNER_DEFAULTS, ...options })
+        .meta({
+        name: options?.title || "Banner",
+        icon: options?.icon || BANNER_ICON,
+    });
+}
+/** The options `Banner` accepts. */
+exports.BannerSchema = zod_1.z.object({
+    title: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "Title", group: "content" }),
+    description: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Description",
+        group: "content",
+        widget: "textarea",
+    }),
+    actions: (0, display_1.blockActionsOption)("Buttons on the right; the last one is the main action."),
+    tone: (0, block_registry_1.ui)((0, display_2.toneEnum)(exports.BANNER_TONES)
+        .default(BANNER_DEFAULTS.tone)
+        .describe("Colour of the wash and the icon."), { label: "Tone", group: "appearance", widget: "select" }),
+    icon: (0, block_registry_1.ui)(zod_1.z.string().optional().describe("Overrides the tone's icon."), {
+        label: "Icon",
+        group: "appearance",
+        widget: "icon",
+    }),
+    size: (0, block_registry_1.ui)(zod_1.z
+        .enum(exports.BANNER_SIZES)
+        .default(BANNER_DEFAULTS.size)
+        .describe("`sm` is the compact one-line banner."), {
+        label: "Size",
+        group: "appearance",
+        widget: "segmented",
+        valueLabels: { md: "Regular", sm: "Compact" },
+    }),
+    dismissible: (0, block_registry_1.ui)(zod_1.z.boolean().optional().describe("Adds a close button, remembered."), { label: "Dismissible", group: "behavior", widget: "switch" }),
+    dismissKey: (0, block_registry_1.ui)(zod_1.z
+        .string()
+        .optional()
+        .describe("Key the dismissal is remembered under; change it to reset."), { label: "Dismiss key", group: "behavior", advanced: true }),
+});
+(0, block_registry_1.RegisterBlockType)({
+    type: "Banner",
+    componentName: BANNER_COMPONENT_NAME,
+    schema: exports.BannerSchema,
+    meta: {
+        name: "Banner",
+        icon: BANNER_ICON,
+        description: "Notice with a tone, link actions and a remembered dismiss.",
+        group: "content",
+    },
+});
+//# sourceMappingURL=banner.js.map

package/dist/base/banner.js.map

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

package/dist/base/block-registry/helpers.d.ts

@@ -1,6 +1,32 @@
 import { type ZodType, type ZodTypeAny, type ZodTypeDef } from "zod";
 import type { BlockOptionUi } from "./types";
+/**
+ * A string option whose declared type is narrower than `string` — a
+ * template-literal union such as a colour value, or a branded id. The schema
+ * still validates as a string, so a builder UI keeps a text control.
+ */
 export declare function narrowString<T extends string>(): ZodType<T, ZodTypeDef, T>;
+/**
+ * An option the schema cannot describe structurally — a component instance, or
+ * a shape only meaningful to the factory. It validates anything; pair it with a
+ * `json` or `block` widget so the UI knows how to present it.
+ */
 export declare function opaqueOption<T>(): ZodType<T, ZodTypeDef, T>;
+/**
+ * An opaque option the factory cannot do without. `z.any()` accepts
+ * `undefined`, so a plain {@link opaqueOption} would let a missing required
+ * value validate; this one refuses it.
+ */
 export declare function requiredOpaqueOption<T>(): ZodType<T, ZodTypeDef, T>;
+/**
+ * Attach builder presentation hints to an option schema. The schema is returned
+ * unchanged, so `ui()` wraps a declaration in place:
+ *
+ * ```typescript
+ * icon: ui(z.string().optional(), { widget: "icon", group: "appearance" })
+ * ```
+ *
+ * Hints live in a side table rather than in the schema, so validation and type
+ * inference are untouched.
+ */
 export declare function ui<T extends ZodTypeAny>(schema: T, hints: BlockOptionUi): T;

package/dist/base/block-registry/helpers.js

@@ -5,19 +5,45 @@ exports.opaqueOption = opaqueOption;
 exports.requiredOpaqueOption = requiredOpaqueOption;
 exports.ui = ui;
 const zod_1 = require("zod");
-const ui_1 = require("./ui");
+const ui_1 = require("./internal/ui");
+/**
+ * A string option whose declared type is narrower than `string` — a
+ * template-literal union such as a colour value, or a branded id. The schema
+ * still validates as a string, so a builder UI keeps a text control.
+ */
 function narrowString() {
     const schema = zod_1.z.string();
     return schema;
 }
+/**
+ * An option the schema cannot describe structurally — a component instance, or
+ * a shape only meaningful to the factory. It validates anything; pair it with a
+ * `json` or `block` widget so the UI knows how to present it.
+ */
 function opaqueOption() {
     return zod_1.z.any();
 }
+/**
+ * An opaque option the factory cannot do without. `z.any()` accepts
+ * `undefined`, so a plain {@link opaqueOption} would let a missing required
+ * value validate; this one refuses it.
+ */
 function requiredOpaqueOption() {
     return zod_1.z.custom((value) => value !== undefined, {
         message: "Required",
     });
 }
+/**
+ * Attach builder presentation hints to an option schema. The schema is returned
+ * unchanged, so `ui()` wraps a declaration in place:
+ *
+ * ```typescript
+ * icon: ui(z.string().optional(), { widget: "icon", group: "appearance" })
+ * ```
+ *
+ * Hints live in a side table rather than in the schema, so validation and type
+ * inference are untouched.
+ */
 function ui(schema, hints) {
     ui_1.UI_HINTS.set(schema, hints);
     return schema;

package/dist/base/block-registry/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/base/block-registry/helpers.ts"],"names":[],"mappings":";;AASA,oCAGC;AAOD,oCAEC;AAOD,oDAIC;AAaD,gBAGC;AAhDD,6BAAwE;AAExE,6BAAgC;AAOhC,SAAgB,YAAY;IAC1B,MAAM,MAAM,GAAwC,OAAC,CAAC,MAAM,EAAE,CAAC;IAC/D,OAAO,MAAmC,CAAC;AAC7C,CAAC;AAOD,SAAgB,YAAY;IAC1B,OAAO,OAAC,CAAC,GAAG,EAA+B,CAAC;AAC9C,CAAC;AAOD,SAAgB,oBAAoB;IAClC,OAAO,OAAC,CAAC,MAAM,CAAI,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,EAAE;QACjD,OAAO,EAAE,UAAU;KACpB,CAAC,CAAC;AACL,CAAC;AAaD,SAAgB,EAAE,CAAuB,MAAS,EAAE,KAAoB;IACtE,aAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"helpers.js","sourceRoot":"","sources":["../../../src/base/block-registry/helpers.ts"],"names":[],"mappings":";;AASA,oCAGC;AAOD,oCAEC;AAOD,oDAIC;AAaD,gBAGC;AAhDD,6BAAwE;AAExE,sCAAyC;AAEzC;;;;GAIG;AACH,SAAgB,YAAY;IAC1B,MAAM,MAAM,GAAwC,OAAC,CAAC,MAAM,EAAE,CAAC;IAC/D,OAAO,MAAmC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY;IAC1B,OAAO,OAAC,CAAC,GAAG,EAA+B,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAgB,oBAAoB;IAClC,OAAO,OAAC,CAAC,MAAM,CAAI,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,EAAE;QACjD,OAAO,EAAE,UAAU;KACpB,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAgB,EAAE,CAAuB,MAAS,EAAE,KAAoB;IACtE,aAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC5B,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/base/block-registry/internal/describe.d.ts

@@ -0,0 +1,35 @@
+import { type ZodTypeAny } from "zod";
+import type { BlockOptionSchema } from "../types";
+/**
+ * A copy of a default value, so freezing a descriptor never reaches an object
+ * zod also holds — `.default(obj)` hands back that very instance on every
+ * parse, and a frozen one is unwritable for every consumer of the schema.
+ *
+ * `structuredClone` is used because it reproduces a `Date`, a `RegExp`, a `Map`
+ * and a `Set`; copying own properties, as a hand-rolled walk does, flattens
+ * every one of those to `{}`. A value it cannot clone — a function, a class
+ * instance — is not a describable default, and is passed through rather than
+ * lost.
+ *
+ * @internal
+ */
+export declare function cloneDefault<T>(value: T): T;
+/**
+ * Describe one option schema as a JSON-serializable shape.
+ *
+ * @internal
+ */
+export declare function describeSchema(schema: ZodTypeAny, depth?: number): BlockOptionSchema;
+/**
+ * Describe a block's whole options schema. A non-object schema yields an empty
+ * record, since a block's options are always a plain object.
+ *
+ * @internal
+ */
+export declare function describeOptions(schema?: ZodTypeAny): Record<string, BlockOptionSchema>;
+/**
+ * The default value of every option that declares one.
+ *
+ * @internal
+ */
+export declare function collectDefaults(described: Record<string, BlockOptionSchema>): Record<string, unknown>;

package/dist/base/block-registry/{describe.js → internal/describe.js}

@@ -7,6 +7,8 @@ exports.collectDefaults = collectDefaults;
 const zod_1 = require("zod");
 const ui_1 = require("./ui");
 const MAX_DEPTH = 6;
+// Wrappers nest independently of the shape's depth: optional-of-default-of-
+// nullable is three peels around a single node.
 const MAX_WRAPPERS = 8;
 const WRAPPER_INNER = {
     [zod_1.ZodFirstPartyTypeKind.ZodOptional]: (def) => def.innerType,
@@ -18,16 +20,24 @@ const WRAPPER_INNER = {
     [zod_1.ZodFirstPartyTypeKind.ZodBranded]: (def) => def.type,
     [zod_1.ZodFirstPartyTypeKind.ZodEffects]: (def) => def.schema,
     [zod_1.ZodFirstPartyTypeKind.ZodLazy]: (def) => def.getter(),
+    // The registry validates what a caller passes, so a pipeline describes its
+    // input rather than what it transforms into.
     [zod_1.ZodFirstPartyTypeKind.ZodPipeline]: (def) => def.in,
 };
 function defOf(schema) {
     return schema._def;
 }
+/**
+ * The walker reads zod 3's internal `_def.typeName`. A zod whose schemas carry
+ * none would describe every option as shapeless, which is worse than not
+ * answering at all — so say so instead.
+ */
 function assertDescribable(def) {
     if (def.typeName === undefined) {
         throw new Error("block-registry: this zod exposes no _def.typeName; the option walker supports zod 3");
     }
 }
+/** Peel wrappers off a schema, collecting the flags and hints they carry. */
 function unwrap(schema) {
     const result = {
         schema,
@@ -54,7 +64,12 @@ function unwrap(schema) {
         }
         current = inner(def);
     }
+    // The loop reads hints at the top of each turn, so the node it stops on has
+    // not been read yet — at exactly the budget its hints would be lost.
     hints.push((0, ui_1.getUiHints)(current));
+    // Still on a wrapper: the budget ran out rather than the walk finishing, and
+    // the node below is never described. Saying so beats reporting a shape that
+    // reads as "no structure".
     result.exhausted =
         peeled && WRAPPER_INNER[defOf(current).typeName] !== undefined;
     result.schema = current;
@@ -62,6 +77,19 @@ function unwrap(schema) {
     result.description = descriptions.find((entry) => !!entry);
     return result;
 }
+/**
+ * A copy of a default value, so freezing a descriptor never reaches an object
+ * zod also holds — `.default(obj)` hands back that very instance on every
+ * parse, and a frozen one is unwritable for every consumer of the schema.
+ *
+ * `structuredClone` is used because it reproduces a `Date`, a `RegExp`, a `Map`
+ * and a `Set`; copying own properties, as a hand-rolled walk does, flattens
+ * every one of those to `{}`. A value it cannot clone — a function, a class
+ * instance — is not a describable default, and is passed through rather than
+ * lost.
+ *
+ * @internal
+ */
 function cloneDefault(value) {
     if (typeof value !== "object" || value === null) {
         return value;
@@ -90,6 +118,7 @@ const PRIMITIVE = {
     [zod_1.ZodFirstPartyTypeKind.ZodMap]: "unknown",
     [zod_1.ZodFirstPartyTypeKind.ZodSet]: "unknown",
 };
+/** The kinds whose shape the walker descends into, and what they report as. */
 const STRUCTURED_TYPE = {
     [zod_1.ZodFirstPartyTypeKind.ZodObject]: "object",
     [zod_1.ZodFirstPartyTypeKind.ZodArray]: "array",
@@ -108,6 +137,7 @@ function literalType(value) {
     }
     return "string";
 }
+/** Collapse a union of single-value enums into one enum, as a picker wants it. */
 function mergeLiteralBranches(branches) {
     const values = [];
     for (const branch of branches) {
@@ -130,6 +160,8 @@ function describeUnion(def, depth) {
         return merged;
     }
     const discriminator = def.discriminator;
+    // The branches disagree on kind, so the union has none of its own: a consumer
+    // switches on `oneOf` rather than on `type`.
     const described = {
         type: "union",
         oneOf: branches,
@@ -179,10 +211,17 @@ const HANDLERS = {
         enum: Object.values(def.values),
     }),
 };
+/**
+ * Describe one option schema as a JSON-serializable shape.
+ *
+ * @internal
+ */
 function describeSchema(schema, depth = 0) {
     const unwrapped = unwrap(schema);
     const def = defOf(unwrapped.schema);
     assertDescribable(def);
+    // Past the depth bound the shape is not walked, but its kind is still known:
+    // reporting `unknown` would read as "no structure" rather than "more below".
     const truncated = unwrapped.exhausted === true ||
         (depth >= MAX_DEPTH && def.typeName in STRUCTURED_TYPE);
     const handler = truncated ? undefined : HANDLERS[def.typeName];
@@ -212,6 +251,12 @@ function describeShape(shape, depth) {
     }
     return described;
 }
+/**
+ * Describe a block's whole options schema. A non-object schema yields an empty
+ * record, since a block's options are always a plain object.
+ *
+ * @internal
+ */
 function describeOptions(schema) {
     if (!schema) {
         return {};
@@ -223,6 +268,11 @@ function describeOptions(schema) {
     }
     return describeShape(def.shape(), 0);
 }
+/**
+ * The default value of every option that declares one.
+ *
+ * @internal
+ */
 function collectDefaults(described) {
     const defaults = {};
     for (const [key, option] of Object.entries(described)) {

package/dist/base/block-registry/internal/describe.js.map

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

package/dist/base/block-registry/internal/ui.d.ts

@@ -0,0 +1,23 @@
+import type { ZodTypeAny } from "zod";
+import type { BlockOptionUi } from "../types";
+/**
+ * Hints live in a side table rather than in the schema, so validation and type
+ * inference are untouched. `ui()`, the declaration side, lives in `./helpers`
+ * with the other authoring helpers; reading them stays here.
+ *
+ * @internal
+ */
+export declare const UI_HINTS: WeakMap<ZodTypeAny, BlockOptionUi>;
+/**
+ * The hints attached to a schema node, if any.
+ *
+ * @internal
+ */
+export declare function getUiHints(schema: ZodTypeAny): BlockOptionUi | undefined;
+/**
+ * Merge hints collected while unwrapping a schema. Outer wrappers
+ * (`optional`, `default`) are visited first, so an inner hint wins.
+ *
+ * @internal
+ */
+export declare function mergeUiHints(hints: Array<BlockOptionUi | undefined>): BlockOptionUi | undefined;

package/dist/base/block-registry/internal/ui.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_HINTS = void 0;
+exports.getUiHints = getUiHints;
+exports.mergeUiHints = mergeUiHints;
+/**
+ * Hints live in a side table rather than in the schema, so validation and type
+ * inference are untouched. `ui()`, the declaration side, lives in `./helpers`
+ * with the other authoring helpers; reading them stays here.
+ *
+ * @internal
+ */
+exports.UI_HINTS = new WeakMap();
+/**
+ * The hints attached to a schema node, if any.
+ *
+ * @internal
+ */
+function getUiHints(schema) {
+    return exports.UI_HINTS.get(schema);
+}
+/**
+ * Merge hints collected while unwrapping a schema. Outer wrappers
+ * (`optional`, `default`) are visited first, so an inner hint wins.
+ *
+ * @internal
+ */
+function mergeUiHints(hints) {
+    const defined = hints.filter((hint) => !!hint);
+    if (defined.length === 0) {
+        return undefined;
+    }
+    return Object.assign({}, ...defined);
+}
+//# sourceMappingURL=ui.js.map

package/dist/base/block-registry/internal/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../../../../src/base/block-registry/internal/ui.ts"],"names":[],"mappings":";;;AAiBA,gCAEC;AAQD,oCAQC;AAhCD;;;;;;GAMG;AACU,QAAA,QAAQ,GAAG,IAAI,OAAO,EAA6B,CAAC;AAEjE;;;;GAIG;AACH,SAAgB,UAAU,CAAC,MAAkB;IAC3C,OAAO,gBAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAC1B,KAAuC;IAEvC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAyB,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/base/block-registry/registry.d.ts

@@ -1,19 +1,43 @@
 import type { ZodTypeAny } from "zod";
 import type { BlockTypeDefinition, BlockTypeDescriptor } from "./types";
+/**
+ * Declare a block type so builder tooling can list, describe and validate it.
+ * Called once per factory, next to the factory itself.
+ *
+ * A second registration under a name already taken replaces the first, which
+ * would let a third-party module quietly stand in for a core block. It is
+ * allowed, because a module reloaded in development re-runs its registrations,
+ * but it is reported so the collision is not silent.
+ */
 export declare function RegisterBlockType(definition: BlockTypeDefinition): void;
+/** Every declared block type, described and JSON-serializable. */
 export declare function ListBlockTypes(): BlockTypeDescriptor[];
+/** One declared block type, or `undefined` when the type is unknown. */
 export declare function GetBlockType(type: string): BlockTypeDescriptor | undefined;
+/** The raw options schema of a block type, for callers that hold zod. */
 export declare function GetBlockSchema(type: string): ZodTypeAny | undefined;
+/** A validation failure, addressed by a JSON pointer into the options object. */
 export interface BlockOptionIssue {
     pointer: string;
     message: string;
 }
+/** The options satisfy the block type's schema. */
 export interface BlockValidationOk {
     valid: true;
 }
+/** The options break the block type's schema, at each of `issues`. */
 export interface BlockValidationFailed {
     valid: false;
     issues: BlockOptionIssue[];
 }
+/** What {@link ValidateBlockOptions} answers. */
 export type BlockValidation = BlockValidationOk | BlockValidationFailed;
+/**
+ * Validate a block's options against its declared schema.
+ *
+ * A registered type that declares no schema validates: the caller cannot do
+ * better than the declaration allows. A type that is not registered at all is
+ * refused — the registry knows it is unknown, and answering "valid" to a
+ * misspelled block type would send the caller on to write it.
+ */
 export declare function ValidateBlockOptions(type: string, options: unknown): BlockValidation;