huibo-ui 0.3.0

package/dist/types/utils/a11y.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 无障碍（a11y）工具集
+ * 统一 ARIA 属性辅助、焦点陷阱、列表键盘导航等在交互组件（Dialog / Drawer / Menu /
+ * Dropdown / Select 等）中重复出现且容易写错的可访问性逻辑。
+ *
+ * 参考标准：WAI-ARIA Authoring Practices 1.2。
+ */
+/** 判定按键是否为「激活」键（Enter / Space），用于自定义可聚焦元素的点击替代 */
+export declare function isActivationKey(key: string | undefined): boolean;
+export declare function getFocusableElements(container: HTMLElement): HTMLElement[];
+/** 焦点陷阱选项 */
+export interface FocusTrapOptions {
+    /** 焦点受限的容器元素 */
+    container: HTMLElement;
+    /** 打开时是否自动聚焦容器内首个可聚焦元素 */
+    autoFocus?: boolean;
+    /** 容器激活前的元素（用于关闭时归还焦点） */
+    returnFocusTo?: HTMLElement | null;
+}
+/** 焦点陷阱句柄 */
+export interface FocusTrap {
+    /** 启用：绑定 Tab 拦截，可选自动聚焦 */
+    connect: () => void;
+    /** 关闭：解除拦截，归还焦点 */
+    disconnect: () => void;
+}
+/**
+ * 创建焦点陷阱（Dialog / Drawer 打开时把 Tab 循环限制在容器内）。
+ * 关键点：Tab 与 Shift+Tab 在容器边界时回环到另一端，防止焦点逃逸到背景。
+ * 返回句柄，组件在打开时 connect()、关闭时 disconnect()。
+ */
+export declare function createFocusTrap(options: FocusTrapOptions): FocusTrap;
+/** 列表键盘导航产生的动作 */
+export type ListKeyAction = {
+    type: 'navigate';
+    index: number;
+} | {
+    type: 'select';
+    index: number;
+} | {
+    type: 'close';
+} | {
+    type: 'none';
+};
+/** 列表键盘导航参数 */
+export interface ListKeyboardOptions {
+    /** 当前高亮项索引（-1 表示无高亮） */
+    activeIndex: number;
+    /** 列表项总数 */
+    itemCount: number;
+    /** 是否允许循环（首尾跳转） */
+    loop?: boolean;
+}
+/**
+ * 列表 / 菜单 / 下拉选项的键盘导航核心逻辑（listbox / menu / combobox 通用）。
+ * 返回应执行的动作，由调用方据此更新 activeIndex / 触发选中 / 关闭。
+ *
+ * 支持：ArrowDown/ArrowUp（竖排）/ArrowRight/ArrowLeft（横排）移动、Home/End 跳首尾、
+ * Enter/Space 选中、Escape 关闭。
+ */
+export declare function handleListKeyboard(event: KeyboardEvent, options: ListKeyboardOptions): ListKeyAction;
+/**
+ * 为元素批量设置 ARIA 属性（不可变：返回新映射，但直接操作 DOM 属性是 a11y 的固有需求）。
+ * 组件挂载后调用一次即可，避免每次 render 重复写 setAttribute。
+ */
+export declare function applyAria(el: HTMLElement, attrs: Record<string, string | boolean | undefined>): void;

package/dist/types/utils/click-outside.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 点击外部检测工具
+ * 统一管理 document click 事件监听，用于下拉/弹出组件的关闭逻辑
+ */
+export interface ClickOutsideOptions {
+    /** 需要检测的宿主元素 */
+    host: HTMLElement;
+    /** 当前是否打开状态（避免不必要的检查） */
+    isOpen: () => boolean;
+    /** 关闭回调 */
+    onClose: () => void;
+}
+/**
+ * 创建点击外部处理器
+ * 返回清理函数，用于在 disconnectedCallback 中移除监听
+ */
+export declare function createClickOutsideHandler(options: ClickOutsideOptions): {
+    connect: () => void;
+    disconnect: () => void;
+};

