aac-board-viewer 0.2.2 → 0.2.3

package/README.md

@@ -14,6 +14,8 @@ Universal AAC (Augmentative and Alternative Communication) board viewer componen
 - **Excel** (`.xlsx` boards)
 - **DOT files** (`.dot` visualizations)
 
+Note: In-browser loading of SQLite-backed formats (`.sps`, `.spb`, `.ce`) requires SQL.js configuration.
+
 ## Features
 
 - 🎯 **Universal Support** - Works with all major AAC file formats
@@ -40,9 +42,36 @@ yarn add aac-board-viewer
 
 ## Quick Start
 
-### Server-Side / API Usage
+### Browser Usage
+
+SQLite-backed formats (Snap `.sps`/`.spb` and TouchChat `.ce`) require SQL.js to be configured in your bundler before loading files:
+
+```tsx
+import { configureBrowserSqlJs, loadAACFile, BoardViewer } from 'aac-board-viewer';
+import sqlWasmUrl from 'sql.js/dist/sql-wasm.wasm?url';
+import 'aac-board-viewer/styles';
+
+configureBrowserSqlJs({
+  locateFile: () => sqlWasmUrl,
+});
+
+function MyViewer({ file }: { file: File }) {
+  const [tree, setTree] = useState(null);
+
+  useEffect(() => {
+    async function load() {
+      const loadedTree = await loadAACFile(file);
+      setTree(loadedTree);
+    }
+    load();
+  }, [file]);
 
-> Important: `@willwade/aac-processors` is a Node-only dependency (uses native modules like `better-sqlite3`). File parsing must happen server-side. For client apps, call an API that returns the parsed tree and pass that to `BoardViewer`.
+  if (!tree) return <div>Loading...</div>;
+  return <BoardViewer tree={tree} />;
+}
+```
+
+### Server-Side / API Usage
 
 ```tsx
 import { BoardViewer } from 'aac-board-viewer';
@@ -60,6 +89,44 @@ function MyViewer({ treeData }) {
 }
 ```
 
