@nestjs-ssr/react 0.2.5 → 0.3.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 (27) hide show
  1. package/README.md +7 -7
  2. package/dist/cli/init.js +35 -72
  3. package/dist/cli/init.mjs +35 -72
  4. package/dist/client.d.mts +55 -304
  5. package/dist/client.d.ts +55 -304
  6. package/dist/client.js +360 -13
  7. package/dist/client.mjs +336 -5
  8. package/dist/{index-BMdluY1g.d.mts → index-BzOLOiIZ.d.ts} +207 -44
  9. package/dist/{index-rl0S5kqW.d.ts → index-DdE--mA2.d.mts} +207 -44
  10. package/dist/index.d.mts +4 -4
  11. package/dist/index.d.ts +4 -4
  12. package/dist/index.js +646 -317
  13. package/dist/index.mjs +640 -319
  14. package/dist/render/index.d.mts +2 -2
  15. package/dist/render/index.d.ts +2 -2
  16. package/dist/render/index.js +610 -315
  17. package/dist/render/index.mjs +610 -315
  18. package/dist/{render-response.interface-Dc-Kwb09.d.mts → render-response.interface-CxbuKGnV.d.mts} +57 -1
  19. package/dist/{render-response.interface-Dc-Kwb09.d.ts → render-response.interface-CxbuKGnV.d.ts} +57 -1
  20. package/dist/templates/entry-client.tsx +21 -5
  21. package/dist/templates/entry-server.tsx +28 -6
  22. package/dist/use-page-context-05ODF4zW.d.ts +281 -0
  23. package/dist/use-page-context-CGT9woWe.d.mts +281 -0
  24. package/package.json +1 -1
  25. package/src/global.d.ts +11 -0
  26. package/src/templates/entry-client.tsx +21 -5
  27. package/src/templates/entry-server.tsx +28 -6
package/dist/client.d.mts CHANGED
@@ -1,319 +1,70 @@
1
+ export { a as PageContextProvider, P as PageProps, c as createSSRHooks, j as updatePageContext, i as useCookie, h as useCookies, g as useHeader, f as useHeaders, u as usePageContext, b as useParams, d as useQuery, e as useRequest } from './use-page-context-CGT9woWe.mjs';
1
2
  import * as react_jsx_runtime from 'react/jsx-runtime';
2
3
  import React from 'react';
3
- import { H as HeadData } from './render-response.interface-Dc-Kwb09.mjs';
4
+ export { R as RenderContext } from './render-response.interface-CxbuKGnV.mjs';
4
5
 
5
6
  /**
6
- * Request context available to all React components.
7
- * Contains safe request metadata that can be exposed to the client.
8
- *
9
- * Extend this interface to add app-specific properties (user, tenant, feature flags, etc.).
10
- * Use module configuration to pass additional headers or cookies safely.
11
- *
12
- * @example
13
- * // Basic usage - use as-is
14
- * const context: RenderContext = {
15
- * url: '/users/123',
16
- * path: '/users/123',
17
- * query: { tab: 'profile' },
18
- * params: { id: '123' },
19
- * method: 'GET',
20
- * };
21
- *
22
- * @example
23
- * // Extended usage - add custom properties for your app
24
- * interface AppRenderContext extends RenderContext {
25
- * user?: {
26
- * id: string;
27
- * name: string;
28
- * email: string;
29
- * roles: string[];
30
- * };
31
- * tenant?: {
32
- * id: string;
33
- * name: string;
34
- * };
35
- * featureFlags?: Record<string, boolean>;
36
- * theme?: string; // From cookie
37
- * }
38
- *
39
- * // Configure module to pass specific cookies/headers
40
- * ReactSSRModule.forRoot({
41
- * allowedCookies: ['theme', 'locale'],
42
- * allowedHeaders: ['x-tenant-id'],
43
- * })
44
- *
45
- * // Use in interceptor/controller
46
- * const context: AppRenderContext = {
47
- * ...baseContext,
48
- * user: req.user,
49
- * tenant: req.tenant,
50
- * featureFlags: await featureFlagService.getFlags(req),
51
- * };
7
+ * Provider component for navigation state.
8
+ * Wrap your app with this to enable useNavigation hooks.
52
9
  */
