@arcote.tech/arc-process 0.7.28

package/src/profiles/arc.ts

@@ -0,0 +1,332 @@
+/**
+ * Profil elementów Arka dla fragmentu process.
+ *
+ * Definiuje rodzaje elementów (aggregate/command/event/…) z paletą
+ * Event Storming, relacje domenowe z semantyką przepływu, grupy doczepień
+ * (dawne REL_SIDE/INPUT_KINDS jako DANE profilu) oraz rozwiązywanie
+ * referencji `<Arc>` (przeniesione z arc-map/src/refs.ts).
+ *
+ * `ArcGraphInput` to strukturalny podzbiór MapJson z arc-map — arc-map
+ * podaje swój obiekt bez konwersji.
+ */
+
+import { defineProfile } from "../model/profile";
+import type {
+  ContextInfo,
+  MethodRef,
+  ProcessGraph,
+  ProcessNode,
+  ResolvedRef,
+} from "../model/types";
+
+// ---------------------------------------------------------------------------
+// Paleta (Event Storming / Event Modeling)
+// ---------------------------------------------------------------------------
+
+export const ARC_ELEMENT_COLOR: Record<string, string> = {
+  command: "#1c7ed6", // blue — command
+  event: "#f76707", // orange — domain event
+  aggregate: "#f59f00", // gold/amber — aggregate
+  view: "#2f9e44", // green — read model / view
+  "static-view": "#0ca678", // teal — static read model
+  listener: "#7048e8", // grape/lilac — policy / reaction
+  route: "#e64980", // pink — external boundary
+  page: "#4263eb", // indigo — UI / page
+  context: "#7c3aed", // violet — zwinięty kontekst
+  note: "#eab308", // yellow — notatka
+  unknown: "#868e96", // slate
+};
+
+export const ARC_EDGE_COLOR: Record<string, string> = {
+  emits: "#ea580c",
+  handles: "#2563eb",
+  listens: "#c026d3",
+  queries: "#16a34a",
+  mutates: "#e11d48",
+  uiQuery: "#4263eb",
+  uiMutation: "#4263eb",
+};
+
+// ---------------------------------------------------------------------------
+// Referencje `<Arc>` (port z arc-map/src/refs.ts)
+// ---------------------------------------------------------------------------
+
+/** Propsy referencyjne `<Arc>` (jeden rodzaj na wystąpienie). */
+export interface ArcRefProps {
+  command?: string;
+  event?: string;
+  view?: string;
+  staticView?: string;
+  listener?: string;
+  route?: string;
+  aggregate?: string;
+  /** Z `aggregate`: metoda mutująca. */
+  mutationMethod?: string;
+  /** Z `aggregate`: metoda odczytu. */
+  queryMethod?: string;
+  /** Zarejestrowana strona (arc `page()`), po ścieżce routingu. */
+  page?: string;
+  /** Komponent React / plik UI (dopasowanie do skanu ts-morph). */
+  component?: string;
+}
+
+/**
+ * Kanoniczna tożsamość strony = jej ŚCIEŻKA routingu, bez query/hash i
+ * końcowego slasha (root "/" zachowany). Normalizacja tu ORAZ przy budowie
+ * nodów stron gwarantuje, że `<Arc page="/checkout">` i nod `/checkout`
+ * zlewają się niezależnie od przypadkowego `?query`.
+ */
+export function normalizePagePath(path: string): string {
+  let p = path.split("?")[0].split("#")[0].trim();
+  if (p.length > 1 && p.endsWith("/")) p = p.slice(0, -1);
+  return p;
+}
+
+/**
+ * Mapuje propsy `<Arc>` na rozwiązaną referencję lub null, gdy brak
+ * rozpoznawanego rodzaju. Czysto strukturalne — istnienie noda waliduje
+ * model przeciw grafowi (czerwony chip po stronie front).
+ */
+export function resolveArcRef(props: ArcRefProps): ResolvedRef | null {
+  if (props.command) {
+    return { nodeId: props.command, kind: "command", key: `command:${props.command}` };
+  }
+  if (props.view) {
+    return { nodeId: props.view, kind: "view", key: `view:${props.view}` };
+  }
+  if (props.staticView) {
+    return {
+      nodeId: props.staticView,
+      kind: "static-view",
+      key: `static-view:${props.staticView}`,
+    };
+  }
+  if (props.listener) {
+    return { nodeId: props.listener, kind: "listener", key: `listener:${props.listener}` };
+  }
+  if (props.route) {
+    return { nodeId: props.route, kind: "route", key: `route:${props.route}` };
+  }
+  if (props.page) {
+    const path = normalizePagePath(props.page);
+    return { nodeId: path, kind: "page", key: `page:${path}` };
+  }
+  if (props.component) {
+    return { nodeId: props.component, kind: "page", key: `component:${props.component}` };
+  }
+  if (props.aggregate) {
+    if (props.mutationMethod) {
+      return {
+        nodeId: props.aggregate,
+        kind: "aggregate",
+        method: { name: props.mutationMethod, kind: "mutation" },
+        key: `aggregate:${props.aggregate}#mutate:${props.mutationMethod}`,
+      };
+    }
+    if (props.queryMethod) {
+      return {
+        nodeId: props.aggregate,
+        kind: "aggregate",
+        method: { name: props.queryMethod, kind: "query" },
+        key: `aggregate:${props.aggregate}#query:${props.queryMethod}`,
+      };
+    }
+    // `<Arc aggregate="x" event="e">` — inline event jest osobnym nodem.
+    if (props.event) {
+      return { nodeId: props.event, kind: "event", key: `event:${props.event}` };
+    }
+    return { nodeId: props.aggregate, kind: "aggregate", key: `aggregate:${props.aggregate}` };
+  }
+  // Samodzielny event (bez agregatu).
+  if (props.event) {
+    return { nodeId: props.event, kind: "event", key: `event:${props.event}` };
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Wejście grafu (strukturalny podzbiór MapJson)
+// ---------------------------------------------------------------------------
+
+/** Metoda elementu (podzbiór MapElementMethod z arc-map). */
+export interface ArcGraphMethod {
+  name: string;
+  kind: string;
+  queryDeps?: string[];
+  mutationDeps?: string[];
+}
+
+/** Element (podzbiór MapElement z arc-map — MapJson jest zgodny strukturalnie). */
+export interface ArcGraphElement {
+  id: string;
+  name: string;
+  kind: string;
+  contextPath?: string[];
+  methods?: ArcGraphMethod[];
+  queryDeps?: string[];
+  mutationDeps?: string[];
+}
+
+export interface ArcGraphEdge {
+  source: string;
+  target: string;
+  kind: string;
+}
+
+export interface ArcGraphComponent {
+  id: string;
+  file: string;
+  name?: string;
+}
+
+export interface ArcGraphComponentEdge {
+  source: string;
+  target: string;
+  usage: "query" | "mutation";
+}
+
+/** Strukturalny podzbiór MapJson przyjmowany przez {@link toProcessGraph}. */
+export interface ArcGraphInput {
+  elements: ArcGraphElement[];
+  edges: ArcGraphEdge[];
+  components?: ArcGraphComponent[];
+  componentEdges?: ArcGraphComponentEdge[];
+  contexts?: ContextInfo[];
+}
+
+/** Przekształca dane mapy Arka na generyczny graf procesu. */
+export function toProcessGraph(input: ArcGraphInput): ProcessGraph {
+  const nodes: ProcessNode[] = input.elements.map((el) => ({
+    id: el.id,
+    kind: el.kind,
+    label: el.name,
+    contextPath: el.contextPath,
+    // Cały element wędruje do meta — profil (forwardDeps) i UI czytają
+    // z niego metody/deps/opisy bez zwężania na poziomie rdzenia.
+    meta: el as unknown as Record<string, unknown>,
+  }));
+  // Komponenty React (warstwa UI z ts-morph) — pseudo-nody rodzaju "page".
+  for (const c of input.components ?? []) {
+    nodes.push({
+      id: c.id,
+      kind: "page",
+      label: c.name ?? c.file,
+      meta: { ui: true, file: c.file },
+    });
+  }
+  const relations = [
+    ...input.edges.map((e) => ({ from: e.source, to: e.target, kind: e.kind })),
+    ...(input.componentEdges ?? []).map((e) => ({
+      from: e.source,
+      to: e.target,
+      kind: e.usage === "query" ? "uiQuery" : "uiMutation",
+    })),
+  ];
+  return { nodes, relations, contexts: input.contexts ?? [] };
+}
+
+// ---------------------------------------------------------------------------
+// Profil
+// ---------------------------------------------------------------------------
+
+/** Per-metodowe forward-zależności agregatów Arka. */
+function arcForwardDeps(
+  node: ProcessNode,
+  method?: MethodRef,
+): Partial<Record<string, string[]>> | null {
+  const meta = node.meta as ArcGraphElement | undefined;
+  if (!meta) return null;
+  if (method) {
+    const m = meta.methods?.find((x) => x.name === method.name);
+    return { queries: m?.queryDeps ?? [], mutates: m?.mutationDeps ?? [] };
+  }
+  return { queries: meta.queryDeps ?? [], mutates: meta.mutationDeps ?? [] };
+}
+
+/**
+ * Profil Arka. Dawne REL_SIDE staje się `defaultSide` grup doczepień:
+ * wejścia (queries/queriedBy/mutatedBy/handledBy/usedByUI) domyślnie na W,
+ * wyjścia (mutates) na E — a MDX może nadpisać per wystąpienie w 8 kierunkach.
+ */
+export const arcProfile = defineProfile({
+  id: "arc",
+  kinds: {
+    command: { color: ARC_ELEMENT_COLOR.command, label: "command" },
+    event: { color: ARC_ELEMENT_COLOR.event, label: "event" },
+    aggregate: { color: ARC_ELEMENT_COLOR.aggregate, label: "aggregate" },
+    view: { color: ARC_ELEMENT_COLOR.view, label: "view" },
+    "static-view": { color: ARC_ELEMENT_COLOR["static-view"], label: "static view" },
+    listener: { color: ARC_ELEMENT_COLOR.listener, label: "listener" },
+    route: { color: ARC_ELEMENT_COLOR.route, label: "route" },
+    page: { color: ARC_ELEMENT_COLOR.page, label: "page" },
+    context: { color: ARC_ELEMENT_COLOR.context, label: "context" },
+    note: { color: ARC_ELEMENT_COLOR.note, label: "note" },
+    unknown: { color: ARC_ELEMENT_COLOR.unknown },
+  },
+  relations: {
+    emits: { color: ARC_EDGE_COLOR.emits, semantics: "out" },
+    mutates: { color: ARC_EDGE_COLOR.mutates, semantics: "out" },
+    handles: { color: ARC_EDGE_COLOR.handles, semantics: "in" },
+    listens: { color: ARC_EDGE_COLOR.listens, semantics: "in" },
+    queries: { color: ARC_EDGE_COLOR.queries, semantics: "in" },
+    uiQuery: { color: ARC_EDGE_COLOR.uiQuery, semantics: "in", label: "czyta", dashed: true },
+    uiMutation: {
+      color: ARC_EDGE_COLOR.uiMutation,
+      semantics: "out",
+      label: "wywołuje",
+      dashed: true,
+    },
+  },
+  attachmentGroups: {
+    queries: {
+      relations: ["queries"],
+      direction: "out",
+      defaultSide: "W",
+      color: ARC_EDGE_COLOR.queries,
+      intoNode: true,
+      label: "czyta",
+    },
+    mutates: {
+      relations: ["mutates"],
+      direction: "out",
+      defaultSide: "E",
+      color: ARC_EDGE_COLOR.mutates,
+      intoNode: false,
+      label: "zapisuje",
+    },
+    mutatedBy: {
+      relations: ["mutates", "emits"],
+      direction: "in",
+      defaultSide: "W",
+      color: ARC_EDGE_COLOR.mutates,
+      intoNode: true,
+      label: "zapisywany przez",
+    },
+    queriedBy: {
+      relations: ["queries"],
+      direction: "in",
+      defaultSide: "W",
+      color: ARC_EDGE_COLOR.queries,
+      intoNode: true,
+      label: "czytany przez",
+    },
+    handledBy: {
+      relations: ["handles", "listens"],
+      direction: "in",
+      defaultSide: "W",
+      color: ARC_EDGE_COLOR.handles,
+      intoNode: true,
+      label: "obsługiwany przez",
+    },
+    usedByUI: {
+      relations: ["uiQuery", "uiMutation"],
+      direction: "in",
+      defaultSide: "W",
+      color: ARC_ELEMENT_COLOR.page,
+      intoNode: true,
+      label: "używany w UI",
+    },
+  },
+  resolveRef: (props) => resolveArcRef(props as ArcRefProps),
+  forwardDeps: arcForwardDeps,
+});

package/src/react/context-card.tsx

@@ -0,0 +1,112 @@
+/**
+ * Wizytówki kontekstów — custom renderery boxa kontekstu na diagramie.
+ *
+ * Kontekst deklaruje komponent w core przez opaque slot
+ * `context([...], { card: contextCard(MojaKarta) })`; ponieważ JSON grafu
+ * nie przenosi komponentów, po stronie klienta wizytówki rejestruje się
+ * w rejestrze: `registerContextCard("chat", ChatCard)` (klucz: id LUB nazwa
+ * kontekstu). Brak wpisu = {@link DefaultContextCard}.
+ */
+
+import type { ComponentType, ReactNode } from "react";
+import type { ContextInfo } from "../model/types";
+import { GLASS, tint } from "./theme";
+
+export interface ContextCardProps {
+  context: ContextInfo;
+  /** Czy box jest zwinięty (true) czy otwarty (obrys wokół wnętrza). */
+  collapsed: boolean;
+  /** Liczba kroków/elementów ukrytych w boxie (gdy znana). */
+  memberCount?: number;
+  /** Przełącza zwinięcie (klik w box = wejście poziom niżej). */
+  onToggle: () => void;
+  /** Etykieta narracji z `<Arc context>` (gdy inna niż tytuł kontekstu). */
+  label?: string;
+}
+
+/** Typowany konstruktor slotu `card` dla core `ContextOptions` (React-free tam). */
+export function contextCard(component: ComponentType<ContextCardProps>): unknown {
+  return component;
+}
+
+const registry = new Map<string, ComponentType<ContextCardProps>>();
+
+/** Zarejestruj wizytówkę pod id lub nazwą kontekstu (np. "chat", "ctx_chat"). */
+export function registerContextCard(
+  key: string,
+  component: ComponentType<ContextCardProps>,
+): void {
+  registry.set(key, component);
+}
+
+/** Znajdź wizytówkę dla kontekstu: po id, potem po nazwie. */
+export function cardFor(
+  ctx: ContextInfo,
+): ComponentType<ContextCardProps> | undefined {
+  return registry.get(ctx.id) ?? (ctx.name ? registry.get(ctx.name) : undefined);
+}
+
+const CONTEXT_COLOR = "#7c3aed";
+
+export function DefaultContextCard({
+  context,
+  collapsed,
+  memberCount,
+  onToggle,
+  label,
+}: ContextCardProps): ReactNode {
+  const title = context.title ?? context.name ?? context.id;
+  return (
+    <div
+      onClick={onToggle}
+      title={context.description ?? title}
+      style={{
+        width: "100%",
+        height: "100%",
+        boxSizing: "border-box",
+        borderRadius: 14,
+        border: `1.5px ${collapsed ? "solid" : "dashed"} ${CONTEXT_COLOR}`,
+        background: collapsed ? tint(CONTEXT_COLOR, 0.1) : "transparent",
+        backdropFilter: collapsed ? GLASS.blurSoft : undefined,
+        boxShadow: collapsed ? GLASS.shadow : "none",
+        padding: "8px 12px",
+        display: "flex",
+        flexDirection: "column",
+        gap: 3,
+        cursor: "pointer",
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+        <span
+          style={{
+            width: 8,
+            height: 8,
+            borderRadius: 99,
+            background: CONTEXT_COLOR,
+            boxShadow: `0 0 0 3px ${tint(CONTEXT_COLOR, 0.18)}`,
+          }}
+        />
+        <span style={{ fontWeight: 700, fontSize: 12.5, color: GLASS.text }}>{title}</span>
+        {memberCount ? (
+          <span
+            style={{
+              fontSize: 10,
+              color: GLASS.textMuted,
+              background: tint(CONTEXT_COLOR, 0.1),
+              borderRadius: 99,
+              padding: "0 7px",
+            }}
+          >
+            {memberCount}
+          </span>
+        ) : null}
+        <span style={{ marginLeft: "auto", fontSize: 10, color: GLASS.textFaint }}>
+          {collapsed ? "▸ otwórz" : "▾ zwiń"}
+        </span>
+      </div>
+      {collapsed && label && label !== title ? (
+        <div style={{ fontSize: 11.5, color: GLASS.textMuted }}>{label}</div>
+      ) : null}
+    </div>
+  );
+}

package/src/react/index.ts

@@ -0,0 +1,42 @@
+/**
+ * @arcote.tech/arc-process/react — komponenty React/MDX fragmentu process.
+ */
+
+export { ProcessDiagram, type ProcessDiagramProps } from "./process-diagram";
+export { makeNodeTypes } from "./nodes";
+export {
+  cardFor,
+  contextCard,
+  DefaultContextCard,
+  registerContextCard,
+  type ContextCardProps,
+} from "./context-card";
+export { GLASS, BG_GRADIENT, MISSING_COLOR, tint } from "./theme";
+export { Arc, type ArcProps } from "../mdx/arc";
+export {
+  Branch,
+  Continue,
+  Entry,
+  Lane,
+  Note,
+  Parallel,
+  Step,
+} from "../mdx/structure";
+export { MdxView, parseProcessFrontmatter, type ProcessFrontmatter } from "../mdx/mdx-view";
+export { ArcRefsProvider } from "../mdx/ref-context";
+export {
+  FocusContext,
+  ProcessDataContext,
+  RegisterContext,
+  StructureContext,
+  ViewStateContext,
+  useFocus,
+  useProcessData,
+  useRegister,
+  useStructure,
+  useViewState,
+  type FocusState,
+  type ProcessData,
+  type RegEntry,
+  type ViewStateActions,
+} from "../mdx/contexts";