fiboui 1.0.2 → 2.0.0

package/README.md

@@ -1,165 +1,211 @@
-# 🏗️ FiboUI v1.0.0
+# FiboUI v2.0.0
 
-**A Flutter & SwiftUI-inspired React UI framework featuring a powerful Assembly Pattern and high-fidelity reactivity.**
+**A Flutter & SwiftUI-inspired React UI framework featuring a fluent builder API and fine-grained reactivity.**
 
-FiboUI brings the expressive, chainable syntax of modern mobile frameworks to React. Build complex, beautiful, and highly-performant UIs with **zero boilerplate** and **maximum readability**.
+FiboUI brings chainable builders to React. Compose screens with `Column()`, `Row()`, `Button()`, and `signal()` — builders passed to `.children()` are finalized automatically.
 
 ---
 
-## ✨ Features
+## Features
 
-- 🏗️ **The Assembly Pattern** - Components return builders for endless chaining.
-- ⚡ **Zero-Build Children** - Pass builders directly to `.children()`; they build implicitly.
-- 🔬 **Fine-Grained Reactivity** - Native support for Signals, Computed, and Observables.
-- 🎭 **Dynamic Multi-Theme** - Material, Cupertino, and Web themes with instant global switching.
-- 🎨 **Premium Aesthetics** - Built-in glassmorphism, micro-animations, and sleek dark modes.
-- 🔷 **100% Type-Safe** - Built with TypeScript for the best developer experience.
+- **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()`.
+- **Multi-theme** — Material, Cupertino, and Web tokens with CSS variables.
+- **Type-safe** — TypeScript builders; `FiboChild` / `FiboChildren` describe child slots.
 
 ---
 
-## 🚀 Installation
+## Installation
 
 ```bash
 npm install fiboui
 ```
 
-Import the styles in your main entry file:
+Import the stylesheet once in your entry file:
 
 ```tsx
-import 'fiboui/dist/style.css';
+import 'fiboui/style.css';
 ```
 
+**Required.** The JS entry does not load CSS. ESM-only (`import`, no `require`). See [MIGRATION.md](./MIGRATION.md) if you used 1.x snapshots.
+
+Peer dependencies: React 18 or 19.
+
+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.
+
+## Releasing
+
+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.
+
 ---
 
-## 🏗️ The Assembly Pattern
+## The assembly pattern
 
-### 1. Components as Builders
-Components return builder instances, allowing customization before rendering.
+### Components as builders
 
 ```tsx
-StakentCard()
-  .className("p-8 hover:border-indigo-500/50")
+import { Card, Text } from 'fiboui';
+
+Card()
+  .className('p-8')
   .style({ backgroundColor: '#111' })
-  .children([ ... ])
-  .build()
+  .children([Text('Hello')])
+  .build();
 ```
 
-### 2. Implicit Construction
-Builders in `.children()` are automatically finalized.
+### Implicit construction
+
+Builders in `.children()` do not need `.build()`. The event API on `Button` is **`.onPress`** (not `onClick`). `FiboBuilder.onClick` still exists for raw DOM handlers on any builder.
 
 ```tsx
-Column().children([
-  Text("Title").variant("h1"), 
-  Button("Action").onClick(handlePress)
-]).build()
+import { Button, Column, Text } from 'fiboui';
+
+Column()
+  .children([
+    Text('Title').variant('h1'),
+    Button('Action').onPress(() => undefined),
+  ])
+  .build();
 ```
 
 ---
 
-## ⚡ Reactivity & State
+## Reactivity & state
+
+### Signals
+
+`.bindSignal(sig)` subscribes the builder and **re-runs `build()`** 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.
 
-### Signals (Primitives)
 ```tsx
+import { Box, Button, Text, signal } from 'fiboui';
+
 const count = signal(0);
 
 Box()
   .bindSignal(count)