53
- interface RenderContext {
54
- url: string;
55
- path: string;
56
- query: Record<string, string | string[]>;
57
- params: Record<string, string>;
58
- method: string;
59
- }
10
+ declare function NavigationProvider({ children, }: {
11
+ children: React.ReactNode;
12
+ }): react_jsx_runtime.JSX.Element;
60
13
 
14
+ interface NavigateOptions {
15
+ /** Use replaceState instead of pushState. Default: false */
16
+ replace?: boolean;
17
+ /** Scroll to top after navigation. Default: true */
18
+ scroll?: boolean;
19
+ }
61
20
  /**
62
- * Generic type for React page component props.
63
- * Spreads controller data directly as props (React-standard pattern).
64
- *
65
- * Request context is available via typed hooks created with createSSRHooks().
66
- *
67
- * @template TProps - The shape of props returned by the controller
68
- *
69
- * @example
70
- * ```typescript
71
- * // src/lib/ssr-hooks.ts
72
- * import { createSSRHooks, RenderContext } from '@nestjs-ssr/react';
73
- *
74
- * interface AppRenderContext extends RenderContext {
75
- * user?: User;
76
- * }
77
- *
78
- * export const { usePageContext } = createSSRHooks<AppRenderContext>();
79
- *
80
- * // src/views/product.tsx
81
- * import { usePageContext } from '@/lib/ssr-hooks';
82
- *
83
- * interface ProductPageProps {
84
- * product: Product;
85
- * relatedProducts: Product[];
86
- * }
87
- *
88
- * export default function ProductDetail(props: PageProps<ProductPageProps>) {
89
- * const { product, relatedProducts, head } = props;
90
- * const context = usePageContext(); // Fully typed!
91
- *
92
- * return (
93
- * <html>
94
- * <head>
95
- * <title>{head?.title || product.name}</title>
96
- * </head>
97
- * <body>
98
- * <h1>{product.name}</h1>
99
- * <p>Current path: {context.path}</p>
100
- * </body>
101
- * </html>
102
- * );
103
- * }
104
- * ```
21
+ * Navigate to a new URL using client-side segment rendering.
22
+ * Falls back to full page navigation if:
23
+ * - No layouts are present in the DOM
24
+ * - No common ancestor layout exists between current and target page
25
+ * - The fetch fails
105
26
  */
106
- type PageProps<TProps = {}> = TProps & {
107
- /**
108
- * Optional head metadata for SEO (title, description, og tags, etc.)
109
- * Pass from controller to populate meta tags, Open Graph, etc.
110
- *
111
- * @example
112
- * ```typescript
113
- * // In controller:
114
- * return {
115
- * product,
116
- * head: {
117
- * title: product.name,
118
- * description: product.description,
119
- * }
120
- * };
121
- *
122
- * // In component:
123
- * <head>
124
- * <title>{props.head?.title}</title>
125
- * <meta name="description" content={props.head?.description} />
126
- * </head>
127
- * ```
128
- */
129
- head?: HeadData;
130
- };
27
+ declare function navigate(url: string, options?: NavigateOptions): Promise<void>;
131
28
 
29
+ interface LinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
30
+ /** The URL to navigate to */
31
+ href: string;
32
+ /** Use replaceState instead of pushState. Default: false */
33
+ replace?: boolean;
34
+ /** Scroll to top after navigation. Default: true */
35
+ scroll?: boolean;
36
+ }
132
37
  /**
133
- * Provider component that makes page context available to all child components.
134
- * Should wrap the entire app in entry-server and entry-client.
38
+ * Client-side navigation link component.
39
+ * Performs segment rendering for same-origin navigation.
40
+ *
41
+ * Falls back to default browser navigation for:
42
+ * - External links (different origin)
43
+ * - Modified clicks (ctrl/cmd/shift/alt)
44
+ * - Middle mouse button clicks
45
+ * - Links with target="_blank"
135
46
  */
