@gravito/ion 3.1.0 → 4.0.0

package/dist/index.d.cts

@@ -1,5 +1,140 @@
 import { GravitoContext, GravitoVariables, GravitoOrbit, PlanetCore } from '@gravito/core';
 
+/**
+ * @fileoverview Type definitions for Inertia v2 protocol features.
+ *
+ * This module provides type definitions for advanced Inertia features:
+ * - Deferred Props: Delay loading of specific props to initial render
+ * - Merge Props: Replace, prepend, or deep-merge props during partial reloads
+ * - History Encryption: Control browser history handling
+ * - Error Bags: Organize form validation errors by category
+ *
+ * @module @gravito/ion/types
+ */
+/**
+ * Marks a prop for deferred loading.
+ *
+ * Deferred props are not executed during the initial page render, but are listed
+ * in the `deferredProps` field of the Inertia page object. The client fetches them
+ * separately after the initial render is complete.
+ *
+ * @template T - Type of the deferred value (inferred from factory return type).
+ *
+ * @example
+ * ```typescript
+ * inertia.render('Dashboard', {
+ *   user: { id: 1, name: 'Carl' },
+ *   // Heavy computation deferred to later
+ *   slowStats: InertiaService.defer(() => calculateStats()),
+ *   // Grouped deferred props
+ *   notifications: InertiaService.defer(
+ *     () => fetchNotifications(),
+ *     'notifications-group'
+ *   )
+ * });
+ * ```
+ */
+interface DeferredPropDefinition<T = unknown> {
+    readonly _type: 'deferred';
+    readonly factory: () => T | Promise<T>;
+    readonly group?: string;
+}
+/**
+ * Marks a prop for merging rather than replacement.
+ *
+ * Used during partial reloads (X-Inertia-Partial-Data) to control how props
+ * are combined with existing data on the client:
+ * - `merge`: Shallow merge at top level
+ * - `prepend`: Add items to the beginning of an array
+ * - `deepMerge`: Recursive merge for nested objects
+ *
+ * @template T - Type of the prop value.
+ *
+ * @example
+ * ```typescript
+ * inertia.render('Products/List', {
+ *   // Deep merge filters with existing data
+ *   filters: InertiaService.deepMerge({ status: 'active', price: 100 }),
+ *   // Prepend new items to the beginning of the list
+ *   items: InertiaService.prepend([newProduct]),
+ *   // Shallow merge config with existing data
+ *   config: InertiaService.merge({ sortBy: 'name' })
+ * });
+ * ```
+ */
+interface MergedPropDefinition<T = unknown> {
+    readonly _type: 'merge' | 'prepend' | 'deepMerge';
+    readonly value: T;
+    readonly matchOn?: string | string[];
+}
+/**
+ * Configuration for error bags in form validation.
+ *
+ * Organizes form validation errors into named categories, allowing multiple
+ * validation failure scenarios to coexist (e.g., 'default' and 'import-csv').
+ *
+ * @example
+ * ```typescript
+ * inertia.withErrors({
+ *   email: 'Email is required',
+ *   password: 'Must be at least 8 characters'
+ * }, 'login');  // Bag name: 'login'
+ *
+ * inertia.withErrors({
+ *   line_1: 'Invalid CSV at row 1',
+ *   line_2: 'Invalid CSV at row 2'
+ * }, 'import');  // Bag name: 'import'
+ * ```
+ */
+interface ErrorBagDefinition {
+    readonly bag: string;
+    readonly errors: Record<string, string | string[]>;
+}
+/**
+ * Inertia page object structure for the initial render response.
+ *
+ * This is the JSON structure sent to the frontend containing component metadata
+ * and all resolved props. Extended with Inertia v2 features.
+ *
+ * @template P - Shape of the props object.
+ */
+interface InertiaPageObject<P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Frontend component name (e.g., 'Pages/Dashboard') */
+    component: string;
+    /** Resolved and merged props for the component */
+    props: P;
+    /** Current URL without query string */
+    url: string;
+    /** Asset version (cache-busting identifier) */
+    version?: string;
+    /** Deferred prop groups and their factories (Inertia v2) */
+    deferredProps?: Record<string, string[]>;
+    /** Keys marked for merge/prepend/deepMerge (Inertia v2) */
+    mergeProps?: {
+        keys: string[];
+        mode: 'merge' | 'prepend' | 'deepMerge';
+    }[];
+    /** Whether to encrypt browser history (Inertia v2) */
+    encryptHistory?: boolean;
+    /** Whether to clear browser history (Inertia v2) */
+    clearHistory?: boolean;
+    /** Error bags organized by category (Inertia v2) */
+    errorBags?: Record<string, Record<string, string | string[]>>;
+}
+/**
+ * Inertia response metadata for partial reloads.
+ *
+ * Controls how the frontend should process the props update:
+ * - Handles reset scenarios (X-Inertia-Reset header)
+ * - Tracks which keys should be reset to undefined
+ */
+interface PartialReloadMetadata {
+    /** Keys to reset to undefined before merging new props */
+    resetKeys?: string[];
+    /** Merge strategy for the reload response */
+    mergeStrategy?: 'replace' | 'merge' | 'deepMerge';
+}
+
 /**
  * @fileoverview Inertia.js Service for Gravito.
  *
@@ -115,8 +250,49 @@ declare class InertiaService {
     private context;
     private config;
     private sharedProps;
+    private errorBags;
+    private encryptHistoryFlag;
+    private clearHistoryFlag;
     private readonly logLevel;
     private readonly onRenderCallback?;
+    /**
+     * Creates a deferred prop that will be loaded after the initial render.
+     *
+     * @param factory - Function that resolves to the prop value.
+     * @param group - Optional group name for organizing deferred props.
+     * @returns A deferred prop definition.
+     *
+     * @example
+     * ```typescript
+     * props: {
+     *   user: { id: 1 },
+     *   stats: InertiaService.defer(() => fetchStats())
+     * }
+     * ```
+     */
+    static defer<T = unknown>(factory: () => T | Promise<T>, group?: string): DeferredPropDefinition<T>;
+    /**
+     * Marks a prop to be merged (shallow) with existing data during partial reloads.
+     *
+     * @param value - The prop value to merge.
+     * @param matchOn - Optional key(s) to match on when merging arrays.
+     * @returns A merge prop definition.
+     */
+    static merge<T = unknown>(value: T, matchOn?: string | string[]): MergedPropDefinition<T>;
+    /**
+     * Marks a prop to prepend to an array during partial reloads.
+     *
+     * @param value - The prop value to prepend.
+     * @returns A prepend prop definition.
+     */
+    static prepend<T = unknown>(value: T): MergedPropDefinition<T>;
+    /**
+     * Marks a prop to be deep-merged with existing data during partial reloads.
+     *
+     * @param value - The prop value to deep merge.
+     * @returns A deep merge prop definition.
+     */
+    static deepMerge<T = unknown>(value: T): MergedPropDefinition<T>;
     /**
      * Initializes a new instance of the Inertia service.
      *
@@ -230,6 +406,77 @@ declare class InertiaService {
      * ```
      */
     getSharedProps(): Record<string, unknown>;
