create-foldkit-app 0.30.1 → 0.31.0

package/dist/templates/base/FOLDKIT.md

@@ -31,7 +31,9 @@ Replace it whenever the project upgrades its Foldkit packages. If `./repos/foldk
 - Foldkit is tightly coupled to the Effect ecosystem. Do not suggest solutions outside of Effect-TS.
 - Model fields must be Schema types (the model is a schema). Plain TypeScript types are fine elsewhere (function return types, local variables, etc.).
 - Use full names like `Message` (not `Msg`), and `withReturnType` (not `as const` or type casting).
-- Use `defineMessageUnion()` for Message unions, `ts()` for tagged structs (Model states, field validation), and `r()` for route schemas.
+- Declare every variant together: `defineMessageUnion()` for Messages, `defineTaggedUnion()` for other domain unions, and `defineRouteUnion()` for Routes.
+- Keep constructors on their union: `Message.ClickedSubmit()`, `FetchState.Ok({ data })`, and `AppRoute.Home()`.
+- Use `taggedStruct()` only when the variants cannot be declared together, such as a recursive union.
 - Push back on any direction that violates Elm Architecture principles: unidirectional data flow, messages as facts (not commands), model as single source of truth, side effects confined to commands. If a prompt suggests mutating state, imperative event handlers, or two-way bindings, flag the issue and propose the idiomatic Foldkit approach.
 - Never use `NoOp`. Every message must describe what happened. A command's result message is named from the command, not from the fact it reports, whether or not it carries a payload: `LockScroll` → `CompletedLockScroll`, `DetermineStartTime` → `CompletedDetermineStartTime` (never `DeterminedStartTime`).
 

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

@@ -9,7 +9,7 @@ import { SESSION_STORAGE_KEY } from './constant'
 import { Session, SessionJsonString } from './domain/session'
 import { Message } from './message'
 import { LoggedIn, LoggedOut, Model } from './model'
-import { DashboardRoute, LoginRoute, urlToAppRoute } from './route'
+import { AppRoute, urlToAppRoute } from './route'
 import { RedirectToDashboard, RedirectToLogin } from './update'
 
 // FLAGS
@@ -56,7 +56,7 @@ export const init: Runtime.RoutingApplicationInit<Model, Message, Flags> = (
           model: LoggedOut.init(route),
         })),
         M.orElse(() => ({
-          model: LoggedOut.init(LoginRoute()),
+          model: LoggedOut.init(AppRoute.Login()),
           commands: [RedirectToLogin()],
         })),
       ),
@@ -68,7 +68,7 @@ export const init: Runtime.RoutingApplicationInit<Model, Message, Flags> = (
           model: LoggedIn.init(route, session),
         })),
         M.orElse(() => ({
-          model: LoggedIn.init(DashboardRoute(), session),
+          model: LoggedIn.init(AppRoute.Dashboard(), session),
           commands: [RedirectToDashboard()],
         })),
       ),

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

@@ -1,11 +1,11 @@
-import { ts } from 'foldkit/schema'
+import { taggedStruct } from 'foldkit/schema'
 
 import { Session } from '../../domain/session'
 import { LoggedInRoute } from '../../route'
 
 // MODEL
 
-export const Model = ts('LoggedIn', {
+export const Model = taggedStruct('LoggedIn', {
   route: LoggedInRoute,
   session: Session,
 })

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

@@ -1,11 +1,11 @@
-import { ts } from 'foldkit/schema'
+import { taggedStruct } from 'foldkit/schema'
 
 import { LoggedOutRoute } from '../../route'
 import * as Login from './page/login'
 
 // MODEL
 
-export const Model = ts('LoggedOut', {
+export const Model = taggedStruct('LoggedOut', {
   route: LoggedOutRoute,
   loginModel: Login.Model,
 })

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

@@ -1,46 +1,36 @@
 import { Schema as S, pipe } from 'effect'
 import { Route } from 'foldkit'
-import { literal, r } from 'foldkit/route'
+import { defineRouteUnion, literal } from 'foldkit/route'
 
-export const HomeRoute = r('Home')
-export const LoginRoute = r('Login')
-export const DashboardRoute = r('Dashboard')
-export const SettingsRoute = r('Settings')
-export const NotFoundRoute = r('NotFound', { path: S.String })
+export const AppRoute = defineRouteUnion({
+  Home: {},
+  Login: {},
+  Dashboard: {},
+  Settings: {},
+  NotFound: { path: S.String },
+})
 
-export type HomeRoute = typeof HomeRoute.Type
-export type LoginRoute = typeof LoginRoute.Type
-export type DashboardRoute = typeof DashboardRoute.Type
-export type SettingsRoute = typeof SettingsRoute.Type
-export type NotFoundRoute = typeof NotFoundRoute.Type
+export type AppRoute = typeof AppRoute.Type
 
-export const LoggedOutRoute = S.Union([HomeRoute, LoginRoute, NotFoundRoute])
-export const LoggedInRoute = S.Union([
-  DashboardRoute,
-  SettingsRoute,
-  NotFoundRoute,
-])
-export const AppRoute = S.Union([
-  HomeRoute,
-  LoginRoute,
-  DashboardRoute,
-  SettingsRoute,
-  NotFoundRoute,
+export const LoggedOutRoute = AppRoute.subset(['Home', 'Login', 'NotFound'])
+export const LoggedInRoute = AppRoute.subset([
+  'Dashboard',
+  'Settings',
+  'NotFound',
 ])
 
 export type LoggedOutRoute = typeof LoggedOutRoute.Type
 export type LoggedInRoute = typeof LoggedInRoute.Type
-export type AppRoute = typeof AppRoute.Type
 
-export const homeRouter = pipe(Route.root, Route.mapTo(HomeRoute))
-export const loginRouter = pipe(literal('login'), Route.mapTo(LoginRoute))
+export const homeRouter = pipe(Route.root, Route.mapTo(AppRoute.Home))
+export const loginRouter = pipe(literal('login'), Route.mapTo(AppRoute.Login))
 export const dashboardRouter = pipe(
   literal('dashboard'),
-  Route.mapTo(DashboardRoute),
+  Route.mapTo(AppRoute.Dashboard),
 )
 export const settingsRouter = pipe(
   literal('settings'),
-  Route.mapTo(SettingsRoute),
+  Route.mapTo(AppRoute.Settings),
 )
 
 const routeParser = Route.oneOf(
@@ -52,5 +42,5 @@ const routeParser = Route.oneOf(
 
 export const urlToAppRoute = Route.parseUrlWithFallback(
   routeParser,
-  NotFoundRoute,
+  AppRoute.NotFound,
 )

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

@@ -20,12 +20,12 @@ import {
   SimulateAuthRequest,
   initModel as initLoginModel,
 } from './page/loggedOut/page/login'
-import { LoginRoute } from './route'
+import { AppRoute } from './route'
 import { RedirectToDashboard, update } from './update'
 import { view } from './view'
 
 const validModel = LoggedOut.Model({
-  route: LoginRoute(),
+  route: AppRoute.Login(),
   loginModel: LoginModel.make({
     ...initLoginModel(),
     email: Valid({ value: 'alice@example.com' }),

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

@@ -8,8 +8,7 @@ import { ClearSession, LogError, SaveSession } from './command'
 import { Message } from './message'
 import { LoggedIn, LoggedOut, Model } from './model'
 import {
-  DashboardRoute,
-  HomeRoute,
+  AppRoute,
   dashboardRouter,
   homeRouter,
   loginRouter,
@@ -62,7 +61,7 @@ const foldLoggedOutOutMessage: (
     SucceededLogin:
       ({ session }) =>
       () => ({
-        model: LoggedIn.init(DashboardRoute(), session),
+        model: LoggedIn.init(AppRoute.Dashboard(), session),
         commands: [SaveSession({ session }), RedirectToDashboard()],
       }),
   }),
@@ -88,7 +87,7 @@ const foldLoggedInOutMessage: (
   M.withReturnType<Update.Step<Model, Message>>(),
   M.tagsExhaustive({
     RequestedLogout: () => () => ({
-      model: LoggedOut.init(HomeRoute()),
+      model: LoggedOut.init(AppRoute.Home()),
       commands: [ClearSession(), RedirectToHome()],
     }),
   }),

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

@@ -21,7 +21,7 @@ import {
 } from 'foldkit/fieldValidation'
 import { type Attribute, Document, Html, HtmlBuilder } from 'foldkit/html'
 import { defineMessageUnion } from 'foldkit/message'
-import { ts } from 'foldkit/schema'
+import { defineTaggedUnion } from 'foldkit/schema'
 import { evo } from 'foldkit/struct'
 
 import { Button, Input, Textarea } from '@foldkit/ui'
@@ -37,22 +37,13 @@ const emailRules = makeRules({
 
 // MODEL
 
-const NotSubmitted = ts('NotSubmitted')
-const Submitting = ts('Submitting')
-const SubmitSuccess = ts('SubmitSuccess', { confirmationText: S.String })
-const SubmitError = ts('SubmitError', { error: S.String })
-
-const Submission = S.Union([
-  NotSubmitted,
-  Submitting,
-  SubmitSuccess,
-  SubmitError,
-])
-
-type NotSubmitted = typeof NotSubmitted.Type
-type Submitting = typeof Submitting.Type
-type SubmitSuccess = typeof SubmitSuccess.Type
-type SubmitError = typeof SubmitError.Type
+const Submission = defineTaggedUnion({
+  NotSubmitted: {},
+  Submitting: {},
+  SubmitSuccess: { confirmationText: S.String },
+  SubmitError: { error: S.String },
+})
+
 type Submission = typeof Submission.Type
 
 export const Model = S.Struct({
@@ -83,7 +74,7 @@ export const initialModel: Model = {
   name: NotValidated({ value: '' }),
   email: NotValidated({ value: '' }),
   messageText: NotValidated({ value: '' }),
-  submission: NotSubmitted(),
+  submission: Submission.NotSubmitted(),
 }
 
 export const init: Runtime.ApplicationInit<Model, Message> = () => ({
@@ -191,7 +182,7 @@ export const update = (model: Model, message: Message) =>
 
       return {
         model: evo(model, {
-          submission: () => Submitting(),
+          submission: () => Submission.Submitting(),
         }),
         commands: [
           SubmitForm({
@@ -206,7 +197,7 @@ export const update = (model: Model, message: Message) =>
     SucceededSubmitForm: ({ name }) => ({
       model: evo(model, {
         submission: () =>
-          SubmitSuccess({
+          Submission.SubmitSuccess({
             confirmationText: `Welcome to the waitlist, ${name}! We'll be in touch soon.`,
           }),
       }),
