@teamix-evo/ui 0.7.0 → 0.7.2

package/src/components/filter-bar/meta.md

@@ -55,3 +55,326 @@
 | `control` | `Control<TForm>` | – | – | 显式指定 RHF control（默认从 FilterBar 上下文取）。 |
 | `children` | `React.ReactElement` | – | – | 静态 JSX 子元素（首选，AI 友好）。内部按子元素身份自动桥接 RHF field 到 `value`/`checked` + 对应 onChange。 适配 Input / Select / Checkbox / Switch / RadioGroup / Slider / Textarea； 不在适配表中的自定义控件请改用 `render` prop。 |
 | `render` | `(props: { field: ControllerRenderProps<TForm, TName>; fieldState: ControllerFieldState; formState: UseFormStateReturn<TForm>; }) => React.ReactElement` | – | – | 渲染输入控件（逆出舱，适配表不覆盖时使用）。 |
+
+## 示例
+
+### Inline
+
+```tsx
+<div>
+  <FilterBar
+    form={form}
+    autoFilter
+    onFilter={(values) => setFiltered(values)}
+  >
+    <FilterBarHeader>
+      <FilterBarField name="status" label="状态">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {STATUS_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="region" label="地域">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {REGION_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="keyword" label="关键词">
+        <Input placeholder="请输入实例名称" />
+      </FilterBarField>
+    </FilterBarHeader>
+  </FilterBar>
+  <FilteredPreview values={filtered} />
+</div>
+```
+
+### WithAdvancedPanel
+
+```tsx
+<div>
+  <FilterBar
+    form={form}
+    columns={3}
+    onFilter={(values) => setFiltered(values)}
+  >
+    <FilterBarHeader>
+      <FilterBarField name="status" label="状态">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {STATUS_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="region" label="地域">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {REGION_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="keyword" label="关键词">
+        <Input placeholder="请输入" />
+      </FilterBarField>
+      <FilterBarTrigger />
+    </FilterBarHeader>
+    <FilterBarContent>
+      <FilterBarField name="type" label="类型">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {TYPE_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="owner" label="负责人">
+        <Input placeholder="请输入负责人" />
+      </FilterBarField>
+      <FilterBarField name="tag" label="标签">
+        <Input placeholder="请输入标签" />
+      </FilterBarField>
+      <FilterBarActions />
+    </FilterBarContent>
+  </FilterBar>
+  <FilteredPreview values={filtered} />
+</div>
+```
+
+### PurePanel
+
+```tsx
+<div>
+  <FilterBar
+    form={form}
+    defaultOpen
+    columns={{ base: 2, md: 4 }}
+    onFilter={(values) => setFiltered(values)}
+  >
+    <FilterBarContent>
+      <FilterBarField name="status" label="状态">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {STATUS_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="region" label="地域">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {REGION_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="type" label="类型">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {TYPE_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="owner" label="负责人">
+        <Input placeholder="请输入" />
+      </FilterBarField>
+      <FilterBarActions />
+    </FilterBarContent>
+  </FilterBar>
+  <FilteredPreview values={filtered} />
+</div>
+```
+
+### WithKeySearch
+
+```tsx
+<div>
+  <FilterBar
+    form={form}
+    columns={3}
+    onFilter={(values) => setFiltered(values)}
+    addonBefore={
+      <Button>
+        <Plus />
+        创建任务
+      </Button>
+    }
+    addonAfter={
+      <Button variant="outline" aria-label="设置">
+        <Settings2 />
+      </Button>
+    }
+  >
+    <FilterBarHeader>
+      <FilterBarSearch className="w-80">
+        <FilterBarSearchKey
+          options={[
+            { name: 'instanceId', label: '实例 ID' },
+            { name: 'instanceName', label: '实例名称' },
+            { name: 'ip', label: 'IP 地址' },
+          ]}
+        />
+        <FilterBarSearchValue />
+        <FilterBarSearchAction />
+      </FilterBarSearch>
+      <FilterBarTrigger />
+    </FilterBarHeader>
+    <FilterBarContent>
+      <FilterBarField name="status" label="状态">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {STATUS_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="region" label="地域">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {REGION_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="type" label="类型">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {TYPE_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarActions />
+    </FilterBarContent>
+  </FilterBar>
+  <FilteredPreview values={filtered} />
+</div>
+```
+
+### CustomActions
+
+```tsx
+<div>
+  <FilterBar
+    form={form}
+    onFilter={(values) =>
+      setSavedFilter(`筛选 → ${JSON.stringify(values)}`)
+    }
+  >
+    <FilterBarHeader>
+      <FilterBarField name="status" label="状态">
+        <Select>
+          <SelectTrigger className="w-full">
+            <SelectValue placeholder="全部" />
+          </SelectTrigger>
+          <SelectContent>
+            {STATUS_OPTIONS.map((o) => (
+              <SelectItem key={o.value} value={o.value}>
+                {o.label}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </FilterBarField>
+      <FilterBarField name="keyword" label="关键词">
+        <Input placeholder="请输入" />
+      </FilterBarField>
+      <FilterBarActions>
+        <Button
+          type="button"
+          variant="outline"
+          onClick={() => form.reset()}
+        >
+          清空
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          onClick={() =>
+            setSavedFilter(`已保存 → ${JSON.stringify(form.getValues())}`)
+          }
+        >
+          保存条件
+        </Button>
+        <Button type="submit">立即查询</Button>
+      </FilterBarActions>
+    </FilterBarHeader>
+  </FilterBar>
+  <div className="mt-3 rounded-md bg-muted/40 px-3 py-2 text-xs text-muted-foreground">
+    <span className="text-foreground">最近动作：</span>
+    {savedFilter ?? '— 无 —'}
+  </div>
+</div>
+```

