@pisell/materials 1.8.20 → 1.8.21

package/es/components/pisellTimeRangeDisplay/components/WeekdayBlock.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { Dayjs } from 'dayjs';
+import type { WeekdayFormatConfig, TextStyleConfig } from '../types';
+export interface WeekdayBlockProps {
+    /** 日期对象（用于获取星期） */
+    weekday: Dayjs;
+    /** 星期格式配置 */
+    format?: WeekdayFormatConfig;
+    /** 文本样式 */
+    style?: TextStyleConfig;
+    /** 自定义类名 */
+    className?: string;
+}
+/**
+ * 星期展示块（复用 PisellDateTimeDisplay 的 formatWeekday）
+ */
+export declare const WeekdayBlock: React.FC<WeekdayBlockProps>;
+export default WeekdayBlock;

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

@@ -0,0 +1,8 @@
+export { TimeRangeBlock } from './TimeRangeBlock';
+export { DateBlock } from './DateBlock';
+export { WeekdayBlock } from './WeekdayBlock';
+export { DurationBlock } from './DurationBlock';
+export type { TimeRangeBlockProps } from './TimeRangeBlock';
+export type { DateBlockProps } from './DateBlock';
+export type { WeekdayBlockProps } from './WeekdayBlock';
+export type { DurationBlockProps } from './DurationBlock';

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

@@ -0,0 +1,3 @@
+export { PisellTimeRangeDisplay, default } from './PisellTimeRangeDisplay';
+export type { PisellTimeRangeDisplayProps, LayoutDirection, TimeRangeFieldType, TimeRangeFieldConfig, DurationFormatConfig, DayjsLike, } from './types';
+export type { TimeFormatConfig, DateFormatConfig, WeekdayFormatConfig, ContainerStyleConfig, TextStyleConfig, TextAlign, } from './types';

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

@@ -0,0 +1,137 @@
+import type { CSSProperties } from 'react';
+import type { Dayjs } from 'dayjs';
+import type { TimeFormatConfig, DateFormatConfig, WeekdayFormatConfig, ContainerStyleConfig, TextStyleConfig, TextAlign } from '../pisellDateTimeDisplay/types';
+export type { TimeFormatConfig, DateFormatConfig, WeekdayFormatConfig, ContainerStyleConfig, TextStyleConfig, TextAlign, };
+/**
+ * 字段类型（时间区间、日期、星期、持续时长）
+ * - time: 时间区间块（HH:mm-HH:mm 或跨天起止）
+ * - date: 日期块
+ * - weekday: 星期块
+ * - duration: 持续时长块
+ */
+export declare type TimeRangeFieldType = 'time' | 'date' | 'weekday' | 'duration';
+/**
+ * 持续时长格式配置
+ */
+export interface DurationFormatConfig {
+    /**
+     * 是否显示秒
+     * @default false
+     * @example true -> "2h30m23s" | false -> "2h30m"
+     */
+    showSeconds?: boolean;
+}
+/**
+ * 字段配置
+ */
+export interface TimeRangeFieldConfig {
+    /**
+     * 是否显示时间区间块
+     * @default true
+     */
+    showTimeRange?: boolean;
+    /**
+     * 是否显示日期块
+     * @default true
+     */
+    showDate?: boolean;
+    /**
+     * 是否显示星期块
+     * @default true
+     */
+    showWeekday?: boolean;
+    /**
+     * 是否显示持续时长块
+     * @default true
+     */
+    showDuration?: boolean;
+    /**
+     * 字段顺序（四类块可任意排序；默认 时间 日期 星期 持续时长，可实现「持续时间在前」等）
+     * @default ['weekday', 'date', 'time', 'duration'] 换行顺序：先持续时间 → 结束时间（跨天）→ 开始/结束时间与日期 → 星期
+     */
+    fieldOrder?: TimeRangeFieldType[];
+}
+/**
+ * startAt / endAt 的 dayjs 兼容值
+ */
+export declare type DayjsLike = Dayjs | string | number;
+/**
+ * PisellTimeRangeDisplay 组件 Props
+ */
+export interface PisellTimeRangeDisplayProps {
+    /**
+     * 开始时间（dayjs 兼容值）
+     */
+    startAt: DayjsLike;
+    /**
+     * 结束时间（dayjs 兼容值）
+     */
+    endAt: DayjsLike;
+    /**
+     * 文本对齐方式（单行/多行均生效）
+     * @default 'center'
+     */
+    textAlign?: TextAlign;
+    /**
+     * 字段显示与排序配置
+     */
+    fields?: TimeRangeFieldConfig;
+    /**
+     * 同一天时是否显示具体日期
+     * @default true
+     */
+    showDateForSameDay?: boolean;
+    /**
+     * 时间格式配置（复用 PisellDateTimeDisplay）
+     */
+    timeFormat?: TimeFormatConfig;
+    /**
+     * 日期格式配置（复用 PisellDateTimeDisplay）
+     */
+    dateFormat?: DateFormatConfig;
+    /**
+     * 星期格式配置（复用 PisellDateTimeDisplay）
+     */
+    weekdayFormat?: WeekdayFormatConfig;
+    /**
+     * 持续时长格式配置
+     */
+    durationFormat?: DurationFormatConfig;
+    /**
+     * 容器样式
+     */
+    containerStyle?: ContainerStyleConfig;
+    /**
+     * 时间区间文本样式
+     */
+    timeStyle?: TextStyleConfig;
+    /**
+     * 日期文本样式
+     */
+    dateStyle?: TextStyleConfig;
+    /**
+     * 星期文本样式
+     */
+    weekdayStyle?: TextStyleConfig;
+    /**
+     * 持续时长文本样式
+     */
+    durationStyle?: TextStyleConfig;
+    /**
+     * dayjs locale（语言代码）
+     * @default 优先使用全局配置，其次浏览器语言
+     */
+    locale?: string;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * 点击回调
+     */
+    onClick?: () => void;
+}

