DX Improvements Plan
This plan focuses on guardrails and clarity without changing core architecture or public API shape.
Priority Summary
| Priority | Item | Status |
|---|---|---|
| P0 | Actionable dev warnings for missing provider / before-mount calls | implemented |
| P0 | Actionable dev warning for host auto-fallback creation | implemented |
| P1 | Actionable dev warning when dedupe identity collides | implemented |
| P1 | Document API naming guidance and preferred usage patterns | proposed |
| P2 | Add explicit preset guidance for success/error/loading/promise | implemented (docs), proposed (runtime tuning) |
Runtime Warning Strategy
| Scenario | Warning strategy | Action in message | Status |
|---|---|---|---|
| Missing provider | Warn once per method in dev when bridge was previously mounted but is currently unavailable. | Mount <ToastProvider> at app root and avoid conditional unmounts. | implemented |
| Toast triggered before mount | Warn once per method in dev when no bridge has ever been mounted yet. | Delay toast calls until after first render/mount lifecycle. | implemented |
| Missing host fallback | Warn once per missing hostId in dev when store auto-creates host state without a mounted renderer. | Mount <ToastHost hostId="..."/> or <ToastViewport hostId="..."/> in target surface. | implemented |
| Duplicate toast dedupe | Warn once per dedupe identity/mode in dev when a dedupe collision is detected. | Confirm dedupeKey/id intent and selected dedupeMode. | implemented |
API Clarity and Naming Consistency
| Recommendation | Impact | Effort | Status |
|---|---|---|---|
Prefer toast.host("...") for imperative cross-surface calls and useToast(hostId) for component-local flows. | High | Low | proposed |
Add a short naming note: treat ToastViewport as the default host renderer alias, ToastHost for explicit hostId. | Medium | Low | proposed |
Add a docs glossary for dedupe vs grouping vs priority with one-line examples. | High | Medium | proposed |
| Add a migration note for teams moving from single-root toast libraries. | Medium | Medium | proposed |
Default Behavior and Preset Guidance
Current sensible defaults (no breaking changes)
| API | Current baseline |
|---|---|
toast.success(...) | Variant success, host duration defaults apply unless overridden. |
toast.error(...) | Variant error, host duration defaults apply unless overridden. |
toast.loading(...) | Persistent loading toast (persistent: true, duration: "persistent"). |
toast.promise(...) | Loading first, then auto-update to success/error with fallback durations (3000 success, 4500 error) when not supplied. |
Proposed runtime tuning (non-breaking)
| Proposal | Rationale | Status |
|---|---|---|
Add optional host-level variant duration defaults for success and error in docs presets examples. | Make common flows feel consistent without per-call repetition. | proposed |
Add optional docs preset for standard promise flow group behavior (update-in-group). | Reduces duplicate async toasts in retry-heavy screens. | proposed |
Minimal implementation patch list
- Added dev-only warning utility for one-time actionable warnings.
- Added bridge-state-aware warnings to global
toastmethods. - Added host auto-fallback warning when unknown host IDs are used without mounted host renderers.
- Added dedupe collision warning to make dedupe behavior explicit during integration.
Non-breaking guarantee
- No API signatures changed.
- No architecture rewrite performed.
- Runtime changes are warning-only guardrails in dev environments.