@almadar/cli 0.3.2 → 1.0.3

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

@@ -0,0 +1,328 @@
+/**
+ * RelationSelect Molecule Component
+ *
+ * A searchable select component for relation fields.
+ * Allows users to search and select from related entities.
+ *
+ * Composed from: Box, HStack, VStack, Input, Button, Spinner, Typography atoms
+ */
+
+import React, {
+  useState,
+  useCallback,
+  useMemo,
+  useRef,
+  useEffect,
+} from "react";
+import { Search, ChevronDown, X } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { Box } from "../atoms/Box";
+import { HStack, VStack } from "../atoms/Stack";
+import { Input } from "../atoms/Input";
+import { Button } from "../atoms/Button";
+import { Spinner } from "../atoms/Spinner";
+import { Typography } from "../atoms/Typography";
+import {
+  debug,
+  debugGroup,
+  debugGroupEnd,
+  isDebugEnabled,
+} from "../../lib/debug";
+
+// Helper to check if specific debug category is enabled
+const isRelationsDebugEnabled = () => isDebugEnabled();
+
+export interface RelationOption {
+  /** The value to store (typically the ID) */
+  value: string;
+  /** The display label */
+  label: string;
+  /** Optional description */
+  description?: string;
+  /** Whether this option is disabled */
+  disabled?: boolean;
+}
+
+export interface RelationSelectProps {
+  /** Current value (ID) */
+  value?: string;
+  /** Callback when value changes */
+  onChange?: (value: string | undefined) => void;
+  /** Available options - accepts readonly for compatibility with generated const arrays */
+  options: readonly RelationOption[];
+  /** Placeholder text */
+  placeholder?: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /** Whether the field is disabled */
+  disabled?: boolean;
+  /** Whether data is loading */
+  isLoading?: boolean;
+  /** Error message */
+  error?: string;
+  /** Allow clearing the selection */
+  clearable?: boolean;
+  /** Name attribute for forms */
+  name?: string;
+  /** Additional CSS classes */
+  className?: string;
+  /** Search placeholder */
+  searchPlaceholder?: string;
+  /** Empty state message */
+  emptyMessage?: string;
+}
+
+export const RelationSelect: React.FC<RelationSelectProps> = ({
+  value,
+  onChange,
+  options = [],
+  placeholder = "Select...",
+  required = false,
+  disabled = false,
+  isLoading = false,
+  error,
+  clearable = true,
+  name,
+  className,
+  searchPlaceholder = "Search...",
+  emptyMessage = "No options found",
+}) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const [searchQuery, setSearchQuery] = useState("");
+  const containerRef = useRef<HTMLDivElement>(null);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+
+  // Debug: Log component initialization
+  useEffect(() => {
+    if (isRelationsDebugEnabled()) {
+      debugGroup(`RelationSelect: ${name || "unnamed"}`);
+      debug(`Options count: ${options.length}`);
+      debug(`Current value: ${value || "none"}`);
+      debug(`Is loading: ${isLoading}`);
+      if (options.length > 0) {
+        debug("Sample options:", options.slice(0, 3));
+      } else {
+        debug("⚠️ No options available!");
+      }
+      debugGroupEnd();
+    }
+  }, [name, options.length, value, isLoading]);
+
+  // Find selected option
+  const selectedOption = useMemo(() => {
+    const found = options.find((opt) => opt.value === value);
+    if (isRelationsDebugEnabled() && value && !found) {
+      debug(`⚠️ Value "${value}" not found in options for ${name}`);
+    }
+    return found;
+  }, [options, value, name]);
+
+  // Filter options by search query
+  const filteredOptions = useMemo(() => {
+    if (!searchQuery.trim()) return options;
+    const query = searchQuery.toLowerCase();
+    return options.filter(
+      (opt) =>
+        opt.label.toLowerCase().includes(query) ||
+        opt.description?.toLowerCase().includes(query),
+    );
+  }, [options, searchQuery]);
+
+  // Handle outside click to close dropdown
+  useEffect(() => {
+    const handleClickOutside = (event: MouseEvent) => {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(event.target as Node)
+      ) {
+        setIsOpen(false);
+        setSearchQuery("");
+      }
+    };
+
+    document.addEventListener("mousedown", handleClickOutside);
+    return () => document.removeEventListener("mousedown", handleClickOutside);
+  }, []);
+
+  // Focus search input when dropdown opens
+  useEffect(() => {
+    if (isOpen && searchInputRef.current) {
+      searchInputRef.current.focus();
+    }
+  }, [isOpen]);
+
+  const handleToggle = useCallback(() => {
+    if (!disabled) {
+      setIsOpen((prev) => !prev);
+      if (!isOpen) {
+        setSearchQuery("");
+      }
+    }
+  }, [disabled, isOpen]);
+
+  const handleSelect = useCallback(
+    (option: RelationOption) => {
+      if (option.disabled) return;
+      onChange?.(option.value);
+      setIsOpen(false);
+      setSearchQuery("");
+    },
+    [onChange],
+  );
+
+  const handleClear = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      onChange?.(undefined);
+    },
+    [onChange],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      if (e.key === "Escape") {
+        setIsOpen(false);
+        setSearchQuery("");
+      } else if (e.key === "Enter" && filteredOptions.length === 1) {
+        handleSelect(filteredOptions[0]);
+      }
+    },
+    [filteredOptions, handleSelect],
+  );
+
+  return (
+    <div ref={containerRef} className={cn("relative", className)}>
+      {/* Hidden input for form submission */}
+      <input type="hidden" name={name} value={value || ""} />
+
+      {/* Trigger button */}
+      <Button
+        type="button"
+        variant="secondary"
+        onClick={handleToggle}
+        disabled={disabled}
+        className={cn(
+          "w-full justify-between font-normal",
+          error && "border-red-300 focus:border-red-500 focus:ring-red-500",
+          isOpen && "ring-2 ring-primary-500 border-primary-500",
+        )}
+      >
+        <Typography
+          variant="body"
+          className={cn(
+            !selectedOption && "text-[var(--color-muted-foreground)]",
+          )}
+        >
+          {isLoading ? (
+            <HStack gap="xs" align="center">
+              <Spinner size="sm" />
+              <span>Loading...</span>
+            </HStack>
+          ) : selectedOption ? (
+            selectedOption.label
+          ) : (
+            placeholder
+          )}
+        </Typography>
+        <HStack gap="xs" align="center">
+          {clearable && selectedOption && !disabled && (
+            <span
+              className="p-0.5 hover:bg-[var(--color-muted)] rounded cursor-pointer"
+              onClick={handleClear}
+            >
+              <X className="h-4 w-4 text-[var(--color-muted-foreground)]" />
+            </span>
+          )}
+          <ChevronDown
+            className={cn(
+              "h-4 w-4 text-[var(--color-muted-foreground)] transition-transform",
+              isOpen && "transform rotate-180",
+            )}
+          />
+        </HStack>
+      </Button>
+
+      {/* Dropdown */}
+      {isOpen && (
+        <Box
+          position="absolute"
+          bg="surface"
+          border
+          rounded="md"
+          shadow="lg"
+          className="z-50 w-full mt-1"
+        >
+          {/* Search input */}
+          <Box padding="sm" className="border-b border-[var(--color-border)]">
+            <Input
+              ref={searchInputRef}
+              type="text"
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              onKeyDown={handleKeyDown}
+              placeholder={searchPlaceholder}
+              icon={Search}
+              className="text-sm"
+            />
+          </Box>
+
+          {/* Options list */}
+          <Box overflow="auto" className="max-h-60">
+            {isLoading ? (
+              <Box padding="md" display="flex" className="justify-center">
+                <Spinner size="md" color="primary" />
+              </Box>
+            ) : filteredOptions.length === 0 ? (
+              <Box padding="md">
+                <Typography
+                  variant="body"
+                  color="muted"
+                  className="text-center"
+                >
+                  {emptyMessage}
+                </Typography>
+              </Box>
+            ) : (
+              <VStack gap="none">
+                {filteredOptions.map((option) => (
+                  <Box
+                    key={option.value}
+                    as="button"
+                    fullWidth
+                    paddingX="sm"
+                    paddingY="sm"
+                    className={cn(
+                      "text-left text-sm hover:bg-[var(--color-muted)] focus:outline-none focus:bg-[var(--color-muted)]",
+                      option.value === value &&
+                        "bg-primary-50 text-primary-700",
+                      option.disabled && "opacity-50 cursor-not-allowed",
+                    )}
+                    onClick={() => handleSelect(option)}
+                  >
+                    <Typography variant="body" className="font-medium">
+                      {option.label}
+                    </Typography>
+                    {option.description && (
+                      <Typography variant="caption" color="muted">
+                        {option.description}
+                      </Typography>
+                    )}
+                  </Box>
+                ))}
+              </VStack>
+            )}
+          </Box>
+        </Box>
+      )}
+
+      {/* Error message */}
+      {error && (
+        <Typography variant="caption" color="error" className="mt-1">
+          {error}
+        </Typography>
+      )}
+    </div>
+  );
+};
+
+RelationSelect.displayName = "RelationSelect";

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

