@learncard/render-method-plugin 4.0.2 → 4.0.4

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.
Files changed (8) hide show
  1. package/README.md +39 -44
  2. package/dist/render-method-plugin.cjs.development.cjs +762 -261
  3. package/dist/render-method-plugin.cjs.development.cjs.map +3 -3
  4. package/dist/render-method-plugin.cjs.production.min.cjs +14 -14
  5. package/dist/render-method-plugin.cjs.production.min.cjs.map +3 -3
  6. package/dist/render-method-plugin.esm.js +756 -255
  7. package/dist/render-method-plugin.esm.js.map +3 -3
  8. package/package.json +13 -18
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 | 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. |
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 | 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. |
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 | Narrows to |
45
- |---|---|
46
- | `isTemplateRenderMethod(rm)` | `TemplateRenderMethod` (Zod-validated shape) |
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
- - `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).
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
- - `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.
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 | 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. |
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`, the `useRenderMethodEnabled` hook gates the **display** path (the `RenderMethodDisplay` component, the `BoostDisplayStyleSelector`, the `getSvgMustacheRenderMethod` lookup). It does **not** gate the write path — whether to attach a render method to a credential is a per-callsite decision and follows the opt-in semantics above.
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
- - The URL could move, be renamed, or 404 — JSON-LD context resolution would fail at verification time.
153
- - Term definitions could change between rc2 and a final spec, breaking interpretation.
154
- - The context is not statically cached by DidKit — verification incurs a network fetch.
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
- - Bundle the context locally, mirroring the pattern in `packages/learn-card-contexts/`.
159
- - Migrate to the stable W3C TR context URL when the spec finalizes.
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
- - **In the plugin** (this package): data domain — attach renderMethod to VCs, find renderMethod entries, shape Mustache contexts. Pure, isomorphic, CLI-safe.
190
- - **In the app**: render domain — Mustache hydration into a target format, DOMPurify sanitization, DOM insertion. Browser-specific.
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
- - 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.
197
- - See `src/types.ts` for types, `src/plugin.ts` for the write side, `src/read.ts` for the read side.
198
- - See `src/test/plugin.test.ts` for the full behavior contract.
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.