structural-codes-viewer 0.1.0-alpha.1 → 0.1.0-alpha.3

package/README.md

@@ -1,102 +1,91 @@
 # structural-codes-viewer
 
-`structural-codes-viewer` è la reference UI React per consultare il corpus
-`structural-codes`. Il sottoprogetto contiene anche il consumer standalone
-locale usato per la revisione editoriale.
+`structural-codes-viewer` è il package React per consultare il corpus
+`structural-codes`. La stessa directory contiene l'applicazione standalone.
 
-- `structural-codes` contiene corpus, schema, provenance e relazioni canoniche;
-- `structural-codes-viewer` contiene UI React, client lazy degli artefatti e
-  generatore deterministico;
-- il viewer standalone Vinext/Vite è un consumer locale della stessa UI e può
-  aggiungere il PDF ufficiale tramite `OfficialPdfPanel`;
-- un futuro `ocfem-website` consumerà la stessa UI senza Vinext, Cloudflare o
-  PDF.js.
+## Boundary
 
-## Uso React
+- `structural-codes`: corpus, schema, provenance e helper non React;
+- `structural-codes-viewer`: viewer React, ricerca, navigazione, annotazioni,
+  client lazy e generatore di artefatti;
+- `viewer/app/`: composizione standalone non pubblicata nel package.
+
+React e ReactDOM sono peer dependency. Il package non dipende a runtime da
+Next/Vinext o `pdfjs-dist`.
+
+## Viewer React
 
 ```tsx
-import { NormativeViewer } from "structural-codes-viewer";
+import { NormativeViewer, type AuxiliaryPanelContext } from "structural-codes-viewer";
 import "structural-codes-viewer/styles.css";
 
+function Panel({ context }: { context: AuxiliaryPanelContext }) {
+  return <aside><button onClick={context.close}>Chiudi</button></aside>;
+}
+
 export function Normativa() {
-  return <NormativeViewer defaultMode="combined" dataBaseUrl="/data/codes" />;
+  return <NormativeViewer
+    defaultMode="combined"
+    dataBaseUrl="/data/codes"
+    auxiliaryPanel={(context) => <Panel context={context} />}
+    auxiliaryPanelModes={["ntc", "circ", "combined"]}
+  />;
 }
 ```
 
-La modalità predefinita è `combined`: la NTC resta la struttura principale e
-la Circolare viene inserita soltanto tramite relazioni esplicite del corpus.
-Le relazioni `proposed` restano tracciate nei dati senza aggiungere etichette
-testuali alla lettura. Il client verifica `formatVersion`, schema e manifest; non usa
-la uguaglianza delle versioni SemVer per interpretare i dati.
-
-API intenzionale:
-
-- `defaultMode`: `combined`, `ntc` o `circ`;
-- `dataBaseUrl`: directory degli artefatti lazy, default `/data/codes`;
-- `assetsBaseUrl`: directory delle figure, default `/assets`;
-- `auxiliaryPanel`: pannello opzionale o render prop locale;
-- `auxiliaryPanelDefaultVisible`: visibilità iniziale del pannello opzionale.
-
-La ricerca è sempre visibile ma carica `search-index.json` soltanto con almeno
-due caratteri. Manifest, indice documento, chunk e relazioni restano separati.
-Le figure sono lazy e il package shared non importa `pdfjs-dist`, non conosce
-`/api/source-pdf` e non dipende da Vinext o Cloudflare. React e ReactDOM sono
-peer dependencies React 19. Nell’indice della consultazione comparata ogni
-colonna segue la selezione corrente: capitolo → paragrafi → sottoparagrafi →
-dettagli. I capitoli entro la soglia di caricamento sono continui; quelli più
-grandi caricano il testo in continuità quando si seleziona il singolo paragrafo.
+`NormativeViewer` espone `dataBaseUrl`, `assetsBaseUrl`, `auxiliaryPanel`,
+`AuxiliaryPanelContext`, controlli di visibilità del pannello e `annotationStore`.
+Il pannello generico consente ai consumer di montare i propri componenti.
+Navigazione, ricerca, annotazioni, note e segnalibri sono indipendenti dalla
+composizione standalone. Sono pubblici anche `./annotations`, `./corpus-data`,
+`./generate-artifacts` e `./styles.css`.
 
 ## Artefatti
 
-`npm run sync:corpus` mantiene il consumer locale aggiornato sotto
-`public/data/codes/`:
-
-```text
-manifest.json
-relations.json
-relation-diagnostics.json
-search-index.json
-ntc2018/index.json
-ntc2018/chunks/*.json
-circ2019/index.json
-circ2019/chunks/*.json
+```bash
+npm run sync:corpus
 ```
 
-Il generatore condiviso legge soltanto i file pubblici del package
-`structural-codes`, è deterministico e non richiede un checkout sibling. La
-CLI inclusa nel package può materializzare gli stessi artefatti in un consumer:
+Il comando genera sotto `viewer/public/data/codes/` manifest, indici documento,
+chunk, relazioni, riferimenti e indice di ricerca. `viewer/public/` è ignorato
+da Git e rigenerabile dal corpus canonico.
+
+Un consumer può usare la CLI inclusa:
 
 ```bash
 npx structural-codes-viewer --source structural-codes \
   --output public/data/codes --assets public/assets
 ```
 
-Il comando non copia il corpus completo nel package viewer: usa il package
-`structural-codes` installato dal consumer come sorgente.
+Il package viewer non include il corpus completo: il generatore legge il
+package `structural-codes` installato nel consumer.
 
-## Viewer standalone
+## Standalone
 
 ```bash
