@ryupold/vode 0.13.1 → 1.0.0

package/.github/workflows/npm-publish.yml

@@ -15,7 +15,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: oven-sh/setup-bun@v2
-      - run: bun run build
+      - run: bun install
+      - run: bun run release
       - run: |
           echo "releasing to npm..."
           bun publish --provenance --access public | grep "+ @ryupold/vode@" > version.txt

package/README.md

@@ -1,11 +1,224 @@
-# vode
+# ![vode-logo](./logo.svg)
 
-Small web framework for minimal websites.
-Each vode app has its own state and renders a tree of HTML elements.
-The state is a singleton object that can be updated, and the UI will re-render when a patch is supplied. Nesting vode-apps is undefined behavior for now.
+A small web framework for a minimalistic development flow. Zero dependencies, no build step except for typescript compilation, and a simple virtual DOM implementation that is easy to understand and use. Autocompletion out of the box due to binding to `lib.dom.d.ts`.
+
+## vode
+
+A `vode` is a representation of a virtual DOM node, which is a tree structure of HTML elements. It is written as tuple:
+
+```
+[TAG, PROPS?, CHILDREN...]
+```
+
+As you can see, it is a simple array with the first element being the tag name, the second element being an optional properties object, and the rest being child-vodes.
+
+### Component
+```ts
+type Component<S> = (s: S) => ChildVode<S>;
+```
+
+A `Component<State>` is a function that takes a state object and returns a `Vode<State>`. It is used to render the UI based on the current state.
+
+```ts
+// A full vode has a tag, properties, and children. props and children are optional.
+const CompFooBar = (s) => [DIV, { class: "container" }, 
+    
+    // a child vode can be a string, which results in a text node
+    [H1, "Hello World"], 
+    
+    // a vode can also be a self-closing tag
+    [BR],
+    
+    // style object maps directly to the HTML style attribute
+    [P, { style: { color: "red", fontWeight: "bold" } }, "This is a paragraph."],
+
+    // class property has multiple forms
+    [UL,
+        [LI, {class: "class1 class2"}, "as string"],
+        [LI, {class: ["class1", "class2"]}, "as array"],
+        [LI, {class: {class1: true, class2: false}}, "as Record<string, boolean>"],
+    ],
+
+    // events get the state object as first argument
+    // and the HTML event object as second argument
+    [BUTTON, {
+        // all on* events accept `Patch<State>`
+        onclick: (state, evt) => {
+            // objects returned by events are patched automatically
+            return { counter: state.counter + 1 }; 
+        },
+
+        // you can set the patch object directly for events
+        onmouseenter: {pointing: true},
+        onmouseleave: {pointing: false},
+
+        // a patch can be an async function
+        onmouseup: async (state, evt) => {
+            state.patch(loading: true);
+            const result = await apiCall();
+            return { title: result.data.title, loading: false };
+        },
+
+        // you can also use a generator function that yields patches
+        onmousedown: async function* (state, evt) => {
+            yield { loading: true }; 
+            const result = await apiCall();
+            yield { 
+                body: result.data.body, 
+                loading: false
+            };
+        },
+
+        class: { bar: s.pointing }
+    }, "Click me!"],
+];
+```
+
+### app
+
+`app` is a function that takes a HTML node, an initial state object, and a render function (`Component<State>`).  
+```ts
+const appNode = document.getElementById('APP-ID');
+const initialState = {
+    counter: 0,
+    pointing: false,
+    loading: false,
+    title: '',
+    body: '',
+};
+const patch = app<State>(appNode, initialState, (s) => CompFooBar(s));
+```
+It will render the initial state and update the DOM when patches are applied to the patch function or via events. All elements returnded by the render function are placed under `appNode`. 
+
+You can have multiple isolated `app` instances on a page, each with its own state and render function. The returned patch function from `app` can be used to synchronize the state between them.
+
+### memoization
+To optimize performance, you can use `memo(Array, Component)` to cache the result of a component function. This is useful when the component does not depend on the state or when the state does not change frequently.
+
+```ts
+const CompMemoFooBar = (s) =>  [DIV, { class: "container" }, 
+    [H1, "Hello World"], 
+    [BR], 
+    [P, "This is a paragraph."],
+    
+    // expensive component to render
+    memo(
+        // this array is shallow compared to the previous render
+        [s.title, s.body], 
+        // this is the component function that will be 
+        // called only when the array changes
+        (s) => {
+            const list = [UL];
+            for (let i = 0; i < 1000; i++) {
+                list.push([LI, `Item ${i}`]);
+            }
+            return list;
+        },
+    )
+];
+```
+
+### state
+The state is a singleton object that can be updated. A re-render happens when a patch object is supplied to the patch function or via event.
+
+```ts
+// type safe way to create the state object
+const s = createState({
+    counter: 0,
+    pointing: false,
+    loading: false,
+    title: 'foo',
+    body: '',
+});
+
+type State = typeof s;
+
+app(appNode, s, ...); // after calling app(), the state object is bound to the appNode
+
+
+s.title = 'Hello World'; // update state directly as it is a singleton (silent patch)
+
+s.patch({}); // render patch
+
+s.patch({ title: 'bar' }); // render patch with a change that is applied to the state 
+
+s.patch((s) => ({body: s.body + ' baz'})); // render patch with a function that receives the state
+
+s.patch(async function*(s){
+    // you can also use a generator function that yields patches
+    yield { loading: true };
+    const result = await apiCall();
+    yield { title: result.title, body: result.body };
+    return { loading: false }; 
+});
+
+s.patch(null); // ignored, also: undefined, number, string, boolean, void
+
+s.patch({ pointing: undefined }); // deletes the property from the state
+```
 
 ## Install
 
