@dsh-plugin/dsh-ui-components 0.0.1 → 0.1.0-dev.43613492370

package/src/foundation/tokens.ts

@@ -1,62 +1,62 @@
-/**
- * 组件共用的几何量。
- *
- * 尺寸取自 DSH 的圆角标准与控制件实测值：标准控件高 36、紧凑控件高 28、
- * 输入框高 32；圆角按角色取 `--dsw-radius-*` 的像素等价量。颜色一律由
- * `bridge.ts` 里的 CSS 变量承担，本文件只管尺寸与字号。
- *
- * @module @dsh-plugin/dsh-ui-components/foundation/tokens
- */
-
-/** 组件共用的几何量，单位均为像素。 */
-export const G = {
-  /** 标准控件高度。 */
-  controlHeight: 36,
-  /** 紧凑控件高度。 */
-  controlHeightSm: 28,
-  /** 输入框高度，介于标准与紧凑之间。 */
-  inputHeight: 32,
-  /** 标准圆角，对应 `--dsw-radius-md`。 */
-  radius: 12,
-  /** 紧凑圆角，对应 `--dsw-radius-sm`。 */
-  radiusSm: 8,
-  /** 大圆角，对应 `--dsw-radius-lg`。 */
-  radiusLg: 16,
-  /** 卡片圆角，对应 `--dsw-radius-xl`。 */
-  radiusXl: 20,
-  /** 面板圆角，对应 `--dsw-radius-panel`。 */
-  radiusPanel: 28,
-  /** 胶囊圆角。 */
-  radiusPill: 999,
-  /** 正文基准字号。 */
-  fontSize: 14,
-  /** 说明文字字号。 */
-  fontSizeSm: 12,
-  /** 正文行高。 */
-  lineHeight: 22,
-  /** 说明文字行高。 */
-  lineHeightSm: 18,
-  /** 标准间距。 */
-  gap: 8,
-  /** 紧凑间距。 */
-  gapSm: 4,
-  /** 分区间距。 */
-  gapLg: 16,
-  /** 弹出层与窗口上下的最小留白。 */
-  overlayMargin: 120,
-} as const
-
-/**
- * 计算弹出层的最大高度。
- *
- * 全局规范要求弹出层与窗口顶部、底部各留至少 {@link G.overlayMargin}，
- * 因此最大高度是视口高度减去两倍留白。
- *
- * @returns 形如 `calc(100dvh - 240px)` 的高度表达式。
- */
-export function overlayMaxHeight(): string {
-  return `calc(100dvh - ${G.overlayMargin * 2}px)`
-}
-
-/** 弹出层最大高度的 CSS 值。 */
-export const OVERLAY_MAX_HEIGHT = overlayMaxHeight()
+/**
+ * 组件共用的几何量。
+ *
+ * 尺寸取自 DSH 的圆角标准与控制件实测值：标准控件高 36、紧凑控件高 28、
+ * 输入框高 32；圆角按角色取 `--dsw-radius-*` 的像素等价量。颜色一律由
+ * `bridge.ts` 里的 CSS 变量承担，本文件只管尺寸与字号。
+ *
+ * @module @dsh-plugin/dsh-ui-components/foundation/tokens
+ */
+
+/** 组件共用的几何量，单位均为像素。 */
+export const G = {
+  /** 标准控件高度。 */
+  controlHeight: 36,
+  /** 紧凑控件高度。 */
+  controlHeightSm: 28,
+  /** 输入框高度，介于标准与紧凑之间。 */
+  inputHeight: 32,
+  /** 标准圆角，对应 `--dsw-radius-md`。 */
+  radius: 12,
+  /** 紧凑圆角，对应 `--dsw-radius-sm`。 */
+  radiusSm: 8,
+  /** 大圆角，对应 `--dsw-radius-lg`。 */
+  radiusLg: 16,
+  /** 卡片圆角，对应 `--dsw-radius-xl`。 */
+  radiusXl: 20,
+  /** 面板圆角，对应 `--dsw-radius-panel`。 */
+  radiusPanel: 28,
+  /** 胶囊圆角。 */
+  radiusPill: 999,
+  /** 正文基准字号。 */
+  fontSize: 14,
+  /** 说明文字字号。 */
+  fontSizeSm: 12,
+  /** 正文行高。 */
+  lineHeight: 22,
+  /** 说明文字行高。 */
+  lineHeightSm: 18,
+  /** 标准间距。 */
+  gap: 8,
+  /** 紧凑间距。 */
+  gapSm: 4,
+  /** 分区间距。 */
+  gapLg: 16,
+  /** 弹出层与窗口上下的最小留白。 */
+  overlayMargin: 120,
+} as const
+
+/**
+ * 计算弹出层的最大高度。
+ *
+ * 全局规范要求弹出层与窗口顶部、底部各留至少 {@link G.overlayMargin}，
+ * 因此最大高度是视口高度减去两倍留白。
+ *
+ * @returns 形如 `calc(100dvh - 240px)` 的高度表达式。
+ */
+export function overlayMaxHeight(): string {
+  return `calc(100dvh - ${G.overlayMargin * 2}px)`
+}
+
+/** 弹出层最大高度的 CSS 值。 */
+export const OVERLAY_MAX_HEIGHT = overlayMaxHeight()

