@antelopejs/interface-dms 0.3.5 → 0.4.0

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

@@ -5,9 +5,18 @@ exports.ListBlockTypes = ListBlockTypes;
 exports.GetBlockType = GetBlockType;
 exports.GetBlockSchema = GetBlockSchema;
 exports.ValidateBlockOptions = ValidateBlockOptions;
-const describe_1 = require("./describe");
+const describe_1 = require("./internal/describe");
 const DEFINITIONS = new Map();
 const DESCRIPTORS = new Map();
+/**
+ * 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.
+ */
 function RegisterBlockType(definition) {
     const previous = DEFINITIONS.get(definition.type);
     if (previous && previous !== definition) {
@@ -28,6 +37,14 @@ function describe(definition) {
         descriptor.childMeta = (0, describe_1.describeOptions)(childMeta);
     return descriptor;
 }
+/**
+ * Descriptors are cached and shared, so they are frozen: a consumer that
+ * normalised one in place would otherwise corrupt every later read.
+ *
+ * Defaults are cloned rather than frozen in place: zod hands back the very
+ * object passed to `.default()` on every parse, so freezing it would make that
+ * shared instance unwritable for every other consumer of the schema.
+ */
 function deepFreeze(value) {
     if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
         return value;
@@ -46,16 +63,20 @@ function descriptorOf(definition) {
     DESCRIPTORS.set(definition.type, descriptor);
     return descriptor;
 }
+/** Every declared block type, described and JSON-serializable. */
 function ListBlockTypes() {
     return Array.from(DEFINITIONS.values()).map(descriptorOf);
 }
+/** One declared block type, or `undefined` when the type is unknown. */
 function GetBlockType(type) {
     const definition = DEFINITIONS.get(type);
     return definition ? descriptorOf(definition) : undefined;
 }
+/** The raw options schema of a block type, for callers that hold zod. */
 function GetBlockSchema(type) {
     return DEFINITIONS.get(type)?.schema;
 }
+/** RFC 6901: the root is the empty string, and `~` and `/` are escaped. */
 function jsonPointer(path) {
     if (path.length === 0) {
         return "";
@@ -63,6 +84,14 @@ function jsonPointer(path) {
     const escaped = path.map((segment) => String(segment).replaceAll("~", "~0").replaceAll("/", "~1"));
     return `/${escaped.join("/")}`;
 }
+/**
+ * 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.
+ */
 function ValidateBlockOptions(type, options) {
     if (!DEFINITIONS.has(type)) {
         return {

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

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

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

@@ -1,34 +1,137 @@
 import type { ZodType, ZodTypeAny, ZodTypeDef } from "zod";
+/**
+ * Asserts an options schema against the factory's own options type: a schema
+ * whose input drifts from the interface stops compiling.
+ *
+ * ```typescript
+ * export const GridSchema = z.object({ … }) satisfies BlockOptionsFor<GridOptions>;
+ * ```
+ */
 export type BlockOptionsFor<Options> = ZodType<unknown, ZodTypeDef, Options>;
+/**
+ * The editor control a block option is best edited with. `text` is the fallback
+ * when no hint is declared and the option is a plain string.
+ */
 export type BlockOptionWidget = "text" | "textarea" | "number" | "range" | "switch" | "select" | "segmented" | "icon" | "color" | "url" | "resource" | "field" | "dataType" | "query" | "dataSource" | "permission" | "json" | "block";
+/** Presentation hints a builder UI applies to one option. */
 export interface BlockOptionUi {
+    /** Human label; defaults to the option key when absent. */
     label?: string;
     widget?: BlockOptionWidget;
+    /** Section the option is grouped under in the config panel. */
     group?: BlockOptionGroup;
+    /** Sort order within the group; unordered options follow declaration order. */
     order?: number;
+    /** Excluded from the config panel (transport-only options). */
     hidden?: boolean;
     placeholder?: string;
     min?: number;
     max?: number;
     step?: number;
+    /**
+     * Dotted path to the option whose value scopes this one — a `field` widget
+     * scoped by the block's resource, for instance.
+     */
     scope?: string;
+    /** Block types accepted by a `block` widget. */
     blockTypes?: string[];
+    /**
+     * The options of the block a `block` widget holds that this block supplies
+     * itself, which an editor leaves out: a card fetches the series its chart
+     * draws and heads it, so the chart's own source and title are never read.
+     */
     supplies?: string[];
+    /**
+     * The aspect(s) a `field` widget's value must carry on the resource. Sorting
+     * on a field that is not sortable, or filtering on one that is not
+     * filterable, is written and then ignored at runtime — so the option says
+     * which aspects it needs and the value is checked against every one of them.
+     *
+     * An option may need more than one: a Kanban groups by a field it both reads
+     * off the listed row and filters each column with.
+     */
     fieldAspect?: FieldAspect | FieldAspect[];
+    /**
+     * Render an object option's own properties in its group rather than nested
+     * under its label — a set of switches that reads as one list of features.
+     */
     flatten?: boolean;
+    /**
+     * What to call each value of an enum, keyed by the value. An editor shows
+     * these in place of the raw values: `Last 30 days` rather than
+     * `last-30-days`.
+     */
     valueLabels?: Record<string, string>;
+    /**
+     * The sibling option this one's value can be derived from — a field's key
+     * from its label. An editor may write it itself, and keep it following that
+     * option for as long as nobody has set it by hand, sparing an author a name
+     * that only code reads.
+     */
     derivedFrom?: string;
+    /**
+     * The switch this option sits behind, by its label. Options naming the same
+     * one are offered together once an author turns it on, and left out — the
+     * block falling back on its own behaviour — while it is off.
+     */
     optIn?: string;
+    /**
+     * The sibling option holding the data type this value is one of — a field's
+     * default takes the field's own type. An editor offers the input that type
+     * calls for, and keeps the JSON box for a type it has none for.
+     */
     typedBy?: string;
+    /**
+     * Offered in an editor's advanced view only: a setting that is an address,
+     * a method or a key is written for whoever reads the code, and an editor's
+     * simple view writes it for its author instead.
+     */
     advanced?: boolean;
+    /**
+     * What an editor places a new block with, when that is not what the option
+     * defaults to: a form placed by hand shows its buttons from the start.
+     */
     initial?: unknown;
+    /**
+     * What the block does with what it fetches, for a `dataSource` option.
+     *
+     * A source editor offers only the calculations whose answer this block can
+     * read: a card wants one number, a chart wants one point per group, a ranked
+     * list wants those points as entries. Without it an editor would let someone
+     * wire a series into a slot that renders a single value.
+     */
     responseShape?: BlockResponseShape;
+    /**
+     * The option this block reads its period from, for a `dataSource` option.
+     *
+     * Binding a source to a period means writing two options at once — the source
+     * itself, and the scope it follows — and only the block knows what its own
+     * period option is called.
+     */
     periodOption?: string;
 }
+/**
+ * The shape of the answer a block reads from its data source.
+ *
+ * `value` is one number, `series` one point per group, `items` those points as a
+ * ranked list, and `card` a number and its series together.
+ */
 export type BlockResponseShape = "value" | "series" | "items" | "card";
+/**
+ * A resource aspect a field must carry for an option naming it to work at
+ * runtime: listed by the list route, full-text searchable, sortable, or
+ * column-filterable.
+ */
 export type FieldAspect = "listable" | "searchable" | "sortable" | "filterable";
+/** The sections a config panel lays its options out in, in this order. */
 export type BlockOptionGroup = "content" | "features" | "data" | "appearance" | "layout" | "behavior" | "advanced";
+/** The primitive kinds a described option can reduce to. */
 export type BlockOptionType = "string" | "number" | "boolean" | "object" | "array" | "record" | "union" | "unknown";
+/**
+ * A JSON-serializable description of one option, derived from its zod schema.
+ * Nested shapes are described recursively through `properties`, `items`,
+ * `values` and `oneOf`.
+ */
 export interface BlockOptionSchema {
     type: BlockOptionType;
     optional?: boolean;
@@ -36,49 +139,95 @@ export interface BlockOptionSchema {
     description?: string;
     default?: unknown;
     enum?: Array<string | number | boolean>;
+    /** Object shape, keyed by property name. */
     properties?: Record<string, BlockOptionSchema>;
+    /** Array element shape. */
     items?: BlockOptionSchema;
+    /** Record value shape. */
     values?: BlockOptionSchema;
+    /**
+     * Record key shape. A key drawn from a closed set carries it as `enum`, so
+     * an editor can offer one entry per key rather than a free-form object.
+     */
     keys?: BlockOptionSchema;
+    /** Union branches, in declaration order. */
     oneOf?: BlockOptionSchema[];
+    /** Property carrying the branch tag of a discriminated union. */
     discriminator?: string;
+    /** Positional element shapes of a tuple, in order. */
     prefixItems?: BlockOptionSchema[];
+    /** Shapes a value must satisfy at once, for an intersection. */
     allOf?: BlockOptionSchema[];
+    /**
+     * The shape is deeper than the walker describes. What is reported is accurate
+     * as far as it goes; the value has more structure below it.
+     */
     truncated?: boolean;
     ui?: BlockOptionUi;
 }
+/** A named region a container block renders its children into. */
 export interface BlockSlotDefinition {
     id: string;
     label?: string;
     description?: string;
 }
+/**
+ * A container whose slots are declared by its own options rather than fixed —
+ * `Tab`, whose `items[].slot` names each region.
+ */
 export interface BlockDynamicSlots {
+    /** Dotted path to the option array holding the slot descriptors. */
     optionPath: string;
+    /** Property of each entry holding the slot id. */
     idKey: string;
+    /** Property of each entry holding the slot label. */
     labelKey?: string;
 }
+/** Palette metadata for a block type. */
 export interface BlockTypeMeta {
     name: string;
     icon?: string;
     description?: string;
+    /** Palette section, e.g. `layout` | `data` | `visualization`. */
     group?: BlockTypeGroup;
 }
 export type BlockTypeGroup = "layout" | "content" | "data" | "visualization";
+/** A block type as declared next to its factory. */
 export interface BlockTypeDefinition {
+    /** Factory export name — the catalog key, e.g. `KpiCard`. */
     type: string;
+    /** Frontend component name the factory emits, e.g. `dms-kpi-card`. */
     componentName: string;
     meta: BlockTypeMeta;
+    /**
+     * Options schema; absent for a factory taking none.
+     *
+     * `watchActions` is deliberately left out of every declaration: it carries the
+     * reactivity wiring `.watch()` emits, not a value an author sets by hand, so a
+     * builder has no business offering it.
+     */
     schema?: ZodTypeAny;
+    /** Whether the block accepts `.child(...)`. */
     container?: boolean;
+    /** Block types accepted as children; any type when absent. */
     allowedChildren?: string[];
     slots?: BlockSlotDefinition[];
     dynamicSlots?: BlockDynamicSlots;
+    /** Schema of the metadata a child carries, e.g. `{ colSpan }`. */
     childMeta?: ZodTypeAny;
+    /**
+     * Options the factory sets itself, whatever the caller passes — a chart's
+     * `type`, which is what tells `dms-chart` which chart to draw. A consumer
+     * rendering from the descriptor alone has to merge these in.
+     */
     fixedOptions?: Record<string, unknown>;
+    /** Whether the factory takes a leading controller class before its options. */
     controllerArg?: boolean;
 }
+/** A block type as reported by `ListBlockTypes`, with its schemas described. */
 export interface BlockTypeDescriptor extends Omit<BlockTypeDefinition, "schema" | "childMeta"> {
     config: Record<string, BlockOptionSchema>;
     childMeta?: Record<string, BlockOptionSchema>;
+    /** Option values the factory applies when the caller omits them. */
     defaults: Record<string, unknown>;
 }

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

@@ -1,16 +1,36 @@
-import "./chart-schemas";
+/**
+ * Side-effect barrel registering every built-in block type.
+ *
+ * Importing it populates the block registry without pulling in the parts of
+ * `dms-base` that need a running DMS (database models, export jobs), so builder
+ * tooling can read the catalog on its own.
+ *
+ * Both surfaces are re-exported: reading a block type and declaring one. A
+ * module registering its own block reaches `RegisterBlockType` through here, so
+ * the helpers its schema needs — `ui`, `narrowString`, `opaqueOption` — have to
+ * be reachable from the same place.
+ */
+import "./activity-feed";
+import "./banner";
+import "./card";
+import "./internal/chart-schemas";
 import "./chart-card";
+import "./empty-state";
 import "./form-block-schema";
 import "./grid";
+import "./key-value-list";
 import "./kpi-card";
+import "./meter";
+import "./nav-card-grid";
 import "./period-selector";
 import "./placeholder";
 import "./resource-form-schema";
+import "./section";
 import "./stack";
+import "./stat-group";
 import "./tab";
 import "./table-view/schema";
 import "./top-list-card";
-import "./tree";
 export * from "./data-sources";
 export * from "./block-registry/helpers";
 export * from "./block-registry/registry";

package/dist/base/block-types.js

@@ -14,19 +14,41 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-require("./chart-schemas");
+/**
+ * Side-effect barrel registering every built-in block type.
+ *
+ * Importing it populates the block registry without pulling in the parts of
+ * `dms-base` that need a running DMS (database models, export jobs), so builder
+ * tooling can read the catalog on its own.
+ *
+ * Both surfaces are re-exported: reading a block type and declaring one. A
+ * module registering its own block reaches `RegisterBlockType` through here, so
+ * the helpers its schema needs — `ui`, `narrowString`, `opaqueOption` — have to
+ * be reachable from the same place.
+ */
+require("./activity-feed");
+require("./banner");
+require("./card");
+require("./internal/chart-schemas");
 require("./chart-card");
+require("./empty-state");
 require("./form-block-schema");
 require("./grid");
+require("./key-value-list");
 require("./kpi-card");
+require("./meter");
+require("./nav-card-grid");
 require("./period-selector");
 require("./placeholder");
 require("./resource-form-schema");
+require("./section");
 require("./stack");
+require("./stat-group");
 require("./tab");
 require("./table-view/schema");
 require("./top-list-card");
-require("./tree");
+// Declared data sources travel with the block types: a builder reading the
+// catalog needs both to know what a block may be pointed at.
 __exportStar(require("./data-sources"), exports);
 __exportStar(require("./block-registry/helpers"), exports);
 __exportStar(require("./block-registry/registry"), exports);

package/dist/base/block-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"block-types.js","sourceRoot":"","sources":["../../src/base/block-types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAYA,2BAAyB;AACzB,wBAAsB;AACtB,+BAA6B;AAC7B,kBAAgB;AAChB,sBAAoB;AACpB,6BAA2B;AAC3B,yBAAuB;AACvB,kCAAgC;AAChC,mBAAiB;AACjB,iBAAe;AACf,+BAA6B;AAC7B,2BAAyB;AACzB,kBAAgB;AAIhB,iDAA+B;AAC/B,2DAAyC;AACzC,4DAA0C;AAC1C,yDAAuC"}
+{"version":3,"file":"block-types.js","sourceRoot":"","sources":["../../src/base/block-types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;GAWG;AACH,2BAAyB;AACzB,oBAAkB;AAClB,kBAAgB;AAChB,oCAAkC;AAClC,wBAAsB;AACtB,yBAAuB;AACvB,+BAA6B;AAC7B,kBAAgB;AAChB,4BAA0B;AAC1B,sBAAoB;AACpB,mBAAiB;AACjB,2BAAyB;AACzB,6BAA2B;AAC3B,yBAAuB;AACvB,kCAAgC;AAChC,qBAAmB;AACnB,mBAAiB;AACjB,wBAAsB;AACtB,iBAAe;AACf,+BAA6B;AAC7B,2BAAyB;AAEzB,2EAA2E;AAC3E,6DAA6D;AAC7D,iDAA+B;AAC/B,2DAAyC;AACzC,4DAA0C;AAC1C,yDAAuC"}

package/dist/base/card.d.ts

@@ -0,0 +1,100 @@
+import { ComponentBuilder } from "../component";
+import { z } from "zod";
+import { type BlockLinkAction } from "./display";
+import type { BaseComponentProps } from "./types";
+/** The looks of a card. */
+export declare const CARD_VARIANTS: readonly ["default", "elevated"];
+export type CardVariant = (typeof CARD_VARIANTS)[number];
+/** The options `Card` takes. */
+export interface CardProps extends BaseComponentProps {
+    /** Eyebrow title of the head; `$`-prefixed for an i18n key. */
+    title?: string;
+    /** Mono count after the title. */
+    count?: number | string;
+    /** One dim line under the title. */
+    description?: string;
+    /** Link buttons on the right of the head. */
+    actions?: BlockLinkAction[];
+    /** Muted text in the foot band. */
+    footer?: string;
+    /** Body padding; turn it off for a list or a table running edge to edge. */
+    padded?: boolean;
+    /** `elevated`: stronger shadow, for a card on an empty backdrop. */
+    variant?: CardVariant;
+}
+/** Slot a child fills in the card head, next to the link actions. */
+export declare const CARD_ACTIONS_SLOT = "actions";
+/** Slot a child fills in the foot band. */
+export declare const CARD_FOOTER_SLOT = "footer";
+/**
+ * Card — a titled card holding other blocks.
+ *
+ * Children without a slot stack in the body. A child placed with
+ * `{ slot: "actions" }` joins the head's link actions, one placed with
+ * `{ slot: "footer" }` fills the foot band; each of those slots holds one
+ * child, so several go in an `HStack`.
+ *
+ * @example
+ * ```typescript
+ * Card({ title: "Connectors", count: 4, actions: [{ label: "View all", to: "/integrations" }] })
+ *   .child("list", KeyValueList({ card: false, items: [...] }))
+ *   .child("foot", HStack().child("sync", ...), { slot: "footer" })
+ * ```
+ */
+export declare function Card(options?: CardProps): ComponentBuilder<CardProps>;
+/** The options `Card` accepts. */
+export declare const CardSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    count: z.ZodOptional<z.ZodUnion<[z.ZodNumber, 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">>;
+    footer: z.ZodOptional<z.ZodString>;
+    padded: z.ZodDefault<z.ZodBoolean>;
+    variant: z.ZodDefault<z.ZodEnum<["default", "elevated"]>>;
+}, "strip", z.ZodTypeAny, {
+    variant: "default" | "elevated";
+    padded: boolean;
+    description?: string | undefined;
+    title?: string | undefined;
+    footer?: string | undefined;
+    count?: string | number | 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;
+}, {
+    description?: string | undefined;
+    title?: string | undefined;
+    variant?: "default" | "elevated" | undefined;
+    footer?: string | undefined;
+    count?: string | number | 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;
+    padded?: boolean | undefined;
+}>;

package/dist/base/card.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CardSchema = exports.CARD_FOOTER_SLOT = exports.CARD_ACTIONS_SLOT = exports.CARD_VARIANTS = void 0;
+exports.Card = Card;
+const component_1 = require("../component");
+const zod_1 = require("zod");
+const block_registry_1 = require("./block-registry");
+const display_1 = require("./display");
+/** The looks of a card. */
+exports.CARD_VARIANTS = ["default", "elevated"];
+const CARD_COMPONENT_NAME = "dms-card-block";
+const CARD_ICON = "i-ph-square";
+const CARD_DEFAULTS = { padded: true, variant: "default" };
+/** Slot a child fills in the card head, next to the link actions. */
+exports.CARD_ACTIONS_SLOT = "actions";
+/** Slot a child fills in the foot band. */
+exports.CARD_FOOTER_SLOT = "footer";
+/**
+ * Card — a titled card holding other blocks.
+ *
+ * Children without a slot stack in the body. A child placed with
+ * `{ slot: "actions" }` joins the head's link actions, one placed with
+ * `{ slot: "footer" }` fills the foot band; each of those slots holds one
+ * child, so several go in an `HStack`.
+ *
+ * @example
+ * ```typescript
+ * Card({ title: "Connectors", count: 4, actions: [{ label: "View all", to: "/integrations" }] })
+ *   .child("list", KeyValueList({ card: false, items: [...] }))
+ *   .child("foot", HStack().child("sync", ...), { slot: "footer" })
+ * ```
+ */
+function Card(options) {
+    return new component_1.ComponentBuilder(CARD_COMPONENT_NAME)
+        .options({ ...CARD_DEFAULTS, ...options })
+        .meta({ name: options?.title || "Card", icon: CARD_ICON });
+}
+/** The options `Card` accepts. */
+exports.CardSchema = zod_1.z.object({
+    title: (0, block_registry_1.ui)(zod_1.z.string().optional().describe("Eyebrow title of the head."), {
+        label: "Title",
+        group: "content",
+    }),
+    count: (0, block_registry_1.ui)(zod_1.z
+        .union([zod_1.z.number(), zod_1.z.string()])
+        .optional()
+        .describe("Mono count after the title."), { label: "Count", group: "content" }),
+    description: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Description",
+        group: "content",
+    }),
+    actions: (0, display_1.blockActionsOption)("Link buttons on the right of the head."),
+    footer: (0, block_registry_1.ui)(zod_1.z.string().optional().describe("Muted text in the foot band."), {
+        label: "Footer",
+        group: "content",
+    }),
+    padded: (0, block_registry_1.ui)(zod_1.z
+        .boolean()
+        .default(CARD_DEFAULTS.padded)
+        .describe("Pads the body; off for a list or table edge to edge."), { label: "Padded body", group: "layout", widget: "switch" }),
+    variant: (0, block_registry_1.ui)(zod_1.z.enum(exports.CARD_VARIANTS).default(CARD_DEFAULTS.variant), {
+        label: "Variant",
+        group: "appearance",
+        widget: "segmented",
+    }),
+});
+(0, block_registry_1.RegisterBlockType)({
+    type: "Card",
+    componentName: CARD_COMPONENT_NAME,
+    schema: exports.CardSchema,
+    container: true,
+    slots: [
+        {
+            id: exports.CARD_ACTIONS_SLOT,
+            label: "Head actions",
+            description: "One block next to the head's link actions.",
+        },
+        {
+            id: exports.CARD_FOOTER_SLOT,
+            label: "Footer",
+            description: "One block in the foot band.",
+        },
+    ],
+    meta: {
+        name: "Card",
+        icon: CARD_ICON,
+        description: "Titled card; its children stack in the body.",
+        group: "layout",
+    },
+});
+//# sourceMappingURL=card.js.map

package/dist/base/card.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"card.js","sourceRoot":"","sources":["../../src/base/card.ts"],"names":[],"mappings":";;;AAqDA,oBAIC;AAzDD,4CAAgD;AAChD,6BAAwB;AACxB,qDAA+E;AAC/E,uCAAqE;AAGrE,2BAA2B;AACd,QAAA,aAAa,GAAG,CAAC,SAAS,EAAE,UAAU,CAAU,CAAC;AAsB9D,MAAM,mBAAmB,GAAG,gBAAgB,CAAC;AAC7C,MAAM,SAAS,GAAG,aAAa,CAAC;AAChC,MAAM,aAAa,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAW,CAAC;AAEpE,qEAAqE;AACxD,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAC3C,2CAA2C;AAC9B,QAAA,gBAAgB,GAAG,QAAQ,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,SAAgB,IAAI,CAAC,OAAmB;IACtC,OAAO,IAAI,4BAAgB,CAAY,mBAAmB,CAAC;SACxD,OAAO,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,CAAC;SACzC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,kCAAkC;AACrB,QAAA,UAAU,GAAG,OAAC,CAAC,MAAM,CAAC;IACjC,KAAK,EAAE,IAAA,mBAAE,EAAC,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC,EAAE;QACtE,KAAK,EAAE,OAAO;QACd,KAAK,EAAE,SAAS;KACjB,CAAC;IACF,KAAK,EAAE,IAAA,mBAAE,EACP,OAAC;SACE,KAAK,CAAC,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC;SAC/B,QAAQ,EAAE;SACV,QAAQ,CAAC,6BAA6B,CAAC,EAC1C,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CACrC;IACD,WAAW,EAAE,IAAA,mBAAE,EAAC,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;QACrC,KAAK,EAAE,aAAa;QACpB,KAAK,EAAE,SAAS;KACjB,CAAC;IACF,OAAO,EAAE,IAAA,4BAAkB,EAAC,wCAAwC,CAAC;IACrE,MAAM,EAAE,IAAA,mBAAE,EAAC,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC,EAAE;QACzE,KAAK,EAAE,QAAQ;QACf,KAAK,EAAE,SAAS;KACjB,CAAC;IACF,MAAM,EAAE,IAAA,mBAAE,EACR,OAAC;SACE,OAAO,EAAE;SACT,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC;SAC7B,QAAQ,CAAC,sDAAsD,CAAC,EACnE,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,CAC5D;IACD,OAAO,EAAE,IAAA,mBAAE,EAAC,OAAC,CAAC,IAAI,CAAC,qBAAa,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE;QAChE,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,YAAY;QACnB,MAAM,EAAE,WAAW;KACpB,CAAC;CACH,CAAsC,CAAC;AAExC,IAAA,kCAAiB,EAAC;IAChB,IAAI,EAAE,MAAM;IACZ,aAAa,EAAE,mBAAmB;IAClC,MAAM,EAAE,kBAAU;IAClB,SAAS,EAAE,IAAI;IACf,KAAK,EAAE;QACL;YACE,EAAE,EAAE,yBAAiB;YACrB,KAAK,EAAE,cAAc;YACrB,WAAW,EAAE,4CAA4C;SAC1D;QACD;YACE,EAAE,EAAE,wBAAgB;YACpB,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,6BAA6B;SAC3C;KACF;IACD,IAAI,EAAE;QACJ,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,SAAS;QACf,WAAW,EAAE,8CAA8C;QAC3D,KAAK,EAAE,QAAQ;KAChB;CACF,CAAC,CAAC"}

package/dist/base/chart-card.d.ts

@@ -21,7 +21,14 @@ export interface ChartCardProps extends BaseComponentProps {
 export interface ChartCardBuilderOptions extends ChartCardProps {
     chart: Component;
 }
+/**
+ * `options` is optional because a page is written as it is built: the editor
+ * places a block before anything is configured, and writes that as the bare
+ * call `ChartCard()`. A page under construction has to compile — it is typechecked
+ * on every edit — so a block with nothing set yet has to be a legal call.
+ */
 export declare function ChartCard(options?: ChartCardBuilderOptions): ComponentBuilder<ChartCardProps>;
+/** The options `ChartCard` accepts, including the chart it wraps. */
 export declare const ChartCardSchema: z.ZodObject<{
     title: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -46,7 +53,7 @@ export declare const ChartCardSchema: z.ZodObject<{
     fetchUrl?: string | undefined;
     fetchUrlMethod?: HttpMethod | undefined;
     periodScope?: string | undefined;
-    valueFormat?: "number" | "currency" | "percent" | "compact" | undefined;
+    valueFormat?: "number" | "compact" | "percent" | "currency" | undefined;
     currencyCode?: string | undefined;
     primaryLabel?: string | undefined;
     comparisonLabel?: string | undefined;
@@ -59,7 +66,7 @@ export declare const ChartCardSchema: z.ZodObject<{
     fetchUrlMethod?: HttpMethod | undefined;
     showLegend?: boolean | undefined;
     periodScope?: string | undefined;
-    valueFormat?: "number" | "currency" | "percent" | "compact" | undefined;
+    valueFormat?: "number" | "compact" | "percent" | "currency" | undefined;
     currencyCode?: string | undefined;
     showDelta?: boolean | undefined;
     primaryLabel?: string | undefined;