@nuucognition/ncm-ui 0.1.1-beta.1 → 0.1.1-beta.2

package/dist/references-BM-lvGrq.d.ts

@@ -0,0 +1,99 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { Block } from '@nuucognition/ncm';
+
+/**
+ * Numbering for inline references (`^[ref: ...]` / `^[footnote: ...]`).
+ *
+ * The two kinds are counted **independently**: refs produce `[1] [2] …` and
+ * footnotes produce `¹ ² …`.
+ *
+ * Numbers are assigned by a pure pre-pass over the `blocks` array and looked up
+ * by **token content**, never by render order. That makes the marker number a
+ * function of the document alone: it is stable under React re-renders,
+ * StrictMode double rendering, virtualised or out-of-order block rendering,
+ * and it gives every citation of the same source the same number.
+ *
+ * Refs additionally honour the document's own bibliography. When a paragraph
+ * reads `[16] Google Gemini Team. Gemini: …` and a `^[ref: Google Gemini
+ * Team. Gemini: …]` token carries that entry, the marker shows `[16]` — the
+ * number the source document uses — so the inline citation, the reference
+ * list, and the original paper all agree. Refs with no bibliography match are
+ * numbered sequentially in first-appearance order, continuing after the
+ * highest bibliography number so the two ranges never collide.
+ *
+ * Footnotes are numbered sequentially in first-appearance order (identical
+ * footnote text shares a number).
+ */
+type ReferenceKind = "ref" | "footnote";
+interface ReferenceCounts {
+    ref: number;
+    footnote: number;
+}
+/** Document-wide numbering: normalised token content → marker number. */
+interface ReferenceNumbering {
+    ref: Map<string, number>;
+    footnote: Map<string, number>;
+}
+/** Collapse whitespace and case so a token and its bibliography entry compare equal. */
+declare function normalizeReferenceContent(content: string): string;
+/**
+ * Map every `[n] entry` paragraph in the document to its number. The first
+ * paragraph carrying a given entry text wins.
+ */
+declare function collectBibliography(blocks: readonly Block[]): Map<string, number>;
+/**
+ * Compute the document-wide numbering (see the module comment for the rules).
+ */
+declare function computeReferenceNumbering(blocks: readonly Block[]): ReferenceNumbering;
+/**
+ * Per-block count of inline references, as the *previous* numbering scheme
+ * exposed it. Kept for API compatibility; the marker numbers no longer derive
+ * from these offsets.
+ */
+declare function computeReferenceBases(blocks: readonly Block[]): Map<string, ReferenceCounts>;
+interface BlockReferenceScopeValue {
+    /**
+     * The marker number for a token with this `kind` and `content`. Pure with
+     * respect to the document: the same content always gets the same number.
+     */
+    numberFor(kind: ReferenceKind, content: string): number;
+    /**
+     * Allocate the next number for `kind` in render order. Legacy API — prefer
+     * `numberFor`, which is stable under re-renders.
+     */
+    next(kind: ReferenceKind): number;
+}
+interface NcmReferencesProviderProps {
+    blocks: readonly Block[];
+    children: ReactNode;
+}
+/** Document-root provider — runs the numbering pre-pass over `blocks`. */
+declare function NcmReferencesProvider({ blocks, children }: NcmReferencesProviderProps): react.JSX.Element;
+interface BlockReferenceScopeProps {
+    /** Block id. Accepted for API compatibility; numbering is document-wide. */
+    blockId?: string;
+    children: ReactNode;
+}
+/**
+ * Reference scope for one block (or one standalone `InlineContent` fragment).
+ *
+ * Inside an `NcmDocument` it resolves numbers from the document pre-pass.
+ * Standalone — no `NcmReferencesProvider` above it — it numbers the fragment's
+ * own tokens by content in first-request order, which is still idempotent
+ * under StrictMode double rendering because a repeated request for the same
+ * content returns the same number.
+ */
+declare function BlockReferenceScope({ children }: BlockReferenceScopeProps): react.JSX.Element;
+/** Read the active per-block reference scope, if any. */
+declare function useBlockReferenceScope(): BlockReferenceScopeValue | null;
+/**
+ * Wrap a subtree so any inline references inside it do NOT take document
+ * numbers — used for a reference's own popover content, which the numbering
+ * pre-pass deliberately does not descend into.
+ */
+declare function InertReferenceScope({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+export { BlockReferenceScope as B, InertReferenceScope as I, NcmReferencesProvider as N, type ReferenceCounts as R, type BlockReferenceScopeProps as a, type BlockReferenceScopeValue as b, type NcmReferencesProviderProps as c, type ReferenceKind as d, type ReferenceNumbering as e, collectBibliography as f, computeReferenceBases as g, computeReferenceNumbering as h, normalizeReferenceContent as n, useBlockReferenceScope as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuucognition/ncm-ui",
-  "version": "0.1.1-beta.1",
+  "version": "0.1.1-beta.2",
   "description": "React renderers for NUU Cognition Markdown (NCM) blocks — a component library that renders parsed NCM Blocks to accessible, themeable markup.",
   "type": "module",
   "license": "MIT",
@@ -45,8 +45,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.2",
     "vitest": "^2.1.9",
-    "@nuucognition/eslint-config": "0.0.0",
-    "@nuucognition/typescript-config": "0.0.0"
+    "@nuucognition/typescript-config": "0.0.0",
+    "@nuucognition/eslint-config": "0.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/dist/references-BYW5pnj_.d.ts

@@ -1,63 +0,0 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-import { Block } from '@nuucognition/ncm';
-
-/**
- * Document-order numbering for inline references (`^[ref: ...]` /
- * `^[footnote: ...]`).
- *
- * The two kinds are counted **independently**: refs produce `[1] [2] …` and
- * footnotes produce `¹ ² …`, each with its own running counter across the
- * whole document.
- *
- * Numbering is computed from the `blocks` array — a pure pre-pass that does not
- * depend on React render order — so markers stay stable even if a host
- * virtualises blocks or renders them out of order. The pre-pass yields, per
- * block, the count of each kind in all *preceding* blocks (the "base"); within
- * a block, a `BlockReferenceScope` hands out sequential numbers in render
- * order. Only the within-block step relies on the block's inline content
- * rendering as a synchronous subtree (it always does).
- */
-type ReferenceKind = "ref" | "footnote";
-interface ReferenceCounts {
-    ref: number;
-    footnote: number;
-}
-/**
- * Map each block id to the number of refs/footnotes that precede it in
- * document order — the starting offset for that block's own markers.
- */
-declare function computeReferenceBases(blocks: readonly Block[]): Map<string, ReferenceCounts>;
-interface BlockReferenceScopeValue {
-    /** Allocate the next document-order number for `kind` within this block. */
-    next(kind: ReferenceKind): number;
-}
-interface NcmReferencesProviderProps {
-    blocks: readonly Block[];
-    children: ReactNode;
-}
-/** Document-root provider — runs the numbering pre-pass over `blocks`. */
-declare function NcmReferencesProvider({ blocks, children }: NcmReferencesProviderProps): react.JSX.Element;
-interface BlockReferenceScopeProps {
-    /** Block id; resolves the base offset from the document pre-pass. */
-    blockId?: string;
-    children: ReactNode;
-}
-/**
- * Per-block numbering scope. Seeds a fresh counter from the block's base offset
- * on every render and hands out sequential numbers as markers render. Resetting
- * each render keeps numbering idempotent under React re-renders / StrictMode.
- */
-declare function BlockReferenceScope({ blockId, children }: BlockReferenceScopeProps): react.JSX.Element;
-/** Read the active per-block reference scope, if any. */
-declare function useBlockReferenceScope(): BlockReferenceScopeValue | null;
-/**
- * Wrap a subtree so any inline references inside it do NOT allocate
- * document-order numbers — used for a reference's own popover content, which
- * the numbering pre-pass deliberately does not descend into.
- */
-declare function InertReferenceScope({ children }: {
-    children: ReactNode;
-}): react.JSX.Element;
-
-export { BlockReferenceScope as B, InertReferenceScope as I, NcmReferencesProvider as N, type ReferenceCounts as R, type BlockReferenceScopeProps as a, type BlockReferenceScopeValue as b, type NcmReferencesProviderProps as c, type ReferenceKind as d, computeReferenceBases as e, useBlockReferenceScope as u };