@morlay/dsh-client-ui-primitives 0.0.7 → 0.0.8

package/src/client/controls/classes.ts

@@ -0,0 +1,7 @@
+// 拼 class 名：CSS Modules 的映射查表给 `string | undefined`（`exactOptionalPropertyTypes` 下没命中的键是
+// undefined），一个没命中的类名不该在 DOM 上留一个空串。
+export function classes(...names: readonly (string | false | null | undefined)[]): string {
+  return names
+    .filter((name): name is string => typeof name === "string" && name !== "")
+    .join(" ");
+}

package/src/client/controls/index.ts

@@ -0,0 +1,30 @@
+// 设置面通用控件：按钮、图标按钮、选择器、标签输入、多行文本。
+//
+// 官方那套基础组件（`Menu` / `Modal` / `Switch` / …）由本包统一 re-export（见 `../index.ts`），业务包只从这里取控件。
+// 两类"带候选"的控件共用同一套「搜索 + 候选」交互：
+// - **multi-input**（`TagInput`）：多值 + 自由输入，聚焦即整体下拉候选、输入即过滤，候选只是加速；
+// - **searchable**（`SearchSelect`）：单值，从候选里搜着选。
+
+export { Bubble, type BubbleProps } from "./Bubble.tsx";
+export { Button, type ButtonProps, type ButtonTone } from "./Button.tsx";
+export { DisclosureRow, type DisclosureRowProps } from "./DisclosureRow.tsx";
+export { SearchInput, type SearchInputProps, type SearchInputWidth } from "./SearchInput.tsx";
+export { SeatButton, type SeatButtonProps } from "./SeatButton.tsx";
+export { Spinner, type SpinnerProps } from "./Spinner.tsx";
+export { Tabs, type TabItem, type TabsProps } from "./Tabs.tsx";
+export { TimeLabel, type TimeLabelProps } from "./TimeLabel.tsx";
+export { VisuallyHidden, type VisuallyHiddenProps } from "./VisuallyHidden.tsx";
+export { IconButton, type IconButtonProps } from "./IconButton.tsx";
+export {
+  ModelRouteList,
+  type ModelRouteCandidate,
+  type ModelRouteListProps,
+} from "./ModelRouteList.tsx";
+export { MultilineField, type MultilineFieldProps } from "./MultilineField.tsx";
+export {
+  SearchSelect,
+  type SearchSelectOption,
+  type SearchSelectProps,
+} from "./SearchSelect.tsx";
+export { TagInput, type TagInputProps } from "./TagInput.tsx";
+export { mergeTags, parseTagList } from "./tags.ts";

package/src/client/controls/tags.ts