package/es/components/pisellTimeRangeDisplay/utils/formatDuration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 将毫秒数格式化为持续时间字符串（d h m s 或 天/时/分/秒）
+ *
+ * @param ms 持续时间（毫秒）
+ * @param showSeconds 是否显示秒，默认 false
+ * @param locale 语言代码，zh 时使用「天/时/分/秒」，否则使用 d/h/m/s
+ * @returns 如 "2h30m"、"1d2h30m23s" 或 "2时30分"、"1天2时30分23秒"
+ *
+ * @example
+ * formatDuration(9000000, false)        // => "2h30m"
+ * formatDuration(9000000, false, 'zh-cn') // => "2时30分"
+ * formatDuration(86400000, false)       // => "1d"
+ */
+export declare function formatDuration(ms: number, showSeconds?: boolean, locale?: string): string;

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

@@ -0,0 +1,4 @@
+export { parseTimeRange } from './parseTimeRange';
+export type { ParseTimeRangeResult } from './parseTimeRange';
+export { formatDuration } from './formatDuration';
+export { formatTime, formatDate, formatWeekday, getDayjsLocale, getRelativeDay, getRelativeDayLabel, getDatePartDisplay, } from '../../pisellDateTimeDisplay/utils';

package/es/components/pisellTimeRangeDisplay/utils/parseTimeRange.d.ts

