@morehao/ark-iam-react 0.0.0-stage → 1.0.0

package/dist/_types/ui/MainLayout.d.ts

@@ -0,0 +1,14 @@
+export interface MainMenuItems {
+    key: string;
+    icon?: React.ReactNode;
+    label: string;
+    children?: MainMenuItems[];
+}
+interface Props {
+    title: string;
+    subtitle?: string;
+    menuItems: MainMenuItems[];
+    hasTenantSwitch?: boolean;
+}
+export declare function MainLayout({ title, subtitle, menuItems, hasTenantSwitch }: Props): import("react").JSX.Element;
+export {};

package/dist/_types/ui/NameLink.d.ts

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+export interface NameLinkProps {
+    /** 名称内容；空值展示为 - */
+    value?: ReactNode;
+    /** 点击查看详情；未提供时退化为普通文本 */
+    onClick?: () => void;
+    /** 悬浮提示；默认取 value 的字符串形式 */
+    title?: string;
+    /** 使用等宽字体（日志键 / 编码类名称） */
+    monospace?: boolean;
+}
+/**
+ * 名称单元格：列表行的「名称即详情入口」（列表页操作列规范，见 DESIGN.md §7.3）。
+ *
+ * 详情不再占用操作列，而是通过点击名称打开；因此名称渲染为主色链接
+ * （hover 下划线 + 手型光标），让用户一眼看出可点击。名称过长时省略号截断并悬浮展示全称。
+ */
+export declare function NameLink({ value, onClick, title, monospace }: NameLinkProps): import("react").JSX.Element;

package/dist/_types/ui/PageContainer.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode } from 'react';
+interface Props {
+    title: string;
+    description?: string;
+    extra?: ReactNode;
+    children: ReactNode;
+    loading?: boolean;
+}
+/**
+ * 统一页面容器：页面标题区（标题 + 描述 + 右侧操作按钮）+ 内容卡片。
+ * 所有管理页共用，保证页面骨架一致。
+ */
+export declare function PageContainer({ title, description, extra, children, loading }: Props): import("react").JSX.Element;
+export declare function pageTitleStyle(): React.CSSProperties;
+export {};

package/dist/_types/ui/ProfileCenter.d.ts

@@ -0,0 +1,6 @@
+interface Props {
+    open: boolean;
+    onClose: () => void;
+}
+export declare function ProfileCenter({ open, onClose }: Props): import("react").JSX.Element;
+export {};

package/dist/_types/ui/RemoteSelect.d.ts

@@ -0,0 +1,57 @@
+import { type CSSProperties } from 'react';
+export interface RemoteSelectOption {
+    value: string;
+    label: string;
+}
+interface RemoteOptionsProps {
+    /** 远程取数：关键字为空表示取默认首页；返回值直接作为下拉选项 */
+    fetchOptions: (keyword: string) => Promise<RemoteSelectOption[]>;
+    /** 搜索去抖毫秒数，默认 300 */
+    debounceMs?: number;
+    /** 可选的外部名称缓存（`Map<值, 名称>`）：多个下拉共享已知名称，如筛选区选过的服务账号在弹窗表单里直接显示名称 */
+    labelCache?: Map<string, string>;
+}
+export interface RemoteSelectProps extends RemoteOptionsProps {
+    /** 受控值（`Form.Item` 自动注入） */
+    value?: string;
+    /** 选中回调；第二参为选中项，便于调用方保存名称（平台端列表经常要回显名称） */
+    onChange?: (value?: string, option?: RemoteSelectOption) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    allowClear?: boolean;
+    /** 固定宽度（筛选区用）；表单内不传则由容器撑满 */
+    width?: number;
+    /** 额外样式（如 `{ width: '100%' }` 撑满表单） */
+    style?: CSSProperties;
+    /** 已知当前值对应的名称：编辑态回显，避免选项未加载时显示裸 ID */
+    initialLabel?: string;
+    id?: string;
+}
+/**
+ * 远程搜索下拉（单选）：选项由 `fetchOptions` 按关键字从服务端取，不在前端一次性全量加载。
+ *
+ * 解决「下拉只取前 N 条 → 数据量上百后选不到目标」的问题（租户/应用/服务账号等可增长资源）。
+ * 不变量见 `useRemoteOptions`。
+ */
+export declare function RemoteSelect({ value, onChange, initialLabel, placeholder, disabled, allowClear, width, style, id, ...rest }: RemoteSelectProps): import("react").JSX.Element;
+export interface RemoteMultiSelectProps extends RemoteOptionsProps {
+    /** 受控值（多选，`Form.Item` 自动注入） */
+    value?: string[];
+    onChange?: (value?: string[], option?: RemoteSelectOption[]) => void;
+    /** 已知已选值的名称（如主体当前已分配的角色）：避免搜索结果未命中时显示裸 ID */
+    initialLabels?: Record<string, string>;
+    placeholder?: string;
+    disabled?: boolean;
+    allowClear?: boolean;
+    /** 固定宽度（筛选区用）；表单内不传则由容器撑满 */
+    width?: number;
+    /** 额外样式（如 `{ width: '100%' }` 撑满表单） */
+    style?: CSSProperties;
+    id?: string;
+}
+/**
+ * 远程搜索下拉（多选）：与 `RemoteSelect` 共用同一套「服务端搜索 + 过期响应丢弃 + 已选值名称兜底」，
+ * 用于角色授权这类「候选集可增长 + 已选项必须回显名称」的多值场景。
+ */
+export declare function RemoteMultiSelect({ value, onChange, initialLabels, placeholder, disabled, allowClear, width, style, id, ...rest }: RemoteMultiSelectProps): import("react").JSX.Element;
+export {};