package/dist/types/utils/date-helpers.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 日历和日期工具函数
+ * 从 DatePicker / DateTimePicker / DatePickerPane 中提取的共享逻辑
+ */
+export interface CalendarDay {
+    date: Date;
+    isCurrentMonth: boolean;
+    isToday: boolean;
+    isSelected: boolean;
+}
+/** 判断两个日期是否为同一天 */
+export declare function isSameDay(date1: Date, date2: Date): boolean;
+/** 生成 42 天（6 周）的日历网格数据 */
+export declare function getCalendarDays(viewDate: Date, selectedDate?: Date, today?: Date): CalendarDay[];
+/**
+ * 格式化日期为指定格式字符串
+ * 支持：YYYY, MM, DD, HH, mm, ss
+ */
+export declare function formatDate(date: Date, format: string): string;
+/** 安全解析日期值 */
+export declare function parseDate(value: string | Date | undefined): Date | undefined;
+/** 月份偏移，返回新日期对象（不可变） */
+export declare function addMonths(date: Date, delta: number): Date;
+/** 年份偏移，返回新日期对象（不可变） */
+export declare function addYears(date: Date, delta: number): Date;
+/**
+ * 生成 years 视图的 12 年档数据（每档 12 年）。
+ * 以 viewDate 所在年份向下取整到 12 的倍数作为起点。
+ */
+export interface CalendarYear {
+    year: number;
+    isCurrentYearRange: boolean;
+    isSelected: boolean;
+}
+export declare function getCalendarYears(viewDate: Date, selectedDate?: Date, startYearBase?: number): CalendarYear[];
+/** 获取 years 视图标题所显示的年份档区间起点 */
+export declare function getYearRangeStart(viewDate: Date): number;
+/** 中文月份名称 */
+export declare const MONTH_NAMES: string[];
+/** 中文星期名称 */
+export declare const WEEK_DAY_NAMES: string[];

package/dist/types/utils/form-input-base.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 表单输入组件共享基础
+ * 统一 size / disabled / clearable / modelValue 这一组在 Input / Select / Cascader /
+ * DatePicker / InputNumber / TimePicker 等组件中重复出现的包装模式。
+ *
+ * 设计原则：纯函数 + 类型导出，不引入基类继承，避免 Stencil 装饰器在继承链上的隐式行为。
+ * 组件按需 import 对应工具，渲染时调用即可。
+ */
+/** 组件尺寸（与 Ant Design 对齐，便于迁移） */
+export type ComponentSize = 'large' | 'default' | 'small';
+/** 全部合法尺寸，用于运行期校验 */
+export declare const COMPONENT_SIZES: readonly ComponentSize[];
+/**
+ * 表单输入组件共享的 prop 契约。
+ * 跨框架消费方（React / Vue / 原生）可据此推断任一表单输入组件的通用能力，
+ * 各组件在此基础上扩展自身特有 prop。
+ */
+export interface FormInputProps {
+    /** 绑定值（双向，配合 hbChange 事件） */
+    modelValue: unknown;
+    /** 尺寸 */
+    size?: ComponentSize;
+    /** 是否禁用 */
+    disabled?: boolean;
+    /** 是否只读 */
+    readonly?: boolean;
+    /** 是否可清空 */
+    clearable?: boolean;
+    /** 占位文本 */
+    placeholder?: string;
+}
+/**
+ * 生成尺寸 class 名：buildSizeClass('hb-input', 'large') -> 'hb-input--large'
+ * 用于替代各组件 render 中重复的 `[`hb-input--${this.size}`]: true` 模板字面量。
+ */
+export declare function buildSizeClass(base: string, size: ComponentSize | undefined): string;
+/** 清空按钮可见性判定参数 */
+export interface ClearVisibleOptions {
+    /** 是否声明了 clearable */
+    clearable: boolean;
+    /** 是否禁用（禁用时不显示） */
+    disabled?: boolean;
+    /** 是否只读（只读时不显示） */
+    readonly?: boolean;
+    /** 当前是否有值（无值时不显示） */
+    hasValue: boolean;
+}
+/**
+ * 判定清空按钮是否应显示。
+ * 抽取自 Input/Select/Cascader 中重复的 `clearable && !disabled && !readonly && hasValue`。
+ */
+export declare function isClearVisible(options: ClearVisibleOptions): boolean;
+/**
+ * 判定一个值是否「非空」（用于清空按钮显隐）。
+ * 兼容字符串、数字、数组（多选）。
+ */
+export declare function hasInputValue(value: unknown): boolean;
+/**
+ * 尺寸 class 集合生成器：返回包含 base 与 size class 的对象，可直接展开进 JSX class 绑定。
+ * 例：sizeClassMap('hb-input', 'large', this.size) -> { 'hb-input': true, 'hb-input--large': true }
+ */
+export declare function sizeClassMap(base: string, size: ComponentSize | undefined): Record<string, boolean>;

