wyreframe 0.6.0 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Wyreframe
 
-> A library that converts ASCII wireframes into working HTML/UI
+> A library that converts ASCII wireframes into working HTML/UI with scene management
 
 [![npm version](https://img.shields.io/npm/v/wyreframe.svg)](https://www.npmjs.com/package/wyreframe)
 [![npm downloads](https://img.shields.io/npm/dm/wyreframe.svg)](https://www.npmjs.com/package/wyreframe)
@@ -19,6 +19,15 @@
 +---------------------------+
 ```
 
+## Features
+
+- **ASCII to HTML**: Convert simple ASCII art into interactive UI elements
+- **Scene Management**: Multi-screen prototypes with transitions (fade, slide, zoom)
+- **Interaction DSL**: Define button clicks, navigation, and form validation
+- **Device Preview**: Responsive previews for mobile, tablet, and desktop
+- **Auto-Fix**: Automatically correct common wireframe formatting issues
+- **TypeScript/ReScript**: Full type safety with both language support
+
 ## Installation
 
 ```bash
@@ -56,121 +65,284 @@ if (result.success) {
 }
 ```
 
-### ReScript
+## Syntax Reference
 
-```rescript
-let ui = `
-@scene: login
+### UI Elements
 
-+---------------------------+
-|       'WYREFRAME'         |
-|  +---------------------+  |
-|  | #email              |  |
-|  +---------------------+  |
-|       [ Login ]           |
-+---------------------------+
+| Syntax | Description | HTML Output |
+|--------|-------------|-------------|
+| `+---+` | Box/Container | `<div>` |
+| `[ Text ]` | Button | `<button>` |
+| `#id` | Input field | `<input>` |
+| `"text"` | Link | `<a>` |
+| `'text'` | Emphasis text | Title, Heading |
+| `[x]` / `[ ]` | Checkbox | `<input type="checkbox">` |
+| `---` | Divider | `<hr>` |
+
+### Scene Directives
+
+```yaml
+@scene: sceneId        # Scene identifier (required)
+@title: Page Title     # Optional page title
+@device: mobile        # Device type for sizing
+@transition: fade      # Default transition effect
+```
 
+### Device Types
+
+| Device | Dimensions | Description |
+|--------|------------|-------------|
+| `desktop` | 1440x900 | Desktop monitor |
+| `laptop` | 1280x800 | Laptop screen |
+| `tablet` | 768x1024 | Tablet portrait |
+| `tablet-landscape` | 1024x768 | Tablet landscape |
+| `mobile` | 375x812 | iPhone X ratio |
+| `mobile-landscape` | 812x375 | Mobile landscape |
+
+### Interactions
+
+```yaml
 #email:
-  placeholder: "Enter your email"
+  placeholder: "Email"
 
 [Login]:
+  variant: primary
   @click -> goto(dashboard, slide-left)
-`
 
-switch Renderer.createUI(ui, None) {
-| Ok({root, sceneManager, _}) => {
-    // Append root to DOM
-    sceneManager.goto("login")
-  }
-| Error(errors) => Console.error(errors)
-}
+"Forgot Password":
+  @click -> goto(reset)
 ```
 
-## Syntax Summary
+**Actions:**
 
-| Syntax | Description | Example |
-|------|------|------|
-| `+---+` | Box/Container | `<div>` |
-| `[ Text ]` | Button | `<button>` |
-| `#id` | Input field | `<input>` |
-| `"text"` | Link | `<a>` |
-| `'text'` | Emphasis text | Title, Heading |
-| `[x]` / `[ ]` | Checkbox | `<input type="checkbox">` |
-| `---` | Scene separator | Multi-scene |
+| Action | Description | Example |
+|--------|-------------|---------|
+| `goto(scene, transition?)` | Navigate to scene | `@click -> goto(home, fade)` |
+| `back()` | Navigate back | `@click -> back()` |
+| `forward()` | Navigate forward | `@click -> forward()` |
+| `validate(fields)` | Validate inputs | `@submit -> validate(email, password)` |
+| `call(fn, args)` | Custom function | `@click -> call(submit, form)` |
+
+**Transitions:** `fade`, `slide-left`, `slide-right`, `zoom`
+
+**Variants:** `primary`, `secondary`, `ghost`
 
 ## API
 
 ### JavaScript/TypeScript
 
 ```javascript
-import { parse, render, createUI, createUIOrThrow } from 'wyreframe';
+import {
+  parse,
+  parseOrThrow,
+  render,
+  createUI,
+  createUIOrThrow,
+  fix,
+  fixOnly
+} from 'wyreframe';
+
+// Parse only - returns { success, ast, warnings } or { success: false, errors }
+const parseResult = parse(text);
+
+// Parse and throw on error
+const ast = parseOrThrow(text);
+
+// Render AST to DOM (pass ast, not parseResult!)
+if (parseResult.success) {
+  const { root, sceneManager } = render(parseResult.ast, options);
+}
 
-// Parse only - returns { success, ast } or { success, errors }
-const result = parse(text);
+// Parse + Render combined (recommended)
+const result = createUI(text, options);
 
-// Render only - IMPORTANT: pass result.ast, not result directly!
-if (result.success) {
-  const { root, sceneManager } = render(result.ast);
-}
+// Parse + Render, throw on error
+const { root, sceneManager } = createUIOrThrow(text, options);
 
-// Parse + Render (recommended) - handles the wrapper automatically
-const result = createUI(text);
+// Auto-fix wireframe formatting issues
+const fixResult = fix(text);
+if (fixResult.success) {
+  console.log('Fixed:', fixResult.fixed.length, 'issues');
+  const cleanText = fixResult.text;
+}
 
-// Throw on error
-const { root, sceneManager } = createUIOrThrow(text);
+// Fix and return text only
+const fixedText = fixOnly(text);
 ```
 
-> **Note:** `parse()` returns a wrapper object `{ success: true, ast: AST }` or `{ success: false, errors: [] }`.
-> When using `render()` directly, make sure to pass `result.ast`, not the result object itself.
+### Render Options
 
-### ReScript
+```typescript
+const options = {
+  // Additional CSS class for container
+  containerClass: 'my-app',
 
-```rescript
-// Parse only
-let result = Parser.parse(text)
+  // Inject default styles (default: true)
+  injectStyles: true,
+
+  // Override device type for all scenes
+  device: 'mobile',
 
-// Render only
-let {root, sceneManager} = Renderer.render(ast, None)
+  // Scene change callback
+  onSceneChange: (fromScene, toScene) => {
+    console.log(`Navigated from ${fromScene} to ${toScene}`);
+  },
 
-// Parse + Render (recommended)
-let result = Renderer.createUI(text, None)
+  // Dead-end click callback (buttons/links without navigation)
+  onDeadEndClick: (info) => {
+    console.log(`Clicked: ${info.elementText} in scene ${info.sceneId}`);
+    // Show modal, custom logic, etc.
+  }
+};
 
-// Throw on error
-let {root, sceneManager, ast} = Renderer.createUIOrThrow(text, None)
+const result = createUI(text, options);
 ```
 
 ### SceneManager
 
 ```javascript
-sceneManager.goto('dashboard');           // Navigate to scene
-sceneManager.getCurrentScene();           // Get current scene
-sceneManager.getSceneIds();               // Get all scene IDs
+const { sceneManager } = result;
+
+sceneManager.goto('dashboard');        // Navigate to scene
+sceneManager.goto('home', 'fade');     // Navigate with transition
+sceneManager.back();                   // Go back in history
+sceneManager.forward();                // Go forward in history
+sceneManager.getCurrentScene();        // Get current scene ID
+sceneManager.getSceneIds();            // Get all scene IDs
 ```
 
+### ReScript
+
 ```rescript
-sceneManager.goto("dashboard")            // Navigate to scene
-sceneManager.getCurrentScene()            // Get current scene (option<string>)
-sceneManager.getSceneIds()                // Get all scene IDs (array<string>)
+// Parse + Render
+switch Renderer.createUI(ui, None) {
+| Ok({root, sceneManager, _}) =>
+    sceneManager.goto("login")
+| Error(errors) => Console.error(errors)
+}
+
+// With options
+let options = {
+  device: Some(#mobile),
+  onSceneChange: Some((from, to) => Console.log2(from, to)),
+  onDeadEndClick: None,
+  containerClass: None,
+  injectStyles: None,
+}
+switch Renderer.createUI(ui, Some(options)) {
+| Ok({root, sceneManager, _}) => ...
+| Error(errors) => ...
+}
 ```
 
-## Interactions
+## Auto-Fix
+
+Wyreframe can automatically fix common formatting issues:
+
+```javascript
+import { fix, fixOnly } from 'wyreframe';
+
+const messyWireframe = `
++----------+
+| Button  |    <- Misaligned pipe
++---------+    <- Width mismatch
+`;
+
+const result = fix(messyWireframe);
+if (result.success) {
+  console.log('Fixed issues:', result.fixed);
+  console.log('Remaining issues:', result.remaining);
+  console.log('Clean wireframe:', result.text);
+}
+
+// Or just get the fixed text
+const cleanText = fixOnly(messyWireframe);
+```
+
+**Fixable Issues:**
+- Misaligned pipes (|)
+- Mismatched border widths
+- Tabs instead of spaces
+- Unclosed brackets
+
+## Multi-Scene Example
+
+```javascript
+const app = `
+@scene: login
+@device: mobile
+
++---------------------------+
+|         'Login'           |
+|  +---------------------+  |
+|  | #email              |  |
+|  +---------------------+  |
+|  +---------------------+  |
+|  | #password           |  |
+|  +---------------------+  |
+|       [ Sign In ]         |
+|                           |
+|    "Create Account"       |
++---------------------------+
+
+---
+
+@scene: signup
+@device: mobile
+
++---------------------------+
+|       'Sign Up'           |
+|  +---------------------+  |
+|  | #name               |  |
+|  +---------------------+  |
+|  +---------------------+  |
+|  | #email              |  |
+|  +---------------------+  |
+|       [ Register ]        |
+|                           |
+|    "Back to Login"        |
++---------------------------+
 
-```yaml
 #email:
   placeholder: "Email"
+#password:
+  placeholder: "Password"
+#name:
+  placeholder: "Full Name"
 
-[Login]:
+[Sign In]:
   variant: primary
-  @click -> goto(dashboard, slide-left)
-```
+  @click -> goto(signup, slide-left)
+
+"Create Account":
+  @click -> goto(signup, slide-left)
+
+[Register]:
+  variant: primary
+  @click -> goto(login, slide-right)
+
+"Back to Login":
+  @click -> goto(login, slide-right)
+`;
+
+const result = createUI(app, {
+  onSceneChange: (from, to) => {
+    console.log(`Scene: ${from} -> ${to}`);
+  }
+});
 
-**Transition effects:** `fade`, `slide-left`, `slide-right`, `zoom`
+if (result.success) {
+  document.getElementById('app').appendChild(result.root);
+  result.sceneManager.goto('login');
+}
+```
 
 ## Documentation
 
 - [API Reference](docs/api.md)
-- [Developer Guide](docs/developer-guide.md)
+- [Type Definitions](docs/types.md)
 - [Examples](docs/examples.md)
+- [Developer Guide](docs/developer-guide.md)
 - [Testing Guide](docs/testing.md)
 - [Live Demo](examples/index.html)
 
@@ -179,10 +351,24 @@ sceneManager.getSceneIds()                // Get all scene IDs (array<string>)
 ```bash
 npm install
 npm run res:build    # ReScript build
+npm run ts:build     # TypeScript build
+npm run build        # Full build
 npm run dev          # Dev server (http://localhost:3000/examples)
 npm test             # Run tests
+npm run test:watch   # Test watch mode
+npm run test:coverage # Generate coverage report
 ```
 
+## Architecture
+
+Wyreframe uses a 3-stage parsing pipeline:
+
+1. **Grid Scanner**: Converts ASCII text to 2D character grid
+2. **Shape Detector**: Identifies boxes, nesting, and hierarchy
+3. **Semantic Parser**: Recognizes UI elements via pluggable parsers
+
+The renderer generates pure DOM elements with CSS-based scene visibility and transitions.
+
 ## License
 
 GPL-3.0 License - see [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyreframe",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "ASCII wireframe + interaction DSL to HTML converter with scene transitions",
   "author": "wickedev",
   "repository": {

package/src/parser/Semantic/SemanticParser.mjs

@@ -595,7 +595,7 @@ function segmentToElement(segment, basePosition, baseCol, bounds) {
       let text$1 = segment._0;
       let actualCol$1 = baseCol + segment._1 | 0;
       let position$1 = Types.Position.make(basePosition.row, actualCol$1);
-      let id = text$1.trim().toLowerCase().replace(/\\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+      let id = text$1.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
       let buttonContent = "[ " + text$1 + " ]";
       let align$1 = AlignmentCalc.calculateWithStrategy(buttonContent, position$1, bounds, "RespectPosition");
       return {
@@ -610,7 +610,7 @@ function segmentToElement(segment, basePosition, baseCol, bounds) {
       let text$2 = segment._0;
       let actualCol$2 = baseCol + segment._1 | 0;
       let position$2 = Types.Position.make(basePosition.row, actualCol$2);
-      let id$1 = text$2.trim().toLowerCase().replace(/\\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+      let id$1 = text$2.trim().toLowerCase().replace(/\s+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
       let align$2 = AlignmentCalc.calculateWithStrategy(text$2, position$2, bounds, "RespectPosition");
       return {
         TAG: "Link",

package/src/parser/Semantic/SemanticParser.res

@@ -992,13 +992,14 @@ let segmentToElement = (
       let position = Position.make(basePosition.row, actualCol)
 
       // Create button ID from text (slugified)
+      // Use String.replaceRegExp (modern API) to avoid escaping issues with %re
       let id = text
         ->String.trim
         ->String.toLowerCase
-        ->Js.String2.replaceByRe(%re("/\\s+/g"), "-")
-        ->Js.String2.replaceByRe(%re("/[^a-z0-9-]/g"), "")
-        ->Js.String2.replaceByRe(%re("/-+/g"), "-")
-        ->Js.String2.replaceByRe(%re("/^-+|-+$/g"), "")
+        ->String.replaceRegExp(%re("/\s+/g"), "-")
+        ->String.replaceRegExp(%re("/[^a-z0-9-]/g"), "")
+        ->String.replaceRegExp(%re("/-+/g"), "-")
+        ->String.replaceRegExp(%re("/^-+|-+$/g"), "")
 
       // Use "[ text ]" format (with spaces) to match visual button width for alignment
       let buttonContent = "[ " ++ text ++ " ]"
@@ -1022,13 +1023,14 @@ let segmentToElement = (
       let position = Position.make(basePosition.row, actualCol)
 
       // Use the same slugify logic as LinkParser for consistent ID generation
+      // Use String.replaceRegExp (modern API) to avoid escaping issues with %re
       let id = text
         ->String.trim
         ->String.toLowerCase
-        ->Js.String2.replaceByRe(%re("/\\s+/g"), "-")
-        ->Js.String2.replaceByRe(%re("/[^a-z0-9-]/g"), "")
-        ->Js.String2.replaceByRe(%re("/-+/g"), "-")
-        ->Js.String2.replaceByRe(%re("/^-+|-+$/g"), "")
+        ->String.replaceRegExp(%re("/\s+/g"), "-")
+        ->String.replaceRegExp(%re("/[^a-z0-9-]/g"), "")
+        ->String.replaceRegExp(%re("/-+/g"), "-")
+        ->String.replaceRegExp(%re("/^-+|-+$/g"), "")
 
       let align = AlignmentCalc.calculateWithStrategy(
         text,