neo.mjs 10.0.0-beta.6 → 10.0.0

package/learn/blog/v10-deep-dive-functional-components.md

@@ -0,0 +1,293 @@
+# Beyond Hooks: A New Breed of Functional Components for a Multi-Threaded World
+
+If you're a seasoned React developer, you've mastered the art of hooks. You know how to build complex, stateful UIs with
+`useState`, `useEffect`, and `useMemo`. You also know the trade-offs—the intricate dependency arrays, the constant battle
+against unnecessary re-renders, and the "memoization tax" you pay to keep your application performant.
+
+We've been taught that these trade-offs are fundamental to the functional component model. But what if they aren't?
+What if they are merely symptoms of a single-threaded architecture?
+
+This article will show you a new breed of functional component, born from a multi-threaded world, that eliminates these
+compromises by design. We didn't build them to copy other frameworks; we built them because our architecture unlocked a
+better way to write UIs.
+
+*(Part 3 of 5 in the v10 blog series. Details at the bottom.)*
+
+### A First Look: The Anatomy of a Neo.mjs Functional Component
+
+Before we dive into the "why," let's look at the "what." Here is a simple, complete, and reactive functional component
+in Neo.mjs. Keep this structure in mind as we explore how it solves the problems you've come to accept as normal.
+
+```javascript
+import {defineComponent, useConfig, useEvent} from 'neo.mjs';
+
+export default defineComponent({
+    // The component's public API (like props)
+    config: {
+        className: 'My.Counter',
+        labelText_: 'Counter:'
+    },
+
+    // The function that creates the VDOM
+    createVdom(config) {
+        // Internal, private state (like useState)
+        const [count, setCount] = useConfig(0);
+
+        // An event listener that updates the private state
+        useEvent('click', () => setCount(prev => prev + 1));
+
+        return {
+            tag: 'button',
+            cn: [
+                {tag: 'span', text: config.labelText},
+                {tag: 'span', cls: ['count-badge'], text: count}
+            ]
+        }
+    }
+});
+```
+
+Notice what's missing: there are no dependency arrays, no `memo` wrappers, and no `useCallback` hooks. Now, let's explore
+the architecture that makes this clean, simple code possible.
+
+---
+
+### The Architectural Divide: Why Your Component's Environment Matters
+
+Before we deconstruct the problems, we have to address the fundamental difference that changes everything. In a
+traditional framework like React, your component function, its state, its reconciliation (diffing), and its DOM
+manipulation all happen on the **same main thread** that is responsible for user interactions.
+
+In Neo.mjs, the architecture is fundamentally different:
+
+1.  **Your Application Logic (including your component's `createVdom` function) runs in a dedicated App Worker.**
+2.  **The VDOM diffing happens in a separate VDom Worker.**
+3.  **The Main Thread is left with one primary job: applying the calculated DOM patches.**
+
+This isn't just a minor difference; it's a paradigm shift. Your component code is decoupled from the rendering engine,
+which allows for a level of performance and predictability that is architecturally impossible on the main thread.
+With this in mind, let's see how this new architecture solves old problems.
+
+---
+
+### Deconstructing the "React Tax": How a New Architecture Solves Old Problems
+
+Let's tackle the compromises you've learned to live with, one by one, and show how a multi-threaded architecture solves
+them at their root.
+
+#### 1. The Problem: Cascading Re-Renders & The `memo` Tax
+
+**The React Way:** You know the drill. A state change in a parent component triggers a re-render. By default, React then
+re-renders **all of its children**, whether their props have changed or not. To prevent this performance drain,
+you are forced to pay the `memo` tax: wrapping components in `React.memo()`, manually memoizing functions with
+`useCallback()`, and objects with `useMemo()`. This manual optimization becomes a core, and often frustrating,
+part of the development process.
+
+```javascript
+// A typical "optimized" React component
+const MyComponent = React.memo(({ onButtonClick, user }) => {
+  console.log('Rendering MyComponent');
+  return <button onClick={onButtonClick}>{user.name}</button>;
+});
+
+const App = () => {
+  const [count, setCount] = useState(0);
+
+  // We must wrap this in useCallback to prevent MyComponent from re-rendering
+  // every time the App component's state changes.
+  const handleClick = useCallback(() => {
+    console.log('Button clicked!');
+  }, []);
+
+  // We must wrap this in useMemo to ensure the object reference is stable.
+  const user = useMemo(() => ({ name: 'John Doe' }), []);
+
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>App Clicks: {count}</button>
+      <MyComponent onButtonClick={handleClick} user={user} />
+    </div>
+  );
+};
+```
+
+**The Neo.mjs Solution: Surgical Effects, Not Brute-Force Renders**
+
+Our `createVdom` method is a surgical `Effect`. It automatically and precisely tracks every piece of reactive state it reads.
+When a piece of state changes, **only the specific `createVdom` effects that depend on that exact piece of state are queued
+for re-execution.**
+
+There are no cascading re-renders. If a parent's `createVdom` re-runs, but the configs passed to a child have not changed,
+the child component's `createVdom` function is **never executed**. 
+
+This means `memo`, `useCallback`, and `useMemo` are not needed. The architecture is efficient by default, eliminating an
+entire class of performance optimizations and bugs.
+
+#### 2. The Problem: The Boilerplate of Immutability
+
+**The React Way:** To change a nested object in React state, you have to meticulously reconstruct the object path with
+spread syntax (`...`), creating new references for every level. This is required to signal to React's diffing algorithm
+that something has changed.
+
+```javascript
+// The familiar immutable update dance
+setState(prevState => ({
+  ...prevState,
+  deeply: {
+    ...prevState.deeply,
+    nested: {
+      ...prevState.deeply.nested,
+      property: 'new value'
+    }
+  }
+}));
+```
+
+**The Neo.mjs Solution: Mutability for You, Immutability for the Machine**
+
+We believe the developer should not carry this cognitive load. In Neo.mjs, you can just mutate the state directly.
+It's simple and intuitive.
+
+```javascript
+// Just change the value. That's it.
+this.myObject.deeply.nested.property = 'new value';
+```
+
+How does it work? When an update is triggered, the framework handles creating an immutable JSON snapshot of the VDOM for
+the diffing process in the VDom Worker. We provide the best of both worlds: simple, direct mutation for the developer
+and a safe, immutable structure for the high-performance diffing algorithm.
+
+#### 3. The Problem: The "SSR and Hydration is the ONLY way" Mindset
+
+**The React/Next.js Way:** The industry has invested heavily in Server-Side Rendering and hydration to improve perceived
+performance and SEO. For content-heavy sites, this is a valid strategy. But for complex, stateful Single-Page Applications,
+it introduces immense complexity: the "hydration crisis," the difficulty of managing server vs. client components, and
+the fact that after all that work, your application is *still* running on the client's main thread.
+
+**The Neo.mjs Solution: Blueprints, Not Dehydrated HTML**
+
+We offer a more robust and scalable model for SPAs. Instead of sending pre-rendered HTML that needs to be brought back
+to life, we can send a compact **JSON blueprint**. The client-side engine, running in a worker, constructs the live,
+interactive UI from this blueprint. This is a more efficient, more predictable, and architecturally cleaner way to build
+complex applications that are not primarily focused on static content.
+
+---
+
+### The "WOW" Effect: Building a Real Application
+
+The simple counter example is a great start, but the true power of functional components is revealed when you build a
+complete, interactive application. Let's build a slightly more advanced "Task List" application to demonstrate how all
+the pieces come together.
+
+This example will showcase:
+- **Component Composition:** Using a class-based `List` component within our functional view.
+- **State Management:** Tracking the currently selected task.
+- **Conditional Rendering:** Displaying task details only when a task is selected.
+- **Event Handling:** Updating state based on events from a child component.
+
+Here is the complete, interactive example.
+
+```javascript live-preview
+import {defineComponent, useConfig} from 'neo.mjs';
+import List from 'neo.mjs/src/list/Base.mjs';
+import Store from 'neo.mjs/src/data/Store.mjs';
+
+// 1. Define a simple data Store for our list
+const TaskStore = Neo.create(Store, {
+    data: [
+        {id: 1, title: 'Build a better component model', description: 'Re-imagine what a component can be when freed from the main thread.'},
+        {id: 2, title: 'Create a new reactivity system', description: 'Design a two-tier system that is both powerful and intuitive.'},
+        {id: 3, title: 'Revolutionize the VDOM',         description: 'Build an asymmetric, off-thread VDOM engine for maximum performance.'}
+    ]
+});
+
+// 2. Define our main application view
+export default defineComponent({
+    config: {
+        className: 'My.TaskListApp',
+        layout: {ntype: 'hbox', align: 'stretch'}
+    },
+    createVdom() {
+        // 3. Manage the selected task with useConfig
+        const [selectedTask, setSelectedTask] = useConfig(null);
+
+        const onSelectionChange = ({value}) => {
+            // 4. Update our state when the list selection changes
+            setSelectedTask(TaskStore.get(value[0]));
+        };
+
+        const paneStyle = {
+            border : '1px solid #c0c0c0',
+            margin : '10px',
+            padding: '10px'
+        };
+
+        return {
+            cn: [{
+                // 5. The List Component
+                module   : List,
+                store    : TaskStore,
+                width    : 250,
+                style    : paneStyle,
+                listeners: {
+                    selectionChange: onSelectionChange
+                }
+            }, {
+                // 6. The Details Pane (with conditional rendering)
+                flex: 1,
+                style: paneStyle,
+                cn: selectedTask ? [
+                    {tag: 'h2', text: selectedTask.title},
+                    {tag: 'p',  text: selectedTask.description}
+                ] : [{
+                    tag  : 'div',
+                    style: {color: '#888'},
+                    text : 'Please select a task to see the details.'
+                }]
+            }]
+        }
+    }
+});
+```
+
+This single `defineComponent` call creates a fully-featured application. Notice how the `createVdom` function is a pure,
+declarative representation of the UI. When the `selectedTask` state changes, the framework surgically re-renders only
+the details pane. This is the power of the new component model in action: complex, stateful, and performant applications
+with beautifully simple code.
+
+---
+
+### The AI Connection: The Inevitable Next Step
+
+This blueprint-first, surgically reactive, and mutable-by-default model isn't just better for you; it's the architecture
+an AI would choose. An AI can easily generate and manipulate a structured JSON blueprint, but it struggles to generate
+flawless, complex JSX. By building on these principles, you are not just using a new framework; you are future-proofing
+your skills for the AI era.
+
+---
+
+### Conclusion: A Different Philosophy, A Better Component
+
+Neo.mjs functional components are not a "React clone." They are a re-imagining of what a functional component can be
+when freed from the architectural constraints of the main thread. They offer a development experience that is not only
+more performant by default but also simpler, more intuitive, and ready for the AI-driven future of the web.
+
+This is what it feels like to stop paying the performance tax and start building again.
+
+The clean, hook-based API for functional components is possible because it stands on the shoulders of a robust, modular,
+and deeply integrated class system. We've engineered the framework's core to handle the complex machinery of reactivity
+and lifecycle management automatically. To learn more about the powerful engine that makes this all possible, see our
+deep dive on the **Two-Tier Reactivity System**.
+
+Next, we will look at how this architecture revolutionizes the very way we render UIs with the Asymmetric VDOM
+and JSON Blueprints.
+
+---
+
+## The Neo.mjs v10 Blog Post Series
+
+1. [A Frontend Love Story: Why the Strategies of Today Won't Build the Apps of Tomorrow](./v10-post1-love-story.md)
+2. [Deep Dive: Named vs. Anonymous State - A New Era of Component Reactivity](./v10-deep-dive-reactivity.md)
+3. Beyond Hooks: A New Breed of Functional Components for a Multi-Threaded World
+4. [Deep Dive: The VDOM Revolution - JSON Blueprints & Asymmetric Rendering](./v10-deep-dive-vdom-revolution.md)
+5. [Deep Dive: The State Provider Revolution](./v10-deep-dive-state-provider.md)