create-foldkit-app 0.33.0 → 0.34.0-canary.4e90e99d9ad3

package/README.md

@@ -1,6 +1,6 @@
 # create-foldkit-app
 
-Scaffolding CLI for new Foldkit applications. Creates a ready-to-run project with Vite, Tailwind CSS, TypeScript, [`@foldkit/vite-plugin`](https://www.npmjs.com/package/@foldkit/vite-plugin) for hot reloading with Model preservation, your choice of rendering mode, and a starter example for SPA scaffolds.
+Scaffolding CLI for new Foldkit applications. Creates a ready-to-run project with Vite, Tailwind CSS, TypeScript, [`@foldkit/vite-plugin`](https://www.npmjs.com/package/@foldkit/vite-plugin) for state-preserving live reload, your choice of rendering mode, and a starter example for SPA scaffolds.
 
 ## Usage
 
@@ -18,11 +18,11 @@ The CLI prompts you for a project name, rendering mode, starter example, and pac
 
 ## Rendering
 
-| Mode  | Description                                                                                                                                                                    |
-| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `spa` | Render entirely in the browser. Starts from your choice of starter example below.                                                                                              |
-| `ssg` | Prerender routes to static HTML at build time, then hydrate in the browser. Scaffolds a small routed app with a server entry and a prerender script.                           |
-| `ssr` | Render each request on a Node server, then hydrate in the browser. Scaffolds a counter whose Flags come from the request, plus an Effect HttpServer host and a `start` script. |
+| Mode  | Description                                                                                                                                                                                  |
+| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `spa` | Render entirely in the browser. Starts from your choice of starter example below.                                                                                                            |
+| `ssg` | Prerender routes to static HTML at build time, then hydrate in the browser. Scaffolds a small routed app with a server entry. One `vite build` writes every route.                           |
+| `ssr` | Render each request, then hydrate in the browser. Scaffolds a counter whose Flags come from the request. One `vite build` emits a Web `fetch` handler; `start` runs `node scripts/serve.ts`. |
 
 The starter examples apply to `spa` rendering. The `ssg` and `ssr` modes scaffold their own starter apps.
 

package/dist/index.js

@@ -14,7 +14,7 @@ const nameSchema = Schema.String.pipe(Schema.check(Schema.makeFilter(value => Op
     onSome: message => message,
 }))));
 const name = Flag.string('name').pipe(Flag.withAlias('n'), Flag.withDescription('The name of the project to create'), Flag.withSchema(nameSchema), Flag.optional);
