@ticatec/uniface-element 0.2.3 → 0.3.0

package/dist/action-bar/README_CN.md

@@ -0,0 +1,285 @@
+# ActionBar 组件
+
+一个灵活的操作栏组件，用于组织和显示操作按钮，支持可选的分隔符。
+
+## 功能特性
+
+- **按钮组织**: 在水平布局中显示多个操作按钮
+- **灵活配置**: 通过数据定义按钮或使用插槽内容
+- **分隔符**: 使用`null`值在按钮组之间添加视觉分隔符
+- **可定制样式**: 控制间距和应用自定义样式
+- **按钮类型**: 支持所有按钮类型（主要、次要、危险等）
+- **图标支持**: 在按钮标签旁显示图标
+- **禁用状态**: 单个按钮禁用功能
+- **响应式**: 适应容器宽度
+
+## 基本用法
+
+```svelte
+<script>
+import ActionBar, { type ButtonAction } from '@ticatec/uniface-element/ActionBar';
+
+const actions: ButtonAction[] = [
+  {
+    label: '保存',
+    type: 'primary',
+    icon: 'icon_google_save',
+    handler: () => console.log('保存被点击')
+  },
+  {
+    label: '取消',
+    type: 'secondary',
+    handler: () => console.log('取消被点击')
+  }
+];
+</script>
+
+<ActionBar buttons={actions} />
+```
+
+## 属性参数
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `buttons` | `ButtonActions` | `[]` | 按钮操作数组或null表示分隔符 |
+| `style` | `string` | `''` | 操作栏的自定义CSS样式 |
+| `gap` | `number` | `8` | 按钮间距（像素） |
+
+## ButtonAction 接口
+
+```typescript
+interface ButtonAction {
+  label: string;           // 按钮文本
+  disabled?: boolean;      // 按钮是否禁用
+  icon?: string;          // 图标类名（可选）
+  type?: ButtonType;      // 按钮样式类型
+  handler?: MouseClickHandler; // 点击事件处理器
+}
+
+type ButtonActions = Array<ButtonAction | null>;
+```
+
+## ButtonType 选项
+
+组件支持所有标准按钮类型：
+- `'primary'` - 主要操作按钮
+- `'secondary'` - 次要操作按钮
+- `'danger'` - 危险/删除操作按钮
+- `'success'` - 成功/确认按钮
+- `'warning'` - 警告按钮
+- `'info'` - 信息按钮
+
+## 使用示例
+
+### 基础操作栏
+
+```svelte
+<script>
+const basicActions = [
+  { label: '新建', handler: createNew },
+  { label: '编辑', handler: editItem },
+  { label: '删除', type: 'danger', handler: deleteItem }
+];
+</script>
+
+<ActionBar buttons={basicActions} />
+```
+
+### 带图标
+
+```svelte
+<script>
+const iconActions = [
+  { 
+    label: '保存', 
+    icon: 'icon_google_save',
+    type: 'primary',
+    handler: save 
+  },
+  { 
+    label: '打印', 
+    icon: 'icon_google_print',
+    handler: print 
+  }
+];
+</script>
+
+<ActionBar buttons={iconActions} />
+```
+
+### 带分隔符
+
+```svelte
+<script>
+const actionsWithSeparators = [
+  { label: '复制', handler: copy },
+  { label: '粘贴', handler: paste },
+  null, // 分隔符
+  { label: '删除', type: 'danger', handler: remove }
+];
+</script>
+
+<ActionBar buttons={actionsWithSeparators} />
+```
+
+### 自定义间距
+
+```svelte
+<ActionBar 
+  buttons={actions}
+  gap={16}
+  style="padding: 12px; background: #f5f5f5;"
+/>
+```
+
+### 使用插槽内容
+
+```svelte
+<ActionBar>
+  <Button label="自定义" type="primary" />
+  <Button label="操作" type="secondary" />
+</ActionBar>
+```
+
+## 动态操作
+
+```svelte
+<script>
+let isEditing = false;
+
+$: actions = isEditing ? [
+  { label: '保存', type: 'primary', handler: save },
+  { label: '取消', handler: cancel }
+] : [
+  { label: '编辑', handler: startEdit },
+  { label: '删除', type: 'danger', handler: remove }
+];
+</script>
+
+<ActionBar buttons={actions} />
+```
+
+## 条件按钮
+
+```svelte
+<script>
+let hasPermission = true;
+let isLoading = false;
+
+$: actions = [
+  { label: '刷新', handler: refresh },
+  hasPermission ? { 
+    label: '保存', 
+    type: 'primary',
+    disabled: isLoading,
+    handler: save 
+  } : null,
+  hasPermission ? { 
+    label: '删除', 
+    type: 'danger',
+    disabled: isLoading,
+    handler: remove 
+  } : null
+].filter(Boolean); // 移除null值
+</script>
+
+<ActionBar buttons={actions} />
+```
+
+## 行为特性
+
+### 按钮渲染
+- 按钮使用内部Button组件渲染
+- 每个按钮接收配置的标签、图标、类型和禁用状态
+- 点击处理器自动绑定到按钮事件
+
+### 分隔符
+- 在按钮数组中使用`null`值插入视觉分隔符
+- 分隔符显示为24px高度的垂直线
+- 用于分组相关操作
+
+### 回退内容
+- 如果没有提供按钮或数组为空，显示插槽内容
+- 允许完全自定义的操作栏布局
+
+## 样式定制
+
+组件使用以下CSS类：
+
+- `.uniface-action-bar` - 主容器，使用flexbox布局
+
+### CSS变量
+
+您可以使用CSS自定义外观：
+
+```css
+.uniface-action-bar {
+  /* 自定义样式 */
+  background: #ffffff;
+  border: 1px solid #e0e0e0;
+  border-radius: 4px;
+  padding: 8px;
+}
+```
+
+## 无障碍访问
+
+- 使用语义化按钮元素以支持正确的键盘导航
+- 禁用按钮正确标记且不可交互
+- 焦点管理遵循标准按钮行为
+- 屏幕阅读器可以正确识别操作按钮
+
+## 常见用例
+
+### 工具栏操作
+
+```svelte
+<ActionBar buttons={[
+  { label: '新建', icon: 'icon_google_add' },
+  { label: '打开', icon: 'icon_google_folder_open' },
+  { label: '保存', icon: 'icon_google_save' },
+  null,
+  { label: '剪切', icon: 'icon_google_content_cut' },
+  { label: '复制', icon: 'icon_google_content_copy' },
+  { label: '粘贴', icon: 'icon_google_content_paste' }
+]} />
+```
+
+### 表单操作
+
+```svelte
+<ActionBar 
+  buttons={[
+    { label: '保存', type: 'primary', handler: submit },
+    { label: '取消', handler: cancel }
+  ]}
+  style="justify-content: flex-end; margin-top: 16px;"
+/>
+```
+
+### CRUD操作
+
+```svelte
+<ActionBar buttons={[
+  { label: '创建', type: 'primary', handler: create },
+  { label: '编辑', handler: edit },
+  { label: '删除', type: 'danger', handler: remove },
+  null,
+  { label: '刷新', handler: refresh }
+]} />
+```
+
+## 最佳实践
+
+1. **分组相关操作**: 使用分隔符分组相关功能
+2. **一致的图标**: 在整个应用程序中使用一致的图标样式
+3. **按钮类型**: 使用适当的按钮类型（主要操作用primary，危险操作用danger）
+4. **禁用状态**: 在操作不可用或加载期间禁用按钮
+5. **响应式设计**: 考虑移动设备的按钮标签和间距
+
+## 注意事项
+
+- 按钮数组中的`null`值会自动渲染为分隔符
+- 如果按钮数组为空，组件会显示插槽内容
+- 所有按钮共享相同的间距设置
+- 图标需要在项目中正确引入相应的图标库

