@antelopejs/interface-dms 0.3.5 → 0.4.0

package/dist/base/meter.d.ts

@@ -0,0 +1,186 @@
+import { ComponentBuilder } from "../component";
+import { z } from "zod";
+import { type BlockLinkAction } from "./display";
+import type { BaseComponentProps, EnumOption } from "./types";
+import type { HttpMethod } from "./types/http";
+/**
+ * Fill tones of a meter: the semantic tones plus `soft`, the pale primary of
+ * what is pending or reserved.
+ */
+export declare const METER_TONES: readonly ["neutral", "primary", "secondary", "success", "warning", "error", "info", "soft"];
+export type MeterTone = (typeof METER_TONES)[number];
+/** Value text right of the label: `8 / 10`, `80%`, `8` or none. */
+export declare const METER_FORMATS: readonly ["fraction", "percent", "value", "none"];
+export type MeterFormat = (typeof METER_FORMATS)[number];
+/** Bar height: `xs` 4px, `sm` 6px, `md` 8px. */
+export declare const METER_SIZES: readonly ["xs", "sm", "md"];
+export type MeterSize = (typeof METER_SIZES)[number];
+/** One stacked fill of a meter. */
+export interface MeterSegment {
+    value: number;
+    tone?: MeterTone;
+    /** Legend text ("6 members"). */
+    label?: string;
+}
+/** The options `Meter` takes. */
+export interface MeterProps extends BaseComponentProps {
+    /** Name of the measure ("Seats"). */
+    label?: string;
+    /** Dimmed note after the label ("8 in use · 2 free"). */
+    hint?: string;
+    /** Filled amount; ignored when `segments` is set. */
+    value?: number;
+    /** Total the bar stands for. Defaults to 100. */
+    max?: number;
+    /** Stacked fills, drawn in order. */
+    segments?: MeterSegment[];
+    /** Shows the segment labels under the bar. */
+    legend?: boolean;
+    /** Value text right of the label. Defaults to `fraction`. */
+    format?: MeterFormat;
+    /** Replaces the formatted value text. */
+    valueLabel?: string;
+    /** Fill tone of a single value. Defaults to `primary`. */
+    tone?: MeterTone;
+    /** Percent of `max` from which the fill turns warning. */
+    warnAt?: number;
+    /** Percent of `max` from which the fill turns error. */
+    errorAt?: number;
+    size?: MeterSize;
+    /**
+     * Endpoint answering an object with any of `{ value, max, segments, hint,
+     * valueLabel }`, for figures that change per request (seats used, quota
+     * left). A meter is one measure, so unlike the list blocks it reads an
+     * object rather than `{ items }`.
+     */
+    fetchUrl?: string;
+    fetchUrlMethod?: EnumOption<HttpMethod>;
+    /** Wraps the meter in a padded card. Defaults to `false`. */
+    card?: boolean;
+    /** Link buttons under the bar, on the right ("Manage members"). */
+    actions?: BlockLinkAction[];
+}
+/**
+ * Meter - an "x of y" bar: seats, quotas, storage, coverage.
+ *
+ * One value or stacked segments with a legend, the value as a fraction or a
+ * percentage, and thresholds turning the bar warning or error.
+ *
+ * @example
+ * ```typescript
+ * Meter({
+ *   label: "Seats",
+ *   max: 10,
+ *   segments: [
+ *     { value: 6, label: "6 members" },
+ *     { value: 2, tone: "soft", label: "2 pending invites" },
+ *   ],
+ *   legend: true,
+ *   warnAt: 80,
+ * })
+ * ```
+ */
+export declare function Meter(options?: MeterProps): ComponentBuilder<MeterProps>;
+/** The options `Meter` accepts. */
+export declare const MeterSchema: z.ZodObject<{
+    label: z.ZodOptional<z.ZodString>;
+    hint: z.ZodOptional<z.ZodString>;
+    value: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodNumber;
+        tone: z.ZodOptional<z.ZodEnum<["soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+        label: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        value: number;
+        label?: string | undefined;
+        tone?: "soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }, {
+        value: number;
+        label?: string | undefined;
+        tone?: "soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }>, "many">>;
+    legend: z.ZodOptional<z.ZodBoolean>;
+    format: z.ZodOptional<z.ZodEnum<["fraction", "percent", "value", "none"]>>;
+    valueLabel: z.ZodOptional<z.ZodString>;
+    tone: z.ZodOptional<z.ZodEnum<["soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+    warnAt: z.ZodOptional<z.ZodNumber>;
+    errorAt: z.ZodOptional<z.ZodNumber>;
+    size: z.ZodOptional<z.ZodEnum<["xs", "sm", "md"]>>;
+    fetchUrl: z.ZodOptional<z.ZodString>;
+    fetchUrlMethod: z.ZodOptional<z.ZodNativeEnum<typeof HttpMethod>>;
+    card: z.ZodDefault<z.ZodBoolean>;
+    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">>;
+}, "strip", z.ZodTypeAny, {
+    card: boolean;
+    value?: number | undefined;
+    max?: number | undefined;
+    size?: "xs" | "sm" | "md" | undefined;
+    format?: "value" | "none" | "percent" | "fraction" | undefined;
+    label?: string | undefined;
+    hint?: string | undefined;
+    fetchUrl?: string | undefined;
+    fetchUrlMethod?: HttpMethod | undefined;
+    valueLabel?: string | undefined;
+    legend?: boolean | 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?: "soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    segments?: {
+        value: number;
+        label?: string | undefined;
+        tone?: "soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }[] | undefined;
+    warnAt?: number | undefined;
+    errorAt?: number | undefined;
+}, {
+    value?: number | undefined;
+    max?: number | undefined;
+    size?: "xs" | "sm" | "md" | undefined;
+    format?: "value" | "none" | "percent" | "fraction" | undefined;
+    label?: string | undefined;
+    hint?: string | undefined;
+    fetchUrl?: string | undefined;
+    fetchUrlMethod?: HttpMethod | undefined;
+    card?: boolean | undefined;
+    valueLabel?: string | undefined;
+    legend?: boolean | 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?: "soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    segments?: {
+        value: number;
+        label?: string | undefined;
+        tone?: "soft" | "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+    }[] | undefined;
+    warnAt?: number | undefined;
+    errorAt?: number | undefined;
+}>;

package/dist/base/meter.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MeterSchema = exports.METER_SIZES = exports.METER_FORMATS = exports.METER_TONES = void 0;
+exports.Meter = Meter;
+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");
+const tone_1 = require("./types/tone");
+/**
+ * Fill tones of a meter: the semantic tones plus `soft`, the pale primary of
+ * what is pending or reserved.
+ */
+exports.METER_TONES = [...tone_1.TONES, "soft"];
+/** Value text right of the label: `8 / 10`, `80%`, `8` or none. */
+exports.METER_FORMATS = ["fraction", "percent", "value", "none"];
+/** Bar height: `xs` 4px, `sm` 6px, `md` 8px. */
+exports.METER_SIZES = ["xs", "sm", "md"];
+const METER_COMPONENT_NAME = "dms-meter-block";
+const DEFAULT_ICON = "i-ph-gauge";
+/**
+ * Meter - an "x of y" bar: seats, quotas, storage, coverage.
+ *
+ * One value or stacked segments with a legend, the value as a fraction or a
+ * percentage, and thresholds turning the bar warning or error.
+ *
+ * @example
+ * ```typescript
+ * Meter({
+ *   label: "Seats",
+ *   max: 10,
+ *   segments: [
+ *     { value: 6, label: "6 members" },
+ *     { value: 2, tone: "soft", label: "2 pending invites" },
+ *   ],
+ *   legend: true,
+ *   warnAt: 80,
+ * })
+ * ```
+ */
+function Meter(options) {
+    return new component_1.ComponentBuilder(METER_COMPONENT_NAME)
+        .options({ ...options })
+        .meta({
+        name: options?.label || "Meter",
+        icon: DEFAULT_ICON,
+    });
+}
+const MeterSegmentSchema = zod_1.z.object({
+    value: (0, block_registry_1.ui)(zod_1.z.number(), { label: "Value", widget: "number" }),
+    tone: (0, block_registry_1.ui)((0, display_2.toneEnum)(exports.METER_TONES).optional(), {
+        label: "Tone",
+        widget: "select",
+    }),
+    label: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "Legend" }),
+});
+/** The options `Meter` accepts. */
+exports.MeterSchema = zod_1.z.object({
+    label: (0, block_registry_1.ui)(zod_1.z.string().optional().describe("Name of the measure."), {
+        label: "Label",
+        group: "content",
+    }),
+    hint: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "Hint", group: "content" }),
+    value: (0, block_registry_1.ui)(zod_1.z.number().optional().describe("Filled amount."), {
+        label: "Value",
+        group: "data",
+        widget: "number",
+    }),
+    max: (0, block_registry_1.ui)(zod_1.z.number().optional().describe("Total the bar stands for."), {
+        label: "Maximum",
+        group: "data",
+        widget: "number",
+        min: 0,
+    }),
+    segments: (0, block_registry_1.ui)(zod_1.z.array(MeterSegmentSchema).optional(), {
+        label: "Segments",
+        group: "data",
+    }),
+    legend: (0, block_registry_1.ui)(zod_1.z.boolean().optional(), {
+        label: "Show legend",
+        group: "appearance",
+        widget: "switch",
+    }),
+    format: (0, block_registry_1.ui)(zod_1.z.enum(exports.METER_FORMATS).optional(), {
+        label: "Value text",
+        group: "appearance",
+        widget: "segmented",
+    }),
+    valueLabel: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Custom value text",
+        group: "content",
+    }),
+    tone: (0, block_registry_1.ui)((0, display_2.toneEnum)(exports.METER_TONES).optional(), {
+        label: "Tone",
+        group: "appearance",
+        widget: "select",
+    }),
+    warnAt: (0, block_registry_1.ui)(zod_1.z.number().optional().describe("Percent of the maximum."), {
+        label: "Warning from",
+        group: "behavior",
+        widget: "number",
+        min: 0,
+        max: 100,
+    }),
+    errorAt: (0, block_registry_1.ui)(zod_1.z.number().optional().describe("Percent of the maximum."), {
+        label: "Error from",
+        group: "behavior",
+        widget: "number",
+        min: 0,
+        max: 100,
+    }),
+    size: (0, block_registry_1.ui)(zod_1.z.enum(exports.METER_SIZES).optional(), {
+        label: "Size",
+        group: "appearance",
+        widget: "segmented",
+    }),
+    fetchUrl: (0, display_1.blockFetchUrlOption)("Where the figures come from."),
+    fetchUrlMethod: (0, display_1.blockFetchUrlMethodOption)(),
+    card: (0, display_1.blockCardOption)(false),
+    actions: (0, display_1.blockActionsOption)("Link buttons under the bar."),
+});
+(0, block_registry_1.RegisterBlockType)({
+    type: "Meter",
+    componentName: METER_COMPONENT_NAME,
+    schema: exports.MeterSchema,
+    meta: {
+        name: "Meter",
+        icon: DEFAULT_ICON,
+        description: "An x-of-y bar for seats, quotas and coverage.",
+        group: "visualization",
+    },
+});
+//# sourceMappingURL=meter.js.map

