aac-board-viewer 0.1.5 → 0.1.7

package/dist/index.d.mts

@@ -42,6 +42,8 @@ interface BoardViewerProps {
     onPageChange?: (pageId: string) => void;
     /** Custom CSS class name */
     className?: string;
+    /** Load ID for fetching images from server (for OBZ files) */
+    loadId?: string;
 }
 /**
  * Result from loading an AAC file
@@ -76,7 +78,7 @@ interface MetricsOptions {
  *
  * @param props - BoardViewerProps
  */
-declare function BoardViewer({ tree, buttonMetrics, showMessageBar, showEffortBadges, showLinkIndicators, initialPageId, onButtonClick, onPageChange, className, }: BoardViewerProps): react_jsx_runtime.JSX.Element;
+declare function BoardViewer({ tree, buttonMetrics, showMessageBar, showEffortBadges, showLinkIndicators, initialPageId, onButtonClick, onPageChange, className, loadId, }: BoardViewerProps): react_jsx_runtime.JSX.Element;
 
 /**
  * React hooks for AAC Board Viewer
@@ -110,6 +112,38 @@ declare function useAACFile(url: string, options?: {
     error: Error | null;
     reload: () => Promise<void>;
 };
+/**
+ * Hook to load an AAC file from a File object (Browser only)
+ *
+ * @param file - File object from file input
+ * @param options - Processor options
+ * @returns Object with tree, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyUploader() {
+ *   const [file, setFile] = useState<File | null>(null);
+ *   const { tree, loading, error } = useAACFileFromFile(file);
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={(e) => setFile(e.target.files?.[0])} />
+ *       {loading && <div>Loading...</div>}
+ *       {tree && <BoardViewer tree={tree} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAACFileFromFile(file: File | Blob | null, options?: {
+    processorOptions?: Record<string, unknown>;
+    enabled?: boolean;
+}): {
+    tree: AACTree | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+};
 /**
  * Hook to load an AAC file and calculate metrics
  *
@@ -142,6 +176,42 @@ declare function useAACFileWithMetrics(url: string, metricsOptions?: MetricsOpti
     error: Error | null;
     reload: () => Promise<void>;
 };
+/**
+ * Hook to load an AAC file from a File object and calculate metrics
+ *
+ * @param file - File object from file input
+ * @param metricsOptions - Metrics calculation options
+ * @returns Object with tree, metrics, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyUploader() {
+ *   const [file, setFile] = useState<File | null>(null);
+ *   const { tree, metrics, loading, error } = useAACFileFromFileWithMetrics(
+ *     file,
+ *     { accessMethod: 'direct' }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={(e) => setFile(e.target.files?.[0])} />
+ *       {loading && <div>Loading...</div>}
+ *       {tree && <BoardViewer tree={tree} buttonMetrics={metrics} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAACFileFromFileWithMetrics(file: File | Blob | null, metricsOptions?: MetricsOptions, fileOptions?: {
+    processorOptions?: Record<string, unknown>;
+    enabled?: boolean;
+}): {
+    tree: AACTree | null;
+    metrics: ButtonMetric[] | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+};
 /**
  * Hook to calculate metrics for a tree
  *
@@ -199,12 +269,15 @@ declare function useSentenceBuilder(): {
  * AAC File Loading Utilities
  *
  * Provides utilities for loading AAC files from various sources
- * (URLs, File objects, file paths) in both client and server contexts.
+ * (File/Blob objects, file paths, URLs) in both browser and server contexts.
+ *
+ * Browser: Supports .obf, .obz, .gridset, .plist, .grd, .opml, .dot
+ * Node.js: Supports all formats including .sps, .spb, .ce (Node-only processors)
  */
 
 type ProcessorOptions = Record<string, unknown> | undefined;
 /**
- * Load an AAC file from a file path (server-side only)
+ * Load an AAC file from a file path (Node.js only)
  *
  * @param filepath - Path to the AAC file
  * @param options - Processor options (e.g., pageLayoutPreference for SNAP)
@@ -217,47 +290,59 @@ type ProcessorOptions = Record<string, unknown> | undefined;
  */
 declare function loadAACFile(filepath: string, options?: ProcessorOptions): Promise<AACTree>;
 /**
- * Load an AAC file and return extended result with format info
+ * Load an AAC file from a File or Blob object (Browser only)
  *
- * @param filepath - Path to the AAC file
+ * @param file - File or Blob object
  * @param options - Processor options
- * @returns Promise resolving to LoadAACFileResult
+ * @returns Promise resolving to AACTree
+ *
+ * @example
+ * ```ts
+ * const input = document.querySelector('input[type="file"]');
+ * const file = input.files[0];
+ * const tree = await loadAACFile(file);
+ * ```
  */
