@rettangoli/fe 0.0.7-rc5 → 0.0.7-rc6

package/README.md

@@ -14,13 +14,18 @@ A modern frontend framework that uses YAML for view definitions, web components
 
 ## Quick Start
 
-**Production usage** (when rtgl is installed globally):
 ```bash
 rtgl fe build     # Build components
 rtgl fe watch     # Start dev server
-rtgl fe scaffold  # Create new component
 ```
 
+## Documentation
+
+- **[Developer Quickstart](./docs/overview.md)** - Complete introduction and examples
+- **[View System](./docs/view.md)** - Complete YAML syntax
+- **[Store Management](./docs/store.md)** - State patterns
+- **[Event Handlers](./docs/handlers.md)** - Event handling
+
 ## Architecture
 
 ### Technology Stack
@@ -84,335 +89,6 @@ src/
 └── index.js           # Main exports
 ```
 
-# Usage
-
-## Component Structure
-
-Each component consists of three files:
-
-```
-component-name/
-├── component-name.handlers.js   # Event handlers
-├── component-name.store.js      # State management
-└── component-name.view.yaml     # UI structure and styling
-```
-
-
-## View Layer (.view.yaml)
-
-Views are written in YAML and compiled to virtual DOM at build time.
-
-### Basic HTML Structure
-
-```yaml
-template:
-  - div#myid.class1.class2 custom-attribute=abcd:
-    - rtgl-text: "Hello World"
-    - rtgl-button: "Click Me"
-```
-
-Compiles to:
-```html
-<div id="myid" class="class1 class2" custom-attribute="abcd">
-  <rtgl-text>Hello World</rtgl-text>
-  <rtgl-button>Click Me</rtgl-button>
-</div>
-```
-
-### Component Definition
-
-```yaml
-elementName: my-custom-component
-
-template:
-  - rtgl-view:
-    - rtgl-text: "My Component"
-```
-
-### Attributes vs Props
-
-When passing data to components, there's an important distinction:
-
-```yaml
-template:
-  - custom-component title=Hello .items=items
-```
-
-- **Attributes** (`title=Hello`): Always string values, passed as HTML attributes
-- **Props** (`.items=items`): JavaScript values from viewData, passed as component properties
-
-Attributes become HTML attributes, while props are JavaScript objects/arrays/functions passed directly to the component.
-
-### Variable Expressions
-
-Views do not support complex variable expressions like `${myValue || 4}`. All values must be pre-computed in the `toViewData` store function:
-
-❌ **Don't do this:**
-```yaml
-template:
-  - rtgl-text: "${user.name || 'Guest'}"
-  - rtgl-view class="${isActive ? 'active' : 'inactive'}"
-```
-
-✅ **Do this instead:**
-```js
-// In your .store.js file
-export const toViewData = ({ state, props, attrs }) => {
-  return {
-    ...state,
-    displayName: state.user.name || 'Guest',
-    statusClass: state.isActive ? 'active' : 'inactive'
-  };
-};
-```
-
-```yaml
-template:
-  - rtgl-text: "${displayName}"
-  - rtgl-view class="${statusClass}"
-```
-
-
-
-### Styling
-
-```yaml
-styles:
-  '#title':
-    font-size: 24px
-    color: blue
-  '@media (min-width: 768px)':
-    '#title':
-      font-size: 32px
-```
-
-### Event Handling
-
-```yaml
-refs:
-  submitButton:
-    eventListeners:
-      click:
-        handler: handleSubmit
-
-template:
-  - rtgl-button#submitButton: "Submit"
-```
-
-### Templating with Jempl
-
-**Loops:**
-```yaml
-template:
-  - rtgl-view:
-      projects:
-        $for project, index in projects:
-          - rtgl-view#project-${project.id}:
-            - rtgl-text: "${project.name}"
-            - rtgl-text: "${project.description}"
-            - rtgl-text: "Item ${index}"
-```
-
-
-#### Props caveats
-
-❌ This will not work. Prop references can only be taken from viewDate, not from loop variables
-
-```yaml
-
-template:
-  - rtgl-view:
-    - $for project, index in projects:
-      - rtgl-view#project-${project.id}:
-        - custom-component .item=project: 
-```
-
-✅ This is the workaround
-
-```yaml
-template:
-  - rtgl-view:
-    - $for project, index in projects:
-      - rtgl-view#project-${project.id}:
-        - custom-component .item=projects[${index}]: 
-```
-
-**Conditionals:**
-```yaml
-template:
-  - rtgl-view:
-      $if isLoggedIn:
-        - user-dashboard: []
-      $else:
-        - login-form: []
-
-# Multiple conditions with logical operators
-template:
-  - rtgl-view:
-      $if user.age >= 18 && user.verified:
-        - admin-panel: []
-      $elif user.age >= 13:
-        - teen-dashboard: []
-      $else:
-        - kid-dashboard: []
-```
-
-For more advanced templating features, see the [Jempl documentation](https://github.com/yuusoft-org/jempl).
-
-### Data Schemas
-
-Define component interfaces with JSON Schema:
-
-```yaml
-viewDataSchema:
-  type: object
-  properties:
-    title:
-      type: string
-      default: "My Component"
-    items:
-      type: array
-      items:
-        type: object
-
-propsSchema:
-  type: object
-  properties:
-    onSelect:
-      type: function
-
-attrsSchema:
-  type: object
-  properties:
-    variant:
-      type: string
-      enum: [primary, secondary]
-```
-
-## State Management (.store.js)
-
-### Initial State
-
-```js
-export const INITIAL_STATE = Object.freeze({
-  title: "My App",
-  items: [],
-  loading: false
-});
-```
-
-### View Data Transformation
-
-```js
-export const toViewData = ({ state, props, attrs }) => {
-  return {
-    ...state,
-    itemCount: state.items.length,
-    hasItems: state.items.length > 0
-  };
-};
-```
-
-### Selectors
-
-```js
-export const selectItems = (state) => state.items;
-export const selectIsLoading = (state) => state.loading;
-```
-
-### Actions
-
-```js
-export const setLoading = (state, isLoading) => {
-  state.loading = isLoading; // Immer makes this immutable
-};
-
-export const addItem = (state, item) => {
-  state.items.push(item);
-};
-
-export const removeItem = (state, itemId) => {
-  const index = state.items.findIndex(item => item.id === itemId);
-  if (index !== -1) {
-    state.items.splice(index, 1);
-  }
-};
-```
-
-## Event Handlers (.handlers.js)
-
-### Special Handlers
-
-```js
-// Called when component mounts
-export const handleOnMount = (deps) => {
-  const { store, render } = deps;
-  
-  // Load initial data
-  store.setLoading(true);
-  loadData().then(data => {
-    store.setItems(data);
-    store.setLoading(false);
-    render();
-  });
-
-  // Return cleanup function
-  return () => {
-    // Cleanup code here
-  };
-};
-```
-
-### Event Handlers
-
-```js
-export const handleSubmit = async (event, deps) => {
-  const { store, render, attrs, props } = deps;
-  
-  event.preventDefault();
-  
-  const formData = new FormData(event.target);
-  const newItem = Object.fromEntries(formData);
-  
-  store.addItem(newItem);
-  render();
-  
-  // Dispatch custom event
-  deps.dispatchEvent(new CustomEvent('item-added', {
-    detail: { item: newItem }
-  }));
-};
-
-export const handleItemClick = (event, deps) => {
-  const itemId = event.target.id.replace('item-', '');
-  console.log('Item clicked:', itemId);
-};
-```
-
-### Dependency Injection
-
-```js
-// In your setup.js file
-const componentDependencies = {
-  apiClient: new ApiClient(),
-  router: new Router()
-};
-
-export const deps = {
-  components: componentDependencies,
-  pages: {}
-};
-```
-
-Access in handlers:
-```js
-export const handleLoadData = async (event, deps) => {
-  const { apiClient } = deps.components;
-  const data = await apiClient.fetchItems();
-  // ... handle data
-};
-```
-
 ## Configuration
 
 Create a `rettangoli.config.yaml` file in your project root:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/fe",
-  "version": "0.0.7-rc5",
+  "version": "0.0.7-rc6",
   "description": "Frontend framework for building reactive web components",
   "type": "module",
   "main": "./src/index.js",

package/src/createComponent.js

@@ -4,7 +4,7 @@ import { parseView } from "./parser.js";
 /**
  * covert this format of json into raw css strings
  * notice if propoperty starts with \@, it will need to nest it
- * 
+ *
     ':host':
       display: contents
     'button':
@@ -26,8 +26,8 @@ import { parseView } from "./parser.js";
     '@media (min-width: 768px)':
       'button':
         height: 40px
- * @param {*} styleObject 
- * @returns 
+ * @param {*} styleObject
+ * @returns
  */
 const yamlToCss = (elementName, styleObject) => {
   if (!styleObject || typeof styleObject !== "object") {
@@ -313,15 +313,24 @@ class BaseComponent extends HTMLElement {
       };
     });
 
-    if (this.handlers?.subscriptions) {
-      this.unsubscribeAll = subscribeAll(this.handlers.subscriptions(deps));
-    }
+    if (this.handlers?.handleBeforeMount) {
+      this._unmountCallback = this.handlers?.handleBeforeMount(deps);
 
-    if (this.handlers?.handleOnMount) {
-      this._unmountCallback = this.handlers?.handleOnMount(deps);
+      // Validate that handleBeforeMount doesn't return a Promise
+      if (this._unmountCallback && typeof this._unmountCallback.then === 'function') {
+        throw new Error('handleBeforeMount must be synchronous and cannot return a Promise.');
+      }
     }
 
     this.render();
+
+    if (this.handlers?.handleAfterMount) {
+      this.handlers?.handleAfterMount(deps);
+    }
+
+    if (this.handlers?.subscriptions) {
+      this.unsubscribeAll = subscribeAll(this.handlers.subscriptions(deps));
+    }
   }
 
   disconnectedCallback() {

package/src/parser.js

@@ -113,7 +113,7 @@ export const createVirtualDom = ({
 
         const entries = Object.entries(item);
         if (entries.length === 0) {
-          console.warn("Skipping empty object item:", item);
+          // skipping empty object item
           return null;
         }