package/dist/base/meter.js.map

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

package/dist/base/nav-card-grid.d.ts

@@ -0,0 +1,173 @@
+import { ComponentBuilder } from "../component";
+import { z } from "zod";
+import { type BlockItemsSource } from "./display";
+import { type Tone, type IconTone } from "./types/tone";
+import type { BaseComponentProps } from "./types";
+import type { CategoryInfo } from "../page/types";
+/** One navigation card. */
+export interface NavCardItem {
+    /** Stable key; the target is used without one. */
+    id?: string;
+    /** `$`-prefixed for an i18n key, like every text of the card. */
+    title: string;
+    description?: string;
+    icon: string;
+    iconTone?: IconTone;
+    /** Route, `#anchor` or URL. */
+    to: string;
+    /** Live state of the target, in mono at the bottom ("3 unread"). */
+    state?: string;
+    /** Tone of the state line (`neutral` = dimmed). */
+    stateTone?: Tone;
+    /** Small uppercase tag after the title (the module a page comes from). */
+    tag?: string;
+    /** Mono readout lines under the description. */
+    readout?: string[];
+}
+/** The options `NavCardGrid` takes. */
+export interface NavCardGridProps extends BaseComponentProps, BlockItemsSource {
+    items?: NavCardItem[];
+    /**
+     * Full id of a category: a card per page of it the viewer can open, in
+     * menu order, each with its navigation badge — in place of `items` and
+     * `fetchUrl`. Set through the `category` option.
+     */
+    categoryId?: string;
+    /** Columns on wide screens (1–4); fewer on narrow ones. */
+    columns?: number;
+    /** Section title above the grid. */
+    title?: string;
+    description?: string;
+}
+/**
+ * NavCardGrid — a grid of navigation cards: icon, title, description, and
+ * optionally the target's live state, a tag or a mono readout.
+ *
+ * The cards are items of one block rather than blocks of their own: a grid of
+ * nav cards is one list (a settings overview, a module home), configured in
+ * one place, reflowed as one grid, and — with `fetchUrl` — fed by one route
+ * that computes every card's state. A single card is a one-item grid.
+ *
+ * @example
+ * ```typescript
+ * NavCardGrid({
+ *   title: "Workspace",
+ *   items: [
+ *     { icon: "i-ph-users", title: "Members", to: "/settings/workspace/members",
+ *       state: "8 of 10 seats" },
+ *   ],
+ * })
+ * ```
+ */
+/** What `NavCardGrid` takes: its options, the category being given whole. */
+export interface NavCardGridOptions extends Omit<NavCardGridProps, "categoryId"> {
+    /**
+     * The category whose pages the cards stand for: a card per page the viewer
+     * can open, with the badge its navigation entry shows. A settings overview
+     * lists its sections this way, a module's home its pages.
+     */
+    category?: CategoryInfo;
+}
+export declare function NavCardGrid(options?: NavCardGridOptions): ComponentBuilder<NavCardGridProps>;
+/** The options `NavCardGrid` accepts. */
+export declare const NavCardGridSchema: z.ZodObject<{
+    fetchUrl: z.ZodOptional<z.ZodString>;
+    fetchUrlMethod: z.ZodOptional<z.ZodNativeEnum<typeof import("./types").HttpMethod>>;
+    empty: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        description?: string | undefined;
+    }, {
+        title: string;
+        description?: string | undefined;
+    }>>;
+    skeletonCount: z.ZodOptional<z.ZodNumber>;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    items: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        icon: z.ZodString;
+        iconTone: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | "muted", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | "muted")[]]>>;
+        to: z.ZodString;
+        state: z.ZodOptional<z.ZodString>;
+        stateTone: z.ZodOptional<z.ZodEnum<["primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral", ...("primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral")[]]>>;
+        tag: z.ZodOptional<z.ZodString>;
+        readout: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        icon: string;
+        to: string;
+        description?: string | undefined;
+        id?: string | undefined;
+        state?: string | undefined;
+        iconTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | "muted" | undefined;
+        stateTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+        tag?: string | undefined;
+        readout?: string[] | undefined;
+    }, {
+        title: string;
+        icon: string;
+        to: string;
+        description?: string | undefined;
+        id?: string | undefined;
+        state?: string | undefined;
+        iconTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | "muted" | undefined;
+        stateTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+        tag?: string | undefined;
+        readout?: string[] | undefined;
+    }>, "many">>;
+    columns: z.ZodDefault<z.ZodNumber>;
+    categoryId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    columns: number;
+    description?: string | undefined;
+    items?: {
+        title: string;
+        icon: string;
+        to: string;
+        description?: string | undefined;
+        id?: string | undefined;
+        state?: string | undefined;
+        iconTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | "muted" | undefined;
+        stateTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+        tag?: string | undefined;
+        readout?: string[] | undefined;
+    }[] | undefined;
+    title?: string | undefined;
+    fetchUrl?: string | undefined;
+    fetchUrlMethod?: import("./types").HttpMethod | undefined;
+    empty?: {
+        title: string;
+        description?: string | undefined;
+    } | undefined;
+    skeletonCount?: number | undefined;
+    categoryId?: string | undefined;
+}, {
+    description?: string | undefined;
+    items?: {
+        title: string;
+        icon: string;
+        to: string;
+        description?: string | undefined;
+        id?: string | undefined;
+        state?: string | undefined;
+        iconTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | "muted" | undefined;
+        stateTone?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral" | undefined;
+        tag?: string | undefined;
+        readout?: string[] | undefined;
+    }[] | undefined;
+    title?: string | undefined;
+    fetchUrl?: string | undefined;
+    fetchUrlMethod?: import("./types").HttpMethod | undefined;
+    columns?: number | undefined;
+    empty?: {
+        title: string;
+        description?: string | undefined;
+    } | undefined;
+    skeletonCount?: number | undefined;
+    categoryId?: string | undefined;
+}>;

