@lumeweb/portal-framework-ui 0.0.1 → 0.1.1

package/dist/esm/components/form/types.d.ts

@@ -0,0 +1,521 @@
+import { ActionItemConfig, ActionListLayout } from "../actions/types.js";
+import { ComponentSize } from "../sizing/index.js";
+import { FormFieldType } from "./fields/types.js";
+import { EnvironmentSyncCallback, ForceRerenderCallback } from "../shared/types/form.js";
+import { UnifiedEnvironment } from "../shared/types/environment.js";
+import { AllowStepNavigation } from "../shared/types/navigation.js";
+import { DialogConfig } from "../dialog/Dialog.types.js";
+import { AutoSaveIndicatorElements, AutoSaveProps, BaseKey, BaseRecord, FormAction, HttpError, OpenNotificationParams } from "@refinedev/core";
+import { ComponentType, ReactNode } from "react";
+import { UseFormProps } from "@refinedev/react-hook-form";
+import { Path } from "react-hook-form";
+import { z } from "zod";
+
+//#region src/components/form/types.d.ts
+/**
+ * Enum defining the adapter types for form handling
+ */
+declare enum AdapterType {
+  /** Refine adapter */
+  REFINE = "refine",
+  /** React Hook Form adapter */
+  RHF = "rhf"
+}
+/**
+ * Callback function type for generating action buttons based on environment
+ */
+type ActionButtonsCallback<TRequest extends BaseRecord = any> = (props: {
+  /** The environment context for the form */environment?: UnifiedEnvironment;
+}) => ActionItemConfig[] | undefined | false;
+/**
+ * Enum defining the order in which grouped and ungrouped fields are rendered
+ */
+declare enum GroupOrder {
+  /** Render groups first, then ungrouped fields */
+  GROUPS_FIRST = "groups-first",
+  /** Render ungrouped fields first, then groups */
+  UNGROUPED_FIRST = "ungrouped-first"
+}
+/**
+ * Enum defining the layout types for forms
+ */
+declare enum LayoutType {
+  /** Grid layout */
+  GRID = "grid",
+  /** Horizontal layout */
+  HORIZONTAL = "horizontal",
+  /** Vertical layout */
+  VERTICAL = "vertical"
+}
+/**
+ * Type for HTML autocomplete attribute values
+ */
+type AutocompleteToken = "current-password" | "email" | "family-name" | "given-name" | "new-password" | "off" | "on" | "one-time-code" | "username";
+/**
+ * Configuration type for form autosave functionality
+ */
+type FormAutosaveConfig<T> = AutoSaveProps<T>["autoSave"];
+/**
+ * Configuration interface for a form
+ */
+interface FormConfig<TRequest extends BaseRecord = any, TResponse extends BaseRecord = any> {
+  /** The form action type (create, edit, etc.) */
+  action?: FormAction;
+  /**
+   * Action buttons configuration for the form footer
+   */
+  actionButtons?: ActionItemConfig[] | false | ActionButtonsCallback;
+  /**
+   * Layout for action buttons in footer
+   * @default "horizontal"
+   */
+  actionButtonsLayout?: ActionListLayout;
+  /** The adapter type to use for form handling */
+  adapter?: AdapterType;
+  /** Whether to enable autosave functionality */
+  autoSave?: boolean | FormAutosaveConfig<TRequest>;
+  /** Custom elements for different autosave states */
+  autoSaveStates?: AutoSaveIndicatorElements;
+  /** Whether to close the dialog after successful submission */
+  closeOnSubmit?: boolean;
+  /** Default values for the form fields */
+  defaultValues?: TRequest;
+  /** Alias for refineCoreProps.errorNotification */
+  errorNotification?: ((error: any) => OpenNotificationParams) | OpenNotificationParams;
+  /** Array of form field configurations */
+  fields: FormFieldConfig<TRequest>[];
+  /**
+   * Custom footer content or configuration
+   * Can be:
+   * - React node
+   * - Array of action button configs
+   * - Function that receives form methods and returns React node
+   */
+  footer?: ((methods: any, closeDialog: () => void, currentDialog?: DialogConfig<TRequest, TResponse>) => ActionItemConfig[] | ReactNode) | ActionItemConfig[] | false | ReactNode;
+  /**
+   * Class name for the footer wrapper
+   * Set to false to disable default padding/border styles
+   * @default "pt-4 mt-4 border-t"
+   */
+  footerClassName?: false | string;
+  /** CSS class name for the form container */
+  formClassName?: string;
+  /**
+   * Unique identifier for the form configuration.
+   * This is separate from the record ID and is used to identify the form itself.
+   */
+  formId?: string;
+  /**
+   * Controls whether grouped or ungrouped fields are rendered first
+   * @default GroupOrder.UNGROUPED_FIRST
+   */
+  groupOrder?: GroupOrder;
+  /**
+   * Groups configuration for organizing fields
+   */
+  groups?: FormGroupType[];
+  /**
+   * Custom header content to render at the top of the form
+   * Can be:
+   * - React node for static content
+   * - Function that receives environment context and returns React node
+   * - false to hide header
+   */
+  header?: ((environment: any) => ReactNode) | false | ReactNode;
+  /** The ID of the record being edited (for edit forms) */
+  id?: BaseKey;
+  /** The layout type for the form */
+  layout?: LayoutType;
+  /** Error handler for form submission */
+  onError?: (error: Error) => void;
+  /** Submit handler for the form */
+  onSubmit?: (values: TRequest) => Promise<TResponse> | void;
+  /** Alias for refineCoreProps.onMutationSuccess */
+  onSuccess?: (response: TResponse, values: TRequest) => void;
+  /** Whether to use refine framework */
+  refine?: boolean;
+  /** Refine-specific form properties */
+  refineCoreProps?: UseFormProps<TRequest, HttpError, TRequest>["refineCoreProps"] & {
+    /** Error notification configuration */errorNotification?: (error: any) => OpenNotificationParams; /** Metadata for the form */
+    meta?: Record<string, unknown>; /** Success notification configuration */
+    successNotification?: (data: any, values: any) => OpenNotificationParams;
+  };
+  /** The resource name for the form */
+  resource?: string;
+  /** Label for the submit button */
+  submitLabel?: ((values: Partial<TRequest>) => string) | string;
+  /** Alias for refineCoreProps.successNotification */
+  successNotification?: (data: any, values: any) => OpenNotificationParams;
+  /** Zod schema for form validation */
+  validationSchema?: z.ZodSchema<TRequest>;
+  /**
+   * Optional callback for receiving a force rerender method.
+   * The framework will call this callback with a method that can be stored
+   * locally and used to force a component rerender when something outside
+   * the render loop needs to trigger a rerender.
+   */
+  forceRerender?: ForceRerenderCallback;
+  /**
+   * Optional callback for receiving an environment sync method.
+   * The framework will call this callback with a method that can be stored
+   * locally and used to sync environment changes when something outside
+   * the normal flow updates the environment.
+   */
+  environmentSync?: EnvironmentSyncCallback;
+  /**
+   * Callback when navigation starts
+   */
+  onNavigationStart?: (fromStep: number, toStep: number, type: 'goTo' | 'jumpTo' | 'next' | 'previous' | 'retry') => void;
+  /**
+   * Callback when navigation ends successfully
+   */
+  onNavigationEnd?: (fromStep: number, toStep: number, type: 'goTo' | 'jumpTo' | 'next' | 'previous' | 'retry') => void;
+  /**
+   * Callback when navigation fails
+   */
+  onNavigationError?: (fromStep: number, toStep: number, type: 'goTo' | 'jumpTo' | 'next' | 'previous' | 'retry', error: any) => void;
+}
+/**
+ * Configuration interface for a form field
+ */
+interface FormFieldConfig<TRequest extends BaseRecord = any> {
+  /**
+   * The HTML autocomplete attribute value for the field.
+   * If provided, it will be passed to the underlying input component.
+   */
+  autocomplete?: AutocompleteToken;
+  /** CSS class name for the field container */
+  className?: string;
+  /** Custom component to render for this field */
+  component?: ComponentType<any>;
+  /**
+   * Optimize performance by specifying which field names (paths using dot notation)
+   * influence the 'show' function or 'requires' conditions for this field.
+   * If omitted, conditional checks might rely on less performant full form watches.
+   */
+  dependencies?: string[];
+  /** Description text for the field */
+  description?: string;
+  /**
+   * Group ID this field belongs to
+   */
+  group?: string;
+  /** CSS class name for the input element */
+  inputClassName?: string;
+  /**
+   * Additional props to pass to the underlying input element
+   */
+  inputProps?: Record<string, any>;
+  /**
+   * Class name applied to the FormItem wrapper component
+   */
+  itemClassName?: string;
+  /** Label text for the field */
+  label?: string;
+  /** CSS class name for the label element */
+  labelClassName?: string;
+  /** Field name/path (using dot notation for nested fields) */
+  name: Path<TRequest> | (string & {});
+  /** Options for select-type fields */
+  options?: FormFieldOption[];
+  /** Placeholder text for the field */
+  placeholder?: string;
+  /** Whether the field is required */
+  required?: boolean;
+  /**
+   * Declaratively define dependencies for field visibility.
+   * The field will only be shown if *all* conditions in this object are met.
+   * Keys are paths to other fields (using dot notation for nested fields).
+   * Values are the required value for that field, or a function predicate.
+   * Example: { 'user.role': 'admin', 'settings.enabled': true, 'profile.age': (age) => age >= 18 }
+   * If used with 'show', both must allow visibility (requires passes AND show returns true).
+   */
+  requires?: Record<string, ((fieldValue: any) => boolean) | any>;
+  /**
+   * Programmatically control field visibility based on form values.
+   * Return true to show the field, false to hide it.
+   * Can be an async function, but this introduces complexity (loading states, error handling)
+   * often better handled within a custom field component.
+   * If used with 'requires', both must allow visibility (requires passes AND show returns true).
+   */
+  show?: (values: TRequest) => boolean | Promise<boolean>;
+  /** The type of form field */
+  type: FormFieldType | string;
+  /** Zod schema for field validation */
+  validation?: z.ZodTypeAny;
+}
+/**
+ * Type for form field options
+ */
+type FormFieldOption = string | {
+  label: string;
+  value: string;
+};
+/**
+ * Configuration interface for form field groups
+ */
+interface FormGroupType {
+  /** CSS class name for the group container */
+  className?: string;
+  /** Description for the group */
+  description?: string;
+  /** Unique ID for the group */
+  id: string;
+  /** Title for the group */
+  title?: string;
+}
+/**
+ * Defines the structure for a single step in a multi-step form.
+ */
+interface StepDefinition<TRequest extends BaseRecord = any> {
+  /**
+   * Whether to allow navigation to this step by clicking on progress indicator
+   * Takes precedence over the wizard-level allowStepNavigation config
+   */
+  allowStepNavigation?: AllowStepNavigation;
+  /**
+   * Description for the step
+   */
+  description?: string;
+  /** Fields in this step */
+  fields: FormFieldConfig<TRequest>[];
+  /**
+   * Icon for the step (used in wizard navigation)
+   */
+  icon?: React.ReactNode;
+  /** Metadata for the step */
+  meta?: Record<string, unknown>;
+  /**
+   * Callback when this step's submission fails
+   */
+  onStepError?: (error: Error) => Promise<void> | void;
+  /**
+   * Callback when this step's form is successfully submitted
+   */
+  onStepSubmit?: (values: Partial<TRequest>) => Promise<void> | void;
+  /**
+   * Callback when this step's submission succeeds
+   */
+  onStepSuccess?: (response: any, values: Partial<TRequest>) => Promise<void> | void;
+  /**
+   * Callback when this step needs to be retried
+   */
+  onRetryStep?: () => Promise<void> | void;
+  /**
+   * Short title for the step (used in wizard navigation)
+   */
+  shortTitle?: string;
+  /**
+   * Dynamic submit label for this step
+   * Receives form values and returns a string label
+   */
+  submitLabel?: (values: Partial<TRequest>) => string;
+  /** Title for the step */
+  title: string;
+  /**
+   * Zod schema for validating this step's fields
+   */
+  validationSchema?: z.ZodSchema<Partial<TRequest>>;
+}
+/**
+ * Configuration interface for a step form
+ */
+interface StepFormConfig<TRequest extends BaseRecord = any, TResponse extends BaseRecord = any> extends Omit<FormConfig<TRequest, TResponse>, "fields" | "footer"> {
+  /**
+   * Whether to allow navigation to steps by clicking on progress indicator
+   * @default true
+   */
+  allowStepNavigation?: boolean | (() => boolean);
+  /** Custom footer renderer for step forms */
+  footer?: StepFormFooterRenderer<TRequest, TResponse>;
+  /**
+   * Callback when all steps are completed successfully
+   */
+  onFinish?: (finalValues: TRequest) => Promise<void> | void;
+  /** Behavior configuration for steps */
+  stepBehavior?: {
+    /** Default step to start on */defaultStep?: number; /** Whether to validate when going back */
+    isBackValidate?: boolean;
+  };
+  /** Array of step definitions */
+  steps: StepDefinition<TRequest>[];
+  /**
+   * Optional callback for receiving a force rerender method.
+   * The framework will call this callback with a method that can be stored
+   * locally and used to force a component rerender when something outside
+   * the render loop needs to trigger a rerender.
+   */
+  forceRerender?: ForceRerenderCallback;
+  /**
+   * Optional callback for receiving an environment sync method.
+   * The framework will call this callback with a method that can be stored
+   * locally and used to sync environment changes when something outside
+   * the normal flow updates the environment.
+   */
+  environmentSync?: EnvironmentSyncCallback;
+}
+/**
+ * Type for step form footer renderer function
+ */
+type StepFormFooterRenderer<TRequest extends BaseRecord = any, TResponse extends BaseRecord = any> = (/** Step control methods */
+
+stepMethods: StepFormMethods, /** Form methods */
+
+formMethods: any, /** Function to close the dialog */
+
+closeDialog: () => void, /** Current dialog configuration */
+
+currentDialog?: DialogConfig<TRequest, TResponse>) => React.ReactNode;
+/**
+ * Configuration object specifically for a multi-step form process.
+ */
+interface StepFormMethods {
+  /** Current step index */
+  currentStep: number;
+  /** Function to navigate to a specific step */
+  gotoStep: (step: number) => void;
+  /** Function to go to the next step */
+  handleNext: () => Promise<void>;
+  /** Function to go to the previous step */
+  handlePrevious: () => Promise<void>;
+  /** Function to retry the current step */
+  handleRetry: () => Promise<void>;
+  /** Function to submit the current step */
+  handleSubmit: () => Promise<void>;
+  /** Whether the current step is the first step */
+  isFirstStep: boolean;
+  /** Whether the current step is the last step */
+  isLastStep: boolean;
+  /** Function to jump to a specific step number */
+  jumpTo: (step: number) => void;
+  /** Total number of steps */
+  totalSteps: number;
+}
+/**
+ * Configuration for a wizard form that extends StepFormConfig with wizard-specific options
+ */
+interface WizardFormConfig<TRequest extends BaseRecord = any, TResponse extends BaseRecord = any> extends StepFormConfig<TRequest, TResponse> {
+  /**
+   * Action buttons configuration for the form footer
+   * Can be:
+   * - Array of action button configs
+   * - Function that receives form methods and step control props and returns array of action button configs
+   * - false to hide action buttons
+   */
+  actionButtons?: ActionItemConfig[] | false | ActionButtonsCallback<TRequest>;
+  /**
+   * Whether to allow navigation to steps by clicking on progress indicator
+   * @default true
+   */
+  allowStepNavigation?: boolean | (() => boolean);
+  /**
+   * Maximum width for step descriptions in the wizard header
+   * Uses standard component size classes (e.g., 'xs', 'sm', 'md', 'lg', 'xl', '2xl', etc.)
+   * @default 'xs'
+   */
+  descriptionMaxWidth?: ComponentSize;
+  /**
+   * Custom className for wizard footer
+   */
+  footerClassName?: string;
+  /**
+   * Custom className for wizard header
+   */
+  headerClassName?: string;
+  /**
+   * Style of progress indicator to use
+   * @default 'timeline'
+   */
+  progressStyle?: "dots" | "stepper" | "timeline";
+  /**
+   * Whether to show step descriptions in the progress indicator
+   * @default true
+   */
+  showStepDescriptions?: boolean;
+  /**
+   * Whether to show step progress indicator
+   * @default true
+   */
+  showStepProgress?: boolean;
+  /**
+   * Whether to show step titles in the progress indicator
+   * @default true
+   */
+  showStepTitles?: boolean;
+  /**
+   * Array of step indices that cannot be navigated to
+   * @default []
+   */
+  stepNavigationDisabled?: ((currentStep: number, data: any) => boolean[]) | boolean[];
+  /**
+   * Custom className for wizard wrapper
+   */
+  wizardClassName?: string;
+  /**
+   * Optional callback for receiving a force rerender method.
+   * The framework will call this callback with a method that can be stored
+   * locally and used to force a component rerender when something outside
+   * the render loop needs to trigger a rerender.
+   */
+  forceRerender?: ForceRerenderCallback;
+  /**
+   * Optional callback for receiving an environment sync method.
+   * The framework will call this callback with a method that can be stored
+   * locally and used to sync environment changes when something outside
+   * the normal flow updates the environment.
+   */
+  environmentSync?: EnvironmentSyncCallback;
+}
+/**
+ * Wizard-specific step definition that extends StepDefinition
+ * Wizard steps require UI properties (icon, shortTitle, description) that are optional in regular step forms
+ */
+interface WizardStepDefinition<TRequest extends BaseRecord = any> extends Omit<StepDefinition<TRequest>, "description" | "icon" | "shortTitle"> {
+  /**
+   * Whether to allow navigation to this step by clicking on progress indicator
+   * Takes precedence over the wizard-level allowStepNavigation config
+   */
+  allowStepNavigation?: AllowStepNavigation;
+  /**
+   * Description for the step
+   * Required for wizard steps
+   */
+  description: string;
+  /**
+   * Icon for the step (used in wizard navigation)
+   * Required for wizard steps
+   */
+  icon: React.ReactNode;
+  /**
+   * Short title for the step (used in wizard navigation)
+   * Required for wizard steps
+   */
+  shortTitle: string;
+}
+/**
+ * Type guard to check if footer is a function with the proper signature
+ */
+declare function isFooterFunction<TRequest extends BaseRecord, TResponse extends BaseRecord>(footer: ((methods: any, closeDialog: () => void, currentDialog?: DialogConfig<TRequest, TResponse>) => ActionItemConfig[] | ReactNode) | ActionItemConfig[] | false | ReactNode | undefined): footer is (methods: any, closeDialog: () => void, currentDialog?: DialogConfig<TRequest, TResponse>) => ActionItemConfig[] | ReactNode;
+/**
+ * Type guard to check if actionButtons is a function with the proper signature
+ */
+declare function isActionButtonsFunction<TRequest extends BaseRecord>(actionButtons: ActionItemConfig[] | false | ((props: {
+  environment?: UnifiedEnvironment;
+}) => ActionItemConfig[] | undefined | false) | undefined): actionButtons is (props: {
+  environment?: UnifiedEnvironment;
+}) => ActionItemConfig[] | undefined | false;
+/**
+ * Type guard to check if header is a function
+ */
+declare function isHeaderFunction<TRequest extends BaseRecord>(header: ((environment: any) => ReactNode) | false | ReactNode | undefined): header is (environment: any) => ReactNode;
+/**
+ * Type guard to differentiate between single-step and multi-step form configs.
+ */
+declare function isStepFormConfig<TRequest extends BaseRecord, TResponse extends BaseRecord = any>(config: FormConfig<TRequest, TResponse> | StepFormConfig<TRequest, TResponse>): config is StepFormConfig<TRequest, TResponse>;
+/**
+ * Type guard to check if submitLabel is a function
+ */
+declare function isSubmitLabelFunction<TRequest extends BaseRecord>(submitLabel: ((values: Partial<TRequest>) => string) | string | undefined): submitLabel is (values: Partial<TRequest>) => string;
+//#endregion
+export { ActionButtonsCallback, AdapterType, AutocompleteToken, FormAutosaveConfig, FormConfig, FormFieldConfig, FormFieldOption, FormGroupType, GroupOrder, LayoutType, StepDefinition, StepFormConfig, StepFormFooterRenderer, StepFormMethods, WizardFormConfig, WizardStepDefinition, isActionButtonsFunction, isFooterFunction, isHeaderFunction, isStepFormConfig, isSubmitLabelFunction };
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/components/form/types.js

