@almadar/cli 0.3.1 → 0.3.3

package/shells/typescript-shell/packages/client/src/components/molecules/WizardNavigation.tsx

@@ -0,0 +1,166 @@
+/**
+ * WizardNavigation Component
+ *
+ * Navigation buttons for multi-step wizards.
+ * Includes Back, Next, and Complete buttons with proper state handling.
+ *
+ * Emits events via useEventBus for trait integration.
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+import { ChevronLeft, ChevronRight } 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";
+import { useEventBus } from "../../hooks/useEventBus";
+
+/**
+ * Safe event bus hook that works outside EventBusProvider context.
+ * Returns a no-op emit function if not in EventBusProvider context.
+ */
+function useSafeEventBus() {
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    return useEventBus();
+  } catch {
+    // Outside EventBusProvider context - return no-op
+    return { emit: () => {}, on: () => () => {}, once: () => {} };
+  }
+}
+
+export interface WizardNavigationProps {
+  /** Current step index (0-based) */
+  currentStep: number;
+  /** Total number of steps */
+  totalSteps: number;
+  /** Whether the current step is valid (enables Next/Complete) */
+  isValid?: boolean;
+  /** Show the Back button */
+  showBack?: boolean;
+  /** Show the Next button */
+  showNext?: boolean;
+  /** Show the Complete button (on last step) */
+  showComplete?: boolean;
+  /** Custom label for Back button */
+  backLabel?: string;
+  /** Custom label for Next button */
+  nextLabel?: string;
+  /** Custom label for Complete button */
+  completeLabel?: string;
+  /** Event to emit on Back click */
+  onBack?: string;
+  /** Event to emit on Next click */
+  onNext?: string;
+  /** Event to emit on Complete click */
+  onComplete?: string;
+  /** Direct callback for Back (alternative to event) */
+  onBackClick?: () => void;
+  /** Direct callback for Next (alternative to event) */
+  onNextClick?: () => void;
+  /** Direct callback for Complete (alternative to event) */
+  onCompleteClick?: () => void;
+  /** Compact mode (smaller padding) */
+  compact?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * WizardNavigation - Wizard navigation buttons
+ */
+export const WizardNavigation: React.FC<WizardNavigationProps> = ({
+  currentStep,
+  totalSteps,
+  isValid = true,
+  showBack = true,
+  showNext = true,
+  showComplete = true,
+  backLabel = "Back",
+  nextLabel = "Next",
+  completeLabel = "Complete",
+  onBack = "WIZARD_BACK",
+  onNext = "WIZARD_NEXT",
+  onComplete = "WIZARD_COMPLETE",
+  onBackClick,
+  onNextClick,
+  onCompleteClick,
+  compact = false,
+  className,
+}) => {
+  const eventBus = useSafeEventBus();
+
+  const isFirstStep = currentStep === 0;
+  const isLastStep = currentStep === totalSteps - 1;
+
+  const handleBack = () => {
+    if (onBackClick) {
+      onBackClick();
+    } else {
+      eventBus.emit(`UI:${onBack}`, { currentStep, totalSteps });
+    }
+  };
+
+  const handleNext = () => {
+    if (onNextClick) {
+      onNextClick();
+    } else {
+      eventBus.emit(`UI:${onNext}`, { currentStep, totalSteps });
+    }
+  };
+
+  const handleComplete = () => {
+    if (onCompleteClick) {
+      onCompleteClick();
+    } else {
+      eventBus.emit(`UI:${onComplete}`, { currentStep, totalSteps });
+    }
+  };
+
+  return (
+    <Box
+      border
+      className={cn(
+        "border-t-2 border-x-0 border-b-0 border-[var(--color-border)] flex justify-between items-center",
+        compact ? "px-4 py-2" : "px-6 py-4",
+        className,
+      )}
+    >
+      {/* Back button */}
+      {showBack ? (
+        <Button variant="secondary" onClick={handleBack} disabled={isFirstStep}>
+          <Icon icon={ChevronLeft} size="sm" />
+          {backLabel}
+        </Button>
+      ) : (
+        <div /> // Spacer for flex justify-between
+      )}
+
+      {/* Step counter */}
+      <div className="flex items-center gap-2">
+        <Typography variant="caption" className="text-neutral-500">
+          Step {currentStep + 1} of {totalSteps}
+        </Typography>
+      </div>
+
+      {/* Next/Complete button */}
+      {isLastStep && showComplete ? (
+        <Button variant="primary" onClick={handleComplete} disabled={!isValid}>
+          {completeLabel}
+        </Button>
+      ) : showNext ? (
+        <Button variant="primary" onClick={handleNext} disabled={!isValid}>
+          {nextLabel}
+          <Icon icon={ChevronRight} size="sm" />
+        </Button>
+      ) : (
+        <div /> // Spacer for flex justify-between
+      )}
+    </Box>
+  );
+};
+
+WizardNavigation.displayName = "WizardNavigation";
+
+export default WizardNavigation;

package/shells/typescript-shell/packages/client/src/components/molecules/WizardProgress.tsx

@@ -0,0 +1,140 @@
+/**
+ * WizardProgress Component
+ *
+ * Step progress indicator for multi-step wizards.
+ * Shows current step, completed steps, and allows navigation to completed steps.
+ *
+ * Uses wireframe theme styling (high contrast, sharp edges).
+ */
+import React from "react";
+import { Check } from "lucide-react";
+import { Typography } from "../atoms/Typography";
+import { Box } from "../atoms/Box";
+import { Icon } from "../atoms/Icon";
+import { cn } from "../../lib/cn";
+
+/**
+ * Step info needed by WizardProgress.
+ * Compatible with WizardContainer's WizardStep (subset of fields).
+ */
+export interface WizardProgressStep {
+  /** Step identifier */
+  id: string;
+  /** Step title */
+  title: string;
+  /** Step description (optional) */
+  description?: string;
+}
+
+export interface WizardProgressProps {
+  /** Step definitions (compatible with WizardContainer's WizardStep) */
+  steps: WizardProgressStep[];
+  /** Current step index (0-based) */
+  currentStep: number;
+  /** Callback when a completed step is clicked */
+  onStepClick?: (stepIndex: number) => void;
+  /** Allow clicking on completed steps to navigate back */
+  allowNavigation?: boolean;
+  /** Compact mode (smaller, no titles) */
+  compact?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * WizardProgress - Step progress indicator
+ */
+export const WizardProgress: React.FC<WizardProgressProps> = ({
+  steps,
+  currentStep,
+  onStepClick,
+  allowNavigation = true,
+  compact = false,
+  className,
+}) => {
+  const totalSteps = steps.length;
+
+  const handleStepClick = (index: number) => {
+    const isCompleted = index < currentStep;
+    if (isCompleted && allowNavigation && onStepClick) {
+      onStepClick(index);
+    }
+  };
+
+  return (
+    <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",
+        className,
+      )}
+    >
+      <div className="flex items-center gap-2">
+        {steps.map((step, index) => {
+          const isActive = index === currentStep;
+          const isCompleted = index < currentStep;
+
+          return (
+            <React.Fragment key={step.id}>
+              {/* Step indicator */}
+              <button
+                onClick={() => handleStepClick(index)}
+                disabled={!isCompleted || !allowNavigation}
+                className={cn(
+                  "flex items-center justify-center text-sm font-bold transition-colors",
+                  "border-2 border-[var(--color-border)]",
+                  compact ? "w-6 h-6" : "w-8 h-8",
+                  isActive &&
+                    "bg-[var(--color-foreground)] text-[var(--color-background)]",
+                  isCompleted &&
+                    "bg-[var(--color-foreground)] text-[var(--color-background)] cursor-pointer hover:bg-[var(--color-muted-foreground)]",
+                  !isActive &&
+                    !isCompleted &&
+                    "bg-[var(--color-card)] text-[var(--color-foreground)]",
+                )}
+              >
+                {isCompleted ? <Icon icon={Check} size="sm" /> : index + 1}
+              </button>
+
+              {/* Step title (on desktop, not in compact mode) */}
+              {!compact && (
+                <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"}
+                  >
+                    {step.title}
+                  </Typography>
+                </div>
+              )}
+
+              {/* Connector line */}
+              {index < totalSteps - 1 && (
+                <div
+                  className={cn(
+                    "flex-1 h-0.5",
+                    index < currentStep
+                      ? "bg-[var(--color-foreground)]"
+                      : "bg-[var(--color-muted)]",
+                  )}
+                />
+              )}
+            </React.Fragment>
+          );
+        })}
+      </div>
+    </Box>
+  );
+};
+
+WizardProgress.displayName = "WizardProgress";
+
+export default WizardProgress;

