@pisell/materials 1.8.23 → 1.8.24

package/es/components/pisellDateTimeDisplay/components/WeekdayDisplay.d.ts

@@ -0,0 +1,57 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+import type { WeekdayFormatConfig, TextStyleConfig } from '../types';
+/**
+ * WeekdayDisplay 组件 Props
+ */
+export interface WeekdayDisplayProps {
+    /**
+     * 日期对象（用于获取星期）
+     */
+    weekday: Dayjs;
+    /**
+     * 星期格式配置
+     */
+    format?: WeekdayFormatConfig;
+    /**
+     * 文本样式
+     */
+    style?: TextStyleConfig;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+}
+/**
+ * 星期展示组件
+ *
+ * @description
+ * - 格式化并展示星期
+ * - 支持完整/缩写/单字母模式
+ * - 自动支持中英文
+ *
+ * @example
+ * // 默认（缩写）
+ * <WeekdayDisplay
+ *   weekday={dayjs()}
+ *   format={{ full: false, singleLetter: false }}
+ *   style={{ fontSize: 18, fontWeight: 400, color: '#666' }}
+ * />
+ * // => "Sat" / "周六"
+ *
+ * // 完整
+ * <WeekdayDisplay
+ *   weekday={dayjs()}
+ *   format={{ full: true }}
+ * />
+ * // => "Saturday" / "星期六"
+ *
+ * // 单字母
+ * <WeekdayDisplay
+ *   weekday={dayjs()}
+ *   format={{ singleLetter: true }}
+ * />
+ * // => "S" / "六"
+ */
+export declare const WeekdayDisplay: React.FC<WeekdayDisplayProps>;
+export default WeekdayDisplay;

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

@@ -0,0 +1,6 @@
+export { TimeDisplay } from './TimeDisplay';
+export { DateDisplay } from './DateDisplay';
+export { WeekdayDisplay } from './WeekdayDisplay';
+export type { TimeDisplayProps } from './TimeDisplay';
+export type { DateDisplayProps } from './DateDisplay';
+export type { WeekdayDisplayProps } from './WeekdayDisplay';

package/es/components/pisellDateTimeDisplay/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useCurrentTime } from './useCurrentTime';
+export type { UseCurrentTimeOptions } from './useCurrentTime';

package/es/components/pisellDateTimeDisplay/hooks/useCurrentTime.d.ts

@@ -0,0 +1,46 @@
+import { Dayjs } from 'dayjs';
+/**
+ * useCurrentTime Hook 配置项
+ */
+export interface UseCurrentTimeOptions {
+    /**
+     * 刷新间隔（毫秒）
+     * @default 60000
+     */
+    refreshInterval?: number;
+    /**
+     * 是否禁用自动刷新
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * dayjs locale
+     * @default 优先使用全局配置，其次使用 i18n 当前语言（getCurrentLocale）
+     * @example 'zh-CN' | 'zh-HK' | 'en' | 'en-US' | 'ja'
+     */
+    locale?: string;
+    /**
+     * 时间更新回调
+     */
+    onUpdate?: (time: Dayjs) => void;
+}
+/**
+ * 管理当前时间状态的自定义 Hook
+ *
+ * @description
+ * - 自动创建定时器刷新时间
+ * - 支持自定义刷新间隔
+ * - 支持国际化（locale）：优先级为 用户指定 > 全局配置 > i18n 当前语言
+ * - 组件卸载时自动清除定时器
+ *
+ * @example
+ * const currentTime = useCurrentTime({
+ *   refreshInterval: 1000,
+ *   locale: 'zh-CN',
+ *   onUpdate: (time) => console.log(time.format())
+ * });
+ *
+ * @param options 配置项
+ * @returns 当前时间（Dayjs 对象）
+ */
+export declare function useCurrentTime(options?: UseCurrentTimeOptions): Dayjs;

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

