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

  1. Identify the account. Scope snapshots by backend deployment and account ID. Visitors do not start the account download or edit transport.
  2. 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.
  3. 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.
  4. 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.
  5. 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

PlacePurpose
MemoryThe current scope’s query answers, timestamps, dirty keys and invalidations.
IndexedDBentries: 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.
sessionStorageA 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.
localStorageAllowlisted 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.

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

  1. 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.
  2. Move past the threshold. Under threshold pixels (3 by default) nothing happens. Past it, onStart("pointer") runs and onPreview reports the starting value.
  3. 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.
  4. Release. onCommit receives the value rounded to step, once, and then onEnd(false) runs.
  5. 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

KeyWhat it does
Arrow Right, Arrow Up on a vertical handleOne step up.
Arrow Left, Arrow Down on a vertical handleOne step down.
Shift with an arrowOne shiftStep, ten steps by default.
HomeTo min.
EndTo max, when there is one.
EscapeCancels 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

OptionDefaultWhat it does
valueRequiredThe current value.
min, max0, noneThe range.
step1What a commit rounds to, and one key’s change.
shiftStepTen stepsOne key’s change with Shift.
axishorizontalhorizontal or vertical.
gain1Value per pixel of travel.
threshold3Pixels of travel before a drag starts.
snapPreviewfalseRounds the preview to step too.
immediateKeyboardfalseCommits on each key.
keyboardtruefalse leaves the keys alone.
disabledfalseIgnores the pointer and the keys.
onCommit(value)RequiredThe change is final.
onPreview(value)NoneShow this value without saving it.
onStart(kind)NoneA drag or keyboard change began: pointer or keyboard.
onEnd(cancelled)NoneIt ended, and whether it was cancelled.
onPointerStart(event)NoneThe press, before any movement.
onTap(event)NoneA press released without moving.

API

NameKindWhat it does
labelAttributeThe slider’s accessible name.
optionsPropertyThe value and callbacks above.
--ds-handle-inkTokenThe line and focus ring, currentColor by default.
--ds-handle-label-inkTokenThe tag’s words.
--ds-handle-label-paperTokenThe 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

VariantWhereSize
BarAnywhereThree squares wide (60px), two pixels high.
SpinnerOn its ownOne square.
SpinnerInside a button or fieldOne 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

NameKindWhat it does
labelAttributeNames the operation. Empty by default, which reads the shared word.
variantAttributebar (the default) or spinner.
gradientAttributeDraws it in the shared palette.
--ds-loading-widthTokenA bar’s width.
--ds-loading-fillTokenA bar’s fill.
--ds-loading-durationTokenA bar’s time across.
--ds-loading-sizeTokenA 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.