@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/field/field.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Field,
   FieldLabel,
@@ -7,25 +7,30 @@ import {
   FieldGroup,
   FieldSet,
   FieldLegend,
+  FieldSection,
+  FieldActions,
 } from './field';
 import { Input } from '@/components/input/input';
 import { Switch } from '@/components/switch/switch';
 import { Button } from '@/components/button/button';
 
 const meta: Meta<typeof Field> = {
-  title: '表单与输入 · Form/Field',
+  title: '数据录入 · Data Entry/Field',
   component: Field,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '通用表单字段抽象 — 比 Form 更通用(Form 强绑 RHF;Field 跟任何状态管理都能搭)。7 个语义槽:Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend。shadcn 2025-10 新增,与现有 Form 共存。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '通用表单字段抽象 — 比 Form 更通用（Form 强绑 RHF；Field 跟任何状态管理都能搭）。7 个语义槽：Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend。必填 `*` **后置**在文字和 tooltip icon 右侧（顺序为 `文字 ⓘ *`），对齐设计规范。shadcn 2025-10 新增，与现有 Form 共存。',
       },
     },
   },
   argTypes: {
-    orientation: { control: 'inline-radio', options: ['vertical', 'horizontal'] },
+    orientation: {
+      control: 'inline-radio',
+      options: ['vertical', 'horizontal'],
+    },
     invalid: { control: 'boolean' },
   },
   args: { orientation: 'vertical', invalid: false },
@@ -47,6 +52,79 @@ export const Playground: Story = {
   ),
 };
 
+/**
+ * **Accessibility(a11y 完整链路)** — `invalid` 是 Field 上的单一真值,
+ * 自动驱动 FieldLabel 着色 / FieldError 可见 / 子控件 ring 染红。
+ * 业务侧需同时给 input 设置 `aria-invalid` / `aria-required` / `aria-describedby` 确保屏幕阅读器叙述完整。
+ */
+export const Accessibility: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          'Field 是 a11y 单一真值:`invalid={true}` 自动驱动 FieldLabel 文字色 → destructive、内部所有控件 ring → destructive、FieldError 可见(role="alert")。业务层把 `aria-invalid` / `aria-required` / `aria-describedby` 设在 input 上保证屏幕阅读器叙述完整。',
+      },
+    },
+  },
+  render: () => (
+    <FieldGroup className="w-80">
+      <Field invalid>
+        <FieldLabel htmlFor="a11y-email" required>
+          邮箱
+        </FieldLabel>
+        <Input
+          id="a11y-email"
+          type="email"
+          aria-required="true"
+          aria-invalid="true"
+          aria-describedby="a11y-email-desc a11y-email-err"
+          defaultValue="not-an-email"
+        />
+        <FieldDescription id="a11y-email-desc">
+          用于接收登录验证码与订单通知
+        </FieldDescription>
+        <FieldError id="a11y-email-err">
+          邮箱格式不正确,请检查后重新输入
+        </FieldError>
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="a11y-name" required>
+          姓名
+        </FieldLabel>
+        <Input
+          id="a11y-name"
+          aria-required="true"
+          aria-describedby="a11y-name-desc"
+          placeholder="请输入真实姓名"
+        />
+        <FieldDescription id="a11y-name-desc">
+          用于显示在主页与通知中
+        </FieldDescription>
+      </Field>
+    </FieldGroup>
+  ),
+};
+
+/** 必填标记 `*` **后置**在文字和 tooltip icon 右侧（顺序为 `文字 ⓘ *`），对齐设计规范。 */
+export const RequiredPosition: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <FieldGroup className="w-80">
+      <Field>
+        <FieldLabel htmlFor="req-name" required>
+          必填字段
+        </FieldLabel>
+        <Input id="req-name" aria-required="true" placeholder="例：张三" />
+      </Field>
+      <Field>
+        <FieldLabel htmlFor="opt-bio">可选字段</FieldLabel>
+        <Input id="opt-bio" placeholder="选填" />
+      </Field>
+    </FieldGroup>
+  ),
+};
+
 export const Horizontal: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
@@ -92,7 +170,7 @@ export const ServerActionForm: Story = {
       onSubmit={(e) => {
         e.preventDefault();
         const fd = new FormData(e.currentTarget);
-        // eslint-disable-next-line no-alert
+
         alert(`提交: ${JSON.stringify(Object.fromEntries(fd.entries()))}`);
       }}
       className="w-96 space-y-4"
@@ -115,3 +193,305 @@ export const ServerActionForm: Story = {
     </form>
   ),
 };
