create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/managed-resource-layer/src/main.ts

@@ -0,0 +1,309 @@
+import {
+  Context,
+  Crypto,
+  Effect,
+  Layer,
+  Match as M,
+  Number,
+  Option,
+  Schema as S,
+} from 'effect'
+import { Command, ManagedResource, Runtime } from 'foldkit'
+import { Document, Html, HtmlBuilder } from 'foldkit/html'
+import { defineMessageUnion } from 'foldkit/message'
+import { ts } from 'foldkit/schema'
+import { evo } from 'foldkit/struct'
+
+import { BrowserCrypto } from '@effect/platform-browser'
+import { Button } from '@foldkit/ui'
+
+// ENGINE
+
+interface ComputeEngine {
+  readonly engineId: string
+  readonly square: (value: number) => number
+}
+
+class ComputeEngineService extends Context.Service<
+  ComputeEngineService,
+  ComputeEngine
+>()('ComputeEngineService') {}
+
+const engineLayer: Layer.Layer<ComputeEngineService> = Layer.effect(
+  ComputeEngineService,
+  Effect.acquireRelease(
+    Effect.gen(function* () {
+      const crypto = yield* Crypto.Crypto
+      const id = yield* Effect.orDie(crypto.randomUUIDv4)
+      const engineId = `engine-${id.slice(0, 8)}`
+      return { engineId, square: (value: number) => value * value }
+    }).pipe(Effect.provide(BrowserCrypto.layer)),
+    ({ engineId }) => Effect.log(`Tore down ${engineId}`),
+  ),
+)
+
+const Engine = ManagedResource.tag<ComputeEngine>()('ComputeEngine')
+type EngineService = ManagedResource.ServiceOf<typeof Engine>
+
+// MODEL
+
+export const EngineOff = ts('EngineOff')
+export const EngineBooting = ts('EngineBooting')
+export const EngineReady = ts('EngineReady', { engineId: S.String })
+export const EngineFailed = ts('EngineFailed', { reason: S.String })
+
+const EngineState = S.Union([
+  EngineOff,
+  EngineBooting,
+  EngineReady,
+  EngineFailed,
+])
+type EngineState = typeof EngineState.Type
+
+export const Model = S.Struct({
+  engine: EngineState,
+  computeCount: S.Number,
+  maybeSquareResult: S.Option(S.Number),
+})
+export type Model = typeof Model.Type
+
+// MESSAGE
+
+export const Message = defineMessageUnion({
+  ClickedStartEngine: {},
+  ClickedStopEngine: {},
+  StartedEngine: { engineId: S.String },
+  StoppedEngine: {},
+  FailedStartEngine: { reason: S.String },
+  ClickedCompute: {},
+  CompletedCompute: { result: S.Number },
+  SkippedCompute: {},
+})
+
+export type Message = typeof Message.Type
+
+// COMMAND
+
+export const Compute = Command.define('Compute', {
+  args: { value: S.Number },
+  messages: [Message.CompletedCompute, Message.SkippedCompute],
+  execute: ({ value }) =>
+    Effect.gen(function* () {
+      const engine = yield* Engine.get
+      return Message.CompletedCompute({ result: engine.square(value) })
+    }).pipe(
+      Effect.catchTag('ResourceNotAvailable', () =>
+        Effect.succeed(Message.SkippedCompute()),
+      ),
+    ),
+})
+
+// UPDATE
+
+type UpdateReturn = readonly [
+  Model,
+  ReadonlyArray<Command.Command<Message, never, EngineService>>,
+]
+
+export const update = (model: Model, message: Message) =>
+  Message.match<UpdateReturn>(message, {
+    ClickedStartEngine: () => [
+      evo(model, { engine: () => EngineBooting() }),
+      [],
+    ],
+
+    ClickedStopEngine: () => [evo(model, { engine: () => EngineOff() }), []],
+
+    StartedEngine: ({ engineId }) => [
+      evo(model, { engine: () => EngineReady({ engineId }) }),
+      [],
+    ],
+
+    StoppedEngine: () => [model, []],
+
+    FailedStartEngine: ({ reason }) => [
+      evo(model, { engine: () => EngineFailed({ reason }) }),
+      [],
+    ],
+
+    ClickedCompute: () => {
+      const nextComputeCount = Number.increment(model.computeCount)
+      return [
+        evo(model, { computeCount: () => nextComputeCount }),
+        [Compute({ value: nextComputeCount })],
+      ]
+    },
+
+    CompletedCompute: ({ result }) => [
+      evo(model, { maybeSquareResult: () => Option.some(result) }),
+      [],
+    ],
+
+    SkippedCompute: () => [model, []],
+  })
+
+// INIT
+
+export const init: Runtime.ApplicationInit<Model, Message> = () => [
+  { engine: EngineOff(), computeCount: 0, maybeSquareResult: Option.none() },
+  [],
+]
+
+// MANAGED RESOURCE
+
+export const managedResources = ManagedResource.make<Model, Message>()(
+  entry => ({
+    engine: entry(S.Option(S.Null), {
+      resource: Engine,
+      modelToMaybeRequirements: model =>
+        M.value(model.engine).pipe(
+          M.tag('EngineBooting', 'EngineReady', () => Option.some(null)),
+          M.tag('EngineOff', 'EngineFailed', () => Option.none()),
+          M.exhaustive,
+        ),
+      acquire: () =>
+        Layer.build(engineLayer).pipe(
+          Effect.map(context => Context.get(context, ComputeEngineService)),
+        ),
+      release: () => Effect.void,
+      onAcquired: ({ engineId }) => Message.StartedEngine({ engineId }),
+      onReleased: () => Message.StoppedEngine(),
+      onAcquireError: error =>
+        Message.FailedStartEngine({ reason: String(error) }),
+    }),
+  }),
+)
+
+// VIEW
+
+const buttonClassName =
+  'px-6 py-3 font-semibold text-white transition-colors data-[disabled]:opacity-40 data-[disabled]:cursor-not-allowed'
+
+const primaryButton = (
+  label: string,
+  message: Message,
+  colorClassName: string,
+  isDisabled: boolean,
+  h: HtmlBuilder<Message>,
+): Html =>
+  Button.view(
+    {
+      onClick: message,
+      isDisabled,
+      toView: attributes =>
+        h.button(
+          [
+            ...attributes.button,
+            h.Class(`${buttonClassName} ${colorClassName}`),
+          ],
+          [label],
+        ),
+    },
+    h,
+  )
+
+const engineStatusView = (
+  engine: EngineState,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const status = M.value(engine).pipe(
+    M.tag('EngineOff', () => ({
+      colorClassName: 'text-gray-500',
+      text: 'Engine is off.',
+    })),
+    M.tag('EngineBooting', () => ({
+      colorClassName: 'text-amber-600',
+      text: 'Booting engine...',
+    })),
+    M.tag('EngineReady', ({ engineId }) => ({
+      colorClassName: 'text-green-600',
+      text: `Engine ready: ${engineId}`,
+    })),
+    M.tag('EngineFailed', ({ reason }) => ({
+      colorClassName: 'text-red-600',
+      text: `Engine failed: ${reason}`,
+    })),
+    M.exhaustive,
+  )
+
+  return h.p([h.Class(status.colorClassName)], [status.text])
+}
+
+const engineControlsView = (
+  engine: EngineState,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const controls = M.value(engine).pipe(
+    M.tag('EngineBooting', 'EngineReady', () => ({
+      label: 'Stop engine',
+      message: Message.ClickedStopEngine(),
+      colorClassName: 'bg-red-500 hover:bg-red-600',
+    })),
+    M.tag('EngineOff', 'EngineFailed', () => ({
+      label: 'Start engine',
+      message: Message.ClickedStartEngine(),
+      colorClassName: 'bg-green-500 hover:bg-green-600',
+    })),
+    M.exhaustive,
+  )
+
+  return h.div(
+    [h.Class('flex gap-3')],
+    [
+      primaryButton(
+        controls.label,
+        controls.message,
+        controls.colorClassName,
+        false,
+        h,
+      ),
+    ],
+  )
+}
+
+const squareResultView = (
+  maybeSquareResult: Option.Option<number>,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const text = Option.match(maybeSquareResult, {
+    onNone: () => 'No result yet.',
+    onSome: value => `Square result: ${value}`,
+  })
+
+  return h.div([h.Class('text-gray-800')], [text])
+}
+
+const isEngineReady = (engine: EngineState): boolean =>
+  engine._tag === 'EngineReady'
+
+export const view = (model: Model, h: HtmlBuilder<Message>): Document => {
+  const isComputeDisabled = !isEngineReady(model.engine)
+
+  return {
+    title: 'Managed Resource Layer',
+    body: h.div(
+      [h.Class('min-h-screen bg-gray-100 flex items-center justify-center')],
+      [
+        h.div(
+          [h.Class('bg-white p-8 rounded-lg shadow flex flex-col gap-5 w-96')],
+          [
+            h.h1(
+              [h.Class('text-xl font-bold text-gray-900')],
+              ['Layer-backed Managed Resource'],
+            ),
+            engineStatusView(model.engine, h),
+            engineControlsView(model.engine, h),
+            primaryButton(
+              'Compute next square',
+              Message.ClickedCompute(),
+              'bg-blue-500 hover:bg-blue-600 data-[disabled]:hover:bg-blue-500',
+              isComputeDisabled,
+              h,
+            ),
+            squareResultView(model.maybeSquareResult, h),
+          ],
+        ),
+      ],
+    ),
+  }
+}

