@zendir/ui 0.5.0 → 0.6.0

package/dist/react/chatgpt/index.js

@@ -1,163 +1,184 @@
-import { useState, useCallback, useEffect, useSyncExternalStore } from "react";
-const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+//#region src/react/chatgpt/index.ts
+/**
+* ChatGPT Apps SDK Integration
+*
+* Hooks and utilities for integrating Zendir UI components with ChatGPT's
+* window.openai API. Based on: https://developers.openai.com/apps-sdk/build/chatgpt-ui/
+*
+* Key capabilities:
+* - window.openai.toolInput / toolOutput - Tool data from MCP server
+* - window.openai.widgetState / setWidgetState - Persistent UI state
+* - window.openai.callTool - Invoke other MCP tools from widget
+* - window.openai.sendFollowUpMessage - Insert user messages
+* - window.openai.theme - Light/dark theme detection
+* - window.openai.locale - Localization
+* - window.openai.requestDisplayMode - Fullscreen/PiP modes
+* - window.openai.notifyIntrinsicHeight - Dynamic height reporting
+*/
+var SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+/**
+* Subscribe to a specific window.openai global value
+*/
 function useOpenAiGlobal(key) {
-  const getSnapshot = useCallback(() => {
-    var _a;
-    return (_a = window.openai) == null ? void 0 : _a[key];
-  }, [key]);
-  const subscribe = useCallback((onChange) => {
-    const handleSetGlobal = (event) => {
-      var _a, _b;
-      const customEvent = event;
-      if (((_b = (_a = customEvent.detail) == null ? void 0 : _a.globals) == null ? void 0 : _b[key]) !== void 0) {
-        onChange();
-      }
-    };
-    window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, { passive: true });
-    return () => window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
-  }, [key]);
-  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+	const getSnapshot = useCallback(() => {
+		return window.openai?.[key];
+	}, [key]);
+	return useSyncExternalStore(useCallback((onChange) => {
+		const handleSetGlobal = (event) => {
+			if (event.detail?.globals?.[key] !== void 0) onChange();
+		};
+		window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, { passive: true });
+		return () => window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
+	}, [key]), getSnapshot, getSnapshot);
 }
+/**
+* Manage widget state that persists across renders via window.openai.setWidgetState
+*/
 function useWidgetState(defaultState) {
-  const widgetStateFromWindow = useOpenAiGlobal("widgetState");
-  const [widgetState, _setWidgetState] = useState(() => {
-    if (widgetStateFromWindow != null) {
-      return widgetStateFromWindow;
-    }
-    return typeof defaultState === "function" ? defaultState() : defaultState;
-  });
-  useEffect(() => {
-    if (widgetStateFromWindow != null) {
-      _setWidgetState(widgetStateFromWindow);
-    }
-  }, [widgetStateFromWindow]);
-  const setWidgetState = useCallback((state) => {
-    _setWidgetState((prevState) => {
-      var _a, _b;
-      const newState = typeof state === "function" ? state(prevState) : state;
-      (_b = (_a = window.openai) == null ? void 0 : _a.setWidgetState) == null ? void 0 : _b.call(_a, newState);
-      return newState;
-    });
-  }, []);
-  return [widgetState, setWidgetState];
+	const widgetStateFromWindow = useOpenAiGlobal("widgetState");
+	const [widgetState, _setWidgetState] = useState(() => {
+		if (widgetStateFromWindow != null) return widgetStateFromWindow;
+		return typeof defaultState === "function" ? defaultState() : defaultState;
+	});
+	useEffect(() => {
+		if (widgetStateFromWindow != null) _setWidgetState(widgetStateFromWindow);
+	}, [widgetStateFromWindow]);
+	return [widgetState, useCallback((state) => {
+		_setWidgetState((prevState) => {
+			const newState = typeof state === "function" ? state(prevState) : state;
+			window.openai?.setWidgetState?.(newState);
+			return newState;
+		});
+	}, [])];
 }
+/**
+* Read the tool output (structuredContent) from the MCP server response
+*/
 function useToolOutput() {
-  return useOpenAiGlobal("toolOutput");
+	return useOpenAiGlobal("toolOutput");
 }
+/**
+* Read the tool input (arguments) from the tool invocation
+*/
 function useToolInput() {
-  return useOpenAiGlobal("toolInput");
+	return useOpenAiGlobal("toolInput");
 }
+/**
+* Get current ChatGPT theme and provide CSS-friendly values
+* Named useChatGPTTheme to avoid conflict with the core useTheme from ThemeProvider
+*/
 function useChatGPTTheme() {
-  const theme = useOpenAiGlobal("theme") ?? "dark";
-  const isDark = theme === "dark";
-  return {
-    theme,
-    isDark,
-    colors: isDark ? {
-      background: "#09090b",
-      surface: "#18181b",
-      surfaceHover: "#27272a",
-      border: "#3f3f46",
-      text: "#fafafa",
-      textMuted: "#a1a1aa",
-      accent: "#22d3ee"
-    } : {
-      background: "#ffffff",
-      surface: "#f4f4f5",
-      surfaceHover: "#e4e4e7",
-      border: "#d4d4d8",
-      text: "#18181b",
-      textMuted: "#636370",
-      // WCAG AA: 5.90:1 on #fff, 5.39:1 on #f4f4f5, 4.66:1 on #e4e4e7 (was #71717a → 4.49:1 FAIL on surface)
-      accent: "#0ea5e9"
-    }
-  };
+	const theme = useOpenAiGlobal("theme") ?? "dark";
+	const isDark = theme === "dark";
+	return {
+		theme,
+		isDark,
+		colors: isDark ? {
+			background: "#09090b",
+			surface: "#18181b",
+			surfaceHover: "#27272a",
+			border: "#3f3f46",
+			text: "#fafafa",
+			textMuted: "#a1a1aa",
+			accent: "#22d3ee"
+		} : {
+			background: "#ffffff",
+			surface: "#f4f4f5",
+			surfaceHover: "#e4e4e7",
+			border: "#d4d4d8",
+			text: "#18181b",
+			textMuted: "#636370",
+			accent: "#0ea5e9"
+		}
+	};
 }
+/**
+* Get current locale for internationalization
+*/
 function useLocale() {
-  return useOpenAiGlobal("locale") ?? "en-US";
+	return useOpenAiGlobal("locale") ?? "en-US";
 }
+/**
+* Manage widget display mode (inline, PiP, fullscreen)
+*/
 function useDisplayMode() {
-  const mode = useOpenAiGlobal("displayMode") ?? "inline";
-  const maxHeight = useOpenAiGlobal("maxHeight");
-  const requestMode = useCallback(async (newMode) => {
-    var _a, _b;
-    await ((_b = (_a = window.openai) == null ? void 0 : _a.requestDisplayMode) == null ? void 0 : _b.call(_a, { mode: newMode }));
-  }, []);
-  const close = useCallback(() => {
-    var _a, _b;
-    (_b = (_a = window.openai) == null ? void 0 : _a.requestClose) == null ? void 0 : _b.call(_a);
-  }, []);
-  return { mode, maxHeight, requestMode, close };
+	return {
+		mode: useOpenAiGlobal("displayMode") ?? "inline",
+		maxHeight: useOpenAiGlobal("maxHeight"),
+		requestMode: useCallback(async (newMode) => {
+			await window.openai?.requestDisplayMode?.({ mode: newMode });
+		}, []),
+		close: useCallback(() => {
+			window.openai?.requestClose?.();
+		}, [])
+	};
 }
