@owlmeans/client 0.1.18-rc.24 → 0.1.18-rc.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +227 -74
  2. package/agent-meta/manifest.json +2 -2
  3. package/agent-meta/skills/client/SKILL.md +1 -1
  4. package/package.json +12 -12
package/README.md CHANGED
@@ -1,116 +1,269 @@
1
1
  # @owlmeans/client
2
2
 
3
- Core React client framework providing hooks, context, navigation, and state management for OwlMeans frontends.
4
-
5
- ## Overview
6
-
7
- - React hooks for subscribing to state stores (`useStoreModel`, `useStoreList`) and async data (`useValue`)
8
- - `useNavigate()` — entrypoint-aware navigation that builds URLs and drives the router
9
- - `useContext()` — access the application's `ClientContext` from any React component
10
- - `useEntrypoint()` — the alias, params and path of the entrypoint that rendered the current screen
11
- - `useToggle()` — boolean state toggle hook
12
- - Used by every React frontend in the OwlMeans ecosystem
3
+ The platform-agnostic React client framework that [`@owlmeans/web-client`](../web-client) (browser)
4
+ and the native client are built on. It provides the client context factory, the `App`/`Router`
5
+ mounts, alias-free navigation, the screen hooks (`useEntrypoint`, `useStoreModel`, `useStoreList`,
6
+ `useValue`, `useToggle`), and the modal and debug services. A browser application normally builds
7
+ its context with `makeContext` from [`@owlmeans/web-panel`](../web-panel) and mounts it with
8
+ `renderApp` from `@owlmeans/web-client`. `@owlmeans/web-client` does not re-export the hooks
9
+ listed here. `web-panel` re-exports `useNavigate`, `useValue` and `useEntrypoint`, while
10
+ `useStoreModel` and `useStoreList` are available only from this package. A cross-platform package
11
+ imports everything from here. Server code never uses this package; its equivalent is
12
+ [`@owlmeans/server-context`](../server-context).
13
13
 
14
14
  ## Installation
15
15
 
16
16
  ```bash
17
- bun add @owlmeans/client@^0.1.18-rc.15
17
+ bun add @owlmeans/client@^0.1.18-rc.25
18
18
  ```
19
19
 
20
+ `react` and `@remix-run/router` are peer dependencies.
21
+
22
+ ## Concepts
23
+
24
+ - **Client context**: `makeClientContext(cfg)` builds on `@owlmeans/client-context` and adds the
25
+ default state resource, the config and plugin resources, the modal and debug services, the
26
+ rerender hook and `context.router()`. Platform factories (`web-client`, `web-panel`) compose it,
27
+ and an app's own `makeContext` composes theirs.
28
+ - **Screen**: a frontend entrypoint protocol (`route(alias, path, frontend(...))`) bound to a
29
+ component with `bindScreen(protocol, handler(Component))`. The router mounts only frontend
30
+ entrypoints, and each nests under its `parent`.
31
+ - **Routed component**: a `RoutedComponent` receives `{ alias, path, params, context }`, and
32
+ `useEntrypoint()` reads the same values anywhere below it.
33
+ - **Navigator**: `useNavigate()` addresses entrypoints, not URLs. The target entrypoint builds its
34
+ own `url(request)`, and the active router plugin performs the navigation.
35
+ - **Store hooks**: `useStoreModel` and `useStoreList` subscribe to a [`@owlmeans/state`](../state)
36
+ resource through `useSyncExternalStore`. `useValue` renders an async result.
37
+ - **Modal stack**: `context.modal().request(Body)` pushes a body onto a stack rendered by a surface
38
+ the app mounts once, and resolves when the body answers.
39
+
20
40
  ## Usage
21
41
 
22
- Subscribe to a state store record:
42
+ ### Declare screens, bind them, mount the app
23
43
 
