@c2-markdown-ui/react 0.4.4 → 0.4.5

package/src/widgets/Radio.tsx

@@ -14,6 +14,13 @@ export interface RadioGroupProps {
   direction?: 'vertical' | 'horizontal';
   /** 自定义布局：每行列数（设置后按 N 列网格排列，优先于 direction） */
   columns?: number;
+  hint?: string;
+  /** 是否必填 */
+  required?: boolean;
+  /** 校验失败提示文案 */
+  message?: string;
+  /** 外部（form 提交时）传入的错误信息，优先于组件内部即时校验 */
+  error?: string;
   /** 是否禁用 */
   disabled?: boolean;
   onchange: (value: string) => void;
@@ -40,6 +47,10 @@ export const RadioGroup: React.FC<RadioGroupProps> = ({
   url,
   direction,
   columns,
+  hint = '',
+  required = false,
+  message = '',
+  error = '',
   disabled = false,
   onchange
 }) => {
@@ -57,6 +68,7 @@ export const RadioGroup: React.FC<RadioGroupProps> = ({
     if (initial !== undefined && initial !== null && initial !== '') return mapInitial(String(initial));
     return items[0]?.value ?? '';
   });
+  const [localError, setLocalError] = useState('');
 
   useEffect(() => {
     if (!url) { setRemoteItems(null); return; }
@@ -80,13 +92,22 @@ export const RadioGroup: React.FC<RadioGroupProps> = ({
   const handleChange = (value: string) => {
     if (disabled) return;
     setSelected(value);
+    setLocalError(validate(value));
     onchange(value);
   };
 
+  /** 校验当前值：返回错误文案或空串 */
+  const validate = (v: string): string => {
+    if (required && v === '') return message || (label ? `请填写${label}` : '请至少选择一项');
+    return '';
+  };
+
+  const shownError = error || localError;
+
   // ---------- 按钮样式（antd RadioButton）：复用 widget-button-group 视觉 ----------
   if (button) {
     return (
-      <div className="widget-button-group">
+      <div className={`widget-button-group${shownError ? ' widget-field-error' : ''}`}>
         {label && <label>{label}</label>}
         <div
           role="group"
@@ -96,7 +117,7 @@ export const RadioGroup: React.FC<RadioGroupProps> = ({
           style={columns && columns >= 1 ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` } : undefined}
         >
           {items.length === 0 && (
-            <div style={{ color: '#9ca3af', fontSize: 13 }}>暂无数据</div>
+            <div style={{ color: 'rgba(0, 0, 0, 0.45)', fontSize: 13 }}>暂无数据</div>
           )}
           {items.map((item) => (
             <button
@@ -110,36 +131,46 @@ export const RadioGroup: React.FC<RadioGroupProps> = ({
             </button>
           ))}
         </div>
+        {shownError ? <div className="widget-error-text" role="alert">{shownError}</div> : null}
       </div>
     );
   }
 
   // ---------- 默认圆点单选样式（antd Radio） ----------
   return (
-    <div className="selector">
-      {label && <div className="selector-multi-label">{label}</div>}
-      <div
-        className="radio-group"
-        role="radiogroup"
-        aria-label={label}
-        data-direction={columns ? 'grid' : (direction || 'vertical')}
-        style={columns && columns >= 1 ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` } : undefined}
-      >
-        {items.length === 0 && (
-          <div style={{ color: '#9ca3af', fontSize: 13 }}>暂无数据</div>
-        )}
-        {items.map((item) => (
-          <label key={item.value} className="radio-item">
-            <input
-              type="radio"
-              value={item.value}
-              checked={selected === item.value}
-              onChange={() => handleChange(item.value)}
-              disabled={disabled}
-            />
-            <span>{item.label}</span>
-          </label>
-        ))}
+    <div className={`selector-multi${shownError ? ' widget-field-error' : ''}`}>
+      {label || hint || required ? (
+        <div className="widget-label-row">
+          {required && <span className="widget-required-mark" aria-hidden="true">*</span>}
+          {label && <div className="selector-multi-label">{label}</div>}
+          {hint && <span className="widget-hint" data-hint={hint}>ⓘ</span>}
+        </div>
+      ) : null}
+      <div className="widget-field-content">
+        <div
+          className="radio-group"
+          role="radiogroup"
+          aria-label={label}
+          data-direction={columns ? 'grid' : (direction || 'vertical')}
+          style={columns && columns >= 1 ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` } : undefined}
+        >
+          {items.length === 0 && (
+            <div style={{ color: 'rgba(0, 0, 0, 0.45)', fontSize: 13 }}>暂无数据</div>
+          )}
+          {items.map((item) => (
+            <label key={item.value} className="radio-item">
+              <input
+                type="radio"
+                value={item.value}
+                checked={selected === item.value}
+                onChange={() => handleChange(item.value)}
+                disabled={disabled}
+              />
+              <span>{item.label}</span>
+            </label>
+          ))}
+        </div>
+        {shownError ? <div className="widget-error-text" role="alert">{shownError}</div> : null}
       </div>
     </div>
   );

package/src/widgets/Select.tsx

@@ -1,142 +1,178 @@
-import React, { useEffect, useMemo, useRef, useState } from 'react';
-import { parseChoices } from './choiceUtils';
-
-export interface SelectProps {
-  choices: string[];
-  label?: string;
-  default?: string;
-  /** 是否可搜索：开启后下拉面板内置搜索框，按 key/value 与 label 过滤选项 */
-  searchable?: boolean;
-  /** 搜索框占位文案 */
-  placeholder?: string;
-  /** 是否禁用 */
-  disabled?: boolean;
-  onchange: (value: string | string[]) => void;
-}
-
-export const Select: React.FC<SelectProps> = ({
-  choices,
-  label = '',
-  default: initial,
-  searchable = false,
-  placeholder = '',
-  disabled = false,
-  onchange
-}) => {
-  const items = parseChoices(choices);
-  const [value, setValue] = useState(initial ?? items[0]?.value ?? '');
-
-  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
-    const newValue = e.target.value;
-    setValue(newValue);
-    onchange(newValue);
-  };
-
-  // ---------- searchable 模式：自定义下拉（触发按钮 + 搜索框 + 滚动选项列表） ----------
-  const rootRef = useRef<HTMLDivElement>(null);
-  const searchInputRef = useRef<HTMLInputElement>(null);
-  const [open, setOpen] = useState(false);
-  /** 搜索关键字（按 value/key 与 label 过滤，大小写不敏感） */
-  const [query, setQuery] = useState('');
-  /** 当前选中项展示文案（value 与 label 不同时优先 label） */
-  const display = useMemo(() => {
-    const hit = items.find(it => it.value === value);
-    return hit ? hit.label : '';
-  }, [items, value]);
-
-  const filtered = useMemo(() => {
-    const q = query.trim().toLowerCase();
-    if (!q) return items;
-    return items.filter(it => it.value.toLowerCase().includes(q) || it.label.toLowerCase().includes(q));
-  }, [items, query]);
-
-  // 外部点击关闭面板
-  useEffect(() => {
-    function onDocClick(e: MouseEvent) {
-      if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);
-    }
-    document.addEventListener('mousedown', onDocClick);
-    return () => document.removeEventListener('mousedown', onDocClick);
-  }, []);
-
-  // 打开面板时聚焦搜索框并清空关键字
-  useEffect(() => {
-    if (open && searchInputRef.current) {
-      setQuery('');
-      searchInputRef.current.focus();
-    }
-  }, [open]);
-
-  function toggleOpen() {
-    if (disabled) return;
-    setOpen(prev => !prev);
-  }
-
-  /** 选中某选项：回填 value 并关闭面板 */
-  function pick(v: string) {
-    if (disabled) return;
-    setValue(v);
-    setOpen(false);
-    onchange(v);
-  }
-
-  if (searchable) {
-    return (
-      <div className="selector" ref={rootRef}>
-        {label && <label>{label}</label>}
-        <div className="widget-field-content widget-select-content">
-          <button
-            type="button"
-            className="cas-input"
-            onClick={toggleOpen}
-            aria-expanded={open}
-            disabled={disabled}
-          >
-            <span className={`cas-input-text${display ? '' : ' cas-placeholder'}`}>{display || placeholder || '请选择'}</span>
-            <span className={`cas-arrow${open ? ' cas-arrow-open' : ''}`} aria-hidden="true">▾</span>
-          </button>
-          {open && (
-            <div className="cas-panel cas-panel-single">
-              <div className="cas-search">
-                <input
-                  ref={searchInputRef}
-                  type="text"
-                  className="cas-search-input"
-                  value={query}
-                  placeholder="搜索选项…"
-                  onChange={e => setQuery(e.target.value)}
-                />
-              </div>
-              <div className="cas-menu cas-menu-full" role="menu">
-                {filtered.map(it => (
-                  <button
-                    type="button"
-                    key={it.value}
-                    className={`cas-option${value === it.value ? ' cas-option-active' : ''}`}
-                    onClick={() => pick(it.value)}
-                  >
-                    <span className="cas-option-label">{it.label}</span>
-                  </button>
-                ))}
-                {filtered.length === 0 && <div className="cas-empty">无匹配选项</div>}
-              </div>
-            </div>
-          )}
-        </div>
-      </div>
-    );
-  }
-
-  return (
-    <div className="selector">
-      {label && <label>{label}</label>}
-      <select value={value} onChange={handleChange} disabled={disabled}>
-        {items.map((item) => (
-          <option key={item.value} value={item.value}>
-            {item.label}
-          </option>
-        ))}
-      </select>
-    </div>
-  );
-};
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { normalizeRemoteChoices, parseChoices, resolveChoiceValue, type ChoiceItem } from './choiceUtils';
+
+export interface SelectProps {
+  choices: string[];
+  label?: string;
+  default?: string;
+  /** 远端数据源 URL：设置后运行时 fetch 拉取选项，choices 作为初始/后备选项 */
+  url?: string;
+  /** 是否可搜索：开启后下拉面板内置搜索框，按 key/value 与 label 过滤选项 */
+  searchable?: boolean;
+  /** 搜索框占位文案 */
+  placeholder?: string;
+  hint?: string;
+  /** 是否必填：label 前红色 * */
+  required?: boolean;
+  /** 是否禁用 */
+  disabled?: boolean;
+  onchange: (value: string | string[]) => void;
+}
+
+export const Select: React.FC<SelectProps> = ({
+  choices,
+  label = '',
+  default: initial,
+  url = '',
+  searchable = false,
+  placeholder = '',
+  hint = '',
+  required = false,
+  disabled = false,
+  onchange
+}) => {
+  // 展示条目：远端拉取成功用 {value,label}，否则本地 choices（url 失败静默回落本地）
+  const [remoteItems, setRemoteItems] = useState<ChoiceItem[] | null>(null);
+  const items = useMemo(() => remoteItems ?? parseChoices(choices), [remoteItems, choices]);
+
+  const [value, setValue] = useState(initial ?? items[0]?.value ?? '');
+  /** 远端加载中：回显文案与空态显示"加载中…" */
+  const [loading, setLoading] = useState(false);
+
+  // ---------- url 远端模式：拉取成功后覆盖本地 choices，失败静默回落本地 ----------
+  useEffect(() => {
+    if (!url) { setRemoteItems(null); return; }
+    let cancelled = false;
+    setLoading(true);
+    (async () => {
+      try {
+        const res = await fetch(url);
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const json: any = await res.json();
+        if (cancelled) return;
+        const list = normalizeRemoteChoices(json);
+        if (list.length === 0) throw new Error('响应中没有可用选项');
+        setRemoteItems(list);
+        // 当前值不在远端取值中时：default/本地值按 label 映射到远端 value，否则回落第一项
+        setValue(prev => {
+          if (list.some(r => r.value === prev)) return prev;
+          const mapped = initial !== undefined ? resolveChoiceValue(initial, list) : prev;
+          const next = list.some(r => r.value === mapped) ? mapped : list[0].value;
+          if (next !== prev) onchange(next);
+          return next;
+        });
+      } catch {
+        // 加载失败：静默回落本地 choices
+      } finally {
+        if (!cancelled) setLoading(false);
+      }
+    })();
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [url]);
+
+  // ---------- 自定义下拉面板（antd 风格）：searchable 带搜索框，普通模式纯选项列表 ----------
+  const rootRef = useRef<HTMLDivElement>(null);
+  const searchInputRef = useRef<HTMLInputElement>(null);
+  const [open, setOpen] = useState(false);
+  /** 搜索关键字（按 value/key 与 label 过滤，大小写不敏感） */
+  const [query, setQuery] = useState('');
+  /** 当前选中项展示文案（value 与 label 不同时优先 label） */
+  const display = useMemo(() => {
+    const hit = items.find(it => it.value === value);
+    return hit ? hit.label : '';
+  }, [items, value]);
+
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return items;
+    return items.filter(it => it.value.toLowerCase().includes(q) || it.label.toLowerCase().includes(q));
+  }, [items, query]);
+
+  // 外部点击关闭面板
+  useEffect(() => {
+    function onDocClick(e: MouseEvent) {
+      if (rootRef.current && !rootRef.current.contains(e.target as Node)) setOpen(false);
+    }
+    document.addEventListener('mousedown', onDocClick);
+    return () => document.removeEventListener('mousedown', onDocClick);
+  }, []);
+
+  // 打开面板时聚焦搜索框并清空关键字（仅 searchable 模式有搜索框）
+  useEffect(() => {
+    if (open && searchable && searchInputRef.current) {
+      setQuery('');
+      searchInputRef.current.focus();
+    }
+  }, [open, searchable]);
+
+  function toggleOpen() {
+    if (disabled) return;
+    setOpen(prev => !prev);
+  }
+
+  /** 选中某选项：回填 value 并关闭面板 */
+  function pick(v: string) {
+    if (disabled) return;
+    setValue(v);
+    setOpen(false);
+    onchange(v);
+  }
+
+  const filteredOptions = searchable ? filtered : items;
+
+  return (
+    <div className="selector" ref={rootRef}>
+      {label || hint || required ? (
+        <div className="widget-label-row">
+          {required && <span className="widget-required-mark" aria-hidden="true">*</span>}
+          {label && <label>{label}</label>}
+          {hint && <span className="widget-hint" data-hint={hint}>ⓘ</span>}
+        </div>
+      ) : null}
+      <div className="widget-field-content widget-select-content">
+        <button
+          type="button"
+          className="cas-input"
+          onClick={toggleOpen}
+          aria-expanded={open}
+          disabled={disabled}
+        >
+          <span className={`cas-input-text${display || loading ? '' : ' cas-placeholder'}`}>{loading ? '加载中…' : (display || placeholder || '请选择')}</span>
+          <span className={`cas-arrow${open ? ' cas-arrow-open' : ''}`} aria-hidden="true">▾</span>
+        </button>
+        {open && (
+          <div className="cas-panel cas-panel-single">
+            {searchable && (
+              <div className="cas-search">
+                <input
+                  ref={searchInputRef}
+                  type="text"
+                  className="cas-search-input"
+                  value={query}
+                  placeholder="搜索选项…"
+                  onChange={e => setQuery(e.target.value)}
+                />
+              </div>
+            )}
+            <div className="cas-menu cas-menu-full" role="menu">
+              {filteredOptions.map(it => (
+                <button
+                  type="button"
+                  key={it.value}
+                  className={`cas-option${value === it.value ? ' cas-option-active' : ''}`}
+                  onClick={() => pick(it.value)}
+                >
+                  <span className="cas-option-label">{it.label}</span>
+                </button>
+              ))}
+              {filteredOptions.length === 0 && (
+                <div className="cas-empty">{loading ? '加载中…' : query.trim() ? '无匹配选项' : '暂无数据'}</div>
+              )}
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+};

package/src/widgets/SelectMulti.tsx

@@ -1,72 +1,105 @@
-import React, { useState } from 'react';
-import { parseChoice, parseChoices } from './choiceUtils';
-
-export interface SelectMultiProps {
-  /** 选项：字符串数组（每项支持 key:label 格式）或对象数组（{key|value,label}，取值为 key/value，展示 label） */
-  choices: string[] | Array<{ value?: string; key?: string; label?: string }>;
-  label?: string;
-  default?: string | string[];
-  /** 选项排列方向：vertical 纵向（默认）/ horizontal 横向 */
-  direction?: 'vertical' | 'horizontal';
-  /** 自定义布局：每行列数（设置后按 N 列网格排列，优先于 direction） */
-  columns?: number;
-  /** 是否禁用 */
-  disabled?: boolean;
-  onchange: (value: string | string[]) => void;
-}
-
-export const SelectMulti: React.FC<SelectMultiProps> = ({
-  choices,
-  label = '',
-  default: initial,
-  direction,
-  columns,
-  disabled = false,
-  onchange
-}) => {
-  const items = parseChoices(choices);
-  // 初始勾选值：default 可能是 key、label 或 key:label 原文，统一解析为 key 体系
-  const [value, setValue] = useState<string[]>(
-    Array.isArray(initial)
-      ? initial.map(v => parseChoice(String(v)).value)
-      : (initial ? [parseChoice(String(initial)).value] : [])
-  );
-
-  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const choice = e.target.value;
-    let newValue: string[];
-
-    if (e.target.checked) {
-      newValue = [...value, choice];
-    } else {
-      newValue = value.filter(v => v !== choice);
-    }
-
-    setValue(newValue);
-    onchange(newValue);
-  };
-
-  return (
-    <div className="selector-multi">
-      {label && <div className="selector-multi-label">{label}</div>}
-      <div
-        className="checkbox-group"
-        data-direction={columns ? 'grid' : (direction || 'vertical')}
-        style={columns && columns >= 1 ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` } : undefined}
-      >
-        {items.map((item) => (
-          <label key={item.value} className="checkbox-item">
-            <input
-              type="checkbox"
-              value={item.value}
-              checked={value.includes(item.value)}
-              onChange={handleChange}
-              disabled={disabled}
-            />
-            <span>{item.label}</span>
-          </label>
-        ))}
-      </div>
-    </div>
-  );
-};
+import React, { useState } from 'react';
+import { parseChoice, parseChoices } from './choiceUtils';
+
+export interface SelectMultiProps {
+  /** 选项：字符串数组（每项支持 key:label 格式）或对象数组（{key|value,label}，取值为 key/value，展示 label） */
+  choices: string[] | Array<{ value?: string; key?: string; label?: string }>;
+  label?: string;
+  default?: string | string[];
+  /** 选项排列方向：vertical 纵向（默认）/ horizontal 横向 */
+  direction?: 'vertical' | 'horizontal';
+  /** 自定义布局：每行列数（设置后按 N 列网格排列，优先于 direction） */
+  columns?: number;
+  hint?: string;
+  /** 是否必填 */
+  required?: boolean;
+  /** 校验失败提示文案 */
+  message?: string;
+  /** 外部（form 提交时）传入的错误信息，优先于组件内部即时校验 */
+  error?: string;
+  /** 是否禁用 */
+  disabled?: boolean;
+  onchange: (value: string | string[]) => void;
+}
+
+export const SelectMulti: React.FC<SelectMultiProps> = ({
+  choices,
+  label = '',
+  default: initial,
+  direction,
+  columns,
+  hint = '',
+  required = false,
+  message = '',
+  error = '',
+  disabled = false,
+  onchange
+}) => {
+  const items = parseChoices(choices);
+  // 初始勾选值：default 可能是 key、label 或 key:label 原文，统一解析为 key 体系
+  const [value, setValue] = useState<string[]>(
+    Array.isArray(initial)
+      ? initial.map(v => parseChoice(String(v)).value)
+      : (initial ? [parseChoice(String(initial)).value] : [])
+  );
+  const [localError, setLocalError] = useState('');
+
+  /** 校验当前值：返回错误文案或空串 */
+  const validate = (v: string[]): string => {
+    if (required && v.length === 0) return message || (label ? `请填写${label}` : '请至少选择一项');
+    return '';
+  };
+
+  const shownError = error || localError;
+
+  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    const choice = e.target.value;
+    let newValue: string[];
+
+    if (e.target.checked) {
+      newValue = [...value, choice];
+    } else {
+      newValue = value.filter(v => v !== choice);
+    }
+
+    setValue(newValue);
+    setLocalError(validate(newValue));
+    onchange(newValue);
+  };
+
+  return (
+    <div className={`selector-multi${shownError ? ' widget-field-error' : ''}`}>
+      {label || hint || required ? (
+        <div className="widget-label-row">
+          {required && <span className="widget-required-mark" aria-hidden="true">*</span>}
+          {label && <div className="selector-multi-label">{label}</div>}
+          {hint && <span className="widget-hint" data-hint={hint}>ⓘ</span>}
+        </div>
+      ) : null}
+      <div className="widget-field-content">
+        <div
+          className="checkbox-group"
+          data-direction={columns ? 'grid' : (direction || 'vertical')}
+          style={columns && columns >= 1 ? { gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` } : undefined}
+        >
+          {items.length === 0 && (
+            <div style={{ color: 'rgba(0, 0, 0, 0.45)', fontSize: '13px' }}>暂无数据</div>
+          )}
+          {items.map((item) => (
+            <label key={item.value} className="checkbox-item">
+              <input
+                type="checkbox"
+                value={item.value}
+                checked={value.includes(item.value)}
+                onChange={handleChange}
+                disabled={disabled}
+              />
+              <span>{item.label}</span>
+            </label>
+          ))}
+        </div>
+        {shownError ? <div className="widget-error-text" role="alert">{shownError}</div> : null}
+      </div>
+    </div>
+  );
+};