+/**
+* Call another MCP tool from within a widget
+*/
 function useCallTool() {
-  const [isLoading, setIsLoading] = useState(false);
-  const [error, setError] = useState(null);
-  const callTool = useCallback(async (name, args) => {
-    var _a;
-    if (!((_a = window.openai) == null ? void 0 : _a.callTool)) {
-      throw new Error("window.openai.callTool not available");
-    }
-    setIsLoading(true);
-    setError(null);
-    try {
-      const result = await window.openai.callTool(name, args);
-      return result;
-    } catch (err) {
-      const error2 = err instanceof Error ? err : new Error(String(err));
-      setError(error2);
-      throw error2;
-    } finally {
-      setIsLoading(false);
-    }
-  }, []);
-  return { callTool, isLoading, error };
+	const [isLoading, setIsLoading] = useState(false);
+	const [error, setError] = useState(null);
+	return {
+		callTool: useCallback(async (name, args) => {
+			if (!window.openai?.callTool) throw new Error("window.openai.callTool not available");
+			setIsLoading(true);
+			setError(null);
+			try {
+				return await window.openai.callTool(name, args);
+			} catch (err) {
+				const error = err instanceof Error ? err : new Error(String(err));
+				setError(error);
+				throw error;
+			} finally {
+				setIsLoading(false);
+			}
+		}, []),
+		isLoading,
+		error
+	};
 }
+/**
+* Send a follow-up message as if the user asked it
+*/
 function useSendMessage() {
-  return useCallback(async (prompt) => {
-    var _a, _b;
-    await ((_b = (_a = window.openai) == null ? void 0 : _a.sendFollowUpMessage) == null ? void 0 : _b.call(_a, { prompt }));
-  }, []);
+	return useCallback(async (prompt) => {
+		await window.openai?.sendFollowUpMessage?.({ prompt });
+	}, []);
 }
+/**
+* Get the maximum height available for the widget from the host environment.
+* This is the CORRECT pattern per OpenAI Apps SDK examples.
+*
+* The host (ChatGPT/MCPJam) provides maxHeight, and widgets should constrain
+* themselves to this height. Widgets should NOT report their height back.
+*
+* @returns The maximum height in pixels, or undefined if not available
+*/
 function useMaxHeight() {
-  const [maxHeight, setMaxHeight] = useState(
-    () => {
-      var _a;
-      return (_a = window.openai) == null ? void 0 : _a.maxHeight;
-    }
-  );
-  useEffect(() => {
-    const handler = (event) => {
-      var _a;
-      if (((_a = event.detail) == null ? void 0 : _a.globals) && "maxHeight" in event.detail.globals) {
-        setMaxHeight(event.detail.globals.maxHeight);
-      }
-    };
-    window.addEventListener("openai:set_globals", handler);
-    return () => window.removeEventListener("openai:set_globals", handler);
-  }, []);
-  return maxHeight;
+	const [maxHeight, setMaxHeight] = useState(() => window.openai?.maxHeight);
+	useEffect(() => {
+		const handler = (event) => {
+			if (event.detail?.globals && "maxHeight" in event.detail.globals) setMaxHeight(event.detail.globals.maxHeight);
+		};
+		window.addEventListener("openai:set_globals", handler);
+		return () => window.removeEventListener("openai:set_globals", handler);
+	}, []);
+	return maxHeight;
 }
+/**
+* Open vetted external links in the user's browser
+*/
 function useOpenExternal() {
-  return useCallback((href) => {
-    var _a, _b;
-    (_b = (_a = window.openai) == null ? void 0 : _a.openExternal) == null ? void 0 : _b.call(_a, { href });
-  }, []);
+	return useCallback((href) => {
+		window.openai?.openExternal?.({ href });
+	}, []);
 }
 function isInChatGPT() {
-  return typeof window !== "undefined" && window.openai !== void 0;
+	return typeof window !== "undefined" && window.openai !== void 0;
 }
-export {
-  isInChatGPT,
-  useCallTool,
-  useChatGPTTheme,
-  useDisplayMode,
-  useLocale,
-  useMaxHeight,
-  useOpenAiGlobal,
-  useOpenExternal,
-  useSendMessage,
-  useToolInput,
-  useToolOutput,
-  useWidgetState
-};
-//# sourceMappingURL=index.js.map
+//#endregion
+export { isInChatGPT, useCallTool, useChatGPTTheme, useDisplayMode, useLocale, useMaxHeight, useOpenAiGlobal, useOpenExternal, useSendMessage, useToolInput, useToolOutput, useWidgetState };
+
+//# sourceMappingURL=index.js.map

