@vef-framework-react/components 2.1.11 → 2.2.0

package/dist/types/form/helpers/create-field.d.ts

@@ -1,61 +1,75 @@
-import { DeepKeys, DeepValue, FieldAsyncValidateOrFn, FieldValidateOrFn, FieldValidators } from '@tanstack/react-form';
+import { DeepKeys, DeepValue, FieldAsyncValidateOrFn, FieldValidateOrFn, UseFieldOptionsBound } from '@tanstack/react-form';
 import { AnyObject, MaybeUndefined } from '@vef-framework-react/shared';
 import { ReactNode } from 'react';
 import { fieldComponents } from '../fields';
 type MaybeFieldSync<T, N extends DeepKeys<T>> = MaybeUndefined<FieldValidateOrFn<T, N, DeepValue<T, N>>>;
 type MaybeFieldAsync<T, N extends DeepKeys<T>> = MaybeUndefined<FieldAsyncValidateOrFn<T, N, DeepValue<T, N>>>;
 /**
- * Simplified `FieldValidators` with all `TOn*` slots widened to their upper bounds.
- * Accepts zod schemas, validator functions, or `undefined` for each lifecycle event.
+ * Bound `<form.AppField>` props for a known field name, with all `TOn*`
+ * validator slots widened to their upper bounds. The `name` field is omitted
+ * because `createField` takes it as the first argument.
  */
-type FieldValidatorsFor<T, N extends DeepKeys<T>> = FieldValidators<T, N, DeepValue<T, N>, MaybeFieldSync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>>;
-declare const ErasedValidatorBrand: unique symbol;
+type AppFieldOptionsFor<T, N extends DeepKeys<T>> = Omit<UseFieldOptionsBound<T, N, DeepValue<T, N>, MaybeFieldSync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>, MaybeFieldSync<T, N>, MaybeFieldAsync<T, N>>, "name">;
+declare const ErasedFieldOptionsBrand: unique symbol;
 /**
- * Opaque wrapper for type-erased field validators. Retains `TFormData`
- * association but hides the specific field name. Cannot be constructed
- * directly — use `createField` to produce values of this type.
+ * Opaque wrapper for type-erased `<form.AppField>` options. Retains the
+ * `TFormData` association while hiding the specific field name. Cannot be
+ * constructed directly — use `createField` to produce values of this type.
  */