package/dist/templates/examples/managed-resource-layer/src/scene.test.ts

@@ -0,0 +1,117 @@
+import { Option } from 'effect'
+import {
+  Command,
+  ManagedResource,
+  click,
+  expect,
+  given,
+  role,
+  scene,
+  text,
+} from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import {
+  Compute,
+  EngineOff,
+  EngineReady,
+  Message,
+  Model,
+  managedResources,
+  update,
+  view,
+} from './main'
+
+const offModel = Model.make({
+  engine: EngineOff(),
+  computeCount: 0,
+  maybeSquareResult: Option.none(),
+})
+
+const readyModel = Model.make({
+  engine: EngineReady({ engineId: 'engine-1' }),
+  computeCount: 2,
+  maybeSquareResult: Option.none(),
+})
+
+describe('view', () => {
+  test('initial view shows the engine off with a Start button', () => {
+    scene(
+      { update, view },
+      given(offModel),
+      expect(text('Engine is off.')).toExist(),
+      expect(role('button', { name: 'Start engine' })).toExist(),
+      expect(role('button', { name: 'Stop engine' })).toBeAbsent(),
+      expect(role('button', { name: 'Compute next square' })).toBeDisabled(),
+      expect(text('No result yet.')).toExist(),
+    )
+  })
+
+  test('clicking Start engine enters the booting state and shows Stop', () => {
+    scene(
+      { update, view },
+      given(offModel),
+      click(role('button', { name: 'Start engine' })),
+      expect(text('Booting engine...')).toExist(),
+      expect(role('button', { name: 'Stop engine' })).toExist(),
+      expect(role('button', { name: 'Start engine' })).toBeAbsent(),
+    )
+  })
+
+  test('a ready engine shows its id and the Stop button', () => {
+    scene(
+      { update, view },
+      given(readyModel),
+      expect(text('Engine ready: engine-1')).toExist(),
+      expect(role('button', { name: 'Stop engine' })).toExist(),
+      expect(
+        role('button', { name: 'Compute next square' }),
+      ).not.toBeDisabled(),
+    )
+  })
+
+  test('clicking Compute fires the Compute command and renders the result', () => {
+    scene(
+      { update, view },
+      given(readyModel),
+      click(role('button', { name: 'Compute next square' })),
+      Command.expectExact(Compute({ value: 3 })),
+      Command.resolve(Compute, Message.CompletedCompute({ result: 9 })),
+      expect(text('Square result: 9')).toExist(),
+    )
+  })
+
+  test('the engine lifecycle drives boot, ready, and stop through the resource steps', () => {
+    scene(
+      { update, view },
+      given(offModel),
+      click(role('button', { name: 'Start engine' })),
+      expect(text('Booting engine...')).toExist(),
+      ManagedResource.acquire(managedResources.engine, {
+        engineId: 'engine-1',
+        square: value => value * value,
+      }),
+      expect(text('Engine ready: engine-1')).toExist(),
+      expect(
+        role('button', { name: 'Compute next square' }),
+      ).not.toBeDisabled(),
+      click(role('button', { name: 'Stop engine' })),
+      ManagedResource.release(managedResources.engine),
+      expect(text('Engine is off.')).toExist(),
+    )
+  })
+
+  test('a failed engine boot shows the failure reason', () => {
+    scene(
+      { update, view },
+      given(offModel),
+      click(role('button', { name: 'Start engine' })),
+      ManagedResource.failAcquire(
+        managedResources.engine,
+        'Error: crypto unavailable',
+      ),
+      expect(text('Engine failed: Error: crypto unavailable')).toExist(),
+      expect(role('button', { name: 'Start engine' })).toExist(),
+    )
+  })
+})

