sibujs 4.6.0 → 4.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +1 -1
  2. package/dist/browser.cjs +62 -8
  3. package/dist/browser.d.cts +23 -0
  4. package/dist/browser.d.ts +23 -0
  5. package/dist/browser.js +6 -5
  6. package/dist/build.cjs +2388 -1004
  7. package/dist/build.d.cts +147 -44
  8. package/dist/build.d.ts +147 -44
  9. package/dist/build.js +1410 -564
  10. package/dist/cdn.dev.global.js +14 -12
  11. package/dist/cdn.full.dev.global.js +15 -13
  12. package/dist/cdn.full.global.js +14 -12
  13. package/dist/cdn.global.js +12 -10
  14. package/dist/chunk-3ACAAQIN.js +224 -0
  15. package/dist/{chunk-7NCARGJW.js → chunk-44MTL7ED.js} +6 -6
  16. package/dist/{chunk-BAAG6ZTI.js → chunk-4WMSTZ7J.js} +8 -5
  17. package/dist/{chunk-H3SRKIYX.js → chunk-62BDYGAG.js} +8 -0
  18. package/dist/{chunk-DKGBBKOF.js → chunk-C5PEWEGH.js} +20 -5
  19. package/dist/{chunk-3ISI6ACU.js → chunk-C7AA2CZX.js} +1 -1
  20. package/dist/{chunk-UZQ6ALFS.js → chunk-CZPRSWSS.js} +1 -1
  21. package/dist/{chunk-D33YTSX5.js → chunk-DSID757X.js} +5 -4
  22. package/dist/{chunk-OXUY2A6L.js → chunk-EGUQLBHE.js} +22 -8
  23. package/dist/{chunk-2INLLLMZ.js → chunk-EXXSN3BW.js} +202 -26
  24. package/dist/{chunk-HURREPU2.js → chunk-FC6KCJSA.js} +87 -150
  25. package/dist/{chunk-HYXDKS4N.js → chunk-GSGNX35Q.js} +5 -5
  26. package/dist/{chunk-7GQCWFOE.js → chunk-J3YQ457H.js} +171 -85
  27. package/dist/{chunk-ORMZXBKQ.js → chunk-JUTFX2RM.js} +18 -10
  28. package/dist/{chunk-QE4TTDU3.js → chunk-KJ3UKABJ.js} +12 -11
  29. package/dist/{chunk-XRRZKZYX.js → chunk-LI4W3U6C.js} +1 -1
  30. package/dist/{chunk-47M47FOM.js → chunk-O6TRVMJI.js} +58 -6
  31. package/dist/{chunk-JSXPZCET.js → chunk-Q5J2LVKH.js} +1 -1
  32. package/dist/{chunk-5MT6SJ3P.js → chunk-QGMSESDD.js} +10 -5
  33. package/dist/{chunk-AIF3Z2T7.js → chunk-RGLPEBDE.js} +13 -10
  34. package/dist/{chunk-5Q4R7HCL.js → chunk-TQQUN4WR.js} +11 -2
  35. package/dist/{chunk-PK6FK2G2.js → chunk-UCNP3HVM.js} +183 -30
  36. package/dist/{chunk-XC4MEKGA.js → chunk-V3LHZSU5.js} +8 -2
  37. package/dist/{chunk-VVWPJ543.js → chunk-VWT3VXPL.js} +55 -20
  38. package/dist/{chunk-SXXVZMKZ.js → chunk-ZVLHNEEL.js} +17 -35
  39. package/dist/{contracts-DRIuclVT.d.cts → contracts-CLqzJnOV.d.ts} +28 -17
  40. package/dist/{contracts-DRIuclVT.d.ts → contracts-CTOJXu-x.d.cts} +28 -17
  41. package/dist/{customElement-MmInOW1U.d.ts → customElement-pYDKUzWl.d.cts} +11 -3
  42. package/dist/{customElement-MmInOW1U.d.cts → customElement-pYDKUzWl.d.ts} +11 -3
  43. package/dist/data.cjs +205 -39
  44. package/dist/data.d.cts +119 -3
  45. package/dist/data.d.ts +119 -3
  46. package/dist/data.js +6 -6
  47. package/dist/devtools.cjs +18 -5
  48. package/dist/devtools.js +5 -5
  49. package/dist/ecosystem.cjs +462 -58
  50. package/dist/ecosystem.d.cts +2 -1
  51. package/dist/ecosystem.d.ts +2 -1
  52. package/dist/ecosystem.js +9 -8
  53. package/dist/extras.cjs +852 -296
  54. package/dist/extras.d.cts +5 -4
  55. package/dist/extras.d.ts +5 -4
  56. package/dist/extras.js +24 -23
  57. package/dist/index.cjs +721 -176
  58. package/dist/index.d.cts +220 -169
  59. package/dist/index.d.ts +220 -169
  60. package/dist/index.js +16 -12
  61. package/dist/motion.cjs +12 -4
  62. package/dist/motion.js +3 -3
  63. package/dist/patterns.cjs +37 -21
  64. package/dist/patterns.d.cts +2 -1
  65. package/dist/patterns.d.ts +2 -1
  66. package/dist/patterns.js +6 -6
  67. package/dist/performance.cjs +48 -6
  68. package/dist/performance.d.cts +12 -2
  69. package/dist/performance.d.ts +12 -2
  70. package/dist/performance.js +8 -6
  71. package/dist/plugins.cjs +672 -261
  72. package/dist/plugins.d.cts +131 -13
  73. package/dist/plugins.d.ts +131 -13
  74. package/dist/plugins.js +83 -47
  75. package/dist/{ssr-XOTUASDO.js → ssr-5OWAH3U2.js} +4 -2
  76. package/dist/{ssr-Bli9XRW5.d.cts → ssr-C8hgIAw7.d.cts} +6 -0
  77. package/dist/{ssr-Bli9XRW5.d.ts → ssr-C8hgIAw7.d.ts} +6 -0
  78. package/dist/ssr.cjs +509 -142
  79. package/dist/ssr.d.cts +55 -5
  80. package/dist/ssr.d.ts +55 -5
  81. package/dist/ssr.js +11 -9
  82. package/dist/{tagFactory-DFstCLQV.d.cts → tagFactory-8qL9LCIx.d.cts} +58 -19
  83. package/dist/{tagFactory-DkaNVUNV.d.ts → tagFactory-BL2fymez.d.ts} +58 -19
  84. package/dist/testing.cjs +17 -4
  85. package/dist/testing.js +4 -4
  86. package/dist/types-CJFViL6Q.d.cts +26 -0
  87. package/dist/types-CJFViL6Q.d.ts +26 -0
  88. package/dist/ui.cjs +635 -254
  89. package/dist/ui.d.cts +3 -2
  90. package/dist/ui.d.ts +3 -2
  91. package/dist/ui.js +9 -8
  92. package/dist/widgets.cjs +22 -14
  93. package/dist/widgets.js +7 -7
  94. package/package.json +8 -5