+    /**
+     * Instructs the Inertia client to navigate to a different URL.
+     *
+     * For Inertia AJAX requests, this returns a 409 Conflict with the `X-Inertia-Location` header.
+     * For regular page loads, this returns a 302 Found redirect.
+     *
+     * This is useful for server-side redirects triggered by authentication or authorization checks.
+     *
+     * @param url - The URL to redirect to.
+     * @returns A redirect response.
+     *
+     * @example
+     * ```typescript
+     * if (!ctx.get('user')) {
+     *   return inertia.location('/login');
+     * }
+     * ```
+     */
+    location(url: string): Response;
+    /**
+     * Controls whether the Inertia client should encrypt browser history.
+     *
+     * When enabled, history is not written to the browser's History API,
+     * preventing users from using the browser back button to return to previous pages.
+     *
+     * @param encrypt - Whether to encrypt history (defaults to true).
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * return await inertia.encryptHistory(true).render('SecurePage');
+     * ```
+     */
+    encryptHistory(encrypt?: boolean): this;
+    /**
+     * Clears the browser history after the page load.
+     *
+     * Useful for sensitive operations or multi-step wizards where you don't want
+     * users navigating back to previous states.
+     *
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * return await inertia.clearHistory().render('SuccessPage');
+     * ```
+     */
+    clearHistory(): this;
+    /**
+     * Registers form validation errors organized into named bags.
+     *
+     * Error bags allow multiple validation failure scenarios to coexist.
+     * For example, you might have 'default' errors and 'import' errors from different forms.
+     *
+     * @param errors - Validation errors, with field names as keys and error messages as values.
+     * @param bag - The error bag name (defaults to 'default').
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * inertia.withErrors({
+     *   email: 'Email is required',
+     *   password: 'Must be 8+ characters'
+     * }, 'login');
+     *
+     * inertia.withErrors({
+     *   line_1: 'Invalid CSV format'
+     * }, 'import');
+     * ```
+     */
+    withErrors(errors: Record<string, string | string[]>, bag?: string): this;
 }
 
 /**
@@ -347,6 +594,34 @@ interface InertiaHelper {
      * Thrown if the rendering lifecycle encounters a fatal error.
      */
     render<T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
