wyreframe 0.1.0 → 0.1.5

package/README.md

@@ -3,7 +3,11 @@
 > A library that converts ASCII wireframes into working HTML/UI
 
 [![npm version](https://img.shields.io/npm/v/wyreframe.svg)](https://www.npmjs.com/package/wyreframe)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm downloads](https://img.shields.io/npm/dm/wyreframe.svg)](https://www.npmjs.com/package/wyreframe)
+[![codecov](https://codecov.io/gh/wickedev/wyreframe/branch/main/graph/badge.svg)](https://codecov.io/gh/wickedev/wyreframe)
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![ReScript](https://img.shields.io/badge/ReScript-12-e6484f.svg)](https://rescript-lang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg)](https://nodejs.org/)
 
 ```
 +---------------------------+
@@ -52,6 +56,36 @@ if (result.success) {
 }
 ```
 
+### ReScript
+
+```rescript
+let ui = `
+@scene: login
+
++---------------------------+
+|       'WYREFRAME'         |
+|  +---------------------+  |
+|  | #email              |  |
+|  +---------------------+  |
+|       [ Login ]           |
++---------------------------+
+
+#email:
+  placeholder: "Enter your email"
+
+[Login]:
+  @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)
+}
+```
+
 ## Syntax Summary
 
 | Syntax | Description | Example |
@@ -66,6 +100,8 @@ if (result.success) {
 
 ## API
 
+### JavaScript/TypeScript
+
 ```javascript
 import { parse, render, createUI, createUIOrThrow } from 'wyreframe';
 
@@ -82,6 +118,22 @@ const result = createUI(text);
 const { root, sceneManager } = createUIOrThrow(text);
 ```
 
+### ReScript
+
+```rescript
+// Parse only
+let result = Parser.parse(text)
+
+// Render only
+let {root, sceneManager} = Renderer.render(ast, None)
+
+// Parse + Render (recommended)
+let result = Renderer.createUI(text, None)
+
+// Throw on error
+let {root, sceneManager, ast} = Renderer.createUIOrThrow(text, None)
+```
+
 ### SceneManager
 
 ```javascript
@@ -90,6 +142,12 @@ sceneManager.getCurrentScene();           // Get current scene
 sceneManager.getSceneIds();               // Get all scene IDs
 ```
 
+```rescript
+sceneManager.goto("dashboard")            // Navigate to scene
+sceneManager.getCurrentScene()            // Get current scene (option<string>)
+sceneManager.getSceneIds()                // Get all scene IDs (array<string>)
+```
+
 ## Interactions
 
 ```yaml
@@ -105,9 +163,11 @@ sceneManager.getSceneIds();               // Get all scene IDs
 
 ## Documentation
 
-- [Parser Architecture](docs/PARSER_ARCHITECTURE.md)
-- [Testing Guide](docs/TESTING.md)
-- [Examples](examples/index.html)
+- [API Reference](docs/api.md)
+- [Developer Guide](docs/developer-guide.md)
+- [Examples](docs/examples.md)
+- [Testing Guide](docs/testing.md)
+- [Live Demo](examples/index.html)
 
 ## Development
 
@@ -120,4 +180,4 @@ npm test             # Run tests
 
 ## License
 
-MIT License
+GPL-3.0 License - see [LICENSE](LICENSE) for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyreframe",
-  "version": "0.1.0",
+  "version": "0.1.5",
   "description": "ASCII wireframe + interaction DSL to HTML converter with scene transitions",
   "author": "wickedev",
   "repository": {
@@ -13,8 +13,8 @@
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "src/parser",
-    "src/renderer",
+    "src",
+    "!src/**/__tests__",
     "README.md"
   ],
   "exports": {
@@ -50,14 +50,15 @@
     "html",
     "prototype"
   ],
-  "license": "MIT",
+  "license": "GPL-3.0",
   "dependencies": {
     "@rescript/core": "^1.6.1",
-    "rescript": "12",
-    "vitest": "^3.2.4"
+    "rescript": "12"
   },
   "devDependencies": {
+    "@vitest/coverage-v8": "^3.1.4",
     "rescript-vitest": "^2.1.1",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^3.1.4"
   }
 }

package/src/index.ts

@@ -0,0 +1,425 @@
+/**
+ * Wyreframe - ASCII Wireframe to HTML/UI Converter
+ *
+ * This module provides a TypeScript-friendly API wrapper
+ * around the ReScript parser implementation.
+ */
+
+// Note: These imports use relative paths that work when compiled to dist/
+// The ReScript .mjs files remain in src/parser/, so dist/index.js imports ../src/parser/
+// @ts-ignore - ReScript generated module
+import * as Parser from '../src/parser/Parser.mjs';
+// @ts-ignore - ReScript generated module
+import * as Renderer from '../src/renderer/Renderer.mjs';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+/** Device type for responsive design */
+export type DeviceType =
+  | 'desktop'
+  | 'laptop'
+  | 'tablet'
+  | 'tablet-landscape'
+  | 'mobile'
+  | 'mobile-landscape';
+
+/** Transition effect for scene changes */
+export type TransitionType = 'fade' | 'slide-left' | 'slide-right' | 'zoom';
+
+/** Text alignment */
+export type Alignment = 'left' | 'center' | 'right';
+
+/** Button variant styles */
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost';
+
+/** Action types for interactions */
+export interface GotoAction {
+  type: 'goto';
+  target: string;
+  transition?: TransitionType;
+}
+
+export type Action = GotoAction;
+
+/** UI Element types */
+export interface BoxElement {
+  TAG: 'Box';
+  name?: string;
+  children: Element[];
+}
+
+export interface ButtonElement {
+  TAG: 'Button';
+  id: string;
+  text: string;
+  align: Alignment;
+  variant?: ButtonVariant;
+  actions: Action[];
+}
+
+export interface InputElement {
+  TAG: 'Input';
+  id: string;
+  placeholder?: string;
+  variant?: string;
+}
+
+export interface LinkElement {
+  TAG: 'Link';
+  id: string;
+  text: string;
+  align: Alignment;
+  actions: Action[];
+}
+
+export interface TextElement {
+  TAG: 'Text';
+  content: string;
+  emphasis: boolean;
+  align: Alignment;
+}
+
+export interface CheckboxElement {
+  TAG: 'Checkbox';
+  checked: boolean;
+  label: string;
+}
+
+export interface DividerElement {
+  TAG: 'Divider';
+}
+
+export interface RowElement {
+  TAG: 'Row';
+  children: Element[];
+  align: Alignment;
+}
+
+export interface SectionElement {
+  TAG: 'Section';
+  name: string;
+  children: Element[];
+}
+
+export type Element =
+  | BoxElement
+  | ButtonElement
+  | InputElement
+  | LinkElement
+  | TextElement
+  | CheckboxElement
+  | DividerElement
+  | RowElement
+  | SectionElement;
+
+/** Scene definition */
+export interface Scene {
+  id: string;
+  title: string;
+  device: DeviceType;
+  transition: TransitionType;
+  elements: Element[];
+}
+
+/** Abstract Syntax Tree */
+export interface AST {
+  scenes: Scene[];
+}
+
+/** Parse error information */
+export interface ParseError {
+  message: string;
+  line?: number;
+  column?: number;
+  source?: string;
+}
+
+/** Scene manager for programmatic navigation */
+export interface SceneManager {
+  /** Navigate to a scene by ID */
+  goto: (sceneId: string) => void;
+  /** Get the current scene ID */
+  getCurrentScene: () => string | undefined;
+  /** Get all available scene IDs */
+  getSceneIds: () => string[];
+}
+
+/** Render options */
+export interface RenderOptions {
+  /** Theme name */
+  theme?: string;
+  /** Enable interactions (default: true) */
+  interactive?: boolean;
+  /** Inject default styles (default: true) */
+  injectStyles?: boolean;
+  /** Additional CSS class for container */
+  containerClass?: string;
+}
+
+/** Render result */
+export interface RenderResult {
+  /** Rendered root element */
+  root: HTMLElement;
+  /** Scene manager for navigation */
+  sceneManager: SceneManager;
+}
+
+// ============================================================================
+// Result Types (TypeScript-friendly)
+// ============================================================================
+
+export type ParseSuccessResult = {
+  success: true;
+  ast: AST;
+};
+
+export type ParseErrorResult = {
+  success: false;
+  errors: ParseError[];
+};
+
+export type ParseResult = ParseSuccessResult | ParseErrorResult;
+
+export type InteractionSuccessResult = {
+  success: true;
+  interactions: unknown[];
+};
+
+export type InteractionErrorResult = {
+  success: false;
+  errors: ParseError[];
+};
+
+export type InteractionResult = InteractionSuccessResult | InteractionErrorResult;
+
+export type CreateUISuccessResult = {
+  success: true;
+  root: HTMLElement;
+  sceneManager: SceneManager;
+  ast: AST;
+};
+
+export type CreateUIErrorResult = {
+  success: false;
+  errors: ParseError[];
+};
+
+export type CreateUIResult = CreateUISuccessResult | CreateUIErrorResult;
+
+// ============================================================================
+// Internal ReScript Result Type
+// ============================================================================
+
+interface ReScriptOk<T> {
+  TAG: 'Ok';
+  _0: T;
+}
+
+interface ReScriptError<E> {
+  TAG: 'Error';
+  _0: E;
+}
+
+type ReScriptResult<T, E> = ReScriptOk<T> | ReScriptError<E>;
+
+// ============================================================================
+// API Functions
+// ============================================================================
+
+/**
+ * Parse mixed text containing wireframe and interactions.
+ *
+ * @param text - Text containing ASCII wireframe and/or interaction DSL
+ * @returns Parse result with success flag
+ *
+ * @example
+ * ```typescript
+ * const result = parse(text);
+ * if (result.success) {
+ *   const { root, sceneManager } = render(result.ast);
+ *   document.body.appendChild(root);
+ * } else {
+ *   console.error(result.errors);
+ * }
+ * ```
+ */
+export function parse(text: string): ParseResult {
+  const result = Parser.parse(text) as ReScriptResult<AST, ParseError[]>;
+
+  if (result.TAG === 'Ok') {
+    return { success: true, ast: result._0 };
+  } else {
+    return { success: false, errors: result._0 };
+  }
+}
+
+/**
+ * Parse text and throw on error.
+ * Use this for simpler code when you expect parsing to succeed.
+ *
+ * @param text - Text containing ASCII wireframe and/or interaction DSL
+ * @returns Parsed AST
+ * @throws Error if parsing fails
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const ast = parseOrThrow(text);
+ *   const { root } = render(ast);
+ *   document.body.appendChild(root);
+ * } catch (error) {
+ *   console.error('Parse failed:', error.message);
+ * }
+ * ```
+ */
+export function parseOrThrow(text: string): AST {
+  const result = parse(text);
+
+  if (result.success) {
+    return result.ast;
+  } else {
+    const errorMessages = result.errors
+      .map((e) => e.message || JSON.stringify(e))
+      .join('\n');
+    throw new Error(`Parse failed:\n${errorMessages}`);
+  }
+}
+
+/**
+ * Parse only the wireframe structure (no interactions).
+ *
+ * @param wireframe - ASCII wireframe string
+ * @returns Parse result with success flag
+ */
+export function parseWireframe(wireframe: string): ParseResult {
+  const result = Parser.parseWireframe(wireframe) as ReScriptResult<AST, ParseError[]>;
+
+  if (result.TAG === 'Ok') {
+    return { success: true, ast: result._0 };
+  } else {
+    return { success: false, errors: result._0 };
+  }
+}
+
+/**
+ * Parse only the interaction DSL.
+ *
+ * @param dsl - Interaction DSL string
+ * @returns Interaction result with success flag
+ */
+export function parseInteractions(dsl: string): InteractionResult {
+  const result = Parser.parseInteractions(dsl) as ReScriptResult<unknown[], ParseError[]>;
+
+  if (result.TAG === 'Ok') {
+    return { success: true, interactions: result._0 };
+  } else {
+    return { success: false, errors: result._0 };
+  }
+}
+
+/**
+ * Render AST to DOM elements.
+ *
+ * @param ast - Parsed AST from parse()
+ * @param options - Render options
+ * @returns Render result with root element and scene manager
+ *
+ * @example
+ * ```typescript
+ * const { root, sceneManager } = render(ast);
+ * document.getElementById('app')!.appendChild(root);
+ *
+ * // Navigate between scenes
+ * sceneManager.goto('dashboard');
+ * ```
+ */
+export function render(ast: AST, options?: RenderOptions): RenderResult {
+  // Pass undefined if no options, so ReScript uses its defaults
+  const result = Renderer.render(ast, options);
+
+  return {
+    root: result.root,
+    sceneManager: {
+      goto: result.sceneManager.goto,
+      getCurrentScene: result.sceneManager.getCurrentScene,
+      getSceneIds: result.sceneManager.getSceneIds,
+    },
+  };
+}
+
+/**
+ * Parse and render in one step.
+ * Convenience function that combines parse() and render().
+ *
+ * @param text - Text containing ASCII wireframe and/or interaction DSL
+ * @param options - Render options
+ * @returns Create UI result with success flag
+ *
+ * @example
+ * ```typescript
+ * const result = createUI(text);
+ * if (result.success) {
+ *   document.getElementById('app')!.appendChild(result.root);
+ *   result.sceneManager.goto('login');
+ * }
+ * ```
+ */
+export function createUI(text: string, options?: RenderOptions): CreateUIResult {
+  const parseResult = parse(text);
+
+  if (!parseResult.success) {
+    return parseResult;
+  }
+
+  const { root, sceneManager } = render(parseResult.ast, options);
+
+  return {
+    success: true,
+    root,
+    sceneManager,
+    ast: parseResult.ast,
+  };
+}
+
+/**
+ * Parse and render, throwing on error.
+ *
+ * @param text - Text containing ASCII wireframe and/or interaction DSL
+ * @param options - Render options
+ * @returns Render result with root element, scene manager, and AST
+ * @throws Error if parsing fails
+ *
+ * @example
+ * ```typescript
+ * const { root, sceneManager } = createUIOrThrow(text);
+ * document.getElementById('app')!.appendChild(root);
+ * ```
+ */
+export function createUIOrThrow(
+  text: string,
+  options?: RenderOptions
+): RenderResult & { ast: AST } {
+  const ast = parseOrThrow(text);
+  const { root, sceneManager } = render(ast, options);
+
+  return { root, sceneManager, ast };
+}
+
+// Version info
+export const version: string = Parser.version;
+export const implementation: string = Parser.implementation;
+
+// Default export for convenience
+export default {
+  parse,
+  parseOrThrow,
+  parseWireframe,
+  parseInteractions,
+  render,
+  createUI,
+  createUIOrThrow,
+  version,
+  implementation,
+};

package/src/renderer/Renderer.gen.tsx

@@ -7,6 +7,8 @@ import * as RendererJS from './Renderer.mjs';
 
 import type {ast as Types_ast} from '../../src/parser/Core/Types.gen';
 
+import type {t as ErrorTypes_t} from '../../src/parser/Errors/ErrorTypes.gen';
+
 export abstract class DomBindings_element { protected opaque!: any }; /* simulate opaque types */
 
 /** * Configuration for the rendering process. */
@@ -27,6 +29,53 @@ export type sceneManager = {
 /** * Render result containing the root element and scene manager. */
 export type renderResult = { readonly root: DomBindings_element; readonly sceneManager: sceneManager };
 
+/** * Result type for createUI function.
+ * Contains either success with rendered elements or error with parse errors. */
+export type createUISuccessResult = {
+  readonly root: DomBindings_element; 
+  readonly sceneManager: sceneManager; 
+  readonly ast: Types_ast
+};
+
+export type createUIResult = 
+    { TAG: "Ok"; _0: createUISuccessResult }
+  | { TAG: "Error"; _0: ErrorTypes_t[] };
+
 export const render: (ast:Types_ast, options:(undefined | renderOptions)) => renderResult = RendererJS.render as any;
 
 export const toHTMLString: (_ast:Types_ast, _options:(undefined | renderOptions)) => string = RendererJS.toHTMLString as any;
+
+/** * Parse and render wireframe in one step.
+ * Combines Parser.parse() and Renderer.render() for convenience.
+ *
+ * @param text Text containing ASCII wireframe and/or interaction DSL
+ * @param options Optional render options
+ * @returns Result containing root element, scene manager, and AST, or errors
+ *
+ * @example
+ * ```rescript
+ * let result = Renderer.createUI(wireframeText, None)
+ * switch result {
+ * | Ok({root, sceneManager, ast}) => {
+ *     // Append root to DOM
+ *     sceneManager.goto("login")
+ *   }
+ * | Error(errors) => Console.error(errors)
+ * }
+ * ``` */
+export const createUI: (text:string, options:(undefined | renderOptions)) => createUIResult = RendererJS.createUI as any;
+
+/** * Parse and render wireframe, throwing on error.
+ * Use this for simpler code when parsing is expected to succeed.
+ *
+ * @param text Text containing ASCII wireframe and/or interaction DSL
+ * @param options Optional render options
+ * @returns Rendered root element, scene manager, and AST
+ * @raises Js.Exn.Error if parsing fails
+ *
+ * @example
+ * ```rescript
+ * let {root, sceneManager, ast} = Renderer.createUIOrThrow(wireframeText, None)
+ * // Use root directly - errors will throw exception
+ * ``` */
+export const createUIOrThrow: (text:string, options:(undefined | renderOptions)) => createUISuccessResult = RendererJS.createUIOrThrow as any;

package/src/renderer/Renderer.mjs

@@ -1,6 +1,9 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Parser from "../parser/Parser.mjs";
 import * as Core__Option from "@rescript/core/src/Core__Option.mjs";
+import * as ErrorMessages from "../parser/Errors/ErrorMessages.mjs";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 
 let DomBindings = {};
@@ -371,6 +374,41 @@ function toHTMLString(_ast, _options) {
   return "<!-- Static HTML generation not yet implemented -->";
 }
 
+function createUI(text, options) {
+  let ast = Parser.parse(text);
+  if (ast.TAG !== "Ok") {
+    return {
+      TAG: "Error",
+      _0: ast._0
+    };
+  }
+  let ast$1 = ast._0;
+  let match = render(ast$1, options);
+  return {
+    TAG: "Ok",
+    _0: {
+      root: match.root,
+      sceneManager: match.sceneManager,
+      ast: ast$1
+    }
+  };
+}
+
+function createUIOrThrow(text, options) {
+  let ast = Parser.parse(text);
+  if (ast.TAG === "Ok") {
+    let ast$1 = ast._0;
+    let match = render(ast$1, options);
+    return {
+      root: match.root,
+      sceneManager: match.sceneManager,
+      ast: ast$1
+    };
+  }
+  let messages = ast._0.map(err => ErrorMessages.getTitle(err.code)).join("\n");
+  return Stdlib_JsError.throwWithMessage("Parse failed:\n" + messages);
+}
+
 export {
   DomBindings,
   defaultOptions,
@@ -387,5 +425,7 @@ export {
   injectStyles,
   render,
   toHTMLString,
+  createUI,
+  createUIOrThrow,
 }
-/* No side effect */
+/* Parser Not a pure module */