@@ -1,9 +1,20 @@
1
- import { T as TrustedHTML } from './ssr-Bli9XRW5.cjs';
1
+ import { A as Accessor } from './signal-EotCj4hS.cjs';
2
+ import { C as Component$1, N as NodeChildren } from './types-CJFViL6Q.cjs';
3
+ import { T as TrustedHTML } from './ssr-C8hgIAw7.cjs';
2
4
  export { P as PluginContext, a as PluginInstallCancelledError, b as PluginRegistry, S as SibuPlugin, c as createPlugin, d as createPluginRegistry, i as inject, e as isPluginInstallCancelledError, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, f as triggerPluginMount, g as triggerPluginUnmount } from './plugin-DVgSnTfK.cjs';
3
5
  export { L as LazyModule, M as Migration, a as MigrationStorageError, P as PackageExportTarget, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, d as compareSemVer, e as createBootSequence, f as createBundle, g as createMigrationRunner, h as createModuleRegistry, i as createSSRCache, j as createTestHarness, k as deferNonCritical, l as env, m as healthCheck, n as lazyModule, p as packageInfo, o as parseSemVer, q as preloadCritical, r as prerenderRoutes, s as satisfies } from './startup-BLfSeL15.cjs';
4
6
 
5
7
  type Translations = Record<string, string>;
