Update docs

2026-07-27 03:16:44 +02:00
parent 74cacc8d61
commit b302b31fa9
2 changed files with 151 additions and 118 deletions
@@ -171,124 +171,6 @@ Pass `initialEncodedValue` only when the first draft should differ from the
 encoded target. Otherwise `LensForm.service` obtains the initial draft by
 encoding the target through the schema.

-## Example: local date input, UTC domain value
-
-The encoded/decoded distinction is especially useful for dates. An HTML
-`datetime-local` input produces a wall-clock string such as
-`"2026-07-22T14:30"`. It contains no time-zone or UTC offset, while application
-state and APIs usually need an unambiguous UTC instant.
-
-A schema can own that entire conversion. The following schema interprets the
-input in the current time zone and decodes it to `DateTime.Utc`:
-
-```tsx title="src/DateTimeUtcFromZonedInput.ts"
-import { DateTime, Effect, Option, ParseResult, Schema } from "effect"
-
-class DateTimeUtcFromZoned extends Schema.transformOrFail(
-  Schema.DateTimeZonedFromSelf,
-  Schema.DateTimeUtcFromSelf,
-  {
-    strict: true,
-    decode: (input) => ParseResult.succeed(DateTime.toUtc(input)),
-    encode: DateTime.setZoneCurrent,
-  },
-) {}
-
-export class DateTimeUtcFromZonedInput extends Schema.transformOrFail(
-  Schema.String,
-  DateTimeUtcFromZoned,
-  {
-    strict: true,
-    decode: (input, _options, ast) =>
-      Effect.flatMap(DateTime.CurrentTimeZone, (timeZone) =>
-        Option.match(
-          DateTime.makeZoned(input, {
-            timeZone,
-            adjustForTimeZone: true,
-          }),
-          {
-            onSome: ParseResult.succeed,
-            onNone: () =>
-              ParseResult.fail(
-                new ParseResult.Type(
-                  ast,
-                  input,
-                  "Enter a valid date and time",
-                ),
-              ),
-          },
-        ),
-      ),
-    encode: (value) =>
-      ParseResult.succeed(
-        DateTime.formatIsoZoned(value).slice(0, 16),
-      ),
-  },
-) {}
-```
-
-Use it like any other field schema. The form and input work with a string, but
-the mutation receives UTC:
-
-```tsx
-import { DateTime, Effect, Schema } from "effect"
-import { Component, Form, MutationForm, View } from "effect-view"
-import { DateTimeUtcFromZonedInput } from "./DateTimeUtcFromZonedInput"
-
-const AppointmentSchema = Schema.Struct({
-  startsAt: DateTimeUtcFromZonedInput,
-})
-
-const AppointmentView = Component.make("Appointment")(function* () {
-  const [form, startsAtField] = yield* Component.useOnMount(() =>
-    Effect.gen(function* () {
-      const form = yield* MutationForm.service({
-        schema: AppointmentSchema,
-        initialEncodedValue: { startsAt: "" },
-        f: ([appointment]) =>
-          Effect.log(
-            `Saving ${DateTime.formatIso(appointment.startsAt)}`,
-          ),
-      })
-
-      return [form, Form.focusObjectOn(form, "startsAt")] as const
-    }),
-  )
-
-  const startsAt = yield* Form.useInput(startsAtField)
-  const [canCommit] = yield* View.useAll([form.canCommit])
-  const runPromise = yield* Component.useRunPromise()
-
-  return (
-    <form
-      onSubmit={(event) => {
-        event.preventDefault()
-        void runPromise(form.submit)
-      }}
-    >
-      <input
-        type="datetime-local"
-        value={startsAt.value}
-        onChange={(event) =>
-          startsAt.setValue(event.currentTarget.value)
-        }
-      />
-      <button disabled={!canCommit}>Save appointment</button>
-    </form>
-  )
-})
-```
-
-The schema requires `DateTime.CurrentTimeZone`; provide
-`DateTime.layerCurrentZoneLocal` in the application runtime. If the current
-zone is `Europe/Paris`, for example, entering `2026-07-22T14:30` decodes to the
-UTC instant `2026-07-22T12:30:00.000Z`.
-
-Encoding works in the other direction. A `LensForm` whose target contains that
-UTC instant presents `2026-07-22T14:30` to the local input. The component never
-manually parses dates, applies offsets, or maintains a second representation;
-the schema defines both directions and the form keeps them synchronized.
-
 ## Focus into subforms

 The root `MutationForm` or `LensForm` represents the complete schema. UI
