@ticatec/uniface-element 0.3.22 → 5.0.0

package/dist/layouts/box/README.md

@@ -0,0 +1,310 @@
+# Box Component
+
+A bordered flex-column container with optional header / footer. The structural building block for cards, panels, and dashboard widgets — Box itself is intentionally minimal (no shadow, no padding); you add visuals via `style` / `contentStyle` and CSS variables.
+
+## Features
+
+- **Header from `title` string OR `header` snippet** — snippet wins when both are set
+- **Optional `footer` snippet** — usually for action buttons
+- **Default children** fill the middle (`flex: 1 1 auto`, `overflow: hidden`)
+- **Optional rounded corners** via `round` prop (sets `border-radius: var(--uniface-box-radius)`)
+- **Outer wrapper clips overflow** — children can't spill out
+- **Per-section styling**: `style` on the outer wrapper, `contentStyle` on the content area only
+- **Theme hook**: `data-theme="{theme}"` on the outer wrapper
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```typescript
+import Box from '@ticatec/uniface-element/Box';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import Box from '@ticatec/uniface-element/Box';
+</script>
+
+<Box title="Card Title">
+  <p>This is the content area.</p>
+</Box>
+```
+
+> **Box has no built-in padding on the content area.** Wrap your content in its own padded container, or pass `contentStyle="padding: 16px;"`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | Title text rendered inside `.box-header > .title`. Ignored when `header` snippet is provided. Empty string → header block is not rendered (unless `header` snippet is set). |
+| `round` | `boolean` | `false` | Adds the `rounded` class → `border-radius: var(--uniface-box-radius)` |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper (`.uniface-box`) |
+| `contentStyle` | `string` | `''` | Inline CSS on the content area (`.box-content`). Use this for padding so the header/footer aren't affected. |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper for scoped CSS overrides |
+| `header` | `Snippet \| undefined` | `undefined` | Custom header content. **Overrides `title` when both are set.** |
+| `children` | `Snippet \| undefined` | `undefined` | Main content |
+| `footer` | `Snippet \| undefined` | `undefined` | Footer content (typically action buttons) |
+
+## Header Precedence
+
+The header block renders when **either** `title` is non-empty **or** `header` snippet is provided. If both are set, **the snippet wins** and `title` is ignored:
+
+```svelte
+<!-- ✅ Title only -->
+<Box title="Hello">...</Box>
+
+<!-- ✅ Header snippet only -->
+<Box>
+  {#snippet header()}<h3>Custom Header</h3>{/snippet}
+  ...
+</Box>
+
+<!-- ⚠️ Both: title is IGNORED, header snippet renders -->
+<Box title="Ignored">
+  {#snippet header()}<h3>Custom Header</h3>{/snippet}
+  ...
+</Box>
+```
+
+If you want the title AND extra content in the header, render the title yourself inside the snippet.
+
+## Layout
+
+```text
+┌──────────────────────────────────┐
+│ .box-header        (if title/header) │  ← user-select: none, ellipsis on title
+├──────────────────────────────────┤
+│ .box-content       (flex 1, overflow: hidden)
+│   {children}                         │  ← NO built-in padding — add via contentStyle
+├──────────────────────────────────┤
+│ .box-footer        (if footer)       │  ← flex row, user-select: none
+└──────────────────────────────────┘
+```
+
+Built-in styles:
+
+```css
+.uniface-box {
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  box-sizing: border-box;
+  overflow: hidden;                  /* children can't spill */
+  background-color: var(--uniface-box-color-surface);
+  border: 1px solid var(--uniface-box-color-border);
+  color: var(--uniface-primary-color-font);
+}
+
+.uniface-box.rounded { border-radius: var(--uniface-box-radius); }
+
+.box-header {
+  width: 100%;
+  background-color: var(--uniface-box-color-header-surface);
+  color: var(--uniface-box-color-header-title);
+  user-select: none;
+  overflow: hidden;
+}
+
+.box-header .title {
+  width: 100%;
+  padding: var(--uniface-box-header-padding);
+  white-space: nowrap;               /* single line */
+  text-overflow: ellipsis;           /* truncates with … */
+  font-weight: var(--uniface-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(--uniface-box-color-footer-surface);
+  color: var(--uniface-box-color-footer-title);
+  font-weight: var(--uniface-box-footer-font-weight, normal);
+}
+```
+
+## Examples
+
+### Title + Content
+
+```svelte
+<Box title="Information">
+  <p>This is some important information.</p>
+</Box>
+```
+
+### Title + Content + Footer (action buttons)
+
+```svelte
+<script>
+  import Box from '@ticatec/uniface-element/Box';
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+</script>
+
+<Box title="User Profile" contentStyle="padding: 16px;">
+  <p>User information and details</p>
+
+  {#snippet footer()}
+    <ActionBar
+      style="width: 100%; justify-content: flex-end; padding: 8px 12px;"
+      buttons={[
+        { label: 'Cancel', handler: cancel },
+        { label: 'Save',   type: 'primary', handler: save }
+      ]}
+    />
+  {/snippet}
+</Box>
+```
+
+### Custom Header (title + action button)
+
+```svelte
+<Box contentStyle="padding: 16px;">
+  {#snippet header()}
+    <div style="display: flex; justify-content: space-between; align-items: center; padding: 8px 16px;">
+      <h3>Sales Overview</h3>
+      <Button type="primary" label="Export" onclick={exportReport} />
+    </div>
+  {/snippet}
+
+  <!-- content -->
+  <p>...</p>
+</Box>
+```
+
+### Rounded Card with Shadow
+
+```svelte
+<Box
+  title="Rounded Card"
+  round
+  style="box-shadow: 0 2px 8px rgba(0,0,0,0.08);"
+  contentStyle="padding: 16px;"
+>
+  <p>This card has rounded corners and a soft shadow.</p>
+</Box>
+```
+
+### Dashboard Widget (header + content + footer)
+
+```svelte
+<script>
+  import Box from '@ticatec/uniface-element/Box';
+</script>
+
+<Box round style="height: 100%;">
+  {#snippet header()}
+    <div style="display: flex; justify-content: space-between; align-items: center; padding: 8px 16px;">
+      <h3>Sales Overview</h3>
+      <select onchange={changeRange}>
+        <option value="this-month">This Month</option>
+        <option value="last-month">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;">Revenue</div>
+    </div>
+    <div>
+      <div style="font-size: 24px; font-weight: bold;">89</div>
+      <div style="color: gray;">Orders</div>
+    </div>
+  </div>
+
+  {#snippet footer()}
+    <a href="/reports/sales" style="padding: 8px 16px; display: inline-block;">
+      View Detailed Report →
+    </a>
+  {/snippet}
+</Box>
+```
+
+### Footer-Only (no header)
+
+```svelte
+<Box contentStyle="padding: 16px;">
+  <p>Content with a footer but no header.</p>
+
+  {#snippet footer()}
+    <small style="padding: 8px 16px; color: #6b7280;">Last updated 2 mins ago</small>
+  {/snippet}
+</Box>
+```
+
+## Theming via CSS Variables
+
+```css
+:root {
+  /* Outer wrapper */
+  --uniface-box-color-surface: #ffffff;        /* content background */
+  --uniface-box-color-border:  #e5e7eb;        /* 1px border */
+  --uniface-primary-color-font: #374151;       /* base text color */
+  --uniface-box-radius: 8px;                    /* applied only when round=true */
+
+  /* Header */
+  --uniface-box-color-header-surface: #f9fafb;
+  --uniface-box-color-header-title:   #374151;
+  --uniface-box-header-padding: 12px 16px;
+  --uniface-box-header-font-weight: 600;
+
+  /* Footer */
+  --uniface-box-color-footer-surface: #f9fafb;
+  --uniface-box-color-footer-title:   #6b7280;
+  --uniface-box-footer-font-weight: normal;
+}
+
+[data-theme='dark'] {
+  --uniface-box-color-surface: #1f2937;
+  --uniface-box-color-border:  #374151;
+  --uniface-box-color-header-surface: #111827;
+  --uniface-box-color-header-title:   #f9fafb;
+  --uniface-box-color-footer-surface: #111827;
+  --uniface-box-color-footer-title:   #9ca3af;
+}
+```
+
+## Behavior Notes
+
+- **`overflow: hidden` is everywhere**: outer wrapper, `.box-header`, `.box-content`. Long content is clipped, not scrolled. Add your own `overflow: auto` inside children if you need scrolling.
+- **Title is single-line** (`white-space: nowrap; text-overflow: ellipsis`). Long titles show `…` instead of wrapping.
+- **Header & footer disable text selection** (`user-select: none`) — they're meant for labels/actions, not copyable content.
+- **No shadow by default.** Pass `style="box-shadow: ..."` for a card look.
+- **No content padding by default.** Use `contentStyle="padding: ..."` so the header/footer aren't affected.
+
+## Accessibility
+
+- The outer wrapper is a plain `<div>` with no role. If the Box represents a landmark (e.g. a `complementary` sidebar), add `role="..."` yourself.
+- For a true "card" semantic, consider wrapping with `<section>` and giving the header `aria-label` or using a heading element inside the `header` snippet.
+- Title text inside the default `.title` div is not heading-tagged — search engines and screen readers won't treat it as a heading. Use the `header` snippet with `<h2>`/`<h3>` for proper document outline.
+
+## Best Practices
+
+1. **Add your own content padding** via `contentStyle="padding: ..."`. Box intentionally doesn't pad so the header/footer edges can sit flush with the border.
+2. **Use `header` snippet over `title`** as soon as you need icons, action buttons, or a different layout — the snippet takes precedence anyway, so it's clearer.
+3. **Reserve the footer for actions**, not extra content — it has `user-select: none` and is visually separated by background.
+4. **For scrollable content**, wrap your content in its own `<div style="overflow: auto; height: 100%">`. Box's `overflow: hidden` will clip but won't scroll.
+5. **Use `round` for cards**, leave it off for full-width panels (where rounded corners look odd against neighbors).
+6. **Long titles will be truncated with `…`** by default. If you need them to wrap, use the `header` snippet with your own styling.
+
+## Related Components
+
+- [ActionBar](../action_bar/README.md) — often placed in the `footer` snippet
+- [AppTopBar](../app_top_bar/README.md) — top-bar counterpart for app shells