package/shells/typescript-shell/packages/client/src/components/molecules/game/ActionButtons.tsx

@@ -0,0 +1,148 @@
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+import { ControlButton } from '../../atoms/game/ControlButton';
+
+export interface ActionButtonConfig {
+  /** Unique identifier */
+  id: string;
+  /** Display label */
+  label?: string;
+  /** Icon component or emoji */
+  icon?: React.ReactNode;
+  /** Button variant */
+  variant?: 'primary' | 'secondary' | 'ghost' | string;
+}
+
+export interface ActionButtonsProps {
+  /** Button configurations */
+  buttons: ActionButtonConfig[];
+  /** Called when a button is pressed/released */
+  onAction: (id: string, pressed: boolean) => void;
+  /** Layout variant */
+  layout?: 'horizontal' | 'vertical' | 'diamond';
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Additional CSS classes */
+  className?: string;
+  /** Disabled state */
+  disabled?: boolean;
+}
+
+const sizeMap = {
+  sm: 'sm' as const,
+  md: 'md' as const,
+  lg: 'lg' as const,
+};
+
+const layoutMap = {
+  horizontal: 'flex flex-row gap-2',
+  vertical: 'flex flex-col gap-2',
+  diamond: 'grid grid-cols-3 gap-1',
+};
+
+export function ActionButtons({
+  buttons,
+  onAction,
+  layout = 'horizontal',
+  size = 'md',
+  className,
+  disabled,
+}: ActionButtonsProps) {
+  const [activeButtons, setActiveButtons] = React.useState<Set<string>>(new Set());
+
+  const handlePress = React.useCallback(
+    (id: string) => {
+      setActiveButtons((prev) => new Set(prev).add(id));
+      onAction(id, true);
+    },
+    [onAction]
+  );
+
+  const handleRelease = React.useCallback(
+    (id: string) => {
+      setActiveButtons((prev) => {
+        const next = new Set(prev);
+        next.delete(id);
+        return next;
+      });
+      onAction(id, false);
+    },
+    [onAction]
+  );
+
+  // Diamond layout: special positioning for 4 buttons (A, B, X, Y style)
+  if (layout === 'diamond' && buttons.length === 4) {
+    const [top, right, bottom, left] = buttons;
+    return (
+      <div className={cn(layoutMap[layout], className)}>
+        <div />
+        <ControlButton
+          icon={top.icon}
+          label={top.label}
+          size={sizeMap[size]}
+          variant={top.variant}
+          pressed={activeButtons.has(top.id)}
+          onPress={() => handlePress(top.id)}
+          onRelease={() => handleRelease(top.id)}
+          disabled={disabled}
+        />
+        <div />
+
+        <ControlButton
+          icon={left.icon}
+          label={left.label}
+          size={sizeMap[size]}
+          variant={left.variant}
+          pressed={activeButtons.has(left.id)}
+          onPress={() => handlePress(left.id)}
+          onRelease={() => handleRelease(left.id)}
+          disabled={disabled}
+        />
+        <div />
+        <ControlButton
+          icon={right.icon}
+          label={right.label}
+          size={sizeMap[size]}
+          variant={right.variant}
+          pressed={activeButtons.has(right.id)}
+          onPress={() => handlePress(right.id)}
+          onRelease={() => handleRelease(right.id)}
+          disabled={disabled}
+        />
+
+        <div />
+        <ControlButton
+          icon={bottom.icon}
+          label={bottom.label}
+          size={sizeMap[size]}
+          variant={bottom.variant}
+          pressed={activeButtons.has(bottom.id)}
+          onPress={() => handlePress(bottom.id)}
+          onRelease={() => handleRelease(bottom.id)}
+          disabled={disabled}
+        />
+        <div />
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn(layoutMap[layout], className)}>
+      {buttons.map((button) => (
+        <ControlButton
+          key={button.id}
+          icon={button.icon}
+          label={button.label}
+          size={sizeMap[size]}
+          variant={button.variant}
+          pressed={activeButtons.has(button.id)}
+          onPress={() => handlePress(button.id)}
+          onRelease={() => handleRelease(button.id)}
+          disabled={disabled}
+        />
+      ))}
+    </div>
+  );
+}
+
+ActionButtons.displayName = 'ActionButtons';

