@pisell/materials 1.8.6 → 1.8.7

package/es/components/pisellEmail/PisellEmail.stories.d.ts

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellEmail } from './PisellEmail';
+/**
+ * PisellEmail 是一个邮箱地址输入/展示组件。
+ *
+ * ## 功能特性
+ * - 支持三种状态：只读、编辑、禁用
+ * - 邮箱格式校验（标准/严格）
+ * - 域名智能补全
+ * - mailto 邮件发送
+ * - 域名隐藏/脱敏
+ * - 白名单/黑名单域名限制
+ */
+declare const meta: Meta<typeof PisellEmail>;
+export default meta;
+declare type Story = StoryObj<typeof PisellEmail>;
+/**
+ * 基础编辑态
+ */
+export declare const Basic: Story;
+/**
+ * 域名智能补全
+ */
+export declare const WithAutoComplete: Story;
+/**
+ * 自定义补全域名
+ */
+export declare const CustomDomains: Story;
+/**
+ * 只读态 - 可发邮件
+ */
+export declare const ReadMode: Story;
+/**
+ * 只读态 - 带邮件图标
+ */
+export declare const ReadModeWithIcon: Story;
+/**
+ * 只读态 - 域名部分隐藏
+ */
+export declare const ReadModePartialMask: Story;
+/**
+ * 只读态 - 域名完全隐藏
+ */
+export declare const ReadModeFullMask: Story;
+/**
+ * 禁用态（编辑）
+ */
+export declare const DisabledEdit: Story;
+/**
+ * 禁用态（只读）
+ */
+export declare const DisabledRead: Story;
+/**
+ * 必填校验
+ */
+export declare const Required: Story;
+/**
+ * 格式校验（实时）
+ */
+export declare const FormatValidation: Story;
+/**
+ * 严格格式校验
+ */
+export declare const StrictValidation: Story;
+/**
+ * 白名单域名限制
+ */
+export declare const AllowedDomains: Story;
+/**
+ * 黑名单域名限制
+ */
+export declare const BlockedDomains: Story;
+/**
+ * 显示清空按钮
+ */
+export declare const WithClearButton: Story;
+/**
+ * 自动聚焦
+ */
+export declare const WithAutoFocus: Story;
+/**
+ * 自定义样式（只读态）
+ */
+export declare const CustomStyle: Story;
+/**
+ * 脱敏模式对比
+ */
+export declare const MaskingComparison: Story;
+/**
+ * 校验时机对比
+ */
+export declare const ValidateTriggerComparison: Story;
+/**
+ * 完整功能示例
+ */
+export declare const CompleteExample: Story;
+/**
+ * 域名补全演示
+ */
+export declare const AutoCompleteDemo: Story;
+/**
+ * mailto 功能演示
+ */
+export declare const MailtoDemo: Story;
+/**
+ * 白名单/黑名单演示
+ */
+export declare const DomainRestrictionDemo: Story;
+/**
+ * 所有状态展示
+ */
+export declare const AllStates: Story;
+/**
+ * 完整交互示例
+ */
+export declare const InteractiveExample: Story;

package/es/components/pisellEmail/components/DisabledView.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { PisellEmailProps } from '../types';
+/**
+ * PisellEmail 禁用态视图组件
+ *
+ * 职责：
+ * - 渲染禁用状态的邮箱组件
+ * - 根据原始 mode 选择渲染 ReadOnlyView 或 EditView
+ * - 应用禁用样式（透明度 40%）
+ *
+ * @param props 组件 Props
+ */
+declare const DisabledView: React.FC<PisellEmailProps>;
+export default DisabledView;

package/es/components/pisellEmail/components/EditView.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { PisellEmailProps } from '../types';
+/**
+ * PisellEmail 编辑态视图组件
+ *
+ * 职责：
+ * - 渲染编辑态邮箱输入框
+ * - 提供域名智能补全（基于 AutoComplete）
+ * - 实时格式校验（标准/严格）
+ * - 错误提示展示
+ *
+ * @param props 组件 Props
+ */
+declare const EditView: React.FC<PisellEmailProps>;
+export default EditView;