@@ -0,0 +1,3 @@
+export { default as PisellDateTimeDisplay } from './PisellDateTimeDisplay';
+export type { PisellDateTimeDisplayProps, LayoutDirection, DateOrder, TextAlign, FieldType, TimeFormatConfig, DateFormatConfig, WeekdayFormatConfig, FieldConfig, TextStyleConfig, ContainerStyleConfig, } from './types';
+export { default } from './PisellDateTimeDisplay';

package/es/components/pisellDateTimeDisplay/utils/formatDate.d.ts

@@ -0,0 +1,21 @@
+import type { Dayjs } from 'dayjs';
+import type { DateFormatConfig } from '../types';
+/**
+ * 格式化日期
+ * @param date dayjs 日期对象
+ * @param config 日期格式配置
+ * @returns 格式化后的日期字符串
+ *
+ * @example
+ * // 英文环境
+ * formatDate(dayjs(), { order: 'YMD', shortMonth: true, showYear: true })
+ * // => "2026-Mar-21"
+ *
+ * // 中文环境
+ * formatDate(dayjs(), { order: 'YMD', showChineseUnit: true, showYear: true })
+ * // => "2026年3月21日"
+ *
+ * formatDate(dayjs(), { order: 'MDY', shortMonth: false, showYear: true })
+ * // => "March 21, 2026"
+ */
+export declare function formatDate(date: Dayjs, config?: DateFormatConfig): string;

package/es/components/pisellDateTimeDisplay/utils/formatDateOrRelative.d.ts

@@ -0,0 +1,17 @@
+import type { Dayjs } from 'dayjs';
+import type { DateFormatConfig, WeekdayFormatConfig } from '../types';
+/**
+ * 获取「日期部分」的展示文案（相对日内置在 datetime）
+ * - 若开启 showRelativeDay 且日期为今天/昨天/明天，返回相对日文案（如「今天」「Yesterday」）
+ * - 否则返回「星期, 日期」格式（用于时间区间跨天等场景）
+ *
+ * 供 PisellDateTimeDisplay、PisellTimeRangeDisplay 等统一使用，相对时间逻辑只在此处维护
+ */
+export declare function getDatePartDisplay(params: {
+    date: Dayjs;
+    dateFormat?: DateFormatConfig;
+    weekdayFormat?: WeekdayFormatConfig;
+    referenceDate: Dayjs;
+    /** 覆盖日期格式（如跨天时的 order: 'DMY', shortMonth: true） */
+    dateFormatOverride?: Partial<DateFormatConfig>;
+}): string;

package/es/components/pisellDateTimeDisplay/utils/formatWeekday.d.ts

@@ -0,0 +1,30 @@
+import type { Dayjs } from 'dayjs';
+import type { WeekdayFormatConfig } from '../types';
+/**
+ * 格式化星期
+ * @param weekday dayjs 日期对象
+ * @param config 星期格式配置
+ * @returns 格式化后的星期字符串
+ *
+ * @example
+ * // 英文环境
+ * formatWeekday(dayjs(), { full: false, singleLetter: false })
+ * // => "Sat"
+ *
+ * formatWeekday(dayjs(), { full: true })
+ * // => "Saturday"
+ *
+ * formatWeekday(dayjs(), { singleLetter: true })
+ * // => "S"
+ *
+ * // 中文环境
+ * formatWeekday(dayjs(), { full: false, singleLetter: false })
+ * // => "周六"
+ *
+ * formatWeekday(dayjs(), { full: true })
+ * // => "星期六"
+ *
+ * formatWeekday(dayjs(), { singleLetter: true })
+ * // => "六"
+ */
+export declare function formatWeekday(weekday: Dayjs, config?: WeekdayFormatConfig): string;

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

@@ -0,0 +1,7 @@
+export { formatTime } from './formatTime';
+export { formatDate } from './formatDate';
+export { formatWeekday } from './formatWeekday';
+export { getDatePartDisplay } from './formatDateOrRelative';
+export { getRefreshInterval } from './getRefreshInterval';
+export { getRelativeDay, getRelativeDayLabel, type RelativeDay, } from './relativeDay';
+export { normalizeLocale, isChinese, getDayjsLocale, } from './localeUtils';

