create-foldkit-app 0.27.3 → 0.28.0

package/dist/templates/examples/state-machine/src/main.ts

@@ -0,0 +1,420 @@
+import {
+  Array,
+  Duration,
+  Effect,
+  Match as M,
+  Number,
+  Option,
+  Schema as S,
+  String,
+  flow,
+  pipe,
+} from 'effect'
+import { Command, Runtime, Update } from 'foldkit'
+import { Machine } from 'foldkit/experimental'
+import { otherwise, to, when } from 'foldkit/experimental/machine'
+import { defineMessageUnion } from 'foldkit/message'
+import { ts } from 'foldkit/schema'
+import { evo } from 'foldkit/struct'
+
+import { RadioGroup } from '@foldkit/ui'
+
+// MODEL
+
+export const Discount = S.Struct({
+  code: S.String,
+  percentOff: S.Number,
+})
+
+export const NoPromo = ts('NoPromo')
+export const AppliedPromo = ts('AppliedPromo', { discount: Discount })
+export const RejectedPromo = ts('RejectedPromo')
+
+export const Promo = S.Union([NoPromo, AppliedPromo, RejectedPromo])
+
+export const Cart = ts('Cart', { isShippingRequired: S.Boolean })
+export const Shipping = ts('Shipping', { isShippingRequired: S.Boolean })
+export const Payment = ts('Payment', {
+  isPaymentMethodSelected: S.Boolean,
+  isShippingRequired: S.Boolean,
+})
+export const Review = ts('Review', {
+  isPaymentMethodSelected: S.Boolean,
+  isShippingRequired: S.Boolean,
+  isTermsAccepted: S.Boolean,
+  promo: Promo,
+  promoCodeInput: S.String,
+})
+export const Placing = ts('Placing', {
+  isShippingRequired: S.Boolean,
+  maybeDiscount: S.Option(Discount),
+})
+export const Confirmed = ts('Confirmed', {
+  isShippingRequired: S.Boolean,
+  maybeDiscount: S.Option(Discount),
+  orderId: S.String,
+})
+export const Cancelled = ts('Cancelled', {
+  isShippingRequired: S.Boolean,
+})
+export const CheckoutState = S.Union([
+  Cart,
+  Shipping,
+  Payment,
+  Review,
+  Placing,
+  Confirmed,
+  Cancelled,
+])
+
+export const TransitionLogEntry = S.Struct({
+  id: S.Number,
+  summary: S.String,
+})
+export type TransitionLogEntry = typeof TransitionLogEntry.Type
+
+const EDITION_RADIO_GROUP_ID = 'edition'
+
+export const HARDCOVER_EDITION = 'Hardcover'
+export const EBOOK_EDITION = 'E-book'
+
+export const EDITIONS: ReadonlyArray<string> = [
+  HARDCOVER_EDITION,
+  EBOOK_EDITION,
+]
+
+export const editionName = (isShippingRequired: boolean): string =>
+  isShippingRequired ? HARDCOVER_EDITION : EBOOK_EDITION
+
+export const EditionRadioGroup = RadioGroup.create()
+
+export const Model = S.Struct({
+  checkout: CheckoutState,
+  editionRadioGroup: RadioGroup.Model,
+  transitionLog: S.Array(TransitionLogEntry),
+  nextTransitionLogId: S.Number,
+})
+export type Model = typeof Model.Type
+
+// MESSAGE
+
+export const Message = defineMessageUnion({
+  ClickedContinue: {},
+  ClickedBack: {},
+  ClickedCancel: {},
+  ClickedPlaceOrder: {},
+  ClickedStartOver: {},
+  ToggledPaymentMethod: { isSelected: S.Boolean },
+  SelectedEdition: { isShippingRequired: S.Boolean },
+  GotEditionRadioGroupMessage: { message: RadioGroup.Message },
+  ToggledTermsAccepted: { isAccepted: S.Boolean },
+  UpdatedPromoCode: { value: S.String },
+  SubmittedPromoCode: {},
+  SucceededPlaceOrder: { orderId: S.String },
+})
+
+export type Message = typeof Message.Type
+
+// COMMAND
+
+const PLACE_ORDER_DELAY = Duration.seconds(1)
+
+export const PlaceOrder = Command.define('PlaceOrder', {
+  args: { isShippingRequired: S.Boolean },
+  messages: [Message.SucceededPlaceOrder],
+  execute: ({ isShippingRequired }) =>
+    Effect.gen(function* () {
+      yield* Effect.sleep(PLACE_ORDER_DELAY)
+      return Message.SucceededPlaceOrder({
+        orderId: isShippingRequired ? 'SHIP-1001' : 'DIGI-1001',
+      })
+    }),
+})
+
+// MACHINE
+
+const PROMO_DISCOUNTS: ReadonlyArray<typeof Discount.Type> = [
+  { code: 'READER10', percentOff: 10 },
+  { code: 'SIGNAL20', percentOff: 20 },
+]
+
+export const promoToMaybeDiscount = (
+  promo: typeof Promo.Type,
+): Option.Option<typeof Discount.Type> =>
+  M.value(promo).pipe(
+    M.tags({ AppliedPromo: appliedPromo => appliedPromo.discount }),
+    M.option,
+  )
+
+export const isReviewReady = (review: typeof Review.Type): boolean =>
+  review.isPaymentMethodSelected && review.isTermsAccepted
+
+export const reviewToMaybeDiscount = (
+  review: typeof Review.Type,
+): Option.Option<typeof Discount.Type> => {
+  const normalizedCode = pipe(
+    review.promoCodeInput,
+    String.trim,
+    String.toUpperCase,
+  )
+
+  return Array.findFirst(
+    PROMO_DISCOUNTS,
+    discount => discount.code === normalizedCode,
+  )
+}
+
+export const checkoutMachine = Machine.define({
+  state: CheckoutState,
+  message: Message,
+})({
+  initial: Cart({ isShippingRequired: true }),
+  states: {
+    Cart: {
+      on: {
+        SelectedEdition: to('Cart', ({ state, message }) =>
+          evo(state, { isShippingRequired: () => message.isShippingRequired }),
+        ),
+        ClickedContinue: [
+          when(
+            state => state.isShippingRequired,
+            'Shipping',
+            ({ state }) =>
+              Shipping({ isShippingRequired: state.isShippingRequired }),
+          ),
+          otherwise(
+            to('Payment', ({ state }) =>
+              Payment({
+                isPaymentMethodSelected: false,
+                isShippingRequired: state.isShippingRequired,
+              }),
+            ),
+          ),
+        ],
+        ClickedCancel: to('Cancelled', ({ state }) =>
+          Cancelled({ isShippingRequired: state.isShippingRequired }),
+        ),
+      },
+    },
+    Shipping: {
+      on: {
+        ClickedContinue: to('Payment', ({ state }) =>
+          Payment({
+            isPaymentMethodSelected: false,
+            isShippingRequired: state.isShippingRequired,
+          }),
+        ),
+        ClickedBack: to('Cart', ({ state }) =>
+          Cart({ isShippingRequired: state.isShippingRequired }),
+        ),
+        ClickedCancel: to('Cancelled', ({ state }) =>
+          Cancelled({ isShippingRequired: state.isShippingRequired }),
+        ),
+      },
+    },
+    Payment: {
+      on: {
+        ToggledPaymentMethod: to('Payment', ({ state, message }) =>
+          evo(state, { isPaymentMethodSelected: () => message.isSelected }),
+        ),
+        ClickedContinue: to('Review', ({ state }) =>
+          Review({
+            isPaymentMethodSelected: state.isPaymentMethodSelected,
+            isShippingRequired: state.isShippingRequired,
+            isTermsAccepted: false,
+            promo: NoPromo(),
+            promoCodeInput: '',
+          }),
+        ),
+        ClickedBack: [
+          when(
+            state => state.isShippingRequired,
+            'Shipping',
+            ({ state }) =>
+              Shipping({ isShippingRequired: state.isShippingRequired }),
+          ),
+          otherwise(
+            to('Cart', ({ state }) =>
+              Cart({ isShippingRequired: state.isShippingRequired }),
+            ),
+          ),
+        ],
+        ClickedCancel: to('Cancelled', ({ state }) =>
+          Cancelled({ isShippingRequired: state.isShippingRequired }),
+        ),
+      },
+    },
+    Review: {
+      on: {
+        ToggledPaymentMethod: to('Review', ({ state, message }) =>
+          evo(state, { isPaymentMethodSelected: () => message.isSelected }),
+        ),
+        ToggledTermsAccepted: to('Review', ({ state, message }) =>
+          evo(state, { isTermsAccepted: () => message.isAccepted }),
+        ),
+        UpdatedPromoCode: to('Review', ({ state, message }) =>
+          evo(state, {
+            promoCodeInput: () => message.value,
+            promo: currentPromo =>
+              currentPromo._tag === 'RejectedPromo' ? NoPromo() : currentPromo,
+          }),
+        ),
+        SubmittedPromoCode: [
+          when(
+            reviewToMaybeDiscount,
+            'Review',
+            ({ state, guardValue: discount }) =>
+              evo(state, { promo: () => AppliedPromo({ discount }) }),
+          ),
+          otherwise(
+            to('Review', ({ state }) =>
+              evo(state, { promo: () => RejectedPromo() }),
+            ),
+          ),
+        ],
+        ClickedPlaceOrder: [
+          when(
+            isReviewReady,
+            'Placing',
+            ({ state }) =>
+              Placing({
+                isShippingRequired: state.isShippingRequired,
+                maybeDiscount: promoToMaybeDiscount(state.promo),
+              }),
+            ({ state }) => [
+              PlaceOrder({ isShippingRequired: state.isShippingRequired }),
+            ],
+          ),
+        ],
+        ClickedBack: to('Payment', ({ state }) =>
+          Payment({
+            isPaymentMethodSelected: state.isPaymentMethodSelected,
+            isShippingRequired: state.isShippingRequired,
+          }),
+        ),
+        ClickedCancel: to('Cancelled', ({ state }) =>
+          Cancelled({ isShippingRequired: state.isShippingRequired }),
+        ),
+      },
+    },
+    Placing: {
+      on: {
+        SucceededPlaceOrder: to('Confirmed', ({ state, message }) =>
+          Confirmed({
+            isShippingRequired: state.isShippingRequired,
+            maybeDiscount: state.maybeDiscount,
+            orderId: message.orderId,
+          }),
+        ),
+      },
+    },
+    Confirmed: {
+      on: {
+        ClickedStartOver: to('Cart', ({ state }) =>
+          Cart({ isShippingRequired: state.isShippingRequired }),
+        ),
+      },
+    },
+    Cancelled: {
+      on: {
+        ClickedStartOver: to('Cart', ({ state }) =>
+          Cart({ isShippingRequired: state.isShippingRequired }),
+        ),
+      },
+    },
+  },
+})
+
+// INIT
+
+export const initialModel = Model.make({
+  checkout: checkoutMachine.initial,
+  editionRadioGroup: RadioGroup.init({ id: EDITION_RADIO_GROUP_ID }),
+  transitionLog: [],
+  nextTransitionLogId: 0,
+})
+
+export const init: Runtime.ApplicationInit<Model, Message> = () => [
+  initialModel,
+  [],
+]
+
+// UPDATE
+
+type UpdateReturn = readonly [Model, ReadonlyArray<Command.Command<Message>>]
+
+export const TRANSITION_LOG_LIMIT = 20
+
+const resultToTransitionSummary = (
+  result: Machine.TransitionResult<typeof CheckoutState.Type, Message>,
+): string =>
+  M.value(result).pipe(
+    M.tagsExhaustive({
+      Transitioned: ({ from, messageTag, target }) =>
+        `${from} -> ${target} on ${messageTag}`,
+      Ignored: ({ messageTag, stateTag }) =>
+        `${messageTag} ignored in ${stateTag}`,
+    }),
+  )
+
+const stepMachine =
+  (message: Message) =>
+  (model: Model): UpdateReturn => {
+    const result = checkoutMachine.step(model.checkout, message)
+
+    const { state: nextCheckout } = result
+
+    const transitionCommands = M.value(result).pipe(
+      M.tagsExhaustive({
+        Transitioned: ({ commands }) => commands,
+        Ignored: () => [],
+      }),
+    )
+
+    const transitionLogEntry: TransitionLogEntry = {
+      id: model.nextTransitionLogId,
+      summary: resultToTransitionSummary(result),
+    }
+
+    return [
+      evo(model, {
+        checkout: () => nextCheckout,
+        transitionLog: flow(
+          Array.prepend(transitionLogEntry),
+          Array.take(TRANSITION_LOG_LIMIT),
+        ),
+        nextTransitionLogId: Number.increment,
+      }),
+      transitionCommands,
+    ]
+  }
+
+const foldEditionRadioGroupOutMessage = M.type<RadioGroup.OutMessage>().pipe(
+  M.withReturnType<Update.Step<Model, Message>>(),
+  M.tagsExhaustive({
+    Selected: ({ value }) =>
+      stepMachine(
+        Message.SelectedEdition({
+          isShippingRequired: value === HARDCOVER_EDITION,
+        }),
+      ),
+  }),
+)
+
+const foldEditionRadioGroup = Update.foldChild({
+  update: EditionRadioGroup.update,
+  read: (model: Model) => Option.some(model.editionRadioGroup),
+  write: (model, nextEditionRadioGroup) =>
+    evo(model, { editionRadioGroup: () => nextEditionRadioGroup }),
+  toParentMessage: message => Message.GotEditionRadioGroupMessage({ message }),
+  foldOutMessage: foldEditionRadioGroupOutMessage,
+})
+
+export const update = (model: Model, message: Message): UpdateReturn =>
+  M.value(message).pipe(
+    M.withReturnType<UpdateReturn>(),
+    M.tag('GotEditionRadioGroupMessage', ({ message }) =>
+      foldEditionRadioGroup(model, message),
+    ),
+    M.orElse(() => stepMachine(message)(model)),
+  )

