aac-board-viewer 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Will Wade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,301 @@
+# AAC Board Viewer
+
+Universal AAC (Augmentative and Alternative Communication) board viewer component for React. Display and interact with communication boards from multiple AAC systems.
+
+## Supported Formats
+
+- **Grid 3** (`.gridset` files)
+- **TouchChat** (`.ce` files)
+- **TD Snap** (`.sps`, `.spb` files)
+- **OpenBoard** (`.obf`, `.obz` files)
+- **Asterics Grid** (`.grd` files)
+- **Apple Panels** (`.plist` files)
+- **OPML** (`.opml` files)
+- **Excel** (`.xlsx` boards)
+- **DOT files** (`.dot` visualizations)
+
+## Features
+
+- 🎯 **Universal Support** - Works with all major AAC file formats
+- 📱 **Responsive Design** - Mobile-friendly with touch support
+- 🎨 **Preserves Styling** - Maintains original colors, fonts, and layouts
+- 🔗 **Interactive Navigation** - Click buttons to navigate between pages
+- 🗣️ **Sentence Building** - Tap buttons to build sentences
+- 🔧 **Customizable** - Flexible styling and behavior options (toggle message bar, link indicators, effort badges)
+- 🌙 **Dark-mode Friendly** - Inherits host app theme when a parent adds the `dark` class
+
+## Installation
+
+Requires Node 20+.
+
+```bash
+npm install aac-board-viewer
+```
+
+Or with yarn:
+
+```bash
+yarn add aac-board-viewer
+```
+
+## Quick Start
+
+### Client-Side Usage
+
+```tsx
+import { BoardViewer, useAACFile } from 'aac-board-viewer';
+import 'aac-board-viewer/styles';
+
+function MyViewer() {
+  const { tree, loading, error } = useAACFile('/path/to/file.sps');
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return <BoardViewer tree={tree} />;
+}
+```
+
+### Server-Side / API Usage
+
+```tsx
+import { BoardViewer } from 'aac-board-viewer';
+import 'aac-board-viewer/styles';
+
+function MyViewer({ treeData }) {
+  return (
+    <BoardViewer
+      tree={treeData}
+      buttonMetrics={metricsData}
+      showMessageBar={true}
+      showEffortBadges={true}
+    />
+  );
+}
+```
+
+### With Metrics
+
+```tsx
+import { BoardViewer, loadAACFile, calculateMetrics } from 'aac-board-viewer';
+
+function MetricsViewer({ filePath }) {
+  const [tree, setTree] = useState(null);
+  const [metrics, setMetrics] = useState(null);
+
+  useEffect(() => {
+    async function load() {
+      const loadedTree = await loadAACFile(filePath);
+      const calculatedMetrics = await calculateMetrics(loadedTree);
+
+      setTree(loadedTree);
+      setMetrics(calculatedMetrics);
+    }
+    load();
+  }, [filePath]);
+
+  if (!tree) return <div>Loading...</div>;
+
+  return (
+    <BoardViewer
+      tree={tree}
+      buttonMetrics={metrics}
+      showEffortBadges={true}
+    />
+  );
+}
+```
+
+## Props
+
+### BoardViewer
+
+```typescript
+interface BoardViewerProps {
+  tree: AACTree;
+  buttonMetrics?: ButtonMetric[] | null;
+  showMessageBar?: boolean;
+  showEffortBadges?: boolean;
+  showLinkIndicators?: boolean;
+  onButtonClick?: (button: AACButton) => void;
+  onPageChange?: (pageId: string) => void;
+  className?: string;
+}
+```
+
+### AACTree
+
+```typescript
+interface AACTree {
+  pages: { [key: string]: AACPage };
+  rootId?: string;
+  toolbarId?: string;
+  metadata?: {
+    format?: string;
+    name?: string;
+    description?: string;
+    [key: string]: any;
+  };
+}
+```
+
+## Advanced Usage
+
+### Custom Styling
+
+```tsx
+<BoardViewer
+  tree={tree}
+  className="my-custom-board"
+/>
+```
+
+### Event Handling
+
+```tsx
+<BoardViewer
+  tree={tree}
+  onButtonClick={(button) => {
+    console.log('Button clicked:', button.label);
+    // Track analytics, play sound, etc.
+  }}
+  onPageChange={(pageId) => {
+    console.log('Page changed to:', pageId);
+    // Track navigation
+  }}
+/>
+```
+
+### Hide Message Bar
+
+```tsx
+<BoardViewer
+  tree={tree}
+  showMessageBar={false}
+/>
+```
+
+## File Loading
+
+The library provides utilities for loading AAC files:
+
+### Client-Side Loading
+
+```tsx
+import { useAACFile } from 'aac-board-viewer';
+
+function Viewer({ fileUrl }) {
+  const { tree, loading, error } = useAACFile(fileUrl);
+
+  // ...
+}
+```
+
+### Programmatic Loading
+
+```tsx
+import { loadAACFile } from 'aac-board-viewer';
+
+const tree = await loadAACFile('/path/to/file.gridset');
+```
+
+### From File Input
+
+```tsx
+import { loadAACFileFromFile } from 'aac-board-viewer';
+
+function FileInput() {
+  const handleChange = async (e) => {
+    const file = e.target.files[0];
+    const tree = await loadAACFileFromFile(file);
+    // Use tree...
+  };
+
+  return <input type="file" onChange={handleChange} />;
+}
+```
+
+## Metrics Calculation
+
+Calculate cognitive effort metrics for buttons:
+
+```tsx
+import { calculateMetrics } from 'aac-board-viewer';
+
+const metrics = await calculateMetrics(tree, {
+  accessMethod: 'direct', // or 'scanning'
+  scanningConfig: {
+    pattern: 'row-column', // 'linear', 'row-column', 'block'
+    selectionMethod: 'auto-1-switch',
+    errorCorrection: false,
+  },
+});
+
+// metrics is an array of ButtonMetric objects:
+// [{ id, label, effort, count, is_word, level }, ...]
+```
+
+## Format-Specific Notes
+
+### Apple Panels
+
+Apple Panels use free-form positioning. The viewer automatically:
+- Converts absolute positioning to grid layout
+- Calculates appropriate grid dimensions
+- Preserves original button placement
+
+### Asterics Grid
+
+Asterics files (`.grd`) are automatically detected and processed using the Asterics Grid processor.
+
+### GridSet / SNAP / TouchChat
+
+These formats use native grid layouts and are displayed as-is, preserving:
+- Grid dimensions (rows × columns)
+- Button colors and borders
+- Font sizes and styles
+- Navigation links between pages
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run demo app
+npm run dev
+
+# Build library
+npm run build
+
+# Type check
+npm run type-check
+
+# Lint
+npm run lint
+```
+
+## Examples
+
+See the `/demo` directory for complete examples:
+- Basic viewer
+- With metrics
+- Multiple formats
+- Server-side rendering
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Related Packages
+
+- [@willwade/aac-processors](https://github.com/willwade/AACProcessors-nodejs) - Core AAC file processing library
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/willwade/aac-board-viewer/issues)
+- Documentation: [Full Docs](https://github.com/willwade/aac-board-viewer/wiki)

package/dist/index.d.mts

@@ -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 };