@imjp/writenex-astro 0.1.0

package/src/client/context/ThemeContext.tsx

@@ -0,0 +1,172 @@
+/**
+ * @fileoverview Theme context and provider for Writenex Astro
+ *
+ * Manages theme state (light/dark/system) and applies the appropriate
+ * class to the document root element. Persists preference to localStorage.
+ *
+ * @module @writenex/astro/client/context/ThemeContext
+ */
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  useCallback,
+  type ReactNode,
+} from "react";
+
+/**
+ * Available theme options
+ */
+export type Theme = "light" | "dark" | "system";
+
+/**
+ * Theme context value interface
+ */
+interface ThemeContextValue {
+  /** Current theme setting */
+  theme: Theme;
+  /** Resolved theme (actual light/dark being displayed) */
+  resolvedTheme: "light" | "dark";
+  /** Update theme preference */
+  setTheme: (theme: Theme) => void;
+}
+
+const STORAGE_KEY = "writenex-astro-theme";
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+/**
+ * Get system color scheme preference
+ */
+function getSystemTheme(): "light" | "dark" {
+  if (typeof window === "undefined") return "dark";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches
+    ? "dark"
+    : "light";
+}
+
+/**
+ * Get stored theme from localStorage
+ */
+function getStoredTheme(): Theme {
+  if (typeof window === "undefined") return "system";
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored === "light" || stored === "dark" || stored === "system") {
+      return stored;
+    }
+  } catch {
+    // localStorage not available
+  }
+  return "system";
+}
+
+/**
+ * Props for ThemeProvider component
+ */
+interface ThemeProviderProps {
+  /** Child components */
+  children: ReactNode;
+  /** Default theme (optional) */
+  defaultTheme?: Theme;
+}
+
+/**
+ * Theme provider component that manages theme state and applies it to DOM.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * <ThemeProvider>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export function ThemeProvider({
+  children,
+  defaultTheme = "system",
+}: ThemeProviderProps): React.ReactElement {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    if (typeof window === "undefined") return defaultTheme;
+    return getStoredTheme();
+  });
+
+  const [resolvedTheme, setResolvedTheme] = useState<"light" | "dark">(() => {
+    if (typeof window === "undefined") return "dark";
+    const stored = getStoredTheme();
+    if (stored === "system") return getSystemTheme();
+    return stored;
+  });
+
+  const setTheme = useCallback((newTheme: Theme) => {
+    setThemeState(newTheme);
+    try {
+      localStorage.setItem(STORAGE_KEY, newTheme);
+    } catch {
+      // localStorage not available
+    }
+  }, []);
+
+  // Apply theme to document and handle system preference changes
+  useEffect(() => {
+    const root = document.documentElement;
+
+    const applyTheme = (isDark: boolean) => {
+      if (isDark) {
+        root.classList.add("wn-dark");
+        root.classList.remove("wn-light");
+      } else {
+        root.classList.add("wn-light");
+        root.classList.remove("wn-dark");
+      }
+      setResolvedTheme(isDark ? "dark" : "light");
+    };
+
+    if (theme === "dark") {
+      applyTheme(true);
+    } else if (theme === "light") {
+      applyTheme(false);
+    } else {
+      // System preference
+      const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+      applyTheme(mediaQuery.matches);
+
+      const listener = (e: MediaQueryListEvent) => {
+        applyTheme(e.matches);
+      };
+
+      mediaQuery.addEventListener("change", listener);
+      return () => mediaQuery.removeEventListener("change", listener);
+    }
+  }, [theme]);
+
+  return (
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+/**
+ * Hook to access theme context
+ *
+ * @returns Theme context value
+ * @throws Error if used outside ThemeProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { theme, setTheme, resolvedTheme } = useTheme();
+ *   return <button onClick={() => setTheme('dark')}>Dark</button>;
+ * }
+ * ```
+ */
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+}

