create-foldkit-app 0.37.0 → 0.38.0

package/dist/templates/examples/api-cache-query/src/scene.test.ts

@@ -0,0 +1,124 @@
+import { Result } from 'effect'
+import {
+  Command,
+  click,
+  expect,
+  given,
+  inside,
+  role,
+  scene,
+  text,
+} from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import { Tabs } from '@foldkit/ui'
+
+import { postQuery, statsQuery, update, view } from './main'
+import {
+  FETCHED_AT,
+  cachedFirstPostModel,
+  firstPostDetail,
+  fixtureStats,
+  loadedPostsModel,
+  loadingPostsModel,
+} from './main.fixture'
+
+const FIRST_REQUEST_GENERATION = 1
+
+const resolveFocusTab = Command.resolve(
+  Tabs.FocusTab,
+  Tabs.Message.CompletedFocusTab(),
+)
+
+describe('view', () => {
+  test('the posts tab renders its loading state and navigation', () => {
+    scene(
+      { update, view },
+      given(loadingPostsModel),
+      expect(text('Loading posts…')).toExist(),
+      expect(role('button', { name: 'Refresh' })).toExist(),
+      expect(role('tab', { name: 'Posts' })).toExist(),
+      expect(role('tab', { name: 'Stats' })).toExist(),
+    )
+  })
+
+  test('clicking a post fetches its detail and renders it', () => {
+    scene(
+      { update, view },
+      given(loadedPostsModel),
+      click(role('button', { name: /First Post/ })),
+      expect(text('Loading post…')).toExist(),
+      Command.expectExact(postQuery.Fetch),
+      Command.resolve(
+        postQuery.Fetch,
+        postQuery.Message.CompletedFetch({
+          args: { postId: 'first-post' },
+          generation: FIRST_REQUEST_GENERATION,
+          result: Result.succeed({
+            post: firstPostDetail,
+            fetchedAt: FETCHED_AT,
+          }),
+        }),
+      ),
+      inside(
+        role('article'),
+        expect(text('By Grace Hopper')).toExist(),
+        expect(text('The whole body of the first fixture post.')).toExist(),
+      ),
+      expect(role('button', { name: 'Back to posts' })).toExist(),
+    )
+  })
+
+  test('opening a cached post skips the fetch', () => {
+    scene(
+      { update, view },
+      given(cachedFirstPostModel),
+      expect(text('Cached')).toExist(),
+      click(role('button', { name: /First Post/ })),
+      Command.expectNone(),
+      expect(text('By Grace Hopper')).toExist(),
+    )
+  })
+
+  test('a failed post fetch shows the error with a Retry button', () => {
+    scene(
+      { update, view },
+      given(loadedPostsModel),
+      click(role('button', { name: /First Post/ })),
+      Command.resolve(
+        postQuery.Fetch,
+        postQuery.Message.CompletedFetch({
+          args: { postId: 'first-post' },
+          generation: FIRST_REQUEST_GENERATION,
+          result: Result.fail('The connection dropped.'),
+        }),
+      ),
+      expect(text('The connection dropped.')).toExist(),
+      expect(role('button', { name: 'Retry' })).toExist(),
+    )
+  })
+
+  test('switching to the Stats tab fetches and renders stats', () => {
+    scene(
+      { update, view },
+      given(loadedPostsModel),
+      click(role('tab', { name: 'Stats' })),
+      expect(text('Loading stats…')).toExist(),
+      resolveFocusTab,
+      Command.expectExact(statsQuery.Fetch),
+      Command.resolve(
+        statsQuery.Fetch,
+        statsQuery.Message.CompletedFetch({
+          generation: FIRST_REQUEST_GENERATION,
+          result: Result.succeed({
+            stats: fixtureStats,
+            fetchedAt: FETCHED_AT,
+          }),
+        }),
+      ),
+      expect(text('Active users')).toExist(),
+      expect(text('97%')).toExist(),
+      expect(text('Updated at', { exact: false })).toExist(),
+    )
+  })
+})

