@almadar/cli 0.3.1 → 0.3.3

package/shells/typescript-shell/packages/client/src/context/ThemeContext.tsx

@@ -0,0 +1,321 @@
+/**
+ * Unified ThemeContext - Single provider for theme and color mode
+ *
+ * Combines design theme selection (ocean, wireframe, etc.) with
+ * color mode (light/dark) into a single, simple system.
+ *
+ * Uses a single data attribute: data-theme="ocean-light" or data-theme="ocean-dark"
+ *
+ * @packageDocumentation
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  useMemo,
+} from "react";
+
+/** Color mode preference */
+export type ColorMode = "light" | "dark" | "system";
+
+/** Resolved color mode (what's actually applied) */
+export type ResolvedMode = "light" | "dark";
+
+/** Theme definition */
+export interface ThemeDefinition {
+  /** Theme identifier (e.g., "ocean", "wireframe") */
+  name: string;
+  /** Display name for UI (e.g., "Ocean Blue") */
+  displayName?: string;
+  /** Whether this theme has light mode styles */
+  hasLightMode?: boolean;
+  /** Whether this theme has dark mode styles */
+  hasDarkMode?: boolean;
+}
+
+/** Built-in themes available in the design system */
+export const BUILT_IN_THEMES: ThemeDefinition[] = [
+  {
+    name: "wireframe",
+    displayName: "Wireframe",
+    hasLightMode: true,
+    hasDarkMode: true,
+  },
+  {
+    name: "minimalist",
+    displayName: "Minimalist",
+    hasLightMode: true,
+    hasDarkMode: true,
+  },
+  {
+    name: "almadar",
+    displayName: "Almadar",
+    hasLightMode: true,
+    hasDarkMode: true,
+  },
+];
+
+/** Theme context value */
+interface ThemeContextValue {
+  /** Current theme name */
+  theme: string;
+  /** Current color mode setting (may be 'system') */
+  mode: ColorMode;
+  /** Resolved color mode (always 'light' or 'dark') */
+  resolvedMode: ResolvedMode;
+  /** Set the theme */
+  setTheme: (theme: string) => void;
+  /** Set the color mode */
+  setMode: (mode: ColorMode) => void;
+  /** Toggle between light and dark modes */
+  toggleMode: () => void;
+  /** Available themes */
+  availableThemes: ThemeDefinition[];
+  /** The full theme string applied to data-theme (e.g., "ocean-light") */
+  appliedTheme: string;
+}
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+/** Storage keys */
+const THEME_STORAGE_KEY = "theme";
+const MODE_STORAGE_KEY = "theme-mode";
+
+/**
+ * Get the system preferred color scheme
+ */
+function getSystemMode(): ResolvedMode {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+}
+
+/**
+ * Resolve the color mode (handle 'system' preference)
+ */
+function resolveMode(mode: ColorMode): ResolvedMode {
+  if (mode === "system") {
+    return getSystemMode();
+  }
+  return mode;
+}
+
+export interface ThemeProviderProps {
+  children: React.ReactNode;
+  /** Available themes (will be merged with built-in themes) */
+  themes?: readonly ThemeDefinition[] | ThemeDefinition[];
+  /** Default theme name */
+  defaultTheme?: string;
+  /** Default color mode */
+  defaultMode?: ColorMode;
+}
+
+/**
+ * Unified ThemeProvider component
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with built-in themes
+ * <ThemeProvider defaultTheme="wireframe" defaultMode="light">
+ *   <App />
+ * </ThemeProvider>
+ *
+ * // With custom themes from almadar schema
+ * import { THEMES } from './generated/theme-manifest';
+ * <ThemeProvider themes={THEMES} defaultTheme="ocean" defaultMode="system">
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export const ThemeProvider: React.FC<ThemeProviderProps> = ({
+  children,
+  themes = [],
+  defaultTheme = "wireframe",
+  defaultMode = "system",
+}) => {
+  // Merge built-in themes with custom themes
+  const availableThemes = useMemo(() => {
+    const themeMap = new Map<string, ThemeDefinition>();
+    // Add built-in themes first
+    BUILT_IN_THEMES.forEach((t) => themeMap.set(t.name, t));
+    // Custom themes override built-in if same name
+    themes.forEach((t) => themeMap.set(t.name, t));
+    return Array.from(themeMap.values());
+  }, [themes]);
+
+  // Initialize theme from storage or default
+  const [theme, setThemeState] = useState<string>(() => {
+    if (typeof window === "undefined") return defaultTheme;
+    const stored = localStorage.getItem(THEME_STORAGE_KEY);
+    // Validate stored theme exists
+    const validThemes = [
+      ...BUILT_IN_THEMES.map((t) => t.name),
+      ...themes.map((t) => t.name),
+    ];
+    if (stored && validThemes.includes(stored)) {
+      return stored;
+    }
+    return defaultTheme;
+  });
+
+  // Initialize mode from storage or default
+  const [mode, setModeState] = useState<ColorMode>(() => {
+    if (typeof window === "undefined") return defaultMode;
+    const stored = localStorage.getItem(MODE_STORAGE_KEY);
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      return stored;
+    }
+    return defaultMode;
+  });
+
+  // Resolved mode (handles 'system' preference)
+  const [resolvedMode, setResolvedMode] = useState<ResolvedMode>(() =>
+    resolveMode(mode),
+  );
+
+  // The applied theme string (e.g., "ocean-light")
+  const appliedTheme = useMemo(
+    () => `${theme}-${resolvedMode}`,
+    [theme, resolvedMode],
+  );
+
+  // Update resolved mode when mode changes or system preference changes
+  useEffect(() => {
+    const updateResolved = () => {
+      setResolvedMode(resolveMode(mode));
+    };
+
+    updateResolved();
+
+    // Listen for system theme changes
+    if (mode === "system") {
+      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+      const handleChange = () => updateResolved();
+      mediaQuery.addEventListener("change", handleChange);
+      return () => mediaQuery.removeEventListener("change", handleChange);
+    }
+    return undefined;
+  }, [mode]);
+
+  // Apply theme to document
+  useEffect(() => {
+    const root = document.documentElement;
+    root.setAttribute("data-theme", appliedTheme);
+
+    // Also set class for Tailwind dark: variant compatibility
+    root.classList.remove("light", "dark");
+    root.classList.add(resolvedMode);
+  }, [appliedTheme, resolvedMode]);
+
+  // Set theme
+  const setTheme = useCallback(
+    (newTheme: string) => {
+      const validTheme = availableThemes.find((t) => t.name === newTheme);
+      if (validTheme) {
+        setThemeState(newTheme);
+        if (typeof window !== "undefined") {
+          localStorage.setItem(THEME_STORAGE_KEY, newTheme);
+        }
+      } else {
+        console.warn(
+          `Theme "${newTheme}" not found. Available: ${availableThemes.map((t) => t.name).join(", ")}`,
+        );
+      }
+    },
+    [availableThemes],
+  );
+
+  // Set mode
+  const setMode = useCallback((newMode: ColorMode) => {
+    setModeState(newMode);
+    if (typeof window !== "undefined") {
+      localStorage.setItem(MODE_STORAGE_KEY, newMode);
+    }
+  }, []);
+
+  // Toggle between light and dark
+  const toggleMode = useCallback(() => {
+    const newMode: ColorMode = resolvedMode === "dark" ? "light" : "dark";
+    setMode(newMode);
+  }, [resolvedMode, setMode]);
+
+  const contextValue = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      mode,
+      resolvedMode,
+      setTheme,
+      setMode,
+      toggleMode,
+      availableThemes,
+      appliedTheme,
+    }),
+    [
+      theme,
+      mode,
+      resolvedMode,
+      setTheme,
+      setMode,
+      toggleMode,
+      availableThemes,
+      appliedTheme,
+    ],
+  );
+
+  return (
+    <ThemeContext.Provider value={contextValue}>
+      {children}
+    </ThemeContext.Provider>
+  );
+};
+
+/**
+ * Hook for accessing theme context
+ *
+ * @returns Theme context value
+ *
+ * @example
+ * ```tsx
+ * const { theme, resolvedMode, toggleMode, setTheme } = useTheme();
+ *
+ * // Toggle dark mode
+ * <button onClick={toggleMode}>
+ *   {resolvedMode === 'dark' ? 'Light' : 'Dark'}
+ * </button>
+ *
+ * // Change theme
+ * <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+ *   {availableThemes.map(t => (
+ *     <option key={t.name} value={t.name}>{t.displayName || t.name}</option>
+ *   ))}
+ * </select>
+ * ```
+ */
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (context === undefined) {
+    // Return a default implementation for storybook/testing
+    return {
+      theme: "wireframe",
+      mode: "light",
+      resolvedMode: "light",
+      setTheme: () => {},
+      setMode: () => {},
+      toggleMode: () => {},
+      availableThemes: BUILT_IN_THEMES,
+      appliedTheme: "wireframe-light",
+    };
+  }
+  return context;
+}
+
+// Legacy exports for backward compatibility
+export type Theme = ColorMode;
+export type ResolvedTheme = ResolvedMode;
+export type DesignTheme = ThemeDefinition;
+
+export default ThemeContext;

