sibujs 3.4.0 → 4.0.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Fran Ramírez
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Fran Ramírez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,16 +2,27 @@
 
 A lightweight, function-based frontend framework with fine-grained reactivity, direct DOM rendering, and zero compilation. **No Virtual DOM. No magic.**
 
-[[NPM Version]](https://www.npmjs.com/package/sibujs)
-[[License]](https://github.com/hexplus/sibujs/blob/main/LICENSE)
+[NPM](https://www.npmjs.com/package/sibujs) · [License](https://github.com/hexplus/sibujs/blob/main/LICENSE)
 
 ## Why SibuJS?
 
-- **Zero VDOM:** Updates only what changes, directly in the DOM.
-- **Function-Based:** Components are just plain functions. No classes, no complex life cycles.
-- **Fine-Grained Reactivity:** Powered by lightweight signals.
-- **No Build Step Required:** Works natively in the browser, but includes a Vite plugin for advanced optimizations.
-- **Modular & Lean:** Core is minimal; features like Router and i18n are optional plugins.
+- **Zero VDOM:** No Virtual DOM and no component-tree reconciliation. Reactive bindings update their exact DOM targets directly; keyed collections reconcile only their own DOM range.
+- **Function-Based:** Components are plain functions returning nodes. No classes, no hooks rules, no compiler-only syntax.
+- **Fine-Grained Reactivity:** `signal`, `derived`, and `effect` track dependencies automatically and update at the value level.
+- **No Build Step Required:** Runs natively in the browser (or via a `<script>` tag), with an optional Vite plugin for template compilation and other build-time optimizations.
+- **Modular & Lean:** The core stays small; every advanced capability ships as a tree-shakeable subpath import, so you pay only for what you use.
+- **Full-Featured:** When you need more, it's already there — router, i18n, SSR with streaming and hydration, islands & progressive enhancement, data fetching, state machines, and reactive wrappers for dozens of browser APIs.
+- **TypeScript-First:** Written in TypeScript with typed props for common elements and full type inference across signals and components.
+
+## Requirements
+
+- **Node.js ≥ 22.3.0** for SSR and tooling. Node 18 and 20 are not supported —
+  both are end-of-life, and SSR request isolation depends on
+  `process.getBuiltinModule`, added in 22.3.
+- **Browsers:** Chrome/Edge ≥ 93, Firefox ≥ 92, Safari ≥ 15.4. The floor is what
+  the source actually requires (`Object.hasOwn`, `ParentNode.replaceChildren`
+  and `new Error(msg, { cause })`), enforced by a build gate rather than only
+  documented.
 
 ## Quick Start
 
@@ -90,15 +101,107 @@ For full documentation, guides, and advanced examples, visit our official websit
 
 ---
 
-## Features at a Glance
+## Core (`sibujs`)
+
+The lean core: reactivity, rendering, and components. Everything below imports from the root.
+
+### Reactivity
+- **`signal`** — reactive value returned as a `[get, set]` tuple; reads inside effects auto-track.
+- **`derived`** — memoized value computed from other signals.
+- **`asyncDerived`** — derived value from an async computation, with loading/error state.
+- **`effect`** — run a side effect whenever its tracked dependencies change.
+- **`watch`** — observe specific sources and react to their new/old values.
+- **`batch`** — group multiple updates into a single flush.
+- **`untracked` / `retrack`** — read signals without subscribing, or re-enable tracking.
+- **`store`** — simple keyed state container.
+- **`deepSignal`** — deep reactive proxy over nested objects/arrays.
+- **`reactiveArray`** — reactive array with fine-grained item tracking.
+- **`writable`** — writable derived (two-way computed).
+- **`ref`** — hold a DOM element or mutable value.
+- **`nextTick`** — await the next reactive flush.
+
+### Rendering & Control Flow
+- **HTML/SVG tag factories** — `div`, `span`, `button`, … and SVG tags with the correct namespace.
+- **`mount`** — render a component into a DOM node.
+- **`html`** — tagged-template authoring (compiler-free, legacy-friendly).
+- **`when`** — conditionally swap subtrees; **`show`** — toggle visibility without unmounting.
+- **`each`** — efficient keyed list rendering (LIS-based diffing).
+- **`match`** — pattern-matching over a value to pick a branch.
+- **`Fragment`** — group children without a wrapper element.
+- **`Portal`** — render a subtree elsewhere in the DOM.
+- **`DynamicComponent`** — render a component chosen at runtime.
+- **`lazy` / `Suspense`** — code-split async components with a fallback.
+- **`slot` / `getSlot`** — named content slots.
+- **`KeepAlive`** — cache and preserve unmounted subtrees.
+- **Directives** — `clickOutside`, `longPress`, `copyOnClick`, `autoResize`, `trapFocus`.
+- **`action`** — register reusable element behaviors.
+
+### Components & Lifecycle
+- **Functional components** — plain functions returning nodes.
+- **Lifecycle** — `onMount`, `onUnmount`, `onCleanup`.
+- **`context`** — dependency injection down the tree.
+- **`ErrorBoundary` / `ErrorDisplay`** — catch and render render-time errors.
+- **`Loading`** — standard loading placeholder.
+- **`catchError` / `catchErrorAsync`** — scoped error handling helpers.
+
+### Islands & Progressive Enhancement
+- **`enhance` / `enhanceAll`** — attach fine-grained reactivity to existing server-rendered HTML with no build step (the third rendering mode alongside `mount` and `hydrate`).
+- **`island` / `registerIsland` / `hydrateIslands`** — hydrate isolated interactive regions on demand.
+
+---
+
+## Subpath Modules
+
+Import advanced features from focused entry points for optimal tree-shaking. `sibujs/extras` re-exports all of them for convenience.
+
+### `sibujs/data` — Data fetching & realtime
+`query` (cached async fetching), `mutation`, `infiniteQuery`, `resource`, `routeLoader`, `offlineStore`, `retry`, `debounce`, `throttle`, `previous`, plus `socket` and `stream` for realtime connections.
+
+### `sibujs/browser` — Reactive browser APIs
+Reactive wrappers for `media` queries, `resize`, `scroll`, `online`/`network`, `geo`, `battery`, `idle`, `permissions`, `clipboard`, `dragDrop`, `title`/`favicon`, `colorScheme`, `visibility`, `mouse`/`swipe`, `windowSize`, `urlState`, `broadcast`, `fullscreen`, `wakeLock`, `animationFrame`, `mutationObserver`, `bounds`, `keyboard`, `speech`, `gamepad`, `pointerLock`, `vibrate`, `textSelection`, `imageLoader`, and `format`.
+
+### `sibujs/ui` — UI utilities
+`form` & `formAction` (validation/binding), `virtualList`, `intersection`, `inputMask`, `a11y` / `a11yPrimitives`, `scopedStyle`, `reactiveAttr`, `dialog`, `toast`, `infiniteScroll`, `pagination`, `eventBus`, `timers`, `hover`, `scrollLock`, `lazyEffect`, plus composable/HOC patterns.
+
+### `sibujs/widgets` — Pre-built components
+Accessible `Combobox`, `Tabs`, `Accordion`, `Popover`, `Select`, `Tooltip`, `FileUpload`, `contentEditable`, and `datePicker`.
+
+### `sibujs/motion` — Transitions & animation
+`transition`, `TransitionGroup`, `animationPresets`, `viewTransition`, `springSignal`, and `reducedMotion`.
 
-- **Reactivity:** `signal`, `effect`, `derived`, `watch`, `batch`.
-- **Components:** Functional, reusable, and lifecycle-aware (`onMount`, `onUnmount`).
-- **Control Flow:** `when` (conditional swaps), `each` (efficient keyed lists), `match` (pattern matching), `show` (toggle visibility).
-- **DOM Utilities:** `Portal` (render out-of-tree), `Fragment` (group children), `Suspense` & `lazy` (async components), `ErrorBoundary`.
-- **State Management:** `store` (simple state containers), `deepSignal` (object proxies), `ref`.
-- **Performance:** Zero VDOM overhead, LIS-based list diffing, and optional template compilation.
-- **Plugins:** Official Router (nested routes, guards), i18n (reactive translations), logic patterns (Finite State Machines).
+### `sibujs/patterns` — State & component patterns
+`machine` (finite state machines), `persist`, `optimistic`, `timeTravel`, `globalStore`; plus `hoc`, `composable`, `componentProps`, and `contracts`.
+
+### `sibujs/plugins` — First-party plugins
+**Router** — `createRouter`, `Route`/`Outlet`/`RouterLink`, nested routes, guards (`beforeEach`, `beforeResolve`, `afterEach`), programmatic navigation, `preloadRoute`, memory router, and per-route transitions. **i18n** — `setLocale`, `t`, `Trans`, `registerTranslations`, reactive locale switching. Plus the plugin system (`modular`, `ecosystem`, `versioning`, `startup`).
+
+### `sibujs/ssr` — Server rendering
+`renderToString`, `renderToReadableStream`, `renderToDocument`, `hydrate`, streaming `Suspense`, `head` management, static site generation, incremental regeneration, route actions/middleware, scroll restoration, service worker & web/wasm workers, and microfrontend helpers.
+
+### `sibujs/performance` — Scheduling & optimization
+Concurrent rendering (`startTransition`, `scheduleUpdate`), cooperative `scheduler`, `domRecycler`, `compiled` templates, `chunkLoader`, `bundleOptimize`, and `normalize`.
+
+### `sibujs/devtools` — Developer tools
+`debug`, `debugValue`, `componentProfiler`, `signalGraph`, `introspect`, `devtoolsOverlay`, HMR support, and source maps.
+
+### `sibujs/build` — Build tooling
+Bundler plugins (`vite`, `webpack`), template compilation, route splitting, static analysis, linting, `.d.ts` declaration generation, CDN helpers, and IDE integration.
+
+### `sibujs/ecosystem` — Adapters
+Adapters bridging third-party state managers (e.g. Redux, MobX) and UI component libraries.
+
+### `sibujs/testing` — Test helpers
+Utilities for testing components and reactivity.
+
+### `sibujs/cdn` — Script-tag bundle
+Self-registering IIFE build exposing `window.Sibu`, for use without a bundler.
+
+```html
+<script src="https://unpkg.com/sibujs@latest/dist/cdn.global.js"></script>
+<script>
+  const { signal, effect, div, mount } = window.Sibu;
+</script>
+```
 
 ---