package/dist/templates/examples/state-machine/src/scene.test.ts

@@ -0,0 +1,85 @@
+import {
+  Command,
+  click,
+  expect,
+  given,
+  label,
+  role,
+  scene,
+  text,
+  type,
+} from 'foldkit/scene'
+import { describe, test } from 'vitest'
+
+import { RadioGroup } from '@foldkit/ui'
+import { Message as RadioGroupMessage } from '@foldkit/ui/radioGroup'
+
+import { Message, PlaceOrder, initialModel, update } from './main'
+import { view } from './view'
+
+const resolveFocusOption = Command.resolve(
+  RadioGroup.FocusOption,
+  RadioGroupMessage.CompletedFocusOption(),
+)
+
+describe('scene', () => {
+  test('initial view shows the hardcover order and state machine inspector', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      expect(role('heading', { name: 'Your order' })).toExist(),
+      expect(role('radio', { name: 'Hardcover' })).toBeChecked(),
+      expect(role('heading', { name: 'State machine inspector' })).toExist(),
+      expect(text('stateDiagram-v2', { exact: false })).toExist(),
+    )
+  })
+
+  test('digital order skips Shipping and can be confirmed', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      click(role('radio', { name: 'E-book' })),
+      resolveFocusOption,
+      expect(role('radio', { name: 'E-book' })).toBeChecked(),
+      click(role('button', { name: 'Continue to payment' })),
+      expect(role('heading', { name: 'Payment' })).toExist(),
+      expect(role('button', { name: 'Review order' })).toBeDisabled(),
+      click(role('checkbox', { name: 'Mastercard •••• 4242' })),
+      expect(role('button', { name: 'Review order' })).toBeEnabled(),
+      click(role('button', { name: 'Review order' })),
+      expect(role('heading', { name: 'Review and place order' })).toExist(),
+      expect(role('button', { name: 'Place order · $30.31' })).toBeDisabled(),
+      click(role('checkbox', { name: 'Accept terms of sale' })),
+      expect(role('button', { name: 'Place order · $30.31' })).toBeEnabled(),
+      click(role('button', { name: 'Place order · $30.31' })),
+      Command.expectExact(PlaceOrder({ isShippingRequired: false })),
+      expect(role('heading', { name: 'Processing your order' })).toExist(),
+      Command.resolve(
+        PlaceOrder,
+        Message.SucceededPlaceOrder({ orderId: 'DIGI-1001' }),
+      ),
+      expect(text('Order DIGI-1001 confirmed')).toExist(),
+    )
+  })
+
+  test('an applied promo code discounts the order total', () => {
+    scene(
+      { update, view },
+      given(initialModel),
+      click(role('radio', { name: 'E-book' })),
+      resolveFocusOption,
+      click(role('button', { name: 'Continue to payment' })),
+      click(role('checkbox', { name: 'Mastercard •••• 4242' })),
+      click(role('button', { name: 'Review order' })),
+      type(label('Promo code'), 'reader10'),
+      click(role('button', { name: 'Apply' })),
+      expect(text('READER10 applied · 10% off')).toExist(),
+      expect(text('Discount · READER10')).toExist(),
+      expect(role('button', { name: 'Place order · $27.28' })).toExist(),
+      type(label('Promo code'), 'bogus'),
+      click(role('button', { name: 'Apply' })),
+      expect(text("That code isn't recognized.")).toExist(),
+      expect(role('button', { name: 'Place order · $30.31' })).toExist(),
+    )
+  })
+})