-declare function loadAACFileWithMetadata(filepath: string, options?: ProcessorOptions): Promise<LoadAACFileResult>;
+declare function loadAACFile(file: File | Blob, options?: ProcessorOptions): Promise<AACTree>;
 /**
- * Load an AAC file from a URL (client-side)
- *
- * Note: This requires the server to provide the file with appropriate CORS headers.
- * For better performance, consider server-side loading instead.
+ * Load an AAC file from an ArrayBuffer (Browser only)
  *
- * @param url - URL to the AAC file
+ * @param buffer - ArrayBuffer containing file data
+ * @param filename - Filename with extension to detect processor
  * @param options - Processor options
  * @returns Promise resolving to AACTree
  *
  * @example
  * ```ts
- * const tree = await loadAACFileFromURL('https://example.com/file.sps');
+ * const arrayBuffer = await file.arrayBuffer();
+ * const tree = await loadAACFile(arrayBuffer, 'board.obf');
  * ```
  */
-declare function loadAACFileFromURL(url: string, options?: ProcessorOptions): Promise<AACTree>;
+declare function loadAACFile(buffer: ArrayBuffer, filename: string, options?: ProcessorOptions): Promise<AACTree>;
 /**
- * Load an AAC file from a File object (client-side file input)
+ * Load an AAC file from a URL (Browser only)
  *
- * @param file - File object from file input
+ * Note: This requires the server to provide the file with appropriate CORS headers.
+ * For better performance, consider using loadAACFileFromFile() with direct file upload instead.
+ *
+ * @param url - URL to the AAC file
  * @param options - Processor options
  * @returns Promise resolving to AACTree
  *
  * @example
  * ```ts
- * const input = document.querySelector('input[type="file"]');
- * input.onchange = async (e) => {
- *   const file = e.target.files[0];
- *   const tree = await loadAACFileFromFile(file);
- *   // Use tree...
- * };
+ * const tree = await loadAACFileFromURL('https://example.com/file.obf');
  * ```
  */
-declare function loadAACFileFromFile(_file: File | Blob, _filename?: string, _options?: unknown): Promise<AACTree>;
+declare function loadAACFileFromURL(url: string, options?: ProcessorOptions): Promise<AACTree>;
+/**
+ * Load an AAC file and return extended result with format info
+ *
+ * @param input - File path (Node.js), File/Blob (Browser), or URL string
+ * @param options - Processor options
+ * @returns Promise resolving to LoadAACFileResult
+ */
+declare function loadAACFileWithMetadata(input: string | File | Blob, options?: ProcessorOptions): Promise<LoadAACFileResult>;
 /**
  * Calculate cognitive effort metrics for an AAC tree
  *
@@ -300,6 +385,22 @@ declare function getSupportedFormats(): Array<{
     name: string;
     extensions: string[];
     description: string;
+    browserCompatible: boolean;
 }>;
+/**
+ * Check if a file format is compatible with browser processing
+ *
+ * @param extension - File extension (e.g., '.obf', 'obf')
+ * @returns true if browser-compatible, false if server-only
+ */
+declare function isBrowserCompatible(extension: string): boolean;
+/**
+ * Get list of browser-compatible file extensions
+ */
+declare function getBrowserExtensions(): string[];
+/**
+ * Get list of Node-only file extensions
+ */
+declare function getNodeOnlyExtensions(): string[];
 
-export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getSupportedFormats, loadAACFile, loadAACFileFromFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileWithMetrics, useMetrics, useSentenceBuilder };
+export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getBrowserExtensions, getNodeOnlyExtensions, getSupportedFormats, isBrowserCompatible, loadAACFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileFromFile, useAACFileFromFileWithMetrics, useAACFileWithMetrics, useMetrics, useSentenceBuilder };

package/dist/index.d.ts

