myrole-docx-editor 0.1.0

package/dist/types/packages/docx-vars/src/scenario.d.ts

@@ -0,0 +1,20 @@
+import type { Tag } from '../../docx-tags/src/index';
+/**
+ * Les sections d'une matrice ne forment pas un arbre dans la tête du rédacteur,
+ * mais une **table de cas** : pour telle temporalité et telle phase, quelle
+ * phrase ? Le bloc RÉMUNÉRATION en est l'exemple — quatre sections imbriquées
+ * pour quatre scénarios de contrat.
+ *
+ * On extrait ces scénarios des conditions elles-mêmes, pour en faire des
+ * interrupteurs. C'est la « toolbox préremplie » du brief : on bascule, le
+ * document se réécrit.
+ */
+export interface Scenario {
+    path: string;
+    label: string;
+    /** un booléen s'inverse ; un énuméré propose les littéraux vus dans le document */
+    options?: string[];
+}
+export declare function scenarios(tags: Tag[]): Scenario[];
+export declare function readValue(obj: any, path: string): unknown;
+export declare function writeValue(obj: any, path: string, value: unknown): void;

package/dist/types/packages/docx-vars/src/substitute.d.ts

@@ -0,0 +1,28 @@
+import type { StyledParagraph } from '../../docx-model/src/index';
+import type { Tag } from '../../docx-tags/src/index';
+import type { Evaluated } from './preview';
+/**
+ * Applique les valeurs évaluées aux runs du document.
+ *
+ * On substitue **run par run** plutôt que paragraphe par paragraphe : après
+ * healing chaque tag est seul dans son run, donc remplacer son texte préserve
+ * la mise en forme de tout ce qui l'entoure. C'est la même propriété qui rend
+ * la réécriture possible côté docx.
+ *
+ * Le nombre de paragraphes est conservé même quand une section les masque :
+ * `bodyBlocks`, `tables` et `resolveNumbering` sont indexés par paragraphe et
+ * se désaligneraient si on en retirait.
+ */
+/** Boîte réservée pour un marqueur donné, quand un affichage tiers l'occupe. */
+export type TagBox = (mark: string) => {
+    widthPx: number;
+    heightPx: number;
+} | undefined;
+/** Morceaux de phrase à dessiner en ligne, quand l'affichage n'est pas une pastille. */
+export type TagInline = (tag: Tag) => {
+    text: string;
+    strong?: boolean;
+}[] | undefined;
+/** Marqueurs à poser en fin d'un paragraphe donné — affichages ancrés au texte. */
+export type ParaMarks = (para: number) => string[];
+export declare function substitute(paras: StyledParagraph[], tags: Tag[], ev: Evaluated, boxOf?: TagBox, inlineOf?: TagInline, marksAt?: ParaMarks): StyledParagraph[];

package/dist/types/packages/docx-vars/src/sync.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Sauvegarde et synchronisation.
+ *
+ * Trois contraintes mesurées, qui décident de tout :
+ *
+ * 1. **Un docx de matrice pèse jusqu'à 6,2 Mo** (`0_comedien.docx`), dont 99 %
+ *    de polices embarquées. Le contenu qui change, lui, fait 33 Ko.
+ * 2. **On ne peut pas envoyer ça au déchargement de la page.** `sendBeacon` et
+ *    `fetch(keepalive)` plafonnent à ~64 Ko — cent fois moins. Compter sur
+ *    `pagehide` pour l'upload, c'est perdre le document.
+ * 3. **`visibilitychange` arrive bien avant**, page encore vivante : un `fetch`
+ *    normal y passe. C'est là qu'il faut vider la file.
+ *
+ * D'où la séparation : l'**upload** part sur changement d'onglet et en différé
+ * pendant l'édition ; la **reprise après incident** ne stocke pas le document
+ * mais la liste des modifications, qui tient en quelques centaines d'octets et
+ * s'écrit instantanément, même sur `pagehide`.
+ */
+export type SyncState = 'clean' | 'dirty' | 'saving' | 'saved' | 'error' | 'local';
+export interface SyncInfo {
+    state: SyncState;
+    /** taille du dernier envoi, en octets */
+    bytes?: number;
+    message?: string;
+    pending: number;
+}
+export interface SyncOptions {
+    /** produit le docx courant — appelé au dernier moment */
+    build(): Uint8Array;
+    /** nombre de modifications en attente */
+    pending(): number;
+    /** identifiant du document, pour la reprise */
+    key(): string;
+    /** état sérialisable à conserver pour la reprise */
+    snapshot(): unknown;
+    onState(info: SyncInfo): void;
+    /** différé pendant l'édition, en ms */
+    debounceMs?: number;
+}
+/** URL de dépôt présignée. Jamais de secret dans l'application — juste une URL déjà signée. */
+export declare const endpoint: {
+    get: () => string;
+    set: (url: string) => void;
+};
+export interface Sync {
+    markDirty(): void;
+    /** envoie maintenant, sans attendre le différé */
+    flush(reason: string): Promise<void>;
+    /** modifications retrouvées d'une session interrompue */
+    recover(): unknown | null;
+    clearRecovery(): void;
+    dispose(): void;
+}
+export declare function createSync(o: SyncOptions): Sync;
+/** Décrit un envoi pour l'utilisateur, en nommant le coût quand il est absurde. */
+export declare function describePayload(bytes: number, fontBytes: number): string;

