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

package/dist/components/Table.js

@@ -0,0 +1,128 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Badge } from "@wallarm-org/design-system/Badge";
+import { Code } from "@wallarm-org/design-system/Code";
+import { FormatDateTime } from "@wallarm-org/design-system/FormatDateTime";
+import { Heading } from "@wallarm-org/design-system/Heading";
+import { HttpMethod } from "@wallarm-org/design-system/HttpMethod";
+import { Ip, IpAddress } from "@wallarm-org/design-system/Ip";
+import { ResponseCode } from "@wallarm-org/design-system/ResponseCode";
+import { Skeleton } from "@wallarm-org/design-system/Skeleton";
+import { Table, createTableColumnHelper } from "@wallarm-org/design-system/Table";
+import { cn } from "@wallarm-org/design-system/utils/cn";
+import { allOf, defineComponent } from "../core/define.js";
+import { NUMBER_FORMATS, formatNumber } from "../core/format.js";
+import * as __rspack_external_zod from "zod";
+const DATE_FORMATS = allOf()([
+    'relative',
+    'date',
+    'datetime'
+]);
+const CELL_TYPES = [
+    'text',
+    'number',
+    'badge',
+    'datetime',
+    'code',
+    'ip',
+    'method',
+    'status'
+];
+const isNumberFormat = (f)=>NUMBER_FORMATS.some((n)=>n === f);
+const isDateFormat = (f)=>DATE_FORMATS.some((d)=>d === f);
+const scalar = (value)=>{
+    if ('string' == typeof value || 'number' == typeof value) return value;
+    if ('boolean' == typeof value) return String(value);
+};
+const CELLS = {
+    text: (value)=>value,
+    number: (value, format)=>'number' == typeof value ? formatNumber(value, isNumberFormat(format) ? format : 'number') : value,
+    badge: (value)=>/*#__PURE__*/ jsx(Badge, {
+            type: "secondary",
+            color: "slate",
+            children: value
+        }),
+    datetime: (value, format)=>/*#__PURE__*/ jsx(FormatDateTime, {
+            value: value,
+            format: isDateFormat(format) ? format : 'datetime',
+            layout: "inline"
+        }),
+    code: (value)=>/*#__PURE__*/ jsx(Code, {
+            size: "s",
+            truncate: true,
+            children: value
+        }),
+    ip: (value)=>/*#__PURE__*/ jsx(Ip, {
+            children: /*#__PURE__*/ jsx(IpAddress, {
+                children: value
+            })
+        }),
+    method: (value)=>/*#__PURE__*/ jsx(HttpMethod, {
+            method: String(value)
+        }),
+    status: (value)=>/*#__PURE__*/ jsx(ResponseCode, {
+            code: value
+        })
+};
+const column = createTableColumnHelper();
+const TableComponent = defineComponent({
+    name: 'Table',
+    description: 'A read-only table of records: requests, events, IPs, rules. Use it when the user needs to compare rows across several fields; for a ranked top-N of one number prefer BarList. Each row is a flat object of strings and numbers keyed by the column keys; rowKey names the field that is unique per row. Column types: datetime takes an ISO time or epoch ms, ip an IP string, method an HTTP verb, status an HTTP response code, code a short literal (path, payload, rule id), badge a short label. Send rows in display order: there is no sorting, paging or selection.',
+    props: __rspack_external_zod.object({
+        title: __rspack_external_zod.string().optional(),
+        rowKey: __rspack_external_zod.string().describe('The row field that is unique per row, e.g. "requestId"'),
+        columns: __rspack_external_zod.array(__rspack_external_zod.object({
+            key: __rspack_external_zod.string().describe('The row field this column shows'),
+            header: __rspack_external_zod.string(),
+            type: __rspack_external_zod["enum"](CELL_TYPES).optional().describe('Default text'),
+            format: __rspack_external_zod["enum"]([
+                ...NUMBER_FORMATS,
+                ...DATE_FORMATS
+            ]).optional().describe('number columns: number, compact, percent (0-100), bytes, ms; datetime columns: relative, date, datetime')
+        })),
+        rows: __rspack_external_zod.array(__rspack_external_zod.looseObject({})).describe('One object per row, keyed by the column keys')
+    }),
+    Skeleton: ()=>/*#__PURE__*/ jsx(Skeleton, {
+            width: "100%",
+            height: "240px",
+            rounded: 8,
+            transparent: false
+        }),
+    View: ({ props })=>{
+        const columns = props.columns.map(({ key, header, type = 'text', format })=>column.accessor(key, {
+                header: header ?? key,
+                meta: {
+                    align: 'number' === type ? 'right' : 'left'
+                },
+                cell: ({ row })=>{
+                    const value = scalar(row.original[key]);
+                    return void 0 === value || '' === value ? '—' : CELLS[type](value, format);
+                }
+            }));
+        const { rows } = props;
+        const seen = new Set();
+        const rowIds = rows.map((row, index)=>{
+            const base = String(scalar(row[props.rowKey]) ?? `#${index}`);
+            const rowId = seen.has(base) ? `${base}#${index}` : base;
+            seen.add(rowId);
+            return rowId;
+        });
+        const getRowId = (_row, index)=>rowIds[index] ?? String(index);
+        return /*#__PURE__*/ jsxs("div", {
+            className: cn('flex min-w-0 flex-col gap-8'),
+            children: [
+                props.title && /*#__PURE__*/ jsx(Heading, {
+                    size: "md",
+                    weight: "medium",
+                    children: props.title
+                }),
+                /*#__PURE__*/ jsx(Table, {
+                    data: rows,
+                    columns: columns,
+                    getRowId: getRowId,
+                    "aria-label": props.title
+                })
+            ]
+        });
+    }
+});
+export { TableComponent };