package/dist/types/utils/popup-manager.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 弹出层管理工具
+ * 统一管理弹出层的 z-index、滚动锁定、Escape 关闭
+ */
+/** 获取下一个 z-index */
+export declare function getNextZIndex(): number;
+/** 锁定 body 滚动 */
+export declare function lockScroll(): void;
+/** 解锁 body 滚动 */
+export declare function unlockScroll(): void;
+/** 计算弹出层位置 */
+export interface PopupPosition {
+    top: number;
+    left: number;
+}
+export type Placement = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end';
+export declare function computePosition(triggerRect: DOMRect, popupWidth: number, popupHeight: number, placement?: Placement, gap?: number): PopupPosition;

package/loader/cdn.js

@@ -0,0 +1 @@
+module.exports = require('../dist/cjs/loader.cjs.js');

package/loader/index.cjs.js

@@ -0,0 +1 @@
+module.exports = require('../dist/cjs/loader.cjs.js');

package/loader/index.d.ts

@@ -0,0 +1,24 @@
+export * from '../dist/types/components';
+export interface CustomElementsDefineOptions {
+  exclude?: string[];
+  resourcesUrl?: string;
+  syncQueue?: boolean;
+  jmp?: (c: Function) => any;
+  raf?: (c: FrameRequestCallback) => number;
+  ael?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;
+  rel?: (el: EventTarget, eventName: string, listener: EventListenerOrEventListenerObject, options: boolean | AddEventListenerOptions) => void;
+}
+export declare function defineCustomElements(win?: Window, opts?: CustomElementsDefineOptions): void;
+/**
+ * @deprecated
+ */
+export declare function applyPolyfills(): Promise<void>;
+
+/**
+ * Used to specify a nonce value that corresponds with an application's CSP.
+ * When set, the nonce will be added to all dynamically created script and style tags at runtime.
+ * Alternatively, the nonce value can be set on a meta tag in the DOM head
+ * (<meta name="csp-nonce" content="{ nonce value here }" />) which
+ * will result in the same behavior.
+ */
+export declare function setNonce(nonce: string): void;

package/loader/index.es2017.js

@@ -0,0 +1 @@
+export * from '../dist/esm/loader.js';

package/loader/index.js

@@ -0,0 +1,2 @@
+(function(){if("undefined"!==typeof window&&void 0!==window.Reflect&&void 0!==window.customElements){var a=HTMLElement;window.HTMLElement=function(){return Reflect.construct(a,[],this.constructor)};HTMLElement.prototype=a.prototype;HTMLElement.prototype.constructor=HTMLElement;Object.setPrototypeOf(HTMLElement,a)}})();
+export * from '../dist/esm/loader.js';