24
- ```typescript
25
- import { useStoreModel, useStoreList } from '@owlmeans/client'
44
+ Screen protocols are declared in the shared `common` package and bound in the web app:
26
45
 
27
- function ProjectView({ projectId }: { projectId: string }) {
28
- const model = useStoreModel<ProjectState>(projectId, 'project-state')
29
- if (model.empty) return <Loading />
46
+ ```ts
47
+ // common: entrypoints.ts
48
+ import { openProtocol } from '@owlmeans/entrypoint'
49
+ import { DEFAULT_GUARD } from '@owlmeans/auth-common'
50
+ import { frontend, route } from '@owlmeans/route'
30
51
 
31
- return <div>{model.record.title}</div>
32
- }
52
+ const projectBase = openProtocol(route('app:project', '/project/:projectId', frontend()), { guards: DEFAULT_GUARD })
53
+
54
+ export const appScreens = {
55
+ project: {
56
+ base: projectBase,
57
+ dashboard: openProtocol(route('app:project:dashboard', '/dashboard', frontend({ parent: projectBase }))),
58
+ settings: openProtocol(route('app:project:settings', '/settings', frontend({ parent: projectBase }))),
59
+ },
60
+ } as const
33
61
  ```
34
62
 
35
- Subscribe to a live list:
63
+ ```tsx
64
+ // web: entrypoints.ts and main.tsx
65
+ import { bindAll, bindScreen, handler, renderApp } from '@owlmeans/web-client'
66
+
67
+ export const entrypoints = [
68
+ ...bindAll({ project: appProtocols.project }), // backend calls
69
+ bindScreen(appScreens.project.base, handler(ProjectLayout)),
70
+ bindScreen(appScreens.project.dashboard, handler(DashboardScreen)),
71
+ bindScreen(appScreens.project.settings, handler(SettingsScreen)),
72
+ ]
36
73
 
37
- ```typescript
38
- const open = useStoreList<ProjectState>({
39
- query: { status: ['draft', 'active'] },
40
- sort: [{ field: 'createdAt', order: 'desc' }],
41
- resource: 'project-state'
42
- })
74
+ const context = makeContext(config) // the app's single factory
75
+ context.registerEntrypoints(entrypoints)
76
+ renderApp(context, undefined, <ModalSurface />) // children render before the router
43
77
  ```
44
78
 
45
- Load async data:
79
+ Outside the browser (a native shell, a test harness) the platform-agnostic mount is
80
+ `<App context={context} />`. `noRouter` skips the router, and `provide` overrides how routes are
81
+ compiled.
46
82
 
47
- ```typescript
48
- import { useValue } from '@owlmeans/client'
83
+ ### A routed screen that loads, stores and renders
49
84
 
50
- function StoryList({ projectId }: { projectId: string }) {
51
- const stories = useValue(async () => {
52
- return await ctx.story().list({ projectId })
53
- }, [projectId])
85
+ ```tsx
86
+ import { useEntrypoint, useStoreModel, useValue } from '@owlmeans/client'
87
+ import type { RoutedComponent } from '@owlmeans/client'
54
88
 
55
- return stories ? <List items={stories.items} /> : <Loading />
56
- }
57
- ```
89
+ export const DashboardScreen: RoutedComponent = () => {
90
+ const context = useContext() // the app's typed wrapper
91
+ const { params } = useEntrypoint<{ projectId?: string }>()
92
+ const projectId = params.projectId
58
93
 
59
- Navigate to an entrypoint:
94
+ // Load once per id, write the answer into the store, render from the store.
95
+ useValue(async cancel => {
96
+ if (projectId == null) {
97
+ return null
98
+ }
99
+ const project = await context.entrypoint(appProtocols.project.get).call({ params: { id: projectId } })
100
+ if (cancel?.current !== true) {
101
+ await context.getStateResource(PROJECTS).save(project)
102
+ }
60
103
 
61
- ```typescript
62
- import { useNavigate } from '@owlmeans/client'
104
+ return project
105
+ }, [projectId])
63
106
 