package/dist/templates/examples/managed-resource-layer/src/story.test.ts

@@ -0,0 +1,118 @@
+import { Option } from 'effect'
+import { Command, given, message, model, story } from 'foldkit/story'
+import { describe, expect, test } from 'vitest'
+
+import {
+  Compute,
+  EngineBooting,
+  EngineFailed,
+  EngineOff,
+  EngineReady,
+  Message,
+  type Model,
+  update,
+} from './main'
+
+const offModel: Model = {
+  engine: EngineOff(),
+  computeCount: 0,
+  maybeSquareResult: Option.none(),
+}
+
+const readyModel: Model = {
+  engine: EngineReady({ engineId: 'engine-1' }),
+  computeCount: 2,
+  maybeSquareResult: Option.none(),
+}
+
+describe('update', () => {
+  describe('engine lifecycle', () => {
+    test('ClickedStartEngine requests the engine by entering EngineBooting', () => {
+      story(
+        update,
+        given(offModel),
+        message(Message.ClickedStartEngine()),
+        model(model => {
+          expect(model.engine._tag).toBe('EngineBooting')
+        }),
+      )
+    })
+
+    test('StartedEngine marks the engine ready with its id', () => {
+      story(
+        update,
+        given({ ...offModel, engine: EngineBooting() }),
+        message(Message.StartedEngine({ engineId: 'engine-7' })),
+        model(model => {
+          expect(model.engine).toStrictEqual(
+            EngineReady({ engineId: 'engine-7' }),
+          )
+        }),
+      )
+    })
+
+    test('ClickedStopEngine releases the engine by entering EngineOff', () => {
+      story(
+        update,
+        given(readyModel),
+        message(Message.ClickedStopEngine()),
+        model(model => {
+          expect(model.engine._tag).toBe('EngineOff')
+        }),
+      )
+    })
+
+    test('StoppedEngine is a no-op lifecycle ack', () => {
+      story(
+        update,
+        given(offModel),
+        message(Message.StoppedEngine()),
+        model(model => {
+          expect(model).toStrictEqual(offModel)
+        }),
+      )
+    })
+
+    test('FailedStartEngine records the failure reason', () => {
+      story(
+        update,
+        given({ ...offModel, engine: EngineBooting() }),
+        message(Message.FailedStartEngine({ reason: 'boot timeout' })),
+        model(model => {
+          expect(model.engine).toStrictEqual(
+            EngineFailed({ reason: 'boot timeout' }),
+          )
+        }),
+      )
+    })
+  })
+
+  describe('compute', () => {
+    test('ClickedCompute increments the counter and fires Compute with the next value', () => {
+      story(
+        update,
+        given(readyModel),
+        message(Message.ClickedCompute()),
+        model(model => {
+          expect(model.computeCount).toBe(3)
+        }),
+        Command.expectExact(Compute({ value: 3 })),
+        Command.resolve(Compute, Message.CompletedCompute({ result: 9 })),
+        model(model => {
+          expect(model.maybeSquareResult).toStrictEqual(Option.some(9))
+        }),
+      )
+    })
+
+    test('SkippedCompute leaves the model unchanged', () => {
+      story(
+        update,
+        given(readyModel),
+        message(Message.SkippedCompute()),
+        model(model => {
+          expect(model).toStrictEqual(readyModel)
+        }),
+      )
+    })
+  })
+})