package/es/components/pisellEmail/components/ReadOnlyView.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { PisellEmailProps } from '../types';
+/**
+ * PisellEmail 只读态视图组件
+ *
+ * 职责：
+ * - 渲染只读态邮箱地址展示
+ * - 支持点击唤起邮件客户端（mailto）
+ * - 支持域名隐藏/脱敏（partial/full 模式）
+ * - 支持邮件图标按钮
+ *
+ * @param props 组件 Props
+ */
+declare const ReadOnlyView: React.FC<PisellEmailProps>;
+export default ReadOnlyView;

package/es/components/pisellEmail/constants/emailDomains.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 常用邮箱域名列表
+ * 用于域名自动补全功能
+ */
+export declare const COMMON_EMAIL_DOMAINS: string[];

package/es/components/pisellEmail/constants/emailRegex.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 邮箱正则表达式常量
+ */
+/**
+ * 标准邮箱格式正则
+ * 覆盖99%的常见邮箱格式
+ */
+export declare const EMAIL_REGEX: RegExp;
+/**
+ * 严格邮箱格式正则（RFC 5322）
+ * 支持更复杂的邮箱格式，符合 RFC 5322 标准
+ */
+export declare const STRICT_EMAIL_REGEX: RegExp;

package/es/components/pisellEmail/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * PisellEmail 组件导出文件
+ */
+export { PisellEmail, default } from './PisellEmail';
+export type { PisellEmailProps, MailtoOptions } from './types';

package/es/components/pisellEmail/types.d.ts

@@ -0,0 +1,176 @@
+import type { CSSProperties } from 'react';
+import type { BaseTextInputProps } from '@pisell/utils';
+/**
+ * Mailto 邮件参数配置类型
+ */
+export interface MailtoOptions {
+    /**
+     * 邮件主题
+     * @example '产品咨询'
+     */
+    subject?: string;
+    /**
+     * 邮件正文
+     * @example '您好，我想咨询...'
+     */
+    body?: string;
+    /**
+     * 抄送地址
+     * @example 'cc@example.com'
+     */
+    cc?: string;
+    /**
+     * 密送地址
+     * @example 'bcc@example.com'
+     */
+    bcc?: string;
+}
+/**
+ * PisellEmail 组件 Props 类型定义
+ *
+ * 继承 BaseTextInputProps，添加邮箱特有的配置
+ */
+export interface PisellEmailProps extends BaseTextInputProps {
+    /**
+     * 状态模式
+     * @default 'edit'
+     */
+    mode?: 'read' | 'edit';
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否使用严格校验（RFC 5322）
+     * @default false
+     */
+    strictValidation?: boolean;
+    /**
+     * 白名单域名列表（仅允许指定域名）
+     * @example ['company.com', 'partner.com']
+     */
+    allowedDomains?: string[];
+    /**
+     * 黑名单域名列表（禁止某些域名）
+     * @example ['tempmail.com', '10minutemail.com']
+     */
+    blockedDomains?: string[];
+    /**
+     * 是否启用域名自动补全
+     * @default true
+     */
+    enableAutoComplete?: boolean;
+    /**
+     * 自定义补全域名列表
+     * @example ['gmail.com', 'company.com', 'custom.com']
+     */
+    autoCompleteDomains?: string[];
+    /**
+     * 是否显示所有建议（不过滤）
+     * @default false
+     */
+    showAllSuggestions?: boolean;
+    /**
+     * 选择补全建议回调
+     * @param value 选中的邮箱地址
+     */
+    onSelect?: (value: string) => void;
+    /**
+     * 是否启用 mailto（只读态）
+     * @default true
+     */
+    enableMailto?: boolean;
+    /**
+     * 是否显示邮件图标
+     * @default false
+     */
+    showEmailIcon?: boolean;
+    /**
+     * mailto 默认参数
+     */
+    mailtoOptions?: MailtoOptions;
+    /**
+     * 发送邮件回调
+     * @param email 邮箱地址
+     */
+    onMailto?: (email: string) => void;
+    /**
+     * 是否隐藏域名（只读态）
+     * @default false
+     */
+    hideDomain?: boolean;
+    /**
+     * 脱敏模式
+     * - partial: 部分隐藏（u***@gmail.com）
+     * - full: 完全隐藏（user@***）
+     * @default 'partial'
+     */
+    maskPattern?: 'partial' | 'full';
+    /**
+     * 是否显示为链接（只读态）
+     * @default true
+     */
+    displayAsLink?: boolean;
+    /**
+     * 字号
+     * @example '14px' 或 14
+     * @default 16
+     */
+    fontSize?: string | number;
+    /**
+     * 字重
+     * @example 'bold' 或 600
+     * @default 500
+     */
+    fontWeight?: string | number;
+    /**
+     * 文本颜色
+     * @example '#000000'
+     * @default '#101828'
+     */
+    color?: string;
+    /**
+     * 链接颜色（只读态）
+     * @example '#1890ff'
+     * @default '#7F56DA'
+     */
+    linkColor?: string;
+    /**
+     * 占位文本
+     * @default '请输入邮箱地址'
+     */
+    placeholder?: string;
+    /**
+     * 最大长度（RFC 5321）
+     * @default 254
+     */
+    maxLength?: number;
+    /**
+     * 是否显示清空按钮
+     * @default false
+     */
+    allowClear?: boolean;
+    /**
+     * 是否自动聚焦
+     * @default false
+     */
+    autoFocus?: boolean;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * ARIA 标签
+     */
+    'aria-label'?: string;
+    /**
+     * ARIA 描述
+     */
+    'aria-describedby'?: string;
+}
+export type { DisplayState, ValidationResult, TextInputState } from '@pisell/utils';

