create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/view-transitions/src/main.ts

@@ -0,0 +1,348 @@
+import { Array, Effect, Match as M, Option, Schema as S, String } from 'effect'
+import { Command, Runtime } from 'foldkit'
+import { Document, Html, HtmlBuilder } from 'foldkit/html'
+import { defineMessageUnion } from 'foldkit/message'
+import { UrlRequest, load, pushUrl } from 'foldkit/navigation'
+import { Transition } from 'foldkit/route'
+import { evo } from 'foldkit/struct'
+import { Url, toString as urlToString } from 'foldkit/url'
+
+import { Artwork, artworks, findArtwork } from './artwork'
+import { AppRoute, artworkRouter, galleryRouter, urlToAppRoute } from './route'
+
+export { ArtworkRoute, GalleryRoute, NotFoundRoute } from './route'
+
+// MODEL
+
+export const Model = S.Struct({
+  route: AppRoute,
+  filterText: S.String,
+})
+export type Model = typeof Model.Type
+
+// MESSAGE
+
+export const Message = defineMessageUnion({
+  CompletedNavigateInternal: {},
+  CompletedLoadExternal: {},
+  ClickedLink: { request: UrlRequest },
+  ChangedUrl: { url: Url },
+  UpdatedFilterText: { filterText: S.String },
+})
+
+export type Message = typeof Message.Type
+
+// INIT
+
+export const init: Runtime.RoutingApplicationInit<Model, Message> = (
+  url: Url,
+) => [{ route: urlToAppRoute(url), filterText: '' }, []]
+
+// COMMAND
+
+const NavigateInternal = Command.define('NavigateInternal', {
+  args: { url: S.String },
+  messages: [Message.CompletedNavigateInternal],
+  execute: ({ url }) =>
+    pushUrl(url).pipe(Effect.as(Message.CompletedNavigateInternal())),
+})
+
+const LoadExternal = Command.define('LoadExternal', {
+  args: { href: S.String },
+  messages: [Message.CompletedLoadExternal],
+  execute: ({ href }) =>
+    load(href).pipe(Effect.as(Message.CompletedLoadExternal())),
+})
+
+// UPDATE
+
+type UpdateReturn = readonly [Model, ReadonlyArray<Command.Command<Message>>]
+const withUpdateReturn = M.withReturnType<UpdateReturn>()
+
+export const update = (model: Model, message: Message) =>
+  Message.match<UpdateReturn>(message, {
+    CompletedNavigateInternal: () => [model, []],
+    CompletedLoadExternal: () => [model, []],
+
+    ClickedLink: ({ request }) =>
+      M.value(request).pipe(
+        withUpdateReturn,
+        M.tagsExhaustive({
+          Internal: ({ url }) => [
+            model,
+            [NavigateInternal({ url: urlToString(url) })],
+          ],
+          External: ({ href }) => [model, [LoadExternal({ href })]],
+        }),
+      ),
+
+    ChangedUrl: ({ url }) => [
+      evo(model, { route: () => urlToAppRoute(url) }),
+      [],
+    ],
+
+    UpdatedFilterText: ({ filterText }) => [
+      evo(model, { filterText: () => filterText }),
+      [],
+    ],
+  })
+
+// NOTE: every arm past the guard is a navigation, so none return `false`.
+// `true` is "animate, with no direction to declare": the root fade in
+// `styles.css` is not type-scoped, so an untyped transition still cross-fades,
+// it just does not slide.
+export const viewTransition: Runtime.ViewTransitionConfig<Model, Message> = ({
+  previousModel,
+  model,
+  message,
+}) => {
+  if (message._tag !== 'ChangedUrl') {
+    return false
+  }
+
+  const transition = Transition.make(previousModel.route, model.route)
+
+  return Option.match(Transition.enteredAny(transition), {
+    onNone: () => true,
+    onSome: M.type<AppRoute>().pipe(
+      M.withReturnType<Runtime.ViewTransitionDecision>(),
+      M.tagsExhaustive({
+        Artwork: () => ({ types: ['to-artwork-detail'] }),
+        Gallery: () => ({ types: ['to-gallery'] }),
+        NotFound: () => true,
+      }),
+    ),
+  })
+}
+
+// VIEW
+
+const transitionNameFor = (artworkId: number): string => `artwork-${artworkId}`
+
+// NOTE: names have to be unique per snapshot, so each artwork carries its own.
+// The shared class is what lets `styles.css` reach all of them with one rule,
+// since a per-artwork name cannot be written as a selector ahead of time.
+const artworkTransitionStyle = (artworkId: number) => ({
+  viewTransitionName: transitionNameFor(artworkId),
+  viewTransitionClass: 'artwork',
+})
+
+const filteredArtworks = (filterText: string): ReadonlyArray<Artwork> => {
+  const normalizedFilter = filterText.trim().toLowerCase()
+
+  if (String.isEmpty(normalizedFilter)) {
+    return artworks
+  } else {
+    return Array.filter(artworks, artwork =>
+      String.includes(normalizedFilter)(
+        `${artwork.title} ${artwork.medium}`.toLowerCase(),
+      ),
+    )
+  }
+}
+
+const artworkCardView = (artwork: Artwork, h: HtmlBuilder<Message>): Html =>
+  h.keyed('a')(
+    `artwork-${artwork.id}`,
+    [h.Href(artworkRouter({ artworkId: artwork.id })), h.Class('group block')],
+    [
+      h.div([
+        h.Class(
+          `aspect-square rounded-xl bg-gradient-to-br shadow-sm transition-shadow group-hover:shadow-lg ${artwork.gradientClassName}`,
+        ),
+        h.Style(artworkTransitionStyle(artwork.id)),
+      ]),
+      h.p([h.Class('mt-3 font-medium text-gray-900')], [artwork.title]),
+      h.p([h.Class('text-sm text-gray-500')], [artwork.medium]),
+    ],
+  )
+
+const emptyGalleryView = (h: HtmlBuilder<Message>): Html =>
+  h.p([h.Class('text-gray-500')], ['No artworks match the filter.'])
+
+const artworkGridView = (
+  matchedArtworks: ReadonlyArray<Artwork>,
+  h: HtmlBuilder<Message>,
+): Html =>
+  h.div(
+    [h.Class('grid grid-cols-2 gap-6 sm:grid-cols-3 lg:grid-cols-4')],
+    Array.map(matchedArtworks, artwork => artworkCardView(artwork, h)),
+  )
+
+const galleryView = (filterText: string, h: HtmlBuilder<Message>): Html =>
+  h.div(
+    [h.Class('mx-auto max-w-5xl px-6')],
+    [
+      h.input([
+        h.Type('search'),
+        h.Value(filterText),
+        h.Placeholder('Filter by title or medium…'),
+        h.OnInput(value => Message.UpdatedFilterText({ filterText: value })),
+        h.Class(
+          'mb-8 w-full max-w-md rounded-lg border border-gray-300 bg-white px-4 py-2 focus:ring-2 focus:ring-gray-400 focus:outline-none',
+        ),
+      ]),
+      Array.match(filteredArtworks(filterText), {
+        onEmpty: () => emptyGalleryView(h),
+        onNonEmpty: matchedArtworks => artworkGridView(matchedArtworks, h),
+      }),
+    ],
+  )
+
+const missingArtworkView = (artworkId: number, h: HtmlBuilder<Message>): Html =>
+  h.div(
+    [],
+    [
+      h.h1(
+        [h.Class('text-3xl font-bold text-gray-900')],
+        ['Artwork not found'],
+      ),
+      h.p(
+        [h.Class('mt-2 text-gray-600')],
+        [`No artwork exists with ID ${artworkId}.`],
+      ),
+      h.a(
+        [
+          h.Href(galleryRouter()),
+          h.Class('mt-4 inline-block text-gray-900 underline'),
+        ],
+        ['← Back to gallery'],
+      ),
+    ],
+  )
+
+// NOTE: the hero keeps the card's square ratio on purpose. A View Transition
+// interpolates the old and new snapshots while it interpolates the box, so a
+// square growing into a wider box visibly stretches mid-flight. Matching the
+// ratio makes the morph a pure scale and translate, which is the one case the
+// browser renders cleanly.
+const foundArtworkView = (artwork: Artwork, h: HtmlBuilder<Message>): Html =>
+  h.div(
+    [],
+    [
+      h.a(
+        [
+          h.Href(galleryRouter()),
+          h.Class('text-gray-600 underline hover:text-gray-900'),
+        ],
+        ['← Back to gallery'],
+      ),
+      h.div(
+        [
+          h.Class(
+            'mt-6 grid gap-10 md:grid-cols-[minmax(0,24rem)_1fr] md:items-center',
+          ),
+        ],
+        [
+          h.div([
+            h.Class(
+              `aspect-square w-full rounded-2xl bg-gradient-to-br shadow-md ${artwork.gradientClassName}`,
+            ),
+            h.Style(artworkTransitionStyle(artwork.id)),
+          ]),
+          h.div(
+            [],
+            [
+              h.h1(
+                [h.Class('text-3xl font-bold text-gray-900')],
+                [artwork.title],
+              ),
+              h.p([h.Class('mt-1 text-sm text-gray-500')], [artwork.medium]),
+              h.p(
+                [h.Class('mt-4 text-lg leading-relaxed text-gray-700')],
+                [artwork.description],
+              ),
+            ],
+          ),
+        ],
+      ),
+    ],
+  )
+
+const artworkDetailView = (artworkId: number, h: HtmlBuilder<Message>): Html =>
+  h.div(
+    [h.Class('mx-auto max-w-5xl px-6')],
+    [
+      Option.match(findArtwork(artworkId), {
+        onNone: () => missingArtworkView(artworkId, h),
+        onSome: artwork => foundArtworkView(artwork, h),
+      }),
+    ],
+  )
+
+const notFoundView = (path: string, h: HtmlBuilder<Message>): Html =>
+  h.div(
+    [h.Class('mx-auto max-w-3xl px-6')],
+    [
+      h.h1([h.Class('text-3xl font-bold text-gray-900')], ['Page not found']),
+      h.p(
+        [h.Class('mt-2 text-gray-600')],
+        [`The path "${path}" does not exist.`],
+      ),
+      h.a(
+        [
+          h.Href(galleryRouter()),
+          h.Class('mt-4 inline-block text-gray-900 underline'),
+        ],
+        ['← Back to gallery'],
+      ),
+    ],
+  )
+
+const routeTitle = (route: AppRoute): string =>
+  M.value(route).pipe(
+    M.tagsExhaustive({
+      Gallery: () => 'View Transitions',
+      Artwork: ({ artworkId }) =>
+        Option.match(findArtwork(artworkId), {
+          onNone: () => 'Artwork Not Found | View Transitions',
+          onSome: artwork => `${artwork.title} | View Transitions`,
+        }),
+      NotFound: () => 'Page Not Found | View Transitions',
+    }),
+  )
+
+export const view = (model: Model, h: HtmlBuilder<Message>): Document => {
+  const routeContent = M.value(model.route).pipe(
+    M.tagsExhaustive({
+      Gallery: () => galleryView(model.filterText, h),
+      Artwork: ({ artworkId }) => artworkDetailView(artworkId, h),
+      NotFound: ({ path }) => notFoundView(path, h),
+    }),
+  )
+
+  return {
+    title: routeTitle(model.route),
+    body: h.div(
+      [h.Class('min-h-screen bg-gray-50 py-10')],
+      [
+        // NOTE: naming the header lifts it out of the root snapshot, so it
+        // stays a live element the transition never touches. Without a name it
+        // rides the page cross-fade and animates on every navigation despite
+        // being identical on both routes, which reads as jank.
+        h.header(
+          [
+            h.Class('mx-auto max-w-5xl px-6 pb-8'),
+            h.Style({ viewTransitionName: 'page-header' }),
+          ],
+          [
+            h.a(
+              [
+                h.Href(galleryRouter()),
+                h.Class('text-2xl font-bold text-gray-900'),
+              ],
+              ['Gradient Gallery'],
+            ),
+            h.p(
+              [h.Class('mt-1 text-gray-600')],
+              [
+                'Click an artwork and watch it grow into the detail page. Typing in the filter never animates.',
+              ],
+            ),
+          ],
+        ),
+        h.main([], [routeContent]),
+      ],
+    ),
+  }
+}

