clxx 3.0.1 → 3.0.4

package/AGENTS.md

@@ -1,3 +1,49 @@
-- 所有回答用中文
-- 任意修改都要检查是否创造了新的bug，如果有bug则修复
-- 一个文件只能有一个React组件
+# AGENTS.md
+
+本仓库是面向移动端 H5 的基础组件库 `clxx`（React 19 + TypeScript + @emotion/react），以下规则对所有 AI Agent 在本工程内的工作均有效。
+
+## 1. 沟通约定
+
+- 所有回复使用中文。
+- 不主动 push 到远程；除非用户显式要求，否则只做本地改动。
+- 任务执行完成后，需自检产物：不允许遗留报错（编译 / 类型 / Lint），除非用户主动要求保留。
+
+## 2. 项目结构
+
+- `src/`：组件库源码，按 PascalCase 目录组织，每个组件一个目录（如 `Toast/`、`MapLocationSelection/`）。
+  - 目录内常见文件：`index.tsx`（导出入口）、`style.ts`（emotion 样式）、子组件 `*.tsx`。
+  - `src/Effect/` 存放自定义 hooks，`src/utils/` 存放无 React 依赖的工具函数。
+  - 对外导出统一在 `src/index.ts` 维护。
+- `test/`：基于 Vite 的本地预览工程，**只用于演示与人工验证 `src/` 下的组件**，不得承载业务逻辑。
+  - 子目录使用 kebab-case（如 `map-location-selection/`），与 `src` 下的 PascalCase 目录一一对应。
+
+## 3. 代码规范
+
+- **一个文件只允许导出一个 React 组件**；同一文件内的辅助子组件必须拆分到独立文件。
+- 组件文件使用 `.tsx`，纯逻辑 / 类型 / 工具使用 `.ts`。
+- 样式优先使用 `@emotion/react`，写在同目录的 `style.ts` 中；避免引入新的 CSS-in-JS 方案。
+- 公共依赖：`react@^19`、`@emotion/react`、`dayjs`、`lodash`、`history`；新增第三方依赖前先确认是否已有等价能力。
+- TypeScript 严格类型：禁止用 `any` 屏蔽类型问题；导出的 props/类型放在组件文件顶部并显式 `export`。
+- 注释只解释「为什么」与不易看出的约束，禁止逐行翻译代码。
+
+## 4. Container 约束（强制）
+
+本库所有组件的 `rem` 自适应、最大宽度居中、CSS 变量 `--clxx-max-width` 等能力均由 `src/Container` 提供。
+
+- 任何使用本库的页面 / Demo / 测试入口，**必须把 `Container` 作为根组件**包裹其它组件，否则尺寸会失真。
+- 修改 `Container` 时需同时验证 `Overlay`、`Fixed`、弹窗类组件（`Dialog`、`Toast`、`Alert`、`Loading`、`*Picker` 等）在 PC 端居中与最大宽度限制下的表现。
+
+## 5. 测试与本地运行
+
+- `test/` 工程：`cd test && npm run dev` 启动本地预览。
+- 库本身：`npm run dev`（tsc watch）/ `npm run build`（清理后产出到 `build/`）。
+- 新增 / 修改组件时，应在 `test/src/<对应目录>/` 下补充或更新最小可运行 Demo。
+- 临时为调试创建、与正常逻辑无关的测试文件 / 代码，**任务完成前必须删除**。
+
+## 6. 质量门禁
+
+- 任何修改完成后，先自检：
+  1. 是否引入新 bug 或破坏既有用例；如有，**必须修复**。
+  2. 是否影响公共导出（`src/index.ts`）的兼容性。
+  3. 是否在 `Container` 之外破坏了自适应行为。
+- 涉及 `peerDependencies`（React/ReactDOM）相关 API 的改动，需确保仍兼容 React 19。

package/README.md