6
- type Params$1 = Record<string, string | number>;
8
+ /**
9
+ * Interpolation parameters for `t()`, `translated()` and `Trans()`.
10
+ *
11
+ * A value may be a GETTER (a signal accessor or any `() => value`). Getters are
12
+ * called at lookup time, so inside a binding the parameter is tracked exactly
13
+ * like the locale: `translated("hello", { name: userName })` re-renders when
14
+ * either `userName` or the locale changes.
15
+ */
16
+ type TranslationParams = Record<string, string | number | (() => string | number)>;
17
+ type Params$1 = TranslationParams;
7
18
  /**
8
19
  * Set the active locale.
9
20
  *
@@ -56,21 +67,72 @@ declare function getLocale(): string;
56
67
  * because the assignment form would invoke the inherited `__proto__` setter for
57
68
  * a locale of that name instead of registering it. Locale names and translation
58
69
  * keys are treated literally throughout — see PROTOTYPE SAFETY above.
70
+ *
71
+ * NOTIFY. Every registration bumps the dictionary revision, so bindings that
72
+ * already rendered a key re-run and pick the new message up — the order of
73
+ * `setLocale()` and `registerTranslations()` no longer matters. The bump comes
74
+ * after publication, so a re-running binding can only ever see the new
75
+ * dictionary.
59
76
  */
60
77
  declare function registerTranslations(locale: string, messages: Translations): void;
61
78
  /**
62
79
  * Translate `key` in the current locale, falling back to the key itself when it
63
80
  * is not registered. A registered empty string is a translation and is returned
64
81
  * unchanged; the previous `|| key` discarded it and returned the key.
82
+ *
83
+ * `t()` returns a STRING — a snapshot. It is live only when it is read inside a
84
+ * binding (`span(() => t("hello"))`), because that binding is what re-runs.
85
+ * Called directly in a component body, `span(t("hello"))` renders the message
86
+ * once and never updates. For anything on screen prefer {@link translated},
87
+ * which hands the binding a getter and works for text children and attributes
88
+ * alike. `t()` remains the right call for one-off strings: event handlers,
89
+ * `confirm()` prompts, log lines, server renders.
90
+ *
91
+ * Parameter getters are resolved on every call, so `t("hi", { name: userName })`
92
+ * inside a binding tracks `userName` too.
65
93
  */
66
94
  declare function t(key: string, params?: Params$1): string;
67
95
  /**
68
- * Trans component — renders a translated string reactively.
69
- * Automatically updates when the client locale changes. During SSR it renders
70
- * once, using the locale belonging to the current request.
96
+ * A LIVE translation: returns a getter that re-reads the message every time a
97
+ * binding calls it. Pass it anywhere the tag factories accept a reactive value
98
+ * — a text child or any attribute — and only that one text node or attribute
99
+ * updates when the locale changes, when messages for it are registered later,
100
+ * or when a getter parameter changes. The surrounding elements are never
101
+ * rebuilt, so focus, typed input values and element identity survive a language
102
+ * switch.
103
+ *
104
+ * During SSR the binding evaluates once, using the locale of the current
105
+ * request.
106
+ *
107
+ * @param key Translation key
108
+ * @param params Optional interpolation parameters; values may be getters
109
+ * @returns An accessor producing the translated string
110
+ *
111
+ * @example
112
+ * ```ts
113
+ * const [userName] = signal("Ada");
114
+ *
115
+ * header([
116
+ * h1(translated("app.title")),
117
+ * span(translated("greeting", { name: userName })),
118
+ * input({ placeholder: translated("search.placeholder"), "aria-label": translated("search.label") }),
119
+ * ]);
120
+ *
121
+ * setLocale("es"); // text and attributes update in place — no re-render
122
+ * ```
123
+ */
124
+ declare function translated(key: string, params?: Params$1): Accessor<string>;
125
+ /**
126
+ * Trans component — renders a translated string reactively inside a `<span>`.
127
+ * Automatically updates when the client locale changes, when messages for the
128
+ * active locale are registered, and when a getter parameter changes. During SSR
129
+ * it renders once, using the locale belonging to the current request.
130
+ *
131
+ * When no wrapper element is wanted, pass {@link translated} straight to the
132
+ * parent instead: `p(translated("greeting"))`.
71
133
  *
72
134
  * @param key Translation key
73
- * @param params Optional interpolation parameters
135
+ * @param params Optional interpolation parameters; values may be getters
74
136
  * @returns An HTMLElement (span) that reactively shows the translated text
75
137
  *
76
138
  * @example
@@ -78,8 +140,8 @@ declare function t(key: string, params?: Params$1): string;
78
140
  * registerTranslations("en", { greeting: "Hello, {name}!" });
79
141
  * registerTranslations("es", { greeting: "Hola, {name}!" });
80
142
  *
81
- * div([Trans("greeting", { name: "World" })]);
82
- * // When locale changes, the text updates automatically
143
+ * div([Trans("greeting", { name: userName })]);
144
+ * // When the locale or userName changes, the text updates automatically
83
145
  * ```
84
146
  */
