@geektech/one 0.0.1 → 0.1.0

package/README-zh.md

@@ -48,6 +48,129 @@ class App extends Component {
 createApp({ root: App }).mount();
 ```
 
+## 组件分类
+
+- 基础：`OneButton`、`OneInput`
+- 表单：`OneForm`、`OneFormItem`、`OneSelect`、`OneCheckbox`、
+  `OneCheckboxGroup`、`OneSwitch`
+- 导航：`OneTabs`、`OneBreadcrumb`、`OnePagination`
+- 数据展示：`OneCard`、`OneTag`、`OneBadge`、`OneEmpty`
+- 反馈与浮层：`OneAlert`、`OneMessage`、`OneDialog`、`OneTooltip`
+
+## 导航
+
+并列内容使用标签页，层级位置使用面包屑，大量同类记录使用分页。三个组件分别
+提供受控状态；涉及原生链接时也可以通过事件决定是否继续导航。
+
+```ts
+import {
+  OneBreadcrumb,
+  OnePagination,
+  OneTabs,
+  type OneBreadcrumbClickEvent,
+  type OnePaginationChangeEvent,
+  type OneTabsChangeEvent,
+} from '@geektech/one';
+
+const tabs = new OneTabs({
+  value: 'overview',
+  items: [
+    { value: 'overview', label: '概览' },
+    { value: 'security', label: '安全' },
+  ],
+  children: [
+    { tag: 'p', slot: 'overview', children: ['概览内容'] },
+    { tag: 'p', slot: 'security', children: ['安全内容'] },
+  ],
+});
+tabs.on('change', (payload) => {
+  const event = payload as OneTabsChangeEvent;
+  tabs.setProps({ value: event.value });
+});
+
+const breadcrumb = new OneBreadcrumb({
+  maxItems: 3,
+  separator: '/',
+  items: [
+    { label: '首页', href: '/' },
+    { label: '项目', href: '/projects' },
+    { label: '详情', current: true },
+  ],
+});
+breadcrumb.on('itemClick', (payload) => {
+  const event = payload as OneBreadcrumbClickEvent;
+  console.log(event.item, event.index);
+});
+
+const basicPagination = new OnePagination({ total: 95 });
+const pagination = new OnePagination({
+  total: 95,
+  page: 1,
+  pageSize: 10,
+  pageSizeOptions: [10, 20, 50],
+  showQuickJumper: true,
+});
+pagination.on('change', (payload) => {
+  const event = payload as OnePaginationChangeEvent;
+  pagination.setProps({ page: event.page, pageSize: event.pageSize });
+});
+void basicPagination;
+```
+
+## 数据展示
+
+标签适合表达紧凑状态，徽标适合展示数量，无数据时使用空状态。`OneEmpty`
+支持通过 `actions` 插槽提供下一步操作。
+
+```ts
+import { OneBadge, OneButton, OneEmpty, OneTag } from '@geektech/one';
+
+new OneTag({ variant: 'success', closable: true });
+new OneBadge({ value: 120, max: 99 });
+const actions = [
+  {
+    component: OneButton,
+    slot: 'actions',
+    children: ['创建项目'],
+  },
+];
+new OneEmpty({ description: '暂无结果', children: actions });
+```
+
+## 反馈与浮层
+
+持续显示的页面内反馈使用 `OneAlert`，附着到单个触发元素的简短说明使用
+`OneTooltip`：
+
+```ts
+import { OneAlert, OneButton, OneTooltip } from '@geektech/one';
+
+const alert = new OneAlert({
+  title: '保存成功',
+  variant: 'success',
+  closable: true,
+});
+
+const tooltip = new OneTooltip({
+  content: '复制链接',
+  placement: 'bottom-end',
+  children: [{ component: OneButton, children: ['复制'] }],
+});
+```
+
+临时消息和确认流程可以使用命令式服务：
+
+```ts
+import { oneDialog, oneMessage } from '@geektech/one';
+
+oneMessage.success('Saved');
+
+const confirmed = await oneDialog.confirm({
+  title: 'Delete item?',
+  description: 'This action cannot be undone.',
+});
+```
+
 ## 按钮变体、尺寸、加载状态和事件
 
 `OneButton` 提供 `primary`、`secondary`、`danger` 三种变体，以及 `sm`、
@@ -104,16 +227,45 @@ slot 的子节点进入默认内容区。
 
 ```ts
 import { createComponent } from '@geektech/tsone';
-import { OneCard } from '@geektech/one';
+import { OneButton, OneCard } from '@geektech/one';
 
 const card = createComponent(OneCard, {}, [
   { tag: 'h2', slot: 'header', children: ['账户'] },
   { tag: 'p', children: ['默认插槽内容'] },
-  { tag: 'button', slot: 'footer', children: ['继续'] },
+  { component: OneButton, slot: 'footer', children: ['继续'] },
 ]);
 ```
 
-## 主题覆盖
+## 全局主题
+
+不可变的内置 `default` 主题始终可用。可以注册任意多套局部配置；未填写的颜色、
+字体、行高、边框和圆角字段都会从 `ONE_DEFAULT_THEME` 继承。
+
+```ts
+import { ONE_DEFAULT_THEME, oneTheme } from '@geektech/one';
+
+oneTheme.init({
+  defaultTheme: 'brand',
+  themes: {
+    brand: {
+      colors: { primary: '#326bff' },
+      typography: { fontFamily: 'Inter, sans-serif', lineHeight: '1.6' },
+      border: { color: '#cbd5e1', width: '1px', style: 'solid' },
+      radius: { sm: '4px', md: '8px', lg: '12px' },
+    },
+    night: { colors: { surface: '#101510', text: '#f4f8f4' } },
+  },
+});
+
+oneTheme.switch('default');
+console.log(oneTheme.currentTheme, ONE_DEFAULT_THEME.colors.primary);
+```
+
+主题服务只写入 `document.documentElement`，不创建局部主题，也不会自动持久化选中
+名称或跟随系统配色。无效配置会抛出 `OneThemeConfigError`，未知主题名称会抛出
+`OneThemeNotFoundError`。
+
+## CSS 变量覆盖
 
 One UI 样式限定在 `.one-*` 选择器中。可以在应用容器或 `:root` 上覆盖公开
 CSS 变量：

package/README.md

@@ -48,6 +48,130 @@ class App extends Component {
 createApp({ root: App }).mount();
 ```
 
+## Component categories
+
+- Basic: `OneButton`, `OneInput`
+- Form: `OneForm`, `OneFormItem`, `OneSelect`, `OneCheckbox`,
+  `OneCheckboxGroup`, `OneSwitch`
+- Navigation: `OneTabs`, `OneBreadcrumb`, `OnePagination`
+- Data display: `OneCard`, `OneTag`, `OneBadge`, `OneEmpty`
+- Feedback and overlays: `OneAlert`, `OneMessage`, `OneDialog`, `OneTooltip`
+
+## Navigation
+
+Use tabs for parallel views, breadcrumbs for a hierarchy, and pagination for a
+long collection. All three components support controlled state or cancellable
+events where native navigation is involved.
+
+```ts
+import {
+  OneBreadcrumb,
+  OnePagination,
+  OneTabs,
+  type OneBreadcrumbClickEvent,
+  type OnePaginationChangeEvent,
+  type OneTabsChangeEvent,
+} from '@geektech/one';
+
+const tabs = new OneTabs({
+  value: 'overview',
+  items: [
+    { value: 'overview', label: 'Overview' },
+    { value: 'security', label: 'Security' },
+  ],
+  children: [
+    { tag: 'p', slot: 'overview', children: ['Overview content'] },
+    { tag: 'p', slot: 'security', children: ['Security content'] },
+  ],
+});
+tabs.on('change', (payload) => {
+  const event = payload as OneTabsChangeEvent;
+  tabs.setProps({ value: event.value });
+});
+
+const breadcrumb = new OneBreadcrumb({
+  maxItems: 3,
+  separator: '/',
+  items: [
+    { label: 'Home', href: '/' },
+    { label: 'Projects', href: '/projects' },
+    { label: 'Details', current: true },
+  ],
+});
+breadcrumb.on('itemClick', (payload) => {
+  const event = payload as OneBreadcrumbClickEvent;
+  console.log(event.item, event.index);
+});
+
+const basicPagination = new OnePagination({ total: 95 });
+const pagination = new OnePagination({
+  total: 95,
+  page: 1,
+  pageSize: 10,
+  pageSizeOptions: [10, 20, 50],
+  showQuickJumper: true,
+});
+pagination.on('change', (payload) => {
+  const event = payload as OnePaginationChangeEvent;
+  pagination.setProps({ page: event.page, pageSize: event.pageSize });
+});
+void basicPagination;
+```
+
+## Data display
+
+Use tags for compact status, badges for counts, and empty states when a view has
+no content. `OneEmpty` accepts an `actions` slot for the next useful action.
+
+```ts
+import { OneBadge, OneButton, OneEmpty, OneTag } from '@geektech/one';
+
+new OneTag({ variant: 'success', closable: true });
+new OneBadge({ value: 120, max: 99 });
+const actions = [
+  {
+    component: OneButton,
+    slot: 'actions',
+    children: ['Create project'],
+  },
+];
+new OneEmpty({ description: 'No results', children: actions });
+```
+
+## Feedback and overlays
+
+Use `OneAlert` for persistent inline feedback and `OneTooltip` for a short
+description attached to one trigger element:
+
+```ts
+import { OneAlert, OneButton, OneTooltip } from '@geektech/one';
+
+const alert = new OneAlert({
+  title: 'Saved',
+  variant: 'success',
+  closable: true,
+});
+
+const tooltip = new OneTooltip({
+  content: 'Copy link',
+  placement: 'bottom-end',
+  children: [{ component: OneButton, children: ['Copy'] }],
+});
+```
+
+Use the imperative services for transient messages and confirmation flows:
+
+```ts
+import { oneDialog, oneMessage } from '@geektech/one';
+
+oneMessage.success('Saved');
+
+const confirmed = await oneDialog.confirm({
+  title: 'Delete item?',
+  description: 'This action cannot be undone.',
+});
+```
+
 ## Button variants, sizes, loading and events
 
 `OneButton` supports `primary`, `secondary`, and `danger` variants and `sm`,
@@ -104,16 +228,47 @@ children without a slot fill the default body.
 
 ```ts
 import { createComponent } from '@geektech/tsone';
-import { OneCard } from '@geektech/one';
+import { OneButton, OneCard } from '@geektech/one';
 
 const card = createComponent(OneCard, {}, [
   { tag: 'h2', slot: 'header', children: ['Account'] },
   { tag: 'p', children: ['Default slot content'] },
-  { tag: 'button', slot: 'footer', children: ['Continue'] },
+  { component: OneButton, slot: 'footer', children: ['Continue'] },
 ]);
 ```
 
-## Theme overrides
+## Global themes
+
+The immutable `default` theme is always available. Register any number of
+partial themes; omitted colors, typography, border, and radius values inherit
+from `ONE_DEFAULT_THEME`.
+
+```ts
+import { ONE_DEFAULT_THEME, oneTheme } from '@geektech/one';
+
+oneTheme.init({
+  defaultTheme: 'brand',
+  themes: {
+    brand: {
+      colors: { primary: '#326bff' },
+      typography: { fontFamily: 'Inter, sans-serif', lineHeight: '1.6' },
+      border: { color: '#cbd5e1', width: '1px', style: 'solid' },
+      radius: { sm: '4px', md: '8px', lg: '12px' },
+    },
+    night: { colors: { surface: '#101510', text: '#f4f8f4' } },
+  },
+});
+
+oneTheme.switch('default');
+console.log(oneTheme.currentTheme, ONE_DEFAULT_THEME.colors.primary);
+```
+
+The service writes to `document.documentElement` only. It does not create local
+themes, persist the selected name, or follow the operating-system scheme.
+Invalid configuration throws `OneThemeConfigError`; unknown theme names throw
+`OneThemeNotFoundError`.
+
+## CSS variable overrides
 
 One UI styles are scoped to `.one-*` selectors. Override public CSS variables
 on an application container or `:root`:

package/dist/alert/OneAlert.d.ts

@@ -0,0 +1,21 @@
+import { Component, type VNode } from '@geektech/tsone';
+import type { OneFeedbackVariant } from '../overlay';
+import { type OneNamedStyle } from '../styles/shared';
+export interface OneAlertProps {
+    title?: string;
+    description?: string;
+    variant?: OneFeedbackVariant;
+    closable?: boolean;
+    children?: Array<VNode | string>;
+}
+interface OneAlertState {
+    visible: boolean;
+}
+export declare const ONE_ALERT_STYLES: OneNamedStyle[];
+export declare class OneAlert extends Component<OneAlertProps, OneAlertState> {
+    protected initState(): OneAlertState;
+    protected initStyles(): void;
+    protected render(): VNode;
+    private close;
+}
+export {};

package/dist/alert/index.d.ts

@@ -0,0 +1,2 @@
+export { OneAlert, ONE_ALERT_STYLES } from './OneAlert';
+export type { OneAlertProps } from './OneAlert';

package/dist/badge/OneBadge.d.ts

@@ -0,0 +1,18 @@
+import { Component, type VNode } from '@geektech/tsone';
+import { type OneDataDisplayVariant } from '../data-display';
+import { type OneNamedStyle } from '../styles/shared';
+export interface OneBadgeProps {
+    value?: number | string;
+    max?: number;
+    dot?: boolean;
+    showZero?: boolean;
+    variant?: OneDataDisplayVariant;
+    ariaLabel?: string;
+    children?: Array<VNode | string>;
+}
+export declare const ONE_BADGE_STYLES: OneNamedStyle[];
+export declare class OneBadge extends Component<OneBadgeProps> {
+    protected initState(): object;
+    protected initStyles(): void;
+    protected render(): VNode;
+}

package/dist/badge/index.d.ts

@@ -0,0 +1,2 @@
+export { OneBadge } from './OneBadge';
+export type { OneBadgeProps } from './OneBadge';

package/dist/breadcrumb/OneBreadcrumb.d.ts

@@ -0,0 +1,38 @@
+import { Component, type VNode } from '@geektech/tsone';
+import { type OneNamedStyle } from '../styles/shared';
+export interface OneBreadcrumbItem {
+    label: string;
+    href?: string;
+    current?: boolean;
+}
+export interface OneBreadcrumbClickEvent {
+    item: OneBreadcrumbItem;
+    index: number;
+    originalEvent: MouseEvent;
+}
+export interface OneBreadcrumbProps {
+    items: readonly OneBreadcrumbItem[];
+    separator?: string;
+    maxItems?: number;
+    ariaLabel?: string;
+    children?: Array<VNode | string>;
+}
+interface OneBreadcrumbState {
+    expanded: boolean;
+}
+export declare const ONE_BREADCRUMB_STYLES: OneNamedStyle[];
+export declare class OneBreadcrumb extends Component<OneBreadcrumbProps, OneBreadcrumbState> {
+    protected initState(): OneBreadcrumbState;
+    protected initStyles(): void;
+    protected render(): VNode;
+    private normalizedItems;
+    private currentIndex;
+    private tokens;
+    private renderToken;
+    private renderItem;
+    private renderCollapse;
+    private renderSeparator;
+    private handleItemClick;
+    private hasSlot;
+}
+export {};

package/dist/breadcrumb/index.d.ts

@@ -0,0 +1 @@
+export { ONE_BREADCRUMB_STYLES, OneBreadcrumb, type OneBreadcrumbClickEvent, type OneBreadcrumbItem, type OneBreadcrumbProps, } from './OneBreadcrumb';

package/dist/categories.d.ts

@@ -1,4 +1,4 @@
-export type OneComponentCategory = 'basic' | 'form' | 'data-display' | 'feedback';
+export type OneComponentCategory = 'basic' | 'form' | 'navigation' | 'data-display' | 'feedback';
 export declare const ONE_COMPONENT_CATEGORIES: readonly [{
     readonly id: "basic";
     readonly label: "基础";
@@ -7,12 +7,16 @@ export declare const ONE_COMPONENT_CATEGORIES: readonly [{
     readonly id: "form";
     readonly label: "表单";
     readonly components: readonly ["OneForm", "OneFormItem", "OneSelect", "OneCheckbox", "OneCheckboxGroup", "OneSwitch"];
+}, {
+    readonly id: "navigation";
+    readonly label: "导航";
+    readonly components: readonly ["OneTabs", "OneBreadcrumb", "OnePagination"];
 }, {
     readonly id: "data-display";
     readonly label: "数据展示";
-    readonly components: readonly ["OneCard"];
+    readonly components: readonly ["OneCard", "OneTag", "OneBadge", "OneEmpty"];
 }, {
     readonly id: "feedback";
     readonly label: "反馈与浮层";
-    readonly components: readonly [];
+    readonly components: readonly ["OneAlert", "OneMessage", "OneDialog", "OneTooltip"];
 }];

package/dist/checkbox/OneCheckboxGroup.d.ts

@@ -1,5 +1,6 @@
 import { Component, type VNode } from '@geektech/tsone';
 import type { OneSelectOption } from '../select';
+import { type OneNamedStyle } from '../styles/shared';
 export interface OneCheckboxGroupProps {
     options: readonly OneSelectOption[];
     value?: string[];
@@ -13,6 +14,7 @@ interface OneCheckboxGroupState {
     internalValue: string[];
     revision: number;
 }
+export declare const ONE_CHECKBOX_GROUP_STYLES: OneNamedStyle[];
 export declare class OneCheckboxGroup extends Component<OneCheckboxGroupProps, OneCheckboxGroupState> {
     private fieldContext;
     private unsubscribe;

package/dist/data-display/index.d.ts

@@ -0,0 +1,2 @@
+export { normalizeOneDataDisplayVariant } from './types';
+export type { OneDataDisplayVariant } from './types';

package/dist/data-display/types.d.ts

@@ -0,0 +1,2 @@
+export type OneDataDisplayVariant = 'neutral' | 'primary' | 'success' | 'warning' | 'error';
+export declare function normalizeOneDataDisplayVariant(value: unknown, fallback?: OneDataDisplayVariant): OneDataDisplayVariant;

package/dist/dialog/DialogOverlay.d.ts

@@ -0,0 +1,30 @@
+import { Component, type VNode } from '@geektech/tsone';
+import { type OneNamedStyle } from '../styles/shared';
+import type { OneDialogCloseReason, OneDialogProps } from './types';
+export interface DialogOverlayProps extends OneDialogProps {
+    id: string;
+    lockBody: boolean;
+    confirmText?: string;
+    cancelText?: string;
+    content?: VNode | string;
+    isTop(): boolean;
+    requestClose(reason: OneDialogCloseReason): void;
+}
+export declare const ONE_DIALOG_STYLES: OneNamedStyle[];
+interface DialogOverlayState {
+}
+export declare class DialogOverlay extends Component<DialogOverlayProps, DialogOverlayState> {
+    private readonly focusManager;
+    private releaseScrollLock;
+    private targetDocument;
+    mount(container: HTMLElement): void;
+    protected initState(): DialogOverlayState;
+    protected initStyles(): void;
+    protected onMounted(): void;
+    protected onUnmounted(): void;
+    protected render(): VNode;
+    private readonly handleEscape;
+    private requestClose;
+    private getPanel;
+}
+export {};

package/dist/dialog/OneDialog.d.ts

@@ -0,0 +1,20 @@
+import { Component, type VNode } from '@geektech/tsone';
+import type { OneDialogProps } from './types';
+interface OneDialogState {
+    internalOpen: boolean;
+}
+export declare class OneDialog extends Component<OneDialogProps, OneDialogState> {
+    private controller;
+    private lockBody;
+    private viewMounted;
+    protected initState(): OneDialogState;
+    protected initStyles(): void;
+    protected onMounted(): void;
+    protected beforeUpdate(): void;
+    protected beforeUnmount(): void;
+    protected render(): VNode;
+    private createOverlay;
+    private synchronizeOverlay;
+    private requestClose;
+}
+export {};

package/dist/dialog/focus-manager.d.ts

@@ -0,0 +1,10 @@
+export declare class OneDialogFocusManager {
+    private dialog;
+    private previousFocus;
+    private isTop;
+    private targetDocument;
+    activate(dialog: HTMLElement, isTop?: () => boolean): void;
+    deactivate(restoreFocus?: boolean): void;
+    private readonly handleKeydown;
+    private focusableElements;
+}

package/dist/dialog/index.d.ts

@@ -0,0 +1,7 @@
+export { DialogOverlay, ONE_DIALOG_STYLES } from './DialogOverlay';
+export { OneDialog } from './OneDialog';
+export { OneDialogService, createOneDialogService, oneDialog } from './service';
+export { OneDialogFocusManager } from './focus-manager';
+export { lockOneDialogBody, unlockOneDialogBody } from './scroll-lock';
+export type { OneDialogServiceOptions } from './service';
+export type { OneDialogCloseReason, OneDialogProps } from './types';

package/dist/dialog/scroll-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function lockOneDialogBody(targetDocument: Document): () => void;
+export declare function unlockOneDialogBody(targetDocument: Document): void;

package/dist/dialog/service.d.ts

@@ -0,0 +1,22 @@
+import type { VNode } from '@geektech/tsone';
+import { type OneOverlayHandle, type OneOverlayHost } from '../overlay';
+import type { OneDialogProps } from './types';
+export interface OneDialogServiceOptions extends Omit<OneDialogProps, 'open' | 'defaultOpen'> {
+    content?: VNode | string;
+    confirmText?: string;
+    cancelText?: string;
+    onConfirm?: () => boolean | void | Promise<boolean | void>;
+    onCancel?: () => void;
+    onError?: (error: unknown) => void;
+}
+export declare class OneDialogService {
+    private readonly suppliedHost?;
+    constructor(suppliedHost?: OneOverlayHost | undefined);
+    open(options: OneDialogServiceOptions): OneOverlayHandle<OneDialogServiceOptions>;
+    confirm(options: OneDialogServiceOptions): Promise<boolean>;
+    close(id: string): void;
+    closeAll(): void;
+    private openInternal;
+}
+export declare function createOneDialogService(host?: OneOverlayHost): OneDialogService;
+export declare const oneDialog: OneDialogService;

package/dist/dialog/types.d.ts

@@ -0,0 +1,14 @@
+import type { VNode } from '@geektech/tsone';
+import type { OneOverlayContainer } from '../overlay';
+export interface OneDialogProps {
+    open?: boolean;
+    defaultOpen?: boolean;
+    title?: string;
+    description?: string;
+    closeOnOverlay?: boolean;
+    closeOnEscape?: boolean;
+    confirmLoading?: boolean;
+    container?: OneOverlayContainer;
+    children?: Array<VNode | string>;
+}
+export type OneDialogCloseReason = 'confirm' | 'cancel' | 'overlay' | 'escape';

package/dist/empty/OneEmpty.d.ts

@@ -0,0 +1,12 @@
+import { Component, type VNode } from '@geektech/tsone';
+import { type OneNamedStyle } from '../styles/shared';
+export interface OneEmptyProps {
+    description?: string;
+    children?: Array<VNode | string>;
+}
+export declare const ONE_EMPTY_STYLES: OneNamedStyle[];
+export declare class OneEmpty extends Component<OneEmptyProps> {
+    protected initState(): object;
+    protected initStyles(): void;
+    protected render(): VNode;
+}

package/dist/empty/index.d.ts

@@ -0,0 +1,2 @@
+export { OneEmpty } from './OneEmpty';
+export type { OneEmptyProps } from './OneEmpty';

package/dist/form/OneForm.d.ts

@@ -1,5 +1,5 @@
 import { Component, type VNode } from '@geektech/tsone';
-import type { OneNamedStyle } from '../styles/shared';
+import { type OneNamedStyle } from '../styles/shared';
 import type { OneFormInitialValues, OneFormRules, OneFormValidationResult, OneFormValues } from './context';
 import { OneFormModel } from './model';
 export interface OneFormProps {

package/dist/form/OneFormItem.d.ts

@@ -1,5 +1,5 @@
 import { Component, type VNode } from '@geektech/tsone';
-import type { OneNamedStyle } from '../styles/shared';
+import { type OneNamedStyle } from '../styles/shared';
 export interface OneFormItemProps {
     name: string;
     label?: string;