sygnal 4.6.0 → 5.0.0

package/README.md

@@ -1,25 +1,25 @@
 # Sygnal
 
-An intuitive framework for building fast, small and composable components or applications.
+A reactive component framework with pure functions, zero side effects, and automatic state management.
 
-Sygnal is built on top of [Cycle.js](https://cycle.js.org/), and allows you to write functional reactive, Observable based, components with fully isolated side-effects without having to worry about the complex plumbing usually associated with functional reactive programming.
+[![npm version](https://img.shields.io/npm/v/sygnal.svg?style=flat-square)](https://www.npmjs.com/package/sygnal)
+[![npm downloads](https://img.shields.io/npm/dm/sygnal.svg?style=flat-square)](https://www.npmjs.com/package/sygnal)
+[![license](https://img.shields.io/npm/l/sygnal.svg?style=flat-square)](https://github.com/tpresley/sygnal/blob/main/LICENSE)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/sygnal?style=flat-square&label=bundle%20size)](https://pkg-size.dev/sygnal)
 
-Components and applications written using Sygnal look similar to React functional components, and can be nested just as easily, but have many benefits including:
-- 100% pure components with absolutely no side effects
-- No need for component state management (it's handled automatically at the application level)
-- Small bundle sizes
-- Fast build times
-- Fast rendering
-- Close to zero boiler plate code
+---
 
-## Documentation
+## Why Sygnal?
 
-- **[Getting Started](./docs/getting-started.md)** — Installation, setup, and your first interactive component
-- **[Guide](./docs/guide.md)** — In-depth coverage of all features: state, MVI, collections, drivers, context, TypeScript, and more
-- **[API Reference](./docs/api-reference.md)** — Complete reference for all exports, types, and configuration options
+- **Pure components** — Views are plain functions. All side effects are handled by drivers, outside your code.
+- **Automatic state management** — Monolithic state tree with no store setup, no providers, no hooks. Trivial undo/redo and time-travel debugging.
+- **Model-View-Intent** — Cleanly separate *what* happens (Model), *when* it happens (Intent), and *how* it looks (View).
+- **Tiny footprint** — Three runtime dependencies: [snabbdom](https://github.com/snabbdom/snabbdom), [xstream](https://github.com/staltz/xstream), and [extend](https://github.com/nicjohnson145/extend).
 
 ## Quick Start
 
+**Scaffold a new project:**
+
 ```bash
 npx degit tpresley/sygnal-template my-app
 cd my-app
@@ -27,15 +27,15 @@ npm install
 npm run dev
 ```
 
-Or install manually:
+**Or add to an existing project:**
 
 ```bash
 npm install sygnal
 ```
 
-## In a Nutshell
+## A Sygnal Component
 
-A Sygnal component is a function (the **view**) with static properties that define **when** things happen (`.intent`) and **what** happens (`.model`):
+A component is a function (the **view**) with static properties that define **when** things happen (`.intent`) and **what** happens (`.model`):
 
 ```jsx
 function Counter({ state }) {
@@ -50,20 +50,18 @@ function Counter({ state }) {
 
 Counter.initialState = { count: 0 }
 
-// Intent: WHEN things happen
 Counter.intent = ({ DOM }) => ({
   INCREMENT: DOM.select('.increment').events('click'),
-  DECREMENT: DOM.select('.decrement').events('click')
+  DECREMENT: DOM.select('.decrement').events('click'),
 })
 
-// Model: WHAT happens
 Counter.model = {
-  INCREMENT: (state) => ({ count: state.count + 1 }),
-  DECREMENT: (state) => ({ count: state.count - 1 })
+  INCREMENT: (state) => ({ ...state, count: state.count + 1 }),
+  DECREMENT: (state) => ({ ...state, count: state.count - 1 }),
 }
 ```
 
-Start it with `run()`:
+Start it:
 
 ```javascript
 import { run } from 'sygnal'
@@ -72,54 +70,105 @@ import Counter from './Counter.jsx'
 run(Counter)
 ```
 
-That's it. No store setup, no providers, no hooks — just a function and some properties.
+No store setup, no providers, no hooks — just a function and some properties.
 
-## Built on Cycle.js
+## Features
 
-Sygnal is built on top of Cycle.js which is a functional reactive coding framework that asks "what if the user was a function?"
+### Collections
 
-It is worth reading the summary on the [Cycle.js homepage](https://cycle.js.org/), but essentially Cycle.js allows you to write simple, concise, extensible, and testable code using a functional reactive style, and helps ensure that all side-effects are isolated away from your component code.
+Render dynamic lists with built-in filtering and sorting:
+
+```jsx
+<Collection of={TodoItem} from="items" filter={item => !item.done} sort="name" />
+```
 
-Sygnal takes it a step further, and makes it easy to write arbitrarily complex applications that have all of the Cycle.js benefits, but with a much easier learning curve, and virtually no complex plumbing or boiler plate code.
+### Switchable
 
-## Key Features
+Swap between components based on state:
 
-### Model-View-Intent Architecture
+```jsx
+<Switchable of={{ home: HomePage, settings: SettingsPage }} current={state.activeTab} />
+```
 
-Separate **what** your component does (Model), **when** it does it (Intent), and **how** it's displayed (View). All side effects are delegated to drivers, keeping your components 100% pure.
+### Context
 
-### Monolithic State
+Top-down data propagation without prop drilling:
 
-Automatic application-level state management with no setup. Trivial undo/redo, state restoration, and time-travel debugging.
+```jsx
+App.context = {
+  theme: (state) => state.settings.theme,
+  currentUser: (state) => state.auth.user,
+}
 
-### Collections
+function Child({ state, context }) {
+  return <div className={context.theme}>{context.currentUser.name}</div>
+}
+```
+
+### Parent-Child Communication
 
-Render dynamic lists with filtering and sorting built in:
+Structured message passing between components:
 
 ```jsx
-<collection of={TodoItem} from="items" filter={item => !item.done} sort="name" />
+// Child emits
+TaskCard.model = {
+  DELETE: { PARENT: (state) => ({ type: 'DELETE', taskId: state.id }) }
+}
+
+// Parent receives (use component reference — minification-safe)
+Lane.intent = ({ CHILD }) => ({
+  TASK_DELETED: CHILD.select(TaskCard).filter(e => e.type === 'DELETE'),
+})
 ```
 
-### Switchable Components
+### Event Bus
 
-Swap between components based on state:
+Global broadcast for cross-component communication:
 
 ```jsx
-<switchable of={{ home: HomePage, settings: SettingsPage }} current={state.activeTab} />
+// Any component can emit
+Publisher.model = {
+  NOTIFY: { EVENTS: (state) => ({ type: 'notification', data: state.message }) }
+}
+
+// Any component can subscribe
+Subscriber.intent = ({ EVENTS }) => ({
+  HANDLE: EVENTS.select('notification'),
+})
 ```
 
-### Form Handling
+### Calculated Fields
 
-Extract form values without the plumbing:
+Derived state with optional dependency tracking:
 
 ```jsx
-import { processForm } from 'sygnal'
+Invoice.calculated = {
+  subtotal: [['items'], (state) => sum(state.items.map(i => i.price))],
+  tax:      [['subtotal'], (state) => state.subtotal * 0.08],
+  total:    [['subtotal', 'tax'], (state) => state.subtotal + state.tax],
+}
+```
+
+### Form Handling
 
+Extract form values without the boilerplate:
+
+```jsx
 MyForm.intent = ({ DOM }) => ({
-  SUBMITTED: processForm(DOM.select('.my-form'), { events: 'submit' })
+  SUBMITTED: processForm(DOM.select('.my-form'), { events: 'submit' }),
 })
 ```
 
+### Drag and Drop
+
+HTML5 drag-and-drop with a dedicated driver:
+
+```javascript
+import { makeDragDriver } from 'sygnal'
+
+run(RootComponent, { DND: makeDragDriver() })
+```
+
 ### Custom Drivers
 
 Wrap any async operation as a driver:
@@ -135,6 +184,146 @@ const apiDriver = driverFromAsync(async (url) => {
 run(RootComponent, { API: apiDriver })
 ```
 
+### Error Boundaries
+
+Catch and recover from rendering errors:
+
+```jsx
+BrokenComponent.onError = (error, { componentName }) => (
+  <div>Something went wrong in {componentName}</div>
+)
+```
+
+### Portals
+
+Render children into a different DOM container:
+
+```jsx
+<Portal target="#modal-root">
+  <div className="modal">Modal content</div>
+</Portal>
+```
+
+### Slots
+
+Pass named content regions to child components:
+
+```jsx
+import { Slot } from 'sygnal'
+
+<Card state="card">
+  <Slot name="header"><h2>Title</h2></Slot>
+  <Slot name="actions"><button>Save</button></Slot>
+  <p>Default content</p>
+</Card>
+
+// In Card's view:
+function Card({ state, slots }) {
+  return (
+    <div>
+      <header>{...(slots.header || [])}</header>
+      <main>{...(slots.default || [])}</main>
+      <footer>{...(slots.actions || [])}</footer>
+    </div>
+  )
+}
+```
+
+### Transitions
+
+CSS-based enter/leave animations:
+
+```jsx
+<Transition name="fade" duration={300}>
+  {state.visible && <div>Animated content</div>}
+</Transition>
+```
+
+### Lazy Loading & Suspense
+
+Code-split components with loading boundaries:
+
+```jsx
+const HeavyChart = lazy(() => import('./HeavyChart.jsx'))
+
+<Suspense fallback={<div>Loading...</div>}>
+  <HeavyChart />
+</Suspense>
+```
+
+### Refs
+
+Access DOM elements declaratively:
+
+```jsx
+const inputRef = createRef()
+<input ref={inputRef} />
+// inputRef.current.focus()
+```
+
+### Commands
+
+Send imperative commands from parent to child:
+
+```jsx
+import { createCommand } from 'sygnal'
+
+const playerCmd = createCommand()
+<VideoPlayer commands={playerCmd} />
+
+// Parent sends commands with optional data
+playerCmd.send('seek', { time: 30 })
+
+// Child receives via commands$ source
+VideoPlayer.intent = ({ commands$ }) => ({
+  SEEK: commands$.select('seek'),  // emits { time: 30 }
+})
+```
+
+### Effect Handlers
+
+Run side effects without state changes — no more `ABORT` workarounds:
+
+```jsx
+App.model = {
+  SEND_COMMAND: {
+    EFFECT: () => playerCmd.send('play'),
+  },
+  ROUTE: {
+    EFFECT: (state, data, next) => {
+      if (state.mode === 'a') next('DO_A', data)
+      else next('DO_B', data)
+    },
+  },
+}
+```
+
+### Model Shorthand
+
+Compact syntax for single-driver model entries:
+
+```jsx
+App.model = {
+  'SEND_CMD | EFFECT': () => playerCmd.send('play'),
+  'NOTIFY | EVENTS': (state) => ({ type: 'alert', data: state.message }),
+  'DELETE | PARENT': (state) => ({ type: 'DELETE', id: state.id }),
+}
+```
+
+### Disposal Hooks
+
+Cleanup on unmount:
+
+```jsx
+MyComponent.intent = ({ dispose$ }) => ({
+  CLEANUP: dispose$,
+})
+
+MyComponent.model = {
+  CLEANUP: { WEBSOCKET: () => ({ type: 'close' }) },
+}
+```
+
 ### Hot Module Replacement
 
 State-preserving HMR out of the box:
@@ -150,6 +339,8 @@ if (import.meta.hot) {
 
 ### Astro Integration
 
+First-class Astro support with server rendering and client hydration:
+
 ```javascript
 // astro.config.mjs
 import sygnal from 'sygnal/astro'
@@ -163,24 +354,24 @@ import Counter from '../components/Counter.jsx'
 <Counter client:load />
 ```
 
-### TypeScript Support
+### TypeScript
 
 Full type definitions included:
 
 ```tsx
 import type { RootComponent } from 'sygnal'
 
-type AppState = { count: number }
-type AppActions = { INCREMENT: null }
+type State = { count: number }
+type Actions = { INCREMENT: null }
 
-const App: RootComponent<AppState, {}, AppActions> = ({ state }) => (
+const App: RootComponent<State, {}, Actions> = ({ state }) => (
   <div>{state.count}</div>
 )
 ```
 
-## Bundler Setup (JSX)
+## Bundler Setup
 
-For Vite:
+**Vite** (recommended):
 
 ```javascript
 // vite.config.js
@@ -188,11 +379,11 @@ export default defineConfig({
   esbuild: {
     jsx: 'automatic',
     jsxImportSource: 'sygnal',
-  }
+  },
 })
 ```
 
-For TypeScript projects, also add to `tsconfig.json`:
+For TypeScript projects, add to `tsconfig.json`:
 
 ```json
 {
@@ -203,25 +394,34 @@ For TypeScript projects, also add to `tsconfig.json`:
 }
 ```
 
-Without JSX, use `h()`:
+Without JSX, use `h()` directly:
 
 ```javascript
 import { h } from 'sygnal'
 h('div', [h('h1', 'Hello'), h('button.btn', 'Click')])
 ```
 
-See the [Guide](./docs/guide.md#bundler-configuration) for other bundlers.
+## Documentation
+
+📖 **[sygnal.js.org](https://sygnal.js.org)** — Full guide, API reference, and examples.
 
 ## Examples
 
-- **[HMR Smoke Test](./examples/hmr-smoke)** — Minimal counter with HMR
-- **[TypeScript 2048](./examples/ts-example-2048)** — Full game in TypeScript
-- **[AI Discussion Panel](./examples/ai-panel-spa)** — Complex SPA with custom drivers
-- **[Astro Integration](./examples/astro-smoke)** — Sygnal in Astro
-- **[Sygnal ToDoMVC](https://github.com/tpresley/sygnal-todomvc)** ([Live Demo](https://tpresley.github.io/sygnal-todomvc/)) — TodoMVC implementation
-- **[Sygnal 2048](https://github.com/tpresley/sygnal-2048)** ([Live Demo](https://tpresley.github.io/sygnal-2048/)) — 2048 game
-- **[Sygnal Calculator](https://github.com/tpresley/sygnal-calculator)** ([Live Demo](https://tpresley.github.io/sygnal-calculator/)) — Simple calculator
+| Example | Description |
+|---------|-------------|
+| [Getting Started](./examples/getting-started) | Interactive guide with live demos (Astro) |
+| [Kanban Board](./examples/kanban) | Drag-and-drop with Collections and cross-component communication |
+| [Advanced Features](./examples/advanced-feature-tests) | Portals, slots, disposal, suspense, lazy loading |
+| [TypeScript 2048](./examples/ts-example-2048) | Full game in TypeScript |
+| [AI Discussion Panel](./examples/ai-panel-spa) | Complex SPA with custom drivers |
+| [Sygnal ToDoMVC](https://github.com/tpresley/sygnal-todomvc) | [Live Demo](https://tpresley.github.io/sygnal-todomvc/) |
+| [Sygnal 2048](https://github.com/tpresley/sygnal-2048) | [Live Demo](https://tpresley.github.io/sygnal-2048/) |
+| [Sygnal Calculator](https://github.com/tpresley/sygnal-calculator) | [Live Demo](https://tpresley.github.io/sygnal-calculator/) |
+
+## Acknowledgments
+
+Sygnal's reactive architecture is built on patterns from [Cycle.js](https://cycle.js.org/) by [André Staltz](https://github.com/staltz). The Cycle.js runtime, DOM driver, state management, and isolation modules have been absorbed into the library — snabbdom, xstream, and extend are the only external dependencies.
 
 ## License
 
-MIT
+[MIT](./LICENSE)