package/src/client/hooks/useAnnounce.ts

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Announce hook for screen reader announcements
+ *
+ * This hook provides a way to announce messages to screen readers
+ * using ARIA live regions. It supports both polite and assertive
+ * politeness levels and handles rapid announcement queuing.
+ *
+ * ## Features:
+ * - Polite and assertive announcement modes
+ * - Message queuing for rapid announcements
+ * - Automatic cleanup of old announcements
+ * - Integration with global live region
+ *
+ * @module @writenex/astro/client/hooks/useAnnounce
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+
+/**
+ * Politeness level for announcements
+ * - polite: Waits for user to finish current task before announcing
+ * - assertive: Interrupts current task to announce immediately
+ */
+export type AnnouncePoliteness = "polite" | "assertive";
+
+/**
+ * Announcement message structure
+ */
+export interface Announcement {
+  /** Unique identifier for the announcement */
+  id: string;
+  /** Message to announce */
+  message: string;
+  /** Politeness level */
+  politeness: AnnouncePoliteness;
+  /** Timestamp when announcement was created */
+  timestamp: number;
+}
+
+/**
+ * Return value from useAnnounce hook
+ */
+export interface UseAnnounceReturn {
+  /** Announce a message to screen readers */
+  announce: (message: string, politeness?: AnnouncePoliteness) => void;
+  /** Current announcement message (for live region) */
+  currentMessage: string;
+  /** Current politeness level */
+  currentPoliteness: AnnouncePoliteness;
+  /** Clear the current announcement */
+  clear: () => void;
+}
+
+/** Maximum age for announcements in milliseconds (5 seconds) */
+const MAX_ANNOUNCEMENT_AGE = 5000;
+
+/** Delay between processing queued announcements */
+const ANNOUNCEMENT_DELAY = 100;
+
+/** Counter for generating unique announcement IDs */
+let announcementIdCounter = 0;
+
+/**
+ * Generate a unique announcement ID
+ */
+function generateAnnouncementId(): string {
+  return `announcement-${++announcementIdCounter}-${Date.now()}`;
+}
+
+/**
+ * Hook for announcing messages to screen readers via live regions
+ *
+ * This hook manages a queue of announcements and processes them
+ * sequentially to ensure screen readers can properly announce each
+ * message. It automatically discards stale announcements.
+ *
+ * @returns Object containing announce function and current message state
+ *
+ * @example
+ * ```tsx
+ * function SaveButton() {
+ *   const { announce } = useAnnounce();
+ *
+ *   const handleSave = async () => {
+ *     try {
+ *       await saveContent();
+ *       announce("Content saved", "polite");
+ *     } catch (error) {
+ *       announce("Save failed", "assertive");
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleSave}>Save</button>;
+ * }
+ * ```
+ */
+export function useAnnounce(): UseAnnounceReturn {
+  const [currentMessage, setCurrentMessage] = useState("");
+  const [currentPoliteness, setCurrentPoliteness] =
+    useState<AnnouncePoliteness>("polite");
+
+  const queueRef = useRef<Announcement[]>([]);
+  const isProcessingRef = useRef(false);
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  /**
+   * Process the next announcement in the queue
+   */
+  const processQueue = useCallback(() => {
+    if (isProcessingRef.current || queueRef.current.length === 0) {
+      return;
+    }
+
+    isProcessingRef.current = true;
+
+    // Get the next announcement
+    const announcement = queueRef.current.shift();
+
+    if (!announcement) {
+      isProcessingRef.current = false;
+      return;
+    }
+
+    // Check if announcement is stale
+    const age = Date.now() - announcement.timestamp;
+    if (age > MAX_ANNOUNCEMENT_AGE) {
+      // Skip stale announcement and process next
+      isProcessingRef.current = false;
+      processQueue();
+      return;
+    }
+
+    // Clear current message first to ensure screen reader announces new message
+    setCurrentMessage("");
+
+    // Set the new message after a brief delay
+    timeoutRef.current = setTimeout(() => {
+      setCurrentMessage(announcement.message);
+      setCurrentPoliteness(announcement.politeness);
+
+      // Clear after announcement and process next
+      timeoutRef.current = setTimeout(() => {
+        setCurrentMessage("");
+        isProcessingRef.current = false;
+        processQueue();
+      }, ANNOUNCEMENT_DELAY);
+    }, ANNOUNCEMENT_DELAY);
+  }, []);
+
+  /**
+   * Announce a message to screen readers
+   */
+  const announce = useCallback(
+    (message: string, politeness: AnnouncePoliteness = "polite") => {
+      if (!message.trim()) return;
+
+      const announcement: Announcement = {
+        id: generateAnnouncementId(),
+        message: message.trim(),
+        politeness,
+        timestamp: Date.now(),
+      };
+
+      // Add to queue
+      queueRef.current.push(announcement);
+
+      // Start processing if not already
+      processQueue();
+    },
+    [processQueue]
+  );
+
+  /**
+   * Clear the current announcement
+   */
+  const clear = useCallback(() => {
+    setCurrentMessage("");
+    queueRef.current = [];
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+    isProcessingRef.current = false;
+  }, []);
+
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    announce,
+    currentMessage,
+    currentPoliteness,
+    clear,
+  };
+}