@@ -0,0 +1,23 @@
+import { type Dayjs } from 'dayjs';
+import type { DayjsLike } from '../types';
+export interface ParseTimeRangeResult {
+    /** 开始时间（已应用 locale） */
+    start: Dayjs;
+    /** 结束时间（已应用 locale） */
+    end: Dayjs;
+    /** 是否同一天（按本地时区自然日判定） */
+    isSameDay: boolean;
+}
+/**
+ * 解析 startAt / endAt 为 Dayjs，并判定是否同一天
+ *
+ * @param startAt 开始时间（dayjs 兼容值）
+ * @param endAt 结束时间（dayjs 兼容值）
+ * @param locale dayjs locale，可选
+ * @returns { start, end, isSameDay }
+ *
+ * @example
+ * parseTimeRange('2026-02-04 09:00', '2026-02-04 18:00', 'zh-cn')
+ * // => { start: Dayjs, end: Dayjs, isSameDay: true }
+ */
+export declare function parseTimeRange(startAt: DayjsLike, endAt: DayjsLike, locale?: string): ParseTimeRangeResult;

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

@@ -0,0 +1,17 @@
+import React from 'react';
+import './index.less';
+export interface PisellToastProps {
+    /** 提示内容	 */
+    content: React.ReactNode;
+    /** 自动关闭的延时，单位秒。设为 0 时不自动关闭 */
+    duration?: number;
+    /** 是否展示action */
+    showAction?: boolean;
+    /** action文案 */
+    actionText?: string;
+    /** 关闭时触发的回调函数 */
+    onClose?: () => void;
+}
+declare const PisellToast: (props: PisellToastProps) => void;
+export { useToast } from './squareToast';
+export default PisellToast;

package/es/components/pisellToast/squareToast/index.d.ts

@@ -0,0 +1,15 @@
+import { clear, show, success, info, loading, fail, hide } from './methods';
+import './index.less';
+interface ToastInstance {
+    show: typeof show;
+    clear: typeof clear;
+    success: typeof success;
+    info: typeof info;
+    loading: typeof loading;
+    fail: typeof fail;
+    error: typeof fail;
+    hide: typeof hide;
+}
+declare const Toast: ToastInstance;
+export declare const useToast: () => ToastInstance;
+export default Toast;

package/es/components/pisellToast/squareToast/methods.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import { ToastProps } from './toast';
+interface ToastInstance {
+    close: () => void;
+}
+declare const show: (configOrContent: Partial<ToastProps> | React.ReactNode, duration?: number, afterClose?: () => void) => ToastInstance;
+declare const clear: () => void;
+declare const success: (content: React.ReactNode, duration?: number, afterClose?: () => void) => ToastInstance;
+declare const info: (content: React.ReactNode, duration?: number, afterClose?: () => void) => ToastInstance;
+declare const loading: (content: React.ReactNode, duration?: number, afterClose?: () => void) => ToastInstance;
+declare const fail: (content: React.ReactNode, duration?: number, afterClose?: () => void) => ToastInstance;
+declare const hide: () => void;
+export { show, clear, success, info, loading, fail, hide };

package/es/components/pisellToast/squareToast/renderImperatively.d.ts

@@ -0,0 +1,28 @@
+import type { ReactElement } from 'react';
+import type { Root } from 'react-dom/client';
+import React from 'react';
+declare type ImperativeProps = {
+    open?: boolean;
+    onCancel?: () => void;
+    afterClose?: () => void;
+};
+declare type TargetElement = ReactElement<ImperativeProps>;
+export declare type ImperativeHandler = {
+    close: () => void;
+    replace: (element: TargetElement) => void;
+    isRendered?: () => boolean;
+};
+export declare type UnmountType = () => Promise<void>;
+export declare type RenderType = (node: React.ReactElement, container: Element | DocumentFragment) => UnmountType;
+declare const MARK = "__pisell_react_root__";
+declare type ContainerType = (Element | DocumentFragment) & {
+    [MARK]?: Root;
+};
+export declare function render(node: React.ReactElement, container: ContainerType): void;
+export declare function unmount(container: ContainerType): Promise<void>;
+/**
+ * @deprecated 设置 React 渲染函数以兼容使用。
+ */
+export declare function unstableSetRender(render?: RenderType): RenderType;
+export declare function renderImperatively(element: TargetElement): ImperativeHandler;
+export {};