package/src/index.ts

@@ -1,18 +1,18 @@
-/**
- * 包出口。
- *
- * 组件按批次分组再统一从这里导出，调用方只依赖一个入口。图标另有两条通道：
- * 根导出的策划命名集，以及 `./icons/<pascal>` 这类逐图标子路径。
- *
- * 组件需要 DSH 皮肤时，在插件根部挂一次 `DshProvider`；不挂也能渲染，但
- * Arco 的浮层会挂到 `body` 下而拿不到 `.dsh-ui` 的变量。
- *
- * @module @dsh-plugin/dsh-ui-components
- */
-export * from './foundation/index.js'
-export * from './basic/index.js'
-export * from './display/index.js'
-export * from './feedback/index.js'
-export * from './navigation/index.js'
-export * from './data/index.js'
-export * from './composites/index.js'
+/**
+ * 包出口。
+ *
+ * 组件按批次分组再统一从这里导出，调用方只依赖一个入口。图标另有两条通道：
+ * 根导出的策划命名集，以及 `./icons/<pascal>` 这类逐图标子路径。
+ *
+ * 组件需要 DSH 皮肤时，在插件根部挂一次 `DshProvider`；不挂也能渲染，但
+ * Arco 的浮层会挂到 `body` 下而拿不到 `.dsh-ui` 的变量。
+ *
+ * @module @dsh-plugin/dsh-ui-components
+ */
+export * from './foundation/index.js'
+export * from './basic/index.js'
+export * from './display/index.js'
+export * from './feedback/index.js'
+export * from './navigation/index.js'
+export * from './data/index.js'
+export * from './composites/index.js'

package/src/navigation/hierarchy.tsx