-const rendering = Flag.choice('rendering', RENDERING_VALUES).pipe(Flag.withAlias('r'), Flag.withDescription('How the application renders: spa renders entirely in the browser, ssg prerenders routes to static HTML at build time, ssr renders each request on a Node server'), Flag.optional);
+const rendering = Flag.choice('rendering', RENDERING_VALUES).pipe(Flag.withAlias('r'), Flag.withDescription('How the application renders: spa renders entirely in the browser, ssg prerenders routes to static HTML at build time, ssr renders each request then hydrates'), Flag.optional);
 const example = Flag.choice('example', EXAMPLE_VALUES).pipe(Flag.withAlias('e'), Flag.withDescription("The example application to start from with spa rendering. Run with no flags for an interactive picker that shows each example's description."), Flag.optional);
 const packageManager = Flag.choice('package-manager', [
     'pnpm',

package/dist/rendering.js

@@ -14,7 +14,7 @@ export const renderings = [
     {
         value: 'ssr',
         title: 'SSR',
-        description: 'Render each request on a Node server, then hydrate in the browser',
+        description: 'Render each request, then hydrate in the browser',
     },
 ];
 export const Scaffold = Data.taggedEnum();

package/dist/templates/examples/api-cache/src/{main.fixtures.ts → main.fixture.ts}

@@ -1,4 +1,5 @@
 import { HashMap, Option } from 'effect'
+import { evo } from 'foldkit/struct'
 
 import { Tabs } from '@foldkit/ui'
 
@@ -43,28 +44,28 @@ export const loadingPostsModel: Model = {
   stats: StatsData.Idle(),
 }
 
-export const loadedPostsModel: Model = {
-  ...loadingPostsModel,
-  posts: PostsData.Success({
-    data: { posts: fixturePosts, fetchedAt: FETCHED_AT },
-  }),
-}
-
-export const cachedFirstPostModel: Model = {
-  ...loadedPostsModel,
-  postDetailById: HashMap.set(
-    HashMap.empty(),
-    'first-post',
-    PostDetailData.Success({
-      data: { detail: firstPostDetail, fetchedAt: FETCHED_AT },
+export const loadedPostsModel: Model = evo(loadingPostsModel, {
+  posts: () =>
+    PostsData.Success({
+      data: { posts: fixturePosts, fetchedAt: FETCHED_AT },
     }),
-  ),
-}
+})
 
-export const loadedStatsModel: Model = {
-  ...loadedPostsModel,
-  activeTab: 'Stats',
-  stats: StatsData.Success({
-    data: { stats: fixtureStats, fetchedAt: FETCHED_AT },
-  }),
-}
+export const cachedFirstPostModel: Model = evo(loadedPostsModel, {
+  postDetailById: () =>
+    HashMap.set(
+      HashMap.empty(),
+      'first-post',
+      PostDetailData.Success({
+        data: { detail: firstPostDetail, fetchedAt: FETCHED_AT },
+      }),
+    ),
+})
+
+export const loadedStatsModel: Model = evo(loadedPostsModel, {
+  activeTab: () => 'Stats',
+  stats: () =>
+    StatsData.Success({
+      data: { stats: fixtureStats, fetchedAt: FETCHED_AT },
+    }),
+})

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

@@ -21,7 +21,7 @@ import {
   fixtureStats,
   loadedPostsModel,
   loadingPostsModel,
-} from './main.fixtures'
+} from './main.fixture'
 
 const resolveFocusTab = Command.resolve(
   Tabs.FocusTab,

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

@@ -1,5 +1,6 @@
 import { HashMap, Option, Result } from 'effect'
 import { Command, given, message, model, story } from 'foldkit/story'
+import { evo } from 'foldkit/struct'
 import { expect, test } from 'vitest'
 
 import { Tabs } from '@foldkit/ui'
@@ -22,7 +23,7 @@ import {
   fixtureStats,
   loadedPostsModel,
   loadedStatsModel,
-} from './main.fixtures'
+} from './main.fixture'
 
 const postDetailTag = (model: Model, postId: string): string =>
   HashMap.get(model.postDetailById, postId).pipe(
@@ -96,7 +97,7 @@ test('a revalidation tick keeps stale stats on screen while refetching', () => {
       FetchStats,
       Message.SettledFetchStats({
         result: Result.succeed({
-          stats: { ...fixtureStats, activeUsers: 99 },
+          stats: evo(fixtureStats, { activeUsers: () => 99 }),
           fetchedAt: FETCHED_AT + 5000,
         }),
       }),
@@ -134,7 +135,7 @@ test('a failed refresh keeps the stale stats on screen with the error', () => {
 test('refresh clicks during an in-flight fetch are deduplicated', () => {
   story(
     update,
-    given({ ...loadedStatsModel, stats: StatsData.Loading() }),
+    given(evo(loadedStatsModel, { stats: () => StatsData.Loading() })),
     message(Message.ClickedRefreshStats()),
     Command.expectNone(),
   )
@@ -143,12 +144,14 @@ test('refresh clicks during an in-flight fetch are deduplicated', () => {
 test('a revalidation tick during a refresh is deduplicated', () => {
   story(
     update,
-    given({
-      ...loadedStatsModel,
-      stats: StatsData.Refreshing({
-        data: { stats: fixtureStats, fetchedAt: FETCHED_AT },
+    given(
+      evo(loadedStatsModel, {
+        stats: () =>
+          StatsData.Refreshing({
+            data: { stats: fixtureStats, fetchedAt: FETCHED_AT },
+          }),
       }),
-    }),
+    ),
     message(Message.TickedRevalidateStats()),
     Command.expectNone(),
   )
@@ -183,10 +186,11 @@ test('invalidating posts refetches while keeping the current list', () => {
 test('retrying failed posts shows the loading state and refetches', () => {
   story(
     update,
-    given({
-      ...loadedPostsModel,
-      posts: PostsData.Failure({ error: 'The server is down.' }),
-    }),
+    given(
+      evo(loadedPostsModel, {
+        posts: () => PostsData.Failure({ error: 'The server is down.' }),
+      }),
+    ),
     message(Message.ClickedRetryPosts()),
     model(model => {
       expect(model.posts._tag).toBe('Loading')
@@ -269,14 +273,16 @@ test('a failed post detail fetch lands in Failure and retry refetches', () => {
 test('revisiting a post with a cached failure shows it without refetching', () => {
   story(
     update,
-    given({
-      ...loadedPostsModel,
-      postDetailById: HashMap.set(
-        HashMap.empty(),
-        'first-post',
-        PostDetailData.Failure({ error: 'The connection dropped.' }),
-      ),
-    }),
+    given(
+      evo(loadedPostsModel, {
+        postDetailById: () =>
+          HashMap.set(
+            HashMap.empty(),
+            'first-post',
+            PostDetailData.Failure({ error: 'The connection dropped.' }),
+          ),
+      }),
+    ),
     message(Message.ClickedPost({ postId: 'first-post' })),
     Command.expectNone(),
     model(model => {

package/dist/templates/examples/auth/src/page/loggedOut/page/login.scene.test.ts

@@ -11,21 +11,14 @@ import {
   type,
   within,
 } from 'foldkit/scene'
+import { evo } from 'foldkit/struct'
 import { describe, test } from 'vitest'
 
-import {
-  Message,
-  Model,
-  SimulateAuthRequest,
-  initModel,
-  update,
-  view,
-} from './login'
+import { Message, SimulateAuthRequest, initModel, update, view } from './login'
 
-const validModel = Model.make({
-  ...initModel(),
-  email: Valid({ value: 'alice@example.com' }),
-  password: Valid({ value: 'password' }),
+const validModel = evo(initModel(), {
+  email: () => Valid({ value: 'alice@example.com' }),
+  password: () => Valid({ value: 'password' }),
 })
 
 const heading = role('heading', { name: 'Sign In' })

package/dist/templates/examples/auth/src/page/loggedOut/page/login.story.test.ts

@@ -8,21 +8,20 @@ import {
   model,
   story,
 } from 'foldkit/story'
+import { evo } from 'foldkit/struct'
 import { describe, expect, test } from 'vitest'
 
 import {
   Message,
-  Model,
   OutMessage,
   SimulateAuthRequest,
   initModel,
   update,
 } from './login'
 
-const validModel = Model.make({
-  ...initModel(),
-  email: Valid({ value: 'alice@example.com' }),
-  password: Valid({ value: 'password' }),
+const validModel = evo(initModel(), {
+  email: () => Valid({ value: 'alice@example.com' }),
+  password: () => Valid({ value: 'password' }),
 })
 
 const aliceSession = { userId: '1', email: 'alice@example.com', name: 'alice' }

package/dist/templates/examples/auth/src/page/loggedOut/page/login.ts

@@ -188,6 +188,7 @@ const fieldView = (
       placeholder,
       onInput: onUpdate,
       isInvalid: field._tag === 'Invalid',
+      hasDescription: field._tag === 'Invalid',
       toView: attributes =>
         h.div(
           [],

package/dist/templates/examples/auth/src/scene.test.ts

@@ -8,6 +8,7 @@ import {
   submit,
   text,
 } from 'foldkit/scene'
+import { evo } from 'foldkit/struct'
 import { describe, test } from 'vitest'
 
 import { SaveSession } from './command'
@@ -16,7 +17,6 @@ import { Message } from './message'
 import { LoggedOut } from './model'
 import {
   Message as LoginMessage,
-  Model as LoginModel,
   SimulateAuthRequest,
   initModel as initLoginModel,
 } from './page/loggedOut/page/login'
@@ -26,10 +26,9 @@ import { view } from './view'
 
 const validModel = LoggedOut.Model({
   route: AppRoute.Login(),
-  loginModel: LoginModel.make({
-    ...initLoginModel(),
-    email: Valid({ value: 'alice@example.com' }),
-    password: Valid({ value: 'password' }),
+  loginModel: evo(initLoginModel(), {
+    email: () => Valid({ value: 'alice@example.com' }),
+    password: () => Valid({ value: 'password' }),
   }),
 })
 

package/dist/templates/examples/canvas-art/src/scene.test.ts

@@ -1,4 +1,5 @@
 import { click, expect, given, role, scene, text } from 'foldkit/scene'
+import { evo } from 'foldkit/struct'
 import { describe, test } from 'vitest'
 
 import { type Model, update, view } from './main'
@@ -33,15 +34,14 @@ describe('view', () => {
   })
 
   test('the ball count reflects spawned balls in the Model', () => {
-    const populatedModel: Model = {
-      ...emptyModel,
-      balls: [
+    const populatedModel: Model = evo(emptyModel, {
+      balls: () => [
         { id: 0, x: 10, y: 20, vx: 1, vy: 1, radius: 8, color: '#ff2d55' },
         { id: 1, x: 30, y: 40, vx: -1, vy: 1, radius: 12, color: '#5ac8fa' },
         { id: 2, x: 50, y: 60, vx: 1, vy: -1, radius: 16, color: '#34c759' },
       ],
-      nextId: 3,
-    }
+      nextId: () => 3,
+    })
 
     scene(
       { update, view },
@@ -51,13 +51,12 @@ describe('view', () => {
   })
 
   test('Clear empties the rendered ball count', () => {
-    const populatedModel: Model = {
-      ...emptyModel,
-      balls: [
+    const populatedModel: Model = evo(emptyModel, {
+      balls: () => [
         { id: 0, x: 10, y: 20, vx: 1, vy: 1, radius: 8, color: '#ff2d55' },
       ],
-      nextId: 1,
-    }
+      nextId: () => 1,
+    })
 
     scene(
       { update, view },

package/dist/templates/examples/canvas-art/src/story.test.ts

@@ -1,4 +1,5 @@
 import { Command, given, message, model, story } from 'foldkit/story'
+import { evo } from 'foldkit/struct'
 import { describe, expect, test } from 'vitest'
 
 import { GenerateBall, Message, type Model, update } from './main'
@@ -9,14 +10,13 @@ const emptyModel: Model = {
   isRunning: true,
 }
 
-const populatedModel: Model = {
-  ...emptyModel,
-  balls: [
+const populatedModel: Model = evo(emptyModel, {
+  balls: () => [
     { id: 0, x: 100, y: 100, vx: 50, vy: 50, radius: 10, color: '#ff2d55' },
     { id: 1, x: 200, y: 200, vx: -50, vy: -50, radius: 15, color: '#5ac8fa' },
   ],
-  nextId: 2,
-}
+  nextId: () => 2,
+})
 
 describe('update', () => {
   describe('spawning balls', () => {
@@ -97,9 +97,8 @@ describe('update', () => {
     })
 
     test('bounces a ball off the canvas edges, flipping its velocity', () => {
-      const movingRightModel: Model = {
-        ...emptyModel,
-        balls: [
+      const movingRightModel: Model = evo(emptyModel, {
+        balls: () => [
           {
             id: 0,
             x: 595,
@@ -110,8 +109,8 @@ describe('update', () => {
             color: '#fff',
           },
         ],
-        nextId: 1,
-      }
+        nextId: () => 1,
+      })
 
       story(
         update,

package/dist/templates/examples/charting/src/{main.fixtures.ts → main.fixture.ts}

@@ -1,4 +1,5 @@
 import { Option } from 'effect'
+import { evo } from 'foldkit/struct'
 
 import { RadioGroup } from '@foldkit/ui'
 
@@ -119,10 +120,9 @@ export const loadingModel = Model.make({
   maybeSelectedDatumId: Option.none(),
 })
 
-export const readyModel = Model.make({
-  ...loadingModel,
-  telemetry: TelemetryAsyncData.Success({ data: sampleTelemetry }),
-  maybeChartHostId: Option.some('test-chart-host'),
+export const readyModel = evo(loadingModel, {
+  telemetry: () => TelemetryAsyncData.Success({ data: sampleTelemetry }),
+  maybeChartHostId: () => Option.some('test-chart-host'),
 })
 
 export const mockGitHubRepository = {

package/dist/templates/examples/charting/src/scene.test.ts

@@ -9,12 +9,13 @@ import {
   scene,
   text,
 } from 'foldkit/scene'
+import { evo } from 'foldkit/struct'
 import { describe, test } from 'vitest'
 
 import { RadioGroup } from '@foldkit/ui'
 
 import { SyncChart } from './command'
-import { loadingModel, readyModel, sampleTelemetry } from './main.fixtures'
+import { loadingModel, readyModel, sampleTelemetry } from './main.fixture'
 import { Message } from './message'
 import { TelemetryAsyncData } from './model'
 import { update } from './update'
@@ -77,10 +78,12 @@ describe('view', () => {
   test('refreshing state keeps the dashboard visible', () => {
     scene(
       { update, view },
-      given({
-        ...readyModel,
-        telemetry: TelemetryAsyncData.Refreshing({ data: sampleTelemetry }),
-      }),
+      given(
+        evo(readyModel, {
+          telemetry: () =>
+            TelemetryAsyncData.Refreshing({ data: sampleTelemetry }),
+        }),
+      ),
       acknowledgeChartMount,
       acknowledgeChartSync,
       expect(text('Refreshing public data')).toExist(),
@@ -91,10 +94,11 @@ describe('view', () => {
   test('failure without stale data shows retry', () => {
     scene(
       { update, view },
-      given({
-        ...loadingModel,
-        telemetry: TelemetryAsyncData.Failure({ error: 'offline' }),
-      }),
+      given(
+        evo(loadingModel, {
+          telemetry: () => TelemetryAsyncData.Failure({ error: 'offline' }),
+        }),
+      ),
       expect(label('Telemetry failed')).toExist(),
       expect(role('button', { name: 'Retry' })).toExist(),
     )

package/dist/templates/examples/charting/src/story.test.ts

@@ -1,4 +1,5 @@
 import { Command, given, message, model, story } from 'foldkit/story'
+import { evo } from 'foldkit/struct'
 import { expect, test } from 'vitest'
 
 import { RadioGroup } from '@foldkit/ui'
@@ -10,7 +11,7 @@ import {
   chartModes,
   packageIds,
 } from './domain'
-import { loadingModel, readyModel, sampleTelemetry } from './main.fixtures'
+import { loadingModel, readyModel, sampleTelemetry } from './main.fixture'
 import { Message } from './message'
 import { TelemetryAsyncData } from './model'
 import { update } from './update'
@@ -101,10 +102,12 @@ test('refreshing with data keeps the old dashboard while fetching', () => {
 test('a failed refresh preserves stale data in the stale state', () => {
   story(
     update,
-    given({
-      ...readyModel,
-      telemetry: TelemetryAsyncData.Refreshing({ data: sampleTelemetry }),
-    }),
+    given(
+      evo(readyModel, {
+        telemetry: () =>
+          TelemetryAsyncData.Refreshing({ data: sampleTelemetry }),
+      }),
+    ),
     message(Message.FailedFetchTelemetry({ error: 'rate limited' })),
     model(model => {
       expect(model.telemetry._tag).toBe('Stale')

package/dist/templates/examples/charting/src/telemetry.test.ts

@@ -7,7 +7,7 @@ import {
   mockGitHubRepository,
   mockNpmDownloads,
   mockNpmPackument,
-} from './main.fixtures'
+} from './main.fixture'
 import { NpmApiLive } from './npmApi'
 import { fetchRawTelemetry, transformTelemetry } from './telemetry'
 

package/dist/templates/examples/embedding/src/scene.test.ts

@@ -1,4 +1,5 @@
 import { Command, click, expect, given, role, scene, text } from 'foldkit/scene'
+import { evo } from 'foldkit/struct'
 import { describe, test } from 'vitest'
 
 import { Message, type Model, ReportCount, update, view } from './main'
@@ -19,7 +20,7 @@ describe('view', () => {
   test('clicking the advance button moves the count by the step', () => {
     scene(
       { update, view },
-      given({ ...initialModel, step: 4 }),
+      given(evo(initialModel, { step: () => 4 })),
       click(role('button', { name: 'Advance by 4' })),
       Command.resolve(ReportCount, Message.CompletedReportCount()),
       expect(text('14')).toExist(),

package/dist/templates/examples/embedding/src/story.test.ts

@@ -1,4 +1,5 @@
 import { Command, given, message, model, story } from 'foldkit/story'
+import { evo } from 'foldkit/struct'
 import { describe, expect, test } from 'vitest'
 
 import { Message, type Model, ReportCount, update } from './main'
@@ -10,7 +11,7 @@ describe('update', () => {
     test('Ticked advances the count by the step and reports it on the outbound port', () => {
       story(
         update,
-        given({ ...initialModel, step: 3 }),
+        given(evo(initialModel, { step: () => 3 })),
         message(Message.Ticked()),
         model(model => {
           expect(model.count).toBe(13)

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

@@ -299,6 +299,7 @@ const inputFieldView = (
       value: field.value,
       onInput: onUpdate,
       isInvalid: field._tag === 'Invalid',
+      hasDescription: field._tag === 'Validating' || field._tag === 'Invalid',
       type,
       toView: attributes =>
         h.div(
@@ -335,6 +336,7 @@ const textareaFieldView = (
       value: field.value,
       onInput: onUpdate,
       isInvalid: field._tag === 'Invalid',
+      hasDescription: field._tag === 'Validating' || field._tag === 'Invalid',
       toView: attributes =>
         h.div(
           [h.Class('mb-4')],

package/dist/templates/examples/form/src/scene.test.ts

@@ -10,6 +10,7 @@ import {
   submit,
   type,
 } from 'foldkit/scene'
+import { evo } from 'foldkit/struct'
 import { describe, test } from 'vitest'
 
 import {
@@ -57,10 +58,9 @@ describe('view', () => {
   })
 
   test('typing a well-formed email triggers async validation', () => {
-    const modelWithValidName = {
-      ...initialModel,
-      name: FieldValidation.Valid({ value: 'Alice' }),
-    }
+    const modelWithValidName = evo(initialModel, {
+      name: () => FieldValidation.Valid({ value: 'Alice' }),
+    })
 
     scene(
       { update, view },
@@ -101,11 +101,10 @@ describe('view', () => {
   })
 
   test('submit becomes enabled once name and email are valid', () => {
-    const validModel = {
-      ...initialModel,
-      name: FieldValidation.Valid({ value: 'Alice' }),
-      email: FieldValidation.Valid({ value: 'alice@example.com' }),
-    }
+    const validModel = evo(initialModel, {
+      name: () => FieldValidation.Valid({ value: 'Alice' }),
+      email: () => FieldValidation.Valid({ value: 'alice@example.com' }),
+    })
 
     scene(
       { update, view },
@@ -115,11 +114,10 @@ describe('view', () => {
   })
 
   test('submitting a valid form shows the loading label then a success banner', () => {
-    const validModel = {
-      ...initialModel,
-      name: FieldValidation.Valid({ value: 'Alice' }),
-      email: FieldValidation.Valid({ value: 'alice@example.com' }),
-    }
+    const validModel = evo(initialModel, {
+      name: () => FieldValidation.Valid({ value: 'Alice' }),
+      email: () => FieldValidation.Valid({ value: 'alice@example.com' }),
+    })
 
     scene(
       { update, view },
@@ -137,11 +135,10 @@ describe('view', () => {
   })
 
   test('a failed submission renders an error banner', () => {
-    const validModel = {
-      ...initialModel,
-      name: FieldValidation.Valid({ value: 'Alice' }),
-      email: FieldValidation.Valid({ value: 'alice@example.com' }),
-    }
+    const validModel = evo(initialModel, {
+      name: () => FieldValidation.Valid({ value: 'Alice' }),
+      email: () => FieldValidation.Valid({ value: 'alice@example.com' }),
+    })
 
     scene(
       { update, view },