create-foldkit-app 0.27.3 → 0.28.0

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

@@ -0,0 +1,120 @@
+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 { Message as TabsMessage } from '@foldkit/ui/tabs'
+
+import { FetchPostDetail, FetchStats, Message, update, view } from './main'
+import {
+  FETCHED_AT,
+  cachedFirstPostModel,
+  firstPostDetail,
+  fixtureStats,
+  loadedPostsModel,
+  loadingPostsModel,
+} from './main.fixtures'
+
+const resolveFocusTab = Command.resolve(
+  Tabs.FocusTab,
+  TabsMessage.CompletedFocusTab(),
+)
+
+describe('view', () => {
+  test('posts load into clickable rows with an Invalidate button', () => {
+    scene(
+      { update, view },
+      given(loadingPostsModel),
+      expect(text('Loading posts...')).toExist(),
+      expect(role('button', { name: 'Invalidate' })).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(FetchPostDetail({ postId: 'first-post' })),
+      Command.resolve(
+        FetchPostDetail,
+        Message.SettledFetchPostDetail({
+          postId: 'first-post',
+          result: Result.succeed({
+            detail: 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('a cached post shows the Cached badge and revisits skip 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 detail fetch shows the error with a Retry button', () => {
+    scene(
+      { update, view },
+      given(loadedPostsModel),
+      click(role('button', { name: /First Post/ })),
+      Command.resolve(
+        FetchPostDetail,
+        Message.SettledFetchPostDetail({
+          postId: 'first-post',
+          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(FetchStats()),
+      Command.resolve(
+        FetchStats,
+        Message.SettledFetchStats({
+          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/src/story.test.ts

@@ -0,0 +1,288 @@
+import { HashMap, Option, Result } from 'effect'
+import { Command, given, message, model, story } from 'foldkit/story'
+import { expect, test } from 'vitest'
+
+import { Tabs } from '@foldkit/ui'
+import { Message as TabsMessage } from '@foldkit/ui/tabs'
+
+import {
+  FetchPostDetail,
+  FetchPosts,
+  FetchStats,
+  Message,
+  type Model,
+  PostDetailData,
+  PostsData,
+  StatsData,
+  update,
+} from './main'
+import {
+  FETCHED_AT,
+  firstPostDetail,
+  fixturePosts,
+  fixtureStats,
+  loadedPostsModel,
+  loadedStatsModel,
+} from './main.fixtures'
+
+const postDetailTag = (model: Model, postId: string): string =>
+  HashMap.get(model.postDetailById, postId).pipe(
+    Option.map(postDetail => postDetail._tag),
+    Option.getOrElse(() => 'Missing'),
+  )
+
+const selectedPostsTab = Message.GotTabsMessage({
+  message: TabsMessage.SelectedTab({ index: 0, value: 'Posts' }),
+})
+
+const selectedStatsTab = Message.GotTabsMessage({
+  message: TabsMessage.SelectedTab({ index: 1, value: 'Stats' }),
+})
+
+const resolveFocusTab = Command.resolve(
+  Tabs.FocusTab,
+  TabsMessage.CompletedFocusTab(),
+)
+
+test('first visit to the Stats tab fetches stats', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(selectedStatsTab),
+    model(model => {
+      expect(model.activeTab).toBe('Stats')
+      expect(model.stats._tag).toBe('Loading')
+    }),
+    resolveFocusTab,
+    Command.resolve(
+      FetchStats,
+      Message.SettledFetchStats({
+        result: Result.succeed({ stats: fixtureStats, fetchedAt: FETCHED_AT }),
+      }),
+    ),
+    model(model => {
+      expect(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(model.stats._tag).toBe('Success')
+    }),
+  )
+})
+
+test('a revalidation tick keeps stale stats on screen while refetching', () => {
+  story(
+    update,
+    given(loadedStatsModel),
+    message(Message.TickedRevalidateStats()),
+    model(model => {
+      expect(model.stats._tag).toBe('Refreshing')
+      if (model.stats._tag === 'Refreshing') {
+        expect(model.stats.data.stats).toEqual(fixtureStats)
+      }
+    }),
+    Command.resolve(
+      FetchStats,
+      Message.SettledFetchStats({
+        result: Result.succeed({
+          stats: { ...fixtureStats, activeUsers: 99 },
+          fetchedAt: FETCHED_AT + 5000,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(model.stats._tag).toBe('Success')
+      if (model.stats._tag === 'Success') {
+        expect(model.stats.data.stats.activeUsers).toBe(99)
+      }
+    }),
+  )
+})
+
+test('a failed refresh keeps the stale stats on screen with the error', () => {
+  story(
+    update,
+    given(loadedStatsModel),
+    message(Message.TickedRevalidateStats()),
+    Command.resolve(
+      FetchStats,
+      Message.SettledFetchStats({
+        result: Result.fail('The server is down.'),
+      }),
+    ),
+    model(model => {
+      expect(model.stats._tag).toBe('Stale')
+      if (model.stats._tag === 'Stale') {
+        expect(model.stats.data.stats).toEqual(fixtureStats)
+        expect(model.stats.error).toBe('The server is down.')
+      }
+    }),
+  )
+})
+
+test('refresh clicks during an in-flight fetch are deduplicated', () => {
+  story(
+    update,
+    given({ ...loadedStatsModel, stats: StatsData.Loading() }),
+    message(Message.ClickedRefreshStats()),
+    Command.expectNone(),
+  )
+})
+
+test('a revalidation tick during a refresh is deduplicated', () => {
+  story(
+    update,
+    given({
+      ...loadedStatsModel,
+      stats: StatsData.Refreshing({
+        data: { stats: fixtureStats, fetchedAt: FETCHED_AT },
+      }),
+    }),
+    message(Message.TickedRevalidateStats()),
+    Command.expectNone(),
+  )
+})
+
+test('invalidating posts refetches while keeping the current list', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(Message.ClickedInvalidatePosts()),
+    model(model => {
+      expect(model.posts._tag).toBe('Refreshing')
+      if (model.posts._tag === 'Refreshing') {
+        expect(model.posts.data.posts).toEqual(fixturePosts)
+      }
+    }),
+    Command.resolve(
+      FetchPosts,
+      Message.SettledFetchPosts({
+        result: Result.succeed({
+          posts: fixturePosts,
+          fetchedAt: FETCHED_AT + 1000,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(model.posts._tag).toBe('Success')
+    }),
+  )
+})
+
+test('retrying failed posts shows the loading state and refetches', () => {
+  story(
+    update,
+    given({
+      ...loadedPostsModel,
+      posts: PostsData.Failure({ error: 'The server is down.' }),
+    }),
+    message(Message.ClickedRetryPosts()),
+    model(model => {
+      expect(model.posts._tag).toBe('Loading')
+    }),
+    Command.resolve(
+      FetchPosts,
+      Message.SettledFetchPosts({
+        result: Result.succeed({ posts: fixturePosts, fetchedAt: FETCHED_AT }),
+      }),
+    ),
+    model(model => {
+      expect(model.posts._tag).toBe('Success')
+    }),
+  )
+})
+
+test('opening a post fetches it once and serves revisits from the Model', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    model(model => {
+      expect(postDetailTag(model, 'first-post')).toBe('Loading')
+    }),
+    Command.resolve(
+      FetchPostDetail,
+      Message.SettledFetchPostDetail({
+        postId: 'first-post',
+        result: Result.succeed({
+          detail: firstPostDetail,
+          fetchedAt: FETCHED_AT,
+        }),
+      }),
+    ),
+    message(Message.ClickedBackToPosts()),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    Command.expectNone(),
+    model(model => {
+      expect(postDetailTag(model, 'first-post')).toBe('Success')
+      expect(model.maybeSelectedPostId).toEqual(Option.some('first-post'))
+    }),
+  )
+})
+
+test('a failed post detail fetch lands in Failure and retry refetches', () => {
+  story(
+    update,
+    given(loadedPostsModel),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    Command.resolve(
+      FetchPostDetail,
+      Message.SettledFetchPostDetail({
+        postId: 'first-post',
+        result: Result.fail('The connection dropped.'),
+      }),
+    ),
+    model(model => {
+      expect(postDetailTag(model, 'first-post')).toBe('Failure')
+    }),
+    message(Message.ClickedRetryPostDetail({ postId: 'first-post' })),
+    model(model => {
+      expect(postDetailTag(model, 'first-post')).toBe('Loading')
+    }),
+    Command.resolve(
+      FetchPostDetail,
+      Message.SettledFetchPostDetail({
+        postId: 'first-post',
+        result: Result.succeed({
+          detail: firstPostDetail,
+          fetchedAt: FETCHED_AT,
+        }),
+      }),
+    ),
+    model(model => {
+      expect(postDetailTag(model, 'first-post')).toBe('Success')
+    }),
+  )
+})
+
+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.' }),
+      ),
+    }),
+    message(Message.ClickedPost({ postId: 'first-post' })),
+    Command.expectNone(),
+    model(model => {
+      expect(postDetailTag(model, 'first-post')).toBe('Failure')
+      expect(model.maybeSelectedPostId).toEqual(Option.some('first-post'))
+    }),
+  )
+})

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

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

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

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

package/dist/templates/examples/auth/package.json

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

package/dist/templates/examples/auth/src/command.ts

@@ -0,0 +1,49 @@
+import { Console, Effect, Schema as S } from 'effect'
+import { KeyValueStore } from 'effect/unstable/persistence'
+import { Command } from 'foldkit'
+
+import { BrowserKeyValueStore } from '@effect/platform-browser'
+
+import { SESSION_STORAGE_KEY } from './constant'
+import { Session } from './domain/session'
+import { Message } from './message'
+
+export const SaveSession = Command.define('SaveSession', {
+  args: { session: Session },
+  messages: [Message.SucceededSaveSession, Message.FailedSaveSession],
+  execute: ({ session }) =>
+    Effect.gen(function* () {
+      const store = yield* KeyValueStore.KeyValueStore
+      yield* store.set(
+        SESSION_STORAGE_KEY,
+        S.encodeSync(S.fromJsonString(Session))(session),
+      )
+      return Message.SucceededSaveSession()
+    }).pipe(
+      Effect.catch(error =>
+        Effect.succeed(Message.FailedSaveSession({ error: String(error) })),
+      ),
+      Effect.provide(BrowserKeyValueStore.layerLocalStorage),
+    ),
+})
+
+export const ClearSession = Command.define('ClearSession', {
+  messages: [Message.SucceededClearSession, Message.FailedClearSession],
+  execute: Effect.gen(function* () {
+    const store = yield* KeyValueStore.KeyValueStore
+    yield* store.remove(SESSION_STORAGE_KEY)
+    return Message.SucceededClearSession()
+  }).pipe(
+    Effect.catch(error =>
+      Effect.succeed(Message.FailedClearSession({ error: String(error) })),
+    ),
+    Effect.provide(BrowserKeyValueStore.layerLocalStorage),
+  ),
+})
+
+export const LogError = Command.define('LogError', {
+  args: { entries: S.Array(S.Unknown) },
+  messages: [Message.CompletedLogError],
+  execute: ({ entries }) =>
+    Console.error(...entries).pipe(Effect.as(Message.CompletedLogError())),
+})

package/dist/templates/examples/auth/src/constant.ts

@@ -0,0 +1 @@
+export const SESSION_STORAGE_KEY = 'auth_session'

package/dist/templates/examples/auth/src/domain/session.ts

@@ -0,0 +1,9 @@
+import { Schema as S } from 'effect'
+
+export const Session = S.Struct({
+  userId: S.String,
+  email: S.String,
+  name: S.String,
+})
+
+export type Session = typeof Session.Type

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

@@ -0,0 +1,25 @@
+import { Runtime } from 'foldkit'
+
+import { Flags, flags, init } from './main'
+import { Message } from './message'
+import { Model } from './model'
+import { update } from './update'
+import { view } from './view'
+
+const application = Runtime.makeApplication({
+  Model,
+  Flags,
+  init,
+  update,
+  view,
+  container: document.getElementById('root'),
+  routing: {
+    onUrlRequest: request => Message.ClickedLink({ request }),
+    onUrlChange: url => Message.ChangedUrl({ url }),
+  },
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.run(application, { flags })

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

@@ -0,0 +1,75 @@
+import { Effect, Match as M, Option, Schema as S } from 'effect'
+import { KeyValueStore } from 'effect/unstable/persistence'
+import { Command, Runtime } from 'foldkit'
+import { Url } from 'foldkit/url'
+
+import { BrowserKeyValueStore } from '@effect/platform-browser'
+
+import { SESSION_STORAGE_KEY } from './constant'
+import { Session } from './domain/session'
+import { Message } from './message'
+import { LoggedIn, LoggedOut, Model } from './model'
+import { DashboardRoute, LoginRoute, urlToAppRoute } from './route'
+import { RedirectToDashboard, RedirectToLogin } from './update'
+
+// FLAGS
+
+export const Flags = S.Struct({
+  maybeSession: S.Option(Session),
+})
+
+export const flags: Effect.Effect<Flags> = Effect.gen(function* () {
+  const store = yield* KeyValueStore.KeyValueStore
+  const sessionJson = yield* Effect.fromOption(
+    Option.fromNullishOr(yield* store.get(SESSION_STORAGE_KEY)),
+  )
+
+  const decodeSession = S.decodeEffect(S.fromJsonString(Session))
+  const session = yield* decodeSession(sessionJson)
+
+  return Flags.make({ maybeSession: Option.some(session) })
+}).pipe(
+  Effect.catch(() =>
+    Effect.succeed(Flags.make({ maybeSession: Option.none() })),
+  ),
+  Effect.provide(BrowserKeyValueStore.layerLocalStorage),
+)
+
+export type Flags = typeof Flags.Type
+
+// INIT
+
+type InitReturn = [Model, ReadonlyArray<Command.Command<Message>>]
+const withInitReturn = M.withReturnType<InitReturn>()
+
+export const init: Runtime.RoutingApplicationInit<Model, Message, Flags> = (
+  flags: Flags,
+  url: Url,
+): InitReturn => {
+  const route = urlToAppRoute(url)
+
+  return Option.match(flags.maybeSession, {
+    onNone: () =>
+      M.value(route).pipe(
+        withInitReturn,
+        M.tag('Home', 'Login', 'NotFound', route => [
+          LoggedOut.init(route),
+          [],
+        ]),
+        M.orElse(() => [LoggedOut.init(LoginRoute()), [RedirectToLogin()]]),
+      ),
+
+    onSome: session =>
+      M.value(route).pipe(
+        withInitReturn,
+        M.tag('Dashboard', 'Settings', 'NotFound', route => [
+          LoggedIn.init(route, session),
+          [],
+        ]),
+        M.orElse(() => [
+          LoggedIn.init(DashboardRoute(), session),
+          [RedirectToDashboard()],
+        ]),
+      ),
+  })
+}

package/dist/templates/examples/auth/src/message.ts

@@ -0,0 +1,22 @@
+import { Schema as S } from 'effect'
+import { defineMessageUnion } from 'foldkit/message'
+import { UrlRequest } from 'foldkit/navigation'
+import { Url } from 'foldkit/url'
+
+import { LoggedIn, LoggedOut } from './page'
+
+export const Message = defineMessageUnion({
+  CompletedNavigateInternal: {},
+  CompletedLoadExternal: {},
+  CompletedLogError: {},
+  ClickedLink: { request: UrlRequest },
+  ChangedUrl: { url: Url },
+  SucceededSaveSession: {},
+  FailedSaveSession: { error: S.String },
+  SucceededClearSession: {},
+  FailedClearSession: { error: S.String },
+  GotLoggedOutMessage: { message: LoggedOut.Message },
+  GotLoggedInMessage: { message: LoggedIn.Message },
+})
+
+export type Message = typeof Message.Type

package/dist/templates/examples/auth/src/model.ts

@@ -0,0 +1,9 @@
+import { Schema as S } from 'effect'
+
+import { LoggedIn, LoggedOut } from './page'
+
+export const Model = S.Union([LoggedOut.Model, LoggedIn.Model])
+
+export type Model = typeof Model.Type
+
+export { LoggedOut, LoggedIn }

package/dist/templates/examples/auth/src/notFoundView.ts

@@ -0,0 +1,25 @@
+import { Html, HtmlBuilder } from 'foldkit/html'
+
+export const notFoundView = <Message>(
+  path: string,
+  backLinkHref: string,
+  backLinkText: string,
+  h: HtmlBuilder<Message>,
+): Html =>
+  h.div(
+    [h.Class('max-w-4xl mx-auto px-4 text-center')],
+    [
+      h.h1(
+        [h.Class('text-4xl font-bold text-red-600 mb-6')],
+        ['404 - Page Not Found'],
+      ),
+      h.p(
+        [h.Class('text-lg text-gray-600 mb-4')],
+        [`The path "${path}" was not found.`],
+      ),
+      h.a(
+        [h.Href(backLinkHref), h.Class('text-blue-500 hover:underline')],
+        [backLinkText],
+      ),
+    ],
+  )

package/dist/templates/examples/auth/src/page/index.ts

@@ -0,0 +1,2 @@
+export * as LoggedOut from './loggedOut'
+export * as LoggedIn from './loggedIn'

package/dist/templates/examples/auth/src/page/loggedIn/index.ts

@@ -0,0 +1,4 @@
+export { Model, init } from './model'
+export { Message, type OutMessage } from './message'
+export { update } from './update'
+export { view } from './view'

package/dist/templates/examples/auth/src/page/loggedIn/message.ts

@@ -0,0 +1,17 @@
+import { defineMessageUnion } from 'foldkit/message'
+
+// MESSAGE
+
+export const Message = defineMessageUnion({
+  ClickedLogout: {},
+})
+
+export type Message = typeof Message.Type
+
+// OUT MESSAGE
+
+export const OutMessage = defineMessageUnion({
+  RequestedLogout: {},
+})
+
+export type OutMessage = typeof OutMessage.Type