package/dist/_types/ui/RowActions.d.ts

@@ -0,0 +1,36 @@
+import type { ReactNode } from 'react';
+/** 表格操作列中的单个操作。 */
+export interface RowAction {
+    /** 操作唯一标识（React key / 菜单 key） */
+    key: string;
+    /** 操作文案 */
+    label: ReactNode;
+    /** 点击回调 */
+    onClick?: () => void;
+    /** 危险操作：按钮/菜单项渲染为语义红 */
+    danger?: boolean;
+    /** 禁用 */
+    disabled?: boolean;
+    /** 二次确认文案；提供时点击后先确认再执行 onClick */
+    confirm?: ReactNode;
+    /** 可选图标（下拉菜单项会展示） */
+    icon?: ReactNode;
+    /** 运行时隐藏该操作（如已吊销的密钥不再展示「吊销」） */
+    hidden?: boolean;
+}
+export interface RowActionsProps {
+    /** 操作列表，按重要程度从高到低排列 */
+    actions: RowAction[];
+    /** 横排上限，超过则收起为「更多」下拉；默认 3 */
+    max?: number;
+}
+/**
+ * 统一的表格「操作列」渲染器（列表页操作列规范，见 DESIGN.md §7.3）：
+ * - 操作数 ≤ max（默认 3）：全部以 `Button type="link" size="small"` 横排；
+ * - 操作数 > max：保留前 `max - 1` 个高频操作横排，其余收进「更多」下拉（菜单项纵向排列），
+ *   避免操作列被撑宽、行内按钮挤成一团。
+ *
+ * 二次确认：横排操作用 Popconfirm 就地气泡确认；下拉菜单项用 Modal.confirm
+ * （菜单点击会先关闭下拉，气泡无法稳定锚定）。
+ */
+export declare function RowActions({ actions, max }: RowActionsProps): import("react").JSX.Element | null;

package/dist/_types/ui/TenantSwitcher.d.ts

@@ -0,0 +1 @@
+export declare function TenantSwitcher(): import("react").JSX.Element;

package/dist/_types/ui/TimeCell.d.ts

