@faasjs/ant-design 8.0.0-beta.16 → 8.0.0-beta.18

package/dist/index.cjs

@@ -32,15 +32,24 @@ let dayjs = require("dayjs");
 dayjs = __toESM(dayjs);
 //#region src/Loading.tsx
 /**
-* Loading component based on Spin
+* Render an Ant Design loading spinner with an optional content fallback.
+*
+* @param {LoadingProps} props - Loading indicator props and optional wrapped children.
 *
 * @example
 * ```tsx
-* <Loading /> // display loading
+* import { Loading } from '@faasjs/ant-design'
 *
-* <Loading loading={ !remoteData }>
-*   <div>{remoteData}</div>
-* </Loading>
+* export function Page({ remoteData }: { remoteData?: string }) {
+*   return (
+*     <>
+*       <Loading />
+*       <Loading loading={!remoteData}>
+*         <div>{remoteData}</div>
+*       </Loading>
+*     </>
+*   )
+* }
 * ```
 */
 function Loading(props) {
@@ -59,18 +68,84 @@ function Loading(props) {
 //#endregion
 //#region src/FaasDataWrapper.tsx
 /**
-* FaasDataWrapper component with Loading
+* Render the `@faasjs/react` data wrapper with an Ant Design loading fallback.
+*
+* When `loading` is not provided, the component renders {@link Loading} with `loadingProps` while
+* the wrapped FaasJS request is pending.
+*
+* @template T - Action path or response data type used for inference.
+* @param {FaasDataWrapperProps<T>} props - Wrapper props including loading fallbacks and request configuration.
 *
 * @example
 * ```tsx
-* function MyComponent (props: FaasDataInjection) {
-*   return <div>{ props.data }</div>
+* import { Alert, Button } from 'antd'
+* import { FaasDataWrapper } from '@faasjs/ant-design'
+*
+* type User = {
+*   name: string
+* }
+*
+* function UserView(props: {
+*   data?: User
+*   error?: Error
+*   reload?: () => void
+* }) {
+*   if (props.error) {
+*     return (
+*       <Alert
+*         type="error"
+*         message={props.error.message}
+*         action={
+*           <Button size="small" onClick={() => props.reload?.()}>
+*             Retry
+*           </Button>
+*         }
+*       />
+*     )
+*   }
+*
+*   return <div>Hello, {props.data?.name}</div>
+* }
+*
+* // Render-prop mode
+* export function UserProfile(props: { id: number }) {
+*   return (
+*     <FaasDataWrapper<User>
+*       action="user/get"
+*       params={{ id: props.id }}
+*       loading={<div>Loading user...</div>}
+*       render={({ data, error, reload }) => {
+*         if (error) {
+*           return (
+*             <Alert
+*               type="error"
+*               message={error.message}
+*               action={
+*                 <Button size="small" onClick={() => reload()}>
+*                   Retry
+*                 </Button>
+*               }
+*             />
+*           )
+*         }
+*
+*         return <div>Hello, {data.name}</div>
+*       }}
+*     />
+*   )
 * }
 *
-* function MyPage () {
-*   return <FaasDataWrapper action="test" params={{ a: 1 }}>
-*     <MyComponent />
-*   </FaasDataWrapper>
+* // Children injection mode
+* export function UserProfileWithChildren(props: { id: number }) {
+*   return (
+*     <FaasDataWrapper<User>
+*       action="user/get"
+*       params={{ id: props.id }}
+*       loading={<div>Loading user...</div>}
+*     >
+*       <UserView />
+*     </FaasDataWrapper>
+*   )
 * }
 * ```
 */
@@ -81,11 +156,27 @@ function FaasDataWrapper(props) {
 	});
 }
 /**
-* HOC to wrap a component with FaasDataWrapper and Loading
+* Wrap a component with {@link FaasDataWrapper} and its Ant Design loading fallback.
+*
+* @template PathOrData - Action path or response data type used for inference.
+* @template TComponentProps - Component props including injected Faas data fields.
+* @param {React.FC<TComponentProps & Record<string, any>>} Component - Component that consumes injected Faas data props.
+* @param {FaasDataWrapperProps<PathOrData>} faasProps - Request configuration forwarded to {@link FaasDataWrapper}.
+* @returns Higher-order component that injects Faas data props.
 *
 * @example
 * ```tsx
-* const MyComponent = withFaasData(({ data }) => <div>{data.name}</div>, { action: 'test', params: { a: 1 } })
+* import { withFaasData } from '@faasjs/ant-design'
+*
+* const UserCard = withFaasData(
+*   ({ data, error, reload }) =>
+*     error ? (
+*       <a onClick={() => reload()}>Retry</a>
+*     ) : (
+*       <div>{data.name}</div>
+*     ),
+*   { action: 'user/get', params: { id: 1 } },
+* )
 * ```
 */
 function withFaasData(Component, faasProps) {
@@ -131,17 +222,29 @@ const baseTheme = {
 	},
 	Link: { style: {} }
 };