-export interface ErasedValidators<TFormData> {
-    readonly [ErasedValidatorBrand]: TFormData;
+export interface ErasedFieldOptions<TFormData> {
+    readonly [ErasedFieldOptionsBrand]: TFormData;
 }
 /**
- * Restore erased validators to their specific field type at the render site.
+ * Restore erased field options to their specific field type at the render
+ * site. Always returns an object (never undefined), so the result can be
+ * spread onto `<form.AppField>` without an extra null check.
  *
  * @example
  * ```tsx
  * items.map(item => (
  *   <form.AppField
+ *     key={item.name}
  *     name={item.name}
- *     validators={restoreValidators(item.validators)}
+ *     {...restoreFieldOptions(item.fieldOptions)}
  *   >
  *     {item.render}
  *   </form.AppField>
  * ));
  * ```
  */
-export declare function restoreValidators<T, N extends DeepKeys<T>>(validators: MaybeUndefined<ErasedValidators<T>>): MaybeUndefined<FieldValidatorsFor<T, N>>;
-interface FormFieldOptions<T, N extends DeepKeys<T>, TMeta extends AnyObject = AnyObject> {
-    validators?: FieldValidatorsFor<T, N>;
+export declare function restoreFieldOptions<T, N extends DeepKeys<T>>(options: MaybeUndefined<ErasedFieldOptions<T>>): AppFieldOptionsFor<T, N>;
+/**
+ * Field definition input accepted by `createField`. Extends every bound
+ * `<form.AppField>` prop (validators, listeners, defaultValue, asyncDebounceMs,
+ * mode, defaultMeta, …) and adds two project-specific slots:
+ *
+ * - `render`: the render-prop body, scoped to the injected field components.
+ * - `renderMeta`: arbitrary metadata consumed by the surrounding map (e.g.
+ * layout span, visibility). Named `renderMeta` to avoid confusion with
+ * TanStack's `defaultMeta`, which seeds `FieldMeta` state.
+ */
+type FormFieldOptions<T, N extends DeepKeys<T>, TMeta extends AnyObject = AnyObject> = AppFieldOptionsFor<T, N> & {
     render: (field: typeof fieldComponents) => ReactNode;
-    meta?: TMeta;
-}
+    renderMeta?: TMeta;
+};
 /**
- * Type-erased form field item for homogeneous array storage.
- * Type checking is performed at the `createField` call site; the erased
- * representation is safe to iterate, filter, and reorder without losing safety.
+ * Type-erased form field item for homogeneous array storage. Type checking
+ * happens at the `createField` call site; the erased representation is safe
+ * to iterate, filter, and reorder without losing safety.
  *
- * Validators use an opaque branded type (`ErasedValidators`) instead of `any`.
- * Use `restoreValidators(item.validators)` at the render site to pass them
- * to `<AppField>`.
+ * Field-name-dependent options live inside `fieldOptions` as an opaque
+ * branded value (`ErasedFieldOptions`). Use `restoreFieldOptions(item.fieldOptions)`
+ * at the render site to spread them onto `<form.AppField>`.
  *
  * `TMeta` allows attaching arbitrary typed metadata (e.g. layout, visibility)
- * to each field item. Defaults to `AnyObject` for zero-overhead when unused.
+ * to each field item via `renderMeta`. Defaults to `AnyObject` for zero
+ * overhead when unused.
  */
 export interface FormFieldItem<TFormData, TMeta extends AnyObject = AnyObject> {
     name: DeepKeys<TFormData>;
-    validators?: ErasedValidators<TFormData>;
+    fieldOptions?: ErasedFieldOptions<TFormData>;
     render: (field: typeof fieldComponents) => ReactNode;
-    meta?: TMeta;
+    renderMeta?: TMeta;
 }
 /**
  * Type-safe field definition factory scoped to a specific form data type.
@@ -68,15 +82,23 @@ export interface FormFieldItem<TFormData, TMeta extends AnyObject = AnyObject> {
  *
  * const items: FormFieldItem<StaffParams, FieldMeta>[] = [
  *   createField("name", {
- *     meta: { span: 12 },
  *     validators: { onBlur: z.string("required").max(32) },
+ *     listeners: {
+ *       onChange: ({ value }) => track("staff_name_changed", { value }),
+ *     },
+ *     defaultValue: "",
+ *     renderMeta: { span: 12 },
  *     render: field => <field.Input required label="Name" />,
  *   }),
  * ];
  *
  * // Render:
  * items.map(item => (
- *   <AppField name={item.name} validators={restoreValidators(item.validators)}>
+ *   <AppField
+ *     key={item.name}
+ *     name={item.name}
+ *     {...restoreFieldOptions(item.fieldOptions)}
+ *   >
  *     {item.render}
  *   </AppField>
  * ));

package/dist/types/form/helpers/index.d.ts

@@ -1,3 +1,3 @@
-export { createField, restoreValidators } from './create-field';
-export type { CreateFieldFn, ErasedValidators, FormFieldItem } from './create-field';
+export { createField, restoreFieldOptions } from './create-field';
+export type { CreateFieldFn, ErasedFieldOptions, FormFieldItem } from './create-field';
 export { withFormItem } from './with-form-item';

package/dist/types/form/index.d.ts

@@ -2,7 +2,7 @@ export type * from './components';
 export type * from './fields';
 export { createFormOptions, useFormContext, useFormStore, withFieldGroup, withForm } from './form';
 export { DefaultResetButton, DefaultSubmitButton, FormActions, type FormActionsProps } from './form-actions';
-export { restoreValidators } from './helpers';
+export { restoreFieldOptions } from './helpers';
 export type { FormFieldItem } from './helpers';
 export type * from './types';
 export { useForm } from './use-form';

package/dist/types/index.d.ts

@@ -8,6 +8,7 @@ export { AutoComplete, type AutoCompleteOption, type AutoCompleteProps } from '.
 export { Avatar, type AvatarGroupProps, type AvatarProps } from './avatar';
 export { Badge, type BadgeProps, type BadgeRibbonProps } from './badge';
 export { Bool, type BoolProps, type BoolVariant } from './bool';
+export { BorderBeam, type BorderBeamColor, type BorderBeamGradient, type BorderBeamProps } from './border-beam';
 export { Breadcrumb, type BreadcrumbItem, type BreadcrumbItemType, type BreadcrumbProps, type BreadcrumbSeparatorType } from './breadcrumb';
 export { Button, type ButtonProps } from './button';
 export { Calendar, type CalendarProps } from './calendar';
@@ -33,11 +34,12 @@ export { Drawer, type DrawerProps } from './drawer';
 export { Dropdown, type DropdownButtonProps, type DropdownButtonType, type DropdownMenuProps, type DropdownProps } from './dropdown';
 export { DynamicIcon, type DynamicIconName, type DynamicIconProps } from './dynamic-icon';
 export { Empty, type EmptyProps } from './empty';
+export { FileUpload, type FileUploadProps, type UploadedFileMeta } from './file-upload';
 export { Flex, type FlexProps } from './flex';
 export { FlexCard, type FlexCardProps } from './flex-card';
 export { FlipText, type FlipTextProps } from './flip-text';
 export { FloatButton, type FloatButtonProps } from './float-button';
-export { createFormOptions, restoreValidators, useForm, useFormContext, useFormStore, withFieldGroup, withForm } from './form';
+export { createFormOptions, restoreFieldOptions, useForm, useFormContext, useFormStore, withFieldGroup, withForm } from './form';
 export type * from './form';
 export { FormDrawer, type FormDrawerProps } from './form-drawer';
 export { FormModal, type FormModalProps } from './form-modal';

package/dist/types/split-text/index.d.ts

@@ -1,4 +1,4 @@
-import { ReactElement } from 'react';
+import { FC } from 'react';
 import { SplitTextProps } from './props';
-export declare function SplitText(props: SplitTextProps): ReactElement;
+export declare const SplitText: FC<SplitTextProps>;
 export { type SplitTextProps } from './props';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vef-framework-react/components",
   "type": "module",
-  "version": "2.1.11",
+  "version": "2.2.0",
   "private": false,
   "description": "Components for VEF Framework",
   "author": {
@@ -50,31 +50,31 @@
   },
   "dependencies": {
     "@ant-design/cssinjs": "^2.1.2",
-    "@ant-design/icons": "^6.1.1",
+    "@ant-design/icons": "^6.2.2",
     "@emotion/cache": "^11.14.0",
     "@emotion/react": "^11.14.0",
     "@emotion/serialize": "^1.3.3",
     "@gsap/react": "^2.1.2",
-    "@lucide/icons": "^1.9.0",
+    "@lucide/icons": "^1.16.0",
     "@radix-ui/react-scroll-area": "^1.2.10",
     "@tanstack/react-form": "^1.29.1",
-    "antd": "^6.3.6",
+    "antd": "^6.4.2",
     "antd-img-crop": "^4.30.0",
     "echarts": "^6.0.0",
     "echarts-for-react": "^3.0.6",
     "gsap": "^3.15.0",
-    "lucide-react": "^1.9.0",
+    "lucide-react": "^1.16.0",
     "modern-normalize": "^3.0.1",
     "react-error-boundary": "^6.1.1",
     "react-syntax-highlighter": "^16.1.1",
     "tslib": "^2.8.1",
-    "@vef-framework-react/core": "2.1.11",
-    "@vef-framework-react/shared": "2.1.11",
-    "@vef-framework-react/hooks": "2.1.11"
+    "@vef-framework-react/core": "2.2.0",
+    "@vef-framework-react/shared": "2.2.0",
+    "@vef-framework-react/hooks": "2.2.0"
   },
   "devDependencies": {
     "@types/react-syntax-highlighter": "^15.5.13",
-    "react": "^19.2.5"
+    "react": "^19.2.6"
   },
   "scripts": {
     "clean": "rimraf dist",