@almadar/ui 1.0.0

package/dist/context/index.d.ts

@@ -0,0 +1,208 @@
+import * as React from 'react';
+import React__default from 'react';
+import { U as UISlotManager, a as UISlot, S as SlotContent } from '../useUISlots-mnggE9X9.js';
+export { R as RenderUIConfig, b as SlotAnimation, c as SlotChangeCallback } from '../useUISlots-mnggE9X9.js';
+import { T as ThemeProviderProps } from '../ThemeContext-lI5bo85E.js';
+export { B as BUILT_IN_THEMES, C as ColorMode, D as DesignTheme, R as ResolvedMode, a as ThemeContext, b as ThemeDefinition, c as ThemeProvider, u as useTheme } from '../ThemeContext-lI5bo85E.js';
+
+/**
+ * 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
+ */
+
+/**
+ * Context for the UI Slot Manager
+ */
+declare const UISlotContext: React__default.Context<UISlotManager | null>;
+interface UISlotProviderProps {
+    children: React__default.ReactNode;
+}
+/**
+ * Provider component that creates and provides the UI Slot Manager.
+ *
+ * Must wrap any components that use traits with render_ui effects.
+ */
+declare function UISlotProvider({ children }: UISlotProviderProps): React__default.ReactElement;
+/**
+ * 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 };
+ * }
+ * ```
+ */
+declare function useUISlots(): UISlotManager;
+/**
+ * Hook to get content for a specific slot.
+ *
+ * Useful for components that only need to read slot state.
+ */
+declare function useSlotContent(slot: UISlot): SlotContent | null;
+/**
+ * Hook to check if a slot has content.
+ */
+declare function useSlotHasContent(slot: UISlot): boolean;
+
+/**
+ * @deprecated Use ThemeProvider from ThemeContext instead
+ */
+declare const DesignThemeProvider: React.FC<ThemeProviderProps>;
+/**
+ * @deprecated Use useTheme from ThemeContext instead
+ *
+ * This wrapper provides backward compatibility with the old API.
+ */
+declare function useDesignTheme(): {
+    designTheme: string;
+    setDesignTheme: (theme: string) => void;
+    availableThemes: string[];
+};
+
+/**
+ * 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
+ */
+
+/**
+ * User data for @user bindings.
+ * Matches UserContext type from evaluator/context.ts
+ */
+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.
+ */
+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 for when no user is logged in.
+ */
+declare const ANONYMOUS_USER: UserData;
+declare const UserContext: React__default.Context<UserContextValue | null>;
+interface UserProviderProps {
+    /** User data (null if not logged in) */
+    user?: UserData | null;
+    /** Children to render */
+    children: React__default.ReactNode;
+}
+/**
+ * Provider component that provides user context to the application.
+ *
+ * Provides RBAC helpers and field access for @user bindings.
+ */
+declare function UserProvider({ user, children, }: UserProviderProps): React__default.ReactElement;
+/**
+ * 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>;
+ * }
+ * ```
+ */
+declare function useUser(): UserContextValue;
+/**
+ * Hook to check if user has a specific role.
+ * Convenience wrapper around useUser().hasRole().
+ */
+declare function useHasRole(role: string): boolean;
+/**
+ * Hook to check if user has a specific permission.
+ * Convenience wrapper around useUser().hasPermission().
+ */
+declare function useHasPermission(permission: string): boolean;
+/**
+ * Hook to get user data for @user bindings in S-expressions.
+ * Returns the user data object compatible with EvaluationContext.user
+ */
+declare function useUserForEvaluation(): UserData | undefined;
+
+export { ANONYMOUS_USER, DesignThemeProvider, SlotContent, ThemeProviderProps, UISlot, UISlotContext, UISlotManager, UISlotProvider, UserContext, type UserContextValue, type UserData, UserProvider, type UserProviderProps, useDesignTheme, useHasPermission, useHasRole, useSlotContent, useSlotHasContent, useUISlots, useUser, useUserForEvaluation };

package/dist/context/index.js