+    /**
+     * Instructs the client to navigate to a different URL.
+     *
+     * @param url - The URL to navigate to.
+     * @returns A redirect response.
+     */
+    location(url: string): Response;
+    /**
+     * Encrypts the browser history to prevent navigation via back button.
+     *
+     * @param encrypt - Whether to enable history encryption (defaults to true).
+     * @returns The helper for method chaining.
+     */
+    encryptHistory(encrypt?: boolean): InertiaHelper;
+    /**
+     * Clears the browser history after page load.
+     *
+     * @returns The helper for method chaining.
+     */
+    clearHistory(): InertiaHelper;
+    /**
+     * Registers form validation errors organized by bag name.
+     *
+     * @param errors - Error map with field names as keys.
+     * @param bag - The error bag name (defaults to 'default').
+     * @returns The helper for method chaining.
+     */
+    withErrors(errors: Record<string, string | string[]>, bag?: string): InertiaHelper;
     /**
      * Direct access to the low-level `InertiaService` instance.
      *
@@ -394,6 +669,19 @@ interface OrbitIonOptions {
             body: string;
         }>;
     };
+    /**
+     * CSRF protection configuration.
+     *
+     * Automatically sets the XSRF-TOKEN cookie for CSRF protection.
+     *
+     * @defaultValue { enabled: true, cookieName: 'XSRF-TOKEN' }
+     */
+    csrf?: {
+        /** Whether CSRF protection is enabled. */
+        enabled?: boolean;
+        /** Name of the CSRF token cookie (commonly read by Axios). */
+        cookieName?: string;
+    };
 }
 /**
  * OrbitIon provides official Inertia.js integration for Gravito.
@@ -445,4 +733,4 @@ declare class OrbitIon implements GravitoOrbit {
     install(core: PlanetCore): void;
 }
 
-export { type InertiaConfig, InertiaConfigError, InertiaDataError, InertiaError, type InertiaHelper, InertiaService, InertiaTemplateError, OrbitIon, type OrbitIonOptions, type RenderMetrics, OrbitIon as default };
+export { type DeferredPropDefinition, type ErrorBagDefinition, type InertiaConfig, InertiaConfigError, InertiaDataError, InertiaError, type InertiaHelper, type InertiaPageObject, InertiaService, InertiaTemplateError, type MergedPropDefinition, OrbitIon, type OrbitIonOptions, type PartialReloadMetadata, type RenderMetrics, OrbitIon as default };

package/dist/index.d.ts

@@ -1,5 +1,140 @@
 import { GravitoContext, GravitoVariables, GravitoOrbit, PlanetCore } from '@gravito/core';
 
+/**
+ * @fileoverview Type definitions for Inertia v2 protocol features.
+ *
+ * This module provides type definitions for advanced Inertia features:
+ * - Deferred Props: Delay loading of specific props to initial render
+ * - Merge Props: Replace, prepend, or deep-merge props during partial reloads
+ * - History Encryption: Control browser history handling
+ * - Error Bags: Organize form validation errors by category
+ *
+ * @module @gravito/ion/types
+ */
+/**
+ * Marks a prop for deferred loading.
+ *
+ * Deferred props are not executed during the initial page render, but are listed
+ * in the `deferredProps` field of the Inertia page object. The client fetches them
+ * separately after the initial render is complete.
+ *
+ * @template T - Type of the deferred value (inferred from factory return type).
+ *
+ * @example
+ * ```typescript
+ * inertia.render('Dashboard', {
+ *   user: { id: 1, name: 'Carl' },
+ *   // Heavy computation deferred to later
+ *   slowStats: InertiaService.defer(() => calculateStats()),
+ *   // Grouped deferred props
+ *   notifications: InertiaService.defer(
+ *     () => fetchNotifications(),
+ *     'notifications-group'
+ *   )
+ * });
+ * ```
+ */
+interface DeferredPropDefinition<T = unknown> {
+    readonly _type: 'deferred';
+    readonly factory: () => T | Promise<T>;
+    readonly group?: string;
+}
+/**
+ * Marks a prop for merging rather than replacement.
+ *
+ * Used during partial reloads (X-Inertia-Partial-Data) to control how props
+ * are combined with existing data on the client:
+ * - `merge`: Shallow merge at top level
+ * - `prepend`: Add items to the beginning of an array
+ * - `deepMerge`: Recursive merge for nested objects
+ *
+ * @template T - Type of the prop value.
+ *
+ * @example
+ * ```typescript
+ * inertia.render('Products/List', {
+ *   // Deep merge filters with existing data
+ *   filters: InertiaService.deepMerge({ status: 'active', price: 100 }),
+ *   // Prepend new items to the beginning of the list
+ *   items: InertiaService.prepend([newProduct]),
+ *   // Shallow merge config with existing data
+ *   config: InertiaService.merge({ sortBy: 'name' })
+ * });
+ * ```
+ */
+interface MergedPropDefinition<T = unknown> {
+    readonly _type: 'merge' | 'prepend' | 'deepMerge';
+    readonly value: T;
+    readonly matchOn?: string | string[];
+}
+/**
+ * Configuration for error bags in form validation.
+ *
+ * Organizes form validation errors into named categories, allowing multiple
+ * validation failure scenarios to coexist (e.g., 'default' and 'import-csv').
+ *
+ * @example
+ * ```typescript
+ * inertia.withErrors({
+ *   email: 'Email is required',
+ *   password: 'Must be at least 8 characters'
+ * }, 'login');  // Bag name: 'login'
+ *
+ * inertia.withErrors({
+ *   line_1: 'Invalid CSV at row 1',
+ *   line_2: 'Invalid CSV at row 2'
+ * }, 'import');  // Bag name: 'import'
+ * ```
+ */
+interface ErrorBagDefinition {
+    readonly bag: string;
+    readonly errors: Record<string, string | string[]>;
+}
+/**
+ * Inertia page object structure for the initial render response.
+ *
+ * This is the JSON structure sent to the frontend containing component metadata
+ * and all resolved props. Extended with Inertia v2 features.
+ *
+ * @template P - Shape of the props object.
+ */
+interface InertiaPageObject<P extends Record<string, unknown> = Record<string, unknown>> {
+    /** Frontend component name (e.g., 'Pages/Dashboard') */
+    component: string;
+    /** Resolved and merged props for the component */
+    props: P;
+    /** Current URL without query string */
+    url: string;
+    /** Asset version (cache-busting identifier) */
+    version?: string;
+    /** Deferred prop groups and their factories (Inertia v2) */
+    deferredProps?: Record<string, string[]>;
+    /** Keys marked for merge/prepend/deepMerge (Inertia v2) */
+    mergeProps?: {
+        keys: string[];
+        mode: 'merge' | 'prepend' | 'deepMerge';
+    }[];
+    /** Whether to encrypt browser history (Inertia v2) */
+    encryptHistory?: boolean;
+    /** Whether to clear browser history (Inertia v2) */
+    clearHistory?: boolean;
+    /** Error bags organized by category (Inertia v2) */
+    errorBags?: Record<string, Record<string, string | string[]>>;
+}
+/**
+ * Inertia response metadata for partial reloads.
+ *
+ * Controls how the frontend should process the props update:
+ * - Handles reset scenarios (X-Inertia-Reset header)
+ * - Tracks which keys should be reset to undefined
+ */
+interface PartialReloadMetadata {
+    /** Keys to reset to undefined before merging new props */
+    resetKeys?: string[];
+    /** Merge strategy for the reload response */
+    mergeStrategy?: 'replace' | 'merge' | 'deepMerge';
+}
+
 /**
  * @fileoverview Inertia.js Service for Gravito.
  *
@@ -115,8 +250,49 @@ declare class InertiaService {
     private context;
     private config;
     private sharedProps;
+    private errorBags;
+    private encryptHistoryFlag;
+    private clearHistoryFlag;
     private readonly logLevel;
     private readonly onRenderCallback?;
+    /**
+     * Creates a deferred prop that will be loaded after the initial render.
+     *
+     * @param factory - Function that resolves to the prop value.
+     * @param group - Optional group name for organizing deferred props.
+     * @returns A deferred prop definition.
+     *
+     * @example
+     * ```typescript
+     * props: {
+     *   user: { id: 1 },
+     *   stats: InertiaService.defer(() => fetchStats())
+     * }
+     * ```
+     */
+    static defer<T = unknown>(factory: () => T | Promise<T>, group?: string): DeferredPropDefinition<T>;
+    /**
+     * Marks a prop to be merged (shallow) with existing data during partial reloads.
+     *
+     * @param value - The prop value to merge.
+     * @param matchOn - Optional key(s) to match on when merging arrays.
+     * @returns A merge prop definition.
+     */
+    static merge<T = unknown>(value: T, matchOn?: string | string[]): MergedPropDefinition<T>;
+    /**
+     * Marks a prop to prepend to an array during partial reloads.
+     *
+     * @param value - The prop value to prepend.
+     * @returns A prepend prop definition.
+     */
+    static prepend<T = unknown>(value: T): MergedPropDefinition<T>;
+    /**
+     * Marks a prop to be deep-merged with existing data during partial reloads.
+     *
+     * @param value - The prop value to deep merge.
+     * @returns A deep merge prop definition.
+     */
+    static deepMerge<T = unknown>(value: T): MergedPropDefinition<T>;
     /**
      * Initializes a new instance of the Inertia service.
      *
@@ -230,6 +406,77 @@ declare class InertiaService {
      * ```
      */
     getSharedProps(): Record<string, unknown>;
