@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/field/meta.md

@@ -0,0 +1,283 @@
+# Field
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+表单字段 Field
+表单控件的包装器，提供标签、描述和错误展示区域。
+
+## 使用场景
+
+- 表单控件的标准包装（label + input + error）
+- 表单验证错误展示
+- 必填项 / 可选项标记
+
+## 示例
+
+### Responsive
+
+响应式布局（推荐默认用法）。
+
+```tsx
+<FieldGroup>
+  <Field orientation="responsive">
+    <FieldLabel htmlFor="r-name" required>
+      名称
+    </FieldLabel>
+    <Input id="r-name" placeholder="请输入名称" />
+  </Field>
+  <Field orientation="responsive">
+    <FieldLabel htmlFor="r-desc">描述</FieldLabel>
+    <FieldContent>
+      <Input id="r-desc" placeholder="请输入描述" />
+      <FieldDescription>对该资源的简要说明。</FieldDescription>
+    </FieldContent>
+  </Field>
+  <Field orientation="responsive">
+    <FieldLabel>端口</FieldLabel>
+    <InputNumber placeholder="8080" min={1} max={65535} />
+  </Field>
+  <Field orientation="responsive">
+    <FieldLabel>创建日期</FieldLabel>
+    <DatePicker placeholder="选择日期" />
+  </Field>
+  <Field orientation="responsive" data-invalid="true">
+    <FieldLabel htmlFor="r-ip" required>
+      IP 地址
+    </FieldLabel>
+    <FieldContent>
+      <InputIP id="r-ip" aria-invalid="true" defaultValue="999.0.0.1" />
+      <FieldError>请输入合法的 IP 地址。</FieldError>
+    </FieldContent>
+  </Field>
+</FieldGroup>
+```
+
+### WithError
+
+带错误提示的字段。
+
+```tsx
+<Field data-invalid="true">
+  <FieldLabel htmlFor="username">用户名</FieldLabel>
+  <Input id="username" aria-invalid="true" defaultValue="ab" />
+  <FieldError>用户名至少需要 3 个字符。</FieldError>
+</Field>
+```
+
+### RequiredField
+
+必填字段。
+
+```tsx
+<Field>
+  <FieldLabel htmlFor="req-name" required>
+    名称
+  </FieldLabel>
+  <Input id="req-name" placeholder="请输入名称" />
+</Field>
+```
+
+### GroupedFields
+
+分组表单（FieldSet + FieldLegend）。
+
+```tsx
+<FieldSet>
+  <FieldLegend>基本信息</FieldLegend>
+  <Field>
+    <FieldLabel htmlFor="g-name" required>
+      名称
+    </FieldLabel>
+    <Input id="g-name" placeholder="请输入名称" />
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="g-desc">描述</FieldLabel>
+    <Input id="g-desc" placeholder="请输入描述" />
+    <FieldDescription>对该资源的简要说明。</FieldDescription>
+  </Field>
+</FieldSet>
+```
+
+### Inset
+
+内嵌模式：Label 嵌入输入框边框内。
+
+```tsx
+<FieldGroup>
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel required>输入框</FieldLabel>
+      <Input placeholder="请输入内容" />
+    </FieldInsetBox>
+    <FieldDescription>我是描述文案</FieldDescription>
+  </Field>
+
+  <Field orientation="inset" data-invalid="true">
+    <FieldInsetBox>
+      <FieldLabel>输入框</FieldLabel>
+      <Input aria-invalid="true" defaultValue="错误值" />
+    </FieldInsetBox>
+    <FieldError>这里是一段错误信息</FieldError>
+  </Field>
+
+  <Field orientation="inset" data-invalid="true">
+    <FieldInsetBox>
+      <FieldLabel required>选择器</FieldLabel>
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="请选择" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="a">选项 A</SelectItem>
+          <SelectItem value="b">选项 B</SelectItem>
+        </SelectContent>
+      </Select>
+    </FieldInsetBox>
+    <FieldError>这里是一段错误信息</FieldError>
+    <FieldDescription>我是描述文案</FieldDescription>
+  </Field>
+</FieldGroup>
+```
+
+### InsetAll
+
+Inset 模式 —— 各类输入控件在 FieldInsetBox 下的表现枚举。
+
+```tsx
+<FieldGroup>
+  {/* Input */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>输入框</FieldLabel>
+      <Input placeholder="请输入" />
+    </FieldInsetBox>
+  </Field>
+
+  {/* Select */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>选择器</FieldLabel>
+      <Select>
+        <SelectTrigger>
+          <SelectValue placeholder="请选择" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="a">选项 A</SelectItem>
+          <SelectItem value="b">选项 B</SelectItem>
+          <SelectItem value="c">选项 C</SelectItem>
+        </SelectContent>
+      </Select>
+    </FieldInsetBox>
+  </Field>
+
+  {/* InputNumber - normal */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>数量</FieldLabel>
+      <InputNumber placeholder="0" min={0} max={100} />
+    </FieldInsetBox>
+  </Field>
+
+  {/* InputIP */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>IP</FieldLabel>
+      <InputIP />
+    </FieldInsetBox>
+  </Field>
+
+  {/* DatePicker */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>日期</FieldLabel>
+      <DatePicker placeholder="选择日期" />
+    </FieldInsetBox>
+  </Field>
+
+  {/* TimePicker */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>时间</FieldLabel>
+      <TimePicker placeholder="选择时间" />
+    </FieldInsetBox>
+  </Field>
+
+  {/* DateRangePicker */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>日期范围</FieldLabel>
+      <DateRangePicker />
+    </FieldInsetBox>
+  </Field>
+
+  {/* TimeRangePicker */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>时间范围</FieldLabel>
+      <TimeRangePicker />
+    </FieldInsetBox>
+  </Field>
+
+  {/* TreeSelect */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>树选择</FieldLabel>
+      <TreeSelect
+        treeData={[
+          {
+            value: 'frontend',
+            label: '前端',
+            children: [
+              { value: 'react', label: 'React' },
+              { value: 'vue', label: 'Vue' },
+            ],
+          },
+          {
+            value: 'backend',
+            label: '后端',
+            children: [
+              { value: 'node', label: 'Node.js' },
+              { value: 'go', label: 'Go' },
+            ],
+          },
+        ]}
+      />
+    </FieldInsetBox>
+  </Field>
+
+  {/* CascaderSelect */}
+  <Field orientation="inset">
+    <FieldInsetBox>
+      <FieldLabel>级联</FieldLabel>
+      <CascaderSelect
+        options={[
+          {
+            value: 'zhejiang',
+            label: '浙江',
+            children: [
+              {
+                value: 'hangzhou',
+                label: '杭州',
+                children: [{ value: 'xihu', label: '西湖区' }],
+              },
+            ],
+          },
+          {
+            value: 'jiangsu',
+            label: '江苏',
+            children: [
+              {
+                value: 'nanjing',
+                label: '南京',
+                children: [{ value: 'xuanwu', label: '玄武区' }],
+              },
+            ],
+          },
+        ]}
+      />
+    </FieldInsetBox>
+  </Field>
+</FieldGroup>
+```