package/dist/base/nav-card-grid.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavCardGridSchema = void 0;
+exports.NavCardGrid = NavCardGrid;
+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");
+const tone_1 = require("./types/tone");
+const NAV_CARD_GRID_COMPONENT_NAME = "dms-nav-card-grid-block";
+const NAV_CARD_GRID_ICON = "i-ph-cards";
+const NAV_CARD_GRID_DEFAULT_COLUMNS = 3;
+function NavCardGrid(options) {
+    const { category, ...rest } = options ?? {};
+    const props = {
+        columns: NAV_CARD_GRID_DEFAULT_COLUMNS,
+        ...rest,
+    };
+    if (category)
+        props.categoryId = category.fullId;
+    return new component_1.ComponentBuilder(NAV_CARD_GRID_COMPONENT_NAME)
+        .options(props)
+        .meta({
+        name: options?.title || "Navigation cards",
+        icon: NAV_CARD_GRID_ICON,
+    });
+}
+const NavCardItemSchema = zod_1.z.object({
+    id: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "Key", advanced: true }),
+    title: (0, block_registry_1.ui)(zod_1.z.string(), { label: "Title" }),
+    description: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Description",
+        widget: "textarea",
+    }),
+    icon: (0, block_registry_1.ui)(zod_1.z.string(), { label: "Icon", widget: "icon" }),
+    iconTone: (0, block_registry_1.ui)((0, display_2.toneEnum)(tone_1.ICON_TONES).optional(), {
+        label: "Icon tone",
+        widget: "select",
+    }),
+    to: (0, block_registry_1.ui)(zod_1.z.string().describe("Route, `#anchor` or URL."), {
+        label: "Link",
+        widget: "url",
+    }),
+    state: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "State" }),
+    stateTone: (0, block_registry_1.ui)((0, display_2.toneEnum)(tone_1.TONES).optional(), {
+        label: "State tone",
+        widget: "select",
+    }),
+    tag: (0, block_registry_1.ui)(zod_1.z.string().optional(), { label: "Tag" }),
+    readout: (0, block_registry_1.ui)(zod_1.z.array(zod_1.z.string()).optional(), { label: "Readout lines" }),
+});
+/** The options `NavCardGrid` accepts. */
+exports.NavCardGridSchema = zod_1.z.object({
+    title: (0, block_registry_1.ui)(zod_1.z.string().optional().describe("Section title above the grid."), {
+        label: "Title",
+        group: "content",
+    }),
+    description: (0, block_registry_1.ui)(zod_1.z.string().optional(), {
+        label: "Description",
+        group: "content",
+        widget: "textarea",
+    }),
+    items: (0, block_registry_1.ui)(zod_1.z.array(NavCardItemSchema).optional().describe("The cards, in order."), { label: "Cards", group: "content" }),
+    columns: (0, block_registry_1.ui)(zod_1.z
+        .number()
+        .int()
+        .min(1)
+        .max(4)
+        .default(NAV_CARD_GRID_DEFAULT_COLUMNS)
+        .describe("Columns on wide screens."), { label: "Columns", group: "layout", widget: "number", min: 1, max: 4 }),
+    categoryId: (0, block_registry_1.ui)(zod_1.z
+        .string()
+        .optional()
+        .describe("Full id of a category: a card per page of it the viewer can open, instead of the cards above."), { label: "Pages of category", group: "content", advanced: true }),
+    ...(0, display_1.blockItemsSourceOptions)(),
+});
+(0, block_registry_1.RegisterBlockType)({
+    type: "NavCardGrid",
+    componentName: NAV_CARD_GRID_COMPONENT_NAME,
+    schema: exports.NavCardGridSchema,
+    meta: {
+        name: "Navigation cards",
+        icon: NAV_CARD_GRID_ICON,
+        description: "Grid of cards linking to other pages, with their state.",
+        group: "content",
+    },
+});
+//# sourceMappingURL=nav-card-grid.js.map

