@pisell/materials 1.8.23 → 1.8.24

package/lib/components/pisellSingleSelect/PisellSingleSelect.stories.d.ts

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import PisellSingleSelect from './PisellSingleSelect';
+/**
+ * PisellSingleSelect 组件 Storybook
+ *
+ * 用于展示和测试组件的各种状态和配置
+ */
+declare const meta: Meta<typeof PisellSingleSelect>;
+export default meta;
+declare type Story = StoryObj<typeof PisellSingleSelect>;
+/**
+ * 基础示例
+ */
+export declare const Basic: Story;
+/**
+ * 带标签
+ */
+export declare const WithLabel: Story;
+/**
+ * 带辅助文本
+ */
+export declare const WithHelperText: Story;
+/**
+ * 带搜索功能
+ */
+export declare const WithSearch: Story;
+/**
+ * 带清空按钮
+ */
+export declare const WithClear: Story;
+/**
+ * 禁用态
+ */
+export declare const Disabled: Story;
+/**
+ * 只读态
+ */
+export declare const ReadOnly: Story;
+/**
+ * 只读态 - 空值
+ */
+export declare const ReadOnlyEmpty: Story;
+/**
+ * 错误状态
+ */
+export declare const WithError: Story;
+/**
+ * 不同尺寸
+ */
+export declare const Sizes: Story;
+/**
+ * 表单场景
+ */
+export declare const InForm: Story;
+/**
+ * 自定义过滤
+ */
+export declare const CustomFilter: Story;
+/**
+ * 回调事件演示
+ */
+export declare const WithCallbacks: Story;
+/**
+ * 所有状态组合
+ */
+export declare const AllStates: Story;

package/lib/components/pisellSingleSelect/components/DisabledView.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PisellSingleSelect - DisabledView (禁用态视图)
+ * 禁用状态下的渲染
+ */
+import React from 'react';
+import type { DisabledViewProps } from '../types';
+declare const DisabledView: React.ForwardRefExoticComponent<DisabledViewProps<string | number> & React.RefAttributes<any>>;
+export default DisabledView;

package/lib/components/pisellSingleSelect/components/EditView.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PisellSingleSelect - EditView (编辑态视图)
+ * 正常可编辑状态下的渲染
+ */
+import React from 'react';
+import type { EditViewProps } from '../types';
+declare const EditView: React.ForwardRefExoticComponent<EditViewProps<string | number> & React.RefAttributes<any>>;
+export default EditView;

package/lib/components/pisellSingleSelect/components/ReadOnlyView.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PisellSingleSelect - ReadOnlyView (只读态视图)
+ * 只读状态下使用 Tag 展示选中值
+ */
+import React from 'react';
+import type { ReadOnlyViewProps } from '../types';
+declare const ReadOnlyView: React.FC<ReadOnlyViewProps>;
+export default ReadOnlyView;

package/lib/components/pisellSingleSelect/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * PisellSingleSelect 组件导出
+ */
+import PisellSingleSelect from './PisellSingleSelect';
+export { PisellSingleSelect };
+export type { PisellSingleSelectProps, SingleSelectRef, EditViewProps, DisabledViewProps, ReadOnlyViewProps, } from './types';
+export type { SelectOption, FilterOptionFunc, SortDirection, SelectState, } from './types';

package/lib/components/pisellSingleSelect/types.d.ts

