@abyss-project/commons-front-core 3.0.0 → 3.1.0

package/dist/components/PdfEditor/types.d.ts

@@ -2,7 +2,13 @@ import { ReactNode } from 'react';
 import { AssetKind } from '@abyss-project/main';
 import { ISpace, IFile } from '@abyss-project/cloud';
 import { SupportCloudImportProps } from '../Support/types';
+/**
+ * Wiring for cloud-backed insertions inside the editor (currently only the
+ * "Insert pages" button). Includes the standard cloud picker props plus a
+ * helper to materialize bytes from the picked file.
+ */
 export interface PdfEditorCloudImportProps extends SupportCloudImportProps {
+    /** Resolve the raw bytes for a picked cloud file (e.g. via presigned URL). */
     downloadCloudFile: (cloud: ISpace, file: IFile) => Promise<ArrayBuffer>;
 }
 export declare enum PdfOperationType {
@@ -38,8 +44,11 @@ export type PdfOperation = {
     text: string;
     fontSize: number;
     color: string;
+    /** Font family; default 'sans' (Helvetica). */
     fontFamily?: TextFontFamily;
+    /** 0..1; default 1. Used by watermarks. */
     opacity?: number;
+    /** Counter-clockwise degrees around the text anchor; default 0 (watermark). */
     rotationDeg?: number;
 } | {
     opId: string;
@@ -68,6 +77,7 @@ export type PdfOperation = {
     y2: number;
     color: string;
     strokeWidth: number;
+    /** Fill color for rect/ellipse (hex). null = no fill (outline only). */
     fill?: string | null;
 } | {
     opId: string;
@@ -120,6 +130,21 @@ export type PdfOperation = {
     opId: string;
     type: PdfOperationType.FLATTEN;
 };
+/**
+ * One variant of the operation union, addressed by its discriminant.
+ *
+ * `PdfOperation` is an anonymous union, so a value annotated with it is the WHOLE union: a
+ * spread like `{ ...op, x }` then fails, because most members carry no `x`. Callers that
+ * genuinely hold one variant (a test builder, a tool that only emits text) say so with this
+ * helper instead of widening and casting back.
+ */
+export type PdfOperationOf<T extends PdfOperationType> = Extract<PdfOperation, {
+    type: T;
+}>;
+/** The subset of operations that carry per-page coordinates. */
+export type PdfPageScopedOperation = Extract<PdfOperation, {
+    pageIndex: number;
+}>;
 export type ExportOption = 'DOWNLOAD' | 'CLOUD_NEW_FILE' | 'CLOUD_REPLACE';
 export type ExportRequest = {
     kind: 'DOWNLOAD';
@@ -219,14 +244,21 @@ export interface AssetPaletteItem {
     id: string;
     kind: AssetKind;
     name: string;
+    /** Full-resolution download URL for image-mode assets; null for text-mode
+     *  (TEXT_BLOCK or typed INITIALS). Used when placing the asset on the PDF. */
     downloadUrl: string | null;
+    /** Small (256x256) thumbnail URL — preferred for grid previews so the
+     *  picker stays light. Falls back to downloadUrl when null. */
     thumbnailUrl?: string | null;
+    /** Raw text payload — set for TEXT_BLOCK and typed-mode INITIALS. */
     textContent?: string | null;
 }
 export interface AssetPaletteOrgBucket {
     id: string;
     name: string;
     items: AssetPaletteItem[];
+    /** Optional pre-rendered avatar node (host-injected, e.g. OrganizationAvatar)
+     *  used by the scope selector inside the picker. */
     avatar?: ReactNode;
 }
 export interface AssetPaletteProjectBucket {
@@ -237,11 +269,23 @@ export interface AssetPaletteProjectBucket {
     avatar?: ReactNode;
 }
 export interface AssetPalette {
+    /** Personal assets (the current user's). */
     personal: AssetPaletteItem[];
+    /** Optional pre-rendered avatar for the personal bucket — used by the
+     *  picker's scope selector to keep visuals consistent with the host app. */
     personalAvatar?: ReactNode;
+    /** Optional org-scoped assets, one bucket per organization the user is a
+     *  member of. */
     organizations?: AssetPaletteOrgBucket[];
+    /** Optional project-scoped assets, one bucket per project the user has
+     *  access to. */
     projects?: AssetPaletteProjectBucket[];
 }
+/** Called when the user clicks "Save signature" in the picker.
+ *  The implementation uploads the dataUrl as a SIGNATURE/INITIALS/STAMP asset.
+ *  - `projectId` set → PROJECT scope (organizationId required too).
+ *  - `organizationId` set (no projectId) → ORG scope.
+ *  - neither set → personal (USER) scope. */
 export type SaveSignatureFn = (params: {
     dataUrl: string;
     kind: AssetKind;
@@ -249,29 +293,70 @@ export type SaveSignatureFn = (params: {
     organizationId?: string | null;
     projectId?: string | null;
 }) => Promise<void>;
+/**
+ * Optional callback invoked debounced (800ms) after operations change,
+ * carrying the FULL list of current operations since the last successful flush.
+ * Hosts wiring a custom persistence backend should dedupe by op.opId
+ * (idempotent). Leave undefined for pure client-side editing.
+ */
 export type OperationsAdapter = (params: {
     operations: PdfOperation[];
 }) => Promise<void>;
+/**
+ * Optional host-provided PDF post-processors. pdf-lib cannot write/strip
+ * encryption nor truly recompress, so these heavy operations are delegated to
+ * the host (which wires a WASM engine like qpdf). Keeping the engine in the host
+ * means the multi-MB WASM never bloats the shared bundle: only apps that opt in
+ * pay for it, and it loads lazily when the user actually runs the action. The
+ * editor surfaces each action only when its callback is provided.
+ */
 export interface PdfSecurity {
+    /** Encrypt the baked PDF with a user password; resolves to encrypted bytes. */
     setPassword?: (bytes: Uint8Array, password: string) => Promise<Uint8Array>;
+    /** Decrypt a password-protected PDF; resolves to plain bytes. */
     removePassword?: (bytes: Uint8Array, password: string) => Promise<Uint8Array>;
+    /** Recompress / optimize the baked PDF; resolves to the smaller bytes. */
     compress?: (bytes: Uint8Array) => Promise<Uint8Array>;
 }
 export interface PdfEditorProps {
     source: PdfSource;
     mode: PdfEditorMode;
+    /** Initial server-loaded operations (replayed on mount). */
     initialOperations?: PdfOperation[];
+    /** Persist new operations server-side (debounced 800ms). */
     operationsAdapter?: OperationsAdapter;
+    /** Authenticated-mode asset palette — enables Saved tab and Save button in SignaturePicker.
+     *  When omitted, the editor runs in anonymous mode (2-tab picker, no save action). */
     assetPalette?: AssetPalette;
+    /** Resolve a saved (server-stored) asset to a data URL ready to embed.
+     *  Authenticated hosts implement this via a presigned download so it works
+     *  cross-origin — a bare fetch of the storage public-access URL is CORS-blocked
+     *  even though an <img> of the same URL renders. When omitted, the editor falls
+     *  back to fetching `item.downloadUrl` (correct for anonymous local `data:` URLs). */
     resolveAssetBytes?: (item: AssetPaletteItem) => Promise<string>;
+    /** Surface a user-facing error (e.g. a toast) — used when an asset fails to
+     *  resolve so the failure is visible instead of silently doing nothing. */
     onAssetError?: (message: string) => void;
+    /** Callback to upload a new signature asset. Wire alongside assetPalette in authenticated mode. */
     onSaveSignature?: SaveSignatureFn;
     onExport: (request: ExportRequest) => Promise<void>;
     exportOptions: ExportOption[];
     readOnly?: boolean;
+    /** Optional: full cloud-import wiring. When provided, the page sidebar's
+     *  "Insert pages" button uses `ImportButton` (file + cloud picker). */
     cloudImport?: PdfEditorCloudImportProps;
+    /** Optional: deep-link to the host's asset management page (Account →
+     *  Assets). When set, the signature picker shows a "Manage" button. */
     manageAssetsUrl?: string;
+    /** Optional: when provided, the toolbar shows a "Change file" button that
+     *  invokes this callback. Hosts typically reset their PdfSource state so
+     *  the dropzone reappears. */
     onChangeSource?: () => void;
+    /** Optional: host-provided encryption/compression engine (e.g. qpdf-WASM).
+     *  Each provided callback adds its matching action to the document menu. */
     pdfSecurity?: PdfSecurity;
+    /** Optional: let the user pick an image from AbyssCloud to insert. Resolves to
+     *  a `data:` URL ready to place, or null if cancelled. When provided, the
+     *  Insert panel shows an "AbyssCloud" image source. */
     pickCloudImage?: () => Promise<string | null>;
 }

package/dist/components/PdfEditor/viewer/PageOverlay.d.ts

@@ -11,17 +11,27 @@ interface PageOverlayProps {
     pendingSignature: string | null;
     pendingText: string | null;
     pendingApplyAllPages: boolean;
+    /** Live virtual page indices (pageOrder) — the targets for "apply to all pages". */
     pageIndices: number[];
     dispatch: React.Dispatch<EditorAction>;
     drawColor?: string;
     drawStrokeWidth?: number;
+    /** New-text styling (existing text keeps its own values). */
     textColor?: string;
     textSize?: number;
     textFamily?: TextFontFamily;
+    /** Active shape kind (rect/ellipse/line/arrow) when the shape tool is on. */
     shapeKind?: ShapeKind;
+    /** Fill color for rect/ellipse shapes (hex), or null for outline only. */
     shapeFill?: string | null;
+    /** Highlighter color (hex). */
     highlightColor?: string;
+    /** Render scale (px per PDF point) — driven by the zoom control. */
     scale?: number;
+    /** Total displayed rotation (page intrinsic /Rotate + user delta), clockwise.
+     *  Annotations are stored in unrotated content space; the overlay maps pointer
+     *  input back to content space and renders inside a rotated inner layer so the
+     *  preview matches the baked output. */
     rotation?: number;
 }
 export declare const PageOverlay: React.FC<PageOverlayProps>;

package/dist/components/PdfEditor/viewer/PdfCanvas.d.ts

@@ -16,6 +16,7 @@ interface PdfCanvasProps {
     activePageIndex: number;
     pageOrder: number[];
     onPageDimensions?: (pageIndex: number, width: number, height: number, totalRotation: number, pointWidth: number) => void;
+    /** Reports the display index of the page currently dominant in the viewport. */
     onVisiblePageChange?: (displayIndex: number) => void;
     children?: (virtualIndex: number, displayIndex: number) => React.ReactNode;
 }

package/dist/components/PdfEditor/viewer/ViewerControls.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 interface ViewerControlsProps {
+    /** Current zoom as a fraction of the base scale (1 = 100%). */
     zoom: number;
     onZoomIn: () => void;
     onZoomOut: () => void;
@@ -10,7 +11,10 @@ interface ViewerControlsProps {
     currentPage: number;
     totalPages: number;
     onGoToPage: (index: number) => void;
+    /** Narrow viewport: dock as a flush full-width bottom bar (no floating pills). */
     compact?: boolean;
+    /** Width (px) of the inline page sidebar, so the floating pills center over the
+     *  PAGE region rather than the whole area (kept in sync with the placement banner). */
     sidebarWidth?: number;
 }
 export declare const ViewerControls: React.FC<ViewerControlsProps>;

package/dist/components/QuotaGauge/AbyssQuotaGauge.component.d.ts

@@ -1,14 +1,53 @@
 import { default as React } from 'react';
 import { QuotaGaugeInput } from './gauge-segments';
+/** Un repère sur l'axe : sa valeur, ce qu'il implique, et le raccourci qui permet d'agir. */
 export interface QuotaMarker {
     kind: 'threshold' | 'included' | 'ceiling';
     value: number;
+    /** Libellé de l'action, et ce qu'elle déclenche. Sans elle, la bulle informe seulement. */
     onAction?: () => void;
 }
 export interface AbyssQuotaGaugeProps extends QuotaGaugeInput {
     markers?: QuotaMarker[];
+    /** Rend une valeur dans l'unité de la métrique — « 1,5 To », « 12 000 événements ». */
     formatValue?: (value: number) => string;
+    /** Hauteur de la barre. La bulle et les repères s'y adaptent. */
     height?: number;
+    /**
+     * Tait la mention « le dépassement n'est pas autorisé » sous l'axe.
+     *
+     * À poser quand le TEXTE PORTEUR le dit déjà. Dans le bandeau compact du satellite, la phrase
+     * apparaissait deux fois à trois lignes d'intervalle : une fois sous la jauge, une fois dans le
+     * message d'état. Répétée, elle n'informe plus, elle encombre — et c'est exactement le genre de
+     * détail qui fait qu'un écran « n'est pas beau » sans qu'on sache dire pourquoi.
+     */
     hideOverageNote?: boolean;
 }
+/**
+ * LA JAUGE DE QUOTA PARTAGÉE.
+ *
+ * ═══ POURQUOI ELLE EXISTE ═══
+ *
+ * Aucune barre de progression partagée n'existait : chaque surface de facturation réimplémentait la
+ * sienne, avec ses propres couleurs de seuil. Vérifié — `commons-front-core` ne portait qu'une
+ * boîte de dialogue « quota atteint », et quatre écrans du hub avaient chacun leur `LinearProgress`.
+ *
+ * ═══ IL N'Y A PAS DE LÉGENDE, ET C'EST DÉLIBÉRÉ ═══
+ *
+ * Chaque SEGMENT porte à la fois sa couleur ET son explication. La solution « remplissage décoratif
+ * plus zone de survol invisible » ferait deux sources à garder synchronisées ; un seul nœud ne peut
+ * pas dériver. Le survol l'éclaire et fait reculer les autres — le contraste fait la lecture.
+ *
+ * ═══ UNE BULLE QUI CONTIENT UN BOUTON N'EST PAS UNE BULLE ═══
+ *
+ * Un pseudo-élément CSS ne se clique pas. Il faut un vrai nœud, survolable, qui reste ouvert quand
+ * la souris y entre — et PORTALISÉ, sinon l'`overflow: hidden` de la carte porteuse le rogne.
+ *
+ * ═══ LE CALCUL N'EST PAS ICI ═══
+ *
+ * Le placement des bulles et le découpage de l'axe vivent dans deux modules purs, testés sans
+ * navigateur sur les quatre largeurs de la spec. Les laisser dans le composant les aurait rendus
+ * vérifiables seulement à l'œil — et le premier passage du contrôle signalait quinze défauts sur
+ * quinze en mobile, dont aucun n'était visible à la relecture.
+ */
 export declare const AbyssQuotaGauge: React.FC<AbyssQuotaGaugeProps>;

package/dist/components/QuotaGauge/bubble-placement.d.ts

@@ -1,7 +1,47 @@
+/**
+ * LE PLACEMENT D'UNE BULLE DE REPÈRE SUR LA JAUGE DE QUOTA.
+ *
+ * ═══ POURQUOI CE CALCUL EST UNE FONCTION PURE, ET PAS DU CSS ═══
+ *
+ * Trois pièges, tous rencontrés en MESURANT plutôt qu'en regardant. Le contrôle qui a servi aux
+ * maquettes signalait quinze défauts sur quinze en mobile, et aucune relecture ne les aurait vus.
+ *
+ *   1. UN SEUIL EN POURCENTAGE NE MARCHE PAS. Le point de bascule entre « bulle centrée » et
+ *      « bulle collée au bord » dépend de la largeur RENDUE, qui change avec l'écran ET avec la
+ *      langue — un libellé allemand décale le basculement d'un repère qu'un libellé français
+ *      laissait tenir.
+ *
+ *   2. `left: 0` SE RÉFÈRE AU PORTEUR, PAS À LA JAUGE. Ancrer sur un bord ne suffit pas : il faut
+ *      convertir en coordonnées de jauge, sinon la bulle d'un repère à 80 % part 80 % trop à
+ *      droite.
+ *
+ *   3. SUR ÉCRAN ÉTROIT LA BULLE EST PLUS LARGE QUE LA JAUGE. Aucune position ne la fait alors
+ *      tenir : il faut la RÉTRÉCIR d'abord. C'est la ligne `min(...)` ci-dessous, et c'est elle qui
+ *      règle les quinze défauts mobiles.
+ *
+ * Sortir ce calcul du composant le rend testable sans navigateur, aux quatre largeurs de la spec,
+ * sans monter de DOM ni simuler un survol.
+ */
+/** La largeur de confort d'une bulle, en pixels. Au-delà, le texte se met à flotter. */
 export declare const BUBBLE_MAX_WIDTH = 232;
 export interface BubblePlacement {
+    /** Largeur retenue : la largeur de confort, ou celle de la jauge si elle est plus étroite. */
     width: number;
+    /** Décalage du bord GAUCHE de la bulle, en coordonnées de jauge. */
     left: number;
+    /**
+     * Décalage de la flèche À L'INTÉRIEUR de la bulle.
+     *
+     * Elle reste sous le porteur où que la bulle atterrisse : une flèche figée au centre pointerait
+     * dans le vide dès que la bulle est bornée par un bord.
+     */
     arrow: number;
 }
+/**
+ * Place une bulle sous un repère.
+ *
+ * @param markerCenter position du repère, en pixels depuis le bord gauche de la JAUGE
+ * @param gaugeWidth largeur rendue de la jauge, en pixels
+ * @param maxWidth largeur de confort de la bulle
+ */
 export declare const placeBubble: (markerCenter: number, gaugeWidth: number, maxWidth?: number) => BubblePlacement;

package/dist/components/QuotaGauge/gauge-segments.d.ts

@@ -1,24 +1,80 @@
+/**
+ * LES SEGMENTS D'UNE JAUGE DE QUOTA, ET L'AXE SUR LEQUEL ILS SE POSENT.
+ *
+ * ═══ L'AXE S'ARRÊTE AU PLAFOND, PAS AU MAXIMUM VENDABLE ═══
+ *
+ * Porter l'axe jusqu'au maximum libre-service écraserait la zone utile : un compte à 200 Go inclus
+ * dont le maximum est 5 To verrait sa limite incluse et son seuil d'alerte confondus sur 4 % de la
+ * barre. L'axe s'arrête donc au PLAFOND — le maximum réel du compte —, et le fait qu'il soit
+ * relevable devient une affordance plutôt qu'une zone à l'échelle qui mentirait.
+ *
+ * Sans plafond fixé, l'axe s'arrête à la limite incluse.
+ *
+ * ═══ POURQUOI CE CALCUL EST PUR ═══
+ *
+ * Un segment porte à la fois sa couleur ET son explication. La solution « remplissage décoratif
+ * plus zone de survol invisible » ferait deux sources à garder synchronisées ; un seul nœud ne peut
+ * pas dériver. Encore faut-il que ce nœud sache exactement où il commence et où il finit — d'où ce
+ * calcul, testable sans monter de DOM.
+ */
+/** Ce qu'un segment raconte. Le nom porte le sens, pas la couleur : le thème décide du rendu. */
 export declare enum QuotaSegmentKind {
+    /** Consommé à l'intérieur de ce que le plan inclut. */
     USED_INCLUDED = "USED_INCLUDED",
+    /** Consommé au-delà de l'inclus — facturé en dépassement. */
     USED_OVERAGE = "USED_OVERAGE",
+    /** Encore inclus, pas encore consommé. */
     FREE_INCLUDED = "FREE_INCLUDED",
+    /** Dépassement encore autorisé avant le plafond. */
     FREE_OVERAGE = "FREE_OVERAGE"
 }
 export interface QuotaSegment {
     kind: QuotaSegmentKind;
+    /** Début et fin en unités de la métrique. */
     from: number;
     to: number;
+    /** Part de l'axe, entre 0 et 1 — ce que le rendu utilise pour sa largeur. */
     ratio: number;
 }
 export interface QuotaAxis {
+    /** Fin de l'axe, en unités de la métrique. */
     max: number;
     segments: QuotaSegment[];
+    /** `true` quand l'axe s'arrête à l'inclus faute de plafond : le dépassement n'est pas autorisé. */
     overageDisallowed: boolean;
 }
 export interface QuotaGaugeInput {
+    /** Consommation courante. */
     current: number;
+    /** Ce que le plan et les modules incluent. `-1` vaut illimité. */
     includedLimit: number;
+    /**
+     * Le plafond du compte, au-delà duquel tout est refusé. `null` : aucun plafond posé, donc aucun
+     * dépassement autorisé. `-1` : dépassement sans borne.
+     */
     ceiling: number | null;
 }
+/**
+ * Découpe l'axe en segments contigus.
+ *
+ * ═══ LES TROIS CAS QUI NE SE DEVINENT PAS ═══
+ *
+ * ILLIMITÉ — une limite à `-1` n'a pas d'axe : une barre de progression vers l'infini est toujours
+ * à zéro pour cent, ce qui est vrai et inutile. On rend un axe vide, et le rendu affiche un état
+ * plutôt qu'une jauge.
+ *
+ * DÉPASSEMENT SANS BORNE — le plafond `-1` ne peut pas terminer l'axe. On le termine à la
+ * consommation courante quand elle dépasse l'inclus, sinon à l'inclus : l'axe suit alors le client
+ * au lieu de lui montrer un infini vide.
+ *
+ * CONSOMMATION AU-DELÀ DU PLAFOND — elle arrive : un plafond baissé après coup, ou un compteur
+ * rattrapé en retard. L'axe s'étend jusqu'à elle, sinon le segment consommé sortirait de la barre.
+ */
 export declare const buildQuotaAxis: ({ current, includedLimit, ceiling, }: QuotaGaugeInput) => QuotaAxis;
+/**
+ * La position d'un repère sur l'axe, en part de l'axe entre 0 et 1.
+ *
+ * Rend `null` quand le repère n'a pas sa place — pas d'axe, ou une valeur au-delà de son bout. Le
+ * rendre à 1 le collerait au bord droit et le ferait passer pour un plafond, ce qu'il n'est pas.
+ */
 export declare const markerRatio: (value: number | null, axis: QuotaAxis) => number | null;

package/dist/components/QuotaOffer/AbyssQuotaOffer.component.d.ts

@@ -1,23 +1,83 @@
 import { default as React } from 'react';
 import { QuotaMarker } from '../QuotaGauge';
 import { QuotaOfferInput } from './quota-offer-state';
+/** Une branche chiffrée. Le composant ne calcule RIEN : il reçoit le montant déjà fait. */
 export interface QuotaOfferBranch {
     kind: 'extension' | 'pack' | 'overage' | 'ceiling' | 'unlock';
+    /**
+     * Montant formaté, prêt à afficher — « 5,35 € ».
+     *
+     * `null` veut dire INDISPONIBLE, pas gratuit : le composant l'affiche comme tel plutôt que de
+     * l'estimer. Un prix inventé côté client diverge de la facture au premier changement de barème.
+     */
     price: string | null;
+    /** Taille du lot, pour l'extension. */
     lot?: number;
     onSelect?: () => void;
 }
 export interface AbyssQuotaOfferProps extends QuotaOfferInput {
+    /** Unité affichée — « Go », « membres ». */
     unit: string;
+    /** La métrique, telle que le contrat d'URL l'attend. */
     metricKey: string;
     branches: QuotaOfferBranch[];
     variant?: 'compact' | 'expanded';
     markers?: QuotaMarker[];
+    /**
+     * Rend une valeur dans l'unité de la métrique. Par défaut, `Intl` — jamais `String(v)`, qui
+     * affichait « 110000 » là où le client lit « 110 000 ».
+     */
     formatValue?: (value: number) => string;
+    /**
+     * La RACINE de facturation du hub — pas l'URL complète.
+     *
+     * LE SATELLITE NE LA CONNAÎT PAS : il la reçoit, comme il reçoit les prix. Embarquer un tunnel
+     * d'achat dans un satellite y dupliquerait Stripe, le moyen de paiement et les items
+     * d'abonnement — tout ce qui vit dans le hub, neuf fois.
+     *
+     * Le lien profond est construit ICI, avec la métrique, le geste visé et l'adresse de retour :
+     * neuf satellites qui le fabriqueraient chacun de leur côté finiraient par en perdre un morceau.
+     */
+    /**
+     * Le service qui sert cette métrique. Le point d'entrée d'offre en exige le couple complet ; le
+     * composant le reçoit du serveur, avec l'offre qu'il affiche.
+     */
     serviceKey: string;
     billingBaseUrl?: string;
+    /**
+     * L'organisation dont le quota est affiché, quand il y en a une.
+     *
+     * Le hub sert la consommation d'une organisation sur une route DISTINCTE, qui porte
+     * l'identifiant dans le chemin. Sans lui, un membre d'une organisation atterrit sur la
+     * consommation de son compte PERSONNEL : des chiffres réels, mais ceux d'un autre compte que
+     * celui qu'il regardait — pire qu'une page d'erreur, qui au moins se voit.
+     */
     organizationId?: string;
+    /** Où revenir après le geste. Généralement l'adresse courante du satellite. */
     returnUrl?: string;
     onNavigateToBilling?: () => void;
 }
+/**
+ * L'OFFRE DE QUOTA, ET SES HUIT ÉTATS.
+ *
+ * ═══ CE QU'IL NE FAIT PAS ═══
+ *
+ * Il ne CALCULE aucun prix et ne DÉRIVE aucun état : les deux arrivent tout faits, l'un du serveur,
+ * l'autre d'une fonction pure testée à part. Un `if` enfoui dans le rendu ne se vérifie qu'à l'œil,
+ * sur les quelques cas qu'on pense à ouvrir — et se tromper d'état a deux coûts opposés, tous deux
+ * chers.
+ *
+ * ═══ LES DEUX VARIANTS, ET CE QUI LES DISTINGUE VRAIMENT ═══
+ *
+ * COMPACT vit dans un satellite : une ligne au-dessus du contenu, JAMAIS devant. Son action REDIRIGE
+ * vers le hub — le satellite informe et route, il ne vend pas.
+ *
+ * ÉTENDU vit dans les pages de facturation du hub : la jauge et les branches chiffrées.
+ *
+ * ═══ AMBRE SE FERME, ROUGE NE SE FERME PAS ═══
+ *
+ * En approche, le bandeau est informatif et FERMABLE : l'utilisateur travaille, on ne lui bloque pas
+ * l'écran. Au refus, l'action vient d'échouer, le bandeau porte la cause et n'est plus fermable —
+ * c'est le seul moment où il a le droit d'insister.
+ */
 export declare const AbyssQuotaOffer: React.FC<AbyssQuotaOfferProps>;

package/dist/components/QuotaOffer/quota-offer-state.d.ts

@@ -1,22 +1,86 @@
+/**
+ * LES HUIT ÉTATS D'UNE OFFRE DE QUOTA, DÉRIVÉS PLUTÔT QUE DÉCIDÉS À L'AFFICHAGE.
+ *
+ * ═══ POURQUOI CETTE DÉRIVATION EST PURE ═══
+ *
+ * Se tromper d'état a deux coûts opposés, et tous deux sont chers : proposer un achat à un client
+ * SAIN décrédibilise l'alerte quand elle arrive vraiment, et ne rien proposer à un client BLOQUÉ le
+ * laisse devant un refus sans issue. Un `if` enfoui dans le rendu ne se vérifie qu'à l'œil, sur les
+ * quelques cas qu'on pense à ouvrir.
+ *
+ * ═══ CE QUE LE COMPOSANT NE FAIT PAS ═══
+ *
+ * Il ne CALCULE aucun prix. Les montants arrivent déjà chiffrés par le serveur, par la même
+ * fonction qui sert l'achat, la réactivation d'un module suspendu et l'aperçu de descente de gamme.
+ * Un barème dupliqué côté client dérive au premier changement, et l'écart se voit sur la facture.
+ */
+/** Les huit états, dans l'ordre de la spec. */
 export declare enum QuotaOfferState {
+    /** 1 — sous le seuil. AUCUNE action proposée. */
     HEALTHY = "HEALTHY",
+    /** 2 — seuil d'alerte franchi. Mention discrète. */
     APPROACHING = "APPROACHING",
+    /** 3 — limite atteinte, dépassement possible. Les trois branches. */
     LIMIT_REACHED = "LIMIT_REACHED",
+    /** 4 — limite atteinte, dépassement IMPOSSIBLE. Deux branches, la troisième expliquée. */
     LIMIT_REACHED_NO_OVERAGE = "LIMIT_REACHED_NO_OVERAGE",
+    /** 5 — en dépassement. L'économie chiffrée. */
     IN_OVERAGE = "IN_OVERAGE",
+    /** 6 — plafond atteint. Refus dur, deux issues. */
     CEILING_REACHED = "CEILING_REACHED",
+    /** 7 — réglage : pas de jauge, une option. */
     SETTING = "SETTING",
+    /** 8 — extension suspendue parce que le plan la couvre. */
     SUSPENDED_BY_PLAN = "SUSPENDED_BY_PLAN"
 }
 export interface QuotaOfferInput {
     current: number;
+    /** Ce que le plan et les modules incluent. `-1` vaut illimité. */
     includedLimit: number;
+    /** Plafond du compte. `null` : aucun, donc aucun dépassement autorisé. `-1` : sans borne. */
     ceiling: number | null;
+    /** Seuil d'alerte, en part de l'inclus — 0,8 pour 80 %. */
     alertThreshold: number;
+    /** Une métrique de RÉGLAGE ne se consomme pas : elle se débloque. */
     isSetting: boolean;
+    /** Le module qui étend cette métrique est suspendu parce que le plan le couvre désormais. */
     moduleSuspendedByPlan: boolean;
+    /** Taille d'un lot, dans l'unité de la métrique. `null` : aucun module ne vend cette métrique. */
     lotSize: number | null;
 }
+/**
+ * Décide l'état à afficher.
+ *
+ * ═══ L'ORDRE DES TESTS EST LA RÈGLE ═══
+ *
+ * Il ne s'agit pas de style : un client peut être À LA FOIS en dépassement et avec un module
+ * suspendu, ou au plafond d'une métrique de réglage. L'ordre dit lequel de ces faits le concerne le
+ * plus, et c'est toujours le plus contraignant — celui qui l'empêche d'agir passe avant celui qui
+ * lui coûte de l'argent, qui passe avant celui qui l'informe.
+ */
 export declare const deriveQuotaOfferState: ({ current, includedLimit, ceiling, alertThreshold, isSetting, moduleSuspendedByPlan, }: QuotaOfferInput) => QuotaOfferState;
+/**
+ * `true` quand l'état autorise une proposition.
+ *
+ * L'état SAIN et l'état APPROCHE en sont exclus : le premier ne dit rien, le second mentionne sans
+ * vendre. Et la SUSPENSION explique, elle ne propose pas — l'option est déjà couverte par le plan.
+ */
 export declare const offersAction: (state: QuotaOfferState) => boolean;
+/**
+ * `true` quand il devient MOINS CHER d'acheter un lot que de subir le dépassement.
+ *
+ * ═══ L'ARITHMÉTIQUE, PARCE QU'ELLE DÉCIDE DU SEUIL ═══
+ *
+ * Le dépassement coûte le DOUBLE de la tranche d'entrée (`OVERAGE_MULTIPLIER`), et un lot de `N`
+ * unités coûte à peu près `N × tranche`. Dépasser de `X` unités coûte donc `2 × X × tranche`, et
+ * acheter devient plus avantageux dès que :
+ *
+ *     2 × X × tranche  >  N × tranche      ⟺      X  >  N / 2
+ *
+ * D'où « la moitié d'un lot », qui n'est pas un chiffre rond choisi au hasard mais le point exact
+ * où les deux courbes se croisent.
+ *
+ * Rend `false` quand aucun module ne vend la métrique : il n'y a pas de lot à proposer, et
+ * suggérer un achat impossible est pire que de se taire.
+ */
 export declare const shouldSuggestModule: (current: number, includedLimit: number, lotSize: number | null) => boolean;

package/dist/components/QuotaReached/QuotaReachedDialog.component.d.ts

@@ -1,5 +1,15 @@
 import { default as React } from 'react';
 export interface QuotaReachedDialogProps {
+    /**
+     * Called when the user clicks the upgrade CTA. The host decides where to send
+     * them (internal route or the main dashboard billing URL). When omitted, the
+     * CTA button is hidden and only an explanatory message + close button show.
+     */
     onUpgrade?: () => void;
 }
+/**
+ * Shared "quota reached" dialog. Triggered imperatively by the billing-quota
+ * axios interceptor (see attachQuotaInterceptor) when a satellite blocks a
+ * create because the current plan's limit is hit.
+ */
 export declare const QuotaReachedDialog: React.FC<QuotaReachedDialogProps>;

package/dist/components/QuotaReached/billing-quota-error.d.ts

@@ -1,4 +1,11 @@
 import { AxiosInstance } from 'axios';
 import { QuotaDialogPayload } from './quota-dialog.store';
+/**
+ * Detects a billing-quota block in an axios error and resolves it into the
+ * payload the quota dialog needs. Returns null for anything that is not a
+ * recognizable quota block. The local `parseQuotaMetric` helper enforces the
+ * backend contract (access_not_allowed code + the exact quota message shape) and
+ * returns the offending metric.
+ */
 export declare const parseQuotaError: (error: unknown) => QuotaDialogPayload | null;
 export declare const attachQuotaInterceptor: (instances: AxiosInstance[]) => void;

package/dist/components/QuotaReached/quota-dialog.store.d.ts

@@ -1,8 +1,11 @@
 import { BillingMetric, BillingService } from '@abyss-project/main';
 import { UseBoundStore, StoreApi } from 'zustand';
 export interface QuotaDialogPayload {
+    /** Metric that hit its ceiling (e.g. TOOLS_BOARD_COUNT). */
     metric: BillingMetric;
+    /** Owning service, resolved from the metric. */
     service: BillingService;
+    /** Raw backend message, kept for debugging / fallback display. */
     rawMessage?: string;
 }
 interface QuotaDialogState {
@@ -11,5 +14,12 @@ interface QuotaDialogState {
     show: (payload: QuotaDialogPayload) => void;
     hide: () => void;
 }
+/**
+ * Shared store driving the global "quota reached" dialog across every Abyss
+ * front. The billing-quota axios interceptor lives outside the React tree, so
+ * it pushes into this store imperatively via
+ * `useQuotaDialogStore.getState().show(...)`. A `<QuotaReachedDialog />`
+ * mounted at the host's app root subscribes and renders.
+ */
 export declare const useQuotaDialogStore: UseBoundStore<StoreApi<QuotaDialogState>>;
 export {};

package/dist/components/QuotaReached/quota-service-meta.d.ts

@@ -6,6 +6,10 @@ interface ServiceMeta {
     icon: React.ReactElement;
     color: PaletteKey;
 }
+/**
+ * How each billing service is displayed in the shared quota dialog. Mirrors
+ * the front-v2 SERVICE_META so the look is consistent across hosts.
+ */
 export declare const QUOTA_SERVICE_META: Record<BillingService, ServiceMeta>;
 export declare const getQuotaServiceColor: (theme: Theme, service: BillingService) => string;
 export declare const renderQuotaServiceIcon: (service: BillingService, fontSize: number) => React.ReactElement;

package/dist/components/Support/SupportCategorySelect.component.d.ts

@@ -1,11 +1,14 @@
 import { default as React } from 'react';
 import { SupportTicketCategory } from '@abyss-project/main';
 interface SupportCategorySelectProps {
+    /** Single value mode (create form) */
     value?: SupportTicketCategory | null;
     onChange?: (value: SupportTicketCategory | null) => void;
+    /** Multiple value mode (filter) */
     multiple?: boolean;
     multipleValue?: SupportTicketCategory[];
     onMultipleChange?: (value: SupportTicketCategory[]) => void;
+    /** Common props */
     label?: string;
     placeholder?: string;
     size?: 'small' | 'medium';