uidl-runtime 0.1.0

package/dist/compiler/types.d.ts

@@ -0,0 +1,315 @@
+import { UIDLDocument } from '../types';
+import { Language } from '../utils/i18n';
+import { CellFormat } from '../utils/listCell';
+/** Seven recipes the public compiler must support */
+export type PageRecipe = "list" | "form" | "report" | "dashboard" | "settings" | "tree" | "wizard";
+export declare const PAGE_RECIPES: readonly PageRecipe[];
+export declare function isPageRecipe(value: unknown): value is PageRecipe;
+export type LocalizedText = {
+    id: string;
+    en: string;
+};
+export type FieldWidget = "TextField" | "Textarea" | "Select" | "RadioGroup" | "Checkbox" | "Switch" | "Slider" | "Link" | "Currency" | "Date" | "Table";
+export interface FieldOption {
+    value: string;
+    label: string;
+}
+/**
+ * A Link field's lookup target. `valueKey`/`labelKey` say how a row of that doctype becomes an
+ * option — the rows come from the host's query and carry the target's own keys, not
+ * `value`/`label`, so without them a Link rendered as an empty select.
+ */
+export interface LinkTarget {
+    doctype: string;
+    valueKey?: string;
+    labelKey?: string;
+}
+export interface FieldMeta {
+    key: string;
+    label: LocalizedText;
+    widget: FieldWidget;
+    /**
+     * How the value is *printed*, when that differs from what the widget implies. Meridian keeps
+     * the two apart: a Float and a Currency both edit as a number box, but only Currency prints
+     * with a symbol — so a "Rate %" mapped to the Currency widget rendered as `IDR 2`.
+     * Unset, the list recipe infers the format from `widget`.
+     */
+    format?: CellFormat;
+    required?: boolean;
+    readOnly?: boolean;
+    options?: FieldOption[] | LinkTarget;
+    placeholder?: string | LocalizedText;
+    default?: unknown;
+    section?: string;
+}
+export interface ListColumn {
+    field: string;
+    width?: string;
+    align?: "left" | "right" | "center";
+}
+export interface ListFilter {
+    field: string;
+    widget: "Select" | "TextField" | "DateRange";
+    label?: LocalizedText;
+    options?: FieldOption[];
+}
+export interface ListSummary {
+    label: LocalizedText;
+    agg: "sum" | "count" | "avg";
+    field: string;
+}
+export interface ListPageMeta {
+    name: string;
+    label: LocalizedText;
+    titleField: string;
+    fields: FieldMeta[];
+    columns: ListColumn[];
+    filters?: ListFilter[];
+    defaultSort: {
+        field: string;
+        dir: "asc" | "desc";
+    };
+    pageSize?: number;
+    statusField?: string;
+    summaries?: ListSummary[];
+}
+export interface StateTransition {
+    name: string;
+    label: LocalizedText;
+    from: string[];
+    to: string;
+    confirm?: LocalizedText;
+}
+export interface DocumentStates {
+    field: string;
+    values: string[];
+    initial: string;
+    transitions: StateTransition[];
+}
+export interface ChildTableRef {
+    field: string;
+    doctype: string;
+}
+export interface FormPageMeta {
+    name: string;
+    label: LocalizedText;
+    titleField: string;
+    fields: FieldMeta[];
+    states?: DocumentStates;
+    childTables?: ChildTableRef[];
+}
+export interface ReportColumn {
+    key: string;
+    label: LocalizedText | string;
+    align?: "left" | "right" | "center";
+    width?: string;
+    /**
+     * How the value is printed — the same ListCell rule a list column follows. A report's
+     * money column is money: without this a General Ledger printed `1500000` beside a reference
+     * that shows `Rp 1.500.000`.
+     */
+    format?: CellFormat;
+}
+export interface ReportFilter {
+    field: string;
+    label: LocalizedText;
+    widget: "Select" | "TextField" | "DateRange";
+    options?: FieldOption[];
+    default?: unknown;
+}
+export interface ReportPageMeta {
+    name: string;
+    label: LocalizedText;
+    columns: ReportColumn[];
+    dataSource: string | Array<Record<string, unknown>> | {
+        $query: unknown;
+    };
+    filters?: ReportFilter[];
+    /**
+     * A headline figure. Give it `agg`/`field` to compute it from the rows the report loaded —
+     * a literal `value` is only for a figure the host already knows, and a report that declared
+     * `value: 0` printed a hard zero next to rows that plainly summed to more.
+     */
+    summaries?: Array<{
+        label: LocalizedText;
+        value?: string | number;
+        agg?: "sum" | "count" | "avg";
+        field?: string;
+        format?: CellFormat;
+    }>;
+}
+export interface DashboardKpi {
+    label: LocalizedText;
+    value: string | number;
+}
+export interface DashboardChart {
+    id: string;
+    title: LocalizedText;
+    type: "bar" | "line" | "donut";
+    xKey: string;
+    yKey: string;
+    dataSource: string | Array<Record<string, unknown>>;
+    style?: Record<string, unknown>;
+}
+export interface DashboardShortcut {
+    doctype: string;
+    label: LocalizedText;
+    description?: LocalizedText;
+    route?: string;
+}
+export interface DashboardPageMeta {
+    name: string;
+    label: LocalizedText;
+    kpis?: DashboardKpi[];
+    charts?: DashboardChart[];
+    shortcuts?: DashboardShortcut[];
+    dataSources?: Record<string, unknown>;
+}
+export interface SettingsField extends FieldMeta {
+    group?: string;
+}
+export interface SettingsSection {
+    id: string;
+    label: LocalizedText;
+    fields: SettingsField[];
+}
+export interface SettingsPageMeta {
+    name: string;
+    label: LocalizedText;
+    sections: SettingsSection[];
+}
+export interface TreeNode {
+    key: string;
+    label: LocalizedText;
+    children?: TreeNode[];
+}
+export interface TreePageMeta {
+    name: string;
+    label: LocalizedText;
+    titleField: string;
+    fields: FieldMeta[];
+    nodes: TreeNode[];
+    parentField?: string;
+}
+export interface WizardStep {
+    id: string;
+    label: LocalizedText;
+    fields: FieldMeta[];
+}
+export interface WizardPageMeta {
+    name: string;
+    label: LocalizedText;
+    steps: WizardStep[];
+}
+export type RecipeMetaMap = {
+    list: ListPageMeta;
+    form: FormPageMeta;
+    report: ReportPageMeta;
+    dashboard: DashboardPageMeta;
+    settings: SettingsPageMeta;
+    tree: TreePageMeta;
+    wizard: WizardPageMeta;
+};
+export interface QueryCapability {
+    collection: string;
+    filterFields?: string[];
+    sortableFields?: string[];
+}
+export interface MutationCapability {
+    collection: string;
+    operations: Array<"create" | "update" | "delete" | "transition">;
+    transitions?: string[];
+}
+/**
+ * Host-owned allowlist. The compiler MUST NOT emit a `$query` collection,
+ * `mutate` collection, or `command` name that is not in this manifest.
+ * Unknown values fail closed (validation error, not silent render).
+ */
+export interface HostCapabilities {
+    /** Allowed `$query.collection` values (e.g. "invoices", "customers"). */
+    collections: string[];
+    /** Allowed `command` names (e.g. "workspace.rag.search"). */
+    commands: string[];
+    /** Allowed `mutate.collection` values — if omitted, same as `collections`. */
+    mutationCollections?: string[];
+    /** Allowed state transition names across all doctypes (optional strict gate). */
+    transitions?: string[];
+    /** Per-collection query allowlist — if provided, compiler validates filter/sort fields. */
+    queries?: QueryCapability[];
+    /** Per-collection mutation allowlist — if provided, compiler validates operations. */
+    mutations?: MutationCapability[];
+    /** Optional hard caps the compiler must respect. */
+    limits?: {
+        maxPageSize?: number;
+        maxFilters?: number;
+    };
+}
+export interface UiPolicy {
+    lang?: Language;
+    density?: "compact" | "comfortable";
+    theme?: string;
+    /**
+     * ISO 4217 code for money columns/fields. Meridian formats currency with the company's own
+     * currency; a host that has one declares it here. Left unset, money prints as a grouped
+     * number with no symbol rather than guessing one.
+     */
+    currency?: string;
+}
+export interface RoutePolicy {
+    /** Base for list pages, e.g. "/app/acme/list". */
+    listBase?: string;
+    /** Base for form/edit pages, e.g. "/app/acme/edit". */
+    formBase?: string;
+    /** Base for report pages, e.g. "/app/acme/report". */
+    reportBase?: string;
+    /** Optional custom resolver — if provided, compiler must call it instead of default join. */
+    resolveListRoute?: (meta: {
+        name: string;
+    }) => string;
+    resolveFormRoute?: (meta: {
+        name: string;
+    }, id: string) => string;
+    resolveReportRoute?: (meta: {
+        name: string;
+    }) => string;
+}
+export interface ResponsivePolicy {
+    breakpoints?: {
+        sm?: number;
+        md?: number;
+        lg?: number;
+        xl?: number;
+    };
+}
+export type CompilePageInputFor<R extends PageRecipe> = {
+    recipe: R;
+    meta: RecipeMetaMap[R];
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    responsivePolicy?: ResponsivePolicy;
+};
+export type CompilePageInput = CompilePageInputFor<"list"> | CompilePageInputFor<"form"> | CompilePageInputFor<"report"> | CompilePageInputFor<"dashboard"> | CompilePageInputFor<"settings"> | CompilePageInputFor<"tree"> | CompilePageInputFor<"wizard">;
+export type CompilePageResult = UIDLDocument;
+export interface PageCompiler {
+    /** Deterministic, pure: same input → byte-identical UIDLDocument. */
+    compilePage(input: CompilePageInput): CompilePageResult;
+}
+export type CapabilityIssue = {
+    code: "unknown_collection" | "unknown_command" | "unknown_transition" | "limit_exceeded";
+    message: string;
+    path: string;
+};
+export declare function validateHostCapabilities(input: CompilePageInput): CapabilityIssue[];
+/**
+ * Deterministic node id for a field/control derived only from recipe + meta
+ * identity, not from file paths or array order. Unchanged fields keep the
+ * same id after a patch, so incremental UIDL patching can preserve
+ * state and focus.
+ */
+export declare function semanticNodeId(recipe: PageRecipe, metaName: string, fieldKey: string): string;
+export declare function semanticListNodeIds(metaName: string): {
+    readonly search: `list-${string}-search`;
+    readonly table: `list-${string}-table`;
+    readonly page: `list-${string}-page`;
+};

