@magicvr/schema-ui-renderer 0.3.0 → 0.3.2

package/renderer/reaction-engine.d.ts

@@ -1,92 +0,0 @@
-/**
- * Multi-round snapshot reaction engine (schema-ui-docs@2.7.0 · 02-reaction-expression.md §14).
- *
- * Implements the upstream conformance contract (`conformance/fixtures/reactions/cases.json`):
- *   Snapshot → Evaluate → Commit → Next tick, with:
- *   - per-field reactions [{ when, fulfill, otherwise }] (value/visible/required/disabled)
- *   - observers evaluated against every round snapshot
- *   - baselines + resetMissingOtherwise (condition false without otherwise → restore baseline;
- *     explicit writes win over implicit baseline restores)
- *   - externalUpdates applied between rounds
- *   - deep-equal change detection (no commit / no next round on no-op writes)
- *   - loop protection (REACTION_LOOP_LIMIT after maxRounds, default 10)
- *   - MULTIPLE_VALUE_WRITES warnings (last write wins, deterministic order)
- */
-export interface ReactionRuleInput {
-    when: string;
-    fulfill?: Record<string, unknown>;
-    otherwise?: Record<string, unknown>;
-}
-export interface FieldReactionInput {
-    field: string;
-    reactions: ReactionRuleInput[];
-}
-export interface ReactionObserverInput {
-    id: string;
-    when: string;
-}
-export interface ExternalUpdateInput {
-    afterRound: number;
-    values: Record<string, unknown>;
-}
-export interface ReactionEngineInput {
-    initialValues: Record<string, unknown>;
-    fields?: FieldReactionInput[];
-    observers?: ReactionObserverInput[];
-    baselines?: Record<string, unknown>;
-    resetMissingOtherwise?: boolean;
-    externalUpdates?: ExternalUpdateInput[];
-    maxRounds?: number;
-}
-export interface ReactionRound {
-    round: number;
-    snapshot: Record<string, unknown>;
-    observations: Record<string, boolean>;
-    commits: Array<{
-        field: string;
-        value: unknown;
-    }>;
-}
-export interface MultipleValueWritesWarning {
-    code: "MULTIPLE_VALUE_WRITES";
-    field: string;
-    count: number;
-}
-export interface ReactionEngineOk {
-    ok: true;
-    values: Record<string, unknown>;
-    rounds: ReactionRound[];
-    warnings: MultipleValueWritesWarning[];
-}
-export interface ReactionEngineLoopError {
-    ok: false;
-    code: "REACTION_LOOP_LIMIT";
-    maxRounds: number;
-    values: Record<string, unknown>;
-    roundCount: number;
-    dependencyFields: string[];
-}
-export type ReactionEngineResult = ReactionEngineOk | ReactionEngineLoopError;
-/** Per-field control state after convergence (renderer integration). */
-export interface ReactionFieldState {
-    visible?: boolean;
-    required?: boolean;
-    disabled?: boolean;
-}
-export interface ReactionEngineDetailed {
-    result: ReactionEngineResult;
-    fieldStates: Record<string, ReactionFieldState>;
-}
-export declare const DEFAULT_MAX_ROUNDS = 10;
-/**
- * Runs the multi-round engine.
- *
- * A field's committed `value` only lands in `commits` when it deep-differs
- * from the snapshot value; a no-op write neither commits nor schedules the
- * next round. Rounds stop when no committed field is a dependency of any
- * expression (reaction when or observer when).
- */
-export declare function runReactionEngine(input: ReactionEngineInput): ReactionEngineResult;
-/** Engine + per-field control state (visible/required/disabled/value) from
- * the final round — used by the Renderer's form integration. */
-export declare function runReactionEngineDetailed(input: ReactionEngineInput): ReactionEngineDetailed;

package/renderer/reaction-expression.d.ts