@@ -1,82 +1,82 @@
-/**
- * 页面结构与位置指示：面包屑、分页、步骤条。
- *
- * @module @dsh-plugin/dsh-ui-components/navigation/hierarchy
- */
-import * as React from 'react'
-import { Arco } from '@dsh-plugin/dsh-loader/client'
-import { injectNavigationStyles } from './styles.js'
-
-/** {@link Breadcrumb} 的 props。 */
-export type BreadcrumbProps = React.ComponentPropsWithoutRef<typeof Arco.Breadcrumb>
-
-/**
- * 层级路径。
- *
- * @param props - 见 {@link BreadcrumbProps}。
- * @returns 面包屑元素。
- */
-export function Breadcrumb(props: BreadcrumbProps): React.ReactElement {
-  injectNavigationStyles()
-  return <Arco.Breadcrumb {...props} />
-}
-
-/** {@link BreadcrumbItem} 的 props。 */
-export type BreadcrumbItemProps = React.ComponentPropsWithoutRef<typeof Arco.Breadcrumb.Item>
-
-/**
- * 面包屑中的一个节点。
- *
- * @param props - 见 {@link BreadcrumbItemProps}。
- * @returns 面包屑节点元素。
- */
-export function BreadcrumbItem(props: BreadcrumbItemProps): React.ReactElement {
-  injectNavigationStyles()
-  return <Arco.Breadcrumb.Item {...props} />
-}
-
-/** {@link Pagination} 的 props。 */
-export type PaginationProps = React.ComponentPropsWithoutRef<typeof Arco.Pagination>
-
-/**
- * 分页器。
- *
- * @param props - 见 {@link PaginationProps}。
- * @returns 分页元素。
- */
-export function Pagination(props: PaginationProps): React.ReactElement {
-  injectNavigationStyles()
-  return <Arco.Pagination {...props} />
-}
-
-/** {@link Steps} 的 props。 */
-export type StepsProps = React.ComponentPropsWithoutRef<typeof Arco.Steps>
-
-/**
- * 步骤条。
- *
- * `<Steps.Step />` 与 Arco 本身一致，用作单步。
- *
- * @param props - 见 {@link StepsProps}。
- * @returns 步骤条元素。
- */
-function StepsBase(props: StepsProps): React.ReactElement {
-  injectNavigationStyles()
-  return <Arco.Steps {...props} />
-}
-
-/** {@link Step} 的 props。 */
-export type StepProps = React.ComponentPropsWithoutRef<typeof Arco.Steps.Step>
-
-/**
- * 步骤条中的一步。
- *
- * 这里直接取 Arco 的原组件而不是包一层：Arco 通过 `child.type` 识别子步骤，
- * 包一层会让识别失败并静默渲染出空步骤条。
- */
-export const Step: typeof Arco.Steps.Step = Arco.Steps.Step
-
-/** 带静态子组件的步骤条导出。 */
-export const Steps: typeof StepsBase & { Step: typeof Arco.Steps.Step } = Object.assign(StepsBase, {
-  Step: Arco.Steps.Step,
-})
+/**
+ * 页面结构与位置指示：面包屑、分页、步骤条。
+ *
+ * @module @dsh-plugin/dsh-ui-components/navigation/hierarchy
+ */
+import * as React from 'react'
+import { Arco } from '@dsh-plugin/dsh-loader/client'
+import { injectNavigationStyles } from './styles.js'
+
+/** {@link Breadcrumb} 的 props。 */
+export type BreadcrumbProps = React.ComponentPropsWithoutRef<typeof Arco.Breadcrumb>
+
+/**
+ * 层级路径。
+ *
+ * @param props - 见 {@link BreadcrumbProps}。
+ * @returns 面包屑元素。
+ */
+export function Breadcrumb(props: BreadcrumbProps): React.ReactElement {
+  injectNavigationStyles()
+  return <Arco.Breadcrumb {...props} />
+}
+
+/** {@link BreadcrumbItem} 的 props。 */
+export type BreadcrumbItemProps = React.ComponentPropsWithoutRef<typeof Arco.Breadcrumb.Item>
+
+/**
+ * 面包屑中的一个节点。
+ *
+ * @param props - 见 {@link BreadcrumbItemProps}。
+ * @returns 面包屑节点元素。
+ */
+export function BreadcrumbItem(props: BreadcrumbItemProps): React.ReactElement {
+  injectNavigationStyles()
+  return <Arco.Breadcrumb.Item {...props} />
+}
+
+/** {@link Pagination} 的 props。 */
+export type PaginationProps = React.ComponentPropsWithoutRef<typeof Arco.Pagination>
+
+/**
+ * 分页器。
+ *
+ * @param props - 见 {@link PaginationProps}。
+ * @returns 分页元素。
+ */
+export function Pagination(props: PaginationProps): React.ReactElement {
+  injectNavigationStyles()
+  return <Arco.Pagination {...props} />
+}
+
+/** {@link Steps} 的 props。 */
+export type StepsProps = React.ComponentPropsWithoutRef<typeof Arco.Steps>
+
+/**
+ * 步骤条。
+ *
+ * `<Steps.Step />` 与 Arco 本身一致，用作单步。
+ *
+ * @param props - 见 {@link StepsProps}。
+ * @returns 步骤条元素。
+ */
+function StepsBase(props: StepsProps): React.ReactElement {
+  injectNavigationStyles()
+  return <Arco.Steps {...props} />
+}
+
+/** {@link Step} 的 props。 */
+export type StepProps = React.ComponentPropsWithoutRef<typeof Arco.Steps.Step>
+
+/**
+ * 步骤条中的一步。
+ *
+ * 这里直接取 Arco 的原组件而不是包一层：Arco 通过 `child.type` 识别子步骤，
+ * 包一层会让识别失败并静默渲染出空步骤条。
+ */
+export const Step: typeof Arco.Steps.Step = Arco.Steps.Step
+
+/** 带静态子组件的步骤条导出。 */
+export const Steps: typeof StepsBase & { Step: typeof Arco.Steps.Step } = Object.assign(StepsBase, {
+  Step: Arco.Steps.Step,
+})