@@ -42,6 +42,8 @@ interface BoardViewerProps {
     onPageChange?: (pageId: string) => void;
     /** Custom CSS class name */
     className?: string;
+    /** Load ID for fetching images from server (for OBZ files) */
+    loadId?: string;
 }
 /**
  * Result from loading an AAC file
@@ -76,7 +78,7 @@ interface MetricsOptions {
  *
  * @param props - BoardViewerProps
  */
-declare function BoardViewer({ tree, buttonMetrics, showMessageBar, showEffortBadges, showLinkIndicators, initialPageId, onButtonClick, onPageChange, className, }: BoardViewerProps): react_jsx_runtime.JSX.Element;
+declare function BoardViewer({ tree, buttonMetrics, showMessageBar, showEffortBadges, showLinkIndicators, initialPageId, onButtonClick, onPageChange, className, loadId, }: BoardViewerProps): react_jsx_runtime.JSX.Element;
 
 /**
  * React hooks for AAC Board Viewer
@@ -110,6 +112,38 @@ declare function useAACFile(url: string, options?: {
     error: Error | null;
     reload: () => Promise<void>;
 };
+/**
+ * Hook to load an AAC file from a File object (Browser only)
+ *
+ * @param file - File object from file input
+ * @param options - Processor options
+ * @returns Object with tree, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyUploader() {
+ *   const [file, setFile] = useState<File | null>(null);
+ *   const { tree, loading, error } = useAACFileFromFile(file);
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={(e) => setFile(e.target.files?.[0])} />
+ *       {loading && <div>Loading...</div>}
+ *       {tree && <BoardViewer tree={tree} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAACFileFromFile(file: File | Blob | null, options?: {
+    processorOptions?: Record<string, unknown>;
+    enabled?: boolean;
+}): {
+    tree: AACTree | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+};
 /**
  * Hook to load an AAC file and calculate metrics
  *
@@ -142,6 +176,42 @@ declare function useAACFileWithMetrics(url: string, metricsOptions?: MetricsOpti
     error: Error | null;
     reload: () => Promise<void>;
 };
+/**
+ * Hook to load an AAC file from a File object and calculate metrics
+ *
+ * @param file - File object from file input
+ * @param metricsOptions - Metrics calculation options
+ * @returns Object with tree, metrics, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyUploader() {
+ *   const [file, setFile] = useState<File | null>(null);
+ *   const { tree, metrics, loading, error } = useAACFileFromFileWithMetrics(
+ *     file,
+ *     { accessMethod: 'direct' }
+ *   );
+ *
+ *   return (
+ *     <div>
+ *       <input type="file" onChange={(e) => setFile(e.target.files?.[0])} />
+ *       {loading && <div>Loading...</div>}
+ *       {tree && <BoardViewer tree={tree} buttonMetrics={metrics} />}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useAACFileFromFileWithMetrics(file: File | Blob | null, metricsOptions?: MetricsOptions, fileOptions?: {
+    processorOptions?: Record<string, unknown>;
+    enabled?: boolean;
+}): {
+    tree: AACTree | null;
+    metrics: ButtonMetric[] | null;
+    loading: boolean;
+    error: Error | null;
+    reload: () => Promise<void>;
+};
 /**
  * Hook to calculate metrics for a tree
  *
@@ -199,12 +269,15 @@ declare function useSentenceBuilder(): {
  * AAC File Loading Utilities
  *
  * Provides utilities for loading AAC files from various sources
- * (URLs, File objects, file paths) in both client and server contexts.
+ * (File/Blob objects, file paths, URLs) in both browser and server contexts.
+ *
+ * Browser: Supports .obf, .obz, .gridset, .plist, .grd, .opml, .dot
+ * Node.js: Supports all formats including .sps, .spb, .ce (Node-only processors)
  */
 
 type ProcessorOptions = Record<string, unknown> | undefined;
 /**
- * Load an AAC file from a file path (server-side only)
+ * Load an AAC file from a file path (Node.js only)
  *
  * @param filepath - Path to the AAC file
  * @param options - Processor options (e.g., pageLayoutPreference for SNAP)
@@ -217,47 +290,59 @@ type ProcessorOptions = Record<string, unknown> | undefined;
  */
 declare function loadAACFile(filepath: string, options?: ProcessorOptions): Promise<AACTree>;
 /**
- * Load an AAC file and return extended result with format info
+ * Load an AAC file from a File or Blob object (Browser only)
  *
- * @param filepath - Path to the AAC file
+ * @param file - File or Blob object
  * @param options - Processor options
- * @returns Promise resolving to LoadAACFileResult
+ * @returns Promise resolving to AACTree
+ *
+ * @example
+ * ```ts
+ * const input = document.querySelector('input[type="file"]');
+ * const file = input.files[0];
+ * const tree = await loadAACFile(file);
+ * ```
  */
