@almadar/cli 0.3.1 → 0.3.3

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

@@ -0,0 +1,196 @@
+/**
+ * SearchInput Molecule Component
+ *
+ * A search input component with icon, clear button, and loading state.
+ * Uses Input, Icon, Button, and Spinner atoms.
+ *
+ * Supports Query Singleton pattern via `query` prop for std/Search behavior.
+ */
+
+import React, { useState, useCallback, useEffect } from 'react';
+import { Search } from 'lucide-react';
+import { Input } from '../atoms/Input';
+import { Spinner } from '../atoms/Spinner';
+import { cn } from '../../lib/cn';
+import { useEventBus } from '../../hooks/useEventBus';
+import { useQuerySingleton } from '../../hooks/useQuerySingleton';
+
+export interface SearchInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+  /**
+   * Search value (controlled mode)
+   */
+  value?: string;
+
+  /**
+   * Callback when search value changes
+   */
+  onSearch?: (value: string) => void;
+
+  /**
+   * Debounce delay in milliseconds
+   * @default 300
+   */
+  debounceMs?: number;
+
+  /**
+   * Show loading state
+   * @default false
+   */
+  isLoading?: boolean;
+
+  /**
+   * Placeholder text
+   * @default 'Search...'
+   */
+  placeholder?: string;
+
+  /**
+   * Show clear button
+   * @default true
+   */
+  clearable?: boolean;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Event name to dispatch on search (schema metadata, wired by trait)
+   * This is metadata used by the trait generator, not by the component.
+   */
+  event?: string;
+
+  /**
+   * Entity type for context-aware search.
+   * When provided, search events include entity context.
+   */
+  entity?: string;
+
+  /**
+   * Query singleton binding for state management.
+   * When provided, syncs search state with the query singleton.
+   * Example: "@TaskQuery"
+   */
+  query?: string;
+}
+
+export const SearchInput: React.FC<SearchInputProps> = ({
+  value,
+  onSearch,
+  debounceMs = 300,
+  isLoading = false,
+  placeholder = 'Search...',
+  clearable = true,
+  className,
+  event,
+  entity,
+  query,
+  ...props
+}) => {
+  const eventBus = useEventBus();
+  const queryState = useQuerySingleton(query);
+
+  // Initialize from query singleton or controlled value
+  const initialValue = queryState?.search ?? value ?? '';
+  const [searchValue, setSearchValue] = useState(initialValue);
+  const [debounceTimer, setDebounceTimer] = useState<NodeJS.Timeout | null>(null);
+
+  // Sync with query singleton changes
+  useEffect(() => {
+    if (queryState && queryState.search !== searchValue) {
+      setSearchValue(queryState.search);
+    }
+  }, [queryState?.search]);
+
+  const handleChange = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
+    const newValue = e.target.value;
+    setSearchValue(newValue);
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    const timer = setTimeout(() => {
+      // Update query singleton if connected
+      if (queryState) {
+        queryState.setSearch(newValue);
+      }
+
+      // Call callback if provided
+      onSearch?.(newValue);
+
+      // Emit event if event name is provided (schema-driven)
+      if (event) {
+        eventBus.emit(`UI:${event}`, { searchTerm: newValue, entity });
+      }
+
+      // Emit generic UI:SEARCH for entity lists/tables/grids when entity, event, or query is configured
+      if (event || entity || query) {
+        eventBus.emit('UI:SEARCH', { searchTerm: newValue, entity, query });
+      }
+    }, debounceMs);
+
+    setDebounceTimer(timer);
+  }, [onSearch, debounceMs, debounceTimer, event, entity, query, eventBus, queryState]);
+
+  const handleClear = useCallback(() => {
+    setSearchValue('');
+
+    // Update query singleton if connected
+    if (queryState) {
+      queryState.setSearch('');
+    }
+
+    onSearch?.('');
+
+    // Emit clear search event
+    if (event || query) {
+      eventBus.emit('UI:CLEAR_SEARCH', { searchTerm: '', entity, query });
+    }
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+  }, [onSearch, debounceTimer, event, query, entity, eventBus, queryState]);
+
+  // Sync with controlled value prop
+  useEffect(() => {
+    if (value !== undefined && value !== searchValue && !query) {
+      setSearchValue(value);
+    }
+  }, [value, query]);
+
+  useEffect(() => {
+    return () => {
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+      }
+    };
+  }, [debounceTimer]);
+
+  return (
+    <div className={cn('relative', className)}>
+      <Input
+        type="search"
+        value={searchValue}
+        onChange={handleChange}
+        placeholder={placeholder}
+        icon={Search}
+        clearable={clearable && !isLoading}
+        onClear={handleClear}
+        disabled={isLoading}
+        className="pr-10"
+        {...props}
+      />
+      {isLoading && (
+        <div className="absolute right-3 top-1/2 -translate-y-1/2">
+          <Spinner size="sm" color="primary" />
+        </div>
+      )}
+    </div>
+  );
+};
+
+SearchInput.displayName = 'SearchInput';
+

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

