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

package/src/client/layout/Stack.tsx

@@ -0,0 +1,82 @@
+// `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,61 @@
+// `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;
+}