-  .children([
+  .children(() => [
     Text(`Count: ${count.value}`),
-    Button("+").onPress(() => count.value++)
+    Button('+').onPress(() => {
+      count.value += 1;
+    }),
   ])
-  .build()
+  .build();
 ```
 
-### Global Store
+`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.
+
+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)`.
+
+### Global store
+
 ```tsx
+import { Box, Text, createStore } from 'fiboui';
+
 const store = createStore({ theme: 'dark', user: 'John' });
 
-Box().observer().children([
-  Text(store.getState().user)
-])
+Box()
+  .observer()
+  .children(() => Text(store.getState().user))
+  .build();
+```
+
+---
+
+## Layout notes
+
+### Column + Row (`spaceBetween`)
+
+Flutter `Column` defaults to `CrossAxisAlignment.center`. SwiftUI `VStack` defaults to `.center`. FiboUI **2.0 matches that: `crossAxisAlignment('center')`.**
+
+**Row uses `align-self: stretch`** so `spaceBetween` still fills the Column width under a centered cross axis.
+
+To stretch every child (Flutter `CrossAxisAlignment.stretch`):
+
+```tsx
+Column().crossAxisAlignment('stretch');
 ```
 
 ---
 
-## 📱 Scaffold & Layout Shells
+## Scaffold & layout shells
 
-The `Scaffold` and `DashboardLayout` components provide professional-grade app structures.
+`Scaffold` uses `headerBar`, `footerBar`, `sideBarLeft`, and `sideBarRight`. `DashboardLayout` uses `header` and `sidebar`.
 
 ```tsx
-import { Scaffold, Sidebar, Header, Text, StakentButton } from 'fiboui';
+import { Header, Scaffold, Sidebar, Text } from 'fiboui';
 
 Scaffold()
-  .header(
-    Header().height(80).className("px-6 bg-white shadow-sm").children([
-      Text("App Title").variant("h2"),
-      StakentButton({ text: "Profile", variant: "outline" })
-    ])
+  .headerBar(
+    Header()
+      .height(80)
+      .className('px-6 bg-white shadow-sm')
+      .children([Text('App Title').variant('h2')])
   )
-  .sidebar(
-    Sidebar().width(240).children([
-       StakentSidebarItem({ label: "Home", active: true, icon: "home" }),
-       StakentSidebarItem({ label: "Settings", icon: "settings" })
-    ])
+  .sideBarLeft(
+    Sidebar().width(240).children([Text('Home'), Text('Settings')])
   )
-  .fab(
-    Button("+").variant("fab").onPress(() => console.log("Added!"))
-  )
-  .children([
-    Text("Welcome to the main content area.")
-  ])
-  .build()
+  .children([Text('Welcome to the main content area.')])
+  .build();
 ```
 
 ---
 
-## 🛒 Full Example: E-commerce Store
-
-Combine **Signals**, **Store**, and **Builders** for a complete reactive application.
+## Example: reactive product grid
 
 ```tsx
-import { signal, computed, createStore, Scaffold, Box, Text, Button, Badge, Row } from 'fiboui';
+import {
+  Badge,
+  Box,
+  Button,
+  Card,
+  Grid,
+  Row,
+  Text,
+  computed,
+  createStore,
+} from 'fiboui';
 
-// 1. Global Store
 const appStore = createStore({
-  cart: [],
+  cart: [] as { id: string; name: string; price: number; quantity: number }[],
   products: [
-    { id: '1', name: 'MacBook Pro', price: 2499, image: '💻' },
-    { id: '2', name: 'iPhone 15', price: 999, image: '📱' }
-  ]
+    { id: '1', name: 'MacBook Pro', price: 2499 },
+    { id: '2', name: 'iPhone 15', price: 999 },
+  ],
 });
 
-// 2. Reactive Computed Values
 const cartTotal = computed(() => {
   const cart = appStore.getState().cart;
   return cart.reduce((sum, item) => sum + item.price * item.quantity, 0);
 });
 
-// 3. UI Component
-export function EcommerceApp() {
-  return Scaffold()
-    .header(
-      Header().children([
-        Text('🛒 FiboShop').variant("h2"),
-        Row().children([
-          Text(`Total: $${cartTotal.value.toFixed(2)}`).bindSignal(cartTotal),
-          Badge().text(appStore.getState().cart.length.toString()).observer()
-        ])
-      ])
-    )
-    .children([
-      Grid().columns(2).gap("md").children(
-        appStore.getState().products.map(product => 
-          Card().children([
-            Text(product.image).fontSize(40),
-            Text(product.name).fontWeight("bold"),
-            Button(`Add $${product.price}`).onPress(() => {
-              // Update Store & Watch UI React!
-              appStore.setState(s => ({ cart: [...s.cart, { ...product, quantity: 1 }] }));
-            })
-          ])
-        )
-      )
+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 }],
+                }));
+              }),
+            ])
+          )
+        ),
     ])
     .build();
 }