@@ -215,7 +206,7 @@ export const update = (model: Model, message: Message) =>
     FailedSubmitForm: () => ({
       model: evo(model, {
         submission: () =>
-          SubmitError({
+          Submission.SubmitError({
             error:
               'Sorry, there was an error adding you to the waitlist. Please try again.',
           }),

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

@@ -52,7 +52,7 @@ describe('view', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       expect(text('Cancelled')).toExist(),
@@ -79,7 +79,7 @@ describe('view', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       expect(role('button', { name: 'Cancel all' })).toBeAbsent(),

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

@@ -57,7 +57,7 @@ describe('update', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       Command.expectNone(),
@@ -83,7 +83,7 @@ describe('update', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.NotFound(),
+          outcome: Interruptible.Outcome.NotFound(),
         }),
       ),
       model(model => {
@@ -105,7 +105,7 @@ describe('update', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       Command.expectExact(
@@ -135,7 +135,7 @@ describe('update', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       Command.resolve(
@@ -161,7 +161,7 @@ describe('update', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       message(Message.ClickedRestartUpload({ uploadId: 0 })),
@@ -201,14 +201,14 @@ describe('update', () => {
         CancelUploadFile({ uploadId: 0 }),
         Message.CompletedCancelUploadFile({
           uploadId: 0,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       Command.resolve(
         CancelUploadFile({ uploadId: 2 }),
         Message.CompletedCancelUploadFile({
           uploadId: 2,
-          outcome: Interruptible.Interrupted(),
+          outcome: Interruptible.Outcome.Interrupted(),
         }),
       ),
       Command.expectNone(),

package/dist/templates/examples/job-application/src/main.ts

@@ -5,7 +5,7 @@ import { BrowserCrypto } from '@effect/platform-browser'
 import { Menu, Tabs } from '@foldkit/ui'
 
 import { Message } from './message'
-import { Model, NotSubmitted } from './model'
+import { Model, Submission } from './model'
 import {
   Attachments,
   CoverLetter,
@@ -58,7 +58,7 @@ export const init: Runtime.ApplicationInit<Model, Message, Flags> = ({
     coverLetter: CoverLetter.init(),
     attachments: Attachments.init(),
     isPreviewVisible: false,
-    submission: NotSubmitted(),
+    submission: Submission.NotSubmitted(),
     stepMenu: Menu.init({ id: 'step-menu' }),
     stepTabs: Tabs.init({ id: 'step-tabs' }),
     isSubmitAttempted: false,

package/dist/templates/examples/job-application/src/model.ts

@@ -1,5 +1,5 @@
 import { Schema as S } from 'effect'
-import { ts } from 'foldkit/schema'
+import { defineTaggedUnion } from 'foldkit/schema'
 
 import { Menu, Tabs } from '@foldkit/ui'
 
@@ -15,17 +15,12 @@ import {
 
 // SUBMISSION
 
-export const NotSubmitted = ts('NotSubmitted')
-export const Submitting = ts('Submitting')
-export const SubmitSuccess = ts('SubmitSuccess')
-export const SubmitError = ts('SubmitError', { error: S.String })
-
-export const Submission = S.Union([
-  NotSubmitted,
-  Submitting,
-  SubmitSuccess,
-  SubmitError,
-])
+export const Submission = defineTaggedUnion({
+  NotSubmitted: {},
+  Submitting: {},
+  SubmitSuccess: {},
+  SubmitError: { error: S.String },
+})
 export type Submission = typeof Submission.Type
 
 // MODEL

package/dist/templates/examples/job-application/src/scene.test.ts

@@ -15,13 +15,7 @@ import { describe, test } from 'vitest'
 import { Menu, Tabs } from '@foldkit/ui'
 import { Message as TabsMessage } from '@foldkit/ui/tabs'
 
-import {
-  type Model,
-  NotSubmitted,
-  SubmitError,
-  SubmitSuccess,
-  Submitting,
-} from './model'
+import { type Model, Submission } from './model'
 import {
   Attachments,
   CoverLetter,
@@ -44,7 +38,7 @@ const initialModel: Model = {
   coverLetter: CoverLetter.init(),
   attachments: Attachments.init(),
   isPreviewVisible: false,
-  submission: NotSubmitted(),
+  submission: Submission.NotSubmitted(),
   stepMenu: Menu.init({ id: 'step-menu' }),
   stepTabs: Tabs.init({ id: 'step-tabs' }),
   isSubmitAttempted: false,
@@ -236,7 +230,7 @@ describe('view', () => {
       given({
         ...initialModel,
         currentStep: 'Review',
-        submission: Submitting(),
+        submission: Submission.Submitting(),
       }),
       expect(role('button', { name: 'Submitting...' })).toExist(),
     )
@@ -248,7 +242,7 @@ describe('view', () => {
       given({
         ...initialModel,
         currentStep: 'Review',
-        submission: SubmitSuccess(),
+        submission: Submission.SubmitSuccess(),
       }),
       expect(text('Application Submitted', { exact: false })).toExist(),
     )
@@ -260,7 +254,7 @@ describe('view', () => {
       given({
         ...initialModel,
         currentStep: 'Review',
-        submission: SubmitError({ error: 'Network down' }),
+        submission: Submission.SubmitError({ error: 'Network down' }),
       }),
       expect(text('Network down')).toExist(),
       expect(role('button', { name: 'Try Again' })).toExist(),

package/dist/templates/examples/job-application/src/story.test.ts

@@ -11,7 +11,7 @@ import { Message as TabsMessage } from '@foldkit/ui/tabs'
 
 import { SubmitApplication } from './command'
 import { Message } from './message'
-import { type Model, NotSubmitted, Submitting } from './model'
+import { type Model, Submission } from './model'
 import {
   Attachments,
   CoverLetter,
@@ -39,7 +39,7 @@ const initialModel: Model = {
   coverLetter: CoverLetter.init(),
   attachments: Attachments.init(),
   isPreviewVisible: false,
-  submission: NotSubmitted(),
+  submission: Submission.NotSubmitted(),
   stepMenu: Menu.init({ id: 'step-menu' }),
   stepTabs: Tabs.init({ id: 'step-tabs' }),
   isSubmitAttempted: false,
@@ -748,7 +748,7 @@ describe('update', () => {
         given({
           ...initialModel,
           currentStep: 'Review',
-          submission: Submitting(),
+          submission: Submission.Submitting(),
         }),
         message(Message.SucceededSubmitApplication()),
         model(model => {
@@ -763,7 +763,7 @@ describe('update', () => {
         given({
           ...initialModel,
           currentStep: 'Review',
-          submission: Submitting(),
+          submission: Submission.Submitting(),
         }),
         message(Message.FailedSubmitApplication({ error: 'Server down' })),
         model(model => {

package/dist/templates/examples/job-application/src/update.ts

@@ -7,7 +7,7 @@ import { Menu, Tabs } from '@foldkit/ui'
 import { SubmitApplication } from './command'
 import { Step } from './domain'
 import { Message } from './message'
-import { type Model, SubmitError, SubmitSuccess, Submitting } from './model'
+import { type Model, Submission } from './model'
 import {
   Attachments,
   CoverLetter,
@@ -163,7 +163,9 @@ export const update = (model: Model, message: Message) =>
       })
       if (isApplicationComplete(revealedModel)) {
         return {
-          model: evo(revealedModel, { submission: () => Submitting() }),
+          model: evo(revealedModel, {
+            submission: () => Submission.Submitting(),
+          }),
           commands: [SubmitApplication()],
         }
       }
@@ -171,10 +173,12 @@ export const update = (model: Model, message: Message) =>
     },
 
     SucceededSubmitApplication: () => ({
-      model: evo(model, { submission: () => SubmitSuccess() }),
+      model: evo(model, { submission: () => Submission.SubmitSuccess() }),
     }),
 
     FailedSubmitApplication: ({ error }) => ({
-      model: evo(model, { submission: () => SubmitError({ error }) }),
+      model: evo(model, {
+        submission: () => Submission.SubmitError({ error }),
+      }),
     }),
   })