@navette-js/forms 1.0.0-beta.1 → 1.0.0-beta.3

package/README.md

@@ -1,8 +1,8 @@
 # @navette-js/forms
 
-Form fields for Navette, the Node.js port of Filament.
+Form fields and validation for Navette admin panels.
 
-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/lib/builder.d.ts

@@ -2,13 +2,13 @@ import { type ColorManager } from '@navette-js/support';
 import { Action } from '@navette-js/actions';
 import { Schema, type Component } from '@navette-js/schemas';
 import { Field } from './index.ts';
-/** Clé d'élément acceptable : les clés viennent du navigateur. */
+/** Whether an item key is acceptable: keys come from the browser. */
 export declare const isItemKey: (key: string) => boolean;
-/** Clé courte à la manière de `Str::random(4)`. */
+/** Random four-character alphanumeric key. */
 export declare const shortKey: () => string;
-/** Écrit une valeur à un chemin d'état du composant hôte. */
+/** Writes a value at a state path of the host component. */
 export declare function writeState(target: any, segments: string[], value: unknown): void;
-/** Bouton-icône d'action de composant (même balisage que Filament : icône, puis indicateur de chargement). */
+/** Icon button for a component action: the icon, then a loading indicator. */
 export declare function iconActionButton(options: {
     label: string;
     icon: string;
@@ -18,14 +18,14 @@ export declare function iconActionButton(options: {
     disabled?: boolean;
     inHeader?: boolean;
 }): string;
-/** Gestionnaire de couleurs du panel de l'hôte (les pages et widgets l'exposent par `panel`). */
+/** Color manager of the host's panel (pages and widgets expose it through `panel`). */
 export declare const colorsOf: (livewire: unknown) => ColorManager | null;
 type BlockContext = {
     builder: Builder;
     itemKey: string;
     data: Record<string, unknown>;
 };
-/** Type d'élément d'un Builder (port de Builder\Block). */
+/** Item type of a Builder. */
 export declare class Block {
     readonly name: string;
     private _label;
@@ -36,9 +36,9 @@ export declare class Block {
     static make(name: string): Block;
     label(label: string | null): this;
     icon(name: string | null): this;
-    /** Composants d'un élément : une fonction, appelée pour chaque élément (ses données courantes sont fournies). */
+    /** Item components: a function called for each item (with its current data). */
     schema(factory: (ctx: BlockContext) => Component[]): this;
-    /** Données d'un nouvel élément quand elles ne se déduisent pas des valeurs par défaut des champs (champs dépendant d'un autre). */
+    /** Data of a new item when it cannot be derived from the fields' defaults (fields depending on another). */
     defaultData(factory: (builder: Builder) => Record<string, unknown>): this;
     getLabel(): string;
     getIcon(): string | null;
@@ -73,53 +73,53 @@ export declare class Builder extends Field {
     blockPickerColumns(columns?: number | null): this;
     blockPickerWidth(width: string | null): this;
     labelBetweenItems(label: string | null): this;
-    /** Sans en-tête, l'élément n'affiche que son contenu : ses actions sont alors à la charge du bloc. */
+    /** Without a header, an item only shows its content: its actions are then up to the block. */
     blockHeaders(condition?: boolean): this;
     cloneable(condition?: boolean): this;
-    /** Numéro de l'élément après le libellé du bloc (actif par défaut, comme Filament). */
+    /** Item number after the block label (on by default). */
     blockNumbers(condition?: boolean): this;
-    /** Icône du bloc dans l'en-tête de l'élément (désactivée par défaut, comme Filament). */
+    /** Block icon in the item header (off by default). */
     blockIcons(condition?: boolean): this;
-    /** Balise du libellé d'en-tête (`h2` par défaut ; Filament la déduit du niveau de titre du schéma). */
+    /** Tag of the header label (`h2` by default). */
     blockLabelHeadingTag(tag: 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p'): this;
-    /** Sélecteur « Insérer entre les blocs » entre deux éléments (actif par défaut, comme Filament). */
+    /** "Insert between blocks" picker between two items (on by default). */
     addBetweenAction(condition?: boolean): this;
     addBetweenActionLabel(label: string | null): this;
     addActionLabel(label: string | null): this;
     addActionIcon(name: string | null): this;
     addActionAlignment(alignment: 'start' | 'center' | 'end' | null): this;
     maxItems(count: number): this;
-    /** Classe ajoutée à la racine (ex. `fi-fo-builder-not-contained`). */
+    /** Class added to the root (e.g. `fi-fo-builder-not-contained`). */
     extraClass(name: string | null): this;
     generateUuidUsing(generator: () => string): this;
     getBlocks(): Block[];
     getBlock(name: unknown): Block | undefined;
-    /** Blocs proposés dans le sélecteur (une sous-classe peut en retirer). */
+    /** Blocks offered in the picker (a subclass may remove some). */
     getBlockPickerBlocks(): Block[];
-    /** Éléments bien formés : clé simple, type déclaré, données en objet. Le reste de ce qu'envoie le navigateur est ignoré. */
+    /** Well-formed items only: simple key, declared type, object data. Anything else the browser sends is ignored. */
     getItems(): Record<string, Item>;
     protected setItems(items: Record<string, Item>): void;
     getDefaultState(): unknown;
     /**
-     * Valeur enregistrée (liste `[{ type, data }]`, comme Filament, éventuellement en JSON) vers l'état du formulaire (table par clé).
-     * Les champs de chaque bloc hydratent leur propre valeur.
+     * Stored value (a `[{ type, data }]` list, possibly as JSON) to form state (a map by key).
+     * Each block's fields hydrate their own value.
      */
     hydrateState(value: unknown): unknown;
     private _storedAsList;
-    /** `false` : la valeur enregistrée reste la table par clé de l'état (filtres), au lieu de la liste `[{ type, data }]`. */
+    /** `false`: the stored value stays the keyed map of the state (filters) instead of a `[{ type, data }]` list. */
     storedAsList(condition?: boolean): this;
     finalizeDehydratedState(state: unknown): unknown;
     dehydrateState(): unknown;
-    /** Schéma d'un élément : clé `<builder>.<élément>.data`, état au même chemin (comme Filament). */
+    /** Item schema: key `<builder>.<item>.data`, state at the same path. */
     protected itemSchema(itemKey: string, item: Item): Schema;
     getChildSchemas(): Schema[];
     protected newItem(block: Block): Item;
-    /** Une sous-classe peut refuser l'ajout (plafond de règles, par exemple). */
+    /** A subclass may refuse adding (a rule cap, for instance). */
     protected canAdd(_block: Block): boolean;
     getActions(): Action[];
-    /** Copie d'un élément ; une sous-classe renouvelle les clés des éléments imbriqués. */
+    /** Copy of an item; a subclass renews the keys of nested items. */
     protected cloneItem(item: Item): Item;
-    /** Expression `mountAction(...)` d'une action de ce composant. */
+    /** `mountAction(...)` expression for an action of this component. */
     actionExpression(action: string, args: Record<string, unknown> | null): string;
     private blockPickerHtml;
     private _labelText;

package/lib/builder.js

@@ -1,7 +1,6 @@
-// @navette-js/forms/builder — port (partiel) de Filament\Forms\Components\Builder : une liste d'éléments dont chacun est un « bloc »
-// choisi dans un menu. L'état est une table `clé d'élément → { type, data }` ; l'ordre des clés est l'ordre d'affichage.
-// Portés : blocs, sélecteur de bloc, ajout / suppression / duplication / déplacement / réordonnancement, libellé entre éléments,
-// en-têtes de bloc (libellé et actions). Non portés : aperçus de bloc, repli, recherche dans le sélecteur, ajout entre éléments.
+// @navette-js/forms/builder — a list of items, each one a "block" picked from a menu.
+// The state is a map `item key → { type, data }`; key order is display order.
+// Not supported yet: block previews, collapsing, searching the block picker.
 import { Attributes, cls, e, icon, js, loadingIndicator, views, configured } from '@navette-js/support';
 import { t } from '@navette-js/support/i18n';
 import { Action } from '@navette-js/actions';
@@ -10,11 +9,11 @@ import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { Field, fillSchema } from "./index.js";
 const asset = (name) => views.render('filament-forms::asset', { path: name }).trim();
 const ITEM_KEY = /^[A-Za-z0-9_-]{1,64}$/;
-/** Clé d'élément acceptable : les clés viennent du navigateur. */
+/** Whether an item key is acceptable: keys come from the browser. */
 export const isItemKey = (key) => ITEM_KEY.test(key) && key !== '__proto__' && key !== 'constructor' && key !== 'prototype';
-/** Clé courte à la manière de `Str::random(4)`. */
+/** Random four-character alphanumeric key. */
 export const shortKey = () => Array.from(randomBytes(4), (b) => 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789'[b % 62]).join('');
-/** Écrit une valeur à un chemin d'état du composant hôte. */
+/** Writes a value at a state path of the host component. */
 export function writeState(target, segments, value) {
     let node = target;
     for (const key of segments.slice(0, -1)) {
@@ -24,9 +23,9 @@ export function writeState(target, segments, value) {
     }
     node[segments[segments.length - 1]] = value;
 }
-/** Bouton-icône d'action de composant (même balisage que Filament : icône, puis indicateur de chargement). */
+/** Icon button for a component action: the icon, then a loading indicator. */
 export function iconActionButton(options) {
-    // En-tête d'élément : Filament place `tabindex` avant `type` et la classe avant les attributs ajoutés.
+    // Item header buttons put `tabindex` before `type`, and the class before the extra attributes.
     const { tabindex = null, ...extra } = options.attributes ?? {};
     const attributes = new Attributes(options.inHeader ? {
         title: options.label, 'aria-disabled': options.disabled ? 'true' : null, 'aria-label': options.label, disabled: options.disabled ? 'disabled' : null, tabindex, type: 'button',
@@ -37,9 +36,9 @@ export function iconActionButton(options) {
     }).class(['fi-ac-icon-btn-action', 'fi-icon-btn', { 'fi-disabled': options.disabled === true }, 'fi-size-sm', ...(options.colorClasses ?? [])]);
     return `<button ${attributes.toHtml()}>${icon(options.icon, { attributes: new Attributes({ 'wire:loading.remove.delay.default': '1', 'wire:target': options.expression }) })}${loadingIndicator(new Attributes({ 'wire:loading.delay.default': '', 'wire:target': options.expression }))}</button>`;
 }
-/** Gestionnaire de couleurs du panel de l'hôte (les pages et widgets l'exposent par `panel`). */
+/** Color manager of the host's panel (pages and widgets expose it through `panel`). */
 export const colorsOf = (livewire) => livewire?.panel?.colors ?? null;
-/** Type d'élément d'un Builder (port de Builder\Block). */
+/** Item type of a Builder. */
 export class Block {
     name;
     _label = null;
@@ -50,16 +49,16 @@ export class Block {
     static make(name) { return configured(new Block(name)); }
     label(label) { this._label = label; return this; }
     icon(name) { this._icon = name; return this; }
-    /** Composants d'un élément : une fonction, appelée pour chaque élément (ses données courantes sont fournies). */
+    /** Item components: a function called for each item (with its current data). */
     schema(factory) { this._schema = factory; return this; }
-    /** Données d'un nouvel élément quand elles ne se déduisent pas des valeurs par défaut des champs (champs dépendant d'un autre). */
+    /** Data of a new item when it cannot be derived from the fields' defaults (fields depending on another). */
     defaultData(factory) { this._defaults = factory; return this; }
     getLabel() { return this._label ?? this.name.replace(/[_-]+/g, ' ').replace(/^./, (c) => c.toUpperCase()); }
     getIcon() { return this._icon; }
     getComponents(ctx) { return this._schema(ctx); }
     getDefaults(builder) { return this._defaults ? this._defaults(builder) : null; }
 }
-/** Empreinte du sélecteur de bloc : Filament y met `md5(serialize([largeur, placement, a des blocs, recherche]))`. */
+/** Precomputed block picker key hashes for common `width|placement|has blocks|searchable` signatures; others hash the signature itself. */
 const PICKER_HASHES = { 'fi-width-md|bottom-start|1|0': '8b2521a32ddb82abb3a5f4fd214c90b1', '||1|0': '9c288f69c73367423cc1eb48b3e9a82b' };
 export class Builder extends Field {
     _blocks = [];
@@ -85,31 +84,30 @@ export class Builder extends Field {
     blockPickerColumns(columns = 2) { this._pickerColumns = columns; return this; }
     blockPickerWidth(width) { this._pickerWidth = width; return this; }
     labelBetweenItems(label) { this._labelBetweenItems = label; return this; }
-    /** Sans en-tête, l'élément n'affiche que son contenu : ses actions sont alors à la charge du bloc. */
+    /** Without a header, an item only shows its content: its actions are then up to the block. */
     blockHeaders(condition = true) { this._blockHeaders = condition; return this; }
     cloneable(condition = true) { this._cloneable = condition; return this; }
-    /** Numéro de l'élément après le libellé du bloc (actif par défaut, comme Filament). */
+    /** Item number after the block label (on by default). */
     blockNumbers(condition = true) { this._blockNumbers = condition; return this; }
-    /** Icône du bloc dans l'en-tête de l'élément (désactivée par défaut, comme Filament). */
+    /** Block icon in the item header (off by default). */
     blockIcons(condition = true) { this._blockIcons = condition; return this; }
-    /** Balise du libellé d'en-tête (`h2` par défaut ; Filament la déduit du niveau de titre du schéma). */
+    /** Tag of the header label (`h2` by default). */
     blockLabelHeadingTag(tag) { this._headingTag = tag; return this; }
-    /** Sélecteur « Insérer entre les blocs » entre deux éléments (actif par défaut, comme Filament). */
+    /** "Insert between blocks" picker between two items (on by default). */
     addBetweenAction(condition = true) { this._addBetween = condition; return this; }
     addBetweenActionLabel(label) { this._addBetweenLabel = label; return this; }
     addActionLabel(label) { this._addLabel = label; return this; }
     addActionIcon(name) { this._addIcon = name; return this; }
     addActionAlignment(alignment) { this._addAlignment = alignment; return this; }
     maxItems(count) { this._maxItems = count; return this; }
-    /** Classe ajoutée à la racine (ex. `fi-fo-builder-not-contained`). */
+    /** Class added to the root (e.g. `fi-fo-builder-not-contained`). */
     extraClass(name) { this._extraClass = name; return this; }
     generateUuidUsing(generator) { this._uuid = generator; return this; }
     getBlocks() { return (this._resolvedBlocks ??= typeof this._blocks === 'function' ? this._blocks() : this._blocks); }
     getBlock(name) { return typeof name === 'string' ? this.getBlocks().find((block) => block.name === name) : undefined; }
-    /** Blocs proposés dans le sélecteur (une sous-classe peut en retirer). */
+    /** Blocks offered in the picker (a subclass may remove some). */
     getBlockPickerBlocks() { return this.getBlocks(); }
-    // --- état
-    /** Éléments bien formés : clé simple, type déclaré, données en objet. Le reste de ce qu'envoie le navigateur est ignoré. */
+    /** Well-formed items only: simple key, declared type, object data. Anything else the browser sends is ignored. */
     getItems() {
         const state = this.context().state;
         if (!state || typeof state !== 'object' || Array.isArray(state))
@@ -125,8 +123,8 @@ export class Builder extends Field {
     setItems(items) { writeState(this.livewire, this.getStatePath().split('.'), items); }
     getDefaultState() { return {}; }
     /**
-     * Valeur enregistrée (liste `[{ type, data }]`, comme Filament, éventuellement en JSON) vers l'état du formulaire (table par clé).
-     * Les champs de chaque bloc hydratent leur propre valeur.
+     * Stored value (a `[{ type, data }]` list, possibly as JSON) to form state (a map by key).
+     * Each block's fields hydrate their own value.
      */
     hydrateState(value) {
         if (typeof value === 'string') {
@@ -156,7 +154,7 @@ export class Builder extends Field {
         return items;
     }
     _storedAsList = true;
-    /** `false` : la valeur enregistrée reste la table par clé de l'état (filtres), au lieu de la liste `[{ type, data }]`. */
+    /** `false`: the stored value stays the keyed map of the state (filters) instead of a `[{ type, data }]` list. */
     storedAsList(condition = true) { this._storedAsList = condition; return this; }
     finalizeDehydratedState(state) {
         if (!this._storedAsList || !state || typeof state !== 'object' || Array.isArray(state))
@@ -164,7 +162,7 @@ export class Builder extends Field {
         return Object.values(state);
     }
     dehydrateState() { return Object.fromEntries(Object.entries(this.getItems()).map(([key, item]) => [key, { type: item.type, data: {} }])); }
-    /** Schéma d'un élément : clé `<builder>.<élément>.data`, état au même chemin (comme Filament). */
+    /** Item schema: key `<builder>.<item>.data`, state at the same path. */
     itemSchema(itemKey, item) {
         const container = this.container;
         return new Schema(container.livewire).key(`${this.getKey()}.${itemKey}.data`).statePath(`${this.getStatePath()}.${itemKey}.data`).operation(container.getOperation()).record(container.getRecord()).root(false)
@@ -180,9 +178,8 @@ export class Builder extends Field {
         fillSchema(this.itemSchema('new', item), data);
         return item;
     }
-    /** Une sous-classe peut refuser l'ajout (plafond de règles, par exemple). */
+    /** A subclass may refuse adding (a rule cap, for instance). */
     canAdd(_block) { return Object.keys(this.getItems()).length < this._maxItems; }
-    // --- actions du composant
     getActions() {
         const insert = (items, after, key, item) => {
             if (after === null || !Object.hasOwn(items, after))
@@ -225,7 +222,7 @@ export class Builder extends Field {
             }),
             Action.make('moveUp').action(move(-1)),
             Action.make('moveDown').action(move(1)),
-            // Glisser-déposer : le nouvel ordre n'est accepté que si c'est une permutation des clés existantes.
+            // Drag and drop: the new order is only accepted if it is a permutation of the existing keys.
             Action.make('reorder').action(({ arguments: args }) => {
                 const items = this.getItems();
                 const keys = Object.keys(items);
@@ -236,9 +233,9 @@ export class Builder extends Field {
             }),
         ];
     }
-    /** Copie d'un élément ; une sous-classe renouvelle les clés des éléments imbriqués. */
+    /** Copy of an item; a subclass renews the keys of nested items. */
     cloneItem(item) { return JSON.parse(JSON.stringify(item)); }
-    /** Expression `mountAction(...)` d'une action de ce composant. */
+    /** `mountAction(...)` expression for an action of this component. */
     actionExpression(action, args) {
         const context = { ...(this.livewire.getActionMountContext?.() ?? {}), schemaComponent: this.getKey() };
         return `mountAction(${js(action)}, ${args ? js(args) : '{}'}, ${js(context)})`;