musae 1.3.1-beta.2 → 1.3.1-beta.21

package/dist/types/form.d.ts

@@ -3,92 +3,119 @@ import type { FieldsValue, Form, Rule, FORM_TOKEN, ChangeHandler } from "../util
 import type { Nullable, Partialable } from "@aiszlab/relax/types";
 import type { ComponentProps } from "./element";
 /**
- * form hook return
+ * @zh 表单实例 hook 的返回值。
+ * @en Return value of the form instance hook.
  */
 interface UsedForm<T extends FieldsValue> {
     /**
-     * set field value
+     * @zh 设置指定字段的值，并清除该字段的校验错误。
+     * @en Set a field value and clear that field's validation error.
      */
     setFieldValue(name: keyof T, value: T[keyof T]): void;
     /**
-     * set fields value
-     * @description set multiple fields value
+     * @zh 批量设置字段值，并清除这些字段的校验错误。
+     * @en Set multiple field values and clear their validation errors.
      */
     setFieldsValue(value: Partial<T>): void;
     /**
-     * reset fields value and clear errors
+     * @zh 将字段值重置为 `defaultValue`，并清除所有校验错误。
+     * @en Reset field values to `defaultValue` and clear all validation errors.
      */
     reset(): void;
     /**
-     * clear fields value and clear errors
+     * @zh 清空字段值并清除所有校验错误。
+     * @en Clear field values and all validation errors.
      */
     clear(): void;
     /**
-     * validate
+     * @zh 校验所有已注册字段；全部通过时返回 `true`。
+     * @en Validate all registered fields; resolve to `true` when all pass.
      */
     validate: () => Promise<boolean>;
     /**
-     * get field value
+     * @zh 获取指定字段当前值。
+     * @en Get the current value of a field.
      */
     getFieldValue: <FieldValue = T[keyof T]>(name: keyof T) => Partialable<FieldValue>;
     /**
-     * get fields value
+     * @zh 获取已注册字段的当前值。
+     * @en Get the current values of registered fields.
      */
     getFieldsValue: () => Partial<T>;
     /**
-     * form instance
+     * @zh 底层表单实例，供组件内部共享使用。
+     * @en Underlying form instance shared by the form components.
      */
     [FORM_TOKEN]: Form<T>;
 }
 /**
- * form hook props
+ * @zh 表单实例 hook 的配置参数。
+ * @en Configuration options for the form instance hook.
  */
 interface UsingForm<T extends FieldsValue> {
     /**
-     * form default value
+     * @zh 非受控表单的初始值，也作为调用 `reset()` 时恢复的值。
+     * @en Initial value for an uncontrolled form and the value restored by `reset()`.
      */
     defaultValue?: Partial<T>;
     /**
-     * registered form
+     * @zh 复用已有的表单实例；不传时会创建新实例。
+     * @en Reuse an existing form instance; a new instance is created when omitted.
      */
     form?: UsedForm<T>;
     /**
-     * change handler
+     * @zh 字段通过表单交互发生变化时调用，参数依次为已登记字段值和本次变更的字段名。
+     * @en Called when a field changes through form interaction, with registered field values and the names changed.
      */
     onChange?: ChangeHandler<T>;
     /**
-     * controlled form value
+     * @zh 受控表单的当前值；传入后由调用方负责更新该值。
+     * @en Current value of a controlled form; the caller is responsible for updating it.
      */
     value?: Partial<T>;
 }
 /**
- * form props
+ * @zh Form 组件的参数。
+ * @en Props for the Form component.
  */
 interface FormProps<T extends FieldsValue> extends ComponentProps {
     /**
-     * used form instance
-     * use `form` can control `Form` value
+     * @zh 表单布局形式
+     * @en Form layout mode
+     * @default "default"
+     */
+    layout?: FormLayout;
+    /**
+     * @zh 传入 `Form.useForm()` 创建的实例以复用或外部操作表单。
+     * @en Pass an instance from `Form.useForm()` to reuse or control the form externally.
      */
     form?: UsedForm<T>;
     /**
-     * children components
+     * @zh 表单内容，通常包含 `Form.Item` 等表单项。
+     * @en Form contents, usually including fields such as `Form.Item`.
      */
     children: ReactNode;
     /**
-     * form value change handler
+     * @zh 字段通过表单交互发生变化时调用，参数依次为已登记字段值和本次变更的字段名。
+     * @en Called when a field changes through form interaction, with registered field values and the names changed.
      */
     onChange?: ChangeHandler<T>;
     /**
-     * default value
+     * @zh 非受控表单的初始值，也作为调用 `form.reset()` 时恢复的值。
+     * @en Initial value for an uncontrolled form and the value restored by `form.reset()`.
      */
     defaultValue?: Partial<T>;
     /**
-     * controlled value
-     * @description
-     * if `value` is provided, `Form` will be controlled
+     * @zh 受控表单的当前值；传入后由调用方负责更新该值。
+     * @en Current value of a controlled form; the caller is responsible for updating it.
      */
     value?: Partial<T>;
 }
