@autional/ui 0.0.0-stage → 0.1.0-rc.42

package/src/molecules/UserMenu.tsx

@@ -0,0 +1,168 @@
+import type React from 'react';
+import { useTranslation } from 'react-i18next';
+import { ChevronDown, LogOut, Settings, UserRound } from 'lucide-react';
+import { useMenuButton } from '../internal/use-menu-button';
+
+export interface UserMenuUserInfo {
+	displayName?: string | null;
+	username?: string | null;
+	email?: string | null;
+	avatarUrl?: string | null;
+}
+
+export interface UserMenuItemSpec {
+	key: string;
+	type?: 'settings' | 'profile' | 'logout' | 'custom';
+	label?: string;
+	icon?: React.ReactNode;
+	href?: string;
+	onClick?: () => void;
+	danger?: boolean;
+}
+
+export interface UserMenuLabels {
+	settings: string;
+	profile: string;
+	logout: string;
+	userMenu: string;
+	emptyUser: string;
+}
+
+export interface UserMenuProps {
+	user?: UserMenuUserInfo | null;
+	items: UserMenuItemSpec[];
+	align?: 'left' | 'right';
+	className?: string;
+	nameClassName?: string;
+	menuClassName?: string;
+	labels?: Partial<UserMenuLabels>;
+}
+
+export function deriveUserInitials(user?: UserMenuUserInfo | null): string {
+	const source =
+		user?.displayName?.trim() || user?.username?.trim() || user?.email?.trim() || '';
+	return source ? source[0]!.toUpperCase() : 'U';
+}
+
+const ITEM_ICONS: Record<string, React.ComponentType<{ className?: string }>> = {
+	settings: Settings,
+	profile: UserRound,
+	logout: LogOut,
+};
+
+export function UserMenu({
+	user,
+	items,
+	align = 'right',
+	className = '',
+	nameClassName = '',
+	menuClassName = '',
+	labels,
+}: UserMenuProps) {
+	const { i18n } = useTranslation();
+	const isZh = (i18n.language || '').toLowerCase().startsWith('zh');
+	const defaults: UserMenuLabels = {
+		settings: isZh ? '个人设置' : 'Settings',
+		profile: isZh ? '个人资料' : 'Profile',
+		logout: isZh ? '退出登录' : 'Log out',
+		userMenu: isZh ? '用户菜单' : 'User menu',
+		emptyUser: isZh ? '未登录' : 'Not signed in',
+	};
+	const text: UserMenuLabels = { ...defaults, ...labels };
+
+	const { open, setOpen, triggerRef, menuRef, triggerProps, menuProps } = useMenuButton();
+
+	const displayName =
+		user?.displayName?.trim() || user?.username?.trim() || user?.email?.trim() || text.emptyUser;
+	const initials = deriveUserInitials(user);
+	// 统一口径：退出登录恒在末位（APG/NN-g 惯例），其余保持调用方顺序
+	const ordered = [...items].sort(
+		(a, b) => Number(a.type === 'logout') - Number(b.type === 'logout'),
+	);
+
+	const activate = (item: UserMenuItemSpec) => {
+		setOpen(false);
+		item.onClick?.();
+	};
+
+	return (
+		<div className="relative">
+			<button
+				{...triggerProps}
+				ref={triggerRef}
+				aria-label={text.userMenu}
+				className={`flex items-center gap-2 rounded-md p-1.5 transition-colors hover:bg-[var(--color-bg-muted)] ${className}`}
+			>
+				{user?.avatarUrl ? (
+					<img src={user.avatarUrl} alt="" className="h-8 w-8 rounded-full object-cover" />
+				) : (
+					<span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-[var(--color-brand)] text-xs font-medium text-[var(--color-text-inverse)]">
+						{initials}
+					</span>
+				)}
+				<span
+					className={`max-w-[10rem] truncate text-sm text-[var(--color-text-primary)] ${nameClassName}`}
+				>
+					{displayName}
+				</span>
+				<ChevronDown className="h-4 w-4 shrink-0 text-[var(--color-text-muted)]" />
+			</button>
+			{open && (
+				<div
+					{...menuProps}
+					ref={menuRef}
+					className={`absolute top-full z-50 mt-2 w-56 rounded-lg border border-[var(--color-border-subtle)] bg-[var(--color-bg-elevated)] py-1 shadow-lg ${
+						align === 'left' ? 'left-0' : 'right-0'
+					} ${menuClassName}`}
+				>
+					<div className="border-b border-[var(--color-border-subtle)] px-3 py-2">
+						<div className="truncate text-sm font-medium text-[var(--color-text-primary)]">
+							{displayName}
+						</div>
+						{user?.email && (
+							<div className="truncate text-xs text-[var(--color-text-muted)]">{user.email}</div>
+						)}
+					</div>
+					{ordered.map((item) => {
+						const Icon = ITEM_ICONS[item.type ?? ''] ?? null;
+						const danger = item.danger ?? item.type === 'logout';
+						const itemClass = `flex w-full items-center gap-2 px-3 py-2 text-left text-sm transition-colors ${
+							danger
+								? 'text-[var(--color-danger-text)] hover:bg-[var(--color-danger-soft)]'
+								: 'text-[var(--color-text-primary)] hover:bg-[var(--color-bg-muted)]'
+						}`;
+						const content = (
+							<>
+								{item.icon ?? (Icon ? <Icon className="h-4 w-4 shrink-0" /> : null)}
+								<span className="truncate">{item.label ?? text[item.type as keyof UserMenuLabels] ?? item.key}</span>
+							</>
+						);
+						return item.href ? (
+							<a
+								key={item.key}
+								role="menuitem"
+								tabIndex={-1}
+								href={item.href}
+								className={itemClass}
+								onClick={() => activate(item)}
+							>
+								{content}
+							</a>
+						) : (
+							<button
+								key={item.key}
+								role="menuitem"
+								tabIndex={-1}
+								type="button"
+								className={itemClass}
+								onClick={() => activate(item)}
+							>
+								{content}
+							</button>
+						);
+					})}
+				</div>
+			)}
+		</div>
+	);
+}