package/dist/app-layout/README.md

@@ -0,0 +1,374 @@
+# App Layout Components
+
+A collection of flexible layout components for building application interfaces with headers, sidebars, and resizable panels.
+
+## Available Components
+
+- **SidebarLayout** - Layout with optional sidebar and header
+- **HeaderLayout** - Layout with header and optional sidebar below
+- **ClassicLayout** - Traditional application layout with header, sidebars, and status bar
+- **ColumnsLayout** - Flexible column-based layout with resizable panels
+- **RowsLayout** - Flexible row-based layout with resizable panels
+
+## Import
+
+```svelte
+<script>
+// Import individual layouts
+import { SidebarLayout } from '@ticatec/uniface-element/app-layout';
+import HeaderLayout from '@ticatec/uniface-element/app-layout/HeaderLayout';
+import ClassicLayout from '@ticatec/uniface-element/app-layout/ClassicLayout';
+import ColumnsLayout from '@ticatec/uniface-element/app-layout/ColumnsLayout';
+import RowsLayout from '@ticatec/uniface-element/app-layout/RowsLayout';
+</script>
+```
+
+## SidebarLayout
+
+A layout with an optional resizable sidebar on the left and header area.
+
+### 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 |
+| `sidebarMinWidth` | `string \| null` | `null` | Minimum sidebar width |
+
+### Slots
+
+- `sidebar` - Content for the sidebar area
+- `header` - Content for the header area
+- `default` - Main content area
+
+### Example
+
+```svelte
+<SidebarLayout 
+  sidebarResize={true}
+  sidebarWidth="250px"
+  sidebarMinWidth="200px"
+  sidebarMaxWidth="400px"
+>
+  <div slot="sidebar">
+    <!-- Navigation menu -->
+  </div>
+  
+  <div slot="header">
+    <!-- Top bar content -->
+  </div>
+  
+  <!-- Main content -->
+  <div>Main application content</div>
+</SidebarLayout>
+```
+
+## HeaderLayout
+
+A layout with a header at the top and optional sidebar 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 |
+| `sidebarMinWidth` | `string \| null` | `null` | Minimum sidebar width |
+
+### Slots
+
+- `header` - Content for the header area
+- `sidebar` - Content for the sidebar area
+- `default` - Main content area
+
+### Example
+
+```svelte
+<HeaderLayout headerHeight="60px" sidebarResize={true}>
+  <div slot="header">
+    <!-- App header -->
+  </div>
+  
+  <div slot="sidebar">
+    <!-- Side navigation -->
+  </div>
+  
+  <!-- Main content -->
+  <div>Page content</div>
+</HeaderLayout>
+```
+
+## ClassicLayout
+
+A traditional desktop application layout with header, left sidebar, optional right sidebar, and 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 |
+| `sidebarMinWidth` | `string \| null` | `null` | Minimum left sidebar width |
+| `rightBarResize` | `boolean` | `false` | Enable right sidebar resizing |
+| `rightBarMaxWidth` | `string \| null` | `null` | Maximum right sidebar width |
+| `rightBarMinWidth` | `string \| null` | `null` | Minimum right sidebar width |
+
+### Slots
+
+- `header` - Header content
+- `sidebar` - Left sidebar content
+- `right-sidebar` - Right sidebar content
+- `bottom` - Status bar content
+- `default` - Main content area
+
+### Example
+
+```svelte
+<ClassicLayout 
+  sidebarResize={true}
+  rightBarResize={true}
+  statusHeight="24px"
+>
+  <div slot="header">
+    <!-- Application header -->
+  </div>
+  
+  <div slot="sidebar">
+    <!-- Left navigation -->
+  </div>
+  
+  <div slot="right-sidebar">
+    <!-- Properties panel -->
+  </div>
+  
+  <div slot="bottom">
+    <!-- Status bar -->
+  </div>
+  
+  <!-- Main workspace -->
+  <div>Editor or main content</div>
+</ClassicLayout>
+```
+
+## ColumnsLayout
+
+A flexible column-based layout with resizable left and right panels.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | Total width of the layout |
+| `height` | `string` | `"100%"` | Total height of the layout |
+| `leftWidth` | `string \| null` | `null` | Width of the left column |
+| `rightWidth` | `string \| null` | `null` | Width of the right column |
+| `leftMin` | `string \| null` | `null` | Minimum width of left column |
+| `leftMax` | `string \| null` | `null` | Maximum width of left column |
+| `rightMin` | `string \| null` | `null` | Minimum width of right column |
+| `rightMax` | `string \| null` | `null` | Maximum width of right column |
+| `leftResize` | `boolean` | `false` | Enable left column resizing |
+| `rightResize` | `boolean` | `false` | Enable right column resizing |
+
+### Slots
+
+- `left` - Left column content
+- `right` - Right column content
+- `default` - Center column content
+
+### Example
+
+```svelte
+<ColumnsLayout 
+  leftResize={true}
+  rightResize={true}
+  leftWidth="200px"
+  rightWidth="300px"
+  leftMin="150px"
+  rightMin="250px"
+>
+  <div slot="left">
+    <!-- Left panel -->
+  </div>
+  
+  <div slot="right">
+    <!-- Right panel -->
+  </div>
+  
+  <!-- Center content -->
+  <div>Main content area</div>
+</ColumnsLayout>
+```
+
+## RowsLayout
+
+A flexible row-based layout with resizable top and bottom panels.
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `width` | `string` | `"100%"` | Total width of the layout |
+| `height` | `string` | `"100%"` | Total height of the layout |
+| `topHeight` | `string \| null` | `null` | Height of the top row |
+| `bottomHeight` | `string \| null` | `null` | Height of the bottom row |
+| `topMin` | `string \| null` | `null` | Minimum height of top row |
+| `topMax` | `string \| null` | `null` | Maximum height of top row |
+| `bottomMin` | `string \| null` | `null` | Minimum height of bottom row |
+| `bottomMax` | `string \| null` | `null` | Maximum height of bottom row |
+| `topResize` | `boolean` | `false` | Enable top row resizing |
+| `bottomResize` | `boolean` | `false` | Enable bottom row resizing |
+
+### Slots
+
+- `top` - Top row content
+- `bottom` - Bottom row content
+- `default` - Center row content
+
+### Example
+
+```svelte
+<RowsLayout 
+  topResize={true}
+  bottomResize={true}
+  topHeight="150px"
+  bottomHeight="100px"
+  topMin="100px"
+  bottomMin="80px"
+>
+  <div slot="top">
+    <!-- Top panel -->
+  </div>
+  
+  <div slot="bottom">
+    <!-- Bottom panel -->
+  </div>
+  
+  <!-- Center content -->
+  <div>Main content area</div>
+</RowsLayout>
+```
+
+## Features
+
+### Resizable Panels
+All layout components support resizable panels when enabled:
+- Drag the split handles to resize panels
+- Respect minimum and maximum width/height constraints
+- Smooth resizing with visual feedback
+
+### Responsive Design
+- Layouts adapt to container dimensions
+- Flexible sizing with percentage and fixed units
+- Overflow handling for content areas
+
+### Slot-based Content
+- Use named slots for different layout areas
+- Optional slots are hidden when no content is provided
+- Default slot for main content area
+
+## Common Patterns
+
+### Application Shell
+
+```svelte
+<ClassicLayout sidebarResize={true}>
+  <div slot="header" class="app-header">
+    <h1>My Application</h1>
+    <!-- Navigation, user menu, etc. -->
+  </div>
+  
+  <div slot="sidebar" class="navigation">
+    <!-- Menu items -->
+  </div>
+  
+  <div slot="bottom" class="status-bar">
+    <!-- Status information -->
+  </div>
+  
+  <main class="main-content">
+    <!-- Page content -->
+  </main>
+</ClassicLayout>
+```
+
+### Dashboard Layout
+
+```svelte
+<ColumnsLayout leftResize={true} rightResize={true}>
+  <div slot="left" class="sidebar">
+    <!-- Filters, navigation -->
+  </div>
+  
+  <div slot="right" class="details-panel">
+    <!-- Item details, actions -->
+  </div>
+  
+  <div class="dashboard-grid">
+    <!-- Main dashboard content -->
+  </div>
+</ColumnsLayout>
+```
+
+### Split View Editor
+
+```svelte
+<RowsLayout topResize={true} bottomResize={true}>
+  <div slot="top" class="editor-area">
+    <!-- Code editor -->
+  </div>
+  
+  <div slot="bottom" class="output-panel">
+    <!-- Console, preview, etc. -->
+  </div>
+  
+  <div class="file-explorer">
+    <!-- File tree, tabs -->
+  </div>
+</RowsLayout>
+```
+
+## Styling
+
+All layout components use flexbox for positioning and include:
+
+- Proper overflow handling
+- Border styling with CSS custom properties
+- Gap spacing between panels
+- Box-sizing: border-box for predictable sizing
+
+### CSS Custom Properties
+
+```css
+:root {
+  --uniface-plain-border-color: #f0f0f0;
+}
+```
+
+## Accessibility
+
+- Proper semantic structure with container elements
+- Keyboard navigation support through resizable splits
+- Focus management during panel resizing
+- Screen reader friendly layout structure
+
+## Browser Support
+
+- Modern browsers with flexbox support
+- CSS custom properties support
+- Drag and drop for resizing functionality
+
+## Best Practices
+
+1. **Choose the Right Layout**: Select the layout component that best fits your application structure
+2. **Set Appropriate Constraints**: Use min/max width/height to prevent panels from becoming too small or large
+3. **Consider Mobile**: Layouts may need responsive adjustments for mobile devices
+4. **Content Overflow**: Ensure content areas have appropriate overflow handling
+5. **Performance**: Minimize content in resizable panels for smooth resizing experience