@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 +21 -0
- package/README.md +251 -2
- package/dist/authority-card.esm.js +778 -0
- package/dist/authority-card.iife.js +788 -0
- package/package.json +39 -3
- package/src/core.js +316 -0
- package/src/demo.html +189 -0
- package/src/index.js +10 -0
- package/src/shadow.js +281 -0
- package/src/tailwind.js +174 -0
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
|
-
#
|
|
1
|
+
# @micropasts/authority-card
|
|
2
2
|
|
|
3
|
-
|
|
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
|