+
+/** **FieldSection** — 带可选标题的字段分组；多个 section 之间由父容器提供 32px 间距(gap-8)。 */
+export const WithSection: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-[480px] flex-col gap-8">
+      <FieldSection title="基本信息">
+        <Field>
+          <FieldLabel htmlFor="sec-name" required>
+            姓名
+          </FieldLabel>
+          <Input id="sec-name" placeholder="例：张三" />
+        </Field>
+        <Field>
+          <FieldLabel htmlFor="sec-email" required>
+            邮箱
+          </FieldLabel>
+          <Input id="sec-email" type="email" />
+        </Field>
+      </FieldSection>
+      <FieldSection title="通知设置">
+        <Field orientation="horizontal">
+          <FieldLabel htmlFor="sec-notify" className="min-w-28 pt-2">
+            邮件通知
+          </FieldLabel>
+          <div className="flex-1">
+            <Switch id="sec-notify" defaultChecked />
+            <FieldDescription className="mt-1">
+              有重要事件时给您发邮件
+            </FieldDescription>
+          </div>
+        </Field>
+      </FieldSection>
+    </div>
+  ),
+};
+
+/** **FieldActions** — 表单底部操作区；支持 `inline`(跟随表单流) 与 `sticky`(吸底带分割线)。 */
+export const WithActions: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-[640px] gap-8">
+      <div className="flex-1">
+        <p className="mb-3 text-xs text-muted-foreground">position="inline"</p>
+        <FieldGroup>
+          <Field>
+            <FieldLabel htmlFor="act-name">姓名</FieldLabel>
+            <Input id="act-name" />
+          </Field>
+          <FieldActions>
+            <Button variant="outline">取消</Button>
+            <Button>保存</Button>
+          </FieldActions>
+        </FieldGroup>
+      </div>
+      <div className="flex-1">
+        <p className="mb-3 text-xs text-muted-foreground">position="sticky"</p>
+        <div className="relative h-[260px] overflow-y-auto rounded-md border border-border">
+          <div className="flex flex-col gap-5 p-4">
+            <Field>
+              <FieldLabel htmlFor="sticky-1">字段 A</FieldLabel>
+              <Input id="sticky-1" />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="sticky-2">字段 B</FieldLabel>
+              <Input id="sticky-2" />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="sticky-3">字段 C</FieldLabel>
+              <Input id="sticky-3" />
+            </Field>
+            <Field>
+              <FieldLabel htmlFor="sticky-4">字段 D</FieldLabel>
+              <Input id="sticky-4" />
+            </Field>
+            <FieldActions position="sticky" className="-mx-4 px-4">
+              <Button variant="outline">取消</Button>
+              <Button>保存</Button>
+            </FieldActions>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+/** **FieldActions.container** — 4 种按钮容器预设,自动配齐 position/align/alignWithInput(对齐规范 §六)。 */
+export const ActionsContainerPresets: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const presets: Array<{
+      key: 'page' | 'page-stepper' | 'modal' | 'drawer';
+      label: string;
+      desc: string;
+    }> = [
+      {
+        key: 'page',
+        label: 'page',
+        desc: '页面基础/分组:inline + start + 基线对齐',
+      },
+      {
+        key: 'page-stepper',
+        label: 'page-stepper',
+        desc: '页面分步:sticky + start',
+      },
+      { key: 'modal', label: 'modal', desc: '弹窗:inline + end' },
+      { key: 'drawer', label: 'drawer', desc: '抽屉:sticky + start' },
+    ];
+    return (
+      <div className="grid w-full grid-cols-2 gap-6">
+        {presets.map((p) => (
+          <div
+            key={p.key}
+            className="rounded-md border border-border bg-card p-4"
+          >
+            <p className="mb-1 text-xs font-medium">{p.label}</p>
+            <p className="mb-3 text-xs text-muted-foreground">{p.desc}</p>
+            <FieldGroup>
+              <Field orientation="horizontal" inputWidth="m">
+                <FieldLabel htmlFor={`ct-${p.key}-name`} className="min-w-20">
+                  名称
+                </FieldLabel>
+                <Input
+                  id={`ct-${p.key}-name`}
+                  style={{ width: 'var(--field-input-width)' }}
+                />
+              </Field>
+              <FieldActions container={p.key}>
+                <Button variant="outline">取消</Button>
+                <Button>提交</Button>
+              </FieldActions>
+            </FieldGroup>
+          </div>
+        ))}
+      </div>
+    );
+  },
+};
+
+/** **详情态(density="detail")** — 12px 行距,纯展示无录入(规范 §3.5)。 */
+export const DetailDensity: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const rows: Array<{ label: string; value: string }> = [
+      { label: '用户组', value: 'shiyichenyutestgrounp' },
+      { label: '显示名称', value: 'Anthony Edward「Tony」Stark' },
+      { label: '备注', value: 'Iron Man · 这里是备注' },
+      { label: '所属部门', value: 'zhao.yu > 公共部门 > 财务' },
+      { label: 'UID', value: '1231231234567' },
+      { label: '创建时间', value: '2018-09-23 19:34:12' },
+    ];
+    return (
+      <div className="grid w-full grid-cols-2 gap-8">
+        <div className="rounded-md border border-border bg-card p-4">
+          <p className="mb-3 text-xs font-medium">
+            density="normal"(20px 行距 · 表单/混合)
+          </p>
+          <FieldGroup density="normal">
+            {rows.map((r) => (
+              <Field key={r.label} orientation="horizontal" inputWidth="m">
+                <FieldLabel className="min-w-24 shrink-0 text-muted-foreground">
+                  {r.label}
+                </FieldLabel>
+                <span className="text-xs">{r.value}</span>
+              </Field>
+            ))}
+          </FieldGroup>
+        </div>
+        <div className="rounded-md border border-border bg-card p-4">
+          <p className="mb-3 text-xs font-medium">
+            density="detail"(12px 行距 · 详情页)
+          </p>
+          <FieldGroup density="detail">
+            {rows.map((r) => (
+              <Field key={r.label} orientation="horizontal" inputWidth="m">
+                <FieldLabel className="min-w-24 shrink-0 text-muted-foreground">
+                  {r.label}
+                </FieldLabel>
+                <span className="text-xs">{r.value}</span>
+              </Field>
+            ))}
+          </FieldGroup>
+        </div>
+      </div>
+    );
+  },
+};
+
+/** **响应式 orientation** — 拖动 viewport,< 432px 自动改上下结构(规范 §4.2)。 */
+export const ResponsiveOrientation: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          'orientation 接受 ResponsiveValue:`{ base: "vertical", xs: "horizontal" }` 表示 <432 单栏上下 / ≥432 左右。底层走 useBreakpoint。',
+      },
+    },
+  },
+  render: () => (
+    <FieldGroup className="w-full">
+      <Field orientation={{ base: 'vertical', xs: 'horizontal' }} inputWidth="m">
+        <FieldLabel htmlFor="resp-name" className="min-w-24" required>
+          名称
+        </FieldLabel>
+        <Input
+          id="resp-name"
+          placeholder="<432 在下,≥432 在右"
+          style={{ width: 'var(--field-input-width)' }}
+        />
+      </Field>
+      <Field orientation={{ base: 'vertical', xs: 'horizontal' }} inputWidth="m">
+        <FieldLabel htmlFor="resp-email" className="min-w-24" required>
+          邮箱
+        </FieldLabel>
+        <Input
+          id="resp-email"
+          type="email"
+          placeholder="you@example.com"
+          style={{ width: 'var(--field-input-width)' }}
+        />
+      </Field>
+    </FieldGroup>
+  ),
+};
+
+/** **inputWidth** — 5 档宽度系统(104 / 216 / 328 / 440 / 552 px)，子组件可消费 `--field-input-width` CSS 变量。 */
+export const WithInputWidth: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <FieldGroup className="w-[600px]">
+      {(['xs', 's', 'm', 'l', 'xl'] as const).map((size) => (
+        <Field key={size} inputWidth={size}>
+          <FieldLabel htmlFor={`w-${size}`}>inputWidth = {size}</FieldLabel>
+          <Input
+            id={`w-${size}`}
+            placeholder={`宽度档位 ${size}`}
+            style={{ width: 'var(--field-input-width)' }}
+          />
+        </Field>
+      ))}
+    </FieldGroup>
+  ),
+};
+
+/** 组合示例 — Section 分组 + inputWidth 宽度档位 + Actions 操作区。 */
+export const FullFormExample: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex w-[560px] flex-col gap-8">
+      <FieldSection title="账号信息">
+        <Field inputWidth="m">
+          <FieldLabel htmlFor="full-name" required>
+            姓名
+          </FieldLabel>
+          <Input
+            id="full-name"
+            placeholder="例：张三"
+            style={{ width: 'var(--field-input-width)' }}
+          />
+          <FieldDescription>用于显示在主页与通知中</FieldDescription>
+        </Field>
+        <Field inputWidth="l" invalid>
+          <FieldLabel htmlFor="full-email" required>
+            邮箱
+          </FieldLabel>
+          <Input
+            id="full-email"
+            type="email"
+            defaultValue="invalid@"
+            style={{ width: 'var(--field-input-width)' }}
+          />
+          <FieldError>邮箱格式不正确</FieldError>
+        </Field>
+      </FieldSection>
+      <FieldSection title="偏好设置">
+        <Field inputWidth="s">
+          <FieldLabel htmlFor="full-nick">昵称</FieldLabel>
+          <Input
+            id="full-nick"
+            style={{ width: 'var(--field-input-width)' }}
+          />
+        </Field>
+        <Field orientation="horizontal">
+          <FieldLabel htmlFor="full-notify" className="min-w-28 pt-2">
+            邮件通知
+          </FieldLabel>
+          <div className="flex-1">
+            <Switch id="full-notify" defaultChecked />
+            <FieldDescription className="mt-1">
+              有重要事件时给您发邮件
+            </FieldDescription>
+          </div>
+        </Field>
+      </FieldSection>
+      <FieldActions>
+        <Button variant="outline">取消</Button>
+        <Button>保存</Button>
+      </FieldActions>
+    </div>
+  ),
+};