package/loader/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "huibo-ui-loader",
+  "private": true,
+  "typings": "./index.d.ts",
+  "module": "./index.js",
+  "main": "./index.cjs.js",
+  "jsnext:main": "./index.es2017.js",
+  "es2015": "./index.es2017.js",
+  "es2017": "./index.es2017.js",
+  "unpkg": "./cdn.js"
+}

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "huibo-ui",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "Stencil Component Starter",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "collection": "dist/collection/collection-manifest.json",
+  "collection:main": "dist/collection/index.js",
+  "unpkg": "dist/huibo-ui/huibo-ui.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/huibo-ui/huibo-ui.esm.js",
+      "require": "./dist/huibo-ui/huibo-ui.cjs.js"
+    },
+    "./loader": {
+      "import": "./loader/index.js",
+      "require": "./loader/index.cjs",
+      "types": "./loader/index.d.ts"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    },
+    "./components/*": {
+      "types": "./dist/components/*.d.ts",
+      "import": "./dist/components/*.js"
+    },
+    "./styles.css": "./dist/huibo-ui/huibo-ui.css"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stenciljs/component-starter.git"
+  },
+  "files": [
+    "dist/",
+    "loader/"
+  ],
+  "lint-staged": {
+    "*.{ts,tsx}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,md,json}": [
+      "prettier --write"
+    ]
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.12",
+    "@playwright/test": "^1.60.0",
+    "@stencil/core": "^4.27.1",
+    "@stencil/react-output-target": "^0.5.3",
+    "@tailwindcss/postcss": "^4.1.16",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.5",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.61.0",
+    "@typescript-eslint/parser": "^8.61.0",
+    "eslint": "^10.5.0",
+    "husky": "^9.1.7",
+    "jest": "^29.7.0",
+    "jest-cli": "^29.7.0",
+    "lint-staged": "^17.0.7",
+    "puppeteer": "^24.3.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "stencil-tailwind-plugin": "^2.0.5",
+    "tailwindcss": "^4.1.16",
+    "vitepress": "^1.6.4"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "stencil build && node patch-react-lib.js && node copy-docs.js",
+    "start": "stencil build --dev --watch --serve",
+    "prestart": "npm run build",
+    "test": "stencil test --spec --e2e",
+    "test.watch": "stencil test --spec --e2e --watchAll",
+    "generate": "stencil generate",
+    "copy-docs": "node copy-docs.js",
+    "lint": "eslint src/ --ext .ts,.tsx",
+    "lint:fix": "eslint src/ --ext .ts,.tsx --fix",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "smoke:cross-browser": "node scripts/cross-browser-smoke.mjs"
+  }
+}

package/readme.md

