Composables
All state management in Parallax Designer is handled through Vue composables. There is no Pinia, Vuex, or other external state store.
Composables follow two patterns:
- Global singletons — Created once at module scope, shared across all consumers. Calling the composable returns the same reactive state every time.
- Factory composables — Accept refs or DOM elements as parameters, creating a new instance tied to the provided context.
useProjectState
Pattern: Factory
The central state composable. Manages the reactive project ref and all layer CRUD operations.
| Export | Description |
|---|---|
project | The reactive ParallaxDesignerProject ref |
defaultProject | Readonly baseline snapshot used by reset and preset flows |
presetNames | Built-in preset name list |
selectedLayer | Computed ref to the currently selected layer (or null) |
setStarter(mode) | Replace current project with 3-layer or 4-layer starter |
addLayer() | Add a new layer with defaults, auto-assign z-index |
removeLayer(id) | Remove a layer by ID with z-index renormalization |
duplicateLayer(id) | Clone a layer with new ID, insert above original |
moveLayer(id, direction) | Move a layer one step up/down while swapping depth values |
reorderLayer(id, targetIndex) | Reorder a layer to a specific index |
resetAll() | Reset current project to defaultProject |
applyPreset(name, strategy) | Apply built-in preset with replace/keep strategy |
selectLayer(id) | Set the selected layer ID in UI state |
setImportedProject(project) | Load imported project and update baseline |
restoreSnapshots(snapshots) | Restore project + baseline for preset undo |
useProjectIO
Pattern: Factory (accepts project ref)
Handles all import/export operations and custom preset management.
| Export | Description |
|---|---|
exportJson() | Serialize project to JSON string |
importJson(text) | Validate and load a JSON string as the current project |
importJsonFile(file) | Validate and load a JSON file as the current project |
prepareRuntimeHtmlExport() | Analyze local IDB image refs and compute export-size planning data |
exportRuntimeHtml(plan, options) | Build runtime HTML output using inline or placeholder IDB mode |
listCustomPresets() | Read custom preset summaries from IndexedDB |
saveCustomPreset(name) | Save current project as a named custom preset to IndexedDB |
loadCustomPreset(id) | Load a custom preset by ID |
deleteCustomPreset(id) | Delete a custom preset from IndexedDB |
clearCustomPresets() | Remove all custom presets from IndexedDB |
useParallaxEngine
Pattern: Factory (accepts container element, layer elements, project ref)
Manages the parallax engine lifecycle: starting/stopping the rAF loop, feeding pointer events, and exposing FPS.
| Export | Description |
|---|---|
fps | Reactive ref to current FPS value |
start() | Begin the requestAnimationFrame loop |
stop() | Cancel the rAF loop |
setPointer() | Manually set normalized pointer position |
Internally tracks pointer position via mousemove events on document, normalizes to [-1, 1], and passes to the engine core. The engine reads the latest project config (scene, harmonics, layer data) from the reactive refs on every frame.
useLayerAssets
Pattern: Factory (accepts project ref)
Resolves idb://asset/<id> image references to browser object URLs.
| Export | Description |
|---|---|
resolvedLayerImageSrc | Reactive map of layer id to resolved image URL |
missingAssetRefs | Reactive list of unresolved idb://asset/<id> refs |
hasLocalAssetRefs | Computed flag indicating any local asset references |
uploadLayerImage(file) | Store uploaded image in IndexedDB and return local ref |
listAssetsWithUsage() | Return saved assets with per-layer usage metadata |
getAssetOptions() | Return {value,label} options for saved-asset dropdown |
deleteAsset(id) | Delete an asset unless currently referenced by layers |
clearAllAssets() | Delete all assets and clear object URLs |
Watches the project's layers for idb:// references, loads the corresponding blobs from IndexedDB via Dexie, creates object URLs, and revokes them on cleanup. Detects missing assets and notifies the user via toast.
useI18n
Pattern: Global singleton
Custom typed i18n system with no external dependency.
| Export | Description |
|---|---|
locale | Readonly ref to the active locale code |
localeMeta | Locale metadata for each supported language |
setLocale(code) | Switch to a different locale (persisted to localStorage) |
toggleLocale() | Cycle to the next supported locale |
t(key, params?) | Typed translation lookup with {name} parameter interpolation |
getHelp(key) | Retrieve localized help content for a given help key |
formatDateTime(ms, opts?) | Locale-aware date/time formatting |
Locale detection priority: localStorage → browser navigator → default (en). Setting a locale updates <html lang> and persists immediately.
useToast
Pattern: Global singleton
Global toast notification system.
| Export | Description |
|---|---|
toasts | Readonly reactive array of active toast objects |
push(message, options?) | Show a toast with timeout and optional action |
dismiss(id) | Dismiss a specific toast |
triggerAction(id) | Run toast action callback then dismiss |
Toasts support an optional action callback (e.g., "Undo" after preset apply).
useHelp
Pattern: Global singleton
Manages the contextual help tooltip state.
| Export | Description |
|---|---|
currentHelp | Readonly ref to the current help payload (or null) |
showHelp(help) | Set the active help content (on mouseenter) |
clearHelp() | Clear the help key with debounce (on mouseleave) |
The debounced clear prevents flickering when moving between adjacent controls.
useHelpDock
Pattern: Factory (accepts panel element ref)
Calculates the position for docking the help tooltip to the overlay panel edge.
| Export | Description |
|---|---|
placement | Computed dock placement (left, right, inline) |
style | Computed CSS position object for docked mode |
Uses the panel's bounding rectangle and viewport dimensions to decide whether to dock left or right of the panel.