package/es/components/pisellToast/squareToast/toast.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import './index.less';
+export declare type ToastType = 'success' | 'error' | 'warning' | 'info' | 'loading';
+export interface ToastProps {
+    /** Toast 类型 */
+    icon?: ToastType | React.ReactNode;
+    /** 显示的内容，支持文本或 React 节点 */
+    content: React.ReactNode;
+    /** 是否显示 */
+    open?: boolean;
+    /** 自动关闭时间，单位毫秒，0 表示不自动关闭 */
+    duration?: number;
+    /** 关闭 */
+    onCancel?: () => void;
+    /** 关闭后回调 */
+    afterClose?: () => void;
+    /** 自定义样式类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: React.CSSProperties;
+    /** 是否显示遮罩 */
+    mask?: boolean;
+}
+declare const Toast: React.FC<ToastProps>;
+export default Toast;

package/es/components/pisellUrl/PisellUrl.stories.d.ts

@@ -0,0 +1,108 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellUrl } from './PisellUrl';
+/**
+ * PisellUrl 是一个 URL 地址输入/展示组件。
+ *
+ * ## 功能特性
+ * - 支持三种状态：只读、编辑、禁用
+ * - URL 格式校验
+ * - 协议自动补全
+ * - 链接跳转（新窗口，安全性保障）
+ * - 协议/路径显示控制
+ * - 协议白名单限制
+ */
+declare const meta: Meta<typeof PisellUrl>;
+export default meta;
+declare type Story = StoryObj<typeof PisellUrl>;
+/**
+ * 基础编辑态
+ */
+export declare const Basic: Story;
+/**
+ * 协议自动补全
+ */
+export declare const WithProtocolAutoComplete: Story;
+/**
+ * 只读态 - 可跳转
+ */
+export declare const ReadMode: Story;
+/**
+ * 只读态 - 隐藏协议
+ */
+export declare const ReadModeHideProtocol: Story;
+/**
+ * 只读态 - 仅域名
+ */
+export declare const ReadModeDomainOnly: Story;
+/**
+ * 禁用态（编辑）
+ */
+export declare const DisabledEdit: Story;
+/**
+ * 禁用态（只读）
+ */
+export declare const DisabledRead: Story;
+/**
+ * 必填校验
+ */
+export declare const Required: Story;
+/**
+ * 格式校验（实时）
+ */
+export declare const FormatValidation: Story;
+/**
+ * 协议限制（仅 HTTPS）
+ */
+export declare const HttpsOnly: Story;
+/**
+ * 协议必需
+ */
+export declare const RequireProtocol: Story;
+/**
+ * 显示清空按钮
+ */
+export declare const WithClearButton: Story;
+/**
+ * 自动聚焦
+ */
+export declare const WithAutoFocus: Story;
+/**
+ * 自定义样式（只读态）
+ */
+export declare const CustomStyle: Story;
+/**
+ * 显示控制对比
+ */
+export declare const DisplayFormatComparison: Story;
+/**
+ * 校验时机对比
+ */
+export declare const ValidateTriggerComparison: Story;
+/**
+ * 所有状态展示
+ */
+export declare const AllStates: Story;
+/**
+ * 完整功能示例
+ */
+export declare const CompleteExample: Story;
+/**
+ * 协议补全演示
+ */
+export declare const ProtocolCompleteDemo: Story;
+/**
+ * 链接跳转演示
+ */
+export declare const LinkClickDemo: Story;
+/**
+ * 协议限制演示
+ */
+export declare const ProtocolRestrictionDemo: Story;
+/**
+ * 完整交互示例
+ */
+export declare const InteractiveExample: Story;
+/**
+ * 协议默认值对比
+ */
+export declare const ProtocolDefaultComparison: Story;

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

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

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

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { PisellUrlProps } from '../types';
+/**
+ * PisellUrl 编辑态视图组件
+ *
+ * 职责：
+ * - 渲染编辑态 URL 输入框
+ * - 失焦时自动补全协议
+ * - 实时格式校验
+ * - 错误提示展示
+ *
+ * @param props 组件 Props
+ */
+declare const EditView: React.FC<PisellUrlProps>;
+export default EditView;

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

