@ticatec/topside-elements 1.0.0

package/dist/navigation/nav_menu/README.md

@@ -0,0 +1,224 @@
+# NavigatorMenu Component
+
+> **Renamed in 5.1.0**: this document uses the names from the [API Naming Guide](../../../docs/NAMING.md); the old names `menuItems` were removed in 5.1.0 (no compatibility aliases are kept).
+
+A hierarchical navigation menu component built with Svelte 5, supporting nested menu items with expand/collapse functionality.
+
+## Features
+
+- **Hierarchical Structure**: Support for multi-level nested menu items
+- **Expand/Collapse**: Click to expand or collapse menu sections
+- **Smooth Animations**: Slide transition for sub-menus
+- **Customizable**: Flexible text field configuration
+- **Click Handling**: Event callback for menu item selection
+- **CSS Variables**: Themeable with CSS variables
+- **Recursive Rendering**: Automatically handles nested menu structures
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+```typescript
+import { NavigatorMenu } from '@ticatec/topside-elements/NavigatorMenu';
+import type MenuItem from '@ticatec/topside-elements/MenuItem';
+```
+
+Or if using within the same project:
+```typescript
+import { NavigatorMenu } from '$lib/nav-menu';
+import type MenuItem from '$lib/nav-menu/MenuItem';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  let items = $state([
+    {
+      item: { label: 'Dashboard', path: '/dashboard' },
+      children: []
+    },
+    {
+      item: { label: 'Projects', path: '/projects' },
+      children: [
+        { item: { label: 'Active Projects', path: '/projects/active' } },
+        { item: { label: 'Archived', path: '/projects/archived' } }
+      ]
+    }
+  ]);
+
+  function handleMenuClick(item) {
+    console.log('Clicked:', item);
+  }
+</script>
+
+<NavigatorMenu
+  items={items}
+  textField="label"
+  onItemClick={handleMenuClick}
+/>
+```
+
+## Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `items` | `Array<MenuItem>` | Yes | Array of menu item objects |
+| `textField` | `string \| GetText<MenuItem>` | Yes | Field name or function to get display text |
+| `onItemClick` | `(item: MenuItem) => void` | Yes | Callback when a menu item is clicked |
+| `style` | `string` | No | Custom inline styles |
+
+## MenuItem Structure
+
+```typescript
+interface MenuItem {
+  item: {
+    [key: string]: any;  // Your data object
+    label?: string;      // Display text (if using string textField)
+  };
+  children?: MenuItem[];  // Nested menu items
+  expand?: boolean;      // Initial expanded state
+}
+```
+
+## Examples
+
+### Simple Menu
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const simpleMenu = [
+    { item: { name: 'Home', icon: 'home' } },
+    { item: { name: 'About', icon: 'info' } },
+    { item: { name: 'Contact', icon: 'mail' } }
+  ];
+</script>
+
+<NavigatorMenu
+  items={simpleMenu}
+  textField="name"
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+### Nested Menu
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const nestedMenu = [
+    {
+      item: { title: 'Products' },
+      expand: true,
+      children: [
+        { item: { title: 'Electronics', category: 'electronics' } },
+        { item: { title: 'Clothing', category: 'clothing' } },
+        {
+          item: { title: 'More' },
+          children: [
+            { item: { title: 'Books' } },
+            { item: { title: 'Toys' } }
+          ]
+        }
+      ]
+    },
+    {
+      item: { title: 'Services' },
+      children: [
+        { item: { title: 'Consulting' } },
+        { item: { title: 'Support' } }
+      ]
+    }
+  ];
+</script>
+
+<NavigatorMenu
+  items={nestedMenu}
+  textField="title"
+  onItemClick={(item) => navigate(item.path)}
+/>
+```
+
+### Custom Text Function
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const customMenu = [
+    {
+      item: { firstName: 'John', lastName: 'Doe', role: 'Admin' },
+      children: []
+    }
+  ];
+
+  function getText(item) {
+    return `${item.firstName} ${item.lastName} (${item.role})`;
+  }
+</script>
+
+<NavigatorMenu
+  items={customMenu}
+  textField={getText}
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+## Styling
+
+### CSS Variables
+
+```css
+:root {
+  --nav-menu-bg: #ffffff;
+  --nav-menu-color: #374151;
+  --nav-menu-hover-bg: #81D4FA;
+  --nav-menu-hover-color: #374151;
+}
+```
+
+### Dark Theme
+
+```css
+.theme-dark {
+  --nav-menu-bg: #1a1a1a;
+  --nav-menu-color: #e0e0e0;
+  --nav-menu-hover-bg: #3a3a3a;
+  --nav-menu-hover-color: #e0e0e0;
+}
+```
+
+## Behavior
+
+### Expand/Collapse
+
+- Clicking a menu item with children toggles its expanded state
+- Clicking a leaf item (no children) triggers `onItemClick`
+- 200ms debounce prevents rapid clicking
+- Arrow indicator (▲) shows on expandable items
+
+### Animation
+
+- Sub-menus use `slide` transition with 200ms duration
+- Smooth expand/collapse animation
+
+## Best Practices
+
+1. **Consistent Structure**: Keep menu item structure consistent across levels
+2. **Depth Limit**: Avoid nesting more than 3-4 levels for usability
+3. **Performance**: For very large menus, consider virtualization
+4. **Labels**: Use clear, concise text labels
+5. **Icons**: Consider adding icons for better visual hierarchy
+
+## Notes
+
+- The component automatically handles recursive rendering of nested items
+- `expand` property controls initial expanded state
+- Text field can be a string key or a function for custom display logic

package/dist/navigation/nav_menu/README_CN.md

@@ -0,0 +1,224 @@
+# NavigatorMenu 导航菜单组件
+
+> **5.1.0 重命名**：本文使用 [API 命名规范](../../../docs/NAMING_CN.md) 中的名字；旧名 `menuItems` 已在 5.1.0 移除（5.1.0 不保留兼容别名）。
+
+基于 Svelte 5 构建的分层导航菜单组件，支持具有展开/折叠功能的嵌套菜单项。
+
+## 特性
+
+- **分层结构**：支持多级嵌套菜单项
+- **展开/折叠**：点击展开或折叠菜单部分
+- **平滑动画**：子菜单滑动过渡效果
+- **可定制**：灵活的文本字段配置
+- **点击处理**：菜单项选择的事件回调
+- **CSS 变量**：可使用 CSS 变量进行主题化
+- **递归渲染**：自动处理嵌套菜单结构
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+```typescript
+import { NavigatorMenu } from '@ticatec/topside-elements/NavigatorMenu';
+import type MenuItem from '@ticatec/topside-elements/MenuItem';
+```
+
+或者在同一项目中使用：
+```typescript
+import { NavigatorMenu } from '$lib/nav-menu';
+import type MenuItem from '$lib/nav-menu/MenuItem';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  let items = $state([
+    {
+      item: { label: '仪表板', path: '/dashboard' },
+      children: []
+    },
+    {
+      item: { label: '项目', path: '/projects' },
+      children: [
+        { item: { label: '进行中', path: '/projects/active' } },
+        { item: { label: '已归档', path: '/projects/archived' } }
+      ]
+    }
+  ]);
+
+  function handleMenuClick(item) {
+    console.log('点击了：', item);
+  }
+</script>
+
+<NavigatorMenu
+  items={items}
+  textField="label"
+  onItemClick={handleMenuClick}
+/>
+```
+
+## 属性
+
+| 属性 | 类型 | 必填 | 描述 |
+|------|------|------|-------------|
+| `items` | `Array<MenuItem>` | 是 | 菜单项对象数组 |
+| `textField` | `string \| GetText<MenuItem>` | 是 | 字段名称或获取显示文本的函数 |
+| `onItemClick` | `(item: MenuItem) => void` | 是 | 点击菜单项时的回调 |
+| `style` | `string` | 否 | 自定义内联样式 |
+
+## MenuItem 结构
+
+```typescript
+interface MenuItem {
+  item: {
+    [key: string]: any;  // 您的数据对象
+    label?: string;      // 显示文本（如果使用字符串 textField）
+  };
+  children?: MenuItem[];  // 嵌套菜单项
+  expand?: boolean;      // 初始展开状态
+}
+```
+
+## 示例
+
+### 简单菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const simpleMenu = [
+    { item: { name: '首页', icon: 'home' } },
+    { item: { name: '关于', icon: 'info' } },
+    { item: { name: '联系', icon: 'mail' } }
+  ];
+</script>
+
+<NavigatorMenu
+  items={simpleMenu}
+  textField="name"
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+### 嵌套菜单
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const nestedMenu = [
+    {
+      item: { title: '产品' },
+      expand: true,
+      children: [
+        { item: { title: '电子产品', category: 'electronics' } },
+        { item: { title: '服装', category: 'clothing' } },
+        {
+          item: { title: '更多' },
+          children: [
+            { item: { title: '图书' } },
+            { item: { title: '玩具' } }
+          ]
+        }
+      ]
+    },
+    {
+      item: { title: '服务' },
+      children: [
+        { item: { title: '咨询' } },
+        { item: { title: '支持' } }
+      ]
+    }
+  ];
+</script>
+
+<NavigatorMenu
+  items={nestedMenu}
+  textField="title"
+  onItemClick={(item) => navigate(item.path)}
+/>
+```
+
+### 自定义文本函数
+
+```svelte
+<script>
+  import { NavigatorMenu } from '$lib/nav-menu';
+
+  const customMenu = [
+    {
+      item: { firstName: '张', lastName: '三', role: '管理员' },
+      children: []
+    }
+  ];
+
+  function getText(item) {
+    return `${item.firstName}${item.lastName} (${item.role})`;
+  }
+</script>
+
+<NavigatorMenu
+  items={customMenu}
+  textField={getText}
+  onItemClick={(item) => console.log(item)}
+/>
+```
+
+## 样式定制
+
+### CSS 变量
+
+```css
+:root {
+  --nav-menu-bg: #ffffff;
+  --nav-menu-color: #374151;
+  --nav-menu-hover-bg: #81D4FA;
+  --nav-menu-hover-color: #374151;
+}
+```
+
+### 深色主题
+
+```css
+.theme-dark {
+  --nav-menu-bg: #1a1a1a;
+  --nav-menu-color: #e0e0e0;
+  --nav-menu-hover-bg: #3a3a3a;
+  --nav-menu-hover-color: #e0e0e0;
+}
+```
+
+## 行为
+
+### 展开/折叠
+
+- 点击带有子项的菜单项切换其展开状态
+- 点击叶子项（无子项）触发 `onItemClick`
+- 200ms 防抖防止快速点击
+- 箭头指示器（▲）显示在可展开项上
+
+### 动画
+
+- 子菜单使用 `slide` 过渡，持续 200ms
+- 平滑的展开/折叠动画
+
+## 最佳实践
+
+1. **一致的结构**：在各层级保持菜单项结构一致
+2. **深度限制**：避免嵌套超过 3-4 层以提高可用性
+3. **性能**：对于非常大的菜单，考虑虚拟化
+4. **标签**：使用清晰简洁的文本标签
+5. **图标**：考虑添加图标以获得更好的视觉层次
+
+## 注意事项
+
+- 组件自动处理嵌套项的递归渲染
+- `expand` 属性控制初始展开状态
+- 文本字段可以是字符串键或用于自定义显示逻辑的函数