+/**
+* React context storing the resolved FaasJS Ant Design theme.
+*/
 const ConfigContext = (0, react.createContext)({ theme: baseTheme });
 /**
-* Config for `@faasjs/ant-design` components.
+* Provide theme overrides and optional FaasJS client initialization for descendants.
+*
+* Theme overrides are merged with the built-in defaults. When `theme.lang` is omitted, the
+* provider infers a default language from `navigator.language`.
+*
+* @param {ConfigProviderProps} props - Theme overrides and optional FaasJS client configuration.
 *
 * @example
 * ```tsx
-* import { ConfigProvider } from '@faasjs/ant-design'
+* import { Blank, ConfigProvider } from '@faasjs/ant-design'
 *
-* <ConfigProvider theme={{ common: { blank: 'Empty' } }}>
-*   <Blank />
-* </ConfigProvider>
+* export function Page() {
+*   return (
+*     <ConfigProvider theme={{ common: { blank: 'Empty' } }}>
+*       <Blank />
+*     </ConfigProvider>
+*   )
+* }
 * ```
 */
 function ConfigProvider(props) {
@@ -162,24 +265,60 @@ function ConfigProvider(props) {
 		children: props.children
 	});
 }
+/**
+* Read the current `@faasjs/ant-design` config context.
+*
+* @returns Current config context value containing the resolved theme.
+*
+* @example
+* ```tsx
+* import { Blank, ConfigProvider, useConfigContext } from '@faasjs/ant-design'
+*
+* function EmptyState() {
+*   const { theme } = useConfigContext()
+*
+*   return <span>{theme.common.blank}</span>
+* }
+*
+* export function Page() {
+*   return (
+*     <ConfigProvider theme={{ common: { blank: 'N/A' } }}>
+*       <EmptyState />
+*     </ConfigProvider>
+*   )
+* }
+* ```
+*/
 function useConfigContext() {
 	return (0, react.useContext)(ConfigContext);
 }
 //#endregion
 //#region src/Drawer.tsx
 /**
-* Hook style drawer
+* Create a hook-managed Ant Design drawer instance.
+*
+* The returned setter merges partial updates into the current drawer props instead of replacing the
+* entire state object.
+*
+* @param {DrawerProps} [init] - Initial drawer props.
+* @returns Hook-managed drawer element, current props, and a state-merging setter.
 *
+* @example
 * ```tsx
+* import { useDrawer } from '@faasjs/ant-design'
+* import { Button } from 'antd'
+*
 * function Example() {
 *   const { drawer, setDrawerProps } = useDrawer()
 *
-*   return <>
-*     <Button onClick={ () => setDrawerProps(prev => ({ open: !prev.open})) }>
-*       Toggle
-*     </Button>
-*     {drawer}
-*   </>
+*   return (
+*     <>
+*       <Button onClick={() => setDrawerProps({ open: true, title: 'Details', children: <div>Content</div> })}>
+*         Open
+*       </Button>
+*       {drawer}
+*     </>
+*   )
 * }
 * ```
 */