package/src/components/float-button/index.tsx

@@ -19,7 +19,7 @@ import { ArrowUpIcon } from 'lucide-react';
 import { cn } from '@/lib/utils';
 
 const floatButtonVariants = cva(
-  'relative inline-flex items-center justify-center transition-all shadow-lg hover:shadow-xl active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring cursor-pointer disabled:cursor-not-allowed disabled:opacity-50',
+  'relative inline-flex cursor-pointer items-center justify-center shadow-lg transition-all hover:shadow-xl focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none active:scale-95 disabled:cursor-not-allowed disabled:opacity-50',
   {
     variants: {
       variant: {
@@ -76,7 +76,7 @@ function FloatButton({
       {badge != null && (
         <span
           data-slot="float-button-badge"
-          className="absolute -right-1 -top-1 flex h-5 min-w-5 items-center justify-center rounded-full bg-destructive px-1 text-xxs font-medium leading-none text-destructive-foreground"
+          className="absolute -top-1 -right-1 flex h-5 min-w-5 items-center justify-center rounded-full bg-destructive px-1 text-xxs leading-none font-medium text-destructive-foreground"
         >
           {badge}
         </span>

package/src/components/form/index.tsx

@@ -198,7 +198,7 @@ function FormMessage({
       id={formMessageId}
       role="alert"
       data-slot="field-error"
-      className={cn('text-xs font-normal text-destructive -mt-1', className)}
+      className={cn('-mt-1 text-xs font-normal text-destructive', className)}
       {...props}
     >
       {body}

package/src/components/form/meta.md

@@ -14,3 +14,122 @@ react-hook-form 极薄封装 — 将 RHF FormProvider / Controller 与 Field 系
 - 表单场景需要 RHF 表单级状态管理
 - 需要自动 aria-invalid / aria-describedby 注入
 - 需要字段级 error 联动（自动标红 + 错误信息展示）
+
+## 示例
+
+### Basic
+
+基础用法:用户名 + 邮箱字段,含校验规则与描述文案。
+
+```tsx
+<Form {...form}>
+  <form
+    onSubmit={form.handleSubmit((data) => console.log(data))}
+    className="flex w-80 flex-col gap-4"
+  >
+    <FormField
+      name="username"
+      rules={{ required: '用户名不能为空' }}
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>用户名</FormLabel>
+          <FormControl>
+            <Input placeholder="请输入用户名" {...field} />
+          </FormControl>
+          <FormDescription>这是你的公开显示名称。</FormDescription>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <FormField
+      name="email"
+      rules={{
+        required: '邮箱不能为空',
+        pattern: { value: /^\S+@\S+$/i, message: '邮箱格式不正确' },
+      }}
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>邮箱</FormLabel>
+          <FormControl>
+            <Input
+              type="email"
+              placeholder="name@example.com"
+              {...field}
+            />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <Button type="submit">提交</Button>
+  </form>
+</Form>
+```
+
+### ErrorState
+
+错误状态:必填 + minLength 校验,提交时联动 `data-invalid` 与 FormMessage。
+
+```tsx
+<Form {...form}>
+  <form
+    onSubmit={form.handleSubmit((data) => console.log(data))}
+    className="flex w-80 flex-col gap-4"
+  >
+    <FormField
+      name="name"
+      rules={{
+        required: '此字段必填',
+        minLength: { value: 2, message: '最少 2 个字符' },
+      }}
+      render={({ field }) => (
+        <FormItem>
+          <FormLabel>姓名</FormLabel>
+          <FormControl>
+            <Input placeholder="请输入姓名" {...field} />
+          </FormControl>
+          <FormMessage />
+        </FormItem>
+      )}
+    />
+    <Button type="submit">验证</Button>
+  </form>
+</Form>
+```
+
+### Horizontal
+
+水平布局:FormItem `orientation="responsive"`,标签与控件并排。
+
+```tsx
+<Form {...form}>
+  <form
+    onSubmit={form.handleSubmit((data) => console.log(data))}
+    className="flex w-96 flex-col gap-4"
+  >
+    <FormField
+      name="firstName"
+      render={({ field }) => (
+        <FormItem orientation="responsive">
+          <FormLabel>姓</FormLabel>
+          <FormControl>
+            <Input {...field} />
+          </FormControl>
+        </FormItem>
+      )}
+    />
+    <FormField
+      name="lastName"
+      render={({ field }) => (
+        <FormItem orientation="responsive">
+          <FormLabel>名</FormLabel>
+          <FormControl>
+            <Input {...field} />
+          </FormControl>
+        </FormItem>
+      )}
+    />
+    <Button type="submit">提交</Button>
+  </form>
+</Form>
+```

package/src/components/hover-card/index.tsx

@@ -70,7 +70,7 @@ function HoverCardContent({
         align={align}
         sideOffset={sideOffset}
         className={cn(
-          'group/hover-card-content relative z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md bg-popover p-2.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          'group/hover-card-content relative z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md bg-popover p-2.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
           className,
         )}
         {...props}

package/src/components/hover-card/meta.md

@@ -27,6 +27,27 @@
 
 ## 示例
 
+### AllPositions
+
+12 方向矩阵：side × align 组合。
+
+```tsx
+<div className="grid grid-cols-3 gap-4">
+  {sides.flatMap((side) =>
+    aligns.map((align) => (
+      <HoverCard key={`${side}-${align}`}>
+        <HoverCardTrigger asChild>
+          <Button>{`${side}-${align}`}</Button>
+        </HoverCardTrigger>
+        <HoverCardContent side={side} align={align}>
+          <p className="text-muted-foreground">{`${side} / ${align}`}</p>
+        </HoverCardContent>
+      </HoverCard>
+    )),
+  )}
+</div>
+```
+
 ### CustomDelay
 
 自定义打开 / 关闭延时。

package/src/components/input/meta.md

@@ -44,6 +44,14 @@
 </div>
 ```
 
+### Invalid
+
+通过 `aria-invalid` 属性标记错误状态，通常用于表单校验失败时。
+
+```tsx
+<Input placeholder="请输入邮箱" aria-invalid="true" />
+```
+
 ### Widths
 
 Input 默认宽度为 100%，可通过 `className` 控制宽度。
@@ -55,3 +63,11 @@ Input 默认宽度为 100%，可通过 `className` 控制宽度。
   <Input className="w-full" placeholder="w-full (默认)" />
 </div>
 ```
+
+### ReadOnly
+
+`readOnly` 属性让输入框只读，用户可复制但无法编辑。
+
+```tsx
+<Input readOnly value="只读内容，可复制" />
+```

package/src/components/input-group/index.tsx

@@ -278,7 +278,7 @@ function InputGroupShowCount({
       data-slot="input-group-show-count"
       data-overflow={overflow || undefined}
       className={cn(
-        'flex items-center text-xs tabular-nums text-muted-foreground/60 select-none',
+        'flex items-center text-xs text-muted-foreground/60 tabular-nums select-none',
         'data-[overflow]:text-destructive',
         className,
       )}

package/src/components/input-group/meta.md

@@ -59,6 +59,87 @@
 </InputGroup>
 ```
 
+### Search
+
+搜索场景：左侧 SearchIcon + 右侧 InputGroupClear 受控清除按钮。 仅当 value 非空时显示清除按钮。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupAddon>
+    <InputGroupText>
+      <SearchIcon />
+    </InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput
+    placeholder="搜索..."
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+  />
+  <InputGroupAddon align="inline-end">
+    <InputGroupClear
+      visible={value.length > 0}
+      onClick={() => setValue('')}
+    />
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Clear
+
+一键清除：使用 `InputGroupClear` helper 受控显示清除按钮， 仅当 `visible` 为 true 时渲染，点击由父级清空 `value`。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupInput
+    placeholder="输入后展示清除按钮"
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+  />
+  <InputGroupAddon align="inline-end">
+    <InputGroupClear
+      visible={value.length > 0}
+      onClick={() => setValue('')}
+    />
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Password
+
+密码输入：使用 `InputGroupPasswordToggle` 受控版，由父级同时控制 `type` 与 `visible`。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupInput
+    type={visible ? 'text' : 'password'}
+    placeholder="请输入密码"
+  />
+  <InputGroupAddon align="inline-end">
+    <InputGroupPasswordToggle
+      visible={visible}
+      onVisibleChange={setVisible}
+    />
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Currency
+
+金额输入：后置货币符号，展示带格式化的数值输入。
+
+```tsx
+<InputGroup className="w-64">
+  <InputGroupInput
+    placeholder="请输入金额"
+    value={format(value)}
+    onChange={(e) => setValue(e.target.value.replace(/,/g, ''))}
+  />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>¥</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
 ### Email
 
 邮箱输入：左侧邮件图标 + 右侧域名后缀文本。
@@ -92,6 +173,43 @@
 </InputGroup>
 ```
 
+### WithCount
+
+单行字符计数：使用 `InputGroupShowCount` 显示 `current/max`。 超过 maxLength 时计数自动转 destructive 色。
+
+```tsx
+<InputGroup className="w-80">
+  <InputGroupInput
+    placeholder="请输入标题"
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+    maxLength={max}
+  />
+  <InputGroupAddon align="inline-end">
+    <InputGroupShowCount current={value.length} max={max} />
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### MultilineWithCount
+
+多行 + 字符计数：textarea 配合 `block-end` 对齐的计数行， 对齐 cloud-design `hasLimitHint` 的视觉位置。
+
+```tsx
+<InputGroup className="w-80">
+  <InputGroupTextarea
+    placeholder="请输入备注..."
+    value={value}
+    onChange={(e) => setValue(e.target.value)}
+    rows={4}
+    className="field-sizing-fixed"
+  />
+  <InputGroupAddon align="block-end" className="justify-end">
+    <InputGroupShowCount current={value.length} max={max} />
+  </InputGroupAddon>
+</InputGroup>
+```
+
 ### Disabled
 
 禁用状态的输入框组合。