create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/interrupting-commands/src/main.ts

@@ -0,0 +1,354 @@
+import clsx from 'clsx'
+import {
+  Array,
+  Duration,
+  Effect,
+  Match as M,
+  Number,
+  Option,
+  Schema as S,
+  pipe,
+} from 'effect'
+import { Command, Runtime } from 'foldkit'
+import { Document, Html, HtmlBuilder } from 'foldkit/html'
+import { defineMessageUnion } from 'foldkit/message'
+import { evo } from 'foldkit/struct'
+
+// MODEL
+
+export const UploadStatus = S.Literals(['Uploading', 'Done', 'Cancelled'])
+export type UploadStatus = typeof UploadStatus.Type
+
+export const Upload = S.Struct({
+  id: S.Number,
+  fileName: S.String,
+  sizeMegabytes: S.Number,
+  status: UploadStatus,
+})
+export type Upload = typeof Upload.Type
+
+export const Model = S.Struct({
+  uploadId: S.Number,
+  uploads: S.Array(Upload),
+})
+export type Model = typeof Model.Type
+
+// MESSAGE
+
+export const Message = defineMessageUnion({
+  ClickedStartUpload: {},
+  ClickedCancelUpload: { uploadId: S.Number },
+  ClickedCancelAllUploads: {},
+  ClickedRestartUpload: { uploadId: S.Number },
+  SucceededUploadFile: { uploadId: S.Number },
+  CompletedCancelUploadFile: {
+    uploadId: S.Number,
+    outcome: Command.Interruptible.Outcome,
+  },
+})
+
+export type Message = typeof Message.Type
+
+// INIT
+
+export const initialModel: Model = {
+  uploadId: 0,
+  uploads: [],
+}
+
+export const init: Runtime.ApplicationInit<Model, Message> = () => [
+  initialModel,
+  [],
+]
+
+// FAKE FILES
+
+export const FakeFile = S.Struct({ name: S.String, sizeMegabytes: S.Number })
+export type FakeFile = typeof FakeFile.Type
+
+export const FAKE_FILES: Array.NonEmptyReadonlyArray<FakeFile> = [
+  { name: 'vacation-photos.zip', sizeMegabytes: 48 },
+  { name: 'demo-recording.mp4', sizeMegabytes: 87 },
+  { name: 'quarterly-report.pdf', sizeMegabytes: 12 },
+  { name: 'design-assets.sketch', sizeMegabytes: 34 },
+  { name: 'database-backup.sql', sizeMegabytes: 61 },
+]
+
+const fakeFileForUpload = (uploadId: number): FakeFile =>
+  pipe(
+    FAKE_FILES,
+    Array.get(uploadId % Array.length(FAKE_FILES)),
+    Option.getOrElse(() => Array.headNonEmpty(FAKE_FILES)),
+  )
+
+// COMMAND
+
+const MILLISECONDS_PER_MEGABYTE = 100
+
+export const UploadKey = S.Struct({ uploadId: S.Number })
+export type UploadKey = typeof UploadKey.Type
+
+export const UploadFile = Command.define('UploadFile', {
+  args: { ...UploadKey.fields, sizeMegabytes: S.Number },
+  messages: [Message.SucceededUploadFile],
+  interrupt: {
+    keyFields: ['uploadId'],
+    toKey: ({ uploadId }) => String(uploadId),
+  },
+  execute: ({ uploadId, sizeMegabytes }) =>
+    Effect.gen(function* () {
+      yield* Effect.sleep(
+        Duration.millis(sizeMegabytes * MILLISECONDS_PER_MEGABYTE),
+      )
+      return Message.SucceededUploadFile({ uploadId })
+    }),
+})
+
+export const CancelUploadFile = ({ uploadId }: UploadKey) =>
+  UploadFile.Interrupt({ uploadId }, outcome =>
+    Message.CompletedCancelUploadFile({ uploadId, outcome }),
+  )
+
+// UPDATE
+
+const setStatusForId = (uploadId: number, status: UploadStatus) =>
+  Array.map((upload: Upload) =>
+    upload.id === uploadId ? evo(upload, { status: () => status }) : upload,
+  )
+
+export const update = (model: Model, message: Message) =>
+  Message.match<readonly [Model, ReadonlyArray<Command.Command<Message>>]>(
+    message,
+    {
+      ClickedStartUpload: () => {
+        const fakeFile = fakeFileForUpload(model.uploadId)
+        const startedUpload = Upload.make({
+          id: model.uploadId,
+          fileName: fakeFile.name,
+          sizeMegabytes: fakeFile.sizeMegabytes,
+          status: 'Uploading',
+        })
+        return [
+          evo(model, {
+            uploadId: Number.increment,
+            uploads: Array.append(startedUpload),
+          }),
+          [
+            UploadFile({
+              uploadId: startedUpload.id,
+              sizeMegabytes: startedUpload.sizeMegabytes,
+            }),
+          ],
+        ]
+      },
+
+      ClickedCancelUpload: ({ uploadId }) => [
+        model,
+        [CancelUploadFile({ uploadId })],
+      ],
+
+      ClickedCancelAllUploads: () => [
+        model,
+        pipe(
+          model.uploads,
+          Array.filter(upload => upload.status === 'Uploading'),
+          Array.map(upload => CancelUploadFile({ uploadId: upload.id })),
+        ),
+      ],
+
+      ClickedRestartUpload: ({ uploadId }) =>
+        pipe(
+          model.uploads,
+          Array.findFirst(
+            upload => upload.id === uploadId && upload.status === 'Cancelled',
+          ),
+          Option.match({
+            onNone: () => [model, []],
+            onSome: upload => [
+              evo(model, { uploads: setStatusForId(uploadId, 'Uploading') }),
+              [UploadFile({ uploadId, sizeMegabytes: upload.sizeMegabytes })],
+            ],
+          }),
+        ),
+
+      SucceededUploadFile: ({ uploadId }) => [
+        evo(model, { uploads: setStatusForId(uploadId, 'Done') }),
+        [],
+      ],
+
+      CompletedCancelUploadFile: ({ uploadId, outcome }) =>
+        M.value(outcome).pipe(
+          M.withReturnType<
+            readonly [Model, ReadonlyArray<Command.Command<Message>>]
+          >(),
+          M.tagsExhaustive({
+            Interrupted: () => [
+              evo(model, { uploads: setStatusForId(uploadId, 'Cancelled') }),
+              [],
+            ],
+            NotFound: () => [model, []],
+          }),
+        ),
+    },
+  )
+
+// VIEW
+
+const badgeClass = (status: UploadStatus): string =>
+  M.value(status).pipe(
+    M.when('Uploading', () => 'bg-blue-100 text-blue-700'),
+    M.when('Done', () => 'bg-green-100 text-green-700'),
+    M.when('Cancelled', () => 'bg-gray-200 text-gray-600'),
+    M.exhaustive,
+  )
+
+const ACTION_BUTTON_CLASS =
+  'px-3 py-1 text-sm font-medium rounded-md border transition'
+
+const uploadActionView = (upload: Upload, h: HtmlBuilder<Message>): Html =>
+  M.value(upload.status).pipe(
+    M.when('Uploading', () =>
+      h.keyed('button')(
+        'Uploading',
+        [
+          h.OnClick(Message.ClickedCancelUpload({ uploadId: upload.id })),
+          h.AriaLabel(`Cancel upload ${upload.id}`),
+          h.Class(
+            clsx(
+              ACTION_BUTTON_CLASS,
+              'border-red-300 text-red-600 hover:bg-red-50',
+            ),
+          ),
+        ],
+        ['Cancel'],
+      ),
+    ),
+    M.when('Cancelled', () =>
+      h.keyed('button')(
+        'Cancelled',
+        [
+          h.OnClick(Message.ClickedRestartUpload({ uploadId: upload.id })),
+          h.AriaLabel(`Restart upload ${upload.id}`),
+          h.Class(
+            clsx(
+              ACTION_BUTTON_CLASS,
+              'border-blue-300 text-blue-600 hover:bg-blue-50',
+            ),
+          ),
+        ],
+        ['Restart'],
+      ),
+    ),
+    M.when('Done', () => h.empty),
+    M.exhaustive,
+  )
+
+const uploadView = (upload: Upload, h: HtmlBuilder<Message>): Html =>
+  h.keyed('li')(
+    String(upload.id),
+    [h.Class('p-4 bg-white rounded-lg shadow flex flex-col gap-2')],
+    [
+      h.div(
+        [h.Class('flex items-center justify-between gap-3')],
+        [
+          h.div(
+            [h.Class('flex items-baseline gap-2 min-w-0')],
+            [
+              h.span(
+                [h.Class('font-medium text-gray-800 truncate')],
+                [upload.fileName],
+              ),
+              h.span(
+                [h.Class('text-sm text-gray-500 shrink-0')],
+                [`${upload.sizeMegabytes} MB`],
+              ),
+            ],
+          ),
+          h.div(
+            [h.Class('flex items-center gap-3 shrink-0')],
+            [
+              h.span(
+                [
+                  h.Class(
+                    clsx(
+                      'px-2 py-0.5 text-xs font-semibold rounded-full',
+                      badgeClass(upload.status),
+                    ),
+                  ),
+                ],
+                [upload.status],
+              ),
+              uploadActionView(upload, h),
+            ],
+          ),
+        ],
+      ),
+      upload.status === 'Uploading'
+        ? h.div([h.Class('h-1.5 rounded-full bg-blue-400 animate-pulse')])
+        : h.empty,
+    ],
+  )
+
+export const view = (model: Model, h: HtmlBuilder<Message>): Document => {
+  const isAnyUploadRunning = Array.some(
+    model.uploads,
+    upload => upload.status === 'Uploading',
+  )
+
+  const body = h.div(
+    [h.Class('min-h-screen bg-gray-100 py-8')],
+    [
+      h.div(
+        [h.Class('max-w-lg mx-auto flex flex-col gap-6 px-4')],
+        [
+          h.h1(
+            [h.Class('text-3xl font-bold text-gray-800 text-center')],
+            ['File Uploads'],
+          ),
+          h.div(
+            [h.Class('flex justify-center gap-3')],
+            [
+              h.button(
+                [
+                  h.OnClick(Message.ClickedStartUpload()),
+                  h.Class(
+                    'px-4 py-2 rounded-md bg-blue-500 text-white font-medium hover:bg-blue-600 transition',
+                  ),
+                ],
+                ['Upload a file'],
+              ),
+              isAnyUploadRunning
+                ? h.keyed('button')(
+                    'CancelAll',
+                    [
+                      h.OnClick(Message.ClickedCancelAllUploads()),
+                      h.Class(
+                        'px-4 py-2 rounded-md border border-red-300 text-red-600 font-medium hover:bg-red-50 transition',
+                      ),
+                    ],
+                    ['Cancel all'],
+                  )
+                : h.empty,
+            ],
+          ),
+          Array.match(model.uploads, {
+            onEmpty: () =>
+              h.keyed('p')(
+                'NoUploads',
+                [h.Class('text-center text-gray-500')],
+                ['Nothing here yet. Start an upload.'],
+              ),
+            onNonEmpty: uploads =>
+              h.keyed('ul')(
+                'UploadList',
+                [h.Class('flex flex-col gap-3')],
+                Array.map(uploads, upload => uploadView(upload, h)),
+              ),
+          }),
+        ],
+      ),
+    ],
+  )
+
+  return { title: 'Foldkit Interrupting Commands Example', body }
+}