+### Client/Server Split (Lightweight Frontend)
+
+Parse boards on the server and send the `AACTree` JSON to the browser for rendering. This keeps the frontend lightweight while the backend handles heavy formats.
+
+Server (Node/Express):
+
+```ts
+import express from 'express';
+import { loadAACFile } from 'aac-board-viewer';
+
+const app = express();
+
+app.get('/api/boards/:id', async (req, res) => {
+  const tree = await loadAACFile(`/data/boards/${req.params.id}.sps`);
+  res.json(tree);
+});
+```
+
+Client (React):
+
+```tsx
+import { BoardViewer } from 'aac-board-viewer';
+import 'aac-board-viewer/styles';
+
+function RemoteBoard({ id }: { id: string }) {
+  const [tree, setTree] = useState(null);
+
+  useEffect(() => {
+    fetch(`/api/boards/${id}`)
+      .then((res) => res.json())
+      .then(setTree);
+  }, [id]);
+
+  if (!tree) return <div>Loading...</div>;
+  return <BoardViewer tree={tree} />;
+}
+```
+
 ### With Metrics
 
 ```tsx

package/dist/index.d.mts

@@ -271,11 +271,19 @@ declare function useSentenceBuilder(): {
  * Provides utilities for loading AAC files from various sources
  * (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)
+ * Browser: Supports all formats. SQLite-backed formats (.sps, .spb, .ce) require SQL.js configuration.
+ * Node.js: Supports all formats including filesystem access and SQLite-backed formats.
  */
 
 type ProcessorOptions = Record<string, unknown> | undefined;
+type SqlJsConfig = {
+    locateFile: (file: string) => string;
+    [key: string]: unknown;
+};
+/**
+ * Configure SQL.js for browser-only SQLite-backed formats (.sps/.spb/.ce).
+ */
+declare function configureBrowserSqlJs(config: SqlJsConfig): Promise<void>;
 /**
  * Load an AAC file from a file path (Node.js only)
  *
@@ -403,4 +411,4 @@ declare function getBrowserExtensions(): string[];
  */
 declare function getNodeOnlyExtensions(): string[];
 
-export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getBrowserExtensions, getNodeOnlyExtensions, getSupportedFormats, isBrowserCompatible, loadAACFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileFromFile, useAACFileFromFileWithMetrics, useAACFileWithMetrics, useMetrics, useSentenceBuilder };
+export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, configureBrowserSqlJs, getBrowserExtensions, getNodeOnlyExtensions, getSupportedFormats, isBrowserCompatible, loadAACFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileFromFile, useAACFileFromFileWithMetrics, useAACFileWithMetrics, useMetrics, useSentenceBuilder };

package/dist/index.d.ts

@@ -271,11 +271,19 @@ declare function useSentenceBuilder(): {
  * Provides utilities for loading AAC files from various sources
  * (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)
+ * Browser: Supports all formats. SQLite-backed formats (.sps, .spb, .ce) require SQL.js configuration.
+ * Node.js: Supports all formats including filesystem access and SQLite-backed formats.
  */
 
 type ProcessorOptions = Record<string, unknown> | undefined;
+type SqlJsConfig = {
+    locateFile: (file: string) => string;
+    [key: string]: unknown;
+};
+/**
+ * Configure SQL.js for browser-only SQLite-backed formats (.sps/.spb/.ce).
+ */
+declare function configureBrowserSqlJs(config: SqlJsConfig): Promise<void>;
 /**
  * Load an AAC file from a file path (Node.js only)
  *
@@ -403,4 +411,4 @@ declare function getBrowserExtensions(): string[];
  */
 declare function getNodeOnlyExtensions(): string[];
 
-export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, getBrowserExtensions, getNodeOnlyExtensions, getSupportedFormats, isBrowserCompatible, loadAACFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileFromFile, useAACFileFromFileWithMetrics, useAACFileWithMetrics, useMetrics, useSentenceBuilder };
+export { BoardViewer, type BoardViewerProps, type ButtonMetric, type LoadAACFileResult, type MetricsOptions, calculateMetrics, configureBrowserSqlJs, getBrowserExtensions, getNodeOnlyExtensions, getSupportedFormats, isBrowserCompatible, loadAACFile, loadAACFileFromURL, loadAACFileWithMetadata, useAACFile, useAACFileFromFile, useAACFileFromFileWithMetrics, useAACFileWithMetrics, useMetrics, useSentenceBuilder };

package/dist/index.js

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   BoardViewer: () => BoardViewer,
   calculateMetrics: () => calculateMetrics,
+  configureBrowserSqlJs: () => configureBrowserSqlJs,
   getBrowserExtensions: () => getBrowserExtensions,
   getNodeOnlyExtensions: () => getNodeOnlyExtensions,
   getSupportedFormats: () => getSupportedFormats,
@@ -288,16 +289,16 @@ function BoardViewer({
     }
   };
   const getTextColor = (backgroundColor) => {
-    if (!backgroundColor) return "text-gray-900 dark:text-gray-100";
+    if (!backgroundColor) return "#111827";
     const hex = backgroundColor.replace("#", "");
     if (hex.length === 6) {
       const r = parseInt(hex.substring(0, 2), 16);
       const g = parseInt(hex.substring(2, 4), 16);
       const b = parseInt(hex.substring(4, 6), 16);
       const brightness = (r * 299 + g * 587 + b * 114) / 1e3;
-      return brightness >= 128 ? "text-gray-900" : "text-white";
+      return brightness >= 128 ? "#111827" : "#f9fafb";
     }
-    return "text-gray-900 dark:text-gray-100";
+    return "#111827";
   };
   if (!currentPage) {
     return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: `flex items-center justify-center h-96 bg-gray-100 dark:bg-gray-800 rounded-lg ${className}`, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "text-center", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", { className: "text-gray-600 dark:text-gray-400", children: "No pages available" }) }) });
@@ -370,7 +371,8 @@ function BoardViewer({
                 className: "aspect-square p-1 rounded border border-gray-200 dark:border-gray-700 transition flex flex-col items-center justify-center gap-0.5 hover:bg-gray-200 dark:hover:bg-gray-700 relative",
                 style: {
                   backgroundColor: button.style?.backgroundColor || "#f3f4f6",
-                  borderColor: button.style?.borderColor || "#e5e7eb"
+                  borderColor: button.style?.borderColor || "#e5e7eb",
+                  color: button.style?.fontColor || getTextColor(button.style?.backgroundColor)
                 },
                 title: `${button.label}
 ${button.message || ""}`,
@@ -379,9 +381,7 @@ ${button.message || ""}`,
                   /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
                     "span",
                     {
-                      className: `text-[8px] sm:text-[9px] text-center font-medium leading-tight line-clamp-2 ${getTextColor(
-                        button.style?.backgroundColor
-                      )}`,
+                      className: "text-[8px] sm:text-[9px] text-center font-medium leading-tight line-clamp-2",
                       children: button.label
                     }
                   )
@@ -495,7 +495,7 @@ ${button.message || ""}`,
                       style: {
                         backgroundColor: button.style?.backgroundColor || "#f3f4f6",
                         borderColor: button.style?.borderColor || "#e5e7eb",
-                        color: button.style?.fontColor || void 0,
+                        color: button.style?.fontColor || getTextColor(button.style?.backgroundColor),
                         gridColumn: `${colIndex + 1} / span ${colSpan}`,
                         gridRow: `${rowIndex + 1} / span ${rowSpan}`
                       },
@@ -523,9 +523,7 @@ ${button.message || ""}`,
                           /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
                             "span",
                             {
-                              className: `text-xs sm:text-sm text-center font-medium leading-tight line-clamp-3 ${getTextColor(
-                                button.style?.backgroundColor
-                              )}`,
+                              className: "text-xs sm:text-sm text-center font-medium leading-tight line-clamp-3",
                               children: button.label
                             }
                           ),
