create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/routing/src/page/people.ts

@@ -0,0 +1,349 @@
+import {
+  Array,
+  Duration,
+  Effect,
+  Match as M,
+  Option,
+  Schema as S,
+  String,
+  pipe,
+} from 'effect'
+import { Command, Submodel } from 'foldkit'
+import { Html, HtmlBuilder } from 'foldkit/html'
+import { defineMessageUnion } from 'foldkit/message'
+import { pushUrl } from 'foldkit/navigation'
+import { ts } from 'foldkit/schema'
+import { evo } from 'foldkit/struct'
+
+import { Button, Input } from '@foldkit/ui'
+
+import { PeopleRoute, peopleRouter, personRouter } from '../route'
+
+// DOMAIN
+
+const Person = S.Struct({
+  id: S.Number,
+  name: S.String,
+  role: S.String,
+})
+type Person = typeof Person.Type
+
+const people: ReadonlyArray<Person> = [
+  { id: 1, name: 'Alice Johnson', role: 'Designer' },
+  { id: 2, name: 'Bob Smith', role: 'Developer' },
+  { id: 3, name: 'Carol Davis', role: 'Manager' },
+  { id: 4, name: 'David Wilson', role: 'Developer' },
+  { id: 5, name: 'Eva Brown', role: 'Designer' },
+]
+
+const SEARCH_HISTORY_LIMIT = 5
+const SEARCH_LATENCY = Duration.millis(300)
+
+const matchesQuery = (person: Person, query: string): boolean => {
+  const lowerQuery = query.toLowerCase()
+  return (
+    person.name.toLowerCase().includes(lowerQuery) ||
+    person.role.toLowerCase().includes(lowerQuery)
+  )
+}
+
+export const searchPeople = (searchText: string): ReadonlyArray<Person> =>
+  pipe(
+    searchText,
+    Option.liftPredicate(String.isNonEmpty),
+    Option.match({
+      onNone: () => people,
+      onSome: query =>
+        Array.filter(people, person => matchesQuery(person, query)),
+    }),
+  )
+
+const addSearchToHistory = (
+  history: ReadonlyArray<string>,
+  value: string,
+): ReadonlyArray<string> => {
+  if (String.isEmpty(value)) {
+    return history
+  }
+
+  return Array.take(Array.dedupe([value, ...history]), SEARCH_HISTORY_LIMIT)
+}
+
+const routeSearchText = (route: PeopleRoute): string =>
+  Option.getOrElse(route.searchText, () => '')
+
+export const findPerson = (id: number) =>
+  Array.findFirst(people, person => person.id === id)
+
+// MODEL
+
+export const SearchLoading = ts('SearchLoading')
+export const SearchLoaded = ts('SearchLoaded', {
+  query: S.String,
+  people: S.Array(Person),
+})
+
+export const SearchResults = S.Union([SearchLoading, SearchLoaded])
+export type SearchResults = typeof SearchResults.Type
+
+export const Model = S.Struct({
+  searchInput: S.String,
+  searchHistory: S.Array(S.String),
+  results: SearchResults,
+})
+export type Model = typeof Model.Type
+
+// MESSAGE
+
+export const Message = defineMessageUnion({
+  ChangedSearchInput: { value: S.String },
+  SubmittedSearch: {},
+  ChangedRoute: { route: PeopleRoute },
+  SucceededFetchPeople: {
+    query: S.String,
+    people: S.Array(Person),
+  },
+  CompletedPushSearchUrl: {},
+})
+
+export type Message = typeof Message.Type
+
+// INIT
+
+export const init = (
+  route: PeopleRoute,
+): readonly [Model, ReadonlyArray<Command.Command<Message>>] => {
+  const searchText = routeSearchText(route)
+  return [
+    {
+      searchInput: searchText,
+      searchHistory: addSearchToHistory([], searchText),
+      results: SearchLoading(),
+    },
+    [FetchPeople({ searchText })],
+  ]
+}
+
+// COMMAND
+
+export const PushSearchUrl = Command.define('PushSearchUrl', {
+  args: { searchText: S.Option(S.String) },
+  messages: [Message.CompletedPushSearchUrl],
+  execute: ({ searchText }) =>
+    pushUrl(peopleRouter({ searchText })).pipe(
+      Effect.as(Message.CompletedPushSearchUrl()),
+    ),
+})
+
+export const FetchPeople = Command.define('FetchPeople', {
+  args: { searchText: S.String },
+  messages: [Message.SucceededFetchPeople],
+  execute: ({ searchText }) =>
+    Effect.sleep(SEARCH_LATENCY).pipe(
+      Effect.as(
+        Message.SucceededFetchPeople({
+          query: searchText,
+          people: searchPeople(searchText),
+        }),
+      ),
+    ),
+})
+
+// UPDATE
+
+export type UpdateReturn = readonly [
+  Model,
+  ReadonlyArray<Command.Command<Message>>,
+]
+
+export const update = (model: Model, message: Message) =>
+  Message.match<UpdateReturn>(message, {
+    ChangedSearchInput: ({ value }) => [
+      evo(model, { searchInput: () => value }),
+      [],
+    ],
+
+    SubmittedSearch: () => [
+      model,
+      [
+        PushSearchUrl({
+          searchText: Option.fromNullishOr(model.searchInput || null),
+        }),
+      ],
+    ],
+
+    ChangedRoute: ({ route }) => {
+      const searchText = routeSearchText(route)
+      return [
+        evo(model, {
+          searchInput: () => searchText,
+          searchHistory: searchHistory =>
+            addSearchToHistory(searchHistory, searchText),
+          results: () => SearchLoading(),
+        }),
+        [FetchPeople({ searchText })],
+      ]
+    },
+
+    SucceededFetchPeople: ({ query, people: fetchedPeople }) => [
+      evo(model, {
+        results: () => SearchLoaded({ query, people: fetchedPeople }),
+      }),
+      [],
+    ],
+
+    CompletedPushSearchUrl: () => [model, []],
+  })
+
+/** Tells the People page that the route changed. People does not own the
+ *  route; it derives its own state (the search input and history) from the new
+ *  route and returns the refetch Command. The parent calls this from its
+ *  `ChangedUrl` handler. Contrast a `reflect*` setter, which writes a field the
+ *  Submodel owns from an external value, with no derivation and no Command. */
+export const informRouteChanged = (model: Model, route: PeopleRoute) =>
+  update(model, Message.ChangedRoute({ route }))
+
+// VIEW
+
+const statusText = (results: SearchResults): string =>
+  M.value(results).pipe(
+    M.withReturnType<string>(),
+    M.tag('SearchLoading', () => 'Searching…'),
+    M.tag('SearchLoaded', ({ query, people: found }) => {
+      if (String.isEmpty(query)) {
+        return 'Click on any person to view their details:'
+      }
+
+      const count = Array.length(found)
+      const noun = count === 1 ? 'result' : 'results'
+      return `${count} ${noun} for “${query}”`
+    }),
+    M.exhaustive,
+  )
+
+const recentSearchesView = (
+  history: ReadonlyArray<string>,
+  h: HtmlBuilder<Message>,
+): Html =>
+  h.div(
+    [h.Class('mb-6 text-sm text-gray-600 flex flex-wrap gap-2')],
+    [
+      h.span([h.Class('font-medium')], ['Recent searches:']),
+      ...Array.map(history, term =>
+        h.keyed('span')(
+          term,
+          [h.Class('px-2 py-1 bg-gray-200 rounded font-mono text-gray-800')],
+          [term],
+        ),
+      ),
+    ],
+  )
+
+const personListItemView = (person: Person, h: HtmlBuilder<Message>): Html =>
+  h.keyed('li')(
+    person.id.toString(),
+    [h.Class('border border-gray-200 rounded-lg hover:bg-gray-50')],
+    [
+      h.a(
+        [h.Href(personRouter({ personId: person.id })), h.Class('block p-4')],
+        [
+          h.div(
+            [h.Class('flex justify-between items-center')],
+            [
+              h.h2(
+                [h.Class('text-xl font-semibold text-gray-800')],
+                [person.name],
+              ),
+              h.p([h.Class('text-gray-600')], [person.role]),
+            ],
+          ),
+        ],
+      ),
+    ],
+  )
+
+export const view = Submodel.defineView<Model, Message>(
+  (model, h): Html =>
+    h.div(
+      [h.Class('max-w-4xl mx-auto px-4')],
+      [
+        h.h1([h.Class('text-4xl font-bold text-gray-800 mb-6')], ['People']),
+
+        h.search(
+          [h.Class('mb-6')],
+          [
+            h.form(
+              [h.OnSubmit(Message.SubmittedSearch()), h.Class('flex gap-2')],
+              [
+                Input.view(
+                  {
+                    id: 'people-search',
+                    type: 'search',
+                    value: model.searchInput,
+                    placeholder: 'Search by name or role...',
+                    onInput: value => Message.ChangedSearchInput({ value }),
+                    toView: ({ input, label, description }) =>
+                      h.div(
+                        [h.Class('flex-1')],
+                        [
+                          h.label(
+                            [...label, h.Class('sr-only')],
+                            ['Search people'],
+                          ),
+                          h.input([
+                            ...input,
+                            h.Autocomplete('off'),
+                            h.Class(
+                              'w-full px-4 py-2 border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500',
+                            ),
+                          ]),
+                          h.span([...description]),
+                        ],
+                      ),
+                  },
+                  h,
+                ),
+                Button.view(
+                  {
+                    type: 'submit',
+                    toView: ({ button }) =>
+                      h.button(
+                        [
+                          ...button,
+                          h.Class(
+                            'px-4 py-2 bg-blue-500 text-white rounded-lg hover:bg-blue-600 transition cursor-pointer',
+                          ),
+                        ],
+                        ['Search'],
+                      ),
+                  },
+                  h,
+                ),
+              ],
+            ),
+          ],
+        ),
+
+        Array.match(model.searchHistory, {
+          onEmpty: () => h.empty,
+          onNonEmpty: history => recentSearchesView(history, h),
+        }),
+
+        h.p(
+          [h.Class('text-lg text-gray-600 mb-6'), h.AriaLive('polite')],
+          [statusText(model.results)],
+        ),
+
+        M.value(model.results).pipe(
+          M.tag('SearchLoading', () => h.empty),
+          M.tag('SearchLoaded', ({ people: results }) =>
+            h.ul(
+              [h.Class('space-y-3')],
+              Array.map(results, person => personListItemView(person, h)),
+            ),
+          ),
+          M.exhaustive,
+        ),
+      ],
+    ),
+)

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