package/dist/templates/examples/interrupting-commands/src/scene.test.ts

@@ -0,0 +1,89 @@
+import { Array } from 'effect'
+import { Interruptible } from 'foldkit/command'
+import { Command, click, expect, given, role, scene, text } from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import {
+  CancelUploadFile,
+  FAKE_FILES,
+  Message,
+  UploadFile,
+  initialModel,
+  update,
+  view,
+} from './main'
+
+const firstFile = Array.headNonEmpty(FAKE_FILES)
+
+describe('view', () => {
+  test('initial view shows the start button and an empty state', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      expect(role('heading', { name: 'File Uploads' })).toExist(),
+      expect(role('button', { name: 'Upload a file' })).toExist(),
+      expect(text('Nothing here yet. Start an upload.')).toExist(),
+    )
+  })
+
+  test('starting an upload shows an Uploading row with a cancel button', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      click(role('button', { name: 'Upload a file' })),
+      expect(text(firstFile.name)).toExist(),
+      expect(text('Uploading')).toExist(),
+      expect(role('button', { name: 'Cancel upload 0' })).toExist(),
+      Command.resolve(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 0 }),
+      ),
+      expect(text('Done')).toExist(),
+    )
+  })
+
+  test('cancelling an upload marks it Cancelled and offers a restart', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      click(role('button', { name: 'Upload a file' })),
+      click(role('button', { name: 'Cancel upload 0' })),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      expect(text('Cancelled')).toExist(),
+      expect(role('button', { name: 'Restart upload 0' })).toExist(),
+      click(role('button', { name: 'Restart upload 0' })),
+      expect(text('Uploading')).toExist(),
+      Command.resolve(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 0 }),
+      ),
+      expect(text('Done')).toExist(),
+    )
+  })
+
+  test('the cancel all button appears only while an upload is running', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      expect(role('button', { name: 'Cancel all' })).toBeAbsent(),
+      click(role('button', { name: 'Upload a file' })),
+      expect(role('button', { name: 'Cancel all' })).toExist(),
+      click(role('button', { name: 'Cancel all' })),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      expect(role('button', { name: 'Cancel all' })).toBeAbsent(),
+      expect(text('Cancelled')).toExist(),
+    )
+  })
+})

