@sia.soul/sia-react-ui 0.1.18 → 0.1.21

package/dist/{chunk-LPRFOSRZ.js → chunk-3TRRBMXY.js}

@@ -3,7 +3,7 @@ import {
   Icon,
   Input,
   PopupPortal
-} from "./chunk-SUMXP2SF.js";
+} from "./chunk-KLI65JVD.js";
 import {
   Button
 } from "./chunk-TZGUBGA4.js";
@@ -87,7 +87,10 @@ function CheckboxGroup({
     children
   ] }) }) });
 }
-var Checkbox2 = Object.assign(CheckboxRoot, { Group: CheckboxGroup });
+var Checkbox2 = Object.assign(CheckboxRoot, {
+  /** 组合多个子项并统一管理布局或选择状态。 */
+  Group: CheckboxGroup
+});
 
 // src/components/FloatingDisplay.tsx
 import { cloneElement, useEffect as useEffect2, useId as useId2, useLayoutEffect, useMemo as useMemo2, useRef as useRef2, useState } from "react";
@@ -637,6 +640,7 @@ var ModalRoot = forwardRef2(function Modal({
   title,
   children,
   footer,
+  footerExtra,
   type = "default",
   okText = "\u786E\u5B9A",
   cancelText = "\u53D6\u6D88",
@@ -761,7 +765,10 @@ var ModalRoot = forwardRef2(function Modal({
               closable ? /* @__PURE__ */ jsx3("button", { type: "button", className: "sia-modal__close", "aria-label": "\u5173\u95ED\u5BF9\u8BDD\u6846", onClick: requestClose, children: /* @__PURE__ */ jsx3(Icon, { name: "close", size: 17 }) }) : null
             ] }),
             children !== void 0 ? /* @__PURE__ */ jsx3("div", { className: "sia-modal__body", children }) : null,
-            footer !== null ? /* @__PURE__ */ jsx3("div", { className: "sia-modal__footer", children: footer ?? defaultFooter }) : null
+            footer !== null ? /* @__PURE__ */ jsxs3("div", { className: "sia-modal__footer", children: [
+              footer === void 0 && footerExtra != null ? /* @__PURE__ */ jsx3("div", { style: { marginRight: "auto" }, children: footerExtra }) : null,
+              footer ?? defaultFooter
+            ] }) : null
           ]
         }
       )
