@navette-js/wire 0.0.0-stage → 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NavetteJS
+
+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

@@ -1,3 +1,9 @@
-# Temporary Holding Version
+# @navette-js/wire
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Server-side runtime compatible with Livewire 3 for Node.js and Express.
+
+Part of [Navette](https://github.com/NavetteJS/navette), a Node.js port of [Filament](https://filamentphp.com). Install the whole framework with `npm install @navette-js/panels`.
+
+**Beta:** the API may still change between beta releases.
+
+License: MIT. Third-party notices: see `THIRD-PARTY-NOTICES.md` where present.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,12 @@
+# Third-party notices
+
+Navette is an independent Node.js port of Filament. It is not affiliated with or endorsed by the Filament, Livewire or Heroicons projects. It reuses the following works, each under its own license; the full license texts ship next to the files they cover.
+
+| Work | Used for | License | License file |
+|---|---|---|---|
+| [Filament](https://github.com/filamentphp/filament) © Filament | HTML markup ported from its Blade views, compiled CSS and JavaScript (`@navette-js/panels/dist/filament`), English translations (`@navette-js/support/data`) | MIT | `packages/panels/dist/FILAMENT-LICENSE.md` |
+| [Livewire](https://github.com/livewire/livewire) © Caleb Porzio | Client script `livewire.js` (`@navette-js/wire/vendor`); the server runtime follows its protocol | MIT | `packages/wire/vendor/LIVEWIRE-LICENSE.md` |
+| [Heroicons](https://github.com/tailwindlabs/heroicons) | SVG icons (`@navette-js/support/icons`) | MIT | `packages/support/icons/HEROICONS-LICENSE.md` |
+| [Inter](https://github.com/rsms/inter) © The Inter Project Authors | Default font files (`@navette-js/panels/dist/filament/fonts`) | SIL Open Font License 1.1 | `packages/panels/dist/filament/fonts/INTER-LICENSE.txt` |
+
+Runtime dependencies installed from npm (Express, Knex, Objection, better-sqlite3, Tiptap, EJS, Busboy…) keep their own licenses.

package/lib/express.d.ts

@@ -0,0 +1,15 @@
+import type { Request, Response, Router } from 'express';
+import { type WireRuntime } from './index.ts';
+/** Jeton CSRF par double soumission : cookie HttpOnly + jeton renvoyé dans le corps par livewire.js (`_token`). */
+export declare function csrfToken(req: Request, res: Response): string;
+/** Vérifie le jeton envoyé (corps ou formulaire) contre le cookie, en temps constant. */
+export declare function verifyCsrf(req: Request, token: unknown): boolean;
+export declare function wireRouter(runtime: WireRuntime, prefix?: string, makeContext?: (req: Request, res: Response) => unknown | Promise<unknown>, 
+/** Exécute le traitement dans un contexte de requête et permet d'enrichir la réponse (notifications…). */
+around?: (ctx: any, req: Request, res: Response, handle: () => Promise<any>) => Promise<any>, 
+/** Autorise un envoi de fichier (par exemple : utilisateur connecté). Sans cette fonction, tout porteur d'une adresse signée et du jeton CSRF peut envoyer. */
+canUpload?: (ctx: any) => boolean | Promise<boolean>): Router;
+/** Balise <script> attendue par livewire.js (équivalent de FrontendAssets::js). */
+export declare function wireScripts(req: Request, res: Response, prefix?: string): string;
+/** Styles attendus par livewire.js (équivalent de FrontendAssets::styles) : à placer dans <head>. */
+export declare function wireStyles(progressBarColor?: string): string;

package/lib/express.js

@@ -0,0 +1,92 @@
+// Intégration Express du runtime : sert livewire.js embarqué, expose l'endpoint de mise à jour, protège par jeton CSRF.
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import express from 'express';
+import { WireError } from "./index.js";
+const vendor = (f) => fileURLToPath(new URL(`../vendor/${f}`, import.meta.url));
+const versionHash = JSON.parse(readFileSync(vendor('manifest.json'), 'utf8'))['/livewire.js'];
+const COOKIE = 'navette_csrf';
+const readCookie = (req, name) => (req.headers.cookie ?? '').split(';').map((c) => c.trim().split('=')).find(([k]) => k === name)?.[1];
+/** Jeton CSRF par double soumission : cookie HttpOnly + jeton renvoyé dans le corps par livewire.js (`_token`). */
+export function csrfToken(req, res) {
+    let token = readCookie(req, COOKIE) ?? res.locals.navetteCsrf;
+    if (!token) {
+        token = randomBytes(24).toString('base64url');
+        res.cookie(COOKIE, token, { httpOnly: true, sameSite: 'lax', secure: req.secure === true });
+        res.locals.navetteCsrf = token;
+    }
+    return token;
+}
+/** Vérifie le jeton envoyé (corps ou formulaire) contre le cookie, en temps constant. */
+export function verifyCsrf(req, token) {
+    const cookie = Buffer.from(readCookie(req, COOKIE) ?? ''), sent = Buffer.from(String(token ?? ''));
+    return cookie.length > 0 && cookie.length === sent.length && timingSafeEqual(cookie, sent);
+}
+export function wireRouter(runtime, prefix = '/livewire', makeContext = (req, res) => ({ req, res }), 
+/** Exécute le traitement dans un contexte de requête et permet d'enrichir la réponse (notifications…). */
+around = (_ctx, _req, _res, handle) => handle(), 
+/** Autorise un envoi de fichier (par exemple : utilisateur connecté). Sans cette fonction, tout porteur d'une adresse signée et du jeton CSRF peut envoyer. */
+canUpload = () => true) {
+    const router = express.Router();
+    router.get(`${prefix}/livewire.js`, (_req, res) => {
+        res.type('application/javascript').set('Cache-Control', 'public, max-age=31536000, immutable').sendFile(vendor('livewire.js'));
+    });
+    router.post(`${prefix}/update`, express.json({ limit: '2mb' }), async (req, res) => {
+        try {
+            if (!verifyCsrf(req, req.body?._token))
+                throw new WireError(419, 'Jeton CSRF invalide.');
+            const ctx = await makeContext(req, res);
+            res.json(await around(ctx, req, res, () => runtime.handle(req.body, ctx)));
+        }
+        catch (e) {
+            const status = e instanceof WireError ? e.status : 500;
+            if (status === 500)
+                console.error(e);
+            else if (process.env.NODE_ENV !== 'production')
+                console.warn(`[wire] ${status} ${e.message} — calls=${JSON.stringify(req.body?.components?.map((c) => c.calls))} updates=${JSON.stringify(req.body?.components?.map((c) => c.updates))}`);
+            res.status(status).send(e instanceof Error ? e.message : 'Erreur');
+        }
+    });
+    // Envoi de fichiers : adresse signée par `_startUpload`, jeton CSRF en en-tête, fichiers reçus dans le dossier temporaire.
+    router.post(`${prefix}/upload-file`, async (req, res) => {
+        try {
+            const store = runtime.uploads;
+            if (!store)
+                throw new WireError(404, 'Téléversement indisponible.');
+            if (!store.verifySignature(req.query.expires, req.query.signature))
+                throw new WireError(401, 'Adresse d\'envoi invalide ou expirée.');
+            if (!verifyCsrf(req, req.get('x-csrf-token')))
+                throw new WireError(419, 'Jeton CSRF invalide.');
+            if (!(await canUpload(await makeContext(req, res))))
+                throw new WireError(401, 'Non authentifié.');
+            res.json({ paths: await store.receive(req) });
+        }
+        catch (e) {
+            const status = e instanceof WireError ? e.status : Number(e?.status) || 500;
+            if (status === 500)
+                console.error(e);
+            res.status(status).json({ message: e instanceof Error ? e.message : 'Erreur' });
+        }
+    });
+    return router;
+}
+/** Balise <script> attendue par livewire.js (équivalent de FrontendAssets::js). */
+export function wireScripts(req, res, prefix = '/livewire') {
+    return `<script src="${prefix}/livewire.js?id=${versionHash}" data-csrf="${csrfToken(req, res)}" data-module-url="${prefix}" data-update-uri="${prefix}/update" data-navigate-once="true"></script>`;
+}
+/** Styles attendus par livewire.js (équivalent de FrontendAssets::styles) : à placer dans <head>. */
+export function wireStyles(progressBarColor = '#2299dd') {
+    const BS = String.fromCharCode(92); // barre oblique inverse : échappe « : » et « . » dans les sélecteurs CSS
+    const sel = (n) => `[wire${BS}:${n.replaceAll('.', BS + '.')}]`;
+    const doubled = (names) => names.map((n) => sel(n) + sel(n)).join(', ');
+    return '<!-- Livewire Styles --><style>'
+        + doubled(['loading', 'loading.delay', 'loading.list-item', 'loading.inline-block', 'loading.inline', 'loading.block', 'loading.flex', 'loading.table', 'loading.grid', 'loading.inline-flex']) + ' {display: none;}'
+        + doubled(['loading.delay.none', 'loading.delay.shortest', 'loading.delay.shorter', 'loading.delay.short', 'loading.delay.default', 'loading.delay.long', 'loading.delay.longer', 'loading.delay.longest']) + ' {display: none;}'
+        + doubled(['offline']) + ' {display: none;}'
+        + sel('dirty') + ':not(textarea):not(input):not(select) {display: none;}'
+        + `:root {--livewire-progress-bar-color: ${progressBarColor};}`
+        + '[x-cloak="x-cloak"],[x-cloak=""] {display: none !important;}'
+        + sel('cloak').replace(']', '="wire:cloak"]') + ',' + sel('cloak').replace(']', '=""]') + ' {display: none !important;}'
+        + 'dialog#livewire-error::backdrop {background-color: rgba(0, 0, 0, .6);}</style>';
+}

package/lib/index.d.ts

@@ -0,0 +1,149 @@
+import { UploadStore } from './uploads.ts';
+export { UploadStore, type TemporaryFile } from './uploads.ts';
+export type Effects = {
+    html?: string;
+    returns?: unknown[];
+    dispatches?: {
+        name: string;
+        params: Record<string, unknown>;
+        self?: boolean;
+        to?: string;
+    }[];
+    redirect?: string;
+    redirectUsingNavigate?: boolean;
+    partials?: Record<string, string>;
+    [key: string]: unknown;
+};
+export type Snapshot = {
+    data: Record<string, unknown>;
+    memo: Record<string, any>;
+    checksum: string;
+};
+export type Call = {
+    method: string;
+    params: unknown[];
+    metadata?: Record<string, unknown>;
+};
+type ComponentClass = (new () => Component) & {
+    componentName?: string;
+    callable?: string[];
+    locked?: string[];
+    reactive?: string[];
+    listeners?: Record<string, string>;
+};
+export declare class WireError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+/** Classe de base d'un composant. Toute propriété propre énumérable ne commençant pas par `_` est de l'état public. */
+export declare abstract class Component {
+    _id: string;
+    _effects: Effects;
+    _skipRender: boolean;
+    _errors: Record<string, string[]>;
+    /** Contexte de la requête HTTP en cours (requête, réponse, panel…), fourni par l'intégration. */
+    _ctx: any;
+    /** Runtime et requête d'origine : servent à monter des composants enfants pendant le rendu. */
+    _runtime: WireRuntime | null;
+    _request: {
+        path?: string;
+        method?: string;
+    };
+    /** Enfants rendus pendant cette requête, et enfants déjà présents dans le navigateur : clé → [balise, identifiant]. */
+    _children: Record<string, [string, string]>;
+    _previousChildren: Record<string, [string, string]>;
+    /** HTML affiché tant qu'un composant « lazy » n'est pas chargé : une seule racine. */
+    placeholder(): string | Promise<string>;
+    /**
+     * Monte un composant enfant et rend son HTML, à insérer dans le rendu du parent (équivalent de `@livewire`).
+     * Si le navigateur possède déjà cet enfant (même clé), seule une souche est rendue : le client conserve l'enfant tel quel.
+     * `lazy` : l'enfant affiche son `placeholder()` et se charge quand il devient visible.
+     */
+    mountChild(name: string, params: Record<string, unknown>, key: string, options?: {
+        lazy?: boolean;
+    }): Promise<string>;
+    /** Rend le HTML du composant : une seule racine. */
+    abstract render(): string | Promise<string>;
+    mount(_params: Record<string, unknown>): void | Promise<void>;
+    boot(): void | Promise<void>;
+    hydrate(): void | Promise<void>;
+    dehydrate(): void | Promise<void>;
+    get id(): string;
+    /** `self` : l'événement n'est reçu que par ce composant (équivalent de `->self()`). */
+    dispatch(name: string, params?: Record<string, unknown> | unknown[], options?: {
+        self?: boolean;
+    }): void;
+    redirect(url: string, navigate?: boolean): void;
+    skipRender(): void;
+    /** Rendu partiel à la Filament : seul le fragment `wire:partial="<nom>"` est renvoyé (effects.partials), sans re-rendre tout le composant. */
+    renderPartial(name: string, html: string): void;
+    addError(path: string, message: string): void;
+    resetErrorBag(): void;
+}
+/**
+ * Méthodes appelables depuis le navigateur : uniquement celles que la classe (ou une classe parente) nomme dans `static callable`.
+ * TypeScript efface `protected` et `private` à l'exécution : sans cette liste, toute méthode interne serait appelable par une
+ * requête forgée, et sa valeur de retour renvoyée au navigateur.
+ */
+export declare function callableMethods(component: Component): Set<string>;
+export declare function publicProperties(component: Component): string[];
+export declare function dehydrateValue(value: unknown): unknown;
+export declare function hydrateValue(value: unknown): unknown;
+/** Équivalent de Utils::insertAttributesIntoHtmlRoot : pose des attributs sur la balise racine. */
+export declare function insertAttributesIntoHtmlRoot(html: string, attributes: Record<string, unknown>): string;
+export type RuntimeOptions = {
+    key: string;
+    locale?: string; /** Dossier des téléversements temporaires ; sans lui, les envois de fichiers sont refusés. */
+    uploads?: UploadStore;
+    uploadPrefix?: string;
+};
+export declare class WireRuntime {
+    private registry;
+    private options;
+    constructor(options: RuntimeOptions);
+    get uploads(): UploadStore | null;
+    /** Paramètres passés par un parent à ses enfants déjà présents, pendant la requête en cours : identifiant de l'enfant → paramètres. */
+    private requestScope;
+    passPropsToChild(childId: string, params: Record<string, unknown>): void;
+    register(name: string, cls: ComponentClass): this;
+    private make;
+    checksum(snapshot: Omit<Snapshot, 'checksum'>): string;
+    private snapshot;
+    /** Paramètres de montage d'un composant « lazy », signés : le navigateur les renvoie tels quels à `__lazyLoad` (conteneur `__mountParamsContainer` de Livewire). */
+    private encodeMountParams;
+    private decodeMountParams;
+    /** Comme Livewire : un paramètre de montage du même nom qu'une propriété publique y est copié. */
+    private assignMatchingProperties;
+    private renderRoot;
+    /** Premier rendu : HTML avec wire:snapshot et wire:effects sur la racine.
+     *  Le mémo ne porte `lazyLoaded` / `lazyIsolated` que pour un composant réellement « lazy » : leur seule présence fait ignorer les événements au client. */
+    mount(name: string, params?: Record<string, unknown>, request?: {
+        path?: string;
+        method?: string;
+        ctx?: unknown;
+    }): Promise<string>;
+    /** Comme mount(), mais rend aussi l'instance montée (pour lire son titre, par exemple). */
+    mountWithInstance(name: string, params?: Record<string, unknown>, request?: {
+        path?: string;
+        method?: string;
+        ctx?: unknown;
+        lazy?: boolean;
+        key?: string;
+    }): Promise<{
+        html: string;
+        component: Component;
+    }>;
+    /** Requête de mise à jour d'un composant : hydratation, mises à jour, appels, rendu, déshydratation. */
+    update(snapshot: Snapshot, updates: Record<string, unknown>, calls: Call[], ctx?: unknown): Promise<{
+        snapshot: Snapshot;
+        effects: Effects;
+    }>;
+    /** Point d'entrée HTTP : corps `{ _token, components: [{ snapshot, updates, calls }] }`. */
+    handle(body: any, ctx?: unknown): Promise<{
+        components: {
+            snapshot: string;
+            effects: Effects;
+        }[];
+        assets: unknown[];
+    }>;
+}