fiboui 2.4.3 → 2.5.0

package/README.md

@@ -1,220 +1,271 @@
-# FiboUI v2.4.3
+<div align="center">
 
-**A Flutter & SwiftUI-inspired React UI framework featuring a fluent builder API and fine-grained reactivity.**
+<img src="./docs/brand/logo.svg" width="88" alt="FiboUI logo" />
 
-FiboUI brings chainable builders to React. Compose screens with `Column()`, `Row()`, `Button()`, and `signal()`. Builders **are** React elements — return them from functions and skip `.build()`. Prefer the fluent API (no JSX tags).
+# FiboUI
 
----
+**Fluent React UI.** Flutter & SwiftUI energy for the web.  
+There is no JSX — the function return **is** the view.
 
-## Features
+<br />
 
-- **Assembly pattern** — factories return builders for endless chaining.
-- **Zero-build children** — pass builders to `.children()`; they build implicitly. Typed methods (`.onPress`, `.id`, `.spacing`, `.children`) stay assignable as children.
-- **Fine-grained reactivity** — `signal()`, `computed()`, `createStore()`, `.bindSignal()`, `.observer()`.
-- **Fluent themes** — `.theme("noir" \| "web" \| …)` / `extendTheme` / `FiboThemeProvider` — CSS vars SSR-safe (Flutter / SwiftUI model). Presets: Material, Cupertino, Web, **Noir**.
-- **Type-safe** — TypeScript builders; `FiboChild` / `FiboChildren` describe child slots.
-- **Media queries** — `Box().padding(8).md({ padding: 16 }).lg({ padding: 24 })` compiles to CSS `@media`. `.responsive({ mobile, tablet, desktop })` still works (JS).
-- **CSS motion & scroll** — `Box().animate('fadeIn').ease('spring')`, `.onScroll('fadeIn')`, `.stagger(80)`, `.scrollProgress()`, `Presence(open).enter('fadeIn').exit('fadeOut')`. Default path is CSS (no rAF). See `docs/guide/animation.md`.
-- **Interaction effects** — full Hover.css–inspired catalog (2D, background sweeps, borders, shadows, bubbles, curls) as fiboui-owned CSS. Any trigger: `.hover(h => h.effect("sweepToRight"))`, `.pressEffect("shrink")`, `.hoverEffect("float")`.
+[![npm](https://img.shields.io/npm/v/fiboui?style=for-the-badge&color=ff2d8a&labelColor=0a0a0a)](https://www.npmjs.com/package/fiboui)
+[![downloads](https://img.shields.io/npm/dm/fiboui?style=for-the-badge&color=c8ff00&labelColor=0a0a0a)](https://www.npmjs.com/package/fiboui)
+[![license](https://img.shields.io/badge/license-MIT-0a0a0a?style=for-the-badge&labelColor=0a0a0a&color=ffffff)](https://github.com/felipeoliveiradev/fiboui)
+[![site](https://img.shields.io/badge/site-fiboui.vercel.app-0a0a0a?style=for-the-badge&labelColor=ff2d8a&color=0a0a0a)](https://fiboui.vercel.app)
 
----
+<br />
 
-## Installation
+<img src="./docs/brand/banner.png" width="960" alt="FiboUI — Fluent React UI. There is no JSX." />
 
-```bash
-npm install fiboui
-```
+</div>
 
-Import the stylesheet once in your entry file:
+---
 
-```tsx
-import 'fiboui/style.css';
-```
+<div align="center">
 
-**Required.** The JS entry does not load CSS. ESM-only (`import`, no `require`). See [MIGRATION.md](./MIGRATION.md) if you used 1.x snapshots.
+### Live product
 
-Peer dependencies: React 18 or 19.
+| Marketing site | Store demo |
+| :---: | :---: |
+| [![FiboUI site](./docs/brand/site-hero.png)](https://fiboui.vercel.app) | [![Fibo Store](./docs/brand/store-hero.png)](https://fiboui-store.vercel.app) |
+| [**fiboui.vercel.app**](https://fiboui.vercel.app) | [**fiboui-store.vercel.app**](https://fiboui-store.vercel.app) |
 
-Next.js App Router: files that **call** builders (`Button()`, `Column()`, …) must be Client Components (`'use client'`). FiboUI uses hooks and context; it is not an RSC factory API. Import `'fiboui/style.css'` from a layout or the client entry.
+Both ships are built **only** with FiboUI fluent builders — no JSX in the product UI.
 
-## Releasing
+</div>
 
-Publishing is automated. The owner must add an **`NPM_TOKEN`** automation secret in the GitHub repo settings. Release branch is **`main`**. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+---
 
-Do not run `npm publish` locally. The `Publish` workflow runs on GitHub Release and on push to `main`: install, typecheck, test, build, then `npm publish --provenance --access public` only if that version is not already on npm. After a successful `main` publish it opens GitHub Release `vX.Y.Z` with the matching CHANGELOG section as notes.
+## Cursor / VS Code extension
 
----
+Fluent trees get Flutter-style **closing labels** (`// Column`, `// List`, `// Form`), **auto-indent** on Enter, **lineage guides** on `.children([…])`, snippets (`fcol`, `frow`, …), chain autocomplete, and the **FiboUI Noir** colour theme.
 
-## The assembly pattern
+```bash
+ln -sfn "$(pwd)/extensions/vscode-fiboui" \
+  "$HOME/.cursor/extensions/felipeoliveiradev.fiboui-0.1.0"
+```
 
-### Components as builders
+Reload the window, then pick theme **FiboUI Noir**. Details: [`extensions/vscode-fiboui/README.md`](./extensions/vscode-fiboui/README.md).
+
+## Install
+
+```bash
+npm install fiboui
+```
 
 ```tsx
-import { Card, Text } from 'fiboui';
+import 'fiboui/style.css' // required once — JS does not load CSS
+import { Button, Column, Text, mount } from 'fiboui'
 
-function Hello() {
-  return Card()
-    .className('p-8')
-    .style({ backgroundColor: '#111' })
-    .children([Text('Hello')]);
+function App() {
+  return Column()
+    .gap(12)
+    .padding(24)
+    .children([
+      Text('Hello FiboUI').variant('h1'),
+      Button('Ship it').onPress(() => undefined),
+    ])
 }
+
+mount('#root', App)
 ```
 
-### No `.build()`
+ESM-only · React **18 / 19** · Next App Router → `'use client'` on files that call builders.
 
-Builders are valid React elements (`isValidElement(Button('Go'))`). Return them from functions, nest them in `.children()`, or pass them as `React.createElement` arguments. `.build()` still exists and is deprecated.
+---
 
-The event API on `Button` is **`.onPress`** (not `onClick`). `FiboBuilder.onClick` still exists for raw DOM handlers on any builder.
+## JSX vs FiboUI
 
 ```tsx
-import { Button, Column, Text } from 'fiboui';
-
-function App() {
-  return Column().children([
-    Text('Title').variant('h1'),
-    Button('Action').onPress(() => undefined),
-  ]);
-}
+// ── JSX ──────────────────────────────────
+<div className="flex flex-col gap-3 p-6">
+  <h1>Hello</h1>
+  <button onClick={onShip}>Ship it</button>
+</div>
+
+// ── FiboUI ───────────────────────────────
+Column()
+  .gap(12)
+  .padding(24)
+  .children([
+    Text('Hello').variant('h1'),
+    Button('Ship it').onPress(onShip),
+  ])
 ```
 
+Same tree. Method calls instead of tags. Layout, theme, motion, and reactivity stay on the builder.
+
 ---
 
-## Reactivity & state
+## Runtime flow
+
+<img src="./docs/brand/flow-runtime.png" width="960" alt="Factory → fluent chain → children → React element → mount" />
 
-### Signals
+```mermaid
+flowchart LR
+  A["Column()"] --> B[".gap().padding()"]
+  B --> C[".children([...])"]
+  C --> D["React element"]
+  D --> E["mount / return"]
+
+  style A fill:#141414,stroke:#fff,color:#fff
+  style B fill:#141414,stroke:#ff2d8a,color:#ff2d8a
+  style C fill:#141414,stroke:#c8ff00,color:#c8ff00
+  style D fill:#141414,stroke:#fff,color:#fff
+  style E fill:#c8ff00,stroke:#c8ff00,color:#0a0a0a
+```
+
+Builders **are** valid React elements (`isValidElement(Button('Go'))`).  
+Return them. Nest them. **Skip `.build()`.**
+
+---
 
-`.bindSignal(sig)` subscribes the builder and **re-assembles** when the signal changes. Read the signal inside a **function child** (or `Text(() => ...)`) so the new value is picked up. Interpolating `sig.value` into a string at construction time is a one-shot snapshot.
+## Signal flow
+
+<img src="./docs/brand/flow-signals.png" width="960" alt="signal → bindSignal → function children → UI" />
 
 ```tsx
-import { Box, Button, Text, signal } from 'fiboui';
+import { Box, Button, Text, signal } from 'fiboui'
 
-const count = signal(0);
+const count = signal(0)
 
 Box()
   .bindSignal(count)
   .children(() => [
     Text(`Count: ${count.value}`),
     Button('+').onPress(() => {
-      count.value += 1;
+      count.value += 1
     }),
-  ]);
+  ])
 ```
 
-`useSignal(count)` and `.observer()` with a function child also work. Signal subscriptions unsubscribe on unmount and are Safe for React 18/19 StrictMode (`useSyncExternalStore`). Signals are in-memory and client-only — do not rely on them during SSR.
-
-`computed(() => ...)` is lazy: the first `.value` read attaches the internal effect. Read it (or `.bindSignal`) so updates notify.
+`.bindSignal` re-assembles. Read `.value` inside a **function child** so updates are live. `` Text(`Total ${todos.$length}`) `` stays live without a function child. Forms and validation: [Form](docs/components/interactive-form.md).
 
-Two store APIs exist: `createStore()` + `useReactiveStore(store)`, and the `@Store()` decorator + `useStore(StoreClass)` (the package-root `useStore`). Builder `.state(key, initial)` is runtime-updatable via `useBuilderState(key)`.
+```mermaid
+sequenceDiagram
+  participant UI as Builder tree
+  participant S as signal(count)
+  participant H as onPress
 
-### Global store
-
-```tsx
-import { Box, Text, createStore } from 'fiboui';
+  UI->>S: .bindSignal(count)
+  H->>S: count.value += 1
+  S-->>UI: notify subscribers
+  UI->>UI: re-assemble children()
+```
 
-const store = createStore({ theme: 'dark', user: 'John' });
+---
 
-Box()
-  .observer()
-  .children(() => Text(store.getState().user));
+## Package architecture
+
+<img src="./docs/brand/flow-architecture.png" width="960" alt="App over layout/content/structure/theme/reactivity over core" />
+
+```mermaid
+flowchart TB
+  APP["your app — screens · domain · mount"]
+  subgraph builders["fluent builders"]
+    L["layout / content<br/>Column · Row · Text · Button"]
+    S["structure / nav<br/>Box · Grid · Scaffold"]
+    T["theme / motion<br/>noir · animate · hover"]
+    R["reactivity<br/>signal · computed · store"]
+  end
+  CORE["core — FiboBuilder · styleManager · bindSignal"]
+
+  APP --> L & S & T & R
+  L & S & T & R --> CORE
+
+  style APP fill:#141414,stroke:#c8ff00,color:#c8ff00
+  style CORE fill:#c8ff00,stroke:#c8ff00,color:#0a0a0a
+  style L fill:#141414,stroke:#ff2d8a,color:#ff2d8a
+  style S fill:#141414,stroke:#fff,color:#fff
+  style T fill:#141414,stroke:#fff,color:#fff
+  style R fill:#141414,stroke:#fff,color:#fff
 ```
 
 ---
 
-## Layout notes
+## Why FiboUI
 
-### Column + Row (`spaceBetween`)
+| | |
+| :--- | :--- |
+| **Assembly pattern** | Factories return builders for endless chaining |
+| **Zero-build children** | Pass builders to `.children()` — they finalize implicitly |
+| **Signals** | `signal()`, `computed()`, `.bindSignal()`, `.observer()` |
+| **Themes** | `.theme("noir")` · `extendTheme` · Material / Cupertino / Web / Noir |
+| **Motion** | `.animate('fadeIn')` · `.onScroll` · `.hoverEffect` · CSS-first |
+| **Type-safe** | TypeScript builders · `FiboChild` / `FiboChildren` |
 
-Flutter `Column` defaults to `CrossAxisAlignment.center`. SwiftUI `VStack` defaults to `.center`. FiboUI **2.0 matches that: `crossAxisAlignment('center')`.**
+### Themes & motion
 
-**Row uses `align-self: stretch`** so `spaceBetween` still fills the Column width under a centered cross axis.
+```tsx
+Box()
+  .theme('noir')
+  .animate('fadeIn')
+  .ease('spring')
+  .hover((h) => h.effect('sweepToRight'))
+
+Box().padding(8).md({ padding: 16 }).lg({ padding: 24 })
+```
+
+### Layout notes
 
-To stretch every child (Flutter `CrossAxisAlignment.stretch`):
+FiboUI **2.x** matches Flutter / SwiftUI: `Column` defaults to `crossAxisAlignment('center')`.  
+`Row` uses `align-self: stretch` so `spaceBetween` still fills width.
 
 ```tsx
-Column().crossAxisAlignment('stretch');
+Column().crossAxisAlignment('stretch')
 ```
 
+`Button` uses **`.onPress`** (not `onClick`).
+
 ---
 
-## Scaffold & layout shells
+## Brand
 
-`Scaffold` uses `headerBar`, `footerBar`, `sideBarLeft`, and `sideBarRight`. `DashboardLayout` uses `header` and `sidebar`.
+<div align="center">
 
-```tsx
-import { Header, Scaffold, Sidebar, Text } from 'fiboui';
-
-Scaffold()
-  .headerBar(
-    Header()
-      .height(80)
-      .className('px-6 bg-white shadow-sm')
-      .children([Text('App Title').variant('h2')])
-  )
-  .sideBarLeft(
-    Sidebar().width(240).children([Text('Home'), Text('Settings')])
-  )
-  .children([Text('Welcome to the main content area.')]);
-```
+<img src="./docs/brand/logo-lockup.svg" width="280" alt="FiboUI lockup" />
+
+<br /><br />
+
+| Token | Hex | |
+| :---: | :---: | :--- |
+| **Ink** | `#0a0a0a` | background |
+| **Chalk** | `#ffffff` | type |
+| **Pink** | `#ff2d8a` | energy |
+| **Lime** | `#c8ff00` | mark / CTA |
+
+<img src="./docs/brand/fibonacci.svg" width="220" alt="Fibonacci spiral" />
+
+**Tailored to each request** · **Attention to detail**
+
+</div>
 
 ---
 
-## Example: reactive product grid
+## Docs & contributing
 
-```tsx
-import {
-  Badge,
-  Box,
-  Button,
-  Card,
-  Grid,
-  Row,
-  Text,
-  computed,
-  createStore,
-} from 'fiboui';
-
-const appStore = createStore({
-  cart: [] as { id: string; name: string; price: number; quantity: number }[],
-  products: [
-    { id: '1', name: 'MacBook Pro', price: 2499 },
-    { id: '2', name: 'iPhone 15', price: 999 },
-  ],
-});
-
-const cartTotal = computed(() => {
-  const cart = appStore.getState().cart;
-  return cart.reduce((sum, item) => sum + item.price * item.quantity, 0);
-});
-
-export function ShopHeader() {
-  return Box()
-    .observer()
-    .children(() => [
-      Row().children([
-        Text(`Total: $${cartTotal.value.toFixed(2)}`).bindSignal(cartTotal),
-        Badge().text(String(appStore.getState().cart.length)),
-      ]),
-      Grid()
-        .columns(2)
-        .gap('md')
-        .children(
-          appStore.getState().products.map((product) =>
-            Card().children([
-              Text(product.name).weight('bold'),
-              Button(`Add $${product.price}`).onPress(() => {
-                appStore.setState((s) => ({
-                  cart: [...s.cart, { ...product, quantity: 1 }],
-                }));
-              }),
-            ])
-          )
-        ),
-    ]);
-}
-```
+| | |
+| :--- | :--- |
+| Migration from 1.x | [MIGRATION.md](./MIGRATION.md) |
+| Contributing & release | [CONTRIBUTING.md](./CONTRIBUTING.md) |
+| Animation guide | [`docs/guide/animation.md`](./docs/guide/animation.md) |
+| Brand assets | [`docs/brand/`](./docs/brand/) |
+
+Publishing is automated on **`main`** (GitHub Actions + `NPM_TOKEN`). Prefer not to `npm publish` locally.
 
 ---
 
-## License
+<div align="center">
+
+<img src="./docs/brand/logo-mark.svg" width="48" alt="" />
+
+<br /><br />
+
+**Wear the return.**
 
 MIT © 2025–2026 FiboUI
+
+[Site](https://fiboui.vercel.app) · [Store](https://fiboui-store.vercel.app) · [npm](https://www.npmjs.com/package/fiboui) · [GitHub](https://github.com/felipeoliveiradev/fiboui)
+
+</div>

package/dist/Link-DU8XI2Na.js

@@ -0,0 +1,50 @@
+import { jsx as u } from "react/jsx-runtime";
+import { aa as m, as as p, a9 as v } from "./client-C5fy1-Lh.js";
+const k = ({
+  to: t,
+  children: c,
+  replace: n = !1,
+  state: e,
+  className: l,
+  style: f,
+  onClick: i
+}) => {
+  const o = m(), a = p(), r = t.startsWith("http") || t.startsWith("//") || t.startsWith("#") ? t : `${(a == null ? void 0 : a.basename) ?? ""}${t}`;
+  return /* @__PURE__ */ u(
+    "a",
+    {
+      href: r,
+      onClick: (s) => {
+        s.ctrlKey || s.metaKey || s.shiftKey || s.button !== 0 || (s.preventDefault(), i && i(s), o(t, { replace: n, state: e }));
+      },
+      className: l,
+      style: f,
+      children: c
+    }
+  );
+}, W = ({
+  to: t,
+  children: c,
+  className: n = "",
+  style: e = {},
+  activeClassName: l = "active",
+  activeStyle: f = {},
+  exact: i = !1,
+  ...o
+}) => {
+  const { currentPath: a } = v(), r = i ? a === t : a.startsWith(t), h = r ? `${n} ${l}`.trim() : n, s = r ? { ...e, ...f } : e;
+  return /* @__PURE__ */ u(
+    k,
+    {
+      to: t,
+      className: h,
+      style: s,
+      ...o,
+      children: c
+    }
+  );
+};
+export {
+  k as L,
+  W as N
+};

package/dist/{PluginManager-D5-ApsSN.js → PluginManager-BRjgOLVa.js}

@@ -1,7 +1,6 @@
-"use client";
 var h = Object.defineProperty;
-var g = (c, t, e) => t in c ? h(c, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : c[t] = e;
-var s = (c, t, e) => g(c, typeof t != "symbol" ? t + "" : t, e);
+var g = (a, t, e) => t in a ? h(a, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : a[t] = e;
+var s = (a, t, e) => g(a, typeof t != "symbol" ? t + "" : t, e);
 const n = class n {
   constructor() {
     s(this, "services", /* @__PURE__ */ new Map());
@@ -49,8 +48,8 @@ const n = class n {
   }
 };
 s(n, "instance");
-let a = n;
-const l = a.getInstance(), i = class i {
+let c = n;
+const f = c.getInstance(), i = class i {
   constructor() {
     s(this, "plugins", /* @__PURE__ */ new Map());
     s(this, "routes", []);
@@ -67,7 +66,7 @@ const l = a.getInstance(), i = class i {
     return this.plugins.has(t.name) ? this : (this.plugins.set(t.name, t), t.setup(this), this);
   }
   registerService(t, e) {
-    l.register(t, e);
+    f.register(t, e);
   }
   registerStore(t, e) {
     const r = e ?? `store-${this.storeSeq++}`;