@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/components/atoms/Spacer.tsx

@@ -0,0 +1,68 @@
+/**
+ * Spacer Component
+ * 
+ * A flexible spacer that expands to fill available space in a flex container.
+ * Useful for pushing elements apart or creating consistent spacing.
+ */
+import React from 'react';
+import { cn } from '../../lib/cn';
+
+export type SpacerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'auto';
+
+export interface SpacerProps {
+  /** Fixed size (auto = flex grow) */
+  size?: SpacerSize;
+  /** Orientation (for fixed sizes) */
+  axis?: 'horizontal' | 'vertical';
+  /** Custom class name */
+  className?: string;
+}
+
+const horizontalSizes: Record<Exclude<SpacerSize, 'auto'>, string> = {
+  xs: 'w-1',
+  sm: 'w-2',
+  md: 'w-4',
+  lg: 'w-6',
+  xl: 'w-8',
+  '2xl': 'w-12',
+};
+
+const verticalSizes: Record<Exclude<SpacerSize, 'auto'>, string> = {
+  xs: 'h-1',
+  sm: 'h-2',
+  md: 'h-4',
+  lg: 'h-6',
+  xl: 'h-8',
+  '2xl': 'h-12',
+};
+
+/**
+ * Spacer - Flexible spacing element for flex layouts
+ * 
+ * Usage:
+ * - size="auto" (default): Expands to fill available space (flex: 1)
+ * - size="md": Fixed size spacing
+ */
+export const Spacer: React.FC<SpacerProps> = ({
+  size = 'auto',
+  axis = 'horizontal',
+  className,
+}) => {
+  if (size === 'auto') {
+    return <div className={cn('flex-1', className)} aria-hidden="true" />;
+  }
+
+  const sizeClass = axis === 'horizontal' 
+    ? horizontalSizes[size] 
+    : verticalSizes[size];
+
+  return (
+    <div 
+      className={cn('flex-shrink-0', sizeClass, className)} 
+      aria-hidden="true" 
+    />
+  );
+};
+
+export default Spacer;
+

package/shells/typescript-shell/packages/client/src/components/atoms/Spinner.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { cn } from "../../lib/cn";
+import { Loader2 } from "lucide-react";
+
+export type SpinnerSize = "xs" | "sm" | "md" | "lg";
+
+export interface SpinnerProps extends React.HTMLAttributes<HTMLDivElement> {
+  size?: SpinnerSize;
+}
+
+const sizeStyles: Record<SpinnerSize, string> = {
+  xs: "h-3 w-3",
+  sm: "h-4 w-4",
+  md: "h-6 w-6",
+  lg: "h-8 w-8",
+};
+
+export const Spinner = React.forwardRef<HTMLDivElement, SpinnerProps>(
+  ({ className, size = "md", ...props }, ref) => {
+    return (
+      <div
+        ref={ref}
+        className={cn("text-[var(--color-foreground)]", className)}
+        {...props}
+      >
+        <Loader2 className={cn("animate-spin", sizeStyles[size])} />
+      </div>
+    );
+  },
+);
+
+Spinner.displayName = "Spinner";

package/shells/typescript-shell/packages/client/src/components/atoms/Stack.tsx

