@navette-js/panels 0.0.0-stage → 1.0.0-beta.2

package/dist/navette/navette/motion.css

@@ -0,0 +1,101 @@
+/*
+ * Navette — mouvement et indicateurs de chargement.
+ *
+ * Écart volontaire avec FilamentPHP (décision du 2026-11-12) : cette feuille n'ajoute que du mouvement et des indicateurs,
+ * sans toucher au balisage ni aux dimensions. Elle se désactive avec `Panel.motion(false)`, ce qui rend l'interface de Filament
+ * telle quelle. Les courbes reprennent l'esprit d'iOS : ressorts doux, sorties rapides, échelle légère à la pression.
+ * Tout est neutralisé pour les personnes qui demandent moins d'animations (`prefers-reduced-motion`).
+ */
+:root {
+    --nv-spring: cubic-bezier(0.32, 0.72, 0, 1);      /* glissement amorti, sans dépassement */
+    --nv-bounce: cubic-bezier(0.2, 0.9, 0.3, 1.25);   /* léger dépassement à l'arrivée */
+    --nv-out: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    /* --- arrivée de page : le contenu monte de quelques pixels en apparaissant */
+    @keyframes nv-rise { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: none; } }
+    /* `backwards` et non `both` : une animation de `transform` qui reste appliquée après sa fin fait de l'élément le bloc conteneur de ses descendants en `position: fixed` ; le fond d'une modale ne couvrait alors que la page, pas la fenêtre. */
+    .fi-page { animation: nv-rise 0.42s var(--nv-spring) backwards; }
+    .fi-simple-main { animation: nv-rise 0.5s var(--nv-spring) backwards; }
+
+    /* --- pression : boutons, liens d'action, éléments de navigation */
+    .fi-btn, .fi-icon-btn, .fi-link, .fi-tabs-item, .fi-sidebar-item-btn, .fi-dropdown-list-item, .fi-pagination-item-btn {
+        transition: transform 0.18s var(--nv-spring), background-color 0.2s var(--nv-out), color 0.2s var(--nv-out), box-shadow 0.2s var(--nv-out), opacity 0.2s var(--nv-out);
+    }
+    .fi-btn:active:not(.fi-disabled, [disabled]), .fi-icon-btn:active:not(.fi-disabled, [disabled]) { transform: scale(0.96); }
+    .fi-link:active, .fi-tabs-item:active, .fi-sidebar-item-btn:active, .fi-dropdown-list-item:active:not(.fi-disabled), .fi-pagination-item-btn:active { transform: scale(0.97); }
+
+    /* --- modales : la fenêtre arrive avec un ressort ; le fond reste celui de Filament (voile sombre, sans flou) */
+    .fi-modal-window { transition-timing-function: var(--nv-spring) !important; transition-duration: 0.42s !important; }
+    .fi-modal-window.fi-transition-leave { transition-timing-function: var(--nv-out) !important; transition-duration: 0.2s !important; }
+
+    /* --- menus déroulants : ils s'ouvrent depuis leur déclencheur */
+    @keyframes nv-pop { from { opacity: 0; transform: scale(0.94) translateY(-4px); } to { opacity: 1; transform: none; } }
+    .fi-dropdown-panel:not([style*="display: none"]) { animation: nv-pop 0.26s var(--nv-bounce); transform-origin: top; }
+
+    /* --- notifications : entrée latérale amortie */
+    .fi-no-notification { transition-timing-function: var(--nv-spring) !important; transition-duration: 0.45s !important; }
+
+    /* --- surfaces et champs */
+    .fi-ta-row { transition: background-color 0.2s var(--nv-out); }
+    .fi-input-wrp { transition: box-shadow 0.2s var(--nv-out), background-color 0.2s var(--nv-out); }
+    .fi-toggle > :first-child { transition-timing-function: var(--nv-bounce) !important; transition-duration: 0.3s !important; }
+    .fi-badge { transition: background-color 0.2s var(--nv-out), color 0.2s var(--nv-out); }
+    .fi-sidebar-group-items { transition: opacity 0.25s var(--nv-out); }
+
+    /* --- indicateur de chargement des zones différées : une roue, au lieu d'un cadre vide */
+    @keyframes nv-spin { to { transform: rotate(360deg); } }
+    @keyframes nv-breathe { 0%, 100% { opacity: 0.55; } 50% { opacity: 1; } }
+    .fi-loading-section { position: relative; animation: nv-breathe 1.6s ease-in-out infinite; }
+    .fi-loading-section::after {
+        content: ''; position: absolute; inset: 0; margin: auto; width: 1.5rem; height: 1.5rem; border-radius: 9999px;
+        border: 2.5px solid color-mix(in oklab, currentColor 18%, transparent); border-top-color: var(--primary-500, currentColor);
+        animation: nv-spin 0.7s linear infinite;
+    }
+
+    /* --- éléments qui arrivent après l'affichage de la page : ils se déploient au lieu d'apparaître d'un coup */
+    /* compteur d'onglet (chargé après coup) : il s'élargit depuis zéro, l'onglet s'étire avec lui */
+    @keyframes nv-expand {
+        from { opacity: 0; max-width: 0; padding-inline: 0; margin-inline-start: -0.5rem; transform: scale(0.6); }
+        60% { opacity: 1; }
+        to { opacity: 1; max-width: 6rem; transform: none; }
+    }
+    .fi-tabs-item > .fi-badge { overflow: hidden; white-space: nowrap; transform-origin: left center; animation: nv-expand 0.5s var(--nv-spring) both; }
+    /* roue d'attente du compteur : elle s'efface en douceur */
+    .fi-tabs-item-badge-placeholder { transition: opacity 0.2s var(--nv-out); }
+    /* zone chargée à la demande (relation manager, widget) : son contenu monte en place quand il remplace la roue */
+    .fi-resource-relation-manager, .fi-wi-widget { animation: nv-rise 0.45s var(--nv-spring) backwards; }
+    /* lignes d'une table qui vient d'être rechargée, erreurs de validation, lignes ajoutées à un Repeater */
+    @keyframes nv-fade-in { from { opacity: 0; } to { opacity: 1; } }
+    @keyframes nv-unfold { from { opacity: 0; transform: translateY(-4px); } to { opacity: 1; transform: none; } }
+    .fi-fo-field-wrp-error-message { animation: nv-unfold 0.3s var(--nv-spring) backwards; }
+    /* `backwards` et non `both` : une animation d'opacité qui reste appliquée garde la ligne en contexte d'empilement ; la liste d'un sélecteur de la ligne passait alors sous le bouton d'ajout du Repeater. */
+    .fi-fo-table-repeater tbody tr { animation: nv-fade-in 0.3s var(--nv-out) backwards; }
+    .fi-ta-summary-row, .fi-ta-summary-header-row { animation: nv-fade-in 0.35s var(--nv-out) backwards; }
+
+    /* --- contenu qui se recharge : il s'estompe légèrement pendant la requête */
+    .fi-ta-content-ctn { transition: opacity 0.2s var(--nv-out); }
+    html[data-nv-busy] .fi-ta-content-ctn { opacity: 0.6; }
+}
+
+/* --- pastille d'activité : visible quand une requête dure (posée par motion.js) */
+.nv-busy {
+    position: fixed; top: 0.75rem; left: 50%; z-index: 60; display: flex; align-items: center; gap: 0.5rem;
+    padding: 0.4rem 0.8rem; border-radius: 9999px; font-size: 0.8125rem; font-weight: 500; pointer-events: none;
+    color: var(--gray-700); background: color-mix(in oklab, white 82%, transparent);
+    box-shadow: 0 6px 24px rgb(0 0 0 / 0.12), 0 0 0 1px rgb(0 0 0 / 0.06);
+    backdrop-filter: blur(14px) saturate(1.6); -webkit-backdrop-filter: blur(14px) saturate(1.6);
+    opacity: 0; transform: translate(-50%, -150%); transition: transform 0.4s var(--nv-spring), opacity 0.25s var(--nv-out);
+}
+.dark .nv-busy { color: var(--gray-200); background: color-mix(in oklab, var(--gray-900) 78%, transparent); box-shadow: 0 6px 24px rgb(0 0 0 / 0.4), 0 0 0 1px rgb(255 255 255 / 0.08); }
+html[data-nv-busy] .nv-busy { opacity: 1; transform: translate(-50%, 0); }
+.nv-busy::before {
+    content: ''; width: 0.875rem; height: 0.875rem; border-radius: 9999px; border: 2px solid color-mix(in oklab, currentColor 22%, transparent);
+    border-top-color: var(--primary-500, currentColor); animation: nv-spin-always 0.7s linear infinite;
+}
+@keyframes nv-spin-always { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) {
+    .nv-busy { transition: opacity 0.2s linear; transform: translate(-50%, 0); }
+    .nv-busy::before { animation-duration: 1.6s; }
+}