@@ -481,6 +481,7 @@ showCitySelect({
 | `onLetterChange` | `(letter: string) => void` | — | 侧边栏当前字母变化回调 |
 | `getLocation` | `() => string \| null \| undefined \| Promise<string \| null \| undefined>` | — | 外部定位能力，可同步或异步，返回城市名或城市 code |
 | `primary` | `string` | `'#2f7dff'` | 主题主色，形如 `#rrggbb`；active 态颜色自动派生 |
+| `taiwanHKMacau` | `boolean` | `false` | 是否包含香港/澳门/台湾；false 时在列表、搜索与定位结果中均不出现 |
 
 **SelectedCity：**
 
@@ -603,7 +604,8 @@ showRegionPicker({
 | `maskClosable` | `boolean` | `true` | 点击遮罩是否可关闭（仅 `showRegionPicker` 路径生效） |
 | `primary` | `string` | `'#2f7dff'` | 主题主色 |
 | `rounded` | `boolean` | `true` | 顶部圆角 |
-| `onConfirm` | `(selection: RegionSelection) => void` | — | 确认回调，仅在三级齐全时可点击 |
+| `taiwanHKMacau` | `boolean` | `false` | 是否包含香港/澳门/台湾；false 时这三个顶层省份不会出现在列表中 |
+| `onConfirm` | `(selection: RegionSelection) => void` | — | 确认回调；选中的市无区级时选到市即可提交 |
 | `onCancel` | `() => void` | — | 取消回调 |
 | `onClose` | `() => void` | — | 请求关闭（由外部处理动画与卸载） |
 
@@ -617,14 +619,15 @@ interface RegionNode {
 interface RegionSelection {
   province: RegionNode;
   city: RegionNode;
-  district: RegionNode;
+  // 部分城市无区级时为 null
+  district: RegionNode | null;
 }
 ```
 
 **特性：**
 - **tabs 联动**：选中后自动跳到下一级；切换上级会清空所有下级。
 - **滚动定位**：切 tab 时把当前选中项对齐到列表顶部（用 `getBoundingClientRect` 差分计算偏移，不依赖 offsetParent）。
-- **三级未齐时**：确认按钮置灰禁用，避免半选确认。
+- **选择未完成时**：确认按钮置灰禁用；选中的市无区级时，选到市使可提交。
 
 ---
 

package/build/Alert/style.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.style = void 0;
 const theme_1 = require("../utils/theme");
+const rem_1 = require("../utils/rem");
 // 1px 硬边框（高清屏 hairline）
 const hairline = 1 / (typeof window !== "undefined" ? window.devicePixelRatio : 1);
 // iOS 风色板
@@ -13,20 +14,20 @@ exports.style = {
         position: "relative",
         overflow: "hidden",
         backgroundColor: "#ffffff",
-        borderRadius: ".28rem",
-        width: (750 * 0.78) / 100 + "rem",
+        borderRadius: (0, rem_1.r)(28),
+        width: (0, rem_1.r)(750 * 0.78),
         fontFamily: theme_1.fontStack,
         color: textPrimary,
         WebkitFontSmoothing: "antialiased",
         MozOsxFontSmoothing: "grayscale",
-        boxShadow: "0 .2rem .6rem rgba(0,0,0,.18)",
+        boxShadow: `0 ${(0, rem_1.r)(20)} ${(0, rem_1.r)(60)} rgba(0,0,0,.18)`,
     },
     content: {
         position: "relative",
-        paddingTop: ".4rem",
-        paddingBottom: ".4rem",
-        paddingLeft: ".36rem",
-        paddingRight: ".36rem",
+        paddingTop: (0, rem_1.r)(40),
+        paddingBottom: (0, rem_1.r)(40),
+        paddingLeft: (0, rem_1.r)(36),
+        paddingRight: (0, rem_1.r)(36),
         "&:after,&::after": {
             content: "''",
             position: "absolute",
@@ -43,21 +44,21 @@ exports.style = {
         textAlign: "center",
         lineHeight: 1.45,
         color: textPrimary,
-        fontSize: ".34rem",
+        fontSize: (0, rem_1.r)(34),
         fontWeight: 600,
-        letterSpacing: ".01rem",
+        letterSpacing: (0, rem_1.r)(1),
     },
     desc: {
         textAlign: "center",
         lineHeight: 1.55,
         color: textSecondary,
-        fontSize: ".28rem",
-        marginTop: ".18rem",
+        fontSize: (0, rem_1.r)(28),
+        marginTop: (0, rem_1.r)(18),
         wordBreak: "break-word",
     },
     btnBox: {
         position: "relative",
-        height: ".92rem",
+        height: (0, rem_1.r)(92),
     },
     btnBoxWithCancel: {
         "&:after,&::after": {
@@ -79,9 +80,9 @@ exports.style = {
         alignItems: "center",
         justifyContent: "center",
         userSelect: "none",
-        fontSize: ".32rem",
+        fontSize: (0, rem_1.r)(32),
         fontWeight: 500,
-        letterSpacing: ".01rem",
+        letterSpacing: (0, rem_1.r)(1),
         cursor: "pointer",
         transition: "background-color .12s",
     },

package/build/CarouselNotice/style.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.style = exports.Bubble = void 0;
 const react_1 = require("@emotion/react");
+const rem_1 = require("../utils/rem");
 // translate 走百分比；fill-mode: forwards 保证动画结束后定格在 -50%，
 // 与 React 的 setState 提交顺序解耦，杜绝"动画结束帧"回弹到 0 造成的闪烁
 exports.Bubble = (0, react_1.keyframes) `
@@ -16,7 +17,7 @@ exports.style = {
     box: {
         position: "relative",
         overflow: "hidden",
-        height: ".8rem",
+        height: (0, rem_1.r)(80),
     },
     wrapper: {
         position: "absolute",

package/build/CitySelect/data.d.ts

@@ -1,3 +1,3 @@
-import type { ProvinceData, CityData } from './type';
+import type { ProvinceData, CityData } from "./type";
 export declare const provinceData: ProvinceData;
 export declare const cityData: CityData;