@broadpaper/blocks 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,312 @@
+import * as _broadpaper_core from '@broadpaper/core';
+import { VNode, RichTextDoc, ConditionGroup, Theme, BlockDefinition, RegistryOptions, BlockRegistry } from '@broadpaper/core';
+
+/**
+ * Structural nodes. They are hidden from the palette; the editor creates them
+ * through layout tools (add section, add row with a column layout).
+ */
+declare const sectionBlock: _broadpaper_core.BlockDefinition<{
+    padding: number;
+    background?: string;
+    label?: string;
+}>;
+declare const rowBlock: _broadpaper_core.BlockDefinition<{
+    layout: number[];
+    allowSplit: boolean;
+    verticalAlign: "top" | "middle" | "bottom" | "stretch";
+}>;
+declare const columnBlock: _broadpaper_core.BlockDefinition<{
+    span: number;
+}>;
+declare const repeaterItemBlock: _broadpaper_core.BlockDefinition<{
+    index: number;
+    count: number;
+}>;
+declare function stack(h: typeof _broadpaper_core.h, children: VNode[], gap: number, extra?: Record<string, unknown>): VNode;
+
+declare const headingBlock: _broadpaper_core.BlockDefinition<{
+    text: string;
+    level: "h1" | "h2" | "h3" | "h4";
+}>;
+declare const textBlock: _broadpaper_core.BlockDefinition<{
+    content: RichTextDoc;
+}>;
+declare const imageBlock: _broadpaper_core.BlockDefinition<{
+    src: string;
+    alt: string;
+    fit: "contain" | "cover";
+    width: number | null;
+    height: number | null;
+    align: "left" | "center" | "right";
+    radius: number;
+    link: string;
+}>;
+declare const logoBlock: _broadpaper_core.BlockDefinition<{
+    variant: "auto" | "light" | "dark";
+    height: number;
+    align: "left" | "center" | "right";
+}>;
+declare const dividerBlock: _broadpaper_core.BlockDefinition<{
+    thickness: number;
+    color: string;
+    lineStyle: "solid" | "dashed" | "dotted";
+    width: number;
+}>;
+declare const spacerBlock: _broadpaper_core.BlockDefinition<{
+    height: number;
+}>;
+declare const buttonBlock: _broadpaper_core.BlockDefinition<{
+    label: string;
+    url: string;
+    variant: "filled" | "outline" | "link";
+    color: string;
+    align: "left" | "center" | "right";
+    size: "sm" | "md" | "lg";
+}>;
+declare const calloutBlock: _broadpaper_core.BlockDefinition<{
+    title: string;
+    content: RichTextDoc;
+    tone: "info" | "success" | "warning" | "danger" | "neutral";
+    icon: boolean;
+}>;
+declare function mixWithWhite(hex: string, amount?: number): string;
+declare const quoteBlock: _broadpaper_core.BlockDefinition<{
+    content: RichTextDoc;
+    attribution: string;
+}>;
+declare const fieldBlock: _broadpaper_core.BlockDefinition<{
+    label: string;
+    value: string;
+    layout: "stacked" | "inline";
+    fallback: string;
+    labelWidth: number;
+}>;
+declare const kpiBlock: _broadpaper_core.BlockDefinition<{
+    label: string;
+    value: string;
+    caption: string;
+    trend: string;
+    trendFormat: "percent" | "number" | "text";
+    accent: string;
+    align: "left" | "center" | "right";
+    size: "sm" | "md" | "lg";
+}>;
+declare const signatureBlock: _broadpaper_core.BlockDefinition<{
+    label: string;
+    name: string;
+    role: string;
+    showDate: boolean;
+    lineWidth: number;
+}>;
+declare const dateBlock: _broadpaper_core.BlockDefinition<{
+    source: "now" | "binding";
+    value: string;
+    pattern: string;
+    prefix: string;
+}>;
+declare const pageNumberBlock: _broadpaper_core.BlockDefinition<{
+    format: string;
+    align: "left" | "center" | "right";
+}>;
+declare const timestampBlock: _broadpaper_core.BlockDefinition<{
+    prefix: string;
+    pattern: string;
+    align: "left" | "center" | "right";
+}>;
+
+declare const containerBlock: _broadpaper_core.BlockDefinition<{
+    padding: number;
+    gap: number | null;
+}>;
+declare const cardBlock: _broadpaper_core.BlockDefinition<{
+    title: string;
+    padding: number | null;
+    accent: boolean;
+    accentColor: string;
+}>;
+declare const pageBreakBlock: _broadpaper_core.BlockDefinition<Record<string, never>>;
+declare const keepTogetherBlock: _broadpaper_core.BlockDefinition<{
+    label: string;
+}>;
+declare const conditionalBlock: _broadpaper_core.BlockDefinition<{
+    condition: string | ConditionGroup;
+    label: string;
+}>;
+declare const repeaterBlock: _broadpaper_core.BlockDefinition<{
+    source: string;
+    alias: string;
+    keepItemTogether: boolean;
+    gap: number | null;
+    limit: number | null;
+    emptyMessage: string;
+    separator: boolean;
+}>;
+
+interface TableColumn {
+    id: string;
+    header: string;
+    /** Expression evaluated per row, e.g. `holding.value | currency`. */
+    value: string;
+    align?: "left" | "center" | "right";
+    /** Width as a percentage of the table width; null = auto (equal share of the rest). */
+    width?: number | null;
+    bold?: boolean;
+    /** Summary function for the totals row. */
+    total?: "none" | "sum" | "avg" | "count" | "min" | "max";
+    /** Expression for the totals cell (overrides `total`), evaluated in the table scope with `rows` available. */
+    totalExpr?: string;
+    /** Formatting pipe applied to the total, e.g. `currency:"GBP"`. */
+    totalFormat?: string;
+    wrap?: boolean;
+}
+interface ConditionalFormat {
+    id: string;
+    /** Column id, or "*" for the whole row. */
+    columnId: string;
+    /** Expression evaluated per row. */
+    condition: string;
+    color?: string;
+    background?: string;
+    bold?: boolean;
+}
+interface TableProps extends Record<string, unknown> {
+    source: string;
+    alias: string;
+    columns: TableColumn[];
+    showHeader: boolean;
+    repeatHeader: boolean;
+    zebra: boolean;
+    borders: "inherit" | "all" | "horizontal" | "outer" | "none";
+    compact: boolean;
+    fontSize: number | null;
+    headerBackground: string;
+    headerColor: string;
+    sortBy: string;
+    sortDir: "asc" | "desc";
+    emptyMessage: string;
+    totalsLabel: string;
+    conditionalFormats: ConditionalFormat[];
+    designRows: number;
+    rowLimit: number | null;
+}
+declare const tableBlock: _broadpaper_core.BlockDefinition<TableProps>;
+declare const keyValueListBlock: _broadpaper_core.BlockDefinition<{
+    items: Array<{
+        id: string;
+        label: string;
+        value: string;
+    }>;
+    layout: "inline" | "stacked" | "grid";
+    labelWidth: number;
+    dividers: boolean;
+    columns: number;
+}>;
+
+type ChartType = "bar" | "horizontalBar" | "line" | "area" | "pie" | "donut";
+interface ChartSeriesData {
+    label: string;
+    values: Array<number | null>;
+    color: string;
+}
+interface ChartData {
+    categories: string[];
+    series: ChartSeriesData[];
+}
+/**
+ * One thing a reader can point at: a bar, a slice, a marker on a line.
+ *
+ * The chart records these as it draws, because it is the only code that knows
+ * which mark is which datum. Nothing is drawn for them and no geometry is
+ * duplicated — the mark itself carries `data-bp-hit="<index>"`, so a screen
+ * renderer can find the element and use its real shape, and a PDF renderer can
+ * drop the attribute and produce exactly the vectors it produced before.
+ */
+interface ChartHit {
+    /** Index into the chart's category list. */
+    categoryIndex: number;
+    category: string;
+    seriesIndex: number;
+    series: string;
+    value: number | null;
+    /** The value as the report itself formats it. */
+    formatted: string;
+    color: string;
+    /** For pie and donut: this slice's share of the whole. */
+    share?: number;
+}
+interface ChartRenderOptions {
+    type: ChartType;
+    width: number;
+    height: number;
+    theme: Theme;
+    fontFamily: string;
+    showLegend: boolean;
+    showValues: boolean;
+    showGrid: boolean;
+    stacked: boolean;
+    smooth: boolean;
+    /** Formats axis ticks and value labels. */
+    formatValue: (n: number) => string;
+    /** Formats pie/donut percentages. */
+    formatPercent: (fraction: number) => string;
+    innerLabel?: string;
+    /**
+     * Filled in as the chart draws, in the same order as the `data-bp-hit`
+     * indices on the marks. Left out entirely when nobody is going to read it.
+     */
+    hits?: ChartHit[];
+}
+declare function colorAt(data: ChartData, i: number): string;
+/** Renders a chart to an SVG VNode. Pure and deterministic. */
+declare function renderChart(data: ChartData, opts: ChartRenderOptions): VNode;
+
+interface ChartSeries {
+    id: string;
+    label: string;
+    /** Expression evaluated per item. */
+    value: string;
+    color?: string;
+}
+interface ChartProps extends Record<string, unknown> {
+    chartType: ChartType;
+    source: string;
+    alias: string;
+    label: string;
+    series: ChartSeries[];
+    height: number;
+    title: string;
+    showLegend: boolean;
+    showValues: boolean;
+    showGrid: boolean;
+    stacked: boolean;
+    smooth: boolean;
+    valueFormat: string;
+    percentDecimals: number;
+    innerLabel: string;
+    limit: number | null;
+}
+declare const chartBlock: _broadpaper_core.BlockDefinition<ChartProps>;
+declare const progressBlock: _broadpaper_core.BlockDefinition<{
+    value: string;
+    max: number;
+    label: string;
+    caption: string;
+    variant: "bar" | "gauge";
+    color: string;
+    trackColor: string;
+    showValue: boolean;
+    format: "percent" | "value" | "fraction";
+    thresholds: Array<{
+        id: string;
+        upTo: number;
+        color: string;
+    }>;
+    height: number;
+}>;
+
+/** Every built-in block, in palette order. */
+declare const builtInBlocks: Array<BlockDefinition<any>>;
+/** Creates a registry with every built-in block plus any custom blocks. */
+declare function createRegistry(custom?: Array<BlockDefinition<any>>, opts?: RegistryOptions): BlockRegistry;
+
+export { type ChartData, type ChartHit, type ChartProps, type ChartRenderOptions, type ChartSeries, type ChartSeriesData, type ChartType, type ConditionalFormat, type TableColumn, type TableProps, builtInBlocks, buttonBlock, calloutBlock, cardBlock, chartBlock, colorAt, columnBlock, conditionalBlock, containerBlock, createRegistry, dateBlock, dividerBlock, fieldBlock, headingBlock, imageBlock, keepTogetherBlock, keyValueListBlock, kpiBlock, logoBlock, mixWithWhite, pageBreakBlock, pageNumberBlock, progressBlock, quoteBlock, renderChart, repeaterBlock, repeaterItemBlock, rowBlock, sectionBlock, signatureBlock, spacerBlock, stack, tableBlock, textBlock, timestampBlock };