package/dist/templates/examples/view-transitions/src/route.ts

@@ -0,0 +1,29 @@
+import { Schema as S, pipe } from 'effect'
+import { Route } from 'foldkit'
+import { int, literal, r, slash } from 'foldkit/route'
+
+export const GalleryRoute = r('Gallery')
+export const ArtworkRoute = r('Artwork', { artworkId: S.Number })
+export const NotFoundRoute = r('NotFound', { path: S.String })
+
+export const AppRoute = S.Union([GalleryRoute, ArtworkRoute, NotFoundRoute])
+
+export type GalleryRoute = typeof GalleryRoute.Type
+export type ArtworkRoute = typeof ArtworkRoute.Type
+export type NotFoundRoute = typeof NotFoundRoute.Type
+export type AppRoute = typeof AppRoute.Type
+
+export const galleryRouter = pipe(Route.root, Route.mapTo(GalleryRoute))
+
+export const artworkRouter = pipe(
+  literal('artwork'),
+  slash(int('artworkId')),
+  Route.mapTo(ArtworkRoute),
+)
+
+const routeParser = Route.oneOf(artworkRouter, galleryRouter)
+
+export const urlToAppRoute = Route.parseUrlWithFallback(
+  routeParser,
+  NotFoundRoute,
+)

package/dist/templates/examples/view-transitions/src/scene.test.ts