+    /**
+     * Instructs the Inertia client to navigate to a different URL.
+     *
+     * For Inertia AJAX requests, this returns a 409 Conflict with the `X-Inertia-Location` header.
+     * For regular page loads, this returns a 302 Found redirect.
+     *
+     * This is useful for server-side redirects triggered by authentication or authorization checks.
+     *
+     * @param url - The URL to redirect to.
+     * @returns A redirect response.
+     *
+     * @example
+     * ```typescript
+     * if (!ctx.get('user')) {
+     *   return inertia.location('/login');
+     * }
+     * ```
+     */
+    location(url: string): Response;
+    /**
+     * Controls whether the Inertia client should encrypt browser history.
+     *
+     * When enabled, history is not written to the browser's History API,
+     * preventing users from using the browser back button to return to previous pages.
+     *
+     * @param encrypt - Whether to encrypt history (defaults to true).
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * return await inertia.encryptHistory(true).render('SecurePage');
+     * ```
+     */
+    encryptHistory(encrypt?: boolean): this;
+    /**
+     * Clears the browser history after the page load.
+     *
+     * Useful for sensitive operations or multi-step wizards where you don't want
+     * users navigating back to previous states.
+     *
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * return await inertia.clearHistory().render('SuccessPage');
+     * ```
+     */
+    clearHistory(): this;
+    /**
+     * Registers form validation errors organized into named bags.
+     *
+     * Error bags allow multiple validation failure scenarios to coexist.
+     * For example, you might have 'default' errors and 'import' errors from different forms.
+     *
+     * @param errors - Validation errors, with field names as keys and error messages as values.
+     * @param bag - The error bag name (defaults to 'default').
+     * @returns The service instance for method chaining.
+     *
+     * @example
+     * ```typescript
+     * inertia.withErrors({
+     *   email: 'Email is required',
+     *   password: 'Must be 8+ characters'
+     * }, 'login');
+     *
+     * inertia.withErrors({
+     *   line_1: 'Invalid CSV format'
+     * }, 'import');
+     * ```
+     */
+    withErrors(errors: Record<string, string | string[]>, bag?: string): this;
 }
 
 /**
@@ -347,6 +594,34 @@ interface InertiaHelper {
      * Thrown if the rendering lifecycle encounters a fatal error.
      */
     render<T extends Record<string, unknown> = Record<string, unknown>>(component: string, props?: T, rootVars?: Record<string, unknown>, status?: number): Promise<Response>;