85
147
  declare function Trans(key: string, params?: Params$1): HTMLElement;
@@ -98,10 +160,18 @@ declare function hasTranslation(key: string): boolean;
98
160
  *
99
161
  * Own enumerable keys, so a locale is listed exactly when it was registered -
100
162
  * including one named `"__proto__"`, which publication now stores literally.
163
+ *
164
+ * Read inside a binding the list is live: registering a new locale re-runs it,
165
+ * so a language picker built from it picks up lazily loaded locales.
101
166
  */
102
167
  declare function getAvailableLocales(): string[];
103
168
 
104
- type Component = () => Element;
169
+ /**
170
+ * A route component. An alias of the public `Component` (props-less, any
171
+ * `Element` root), kept under this name so existing imports of the router's
172
+ * `Component` continue to work.
173
+ */
174
+ type Component = Component$1<void, Element>;
105
175
  type AsyncComponent = () => Promise<Element>;
106
176
  type LazyComponent = () => Promise<{
107
177
  default: Component;
@@ -127,6 +197,41 @@ interface RouteBase {
127
197
  readonly children?: RouteDef[];
128
198
  readonly beforeEnter?: Guard | Guard[];
129
199
  readonly alias?: string | string[];
200
+ /**
201
+ * Identity of the mounted instance of this route's component.
202
+ *
203
+ * When a navigation stays on this route but the key changes, the outlet
204
+ * disposes the old instance (running its `onUnmount` / `onCleanup`
205
+ * callbacks and releasing its bindings) and mounts a fresh one — so a page
206
+ * that reads `route().params.id` once at setup always sees the right id.
207
+ *
208
+ * **Default:** the path params this record declares in its *own* path (and
209
+ * aliases). `/records/1` → `/records/2` remounts; `?tab=a` → `?tab=b` or a
210
+ * hash change does not. A parent layout is not remounted when only a child's
211
+ * param changes — the child's `Outlet()` remounts the child instead. A
212
+ * record with no params of its own is never remounted by a param change, and
213
+ * a `*` tail (`pathMatch`) is not part of the default: a catch-all keeps its
214
+ * instance and reads `pathMatch` reactively (`key: (r) => r.params.pathMatch`
215
+ * remounts per path).
216
+ *
217
+ * **Override:** return any string derived from the route. Return a constant
218
+ * to keep one long-lived instance across param changes (the instance must
219
+ * then read params reactively, e.g. `routerState().params()` or
220
+ * `() => route().params.id`). Include query values to also remount on a
221
+ * query change.
222
+ *
223
+ * Called untracked with the committed route. Ignored by `KeepAliveRoute()`,
224
+ * which already keeps one instance per full location.
225
+ *
226
+ * @example
227
+ * ```ts
228
+ * // Keep one instance for every record; the page reads params reactively.
229
+ * { path: "/records/:id", component: RecordPage, key: () => "record" }
230
+ * // Also remount when ?tab changes.
231
+ * { path: "/records/:id", component: RecordPage, key: (r) => `${r.params.id}|${r.query.tab ?? ""}` }
232
+ * ```
233
+ */
234
+ readonly key?: (route: RouteContext) => string;
130
235
  }
131
236
  interface ComponentRoute extends RouteBase {
132
237
  readonly component: Component;
@@ -367,6 +472,11 @@ declare function setRoutes(routes: RouteDef[]): void;
367
472
  /**
368
473
  * Read the current route as a plain snapshot.
369
474
  *
475
+ * Reading it once in a route component's setup is safe: when a navigation
476
+ * changes that route's own params, the outlet mounts a fresh instance (see
477
+ * `RouteBase.key`). Inside a getter — `() => route().params.id` — the read is
478
+ * reactive, which is what a long-lived layout or a constant-`key` route needs.
479
+ *
370
480
  * @returns The active {@link RouteContext} (path, params, query, hash).
371
481
  * @throws If no router has been created yet.
372
482
  */
@@ -456,7 +566,10 @@ declare function beforeResolve(guard: NavigationGuard): () => void;
456
566
  declare function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
457
567
  /**
458
568
  * The route outlet: renders whichever component matches the current route, and
459
- * swaps it on every navigation.
569
+ * swaps it when the top-level matched record or its instance key changes. By
570
+ * default the key is that record's own path params, so `/records/1` →
571
+ * `/records/2` mounts a fresh instance while a query- or hash-only change keeps
572
+ * the current one (see `RouteBase.key`).
460
573
  *
461
574
  * @returns A Comment anchor that manages the matched component. Like every
462
575
  * factory here it hands back a live node the caller can insert directly.
@@ -525,11 +638,11 @@ declare function RouterLink(props: {
525
638
  activeClass?: string;
526
639
  exactActiveClass?: string;
527
640
  /** @deprecated Pass children positionally: `RouterLink(props, children)`. */
528
- nodes?: string | Node | (string | Node)[];
641
+ nodes?: NodeChildren;
529
642
  target?: string;
530
643
  rel?: string;
531
644
  [key: string]: unknown;
532
- }, children?: string | Node | (string | Node)[]): HTMLAnchorElement;
645
+ }, children?: NodeChildren): HTMLAnchorElement;
533
646
  /**
534
647
  * Async boundary for code-split / deferred content.
535
648
  *
@@ -617,6 +730,11 @@ declare function __removeRouterPagehideHandler(): void;
617
730
  /**
618
731
  * Outlet renders the child route component within a layout.
619
732
  * Use inside a parent route's component to render matched children.
733
+ *
734
+ * The child is remounted when the matched child record changes or when its
735
+ * instance key does — by default the params declared below the top-level
736
+ * record, so a child-only param change remounts the child and leaves the
737
+ * layout in place (see `RouteBase.key`).
620
738
  */