package/shells/typescript-shell/packages/client/src/components/molecules/game/DPad.tsx

@@ -0,0 +1,98 @@
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+import { ControlButton } from '../../atoms/game/ControlButton';
+
+export type DPadDirection = 'up' | 'down' | 'left' | 'right';
+
+export interface DPadProps {
+  /** Called when a direction is pressed/released */
+  onDirection: (direction: DPadDirection, pressed: boolean) => void;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Whether to include diagonal buttons */
+  includeDiagonals?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+  /** Disabled state */
+  disabled?: boolean;
+}
+
+const sizeMap = {
+  sm: { button: 'sm' as const, gap: 'gap-0.5', container: 'w-28' },
+  md: { button: 'md' as const, gap: 'gap-1', container: 'w-40' },
+  lg: { button: 'lg' as const, gap: 'gap-1.5', container: 'w-52' },
+};
+
+const arrowIcons: Record<DPadDirection, React.ReactNode> = {
+  up: '▲',
+  down: '▼',
+  left: '◀',
+  right: '▶',
+};
+
+export function DPad({
+  onDirection,
+  size = 'md',
+  includeDiagonals = false,
+  className,
+  disabled,
+}: DPadProps) {
+  const sizes = sizeMap[size];
+  const [activeDirections, setActiveDirections] = React.useState<Set<DPadDirection>>(new Set());
+
+  const handlePress = React.useCallback(
+    (direction: DPadDirection) => {
+      setActiveDirections((prev) => new Set(prev).add(direction));
+      onDirection(direction, true);
+    },
+    [onDirection]
+  );
+
+  const handleRelease = React.useCallback(
+    (direction: DPadDirection) => {
+      setActiveDirections((prev) => {
+        const next = new Set(prev);
+        next.delete(direction);
+        return next;
+      });
+      onDirection(direction, false);
+    },
+    [onDirection]
+  );
+
+  const createButton = (direction: DPadDirection) => (
+    <ControlButton
+      key={direction}
+      icon={arrowIcons[direction]}
+      size={sizes.button}
+      variant="secondary"
+      pressed={activeDirections.has(direction)}
+      onPress={() => handlePress(direction)}
+      onRelease={() => handleRelease(direction)}
+      disabled={disabled}
+    />
+  );
+
+  return (
+    <div className={cn('inline-grid grid-cols-3', sizes.gap, sizes.container, className)}>
+      {/* Row 1: Empty, Up, Empty */}
+      <div />
+      {createButton('up')}
+      <div />
+
+      {/* Row 2: Left, Center, Right */}
+      {createButton('left')}
+      <div className="flex items-center justify-center">
+        <div className="w-6 h-6 rounded-full bg-gray-700 border-2 border-gray-600" />
+      </div>
+      {createButton('right')}
+
+      {/* Row 3: Empty, Down, Empty */}
+      <div />
+      {createButton('down')}
+      <div />
+    </div>
+  );
+}
+
+DPad.displayName = 'DPad';

