59 lines
3.8 KiB
Markdown
59 lines
3.8 KiB
Markdown
# The preset plugin standard — how to ship named variants that appear by themselves
|
|
|
|
A **preset** is one profile rendered N ways by different props: doxa-simple-map ships `prayer`,
|
|
`engagement` and `adoption` from a single `<doxa-simple-map>` element. Presets are **discovered, never
|
|
registered** — nothing in Plugin Studio, the gallery or the manifest generator holds a list of them.
|
|
Verified on the tree as it stands: the only match for "prayer|engagement|adoption" anywhere in
|
|
`plugin-studio.vue` is an unrelated comment about a layout bug.
|
|
|
|
## Declare one file
|
|
|
|
Put `<name>.instances.json` beside your profile in `plugin-designs/<bundle>/`. That file's PRESENCE is
|
|
the whole registration: `discover.mjs` (`detectProfileType`) types a bundle **parameterized** — capability
|
|
2 — because it ships one, and `null` otherwise. Nothing else is consulted.
|
|
|
|
```
|
|
plugin-designs/doxa-simple-map/
|
|
doxa-simple-map.vue the profile
|
|
simple-map.instances.json the presets <- this is the registration
|
|
```
|
|
|
|
Two accepted shapes, both read by `discover.mjs`: a bare array `[{ id, title, props }]`, or an object
|
|
`{ profile, apiBaseUrl, instances: [...] }` when the presets need a base URL or name their profile
|
|
explicitly. Each instance needs `id` (url-safe, becomes the folder), `title` (what a reader sees) and
|
|
`props` (exactly what you would pass the element).
|
|
|
|
## What you get without asking
|
|
|
|
- **A standalone embeddable page per preset** at `<tree>/<bundle>/<instance>/index.html`, nested under
|
|
the profile, each with its own SRI-pinned script tag.
|
|
- **A manifest entry per preset** under the profile's `instances`, so every consumer sees them at once.
|
|
- **A rail row and a gallery card per preset**, from that same manifest.
|
|
- **Capability 2**, derived. Do not hand-declare `"type": "parameterized"` to get it.
|
|
|
|
## The rules that keep it automatic
|
|
|
|
1. **Never add your preset to a list elsewhere.** If a preset needs a change in Plugin Studio to show
|
|
up, that is a defect in the discovery path, not something to work around. The one bundle-name list
|
|
that used to exist is exactly the thing this standard replaced.
|
|
2. **The base profile still stands on its own.** Presets SPLIT one profile into named render targets;
|
|
they do not replace it. `doxa-simple-map/doxa-simple-map/` still accepts live props.
|
|
3. **A preset's `props` MERGE OVER its profile's defaults; they never replace them.** A preset page's
|
|
config is the profile's `<profile>.meta.json` `config`, then the preset's `props` over it, key by key
|
|
(a shallow merge). A default the preset does not repeat is kept: set it in `props` only to change it.
|
|
`check:preset-config-merge` asserts this on the built tree.
|
|
4. **`props` is the whole difference between presets.** If two presets differ by anything the element
|
|
cannot be told through props, they are two profiles, not two presets.
|
|
5. **Presets are not tabs.** A tab nests several components inside one element; a preset renders the
|
|
same element several ways. Choosing the wrong one shows up later as a capability that will not
|
|
derive: tabs make a bundle a composite (cap 4+), presets keep it parameterized (cap 2).
|
|
6. **An `id` is a URL.** It becomes a folder under the tree and is embedded in partner pages, so
|
|
renaming one breaks links already shared. Treat it like the share-link vocabulary: additive.
|
|
|
|
## How to check it worked
|
|
|
|
Build the tree, then read the manifest rather than the screen: your bundle's profile should carry an
|
|
`instances` array with one entry per preset, and `check:capability-derived` should report the profile as
|
|
a real tier. A preset that does not appear is almost always a filename that does not end
|
|
`.instances.json`, or an `instances` key that is not an array — `discover.mjs` treats both as "no
|
|
presets" and types the bundle `single`, silently.
|