621
739
  declare function Outlet(): Node;
622
740
  /**
@@ -782,4 +900,4 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
782
900
  }) => string;
783
901
  };
784
902
 
785
- export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };
903
+ export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, type TranslationParams, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t, translated };
package/dist/plugins.d.ts CHANGED
@@ -1,9 +1,20 @@
1
- import { T as TrustedHTML } from './ssr-Bli9XRW5.js';
1
+ import { A as Accessor } from './signal-EotCj4hS.js';
2
+ import { C as Component$1, N as NodeChildren } from './types-CJFViL6Q.js';
3
+ import { T as TrustedHTML } from './ssr-C8hgIAw7.js';
2
4
  export { P as PluginContext, a as PluginInstallCancelledError, b as PluginRegistry, S as SibuPlugin, c as createPlugin, d as createPluginRegistry, i as inject, e as isPluginInstallCancelledError, p as plugin, r as resetPlugins, s as setDefaultPluginRegistry, t as triggerPluginError, f as triggerPluginMount, g as triggerPluginUnmount } from './plugin-DVgSnTfK.js';
3
5
  export { L as LazyModule, M as Migration, a as MigrationStorageError, P as PackageExportTarget, S as SemVer, V as VERSION, b as bundlerMetadata, c as checkCompatibility, d as compareSemVer, e as createBootSequence, f as createBundle, g as createMigrationRunner, h as createModuleRegistry, i as createSSRCache, j as createTestHarness, k as deferNonCritical, l as env, m as healthCheck, n as lazyModule, p as packageInfo, o as parseSemVer, q as preloadCritical, r as prerenderRoutes, s as satisfies } from './startup-BLfSeL15.js';
4
6
 
5
7
  type Translations = Record<string, string>;
6
- type Params$1 = Record<string, string | number>;
8
+ /**
9
+ * Interpolation parameters for `t()`, `translated()` and `Trans()`.
10
+ *
11
+ * A value may be a GETTER (a signal accessor or any `() => value`). Getters are
12
+ * called at lookup time, so inside a binding the parameter is tracked exactly
13
+ * like the locale: `translated("hello", { name: userName })` re-renders when
14
+ * either `userName` or the locale changes.
15
+ */
16
+ type TranslationParams = Record<string, string | number | (() => string | number)>;
17
+ type Params$1 = TranslationParams;
7
18
  /**
8
19
  * Set the active locale.
9
20
  *
@@ -56,21 +67,72 @@ declare function getLocale(): string;
56
67
  * because the assignment form would invoke the inherited `__proto__` setter for
57
68
  * a locale of that name instead of registering it. Locale names and translation
58
69
  * keys are treated literally throughout — see PROTOTYPE SAFETY above.
70
+ *
71
+ * NOTIFY. Every registration bumps the dictionary revision, so bindings that
72
+ * already rendered a key re-run and pick the new message up — the order of
73
+ * `setLocale()` and `registerTranslations()` no longer matters. The bump comes
74
+ * after publication, so a re-running binding can only ever see the new
75
+ * dictionary.
59
76
  */
