61 lines
2.6 KiB
Markdown
61 lines
2.6 KiB
Markdown
|
# Design
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
Pages are Vue 2 + Bootstrap 4 via CDN with swal/toastr dialogs; behavior and
|
||
|
|
endpoints are frozen for this change (see proposal.md). Carbon web components
|
||
|
|
v2.50.0 are available as bundled per-component `.min.js` artifacts on IBM's CDN
|
||
|
|
(verified: button, text-input, dropdown, notification [inline-notification +
|
||
|
|
toast], progress-bar, tag, checkbox, textarea, tile, ui-shell, modal, loading);
|
||
|
|
`@carbon/styles` CSS (jsdelivr) provides tokens + Carbon-styled native
|
||
|
|
controls; IBM Plex Sans comes from Google Fonts.
|
||
|
|
|
||
|
|
## Goals / Non-Goals
|
||
|
|
|
||
|
|
**Goals:** Carbon look across landing + both tools with zero build step;
|
||
|
|
Vue 2 kept as the thin state layer; server untouched.
|
||
|
|
|
||
|
|
**Non-Goals:** Framework rewrite; UX/flow changes; self-hosting assets;
|
||
|
|
replacing vue-croppa.
|
||
|
|
|
||
|
|
## Decisions
|
||
|
|
|
||
|
|
1. **CDN delivery, version-pinned (v2.50.0)** — same pattern as the existing
|
||
|
|
Vue/axios CDNs; zero tooling. Self-hosting is the fallback if CDN
|
||
|
|
availability becomes a field problem.
|
||
|
|
2. **Hybrid controls** — true web components where Vue interacts lightly
|
||
|
|
(cds-button click, cds-tag, cds-inline-notification, cds-toast,
|
||
|
|
cds-progress-bar, cds-tile); Carbon-styled native controls where v-model
|
||
|
|
matters (text inputs, selects, checkboxes, textarea use
|
||
|
|
`cds--text-input`/`cds--select-input`/`cds--checkbox` classes from
|
||
|
|
@carbon/styles CSS). Avoids value/event adapter friction with shadow-DOM
|
||
|
|
inputs.
|
||
|
|
3. **Notification models replace dialogs** — wizard: one inline-notification
|
||
|
|
slot (`notif` state, auto-dismiss on success); cropper: a fixed
|
||
|
|
`cds-toast` viewport fed by a `toasts` array with timed removal. Native
|
||
|
|
`confirm()` stays for dequeue (behavior frozen).
|
||
|
|
4. **`Vue.config.ignoredElements = [/^cds-/]`** plus a
|
||
|
|
`customElements.whenDefined('cds-button').then($forceUpdate)` so
|
||
|
|
pre-upgrade property bindings (disabled, progress value) re-apply after
|
||
|
|
upgrade.
|
||
|
|
5. **style.css rewritten on Carbon tokens** (layout helpers kept: grid, gaps,
|
||
|
|
details grid, editor grid, croppa pad, footer).
|
||
|
|
|
||
|
|
## Risks / Trade-offs
|
||
|
|
|
||
|
|
- [Shadow-DOM inputs would fight Vue v-model] → native controls for fields;
|
||
|
|
web components only for click/display surfaces.
|
||
|
|
- [IBM CDN availability] → pinned version; self-hosting is a drop-in swap of
|
||
|
|
the script/link URLs.
|
||
|
|
- [Lit property set before upgrade] → forceUpdate after whenDefined; disabled
|
||
|
|
states verified in the visual harness.
|
||
|
|
|
||
|
|
## Migration Plan
|
||
|
|
|
||
|
|
Rewrite pages/styles → visual harness screenshots (landing, wizard, cropper at
|
||
|
|
390/768/1280) → unit tests (server untouched) → docker smoke → walkthrough.
|
||
|
|
|
||
|
|
## Open Questions
|
||
|
|
|
||
|
|
None.
|