@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/alert/index.tsx

@@ -0,0 +1,220 @@
+/**
+ * 警告提示 Alert
+ *
+ * 用于在页面或区域内展示静态的反馈提示，提供五档语义色与可关闭、操作区等能力。
+ * 不包含弹出能力（Toast）— 弹出式反馈请使用 Sonner。
+ *
+ * @when
+ * - 操作完成后的成功 / 失败反馈（非弹出形式）
+ * - 页面或卡片内的系统公告、风险提示
+ * - 表单顶部的统一校验/帮助说明
+ *
+ * 组合结构：Alert > AlertIcon + AlertTitle + AlertDescription + AlertAction
+ */
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import {
+  ErrorFilledIcon,
+  HelpFilledIcon,
+  InfoFilledIcon,
+  SuccessFilledIcon,
+  WarningFilledIcon,
+} from '@/components/icon';
+
+const alertVariants = cva(
+  'group/alert relative grid w-full grid-cols-[auto_1fr] items-center gap-x-2 rounded-md p-2 text-left text-foreground has-data-[slot=alert-title]:items-start has-data-[slot=alert-action]:pr-18 has-data-[slot=alert-close]:pr-7',
+  {
+    variants: {
+      variant: {
+        info: 'border border-info-bg bg-info-bg',
+        success: 'border border-success-bg bg-success-bg',
+        warning: 'border border-warning-bg bg-warning-bg',
+        destructive: 'border border-destructive-bg bg-destructive-bg',
+        help: 'border border-border border-help-bg bg-help-bg',
+      },
+    },
+    defaultVariants: {
+      variant: 'info',
+    },
+  },
+);
+
+type AlertVariant = NonNullable<VariantProps<typeof alertVariants>['variant']>;
+
+/* 面性状态图标映射（外圈 fill-current，由外层 text-{variant} 控色） */
+const FILLED_STATE_ICONS: Record<
+  AlertVariant,
+  React.ComponentType<{ className?: string }>
+> = {
+  info: InfoFilledIcon,
+  success: SuccessFilledIcon,
+  warning: WarningFilledIcon,
+  destructive: ErrorFilledIcon,
+  help: HelpFilledIcon,
+};
+
+/* 状态图标色类，供 currentColor 控色 */
+const ICON_TONE_CLASS: Record<AlertVariant, string> = {
+  info: 'text-info',
+  success: 'text-success',
+  warning: 'text-warning',
+  destructive: 'text-destructive',
+  help: 'text-help',
+};
+
+export interface AlertProps
+  extends Omit<React.ComponentProps<'div'>, 'title'>,
+    VariantProps<typeof alertVariants> {
+  /** 反馈语义色 — info 信息（默认）/ success 成功 / warning 警告 / destructive 错误 / help 帮助 */
+  variant?: AlertVariant;
+  /** 是否显示关闭按钮 */
+  closable?: boolean;
+  /** 关闭按钮点击回调 */
+  onClose?: (event: React.MouseEvent<HTMLButtonElement>) => void;
+  /** 默认是否显示（仅非受控生效），关闭后组件渲染 null */
+  defaultOpen?: boolean;
+  /** 是否在未提供 AlertIcon 时按 variant 自动注入默认面性图标 */
+  showIcon?: boolean;
+}
+
+function Alert({
+  className,
+  variant = 'info',
+  closable = false,
+  onClose,
+  defaultOpen = true,
+  showIcon = true,
+  children,
+  ...props
+}: AlertProps) {
+  const [open, setOpen] = React.useState(defaultOpen);
+
+  if (!open) return null;
+
+  // 子节点中是否已经包含自定义 AlertIcon（按 displayName 识别）
+  const hasCustomIcon = React.Children.toArray(children).some(
+    (child) =>
+      React.isValidElement(child) &&
+      (child.type as { displayName?: string })?.displayName === 'AlertIcon',
+  );
+
+  const resolvedVariant: AlertVariant = variant ?? 'info';
+  const StateIcon =
+    !hasCustomIcon && showIcon ? FILLED_STATE_ICONS[resolvedVariant] : null;
+
+  const handleClose = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onClose?.(event);
+    setOpen(false);
+  };
+
+  return (
+    <div
+      data-slot="alert"
+      data-variant={resolvedVariant}
+      role="alert"
+      className={cn(alertVariants({ variant }), className)}
+      {...props}
+    >
+      {StateIcon ? (
+        <span
+          data-slot="alert-icon"
+          className={cn(
+            'inline-flex shrink-0',
+            ICON_TONE_CLASS[resolvedVariant],
+          )}
+        >
+          <StateIcon />
+        </span>
+      ) : null}
+      {children}
+      {closable ? (
+        <button
+          type="button"
+          data-slot="alert-close"
+          aria-label="关闭"
+          onClick={handleClose}
+          className="absolute top-1.5 right-1.5 inline-flex size-5 cursor-pointer items-center justify-center rounded-sm text-foreground opacity-60 transition-opacity hover:opacity-100 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
+        >
+          <XIcon className="size-3.5" />
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+/** AlertIcon — 自定义图标承载位（覆盖默认面性状态图标） */
+function AlertIcon({ className, ...props }: React.ComponentProps<'span'>) {
+  return (
+    <span
+      data-slot="alert-icon"
+      className={cn(
+        'inline-flex size-5 shrink-0 items-center justify-center *:[svg]:size-5',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+AlertIcon.displayName = 'AlertIcon';
+
+/** AlertTitle — 14px / 500 / 20px 行高 / 右内边距 12px */
+function AlertTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-title"
+      className={cn(
+        'col-start-2 pr-3 text-sm leading-5 font-medium [&_a]:text-primary [&_a]:hover:text-primary/80',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * AlertDescription — 默认字号字重；
+ * 有 Title 时上 margin 4px、行高 18px（leading-normal）；
+ * 无 Title 时行高 20px（leading-5），与 icon 垂直居中。
+ */
+function AlertDescription({
+  className,
+  ...props
+}: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-description"
+      className={cn(
+        'col-start-2 text-xs leading-5 text-muted-foreground group-has-data-[slot=alert-title]/alert:mt-1 group-has-data-[slot=alert-title]/alert:leading-normal [&_a]:text-primary [&_a]:hover:text-primary/80 [&_p:not(:last-child)]:mb-4',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** AlertAction — 操作区，绝对定位右侧居中；与 close 共存时自动让位 */
+function AlertAction({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="alert-action"
+      className={cn(
+        'absolute top-1/2 right-2 -translate-y-1/2',
+        'group-has-data-[slot=alert-close]/alert:right-8',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Alert,
+  AlertIcon,
+  AlertTitle,
+  AlertDescription,
+  AlertAction,
+  alertVariants,
+};

package/src/components/alert/meta.md

@@ -0,0 +1,133 @@
+# Alert
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+警告提示 Alert
+用于在页面或区域内展示静态的反馈提示，提供五档语义色与可关闭、操作区等能力。
+不包含弹出能力（Toast）— 弹出式反馈请使用 Sonner。
+
+## 使用场景
+
+- 操作完成后的成功 / 失败反馈（非弹出形式）
+- 页面或卡片内的系统公告、风险提示
+- 表单顶部的统一校验/帮助说明
+- 组合结构：Alert > AlertIcon + AlertTitle + AlertDescription + AlertAction
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `AlertVariant` | – | – | 反馈语义色 — info 信息（默认）/ success 成功 / warning 警告 / destructive 错误 / help 帮助 |
+| `closable` | `boolean` | – | – | 是否显示关闭按钮 |
+| `onClose` | `(event: React.MouseEvent<HTMLButtonElement>) => void` | – | – | 关闭按钮点击回调 |
+| `defaultOpen` | `boolean` | – | – | 默认是否显示（仅非受控生效），关闭后组件渲染 null |
+| `showIcon` | `boolean` | – | – | 是否在未提供 AlertIcon 时按 variant 自动注入默认面性图标 |
+
+## 示例
+
+### Variants
+
+五档语义色
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Alert variant="info">
+    <AlertTitle>Info</AlertTitle>
+    <AlertDescription>Content Content Content Content</AlertDescription>
+  </Alert>
+  <Alert variant="success">
+    <AlertTitle>Success</AlertTitle>
+    <AlertDescription>Content Content Content Content</AlertDescription>
+  </Alert>
+  <Alert variant="warning">
+    <AlertTitle>Warning</AlertTitle>
+    <AlertDescription>Content Content Content Content</AlertDescription>
+  </Alert>
+  <Alert variant="destructive">
+    <AlertTitle>Error</AlertTitle>
+    <AlertDescription>Content Content Content Content</AlertDescription>
+  </Alert>
+  <Alert variant="help">
+    <AlertTitle>Help</AlertTitle>
+    <AlertDescription>Content Content Content Content</AlertDescription>
+  </Alert>
+</div>
+```
+
+### DescriptionOnly
+
+仅描述（无标题，与 icon 垂直居中）
+
+```tsx
+<Alert variant="info">
+  <AlertDescription>This is an Inline Message Notice</AlertDescription>
+</Alert>
+```
+
+### WithoutIcon
+
+隐藏图标
+
+```tsx
+<Alert variant="success" showIcon={false}>
+  <AlertTitle>成功</AlertTitle>
+  <AlertDescription>无图标的提示信息。</AlertDescription>
+</Alert>
+```
+
+### CustomIcon
+
+自定义图标
+
+```tsx
+<Alert variant="info">
+  <AlertIcon>
+    <RocketIcon />
+  </AlertIcon>
+  <AlertTitle>新功能上线</AlertTitle>
+  <AlertDescription>访问帮助中心查看变更说明。</AlertDescription>
+</Alert>
+```
+
+### Closable
+
+可关闭
+
+```tsx
+<Alert variant="warning" closable onClose={() => console.log('closed')}>
+  <AlertTitle>提醒</AlertTitle>
+  <AlertDescription>请在到期前完成续费。</AlertDescription>
+</Alert>
+```
+
+### WithAction
+
+带操作区
+
+```tsx
+<Alert variant="warning">
+  <AlertTitle>版本过期</AlertTitle>
+  <AlertDescription>
+    当前版本已不再维护，建议升级到最新版本。
+  </AlertDescription>
+  <AlertAction>
+    <Button size="sm">升级</Button>
+  </AlertAction>
+</Alert>
+```
+
+### ClosableWithAction
+
+同时可关闭与操作区
+
+```tsx
+<Alert variant="info" closable>
+  <AlertTitle>新版本可用</AlertTitle>
+  <AlertDescription>建议升级以获得最新能力。</AlertDescription>
+  <AlertAction>
+    <Button size="sm">升级</Button>
+  </AlertAction>
+</Alert>
+```

package/src/components/alert/stories.tsx

@@ -0,0 +1,126 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Alert,
+  AlertIcon,
+  AlertTitle,
+  AlertDescription,
+  AlertAction,
+} from './index';
+import { Button } from '@/components/button';
+import { RocketIcon } from 'lucide-react';
+
+const meta: Meta<typeof Alert> = {
+  title: '反馈 · Feedback/Alert 警告提示',
+  component: Alert,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Alert>;
+
+/** 默认提示（info）*/
+export const Default: Story = {
+  render: () => (
+    <Alert>
+      <AlertDescription>这是一条默认提示信息。</AlertDescription>
+    </Alert>
+  ),
+};
+
+/** 五档语义色 */
+export const Variants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Alert variant="info">
+        <AlertTitle>Info</AlertTitle>
+        <AlertDescription>Content Content Content Content</AlertDescription>
+      </Alert>
+      <Alert variant="success">
+        <AlertTitle>Success</AlertTitle>
+        <AlertDescription>Content Content Content Content</AlertDescription>
+      </Alert>
+      <Alert variant="warning">
+        <AlertTitle>Warning</AlertTitle>
+        <AlertDescription>Content Content Content Content</AlertDescription>
+      </Alert>
+      <Alert variant="destructive">
+        <AlertTitle>Error</AlertTitle>
+        <AlertDescription>Content Content Content Content</AlertDescription>
+      </Alert>
+      <Alert variant="help">
+        <AlertTitle>Help</AlertTitle>
+        <AlertDescription>Content Content Content Content</AlertDescription>
+      </Alert>
+    </div>
+  ),
+};
+
+/** 仅描述（无标题，与 icon 垂直居中）*/
+export const DescriptionOnly: Story = {
+  render: () => (
+    <Alert variant="info">
+      <AlertDescription>This is an Inline Message Notice</AlertDescription>
+    </Alert>
+  ),
+};
+
+/** 隐藏图标 */
+export const WithoutIcon: Story = {
+  render: () => (
+    <Alert variant="success" showIcon={false}>
+      <AlertTitle>成功</AlertTitle>
+      <AlertDescription>无图标的提示信息。</AlertDescription>
+    </Alert>
+  ),
+};
+
+/** 自定义图标 */
+export const CustomIcon: Story = {
+  render: () => (
+    <Alert variant="info">
+      <AlertIcon>
+        <RocketIcon />
+      </AlertIcon>
+      <AlertTitle>新功能上线</AlertTitle>
+      <AlertDescription>访问帮助中心查看变更说明。</AlertDescription>
+    </Alert>
+  ),
+};
+
+/** 可关闭 */
+export const Closable: Story = {
+  render: () => (
+    <Alert variant="warning" closable onClose={() => console.log('closed')}>
+      <AlertTitle>提醒</AlertTitle>
+      <AlertDescription>请在到期前完成续费。</AlertDescription>
+    </Alert>
+  ),
+};
+
+/** 带操作区 */
+export const WithAction: Story = {
+  render: () => (
+    <Alert variant="warning">
+      <AlertTitle>版本过期</AlertTitle>
+      <AlertDescription>
+        当前版本已不再维护，建议升级到最新版本。
+      </AlertDescription>
+      <AlertAction>
+        <Button size="sm">升级</Button>
+      </AlertAction>
+    </Alert>
+  ),
+};
+
+/** 同时可关闭与操作区 */
+export const ClosableWithAction: Story = {
+  render: () => (
+    <Alert variant="info" closable>
+      <AlertTitle>新版本可用</AlertTitle>
+      <AlertDescription>建议升级以获得最新能力。</AlertDescription>
+      <AlertAction>
+        <Button size="sm">升级</Button>
+      </AlertAction>
+    </Alert>
+  ),
+};