package/dist/react/chatgpt/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../../../src/react/chatgpt/index.ts"],"sourcesContent":["/**\n * ChatGPT Apps SDK Integration\n * \n * Hooks and utilities for integrating Zendir UI components with ChatGPT's\n * window.openai API. Based on: https://developers.openai.com/apps-sdk/build/chatgpt-ui/\n * \n * Key capabilities:\n * - window.openai.toolInput / toolOutput - Tool data from MCP server\n * - window.openai.widgetState / setWidgetState - Persistent UI state\n * - window.openai.callTool - Invoke other MCP tools from widget\n * - window.openai.sendFollowUpMessage - Insert user messages\n * - window.openai.theme - Light/dark theme detection\n * - window.openai.locale - Localization\n * - window.openai.requestDisplayMode - Fullscreen/PiP modes\n * - window.openai.notifyIntrinsicHeight - Dynamic height reporting\n */\n\nimport { useState, useEffect, useCallback, useSyncExternalStore } from 'react';\n\n// ============================================================================\n// Type Definitions\n// ============================================================================\n\nexport interface OpenAiGlobals {\n  /** Arguments supplied when the tool was invoked */\n  toolInput?: Record<string, unknown>;\n  /** Your structuredContent - the model reads this */\n  toolOutput?: Record<string, unknown>;\n  /** Metadata payload - only widget sees it */\n  toolResponseMetadata?: Record<string, unknown>;\n  /** Snapshot of UI state persisted between renders */\n  widgetState?: Record<string, unknown>;\n  /** Current theme */\n  theme?: 'light' | 'dark';\n  /** Current locale (e.g., 'en-US') */\n  locale?: string;\n  /** Display mode */\n  displayMode?: 'inline' | 'pip' | 'fullscreen';\n  /** Maximum allowed height */\n  maxHeight?: number;\n  /** View type */\n  view?: 'conversation' | 'modal';\n  /** User agent info */\n  userAgent?: string;\n  /** Safe area insets */\n  safeArea?: { top: number; bottom: number; left: number; right: number };\n  \n  // API Methods\n  setWidgetState?: (state: Record<string, unknown>) => void;\n  callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;\n  sendFollowUpMessage?: (options: { prompt: string }) => Promise<void>;\n  uploadFile?: (file: File) => Promise<{ fileId: string }>;\n  getFileDownloadUrl?: (options: { fileId: string }) => Promise<{ downloadUrl: string }>;\n  requestDisplayMode?: (options: { mode: 'inline' | 'pip' | 'fullscreen' }) => Promise<void>;\n  requestModal?: (options: unknown) => Promise<void>;\n  notifyIntrinsicHeight?: (height: number) => void;\n  openExternal?: (options: { href: string }) => void;\n  requestClose?: () => void;\n}\n\ndeclare global {\n  interface Window {\n    openai?: OpenAiGlobals;\n  }\n}\n\n// ============================================================================\n// Core Hook: useOpenAiGlobal\n// ============================================================================\n\nconst SET_GLOBALS_EVENT_TYPE = 'openai:set_globals';\n\ninterface SetGlobalsEvent extends CustomEvent {\n  detail: { globals: Partial<OpenAiGlobals> };\n}\n\n/**\n * Subscribe to a specific window.openai global value\n */\nexport function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] {\n  const getSnapshot = useCallback(() => {\n    return window.openai?.[key];\n  }, [key]);\n\n  const subscribe = useCallback((onChange: () => void) => {\n    const handleSetGlobal = (event: Event) => {\n      const customEvent = event as SetGlobalsEvent;\n      if (customEvent.detail?.globals?.[key] !== undefined) {\n        onChange();\n      }\n    };\n\n    window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, { passive: true });\n    return () => window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);\n  }, [key]);\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n// ============================================================================\n// Widget State Hook\n// ============================================================================\n\ntype SetStateAction<T> = T | ((prevState: T) => T);\n\n/**\n * Manage widget state that persists across renders via window.openai.setWidgetState\n */\nexport function useWidgetState<T extends Record<string, unknown>>(\n  defaultState: T | (() => T)\n): readonly [T, (state: SetStateAction<T>) => void] {\n  const widgetStateFromWindow = useOpenAiGlobal('widgetState') as T | undefined;\n\n  const [widgetState, _setWidgetState] = useState<T>(() => {\n    if (widgetStateFromWindow != null) {\n      return widgetStateFromWindow;\n    }\n    return typeof defaultState === 'function' ? (defaultState as () => T)() : defaultState;\n  });\n\n  useEffect(() => {\n    if (widgetStateFromWindow != null) {\n      _setWidgetState(widgetStateFromWindow);\n    }\n  }, [widgetStateFromWindow]);\n\n  const setWidgetState = useCallback((state: SetStateAction<T>) => {\n    _setWidgetState((prevState: T) => {\n      const newState = typeof state === 'function' ? (state as (p: T) => T)(prevState) : state;\n      window.openai?.setWidgetState?.(newState);\n      return newState;\n    });\n  }, []);\n\n  return [widgetState, setWidgetState] as const;\n}\n\n// ============================================================================\n// Tool Output Hook\n// ============================================================================\n\n/**\n * Read the tool output (structuredContent) from the MCP server response\n */\nexport function useToolOutput<T = Record<string, unknown>>(): T | undefined {\n  return useOpenAiGlobal('toolOutput') as T | undefined;\n}\n\n/**\n * Read the tool input (arguments) from the tool invocation\n */\nexport function useToolInput<T = Record<string, unknown>>(): T | undefined {\n  return useOpenAiGlobal('toolInput') as T | undefined;\n}\n\n// ============================================================================\n// Theme Hook\n// ============================================================================\n\nexport type ThemeMode = 'light' | 'dark';\n\n/**\n * Get current ChatGPT theme and provide CSS-friendly values\n * Named useChatGPTTheme to avoid conflict with the core useTheme from ThemeProvider\n */\nexport function useChatGPTTheme(): {\n  theme: ThemeMode;\n  isDark: boolean;\n  colors: {\n    background: string;\n    surface: string;\n    surfaceHover: string;\n    border: string;\n    text: string;\n    textMuted: string;\n    accent: string;\n  };\n} {\n  const theme = useOpenAiGlobal('theme') ?? 'dark';\n  const isDark = theme === 'dark';\n\n  return {\n    theme,\n    isDark,\n    colors: isDark ? {\n      background: '#09090b',\n      surface: '#18181b',\n      surfaceHover: '#27272a',\n      border: '#3f3f46',\n      text: '#fafafa',\n      textMuted: '#a1a1aa',\n      accent: '#22d3ee',\n    } : {\n      background: '#ffffff',\n      surface: '#f4f4f5',\n      surfaceHover: '#e4e4e7',\n      border: '#d4d4d8',\n      text: '#18181b',\n      textMuted: '#636370',  // WCAG AA: 5.90:1 on #fff, 5.39:1 on #f4f4f5, 4.66:1 on #e4e4e7 (was #71717a → 4.49:1 FAIL on surface)\n      accent: '#0ea5e9',\n    },\n  };\n}\n\n// ============================================================================\n// Locale Hook\n// ============================================================================\n\n/**\n * Get current locale for internationalization\n */\nexport function useLocale(): string {\n  return useOpenAiGlobal('locale') ?? 'en-US';\n}\n\n// ============================================================================\n// Display Mode Hook\n// ============================================================================\n\n/**\n * Manage widget display mode (inline, PiP, fullscreen)\n */\nexport function useDisplayMode(): {\n  mode: 'inline' | 'pip' | 'fullscreen';\n  maxHeight?: number;\n  requestMode: (mode: 'inline' | 'pip' | 'fullscreen') => Promise<void>;\n  close: () => void;\n} {\n  const mode = useOpenAiGlobal('displayMode') ?? 'inline';\n  const maxHeight = useOpenAiGlobal('maxHeight');\n\n  const requestMode = useCallback(async (newMode: 'inline' | 'pip' | 'fullscreen') => {\n    await window.openai?.requestDisplayMode?.({ mode: newMode });\n  }, []);\n\n  const close = useCallback(() => {\n    window.openai?.requestClose?.();\n  }, []);\n\n  return { mode, maxHeight, requestMode, close };\n}\n\n// ============================================================================\n// Tool Calling Hook\n// ============================================================================\n\n/**\n * Call another MCP tool from within a widget\n */\nexport function useCallTool(): {\n  callTool: <T = unknown>(name: string, args: Record<string, unknown>) => Promise<T>;\n  isLoading: boolean;\n  error: Error | null;\n} {\n  const [isLoading, setIsLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const callTool = useCallback(async <T = unknown>(\n    name: string,\n    args: Record<string, unknown>\n  ): Promise<T> => {\n    if (!window.openai?.callTool) {\n      throw new Error('window.openai.callTool not available');\n    }\n\n    setIsLoading(true);\n    setError(null);\n\n    try {\n      const result = await window.openai.callTool(name, args);\n      return result as T;\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      setError(error);\n      throw error;\n    } finally {\n      setIsLoading(false);\n    }\n  }, []);\n\n  return { callTool, isLoading, error };\n}\n\n// ============================================================================\n// Follow-up Message Hook\n// ============================================================================\n\n/**\n * Send a follow-up message as if the user asked it\n */\nexport function useSendMessage(): (prompt: string) => Promise<void> {\n  return useCallback(async (prompt: string) => {\n    await window.openai?.sendFollowUpMessage?.({ prompt });\n  }, []);\n}\n\n// ============================================================================\n// Dynamic Height Hook\n// ============================================================================\n\n/**\n * Get the maximum height available for the widget from the host environment.\n * This is the CORRECT pattern per OpenAI Apps SDK examples.\n * \n * The host (ChatGPT/MCPJam) provides maxHeight, and widgets should constrain\n * themselves to this height. Widgets should NOT report their height back.\n * \n * @returns The maximum height in pixels, or undefined if not available\n */\nexport function useMaxHeight(): number | undefined {\n  const [maxHeight, setMaxHeight] = useState<number | undefined>(\n    () => window.openai?.maxHeight\n  );\n  \n  useEffect(() => {\n    const handler = (event: CustomEvent) => {\n      if (event.detail?.globals && 'maxHeight' in event.detail.globals) {\n        setMaxHeight(event.detail.globals.maxHeight);\n      }\n    };\n    \n    window.addEventListener('openai:set_globals', handler as EventListener);\n    return () => window.removeEventListener('openai:set_globals', handler as EventListener);\n  }, []);\n  \n  return maxHeight;\n}\n\n// ============================================================================\n// External Link Hook\n// ============================================================================\n\n/**\n * Open vetted external links in the user's browser\n */\nexport function useOpenExternal(): (href: string) => void {\n  return useCallback((href: string) => {\n    window.openai?.openExternal?.({ href });\n  }, []);\n}\n\n// ============================================================================\n// Utility: Check if running in ChatGPT\n// ============================================================================\n\nexport function isInChatGPT(): boolean {\n  return typeof window !== 'undefined' && window.openai !== undefined;\n}\n\n// ============================================================================\n// Re-exports (types are already exported above)\n// ============================================================================\n\n"],"names":["error"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/react/chatgpt/index.ts"],"sourcesContent":["/**\n * ChatGPT Apps SDK Integration\n *\n * Hooks and utilities for integrating Zendir UI components with ChatGPT's\n * window.openai API. Based on: https://developers.openai.com/apps-sdk/build/chatgpt-ui/\n *\n * Key capabilities:\n * - window.openai.toolInput / toolOutput - Tool data from MCP server\n * - window.openai.widgetState / setWidgetState - Persistent UI state\n * - window.openai.callTool - Invoke other MCP tools from widget\n * - window.openai.sendFollowUpMessage - Insert user messages\n * - window.openai.theme - Light/dark theme detection\n * - window.openai.locale - Localization\n * - window.openai.requestDisplayMode - Fullscreen/PiP modes\n * - window.openai.notifyIntrinsicHeight - Dynamic height reporting\n */\n\nimport { useState, useEffect, useCallback, useSyncExternalStore } from \"react\";\n\n// ============================================================================\n// Type Definitions\n// ============================================================================\n\nexport interface OpenAiGlobals {\n  /** Arguments supplied when the tool was invoked */\n  toolInput?: Record<string, unknown>;\n  /** Your structuredContent - the model reads this */\n  toolOutput?: Record<string, unknown>;\n  /** Metadata payload - only widget sees it */\n  toolResponseMetadata?: Record<string, unknown>;\n  /** Snapshot of UI state persisted between renders */\n  widgetState?: Record<string, unknown>;\n  /** Current theme */\n  theme?: \"light\" | \"dark\";\n  /** Current locale (e.g., 'en-US') */\n  locale?: string;\n  /** Display mode */\n  displayMode?: \"inline\" | \"pip\" | \"fullscreen\";\n  /** Maximum allowed height */\n  maxHeight?: number;\n  /** View type */\n  view?: \"conversation\" | \"modal\";\n  /** User agent info */\n  userAgent?: string;\n  /** Safe area insets */\n  safeArea?: { top: number; bottom: number; left: number; right: number };\n\n  // API Methods\n  setWidgetState?: (state: Record<string, unknown>) => void;\n  callTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;\n  sendFollowUpMessage?: (options: { prompt: string }) => Promise<void>;\n  uploadFile?: (file: File) => Promise<{ fileId: string }>;\n  getFileDownloadUrl?: (options: {\n    fileId: string;\n  }) => Promise<{ downloadUrl: string }>;\n  requestDisplayMode?: (options: {\n    mode: \"inline\" | \"pip\" | \"fullscreen\";\n  }) => Promise<void>;\n  requestModal?: (options: unknown) => Promise<void>;\n  notifyIntrinsicHeight?: (height: number) => void;\n  openExternal?: (options: { href: string }) => void;\n  requestClose?: () => void;\n}\n\ndeclare global {\n  interface Window {\n    openai?: OpenAiGlobals;\n  }\n}\n\n// ============================================================================\n// Core Hook: useOpenAiGlobal\n// ============================================================================\n\nconst SET_GLOBALS_EVENT_TYPE = \"openai:set_globals\";\n\ninterface SetGlobalsEvent extends CustomEvent {\n  detail: { globals: Partial<OpenAiGlobals> };\n}\n\n/**\n * Subscribe to a specific window.openai global value\n */\nexport function useOpenAiGlobal<K extends keyof OpenAiGlobals>(\n  key: K,\n): OpenAiGlobals[K] {\n  const getSnapshot = useCallback(() => {\n    return window.openai?.[key];\n  }, [key]);\n\n  const subscribe = useCallback(\n    (onChange: () => void) => {\n      const handleSetGlobal = (event: Event) => {\n        const customEvent = event as SetGlobalsEvent;\n        if (customEvent.detail?.globals?.[key] !== undefined) {\n          onChange();\n        }\n      };\n\n      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {\n        passive: true,\n      });\n      return () =>\n        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);\n    },\n    [key],\n  );\n\n  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);\n}\n\n// ============================================================================\n// Widget State Hook\n// ============================================================================\n\ntype SetStateAction<T> = T | ((prevState: T) => T);\n\n/**\n * Manage widget state that persists across renders via window.openai.setWidgetState\n */\nexport function useWidgetState<T extends Record<string, unknown>>(\n  defaultState: T | (() => T),\n): readonly [T, (state: SetStateAction<T>) => void] {\n  const widgetStateFromWindow = useOpenAiGlobal(\"widgetState\") as T | undefined;\n\n  const [widgetState, _setWidgetState] = useState<T>(() => {\n    if (widgetStateFromWindow != null) {\n      return widgetStateFromWindow;\n    }\n    return typeof defaultState === \"function\"\n      ? (defaultState as () => T)()\n      : defaultState;\n  });\n\n  useEffect(() => {\n    if (widgetStateFromWindow != null) {\n      _setWidgetState(widgetStateFromWindow);\n    }\n  }, [widgetStateFromWindow]);\n\n  const setWidgetState = useCallback((state: SetStateAction<T>) => {\n    _setWidgetState((prevState: T) => {\n      const newState =\n        typeof state === \"function\" ? (state as (p: T) => T)(prevState) : state;\n      window.openai?.setWidgetState?.(newState);\n      return newState;\n    });\n  }, []);\n\n  return [widgetState, setWidgetState] as const;\n}\n\n// ============================================================================\n// Tool Output Hook\n// ============================================================================\n\n/**\n * Read the tool output (structuredContent) from the MCP server response\n */\nexport function useToolOutput<T = Record<string, unknown>>(): T | undefined {\n  return useOpenAiGlobal(\"toolOutput\") as T | undefined;\n}\n\n/**\n * Read the tool input (arguments) from the tool invocation\n */\nexport function useToolInput<T = Record<string, unknown>>(): T | undefined {\n  return useOpenAiGlobal(\"toolInput\") as T | undefined;\n}\n\n// ============================================================================\n// Theme Hook\n// ============================================================================\n\nexport type ThemeMode = \"light\" | \"dark\";\n\n/**\n * Get current ChatGPT theme and provide CSS-friendly values\n * Named useChatGPTTheme to avoid conflict with the core useTheme from ThemeProvider\n */\nexport function useChatGPTTheme(): {\n  theme: ThemeMode;\n  isDark: boolean;\n  colors: {\n    background: string;\n    surface: string;\n    surfaceHover: string;\n    border: string;\n    text: string;\n    textMuted: string;\n    accent: string;\n  };\n} {\n  const theme = useOpenAiGlobal(\"theme\") ?? \"dark\";\n  const isDark = theme === \"dark\";\n\n  return {\n    theme,\n    isDark,\n    colors: isDark\n      ? {\n          background: \"#09090b\",\n          surface: \"#18181b\",\n          surfaceHover: \"#27272a\",\n          border: \"#3f3f46\",\n          text: \"#fafafa\",\n          textMuted: \"#a1a1aa\",\n          accent: \"#22d3ee\",\n        }\n      : {\n          background: \"#ffffff\",\n          surface: \"#f4f4f5\",\n          surfaceHover: \"#e4e4e7\",\n          border: \"#d4d4d8\",\n          text: \"#18181b\",\n          textMuted: \"#636370\", // WCAG AA: 5.90:1 on #fff, 5.39:1 on #f4f4f5, 4.66:1 on #e4e4e7 (was #71717a → 4.49:1 FAIL on surface)\n          accent: \"#0ea5e9\",\n        },\n  };\n}\n\n// ============================================================================\n// Locale Hook\n// ============================================================================\n\n/**\n * Get current locale for internationalization\n */\nexport function useLocale(): string {\n  return useOpenAiGlobal(\"locale\") ?? \"en-US\";\n}\n\n// ============================================================================\n// Display Mode Hook\n// ============================================================================\n\n/**\n * Manage widget display mode (inline, PiP, fullscreen)\n */\nexport function useDisplayMode(): {\n  mode: \"inline\" | \"pip\" | \"fullscreen\";\n  maxHeight?: number;\n  requestMode: (mode: \"inline\" | \"pip\" | \"fullscreen\") => Promise<void>;\n  close: () => void;\n} {\n  const mode = useOpenAiGlobal(\"displayMode\") ?? \"inline\";\n  const maxHeight = useOpenAiGlobal(\"maxHeight\");\n\n  const requestMode = useCallback(\n    async (newMode: \"inline\" | \"pip\" | \"fullscreen\") => {\n      await window.openai?.requestDisplayMode?.({ mode: newMode });\n    },\n    [],\n  );\n\n  const close = useCallback(() => {\n    window.openai?.requestClose?.();\n  }, []);\n\n  return { mode, maxHeight, requestMode, close };\n}\n\n// ============================================================================\n// Tool Calling Hook\n// ============================================================================\n\n/**\n * Call another MCP tool from within a widget\n */\nexport function useCallTool(): {\n  callTool: <T = unknown>(\n    name: string,\n    args: Record<string, unknown>,\n  ) => Promise<T>;\n  isLoading: boolean;\n  error: Error | null;\n} {\n  const [isLoading, setIsLoading] = useState(false);\n  const [error, setError] = useState<Error | null>(null);\n\n  const callTool = useCallback(\n    async <T = unknown>(\n      name: string,\n      args: Record<string, unknown>,\n    ): Promise<T> => {\n      if (!window.openai?.callTool) {\n        throw new Error(\"window.openai.callTool not available\");\n      }\n\n      setIsLoading(true);\n      setError(null);\n\n      try {\n        const result = await window.openai.callTool(name, args);\n        return result as T;\n      } catch (err) {\n        const error = err instanceof Error ? err : new Error(String(err));\n        setError(error);\n        throw error;\n      } finally {\n        setIsLoading(false);\n      }\n    },\n    [],\n  );\n\n  return { callTool, isLoading, error };\n}\n\n// ============================================================================\n// Follow-up Message Hook\n// ============================================================================\n\n/**\n * Send a follow-up message as if the user asked it\n */\nexport function useSendMessage(): (prompt: string) => Promise<void> {\n  return useCallback(async (prompt: string) => {\n    await window.openai?.sendFollowUpMessage?.({ prompt });\n  }, []);\n}\n\n// ============================================================================\n// Dynamic Height Hook\n// ============================================================================\n\n/**\n * Get the maximum height available for the widget from the host environment.\n * This is the CORRECT pattern per OpenAI Apps SDK examples.\n *\n * The host (ChatGPT/MCPJam) provides maxHeight, and widgets should constrain\n * themselves to this height. Widgets should NOT report their height back.\n *\n * @returns The maximum height in pixels, or undefined if not available\n */\nexport function useMaxHeight(): number | undefined {\n  const [maxHeight, setMaxHeight] = useState<number | undefined>(\n    () => window.openai?.maxHeight,\n  );\n\n  useEffect(() => {\n    const handler = (event: CustomEvent) => {\n      if (event.detail?.globals && \"maxHeight\" in event.detail.globals) {\n        setMaxHeight(event.detail.globals.maxHeight);\n      }\n    };\n\n    window.addEventListener(\"openai:set_globals\", handler as EventListener);\n    return () =>\n      window.removeEventListener(\n        \"openai:set_globals\",\n        handler as EventListener,\n      );\n  }, []);\n\n  return maxHeight;\n}\n\n// ============================================================================\n// External Link Hook\n// ============================================================================\n\n/**\n * Open vetted external links in the user's browser\n */\nexport function useOpenExternal(): (href: string) => void {\n  return useCallback((href: string) => {\n    window.openai?.openExternal?.({ href });\n  }, []);\n}\n\n// ============================================================================\n// Utility: Check if running in ChatGPT\n// ============================================================================\n\nexport function isInChatGPT(): boolean {\n  return typeof window !== \"undefined\" && window.openai !== undefined;\n}\n\n// ============================================================================\n// Re-exports (types are already exported above)\n// ============================================================================\n"],"mappings":";;;;;;;;;;;;;;;;;;AA0EA,IAAM,yBAAyB;;;;AAS/B,SAAgB,gBACd,KACkB;CAClB,MAAM,cAAc,kBAAkB;EACpC,OAAO,OAAO,SAAS;CACzB,GAAG,CAAC,GAAG,CAAC;CAoBR,OAAO,qBAlBW,aACf,aAAyB;EACxB,MAAM,mBAAmB,UAAiB;GAExC,IAAI,MAAY,QAAQ,UAAU,SAAS,KAAA,GACzC,SAAS;EAEb;EAEA,OAAO,iBAAiB,wBAAwB,iBAAiB,EAC/D,SAAS,KACX,CAAC;EACD,aACE,OAAO,oBAAoB,wBAAwB,eAAe;CACtE,GACA,CAAC,GAAG,CAGsB,GAAW,aAAa,WAAW;AACjE;;;;AAWA,SAAgB,eACd,cACkD;CAClD,MAAM,wBAAwB,gBAAgB,aAAa;CAE3D,MAAM,CAAC,aAAa,mBAAmB,eAAkB;EACvD,IAAI,yBAAyB,MAC3B,OAAO;EAET,OAAO,OAAO,iBAAiB,aAC1B,aAAyB,IAC1B;CACN,CAAC;CAED,gBAAgB;EACd,IAAI,yBAAyB,MAC3B,gBAAgB,qBAAqB;CAEzC,GAAG,CAAC,qBAAqB,CAAC;CAW1B,OAAO,CAAC,aATe,aAAa,UAA6B;EAC/D,iBAAiB,cAAiB;GAChC,MAAM,WACJ,OAAO,UAAU,aAAc,MAAsB,SAAS,IAAI;GACpE,OAAO,QAAQ,iBAAiB,QAAQ;GACxC,OAAO;EACT,CAAC;CACH,GAAG,CAAC,CAEiB,CAAc;AACrC;;;;AASA,SAAgB,gBAA4D;CAC1E,OAAO,gBAAgB,YAAY;AACrC;;;;AAKA,SAAgB,eAA2D;CACzE,OAAO,gBAAgB,WAAW;AACpC;;;;;AAYA,SAAgB,kBAYd;CACA,MAAM,QAAQ,gBAAgB,OAAO,KAAK;CAC1C,MAAM,SAAS,UAAU;CAEzB,OAAO;EACL;EACA;EACA,QAAQ,SACJ;GACE,YAAY;GACZ,SAAS;GACT,cAAc;GACd,QAAQ;GACR,MAAM;GACN,WAAW;GACX,QAAQ;EACV,IACA;GACE,YAAY;GACZ,SAAS;GACT,cAAc;GACd,QAAQ;GACR,MAAM;GACN,WAAW;GACX,QAAQ;EACV;CACN;AACF;;;;AASA,SAAgB,YAAoB;CAClC,OAAO,gBAAgB,QAAQ,KAAK;AACtC;;;;AASA,SAAgB,iBAKd;CAeA,OAAO;EAAE,MAdI,gBAAgB,aAAa,KAAK;EAchC,WAbG,gBAAgB,WAanB;EAAW,aAXN,YAClB,OAAO,YAA6C;GAClD,MAAM,OAAO,QAAQ,qBAAqB,EAAE,MAAM,QAAQ,CAAC;EAC7D,GACA,CAAC,CAOuB;EAAa,OAJzB,kBAAkB;GAC9B,OAAO,QAAQ,eAAe;EAChC,GAAG,CAAC,CAEmC;CAAM;AAC/C;;;;AASA,SAAgB,cAOd;CACA,MAAM,CAAC,WAAW,gBAAgB,SAAS,KAAK;CAChD,MAAM,CAAC,OAAO,YAAY,SAAuB,IAAI;CA4BrD,OAAO;EAAE,UA1BQ,YACf,OACE,MACA,SACe;GACf,IAAI,CAAC,OAAO,QAAQ,UAClB,MAAM,IAAI,MAAM,sCAAsC;GAGxD,aAAa,IAAI;GACjB,SAAS,IAAI;GAEb,IAAI;IAEF,OAAO,MADc,OAAO,OAAO,SAAS,MAAM,IAAI;GAExD,SAAS,KAAK;IACZ,MAAM,QAAQ,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC;IAChE,SAAS,KAAK;IACd,MAAM;GACR,UAAU;IACR,aAAa,KAAK;GACpB;EACF,GACA,CAAC,CAGM;EAAU;EAAW;CAAM;AACtC;;;;AASA,SAAgB,iBAAoD;CAClE,OAAO,YAAY,OAAO,WAAmB;EAC3C,MAAM,OAAO,QAAQ,sBAAsB,EAAE,OAAO,CAAC;CACvD,GAAG,CAAC,CAAC;AACP;;;;;;;;;;AAeA,SAAgB,eAAmC;CACjD,MAAM,CAAC,WAAW,gBAAgB,eAC1B,OAAO,QAAQ,SACvB;CAEA,gBAAgB;EACd,MAAM,WAAW,UAAuB;GACtC,IAAI,MAAM,QAAQ,WAAW,eAAe,MAAM,OAAO,SACvD,aAAa,MAAM,OAAO,QAAQ,SAAS;EAE/C;EAEA,OAAO,iBAAiB,sBAAsB,OAAwB;EACtE,aACE,OAAO,oBACL,sBACA,OACF;CACJ,GAAG,CAAC,CAAC;CAEL,OAAO;AACT;;;;AASA,SAAgB,kBAA0C;CACxD,OAAO,aAAa,SAAiB;EACnC,OAAO,QAAQ,eAAe,EAAE,KAAK,CAAC;CACxC,GAAG,CAAC,CAAC;AACP;AAMA,SAAgB,cAAuB;CACrC,OAAO,OAAO,WAAW,eAAe,OAAO,WAAW,KAAA;AAC5D"}

