foldkit-site 0.0.0-stage → 0.1.0

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.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Patrick Glenn
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,287 @@
1
- # Temporary Holding Version
1
+ # `foldkit-site`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The deployed route topology of a Foldkit application: which locations exist,
4
+ how they nest, what each is called, and what it activates — as data that
5
+ compiles down to the primitives the runtime already runs.
6
+
7
+ ## What this package is
8
+
9
+ Every application with more than one screen answers the same questions: what
10
+ places exist, which place are we on, how do places link to each other, and
11
+ what does each place show. Foldkit's Router already answers the URL half with
12
+ bidirectional parsers. `foldkit-site` answers the structural half: a tree of
13
+ stable route nodes over those parsers, with one annotated place for the
14
+ metadata (titles, sections, history intent) that applications otherwise
15
+ recompute in four parallel tables.
16
+
17
+ ## When it owns the problem
18
+
19
+ `foldkit-site` owns **where the application is**, and nothing else:
20
+
21
+ ```text
22
+ Site "What location are we at, and what is around it?"
23
+ Surface "What may this location observe, and which Messages may it cause?"
24
+ Remote "What server facts do those observations require?"
25
+ ```
26
+
27
+ It owns no Model, runs no Effects, dispatches no Messages, and fetches
28
+ nothing. A node lowers to an ordinary Foldkit Router (which it is built
29
+ from), an ordinary `Surface.when` (through `Site.sources`), and — in a later
30
+ cut — an ordinary Bundle placement. If a feature would need the Site to
31
+ become another store, async runtime, or cache, it does not belong here.
32
+
33
+ ## The mental model
34
+
35
+ ```text
36
+ Foldkit Router (per node) URL <-> typed route value
37
+ +
38
+ Site tree route value -> chain, metadata, Surfaces
39
+ +
40
+ Surface / Remote / SSR the existing consumers of those answers
41
+ ```
42
+
43
+ A node is a stable first-class value: mounting it in a tree never mutates
44
+ it, so the same node builds targets, hrefs, and inspection wherever it is
45
+ mounted. A target is one typed destination — node, route value, and URL from
46
+ one declaration — so a link can never point where the parser would not go.
47
+
48
+ ## Install
49
+
50
+ ```sh
51
+ pnpm add foldkit-site
52
+ ```
53
+
54
+ Peers: `effect`, `foldkit`. `foldkit-surface` is a dependency (for
55
+ `Site.sources`).
56
+
57
+ ## 60-second example
58
+
59
+ ```ts
60
+ import { Site } from 'foldkit-site'
61
+
62
+ const Home = Site.route(homeRouter, AppRoute.Home, { title: () => 'Routing' })
63
+ const Person = Site.route(personRouter, AppRoute.Person, {
64
+ title: ({ personId }) => `Person ${personId} | Routing`,
65
+ section: 'People',
66
+ })
67
+
68
+ const AppSite = Site.make(Home, Site.mount(People, []))
69
+
70
+ // One declaration builds the value and the address together.
71
+ const target = Site.target(Person, { personId: 3 })
72
+ target.route // AppRoute.Person({ personId: 3 })
73
+ target.url // '/people/3'
74
+
75
+ // And the tree answers structural questions off route values.
76
+ Site.chainOf(AppSite, target.route) // [People, Person]
77
+ Site.titleOf(AppSite, target.route) // 'Person 3 | Routing'
78
+ Site.sectionOf(AppSite, target.route) // 'People'
79
+ ```
80
+
81
+ `Site.route` takes an existing full Foldkit Router — `literal`, `slash`,
82
+ `query`, `mapTo`, all of it — and the route case it builds. The router stays
83
+ the whole URL story; the Site adds hierarchy, metadata, and inspection
84
+ without re-parsing anything.
85
+
86
+ ## Core concepts
87
+
88
+ **Nodes.** `Site.route(router, case, options?)` declares one location. Options
89
+ are `title` (a function of the route value), `section`, `landing` (the
90
+ section's nav address as this node's params), `shortcut` (the keys that go
91
+ here), `history`, and `surface` (below). The node is frozen; keep the
92
+ exported value and use it for targets and hrefs. To annotate in steps, or to
93
+ share an annotation bundle across nodes, build incrementally instead — the
94
+ options are sugar over this builder:
95
+
96
+ ```ts
97
+ const Person = Site.node(personRouter, AppRoute.Person)
98
+ .title(({ personId }) => `Person ${personId} | Routing`)
99
+ .section('People')
100
+ .node
101
+ ```
102
+
103
+ Methods — not pipeable fragments — because each stage of a pipe is a
104
+ separate generic call and could not infer the route. Read `.node` at any
105
+ stage: every step freezes, so intermediates are usable nodes too, never
106
+ drafts. Named bundles also compose through `.pipe` (Effect-style, one
107
+ bundle; chain for more) or free `pipe(builder, bundle)` — the bundle stays
108
+ generic over the builder it meets, so it instantiates with no annotation.
109
+
110
+ **Trees.** `Site.mount(node, children?)` mounts a node under children without
111
+ mutating it — children may be bare nodes or mounts. `Site.make(...roots)`
112
+ freezes the topology. Two nodes sharing a tag, or one node mounted twice,
113
+ throw at `make`: both would make chain inspection ambiguous.
114
+
115
+ **Targets.** `Site.target(node, params)` is `{ node, route, url }`.
116
+ `Site.href(target)` — or `Site.href(node, params)` — is its URL. Because the
117
+ URL is built by the node's own router, a round trip holds by construction: a
118
+ built URL parses back to the target's route (there is a test proving it).
119
+
120
+ **Inspection.** `Site.nodeOf(site, route)` and `Site.chainOf(site, route)`
121
+ resolve a route value to its node and its root-first chain (`[]` for a tag
122
+ the tree does not hold, as an inactive Surface resolves to nothing).
123
+ `Site.parentOf`, `Site.ancestorsOf`, `Site.depthOf`, and `Site.nodesOf`
124
+ (depth-first, parents before children) cover the rest.
125
+
126
+ **History.** `Site.historyOf(prev, next)` declares push-vs-replace once: to
127
+ another node — or from an unknown location, so Back can still return to it — a
128
+ step; within a node, its `history` rule (a string, or a function for nodes
129
+ where some param changes are entries of their own, such as another person,
130
+ and others are views of one entry, such as another search). This unifies the
131
+ mirror's per-key spelling with the routed code that used to spell the same
132
+ rule by hand.
133
+
134
+ **Navigation metadata.** Titles and sections read with `Site.titleOf` and
135
+ `Site.sectionOf`. `Site.landing(site, section)` is where the section's nav
136
+ item points: the first node of the section that declares a landing, as a
137
+ target. Shortcuts ride beside their destinations; key bindings stay
138
+ application-owned, derived with each name validated against the application's
139
+ union. Annotate once; derive nav, titles, shortcuts, and breadcrumbs from it.
140
+
141
+ ## Nested rendering
142
+
143
+ `Site.view(site, route, model, h)` draws the route: the deepest node's view,
144
+ wrapped by every ancestor's layout root-first. Declare them on nodes:
145
+
146
+ ```ts
147
+ const Section = Site.route(sectionRouter, AppRoute.Section, {
148
+ layout: {
149
+ render: (child, model, h) => h.div([], [sidebar(model, h), child]),
150
+ },
151
+ view: {
152
+ render: (model, h) => h.ul([], [...]),
153
+ },
154
+ })
155
+ ```
156
+
157
+ Ancestors contribute layouts only — never their views. A layout receives its
158
+ composed child explicitly: no Outlet, no context provider, no hidden route
159
+ state, no child router. Unknown tags and viewless leaves fail loudly instead
160
+ of guessing.
161
+
162
+ **Attached Surfaces.** A node may name the Surface its route activates:
163
+
164
+ ```ts
165
+ const People = Site.route(peopleRouter, AppRoute.People, {
166
+ surface: {
167
+ surface: PeoplePage,
168
+ params: route => ({ searchText: route.searchText }),
169
+ },
170
+ })
171
+ ```
172
+
173
+ `Site.sources(site, App.owner, App.model.route)` is each surfaced node as its
174
+ `Surface.when`, keyed by tag, for `Data.wiring`, `Data.subscriptions`,
175
+ `Data.satisfy`, or an SSR plan's `surfaces`. A surface from another
176
+ application is refused here. Each entry answers its own tag only: on a
177
+ person page the person surface is active and the people surface is not.
178
+ `Site.sourcesFor(site, owner, place, target.route)` is the same entries for
179
+ the target's chain only — the route-level Sources prefetch and SSR read. A
180
+ layout surface active for several tags is not yet expressible — that is a
181
+ `Surface.whenAny`-shaped extension, deliberately deferred until a real layout
182
+ needs it.
183
+
184
+ ## Routed pages
185
+
186
+ `Site.placement` states one routed page once — its link, what starts it, and
187
+ what its route arrival tells it — so the fold and the drawing never restate
188
+ the field, the wrapper, or the slot:
189
+
190
+ ```ts
191
+ const PeoplePage = Site.placement(People, PeopleBundle, {
192
+ link: Link.field<Model>()('peoplePage', Link.wrapper(Message.GotPeopleMessage)),
193
+ args: parent => ({
194
+ searchText: parent.route._tag === 'People' ? parent.route.searchText : Option.none(),
195
+ }),
196
+ changed: route => People.Message.ChangedRoute({ route }),
197
+ })
198
+
199
+ const assembly = Bundle.assemble([PeoplePage.placed, Routing])
200
+ const update = assembly.update((model, message) =>
201
+ Routing.reduces(message) || message._tag === 'GotPeopleMessage' ? { model } : updateOwn(model, message),
202
+ )
203
+ ```
204
+
205
+ `placed.update` folds the child's Messages (route it in `update` through the
206
+ assembly; the wrapper tag never reaches your own branches) and `placed.view`
207
+ draws it. `changed` receives the node's own case value when its route
208
+ arrives and returns the child's Message — or nothing when the arrival needs
209
+ no answer. Pass the pages to `Site.routing` (`pages: [PeoplePage]`) and the
210
+ wiring informs each page whose route arrives, after setting the route field.
211
+
212
+ Without `changed` a page is never informed. Bundles with OutMessages, and
213
+ children that are not Bundles, stay on `Bundle.at` and `Link.child` directly.
214
+ With service-needing pages, name the services on both calls:
215
+ `Site.routing<Model, Message, AppRoute, RemoteClient>`.
216
+
217
+ ## The lifecycle wiring
218
+
219
+ `Site.routing` is the application's link-click and URL-change lifecycle as
220
+ one wiring, so `update` stops hand-writing those two branches:
221
+
222
+ ```ts
223
+ import { modifyFields } from 'foldkit/struct'
224
+
225
+ const Routing = Site.routing<Model, Message, AppRoute>({
226
+ site: AppSite,
227
+ owner: App.owner,
228
+ route: {
229
+ dependency: App.model.route.dependency,
230
+ get: (model) => model.route,
231
+ set: (model, route) => modifyFields(model, { route: () => route }),
232
+ },
233
+ parse: urlToAppRoute,
234
+ tags: { clicked: 'ClickedLink', changed: 'ChangedUrl' },
235
+ completed: Message.CompletedNavigation,
236
+ })
237
+
238
+ const assembly = Bundle.assemble([Routing, ...pages])
239
+ const update = assembly.update((model, message) =>
240
+ Routing.reduces(message) ? { model } : updateOwn(model, message),
241
+ )
242
+ ```
243
+
244
+ A click on an internal link navigates — pushing or replacing per
245
+ `Site.historyOf`, computed from the current route, so entries stay entries.
246
+ An external link loads. A URL change sets the route field, or returns the
247
+ same Model when the address parses to the route already shown, so an echo of
248
+ our own write never re-renders or clears pending state. The application's own
249
+ update answers nothing for either message; `reduces` names them for its
250
+ guard, the way `Remote.reduces` does.
251
+
252
+ The wiring claims the click tag and shares the change tag with URL mirrors,
253
+ which read their slices first. `CompletedNavigation` is one completion for
254
+ the navigation commands — declare the variant, pass the constructor. Route
255
+ changes reach child pages through their own Messages only once routed
256
+ placements land; until then informing them stays hand-written.
257
+
258
+ ## Common workflows
259
+
260
+ **Navigation rendering.** Derive the nav from the tree instead of keeping
261
+ parallel tables: sections in tree order, hrefs from `Site.landing`, titles
262
+ from `Site.titleOf`, shortcuts from the annotated nodes, and the current
263
+ section by comparing tags.
264
+
265
+ **Route changes.** On a URL change, resolve the route value once, then
266
+ `Site.chainOf` for the active chain and `Site.historyOf` for the history
267
+ step — or hand both branches to `Site.routing` (with `pages` for the routed
268
+ placements) and keep only the guard in `update`. What each route *does* with
269
+ the change beyond informing its page is still the application's `update`.
270
+
271
+ **Prefetch and SSR.** `Site.target` plus `Site.chainOf` say which Surfaces a
272
+ destination will activate; `Site.sourcesFor(site, owner, place, target.route)`
273
+ is those as Sources — `Data.satisfy` over them, with the route set to the
274
+ target's, prepares the Model before a synchronous render. Preparation stays
275
+ caller-composed — there is no `prepare` in any plan.
276
+
277
+ ## Limits / when not to use it
278
+
279
+ - A single-screen application has one node; the tree buys nothing.
280
+ - Keyboard shortcuts are still hand-written per application.
281
+ - Bundles with OutMessages, and children that are not Bundles, stay on
282
+ `Bundle.at` and `Link.child`: `Site.placement` takes neither `onOut` nor a
283
+ non-Bundle child.
284
+ - A node's `history` function sees only its own route values; cross-node
285
+ rules more subtle than "another node is a step" do not exist yet.
286
+ - Locales are route params like any other when they arrive; themes are
287
+ preferences, not routes.