package/dist/types/packages/docx-vars/src/target-canvas.d.ts

@@ -0,0 +1,66 @@
+import type { MarkRect } from '../../docx-render/src/index';
+import type { Contributions, MenuItem } from './index.js';
+/**
+ * Cible canvas.
+ *
+ * Le canvas peint le texte ; les décorations vivent dans une **couche DOM**
+ * posée par-dessus, en coordonnées de page. C'est le parti pris d'OnlyOffice :
+ * l'éditeur possède le canvas, les extensions n'y peignent jamais — on garde
+ * la fidélité du texte et tout CSS pour l'interaction.
+ */
+export interface OverlayOptions {
+    container: HTMLElement;
+    rects: MarkRect[];
+    contributions: Contributions;
+    onMenu(items: MenuItem[], x: number, y: number): void;
+    /**
+     * Texte à afficher dans le badge, quand ce n'est pas son libellé — l'onglet
+     * Technique montre le tag brut. Le canvas a réservé la place de CE texte :
+     * le badge doit donc afficher le même, sinon il déborde ou se coupe.
+     */
+    textOf?(id: string): string | undefined;
+    /**
+     * Couleur de provenance, en mode Résultat : la décoration n'est plus un
+     * badge mais une simple teinte sur la valeur, comme le surligneur du
+     * générateur. Renvoyer `undefined` laisse le badge normal.
+     */
+    tintOf?(id: string): string | undefined;
+    /** badges déjà construits et mesurés — voir `prepareMarks` */
+    prepared?: Map<string, Prepared>;
+}
+/**
+ * Badge préparé : son élément et la boîte qu'il occupe.
+ *
+ * On le construit et on le mesure AVANT la mise en page, parce que le renderer
+ * doit réserver sa place exacte dans le flux. Sans ça il ne reste que le calque
+ * posé par-dessus, qui recouvre ses voisins.
+ */
+export interface Prepared {
+    el: HTMLElement;
+    size: {
+        widthPx: number;
+        heightPx: number;
+    };
+}
+/**
+ * Construit les badges et les mesure hors écran.
+ *
+ * `maxWidthPx` est la largeur utile de la page : un badge qui tient plusieurs
+ * mots doit se replier ici EXACTEMENT comme il se repliera sur la page, sinon
+ * la boîte réservée ne correspond pas à ce qui sera posé dedans.
+ */
+export declare function prepareMarks(o: OverlayOptions, maxWidthPx: number): Map<string, Prepared>;
+/**
+ * Regroupe les rectangles d'un même marqueur sur une même page, dans l'ordre
+ * de lecture. Un run replié occupe plusieurs lignes : on ne prend pas leur
+ * enveloppe, qui recouvrirait le voisin du dessus — le badge se pose sur la
+ * première ligne, les suivantes sont simplement masquées.
+ */
+export declare function group(rects: MarkRect[]): MarkRect[][];
+/**
+ * Enveloppe chaque canvas et pose la couche de décorations.
+ *
+ * Le renderer remplace le contenu du conteneur par ses canvas : on ne peut donc
+ * préparer les enveloppes qu'après coup.
+ */
+export declare function paintOverlay(o: OverlayOptions): number;

