@almadar/cli 0.3.2 → 0.3.3

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

@@ -0,0 +1,226 @@
+/**
+ * ButtonGroup Molecule Component
+ *
+ * A component for grouping buttons together with connected styling.
+ * Supports both children-based and form-actions pattern (primary/secondary) usage.
+ * Uses Button atoms.
+ */
+
+import React from 'react';
+import { cn } from '../../lib/cn';
+import { Button } from '../atoms';
+import { useNavigate } from 'react-router-dom';
+import { useEventBus } from '../../hooks/useEventBus';
+
+export type ButtonGroupVariant = 'default' | 'segmented' | 'toggle';
+
+/** Action button config for form-actions pattern */
+export interface ActionButton {
+  label: string;
+  /** Action type - 'submit' renders as submit button, others render as button */
+  actionType?: string;
+  event?: string;
+  navigatesTo?: string;
+  /** Button variant - matches Button component variants. Accepts string for schema compatibility. */
+  variant?: string;
+}
+
+/** Filter definition for filter-group pattern */
+export interface FilterDefinition {
+  field: string;
+  label: string;
+  /** Filter type (checkbox, select, etc.) */
+  type?: 'checkbox' | 'select' | 'toggle';
+  /** Options for select filters */
+  options?: readonly string[];
+}
+
+export interface ButtonGroupProps {
+  /**
+   * Button group content (Button components) - use this OR primary/secondary
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Primary action button config (for form-actions pattern)
+   * Accepts Readonly for compatibility with generated const objects
+   */
+  primary?: Readonly<ActionButton>;
+
+  /**
+   * Secondary action buttons config (for form-actions pattern)
+   * Accepts readonly array for compatibility with generated const arrays
+   */
+  secondary?: readonly Readonly<ActionButton>[];
+
+  /**
+   * Visual variant
+   * @default 'default'
+   */
+  variant?: ButtonGroupVariant;
+
+  /**
+   * Orientation
+   * @default 'horizontal'
+   */
+  orientation?: 'horizontal' | 'vertical';
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Entity type for filter-group pattern (schema metadata)
+   */
+  entity?: string;
+
+  /**
+   * Filter definitions for filter-group pattern
+   */
+  filters?: readonly FilterDefinition[];
+}
+
+/**
+ * Safe navigation hook that works outside Router context.
+ * Returns a no-op function if not in Router context.
+ */
+function useSafeNavigate(): (to: string) => void {
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const navigate = useNavigate();
+    return navigate;
+  } catch {
+    // Outside Router context - return no-op
+    return () => {};
+  }
+}
+
+/**
+ * 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 const ButtonGroup: React.FC<ButtonGroupProps> = ({
+  children,
+  primary,
+  secondary,
+  variant = 'default',
+  orientation = 'horizontal',
+  className,
+  // Filter-group pattern props (entity and filters are used for schema-driven filtering)
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  entity: _entity,
+  filters,
+}) => {
+  const navigate = useSafeNavigate();
+  const eventBus = useSafeEventBus();
+  const variantClasses = {
+    default: 'gap-0',
+    segmented: 'gap-0 [&>button]:rounded-none [&>button:first-child]:rounded-l-lg [&>button:last-child]:rounded-r-lg [&>button:not(:first-child)]:border-l-0',
+    toggle: 'gap-0 [&>button]:rounded-none [&>button:first-child]:rounded-l-lg [&>button:last-child]:rounded-r-lg [&>button:not(:first-child)]:border-l-0',
+  };
+
+  const orientationClasses = {
+    horizontal: 'flex-row',
+    vertical: 'flex-col [&>button:first-child]:rounded-t-lg [&>button:last-child]:rounded-b-lg [&>button:not(:first-child)]:border-t-0 [&>button:not(:first-child)]:border-l',
+  };
+
+  // Handle action button click
+  const handleActionClick = (action: ActionButton) => {
+    // Emit event via event bus if specified
+    if (action.event) {
+      eventBus.emit('UI:DISPATCH', { event: action.event });
+    }
+    // Navigate if specified
+    if (action.navigatesTo) {
+      navigate(action.navigatesTo);
+    }
+  };
+
+  // Button variant type for type assertions
+  type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger' | 'success' | 'warning';
+
+  // Render buttons from primary/secondary config when no children
+  const renderFormActions = () => {
+    const buttons: React.ReactNode[] = [];
+
+    // Render secondary buttons first (typically on the left)
+    if (secondary) {
+      secondary.forEach((action, index) => {
+        buttons.push(
+          <Button
+            key={`secondary-${index}`}
+            type={action.actionType === 'submit' ? 'submit' : 'button'}
+            variant={(action.variant || 'ghost') as ButtonVariant}
+            onClick={() => handleActionClick(action)}
+          >
+            {action.label}
+          </Button>
+        );
+      });
+    }
+
+    // Render primary button (typically on the right)
+    if (primary) {
+      const isSubmit = primary.actionType === 'submit';
+      buttons.push(
+        <Button
+          key="primary"
+          type={isSubmit ? 'submit' : 'button'}
+          variant={(primary.variant || 'primary') as ButtonVariant}
+          onClick={() => handleActionClick(primary)}
+          data-testid={isSubmit ? 'form-submit' : undefined}
+        >
+          {primary.label}
+        </Button>
+      );
+    }
+
+    return buttons;
+  };
+
+  // Render filter buttons from filters config (filter-group pattern)
+  const renderFilters = () => {
+    if (!filters || filters.length === 0) return null;
+
+    return filters.map((filter, index) => (
+      <Button
+        key={`filter-${filter.field}-${index}`}
+        variant="ghost"
+        onClick={() => {
+          // Filter click handling would be connected to state management
+          console.log(`Filter clicked: ${filter.field}`);
+        }}
+      >
+        {filter.label}
+      </Button>
+    ));
+  };
+
+  return (
+    <div
+      className={cn(
+        'inline-flex gap-2',
+        variantClasses[variant],
+        orientationClasses[orientation],
+        className
+      )}
+      role="group"
+    >
+      {children || renderFilters() || renderFormActions()}
+    </div>
+  );
+};
+
+ButtonGroup.displayName = 'ButtonGroup';
+

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

@@ -0,0 +1,135 @@
+/**
+ * Card Component
+ *
+ * A generic card container for displaying content with optional title,
+ * subtitle, and action buttons.
+ *
+ * @generated by Almadar Compiler
+ */
+
+import React from "react";
+
+export interface CardAction {
+  label: string;
+  onClick: () => void;
+  variant?: "default" | "primary" | "danger";
+  icon?: string;
+  disabled?: boolean;
+}
+
+export interface CardProps {
+  /** Card title */
+  title?: string;
+  /** Card subtitle or description */
+  subtitle?: string;
+  /** Image URL to display at top of card */
+  image?: string;
+  /** Action buttons to display in card footer */
+  actions?: CardAction[];
+  /** Card content */
+  children?: React.ReactNode;
+  /** Click handler for the entire card */
+  onClick?: () => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * Card component for displaying content in a contained box
+ */
+export function Card({
+  title,
+  subtitle,
+  image,
+  actions,
+  children,
+  onClick,
+  className = "",
+}: CardProps) {
+  const isClickable = !!onClick;
+
+  return (
+    <div
+      className={`
+        bg-[var(--color-card)]
+        border border-[var(--color-border)]
+        rounded-[var(--radius-md)] shadow-[var(--shadow-sm)]
+        ${isClickable ? "cursor-pointer hover:shadow-[var(--shadow-hover)] transition-shadow" : ""}
+        ${className}
+      `}
+      onClick={onClick}
+      role={isClickable ? "button" : undefined}
+      tabIndex={isClickable ? 0 : undefined}
+      onKeyDown={
+        isClickable ? (e) => e.key === "Enter" && onClick?.() : undefined
+      }
+    >
+      {/* Image */}
+      {image && (
+        <div className="aspect-video w-full overflow-hidden rounded-t-lg">
+          <img
+            src={image}
+            alt={title || "Card image"}
+            className="w-full h-full object-cover"
+          />
+        </div>
+      )}
+
+      {/* Content */}
+      <div className="p-4">
+        {/* Header */}
+        {(title || subtitle) && (
+          <div className="mb-3">
+            {title && (
+              <h3 className="text-lg font-semibold text-[var(--color-card-foreground)]">
+                {title}
+              </h3>
+            )}
+            {subtitle && (
+              <p className="text-sm text-[var(--color-muted-foreground)] mt-1">
+                {subtitle}
+              </p>
+            )}
+          </div>
+        )}
+
+        {/* Children */}
+        {children && (
+          <div className="text-[var(--color-card-foreground)]">{children}</div>
+        )}
+
+        {/* Actions */}
+        {actions && actions.length > 0 && (
+          <div className="flex flex-wrap gap-2 mt-4 pt-4 border-t border-[var(--color-border)]">
+            {actions.map((action, index) => (
+              <button
+                key={index}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  action.onClick();
+                }}
+                disabled={action.disabled}
+                className={`
+                  px-3 py-1.5 text-sm font-medium rounded-[var(--radius-sm)]
+                  transition-colors
+                  ${
+                    action.variant === "primary"
+                      ? "bg-[var(--color-primary)] text-[var(--color-primary-foreground)] hover:bg-[var(--color-primary-hover)] disabled:opacity-50"
+                      : action.variant === "danger"
+                        ? "bg-[var(--color-error)] text-[var(--color-error-foreground)] hover:opacity-90 disabled:opacity-50"
+                        : "bg-[var(--color-muted)] text-[var(--color-foreground)] hover:bg-[var(--color-surface-hover)]"
+                  }
+                  disabled:cursor-not-allowed
+                `}
+              >
+                {action.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default Card;

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

@@ -0,0 +1,78 @@
+/**
+ * Container Component
+ * 
+ * A max-width wrapper that centers content horizontally.
+ * Essential for controlling page width and maintaining consistent margins.
+ */
+import React from 'react';
+import { cn } from '../../lib/cn';
+
+export type ContainerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+export type ContainerPadding = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface ContainerProps {
+  /** Maximum width */
+  size?: ContainerSize;
+  /** Alias for size (pattern compatibility) */
+  maxWidth?: ContainerSize;
+  /** Horizontal padding */
+  padding?: ContainerPadding;
+  /** Center horizontally */
+  center?: boolean;
+  /** Custom class name */
+  className?: string;
+  /** Children elements */
+  children?: React.ReactNode;
+  /** HTML element to render as */
+  as?: React.ElementType;
+}
+
+const sizeStyles: Record<ContainerSize, string> = {
+  xs: 'max-w-xs',        // 320px
+  sm: 'max-w-screen-sm', // 640px
+  md: 'max-w-screen-md', // 768px
+  lg: 'max-w-screen-lg', // 1024px
+  xl: 'max-w-screen-xl', // 1280px
+  '2xl': 'max-w-screen-2xl', // 1536px
+  full: 'max-w-full',
+};
+
+const paddingStyles: Record<ContainerPadding, string> = {
+  none: 'px-0',
+  sm: 'px-4',
+  md: 'px-6',
+  lg: 'px-8',
+  xl: 'px-12',
+};
+
+/**
+ * Container - Centers and constrains content width
+ */
+export const Container: React.FC<ContainerProps> = ({
+  size,
+  maxWidth,
+  padding = 'md',
+  center = true,
+  className,
+  children,
+  as: Component = 'div',
+}) => {
+  // Use maxWidth if provided, otherwise fall back to size, then default to 'lg'
+  const resolvedSize = maxWidth ?? size ?? 'lg';
+  return (
+    <Component
+      className={cn(
+        'w-full',
+        sizeStyles[resolvedSize],
+        paddingStyles[padding],
+        center && 'mx-auto',
+        className
+      )}
+    >
+      {children}
+    </Component>
+  );
+};
+
+export default Container;
+

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

@@ -0,0 +1,254 @@
+/**
+ * Drawer Molecule Component
+ *
+ * A slide-in drawer component for displaying secondary content.
+ * Used by the UI Slot system for render_ui effects targeting the drawer slot.
+ *
+ * Features:
+ * - Left/right positioning
+ * - Configurable width
+ * - Overlay backdrop
+ * - Click-outside to dismiss
+ * - Slide animation
+ * - Escape key to close
+ *
+ * @packageDocumentation
+ */
+
+import React, { useEffect, useRef } from "react";
+import { X } from "lucide-react";
+import { Icon } from "../atoms/Icon";
+import { Box } from "../atoms/Box";
+import { Typography } from "../atoms/Typography";
+import { Overlay } from "../atoms/Overlay";
+import { cn } from "../../lib/cn";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DrawerPosition = "left" | "right";
+export type DrawerSize = "sm" | "md" | "lg" | "xl" | "full";
+
+export interface DrawerProps {
+  /** Whether the drawer is open (defaults to true when rendered by slot wrapper) */
+  isOpen?: boolean;
+  /** Callback when drawer should close (injected by slot wrapper) */
+  onClose?: () => void;
+  /** Drawer title */
+  title?: string;
+  /** Drawer content (can be empty if using slot content) */
+  children?: React.ReactNode;
+  /** Footer content */
+  footer?: React.ReactNode;
+  /** Position (left or right) */
+  position?: DrawerPosition;
+  /** Width (CSS value or preset size) */
+  width?: string | DrawerSize;
+  /** Show close button */
+  showCloseButton?: boolean;
+  /** Close on overlay click */
+  closeOnOverlayClick?: boolean;
+  /** Close on escape key */
+  closeOnEscape?: boolean;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================================================
+// Size Presets
+// ============================================================================
+
+const sizeWidths: Record<DrawerSize, string> = {
+  sm: "w-80", // 320px
+  md: "w-96", // 384px
+  lg: "w-[480px]", // 480px
+  xl: "w-[640px]", // 640px
+  full: "w-screen",
+};
+
+// ============================================================================
+// Component
+// ============================================================================
+
+export const Drawer: React.FC<DrawerProps> = ({
+  isOpen = true,
+  onClose = () => {},
+  title,
+  children = null,
+  footer,
+  position = "right",
+  width = "md",
+  showCloseButton = true,
+  closeOnOverlayClick = true,
+  closeOnEscape = true,
+  className,
+}) => {
+  const drawerRef = useRef<HTMLDivElement>(null);
+  const previousActiveElement = useRef<HTMLElement | null>(null);
+
+  // Focus management
+  useEffect(() => {
+    if (isOpen) {
+      previousActiveElement.current = document.activeElement as HTMLElement;
+      const focusableElements = drawerRef.current?.querySelectorAll(
+        'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+      );
+      const firstElement = focusableElements?.[0] as HTMLElement;
+      firstElement?.focus();
+    } else {
+      previousActiveElement.current?.focus();
+    }
+  }, [isOpen]);
+
+  // Escape key handler
+  useEffect(() => {
+    if (!isOpen || !closeOnEscape) return;
+
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        onClose();
+      }
+    };
+
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, [isOpen, closeOnEscape, onClose]);
+
+  // Prevent body scroll when open
+  useEffect(() => {
+    if (isOpen) {
+      document.body.style.overflow = "hidden";
+    } else {
+      document.body.style.overflow = "";
+    }
+    return () => {
+      document.body.style.overflow = "";
+    };
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+
+  // Handle overlay click
+  const handleOverlayClick = (e: React.MouseEvent) => {
+    if (closeOnOverlayClick && e.target === e.currentTarget) {
+      onClose();
+    }
+  };
+
+  // Resolve width
+  const widthClass = width in sizeWidths ? sizeWidths[width as DrawerSize] : "";
+  const widthStyle = width in sizeWidths ? undefined : { width };
+
+  // Position classes
+  const positionClasses =
+    position === "right" ? "right-0 border-l" : "left-0 border-r";
+
+  // Animation classes
+  const animationClasses =
+    position === "right" ? "animate-slide-in-right" : "animate-slide-in-left";
+
+  return (
+    <>
+      {/* Overlay */}
+      <Overlay
+        isVisible={isOpen}
+        onClick={handleOverlayClick}
+        className="z-40"
+      />
+
+      {/* Drawer */}
+      <Box
+        ref={drawerRef}
+        bg="surface"
+        border
+        shadow="xl"
+        className={cn(
+          "fixed top-0 bottom-0 z-50",
+          "flex flex-col max-h-screen",
+          positionClasses,
+          widthClass,
+          animationClasses,
+          className,
+        )}
+        style={widthStyle}
+        role="dialog"
+        aria-modal="true"
+        {...(title && { "aria-labelledby": "drawer-title" })}
+      >
+        {/* Header */}
+        {(title || showCloseButton) && (
+          <div
+            className={cn(
+              "px-6 py-4 flex items-center justify-between shrink-0",
+              "border-b-[length:var(--border-width)] border-[var(--color-border)]",
+            )}
+          >
+            {title && (
+              <Typography variant="h4" as="h2" id="drawer-title">
+                {title}
+              </Typography>
+            )}
+            {showCloseButton && (
+              <button
+                type="button"
+                onClick={onClose}
+                className={cn(
+                  "p-1 transition-colors rounded-[var(--radius-sm)]",
+                  "hover:bg-[var(--color-muted)]",
+                  !title && "ml-auto",
+                )}
+                aria-label="Close drawer"
+              >
+                <Icon icon={X} size="md" />
+              </button>
+            )}
+          </div>
+        )}
+
+        {/* Content */}
+        <div className="flex-1 overflow-y-auto p-6">{children}</div>
+
+        {/* Footer */}
+        {footer && (
+          <div
+            className={cn(
+              "px-6 py-4 shrink-0 bg-[var(--color-muted)]",
+              "border-t-[length:var(--border-width)] border-[var(--color-border)]",
+            )}
+          >
+            {footer}
+          </div>
+        )}
+      </Box>
+
+      {/* Animation styles */}
+      <style>{`
+        @keyframes slide-in-right {
+          from {
+            transform: translateX(100%);
+          }
+          to {
+            transform: translateX(0);
+          }
+        }
+        @keyframes slide-in-left {
+          from {
+            transform: translateX(-100%);
+          }
+          to {
+            transform: translateX(0);
+          }
+        }
+        .animate-slide-in-right {
+          animation: slide-in-right 0.3s ease-out;
+        }
+        .animate-slide-in-left {
+          animation: slide-in-left 0.3s ease-out;
+        }
+      `}</style>
+    </>
+  );
+};
+
+Drawer.displayName = "Drawer";