+### ESM
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>ESM Example</title>
+</head>
+<body>
+    <div id="app"></div>
+    <script type="module">
+        import { app, createState, BR, DIV, INPUT, SPAN } from 'https://cdn.jsdelivr.net/npm/@ryupold/vode/dist/vode.min.mjs';
+
+        const appNode = document.getElementById('app');
+
+        app(appNode, { counter: 0 },
+            (s) => [DIV,
+                [INPUT, {
+                    type: 'button',
+                    onclick: { counter: s.counter + 1 },
+                    value: 'Click me',
+                }],
+                [BR],
+                [SPAN, { style: { color: 'red' } }, `${s.counter}`],
+            ]
+        );
+    </script>
+</body>
+</html>
+```
+
+### Classic
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>Classic Script Example</title>
+    <script src="https://cdn.jsdelivr.net/npm/@ryupold/vode/dist/vode.min.js"></script>
+</head>
+<body>
+    <div id="app"></div>
+    <script>
+        const appNode = document.getElementById('app');
+        V.app(appNode, { counter: 0 },
+            (s) => ["DIV",
+                ["INPUT", {
+                    type: 'button',
+                    onclick: { counter: s.counter + 1 },
+                    value: 'Click me',
+                }
+                ],
+                ["BR"],
+                ["SPAN", { style: { color: 'red' } }, `${s.counter}`],
+            ]);
+    </script>
+</body>
+</html>
+```
+
+### NPM
+
 ```bash
 # npm
 npm install @ryupold/vode --save
@@ -17,14 +230,7 @@ yarn add @ryupold/vode
 bun add @ryupold/vode
 ```
 
-## Patch
-
-The `patch` function returned by `app(...)` is a function that can be passed an object called `Patch` this object is used to update the state and re-render the UI. It takes a `Patch` object that describes the changes to be made to the state in a "trickle down manner". The `Patch` can be a simple object or a function that returns a new `Patch` to the current state. It can also be an async and/or genrator function that yields `Patch`es. Events also can return a `Patch`. When a number | boolean | string | null | undefined is applied as a `Patch`, it will be ignored.
-
-## Usage
-
 index.html
-
 ```html
 <html>
 <head>
@@ -39,8 +245,6 @@ index.html
 
 main.ts
 ```ts
-// import { app, createState} from 'vode.js';
-// import { BR, DIV, INPUT, SPAN } from 'vode-tags.js';
 import { app, createState, BR, DIV, INPUT, SPAN } from '@ryupold/vode';
 
 
@@ -65,70 +269,13 @@ app<State>(appNode, init,
 );
 ```
 
-## Claude
-
-> Prompt: "what can you tell me about the overall design philosophy of the vode library based on what you see in `src/vode.ts`"
-
-
-Based on my analysis of `src/vode.ts`, here's the overall design philosophy of the vode library:
-
-### Core Design Philosophy
-
-**Functional Virtual DOM with Minimal Abstractions**
-- Uses array-based virtual nodes (`[tag, props?, ...children]`) instead of object-based structures
-- Prioritizes simplicity and performance over complex abstractions
-
-**State-Centric Architecture**
-- Central state object with patch-based updates
-- Immutable-style state management with deep merging
-- Single source of truth pattern
-
-**Zero-Dependency Minimalism**
-- Pure TypeScript/JavaScript implementation
-- No external dependencies or build tools required
-- Direct DOM manipulation without heavy runtime
-
-### Key Architectural Decisions
-
-#### Virtual DOM Structure
-```typescript
-// Simple array-based nodes
-["div", { class: "container" }, "Hello", ["span", "World"]]
-```
-- Minimal memory footprint
-- Easy serialization/debugging
-- Type-safe with TypeScript generics
-
-#### Reactive State Management
-```typescript
-state.patch(newData)           // Direct updates
-state.patch([effect, payload]) // Function-based effects
-state.patch(promise)           // Async support
-```
-- Unified patch system for all state changes
-- Built-in async/generator support
-- Functional effects pattern
-
-#### Performance Optimizations
-- **Memoization**: `memo()` for component caching
-- **Reconciliation**: Intelligent DOM diffing
-- **Batched Updates**: RequestAnimationFrame-based rendering
-- **Memory Management**: Proper cleanup with mount/unmount hooks
-
-#### Developer Experience
-- **Type Safety**: Full TypeScript support with generics
-- **Debugging**: Built-in performance statistics
-- **Flexibility**: Support for HTML, SVG, and MathML
-- **Composability**: Functional component model
+## Contributing
 
-### Philosophy Summary
+I was delighted by the simplicity of [hyperapp](https://github.com/jorgebucaran/hyperapp), which inspired me to create this library. 
 
-Vode follows a **"less is more"** philosophy, providing a lightweight alternative to heavyweight frameworks while maintaining modern reactive patterns. It emphasizes:
+Not planning to add more features, just keeping it simple and easy.
 
-1. **Explicitness over magic** - Clear, predictable behavior
-2. **Performance by design** - Minimal overhead, efficient updates
-3. **Developer control** - Direct state manipulation without hidden abstractions
-4. **Functional paradigms** - Immutable updates, pure components
-5. **Modern web standards** - Leverages native browser APIs effectively
+But if you find bugs or have suggestions, feel free to open an [issue](https://github.com/ryupold/vode/issues) or a pull request.
 
-The library appears designed for developers who want React-like reactivity without the complexity and bundle size of modern frameworks.
+## License
+[MIT](./LICENSE)