@@ -0,0 +1,53 @@
+import type { ColumnType } from 'antd/es/table';
+/**
+ * 时间列标准宽度（px）。
+ *
+ * 依据：完整时间串 `2026-09-03 17:19:46` 在 antd 表格 14px 字号 + 全站 `tabular-nums`
+ * 下实测 146.06px（macOS / Chrome / 系统字体栈，为常见平台里较宽的一种）；
+ * antd v5 单元格水平内边距为 `token.padding` × 2 = 32px，故单行显示至少需要 178.06px，
+ * 取 180 留余量。低于该值的列宽会让时间恰好在唯一的空格处折行成「日期 / 时间」两行
+ * （规范见 frontend/DESIGN.md §7.3）。
+ */
+export declare const TIME_COL_WIDTH = 180;
+/**
+ * 相对时间列宽度（px）：如「3 天前」实测 40.47px、最长档「10 个月前」约 63px，
+ * 加 32px 内边距后 120 有充足余量。
+ */
+export declare const TIME_COL_WIDTH_RELATIVE = 120;
+export interface TimeCellProps {
+    /** 秒级时间戳（约定见 AGENTS.md），兼容字符串与毫秒值 */
+    value?: number | string | null;
+    /** 空值占位文案（默认 '-'），如「永不过期」 */
+    placeholder?: string;
+    /** 相对时间模式：展示「3 天前」，悬浮给出完整 `YYYY-MM-DD HH:mm:ss` */
+    relative?: boolean;
+}
+/**
+ * 表格时间单元格：统一 `YYYY-MM-DD HH:mm:ss`，并强制单行不折行。
+ *
+ * 所有时间列都必须走本组件（或 `timeColumn` 工厂），禁止页面直接 `fmtTime` 且自定列宽 ——
+ * 列宽与 `whiteSpace: nowrap` 是一对，缺任何一半都会出现"折行"或"溢出串列"。
+ */
+export declare function TimeCell({ value, placeholder, relative }: TimeCellProps): import("react").JSX.Element;
+export interface TimeColumnConfig<T> {
+    title: string;
+    /** 记录字段名；同时作为列的 key */
+    dataIndex: keyof T & string;
+    /** 覆盖默认列宽（默认绝对时间 180 / 相对时间 120） */
+    width?: number;
+    placeholder?: string;
+    /** 次要时间字段（最后使用 / 登录时间等）用相对时间 + Tooltip */
+    relative?: boolean;
+}
+/**
+ * 时间列工厂：一次给出「标题 + 字段 + 标准列宽 + TimeCell 渲染」，
+ * 避免各页面手写列宽（历史 bug 根因就是每页各写 150/160/170）。
+ *
+ * ```tsx
+ * const columns: ColumnsType<TenantItem> = [
+ *   timeColumn<TenantItem>({ title: '创建时间', dataIndex: 'createdAt' }),
+ *   timeColumn<TenantUserLoginLogItem>({ title: '登录时间', dataIndex: 'loginTime', relative: true }),
+ * ]
+ * ```
+ */
+export declare function timeColumn<T>({ title, dataIndex, width, placeholder, relative, }: TimeColumnConfig<T>): ColumnType<T>;

package/dist/_types/ui/columns.d.ts