package/dist/layouts/box/README_CN.md

@@ -0,0 +1,310 @@
+# Box 容器组件
+
+带可选 header / footer 的边框 flex-column 容器。卡片、面板、仪表盘小部件的结构化基础积木 —— Box 本身故意做得很最小（无阴影、无 padding），视觉效果通过 `style` / `contentStyle` 和 CSS 变量叠加。
+
+## 功能特性
+
+- **header 可来自 `title` 字符串或 `header` snippet** —— 两者同时传时 snippet 优先
+- **可选 `footer` snippet** —— 通常放操作按钮
+- **默认 children 填充中间**（`flex: 1 1 auto`、`overflow: hidden`）
+- **可选圆角**通过 `round` prop（设置 `border-radius: var(--uniface-box-radius)`）
+- **外层 wrapper 裁剪溢出** —— 子内容不会溢出
+- **分区样式**：`style` 作用于外层，`contentStyle` 仅作用于内容区
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```typescript
+import Box from '@ticatec/uniface-element/Box';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import Box from '@ticatec/uniface-element/Box';
+</script>
+
+<Box title="卡片标题">
+  <p>这是内容区域。</p>
+</Box>
+```
+
+> **Box 的内容区不带 padding。** 自己用 padded 容器包内容，或者传 `contentStyle="padding: 16px;"`。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | 渲染在 `.box-header > .title` 里的标题文字。提供 `header` snippet 时被忽略。空字符串 → 不渲染 header 块（除非提供了 `header` snippet） |
+| `round` | `boolean` | `false` | 加 `rounded` 类 → `border-radius: var(--uniface-box-radius)` |
+| `style` | `string` | `''` | 外层 wrapper（`.uniface-box`）的内联 CSS |
+| `contentStyle` | `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，靠 contentStyle 加
+├──────────────────────────────────┤
+│ .box-footer        (footer 提供时)      │  ← flex row，user-select: none
+└──────────────────────────────────┘
+```
+
+内置样式：
+
+```css
+.uniface-box {
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  box-sizing: border-box;
+  overflow: hidden;                  /* 子内容不溢出 */
+  background-color: var(--uniface-box-color-surface);
+  border: 1px solid var(--uniface-box-color-border);
+  color: var(--uniface-primary-color-font);
+}
+
+.uniface-box.rounded { border-radius: var(--uniface-box-radius); }
+
+.box-header {
+  width: 100%;
+  background-color: var(--uniface-box-color-header-surface);
+  color: var(--uniface-box-color-header-title);
+  user-select: none;
+  overflow: hidden;
+}
+
+.box-header .title {
+  width: 100%;
+  padding: var(--uniface-box-header-padding);
+  white-space: nowrap;               /* 单行 */
+  text-overflow: ellipsis;           /* 溢出加 … */
+  font-weight: var(--uniface-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(--uniface-box-color-footer-surface);
+  color: var(--uniface-box-color-footer-title);
+  font-weight: var(--uniface-box-footer-font-weight, normal);
+}
+```
+
+## 示例
+
+### 标题 + 内容
+
+```svelte
+<Box title="信息">
+  <p>这是一些需要显示的重要信息。</p>
+</Box>
+```
+
+### 标题 + 内容 + 底部（操作按钮）
+
+```svelte
+<script>
+  import Box from '@ticatec/uniface-element/Box';
+  import ActionBar from '@ticatec/uniface-element/ActionBar';
+</script>
+
+<Box title="用户资料" contentStyle="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 contentStyle="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);"
+  contentStyle="padding: 16px;"
+>
+  <p>这个卡片有圆角和柔和阴影。</p>
+</Box>
+```
+
+### 仪表盘小部件（header + 内容 + footer）
+
+```svelte
+<script>
+  import Box from '@ticatec/uniface-element/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 contentStyle="padding: 16px;">
+  <p>有 footer 但无 header 的内容。</p>
+
+  {#snippet footer()}
+    <small style="padding: 8px 16px; color: #6b7280;">2 分钟前更新</small>
+  {/snippet}
+</Box>
+```
+
+## 通过 CSS 变量做主题化
+
+```css
+:root {
+  /* 外层 wrapper */
+  --uniface-box-color-surface: #ffffff;        /* 内容背景 */
+  --uniface-box-color-border:  #e5e7eb;        /* 1px 边框 */
+  --uniface-primary-color-font: #374151;       /* 基础文字色 */
+  --uniface-box-radius: 8px;                    /* 仅 round=true 时生效 */
+
+  /* header */
+  --uniface-box-color-header-surface: #f9fafb;
+  --uniface-box-color-header-title:   #374151;
+  --uniface-box-header-padding: 12px 16px;
+  --uniface-box-header-font-weight: 600;
+
+  /* footer */
+  --uniface-box-color-footer-surface: #f9fafb;
+  --uniface-box-color-footer-title:   #6b7280;
+  --uniface-box-footer-font-weight: normal;
+}
+
+[data-theme='dark'] {
+  --uniface-box-color-surface: #1f2937;
+  --uniface-box-color-border:  #374151;
+  --uniface-box-color-header-surface: #111827;
+  --uniface-box-color-header-title:   #f9fafb;
+  --uniface-box-color-footer-surface: #111827;
+  --uniface-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。** 用 `contentStyle="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 自己加**，用 `contentStyle="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 外壳的顶栏对应物