package/dist/base/nav-card-grid.js.map

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

package/dist/base/period-selector.d.ts

@@ -1,16 +1,25 @@
 import { ComponentBuilder } from "../component";
 import { z } from "zod";
 import type { BaseComponentProps } from "./types";
+/** Every date range the selector can offer. */
 export declare const PERIOD_PRESETS: readonly ["last-hour", "last-24h", "today", "yesterday", "last-7-days", "last-30-days", "last-90-days", "this-month", "last-month", "this-quarter", "last-quarter", "ytd", "last-year", "custom"];
 export type PeriodPreset = (typeof PERIOD_PRESETS)[number];
+/** Every comparison the selector can offer. */
 export declare const PERIOD_COMPARISONS: readonly ["none", "previous-period", "previous-year", "custom"];
 export type PeriodComparison = (typeof PERIOD_COMPARISONS)[number];
+/** Where the selector sits in its row. */
 export declare const PERIOD_ALIGNS: readonly ["left", "center", "right"];
 export type PeriodAlign = (typeof PERIOD_ALIGNS)[number];
+/** How the selector renders its presets. */
 export declare const PERIOD_SELECTOR_VARIANTS: readonly ["default", "segmented"];
 export type PeriodSelectorVariant = (typeof PERIOD_SELECTOR_VARIANTS)[number];
