@willwade/aac-processors 0.1.0 → 0.1.2

package/docs/PAGESET_GETTING_STARTED.md

@@ -0,0 +1,185 @@
+# AAC Pageset Quickstart (Node + Browser)
+
+This guide shows two simple ways to generate or convert AAC pagesets using `aac-processors`:
+
+- Node.js: full conversion between formats (read + write)
+- Browser: generate or export to OBF/OBZ in-memory (downloadable)
+
+If you need lossless conversion in the browser, use a Node/worker service for the save step (file I/O is required for most formats).
+
+## Node.js: Convert and Generate Pagesets
+
+### Install
+
+```bash
+npm install aac-processors
+```
+
+### Convert a Gridset to OBF
+
+```ts
+import { getProcessor, ObfProcessor } from 'aac-processors';
+
+async function convertGridsetToObf() {
+  const sourcePath = './input/example.gridset';
+  const targetPath = './output/example.obf';
+
+  const sourceProcessor = getProcessor(sourcePath); // GridsetProcessor
+  const tree = await sourceProcessor.loadIntoTree(sourcePath);
+
+  const obf = new ObfProcessor();
+  await obf.saveFromTree(tree, targetPath);
+
+  console.log('Saved:', targetPath);
+}
+
+convertGridsetToObf().catch(console.error);
+```
+
+### Generate a Simple Pageset and Save as OBZ
+
+```ts
+import { AACTree, AACPage, AACButton, ObfProcessor } from 'aac-processors';
+
+async function generateObz() {
+  const tree = new AACTree();
+  tree.metadata = { name: 'Starter Demo', locale: 'en' };
+
+  const hello = new AACButton({ id: 'hello', label: 'Hello', message: 'Hello' });
+  const thanks = new AACButton({ id: 'thanks', label: 'Thanks', message: 'Thank you' });
+
+  const home = new AACPage({
+    id: 'home',
+    name: 'Home',
+    buttons: [hello, thanks],
+    grid: [[hello, thanks]],
+  });
+
+  tree.addPage(home);
+  tree.rootId = 'home';
+
+  const obf = new ObfProcessor();
+  await obf.saveFromTree(tree, './output/starter.obz');
+
+  console.log('Saved: ./output/starter.obz');
+}
+
+generateObz().catch(console.error);
+```
+
+## Browser: Generate or Convert to OBF/OBZ
+
+In the browser you can still parse files and build an `AACTree`, but most processors cannot write to disk (no `fs`).
+The example below generates an `AACTree`, converts it to OBF JSON in-memory, and downloads it.
+
+If you need full conversions in a browser app, do the save step in Node (server or worker).
+
+### Generate a Pageset and Download as OBF
+
+```ts
+import { AACTree, AACPage, AACButton, ObfProcessor } from 'aac-processors';
+
+function downloadBlob(data: BlobPart, filename: string, type: string) {
+  const blob = new Blob([data], { type });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+function buildSampleTree() {
+  const tree = new AACTree();
+  tree.metadata = { name: 'Browser Demo', locale: 'en' };
+
+  const hello = new AACButton({ id: 'hello', label: 'Hello', message: 'Hello' });
+  const yes = new AACButton({ id: 'yes', label: 'Yes', message: 'Yes' });
+
+  const home = new AACPage({
+    id: 'home',
+    name: 'Home',
+    buttons: [hello, yes],
+    grid: [[hello, yes]],
+  });
+
+  tree.addPage(home);
+  tree.rootId = 'home';
+  return tree;
+}
+
+async function exportObf(tree: AACTree) {
+  // This mirrors the browser demo approach: create OBF JSON and download.
+  // ObfProcessor.saveFromTree writes to disk, so we build a board in-memory.
+  const obf = new ObfProcessor() as ObfProcessor & {
+    createObfBoardFromPage?: (page: AACPage, fallbackName: string, metadata?: AACTree['metadata']) => any;
+  };
+
+  const rootPage = tree.rootId ? tree.getPage(tree.rootId) : Object.values(tree.pages)[0];
+  const board = obf.createObfBoardFromPage
+    ? obf.createObfBoardFromPage(rootPage!, 'Board', tree.metadata)
+    : {
+        format: 'open-board-0.1',
+        id: rootPage?.id ?? 'board',
+        name: rootPage?.name ?? 'Board',
+        locale: tree.metadata?.locale || 'en',
+        grid: { rows: 1, columns: rootPage?.buttons.length ?? 0, order: [] },
+        buttons: (rootPage?.buttons || []).map((button) => ({
+          id: button.id,
+          label: button.label,
+          vocalization: button.message || button.label,
+        })),
+      };
+
+  const json = JSON.stringify(board, null, 2);
+  downloadBlob(json, 'browser-demo.obf', 'application/json');
+}
+
+const tree = buildSampleTree();
+exportObf(tree);
+```
+
+### Convert an Uploaded Pageset to OBZ (Browser)
+
+This uses the same idea as the Vite demo: parse any supported file into a tree,
+then export OBF/OBZ in-memory and download.
+
+```ts
+import { getProcessor, ObfProcessor, type AACTree, type AACPage } from 'aac-processors';
+import JSZip from 'jszip';
+
+async function convertToObz(file: File) {
+  const extension = '.' + file.name.split('.').pop();
+  const processor = getProcessor(extension);
+  const buffer = await file.arrayBuffer();
+  const tree = await processor.loadIntoTree(buffer);
+
+  const obf = new ObfProcessor() as ObfProcessor & {
+    createObfBoardFromPage?: (page: AACPage, fallbackName: string, metadata?: AACTree['metadata']) => any;
+  };
+
+  const zip = new JSZip();
+  Object.values(tree.pages).forEach((page) => {
+    const board = obf.createObfBoardFromPage
+      ? obf.createObfBoardFromPage(page, 'Board', tree.metadata)
+      : { format: 'open-board-0.1', id: page.id, name: page.name, grid: { rows: 0, columns: 0, order: [] }, buttons: [] };
+    zip.file(`${page.id}.obf`, JSON.stringify(board, null, 2));
+  });
+
+  const data = await zip.generateAsync({ type: 'uint8array' });
+  const blob = new Blob([data], { type: 'application/zip' });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = 'converted.obz';
+  a.click();
+  URL.revokeObjectURL(url);
+}
+```
+
+## Tips
+
+- Use `loadIntoTree()` to normalize different AAC formats into one structure.
+- In Node, `saveFromTree()` lets you write to OBF, OBZ, Gridset, etc.
+- In the browser, build the output in memory and offer it for download.
+- For full-fidelity conversions in the browser, use a server-side endpoint to save files.