@@ -0,0 +1,24 @@
+// 名单类字段的文本解析：把粘贴或输入的一串名字折成标签列表。
+
+// 分隔符：中英逗号、分号、制表符与换行；去空白、去重、保序。
+export function parseTagList(text: string): string[] {
+  const seen = new Set<string>();
+  const names: string[] = [];
+  for (const raw of text.split(/[,，;；\t\n\r]+/u)) {
+    const name = raw.trim();
+    if (name === "" || seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+  }
+  return names;
+}
+
+// 把新名字并进现有名单：去重、保序（现有的在前），返回新数组（一次替换就是一次编辑动作）。
+export function mergeTags(current: readonly string[], incoming: readonly string[]): string[] {
+  const merged = [...current];
+  for (const name of incoming) {
+    if (name === "" || merged.includes(name)) continue;
+    merged.push(name);
+  }
+  return merged;
+}

package/src/client/index.ts

@@ -1,10 +1,18 @@
 import type { Context } from "@deepseek-ai/cordis";
 import * as schemaForm from "./schema-form/index.ts";
 
-export * from "./styling/index.ts";
-export * from "./theme.ts";
+// 官方那套基础组件（`Button` / `Menu` / `Input` / `Tag` / `Modal` / `Switch` / `SegmentedControl` /
+// `SettingsForm` 与两个字段控件 / `DisclosureRow` / 图标 …）统一从这里转出：业务包只向本包取控件，不必各自去认
+// 官方包名。官方那份**直接用**（同形同名、样式本来就是上游的 CSS Modules），本包只补官方没有的那几件。
+export * from "@deepseek-ai/dsh-client-ui-primitives";
+
 export * from "./markdown-labels.ts";
+export * from "./layout/index.ts";
 export * from "./settings-form/index.ts";
+export * from "./controls/index.ts";
+// `Button` 与 `DisclosureRow` 是本包包装版（官方那份 + 文字不换行 / 危险档 / 两条固定的布局类）：
+// 两个星号导出之间必须显式点名，否则判成歧义。
+export { Button, DisclosureRow, type ButtonProps, type ButtonTone, type DisclosureRowProps } from "./controls/index.ts";
 // 按行 schema 自动生成的行配置页（原 `@morlay/dsh-client-ui-schema-form/client`，2026-09-28 合并进来）：
 // 两者都是"对话 UI / 设置页的基础面"，拆成两行会各自注册一遍、还要求每个 bundle 都插齐两行。
 // 只**具名导出**它那一面的门面：`export *` 会与 settings-form 的样式 / token 重名。

package/src/client/layout/Row.tsx

@@ -0,0 +1,86 @@
+// `Row`：横向行 + 间距档。标题行的「左列文本 + 右侧控件」（`justify="between"`）、按钮排、标签排都用它。
+
+import { forwardRef, type ElementType, type HTMLAttributes, type ReactNode } from "react";
+import { classes } from "../controls/classes.ts";
+import css from "./layout.module.css";
+import {
+  alignClass,
+  gapClass,
+  justifyClass,
+  padClass,
+  type LayoutAlign,
+  type LayoutGap,
+  type LayoutJustify,
+  type LayoutPad,
+} from "./scales.ts";
+
+export interface RowProps extends HTMLAttributes<HTMLDivElement> {
+  // 渲染成哪个元素（行内摘要用 `span`）。
+  as?: ElementType;
+  // 子项之间的横向间距。
+  gap?: LayoutGap;
+  // 交叉轴对齐；缺省 `stretch`。
+  align?: LayoutAlign;
+  // 主轴分布；缺省从起点排。
+  justify?: LayoutJustify;
+  // 放不下就换行。
+  wrap?: boolean;
+  // 撑开：吃掉剩下的宽度并允许收缩。
+  grow?: boolean;
+  // 卡片底座（边框 + 圆角 + 底色）。
+  boxed?: boolean;
+  // 不被压缩（页头、动作排这类固定项）。
+  fixed?: boolean;
+  // 窄列宽度（对话消息那一列）。
+  narrow?: boolean;
+  // 贴右：把这一项推到行尾。
+  push?: boolean;
+  // 列表（配 `as="ul"`）：去掉列表标记与内距。
+  plain?: boolean;
+  // 内距档；缺省不留内距。
+  pad?: LayoutPad;
+}
+
+export const Row = forwardRef<HTMLElement, RowProps>(function Row({
+  as: Element = "div",
+  gap,
+  align,
+  justify,
+  wrap = false,
+  grow = false,
+  boxed = false,
+  fixed = false,
+  narrow = false,
+  push = false,
+  plain = false,
+  pad,
+  className,
+  children,
+  ...rest
+}, ref): ReactNode {
+  return (
+    <Element
+      ref={ref}
+      className={classes(
+        css.row,
+        gapClass(css, gap),
+        alignClass(css, align),
+        justifyClass(css, justify),
+        padClass(css, pad),
+        wrap ? css.wrap : undefined,
+        grow ? css.grow : undefined,
+        boxed ? css.boxed : undefined,
+        fixed ? css.fixed : undefined,
+        narrow ? css.narrow : undefined,
+        push ? css.push : undefined,
+        boxed ? css.boxed : undefined,
+        fixed ? css.fixed : undefined,
+        plain ? css.plain : undefined,
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </Element>
+  );
+});

package/src/client/layout/Stack.tsx

@@ -0,0 +1,79 @@
+// `Stack`：纵向列 + 间距档。设置面上绝大多数区块都是它（页根、分组、字段列），
+// 间距只从档位里选，页面不写数值。
+
+import { forwardRef, type ElementType, type HTMLAttributes, type ReactNode } from "react";
+import { classes } from "../controls/classes.ts";
+import css from "./layout.module.css";
+import {
+  alignClass,
+  gapClass,
+  padClass,
+  type LayoutAlign,
+  type LayoutGap,
+  type LayoutPad,
+} from "./scales.ts";
+
+export interface StackProps extends HTMLAttributes<HTMLDivElement> {
+  // 渲染成哪个元素（区块用 `section`、列表用 `ul`、行内用 `span`）。
+  as?: ElementType;
+  // 子项之间的纵向间距。
+  gap?: LayoutGap;
+  // 交叉轴对齐；缺省 `stretch`（子项撑满整列）。
+  align?: LayoutAlign;
+  // 内距档；缺省不留内距。
+  pad?: LayoutPad;
+  // 撑开：吃掉剩下的宽度并允许收缩。
+  grow?: boolean;
+  // 卡片底座（边框 + 圆角 + 底色）。
+  boxed?: boolean;
+  // 不被压缩（页头、动作排这类固定项）。
+  fixed?: boolean;
+  // 窄列宽度（对话消息那一列）。
+  narrow?: boolean;
+  // 占满：页面根（宽高撑满、自己不滚）。
+  fill?: boolean;
+  // 滚动区：吃掉剩下的高度，内容长了它自己滚。
+  scroll?: boolean;
+  // 列表（配 `as="ul"`）：去掉列表标记与内距。
+  plain?: boolean;
+}
+
+export const Stack = forwardRef<HTMLElement, StackProps>(function Stack({
+  as: Element = "div",
+  gap,
+  align,
+  pad,
+  grow = false,
+  boxed = false,
+  fixed = false,
+  narrow = false,
+  fill = false,
+  scroll = false,
+  plain = false,
+  className,
+  children,
+  ...rest
+}, ref): ReactNode {
+  return (
+    <Element
+      ref={ref}
+      className={classes(
+        css.stack,
+        gapClass(css, gap),
+        alignClass(css, align),
+        padClass(css, pad),
+        grow ? css.grow : undefined,
+        boxed ? css.boxed : undefined,
+        fixed ? css.fixed : undefined,
+        narrow ? css.narrow : undefined,
+        fill ? css.fill : undefined,
+        scroll ? css.scroll : undefined,
+        plain ? css.plain : undefined,
+        className,
+      )}
+      {...rest}
+    >
+      {children}
+    </Element>
+  );
+});

package/src/client/layout/Text.tsx

@@ -0,0 +1,54 @@
+// `Text`：文本档位（字号 / 颜色 / 字重 / 等宽 / 截断）。设置面上的标题、说明、摘要、诊断行都从这里选档，
+// 页面不写字号与颜色。
+
+import type { ElementType, HTMLAttributes, ReactNode } from "react";
+import { classes } from "../controls/classes.ts";
+import css from "./layout.module.css";
+import { sizeClass, toneClass, weightClass, type TextSize, type TextTone, type TextWeight } from "./scales.ts";
+
+export interface TextProps extends Omit<HTMLAttributes<HTMLElement>, "children" | "color"> {
+  // 渲染成哪个元素（标题用 `h4`、说明用 `p`、行内摘要用 `span`）。
+  as?: ElementType;
+  // 字号档；缺省继承。
+  size?: TextSize;
+  // 颜色档；缺省继承。
+  tone?: TextTone;
+  // 字重档（区块标题那一档）。
+  weight?: TextWeight;
+  // 等宽（诊断行、配置值那类文本）。
+  mono?: boolean;
+  // 一行放不下就省略号截断。
+  truncate?: boolean;
+  // 数字等宽（计数、分页这类会跳动的数值）。
+  tabular?: boolean;
+  children?: ReactNode;
+}
+
+export function Text({
+  as: Element = "span",
+  size,
+  tone,
+  weight,
+  mono = false,
+  truncate = false,
+  tabular = false,
+  className,
+  children,
+}: TextProps): ReactNode {
+  return (
+    <Element
+      className={classes(
+        css.text,
+        sizeClass(css, size),
+        toneClass(css, tone),
+        weightClass(css, weight),
+        mono ? css.mono : undefined,
+        truncate ? css.truncate : undefined,
+        tabular ? css.tabular : undefined,
+        className,
+      )}
+    >
+      {children}
+    </Element>
+  );
+}

package/src/client/layout/index.ts

@@ -0,0 +1,16 @@
+// 布局原语：业务页面只摆结构与选档，不写样式。
+//
+// 通用原语（`Stack` / `Row` / `Text` / `Panel`）覆盖设置面的绝大多数排法；成型的那几件（字段行
+// `SettingsFieldRow`、标签输入 `TagInput` 等）住在 `../controls` 与 `../settings-form`。
+
+export { Row, type RowProps } from "./Row.tsx";
+export { Stack, type StackProps } from "./Stack.tsx";
+export { Text, type TextProps } from "./Text.tsx";
+export type {
+  LayoutAlign,
+  LayoutGap,
+  LayoutJustify,
+  LayoutPad,
+  TextSize,
+  TextTone,
+} from "./scales.ts";

package/src/client/layout/layout.module.css

@@ -0,0 +1,217 @@
+/* 布局原语共用的档位表：几何只有一套（间距 / 内距 / 文本档位），四个原语都从这份里取类名。
+   数值照官方设置面的尺度：2/4/6/8/12/14/16 的间距档、11/12/13/16 的字号档。 */
+
+/* 纵向列与横向行的底座。 */
+.stack {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.row {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  min-width: 0;
+}
+
+/* 间距档。 */
+.gap0 {
+  gap: 0;
+}
+.gap2 {
+  gap: 2px;
+}
+.gap4 {
+  gap: 4px;
+}
+.gap6 {
+  gap: 6px;
+}
+.gap8 {
+  gap: 8px;
+}
+.gap10 {
+  gap: 10px;
+}
+.gap12 {
+  gap: 12px;
+}
+.gap14 {
+  gap: 14px;
+}
+.gap16 {
+  gap: 16px;
+}
+
+/* 交叉轴对齐：不写就是 `stretch`（列里子项撑满，行里子项等高）。 */
+.alignStart {
+  align-items: flex-start;
+}
+.alignCenter {
+  align-items: center;
+}
+.alignEnd {
+  align-items: flex-end;
+}
+
+/* 主轴分布：`between` 是「左列文本 + 右侧控件」那一行，`end` 是分页那种贴右。 */
+.justifyBetween {
+  justify-content: space-between;
+}
+.justifyEnd {
+  justify-content: flex-end;
+}
+.justifyCenter {
+  justify-content: center;
+}
+
+/* 一行放不下就换行（标签与按钮排）。 */
+.wrap {
+  flex-wrap: wrap;
+}
+
+/* 撑开：吃掉剩下的宽度并允许收缩（长文本因此不会把整行撑出去）。 */
+.grow {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+/* 贴右：把这一项推到行尾。 */
+.push {
+  margin-left: auto;
+}
+
+/* 占满：整块页面的根（宽高都撑满，自己不滚——滚动交给里面的 `scroll` 那一层）。 */
+.fill {
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+/* 滚动区：吃掉剩下的高度，内容长了它自己滚。 */
+.scroll {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* 列表（`as="ul"` 时）：去掉列表标记与内距。 */
+.plain {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+/* 内距档：`card` 是模式卡片那档，`body` 是卡片内容那档，`page` / `row` / `blocking` 见注释。
+   上下必须对称——不对称的内距会让里面的行看着不在卡片中线（旧实现里的 4/8 与 8/4 就是这么偏的）。 */
+.padNone {
+  padding: 0;
+}
+.padCard {
+  padding: 8px 12px;
+}
+.padBody {
+  padding: 8px 0;
+}
+/* 页面根那一档。 */
+.padPage {
+  padding: 24px 28px;
+}
+/* 列表里的一行卡片。 */
+.padRow {
+  padding: 10px 12px;
+}
+/* 居中的提示块（加载中 / 阻塞提示）。 */
+.padBlocking {
+  padding: 32px 40px;
+}
+
+/* 文本档：字号 / 行高 / 颜色 / 字重 / 等宽 / 截断 / 等宽数字。 */
+.text {
+  margin: 0;
+}
+.sizeXs {
+  font-size: 11px;
+  line-height: 1.5;
+}
+.sizeSm {
+  font-size: 12px;
+  line-height: 18px;
+}
+.sizeMd {
+  font-size: 13px;
+  line-height: 20px;
+}
+.sizeBase {
+  font-size: 14px;
+  line-height: 24px;
+}
+.sizeLg {
+  font-size: 16px;
+  line-height: 24px;
+}
+.tonePrimary {
+  color: var(--dsw-alias-label-primary);
+}
+.toneSecondary {
+  color: var(--dsw-alias-label-secondary);
+}
+.toneTertiary {
+  color: var(--dsw-alias-label-tertiary);
+}
+/* 失败提示那一档：官方主题里有就用它，没有就退回主文本色。 */
+.toneDanger {
+  color: var(--dsw-alias-label-error, var(--dsw-alias-label-primary));
+}
+.weightMedium {
+  font-weight: 500;
+}
+.strong {
+  font-weight: 600;
+}
+.mono {
+  font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+  word-break: break-all;
+}
+.truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+/* 卡片底座：边框 + 圆角 + 底色（列表里的一行、用量块）。内距由 `pad` 档给。 */
+.boxed {
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 10px;
+  background: var(--dsw-alias-bg-base);
+}
+
+/* 不被压缩：页头、动作排这类固定项（内容变长时它们不该被压成 min-content）。 */
+.fixed {
+  flex: none;
+}
+
+/* 两轴不同间距的一排（统计项：列间距 20，换行后的行间距 6）。 */
+.gapWide {
+  column-gap: 20px;
+  row-gap: 6px;
+}
+
+/* 窄列：对话消息那一列。上游以宽度轴的比例表达 Figma 那个 525px 上限（525/748 ≈ 0.702），
+   748px 的兜底覆盖"挂在会话列之外"的挂载（此时轴变量不在）。 */
+.narrow {
+  min-width: 0;
+  max-width: min(calc(var(--dsh-chat-content-width, 748px) * 0.702), 82%);
+}
+
+/* 搜索框那一档宽度（列表与设置面的搜索行）。 */
+.wSearch {
+  width: 360px;
+  max-width: 100%;
+  flex: none;
+}

package/src/client/layout/scales.ts

@@ -0,0 +1,91 @@
+// 布局原语的档位：几何只有这一套，四个原语与消费方都从这里取，页面不写数值。
+
+// 间距档（px）：2/4/6/8 是行内与字段内的尺度，12/14/16 是区块之间的尺度。
+export type LayoutGap = 0 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 16 | "wide";
+
+// 交叉轴对齐：`stretch`（缺省）让列里子项撑满、行里子项等高。
+export type LayoutAlign = "stretch" | "start" | "center" | "end";
+
+// 主轴分布：`between` 用于"左列文本 + 右侧控件"那一行，`end` 用于贴右（分页）。
+export type LayoutJustify = "start" | "center" | "between" | "end";
+
+// 内距档：`card` = 模式卡片那档，`body` = 卡片内容那档，`page` / `row` / `blocking` 见样式表。
+export type LayoutPad = "none" | "card" | "body" | "page" | "row" | "blocking";
+
+// 文本字号档：11 / 12 / 13 / 16px。
+export type TextSize = "xs" | "sm" | "md" | "base" | "lg";
+
+// 文本颜色档。
+export type TextTone = "primary" | "secondary" | "tertiary" | "danger";
+
+// 文本字重档。
+export type TextWeight = "medium" | "strong";
+
+// 档位 → 类名。CSS Modules 的映射查表可能给 undefined（exactOptionalPropertyTypes），交给 `classes` 过滤。
+export function gapClass(
+  css: Readonly<Record<string, string | undefined>>,
+  gap?: LayoutGap,
+): string | undefined {
+  if (gap === undefined) return undefined;
+  // `wide` 是两轴不同间距的那一档（见样式表的 `.gapWide`）。
+  return gap === "wide" ? css.gapWide : css[`gap${gap}`];
+}
+
+export function alignClass(
+  css: Readonly<Record<string, string | undefined>>,
+  align?: LayoutAlign,
+): string | undefined {
+  if (align === undefined || align === "stretch") return undefined;
+  if (align === "start") return css.alignStart;
+  return align === "center" ? css.alignCenter : css.alignEnd;
+}
+
+export function justifyClass(
+  css: Readonly<Record<string, string | undefined>>,
+  justify?: LayoutJustify,
+): string | undefined {
+  if (justify === undefined) return undefined;
+  if (justify === "between") return css.justifyBetween;
+  if (justify === "end") return css.justifyEnd;
+  return justify === "center" ? css.justifyCenter : undefined;
+}
+
+export function padClass(
+  css: Readonly<Record<string, string | undefined>>,
+  pad?: LayoutPad,
+): string | undefined {
+  if (pad === undefined || pad === "none") return undefined;
+  if (pad === "card") return css.padCard;
+  if (pad === "body") return css.padBody;
+  if (pad === "page") return css.padPage;
+  return pad === "row" ? css.padRow : css.padBlocking;
+}
+
+export function sizeClass(
+  css: Readonly<Record<string, string | undefined>>,
+  size?: TextSize,
+): string | undefined {
+  if (size === undefined) return undefined;
+  if (size === "xs") return css.sizeXs;
+  if (size === "sm") return css.sizeSm;
+  if (size === "md") return css.sizeMd;
+  return size === "base" ? css.sizeBase : css.sizeLg;
+}
+
+export function toneClass(
+  css: Readonly<Record<string, string | undefined>>,
+  tone?: TextTone,
+): string | undefined {
+  if (tone === undefined) return undefined;
+  if (tone === "primary") return css.tonePrimary;
+  if (tone === "secondary") return css.toneSecondary;
+  return tone === "tertiary" ? css.toneTertiary : css.toneDanger;
+}
+
+export function weightClass(
+  css: Readonly<Record<string, string | undefined>>,
+  weight?: TextWeight,
+): string | undefined {
+  if (weight === undefined) return undefined;
+  return weight === "medium" ? css.weightMedium : css.strong;
+}