package/dist/templates/examples/api-cache-query/src/story.test.ts

@@ -0,0 +1,297 @@
+import { Option, Result } from 'effect'
+import { Command, given, message, model, story } from 'foldkit/story'
+import { modifyFields } from 'foldkit/struct'
+import { expect, test } from 'vitest'
+
+import { Tabs } from '@foldkit/ui'
+
+import { Message, postQuery, postsQuery, statsQuery, update } from './main'
+import {
+  FETCHED_AT,
+  failedFirstPostModel,
+  failedPostsModel,
+  firstPostDetail,
+  fixturePosts,
+  fixtureStats,
+  loadedPostsModel,
+  loadedStatsModel,
+  loadingStatsModel,
+  refreshingStatsModel,
+} from './main.fixture'
+
+const FIRST_REQUEST_GENERATION = 1
+const SECOND_REQUEST_GENERATION = 2
+
+const postAsyncDataTag = (
+  model: typeof loadedPostsModel,
+  postId: string,
+): string => postQuery.read(model.postDetails, { postId })._tag
+
+const selectedPostsTab = Message.GotTabsMessage({
+  message: Tabs.Message.SelectedTab({ index: 0, value: 'Posts' }),
+})
+
+const selectedStatsTab = Message.GotTabsMessage({
+  message: Tabs.Message.SelectedTab({ index: 1, value: 'Stats' }),
+})
+
+const resolveFocusTab = Command.resolve(
+  Tabs.FocusTab,
+  Tabs.Message.CompletedFocusTab(),
+)
+
+test('first visit to the Stats tab fetches stats', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(selectedStatsTab),
+    model(model => {
+      expect(model.activeTab).toBe('Stats')
+      expect(statsQuery.read(model.stats)._tag).toBe('Loading')
+    }),
+    resolveFocusTab,
+    Command.resolve(
+      statsQuery.Fetch,
+      statsQuery.Message.CompletedFetch({
+        generation: FIRST_REQUEST_GENERATION,
+        result: Result.succeed({
+          stats: fixtureStats,
+          fetchedAt: FETCHED_AT,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(statsQuery.read(model.stats)._tag).toBe('Success')
+    }),
+  )
+})
+
+test('returning to a tab with cached data does not refetch', () => {
+  story(
+    update,
+    given(loadedStatsModel),
+    message(selectedPostsTab),
+    resolveFocusTab,
+    Command.expectNone(),
+    message(selectedStatsTab),
+    resolveFocusTab,
+    Command.expectNone(),
+    model(model => {
+      expect(statsQuery.read(model.stats)._tag).toBe('Success')
+    }),
+  )
+})
+
+test('a revalidation tick keeps stale stats on screen while refetching', () => {
+  story(
+    update,
+    given(loadedStatsModel),
+    message(Message.TickedStatsRefreshInterval()),
+    model(model => {
+      const statsAsyncData = statsQuery.read(model.stats)
+      expect(statsAsyncData._tag).toBe('Refreshing')
+      if (statsAsyncData._tag === 'Refreshing') {
+        expect(statsAsyncData.data.stats).toEqual(fixtureStats)
+      }
+    }),
+    Command.resolve(
+      statsQuery.Fetch,
+      statsQuery.Message.CompletedFetch({
+        generation: SECOND_REQUEST_GENERATION,
+        result: Result.succeed({
+          stats: modifyFields(fixtureStats, { activeUsers: () => 99 }),
+          fetchedAt: FETCHED_AT + 5000,
+        }),
+      }),
+    ),
+    model(model => {
+      const statsAsyncData = statsQuery.read(model.stats)
+      expect(statsAsyncData._tag).toBe('Success')
+      if (statsAsyncData._tag === 'Success') {
+        expect(statsAsyncData.data.stats.activeUsers).toBe(99)
+      }
+    }),
+  )
+})
+
+test('a failed refresh keeps the stale stats on screen with the error', () => {
+  story(
+    update,
+    given(loadedStatsModel),
+    message(Message.TickedStatsRefreshInterval()),
+    Command.resolve(
+      statsQuery.Fetch,
+      statsQuery.Message.CompletedFetch({
+        generation: SECOND_REQUEST_GENERATION,
+        result: Result.fail('The server is down.'),
+      }),
+    ),
+    model(model => {
+      const statsAsyncData = statsQuery.read(model.stats)
+      expect(statsAsyncData._tag).toBe('Stale')
+      if (statsAsyncData._tag === 'Stale') {
+        expect(statsAsyncData.data.stats).toEqual(fixtureStats)
+        expect(statsAsyncData.error).toBe('The server is down.')
+      }
+    }),
+  )
+})
+
+test('refresh clicks during an in-flight fetch are deduplicated', () => {
+  story(
+    update,
+    given(loadingStatsModel),
+    message(Message.ClickedRefreshStats()),
+    Command.expectNone(),
+  )
+})
+
+test('a revalidation tick during a refresh is deduplicated', () => {
+  story(
+    update,
+    given(refreshingStatsModel),
+    message(Message.TickedStatsRefreshInterval()),
+    Command.expectNone(),
+  )
+})
+
+test('refreshing posts refetches while keeping the current list', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(Message.ClickedRefreshPosts()),
+    model(model => {
+      const postsAsyncData = postsQuery.read(model.posts)
+      expect(postsAsyncData._tag).toBe('Refreshing')
+      if (postsAsyncData._tag === 'Refreshing') {
+        expect(postsAsyncData.data.posts).toEqual(fixturePosts)
+      }
+    }),
+    Command.resolve(
+      postsQuery.Fetch,
+      postsQuery.Message.CompletedFetch({
+        generation: SECOND_REQUEST_GENERATION,
+        result: Result.succeed({
+          posts: fixturePosts,
+          fetchedAt: FETCHED_AT + 1000,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(postsQuery.read(model.posts)._tag).toBe('Success')
+    }),
+  )
+})
+
+test('retrying failed posts shows the loading state and refetches', () => {
+  story(
+    update,
+    given(failedPostsModel),
+    message(Message.ClickedRetryPosts()),
+    model(model => {
+      expect(postsQuery.read(model.posts)._tag).toBe('Loading')
+    }),
+    Command.resolve(
+      postsQuery.Fetch,
+      postsQuery.Message.CompletedFetch({
+        generation: SECOND_REQUEST_GENERATION,
+        result: Result.succeed({
+          posts: fixturePosts,
+          fetchedAt: FETCHED_AT,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(postsQuery.read(model.posts)._tag).toBe('Success')
+    }),
+  )
+})
+
+test('opening a post once reuses its retained data on later visits', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Loading')
+    }),
+    Command.resolve(
+      postQuery.Fetch,
+      postQuery.Message.CompletedFetch({
+        args: { postId: 'first-post' },
+        generation: FIRST_REQUEST_GENERATION,
+        result: Result.succeed({
+          post: firstPostDetail,
+          fetchedAt: FETCHED_AT,
+        }),
+      }),
+    ),
+    message(Message.ClickedBackToPosts()),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    Command.expectNone(),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Success')
+      expect(model.maybeSelectedPostId).toEqual(Option.some('first-post'))
+    }),
+  )
+})
+
+test('a failed post fetch enters Failure and retry fetches it again', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    Command.resolve(
+      postQuery.Fetch,
+      postQuery.Message.CompletedFetch({
+        args: { postId: 'first-post' },
+        generation: FIRST_REQUEST_GENERATION,
+        result: Result.fail('The connection dropped.'),
+      }),
+    ),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Failure')
+    }),
+    message(Message.ClickedRetryPost({ postId: 'first-post' })),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Loading')
+    }),
+    Command.resolve(
+      postQuery.Fetch,
+      postQuery.Message.CompletedFetch({
+        args: { postId: 'first-post' },
+        generation: SECOND_REQUEST_GENERATION,
+        result: Result.succeed({
+          post: firstPostDetail,
+          fetchedAt: FETCHED_AT,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Success')
+    }),
+  )
+})
+
+test('revisiting a post with a cached failure loads it again', () => {
+  story(
+    update,
+    given(failedFirstPostModel),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Loading')
+      expect(model.maybeSelectedPostId).toEqual(Option.some('first-post'))
+    }),
+    Command.resolve(
+      postQuery.Fetch,
+      postQuery.Message.CompletedFetch({
+        args: { postId: 'first-post' },
+        generation: SECOND_REQUEST_GENERATION,
+        result: Result.fail('The connection dropped.'),
+      }),
+    ),
+    model(model => {
+      expect(postAsyncDataTag(model, 'first-post')).toBe('Failure')
+    }),
+  )
+})