package/dist/components/Text.d.ts

@@ -0,0 +1,9 @@
+import * as z from 'zod';
+export declare const TextComponent: import("../index.js").GenUiComponent<z.ZodObject<{
+    text: z.ZodString;
+    tone: z.ZodOptional<z.ZodEnum<{
+        danger: "danger";
+        primary: "primary";
+        secondary: "secondary";
+    }>>;
+}, z.core.$strip>>;

package/dist/components/Text.js

@@ -0,0 +1,27 @@
+import { jsx } from "react/jsx-runtime";
+import { Skeleton } from "@wallarm-org/design-system/Skeleton";
+import { Text } from "@wallarm-org/design-system/Text";
+import { defineComponent, subsetOf } from "../core/define.js";
+import * as __rspack_external_zod from "zod";
+const TextComponent = defineComponent({
+    name: 'Text',
+    description: 'A paragraph of plain text (no markdown).',
+    props: __rspack_external_zod.object({
+        text: __rspack_external_zod.string(),
+        tone: __rspack_external_zod["enum"](subsetOf()([
+            'primary',
+            'secondary',
+            'danger'
+        ])).optional()
+    }),
+    Skeleton: ()=>/*#__PURE__*/ jsx(Skeleton, {
+            width: "100%",
+            height: "16px",
+            transparent: false
+        }),
+    View: ({ props })=>/*#__PURE__*/ jsx(Text, {
+            color: props.tone ?? 'primary',
+            children: props.text
+        })
+});
+export { TextComponent };

package/dist/components/index.d.ts

@@ -0,0 +1,20 @@
+import type { GenUiComponent } from '../core/define.js';
+export * from './Alert.js';
+export * from './AreaChart.js';
+export * from './Badge.js';
+export * from './BarList.js';
+export * from './Button.js';
+export * from './Card.js';
+export * from './ColumnChart.js';
+export * from './Grid.js';
+export * from './Heading.js';
+export * from './HorizontalBarStack.js';
+export * from './LineChart.js';
+export * from './Metric.js';
+export * from './PieChart.js';
+export * from './Section.js';
+export * from './Stack.js';
+export * from './Table.js';
+export * from './Text.js';
+/** The catalog: layout (Section, Grid, Stack, Card), text, status, actions, charts and Table. */
+export declare const wallarmComponents: readonly GenUiComponent[];

