foldkit 0.161.0 → 0.162.0-canary.01d0205a4e2b

package/README.md

@@ -45,7 +45,7 @@ import { Schema } from 'effect'
 import { Runtime, Update } from 'foldkit'
 import { Document, HtmlBuilder } from 'foldkit/html'
 import { defineMessageUnion } from 'foldkit/message'
-import { evo } from 'foldkit/struct'
+import { modifyFields } from 'foldkit/struct'
 
 // MODEL
 
@@ -66,12 +66,12 @@ export type Message = typeof Message.Type
 export const update = (model: Model, message: Message) =>
   Message.match<Update.Return<Model, Message>>(message, {
     ClickedDecrement: () => ({
-      model: evo(model, { count: count => count - 1 }),
+      model: modifyFields(model, { count: count => count - 1 }),
     }),
     ClickedIncrement: () => ({
-      model: evo(model, { count: count => count + 1 }),
+      model: modifyFields(model, { count: count => count + 1 }),
     }),
-    ClickedReset: () => ({ model: evo(model, { count: () => 0 }) }),
+    ClickedReset: () => ({ model: modifyFields(model, { count: () => 0 }) }),
   })
 
 // INIT

package/dist/asyncData/asyncData.d.ts

@@ -407,7 +407,7 @@ export declare const all: <const Inputs extends Iterable<AsyncData<any, any>> |
  *
  *  // One update arm folds it in, whatever the previous state was:
  *  SettledLoadNotes: ({ result }) => ({
- *    model: evo(model, { notes: AsyncData.settle(result) }),
+ *    model: modifyFields(model, { notes: AsyncData.settle(result) }),
  *  })
  *  ```
  */

package/dist/asyncData/asyncData.js

@@ -418,7 +418,7 @@ export const all = (inputs) => {
  *
  *  // One update arm folds it in, whatever the previous state was:
  *  SettledLoadNotes: ({ result }) => ({
- *    model: evo(model, { notes: AsyncData.settle(result) }),
+ *    model: modifyFields(model, { notes: AsyncData.settle(result) }),
  *  })
  *  ```
  */

package/dist/devTools/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/devTools/store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/devTools/store.ts"],"names":[],"mappings":"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"}

package/dist/devTools/store.js

@@ -1,5 +1,5 @@
 import { Array, Effect, HashMap, HashSet, Match, Option, Predicate, Record, String, SubscriptionRef, pipe, } from 'effect';
-import { evo } from '../struct/index.js';
+import { modifyFields } from '../struct/index.js';
 export const INIT_INDEX = -1;
 const DEFAULT_KEYFRAME_INTERVAL = 31;
 const DEFAULT_MAX_ENTRIES = 100;
@@ -126,14 +126,14 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
         const nextStartIndex = state.startIndex + keyframeInterval;
         const isPausedAtRetainedIndex = state.pausedAtIndex >= nextStartIndex ||
             state.pausedAtIndex === INIT_INDEX;