@@ -0,0 +1,82 @@
+import { Schema as S, pipe } from 'effect'
+import { Route } from 'foldkit'
+import { int, literal, r, rest, slash } from 'foldkit/route'
+
+export const HomeRoute = r('Home')
+export const NestedRoute = r('Nested')
+export const PeopleRoute = r('People', { searchText: S.Option(S.String) })
+export const PersonRoute = r('Person', { personId: S.Number })
+export const FilesIndexRoute = r('FilesIndex')
+export const FilesRoute = r('Files', { path: S.NonEmptyArray(S.String) })
+export const NotFoundRoute = r('NotFound', { path: S.String })
+
+export const AppRoute = S.Union([
+  HomeRoute,
+  NestedRoute,
+  PeopleRoute,
+  PersonRoute,
+  FilesIndexRoute,
+  FilesRoute,
+  NotFoundRoute,
+])
+
+export type HomeRoute = typeof HomeRoute.Type
+export type NestedRoute = typeof NestedRoute.Type
+export type PeopleRoute = typeof PeopleRoute.Type
+export type PersonRoute = typeof PersonRoute.Type
+export type FilesIndexRoute = typeof FilesIndexRoute.Type
+export type FilesRoute = typeof FilesRoute.Type
+export type NotFoundRoute = typeof NotFoundRoute.Type
+export type AppRoute = typeof AppRoute.Type
+
+export const homeRouter = pipe(Route.root, Route.mapTo(HomeRoute))
+
+export const nestedRouter = pipe(
+  literal('nested'),
+  slash(literal('route')),
+  slash(literal('is')),
+  slash(literal('very')),
+  slash(literal('nested')),
+  Route.mapTo(NestedRoute),
+)
+
+export const peopleRouter = pipe(
+  literal('people'),
+  Route.query(
+    S.Struct({
+      searchText: S.OptionFromOptional(S.String),
+    }),
+  ),
+  Route.mapTo(PeopleRoute),
+)
+
+export const personRouter = pipe(
+  literal('people'),
+  slash(int('personId')),
+  Route.mapTo(PersonRoute),
+)
+
+export const filesIndexRouter = pipe(
+  literal('files'),
+  Route.mapTo(FilesIndexRoute),
+)
+
+export const filesRouter = pipe(
+  literal('files'),
+  slash(rest('path')),
+  Route.mapTo(FilesRoute),
+)
+
+const routeParser = Route.oneOf(
+  personRouter,
+  peopleRouter,
+  filesIndexRouter,
+  filesRouter,
+  nestedRouter,
+  homeRouter,
+)
+
+export const urlToAppRoute = Route.parseUrlWithFallback(
+  routeParser,
+  NotFoundRoute,
+)

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

