@navette-js/panels 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -1,8 +1,8 @@
 # @navette-js/panels
 
-Admin panels for Node.js: a port of Filament (resources, pages, navigation, authentication, tenancy).
+Admin panels for Node.js: resources, pages, navigation, authentication, tenancy.
 
-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`.
+Part of [Navette](https://github.com/NavetteJS/navette), admin panels for Node.js. Start a project with `npm create navette@latest`, or install the framework with `npm install @navette-js/panels`.
 
 **Beta:** the API may still change between beta releases.
 

package/THIRD-PARTY-NOTICES.md

@@ -1,10 +1,10 @@
 # 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.
+Navette is an independent project, 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` |
+| [Filament](https://github.com/filamentphp/filament) © Filament | HTML markup derived 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` |

package/lib/auth.d.ts

@@ -1,16 +1,16 @@
 import type { AuthProvider, TenantProvider } from './index.ts';
-/** Empreinte d'un mot de passe (scrypt, sel aléatoire) : `$scrypt$N$r$p$sel$empreinte`. */
+/** Hashes a password with scrypt and a random salt: `$scrypt$N$r$p$salt$hash`. */
 export declare function hashPassword(password: string): Promise<string>;
-/** Compare un mot de passe à une empreinte produite par `hashPassword` (en temps constant). Toute autre empreinte est refusée. */
+/** Checks a password against a `hashPassword` hash in constant time. Any other hash format is rejected. */
 export declare function verifyPassword(password: string, stored: string | null | undefined): Promise<boolean>;
 export declare function verifyAgainstDummy(password: string): Promise<void>;
-/** Jeton signé à durée de vie limitée : `charge.signature`. `purpose` empêche de réutiliser un jeton pour un autre usage. */
+/** Signed, expiring token: `payload.signature`. `purpose` prevents reusing a token for another use. */
 export declare function signToken(key: string, purpose: string, payload: Record<string, unknown>, ttlSeconds: number): string;
-/** Charge d'un jeton valide et non expiré, sinon `null`. */
+/** Payload of a valid, unexpired token, otherwise `null`. */
 export declare function readToken(key: string, purpose: string, token: unknown): Record<string, unknown> | null;
-/** Empreinte courte d'une valeur secrète (mot de passe enregistré) : un jeton qui la contient meurt quand elle change. */
+/** Short fingerprint of a secret (the stored password hash): a token embedding it dies when the secret changes. */
 export declare const fingerprint: (value: unknown) => string;
-/** Signature des adresses de vérification d'e-mail (comme `URL::temporarySignedRoute` de Laravel). */
+/** Signs an expiring email verification URL. */
 export declare function signVerificationUrl(key: string, id: string | number, email: string, expires: number): {
     hash: string;
     signature: string;
@@ -26,30 +26,30 @@ export type MailMessage = {
     };
     outro?: string[];
 };
-/** Envoi d'un e-mail : branchez votre service (SMTP, API…). Le texte est fourni prêt à l'emploi, en lignes. */
+/** Sends an email: plug in your own service (SMTP, API…). The text is provided ready to use, as lines. */
 export interface Mailer {
     send(message: MailMessage): void | Promise<void>;
 }
-/** Rendu texte d'un message (comme les notifications « mail » de Laravel). */
+/** Plain-text rendering of a message. */
 export declare const mailText: (message: MailMessage) => string;
-/** Par défaut : le message est écrit dans la console (développement). */
+/** Default mailer: writes the message to the console (development). */
 export declare const consoleMailer: Mailer;
-/** Écrit chaque message sur une ligne JSON d'un fichier (tests, démonstration). */
+/** Appends each message to a file as one JSON line (tests, demos). */
 export declare const fileMailer: (file: string) => Mailer;
-/** Accès à une table : `(table) => knex(table)`. */
+/** Table accessor: `(table) => knex(table)`. */
 export type TableQuery = (table: string) => any;
 /**
- * Utilisateurs dans une table au format de Laravel (`users` : id, name, email, password, email_verified_at).
- * Les mots de passe sont hachés par `hashPassword` (scrypt). Pour accepter d'autres empreintes (bcrypt de Laravel…),
- * fournissez `verify(motDePasse, empreinte)` : il est consulté pour toute empreinte qui n'est pas au format scrypt.
+ * Users stored in a `users` table (id, name, email, password, email_verified_at).
+ * Passwords are hashed with `hashPassword` (scrypt). To accept other hash formats (bcrypt…), pass
+ * `verify(password, hash)`: it is called for any stored hash that is not in scrypt format.
  */
 export declare function knexAuthProvider(db: TableQuery, options?: {
     table?: string;
     verify?: (password: string, hash: string) => boolean | Promise<boolean>;
 }): AuthProvider;
 /**
- * Locataires (équipes) dans une table, liés aux utilisateurs par une table pivot — comme `teams` et `team_user` de la démo Filament.
- * `label` : texte au-dessus du nom dans le menu (« Current team »), comme `HasCurrentTenantLabel`.
+ * Tenants (teams) stored in a table and linked to users through a pivot table (`teams` and `team_user` by default).
+ * `label`: text shown above the tenant name in the menu ("Current team").
  */
 export declare function knexTenantProvider(db: TableQuery, options?: {
     table?: string;

package/lib/auth.js

@@ -1,23 +1,22 @@
-// Authentification complète : hachage des mots de passe, jetons signés (réinitialisation, vérification de l'adresse),
-// envoi des e-mails, et fournisseurs prêts à l'emploi sur une base knex (utilisateurs, locataires).
+// Authentication building blocks: password hashing, signed tokens (password reset, email verification),
+// mailers, and ready-made knex providers (users, tenants).
 import { appendFileSync } from 'node:fs';
 import { createHash, createHmac, randomBytes, scrypt as scryptCallback, timingSafeEqual } from 'node:crypto';
-// ------------------------------------------------------------------ mots de passe
 const SCRYPT_COST = { N: 16384, r: 8, p: 1 };
 const scrypt = (password, salt, length, options) => new Promise((resolve, reject) => scryptCallback(password, salt, length, { ...options, maxmem: 256 * 1024 * 1024 }, (error, key) => (error ? reject(error) : resolve(key))));
-/** Empreinte d'un mot de passe (scrypt, sel aléatoire) : `$scrypt$N$r$p$sel$empreinte`. */
+/** Hashes a password with scrypt and a random salt: `$scrypt$N$r$p$salt$hash`. */
 export async function hashPassword(password) {
     const salt = randomBytes(16);
     const hash = await scrypt(password, salt, 32, SCRYPT_COST);
     return `$scrypt$${SCRYPT_COST.N}$${SCRYPT_COST.r}$${SCRYPT_COST.p}$${salt.toString('base64url')}$${hash.toString('base64url')}`;
 }
-/** Compare un mot de passe à une empreinte produite par `hashPassword` (en temps constant). Toute autre empreinte est refusée. */
+/** Checks a password against a `hashPassword` hash in constant time. Any other hash format is rejected. */
 export async function verifyPassword(password, stored) {
     const parts = String(stored ?? '').split('$');
     if (parts.length !== 7 || parts[1] !== 'scrypt')
         return false;
     const [N, r, p] = parts.slice(2, 5).map(Number);
-    // Paramètres bornés : une empreinte forgée ne peut pas faire travailler le serveur indéfiniment.
+    // Bounded parameters: a forged hash cannot make the server work indefinitely.
     if (![N, r, p].every(Number.isInteger) || N < 2 || N > 2 ** 20 || r < 1 || r > 32 || p < 1 || p > 16)
         return false;
     const expected = Buffer.from(parts[6], 'base64url');
@@ -26,18 +25,17 @@ export async function verifyPassword(password, stored) {
     const actual = await scrypt(password, Buffer.from(parts[5], 'base64url'), expected.length, { N, r, p });
     return timingSafeEqual(expected, actual);
 }
-/** Empreinte de référence : vérifiée quand l'adresse est inconnue, pour que la réponse prenne le même temps. */
+/** Verified when the email is unknown, so the response takes the same time (no user enumeration by timing). */
 let dummyHash = null;
 export async function verifyAgainstDummy(password) { await verifyPassword(password, await (dummyHash ??= hashPassword(randomBytes(16).toString('hex')))); }
-// ------------------------------------------------------------------ jetons signés
 const sign = (key, value) => createHmac('sha256', key).update(value).digest('base64url');
 const sameText = (a, b) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y); };
-/** Jeton signé à durée de vie limitée : `charge.signature`. `purpose` empêche de réutiliser un jeton pour un autre usage. */
+/** Signed, expiring token: `payload.signature`. `purpose` prevents reusing a token for another use. */
 export function signToken(key, purpose, payload, ttlSeconds) {
     const body = Buffer.from(JSON.stringify({ ...payload, exp: Math.floor(Date.now() / 1000) + ttlSeconds })).toString('base64url');
     return `${body}.${sign(key, `${purpose}.${body}`)}`;
 }
-/** Charge d'un jeton valide et non expiré, sinon `null`. */
+/** Payload of a valid, unexpired token, otherwise `null`. */
 export function readToken(key, purpose, token) {
     if (typeof token !== 'string' || token.length > 2000)
         return null;
@@ -52,9 +50,9 @@ export function readToken(key, purpose, token) {
         return null;
     }
 }
-/** Empreinte courte d'une valeur secrète (mot de passe enregistré) : un jeton qui la contient meurt quand elle change. */
+/** Short fingerprint of a secret (the stored password hash): a token embedding it dies when the secret changes. */
 export const fingerprint = (value) => createHash('sha256').update(String(value ?? '')).digest('base64url').slice(0, 22);
-/** Signature des adresses de vérification d'e-mail (comme `URL::temporarySignedRoute` de Laravel). */
+/** Signs an expiring email verification URL. */
 export function signVerificationUrl(key, id, email, expires) {
     const hash = createHash('sha1').update(email).digest('hex');
     return { hash, signature: sign(key, `verify-email.${id}.${hash}.${expires}`) };
@@ -63,17 +61,17 @@ export function checkVerificationUrl(key, id, hash, expires, signature) {
     const at = Number(expires);
     return Number.isFinite(at) && at > Date.now() / 1000 && typeof signature === 'string' && sameText(signature, sign(key, `verify-email.${id}.${hash}.${at}`));
 }
-/** Rendu texte d'un message (comme les notifications « mail » de Laravel). */
+/** Plain-text rendering of a message. */
 export const mailText = (message) => [...message.lines, ...(message.action ? ['', `${message.action.label} : ${message.action.url}`, ''] : []), ...(message.outro ?? [])].join('\n');
-/** Par défaut : le message est écrit dans la console (développement). */
-export const consoleMailer = { send(message) { console.log(`[navette:mail] À ${message.to} — ${message.subject}\n${mailText(message)}`); } };
-/** Écrit chaque message sur une ligne JSON d'un fichier (tests, démonstration). */
+/** Default mailer: writes the message to the console (development). */
+export const consoleMailer = { send(message) { console.log(`[navette:mail] To ${message.to} — ${message.subject}\n${mailText(message)}`); } };
+/** Appends each message to a file as one JSON line (tests, demos). */
 export const fileMailer = (file) => ({ send(message) { appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...message }) + '\n'); } });
 const now = () => new Date().toISOString().slice(0, 19).replace('T', ' ');
 /**
- * Utilisateurs dans une table au format de Laravel (`users` : id, name, email, password, email_verified_at).
- * Les mots de passe sont hachés par `hashPassword` (scrypt). Pour accepter d'autres empreintes (bcrypt de Laravel…),
- * fournissez `verify(motDePasse, empreinte)` : il est consulté pour toute empreinte qui n'est pas au format scrypt.
+ * Users stored in a `users` table (id, name, email, password, email_verified_at).
+ * Passwords are hashed with `hashPassword` (scrypt). To accept other hash formats (bcrypt…), pass
+ * `verify(password, hash)`: it is called for any stored hash that is not in scrypt format.
  */
 export function knexAuthProvider(db, options = {}) {
     const table = options.table ?? 'users';
@@ -115,8 +113,8 @@ export function knexAuthProvider(db, options = {}) {
     };
 }
 /**
- * Locataires (équipes) dans une table, liés aux utilisateurs par une table pivot — comme `teams` et `team_user` de la démo Filament.
- * `label` : texte au-dessus du nom dans le menu (« Current team »), comme `HasCurrentTenantLabel`.
+ * Tenants (teams) stored in a table and linked to users through a pivot table (`teams` and `team_user` by default).
+ * `label`: text shown above the tenant name in the menu ("Current team").
  */
 export function knexTenantProvider(db, options = {}) {
     const table = options.table ?? 'teams', pivot = options.pivot ?? 'team_user';

package/lib/calendar.d.ts

@@ -1,17 +1,17 @@
-/** Un événement. `start` et `end` sont des dates `YYYY-MM-DD` ou des dates-heures ISO (`2026-11-12T09:30`) ; `end` est inclus. */
+/** A calendar event. `start` and `end` are `YYYY-MM-DD` dates or ISO date-times (`2026-11-12T09:30`); `end` is inclusive. */
 export type CalendarEvent = {
     id: string | number;
     title: string;
     start: string;
     end?: string | null;
-    /** Couleur du panel (`primary`, `success`, `warning`, `danger`, `info`, `gray`, ou une couleur déclarée). */
+    /** Panel color (`primary`, `success`, `warning`, `danger`, `info`, `gray`, or a registered color). */
     color?: string | null;
-    /** Adresse ouverte au clic. Sans adresse, le clic appelle `onEventClick()` du widget s'il est redéfini. */
+    /** URL opened on click. Without one, a click calls the widget's `onEventClick()` if it is overridden. */
     url?: string | null;
     openUrlInNewTab?: boolean;
-    /** Texte de l'infobulle ; par défaut, le titre. */
+    /** Tooltip text; defaults to the title. */
     description?: string | null;
-    /** Données libres, à disposition de `renderEvent()` et de `onEventClick()`. Elles ne sont pas envoyées au navigateur. */
+    /** Free-form data for `renderEvent()` and `onEventClick()`. It is never sent to the browser. */
     extra?: Record<string, unknown>;
 };
 export type CalendarView = 'month' | 'week' | 'list';
@@ -19,21 +19,21 @@ export declare const CALENDAR_VIEWS: CalendarView[];
 export declare const isDate: (value: unknown) => value is string;
 export declare const addDays: (day: string, count: number) => string;
 export declare function addMonths(day: string, count: number): string;
-/** Premier jour de la semaine contenant `day` ; `firstDay` : 0 = dimanche, 1 = lundi… */
+/** First day of the week containing `day`; `firstDay`: 0 = Sunday, 1 = Monday… */
 export declare const startOfWeek: (day: string, firstDay?: number) => string;
 export declare const startOfMonth: (day: string) => string;
 export declare const endOfMonth: (day: string) => string;
-/** Jour (`YYYY-MM-DD`) d'une date ou d'une date-heure d'événement ; nul si la valeur est illisible. */
+/** Day (`YYYY-MM-DD`) of an event date or date-time; `null` if the value is unreadable. */
 export declare const dayOf: (value: unknown) => string | null;
-/** Heure `HH:MM` d'une date-heure d'événement, nulle pour une date seule. */
+/** `HH:MM` time of an event date-time; `null` for a plain date. */
 export declare const timeOf: (value: unknown) => string | null;
-/** Jours affichés par une vue autour de la date d'ancrage : le mois complété en semaines entières, la semaine, ou le mois (liste). */
+/** Days shown by a view around the anchor date: the month padded to whole weeks, the week, or the month (list). */
 export declare function visibleRange(view: CalendarView, anchor: string, firstDay?: number): {
     start: string;
     end: string;
 };
 export declare function daysBetween(start: string, end: string): string[];
-/** Événements d'un jour, ceux qui ont commencé plus tôt d'abord, puis par heure et par titre. */
+/** Events on a day: those that started earlier first, then by time and title. */
 export declare function eventsOn(day: string, events: CalendarEvent[]): CalendarEvent[];
 export type CalendarLabels = {
     previous: string;
@@ -50,33 +50,33 @@ export type CalendarModel = {
     heading: string | null;
     view: CalendarView;
     views: CalendarView[];
-    /** Date d'ancrage et date du jour, `YYYY-MM-DD`. */
+    /** Anchor date and today's date, `YYYY-MM-DD`. */
     anchor: string;
     today: string;
     firstDay: number;
     locale: string;
     events: CalendarEvent[];
     maxEventsPerDay: number;
-    /** Les numéros de jour sont des boutons (`selectDate`). */
+    /** Day numbers are buttons (`selectDate`). */
     datesClickable: boolean;
-    /** Les événements sans adresse sont des boutons (`selectEvent`). */
+    /** Events without a URL are buttons (`selectEvent`). */
     eventsClickable: boolean;
     labels: CalendarLabels;
-    /** Remplace le rendu d'un événement : rendre du HTML déjà échappé, ou `null` pour garder le rendu par défaut. */
+    /** Overrides an event's rendering: return already-escaped HTML, or `null` to keep the default. */
     renderEvent?: (event: CalendarEvent, context: {
         day: string;
         view: CalendarView;
     }) => string | null;
-    /** HTML ajouté au bas de la case d'un jour (total, pastille…), déjà échappé. */
+    /** Already-escaped HTML appended to the bottom of a day cell (total, badge…). */
     renderDayFooter?: (day: string, events: CalendarEvent[]) => string;
-    /** HTML placé à droite de la barre d'outils (boutons d'action…), déjà échappé. */
+    /** Already-escaped HTML placed at the end of the toolbar (action buttons…). */
     toolbarEnd?: string;
 };
-/** Rendu par défaut d'un événement : un lien, un bouton ou un simple bloc, selon ce qu'un clic peut faire. */
+/** Default event rendering: a link, a button or a plain block, depending on what a click can do. */
 export declare function renderCalendarEvent(event: CalendarEvent, context: {
     day: string;
     view: CalendarView;
     clickable: boolean;
 }): string;
-/** Rend le calendrier complet : barre d'outils, puis la vue demandée. */
+/** Renders the whole calendar: toolbar, then the requested view. */
 export declare function renderCalendar(model: CalendarModel): string;

package/lib/calendar.js

@@ -1,5 +1,5 @@
-// Calendrier — composant propre à Navette (Filament n'en fournit pas) : dates, grille et rendu, sans dépendance au runtime.
-// Le widget `CalendarWidget` (index.ts) s'appuie sur ce module ; chaque morceau du rendu peut être remplacé.
+// Calendar: date helpers, grid and rendering, with no runtime dependency.
+// `CalendarWidget` (index.ts) builds on this module; every part of the rendering can be replaced.
 import { Attributes, e, icon } from '@navette-js/support';
 export const CALENDAR_VIEWS = ['month', 'week', 'list'];
 const DAY = 86400000;
@@ -14,15 +14,15 @@ export function addMonths(day, count) {
     target.setUTCDate(Math.min(date.getUTCDate(), last));
     return iso(target);
 }
-/** Premier jour de la semaine contenant `day` ; `firstDay` : 0 = dimanche, 1 = lundi… */
+/** First day of the week containing `day`; `firstDay`: 0 = Sunday, 1 = Monday… */
 export const startOfWeek = (day, firstDay = 1) => addDays(day, -((toDate(day).getUTCDay() - firstDay + 7) % 7));
 export const startOfMonth = (day) => `${day.slice(0, 8)}01`;
 export const endOfMonth = (day) => { const date = toDate(day); return iso(new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + 1, 0))); };
