@wallarm-org/gen-ui 0.0.0-stage → 0.1.0

package/dist/fixtures/stream.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Writes a recorded answer once and streams it in every format. A scenario is the agent's layout,
+ * in the chunks it would send them, with every figure bound to a path, plus the app's data for
+ * those paths and when it arrives. `toStreams` turns it into A2UI messages and json-render patches,
+ * each line marked with who sent it.
+ */
+import type { SpecStreamLine } from '@json-render/core';
+import { type A2uiMessage } from '../a2ui/catalog.js';
+import type { GenUiAction } from '../core/define.js';
+import { type OpenUiLine } from './openui.js';
+/** A value the app fills: becomes `{ "@path" }` in A2UI and `{ "$state" }` in json-render. */
+export declare const bind: (path: string) => {
+    bind: string;
+};
+/** One component in the agent's layout. */
+export interface LayoutNode {
+    id: string;
+    type: string;
+    props?: Record<string, unknown>;
+    children?: string[];
+    /** For a Button: the action and its context, which may hold bindings too. */
+    press?: {
+        action: string;
+        params: Record<string, unknown>;
+    };
+}
+export declare const node: (id: string, type: string, props?: LayoutNode['props'], children?: string[]) => LayoutNode;
+export interface Scenario {
+    /** Stable id, e.g. for a URL. */
+    id: string;
+    /** What the user asked. */
+    prompt: string;
+    /** One line under the prompt in a picker: what the answer shows. */
+    summary: string;
+    surfaceId: string;
+    actions: readonly GenUiAction[];
+    /** The agent's components in arrival order, one array per chunk it sends. */
+    layout: LayoutNode[][];
+    /** The app's data: each batch arrives right after the layout chunk at `after` (its index). */
+    data: {
+        after: number;
+        values: DataValue[];
+    }[];
+    /** Data the app keeps sending once the answer is complete: no agent involved. */
+    live?: LiveData;
+}
+/** One write to the data model: a bound path and its new value. */
+export interface DataValue {
+    path: string;
+    value: unknown;
+}
+/**
+ * Live data: the app sends new values for paths the layout already binds, every `every` ms, and
+ * the page updates without asking the agent again. `update(tick)` gives the values of update
+ * number `tick` (1, 2, …); it must be pure, so a replay is the same every time.
+ */
+export interface LiveData {
+    every: number;
+    update: (tick: number) => DataValue[];
+}
+/** Who sent a line: the agent (layout) or the app (data). */
+export type StreamOrigin = 'agent' | 'app';
+export interface StreamLine<T> {
+    origin: StreamOrigin;
+    line: T;
+}
+export interface ScenarioStreams {
+    a2ui: StreamLine<A2uiMessage>[];
+    jsonRender: StreamLine<SpecStreamLine>[];
+    /** OpenUI Lang statements from the agent, data writes from the app (`toOpenUiLines`). */
+    openui: StreamLine<OpenUiLine>[];
+    /** The app's live updates, as lines of both formats, for update number `tick`. */
+    liveStreams?: {
+        every: number;
+        lines: (tick: number) => Omit<ScenarioStreams, 'liveStreams'>;
+    };
+}
+/** The scenario as both formats stream it. The first layout chunk's first node is the root. */
+export declare const toStreams: (s: Scenario) => ScenarioStreams;

package/dist/fixtures/stream.js