64
- function CreateButton() {
65
- const navigate = useNavigate()
66
- return <button onClick={() => navigate.go('project-create')}>Create</button>
107
+ const project = useStoreModel<Project>(projectId, PROJECTS)
108
+ if (project.empty) {
109
+ return <Spinner />
110
+ }
111
+
112
+ return <ProjectBoard project={project.record} onRename={title => project.update({ title })} />
67
113
  }
68
114
  ```
69
115
 
70
- ## API
71
-
72
- ### `useStoreModel<T>(id?, alias?): StateModel<T>`
116
+ The app's `useContext` is typically `() => useBasicContext<Config, Context>()` over the one exported
117
+ here (or re-exported by `web-panel`), so app-level accessors are typed.
73
118
 
74
- One record from a state resource, live. An id the store knows nothing about yields a model whose
75
- `empty` is true — `record` gives the resource's configured default and nothing is written on the
76
- way — so the hook never throws for missing data. Passing no id addresses the one record of a
77
- `single` resource; on any other that is a configuration error and throws.
119
+ ### Navigate by protocol
78
120
 
79
- ### `useStoreList<T>(opts?): StateModel<T>[]`
80
-
81
- A live list from a state resource: every record `opts.query` accepts, re-evaluated on every write
82
- that changes the answer. `opts` takes `query` (a `Criteria<T>`; omitted matches everything), `sort`
83
- and `resource` (the context's default state resource when omitted).
84
-
85
- ### `useValue<T>(loader, deps?, forceDefault?): T | null`
121
+ ```tsx
122
+ import { useNavigate } from '@owlmeans/client'
86
123
 
87
- Async data loader hook. Re-runs when `deps` change. Returns `null` while loading.
124
+ export const ProjectTabs: FC<{ projectId: string }> = ({ projectId }) => {
125
+ const nav = useNavigate()
88
126
 
89
- ### `useNavigate(): Navigator`
127
+ return <nav>
128
+ <button onClick={nav.press(appScreens.project.dashboard, { params: { projectId } })}>Dashboard</button>
129
+ <button onClick={nav.press(appScreens.project.settings, { params: { projectId }, query: { tab: 'members' } })}>
130
+ Members
131
+ </button>
132
+ <button onClick={nav.pressBack()}>Back</button>
133
+ </nav>
134
+ }
90
135
 
91
- Returns a navigator with:
92
- - `navigate(entrypoint, request?)` — navigate to a bound protocol, addressed by its `url()`
93
- - `go(alias, request?)` — navigate by entrypoint alias
94
- - `press(alias, request?)` / `pressBack()` — the same as event handlers
95
- - `back()` / `location()`
136
+ // imperatively, replacing the history entry
137
+ await nav.go(appScreens.project.dashboard, { params: { projectId }, replace: true })
138
+ ```
96
139
 
97
- ### `useContext<T>(): T`
140
+ A URL that resolves to another service (`http…`) is assigned to `location.href` instead of being
141
+ pushed onto the history.
98
142
 
99
- Returns the current `ClientContext` cast to `T`.
143
+ ### A modal request
100
144
 
101
- ### `useEntrypoint<T>(): EntrypointContextParams<T>`
145
+ ```tsx
146
+ import type { ModalBodyProps } from '@owlmeans/client'
147
+ import { createElement } from 'react'
102
148
 
103
- The `alias`, `params`, `path` and `context` of the entrypoint that rendered the current screen.
149
+ const ConfirmDelete: FC<ModalBodyProps & { storyId: string }> = ({ modal, storyId }) =>
150
+ <Dialog.Body>
151
+ <Button onClick={() => modal?.response(true)}>Delete {storyId}</Button>
152
+ <Button onClick={() => modal?.cancel()}>Cancel</Button>
153
+ </Dialog.Body>
104
154
 