package/dist/types/packages/docx-vars/src/tokens.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Découpe un tag en morceaux colorables.
+ *
+ * Une grammaire Lezer serait la réponse propre pour un langage entier ; pour un
+ * tag de matrice — une expression sur une ligne — huit motifs suffisent. Ils
+ * sont essayés dans l'ordre, et la chaîne littérale passe en premier : sans ça
+ * `« à 25 % »` se ferait découper comme du code.
+ */
+export declare const TOKEN_RE: RegExp;
+export type TokenKind = 'str' | 'delim' | 'fn' | 'path' | 'num' | 'word' | 'op';
+export interface Token {
+    from: number;
+    to: number;
+    kind: TokenKind;
+    text: string;
+}
+/** Parcourt un tag et rend ses morceaux, dans l'ordre. */
+export declare function tokens(text: string): Token[];

package/dist/types/packages/fonts/src/advances.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Lecture des avances (hmtx) et de la table cmap d'un TTF/OTF.
+ *
+ * Canvas `measureText` (CoreText/macOS) mesure les glyphes ~1% plus large que
+ * les avances du fichier de police. Sur une ligne pleine de 504pt en Arial 8,
+ * ça fait 5pt de trop et le dernier mot est renvoyé à tort.
+ *
+ * On calcule la largeur du fichier sur un texte de référence, on la compare à
+ * `ctx.measureText` du même texte, et le ratio sert de facteur de correction
+ * global par police. C'est le SEUL mécanisme qui corrige le biais sans casser
+ * les décisions de resserrement — un slack global ou un seuil différent change
+ * toutes les lignes, celui-ci ne change que la MESURE.
+ *
+ * ponytail: le parseur couvre cmap format 4 (le plus courant en ASCII/BMP) et
+ * hmtx seule — ni cmap 12, ni GPOS/GSUB, ni ligatures. Le ratio est correct
+ * pour du latin occidental, la cible de ces contrats.
+ */
+/**
+ * Pré-parse un fichier de police et retourne une fonction de mesure rapide.
+ *
+ * Le parsing de cmap et hmtx ne se fait qu'une fois ; les appels suivants
+ * sont un simple parcours du texte avec des lookups dans des tableaux.
+ */
+/**
+ * De combien l'ENCRE d'une chaîne est-elle en retrait de son AVANCE ?
+ *
+ * Word coupe ses lignes sur l'encre, nous sur l'avance — mesuré : sur
+ * « CONTRAT CASCADEURS », sa ligne avance de 554,31 pt dans une colonne de
+ * 551,70 et son encre remplit exactement 551,70. La différence est l'approche
+ * du premier glyphe à gauche et celle du dernier à droite, que Word laisse
+ * pendre dans la marge.
+ *
+ * Une TOLÉRANCE ne remplace pas ce calcul : plate ou proportionnelle au corps,
+ * elle accorde la permission à toutes les lignes alors que Word ne l'accorde
+ * qu'à celles dont le dernier glyphe a une approche à donner. Les deux formes
+ * ont été balayées sur 400 documents et perdent de façon monotone.
+ *
+ * Les 219 faces que nous servons sont toutes en TrueType — table `glyf`, pas
+ * de CFF — donc la boîte d'un glyphe se lit en quatre entiers après son
+ * en-tête, et `loca` donne l'offset. Rien à installer.
+ *
+ * Renvoie `{ gauche, droite }` en EM : le retrait à retrancher de chaque bout.
+ *
+ * COUPER SUR L'ENCRE A ÉTÉ IMPLÉMENTÉ ET RÉFUTÉ. Le test de coupure a été
+ * changé pour retrancher le débord droit du mot candidat, et le corpus perd —
+ * même après avoir rebalayé `FINAL_LINE_SHRINK`, qui avait été calibré avec le
+ * test sur l'avance :
+ *
+ *   test sur l'AVANCE, FINAL 0,25   45,27 par document, 39,15 pondéré ligne
+ *   test sur l'ENCRE,  FINAL 0,15   43,24                36,94
+ *   test sur l'ENCRE,  FINAL 0,20   44,16                37,84
+ *   test sur l'ENCRE,  FINAL 0,25   43,62                37,26
+ *
+ * L'hypothèse expliquait pourtant la ligne qui l'avait suggérée à 0,1 pt près.
+ * Elle ne tient pas sur 400 documents : Word ne coupe pas simplement sur
+ * l'encre. Ce qu'il fait de plus reste à trouver.
+ *
+ * La lecture est gardée — `nodeSurface` publie désormais les mêmes
+ * `actualBoundingBox*` qu'un vrai canvas, ce qui rend les deux chemins
+ * comparables et permettra de tester la prochaine hypothèse sans reconstruire
+ * un parseur `glyf`.
+ */
+export declare function createInkTrim(buf: ArrayBuffer): ((text: string) => {
+    gauche: number;
+    droite: number;
+}) | undefined;
+export declare function createMeasurer(buf: ArrayBuffer): ((text: string) => number) | undefined;
+/**
+ * Largeur d'un texte en unités de design (hmtx), divisée par unitsPerEm.
+ *
+ * Retourne la largeur en « em » : multiplier par la taille en px donne des px.
+ * Retourne `undefined` si le fichier ne peut pas être lu.
+ *
+ * ponytail: version non-cachée pour les usages ponctuels (calibration).
+ * Pour le rendu, utiliser `createMeasurer` qui parse une seule fois.
+ */
+export declare function textWidthEm(buf: ArrayBuffer, text: string): number | undefined;
+/**
+ * Facteur de correction Canvas → hmtx pour une police donnée.
+ *
+ * `< 1` si Canvas mesure plus large (le cas courant), `> 1` sinon.
+ * Retourne `undefined` si la calibration échoue.
+ */
+/**
+ * Facteurs de correction pour toutes les polices servies.
+ *
+ * Même pattern que `fontLineRatios` : on fetch chaque TTF et on calibre.
+ */
+export declare function measureAllCorrections(ctx: CanvasRenderingContext2D, baseUrl?: string): Promise<Record<string, number>>;
+export declare function canvasCorrection(ctx: CanvasRenderingContext2D, family: string, fontBuf: ArrayBuffer): number | undefined;

