@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/components/organisms/WizardContainer.tsx

@@ -0,0 +1,369 @@
+/**
+ * WizardContainer Component
+ *
+ * Multi-step wizard pattern with progress indicator.
+ * Composes Box, Typography, and Button atoms.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React, { useState, useCallback } from "react";
+import { ChevronLeft, ChevronRight, Check } from "lucide-react";
+import { Button } from "../atoms/Button";
+import { Typography } from "../atoms/Typography";
+import { Box } from "../atoms/Box";
+import { Icon } from "../atoms/Icon";
+import { cn } from "../../lib/cn";
+
+/** Form field definition for wizard sections */
+export interface WizardField {
+  id: string;
+  type: string;
+  label?: string;
+  required?: boolean;
+  repeatable?: boolean;
+  options?: Array<{ value: string; label: string; isDefault?: boolean }>;
+  defaultValue?: unknown;
+  condition?: unknown[];
+  placeholder?: string;
+  entityField?: string;
+  minLength?: number;
+  maxLength?: number;
+  dataSource?: Record<string, unknown>;
+  displayFields?: string[];
+  searchConfig?: Record<string, unknown>;
+  hiddenCalculations?: Array<{
+    variable: string;
+    expression: unknown;
+    scope?: string;
+  }>;
+  signatureConfig?: Record<string, unknown>;
+  displayTemplate?: Record<string, unknown>;
+  lawReference?: Record<string, unknown>;
+  contextMenu?: string[];
+  calculated?: Record<string, unknown>;
+  readOnly?: boolean;
+  minDate?: unknown;
+  stats?: Array<{ label: string; value: unknown; icon?: string }>;
+  items?: Array<{ id: string; label: string; autoCheck?: unknown }>;
+  [key: string]: unknown;
+}
+
+/** Section within a wizard step */
+export interface WizardSection {
+  id: string;
+  title?: string;
+  description?: string;
+  fields?: WizardField[];
+  subsections?: WizardSection[];
+  condition?: unknown[];
+  repeatable?: boolean;
+  minItems?: number;
+  addButtonLabel?: string;
+  hiddenCalculations?: Array<{
+    variable: string;
+    expression: unknown;
+    scope?: string;
+  }>;
+  dataSource?: Record<string, unknown>;
+  readOnly?: boolean;
+  [key: string]: unknown;
+}
+
+/** Entity mapping configuration */
+export interface WizardEntityMapping {
+  entity: string;
+  mode:
+    | "search_or_create"
+    | "create_multiple"
+    | "select_one"
+    | "update"
+    | string;
+  parentField?: string;
+  idField?: string;
+  [key: string]: unknown;
+}
+
+/** Validation rule for wizard steps */
+export interface WizardValidationRule {
+  condition: unknown[];
+  message: string;
+}
+
+/** Law reference for compliance */
+export interface WizardLawReference {
+  law: string;
+  article: string;
+  description?: string;
+}
+
+export interface WizardStep {
+  /** Step identifier */
+  id?: string;
+  /** Tab identifier (schema-driven) */
+  tabId?: string;
+  /** Step title */
+  title?: string;
+  /** Step name (schema-driven, used as title if title not provided) */
+  name?: string;
+  /** Step description (optional) */
+  description?: string;
+  /** Step content (React component mode) */
+  content?: React.ReactNode;
+  /** Whether this step can be skipped */
+  optional?: boolean;
+  /** Custom validation for this step */
+  isValid?: () => boolean;
+
+  // Schema-driven wizard properties
+  /** Form sections within this step */
+  sections?: WizardSection[];
+  /** Global variables required before entering this step */
+  globalVariablesRequired?: string[];
+  /** Global variables set by this step */
+  globalVariablesSet?: string[];
+  /** Local variables scoped to this step */
+  localVariables?: string[];
+  /** Entity mapping configuration */
+  entityMapping?: WizardEntityMapping;
+  /** Validation rules for this step */
+  validationRules?: WizardValidationRule[];
+  /** Law references for compliance */
+  lawReferences?: WizardLawReference[];
+  /** Phase of the inspection process */
+  phase?: string;
+  /** Context menu actions */
+  contextMenu?: string[];
+
+  /** Allow additional properties from schema */
+  [key: string]: unknown;
+}
+
+export interface WizardContainerProps {
+  /** Wizard steps */
+  steps: WizardStep[];
+  /** Current step index (controlled) - accepts unknown for generated code compatibility */
+  currentStep?: number | string | unknown;
+  /** Callback when step changes */
+  onStepChange?: (stepIndex: number) => void;
+  /** Callback when wizard is completed */
+  onComplete?: () => void;
+  /** Show progress indicator */
+  showProgress?: boolean;
+  /** Allow navigation to previous steps */
+  allowBack?: boolean;
+  /** Modal mode (compact header, no padding) */
+  compact?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+  /** Entity type name (schema-driven) */
+  entity?: string;
+}
+
+/**
+ * WizardContainer - Multi-step wizard
+ */
+export const WizardContainer: React.FC<WizardContainerProps> = ({
+  steps,
+  currentStep: controlledStep,
+  onStepChange,
+  onComplete,
+  showProgress = true,
+  allowBack = true,
+  compact = false,
+  className,
+  entity: _entity, // Accept but don't use directly yet
+}) => {
+  const [internalStep, setInternalStep] = useState(0);
+
+  // Normalize controlledStep to number (handles string/unknown from generated code)
+  const normalizedControlledStep = (() => {
+    if (controlledStep === undefined || controlledStep === null)
+      return undefined;
+    if (typeof controlledStep === "number") return controlledStep;
+    if (typeof controlledStep === "string") return parseInt(controlledStep, 10);
+    // Handle unknown - try to convert to number
+    const num = Number(controlledStep);
+    return isNaN(num) ? undefined : num;
+  })();
+  const currentStep =
+    normalizedControlledStep !== undefined
+      ? normalizedControlledStep
+      : internalStep;
+  const totalSteps = steps.length;
+  const currentStepData = steps[currentStep];
+  const isFirstStep = currentStep === 0;
+  const isLastStep = currentStep === totalSteps - 1;
+
+  const goToStep = useCallback(
+    (stepIndex: number) => {
+      if (stepIndex < 0 || stepIndex >= totalSteps) return;
+
+      if (controlledStep === undefined) {
+        setInternalStep(stepIndex);
+      }
+      onStepChange?.(stepIndex);
+    },
+    [controlledStep, totalSteps, onStepChange],
+  );
+
+  const handleNext = () => {
+    // Validate current step if validator exists
+    if (currentStepData.isValid && !currentStepData.isValid()) {
+      return;
+    }
+
+    if (isLastStep) {
+      onComplete?.();
+    } else {
+      goToStep(currentStep + 1);
+    }
+  };
+
+  const handleBack = () => {
+    if (!isFirstStep && allowBack) {
+      goToStep(currentStep - 1);
+    }
+  };
+
+  return (
+    <Box className={cn("flex flex-col h-full", className)}>
+      {/* Progress indicator */}
+      {showProgress && (
+        <Box
+          border
+          className={cn(
+            "border-b-2 border-x-0 border-t-0 border-[var(--color-border)]",
+            compact ? "px-4 py-2" : "px-6 py-4",
+          )}
+        >
+          <div className="flex items-center gap-2">
+            {steps.map((step, index) => {
+              const isActive = index === currentStep;
+              const isCompleted = index < currentStep;
+              // Use id, tabId, or index as key; use title or name for display
+              const stepKey = step.id ?? step.tabId ?? `step-${index}`;
+              const stepTitle = step.title ?? step.name ?? `Step ${index + 1}`;
+
+              return (
+                <React.Fragment key={stepKey}>
+                  {/* Step indicator */}
+                  <button
+                    onClick={() => isCompleted && allowBack && goToStep(index)}
+                    disabled={!isCompleted || !allowBack}
+                    className={cn(
+                      "w-8 h-8 flex items-center justify-center text-sm font-bold transition-colors",
+                      "border-2 border-[var(--color-border)]",
+                      isActive &&
+                        "bg-[var(--color-primary)] text-[var(--color-primary-foreground)]",
+                      isCompleted &&
+                        "bg-[var(--color-primary)] text-[var(--color-primary-foreground)] cursor-pointer hover:bg-[var(--color-primary-hover)]",
+                      !isActive &&
+                        !isCompleted &&
+                        "bg-[var(--color-card)] text-[var(--color-foreground)]",
+                    )}
+                  >
+                    {isCompleted ? <Icon icon={Check} size="sm" /> : index + 1}
+                  </button>
+
+                  {/* Step title (on desktop) */}
+                  <div
+                    className={cn(
+                      "hidden md:block",
+                      isActive
+                        ? "text-[var(--color-foreground)] font-bold"
+                        : "text-[var(--color-muted-foreground)]",
+                    )}
+                  >
+                    <Typography
+                      variant="small"
+                      weight={isActive ? "bold" : "normal"}
+                    >
+                      {stepTitle}
+                    </Typography>
+                  </div>
+
+                  {/* Connector line */}
+                  {index < totalSteps - 1 && (
+                    <div
+                      className={cn(
+                        "flex-1 h-0.5",
+                        index < currentStep
+                          ? "bg-[var(--color-primary)]"
+                          : "bg-[var(--color-border)]",
+                      )}
+                    />
+                  )}
+                </React.Fragment>
+              );
+            })}
+          </div>
+        </Box>
+      )}
+
+      {/* Step header */}
+      {!compact && currentStepData && (
+        <Box
+          paddingX="lg"
+          paddingY="md"
+          border
+          className="border-b-2 border-x-0 border-t-0 border-[var(--color-border)]"
+        >
+          <Typography variant="h4" as="h2">
+            {currentStepData.title ??
+              currentStepData.name ??
+              `Step ${currentStep + 1}`}
+          </Typography>
+          {currentStepData.description && (
+            <Typography
+              variant="body2"
+              className="text-[var(--color-muted-foreground)] mt-1"
+            >
+              {currentStepData.description}
+            </Typography>
+          )}
+        </Box>
+      )}
+
+      {/* Step content */}
+      <div className={cn("flex-1 overflow-auto", compact ? "p-4" : "p-6")}>
+        {currentStepData?.content}
+      </div>
+
+      {/* Navigation buttons */}
+      <Box
+        border
+        className={cn(
+          "border-t-2 border-x-0 border-b-0 border-[var(--color-border)] flex justify-between",
+          compact ? "px-4 py-2" : "px-6 py-4",
+        )}
+      >
+        <Button
+          variant="secondary"
+          onClick={handleBack}
+          disabled={isFirstStep || !allowBack}
+        >
+          <Icon icon={ChevronLeft} size="sm" />
+          Back
+        </Button>
+
+        <div className="flex items-center gap-2">
+          <Typography
+            variant="caption"
+            className="text-[var(--color-muted-foreground)]"
+          >
+            Step {currentStep + 1} of {totalSteps}
+          </Typography>
+        </div>
+
+        <Button variant="primary" onClick={handleNext}>
+          {isLastStep ? "Complete" : "Next"}
+          {!isLastStep && <Icon icon={ChevronRight} size="sm" />}
+        </Button>
+      </Box>
+    </Box>
+  );
+};
+
+WizardContainer.displayName = "WizardContainer";
+
+export default WizardContainer;

