@nocobase/app-template-default 1.0.0-beta.69 → 1.0.0-beta.71

package/client/components/flow-layout.ts

@@ -0,0 +1,250 @@
+import type {
+  ELK,
+  ELKConstructorArguments,
+  ElkNode,
+} from 'elkjs/lib/elk-api.js';
+
+export interface FlowDiagramNode {
+  readonly id: string;
+  readonly label: string;
+  readonly kind?: 'initial' | 'final' | 'state';
+  /** True only when the lifecycle definition binds configurable parameters to this state. */
+  readonly configurable?: boolean;
+  /** Fixed canvas dimensions; customize these when supplying richer node content. */
+  readonly width?: number;
+  readonly height?: number;
+  /** A visual annotation, not an inspectable business state or transition. */
+  readonly decorative?: boolean;
+  readonly visited?: boolean;
+  readonly highlighted?: boolean;
+  readonly className?: string;
+}
+
+export interface FlowDiagramEdge {
+  readonly id: string;
+  readonly source: string;
+  readonly target: string;
+  readonly label?: string;
+  /** True when the transition binds editable business parameters. */
+  readonly configurable?: boolean;
+  /** A visual annotation, not an inspectable business state or transition. */
+  readonly decorative?: boolean;
+  readonly visited?: boolean;
+  readonly highlighted?: boolean;
+  readonly dashed?: boolean;
+}
+
+export type FlowDiagramDirection = 'RIGHT' | 'DOWN';
+
+export interface FlowDiagramGraph {
+  readonly nodes: readonly FlowDiagramNode[];
+  readonly edges: readonly FlowDiagramEdge[];
+}
+
+export interface FlowDiagramPoint {
+  readonly x: number;
+  readonly y: number;
+}
+
+export interface FlowDiagramLayout {
+  readonly width: number;
+  readonly height: number;
+  readonly nodes: readonly (FlowDiagramNode &
+    FlowDiagramPoint & { width: number; height: number })[];
+  readonly edges: readonly (FlowDiagramEdge & {
+    points: readonly FlowDiagramPoint[];
+    labelPosition?: FlowDiagramPoint;
+  })[];
+}
+
+type ElkConstructor = new (args?: ELKConstructorArguments) => ELK;
+let elkPromise: Promise<ELK> | undefined;
+
+function getElk(): Promise<ELK> {
+  return (elkPromise ??= import('elkjs/lib/elk.bundled.js').then((module) => {
+    // elkjs is CommonJS: NodeNext and Vite expose its constructor differently.
+    const imported = module.default as
+      ElkConstructor | { default: ElkConstructor };
+    return new (typeof imported === 'function' ? imported : imported.default)();
+  }));
+}
+
+/** Layout and route the same graph, including cycles, parallel edges and self-transitions. */
+export async function layoutFlowDiagram(
+  graph: FlowDiagramGraph,
+  direction: FlowDiagramDirection = 'RIGHT',
+): Promise<FlowDiagramLayout> {
+  const ids = new Set<string>();
+  for (const node of graph.nodes) {
+    if (ids.has(node.id)) throw new Error(`Duplicate node: ${node.id}`);
+    ids.add(node.id);
+    if (
+      !Number.isFinite(node.width ?? 232) ||
+      (node.width ?? 232) <= 0 ||
+      !Number.isFinite(node.height ?? 104) ||
+      (node.height ?? 104) <= 0
+    )
+      throw new Error(`Invalid dimensions: ${node.id}`);
+  }
+  const edgeIds = new Set<string>();
+  for (const edge of graph.edges) {
+    if (edgeIds.has(edge.id)) throw new Error(`Duplicate edge: ${edge.id}`);
+    edgeIds.add(edge.id);
+    if (!ids.has(edge.source) || !ids.has(edge.target))
+      throw new Error(`Unknown endpoint: ${edge.id}`);
+  }
+  // Internal ids occupy their own namespace, regardless of caller-provided ids.
+  const nodeIds = new Map(
+    graph.nodes.map((node, index) => [node.id, `n${index}`]),
+  );
+  const elk = await getElk();
+  const result = await elk.layout<ElkNode>({
+    id: 'root',
+    layoutOptions: {
+      'elk.algorithm': 'layered',
+      'elk.direction': direction,
+      'elk.edgeRouting': 'ORTHOGONAL',
+      'elk.spacing.nodeNode': '40',
+      'elk.layered.spacing.nodeNodeBetweenLayers': '72',
+      'elk.layered.nodePlacement.strategy': 'NETWORK_SIMPLEX',
+      // Declared state order keeps retry edges from moving later states before the start.
+      'elk.layered.cycleBreaking.strategy': 'MODEL_ORDER',
+      'elk.layered.crossingMinimization.strategy': 'LAYER_SWEEP',
+      'elk.layered.thoroughness': '32',
+      'elk.spacing.edgeEdge': '20',
+      'elk.layered.spacing.edgeEdgeBetweenLayers': '20',
+      'elk.layered.spacing.edgeNodeBetweenLayers': '24',
+    },
+    children: graph.nodes.map((node) => {
+      const id = nodeIds.get(node.id)!;
+      const width = node.width ?? 232;
+      const height = node.height ?? 104;
+      const connections = graph.edges.map((edge, index) => ({ edge, index }));
+      const incoming = connections.filter(
+        ({ edge }) => edge.target === node.id,
+      );
+      const outgoing = connections.filter(
+        ({ edge }) => edge.source === node.id,
+      );
+      return {
+        id,
+        width,
+        height,
+        // Let crossing minimization order ports instead of freezing declaration order.
+        layoutOptions: { 'elk.portConstraints': 'FIXED_SIDE' },
+        ports: [
+          ...incoming.map(({ index }) => ({
+            id: `e${index}:in`,
+            width: 0,
+            height: 0,
+            layoutOptions: {
+              'elk.port.side': direction === 'RIGHT' ? 'WEST' : 'NORTH',
+            },
+          })),
+          ...outgoing.map(({ index }) => ({
+            id: `e${index}:out`,
+            width: 0,
+            height: 0,
+            layoutOptions: {
+              'elk.port.side': direction === 'RIGHT' ? 'EAST' : 'SOUTH',
+            },
+          })),
+        ],
+      };
+    }),
+    edges: graph.edges.map((edge, index) => ({
+      id: `e${index}`,
+      sources: [`e${index}:out`],
+      targets: [`e${index}:in`],
+      labels: edge.label
+        ? [
+            {
+              text: edge.label,
+              // Reserve space on the routed edge so labels remain attached to it.
+              layoutOptions: {
+                'elk.edgeLabels.placement': 'CENTER',
+                'elk.edgeLabels.inline': 'true',
+              },
+              width: Math.min(
+                320,
+                [...edge.label].reduce(
+                  (total, char) => total + (char.charCodeAt(0) > 255 ? 14 : 7),
+                  16,
+                ),
+              ),
+              height: 24,
+            },
+          ]
+        : [],
+    })),
+  });
+  return {
+    width: result.width ?? 0,
+    height: result.height ?? 0,
+    nodes: graph.nodes.map((node, index) => {
+      const placed = result.children![index];
+      return {
+        ...node,
+        x: placed.x ?? 0,
+        y: placed.y ?? 0,
+        width: placed.width ?? node.width ?? 232,
+        height: placed.height ?? node.height ?? 104,
+      };
+    }),
+    edges: graph.edges.map((edge, index) => {
+      const routed = result.edges![index];
+      const label = routed.labels?.[0];
+      const points = (routed.sections ?? []).flatMap((section) => [
+        section.startPoint,
+        ...(section.bendPoints ?? []),
+        section.endPoint,
+      ]);
+      // ELK may round a self-loop's port but leave its neighboring bend fractional.
+      // Align those bends with the port so even short endpoint segments stay orthogonal.
+      if (points.length >= 4) {
+        const axis = direction === 'RIGHT' ? 'y' : 'x';
+        for (const [endpoint, bend] of [
+          [0, 1],
+          [points.length - 1, points.length - 2],
+        ]) {
+          if (Math.abs(points[endpoint][axis] - points[bend][axis]) < 1) {
+            points[bend] = { ...points[bend], [axis]: points[endpoint][axis] };
+          }
+        }
+      }
+      let labelPosition: FlowDiagramPoint | undefined;
+      if (label) {
+        const center = {
+          x: (label.x ?? 0) + (label.width ?? 0) / 2,
+          y: (label.y ?? 0) + (label.height ?? 0) / 2,
+        };
+        // ELK reserves inline label space, but can offset its center slightly
+        // in horizontal layouts. Anchor it precisely to that reserved segment.
+        let distance = Infinity;
+        for (let index = 1; index < points.length; index++) {
+          const start = points[index - 1];
+          const end = points[index];
+          const candidate = {
+            x: Math.max(
+              Math.min(start.x, end.x),
+              Math.min(center.x, Math.max(start.x, end.x)),
+            ),
+            y: Math.max(
+              Math.min(start.y, end.y),
+              Math.min(center.y, Math.max(start.y, end.y)),
+            ),
+          };
+          const nextDistance = Math.hypot(
+            candidate.x - center.x,
+            candidate.y - center.y,
+          );
+          if (nextDistance < distance) {
+            labelPosition = candidate;
+            distance = nextDistance;
+          }
+        }
+      }
+      return { ...edge, points, labelPosition };
+    }),
+  };
+}