-/** Jour (`YYYY-MM-DD`) d'une date ou d'une date-heure d'événement ; nul si la valeur est illisible. */
+/** Day (`YYYY-MM-DD`) of an event date or date-time; `null` if the value is unreadable. */
 export const dayOf = (value) => (typeof value === 'string' && isDate(value.slice(0, 10)) ? value.slice(0, 10) : null);
-/** Heure `HH:MM` d'une date-heure d'événement, nulle pour une date seule. */
+/** `HH:MM` time of an event date-time; `null` for a plain date. */
 export const timeOf = (value) => (typeof value === 'string' ? (/^\d{4}-\d{2}-\d{2}[T ](\d{2}:\d{2})/.exec(value)?.[1] ?? null) : null);
-/** Jours affichés par une vue autour de la date d'ancrage : le mois complété en semaines entières, la semaine, ou le mois (liste). */
+/** Days shown by a view around the anchor date: the month padded to whole weeks, the week, or the month (list). */
 export function visibleRange(view, anchor, firstDay = 1) {
     if (view === 'week') {
         const start = startOfWeek(anchor, firstDay);
@@ -40,7 +40,7 @@ export function daysBetween(start, end) {
         days.push(day);
     return days;
 }
-/** Événements d'un jour, ceux qui ont commencé plus tôt d'abord, puis par heure et par titre. */
+/** Events on a day: those that started earlier first, then by time and title. */
 export function eventsOn(day, events) {
     return events
         .filter((event) => { const start = dayOf(event.start); const end = dayOf(event.end ?? event.start) ?? start; return start !== null && start <= day && day <= (end < start ? start : end); })
@@ -48,10 +48,10 @@ export function eventsOn(day, events) {
 }
 export const CALENDAR_LABELS = { previous: 'Previous', next: 'Next', today: 'Today', month: 'Month', week: 'Week', list: 'List', more: (count) => `+${count} more`, empty: 'No events.' };
 const COLOR = /^[a-z][a-z0-9-]*$/;
-/** Seules une adresse du site (`/…`) ou une adresse http(s) deviennent un lien. */
+/** Only a same-site path (`/…`) or an http(s) URL becomes a link (no `javascript:` or protocol-relative URLs). */
 const safeUrl = (url) => (typeof url === 'string' && /^(\/(?!\/)|https?:\/\/)/.test(url) ? url : null);
 const call = (method, argument) => `${method}(${JSON.stringify(String(argument)).replace(/"/g, "'")})`;
-/** Rendu par défaut d'un événement : un lien, un bouton ou un simple bloc, selon ce qu'un clic peut faire. */
+/** Default event rendering: a link, a button or a plain block, depending on what a click can do. */
 export function renderCalendarEvent(event, context) {
     const start = dayOf(event.start);
     const end = dayOf(event.end ?? event.start) ?? start;
@@ -65,7 +65,7 @@ export function renderCalendarEvent(event, context) {
     const tag = url ? 'a' : context.clickable ? 'button' : 'div';
     return `<${tag} ${attributes.toHtml()}>${time ? `<time class="nv-cal-event-time">${e(time)}</time>` : ''}<span class="nv-cal-event-title">${e(event.title)}</span></${tag}>`;
 }
-/** Rend le calendrier complet : barre d'outils, puis la vue demandée. */
+/** Renders the whole calendar: toolbar, then the requested view. */
 export function renderCalendar(model) {
     const { view, anchor, today, firstDay, locale, labels } = model;
     const range = visibleRange(view, anchor, firstDay);