@gnwebsoft/ui 4.0.0 → 4.0.2

package/dist/types/index.d.ts

@@ -1,820 +0,0 @@
-import { GridSortModel } from '@mui/x-data-grid';
-export { a as AsyncSelectMultiPayload, A as AsyncSelectPayload } from '../AsyncSelectPayload-B9-6l33R.js';
-export { E as EventOrValue, F as FormChangeEvent, c as GenericEventHandler, G as GenericSyntheticEvent, H as HtmlSelectElement, a as InputChangeEvent, I as InputElement, S as SelectChangeEvent, b as TransformInputHandler, T as TransformOutputHandler, g as createEventValueExtractor, f as extractEventValue, e as isFormChangeEvent, i as isInputChangeEvent, d as isSelectChangeEvent } from '../events-BcHVCLBz.js';
-import 'react';
-
-/**
- * Type definition for server validation errors structure.
- *
- * This type represents the format of validation errors returned from server APIs.
- * It supports multiple error formats for each field, allowing flexibility in how
- * validation errors are communicated and processed.
- *
- * @example
- * String error messages:
- * ```tsx
- * const errors: ValidationErrors = {
- *   email: 'Email is required',
- *   username: 'Username must be unique'
- * };
- * ```
- *
- * @example
- * Array of error messages:
- * ```tsx
- * const errors: ValidationErrors = {
- *   password: [
- *     'Password must be at least 8 characters',
- *     'Password must contain at least one number',
- *     'Password must contain at least one special character'
- *   ]
- * };
- * ```
- *
- * @example
- * Boolean flags for validation state:
- * ```tsx
- * const errors: ValidationErrors = {
- *   termsAccepted: false, // Field is invalid
- *   emailVerified: true   // Field has an error
- * };
- * ```
- *
- * @example
- * Structured error objects:
- * ```tsx
- * const errors: ValidationErrors = {
- *   dateOfBirth: {
- *     key: 'DATE_INVALID',
- *     message: 'Date of birth must be in the past'
- *   }
- * };
- * ```
- *
- * @public
- */
-interface ValidationErrors {
-    [field: string]: string | string[] | boolean | {
-        key: string;
-        message: string;
-    };
-}
-
-/**
- * Standardized API response structure for server communications.
- *
- * This type defines the common structure for API responses throughout the application,
- * providing a consistent interface for handling server responses, errors, and data.
- * It follows a standard error response format with optional success data.
- *
- * @template TModel - The type of data contained in the apiData field
- *
- * @example
- * Success response with data:
- * ```tsx
- * const userResponse: ApiResponse<User> = {
- *   status: 200,
- *   apiData: {
- *     id: 1,
- *     name: 'John Doe',
- *     email: 'john@example.com'
- *   }
- * };
- * ```
- *
- * @example
- * Error response with validation errors:
- * ```tsx
- * const errorResponse: ApiResponse<null> = {
- *   type: 'validation_error',
- *   title: 'Validation failed',
- *   status: 400,
- *   traceId: 'abc123',
- *   errors: {
- *     email: 'Email is required',
- *     password: ['Too short', 'Must contain numbers']
- *   },
- *   modelErrors: true
- * };
- * ```
- *
- * @public
- */
-interface ApiResponse<TModel> {
-    /**
-     * The type or category of the response/error
-     * @example "validation_error" | "server_error" | "success"
-     */
-    type?: string;
-    /**
-     * Human-readable title or summary of the response
-     * @example "Validation Failed" | "User Created Successfully"
-     */
-    title?: string;
-    /**
-     * HTTP status code of the response
-     * @example 200 | 400 | 500
-     */
-    status?: number;
-    /**
-     * Unique identifier for tracing/debugging the request
-     * @example "abc123-def456-ghi789"
-     */
-    traceId?: string;
-    /**
-     * Field-specific validation errors
-     */
-    errors?: ValidationErrors;
-    /**
-     * Flag indicating if there are model validation errors
-     */
-    modelErrors?: boolean;
-    /**
-     * The actual response data/payload
-     */
-    apiData?: TModel;
-}
-
-/**
- * Standard option item structure for select components.
- *
- * This type defines the expected structure for option items used in
- * select components throughout the application. It provides a consistent
- * interface with string labels and values.
- *
- * @example
- * Basic usage:
- * ```tsx
- * const categories: OptionItem[] = [
- *   { Label: 'Technology', Value: 'tech' },
- *   { Label: 'Finance', Value: 'finance' },
- *   { Label: 'Healthcare', Value: 'health' }
- * ];
- * ```
- *
- * @public
- */
-interface OptionItem {
-    /** Display text shown to the user */
-    Label: string;
-    /** Internal value used for form submission and identification */
-    Value: string;
-}
-/**
- * Payload structure for async multi-select operations.
- *
- * This type defines the data structure used when performing asynchronous
- * multi-select operations, typically for server-side filtering and loading
- * of options with pre-selected values.
- *
- * @example
- * Search with initial values:
- * ```tsx
- * const payload: AsyncMultiSelectPayload = {
- *   query: 'john',
- *   initialValues: ['user1', 'user2', 'user3']
- * };
- * ```
- *
- * @public
- */
-interface AsyncMultiSelectPayload {
-    /** Search query string for filtering options */
-    query: string | null;
-    /** Pre-selected values to be included in the selection */
-    initialValues?: string[] | number[] | null;
-}
-/**
- * Extended option item structure supporting both string and number values.
- *
- * This type extends the basic OptionItem to support numeric values,
- * providing flexibility for different data types while maintaining
- * the same label-value structure.
- *
- * @example
- * Mixed value types:
- * ```tsx
- * const options: OptionItem2[] = [
- *   { Label: 'First Option', Value: 1 },
- *   { Label: 'Second Option', Value: 'second' },
- *   { Label: 'Third Option', Value: 3 }
- * ];
- * ```
- *
- * @public
- */
-interface OptionItem2 {
-    /** Display text shown to the user */
-    Label: string;
-    /** Internal value that can be either a number or string */
-    Value: number | string;
-}
-
-interface OperationResponse {
-    id?: number;
-    rowsAffected: number;
-}
-
-/**
- * Type-safe API request and response utilities
- * @module types/api
- */
-/**
- * HTTP methods supported by the API
- */
-type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-/**
- * Valid JSON primitive types that can be sent in request bodies
- */
-type JsonPrimitive = string | number | boolean | null;
-/**
- * Valid JSON values (primitives, objects, arrays)
- */
-type JsonValue = JsonPrimitive | JsonObject | JsonArray;
-/**
- * JSON object with string keys and JSON values
- */
-interface JsonObject {
-    [key: string]: JsonValue;
-}
-/**
- * JSON array containing JSON values
- */
-type JsonArray = JsonValue[];
-/**
- * Type-safe request body - must be JSON-serializable
- */
-type RequestBody = JsonObject | JsonArray | FormData;
-/**
- * Standard HTTP headers with known header names
- */
-type HttpHeaders = Record<string, string>;
-/**
- * Options for making HTTP requests (based on fetch API)
- */
-interface RequestOptions {
-    /**
-     * HTTP method for the request
-     */
-    method: HttpMethod;
-    /**
-     * Request headers
-     */
-    headers?: HttpHeaders;
-    /**
-     * Request body (string for JSON, FormData for file uploads)
-     */
-    body?: string | FormData;
-    /**
-     * Request credentials mode
-     */
-    credentials?: RequestCredentials;
-    /**
-     * Request mode (cors, no-cors, same-origin)
-     */
-    mode?: RequestMode;
-    /**
-     * Cache mode for the request
-     */
-    cache?: RequestCache;
-    /**
-     * Redirect mode for the request
-     */
-    redirect?: RequestRedirect;
-    /**
-     * Referrer policy for the request
-     */
-    referrerPolicy?: ReferrerPolicy;
-    /**
-     * AbortSignal for request cancellation
-     */
-    signal?: AbortSignal;
-}
-/**
- * Configuration options for API calls
- */
-interface ApiCallOptions {
-    /**
-     * Custom headers to include in the request
-     */
-    headers?: HttpHeaders;
-    /**
-     * Whether to include authentication token
-     * @defaultValue true
-     */
-    includeAuth?: boolean;
-    /**
-     * AbortSignal for request cancellation
-     */
-    signal?: AbortSignal;
-    /**
-     * Custom base URL (overrides default)
-     */
-    baseUrl?: string;
-}
-/**
- * Options for fetch operations with any additional parameters
- */
-interface FetchOptions extends Omit<RequestInit, 'body' | 'headers'> {
-    /**
-     * Request headers
-     */
-    headers?: HttpHeaders;
-    /**
-     * Request body
-     */
-    body?: RequestBody;
-}
-/**
- * Type guard to check if a value is a valid JSON object
- */
-declare function isJsonObject(value: unknown): value is JsonObject;
-/**
- * Type guard to check if a value is a valid JSON array
- */
-declare function isJsonArray(value: unknown): value is JsonArray;
-/**
- * Type guard to check if a value is FormData
- */
-declare function isFormData(value: unknown): value is FormData;
-/**
- * Type guard to check if a value is a valid request body
- */
-declare function isRequestBody(value: unknown): value is RequestBody;
-
-/**
- * Utility types and type helpers for enhanced type safety
- *
- * @packageDocumentation
- */
-/**
- * Makes all properties of T required and non-nullable
- *
- * @example
- * ```typescript
- * interface User {
- *   id?: string;
- *   name?: string | null;
- * }
- *
- * type RequiredUser = DeepRequired<User>;
- * // { id: string; name: string }
- * ```
- *
- * @public
- */
-type DeepRequired<T> = {
-    [P in keyof T]-?: NonNullable<T[P]>;
-};
-/**
- * Makes all properties of T optional
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name: string;
- * }
- *
- * type PartialUser = DeepPartial<User>;
- * // { id?: string; name?: string }
- * ```
- *
- * @public
- */
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-/**
- * Makes all properties of T readonly deeply
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   profile: {
- *     name: string;
- *   };
- * }
- *
- * type ReadonlyUser = DeepReadonly<User>;
- * // { readonly id: string; readonly profile: { readonly name: string } }
- * ```
- *
- * @public
- */
-type DeepReadonly<T> = {
-    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
-};
-/**
- * Extracts keys from T that are not undefined
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name?: string;
- *   email: string | undefined;
- * }
- *
- * type RequiredKeys = RequiredKeys<User>;
- * // 'id'
- * ```
- *
- * @public
- */
-type RequiredKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? never : K;
-}[keyof T];
-/**
- * Extracts keys from T that can be undefined
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name?: string;
- *   email: string | undefined;
- * }
- *
- * type OptKeys = OptionalKeys<User>;
- * // 'name' | 'email'
- * ```
- *
- * @public
- */
-type OptionalKeys<T> = {
-    [K in keyof T]-?: undefined extends T[K] ? K : never;
-}[keyof T];
-/**
- * Makes specified keys K of type T required
- *
- * @example
- * ```typescript
- * interface User {
- *   id?: string;
- *   name?: string;
- *   email?: string;
- * }
- *
- * type UserWithId = RequireKeys<User, 'id' | 'email'>;
- * // { id: string; name?: string; email: string }
- * ```
- *
- * @public
- */
-type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-/**
- * Makes specified keys K of type T optional
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * type UserUpdate = PartialKeys<User, 'name' | 'email'>;
- * // { id: string; name?: string; email?: string }
- * ```
- *
- * @public
- */
-type PartialKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-/**
- * Excludes keys K from type T
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   password: string;
- *   email: string;
- * }
- *
- * type PublicUser = ExcludeKeys<User, 'password'>;
- * // { id: string; email: string }
- * ```
- *
- * @public
- */
-type ExcludeKeys<T, K extends keyof T> = Omit<T, K>;
-/**
- * Picks only keys K from type T
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   name: string;
- *   email: string;
- * }
- *
- * type UserCredentials = PickKeys<User, 'email'>;
- * // { email: string }
- * ```
- *
- * @public
- */
-type PickKeys<T, K extends keyof T> = Pick<T, K>;
-/**
- * Extracts the value type from an array type
- *
- * @example
- * ```typescript
- * type StringArray = string[];
- * type Item = ArrayElement<StringArray>;
- * // string
- * ```
- *
- * @public
- */
-type ArrayElement<T> = T extends readonly (infer E)[] ? E : never;
-/**
- * Extracts the return type of an async function
- *
- * @example
- * ```typescript
- * async function getUser(): Promise<User> {
- *   return { id: '1', name: 'John' };
- * }
- *
- * type User = AsyncReturnType<typeof getUser>;
- * // User
- * ```
- *
- * @public
- */
-type AsyncReturnType<T extends (...args: readonly unknown[]) => Promise<unknown>> = T extends (...args: readonly unknown[]) => Promise<infer R> ? R : never;
-/**
- * Makes a type nullable (adds null)
- *
- * @example
- * ```typescript
- * type Username = string;
- * type NullableUsername = Nullable<Username>;
- * // string | null
- * ```
- *
- * @public
- */
-type Nullable<T> = T | null;
-/**
- * Makes a type optional (adds undefined)
- *
- * @example
- * ```typescript
- * type Username = string;
- * type OptionalUsername = Maybe<Username>;
- * // string | undefined
- * ```
- *
- * @public
- */
-type Maybe<T> = T | undefined;
-/**
- * Makes a type nullish (adds null and undefined)
- *
- * @example
- * ```typescript
- * type Username = string;
- * type NullishUsername = Nullish<Username>;
- * // string | null | undefined
- * ```
- *
- * @public
- */
-type Nullish<T> = T | null | undefined;
-/**
- * Creates a union of all possible paths through an object type
- *
- * @example
- * ```typescript
- * interface User {
- *   profile: {
- *     name: string;
- *     address: {
- *       city: string;
- *     };
- *   };
- * }
- *
- * type Paths = ObjectPaths<User>;
- * // 'profile' | 'profile.name' | 'profile.address' | 'profile.address.city'
- * ```
- *
- * @public
- */
-type ObjectPaths<T> = {
-    [K in keyof T & string]: T[K] extends object ? K | `${K}.${ObjectPaths<T[K]>}` : K;
-}[keyof T & string];
-/**
- * Merges two types, with properties from B overriding those in A
- *
- * @example
- * ```typescript
- * interface A {
- *   id: number;
- *   name: string;
- * }
- *
- * interface B {
- *   id: string;
- *   email: string;
- * }
- *
- * type Merged = Merge<A, B>;
- * // { id: string; name: string; email: string }
- * ```
- *
- * @public
- */
-type Merge<A, B> = Omit<A, keyof B> & B;
-/**
- * Ensures a type is serializable (no functions, symbols, undefined)
- *
- * @example
- * ```typescript
- * interface Data {
- *   id: string;
- *   callback: () => void;
- *   value: number;
- * }
- *
- * type SerializableData = Serializable<Data>;
- * // { id: string; value: number }
- * ```
- *
- * @public
- */
-type Serializable<T> = {
-    [K in keyof T as T[K] extends (...args: readonly unknown[]) => unknown ? never : T[K] extends symbol ? never : T[K] extends undefined ? never : K]: T[K] extends object ? Serializable<T[K]> : T[K];
-};
-/**
- * Converts a union type to an intersection type
- *
- * @example
- * ```typescript
- * type Union = { a: string } | { b: number };
- * type Intersection = UnionToIntersection<Union>;
- * // { a: string } & { b: number }
- * ```
- *
- * @public
- */
-type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-/**
- * Gets all keys of T whose values extend V
- *
- * @example
- * ```typescript
- * interface User {
- *   id: string;
- *   age: number;
- *   name: string;
- *   active: boolean;
- * }
- *
- * type StringKeys = KeysOfType<User, string>;
- * // 'id' | 'name'
- * ```
- *
- * @public
- */
-type KeysOfType<T, V> = {
-    [K in keyof T]: T[K] extends V ? K : never;
-}[keyof T];
-/**
- * Ensures a value is exactly the type T (no wider types allowed)
- *
- * @example
- * ```typescript
- * const config: Exact<{ debug: boolean }> = {
- *   debug: true,
- *   // extra: 'value'  // ❌ Error: extra property not allowed
- * };
- * ```
- *
- * @public
- */
-type Exact<T, Shape = T> = T extends Shape ? Exclude<keyof T, keyof Shape> extends never ? T : never : never;
-/**
- * Creates a branded type for nominal typing
- * This prevents mixing values of the same primitive type
- *
- * @example
- * ```typescript
- * type UserId = Brand<string, 'UserId'>;
- * type ProductId = Brand<string, 'ProductId'>;
- *
- * const userId: UserId = '123' as UserId;
- * const productId: ProductId = '456' as ProductId;
- *
- * // ❌ Type error: UserId is not assignable to ProductId
- * const test: ProductId = userId;
- * ```
- *
- * @public
- */
-type Brand<T, TBrand extends string> = T & {
-    readonly __brand: TBrand;
-};
-/**
- * Helper to create a branded value
- *
- * @param value - The value to brand
- * @returns The value as a branded type
- *
- * @example
- * ```typescript
- * type UserId = Brand<string, 'UserId'>;
- * const id = brand<string, 'UserId'>('user-123');
- * // id has type UserId
- * ```
- *
- * @public
- */
-declare function brand<T, TBrand extends string>(value: T): Brand<T, TBrand>;
-/**
- * Removes branding from a branded type
- *
- * @example
- * ```typescript
- * type UserId = Brand<string, 'UserId'>;
- * type PlainId = Unbrand<UserId>;
- * // string
- * ```
- *
- * @public
- */
-type Unbrand<T> = T extends infer U & {
-    readonly __brand: string;
-} ? U : T;
-/**
- * Type-safe Object.keys that preserves key types
- *
- * @param obj - The object to get keys from
- * @returns Array of keys with proper type
- *
- * @example
- * ```typescript
- * const user = { id: '1', name: 'John' } as const;
- * const keys = typedKeys(user);
- * // keys has type: ('id' | 'name')[]
- * ```
- *
- * @public
- */
-declare function typedKeys<T extends Record<string, unknown>>(obj: T): Array<keyof T>;
-/**
- * Type-safe Object.entries that preserves key and value types
- *
- * @param obj - The object to get entries from
- * @returns Array of [key, value] tuples with proper types
- *
- * @example
- * ```typescript
- * const user = { id: '1', age: 30 } as const;
- * const entries = typedEntries(user);
- * // entries has type: ['id', '1'] | ['age', 30]
- * ```
- *
- * @public
- */
-declare function typedEntries<T extends Record<string, unknown>>(obj: T): Array<[keyof T, T[keyof T]]>;
-/**
- * Type-safe Object.values that preserves value types
- *
- * @param obj - The object to get values from
- * @returns Array of values with proper type
- *
- * @example
- * ```typescript
- * const user = { id: '1', age: 30 };
- * const values = typedValues(user);
- * // values has type: (string | number)[]
- * ```
- *
- * @public
- */
-declare function typedValues<T extends Record<string, unknown>>(obj: T): Array<T[keyof T]>;
-
-interface PostModel<TFilterModel> {
-    filterModel?: TFilterModel;
-    pageOffset: number;
-    pageSize: number;
-    sortField: string | null;
-    sortOrder: "asc" | "desc" | null | undefined;
-    sortModel?: GridSortModel;
-}
-interface ListResponse<TGridModel> {
-    Data: TGridModel[];
-    Total: number;
-}
-interface ValueLabel {
-    Value: number | string;
-    Label: string;
-}
-
-export { type ApiCallOptions, type ApiResponse, type ArrayElement, type AsyncMultiSelectPayload, type AsyncReturnType, type Brand, type DeepPartial, type DeepReadonly, type DeepRequired, type Exact, type ExcludeKeys, type FetchOptions, type HttpHeaders, type HttpMethod, type JsonArray, type JsonObject, type JsonPrimitive, type JsonValue, type KeysOfType, type ListResponse, type Maybe, type Merge, type Nullable, type Nullish, type ObjectPaths, type OperationResponse, type OptionItem, type OptionItem2, type OptionalKeys, type PartialKeys, type PickKeys, type PostModel, type RequestBody, type RequestOptions, type RequireKeys, type RequiredKeys, type Serializable, type Unbrand, type UnionToIntersection, type ValidationErrors, type ValueLabel, brand, isFormData, isJsonArray, isJsonObject, isRequestBody, typedEntries, typedKeys, typedValues };