@learncard/render-method-plugin 4.0.2 → 4.0.3
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/README.md +39 -44
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -20,53 +20,53 @@ const lc = await baseLc.addPlugin(getRenderMethodPlugin(baseLc));
|
|
|
20
20
|
|
|
21
21
|
### Write side
|
|
22
22
|
|
|
23
|
-
| Method
|
|
24
|
-
|
|
25
|
-
| `attachRenderMethod`
|
|
26
|
-
| `buildTemplateRenderMethod` | `(config) => TemplateRenderMethod` | Builds a `TemplateRenderMethod` descriptor without mutating a VC.
|
|
23
|
+
| Method | Signature | Description |
|
|
24
|
+
| --------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
25
|
+
| `attachRenderMethod` | `(vc, config?) => UnsignedVC` | Attaches a `TemplateRenderMethod` to the VC and injects the JSON-LD context. **Opt-in:** returns the VC unchanged when `config` is omitted. Merges with existing `renderMethod` entries. |
|
|
26
|
+
| `buildTemplateRenderMethod` | `(config) => TemplateRenderMethod` | Builds a `TemplateRenderMethod` descriptor without mutating a VC. |
|
|
27
27
|
|
|
28
28
|
### Read side
|
|
29
29
|
|
|
30
30
|
Layered API — pick the level that fits your need:
|
|
31
31
|
|
|
32
|
-
| Method
|
|
33
|
-
|
|
34
|
-
| `findTemplateRenderMethod`
|
|
35
|
-
| `findTemplateRenderMethods`
|
|
36
|
-
| `getSvgMustacheRenderMethod` | `(vc) => TemplateRenderMethod \| null`
|
|
37
|
-
| `findRenderMethod`
|
|
38
|
-
| `findRenderMethods`
|
|
39
|
-
| `getRenderMethods`
|
|
40
|
-
| `buildRenderData`
|
|
32
|
+
| Method | Signature | When to use |
|
|
33
|
+
| ---------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
|
|
34
|
+
| `findTemplateRenderMethod` | `(vc, suite \| suites[]) => TemplateRenderMethod \| null` | **Most common.** Filter by `renderSuite` string. Pass an array for capability negotiation. |
|
|
35
|
+
| `findTemplateRenderMethods` | `(vc, suite \| suites[]) => TemplateRenderMethod[]` | All matches of a suite (or any of several). |
|
|
36
|
+
| `getSvgMustacheRenderMethod` | `(vc) => TemplateRenderMethod \| null` | Backward-compatible alias for `findTemplateRenderMethod(vc, 'svg-mustache')`. |
|
|
37
|
+
| `findRenderMethod` | `(vc, predicate) => T \| null` | Escape hatch: arbitrary predicate for non-template render methods. |
|
|
38
|
+
| `findRenderMethods` | `(vc, predicate) => T[]` | Same, all matches. |
|
|
39
|
+
| `getRenderMethods` | `(vc) => RenderMethod[]` | Raw access. Unwraps `CertifiedBoostCredential`, normalizes object↔array. No validation. |
|
|
40
|
+
| `buildRenderData` | `(vc, renderProperty?) => Record<string, unknown>` | Portable Mustache context (adds `vc` / `credential` / `credentialSubjects` aliases). Optional RFC 6901 overlay. |
|
|
41
41
|
|
|
42
42
|
### Type guards (composable selection)
|
|
43
43
|
|
|
44
|
-
| Guard
|
|
45
|
-
|
|
46
|
-
| `isTemplateRenderMethod(rm)`
|
|
44
|
+
| Guard | Narrows to |
|
|
45
|
+
| ------------------------------- | ------------------------------------------------------------ |
|
|
46
|
+
| `isTemplateRenderMethod(rm)` | `TemplateRenderMethod` (Zod-validated shape) |
|
|
47
47
|
| `isSvgMustacheRenderMethod(rm)` | `TemplateRenderMethod` with `renderSuite === 'svg-mustache'` |
|
|
48
48
|
|
|
49
49
|
### Constants
|
|
50
50
|
|
|
51
|
-
-
|
|
52
|
-
-
|
|
51
|
+
- `DEFAULT_TEMPLATE_ID` — URL of the default hosted LearnCard template. Pass as `templateId` to opt in.
|
|
52
|
+
- `RENDER_METHOD_CONTEXT` — JSON-LD context URL injected by `attachRenderMethod`. See the [draft context warning](#draft-context-warning).
|
|
53
53
|
|
|
54
54
|
### Throws
|
|
55
55
|
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
56
|
+
- `attachRenderMethod` / `buildTemplateRenderMethod` throw if:
|
|
57
|
+
- `templateId` is provided but is not an `http://` or `https://` URL.
|
|
58
|
+
- `templateValue` is provided but is empty or whitespace-only.
|
|
59
|
+
- `buildTemplateRenderMethod` is called without either field set.
|
|
60
60
|
|
|
61
61
|
### `AttachRenderMethodConfig`
|
|
62
62
|
|
|
63
63
|
`templateId` and `templateValue` are mutually exclusive — provide one or the other. The discriminated union enforces this at compile time.
|
|
64
64
|
|
|
65
|
-
| Field
|
|
66
|
-
|
|
67
|
-
| `templateId`
|
|
68
|
-
| `templateValue`
|
|
69
|
-
| `renderProperty` | `string[]?` | JSON Pointer paths (RFC 6901) scoping which VC fields are exposed to the template.
|
|
65
|
+
| Field | Type | Description |
|
|
66
|
+
| ---------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
|
|
67
|
+
| `templateId` | `string` | HTTPS URL of a hosted SVG Mustache template. Only `http://` and `https://` schemes are accepted. |
|
|
68
|
+
| `templateValue` | `string` | Inline SVG Mustache content (embedded as a URL-encoded `data:image/svg+xml,` URI). Must be non-empty. |
|
|
69
|
+
| `renderProperty` | `string[]?` | JSON Pointer paths (RFC 6901) scoping which VC fields are exposed to the template. |
|
|
70
70
|
|
|
71
71
|
## Opt-in semantics
|
|
72
72
|
|
|
@@ -135,9 +135,7 @@ const renderMethod = lc.invoke.buildTemplateRenderMethod({
|
|
|
135
135
|
|
|
136
136
|
## Feature-flag interaction
|
|
137
137
|
|
|
138
|
-
In `apps/learn-card-app`,
|
|
139
|
-
|
|
140
|
-
In other words: enabling the LaunchDarkly flag turns on rendering for credentials that already have a `renderMethod`, but it does not retroactively change which credentials carry one.
|
|
138
|
+
In `apps/learn-card-app`, credentials with a supported `renderMethod` are rendered across previews, claim surfaces, and the display-style selector. Attaching a render method remains a per-callsite decision and follows the opt-in semantics above.
|
|
141
139
|
|
|
142
140
|
## Draft context warning
|
|
143
141
|
|
|
@@ -149,14 +147,14 @@ https://digitalbazaar.github.io/vc-render-method-context/contexts/v2rc2.jsonld
|
|
|
149
147
|
|
|
150
148
|
The `v2rc2` suffix means "v2, release candidate 2". This is **not** a finalized W3C TR. Risks of issuing VCs that reference this URL in their `@context`:
|
|
151
149
|
|
|
152
|
-
-
|
|
153
|
-
-
|
|
154
|
-
-
|
|
150
|
+
- The URL could move, be renamed, or 404 — JSON-LD context resolution would fail at verification time.
|
|
151
|
+
- Term definitions could change between rc2 and a final spec, breaking interpretation.
|
|
152
|
+
- The context is not statically cached by DidKit — verification incurs a network fetch.
|
|
155
153
|
|
|
156
154
|
Mitigation plan (not yet implemented):
|
|
157
155
|
|
|
158
|
-
-
|
|
159
|
-
-
|
|
156
|
+
- Bundle the context locally, mirroring the pattern in `packages/learn-card-contexts/`.
|
|
157
|
+
- Migrate to the stable W3C TR context URL when the spec finalizes.
|
|
160
158
|
|
|
161
159
|
Tracking: <https://www.w3.org/TR/vc-render-method/>
|
|
162
160
|
|
|
@@ -171,10 +169,7 @@ The read-side API is intentionally generic so new render suites can be added by
|
|
|
171
169
|
const found = lc.invoke.findTemplateRenderMethod(vc, 'html-mustache');
|
|
172
170
|
|
|
173
171
|
// Capability negotiation — first match across the suites your renderer supports
|
|
174
|
-
const renderable = lc.invoke.findTemplateRenderMethod(vc, [
|
|
175
|
-
'svg-mustache',
|
|
176
|
-
'html-mustache',
|
|
177
|
-
]);
|
|
172
|
+
const renderable = lc.invoke.findTemplateRenderMethod(vc, ['svg-mustache', 'html-mustache']);
|
|
178
173
|
|
|
179
174
|
// All matches (e.g., when offering the user a choice)
|
|
180
175
|
const allHtml = lc.invoke.findTemplateRenderMethods(vc, 'html-mustache');
|
|
@@ -186,13 +181,13 @@ The plugin handles **selection** and **data shaping** uniformly across suites. T
|
|
|
186
181
|
|
|
187
182
|
## Architectural boundary
|
|
188
183
|
|
|
189
|
-
-
|
|
190
|
-
-
|
|
184
|
+
- **In the plugin** (this package): data domain — attach renderMethod to VCs, find renderMethod entries, shape Mustache contexts. Pure, isomorphic, CLI-safe.
|
|
185
|
+
- **In the app**: render domain — Mustache hydration into a target format, DOMPurify sanitization, DOM insertion. Browser-specific.
|
|
191
186
|
|
|
192
187
|
The seam is "data that describes how to render" (plugin) vs. "execute the render and put pixels on screen" (app).
|
|
193
188
|
|
|
194
189
|
## Notes
|
|
195
190
|
|
|
196
|
-
-
|
|
197
|
-
-
|
|
198
|
-
-
|
|
191
|
+
- Only `svg-mustache` is supported as a render suite at this time. The renderer in `apps/learn-card-app/src/helpers/renderMethod.helpers.ts` performs DOMPurify sanitization on the hydrated SVG before insertion.
|
|
192
|
+
- See `src/types.ts` for types, `src/plugin.ts` for the write side, `src/read.ts` for the read side.
|
|
193
|
+
- See `src/test/plugin.test.ts` for the full behavior contract.
|