foldkit-site 0.7.0 → 0.9.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.
Files changed (2) hide show
  1. package/README.md +314 -10
  2. package/package.json +10 -10
package/README.md CHANGED
@@ -59,10 +59,69 @@ Peers: `effect`, `foldkit`. `foldkit-surface` is a dependency (for
59
59
 
60
60
  ## 60-second example
61
61
 
62
+ <!-- docs-check standalone define site-routes
63
+ import { Effect, Option, Schema, pipe } from 'effect'
64
+ import { defineMessageUnion } from 'foldkit/message'
65
+ import { UrlRequest } from 'foldkit/navigation'
66
+ import {
67
+ defineRouteUnion,
68
+ int,
69
+ literal,
70
+ mapTo,
71
+ oneOf,
72
+ parseUrlWithFallback,
73
+ query,
74
+ root,
75
+ slash,
76
+ } from 'foldkit/route'
77
+ import { Url } from 'foldkit/url'
78
+ import { Projection, Surface } from 'foldkit-surface'
79
+
80
+ const AppRoute = defineRouteUnion({
81
+ Home: {},
82
+ People: { searchText: Schema.Option(Schema.String) },
83
+ Person: { personId: Schema.Number },
84
+ Nested: {},
85
+ NotFound: { path: Schema.String },
86
+ })
87
+ type AppRoute = typeof AppRoute.Type
88
+ const homeRouter = pipe(root, mapTo(AppRoute.Home))
89
+ const peopleRouter = pipe(
90
+ literal('people'),
91
+ query(Schema.Struct({ searchText: Schema.OptionFromOptional(Schema.String) })),
92
+ mapTo(AppRoute.People),
93
+ )
94
+ const personRouter = pipe(literal('people'), slash(int('personId')), mapTo(AppRoute.Person))
95
+ const nestedRouter = pipe(literal('nested'), mapTo(AppRoute.Nested))
96
+ const urlToAppRoute = parseUrlWithFallback(
97
+ oneOf(personRouter, peopleRouter, homeRouter, nestedRouter),
98
+ AppRoute.NotFound,
99
+ )
100
+ const Model = Schema.Struct({ route: AppRoute, bios: Schema.Record(Schema.String, Schema.String) })
101
+ type Model = typeof Model.Type
102
+ const Message = defineMessageUnion({
103
+ ClickedLink: { request: UrlRequest },
104
+ ChangedUrl: { url: Url },
105
+ CompletedNavigation: {},
106
+ })
107
+ type Message = typeof Message.Type
108
+ const App = Surface.application({
109
+ Model,
110
+ Message,
111
+ initial: { route: AppRoute.Home(), bios: {} },
112
+ update: (model: Model) => ({ model }),
113
+ })
114
+ const PeoplePage = App.surface('PeoplePage', {
115
+ params: { searchText: Schema.Option(Schema.String) },
116
+ model: ({ model }) => Projection.struct({ route: model.route }),
117
+ })
118
+ -->
119
+
62
120
  ```ts
63
121
  import { Site } from 'foldkit-site'
64
122
 
65
123
  const Home = Site.route(homeRouter, AppRoute.Home, { title: () => 'Routing' })
124
+ const People = Site.route(peopleRouter, AppRoute.People)
66
125
  const Person = Site.route(personRouter, AppRoute.Person, {
67
126
  title: ({ personId }) => `Person ${personId} | Routing`,
68
127
  section: 'People',
@@ -96,6 +155,10 @@ exported value and use it for targets and hrefs. To annotate in steps, or to
96
155
  share an annotation bundle across nodes, build incrementally instead — the
97
156
  options are sugar over this builder:
98
157
 
158
+ <!-- docs-check standalone use site-routes
159
+ import { Site } from 'foldkit-site'
160
+ -->
161
+
99
162
  ```ts
100
163
  const Person = Site.node(personRouter, AppRoute.Person)
101
164
  .title(({ personId }) => `Person ${personId} | Routing`)
@@ -139,6 +202,12 @@ a node whose route has no params once, and a node with params by its
139
202
  `Site.paths(node, list)`, where `list` is an Effect giving each address's
140
203
  params and, for a sitemap, when it last changed:
141
204
 
205
+ <!-- docs-check
206
+ const Home = Site.route(homeRouter, AppRoute.Home)
207
+ const People = Site.route(peopleRouter, AppRoute.People)
208
+ const AppSite = Site.make(Home, Site.mount(People, [Person]))
209
+ -->
210
+
142
211
  ```ts
143
212
  const list = Site.paths(People, Effect.succeed([{ params: { searchText: Option.none() } }]))
144
213
  const people = Site.paths(
@@ -188,6 +257,17 @@ root first, a deeper node's field replacing its ancestor's, the preview
188
257
  title falling back to the node's `title`, and `noindex` for an unindexed
189
258
  route whatever its `meta` says. It is an SSR plan's `meta` as it stands:
190
259
 
260
+ <!-- docs-check standalone use site-routes
261
+ import { Site } from 'foldkit-site'
262
+ import { SSR } from 'foldkit-ssr'
263
+ const AppSite = Site.make(
264
+ Site.route(homeRouter, AppRoute.Home),
265
+ Site.mount(Site.route(peopleRouter, AppRoute.People), [
266
+ Site.route(personRouter, AppRoute.Person),
267
+ ]),
268
+ )
269
+ -->
270
+
191
271
  ```ts
192
272
  const Person = Site.node(personRouter, AppRoute.Person)
193
273
  .title(({ personId }) => `Person ${personId} | Routing`)
@@ -230,6 +310,10 @@ of guessing.
230
310
 
231
311
  **Attached Surfaces.** A node may name the Surface its route activates:
232
312
 
313
+ <!-- docs-check standalone use site-routes
314
+ import { Site } from 'foldkit-site'
315
+ -->
316
+
233
317
  ```ts
234
318
  const People = Site.route(peopleRouter, AppRoute.People, {
235
319
  surface: {
@@ -252,6 +336,31 @@ as well as by the route. Give the node's surface a `viewer`, a function of
252
336
  the Model that is `None` until the application knows who is signed in, and
253
337
  `params` receives what it gives:
254
338
 
339
+ <!-- docs-check standalone
340
+ import { Option, Schema, pipe } from 'effect'
341
+ import { defineMessageUnion } from 'foldkit/message'
342
+ import { defineRouteUnion, mapTo, root } from 'foldkit/route'
343
+ import { Entity } from 'foldkit-entity'
344
+ import { Remote, RemoteData } from 'foldkit-remote'
345
+ import { Site } from 'foldkit-site'
346
+ import { Projection, Surface } from 'foldkit-surface'
347
+
348
+ const AppRoute = defineRouteUnion({ Home: {} })
349
+ const homeRouter = pipe(root, mapTo(AppRoute.Home))
350
+ const Account = Entity.define('Account', Schema.Struct({ id: Schema.String, name: Schema.String }))
351
+ const Model = Schema.Struct({ route: AppRoute, remote: Remote.Model })
352
+ type Model = typeof Model.Type
353
+ const App = Surface.application({ Model, Message: defineMessageUnion({ ...Remote.messages }) })
354
+ const Data = Remote.make({ model: App.model.remote, entities: [Account] })
355
+ const Session = App.surface('Session', {
356
+ model: () => ({ me: Data.get(Entity.select(Account, { id: true }), 'me') }),
357
+ })
358
+ const HomeFeed = App.surface('HomeFeed', {
359
+ params: { ownerId: Schema.String },
360
+ model: ({ params }) => ({ ownerId: Projection.fromReader(Schema.String, () => params.ownerId) }),
361
+ })
362
+ -->
363
+
255
364
  ```ts
256
365
  const viewerOf = (model: Model): Option.Option<{ readonly id: string }> =>
257
366
  RemoteData.match(Surface.read(Session, model).me, {
@@ -287,24 +396,127 @@ needs it.
287
396
  what its route arrival tells it — so the fold and the drawing never restate
288
397
  the field, the wrapper, or the slot:
289
398
 
399
+ <!-- docs-check standalone define site-people
400
+ import { Option, Schema, pipe } from 'effect'
401
+ import { Submodel } from 'foldkit'
402
+ import type { HtmlBuilder } from 'foldkit/html'
403
+ import { defineMessageUnion } from 'foldkit/message'
404
+ import { UrlRequest } from 'foldkit/navigation'
405
+ import {
406
+ defineRouteUnion,
407
+ int,
408
+ literal,
409
+ mapTo,
410
+ oneOf,
411
+ parseUrlWithFallback,
412
+ query,
413
+ root,
414
+ slash,
415
+ } from 'foldkit/route'
416
+ import { modifyFields } from 'foldkit/struct'
417
+ import { Url } from 'foldkit/url'
418
+ import { Bundle, Link } from 'foldkit-bundle'
419
+ import { Site } from 'foldkit-site'
420
+ import { ModelRef, Surface } from 'foldkit-surface'
421
+
422
+ const AppRoute = defineRouteUnion({
423
+ Home: {},
424
+ People: { searchText: Schema.Option(Schema.String) },
425
+ Person: { personId: Schema.Number },
426
+ NotFound: { path: Schema.String },
427
+ })
428
+ type AppRoute = typeof AppRoute.Type
429
+ const homeRouter = pipe(root, mapTo(AppRoute.Home))
430
+ const peopleRouter = pipe(
431
+ literal('people'),
432
+ query(Schema.Struct({ searchText: Schema.OptionFromOptional(Schema.String) })),
433
+ mapTo(AppRoute.People),
434
+ )
435
+ const personRouter = pipe(literal('people'), slash(int('personId')), mapTo(AppRoute.Person))
436
+ const urlToAppRoute = parseUrlWithFallback(
437
+ oneOf(personRouter, peopleRouter, homeRouter),
438
+ AppRoute.NotFound,
439
+ )
440
+ const Home = Site.route(homeRouter, AppRoute.Home)
441
+ const People = Site.route(peopleRouter, AppRoute.People)
442
+ const Person = Site.route(personRouter, AppRoute.Person)
443
+ const AppSite = Site.make(Home, Site.mount(People, [Person]))
444
+
445
+ const PeopleModel = Schema.Struct({ searchInput: Schema.String, found: Schema.Array(Schema.String) })
446
+ type PeopleModel = typeof PeopleModel.Type
447
+ const PeopleMessage = defineMessageUnion({
448
+ ChangedRoute: { route: AppRoute.People },
449
+ Picked: { name: Schema.String },
450
+ })
451
+ type PeopleMessage = typeof PeopleMessage.Type
452
+ const PeopleBundle = Bundle.make('People', {
453
+ Model: PeopleModel,
454
+ Message: PeopleMessage,
455
+ args: Schema.Struct({ searchText: Schema.Option(Schema.String) }),
456
+ init: ({ searchText }) => ({
457
+ model: { searchInput: Option.getOrElse(searchText, () => ''), found: [] },
458
+ }),
459
+ update: (model, message) =>
460
+ PeopleMessage.match(message, {
461
+ ChangedRoute: ({ route }) => ({
462
+ model: { searchInput: Option.getOrElse(route.searchText, () => ''), found: [] },
463
+ }),
464
+ Picked: ({ name }) => ({ model: { ...model, found: [...model.found, name] } }),
465
+ }),
466
+ view: Submodel.defineView<PeopleModel, PeopleMessage>((model, h: HtmlBuilder<PeopleMessage>) =>
467
+ h.p([], [model.searchInput]),
468
+ ),
469
+ })
470
+ const Model = Schema.Struct({ route: AppRoute, peoplePage: PeopleModel })
471
+ type Model = typeof Model.Type
472
+ const Message = defineMessageUnion({
473
+ ClickedLink: { request: UrlRequest },
474
+ ChangedUrl: { url: Url },
475
+ CompletedNavigation: {},
476
+ GotPeopleMessage: { message: PeopleMessage },
477
+ })
478
+ type Message = typeof Message.Type
479
+ const App = Surface.application({ Model, Message })
480
+ const updateOwn = (model: Model, _message: Message) => ({ model })
481
+ -->
482
+
290
483
  ```ts
291
484
  const PeoplePage = Site.placement(People, PeopleBundle, {
292
485
  link: Link.field<Model>()('peoplePage', Link.wrapper(Message.GotPeopleMessage)),
293
486
  args: parent => ({
294
487
  searchText: parent.route._tag === 'People' ? parent.route.searchText : Option.none(),
295
488
  }),
296
- changed: route => People.Message.ChangedRoute({ route }),
489
+ changed: route => PeopleMessage.ChangedRoute({ route }),
297
490
  })
298
-
299
- const assembly = Bundle.assemble([PeoplePage.placed, Routing])
300
- const update = assembly.update((model, message) =>
301
- Routing.reduces(message) || message._tag === 'GotPeopleMessage' ? { model } : updateOwn(model, message),
302
- )
303
491
  ```
304
492
 
493
+ <!-- docs-check
494
+ const Routing = Site.routing<Model, Message, AppRoute>({
495
+ site: AppSite,
496
+ owner: App.owner,
497
+ route: {
498
+ dependency: ModelRef.focus(App.model.route).dependency,
499
+ get: model => model.route,
500
+ set: (model, route) => modifyFields(model, { route: () => route }),
501
+ },
502
+ parse: urlToAppRoute,
503
+ tags: { clicked: 'ClickedLink', changed: 'ChangedUrl' },
504
+ completed: Message.CompletedNavigation,
505
+ pages: [PeoplePage],
506
+ })
507
+ -->
508
+
305
509
  `placed.update` folds the child's Messages (route it in `update` through the
306
510
  assembly; the wrapper tag never reaches your own branches) and `placed.view`
307
- draws it. `changed` receives the node's own case value when its route
511
+ draws it:
512
+
513
+ ```ts
514
+ const assembly = Bundle.assemble<Model, Message>()([PeoplePage.placed, Routing])
515
+ const update = assembly.update((model, message) =>
516
+ Routing.reduces(message) ? { model } : updateOwn(model, message),
517
+ )
518
+ ```
519
+ `changed` receives the node's own case value when its route
308
520
  arrives and returns the child's Message — or nothing when the arrival needs
309
521
  no answer. Pass the pages to `Site.routing` (`pages: [PeoplePage]`) and the
310
522
  wiring informs each page whose route arrives, after setting the route field.
@@ -319,6 +531,17 @@ With service-needing pages, name the services on both calls:
319
531
  `Site.routing` is the application's link-click and URL-change lifecycle as
320
532
  one wiring, so `update` stops hand-writing those two branches:
321
533
 
534
+ <!-- docs-check standalone use site-people
535
+ const PeoplePage = Site.placement(People, PeopleBundle, {
536
+ link: Link.field<Model>()('peoplePage', Link.wrapper(Message.GotPeopleMessage)),
537
+ args: parent => ({
538
+ searchText: parent.route._tag === 'People' ? parent.route.searchText : Option.none(),
539
+ }),
540
+ changed: route => PeopleMessage.ChangedRoute({ route }),
541
+ })
542
+ const pages = [PeoplePage]
543
+ -->
544
+
322
545
  ```ts
323
546
  import { modifyFields } from 'foldkit/struct'
324
547
  import { ModelRef } from 'foldkit-surface'
@@ -336,7 +559,7 @@ const Routing = Site.routing<Model, Message, AppRoute>({
336
559
  completed: Message.CompletedNavigation,
337
560
  })
338
561
 
339
- const assembly = Bundle.assemble([Routing, ...pages])
562
+ const assembly = Bundle.assemble<Model, Message>()([Routing, ...pages.map(page => page.placed)])
340
563
  const update = assembly.update((model, message) =>
341
564
  Routing.reduces(message) ? { model } : updateOwn(model, message),
342
565
  )
@@ -360,7 +583,7 @@ before its route is set: `'history'` when the browser's `popstate` brought it
360
583
  is no navigation, and tells nothing. Remote uses it to show a list the reader
361
584
  just left as it was on the way back, rather than refetching it:
362
585
 
363
- ```ts
586
+ ```ts sketch
364
587
  const Navigating = Site.routing<Model, Message, AppRoute, RemoteClient>({
365
588
  // ...site, route, parse, tags and completed, as above
366
589
  navigated: (model, kind) => Data.reduce(model, { _tag: 'Navigated', kind }),
@@ -397,6 +620,30 @@ page. `access` on a node says who may be shown it and the nodes below it,
397
620
  from what the application knows of the reader (its `Me` row), and where
398
621
  anyone else goes (from `access.test.ts`):
399
622
 
623
+ <!-- docs-check standalone
624
+ import { Option, Schema, pipe } from 'effect'
625
+ import { defineRouteUnion, literal, mapTo, query } from 'foldkit/route'
626
+ import { Site } from 'foldkit-site'
627
+
628
+ const AppRoute = defineRouteUnion({
629
+ Home: {},
630
+ SignIn: { returnTo: Schema.Option(Schema.String) },
631
+ Projects: {},
632
+ })
633
+ interface Me {
634
+ readonly signedIn: boolean
635
+ }
636
+ const SignIn = Site.route(
637
+ pipe(
638
+ literal('sign-in'),
639
+ query(Schema.Struct({ returnTo: Schema.OptionFromOptional(Schema.String) })),
640
+ mapTo(AppRoute.SignIn),
641
+ ),
642
+ AppRoute.SignIn,
643
+ )
644
+ const toSignIn = (requested: string) => Site.target(SignIn, { returnTo: Option.some(requested) })
645
+ -->
646
+
400
647
  ```ts
401
648
  const Projects = Site.node(pipe(literal('projects'), mapTo(AppRoute.Projects)), AppRoute.Projects)
402
649
  .access<Me>({ allow: me => me.signedIn, otherwise: toSignIn })
@@ -422,11 +669,68 @@ is those as Sources — `Data.satisfy` over them, with the route set to the
422
669
  target's, prepares the Model before a synchronous render. Preparation stays
423
670
  caller-composed — there is no `prepare` in any plan.
424
671
 
672
+ **A data policy per route.** A node carries no data policy of its own: how
673
+ long a page's reads stay fresh is the Remote domain's `policy`, and
674
+ `Data.wiring` takes it as a function of the Model. Match the route there, with
675
+ the route union's own `match`, so a route added later is a type error until its
676
+ policy is chosen (from Chirp, which reads a profile again sooner than the
677
+ timeline):
678
+
679
+ <!-- docs-check standalone
680
+ import { Schema, pipe } from 'effect'
681
+ import { defineMessageUnion } from 'foldkit/message'
682
+ import { defineRouteUnion, literal, mapTo, root, slash, string } from 'foldkit/route'
683
+ import { Remote, RemotePolicy } from 'foldkit-remote'
684
+ import { Site } from 'foldkit-site'
685
+ import { Surface } from 'foldkit-surface'
686
+
687
+ const AppRoute = defineRouteUnion({ Home: {}, Profile: { handle: Schema.String } })
688
+ const Model = Schema.Struct({ route: AppRoute, remote: Remote.Model })
689
+ type Model = typeof Model.Type
690
+ const App = Surface.application({ Model, Message: defineMessageUnion({ ...Remote.messages }) })
691
+ const Data = Remote.make({ model: App.model.remote, entities: [] })
692
+ const Home = App.surface('Home', { model: () => ({}) })
693
+ const Profile = App.surface('Profile', {
694
+ params: { handle: Schema.String },
695
+ model: () => ({}),
696
+ })
697
+ const AppSite = Site.make(
698
+ Site.route(pipe(root, mapTo(AppRoute.Home)), AppRoute.Home, {
699
+ surface: { surface: Home, params: () => undefined },
700
+ }),
701
+ Site.route(pipe(literal('people'), slash(string('handle')), mapTo(AppRoute.Profile)), AppRoute.Profile, {
702
+ surface: { surface: Profile, params: ({ handle }) => ({ handle }) },
703
+ }),
704
+ )
705
+ -->
706
+
707
+ ```ts
708
+ const timeline = RemotePolicy.staleWhileRevalidate({ maxAge: 60_000 })
709
+ const profile = RemotePolicy.staleWhileRevalidate({ maxAge: 15_000 })
710
+
711
+ const wiring = Data.wiring(Site.sources(AppSite, App.owner, App.model.route), {
712
+ policy: (model: Model) =>
713
+ AppRoute.match(model.route, {
714
+ Home: () => timeline,
715
+ Profile: () => profile,
716
+ }),
717
+ })
718
+ ```
719
+
720
+ The Surfaces come from the tree (`Site.sources`), each answering its own
721
+ route, and the policy is the one the Model's route picks, so the two vary
722
+ together without either naming the other. Nothing here fetches: `Data.wiring`
723
+ reads the policy when it plans a read. The limit is that one policy covers
724
+ every Surface active on a route; two policies on one route would need a
725
+ Surface-level option the Remote domain does not have. Retention stays the
726
+ store's: a node has no `retain`. See `examples/chirp/src/app.ts` (`policy`)
727
+ and `examples/chirp/test/site.test.ts` for the same wiring checked per route.
728
+
425
729
  **Reading a page ahead on intent.** Give `Site.routing` a `preload`, and a
426
730
  link the reader means to follow is read before they follow it, so its page
427
731
  draws at once:
428
732
 
429
- ```ts
733
+ ```ts sketch
430
734
  import { pointedLinks } from 'foldkit-primitives/dom'
431
735
 
432
736
  const Routing = Site.routing<Model, Message, AppRoute, RemoteClient>({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-site",
3
- "version": "0.7.0",
3
+ "version": "0.9.0",
4
4
  "description": "The deployed route topology of a Foldkit application: stable route nodes, their hierarchy, typed targets, and per-node metadata, compiled to the Foldkit Router, Surface, and Bundle primitives the runtime already runs.",
5
5
  "keywords": [
6
6
  "foldkit",
@@ -38,9 +38,9 @@
38
38
  "LICENSE"
39
39
  ],
40
40
  "dependencies": {
41
- "foldkit-bundle": "0.11.0",
42
- "foldkit-ssr": "0.11.0",
43
- "foldkit-surface": "0.13.0"
41
+ "foldkit-ssr": "0.12.0",
42
+ "foldkit-surface": "0.14.0",
43
+ "foldkit-bundle": "0.13.0"
44
44
  },
45
45
  "peerDependencies": {
46
46
  "effect": "^4.1.0",
@@ -51,12 +51,12 @@
51
51
  "foldkit": "0.170.0",
52
52
  "tsdown": "^0.23.1",
53
53
  "typescript": "7.0.2",
54
- "foldkit-entity": "0.16.0",
55
- "foldkit-bundle": "0.11.0",
56
- "foldkit-ssr": "0.11.0",
57
- "foldkit-primitives": "0.18.0",
58
- "foldkit-surface": "0.13.0",
59
- "foldkit-remote": "0.24.0"
54
+ "foldkit-bundle": "0.13.0",
55
+ "foldkit-entity": "0.17.0",
56
+ "foldkit-primitives": "0.20.0",
57
+ "foldkit-remote": "0.26.0",
58
+ "foldkit-ssr": "0.12.0",
59
+ "foldkit-surface": "0.14.0"
60
60
  },
61
61
  "scripts": {
62
62
  "build": "node ../../scripts/declarations.mjs . && tsdown && node ../../scripts/declared-any.mjs .",