@@ -0,0 +1,147 @@
+import { WALLARM_A2UI_CATALOG_ID } from "../a2ui/catalog.js";
+import { toOpenUiLines } from "./openui.js";
+const bind = (path)=>({
+        bind: path
+    });
+const isBound = (v)=>'object' == typeof v && null !== v && 'bind' in v && 1 === Object.keys(v).length;
+const node = (id, type, props = {}, children)=>({
+        id,
+        type,
+        props,
+        children
+    });
+const mapBindings = (value, to)=>{
+    if (isBound(value)) return to(value.bind);
+    if (Array.isArray(value)) return value.map((v)=>mapBindings(v, to));
+    if ('object' == typeof value && null !== value) return Object.fromEntries(Object.entries(value).map(([k, v])=>[
+            k,
+            mapBindings(v, to)
+        ]));
+    return value;
+};
+const interleave = (start, chunks, dataAfter)=>[
+        ...start.map((line)=>({
+                origin: 'agent',
+                line
+            })),
+        ...chunks.flatMap((chunk, i)=>[
+                ...chunk.map((line)=>({
+                        origin: 'agent',
+                        line
+                    })),
+                ...dataAfter(i).map((line)=>({
+                        origin: 'app',
+                        line
+                    }))
+            ])
+    ];
+const toA2uiPath = (path)=>({
+        '@path': path
+    });
+const toJsonRenderPath = (path)=>({
+        $state: path
+    });
+const a2uiComponent = (n)=>({
+        id: n.id,
+        component: n.type,
+        ...mapBindings(n.props, toA2uiPath),
+        ...n.children ? {
+            children: n.children
+        } : {},
+        ...n.press ? {
+            press: {
+                event: {
+                    name: n.press.action,
+                    context: mapBindings(n.press.params, toA2uiPath)
+                }
+            }
+        } : {}
+    });
+const jsonRenderElement = (n)=>({
+        op: 'add',
+        path: `/elements/${n.id}`,
+        value: {
+            type: n.type,
+            props: mapBindings(n.props, toJsonRenderPath),
+            children: n.children ?? [],
+            ...n.press ? {
+                on: {
+                    press: {
+                        action: n.press.action,
+                        params: mapBindings(n.press.params, toJsonRenderPath)
+                    }
+                }
+            } : {}
+        }
+    });
+const a2uiData = (surfaceId, d)=>({
+        version: '1.0',
+        updateDataModel: {
+            surfaceId,
+            path: d.path,
+            value: d.value
+        }
+    });
+const jsonRenderData = (d)=>({
+        op: 'add',
+        path: `/state${d.path}`,
+        value: d.value
+    });
+const fromApp = (line)=>({
+        origin: 'app',
+        line
+    });
+const toStreams = (s)=>{
+    const dataAt = (i)=>s.data.filter((d)=>d.after === i).flatMap((d)=>d.values);
+    const rootId = s.layout[0]?.[0]?.id ?? 'root';
+    const a2ui = interleave([
+        {
+            version: '1.0',
+            createSurface: {
+                surfaceId: s.surfaceId,
+                catalogId: WALLARM_A2UI_CATALOG_ID
+            }
+        }
+    ], s.layout.map((chunk)=>[
+            {
+                version: '1.0',
+                updateComponents: {
+                    surfaceId: s.surfaceId,
+                    components: chunk.map(a2uiComponent)
+                }
+            }
+        ]), (i)=>dataAt(i).map((d)=>a2uiData(s.surfaceId, d)));
+    return {
+        a2ui,
+        openui: toOpenUiLines(a2ui),
+        jsonRender: [
+            {
+                origin: 'app',
+                line: {
+                    op: 'add',
+                    path: '/state',
+                    value: {}
+                }
+            },
+            ...interleave([
+                {
+                    op: 'add',
+                    path: '/root',
+                    value: rootId
+                }
+            ], s.layout.map((chunk)=>chunk.map(jsonRenderElement)), (i)=>dataAt(i).map(jsonRenderData))
+        ],
+        liveStreams: s.live && {
+            every: s.live.every,
+            lines: (tick)=>{
+                const values = s.live?.update(tick) ?? [];
+                return {
+                    a2ui: values.map((d)=>fromApp(a2uiData(s.surfaceId, d))),
+                    jsonRender: values.map((d)=>fromApp(jsonRenderData(d))),
+                    openui: values.map(fromApp)
+                };
+            }
+        }
+    };
+};
+export { bind, node, toStreams };