+npm ci
 npm run dev
-npm run build
-npm test
 ```
 
-La route `/consultazione` usa `NormativeViewer` e compone il pannello PDF
-locale opzionale. PDF.js e il file PDF vengono caricati solo dopo l’azione
-esplicita “Apri PDF ufficiale”; il PDF non entra nel package shared.
-
-## Package
+Il PDF ufficiale è un ausilio locale di debug e non entra nel build pubblico o
+nel package.
 
-La prerelease non viene pubblicata da questo repository. Per una futura
-pubblicazione, dopo review:
+## Sviluppo e verifica
 
 ```bash
-npm run build:library
-npm pack
-npm publish --access public
+npm run typecheck
+npm run lint
+npm test
+npm run check
+npm run pack:verify
+npm run test:consumer
 ```
 
-Il tarball contiene soltanto `package-dist/`, CSS, README e metadati del
-package; non contiene app standalone, worker Cloudflare, test, cache, corpus
-completo o `pdfjs-dist`.
+`check` costruisce app e libreria ed esegue i test del viewer e del boundary.
+`pack:verify` mostra il contenuto del tarball. `test:consumer` crea tarball
+reali dei due package, li installa in una nuova app Next e verifica l'API
+pubblica del viewer, inclusa l'integrazione tramite `auxiliaryPanel`.
+
+Il tarball contiene soltanto `package-dist/`, README, licenza, notice e
+manifest. Restano fuori `app/`, test, PDF, corpus completo, `.env` e output
+standalone.

package/package-dist/CorpusContent.d.ts

@@ -1,16 +1,51 @@
-import type { AssetBundle, CorpusBlock, CorpusUnit } from "./corpusData";
+import type { AssetBundle, CorpusBlock, DocumentId, InlineSegment, CorpusUnit } from "./corpusData";
+export declare function leadingMathLabelEnd(inline: InlineSegment[]): number;
+export declare function hasOfficialListMarker(block: CorpusBlock): boolean;
+export declare function hasAlphaRatioListLayout(block: CorpusBlock, sourceUnitId?: string): boolean;
+export declare function hasInferredAlphaRatioListMarker(block: CorpusBlock, sourceUnitId?: string): boolean;
+export declare function hasAlphabeticListMarker(block: CorpusBlock): boolean;
+export declare function hasSimpleDashMarker(block: CorpusBlock): boolean;
+export declare function hasNoListMarker(block: CorpusBlock): boolean;
+export declare function listMarkerClass(block: CorpusBlock): "" | "list-item-with-bullet";
+export declare function listLevelClass(block: CorpusBlock): string;
+export declare function indentLevelClass(block: CorpusBlock): string;
+export declare function hasLeadingMath(block: CorpusBlock): boolean;
+export declare function hasAlignedListContinuation(block: CorpusBlock): boolean;
+export declare function hasLeadingEmphasisLabel(block: CorpusBlock): boolean;
+export declare function leadingLabelKind(block: CorpusBlock): "math" | "emphasis" | null;
+export type CorpusBlockGroup = {
+    kind: "label-list";
+    blocks: CorpusBlock[];
+} | {
+    kind: "block";
+    block: CorpusBlock;
+    index: number;
+};
+export declare function groupAlignedLabelBlocks(blocks: CorpusBlock[]): CorpusBlockGroup[];
+export declare function hasTrailingStrong(block: CorpusBlock): boolean;
+export declare function hasTrailingMath(block: CorpusBlock): boolean;
 export interface BlockContentProps {
     block: CorpusBlock;
     assets: AssetBundle | null;
-    showRaw?: boolean;
     assetsBaseUrl?: string;
+    aligned?: boolean;
+    sourceUnitId?: string;
+    sourceDocument?: DocumentId;
 }
-export declare function BlockContent({ block, assets, showRaw, assetsBaseUrl }: BlockContentProps): import("react/jsx-runtime").JSX.Element;
-export declare function isRepeatedUnitTitle(unit: CorpusUnit, block: CorpusUnit["blocks"][number]): boolean;
-export declare function UnitBlocks({ unit, assets, showRaw, compact, assetsBaseUrl }: {
-    unit: CorpusUnit;
-    assets: AssetBundle;
-    showRaw?: boolean;
-    compact?: boolean;
+type InlineSegments = InlineSegment[];
+interface ReferenceContext {
+    sourceUnitId: string;
+    sourceDocument: DocumentId;
+}
+export declare function renderInlineSegments(inline: InlineSegments, context?: ReferenceContext | null): import("react").ReactNode[];
+export declare function BlockContent({ block, assets, assetsBaseUrl, aligned, sourceUnitId, sourceDocument }: BlockContentProps): import("react/jsx-runtime").JSX.Element;
+export declare function AlignedLabelList({ blocks, assets, assetsBaseUrl, sourceUnitId, sourceDocument, renderAccessory }: {
+    blocks: CorpusBlock[];
+    assets: AssetBundle | null;
     assetsBaseUrl?: string;
+    sourceUnitId?: string;
+    sourceDocument?: DocumentId;
+    renderAccessory?: (block: CorpusBlock) => React.ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
+export declare function isRepeatedUnitTitle(unit: CorpusUnit, block: CorpusUnit["blocks"][number]): boolean;
+export {};