@@ -1,74 +0,0 @@
-/**
- * Full protocol expression engine (schema-ui-docs@2.7.0 · docs/02-reaction-expression.md).
- *
- * Whitelisted grammar (no eval / new Function):
- *   - namespaces: $deps.<field>, $self, $context.user.* / $context.features.*
- *   - operators:  ==  !=  >  >=  <  <=  contains  &&  ||  !
- *   - grouping:   ( )
- *   - literals:   'str' | "str" | number (int/float/exponent) | true | false | null
- *
- * Semantics (ADR-0016 / §7-§14):
- *   - strict typing, no coercion: 1 == 1.0 true; 1 == '1' false; true == 1 false
- *   - contains: array left operand, strict element equality; non-array → false
- *   - string ordering by Unicode code points (not UTF-16 code units)
- *   - undefined values compare as false (missing deps never throw)
- */
-export type ExprValue = string | number | boolean | null | ExprValue[] | {
-    [key: string]: ExprValue;
-} | undefined;
-export interface ReactionEnv {
-    /** $deps.<field> values (form field snapshot). */
-    deps?: Record<string, unknown>;
-    /** $self (current field value). */
-    self?: unknown;
-    /** $context.user.* / $context.features.* snapshots. */
-    context?: Record<string, unknown>;
-}
-export type ParseError = {
-    ok: false;
-    code: "SYNTAX";
-    message: string;
-} | {
-    ok: false;
-    code: "FORBIDDEN_VARIABLE";
-    message: string;
-} | {
-    ok: false;
-    code: "UNSUPPORTED_OPERATOR";
-    message: string;
-};
-export type ParsedExpr = {
-    kind: "literal";
-    value: ExprValue;
-} | {
-    kind: "var";
-    path: string[];
-} | {
-    kind: "self";
-} | {
-    kind: "not";
-    operand: ParsedExpr;
-} | {
-    kind: "and";
-    left: ParsedExpr;
-    right: ParsedExpr;
-} | {
-    kind: "or";
-    left: ParsedExpr;
-    right: ParsedExpr;
-} | {
-    kind: "compare";
-    op: "==" | "!=" | ">" | ">=" | "<" | "<=" | "contains";
-    left: ParsedExpr;
-    right: ParsedExpr;
-};
-/** Parses a whitelisted expression; returns the AST or a typed error. */
-export declare function parseExpression(source: string): ParsedExpr | ParseError;
-/** Deep equality (arrays/objects by structure; scalars by strict identity). */
-export declare function deepEqual(left: unknown, right: unknown): boolean;
-/** Evaluates a whitelisted expression to a boolean; invalid input → false. */
-export declare function evaluateFullExpression(source: string, env: ReactionEnv): boolean;
-/** True when `source` parses under the full grammar. */
-export declare function isValidFullExpression(source: string): boolean;
-/** Extracts the $deps.<root> field names referenced by an expression. */
-export declare function expressionDependencyFields(source: string): string[];

package/renderer/reactions.d.ts

