@rettangoli/fe 0.0.14 → 1.0.0-rc3

package/README.md

@@ -1,10 +1,10 @@
 # Rettangoli Frontend
 
-A modern frontend framework that uses YAML for view definitions, web components for composition, and Immer for state management. Build reactive applications with minimal complexity using just 3 types of files.
+A modern frontend framework that uses YAML for view definitions, web components for composition, and Immer for state management. Build reactive applications with minimal complexity using 4 types of files.
 
 ## Features
 
-- **🗂️ Three-File Architecture** - `.view.yaml`, `.store.js`, `.handlers.js` files scale from single page to complex applications
+- **🗂️ Four-File Architecture** - `.view.yaml`, `.store.js`, `.handlers.js`, `.schema.yaml` scale from single page to complex applications
 - **📝 YAML Views** - Declarative UI definitions that compile to virtual DOM
 - **🧩 Web Components** - Standards-based component architecture
 - **🔄 Reactive State** - Immer-powered immutable state management
@@ -23,6 +23,7 @@ rtgl fe watch     # Start dev server
 
 - **[Developer Quickstart](./docs/overview.md)** - Complete introduction and examples
 - **[View System](./docs/view.md)** - Complete YAML syntax
+- **[Schema System](./docs/schema.md)** - Component API and metadata
 - **[Store Management](./docs/store.md)** - State patterns
 - **[Event Handlers](./docs/handlers.md)** - Event handling
 
@@ -38,7 +39,6 @@ rtgl fe watch     # Start dev server
 
 **Build & Development:**
 - [ESBuild](https://esbuild.github.io/) - Fast bundling
-- [Vite](https://vite.dev/) - Development server with hot reload
 
 **Browser Native:**
 - Web Components - Component encapsulation
@@ -60,7 +60,7 @@ bun install
 2. **Create project structure**:
 ```bash
 # Scaffold a new component
-node ../rettangoli-cli/cli.js fe scaffold --category components --name MyButton
+node ../rettangoli-cli/cli.js fe scaffold --category components --component-name MyButton
 ```
 
 3. **Start development**:
@@ -83,7 +83,7 @@ src/
 │   ├── examples.js    # Generate examples for testing
 │   └── blank/         # Component templates
 ├── createComponent.js # Component factory
-├── createWebPatch.js  # Virtual DOM patching
+├── createWebPatch.js  # Internal virtual DOM patching
 ├── parser.js          # YAML to JSON converter
 ├── common.js          # Shared utilities
 └── index.js           # Main exports
@@ -104,17 +104,102 @@ fe:
     outputDir: "./vt/specs/examples"
 ```
 
+## Setup Contract
+
+`setup.js` should export `deps` only.
+`createWebPatch`/`h` wiring is internalized by the framework.
+
+```js
+const deps = {
+  components: {},
+  pages: {},
+};
+
+export { deps };
+```
+
+## Action Listeners
+
+In `.view.yaml`, listeners can dispatch store actions directly with `action`.
+This path auto-runs render after the action executes.
+
+```yaml
+refs:
+  inputEmail:
+    eventListeners:
+      input:
+        action: setEmail
+        payload:
+          value: ${_event.target.value}
+```
+
+Store action:
+
+```js
+export const setEmail = ({ state }, { value }) => {
+  state.email = value;
+};
+```
+
+Runtime-injected action payload fields:
+- `_event`
+- `_action` (internal dispatch metadata)
+
 ## Testing
 
-### View Components
+### Unit and Contract Tests
 
-Use visual testing with `rtgl vt`:
+- **Puty contract tests** (`spec/`) — YAML-driven pure-function specs for view, store, schema, and handler contracts.
+- **Vitest integration tests** (`test/`) — runtime behavior tests for component lifecycle, props, events, and DOM.
 
 ```bash
-rtgl vt generate
-rtgl vt report
+bun run test           # all tests
+bun run test:puty      # contract tests only
+bun run test:vitest    # integration tests only
 ```
 
+### End-to-End Testing
+
+FE has two E2E suites in this package:
+
+- `packages/rettangoli-fe/e2e/dashboard`
+- `packages/rettangoli-fe/e2e/interactions`
+
+Use this workflow:
+1. Build FE with the local repo CLI (`cli.js`) so it uses your current FE source.
+2. Run VT in Docker for stable Playwright runtime.
+
+Docker image:
+
+```bash
+IMAGE="han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.0-rc4"
+```
+
+Dashboard suite:
+
+```bash
+(cd packages/rettangoli-fe/e2e/dashboard && node ../../../rettangoli-cli/cli.js fe build)
+docker run --rm -v "$(pwd):/workspace" -w /workspace/packages/rettangoli-fe/e2e/dashboard "$IMAGE" rtgl vt generate
+docker run --rm -v "$(pwd):/workspace" -w /workspace/packages/rettangoli-fe/e2e/dashboard "$IMAGE" rtgl vt report
+```
+
+Interactions suite:
+
+```bash
+(cd packages/rettangoli-fe/e2e/interactions && node ../../../rettangoli-cli/cli.js fe build)
+docker run --rm -v "$(pwd):/workspace" -w /workspace/packages/rettangoli-fe/e2e/interactions "$IMAGE" rtgl vt generate
+docker run --rm -v "$(pwd):/workspace" -w /workspace/packages/rettangoli-fe/e2e/interactions "$IMAGE" rtgl vt report
+```
+
+Accept intentional visual changes:
+
+```bash
+docker run --rm -v "$(pwd):/workspace" -w /workspace/packages/rettangoli-fe/e2e/dashboard "$IMAGE" rtgl vt accept
+docker run --rm -v "$(pwd):/workspace" -w /workspace/packages/rettangoli-fe/e2e/interactions "$IMAGE" rtgl vt accept
+```
+
+VT specs live under each suite's `vt/specs/` directory.
+
 ## Examples
 
 For a complete working example, see the todos app in `examples/example1/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/fe",
-  "version": "0.0.14",
+  "version": "1.0.0-rc3",
   "description": "Frontend framework for building reactive web components",
   "type": "module",
   "main": "./src/index.js",
@@ -25,7 +25,10 @@
     ".": "./src/index.js",
     "./cli": "./src/cli/index.js"
   },
-  "devDependencies": {},
+  "devDependencies": {
+    "puty": "^0.1.1",
+    "vitest": "^4.0.15"
+  },
   "dependencies": {
     "esbuild": "^0.25.5",
     "immer": "^10.1.1",
@@ -36,6 +39,9 @@
     "vite": "^6.3.5"
   },
   "scripts": {
-    "dev": "node watch.js --watch"
+    "dev": "node watch.js --watch",
+    "test": "vitest run --reporter=verbose",
+    "test:puty": "vitest run puty.spec.js --reporter=verbose",
+    "test:vitest": "vitest run test/**/*.test.js --reporter=verbose"
   }
 }