package/src/navigation/index.ts

@@ -1,21 +1,21 @@
-/**
- * 导航组件出口。
- *
- * @module @dsh-plugin/dsh-ui-components/navigation
- */
-export { Dropdown, Menu, MenuItem, TabPane, Tabs, type DropdownProps, type MenuItemProps, type MenuProps, type TabPaneProps, type TabsProps } from './menu.js'
-export {
-  Breadcrumb,
-  BreadcrumbItem,
-  Pagination,
-  Step,
-  Steps,
-  type BreadcrumbItemProps,
-  type BreadcrumbProps,
-  type PaginationProps,
-  type StepProps,
-  type StepsProps,
-} from './hierarchy.js'
-export { SegmentedControl, type Segment, type SegmentedControlProps } from './segmented.js'
-export { DisclosureRow, StateDot, type DisclosureRowProps, type StateDotProps, type StateDotState } from './indicator.js'
-export { NAVIGATION_CSS, injectNavigationStyles } from './styles.js'
+/**
+ * 导航组件出口。
+ *
+ * @module @dsh-plugin/dsh-ui-components/navigation
+ */
+export { Dropdown, Menu, MenuItem, TabPane, Tabs, type DropdownProps, type MenuItemProps, type MenuProps, type TabPaneProps, type TabsProps } from './menu.js'
+export {
+  Breadcrumb,
+  BreadcrumbItem,
+  Pagination,
+  Step,
+  Steps,
+  type BreadcrumbItemProps,
+  type BreadcrumbProps,
+  type PaginationProps,
+  type StepProps,
+  type StepsProps,
+} from './hierarchy.js'
+export { SegmentedControl, type Segment, type SegmentedControlProps } from './segmented.js'
+export { DisclosureRow, StateDot, type DisclosureRowProps, type StateDotProps, type StateDotState } from './indicator.js'
+export { NAVIGATION_CSS, injectNavigationStyles } from './styles.js'

package/src/navigation/indicator.tsx