@@ -0,0 +1,92 @@
+import type { BaseSelectProps, SelectOption } from '@pisell/utils';
+/**
+ * PisellSingleSelect 组件 Props 类型定义
+ *
+ * 继承 BaseSelectProps，添加单选特有的配置
+ * @template T 选项值的类型，默认为 string | number
+ */
+export interface PisellSingleSelectProps<T = string | number> extends BaseSelectProps<T> {
+    /**
+     * 受控模式：当前选中值
+     */
+    value?: T | null;
+    /**
+     * 非受控模式：默认选中值
+     */
+    defaultValue?: T;
+    /**
+     * 值变化回调
+     * @param value 新的选中值
+     * @param option 选中的选项对象（如果值为 null 则 option 也为 null）
+     */
+    onChange?: (value: T | null, option: SelectOption<T> | null) => void;
+    /**
+     * ARIA 标签
+     */
+    'aria-label'?: string;
+    /**
+     * ARIA 是否必填
+     */
+    'aria-required'?: boolean;
+    /**
+     * ARIA 是否无效
+     */
+    'aria-invalid'?: boolean;
+    /**
+     * ARIA 描述关联 ID
+     */
+    'aria-describedby'?: string;
+}
+/**
+ * PisellSingleSelect 组件 Ref 方法
+ * @template T 选项值的类型
+ */
+export interface SingleSelectRef<T = string | number> {
+    /**
+     * 聚焦到组件
+     */
+    focus: () => void;
+    /**
+     * 失焦
+     */
+    blur: () => void;
+    /**
+     * 获取当前选中值
+     */
+    getValue: () => T | null;
+    /**
+     * 设置选中值
+     */
+    setValue: (value: T | null) => void;
+    /**
+     * 清空选中值
+     */
+    clearValue: () => void;
+}
+/**
+ * EditView 组件 Props
+ * @template T 选项值的类型
+ */
+export interface EditViewProps<T = string | number> extends PisellSingleSelectProps<T> {
+    /**
+     * 内部状态管理对象（从 useSelectState Hook 传入）
+     */
+    state?: {
+        value: T | null | undefined;
+        setValue: (value: T | null) => void;
+        clearValue: () => void;
+    };
+}
+/**
+ * DisabledView 组件 Props
+ * @template T 选项值的类型
+ */
+export interface DisabledViewProps<T = string | number> extends PisellSingleSelectProps<T> {
+}
+/**
+ * ReadOnlyView 组件 Props
+ * @template T 选项值的类型
+ */
+export interface ReadOnlyViewProps<T = string | number> extends PisellSingleSelectProps<T> {
+}
+export type { SelectOption, FilterOptionFunc, SortDirection, SelectState, } from '@pisell/utils';

package/lib/components/pisellText/components/Amount/index.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import { PisellContextType } from '../../../pisell-config-provider/context';
+export interface AmountProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** 平台 */
+    platform?: PisellContextType['platform'];
+    /** 当前数值  */
+    value?: number | string;
+    /** 小数点后位数 默认是小数点后2位 */
+    precision?: number;
+    /** 显示货币符号 指的是 ¥$ 等货币符号等显隐，默认是展示 */
+    showCurrencySymbol?: boolean;
+    /** 千分位 指的是长金额的千分位逗号隔开，比如“123, 245, 315” 这种展现形式，默认是关闭 */
+    useThousandsSeparator?: boolean;
+    /** 整数位隐藏小数 指的是如果价格为整数，后面的".00" 将被省略以节省页面空间 */
+    hideDecimalForWholeNumbers?: boolean;
+    /** 货币符号 */
+    symbol?: string;
+}
+declare const Amount: (props: AmountProps) => JSX.Element;
+export default Amount;

package/lib/components/pisellText/components/Editable/index.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import './index.less';
+export declare type MultiLanguageValue = {
+    en: string;
+    'zh-CN': string;
+    'zh-HK': string;
+    'ja': string;
+    'pt': string;
+    original: string;
+};
+export interface EditableConfig {
+    /** 是否禁用编辑 */
+    disabled?: boolean;
+    /** 最大长度 */
+    maxLength?: number;
+    /** 编辑图标 */
+    icon?: React.ReactNode;
+}
+export interface EditableProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** 文本内容，支持字符串或多语言对象 */
+    value?: string | MultiLanguageValue;
+    /** 子节点内容，优先级高于 value */
+    children?: string;
+    /** 可编辑配置，boolean 时使用默认配置 */
+    editable?: boolean | EditableConfig;
+    /** 编辑变更回调 */
+    onChange?: (value: string | MultiLanguageValue) => void;
+    /** 输入框尺寸 */
+    size?: 'large' | 'middle' | 'small';
+}
+declare const Editable: React.FC<EditableProps>;
+export default Editable;