package/dist/react/context/CategoryContext.d.ts

@@ -1,7 +1,6 @@
 import { default as React, ReactNode } from 'react';
 import { CategoryPalette } from '../utils/categoryPalette';
 import { CategoryDef } from '../types';
-
 export interface CategoryContextValue {
     /** Palette instance built from the provided categories. */
     palette: CategoryPalette;

package/dist/react/context/CategoryContext.js

@@ -1,36 +1,85 @@
-import { jsx } from "react/jsx-runtime";
-import { useMemo, useContext, createContext } from "react";
 import { CategoryPalette } from "../utils/categoryPalette.js";
-const CategoryContext = createContext(null);
+import { createContext, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/context/CategoryContext.tsx
+/**
+* @zendir/ui — CategoryProvider
+*
+* Optional React context for sharing a `CategoryPalette` and display label
+* across sibling components in a dashboard layout. Components that are
+* "category-aware" (Timeline, GroundTrackMap, AstroChart, DataTable) can
+* read from this context to resolve colors/labels without each needing
+* explicit palette props.
+*
+* **This context is fully opt-in.** Components continue to work standalone
+* — explicit `color` / `team` props always take precedence over context.
+*
+* @example
+* ```tsx
+* import { CategoryProvider, useCategoryPalette } from '@zendir/ui';
+*
+* const categories = [
+*   { id: 'alpha', label: 'Team Alpha', color: '#2dccff' },
+*   { id: 'bravo', label: 'Team Bravo', color: '#fce83a' },
+* ];
+*
+* // Wrap a section of your dashboard
+* <CategoryProvider categories={categories} categoryLabel="Squads">
+*   <Timeline events={events} />
+*   <GroundTrackMap pins={pins} />
+* </CategoryProvider>
+*
+* // Inside any component
+* function MyWidget() {
+*   const ctx = useCategoryPalette();
+*   if (!ctx) return null; // graceful when no provider
+*   const color = ctx.palette.getColor('alpha');
+*   const label = ctx.categoryLabel; // "Squads"
+* }
+* ```
+*/
+var CategoryContext = createContext(null);
 CategoryContext.displayName = "CategoryContext";
-function CategoryProvider({
-  categories,
-  categoryLabel = "Categories",
-  fallbackPalette,
-  children
-}) {
-  const value = useMemo(() => ({
-    palette: new CategoryPalette(categories, fallbackPalette),
-    categories,
-    categoryLabel
-  }), [categories, categoryLabel, fallbackPalette]);
-  return /* @__PURE__ */ jsx(CategoryContext.Provider, { value, children });
+/**
+* Provides a shared `CategoryPalette` to descendant components.
+*
+* Wrap a dashboard section (not the entire app) so sibling components
+* like Timeline + Map + Charts resolve the same colors for the same ids.
+*/
+function CategoryProvider({ categories, categoryLabel = "Categories", fallbackPalette, children }) {
+	const value = useMemo(() => ({
+		palette: new CategoryPalette(categories, fallbackPalette),
+		categories,
+		categoryLabel
+	}), [
+		categories,
+		categoryLabel,
+		fallbackPalette
+	]);
+	return /* @__PURE__ */ jsx(CategoryContext.Provider, {
+		value,
+		children
+	});
 }
+/**
+* Access the nearest `CategoryProvider`'s palette and label.
+*
+* Returns `null` when no provider is present — components should treat
+* this as "standalone mode" and fall back to explicit props / defaults.
+*/
 function useCategoryPalette() {
-  return useContext(CategoryContext);
+	return useContext(CategoryContext);
 }
+/**
+* Like `useCategoryPalette()` but throws if no provider is found.
+* Use only when you know a provider is always present.
+*/
 function useCategoryPaletteRequired() {
-  const ctx = useContext(CategoryContext);
-  if (!ctx) {
-    throw new Error(
-      "useCategoryPaletteRequired() was called outside of a <CategoryProvider>. Wrap a parent component with <CategoryProvider categories={[...]}> or use useCategoryPalette() for graceful null handling."
-    );
-  }
-  return ctx;
+	const ctx = useContext(CategoryContext);
+	if (!ctx) throw new Error("useCategoryPaletteRequired() was called outside of a <CategoryProvider>. Wrap a parent component with <CategoryProvider categories={[...]}> or use useCategoryPalette() for graceful null handling.");
+	return ctx;
 }
-export {
-  CategoryProvider,
-  useCategoryPalette,
-  useCategoryPaletteRequired
-};
-//# sourceMappingURL=CategoryContext.js.map
+//#endregion
+export { CategoryProvider, useCategoryPalette, useCategoryPaletteRequired };
+
+//# sourceMappingURL=CategoryContext.js.map

package/dist/react/context/CategoryContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"CategoryContext.js","sources":["../../../src/react/context/CategoryContext.tsx"],"sourcesContent":["/**\r\n * @zendir/ui — CategoryProvider\r\n *\r\n * Optional React context for sharing a `CategoryPalette` and display label\r\n * across sibling components in a dashboard layout. Components that are\r\n * \"category-aware\" (Timeline, GroundTrackMap, AstroChart, DataTable) can\r\n * read from this context to resolve colors/labels without each needing\r\n * explicit palette props.\r\n *\r\n * **This context is fully opt-in.** Components continue to work standalone\r\n * — explicit `color` / `team` props always take precedence over context.\r\n *\r\n * @example\r\n * ```tsx\r\n * import { CategoryProvider, useCategoryPalette } from '@zendir/ui';\r\n *\r\n * const categories = [\r\n *   { id: 'alpha', label: 'Team Alpha', color: '#2dccff' },\r\n *   { id: 'bravo', label: 'Team Bravo', color: '#fce83a' },\r\n * ];\r\n *\r\n * // Wrap a section of your dashboard\r\n * <CategoryProvider categories={categories} categoryLabel=\"Squads\">\r\n *   <Timeline events={events} />\r\n *   <GroundTrackMap pins={pins} />\r\n * </CategoryProvider>\r\n *\r\n * // Inside any component\r\n * function MyWidget() {\r\n *   const ctx = useCategoryPalette();\r\n *   if (!ctx) return null; // graceful when no provider\r\n *   const color = ctx.palette.getColor('alpha');\r\n *   const label = ctx.categoryLabel; // \"Squads\"\r\n * }\r\n * ```\r\n */\r\n\r\nimport React, { createContext, useContext, useMemo, type ReactNode } from 'react';\r\nimport { CategoryPalette } from '../utils/categoryPalette';\r\nimport type { CategoryDef } from '../types';\r\n\r\n// =============================================================================\r\n// Context value\r\n// =============================================================================\r\n\r\nexport interface CategoryContextValue {\r\n  /** Palette instance built from the provided categories. */\r\n  palette: CategoryPalette;\r\n  /** All registered category definitions. */\r\n  categories: CategoryDef[];\r\n  /**\r\n   * Human-readable label for the grouping dimension.\r\n   * Defaults to `\"Categories\"`. Components that support a label override\r\n   * (e.g. Timeline's `teamLabel`) should fall back to this when no\r\n   * explicit prop is provided.\r\n   */\r\n  categoryLabel: string;\r\n}\r\n\r\nconst CategoryContext = createContext<CategoryContextValue | null>(null);\r\nCategoryContext.displayName = 'CategoryContext';\r\n\r\n// =============================================================================\r\n// Provider\r\n// =============================================================================\r\n\r\nexport interface CategoryProviderProps {\r\n  /** Category definitions — each must have `id`, `label`, and `color`. */\r\n  categories: CategoryDef[];\r\n  /**\r\n   * Display label for the grouping dimension, e.g. `\"Teams\"`, `\"Squads\"`,\r\n   * `\"Subsystems\"`. Defaults to `\"Categories\"`.\r\n   */\r\n  categoryLabel?: string;\r\n  /**\r\n   * Optional custom fallback palette for auto-assigned unknown ids.\r\n   * Defaults to the Astro data-viz palette built into `CategoryPalette`.\r\n   */\r\n  fallbackPalette?: string[];\r\n  children: ReactNode;\r\n}\r\n\r\n/**\r\n * Provides a shared `CategoryPalette` to descendant components.\r\n *\r\n * Wrap a dashboard section (not the entire app) so sibling components\r\n * like Timeline + Map + Charts resolve the same colors for the same ids.\r\n */\r\nexport function CategoryProvider({\r\n  categories,\r\n  categoryLabel = 'Categories',\r\n  fallbackPalette,\r\n  children,\r\n}: CategoryProviderProps): React.ReactElement {\r\n  const value = useMemo<CategoryContextValue>(() => ({\r\n    palette: new CategoryPalette(categories, fallbackPalette),\r\n    categories,\r\n    categoryLabel,\r\n  }), [categories, categoryLabel, fallbackPalette]);\r\n\r\n  return (\r\n    <CategoryContext.Provider value={value}>\r\n      {children}\r\n    </CategoryContext.Provider>\r\n  );\r\n}\r\n\r\n// =============================================================================\r\n// Hooks\r\n// =============================================================================\r\n\r\n/**\r\n * Access the nearest `CategoryProvider`'s palette and label.\r\n *\r\n * Returns `null` when no provider is present — components should treat\r\n * this as \"standalone mode\" and fall back to explicit props / defaults.\r\n */\r\nexport function useCategoryPalette(): CategoryContextValue | null {\r\n  return useContext(CategoryContext);\r\n}\r\n\r\n/**\r\n * Like `useCategoryPalette()` but throws if no provider is found.\r\n * Use only when you know a provider is always present.\r\n */\r\nexport function useCategoryPaletteRequired(): CategoryContextValue {\r\n  const ctx = useContext(CategoryContext);\r\n  if (!ctx) {\r\n    throw new Error(\r\n      'useCategoryPaletteRequired() was called outside of a <CategoryProvider>. ' +\r\n      'Wrap a parent component with <CategoryProvider categories={[...]}> or ' +\r\n      'use useCategoryPalette() for graceful null handling.',\r\n    );\r\n  }\r\n  return ctx;\r\n}\r\n"],"names":[],"mappings":";;;AA2DA,MAAM,kBAAkB,cAA2C,IAAI;AACvE,gBAAgB,cAAc;AA4BvB,SAAS,iBAAiB;AAAA,EAC/B;AAAA,EACA,gBAAgB;AAAA,EAChB;AAAA,EACA;AACF,GAA8C;AAC5C,QAAM,QAAQ,QAA8B,OAAO;AAAA,IACjD,SAAS,IAAI,gBAAgB,YAAY,eAAe;AAAA,IACxD;AAAA,IACA;AAAA,EAAA,IACE,CAAC,YAAY,eAAe,eAAe,CAAC;AAEhD,SACE,oBAAC,gBAAgB,UAAhB,EAAyB,OACvB,SAAA,CACH;AAEJ;AAYO,SAAS,qBAAkD;AAChE,SAAO,WAAW,eAAe;AACnC;AAMO,SAAS,6BAAmD;AACjE,QAAM,MAAM,WAAW,eAAe;AACtC,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAIJ;AACA,SAAO;AACT;"}
+{"version":3,"file":"CategoryContext.js","names":[],"sources":["../../../src/react/context/CategoryContext.tsx"],"sourcesContent":["/**\n * @zendir/ui — CategoryProvider\n *\n * Optional React context for sharing a `CategoryPalette` and display label\n * across sibling components in a dashboard layout. Components that are\n * \"category-aware\" (Timeline, GroundTrackMap, AstroChart, DataTable) can\n * read from this context to resolve colors/labels without each needing\n * explicit palette props.\n *\n * **This context is fully opt-in.** Components continue to work standalone\n * — explicit `color` / `team` props always take precedence over context.\n *\n * @example\n * ```tsx\n * import { CategoryProvider, useCategoryPalette } from '@zendir/ui';\n *\n * const categories = [\n *   { id: 'alpha', label: 'Team Alpha', color: '#2dccff' },\n *   { id: 'bravo', label: 'Team Bravo', color: '#fce83a' },\n * ];\n *\n * // Wrap a section of your dashboard\n * <CategoryProvider categories={categories} categoryLabel=\"Squads\">\n *   <Timeline events={events} />\n *   <GroundTrackMap pins={pins} />\n * </CategoryProvider>\n *\n * // Inside any component\n * function MyWidget() {\n *   const ctx = useCategoryPalette();\n *   if (!ctx) return null; // graceful when no provider\n *   const color = ctx.palette.getColor('alpha');\n *   const label = ctx.categoryLabel; // \"Squads\"\n * }\n * ```\n */\n\nimport React, {\n  createContext,\n  useContext,\n  useMemo,\n  type ReactNode,\n} from \"react\";\nimport { CategoryPalette } from \"../utils/categoryPalette\";\nimport type { CategoryDef } from \"../types\";\n\n// =============================================================================\n// Context value\n// =============================================================================\n\nexport interface CategoryContextValue {\n  /** Palette instance built from the provided categories. */\n  palette: CategoryPalette;\n  /** All registered category definitions. */\n  categories: CategoryDef[];\n  /**\n   * Human-readable label for the grouping dimension.\n   * Defaults to `\"Categories\"`. Components that support a label override\n   * (e.g. Timeline's `teamLabel`) should fall back to this when no\n   * explicit prop is provided.\n   */\n  categoryLabel: string;\n}\n\nconst CategoryContext = createContext<CategoryContextValue | null>(null);\nCategoryContext.displayName = \"CategoryContext\";\n\n// =============================================================================\n// Provider\n// =============================================================================\n\nexport interface CategoryProviderProps {\n  /** Category definitions — each must have `id`, `label`, and `color`. */\n  categories: CategoryDef[];\n  /**\n   * Display label for the grouping dimension, e.g. `\"Teams\"`, `\"Squads\"`,\n   * `\"Subsystems\"`. Defaults to `\"Categories\"`.\n   */\n  categoryLabel?: string;\n  /**\n   * Optional custom fallback palette for auto-assigned unknown ids.\n   * Defaults to the Astro data-viz palette built into `CategoryPalette`.\n   */\n  fallbackPalette?: string[];\n  children: ReactNode;\n}\n\n/**\n * Provides a shared `CategoryPalette` to descendant components.\n *\n * Wrap a dashboard section (not the entire app) so sibling components\n * like Timeline + Map + Charts resolve the same colors for the same ids.\n */\nexport function CategoryProvider({\n  categories,\n  categoryLabel = \"Categories\",\n  fallbackPalette,\n  children,\n}: CategoryProviderProps): React.ReactElement {\n  const value = useMemo<CategoryContextValue>(\n    () => ({\n      palette: new CategoryPalette(categories, fallbackPalette),\n      categories,\n      categoryLabel,\n    }),\n    [categories, categoryLabel, fallbackPalette],\n  );\n\n  return (\n    <CategoryContext.Provider value={value}>\n      {children}\n    </CategoryContext.Provider>\n  );\n}\n\n// =============================================================================\n// Hooks\n// =============================================================================\n\n/**\n * Access the nearest `CategoryProvider`'s palette and label.\n *\n * Returns `null` when no provider is present — components should treat\n * this as \"standalone mode\" and fall back to explicit props / defaults.\n */\nexport function useCategoryPalette(): CategoryContextValue | null {\n  return useContext(CategoryContext);\n}\n\n/**\n * Like `useCategoryPalette()` but throws if no provider is found.\n * Use only when you know a provider is always present.\n */\nexport function useCategoryPaletteRequired(): CategoryContextValue {\n  const ctx = useContext(CategoryContext);\n  if (!ctx) {\n    throw new Error(\n      \"useCategoryPaletteRequired() was called outside of a <CategoryProvider>. \" +\n        \"Wrap a parent component with <CategoryProvider categories={[...]}> or \" +\n        \"use useCategoryPalette() for graceful null handling.\",\n    );\n  }\n  return ctx;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,IAAM,kBAAkB,cAA2C,IAAI;AACvE,gBAAgB,cAAc;;;;;;;AA4B9B,SAAgB,iBAAiB,EAC/B,YACA,gBAAgB,cAChB,iBACA,YAC4C;CAC5C,MAAM,QAAQ,eACL;EACL,SAAS,IAAI,gBAAgB,YAAY,eAAe;EACxD;EACA;CACF,IACA;EAAC;EAAY;EAAe;CAAe,CAC7C;CAEA,OACE,oBAAC,gBAAgB,UAAjB;EAAiC;EAC9B;CACuB,CAAA;AAE9B;;;;;;;AAYA,SAAgB,qBAAkD;CAChE,OAAO,WAAW,eAAe;AACnC;;;;;AAMA,SAAgB,6BAAmD;CACjE,MAAM,MAAM,WAAW,eAAe;CACtC,IAAI,CAAC,KACH,MAAM,IAAI,MACR,qMAGF;CAEF,OAAO;AACT"}

package/dist/react/context/DisplaySettingsContext.d.ts

@@ -1,6 +1,5 @@
 import { default as React, ReactNode } from 'react';
-
-export type ColorTarget = 'both' | 'accent' | 'glass';
+export type ColorTarget = "both" | "accent" | "glass";
 export interface DisplaySettings {
     /** Global compact mode - affects all cards */
     compactMode: boolean;