package/dist/templates/examples/managed-resource-layer/src/styles.css

@@ -0,0 +1 @@
+@import 'tailwindcss';

package/dist/templates/examples/managed-resource-layer/src/vitest-setup.ts

@@ -0,0 +1,3 @@
+import { setup } from 'foldkit/test/vitest'
+
+setup()

package/dist/templates/examples/map/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "map-example",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@effect/platform-browser": "4.0.0-rc.109",
+    "@foldkit/ui": "workspace:*",
+    "@tailwindcss/vite": "^4.3.1",
+    "clsx": "^2.1.1",
+    "effect": "4.0.0-rc.109",
+    "foldkit": "workspace:*",
+    "maplibre-gl": "^5.24.0",
+    "tailwindcss": "^4.3.1"
+  },
+  "devDependencies": {
+    "@foldkit/devtools": "workspace:*",
+    "@foldkit/vite-plugin": "workspace:*",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "happy-dom": "^20.10.4",
+    "prettier": "^3.8.4",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.16",
+    "vitest": "^4.1.9"
+  }
+}

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

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

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

@@ -0,0 +1,69 @@
+import { Schema as S } from 'effect'
+
+export const Location = S.Struct({
+  id: S.String,
+  name: S.String,
+  region: S.String,
+  lng: S.Number,
+  lat: S.Number,
+})
+export type Location = typeof Location.Type
+
+export const featuredLocations: ReadonlyArray<Location> = [
+  {
+    id: 'statue-of-liberty',
+    name: 'Statue of Liberty',
+    region: 'New York, USA',
+    lng: -74.0445,
+    lat: 40.6892,
+  },
+  {
+    id: 'eiffel-tower',
+    name: 'Eiffel Tower',
+    region: 'Paris, France',
+    lng: 2.2945,
+    lat: 48.8584,
+  },
+  {
+    id: 'sydney-opera-house',
+    name: 'Sydney Opera House',
+    region: 'Sydney, Australia',
+    lng: 151.2153,
+    lat: -33.8568,
+  },
+  {
+    id: 'great-wall',
+    name: 'Great Wall (Mutianyu)',
+    region: 'Beijing, China',
+    lng: 116.5685,
+    lat: 40.4319,
+  },
+  {
+    id: 'christ-the-redeemer',
+    name: 'Christ the Redeemer',
+    region: 'Rio de Janeiro, Brazil',
+    lng: -43.2105,
+    lat: -22.9519,
+  },
+  {
+    id: 'taj-mahal',
+    name: 'Taj Mahal',
+    region: 'Agra, India',
+    lng: 78.0421,
+    lat: 27.1751,
+  },
+  {
+    id: 'machu-picchu',
+    name: 'Machu Picchu',
+    region: 'Cusco Region, Peru',
+    lng: -72.5449,
+    lat: -13.1631,
+  },
+  {
+    id: 'colosseum',
+    name: 'Colosseum',
+    region: 'Rome, Italy',
+    lng: 12.4924,
+    lat: 41.8902,
+  },
+]

package/dist/templates/examples/map/src/main.fixtures.ts

@@ -0,0 +1,28 @@
+import { Option } from 'effect'
+
+import { Location, featuredLocations } from './locations'
+import { GeolocateIdle, type Model } from './main'
+
+export const initialModel: Model = {
+  locations: featuredLocations,
+  searchQuery: '',
+  maybeMapHostId: Option.none(),
+  maybeMapError: Option.none(),
+  maybeBounds: Option.none(),
+  maybeSelectedLocationId: Option.none(),
+  maybeUserLocation: Option.none(),
+  geolocateState: GeolocateIdle(),
+}
+
+export const mountedModel: Model = {
+  ...initialModel,
+  maybeMapHostId: Option.some('map-host-1'),
+}
+
+export const eiffelTower: Location = {
+  id: 'eiffel-tower',
+  name: 'Eiffel Tower',
+  region: 'Paris, France',
+  lng: 2.2945,
+  lat: 48.8584,
+}