@geektech/one 0.0.1 → 0.2.0

package/README-zh.md

@@ -48,6 +48,168 @@ class App extends Component {
 createApp({ root: App }).mount();
 ```
 
+## 组件分类
+
+- 基础：`OneButton`
+- 表单：`OneForm`、`OneFormItem`、`OneInput`、`OneSelect`、`OneTimePicker`、
+  `OneCheckbox`、`OneCheckboxGroup`、`OneRadio`、`OneRadioGroup`、`OneSwitch`、
+  `OneSlider`、`OneRate`、`OneUpload`
+- 导航：`OneTabs`、`OneBreadcrumb`、`OnePagination`
+- 数据展示：`OneCard`、`OneTag`、`OneBadge`、`OneAvatar`、`OneProgress`、
+  `OneEmpty`、`OneTable`、`OneCollapse`、`OneSkeleton`
+- 反馈与浮层：`OneAlert`、`OneMessage`、`OneDialog`、`OneTooltip`、
+  `OneLoading`
+
+## 导航
+
+并列内容使用标签页，层级位置使用面包屑，大量同类记录使用分页。三个组件分别
+提供受控状态；涉及原生链接时也可以通过事件决定是否继续导航。
+
+```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 });
+```
+
+```ts
+import { OneAvatar, OneProgress } from '@geektech/one';
+
+new OneAvatar({ text: 'M', variant: 'primary' });
+new OneAvatar({ src: '/avatar.png', alt: '头像', shape: 'square' });
+new OneProgress({ percent: 65, showText: true });
+new OneProgress({ percent: 30, variant: 'success' });
+```
+
+```ts
+import { OneTable, OneCollapse, OneSkeleton } from '@geektech/one';
+
+new OneTable({
+  data: [
+    { name: '林晚', role: '设计' },
+    { name: '苏北', role: '前端' },
+  ],
+  columns: [
+    { key: 'name', title: '姓名' },
+    { key: 'role', title: '角色' },
+  ],
+});
+new OneCollapse({
+  accordion: true,
+  defaultActive: ['basic'],
+  items: [
+    { value: 'basic', title: '基础用法', children: ['内容'] },
+    { value: 'advanced', title: '高级用法', children: ['更多内容'] },
+  ],
+});
+new OneSkeleton({ rows: 3, title: true, avatar: true });
+```
+
+## 反馈与浮层
+
+持续显示的页面内反馈使用 `OneAlert`，附着到单个触发元素的简短说明使用
+`OneTooltip`，进行中的加载状态使用 `OneLoading`：
+
+```ts
+import { OneAlert, OneButton, OneLoading, 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: ['复制'] }],
+});
+
+const loading = new OneLoading({ size: 'md', label: '加载中' });
+```
+
+临时消息和确认流程可以使用命令式服务：
+
+```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`、
@@ -97,6 +259,70 @@ uncontrolled.on('change', (payload) => {
 });
 ```
 
+## 选择与时间
+
+单选按钮从多个选项中选一个，时间选择器提供可编辑文本输入，点击展开时/分/秒下拉
+面板。二者都支持受控与非受控模式。
+
+```ts
+import {
+  OneRadio,
+  OneRadioGroup,
+  OneTimePicker,
+  type OneFieldValueEvent,
+} from '@geektech/one';
+
+const radio = new OneRadio({ value: 'design', defaultChecked: true });
+const group = new OneRadioGroup({
+  defaultValue: 'weekly',
+  ariaLabel: '通知频率',
+  options: [
+    { value: 'daily', label: '每天' },
+    { value: 'weekly', label: '每周' },
+  ],
+});
+group.on('change', (payload) => {
+  const event = payload as OneFieldValueEvent<string>;
+  console.log(event.value);
+});
+
+new OneTimePicker({ defaultValue: '09:30', ariaLabel: '开始时间' });
+```
+
+## 滑块、评分与上传
+
+滑块在范围内选择一个数值，评分用星星表达打分，上传用于收集本地文件元数据。
+三者都支持受控与非受控模式。
+
+```ts
+import {
+  OneSlider,
+  OneRate,
+  OneUpload,
+  type OneSliderValueEvent,
+  type OneRateValueEvent,
+  type OneUploadChangeEvent,
+} from '@geektech/one';
+
+const slider = new OneSlider({ defaultValue: 60, showValue: true });
+slider.on('change', (payload) => {
+  const event = payload as OneSliderValueEvent;
+  console.log(event.value);
+});
+
+const rating = new OneRate({ defaultValue: 4, allowClear: true });
+rating.on('change', (payload) => {
+  const event = payload as OneRateValueEvent;
+  console.log(event.value);
+});
+
+const upload = new OneUpload({ multiple: true, ariaLabel: '附件' });
+upload.on('change', (payload) => {
+  const event = payload as OneUploadChangeEvent;
+  console.log(event.files.map((file) => file.name));
+});
+```
+
 ## 卡片插槽
 
 带有 `slot: 'header'` 或 `slot: 'footer'` 的子节点进入对应命名插槽，未指定