package/shells/typescript-shell/packages/client/src/components/molecules/game/StatBadge.tsx

@@ -0,0 +1,104 @@
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+import { HealthBar } from '../../atoms/game/HealthBar';
+import { ScoreDisplay } from '../../atoms/game/ScoreDisplay';
+
+export interface StatBadgeProps {
+  /** Stat label */
+  label: string;
+  /** Current value (defaults to 0 if not provided) */
+  value?: number | string;
+  /** Maximum value (for bar/hearts format) */
+  max?: number;
+  /** Data source entity name (for schema config) */
+  source?: string;
+  /** Field name in the source (for schema config) */
+  field?: string;
+  /** Display format */
+  format?: 'number' | 'hearts' | 'bar' | 'text' | string;
+  /** Icon component or emoji */
+  icon?: React.ReactNode;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg' | string;
+  /** Visual variant */
+  variant?: 'default' | 'primary' | 'success' | 'warning' | 'danger' | string;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+const sizeMap = {
+  sm: 'text-xs px-2 py-1',
+  md: 'text-sm px-3 py-1.5',
+  lg: 'text-base px-4 py-2',
+};
+
+const variantMap = {
+  default: 'bg-gray-800/80 border-gray-700',
+  primary: 'bg-blue-900/80 border-blue-700',
+  success: 'bg-green-900/80 border-green-700',
+  warning: 'bg-yellow-900/80 border-yellow-700',
+  danger: 'bg-red-900/80 border-red-700',
+};
+
+export function StatBadge({
+  label,
+  value = 0,
+  max,
+  format = 'number',
+  icon,
+  size = 'md',
+  variant = 'default',
+  className,
+  // Ignored config props (used for schema binding)
+  source: _source,
+  field: _field,
+}: StatBadgeProps) {
+  const numValue = typeof value === 'number' ? value : parseInt(String(value), 10) || 0;
+
+  return (
+    <div
+      className={cn(
+        'inline-flex items-center gap-2 rounded-lg border backdrop-blur-sm',
+        sizeMap[size as keyof typeof sizeMap] ?? sizeMap.md,
+        variantMap[variant as keyof typeof variantMap] ?? variantMap.default,
+        className
+      )}
+    >
+      {icon && <span className="flex-shrink-0 text-lg">{icon}</span>}
+      
+      <span className="text-gray-400 font-medium">{label}</span>
+      
+      {format === 'hearts' && max && (
+        <HealthBar
+          current={numValue}
+          max={max}
+          format="hearts"
+          size={size === 'lg' ? 'md' : 'sm'}
+        />
+      )}
+      
+      {format === 'bar' && max && (
+        <HealthBar
+          current={numValue}
+          max={max}
+          format="bar"
+          size={size === 'lg' ? 'md' : 'sm'}
+        />
+      )}
+      
+      {format === 'number' && (
+        <ScoreDisplay
+          value={numValue}
+          size={size === 'lg' ? 'md' : 'sm'}
+          animated
+        />
+      )}
+      
+      {format === 'text' && (
+        <span className="font-bold text-white">{value}</span>
+      )}
+    </div>
+  );
+}
+
+StatBadge.displayName = 'StatBadge';

package/shells/typescript-shell/packages/client/src/components/molecules/game/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Game Molecule Components
+ *
+ * Composed components for game UI patterns.
+ *
+ * @packageDocumentation
+ */
+
+export { DPad, type DPadProps, type DPadDirection } from './DPad';
+export { ActionButtons, type ActionButtonsProps, type ActionButtonConfig } from './ActionButtons';
+export { StatBadge, type StatBadgeProps } from './StatBadge';