LODox Data Viewer (lodox-data-viewer)

Live demo →

LODox Data Viewer is a framework-agnostic library of web components and a pure data pipeline for rendering Linked Art, schema.org, and generic JSON-LD / RDF as themeable cards. It has zero runtime dependencies and runs both in the browser and in Node.js (server-side rendering and static-site builds). Developed for LODox (Linked Open Data at Oxford), it is fully usable as an independent package.

Refer to USAGE.md for the complete usage guide, covering embedding, theming, card configuration, the configurable ontology vocabulary, and generic JSON-LD support.

Installation

npm install lodox-data-viewer

Alternatively, the package can be loaded directly from a CDN with a single script tag, without any build step:

<script type="module" src="https://unpkg.com/lodox-data-viewer"></script>
<lod-bundle src="/data/mona_lisa.jsonld" config="/data/mona_lisa.cards.json"
            base-url="/data/" lang="en"></lod-bundle>

Features

• Web components. <lod-bundle> and <lod-card> are Shadow-DOM components that fetch (or accept) a JSON-LD bundle, run the pipeline, and lay out cards on a responsive grid. A failed fetch renders an error state rather than throwing an exception.
• Themeable by design. The default theme is fully overridable through --lod-card-* CSS custom properties and ::part() selectors. No CSS framework is used.
• Lossless pipeline. Every property of the input appears as a card attribute row, and the unmodified source record remains available at card.raw. The core functions (extractCards and related) can be imported DOM-free from lodox-data-viewer/core for server-side rendering.
• Fully configurable. Row labels are resolved from a configurable vocabulary (_terms), which can rename or hide any field and is both path-aware and ontology-URI-aware. Title, description, and image detection for the generic profile is driven by configurable key lists (_fields). Built-in values serve only as defaults.
• Card configuration. Per-record variant, width, and header colours, or single-word presets. Legacy Tailwind-valued configurations are normalised automatically.

Demo

The live demo loads the package from unpkg, so it always reflects the latest published release. To run it locally against the working tree instead:

npm run demo          # development server: all fixture bundles,
                      # language switching, custom-theme toggle
npm run demo:build    # static build of demo/dist/, deployable to any prefix

Stability contract

Card output is pinned by an executable contract, which makes upgrades safe to review:

• contract/card.schema.json defines the card view-model schema, and contract/card-config.schema.json defines the card-configuration vocabulary.
• fixtures/goldens/*.cards.json are snapshot outputs of the pipeline. The test suite asserts that every build reproduces them exactly (10 bundles, 748 cards, including a 729-record CIDOC-CRM export and a bilingual Chinese/English bundle).

Intentional behavioural changes regenerate the snapshots, and the resulting diff is reviewed as an API change:

npm run regen-goldens

Development

npm install
npm test          # vitest: unit, golden, DOM, and vocabulary tests
npm run typecheck
npm run build     # tsup: ESM, CJS, and type declarations in dist/

Developer documentation is available in dev-docs/, including the architecture and design invariants, a module-by-module code walkthrough, and the full reference.

License

This project is licensed under the MIT License.