create-foldkit-app 0.38.0 → 0.39.0

package/dist/templates/base/FOLDKIT.md

@@ -108,7 +108,9 @@ For DOM operations (focus, scroll, modals, scroll lock), Foldkit ships a `Dom` m
 
 ### File Organization
 
-The invariant: keep the runtime boot separate from the pure definitions. `src/entry.ts` calls `Runtime.makeApplication` and `Runtime.run`, and `index.html` references it. The definitions (Model, Messages, init, update, view, Commands) never call `Runtime.run`, so they stay importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+Keep the runtime boot separate from the pure definitions. `src/entry.ts` calls `Runtime.makeApplication`, then `Runtime.run` for a client-rendered app or `Runtime.hydrate` for an SSR or SSG app. A client-rendered app references that entry from `index.html`. An SSR or SSG app names it in `ssr.clientEntry` in `vite.config.ts`, imports CSS from it, and exports `renderDocument` from `src/entry.server.ts` to produce the complete document. Its source tree has no `index.html`.
+
+The definitions (Model, Messages, init, update, view, Commands) never call `Runtime.run` or `Runtime.hydrate`, so tests and server entries can import them without booting a browser runtime. Keep both calls out of `main.ts`.
 
 For a small app the definitions all fit in one `src/main.ts`. Split a unit into its own file when it has _both_ a distinct reason to change _and_ a name you'd give it unprompted: the pure domain core into `timer.ts` or `domain.ts`, the view into `view.ts` (or a `components/` directory), a Command's owned resource into its own module. Split on that revealed seam, not on line count alone. A file that has grown large is _evidence_ a seam has formed, so treat its size as a prompt to re-check for one. Two splits are forced: extract Messages to `message.ts` when Commands need the constructors (this breaks the cycle between `command.ts` and `main.ts`), and colocate Commands with the update that returns them. Exemplars: counter and stopwatch are a single `main.ts`; kanban splits `domain` / `command` / `message` / `model`; typing-game splits views by page.
 

package/dist/templates/examples/canvas-art/src/main.ts