package/shells/typescript-shell/packages/client/src/context/UISlotContext.tsx

@@ -0,0 +1,143 @@
+/**
+ * UISlotContext
+ *
+ * React context for providing the UI Slot Manager throughout the application.
+ * Traits use this context to render content into slots via render_ui effects.
+ *
+ * Usage:
+ * ```tsx
+ * // In App.tsx or layout
+ * <UISlotProvider>
+ *   <App />
+ * </UISlotProvider>
+ *
+ * // In trait hooks or components
+ * const { render, clear } = useUISlots();
+ * render({ target: 'modal', pattern: 'form-section', props: {...} });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import React, { createContext, useContext, useMemo } from 'react';
+import {
+  useUISlotManager,
+  type UISlotManager,
+  type UISlot,
+  type SlotContent,
+  type RenderUIConfig,
+  type SlotAnimation,
+  type SlotChangeCallback,
+} from '../hooks/useUISlots';
+
+// ============================================================================
+// Context
+// ============================================================================
+
+/**
+ * Context for the UI Slot Manager
+ */
+const UISlotContext = createContext<UISlotManager | null>(null);
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface UISlotProviderProps {
+  children: React.ReactNode;
+}
+
+/**
+ * Provider component that creates and provides the UI Slot Manager.
+ *
+ * Must wrap any components that use traits with render_ui effects.
+ */
+export function UISlotProvider({ children }: UISlotProviderProps): React.ReactElement {
+  const slotManager = useUISlotManager();
+
+  // Memoize the context value to prevent unnecessary re-renders
+  const contextValue = useMemo(() => slotManager, [slotManager]);
+
+  return (
+    <UISlotContext.Provider value={contextValue}>
+      {children}
+    </UISlotContext.Provider>
+  );
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook to access the UI Slot Manager.
+ *
+ * Must be used within a UISlotProvider.
+ *
+ * @throws Error if used outside of UISlotProvider
+ *
+ * @example
+ * ```tsx
+ * function MyTraitHook() {
+ *   const { render, clear } = useUISlots();
+ *
+ *   const showModal = () => {
+ *     render({
+ *       target: 'modal',
+ *       pattern: 'form-section',
+ *       props: { title: 'Create Item' },
+ *     });
+ *   };
+ *
+ *   const closeModal = () => {
+ *     clear('modal');
+ *   };
+ *
+ *   return { showModal, closeModal };
+ * }
+ * ```
+ */
+export function useUISlots(): UISlotManager {
+  const context = useContext(UISlotContext);
+
+  if (!context) {
+    throw new Error(
+      'useUISlots must be used within a UISlotProvider. ' +
+      'Make sure your component tree is wrapped with <UISlotProvider>.'
+    );
+  }
+
+  return context;
+}
+
+/**
+ * Hook to get content for a specific slot.
+ *
+ * Useful for components that only need to read slot state.
+ */
+export function useSlotContent(slot: UISlot): SlotContent | null {
+  const { getContent } = useUISlots();
+  return getContent(slot);
+}
+
+/**
+ * Hook to check if a slot has content.
+ */
+export function useSlotHasContent(slot: UISlot): boolean {
+  const { hasContent } = useUISlots();
+  return hasContent(slot);
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export {
+  UISlotContext,
+  type UISlotManager,
+  type UISlot,
+  type SlotContent,
+  type RenderUIConfig,
+  type SlotAnimation,
+  type SlotChangeCallback,
+};

package/shells/typescript-shell/packages/client/src/context/UserContext.tsx

@@ -0,0 +1,259 @@
+/**
+ * UserContext
+ *
+ * React context for providing user data throughout the application.
+ * Enables @user bindings in S-expressions for role-based UI and permissions.
+ *
+ * Usage:
+ * ```tsx
+ * // In App.tsx or layout
+ * <UserProvider user={{ id: '123', role: 'admin', permissions: ['read', 'write'] }}>
+ *   <App />
+ * </UserProvider>
+ *
+ * // In components - access via hook
+ * const { user, hasRole, hasPermission } = useUser();
+ * if (hasRole('admin')) { ... }
+ * if (hasPermission('delete')) { ... }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+import React, { createContext, useContext, useMemo, useCallback } from 'react';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * User data for @user bindings.
+ * Matches UserContext type from evaluator/context.ts
+ */
+export interface UserData {
+  /** User's unique ID */
+  id: string;
+  /** User's email */
+  email?: string;
+  /** User's display name */
+  name?: string;
+  /** User's role (for RBAC) */
+  role?: string;
+  /** User's permissions */
+  permissions?: string[];
+  /** Additional custom profile fields */
+  [key: string]: unknown;
+}
+
+/**
+ * User context value.
+ */
+export interface UserContextValue {
+  /** Current user data (null if not logged in) */
+  user: UserData | null;
+  /** Check if user is logged in */
+  isLoggedIn: boolean;
+  /** Check if user has a specific role */
+  hasRole: (role: string) => boolean;
+  /** Check if user has a specific permission */
+  hasPermission: (permission: string) => boolean;
+  /** Check if user has any of the specified roles */
+  hasAnyRole: (roles: string[]) => boolean;
+  /** Check if user has all of the specified permissions */
+  hasAllPermissions: (permissions: string[]) => boolean;
+  /** Get a user field by path (for @user.field bindings) */
+  getUserField: (path: string) => unknown;
+}
+
+// ============================================================================
+// Anonymous User
+// ============================================================================
+
+/**
+ * Anonymous user for when no user is logged in.
+ */
+const ANONYMOUS_USER: UserData = {
+  id: 'anonymous',
+  role: 'anonymous',
+  permissions: [],
+};
+
+// ============================================================================
+// Context
+// ============================================================================
+
+const UserContext = createContext<UserContextValue | null>(null);
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface UserProviderProps {
+  /** User data (null if not logged in) */
+  user?: UserData | null;
+  /** Children to render */
+  children: React.ReactNode;
+}
+
+/**
+ * Provider component that provides user context to the application.
+ *
+ * Provides RBAC helpers and field access for @user bindings.
+ */
+export function UserProvider({
+  user = null,
+  children,
+}: UserProviderProps): React.ReactElement {
+  // Role check helper
+  const hasRole = useCallback(
+    (role: string): boolean => {
+      if (!user) return role === 'anonymous';
+      return user.role === role;
+    },
+    [user]
+  );
+
+  // Permission check helper
+  const hasPermission = useCallback(
+    (permission: string): boolean => {
+      if (!user) return false;
+      return user.permissions?.includes(permission) ?? false;
+    },
+    [user]
+  );
+
+  // Multiple role check
+  const hasAnyRole = useCallback(
+    (roles: string[]): boolean => {
+      if (!user) return roles.includes('anonymous');
+      return user.role ? roles.includes(user.role) : false;
+    },
+    [user]
+  );
+
+  // Multiple permission check
+  const hasAllPermissions = useCallback(
+    (permissions: string[]): boolean => {
+      if (!user || !user.permissions) return false;
+      return permissions.every((p) => user.permissions?.includes(p));
+    },
+    [user]
+  );
+
+  // Field access for @user.field bindings
+  const getUserField = useCallback(
+    (path: string): unknown => {
+      const userData = user ?? ANONYMOUS_USER;
+      const parts = path.split('.');
+      let value: unknown = userData;
+
+      for (const segment of parts) {
+        if (value === null || value === undefined) {
+          return undefined;
+        }
+        if (typeof value === 'object') {
+          value = (value as Record<string, unknown>)[segment];
+        } else {
+          return undefined;
+        }
+      }
+
+      return value;
+    },
+    [user]
+  );
+
+  // Build context value
+  const contextValue = useMemo<UserContextValue>(
+    () => ({
+      user,
+      isLoggedIn: user !== null,
+      hasRole,
+      hasPermission,
+      hasAnyRole,
+      hasAllPermissions,
+      getUserField,
+    }),
+    [user, hasRole, hasPermission, hasAnyRole, hasAllPermissions, getUserField]
+  );
+
+  return <UserContext.Provider value={contextValue}>{children}</UserContext.Provider>;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook to access the user context.
+ *
+ * Returns default values if used outside of UserProvider (for resilience).
+ *
+ * @example
+ * ```tsx
+ * function AdminPanel() {
+ *   const { user, hasRole, hasPermission } = useUser();
+ *
+ *   if (!hasRole('admin') && !hasPermission('admin:access')) {
+ *     return <AccessDenied />;
+ *   }
+ *
+ *   return <div>Welcome, {user?.name}</div>;
+ * }
+ * ```
+ */
+export function useUser(): UserContextValue {
+  const context = useContext(UserContext);
+
+  // Return defaults if not in provider (for resilience)
+  if (!context) {
+    return {
+      user: null,
+      isLoggedIn: false,
+      hasRole: (role) => role === 'anonymous',
+      hasPermission: () => false,
+      hasAnyRole: (roles) => roles.includes('anonymous'),
+      hasAllPermissions: () => false,
+      getUserField: () => undefined,
+    };
+  }
+
+  return context;
+}
+
+// ============================================================================
+// Utility Hooks
+// ============================================================================
+
+/**
+ * Hook to check if user has a specific role.
+ * Convenience wrapper around useUser().hasRole().
+ */
+export function useHasRole(role: string): boolean {
+  const { hasRole } = useUser();
+  return hasRole(role);
+}
+
+/**
+ * Hook to check if user has a specific permission.
+ * Convenience wrapper around useUser().hasPermission().
+ */
+export function useHasPermission(permission: string): boolean {
+  const { hasPermission } = useUser();
+  return hasPermission(permission);
+}
+
+/**
+ * Hook to get user data for @user bindings in S-expressions.
+ * Returns the user data object compatible with EvaluationContext.user
+ */
+export function useUserForEvaluation(): UserData | undefined {
+  const { user, isLoggedIn } = useUser();
+  return isLoggedIn && user ? user : undefined;
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { UserContext, ANONYMOUS_USER };