60
77
  declare function registerTranslations(locale: string, messages: Translations): void;
61
78
  /**
62
79
  * Translate `key` in the current locale, falling back to the key itself when it
63
80
  * is not registered. A registered empty string is a translation and is returned
64
81
  * unchanged; the previous `|| key` discarded it and returned the key.
82
+ *
83
+ * `t()` returns a STRING — a snapshot. It is live only when it is read inside a
84
+ * binding (`span(() => t("hello"))`), because that binding is what re-runs.
85
+ * Called directly in a component body, `span(t("hello"))` renders the message
86
+ * once and never updates. For anything on screen prefer {@link translated},
87
+ * which hands the binding a getter and works for text children and attributes
88
+ * alike. `t()` remains the right call for one-off strings: event handlers,
89
+ * `confirm()` prompts, log lines, server renders.
90
+ *
91
+ * Parameter getters are resolved on every call, so `t("hi", { name: userName })`
92
+ * inside a binding tracks `userName` too.
65
93
  */
66
94
  declare function t(key: string, params?: Params$1): string;
67
95
  /**
68
- * Trans component — renders a translated string reactively.
69
- * Automatically updates when the client locale changes. During SSR it renders
70
- * once, using the locale belonging to the current request.
96
+ * A LIVE translation: returns a getter that re-reads the message every time a
97
+ * binding calls it. Pass it anywhere the tag factories accept a reactive value
98
+ * — a text child or any attribute — and only that one text node or attribute
99
+ * updates when the locale changes, when messages for it are registered later,
100
+ * or when a getter parameter changes. The surrounding elements are never
101
+ * rebuilt, so focus, typed input values and element identity survive a language
102
+ * switch.
103
+ *
104
+ * During SSR the binding evaluates once, using the locale of the current
105
+ * request.
106
+ *
107
+ * @param key Translation key
108
+ * @param params Optional interpolation parameters; values may be getters
109
+ * @returns An accessor producing the translated string
110
+ *
111
+ * @example
112
+ * ```ts
113
+ * const [userName] = signal("Ada");
114
+ *
115
+ * header([
116
+ * h1(translated("app.title")),
117
+ * span(translated("greeting", { name: userName })),
118
+ * input({ placeholder: translated("search.placeholder"), "aria-label": translated("search.label") }),
119
+ * ]);
120
+ *
121
+ * setLocale("es"); // text and attributes update in place — no re-render
122
+ * ```
123
+ */
124
+ declare function translated(key: string, params?: Params$1): Accessor<string>;
125
+ /**
126
+ * Trans component — renders a translated string reactively inside a `<span>`.
127
+ * Automatically updates when the client locale changes, when messages for the
128
+ * active locale are registered, and when a getter parameter changes. During SSR
129
+ * it renders once, using the locale belonging to the current request.
130
+ *
131
+ * When no wrapper element is wanted, pass {@link translated} straight to the
132
+ * parent instead: `p(translated("greeting"))`.
71
133
  *
72
134
  * @param key Translation key
73
- * @param params Optional interpolation parameters
135
+ * @param params Optional interpolation parameters; values may be getters
74
136
  * @returns An HTMLElement (span) that reactively shows the translated text
75
137
  *
76
138
  * @example
@@ -78,8 +140,8 @@ declare function t(key: string, params?: Params$1): string;
78
140
  * registerTranslations("en", { greeting: "Hello, {name}!" });
79
141
  * registerTranslations("es", { greeting: "Hola, {name}!" });
80
142
  *
81
- * div([Trans("greeting", { name: "World" })]);
82
- * // When locale changes, the text updates automatically
143
+ * div([Trans("greeting", { name: userName })]);
144
+ * // When the locale or userName changes, the text updates automatically
83
145
  * ```
84
146
  */