@@ -159,7 +159,7 @@ export const update = (model: Model, message: Message) =>
 // SUBSCRIPTION
 
 export const subscriptions = Subscription.make<Model, Message>()(_entry => ({
-  frame: Subscription.animationFrame({
+  frame: Subscription.animationFrameEntry({
     isActive: model => model.isRunning,
     toMessage: deltaTime => Message.TickedFrame({ deltaTime }),
   }),

package/dist/templates/examples/charting/src/chartHost.ts

@@ -10,11 +10,10 @@ export const setChart = (hostId: string, chart: EChartsType): void => {
 export const getChart = (hostId: string): Option.Option<EChartsType> =>
   Option.fromNullishOr(chartsByHostId.get(hostId))
 
-export const removeChart = (hostId: string): void => {
-  const maybeChart = getChart(hostId)
+export const removeChart = (hostId: string, chart: EChartsType): void => {
+  chart.dispose()
 
-  if (Option.isSome(maybeChart)) {
-    maybeChart.value.dispose()
+  if (chartsByHostId.get(hostId) === chart) {
     chartsByHostId.delete(hostId)
   }
 }

package/dist/templates/examples/charting/src/entry.ts

@@ -4,7 +4,6 @@ import { registerEcharts } from './echarts'
 import { init } from './init'
 import { Message } from './message'
 import { Model } from './model'
-import { subscriptions } from './subscription'
 import { update } from './update'
 import { view } from './view/index'
 
@@ -15,7 +14,6 @@ const application = Runtime.makeApplication({
   init,
   update,
   view,
-  subscriptions,
   container: document.getElementById('root'),
   devTools: {
     Message,

package/dist/templates/examples/charting/src/view/chart.ts

@@ -1,5 +1,5 @@
 import * as echarts from 'echarts/core'
-import { Effect, Option, Schema } from 'effect'
+import { Effect, Option, Queue, Schema, Stream, pipe } from 'effect'
 import { Mount } from 'foldkit'
 import type { Html } from 'foldkit/html'
 import { HtmlBuilder } from 'foldkit/html'
@@ -13,49 +13,114 @@ import { formatInteger } from './format'
 
 export const CHART_HOST_ID = 'charting-chart'
 
-const mountChart = (element: Element, hostId: string) =>
-  Effect.gen(function* () {
-    if (!(element instanceof HTMLElement)) {
-      return Message.FailedMountChart({
-        reason: 'Chart host is not an HTMLElement.',
-      })
-    }
-
-    return yield* Effect.acquireRelease(
-      Effect.try({
-        try: () => {
-          const chart = echarts.init(element, undefined, {
-            renderer: 'canvas',
-          })
-          const resizeObserver = new ResizeObserver(() => chart.resize())
+type MountChartMessage =
+  | typeof Message.SucceededMountChart.Type
+  | typeof Message.FailedMountChart.Type
+  | typeof Message.ClickedChartDatum.Type
+
+const toChartMountError = (error: unknown): Error =>
+  error instanceof Error ? error : new Error(`Failed to mount chart: ${error}`)
+
+const ChartClickEvent = Schema.Struct({
+  data: Schema.OptionFromOptional(Schema.Struct({ id: Schema.String })),
+})
+
+const datumIdFromChartClickEvent = (event: unknown): Option.Option<string> =>
+  pipe(
+    event,
+    Schema.decodeUnknownOption(ChartClickEvent),
+    Option.flatMap(({ data }) => data),
+    Option.map(({ id }) => id),
+  )
+
+const observeChartResizeAndClickEvents = (
+  element: HTMLElement,
+  chart: ReturnType<typeof echarts.init>,
+  queue: Queue.Enqueue<MountChartMessage>,
+) =>
+  Effect.acquireRelease(
+    Effect.try({
+      try: () => {
+        const resizeObserver = new ResizeObserver(() => chart.resize())
+        const onWindowResize = () => chart.resize()
+        const onClick = (event: unknown) => {
+          const maybeDatumId = datumIdFromChartClickEvent(event)
+
+          if (Option.isSome(maybeDatumId)) {
+            Queue.offerUnsafe(
+              queue,
+              Message.ClickedChartDatum({ datumId: maybeDatumId.value }),
+            )
+          }
+        }
+
+        try {
           resizeObserver.observe(element)
-          const onWindowResize = () => chart.resize()
           window.addEventListener('resize', onWindowResize)
-          setChart(hostId, chart)
-          return { resizeObserver, onWindowResize }
-        },
-        catch: error =>
-          error instanceof Error
-            ? error
-            : new Error(`Failed to mount chart: ${error}`),
-      }),
-      ({ resizeObserver, onWindowResize }) =>
-        Effect.sync(() => {
-          resizeObserver.disconnect()
+          chart.on('click', onClick)
+          return { resizeObserver, onWindowResize, onClick }
+        } catch (error) {
+          chart.off('click', onClick)
           window.removeEventListener('resize', onWindowResize)
-          removeChart(hostId)
+          resizeObserver.disconnect()
+          throw error
+        }
+      },
+      catch: toChartMountError,
+    }),
+    ({ resizeObserver, onWindowResize, onClick }) =>
+      Effect.sync(() => {
+        chart.off('click', onClick)
+        window.removeEventListener('resize', onWindowResize)
+        resizeObserver.disconnect()
+      }),
+  )
+
+const mountChart = (element: Element, hostId: string) =>
+  Stream.callback<MountChartMessage>(queue =>
+    Effect.gen(function* () {
+      if (!(element instanceof HTMLElement)) {
+        Queue.offerUnsafe(
+          queue,
+          Message.FailedMountChart({
+            reason: 'Chart host is not an HTMLElement.',
+          }),
+        )
+        return yield* Effect.never
+      }
+
+      const chart = yield* Effect.acquireRelease(
+        Effect.try({
+          try: () => echarts.init(element, undefined, { renderer: 'canvas' }),
+          catch: toChartMountError,
         }),
-    ).pipe(
-      Effect.map(() => Message.SucceededMountChart({ hostId })),
+        chart => Effect.sync(() => removeChart(hostId, chart)),
+      )
+      setChart(hostId, chart)
+
+      yield* observeChartResizeAndClickEvents(element, chart, queue)
+
+      Queue.offerUnsafe(queue, Message.SucceededMountChart({ hostId }))
+      return yield* Effect.never
+    }).pipe(
       Effect.catch(error =>
-        Effect.succeed(Message.FailedMountChart({ reason: error.message })),
+        Effect.sync(() =>
+          Queue.offerUnsafe(
+            queue,
+            Message.FailedMountChart({ reason: error.message }),
+          ),
+        ),
       ),
-    )
-  })
+    ),
+  )
 
-export const MountChart = Mount.define('MountChart', {
+export const MountChart = Mount.defineStream('MountChart', {
   args: { hostId: Schema.String },
-  messages: [Message.SucceededMountChart, Message.FailedMountChart],
+  messages: [
+    Message.SucceededMountChart,
+    Message.FailedMountChart,
+    Message.ClickedChartDatum,
+  ],
   execute: ({ element, hostId }) => mountChart(element, hostId),
 })
 

package/dist/templates/examples/embedding/src/main.ts

@@ -79,10 +79,10 @@ export const update = (model: Model, message: Message) =>
 const TICK_INTERVAL = Duration.seconds(1)
 
 export const subscriptions = Subscription.make<Model, Message>()(_entry => ({
-  tick: Subscription.persistent(
-    Stream.tick(TICK_INTERVAL).pipe(Stream.map(Message.Ticked)),
+  tick: Subscription.persistentEntry(
+    Stream.tick(TICK_INTERVAL).pipe(Stream.drop(1), Stream.map(Message.Ticked)),
   ),
-  hostStep: Port.subscription(ports.inbound.stepChanged, step =>
+  hostStep: Port.subscriptionEntry(ports.inbound.stepChanged, step =>
     Message.ChangedStep({ step }),
   ),
 }))

package/dist/templates/examples/generative-art/src/subscription.ts

@@ -23,7 +23,7 @@ const noiseScaleSliderSubscriptions = Subscription.lift({
 })
 
 const frameSubscription = Subscription.make<Model, Message>()(_entry => ({
-  frame: Subscription.animationFrame({
+  frame: Subscription.animationFrameEntry({
     isActive: model => model.isRunning,
     toMessage: deltaTimeMs => Message.TickedFrame({ deltaTimeMs }),
   }),

package/dist/templates/examples/job-application/src/step/education/education.ts

@@ -54,9 +54,7 @@ export const GenerateEntryId = Command.define('GenerateEntryId', {
 
 // UPDATE
 
-const foldEntryOutMessage: (
-  entryId: string,
-) => (outMessage: Entry.OutMessage) => Update.Step<Model, Message> = entryId =>
+const foldEntryOutMessage = (entryId: string) =>
   Entry.OutMessage.match<Update.Step<Model, Message>>({
     Removed: () => model => ({
       model: modifyFields(model, {
@@ -65,18 +63,18 @@ const foldEntryOutMessage: (
     }),
   })
 
-const foldEntry = (entryId: string) =>
-  Update.foldChild({
-    update: Entry.update,
-    read: (model: Model) =>
-      Array.findFirst(model.entries, entry => entry.id === entryId),
-    write: (model, nextEntry) =>
-      modifyFields(model, {
-        entries: Array.map(entry => (entry.id === entryId ? nextEntry : entry)),
-      }),
-    toParentMessage: message => Message.GotEntryMessage({ entryId, message }),
-    foldOutMessage: foldEntryOutMessage(entryId),
-  })
+const foldEntry = Update.foldChildAt({
+  update: Entry.update,
+  readAt: (model: Model, entryId: string) =>
+    Array.findFirst(model.entries, entry => entry.id === entryId),
+  writeAt: (model, entryId, nextEntry) =>
+    modifyFields(model, {
+      entries: Array.map(entry => (entry.id === entryId ? nextEntry : entry)),
+    }),
+  toParentMessage: (entryId, message) =>
+    Message.GotEntryMessage({ entryId, message }),
+  foldOutMessage: foldEntryOutMessage,
+})
 
 export const update = (model: Model, message: Message) =>
   Message.match<Update.Return<Model, Message>>(message, {
@@ -97,7 +95,7 @@ export const update = (model: Model, message: Message) =>
     }),
 
     GotEntryMessage: ({ entryId, message }) =>
-      foldEntry(entryId)(model, message),
+      foldEntry(model, entryId, message),
   })
 
 // VALIDATION SUMMARY

package/dist/templates/examples/job-application/src/step/skills/skills.ts

@@ -51,9 +51,7 @@ export const GenerateEntryId = Command.define('GenerateEntryId', {
 
 // UPDATE
 
-const foldEntryOutMessage: (
-  entryId: string,
-) => (outMessage: Entry.OutMessage) => Update.Step<Model, Message> = entryId =>
+const foldEntryOutMessage = (entryId: string) =>
   Entry.OutMessage.match<Update.Step<Model, Message>>({
     Removed: () => model => ({
       model: modifyFields(model, {
@@ -62,18 +60,18 @@ const foldEntryOutMessage: (
     }),
   })
 
-const foldEntry = (entryId: string) =>
-  Update.foldChild({
-    update: Entry.update,
-    read: (model: Model) =>
-      Array.findFirst(model.entries, entry => entry.id === entryId),
-    write: (model, nextEntry) =>
-      modifyFields(model, {
-        entries: Array.map(entry => (entry.id === entryId ? nextEntry : entry)),
-      }),
-    toParentMessage: message => Message.GotEntryMessage({ entryId, message }),
-    foldOutMessage: foldEntryOutMessage(entryId),
-  })
+const foldEntry = Update.foldChildAt({
+  update: Entry.update,
+  readAt: (model: Model, entryId: string) =>
+    Array.findFirst(model.entries, entry => entry.id === entryId),
+  writeAt: (model, entryId, nextEntry) =>
+    modifyFields(model, {
+      entries: Array.map(entry => (entry.id === entryId ? nextEntry : entry)),
+    }),
+  toParentMessage: (entryId, message) =>
+    Message.GotEntryMessage({ entryId, message }),
+  foldOutMessage: foldEntryOutMessage,
+})
 
 export const update = (model: Model, message: Message) =>
   Message.match<Update.Return<Model, Message>>(message, {
@@ -94,7 +92,7 @@ export const update = (model: Model, message: Message) =>
     }),
 
     GotEntryMessage: ({ entryId, message }) =>
-      foldEntry(entryId)(model, message),
+      foldEntry(model, entryId, message),
   })
 
 // VALIDATION SUMMARY

package/dist/templates/examples/job-application/src/step/workHistory/workHistory.ts

@@ -54,9 +54,7 @@ export const GenerateEntryId = Command.define('GenerateEntryId', {
 
 // UPDATE
 
-const foldEntryOutMessage: (
-  entryId: string,
-) => (outMessage: Entry.OutMessage) => Update.Step<Model, Message> = entryId =>
+const foldEntryOutMessage = (entryId: string) =>
   Entry.OutMessage.match<Update.Step<Model, Message>>({
     Removed: () => model => ({
       model: modifyFields(model, {
@@ -65,18 +63,18 @@ const foldEntryOutMessage: (
     }),
   })
 
-const foldEntry = (entryId: string) =>
-  Update.foldChild({
-    update: Entry.update,
-    read: (model: Model) =>
-      Array.findFirst(model.entries, entry => entry.id === entryId),
-    write: (model, nextEntry) =>
-      modifyFields(model, {
-        entries: Array.map(entry => (entry.id === entryId ? nextEntry : entry)),
-      }),
-    toParentMessage: message => Message.GotEntryMessage({ entryId, message }),
-    foldOutMessage: foldEntryOutMessage(entryId),
-  })
+const foldEntry = Update.foldChildAt({
+  update: Entry.update,
+  readAt: (model: Model, entryId: string) =>
+    Array.findFirst(model.entries, entry => entry.id === entryId),
+  writeAt: (model, entryId, nextEntry) =>
+    modifyFields(model, {
+      entries: Array.map(entry => (entry.id === entryId ? nextEntry : entry)),
+    }),
+  toParentMessage: (entryId, message) =>
+    Message.GotEntryMessage({ entryId, message }),
+  foldOutMessage: foldEntryOutMessage,
+})
 
 export const update = (model: Model, message: Message) =>
   Message.match<Update.Return<Model, Message>>(message, {
@@ -97,7 +95,7 @@ export const update = (model: Model, message: Message) =>
     }),
 
     GotEntryMessage: ({ entryId, message }) =>
-      foldEntry(entryId)(model, message),
+      foldEntry(model, entryId, message),
   })
 
 // VALIDATION SUMMARY

package/dist/templates/examples/map/src/entry.ts

@@ -1,13 +1,12 @@
 import { Runtime } from 'foldkit'
 
-import { Message, Model, init, subscriptions, update, view } from './main'
+import { Message, Model, init, update, view } from './main'
 
 const application = Runtime.makeApplication({
   Model,
   init,
   update,
   view,
-  subscriptions,
   container: document.getElementById('root'),
   devTools: {
     Message,