package/client/components/lifecycle-diagram-model.ts

@@ -0,0 +1,217 @@
+import type { LifecycleDescription } from '@nocobase/lifecycle';
+import type { FlowDiagramGraph } from '#components/flow-layout';
+
+export interface LifecycleDiagramHistoryEntry {
+  readonly transition: string;
+  readonly from: string | null;
+  readonly to: string;
+}
+
+export interface LifecycleDiagramOptions {
+  /** Localized label for separate end markers; omitted to hide them. */
+  readonly endLabel?: string;
+  readonly history?: readonly LifecycleDiagramHistoryEntry[];
+  readonly visitedStates?: readonly string[];
+  readonly currentState?: string;
+  /** Names from view.available filtered by the caller to transitions actually available. */
+  readonly availableTransitions?: readonly string[];
+  readonly stateLabel?: (
+    state: LifecycleDescription['stateInfo'][number],
+  ) => string;
+  readonly transitionLabel?: (
+    transition: LifecycleDescription['transitions'][number],
+  ) => string;
+}
+
+/** Builds edges for every declared source/destination pair; it never infers a record's history. */
+export function lifecycleDiagramGraph(
+  description: LifecycleDescription,
+  options: LifecycleDiagramOptions = {},
+): FlowDiagramGraph {
+  const history = options.history ?? [];
+  const visitedStates = new Set([
+    ...(options.visitedStates ?? []),
+    ...history.flatMap((entry) =>
+      entry.from === null ? [entry.to] : [entry.from, entry.to],
+    ),
+  ]);
+  const visitedEdges = new Set(
+    history
+      .filter((entry) => entry.from !== null)
+      .map((entry) => JSON.stringify([entry.transition, entry.from, entry.to])),
+  );
+  const graph: FlowDiagramGraph = {
+    nodes: description.stateInfo.map((state) => ({
+      id: state.name,
+      width: 232,
+      height: 104,
+      label: options.stateLabel?.(state) ?? state.title,
+      configurable: (description.parameterConfiguration?.groups ?? []).some(
+        (group) =>
+          Object.values(group.fields).some((field) =>
+            field.bindings?.some((binding) => binding.state === state.name),
+          ),
+      ),
+      visited: visitedStates.has(state.name),
+      highlighted: state.name === options.currentState,
+      kind: state.final
+        ? 'final'
+        : description.initialStates.includes(state.name)
+          ? 'initial'
+          : 'state',
+    })),
+    edges: description.transitions.flatMap((transition) =>
+      transition.from.flatMap((source) =>
+        transition.to.map((target) => ({
+          id: JSON.stringify([transition.name, source, target]),
+          source,
+          target,
+          label: options.transitionLabel?.(transition) ?? transition.title,
+          configurable: (description.parameterConfiguration?.groups ?? []).some(
+            (group) =>
+              Object.values(group.fields).some((field) =>
+                field.bindings?.some(
+                  (binding) => binding.transition === transition.name,
+                ),
+              ),
+          ),
+          visited: visitedEdges.has(
+            JSON.stringify([transition.name, source, target]),
+          ),
+          highlighted:
+            source === options.currentState &&
+            (options.availableTransitions?.includes(transition.name) ?? false),
+        })),
+      ),
+    ),
+  };
+  if (!options.endLabel) return graph;
+  const ids = new Set(graph.nodes.map((node) => node.id));
+  const endings = description.stateInfo
+    .filter((state) => state.final)
+    .map((state) => {
+      let id = JSON.stringify(['$end', state.name]);
+      while (ids.has(id)) id += ':';
+      ids.add(id);
+      return { state, id };
+    });
+  return {
+    nodes: [
+      ...graph.nodes,
+      ...endings.map(({ state, id }) => ({
+        id,
+        label: `◎ ${options.endLabel}`,
+        // Compact fixed canvas dimensions for a terminal annotation.
+        width: 88,
+        height: 32,
+        decorative: true,
+        visited:
+          state.name === options.currentState || visitedStates.has(state.name),
+        className:
+          'rounded-full border-0 bg-transparent text-muted-foreground shadow-none',
+      })),
+    ],
+    edges: [
+      ...graph.edges,
+      ...endings.map(({ state, id }) => ({
+        id: JSON.stringify(['$end', state.name]),
+        source: state.name,
+        target: id,
+        decorative: true,
+        visited:
+          state.name === options.currentState || visitedStates.has(state.name),
+      })),
+    ],
+  };
+}
+
+export type LifecycleConfigurationTarget =
+  | { readonly kind: 'state'; readonly name: string }
+  | { readonly kind: 'transition'; readonly name: string };
+export type LifecycleParameterGroup = NonNullable<
+  LifecycleDescription['parameterConfiguration']
+>['groups'][number];
+export type LifecycleParameterField = LifecycleParameterGroup['fields'][string];
+export interface LifecycleConfigurationSelection {
+  readonly target: LifecycleConfigurationTarget;
+  /** Only bound, authorized fields. Editors must merge into a complete group before saving. */
+  readonly groups: readonly LifecycleParameterGroup[];
+}
+export interface LifecycleDiagramConfiguration {
+  readonly label: (target: LifecycleConfigurationTarget) => string;
+  /** UI affordance only: the server must independently authorize reads and writes. */
+  readonly canConfigure: (
+    group: LifecycleParameterGroup,
+    field: string,
+    definition: LifecycleParameterField,
+  ) => boolean;
+  readonly onConfigure: (selection: LifecycleConfigurationSelection) => void;
+}
+
+/** Selects declared bindings only; never guesses parameters from node names or labels. */
+export function lifecycleConfigurationSelection(
+  description: LifecycleDescription,
+  target: LifecycleConfigurationTarget,
+  canConfigure: LifecycleDiagramConfiguration['canConfigure'],
+): LifecycleConfigurationSelection | undefined {
+  const exists =
+    target.kind === 'state'
+      ? description.stateInfo.some((state) => state.name === target.name)
+      : description.transitions.some(
+          (transition) => transition.name === target.name,
+        );
+  if (!exists) return undefined;
+  const groups = (description.parameterConfiguration?.groups ?? []).flatMap(
+    (group) => {
+      const fields = Object.fromEntries(
+        Object.entries(group.fields).filter(
+          ([key, field]) =>
+            field.bindings?.some(
+              (binding) => binding[target.kind] === target.name,
+            ) && canConfigure(group, key, field),
+        ),
+      );
+      return Object.keys(fields).length ? [{ ...group, fields }] : [];
+    },
+  );
+  return groups.length ? { target, groups } : undefined;
+}
+
+/** Surface an outgoing transition's declared policy on its owning node as well. */
+export function lifecycleNodeConfigurationSelections(
+  description: LifecycleDescription,
+  state: string,
+  canConfigure: LifecycleDiagramConfiguration['canConfigure'],
+): readonly LifecycleConfigurationSelection[] {
+  if (!description.stateInfo.some((item) => item.name === state)) return [];
+  const own = lifecycleConfigurationSelection(
+    description,
+    { kind: 'state', name: state },
+    canConfigure,
+  );
+  const covered = new Set(
+    own?.groups.flatMap((group) =>
+      Object.keys(group.fields).map((field) =>
+        JSON.stringify([group.key, field]),
+      ),
+    ),
+  );
+  const outgoing = description.transitions.flatMap((transition) => {
+    if (!transition.from.includes(state)) return [];
+    const selection = lifecycleConfigurationSelection(
+      description,
+      { kind: 'transition', name: transition.name },
+      canConfigure,
+    );
+    // A dual state/transition binding already has an entry on this node. Keep
+    // distinct transitions distinct, even when they happen to share fields.
+    return selection?.groups.some((group) =>
+      Object.keys(group.fields).some(
+        (field) => !covered.has(JSON.stringify([group.key, field])),
+      ),
+    )
+      ? [selection]
+      : [];
+  });
+  return own ? [own, ...outgoing] : outgoing;
+}