@@ -224,6 +363,24 @@ function ErrorChildren(props) {
 }
 /**
 * Styled error boundary.
+*
+* When `errorChildren` is not provided, the fallback UI renders an Ant Design `Alert` containing
+* the captured error message and description.
+*
+* @param {ErrorBoundaryProps} props - Error boundary props forwarded to the underlying React implementation.
+*
+* @example
+* ```tsx
+* import { ErrorBoundary } from '@faasjs/ant-design'
+*
+* export function Page() {
+*   return (
+*     <ErrorBoundary>
+*       <DangerousWidget />
+*     </ErrorBoundary>
+*   )
+* }
+* ```
 */
 function ErrorBoundary(props) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_faasjs_react.ErrorBoundary, {
@@ -234,16 +391,30 @@ function ErrorBoundary(props) {
 //#endregion
 //#region src/Modal.tsx
 /**
-* Hook style modal
+* Create a hook-managed Ant Design modal instance.
+*
+* The returned setter merges partial updates into the current modal props instead of replacing the
+* entire state object.
 *
+* @param {ModalProps} [init] - Initial modal props.
+* @returns Hook-managed modal element, current props, and a state-merging setter.
+*
+* @example
 * ```tsx
+* import { useModal } from '@faasjs/ant-design'
+* import { Button } from 'antd'
+*
 * function Example() {
 *   const { modal, setModalProps } = useModal()
 *
-*   return <>
-*     <Button onClick={() => setModalProps({ open: true })}>Open Modal</Button>
-*     {modal}
-*   </>
+*   return (
+*     <>
+*       <Button onClick={() => setModalProps({ open: true, title: 'Delete', children: 'Are you sure?' })}>
+*         Open Modal
+*       </Button>
+*       {modal}
+*     </>
+*   )
 * }
 * ```
 */
@@ -273,6 +444,9 @@ function useModal(init) {
 }
 //#endregion
 //#region src/useApp.ts
+/**
+* Shared context storing message, notification, modal, and drawer helpers.
+*/
 const AppContext = (0, _faasjs_react.createSplittingContext)([
 	"message",
 	"notification",
@@ -282,12 +456,38 @@ const AppContext = (0, _faasjs_react.createSplittingContext)([
 	"setDrawerProps"
 ]);
 /**
-* Get app context.
+* Read app-level services exposed by the root `App` component.
 *
-* ```ts
-* import { useApp } from '@faasjs/ant-design'
+* @template NewT - Narrowed app context shape to read from `AppContext`.
+* @returns Read-only app context value.
 *
-* const { message, notification, setModalProps, setDrawerProps } = useApp()
+* @example
+* ```tsx
+* import { App, useApp } from '@faasjs/ant-design'
+* import { Button } from 'antd'
+*
+* function Page() {
+*   const { message, setModalProps } = useApp()
+*
+*   return (
+*     <Button
+*       onClick={() => {
+*         message.success('Saved')
+*         setModalProps({ open: true, title: 'Done', children: 'Profile updated.' })
+*       }}
+*     >
+*       Save
+*     </Button>
+*   )
+* }
+*
+* export function Root() {
+*   return (
+*     <App>
+*       <Page />
+*     </App>
+*   )
+* }
 * ```
 */
 function useApp() {
@@ -306,25 +506,25 @@ function RoutesApp(props) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(react_jsx_runtime.Fragment, { children: props.children });
 }
 /**
-* App component with Ant Design & FaasJS
+* Render the root provider shell for a FaasJS Ant Design application.
+*
+* `App` initializes Ant Design message and notification APIs, exposes hook-managed modal and
+* drawer state through {@link AppContext}, wraps descendants with {@link ErrorBoundary}, and
+* optionally mounts React Router's `BrowserRouter`.
 *
-* - Based on Ant Design's [ConfigProvider](https://ant.design/components/config-provider/).
-* - Integrated Ant Design's [Message](https://ant.design/components/message/) and [Notification](https://ant.design/components/notification/).
-* - Based on FaasJS's [ConfigProvider](https://faasjs.com/doc/ant-design/#configprovider).
-* - Integrated FaasJS's [Modal](https://faasjs.com/doc/ant-design/#usemodal), [Drawer](https://faasjs.com/doc/ant-design/#usedrawer) and [ErrorBoundary](https://faasjs.com/doc/ant-design/#errorboundary).
-* - Integrated React Router's [BrowserRouter](https://api.reactrouter.com/v7/interfaces/react_router.BrowserRouterProps.html).
+* @param {AppProps} props - App shell props including providers, routing, and error handling options.
 *
 * @example
 * ```tsx
 * import { App } from '@faasjs/ant-design'
 *
-* export default function () {
+* export default function Page() {
 *   return (
 *     <App
-*      configProviderProps={{}} // https://ant.design/components/config-provider/#API
-*      browserRouterProps={{}} // https://api.reactrouter.com/v7/interfaces/react_router.BrowserRouterProps.html
-*      errorBoundaryProps={{}} // https://faasjs.com/doc/ant-design/#errorboundary
-*      faasConfigProviderProps={{}} // https://faasjs.com/doc/ant-design/#configprovider
+*       configProviderProps={{}}
+*       browserRouterProps={{}}
+*       errorBoundaryProps={{}}
+*       faasConfigProviderProps={{}}
 *     >
 *       <div>content</div>
 *     </App>
@@ -335,8 +535,8 @@ function RoutesApp(props) {
 function App(props) {
 	const [messageApi, messageContextHolder] = antd.message.useMessage();
 	const [notificationApi, notificationContextHolder] = antd.notification.useNotification();
-	const { modal, modalProps, setModalProps } = useModal();
-	const { drawer, drawerProps, setDrawerProps } = useDrawer();
+	const { modal, modalProps, setModalProps } = useModal({ destroyOnHidden: true });
+	const { drawer, drawerProps, setDrawerProps } = useDrawer({ destroyOnHidden: true });
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_faasjs_react.OptionalWrapper, {
 		condition: !!props.configProviderProps,
 		Wrapper: antd.ConfigProvider,
@@ -382,15 +582,20 @@ function App(props) {
 //#endregion
 //#region src/Blank.tsx
 /**
-* Blank component.
+* Render a disabled placeholder when a value is empty.
 *
-* If value is undefined or null, return text, otherwise return value.
+* Empty values include `undefined`, `null`, empty strings, and empty arrays.
+*
+* @param {BlankProps} [options] - Placeholder text and value to render.
+* @returns Rendered value or the configured placeholder text.
 *
 * @example
 * ```tsx
 * import { Blank } from '@faasjs/ant-design'
 *
-* <Blank value={undefined} text="Empty" />
+* export function FieldPreview() {
+*   return <Blank value={undefined} text="Empty" />
+* }
 * ```
 */
 function Blank(options) {
@@ -403,17 +608,14 @@ function Blank(options) {
 //#endregion
 //#region src/data.ts
 /**
-* Converts an identifier string to a title case string.
-*
-* This function takes an identifier string with words separated by underscores,
-* capitalizes the first letter of each word, and joins them together without spaces.
+* Convert a snake_case, kebab-case, or spaced identifier into a title-style label.
 *
-* @param id - The identifier string to convert.
-* @returns The converted title case string.
+* @param {string | number} id - Identifier to convert.
+* @returns Generated label string.
 *
 * @example
-* ```typescript
-* idToTitle('example_id'); // returns 'ExampleId'
+* ```ts
+* idToTitle('example_id') // 'Example Id'
 * ```
 */
 function idToTitle(id) {
@@ -422,7 +624,24 @@ function idToTitle(id) {
 	return splitted.charAt(0).toUpperCase() + splitted.slice(1);
 }
 /**
-* convert string[] or number[] to { label, value }[]
+* Normalize primitive options into explicit `{ label, value }` objects.
+*
+* String and number options are converted with {@link idToTitle}, while pre-shaped option objects
+* are returned as-is.
+*
+* @param {BaseOption[]} options - Raw option list to normalize.
+* @returns Normalized option list.
+*
+* @example
+* ```ts
+* import { transferOptions } from '@faasjs/ant-design'
+*
+* transferOptions(['draft', { label: 'Published', value: 'published' }])
+* // [
+* //   { label: 'Draft', value: 'draft' },
+* //   { label: 'Published', value: 'published' },
+* // ]
+* ```
 */
 function transferOptions(options) {
 	if (!options) return [];
@@ -431,6 +650,25 @@ function transferOptions(options) {
 		value: item
 	});
 }
+/**
+* Normalize raw values into the runtime shape expected by FaasJS Ant Design components.
+*
+* Primitive strings such as `'null'` and `'undefined'` become `null`, comma-delimited array
+* strings are split into arrays, and date or time values are converted to `dayjs` objects.
+*
+* @param {FaasItemType | null | undefined} type - Target field type.
+* @param {any} value - Raw value to normalize.
+* @returns Normalized value for rendering or form initialization.
+*
+* @example
+* ```ts
+* import { transferValue } from '@faasjs/ant-design'
+*
+* transferValue('number', '42') // 42
+* transferValue('boolean', 'true') // true
+* transferValue('string[]', 'a,b') // ['a', 'b']
+* ```
+*/
 function transferValue(type, value) {
 	if (!type) type = "string";
 	if (!type.endsWith("[]") && (typeof value === "undefined" || value === null || value === "" || value === "null" || value === "undefined")) return null;
@@ -456,15 +694,27 @@ function transferValue(type, value) {
 	return value;
 }
 /**
-* Clone a UnionFaasItemElement with the given props.
+* Clone a {@link UnionFaasItemElement} with FaasJS injection props.
+*
+* React elements are cloned directly, while component references are first wrapped with
+* `createElement`.
 *
-* This function takes a UnionFaasItemElement and props, and returns a cloned element.
-* If the provided element is a valid React element, it clones it with the new props.
-* Otherwise, it creates a new element from the provided element and props.
+* @param {UnionFaasItemElement} element - Element or component to clone.
+* @param {any} props - Injection props such as `scene`, `value`, `values`, and `index`.
+* @returns Cloned React element ready for rendering.
 *
-* @param element - The UnionFaasItemElement to be cloned.
-* @param props - The props to be applied to the cloned element.
-* @returns The cloned element with the applied props.
+* @example
+* ```tsx
+* import { cloneUnionFaasItemElement, type UnionFaasItemElement } from '@faasjs/ant-design'
+*
+* const Cell: UnionFaasItemElement<string> = ({ value }) => <span>{value}</span>
+*
+* const element = cloneUnionFaasItemElement(Cell, {
+*   scene: 'table',
+*   value: 'Hello',
+*   index: 0,
+* })
+* ```
 */
 function cloneUnionFaasItemElement(element, props) {
 	return (0, react.cloneElement)((0, react.isValidElement)(element) ? element : (0, react.createElement)(element), props);
@@ -547,31 +797,41 @@ function DescriptionItemContent(props) {
 }
 DescriptionItemContent.displayName = "DescriptionItemContent";
 /**
-* Description component
+* Render an Ant Design description list from FaasJS item metadata.
 *
-* - Based on [Ant Design Descriptions](https://ant.design/components/descriptions/).
+* The component can render a local `dataSource` directly or resolve one through `faasData`, and
+* it applies the same item type normalization helpers used by the form and table components.
+*
+* @template T - Data record shape rendered by the component.
+* @param {DescriptionProps<T>} props - Description props including items, data source, and optional Faas data config.
+* @throws {Error} When an entry in `extendTypes` omits both `children` and `render`.
 *
 * @example
 * ```tsx
 * import { Description } from '@faasjs/ant-design'
 *
-* <Description
-*   title="Title"
-*   items={[
-*     {
-*       id: 'id',
-*       title: 'Title',
-*       type: 'string',
-*     },
-*   ]}
-*   dataSource={{ id: 'value' }}
-* />
+* export function Detail() {
+*   return (
+*     <Description
+*       title="Title"
+*       items={[
+*         {
+*           id: 'id',
+*           title: 'Title',
+*           type: 'string',
+*         },
+*       ]}
+*       dataSource={{ id: 'value' }}
+*     />
+*   )
+* }
 * ```
 */
-function Description({ faasData, dataSource, renderTitle, extendTypes, ...props }) {
+function Description(props) {
+	const { faasData, dataSource, renderTitle, extendTypes, ...descriptionProps } = props;
 	if (faasData && !dataSource) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FaasDataWrapper, {
 		render: ({ data }) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Description, {
-			...props,
+			...descriptionProps,
 			dataSource: data,
 			...renderTitle ? { renderTitle } : {},
 			...extendTypes ? { extendTypes } : {}
@@ -579,9 +839,9 @@ function Description({ faasData, dataSource, renderTitle, extendTypes, ...props
 		...faasData
 	});
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(antd.Descriptions, {
-		...props,
-		title: typeof renderTitle === "function" ? renderTitle(dataSource) : props.title,
-		items: props.items.filter((item) => item && !(item.descriptionChildren === null || item.children === null || item.descriptionRender === null || item.render === null) && (!item.if || item.if(dataSource))).map((item) => ({
+		...descriptionProps,
+		title: typeof renderTitle === "function" ? renderTitle(dataSource) : descriptionProps.title,
+		items: descriptionProps.items.filter((item) => item && !(item.descriptionChildren === null || item.children === null || item.descriptionRender === null || item.render === null) && (!item.if || item.if(dataSource))).map((item) => ({
 			...item,
 			key: item.id,
 			label: item.title ?? idToTitle(item.id),
@@ -633,20 +893,30 @@ function processProps(propsCopy, config) {
 	return propsCopy;
 }
 /**
-* FormItem
+* Render a FaasJS-aware Ant Design form field or nested field group.
+*
+* The component derives default labels from `id`, applies required validation messages from the
+* active theme, supports surface-specific union renderers, and can render nested `object` or
+* `object[]` field structures.
 *
-* - Based on [Ant Design Form.Item](https://ant.design/components/form#formitem).
-* - Can be used without [Form](https://faasjs.com/doc/ant-design/#form).
+* @template T - Value type rendered or edited by the form item.
+* @param {FormItemProps<T>} props - Form item props including field metadata, rules, and custom renderers.
 *
 * @example
 * ```tsx
-* // use inline type
-* <FormItem type='string' id='name' />
+* import { FormItem } from '@faasjs/ant-design'
+* import { Input } from 'antd'
 *
-* // use custom type
-* <FormItem id='password'>
-*   <Input.Password />
-* </>
+* export function AccountFields() {
+*   return (
+*     <>
+*       <FormItem id="name" type="string" />
+*       <FormItem id="password">
+*         <Input.Password />
+*       </FormItem>
+*     </>
+*   )
+* }
 * ```
 */
 function FormItem(props) {
@@ -895,108 +1165,189 @@ function isFormItemProps(item) {
 	return item.id !== void 0;
 }
 /**
-* Form component with Ant Design & FaasJS
+* Render a data-aware Ant Design form with optional FaasJS submission helpers.
+*
+* The component normalizes `initialValues` with {@link transferValue}, renders item definitions
+* through {@link FormItem}, and can either delegate submission to a custom `onFinish` handler or
+* the built-in FaasJS request flow configured by `faas`.
+*
+* @template Values - Form values shape.
+* @param {FormProps<Values>} props - Form props including items, submit behavior, and FaasJS integration.
+*
+* @example
+* ```tsx
+* import { Form } from '@faasjs/ant-design'
+*
+* export function ProfileForm() {
+*   return (
+*     <Form
+*       items={[
+*         { id: 'name', required: true },
+*         { id: 'email', required: true },
+*       ]}
+*       onFinish={async (values) => {
+*         console.log(values)
+*       }}
+*     />
+*   )
+* }
+* ```
+*
+* @example
+* ```tsx
+* import { Form } from '@faasjs/ant-design'
 *
-* - Based on [Ant Design Form](https://ant.design/components/form/).
+* export function CreateUserForm() {
+*   return (
+*     <Form
+*       initialValues={{ role: 'user' }}
+*       items={[
+*         { id: 'name', required: true },
+*         { id: 'role', options: ['user', 'admin'] },
+*       ]}
+*       faas={{
+*         action: 'user/create',
+*         params: (values) => ({
+*           role: values.role || 'user',
+*         }),
+*       }}
+*     />
+*   )
+* }
+* ```
 */
 function Form(props) {
 	const [loading, setLoading] = (0, react.useState)(false);
-	const [computedProps, setComputedProps] = (0, react.useState)();
-	const [submit, setSubmit] = (0, react.useState)();
+	const [antdProps, setAntdProps] = (0, react.useState)();
+	const [submit, setSubmit] = (0, react.useState)(props.submit === false ? false : {});
+	const [items, setItems] = (0, react.useState)([]);
 	const config = useConfigContext();
 	const [extendTypes, setExtendTypes] = (0, react.useState)();
 	const [form] = antd.Form.useForm(props.form);
 	const [initialValues, setInitialValues] = (0, react.useState)(props.initialValues || Object.create(null));
+	const [onFinish, setOnFinish] = (0, react.useState)();
 	(0, _faasjs_react.useEqualEffect)(() => {
-		const { submit, ...propsCopy } = {
-			...props,
-			form
-		};
-		let nextInitialValues = propsCopy.initialValues;
-		if (typeof submit !== "undefined") setSubmit(submit);
-		if (propsCopy.initialValues && propsCopy.items?.length) {
-			for (const key in propsCopy.initialValues) propsCopy.initialValues[key] = transferValue(propsCopy.items.find((item) => isFormItemProps(item) && item.id === key)?.type, propsCopy.initialValues[key]);
-			nextInitialValues = propsCopy.initialValues;
-			setInitialValues(propsCopy.initialValues);
-			delete propsCopy.initialValues;
-		}
-		if (propsCopy.items?.length) {
-			for (const item of propsCopy.items) if (isFormItemProps(item) && item.if) item.hidden = !item.if(nextInitialValues || Object.create(null));
+		if (props.onFinish) {
+			setOnFinish(() => async (values) => {
+				if (!props.onFinish) return;
+				setLoading(true);
+				try {
+					return await props.onFinish(values);
+				} finally {
+					setLoading(false);
+				}
+			});
+			return;
 		}
-		const submitTo = typeof submit === "object" ? submit.to : void 0;
-		if (propsCopy.onFinish) {
-			const originOnFinish = propsCopy.onFinish;
-			propsCopy.onFinish = async (values) => {
+		if (props.faas?.action) {
+			setOnFinish(() => async (values) => {
+				if (!props.faas?.action) return;
 				setLoading(true);
+				let submitValues = values;
 				try {
-					if (submitTo?.action) await originOnFinish(values, async (nextValues) => (0, _faasjs_react.faas)(submitTo.action, submitTo.params ? {
-						...nextValues,
-						...submitTo.params
-					} : nextValues));
-					else await originOnFinish(values);
+					if (props.faas?.transformValues) submitValues = await props.faas.transformValues(values);
+					const extraParams = typeof props.faas?.params === "function" ? props.faas.params(submitValues) : props.faas.params;
+					if (extraParams) submitValues = {
+						...submitValues,
+						...extraParams
+					};
+					const result = await (0, _faasjs_react.faas)(props.faas.action, submitValues);
+					props.faas.onSuccess?.(result, submitValues);
+					return result;
 				} catch (error) {
-					console.error(error);
+					props.faas.onError?.(error, submitValues);
+					throw error;
+				} finally {
+					props.faas.onFinally?.();
+					setLoading(false);
 				}
-				setLoading(false);
-			};
-		} else if (submitTo?.action) propsCopy.onFinish = async (values) => {
-			setLoading(true);
-			return (0, _faasjs_react.faas)(submitTo.action, submitTo.params ? {
-				...values,
-				...submitTo.params
-			} : values).then((result) => {
-				submitTo.then?.(result);
-				return result;
-			}).catch((error) => {
-				submitTo.catch?.(error);
-				return Promise.reject(error);
-			}).finally(() => {
-				submitTo.finally?.();
-				setLoading(false);
 			});
-		};
-		if (propsCopy.extendTypes) {
-			setExtendTypes(propsCopy.extendTypes);
-			delete propsCopy.extendTypes;
+			return;
 		}
-		setComputedProps(propsCopy);
-	}, [form, props]);
+		setOnFinish(void 0);
+	}, [props.onFinish, props.faas]);
+	(0, _faasjs_react.useEqualEffect)(() => {
+		setExtendTypes(props.extendTypes);
+	}, [props.extendTypes]);
+	(0, _faasjs_react.useEqualEffect)(() => {
+		setSubmit(props.submit === false ? false : props.submit || {});
+	}, [props.submit]);
+	(0, _faasjs_react.useEqualEffect)(() => {
+		const nextInitialValues = props.initialValues ? JSON.parse(JSON.stringify(props.initialValues)) : Object.create(null);
+		for (const key in nextInitialValues) nextInitialValues[key] = transferValue(props.items?.find((item) => isFormItemProps(item) && item.id === key)?.type, nextInitialValues[key]);
+		if (props.items?.length) setItems(props.items.map((item) => {
+			if (!isFormItemProps(item) || !item.if) return item;
+			return {
+				...item,
+				hidden: !item.if(nextInitialValues)
+			};
+		}));
+		else setItems([]);
+		if (props.initialValues) {
+			setInitialValues(nextInitialValues);
+			return;
+		}
+		setInitialValues(null);
+	}, [props.initialValues, props.items]);
+	(0, _faasjs_react.useEqualEffect)(() => {
+		const propsCopy = { ...props };
+		delete propsCopy.onFinish;
+		delete propsCopy.faas;
+		delete propsCopy.extendTypes;
+		delete propsCopy.submit;
+		delete propsCopy.items;
+		delete propsCopy.initialValues;
+		setAntdProps(propsCopy);
+	}, [props]);
 	const onValuesChange = (0, _faasjs_react.useEqualCallback)((changedValues, allValues) => {
 		console.debug("Form:onValuesChange", changedValues, allValues);
 		if (props.onValuesChange) props.onValuesChange(changedValues, allValues);
-		if (!props.items) return;
+		if (!items.length) return;
 		for (const key in changedValues) {
-			const item = computedProps?.items?.find((i) => isFormItemProps(i) && i.id === key);
+			const item = items.find((i) => isFormItemProps(i) && i.id === key);
 			if (item?.onValueChange) item.onValueChange(changedValues[key], allValues, form);
 		}
-	}, [computedProps]);
+	}, [
+		items,
+		props.onValuesChange,
+		form
+	]);
 	(0, _faasjs_react.useEqualEffect)(() => {
 		if (!initialValues) return;
 		console.debug("Form:initialValues", initialValues);
 		form.setFieldsValue(initialValues);
 		setInitialValues(null);
-	}, [form, initialValues]);
-	if (!computedProps) return null;
+	}, [
+		form,
+		initialValues,
+		items
+	]);
+	if (!antdProps) return null;
+	const submitButtonProps = typeof submit === "object" ? submit.buttonProps : void 0;
+	const submitButtonLoading = loading ? true : submitButtonProps?.loading ?? false;
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(antd.Form, {
-		...computedProps,
+		...antdProps,
+		form,
+		onFinish,
 		onValuesChange,
 		children: [
-			computedProps.beforeItems,
-			computedProps.items?.map((item) => {
+			props.beforeItems,
+			items.map((item) => {
 				if (isFormItemProps(item)) return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(FormItem, {
 					...item,
 					...extendTypes ? { extendTypes } : {}
 				}, item.id);
 				return item;
 			}),
-			computedProps.children,
+			props.children,
 			typeof submit !== "boolean" && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(antd.Button, {
+				...submitButtonProps,
 				htmlType: "submit",
-				type: "primary",
-				loading,
+				type: submitButtonProps?.type || "primary",
+				loading: submitButtonLoading,
 				children: submit?.text || config.theme.Form.submit.text
 			}),
-			computedProps.footer
+			props.footer
 		]
 	});
 }
@@ -1010,15 +1361,27 @@ Form.Provider = antd.Form.Provider;
 //#endregion
 //#region src/Link.tsx
 /**
-* Link component with button
+* Render a navigation-aware link or button.
+*
+* Internal links are pushed through React Router, while links with `_blank` targets are opened
+* with `window.open`.
+*
+* @param {LinkProps} props - Link props controlling navigation target, rendering mode, and button behavior.
 *
 * @example
 * ```tsx
-* // pure link
-* <Link href="/">Home</Link>
+* import { Link } from '@faasjs/ant-design'
 *
-* // link with button
-* <Link href="/" button={{ type:'primary' }}>Home</Link>
+* export function Navigation() {
+*   return (
+*     <>
+*       <Link href="/">Home</Link>
+*       <Link href="/users/new" button={{ type: 'primary' }}>
+*         Create User
+*       </Link>
+*     </>
+*   )
+* }
 * ```
 */
 function Link(props) {
@@ -1075,6 +1438,23 @@ function Link(props) {
 }
 //#endregion
 //#region src/Routers.tsx
+/**
+* Default 404 route element that uses the configured localized title.
+*
+* @example
+* ```tsx
+* import { PageNotFound, Routes } from '@faasjs/ant-design'
+*
+* export function AppRoutes() {
+*   return (
+*     <Routes
+*       routes={[{ path: '/', element: <div>Home</div> }]}
+*       notFound={<PageNotFound />}
+*     />
+*   )
+* }
+* ```
+*/
 function PageNotFound() {
 	const { theme } = useConfigContext();
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(antd.Result, {
@@ -1083,22 +1463,31 @@ function PageNotFound() {
 	});
 }
 /**
-* Routes with lazy loading and 404 page.
+* Render React Router routes with lazy-page support and a default 404 route.
+*
+* The wrapper adds a catch-all route automatically and uses an Ant Design `Skeleton` fallback when
+* `fallback` is not provided.
+*
+* @param {RoutesProps} props - Route definitions and optional fallback or 404 elements.
 *
 * @example
 * ```tsx
 * import { Routes, lazy } from '@faasjs/ant-design'
 * import { BrowserRouter } from 'react-router-dom'
 *
-* export function App () {
-*   return <BrowserRouter>
-*     <Routes routes={[
-*       {
-*         path: '/',
-*         page: lazy(() => import('./pages/home'))
-*       }
-*     ]} />
-*   </BrowserRouter>
+* export function App() {
+*   return (
+*     <BrowserRouter>
+*       <Routes
+*         routes={[
+*           {
+*             path: '/',
+*             page: lazy(() => import('./pages/home')),
+*           },
+*         ]}
+*       />
+*     </BrowserRouter>
+*   )
 * }
 * ```
 */
@@ -1139,12 +1528,39 @@ function processValue(item, value) {
 	return transferred;
 }
 /**
-* Table component with Ant Design & FaasJS
+* Render an Ant Design table from FaasJS item metadata.
+*
+* The component can render local `dataSource` rows or resolve remote rows through `faasData`. It
+* also generates default filters and sorters for built-in item types unless you disable them with
+* the corresponding Ant Design column props.
 *
-* - Based on [Ant Design Table](https://ant.design/components/table/).
-* - Support FaasJS injection.
-* - Auto generate filter dropdown (disable with `filterDropdown: false`).
-* - Auto generate sorter (disable with `sorter: false`).
+* @template T - Row record type rendered by the table.
+* @template ExtendTypes - Additional item prop shape accepted by `items`.
+* @param {TableProps<T, ExtendTypes>} props - Table props including columns, data source, and optional Faas data config.
+* @throws {Error} When an entry in `extendTypes` omits both `children` and `render`.
+*
+* @example
+* ```tsx
+* import { Table } from '@faasjs/ant-design'
+*
+* const rows = [
+*   { id: 1, name: 'Alice', active: true },
+*   { id: 2, name: 'Bob', active: false },
+* ]
+*
+* export function UserTable() {
+*   return (
+*     <Table
+*       rowKey="id"
+*       dataSource={rows}
+*       items={[
+*         { id: 'name', title: 'Name' },
+*         { id: 'active', type: 'boolean', title: 'Active' },
+*       ]}
+*     />
+*   )
+* }
+* ```
 */
 function Table(props) {
 	const [columns, setColumns] = (0, react.useState)();
@@ -1530,28 +1946,32 @@ function FaasDataTable({ props, columns, data, params, reload, loading }) {
 //#endregion
 //#region src/Tabs.tsx
 /**
-* Tabs component with Ant Design & FaasJS
+* Render an Ant Design tabs wrapper that accepts FaasJS-style tab definitions.
+*
+* Missing `key` and `label` values are derived from each tab's `id` and `title`.
 *
-* - Based on [Ant Design Tabs](https://ant.design/components/tabs/).
-* - Support auto skip null/false tab item.
-* - Support `id` as key and label.
+* @param {TabsProps} props - Tabs props including tab items and Ant Design tab options.
 *
 * @example
 * ```tsx
 * import { Tabs } from '@faasjs/ant-design'
 *
-* <Tabs
-*   items={[
-*     {
-*       id: 'id',
-*       children: 'content',
-*     },
-*     1 === 0 && {
-*       id: 'hidden',
-*       children: 'content',
-*     },
-*   ]}
-* />
+* export function Page() {
+*   return (
+*     <Tabs
+*       items={[
+*         {
+*           id: 'id',
+*           children: 'content',
+*         },
+*         1 === 0 && {
+*           id: 'hidden',
+*           children: 'content',
+*         },
+*       ]}
+*     />
+*   )
+* }
 * ```
 */
 function Tabs(props) {
@@ -1567,21 +1987,24 @@ function Tabs(props) {
 //#endregion
 //#region src/Title.tsx
 /**
-* Title is used to change the title of the page
+* Update `document.title` and optionally render the title inline.
 *
-* Return null by default.
+* The component returns `null` by default and is often used only for its side effect.
 *
-* ```tsx
-* // return null
-* <Title title='hi' /> // => change the document.title to 'hi'
-* <Title title={['a', 'b']} /> // => change the document.title to 'a - b'
+* @param {TitleProps} props - Title props controlling document title updates and optional inline rendering.
 *
-* // return h1
-* <Title title='hi' h1 /> // => <h1>hi</h1>
-* <Title title={['a', 'b']} h1 /> // => <h1>a</h1>
+* @example
+* ```tsx
+* import { Title } from '@faasjs/ant-design'
 *
-* // return children
-* <Title title='hi'><CustomTitle /></Title> // => <CustomTitle />
+* export function DetailPage() {
+*   return (
+*     <>
+*       <Title title={['Orders', 'Detail']} h1 />
+*       <div>...</div>
+*     </>
+*   )
+* }
 * ```
 */
 function Title(props) {
@@ -1605,12 +2028,20 @@ function Title(props) {
 //#endregion
 //#region src/useThemeToken.ts
 /**
-* Hook to retrieve the theme token from the Ant Design theme configuration.
+* Read the current Ant Design theme token.
 *
-* This function uses the `theme.useToken` method to get the current theme configuration
-* and returns the `token` property from the configuration.
+* @returns Ant Design global token object for the active theme.
 *
-* @returns {GlobalToken} The theme token from the Ant Design theme configuration.
+* @example
+* ```tsx
+* import { useThemeToken } from '@faasjs/ant-design'
+*
+* function PrimarySwatch() {
+*   const { colorPrimary } = useThemeToken()
+*
+*   return <div style={{ width: 24, height: 24, background: colorPrimary }} />
+* }
+* ```
 */
 function useThemeToken() {
 	return antd.theme.useToken().token;