@@ -0,0 +1,116 @@
+/**
+ * SidePanel Molecule Component
+ *
+ * A side panel that slides in from the right (or left) with header and content.
+ * Uses Button, Typography atoms.
+ */
+
+import React from "react";
+import { X } from "lucide-react";
+import { Button } from "../atoms/Button";
+import { Typography } from "../atoms/Typography";
+import { cn } from "../../lib/cn";
+
+export interface SidePanelProps {
+  /**
+   * Panel title
+   */
+  title: string;
+
+  /**
+   * Panel content
+   */
+  children: React.ReactNode;
+
+  /**
+   * Is panel open
+   */
+  isOpen: boolean;
+
+  /**
+   * On close handler
+   */
+  onClose: () => void;
+
+  /**
+   * Panel width
+   * @default 'w-96'
+   */
+  width?: string;
+
+  /**
+   * Panel position
+   * @default 'right'
+   */
+  position?: "left" | "right";
+
+  /**
+   * Show overlay on mobile
+   * @default true
+   */
+  showOverlay?: boolean;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+}
+
+export const SidePanel: React.FC<SidePanelProps> = ({
+  title,
+  children,
+  isOpen,
+  onClose,
+  width = "w-96",
+  position = "right",
+  showOverlay = true,
+  className,
+}) => {
+  if (!isOpen) return null;
+
+  return (
+    <>
+      {/* Overlay */}
+      {showOverlay && (
+        <div
+          className="fixed inset-0 bg-white/80 backdrop-blur-sm z-40 lg:hidden"
+          onClick={onClose}
+        />
+      )}
+
+      {/* Side Panel */}
+      <aside
+        className={cn(
+          "fixed top-16 lg:top-0 bottom-0 z-[60]",
+          "bg-[var(--color-card)]",
+          "border-l-2 border-[var(--color-border)]",
+          position === "left" && "border-l-0 border-r-2",
+          "flex flex-col",
+          "transition-transform duration-300 ease-in-out",
+          width,
+          position === "right" ? "right-0" : "left-0",
+          className,
+        )}
+      >
+        {/* Header */}
+        <div className="flex items-center justify-between p-4 border-b-2 border-[var(--color-border)] sticky top-0 bg-[var(--color-card)] z-10">
+          <Typography variant="h6">{title}</Typography>
+          <Button
+            variant="ghost"
+            size="sm"
+            icon={X}
+            onClick={onClose}
+            aria-label="Close panel"
+          >
+            <span className="sr-only">Close</span>
+          </Button>
+        </div>
+
+        {/* Content */}
+        <div className="p-4 flex-1 overflow-y-auto">{children}</div>
+      </aside>
+    </>
+  );
+};
+
+SidePanel.displayName = "SidePanel";

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