package/src/molecules/index.ts

@@ -0,0 +1,31 @@
+export { PageHeader } from './PageHeader';
+export { EmptyState } from './EmptyState';
+export { SectionCard } from './SectionCard';
+export { CodeBlock } from './CodeBlock';
+export { ConfirmDialog } from './ConfirmDialog';
+export { ToastProvider, useToast, showToast } from './Toast';
+export { LoadingScreen } from './LoadingScreen';
+export { ErrorState } from './ErrorState';
+export { Modal } from './Modal';
+export { ThemeToggle } from './ThemeToggle';
+export { LanguageSwitcher } from './LanguageSwitcher';
+export { UserMenu, deriveUserInitials } from './UserMenu';
+export type { UserMenuProps, UserMenuUserInfo, UserMenuItemSpec, UserMenuLabels } from './UserMenu';
+export { PortalSwitcher } from './PortalSwitcher';
+export type { PortalSwitcherProps, PortalSwitcherLabels, PortalLink } from './PortalSwitcher';
+export type { ToastType } from './Toast';
+export type { LoadingScreenProps } from './LoadingScreen';
+export type { ErrorStateProps } from './ErrorState';
+export { ErrorBoundary } from './ErrorBoundary';
+export { FormField, useFormFieldA11y } from './FormField';
+export type { FormFieldProps } from './FormField';
+export { PageContainer } from './PageContainer';
+export type { PageContainerProps } from './PageContainer';
+export { AppShell } from './AppShell';
+export type { AppShellProps } from './AppShell';
+export { ConsolePageHeader } from './ConsolePageHeader';
+export type { ConsolePageHeaderProps } from './ConsolePageHeader';
+export { Alert } from './Alert';
+export type { AlertProps, AlertVariant } from './Alert';
+export { Result } from './Result';
+export type { ResultProps, ResultSurface } from './Result';