@@ -0,0 +1,69 @@
+//#region src/components/form/types.ts
+/**
+* Enum defining the adapter types for form handling
+*/
+let AdapterType = /* @__PURE__ */ function(AdapterType) {
+	/** Refine adapter */
+	AdapterType["REFINE"] = "refine";
+	/** React Hook Form adapter */
+	AdapterType["RHF"] = "rhf";
+	return AdapterType;
+}({});
+/**
+* Enum defining the order in which grouped and ungrouped fields are rendered
+*/
+let GroupOrder = /* @__PURE__ */ function(GroupOrder) {
+	/** Render groups first, then ungrouped fields */
+	GroupOrder["GROUPS_FIRST"] = "groups-first";
+	/** Render ungrouped fields first, then groups */
+	GroupOrder["UNGROUPED_FIRST"] = "ungrouped-first";
+	return GroupOrder;
+}({});
+/**
+* Enum defining the layout types for forms
+*/
+let LayoutType = /* @__PURE__ */ function(LayoutType) {
+	/** Grid layout */
+	LayoutType["GRID"] = "grid";
+	/** Horizontal layout */
+	LayoutType["HORIZONTAL"] = "horizontal";
+	/** Vertical layout */
+	LayoutType["VERTICAL"] = "vertical";
+	return LayoutType;
+}({});
+/**
+* Type guard to check if footer is a function with the proper signature
+*/
+function isFooterFunction(footer) {
+	if (typeof footer !== "function") return false;
+	const fn = footer;
+	return fn.length >= 2 && fn.length <= 3;
+}
+/**
+* Type guard to check if actionButtons is a function with the proper signature
+*/
+function isActionButtonsFunction(actionButtons) {
+	return typeof actionButtons === "function";
+}
+/**
+* Type guard to check if header is a function
+*/
+function isHeaderFunction(header) {
+	return typeof header === "function";
+}
+/**
+* Type guard to differentiate between single-step and multi-step form configs.
+*/
+function isStepFormConfig(config) {
+	return config?.steps !== void 0;
+}
+/**
+* Type guard to check if submitLabel is a function
+*/
+function isSubmitLabelFunction(submitLabel) {
+	return typeof submitLabel === "function";
+}
+
+//#endregion
+export { AdapterType, GroupOrder, LayoutType, isActionButtonsFunction, isFooterFunction, isHeaderFunction, isStepFormConfig, isSubmitLabelFunction };
+//# sourceMappingURL=types.js.map