package/es/components/pisellDateTimeDisplay/utils/localeUtils.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 标准化 locale 代码
+ * @param locale 原始 locale 代码
+ * @returns 标准化后的 locale 代码（小写，用于 dayjs）
+ * @example 'zh-CN' -> 'zh-cn', 'en' -> 'en'
+ */
+export declare function normalizeLocale(locale: string): string;
+/**
+ * 判断是否为中文环境
+ * @param locale locale 代码
+ * @returns 是否为中文
+ * @example isChinese('zh-CN') -> true, isChinese('zh-HK') -> true, isChinese('en') -> false
+ */
+export declare function isChinese(locale: string): boolean;
+/**
+ * 获取 dayjs 兼容的 locale 代码
+ * 未传 locale 时：优先 materials 当前语言（globalConfig / umi_locale），若为默认 en-US 则用 @pisell/utils getLocale
+ * @param locale 原始 locale 代码（可选）
+ * @returns dayjs 兼容的 locale 代码（与已加载的 zh-cn、en 对齐）
+ * @example 'zh-CN' -> 'zh-cn', 'en-US' -> 'en'
+ */
+export declare function getDayjsLocale(locale?: string): string;

package/es/components/pisellDateTimeDisplay/utils/relativeDay.d.ts

@@ -0,0 +1,24 @@
+import type { Dayjs } from 'dayjs';
+export declare type RelativeDay = 'today' | 'yesterday' | 'tomorrow';
+/**
+ * 判断日期相对于参考日期是今天、昨天还是明天
+ *
+ * @param date 要展示的日期
+ * @param reference 参考日期（通常为「当前」dayjs()）
+ * @returns 'today' | 'yesterday' | 'tomorrow' | null
+ *
+ * @example
+ * getRelativeDay(dayjs(), dayjs())           // => 'today'
+ * getRelativeDay(dayjs().add(1,'day'), dayjs()) // => 'tomorrow'
+ * getRelativeDay(dayjs().subtract(1,'day'), dayjs()) // => 'yesterday'
+ */
+export declare function getRelativeDay(date: Dayjs, reference: Dayjs): RelativeDay | null;
+/**
+ * 根据 locale 返回相对日期的展示文案
+ * 未传 locale 时使用 getDayjsLocale()（与 locales.getLocale 同源）
+ *
+ * @param day 'today' | 'yesterday' | 'tomorrow'
+ * @param locale dayjs locale，如 'zh-cn'、'en'
+ * @returns 如 '今天'、'Today'
+ */
+export declare function getRelativeDayLabel(day: RelativeDay, locale?: string): string;

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

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { PisellEmailProps } from './types';
+import './PisellEmail.less';
+/**
+ * PisellEmail 邮箱地址组件
+ *
+ * 邮箱地址输入/展示组件，支持只读、编辑、禁用三种状态。
+ * 基于 Ant Design AutoComplete 和 Input 组件开发，提供邮箱格式校验、域名智能补全、
+ * mailto 邮件发送和域名隐藏功能。
+ *
+ * @param props 组件 Props
+ *
+ * @example
+ * // 编辑态（邮箱输入）
+ * <PisellEmail
+ *   placeholder="请输入邮箱地址"
+ *   required
+ * />
+ *
+ * @example
+ * // 只读态（可发邮件）
+ * <PisellEmail
+ *   mode="read"
+ *   value="user@example.com"
+ *   enableMailto
+ * />
+ *
+ * @example
+ * // 域名补全
+ * <PisellEmail
+ *   enableAutoComplete
+ *   autoCompleteDomains={['gmail.com', 'company.com']}
+ * />
+ */
+export declare const PisellEmail: React.FC<PisellEmailProps>;
+declare const _default: React.NamedExoticComponent<PisellEmailProps>;
+export default _default;

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/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * PisellEmail 组件导出文件
+ */
+import PisellEmail from './PisellEmail';
+export { PisellEmail };
+export default 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';