@lotics/app-sdk 0.100.1 → 0.101.1

package/docs/navigation_and_state.md

@@ -1,13 +1,8 @@
 # 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.
+state persists across sessions: **`AppRouter`**, **`useUrlState`** + the
+**`urlParam`** codecs, **`useRecents`**, and **`useFolderPick`**.
 
 ## The two URL layers
 
@@ -24,14 +19,8 @@ Neither is server state — `useUrlState` values are *client* state that you fee
 into a query's *server* params (see [named-query params](./queries.md) and the
 [data-fetching hooks](./data_fetching.md) they drive).
 
-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 app-host 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).
+Both mechanisms expose one API embedded and standalone ([runtime](./runtime.md));
+the few differences are flagged below.
 
 ## `AppRouter` — in-app routing
 
@@ -57,12 +46,9 @@ export default function App() {
 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`
-  (`^7 || ^8` — the canonical package; the `react-router-dom` shim's tree also
-  satisfies it) is an **optional peer dependency** — an app that imports the
-  router entry must install it itself; nothing else in the SDK needs it.
+- **Its own entry.** `AppRouter` ships from `@lotics/app-sdk/router`
+  (signature: `dist/router.d.ts`), apart from the hooks; its
+  `react-router` peer is `^7 || ^8`.
 - **An address no route claims says so.** `AppRouter` appends a catch-all at
   every level of the tree, so such a path renders a not-found screen — a
   message naming the path and a link to the first route — instead of an empty
@@ -140,7 +126,7 @@ yourself; undeclared keys are already preserved automatically (see below).
 
 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`):
+main entry (signature: `dist/use_url_state.d.ts`):
 
 ```tsx
 import { urlParam, useUrlState } from "@lotics/app-sdk";
@@ -157,8 +143,6 @@ 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.
@@ -204,7 +188,7 @@ 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`.
+`dist/url_params.d.ts`.
 
 | Builder | Decoded type | URL form | Decode rules |
 | --- | --- | --- | --- |
@@ -264,7 +248,7 @@ 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`):
+`dist/use_recents.d.ts`):
 
 ```tsx
 const { recents, remember, forget, clear } = useRecents<Item>("item-picker", {
@@ -300,13 +284,20 @@ default `JSON.stringify`) and `max` (default **5**).
   live; a tab sees them only when a hook next mounts (or its `key` changes).
   Concurrent tabs last-write-win.
 
-## Shipped symbols
+## `useFolderPick` — the folder a viewer works inside
+
+A screen scoped to one row of another table — a project, a branch, a season —
+keeps which one the viewer works inside by its record id, per folder table:
+
+```tsx
+const { picked, pick } = useFolderPick(projectsTableId);
+// picked: undefined while it is read, null where none is picked, else the row's id
+pick("rec_…"); // or pick(null) to leave for the list of folders
+```
 
-| 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` |
-| `openApp` | `@lotics/app-sdk` | `dist/src/open_app.d.ts` |
+- **The host keeps it for the viewer**, so every app of theirs scoped to the
+  same table opens in the same folder — each app is served from its own origin,
+  and only the host sees them all. Standalone, the app's own origin keeps it.
+- **An id only.** Read the row itself for its name and picture, and drop the
+  pick (`pick(null)`) when that read finds no row: a folder deleted, or no
+  longer the viewer's to read.