package/dist/navette/navette/motion.js

@@ -0,0 +1,49 @@
+// Navette — pastille d'activité : signale une requête qui dure, pour que l'écran ne paraisse jamais figé.
+// Écart volontaire avec FilamentPHP, désactivable avec `Panel.motion(false)`. Aucune dépendance : s'appuie sur les hooks de Livewire.
+(() => {
+    const DELAY = 350; // en dessous, la réponse arrive avant qu'un indicateur soit utile
+    let pending = 0;
+    let timer = null;
+
+    const pill = () => {
+        let element = document.querySelector('.nv-busy');
+        if (!element) {
+            element = document.createElement('div');
+            element.className = 'nv-busy';
+            element.setAttribute('role', 'status');
+            element.setAttribute('aria-live', 'polite');
+            // Conservée d'une page à l'autre par la navigation de Livewire.
+            element.setAttribute('wire:ignore', '');
+            element.setAttribute('x-persist', 'nv-busy');
+            element.textContent = document.documentElement.lang?.startsWith('fr') ? 'Chargement…' : 'Loading…';
+            document.body.appendChild(element);
+        }
+        return element;
+    };
+    const update = () => {
+        if (pending > 0) {
+            if (timer === null && !document.documentElement.hasAttribute('data-nv-busy')) {
+                timer = setTimeout(() => { timer = null; if (pending > 0) { pill(); document.documentElement.setAttribute('data-nv-busy', ''); } }, DELAY);
+            }
+            return;
+        }
+        if (timer !== null) { clearTimeout(timer); timer = null; }
+        document.documentElement.removeAttribute('data-nv-busy');
+    };
+    const begin = () => { pending++; update(); };
+    const end = () => { pending = Math.max(0, pending - 1); update(); };
+
+    document.addEventListener('livewire:init', () => {
+        // Chaque requête de mise à jour d'un composant.
+        window.Livewire.hook('commit', ({ succeed, fail }) => {
+            begin();
+            let done = false;
+            const finish = () => { if (!done) { done = true; end(); } };
+            succeed(finish);
+            fail(finish);
+        });
+    });
+    // Navigation entre pages.
+    document.addEventListener('livewire:navigate', begin);
+    document.addEventListener('livewire:navigated', () => { pending = 0; update(); });
+})();