85
147
  declare function Trans(key: string, params?: Params$1): HTMLElement;
@@ -98,10 +160,18 @@ declare function hasTranslation(key: string): boolean;
98
160
  *
99
161
  * Own enumerable keys, so a locale is listed exactly when it was registered -
100
162
  * including one named `"__proto__"`, which publication now stores literally.
163
+ *
164
+ * Read inside a binding the list is live: registering a new locale re-runs it,
165
+ * so a language picker built from it picks up lazily loaded locales.
101
166
  */
102
167
  declare function getAvailableLocales(): string[];
103
168
 
104
- type Component = () => Element;
169
+ /**
170
+ * A route component. An alias of the public `Component` (props-less, any
171
+ * `Element` root), kept under this name so existing imports of the router's
172
+ * `Component` continue to work.
173
+ */
174
+ type Component = Component$1<void, Element>;
105
175
  type AsyncComponent = () => Promise<Element>;
106
176
  type LazyComponent = () => Promise<{
107
177
  default: Component;
@@ -127,6 +197,41 @@ interface RouteBase {
127
197
  readonly children?: RouteDef[];
128
198
  readonly beforeEnter?: Guard | Guard[];
129
199
  readonly alias?: string | string[];
200
+ /**
201
+ * Identity of the mounted instance of this route's component.
202
+ *
203
+ * When a navigation stays on this route but the key changes, the outlet
204
+ * disposes the old instance (running its `onUnmount` / `onCleanup`
205
+ * callbacks and releasing its bindings) and mounts a fresh one — so a page
206
+ * that reads `route().params.id` once at setup always sees the right id.
207
+ *
208
+ * **Default:** the path params this record declares in its *own* path (and
209
+ * aliases). `/records/1` → `/records/2` remounts; `?tab=a` → `?tab=b` or a
210
+ * hash change does not. A parent layout is not remounted when only a child's
211
+ * param changes — the child's `Outlet()` remounts the child instead. A
212
+ * record with no params of its own is never remounted by a param change, and
213
+ * a `*` tail (`pathMatch`) is not part of the default: a catch-all keeps its
214
+ * instance and reads `pathMatch` reactively (`key: (r) => r.params.pathMatch`
215
+ * remounts per path).
216
+ *
217
+ * **Override:** return any string derived from the route. Return a constant
218
+ * to keep one long-lived instance across param changes (the instance must
219
+ * then read params reactively, e.g. `routerState().params()` or
220
+ * `() => route().params.id`). Include query values to also remount on a
221
+ * query change.
222
+ *
223
+ * Called untracked with the committed route. Ignored by `KeepAliveRoute()`,
224
+ * which already keeps one instance per full location.
225
+ *
226
+ * @example
227
+ * ```ts
228
+ * // Keep one instance for every record; the page reads params reactively.
229
+ * { path: "/records/:id", component: RecordPage, key: () => "record" }
230
+ * // Also remount when ?tab changes.
231
+ * { path: "/records/:id", component: RecordPage, key: (r) => `${r.params.id}|${r.query.tab ?? ""}` }
232
+ * ```
233
+ */
234
+ readonly key?: (route: RouteContext) => string;
130
235
  }
131
236
  interface ComponentRoute extends RouteBase {
132
237
  readonly component: Component;
@@ -367,6 +472,11 @@ declare function setRoutes(routes: RouteDef[]): void;
367
472
  /**
368
473
  * Read the current route as a plain snapshot.
369
474
  *
475
+ * Reading it once in a route component's setup is safe: when a navigation
476
+ * changes that route's own params, the outlet mounts a fresh instance (see
477
+ * `RouteBase.key`). Inside a getter — `() => route().params.id` — the read is
478
+ * reactive, which is what a long-lived layout or a constant-`key` route needs.
479
+ *
370
480
  * @returns The active {@link RouteContext} (path, params, query, hash).
371
481
  * @throws If no router has been created yet.
372
482
  */
@@ -456,7 +566,10 @@ declare function beforeResolve(guard: NavigationGuard): () => void;
456
566
  declare function afterEach(hook: (to: RouteContext, from: RouteContext) => void): () => void;
457
567
  /**
458
568
  * The route outlet: renders whichever component matches the current route, and
459
- * swaps it on every navigation.
569
+ * swaps it when the top-level matched record or its instance key changes. By
570
+ * default the key is that record's own path params, so `/records/1` →
571
+ * `/records/2` mounts a fresh instance while a query- or hash-only change keeps
572
+ * the current one (see `RouteBase.key`).
460
573
  *
461
574
  * @returns A Comment anchor that manages the matched component. Like every
462
575
  * factory here it hands back a live node the caller can insert directly.
@@ -525,11 +638,11 @@ declare function RouterLink(props: {
525
638
  activeClass?: string;
526
639
  exactActiveClass?: string;
527
640
  /** @deprecated Pass children positionally: `RouterLink(props, children)`. */
528
- nodes?: string | Node | (string | Node)[];
641
+ nodes?: NodeChildren;
529
642
  target?: string;
530
643
  rel?: string;
531
644
  [key: string]: unknown;
532
- }, children?: string | Node | (string | Node)[]): HTMLAnchorElement;
645
+ }, children?: NodeChildren): HTMLAnchorElement;
533
646
  /**
534
647
  * Async boundary for code-split / deferred content.
535
648
  *
@@ -617,6 +730,11 @@ declare function __removeRouterPagehideHandler(): void;
617
730
  /**
618
731
  * Outlet renders the child route component within a layout.
619
732
  * Use inside a parent route's component to render matched children.
733
+ *
734
+ * The child is remounted when the matched child record changes or when its
735
+ * instance key does — by default the params declared below the top-level
736
+ * record, so a child-only param change remounts the child and leaves the
737
+ * layout in place (see `RouteBase.key`).
620
738
  */