@@ -1,64 +0,0 @@
-/**
- * R5 D-EXPR reaction surface (frozen Q: reactions operate on the $context
- * namespace only; no field-value triggers).
- *
- * A reaction is a `{ when, apply }` rule: `when` is a frozen $context
- * expression (evaluateExpression grammar), and `apply` turns a form control
- * state on/off when the expression holds. This is the renderer-level
- * equivalent of the navigation visibleWhen gate, applied to form fields.
- *
- * Fails closed: an unparseable `when` expression or an unknown apply target
- * keeps the field at its default state instead of mutating it silently.
- */
-export interface ReactionApply {
-    fieldId: string;
-    /** visible/disabled toggles are explicit booleans (no implicit flip). */
-    visible?: boolean;
-    disabled?: boolean;
-}
-export interface ReactionRule {
-    id: string;
-    when: string;
-    apply: ReactionApply[];
-}
-export type ReactionErrorCode = "REACTION_EXPRESSION_INVALID" | "REACTION_APPLY_FIELD_UNKNOWN" | "REACTION_APPLY_INVALID";
-export interface ReactionError {
-    code: ReactionErrorCode;
-    path: string;
-    message: string;
-}
-export interface FormControlState {
-    visible: boolean;
-    disabled: boolean;
-}
-export type FormControlStateMap = Record<string, FormControlState>;
-export interface ReactionEvaluation {
-    state: FormControlStateMap;
-    errors: ReactionError[];
-}
-/** Parses a raw reaction rule, fail-closed on malformed shapes. */
-export declare function parseReactionRule(value: unknown, path: string): ReactionRule | ReactionError;
-/**
- * Evaluates a reaction rule list against the frozen $context snapshot.
- * Unknown apply fieldIds fail closed (keep default) and are reported.
- */
-export declare function evaluateReactions(rules: ReactionRule[], context: Record<string, unknown>, fieldIds: string[]): ReactionEvaluation;
-/** Validates raw rules and returns parsed rules + fail-closed errors. */
-export declare function parseAndEvaluateReactions(rawRules: unknown, context: Record<string, unknown>, fieldIds: string[]): ReactionEvaluation;
-export interface FullReactionResult {
-    /** True when the form declares upstream-shaped per-field reactions ($deps). */
-    usesFullEngine: boolean;
-    /** Per-field control state after convergence (visible/disabled). */
-    state: FormControlStateMap;
-    /** Value commits to merge into the form values (last-wins, convergent). */
-    values: Record<string, unknown>;
-    errors: ReactionError[];
-}
-/**
- * Resolves the full multi-round $deps reaction engine over a form's fields.
- *
- * Upstream shape (02-reaction-expression.md): each field node carries
- * `reactions: [{ when, fulfill, otherwise }]`. Returns the convergent control
- * state + value commits; malformed rules fail closed (reported, not applied).
- */
-export declare function resolveFullFormReactions(rawFields: unknown, values: Record<string, unknown>, baselines: Record<string, unknown>): FullReactionResult;

package/renderer/render.d.ts

