api_binding_ui 1.1.0 → 2.0.0

package/dist/framework/engine.d.ts

@@ -0,0 +1,88 @@
+/** Matching, proposals and status for bindings. Generic: no kinds, products or field names. */
+import type { OperationConsumeBinding, BindId, Catalog, ComponentDescriptor, ComponentInstance, ContextDeclaration, ContextProvider, Glossary, ScreenEntry, ScreenId, ScreenRegistry, SlotBinding, SlotDescriptor, TransformDefinition } from "./contract";
+import { type Field, type OpView } from "./schema";
+export type { Field, OpView, ReqField } from "./schema";
+export { opViews } from "./schema";
+export { humanize, words } from "./names";
+export interface FrameworkData {
+    descriptors: ComponentDescriptor[];
+    registry: ScreenRegistry;
+    catalog: Catalog;
+    transforms?: TransformDefinition[];
+    providers?: ContextProvider[];
+    glossaries?: Glossary[];
+}
+export interface Source {
+    expr: string;
+    label: string;
+    name?: string;
+    type: string;
+    group: "item" | "screen" | "context" | "provider";
+    fields?: Field[];
+    /** Set when the value's shape is not known yet: names the slot that must be connected first. */
+    waitsFor?: string;
+}
+export interface Ranked {
+    view: OpView;
+    score: number;
+    reasons: string[];
+}
+export type SlotState = "bound" | "suggested" | "unbound";
+export type BindingIndex = Record<ScreenId, SlotBinding[]>;
+export declare function createEngine(fw: FrameworkData, manifests: BindingIndex): {
+    fw: FrameworkData;
+    OPV: Map<string, OpView>;
+    OPS: OpView[];
+    DESC: Map<string, ComponentDescriptor>;
+    SCR: Map<string, ScreenEntry>;
+    getB: (s: ScreenId, c: BindId, sl: string) => SlotBinding | undefined;
+    screen: (id: ScreenId) => ScreenEntry;
+    compOf: (s: ScreenId, id: BindId) => ComponentInstance | undefined;
+    descOf: (c: ComponentInstance) => ComponentDescriptor | undefined;
+    bindable: (d: ComponentDescriptor | undefined) => SlotDescriptor[];
+    typeFit: (target: string, source: string) => {
+        ok: boolean;
+        transform?: string;
+    };
+    shapeOf: (s: ScreenId, comp: ComponentInstance, slot: SlotDescriptor) => {
+        many: boolean;
+        fields?: Field[];
+        type?: string;
+        via?: string;
+    };
+    contextShape: (ctx: ContextDeclaration) => {
+        many: boolean;
+        fields: Field[];
+    };
+    scopeFields: (s: ScreenId, comp: ComponentInstance, slot: SlotDescriptor) => Field[] | null;
+    sources: (s: ScreenId, opts?: {
+        item?: Field[];
+    }) => Source[];
+    triggerSources: (s: ScreenId, item?: Field[]) => Source[];
+    bestSource: (targetName: string, targetType: string, srcs: Source[]) => {
+        expr: string;
+        score: number;
+        source: Source;
+    };
+    rankSources: (targetName: string, targetType: string, srcs: Source[], min?: number) => {
+        expr: string;
+        score: number;
+        source: Source;
+    }[];
+    proposeRequest: (v: OpView, srcs: Source[]) => Record<string, string>;
+    proposeMap: (slotFields: Field[], itemFields: Field[]) => Record<string, string>;
+    rank: (s: ScreenId, comp: ComponentInstance, slot: SlotDescriptor) => Ranked[];
+    slotState: (s: ScreenId, c: BindId, sl: string) => SlotState;
+    compState: (s: ScreenId, comp: ComponentInstance) => SlotState | "partial";
+    tally: (screens: ScreenEntry[]) => {
+        bound: number;
+        suggested: number;
+        unbound: number;
+        total: number;
+    };
+    manyContext: (s: ScreenId) => ContextDeclaration | undefined;
+    fieldsAt: (v: OpView, select: string) => Field[];
+    proposeConsume: (s: ScreenId, comp: ComponentInstance, slot: SlotDescriptor, opId: string, strict?: boolean) => OperationConsumeBinding | null;
+    siblingFills: (s: ScreenId, comp: ComponentInstance, slot: SlotDescriptor, opId: string) => OperationConsumeBinding[];
+};
+export type Engine = ReturnType<typeof createEngine>;