@@ -0,0 +1,130 @@
+import { Option } from 'effect'
+import { Scene } from 'foldkit'
+import { fromString } from 'foldkit/url'
+import { describe, expect, test } from 'vitest'
+
+import {
+  ArtworkRoute,
+  GalleryRoute,
+  Message,
+  Model,
+  NotFoundRoute,
+  update,
+  view,
+  viewTransition,
+} from './main'
+
+const gallery = Model.make({ route: GalleryRoute(), filterText: '' })
+const artworkDetail = (artworkId: number) =>
+  Model.make({ route: ArtworkRoute({ artworkId }), filterText: '' })
+const notFound = Model.make({
+  route: NotFoundRoute({ path: '/nowhere' }),
+  filterText: '',
+})
+
+const FILTER_PLACEHOLDER = 'Filter by title or medium…'
+
+describe('gallery', () => {
+  test('renders a card for every artwork', () => {
+    Scene.scene(
+      { update, view },
+      Scene.given(gallery),
+      Scene.expect(Scene.text('Dawn Chorus')).toExist(),
+      Scene.expect(Scene.text('Deep Water')).toExist(),
+      Scene.expect(Scene.text('Pollen')).toExist(),
+    )
+  })
+
+  test('typing in the filter narrows the grid', () => {
+    Scene.scene(
+      { update, view },
+      Scene.given(gallery),
+      Scene.type(Scene.placeholder(FILTER_PLACEHOLDER), 'graphite'),
+      Scene.expect(Scene.text('Graphite')).toExist(),
+      Scene.expect(Scene.text('Dawn Chorus')).toBeAbsent(),
+    )
+  })
+
+  test('a filter with no matches shows the empty state', () => {
+    Scene.scene(
+      { update, view },
+      Scene.given(gallery),
+      Scene.type(Scene.placeholder(FILTER_PLACEHOLDER), 'watercolor'),
+      Scene.expect(Scene.text('No artworks match the filter.')).toExist(),
+    )
+  })
+})
+
+describe('artwork detail', () => {
+  test('renders the artwork with its description and a back link', () => {
+    Scene.scene(
+      { update, view },
+      Scene.given(artworkDetail(2)),
+      Scene.expect(Scene.text('Deep Water')).toExist(),
+      Scene.expect(Scene.role('link', { name: '← Back to gallery' })).toExist(),
+    )
+  })
+
+  test('renders a missing state for an unknown artwork ID', () => {
+    Scene.scene(
+      { update, view },
+      Scene.given(artworkDetail(999)),
+      Scene.expect(Scene.text('Artwork not found')).toExist(),
+    )
+  })
+})
+
+describe('not found', () => {
+  test('renders the missing path', () => {
+    Scene.scene(
+      { update, view },
+      Scene.given(notFound),
+      Scene.expect(Scene.text('Page not found')).toExist(),
+    )
+  })
+})
+
+describe('viewTransition', () => {
+  const urlFor = (path: string) =>
+    Option.getOrThrow(fromString(`http://localhost${path}`))
+
+  test('transitions to-artwork-detail when the gallery gives way to an artwork', () => {
+    const decision = viewTransition({
+      previousModel: gallery,
+      model: artworkDetail(1),
+      message: Message.ChangedUrl({ url: urlFor('/artwork/1') }),
+    })
+
+    expect(decision).toEqual({ types: ['to-artwork-detail'] })
+  })
+
+  test('transitions to-gallery when an artwork gives way to the gallery', () => {
+    const decision = viewTransition({
+      previousModel: artworkDetail(1),
+      model: gallery,
+      message: Message.ChangedUrl({ url: urlFor('/') }),
+    })
+
+    expect(decision).toEqual({ types: ['to-gallery'] })
+  })
+
+  test('transitions untyped between two artworks', () => {
+    const decision = viewTransition({
+      previousModel: artworkDetail(1),
+      model: artworkDetail(2),
+      message: Message.ChangedUrl({ url: urlFor('/artwork/2') }),
+    })
+
+    expect(decision).toBe(true)
+  })
+
+  test('never transitions on filter keystrokes', () => {
+    const decision = viewTransition({
+      previousModel: gallery,
+      model: gallery,
+      message: Message.UpdatedFilterText({ filterText: 'g' }),
+    })
+
+    expect(decision).toBe(false)
+  })
+})