@@ -0,0 +1,111 @@
+[![Built With Stencil](https://img.shields.io/badge/-Built%20With%20Stencil-16161d.svg?logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDE5LjIuMSwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA1MTIgNTEyIiBzdHlsZT0iZW5hYmxlLWJhY2tncm91bmQ6bmV3IDAgMCA1MTIgNTEyOyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI%2BCjxzdHlsZSB0eXBlPSJ0ZXh0L2NzcyI%2BCgkuc3Qwe2ZpbGw6I0ZGRkZGRjt9Cjwvc3R5bGU%2BCjxwYXRoIGNsYXNzPSJzdDAiIGQ9Ik00MjQuNywzNzMuOWMwLDM3LjYtNTUuMSw2OC42LTkyLjcsNjguNkgxODAuNGMtMzcuOSwwLTkyLjctMzAuNy05Mi43LTY4LjZ2LTMuNmgzMzYuOVYzNzMuOXoiLz4KPHBhdGggY2xhc3M9InN0MCIgZD0iTTQyNC43LDI5Mi4xSDE4MC40Yy0zNy42LDAtOTIuNy0zMS05Mi43LTY4LjZ2LTMuNkgzMzJjMzcuNiwwLDkyLjcsMzEsOTIuNyw2OC42VjI5Mi4xeiIvPgo8cGF0aCBjbGFzcz0ic3QwIiBkPSJNNDI0LjcsMTQxLjdIODcuN3YtMy42YzAtMzcuNiw1NC44LTY4LjYsOTIuNy02OC42SDMzMmMzNy45LDAsOTIuNywzMC43LDkyLjcsNjguNlYxNDEuN3oiLz4KPC9zdmc%2BCg%3D%3D&colorA=16161d&style=flat-square)](https://stenciljs.com)
+
+# Stencil Component Starter
+
+> This is a starter project for building a standalone Web Components using Stencil.
+
+Stencil is a compiler for building fast web apps using Web Components.
+
+Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than runtime tool. Stencil takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run in any browser supporting the Custom Elements specification.
+
+Stencil components are just Web Components, so they work in any major framework or with no framework at all.
+
+## Getting Started
+
+To start building a new web component using Stencil, clone this repo to a new directory:
+
+```bash
+git clone https://github.com/stenciljs/component-starter.git my-component
+cd my-component
+git remote rm origin
+```
+
+and run:
+
+```bash
+npm install
+npm start
+```
+
+To build the component for production, run:
+
+```bash
+npm run build
+```
+
+To run the unit tests for the components, run:
+
+```bash
+npm test
+```
+
+Need help? Check out our docs [here](https://stenciljs.com/docs/my-first-component).
+
+## Naming Components
+
+When creating new component tags, we recommend _not_ using `stencil` in the component name (ex: `<stencil-datepicker>`). This is because the generated component has little to nothing to do with Stencil; it's just a web component!
+
+Instead, use a prefix that fits your company or any name for a group of related components. For example, all of the [Ionic-generated](https://ionicframework.com/) web components use the prefix `ion`.
+
+## Using this component
+
+There are two strategies we recommend for using web components built with Stencil.
+
+The first step for all two of these strategies is to [publish to NPM](https://docs.npmjs.com/getting-started/publishing-npm-packages).
+
+You can read more about these different approaches in the [Stencil docs](https://stenciljs.com/docs/publishing).
+
+### Lazy Loading
+
+If your Stencil project is built with the [`dist`](https://stenciljs.com/docs/distribution) output target, you can import a small bootstrap script that registers all components and allows you to load individual component scripts lazily.
+
+For example, given your Stencil project namespace is called `my-design-system`, to use `my-component` on any website, inject this into your HTML:
+
+```html
+<script type="module" src="https://unpkg.com/my-design-system"></script>
+<!--
+To avoid unpkg.com redirects to the actual file, you can also directly import:
+https://unpkg.com/foobar-design-system@0.0.1/dist/foobar-design-system/foobar-design-system.esm.js
+-->
+<my-component first="Stencil" middle="'Don't call me a framework'" last="JS"></my-component>
+```
+
+This will only load the necessary scripts needed to render `<my-component />`. Once more components of this package are used, they will automatically be loaded lazily.
+
+You can also import the script as part of your `node_modules` in your applications entry file:
+
+```tsx
+import 'foobar-design-system/dist/foobar-design-system/foobar-design-system.esm.js';
+```
+
+Check out this [Live Demo](https://stackblitz.com/edit/vitejs-vite-y6v26a?file=src%2Fmain.tsx).
+
+### Standalone
+
+If you are using a Stencil component library with `dist-custom-elements`, we recommend importing Stencil components individually in those files where they are needed.
+
+To export Stencil components as standalone components make sure you have the [`dist-custom-elements`](https://stenciljs.com/docs/custom-elements) output target defined in your `stencil.config.ts`.
+
+For example, given you'd like to use `<my-component />` as part of a React component, you can import the component directly via:
+
+```tsx
+import 'foobar-design-system/my-component';
+
+function App() {
+  return (
+    <>
+      <div>
+        <my-component
+          first="Stencil"
+          middle="'Don't call me a framework'"
+          last="JS"
+        ></my-component>
+      </div>
+    </>
+  );
+}
+
+export default App;
+```
+
+Check out this [Live Demo](https://stackblitz.com/edit/vitejs-vite-b6zuds?file=src%2FApp.tsx).