+    /**
+     * Instructs the client to navigate to a different URL.
+     *
+     * @param url - The URL to navigate to.
+     * @returns A redirect response.
+     */
+    location(url: string): Response;
+    /**
+     * Encrypts the browser history to prevent navigation via back button.
+     *
+     * @param encrypt - Whether to enable history encryption (defaults to true).
+     * @returns The helper for method chaining.
+     */
+    encryptHistory(encrypt?: boolean): InertiaHelper;
+    /**
+     * Clears the browser history after page load.
+     *
+     * @returns The helper for method chaining.
+     */
+    clearHistory(): InertiaHelper;
+    /**
+     * Registers form validation errors organized by bag name.
+     *
+     * @param errors - Error map with field names as keys.
+     * @param bag - The error bag name (defaults to 'default').
+     * @returns The helper for method chaining.
+     */
+    withErrors(errors: Record<string, string | string[]>, bag?: string): InertiaHelper;
     /**
      * Direct access to the low-level `InertiaService` instance.
      *
@@ -394,6 +669,19 @@ interface OrbitIonOptions {
             body: string;
         }>;
     };
+    /**
+     * CSRF protection configuration.
+     *
+     * Automatically sets the XSRF-TOKEN cookie for CSRF protection.
+     *
+     * @defaultValue { enabled: true, cookieName: 'XSRF-TOKEN' }
+     */
+    csrf?: {
+        /** Whether CSRF protection is enabled. */
+        enabled?: boolean;
+        /** Name of the CSRF token cookie (commonly read by Axios). */
+        cookieName?: string;
+    };
 }
 /**
  * OrbitIon provides official Inertia.js integration for Gravito.
@@ -445,4 +733,4 @@ declare class OrbitIon implements GravitoOrbit {
     install(core: PlanetCore): void;
 }
 
-export { type InertiaConfig, InertiaConfigError, InertiaDataError, InertiaError, type InertiaHelper, InertiaService, InertiaTemplateError, OrbitIon, type OrbitIonOptions, type RenderMetrics, OrbitIon as default };
+export { type DeferredPropDefinition, type ErrorBagDefinition, type InertiaConfig, InertiaConfigError, InertiaDataError, InertiaError, type InertiaHelper, type InertiaPageObject, InertiaService, InertiaTemplateError, type MergedPropDefinition, OrbitIon, type OrbitIonOptions, type PartialReloadMetadata, type RenderMetrics, OrbitIon as default };