@@ -824,12 +831,19 @@ function preset(type, defaults = {}) {
   });
 }
 var Modal2 = Object.assign(ModalRoot, {
+  /** 直接打开实例，返回可用于更新或关闭的操作句柄。 */
   open: openModal,
+  /** 显示普通信息提示。 */
   info: preset("info", { title: "\u63D0\u793A" }),
+  /** 显示成功提示。 */
   success: preset("success", { title: "\u64CD\u4F5C\u6210\u529F" }),
+  /** 显示警告提示。 */
   warning: preset("warning", { title: "\u8BF7\u6CE8\u610F" }),
+  /** 显示错误提示。 */
   error: preset("error", { title: "\u64CD\u4F5C\u5931\u8D25" }),
+  /** 打开确认弹框，支持异步确认；返回 false 可阻止关闭。 */
   confirm: preset("confirm", { title: "\u786E\u8BA4\u64CD\u4F5C" }),
+  /** 关闭由此 API 打开的所有弹层。 */
   destroyAll() {
     [...modalHandles].forEach((handle) => handle.destroy());
   }
@@ -843,6 +857,7 @@ function SelectionPanel({
   value,
   onChange,
   multiple = false,
+  allowDeselect = false,
   disabled = false,
   loading = false,
   showSearch = true,
@@ -861,6 +876,8 @@ function SelectionPanel({
   const search = searchValue ?? localSearch;
   const [scrollTop, setScrollTop] = useState3(0);
   const [active, setActive] = useState3();
+  const [keyboardActive, setKeyboardActive] = useState3(false);
+  const [deselectedHover, setDeselectedHover] = useState3();
   const listRef = useRef5(null);
   const id = useId4();
   const selected = useMemo3(() => new Set(value), [value]);
@@ -905,10 +922,12 @@ function SelectionPanel({
     if (listRef.current) listRef.current.scrollTop = 0;
     setActive(void 0);
   }, [search, selectedOnly, count]);
-  function toggle(option) {
+  function toggle(option, keyboard = false) {
     if (disabled || loading || option.disabled || option.optionType === "divider") return;
     setActive(option.value);
-    onChange(multiple ? selected.has(option.value) ? value.filter((item) => item !== option.value) : [...value, option.value] : [option.value]);
+    setKeyboardActive(keyboard);
+    setDeselectedHover(!keyboard && !multiple && allowDeselect && selected.has(option.value) ? option.value : void 0);
+    onChange(multiple ? selected.has(option.value) ? value.filter((item) => item !== option.value) : [...value, option.value] : allowDeselect && selected.has(option.value) ? [] : [option.value]);
   }
   function batch(operation) {
     if (disabled || loading) return;
@@ -957,6 +976,10 @@ function SelectionPanel({
         className: "sia-selection-panel__list",
         style: { maxHeight },
         onScroll: (event) => setScrollTop(event.currentTarget.scrollTop),
+        onPointerDown: () => setKeyboardActive(false),
+        onBlur: (event) => {
+          if (!event.currentTarget.contains(event.relatedTarget)) setKeyboardActive(false);
+        },
         "aria-activedescendant": active !== void 0 ? `${id}-${typeof active}-${active}` : void 0,
         onKeyDown: (event) => {
           if (event.target instanceof HTMLInputElement) return;
@@ -964,6 +987,8 @@ function SelectionPanel({
           const index = enabled.findIndex((option) => option.value === active);
           if (["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) {
             event.preventDefault();
+            setKeyboardActive(true);
+            setDeselectedHover(void 0);
             const next = event.key === "Home" ? 0 : event.key === "End" ? enabled.length - 1 : Math.max(0, Math.min(enabled.length - 1, index + (event.key === "ArrowDown" ? 1 : -1)));
             const option = enabled[next];
             setActive(option.value);
@@ -974,7 +999,7 @@ function SelectionPanel({
             }
           } else if ((event.key === "Enter" || event.key === " ") && index >= 0) {
             event.preventDefault();
-            toggle(enabled[index]);
+            toggle(enabled[index], true);
           }
         },
         children: loading ? /* @__PURE__ */ jsx4("div", { role: "status", children: "\u52A0\u8F7D\u4E2D\u2026" }) : !rows.length ? /* @__PURE__ */ jsx4("div", { className: "sia-selection-panel__empty", children: "\u6682\u65E0\u5339\u914D\u9009\u9879" }) : /* @__PURE__ */ jsx4("div", { style: { height: totalHeight, position: "relative" }, children: renderedRows.map((row) => /* @__PURE__ */ jsx4(
@@ -990,7 +1015,11 @@ function SelectionPanel({
                 tabIndex: -1,
                 "aria-selected": selected.has(option.value),
                 "aria-disabled": disabled || option.disabled || void 0,
-                className: `sia-selection-panel__option${active === option.value ? " is-active" : ""}`,
+                className: `sia-selection-panel__option${keyboardActive && active === option.value ? " is-active" : ""}`,
+                "data-deselected-hover": deselectedHover === option.value || void 0,
+                onPointerLeave: () => {
+                  if (deselectedHover === option.value) setDeselectedHover(void 0);
+                },
                 onClick: (event) => {
                   if (!event.target.closest(".sia-checkbox")) toggle(option);
                 },
@@ -1445,7 +1474,8 @@ function defaultFilterOption(query, option) {
 var Select = forwardRef3(function Select2({
   options,
   mode = "single",
-  popupMode = "dropdown",
+  popupMode: popupModeProp,
+  modalThreshold = 15,
   modalConfig,
   value,
   defaultValue,
@@ -1454,7 +1484,7 @@ var Select = forwardRef3(function Select2({
   placeholderMode,
   size: sizeProp,
   status = "default",
-  allowClear = false,
+  allowClear = true,
   loading = false,
   showSearch = false,
   showValue = false,
@@ -1487,6 +1517,9 @@ var Select = forwardRef3(function Select2({
   const searchRef = useRef7(null);
   const listRef = useRef7(null);
   const [open, setOpen] = useState5(false);
+  const automaticMode = popupModeProp ?? (options.length > modalThreshold ? "modal" : "dropdown");
+  const [openedMode, setOpenedMode] = useState5(automaticMode);
+  const popupMode = open ? openedMode : automaticMode;
   const [modalValues, setModalValues] = useState5([]);
   const [selectedOnly, setSelectedOnly] = useState5(false);
   const [query, setQuery] = useState5("");
@@ -1558,9 +1591,10 @@ var Select = forwardRef3(function Select2({
   }
   function openDropdown() {
     if (disabled || loading) return;
+    setOpenedMode(automaticMode);
     const selectedIndex = filteredOptions.findIndex((option) => selectedValueSet.has(option.value) && !option.disabled);
     setActiveIndex(selectedIndex >= 0 ? selectedIndex : firstEnabledIndex());
-    if (popupMode === "modal") {
+    if (automaticMode === "modal") {
       setModalValues([...selectedValues]);
       setSelectedOnly(false);
     }
@@ -1847,6 +1881,7 @@ var Select = forwardRef3(function Select2({
               value: modalValues,
               onChange: setModalValues,
               multiple,
+              allowDeselect: allowClear,
               selectedOnly,
               showValue,
               showSearch: false,

package/dist/{chunk-JX53ZBIW.js → chunk-7RNS52YG.js}

@@ -5,11 +5,11 @@ import {
   Popover,
   Tooltip,
   useOverlayLifecycle
-} from "./chunk-LPRFOSRZ.js";
+} from "./chunk-3TRRBMXY.js";
 import {
   Dropdown,
   Icon
-} from "./chunk-SUMXP2SF.js";
+} from "./chunk-KLI65JVD.js";
 import {
   Button
 } from "./chunk-TZGUBGA4.js";
@@ -521,11 +521,17 @@ function openNotification(config) {
   return { key, close: () => closeNotification(key) };
 }
 var notification = {
+  /** 直接打开实例，返回可用于更新或关闭的操作句柄。 */
   open: openNotification,
+  /** 显示普通信息提示。 */
   info: (config) => openNotification({ ...config, type: "info" }),
+  /** 显示成功提示。 */
   success: (config) => openNotification({ ...config, type: "success" }),
+  /** 显示警告提示。 */
   warning: (config) => openNotification({ ...config, type: "warning" }),
+  /** 显示错误提示。 */
   error: (config) => openNotification({ ...config, type: "error" }),
+  /** 关闭指定实例；未指定标识时关闭所有实例。 */
   destroy: (key) => {
     if (key !== void 0) closeNotification(key);
     else {
@@ -961,7 +967,12 @@ function UploadDragger({ hint = "\u652F\u6301\u5355\u4E2A\u6216\u6279\u91CF\u4E0
     /* @__PURE__ */ jsx6("span", { children: hint })
   ] }) });
 }
-var Upload = Object.assign(UploadRoot, { Dragger: UploadDragger, LIST_IGNORE });
+var Upload = Object.assign(UploadRoot, {
+  /** 支持拖入文件上传的区域组件。 */
+  Dragger: UploadDragger,
+  /** beforeUpload 返回此标记时忽略该文件，不加入上传列表。 */
+  LIST_IGNORE
+});
 
 // src/components/Message.tsx
 import { createRoot as createRoot2 } from "react-dom/client";
@@ -1041,12 +1052,19 @@ function shortcut(type) {
   return (content, duration) => openMessage({ content, duration, type });
 }
 var message = {
+  /** 直接打开实例，返回可用于更新或关闭的操作句柄。 */
   open: openMessage,
+  /** 显示普通信息提示。 */
   info: shortcut("info"),
+  /** 显示成功提示。 */
   success: shortcut("success"),
+  /** 显示警告提示。 */
   warning: shortcut("warning"),
+  /** 显示错误提示。 */
   error: shortcut("error"),
+  /** 显示持续加载提示。 */
   loading: shortcut("loading"),
+  /** 关闭指定实例；未指定标识时关闭所有实例。 */
   destroy(key) {
     if (key !== void 0) {
       closeMessage(key);
@@ -1054,6 +1072,7 @@ var message = {
     }
     [...messageItems].forEach((item) => closeMessage(item.key));
   },
+  /** 配置消息默认持续时间和最大同时显示数量。 */
   config(config) {
     if (config.duration !== void 0) defaultDuration = config.duration;
     if (config.maxCount !== void 0) maxCount = Math.max(1, config.maxCount);
@@ -1227,7 +1246,16 @@ function Link({ disabled, className = "", onClick, href, target, rel, ...props }
 function TypographyRoot({ className = "", ...props }) {
   return /* @__PURE__ */ jsx9("div", { ...props, className: `sia-typography ${className}`.trim() });
 }
-var Typography = Object.assign(TypographyRoot, { Title, Text, Paragraph, Link });
+var Typography = Object.assign(TypographyRoot, {
+  /** 语义化标题，支持标题级别、复制和编辑。 */
+  Title,
+  /** 行内文本，支持强调、复制、编辑和省略。 */
+  Text,
+  /** 段落文本，支持复制、编辑和省略。 */
+  Paragraph,
+  /** 具有排版样式的链接。 */
+  Link
+});
 
 // src/components/FloatButton.tsx
 import { createContext, forwardRef, useContext, useEffect as useEffect4, useId as useId3, useRef as useRef6, useState as useState6 } from "react";
@@ -1358,7 +1386,12 @@ function FloatButtonBackTop({ target, visibilityHeight = 400, behavior = "smooth
     element?.scrollTo({ top: 0, behavior: window.matchMedia("(prefers-reduced-motion: reduce)").matches ? "auto" : behavior });
   } });
 }
-var FloatButton2 = Object.assign(FloatButtonRoot, { Group: FloatButtonGroup, BackTop: FloatButtonBackTop });
+var FloatButton2 = Object.assign(FloatButtonRoot, {
+  /** 组合多个子项并统一管理布局或选择状态。 */
+  Group: FloatButtonGroup,
+  /** 滚动超过指定距离后显示的返回顶部按钮。 */
+  BackTop: FloatButtonBackTop
+});
 
 export {
   Card,

package/dist/{chunk-SUMXP2SF.js → chunk-KLI65JVD.js}

@@ -1160,7 +1160,7 @@ function Segmented({ options, value, defaultValue, size: sizeProp, block = false
 }
 
 // src/components/Dropdown.tsx
-import { useEffect as useEffect2, useRef as useRef3, useState as useState3 } from "react";
+import { cloneElement, isValidElement, useEffect as useEffect2, useRef as useRef3, useState as useState3 } from "react";
 import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
 var placementMap = {
   bottomLeft: "bottom-start",
@@ -1176,6 +1176,7 @@ function DropdownRoot({
   open,
   defaultOpen = false,
   disabled = false,
+  showTriggerIcon = true,
   arrow = false,
   autoFocus = false,
   openDelay = 80,
@@ -1336,6 +1337,10 @@ function DropdownRoot({
       className: "sia-dropdown__menu"
     }
   );
+  const triggerNode = showTriggerIcon && isValidElement(children) && children.type === Button && children.props.children !== void 0 && children.props.children !== null ? cloneElement(children, {}, /* @__PURE__ */ jsxs4("span", { className: "sia-dropdown__trigger-content", children: [
+    children.props.children,
+    /* @__PURE__ */ jsx5(Icon, { name: "chevron-down", size: 14, className: "sia-dropdown__trigger-icon" })
+  ] })) : children;
   return /* @__PURE__ */ jsxs4(
     "span",
     {
@@ -1351,7 +1356,7 @@ function DropdownRoot({
       onKeyDown: handleKeyDown,
       ...props,
       children: [
-        children,
+        triggerNode,
         /* @__PURE__ */ jsx5(
           "span",
           {
@@ -1398,7 +1403,7 @@ function DropdownButton({
 }) {
   return /* @__PURE__ */ jsxs4("span", { className: `sia-dropdown-button ${className}`.trim(), children: [
     /* @__PURE__ */ jsx5(Button, { ...buttonProps, disabled, onClick, children }),
-    /* @__PURE__ */ jsx5(DropdownRoot, { ...dropdownProps, disabled, trigger, children: /* @__PURE__ */ jsx5(
+    /* @__PURE__ */ jsx5(DropdownRoot, { ...dropdownProps, disabled, trigger, showTriggerIcon: false, children: /* @__PURE__ */ jsx5(
       Button,
       {
         ...buttonProps,
@@ -1410,7 +1415,10 @@ function DropdownButton({
     ) })
   ] });
 }
-var Dropdown = Object.assign(DropdownRoot, { Button: DropdownButton });
+var Dropdown = Object.assign(DropdownRoot, {
+  /** 组合主操作按钮与下拉菜单的按钮组件。 */
+  Button: DropdownButton
+});
 
 // src/components/Input.tsx
 import { forwardRef as forwardRef3, useId as useId2, useRef as useRef4, useState as useState4 } from "react";

package/dist/{chunk-I3EF5SF2.js → chunk-RWGSZW32.js}

@@ -2,7 +2,7 @@ import {
   Dropdown,
   Icon,
   Input
-} from "./chunk-SUMXP2SF.js";
+} from "./chunk-KLI65JVD.js";
 import {
   Button
 } from "./chunk-TZGUBGA4.js";

package/dist/{chunk-UCQZZ2YC.js → chunk-VN6PIPP7.js}

@@ -1,10 +1,10 @@
 import {
   Select
-} from "./chunk-LPRFOSRZ.js";
+} from "./chunk-3TRRBMXY.js";
 import {
   Icon,
   PopupPortal
-} from "./chunk-SUMXP2SF.js";
+} from "./chunk-KLI65JVD.js";
 import {
   useControlSize,
   useControllableState,