@@ -308,6 +190,16 @@ const contactForm = Form.focusObjectOn(form, "contact")
 const emailField = Form.focusObjectOn(contactForm, "email")
 ```

+Form focus helpers also have a dual API. Pass only the key or index to get a curried function. Curried helpers can be chained
+with `pipe` to focus through a deeper path:
+
+```tsx
+const emailField = form.pipe(
+  Form.focusObjectOn("contact"),
+  Form.focusObjectOn("email"),
+)
+```
+
 `displayNameField`, `ageField`, and `emailField` can each be passed to the input
 component responsible for that field. Focusing can also be repeated:
 `contactForm` represents the complete contact section, and `emailField`
@@ -463,3 +355,121 @@ They expose the schema pipeline as reactive Lenses and Views:
 The form model itself is Effect code. Effect View adds the React-facing hooks,
 including `Form.useInput` and `Form.useOptionalInput`, while your own component
 library remains responsible for rendering controls and layout.
+
+## Example: local date input, UTC domain value
+
+The encoded/decoded distinction is especially useful for dates. An HTML
+`datetime-local` input produces a wall-clock string such as
+`"2026-07-22T14:30"`. It contains no time-zone or UTC offset, while application
+state and APIs usually need an unambiguous UTC instant.
+
+A schema can own that entire conversion. The following schema interprets the
+input in the current time zone and decodes it to `DateTime.Utc`:
+
+```tsx title="src/DateTimeUtcFromZonedInput.ts"
+import { DateTime, Effect, Option, ParseResult, Schema } from "effect"
+
+class DateTimeUtcFromZoned extends Schema.transformOrFail(
+  Schema.DateTimeZonedFromSelf,
+  Schema.DateTimeUtcFromSelf,
+  {
+    strict: true,
+    decode: (input) => ParseResult.succeed(DateTime.toUtc(input)),
+    encode: DateTime.setZoneCurrent,
+  },
+) {}
+
+export class DateTimeUtcFromZonedInput extends Schema.transformOrFail(
+  Schema.String,
+  DateTimeUtcFromZoned,
+  {
+    strict: true,
+    decode: (input, _options, ast) =>
+      Effect.flatMap(DateTime.CurrentTimeZone, (timeZone) =>
+        Option.match(
+          DateTime.makeZoned(input, {
+            timeZone,
+            adjustForTimeZone: true,
+          }),
+          {
+            onSome: ParseResult.succeed,
+            onNone: () =>
+              ParseResult.fail(
+                new ParseResult.Type(
+                  ast,
+                  input,
+                  "Enter a valid date and time",
+                ),
+              ),
+          },
+        ),
+      ),
+    encode: (value) =>
+      ParseResult.succeed(
+        DateTime.formatIsoZoned(value).slice(0, 16),
+      ),
+  },
+) {}
+```
+
+Use it like any other field schema. The form and input work with a string, but
+the mutation receives UTC:
+
+```tsx
+import { DateTime, Effect, Schema } from "effect"
+import { Component, Form, MutationForm, View } from "effect-view"
+import { DateTimeUtcFromZonedInput } from "./DateTimeUtcFromZonedInput"
+
+const AppointmentSchema = Schema.Struct({
+  startsAt: DateTimeUtcFromZonedInput,
+})
+
+const AppointmentView = Component.make("Appointment")(function* () {
+  const [form, startsAtField] = yield* Component.useOnMount(() =>
+    Effect.gen(function* () {
+      const form = yield* MutationForm.service({
+        schema: AppointmentSchema,
+        initialEncodedValue: { startsAt: "" },
+        f: ([appointment]) =>
+          Effect.log(
+            `Saving ${DateTime.formatIso(appointment.startsAt)}`,
+          ),
+      })
+
+      return [form, Form.focusObjectOn(form, "startsAt")] as const
+    }),
+  )
+
+  const startsAt = yield* Form.useInput(startsAtField)
+  const [canCommit] = yield* View.useAll([form.canCommit])
+  const runPromise = yield* Component.useRunPromise()
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        void runPromise(form.submit)
+      }}
+    >
+      <input
+        type="datetime-local"
+        value={startsAt.value}
+        onChange={(event) =>
+          startsAt.setValue(event.currentTarget.value)
+        }
+      />
+      <button disabled={!canCommit}>Save appointment</button>
+    </form>
+  )
+})
+```
+
+The schema requires `DateTime.CurrentTimeZone`; provide
+`DateTime.layerCurrentZoneLocal` in the application runtime. If the current
+zone is `Europe/Paris`, for example, entering `2026-07-22T14:30` decodes to the
+UTC instant `2026-07-22T12:30:00.000Z`.
+
+Encoding works in the other direction. A `LensForm` whose target contains that
+UTC instant presents `2026-07-22T14:30` to the local input. The component never
+manually parses dates, applies offsets, or maintains a second representation;
+the schema defines both directions and the form keeps them synchronized.
@@ -219,6 +219,11 @@ interface UserProfile {
  readonly name: string
  readonly email: string
  readonly role: string
+  readonly contact: {
+    readonly address: {
+      readonly city: string
+    }
+  }
 }

 class ProfileState extends Context.Service<
@@ -237,6 +242,11 @@ class ProfileState extends Context.Service<
          name: "",
          email: "",
          role: "reader",
+          contact: {
+            address: {
+              city: "",
+            },
+          },
        }),
      )
      const name = Lens.focusObjectOn(profile, "name")
@@ -269,6 +279,19 @@ Updating the focused `name` Lens through `Lens.useState` updates the parent
 `profile` Lens. The focused `role` Lens is only read, so it stays on the simpler
 `View.useAll` path.

+Lens focus helpers have a dual API. They can be called in data-first form, such
+as `Lens.focusObjectOn(profile, "name")`, or in curried form with only the key
+or index. The curried form composes naturally with `pipe` for deeper paths:
+
+```tsx
+// profileLens is a Lens.Lens<UserProfile>
+const cityLens = profileLens.pipe(
+  Lens.focusObjectOn("contact"),
+  Lens.focusObjectOn("address"),
+  Lens.focusObjectOn("city"),
+)
+```
+
 For focusing into nested state, deriving lenses, custom write behavior, and the
 complete API, refer to the
 [`effect-lens` documentation](https://www.npmjs.com/package/effect-lens/v/beta).