105
- ### `useToggle(initial?): [boolean, () => void]`
155
+ const onDelete = async () => {
156
+ const confirmed = await context.modal().request<boolean>(
157
+ ({ modal }) => createElement(ConfirmDelete, { modal, storyId })
158
+ )
159
+ if (confirmed === true) { // null when cancelled
160
+ await context.entrypoint(appProtocols.story.delete).call({ params: { id: storyId } })
161
+ }
162
+ }
163
+ ```
106
164
 
107
- Simple boolean toggle hook.
165
+ The surface is mounted once. It calls `useSetupModalNavigator()`, links a `useToggle()` to
166
+ `context.modal().link(toggle)` after `waitForInitialized()`, and renders
167
+ `context.modal().layer()?.Com` with `modal={context.modal()}`.
108
168
 
109
- ## Related Packages
169
+ ## API
110
170
 
111
- - [`@owlmeans/state`](../state) — `StateModel`, `StateResource` used by `useStoreModel`
112
- - [`@owlmeans/client-entrypoint`](../client-entrypoint) — protocol bindings used by `useNavigate`
113
- - [`@owlmeans/client-context`](../client-context) — `ClientContext` returned by `useContext`
171
+ ### Context and mounting
172
+
173
+ | Symbol | Kind | Purpose |
174
+ |---|---|---|
175
+ | `makeClientContext<C, T>(cfg)` | function | Build the React client context (state, config/plugin resources, modal, debug, router accessor) |
176
+ | `ClientContext<C>` | type | Adds `router()`, `registerRerenderer(fn)`, `rerender()`, `modal()`, `debug()`, `getStateResource` |
177
+ | `App` / `AppProps` | component / type | Provide the context and, unless `noRouter`, mount the router; `children` render first |
178
+ | `Context`, `ClientContextContainer` | React context | The provider and the container behind it |
179
+ | `useContext<C, T>()` | hook | Read the current client context |
180
+ | `Router` / `RouterProps` | component / type | Resolve frontend entrypoints into routes; `provide` is optional |
181
+ | `makeRouterModel()`, `RouterModel`, `RouterProvider` | function / type | The route model and the router-provider signature |
182
+ | `handler(Component, preprender?)` | function | Wrap a component as an entrypoint handler for `bindScreen` |
183
+
184
+ ### Screens and navigation
185
+
186
+ | Symbol | Kind | Purpose |
187
+ |---|---|---|
188
+ | `RoutedComponent<Extra>` | type | A component bound to a frontend protocol |
189
+ | `EntrypointContextParams<T>` | type | `{ alias, params, path, context }` |
190
+ | `useEntrypoint<T>()` | hook | The params of the screen currently rendering |
191
+ | `useNavigate()` | hook | The `Navigator` |
192
+ | `Navigator` | type | `navigate(entrypoint, req?)`, `go(target, req?)`, `press(target, req?)`, `back()`, `pressBack()`, `location()` |
193
+ | `NavRequest<T>` | type | A partial `AbstractRequest` plus `replace` and `silent` |
194
+ | `EntrypointTarget` | type | `EntrypointReference \| string`; application code passes protocol objects |
195
+
196
+ ### State and values
197
+
198
+ | Symbol | Kind | Purpose |
199
+ |---|---|---|
200
+ | `useStoreModel<T>(id?, alias?)` | hook | One record from a state resource, live; never throws for missing data |
201
+ | `useStoreList<T>(opts?)` | hook | A live query `{ query?, sort?, resource? }` returning `StateModel<T>[]` |
202
+ | `UseStoreListOptions<T>` | type | The `useStoreList` options |
203
+ | `useValue<T>(loader, deps?, forceDefault?)` | hook | Render an async result; `null` (or the default) until it resolves |
204
+ | `UseValueParams<T>` | type | `{ default?, deps? }` |
205
+ | `useToggle(opened?)`, `Toggleable` | hook / type | `{ opened, open, close, set, toggle }` |
206
+
207
+ ### Modal and debug services
208
+
209
+ | Symbol | Kind | Purpose |
210
+ |---|---|---|
211
+ | `appendModalService(ctx, alias?)`, `createModalService(alias?)` | function | Register or create the modal stack (`context.modal()`) |
212
+ | `ModalService`, `ModalStackLayer`, `ModalBodyProps`, `ModalServiceAppend` | type | `request`, `response`, `cancel`, `error`, `layer`, `link`, `stack`, `toggle` |
213
+ | `useSetupModalNavigator()` | hook | Give modal bodies a navigator; call once in the surface |
214
+ | `appendDebugService(ctx, alias?)`, `createDebugService(alias?)` | function | The debug menu, registered only when `cfg.debug.all` or `cfg.debug.debugger` is set |
215
+ | `appendStateDebug(ctx, alias)` | function | List a client resource under "Reset states" in the debug menu |
216
+ | `DebugService`, `DebugMenuItem`, `DebugServiceAppend`, `DebugConfigRecord` | type | Debug menu contracts; `context.debug()` may be `undefined` |
217
+
218
+ ### Errors and constants
219
+
220
+ | Symbol | Kind | Purpose |
221
+ |---|---|---|
222
+ | `ClientError`, `ComponentError`, `ComponentPropError`, `ComponentPropUndefined` | class | The client error family, registered with `ResilientError` |
223
+ | `DEF_MODAL_ALIAS`, `DEF_DEBUG_ALIAS` | const | `'modal'`, `'debug'` |
224
+ | `DEBUGGER_FLAG`, `DEBUG_CONFIG_KEY` | const | `'debugger'` |
225
+
226
+ ### Subpath `@owlmeans/client/utils`
227
+
228
+ | Symbol | Kind | Purpose |
229
+ |---|---|---|
230
+ | `buildEntrypointTree`, `visitEntrypointTree`, `EntrypointTreeVisitor` | function / type | Build and walk the frontend entrypoint tree |
231
+ | `initializeRouter(context)` | function | Initialize the router for a context |
232
+ | `createRouteRenderer`, `HandledRenderer` | function / type | Render one route with guards applied |
233
+ | `EntrypointContext` | React context | What `useEntrypoint` reads |
234
+
235
+ These are the pieces the router is assembled from. A package building its own routing surface
236
+ uses them; an application does not.
237
+
238
+ ## Common pitfalls
239
+
240
+ - **Building URLs or passing alias strings in components.** Navigate with protocol objects
241
+ (`nav.go(protocol, { params })`) and let the entrypoint build the URL.
242
+ - **Resolving route params in nested components.** Read `params` from the screen props or
243
+ `useEntrypoint()` and pass them down.
244
+ - **Reading `useValue`'s second argument as a default.** An array is the dependency list, and an
245
+ object uses `{ default, deps }`. A bare non-array value is the default and gives no deps.
246
+ - **Committing after unmount in a multi-await loader.** Check `cancel.current` before writing.
247
+ - **Assigning into `model.record`.** Nothing re-renders. Use `model.update({ ... })`.
248
+ - **Importing `useNavigate`, `useEntrypoint`, `useStoreModel`, `useStoreList` or `useValue` from
249
+ `@owlmeans/web-client`.** It does not re-export them; import them from this package.
250
+ - **Requesting a modal from inside another modal body.** Closing the child also pops the parent,
251
+ and the parent's request never resolves. Await the first request, then issue the next.
252
+ - **Mounting global overlays inside a route.** They are torn down on every navigation. Pass them
253
+ as `App`/`renderApp` children.
254
+ - **Assuming `context.debug()` exists.** It is `undefined` unless the debug flags are set.
255
+ - **A screen whose guards all fail.** The renderer throws `AuthorizationError('frontend-guard')`, so
256
+ bind a login flow for guarded screens.
257
+
258
+ ## Related packages
259
+
260
+ - [`@owlmeans/web-client`](../web-client): the browser layer (`renderApp`, `WebApp`, `makeContext`)
261
+ - [`@owlmeans/web-panel`](../web-panel): the shadcn UI context factory and navigation shell most web apps start from
262
+ - [`@owlmeans/state`](../state): the store `useStoreModel` / `useStoreList` read
263
+ - [`@owlmeans/client-entrypoint`](../client-entrypoint): `bind`, `bindAll`, `bindScreen`, typed `call`/`invoke`/`url`
264
+ - [`@owlmeans/client-context`](../client-context): the base client context and config
265
+ - [`@owlmeans/router`](../router): the router plugin `context.router()` resolves
266
+ - [`@owlmeans/route`](../route): `route()` and `frontend()` for screen declarations
114
267
 
115
268
  <!-- owlmeans:agent-guidance:start -->
116
269
  ## Agent guidance
@@ -120,7 +273,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
120
273
  your project's skill store (`.agents/skills/`):
121
274
 
122
275
  ```sh