package/dist/navigation/nav_menu/index.d.ts

@@ -0,0 +1,8 @@
+import NavigatorMenu from "./NavigatorMenu.svelte";
+import type MenuItem from "./MenuItem";
+import type { MenuNode } from "./MenuItem";
+import type { OnMenuItemClick } from "./MenuItem";
+import Menus from "./Menus";
+export default NavigatorMenu;
+export type { MenuItem, MenuNode, OnMenuItemClick };
+export { Menus };

package/dist/navigation/nav_menu/index.js

@@ -0,0 +1,4 @@
+import NavigatorMenu from "./NavigatorMenu.svelte";
+import Menus from "./Menus";
+export default NavigatorMenu;
+export { Menus };

package/dist/navigation/navigator/NavItemStatus.d.ts

@@ -0,0 +1,5 @@
+export declare enum NavItemStatus {
+    Completed = "nav-completed",
+    Warning = "nav-warning",
+    NotStart = "nav-not-start"
+}

package/dist/navigation/navigator/NavItemStatus.js

@@ -0,0 +1,6 @@
+export var NavItemStatus;
+(function (NavItemStatus) {
+    NavItemStatus["Completed"] = "nav-completed";
+    NavItemStatus["Warning"] = "nav-warning";
+    NavItemStatus["NotStart"] = "nav-not-start";
+})(NavItemStatus || (NavItemStatus = {}));