@@ -0,0 +1,90 @@
+/**
+ * SimpleGrid Component
+ * 
+ * A simplified grid that automatically adjusts columns based on available space.
+ * Perfect for card layouts and item collections.
+ */
+import React from 'react';
+import { cn } from '../../lib/cn';
+
+export type SimpleGridGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface SimpleGridProps {
+  /** Minimum width of each child (e.g., 200, "200px", "15rem") */
+  minChildWidth?: number | string;
+  /** Maximum number of columns */
+  maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Exact number of columns (disables auto-fit) */
+  cols?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Gap between items */
+  gap?: SimpleGridGap;
+  /** Custom class name */
+  className?: string;
+  /** Children elements */
+  children: React.ReactNode;
+}
+
+const gapStyles: Record<SimpleGridGap, string> = {
+  none: 'gap-0',
+  xs: 'gap-1',
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-6',
+  xl: 'gap-8',
+};
+
+const colStyles = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-2',
+  3: 'grid-cols-3',
+  4: 'grid-cols-4',
+  5: 'grid-cols-5',
+  6: 'grid-cols-6',
+};
+
+/**
+ * SimpleGrid - Auto-responsive grid layout
+ */
+export const SimpleGrid: React.FC<SimpleGridProps> = ({
+  minChildWidth = 250,
+  maxCols,
+  cols,
+  gap = 'md',
+  className,
+  children,
+}) => {
+  // If exact cols specified, use fixed grid
+  if (cols) {
+    return (
+      <div className={cn('grid', colStyles[cols], gapStyles[gap], className)}>
+        {children}
+      </div>
+    );
+  }
+
+  // Otherwise use auto-fit with minChildWidth
+  const minWidth = typeof minChildWidth === 'number' 
+    ? `${minChildWidth}px` 
+    : minChildWidth;
+
+  // Calculate max column constraint if provided
+  const templateColumns = maxCols
+    ? `repeat(auto-fit, minmax(min(${minWidth}, 100%), 1fr))`
+    : `repeat(auto-fit, minmax(${minWidth}, 1fr))`;
+
+  return (
+    <div
+      className={cn('grid', gapStyles[gap], className)}
+      style={{ 
+        gridTemplateColumns: templateColumns,
+        // Limit max columns if specified
+        ...(maxCols && { maxWidth: `calc(${maxCols} * (${minWidth} + var(--gap, 1rem)))` }),
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+export default SimpleGrid;
+

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

@@ -0,0 +1,208 @@
+/**
+ * Tabs Molecule Component
+ * 
+ * A tabbed interface component with keyboard navigation and badge support.
+ * Uses theme-aware CSS variables for styling.
+ */
+
+import React, { useState, useRef } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import { Icon } from '../atoms/Icon';
+import { Badge } from '../atoms/Badge';
+import { Typography } from '../atoms/Typography';
+import { cn } from '../../lib/cn';
+import { useEventBus } from '../../hooks/useEventBus';
+
+export interface TabItem {
+  /** Tab ID */
+  id: string;
+  /** Tab label */
+  label: string;
+  /** Tab content - optional for event-driven tabs */
+  content?: React.ReactNode;
+  /** Tab icon */
+  icon?: LucideIcon;
+  /** Tab badge */
+  badge?: string | number;
+  /** Disable tab */
+  disabled?: boolean;
+  /** Event to emit when tab is clicked (for trait state machine integration) */
+  event?: string;
+  /** Whether this tab is currently active (for controlled tabs) */
+  active?: boolean;
+}
+
+export interface TabsProps {
+  /** Tab items */
+  items?: TabItem[];
+  /** Tab items (alias for items - used by generated code) */
+  tabs?: TabItem[];
+  /** Default active tab ID */
+  defaultActiveTab?: string;
+  /** Controlled active tab ID */
+  activeTab?: string;
+  /** Callback when tab changes */
+  onTabChange?: (tabId: string) => void;
+  /** Tab variant */
+  variant?: 'default' | 'pills' | 'underline';
+  /** Tab orientation */
+  orientation?: 'horizontal' | 'vertical';
+  /** Additional CSS classes */
+  className?: string;
+}
+
+export const Tabs: React.FC<TabsProps> = ({
+  items,
+  tabs,
+  defaultActiveTab,
+  activeTab: controlledActiveTab,
+  onTabChange,
+  variant = 'default',
+  orientation = 'horizontal',
+  className,
+}) => {
+  // Guard against undefined or empty items - support both 'items' and 'tabs' props
+  const safeItems = items ?? tabs ?? [];
+  const eventBus = useEventBus();
+
+  // Find initially active tab (check for active: true in items)
+  const initialActive = safeItems.find(item => item.active)?.id;
+
+  const [internalActiveTab, setInternalActiveTab] = useState(
+    defaultActiveTab || initialActive || safeItems[0]?.id || ''
+  );
+  const activeTab = controlledActiveTab !== undefined ? controlledActiveTab : internalActiveTab;
+  const tabRefs = useRef<Record<string, HTMLButtonElement | null>>({});
+
+  const handleTabChange = (tabId: string, tabEvent?: string) => {
+    if (controlledActiveTab === undefined) {
+      setInternalActiveTab(tabId);
+    }
+    onTabChange?.(tabId);
+
+    // Emit event if tab has event configured (for trait state machine integration)
+    if (tabEvent) {
+      eventBus.emit(`UI:${tabEvent}`, { tabId });
+    }
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
+    if (e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+      e.preventDefault();
+      const direction = e.key === 'ArrowLeft' ? -1 : 1;
+      const nextIndex = (index + direction + safeItems.length) % safeItems.length;
+      const nextTab = safeItems[nextIndex];
+      if (nextTab && !nextTab.disabled) {
+        handleTabChange(nextTab.id);
+        tabRefs.current[nextTab.id]?.focus();
+      }
+    } else if (e.key === 'Home' || e.key === 'End') {
+      e.preventDefault();
+      const targetIndex = e.key === 'Home' ? 0 : safeItems.length - 1;
+      const targetTab = safeItems[targetIndex];
+      if (targetTab && !targetTab.disabled) {
+        handleTabChange(targetTab.id);
+        tabRefs.current[targetTab.id]?.focus();
+      }
+    }
+  };
+
+  const activeTabContent = safeItems.find(item => item.id === activeTab)?.content;
+
+  // Graceful handling for empty tabs
+  if (safeItems.length === 0) {
+    return (
+      <div className={cn('w-full', className)}>
+        <div className="text-[var(--color-muted-foreground)] text-sm py-4">
+          No tabs available
+        </div>
+      </div>
+    );
+  }
+
+  // Theme-aware variant styles
+  const variantClasses = {
+    default: [
+      'border-b-[length:var(--border-width)] border-transparent',
+      'hover:border-[var(--color-muted-foreground)]',
+      'data-[active=true]:border-[var(--color-primary)]',
+    ].join(' '),
+    pills: [
+      'rounded-[var(--radius-sm)]',
+      'data-[active=true]:bg-[var(--color-primary)]',
+      'data-[active=true]:text-[var(--color-primary-foreground)]',
+    ].join(' '),
+    underline: [
+      'border-b-[length:var(--border-width)] border-transparent',
+      'data-[active=true]:border-[var(--color-primary)]',
+    ].join(' '),
+  };
+
+  return (
+    <div className={cn('w-full', className)}>
+      <div
+        role="tablist"
+        className={cn(
+          'flex',
+          orientation === 'horizontal'
+            ? 'flex-row border-b-[length:var(--border-width)] border-[var(--color-border)]'
+            : 'flex-col border-r-[length:var(--border-width)] border-[var(--color-border)]',
+          variant === 'pills' && 'gap-1 p-1 bg-[var(--color-muted)] border-0 rounded-[var(--radius-md)]',
+          variant === 'underline' && orientation === 'vertical' && 'border-b-0'
+        )}
+      >
+        {safeItems.map((item, index) => {
+          const isActive = item.id === activeTab;
+          const isDisabled = item.disabled;
+
+          return (
+            <button
+              key={item.id}
+              ref={(el) => {
+                tabRefs.current[item.id] = el;
+              }}
+              role="tab"
+              aria-selected={isActive}
+              aria-controls={`tabpanel-${item.id}`}
+              aria-disabled={isDisabled}
+              disabled={isDisabled}
+              onClick={() => !isDisabled && handleTabChange(item.id, item.event)}
+              onKeyDown={(e) => handleKeyDown(e, index)}
+              data-active={isActive}
+              className={cn(
+                'flex items-center gap-2 px-4 py-2 text-sm font-medium transition-all',
+                'focus:outline-none focus:ring-2 focus:ring-[var(--color-ring)] focus:ring-offset-2',
+                'disabled:opacity-50 disabled:cursor-not-allowed',
+                variantClasses[variant],
+                isActive
+                  ? 'text-[var(--color-foreground)] font-bold'
+                  : 'text-[var(--color-muted-foreground)] hover:text-[var(--color-foreground)]'
+              )}
+            >
+              {item.icon && <Icon icon={item.icon} size="sm" />}
+              <Typography variant="small" weight={isActive ? 'semibold' : 'normal'}>
+                {item.label}
+              </Typography>
+              {item.badge !== undefined && (
+                <Badge variant="default" size="sm">
+                  {item.badge}
+                </Badge>
+              )}
+            </button>
+          );
+        })}
+      </div>
+
+      <div
+        role="tabpanel"
+        id={`tabpanel-${activeTab}`}
+        aria-labelledby={`tab-${activeTab}`}
+        className="mt-4"
+      >
+        {activeTabContent}
+      </div>
+    </div>
+  );
+};
+
+Tabs.displayName = 'Tabs';