@workbench-kit/shell-react 0.0.2-prototype.0.2.10

package/src/field-remap/io-class-browse.tsx

@@ -0,0 +1,145 @@
+import { useMemo, type JSX } from 'react';
+import {
+  projectSourceFields,
+  projectTargetSlots,
+  type SourceField,
+  type TargetSlot,
+} from '@workbench-kit/field-remap';
+
+export type FieldRemapIoChrome = 'browse' | 'edit' | 'none';
+
+export interface FieldRemapIoClassBrowseProps {
+  readonly sources: readonly SourceField[];
+  readonly targets: readonly TargetSlot[];
+  /**
+   * When `false` (default), omit `hidden` ports/fields.
+   * When `true`, keep them and show a Hidden badge.
+   */
+  readonly includeHidden?: boolean;
+  readonly sourcesTitle?: string;
+  readonly targetsTitle?: string;
+  readonly className?: string;
+  readonly emptyLabel?: string;
+}
+
+export function resolveFieldRemapIoChrome(
+  ioChrome: FieldRemapIoChrome | undefined,
+  editableShapes: boolean,
+): FieldRemapIoChrome {
+  if (ioChrome) {
+    return ioChrome;
+  }
+  return editableShapes ? 'edit' : 'none';
+}
+
+function formatClassRef(classRef: { readonly id: string; readonly version: number }): string {
+  return `${classRef.id}@${classRef.version}`;
+}
+
+function FieldTree({
+  nodes,
+  emptyLabel,
+}: {
+  readonly nodes: readonly (SourceField | TargetSlot)[];
+  readonly emptyLabel: string;
+}): JSX.Element {
+  if (nodes.length === 0) {
+    return <p className="workbench-field-remap-io-browse__empty">{emptyLabel}</p>;
+  }
+  return (
+    <ul className="workbench-field-remap-io-browse__fields">
+      {nodes.map((node) => (
+        <li key={node.id}>
+          <div className="workbench-field-remap-io-browse__row">
+            <code className="workbench-field-remap-io-browse__path">{node.path ?? node.label}</code>
+            <span className="workbench-field-remap-io-browse__meta">
+              {node.dataType ? <span>{node.dataType}</span> : null}
+              {node.classRef ? (
+                <span className="workbench-field-remap-io-browse__badge" title="classRef">
+                  {formatClassRef(node.classRef)}
+                </span>
+              ) : null}
+              {node.hidden === true ? (
+                <span className="workbench-field-remap-io-browse__badge" title="hidden">
+                  Hidden
+                </span>
+              ) : null}
+            </span>
+          </div>
+          {node.children?.length ? (
+            <FieldTree emptyLabel={emptyLabel} nodes={node.children} />
+          ) : null}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+function PortSection({
+  title,
+  nodes,
+  emptyLabel,
+}: {
+  readonly title: string;
+  readonly nodes: readonly (SourceField | TargetSlot)[];
+  readonly emptyLabel: string;
+}): JSX.Element {
+  return (
+    <section aria-label={title} className="workbench-field-remap-io-browse__section">
+      <h3 className="workbench-field-remap-io-browse__section-title">{title}</h3>
+      {nodes.length === 0 ? (
+        <p className="workbench-field-remap-io-browse__empty">{emptyLabel}</p>
+      ) : (
+        nodes.map((node) => (
+          <div className="workbench-field-remap-io-browse__port" key={node.id}>
+            <p className="workbench-field-remap-io-browse__port-title">
+              <span className="workbench-field-remap-io-browse__port-id">{node.label}</span>
+              <span className="workbench-field-remap-io-browse__port-meta">
+                {node.classRef ? formatClassRef(node.classRef) : node.id}
+                {node.hidden === true ? ' · Hidden' : ''}
+              </span>
+            </p>
+            <FieldTree
+              emptyLabel={emptyLabel}
+              nodes={node.children?.length ? node.children : [node]}
+            />
+          </div>
+        ))
+      )}
+    </section>
+  );
+}
+
+/**
+ * Read-only I/O chrome: browse source/target trees with optional `classRef` and `hidden`.
+ * Prefer this over {@link FieldRemapShapeIoEditor} when hosts author topology on Flow and
+ * only need to inspect declared shapes.
+ */
+export function FieldRemapIoClassBrowse({
+  sources,
+  targets,
+  includeHidden = false,
+  sourcesTitle = 'Inputs',
+  targetsTitle = 'Outputs',
+  className,
+  emptyLabel = 'No fields',
+}: FieldRemapIoClassBrowseProps): JSX.Element {
+  const projectedSources = useMemo(
+    () => projectSourceFields(sources, { includeHidden }),
+    [includeHidden, sources],
+  );
+  const projectedTargets = useMemo(
+    () => projectTargetSlots(targets, { includeHidden }),
+    [includeHidden, targets],
+  );
+
+  return (
+    <div
+      className={['workbench-field-remap-io-browse', className].filter(Boolean).join(' ')}
+      data-testid="field-remap-io-browse"
+    >
+      <PortSection emptyLabel={emptyLabel} nodes={projectedSources} title={sourcesTitle} />
+      <PortSection emptyLabel={emptyLabel} nodes={projectedTargets} title={targetsTitle} />
+    </div>
+  );
+}

package/src/field-remap/jsonata-transform.ts

@@ -0,0 +1,166 @@
+import jsonata from 'jsonata';
+import type { ValueTransformDefinition } from '@workbench-kit/field-remap';
+
+/** Host-registered JSONata expression transform (Stedi-style advanced mapping). */
+export const JSONATA_TRANSFORM_ID = 'expr:jsonata' as const;
+
+/** Default wall-clock budget for a single expression evaluation. */
+export const DEFAULT_JSONATA_TIMEOUT_MS = 2_000;
+
+/** Default maximum expression source length (characters). */
+export const DEFAULT_JSONATA_MAX_EXPRESSION_LENGTH = 4_096;
+
+export type JsonataTransformErrorPolicy = 'passthrough' | 'throw';
+
+export interface CreateJsonataValueTransformOptions {
+  /** Wall-clock timeout for `evaluate` (default {@link DEFAULT_JSONATA_TIMEOUT_MS}). */
+  readonly timeoutMs?: number;
+  /**
+   * Reject expressions longer than this many characters
+   * (default {@link DEFAULT_JSONATA_MAX_EXPRESSION_LENGTH}).
+   */
+  readonly maxExpressionLength?: number;
+  /**
+   * - `throw` (default): surface timeout / compile / evaluate failures to the host
+   * - `passthrough`: return the original value (legacy silent identity)
+   */
+  readonly onError?: JsonataTransformErrorPolicy;
+}
+
+export function createJsonataValueTransform(
+  options: CreateJsonataValueTransformOptions = {},
+): ValueTransformDefinition {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_JSONATA_TIMEOUT_MS;
+  const maxExpressionLength = options.maxExpressionLength ?? DEFAULT_JSONATA_MAX_EXPRESSION_LENGTH;
+  const onError = options.onError ?? 'throw';
+
+  return {
+    id: JSONATA_TRANSFORM_ID,
+    label: 'JSONata expression',
+    description:
+      'Evaluate a JSONata expression against the source value (host-registered; bounded).',
+    category: 'expression',
+    inputTypes: ['string', 'number', 'boolean', 'object', 'array', 'unknown'],
+    outputType: 'unknown',
+    optionFields: [
+      {
+        key: 'expression',
+        label: 'Expression',
+        kind: 'string',
+      },
+    ],
+    apply: async (value, context) => {
+      const expression =
+        typeof context.options?.expression === 'string' ? context.options.expression.trim() : '';
+      if (!expression) {
+        return value;
+      }
+
+      if (expression.length > maxExpressionLength) {
+        return handleJsonataError(
+          new Error(
+            `JSONata expression exceeds max length (${expression.length} > ${maxExpressionLength}).`,
+          ),
+          value,
+          onError,
+        );
+      }
+
+      try {
+        const compiled = jsonata(expression);
+        // jsonata@2.x evaluate returns a Promise (1.x was synchronous).
+        return await raceJsonataEvaluation(compiled.evaluate(value), {
+          timeoutMs,
+          signal: context.signal,
+        });
+      } catch (error) {
+        return handleJsonataError(error, value, onError);
+      }
+    },
+  };
+}
+
+/** Default bounded transform (`onError: 'throw'`, 2s timeout, 4k expression cap). */
+export const jsonataValueTransform: ValueTransformDefinition = createJsonataValueTransform();
+
+export class JsonataTransformTimeoutError extends Error {
+  override readonly name = 'JsonataTransformTimeoutError';
+
+  constructor(timeoutMs: number) {
+    super(`JSONata evaluation timed out after ${timeoutMs}ms.`);
+  }
+}
+
+/** Race a JSONata evaluation against timeout / AbortSignal (exported for unit tests). */
+export async function raceJsonataEvaluation<T>(
+  evaluation: PromiseLike<T>,
+  bounds: { readonly timeoutMs: number; readonly signal?: AbortSignal },
+): Promise<T> {
+  const { timeoutMs, signal } = bounds;
+  if (signal?.aborted) {
+    throw signal.reason instanceof Error
+      ? signal.reason
+      : Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' });
+  }
+
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return evaluation;
+  }
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new JsonataTransformTimeoutError(timeoutMs));
+    }, timeoutMs);
+
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(
+        signal?.reason instanceof Error
+          ? signal.reason
+          : Object.assign(new Error('The operation was aborted.'), { name: 'AbortError' }),
+      );
+    };
+
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    };
+
+    signal?.addEventListener('abort', onAbort, { once: true });
+
+    Promise.resolve(evaluation).then(
+      (result) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(result);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      },
+    );
+  });
+}
+
+function handleJsonataError(
+  error: unknown,
+  value: unknown,
+  onError: JsonataTransformErrorPolicy,
+): unknown {
+  if (onError === 'passthrough') {
+    return value;
+  }
+  if (error instanceof Error) {
+    throw error;
+  }
+  throw new Error(String(error));
+}