@arcote.tech/arc-process 0.7.28

package/src/model/collapse.ts

@@ -0,0 +1,205 @@
+/**
+ * Zwijanie kontekstów na diagramie procesu.
+ *
+ * Kroki, których `contextPath` zawiera ZWINIĘTY kontekst, zlewają się —
+ * przyległymi seriami w kolejności dokumentu — w jeden pseudo-krok rodzaju
+ * "context" (box ukrywający wewnętrzne eventy/widoki). Relacje do środka
+ * layout re-targetuje na box. `<Arc context="…">` produkuje taki pseudo-krok
+ * wprost (już w modelu), więc zlewa się z przyległymi krokami tego kontekstu.
+ *
+ * Reguła domyślna (tryb `defaultCollapsed=true`, „górny rzut”): zwinięte są
+ * wszystkie konteksty POZA kontekstem domowym dokumentu (`homeContextId`)
+ * i jego przodkami — narracja własnego pakietu pozostaje widoczna, a obce
+ * fragmenty (np. czat AI) zamykają się w boxach. Stan czytelnika
+ * (`collapsedContexts`) nadpisuje domyślne per kontekst.
+ */
+
+import type { ProcessViewState } from "../state/view-state";
+import {
+  CONTEXT_REF_KIND,
+  type ContextInfo,
+  type ProcessModel,
+  type ProcessStep,
+} from "./types";
+
+export interface CollapseOptions {
+  contexts: ContextInfo[];
+  state: ProcessViewState;
+  /** Tryb domyślny: true = górny rzut (obce konteksty zwinięte). */
+  defaultCollapsed: boolean;
+  /** Kontekst domowy dokumentu — jego narracja nie zwija się domyślnie. */
+  homeContextId?: string;
+}
+
+export interface CollapsedGroup {
+  /** occId pseudo-kroku grupy. */
+  occId: string;
+  /** Zwinięty kontekst. */
+  context: ContextInfo;
+  /** occId kroków-członków (w kolejności dokumentu). */
+  memberOccIds: string[];
+  /** Id nodów członków — do re-targetowania relacji na box. */
+  memberNodeIds: Set<string>;
+}
+
+export interface CollapseResult {
+  /** Kroki po zwinięciu: pseudo-kroki grup zastępują serie członków. */
+  steps: ProcessStep[];
+  groups: CollapsedGroup[];
+  /** occId członka → occId grupy. */
+  groupByOcc: Map<string, string>;
+  /** id noda członka → occId grupy (re-target krawędzi). */
+  groupByNodeId: Map<string, string>;
+}
+
+/** Czy kontekst jest zwinięty w danym stanie/trybie. */
+export function isContextCollapsed(
+  ctx: ContextInfo,
+  opts: CollapseOptions,
+): boolean {
+  const explicit = opts.state.collapsedContexts[ctx.id];
+  if (explicit !== undefined) return explicit;
+  if (!opts.defaultCollapsed) return false;
+  // Kontekst bez zadeklarowanej nazwy (id z hasha) nie jest sensownym boxem —
+  // anonimowe konteksty pozostają przezroczyste.
+  if (!ctx.name && !ctx.title) return false;
+  // Kontekst domowy i jego przodkowie pozostają otwarci.
+  if (opts.homeContextId) {
+    const home = opts.contexts.find((c) => c.id === opts.homeContextId);
+    if (home) {
+      const isAncestorOrHome =
+        ctx.path.length <= home.path.length &&
+        ctx.path.every((seg, i) => home.path[i] === seg);
+      if (isAncestorOrHome) return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Najbardziej ZEWNĘTRZNY zwinięty kontekst na ścieżce kroku — gdy zwinięty
+ * jest kontekst nadrzędny, wszystko w środku zlewa się do jego boxa.
+ */
+function collapsedPrefixOf(
+  step: ProcessStep,
+  byId: Map<string, ContextInfo>,
+  opts: CollapseOptions,
+): ContextInfo | undefined {
+  const path = step.node?.contextPath;
+  if (!path) return undefined;
+  for (const id of path) {
+    const ctx = byId.get(id);
+    if (ctx && isContextCollapsed(ctx, opts)) return ctx;
+  }
+  return undefined;
+}
+
+/** Pseudo-krok grupy zwiniętego kontekstu. */
+function groupStep(
+  ctx: ContextInfo,
+  members: ProcessStep[],
+  occId: string,
+): ProcessStep {
+  const first = members[0];
+  return {
+    occId,
+    seq: first.seq,
+    ref: { nodeId: ctx.id, kind: CONTEXT_REF_KIND, key: `context:${ctx.id}` },
+    exists: true,
+    node: {
+      id: `ctx:${ctx.id}`,
+      kind: CONTEXT_REF_KIND,
+      label: ctx.title ?? ctx.name ?? ctx.id,
+      contextPath: ctx.path,
+      meta: { context: ctx, memberCount: members.length },
+    },
+    label: ctx.title ?? ctx.name ?? ctx.id,
+    attachments: {},
+    notes: members.flatMap((m) => m.notes),
+    depth: Math.min(...members.map((m) => m.depth)),
+    lane: first.lane,
+    alt: first.alt,
+    stepTitle: first.stepTitle,
+    laneTitle: first.laneTitle,
+    blockId: first.blockId,
+    phaseId: first.phaseId,
+    entryId: first.entryId,
+    entryTitle: first.entryTitle,
+  };
+}
+
+/**
+ * Zlej przyległe (w kolejności dokumentu) kroki z tym samym zwiniętym
+ * prefiksem kontekstu w pseudo-kroki grup.
+ */
+export function collapseContexts(
+  model: ProcessModel,
+  opts: CollapseOptions,
+): CollapseResult {
+  const byId = new Map(opts.contexts.map((c) => [c.id, c]));
+  const steps: ProcessStep[] = [];
+  const groups: CollapsedGroup[] = [];
+  const groupByOcc = new Map<string, string>();
+  const groupByNodeId = new Map<string, string>();
+
+  let run: { ctx: ContextInfo; members: ProcessStep[] } | null = null;
+  const flush = () => {
+    if (!run) return;
+    const { ctx, members } = run;
+    run = null;
+    if (members.length === 1 && members[0].node?.kind === CONTEXT_REF_KIND) {
+      // Samotny `<Arc context>` — już jest boxem, nie owijamy drugi raz.
+      steps.push(members[0]);
+      return;
+    }
+    const occId = `grp:${ctx.id}:${members[0].seq}`;
+    const g: CollapsedGroup = {
+      occId,
+      context: ctx,
+      memberOccIds: members.map((m) => m.occId),
+      memberNodeIds: new Set(
+        members.filter((m) => m.exists).map((m) => m.node!.id),
+      ),
+    };
+    groups.push(g);
+    for (const m of members) groupByOcc.set(m.occId, occId);
+    for (const id of g.memberNodeIds) groupByNodeId.set(id, occId);
+    steps.push(groupStep(ctx, members, occId));
+  };
+
+  for (const step of model.steps) {
+    // `<Arc context>` liczy się jak krok swojego kontekstu (zlewa się z sąsiadami).
+    const ctx =
+      step.node?.kind === CONTEXT_REF_KIND
+        ? byId.get(step.node.contextPath?.[step.node.contextPath.length - 1] ?? "")
+        : collapsedPrefixOf(step, byId, opts);
+    // Członkiem serii jest krok zwiniętego kontekstu; pseudo-krok `<Arc context>`
+    // zlewa się tylko, gdy jego kontekst też jest zwinięty.
+    const collapsedCtx =
+      ctx && (step.node?.kind === CONTEXT_REF_KIND
+        ? isContextCollapsed(ctx, opts)
+        : true)
+        ? ctx
+        : undefined;
+
+    if (collapsedCtx) {
+      if (run && run.ctx.id === collapsedCtx.id && sameTrack(run.members[0], step)) {
+        run.members.push(step);
+      } else {
+        flush();
+        run = { ctx: collapsedCtx, members: [step] };
+      }
+    } else {
+      flush();
+      steps.push(step);
+    }
+  }
+  flush();
+
+  return { steps, groups, groupByOcc, groupByNodeId };
+}
+
+/** Kroki zlewają się tylko w obrębie tego samego toru (Entry/lane). */
+function sameTrack(a: ProcessStep, b: ProcessStep): boolean {
+  return a.entryId === b.entryId && a.lane === b.lane;
+}

package/src/model/profile.ts

@@ -0,0 +1,95 @@
+/**
+ * Profil procesu — warstwa semantyki nad generycznym grafem.
+ *
+ * Profil definiuje: rodzaje nodów (kolory/ikony/etykiety), relacje wraz z ich
+ * semantyką przepływu i stylem, grupy doczepień (co i po której stronie
+ * rozwija się wokół kroku) oraz rozwiązywanie referencji z propsów `<Arc>`.
+ * Rdzeń modelu i layout są od profilu niezależne.
+ */
+
+import type {
+  Direction,
+  MethodRef,
+  ProcessNode,
+  ResolvedRef,
+} from "./types";
+
+/** Wygląd rodzaju noda. */
+export interface NodeKindSpec {
+  color: string;
+  /** Etykieta rodzaju (fallback: klucz). */
+  label?: string;
+  icon?: string;
+}
+
+/** Semantyka i styl relacji. */
+export interface RelationSpec {
+  color: string;
+  /** Etykieta na krawędzi (fallback: klucz). */
+  label?: string;
+  /**
+   * Semantyka przepływu: "out" — source produkuje target (strzałka
+   * source→target, np. mutates/emits); "in" — source konsumuje target
+   * (strzałka target→source, np. queries/listens/handles).
+   */
+  semantics: "in" | "out";
+  /** Krawędź kreskowana (np. użycia UI). */
+  dashed?: boolean;
+}
+
+/** Grupa doczepień — powiązane nody rozwijane wokół kroku. */
+export interface AttachmentGroupSpec {
+  /** Rodzaje relacji zasilające grupę. */
+  relations: string[];
+  /**
+   * Kierunek zbierania: "out" — nody, na które ten nod wskazuje (from=nod);
+   * "in" — nody wskazujące na ten nod (to=nod).
+   */
+  direction: "in" | "out";
+  /** Domyślna strona doczepienia (MDX może nadpisać per wystąpienie). */
+  defaultSide: Direction;
+  color: string;
+  /** Czy krawędź doczepki wchodzi DO kroku (true) czy z niego wychodzi. */
+  intoNode: boolean;
+  label?: string;
+}
+
+export interface ProcessProfile {
+  id: string;
+  /** Rodzaje nodów tego profilu. */
+  kinds: Record<string, NodeKindSpec>;
+  /** Relacje tego profilu. */
+  relations: Record<string, RelationSpec>;
+  /** Grupy doczepień (badge/rozwinięcia) wokół kroków. */
+  attachmentGroups: Record<string, AttachmentGroupSpec>;
+  /**
+   * Mapuje propsy `<Arc>` na referencję do noda (bez walidacji istnienia —
+   * tę robi model przeciw grafowi). Zwraca null, gdy propsy nie zawierają
+   * rozpoznawanej referencji.
+   */
+  resolveRef(props: Record<string, unknown>): ResolvedRef | null;
+  /**
+   * Opcjonalne nadpisanie forward-zależności per nod/metoda (np. per-metodowe
+   * zależności agregatu Arc). Zwrócone grupy ZASTĘPUJĄ listy wyliczone z
+   * relacji grafu; null — użyj wyliczonych.
+   */
+  forwardDeps?(
+    node: ProcessNode,
+    method?: MethodRef,
+  ): Partial<Record<string, string[]>> | null;
+}
+
+/** Pomocnik identycznościowy — utrzymuje pełne typowanie deklaracji profilu. */
+export function defineProfile(profile: ProcessProfile): ProcessProfile {
+  return profile;
+}
+
+/** Kolor rodzaju noda z profilu (fallback: szary). */
+export function kindColor(profile: ProcessProfile, kind: string): string {
+  return profile.kinds[kind]?.color ?? "#868e96";
+}
+
+/** Kolor relacji z profilu (fallback: szary). */
+export function relationColor(profile: ProcessProfile, kind: string): string {
+  return profile.relations[kind]?.color ?? "#868e96";
+}

package/src/model/types.ts

@@ -0,0 +1,231 @@
+/**
+ * Generyczny model grafu procesów.
+ *
+ * Rdzeń fragmentu process NIE zna rodzajów elementów Arka — operuje na
+ * abstrakcyjnych nodach/relacjach, a semantykę (kolory, ikony, kierunki
+ * domyślne, rozwiązywanie referencji) wnosi PROFIL ({@link ProcessProfile}).
+ * Dzięki temu to samo API opisuje use case'y Arka i czysto biznesowe
+ * procesy (np. BMF), każde z własnym profilem.
+ *
+ * Plik bez zależności (React-free) — testowalny bunem.
+ */
+
+// ---------------------------------------------------------------------------
+// Kierunki — róża kompasu
+// ---------------------------------------------------------------------------
+
+/**
+ * 8 kierunków doczepiania elementów wokół noda. Skosy (NE/SE/SW/NW) wyrażają
+ * kontynuacje procesów, czysta N/S — doczepki typu notatka. Każda doczepiona
+ * karteczka może rekurencyjnie otwierać własne relacje.
+ */
+export type Direction = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
+
+/** Składowa pozioma kierunku: -1 (zachód), 0, 1 (wschód). */
+export function directionDx(d: Direction): -1 | 0 | 1 {
+  if (d === "W" || d === "NW" || d === "SW") return -1;
+  if (d === "E" || d === "NE" || d === "SE") return 1;
+  return 0;
+}
+
+/** Składowa pionowa kierunku: -1 (północ), 0, 1 (południe). */
+export function directionDy(d: Direction): -1 | 0 | 1 {
+  if (d === "N" || d === "NE" || d === "NW") return -1;
+  if (d === "S" || d === "SE" || d === "SW") return 1;
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Graf wejściowy
+// ---------------------------------------------------------------------------
+
+/** Pojedynczy nod grafu — znaczenie `kind` definiuje profil. */
+export interface ProcessNode {
+  id: string;
+  kind: string;
+  label: string;
+  /** Ścieżka kontekstów-przodków (id od korzenia), z core `__contextPath`. */
+  contextPath?: string[];
+  /** Dane profilu (np. metody agregatu, ścieżka HTTP, schema). */
+  meta?: Record<string, unknown>;
+}
+
+/** Relacja między nodami — znaczenie `kind` definiuje profil. */
+export interface ProcessRelation {
+  from: string;
+  to: string;
+  kind: string;
+}
+
+/** Kontekst (przestrzeń) — węzeł drzewa hierarchii kontekstów. */
+export interface ContextInfo {
+  /** Stabilne id kontekstu (core `ArcContext.id`, np. `ctx_chat`). */
+  id: string;
+  /** Ścieżka id od korzenia do tego kontekstu (włącznie). */
+  path: string[];
+  name?: string;
+  title?: string;
+  description?: string;
+  /** Czy kontekst deklaruje komponent-wizytówkę (samego komponentu JSON nie przenosi). */
+  hasCard?: boolean;
+}
+
+/** Kompletny graf wejściowy diagramu. */
+export interface ProcessGraph {
+  nodes: ProcessNode[];
+  relations: ProcessRelation[];
+  contexts?: ContextInfo[];
+}
+
+/** Pusty graf — wszystkie referencje będą czerwonymi chipami TODO. */
+export const EMPTY_GRAPH: ProcessGraph = { nodes: [], relations: [], contexts: [] };
+
+// ---------------------------------------------------------------------------
+// Referencje
+// ---------------------------------------------------------------------------
+
+/** Metoda noda (np. metoda agregatu Arc). */
+export interface MethodRef {
+  name: string;
+  kind: "mutation" | "query";
+}
+
+/** Rozwiązana referencja `<Arc>` — mapowanie propsów na nod grafu. */
+export interface ResolvedRef {
+  /** Id docelowego noda w {@link ProcessGraph}. */
+  nodeId: string;
+  /** Rodzaj (z profilu) lub "context" dla referencji całego kontekstu. */
+  kind: string;
+  method?: MethodRef;
+  /** Kanoniczny klucz do dedup / linkowania chip<->nod. */
+  key: string;
+}
+
+/** Rodzaj referencji kontekstowej (`<Arc context="…">`). */
+export const CONTEXT_REF_KIND = "context";
+
+// ---------------------------------------------------------------------------
+// Struktura MDX (ścieżki strukturalne)
+// ---------------------------------------------------------------------------
+
+/** Segment ścieżki strukturalnej od korzenia MDX do wystąpienia. */
+export interface PathSeg {
+  type: "parallel" | "branch" | "lane" | "step" | "entry";
+  id: string;
+  /** Indeks toru dziecka w parallel/branch. */
+  laneIndex?: number;
+  title?: string;
+  /** Lane'y branchy są alternatywami (XOR). */
+  alt?: boolean;
+  /** Identyfikator fazy (`<Step id="…">`) — cel dla `<Continue to>`. */
+  phaseId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Wystąpienia (rejestrowane przez MDX w kolejności dokumentu)
+// ---------------------------------------------------------------------------
+
+/** Wystąpienie kroku — jedno na każdy `<Arc>` w narracji. */
+export interface StepOccurrence {
+  type: "step";
+  occId: string;
+  ref: ResolvedRef | null;
+  label: string;
+  path?: PathSeg[];
+  /** Override strony doczepienia per grupa relacji (`<Arc sides={{mutates:"SE"}}>`). */
+  sides?: Partial<Record<string, Direction>>;
+  /** Grupy relacji otwarte na starcie (`<Arc expand={["mutates"]}>`). */
+  expand?: string[];
+}
+
+/** Marker `<Continue to="faza"/>` — zamyka bieżące Entry, wskazuje cel. */
+export interface ContinueOccurrence {
+  type: "continue";
+  to: string;
+  path?: PathSeg[];
+}
+
+/** Notatka `<Note side="N">…</Note>` — doczepiana do poprzedzającego kroku. */
+export interface NoteOccurrence {
+  type: "note";
+  occId: string;
+  text: string;
+  side?: Direction;
+  title?: string;
+  path?: PathSeg[];
+}
+
+export type Occurrence = StepOccurrence | ContinueOccurrence | NoteOccurrence;
+
+// ---------------------------------------------------------------------------
+// Model wynikowy
+// ---------------------------------------------------------------------------
+
+/** Notatka doczepiona do kroku. */
+export interface StepNote {
+  occId: string;
+  side: Direction;
+  title?: string;
+  text: string;
+}
+
+/** Krok procesu — jeden na wystąpienie (bez dedup). */
+export interface ProcessStep {
+  occId: string;
+  seq: number;
+  ref: ResolvedRef | null;
+  exists: boolean;
+  node?: ProcessNode;
+  label: string;
+  method?: MethodRef;
+  /** Powiązane nody NIEwidoczne na osi, pogrupowane po grupie relacji. */
+  attachments: Partial<Record<string, string[]>>;
+  /** Override strony per grupa (z MDX). */
+  sides?: Partial<Record<string, Direction>>;
+  /** Grupy otwarte na starcie (z MDX). */
+  expand?: string[];
+  notes: StepNote[];
+  /** Pozycja pozioma (czas / głębokość zależności), 0-based. */
+  depth: number;
+  /** Tor pionowy — 0 = oś główna; ujemne = wejścia nad osią. */
+  lane: number;
+  /** True dla lane'ów branchy (alternatywy / XOR). */
+  alt?: boolean;
+  stepTitle?: string;
+  laneTitle?: string;
+  blockId?: string;
+  /** Id fazy (`<Step id>`), w której leży krok. */
+  phaseId?: string;
+  /** Id/tytuł bloku Entry, gdy krok jest punktem wejścia. */
+  entryId?: string;
+  entryTitle?: string;
+}
+
+/** Element-hydraulika na przepływie między dwoma opowiedzianymi krokami. */
+export interface ProcessConnector {
+  id: string;
+  node: ProcessNode;
+  /** seq dwóch opowiedzianych kroków [upstream → downstream]. */
+  between: [number, number];
+  /** Pozycja 1-based wśród pośredników na ścieżce. */
+  order: number;
+  /** Liczba pośredników na tej ścieżce. */
+  count: number;
+}
+
+/** Krawędź „continues” — z ostatniego kroku Entry do pierwszego kroku fazy. */
+export interface ContinueEdge {
+  fromOcc: string;
+  toOcc: string;
+  phaseId: string;
+}
+
+export interface ProcessModel {
+  steps: ProcessStep[];
+  connectors: ProcessConnector[];
+  /** Widoczne id nodów: istniejące kroki + connectory. */
+  visible: Set<string>;
+  /** id noda -> seq pierwszego istniejącego kroku. */
+  firstSeqByNode: Map<string, number>;
+  continueEdges: ContinueEdge[];
+}