package/dist/fixtures/weeklyReport.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A weekly security report as an agent would write it: a summary, KPIs, the attack trend, a few
+ * breakdowns and recommendations. The agent writes the words, the app fills every figure.
+ */
+import type { GenUiAction } from '../core/define.js';
+import { type Scenario } from './stream.js';
+export declare const WEEKLY_REPORT_DATA: {
+    kpi: {
+        requests: number;
+        requestsDelta: {
+            value: number;
+            trend: string;
+            sentiment: string;
+        };
+        attacks: number;
+        attacksDelta: {
+            value: number;
+            trend: string;
+            sentiment: string;
+        };
+        blockedPercent: number;
+        blockedDelta: {
+            value: number;
+            trend: string;
+            sentiment: string;
+        };
+    };
+    daily: {
+        x: string;
+        attacks: number;
+        blocked: number;
+    }[];
+    responseCodes: {
+        name: string;
+        value: number;
+        color: string;
+    }[];
+    attackTypes: {
+        label: string;
+        value: number;
+        color: string;
+    }[];
+};
+export declare const WEEKLY_REPORT_ACTIONS: readonly GenUiAction[];
+/** Weekly security report: summary, KPIs, attack trend, breakdowns and recommendations. */
+export declare const WEEKLY_REPORT_SCENARIO: Scenario;

package/dist/fixtures/weeklyReport.js