package/dist/templates/examples/interrupting-commands/src/story.test.ts

@@ -0,0 +1,224 @@
+import { Array, Option } from 'effect'
+import { Interruptible } from 'foldkit/command'
+import { Command, given, message, model, story } from 'foldkit/story'
+import { describe, expect, test } from 'vitest'
+
+import {
+  CancelUploadFile,
+  FAKE_FILES,
+  Message,
+  UploadFile,
+  initialModel,
+  update,
+} from './main'
+
+const firstFile = Array.headNonEmpty(FAKE_FILES)
+const secondFile = Option.getOrThrow(Array.get(FAKE_FILES, 1))
+
+describe('update', () => {
+  test('starting an upload appends an Uploading entry and fires UploadFile', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      model(model => {
+        expect(model.uploads).toEqual([
+          {
+            id: 0,
+            fileName: firstFile.name,
+            sizeMegabytes: firstFile.sizeMegabytes,
+            status: 'Uploading',
+          },
+        ])
+        expect(model.uploadId).toBe(1)
+      }),
+      Command.expectExact(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+      ),
+      Command.resolve(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 0 }),
+      ),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Done',
+        ])
+      }),
+    )
+  })
+
+  test('cancelling an upload interrupts it and marks it Cancelled', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedCancelUpload({ uploadId: 0 })),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      Command.expectNone(),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Cancelled',
+        ])
+      }),
+    )
+  })
+
+  test('a cancel that lands after completion resolves NotFound and changes nothing', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      Command.resolve(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 0 }),
+      ),
+      message(Message.ClickedCancelUpload({ uploadId: 0 })),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.NotFound(),
+        }),
+      ),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Done',
+        ])
+      }),
+    )
+  })
+
+  test('cancelling one upload leaves the other running', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedCancelUpload({ uploadId: 0 })),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      Command.expectExact(
+        UploadFile({ uploadId: 1, sizeMegabytes: secondFile.sizeMegabytes }),
+      ),
+      Command.resolve(
+        UploadFile({ uploadId: 1, sizeMegabytes: secondFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 1 }),
+      ),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Cancelled',
+          'Done',
+        ])
+      }),
+    )
+  })
+
+  test('a new upload can start while a cancellation is still pending', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedCancelUpload({ uploadId: 0 })),
+      message(Message.ClickedStartUpload()),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      Command.resolve(
+        UploadFile({ uploadId: 1, sizeMegabytes: secondFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 1 }),
+      ),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Cancelled',
+          'Done',
+        ])
+      }),
+    )
+  })
+
+  test('restarting a cancelled upload reuses its id and file', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedCancelUpload({ uploadId: 0 })),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      message(Message.ClickedRestartUpload({ uploadId: 0 })),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Uploading',
+        ])
+      }),
+      Command.expectExact(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+      ),
+      Command.resolve(
+        UploadFile({ uploadId: 0, sizeMegabytes: firstFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 0 }),
+      ),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Done',
+        ])
+      }),
+    )
+  })
+
+  test('cancel all interrupts every running upload and only those', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedStartUpload()),
+      message(Message.ClickedStartUpload()),
+      Command.resolve(
+        UploadFile({ uploadId: 1, sizeMegabytes: secondFile.sizeMegabytes }),
+        Message.SucceededUploadFile({ uploadId: 1 }),
+      ),
+      message(Message.ClickedCancelAllUploads()),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 0 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 0,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      Command.resolve(
+        CancelUploadFile({ uploadId: 2 }),
+        Message.CompletedCancelUploadFile({
+          uploadId: 2,
+          outcome: Interruptible.Interrupted(),
+        }),
+      ),
+      Command.expectNone(),
+      model(model => {
+        expect(Array.map(model.uploads, upload => upload.status)).toEqual([
+          'Cancelled',
+          'Done',
+          'Cancelled',
+        ])
+      }),
+    )
+  })
+})

package/dist/templates/examples/interrupting-commands/src/styles.css

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

package/dist/templates/examples/interrupting-commands/src/vitest-setup.ts

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

package/dist/templates/examples/job-application/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "job-application-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:*",
+    "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"
+  }
+}