@ticatec/topside-elements 1.0.0

package/dist/app_layout/README_CN.md

@@ -0,0 +1,323 @@
+# 应用布局组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../docs/NAMING_CN.md) 中的名字；旧名 `bottomMax`, `bottomMin`, `leftMax`, `leftMin`, `rightMax`, `rightMin`, `topMax`, `topMin` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+一套灵活的布局组件，用于构建带有标题栏、侧边栏和可调整面板的应用程序界面。
+
+所有组件基于 **Svelte 5**，使用 snippet API（`{#snippet ...}` / `{@render ...}`）。默认内容通过 `children` snippet 传入（即组件标签内直接写的内容）。
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```svelte
+<script lang="ts">
+  import {
+    SidebarLayout,
+    HeaderLayout,
+    ClassicLayout,
+    ColumnsLayout,
+    RowsLayout
+  } from '@ticatec/topside-elements/app-layout';
+</script>
+```
+
+> 每个组件也支持默认导入：`import SidebarLayout from '@ticatec/topside-elements/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%`） |
+| `leftMinWidth` | `string \| null` | `null` | 左列最小宽度 |
+| `leftMaxWidth` | `string \| null` | `null` | 左列最大宽度 |
+| `rightMinWidth` | `string \| null` | `null` | 右列最小宽度 |
+| `rightMaxWidth` | `string \| null` | `null` | 右列最大宽度 |
+| `leftResize` | `boolean` | `false` | 启用左列调整大小 |
+| `rightResize` | `boolean` | `false` | 启用右列调整大小 |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `left` | 否 | 左列内容（不提供则不渲染左列） |
+| `right` | 否 | 右列内容（不提供则不渲染右列） |
+| `children` | 否 | 中央列内容 |
+
+### 示例
+
+```svelte
+<ColumnsLayout
+  leftResize={true}
+  rightResize={true}
+  leftWidth="200px"
+  rightWidth="300px"
+  leftMinWidth="150px"
+  rightMinWidth="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%`） |
+| `topMinHeight` | `string \| null` | `null` | 顶部行最小高度 |
+| `topMaxHeight` | `string \| null` | `null` | 顶部行最大高度 |
+| `bottomMinHeight` | `string \| null` | `null` | 底部行最小高度 |
+| `bottomMaxHeight` | `string \| null` | `null` | 底部行最大高度 |
+| `topResize` | `boolean` | `false` | 启用顶部行调整大小 |
+| `bottomResize` | `boolean` | `false` | 启用底部行调整大小 |
+
+### Snippets
+
+| Snippet | 必需 | 描述 |
+|---------|------|------|
+| `top` | 否 | 顶部行内容（不提供则不渲染顶部行） |
+| `bottom` | 否 | 底部行内容（不提供则不渲染底部行） |
+| `children` | 否 | 中央行内容 |
+
+### 示例
+
+```svelte
+<RowsLayout
+  topResize={true}
+  bottomResize={true}
+  topHeight="150px"
+  bottomHeight="100px"
+  topMinHeight="100px"
+  bottomMinHeight="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. **性能**：最小化可调整面板中的内容以获得平滑的调整体验
+
+## 注意事项
+
+- 可调整面板功能需要支持拖放的浏览器
+- 在设置面板尺寸时考虑内容的最小可用空间
+- 布局组件需要明确的容器高度才能正常工作
+- 在移动设备上考虑禁用面板调整功能以提供更好的触摸体验

package/dist/app_layout/RowsLayout.svelte

@@ -0,0 +1,95 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte';
+    import Split from "../general/split";
+
+    interface Props {
+        width?: string;
+        height?: string;
+        topHeight?: string | null;
+        bottomHeight?: string | null;
+        /** 上栏最小高度（CSS 长度） */
+        topMinHeight?: string | null;
+        /** 上栏最大高度（CSS 长度） */
+        topMaxHeight?: string | null;
+        /** 下栏最小高度（CSS 长度） */
+        bottomMinHeight?: string | null;
+        /** 下栏最大高度（CSS 长度） */
+        bottomMaxHeight?: string | null;
+        topResize?: boolean;
+        bottomResize?: boolean;
+        top?: Snippet;
+        children?: Snippet;
+        bottom?: Snippet;
+    }
+
+    let {
+        width = '100%',
+        height = '100%',
+        topHeight = null,
+        bottomHeight = null,
+        topMinHeight = null,
+        topMaxHeight = null,
+        bottomMinHeight = null,
+        bottomMaxHeight = null,
+        topResize = false,
+        bottomResize = false,
+        top,
+        children,
+        bottom
+    }: Props = $props();
+
+    let topPanel = $state<HTMLElement>();
+    let bottomPanel = $state<HTMLElement>();
+
+    let rowHeight = $derived(bottom ? '25%' : '50%');
+
+    const generateStyle = (attr: string, v: string | null): string => {
+        return v ? `${attr}: ${v};` : ''
+    }
+
+    let topStyle = $derived(`${generateStyle('min-height', topMinHeight)} ${generateStyle('max-height', topMaxHeight)} ${generateStyle('height', topHeight ?? rowHeight)}`);
+    let bottomStyle = $derived(`${generateStyle('min-height', bottomMinHeight)} ${generateStyle('max-height', bottomMaxHeight)} ${generateStyle('height', bottomHeight ?? rowHeight)}`);
+</script>
+
+<div class="topside-rows-layout" style="width: {width}; height: {height}">
+    <div bind:this={topPanel} class="top-panel" style={topStyle}>
+        {#if top}
+            {@render top()}
+        {/if}
+    </div>
+    {#if topResize}
+        <Split bindingPanel={topPanel} direction="horizontal"/>
+    {/if}
+    <div class="center-panel">
+        {#if children}
+            {@render children()}
+        {/if}
+    </div>
+    {#if bottom}
+        {#if bottomResize}
+            <Split bindingPanel={bottomPanel} reverse direction="horizontal"/>
+        {/if}
+        <div bind:this={bottomPanel} class="bottom-panel" style={bottomStyle}>
+            {@render bottom()}
+        </div>
+    {/if}
+</div>
+
+<style>
+    .topside-rows-layout {
+        display: flex;
+        flex-direction: column;
+        flex-wrap: nowrap;
+    }
+
+    .top-panel,
+    .bottom-panel {
+        flex: 0 0 auto;
+        overflow: auto;
+    }
+
+    .center-panel {
+        flex: 1 1 auto;
+        overflow: auto;
+    }
+</style>

package/dist/app_layout/RowsLayout.svelte.d.ts

@@ -0,0 +1,23 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    width?: string;
+    height?: string;
+    topHeight?: string | null;
+    bottomHeight?: string | null;
+    /** 上栏最小高度（CSS 长度） */
+    topMinHeight?: string | null;
+    /** 上栏最大高度（CSS 长度） */
+    topMaxHeight?: string | null;
+    /** 下栏最小高度（CSS 长度） */
+    bottomMinHeight?: string | null;
+    /** 下栏最大高度（CSS 长度） */
+    bottomMaxHeight?: string | null;
+    topResize?: boolean;
+    bottomResize?: boolean;
+    top?: Snippet;
+    children?: Snippet;
+    bottom?: Snippet;
+}
+declare const RowsLayout: import("svelte").Component<Props, {}, "">;
+type RowsLayout = ReturnType<typeof RowsLayout>;
+export default RowsLayout;

package/dist/app_layout/SidebarLayout.svelte

@@ -0,0 +1,93 @@
+<script lang="ts">
+    import type { Snippet } from 'svelte';
+    import Split from "../general/split";
+
+    interface Props {
+        sidebarResize?: boolean;
+        headerHeight?: string;
+        sidebarWidth?: string;
+        sidebarMaxWidth?: string | null;
+        sidebarMinWidth?: string | null;
+        sidebar?: Snippet;
+        header?: Snippet;
+        children?: Snippet;
+    }
+
+    let {
+        sidebarResize = false,
+        headerHeight = "48px",
+        sidebarWidth = '300px',
+        sidebarMaxWidth = null,
+        sidebarMinWidth = null,
+        sidebar,
+        header,
+        children
+    }: Props = $props();
+
+    let sidebarPanel = $state<HTMLElement>();
+    let maxWidth = $derived(sidebarResize && sidebarMaxWidth ? `max-width: ${sidebarMaxWidth};` : '');
+    let minWidth = $derived(sidebarResize && sidebarMinWidth ? `min-width: ${sidebarMinWidth};` : '');
+</script>
+
+<div class="topside-sidebar-layout">
+    {#if sidebar}
+        <div bind:this={sidebarPanel} class="sidebar" style="width: {sidebarWidth}; {maxWidth} {minWidth}">
+            {#if sidebar}
+                {@render sidebar()}
+            {/if}
+        </div>
+        {#if sidebarResize}
+            <Split direction="vertical" bindingPanel={sidebarPanel}/>
+        {/if}
+    {/if}
+    <div class="main-content">
+        {#if header}
+            <div class="header-area" style="height: {headerHeight}">
+                {@render header()}
+            </div>
+        {/if}
+        <div class="content-area">
+            {#if children}
+                {@render children()}
+            {/if}
+        </div>
+    </div>
+</div>
+
+<style>
+    .topside-sidebar-layout {
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        display: flex;
+        flex-direction: row;
+        gap: var(--topside-spacing-2);
+    }
+
+    .sidebar {
+        height: 100%;
+        flex: 0 0 auto;
+        overflow: auto;
+        border-right: 1px solid var(--topside-color-border-secondary);
+    }
+
+    .main-content {
+        height: 100%;
+        flex: 1 1 auto;
+        overflow: hidden;
+        display: flex;
+        flex-direction: column;
+    }
+
+    .header-area {
+        width: 100%;
+        flex: 0 0 auto;
+        overflow: auto;
+    }
+
+    .content-area {
+        width: 100%;
+        flex: 1 1 auto;
+        overflow: auto;
+    }
+</style>

package/dist/app_layout/SidebarLayout.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    sidebarResize?: boolean;
+    headerHeight?: string;
+    sidebarWidth?: string;
+    sidebarMaxWidth?: string | null;
+    sidebarMinWidth?: string | null;
+    sidebar?: Snippet;
+    header?: Snippet;
+    children?: Snippet;
+}
+declare const SidebarLayout: import("svelte").Component<Props, {}, "">;
+type SidebarLayout = ReturnType<typeof SidebarLayout>;
+export default SidebarLayout;

package/dist/app_layout/index.d.ts

@@ -0,0 +1,6 @@
+import SidebarLayout from "./SidebarLayout.svelte";
+import HeaderLayout from "./HeaderLayout.svelte";
+import ClassicLayout from "./ClassicLayout.svelte";
+import ColumnsLayout from "./ColumnsLayout.svelte";
+import RowsLayout from "./RowsLayout.svelte";
+export { SidebarLayout, HeaderLayout, ClassicLayout, ColumnsLayout, RowsLayout };

package/dist/app_layout/index.js

@@ -0,0 +1,6 @@
+import SidebarLayout from "./SidebarLayout.svelte";
+import HeaderLayout from "./HeaderLayout.svelte";
+import ClassicLayout from "./ClassicLayout.svelte";
+import ColumnsLayout from "./ColumnsLayout.svelte";
+import RowsLayout from "./RowsLayout.svelte";
+export { SidebarLayout, HeaderLayout, ClassicLayout, ColumnsLayout, RowsLayout };