gedcom-ts 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -2,6 +2,98 @@
 
 All notable changes of gedcom-ts
 
+## [Unreleased]
+
+## [2.1.0] - 2026-05-13
+
+### Highlights
+
+- Major GEDCOM 7 coverage push: round-trip preservation (`preservedTopLevelRecords`, label-keyed FAM / NOTE xrefs, level-0 `OBJE`), richer `HEAD` export options, full P1.4 dates and places (INT/EST/CAL, `3 PHRASE`, `3 TIME`, `2 SDATE`, `2 PHRASE` event-level, ISO date input, verbatim fallback).
+- New **fluent edit layer** (`editPerson`, `editAct`, `editActs`, `editDateAct`, `editPlace`, `editNotes` + `*Edit` classes) for in-place model mutations with chainable APIs.
+- **README fully rewritten** with a complete public-API reference and a link to the live graphical demo at **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+
+### Added
+
+#### Import
+
+- `ReadGed.preservedTopLevelRecords`: top-level `0 …` GEDCOM records that are not loaded into the typed model (e.g. `REPO`, `SOUR`, `SUBM`, and undecodable `OBJE`) are preserved in file order. `0 TRLR` is not stored.
+- **FAM / `@N` xrefs non numériques** : enregistrements `0 @F…@ FAM` et `0 @N…@ NOTE|SNOTE` indexés par libellé puis mappés vers des ids internes numériques (comme pour les `INDI` textuels) ; `FAMS` / `FAMC` / notes résolus via tables de pointeurs.
+- **OBJE de niveau 0** : si le bloc contient un `FILE` exploitable, il est retiré de `preservedTopLevelRecords` et sert à hydrater `MultimediaFile.sourceUri` pour les pointeurs `1 OBJE` / `2 OBJE` (`PersonGedcomImportOptions` / résolution interne dans `ReadGed`).
+- **Import actes (FAM)** : `1 HUSB` / `1 WIFE` avec pointeur `@I{n}@` **ou** xref textuelle `@Libellé@` (même clé que `0 @Libellé@ INDI`) alimentent les participants des actes extraits (`extractActEntriesAndIndis`).
+- `ReadGed.resolveIndividualPointer(raw)`, `ReadGed.getChildrenForParent(parent)`, `ReadGed.getChildrenOfFamily(familyId)` exposés publiquement pour naviguer le graphe importé.
+
+#### Export
+
+- `GedcomExportOptions` enrichies : `extraTopLevelRecords` (round-trip), `headLanguageTag`, **`headCopyright`** (`1 COPR`), **`headDestination`** (`1 DEST`), **`headSchemaTagDefs`** (`HEAD`.`SCHMA` / `2 TAG …`).
+- `HEAD`.`SOUR` structuré : émission de **`2 VERS`** + **`2 NAME`** sous `SOUR`, en plus du `CHAR` / `LANG` standard.
+- Constante **`GEDCOM_LIBRARY_VERSION`** (`src/version.ts`, alignée sur `package.json` via test) utilisée pour `2 VERS` à l’export.
+- **FAM** : sexes U / X / indéfini sont exportés en **`1 HUSB`** (placeholder GEDCOM moins biaisé que `WIFE`).
+
+#### Domain model — dates, places, events (P1.4)
+
+- **`DateAct`** :
+  - qualificateurs **INT**, **EST**, **CAL** ;
+  - phrase finale `(...)` et **`datePhrase`** ;
+  - import **`3 PHRASE`** sous `DATE` ;
+  - **`3 TIME`** sous `DATE` / **`SDATE`** (`dateTime`) ;
+  - entrée date **`YYYY-MM-DD`** / **`YYYY-MM`** ;
+  - **`verbatimDatePayload`** pour charges non typées (URI, texte hors parseur) ;
+  - tolérance `(...)` sur les bornes d’intervalles (`parseCoreDateValue`) ;
+  - format mois/année slash strict **`d{1,2}/d{2,4}`** uniquement (évite les faux positifs sur URL).
+- **`Act`** :
+  - **`2 SDATE`** (+ sous-lignes) sur `sdateAct` ;
+  - **`2 PHRASE`** niveau événement (`eventPhrases`) ;
+  - **`preservedSubrecordPrefix`** / **`preservedSubrecordSuffix`** pour sous-lignes non modélisées (`HUSB`/`AGE`/`4 PHRASE`, `3 DATE` sous `STAT`, …) avec ré-export ;
+  - tri des actes : **`DATE`** sinon **`SDATE`** valide.
+- **`Place`** : **`placPhrase`** et import **`3 PHRASE`** direct sous `PLAC` ; export **`3 PHRASE`** pour date et lieu quand présents ; export **`3 TIME`** / blocs **`SDATE`** / **`2 PHRASE`** événement.
+
+#### Fluent edit layer
+
+- Nouveau module `src/edit/` réexporté depuis la racine du paquet :
+  - **`editPerson`** / `PersonEdit` (identité, liens `FAMC` / `FAMS`, name variants, attributes, accès chaîné à `acts()` / `notes()`) ;
+  - **`editActs`** / `ActsEdit` (add, replaceAt, removeAt, clear, sortByDate, at) ;
+  - **`editAct`** / `ActEdit` (type, indis, date, sdate, place, EVEN, phrases, preserved prefix/suffix) ;
+  - **`editDateAct`** / `DateActEdit` (clear, applyGedcomPayload, setExactDate, setQualified, setBetween, setFromTo, setTime, setDatePhrase, setVerbatimPayload) ;
+  - **`editPlace`** / `PlaceEdit` (city/county/state/country, GEDCOM 7 payload, placPhrase, coordinates) ;
+  - **`editNotes`** / `NotesEdit` (add, replaceAt, removeAt, clear) ;
+  - chaînage cohérent (`this`) sur le modèle existant, mutation in-place.
+
+#### Public API surface
+
+- Types exportés : `PersonGedcomImportOptions`, `GedcomExportOptions`, `TypeDateActSimpleQualifier`, `Gedcom7EventTag`, `IndiGedcomSubLine`, `GedcomDatasetVersion`.
+- Classes / valeurs réexportées depuis l’index : `PersonNameVariant`, `PersonNameTranslation`, `IndiAttribute`, `ActConstructionOptions`, `GEDCOM_7_ALL_EVENT_TAGS`, `GEDCOM_7_EVENT_SORT_ORDER`, `GEDCOM_7_EVENT_TAG_SET`, `selectPrimaryNameVariant`, `extractPersonNameVariants`, `extractIndiAttributes`, `createEmptyReadGed`, `IMPORT_ERR_ZIP_GED_UNREADABLE`, **`GEDCOM_LIBRARY_VERSION`**.
+
+#### Tests
+
+- **Golden export** : fixture `tests/fixtures/golden-in/marriage-marr-roundtrip.ged` + fichiers attendus `tests/fixtures/golden-out/*.golden.txt` ; `tests/import/goldenMarrExport.spec.ts` verrouille le bloc `1 MARR` exporté (fixture minimale + extrait `maximal70` pour `@I1@`) et l’idempotence import → export → import.
+- Non-régression `ReadGed.groupPartners()` appelée plusieurs fois (les enfants et conjoints ne sont plus dupliqués).
+
+#### Documentation
+
+- **README intégralement réécrit** : référence complète de l’API publique (un sous-titre par export de `src/index.ts`), tables synthétiques pour `ReadGed`, `GedcomExportOptions` et la couche `*Edit`, exemples mis à jour pour chaque type / classe / fonction exposés.
+- Mention en tête du README du **site de démo graphique** : **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+
+### Changed
+
+- Export `FAM` : sexe inconnu / non binaire / absent (`U`, `X`, `undefined`) émet **`1 HUSB`** au lieu de **`1 WIFE`** pour le rôle conjoint (placeholder GEDCOM moins biaisé).
+
+### Fixed
+
+- Export GEDCOM : terminaison correcte `0 TRLR` avec saut de ligne (au lieu du seul tag `TRLR`).
+- **`ReadGed.groupPartners()`** : les cartes `partnersMap` et `childsMap` sont vidées avant reconstruction, afin que des rappels successifs (après édition des liens en mémoire) ne dupliquent plus conjoints ni enfants.
+
+## [2.0.4] - 2026-05-11
+
+### Added
+
+- GEDCOM 7–oriented export: default `SUBM` pointer in `HEAD` and a minimal `@U1@ SUBM` record before `TRLR`.
+- `Place` supports structured locality fields (`county`, `state`, `country`) and comma-separated `PLAC` payloads aligned with the default `HEAD`.`PLAC`.`FORM`.
+- Event and person media: `FILE` with `https?://` URIs without a local `File`; optional `OBJE @O{n}@` pointers with generated `0 @O{n}@ OBJE` records when `MultimediaFile.sourceUri` and `objeXrefId` are set.
+- Import of `2 OBJE @O{n}@` under individual events (same model as level-1 `OBJE` on `INDI`).
+- `guessMediaFormFromUri()` exported from the package entrypoint (MIME guess for `OBJE`.`FILE`.`FORM`).
+- `resolveDatasetVersion` / `GedcomDatasetVersion` and GEDCOM 7 event tag constants (`GEDCOM_7_ALL_EVENT_TAGS`, etc.) on the public API.
+- Tests: `gedcom7Export`, `mediaFormFromUri`, `datasetVersion`, import smoke test against the gedcom.io `maximal70.ged` sample (file added to the repo for CI).
+
 ## [2.0.2] - 2026-05-11
 
 ### Fixed