package/examples/vitedemo/QUICKSTART.md

@@ -40,6 +40,7 @@ The `test-files/` folder contains example AAC files you can use:
 - **Navigation**: Click NAVIGATE buttons to jump between pages
 - **Stats**: See page/button/text counts and load time
 - **Logs**: Watch the processing log in real-time
+- **Pageset Lab**: Open the "Create & Convert" tab to generate a sample pageset or convert an upload to OBF/OBZ
 
 ## 🛠️ Development
 

package/examples/vitedemo/index.html

@@ -63,6 +63,39 @@
             border-bottom: 2px solid #667eea;
         }
 
+        .tab-header {
+            display: flex;
+            gap: 8px;
+            margin-bottom: 15px;
+        }
+
+        .tab-btn {
+            flex: 1;
+            border: 1px solid #d6daf5;
+            background: #f7f8ff;
+            color: #3d4bb8;
+            padding: 8px 12px;
+            border-radius: 8px;
+            font-size: 13px;
+            font-weight: 600;
+            cursor: pointer;
+            transition: all 0.2s;
+        }
+
+        .tab-btn.active {
+            background: #667eea;
+            color: #fff;
+            border-color: #667eea;
+        }
+
+        .tab-content {
+            display: none;
+        }
+
+        .tab-content.active {
+            display: block;
+        }
+
         .upload-area {
             border: 2px dashed #ccc;
             border-radius: 8px;
@@ -290,6 +323,83 @@
             font-size: 13px;
         }
 