-declare function loadAACFileWithMetadata(filepath: string, options?: ProcessorOptions): Promise<LoadAACFileResult>;
+declare function loadAACFile(file: File | Blob, options?: ProcessorOptions): Promise<AACTree>;
 /**
- * Load an AAC file from a URL (client-side)
- *
- * Note: This requires the server to provide the file with appropriate CORS headers.
- * For better performance, consider server-side loading instead.
+ * Load an AAC file from an ArrayBuffer (Browser only)
  *
- * @param url - URL to the AAC file
+ * @param buffer - ArrayBuffer containing file data
+ * @param filename - Filename with extension to detect processor
  * @param options - Processor options
  * @returns Promise resolving to AACTree
  *
  * @example
  * ```ts
- * const tree = await loadAACFileFromURL('https://example.com/file.sps');
+ * const arrayBuffer = await file.arrayBuffer();
+ * const tree = await loadAACFile(arrayBuffer, 'board.obf');
  * ```
  */
-declare function loadAACFileFromURL(url: string, options?: ProcessorOptions): Promise<AACTree>;
+declare function loadAACFile(buffer: ArrayBuffer, filename: string, options?: ProcessorOptions): Promise<AACTree>;
 /**
- * Load an AAC file from a File object (client-side file input)
+ * Load an AAC file from a URL (Browser only)
  *
- * @param file - File object from file input
+ * Note: This requires the server to provide the file with appropriate CORS headers.
+ * For better performance, consider using loadAACFileFromFile() with direct file upload instead.
+ *
+ * @param url - URL to the AAC file
  * @param options - Processor options
  * @returns Promise resolving to AACTree
  *
  * @example
  * ```ts
- * const input = document.querySelector('input[type="file"]');
- * input.onchange = async (e) => {
- *   const file = e.target.files[0];
- *   const tree = await loadAACFileFromFile(file);
- *   // Use tree...
- * };
+ * const tree = await loadAACFileFromURL('https://example.com/file.obf');
  * ```
  */
-declare function loadAACFileFromFile(_file: File | Blob, _filename?: string, _options?: unknown): Promise<AACTree>;
+declare function loadAACFileFromURL(url: string, options?: ProcessorOptions): Promise<AACTree>;
+/**
+ * Load an AAC file and return extended result with format info
+ *
+ * @param input - File path (Node.js), File/Blob (Browser), or URL string
+ * @param options - Processor options
+ * @returns Promise resolving to LoadAACFileResult
+ */
+declare function loadAACFileWithMetadata(input: string | File | Blob, options?: ProcessorOptions): Promise<LoadAACFileResult>;
 /**
  * Calculate cognitive effort metrics for an AAC tree
  *
@@ -300,6 +385,22 @@ declare function getSupportedFormats(): Array<{
     name: string;
     extensions: string[];
     description: string;
+    browserCompatible: boolean;
 }>;
+/**
+ * Check if a file format is compatible with browser processing
+ *
+ * @param extension - File extension (e.g., '.obf', 'obf')
+ * @returns true if browser-compatible, false if server-only
+ */
+declare function isBrowserCompatible(extension: string): boolean;
+/**
+ * Get list of browser-compatible file extensions
+ */
+declare function getBrowserExtensions(): string[];
+/**
+ * Get list of Node-only file extensions
+ */
+declare function getNodeOnlyExtensions(): string[];
 
-export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getSupportedFormats, loadAACFile, loadAACFileFromFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileWithMetrics, useMetrics, useSentenceBuilder };
+export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getBrowserExtensions, getNodeOnlyExtensions, getSupportedFormats, isBrowserCompatible, loadAACFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileFromFile, useAACFileFromFileWithMetrics, useAACFileWithMetrics, useMetrics, useSentenceBuilder };