IndexedDB
The app remembers its last server answers on this device, so a returning reader sees their content while fresh answers arrive.
A ghost component in 1 Root: it draws nothing, takes no space and has no focus or pointer target. The app starts its account runtime once from the root; pages read through that runtime. This AppLike guide documents an existing application pattern, not an exported element or a storage service supplied by DS1.
Open, remember, refresh
- Identify the account. Scope snapshots by backend deployment and account ID. Visitors do not start the account download or edit transport.
- Read what is already here. Memory, the tab’s session copy and a small allowlist of settings metadata can answer synchronously. IndexedDB hydrates asynchronously, once per scope. A late disk answer cannot replace a newer value or revive an invalidated record.
- Draw, then listen. A page receives its cached answer immediately if one exists, with pending local changes projected over it. Its live query stays subscribed. The next server answer replaces the snapshot; a refused query removes its cached answer and reports the error. There is no global loading gate.
- Refresh in the background. Startup reads the account’s lists and overview. Lists whose
updated_at still matches reuse their held items; the next sync after six hours reads every list again. Up to four list reads run together. Reconnecting starts another sync.
- Remember only the changes. Changed query keys are queued for persistence. Switching accounts or signing out clears the snapshot state and queues deletion of the stored account.
What lives where
| Place | Purpose |
| Memory | The current scope’s query answers, timestamps, dirty keys and invalidations. |
| IndexedDB | entries: one { value, time } record per query key. meta: the account scope. A scope change clears the previous account’s entries in the same write transaction. |
| sessionStorage | A warm tab copy: the newest 40 eligible answers, trimmed until its serialized string is at most 1,000,000 characters. These limits apply to this copy, not the IndexedDB database. |
| localStorage | Allowlisted settings display metadata and sync timestamps. Pending edits are separate records here, not in the IndexedDB snapshot store. |
A query key combines its function name and JSON arguments, with object keys sorted recursively. Use non-secret identifiers as arguments; never put credentials or access tokens in snapshot keys or values. The account scope separates caches; the server still decides access.
One record per query
The storage adapter opens a versioned database with two object stores. A read loads its scope, keys and values in one transaction. A write puts changed records and deletes removed keys in one read-write transaction, with relaxed durability. It resolves when the transaction completes and closes the database in finally.
Do not serialize the whole account after every edit. A list already holds its items, so identical item and note snapshots are omitted from disk and derived from the list when it is read back. This deduplication belongs to the application’s data model.
- Small writes are grouped after 250 ms. Large overview records and the tab copy wait until edits settle for five seconds.
- Equal answers keep their existing value object and usually write nothing. A server-confirmed unchanged record is eligible for a disk timestamp refresh after one day.
- Snapshots older than seven days are not used. Expired records encountered during disk hydration are queued for removal.
pagehide and a hidden document trigger a full flush. These are best-effort opportunities, not a guarantee that a closing browser will finish writing.
Pending edits stay separate
The snapshot is the last confirmed answer. An edit queue persists local intent and projects it over that answer for immediate feedback. After the server accepts an edit, the queue marks it confirmed, folds it into the snapshots and waits for their quick flush before removing the queued record. If device storage fails, the confirmed record stays queued. A cached read alone is not an offline editing or conflict-resolution system.
Account and failure boundaries
Every asynchronous read, refresh and write checks that its captured scope still matches the active account. Sign-out clears memory, timers, session and settings copies, and serializes the IndexedDB clear after outstanding writes. Storage events detect account changes in other tabs. A profile preference change is not an account switch.
Opening the database times out after two seconds and rejects blocked or failed opens. Startup refresh stops after 30 seconds. Failed snapshot reads are optional: the app continues with memory and live queries. Failed writes restore dirty keys for a later flush. Storage can be unavailable or cleared by the browser, so snapshots are a cache, never the only copy of the reader’s work.
Wiring in the app
These are the reference implementation’s module responsibilities, not imports from the App package:
initializeApp.ts- Starts the account runtime on initialization, account changes, navigation and reconnect; skips visitors.
startupStorage.ts- Owns database opening, transactions, per-query records and clearing the stored scope.
querySnapshots.ts- Owns memory, hydration, freshness, deduplication, batching and persistence failure handling.
startupSync.ts- Collects account data, reuses unchanged lists and schedules full refreshes.
cachedQueries.ts- Delivers cached answers, subscribes to live results and cleans up page subscriptions.
localChanges.ts- Keeps the separate edit queue and projects pending changes over confirmed snapshots.
This public guide describes an application pattern. Each application owns its account scope, records and storage permissions.
Spacing handle
Adjust a spacing value by dragging or using the arrow keys. The application owns preview, commit and undo.
A public control in the AppLike extension, built for editors. It holds no product state: placement, undo snapshots and the surrounding document belong to the consumer. The value comes in through options, and changes go out through callbacks.
Use it
import '@0001-labs/app/spacing-handle';
handle.options = {
value: 20, min: 0, max: 100, step: 10,
onPreview: value => preview(value),
onCommit: value => save(value)
};
options is a property, not an attribute, and is read afresh at every event. Update its value after a commit: the handle never changes the value it was given.
A drag
- Press. A primary press with the main button takes the pointer and calls
onPointerStart. The second press of a double click is ignored, so a double click stays the application’s. A disabled handle ignores the press.
- Move past the threshold. Under
threshold pixels (3 by default) nothing happens. Past it, onStart("pointer") runs and onPreview reports the starting value.
- Preview. Each move previews the starting value plus the pointer’s travel times
gain, within min and max. The preview is raw, following the hand, unless snapPreview rounds it to step.
- Release.
onCommit receives the value rounded to step, once, and then onEnd(false) runs.
- Or cancel. Escape, a cancelled pointer, lost capture, the window losing focus, the handle becoming disabled or the handle being removed all stop the drag.
onPreview receives the starting value, nothing commits, and onEnd(true) runs.
A release without movement is a tap: onTap runs and nothing else. Set gain to 2 for a handle at the midpoint of a gap, which grows on both sides, so the midpoint stays under the pointer.
Keyboard
| Key | What it does |
| Arrow Right, Arrow Up on a vertical handle | One step up. |
| Arrow Left, Arrow Down on a vertical handle | One step down. |
| Shift with an arrow | One shiftStep, ten steps by default. |
| Home | To min. |
| End | To max, when there is one. |
| Escape | Cancels keys pressed so far: the preview goes back and nothing commits. |
By default keys accumulate in the preview and commit once, on key up or when the handle loses focus, so holding an arrow writes one change. immediateKeyboard commits on every key instead, with no preview. Removing the handle never reverses a commit already made. Set keyboard: false when a native input owns the keys.
On the grid
The handle is one square in each direction. A 1px line runs through its middle: upright for a horizontal handle, which moves across, and flat for a vertical one. The cursor follows the axis. Under the pointer or keyboard focus, the value shows beside the line in small type on a filled tag one square high. Focus is a 1px ring standing 2px off, and a disabled handle is at half strength.
Accessibility
The face is a role="slider" named by label, “Spacing” by default. Write what it changes: “Gap above the title”. It carries aria-orientation, aria-valuemin, aria-valuemax and aria-valuenow, and aria-disabled when disabled, when it also leaves the tab order. With no min the minimum is 0, and with no max the slider reports 1,000,000.
Options
| Option | Default | What it does |
value | Required | The current value. |
min, max | 0, none | The range. |
step | 1 | What a commit rounds to, and one key’s change. |
shiftStep | Ten steps | One key’s change with Shift. |
axis | horizontal | horizontal or vertical. |
gain | 1 | Value per pixel of travel. |
threshold | 3 | Pixels of travel before a drag starts. |
snapPreview | false | Rounds the preview to step too. |
immediateKeyboard | false | Commits on each key. |
keyboard | true | false leaves the keys alone. |
disabled | false | Ignores the pointer and the keys. |
onCommit(value) | Required | The change is final. |
onPreview(value) | None | Show this value without saving it. |
onStart(kind) | None | A drag or keyboard change began: pointer or keyboard. |
onEnd(cancelled) | None | It ended, and whether it was cancelled. |
onPointerStart(event) | None | The press, before any movement. |
onTap(event) | None | A press released without moving. |
API
| Name | Kind | What it does |
label | Attribute | The slider’s accessible name. |
options | Property | The value and callbacks above. |
--ds-handle-ink | Token | The line and focus ring, currentColor by default. |
--ds-handle-label-ink | Token | The tag’s words. |
--ds-handle-label-paper | Token | The tag’s fill. |
It has no slots, parts or events. bindSpacingHandle(target, () => options) gives any element of your own the same pointer and keyboard behaviour, and returns a function that removes it, cancelling a drag in progress. Style that element with the class ds-spacing-control from ds-spacing-handle.css.
React
Sync 1's components export copies the React adapter with spacing-handle (react/spacing-handle.ts), unless the product asks for "react": false.
import { SpacingHandle } from './design/react/spacing-handle';
<SpacingHandle label="Gap above the title" value={gap} step={10} onCommit={save} />
It takes the options as props, reading the latest on each event, plus label, valueText for aria-valuetext, className, style and onDoubleClick. Children replace the value tag. It renders a native target and brings its styles with it, so it works before hydration, and it stops its clicks from bubbling up.
Loading indicator
Automatic pending-state feedback, with an accessible status label. Use a bar for a page or a spinner beside a control.
A public control in the AppLike extension. It shows that the application is waiting, and for nothing else: it is not content a person adds, and it never stands for elapsed time or a percentage. The application mounts it while work is pending and removes it after.
Colour
A gradient indicator in the shared palette on a neutral track.
By default it takes currentColor, on a track of the same colour at low strength, so it follows the words around it and preserves a surrounding brand. gradient is opt-in. --ds-loading-fill changes a bar’s fill.
Use it
import '@0001-labs/app/loading';
<ds-loading label="Loading document"></ds-loading>
<ds-loading variant="spinner"></ds-loading>
<ds-loading gradient></ds-loading>
<ds-loading gradient variant="spinner"></ds-loading>
On the grid
| Variant | Where | Size |
| Bar | Anywhere | Three squares wide (60px), two pixels high. |
| Spinner | On its own | One square. |
| Spinner | Inside a button or field | One control high (16px), the size of the icon it stands in for. |
The spinner finds out for itself whether it stands in a button or a field when it connects, through shadow roots too. The list is LOADING_CONTROLS: button, [role="button"], ds-button, ds-input, ds-select and the native classes .ds-button, .ds-field, .ds-input and .ds-select. --ds-loading-size sets it outright. All measures are multiplied by the surface scale.
Motion
The bar’s fill slides across its track every 1.8 seconds, which --ds-loading-duration changes. The spinner turns every 0.72 seconds, in transform alone. Under reduced motion both stop: the bar stands as a full fill at lower strength, and the spinner as a still ring.
Accessibility
The element is a role="status" with aria-busy="true", named by label; the moving fill is hidden from assistive technology. Write what is happening: “Opening document”. Unset, the label is the shared word “Loading” in the page’s language, which follows a change of language when the page loads the shared words. Without them it reads “Loading” in English.
Where a surrounding status already speaks, use React’s decorative: the indicator then has no role or label and is hidden from assistive technology.
API
| Name | Kind | What it does |
label | Attribute | Names the operation. Empty by default, which reads the shared word. |
variant | Attribute | bar (the default) or spinner. |
gradient | Attribute | Draws it in the shared palette. |
--ds-loading-width | Token | A bar’s width. |
--ds-loading-fill | Token | A bar’s fill. |
--ds-loading-duration | Token | A bar’s time across. |
--ds-loading-size | Token | A spinner’s size. |
It has no slots, parts or events. The module also exports LOADING_LABEL, LOADING_CONTROLS and inLoadingControl(element). Add hidden to hide it.
React
Sync 1's components export copies the React adapter with loading (react/loading.ts), unless the product asks for "react": false.
import { LoadingIndicator } from './design/react/loading';
<LoadingIndicator label="Opening document" variant="spinner" />
It takes label, variant, gradient, decorative, className and style. It renders plain markup with its own styles and no DOM runtime, so it shows before hydration. Its spinner takes one control high from a surrounding button or field in the same document.