@ticatec/topside-elements 1.0.0

package/dist/layouts/box/README_CN.md

@@ -0,0 +1,312 @@
+# Box 容器组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `contentStyle` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+带可选 header / footer 的边框 flex-column 容器。卡片、面板、仪表盘小部件的结构化基础积木 —— Box 本身故意做得很最小（无阴影、无 padding），视觉效果通过 `style` / `content$style` 和 CSS 变量叠加。
+
+## 功能特性
+
+- **header 可来自 `title` 字符串或 `header` snippet** —— 两者同时传时 snippet 优先
+- **可选 `footer` snippet** —— 通常放操作按钮
+- **默认 children 填充中间**（`flex: 1 1 auto`、`overflow: hidden`）
+- **可选圆角**通过 `round` prop（设置 `border-radius: var(--topside-box-radius)`）
+- **外层 wrapper 裁剪溢出** —— 子内容不会溢出
+- **分区样式**：`style` 作用于外层，`content$style` 仅作用于内容区
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import Box from '@ticatec/topside-elements/Box';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Box from '@ticatec/topside-elements/Box';
+</script>
+
+<Box title="卡片标题">
+  <p>这是内容区域。</p>
+</Box>
+```
+
+> **Box 的内容区不带 padding。** 自己用 padded 容器包内容，或者传 `content$style="padding: 16px;"`。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | 渲染在 `.box-header > .title` 里的标题文字。提供 `header` snippet 时被忽略。空字符串 → 不渲染 header 块（除非提供了 `header` snippet） |
+| `round` | `boolean` | `false` | 加 `rounded` 类 → `border-radius: var(--topside-box-radius)` |
+| `style` | `string` | `''` | 外层 wrapper（`.topside-box`）的内联 CSS |
+| `content$style` | `string` | `''` | 内容区（`.box-content`）的内联 CSS。padding 写在这里，不影响 header/footer |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme`，便于作用域化 CSS 覆盖 |
+| `header` | `Snippet \| undefined` | `undefined` | 自定义 header 内容。**同时传 `title` 时 snippet 优先** |
+| `children` | `Snippet \| undefined` | `undefined` | 主要内容 |
+| `footer` | `Snippet \| undefined` | `undefined` | 底部内容（通常是操作按钮） |
+
+## Header 优先级
+
+header 块在 `title` 非空**或** `header` snippet 提供**任一满足**时渲染。两者都传时，**snippet 优先**，`title` 被忽略：
+
+```svelte
+<!-- ✅ 仅 title -->
+<Box title="你好">...</Box>
+
+<!-- ✅ 仅 header snippet -->
+<Box>
+  {#snippet header()}<h3>自定义标题</h3>{/snippet}
+  ...
+</Box>
+
+<!-- ⚠️ 两者都传：title 被忽略，渲染 header snippet -->
+<Box title="被忽略">
+  {#snippet header()}<h3>自定义标题</h3>{/snippet}
+  ...
+</Box>
+```
+
+如果既要保留 title 文字又要额外内容，自己在 snippet 里渲染 title。
+
+## 布局
+
+```text
+┌──────────────────────────────────┐
+│ .box-header        (title/header 提供时) │  ← user-select: none，title 加省略号
+├──────────────────────────────────┤
+│ .box-content       (flex 1，overflow: hidden)
+│   {children}                         │  ← 默认无 padding，靠 content$style 加
+├──────────────────────────────────┤
+│ .box-footer        (footer 提供时)      │  ← flex row，user-select: none
+└──────────────────────────────────┘
+```
+
+内置样式：
+
+```css
+.topside-box {
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  box-sizing: border-box;
+  overflow: hidden;                  /* 子内容不溢出 */
+  background-color: var(--topside-box-color-surface);
+  border: 1px solid var(--topside-box-color-border);
+  color: var(--topside-primary-color-font);
+}
+
+.topside-box.rounded { border-radius: var(--topside-box-radius); }
+
+.box-header {
+  width: 100%;
+  background-color: var(--topside-box-color-header-surface);
+  color: var(--topside-box-color-header-title);
+  user-select: none;
+  overflow: hidden;
+}
+
+.box-header .title {
+  width: 100%;
+  padding: var(--topside-box-header-padding);
+  white-space: nowrap;               /* 单行 */
+  text-overflow: ellipsis;           /* 溢出加 … */
+  font-weight: var(--topside-box-header-font-weight, 600);
+}
+
+.box-content {
+  flex: 1 1 auto;
+  position: relative;
+  overflow: hidden;
+}
+
+.box-footer {
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  width: 100%;
+  flex: 0 0 auto;
+  user-select: none;
+  background-color: var(--topside-box-color-footer-surface);
+  color: var(--topside-box-color-footer-title);
+  font-weight: var(--topside-box-footer-font-weight, normal);
+}
+```
+
+## 示例
+
+### 标题 + 内容
+
+```svelte
+<Box title="信息">
+  <p>这是一些需要显示的重要信息。</p>
+</Box>
+```
+
+### 标题 + 内容 + 底部（操作按钮）
+
+```svelte
+<script>
+  import Box from '@ticatec/topside-elements/Box';
+  import ActionBar from '@ticatec/topside-elements/ActionBar';
+</script>
+
+<Box title="用户资料" content$style="padding: 16px;">
+  <p>用户信息和详情</p>
+
+  {#snippet footer()}
+    <ActionBar
+      style="width: 100%; justify-content: flex-end; padding: 8px 12px;"
+      buttons={[
+        { label: '取消', handler: cancel },
+        { label: '保存', type: 'primary', handler: save }
+      ]}
+    />
+  {/snippet}
+</Box>
+```
+
+### 自定义标题（标题文字 + 操作按钮）
+
+```svelte
+<Box content$style="padding: 16px;">
+  {#snippet header()}
+    <div style="display: flex; justify-content: space-between; align-items: center; padding: 8px 16px;">
+      <h3>销售概览</h3>
+      <Button type="primary" label="导出" onclick={exportReport} />
+    </div>
+  {/snippet}
+
+  <!-- 内容 -->
+  <p>...</p>
+</Box>
+```
+
+### 圆角 + 阴影卡片
+
+```svelte
+<Box
+  title="圆角卡片"
+  round
+  style="box-shadow: 0 2px 8px rgba(0,0,0,0.08);"
+  content$style="padding: 16px;"
+>
+  <p>这个卡片有圆角和柔和阴影。</p>
+</Box>
+```
+
+### 仪表盘小部件（header + 内容 + footer）
+
+```svelte
+<script>
+  import Box from '@ticatec/topside-elements/Box';
+</script>
+
+<Box round style="height: 100%;">
+  {#snippet header()}
+    <div style="display: flex; justify-content: space-between; align-items: center; padding: 8px 16px;">
+      <h3>销售概览</h3>
+      <select onchange={changeRange}>
+        <option value="this-month">本月</option>
+        <option value="last-month">上月</option>
+      </select>
+    </div>
+  {/snippet}
+
+  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px; padding: 16px;">
+    <div>
+      <div style="font-size: 24px; font-weight: bold;">¥12,345</div>
+      <div style="color: gray;">收入</div>
+    </div>
+    <div>
+      <div style="font-size: 24px; font-weight: bold;">89</div>
+      <div style="color: gray;">订单</div>
+    </div>
+  </div>
+
+  {#snippet footer()}
+    <a href="/reports/sales" style="padding: 8px 16px; display: inline-block;">
+      查看详细报告 →
+    </a>
+  {/snippet}
+</Box>
+```
+
+### 仅 footer（无 header）
+
+```svelte
+<Box content$style="padding: 16px;">
+  <p>有 footer 但无 header 的内容。</p>
+
+  {#snippet footer()}
+    <small style="padding: 8px 16px; color: #6b7280;">2 分钟前更新</small>
+  {/snippet}
+</Box>
+```
+
+## 通过 CSS 变量做主题化
+
+```css
+:root {
+  /* 外层 wrapper */
+  --topside-box-color-surface: #ffffff;        /* 内容背景 */
+  --topside-box-color-border:  #e5e7eb;        /* 1px 边框 */
+  --topside-primary-color-font: #374151;       /* 基础文字色 */
+  --topside-box-radius: 8px;                    /* 仅 round=true 时生效 */
+
+  /* header */
+  --topside-box-color-header-surface: #f9fafb;
+  --topside-box-color-header-title:   #374151;
+  --topside-box-header-padding: 12px 16px;
+  --topside-box-header-font-weight: 600;
+
+  /* footer */
+  --topside-box-color-footer-surface: #f9fafb;
+  --topside-box-color-footer-title:   #6b7280;
+  --topside-box-footer-font-weight: normal;
+}
+
+[data-theme='dark'] {
+  --topside-box-color-surface: #1f2937;
+  --topside-box-color-border:  #374151;
+  --topside-box-color-header-surface: #111827;
+  --topside-box-color-header-title:   #f9fafb;
+  --topside-box-color-footer-surface: #111827;
+  --topside-box-color-footer-title:   #9ca3af;
+}
+```
+
+## 行为说明
+
+- **到处都是 `overflow: hidden`**：外层 wrapper、`.box-header`、`.box-content`。长内容被裁剪，不滚动。需要滚动自己在 children 里加 `overflow: auto`
+- **title 单行**（`white-space: nowrap; text-overflow: ellipsis`）。长 title 显示 `…` 而不是换行
+- **header 和 footer 禁用文本选中**（`user-select: none`）—— 它们是标签/操作，不是可复制内容
+- **默认无阴影。** 传 `style="box-shadow: ..."` 走卡片视觉
+- **默认无内容 padding。** 用 `content$style="padding: ..."`，不影响 header/footer
+
+## 无障碍访问
+
+- 外层 wrapper 是普通 `<div>`，无 role。如果 Box 代表 landmark（如 `complementary` 侧边栏），自己加 `role="..."`
+- 想要真正的"卡片"语义，外面用 `<section>` 包一层，header snippet 里用 `aria-label` 或 heading 元素
+- 默认 `.title` div 里的文字不带 heading 标签 —— 搜索引擎和屏幕阅读器不会把它当标题。需要文档大纲时用 `header` snippet 配 `<h2>`/`<h3>`
+
+## 最佳实践
+
+1. **内容 padding 自己加**，用 `content$style="padding: ..."`。Box 故意不加，好让 header/footer 边缘与边框对齐
+2. **一旦需要图标、操作按钮或不同布局，就用 `header` snippet 替代 `title`** —— 反正 snippet 优先，显式更清楚
+3. **footer 留给操作**，不是额外内容 —— 它带 `user-select: none`，视觉上也有背景区分
+4. **需要滚动的内容**自己在 children 里包 `<div style="overflow: auto; height: 100%">`。Box 的 `overflow: hidden` 只裁不滚
+5. **卡片用 `round`，全宽面板不要**（圆角对邻居时显得奇怪）
+6. **长 title 默认 `…` 截断**。需要换行就用 `header` snippet 自己控制样式
+
+## 相关组件
+
+- [ActionBar](../action_bar/README_CN.md) —— 常放在 `footer` snippet 里
+- [AppTopBar](../app_top_bar/README_CN.md) —— app 外壳的顶栏对应物