@@ -0,0 +1,236 @@
+/**
+ * RepeatableFormSection
+ *
+ * A form section that can be repeated multiple times.
+ * Used for collecting multiple entries (participants, findings, etc.)
+ *
+ * Enhanced with trackAddedInState for inspection audit trails.
+ *
+ * Event Contract:
+ * - Emits: UI:SECTION_ADDED { sectionType, index, addedInState? }
+ * - Emits: UI:SECTION_REMOVED { sectionType, index, itemId }
+ */
+
+import React, { useCallback } from "react";
+import { cn } from "../../lib/cn";
+import { Box } from "../atoms/Box";
+import { VStack, HStack } from "../atoms/Stack";
+import { Typography } from "../atoms/Typography";
+import { Button } from "../atoms/Button";
+import { Card } from "../atoms/Card";
+import { Icon } from "../atoms/Icon";
+import { useEventBus } from "../../hooks/useEventBus";
+
+export interface RepeatableItem {
+  id: string;
+  /** State in which this item was added (for audit trails) */
+  addedInState?: string;
+  /** Timestamp when item was added */
+  addedAt?: string;
+  [key: string]: unknown;
+}
+
+export interface RepeatableFormSectionProps {
+  /** Section type identifier */
+  sectionType: string;
+  /** Section title */
+  title: string;
+  /** Items in the section */
+  items: RepeatableItem[];
+  /** Render function for each item */
+  renderItem: (item: RepeatableItem, index: number) => React.ReactNode;
+  /** Minimum items required */
+  minItems?: number;
+  /** Maximum items allowed */
+  maxItems?: number;
+  /** Allow reordering */
+  allowReorder?: boolean;
+  /** Add button label */
+  addLabel?: string;
+  /** Empty state message */
+  emptyMessage?: string;
+  /** Read-only mode */
+  readOnly?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+  /** Add handler */
+  onAdd?: () => void;
+  /** Remove handler */
+  onRemove?: (itemId: string, index: number) => void;
+  /** Reorder handler */
+  onReorder?: (fromIndex: number, toIndex: number) => void;
+
+  // Inspection-specific enhancements
+  /** Track the state in which items are added (for inspection audit) */
+  trackAddedInState?: boolean;
+  /** Current inspection state (used when trackAddedInState is true) */
+  currentState?: string;
+  /** Show audit metadata (addedInState, addedAt) */
+  showAuditInfo?: boolean;
+}
+
+export const RepeatableFormSection: React.FC<RepeatableFormSectionProps> = ({
+  sectionType,
+  title,
+  items,
+  renderItem,
+  minItems = 0,
+  maxItems = Infinity,
+  allowReorder = false,
+  addLabel = "Add Item",
+  emptyMessage = "No items added yet",
+  readOnly = false,
+  className,
+  onAdd,
+  onRemove,
+  onReorder,
+  trackAddedInState = false,
+  currentState,
+  showAuditInfo = false,
+}) => {
+  const eventBus = useEventBus();
+
+  const canAdd = !readOnly && items.length < maxItems;
+  const canRemove = !readOnly && items.length > minItems;
+
+  const handleAdd = useCallback(() => {
+    onAdd?.();
+
+    const eventPayload: Record<string, unknown> = {
+      sectionType,
+      index: items.length,
+    };
+
+    // Include state tracking info if enabled
+    if (trackAddedInState && currentState) {
+      eventPayload.addedInState = currentState;
+      eventPayload.addedAt = new Date().toISOString();
+    }
+
+    eventBus.emit("UI:SECTION_ADDED", eventPayload);
+  }, [
+    sectionType,
+    items.length,
+    onAdd,
+    eventBus,
+    trackAddedInState,
+    currentState,
+  ]);
+
+  const handleRemove = useCallback(
+    (itemId: string, index: number) => {
+      onRemove?.(itemId, index);
+      eventBus.emit("UI:SECTION_REMOVED", { sectionType, index, itemId });
+    },
+    [sectionType, onRemove, eventBus],
+  );
+
+  return (
+    <VStack gap="md" className={cn("w-full", className)}>
+      {/* Header */}
+      <HStack justify="between" align="center">
+        <HStack gap="sm" align="center">
+          <Typography variant="h4">{title}</Typography>
+          <Typography variant="caption" color="muted">
+            ({items.length}
+            {maxItems !== Infinity ? `/${maxItems}` : ""})
+          </Typography>
+        </HStack>
+
+        {canAdd && (
+          <Button variant="secondary" size="sm" onClick={handleAdd}>
+            <Icon name="plus" size="sm" className="mr-1" />
+            {addLabel}
+          </Button>
+        )}
+      </HStack>
+
+      {/* Items */}
+      {items.length === 0 ? (
+        <Card className="p-6">
+          <VStack align="center" gap="sm">
+            <Typography variant="body" color="muted">
+              {emptyMessage}
+            </Typography>
+            {canAdd && (
+              <Button variant="primary" size="sm" onClick={handleAdd}>
+                <Icon name="plus" size="sm" className="mr-1" />
+                {addLabel}
+              </Button>
+            )}
+          </VStack>
+        </Card>
+      ) : (
+        <VStack gap="sm">
+          {items.map((item, index) => (
+            <Card key={item.id} className="p-4">
+              <VStack gap="sm">
+                {/* Audit info header */}
+                {showAuditInfo && (item.addedInState || item.addedAt) && (
+                  <HStack
+                    justify="between"
+                    align="center"
+                    className="pb-2 border-b border-[var(--color-border)]"
+                  >
+                    <HStack gap="sm" align="center">
+                      {item.addedInState && (
+                        <Typography variant="caption" color="muted">
+                          Added in:{" "}
+                          <Typography
+                            as="span"
+                            variant="caption"
+                            weight="semibold"
+                          >
+                            {item.addedInState}
+                          </Typography>
+                        </Typography>
+                      )}
+                    </HStack>
+                    {item.addedAt && (
+                      <Typography variant="caption" color="muted">
+                        {new Date(item.addedAt).toLocaleString()}
+                      </Typography>
+                    )}
+                  </HStack>
+                )}
+
+                <HStack gap="sm" align="start">
+                  {/* Drag handle */}
+                  {allowReorder && !readOnly && (
+                    <Box className="pt-2 cursor-move text-[var(--color-muted-foreground)] hover:text-[var(--color-foreground)]">
+                      <Icon name="grip-vertical" size="md" />
+                    </Box>
+                  )}
+
+                  {/* Item content */}
+                  <Box className="flex-1">{renderItem(item, index)}</Box>
+
+                  {/* Remove button */}
+                  {canRemove && (
+                    <Button
+                      variant="ghost"
+                      size="sm"
+                      onClick={() => handleRemove(item.id, index)}
+                      className="text-[var(--color-error)] hover:text-[var(--color-error)] hover:bg-[var(--color-error)]/10"
+                    >
+                      <Icon name="trash-2" size="sm" />
+                    </Button>
+                  )}
+                </HStack>
+              </VStack>
+            </Card>
+          ))}
+        </VStack>
+      )}
+
+      {/* Min items warning */}
+      {items.length < minItems && (
+        <Typography variant="caption" color="warning">
+          At least {minItems} item{minItems !== 1 ? "s" : ""} required
+        </Typography>
+      )}
+    </VStack>
+  );
+};
+
+RepeatableFormSection.displayName = "RepeatableFormSection";