@imjp/writenex-astro 0.1.0

package/src/client/hooks/useApi.ts

@@ -0,0 +1,374 @@
+/**
+ * @fileoverview API hooks for Writenex client
+ *
+ * Custom React hooks for interacting with the Writenex API.
+ * These hooks use the shared API client from ApiContext when available,
+ * falling back to creating a new client for standalone usage.
+ *
+ * @module @writenex/astro/client/hooks/useApi
+ */
+
+import { useState, useCallback, useMemo } from "react";
+
+/**
+ * Collection data from API
+ */
+export interface Collection {
+  name: string;
+  path: string;
+  filePattern: string;
+  count: number;
+  schema?: Record<string, unknown>;
+  previewUrl?: string;
+}
+
+/**
+ * Content summary for listing
+ */
+export interface ContentSummary {
+  id: string;
+  path: string;
+  title: string;
+  pubDate?: string;
+  draft?: boolean;
+  excerpt?: string;
+}
+
+/**
+ * Full content item
+ */
+export interface ContentItem {
+  id: string;
+  path: string;
+  frontmatter: Record<string, unknown>;
+  body: string;
+  raw: string;
+}
+
+/**
+ * API client configuration
+ */
+interface ApiConfig {
+  apiBase: string;
+}
+
+/**
+ * Image configuration from API
+ */
+export interface ImageConfig {
+  strategy: "colocated" | "public" | "custom";
+  publicPath?: string;
+  storagePath?: string;
+}
+
+/**
+ * Editor configuration from API
+ */
+export interface EditorConfig {
+  autosave?: boolean;
+  autosaveInterval?: number;
+}
+
+/**
+ * Writenex configuration from API
+ */
+export interface WritenexClientConfig {
+  images?: ImageConfig;
+  editor?: EditorConfig;
+  /** Astro's trailingSlash setting for preview URLs */
+  trailingSlash?: "always" | "never" | "ignore";
+}
+
+/**
+ * Config path response from API
+ */
+export interface ConfigPathResponse {
+  configPath: string | null;
+  projectRoot: string;
+  hasConfigFile: boolean;
+}
+
+/**
+ * Create API client functions
+ */
+export function createApiClient(config: ApiConfig) {
+  const { apiBase } = config;
+
+  // Extract basePath from apiBase (remove /api suffix)
+  const basePath = apiBase.replace(/\/api$/, "");
+
+  return {
+    /** Base path for the Writenex editor (without /api) */
+    basePath,
+    /**
+     * Fetch configuration
+     */
+    async getConfig(): Promise<WritenexClientConfig> {
+      const response = await fetch(`${apiBase}/config`);
+      if (!response.ok) {
+        throw new Error("Failed to fetch config");
+      }
+      return response.json();
+    },
+
+    /**
+     * Fetch config file path for opening in editor
+     */
+    async getConfigPath(): Promise<ConfigPathResponse> {
+      const response = await fetch(`${apiBase}/config/path`);
+      if (!response.ok) {
+        throw new Error("Failed to fetch config path");
+      }
+      return response.json();
+    },
+
+    /**
+     * Fetch all collections
+     */
+    async getCollections(): Promise<Collection[]> {
+      const response = await fetch(`${apiBase}/collections`);
+      if (!response.ok) {
+        throw new Error("Failed to fetch collections");
+      }
+      const data = await response.json();
+      return data.collections;
+    },
+
+    /**
+     * Fetch content list for a collection
+     */
+    async getContentList(
+      collection: string,
+      options?: {
+        includeDrafts?: boolean;
+        sort?: string;
+        order?: "asc" | "desc";
+      }
+    ): Promise<ContentSummary[]> {
+      const params = new URLSearchParams();
+      if (options?.includeDrafts) params.set("draft", "true");
+      if (options?.sort) params.set("sort", options.sort);
+      if (options?.order) params.set("order", options.order);
+
+      const url = `${apiBase}/content/${collection}${params.toString() ? `?${params}` : ""}`;
+      const response = await fetch(url);
+      if (!response.ok) {
+        throw new Error("Failed to fetch content list");
+      }
+      const data = await response.json();
+      return data.items;
+    },
+
+    /**
+     * Fetch single content item
+     */
+    async getContent(collection: string, id: string): Promise<ContentItem> {
+      const response = await fetch(`${apiBase}/content/${collection}/${id}`);
+      if (!response.ok) {
+        throw new Error("Failed to fetch content");
+      }
+      return response.json();
+    },
+
+    /**
+     * Create new content
+     */
+    async createContent(
+      collection: string,
+      data: {
+        frontmatter: Record<string, unknown>;
+        body: string;
+        slug?: string;
+      }
+    ): Promise<{
+      success: boolean;
+      id?: string;
+      path?: string;
+      error?: string;
+    }> {
+      const response = await fetch(`${apiBase}/content/${collection}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      return response.json();
+    },
+
+    /**
+     * Update content
+     */
+    async updateContent(
+      collection: string,
+      id: string,
+      data: { frontmatter?: Record<string, unknown>; body?: string }
+    ): Promise<{ success: boolean; error?: string }> {
+      const response = await fetch(`${apiBase}/content/${collection}/${id}`, {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(data),
+      });
+      return response.json();
+    },
+
+    /**
+     * Delete content
+     */
+    async deleteContent(
+      collection: string,
+      id: string
+    ): Promise<{ success: boolean; error?: string }> {
+      const response = await fetch(`${apiBase}/content/${collection}/${id}`, {
+        method: "DELETE",
+      });
+      return response.json();
+    },
+
+    /**
+     * Upload image
+     */
+    async uploadImage(
+      file: File,
+      collection: string,
+      contentId: string
+    ): Promise<{
+      success: boolean;
+      path?: string;
+      url?: string;
+      error?: string;
+    }> {
+      const formData = new FormData();
+      formData.append("file", file);
+      formData.append("collection", collection);
+      formData.append("contentId", contentId);
+
+      const response = await fetch(`${apiBase}/images`, {
+        method: "POST",
+        body: formData,
+      });
+      return response.json();
+    },
+  };
+}
+
+/**
+ * Hook for using the API client
+ *
+ * Creates a memoized API client instance that persists across re-renders.
+ * For shared usage across the app, consider using ApiProvider and useSharedApi instead.
+ */
+export function useApi(apiBase: string) {
+  const client = useMemo(() => createApiClient({ apiBase }), [apiBase]);
+  return client;
+}
+
+/** API client type */
+export type ApiClient = ReturnType<typeof createApiClient>;
+
+/**
+ * Hook for fetching collections
+ *
+ * @param apiBaseOrClient - Either an API base URL string or a pre-created API client
+ */
+export function useCollections(apiBaseOrClient: string | ApiClient) {
+  const client = useMemo(() => {
+    if (typeof apiBaseOrClient === "string") {
+      return createApiClient({ apiBase: apiBaseOrClient });
+    }
+    return apiBaseOrClient;
+  }, [apiBaseOrClient]);
+  const [collections, setCollections] = useState<Collection[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getCollections();
+      setCollections(data);
+    } catch (err) {
+      setError(
+        err instanceof Error ? err.message : "Failed to fetch collections"
+      );
+    } finally {
+      setLoading(false);
+    }
+  }, [client]);
+
+  return { collections, loading, error, refresh };
+}
+
+/**
+ * Hook for fetching content list
+ *
+ * @param apiBaseOrClient - Either an API base URL string or a pre-created API client
+ * @param collection - Collection name to fetch content from
+ */
+export function useContentList(
+  apiBaseOrClient: string | ApiClient,
+  collection: string | null
+) {
+  const client = useMemo(() => {
+    if (typeof apiBaseOrClient === "string") {
+      return createApiClient({ apiBase: apiBaseOrClient });
+    }
+    return apiBaseOrClient;
+  }, [apiBaseOrClient]);
+  const [items, setItems] = useState<ContentSummary[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    if (!collection) {
+      setItems([]);
+      return;
+    }
+
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getContentList(collection, {
+        includeDrafts: true,
+      });
+      setItems(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch content");
+    } finally {
+      setLoading(false);
+    }
+  }, [client, collection]);
+
+  return { items, loading, error, refresh };
+}
+
+/**
+ * Hook for fetching configuration
+ *
+ * @param apiBaseOrClient - Either an API base URL string or a pre-created API client
+ */
+export function useConfig(apiBaseOrClient: string | ApiClient) {
+  const client = useMemo(() => {
+    if (typeof apiBaseOrClient === "string") {
+      return createApiClient({ apiBase: apiBaseOrClient });
+    }
+    return apiBaseOrClient;
+  }, [apiBaseOrClient]);
+  const [config, setConfig] = useState<WritenexClientConfig | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const refresh = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const data = await client.getConfig();
+      setConfig(data);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : "Failed to fetch config");
+    } finally {
+      setLoading(false);
+    }
+  }, [client]);
+
+  return { config, loading, error, refresh };
+}

package/src/client/hooks/useArrowNavigation.ts

@@ -0,0 +1,286 @@
+/**
+ * @fileoverview Arrow key navigation hook for list accessibility
+ *
+ * This hook provides arrow key navigation for lists and tab panels,
+ * supporting both vertical (ArrowUp/ArrowDown) and horizontal
+ * (ArrowLeft/ArrowRight) navigation patterns.
+ *
+ * ## Features:
+ * - Vertical arrow key navigation for lists
+ * - Horizontal arrow key navigation for tabs
+ * - Loop and non-loop modes
+ * - Enter key for selection
+ * - Home/End key support
+ *
+ * @module @writenex/astro/client/hooks/useArrowNavigation
+ */
+
+import { useCallback, useEffect, useRef } from "react";
+
+/**
+ * Navigation orientation
+ */
+export type NavigationOrientation = "vertical" | "horizontal";
+
+/**
+ * Options for useArrowNavigation hook
+ */
+export interface UseArrowNavigationOptions {
+  /** List of item IDs or refs */
+  items: string[] | React.RefObject<HTMLElement | null>[];
+  /** Current focused index */
+  currentIndex: number;
+  /** Callback when index changes */
+  onIndexChange: (index: number) => void;
+  /** Callback when Enter is pressed on an item */
+  onSelect?: (index: number) => void;
+  /** Whether navigation is vertical (default) or horizontal */
+  orientation?: NavigationOrientation;
+  /** Whether to loop at boundaries (default: true) */
+  loop?: boolean;
+  /** Whether the navigation is enabled (default: true) */
+  enabled?: boolean;
+}
+
+/**
+ * Return value from useArrowNavigation hook
+ */
+export interface UseArrowNavigationReturn {
+  /** Ref to attach to the container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Handle keydown event (for manual attachment) */
+  handleKeyDown: (event: React.KeyboardEvent) => void;
+  /** Move focus to next item */
+  focusNext: () => void;
+  /** Move focus to previous item */
+  focusPrevious: () => void;
+  /** Move focus to first item */
+  focusFirst: () => void;
+  /** Move focus to last item */
+  focusLast: () => void;
+}
+
+/**
+ * Get the element at a given index from items array
+ */
+function getElementAtIndex(
+  items: string[] | React.RefObject<HTMLElement | null>[],
+  index: number
+): HTMLElement | null {
+  if (index < 0 || index >= items.length) return null;
+
+  const item = items[index];
+
+  // Check if it's a ref
+  if (item && typeof item === "object" && "current" in item) {
+    return item.current;
+  }
+
+  // It's an ID string
+  if (typeof item === "string") {
+    return document.getElementById(item);
+  }
+
+  return null;
+}
+
+/**
+ * Hook for arrow key navigation in lists and tab panels
+ *
+ * This hook implements the WAI-ARIA keyboard navigation patterns
+ * for lists and tabs, allowing users to navigate using arrow keys.
+ *
+ * @param options - Navigation configuration options
+ * @returns Object containing container ref and navigation functions
+ *
+ * @example
+ * ```tsx
+ * function CollectionList({ collections, selectedIndex, onSelect }) {
+ *   const { containerRef, handleKeyDown } = useArrowNavigation({
+ *     items: collections.map(c => c.id),
+ *     currentIndex: selectedIndex,
+ *     onIndexChange: setSelectedIndex,
+ *     onSelect: (index) => onSelect(collections[index]),
+ *     orientation: 'vertical',
+ *     loop: true,
+ *   });
+ *
+ *   return (
+ *     <ul ref={containerRef} role="listbox" onKeyDown={handleKeyDown}>
+ *       {collections.map((collection, index) => (
+ *         <li
+ *           key={collection.id}
+ *           id={collection.id}
+ *           role="option"
+ *           aria-selected={index === selectedIndex}
+ *           tabIndex={index === selectedIndex ? 0 : -1}
+ *         >
+ *           {collection.name}
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export function useArrowNavigation(
+  options: UseArrowNavigationOptions
+): UseArrowNavigationReturn {
+  const {
+    items,
+    currentIndex,
+    onIndexChange,
+    onSelect,
+    orientation = "vertical",
+    loop = true,
+    enabled = true,
+  } = options;
+
+  const containerRef = useRef<HTMLElement | null>(null);
+
+  /**
+   * Calculate the next index based on direction
+   */
+  const getNextIndex = useCallback(
+    (direction: "next" | "previous"): number => {
+      if (items.length === 0) return -1;
+
+      if (direction === "next") {
+        const nextIndex = currentIndex + 1;
+        if (nextIndex >= items.length) {
+          return loop ? 0 : currentIndex;
+        }
+        return nextIndex;
+      } else {
+        const prevIndex = currentIndex - 1;
+        if (prevIndex < 0) {
+          return loop ? items.length - 1 : currentIndex;
+        }
+        return prevIndex;
+      }
+    },
+    [items.length, currentIndex, loop]
+  );
+
+  /**
+   * Move focus to next item
+   */
+  const focusNext = useCallback(() => {
+    const nextIndex = getNextIndex("next");
+    if (nextIndex !== currentIndex) {
+      onIndexChange(nextIndex);
+      const element = getElementAtIndex(items, nextIndex);
+      element?.focus();
+    }
+  }, [getNextIndex, currentIndex, onIndexChange, items]);
+
+  /**
+   * Move focus to previous item
+   */
+  const focusPrevious = useCallback(() => {
+    const prevIndex = getNextIndex("previous");
+    if (prevIndex !== currentIndex) {
+      onIndexChange(prevIndex);
+      const element = getElementAtIndex(items, prevIndex);
+      element?.focus();
+    }
+  }, [getNextIndex, currentIndex, onIndexChange, items]);
+
+  /**
+   * Move focus to first item
+   */
+  const focusFirst = useCallback(() => {
+    if (items.length === 0) return;
+    onIndexChange(0);
+    const element = getElementAtIndex(items, 0);
+    element?.focus();
+  }, [items, onIndexChange]);
+
+  /**
+   * Move focus to last item
+   */
+  const focusLast = useCallback(() => {
+    if (items.length === 0) return;
+    const lastIndex = items.length - 1;
+    onIndexChange(lastIndex);
+    const element = getElementAtIndex(items, lastIndex);
+    element?.focus();
+  }, [items, onIndexChange]);
+
+  /**
+   * Handle keydown event
+   */
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (!enabled || items.length === 0) return;
+
+      const isVertical = orientation === "vertical";
+      const nextKey = isVertical ? "ArrowDown" : "ArrowRight";
+      const prevKey = isVertical ? "ArrowUp" : "ArrowLeft";
+
+      switch (event.key) {
+        case nextKey:
+          event.preventDefault();
+          focusNext();
+          break;
+
+        case prevKey:
+          event.preventDefault();
+          focusPrevious();
+          break;
+
+        case "Home":
+          event.preventDefault();
+          focusFirst();
+          break;
+
+        case "End":
+          event.preventDefault();
+          focusLast();
+          break;
+
+        case "Enter":
+        case " ":
+          if (onSelect && currentIndex >= 0) {
+            event.preventDefault();
+            onSelect(currentIndex);
+          }
+          break;
+      }
+    },
+    [
+      enabled,
+      items.length,
+      orientation,
+      focusNext,
+      focusPrevious,
+      focusFirst,
+      focusLast,
+      onSelect,
+      currentIndex,
+    ]
+  );
+
+  // Focus the current item when index changes externally
+  useEffect(() => {
+    if (!enabled || currentIndex < 0) return;
+
+    const element = getElementAtIndex(items, currentIndex);
+    if (element && document.activeElement !== element) {
+      // Only focus if the container or one of its children has focus
+      const container = containerRef.current;
+      if (container && container.contains(document.activeElement)) {
+        element.focus();
+      }
+    }
+  }, [enabled, currentIndex, items]);
+
+  return {
+    containerRef,
+    handleKeyDown,
+    focusNext,
+    focusPrevious,
+    focusFirst,
+    focusLast,
+  };
+}