package/dist/layouts/box/index.d.ts

@@ -0,0 +1,2 @@
+import Box from "./Box.svelte";
+export default Box;

package/dist/layouts/box/index.js

@@ -0,0 +1,2 @@
+import Box from "./Box.svelte";
+export default Box;

package/dist/layouts/criteria_field/CriteriaField.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+
+    import type {Snippet} from "svelte";
+
+    interface Props {
+        style?: string;
+        theme?: string;
+        label: string;
+        label$style?: string;
+        labelSuffix?: string;
+        children: Snippet;
+        size?: '' | 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40';
+    }
+
+    let {
+        style = '',
+        size = '',
+        theme,
+        label,
+        label$style,
+        labelSuffix = ':',
+        children
+    }: Props = $props();
+
+
+</script>
+<div class="topside-filter-field {size}" data-theme={theme} {style}>
+    <div class="field-container">
+        <div class="field-label" style={label$style}>
+            <span>{label}{labelSuffix}</span>
+        </div>
+        <div class="field">
+            {@render children()}
+        </div>
+    </div>
+</div>
+<style>.topside-filter-field {
+  box-sizing: border-box;
+  display: block;
+  position: relative;
+  padding: 0 4px;
+  width: 100px;
+}
+.topside-filter-field.x15 {
+  width: 150px;
+}
+.topside-filter-field.x20 {
+  width: 200px;
+}
+.topside-filter-field.x25 {
+  width: 250px;
+}
+.topside-filter-field.x30 {
+  width: 300px;
+}
+.topside-filter-field.x35 {
+  width: 350px;
+}
+.topside-filter-field.x40 {
+  width: 400px;
+}
+.topside-filter-field .field-container {
+  width: 100%;
+  display: grid;
+  position: relative;
+  gap: 4px;
+  grid-template-columns: 1fr;
+}
+.topside-filter-field .field-label {
+  color: var(--topside-criteria-field-label-color);
+  font-size: 0.9em;
+  font-weight: 500;
+  width: 100%;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.topside-filter-field .field {
+  position: relative;
+  display: flex;
+  flex-direction: row;
+  justify-items: center;
+  width: 100%;
+}
+
+.field-layout-horizontal .field-container {
+  grid-template-columns: auto 1fr;
+  align-items: center;
+  gap: 8px;
+}
+.field-layout-horizontal .field-label {
+  text-align: var(--topside-criteria-field-label-alignment);
+  width: var(--topside-criteria-field-label-width);
+  overflow: unset;
+  text-overflow: unset;
+  white-space: unset;
+}</style>

package/dist/layouts/criteria_field/CriteriaField.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Snippet } from "svelte";
+interface Props {
+    style?: string;
+    theme?: string;
+    label: string;
+    label$style?: string;
+    labelSuffix?: string;
+    children: Snippet;
+    size?: '' | 'x15' | 'x20' | 'x25' | 'x30' | 'x35' | 'x40';
+}
+declare const CriteriaField: import("svelte").Component<Props, {}, "">;
+type CriteriaField = ReturnType<typeof CriteriaField>;
+export default CriteriaField;