@@ -0,0 +1,151 @@
+/**
+ * Stack Component
+ *
+ * A layout primitive for arranging children in a vertical or horizontal stack with consistent spacing.
+ * Includes convenience exports VStack and HStack for common use cases.
+ */
+import React from "react";
+import { cn } from "../../lib/cn";
+
+export type StackDirection = "horizontal" | "vertical";
+export type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+export type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+export type StackJustify =
+  | "start"
+  | "center"
+  | "end"
+  | "between"
+  | "around"
+  | "evenly";
+
+export interface StackProps {
+  /** Stack direction */
+  direction?: StackDirection;
+  /** Gap between children */
+  gap?: StackGap;
+  /** Align items on the cross axis */
+  align?: StackAlign;
+  /** Justify items on the main axis */
+  justify?: StackJustify;
+  /** Allow items to wrap */
+  wrap?: boolean;
+  /** Reverse the order of children */
+  reverse?: boolean;
+  /** Fill available space (flex: 1) */
+  flex?: boolean;
+  /** Custom class name */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+  /** Children elements */
+  children?: React.ReactNode;
+  /** HTML element to render as */
+  as?: React.ElementType;
+  /** Click handler */
+  onClick?: (e: React.MouseEvent) => void;
+  /** Keyboard handler */
+  onKeyDown?: (e: React.KeyboardEvent) => void;
+  /** Role for accessibility */
+  role?: string;
+  /** Tab index for focus management */
+  tabIndex?: number;
+}
+
+const gapStyles: Record<StackGap, string> = {
+  none: "gap-0",
+  xs: "gap-1",
+  sm: "gap-2",
+  md: "gap-4",
+  lg: "gap-6",
+  xl: "gap-8",
+  "2xl": "gap-12",
+};
+
+const alignStyles: Record<StackAlign, string> = {
+  start: "items-start",
+  center: "items-center",
+  end: "items-end",
+  stretch: "items-stretch",
+  baseline: "items-baseline",
+};
+
+const justifyStyles: Record<StackJustify, string> = {
+  start: "justify-start",
+  center: "justify-center",
+  end: "justify-end",
+  between: "justify-between",
+  around: "justify-around",
+  evenly: "justify-evenly",
+};
+
+/**
+ * Stack - Flexible layout component for arranging children
+ */
+export const Stack: React.FC<StackProps> = ({
+  direction = "vertical",
+  gap = "md",
+  align = "stretch",
+  justify = "start",
+  wrap = false,
+  reverse = false,
+  flex = false,
+  className,
+  style,
+  children,
+  as: Component = "div",
+  onClick,
+  onKeyDown,
+  role,
+  tabIndex,
+}) => {
+  const directionClass =
+    direction === "horizontal"
+      ? reverse
+        ? "flex-row-reverse"
+        : "flex-row"
+      : reverse
+        ? "flex-col-reverse"
+        : "flex-col";
+
+  return (
+    <Component
+      className={cn(
+        "flex",
+        directionClass,
+        gapStyles[gap],
+        alignStyles[align],
+        justifyStyles[justify],
+        wrap && "flex-wrap",
+        flex && "flex-1",
+        className,
+      )}
+      style={style}
+      onClick={onClick}
+      onKeyDown={onKeyDown}
+      role={role}
+      tabIndex={tabIndex}
+    >
+      {children}
+    </Component>
+  );
+};
+
+/**
+ * VStack - Vertical stack shorthand
+ */
+export interface VStackProps extends Omit<StackProps, "direction"> {}
+
+export const VStack: React.FC<VStackProps> = (props) => (
+  <Stack direction="vertical" {...props} />
+);
+
+/**
+ * HStack - Horizontal stack shorthand
+ */
+export interface HStackProps extends Omit<StackProps, "direction"> {}
+
+export const HStack: React.FC<HStackProps> = (props) => (
+  <Stack direction="horizontal" {...props} />
+);
+
+export default Stack;

package/shells/typescript-shell/packages/client/src/components/atoms/Switch.tsx