package/dist/framework/expr.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Expression evaluator (FRAMEWORK.md §7). One grammar for every source:
+ *
+ *   <bindId>.<slot>[.path]      a produce slot on this screen
+ *   $item[.path]                the current item (scoped slot or forEach)
+ *   $context.<id>[.path]        a value the screen received
+ *   $steps.<stepId>[.path]      an earlier call step's result ({ response })
+ *   $<provider>[.path]          a registered context provider
+ *   <expr>[*].<path>            every item of a list
+ *   <expr> | name(args)         a registered transform
+ *
+ * Nothing outside this grammar is evaluated; unknown heads resolve to undefined.
+ */
+export type Transforms = Record<string, (value: unknown, ...args: unknown[]) => unknown>;
+export interface Scope {
+    /** Current value of a produce slot on the screen. */
+    slot: (bindId: string, slotId: string) => unknown;
+    item?: unknown;
+    context?: Record<string, unknown>;
+    providers?: Record<string, unknown>;
+    steps?: Record<string, unknown>;
+    transforms?: Transforms;
+}
+interface Parsed {
+    head: string[];
+    path: string[];
+    pipes: Array<{
+        name: string;
+        args: unknown[];
+    }>;
+}
+export declare function parse(expr: string): Parsed;
+export declare function evaluate(expr: string, scope: Scope): unknown;
+export {};

package/dist/framework/loadCatalog.d.ts

@@ -0,0 +1,6 @@
+import type { Catalog } from "./contract";
+export declare class CatalogLoadError extends Error {
+    readonly url: string;
+    constructor(message: string, url: string);
+}
+export declare function loadCatalog(url: string, init?: RequestInit): Promise<Catalog>;

package/dist/framework/names.d.ts

@@ -0,0 +1,7 @@
+/** Identifiers to words, for matching and labels. */
+import type { Glossary } from "./contract";
+export declare const sing: (w: string) => string;
+export declare function synonymIndex(glossaries: Glossary[]): Record<string, string[]>;
+export declare function words(text: string): string[];
+/** Turns an identifier into words people read: "noteTypeId" → "Note type id". */
+export declare function humanize(id: string): string;

package/dist/framework/openapi.d.ts

@@ -0,0 +1,7 @@
+/** OpenAPI 3.0–3.2 → Catalog. */
+import type { Catalog } from "./contract";
+/** FNV-1a, enough to detect catalog drift. */
+export declare function hashString(s: string): string;
+export declare function catalogFromOpenApi(input: unknown, source?: {
+    url?: string;
+}): Catalog;

package/dist/framework/runner.d.ts

