@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/components/organisms/PageHeader.tsx

@@ -0,0 +1,244 @@
+import React from "react";
+import { cn } from "../../lib/cn";
+import { Button } from "../atoms";
+import { ArrowLeft, LucideIcon } from "lucide-react";
+import { useNavigate, useParams } from "react-router-dom";
+import { useEventBus } from "../../hooks/useEventBus";
+
+export interface PageBreadcrumb {
+  label: string;
+  href?: string;
+}
+
+/**
+ * Schema-based action definition
+ */
+export interface SchemaAction {
+  label: string;
+  /** Navigate to URL when clicked */
+  navigatesTo?: string;
+  /** Custom click handler */
+  onClick?: () => void;
+  /** Event to dispatch via event bus (for trait state machine integration) */
+  event?: string;
+  variant?: "primary" | "secondary" | "ghost" | "danger";
+  icon?: LucideIcon;
+  loading?: boolean;
+  disabled?: boolean;
+}
+
+export interface PageHeaderProps {
+  /** Page title - accepts unknown to handle generated code accessing dynamic entity data */
+  title?: string | number | unknown;
+  /** Optional subtitle/description */
+  subtitle?: string | number | unknown;
+  /** Show back button */
+  showBack?: boolean;
+  /** Event to emit when back is clicked (default: BACK) */
+  backEvent?: string;
+  /** Breadcrumbs */
+  breadcrumbs?: readonly PageBreadcrumb[];
+  /** Status badge */
+  status?: {
+    label: string;
+    variant?: "default" | "success" | "warning" | "danger" | "info";
+  };
+  /** Actions array - first action with variant='primary' (or first action) is the main action */
+  actions?: readonly Readonly<SchemaAction>[];
+  /** Loading state indicator */
+  isLoading?: boolean;
+  /** Tabs for sub-navigation */
+  tabs?: ReadonlyArray<{
+    label: string;
+    value: string;
+    count?: number;
+  }>;
+  activeTab?: string;
+  onTabChange?: (value: string) => void;
+  /** Custom content in the header */
+  children?: React.ReactNode;
+  className?: string;
+}
+
+export const PageHeader: React.FC<PageHeaderProps> = ({
+  title,
+  subtitle,
+  showBack = false,
+  backEvent = "BACK",
+  breadcrumbs,
+  status,
+  actions,
+  isLoading,
+  tabs,
+  activeTab,
+  onTabChange,
+  children,
+  className,
+}) => {
+  const navigate = useNavigate();
+  const params = useParams();
+  const eventBus = useEventBus();
+
+  const handleBack = () => {
+    // Emit event for trait state machine to handle
+    // The trait can transition state and/or trigger navigate effect
+    eventBus.emit(`UI:${backEvent}`);
+  };
+
+  /**
+   * Replace template placeholders like {{id}} with actual URL params.
+   * E.g., "/tasks/{{id}}/edit" with params {id: "123"} becomes "/tasks/123/edit"
+   */
+  const replacePlaceholders = (url: string): string => {
+    return url.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+      return String(params[key] || "");
+    });
+  };
+
+  // Create click handler for schema actions
+  const createActionHandler = (action: SchemaAction) => () => {
+    // Emit event via event bus if defined (for trait state machine integration)
+    if (action.event) {
+      eventBus.emit(`UI:${action.event}`);
+    }
+    if (action.navigatesTo) {
+      const resolvedUrl = replacePlaceholders(action.navigatesTo);
+      navigate(resolvedUrl);
+    }
+    if (action.onClick) {
+      action.onClick();
+    }
+  };
+
+  const statusColors = {
+    default: "bg-[var(--color-muted)] text-[var(--color-foreground)]",
+    success: "bg-[var(--color-success)]/10 text-[var(--color-success)]",
+    warning: "bg-[var(--color-warning)]/10 text-[var(--color-warning)]",
+    danger: "bg-[var(--color-error)]/10 text-[var(--color-error)]",
+    info: "bg-[var(--color-info)]/10 text-[var(--color-info)]",
+  };
+
+  return (
+    <div className={cn("mb-6", className)}>
+      {/* Breadcrumbs */}
+      {breadcrumbs && breadcrumbs.length > 0 && (
+        <nav className="mb-4">
+          <ol className="flex items-center gap-2 text-sm">
+            {breadcrumbs.map((crumb, idx) => (
+              <React.Fragment key={idx}>
+                {idx > 0 && (
+                  <span className="text-[var(--color-muted-foreground)]">
+                    /
+                  </span>
+                )}
+                {crumb.href ? (
+                  <a
+                    href={crumb.href}
+                    className="text-[var(--color-muted-foreground)] hover:text-[var(--color-foreground)]"
+                  >
+                    {crumb.label}
+                  </a>
+                ) : (
+                  <span className="text-[var(--color-foreground)] font-medium">
+                    {crumb.label}
+                  </span>
+                )}
+              </React.Fragment>
+            ))}
+          </ol>
+        </nav>
+      )}
+
+      {/* Main header row */}
+      <div className="flex items-start justify-between gap-4">
+        <div className="flex items-start gap-4">
+          {showBack && (
+            <button
+              onClick={handleBack}
+              className="mt-1 p-2 rounded-[var(--radius-lg)] hover:bg-[var(--color-muted)] transition-colors"
+            >
+              <ArrowLeft className="h-5 w-5 text-[var(--color-muted-foreground)]" />
+            </button>
+          )}
+          <div>
+            <div className="flex items-center gap-3">
+              <h1 className="text-2xl font-bold text-[var(--color-foreground)]">
+                {title != null ? String(title) : ""}
+              </h1>
+              {status && (
+                <span
+                  className={cn(
+                    "px-2.5 py-1 rounded-[var(--radius-full)] text-xs font-medium",
+                    statusColors[status.variant || "default"],
+                  )}
+                >
+                  {status.label}
+                </span>
+              )}
+            </div>
+            {subtitle != null && subtitle !== "" && (
+              <p className="mt-1 text-sm text-[var(--color-muted-foreground)]">
+                {String(subtitle)}
+              </p>
+            )}
+          </div>
+        </div>
+
+        {/* Actions */}
+        <div className="flex items-center gap-2 shrink-0">
+          {actions?.map((action, idx) => (
+            <Button
+              key={`action-${idx}`}
+              data-event={action.event}
+              data-testid={action.event ? `action-${action.event}` : undefined}
+              variant={action.variant || (idx === 0 ? "primary" : "secondary")}
+              leftIcon={action.icon && <action.icon className="h-4 w-4" />}
+              onClick={createActionHandler(action)}
+              isLoading={action.loading || isLoading}
+              disabled={action.disabled || isLoading}
+            >
+              {action.label}
+            </Button>
+          ))}
+        </div>
+      </div>
+
+      {/* Tabs */}
+      {tabs && tabs.length > 0 && (
+        <div className="mt-6 border-b border-[var(--color-border)]">
+          <nav className="flex gap-6">
+            {tabs.map((tab) => (
+              <button
+                key={tab.value}
+                onClick={() => onTabChange?.(tab.value)}
+                className={cn(
+                  "pb-3 text-sm font-bold border-b-2 transition-colors rounded-none",
+                  activeTab === tab.value
+                    ? "border-[var(--color-primary)] text-[var(--color-foreground)]"
+                    : "border-transparent text-[var(--color-muted-foreground)] hover:text-[var(--color-foreground)] hover:border-[var(--color-border)]",
+                )}
+              >
+                {tab.label}
+                {tab.count !== undefined && (
+                  <span
+                    className={cn(
+                      "ml-2 px-2 py-0.5 rounded-[var(--radius-full)] text-xs",
+                      activeTab === tab.value
+                        ? "bg-[var(--color-primary)]/10 text-[var(--color-primary)]"
+                        : "bg-[var(--color-muted)] text-[var(--color-muted-foreground)]",
+                    )}
+                  >
+                    {tab.count}
+                  </span>
+                )}
+              </button>
+            ))}
+          </nav>
+        </div>
+      )}
+
+      {/* Custom content */}
+      {children}
+    </div>
+  );
+};