+/**
+ * @zh 表单布局形式
+ * @en Form layout mode
+ */
+type FormLayout = "default" | "inline";
 /**
  * typed form list
  */
@@ -130,47 +157,58 @@ interface TypedForm {
     useFormContext: UseFormContext;
 }
 /**
- * form item props
+ * @zh Form.Item 组件的参数。
+ * @en Props for the Form.Item component.
  */
 interface FormItemProps<T extends FieldsValue, FieldKey extends keyof T> {
     /**
-     * name
+     * @zh 对应表单数据中的字段名；省略时该项不与表单值绑定。
+     * @en Field name in the form data; when omitted, this item is not bound to a form value.
      */
     name?: FieldKey;
     /**
-     * required field
+     * @zh 标记该字段为必填，并用于显示必填状态。
+     * @en Mark the field as required and display its required state.
      */
     required?: boolean;
     /**
-     * class name
+     * @zh 应用于表单项根元素的额外类名。
+     * @en Additional class name applied to the form item root.
      */
     className?: string;
     /**
-     * style
+     * @zh 应用于表单项根元素的内联样式。
+     * @en Inline styles applied to the form item root.
      */
     style?: CSSProperties;
     /**
-     * supporting
+     * @zh 显示在字段下方的补充说明。
+     * @en Supporting text displayed below the field.
      */
     supporting?: ReactNode;
     /**
-     * label
+     * @zh 字段标签内容。
+     * @en Field label content.
      */
     label?: ReactNode;
     /**
-     * labelCol
+     * @zh 标签区域占用的栅格列数。
+     * @en Number of grid columns occupied by the label.
      */
     labelCol?: number;
     /**
-     * wrapperCol
+     * @zh 字段控件区域占用的栅格列数。
+     * @en Number of grid columns occupied by the field control.
      */
     wrapperCol?: number;
     /**
-     * children
+     * @zh 字段控件或其他表单项内容。
+     * @en Field control or other form item content.
      */
     children?: ReactNode;
     /**
-     * rules
+     * @zh 按顺序执行的字段校验规则。
+     * @en Validation rules run for this field.
      */
     rules?: Rule<T, FieldKey>[];
 }
@@ -235,4 +273,4 @@ interface FormListItemProps<T extends FieldsValue = {}> {
      */
     form?: UsedForm<T>;
 }
-export { FormProps, FormItemProps, TypedForm, FieldsValue, ContextValue, UsedForm, UsingForm, FormListField, FormListProps, FormContextValue, TypedFormList, FormListItemProps, UseFormContext, };
+export { FormProps, FormItemProps, TypedForm, FieldsValue, ContextValue, UsedForm, UsingForm, FormListField, FormListProps, FormContextValue, TypedFormList, FormListItemProps, UseFormContext, FormLayout, };

package/dist/types/input.d.ts

@@ -1,91 +1,84 @@
 import type { InputHTMLAttributes, ReactNode } from "react";
 import type { ComponentProps } from "./element";