+        .demo-section {
+            background: #f8f9ff;
+            border-radius: 10px;
+            padding: 15px;
+            border: 1px solid #e4e7ff;
+            margin-bottom: 15px;
+        }
+
+        .section-title {
+            font-size: 14px;
+            font-weight: 700;
+            color: #3942a3;
+            margin-bottom: 10px;
+        }
+
+        .field {
+            display: flex;
+            flex-direction: column;
+            gap: 6px;
+            margin-bottom: 10px;
+            font-size: 12px;
+            color: #4d4d4d;
+        }
+
+        .field select,
+        .field input {
+            border: 1px solid #d7d9f5;
+            border-radius: 6px;
+            padding: 8px 10px;
+            font-size: 13px;
+        }
+
+        .action-row {
+            display: flex;
+            gap: 10px;
+        }
+
+        .action-row .btn {
+            margin-bottom: 0;
+        }
+
+        .hint {
+            font-size: 12px;
+            color: #667;
+            margin-top: 8px;
+        }
+
+        .status-pill {
+            margin-top: 10px;
+            font-size: 12px;
+            padding: 8px 10px;
+            border-radius: 8px;
+            background: #eef0ff;
+            color: #4a4a8a;
+        }
+
+        .status-pill.success {
+            background: #e0f4e7;
+            color: #256d3b;
+        }
+
+        .status-pill.warn {
+            background: #fff4d6;
+            color: #7a5a00;
+        }
+
+        .code-preview {
+            background: #0f172a;
+            color: #d7e3ff;
+            padding: 12px;
+            border-radius: 8px;
+            font-size: 12px;
+            max-height: 220px;
+            overflow: auto;
+            white-space: pre-wrap;
+        }
+
         @media (max-width: 1024px) {
             .main-grid {
                 grid-template-columns: 1fr;
@@ -361,11 +471,56 @@
 
             <!-- Right Panel: Results -->
             <div class="panel results-panel">
-                <div class="panel-title">📊 File Contents</div>
-                <div id="results">
-                    <p style="color: #999; text-align: center; padding: 40px;">
-                        Load a file to see its contents here
-                    </p>
+                <div class="panel-title">📊 AAC Pageset Lab</div>
+                <div class="tab-header">
+                    <button class="tab-btn active" data-tab="inspectTab">Inspect</button>
+                    <button class="tab-btn" data-tab="pagesetTab">Create & Convert</button>
+                </div>
+                <div class="tab-content active" id="inspectTab">
+                    <div id="results">
+                        <p style="color: #999; text-align: center; padding: 40px;">
+                            Load a file to see its contents here
+                        </p>
+                    </div>
+                </div>
+                <div class="tab-content" id="pagesetTab">
+                    <div class="demo-section">
+                        <div class="section-title">✨ Create a Sample Pageset</div>
+                        <div class="field">
+                            <label for="templateSelect">Template</label>
+                            <select id="templateSelect">
+                                <option value="starter">Starter 2x2 + Feelings</option>
+                                <option value="home">Home & Core 3x3</option>
+                            </select>
+                        </div>
+                        <div class="field">
+                            <label for="formatSelect">Output format</label>
+                            <select id="formatSelect">
+                                <option value="obf">OBF (.obf)</option>
+                                <option value="obz">OBZ (.obz)</option>
+                            </select>
+                        </div>
+                        <div class="action-row">
+                            <button class="btn" id="createPagesetBtn">Generate & Download</button>
+                            <button class="btn btn-secondary" id="previewPagesetBtn">Preview in Viewer</button>
+                        </div>
+                        <div class="hint">Creates a demo AACTree, then exports to OBF/OBZ.</div>
+                    </div>
+
+                    <div class="demo-section">
+                        <div class="section-title">🔁 Convert Loaded Pageset</div>
+                        <div class="action-row">
+                            <button class="btn" id="convertToObfBtn" disabled>Download .obf</button>
+                            <button class="btn btn-secondary" id="convertToObzBtn" disabled>Download .obz</button>
+                        </div>
+                        <div class="hint">Upload and process a file first, then export it in another format.</div>
+                        <div class="status-pill" id="conversionStatus">No pageset loaded yet.</div>
+                    </div>
+
+                    <div class="demo-section">
+                        <div class="section-title">📄 Export Preview</div>
+                        <pre class="code-preview" id="pagesetOutput">Generate or convert a pageset to preview the output JSON.</pre>
+                    </div>
                 </div>
             </div>
         </div>