package/dist/components/index.js

@@ -0,0 +1,55 @@
+import { AlertComponent } from "./Alert.js";
+import { AreaChartComponent } from "./AreaChart.js";
+import { BadgeComponent } from "./Badge.js";
+import { BarListComponent } from "./BarList.js";
+import { ButtonComponent } from "./Button.js";
+import { CardComponent } from "./Card.js";
+import { ColumnChartComponent } from "./ColumnChart.js";
+import { GridComponent, GridItemComponent } from "./Grid.js";
+import { HeadingComponent } from "./Heading.js";
+import { HorizontalBarStackComponent } from "./HorizontalBarStack.js";
+import { LineChartComponent } from "./LineChart.js";
+import { MetricComponent } from "./Metric.js";
+import { PieChartComponent } from "./PieChart.js";
+import { SectionComponent } from "./Section.js";
+import { StackComponent } from "./Stack.js";
+import { TableComponent } from "./Table.js";
+import { TextComponent } from "./Text.js";
+export * from "./Alert.js";
+export * from "./AreaChart.js";
+export * from "./Badge.js";
+export * from "./BarList.js";
+export * from "./Button.js";
+export * from "./Card.js";
+export * from "./ColumnChart.js";
+export * from "./Grid.js";
+export * from "./Heading.js";
+export * from "./HorizontalBarStack.js";
+export * from "./LineChart.js";
+export * from "./Metric.js";
+export * from "./PieChart.js";
+export * from "./Section.js";
+export * from "./Stack.js";
+export * from "./Table.js";
+export * from "./Text.js";
+const wallarmComponents = [
+    SectionComponent,
+    GridComponent,
+    GridItemComponent,
+    StackComponent,
+    CardComponent,
+    HeadingComponent,
+    TextComponent,
+    BadgeComponent,
+    AlertComponent,
+    ButtonComponent,
+    MetricComponent,
+    BarListComponent,
+    HorizontalBarStackComponent,
+    PieChartComponent,
+    LineChartComponent,
+    AreaChartComponent,
+    ColumnChartComponent,
+    TableComponent
+];
+export { wallarmComponents };

package/dist/core/check.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Checks a finished answer for the agent's own mistakes, the ones that would leave a skeleton on
+ * the page for good: an unknown component, a prop its schema rejects, a child that was never
+ * sent, an action outside the allowlist. A bound prop is never an issue: its value is the app's.
+ * Each format reads its answer into nodes (`checkA2uiAnswer`, `checkJsonRenderAnswer`); the result
+ * goes back to the model as a "fix these" message (`describeIssues`) or into an eval.
+ */
+import type { GenUiAction, GenUiComponent } from './define.js';
+/** One component of an answer, as both formats describe it. */
+export interface AnswerNode {
+    id: string;
+    type: string;
+    /** Data props only: no children, no action props. */
+    props: Record<string, unknown>;
+    children: readonly string[];
+    /** Names of the actions the component fires. */
+    actions: readonly string[];
+}
+export interface GenUiIssue {
+    /** The agent's component id; the root's id for an issue with the answer as a whole. */
+    id: string;
+    component?: string;
+    /** The prop, dot-separated, when the issue is in one. */
+    prop?: string;
+    message: string;
+}
+export interface CheckOptions {
+    components: readonly GenUiComponent[];
+    actions: readonly GenUiAction[];
+    /** Report a number written into a prop instead of bound: a figure the model may have made up. */
+    boundFigures?: boolean;
+}
+export declare const checkNodes: (nodes: readonly AnswerNode[], rootId: string | undefined, isBinding: (value: unknown) => boolean, { components, actions, boundFigures }: CheckOptions) => GenUiIssue[];
+/** The issues as one message to send the model, asking it to resend only those components. */
+export declare const describeIssues: (issues: readonly GenUiIssue[]) => string;