136
- declare function PageContextProvider({ context, children, }: {
137
- context: RenderContext;
138
- children: React.ReactNode;
139
- }): react_jsx_runtime.JSX.Element;
47
+ declare function Link({ href, replace, scroll, children, onClick, ...props }: LinkProps): react_jsx_runtime.JSX.Element;
48
+
140
49
  /**
141
- * Factory function to create typed SSR hooks bound to your app's context type.
142
- * Use this once in your app to create hooks with full type safety.
143
- *
144
- * This eliminates the need to pass generic types to every hook call,
145
- * providing excellent DX with full IntelliSense support.
146
- *
147
- * @template T - Your extended RenderContext type with app-specific properties
148
- *
149
- * @example
150
- * ```typescript
151
- * // src/lib/ssr-hooks.ts - Define once
152
- * import { createSSRHooks, RenderContext } from '@nestjs-ssr/react';
153
- *
154
- * interface AppRenderContext extends RenderContext {
155
- * user?: {
156
- * id: string;
157
- * name: string;
158
- * email: string;
159
- * };
160
- * tenant?: { id: string; name: string };
161
- * featureFlags?: Record<string, boolean>;
162
- * theme?: string; // From cookie
163
- * }
164
- *
165
- * export const {
166
- * usePageContext,
167
- * useParams,
168
- * useQuery,
169
- * useRequest,
170
- * useHeaders,
171
- * useHeader,
172
- * useCookies,
173
- * useCookie,
174
- * } = createSSRHooks<AppRenderContext>();
175
- *
176
- * // Create custom helper hooks
177
- * export const useUser = () => usePageContext().user;
178
- * export const useTheme = () => useCookie('theme');
179
- * export const useUserAgent = () => useHeader('user-agent');
180
- * ```
181
- *
182
- * @example
183
- * ```typescript
184
- * // src/views/home.tsx - Use everywhere with full types
185
- * import { usePageContext, useUser, useTheme, useCookie, useHeader } from '@/lib/ssr-hooks';
186
- *
187
- * export default function Home() {
188
- * const { user, featureFlags } = usePageContext(); // ✅ Fully typed!
189
- * const user = useUser(); // ✅ Also typed!
190
- * const theme = useTheme(); // ✅ From cookie
191
- * const locale = useCookie('locale'); // ✅ Access specific cookie
192
- * const tenantId = useHeader('x-tenant-id'); // ✅ Access specific header
193
- *
194
- * return (
195
- * <div>
196
- * <h1>Welcome {user?.name}</h1>
197
- * <p>Theme: {theme}</p>
198
- * <p>Locale: {locale}</p>
199
- * <p>Tenant: {tenantId}</p>
200
- * </div>
201
- * );
202
- * }
203
- * ```
50
+ * Hook to access navigation state and navigate function.
204
51
  */
