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

package/lib/query-builder.d.ts

@@ -2,10 +2,10 @@ import type { ListQuery } from '@navette-js/database';
 import { Block, Builder } from '@navette-js/forms/builder';
 import { Component } from '@navette-js/schemas';
 import type { FilterIndicator, FilterState, TableFilter, TableHost } from './index.ts';
-/** Plafonds appliqués à l'arbre de règles reçu du navigateur. */
+/** Limits applied to the rule tree received from the browser. */
 export declare const MAX_RULES = 100;
 export declare const MAX_NESTING_DEPTH = 3;
-/** Nombre maximal de valeurs d'une sélection multiple. */
+/** Maximum number of values in a multiple select. */
 export declare const MAX_LIST_VALUES = 100;
 type Comparison = '=' | '!=' | '<' | '<=' | '>' | '>=';
 type Key = string | number;
@@ -29,7 +29,7 @@ export type Condition = {
     operator: Comparison;
     value: string | number;
 }
-/** Valeur renseignée (ni nulle, ni chaîne vide), ou l'inverse. */
+/** Value is filled (neither null nor an empty string), or the opposite. */
  | {
     kind: 'filled';
     column: string;
@@ -40,7 +40,7 @@ export type Condition = {
     values: Key[];
     negate: boolean;
 }
-/** Nombre d'enregistrements liés comparé à une valeur. */
+/** Number of related records compared to a value. */
  | {
     kind: 'relationCount';
     relationship: string;
@@ -48,7 +48,7 @@ export type Condition = {
     value: number;
     modify?: RelationshipQueryModifier;
 }
-/** Au moins un enregistrement lié (parmi `keys` si la liste est donnée), ou aucun (`negate`). */
+/** At least one related record (among `keys` when given), or none (`negate`). */
  | {
     kind: 'related';
     relationship: string;
@@ -56,7 +56,7 @@ export type Condition = {
     negate: boolean;
     modify?: RelationshipQueryModifier;
 };
-/** `whereHas` : les conditions s'appliquent aux enregistrements liés par la relation. */
+/** `{ relationship, nodes }`: the nodes apply to the related records (`whereExists` subquery). */
 export type ConditionNode = Condition | {
     or: ConditionNode[][];
 } | {
@@ -69,27 +69,27 @@ type Resolved = {
     condition: Condition;
     summary: string;
 };
-/** Opérateur d'une contrainte : son formulaire de réglages et sa traduction en condition. */
+/** Constraint operator: its settings form and how it turns into a condition. */
 type Operator = {
     name: string;
     label: (inverse: boolean) => string;
-    /** Réglages par défaut (null : l'opérateur n'a pas de formulaire). */
+    /** Default settings (null: the operator has no form). */
     defaults: () => Settings | null;
     fields: () => Component[];
-    /** Null quand les réglages ne passent pas la validation du formulaire : la règle est alors sans effet, comme dans Filament. */
+    /** Null when the settings fail the form's validation: the rule then has no effect. */
     resolve: (settings: Settings, inverse: boolean, constraint: Constraint) => Resolved | null;
-    /** Condition posée sur la requête principale, même quand la contrainte vise une relation (opérateurs de RelationshipConstraint). */
+    /** Condition applied to the base query even when the constraint targets a relationship (RelationshipConstraint operators). */
     onBaseQuery?: boolean;
 };
-/** Date (ou date et heure, avec `hasTime`) visée par les réglages d'un opérateur « après / avant ». */
+/** Date (or date-time, with `hasTime`) targeted by an "after / before" operator's settings. */
 export declare function resolveRuleDate(settings: Settings, now?: Date, hasTime?: boolean): string | null;
 declare const OPERATORS: Record<'text' | 'number' | 'boolean' | 'date', Operator[]>;
 type ConstraintType = keyof typeof OPERATORS | 'select' | 'relationship';
-/** Modification de la requête des enregistrements liés (knex / objection), posée par l'application. */
+/** Application-defined modifier of the related records query (knex / objection). */
 export type RelationshipQueryModifier = (query: any) => void;
 /**
- * Attribut filtrable par le constructeur de requêtes (port de Constraint). La colonne et la relation interrogées sont celles déclarées
- * ici, jamais des valeurs du navigateur : celui-ci ne choisit qu'une contrainte (par son nom) et un opérateur de sa liste.
+ * Attribute the query builder can filter on. The queried column and relationship are the ones declared here, never browser values:
+ * the browser only picks a constraint (by name) and one of its operators.
  */
 export declare class Constraint {
     readonly name: string;
@@ -101,22 +101,22 @@ export declare class Constraint {
     protected _relationship: string | null;
     protected _modifyRelationshipQuery: RelationshipQueryModifier | null;
     protected _nullable: boolean;
-    /** Modèle Objection interrogé (enregistrements de la table), pour les listes d'enregistrements liés. */
+    /** Objection model of the table's records, used to list related records. */
     protected _model: any;
     constructor(name: string, type: ConstraintType, icon: string);
     label(label: string): this;
-    /** Nom de l'attribut dans les résumés des règles (par défaut, le libellé). */
+    /** Attribute name used in rule summaries (defaults to the label). */
     attributeLabel(label: string | null): this;
     icon(name: string): this;
-    /** Colonne (ou alias de la requête) interrogée quand elle diffère du nom. */
+    /** Queried column (or query alias) when it differs from the name. */
     attribute(column: string): this;
     /**
-     * La contrainte porte sur un attribut d'enregistrements liés (`whereHas`) : `relationship('author', 'name')` filtre sur le nom de
-     * l'auteur. La relation doit être déclarée par le modèle Objection (`relationMappings`).
+     * Filters on an attribute of related records: `relationship('author', 'name')` filters on the author's name.
+     * The relationship must be declared by the Objection model (`relationMappings`).
      */
     relationship(name: string, titleAttribute: string, modifyQueryUsing?: RelationshipQueryModifier | null): this;
     modifyRelationshipQueryUsing(callback: RelationshipQueryModifier | null): this;
-    /** Ajoute l'opérateur « Is filled » / « Is blank » (port de `nullable()`). */
+    /** Adds the "Is filled" / "Is blank" operator. */
     nullable(condition?: boolean): this;
     isNullable(): boolean;
     model(model: any): this;
@@ -125,19 +125,19 @@ export declare class Constraint {
     getAttributeLabel(): string;
     getIcon(): string;
     getColumn(): string;
-    /** Relation dont les enregistrements portent l'attribut, ou `null` pour une colonne de la table. */
+    /** Relationship whose records hold the attribute, or `null` for a column of the table. */
     getRelationshipName(): string | null;
     getModifyRelationshipQueryUsing(): RelationshipQueryModifier | null;
     getOperators(): Operator[];
-    /** `contains` ou `contains.inverse` → opérateur et sens ; null si la contrainte ne le déclare pas. */
+    /** `contains` or `contains.inverse` → operator and direction; null if the constraint does not declare it. */
     parseOperator(value: unknown): {
         operator: Operator;
         inverse: boolean;
     } | null;
     getOperatorOptions(): [string, string][];
-    /** Noms de réglages connus de la contrainte, tous opérateurs confondus (un changement d'opérateur conserve les anciens, comme Filament). */
+    /** Setting names known to the constraint across all operators (switching operator keeps the previous settings). */
     getSettingNames(): string[];
-    /** Réglages dont la valeur est une liste (sélection multiple). */
+    /** Settings whose value is a list (multiple select). */
     getListSettingNames(): string[];
     getDefaultData(): Record<string, unknown>;
 }
@@ -150,7 +150,7 @@ export declare class NumberConstraint extends Constraint {
 export declare class BooleanConstraint extends Constraint {
     static make(name: string): BooleanConstraint;
 }
-/** Date ; avec `time()`, la date et l'heure (sélecteur date-heure, préréglages et unités à la minute ou à l'heure). */
+/** Date constraint; with `time()`, date and time (date-time picker, minute and hour presets and units). */
 export declare class DateConstraint extends Constraint {
     private _time;
     static make(name: string): DateConstraint;
@@ -158,13 +158,13 @@ export declare class DateConstraint extends Constraint {
     hasTime(): boolean;
     getOperators(): Operator[];
 }
-/** Valeur choisie dans une liste fixe (port de SelectConstraint) ; `multiple()` : l'une des valeurs choisies. */
+/** Value picked from a fixed list; with `multiple()`, any of the picked values. */
 export declare class SelectConstraint extends Constraint {
     private _options;
     private _multiple;
     private _searchable;
     static make(name: string): SelectConstraint;
-    /** Options `[valeur, libellé]` ou `{ valeur: libellé }` ; seules ces valeurs filtrent. */
+    /** Options as `[value, label]` pairs or `{ value: label }`; only these values can filter. */
     options(options: [string | number, string][] | Record<string, string>): this;
     getOptions(): [string, string][];
     multiple(condition?: boolean): this;
@@ -173,8 +173,8 @@ export declare class SelectConstraint extends Constraint {
     getOperators(): Operator[];
 }
 /**
- * Opérateur « Is » / « Contains » d'une RelationshipConstraint (port de IsRelatedToOperator) : les enregistrements liés sont choisis dans
- * une liste tirée du modèle lié, par leur clé ; `titleAttribute` est la colonne affichée.
+ * "Is" / "Contains" operator of a RelationshipConstraint: related records are picked by key from a list loaded from the related model;
+ * `titleAttribute` is the displayed column.
  */
 export declare class IsRelatedToOperator {
     private _titleAttribute;
@@ -193,19 +193,19 @@ export declare class IsRelatedToOperator {
     optionsLimit(limit: number): this;
     modifyRelationshipQueryUsing(callback: RelationshipQueryModifier | null): this;
     getModifyRelationshipQueryUsing(): RelationshipQueryModifier | null;
-    /** Opérateur du constructeur pour la contrainte donnée. */
+    /** Builds the query builder operator for the given constraint. */
     toOperator(constraint: RelationshipConstraint): Operator;
     getOptionsLimit(): number;
 }
 /**
- * Enregistrements liés (port de RelationshipConstraint) : nombre minimal, maximal ou exact (`multiple()`), relation vide (`emptyable()`,
- * par défaut avec `multiple()`), ou liés à des enregistrements choisis (`selectable(IsRelatedToOperator.make()…)`).
+ * Related records: minimum, maximum or exact count (`multiple()`), empty relationship (`emptyable()`, on by default with `multiple()`),
+ * or related to picked records (`selectable(IsRelatedToOperator.make()…)`).
  */
 export declare class RelationshipConstraint extends Constraint {
     private _multiple;
     private _emptyable;
     private _selectable;
-    /** Libellés des enregistrements liés cités par les règles, chargés avant le calcul des indicateurs. */
+    /** Labels of the related records cited by rules, loaded before indicators are computed. */
     private _relatedLabels;
     static make(name: string): RelationshipConstraint;
     multiple(condition?: boolean): this;
@@ -214,16 +214,16 @@ export declare class RelationshipConstraint extends Constraint {
     canBeEmpty(): boolean;
     selectable(operator: IsRelatedToOperator): this;
     getSelectableOperator(): IsRelatedToOperator | null;
-    /** Relation interrogée : celle de `relationship()`, sinon `attribute()`, sinon le nom de la contrainte. */
+    /** Queried relationship: from `relationship()`, else `attribute()`, else the constraint name. */
     getRelationshipName(): string;
     getOperators(): Operator[];
     getRelatedLabel(key: Key): string | null;
-    /** Modèle lié, retrouvé par la relation du modèle de la table (déclaré, ou celui de l'adaptateur Objection de l'hôte). */
+    /** Related model, found through the table model's relationship (declared, or the host's Objection adapter model). */
     private relatedModel;
     private relatedQuery;
-    /** Options de la liste : enregistrements du modèle lié, triés par leur titre. */
+    /** Select options: records of the related model, sorted by title. */
     loadRelatedOptions(operator: IsRelatedToOperator, host: unknown): Promise<[string, string][]>;
-    /** Charge les libellés des clés citées par des règles (indicateurs « Author is Ada or Linus »). */
+    /** Loads labels of the keys cited by rules (for indicators such as "Author is Ada or Linus"). */
     loadRelatedLabels(keys: Key[], host: unknown): Promise<void>;
 }
 type Rule = {
@@ -232,41 +232,41 @@ type Rule = {
 };
 type Rules = Record<string, Rule>;
 /**
- * Arbre de règles reçu du navigateur → arbre ne contenant que ce que le filtre déclare : types de blocs connus, opérateurs de la contrainte,
- * réglages scalaires aux noms connus, profondeur et nombre de règles bornés. Un opérateur inconnu est remis à vide (règle sans effet).
+ * Reduces the browser's rule tree to what the filter declares: known block types, the constraint's operators, scalar settings with
+ * known names, bounded depth and rule count. An unknown operator is reset to null (the rule has no effect).
  */
 export declare function sanitizeRules(constraints: Constraint[], raw: unknown, depth?: number, budget?: {
     rules: number;
 }): Rules;
-/** Règles nettoyées → conditions et libellés d'indicateurs (une entrée par règle de premier niveau qui a un effet). */
+/** Sanitized rules → conditions and indicator labels (one entry per effective top-level rule). */
 export declare function compileRules(constraints: Constraint[], rules: Rules, iteration?: number): {
     nodes: ConditionNode[];
     summaries: Record<string, string>;
 };
-/** Famille de SQL de la connexion knex de la requête. */
+/** SQL dialect of the query's knex connection. */
 export type SqlDialect = 'sqlite' | 'mysql' | 'pg' | 'mssql';
-/** Dialecte lu dans le client knex (`query.client.config.client`, ou celui de la connexion du modèle Objection) ; SQLite par défaut. */
+/** Dialect read from the knex client (`query.client.config.client`, or the Objection model's connection); SQLite by default. */
 export declare function sqlDialectOf(query: any): SqlDialect;
 /**
- * Applique des conditions à une requête knex / objection. Colonnes passées en identifiants, valeurs en paramètres liés ; les opérateurs
- * de comparaison viennent d'une liste fermée. Le SQL de date et de recherche suit le dialecte de la connexion.
+ * Applies conditions to a knex / objection query. Columns are bound as identifiers and values as parameters; comparison operators
+ * come from a closed list. Date and search SQL follows the connection's dialect.
  */
 export declare function applyConditions(query: any, nodes: ConditionNode[], dialect?: SqlDialect): void;
-/** Constructeur de règles (port de RuleBuilder) : un Builder dont les blocs sont les contraintes du filtre, plus le bloc « OR ». */
+/** Rule builder: a Builder whose blocks are the filter's constraints, plus the "OR" block. */
 export declare class RuleBuilder extends Builder {
     readonly filter: QueryBuilder;
     readonly depth: number;
     constructor(name: string, filter: QueryBuilder, depth?: number);
-    /** Le bloc « OR » n'est plus proposé (ni accepté) quand il dépasserait la profondeur autorisée ; rien ne l'est une fois le plafond de règles atteint. */
+    /** The "OR" block is neither offered nor accepted beyond the maximum depth; nothing is offered once the rule limit is reached. */
     getBlockPickerBlocks(): Block[];
     getBlock(name: unknown): Block | undefined;
     protected canAdd(): boolean;
-    /** Nombre de règles de l'arbre entier (les blocs « OR » ne comptent pas), lu dans l'état différé de l'hôte. */
+    /** Counts rules across the whole tree ("OR" blocks excluded), read from the host's deferred filter state. */
     isAtRuleLimit(): boolean;
-    /** Action de composant sans modale (utilisée aussi par les groupes « OR »). */
+    /** Component action without modal (also used by "OR" groups). */
     makeAction(name: string, handler: (args: Record<string, unknown>) => void): any;
 }
-/** Filtre « constructeur de requêtes » d'une table. */
+/** Query builder table filter. */
 export declare class QueryBuilder implements TableFilter {
     readonly name = "queryBuilder";
     private _constraints;
@@ -274,9 +274,9 @@ export declare class QueryBuilder implements TableFilter {
     private _model;
     static make(): QueryBuilder;
     constraints(constraints: Constraint[]): this;
-    /** Modèle Objection de la table, transmis aux contraintes de relation (listes d'enregistrements liés). */
+    /** Objection model of the table, passed to relationship constraints (related record lists). */
     model(model: any): this;
-    /** Avant les indicateurs : charge les libellés des enregistrements liés que citent les règles (`RelationshipConstraint.selectable`). */
+    /** Before indicators: loads labels of the related records cited by rules (`RelationshipConstraint.selectable`). */
     loadIndicatorData(state: FilterState, host: TableHost): Promise<void>;
     constraintPickerColumns(columns?: number | null): this;
     getConstraints(): Constraint[];
@@ -287,7 +287,7 @@ export declare class QueryBuilder implements TableFilter {
         placeholder: string;
         options: [string, string][];
     };
-    /** Le filtre occupe toute la largeur du formulaire des filtres. */
+    /** The filter spans the full width of the filters form. */
     getColumnSpan(): Record<string, number | string>;
     getFormComponents(): Component[];
     sanitizeState(state: unknown): FilterState;
@@ -295,7 +295,7 @@ export declare class QueryBuilder implements TableFilter {
     private compile;
     isActive(state: FilterState): boolean;
     getIndicators(state: FilterState): FilterIndicator[];
-    /** Retrait d'un indicateur : la règle de premier niveau correspondante disparaît. */
+    /** Removing an indicator removes the matching top-level rule. */
     removeIndicator(state: FilterState, field: string): FilterState;
     apply(query: Omit<ListQuery, 'page' | 'perPage'>, state: FilterState): void;
 }