package/dist/templates/examples/api-cache-query/src/styles.css

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

package/dist/templates/examples/api-cache-query/src/vitest-setup.ts

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

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

@@ -1,3 +1,4 @@
+import { Option } from 'effect'
 import { Subscription } from 'foldkit'
 
 import { Slider } from '@foldkit/ui'
@@ -9,7 +10,7 @@ const flowStrengthSliderSubscriptions = Subscription.lift({
   flowStrengthSliderPointer: Slider.subscriptions.dragPointer,
   flowStrengthSliderEscape: Slider.subscriptions.dragEscape,
 })<Model, Message>({
-  toChildModel: model => model.flowStrengthSlider,
+  read: model => Option.some(model.flowStrengthSlider),
   toParentMessage: message => Message.GotFlowStrengthSliderMessage({ message }),
 })
 
@@ -17,7 +18,7 @@ const noiseScaleSliderSubscriptions = Subscription.lift({
   noiseScaleSliderPointer: Slider.subscriptions.dragPointer,
   noiseScaleSliderEscape: Slider.subscriptions.dragEscape,
 })<Model, Message>({
-  toChildModel: model => model.noiseScaleSlider,
+  read: model => Option.some(model.noiseScaleSlider),
   toParentMessage: message => Message.GotNoiseScaleSliderMessage({ message }),
 })
 