package/dist/compiler/wizard.d.ts

@@ -0,0 +1,10 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { HostCapabilities, RoutePolicy, UiPolicy, WizardPageMeta } from './types.js';
+export interface CompileWizardOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    extraHeaderActions?: UIDLNode[];
+}
+export declare function compileWizardPage(meta: WizardPageMeta, options: CompileWizardOptions): UIDLDocument;

package/dist/components/BarcodeAndQRCode.d.ts

@@ -0,0 +1,29 @@
+import { SVGProps } from 'react';
+export interface QRCodeSVGProps extends SVGProps<SVGSVGElement> {
+    value?: string;
+    size?: number;
+    fgColor?: string;
+    bgColor?: string;
+}
+/**
+ * Deterministic vector QR code SVG generator for verification URLs, DJP e-Faktur, and BMT certificates.
+ */
+export declare function QRCodeSVG({ value, size, fgColor, bgColor, className, ...props }: QRCodeSVGProps): import("react").JSX.Element;
+export interface BarcodeSVGProps extends SVGProps<SVGSVGElement> {
+    value?: string;
+    width?: number;
+    height?: number;
+    showText?: boolean;
+}
+/**
+ * 1D Barcode SVG generator (Code 128 style) for shipping tracking numbers, Medical Records (RM), and SKU tags.
+ */
+export declare function BarcodeSVG({ value, width, height, showText, className, ...props }: BarcodeSVGProps): import("react").JSX.Element;
+export interface DataMatrixSVGProps extends SVGProps<SVGSVGElement> {
+    value?: string;
+    size?: number;
+}
+/**
+ * 2D DataMatrix SVG generator for ISO 13485 Medical Device UDI (Unique Device Identification).
+ */
+export declare function DataMatrixSVG({ value, size, className, ...props }: DataMatrixSVGProps): import("react").JSX.Element;