@@ -1,194 +0,0 @@
-import { type ComponentType, type ReactNode } from "react";
-import { type UploadableFile } from "@schema-ui/protocol/conformance/upload-orchestration";
-import { type FormControlField } from "@schema-ui/renderer/renderer/form-controls.types";
-import { type ResourceList, type ResourceQuery } from "@schema-ui/renderer/renderer/resource";
-import { type RenderActionButtonNode, type RenderChartNode, type RenderFormNode, type RenderPageDocument, type RenderStatCardNode, type RenderTableNode } from "@schema-ui/renderer/renderer/render.types";
-/**
- * R5 D-COMP minimal Renderer (resolve R4 F-002) + S4 Schema CRUD (GOAL-007).
- *
- * Dispatch layer: parses a page document, applies the frozen $context
- * reaction engine to form field state, and renders whitelisted node types
- * through the components in this directory. Unknown node types fail closed.
- *
- * S4 one-time completion (I-007-003 v0.2.2 §9): a SchemaCrudProvider owns the
- * cross-node state a Schema-driven CRUD page needs — selected row (feeds
- * recordView + edit-form prefill), per-table query (search form-to-query
- * binding), a reload token, the active modal, the pending delete confirm, and
- * a generic action executor that gates through the frozen `executeAction`
- * engine and constructs requests with the pinned conformance constructor
- * (`request-construction.ts`). Every page-level behaviour stays fixture-driven;
- * after this completion page behavior remains schema-owned; core fixtures and
- * module-owned schema packages can add pages without Renderer changes.
- *
- * Scope: the frozen §5 node whitelist — layout (grid/section/tabs),
- * data/action (text/table/recordView/actionButton) and form. The form control
- * whitelist itself is enforced by D-FORM (isWhitelistedFormControl /
- * checkFormCapabilities) via gateRenderFormFields. The default app path wires
- * a schema-driven table surface (SchemaTable, GOAL-004) as `tableRenderer`;
- * a table node dispatched without one fails closed with an observable note.
- *
- * A-002 F-002-002 (GOAL-009 S1): form submission is blocked while any
- * gate/reaction error is present — the submit button is disabled and
- * handleSubmit re-rejects before any request can be constructed.
- */
-export interface RendererComponentProps {
-    document: RenderPageDocument;
-    context: Record<string, unknown>;
-    /** Renders a table node; provided by the example page that owns data. */
-    tableRenderer?: (node: RenderTableNode) => ReactNode;
-    /** Renders statCard/chart nodes (supportsData display, registry); defaults to built-ins. */
-    dataRenderer?: (node: RenderStatCardNode | RenderChartNode) => ReactNode;
-    /** Invoked when an actionButton node is activated. */
-    onAction?: (node: RenderActionButtonNode) => void;
-    /**
-     * Session-internal navigation hook (ADR-0021 navigate actions; GOAL-015
-     * F-001): the host pushes the target onto its own history/visit stack so
-     * breadcrumbs survive. Falls back to window.location.assign when absent.
-     */
-    onNavigate?: (url: string) => void;
-    /** Overrides the default FormControls component (keeps field wiring local). */
-    formComponent?: ComponentType<{
-        fields: FormControlField[];
-        values: Record<string, unknown>;
-        onChange: (id: string, value: unknown) => void;
-        fieldDisabled?: (id: string) => boolean;
-        onUpload?: (field: FormControlField, files: UploadableFile[]) => Promise<unknown>;
-        /** W11 · U-01/U-02: auth-aware transport for dynamic option sources. */
-        fetcher?: typeof fetch;
-    }>;
-}
-export interface SchemaCrudFeedback {
-    kind: "success" | "error";
-    message: string;
-    code?: string;
-    /** VP-007 S4: catalog key for the frontend localization floor. */
-    messageKey?: string;
-    /** VP-007 S4: interpolation params for messageKey. */
-    params?: Record<string, unknown>;
-}
-export interface SchemaCrudConfirm {
-    actionRef: string;
-    actionKey: string;
-    row: Record<string, unknown>;
-    requestMapping?: Record<string, unknown>;
-    message: string;
-    /** Batch trigger confirm (ADR-0022 D4/D5): carries the selection snapshot. */
-    batch?: {
-        tableId: string;
-        selection: TableSelection;
-    };
-    /** Toolbar item batchMapping carried through confirm. */
-    batchMapping?: Record<string, unknown>;
-}
-/** Selection snapshot (ADR-0022 D3): ordered keys + count. */
-export interface TableSelection {
-    keys: unknown[];
-    count: number;
-}
-export type ActionResult = {
-    ok: true;
-    fieldErrors?: Array<{
-        field: string;
-        reason: string;
-        rowNumber?: number;
-    }>;
-    message?: string;
-    messageKey?: string;
-} | {
-    ok: false;
-    code: string;
-    message: string;
-    messageKey?: string;
-    params?: Record<string, unknown>;
-    /** GOAL-014 D-002 §2: server field-level validation failures. */
-    fieldErrors?: Array<{
-        field: string;
-        reason: string;
-        rowNumber?: number;
-    }>;
-};
-export interface SchemaCrudValue {
-    selectedRow: Record<string, unknown> | null;
-    selectRow: (row: Record<string, unknown> | null) => void;
-    tableQuery: (id: string) => ResourceQuery | undefined;
-    setTableQuery: (id: string, query: ResourceQuery) => void;
-    reloadToken: number;
-    reloadList: () => void;
-    /**
-     * Fetches a resource list through the page-level in-flight coalescer:
-     * simultaneous consumers of the same URL share ONE network request (three
-     * statCards + the wallet-ensure probe on one "我的钱包" visit merge into a
-     * single GET /me). Requests are otherwise never memoized — every query,
-     * reset or reload refetches — and reloadList drops the in-flight map so a
-     * reload issued during a slow fetch starts its own fresh request.
-     * `transport` is the caller's own transport (a directly injected fixture or
-     * the auth fetcher); defaults to the provider's registered fetcher.
-     */
-    fetchList: (dataSource: string, query: ResourceQuery, extraQuery?: string, transport?: typeof fetch) => Promise<ResourceList>;
-    /**
-     * Targeted display-data refresh (W25): bumps the per-URL refresh token for
-     * the standard display query of `dataSource` (statCard/chart consume it),
-     * so a consumer can refetch ONE surface without a full-page reload wave.
-     * Only applies to display nodes without route-param bindings (the standard
-     * DISPLAY_LIST_QUERY shape); tables/misc surfaces keep their data until a
-     * manual reload.
-     */
-    refreshList: (dataSource: string) => void;
-    /** Current refresh token for a display dataSource (0 when untouched). */
-    listRefreshToken: (dataSource: string) => number;
-    activeModal: {
-        actionRef: string;
-        row: Record<string, unknown> | null;
-        title: string;
-    } | null;
-    modalRow: Record<string, unknown> | null;
-    openModal: (actionRef: string, row: Record<string, unknown> | null, title: string) => void;
-    closeModal: () => void;
-    pendingConfirm: SchemaCrudConfirm | null;
-    requestConfirm: (confirm: SchemaCrudConfirm) => void;
-    resolveConfirm: (confirmed: boolean) => Promise<void>;
-    feedback: SchemaCrudFeedback | null;
-    registerFetcher: (fetcher: typeof fetch) => void;
-    /** The currently registered transport (globalThis.fetch until injected). */
-    fetcher: typeof fetch;
-    /** Runs a request action end-to-end (gate → construct → fetch → feedback/reload). */
-    runRowAction: (actionRef: string, opts: RunRequestOptions) => Promise<ActionResult>;
-    /** Dispatches a toolbar/row action entry: modal open, confirm, or request. */
-    invokeAction: (item: Record<string, unknown>, row: Record<string, unknown> | null) => void;
-    /** Dispatches a batch toolbar trigger (ADR-0022): gate → confirm → request. */
-    invokeBatchAction: (item: Record<string, unknown>, tableId: string) => void;
-    /** Upload control transport (ADR-0012): resolves action/actionRef → validates → uploads. */
-    uploadFiles: (field: FormControlField, files: UploadableFile[]) => Promise<unknown>;
-    /** Per-table selection state (keys + count; normalized by the table). */
-    selection: (tableId: string) => TableSelection | undefined;
-    setSelection: (tableId: string, keys: unknown[]) => void;
-    clearSelection: (tableId: string) => void;
-    /** Submits a default-mode form against its `submitAction`. */
-    submitForm: (form: RenderFormNode, values: Record<string, unknown>) => Promise<ActionResult>;
-    /** Binds a search-mode form's fields to its target table query. */
-    searchFormSubmit: (form: RenderFormNode, values: Record<string, unknown>) => void;
-    effectivePermission: (targetId: string) => boolean;
-    /**
-     * Current route snapshot (from the render context; App injects
-     * route: {params, query}). Used for ADR-0039 dataSource bindings and
-     * create-modal readOnly seeding instead of reading window.location.
-     */
-    route: {
-        query: Record<string, string>;
-        params: Record<string, string>;
-    };
-}
-export interface RunRequestOptions {
-    row?: Record<string, unknown> | null;
-    formValues?: Record<string, unknown>;
-    requestMapping?: Record<string, unknown>;
-    gateTargetId?: string;
-    confirmed?: boolean;
-}
-/** Page CRUD context consumed by custom components (rendered nodes). */
-export declare const SchemaCrudContext: import("react").Context<SchemaCrudValue | null>;
-/** Reads the page-level Schema CRUD provider (null when rendered bare). */
-export declare function useSchemaCrud(): SchemaCrudValue | null;
-export declare function RenderPage({ document, context, tableRenderer, dataFetcher, onAction, onNavigate, formComponent, }: RendererComponentProps & {
-    dataFetcher?: typeof fetch;
-}): import("react").JSX.Element;