123
- npx @owlmeans/agent-skills@^0.1.18-rc.20
276
+ npx @owlmeans/agent-skills@^0.1.18-rc.22
124
277
  ```
125
278
 
126
279
  The embedded files are version-matched to this package release. Do not edit them
package/agent-meta/manifest.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "schemaVersion": 2,
3
3
  "package": "@owlmeans/client",
4
- "version": "0.1.18-rc.24",
5
- "generatedAt": "2026-09-12T14:18:54.788Z",
4
+ "version": "0.1.18-rc.26",
5
+ "generatedAt": "2026-09-15T12:38:15.187Z",
6
6
  "canonicalRepo": "https://github.com/owlmeans/common",
7
7
  "entries": [
8
8
  {
package/agent-meta/skills/client/SKILL.md CHANGED
@@ -8,7 +8,7 @@ user-invocable: false
8
8
  # @owlmeans/client
9
9
 
10
10
  **Layer:** Client
11
- **Install:** `"@owlmeans/client": "^0.1.18-rc.24"` in `dependencies`
11
+ **Install:** `"@owlmeans/client": "^0.1.18-rc.26"` in `dependencies`
12
12
 
13
13
  The React substrate `@owlmeans/web-client` (browser) and the native equivalent are built on. A
14
14
  cross-platform package imports from here; an application normally imports from the platform
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@owlmeans/client",
3
- "version": "0.1.18-rc.24",
3
+ "version": "0.1.18-rc.26",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "scripts": {
@@ -28,17 +28,17 @@
28
28
  }
29
29
  },
30
30
  "dependencies": {
31
- "@owlmeans/auth": "^0.1.18-rc.17",
32
- "@owlmeans/client-context": "^0.1.18-rc.21",
33
- "@owlmeans/client-entrypoint": "^0.1.18-rc.21",
34
- "@owlmeans/client-resource": "^0.1.18-rc.21",
35
- "@owlmeans/config": "^0.1.18-rc.20",
36
- "@owlmeans/context": "^0.1.18-rc.16",
37
- "@owlmeans/error": "^0.1.18-rc.16",
38
- "@owlmeans/entrypoint": "^0.1.18-rc.19",
39
- "@owlmeans/resource": "^0.1.18-rc.17",
40
- "@owlmeans/router": "^0.1.18-rc.16",
41
- "@owlmeans/state": "^0.1.18-rc.18"
31
+ "@owlmeans/auth": "^0.1.18-rc.19",
32
+ "@owlmeans/client-context": "^0.1.18-rc.23",
33
+ "@owlmeans/client-entrypoint": "^0.1.18-rc.23",
34
+ "@owlmeans/client-resource": "^0.1.18-rc.23",
35
+ "@owlmeans/config": "^0.1.18-rc.22",
36
+ "@owlmeans/context": "^0.1.18-rc.18",
37
+ "@owlmeans/error": "^0.1.18-rc.18",
38
+ "@owlmeans/entrypoint": "^0.1.18-rc.21",
39
+ "@owlmeans/resource": "^0.1.18-rc.19",
40
+ "@owlmeans/router": "^0.1.18-rc.18",
41
+ "@owlmeans/state": "^0.1.18-rc.20"
42
42
  },
43
43
  "peerDependencies": {
44
44
  "@remix-run/router": "*",