@@ -0,0 +1,443 @@
+import { createContext, useMemo, useContext, useState, useEffect, useCallback, useRef } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+// context/UISlotContext.tsx
+var DEFAULT_SLOTS = {
+  main: null,
+  sidebar: null,
+  modal: null,
+  drawer: null,
+  overlay: null,
+  center: null,
+  toast: null,
+  "hud-top": null,
+  "hud-bottom": null,
+  floating: null
+};
+var idCounter = 0;
+function generateId() {
+  return `slot-content-${++idCounter}-${Date.now()}`;
+}
+function useUISlotManager() {
+  const [slots, setSlots] = useState(DEFAULT_SLOTS);
+  const subscribersRef = useRef(/* @__PURE__ */ new Set());
+  const timersRef = useRef(/* @__PURE__ */ new Map());
+  useEffect(() => {
+    return () => {
+      timersRef.current.forEach((timer) => clearTimeout(timer));
+      timersRef.current.clear();
+    };
+  }, []);
+  const notifySubscribers = useCallback((slot, content) => {
+    subscribersRef.current.forEach((callback) => {
+      try {
+        callback(slot, content);
+      } catch (error) {
+        console.error("[UISlots] Subscriber error:", error);
+      }
+    });
+  }, []);
+  const render = useCallback((config) => {
+    const id = generateId();
+    const content = {
+      id,
+      pattern: config.pattern,
+      props: config.props ?? {},
+      priority: config.priority ?? 0,
+      animation: config.animation ?? "fade",
+      onDismiss: config.onDismiss,
+      sourceTrait: config.sourceTrait
+    };
+    if (config.autoDismissMs && config.autoDismissMs > 0) {
+      content.autoDismissAt = Date.now() + config.autoDismissMs;
+      const timer = setTimeout(() => {
+        setSlots((prev) => {
+          if (prev[config.target]?.id === id) {
+            content.onDismiss?.();
+            notifySubscribers(config.target, null);
+            return { ...prev, [config.target]: null };
+          }
+          return prev;
+        });
+        timersRef.current.delete(id);
+      }, config.autoDismissMs);
+      timersRef.current.set(id, timer);
+    }
+    setSlots((prev) => {
+      const existing = prev[config.target];
+      if (existing && existing.priority > content.priority) {
+        console.warn(
+          `[UISlots] Slot "${config.target}" already has higher priority content (${existing.priority} > ${content.priority})`
+        );
+        return prev;
+      }
+      notifySubscribers(config.target, content);
+      return { ...prev, [config.target]: content };
+    });
+    return id;
+  }, [notifySubscribers]);
+  const clear = useCallback((slot) => {
+    setSlots((prev) => {
+      const content = prev[slot];
+      if (content) {
+        const timer = timersRef.current.get(content.id);
+        if (timer) {
+          clearTimeout(timer);
+          timersRef.current.delete(content.id);
+        }
+        content.onDismiss?.();
+        notifySubscribers(slot, null);
+      }
+      return { ...prev, [slot]: null };
+    });
+  }, [notifySubscribers]);
+  const clearById = useCallback((id) => {
+    setSlots((prev) => {
+      const entry = Object.entries(prev).find(([, content]) => content?.id === id);
+      if (entry) {
+        const [slot, content] = entry;
+        const timer = timersRef.current.get(id);
+        if (timer) {
+          clearTimeout(timer);
+          timersRef.current.delete(id);
+        }
+        content.onDismiss?.();
+        notifySubscribers(slot, null);
+        return { ...prev, [slot]: null };
+      }
+      return prev;
+    });
+  }, [notifySubscribers]);
+  const clearAll = useCallback(() => {
+    timersRef.current.forEach((timer) => clearTimeout(timer));
+    timersRef.current.clear();
+    setSlots((prev) => {
+      Object.entries(prev).forEach(([slot, content]) => {
+        if (content) {
+          content.onDismiss?.();
+          notifySubscribers(slot, null);
+        }
+      });
+      return DEFAULT_SLOTS;
+    });
+  }, [notifySubscribers]);
+  const subscribe = useCallback((callback) => {
+    subscribersRef.current.add(callback);
+    return () => {
+      subscribersRef.current.delete(callback);
+    };
+  }, []);
+  const hasContent = useCallback((slot) => {
+    return slots[slot] !== null;
+  }, [slots]);
+  const getContent = useCallback((slot) => {
+    return slots[slot];
+  }, [slots]);
+  return {
+    slots,
+    render,
+    clear,
+    clearById,
+    clearAll,
+    subscribe,
+    hasContent,
+    getContent
+  };
+}
+var UISlotContext = createContext(null);
+function UISlotProvider({ children }) {
+  const slotManager = useUISlotManager();
+  const contextValue = useMemo(() => slotManager, [slotManager]);
+  return /* @__PURE__ */ jsx(UISlotContext.Provider, { value: contextValue, children });
+}
+function useUISlots() {
+  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;
+}
+function useSlotContent(slot) {
+  const { getContent } = useUISlots();
+  return getContent(slot);
+}
+function useSlotHasContent(slot) {
+  const { hasContent } = useUISlots();
+  return hasContent(slot);
+}
+var BUILT_IN_THEMES = [
+  {
+    name: "wireframe",
+    displayName: "Wireframe",
+    hasLightMode: true,
+    hasDarkMode: true
+  },
+  {
+    name: "minimalist",
+    displayName: "Minimalist",
+    hasLightMode: true,
+    hasDarkMode: true
+  },
+  {
+    name: "almadar",
+    displayName: "Almadar",
+    hasLightMode: true,
+    hasDarkMode: true
+  }
+];
+var ThemeContext = createContext(void 0);
+var THEME_STORAGE_KEY = "theme";
+var MODE_STORAGE_KEY = "theme-mode";
+function getSystemMode() {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function resolveMode(mode) {
+  if (mode === "system") {
+    return getSystemMode();
+  }
+  return mode;
+}
+var ThemeProvider = ({
+  children,
+  themes = [],
+  defaultTheme = "wireframe",
+  defaultMode = "system"
+}) => {
+  const availableThemes = useMemo(() => {
+    const themeMap = /* @__PURE__ */ new Map();
+    BUILT_IN_THEMES.forEach((t) => themeMap.set(t.name, t));
+    themes.forEach((t) => themeMap.set(t.name, t));
+    return Array.from(themeMap.values());
+  }, [themes]);
+  const [theme, setThemeState] = useState(() => {
+    if (typeof window === "undefined") return defaultTheme;
+    const stored = localStorage.getItem(THEME_STORAGE_KEY);
+    const validThemes = [
+      ...BUILT_IN_THEMES.map((t) => t.name),
+      ...themes.map((t) => t.name)
+    ];
+    if (stored && validThemes.includes(stored)) {
+      return stored;
+    }
+    return defaultTheme;
+  });
+  const [mode, setModeState] = useState(() => {
+    if (typeof window === "undefined") return defaultMode;
+    const stored = localStorage.getItem(MODE_STORAGE_KEY);
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      return stored;
+    }
+    return defaultMode;
+  });
+  const [resolvedMode, setResolvedMode] = useState(
+    () => resolveMode(mode)
+  );
+  const appliedTheme = useMemo(
+    () => `${theme}-${resolvedMode}`,
+    [theme, resolvedMode]
+  );
+  useEffect(() => {
+    const updateResolved = () => {
+      setResolvedMode(resolveMode(mode));
+    };
+    updateResolved();
+    if (mode === "system") {
+      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+      const handleChange = () => updateResolved();
+      mediaQuery.addEventListener("change", handleChange);
+      return () => mediaQuery.removeEventListener("change", handleChange);
+    }
+    return void 0;
+  }, [mode]);
+  useEffect(() => {
+    const root = document.documentElement;
+    root.setAttribute("data-theme", appliedTheme);
+    root.classList.remove("light", "dark");
+    root.classList.add(resolvedMode);
+  }, [appliedTheme, resolvedMode]);
+  const setTheme = useCallback(
+    (newTheme) => {
+      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]
+  );
+  const setMode = useCallback((newMode) => {
+    setModeState(newMode);
+    if (typeof window !== "undefined") {
+      localStorage.setItem(MODE_STORAGE_KEY, newMode);
+    }
+  }, []);
+  const toggleMode = useCallback(() => {
+    const newMode = resolvedMode === "dark" ? "light" : "dark";
+    setMode(newMode);
+  }, [resolvedMode, setMode]);
+  const contextValue = useMemo(
+    () => ({
+      theme,
+      mode,
+      resolvedMode,
+      setTheme,
+      setMode,
+      toggleMode,
+      availableThemes,
+      appliedTheme
+    }),
+    [
+      theme,
+      mode,
+      resolvedMode,
+      setTheme,
+      setMode,
+      toggleMode,
+      availableThemes,
+      appliedTheme
+    ]
+  );
+  return /* @__PURE__ */ jsx(ThemeContext.Provider, { value: contextValue, children });
+};
+function useTheme() {
+  const context = useContext(ThemeContext);
+  if (context === void 0) {
+    return {
+      theme: "wireframe",
+      mode: "light",
+      resolvedMode: "light",
+      setTheme: () => {
+      },
+      setMode: () => {
+      },
+      toggleMode: () => {
+      },
+      availableThemes: BUILT_IN_THEMES,
+      appliedTheme: "wireframe-light"
+    };
+  }
+  return context;
+}
+var ThemeContext_default = ThemeContext;
+
+// context/DesignThemeContext.tsx
+var DesignThemeProvider = ThemeProvider;
+function useDesignTheme() {
+  const { theme, setTheme, availableThemes } = useTheme();
+  return {
+    designTheme: theme,
+    setDesignTheme: setTheme,
+    availableThemes: availableThemes.map((t) => t.name)
+  };
+}
+var ANONYMOUS_USER = {
+  id: "anonymous",
+  role: "anonymous",
+  permissions: []
+};
+var UserContext = createContext(null);
+function UserProvider({
+  user = null,
+  children
+}) {
+  const hasRole = useCallback(
+    (role) => {
+      if (!user) return role === "anonymous";
+      return user.role === role;
+    },
+    [user]
+  );
+  const hasPermission = useCallback(
+    (permission) => {
+      if (!user) return false;
+      return user.permissions?.includes(permission) ?? false;
+    },
+    [user]
+  );
+  const hasAnyRole = useCallback(
+    (roles) => {
+      if (!user) return roles.includes("anonymous");
+      return user.role ? roles.includes(user.role) : false;
+    },
+    [user]
+  );
+  const hasAllPermissions = useCallback(
+    (permissions) => {
+      if (!user || !user.permissions) return false;
+      return permissions.every((p) => user.permissions?.includes(p));
+    },
+    [user]
+  );
+  const getUserField = useCallback(
+    (path) => {
+      const userData = user ?? ANONYMOUS_USER;
+      const parts = path.split(".");
+      let value = userData;
+      for (const segment of parts) {
+        if (value === null || value === void 0) {
+          return void 0;
+        }
+        if (typeof value === "object") {
+          value = value[segment];
+        } else {
+          return void 0;
+        }
+      }
+      return value;
+    },
+    [user]
+  );
+  const contextValue = useMemo(
+    () => ({
+      user,
+      isLoggedIn: user !== null,
+      hasRole,
+      hasPermission,
+      hasAnyRole,
+      hasAllPermissions,
+      getUserField
+    }),
+    [user, hasRole, hasPermission, hasAnyRole, hasAllPermissions, getUserField]
+  );
+  return /* @__PURE__ */ jsx(UserContext.Provider, { value: contextValue, children });
+}
+function useUser() {
+  const context = useContext(UserContext);
+  if (!context) {
+    return {
+      user: null,
+      isLoggedIn: false,
+      hasRole: (role) => role === "anonymous",
+      hasPermission: () => false,
+      hasAnyRole: (roles) => roles.includes("anonymous"),
+      hasAllPermissions: () => false,
+      getUserField: () => void 0
+    };
+  }
+  return context;
+}
+function useHasRole(role) {
+  const { hasRole } = useUser();
+  return hasRole(role);
+}
+function useHasPermission(permission) {
+  const { hasPermission } = useUser();
+  return hasPermission(permission);
+}
+function useUserForEvaluation() {
+  const { user, isLoggedIn } = useUser();
+  return isLoggedIn && user ? user : void 0;
+}
+
+export { ANONYMOUS_USER, BUILT_IN_THEMES, DesignThemeProvider, ThemeContext_default as ThemeContext, ThemeProvider, UISlotContext, UISlotProvider, UserContext, UserProvider, useDesignTheme, useHasPermission, useHasRole, useSlotContent, useSlotHasContent, useTheme, useUISlots, useUser, useUserForEvaluation };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map