package/es/components/pisellEmail/utils/domainSuggestions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 域名补全工具函数（框架占位符）
+ * TODO: 实现完整的补全逻辑
+ */
+/**
+ * 获取邮箱域名补全建议
+ * @param input 用户输入
+ * @param domains 域名列表
+ * @returns 补全建议列表
+ *
+ * @example
+ * getEmailSuggestions('user@g', COMMON_EMAIL_DOMAINS)
+ * // 返回: ['user@gmail.com']
+ */
+export declare function getEmailSuggestions(input: string, domains?: string[]): string[];

package/es/components/pisellEmail/utils/emailHelper.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 邮箱辅助函数
+ */
+import type { MailtoOptions } from '../types';
+/**
+ * 提取邮箱域名
+ * @param email 邮箱地址
+ * @returns 域名部分
+ *
+ * @example
+ * extractEmailDomain('user@example.com') // 'example.com'
+ */
+export declare function extractEmailDomain(email: string): string;
+/**
+ * 提取邮箱本地部分
+ * @param email 邮箱地址
+ * @returns 本地部分（@ 前面的部分）
+ *
+ * @example
+ * extractEmailLocal('user@example.com') // 'user'
+ */
+export declare function extractEmailLocal(email: string): string;
+/**
+ * 规范化邮箱地址（转小写）
+ * @param email 邮箱地址
+ * @returns 规范化后的邮箱地址
+ *
+ * @example
+ * normalizeEmail('User@Example.COM') // 'user@example.com'
+ */
+export declare function normalizeEmail(email: string): string;
+/**
+ * 邮箱域名脱敏（partial 模式）
+ * 只显示本地部分的第一个字符，其余用 *** 替代
+ *
+ * @param email 邮箱地址
+ * @returns 脱敏后的邮箱（u***@gmail.com）
+ *
+ * @example
+ * hideEmailDomain('user@gmail.com') // 'u***@gmail.com'
+ */
+export declare function hideEmailDomain(email: string): string;
+/**
+ * 邮箱域名完全隐藏（full 模式）
+ * 隐藏整个域名部分
+ *
+ * @param email 邮箱地址
+ * @returns 脱敏后的邮箱（user@***）
+ *
+ * @example
+ * maskEmailDomain('user@gmail.com') // 'user@***'
+ */
+export declare function maskEmailDomain(email: string): string;
+/**
+ * 处理 mailto 点击，唤起邮件客户端
+ *
+ * @param email 邮箱地址
+ * @param options mailto 可选参数（主题、正文、抄送等）
+ *
+ * @example
+ * handleEmailClick('support@example.com', {
+ *   subject: '产品咨询',
+ *   body: '您好，我想咨询...'
+ * })
+ */
+export declare function handleEmailClick(email: string, options?: MailtoOptions): void;