package/lib/components/pisellTimeNavigator/PisellTimeNavigator.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="react" />
+import type { PisellTimeNavigatorProps } from './types';
+import './PisellTimeNavigator.less';
+/**
+ * PisellTimeNavigator：可拖动的时间导航轴，时间范围内浏览、选择、控制
+ */
+export declare function PisellTimeNavigator(props: PisellTimeNavigatorProps): JSX.Element;
+export declare namespace PisellTimeNavigator {
+    var displayName: string;
+}

package/lib/components/pisellTimeNavigator/PisellTimeNavigator.js

@@ -66,7 +66,7 @@ function PisellTimeNavigator(props) {
     disabledRanges,
     showNowButton = true,
     userInteractionLocked = false,
-    snapToStep = true,
+    snapToStep = false,
     inertia = false,
     businessHours,
     pastTimeFade,

package/lib/components/pisellTimeNavigator/PisellTimeNavigator.less

@@ -236,6 +236,8 @@
   color: #000;
   /* 与 dot 一致：以格子水平中心为基准，避免与竖线错位 */
   text-align: center;
+  /** 窄格（cursor-moves 压缩）下小时数字不换行 */
+  white-space: nowrap;
 }
 
 .pisell-time-navigator-scale-cell--h .pisell-time-navigator-scale-label {

package/lib/components/pisellTimeNavigator/PisellTimeNavigator.stories.d.ts

@@ -0,0 +1,79 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { PisellTimeNavigator } from './PisellTimeNavigator';
+/**
+ * PisellTimeNavigator 组件 Storybook
+ * 时间导航轴：时间范围内浏览、选择、控制
+ */
+declare const meta: Meta<typeof PisellTimeNavigator>;
+export default meta;
+declare type Story = StoryObj<typeof PisellTimeNavigator>;
+/**
+ * 默认：横向、轴动、显示 Now
+ */
+export declare const Default: Story;
+/** 默认 - 竖向 */
+export declare const DefaultVertical: Story;
+/**
+ * 受控 + 默认 12:00
+ */
+export declare const Controlled: Story;
+/** 受控 - 竖向 */
+export declare const ControlledVertical: Story;
+/**
+ * 非受控 + 默认 14:30
+ */
+export declare const Uncontrolled: Story;
+/** 非受控 - 竖向 */
+export declare const UncontrolledVertical: Story;
+/**
+ * 竖向
+ */
+export declare const Vertical: Story;
+/**
+ * 指针动模式（cursor-moves）
+ */
+export declare const CursorMoves: Story;
+/** 指针动模式 - 竖向 */
+export declare const CursorMovesVertical: Story;
+/**
+ * 营业时间高亮 10:00–22:00
+ */
+export declare const BusinessHours: Story;
+/** 营业时间高亮 - 竖向 */
+export declare const BusinessHoursVertical: Story;
+/**
+ * 自定义时间范围 08:00–20:00
+ */
+export declare const CustomRange: Story;
+/** 自定义时间范围 - 竖向 */
+export declare const CustomRangeVertical: Story;
+/**
+ * 步长 30 分钟
+ */
+export declare const Step30: Story;
+/** 步长 30 分钟 - 竖向 */
+export declare const Step30Vertical: Story;
+/**
+ * 惯性滚动开启
+ */
+export declare const Inertia: Story;
+/** 惯性滚动 - 竖向 */
+export declare const InertiaVertical: Story;
+/**
+ * 吸附到整点（松手后自动吸附到 0/15/30/45 分刻度）
+ */
+export declare const SnapToStep: Story;
+/** 吸附到整点 - 竖向 */
+export declare const SnapToStepVertical: Story;
+/**
+ * 隐藏 Now 按钮
+ */
+export declare const NoNowButton: Story;
+/** 隐藏 Now 按钮 - 竖向 */
+export declare const NoNowButtonVertical: Story;
+/**
+ * 实时模式（仅演示，实际会跟随系统时间）
+ */
+export declare const Realtime: Story;
+/** 实时模式 - 竖向 */
+export declare const RealtimeVertical: Story;

package/lib/components/pisellTimeNavigator/components/NowButton.d.ts

@@ -0,0 +1,14 @@
+import React from 'react';
+import type { CSSProperties } from 'react';
+export interface NowButtonProps {
+    orientation: 'horizontal' | 'vertical';
+    onClick: () => void;
+    style?: CSSProperties;
+    className?: string;
+    renderCustom?: () => React.ReactNode;
+}
+/**
+ * Now 按钮：固定入口，点击跳回当前时间并进入 Realtime
+ * 横向：右侧，左箭头；竖向：底部，上箭头
+ */
+export declare function NowButton({ orientation, onClick, style, className, renderCustom, }: NowButtonProps): JSX.Element;

package/lib/components/pisellTimeNavigator/components/index.d.ts

@@ -0,0 +1,5 @@
+export { BackgroundLayer } from './BackgroundLayer';
+export { CursorLayer } from './CursorLayer';
+export { GestureLayer } from './GestureLayer';
+export { NowButton } from './NowButton';
+export { ScaleLayer } from './ScaleLayer';

package/lib/components/pisellTimeNavigator/hooks/index.d.ts

@@ -0,0 +1,5 @@
+export { useTimeAxis } from './useTimeAxis';
+export type { UseTimeAxisOptions, TimeAxisState } from './useTimeAxis';
+export { useRealtime } from './useRealtime';
+export { useDragInertia } from './useDragInertia';
+export type { UseDragInertiaOptions } from './useDragInertia';

package/lib/components/pisellTimeNavigator/hooks/useTimeAxis.d.ts

@@ -0,0 +1,27 @@
+import type { Dayjs } from 'dayjs';
+import type { TimeRangeOption } from '../types';
+export interface UseTimeAxisOptions {
+    range?: TimeRangeOption;
+    stepMinutes: number;
+    referenceDate: Dayjs;
+    orientation: 'horizontal' | 'vertical';
+    /** 横向时每格宽度（px），竖向时每格高度（px） */
+    cellSizePx: number;
+}
+export interface TimeAxisState {
+    rangeStart: Dayjs;
+    rangeEnd: Dayjs;
+    ticks: Dayjs[];
+    /** 时间转主轴偏移（px） */
+    timeToOffset: (t: Dayjs) => number;
+    /** 主轴偏移（px）转时间（最近刻度，用于刻度对齐） */
+    offsetToTime: (offset: number) => Dayjs | null;
+    /** 主轴偏移（px）转时间（连续插值，用于拖动时按分钟步长显示） */
+    offsetToTimeContinuous: (offset: number) => Dayjs | null;
+    /** 主轴总长度（px） */
+    totalLengthPx: number;
+}
+/**
+ * 时间轴刻度与时间↔像素换算
+ */
+export declare function useTimeAxis(options: UseTimeAxisOptions): TimeAxisState;

package/lib/components/pisellTimeNavigator/types.d.ts

@@ -0,0 +1,160 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { Dayjs } from 'dayjs';
+/**
+ * value / defaultValue 的 dayjs 兼容类型（组件内部统一为 Dayjs）
+ */
+export declare type TimeNavigatorValue = Dayjs | string | null;
+/**
+ * 时间范围（HH:mm 或 HH:mm:ss，相对 referenceDate 的营业日）
+ * - 同自然日：如 08:00–22:00
+ * - 跨日：结束钟面 ≤ 开始时视为次日结束，如 02:01–02:00 表示至次日 02:00
+ */
+export interface TimeRangeOption {
+    start: string;
+    end: string;
+}
+/**
+ * 拖动/指示器模式
+ * - axis-moves：指示器固定视口中央，刻度移动（默认）
+ * - cursor-moves：刻度固定，指示器在轴上移动
+ */
+export declare type CursorMode = 'axis-moves' | 'cursor-moves';
+/**
+ * 布局方向
+ */
+export declare type TimeNavigatorOrientation = 'horizontal' | 'vertical';
+/**
+ * PisellTimeNavigator 组件 Props
+ */
+export interface PisellTimeNavigatorProps {
+    /**
+     * 当前选中时间（受控）。支持 dayjs 实例或可被 dayjs 解析的字符串
+     */
+    value?: TimeNavigatorValue;
+    /**
+     * 时间变更回调（受控时必传）
+     */
+    onChange?: (value: Dayjs) => void;
+    /**
+     * 默认选中时间（非受控）
+     */
+    defaultValue?: TimeNavigatorValue;
+    /**
+     * 时间轴锚定到的日历日（startOf day）。`range` 的 HH:mm 均相对于该日。
+     * 不传则与历史一致：取「当天」0 点，避免跨天后刻度错位。
+     */
+    referenceDate?: TimeNavigatorValue;
+    /**
+     * 是否 Realtime 模式：value 自动跟随系统当前时间更新
+     * @default false
+     */
+    realtime?: boolean;
+    /**
+     * 时间范围（支持跨日营业，见 {@link TimeRangeOption}）。不传则默认当日 00:00–24:00
+     */
+    range?: TimeRangeOption;
+    /**
+     * 吸附步长（分钟），如 15、30、60
+     * @default 15
+     */
+    stepMinutes?: number;
+    /**
+     * 大刻度间隔（分钟），用于整点刻度；不传则与 stepMinutes 一致或 60
+     * @default 60
+     */
+    majorStepMinutes?: number;
+    /**
+     * 指示器/轴移动模式
+     * @default 'axis-moves'
+     */
+    cursorMode?: CursorMode;
+    /**
+     * 横向或竖向展示
+     * @default 'horizontal'
+     */
+    orientation?: TimeNavigatorOrientation;
+    /**
+     * 营业时间范围（视觉高亮，可选限制选择范围）
+     */
+    businessHours?: TimeRangeOption;
+    /**
+     * 禁用时间段，禁止选中（点击/吸附到该区间无效）
+     */
+    disabledRanges?: TimeRangeOption[];
+    /**
+     * 是否显示 Now 按钮（固定入口）
+     * @default true
+     */
+    showNowButton?: boolean;
+    /**
+     * 为 true 时禁止用户拖动/滚动时间轴、点击刻度改时间（仍随 `value` 程序性对齐视口；用于「跟随当前时刻」等只读轴）
+     * @default false
+     */
+    userInteractionLocked?: boolean;
+    /**
+     * 是否吸附到 step 刻度
+     * @default false
+     */
+    snapToStep?: boolean;
+    /**
+     * 是否开启惯性滚动（拖动松手后减速）
+     * @default false
+     */
+    inertia?: boolean;
+    /**
+     * 过去时间淡化背景色（CSS 颜色值）
+     */
+    pastTimeFade?: string;
+    /**
+     * 容器样式覆盖
+     */
+    containerStyle?: CSSProperties;
+    /**
+     * 刻度层样式覆盖
+     */
+    scaleStyle?: CSSProperties;
+    /**
+     * 时间气泡/竖线样式覆盖（区分 realtime 时由组件内部应用主题色）
+     */
+    cursorStyle?: CSSProperties;
+    /**
+     * Now 按钮样式覆盖
+     */
+    nowButtonStyle?: CSSProperties;
+    /**
+     * 自定义类名
+     */
+    className?: string;
+    /**
+     * 根节点自定义样式
+     */
+    style?: CSSProperties;
+    /**
+     * dayjs locale
+     */
+    locale?: string;
+    /**
+     * 时间气泡展示格式（dayjs format）
+     * @default 'HH:mm'
+     */
+    timeFormat?: string;
+    /**
+     * 自定义 Now 按钮内容（覆盖默认文案与图标时使用）
+     */
+    renderNowButton?: () => ReactNode;
+    /**
+     * 横向轴上与刻度槽位数一致的密度序列（任意正数，内部按最大值归一化折线高度）
+     */
+    densitySeries?: number[];
+    /**
+     * 未传 `densitySeries` 时按 `referenceDate` 拉取；日历日变更会重新请求，过期响应丢弃
+     */
+    loadDensity?: (params: {
+        referenceDate: Dayjs;
+        stepMinutes: number;
+    }) => Promise<number[]>;
+    /**
+     * 用户开始操作时间轴（拖轴、点刻度、键盘、拖指针等）时回调；用于上层关闭「跟随当前」等。
+     */
+    onUserInteraction?: () => void;
+}

package/lib/components/pisellTimeNavigator/utils/index.d.ts

@@ -0,0 +1,30 @@
+import { type Dayjs } from 'dayjs';
+import type { TimeNavigatorValue, TimeRangeOption } from '../types';
+/**
+ * 解析 value 为 Dayjs，无效则返回 null。
+ * 支持 dayjs 可解析的日期时间；纯时间字符串（如 '12:00'、'14:30'）会基于 reference 的日期解析。
+ */
+export declare function parseValue(value: TimeNavigatorValue, reference?: Dayjs): Dayjs | null;
+/**
+ * 将 range 转为 [startDayjs, endDayjs]（reference 为营业锚定日的 0 点）
+ * - 同日内：如 08:00–22:00
+ * - 跨日营业：结束钟面早于或等于开始（如 02:01–次日 02:00）时，end 解析为 reference 的次日同一时刻
+ */
+export declare function getRangeBounds(range: TimeRangeOption | undefined, reference: Dayjs): [Dayjs, Dayjs];
+/**
+ * 将时间吸附到 step 分钟刻度（0、15、30、45 等）：四舍五入到最近刻度。
+ */
+export declare function snapToStepMinutes(t: Dayjs, stepMinutes: number): Dayjs;
+/**
+ * 判断时间是否落在任一禁用区间内（按绝对时间与区间 [start,end) 比较）
+ * 注：与主时间轴同 reference 的跨日 range 一致时需传入同一营业锚定日解析出的区间。
+ */
+export declare function isInDisabledRanges(t: Dayjs, disabledRanges: TimeRangeOption[] | undefined): boolean;
+/**
+ * 在 [rangeStart, rangeEnd] 内按 stepMinutes 生成刻度时间列表（Dayjs）
+ */
+export declare function getTicks(rangeStart: Dayjs, rangeEnd: Dayjs, stepMinutes: number): Dayjs[];
+/**
+ * 横向时间轴「格」数量，与 useTimeAxis 中 totalLengthPx 算法一致（含尾格）
+ */
+export declare function getHorizontalAxisSlotCount(range: TimeRangeOption | undefined, referenceDate: Dayjs, stepMinutes: number): number;

package/lib/components/pisellTimeRangeDisplay/PisellTimeRangeDisplay.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+import 'dayjs/locale/zh-cn';
+import 'dayjs/locale/en';
+import type { PisellTimeRangeDisplayProps } from './types';
+import './PisellTimeRangeDisplay.less';
+/**
+ * PisellTimeRangeDisplay 组件
+ *
+ * @description
+ * 纯展示型时间区间组件，将 startAt / endAt 格式化为「时间区间 + 持续时间」。
+ * - 同一天：HH:mm-HH:mm，可选显示日期/星期
+ * - 跨天：起止日期时间
+ * - 持续时间：d h m s 格式
+ * - 字段顺序由 fieldOrder 控制，可将 duration 放在中间
+ *
+ * @example
+ * <PisellTimeRangeDisplay
+ *   startAt="2026-02-04 09:00"
+ *   endAt="2026-02-04 18:00"
+ * />
+ * // => "09:00-18:00" + "9h"
+ *
+ * <PisellTimeRangeDisplay
+ *   startAt={start}
+ *   endAt={end}
+ *   fields={{ fieldOrder: ['time', 'duration', 'date', 'weekday'] }}
+ *   showDateForSameDay
+ * />
+ */
+export declare const PisellTimeRangeDisplay: React.FC<PisellTimeRangeDisplayProps>;
+declare const _default: React.NamedExoticComponent<PisellTimeRangeDisplayProps>;
+export default _default;