package/dist/components/charts.d.ts

@@ -0,0 +1,66 @@
+export interface ChartGeometryProps {
+    /** One array per series; each inner array is that series' y values. */
+    points: number[][];
+    xLabels?: string[];
+    colors?: string[];
+    viewBoxHeight?: number;
+    aspectRatio?: number;
+    axisPadding?: number;
+    pointsPadding?: number;
+    xLabelOffset?: number;
+    yLabelOffset?: number;
+    yLabelDivisions?: number;
+    gridColor?: string;
+    fontColor?: string;
+    fontSize?: number;
+    gridThickness?: number;
+    left?: number;
+    bottom?: number;
+    extendGridX?: number;
+    yMin?: number | null;
+    yMax?: number | null;
+    formatY?: (value: number) => string;
+    formatX?: (value: string) => string;
+    drawXGrid?: boolean;
+    drawLabels?: boolean;
+}
+export interface BarChartProps extends ChartGeometryProps {
+    className?: string;
+    /** Bar width in viewBox units (Meridian: 28). */
+    barWidth?: number;
+    /** Corner radius in viewBox units (Meridian: 17 — bars are visibly pill-capped). */
+    radius?: number;
+    skipXLabel?: number;
+    drawZeroLine?: boolean;
+    zeroLineColor?: string;
+    ariaLabel?: string;
+}
+export declare function MeridianBarChart({ points, xLabels, colors, className, viewBoxHeight, aspectRatio, axisPadding, pointsPadding, xLabelOffset, yLabelOffset, yLabelDivisions, gridColor, zeroLineColor, fontColor, fontSize, gridThickness, left, bottom, extendGridX, barWidth, radius, skipXLabel, yMin, yMax, formatY, formatX, drawXGrid, drawLabels, drawZeroLine, ariaLabel, }: BarChartProps): import("react").JSX.Element;
+export interface LineChartProps extends ChartGeometryProps {
+    className?: string;
+    /** Stroke width in viewBox units (Meridian: 5). */
+    thickness?: number;
+    ariaLabel?: string;
+}
+export declare function MeridianLineChart({ points, xLabels, colors, className, viewBoxHeight, aspectRatio, axisPadding, pointsPadding, xLabelOffset, yLabelOffset, yLabelDivisions, gridColor, fontColor, fontSize, gridThickness, thickness, left, bottom, extendGridX, yMin, yMax, formatY, formatX, drawXGrid, drawLabels, ariaLabel, }: LineChartProps): import("react").JSX.Element;
+export interface DonutSector {
+    color: string;
+    value: number;
+    label?: string;
+}
+export interface DonutChartProps {
+    sectors: DonutSector[];
+    className?: string;
+    totalLabel?: string;
+    radius?: number;
+    startAngle?: number;
+    thickness?: number;
+    offsetX?: number;
+    offsetY?: number;
+    textOffsetX?: number;
+    textOffsetY?: number;
+    valueFormatter?: (value: number) => string;
+    ariaLabel?: string;
+}
+/** Meridian's DonutChart: a 100×100 viewBox, arcs stroked onto a clipped hole. */
+export declare function MeridianDonutChart({ sectors, className, totalLabel, radius, startAngle, thickness, offsetX, offsetY, textOffsetX, textOffsetY, valueFormatter, ariaLabel, }: DonutChartProps): import("react").JSX.Element;