@@ -0,0 +1,91 @@
+import * as React from "react";
+import { cn } from "../../lib/cn";
+
+export interface SwitchProps {
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  label?: string;
+  id?: string;
+  name?: string;
+  className?: string;
+}
+
+export const Switch = React.forwardRef<HTMLButtonElement, SwitchProps>(
+  (
+    {
+      checked,
+      defaultChecked = false,
+      onChange,
+      disabled = false,
+      label,
+      id,
+      name,
+      className,
+    },
+    ref,
+  ) => {
+    const [isChecked, setIsChecked] = React.useState(
+      checked !== undefined ? checked : defaultChecked,
+    );
+
+    React.useEffect(() => {
+      if (checked !== undefined) {
+        setIsChecked(checked);
+      }
+    }, [checked]);
+
+    const handleClick = () => {
+      if (disabled) return;
+      const newValue = !isChecked;
+      if (checked === undefined) {
+        setIsChecked(newValue);
+      }
+      onChange?.(newValue);
+    };
+
+    return (
+      <div className={cn("inline-flex items-center gap-2", className)}>
+        <button
+          ref={ref}
+          type="button"
+          role="switch"
+          aria-checked={isChecked}
+          aria-label={label}
+          id={id}
+          name={name}
+          disabled={disabled}
+          onClick={handleClick}
+          className={cn(
+            "relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors",
+            "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background",
+            isChecked ? "bg-primary" : "bg-muted",
+            disabled && "cursor-not-allowed opacity-50",
+          )}
+        >
+          <span
+            className={cn(
+              "pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg ring-0 transition-transform",
+              isChecked ? "translate-x-5" : "translate-x-0",
+            )}
+          />
+        </button>
+        {label && (
+          <label
+            htmlFor={id}
+            className={cn(
+              "text-sm font-medium leading-none cursor-pointer",
+              disabled && "cursor-not-allowed opacity-70",
+            )}
+            onClick={handleClick}
+          >
+            {label}
+          </label>
+        )}
+      </div>
+    );
+  },
+);
+
+Switch.displayName = "Switch";

package/shells/typescript-shell/packages/client/src/components/atoms/TextHighlight.tsx

@@ -0,0 +1,111 @@
+/**
+ * TextHighlight Atom Component
+ *
+ * A styled span component for highlighting text with annotations (questions or notes).
+ * Uses different colors for different annotation types:
+ * - Questions: Blue highlight
+ * - Notes: Yellow highlight
+ */
+
+import React from "react";
+import { cn } from "../../lib/cn";
+
+export type HighlightType = "question" | "note";
+
+export interface TextHighlightProps {
+  /**
+   * Type of highlight (determines color)
+   */
+  type: HighlightType;
+
+  /**
+   * Whether the highlight is currently active/focused
+   * @default false
+   */
+  isActive?: boolean;
+
+  /**
+   * Callback when highlight is clicked
+   */
+  onClick?: () => void;
+
+  /**
+   * Callback when highlight is hovered
+   */
+  onMouseEnter?: () => void;
+
+  /**
+   * Callback when hover ends
+   */
+  onMouseLeave?: () => void;
+
+  /**
+   * Unique ID for the annotation
+   */
+  annotationId?: string;
+
+  /**
+   * Additional CSS classes
+   */
+  className?: string;
+
+  /**
+   * Highlighted text content
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * TextHighlight component for rendering highlighted text annotations
+ */
+export const TextHighlight: React.FC<TextHighlightProps> = ({
+  type,
+  isActive = false,
+  onClick,
+  onMouseEnter,
+  onMouseLeave,
+  annotationId,
+  className,
+  children,
+}) => {
+  const baseStyles = "cursor-pointer transition-all duration-150";
+
+  const typeStyles = {
+    question: cn(
+      // Blue border for questions
+      "bg-[var(--color-card)] border-b-2 border-primary-600",
+      "hover:bg-[var(--color-muted)]",
+      isActive && "bg-primary-100 ring-2 ring-primary-600",
+    ),
+    note: cn(
+      // Yellow border for notes
+      "bg-[var(--color-card)] border-b-2 border-amber-500",
+      "hover:bg-[var(--color-muted)]",
+      isActive && "bg-amber-100 ring-2 ring-amber-500",
+    ),
+  };
+
+  return (
+    <span
+      data-highlight="true"
+      data-highlight-type={type}
+      data-annotation-id={annotationId}
+      className={cn(baseStyles, typeStyles[type], className)}
+      onClick={onClick}
+      onMouseEnter={onMouseEnter}
+      onMouseLeave={onMouseLeave}
+      role="button"
+      tabIndex={0}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onClick?.();
+        }
+      }}
+    >
+      {children}
+    </span>
+  );
+};
+
+TextHighlight.displayName = "TextHighlight";

