@ticatec/uniface-element 0.3.23 → 5.0.0

package/dist/app_layout/README.md

@@ -0,0 +1,314 @@
+# App Layout Components
+
+A collection of flexible layout components for building application interfaces with headers, sidebars, and resizable panels.
+
+All components target **Svelte 5** and use the snippet API (`{#snippet ...}` / `{@render ...}`). Default content is passed as `children` (the implicit body of the component).
+
+## Installation
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## Import
+
+```svelte
+<script lang="ts">
+  import {
+    SidebarLayout,
+    HeaderLayout,
+    ClassicLayout,
+    ColumnsLayout,
+    RowsLayout
+  } from '@ticatec/uniface-element/app-layout';
+</script>
+```
+
+> Each component is also available as a default export: `import SidebarLayout from '@ticatec/uniface-element/app-layout/SidebarLayout'`.
+
+## Components
+
+| Component | Structure |
+|-----------|-----------|
+| **SidebarLayout** | Sidebar on the left, header + content on the right |
+| **HeaderLayout** | Header on top, then sidebar + content below |
+| **ClassicLayout** | Header + left sidebar + content + optional right sidebar + optional status bar |
+| **ColumnsLayout** | Left + center + right horizontal panels |
+| **RowsLayout** | Top + center + bottom vertical panels |
+
+All layouts accept `*Resize` props and constraints; panels without a corresponding snippet are not rendered.
+
+---
+
+## SidebarLayout
+
+Optional resizable sidebar on the left, plus a header area and content area stacked vertically on the right.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sidebarResize` | `boolean` | `false` | Enable sidebar resizing |
+| `headerHeight` | `string` | `'48px'` | Height of the header area |
+| `sidebarWidth` | `string` | `'300px'` | Initial width of the sidebar |
+| `sidebarMaxWidth` | `string \| null` | `null` | Maximum sidebar width (only when `sidebarResize`) |
+| `sidebarMinWidth` | `string \| null` | `null` | Minimum sidebar width (only when `sidebarResize`) |
+
+### Snippets
+
+| Snippet | Required | Description |
+|---------|----------|-------------|
+| `sidebar` | no | Sidebar content (if omitted, no sidebar is rendered) |
+| `header` | no | Header content (if omitted, no header is rendered) |
+| `children` | no | Main content area |
+
+### Example
+
+```svelte
+<SidebarLayout
+  sidebarResize={true}
+  sidebarWidth="250px"
+  sidebarMinWidth="200px"
+  sidebarMaxWidth="400px"
+>
+  {#snippet sidebar()}
+    <!-- Navigation menu -->
+  {/snippet}
+
+  {#snippet header()}
+    <!-- Top bar content -->
+  {/snippet}
+
+  <!-- Main content (children) -->
+  <div>Main application content</div>
+</SidebarLayout>
+```
+
+---
+
+## HeaderLayout
+
+Header on top, with a sidebar + content area below the header.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `headerHeight` | `string` | `'48px'` | Height of the header |
+| `sidebarWidth` | `string` | `'300px'` | Width of the sidebar |
+| `sidebarResize` | `boolean` | `false` | Enable sidebar resizing |
+| `sidebarMaxWidth` | `string \| null` | `null` | Maximum sidebar width (only when `sidebarResize`) |
+| `sidebarMinWidth` | `string \| null` | `null` | Minimum sidebar width (only when `sidebarResize`) |
+
+### Snippets
+
+| Snippet | Required | Description |
+|---------|----------|-------------|
+| `header` | no | Header content (if omitted, no header is rendered) |
+| `sidebar` | no | Sidebar content (if omitted, no sidebar is rendered) |
+| `children` | no | Main content area |
+
+### Example
+
+```svelte
+<HeaderLayout headerHeight="60px" sidebarResize={true}>
+  {#snippet header()}
+    <!-- App header -->
+  {/snippet}
+
+  {#snippet sidebar()}
+    <!-- Side navigation -->
+  {/snippet}
+
+  <!-- Main content -->
+  <div>Page content</div>
+</HeaderLayout>
+```
+
+---
+
+## ClassicLayout
+
+Traditional desktop application layout: header, left sidebar, content area, optional right sidebar, optional status bar.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `headerHeight` | `string` | `'48px'` | Height of the header |
+| `sidebarWidth` | `string` | `'300px'` | Width of the left sidebar |
+| `statusHeight` | `string` | `'22px'` | Height of the status bar |
+| `rightBarWidth` | `string` | `'240px'` | Width of the right sidebar |
+| `sidebarResize` | `boolean` | `false` | Enable left sidebar resizing |
+| `sidebarMaxWidth` | `string \| null` | `null` | Maximum left sidebar width (only when `sidebarResize`) |
+| `sidebarMinWidth` | `string \| null` | `null` | Minimum left sidebar width (only when `sidebarResize`) |
+| `rightBarResize` | `boolean` | `false` | Enable right sidebar resizing |
+| `rightBarMaxWidth` | `string \| null` | `null` | Maximum right sidebar width (only when `rightBarResize`) |
+| `rightBarMinWidth` | `string \| null` | `null` | Minimum right sidebar width (only when `rightBarResize`) |
+
+### Snippets
+
+| Snippet | Required | Description |
+|---------|----------|-------------|
+| `header` | no | Header content |
+| `sidebar` | no | Left sidebar content |
+| `rightSidebar` | no | Right sidebar content (camelCase — not `right-sidebar`) |
+| `bottom` | no | Status bar content |
+| `children` | no | Main content area |
+
+### Example
+
+```svelte
+<ClassicLayout
+  sidebarResize={true}
+  rightBarResize={true}
+  statusHeight="24px"
+>
+  {#snippet header()}
+    <!-- Application header -->
+  {/snippet}
+
+  {#snippet sidebar()}
+    <!-- Left navigation -->
+  {/snippet}
+
+  {#snippet rightSidebar()}
+    <!-- Properties panel -->
+  {/snippet}
+
+  {#snippet bottom()}
+    <!-- Status bar -->
+  {/snippet}
+
+  <!-- Main workspace -->
+  <div>Editor or main content</div>
+</ClassicLayout>
+```
+
+---
+
+## ColumnsLayout
+
+Three-column horizontal layout: left + center + right. Center fills remaining space; left and right default to `25%` (or `50%` when only one side panel is provided).
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `string` | `'100%'` | Total layout width |
+| `height` | `string` | `'100%'` | Total layout height |
+| `leftWidth` | `string \| null` | `null` | Left column width (falls back to `25%` / `50%`) |
+| `rightWidth` | `string \| null` | `null` | Right column width (falls back to `25%` / `50%`) |
+| `leftMin` | `string \| null` | `null` | Left column min-width |
+| `leftMax` | `string \| null` | `null` | Left column max-width |
+| `rightMin` | `string \| null` | `null` | Right column min-width |
+| `rightMax` | `string \| null` | `null` | Right column max-width |
+| `leftResize` | `boolean` | `false` | Enable left column resizing |
+| `rightResize` | `boolean` | `false` | Enable right column resizing |
+
+### Snippets
+
+| Snippet | Required | Description |
+|---------|----------|-------------|
+| `left` | no | Left column content (if omitted, no left column is rendered) |
+| `right` | no | Right column content (if omitted, no right column is rendered) |
+| `children` | no | Center column content |
+
+### Example
+
+```svelte
+<ColumnsLayout
+  leftResize={true}
+  rightResize={true}
+  leftWidth="200px"
+  rightWidth="300px"
+  leftMin="150px"
+  rightMin="250px"
+>
+  {#snippet left()}
+    <!-- Left panel -->
+  {/snippet}
+
+  {#snippet right()}
+    <!-- Right panel -->
+  {/snippet}
+
+  <!-- Center content -->
+  <div>Main content area</div>
+</ColumnsLayout>
+```
+
+---
+
+## RowsLayout
+
+Three-row vertical layout: top + center + bottom. Center fills remaining space; top and bottom default to `25%` (or `50%` when only one outer panel is provided).
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `string` | `'100%'` | Total layout width |
+| `height` | `string` | `'100%'` | Total layout height |
+| `topHeight` | `string \| null` | `null` | Top row height (falls back to `25%` / `50%`) |
+| `bottomHeight` | `string \| null` | `null` | Bottom row height (falls back to `25%` / `50%`) |
+| `topMin` | `string \| null` | `null` | Top row min-height |
+| `topMax` | `string \| null` | `null` | Top row max-height |
+| `bottomMin` | `string \| null` | `null` | Bottom row min-height |
+| `bottomMax` | `string \| null` | `null` | Bottom row max-height |
+| `topResize` | `boolean` | `false` | Enable top row resizing |
+| `bottomResize` | `boolean` | `false` | Enable bottom row resizing |
+
+### Snippets
+
+| Snippet | Required | Description |
+|---------|----------|-------------|
+| `top` | no | Top row content (if omitted, no top row is rendered) |
+| `bottom` | no | Bottom row content (if omitted, no bottom row is rendered) |
+| `children` | no | Center row content |
+
+### Example
+
+```svelte
+<RowsLayout
+  topResize={true}
+  bottomResize={true}
+  topHeight="150px"
+  bottomHeight="100px"
+  topMin="100px"
+  bottomMin="80px"
+>
+  {#snippet top()}
+    <!-- Top panel -->
+  {/snippet}
+
+  {#snippet bottom()}
+    <!-- Bottom panel -->
+  {/snippet}
+
+  <!-- Center content -->
+  <div>Main content area</div>
+</RowsLayout>
+```
+
+---
+
+## Resizable Panels
+
+When `*Resize` is enabled, a split handle is rendered between the panel and the center area:
+
+- Drag the handle to resize.
+- Min/max constraints are honored when set.
+- SidebarLayout / HeaderLayout / ClassicLayout use **vertical** split handles (drag horizontally).
+- RowsLayout uses **horizontal** split handles (drag vertically).
+- ClassicLayout's right sidebar uses a reversed handle (anchored to the right).
+
+`min`/`max` props are only applied while the corresponding `*Resize` is `true`.
+
+## Best Practices
+
+1. **Pick the right layout** — match the component to your application structure.
+2. **Set constraints** — use `min`/`max` to prevent panels from collapsing or overgrowing.
+3. **Remember container height** — these layouts fill their parent; make sure the parent has an explicit height.
+4. **Snippets are conditional** — omit a snippet and the panel disappears entirely (no empty space).
+5. **Performance** — keep resizable panels light for smooth dragging.

package/dist/app_layout/README_CN.md

@@ -0,0 +1,321 @@
+# 应用布局组件
+
+一套灵活的布局组件，用于构建带有标题栏、侧边栏和可调整面板的应用程序界面。
+
+所有组件基于 **Svelte 5**，使用 snippet API（`{#snippet ...}` / `{@render ...}`）。默认内容通过 `children` snippet 传入（即组件标签内直接写的内容）。
+
+## 安装
+
+```bash
+npm install @ticatec/uniface-element
+```
+
+## 导入
+
+```svelte
+<script lang="ts">
+  import {
+    SidebarLayout,
+    HeaderLayout,
+    ClassicLayout,
+    ColumnsLayout,
+    RowsLayout
+  } from '@ticatec/uniface-element/app-layout';
+</script>
+```
+
+> 每个组件也支持默认导入：`import SidebarLayout from '@ticatec/uniface-element/app-layout/SidebarLayout'`。
+
+## 可用组件
+
+| 组件 | 结构 |
+|------|------|
+| **SidebarLayout** | 左侧侧边栏，右侧为标题 + 主内容 |
+| **HeaderLayout** | 顶部标题栏，下方为侧边栏 + 主内容 |
+| **ClassicLayout** | 标题栏 + 左侧边栏 + 主内容 + 可选右侧边栏 + 可选状态栏 |
+| **ColumnsLayout** | 左 + 中 + 右 三列水平布局 |
+| **RowsLayout** | 上 + 中 + 下 三行垂直布局 |
+
+所有布局都支持 `*Resize` 属性和 min/max 约束；未提供对应 snippet 的面板不会被渲染。
+
+---
+
+## SidebarLayout
+
+左侧可选可调整侧边栏，右侧上方为标题区域、下方为主内容区域。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `sidebarResize` | `boolean` | `false` | 启用侧边栏调整大小 |
+| `headerHeight` | `string` | `"48px"` | 标题区域高度 |
+| `sidebarWidth` | `string` | `"300px"` | 侧边栏初始宽度 |
+| `sidebarMaxWidth` | `string \| null` | `null` | 侧边栏最大宽度（仅当 `sidebarResize` 为真时生效） |
+| `sidebarMinWidth` | `string \| null` | `null` | 侧边栏最小宽度（仅当 `sidebarResize` 为真时生效） |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `sidebar` | 否 | 侧边栏内容（不提供则不渲染侧边栏） |
+| `header` | 否 | 标题区域内容（不提供则不渲染标题区域） |
+| `children` | 否 | 主内容区域 |
+
+### 示例
+
+```svelte
+<SidebarLayout
+  sidebarResize={true}
+  sidebarWidth="250px"
+  sidebarMinWidth="200px"
+  sidebarMaxWidth="400px"
+>
+  {#snippet sidebar()}
+    <!-- 导航菜单 -->
+  {/snippet}
+
+  {#snippet header()}
+    <!-- 顶部栏内容 -->
+  {/snippet}
+
+  <!-- 主内容（children） -->
+  <div>主应用程序内容</div>
+</SidebarLayout>
+```
+
+---
+
+## HeaderLayout
+
+顶部为标题栏，标题栏下方为侧边栏 + 主内容。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `headerHeight` | `string` | `"48px"` | 标题栏高度 |
+| `sidebarWidth` | `string` | `"300px"` | 侧边栏宽度 |
+| `sidebarResize` | `boolean` | `false` | 启用侧边栏调整大小 |
+| `sidebarMaxWidth` | `string \| null` | `null` | 侧边栏最大宽度（仅当 `sidebarResize` 为真时生效） |
+| `sidebarMinWidth` | `string \| null` | `null` | 侧边栏最小宽度（仅当 `sidebarResize` 为真时生效） |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `header` | 否 | 标题区域内容（不提供则不渲染标题区域） |
+| `sidebar` | 否 | 侧边栏区域内容（不提供则不渲染侧边栏） |
+| `children` | 否 | 主内容区域 |
+
+### 示例
+
+```svelte
+<HeaderLayout headerHeight="60px" sidebarResize={true}>
+  {#snippet header()}
+    <!-- 应用标题栏 -->
+  {/snippet}
+
+  {#snippet sidebar()}
+    <!-- 侧边导航 -->
+  {/snippet}
+
+  <!-- 主内容 -->
+  <div>页面内容</div>
+</HeaderLayout>
+```
+
+---
+
+## ClassicLayout
+
+传统桌面应用程序布局：标题栏、左侧边栏、主内容区，可选的右侧边栏和状态栏。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `headerHeight` | `string` | `"48px"` | 标题栏高度 |
+| `sidebarWidth` | `string` | `"300px"` | 左侧边栏宽度 |
+| `statusHeight` | `string` | `"22px"` | 状态栏高度 |
+| `rightBarWidth` | `string` | `"240px"` | 右侧边栏宽度 |
+| `sidebarResize` | `boolean` | `false` | 启用左侧边栏调整大小 |
+| `sidebarMaxWidth` | `string \| null` | `null` | 左侧边栏最大宽度（仅当 `sidebarResize` 为真时生效） |
+| `sidebarMinWidth` | `string \| null` | `null` | 左侧边栏最小宽度（仅当 `sidebarResize` 为真时生效） |
+| `rightBarResize` | `boolean` | `false` | 启用右侧边栏调整大小 |
+| `rightBarMaxWidth` | `string \| null` | `null` | 右侧边栏最大宽度（仅当 `rightBarResize` 为真时生效） |
+| `rightBarMinWidth` | `string \| null` | `null` | 右侧边栏最小宽度（仅当 `rightBarResize` 为真时生效） |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `header` | 否 | 标题栏内容 |
+| `sidebar` | 否 | 左侧边栏内容 |
+| `rightSidebar` | 否 | 右侧边栏内容（注意是驼峰 `rightSidebar`，不是 `right-sidebar`） |
+| `bottom` | 否 | 状态栏内容 |
+| `children` | 否 | 主内容区域 |
+
+### 示例
+
+```svelte
+<ClassicLayout
+  sidebarResize={true}
+  rightBarResize={true}
+  statusHeight="24px"
+>
+  {#snippet header()}
+    <!-- 应用程序标题栏 -->
+  {/snippet}
+
+  {#snippet sidebar()}
+    <!-- 左侧导航 -->
+  {/snippet}
+
+  {#snippet rightSidebar()}
+    <!-- 属性面板 -->
+  {/snippet}
+
+  {#snippet bottom()}
+    <!-- 状态栏 -->
+  {/snippet}
+
+  <!-- 主工作区 -->
+  <div>编辑器或主内容</div>
+</ClassicLayout>
+```
+
+---
+
+## ColumnsLayout
+
+三列水平布局：左 + 中 + 右。中间列填充剩余空间；左右列默认宽度为 `25%`（仅提供一侧时为 `50%`）。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | 布局总宽度 |
+| `height` | `string` | `"100%"` | 布局总高度 |
+| `leftWidth` | `string \| null` | `null` | 左列宽度（缺省回退到 `25%` / `50%`） |
+| `rightWidth` | `string \| null` | `null` | 右列宽度（缺省回退到 `25%` / `50%`） |
+| `leftMin` | `string \| null` | `null` | 左列最小宽度 |
+| `leftMax` | `string \| null` | `null` | 左列最大宽度 |
+| `rightMin` | `string \| null` | `null` | 右列最小宽度 |
+| `rightMax` | `string \| null` | `null` | 右列最大宽度 |
+| `leftResize` | `boolean` | `false` | 启用左列调整大小 |
+| `rightResize` | `boolean` | `false` | 启用右列调整大小 |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `left` | 否 | 左列内容（不提供则不渲染左列） |
+| `right` | 否 | 右列内容（不提供则不渲染右列） |
+| `children` | 否 | 中央列内容 |
+
+### 示例
+
+```svelte
+<ColumnsLayout
+  leftResize={true}
+  rightResize={true}
+  leftWidth="200px"
+  rightWidth="300px"
+  leftMin="150px"
+  rightMin="250px"
+>
+  {#snippet left()}
+    <!-- 左面板 -->
+  {/snippet}
+
+  {#snippet right()}
+    <!-- 右面板 -->
+  {/snippet}
+
+  <!-- 中央内容 -->
+  <div>主内容区域</div>
+</ColumnsLayout>
+```
+
+---
+
+## RowsLayout
+
+三行垂直布局：上 + 中 + 下。中间行填充剩余空间；上下行默认高度为 `25%`（仅提供一侧时为 `50%`）。
+
+### 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | 布局总宽度 |
+| `height` | `string` | `"100%"` | 布局总高度 |
+| `topHeight` | `string \| null` | `null` | 顶部行高度（缺省回退到 `25%` / `50%`） |
+| `bottomHeight` | `string \| null` | `null` | 底部行高度（缺省回退到 `25%` / `50%`） |
+| `topMin` | `string \| null` | `null` | 顶部行最小高度 |
+| `topMax` | `string \| null` | `null` | 顶部行最大高度 |
+| `bottomMin` | `string \| null` | `null` | 底部行最小高度 |
+| `bottomMax` | `string \| null` | `null` | 底部行最大高度 |
+| `topResize` | `boolean` | `false` | 启用顶部行调整大小 |
+| `bottomResize` | `boolean` | `false` | 启用底部行调整大小 |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `top` | 否 | 顶部行内容（不提供则不渲染顶部行） |
+| `bottom` | 否 | 底部行内容（不提供则不渲染底部行） |
+| `children` | 否 | 中央行内容 |
+
+### 示例
+
+```svelte
+<RowsLayout
+  topResize={true}
+  bottomResize={true}
+  topHeight="150px"
+  bottomHeight="100px"
+  topMin="100px"
+  bottomMin="80px"
+>
+  {#snippet top()}
+    <!-- 顶部面板 -->
+  {/snippet}
+
+  {#snippet bottom()}
+    <!-- 底部面板 -->
+  {/snippet}
+
+  <!-- 中央内容 -->
+  <div>主内容区域</div>
+</RowsLayout>
+```
+
+---
+
+## 可调整面板
+
+当 `*Resize` 启用时，面板与中央区域之间会渲染一个拖动手柄：
+
+- 拖动手柄即可调整面板大小
+- 遵守 min/max 宽度/高度约束
+- SidebarLayout / HeaderLayout / ClassicLayout 使用**竖向**手柄（水平拖动）
+- RowsLayout 使用**横向**手柄（垂直拖动）
+- ClassicLayout 右侧边栏使用反向手柄（锚定在右侧）
+
+`min` / `max` 属性仅在对应的 `*Resize` 为 `true` 时生效。
+
+## 最佳实践
+
+1. **选择正确的布局**：选择最适合您应用程序结构的布局组件
+2. **设置适当的约束**：使用 min/max 宽度/高度防止面板变得太小或太大
+3. **注意容器高度**：这些布局会填满父容器，确保父容器有明确的高度
+4. **Snippet 是条件渲染的**：不提供某个 snippet，对应面板就完全不渲染（不会留下空白）
+5. **性能**：最小化可调整面板中的内容以获得平滑的调整体验
+
+## 注意事项
+
+- 可调整面板功能需要支持拖放的浏览器
+- 在设置面板尺寸时考虑内容的最小可用空间
+- 布局组件需要明确的容器高度才能正常工作
+- 在移动设备上考虑禁用面板调整功能以提供更好的触摸体验