package/dist/templates/examples/kanban/src/subscription.ts

@@ -1,3 +1,4 @@
+import { Option } from 'effect'
 import { Subscription } from 'foldkit'
 
 import { DragAndDrop } from '@foldkit/ui'
@@ -11,6 +12,6 @@ export const subscriptions = Subscription.lift({
   dragKeyboard: DragAndDrop.subscriptions.documentKeyboard,
   autoScroll: DragAndDrop.subscriptions.autoScroll,
 })<Model, Message>({
-  toChildModel: model => model.dragAndDrop,
+  read: model => Option.some(model.dragAndDrop),
   toParentMessage: message => Message.GotDragAndDropMessage({ message }),
 })

package/dist/templates/examples/ui-showcase/src/main.ts

@@ -671,6 +671,6 @@ export const subscriptions = Subscription.lift(UiSubscriptions.subscriptions)<
   Model,
   Message
 >({
-  toChildModel: model => model.uiModel,
+  read: model => Option.some(model.uiModel),
   toParentMessage: message => Message.GotUiMessage({ message }),
 })

package/dist/templates/examples/ui-showcase/src/ui/subscriptions.ts

@@ -1,3 +1,4 @@
+import { Option } from 'effect'
 import { Subscription } from 'foldkit'
 
 import { DragAndDrop, Slider, VirtualList } from '@foldkit/ui'
@@ -12,7 +13,7 @@ const dragAndDropSubscriptions = Subscription.lift({
   dragKeyboard: DragAndDrop.subscriptions.documentKeyboard,
   autoScroll: DragAndDrop.subscriptions.autoScroll,
 })<UiModel, UiMessage>({
-  toChildModel: model => model.dragAndDropDemo,
+  read: model => Option.some(model.dragAndDropDemo),
   toParentMessage: message => UiMessage.GotDragAndDropDemoMessage({ message }),
 })
 