package/src/components/field/stories.tsx

@@ -0,0 +1,327 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Field,
+  FieldInsetBox,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+  FieldContent,
+} from './index';
+import { Input } from '@/components/input';
+import { InputNumber } from '@/components/input-number';
+import { InputIP } from '@/components/input-ip';
+import { DatePicker, DateRangePicker } from '@/components/date-picker';
+import { TimePicker, TimeRangePicker } from '@/components/time-picker';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/select';
+import { TreeSelect } from '@/components/tree-select';
+import { CascaderSelect } from '@/components/cascader-select';
+
+const meta: Meta<typeof Field> = {
+  title: '数据录入 · Data Entry/Field 表单字段',
+  component: Field,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '表单字段 —— 为输入控件提供标签、描述、错误展示区域的包装器。',
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 基础表单字段，包含标签、输入框和描述。 */
+export const Default: Story = {
+  render: () => (
+    <Field>
+      <FieldLabel htmlFor="email">邮箱地址</FieldLabel>
+      <Input id="email" type="email" placeholder="name@example.com" />
+      <FieldDescription>我们不会公开您的邮箱。</FieldDescription>
+    </Field>
+  ),
+};
+
+/** 响应式布局（推荐默认用法）。 */
+export const Responsive: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '基于 CSS Grid 12 栅格 + 容器查询（断点 480px）：\n' +
+          '- 容器 ≥ 480px：水平 grid 布局，label 占 2 列（≈ 24 栅格中的 4），组件占 8 列（≈ 24 栅格中的 16），右侧空 2 列\n' +
+          '- 容器 < 480px：自动切换为垂直布局，label 和组件均满宽\n\n' +
+          '需要包裹在 FieldGroup 中（提供 `@container` 上下文）。\n' +
+          '自定义比例：在 FieldLabel 上覆盖 `className="@[30rem]/field-group:col-span-3"` 即可调整。',
+      },
+    },
+  },
+  render: () => (
+    <FieldGroup>
+      <Field orientation="responsive">
+        <FieldLabel htmlFor="r-name" required>
+          名称
+        </FieldLabel>
+        <Input id="r-name" placeholder="请输入名称" />
+      </Field>
+      <Field orientation="responsive">
+        <FieldLabel htmlFor="r-desc">描述</FieldLabel>
+        <FieldContent>
+          <Input id="r-desc" placeholder="请输入描述" />
+          <FieldDescription>对该资源的简要说明。</FieldDescription>
+        </FieldContent>
+      </Field>
+      <Field orientation="responsive">
+        <FieldLabel>端口</FieldLabel>
+        <InputNumber placeholder="8080" min={1} max={65535} />
+      </Field>
+      <Field orientation="responsive">
+        <FieldLabel>创建日期</FieldLabel>
+        <DatePicker placeholder="选择日期" />
+      </Field>
+      <Field orientation="responsive" data-invalid="true">
+        <FieldLabel htmlFor="r-ip" required>
+          IP 地址
+        </FieldLabel>
+        <FieldContent>
+          <InputIP id="r-ip" aria-invalid="true" defaultValue="999.0.0.1" />
+          <FieldError>请输入合法的 IP 地址。</FieldError>
+        </FieldContent>
+      </Field>
+    </FieldGroup>
+  ),
+};
+
+/** 带错误提示的字段。 */
+export const WithError: Story = {
+  render: () => (
+    <Field data-invalid="true">
+      <FieldLabel htmlFor="username">用户名</FieldLabel>
+      <Input id="username" aria-invalid="true" defaultValue="ab" />
+      <FieldError>用户名至少需要 3 个字符。</FieldError>
+    </Field>
+  ),
+};
+
+/** 必填字段。 */
+export const RequiredField: Story = {
+  render: () => (
+    <Field>
+      <FieldLabel htmlFor="req-name" required>
+        名称
+      </FieldLabel>
+      <Input id="req-name" placeholder="请输入名称" />
+    </Field>
+  ),
+};
+
+/** 分组表单（FieldSet + FieldLegend）。 */
+export const GroupedFields: Story = {
+  render: () => (
+    <FieldSet>
+      <FieldLegend>基本信息</FieldLegend>
+      <Field>
+        <FieldLabel htmlFor="g-name" required>
+          名称
+        </FieldLabel>
+        <Input id="g-name" placeholder="请输入名称" />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="g-desc">描述</FieldLabel>
+        <Input id="g-desc" placeholder="请输入描述" />
+        <FieldDescription>对该资源的简要说明。</FieldDescription>
+      </Field>
+    </FieldSet>
+  ),
+};
+
+/** 内嵌模式：Label 嵌入输入框边框内。 */
+export const Inset: Story = {
+  render: () => (
+    <FieldGroup>
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel required>输入框</FieldLabel>
+          <Input placeholder="请输入内容" />
+        </FieldInsetBox>
+        <FieldDescription>我是描述文案</FieldDescription>
+      </Field>
+
+      <Field orientation="inset" data-invalid="true">
+        <FieldInsetBox>
+          <FieldLabel>输入框</FieldLabel>
+          <Input aria-invalid="true" defaultValue="错误值" />
+        </FieldInsetBox>
+        <FieldError>这里是一段错误信息</FieldError>
+      </Field>
+
+      <Field orientation="inset" data-invalid="true">
+        <FieldInsetBox>
+          <FieldLabel required>选择器</FieldLabel>
+          <Select>
+            <SelectTrigger>
+              <SelectValue placeholder="请选择" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="a">选项 A</SelectItem>
+              <SelectItem value="b">选项 B</SelectItem>
+            </SelectContent>
+          </Select>
+        </FieldInsetBox>
+        <FieldError>这里是一段错误信息</FieldError>
+        <FieldDescription>我是描述文案</FieldDescription>
+      </Field>
+    </FieldGroup>
+  ),
+};
+
+/** Inset 模式 —— 各类输入控件在 FieldInsetBox 下的表现枚举。 */
+export const InsetAll: Story = {
+  render: () => (
+    <FieldGroup>
+      {/* Input */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>输入框</FieldLabel>
+          <Input placeholder="请输入" />
+        </FieldInsetBox>
+      </Field>
+
+      {/* Select */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>选择器</FieldLabel>
+          <Select>
+            <SelectTrigger>
+              <SelectValue placeholder="请选择" />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="a">选项 A</SelectItem>
+              <SelectItem value="b">选项 B</SelectItem>
+              <SelectItem value="c">选项 C</SelectItem>
+            </SelectContent>
+          </Select>
+        </FieldInsetBox>
+      </Field>
+
+      {/* InputNumber - normal */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>数量</FieldLabel>
+          <InputNumber placeholder="0" min={0} max={100} />
+        </FieldInsetBox>
+      </Field>
+
+      {/* InputIP */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>IP</FieldLabel>
+          <InputIP />
+        </FieldInsetBox>
+      </Field>
+
+      {/* DatePicker */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>日期</FieldLabel>
+          <DatePicker placeholder="选择日期" />
+        </FieldInsetBox>
+      </Field>
+
+      {/* TimePicker */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>时间</FieldLabel>
+          <TimePicker placeholder="选择时间" />
+        </FieldInsetBox>
+      </Field>
+
+      {/* DateRangePicker */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>日期范围</FieldLabel>
+          <DateRangePicker />
+        </FieldInsetBox>
+      </Field>
+
+      {/* TimeRangePicker */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>时间范围</FieldLabel>
+          <TimeRangePicker />
+        </FieldInsetBox>
+      </Field>
+
+      {/* TreeSelect */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>树选择</FieldLabel>
+          <TreeSelect
+            treeData={[
+              {
+                value: 'frontend',
+                label: '前端',
+                children: [
+                  { value: 'react', label: 'React' },
+                  { value: 'vue', label: 'Vue' },
+                ],
+              },
+              {
+                value: 'backend',
+                label: '后端',
+                children: [
+                  { value: 'node', label: 'Node.js' },
+                  { value: 'go', label: 'Go' },
+                ],
+              },
+            ]}
+          />
+        </FieldInsetBox>
+      </Field>
+
+      {/* CascaderSelect */}
+      <Field orientation="inset">
+        <FieldInsetBox>
+          <FieldLabel>级联</FieldLabel>
+          <CascaderSelect
+            options={[
+              {
+                value: 'zhejiang',
+                label: '浙江',
+                children: [
+                  {
+                    value: 'hangzhou',
+                    label: '杭州',
+                    children: [{ value: 'xihu', label: '西湖区' }],
+                  },
+                ],
+              },
+              {
+                value: 'jiangsu',
+                label: '江苏',
+                children: [
+                  {
+                    value: 'nanjing',
+                    label: '南京',
+                    children: [{ value: 'xuanwu', label: '玄武区' }],
+                  },
+                ],
+              },
+            ]}
+          />
+        </FieldInsetBox>
+      </Field>
+    </FieldGroup>
+  ),
+};