aac-board-viewer 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as _willwade_aac_processors from '@willwade/aac-processors';
+import { AACTree } from '@willwade/aac-processors';
+export { AACButton, AACPage, AACSemanticAction, AACSemanticCategory, AACSemanticIntent, AACTree } from '@willwade/aac-processors';
+
+/**
+ * Button metric information for effort scoring
+ */
+interface ButtonMetric {
+    /** Button ID */
+    id: string;
+    /** Button label text */
+    label: string;
+    /** Cognitive effort score (lower is easier) */
+    effort: number;
+    /** Usage count */
+    count?: number;
+    /** Whether the button represents a word */
+    is_word?: boolean;
+    /** Depth level in navigation tree */
+    level?: number;
+}
+/**
+ * Props for BoardViewer component
+ */
+interface BoardViewerProps {
+    /** The AAC tree containing pages and navigation structure */
+    tree: _willwade_aac_processors.AACTree;
+    /** Optional button metrics to display effort scores */
+    buttonMetrics?: ButtonMetric[] | null;
+    /** Show the message bar at the top (default: true) */
+    showMessageBar?: boolean;
+    /** Show effort badges on buttons (default: true if metrics provided) */
+    showEffortBadges?: boolean;
+    /** Show indicators for buttons that link to other pages (default: true) */
+    showLinkIndicators?: boolean;
+    /** Start the viewer on this page id (overrides tree.rootId) */
+    initialPageId?: string;
+    /** Callback when a button is clicked */
+    onButtonClick?: (button: _willwade_aac_processors.AACButton) => void;
+    /** Callback when page changes */
+    onPageChange?: (pageId: string) => void;
+    /** Custom CSS class name */
+    className?: string;
+}
+/**
+ * Result from loading an AAC file
+ */
+interface LoadAACFileResult {
+    tree: _willwade_aac_processors.AACTree;
+    format: string;
+    metadata?: {
+        [key: string]: unknown;
+    };
+}
+
+interface MetricsOptions {
+    /** Access method: 'direct' or 'scanning' */
+    accessMethod?: 'direct' | 'scanning';
+    /** Scanning configuration */
+    scanningConfig?: {
+        /** Scanning pattern: 'linear', 'row-column', or 'block' */
+        pattern?: 'linear' | 'row-column' | 'block';
+        /** Selection method for scanning */
+        selectionMethod?: string;
+        /** Enable error correction */
+        errorCorrection?: boolean;
+    };
+}
+
+/**
+ * AAC Board Viewer Component
+ *
+ * Displays AAC boards with interactive navigation, sentence building,
+ * and optional effort metrics.
+ *
+ * @param props - BoardViewerProps
+ */
+declare function BoardViewer({ tree, buttonMetrics, showMessageBar, showEffortBadges, showLinkIndicators, initialPageId, onButtonClick, onPageChange, className, }: BoardViewerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * React hooks for AAC Board Viewer
+ */
+
+/**
+ * Hook to load an AAC file from a URL
+ *
+ * @param url - URL to the AAC file
+ * @param options - Processor options (e.g., pageLayoutPreference for SNAP)
+ * @returns Object with tree, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyViewer() {
+ *   const { tree, loading, error, reload } = useAACFile('/files/board.sps');
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return <BoardViewer tree={tree} />;
+ * }
+ * ```
+ */
+declare function useAACFile(url: string, 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
+ *
+ * @param url - URL to the AAC file
+ * @param metricsOptions - Metrics calculation options
+ * @returns Object with tree, metrics, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyViewer() {
+ *   const { tree, metrics, loading, error } = useAACFileWithMetrics(
+ *     '/files/board.sps',
+ *     { accessMethod: 'direct' }
+ *   );
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return <BoardViewer tree={tree} buttonMetrics={metrics} />;
+ * }
+ * ```
+ */
+declare function useAACFileWithMetrics(url: string, 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
+ *
+ * @param tree - The AAC tree
+ * @param options - Metrics calculation options
+ * @returns Object with metrics, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MyViewer({ tree }) {
+ *   const { metrics, loading } = useMetrics(tree, {
+ *     accessMethod: 'scanning',
+ *     scanningConfig: { pattern: 'row-column' }
+ *   });
+ *
+ *   return <BoardViewer tree={tree} buttonMetrics={metrics} />;
+ * }
+ * ```
+ */
+declare function useMetrics(tree: AACTree | null, options?: MetricsOptions): {
+    metrics: ButtonMetric[] | null;
+    loading: boolean;
+    error: Error | null;
+    recalculate: () => Promise<void>;
+};
+/**
+ * Hook for sentence building state
+ *
+ * @returns Object with message state and handlers
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { message, wordCount, effort, addWord, clear } = useSentenceBuilder();
+ *
+ *   return (
+ *     <div>
+ *       <p>{message || 'Start building...'}</p>
+ *       <p>{wordCount} words, {effort.toFixed(2)} effort</p>
+ *       <button onClick={clear}>Clear</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSentenceBuilder(): {
+    message: string;
+    wordCount: number;
+    effort: number;
+    addWord: (word: string, wordEffort?: number) => void;
+    clear: () => void;
+};
+
+/**
+ * AAC File Loading Utilities
+ *
+ * Provides utilities for loading AAC files from various sources
+ * (URLs, File objects, file paths) in both client and server contexts.
+ */
+
+type ProcessorOptions = Record<string, unknown> | undefined;
+/**
+ * Load an AAC file from a file path (server-side only)
+ *
+ * @param filepath - Path to the AAC file
+ * @param options - Processor options (e.g., pageLayoutPreference for SNAP)
+ * @returns Promise resolving to AACTree
+ *
+ * @example
+ * ```ts
+ * const tree = await loadAACFile('/path/to/file.sps');
+ * ```
+ */
+declare function loadAACFile(filepath: string, options?: ProcessorOptions): Promise<AACTree>;
+/**
+ * Load an AAC file and return extended result with format info
+ *
+ * @param filepath - Path to the AAC file
+ * @param options - Processor options
+ * @returns Promise resolving to LoadAACFileResult
+ */
+declare function loadAACFileWithMetadata(filepath: string, options?: ProcessorOptions): Promise<LoadAACFileResult>;
+/**
+ * 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.
+ *
+ * @param url - URL to the AAC file
+ * @param options - Processor options
+ * @returns Promise resolving to AACTree
+ *
+ * @example
+ * ```ts
+ * const tree = await loadAACFileFromURL('https://example.com/file.sps');
+ * ```
+ */
+declare function loadAACFileFromURL(url: string, options?: ProcessorOptions): Promise<AACTree>;
+/**
+ * Load an AAC file from a File object (client-side file input)
+ *
+ * @param file - File object from file input
+ * @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...
+ * };
+ * ```
+ */
+declare function loadAACFileFromFile(_file: File | Blob, _filename?: string, _options?: unknown): Promise<AACTree>;
+/**
+ * Calculate cognitive effort metrics for an AAC tree
+ *
+ * @param tree - The AAC tree
+ * @param options - Metrics calculation options
+ * @returns Promise resolving to array of ButtonMetrics
+ *
+ * @example
+ * ```ts
+ * import { calculateMetrics } from 'aac-board-viewer';
+ *
+ * const metrics = await calculateMetrics(tree, {
+ *   accessMethod: 'direct',
+ * });
+ * ```
+ */
+declare function calculateMetrics(tree: AACTree, options?: {
+    accessMethod?: 'direct' | 'scanning';
+    scanningConfig?: {
+        pattern?: 'linear' | 'row-column' | 'block';
+        selectionMethod?: string;
+        errorCorrection?: boolean;
+    };
+}): Promise<{
+    id: string;
+    label: string;
+    effort: number;
+    count: number;
+    is_word: boolean;
+    level: number | undefined;
+    semantic_id: string | undefined;
+    clone_id: string | undefined;
+}[]>;
+/**
+ * Get a list of supported file formats
+ *
+ * @returns Array of format information
+ */
+declare function getSupportedFormats(): Array<{
+    name: string;
+    extensions: string[];
+    description: string;
+}>;
+
+export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getSupportedFormats, loadAACFile, loadAACFileFromFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileWithMetrics, useMetrics, useSentenceBuilder };