@@ -0,0 +1,33 @@
+/** Builds requests, reads responses and runs trigger steps. */
+import type { CatalogOperation, OperationConsumeBinding, Step } from "./contract";
+import { type Scope } from "./expr";
+export interface HttpRequest {
+    method: string;
+    /** Path with parameters filled in, e.g. "/cls/v1/notes/42". */
+    path: string;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+/** Sends a request. Supplied by the host (base URL, auth, errors). */
+export type Fetcher = (request: HttpRequest, operation: CatalogOperation) => Promise<unknown>;
+export declare class BindingError extends Error {
+    readonly detail?: unknown | undefined;
+    constructor(message: string, detail?: unknown | undefined);
+}
+export declare function buildRequest(op: CatalogOperation, request: Record<string, string>, scope: Scope): HttpRequest;
+/** Identical requests share a key, and so one fetch. */
+export declare const requestKey: (r: HttpRequest) => string;
+/** "$", "$.a.b" or "$.a.items[*]" applied to a response. */
+export declare function select(response: unknown, selector: string): unknown;
+/** Applies a consume binding's `map` to each item; without a map the items pass through untouched. */
+export declare function mapItems(data: unknown, binding: OperationConsumeBinding, scope: Scope): unknown;
+export declare function runConsume(binding: OperationConsumeBinding, op: CatalogOperation, scope: Scope, fetcher: Fetcher): Promise<unknown>;
+export interface StepOutcome {
+    step: string;
+    ok: boolean;
+    response?: unknown;
+    error?: unknown;
+}
+/** Runs call steps in order. `forEach` runs a call once per item; `onError: "stop"` ends the run at the first failure. */
+export declare function runSteps(steps: Step[], operations: Map<string, CatalogOperation>, scope: Scope, fetcher: Fetcher): Promise<StepOutcome[]>;

package/dist/framework/schema.d.ts

@@ -0,0 +1,22 @@
+/** JSON Schema helpers and per-operation views. */
+import type { Catalog, CatalogOperation, JsonSchema } from "./contract";
+export type Field = [name: string, type: string];
+export type ReqField = [pointer: string, type: string, required: boolean];
+export interface OpView {
+    op: CatalogOperation;
+    req: ReqField[];
+    lists: Array<{
+        select: string;
+        fields: Field[];
+    }>;
+    one: Field[] | null;
+    scalars: Field[];
+}
+type S = Record<string, any>;
+export declare const obj: (s: JsonSchema | undefined) => S;
+export declare function flat(s: JsonSchema | undefined): S;
+export declare function typeName(s: JsonSchema | undefined): string;
+export declare const isObject: (s: JsonSchema | undefined) => boolean;
+export declare const propsOf: (s: JsonSchema | undefined) => Field[];
+export declare function opViews(catalog: Catalog): Map<string, OpView>;
+export {};

package/dist/framework/store.d.ts

@@ -0,0 +1,17 @@
+/** Manifest persistence and edit helpers. */
+import type { BindingManifest, PersistenceAdapter, ScreenId, SlotBinding } from "./contract";
+import type { BindingIndex, FrameworkData } from "./engine";
+export declare function localStorageAdapter(prefix?: string): PersistenceAdapter;
+export declare function memoryAdapter(seed?: BindingManifest[]): PersistenceAdapter;
+export declare function toManifest(fw: FrameworkData, screen: ScreenId, bindings: SlotBinding[]): BindingManifest;
+/** Unsaved screens with an edit counter; a screen is cleared only by a save that covers its latest edit. */
+export type Pending = Map<ScreenId, number>;
+export declare function markDirty(pending: Pending, screen: ScreenId): void;
+/** Saves every pending screen from `idx`. Returns the screens whose save failed (they stay pending). */
+export declare function savePending(adapter: PersistenceAdapter, fw: FrameworkData, idx: BindingIndex, pending: Pending): Promise<ScreenId[]>;
+export declare function loadAll(adapter: PersistenceAdapter, screens: ScreenId[]): Promise<BindingIndex>;
+/** Pure edit helpers: return a new index. */
+export declare function putBinding(idx: BindingIndex, screen: ScreenId, b: SlotBinding): BindingIndex;
+export declare function dropBinding(idx: BindingIndex, screen: ScreenId, component: string, slot: string): BindingIndex;
+/** Parses imported manifests (one or a list). Throws on the first invalid entry. */
+export declare function parseManifests(text: string): BindingManifest[];

package/dist/framework/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ScreenRegistry, ValidationIssue } from "./contract";
+import type { Engine, FrameworkData } from "./engine";
+export declare function validateRegistry(fw: FrameworkData): {
+    registry: ScreenRegistry;
+    issues: ValidationIssue[];
+};
+export declare function validateBindings(engine: Engine): ValidationIssue[];