package/src/rhf/FormInput.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import type { FieldValues } from 'react-hook-form';
+import { FormField } from '../molecules/FormField';
+import { fieldControlClass, fieldControlHeight } from '../internal/field-styles';
+import { ControlSlot, useBoundField, type FormControlBaseProps } from './shared';
+
+export interface FormInputProps<T extends FieldValues>
+	extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'name' | 'defaultValue' | 'className' | 'prefix'>,
+		FormControlBaseProps<T> {
+	/**
+	 * 控件内部的**前置装饰**（如金额框里的 ¥）。装饰是展示，不进表单值。
+	 *
+	 * 为什么收进 API 而不是让调用方自己拼：装饰必须贴在**输入框**上。
+	 * 调用方若把装饰塞进 FormField 的控件槽，那一块的高度是整个控件块（含标签），
+	 * `top-1/2` 会算到标签上，装饰就浮到输入框上沿去了 —— 实测两个页面都踩到，
+	 * 于是各自复制了一份「把装饰和控件放进同一个定位块」的胶水代码。
+	 */
+	leading?: React.ReactNode;
+	/** 控件内部的**后置装饰**（如显示/隐藏密码的按钮，可点，不是装饰而是控件）。 */
+	trailing?: React.ReactNode;
+}
+
+/** 文本输入（绑定 react-hook-form）。 */
+export function FormInput<T extends FieldValues>({
+	name,
+	control,
+	rules,
+	error: errorOverride,
+	label,
+	hint,
+	required,
+	leading,
+	trailing,
+	className = '',
+	...rest
+}: FormInputProps<T>) {
+	const { field, error } = useBoundField(name, control, rules, errorOverride);
+	// 装饰占位：设计系统固定给前置 2rem / 后置 2.5rem。需要别的宽度时用 FormField + ControlSlot
+	// （同一个入口里导出的逃生口），而不是在这里加一个宽度 prop —— 那会长成配置表。
+	const padding = [leading ? 'pl-8' : '', trailing ? 'pr-10' : ''].filter(Boolean).join(' ');
+	return (
+		<FormField label={label} hint={hint} error={error} required={required}>
+			<ControlSlot
+				render={(a11y) => (
+					<div className={leading || trailing ? 'relative' : undefined}>
+						{leading && (
+							<span className="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-sm text-[var(--color-text-secondary)]">
+								{leading}
+							</span>
+						)}
+						<input
+							{...rest}
+							{...field}
+							id={a11y.id}
+							aria-invalid={a11y.invalid || undefined}
+							aria-describedby={a11y.describedBy}
+							className={fieldControlClass(a11y.invalid, [fieldControlHeight, padding, className].filter(Boolean).join(' '))}
+						/>
+						{trailing && (
+							<span className="absolute right-2 top-1/2 -translate-y-1/2 flex items-center">{trailing}</span>
+						)}
+					</div>
+				)}
+			/>
+		</FormField>
+	);
+}

package/src/rhf/FormSelect.tsx

@@ -0,0 +1,43 @@
+import * as React from 'react';
+import type { FieldValues } from 'react-hook-form';
+import { FormField } from '../molecules/FormField';
+import { fieldControlClass, fieldControlHeight } from '../internal/field-styles';
+import { ControlSlot, useBoundField, type FormControlBaseProps } from './shared';
+
+export interface FormSelectProps<T extends FieldValues>
+	extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'name' | 'defaultValue' | 'className'>,
+		FormControlBaseProps<T> {}
+
+/** 下拉选择（绑定 react-hook-form，原生 select + 设计系统的控件外观）。 */
+export function FormSelect<T extends FieldValues>({
+	name,
+	control,
+	rules,
+	error: errorOverride,
+	label,
+	hint,
+	required,
+	className = '',
+	children,
+	...rest
+}: FormSelectProps<T>) {
+	const { field, error } = useBoundField(name, control, rules, errorOverride);
+	return (
+		<FormField label={label} hint={hint} error={error} required={required}>
+			<ControlSlot
+				render={(a11y) => (
+					<select
+						{...rest}
+						{...field}
+						id={a11y.id}
+						aria-invalid={a11y.invalid || undefined}
+						aria-describedby={a11y.describedBy}
+						className={fieldControlClass(a11y.invalid, fieldControlHeight + ' ' + className)}
+					>
+						{children}
+					</select>
+				)}
+			/>
+		</FormField>
+	);
+}

package/src/rhf/FormTextarea.tsx