package/dist/types/packages/fonts/src/aliases.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Names a document uses for a font we serve under another name.
+ *
+ * PostScript spellings (`ArialMT`, `TimesNewRomanPSMT`), vendor variants
+ * (`Futura LT`) and metric-compatible clones (`Arimo`) all reach us as literal
+ * strings out of `w:rFonts`, and every lookup in this codebase is exact-match.
+ * Unaliased, such a name misses the web font, misses the line-height table and
+ * misses the advance table at once — three different wrong answers, none of
+ * which logs anything.
+ *
+ * This table used to live inside `scripts/build-metrics.py`, which meant only
+ * the line-height table knew about it; the font loader and the Node measurer
+ * did not, so `Arial MT` (4342 runs in the corpus) silently fell back. Before
+ * that it was hand-written into the generated `metrics.ts`, where a
+ * regeneration erased nineteen entries in one go.
+ *
+ * alias → the served family whose metrics it borrows.
+ */
+export declare const FONT_ALIASES: Record<string, string>;
+/**
+ * The served family a name resolves to, or undefined if we serve nothing for it.
+ *
+ * Tries the alias table, then a case- and separator-insensitive match: a
+ * document that writes `Times-New-Roman` means the same font, and exact
+ * matching is the only reason it would miss.
+ */
+export declare function resolveFamily(name: string, served: Iterable<string>): string | undefined;

package/dist/types/packages/fonts/src/families.d.ts

@@ -0,0 +1 @@
+export declare const FAMILIES: readonly ["Abadi MT Condensed Extra Bold", "Abadi MT Condensed Light", "Angsana New", "Apple Color Emoji", "Apple Symbols", "Aptos", "Aptos Narrow", "Arial", "Arial Black", "Arial Hebrew", "Arial Narrow", "Arial Rounded MT Bold", "Arial Unicode MS", "Avenir", "Avenir Next", "Avenir Black", "Avenir Book", "Avenir Heavy", "Avenir Light", "Baskerville Old Face", "Batang", "Bauhaus 93", "Big Caslon", "Bookman Old Style", "Calibri", "Calibri Light", "Cambria", "Cambria Math", "Candara", "Century", "Century Gothic", "Century Schoolbook", "Comic Sans MS", "Consolas", "Corbel", "Cordia New", "Courier", "Courier New", "DengXian", "DengXian Light", "Didot", "Edwardian Script ITC", "Euphemia UCAS", "Eurostile", "Franklin Gothic Book", "Franklin Gothic Demi", "Franklin Gothic Demi Cond", "Franklin Gothic Medium", "Franklin Gothic Medium Cond", "Futura", "Garamond", "Geneva", "Georgia", "Gill Sans", "Gill Sans Light", "Gill Sans MT", "Helvetica", "Helvetica Neue", "Hoefler Text", "Lucida Grande", "Lucida Sans", "Lucida Sans Unicode", "Malgun Gothic", "Mangal", "Microsoft Sans Serif", "Microsoft YaHei", "Microsoft Yi Baiti", "Monotype Sorts", "MS Gothic", "MS Mincho", "MS UI Gothic", "New York", "News Gothic MT", "NSimSun", "Optima", "Palatino", "Palatino Linotype", "PMingLiU", "PT Mono", "Segoe UI Symbol", "SimSun", "Skia", "Stencil", "Symbol", "Tahoma", "Times", "Times New Roman", "Trebuchet MS", "Tw Cen MT", "Tw Cen MT Condensed", "Verdana", "Webdings", "Wingdings", "Wingdings 2", "Wingdings 3", "Yu Gothic Light", "Yu Mincho"];