@@ -1,125 +1,125 @@
-/**
- * 折叠标题行与状态点。
- *
- * `DisclosureRow` 是宿主思考行、工具行那样「一行标题 + 就地展开内容」的结构；
- * `StateDot` 是列表与任务行的状态标记。
- *
- * @module @dsh-plugin/dsh-ui-components/navigation/indicator
- */
-import * as React from 'react'
-import { cx } from '../foundation/style.js'
-import { Icon } from '../foundation/icons.js'
-import { injectNavigationStyles } from './styles.js'
-
-/** {@link DisclosureRow} 的 props。 */
-export interface DisclosureRowProps {
-  /** 标题。 */
-  title: React.ReactNode
-  /** 标题前的小图标。 */
-  leading?: React.ReactNode
-  /** 展开后的内容。不需要展开时省略。 */
-  children?: React.ReactNode
-  /** 受控展开状态；与 `onToggle` 同时提供时由调用方持有。 */
-  expanded?: boolean
-  /** 默认展开状态，非受控时使用。 */
-  defaultExpanded?: boolean
-  /** 展开状态变化时回调。 */
-  onToggle?: (expanded: boolean) => void
-  /** 标题行右侧的独立操作，点击它不会触发展开。 */
-  accessory?: React.ReactNode
-  /** 追加类名。 */
-  className?: string
-}
-
-/**
- * 一行可折叠的标题。
- *
- * 展开时标题行显示向上箭头，收起时悬停显示向下箭头，与宿主的思考行一致。
- *
- * @param props - 见 {@link DisclosureRowProps}。
- * @returns 折叠行元素。
- */
-export function DisclosureRow({
-  title,
-  leading,
-  children,
-  expanded,
-  defaultExpanded = false,
-  onToggle,
-  accessory,
-  className,
-}: DisclosureRowProps): React.ReactElement {
-  injectNavigationStyles()
-  const [internal, setInternal] = React.useState(defaultExpanded)
-  const open = expanded ?? internal
-  const expandable = children !== undefined
-
-  /**
-   * 切换展开状态。受控与非受控都走同一入口。
-   */
-  const toggle = (): void => {
-    if (!expandable) return
-    const next = !open
-    if (expanded === undefined) setInternal(next)
-    onToggle?.(next)
-  }
-
-  const header = (
-    <>
-      {leading === undefined ? null : <span className="dsh-disclosure__leading" aria-hidden="true">{leading}</span>}
-      <span className="dsh-disclosure__title">{title}</span>
-      {expandable ? (
-        <span className="dsh-disclosure__leading" aria-hidden="true">
-          <Icon name={open ? 'ChevronDown' : 'ChevronRight'} size={14} />
-        </span>
-      ) : null}
-    </>
-  )
-
-  return (
-    <div className={cx('dsh-disclosure', className)}>
-      <div className="dsh-disclosure__header">
-        {expandable ? (
-          <button
-            type="button"
-            className="dsh-disclosure__header--expandable"
-            aria-expanded={open}
-            onClick={toggle}
-            style={{ display: 'flex', alignItems: 'center', gap: 6 }}
-          >
-            {header}
-          </button>
-        ) : (
-          <span className="dsh-disclosure__header--expandable" style={{ display: 'flex', alignItems: 'center', gap: 6 }}>{header}</span>
-        )}
-        {accessory}
-      </div>
-      {expandable && open ? <div className="dsh-disclosure__content">{children}</div> : null}
-    </div>
-  )
-}
-
-/** 状态点的状态。 */
-export type StateDotState = 'done' | 'warning' | 'error' | 'idle' | 'ongoing'
-
-/** {@link StateDot} 的 props。 */
-export interface StateDotProps {
-  /** 状态，默认 `idle`。 */
-  state?: StateDotState
-  /** 追加类名。 */
-  className?: string
-}
-
-/**
- * 一个状态标记。
- *
- * 它是装饰元素（`aria-hidden`），名字由所在行的调用方提供；`ongoing` 渲染
- * 为持续旋转的圆环，其余状态是一枚实心圆点。
- *
- * @param props - 见 {@link StateDotProps}。
- * @returns 状态点元素。
- */
-export function StateDot({ state = 'idle', className }: StateDotProps): React.ReactElement {
-  injectNavigationStyles()
-  return <span className={cx('dsh-state-dot', className)} data-state={state} aria-hidden="true" />
-}
+/**
+ * 折叠标题行与状态点。
+ *
+ * `DisclosureRow` 是宿主思考行、工具行那样「一行标题 + 就地展开内容」的结构；
+ * `StateDot` 是列表与任务行的状态标记。
+ *
+ * @module @dsh-plugin/dsh-ui-components/navigation/indicator
+ */
+import * as React from 'react'
+import { cx } from '../foundation/style.js'
+import { Icon } from '../foundation/icons.js'
+import { injectNavigationStyles } from './styles.js'
+
+/** {@link DisclosureRow} 的 props。 */
+export interface DisclosureRowProps {
+  /** 标题。 */
+  title: React.ReactNode
+  /** 标题前的小图标。 */
+  leading?: React.ReactNode
+  /** 展开后的内容。不需要展开时省略。 */
+  children?: React.ReactNode
+  /** 受控展开状态；与 `onToggle` 同时提供时由调用方持有。 */
+  expanded?: boolean
+  /** 默认展开状态，非受控时使用。 */
+  defaultExpanded?: boolean
+  /** 展开状态变化时回调。 */
+  onToggle?: (expanded: boolean) => void
+  /** 标题行右侧的独立操作，点击它不会触发展开。 */
+  accessory?: React.ReactNode
+  /** 追加类名。 */
+  className?: string
+}
+
+/**
+ * 一行可折叠的标题。
+ *
+ * 展开时标题行显示向上箭头，收起时悬停显示向下箭头，与宿主的思考行一致。
+ *
+ * @param props - 见 {@link DisclosureRowProps}。
+ * @returns 折叠行元素。
+ */
+export function DisclosureRow({
+  title,
+  leading,
+  children,
+  expanded,
+  defaultExpanded = false,
+  onToggle,
+  accessory,
+  className,
+}: DisclosureRowProps): React.ReactElement {
+  injectNavigationStyles()
+  const [internal, setInternal] = React.useState(defaultExpanded)
+  const open = expanded ?? internal
+  const expandable = children !== undefined
+
+  /**
+   * 切换展开状态。受控与非受控都走同一入口。
+   */
+  const toggle = (): void => {
+    if (!expandable) return
+    const next = !open
+    if (expanded === undefined) setInternal(next)
+    onToggle?.(next)
+  }
+
+  const header = (
+    <>
+      {leading === undefined ? null : <span className="dsh-disclosure__leading" aria-hidden="true">{leading}</span>}
+      <span className="dsh-disclosure__title">{title}</span>
+      {expandable ? (
+        <span className="dsh-disclosure__leading" aria-hidden="true">
+          <Icon name={open ? 'ChevronDown' : 'ChevronRight'} size={14} />
+        </span>
+      ) : null}
+    </>
+  )
+
+  return (
+    <div className={cx('dsh-disclosure', className)}>
+      <div className="dsh-disclosure__header">
+        {expandable ? (
+          <button
+            type="button"
+            className="dsh-disclosure__header--expandable"
+            aria-expanded={open}
+            onClick={toggle}
+            style={{ display: 'flex', alignItems: 'center', gap: 6 }}
+          >
+            {header}
+          </button>
+        ) : (
+          <span className="dsh-disclosure__header--expandable" style={{ display: 'flex', alignItems: 'center', gap: 6 }}>{header}</span>
+        )}
+        {accessory}
+      </div>
+      {expandable && open ? <div className="dsh-disclosure__content">{children}</div> : null}
+    </div>
+  )
+}
+
+/** 状态点的状态。 */
+export type StateDotState = 'done' | 'warning' | 'error' | 'idle' | 'ongoing'
+
+/** {@link StateDot} 的 props。 */
+export interface StateDotProps {
+  /** 状态，默认 `idle`。 */
+  state?: StateDotState
+  /** 追加类名。 */
+  className?: string
+}
+
+/**
+ * 一个状态标记。
+ *
+ * 它是装饰元素（`aria-hidden`），名字由所在行的调用方提供；`ongoing` 渲染
+ * 为持续旋转的圆环，其余状态是一枚实心圆点。
+ *
+ * @param props - 见 {@link StateDotProps}。
+ * @returns 状态点元素。
+ */
+export function StateDot({ state = 'idle', className }: StateDotProps): React.ReactElement {
+  injectNavigationStyles()
+  return <span className={cx('dsh-state-dot', className)} data-state={state} aria-hidden="true" />
+}