@levo-so/site-runtime 0.3.22 → 0.3.23

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @levo-so/site-runtime
 
+## 0.3.23
+
+### Patch Changes
+
+- Two records in one URL segment. `levoParams(key, pattern, [siblings])` declares how a route's single param splits into several record variables, e.g. `/health-packages/<package>-in-<city>`:
+
+  - `const split = levoParams("packages_in_cities", "{$packages}-in-{$cities}")` goes on the route as `params: split`; the page reads `packages` and `cities` from `Route.useParams()`.
+  - The segment splits on its rightmost separator. A segment that does not fit is declined, so a plain sibling page (`$packages.tsx`) keeps serving `/health-packages/<package>`.
+  - `split.link(values)` is the `params` of a `<Link>` to the page (TanStack types it from every parsed param, so the segment alone does not compile); `split.segment(values)` is the string form.
+  - A plain variable beside the split in the same route is named in the third argument: `levoParams("c_in_d", "{$c}-in-{$d}", ["a"])`.
+  - Both arguments must be string literals, or top-level consts holding them: the platform reads the declaration out of the route file to enumerate the page's sitemap URLs and pairs each variable with the record binding whose `param` names it.
+
+  Loud failures for URL and binding mismatches:
+
+  - A record binding whose `param` names no param of the route throws on staging previews with the route's params listed, and logs on production sites while the record resolves to null as before.
+  - A `levoParams` key the route does not have is declined and reported once in the server log; the type check and the platform's publish check refuse it.
+  - Pattern errors (no variable, duplicate name, two variables with nothing between them, stray braces) throw when the route module initialises.
+
+  Requires the matching platform release for sitemap enumeration and publish validation; sites must pin this version for the builder AI to use the feature.
+
+  - @levo-so/core@0.3.23
+  - @levo-so/insights@0.3.23
+
 ## 0.3.22
 
 ### Internal

package/index.d.ts

@@ -883,6 +883,51 @@ export declare interface ILevoOtpSlot {
     };
 }
 
+/**
+ * One split segment, declared once: the route's `params` option IS this object, and every
+ * link to the route reuses the same const, so the pattern is never spelled twice.
+ * `TSiblings` names the route's other required params, `never` when the segment is the only
+ * one (see `levoParams`).
+ */
+export declare interface ILevoParams<TSegment extends string, TPattern extends string, TSiblings extends string = never> {
+    /**
+     * TanStack's `params.parse`: the variables split out of the segment beside the raw key and
+     * the siblings, or `false` for a segment the pattern does not fit, which declines the route
+     * so the sibling route with no pattern serves the URL. Throws when the key is not a param of
+     * the route at all (the first argument misspells the file's `$param`): see `parse` below.
+     */
+    parse: (raw: Record<TSegment | NoInfer<TSiblings>, string>) => ILevoParsedParams<TSegment, TPattern, TSiblings> | false;
+    /**
+     * The segment the values compose (`"full-body-in-mumbai"`), for a string href: a JSON-LD
+     * url, a sitemap-style index. A missing or empty value throws: a link with a hole is a bug,
+     * not a URL.
+     */
+    segment: (values: Record<ILevoPatternVars<TPattern>, string>) => string;
+    /**
+     * The `params` of a `<Link>` to the route: the values plus the composed segment under the
+     * raw key, with the sibling values passed through so a `<Link to="/$a/$c_in_d">` gets `a`
+     * beside the segment. Exists because TanStack types `Link params` from the route's PARSED
+     * params, so the variables are required beside the segment and the segment alone does not
+     * compile. Throws for a missing or empty value, as `segment` does.
+     */
+    link: (values: Record<ILevoPatternVars<TPattern> | TSiblings, string>) => ILevoParsedParams<TSegment, TPattern, TSiblings>;
+}
+
+/**
+ * What `parse` returns and `link` composes: the route's raw segment param (TanStack's
+ * parsed-params type must keep it), the route's other required params named as siblings
+ * (TanStack types the route's params from this alone, so a sibling not named here drops out
+ * of the route's types), plus one string per pattern variable.
+ */
+export declare type ILevoParsedParams<TSegment extends string, TPattern extends string, TSiblings extends string = never> = Record<TSegment | TSiblings, string> & Record<ILevoPatternVars<TPattern>, string>;
+
+/**
+ * The variable names of a pattern as a union of literals:
+ * `ILevoPatternVars<"{$packages}-in-{$cities}">` is `"packages" | "cities"`.
+ * A pattern that is not a literal has no inferable names (`never`).
+ */
+export declare type ILevoPatternVars<TPattern extends string> = TPattern extends `${string}{$${infer TName}}${infer TRest}` ? TName | ILevoPatternVars<TRest> : never;
+
 export declare interface ILevoPopupsProps {
     /**
      * The site's id (`site.json` `id`) — scopes the active-popups fetch. Absent → the
@@ -921,7 +966,9 @@ export declare interface ILevoRecordConfig {
      * Route param this binding's slug comes from — `"slug"` on `/blog/$slug`, `"events"` on
      * `/legal-events/$events`. Every generated record binding carries it: it is the mapping a
      * multi-param route needs, since with two variable segments nothing else in the file says
-     * which binding fills which slot. Round-tripped through the editor binding like the rest.
+     * which binding fills which slot. On a `levoParams` page it names one pattern variable
+     * (`"packages"` for `{$packages}-in-{$cities}`), which is how the platform pairs each variable
+     * with a collection. Round-tripped through the editor binding like the rest.
      *
      * Optional only for the pages written before it existed — see {@link recordSlug}.
      */
@@ -1755,6 +1802,8 @@ export declare const LevoEventRegister: ({ eventID, title, external, buttonText,
  */
 export declare const LevoForm: React.FC<ILevoFormProps>;
 
+export declare const levoParams: <TSegment extends string, TPattern extends string, TSiblings extends string = never>(key: TSegment, pattern: TPattern, _siblings?: readonly TSiblings[]) => ILevoParams<TSegment, TPattern, TSiblings>;
+
 /**
  * Mounts the site's popups, wired from `site.json`. Rendered once from the scaffold's
  * `__root` (via the `SitePopups` shim), inside `<LevoSiteProvider>` — `PopupLoader` reads
@@ -1936,6 +1985,12 @@ export declare const parseRawHead: (raw: string) => IComposedHead;
  * source resolves to null so it doesn't blank the whole page — the hook surfaces that
  * binding's error while the rest render.
  *
+ * One failure is NOT absorbed outside production: a record binding whose `param` names no
+ * param of the route. That is a wiring mistake in the page (never a transient fetch error),
+ * it renders as a not-found record that no one can tell from a bad slug, and the preview is
+ * where it gets fixed — so there the loader rejects with the message and the route's error
+ * boundary shows it. See the branch below for what "preview" can mean here.
+ *
  * Returns the fetched values keyed by source key (records as the record object, lists as
  * `{data, meta}`). The route loader returns this map, making it the route's `loaderData` —
  * which `levoHead`'s dynamic config reads for per-record titles/descriptions/share images.