npm - reactolith - Versions diffs - 1.0.19 - Mend

reactolith 1.0.19

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/LICENSE +21 -0
package/README.md +523 -0
package/dist/cli/generate-web-types.cjs +607 -0
package/dist/cli/generate-web-types.cjs.map +1 -0
package/dist/index.cjs +611 -0
package/dist/index.cjs.map +1 -0
package/dist/index.d.ts +236 -0
package/dist/index.mjs +599 -0
package/dist/index.mjs.map +1 -0
package/package.json +88 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Franz Mayr-Wilding
+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 ADDED Viewed

@@ -0,0 +1,523 @@
+# ⚡️ reactolith
+> **Proof of Concept** – This project is still experimental and **not ready for production**.
+`reactolith` lets you **write React components directly in HTML** — making it possible to render and hydrate a React app using server-generated HTML from any backend (e.g. Symfony/Twig, Rails, Laravel, Django, etc.).
+✨ Instead of manually wiring React components everywhere, just return HTML from your backend and `reactolith` will transform it into a live, interactive React application.
+It even includes a **built-in router** that intercepts link clicks and form submissions, fetches the next page via AJAX, and updates only what changed — **keeping React state intact between navigations**.
+---
+## 🚀 Features
+- 🔌 **Backend-agnostic** – Works with any backend (Symfony, Rails, Laravel, etc.)
+- 🛠 **Use existing backend helpers** (Twig path functions, permission checks, etc.)
+- 🔄 **State preserved across pages** – No resets on navigation
+- 📋 **Form support** – Modify forms dynamically (e.g., add buttons on checkbox click) **without losing state or focus**
+- 🪶 **Lightweight** – Just a few lines of setup, no heavy dependencies
+- 📡 **Real-time updates** – Works with Mercure Server-Sent-Events to push updates from the backend to the frontend
+---
+## 📦 Installation
+```bash
+npm install reactolith
+```
+Since react and react-dom are peer dependencies, make sure to also install them:
+```bash
+npm install react react-dom
+```
+---
+### How It Works
+1. **Initial Load**: Symfony renders HTML with Twig, `reactolith` hydrates it into React components
+2. **Navigation**: Clicking links fetches new HTML via AJAX, React reconciles the differences
+3. **Real-time**: Mercure pushes HTML updates from server, UI updates automatically
+4. **State Preserved**: React component state survives both navigation and real-time updates
+---
+## 💡 Usage
+Your backend returns simple HTML:
+```html
+<html lang="en">
+  <body>
+    <div id="reactolith-app">
+      <h1>Hello world</h1>
+      <ui-button type="primary">This will be a shadcn button</ui-button>
+    </div>
+  </body>
+</html>
+```
+Your frontend mounts the reactolith app:
+```ts
+// app.ts
+import loadable from '@loadable/component'
+import { App } from 'reactolith'
+const component = loadable(
+  async ({ is }: { is: string }) => {
+    return import(`./components/ui/${is.substring(3)}.tsx`)
+  },
+  {
+    cacheKey: ({ is }) => is,
+    // Since shadcn files don’t export a default,
+    // we resolve the correct named export
+    resolveComponent: (mod, { is }: { is: string }) => {
+      const cmpName = is
+        .substring(3)
+        .replace(/(^\w|-\w)/g, match => match.replace(/-/, '').toUpperCase())
+      return mod[cmpName]
+    },
+  }
+)
+// Uses the HTML element with id="reactolith-app" as root
+new App(component)
+```
+### 🎨 Example with Custom Root Component & Selector
+```ts
+// app.ts
+import loadable from '@loadable/component'
+import { App } from 'reactolith'
+import { AppProvider } from './providers/app-provider.tsx'
+const component = loadable(
+  async ({ is }: { is: string }) => import(`./components/${is}.tsx`),
+  { cacheKey: ({ is }) => is }
+)
+new App(component, AppProvider, '#app')
+```
+```tsx
+// providers/app-provider.tsx
+import React, { ElementType } from "react"
+import { App, RootComponent } from "reactolith"
+import { RouterProvider } from "react-aria-components"
+import { ThemeProvider } from "./theme-provider"
+export const AppProvider: React.FC<{
+  app: App
+  element: HTMLElement
+  component: ElementType
+}> = ({ app, element, component }) => (
+  <React.StrictMode>
+    <RouterProvider navigate={app.router.navigate}>
+      <ThemeProvider>
+        <RootComponent element={element} component={component} />
+      </ThemeProvider>
+    </RouterProvider>
+  </React.StrictMode>
+)
+```
+---
+## 🔄 Navigation Without Losing State
+When navigating, `reactolith` fetches the **next HTML page** and applies **only the differences** using React’s reconciliation algorithm.
+👉 This means component state is preserved (e.g., toggles, inputs, focus).
+```html
+<!-- page1.html -->
+<div id="reactolith-app">
+  <h1>Page 1</h1>
+  <ui-toggle json-pressed="false">Toggle</ui-toggle>
+  <a href="page2.html">Go to page 2</a>
+</div>
+```
+```html
+<!-- page2.html -->
+<div id="reactolith-app">
+  <h1>Page 2</h1>
+  <ui-toggle json-pressed="true">Toggle</ui-toggle>
+  <a href="page1.html">Go to page 1</a>
+</div>
+```
+Only the `<h1>` text and the `pressed` prop are updated — everything else remains untouched ✅.
+---
+## Props
+If you pass props to your reactolith components like this:
+```html
+<my-component enabled name="test" data-foo="baa" as="{my-other-component}" json-config='{ "foo": "baa" }'
+```
+your components will get this props:
+```tsx
+const props = {
+    enabled: true,
+    name: 'test',
+    foot: 'baa',
+    as: <MyOtherComponent />,
+    config: { foo: 'baa' },
+}
+```
+---
+## Slots
+reactolith also provides a simple slot mechanism: Every child if a reactolith-component with a slot attribute will be
+transformed to a slot property, holding the children of the element:
+```html
+<my-component>
+    <template slot="header"><h1>My header content</h1></template>
+    <div slot="footer">My footer content</div>
+</my-component>
+```
+your components will get this props:
+```tsx
+function MyComponent({ header, footer } : { header : ReactNode, footer : ReactNode }) {
+    <article>
+        <header>{header}</header>
+        <div>My content</div>
+        <footer>{footer}</footer>
+        <aside>
+            <footer>{footer}</footer>
+        </aside>
+    </article>
+}
+```
+---
+## 📡 Real-time Updates with Mercure
+`reactolith` supports **Server-Sent Events (SSE)** via [Mercure](https://mercure.rocks/) for real-time updates from your backend. When the server publishes an update, the HTML is automatically rendered — just like with router navigation.
+Mercure automatically subscribes to the **current URL pathname** as the topic and re-subscribes when the route changes.
+### Auto-Configuration (Recommended)
+The easiest way to configure Mercure is to add the `data-mercure-hub-url` attribute to your root element:
+```html
+<div id="reactolith-app" data-mercure-hub-url="https://example.com/.well-known/mercure">
+  <!-- Your content -->
+</div>
+<!-- With credentials (cookies): -->
+<div id="reactolith-app"
+     data-mercure-hub-url="https://example.com/.well-known/mercure"
+     data-mercure-with-credentials>
+  <!-- Your content -->
+</div>
+```
+```typescript
+import { App, Mercure } from "reactolith";
+const app = new App(component);
+// mercureConfig is automatically set from data-mercure-hub-url attribute
+const mercure = new Mercure(app);
+mercure.subscribe(app.mercureConfig!);
+// optional listen to events
+mercure.on("sse:connected", (url) => {
+  console.log("Connected to Mercure hub");
+});
+```
+### Manual Configuration
+Alternatively, you can configure Mercure programmatically:
+```typescript
+import { App, Mercure } from "reactolith";
+const app = new App(component);
+const mercure = new Mercure(app);
+// Subscribe to Mercure hub (uses current pathname as topic)
+mercure.subscribe({
+  hubUrl: "https://example.com/.well-known/mercure",
+  withCredentials: true,  // Include cookies for authentication
+});
+```
+When the user navigates to a different route, Mercure automatically reconnects with the new pathname as the topic.
+### Auto-Refetch on Empty Messages
+When Mercure receives an **empty message** (or whitespace-only), it automatically refetches the current route. This makes it easy to invalidate the current page from the backend without having to render and send the full HTML:
+**Backend (simple invalidation):**
+```php
+// Just notify that the page should refresh - no HTML needed
+$hub->publish(new Update('/dashboard', ''));
+```
+Instead of:
+```php
+// Old way: render and send full HTML
+$html = $twig->render('dashboard.html.twig', $data);
+$hub->publish(new Update('/dashboard', $html));
+```
+This triggers a GET request to the current URL and renders the response.
+### Mercure Events
+| Event | Arguments | Description |
+|-------|-----------|-------------|
+| `sse:connected` | `url` | Connection established |
+| `sse:disconnected` | `url` | Connection closed |
+| `sse:message` | `event, html` | Message received |
+| `render:success` | `event, html` | HTML rendered successfully |
+| `render:failed` | `event, html` | Render failed (no root element) |
+| `refetch:started` | `event` | Auto-refetch triggered (empty message) |
+| `refetch:success` | `event, html` | Auto-refetch completed successfully |
+| `refetch:failed` | `event, error` | Auto-refetch failed |
+| `sse:error` | `error` | Connection error |
+### Live Data with useMercureTopic
+For simple live values (like notification counts, user status), use the `useMercureTopic` hook to subscribe to Mercure topics that send JSON data:
+```tsx
+import { useMercureTopic } from 'reactolith';
+// Simple types - inferred from initial value
+function NotificationBadge() {
+  const count = useMercureTopic('/notifications/count', 0);
+  if (count === 0) return null;
+  return <span className="badge">{count}</span>;
+}
+// Explicit type parameter
+function UserStatus({ userId }: { userId: number }) {
+  const status = useMercureTopic<'online' | 'offline' | 'away'>(
+    `/user/${userId}/status`,
+    'offline'
+  );
+  return <span className={status}>{status}</span>;
+}
+// Complex types with interfaces
+interface DashboardStats {
+  visitors: number;
+  sales: number;
+  conversion: number;
+}
+function Dashboard() {
+  const stats = useMercureTopic<DashboardStats>('/dashboard/stats', {
+    visitors: 0,
+    sales: 0,
+    conversion: 0,
+  });
+  return (
+    <div>
+      <span>Visitors: {stats.visitors}</span>
+      <span>Sales: {stats.sales}</span>
+      <span>Conversion: {stats.conversion}%</span>
+    </div>
+  );
+}
+```
+**Backend:**
+```php
+// Push JSON data to topic
+$hub->publish(new Update(
+    '/notifications/count',
+    json_encode(42)
+));
+```
+**Note:** When using `useMercureTopic`, make sure `app.mercureConfig` is set. You can either:
+- Use the auto-configuration by adding `data-mercure-hub-url` to your root element (recommended), or
+- Set it manually:
+```typescript
+const app = new App(component);
+app.mercureConfig = {
+  hubUrl: "/.well-known/mercure",
+  withCredentials: true,
+};
+```
+### Custom Live Regions (Partial Updates)
+For partial updates (e.g., updating a sidebar across all pages), you can create your own live region component. The `mercureConfig` is accessible via `useApp()`:
+**Setup:**
+```typescript
+import { App, Mercure, MercureLive } from 'reactolith';
+import loadable from '@loadable/component';
+const component = loadable(
+    async ({ is }: { is: string }) => {
+        // The mapping is up to you, reactolith only provides the MercureLive Component (don't lazy load it!)
+        if (is === 'mercure-live') {
+            return MercureLive;
+        }
+        // Your default implementaiton
+        return import(`./components/${is}.tsx`);
+    },
+    {
+        cacheKey: ({ is }) => is,
+        resolveComponent: (mod, { is }) => {
+            if (is === 'mercure-live') {
+                return mod;
+            }
+            return mod.default || mod[is];
+        }
+    }
+);
+const app = new App(component);
+const mercure = new Mercure(app);
+// Store config for components to access
+app.mercureConfig = {
+  hubUrl: "/.well-known/mercure",
+  withCredentials: true,
+};
+mercure.subscribe(app.mercureConfig);
+```
+### Beispiel: Live Sidebar
+```tsx
+// components/sidebar.tsx
+export function Sidebar({ children }: { children: React.ReactNode }) {
+  return (
+    <aside className="sidebar">
+      {children}
+    </aside>
+  );
+}
+```
+**HTML Usage:**
+```html
+<div id="reactolith-app">
+  <nav>...</nav>
+  <!-- Diese Region wird live aktualisiert -->
+  <mercure-live topic="/sidebar">
+    <sidebar>
+      <ul>
+        <li>Initial menu item 1</li>
+        <li>Initial menu item 2</li>
+      </ul>
+    </sidebar>
+  </mercure-live>
+  <main>...</main>
+</div>
+```
+**Backend:**
+```php
+// Render die Sidebar neu
+$html = $twig->render('_sidebar.html.twig', [
+    'menuItems' => $updatedMenuItems
+]);
+// Push zu allen Clients
+$hub->publish(new Update('/sidebar', $html));
+```
+**Template (_sidebar.html.twig):**
+```twig
+<sidebar>
+  <ul>
+    {% for item in menuItems %}
+    <li>{{ item.label }}</li>
+    {% endfor %}
+  </ul>
+</sidebar>
+```
+---
+## 🧩 IDE Autocomplete (Web-Types)
+`reactolith` includes a CLI tool to generate [web-types](https://github.com/JetBrains/web-types) for your custom components. This enables **autocomplete and validation** in IDEs like WebStorm, PhpStorm, and VS Code (with appropriate plugins).
+### Generate web-types.json
+```bash
+npx generate-web-types -c src/components/ui -o web-types.json -n my-app
+```
+**Options:**
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--components` | `-c` | Components directory | `components/ui` |
+| `--tsconfig` | `-t` | TypeScript config file | `tsconfig.app.json` (or `tsconfig.json`) |
+| `--out` | `-o` | Output file | `web-types.json` |
+| `--name` | `-n` | Library name | `reactolith-components` |
+| `--version` | `-v` | Library version | `1.0.0` |
+| `--prefix` | `-p` | Element name prefix | `""` |
+| `--help` | `-h` | Show help | |
+### Configure your project
+Add the generated file to your `package.json`:
+```json
+{
+  "name": "my-app",
+  "web-types": "./web-types.json"
+}
+```
+### Result
+After restarting your IDE, you'll get:
+- ✅ **Autocomplete** for custom element names (e.g., `<ui-button>`)
+- ✅ **Prop suggestions** with types and descriptions
+- ✅ **Slot hints** for components with children/slots
+- ✅ **Validation** for required props and valid values
+**Tip:** Add `npx generate-web-types ...` to your build script to keep web-types in sync:
+```json
+{
+  "scripts": {
+    "build": "vite build && npx generate-web-types -c src/components/ui -o web-types.json"
+  }
+}
+```
+---
+## 🤝 Contributing
+Contributions are welcome!
+Feel free to open an issue or submit a PR.
+---
+## 🛠 Development Build
+If you’re contributing to this library:
+```bash
+npm install
+npm run build
+```