@@ -167,6 +213,6 @@ export function EcommerceApp() {
 
 ---
 
-## 📄 License
+## License
 
-MIT © 2025 FiboUI
+MIT © 2025–2026 FiboUI

package/dist/FineGrain-kBxv0WeR.js

@@ -0,0 +1,29 @@
+"use client";
+import s, { useRef as l, useEffect as p } from "react";
+import { i as x, r as m, E } from "./builder-DjLYXkXu.js";
+function R({
+  compute: e,
+  as: n = "span",
+  className: i,
+  style: o,
+  ...u
+}) {
+  const r = x(), t = l(null), a = e();
+  return p(() => m(r, () => {
+    const f = new E(() => {
+      const c = e();
+      t.current && t.current.textContent !== c && (t.current.textContent = c);
+    });
+    return () => f.dispose();
+  }), [e, r]), s.createElement(n, { ref: t, className: i, style: o, ...u }, a);
+}
+function d(e, n) {
+  return s.createElement(R, {
+    compute: () => String(e.value),
+    as: n
+  });
+}
+export {
+  R as F,
+  d as b
+};

package/dist/Link-DDzSPY1Q.js

@@ -0,0 +1,88 @@
+"use client";
+import { jsx as d } from "react/jsx-runtime";
+import { createContext as p, useContext as m } from "react";
+const w = p(null);
+function s() {
+  const t = m(w);
+  if (!t)
+    throw new Error("useRouter must be used within a Router");
+  return t;
+}
+function y() {
+  return m(w);
+}
+function v() {
+  const { navigate: t } = s();
+  return t;
+}
+function b() {
+  const { params: t } = s();
+  return t;
+}
+function k() {
+  const { query: t } = s();
+  return t;
+}
+function L() {
+  const { currentPath: t } = s();
+  return {
+    pathname: t,
+    search: typeof window < "u" ? window.location.search : "",
+    hash: typeof window < "u" ? window.location.hash : ""
+  };
+}
+const x = ({
+  to: t,
+  children: u,
+  replace: a = !1,
+  state: r,
+  className: c,
+  style: f,
+  onClick: o
+}) => {
+  const h = v(), e = y(), i = t.startsWith("http") || t.startsWith("//") || t.startsWith("#") ? t : `${(e == null ? void 0 : e.basename) ?? ""}${t}`;
+  return /* @__PURE__ */ d(
+    "a",
+    {
+      href: i,
+      onClick: (n) => {
+        n.ctrlKey || n.metaKey || n.shiftKey || n.button !== 0 || (n.preventDefault(), o && o(n), h(t, { replace: a, state: r }));
+      },
+      className: c,
+      style: f,
+      children: u
+    }
+  );
+}, N = ({
+  to: t,
+  children: u,
+  className: a = "",
+  style: r = {},
+  activeClassName: c = "active",
+  activeStyle: f = {},
+  exact: o = !1,
+  ...h
+}) => {
+  const { currentPath: e } = s(), i = o ? e === t : e.startsWith(t), l = i ? `${a} ${c}`.trim() : a, n = i ? { ...r, ...f } : r;
+  return /* @__PURE__ */ d(
+    x,
+    {
+      to: t,
+      className: l,
+      style: n,
+      ...h,
+      children: u
+    }
+  );
+};
+export {
+  x as L,
+  N,
+  w as R,
+  v as a,
+  b,
+  L as c,
+  k as d,
+  y as e,
+  s as u
+};

package/dist/PluginManager-D5-ApsSN.js

@@ -0,0 +1,111 @@
+"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);
+const n = class n {
+  constructor() {
+    s(this, "services", /* @__PURE__ */ new Map());
+  }
+  static getInstance() {
+    return n.instance || (n.instance = new n()), n.instance;
+  }
+  register(t, e, r = {}) {
+    if (this.services.has(t) && !r.override)
+      return;
+    const u = {
+      token: t,
+      provider: e,
+      singleton: r.singleton ?? !1
+    };
+    this.services.set(t, u);
+  }
+  registerSingleton(t, e) {
+    this.register(t, e, { singleton: !0 });
+  }
+  resolve(t) {
+    const e = this.services.get(t);
+    if (!e)
+      throw new Error(`Service not found for token: ${String(t)}`);
+    if (e.singleton && e.instance)
+      return e.instance;
+    const r = this.createInstance(e.provider);
+    return e.singleton && (e.instance = r), r;
+  }
+  has(t) {
+    return this.services.has(t);
+  }
+  clear() {
+    this.services.clear();
+  }
+  createInstance(t) {
+    return typeof t != "function" ? t : this.isConstructor(t) ? new t() : t();
+  }
+  isConstructor(t) {
+    try {
+      return Reflect.construct(String, [], t), !0;
+    } catch {
+      return !1;
+    }
+  }
+};
+s(n, "instance");
+let a = n;
+const l = a.getInstance(), i = class i {
+  constructor() {
+    s(this, "plugins", /* @__PURE__ */ new Map());
+    s(this, "routes", []);
+    s(this, "sidebarItems", []);
+    s(this, "topbarActions", []);
+    s(this, "overlays", []);
+    s(this, "stores", /* @__PURE__ */ new Map());
+    s(this, "storeSeq", 0);
+  }
+  static getInstance() {
+    return i.instance || (i.instance = new i()), i.instance;
+  }
+  use(t) {
+    return this.plugins.has(t.name) ? this : (this.plugins.set(t.name, t), t.setup(this), this);
+  }
+  registerService(t, e) {
+    l.register(t, e);
+  }
+  registerStore(t, e) {
+    const r = e ?? `store-${this.storeSeq++}`;
+    this.stores.set(r, t);
+  }
+  getStore(t) {
+    return this.stores.get(t);
+  }
+  getStores() {
+    return this.stores;
+  }
+  registerRoute(t) {
+    this.routes.push(t);
+  }
+  registerSidebarItem(t) {
+    this.sidebarItems.push(t);
+  }
+  registerTopbarAction(t) {
+    this.topbarActions.push(t);
+  }
+  registerOverlay(t) {
+    this.overlays.push(t);
+  }
+  getRoutes() {
+    return this.routes;
+  }
+  getSidebarItems() {
+    return this.sidebarItems.sort((t, e) => (t.order || 0) - (e.order || 0));
+  }
+  getTopbarActions() {
+    return this.topbarActions;
+  }
+  getOverlays() {
+    return this.overlays;
+  }
+};
+s(i, "instance");
+let o = i;
+export {
+  o as P
+};