package/shells/typescript-shell/packages/client/src/components/organisms/debug/RuntimeDebugger.css

@@ -0,0 +1,102 @@
+/**
+ * RuntimeDebugger CSS Styles
+ * 
+ * Minimal styles for the debug panel (uses component library for most styling).
+ */
+
+/* Main container */
+.runtime-debugger {
+    font-family: 'SF Mono', 'Monaco', 'Consolas', ui-monospace, monospace;
+    font-size: 12px;
+}
+
+.runtime-debugger--collapsed {
+    width: auto;
+    height: auto;
+}
+
+.runtime-debugger--expanded {
+    width: 450px;
+    max-height: 75vh;
+}
+
+/* Toggle button styling override */
+.runtime-debugger__toggle {
+    width: 48px !important;
+    height: 48px !important;
+    border-radius: 50% !important;
+    font-size: 20px !important;
+    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
+}
+
+.runtime-debugger__toggle:hover {
+    transform: scale(1.05);
+    box-shadow: 0 6px 20px rgba(0, 0, 0, 0.2);
+}
+
+/* Panel layout */
+.runtime-debugger__panel {
+    display: flex;
+    flex-direction: column;
+    max-height: 70vh;
+    overflow: hidden;
+}
+
+.runtime-debugger__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: 12px 16px;
+    border-bottom: 1px solid var(--gray-200, #e5e7eb);
+}
+
+.dark .runtime-debugger__header {
+    border-color: var(--gray-700, #374151);
+}
+
+.runtime-debugger__content {
+    flex: 1;
+    overflow-y: auto;
+    padding: 12px;
+}
+
+.runtime-debugger__footer {
+    padding: 8px 16px;
+    border-top: 1px solid var(--gray-200, #e5e7eb);
+    text-align: center;
+}
+
+.dark .runtime-debugger__footer {
+    border-color: var(--gray-700, #374151);
+}
+
+/* Tab content padding */
+.debug-tab {
+    padding: 4px 0;
+}
+
+/* Scrollbar */
+.runtime-debugger__content::-webkit-scrollbar {
+    width: 6px;
+}
+
+.runtime-debugger__content::-webkit-scrollbar-track {
+    background: transparent;
+}
+
+.runtime-debugger__content::-webkit-scrollbar-thumb {
+    background: rgba(0, 0, 0, 0.1);
+    border-radius: 3px;
+}
+
+.dark .runtime-debugger__content::-webkit-scrollbar-thumb {
+    background: rgba(255, 255, 255, 0.1);
+}
+
+.runtime-debugger__content::-webkit-scrollbar-thumb:hover {
+    background: rgba(0, 0, 0, 0.2);
+}
+
+.dark .runtime-debugger__content::-webkit-scrollbar-thumb:hover {
+    background: rgba(255, 255, 255, 0.2);
+}

package/shells/typescript-shell/packages/client/src/components/organisms/debug/RuntimeDebugger.tsx

@@ -0,0 +1,176 @@
+/**
+ * RuntimeDebugger - Main debug panel for KFlow applications
+ * 
+ * Press backtick (`) to toggle. Displays traits, ticks, entities, events, and guards.
+ * Uses existing component library atoms/molecules.
+ * 
+ * @packageDocumentation
+ */
+
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+import { useDebugData } from './hooks/useDebugData';
+import { onDebugToggle, isDebugEnabled } from '../../../lib/debugUtils';
+import { Tabs, type TabItem } from '../../molecules/Tabs';
+import { Button } from '../../atoms/Button';
+import { Card } from '../../atoms/Card';
+import { Badge } from '../../atoms/Badge';
+import { Typography } from '../../atoms/Typography';
+import { TraitsTab } from './tabs/TraitsTab';
+import { TicksTab } from './tabs/TicksTab';
+import { EntitiesTab } from './tabs/EntitiesTab';
+import { EventFlowTab } from './tabs/EventFlowTab';
+import { GuardsPanel } from './tabs/GuardsPanel';
+import './RuntimeDebugger.css';
+
+export interface RuntimeDebuggerProps {
+    /** Initial position */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Initial collapsed state */
+    defaultCollapsed?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+
+export function RuntimeDebugger({
+    position = 'bottom-right',
+    defaultCollapsed = true,
+    className,
+}: RuntimeDebuggerProps) {
+    const [isCollapsed, setIsCollapsed] = React.useState(defaultCollapsed);
+    const [isVisible, setIsVisible] = React.useState(isDebugEnabled());
+
+    const debugData = useDebugData();
+
+    // Listen for keyboard toggle
+    React.useEffect(() => {
+        return onDebugToggle((enabled) => {
+            setIsVisible(enabled);
+            if (enabled) {
+                setIsCollapsed(false);
+            }
+        });
+    }, []);
+
+    // Keyboard shortcut to toggle collapse
+    React.useEffect(() => {
+        const handleKeyDown = (e: KeyboardEvent) => {
+            if (e.key === '`' && isVisible) {
+                // Don't toggle if typing in input
+                const target = e.target as HTMLElement;
+                if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA') return;
+                setIsCollapsed(prev => !prev);
+            }
+        };
+
+        window.addEventListener('keydown', handleKeyDown);
+        return () => window.removeEventListener('keydown', handleKeyDown);
+    }, [isVisible]);
+
+    if (!isVisible) {
+        return null;
+    }
+
+    const positionClasses = {
+        'bottom-right': 'bottom-4 right-4',
+        'bottom-left': 'bottom-4 left-4',
+        'top-right': 'top-4 right-4',
+        'top-left': 'top-4 left-4',
+    };
+
+    // Build tab items using existing Tabs molecule
+    const tabItems: TabItem[] = [
+        {
+            id: 'traits',
+            label: 'Traits',
+            badge: debugData.traits.length || undefined,
+            content: <TraitsTab traits={debugData.traits} />,
+        },
+        {
+            id: 'ticks',
+            label: 'Ticks',
+            badge: debugData.ticks.filter((t: { active: boolean }) => t.active).length || undefined,
+            content: <TicksTab ticks={debugData.ticks} />,
+        },
+        {
+            id: 'entities',
+            label: 'Entities',
+            badge: debugData.entitySnapshot?.runtime.length || undefined,
+            content: <EntitiesTab snapshot={debugData.entitySnapshot} />,
+        },
+        {
+            id: 'events',
+            label: 'Events',
+            badge: debugData.events.length > 0 ? debugData.events.length : undefined,
+            content: <EventFlowTab events={debugData.events} />,
+        },
+        {
+            id: 'guards',
+            label: 'Guards',
+            badge: debugData.guards.filter((g: { result: boolean }) => !g.result).length || undefined,
+            content: <GuardsPanel guards={debugData.guards} />,
+        },
+    ];
+
+    return (
+        <div
+            className={cn(
+                'runtime-debugger',
+                'fixed z-[9999]',
+                positionClasses[position],
+                isCollapsed ? 'runtime-debugger--collapsed' : 'runtime-debugger--expanded',
+                className
+            )}
+            data-testid={isCollapsed ? 'debugger-collapsed' : 'debugger-expanded'}
+        >
+            {isCollapsed ? (
+                <Button
+                    onClick={() => setIsCollapsed(false)}
+                    variant="secondary"
+                    size="sm"
+                    className="runtime-debugger__toggle"
+                    title="Open Debugger (`)"
+                >
+                    🔍
+                </Button>
+            ) : (
+                <Card className="runtime-debugger__panel">
+                    {/* Header */}
+                    <div className="runtime-debugger__header">
+                        <div className="flex items-center gap-2">
+                            <span className="text-lg">🔍</span>
+                            <Typography variant="h6">KFlow Debugger</Typography>
+                            <Badge variant="info" size="sm">Runtime</Badge>
+                        </div>
+                        <Button
+                            onClick={() => setIsCollapsed(true)}
+                            variant="ghost"
+                            size="sm"
+                            title="Close (`)"
+                        >
+                            ✕
+                        </Button>
+                    </div>
+
+                    {/* Tabs - using existing Tabs molecule */}
+                    <div className="runtime-debugger__content">
+                        <Tabs
+                            items={tabItems}
+                            variant="pills"
+                            className="runtime-debugger__tabs"
+                        />
+                    </div>
+
+                    {/* Footer */}
+                    <div className="runtime-debugger__footer">
+                        <Typography variant="small" className="text-gray-500">
+                            Press ` to toggle
+                        </Typography>
+                    </div>
+                </Card>
+            )}
+        </div>
+    );
+}
+
+RuntimeDebugger.displayName = 'RuntimeDebugger';