package/dist/core/check.js

@@ -0,0 +1,63 @@
+import { isRecord } from "./guards.js";
+const checkNodes = (nodes, rootId, isBinding, { components, actions, boundFigures = false })=>{
+    const issues = [];
+    const ids = new Set(nodes.map((node)=>node.id));
+    if (!rootId || !ids.has(rootId)) issues.push({
+        id: rootId ?? 'root',
+        message: 'The answer has no root component.'
+    });
+    for (const node of nodes){
+        const at = {
+            id: node.id,
+            component: node.type
+        };
+        const entry = components.find((c)=>c.name === node.type);
+        if (!entry) {
+            issues.push({
+                ...at,
+                message: `Unknown component "${node.type}".`
+            });
+            continue;
+        }
+        const parsed = entry.props.safeParse(node.props);
+        for (const issue of parsed.success ? [] : parsed.error.issues)if (!boundOnPath(node.props, issue.path, isBinding)) issues.push({
+            ...at,
+            prop: issue.path.join('.') || void 0,
+            message: issue.message
+        });
+        for (const child of node.children)if (!ids.has(child)) issues.push({
+            ...at,
+            message: `Child "${child}" was never sent.`
+        });
+        for (const action of node.actions)if (!actions.some((a)=>a.name === action)) issues.push({
+            ...at,
+            message: `Action "${action}" is not allowed.`
+        });
+        if (boundFigures) for (const prop of literalNumbers(node.props, isBinding))issues.push({
+            ...at,
+            prop,
+            message: 'A figure is written in; bind it to the app data.'
+        });
+    }
+    return issues;
+};
+const describeIssues = (issues)=>[
+        'Some components in your answer cannot render. Fix them and resend only these components:',
+        ...issues.map((i)=>`- ${i.id}${i.component ? ` (${i.component})` : ''}${i.prop ? `, ${i.prop}` : ''}: ${i.message}`)
+    ].join('\n');
+const boundOnPath = (props, path, isBinding)=>{
+    let value = props;
+    for (const key of path){
+        if (isBinding(value)) return true;
+        value = 'object' == typeof value && null !== value ? Reflect.get(value, key) : void 0;
+    }
+    return isBinding(value);
+};
+const literalNumbers = (value, isBinding, prefix = '')=>{
+    if ('number' == typeof value) return [
+        prefix
+    ];
+    if (isBinding(value) || !(isRecord(value) || Array.isArray(value))) return [];
+    return Object.entries(value).flatMap(([key, v])=>literalNumbers(v, isBinding, prefix ? `${prefix}.${key}` : key));
+};
+export { checkNodes, describeIssues };

package/dist/core/define.d.ts