package/dist/types/packages/fonts/src/load.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Load all @myrole/fonts @font-face declarations and wait for them to be ready.
+ * Import the CSS side-effect first, then call `await loadFonts()` before rendering.
+ *
+ * Usage:
+ *   import './faces'
+ *   import { loadFonts } from './load'
+ *   await loadFonts()          // resolves when every woff2 is painted-ready
+ *   ctx.font = '12px Calibri'  // guaranteed to hit the real font
+ */
+export { FAMILIES } from './families';
+import { FAMILIES } from './families';
+export type FontFamily = (typeof FAMILIES)[number];
+/**
+ * Wait until every declared @font-face is loaded (or 15 s timeout).
+ * Returns the list of families that actually loaded.
+ *
+ * `document.fonts.ready` ne suffit PAS : une @font-face que rien n'a encore
+ * demandée n'est pas « en attente », donc `ready` se résout aussitôt sans avoir
+ * rien téléchargé. Le canvas dessinait alors du sans-serif de repli là où le
+ * document demande du Times New Roman — texte gris et lourd, chaque glyphe
+ * différent de Word même à la bonne position. Il faut réclamer chaque face
+ * explicitement.
+ */
+export declare function loadFonts(): Promise<FontFamily[]>;

package/dist/types/packages/fonts/src/metrics.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hauteur de ligne réelle de chaque police, lue dans les TTF qu'on sert.
+ *
+ * Word compose une ligne « simple » comme
+ * `(hhea.ascender − hhea.descender + hhea.lineGap) / unitsPerEm`. Ni OS/2
+ * `usWin*`, ni `fontBoundingBox*` du Canvas — les trois donnent des valeurs
+ * différentes, et seule la première correspond à ce que Word dessine.
+ *
+ * On lit donc la valeur dans le fichier, au démarrage, plutôt que de tenir une
+ * table à la main : celle-ci laissait des trous, et une police absente
+ * retombait sur un ratio générique — 6 % trop court sur chaque ligne d'un
+ * contrat composé uniquement en Century Gothic.
+ *
+ * ponytail: lecture directe des deux tables qui nous intéressent, pas de
+ * bibliothèque de polices. Un parseur OpenType complet pèse 200 ko pour trois
+ * entiers 16 bits.
+ */
+import { type FontFamily } from './load';
+/**
+ * Ascendante, descendante et interligne d'une police, en em.
+ *
+ * `ascent` et `descent` sont ce que `measureText().fontBoundingBoxAscent` et
+ * `…Descent` rendent dans Chrome — vérifié sur 89 des 91 familles servies. Ils
+ * placent la LIGNE DE BASE ; `ratio` donne la hauteur de la ligne entière.
+ */
+export interface FontMetrics {
+    /** hhea.ascender / unitsPerEm */
+    ascent: number;
+    /** −hhea.descender / unitsPerEm (positif) */
+    descent: number;
+    /** hhea.lineGap / unitsPerEm */
+    lineGap: number;
+}
+/** Décodage des deux tables dont dépendent la hauteur de ligne et la baseline. */
+export declare function fontMetricsOf(ttf: ArrayBuffer): FontMetrics | undefined;
+/** Décodage des deux tables dont dépend la hauteur de ligne. */
+export declare function lineRatioOf(ttf: ArrayBuffer): number | undefined;
+/**
+ * Ratio de hauteur de ligne par famille, lu dans les fichiers servis.
+ *
+ * `baseUrl` doit pointer le dossier qui contient `ttf/` — par défaut celui du
+ * module, ce qui marche avec un bundler qui réécrit les URL relatives.
+ */
+export declare function fontLineRatios(baseUrl?: string): Promise<Partial<Record<FontFamily, number>>>;