@micropasts/authority-card 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Daniel Pett
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,252 @@
1
- # Temporary Holding Version
1
+ # @micropasts/authority-card
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Zero-dependency JavaScript Web Components that turn persistent Linked Open Data URIs (**Pleiades**, **Wikidata**, **Getty AAT/TGN/ULAN**, **Nomisma.org**, or custom endpoints) into cached hover popovers and synchronized inspector panels.
4
+
5
+ Available in two flavors:
6
+ - **`<authority-card>`** — Encapsulated Shadow DOM component with CSS custom properties, `::part()` selectors, and custom HTML template hooks.
7
+ - **`<authority-card-tw>`** — Light-DOM component styled with Tailwind CSS utility classes and `dark:` variants.
8
+
9
+ ---
10
+
11
+ ## Table of Contents
12
+
13
+ - [Features](#features)
14
+ - [Project Structure](#project-structure)
15
+ - [Installation & Build](#installation--build)
16
+ - [Quick Start](#quick-start)
17
+ - [Tailwind CSS Version (`<authority-card-tw>`)](#1-tailwind-css-version-authority-card-tw)
18
+ - [Shadow DOM Version (`<authority-card>`)](#2-shadow-dom-version-authority-card)
19
+ - [Synchronized Inspector Panel Mode](#3-synchronized-inspector-panel-mode)
20
+ - [Customizing Styles](#customizing-styles)
21
+ - [Tailwind Utility Overrides](#tailwind-utility-overrides-authority-card-tw)
22
+ - [Shadow DOM Tokens & `::part()`](#shadow-dom-tokens--part-authority-card)
23
+ - [Full Markup Template Override](#full-markup-template-override)
24
+ - [Registering Custom Adapters & Seeding Offline Data](#registering-custom-adapters--seeding-offline-data)
25
+ - [Deploying the Demo to GitHub Pages (`docs/`)](#deploying-the-demo-to-github-pages-docs)
26
+ - [License](#license)
27
+
28
+ ---
29
+
30
+ ## Features
31
+
32
+ - **Pure ES2022 JavaScript:** Written in clean vanilla JavaScript without TypeScript compilation, framework lock-in, or runtime dependencies.
33
+ - **Built-in LOD Adapters:** Resolves URIs from **Pleiades**, **Wikidata**, **Getty Vocabularies (AAT, TGN, ULAN)**, and **Nomisma.org** into a consistent display model.
34
+ - **Request Deduplication & Caching:** Concurrent or repeated lookups for the same URI share a single in-flight promise and cache results in memory.
35
+ - **Offline / Static Hydration:** Pre-seed records from embedded JSON-LD or Linked Art `@graph` payloads via `seedRecords()` so static sites can render without external network requests.
36
+ - **Cross-Component Event Bus:** Emits and listens for `heritage:select` `CustomEvent`s so maps, timelines, graphs, and side panels stay synchronized.
37
+
38
+ ---
39
+
40
+ ## Project Structure
41
+
42
+ ```text
43
+ authority-card/
44
+ ├── .github/
45
+ │ └── workflows/
46
+ │ └── pages.yml # Builds dist + docs/ and deploys docs/ to GitHub Pages
47
+ ├── scripts/
48
+ │ └── build.js # Bundles dist/ and builds self-contained docs/ output
49
+ ├── src/
50
+ │ ├── core.js # Cache, deduplication, event bus, LOD adapters
51
+ │ ├── shadow.js # Encapsulated <authority-card> (CSS vars + ::part + templates)
52
+ │ ├── tailwind.js # Light-DOM <authority-card-tw> (Tailwind utility classes)
53
+ │ ├── demo.html # Source HTML template for the demo
54
+ │ └── index.js # Package entry point
55
+ ├── docs/ # Generated GitHub Pages output (index.html + authority-card.esm.js)
56
+ ├── package.json
57
+ └── README.md
58
+ ```
59
+
60
+ ---
61
+
62
+ ## Installation & Build
63
+
64
+ Install from npm:
65
+
66
+ ```bash
67
+ npm install @micropasts/authority-card
68
+ ```
69
+
70
+ Or build locally from source with zero external build dependencies:
71
+
72
+ ```bash
73
+ npm run build
74
+ ```
75
+
76
+ Running `npm run build` generates:
77
+ - `dist/authority-card.esm.js` — Combined ES Module bundle
78
+ - `dist/authority-card.iife.js` — Global `<script>` bundle (`window.AuthorityCardLib`)
79
+ - `docs/index.html` and `docs/authority-card.esm.js` — Self-contained GitHub Pages demo
80
+
81
+ To build and serve the demo locally:
82
+
83
+ ```bash
84
+ npm run dev
85
+ ```
86
+
87
+ ---
88
+
89
+ ## Quick Start
90
+
91
+ ### 1. Tailwind CSS Version (`<authority-card-tw>`)
92
+
93
+ ```html
94
+ <script type="module" src="./dist/authority-card.esm.js"></script>
95
+
96
+ <p>
97
+ Excavated at
98
+ <authority-card-tw uri="https://pleiades.stoa.org/places/79739">
99
+ Verulamium
100
+ </authority-card-tw>,
101
+ a silver
102
+ <authority-card-tw uri="https://nomisma.org/id/denarius">
103
+ denarius
104
+ </authority-card-tw>
105
+ of
106
+ <authority-card-tw uri="http://www.wikidata.org/entity/Q1405">
107
+ Augustus
108
+ </authority-card-tw>.
109
+ </p>
110
+ ```
111
+
112
+ ### 2. Shadow DOM Version (`<authority-card>`)
113
+
114
+ Works without Tailwind CSS on any static page, CMS, or scholarly edition:
115
+
116
+ ```html
117
+ <script type="module" src="./dist/authority-card.esm.js"></script>
118
+
119
+ <authority-card uri="http://vocab.getty.edu/aat/300037222">
120
+ denarii
121
+ </authority-card>
122
+ ```
123
+
124
+ ### 3. Synchronized Inspector Panel Mode
125
+
126
+ Mount a persistent panel that updates whenever any inline card (or external map, timeline, or graph component) broadcasts `heritage:select`:
127
+
128
+ ```html
129
+ <authority-card-tw mode="panel" listen="heritage:select"></authority-card-tw>
130
+
131
+ <script type="module">
132
+ import { emitSelect } from '@micropasts/authority-card';
133
+
134
+ // Example: triggered when a user selects a site on a map or timeline
135
+ emitSelect(window, 'https://pleiades.stoa.org/places/79739');
136
+ </script>
137
+ ```
138
+
139
+ ---
140
+
141
+ ## Customizing Styles
142
+
143
+ ### Tailwind Utility Overrides (`<authority-card-tw>`)
144
+
145
+ Pass `trigger-class` and `card-class` attributes on individual instances:
146
+
147
+ ```html
148
+ <authority-card-tw
149
+ uri="http://vocab.getty.edu/aat/300037222"
150
+ trigger-class="text-amber-700 font-semibold"
151
+ card-class="border-amber-500 shadow-2xl">
152
+ denarii
153
+ </authority-card-tw>
154
+ ```
155
+
156
+ Or override the shared class dictionary globally at application startup:
157
+
158
+ ```javascript
159
+ import { AuthorityCardTailwind } from '@micropasts/authority-card';
160
+
161
+ AuthorityCardTailwind.classes.popover =
162
+ 'absolute left-0 top-full mt-2 z-50 w-96 rounded-none border-2 border-black bg-white p-4 shadow-lg';
163
+ ```
164
+
165
+ ### Shadow DOM Tokens & `::part()` (`<authority-card>`)
166
+
167
+ Customize CSS custom properties or style exposed `::part()` elements directly from your stylesheet:
168
+
169
+ ```css
170
+ authority-card.custom-theme {
171
+ --ac-bg: #1c1917;
172
+ --ac-fg: #fafaf9;
173
+ --ac-muted: #a8a29e;
174
+ --ac-border: #b45309;
175
+ --ac-radius: 0.25rem;
176
+ --ac-width: 360px;
177
+ }
178
+
179
+ authority-card.custom-theme::part(title) {
180
+ font-family: Georgia, serif;
181
+ color: #fbbf24;
182
+ }
183
+ ```
184
+
185
+ ### Full Markup Template Override
186
+
187
+ Replace the card inner markup while keeping all caching, deduplication, and adapter logic:
188
+
189
+ ```javascript
190
+ import { AuthorityCard } from '@micropasts/authority-card';
191
+
192
+ AuthorityCard.setTemplate((record, esc) => `
193
+ <div class="my-card">
194
+ <strong>${esc(record.label)}</strong> (${esc(record.source)})
195
+ <p>${esc(record.scopeNote)}</p>
196
+ </div>
197
+ `);
198
+ ```
199
+
200
+ ---
201
+
202
+ ## Registering Custom Adapters & Seeding Offline Data
203
+
204
+ ```javascript
205
+ import { registerAdapter, seedRecords } from '@micropasts/authority-card';
206
+
207
+ // 1. Register a custom authority resolver
208
+ registerAdapter({
209
+ name: 'British Museum',
210
+ badgeColor: '#1e3a8a',
211
+ match: (uri) => /collection\.britishmuseum\.org\/id\/object\/([^/?#]+)/i.exec(uri),
212
+ async fetch([, id], uri) {
213
+ const res = await fetch(`${uri}.json`);
214
+ const data = await res.json();
215
+ return {
216
+ id,
217
+ label: data._label || id,
218
+ subtitle: 'British Museum Collection',
219
+ scopeNote: data.referred_to_by?.[0]?.content || '',
220
+ };
221
+ },
222
+ });
223
+
224
+ // 2. Seed records from embedded JSON-LD (zero network requests)
225
+ seedRecords({
226
+ 'https://pleiades.stoa.org/places/79739': {
227
+ source: 'Pleiades',
228
+ badgeColor: '#15803d',
229
+ label: 'Verulamium',
230
+ subtitle: 'Ancient Roman Municipium',
231
+ scopeNote: 'Major Roman town near modern St Albans, Hertfordshire.',
232
+ meta: [{ label: 'Coordinates', value: '51.7519°, -0.3558°' }],
233
+ },
234
+ });
235
+ ```
236
+
237
+ ---
238
+
239
+ ## Deploying the Demo to GitHub Pages (`docs/`)
240
+
241
+ `npm run build` outputs the demo site to `docs/index.html` alongside `docs/authority-card.esm.js`.
242
+
243
+ 1. Push your repository to GitHub with `main` as your default branch.
244
+ 2. In **Settings → Pages**, choose either:
245
+ - **Source: GitHub Actions** (uses `.github/workflows/pages.yml` to run `npm run build` and deploy `./docs`), or
246
+ - **Source: Deploy from a branch** → select `main` and `/docs` after running `npm run build`.
247
+
248
+ ---
249
+
250
+ ## License
251
+
252
+ MIT