Skip to content

refactor(non-verbal): eliminate parallel TS projection (TODO.figures/19 Option A)#74

Merged
ronaldtse merged 1 commit into
mainfrom
chore/eliminate-nonverbal-ts-projection
Jun 22, 2026
Merged

refactor(non-verbal): eliminate parallel TS projection (TODO.figures/19 Option A)#74
ronaldtse merged 1 commit into
mainfrom
chore/eliminate-nonverbal-ts-projection

Conversation

@ronaldtse

Copy link
Copy Markdown
Member

Closes TODO.figures/19 Step 7 Option A.

What

Removes the parallel TypeScript projection of the non-verbal hierarchy.
Bridges now return glossarist-js class instances (new Figure(...),
new Table(...), new Formula(...), new FigureImage(...)) instead of
plain { \$kind: 'figure', ... } literals, and components narrow via
instanceof / property access against the upstream classes.

Why

The consumer's adapters/non-verbal/types.ts previously redeclared every
class shape as a TS interface — a parallel projection of the upstream model.
Every shape change in glossarist-js required a corresponding edit here, and
the two definitions could silently drift. With this refactor the upstream
classes become the single source of truth at the type layer; this repo only
owns what is genuinely consumer-side (wire shapes parsed by the bridges,
plus the local string-union refinements).

Slimmed types.ts to consumer-only types

Kept:

  • LocalizedString, NonVerbalKind — routing/anchor/mention discriminator
  • FigureImageFormat, FigureImageRole, TableFormat, FormulaNotation
    validated string unions the bridges check at parse time
  • NonVerbalSource* — wire shape for JSON-LD source entries
  • TableContent — discriminated union the TableDisplay component switches on
  • NonVerbRepV3, NonVerbRepImage — local view of NonVerbRep's V3 runtime
    shape (upstream .d.ts still pre-V3, see chore(types): declare NonVerbal classes in models/index.d.ts glossarist-js#31)
  • NonVerbalReference — inline mention routing shape

Removed (sourced from glossarist):

  • Figure, Table, Formula, FigureImage
  • NonVerbalEntity, NonVerbalEntityBase

Component updates

  • FigureImages accepts ImageLike = FigureImage | NonVerbRepImage so the
    same component works for class instances (Figure) and plain objects
    (NonVerbRep). Nullable-safe accessors (imgSrc, imgFormat, imgRole)
    paper over the T | null upstream convention.
  • Props accept T | null throughout (upstream convention) instead of
    T | undefined. Resolvers receive ?? undefined at the call site.
  • NonVerbalSources takes upstream ConceptSource[] directly. The old
    asCitation shim is gone — src.origin is already Citation | null.
  • TableDisplay casts table.content to the consumer's TableContent
    union. Upstream keeps it as Record<string, unknown> because the
    structured/markup split is a consumer concern.
  • FormulaDisplay casts formula.notation to FormulaNotation.

Temporary module augmentation

Added src/adapters/non-verbal/glossarist-augment.d.ts. Upstream's
published .d.ts (v0.4.2) re-exports Figure / Table / Formula from
index.d.ts, but the underlying models/index.d.ts declares none of them,
so TypeScript silently resolves consumer imports to any. The local
augmentation restores type safety until PR glossarist/glossarist-js#31
ships in v0.4.3+. Deletion marker is in the file header.

Verification

  • npx vue-tsc --noEmit — 0 errors
  • npm test — 797 passed, 1 skipped
  • npm run check:scripts — syntax OK on 14 files

…19 Option A)

Bridges now return glossarist-js class instances (new Figure/Table/Formula/
FigureImage) instead of plain {$kind: 'figure', ...} literals. Components
narrow via instanceof and property access; the parallel TS projection in
adapters/non-verbal/types.ts is removed.

Slimmed types.ts to consumer-only types:
- LocalizedString, NonVerbalKind, FigureImageFormat, FigureImageRole
- NonVerbalSource* (wire shape for source-bridge parsing)
- TableFormat, TableContent, FormulaNotation (validated string unions)
- NonVerbRepV3 + NonVerbRepImage (local view until upstream .d.ts lands)
- NonVerbalReference (inline mention routing)

Removed (now sourced from glossarist):
- Figure, Table, Formula, FigureImage, NonVerbalEntity, NonVerbalEntityBase

Component updates:
- FigureImages accepts ImageLike = FigureImage | NonVerbRepImage for dual
  compatibility with class instances (Figure) and plain objects (NonVerbRep).
- Props accept T | null throughout (upstream convention) instead of T | undefined.
- NonVerbalSources now takes ConceptSource[] directly; asCitation shim removed
  since src.origin is already Citation | null in upstream.
- TableDisplay casts table.content to consumer's TableContent union.
- FormulaDisplay casts table.notation to FormulaNotation.

Added src/adapters/non-verbal/glossarist-augment.d.ts as a temporary module
augmentation. Upstream's published .d.ts (v0.4.2) re-exports Figure/Table/
Formula from index.d.ts but the underlying models/index.d.ts declares none
of them, so TypeScript silently resolves consumer imports to any. The local
augmentation restores type safety until PR glossarist/glossarist-js#31 ships.

vue-tsc --noEmit: 0 errors. npm test: 797 passed, 1 skipped.
@ronaldtse ronaldtse merged commit 5bec835 into main Jun 22, 2026
4 checks passed
@ronaldtse ronaldtse deleted the chore/eliminate-nonverbal-ts-projection branch June 22, 2026 13:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant