@arcote.tech/arc-map 0.7.27

package/src/app/nodes.tsx

@@ -0,0 +1,478 @@
+/** Custom React Flow node renderers: space box, element, React component.
+ *  Light glassmorphism styling (frosted glass + purple accents, ndt-like). */
+
+import { Handle, Position, type NodeProps } from "@xyflow/react";
+import type { MapComponent, MapElement } from "../types";
+import { COMPONENT_COLOR, ELEMENT_COLOR, GLASS } from "./theme";
+import { useExpand, useFocus } from "./contexts";
+import type { RelKind, StepNode as StepModel } from "./usecase-model";
+
+const REL_LABEL: Record<RelKind, string> = {
+  queries: "czyta",
+  mutates: "mutuje",
+  mutatedBy: "mutowane przez",
+  queriedBy: "czytane przez",
+  handledBy: "obsługiwane przez",
+  usedByUI: "UI",
+};
+
+const KIND_ICON: Record<string, string> = {
+  aggregate: "◆",
+  command: "▶",
+  event: "✶",
+  view: "▦",
+  "static-view": "▤",
+  listener: "♪",
+  route: "⇄",
+  page: "▢",
+  unknown: "•",
+};
+
+/** Hex accent -> translucent tint for the element surface. */
+function tint(hex: string, alpha: number): string {
+  const h = hex.replace("#", "");
+  const r = parseInt(h.slice(0, 2), 16);
+  const g = parseInt(h.slice(2, 4), 16);
+  const b = parseInt(h.slice(4, 6), 16);
+  return `rgba(${r},${g},${b},${alpha})`;
+}
+
+export function SpaceNode({ data }: NodeProps) {
+  const d = data as { label: string; count: number };
+  return (
+    <div
+      style={{
+        width: "100%",
+        height: "100%",
+        borderRadius: 18,
+        border: `1px solid ${GLASS.border}`,
+        background: GLASS.space,
+        backdropFilter: GLASS.blur,
+        WebkitBackdropFilter: GLASS.blur,
+        boxShadow: GLASS.shadow,
+      }}
+    >
+      <div
+        style={{
+          padding: "11px 18px",
+          fontWeight: 700,
+          fontSize: 14,
+          color: GLASS.text,
+          letterSpacing: 0.2,
+          borderBottom: `1px solid ${GLASS.border}`,
+          display: "flex",
+          gap: 9,
+          alignItems: "center",
+        }}
+      >
+        <span
+          style={{
+            width: 8,
+            height: 8,
+            borderRadius: 99,
+            background: "#7c3aed",
+            boxShadow: "0 0 0 4px rgba(124,58,237,0.18)",
+          }}
+        />
+        <span>{d.label}</span>
+        <span
+          style={{
+            fontSize: 11,
+            color: GLASS.textMuted,
+            background: "rgba(124,58,237,0.10)",
+            borderRadius: 99,
+            padding: "1px 8px",
+          }}
+        >
+          {d.count}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+export function ElementNode({ data, selected }: NodeProps) {
+  const d = data as { element: MapElement; seq?: number; referenced?: boolean };
+  const el = d.element;
+  const color = ELEMENT_COLOR[el.kind] ?? ELEMENT_COLOR.unknown;
+  // In use-case mode `referenced` is set: referenced nodes stay solid, related
+  // (connector/neighbour) nodes are de-emphasized.
+  const related = d.referenced === false;
+  return (
+    <div
+      style={{
+        position: "relative",
+        width: 196,
+        height: 62,
+        boxSizing: "border-box",
+        borderRadius: 13,
+        border: `1px solid ${selected ? color : GLASS.border}`,
+        borderLeft: `4px solid ${color}`,
+        background: selected ? GLASS.cardStrong : GLASS.card,
+        backdropFilter: GLASS.blurSoft,
+        WebkitBackdropFilter: GLASS.blurSoft,
+        padding: "9px 12px",
+        display: "flex",
+        flexDirection: "column",
+        gap: 3,
+        cursor: "pointer",
+        opacity: related ? 0.62 : 1,
+        boxShadow: selected ? GLASS.shadowStrong : GLASS.shadow,
+      }}
+    >
+      {d.seq != null ? (
+        <span
+          style={{
+            position: "absolute",
+            top: -9,
+            left: -9,
+            width: 20,
+            height: 20,
+            borderRadius: 99,
+            background: color,
+            color: "#fff",
+            fontSize: 11,
+            fontWeight: 700,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: "0 1px 4px rgba(0,0,0,0.25)",
+          }}
+        >
+          {d.seq}
+        </span>
+      ) : null}
+      <Handle type="target" position={Position.Left} style={{ background: color, border: "none" }} />
+      <Handle type="source" position={Position.Right} style={{ background: color, border: "none" }} />
+      <div style={{ display: "flex", gap: 7, alignItems: "center" }}>
+        <span style={{ color, fontSize: 13 }}>{KIND_ICON[el.kind] ?? "•"}</span>
+        <span
+          style={{
+            fontWeight: 700,
+            fontSize: 12.5,
+            color: GLASS.text,
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+          }}
+        >
+          {el.name}
+        </span>
+      </div>
+      <div style={{ display: "flex", gap: 6, alignItems: "center" }}>
+        <span
+          style={{
+            fontSize: 9.5,
+            fontWeight: 600,
+            color,
+            background: tint(color, 0.12),
+            borderRadius: 5,
+            padding: "1px 6px",
+            textTransform: "uppercase",
+            letterSpacing: 0.4,
+          }}
+        >
+          {el.kind}
+        </span>
+        {el.protections?.length ? (
+          <span style={{ fontSize: 10 }} title={el.protections.join(", ")}>
+            🔒
+          </span>
+        ) : null}
+        {el.moduleName ? (
+          <span style={{ fontSize: 9.5, color: GLASS.textFaint, marginLeft: "auto" }}>
+            {el.moduleName}
+          </span>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+export function ComponentNode({ data, selected }: NodeProps) {
+  const c = (data as { component: MapComponent }).component;
+  return (
+    <div
+      style={{
+        width: 214,
+        height: 54,
+        boxSizing: "border-box",
+        borderRadius: 13,
+        border: `1.5px dashed ${selected ? COMPONENT_COLOR : GLASS.border}`,
+        background: selected ? GLASS.cardStrong : "rgba(255,255,255,0.55)",
+        backdropFilter: GLASS.blurSoft,
+        WebkitBackdropFilter: GLASS.blurSoft,
+        padding: "8px 12px",
+        cursor: "pointer",
+        boxShadow: GLASS.shadow,
+      }}
+    >
+      <Handle type="source" position={Position.Right} style={{ background: COMPONENT_COLOR, border: "none" }} />
+      <div
+        style={{
+          fontSize: 12,
+          fontWeight: 700,
+          color: GLASS.text,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+          whiteSpace: "nowrap",
+        }}
+      >
+        ⚛ {c.name ?? c.file}
+      </div>
+      <div
+        style={{
+          fontSize: 9.5,
+          color: GLASS.textFaint,
+          overflow: "hidden",
+          textOverflow: "ellipsis",
+          whiteSpace: "nowrap",
+        }}
+      >
+        {c.file}
+      </div>
+    </div>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Use-case data-flow nodes
+// ---------------------------------------------------------------------------
+
+/** A narrated `<Arc>` step on the backbone — with badges per relation kind. */
+export function StepNode({ data }: NodeProps) {
+  const step = (data as { step: StepModel }).step;
+  const expandedKinds = (data as { expanded: RelKind[] }).expanded ?? [];
+  const { toggle } = useExpand();
+  const { focusNodeId } = useFocus();
+  const el = step.element;
+  const missing = !step.exists;
+  // Keep the declared kind even when the element does not exist yet, so we don't
+  // lose knowledge — colour/label like any other node, just dashed + faded.
+  const kind = (el?.kind ?? (step.ref?.kind as string) ?? "unknown") as keyof typeof ELEMENT_COLOR;
+  const color = ELEMENT_COLOR[kind] ?? ELEMENT_COLOR.unknown;
+  const myId = el?.id ?? step.ref?.nodeId;
+  const dimmed = !!focusNodeId && focusNodeId !== myId;
+  const focused = !!focusNodeId && focusNodeId === myId;
+  const badgeKinds = Object.keys(step.badges) as RelKind[];
+
+  return (
+    <div
+      style={{
+        minWidth: 200,
+        maxWidth: 230,
+        boxSizing: "border-box",
+        borderRadius: 14,
+        // Dashed is reserved for MISSING (not-yet-implemented) elements. Branch
+        // alternatives stay solid — their "alt" nature is shown by the ⋔ badge,
+        // not by a dashed border that reads as "not implemented".
+        border: `1px ${missing ? "dashed" : "solid"} ${color}`,
+        borderLeft: `5px ${missing ? "dashed" : "solid"} ${color}`,
+        background: GLASS.cardStrong,
+        backdropFilter: GLASS.blurSoft,
+        WebkitBackdropFilter: GLASS.blurSoft,
+        padding: "10px 12px",
+        position: "relative",
+        opacity: dimmed ? 0.35 : missing ? 0.7 : 1,
+        boxShadow: focused ? `0 0 0 2px ${color}` : GLASS.shadow,
+        transition: "opacity 120ms ease, box-shadow 120ms ease",
+      }}
+    >
+      <Handle type="target" position={Position.Left} style={{ background: color, border: "none" }} />
+      <Handle type="source" position={Position.Right} style={{ background: color, border: "none" }} />
+      <span
+        style={{
+          position: "absolute",
+          top: -10,
+          left: -10,
+          width: 22,
+          height: 22,
+          borderRadius: 99,
+          background: color,
+          color: "#fff",
+          fontSize: 12,
+          fontWeight: 700,
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "center",
+          boxShadow: "0 1px 4px rgba(0,0,0,0.25)",
+        }}
+      >
+        {step.seq}
+      </span>
+      <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
+        <span style={{ color, fontSize: 13 }}>{KIND_ICON[kind] ?? "•"}</span>
+        <span style={{ fontWeight: 700, fontSize: 13, color: GLASS.text }}>
+          {step.ref?.nodeId ?? step.label}
+        </span>
+      </div>
+      <div style={{ display: "flex", alignItems: "center", gap: 6, marginTop: 2 }}>
+        <span
+          style={{
+            fontSize: 9.5,
+            fontWeight: 600,
+            color,
+            background: tint(color, 0.12),
+            borderRadius: 5,
+            padding: "1px 6px",
+            textTransform: "uppercase",
+            letterSpacing: 0.4,
+          }}
+        >
+          {kind}
+        </span>
+        {step.method ? (
+          <span style={{ fontSize: 11, color: "#3b2a55" }}>
+            ·{step.method.name}
+            <span style={{ color: GLASS.textFaint }}> ({step.method.kind})</span>
+          </span>
+        ) : null}
+      </div>
+      {step.label && step.label !== step.ref?.nodeId ? (
+        <div style={{ fontSize: 11, color: GLASS.textMuted, marginTop: 3 }}>{step.label}</div>
+      ) : null}
+      {step.stepTitle || step.laneTitle || step.alt ? (
+        <div style={{ display: "flex", gap: 5, marginTop: 4, flexWrap: "wrap" }}>
+          {step.stepTitle ? (
+            <span style={{ fontSize: 9, fontWeight: 700, color: "#1c7ed6", background: "rgba(28,126,214,0.1)", borderRadius: 4, padding: "0 5px" }}>
+              ▸ {step.stepTitle}
+            </span>
+          ) : null}
+          {step.alt ? (
+            <span style={{ fontSize: 9, fontWeight: 700, color: "#e64980", background: "rgba(230,73,128,0.1)", borderRadius: 4, padding: "0 5px" }}>
+              ⋔ {step.laneTitle ?? "alt"}
+            </span>
+          ) : step.laneTitle ? (
+            <span style={{ fontSize: 9, fontWeight: 700, color: "#7c3aed", background: "rgba(124,58,237,0.1)", borderRadius: 4, padding: "0 5px" }}>
+              ∥ {step.laneTitle}
+            </span>
+          ) : null}
+        </div>
+      ) : null}
+      {badgeKinds.length ? (
+        <div style={{ display: "flex", flexWrap: "wrap", gap: 4, marginTop: 7 }}>
+          {badgeKinds.map((k) => {
+            const active = expandedKinds.includes(k);
+            const c = REL_BADGE_COLOR[k];
+            return (
+              <button
+                key={k}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  toggle(step.occId, k);
+                }}
+                style={{
+                  fontSize: 9.5,
+                  fontWeight: 600,
+                  border: `1px solid ${c}`,
+                  background: active ? c : tint(c, 0.1),
+                  color: active ? "#fff" : c,
+                  borderRadius: 6,
+                  padding: "1px 6px",
+                  cursor: "pointer",
+                }}
+                title={`${REL_LABEL[k]}: ${step.badges[k]!.join(", ")}`}
+              >
+                {relBadgeLabel(k, el?.kind)} {step.badges[k]!.length}
+              </button>
+            );
+          })}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+const REL_BADGE_COLOR: Record<RelKind, string> = {
+  queries: "#2f9e44",
+  mutates: "#e11d48",
+  mutatedBy: "#d97706",
+  queriedBy: "#0ca678",
+  handledBy: "#1c7ed6",
+  usedByUI: "#4263eb",
+};
+
+function relBadgeLabel(k: RelKind, elKind?: string): string {
+  if (k === "mutatedBy" && elKind === "event") return "emitowane przez";
+  return REL_LABEL[k];
+}
+
+/** A dependency element revealed in a left/right column when a badge expands. */
+export function DepNode({ data }: NodeProps) {
+  const el = (data as { element: MapElement }).element;
+  const { focusNodeId } = useFocus();
+  const color = ELEMENT_COLOR[el.kind] ?? "#64748b";
+  const dimmed = !!focusNodeId && focusNodeId !== el.id;
+  const focused = !!focusNodeId && focusNodeId === el.id;
+  return (
+    <div
+      style={{
+        width: 178,
+        boxSizing: "border-box",
+        borderRadius: 10,
+        border: `1px solid ${color}`,
+        borderLeft: `4px solid ${color}`,
+        background: GLASS.card,
+        padding: "6px 9px",
+        opacity: dimmed ? 0.35 : 1,
+        boxShadow: focused ? `0 0 0 2px ${color}` : GLASS.shadow,
+        transition: "opacity 120ms ease",
+      }}
+    >
+      <Handle type="target" position={Position.Left} style={{ background: color, border: "none" }} />
+      <Handle type="source" position={Position.Right} style={{ background: color, border: "none" }} />
+      <div style={{ display: "flex", gap: 5, alignItems: "center" }}>
+        <span style={{ color, fontSize: 11 }}>{KIND_ICON[el.kind] ?? "•"}</span>
+        <span style={{ fontWeight: 600, fontSize: 11.5, color: GLASS.text, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+          {el.name}
+        </span>
+      </div>
+      <div style={{ fontSize: 8.5, color, textTransform: "uppercase", letterSpacing: 0.3 }}>{el.kind}</div>
+    </div>
+  );
+}
+
+/** An element on a connecting flow path between two narrated steps. Rendered
+ *  exactly like any other element node — no special "connector" marking. */
+export function ConnectorNode({ data }: NodeProps) {
+  const el = (data as { element: MapElement }).element;
+  const { focusNodeId } = useFocus();
+  const color = ELEMENT_COLOR[el.kind] ?? "#64748b";
+  const dimmed = !!focusNodeId && focusNodeId !== el.id;
+  const focused = !!focusNodeId && focusNodeId === el.id;
+  return (
+    <div
+      style={{
+        width: 178,
+        boxSizing: "border-box",
+        borderRadius: 10,
+        border: `1px solid ${color}`,
+        borderLeft: `4px solid ${color}`,
+        background: GLASS.card,
+        padding: "6px 9px",
+        opacity: dimmed ? 0.35 : 1,
+        boxShadow: focused ? `0 0 0 2px ${color}` : GLASS.shadow,
+        transition: "opacity 120ms ease",
+      }}
+    >
+      <Handle type="target" position={Position.Left} style={{ background: color, border: "none" }} />
+      <Handle type="source" position={Position.Right} style={{ background: color, border: "none" }} />
+      <div style={{ display: "flex", gap: 5, alignItems: "center" }}>
+        <span style={{ color, fontSize: 11 }}>{KIND_ICON[el.kind] ?? "•"}</span>
+        <span style={{ fontWeight: 600, fontSize: 11.5, color: GLASS.text, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+          {el.name}
+        </span>
+      </div>
+      <div style={{ fontSize: 8.5, color, textTransform: "uppercase", letterSpacing: 0.3 }}>{el.kind}</div>
+    </div>
+  );
+}
+
+export const nodeTypes = {
+  space: SpaceNode,
+  element: ElementNode,
+  component: ComponentNode,
+  step: StepNode,
+  dep: DepNode,
+  connector: ConnectorNode,
+};

package/src/app/ref-context.tsx

@@ -0,0 +1,49 @@
+/**
+ * ArcRefsProvider — collects `<Arc>` registrations rendered inside it and
+ * reports them to the parent in DOCUMENT ORDER (read from the DOM, so nesting
+ * and ordering are exact). Remount per use-case (via `key`) gives a fresh
+ * registry. Guarded against update loops by comparing the ordered key list.
+ */
+
+import { useCallback, useEffect, useRef, type ReactNode } from "react";
+import { ArcRegisterContext, type ArcRegEntry } from "./contexts";
+
+export function ArcRefsProvider({
+  children,
+  onRefs,
+}: {
+  children: ReactNode;
+  onRefs: (refs: ArcRegEntry[]) => void;
+}) {
+  const registry = useRef(new Map<string, ArcRegEntry>());
+  const containerRef = useRef<HTMLDivElement>(null);
+  const lastSig = useRef<string>("");
+
+  const register = useCallback((entry: ArcRegEntry) => {
+    registry.current.set(entry.id, entry);
+  }, []);
+
+  // After every render, read the chips in DOM order and lift the list up —
+  // but only when the ordered set actually changed (prevents render loops).
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const ordered: ArcRegEntry[] = [];
+    el.querySelectorAll<HTMLElement>("[data-arc-id]").forEach((node) => {
+      const e = registry.current.get(node.dataset.arcId ?? "");
+      if (e) ordered.push(e);
+    });
+    const sig = ordered.map((e) => e.ref?.key ?? `?${e.id}`).join("|");
+    if (sig === lastSig.current) return;
+    lastSig.current = sig;
+    onRefs(ordered);
+  });
+
+  return (
+    <div ref={containerRef}>
+      <ArcRegisterContext.Provider value={register}>
+        {children}
+      </ArcRegisterContext.Provider>
+    </div>
+  );
+}

package/src/app/structure.tsx

@@ -0,0 +1,95 @@
+/**
+ * Structural MDX components for use-case flows. They render a light visual cue
+ * in the prose AND give each nested `<Arc>` a structural path (via context),
+ * which the model turns into depth (time) × lane (parallel / branch).
+ *
+ *   <Parallel>            — children run concurrently (AND); same depth, lanes
+ *   <Branch><Lane>…</Lane> — alternative paths (XOR); branch lanes
+ *   <Step title="…">      — a named phase grouping a sub-sequence
+ */
+
+import { Children, isValidElement, useId, type ReactNode } from "react";
+import { StructureContext, useStructure, type PathSeg } from "./contexts";
+import { GLASS } from "./theme";
+
+/** Wrap each element child with a structural segment + lane index. */
+function mapLanes(children: ReactNode, base: PathSeg[], seg: (i: number) => PathSeg): ReactNode {
+  let i = 0;
+  return Children.map(children, (child) => {
+    if (!isValidElement(child)) return child;
+    const s = seg(i++);
+    return <StructureContext.Provider value={{ path: [...base, s] }}>{child}</StructureContext.Provider>;
+  });
+}
+
+const wrapStyle: React.CSSProperties = {
+  display: "block",
+  borderLeft: `3px solid ${GLASS.border}`,
+  paddingLeft: 12,
+  margin: "8px 0",
+};
+
+const tagStyle = (color: string): React.CSSProperties => ({
+  display: "inline-block",
+  fontSize: 10,
+  fontWeight: 700,
+  textTransform: "uppercase",
+  letterSpacing: 0.5,
+  color,
+  background: "rgba(124,58,237,0.08)",
+  borderRadius: 5,
+  padding: "1px 7px",
+  marginBottom: 4,
+});
+
+export function Parallel({ children }: { children?: ReactNode }) {
+  const id = useId();
+  const { path } = useStructure();
+  return (
+    <span style={{ ...wrapStyle, borderLeftColor: "#7c3aed" }}>
+      <span style={tagStyle("#7c3aed")}>∥ równolegle</span>
+      {mapLanes(children, path, (i) => ({ type: "parallel", id, laneIndex: i }))}
+    </span>
+  );
+}
+
+export function Branch({ children }: { children?: ReactNode }) {
+  const id = useId();
+  const { path } = useStructure();
+  return (
+    <span style={{ ...wrapStyle, borderLeftColor: "#e64980" }}>
+      <span style={tagStyle("#e64980")}>⋔ alternatywnie</span>
+      {mapLanes(children, path, (i) => ({ type: "branch", id, laneIndex: i }))}
+    </span>
+  );
+}
+
+export function Lane({ title, children }: { title?: string; children?: ReactNode }) {
+  const id = useId();
+  const { path } = useStructure();
+  return (
+    <StructureContext.Provider value={{ path: [...path, { type: "lane", id, title, alt: true }] }}>
+      <span style={{ display: "block", margin: "4px 0" }}>
+        {title ? (
+          <span style={{ fontSize: 11, fontWeight: 700, color: "#e64980", marginRight: 6 }}>
+            {title}:
+          </span>
+        ) : null}
+        {children}
+      </span>
+    </StructureContext.Provider>
+  );
+}
+
+export function Step({ title, children }: { title?: string; children?: ReactNode }) {
+  const id = useId();
+  const { path } = useStructure();
+  return (
+    <StructureContext.Provider value={{ path: [...path, { type: "step", id, title }] }}>
+      <span style={{ ...wrapStyle, borderLeftColor: "#1c7ed6" }}>
+        {title ? <span style={tagStyle("#1c7ed6")}>▸ {title}</span> : null}
+        {children}
+      </span>
+    </StructureContext.Provider>
+  );
+}