@fieldia/core 0.1.0

package/src/lib/format/layout.d.mts

@@ -0,0 +1,521 @@
+import * as z from 'zod';
+import { type JsonValue } from './json.mjs';
+/**
+ * The layout: where each field goes and what surrounds it.
+ *
+ * Every element carries a stable `id`, unique within the page, so a designer
+ * can select it, undo can name it, and an app can override it. Anything that
+ * shows or hides by state takes a modifier: `true`, `false`, or an expression
+ * such as `state == 'draft' and amount > 100`.
+ */
+/** `true`, `false`, or an expression evaluated against the record's values. */
+export type Modifier = boolean | string;
+export type Tone = 'info' | 'success' | 'warning' | 'danger' | 'muted';
+export interface FieldNode {
+    type: 'field';
+    id: string;
+    field: string;
+    label?: string;
+    /** How the value is shown, when not the type's default: radio, tags, email… */
+    widget?: string;
+    placeholder?: string;
+    help?: string;
+    /** Grid columns this field spans inside a section. */
+    colspan?: number;
+    /** For one2many and many2many: which line fields show as columns. */
+    columns?: string[];
+    invisible?: Modifier;
+    readonly?: Modifier;
+    required?: Modifier;
+}
+export interface ButtonNode {
+    type: 'button';
+    id: string;
+    label: string;
+    /** The action's name. The app decides what it does. */
+    action: string;
+    params?: {
+        [key: string]: JsonValue;
+    };
+    style?: 'primary' | 'secondary' | 'danger' | 'link';
+    /** Ask before running the action. */
+    confirm?: string;
+    icon?: string;
+    invisible?: Modifier;
+}
+export interface TextNode {
+    type: 'text';
+    id: string;
+    text: string;
+    style?: 'heading' | 'paragraph' | 'note';
+    invisible?: Modifier;
+}
+/** A named place the app fills with its own content, such as an activity feed. */
+export interface SlotNode {
+    type: 'slot';
+    id: string;
+    name: string;
+    invisible?: Modifier;
+}
+export interface SectionNode {
+    type: 'section';
+    id: string;
+    title?: string;
+    description?: string;
+    columns?: 1 | 2 | 3 | 4;
+    collapsible?: boolean;
+    invisible?: Modifier;
+    children: LayoutNode[];
+}
+export interface TabNode {
+    type: 'tab';
+    id: string;
+    label: string;
+    icon?: string;
+    invisible?: Modifier;
+    children: LayoutNode[];
+}
+export interface TabsNode {
+    type: 'tabs';
+    id: string;
+    invisible?: Modifier;
+    children: TabNode[];
+}
+/** A step of a wizard. An invisible step is skipped, which is how surveys branch. */
+export interface StepNode {
+    type: 'step';
+    id: string;
+    label: string;
+    description?: string;
+    invisible?: Modifier;
+    children: LayoutNode[];
+}
+export interface WizardNode {
+    type: 'wizard';
+    id: string;
+    children: StepNode[];
+}
+export interface SectionsNode {
+    type: 'sections';
+    id: string;
+    children: LayoutNode[];
+}
+export interface StatButton {
+    id: string;
+    label: string;
+    action: string;
+    /** A numeric field shown on the button, such as a count of invoices. */
+    field?: string;
+    icon?: string;
+    invisible?: Modifier;
+}
+export interface Ribbon {
+    id: string;
+    label: string;
+    tone?: Tone;
+    invisible?: Modifier;
+}
+export interface Alert {
+    id: string;
+    message: string;
+    tone?: Tone;
+    invisible?: Modifier;
+}
+export interface SheetTitle {
+    field: string;
+    subtitleField?: string;
+    avatarField?: string;
+    placeholder?: string;
+}
+export interface Statusbar {
+    field: string;
+    /** Show only these states, as Flectra-style status bars often do. */
+    visibleStates?: (string | number)[];
+    /** Clicking a state moves the record to it. */
+    clickable?: boolean;
+}
+/** The record layout: a header with a statusbar and buttons, then the sheet itself. */
+export interface SheetNode {
+    type: 'sheet';
+    id: string;
+    title?: SheetTitle;
+    statusbar?: Statusbar;
+    buttons?: ButtonNode[];
+    statButtons?: StatButton[];
+    ribbon?: Ribbon;
+    alerts?: Alert[];
+    children: LayoutNode[];
+    sidePanel?: SlotNode;
+}
+/** Anything that can sit inside a section, tab, step or sheet. */
+export type LayoutNode = FieldNode | ButtonNode | TextNode | SlotNode | SectionNode | TabsNode;
+/** What a page's `layout` can be: the four page layouts. */
+export type RootLayout = SheetNode | SectionsNode | TabsNode | WizardNode;
+export declare const ModifierSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>;
+export declare const FieldNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"field">;
+    id: z.ZodString;
+    field: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    widget: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    help: z.ZodOptional<z.ZodString>;
+    colspan: z.ZodOptional<z.ZodInt>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    readonly: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    required: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const ButtonNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"button">;
+    id: z.ZodString;
+    label: z.ZodString;
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    style: z.ZodOptional<z.ZodEnum<{
+        danger: "danger";
+        primary: "primary";
+        secondary: "secondary";
+        link: "link";
+    }>>;
+    confirm: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const TextNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    id: z.ZodString;
+    text: z.ZodString;
+    style: z.ZodOptional<z.ZodEnum<{
+        heading: "heading";
+        paragraph: "paragraph";
+        note: "note";
+    }>>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const SlotNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"slot">;
+    id: z.ZodString;
+    name: z.ZodString;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const SectionNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"section">;
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+    collapsible: z.ZodOptional<z.ZodBoolean>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+}, z.core.$strict>;
+export declare const TabNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tab">;
+    id: z.ZodString;
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+}, z.core.$strict>;
+export declare const TabsNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"tabs">;
+    id: z.ZodString;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"tab">;
+        id: z.ZodString;
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        children: z.ZodArray<typeof LayoutNodeSchema>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const LayoutNodeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"field">;
+    id: z.ZodString;
+    field: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    widget: z.ZodOptional<z.ZodString>;
+    placeholder: z.ZodOptional<z.ZodString>;
+    help: z.ZodOptional<z.ZodString>;
+    colspan: z.ZodOptional<z.ZodInt>;
+    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    readonly: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    required: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"button">;
+    id: z.ZodString;
+    label: z.ZodString;
+    action: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    style: z.ZodOptional<z.ZodEnum<{
+        danger: "danger";
+        primary: "primary";
+        secondary: "secondary";
+        link: "link";
+    }>>;
+    confirm: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    id: z.ZodString;
+    text: z.ZodString;
+    style: z.ZodOptional<z.ZodEnum<{
+        heading: "heading";
+        paragraph: "paragraph";
+        note: "note";
+    }>>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"slot">;
+    id: z.ZodString;
+    name: z.ZodString;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"section">;
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    columns: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<1>, z.ZodLiteral<2>, z.ZodLiteral<3>, z.ZodLiteral<4>]>>;
+    collapsible: z.ZodOptional<z.ZodBoolean>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"tabs">;
+    id: z.ZodString;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"tab">;
+        id: z.ZodString;
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        children: z.ZodArray<typeof LayoutNodeSchema>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "type">;
+export declare const StepNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"step">;
+    id: z.ZodString;
+    label: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+}, z.core.$strict>;
+export declare const WizardNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"wizard">;
+    id: z.ZodString;
+    children: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"step">;
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        children: z.ZodArray<typeof LayoutNodeSchema>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const SectionsNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"sections">;
+    id: z.ZodString;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+}, z.core.$strict>;
+export declare const StatButtonSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    action: z.ZodString;
+    field: z.ZodOptional<z.ZodString>;
+    icon: z.ZodOptional<z.ZodString>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const RibbonSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        success: "success";
+        info: "info";
+        warning: "warning";
+        danger: "danger";
+        muted: "muted";
+    }>>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const AlertSchema: z.ZodObject<{
+    id: z.ZodString;
+    message: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        success: "success";
+        info: "info";
+        warning: "warning";
+        danger: "danger";
+        muted: "muted";
+    }>>;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+}, z.core.$strict>;
+export declare const SheetNodeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"sheet">;
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        subtitleField: z.ZodOptional<z.ZodString>;
+        avatarField: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    statusbar: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        visibleStates: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        clickable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"button">;
+        id: z.ZodString;
+        label: z.ZodString;
+        action: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        style: z.ZodOptional<z.ZodEnum<{
+            danger: "danger";
+            primary: "primary";
+            secondary: "secondary";
+            link: "link";
+        }>>;
+        confirm: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>>;
+    statButtons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        action: z.ZodString;
+        field: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>>;
+    ribbon: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            success: "success";
+            info: "info";
+            warning: "warning";
+            danger: "danger";
+            muted: "muted";
+        }>>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>;
+    alerts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        message: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            success: "success";
+            info: "info";
+            warning: "warning";
+            danger: "danger";
+            muted: "muted";
+        }>>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>>;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+    sidePanel: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"slot">;
+        id: z.ZodString;
+        name: z.ZodString;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const RootLayoutSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"sheet">;
+    id: z.ZodString;
+    title: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        subtitleField: z.ZodOptional<z.ZodString>;
+        avatarField: z.ZodOptional<z.ZodString>;
+        placeholder: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    statusbar: z.ZodOptional<z.ZodObject<{
+        field: z.ZodString;
+        visibleStates: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        clickable: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"button">;
+        id: z.ZodString;
+        label: z.ZodString;
+        action: z.ZodString;
+        params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+        style: z.ZodOptional<z.ZodEnum<{
+            danger: "danger";
+            primary: "primary";
+            secondary: "secondary";
+            link: "link";
+        }>>;
+        confirm: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>>;
+    statButtons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        action: z.ZodString;
+        field: z.ZodOptional<z.ZodString>;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>>;
+    ribbon: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            success: "success";
+            info: "info";
+            warning: "warning";
+            danger: "danger";
+            muted: "muted";
+        }>>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>;
+    alerts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        message: z.ZodString;
+        tone: z.ZodOptional<z.ZodEnum<{
+            success: "success";
+            info: "info";
+            warning: "warning";
+            danger: "danger";
+            muted: "muted";
+        }>>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>>;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+    sidePanel: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"slot">;
+        id: z.ZodString;
+        name: z.ZodString;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"sections">;
+    id: z.ZodString;
+    children: z.ZodArray<typeof LayoutNodeSchema>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"tabs">;
+    id: z.ZodString;
+    invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+    children: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"tab">;
+        id: z.ZodString;
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        children: z.ZodArray<typeof LayoutNodeSchema>;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"wizard">;
+    id: z.ZodString;
+    children: z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"step">;
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        invisible: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>;
+        children: z.ZodArray<typeof LayoutNodeSchema>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "type">;