621
739
  declare function Outlet(): Node;
622
740
  /**
@@ -782,4 +900,4 @@ declare function createSSRRouter(routes: SSRRouteDef[]): {
782
900
  }) => string;
783
901
  };
784
902
 
785
- export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t };
903
+ export { type AsyncComponent, type AsyncRoute, type Component, type ComponentRoute, type Guard, type GuardResult, KeepAliveRoute, type LazyComponent, type LazyRoute, type NavigationFailure, type NavigationFailureReason, type NavigationGuard, type NavigationNext, type NavigationResult, type NavigationTarget, Outlet, type Params, type RedirectRoute, Route, type RouteBase, type RouteContext, type RouteDef, type RouteMeta, type RouteTransitionOptions, RouterLink, type RouterOptions, type RouterPlugin, type SSRRouteDef, type SSRRouteState, type ScrollBehavior, type ScrollPosition, SibuRouter, Suspense, Trans, type TranslationParams, __getNavigationEpoch, __removeRouterPagehideHandler, addRoute, afterEach, back, beforeEach, beforeResolve, buildURL, createMemoryRouter, createRouter, createSSRRouter, deserializeRouteState, destroyRouter, forward, getAvailableLocales, getLocale, getRouteInfo, getRouteTransition, go, hasRoute, hasTranslation, hydrateRouter, lazy, navigate, preloadRoute, push, registerTranslations, removeRoute, renderRouteToDocument, renderRouteToString, replace, resolveServerRoute, route, router, routerPlugin, routerState, serializeRouteState, setLocale, setRouteTransition, setRoutes, t, translated };