@gzl10/nexus-sdk 0.12.7 → 0.13.0

package/dist/field-CngHXora.d.ts

@@ -0,0 +1,375 @@
+/**
+ * Localization (i18n) types and helpers
+ */
+/**
+ * Localized string supporting multiple languages.
+ * Can be a simple string (single language) or object with language codes.
+ *
+ * @example
+ * // Simple string (backward compatible)
+ * label: 'Users'
+ *
+ * // Multi-language object
+ * label: { en: 'Users', es: 'Usuarios' }
+ */
+type LocalizedString = string | Record<string, string>;
+/**
+ * Auth provider information for dynamic login buttons.
+ * Plugins register this info so the UI can render buttons without knowing provider details.
+ *
+ * @example
+ * ```typescript
+ * ctx.registerService('google.provider', {
+ *   getInfo: () => ({
+ *     code: 'GOOGLE_AUTH',
+ *     provider: 'google',
+ *     icon: 'mdi:google',
+ *     label: { en: 'Sign in with Google', es: 'Iniciar sesión con Google' },
+ *     color: '#4285F4',
+ *     authorizeEndpoint: '/api/v1/google/authorize'
+ *   })
+ * })
+ * ```
+ */
+interface AuthProviderInfo {
+    /** Unique code for this auth method (e.g., 'GOOGLE_AUTH') */
+    code: string;
+    /** Provider identifier (e.g., 'google', 'github') */
+    provider: string;
+    /** Iconify icon name (e.g., 'mdi:google') */
+    icon: string;
+    /** Button label in multiple languages */
+    label: LocalizedString;
+    /** Brand color for the button (hex) */
+    color: string;
+    /** Endpoint to start OAuth flow */
+    authorizeEndpoint: string;
+}
+/**
+ * Service interface for auth providers.
+ * Plugins implement this to expose their button info.
+ */
+interface AuthProviderService {
+    /** Returns the provider info for UI rendering (null if disabled) */
+    getInfo(): Promise<AuthProviderInfo | null>;
+}
+/**
+ * Resolves a LocalizedString to the appropriate language.
+ * Falls back to 'en', then first available, then empty string.
+ *
+ * @param value - The localized string to resolve
+ * @param locale - The target locale (e.g., 'en', 'es')
+ * @returns The resolved string for the given locale
+ */
+declare function resolveLocalized(value: LocalizedString | undefined, locale: string): string;
+/**
+ * Gets the appropriate label based on count (pluralization).
+ * Returns labelPlural for count !== 1, label otherwise.
+ *
+ * @param label - Singular form
+ * @param labelPlural - Plural form (optional, defaults to label)
+ * @param count - The count to determine singular/plural
+ * @param locale - The target locale
+ * @returns The resolved string for the given count and locale
+ */
+declare function getCountLabel(label: LocalizedString | undefined, labelPlural: LocalizedString | undefined, count: number, locale: string): string;
+
+/**
+ * Field definition types for entity schemas
+ */
+
+/**
+ * Database column types for Knex migrations.
+ *
+ * Maps to SQL column types:
+ * - `string` → VARCHAR(size) - Use with `db.size` for length
+ * - `text` → TEXT - Unlimited length text
+ * - `integer` → INTEGER - Whole numbers
+ * - `decimal` → DECIMAL(p,s) - Use with `db.precision` for scale
+ * - `boolean` → BOOLEAN - True/false values
+ * - `date` → DATE - Date without time
+ * - `datetime` → DATETIME/TIMESTAMP - Date with time
+ * - `json` → JSON/JSONB - Structured data (use for LocalizedString)
+ * - `uuid` → UUID - Universally unique identifier
+ * - `array` → Virtual only - No database column generated
+ */
+type DbType = 'string' | 'text' | 'integer' | 'decimal' | 'boolean' | 'date' | 'datetime' | 'json' | 'uuid' | 'array';
+/**
+ * UI input types that determine which form component renders.
+ *
+ * **Text inputs:**
+ * - `text` → NInput - Single line text
+ * - `email` → NInput with email validation
+ * - `password` → NInput with password mask
+ * - `url` → NInput with URL validation
+ * - `tel` → NInput for phone numbers
+ *
+ * **Numeric inputs:**
+ * - `number` → NInputNumber - Integer values
+ * - `decimal` → NInputNumber with decimal precision
+ *
+ * **Rich text:**
+ * - `textarea` → NInput multiline
+ * - `markdown` → MarkdownInput with preview
+ * - `json` → JsonInput with syntax highlighting
+ *
+ * **Selection:**
+ * - `select` → NSelect - Single selection dropdown
+ * - `multiselect` → NSelect with multiple - Multiple selection
+ * - `autocomplete` → NAutoComplete - Text input with suggestions
+ * - `transfer` → NTransfer - Dual list selection
+ * - `tags` → NSelect with tags - Free-form tags input
+ *
+ * **Boolean:**
+ * - `checkbox` → NCheckbox
+ * - `switch` → NSwitch - Toggle switch
+ *
+ * **Date/Time:**
+ * - `date` → NDatePicker - Date only
+ * - `datetime` → NDatePicker with time
+ *
+ * **Files:**
+ * - `file` → FileInput - Single file upload
+ * - `multifile` → MultiFileInput - Multiple files
+ * - `image` → ImageInput - Single image with preview
+ * - `multiimage` → MultiImageInput - Image gallery
+ *
+ * **Other:**
+ * - `icon` → IconPicker - Icon selection from library
+ */
+type InputType = 'text' | 'email' | 'password' | 'url' | 'tel' | 'number' | 'decimal' | 'rate' | 'textarea' | 'markdown' | 'json' | 'select' | 'multiselect' | 'autocomplete' | 'transfer' | 'tags' | 'radio' | 'checkbox' | 'switch' | 'date' | 'datetime' | 'file' | 'multifile' | 'image' | 'multiimage' | 'icon' | 'color' | 'otp' | 'qr' | 'cron' | 'uuid' | 'slug' | 'tree' | 'time' | 'range' | 'hidden' | 'code';
+/**
+ * Database column configuration for Knex migrations.
+ */
+interface FieldDbConfig {
+    /** Column type for the database */
+    type: DbType;
+    /** If true, no database column is created (for computed/virtual fields) */
+    virtual?: boolean;
+    /** String length for VARCHAR columns */
+    size?: number;
+    /** Precision and scale for DECIMAL: [precision, scale] e.g., [10, 2] */
+    precision?: [number, number];
+    /** Allow NULL values. Inferred from `required` if not specified */
+    nullable?: boolean;
+    /** Create unique constraint on this column */
+    unique?: boolean;
+    /** Static default value for the column */
+    default?: unknown;
+    /** Database function for default value: 'now' for timestamps, 'uuid' for auto-generated UUIDs */
+    defaultFn?: 'now' | 'uuid';
+    /** Create index on this column for faster queries */
+    index?: boolean;
+    /** Auto-increment for integer primary keys */
+    autoIncrement?: boolean;
+    /** Mark as primary key */
+    primary?: boolean;
+    /**
+     * ID generation strategy for primary key fields.
+     * Used by BaseEntityService to generate IDs at runtime.
+     * - 'ulid': Time-sortable, 26 chars (default)
+     * - 'uuid': Standard UUID v4, 36 chars
+     * - 'nanoid': URL-safe, 21 chars
+     * - 'cuid2': Collision-resistant, 24 chars
+     * - 'auto': Database auto-increment
+     * - 'custom': User-provided ID
+     * - 'pattern': Sequential with pattern (e.g., TP-2025-000001)
+     */
+    idType?: 'ulid' | 'uuid' | 'nanoid' | 'cuid2' | 'auto' | 'custom' | 'pattern';
+    /**
+     * Pattern configuration for 'pattern' ID type.
+     * Required when idType is 'pattern'.
+     */
+    patternConfig?: {
+        /** Pattern template with tokens: {prefix}, {year}, {seq:N}, etc. */
+        pattern: string;
+        /** Static prefix for {prefix} token */
+        prefix?: string;
+        /** Static suffix for {suffix} token */
+        suffix?: string;
+        /** When to reset sequence: 'never' | 'year' | 'month' | 'day' */
+        resetOn?: 'never' | 'year' | 'month' | 'day';
+        /** Starting number for sequence (default: 1) */
+        startAt?: number;
+    };
+}
+/**
+ * Foreign key relationship configuration.
+ */
+interface FieldRelation {
+    /** Target table name */
+    table: string;
+    /** Target column name (default: 'id') */
+    column?: string;
+    /** Action when referenced row is deleted */
+    onDelete?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+    /** Action when referenced row's key is updated */
+    onUpdate?: 'CASCADE' | 'RESTRICT' | 'SET NULL' | 'NO ACTION';
+}
+/**
+ * Validation rules for runtime and form validation.
+ */
+interface FieldValidationConfig {
+    /** Minimum value (numbers) or minimum length (strings) */
+    min?: number;
+    /** Maximum value (numbers) or maximum length (strings) */
+    max?: number;
+    /** Regular expression pattern for validation */
+    pattern?: string;
+    /** Allowed values (creates enum constraint) */
+    enum?: string[];
+    /** Format hint for OpenAPI schema (e.g., 'email', 'uri', 'date-time') */
+    format?: 'email' | 'uri' | 'date' | 'date-time' | 'uuid' | string;
+}
+/**
+ * Configuration for select, multiselect, and dropdown fields.
+ */
+interface FieldOptions {
+    /** API endpoint for dynamic options (GET request) */
+    endpoint?: string;
+    /** Field to use as option value (default: 'id') */
+    valueField?: string;
+    /** Field to use as option label (default: 'name') */
+    labelField?: string;
+    /** Static list of options */
+    static?: Array<{
+        value: string;
+        label: LocalizedString;
+        icon?: string;
+    }>;
+    /** Allow creating new options on-the-fly (renders combobox) */
+    allowCreate?: boolean;
+}
+/**
+ * Storage configuration for file and image upload fields.
+ */
+interface FieldStorageConfig {
+    /** Accepted MIME types (e.g., 'image/*', 'application/pdf') */
+    accept?: string;
+    /** Maximum file size in bytes (default: 10MB = 10485760) */
+    maxSize?: number;
+    /** Maximum number of files for array types (multifile, multiimage) */
+    maxFiles?: number;
+    /** Folder/prefix in storage bucket (e.g., 'avatars', 'documents/contracts') */
+    folder?: string;
+    /** Thumbnail sizes to auto-generate for images */
+    thumbnails?: Array<{
+        width: number;
+        height: number;
+    }>;
+    /** Enable SHA256 hash deduplication */
+    dedupe?: boolean;
+    /** If true, files are publicly accessible without authentication */
+    isPublic?: boolean;
+}
+/**
+ * Field metadata for UI behavior and data operations.
+ */
+interface FieldMeta {
+    /** Enable sorting by this field in table columns */
+    sortable?: boolean;
+    /** Include this field in search/filter operations */
+    searchable?: boolean;
+    /** Include this field in CSV/Excel exports */
+    exportable?: boolean;
+    /** Mark as audit field (auto-populated with user ID on create/update) */
+    auditField?: 'created_by' | 'updated_by';
+    /** Show in display components (Table, List, Masonry). Default: true */
+    showInDisplay?: boolean;
+    /** Show in forms. Use 'create'/'edit' for conditional display. Default: true */
+    showInForm?: boolean | 'create' | 'edit';
+}
+/**
+ * Serializable field condition for dynamic visibility/required/disabled.
+ * Evaluated in the frontend based on current form data.
+ */
+interface FieldCondition {
+    /** Field name to evaluate */
+    field: string;
+    /** Equal (value === $eq) */
+    $eq?: unknown;
+    /** Not equal (value !== $ne) */
+    $ne?: unknown;
+    /** In array (array.includes(value)) */
+    $in?: unknown[];
+    /** Not in array (!array.includes(value)) */
+    $nin?: unknown[];
+    /** Is null/undefined/empty (true = is empty, false = is not empty) */
+    $isnull?: boolean;
+}
+/**
+ * Conditional boolean - can be static, function, or serializable condition.
+ */
+type ConditionalBoolean = boolean | FieldCondition | ((record: Record<string, unknown>) => boolean);
+/**
+ * Complete field definition for entity fields.
+ *
+ * This is the core building block for defining entity schemas in Nexus.
+ * Contains all the information needed for:
+ * - **UI**: Form inputs, table columns, list displays
+ * - **Database**: Knex migrations, column types, constraints
+ * - **Validation**: Zod schemas, runtime validation rules
+ */
+interface FieldDefinition {
+    /** Human-readable label displayed in forms, tables, and lists */
+    label: LocalizedString;
+    /** Input type that determines which UI component renders this field */
+    input: InputType;
+    /** Placeholder text shown in empty input fields */
+    placeholder?: LocalizedString;
+    /** Help text displayed below the input field */
+    hint?: LocalizedString;
+    /** Controls field visibility in the UI */
+    hidden?: ConditionalBoolean;
+    /** Controls whether the field is read-only in forms */
+    disabled?: ConditionalBoolean;
+    /** Marks the field as required for form validation */
+    required?: ConditionalBoolean;
+    /** Default value used when creating new records */
+    defaultValue?: unknown;
+    /** Database column configuration for Knex migrations */
+    db?: FieldDbConfig;
+    /** Foreign key relationship configuration */
+    relation?: FieldRelation;
+    /** Validation rules applied during form submission and API requests */
+    validation?: FieldValidationConfig;
+    /** Configuration for select inputs and relationship dropdowns */
+    options?: FieldOptions;
+    /** Storage configuration for file and image inputs */
+    storage?: FieldStorageConfig;
+    /** Additional metadata for categorization and UI organization */
+    meta?: FieldMeta;
+    /** Additional props passed directly to the form input component */
+    inputProps?: Record<string, unknown>;
+    /** Additional props passed to display components (table columns, list items) */
+    displayProps?: Record<string, unknown>;
+}
+/**
+ * Composite table index definition for database migrations.
+ */
+interface EntityIndex {
+    /** Column names to include in the composite index */
+    columns: string[];
+    /** Create unique constraint on the column combination */
+    unique?: boolean;
+}
+/**
+ * Creates options configuration for a reference field pointing to a reference entity.
+ * When entity is omitted, the endpoint is `/{module}` (entity mounted at module root).
+ */
+declare function refOptions(module: string, entityOrLabel?: string, labelField?: string): {
+    endpoint: string;
+    valueField: string;
+    labelField: string;
+};
+/**
+ * Creates a field definition that references a master table.
+ */
+declare function refMaster(master: string, options?: {
+    default?: string;
+    label?: LocalizedString;
+    required?: boolean;
+    input?: 'select' | 'autocomplete';
+}): FieldDefinition;
+
+export { type AuthProviderInfo as A, type ConditionalBoolean as C, type DbType as D, type EntityIndex as E, type FieldCondition as F, type InputType as I, type LocalizedString as L, type FieldMeta as a, type AuthProviderService as b, type FieldDbConfig as c, type FieldRelation as d, type FieldValidationConfig as e, type FieldOptions as f, getCountLabel as g, type FieldStorageConfig as h, type FieldDefinition as i, refOptions as j, refMaster as k, resolveLocalized as r };