@@ -0,0 +1,64 @@
+import type { FC, ReactNode } from 'react';
+import * as z from 'zod';
+/** What a component's View receives from either format's renderer. */
+export interface GenUiViewProps<P> {
+    /** Props with every binding already resolved to a value. */
+    props: P;
+    /** Fires one of the component's `events`; the format decides what reaches the agent. */
+    emit: (event: string) => void;
+    /** Rendered children, when the component `hasChildren`. */
+    children?: ReactNode;
+}
+/**
+ * One catalog entry, written once and rendered by both formats.
+ *
+ * Constraints that keep it portable:
+ * - `props` is a plain zod object of strings, numbers, booleans, enums, arrays and objects:
+ *   no functions, no ReactNode.
+ * - No prop named `id`, `component`, `children` or `child`: A2UI puts props flat next to them.
+ * - Events carry no arguments: the spec, not the component, decides what an action sends.
+ */
+export interface GenUiComponent<S extends z.ZodObject = z.ZodObject> {
+    name: string;
+    /** Read by the model: say when to use it, not how it looks. */
+    description: string;
+    props: S;
+    events?: readonly string[];
+    hasChildren?: boolean;
+    View: FC<GenUiViewProps<z.infer<S>>>;
+    /**
+     * Drawn while the props don't match the schema yet (mid-stream: data still on its way), shaped
+     * like the loaded component so the layout doesn't jump. Gets the title once it has streamed in.
+     * Default: a plain block.
+     */
+    Skeleton?: FC<{
+        title?: string;
+    }>;
+}
+/** An app action a spec may bind a component event to, e.g. `block_ip`. */
+export interface GenUiAction {
+    name: string;
+    description: string;
+}
+/** Where both formats deliver a fired action; `params` comes from the spec, never from the View. */
+export type GenUiActionHandler = (name: string, params: Record<string, unknown>) => void;
+export declare const defineComponent: <S extends z.ZodObject>(c: GenUiComponent<S>) => GenUiComponent<S>;
+/** The string values of a DS prop type: `Values<BadgeProps['color']>`. */
+export type Values<T> = Extract<NonNullable<T>, string>;
+/**
+ * The enum values a catalog entry offers, checked against the DS union they come from, so the two
+ * can't drift: `z.enum(subsetOf<BadgeColor>()(['slate', 'red']))`. A value the DS renames or removes
+ * fails typecheck. Use it where the catalog deliberately offers fewer values than the DS has.
+ */
+export declare const subsetOf: <T extends string>() => <const A extends readonly [T, ...T[]]>(values: A) => A;
+/**
+ * Like `subsetOf`, for a DS union the catalog offers in full (a meaning, not a palette). It also
+ * fails typecheck with `{ missing: '<value>' }` when the DS adds a value the list lacks.
+ */
+export declare const allOf: <T extends string>() => <const A extends readonly [T, ...T[]]>(values: A & ([Exclude<T, A[number]>] extends [never] ? unknown : {
+    missing: Exclude<T, A[number]>;
+})) => A;
+/** A series' field in each point. `x` is the axis, and `__`-prefixed keys are the Views' own. */
+export declare const seriesKey: z.ZodString;
+/** For `.refine` on an array of items keyed by `field`: React keys and the DS join on it. */
+export declare const unique: <K extends string>(field: K) => (items: readonly Partial<Record<K, unknown>>[]) => boolean;

package/dist/core/define.js

@@ -0,0 +1,7 @@
+import * as __rspack_external_zod from "zod";
+const defineComponent = (c)=>c;
+const subsetOf = ()=>(values)=>values;
+const allOf = ()=>(values)=>values;
+const seriesKey = __rspack_external_zod.string().refine((key)=>'x' !== key && !key.startsWith('__'), 'x and __-prefixed keys are reserved');
+const unique = (field)=>(items)=>new Set(items.map((item)=>item[field])).size === items.length;
+export { allOf, defineComponent, seriesKey, subsetOf, unique };

package/dist/core/format.d.ts

@@ -0,0 +1,24 @@
+import * as z from 'zod';
+/**
+ * Named formats instead of formatter functions: a spec is data, so a chart axis or a table cell
+ * says `'percent'` and the View formats it. One registry for Metric, the charts and Table.
+ */
+export declare const NUMBER_FORMATS: readonly ['number', 'compact', 'percent', 'bytes', 'ms'];
+export declare const TIME_FORMATS: readonly ['time', 'date', 'datetime'];
+export type NumberFormat = (typeof NUMBER_FORMATS)[number];
+export type TimeFormat = (typeof TIME_FORMATS)[number];
+export declare const numberFormat: z.ZodOptional<z.ZodEnum<{
+    bytes: "bytes";
+    compact: "compact";
+    ms: "ms";
+    number: "number";
+    percent: "percent";
+}>>;
+export declare const timeFormat: z.ZodOptional<z.ZodEnum<{
+    date: "date";
+    datetime: "datetime";
+    time: "time";
+}>>;
+export declare const formatNumber: (value: number, format?: NumberFormat) => string;
+/** An ISO string or epoch ms; an unparseable value is printed as is. */
+export declare const formatTime: (value: string | number, format?: TimeFormat) => string;