package/es/components/pisellEmail/utils/emailValidator.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 邮箱校验工具函数
+ */
+/**
+ * 标准邮箱格式校验
+ * @param email 邮箱地址
+ * @returns 是否通过校验
+ *
+ * @example
+ * validateEmail('user@example.com') // true
+ * validateEmail('invalid-email') // false
+ */
+export declare function validateEmail(email: string): boolean;
+/**
+ * 严格邮箱格式校验（RFC 5322）
+ * @param email 邮箱地址
+ * @returns 是否通过校验
+ *
+ * @example
+ * validateEmailStrict('user@example.com') // true
+ */
+export declare function validateEmailStrict(email: string): boolean;
+/**
+ * 邮箱分部校验
+ * 检查邮箱的各个部分是否符合规范
+ *
+ * @param email 邮箱地址
+ * @returns 校验结果
+ */
+export declare function validateEmailParts(email: string): {
+    isValid: boolean;
+    errors: string[];
+};
+/**
+ * 域名白名单/黑名单校验
+ *
+ * @param email 邮箱地址
+ * @param allowedDomains 白名单域名列表
+ * @param blockedDomains 黑名单域名列表
+ * @returns 校验结果
+ */
+export declare function validateEmailDomain(email: string, allowedDomains?: string[], blockedDomains?: string[]): {
+    isValid: boolean;
+    errors: string[];
+};

package/es/components/pisellEmail/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PisellEmail 工具函数导出
+ */
+export * from './emailValidator';
+export * from './emailHelper';
+export * from './domainSuggestions';

package/es/components/pisellEmpty/index.d.ts

@@ -15,5 +15,5 @@ export interface PisellEmptyProps extends EmptyProps {
     /** 最大宽度 */
     maxWidth?: number;
 }
-declare const PisellEmpty: (props: PisellEmptyProps) => JSX.Element;
+declare const PisellEmpty: (props: PisellEmptyProps) => React.JSX.Element;
 export default PisellEmpty;

package/es/components/pisellFilter/index.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="react" />
+import React from 'react';
 import { PisellFilterProps } from './type';
-declare const PisellFilter: (props: PisellFilterProps) => JSX.Element;
+declare const PisellFilter: (props: PisellFilterProps) => React.JSX.Element;
 export default PisellFilter;

package/es/components/pisellFloatingPanel/index.d.ts

@@ -13,5 +13,5 @@ export interface PisellFloatingPanelProps {
     style?: React.CSSProperties;
     retractIconStyle?: React.CSSProperties;
 }
-declare const PisellFloatingPanel: (props: PisellFloatingPanelProps) => JSX.Element;
+declare const PisellFloatingPanel: (props: PisellFloatingPanelProps) => React.JSX.Element;
 export default PisellFloatingPanel;

package/es/components/pisellGoodPassCard/index.d.ts

@@ -46,5 +46,5 @@ export interface PisellGoodPassCardProps {
     mixedSort?: (val: Discount[]) => Discount[];
     isInModal: boolean;
 }
-declare const index: (props: PisellGoodPassCardProps) => JSX.Element;
+declare const index: (props: PisellGoodPassCardProps) => React.JSX.Element;
 export default index;