package/dist/templates/examples/state-machine/src/story.test.ts

@@ -0,0 +1,199 @@
+import { Array, Effect, Fiber, Option, Ref, pipe } from 'effect'
+import { TestClock } from 'effect/testing'
+import { Command, given, message, model, story } from 'foldkit/story'
+import { describe, expect, test } from 'vitest'
+
+import {
+  AppliedPromo,
+  Cart,
+  Message,
+  PlaceOrder,
+  RejectedPromo,
+  TRANSITION_LOG_LIMIT,
+  initialModel,
+  update,
+} from './main'
+import type { Model } from './main'
+
+const maybeLatestTransitionSummary = (model: Model): Option.Option<string> =>
+  pipe(
+    Array.head(model.transitionLog),
+    Option.map(entry => entry.summary),
+  )
+
+describe('update', () => {
+  test('PlaceOrder waits before succeeding', () =>
+    Effect.runPromise(
+      Effect.gen(function* () {
+        const didComplete = yield* Ref.make(false)
+        const fiber = yield* Effect.forkChild(
+          PlaceOrder({ isShippingRequired: false }).effect.pipe(
+            Effect.tap(() => Ref.set(didComplete, true)),
+          ),
+          { startImmediately: true },
+        )
+
+        yield* TestClock.adjust('999 millis')
+        expect(yield* Ref.get(didComplete)).toBe(false)
+
+        yield* TestClock.adjust('1 millis')
+        expect(yield* Fiber.join(fiber)).toStrictEqual(
+          Message.SucceededPlaceOrder({ orderId: 'DIGI-1001' }),
+        )
+      }).pipe(Effect.scoped, Effect.provide(TestClock.layer())),
+    ))
+
+  test('physical carts visit Shipping before Payment', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.ClickedContinue()),
+      Command.expectNone(),
+      model(model => {
+        expect(model.checkout._tag).toBe('Shipping')
+        expect(maybeLatestTransitionSummary(model)).toEqual(
+          Option.some('Cart -> Shipping on ClickedContinue'),
+        )
+      }),
+      message(Message.ClickedContinue()),
+      model(model => {
+        expect(model.checkout._tag).toBe('Payment')
+        expect(Array.map(model.transitionLog, entry => entry.summary)).toEqual([
+          'Shipping -> Payment on ClickedContinue',
+          'Cart -> Shipping on ClickedContinue',
+        ])
+      }),
+    )
+  })
+
+  test('digital carts skip Shipping through the otherwise branch', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.SelectedEdition({ isShippingRequired: false })),
+      message(Message.ClickedContinue()),
+      model(model => {
+        expect(model.checkout._tag).toBe('Payment')
+      }),
+      message(Message.ClickedBack()),
+      model(model => {
+        expect(model.checkout._tag).toBe('Cart')
+      }),
+    )
+  })
+
+  test('starting over after cancelling keeps the selected edition', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.SelectedEdition({ isShippingRequired: false })),
+      message(Message.ClickedCancel()),
+      model(model => {
+        expect(model.checkout._tag).toBe('Cancelled')
+      }),
+      message(Message.ClickedStartOver()),
+      model(model => {
+        expect(model.checkout).toStrictEqual(
+          Cart({ isShippingRequired: false }),
+        )
+      }),
+    )
+  })
+
+  test('a known promo code resolves to a discount and an unknown one clears it', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.SelectedEdition({ isShippingRequired: false })),
+      message(Message.ClickedContinue()),
+      message(Message.ToggledPaymentMethod({ isSelected: true })),
+      message(Message.ClickedContinue()),
+      message(Message.UpdatedPromoCode({ value: ' reader10 ' })),
+      message(Message.SubmittedPromoCode()),
+      model(model => {
+        expect(model.checkout._tag).toBe('Review')
+        if (model.checkout._tag === 'Review') {
+          expect(model.checkout.promo).toEqual(
+            AppliedPromo({ discount: { code: 'READER10', percentOff: 10 } }),
+          )
+        }
+      }),
+      message(Message.UpdatedPromoCode({ value: 'BOGUS' })),
+      message(Message.SubmittedPromoCode()),
+      model(model => {
+        expect(model.checkout._tag).toBe('Review')
+        if (model.checkout._tag === 'Review') {
+          expect(model.checkout.promo).toEqual(RejectedPromo())
+        }
+        expect(maybeLatestTransitionSummary(model)).toEqual(
+          Option.some('Review -> Review on SubmittedPromoCode'),
+        )
+      }),
+    )
+  })
+
+  test('unaccepted review ignores place order without a Command', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.SelectedEdition({ isShippingRequired: false })),
+      message(Message.ClickedContinue()),
+      message(Message.ToggledPaymentMethod({ isSelected: true })),
+      message(Message.ClickedContinue()),
+      message(Message.ClickedPlaceOrder()),
+      Command.expectNone(),
+      model(model => {
+        expect(model.checkout._tag).toBe('Review')
+        expect(maybeLatestTransitionSummary(model)).toEqual(
+          Option.some('ClickedPlaceOrder ignored in Review'),
+        )
+      }),
+    )
+  })
+
+  test('ready review emits PlaceOrder after its guard passes', () => {
+    story(
+      update,
+      given(initialModel),
+      message(Message.SelectedEdition({ isShippingRequired: false })),
+      message(Message.ClickedContinue()),
+      message(Message.ToggledPaymentMethod({ isSelected: true })),
+      message(Message.ClickedContinue()),
+      message(Message.ToggledTermsAccepted({ isAccepted: true })),
+      message(Message.ClickedPlaceOrder()),
+      Command.expectExact(PlaceOrder({ isShippingRequired: false })),
+      Command.resolve(
+        PlaceOrder,
+        Message.SucceededPlaceOrder({ orderId: 'DIGI-1001' }),
+      ),
+      model(model => {
+        expect(model.checkout._tag).toBe('Confirmed')
+        if (model.checkout._tag === 'Confirmed') {
+          expect(model.checkout.orderId).toBe('DIGI-1001')
+        }
+      }),
+    )
+  })
+
+  test('the transition log truncates to the newest twenty entries', () => {
+    const messageCount = TRANSITION_LOG_LIMIT + 5
+
+    const finalModel = pipe(
+      Array.makeBy(messageCount, index =>
+        Message.SelectedEdition({ isShippingRequired: index % 2 === 0 }),
+      ),
+      Array.reduce(initialModel, (model, message) => {
+        const [nextModel] = update(model, message)
+        return nextModel
+      }),
+    )
+
+    expect(finalModel.transitionLog).toHaveLength(TRANSITION_LOG_LIMIT)
+    expect(
+      Option.map(Array.head(finalModel.transitionLog), entry => entry.id),
+    ).toEqual(Option.some(messageCount - 1))
+    expect(
+      Option.map(Array.last(finalModel.transitionLog), entry => entry.id),
+    ).toEqual(Option.some(messageCount - TRANSITION_LOG_LIMIT))
+  })
+})