package/shells/typescript-shell/packages/client/src/components/organisms/Section.tsx

@@ -0,0 +1,131 @@
+/**
+ * Section Component
+ * 
+ * A semantic section wrapper with optional title, description, and action.
+ * Perfect for grouping related content with consistent spacing.
+ */
+import React from 'react';
+import { cn } from '../../lib/cn';
+import { Typography } from '../atoms/Typography';
+
+export type SectionPadding = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+export type SectionVariant = 'default' | 'card' | 'bordered' | 'filled';
+
+export interface SectionProps {
+  /** Section title */
+  title?: string;
+  /** Section subtitle/description */
+  description?: string;
+  /** Action element (e.g., button, link) */
+  action?: React.ReactNode;
+  /** Padding amount */
+  padding?: SectionPadding;
+  /** Visual variant */
+  variant?: SectionVariant;
+  /** Show divider below header */
+  divider?: boolean;
+  /** Custom class name */
+  className?: string;
+  /** Children elements */
+  children: React.ReactNode;
+  /** Header custom class name */
+  headerClassName?: string;
+  /** Content custom class name */
+  contentClassName?: string;
+  /** HTML element to render as */
+  as?: React.ElementType;
+}
+
+const paddingStyles: Record<SectionPadding, string> = {
+  none: 'p-0',
+  sm: 'p-3',
+  md: 'p-4',
+  lg: 'p-6',
+  xl: 'p-8',
+};
+
+// Using CSS variables for theme-aware styling
+const variantStyles: Record<SectionVariant, string> = {
+  default: '',
+  card: [
+    'bg-[var(--color-card)]',
+    'border-[length:var(--border-width)] border-[var(--color-border)]',
+    'shadow-[var(--shadow-main)]',
+    'rounded-[var(--radius-md)]',
+  ].join(' '),
+  bordered: [
+    'border-[length:var(--border-width)] border-[var(--color-border)]',
+    'rounded-[var(--radius-md)]',
+  ].join(' '),
+  filled: 'bg-[var(--color-muted)] rounded-[var(--radius-md)]',
+};
+
+/**
+ * Section - Semantic content grouping with header
+ */
+export const Section: React.FC<SectionProps> = ({
+  title,
+  description,
+  action,
+  padding = 'md',
+  variant = 'default',
+  divider = false,
+  className,
+  children,
+  headerClassName,
+  contentClassName,
+  as: Component = 'section',
+}) => {
+  const hasHeader = title || description || action;
+
+  return (
+    <Component
+      className={cn(
+        paddingStyles[padding],
+        variantStyles[variant],
+        className
+      )}
+    >
+      {hasHeader && (
+        <div
+          className={cn(
+            'flex flex-col sm:flex-row sm:items-start sm:justify-between gap-2 sm:gap-4',
+            divider && 'pb-4 mb-4 border-b-[length:var(--border-width)] border-[var(--color-border)]',
+            !divider && 'mb-4',
+            headerClassName
+          )}
+        >
+          <div className="flex-1 min-w-0">
+            {title && (
+              <Typography
+                variant="h4"
+                className="text-[var(--color-foreground)] font-semibold"
+              >
+                {title}
+              </Typography>
+            )}
+            {description && (
+              <Typography
+                variant="body"
+                color="muted"
+                className="mt-1"
+              >
+                {description}
+              </Typography>
+            )}
+          </div>
+          {action && (
+            <div className="flex-shrink-0 flex items-center gap-2">
+              {action}
+            </div>
+          )}
+        </div>
+      )}
+      <div className={contentClassName}>
+        {children}
+      </div>
+    </Component>
+  );
+};
+
+export default Section;

