archrip 0.2.2 → 0.2.4

package/dist/viewer-template/src/components/Legend.tsx

@@ -2,9 +2,12 @@ import { getCategoryColors, getCategoryLabel } from '../types.ts';
 
 interface LegendProps {
   categories: string[];
+  hiddenCategories: Set<string>;
+  onToggleCategory: (category: string) => void;
+  onShowAll: () => void;
 }
 
-export function Legend({ categories }: LegendProps) {
+export function Legend({ categories, hiddenCategories, onToggleCategory, onShowAll }: LegendProps) {
   return (
     <div
       className="absolute bottom-3 right-3 z-10 rounded-lg p-3 border"
@@ -23,19 +26,46 @@ export function Legend({ categories }: LegendProps) {
       <div className="grid grid-cols-2 gap-x-4 gap-y-1">
         {categories.map((cat) => {
           const colors = getCategoryColors(cat);
+          const hidden = hiddenCategories.has(cat);
           return (
-            <div key={cat} className="flex items-center gap-1.5">
+            <button
+              key={cat}
+              onClick={() => onToggleCategory(cat)}
+              className="flex items-center gap-1.5 cursor-pointer bg-transparent border-none p-0 text-left"
+            >
               <div
                 className="w-3 h-3 rounded-sm border"
-                style={{ background: colors.bg, borderColor: colors.border }}
+                style={{
+                  background: colors.bg,
+                  borderColor: colors.border,
+                  opacity: hidden ? 0.3 : 1,
+                  transition: 'opacity 0.2s',
+                }}
               />
-              <span className="text-xs" style={{ color: 'var(--color-content-secondary)' }}>
+              <span
+                className="text-xs"
+                style={{
+                  color: 'var(--color-content-secondary)',
+                  opacity: hidden ? 0.4 : 1,
+                  textDecoration: hidden ? 'line-through' : 'none',
+                  transition: 'opacity 0.2s',
+                }}
+              >
                 {getCategoryLabel(cat)}
               </span>
-            </div>
+            </button>
           );
         })}
       </div>
+      {hiddenCategories.size > 0 && (
+        <button
+          onClick={onShowAll}
+          className="mt-2 text-xs cursor-pointer hover:underline bg-transparent border-none p-0"
+          style={{ color: 'var(--color-interactive-primary)' }}
+        >
+          Show All
+        </button>
+      )}
     </div>
   );
 }

package/dist/viewer-template/src/components/UseCaseFilter.tsx

@@ -1,12 +1,53 @@
 import type { UseCase } from '../types.ts';
+import type { FlowAnimationState } from '../hooks/useFlowAnimation.ts';
 
 interface UseCaseFilterProps {
   useCases: UseCase[];
   selectedUseCase: string | null;
   onSelect: (useCaseId: string | null) => void;
+  flowInfo: FlowAnimationState;
 }
 
-export function UseCaseFilter({ useCases, selectedUseCase, onSelect }: UseCaseFilterProps) {
+function FlowButton({ label, onClick }: { label: string; onClick: () => void }) {
+  return (
+    <button
+      onClick={onClick}
+      className="w-7 h-7 flex items-center justify-center rounded border text-xs cursor-pointer"
+      style={{
+        background: 'var(--color-surface-secondary)',
+        borderColor: 'var(--color-border-primary)',
+        color: 'var(--color-content-secondary)',
+      }}
+      aria-label={label}
+    >
+      {label === 'Previous' && (
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
+          <path d="M8 1.5L3.5 6L8 10.5" stroke="currentColor" strokeWidth="1.5" fill="none" strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      )}
+      {label === 'Play' && (
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
+          <path d="M3 1.5L10 6L3 10.5V1.5Z" />
+        </svg>
+      )}
+      {label === 'Pause' && (
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
+          <rect x="2.5" y="1.5" width="2.5" height="9" rx="0.5" />
+          <rect x="7" y="1.5" width="2.5" height="9" rx="0.5" />
+        </svg>
+      )}
+      {label === 'Next' && (
+        <svg width="12" height="12" viewBox="0 0 12 12" fill="currentColor">
+          <path d="M4 1.5L8.5 6L4 10.5" stroke="currentColor" strokeWidth="1.5" fill="none" strokeLinecap="round" strokeLinejoin="round" />
+        </svg>
+      )}
+    </button>
+  );
+}
+
+export function UseCaseFilter({ useCases, selectedUseCase, onSelect, flowInfo }: UseCaseFilterProps) {
+  const selectedUc = selectedUseCase ? useCases.find((uc) => uc.id === selectedUseCase) : undefined;
+
   return (
     <div
       className="rounded-lg p-3 w-64 border"
@@ -40,11 +81,29 @@ export function UseCaseFilter({ useCases, selectedUseCase, onSelect }: UseCaseFi
           </option>
         ))}
       </select>
-      {selectedUseCase && (
+      {selectedUc && (
         <div className="mt-2">
           <p className="text-xs" style={{ color: 'var(--color-content-secondary)' }}>
-            {useCases.find((uc) => uc.id === selectedUseCase)?.description}
+            {selectedUc.description}
           </p>
+          {flowInfo.flowNodeIds && (
+            <div className="mt-1.5">
+              <p
+                className="text-xs font-mono mb-1.5"
+                style={{ color: 'var(--color-interactive-primary)' }}
+              >
+                Step {flowInfo.activeStep + 1}/{flowInfo.flowNodeIds.length}
+              </p>
+              <div className="flex items-center gap-1">
+                <FlowButton label="Previous" onClick={flowInfo.prev} />
+                <FlowButton
+                  label={flowInfo.isPlaying ? 'Pause' : 'Play'}
+                  onClick={flowInfo.isPlaying ? flowInfo.pause : flowInfo.play}
+                />
+                <FlowButton label="Next" onClick={flowInfo.next} />
+              </div>
+            </div>
+          )}
           <button
             onClick={() => onSelect(null)}
             className="mt-1.5 text-xs cursor-pointer hover:underline"

package/dist/viewer-template/src/hooks/useCategoryFilter.ts

@@ -0,0 +1,36 @@
+import { useCallback, useMemo } from 'react';
+import { useQueryState, parseAsString } from 'nuqs';
+
+interface CategoryFilterState {
+  hiddenCategories: Set<string>;
+  toggleCategory: (category: string) => void;
+  showAll: () => void;
+}
+
+export function useCategoryFilter(): CategoryFilterState {
+  const [hideParam, setHideParam] = useQueryState('hide', parseAsString.withOptions({ history: 'replace' }));
+
+  const hiddenCategories = useMemo(() => {
+    if (!hideParam) return new Set<string>();
+    return new Set(hideParam.split(',').filter(Boolean));
+  }, [hideParam]);
+
+  const toggleCategory = useCallback(
+    (category: string) => {
+      const next = new Set(hiddenCategories);
+      if (next.has(category)) {
+        next.delete(category);
+      } else {
+        next.add(category);
+      }
+      void setHideParam(next.size > 0 ? [...next].join(',') : null);
+    },
+    [hiddenCategories, setHideParam],
+  );
+
+  const showAll = useCallback(() => {
+    void setHideParam(null);
+  }, [setHideParam]);
+
+  return { hiddenCategories, toggleCategory, showAll };
+}

package/dist/viewer-template/src/hooks/useCommandPalette.ts

@@ -0,0 +1,91 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ArchFlowNode } from '../types.ts';
+
+export interface CommandPaletteResult {
+  id: string;
+  label: string;
+  category: string;
+  description: string;
+}
+
+interface CommandPaletteState {
+  isOpen: boolean;
+  toggle: () => void;
+  close: () => void;
+  query: string;
+  setQuery: (q: string) => void;
+  results: CommandPaletteResult[];
+  activeIndex: number;
+  moveUp: () => void;
+  moveDown: () => void;
+  activeItem: CommandPaletteResult | null;
+}
+
+const MAX_RESULTS = 20;
+
+export function useCommandPalette(
+  nodes: ArchFlowNode[],
+  hiddenCategories: Set<string>,
+): CommandPaletteState {
+  const [isOpen, setIsOpen] = useState(false);
+  const [query, setQueryRaw] = useState('');
+  const [activeIndex, setActiveIndex] = useState(0);
+
+  const toggle = useCallback(() => {
+    setIsOpen((prev) => {
+      if (!prev) {
+        setQueryRaw('');
+        setActiveIndex(0);
+      }
+      return !prev;
+    });
+  }, []);
+
+  const close = useCallback(() => {
+    setIsOpen(false);
+  }, []);
+
+  const setQuery = useCallback((q: string) => {
+    setQueryRaw(q);
+    setActiveIndex(0);
+  }, []);
+
+  const results = useMemo(() => {
+    const searchable = nodes.filter(
+      (n) => !n.hidden && !hiddenCategories.has(n.data.category),
+    );
+
+    if (!query.trim()) {
+      return searchable.slice(0, MAX_RESULTS).map((n) => ({
+        id: n.id,
+        label: n.data.label,
+        category: n.data.category,
+        description: n.data.description,
+      }));
+    }
+
+    const q = query.toLowerCase();
+    return searchable
+      .filter((n) => n.data.label.toLowerCase().includes(q))
+      .slice(0, MAX_RESULTS)
+      .map((n) => ({
+        id: n.id,
+        label: n.data.label,
+        category: n.data.category,
+        description: n.data.description,
+      }));
+  }, [nodes, hiddenCategories, query]);
+
+  const moveUp = useCallback(() => {
+    setActiveIndex((prev) => (prev <= 0 ? prev : prev - 1));
+  }, []);
+
+  const moveDown = useCallback(() => {
+    setActiveIndex((prev) => (prev >= results.length - 1 ? prev : prev + 1));
+  }, [results.length]);
+
+  const activeItem = results[activeIndex] ?? null;
+
+  return { isOpen, toggle, close, query, setQuery, results, activeIndex, moveUp, moveDown, activeItem };
+}

package/dist/viewer-template/src/hooks/useFlowAnimation.ts

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { UseCase } from '../types.ts';
+
+export interface FlowAnimationState {
+  activeStep: number;
+  flowNodeIds: string[] | null;
+  isPlaying: boolean;
+  play: () => void;
+  pause: () => void;
+  next: () => void;
+  prev: () => void;
+}
+
+const NOOP = () => {};
+
+const IDLE_STATE: FlowAnimationState = {
+  activeStep: -1,
+  flowNodeIds: null,
+  isPlaying: false,
+  play: NOOP,
+  pause: NOOP,
+  next: NOOP,
+  prev: NOOP,
+};
+
+export function useFlowAnimation(
+  useCases: UseCase[],
+  selectedUseCase: string | null,
+): FlowAnimationState {
+  const [activeStep, setActiveStep] = useState(0);
+  const [isPlaying, setIsPlaying] = useState(true);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const uc = selectedUseCase ? useCases.find((u) => u.id === selectedUseCase) : undefined;
+  const flow = uc?.flow;
+  const flowLength = flow?.length ?? 0;
+
+  // Reset on use case change
+  useEffect(() => {
+    setActiveStep(0);
+    setIsPlaying(true);
+  }, [selectedUseCase]);
+
+  // Auto-advance timer
+  useEffect(() => {
+    if (!flow || flowLength < 2 || !isPlaying) return;
+
+    timerRef.current = setTimeout(() => {
+      setActiveStep((prev) => {
+        const next = prev + 1;
+        return next >= flowLength ? 0 : next;
+      });
+    }, 800);
+
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [flow, flowLength, isPlaying, activeStep]);
+
+  const play = useCallback(() => setIsPlaying(true), []);
+  const pause = useCallback(() => setIsPlaying(false), []);
+
+  const next = useCallback(() => {
+    setIsPlaying(false);
+    setActiveStep((prev) => (prev + 1 >= flowLength ? prev : prev + 1));
+  }, [flowLength]);
+
+  const prev = useCallback(() => {
+    setIsPlaying(false);
+    setActiveStep((prev) => (prev <= 0 ? 0 : prev - 1));
+  }, []);
+
+  if (!flow || flowLength < 2) {
+    return IDLE_STATE;
+  }
+
+  return { activeStep, flowNodeIds: flow, isPlaying, play, pause, next, prev };
+}

package/dist/viewer-template/src/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,39 @@
+import { useEffect } from 'react';
+
+interface KeyboardShortcutActions {
+  onTogglePalette: () => void;
+  onEscape: () => void;
+  isPaletteOpen: boolean;
+}
+
+export function useKeyboardShortcuts(actions: KeyboardShortcutActions): void {
+  useEffect(() => {
+    function handleKeyDown(e: KeyboardEvent) {
+      // Skip when focused on form elements
+      const tag = (e.target as HTMLElement).tagName;
+      if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') {
+        // Allow Escape even in input
+        if (e.key === 'Escape') {
+          actions.onEscape();
+          return;
+        }
+        return;
+      }
+
+      // Cmd/Ctrl+K: toggle palette
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        actions.onTogglePalette();
+        return;
+      }
+
+      if (e.key === 'Escape') {
+        actions.onEscape();
+        return;
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [actions]);
+}

package/dist/viewer-template/src/hooks/useUseCaseFilter.ts

@@ -3,6 +3,7 @@ import { useQueryState, parseAsString } from 'nuqs';
 import type { Edge } from '@xyflow/react';
 
 import type { ArchFlowNode, UseCase } from '../types.ts';
+import { useFlowAnimation } from './useFlowAnimation.ts';
 
 function isNodeActive(node: ArchFlowNode, activeIds: Set<string>): boolean {
   if (node.data.isGroup && node.data.memberNodes) {
@@ -11,8 +12,20 @@ function isNodeActive(node: ArchFlowNode, activeIds: Set<string>): boolean {
   return activeIds.has(node.id);
 }
 
+/** Resolve a node's effective ID for flow matching (group → first active member) */
+function getFlowId(node: ArchFlowNode, flowSet: Set<string>): string | null {
+  if (flowSet.has(node.id)) return node.id;
+  if (node.data.isGroup && node.data.memberNodes) {
+    const member = node.data.memberNodes.find((m) => flowSet.has(m.id));
+    if (member) return member.id;
+  }
+  return null;
+}
+
 export function useUseCaseFilter(nodes: ArchFlowNode[], edges: Edge[], useCases: UseCase[]) {
   const [selectedUseCase, setSelectedUseCase] = useQueryState('uc', parseAsString.withOptions({ history: 'replace' }));
+  const flowState = useFlowAnimation(useCases, selectedUseCase);
+  const { activeStep, flowNodeIds } = flowState;
 
   const categories = useMemo(() => {
     const set = new Set<string>();
@@ -27,19 +40,77 @@ export function useUseCaseFilter(nodes: ArchFlowNode[], edges: Edge[], useCases:
     const uc = useCases.find((u) => u.id === selectedUseCase);
     if (!uc) return nodes;
     const activeIds = new Set(uc.nodeIds);
+
+    // No flow — static highlight (backward compat)
+    if (!flowNodeIds) {
+      return nodes.map((node) => {
+        if (node.hidden) return node;
+        const active = isNodeActive(node, activeIds);
+        return {
+          ...node,
+          style: {
+            ...node.style,
+            opacity: active ? 1 : 0.15,
+            transition: 'opacity 0.3s',
+          },
+        };
+      });
+    }
+
+    // Flow animation mode
+    const flowSet = new Set(flowNodeIds);
+    const activeFlowId = flowNodeIds[activeStep];
+    const passedIds = new Set(flowNodeIds.slice(0, activeStep));
+
     return nodes.map((node) => {
       if (node.hidden) return node;
       const active = isNodeActive(node, activeIds);
+      if (!active) {
+        // Non-participating node
+        return {
+          ...node,
+          style: { ...node.style, opacity: 0.08, transition: 'opacity 0.3s' },
+        };
+      }
+
+      const flowId = getFlowId(node, flowSet);
+      if (!flowId) {
+        // In use case but not in flow — dim slightly
+        return {
+          ...node,
+          style: { ...node.style, opacity: 0.3, transition: 'opacity 0.3s' },
+        };
+      }
+
+      if (flowId === activeFlowId) {
+        // Active step — glow + scale
+        return {
+          ...node,
+          style: {
+            ...node.style,
+            opacity: 1,
+            boxShadow: 'var(--shadow-node-flow-active)',
+            transform: 'scale(1.02)',
+            transition: 'opacity 0.3s, box-shadow 0.3s, transform 0.3s',
+          },
+        };
+      }
+
+      if (passedIds.has(flowId)) {
+        // Already passed
+        return {
+          ...node,
+          style: { ...node.style, opacity: 1, transition: 'opacity 0.3s' },
+        };
+      }
+
+      // Not yet reached
       return {
         ...node,
-        style: {
-          ...node.style,
-          opacity: active ? 1 : 0.15,
-          transition: 'opacity 0.3s',
-        },
+        style: { ...node.style, opacity: 0.3, transition: 'opacity 0.3s' },
       };
     });
-  }, [nodes, selectedUseCase, useCases]);
+  }, [nodes, selectedUseCase, useCases, flowNodeIds, activeStep]);
 
   const filteredEdges = useMemo(() => {
     if (!selectedUseCase) return edges;
@@ -55,19 +126,93 @@ export function useUseCaseFilter(nodes: ArchFlowNode[], edges: Edge[], useCases:
       }
     }
 
-    return edges.map((edge) => ({
-      ...edge,
-      style: {
-        ...edge.style,
-        opacity: activeNodeIds.has(edge.source) && activeNodeIds.has(edge.target) ? 1 : 0.08,
-        transition: 'opacity 0.3s',
-      },
-      labelStyle: {
-        ...((edge.labelStyle as Record<string, unknown>) ?? {}),
-        opacity: activeNodeIds.has(edge.source) && activeNodeIds.has(edge.target) ? 1 : 0,
-      },
-    }));
-  }, [edges, nodes, selectedUseCase, useCases]);
-
-  return { selectedUseCase, setSelectedUseCase, categories, filteredNodes, filteredEdges };
+    // No flow — static highlight (backward compat)
+    if (!flowNodeIds) {
+      return edges.map((edge) => ({
+        ...edge,
+        style: {
+          ...edge.style,
+          opacity: activeNodeIds.has(edge.source) && activeNodeIds.has(edge.target) ? 1 : 0.08,
+          transition: 'opacity 0.3s',
+        },
+        labelStyle: {
+          ...((edge.labelStyle as Record<string, unknown>) ?? {}),
+          opacity: activeNodeIds.has(edge.source) && activeNodeIds.has(edge.target) ? 1 : 0,
+        },
+      }));
+    }
+
+    // Flow animation mode — build flow edge lookup
+    // A flow edge is one connecting flow[i] → flow[i+1]
+    const flowEdgeMap = new Map<string, 'active' | 'passed' | 'upcoming'>();
+    for (let i = 0; i < flowNodeIds.length - 1; i++) {
+      const src = flowNodeIds[i];
+      const tgt = flowNodeIds[i + 1];
+      // Check both edge ID conventions
+      const key1 = `${src}->${tgt}`;
+      const key2 = `${tgt}->${src}`;
+      let status: 'active' | 'passed' | 'upcoming';
+      if (i + 1 === activeStep) {
+        status = 'active';
+      } else if (i + 1 <= activeStep) {
+        status = 'passed';
+      } else {
+        status = 'upcoming';
+      }
+      flowEdgeMap.set(key1, status);
+      flowEdgeMap.set(key2, status);
+    }
+
+    return edges.map((edge) => {
+      const bothActive = activeNodeIds.has(edge.source) && activeNodeIds.has(edge.target);
+      if (!bothActive) {
+        return {
+          ...edge,
+          style: { ...edge.style, opacity: 0.08, transition: 'opacity 0.3s' },
+          className: '',
+          labelStyle: {
+            ...((edge.labelStyle as Record<string, unknown>) ?? {}),
+            opacity: 0,
+          },
+        };
+      }
+
+      const flowStatus = flowEdgeMap.get(edge.id);
+      if (flowStatus === 'active') {
+        return {
+          ...edge,
+          style: { ...edge.style, opacity: 1, stroke: undefined, strokeWidth: undefined },
+          className: 'flow-edge-active',
+          labelStyle: {
+            ...((edge.labelStyle as Record<string, unknown>) ?? {}),
+            opacity: 1,
+          },
+        };
+      }
+      if (flowStatus === 'passed') {
+        return {
+          ...edge,
+          style: { ...edge.style, opacity: 1, transition: 'opacity 0.3s' },
+          className: '',
+          labelStyle: {
+            ...((edge.labelStyle as Record<string, unknown>) ?? {}),
+            opacity: 1,
+          },
+        };
+      }
+
+      // In use case but not a flow edge, or upcoming flow edge
+      return {
+        ...edge,
+        style: { ...edge.style, opacity: 0.3, transition: 'opacity 0.3s' },
+        className: '',
+        labelStyle: {
+          ...((edge.labelStyle as Record<string, unknown>) ?? {}),
+          opacity: 0.3,
+        },
+      };
+    });
+  }, [edges, nodes, selectedUseCase, useCases, flowNodeIds, activeStep]);
+
+  return { selectedUseCase, setSelectedUseCase, categories, filteredNodes, filteredEdges, flowInfo: flowState };
 }

package/dist/viewer-template/src/index.css

@@ -33,6 +33,7 @@
   --shadow-panel: 0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1);
   --shadow-node: 0 1px 3px rgba(0, 0, 0, 0.1);
   --shadow-node-selected: 0 0 0 2px rgba(37, 99, 235, 0.25);
+  --shadow-node-flow-active: 0 0 12px 2px rgba(59, 130, 246, 0.5);
 
   /* Category colors (light) */
   --cat-controller-bg: #dbeafe;
@@ -50,6 +51,9 @@
   --cat-model-bg: #fee2e2;
   --cat-model-border: #ef4444;
   --cat-model-text: #991b1b;
+  --cat-database-bg: #fef3c7;
+  --cat-database-border: #d97706;
+  --cat-database-text: #92400e;
   --cat-external-bg: #f3f4f6;
   --cat-external-border: #6b7280;
   --cat-external-text: #374151;
@@ -88,6 +92,7 @@
   --shadow-panel: 0 1px 3px 0 rgba(0, 0, 0, 0.4), 0 1px 2px -1px rgba(0, 0, 0, 0.4);
   --shadow-node: 0 1px 3px rgba(0, 0, 0, 0.3);
   --shadow-node-selected: 0 0 0 2px rgba(96, 165, 250, 0.3);
+  --shadow-node-flow-active: 0 0 12px 2px rgba(96, 165, 250, 0.4);
 
   /* Category colors (dark) */
   --cat-controller-bg: #1e293b;
@@ -105,6 +110,9 @@
   --cat-model-bg: #2b1111;
   --cat-model-border: #f87171;
   --cat-model-text: #fca5a5;
+  --cat-database-bg: #2b1f06;
+  --cat-database-border: #fbbf24;
+  --cat-database-text: #fde68a;
   --cat-external-bg: #1e2330;
   --cat-external-border: #9ca3af;
   --cat-external-text: #d1d5db;
@@ -119,6 +127,17 @@
   --cat-fallback-text: #d6d3d1;
 }
 
+/* ─── Flow Animation ─── */
+@keyframes dash-flow {
+  to { stroke-dashoffset: -20; }
+}
+.react-flow__edge.flow-edge-active .react-flow__edge-path {
+  stroke: var(--color-interactive-primary) !important;
+  stroke-width: 2.5 !important;
+  stroke-dasharray: 8 4;
+  animation: dash-flow 0.6s linear infinite;
+}
+
 html,
 body,
 #root {