+import type { VirtualElement } from "@floating-ui/dom";
 /**
- * @description
- * Variant
+ * @zh 输入框变体
+ * @en Input variant
  */
-export type Variant = "outlined" | "filled" | "standard";
+export type Variant = "outlined" | "filled";
 /**
- * @description
- * component props
+ * @zh 输入框组件属性
+ * @en Input component props
  */
-export interface InputProps extends Pick<InputHTMLAttributes<HTMLInputElement>, "onFocus" | "onBlur" | "name" | "value" | "disabled" | "onClick" | "maxLength" | "onKeyDown">, ComponentProps {
+export interface InputProps extends Pick<InputHTMLAttributes<HTMLInputElement>, "onFocus" | "onBlur" | "name" | "value" | "disabled" | "readOnly" | "onClick" | "maxLength" | "onKeyDown" | "role" | "aria-expanded" | "aria-controls" | "aria-activedescendant" | "aria-autocomplete">, ComponentProps {
     /**
-     * @description
-     * value
+     * @zh 输入框值
+     * @en Input value
      * @default void 0
      */
     value?: string;
     /**
-     * @description
-     * placeholder for input
+     * @zh 输入框占位符
+     * @en Input placeholder
      * @default void 0
      */
     placeholder?: string;
     /**
-     * @description
-     * variant for input, display different style
+     * @zh 输入框变体，展示不同样式
+     * @en Input variant for displaying different styles
      * @default "outlined"
      */
     variant?: Variant;
     /**
-     * @description
-     * leading node
+     * @default false
+     */
+    shaped?: boolean;
+    /**
+     * @zh 输入元素的附加类名
+     * @en Additional class name for the input element
+     */
+    inputClassName?: string;
+    /**
+     * @zh 前置节点
+     * @en Leading node
      * @default void 0
      */
     leading?: ReactNode;
     /**
-     * @description
-     * trailing node
+     * @zh 后置节点
+     * @en Trailing node
      * @default void 0
      */
     trailing?: ReactNode;
     /**
-     * @description
-     * input type
+     * @zh 输入框类型
+     * @en Input type
      * @default "text"
      */
     type?: "text" | "password" | "number";
     /**
-     * @description
-     * invalid
+     * @zh 是否无效
+     * @en Whether the input is invalid
      * @default false
      */
     invalid?: boolean;
     /**
-     * @description
-     * change handler
+     * @zh 值变更处理函数
+     * @en Value change handler
      * @default void 0
      */
     onChange?: (value: string) => void;
+    /**
+     * @zh 输入框标签
+     * @en Input label
+     */
+    label?: string;
 }
 /**
- * @description
- * label props
- */
-export interface LabelRenderProps {
-    focused: boolean;
-}
-/**
- * @description
- * input ref
+ * @zh 输入组件引用
+ * @en Input component ref
  */
-export interface InputRef {
-    /**
-     * @description
-     * focus
-     */
-    focus?: HTMLInputElement["focus"];
-    /**
-     * @description
-     * blur
-     */
-    blur?: HTMLInputElement["blur"];
-    /**
-     * @description
-     * select
-     */
-    select?: HTMLInputElement["select"];
+export interface InputRef extends Pick<HTMLInputElement, "blur" | "focus" | "select">, VirtualElement {
     /**
      * @zh 获取组件内部值
      * @en Get the current internal value

package/dist/types/menu.d.ts

@@ -120,11 +120,17 @@ export type MenuItem = ComponentProps & {
      */
     label?: ReactNode;
     /**
-     * @description
-     * prefix node
+     * @zh 后置内容
+     * @en Trailing content
+     * @default void 0
+     */
+    trailing?: ReactNode;
+    /**
+     * @zh 前置内容
+     * @en Leading content
      * @default void 0
      */
-    prefix?: ReactNode;
+    leading?: ReactNode;
     /**
      * @description
      * children
@@ -150,12 +156,6 @@ export type MenuItemProps = Omit<MenuItem, "key" | "children"> & ComponentProps
      * value
      */
     value: Key;
-    /**
-     * @description
-     * suffix
-     * @default void 0
-     */
-    suffix?: ReactNode;
     /**
      * @description
      * children

package/dist/types/picker.d.ts

@@ -1,123 +1,64 @@
-import type { CSSProperties, HTMLAttributes, MouseEventHandler, ReactNode } from "react";
-import type { ComponentProps } from "./element";
-import type { Nullable } from "@aiszlab/relax/types";
+import type { CSSProperties, ReactNode, RefObject } from "react";
+import type { PopperTrigger } from "./popper";
 /**
- * @description
- * picker props
+ * @zh Picker 触发器渲染参数
+ * @en Picker trigger render parameters
  */
-export interface PickerProps extends ComponentProps, Pick<HTMLAttributes<HTMLSpanElement>, "onBlur"> {
+export interface PickerTriggerRenderProps<T extends PopperTrigger = PopperTrigger> {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    isOpen: boolean;
+    triggerRef: RefObject<T | null>;
+}
+/**
+ * @zh Picker 属性
+ * @en Picker props
+ */
+export interface PickerProps<T extends PopperTrigger = PopperTrigger> {
     /**
-     * @description
-     * children
+     * @zh 触发器渲染函数
+     * @en Trigger render function
      */
-    children: ReactNode;
+    children: (props: PickerTriggerRenderProps<T>) => ReactNode;
     /**
-     * @description
-     * popup width
+     * @zh 弹层宽度
+     * @en Popup width
      */
     popupWidth?: "match" | number | false;
     /**
-     * @description
-     * when trigger on popper entering
+     * @zh 弹层开始进入时的处理函数
+     * @en Handler invoked when the popup starts entering
      */
     onPopperEnter?: () => Promise<void> | void;
     /**
-     * @description
-     * when trigger on popper entered
+     * @zh 弹层进入完成时的处理函数
+     * @en Handler invoked when the popup has entered
      */
     onPopperEntered?: () => Promise<void> | void;
     /**
-     * @description
-     * when trigger on popper exited
+     * @zh 弹层开始退出时的处理函数
+     * @en Handler invoked when the popup starts exiting
      */
     onPopperExite?: () => Promise<void> | void;
     /**
-     * @description
-     * when trigger on popper exited
+     * @zh 弹层退出完成时的处理函数
+     * @en Handler invoked when the popup has exited
      */
     onPopperExited?: () => Promise<void> | void;
     /**
-     * @description
-     * click handler
-     */
-    onClick?: MouseEventHandler<HTMLSpanElement>;
-    /**
-     * @description
-     * pickable
+     * @zh 可选内容或其渲染函数
+     * @en Pickable content or its render function
      */
-    pickable: ReactNode;
+    pickable: ReactNode | ((props: PickerTriggerRenderProps<T>) => ReactNode);
     /**
-     * @description
-     * pickable class name
+     * @zh 可选内容的类名
+     * @en Class name for the pickable content
      */
     pickableClassName?: string;
     /**
-     * @description
-     * pickable style
+     * @zh 可选内容的样式
+     * @en Style for the pickable content
      */
     pickableStyle?: CSSProperties;
-    /**
-     * @description
-     * invalid
-     * @default false
-     */
-    invalid?: boolean;
-    /**
-     * @description
-     * clear handler
-     * @default void 0
-     */
-    onClear?: () => void;
-    /**
-     * @description
-     * disabled state of the picker
-     * @default false
-     */
-    disabled?: boolean;
-}
-/**
- * @description
- * picker ref
- */
-export interface PickerRef {
-    /**
-     * @description
-     * close
-     */
-    close: () => void;
-}
-/**
- * @description
- * picker context value
- * provide picker state for custom render
- *
- * like in searchable select, if picker is focused, should show search input
- */
-export interface ContextValue {
-    /**
-     * @description
-     * why put `open` into context
-     *
-     * answer:
-     * in select case,
-     * if select is searchable, when typing search key,
-     * should show dropdown
-     */
-    open: Nullable<() => void>;
-    /**
-     * @description
-     * why put `isFocused` into context
-     *
-     * answer:
-     * in select
-     */
-    isFocused: boolean;
-    /**
-     * @description
-     * why put `isOpen` into context
-     *
-     * answer:
-     * in `Select` component, when `isOpen` is false, should keep the last state options
-     */
-    isOpen: boolean;
 }

package/dist/types/popper.d.ts

@@ -1,8 +1,9 @@
 import type { Nullable } from "@aiszlab/relax/types";
 import type { CSSProperties, DOMAttributes, ReactNode } from "react";
 import type { ComponentProps } from "./element";
-import type { Derivable, OffsetOptions, Placement } from "@floating-ui/dom";
+import type { Derivable, OffsetOptions, Placement, VirtualElement } from "@floating-ui/dom";
 import type { PortalProps } from "./portal";
+export type PopperTrigger = VirtualElement;
 /**
  * @author murukal
  *
@@ -24,7 +25,7 @@ export interface PopperProps extends Pick<DOMAttributes<HTMLDivElement>, "onMous
      * @description
      * trigger
      */
-    trigger?: Nullable<HTMLElement> | (() => Nullable<HTMLElement>);
+    trigger?: Nullable<PopperTrigger> | (() => Nullable<PopperTrigger>);
     /**
      * @description
      * placement

package/dist/types/search.d.ts

@@ -1,5 +1,28 @@
-import type { ReactNode } from "react";
+import type { Key, ReactNode } from "react";
 import { ComponentProps } from "./element";
+/**
+ * @zh Search View 展示模式
+ * @en Search View display mode
+ */
+export type SearchView = "auto" | "modal" | "full-screen";
+/**
+ * @zh 已解析的 Search View 展示模式
+ * @en Resolved Search View display mode
+ */
+export type ResolvedSearchView = Exclude<SearchView, "auto">;
+/**
+ * @zh Search 搜索结果项
+ * @en Search result item
+ */
+export type SearchItem = {
+    key: Key;
+    value: string;
+    label: ReactNode;
+    supportingText?: ReactNode;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    disabled?: boolean;
+};
 /**
  * @zh Search 组件的 ref 方法
  * @en Ref methods for Search component
@@ -31,6 +54,66 @@ export interface SearchRef {
  * @en Search component props
  */
 export type SearchProps = ComponentProps & {
+    /**
+     * @zh Search View 展示模式
+     * @en Search View display mode
+     * @default "auto"
+     */
+    view?: SearchView;
+    /**
+     * @zh 受控打开状态
+     * @en Controlled open state
+     * @default undefined
+     */
+    open?: boolean;
+    /**
+     * @zh 非受控默认打开状态
+     * @en Default open state for uncontrolled mode
+     * @default false
+     */
+    defaultOpen?: boolean;
+    /**
+     * @zh 打开状态变化时的回调
+     * @en Callback when the open state changes
+     * @default undefined
+     */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * @zh 搜索结果项
+     * @en Search result items
+     * @default []
+     */
+    items?: SearchItem[];
+    /**
+     * @zh 自定义搜索结果项内容
+     * @en Custom search result item content
+     * @default undefined
+     */
+    renderItem?: (item: SearchItem) => ReactNode;
+    /**
+     * @zh 选择搜索结果项时的回调
+     * @en Callback when a search result item is selected
+     * @default undefined
+     */
+    onSelect?: (item: SearchItem) => void;
+    /**
+     * @zh 选择搜索结果项后是否关闭 Search View
+     * @en Whether to close the Search View after selecting a search result item
+     * @default true
+     */
+    closeOnSelect?: boolean;
+    /**
+     * @zh Search 前置内容
+     * @en Search leading content
+     * @default undefined
+     */
+    leading?: ReactNode;
+    /**
+     * @zh Search 后置内容
+     * @en Search trailing content
+     * @default undefined
+     */
+    trailing?: ReactNode | ReactNode[];
     /**
      * @zh 受控值
      * @en Controlled value