package/src/cli/blank/blank.handlers.js

@@ -1,8 +1,11 @@
+export const handleBeforeMount = (deps, payload) => {
+  //
+}
 
-export const handleOnMount = (deps, event) => {
+export const handleAfterMount = async (deps, payload) => {
   //
 }
 
-export const handlerSomeEvent = (deps, event) => {
+export const handleSomeEvent = (deps, payload) => {
   //
 }

package/src/cli/blank/blank.schema.yaml

@@ -0,0 +1,13 @@
+componentName: custom-blank
+
+description: Blank component scaffold
+
+propsSchema:
+  type: object
+  properties: {}
+
+events: []
+
+methods:
+  type: object
+  properties: {}

package/src/cli/blank/blank.view.yaml

@@ -1,16 +1,5 @@
-elementName: custom-blank
-
-viewDataSchema:
-  type: object
-
-propsSchema:
-  type: object
-  properties: {}
-
 refs: {}
 
-events: {}
-
 template:
   - rtgl-view w=f h=f p=md:
     - rtgl-text s=h2: blank

package/src/cli/build.js

@@ -10,24 +10,32 @@ import { load as loadYaml } from "js-yaml";
 import { parse } from 'jempl';
 import { extractCategoryAndComponent } from '../commonBuild.js';
 import { getAllFiles } from '../commonBuild.js';
+import {
+  isSupportedComponentFile,
+  validateComponentEntries,
+} from "./contracts.js";
 import path from "node:path";
 
 function capitalize(word) {
   return word ? word[0].toUpperCase() + word.slice(1) : word;
 }
 
-// Function to process view files - loads YAML and creates temporary JS file
-export const writeViewFile = (view, category, component, tempDir) => {
+const writeYamlModuleFile = (yamlObject, category, component, fileType, tempDir = path.resolve(process.cwd(), ".temp")) => {
   const dir = path.join(tempDir, category);
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
   writeFileSync(
-    path.join(dir, `${component}.view.js`),
-    `export default ${JSON.stringify(view)};`,
+    path.join(dir, `${component}.${fileType}.js`),
+    `export default ${JSON.stringify(yamlObject)};`,
   );
 };
 
+// Function to process view files - loads YAML and creates temporary JS file
+export const writeViewFile = (view, category, component, tempDir = path.resolve(process.cwd(), ".temp")) => {
+  writeYamlModuleFile(view, category, component, "view", tempDir);
+};
+
 export const bundleFile = async (options) => {
   const { outfile, tempDir, development = false } = options;
   await esbuild.build({
@@ -66,18 +74,13 @@ const buildRettangoliFrontend = async (options) => {
     mkdirSync(tempDir, { recursive: true });
   }
 
-  const allFiles = getAllFiles(resolvedDirs).filter((filePath) => {
-    return (
-      filePath.endsWith(".store.js") ||
-      filePath.endsWith(".handlers.js") ||
-      filePath.endsWith(".view.yaml")
-    );
-  });
+  const allFiles = getAllFiles(resolvedDirs).filter((filePath) => isSupportedComponentFile(filePath));
 
   let output = "";
 
   const categories = [];
   const imports = {};
+  const componentContractEntries = [];
 
   // unique identifier needed for replacing
   let count = 10000000000;
@@ -101,7 +104,14 @@ const buildRettangoliFrontend = async (options) => {
     }
 
 
-    if (["handlers", "store"].includes(fileType)) {
+    const componentContractEntry = {
+      category,
+      component,
+      fileType,
+      filePath,
+    };
+
+    if (["handlers", "store", "methods"].includes(fileType)) {
       const relativePath = path.relative(tempDir, filePath).replaceAll(path.sep, "/");
       output += `import * as ${component}${capitalize(
         fileType,
@@ -110,35 +120,57 @@ const buildRettangoliFrontend = async (options) => {
       replaceMap[count] = `${component}${capitalize(fileType)}`;
       imports[category][component][fileType] = count;
       count++;
-    } else if (["view"].includes(fileType)) {
-      const view = loadYaml(readFileSync(filePath, "utf8"));
-      try {
-        view.template = parse(view.template);
-      } catch (error) {
-        console.error(`Error parsing template in file: ${filePath}`);
-        throw error;
+    } else if (["view", "constants", "schema"].includes(fileType)) {
+      const yamlObject = loadYaml(readFileSync(filePath, "utf8")) ?? {};
+      componentContractEntry.yamlObject = yamlObject;
+      if (fileType === "view") {
+        try {
+          yamlObject.template = parse(yamlObject.template);
+        } catch (error) {
+          console.error(`Error parsing template in file: ${filePath}`);
+          throw error;
+        }
       }
-      writeViewFile(view, category, component, tempDir);
+      if (
+        fileType === "constants" &&
+        (yamlObject === null || typeof yamlObject !== "object" || Array.isArray(yamlObject))
+      ) {
+        throw new Error(`[Build] ${filePath} must contain a YAML object at the root.`);
+      }
+
+      writeYamlModuleFile(yamlObject, category, component, fileType, tempDir);
       output += `import ${component}${capitalize(
         fileType,
-      )} from './${category}/${component}.view.js';\n`;
+      )} from './${category}/${component}.${fileType}.js';\n`;
       replaceMap[count] = `${component}${capitalize(fileType)}`;
 
       imports[category][component][fileType] = count;
       count++;
     }
+
+    componentContractEntries.push(componentContractEntry);
   }
 
+  validateComponentEntries({
+    entries: componentContractEntries,
+    errorPrefix: "[Build]",
+  });
+
   const relativeSetup = path.relative(tempDir, resolvedSetup).replaceAll(path.sep, "/");
   output += `
 import { createComponent } from '@rettangoli/fe';
-import { deps, patch, h } from '${relativeSetup}';
+import { deps } from '${relativeSetup}';
 const imports = ${JSON.stringify(imports, null, 2)};
 
 Object.keys(imports).forEach(category => {
   Object.keys(imports[category]).forEach(component => {
-    const webComponent = createComponent({ ...imports[category][component], patch, h }, deps[category])
-    customElements.define(imports[category][component].view.elementName, webComponent);
+    const componentConfig = imports[category][component];
+    const webComponent = createComponent({ ...componentConfig }, deps[category])
+    const elementName = componentConfig.schema?.componentName;
+    if (!elementName) {
+      throw new Error(\`[Build] Missing schema.componentName for \${category}/\${component}. Define it in .schema.yaml.\`);
+    }
+    customElements.define(elementName, webComponent);
   })
 })
 

package/src/cli/check.js

@@ -0,0 +1,53 @@
+import path from "node:path";
+import {
+  analyzeComponentDirs,
+  formatContractFailureReport,
+} from "./contracts.js";
+
+const checkRettangoliFrontend = (options = {}) => {
+  const {
+    cwd = process.cwd(),
+    dirs = ["./example"],
+    format = "text",
+  } = options;
+  const outputFormat = format === "json" ? "json" : "text";
+
+  const resolvedDirs = dirs.map((dir) => path.resolve(cwd, dir));
+  const { errors, summary, index } = analyzeComponentDirs({ dirs: resolvedDirs });
+
+  if (errors.length > 0) {
+    if (outputFormat === "json") {
+      console.log(JSON.stringify({
+        ok: false,
+        prefix: "[Check]",
+        summary,
+        errors,
+      }, null, 2));
+    } else {
+      console.error(formatContractFailureReport({
+        errorPrefix: "[Check]",
+        errors,
+      }));
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  const componentCount = Object.values(index).reduce((count, categoryComponents) => {
+    return count + Object.keys(categoryComponents).length;
+  }, 0);
+
+  if (outputFormat === "json") {
+    console.log(JSON.stringify({
+      ok: true,
+      prefix: "[Check]",
+      componentCount,
+      summary,
+    }, null, 2));
+    return;
+  }
+
+  console.log(`[Check] Component contracts passed for ${componentCount} component(s).`);
+};
+
+export default checkRettangoliFrontend;

package/src/cli/contracts.js

@@ -0,0 +1,149 @@
+import { readFileSync } from "node:fs";
+import { load as loadYaml } from "js-yaml";
+import { extractCategoryAndComponent, getAllFiles } from "../commonBuild.js";
+import {
+  buildComponentContractIndex,
+  formatContractErrors as formatContractErrorLines,
+  validateComponentContractIndex,
+} from "../core/contracts/componentFiles.js";
+
+export const SUPPORTED_COMPONENT_FILE_SUFFIXES = Object.freeze([
+  ".store.js",
+  ".handlers.js",
+  ".methods.js",
+  ".constants.yaml",
+  ".schema.yaml",
+  ".view.yaml",
+]);
+
+export const isSupportedComponentFile = (filePath) => {
+  return SUPPORTED_COMPONENT_FILE_SUFFIXES.some((suffix) => filePath.endsWith(suffix));
+};
+
+export const collectComponentContractEntriesFromFiles = (allFiles = []) => {
+  return allFiles
+    .filter((filePath) => isSupportedComponentFile(filePath))
+    .map((filePath) => {
+      const { category, component, fileType } = extractCategoryAndComponent(filePath);
+      const entry = {
+        category,
+        component,
+        fileType,
+        filePath,
+      };
+
+      if (["view", "schema"].includes(fileType)) {
+        try {
+          entry.yamlObject = loadYaml(readFileSync(filePath, "utf8")) ?? {};
+        } catch (err) {
+          throw new Error(
+            `[Check] Failed to read or parse ${filePath}: ${err.message}`,
+          );
+        }
+      }
+
+      return entry;
+    });
+};
+
+export const collectComponentContractEntriesFromDirs = (dirs = []) => {
+  const allFiles = getAllFiles(dirs);
+  return collectComponentContractEntriesFromFiles(allFiles);
+};
+
+export const validateComponentEntries = ({
+  entries = [],
+  errorPrefix = "[Check]",
+}) => {
+  const index = buildComponentContractIndex(entries);
+  const errors = validateComponentContractIndex(index);
+  if (errors.length > 0) {
+    throw new Error(
+      `${errorPrefix} Component contract validation failed:\n${formatContractErrors(errors).join("\n")}`,
+    );
+  }
+  return {
+    index,
+    errors,
+  };
+};
+
+export const validateComponentDirs = ({
+  dirs = [],
+  errorPrefix = "[Check]",
+}) => {
+  const entries = collectComponentContractEntriesFromDirs(dirs);
+  const validationResult = validateComponentEntries({ entries, errorPrefix });
+  return {
+    entries,
+    ...validationResult,
+  };
+};
+
+export const summarizeContractErrors = (errors = []) => {
+  const byCode = {};
+  const byComponent = {};
+
+  errors.forEach((error) => {
+    const code = error?.code || "UNKNOWN";
+    byCode[code] = (byCode[code] || 0) + 1;
+
+    const componentLabelMatch = String(error?.message || "").match(/^([^:]+):\s/);
+    const componentLabel = componentLabelMatch ? componentLabelMatch[1] : "unknown";
+    byComponent[componentLabel] = (byComponent[componentLabel] || 0) + 1;
+  });
+
+  const byCodeSorted = Object.entries(byCode)
+    .map(([code, count]) => ({ code, count }))
+    .sort((a, b) => a.code.localeCompare(b.code));
+
+  const byComponentSorted = Object.entries(byComponent)
+    .map(([component, count]) => ({ component, count }))
+    .sort((a, b) => b.count - a.count || a.component.localeCompare(b.component));
+
+  return {
+    total: errors.length,
+    byCode: byCodeSorted,
+    byComponent: byComponentSorted,
+  };
+};
+
+export const formatContractFailureReport = ({
+  errorPrefix = "[Check]",
+  errors = [],
+}) => {
+  const summary = summarizeContractErrors(errors);
+  const header = `${errorPrefix} Component contract validation failed: ${summary.total} issue(s)`;
+  const byCodeLines = summary.byCode.map(({ code, count }) => `- ${code}: ${count}`);
+  const byComponentLines = summary.byComponent.map(
+    ({ component, count }) => `- ${component}: ${count}`,
+  );
+  const detailLines = formatContractErrorLines(errors);
+
+  return [
+    header,
+    "By rule:",
+    ...(byCodeLines.length > 0 ? byCodeLines : ["- none"]),
+    "By component:",
+    ...(byComponentLines.length > 0 ? byComponentLines : ["- none"]),
+    "Details:",
+    ...(detailLines.length > 0 ? detailLines : ["- none"]),
+  ].join("\n");
+};
+
+export const analyzeComponentEntries = ({ entries = [] }) => {
+  const index = buildComponentContractIndex(entries);
+  const errors = validateComponentContractIndex(index);
+  const summary = summarizeContractErrors(errors);
+  return {
+    entries,
+    index,
+    errors,
+    summary,
+  };
+};
+
+export const analyzeComponentDirs = ({ dirs = [] }) => {
+  const entries = collectComponentContractEntriesFromDirs(dirs);
+  return analyzeComponentEntries({ entries });
+};

package/src/cli/index.js

@@ -1,11 +1,5 @@
-import build from './build.js';
-import scaffold from './scaffold.js';
-import watch from './watch.js';
-import examples from './examples.js';
-
-export {
-  build,
-  scaffold,
-  watch,
-  examples
-}
+export { default as build } from "./build.js";
+export { default as check } from "./check.js";
+export { default as scaffold } from "./scaffold.js";
+export { default as watch } from "./watch.js";
+export { default as examples } from "./examples.js";

package/src/cli/scaffold.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { validateComponentDirs } from './contracts.js';
 
 const __dirname = path.dirname(new URL(import.meta.url).pathname);
 
@@ -37,6 +38,11 @@ const scaffoldPage = (options) => {
     }
   });
 
+  validateComponentDirs({
+    dirs: [path.resolve(targetDir)],
+    errorPrefix: "[Scaffold]",
+  });
+
   console.log(`Successfully scaffolded ${targetDir} from template`);
 }
 

package/src/cli/watch.js

@@ -20,9 +20,10 @@ const setupWatcher = (directory, options) => {
       console.log(`Detected ${event} in ${directory}/${filename}`);
       if (filename) {
         try {
+          const changedFilePath = path.join(directory, filename);
           if (filename.endsWith('.view.yaml')) {
-            const view = loadYaml(readFileSync(path.join(directory, filename), "utf8"));
-            const { category, component } = extractCategoryAndComponent(filename);
+            const view = loadYaml(readFileSync(changedFilePath, "utf8"));
+            const { category, component } = extractCategoryAndComponent(changedFilePath);
             await writeViewFile(view, category, component);
           }