@@ -0,0 +1,180 @@
+import { Array, Option, String } from 'effect'
+import { expect, given, role, scene, text } from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import {
+  FilesIndexRoute,
+  FilesRoute,
+  HomeRoute,
+  Model,
+  NestedRoute,
+  NotFoundRoute,
+  PeopleRoute,
+  PersonRoute,
+  update,
+  view,
+} from './main'
+import { People } from './page'
+
+const peoplePageWith = (searchInput: string) =>
+  People.Model.make({
+    searchInput,
+    searchHistory: Array.liftPredicate(String.isNonEmpty)(searchInput),
+    results: People.SearchLoaded({
+      query: searchInput,
+      people: People.searchPeople(searchInput),
+    }),
+  })
+
+const initialPeoplePage = peoplePageWith('')
+
+const home = Model.make({ route: HomeRoute(), peoplePage: initialPeoplePage })
+const people = (searchInput: string) =>
+  Model.make({
+    route: PeopleRoute({
+      searchText: Option.liftPredicate(String.isNonEmpty)(searchInput),
+    }),
+    peoplePage: peoplePageWith(searchInput),
+  })
+const person = (personId: number) =>
+  Model.make({
+    route: PersonRoute({ personId }),
+    peoplePage: initialPeoplePage,
+  })
+const nested = Model.make({
+  route: NestedRoute(),
+  peoplePage: initialPeoplePage,
+})
+const filesIndex = Model.make({
+  route: FilesIndexRoute(),
+  peoplePage: initialPeoplePage,
+})
+const files = (path: Array.NonEmptyReadonlyArray<string>) =>
+  Model.make({
+    route: FilesRoute({ path }),
+    peoplePage: initialPeoplePage,
+  })
+const notFound = (path: string) =>
+  Model.make({
+    route: NotFoundRoute({ path }),
+    peoplePage: initialPeoplePage,
+  })
+
+describe('view', () => {
+  test('the nav bar appears on every route', () => {
+    scene(
+      { update, view },
+      given(home),
+      expect(role('link', { name: 'Home' })).toExist(),
+      expect(role('link', { name: 'People' })).toExist(),
+      expect(role('link', { name: 'Files' })).toExist(),
+      expect(role('link', { name: 'Nested' })).toExist(),
+    )
+  })
+
+  test('the Home route renders its welcome heading', () => {
+    scene(
+      { update, view },
+      given(home),
+      expect(role('heading', { name: 'Welcome Home' })).toExist(),
+    )
+  })
+
+  test('the Nested route renders its deep-route message', () => {
+    scene(
+      { update, view },
+      given(nested),
+      expect(role('heading', { name: 'Very Nested Route!' })).toExist(),
+    )
+  })
+
+  test('the People route lists every person', () => {
+    scene(
+      { update, view },
+      given(people('')),
+      expect(text('Alice Johnson')).toExist(),
+      expect(text('Bob Smith')).toExist(),
+      expect(text('Carol Davis')).toExist(),
+      expect(text('David Wilson')).toExist(),
+      expect(text('Eva Brown')).toExist(),
+    )
+  })
+
+  test('a search filters People to matches by name or role', () => {
+    scene(
+      { update, view },
+      given(people('designer')),
+      expect(text('Alice Johnson')).toExist(),
+      expect(text('Eva Brown')).toExist(),
+      expect(text('Bob Smith')).toBeAbsent(),
+      expect(text('2 results', { exact: false })).toExist(),
+    )
+  })
+
+  test('a valid Person route renders the person details', () => {
+    scene(
+      { update, view },
+      given(person(1)),
+      expect(role('heading', { name: 'Alice Johnson' })).toExist(),
+      expect(text('Designer')).toExist(),
+      expect(role('link', { name: '← Back to People' })).toExist(),
+    )
+  })
+
+  test('an unknown Person id renders the not-found panel', () => {
+    scene(
+      { update, view },
+      given(person(99)),
+      expect(role('heading', { name: 'Person Not Found' })).toExist(),
+      expect(text('No person found with ID: 99')).toExist(),
+    )
+  })
+
+  test('the Files index lists the top-level entries', () => {
+    scene(
+      { update, view },
+      given(filesIndex),
+      expect(role('link', { name: 'documents' })).toExist(),
+      expect(role('link', { name: 'photos' })).toExist(),
+      expect(role('link', { name: 'notes.txt' })).toExist(),
+    )
+  })
+
+  test('a directory path renders breadcrumb links and its entries', () => {
+    scene(
+      { update, view },
+      given(files(['documents', 'taxes'])),
+      expect(role('link', { name: 'documents' })).toExist(),
+      expect(role('link', { name: '2024.pdf' })).toExist(),
+      expect(role('link', { name: '2025.pdf' })).toExist(),
+    )
+  })
+
+  test('a file path renders the file details', () => {
+    scene(
+      { update, view },
+      given(files(['documents', 'resume.pdf'])),
+      expect(role('heading', { name: 'resume.pdf' })).toExist(),
+      expect(text('47.1 KB')).toExist(),
+    )
+  })
+
+  test('an unknown path under files renders the missing panel', () => {
+    scene(
+      { update, view },
+      given(files(['documents', 'missing.txt'])),
+      expect(role('heading', { name: 'Nothing Here' })).toExist(),
+      expect(role('link', { name: '← Back to Files' })).toExist(),
+    )
+  })
+
+  test('an unmatched URL renders the NotFound view', () => {
+    scene(
+      { update, view },
+      given(notFound('/missing')),
+      expect(role('heading', { name: '404 - Page Not Found' })).toExist(),
+      expect(text('The path "/missing" was not found.')).toExist(),
+      expect(role('link', { name: '← Go Home' })).toExist(),
+    )
+  })
+})