@@ -0,0 +1,116 @@
+import type { ReactNode } from 'react';
+import type { ColumnType } from 'antd/es/table';
+import { type RowAction } from './RowActions';
+/**
+ * 列表列宽标准（px）与列工厂（规范见 frontend/DESIGN.md §7.3）。
+ *
+ * 背景：历史 bug 是各页手写列宽 + 手写 `scroll.x`，列宽普遍偏大（ID 150、编码 180…）
+ * 叠加后总宽轻松超过内容区，导致「一进列表就有横向滚动条、操作列要横滑很久才看得到」。
+ * 这里把所有列宽收口成具名常量与工厂，页面不再出现魔法数字。
+ *
+ * 列宽 = 内容实测宽 + antd v5 单元格左右内边距（16 × 2 = 32）。
+ */
+/** ID 列：`IDCell` 默认展示「首 8 + … + 尾 4」共 13 个 12px 等宽字符（≈93.6px）+ 内边距。 */
+export declare const ID_COL_WIDTH = 130;
+/** 名称列：约 10 个汉字；过长由 `NameLink` / `EllipsisCell` 省略号截断。 */
+export declare const NAME_COL_WIDTH = 180;
+/** 编码 / key / 域名等等宽短标识列。 */
+export declare const CODE_COL_WIDTH = 150;
+/** 分类 Tag 列（类型 / 可见性 / 来源等）。 */
+export declare const TAG_COL_WIDTH = 110;
+/** 状态 Tag 列（正常 / 挂起 / 启用 / 停用）。 */
+export declare const STATUS_COL_WIDTH = 100;
+/** 数字计数列（成员数、角色数、排序）。 */
+export declare const COUNT_COL_WIDTH = 90;
+/** 自由文本列（描述、备注等），一律省略号截断。 */
+export declare const TEXT_COL_WIDTH = 200;
+/** 长文本列（日志 payload、长描述）：比 `TEXT_COL_WIDTH` 宽一档，仍省略号截断。 */
+export declare const LONG_TEXT_COL_WIDTH = 320;
+export interface IDColumnConfig<T> {
+    /** 记录中的 ID 字段 */
+    dataIndex: keyof T & string;
+    /** 列标题，默认 `ID` */
+    title?: string;
+    /** 覆盖默认列宽（默认 `ID_COL_WIDTH`） */
+    width?: number;
+}
+/**
+ * ID 列：`IDCell`（等宽 + 首 8 尾 4 + Tooltip 可拖选复制）。
+ *
+ * 同一行已有对外可读业务键（编码 / 客户端编码 / key / 域名）时，内部 UUID 列通常是噪声，
+ * 可按需省略；保留时一律用本工厂（默认 130，而非手写 150）。
+ */
+export declare function idColumn<T>({ dataIndex, title, width }: IDColumnConfig<T>): ColumnType<T>;
+export interface TextColumnConfig<T> {
+    title: ReactNode;
+    /** 记录字段名；同时作为列的 key */
+    dataIndex: keyof T & string;
+    /** 列宽；不传时取 `TEXT_COL_WIDTH` */
+    width?: number;
+    /** 空值占位文案，默认 `-` */
+    placeholder?: string;
+    /** 等宽字体（编码 / key / 路径等） */
+    monospace?: boolean;
+}
+/**
+ * 文本列：`EllipsisCell`（超出省略号截断 + 悬浮展示全文），列宽固定不随内容膨胀。
+ */
+export declare function textColumn<T>({ title, dataIndex, width, placeholder, monospace, }: TextColumnConfig<T>): ColumnType<T>;
+export interface NameColumnConfig<T> {
+    title: ReactNode;
+    /** 记录字段名；同时作为列的 key */
+    dataIndex: keyof T & string;
+    /** 列宽；不传时取 `NAME_COL_WIDTH` */
+    width?: number;
+    /** 等宽字体（日志键 / 编码类名称） */
+    monospace?: boolean;
+    /** 点击名称的回调（详情 / 下级入口）；不传时退化为普通文本 */
+    onClick?: (record: T) => void;
+}
+/**
+ * 名称列：`NameLink`（主色链接，详情入口；见 DESIGN.md §7.3 R2）。
+ */
+export declare function nameColumn<T>({ title, dataIndex, width, monospace, onClick, }: NameColumnConfig<T>): ColumnType<T>;
+export interface ActionColumnConfig<T> {
+    /** 由记录生成操作列表，按重要程度从高到低排列 */
+    actions: (record: T) => RowAction[];
+    /** 横排上限，超过则收起为「更多」下拉；默认 3 */
+    max?: number;
+    /** 覆盖自动计算的列宽 */
+    width?: number;
+}
+/**
+ * 操作列工厂（列表页操作列规范，DESIGN.md §7.3 R1）：
+ * - 统一 `RowActions` 渲染（≤ max 横排，> max 收「更多」）；
+ * - **永远 `fixed: 'right'`**：即使表格出现横向滚动，操作列也钉在右侧可见，
+ *   不会再出现「横向滑动很久才看到操作」；
+ * - 列宽由 `actionColumnWidth(max)` 统一给出，页面禁止再手写 120/200/240。
+ */
+export declare function actionColumn<T>({ actions, max, width }: ActionColumnConfig<T>): ColumnType<T>;
+/**
+ * 操作列宽度估算（px）：`单元格内边距 32 + 横排数 × 56 + 间距 4`，向上取整到 10。
+ *
+ * 56 = 约 3 个汉字（42px）+ link 按钮左右内边距（14px）。**横排按钮文案应保持简短
+ * （≤ 4 个汉字）**；文案更长时请降低 `max` 把它收进「更多」下拉，或显式传入 `width`。
+ */
+export declare function actionColumnWidth(max: number): number;
+type WidthableColumn<T> = ColumnType<T> & {
+    children?: WidthableColumn<T>[];
+};
+/**
+ * 由列定义计算表格 `scroll.x`：所有列宽之和。
+ *
+ * 取代各页手写的 `scroll={{ x: 1490 }}`——手写值会随列增删漂移（历史上 apiKey 页
+ * 实际列宽合计已到 1580 却仍写 1520），且写大了会让本可放下的表格也强制出现横滚条。
+ *
+ * 配合 `tableLayout="fixed"`：列宽严格生效（`EllipsisCell` / `TimeCell` 才能正确截断），
+ * 总宽小于容器时表格按 `min-width: 100%` 铺满，不会留白也不会出现滚动条。
+ *
+ * ```tsx
+ * <Table columns={columns} scroll={tableScrollX(columns)} tableLayout="fixed" />
+ * ```
+ */
+export declare function tableScrollX<T>(columns: readonly WidthableColumn<T>[]): {
+    x: number;
+};
+export {};

