@lotics/app-sdk 0.46.0 → 0.47.0

package/docs/navigation_and_state.md

@@ -0,0 +1,289 @@
+# Navigation & client state
+
+How an app's screens and view-state live in the URL, and how small client-side
+state persists across sessions. Covers **`AppRouter`** (multi-screen in-app
+routing from the `@lotics/app-sdk/router` entry), **`useUrlState`** + the
+**`urlParam`** codecs (a typed, declared slice of filters/search/sort/tab kept
+in the address bar), and **`useRecents`** (a localStorage-backed recently-used
+list). Read this when an app has more than one screen, when a filtered view
+must survive refresh or be shareable as a link, or when a picker should
+remember what the user chose last.
+
+## The two URL layers
+
+The URL carries two independent kinds of app state, each owned by exactly one
+mechanism:
+
+| Layer | Owner | What it holds | History behavior |
+| --- | --- | --- | --- |
+| **Routing** (path) | `AppRouter` | Which screen is showing (`/`, `/item/:id`) | Navigations push entries — browser Back/Forward walk screens |
+| **View-state** (query params) | `useUrlState` | Filters, search, sort, active tab | Writes replace in place — never a history entry |
+
+They compose: a screen is a path; the screen's filters ride as query params.
+Neither is server state — `useUrlState` values are *client* state that you feed
+into a query's *server* params (see [named-query params](./queries.md) and the
+[data-fetching hooks](./data_fetching.md) they drive). Nothing here is
+persisted server-side; the address bar is the only store.
+
+The embedded-vs-standalone distinction below is the runtime's: embedded means
+the app runs in an iframe inside the Lotics host, standalone means it runs on
+its own `<slug>.lotics.app` page (see [runtime](./runtime.md)). Both mechanisms
+expose the same API in both modes with no per-mode code (the few behavioral
+differences — embedded first-paint hydration, cross-screen persistence — are
+flagged below); mode is detected automatically (from the `lotics_host` param
+the host puts on the iframe src — `isEmbedded()` from the main entry exposes it
+if you need it).
+
+## `AppRouter` — in-app routing
+
+For a multi-screen app, write plain react-router and wrap the route config in
+`AppRouter`:
+
+```tsx
+import { AppRouter } from "@lotics/app-sdk/router";
+
+export default function App() {
+  return (
+    <AppRouter
+      routes={[
+        { path: "/", element: <ItemList /> },
+        { path: "/item/:id", element: <ItemDetail /> },
+      ]}
+    />
+  );
+}
+```
+
+`routes` is a react-router `RouteObject[]` — nested `children`, `index`
+routes, and splats all work. Inside the tree, use react-router normally:
+`useNavigate`, `useParams`, `useLocation`, `<Link>`, `<Outlet>`.
+
+- **Separate entry, optional peer.** `AppRouter` ships from
+  `@lotics/app-sdk/router` (signature: `dist/src/router.d.ts`) so apps that
+  don't route never pull react-router into their bundle. `react-router-dom`
+  (`^7`) is an **optional peer dependency** — an app that imports the router
+  entry must install it itself; nothing else in the SDK needs it.
+- **Limitation: element routing only.** `AppRouter` mounts a plain browser
+  router, not a react-router *data* router — route `loader`/`action` fields
+  are ignored, and `useLoaderData` **throws** ("must be used within a data
+  router"). Fetch data inside screen components with the
+  [data-fetching hooks](./data_fetching.md).
+
+### The URL model
+
+The app owns its **own** URL in both modes — the host URL only ever *mirrors*
+the screen, it never drives the router:
+
+- **Standalone** (`<slug>.lotics.app`): a normal browser router. Screens are
+  real path URLs, browser Back/Forward are native, and deep-links/refresh work
+  because the app host serves the entry HTML for any path the build didn't
+  emit (SPA fallback).
+
+  **Limitation:** the SPA fallback only fires for paths containing **no `.`
+  anywhere** — a route path with a dot in it (e.g. `/item/v1.2`) navigates
+  fine client-side but returns 404 on standalone refresh/deep-link. Keep dots
+  out of route paths (put such values in a query param instead).
+
+- **Embedded** (inside the Lotics host): the router drives the **iframe's own
+  URL** (the iframe is same-origin to itself). The user sees the host's
+  address bar, never the iframe's, and the host never sees the iframe's URL —
+  so in-app navigation never causes a host navigation and never remounts or
+  reloads the app. The iframe's history still participates in the browser's
+  session history, so **Back/Forward walk app screens** (and then leave the
+  app).
+
+### Share and refresh survival (embedded)
+
+To keep embedded screens shareable and refresh-survivable, `AppRouter` mirrors
+the current screen (path + query + hash) into the **host** URL under the
+`_loc` query param — a non-remounting `history.replaceState` on the host,
+never a navigation. The mirror is write-only from the app's side; on (re)load
+the host reads `_loc` back and bakes it into the iframe `src`, so the app
+boots *directly* at the saved screen — no extra code in the app.
+
+Observable details:
+
+- The `lotics_host` handshake param is stripped from the mirrored href — it is
+  part of the iframe's boot URL, never part of a route.
+- The host honours `_loc` only when it resolves same-origin to the app;
+  anything else (a foreign URL, malformed input) boots the app at its root.
+- Standalone needs none of this — the app's own URL already *is* the screen.
+
+**Warning — reserved query keys:** `_loc` (the screen mirror), `lotics_host`
+(the host handshake), and `__mock` (the [mock harness](./runtime.md)) belong
+to the framework. Never declare them in a `useUrlState` shape or write them
+yourself; undeclared keys are already preserved automatically (see below).
+
+## `useUrlState` — typed view-state in the address bar
+
+Save a declared slice of view-state into the address bar so a filtered view
+survives refresh and is shareable/bookmarkable as a link. Exported from the
+main entry (signature: `dist/src/use_url_state.d.ts`):
+
+```tsx
+import { urlParam, useUrlState } from "@lotics/app-sdk";
+
+const [filters, setFilters] = useUrlState({
+  q: urlParam.string.withDefault(""),
+  status: urlParam.enum(["open", "won", "lost"]), // optional → undefined when absent
+  tags: urlParam.arrayOf(urlParam.string).withDefault([]),
+  page: urlParam.number.withDefault(1),
+});
+// filters: { q: string; status: "open" | "won" | "lost" | undefined; tags: string[]; page: number }
+
+setFilters({ status: "won" }); // merge into the address bar → ?status=won
+setFilters({ page: 2 });       // merge; replaces in place — no history entry
+```
+
+Semantics — each of these is load-bearing:
+
+- **The URL is the only store.** `filters` is decoded fresh from the current
+  params each render — don't mirror it into `useState`; there is no second
+  copy to drift.
+- **Writes replace, never push.** Every `setFilters` is a
+  `history.replaceState`-style write — view-state changes never add history
+  entries. The back button belongs to routing, not to filters.
+- **Writes are merges over declared keys only.** A patch touches exactly the
+  keys it names; every other query param — a key a second `useUrlState` owns,
+  the framework's `lotics_host`/`__mock`/`_loc`, a future host param — is read
+  past and preserved on write. Multiple `useUrlState` calls with disjoint keys
+  coexist without a namespace rule.
+- **Defaults are omitted from the URL.** A value equal to its
+  `.withDefault(...)` fallback encodes to nothing — `?page=1` and `?q=` never
+  appear, so a shared link carries only what the user actually changed.
+  Setting a key back to its default (or an optional key to `undefined`)
+  *clears* it from the URL.
+- **Writes are optimistic.** The returned values reflect a write immediately.
+  If the underlying address-bar write fails, the failure is logged
+  (`console.error`) and the in-session state is kept — only cross-refresh
+  persistence is lost.
+- **Back/Forward and hand-edited URLs flow back in.** External URL changes
+  re-decode into fresh values automatically in both modes.
+- **Embedded first paint hydrates one tick late.** A standalone app reads its
+  own URL synchronously, so the first render already has the URL's values. An
+  embedded app cannot read the cross-origin host URL synchronously: the first
+  render sees the declared defaults, and the real values arrive right after
+  mount over the bridge. Gate an expensive initial fetch accordingly (e.g.
+  `enabled`, see [data fetching](./data_fetching.md)) or accept one
+  re-render. A user edit made before hydration lands is never clobbered by it.
+- **Declare the shape statically.** Declare it inline, once, with a fixed set
+  of keys. The hook reads the codec map through a ref — a shape whose keys or
+  codecs change between renders is not re-decoded until the params next
+  change.
+- **Debounce text input.** In an embedded app each `setFilters` is a
+  cross-frame write. For a search box, keep the live input in local
+  `useState` and commit to `setFilters` on a debounce.
+
+### `urlParam` codecs
+
+Every base codec is *optional*: an absent key decodes to `undefined`, and
+encoding `undefined` clears the key. Chain `.withDefault(fallback)` to make it
+required — absent (or unparseable) decodes to `fallback`, and a value equal to
+`fallback` is kept out of the URL. Equality for `withDefault` compares dates by
+timestamp and arrays element-wise, so `withDefault([])` and
+`withDefault(new Date(...))` behave correctly. Types are in
+`dist/src/url_params.d.ts`.
+
+| Builder | Decoded type | URL form | Decode rules |
+| --- | --- | --- | --- |
+| `urlParam.string` | `string` | `?q=text` | Raw text as-is; an empty `?q=` decodes to `""` |
+| `urlParam.number` | `number` | `?page=2` | `Number(...)`; empty or non-finite input → absent |
+| `urlParam.boolean` | `boolean` | `?done=true` | Only the literals `true`/`false`; anything else → absent |
+| `urlParam.isoDate` | `Date` | `?from=2025-04-01` | Strictly `YYYY-MM-DD`; decodes to UTC midnight of that day |
+| `urlParam.enum([...])` | union of the literals | `?status=open` | A value not in the list → absent |
+| `urlParam.arrayOf(inner)` | `T[]` | `?tag=a&tag=b` (repeated key) | A single occurrence decodes to a 1-element array; elements the inner codec rejects are dropped |
+
+Behavior notes:
+
+- **Unparseable ≡ absent.** A malformed value (letters in a `number`, a bad
+  date, an unknown enum literal) decodes exactly like a missing key:
+  `undefined` for an optional codec, the fallback for a defaulted one. A
+  hand-mangled shared link degrades to defaults, never to a crash.
+- **Repeated keys on a scalar codec** take the first occurrence.
+- **`arrayOf`**: an empty array encodes to nothing — the key is omitted, so an
+  empty array and an absent key are indistinguishable (use
+  `.withDefault([])` and both decode to `[]`). The inner codec is any *base*
+  builder (`string`, `number`, `boolean`, `isoDate`, `enum([...])`).
+  **Limitation:** one level only — `arrayOf(arrayOf(...))` silently encodes to
+  nothing.
+- **`isoDate` is UTC calendar-date semantics.** It encodes the UTC date of the
+  `Date` instant and decodes to UTC midnight. Dates produced by the codec
+  round-trip exactly; a `Date` you construct at *local* midnight in a non-UTC
+  timezone can encode as the neighbouring day. Construct date-only values in
+  UTC, or reuse decoded values.
+
+### How `useUrlState` relates to routing
+
+`useUrlState` and `AppRouter` own different stores — keep each query key owned
+by exactly one mechanism, and read it only through its owner:
+
+- `useUrlState` keys live in the **host** address bar when embedded (written
+  over the bridge — the app cannot touch the cross-origin host URL itself) and
+  in the page URL when standalone. Read them via the hook, never via
+  react-router's `useSearchParams`.
+- Query params you put in a route target (`<Link to="/items?tab=recent">`)
+  live in the **router's** location. Read them via react-router. Embedded,
+  they are part of the screen mirrored under `_loc`, so they are shareable and
+  refresh-survivable too.
+
+**Warning — cross-screen persistence differs by mode.** Embedded,
+`useUrlState` keys sit in the host URL, and in-app navigation only merges the
+`_loc` mirror into it, leaving every other key alone — navigate away and back
+and the filters are still in the URL. Standalone, a
+react-router navigation rewrites the whole page URL (path *and* query), which
+drops `useUrlState` keys from the address bar. So treat `useUrlState` state as
+scoped to the screen the hook mounts on; state that must ride along a
+navigation in both modes belongs in the route itself (a path param, or query
+params on the `<Link>` target).
+
+## `useRecents` — recently-used items
+
+A small, most-recent-first list persisted across sessions — the "recently
+used" affordance a search box or picker shows when focused but empty (pair it
+with a combobox's recent-options slot; see the picker pattern in
+[data fetching](./data_fetching.md)). Exported from the main entry (signature:
+`dist/src/use_recents.d.ts`):
+
+```tsx
+const { recents, remember, forget, clear } = useRecents<Item>("item-picker", {
+  keyOf: (item) => item.id,
+  max: 8,
+});
+// on select:
+remember(item);
+```
+
+| Member | Behavior |
+| --- | --- |
+| `recents` | Remembered items, most-recent first, deduped, capped |
+| `remember(item)` | Records `item` as most-recent — moves an existing match (by `keyOf`) to the front, caps at `max`, persists. Call on select. |
+| `forget(item)` | Drops one item, matched by `keyOf` |
+| `clear()` | Empties the list |
+
+Options: `keyOf` (stable identity per item — used for dedupe and `forget`;
+default `JSON.stringify`) and `max` (default **5**).
+
+- **Storage**: `localStorage`, namespaced per `key` (two pickers on one page
+  keep separate lists), so it is per browser profile, per device, and per app
+  origin — never synced across devices or users. Passing a different `key` to
+  a mounted hook re-hydrates from the new namespace.
+- **Failure-tolerant by design**: if storage is unavailable (private mode,
+  quota) or holds corrupt JSON, the hook keeps working in-memory for the
+  session — only cross-reload persistence is lost. It never throws.
+- **Items round-trip through JSON.** Store plain serializable values; a `Date`
+  inside a remembered item comes back as a string after reload. For objects
+  you re-create per render, pass a `keyOf` that returns the item's id — the
+  default `JSON.stringify` identity treats any field change as a new item.
+- **Limitation — no cross-tab sync**: another tab's writes are not observed
+  live; a tab sees them only when a hook next mounts (or its `key` changes).
+  Concurrent tabs last-write-win.
+
+## Shipped symbols
+
+| Symbol | Entry | Signature |
+| --- | --- | --- |
+| `AppRouter` | `@lotics/app-sdk/router` | `dist/src/router.d.ts` |
+| `useUrlState`, `UrlStateShape`, `UrlStateValues` | `@lotics/app-sdk` | `dist/src/use_url_state.d.ts` |
+| `urlParam`, `UrlParamCodec`, `OptionalUrlParamCodec`, `UrlParams`, `UrlParamValue` | `@lotics/app-sdk` | `dist/src/url_params.d.ts` |
+| `useRecents`, `RecentsApi`, `RecentsOptions` | `@lotics/app-sdk` | `dist/src/use_recents.d.ts` |
+| `isEmbedded` | `@lotics/app-sdk` | `dist/src/rpc.d.ts` |