@@ -0,0 +1,15 @@
+import React from 'react';
+import type { PisellUrlProps } from '../types';
+/**
+ * PisellUrl 只读态视图组件
+ *
+ * 职责：
+ * - 渲染只读态 URL 链接展示
+ * - 支持点击新窗口打开链接（安全性保障）
+ * - 支持协议/路径隐藏
+ * - 支持链接图标
+ *
+ * @param props 组件 Props
+ */
+declare const ReadOnlyView: React.FC<PisellUrlProps>;
+export default ReadOnlyView;

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

@@ -0,0 +1,7 @@
+/**
+ * PisellUrl 组件导出文件
+ */
+import PisellUrl from './PisellUrl';
+export { PisellUrl };
+export default PisellUrl;
+export type { PisellUrlProps } from './types';

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

@@ -0,0 +1,160 @@
+import type { CSSProperties } from 'react';
+import type { BaseTextInputProps } from '@pisell/utils';
+/**
+ * PisellUrl 组件 Props 类型定义
+ *
+ * 继承 BaseTextInputProps，添加 URL 特有的配置
+ */
+export interface PisellUrlProps extends BaseTextInputProps {
+    /**
+     * 状态模式
+     * @default 'edit'
+     */
+    mode?: 'read' | 'edit';
+    /**
+     * 是否禁用
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * 是否使用严格校验
+     * @default true
+     */
+    strictValidation?: boolean;
+    /**
+     * 允许的协议列表
+     * @example ['http', 'https']
+     * @default ['http', 'https']
+     */
+    allowedProtocols?: string[];
+    /**
+     * 是否要求必须有协议
+     * @default false
+     */
+    requireProtocol?: boolean;
+    /**
+     * 是否自动补全协议
+     * @default true
+     */
+    autoCompleteProtocol?: boolean;
+    /**
+     * 默认协议
+     * @default 'https://'
+     */
+    defaultProtocol?: 'http://' | 'https://';
+    /**
+     * 协议补全回调
+     * @param url 补全后的 URL
+     */
+    onProtocolComplete?: (url: string) => void;
+    /**
+     * 是否启用链接跳转（只读态）
+     * @default true
+     */
+    enableLinkClick?: boolean;
+    /**
+     * 是否新窗口打开
+     * @default true
+     */
+    openInNewWindow?: boolean;
+    /**
+     * 是否显示链接图标
+     * @default true
+     */
+    showLinkIcon?: boolean;
+    /**
+     * 链接点击回调
+     * @param url URL 地址
+     */
+    onLinkClick?: (url: string) => void;
+    /**
+     * 是否显示协议（只读态）
+     * @default false
+     */
+    showProtocol?: boolean;
+    /**
+     * 是否显示 www 前缀（只读态）
+     * @default false
+     */
+    showWww?: boolean;
+    /**
+     * 是否显示路径（只读态）
+     * @default true
+     */
+    showPathname?: boolean;
+    /**
+     * 显示格式（只读态）
+     * - full: 完整 URL
+     * - domain: 仅域名
+     * - custom: 自定义格式
+     * @default 'full'
+     */
+    displayFormat?: 'full' | 'domain' | 'custom';
+    /**
+     * 自定义格式化函数（只读态）
+     * @param url URL 地址
+     * @returns 格式化后的显示文本
+     */
+    customFormat?: (url: string) => string;
+    /**
+     * 字号
+     * @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 '请输入 URL 地址'
+     */
+    placeholder?: string;
+    /**
+     * 最大长度
+     * @default 2048
+     */
+    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/pisellUrl/utils/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * PisellUrl 工具函数导出
+ */
+export * from './urlValidator';
+export * from './urlHelper';
+export * from './urlFormatter';