package/dist/esm/components/form/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","names":[],"sources":["../../../../src/components/form/types.ts"],"sourcesContent":["import type { ComponentType, ReactNode } from \"react\";\n\nimport {\n  type AutoSaveIndicatorElements,\n  type AutoSaveProps,\n  type BaseKey,\n  BaseRecord,\n  type FormAction,\n  HttpError,\n  OpenNotificationParams,\n} from \"@refinedev/core\";\nimport { UseFormProps as RefineUseFormProps } from \"@refinedev/react-hook-form\";\nimport { Path } from \"react-hook-form\";\nimport { z } from \"zod\";\n\nimport type { DialogConfig } from \"../dialog/Dialog.types\";\n\nimport { ActionItemConfig, ActionListLayout } from \"../actions\";\nimport { ComponentSize } from \"../sizing\";\nimport { FormFieldType } from \"./fields/types\";\nimport { UnifiedEnvironment } from \"../shared/types/environment\";\nimport type {\n  ForceRerenderCallback,\n  EnvironmentSyncCallback,\n} from \"../shared/types/form\";\nimport type { AllowStepNavigation } from \"../shared/types/navigation\";\n\n/**\n * Enum defining the adapter types for form handling\n */\nexport enum AdapterType {\n  /** Refine adapter */\n  REFINE = \"refine\",\n  /** React Hook Form adapter */\n  RHF = \"rhf\",\n}\n\n/**\n * Callback function type for generating action buttons based on environment\n */\nexport type ActionButtonsCallback<TRequest extends BaseRecord = any> = (props: {\n  /** The environment context for the form */\n  environment?: UnifiedEnvironment;\n}) => ActionItemConfig[] | undefined | false;\n\n/**\n * Enum defining the order in which grouped and ungrouped fields are rendered\n */\nexport enum GroupOrder {\n  /** Render groups first, then ungrouped fields */\n  GROUPS_FIRST = \"groups-first\",\n  /** Render ungrouped fields first, then groups */\n  UNGROUPED_FIRST = \"ungrouped-first\",\n}\n\n/**\n * Enum defining the layout types for forms\n */\nexport enum LayoutType {\n  /** Grid layout */\n  GRID = \"grid\",\n  /** Horizontal layout */\n  HORIZONTAL = \"horizontal\",\n  /** Vertical layout */\n  VERTICAL = \"vertical\",\n}\n\n/**\n * Type for HTML autocomplete attribute values\n */\nexport type AutocompleteToken =\n  | \"current-password\"\n  | \"email\"\n  | \"family-name\"\n  | \"given-name\"\n  | \"new-password\"\n  | \"off\"\n  | \"on\"\n  | \"one-time-code\"\n  | \"username\";\n\n/**\n * Configuration type for form autosave functionality\n */\nexport type FormAutosaveConfig<T> = AutoSaveProps<T>[\"autoSave\"];\n\n/**\n * Configuration interface for a form\n */\nexport interface FormConfig<\n  TRequest extends BaseRecord = any,\n  TResponse extends BaseRecord = any,\n> {\n  /** The form action type (create, edit, etc.) */\n  action?: FormAction;\n  /**\n   * Action buttons configuration for the form footer\n   */\n  actionButtons?: ActionItemConfig[] | false | ActionButtonsCallback;\n  /**\n   * Layout for action buttons in footer\n   * @default \"horizontal\"\n   */\n  actionButtonsLayout?: ActionListLayout;\n  /** The adapter type to use for form handling */\n  adapter?: AdapterType;\n  /** Whether to enable autosave functionality */\n  autoSave?: boolean | FormAutosaveConfig<TRequest>;\n  /** Custom elements for different autosave states */\n  autoSaveStates?: AutoSaveIndicatorElements;\n  /** Whether to close the dialog after successful submission */\n  closeOnSubmit?: boolean;\n  /** Default values for the form fields */\n  defaultValues?: TRequest;\n  /** Alias for refineCoreProps.errorNotification */\n  errorNotification?:\n    | ((error: any) => OpenNotificationParams)\n    | OpenNotificationParams;\n  /** Array of form field configurations */\n  fields: FormFieldConfig<TRequest>[];\n  /**\n   * Custom footer content or configuration\n   * Can be:\n   * - React node\n   * - Array of action button configs\n   * - Function that receives form methods and returns React node\n   */\n  footer?:\n    | ((\n        methods: any,\n        closeDialog: () => void,\n        currentDialog?: DialogConfig<TRequest, TResponse>,\n      ) => ActionItemConfig[] | ReactNode)\n    | ActionItemConfig[]\n    | false\n    | ReactNode;\n  /**\n   * Class name for the footer wrapper\n   * Set to false to disable default padding/border styles\n   * @default \"pt-4 mt-4 border-t\"\n   */\n  footerClassName?: false | string;\n  /** CSS class name for the form container */\n  formClassName?: string;\n  /**\n   * Unique identifier for the form configuration.\n   * This is separate from the record ID and is used to identify the form itself.\n   */\n  formId?: string;\n  /**\n   * Controls whether grouped or ungrouped fields are rendered first\n   * @default GroupOrder.UNGROUPED_FIRST\n   */\n  groupOrder?: GroupOrder;\n  /**\n   * Groups configuration for organizing fields\n   */\n  groups?: FormGroupType[];\n  /**\n   * Custom header content to render at the top of the form\n   * Can be:\n   * - React node for static content\n   * - Function that receives environment context and returns React node\n   * - false to hide header\n   */\n  header?: ((environment: any) => ReactNode) | false | ReactNode;\n  /** The ID of the record being edited (for edit forms) */\n  id?: BaseKey;\n  /** The layout type for the form */\n  layout?: LayoutType;\n  /** Error handler for form submission */\n  onError?: (error: Error) => void;\n  /** Submit handler for the form */\n  onSubmit?: (values: TRequest) => Promise<TResponse> | void;\n  /** Alias for refineCoreProps.onMutationSuccess */\n  onSuccess?: (response: TResponse, values: TRequest) => void;\n  /** Whether to use refine framework */\n  refine?: boolean;\n  /** Refine-specific form properties */\n  refineCoreProps?: RefineUseFormProps<\n    TRequest,\n    HttpError,\n    TRequest\n  >[\"refineCoreProps\"] & {\n    /** Error notification configuration */\n    errorNotification?: (error: any) => OpenNotificationParams;\n    /** Metadata for the form */\n    meta?: Record<string, unknown>;\n    /** Success notification configuration */\n    successNotification?: (data: any, values: any) => OpenNotificationParams;\n  };\n  /** The resource name for the form */\n  resource?: string;\n  /** Label for the submit button */\n  submitLabel?: ((values: Partial<TRequest>) => string) | string;\n  /** Alias for refineCoreProps.successNotification */\n  successNotification?: (data: any, values: any) => OpenNotificationParams;\n  /** Zod schema for form validation */\n  validationSchema?: z.ZodSchema<TRequest>;\n  /**\n   * Optional callback for receiving a force rerender method.\n   * The framework will call this callback with a method that can be stored\n   * locally and used to force a component rerender when something outside\n   * the render loop needs to trigger a rerender.\n   */\n  forceRerender?: ForceRerenderCallback;\n  /**\n   * Optional callback for receiving an environment sync method.\n   * The framework will call this callback with a method that can be stored\n   * locally and used to sync environment changes when something outside\n   * the normal flow updates the environment.\n   */\n  environmentSync?: EnvironmentSyncCallback;\n  /**\n   * Callback when navigation starts\n   */\n  onNavigationStart?: (fromStep: number, toStep: number, type: 'goTo' | 'jumpTo' | 'next' | 'previous' | 'retry') => void;\n  /**\n   * Callback when navigation ends successfully\n   */\n  onNavigationEnd?: (fromStep: number, toStep: number, type: 'goTo' | 'jumpTo' | 'next' | 'previous' | 'retry') => void;\n  /**\n   * Callback when navigation fails\n   */\n  onNavigationError?: (fromStep: number, toStep: number, type: 'goTo' | 'jumpTo' | 'next' | 'previous' | 'retry', error: any) => void;\n}\n\n/**\n * Configuration interface for a form field\n */\nexport interface FormFieldConfig<TRequest extends BaseRecord = any> {\n  /**\n   * The HTML autocomplete attribute value for the field.\n   * If provided, it will be passed to the underlying input component.\n   */\n  autocomplete?: AutocompleteToken;\n  /** CSS class name for the field container */\n  className?: string;\n  /** Custom component to render for this field */\n  component?: ComponentType<any>;\n  /**\n   * Optimize performance by specifying which field names (paths using dot notation)\n   * influence the 'show' function or 'requires' conditions for this field.\n   * If omitted, conditional checks might rely on less performant full form watches.\n   */\n  dependencies?: string[];\n  /** Description text for the field */\n  description?: string;\n  /**\n   * Group ID this field belongs to\n   */\n  group?: string;\n  /** CSS class name for the input element */\n  inputClassName?: string;\n  /**\n   * Additional props to pass to the underlying input element\n   */\n  inputProps?: Record<string, any>;\n  /**\n   * Class name applied to the FormItem wrapper component\n   */\n  itemClassName?: string;\n  /** Label text for the field */\n  label?: string;\n  /** CSS class name for the label element */\n  labelClassName?: string;\n  /** Field name/path (using dot notation for nested fields) */\n  name: Path<TRequest> | (string & {});\n  /** Options for select-type fields */\n  options?: FormFieldOption[];\n  /** Placeholder text for the field */\n  placeholder?: string;\n  /** Whether the field is required */\n  required?: boolean;\n  /**\n   * Declaratively define dependencies for field visibility.\n   * The field will only be shown if *all* conditions in this object are met.\n   * Keys are paths to other fields (using dot notation for nested fields).\n   * Values are the required value for that field, or a function predicate.\n   * Example: { 'user.role': 'admin', 'settings.enabled': true, 'profile.age': (age) => age >= 18 }\n   * If used with 'show', both must allow visibility (requires passes AND show returns true).\n   */\n  requires?: Record<string, ((fieldValue: any) => boolean) | any>;\n  /**\n   * Programmatically control field visibility based on form values.\n   * Return true to show the field, false to hide it.\n   * Can be an async function, but this introduces complexity (loading states, error handling)\n   * often better handled within a custom field component.\n   * If used with 'requires', both must allow visibility (requires passes AND show returns true).\n   */\n  show?: (values: TRequest) => boolean | Promise<boolean>;\n  /** The type of form field */\n  type: FormFieldType | string;\n  /** Zod schema for field validation */\n  validation?: z.ZodTypeAny;\n}\n\n/**\n * Type for form field options\n */\nexport type FormFieldOption = string | { label: string; value: string };\n\n/**\n * Configuration interface for form field groups\n */\nexport interface FormGroupType {\n  /** CSS class name for the group container */\n  className?: string;\n  /** Description for the group */\n  description?: string;\n  /** Unique ID for the group */\n  id: string;\n  /** Title for the group */\n  title?: string;\n}\n\n/**\n * Defines the structure for a single step in a multi-step form.\n */\nexport interface StepDefinition<TRequest extends BaseRecord = any> {\n  /**\n   * Whether to allow navigation to this step by clicking on progress indicator\n   * Takes precedence over the wizard-level allowStepNavigation config\n   */\n  allowStepNavigation?: AllowStepNavigation;\n  /**\n   * Description for the step\n   */\n  description?: string;\n  /** Fields in this step */\n  fields: FormFieldConfig<TRequest>[];\n  /**\n   * Icon for the step (used in wizard navigation)\n   */\n  icon?: React.ReactNode;\n  /** Metadata for the step */\n  meta?: Record<string, unknown>;\n  /**\n   * Callback when this step's submission fails\n   */\n  onStepError?: (error: Error) => Promise<void> | void;\n  /**\n   * Callback when this step's form is successfully submitted\n   */\n  onStepSubmit?: (values: Partial<TRequest>) => Promise<void> | void;\n  /**\n   * Callback when this step's submission succeeds\n   */\n  onStepSuccess?: (\n    response: any,\n    values: Partial<TRequest>,\n  ) => Promise<void> | void;\n  /**\n   * Callback when this step needs to be retried\n   */\n  onRetryStep?: () => Promise<void> | void;\n  /**\n   * Short title for the step (used in wizard navigation)\n   */\n  shortTitle?: string;\n  /**\n   * Dynamic submit label for this step\n   * Receives form values and returns a string label\n   */\n  submitLabel?: (values: Partial<TRequest>) => string;\n  /** Title for the step */\n  title: string;\n  /**\n   * Zod schema for validating this step's fields\n   */\n  validationSchema?: z.ZodSchema<Partial<TRequest>>;\n}\n\n/**\n * Configuration interface for a step form\n */\nexport interface StepFormConfig<\n  TRequest extends BaseRecord = any,\n  TResponse extends BaseRecord = any,\n> extends Omit<FormConfig<TRequest, TResponse>, \"fields\" | \"footer\"> {\n  /**\n   * Whether to allow navigation to steps by clicking on progress indicator\n   * @default true\n   */\n  allowStepNavigation?: boolean | (() => boolean);\n  /** Custom footer renderer for step forms */\n  footer?: StepFormFooterRenderer<TRequest, TResponse>;\n  /**\n   * Callback when all steps are completed successfully\n   */\n  onFinish?: (finalValues: TRequest) => Promise<void> | void;\n  /** Behavior configuration for steps */\n  stepBehavior?: {\n    /** Default step to start on */\n    defaultStep?: number;\n    /** Whether to validate when going back */\n    isBackValidate?: boolean;\n  };\n  /** Array of step definitions */\n  steps: StepDefinition<TRequest>[];\n  /**\n   * Optional callback for receiving a force rerender method.\n   * The framework will call this callback with a method that can be stored\n   * locally and used to force a component rerender when something outside\n   * the render loop needs to trigger a rerender.\n   */\n  forceRerender?: ForceRerenderCallback;\n  /**\n   * Optional callback for receiving an environment sync method.\n   * The framework will call this callback with a method that can be stored\n   * locally and used to sync environment changes when something outside\n   * the normal flow updates the environment.\n   */\n  environmentSync?: EnvironmentSyncCallback;\n}\n\n/**\n * Type for step form footer renderer function\n */\nexport type StepFormFooterRenderer<\n  TRequest extends BaseRecord = any,\n  TResponse extends BaseRecord = any,\n> = (\n  /** Step control methods */\n  stepMethods: StepFormMethods,\n  /** Form methods */\n  formMethods: any,\n  /** Function to close the dialog */\n  closeDialog: () => void,\n  /** Current dialog configuration */\n  currentDialog?: DialogConfig<TRequest, TResponse>,\n) => React.ReactNode;\n\n/**\n * Configuration object specifically for a multi-step form process.\n */\nexport interface StepFormMethods {\n  /** Current step index */\n  currentStep: number;\n  /** Function to navigate to a specific step */\n  gotoStep: (step: number) => void;\n  /** Function to go to the next step */\n  handleNext: () => Promise<void>;\n  /** Function to go to the previous step */\n  handlePrevious: () => Promise<void>;\n  /** Function to retry the current step */\n  handleRetry: () => Promise<void>;\n  /** Function to submit the current step */\n  handleSubmit: () => Promise<void>;\n  /** Whether the current step is the first step */\n  isFirstStep: boolean;\n  /** Whether the current step is the last step */\n  isLastStep: boolean;\n  /** Function to jump to a specific step number */\n  jumpTo: (step: number) => void;\n  /** Total number of steps */\n  totalSteps: number;\n}\n\n/**\n * Configuration for a wizard form that extends StepFormConfig with wizard-specific options\n */\nexport interface WizardFormConfig<\n  TRequest extends BaseRecord = any,\n  TResponse extends BaseRecord = any,\n> extends StepFormConfig<TRequest, TResponse> {\n  /**\n   * Action buttons configuration for the form footer\n   * Can be:\n   * - Array of action button configs\n   * - Function that receives form methods and step control props and returns array of action button configs\n   * - false to hide action buttons\n   */\n  actionButtons?: ActionItemConfig[] | false | ActionButtonsCallback<TRequest>;\n  /**\n   * Whether to allow navigation to steps by clicking on progress indicator\n   * @default true\n   */\n  allowStepNavigation?: boolean | (() => boolean);\n  /**\n   * Maximum width for step descriptions in the wizard header\n   * Uses standard component size classes (e.g., 'xs', 'sm', 'md', 'lg', 'xl', '2xl', etc.)\n   * @default 'xs'\n   */\n  descriptionMaxWidth?: ComponentSize;\n  /**\n   * Custom className for wizard footer\n   */\n  footerClassName?: string;\n  /**\n   * Custom className for wizard header\n   */\n  headerClassName?: string;\n  /**\n   * Style of progress indicator to use\n   * @default 'timeline'\n   */\n  progressStyle?: \"dots\" | \"stepper\" | \"timeline\";\n  /**\n   * Whether to show step descriptions in the progress indicator\n   * @default true\n   */\n  showStepDescriptions?: boolean;\n  /**\n   * Whether to show step progress indicator\n   * @default true\n   */\n  showStepProgress?: boolean;\n  /**\n   * Whether to show step titles in the progress indicator\n   * @default true\n   */\n  showStepTitles?: boolean;\n  /**\n   * Array of step indices that cannot be navigated to\n   * @default []\n   */\n  stepNavigationDisabled?:\n    | ((currentStep: number, data: any) => boolean[])\n    | boolean[];\n  /**\n   * Custom className for wizard wrapper\n   */\n  wizardClassName?: string;\n  /**\n   * Optional callback for receiving a force rerender method.\n   * The framework will call this callback with a method that can be stored\n   * locally and used to force a component rerender when something outside\n   * the render loop needs to trigger a rerender.\n   */\n  forceRerender?: ForceRerenderCallback;\n  /**\n   * Optional callback for receiving an environment sync method.\n   * The framework will call this callback with a method that can be stored\n   * locally and used to sync environment changes when something outside\n   * the normal flow updates the environment.\n   */\n  environmentSync?: EnvironmentSyncCallback;\n}\n\n/**\n * Wizard-specific step definition that extends StepDefinition\n * Wizard steps require UI properties (icon, shortTitle, description) that are optional in regular step forms\n */\nexport interface WizardStepDefinition<TRequest extends BaseRecord = any>\n  extends Omit<\n    StepDefinition<TRequest>,\n    \"description\" | \"icon\" | \"shortTitle\"\n  > {\n  /**\n   * Whether to allow navigation to this step by clicking on progress indicator\n   * Takes precedence over the wizard-level allowStepNavigation config\n   */\n  allowStepNavigation?: AllowStepNavigation;\n  /**\n   * Description for the step\n   * Required for wizard steps\n   */\n  description: string;\n  /**\n   * Icon for the step (used in wizard navigation)\n   * Required for wizard steps\n   */\n  icon: React.ReactNode;\n  /**\n   * Short title for the step (used in wizard navigation)\n   * Required for wizard steps\n   */\n  shortTitle: string;\n}\n\n/**\n * Type guard to check if footer is a function with the proper signature\n */\nexport function isFooterFunction<\n  TRequest extends BaseRecord,\n  TResponse extends BaseRecord,\n>(\n  footer:\n    | ((\n        methods: any,\n        closeDialog: () => void,\n        currentDialog?: DialogConfig<TRequest, TResponse>,\n      ) => ActionItemConfig[] | ReactNode)\n    | ActionItemConfig[]\n    | false\n    | ReactNode\n    | undefined,\n): footer is (\n  methods: any,\n  closeDialog: () => void,\n  currentDialog?: DialogConfig<TRequest, TResponse>,\n) => ActionItemConfig[] | ReactNode {\n  if (typeof footer !== \"function\") return false;\n\n  // We can't fully validate function signatures at runtime, but we can check the length\n  // Footer functions should have 2 or 3 parameters (methods, closeDialog, currentDialog?)\n  const fn = footer as Function;\n  return fn.length >= 2 && fn.length <= 3;\n}\n\n/**\n * Type guard to check if actionButtons is a function with the proper signature\n */\nexport function isActionButtonsFunction<TRequest extends BaseRecord>(\n  actionButtons:\n    | ActionItemConfig[]\n    | false\n    | ((props: {\n        environment?: UnifiedEnvironment;\n      }) => ActionItemConfig[] | undefined | false)\n    | undefined,\n): actionButtons is (props: {\n  environment?: UnifiedEnvironment;\n}) => ActionItemConfig[] | undefined | false {\n  return typeof actionButtons === \"function\";\n}\n\n/**\n * Type guard to check if header is a function\n */\nexport function isHeaderFunction<TRequest extends BaseRecord>(\n  header: ((environment: any) => ReactNode) | false | ReactNode | undefined,\n): header is (environment: any) => ReactNode {\n  return typeof header === \"function\";\n}\n\n/**\n * Type guard to differentiate between single-step and multi-step form configs.\n */\nexport function isStepFormConfig<\n  TRequest extends BaseRecord,\n  TResponse extends BaseRecord = any,\n>(\n  config: FormConfig<TRequest, TResponse> | StepFormConfig<TRequest, TResponse>,\n): config is StepFormConfig<TRequest, TResponse> {\n  return (config as StepFormConfig<TRequest>)?.steps !== undefined;\n}\n\n/**\n * Type guard to check if submitLabel is a function\n */\nexport function isSubmitLabelFunction<TRequest extends BaseRecord>(\n  submitLabel: ((values: Partial<TRequest>) => string) | string | undefined,\n): submitLabel is (values: Partial<TRequest>) => string {\n  return typeof submitLabel === \"function\";\n}\n"],"mappings":";;;;AA8BA,IAAY,cAAL;;AAEL;;AAEA;;KACD;;;;AAaD,IAAY,aAAL;;AAEL;;AAEA;;KACD;;;;AAKD,IAAY,aAAL;;AAEL;;AAEA;;AAEA;;KACD;;;;AA6fD,SAAgB,iBAId,QAckC;AAClC,KAAI,OAAO,WAAW,WAAY,QAAO;CAIzC,MAAM,KAAK;AACX,QAAO,GAAG,UAAU,KAAK,GAAG,UAAU;;;;;AAMxC,SAAgB,wBACd,eAS2C;AAC3C,QAAO,OAAO,kBAAkB;;;;;AAMlC,SAAgB,iBACd,QAC2C;AAC3C,QAAO,OAAO,WAAW;;;;;AAM3B,SAAgB,iBAId,QAC+C;AAC/C,QAAQ,QAAqC,UAAU;;;;;AAMzD,SAAgB,sBACd,aACsD;AACtD,QAAO,OAAO,gBAAgB"}