@@ -20,7 +21,7 @@ const sliderRatingSubscriptions = Subscription.lift({
   sliderRatingPointer: Slider.subscriptions.dragPointer,
   sliderRatingEscape: Slider.subscriptions.dragEscape,
 })<UiModel, UiMessage>({
-  toChildModel: model => model.sliderRatingDemo,
+  read: model => Option.some(model.sliderRatingDemo),
   toParentMessage: message => UiMessage.GotSliderRatingDemoMessage({ message }),
 })
 
@@ -28,21 +29,21 @@ const sliderVolumeSubscriptions = Subscription.lift({
   sliderVolumePointer: Slider.subscriptions.dragPointer,
   sliderVolumeEscape: Slider.subscriptions.dragEscape,
 })<UiModel, UiMessage>({
-  toChildModel: model => model.sliderVolumeDemo,
+  read: model => Option.some(model.sliderVolumeDemo),
   toParentMessage: message => UiMessage.GotSliderVolumeDemoMessage({ message }),
 })
 
 const virtualListDemoSubscriptions = Subscription.lift({
   virtualListContainerEvents: VirtualList.subscriptions.containerEvents,
 })<UiModel, UiMessage>({
-  toChildModel: model => model.virtualListDemo,
+  read: model => Option.some(model.virtualListDemo),
   toParentMessage: message => UiMessage.GotVirtualListDemoMessage({ message }),
 })
 
 const virtualListVariableDemoSubscriptions = Subscription.lift({
   virtualListVariableContainerEvents: VirtualList.subscriptions.containerEvents,
 })<UiModel, UiMessage>({
-  toChildModel: model => model.virtualListVariableDemo,
+  read: model => Option.some(model.virtualListVariableDemo),
   toParentMessage: message =>
     UiMessage.GotVirtualListVariableDemoMessage({ message }),
 })
@@ -51,7 +52,7 @@ const toastDemoSubscriptions = Subscription.lift(Toast.subscriptions)<
   UiModel,
   UiMessage
 >({
-  toChildModel: model => model.toastDemo,
+  read: model => Option.some(model.toastDemo),
   toParentMessage: message => UiMessage.GotToastDemoMessage({ message }),
 })
 

package/dist/templates/release.json

@@ -1,22 +1,22 @@
 {
   "schemaVersion": 1,
   "channel": "stable",
-  "sourceCommit": "0b2a4fd04171afa8c8911d22aa9bec2f22faae52",
+  "sourceCommit": "7590156835c822a0aa135a5fde14c8e2009c9124",
   "packages": {
-    "create-foldkit-app": "0.37.0",
-    "@foldkit/devtools": "0.165.0",
-    "@foldkit/devtools-mcp": "0.24.0",
-    "foldkit": "0.165.0",
-    "@foldkit/markdown": "0.14.0",
-    "@foldkit/oxlint-plugin": "0.15.1",
-    "@foldkit/ui": "0.165.0",
-    "@foldkit/vite-plugin": "0.26.0"
+    "create-foldkit-app": "0.38.0",
+    "@foldkit/devtools": "0.166.0",
+    "@foldkit/devtools-mcp": "0.24.1",
+    "foldkit": "0.166.0",
+    "@foldkit/markdown": "0.14.1",
+    "@foldkit/oxlint-plugin": "0.15.2",
+    "@foldkit/ui": "0.166.0",
+    "@foldkit/vite-plugin": "0.26.1"
   },
   "dependencies": {
-    "@foldkit/devtools": "0.165.0",
-    "@foldkit/vite-plugin": "0.26.0",
-    "@foldkit/devtools-mcp": "0.24.0",
-    "@foldkit/oxlint-plugin": "0.15.1",
+    "@foldkit/devtools": "0.166.0",
+    "@foldkit/vite-plugin": "0.26.1",
+    "@foldkit/devtools-mcp": "0.24.1",
+    "@foldkit/oxlint-plugin": "0.15.2",
     "@types/node": "26.4.0",
     "happy-dom": "^20.14.5",
     "oxfmt": "^0.66.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",