@jsenv/navi 0.29.224 → 0.29.226

package/README.md

@@ -14,6 +14,8 @@ How to declare routes, render them, and turn them into tabs — including `Route
 
 Actions are async operations with lifecycle management — pending, success, error. You can declare actions that run when navigating to a route, and any component can subscribe to them via `useAsyncData` to reflect what is happening: loading states, results, errors. No manual wiring.
 
+Code loaded on demand is the same thing: a page's `import()` is a route action, started with the page's data on the url change and prefetched when a link to it is hovered or focused; a component inside a page that stays reads its own with `useAsyncData(() => import(…))`. One wait, one failure, no lazy-shaped API. See [docs/dynamic_import.md](./docs/dynamic_import.md).
+
 ## REST state
 
 `resource()` turns a REST endpoint into a reactive store: one action per verb, a

package/dist/dev/jsenv_navi.js

@@ -17336,6 +17336,17 @@ const useAsyncData = (promiseOrAction, {
   run,
   onLoad
 } = {}) => {
+  // The request this component owns, as a function: one action per instance,
+  // made on the first render and kept — the function's identity changes on
+  // every render when it is written inline, the action's does not.
+  const ownActionRef = useRef(null);
+  if (typeof promiseOrAction === "function" && !promiseOrAction.isAction) {
+    if (!ownActionRef.current) {
+      ownActionRef.current = createAction(promiseOrAction);
+    }
+    promiseOrAction = ownActionRef.current;
+    run = true;
+  }
   const isAction = Boolean(promiseOrAction && promiseOrAction.isAction);
   if (loading === true) {
     loading = "use";
@@ -17659,9 +17670,9 @@ const LoadingFallback = ({
   // A suspension nobody here wrote — preact/compat's lazy(), a promise thrown
   // by hand: the boundary holds the subtree and has nothing to say about it,
   // so the fallback is not drawn. Said out loud in dev rather than found by
-  // reading this file; navi's own lazy() is an action and never lands here.
+  // reading this file; an import read through an action never lands here.
   if (!action) {
-    console.warn(`<Loading> caught a suspension it cannot attribute to an action, so its fallback is not drawn. For code loaded on demand use lazy() from @jsenv/navi (see docs/dynamic_import.md).`);
+    console.warn(`<Loading> caught a suspension it cannot attribute to an action, so its fallback is not drawn. Read code loaded on demand through an action — a routeAction or useAsyncData(() => import(...)) — see docs/dynamic_import.md.`);
   }
   if (loadingRef.current.reason !== "loading") {
     return null;
@@ -17779,86 +17790,6 @@ const ErrorBoundary = ({
   return children;
 };
 
-/**
- * A component whose code is fetched on demand, the way its data is.
- *
- * The import is an action: it starts from the first render that needs it (or
- * from `preload()`), waits in the nearest `<Loading>`, fails in the nearest
- * `<ErrorBoundary>` with a `rerun` as the way back, and is counted by the
- * document busy signal like any other run. A page under `<Route>` therefore
- * fetches its code and its route action's data side by side, and shows one
- * wait for the two. See docs/dynamic_import.md.
- */
-
-
-/**
- * @param {() => Promise<Function | object>} load - what fetches the code,
- *   typically `() => import("./page.jsx")`. May resolve to the component
- *   itself or to the module: its `default` export, or its only exported
- *   function.
- * @returns {Function & { preload: () => void, action: object }} the component,
- *   rendering the loaded one with its props. `preload()` starts the fetch ahead
- *   of the render — on a link hovered, on an idle moment; a prefetch that fails
- *   is forgotten, the visit asks again.
- */
-const lazy = load => {
-  const loadAction = createAction(async () => {
-    const loaded = await load();
-    return resolveComponent(loaded);
-  }, {
-    name: nameFromLoader(load)
-  });
-  const Lazy = props => {
-    const [Component] = useAsyncData(loadAction, {
-      run: true
-    });
-    return h(Component, props);
-  };
-  Lazy.displayName = `Lazy(${loadAction.name})`;
-  Lazy.action = loadAction;
-  // A prefetch is a prerun: nothing on screen asked for it. One that fails is
-  // forgotten rather than reported — the visit that needs the code asks again
-  // and shows its own failure; a boundary already showing this one keeps it
-  // until the retry runs.
-  Lazy.preload = () => {
-    const prerunResult = loadAction.prerun({
-      reason: "preload"
-    });
-    // A run already in flight or done answers with nothing to wait for.
-    if (prerunResult && typeof prerunResult.catch === "function") {
-      prerunResult.catch(() => {
-        loadAction.reset({
-          reason: "preload failed"
-        });
-      });
-    }
-  };
-  return Lazy;
-};
-const resolveComponent = loaded => {
-  if (typeof loaded === "function") {
-    return loaded;
-  }
-  if (loaded && typeof loaded === "object") {
-    if (typeof loaded.default === "function") {
-      return loaded.default;
-    }
-    const functionExportNames = Object.keys(loaded).filter(key => typeof loaded[key] === "function");
-    if (functionExportNames.length === 1) {
-      return loaded[functionExportNames[0]];
-    }
-    throw new Error(`lazy(): the module must export one component, found ${functionExportNames.length} (${functionExportNames.join(", ") || "none"}). Return the component from the loader to say which.`);
-  }
-  throw new Error(`lazy(): expected a component or a module, got ${loaded}`);
-};
-
-// The specifier read off the loader's source, so the action (and the busy
-// signal, and the debug output) says which page is being fetched.
-const nameFromLoader = load => {
-  const match = /import\(\s*["']([^"']+)["']/.exec(String(load));
-  return match ? `import ${match[1]}` : "lazy";
-};
-
 /**
  * Creates a function that generates abort signals, automatically cancelling previous requests.
  *
@@ -25073,11 +25004,9 @@ const route = (
       return `route "${cleanPattern}"`;
     },
   };
-  // What fetches the code of this route ahead of the render — the lazy
-  // elements the routers on screen have registered for it (see
-  // registerRoutePreload). Code only: the data is the route action's, asked
-  // for on arrival with the params the address holds, and a prefetch has no
-  // address yet.
+  // Asks ahead of the arrival for what this route's actions ask without the
+  // address — a page's code, a read without params (see routeAction). An
+  // action keyed by a param waits for the arrival: a prefetch has no address.
   route.preload = () => {
     const preloadSet = routePreloadMap.get(route);
     if (!preloadSet) {
@@ -25570,10 +25499,10 @@ const registerRoutePreload = (route, preload) => {
   preloadSet.add(preload);
 };
 /**
- * Fetches the code of every route the url leads to, a section and the page
- * inside it alike. What a link does when the pointer or the focus reaches it
- * (see use_preload_on_intent.js), available to anything else that knows where
- * it is about to go.
+ * Preloads every route the url leads to, a section and the page inside it
+ * alike. What a link does when the pointer or the focus reaches it (see
+ * use_preload_on_intent.js), available to anything else that knows where it
+ * is about to go.
  */
 const preloadUrl = (url) => {
   if (!activeRouteSet) {
@@ -27612,12 +27541,8 @@ const collectBranches = children => {
       children: nodeChildren,
       fallback,
       route,
-      routeParams,
-      element
+      routeParams
     } = child.props;
-    if (route) {
-      registerElementPreload(route, element);
-    }
     if (nodeChildren) {
       const {
         matchingBranch: matchingChild
@@ -27667,17 +27592,6 @@ const collectBranches = children => {
     activeBranch
   };
 };
-// A branch whose element fetches its code on demand (see lazy.jsx) tells its
-// route, so that intent on a link to that route — or `route.preload()` — can
-// fetch it ahead of the render. Read off the vnode the container walks, which
-// is why a router on screen is what knows: a section's sub-pages register when
-// the section renders its own router.
-const registerElementPreload = (route, element) => {
-  const type = element && element.type ? element.type : element;
-  if (type && typeof type.preload === "function") {
-    registerRoutePreload(route, type.preload);
-  }
-};
 const wrapBranch = (branch, wrapper) => {
   return {
     ...branch,
@@ -31302,20 +31216,55 @@ const writeCover = (edge, element, size) => {
   style.setProperty(property, value);
 };
 
+/**
+ * Binds an action to a route: it runs when the route matches, with the params
+ * the effect reads off the address, and is aborted when the route is left.
+ * Its data, its wait and its failure are read by the page through
+ * `useAsyncData`.
+ *
+ * A page's CODE is declared the same way — the import is one more thing the
+ * address asks for, started with the data rather than after it:
+ *
+ * ```js
+ * const GAME_PAGE_CODE = routeAction(GAME_ROUTE, () =>
+ *   import("./game_page.jsx").then((m) => m.GamePage),
+ * );
+ * ```
+ *
+ * @param {object | object[]} routeOrRoutes - the route, or the routes, this
+ *   action belongs to.
+ * @param {object | Function} action - an action, or a function made into one.
+ * @param {() => any} [paramsEffect] - what the action runs with, read off
+ *   signals (the route's params, a search param): re-read when they change.
+ *   Return a falsy value to run nothing. Without it the action asks nothing of
+ *   the address, which is also what makes it worth fetching AHEAD of the
+ *   arrival: a link to the route preruns it when the pointer or the focus
+ *   reaches the link (see docs/dynamic_import.md). An action whose params
+ *   come from the address is never prefetched — a prefetch has no address.
+ * @param {object} [options]
+ * @param {boolean} [options.prefetch=true] - `false` keeps a param-less action
+ *   from being prerun on intent, when the read is not worth a hover.
+ */
 const routeAction = (
   routeOrRoutes,
   action,
-  paramsEffect = () => true,
-  options = {},
+  paramsEffect,
+  { prefetch = true, ...options } = {},
 ) => {
-  const routeMatchingSignal = Array.isArray(routeOrRoutes)
-    ? anyMatchingRouteSignal(routeOrRoutes)
-    : routeOrRoutes.matchingSignal;
+  if (typeof action === "function") {
+    action = createAction(action);
+  }
+  const routes = Array.isArray(routeOrRoutes) ? routeOrRoutes : [routeOrRoutes];
+  const routeMatchingSignal =
+    routes.length === 1
+      ? routes[0].matchingSignal
+      : anyMatchingRouteSignal(routes);
+  const readParams = paramsEffect || (() => true);
   const actionBoundToRoute = actionRunEffect(
     action,
     () => {
       const matching = routeMatchingSignal.value;
-      const params = paramsEffect();
+      const params = readParams();
       if (!matching) {
         return null;
       }
@@ -31323,10 +31272,38 @@ const routeAction = (
     },
     options,
   );
-
+  if (!paramsEffect && prefetch) {
+    for (const route of routes) {
+      registerRoutePreload(route, () => {
+        prefetchParamless(action);
+      });
+    }
+  }
   return actionBoundToRoute;
 };
 
+// The instance the effect above runs on the match is the one bound to `true`
+// (the default params), so a prerun here is what the arrival promotes to a
+// run. A prefetch that fails is not reported: nothing on screen asked for it,
+// and the failure stays on the instance, where a run asks again — a FAILED
+// action is run, only RUNNING and COMPLETED are left alone — and the arrival
+// shows its own. It is left FAILED on purpose, not reset: the press that
+// brings the arrival also focuses the link, so a prerun can be in flight when
+// the arrival promotes it, and a reset landing after that would pull the
+// answer from under the page that is reading it.
+const prefetchParamless = (action) => {
+  const instance = action.bindParams(true);
+  let result;
+  try {
+    result = instance.prerun({ reason: "intent" });
+  } catch {
+    return;
+  }
+  if (result && typeof result.catch === "function") {
+    result.catch(() => {});
+  }
+};
+
 // I delibrately prefer the term "any" and avoid "some" so dev are not tempted to think
 // "well I could just use array.some" and bypass this helper entirely, which would be incorrect:
 // This helper does return if some/any route is matching but ensure all route matching signals are read (subscribed to)
@@ -41313,10 +41290,11 @@ const Icon = ({
 };
 
 /**
- * The code of where a link leads, fetched when the pointer or the focus
- * arrives on it: the moment the user signals a destination, before the press.
- * Only code is fetched (see route.preload), so a link whose address is not the
- * final one — an id still to be chosen — loses nothing by asking.
+ * Where a link leads, asked for when the pointer or the focus arrives on it:
+ * the moment the user signals a destination, before the press. Only what the
+ * route's actions ask without the address is fetched (see route.preload), so
+ * a link whose address is not the final one — an id still to be chosen —
+ * loses nothing by asking.
  */
 const usePreloadOnIntent = (ref, href, prefetch = true) => {
   useEffect(() => {
@@ -41850,8 +41828,10 @@ Object.assign(PSEUDO_CLASSES, {
  *   button leaves by where the reader came in.
  * @param {boolean} [props.prefetch=true] Fetch the code of where this leads when the
  *   pointer or the focus arrives, ahead of the press (see
- *   docs/dynamic_import.md). Code only: the data stays the route action's.
- *   `false` for a destination not worth fetching on a hover.
+ *   docs/dynamic_import.md): the route actions that ask nothing of the
+ *   address — a page's code, a read without params — are prerun; one keyed by
+ *   a param waits for the arrival. `false` for a destination not worth
+ *   fetching on a hover.
  * @param {string} [props.command] - What the press asks of a control around
  *   the link — `"--navi-close"` on a link that leaves the sheet it is in.
  *   Triggered on the press, before the navigation.
@@ -48380,8 +48360,10 @@ const COMMAND_DEFAULT_PROPS_FACTORIES = {
  *   as a button.
  * @param {boolean} [prefetch=true] Fetch the code of where this leads when the
  *   pointer or the focus arrives, ahead of the press (see
- *   docs/dynamic_import.md). Code only: the data stays the route action's.
- *   `false` for a destination not worth fetching on a hover.
+ *   docs/dynamic_import.md): the route actions that ask nothing of the
+ *   address — a page's code, a read without params — are prerun; one keyed by
+ *   a param waits for the arrival. `false` for a destination not worth
+ *   fetching on a hover.
  * @param {boolean} [pressableDuringRouteTransition] Keep answering presses
  *   while a route transition plays: what a movement photographs goes deaf to
  *   the pointer for its whole length, and the door that opened the page — a
@@ -83898,5 +83880,5 @@ const UserSvg = () => jsx("svg", {
   })
 });
 
-export { ActionRenderer, ActiveKeyboardShortcuts, Address, Badge, BadgeCount, BadgeList, Binder, Box, Button, ButtonCopyToClipboard, CalloutStatusIcon, Caption, CardLayout, CheckSvg, CheckboxGroup, CloseSvg, Code, Col, Colgroup, Color, ConstructionSvg, ControlGroup, ControlSwap, DaySpin, Details, Dialog, Editable, ErrorBoundary, ErrorBoundaryContext, ExclamationSvg, Expandable, EyeClosedSvg, EyeSvg, Field, FixedBar, Form, Group, Head, HeartSvg, HomeSvg, Icon, Image, InfoSvg, Input, InputDuration, Interpolate, Label, Link, LinkAnchorSvg, LinkBlankTargetSvg, LinkCurrentSvg, List, ListItem, ListItemGroup, ListItems, Loading, LoadingDotsSvg, LoadingIndicator, LoadingIndicatorFluid, LoadingOutline, MessageBox, Meter, Nav, NaviDebug, NumberSpin, OfflineError, Paragraph, Picker, Popover, Popup, Quantity, RadioGroup, Route, RouteTransitionArea, RouteTravel, RowNumberCol, RowNumberTableCell, SVGMaskOverlay, SearchSvg, Select, SelectableInput, SelectionContext, Separator, SettingsSvg, SidePanel, Slide, SlideContainer, Spin, SpinGroup, SplitButton, StarSvg, Step, StepList, SummaryMarker, Svg, Table, TableCell, Tbody, Text, TextBox, Textarea, TextareaCharCount, Thead, Time, TimeRange, TimeRangeSpin, TimeRangeWheel, TimeSpin, TimeWheel, Title, Tr, UITransition, Unit, UserSvg, ViewportLayout, Wheel, WheelGroup, WheelItem, actionRunEffect, anyMatchingRouteSignal, applySearch, arraySignalMembership, canNavBackSignal, canNavForwardSignal, coarsePointerSignal, compareTwoJsValues, constraintFromValidityRule, createAction, createAvailableConstraint, createRequestCanceller, createSearch, createSelectionKeyboardShortcuts, createSlot, defineInteractionDetector, defineRouteDefaultTransition, defineRouteTransition, detectHorizontalOverflow, dispatchRequestSetUIState, enableDebugActions, enableDebugOnDocumentLoading, ensureDocumentStartViewTransition, errorIsDisplayed, filterTableSelection, getNowHours, getNowHoursRoundedToStep, isCellSelected, isColumnSelected, isOfflineError, isRowSelected, isScrolling, isToday, languagesSignal, lazy, localStorageSignal, markAsOutsideTextFlow, markErrorAsDisplayedBy, moveArrayItemByIndex, moveFocusTo, navBack, navForward, navIntegratedVia, navTo, naviI18n, openCallout, preloadUrl, rawUrlPart, registerGlobalConstraint, reload, rerunActions, resource, route, routeAction, scrollActivitySignal, setBaseUrl, setNetworkPolicy, setPreferredLanguage, setSupportedLanguages, setUrlTargetOptions, setupRoutes, smallTouchScreenSignal, stateSignal, stopLoad, stringifyTableSelectionValue, swapArrayItemByIndex, syncOwnedResourceToSignals, syncResourceToSignals, triggerNaviCommand, updateActions, useActionStatus, useArraySignalMembership, useAsyncData, useCalloutElement, useCalloutRequestClose, useCanNavBack, useCanNavForward, useCancelPrevious, useCellGridFromRows, useConstraintValidityState, useDependenciesDiff, useDisplayedLayoutEffect, useDocumentResource, useDocumentState, useDocumentUrl, useEditionController, useFocusGroup, useInputGroup, useKeyboardShortcuts, useNavState, useNetworkPolicyReason, useOrderedColumns, usePopupMode, useRouteStatus, useSearchText, useSelectableElement, useSelectionController, useSignalSync, useSlideContainer, useSlideValue, useStateArray, useTitleLevel, useTransitionCover, useUrlSearchParam, useUrlTargetId, valueInLocalStorage, windowWidthSignal };
+export { ActionRenderer, ActiveKeyboardShortcuts, Address, Badge, BadgeCount, BadgeList, Binder, Box, Button, ButtonCopyToClipboard, CalloutStatusIcon, Caption, CardLayout, CheckSvg, CheckboxGroup, CloseSvg, Code, Col, Colgroup, Color, ConstructionSvg, ControlGroup, ControlSwap, DaySpin, Details, Dialog, Editable, ErrorBoundary, ErrorBoundaryContext, ExclamationSvg, Expandable, EyeClosedSvg, EyeSvg, Field, FixedBar, Form, Group, Head, HeartSvg, HomeSvg, Icon, Image, InfoSvg, Input, InputDuration, Interpolate, Label, Link, LinkAnchorSvg, LinkBlankTargetSvg, LinkCurrentSvg, List, ListItem, ListItemGroup, ListItems, Loading, LoadingDotsSvg, LoadingIndicator, LoadingIndicatorFluid, LoadingOutline, MessageBox, Meter, Nav, NaviDebug, NumberSpin, OfflineError, Paragraph, Picker, Popover, Popup, Quantity, RadioGroup, Route, RouteTransitionArea, RouteTravel, RowNumberCol, RowNumberTableCell, SVGMaskOverlay, SearchSvg, Select, SelectableInput, SelectionContext, Separator, SettingsSvg, SidePanel, Slide, SlideContainer, Spin, SpinGroup, SplitButton, StarSvg, Step, StepList, SummaryMarker, Svg, Table, TableCell, Tbody, Text, TextBox, Textarea, TextareaCharCount, Thead, Time, TimeRange, TimeRangeSpin, TimeRangeWheel, TimeSpin, TimeWheel, Title, Tr, UITransition, Unit, UserSvg, ViewportLayout, Wheel, WheelGroup, WheelItem, actionRunEffect, anyMatchingRouteSignal, applySearch, arraySignalMembership, canNavBackSignal, canNavForwardSignal, coarsePointerSignal, compareTwoJsValues, constraintFromValidityRule, createAction, createAvailableConstraint, createRequestCanceller, createSearch, createSelectionKeyboardShortcuts, createSlot, defineInteractionDetector, defineRouteDefaultTransition, defineRouteTransition, detectHorizontalOverflow, dispatchRequestSetUIState, enableDebugActions, enableDebugOnDocumentLoading, ensureDocumentStartViewTransition, errorIsDisplayed, filterTableSelection, getNowHours, getNowHoursRoundedToStep, isCellSelected, isColumnSelected, isOfflineError, isRowSelected, isScrolling, isToday, languagesSignal, localStorageSignal, markAsOutsideTextFlow, markErrorAsDisplayedBy, moveArrayItemByIndex, moveFocusTo, navBack, navForward, navIntegratedVia, navTo, naviI18n, openCallout, preloadUrl, rawUrlPart, registerGlobalConstraint, reload, rerunActions, resource, route, routeAction, scrollActivitySignal, setBaseUrl, setNetworkPolicy, setPreferredLanguage, setSupportedLanguages, setUrlTargetOptions, setupRoutes, smallTouchScreenSignal, stateSignal, stopLoad, stringifyTableSelectionValue, swapArrayItemByIndex, syncOwnedResourceToSignals, syncResourceToSignals, triggerNaviCommand, updateActions, useActionStatus, useArraySignalMembership, useAsyncData, useCalloutElement, useCalloutRequestClose, useCanNavBack, useCanNavForward, useCancelPrevious, useCellGridFromRows, useConstraintValidityState, useDependenciesDiff, useDisplayedLayoutEffect, useDocumentResource, useDocumentState, useDocumentUrl, useEditionController, useFocusGroup, useInputGroup, useKeyboardShortcuts, useNavState, useNetworkPolicyReason, useOrderedColumns, usePopupMode, useRouteStatus, useSearchText, useSelectableElement, useSelectionController, useSignalSync, useSlideContainer, useSlideValue, useStateArray, useTitleLevel, useTransitionCover, useUrlSearchParam, useUrlTargetId, valueInLocalStorage, windowWidthSignal };
 //# sourceMappingURL=jsenv_navi.js.map