@@ -537,9 +535,7 @@ ${button.message || ""}`,
                         button.message && button.message !== button.label && !isPredictionCell && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
                           "span",
                           {
-                            className: `text-[10px] sm:text-xs text-center opacity-75 line-clamp-2 ${getTextColor(
-                              button.style?.backgroundColor
-                            )}`,
+                            className: "text-[10px] sm:text-xs text-center opacity-75 line-clamp-2",
                             children: button.message
                           }
                         )
@@ -576,14 +572,38 @@ ${button.message || ""}`,
 var import_react2 = require("react");
 
 // src/utils/loaders.ts
-var NODE_ONLY_EXTENSIONS = [".sps", ".spb", ".ce"];
-var BROWSER_EXTENSIONS = [".obf", ".obz", ".gridset", ".plist", ".grd", ".opml", ".dot"];
+var NODE_ONLY_EXTENSIONS = [".xlsx", ".xls"];
+var BROWSER_EXTENSIONS = [
+  ".obf",
+  ".obz",
+  ".gridset",
+  ".plist",
+  ".grd",
+  ".opml",
+  ".dot",
+  ".sps",
+  ".spb",
+  ".ce"
+];
 function isBrowserEnvironment() {
   return typeof window !== "undefined" && typeof window.document !== "undefined";
 }
 async function importProcessors() {
+  if (isBrowserEnvironment()) {
+    return import("@willwade/aac-processors/browser");
+  }
   return import("@willwade/aac-processors");
 }
+async function configureBrowserSqlJs(config) {
+  if (!isBrowserEnvironment()) {
+    throw new Error("configureBrowserSqlJs can only be used in a browser environment.");
+  }
+  const processors = await import("@willwade/aac-processors/browser");
+  if (typeof processors.configureSqlJs !== "function") {
+    throw new Error("configureSqlJs is not available in this build of @willwade/aac-processors.");
+  }
+  processors.configureSqlJs(config);
+}
 async function getProcessorForFile(filepath, options) {
   const { getProcessor } = await importProcessors();
   const ext = filepath.toLowerCase().split(".").pop();
@@ -601,11 +621,6 @@ async function getProcessorForFile(filepath, options) {
     throw new Error(`Unsupported file type: ${extension}`);
   }
   if (extension === ".sps" || extension === ".spb") {
-    if (isBrowserEnvironment()) {
-      throw new Error(
-        `SNAP files (.sps, .spb) require server-side processing. Please use the server API or upload a browser-compatible format. Browser supports: ${BROWSER_EXTENSIONS.join(", ")}`
-      );
-    }
     const { SnapProcessor } = await importProcessors();
     return {
       processor: options ? new SnapProcessor(null, options) : new SnapProcessor(),
@@ -659,7 +674,12 @@ async function loadAACFileFromURL(url, options) {
   return loadAACFileFromFile(blob, filename, options);
 }
 async function loadAACFileWithMetadata(input, options) {
-  const tree = await loadAACFile(input, options);
+  let tree;
+  if (typeof input === "string") {
+    tree = await loadAACFile(input, options);
+  } else {
+    tree = await loadAACFile(input, options);
+  }
   let filepath = "";
   if (typeof input === "string") {
     filepath = input;
@@ -695,8 +715,9 @@ function getFilenameFromURL(url) {
   }
 }
 async function calculateMetrics(tree, options = {}) {
-  const aacProcessors = await import("@willwade/aac-processors");
-  if (!aacProcessors.MetricsCalculator) {
+  const aacProcessors = await importProcessors();
+  const hasMetricsCalculator = typeof aacProcessors.MetricsCalculator === "function";
+  if (!hasMetricsCalculator) {
     console.warn("MetricsCalculator not available in this environment");
     return [];
   }
@@ -751,14 +772,14 @@ function getSupportedFormats() {
     {
       name: "TD Snap",
       extensions: [".sps", ".spb"],
-      description: "Tobii Dynavox Snap files",
-      browserCompatible: false
+      description: "Tobii Dynavox Snap files (requires SQL.js in browser)",
+      browserCompatible: true
     },
     {
       name: "TouchChat",
       extensions: [".ce"],
-      description: "Saltillo TouchChat files",
-      browserCompatible: false
+      description: "Saltillo TouchChat files (requires SQL.js in browser)",
+      browserCompatible: true
     },
     {
       name: "OpenBoard",
@@ -996,6 +1017,7 @@ function useSentenceBuilder() {
 0 && (module.exports = {
   BoardViewer,
   calculateMetrics,
+  configureBrowserSqlJs,
   getBrowserExtensions,
   getNodeOnlyExtensions,
   getSupportedFormats,