package/dist/esm/components/form/utils/animationUtils.d.ts

@@ -0,0 +1,14 @@
+//#region src/components/form/utils/animationUtils.d.ts
+/**
+ * Determines animation classes for wizard step transitions using CSS Grid
+ *
+ * @param isEntering - Whether the step is currently entering
+ * @param isExiting - Whether the step is currently exiting
+ * @param isActive - Whether the step is currently active
+ * @param direction - The direction of transition ("forward", "backward", or null)
+ * @returns CSS classes for the transition animation
+ */
+declare function getStepAnimationClasses(isEntering: boolean, isExiting: boolean, isActive: boolean, direction: "backward" | "forward" | null): string;
+//#endregion
+export { getStepAnimationClasses };
+//# sourceMappingURL=animationUtils.d.ts.map

package/dist/esm/components/form/utils/animationUtils.js

@@ -0,0 +1,20 @@
+//#region src/components/form/utils/animationUtils.ts
+/**
+* Determines animation classes for wizard step transitions using CSS Grid
+*
+* @param isEntering - Whether the step is currently entering
+* @param isExiting - Whether the step is currently exiting
+* @param isActive - Whether the step is currently active
+* @param direction - The direction of transition ("forward", "backward", or null)
+* @returns CSS classes for the transition animation
+*/
+function getStepAnimationClasses(isEntering, isExiting, isActive, direction) {
+	if (isEntering) return "opacity-100 scale-100 pointer-events-auto z-10";
+	if (isExiting) return "opacity-0 scale-95 pointer-events-none z-0";
+	if (isActive) return "opacity-100 scale-100 pointer-events-auto z-10";
+	return "opacity-0 scale-95 pointer-events-none z-0";
+}
+
+//#endregion
+export { getStepAnimationClasses };
+//# sourceMappingURL=animationUtils.js.map