package/lib/auth.d.ts

@@ -0,0 +1,61 @@
+import type { AuthProvider, TenantProvider } from './index.ts';
+/** Hashes a password with scrypt and a random salt: `$scrypt$N$r$p$salt$hash`. */
+export declare function hashPassword(password: string): Promise<string>;
+/** 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>;
+/** 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;
+/** Payload of a valid, unexpired token, otherwise `null`. */
+export declare function readToken(key: string, purpose: string, token: unknown): Record<string, unknown> | null;
+/** 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;
+/** Signs an expiring email verification URL. */
+export declare function signVerificationUrl(key: string, id: string | number, email: string, expires: number): {
+    hash: string;
+    signature: string;
+};
+export declare function checkVerificationUrl(key: string, id: string, hash: string, expires: unknown, signature: unknown): boolean;
+export type MailMessage = {
+    to: string;
+    subject: string;
+    lines: string[];
+    action?: {
+        label: string;
+        url: string;
+    };
+    outro?: string[];
+};
+/** 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>;
+}
+/** Plain-text rendering of a message. */
+export declare const mailText: (message: MailMessage) => string;
+/** Default mailer: writes the message to the console (development). */
+export declare const consoleMailer: Mailer;
+/** Appends each message to a file as one JSON line (tests, demos). */
+export declare const fileMailer: (file: string) => Mailer;
+/** Table accessor: `(table) => knex(table)`. */
+export type TableQuery = (table: string) => any;
+/**
+ * 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;
+/**
+ * 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;
+    pivot?: string;
+    foreignKey?: string;
+    userKey?: string;
+    nameAttribute?: string;
+    label?: string | null;
+}): TenantProvider;

package/lib/auth.js

@@ -0,0 +1,140 @@
+// 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';
+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))));
+/** 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')}`;
+}
+/** 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);
+    // 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');
+    if (expected.length < 16 || expected.length > 64)
+        return false;
+    const actual = await scrypt(password, Buffer.from(parts[5], 'base64url'), expected.length, { N, r, p });
+    return timingSafeEqual(expected, actual);
+}
+/** 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')))); }
+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); };
+/** 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}`)}`;
+}
+/** Payload of a valid, unexpired token, otherwise `null`. */
+export function readToken(key, purpose, token) {
+    if (typeof token !== 'string' || token.length > 2000)
+        return null;
+    const [body, mac] = token.split('.');
+    if (!body || !mac || !sameText(mac, sign(key, `${purpose}.${body}`)))
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(body, 'base64url').toString());
+        return typeof payload === 'object' && payload && Number(payload.exp) > Date.now() / 1000 ? payload : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** 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);
+/** 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}`) };
+}
+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}`));
+}
+/** Plain-text rendering of a message. */
+export const mailText = (message) => [...message.lines, ...(message.action ? ['', `${message.action.label} : ${message.action.url}`, ''] : []), ...(message.outro ?? [])].join('\n');
+/** 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', ' ');
+/**
+ * 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';
+    const toUser = (row) => (row ? { id: row.id, name: row.name, email: row.email, emailVerifiedAt: row.email_verified_at ?? null } : null);
+    const byEmail = (email) => db(table).where('email', String(email)).first();
+    return {
+        async attempt(email, password) {
+            const row = await byEmail(email);
+            if (!row) {
+                await verifyAgainstDummy(password);
+                return null;
+            }
+            const stored = String(row.password ?? '');
+            const ok = stored.startsWith('$scrypt$') ? await verifyPassword(password, stored) : Boolean(await options.verify?.(password, stored));
+            return ok ? toUser(row) : null;
+        },
+        async find(id) { return toUser(await db(table).where('id', id).first()); },
+        async findByEmail(email) { return toUser(await byEmail(email)); },
+        async create(data) {
+            await db(table).insert({ name: data.name, email: data.email, password: await hashPassword(data.password), created_at: now(), updated_at: now() });
+            return toUser(await byEmail(data.email));
+        },
+        async update(user, data) {
+            const changes = { updated_at: now() };
+            if (typeof data.name === 'string')
+                changes.name = data.name;
+            if (typeof data.email === 'string' && data.email !== user.email) {
+                changes.email = data.email;
+                changes.email_verified_at = null;
+            }
+            if (typeof data.password === 'string' && data.password !== '')
+                changes.password = await hashPassword(data.password);
+            await db(table).where('id', user.id).update(changes);
+            return toUser(await db(table).where('id', user.id).first());
+        },
+        async hasVerifiedEmail(user) { return Boolean((await db(table).where('id', user.id).first())?.email_verified_at); },
+        async markEmailAsVerified(user) { await db(table).where('id', user.id).update({ email_verified_at: now(), updated_at: now() }); },
+        async getPasswordFingerprint(user) { return fingerprint((await db(table).where('id', user.id).first())?.password); },
+    };
+}
+/**
+ * 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';
+    const foreignKey = options.foreignKey ?? 'team_id', userKey = options.userKey ?? 'user_id', nameAttribute = options.nameAttribute ?? 'name';
+    return {
+        async getTenants(user) { return db(table).join(pivot, `${pivot}.${foreignKey}`, `${table}.id`).where(`${pivot}.${userKey}`, user.id).select(`${table}.*`).orderBy(`${table}.id`); },
+        async find(key) { return /^\d+$/.test(String(key)) ? (await db(table).where('id', Number(key)).first()) ?? null : null; },
+        async canAccess(user, tenant) { return Boolean(await db(pivot).where({ [userKey]: user.id, [foreignKey]: tenant.id }).first()); },
+        getKey: (tenant) => String(tenant.id),
+        getName: (tenant) => String(tenant[nameAttribute] ?? ''),
+        getCurrentTenantLabel: () => options.label ?? null,
+        async create(data, user) {
+            const [id] = await db(table).insert({ ...data, created_at: now(), updated_at: now() });
+            const tenantId = typeof id === 'object' ? id.id : id;
+            await db(pivot).insert({ [foreignKey]: tenantId, [userKey]: user.id, created_at: now(), updated_at: now() });
+            return db(table).where('id', tenantId).first();
+        },
+        async update(tenant, data) {
+            await db(table).where('id', tenant.id).update({ ...data, updated_at: now() });
+            return db(table).where('id', tenant.id).first();
+        },
+    };
+}

package/lib/calendar.d.ts

@@ -0,0 +1,82 @@
+/** 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;
+    /** Panel color (`primary`, `success`, `warning`, `danger`, `info`, `gray`, or a registered color). */
+    color?: string | null;
+    /** URL opened on click. Without one, a click calls the widget's `onEventClick()` if it is overridden. */
+    url?: string | null;
+    openUrlInNewTab?: boolean;
+    /** Tooltip text; defaults to the title. */
+    description?: string | null;
+    /** Free-form data for `renderEvent()` and `onEventClick()`. It is never sent to the browser. */
+    extra?: Record<string, unknown>;
+};
+export type CalendarView = 'month' | 'week' | 'list';
+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;
+/** 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;
+/** 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;
+/** `HH:MM` time of an event date-time; `null` for a plain date. */
+export declare const timeOf: (value: unknown) => string | null;
+/** 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[];
+/** 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;
+    next: string;
+    today: string;
+    month: string;
+    week: string;
+    list: string;
+    more: (count: number) => string;
+    empty: string;
+};
+export declare const CALENDAR_LABELS: CalendarLabels;
+export type CalendarModel = {
+    heading: string | null;
+    view: CalendarView;
+    views: CalendarView[];
+    /** Anchor date and today's date, `YYYY-MM-DD`. */
+    anchor: string;
+    today: string;
+    firstDay: number;
+    locale: string;
+    events: CalendarEvent[];
+    maxEventsPerDay: number;
+    /** Day numbers are buttons (`selectDate`). */
+    datesClickable: boolean;
+    /** Events without a URL are buttons (`selectEvent`). */
+    eventsClickable: boolean;
+    labels: CalendarLabels;
+    /** 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;
+    /** Already-escaped HTML appended to the bottom of a day cell (total, badge…). */
+    renderDayFooter?: (day: string, events: CalendarEvent[]) => string;
+    /** Already-escaped HTML placed at the end of the toolbar (action buttons…). */
+    toolbarEnd?: string;
+};
+/** 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;
+/** Renders the whole calendar: toolbar, then the requested view. */
+export declare function renderCalendar(model: CalendarModel): string;