@@ -104,16 +330,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,171 @@ class App extends Component {
 createApp({ root: App }).mount();
 ```
 
+## Component categories
+
+- Basic: `OneButton`
+- Form: `OneForm`, `OneFormItem`, `OneInput`, `OneSelect`, `OneTimePicker`,
+  `OneCheckbox`, `OneCheckboxGroup`, `OneRadio`, `OneRadioGroup`, `OneSwitch`,
+  `OneSlider`, `OneRate`, `OneUpload`
+- Navigation: `OneTabs`, `OneBreadcrumb`, `OnePagination`
+- Data display: `OneCard`, `OneTag`, `OneBadge`, `OneAvatar`, `OneProgress`,
+  `OneEmpty`, `OneTable`, `OneCollapse`, `OneSkeleton`
+- Feedback and overlays: `OneAlert`, `OneMessage`, `OneDialog`, `OneTooltip`,
+  `OneLoading`
+
+## 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, avatars for identity, progress
+bars for completion, empty states when a view has no content, tables for row
+data, collapsible panels for grouped detail, and skeletons while content loads.
+`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 });
+```
+
+```ts
+import { OneAvatar, OneProgress } from '@geektech/one';
+
+new OneAvatar({ text: 'M', variant: 'primary' });
+new OneAvatar({ src: '/avatar.png', alt: 'Avatar', shape: 'square' });
+new OneProgress({ percent: 65, showText: true });
+new OneProgress({ percent: 30, variant: 'success' });
+```
+
+```ts
+import { OneTable, OneCollapse, OneSkeleton } from '@geektech/one';
+
+new OneTable({
+  data: [
+    { name: 'Eve Lin', role: 'Design' },
+    { name: 'Ben Su', role: 'Frontend' },
+  ],
+  columns: [
+    { key: 'name', title: 'Name' },
+    { key: 'role', title: 'Role' },
+  ],
+});
+new OneCollapse({
+  accordion: true,
+  defaultActive: ['basic'],
+  items: [
+    { value: 'basic', title: 'Basic usage', children: ['Content'] },
+    { value: 'advanced', title: 'Advanced usage', children: ['More content'] },
+  ],
+});
+new OneSkeleton({ rows: 3, title: true, avatar: true });
+```
+
+## Feedback and overlays
+
+Use `OneAlert` for persistent inline feedback, `OneTooltip` for a short
+description attached to one trigger element, and `OneLoading` for an
+in-progress indicator:
+
+```ts
+import { OneAlert, OneButton, OneLoading, 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'] }],
+});
+
+const loading = new OneLoading({ size: 'md', label: 'Loading' });
+```
+
+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`,
@@ -97,6 +262,72 @@ uncontrolled.on('change', (payload) => {
 });
 ```
 
+## Selection and time
+
+Radio buttons pick one option out of several. Time pickers offer an editable
+text input plus a click-to-open hour/minute/second dropdown. Both support
+controlled and uncontrolled modes.
+
+```ts
+import {
+  OneRadio,
+  OneRadioGroup,
+  OneTimePicker,
+  type OneFieldValueEvent,
+} from '@geektech/one';
+
+const radio = new OneRadio({ value: 'design', defaultChecked: true });
+const group = new OneRadioGroup({
+  defaultValue: 'weekly',
+  ariaLabel: 'Frequency',
+  options: [
+    { value: 'daily', label: 'Daily' },
+    { value: 'weekly', label: 'Weekly' },
+  ],
+});
+group.on('change', (payload) => {
+  const event = payload as OneFieldValueEvent<string>;
+  console.log(event.value);
+});
+
+new OneTimePicker({ defaultValue: '09:30', ariaLabel: 'Start time' });
+```
+
+## Sliders, ratings and uploads
+
+Sliders pick a number within a range, ratings express a star score, and uploads
+collect local file metadata. All three support controlled and uncontrolled
+modes.
+
+```ts
+import {
+  OneSlider,
+  OneRate,
+  OneUpload,
+  type OneSliderValueEvent,
+  type OneRateValueEvent,
+  type OneUploadChangeEvent,
+} from '@geektech/one';
+
+const slider = new OneSlider({ defaultValue: 60, showValue: true });
+slider.on('change', (payload) => {
+  const event = payload as OneSliderValueEvent;
+  console.log(event.value);
+});
+
+const rating = new OneRate({ defaultValue: 4, allowClear: true });
+rating.on('change', (payload) => {
+  const event = payload as OneRateValueEvent;
+  console.log(event.value);
+});
+
+const upload = new OneUpload({ multiple: true, ariaLabel: 'Attachments' });
+upload.on('change', (payload) => {
+  const event = payload as OneUploadChangeEvent;
+  console.log(event.files.map((file) => file.name));
+});
+```
+
 ## Card slots
 
 Children with `slot: 'header'` or `slot: 'footer'` fill the named regions;
@@ -104,16 +335,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/avatar/OneAvatar.d.ts

@@ -0,0 +1,21 @@
+import { Component, type VNode } from '@geektech/tsone';
+import { type OneDataDisplayVariant } from '../data-display';
+import { type OneNamedStyle } from '../styles/shared';
+import type { OneComponentSize } from '../types';
+export type OneAvatarShape = 'circle' | 'square';
+export interface OneAvatarProps {
+    src?: string;
+    alt?: string;
+    text?: string;
+    size?: OneComponentSize;
+    shape?: OneAvatarShape;
+    variant?: OneDataDisplayVariant;
+    ariaLabel?: string;
+    children?: Array<VNode | string>;
+}
+export declare const ONE_AVATAR_STYLES: OneNamedStyle[];
+export declare class OneAvatar extends Component<OneAvatarProps> {
+    protected initState(): object;
+    protected initStyles(): void;
+    protected render(): VNode;
+}

package/dist/avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { OneAvatar } from './OneAvatar';
+export type { OneAvatarProps, OneAvatarShape } from './OneAvatar';

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';