package/dist/core/format.js

@@ -0,0 +1,74 @@
+import * as __rspack_external_zod from "zod";
+const NUMBER_FORMATS = [
+    'number',
+    'compact',
+    'percent',
+    'bytes',
+    'ms'
+];
+const TIME_FORMATS = [
+    'time',
+    'date',
+    'datetime'
+];
+const numberFormat = __rspack_external_zod["enum"](NUMBER_FORMATS).optional().describe('number 1,240 · compact 1.2K · percent 42% (value is 0-100) · bytes 1.2 MB · ms 340 ms');
+const timeFormat = __rspack_external_zod["enum"](TIME_FORMATS).optional().describe('How to print ISO timestamps: time 14:05 · date 5 Nov · datetime 5 Nov, 14:05');
+const BYTE_UNITS = [
+    'B',
+    'KB',
+    'MB',
+    'GB',
+    'TB'
+];
+const formatNumber = (value, format = 'number')=>{
+    switch(format){
+        case 'compact':
+            return new Intl.NumberFormat('en-US', {
+                notation: 'compact',
+                maximumFractionDigits: 1
+            }).format(value);
+        case 'percent':
+            return `${new Intl.NumberFormat('en-US', {
+                maximumFractionDigits: 1
+            }).format(value)}%`;
+        case 'bytes':
+            {
+                let unit = 0;
+                let n = Math.abs(value);
+                while(n >= 1024 && unit < BYTE_UNITS.length - 1){
+                    n /= 1024;
+                    unit++;
+                }
+                return `${Math.sign(value) < 0 ? '-' : ''}${n.toFixed(unit && n < 10 ? 1 : 0)} ${BYTE_UNITS[unit]}`;
+            }
+        case 'ms':
+            return `${new Intl.NumberFormat('en-US', {
+                maximumFractionDigits: 0
+            }).format(value)} ms`;
+        default:
+            return value.toLocaleString('en-US');
+    }
+};
+const TIME_OPTIONS = {
+    time: {
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23'
+    },
+    date: {
+        day: 'numeric',
+        month: 'short'
+    },
+    datetime: {
+        day: 'numeric',
+        month: 'short',
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23'
+    }
+};
+const formatTime = (value, format = 'datetime')=>{
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? String(value) : new Intl.DateTimeFormat('en-GB', TIME_OPTIONS[format]).format(date);
+};
+export { NUMBER_FORMATS, TIME_FORMATS, formatNumber, formatTime, numberFormat, timeFormat };

package/dist/core/guards.d.ts

@@ -0,0 +1,2 @@
+/** Agent output is untrusted: narrow before reading a field. */
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/core/guards.js

@@ -0,0 +1,2 @@
+const isRecord = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+export { isRecord };

package/dist/fixtures/apiInventory.d.ts

@@ -0,0 +1,36 @@
+/**
+ * An API inventory answer: the agent lays out where sensitive data is exposed, with every figure
+ * bound to a path, and the app fills those paths from its API Discovery data.
+ */
+import type { GenUiAction } from '../core/define.js';
+import { type Scenario } from './stream.js';
+export declare const API_INVENTORY_DATA: {
+    kpi: {
+        endpoints: number;
+        sensitive: number;
+        unauthenticated: number;
+        newThisWeek: number;
+    };
+    dataTypes: {
+        label: string;
+        value: number;
+        color: string;
+    }[];
+    newEndpoints: {
+        x: string;
+        sensitive: number;
+        other: number;
+    }[];
+    endpoints: {
+        id: string;
+        method: string;
+        path: string;
+        status: number;
+        dataType: string;
+        hits: number;
+        last: string;
+    }[];
+};
+export declare const API_INVENTORY_ACTIONS: readonly GenUiAction[];
+/** API inventory: KPI tiles, sensitive data types, new endpoints per day and an endpoints table. */
+export declare const API_INVENTORY_SCENARIO: Scenario;