@@ -0,0 +1,42 @@
+import * as React from 'react';
+import type { FieldValues } from 'react-hook-form';
+import { FormField } from '../molecules/FormField';
+import { fieldControlClass } from '../internal/field-styles';
+import { ControlSlot, useBoundField, type FormControlBaseProps } from './shared';
+
+export interface FormTextareaProps<T extends FieldValues>
+	extends Omit<React.TextareaHTMLAttributes<HTMLTextAreaElement>, 'name' | 'defaultValue' | 'className'>,
+		FormControlBaseProps<T> {}
+
+/** 多行文本（绑定 react-hook-form）。与单行控件的差别只有高度：不锁 h-10。 */
+export function FormTextarea<T extends FieldValues>({
+	name,
+	control,
+	rules,
+	error: errorOverride,
+	label,
+	hint,
+	required,
+	className = '',
+	rows = 3,
+	...rest
+}: FormTextareaProps<T>) {
+	const { field, error } = useBoundField(name, control, rules, errorOverride);
+	return (
+		<FormField label={label} hint={hint} error={error} required={required}>
+			<ControlSlot
+				render={(a11y) => (
+					<textarea
+						{...rest}
+						{...field}
+						rows={rows}
+						id={a11y.id}
+						aria-invalid={a11y.invalid || undefined}
+						aria-describedby={a11y.describedBy}
+						className={fieldControlClass(a11y.invalid, className)}
+					/>
+				)}
+			/>
+		</FormField>
+	);
+}

package/src/rhf/index.ts

@@ -0,0 +1,18 @@
+// react-hook-form 绑定入口 —— 与默认入口分离。
+//
+// 为什么单独一个子路径（与 ./antd 同一个理由）：根入口的消费方里有不吃 react-hook-form 的
+// （5 个 Astro 站、营销站），把绑定控件并进根入口等于让所有人替一个他们不用的库付包体积。
+// 所以 react-hook-form 是 **optional peerDependency**，且默认入口 0 处 import 它（第 19 道闸门断言）。
+
+export { FormInput } from './FormInput';
+export type { FormInputProps } from './FormInput';
+export { FormSelect } from './FormSelect';
+export type { FormSelectProps } from './FormSelect';
+export { FormTextarea } from './FormTextarea';
+export type { FormTextareaProps } from './FormTextarea';
+export type { FormControlBaseProps } from './shared';
+// 自研控件（或需要自定义装饰/布局的字段）要接同一套 a11y 接线时用这两个：
+// 实测两个页面为了「装饰贴着输入框」各自复制了一份 ControlSlot —— 导出它正是为了让这种复制没有理由发生。
+export { useBoundField, ControlSlot } from './shared';
+export { FormField, useFormFieldA11y } from '../molecules/FormField';
+export type { FormFieldProps } from '../molecules/FormField';

package/src/rhf/shared.tsx