package/dist/navigation/navigator/Navigator.svelte

@@ -0,0 +1,156 @@
+<script lang="ts">
+    import {NavItemStatus} from "./NavItemStatus";
+
+    type OnItemClick = (item: any) => void;
+    type RetrieveItemStatus = (item: any) => NavItemStatus;
+
+    interface Props {
+        items: Array<any>;
+        activeItem?: any;
+        style?: string;
+        highlights?: Array<any>;
+        /** 项点击回调 */
+        onItemClick?: OnItemClick;
+        retrieveStatus?: RetrieveItemStatus;
+    }
+
+    let {
+        items,
+        activeItem = $bindable(),
+        style = "",
+        highlights = [],
+        onItemClick,
+        retrieveStatus
+    }: Props = $props();
+
+    const handleClick = (item: any) => {
+        activeItem = item;
+        onItemClick?.(item);
+    };
+
+    const handleKeyDown = (item: any) => (e: KeyboardEvent) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleClick(item);
+        }
+    };
+</script>
+
+<div class="topside-navigator-panel" {style}>
+    <div class="navigator-content" role="list">
+        {#each items as item}
+            <div class="topside-navigator-item {retrieveStatus?.(item) ?? NavItemStatus.Completed}"
+                 class:active={activeItem === item}
+                 class:highlight={highlights.indexOf(item) > -1}
+                 role="button" tabindex="0" aria-current={activeItem === item ? 'step' : undefined}
+                 onclick={() => handleClick(item)} onkeydown={handleKeyDown(item)}>
+                <span>{item.text}</span>
+            </div>
+        {/each}
+    </div>
+</div>
+
+<style>
+    .topside-navigator-panel {
+        --topside-navigator-active-text-weight: 600;
+
+        position: relative;
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        overflow: hidden;
+        background-color: var(--topside-navigator-background-color);
+    }
+
+    .navigator-content {
+        width: 100%;
+        height: 100%;
+        box-sizing: border-box;
+        overflow-y: auto;
+        overflow-x: hidden;
+        position: relative;
+        user-select: none;
+    }
+
+    .topside-navigator-item {
+        font-size: 12px;
+        padding: 4px 8px 4px 24px;
+        position: relative;
+        background: linear-gradient(to right, transparent 12px, var(--topside-navigator-connector-color) 12px, var(--topside-navigator-connector-color) 13px, transparent 13px);
+    }
+
+    .topside-navigator-item:first-child {
+        background-size: 100% 60%;
+        background-position: bottom;
+        background-repeat: no-repeat;
+    }
+
+    .topside-navigator-item:last-child {
+        background-size: 100% 60%;
+        background-position: top;
+        background-repeat: no-repeat;
+    }
+
+    .topside-navigator-item.nav-completed {
+        color: var(--topside-navigator-completed-text-color);
+    }
+
+    .topside-navigator-item.nav-warning {
+        color: var(--topside-navigator-completed-text-color);
+        position: relative;
+    }
+
+    .topside-navigator-item.nav-warning::after {
+        content: "";
+        position: absolute;
+        right: 8px;
+        top: 30%;
+        transform: translateY(-50%);
+        width: 6px;
+        height: 6px;
+        border-radius: 50%;
+        background-color: var(--topside-navigator-warning-dot-color);
+    }
+
+    .topside-navigator-item.nav-not-start {
+        color: var(--topside-navigator-not-start-text-color);
+        font-style: italic;
+    }
+
+    .topside-navigator-item:hover {
+        color: var(--topside-navigator-hover-text-color);
+        cursor: pointer;
+    }
+
+    .topside-navigator-item.highlight {
+        color: var(--topside-navigator-highlight-text-color);
+    }
+
+    .topside-navigator-item.active {
+        color: var(--topside-navigator-active-text-color);
+        font-weight: var(--topside-navigator-active-text-weight);
+    }
+
+    .topside-navigator-item.active::before {
+        content: "";
+        position: absolute;
+        left: 8px;
+        top: 50%;
+        transform: translateY(-50%);
+        box-sizing: border-box;
+        width: 10px;
+        height: 10px;
+        border: 3px solid var(--topside-navigator-active-text-color);
+        border-radius: 50%;
+        background-color: var(--topside-navigator-background-color, white);
+    }
+
+    .topside-navigator-item.active:hover {
+        color: var(--topside-navigator-active-text-color);
+        cursor: default;
+    }
+
+    .topside-navigator-item.active.nav-not-start {
+        font-style: normal;
+    }
+</style>

package/dist/navigation/navigator/Navigator.svelte.d.ts

@@ -0,0 +1,15 @@
+import { NavItemStatus } from "./NavItemStatus";
+type OnItemClick = (item: any) => void;
+type RetrieveItemStatus = (item: any) => NavItemStatus;
+interface Props {
+    items: Array<any>;
+    activeItem?: any;
+    style?: string;
+    highlights?: Array<any>;
+    /** 项点击回调 */
+    onItemClick?: OnItemClick;
+    retrieveStatus?: RetrieveItemStatus;
+}
+declare const Navigator: import("svelte").Component<Props, {}, "activeItem">;
+type Navigator = ReturnType<typeof Navigator>;
+export default Navigator;