-        return evo(state, {
+        return modifyFields(state, {
             entries: Array.drop(keyframeInterval),
             keyframes: HashMap.remove(state.startIndex),
             startIndex: () => nextStartIndex,
             isPaused: isPaused => isPaused && isPausedAtRetainedIndex,
         });
     };
-    const recordInit = (model, commands, mountStarts = []) => SubscriptionRef.update(stateRef, state => evo(state, {
+    const recordInit = (model, commands, mountStarts = []) => SubscriptionRef.update(stateRef, state => modifyFields(state, {
         maybeInitModel: () => Option.some(model),
         initCommands: () => commands,
         initMountStarts: () => mountStarts,
@@ -147,7 +147,7 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
                 ? computeDiff(modelBeforeUpdate, modelAfterUpdate)
                 : emptyDiff;
             const hasChangedFields = HashSet.size(diff.changedPaths) > 0;
-            const nextState = evo(state, {
+            const nextState = modifyFields(state, {
                 entries: Array.append({
                     tag: message._tag,
                     message,
@@ -171,12 +171,12 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
         }
     });
     const recordResolvedCommand = (id, submodelPath) => SubscriptionRef.update(stateRef, state => {
-        const updateCommands = (commands) => pipe(commands, Array.findFirstIndex(command => command.id === id), Option.flatMap(index => Array.modify(commands, index, command => evo(command, {
+        const updateCommands = (commands) => pipe(commands, Array.findFirstIndex(command => command.id === id), Option.flatMap(index => Array.modify(commands, index, command => modifyFields(command, {
             maybeSubmodelPath: () => Option.some(submodelPath),
         }))));
         const maybeInitCommands = updateCommands(state.initCommands);
         if (Option.isSome(maybeInitCommands)) {
-            return evo(state, {
+            return modifyFields(state, {
                 initCommands: () => maybeInitCommands.value,
             });
         }
@@ -186,11 +186,11 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
         }
         const maybeEntries = Array.modify(state.entries, maybeEntryIndex.value, entry => Option.match(updateCommands(entry.commands), {
             onNone: () => entry,
-            onSome: nextCommands => evo(entry, { commands: () => nextCommands }),
+            onSome: nextCommands => modifyFields(entry, { commands: () => nextCommands }),
         }));
         return Option.match(maybeEntries, {
             onNone: () => state,
-            onSome: nextEntries => evo(state, { entries: () => nextEntries }),
+            onSome: nextEntries => modifyFields(state, { entries: () => nextEntries }),
         });
     });
     /** Attaches Mount lifecycle events from the most recent render to the
@@ -209,11 +209,11 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
             return state;
         }
         return Array.match(state.entries, {
-            onEmpty: () => evo(state, {
+            onEmpty: () => modifyFields(state, {
                 initMountStarts: Array.appendAll(mountStarts),
             }),
-            onNonEmpty: entries => evo(state, {
-                entries: () => Array.modifyLastNonEmpty(entries, last => evo(last, {
+            onNonEmpty: entries => modifyFields(state, {
+                entries: () => Array.modifyLastNonEmpty(entries, last => modifyFields(last, {
                     mountStarts: Array.appendAll(mountStarts),
                     mountEnds: Array.appendAll(mountEnds),
                 })),
@@ -243,14 +243,14 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
             return isTargetRetained
                 ? [
                     false,
-                    evo(currentState, {
+                    modifyFields(currentState, {
                         isPaused: () => true,
                         pausedAtIndex: () => index,
                     }),
                 ]
                 : [
                     true,
-                    evo(currentState, {
+                    modifyFields(currentState, {
                         isPaused: () => false,
                     }),
                 ];
@@ -261,7 +261,7 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
         return model;
     });
     const resume = Effect.gen(function* () {
-        yield* SubscriptionRef.update(stateRef, state => evo(state, {
+        yield* SubscriptionRef.update(stateRef, state => modifyFields(state, {
             isPaused: () => false,
         }));
         yield* bridge.markRenderPending;
@@ -274,7 +274,7 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
             return state;
         }
         else {
-            return evo(state, {
+            return modifyFields(state, {
                 entries: () => [],
                 startIndex: () => 0,
                 pausedAtIndex: () => 0,
@@ -296,7 +296,7 @@ export const createDevToolsStore = (bridge, options = {}) => Effect.gen(function
             onSome: ({ diff }) => diff,
         }));
     });
-    const updateLatestModel = (model) => SubscriptionRef.update(stateRef, evo({ maybeLatestModel: () => Option.some(model) }));
+    const updateLatestModel = (model) => SubscriptionRef.update(stateRef, modifyFields({ maybeLatestModel: () => Option.some(model) }));
     return {
         recordInit,
         recordMessage,

package/dist/experimental/machine/machine.d.ts

@@ -340,7 +340,7 @@ export type FoldConfig<ParentModel, State extends Tagged, Message extends Tagged
  *   machine: uploadMachine,
  *   read: (model: Model) => Option.some(model.upload),
  *   write: (model, nextUpload) =>
- *     evo(model, { upload: () => nextUpload }),
+ *     modifyFields(model, { upload: () => nextUpload }),
  *   context: model => model.uploadQueues,
  * })
  *

package/dist/experimental/machine/machine.js

@@ -133,7 +133,7 @@ const transitionFoldedMachine = (config, model, state, message) => {
  *   machine: uploadMachine,
  *   read: (model: Model) => Option.some(model.upload),
  *   write: (model, nextUpload) =>
- *     evo(model, { upload: () => nextUpload }),
+ *     modifyFields(model, { upload: () => nextUpload }),
  *   context: model => model.uploadQueues,
  * })
  *

package/dist/experimental/server/server.d.ts

@@ -222,12 +222,15 @@ export type RenderUrlFlagsOptions<Flags> = RenderUrlOptions & RenderFlagsOptions
  * reconstruct, so the served DOM and the client's first render agree by
  * construction even for codecs whose round trip is not the identity.
  *
- * When a routing view omits `Document.canonical`, the render defaults it (and
- * `ogUrl`) to the request URL, normalized the way the client computes the
- * current location but with the query string kept. Set `Document.canonical`
- * explicitly when the query string is not part of the page's identity, such as
- * tracking parameters or a session token, so a crawler does not index every
- * variant as its own canonical page.
+ * Canonical metadata has no request URL default. The result includes
+ * `canonical` only when the view supplies it. It includes `ogUrl` when the view
+ * supplies it, or uses an explicit canonical when `ogUrl` is omitted. When a
+ * field is absent from the result, `injectIntoTemplate` leaves the
+ * corresponding tag in the template unchanged.
+ *
+ * Derive the canonical URL from the typed route in the Model. `Request.url`
+ * gives routing applications the request to parse, but only the application
+ * knows which route and query values identify the page.
  *
  * @example
  * ```typescript

package/dist/experimental/server/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/experimental/server/server.ts"],"names":[],"mappings":"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"}

package/dist/experimental/server/server.js

@@ -810,23 +810,6 @@ const parseUrl = (url) => Option.match(fromString(url), {
     onNone: () => Effect.fail(new InvalidUrl({ url })),
     onSome: Effect.succeed,
 });
-// The client defaults canonical to `origin + pathname + search` of the current
-// location, which drops the fragment and normalizes host case and default
-// ports. Building the server default with the WHATWG URL parser reproduces that
-// exact string, so the metadata a crawler reads before hydration matches what
-// the hydrated page computes.
-const normalizedRequestUrl = (rawUrl) => {
-    if (rawUrl === undefined) {
-        return undefined;
-    }
-    try {
-        const parsed = new URL(rawUrl);
-        return `${parsed.origin}${parsed.pathname}${parsed.search}`;
-    }
-    catch {
-        return undefined;
-    }
-};
 const validateHydrationRoot = (body) => {
     if (body === null) {
         return Effect.fail(new InvalidHydrationRoot({ rootKind: 'Empty' }));
@@ -921,15 +904,7 @@ export function renderToString(config, options) {
             catch: cause => new SerializationError({ cause }),
         });
         const flagsPayload = flagsHandoff !== undefined ? flagsHandoff.payloadScript : '';
-        // Mirror the client's document-metadata defaults so the served HTML a
-        // crawler reads carries the same canonical and Open Graph URL the hydrated
-        // page computes: canonical falls back to the request URL, and ogUrl to the
-        // resolved canonical, the chain the runtime applies on the client. A
-        // non-routing render has no request URL, so it inherits only an explicitly
-        // set canonical.
-        const resolvedCanonical = nextDocument.canonical ??
-            (hasRouting ? normalizedRequestUrl(options?.url) : undefined);
-        const resolvedOgUrl = nextDocument.ogUrl ?? resolvedCanonical;
+        const resolvedOgUrl = nextDocument.ogUrl ?? nextDocument.canonical;
         return {
             html: `${rootHtml}${flagsPayload}`,
             title: nextDocument.title,
@@ -937,8 +912,8 @@ export function renderToString(config, options) {
             ...(nextDocument.dir !== undefined
                 ? { dir: textDirectionToAttribute(nextDocument.dir) }
                 : {}),
-            ...(resolvedCanonical !== undefined
-                ? { canonical: resolvedCanonical }
+            ...(nextDocument.canonical !== undefined
+                ? { canonical: nextDocument.canonical }
                 : {}),
             ...(resolvedOgUrl !== undefined ? { ogUrl: resolvedOgUrl } : {}),
         };

package/dist/html/index.d.ts

@@ -95,25 +95,33 @@ export type TextDirection = typeof TextDirection.Type;
  *  it after each render, and server rendering, which stamps it into the served
  *  shell so the direction is correct on first paint. */
 export declare const textDirectionToAttribute: (direction: TextDirection) => 'ltr' | 'rtl' | 'auto';
-/** A view's complete output for the runtime: title, body, and optional document
- *  metadata. The runtime applies `title` to `document.title`, syncs `lang` and
- *  `dir` to the `<html>` element, syncs `canonical` to `<link rel="canonical">`
- *  (creating it if absent), syncs `ogUrl` to `<meta property="og:url">`
- *  (creating it if absent), and patches `body` into the application container.
+/** The complete output of a page-owning view. The runtime patches `body` into
+ *  the application container, writes `title` to `document.title`, and manages
+ *  the optional document metadata.
  *
- *  When `canonical` is omitted, it defaults to the current URL (origin +
- *  pathname + search). When `ogUrl` is omitted, it falls back to `canonical`.
+ *  Supplied `lang` and `dir` values are written to the `<html>` element. An
+ *  omitted value leaves the current attribute unchanged, including a value
+ *  from the served HTML or an earlier render. Drive both fields from the Model
+ *  when the application can switch languages at runtime.
  *
- *  `lang` and `dir` have no default. When either is omitted the runtime does not
- *  touch that attribute, leaving whatever value it currently holds, so a view
- *  that never sets it leaves the served HTML in place. Drive them from the Model
- *  when the app switches language at runtime. The served HTML still decides what
- *  a crawler sees on first paint, because the runtime can only sync after the
- *  first render.
+ *  `canonical` has no address-bar default. Derive it from the typed route in
+ *  the Model, where the application can decide which route and query values
+ *  identify the page. If the view never supplies it, the runtime leaves a
+ *  served `<link rel="canonical">` unchanged or keeps the document without one.
  *
- *  This is the return type of a `makeApplication` view, which owns the document. An
- *  app embedded at a node should use `makeElement` instead, whose view returns
- *  `Html` and never touches the `<head>` or the `<html>` element. */
+ *  Before the client first writes `canonical` or `ogUrl`, it records the value
+ *  already present on the corresponding element. A later omission restores
+ *  that value, or removes the element if the runtime created it. During
+ *  hydration, the recorded value may be metadata rendered for the initial
+ *  route. `ogUrl` can be supplied independently; when omitted alongside an
+ *  explicit `canonical`, it uses that canonical.
+ *
+ *  Server rendering returns only the canonical supplied by the view. It
+ *  returns `ogUrl` when supplied or falls back to an explicit canonical.
+ *
+ *  This is the return type of a `makeApplication` view. An application embedded
+ *  at a node should use `makeElement`; its view returns `Html` and never changes
+ *  the `<head>` or `<html>` element. */
 export type Document = Readonly<{
     title: string;
     lang?: string;