@willwade/aac-processors 0.0.6 → 0.0.8

package/docs/ApplePanels.md

@@ -1,309 +0,0 @@
-## Apple Panels 
-
-This is not exactly a aac tool. but  can be used as open
-
-File format:
-
-in a folder called '*.ascconfig'
-
-we have Contents/
-
-in this folder we have a file called 'Info.plist'
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>ASCConfigurationDisplayName</key>
-	<string>Default Panels</string>
-	<key>ASCConfigurationIdentifier</key>
-	<string>49F8121E-736B-4FC2-BEA8-209C3EF54ED9</string>
-	<key>ASCConfigurationProductSupportType</key>
-	<string>VirtualKeyboard</string>
-	<key>ASCConfigurationVersion</key>
-	<string>7.1</string>
-	<key>CFBundleDevelopmentRegion</key>
-	<string>en</string>
-	<key>CFBundleIdentifier</key>
-	<string>com.apple.AssistiveControl.panel.newDoc.defs</string>
-	<key>CFBundleName</key>
-	<string>Assistive Control Panels</string>
-	<key>CFBundleShortVersionString</key>
-	<string>2.0</string>
-	<key>CFBundleVersion</key>
-	<string>383</string>
-	<key>NSHumanReadableCopyright</key>
-	<string>Copyright © 2016-2024 Apple Inc. All Rights Reserved.</string>
-</dict>
-</plist>
-```
-
-then Resources/ (so Contents/Resources/)
-We have 'AssetIndex.plist' 
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict/>
-</plist>
-```
- 
- and then PanelDefinitions.plist 
-
- ``xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-	<key>Panels</key>
-	<dict>
-		<key>USER.82FC8D2C-6991-41E9-B534-78E52F101AC7</key>
-		<dict>
-			<key>DisplayOrder</key>
-			<integer>1</integer>
-			<key>GlidingLensSize</key>
-			<integer>5</integer>
-			<key>HasTransientPosition</key>
-			<false/>
-			<key>HideHome</key>
-			<false/>
-			<key>HideMinimize</key>
-			<false/>
-			<key>HidePanelAdjustments</key>
-			<false/>
-			<key>HideSwitchDock</key>
-			<false/>
-			<key>HideSwitchDockContextualButtons</key>
-			<false/>
-			<key>HideTitlebar</key>
-			<false/>
-			<key>ID</key>
-			<string>USER.82FC8D2C-6991-41E9-B534-78E52F101AC7</string>
-			<key>Name</key>
-			<string>New Panel</string>
-			<key>PanelObjects</key>
-			<array>
-				<dict>
-					<key>Actions</key>
-					<array>
-						<dict>
-							<key>ActionParam</key>
-							<dict>
-								<key>CharString</key>
-								<string>Enter this Text</string>
-								<key>isStickyKey</key>
-								<false/>
-							</dict>
-							<key>ActionRecordedOffset</key>
-							<real>0.0</real>
-							<key>ActionType</key>
-							<string>ActionPressKeyCharSequence</string>
-							<key>ID</key>
-							<string>Action.A502D835-D3B7-4253-80A3-97FE4B433EBE</string>
-						</dict>
-					</array>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayColor</key>
-					<string>0.041 0.375 0.998 1.000</string>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>enter text button</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.186CD086-698B-496F-8496-1326D141833C</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{0, 0}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>Actions</key>
-					<array>
-						<dict>
-							<key>ActionParam</key>
-							<dict>
-								<key>PanelID</key>
-								<string>ACSH.homePanel.primary.dwell</string>
-							</dict>
-							<key>ActionRecordedOffset</key>
-							<real>0.0</real>
-							<key>ActionType</key>
-							<string>ActionOpenPanel</string>
-							<key>ID</key>
-							<string>Action.6C2E1080-B39F-491A-8F8A-F60460A35732</string>
-						</dict>
-					</array>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayColor</key>
-					<string>0.161 0.781 0.197 1.000</string>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>nav button</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.8CD3879D-A328-47FB-BB7E-BB0E1973AFE8</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{105, 0}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayImageResource</key>
-					<string>DoubleClick</string>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>button with image</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.36BCE679-1DF3-422F-80BB-F37F2E8527F2</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{215, 0}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>Actions</key>
-					<array>
-						<dict>
-							<key>ActionRecordedOffset</key>
-							<real>0.0</real>
-						</dict>
-					</array>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>Current Text</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.39446632-CBCB-4D6D-945A-8F413DB611FA</string>
-					<key>LocalizedDisplayText</key>
-					<string>defaultButton.hoverText</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{325, 0}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>untitled</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.711EC127-B802-49DD-AC6A-2996D8DBCADF</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{0, 30}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>untitled</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.52D329DC-F607-4C62-9598-2C5B9F14D9B7</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{105, 30}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>untitled</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.E48FC5B5-D13C-4776-A7FB-9E8BDBAF1988</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{215, 30}, {100, 25}}</string>
-				</dict>
-				<dict>
-					<key>ButtonType</key>
-					<integer>0</integer>
-					<key>DisplayImageResourceIsTemplate</key>
-					<false/>
-					<key>DisplayImageWeight</key>
-					<string>FontWeightRegular</string>
-					<key>DisplayText</key>
-					<string>untitled</string>
-					<key>FontSize</key>
-					<real>12</real>
-					<key>ID</key>
-					<string>Button.DD4A146E-35FA-4CFE-81F7-C01AB245C955</string>
-					<key>PanelObjectType</key>
-					<string>Button</string>
-					<key>Rect</key>
-					<string>{{325, 30}, {100, 25}}</string>
-				</dict>
-			</array>
-			<key>ProductSupportType</key>
-			<string>All</string>
-			<key>Rect</key>
-			<string>{{15, 75}, {425, 55}}</string>
-			<key>ScanStyle</key>
-			<integer>0</integer>
-			<key>ShowPanelLocationString</key>
-			<string>CustomPanelList</string>
-			<key>UsesPinnedResizing</key>
-			<false/>
-		</dict>
-	</dict>
-	<key>ToolbarOrdering</key>
-	<dict>
-		<key>ToolbarIdentifiersAfterBasePanel</key>
-		<array/>
-		<key>ToolbarIdentifiersPriorToBasePanel</key>
-		<array>
-			<string>ACSH.systemPanel.dynamic.bestDwellActions</string>
-			<string>ACSH.systemPanel.dynamic.hoverText</string>
-			<string>ACSH.systemPanel.dynamic.bestSuggestions</string>
-			<string>ACSH.systemPanel.dynamic.bestFunctionKeys</string>
-		</array>
-	</dict>
-</dict>
-</plist>
-
-```

package/docs/Grid3-Styling-Guide.md

@@ -1,287 +0,0 @@
-# Grid3 Styling Guide
-
-This guide explains how to work with Grid3 styles using the AACProcessors library.
-
-## Overview
-
-Grid3 uses a sophisticated styling system with:
-- **Default styles** for common UI elements
-- **Category styles** for organizing content by semantic meaning
-- **Inline style overrides** for cell-specific customization
-- **Style inheritance** through `BasedOnStyle` references
-
-## Default Styles
-
-The library provides built-in default styles for common use cases:
-
-### Available Default Styles
-
-| Style Name | Purpose | Background | Text Color |
-|-----------|---------|-----------|-----------|
-| `Default` | General purpose cells | Light blue (#E2EDF8) | Black |
-| `Workspace` | Message/chat area | White (#FFFFFF) | Black |
-| `Auto content` | Wordlists, predictions | Light blue (#E8F4F8) | Black |
-| `Vocab cell` | Vocabulary cells | Light blue (#E8F4F8) | Black |
-| `Keyboard key` | On-screen keyboard | Light gray (#F0F0F0) | Black |
-
-### Category Styles
-
-Category styles are used for organizing content by semantic meaning:
-
-| Style Name | Color | Use Case |
-|-----------|-------|----------|
-| `Actions category style` | Blue (#4472C4) | Action verbs, commands |
-| `People category style` | Orange (#ED7D31) | Names, people |
-| `Places category style` | Gray (#A5A5A5) | Locations, places |
-| `Descriptive category style` | Green (#70AD47) | Adjectives, descriptors |
-| `Social category style` | Gold (#FFC000) | Social phrases, greetings |
-| `Questions category style` | Light blue (#5B9BD5) | Questions, interrogatives |
-| `Little words category style` | Brown (#C55A11) | Function words, particles |
-
-## Using Styles in Code
-
-### Import Style Helpers
-
-```typescript
-import {
-  DEFAULT_GRID3_STYLES,
-  CATEGORY_STYLES,
-  createDefaultStylesXml,
-  createCategoryStyle,
-  ensureAlphaChannel,
-} from 'aac-processors';
-```
-
-### Access Predefined Styles
-
-```typescript
-// Get a specific default style
-const defaultStyle = DEFAULT_GRID3_STYLES['Default'];
-console.log(defaultStyle.BackColour); // #E2EDF8FF
-
-// Get a category style
-const actionStyle = CATEGORY_STYLES['Actions category style'];
-console.log(actionStyle.BackColour); // #4472C4FF
-```
-
-### Create Custom Category Styles
-
-```typescript
-// Create a custom category style with automatic border darkening
-const customStyle = createCategoryStyle(
-  'My Category',
-  '#FF6B6B', // Background color
-  '#FFFFFF'  // Font color (optional, defaults to white)
-);
-
-// Result:
-// {
-//   BackColour: '#FF6B6BFF',
-//   TileColour: '#FF6B6BFF',
-//   BorderColour: '#CB5555FF', // Automatically darkened
-//   FontColour: '#FFFFFFFF',
-//   FontName: 'Arial',
-//   FontSize: '16'
-// }
-```
-
-### Generate Default Styles XML
-
-```typescript
-// Generate Settings0/styles.xml with all default and category styles
-const stylesXml = createDefaultStylesXml(true);
-
-// Or just default styles without categories
-const basicStylesXml = createDefaultStylesXml(false);
-```
-
-### Ensure Color Has Alpha Channel
-
-Grid3 requires colors in 8-digit ARGB format (#AARRGGBBFF):
-
-```typescript
-import { ensureAlphaChannel } from 'aac-processors';
-
-ensureAlphaChannel('#FF0000');      // Returns: #FF0000FF
-ensureAlphaChannel('#F00');         // Returns: #FF0000FF
-ensureAlphaChannel('#FF0000FF');    // Returns: #FF0000FF (unchanged)
-ensureAlphaChannel(undefined);      // Returns: #FFFFFFFF (white)
-```
-
-## Applying Styles to Cells
-
-### Using BasedOnStyle Reference
-
-In Grid3 XML, cells reference styles by name:
-
-```xml
-<Cell X="0" Y="0">
-  <Content>
-    <CaptionAndImage>
-      <Caption>Hello</Caption>
-    </CaptionAndImage>
-    <Style>
-      <BasedOnStyle>Actions category style</BasedOnStyle>
-    </Style>
-  </Content>
-</Cell>
-```
-
-### Inline Style Overrides
-
-You can override specific properties while keeping the base style:
-
-```xml
-<Cell X="1" Y="0">
-  <Content>
-    <CaptionAndImage>
-      <Caption>Custom</Caption>
-    </CaptionAndImage>
-    <Style>
-      <BasedOnStyle>Default</BasedOnStyle>
-      <BackColour>#FF0000FF</BackColour>  <!-- Override background -->
-      <FontSize>20</FontSize>             <!-- Override font size -->
-    </Style>
-  </Content>
-</Cell>
-```
-
-## Color Format
-
-Grid3 uses 8-digit ARGB hexadecimal format: `#AARRGGBBFF`
-
-- **AA**: Alpha channel (FF = fully opaque, 00 = fully transparent)
-- **RR**: Red component (00-FF)
-- **GG**: Green component (00-FF)
-- **BB**: Blue component (00-FF)
-- **FF**: Always FF for Grid3 (fully opaque)
-
-### Examples
-
-| Color | Hex Code | Description |
-|-------|----------|-------------|
-| White | #FFFFFFFF | Fully opaque white |
-| Black | #000000FF | Fully opaque black |
-| Red | #FF0000FF | Fully opaque red |
-| Blue | #0000FFFF | Fully opaque blue |
-| Green | #00FF00FF | Fully opaque green |
-
-## Style Inheritance
-
-Grid3 uses a cascading style system:
-
-1. **Theme** provides base properties (Modern, Kids/Bubble, Flat/Blocky, Explorer)
-2. **Built-in style** defines category defaults
-3. **Cell-specific overrides** apply on top
-
-```xml
-<!-- Example: Override just the background color -->
-<Style>
-  <BasedOnStyle>Actions category style</BasedOnStyle>
-  <BackColour>#FF0000FF</BackColour>  <!-- Override just this property -->
-</Style>
-```
-
-## Creating Gridsets with Styles
-
-### Using GridsetProcessor
-
-```typescript
-import { GridsetProcessor, AACTree, AACPage, AACButton } from 'aac-processors';
-
-const processor = new GridsetProcessor();
-const tree = new AACTree();
-
-// Create a page with styling
-const page = new AACPage({
-  id: 'main-page',
-  name: 'Main Board',
-  grid: [],
-  buttons: [],
-  parentId: null,
-  style: {
-    backgroundColor: '#f0f8ff',
-    fontFamily: 'Arial',
-    fontSize: 16,
-  },
-});
-
-// Create styled buttons
-const button = new AACButton({
-  id: 'btn-1',
-  label: 'Hello',
-  message: 'Hello, how are you?',
-  style: {
-    backgroundColor: '#4472C4',  // Blue (Actions category)
-    fontColor: '#FFFFFF',
-    fontSize: 18,
-    fontFamily: 'Arial',
-  },
-});
-
-page.addButton(button);
-tree.addPage(page);
-
-// Save with styles
-processor.saveFromTree(tree, 'output.gridset');
-```
-
-### Using Grid-Generator
-
-```typescript
-import { generateGridset } from '@willwade/grid-generator';
-
-const template = {
-  aacsystem: 'Grid3',
-  homeGrid: {
-    enabled: true,
-    name: 'Home',
-    title: 'Categories',
-  },
-  wordlists: [
-    {
-      name: 'Greetings',
-      items: ['Hello', 'Hi', 'Hey'],
-      partOfSpeech: 'Interjection',
-    },
-  ],
-};
-
-const gridset = generateGridset(template);
-```
-
-## Best Practices
-
-1. **Use category styles** for semantic organization - helps with accessibility and consistency
-2. **Maintain contrast** - ensure text color has sufficient contrast with background
-3. **Use consistent fonts** - stick to standard fonts like Arial, Verdana, or Roboto
-4. **Test in Grid3** - always verify styling in the actual Grid3 application
-5. **Document custom styles** - if creating custom category styles, document their purpose
-6. **Use inline overrides sparingly** - prefer creating new styles for significant variations
-
-## Troubleshooting
-
-### Styles Not Appearing
-
-- Verify `Settings0/styles.xml` exists in the gridset
-- Check that style names in cells match exactly (case-sensitive)
-- Ensure colors are in 8-digit ARGB format
-
-### Colors Look Wrong
-
-- Verify alpha channel is FF (fully opaque)
-- Check RGB values are correct
-- Test in Grid3 to see actual rendering
-
-### Performance Issues
-
-- Avoid creating too many unique styles (consolidate similar styles)
-- Use style references instead of inline overrides when possible
-- Keep font sizes reasonable (12-24 points typical)
-
-## See Also
-
-- [Grid3 XML Format Documentation](./Grid3-XML-Format.md)
-- [Wordlist Helpers Guide](./Grid3-Wordlist-Helpers.md)
-- [AACProcessors API Reference](./API-Reference.md)
-