package/es/components/pisellGridPro/GridPro.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import './index.less';
+export interface GridProProps {
+    className?: string;
+    children?: React.ReactNode;
+    style?: React.CSSProperties;
+}
+declare const PisellGridPro: (props: GridProProps) => React.JSX.Element;
+export default PisellGridPro;

package/es/components/pisellGridPro/GridView/index.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import './index.less';
+import { GridViewProps } from './type';
+export type { GridViewProps };
+declare const GridView: (props: GridViewProps) => React.JSX.Element;
+export default GridView;

package/es/components/pisellGridPro/GridView/type.d.ts

@@ -0,0 +1,3 @@
+import { PisellScrollViewProps } from '../../PisellScrollView/types';
+export interface GridViewProps extends PisellScrollViewProps {
+}

package/es/components/pisellGridPro/ToolBar/index.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import './index.less';
+import { ToolBarProps } from './type';
+export type { ToolBarProps };
+declare const Toolbar: React.FC<ToolBarProps>;
+export default Toolbar;

package/es/components/pisellGridPro/ToolBar/type.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+export interface ToolBarProps {
+    className?: string;
+    style?: React.CSSProperties;
+    tabs?: React.ReactNode;
+    topLeft?: React.ReactNode;
+    topRight?: React.ReactNode;
+    bottomLeft?: React.ReactNode;
+    bottomRight?: React.ReactNode;
+}

package/es/components/pisellGridPro/components/DataCard/components/StatCard/index.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+import { StatCardItem } from '../../types';
+import './index.less';
+/**
+ * StatCard 统计卡片组件
+ * @description 用于展示单个统计数据，包含标题、数值和对比信息
+ * @author Pisell Team
+ */
+declare const StatCard: React.FC<StatCardItem>;
+export default StatCard;

package/es/components/pisellGridPro/components/DataCard/index.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { DataCardProps } from './types';
+export type { DataCardProps };
+import './index.less';
+declare const DataCard: (props: DataCardProps) => React.JSX.Element | null;
+export default DataCard;

package/es/components/pisellGridPro/components/DataCard/types.d.ts

@@ -0,0 +1,70 @@
+import React from 'react';
+/**
+ * PisellGridProDataCard 组件属性接口
+ */
+export interface DataCardProps {
+    /**
+     * 统计卡片数据列表
+     */
+    dataItems?: StatCardItem[];
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: React.CSSProperties;
+}
+/**
+ * 统计卡片数据项接口
+ */
+export interface StatCardItem {
+    /**
+     * 唯一标识
+     */
+    key: string;
+    /**
+     * 卡片标题
+     * @example "Total Orders"
+     */
+    title: React.ReactNode;
+    /**
+     * 主要数值
+     * @example 50 或 "$1580"
+     */
+    value: React.ReactNode;
+    /**
+     * 对比数值
+     * @example "+12" 或 "-230"
+     */
+    compareValue?: React.ReactNode;
+    /**
+     * 对比趋势
+     * @description up-增长(绿色), down-下降(红色)
+     * @default undefined
+     */
+    trend?: 'up' | 'down';
+    /**
+     * 对比前缀文本
+     * @default "v.s. pre"
+     */
+    comparePrefix?: string;
+    /**
+     * 是否显示对比信息
+     * @default true
+     */
+    showCompare?: boolean;
+    /**
+     * 自定义卡片样式
+     */
+    style?: React.CSSProperties;
+    /**
+     * 自定义卡片类名
+     */
+    className?: string;
+    /**
+     * 点击回调
+     */
+    onClick?: () => void;
+}

package/es/components/pisellGridPro/components/Footer/index.d.ts

@@ -0,0 +1,9 @@
+import React from 'react';
+import './index.less';
+export interface FooterProps {
+    className?: string;
+    children?: React.ReactNode;
+    style?: React.CSSProperties;
+}
+declare const Footer: (props: FooterProps) => React.JSX.Element;
+export default Footer;