@@ -0,0 +1,266 @@
+import { bind, node } from "./stream.js";
+const DAYS = Array.from({
+    length: 7
+}, (_, i)=>new Date(Date.UTC(2026, 10, 5 + i)).toISOString());
+const daily = DAYS.map((x, i)=>{
+    const attacks = 52000 + 4000 * i + (i % 2 ? 3000 : 0);
+    return {
+        x,
+        attacks,
+        blocked: Math.round(0.964 * attacks)
+    };
+});
+const WEEKLY_REPORT_DATA = {
+    kpi: {
+        requests: 92418306,
+        requestsDelta: {
+            value: 4,
+            trend: 'up',
+            sentiment: 'neutral'
+        },
+        attacks: daily.reduce((sum, d)=>sum + d.attacks, 0),
+        attacksDelta: {
+            value: 18,
+            trend: 'up',
+            sentiment: 'negative'
+        },
+        blockedPercent: 96.4,
+        blockedDelta: {
+            value: 1.2,
+            trend: 'up',
+            sentiment: 'positive'
+        }
+    },
+    daily: daily,
+    responseCodes: [
+        {
+            name: '2xx Success',
+            value: 88604020,
+            color: 'green'
+        },
+        {
+            name: '3xx Redirect',
+            value: 2114870,
+            color: 'blue'
+        },
+        {
+            name: '4xx Blocked',
+            value: 1486210,
+            color: 'amber'
+        },
+        {
+            name: '5xx Error',
+            value: 213206,
+            color: 'red'
+        }
+    ],
+    attackTypes: [
+        {
+            label: 'SQL injection',
+            value: 164520,
+            color: 'red'
+        },
+        {
+            label: "Cross-site scripting",
+            value: 121300,
+            color: 'amber'
+        },
+        {
+            label: 'BOLA',
+            value: 78440,
+            color: 'purple'
+        },
+        {
+            label: 'Brute force',
+            value: 52180,
+            color: 'blue'
+        },
+        {
+            label: 'Path traversal',
+            value: 40560,
+            color: 'slate'
+        }
+    ]
+};
+const WEEKLY_REPORT_ACTIONS = [
+    {
+        name: 'share_report',
+        description: 'Share the report with the given team (asks the user to pick recipients first).'
+    }
+];
+const LAYOUT = [
+    [
+        node('root', 'Section', {
+            title: 'Weekly security report',
+            subtitle: '5-11 Nov · all applications'
+        }, [
+            'summary',
+            'kpis',
+            'charts',
+            'response_codes',
+            'recommendations',
+            'actions'
+        ]),
+        node('summary', 'Text', {
+            text: 'Attacks rose again this week, led by SQL injection against the login endpoint. Nearly all of them were blocked, and error rates stayed flat.'
+        }),
+        node('kpis', 'Grid', {
+            columns: '3'
+        }, [
+            'm_requests',
+            'm_attacks',
+            'm_blocked'
+        ]),
+        node('charts', 'Grid', {
+            columns: '2'
+        }, [
+            'attack_trend',
+            'attack_types'
+        ])
+    ],
+    [
+        node('m_requests', 'Metric', {
+            title: 'Requests',
+            value: bind('/kpi/requests'),
+            format: 'compact',
+            delta: bind('/kpi/requestsDelta'),
+            caption: 'vs the previous week'
+        }),
+        node('m_attacks', 'Metric', {
+            title: 'Attacks',
+            value: bind('/kpi/attacks'),
+            format: 'compact',
+            delta: bind('/kpi/attacksDelta'),
+            caption: 'vs the previous week'
+        }),
+        node('m_blocked', 'Metric', {
+            title: 'Blocked',
+            value: bind('/kpi/blockedPercent'),
+            format: 'percent',
+            delta: bind('/kpi/blockedDelta'),
+            caption: 'of attacks'
+        })
+    ],
+    [
+        node('attack_trend', 'AreaChart', {
+            title: 'Attacks vs blocked',
+            variant: 'standard',
+            series: [
+                {
+                    key: 'attacks',
+                    label: 'Attacks',
+                    color: 'red'
+                },
+                {
+                    key: 'blocked',
+                    label: 'Blocked',
+                    color: 'green'
+                }
+            ],
+            points: bind('/daily'),
+            xFormat: 'date',
+            yFormat: 'compact'
+        }),
+        node('attack_types', 'BarList', {
+            title: 'Top attack types',
+            items: bind('/attackTypes')
+        })
+    ],
+    [
+        node('response_codes', 'HorizontalBarStack', {
+            title: 'Response codes',
+            items: bind('/responseCodes'),
+            legend: true
+        })
+    ],
+    [
+        node('recommendations', 'Stack', {
+            gap: '8'
+        }, [
+            'rec_title',
+            'rec_1',
+            'rec_2',
+            'rec_3'
+        ]),
+        node('rec_title', 'Heading', {
+            text: 'Recommendations',
+            size: 'md'
+        }),
+        node('rec_1', 'Alert', {
+            tone: 'info',
+            title: 'Turn on brute-force protection',
+            description: 'POST /api/v2/auth/login takes most of the credential attacks.'
+        }),
+        node('rec_2', 'Alert', {
+            tone: 'info',
+            title: 'Enforce object ownership checks',
+            description: 'The BOLA hits on /api/v2/orders read orders that belong to other users.'
+        }),
+        node('rec_3', 'Alert', {
+            tone: 'info',
+            title: 'Block path traversal',
+            description: 'Move the path traversal rules from monitoring to blocking mode.'
+        }),
+        node('actions', 'Stack', {
+            direction: 'row',
+            gap: '8'
+        }, [
+            'share'
+        ]),
+        {
+            ...node('share', 'Button', {
+                label: 'Share with the team',
+                variant: 'primary'
+            }),
+            press: {
+                action: 'share_report',
+                params: {
+                    report: 'weekly-security',
+                    week: '2026-W45'
+                }
+            }
+        }
+    ]
+];
+const WEEKLY_REPORT_SCENARIO = {
+    id: 'weekly-report',
+    prompt: 'Write a weekly security report for my team',
+    summary: 'A summary, KPI tiles, attacks vs blocked by day, breakdowns and recommendations',
+    surfaceId: 'weekly_report',
+    actions: WEEKLY_REPORT_ACTIONS,
+    layout: LAYOUT,
+    data: [
+        {
+            after: 1,
+            values: [
+                {
+                    path: '/kpi',
+                    value: WEEKLY_REPORT_DATA.kpi
+                }
+            ]
+        },
+        {
+            after: 2,
+            values: [
+                {
+                    path: '/daily',
+                    value: WEEKLY_REPORT_DATA.daily
+                },
+                {
+                    path: '/attackTypes',
+                    value: WEEKLY_REPORT_DATA.attackTypes
+                }
+            ]
+        },
+        {
+            after: 3,
+            values: [
+                {
+                    path: '/responseCodes',
+                    value: WEEKLY_REPORT_DATA.responseCodes
+                }
+            ]
+        }
+    ]
+};
+export { WEEKLY_REPORT_ACTIONS, WEEKLY_REPORT_DATA, WEEKLY_REPORT_SCENARIO };

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@wallarm-org/gen-ui`: the catalog and the API to define entries. The formats live in their own
+ * entry points, `@wallarm-org/gen-ui/a2ui` and `@wallarm-org/gen-ui/json-render`.
+ */
+export * from './components/index.js';
+export { type AnswerNode, type CheckOptions, describeIssues, type GenUiIssue, } from './core/check.js';
+export { allOf, defineComponent, type GenUiAction, type GenUiActionHandler, type GenUiComponent, type GenUiViewProps, seriesKey, subsetOf, unique, type Values, } from './core/define.js';
+export { formatNumber, formatTime, NUMBER_FORMATS, type NumberFormat, numberFormat, TIME_FORMATS, type TimeFormat, timeFormat, } from './core/format.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./components/index.js";
+export { describeIssues } from "./core/check.js";
+export { allOf, defineComponent, seriesKey, subsetOf, unique } from "./core/define.js";
+export { NUMBER_FORMATS, TIME_FORMATS, formatNumber, formatTime, numberFormat, timeFormat } from "./core/format.js";

package/dist/json-render/JsonRenderSurface.d.ts

@@ -0,0 +1,13 @@
+import { type FC } from 'react';
+import { type Spec } from '@json-render/core';
+import type { GenUiActionHandler } from '../core/define.js';
+import type { JsonRenderCatalog } from './catalog.js';
+export interface JsonRenderSurfaceProps {
+    catalog: JsonRenderCatalog;
+    /** The spec so far (`specFromLines`); it grows while the model streams. */
+    spec: Spec | null;
+    streaming?: boolean;
+    onAction: GenUiActionHandler;
+}
+/** Renders one json-render spec through the catalog: actions allowlisted, state kept in step. */
+export declare const JsonRenderSurface: FC<JsonRenderSurfaceProps>;

package/dist/json-render/JsonRenderSurface.js

@@ -0,0 +1,63 @@
+import { jsx } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { createStateStore } from "@json-render/core";
+import { JSONUIProvider, Renderer } from "@json-render/react";
+import { isRecord } from "../core/guards.js";
+import { Placeholder } from "../render/Placeholder.js";
+import { SurfaceBoundary } from "../render/SurfaceBoundary.js";
+import { sanitizeSpec } from "./spec.js";
+const JsonRenderSurface = ({ catalog, spec, streaming, onAction })=>{
+    const onActionRef = useRef(onAction);
+    useEffect(()=>{
+        onActionRef.current = onAction;
+    });
+    const [handlers] = useState(()=>Object.fromEntries(catalog.actions.map((a)=>[
+                a.name,
+                (params)=>onActionRef.current(a.name, params)
+            ])));
+    const [store] = useState(()=>createStateStore(spec?.state ?? {}));
+    const applied = useRef({});
+    useEffect(()=>{
+        const next = leaves(spec?.state ?? {});
+        const updates = {};
+        for (const [pointer, value] of Object.entries(next)){
+            const json = JSON.stringify(value);
+            if (applied.current[pointer] !== json) updates[pointer] = value;
+            applied.current[pointer] = json;
+        }
+        for (const pointer of Object.keys(applied.current))if (!(pointer in next)) {
+            updates[pointer] = void 0;
+            delete applied.current[pointer];
+        }
+        if (Object.keys(updates).length) store.update(updates);
+    }, [
+        spec?.state,
+        store
+    ]);
+    return /*#__PURE__*/ jsx(JSONUIProvider, {
+        registry: catalog.registry,
+        store: store,
+        handlers: handlers,
+        children: /*#__PURE__*/ jsx(SurfaceBoundary, {
+            children: /*#__PURE__*/ jsx(Renderer, {
+                spec: sanitizeSpec(spec, catalog.actions),
+                registry: catalog.registry,
+                loading: streaming,
+                fallback: PendingElement
+            })
+        })
+    });
+};
+const PendingElement = ({ element })=>/*#__PURE__*/ jsx(Placeholder, {
+        id: String(element.props.id ?? element.type)
+    });
+const leaves = (value, prefix = '')=>Object.fromEntries(Object.entries(value).flatMap(([key, v])=>{
+        const pointer = `${prefix}/${key.replace(/~/g, '~0').replace(/\//g, '~1')}`;
+        return isRecord(v) ? Object.entries(leaves(v, pointer)) : [
+            [
+                pointer,
+                v
+            ]
+        ];
+    }));
+export { JsonRenderSurface };