@@ -0,0 +1,63 @@
+'use client';
+
+// @autional/ui/rhf 的绑定控件：把 react-hook-form 的 useController 也包掉，
+// 于是调用点只剩「字段名 + 标签 + 输入属性」，标签/错误/aria 接线一律由设计系统给。
+//
+// 为什么值得包：整个舰队有 50 处 react-hook-form 的 register( 调用点（user 10 / auth 34 / status 4 / trust 2），
+// 每一处都在自己决定标签怎么写、错误显示成什么样、读屏器能不能念到那条错误。
+//
+// 为什么是**可选** peer：绑定控件在 ./rhf 子路径入口，不进默认入口 ——
+// 不吃 react-hook-form 的站点（5 个 Astro 站、营销站）不会因为它多装一个包。
+
+import * as React from 'react';
+import { useController } from 'react-hook-form';
+import type { Control, FieldValues, Path, UseControllerProps } from 'react-hook-form';
+import { useFormFieldA11y } from '../molecules/FormField';
+
+/** 绑定控件共有的 props。泛型 T 是表单值的类型，name 因此能校验到真实字段。 */
+export interface FormControlBaseProps<T extends FieldValues> {
+	name: Path<T>;
+	/** 表单控制对象。给了就用它，不给则从最近的 FormProvider 上下文取。 */
+	control?: Control<T>;
+	label?: string;
+	hint?: string;
+	required?: boolean;
+	/**
+	 * 字段级校验规则（透传给 react-hook-form）。
+	 *
+	 * 站点的 schema 校验走 zodResolver，用不到它；但**没有它，需要单字段规则的地方就只能退回 register()** ——
+	 * 那正是这个入口想消灭的写法。所以照 RHF 的原义透传，而不是自创一套。
+	 */
+	rules?: UseControllerProps<T>['rules'];
+	/**
+	 * 覆盖错误文案。不给就用表单库给的那条。
+	 *
+	 * 为什么需要这个口子：本项目的 zod message 是 **i18n 键**（如 `mustMatch`），不是给人看的文案，
+	 * 而页面今天按字段给的是自己的键（如 `security.deleteAccount.passwordRequired`）。
+	 * 没有覆盖口子，接入绑定控件就会**悄悄换掉用户看到的报错文案** —— 那是收敛不该付的代价。
+	 * 校验仍然归表单库，这里只决定「显示哪句话」。
+	 */
+	error?: string;
+	className?: string;
+}
+
+/** 把 FormField 生成的 id / aria-invalid / aria-describedby 接到真实控件上。 */
+export function ControlSlot({
+	render,
+}: {
+	render: (a11y: { id: string; invalid: boolean; describedBy?: string }) => React.ReactNode;
+}) {
+	const a11y = useFormFieldA11y();
+	// FormField 一定会提供上下文；这里的兜底只为类型收敛，不改变行为。
+	return <>{render(a11y ?? { id: '', invalid: false, describedBy: undefined })}</>;
+}
+
+export function useBoundField<T extends FieldValues>(
+	name: Path<T>,
+	control: Control<T> | undefined,
+	rules: UseControllerProps<T>['rules'],
+	override?: string,
+) {
+	const { field, fieldState } = useController({ name, control, rules });
+	return { field, error: override ?? fieldState.error?.message };
+}

package/src/styles/globals.css

@@ -0,0 +1,19 @@
+/* 令牌由各站点 <head> 里的 CDN <link> 提供（单一来源）。
+   这份 CSS 被 packages/ui/src/index.ts 引入，若在这里再 @import 一份，
+   令牌就会有两个来源（CDN + bundle），CDN 侧改动本地看不出来。 */
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  html {
+    font-family: var(--font-sans);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+  body {
+    background-color: var(--color-bg-primary);
+    color: var(--color-text-primary);
+  }
+}

package/src/test-setup.ts

@@ -0,0 +1,37 @@
+// 测试环境的 jsdom 缺口 —— **由设计系统统一补这一份**。
+//
+// 为什么放在这里而不是各站各写一遍：实测三个控制台各自抄了一份 matchMedia + ResizeObserver，
+// 而 user 只有 matchMedia。于是 user 接入 antd 的那一天，8 个既有用例一起红在
+// 「ResizeObserver is not defined」——错误信息完全指不到「这是 jsdom 的缺口」。
+// 抄了四份的东西必然有一份漏掉，这是「拷贝而非依赖」的教科书案例。
+//
+// 用法（站点 vitest 配置的 setupFiles 里）：
+//   import '@testing-library/jest-dom/vitest';
+//   import '@autional/ui/test-setup';
+//
+// 这不是「为了让测试过而 mock」：matchMedia 与 ResizeObserver 是真实浏览器里就有的 API，
+// jsdom 只是没实现。不补的后果实测过：antd 组件会在 rc-component 的 useLayoutEffect 里抛错，
+// 报错落在与真正原因完全无关的位置。
+
+if (typeof window !== 'undefined' && !window.matchMedia) {
+	window.matchMedia = ((query: string) => ({
+		matches: false,
+		media: query,
+		onchange: null,
+		addListener: () => {},
+		removeListener: () => {},
+		addEventListener: () => {},
+		removeEventListener: () => {},
+		dispatchEvent: () => false,
+	})) as unknown as typeof window.matchMedia;
+}
+
+if (typeof globalThis !== 'undefined' && !(globalThis as { ResizeObserver?: unknown }).ResizeObserver) {
+	(globalThis as { ResizeObserver?: unknown }).ResizeObserver = class {
+		observe() {}
+		unobserve() {}
+		disconnect() {}
+	};
+}
+
+export {};

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.