+/**
+ * The scope a selector drives when nothing else is named: the one a builder
+ * binds a card's period to. One selector per page needs no other.
+ */
 export declare const DEFAULT_PERIOD_SCOPE = "page";
 export interface PeriodSelectorProps extends BaseComponentProps {
+    /** Scope id the cards on the page refer to. Defaults to {@link DEFAULT_PERIOD_SCOPE}. */
     id?: string;
     defaultPreset?: PeriodPreset;
     defaultComparison?: PeriodComparison;
@@ -21,9 +30,20 @@ export interface PeriodSelectorProps extends BaseComponentProps {
     align?: PeriodAlign;
     size?: "xs" | "sm" | "md" | "lg" | "xl";
     showRangeLabel?: boolean;
+    /**
+     * `segmented` renders the presets as inline pills for one-click range
+     * switching; the custom range stays in its popover calendar.
+     */
     variant?: PeriodSelectorVariant;
 }
+/**
+ * `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 `PeriodSelector()`. 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 PeriodSelector(options?: PeriodSelectorProps): ComponentBuilder<PeriodSelectorProps>;
+/** The options `PeriodSelector` accepts. */
 export declare const PeriodSelectorSchema: z.ZodObject<{
     id: z.ZodDefault<z.ZodString>;
     defaultPreset: z.ZodOptional<z.ZodEnum<["last-hour", "last-24h", "today", "yesterday", "last-7-days", "last-30-days", "last-90-days", "this-month", "last-month", "this-quarter", "last-quarter", "ytd", "last-year", "custom"]>>;