package/lib/calendar.js

@@ -0,0 +1,107 @@
+// 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;
+export const isDate = (value) => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) && !Number.isNaN(Date.parse(`${value}T00:00:00Z`)) && toDate(value).toISOString().slice(0, 10) === value;
+function toDate(day) { return new Date(`${day}T00:00:00Z`); }
+const iso = (date) => date.toISOString().slice(0, 10);
+export const addDays = (day, count) => iso(new Date(toDate(day).getTime() + count * DAY));
+export function addMonths(day, count) {
+    const date = toDate(day);
+    const target = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + count, 1));
+    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
+    target.setUTCDate(Math.min(date.getUTCDate(), last));
+    return iso(target);
+}
+/** 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))); };
+/** 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);
+/** `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);
+/** 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);
+        return { start, end: addDays(start, 6) };
+    }
+    if (view === 'list')
+        return { start: startOfMonth(anchor), end: endOfMonth(anchor) };
+    const start = startOfWeek(startOfMonth(anchor), firstDay);
+    const end = addDays(startOfWeek(endOfMonth(anchor), firstDay), 6);
+    return { start, end };
+}
+export function daysBetween(start, end) {
+    const days = [];
+    for (let day = start; day <= end && days.length < 400; day = addDays(day, 1))
+        days.push(day);
+    return days;
+}
+/** 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); })
+        .sort((a, b) => (dayOf(a.start) < dayOf(b.start) ? -1 : dayOf(a.start) > dayOf(b.start) ? 1 : (timeOf(a.start) ?? '').localeCompare(timeOf(b.start) ?? '') || a.title.localeCompare(b.title)));
+}
+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-]*$/;
+/** 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, "'")})`;
+/** 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;
+    const color = event.color && COLOR.test(event.color) ? event.color : 'primary';
+    const url = safeUrl(event.url);
+    const time = context.day === start ? timeOf(event.start) : null;
+    const attributes = new Attributes({
+        title: event.description ?? event.title, 'data-event': String(event.id),
+        ...(url ? { href: url, ...(event.openUrlInNewTab ? { target: '_blank', rel: 'noopener noreferrer' } : url.startsWith('/') ? { 'wire:navigate': '' } : {}) } : context.clickable ? { type: 'button', 'wire:click': call('selectEvent', event.id) } : {}),
+    }).class(['nv-cal-event', 'fi-color', `fi-color-${color}`, context.day > start ? 'nv-cal-event-continued' : null, context.day < end ? 'nv-cal-event-continues' : null]);
+    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}>`;
+}
+/** 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);
+    const days = daysBetween(range.start, range.end);
+    const format = (options, day) => new Intl.DateTimeFormat(locale, { ...options, timeZone: 'UTC' }).format(toDate(day));
+    const title = view === 'week'
+        ? `${format({ month: 'short', day: 'numeric' }, range.start)} – ${format({ month: 'short', day: 'numeric', year: 'numeric' }, range.end)}`
+        : format({ month: 'long', year: 'numeric' }, anchor);
+    const eventHtml = (event, day) => model.renderEvent?.(event, { day, view }) ?? renderCalendarEvent(event, { day, view, clickable: model.eventsClickable });
+    const dayNumber = (day, text) => (model.datesClickable
+        ? `<button type="button" wire:click="${call('selectDate', day)}" class="nv-cal-day-number">${e(text)}</button>`
+        : `<span class="nv-cal-day-number">${e(text)}</span>`);
+    const iconButton = (name, label, method) => `<button type="button" wire:click="${method}" title="${e(label)}" aria-label="${e(label)}" class="fi-icon-btn fi-size-md nv-cal-nav">${icon(name)}</button>`;
+    const switcher = model.views.length > 1
+        ? `<div class="nv-cal-views" role="group">${model.views.map((name) => `<button type="button" wire:click="${call('setView', name)}" aria-pressed="${name === view}" class="nv-cal-view${name === view ? ' nv-cal-view-active' : ''}">${e(labels[name])}</button>`).join('')}</div>`
+        : '';
+    const toolbar = `<div class="nv-cal-toolbar"><div class="nv-cal-nav-group">${iconButton('m-chevron-left', labels.previous, 'previousPeriod')}<button type="button" wire:click="goToToday" class="nv-cal-today-btn">${e(labels.today)}</button>${iconButton('m-chevron-right', labels.next, 'nextPeriod')}</div><h3 class="nv-cal-title" aria-live="polite">${e(model.heading ? `${model.heading} — ${title}` : title)}</h3><div class="nv-cal-toolbar-end">${switcher}${model.toolbarEnd ?? ''}</div></div>`;
+    let body;
+    if (view === 'list') {
+        const filled = days.map((day) => [day, eventsOn(day, model.events)]).filter(([, events]) => events.length);
+        body = filled.length
+            ? `<div class="nv-cal-list">${filled.map(([day, events]) => `<section class="nv-cal-list-day${day === today ? ' nv-cal-today' : ''}" data-date="${day}"><h4 class="nv-cal-list-date">${dayNumber(day, format({ weekday: 'long', month: 'long', day: 'numeric' }, day))}</h4><div class="nv-cal-events">${events.map((event) => eventHtml(event, day)).join('')}</div>${model.renderDayFooter?.(day, events) ?? ''}</section>`).join('')}</div>`
+            : `<p class="nv-cal-empty">${e(labels.empty)}</p>`;
+    }
+    else {
+        const month = anchor.slice(0, 7);
+        const head = days.slice(0, 7).map((day) => `<div role="columnheader" class="nv-cal-weekday">${e(format({ weekday: 'short' }, day))}</div>`).join('');
+        const cells = days.map((day) => {
+            const events = eventsOn(day, model.events);
+            const limit = view === 'month' ? Math.max(1, model.maxEventsPerDay) : events.length;
+            const shown = events.length > limit ? events.slice(0, limit - 1) : events;
+            const more = events.length - shown.length;
+            const label = view === 'week' ? format({ day: 'numeric' }, day) : String(Number(day.slice(8)));
+            return `<div role="gridcell" data-date="${day}" aria-label="${e(format({ dateStyle: 'full' }, day))}" class="nv-cal-day${view === 'month' && !day.startsWith(month) ? ' nv-cal-outside' : ''}${day === today ? ' nv-cal-today' : ''}"><div class="nv-cal-day-head">${dayNumber(day, label)}</div><div class="nv-cal-events">${shown.map((event) => eventHtml(event, day)).join('')}${more > 0 ? `<button type="button" wire:click="${call('showDay', day)}" class="nv-cal-more">${e(labels.more(more))}</button>` : ''}</div>${model.renderDayFooter?.(day, events) ?? ''}</div>`;
+        }).join('');
+        body = `<div role="grid" class="nv-cal-grid nv-cal-grid-${view}"><div role="row" class="nv-cal-weekdays">${head}</div><div class="nv-cal-days">${cells}</div></div>`;
+    }
+    return `<div class="nv-cal nv-cal-view-${view}" data-date="${anchor}" wire:loading.class="nv-cal-loading">${toolbar}${body}</div>`;
+}