package/dist/templates/examples/view-transitions/src/styles.css

@@ -0,0 +1,66 @@
+@import 'tailwindcss';
+
+/* The morph is the whole show. The header is named so the browser lifts it out
+   of the root snapshot and holds it still, the artwork grows from grid card to
+   detail hero, and everything else cross-fades underneath it. Nothing slides,
+   so nothing competes with the one element the eye is already tracking.
+   Reduced-motion users never reach this file: the runtime skips
+   startViewTransition entirely. */
+
+::view-transition-group(page-header) {
+  animation: none;
+}
+
+/* Staggered rather than cross-faded. Two layouts dissolving through each other
+   reads as a double exposure: grid cards sit on top of detail copy for the
+   whole overlap. The outgoing page leaves quickly, then the incoming one
+   arrives, so there is a beat where only the artwork is moving. */
+::view-transition-old(root) {
+  animation-duration: 130ms;
+  animation-timing-function: ease-in;
+}
+
+::view-transition-new(root) {
+  /* Overlaps the tail of the outgoing fade by a hair. A clean handoff at the
+     same instant leaves a stretch where neither page is drawn and the screen
+     washes out; starting slightly early covers it without bringing back the
+     double exposure. */
+  animation-delay: 100ms;
+  animation-duration: 240ms;
+  animation-timing-function: ease-out;
+  /* Holds the incoming page at its from-state through the delay, instead of
+     letting it sit at full opacity while the old page is still leaving. */
+  animation-fill-mode: backwards;
+}
+
+/* Every card carries a name, so every card becomes its own group and none of
+   them are covered by the root fade above. The seven the user did not click
+   have no counterpart on the detail page, so they only fade, and without this
+   they would drift out on the hero's long timing instead of clearing with the
+   page they belong to. For the one card that does have a counterpart, the same
+   rule tightens the cross-fade between its two snapshots so the morph reads as
+   one solid object rather than two images dissolving through each other. */
+::view-transition-old(.artwork),
+::view-transition-new(.artwork) {
+  animation-duration: 160ms;
+}
+
+/* Both directions ease in and out rather than front-loading. The heavily
+   front-loaded curves (ease-out-quint and friends) put most of the travel in
+   the first fifth of the duration, so the artwork lunges and then crawls, which
+   is what made this read as janky.
+
+   The directions differ in pace, not in curve: arriving at a detail page is
+   unhurried, returning to the grid is brisk. Transition types are what let CSS
+   tell the two apart, since the DOM change is otherwise symmetric. */
+:root:active-view-transition-type(to-artwork-detail)::view-transition-group(
+    .artwork
+  ) {
+  animation-duration: 480ms;
+  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+:root:active-view-transition-type(to-gallery)::view-transition-group(.artwork) {
+  animation-duration: 320ms;
+  animation-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
+}

package/dist/templates/examples/view-transitions/src/vitest-setup.ts

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

package/dist/templates/examples/weather/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "weather-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",
+    "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/weather/src/entry.ts

@@ -0,0 +1,16 @@
+import { Runtime } from 'foldkit'
+
+import { Message, Model, init, update, view } from './main'
+
+const application = Runtime.makeApplication({
+  Model,
+  init,
+  update,
+  view,
+  container: document.getElementById('root'),
+  devTools: {
+    Message,
+  },
+})
+
+Runtime.run(application)

package/dist/templates/examples/weather/src/main.fixtures.ts

@@ -0,0 +1,59 @@
+import type { Model, WeatherData } from './main'
+import { WeatherAsyncData } from './main'
+
+export const weatherModel: Model = {
+  zipCodeInput: '90210',
+  weather: WeatherAsyncData.Idle(),
+}
+
+export const weatherData: WeatherData = {
+  zipCode: '90210',
+  temperature: 72,
+  description: 'Clear sky',
+  humidity: 45,
+  windSpeed: 10,
+  locationName: 'Beverly Hills',
+  region: 'California',
+}
+
+export const mockGeocodingResponse: Readonly<{
+  results: ReadonlyArray<
+    Readonly<{
+      name: string
+      latitude: number
+      longitude: number
+      admin1: string
+    }>
+  >
+  generationtime_ms: number
+}> = {
+  results: [
+    {
+      name: 'Beverly Hills',
+      latitude: 34.07362,
+      longitude: -118.40036,
+      admin1: 'California',
+    },
+  ],
+  generationtime_ms: 0.5,
+}
+
+export const mockWeatherResponse: Readonly<{
+  current: Readonly<{
+    time: string
+    interval: number
+    temperature_2m: number
+    relative_humidity_2m: number
+    wind_speed_10m: number
+    weather_code: number
+  }>
+}> = {
+  current: {
+    time: '2026-03-10T01:30',
+    interval: 900,
+    temperature_2m: 72.4,
+    relative_humidity_2m: 45,
+    wind_speed_10m: 9.8,
+    weather_code: 0,
+  },
+}