package/dist/components/iconPaths.d.ts

@@ -0,0 +1,5 @@
+/** Every icon name a document or the demo chrome may reference. */
+export declare const ICON_PATHS: Record<string, string[]>;
+export type IconName = keyof typeof ICON_PATHS;
+export declare const ICON_NAMES: IconName[];
+export declare function hasIcon(name: string): boolean;

package/dist/components/icons.d.ts

@@ -0,0 +1,31 @@
+import { CSSProperties } from 'react';
+import { ICON_PATHS, ICON_NAMES, hasIcon, IconName } from './iconPaths';
+export { ICON_PATHS, ICON_NAMES, hasIcon };
+export type { IconName };
+export interface IconProps {
+    /** A name from `ICON_NAMES`. An unknown name renders nothing rather than a broken glyph. */
+    name: string;
+    /** Tailwind sizing/colour classes. Defaults to Meridian's sidebar icon size. */
+    className?: string;
+    style?: CSSProperties;
+    /** Give the icon an accessible name; without one it stays `aria-hidden`. */
+    title?: string;
+    /** Meridian strokes its chrome icons at 1.5; 2 reads better below 16px. */
+    strokeWidth?: number;
+}
+/**
+ * One outline glyph. `currentColor` on the stroke means an icon inherits the text colour of the
+ * row it sits in, which is what keeps the sidebar's active/inactive states in one place.
+ */
+export declare function Icon({ name, className, style, title, strokeWidth }: IconProps): import("react").JSX.Element | null;
+/**
+ * The registry widget. Sized in `em` so an icon dropped next to text in a document tracks that
+ * text's size instead of needing a class of its own.
+ */
+export declare function IconWidget({ name, size, title, className, strokeWidth, }: {
+    name?: string;
+    size?: number | string;
+    title?: string;
+    className?: string;
+    strokeWidth?: number;
+}): import("react").JSX.Element | null;