package/shells/typescript-shell/packages/client/src/components/atoms/Textarea.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import { cn } from "../../lib/cn";
+
+export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+  error?: string;
+}
+
+export const Textarea = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
+  ({ className, error, ...props }, ref) => {
+    return (
+      <textarea
+        ref={ref}
+        className={cn(
+          "block w-full border-[length:var(--border-width)] shadow-[var(--shadow-sm)]",
+          "px-3 py-2 text-sm text-[var(--color-foreground)]",
+          "bg-[var(--color-card)]",
+          "placeholder:text-[var(--color-placeholder)]",
+          "focus:outline-none focus:ring-2 focus:ring-offset-0 focus:ring-[var(--color-ring)]",
+          "disabled:bg-[var(--color-muted)] disabled:text-[var(--color-muted-foreground)] disabled:cursor-not-allowed",
+          "resize-y min-h-[80px]",
+          error
+            ? "border-[var(--color-error)] focus:border-[var(--color-error)]"
+            : "border-[var(--color-border)] focus:border-[var(--color-primary)]",
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+
+Textarea.displayName = "Textarea";

package/shells/typescript-shell/packages/client/src/components/atoms/ThemeSelector.tsx

@@ -0,0 +1,128 @@
+/**
+ * ThemeSelector - Design theme selector component
+ *
+ * A dropdown/toggle component for switching between design themes.
+ *
+ * @packageDocumentation
+ */
+
+import React from "react";
+import {
+  useDesignTheme,
+  type DesignTheme,
+} from "../../context/DesignThemeContext";
+
+interface ThemeSelectorProps {
+  /** Optional className */
+  className?: string;
+  /** Show as dropdown or buttons */
+  variant?: "dropdown" | "buttons";
+  /** Show labels */
+  showLabels?: boolean;
+}
+
+const THEME_LABELS: Record<
+  string,
+  { label: string; icon: string; description: string }
+> = {
+  wireframe: {
+    label: "Wireframe",
+    icon: "📐",
+    description: "Sharp corners, thick borders",
+  },
+  minimalist: {
+    label: "Minimalist",
+    icon: "✨",
+    description: "Clean, subtle, refined",
+  },
+  almadar: {
+    label: "Almadar",
+    icon: "💎",
+    description: "Teal gradients, glowing accents",
+  },
+};
+
+/**
+ * ThemeSelector component for switching design themes
+ */
+export const ThemeSelector: React.FC<ThemeSelectorProps> = ({
+  className = "",
+  variant = "dropdown",
+  showLabels = true,
+}) => {
+  const { designTheme, setDesignTheme, availableThemes } = useDesignTheme();
+
+  if (variant === "buttons") {
+    return (
+      <div className={`flex gap-2 ${className}`}>
+        {availableThemes.map((theme) => {
+          const { label, icon } = THEME_LABELS[theme];
+          const isActive = designTheme === theme;
+
+          return (
+            <button
+              key={theme}
+              onClick={() => setDesignTheme(theme)}
+              className={`
+                px-3 py-2 text-sm font-medium transition-all
+                border-[length:var(--border-width)] rounded-[var(--radius-sm)]
+                ${
+                  isActive
+                    ? "bg-[var(--color-primary)] text-[var(--color-primary-foreground)] border-[var(--color-primary)]"
+                    : "bg-[var(--color-secondary)] text-[var(--color-secondary-foreground)] border-[var(--color-border)] hover:bg-[var(--color-secondary-hover)]"
+                }
+              `}
+              title={THEME_LABELS[theme].description}
+            >
+              {icon} {showLabels && label}
+            </button>
+          );
+        })}
+      </div>
+    );
+  }
+
+  // Dropdown variant
+  return (
+    <div className={`relative ${className}`}>
+      <select
+        value={designTheme}
+        onChange={(e) => setDesignTheme(e.target.value as DesignTheme)}
+        className={`
+          px-3 py-2 pr-8 text-sm font-medium
+          bg-[var(--color-secondary)] text-[var(--color-secondary-foreground)]
+          border-[length:var(--border-width)] border-[var(--color-border)]
+          rounded-[var(--radius-sm)]
+          cursor-pointer appearance-none
+          focus:outline-none focus:ring-2 focus:ring-[var(--color-ring)]
+        `}
+      >
+        {availableThemes.map((theme) => {
+          const { label, icon } = THEME_LABELS[theme];
+          return (
+            <option key={theme} value={theme}>
+              {icon} {label}
+            </option>
+          );
+        })}
+      </select>
+      <div className="absolute right-2 top-1/2 -translate-y-1/2 pointer-events-none">
+        <svg
+          className="w-4 h-4"
+          fill="none"
+          stroke="currentColor"
+          viewBox="0 0 24 24"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            strokeWidth={2}
+            d="M19 9l-7 7-7-7"
+          />
+        </svg>
+      </div>
+    </div>
+  );
+};
+
+export default ThemeSelector;

package/shells/typescript-shell/packages/client/src/components/atoms/ThemeToggle.tsx

@@ -0,0 +1,91 @@
+/**
+ * ThemeToggle Atom Component
+ *
+ * A button that toggles between light and dark themes.
+ * Uses Sun and Moon icons to indicate current/target theme.
+ *
+ * @packageDocumentation
+ */
+
+import React from "react";
+import { Sun, Moon } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { useTheme } from "../../context/ThemeContext";
+
+export interface ThemeToggleProps {
+  /** Additional CSS classes */
+  className?: string;
+  /** Size variant */
+  size?: "sm" | "md" | "lg";
+  /** Show label text */
+  showLabel?: boolean;
+}
+
+const sizeClasses = {
+  sm: "p-1.5",
+  md: "p-2",
+  lg: "p-2.5",
+};
+
+const iconSizes = {
+  sm: "h-4 w-4",
+  md: "h-5 w-5",
+  lg: "h-6 w-6",
+};
+
+/**
+ * ThemeToggle component for switching between light and dark modes
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ThemeToggle />
+ *
+ * // With label
+ * <ThemeToggle showLabel />
+ *
+ * // Custom size
+ * <ThemeToggle size="lg" />
+ * ```
+ */
+export const ThemeToggle: React.FC<ThemeToggleProps> = ({
+  className,
+  size = "md",
+  showLabel = false,
+}) => {
+  const { resolvedMode, toggleMode } = useTheme();
+  const isDark = resolvedMode === "dark";
+
+  return (
+    <button
+      type="button"
+      onClick={toggleMode}
+      className={cn(
+        "inline-flex items-center justify-center gap-2",
+        "text-[var(--color-foreground)]",
+        "hover:bg-[var(--color-muted)] border-[length:var(--border-width)] border-transparent hover:border-[var(--color-border)]",
+        "focus:outline-none focus:ring-2 focus:ring-[var(--color-ring)] focus:ring-offset-2",
+        "transition-colors duration-200",
+        sizeClasses[size],
+        className,
+      )}
+      aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
+      title={isDark ? "Switch to light mode" : "Switch to dark mode"}
+    >
+      {isDark ? (
+        <Sun
+          className={cn(iconSizes[size], "text-[var(--color-foreground)]")}
+        />
+      ) : (
+        <Moon
+          className={cn(iconSizes[size], "text-[var(--color-foreground)]")}
+        />
+      )}
+      {showLabel && (
+        <span className="text-sm font-medium">{isDark ? "Light" : "Dark"}</span>
+      )}
+    </button>
+  );
+};
+
+ThemeToggle.displayName = "ThemeToggle";