package/dist/_types/ui/format.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 时间渲染：兼容秒级时间戳与字符串，统一为 `YYYY-MM-DD HH:mm:ss`。
+ * 前后端时间交互约定为秒级 int64 时间戳（见 AGENTS.md），前端展示统一走本函数。
+ */
+export declare function fmtTime(value?: number | string | null): string;
+/**
+ * 时间戳归一化为毫秒：约定入参是秒级时间戳（AGENTS.md），
+ * 同时兼容历史上传入的毫秒值（1e12 已远超秒级上限，可安全区分）。
+ */
+export declare function toMillis(value: number): number;
+/**
+ * 相对时间：`刚刚 / N 分钟前 / N 小时前 / N 天前 / N 个月前 / N 年前`。
+ *
+ * 只用于「最后使用 / 最近使用 / 登录时间」这类"最近"语义的次要时间字段
+ * （列窄、扫描时只需粒度感，精确时间由 TimeCell 的 Tooltip 兜底）。
+ * - 时间戳晚于当前时刻（时钟漂移等）不猜测为"N 分钟后"，回退绝对时间；
+ * - 空值返回空串，由 TimeCell 负责占位文案（如「从未使用」）；
+ * - `now` 仅用于测试注入。
+ */
+export declare function fmtRelativeTime(value?: number | string | null, now?: number): string;

package/dist/_types/ui/index.d.ts

@@ -0,0 +1,25 @@
+export { MainLayout } from './MainLayout';
+export type { MainMenuItems } from './MainLayout';
+export { LoginPage } from './LoginPage';
+export { TenantSwitcher } from './TenantSwitcher';
+export { ProfileCenter } from './ProfileCenter';
+export { PageContainer } from './PageContainer';
+export { IDCell } from './IDCell';
+export { InitialPasswordModal } from './InitialPasswordModal';
+export type { InitialPasswordModalProps } from './InitialPasswordModal';
+export { EllipsisCell } from './EllipsisCell';
+export type { EllipsisCellProps } from './EllipsisCell';
+export { ID_COL_WIDTH, NAME_COL_WIDTH, CODE_COL_WIDTH, TAG_COL_WIDTH, STATUS_COL_WIDTH, COUNT_COL_WIDTH, TEXT_COL_WIDTH, LONG_TEXT_COL_WIDTH, idColumn, textColumn, nameColumn, actionColumn, actionColumnWidth, tableScrollX, } from './columns';
+export type { IDColumnConfig, TextColumnConfig, NameColumnConfig, ActionColumnConfig, } from './columns';
+export { RowActions } from './RowActions';
+export type { RowAction, RowActionsProps } from './RowActions';
+export { NameLink } from './NameLink';
+export type { NameLinkProps } from './NameLink';
+export { RemoteSelect, RemoteMultiSelect } from './RemoteSelect';
+export type { RemoteMultiSelectProps, RemoteSelectOption, RemoteSelectProps, } from './RemoteSelect';
+export { AppShell } from './AppShell';
+export { themeConfig, brand, tokens } from './theme';
+export { EnableTag, SuspendedTag, VerifiedTag, TypeTag, SourceTag } from './status';
+export { fmtTime, fmtRelativeTime, toMillis } from './format';
+export { TimeCell, TIME_COL_WIDTH, TIME_COL_WIDTH_RELATIVE, timeColumn } from './TimeCell';
+export type { TimeCellProps, TimeColumnConfig } from './TimeCell';