package/shells/typescript-shell/packages/client/src/components/organisms/Sidebar.tsx

@@ -0,0 +1,270 @@
+/**
+ * Sidebar Organism Component
+ * 
+ * A sidebar component with logo, navigation items, user section, and collapse/expand.
+ * Styled to match the main Layout component with theme-aware CSS variables.
+ */
+
+import React, { useState } from 'react';
+import type { LucideIcon } from 'lucide-react';
+import { ChevronLeft, ChevronRight, X } from 'lucide-react';
+import { Badge } from '../atoms/Badge';
+import { cn } from '../../lib/cn';
+
+export interface SidebarItem {
+  /** Item ID */
+  id: string;
+  /** Item label */
+  label: string;
+  /** Item icon */
+  icon?: LucideIcon;
+  /** Item badge */
+  badge?: string | number;
+  /** Item href */
+  href?: string;
+  /** Item click handler */
+  onClick?: () => void;
+  /** Is active */
+  active?: boolean;
+  /** @deprecated Use `active` instead */
+  isActive?: boolean;
+  /** Sub-items (for nested navigation) */
+  subItems?: SidebarItem[];
+}
+
+export interface SidebarProps {
+  /** Logo/Brand content - can be a ReactNode or logo config */
+  logo?: React.ReactNode;
+  /** Logo image source */
+  logoSrc?: string;
+  /** Brand/App name */
+  brandName?: string;
+  /** Navigation items */
+  items: SidebarItem[];
+  /** User section content */
+  userSection?: React.ReactNode;
+  /** Footer content (e.g., theme toggle) */
+  footerContent?: React.ReactNode;
+  /** Collapsed state (controlled) */
+  collapsed?: boolean;
+  /** Default collapsed state */
+  defaultCollapsed?: boolean;
+  /** Callback when collapse state changes */
+  onCollapseChange?: (collapsed: boolean) => void;
+  /** Hide the collapse/expand button */
+  hideCollapseButton?: boolean;
+  /** Show a close button (for mobile) */
+  showCloseButton?: boolean;
+  /** Callback when close button is clicked */
+  onClose?: () => void;
+  /** Callback when logo/brand is clicked */
+  onLogoClick?: () => void;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * Single navigation item component
+ */
+const SidebarNavItem: React.FC<{
+  item: SidebarItem;
+  collapsed: boolean;
+}> = ({ item, collapsed }) => {
+  const Icon = item.icon;
+  const isActive = item.active ?? item.isActive;
+
+  return (
+    <button
+      onClick={item.onClick}
+      className={cn(
+        'w-full flex items-center gap-3 px-3 py-2.5 transition-all duration-[var(--transition-fast)] group relative',
+        'rounded-[var(--radius-sm)] border-[length:var(--border-width-thin)] border-transparent',
+        isActive
+          ? [
+            'bg-[var(--color-foreground)] text-[var(--color-background)]',
+            'font-medium shadow-[var(--shadow-sm)]',
+            'border-[var(--color-border)] translate-x-1 -translate-y-0.5',
+          ].join(' ')
+          : [
+            'text-[var(--color-foreground)]',
+            'hover:bg-[var(--color-muted)] hover:border-[var(--color-border)]',
+            'active:bg-[var(--color-foreground)] active:text-[var(--color-background)]',
+          ].join(' ')
+      )}
+      title={collapsed ? item.label : undefined}
+    >
+      {Icon && (
+        <Icon
+          size={20}
+          className={cn(
+            'min-w-[20px] flex-shrink-0',
+            isActive && 'text-[var(--color-background)]'
+          )}
+        />
+      )}
+
+      {!collapsed && (
+        <span className="font-medium truncate flex-1 text-left">{item.label}</span>
+      )}
+
+      {!collapsed && item.badge !== undefined && (
+        <Badge variant="danger" size="sm">{item.badge}</Badge>
+      )}
+
+      {/* Tooltip for collapsed state */}
+      {collapsed && (
+        <div className={cn(
+          'absolute left-full ml-2 px-2 py-1 text-xs opacity-0 group-hover:opacity-100',
+          'pointer-events-none whitespace-nowrap z-50 transition-opacity',
+          'bg-[var(--color-primary)] text-[var(--color-primary-foreground)]',
+          'border-[length:var(--border-width-thin)] border-[var(--color-border)]',
+          'rounded-[var(--radius-sm)]'
+        )}>
+          {item.label}
+        </div>
+      )}
+    </button>
+  );
+};
+
+export const Sidebar: React.FC<SidebarProps> = ({
+  logo,
+  logoSrc,
+  brandName = 'KFlow',
+  items,
+  userSection,
+  footerContent,
+  collapsed: controlledCollapsed,
+  defaultCollapsed = false,
+  onCollapseChange,
+  hideCollapseButton = false,
+  showCloseButton = false,
+  onClose,
+  onLogoClick,
+  className,
+}) => {
+  const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
+  const collapsed = controlledCollapsed !== undefined ? controlledCollapsed : internalCollapsed;
+
+  const handleToggle = () => {
+    const newCollapsed = !collapsed;
+    if (controlledCollapsed === undefined) {
+      setInternalCollapsed(newCollapsed);
+    }
+    onCollapseChange?.(newCollapsed);
+  };
+
+  return (
+    <aside
+      className={cn(
+        'flex flex-col h-full',
+        'bg-[var(--color-card)] border-r border-[var(--color-border)]',
+        'transition-all duration-300 ease-in-out',
+        collapsed ? 'w-20' : 'w-64',
+        className
+      )}
+    >
+      {/* Header with Logo */}
+      <div className="h-16 flex items-center justify-between px-4 border-b border-[var(--color-border)] flex-shrink-0">
+        <div
+          className={cn(
+            'flex items-center gap-3 cursor-pointer',
+            collapsed && 'justify-center w-full'
+          )}
+          onClick={onLogoClick}
+        >
+          {/* Logo image or custom logo */}
+          {logo ? (
+            typeof logo === 'string' ? (
+              <img src={logo} alt={brandName} className="h-8 w-8" />
+            ) : (
+              logo
+            )
+          ) : logoSrc ? (
+            <img src={logoSrc} alt={brandName} className="h-8 w-8" />
+          ) : (
+            <div className="h-8 w-8 bg-[var(--color-primary)] flex items-center justify-center rounded-[var(--radius-sm)]">
+              <span className="text-[var(--color-primary-foreground)] font-bold text-sm">K</span>
+            </div>
+          )}
+
+          {/* Brand name */}
+          {!collapsed && (
+            <span className="text-xl font-bold text-[var(--color-foreground)]">
+              {brandName}
+            </span>
+          )}
+        </div>
+
+        {/* Collapse button */}
+        {!hideCollapseButton && (
+          <button
+            onClick={handleToggle}
+            className={cn(
+              'p-1.5 hover:bg-[var(--color-muted)] text-[var(--color-foreground)] hidden lg:block',
+              'rounded-[var(--radius-sm)]',
+              collapsed && 'mx-auto'
+            )}
+            title={collapsed ? "Expand Sidebar" : "Collapse Sidebar"}
+          >
+            {collapsed ? <ChevronRight size={18} /> : <ChevronLeft size={18} />}
+          </button>
+        )}
+
+        {/* Close button for mobile */}
+        {showCloseButton && (
+          <button
+            onClick={onClose}
+            className="p-1.5 hover:bg-[var(--color-muted)] text-[var(--color-foreground)] lg:hidden rounded-[var(--radius-sm)]"
+            aria-label="Close sidebar"
+          >
+            <X size={18} />
+          </button>
+        )}
+      </div>
+
+      {/* Navigation */}
+      <nav className="flex-1 py-6 px-3 space-y-1 overflow-y-auto">
+        {items.map((item) => (
+          <SidebarNavItem
+            key={item.id}
+            item={item}
+            collapsed={collapsed}
+          />
+        ))}
+      </nav>
+
+      {/* Footer with User Section and additional content */}
+      {(footerContent || userSection) && (
+        <div className="p-3 border-t border-[var(--color-border)] space-y-1 flex-shrink-0">
+          <div className={cn(
+            'flex items-center',
+            collapsed ? 'justify-center flex-col gap-4' : 'justify-between px-2'
+          )}>
+            {footerContent && (
+              <div className="flex items-center">
+                {footerContent}
+              </div>
+            )}
+            {userSection && (
+              <div className="flex items-center">
+                {userSection}
+              </div>
+            )}
+          </div>
+
+          {collapsed && !hideCollapseButton && (
+            <button
+              onClick={handleToggle}
+              className="w-full flex justify-center p-2 mt-2 text-[var(--color-muted-foreground)] hover:text-[var(--color-foreground)] lg:hidden"
+            >
+              <ChevronRight size={20} />
+            </button>
+          )}
+        </div>
+      )}
+    </aside>
+  );
+};
+
+Sidebar.displayName = 'Sidebar';