205
- declare function createSSRHooks<T extends RenderContext = RenderContext>(): {
206
- /**
207
- * Hook to access the full page context with your app's type.
208
- * Contains URL metadata, headers, and any custom properties you've added.
209
- */
210
- usePageContext: () => T;
211
- /**
212
- * Hook to access route parameters.
213
- *
214
- * @example
215
- * ```tsx
216
- * // Route: /users/:id
217
- * const params = useParams();
218
- * console.log(params.id); // '123'
219
- * ```
220
- */
221
- useParams: () => Record<string, string>;
222
- /**
223
- * Hook to access query string parameters.
224
- *
225
- * @example
226
- * ```tsx
227
- * // URL: /search?q=react&sort=date
228
- * const query = useQuery();
229
- * console.log(query.q); // 'react'
230
- * console.log(query.sort); // 'date'
231
- * ```
232
- */
233
- useQuery: () => Record<string, string | string[]>;
234
- /**
235
- * Alias for usePageContext() with a more intuitive name.
236
- * Returns the full request context with your app's type.
237
- *
238
- * @example
239
- * ```tsx
240
- * const request = useRequest();
241
- * console.log(request.path); // '/users/123'
242
- * console.log(request.method); // 'GET'
243
- * console.log(request.params); // { id: '123' }
244
- * console.log(request.query); // { search: 'foo' }
245
- * ```
246
- */
247
- useRequest: () => T;
248
- /**
249
- * Hook to access headers configured via allowedHeaders.
250
- * Returns all headers as a Record.
251
- *
252
- * Configure in module registration:
253
- * ```typescript
254
- * RenderModule.forRoot({
255
- * allowedHeaders: ['user-agent', 'x-tenant-id', 'x-api-version']
256
- * })
257
- * ```
258
- *
259
- * @example
260
- * ```tsx
261
- * const headers = useHeaders();
262
- * console.log(headers['user-agent']); // 'Mozilla/5.0...'
263
- * console.log(headers['x-tenant-id']); // 'tenant-123'
264
- * console.log(headers['x-api-version']); // 'v2'
265
- * ```
266
- */
267
- useHeaders: () => Record<string, string>;
268
- /**
269
- * Hook to access a specific custom header by name.
270
- * Returns undefined if the header is not configured or not present.
271
- *
272
- * @param name - The header name (as configured in allowedHeaders)
273
- *
274
- * @example
275
- * ```tsx
276
- * const tenantId = useHeader('x-tenant-id');
277
- * if (tenantId) {
278
- * console.log(`Tenant: ${tenantId}`);
279
- * }
280
- * ```
281
- */
282
- useHeader: (name: string) => string | undefined;
283
- /**
284
- * Hook to access cookies configured via allowedCookies.
285
- * Returns all allowed cookies as a Record.
286
- *
287
- * Configure in module registration:
288
- * ```typescript
289
- * RenderModule.forRoot({
290
- * allowedCookies: ['theme', 'locale', 'consent']
291
- * })
292
- * ```
293
- *
294
- * @example
295
- * ```tsx
296
- * const cookies = useCookies();
297
- * console.log(cookies.theme); // 'dark'
298
- * console.log(cookies.locale); // 'en-US'
299
- * ```
300
- */
301
- useCookies: () => Record<string, string>;
302
- /**
303
- * Hook to access a specific cookie by name.
304
- * Returns undefined if the cookie is not configured or not present.
305
- *
306
- * @param name - The cookie name (as configured in allowedCookies)
307
- *
308
- * @example
309
- * ```tsx
310
- * const theme = useCookie('theme');
311
- * if (theme === 'dark') {
312
- * console.log('Dark mode enabled');
313
- * }
314
- * ```
315
- */
316
- useCookie: (name: string) => string | undefined;
52
+ declare function useNavigation(): {
53
+ state: "idle" | "loading";
54
+ navigate: typeof navigate;
317
55
  };
56
+ /**
57
+ * Hook to get only the navigation state.
58
+ * Returns 'idle' or 'loading'.
59
+ */
60
+ declare function useNavigationState(): 'idle' | 'loading';
61
+ /**
62
+ * Hook that returns the navigate function for programmatic navigation.
63
+ */
64
+ declare function useNavigate(): (url: string, options?: NavigateOptions) => Promise<void>;
65
+ /**
66
+ * Hook to check if navigation is in progress.
67
+ */
68
+ declare function useIsNavigating(): boolean;
318
69
 
319
- export { PageContextProvider, type PageProps, type RenderContext, createSSRHooks };
70
+ export { Link, type LinkProps, type NavigateOptions, NavigationProvider, navigate, useIsNavigating, useNavigate, useNavigation, useNavigationState };