@ticatec/topside-elements 1.0.0

package/dist/layouts/app_top_bar/AppTopBar.svelte

@@ -0,0 +1,83 @@
+<script lang="ts">
+    import type {Snippet} from 'svelte';
+
+    interface Props {
+        title?: string;
+        style?: string;
+        theme?: string;
+        home?: Snippet;
+        children?: Snippet;
+        right?: Snippet;
+    }
+
+    let {
+        title = '',
+        style = '',
+        theme,
+        home,
+        children,
+        right
+    }: Props = $props();
+</script>
+
+<div class="topside-top-bar" data-theme={theme} {style}>
+    {#if home}
+        <div class="bar-home">
+            {@render home()}
+        </div>
+    {/if}
+    {#if title}
+        <div class="bar-title">
+            <span>{title}</span>
+        </div>
+    {/if}
+    <div class="main-content">
+        {#if children}
+            {@render children()}
+        {/if}
+    </div>
+    {#if right}
+        <div class="bar-right">
+            {@render right()}
+        </div>
+    {/if}
+</div>
+
+<style>.topside-top-bar {
+  background-color: var(--topside-top-bar-color-surface);
+  color: var(--topside-top-bar-color-text);
+  width: 100%;
+  height: var(--topside-app-top-bar-height);
+  font-size: var(--topside-app-top-bar-font-size);
+  display: flex;
+  flex-direction: row;
+  justify-items: center;
+  align-items: center;
+  padding: 0 var(--topside-app-top-bar-margin);
+  gap: var(--topside-app-top-bar-spacing, 8px);
+}
+
+.topside-top-bar .bar-home {
+  position: relative;
+  cursor: pointer;
+  flex: 0 0 auto;
+}
+
+.topside-top-bar .bar-home:active {
+  top: 1px;
+}
+
+.topside-top-bar .bar-title {
+  flex: 0 0 auto;
+}
+
+.topside-top-bar .main-content {
+  flex: 1 1 auto;
+  text-align: left;
+  overflow: hidden;
+  position: relative;
+}
+
+.topside-top-bar .bar-right {
+  flex: 0 0 auto;
+}</style>

package/dist/layouts/app_top_bar/AppTopBar.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    title?: string;
+    style?: string;
+    theme?: string;
+    home?: Snippet;
+    children?: Snippet;
+    right?: Snippet;
+}
+declare const AppTopBar: import("svelte").Component<Props, {}, "">;
+type AppTopBar = ReturnType<typeof AppTopBar>;
+export default AppTopBar;

package/dist/layouts/app_top_bar/README.md

@@ -0,0 +1,258 @@
+# AppTopBar Component
+
+A fixed-height top application bar with four slots: `home` (left), `title` (text), default children (flexible center), and `right`. Designed to sit at the top of an app shell.
+
+## Features
+
+- **Four content slots**: `home` snippet, `title` string, default `children` snippet, `right` snippet — all optional, rendered left → right
+- **Fixed height**: driven by the `--topside-app-top-bar-height` token
+- **Center absorbs slack**: the default `children` area is `flex: 1 1 auto` and clips overflow; `home` / `title` / `right` stay at content width
+- **Built-in click feedback on `home`**: the home slot wrapper has `cursor: pointer` and a 1px press-down on `:active` — meant for a logo / menu button
+- **Theme hook**: outer wrapper exposes `data-theme="{theme}"`
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+</script>
+
+<AppTopBar title="My Application">
+  {#snippet home()}
+    <img src="/logo.png" alt="Logo" style="height: 28px;" />
+  {/snippet}
+
+  {#snippet right()}
+    <button>User Menu</button>
+  {/snippet}
+</AppTopBar>
+```
+
+> **Svelte 5 snippets, not slots.** Use `{#snippet home()}…{/snippet}` and `{#snippet right()}…{/snippet}`. The default (untagged) children between the tags go to the `children` snippet. There is no slot called `left` — the leftmost slot is named `home`.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | Title text rendered in the `.bar-title` slot, between `home` and `children`. Empty string → title block is not rendered. |
+| `style` | `string` | `''` | Inline CSS on the outer wrapper |
+| `theme` | `string \| undefined` | `undefined` | Set as `data-theme` on the outer wrapper for scoped CSS overrides |
+| `home` | `Snippet \| undefined` | `undefined` | Leftmost content (logo, menu button, etc.). Wrapping `<div>` has `cursor: pointer` + active feedback. |
+| `children` | `Snippet \| undefined` | `undefined` | Center content. The wrapper is `flex: 1 1 auto` and clips overflow. |
+| `right` | `Snippet \| undefined` | `undefined` | Right-aligned content (actions, user menu). |
+
+## Layout
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ [home] [title] [          children (flex 1)          ] [right]│
+└─────────────────────────────────────────────────────────────┘
+  flex:0    flex:0   flex:1 1 auto, overflow:hidden      flex:0
+```
+
+The bar itself:
+
+```css
+.topside-top-bar {
+  width: 100%;
+  height: var(--topside-app-top-bar-height);
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  padding: 0 var(--topside-app-top-bar-margin);
+  gap: var(--topside-app-top-bar-spacing, 8px);
+}
+```
+
+Consequences worth knowing:
+
+- **The title is not centered.** It sits between `home` and `children`. If you need a centered title, omit `home` and `children` and the title naturally falls at the left.
+- **`children` clips overflow** (`overflow: hidden`). Don't put wide content there without giving it its own scroll container.
+- **The bar is exactly `--topside-app-top-bar-height` tall.** Content taller than that will be clipped by the flex layout.
+
+## Examples
+
+### Menu Button + Title + User
+
+```svelte
+<AppTopBar title="Dashboard">
+  {#snippet home()}
+    <button class="menu-toggle" onclick={toggleDrawer}>☰</button>
+  {/snippet}
+
+  {#snippet right()}
+    <button class="user-menu" onclick={openProfile}>Profile</button>
+  {/snippet}
+</AppTopBar>
+```
+
+### Logo + Nav + Right Actions
+
+```svelte
+<script>
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+  import Icon from '@ticatec/topside-elements/Icon';
+</script>
+
+<AppTopBar title="Project Manager">
+  {#snippet home()}
+    <img src="/logo.svg" alt="Logo" style="height: 28px;" />
+  {/snippet}
+
+  <!-- default children: middle nav -->
+  <nav style="display: flex; gap: 16px;">
+    <a href="/dashboard">Dashboard</a>
+    <a href="/projects">Projects</a>
+    <a href="/team">Team</a>
+  </nav>
+
+  {#snippet right()}
+    <Icon name="icon_google_notifications" onclick={openNotifications} />
+    <img src="/avatar.jpg" alt="User" style="height: 32px; border-radius: 50%;" />
+  {/snippet}
+</AppTopBar>
+```
+
+### Search Field in the Middle
+
+```svelte
+<script>
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+
+  let searchTerm = $state('');
+</script>
+
+<AppTopBar title="Search">
+  {#snippet home()}
+    <button onclick={toggleDrawer}>☰</button>
+  {/snippet}
+
+  <!-- middle: search -->
+  <TextEditor
+    placeholder="Search..."
+    style="max-width: 480px; width: 100%;"
+    bind:value={searchTerm}
+  />
+
+  {#snippet right()}
+    <button onclick={handleSearch}>Search</button>
+  {/snippet}
+</AppTopBar>
+```
+
+### Title-Only (No Slots)
+
+```svelte
+<AppTopBar title="Settings" />
+```
+
+Just renders the title at the left edge of the bar.
+
+### Custom Theme via Inline Style
+
+```svelte
+<AppTopBar
+  title="Dark Dashboard"
+  style="background-color: #1a1a2e; color: #eaeaea;"
+>
+  {#snippet home()}
+    <img src="/logo-white.svg" alt="Logo" style="height: 28px;" />
+  {/snippet}
+  {#snippet right()}
+    <button onclick={toggleDarkMode}>🌙</button>
+  {/snippet}
+</AppTopBar>
+```
+
+## DOM Structure & CSS
+
+Rendered output:
+
+```html
+<div class="topside-top-bar" data-theme="..." style="...">
+  <!-- only if `home` snippet provided -->
+  <div class="bar-home">{@render home()}</div>
+
+  <!-- only if `title` is non-empty -->
+  <div class="bar-title"><span>{title}</span></div>
+
+  <!-- always rendered; content from default children snippet -->
+  <div class="main-content">{@render children()}</div>
+
+  <!-- only if `right` snippet provided -->
+  <div class="bar-right">{@render right()}</div>
+</div>
+```
+
+### CSS classes
+
+| Class | Purpose |
+|-------|---------|
+| `.topside-top-bar` | Outer wrapper (flex row) |
+| `.bar-home` | Wraps `home` snippet; `cursor: pointer`, `:active { top: 1px }` |
+| `.bar-title` | Wraps `<span>{title}</span>` |
+| `.main-content` | Wraps default children; `flex: 1 1 auto`, `overflow: hidden` |
+| `.bar-right` | Wraps `right` snippet |
+
+### CSS Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `--topside-top-bar-color-surface` | Background color |
+| `--topside-top-bar-color-text` | Text color |
+| `--topside-app-top-bar-height` | Bar height |
+| `--topside-app-top-bar-font-size` | Base font size |
+| `--topside-app-top-bar-margin` | Horizontal padding (left/right) |
+| `--topside-app-top-bar-spacing` | Gap between slots (defaults to `8px` if unset) |
+
+Override globally or per-theme:
+
+```css
+:root {
+  --topside-app-top-bar-height: 56px;
+  --topside-app-top-bar-margin: 16px;
+}
+
+[data-theme='dark'] {
+  --topside-top-bar-color-surface: #1f2937;
+  --topside-top-bar-color-text: #f9fafb;
+}
+```
+
+## Behavior Notes
+
+- **Snippet gates**: `home` and `right` only render their wrapper `<div>` if the snippet is provided. `title` only renders if non-empty. The middle `main-content` wrapper **always renders** (even when empty) so the flex layout keeps `right` pushed to the right edge.
+- **`home` is interactive by default**: the wrapper has `cursor: pointer` and a press-down animation. If you put non-interactive content (like a logo) in there, the cursor will still show as pointer — override with `style="cursor: default"` on the snippet's root if that bothers you.
+- **No built-in sticky positioning**: the bar is a normal block. Wrap it in a sticky/fixed container yourself if you want it pinned on scroll.
+
+## Accessibility
+
+- The outer wrapper is a plain `<div>` with no role. Add `role="banner"` yourself if you want landmark semantics.
+- The `home` slot's cursor/active styling is purely visual — there's no automatic keyboard handling. Put a real `<button>` inside the `home` snippet if it should be keyboard-activatable.
+- Long titles will be clipped by neighbors rather than truncated with `…`. If your title can be long, wrap it in your own element with `text-overflow: ellipsis`.
+
+## Best Practices
+
+1. **Use snippets, not slots.** Svelte 5 dropped the `slot="..."` syntax; named slots are now named snippets.
+2. **Reserve `home` for navigation entry points** (logo, hamburger). It has pointer cursor + press feedback baked in.
+3. **Don't put wide content in `children`** without scroll management — `overflow: hidden` will clip it.
+4. **Use `--topside-app-top-bar-*` tokens** to keep the bar height/spacing consistent across the app.
+5. **For dark mode**, scope `data-theme="dark"` and override the two color tokens.
+
+## Related Components
+
+- [ActionBar](../action_bar/README.md) — horizontal button row, often used inside the `right` snippet
+- [Icon](../../general/icon/README.md) — icons for menu / notifications / etc.

package/dist/layouts/app_top_bar/README_CN.md

@@ -0,0 +1,258 @@
+# AppTopBar 顶栏组件
+
+固定高度的顶部应用栏，包含四个槽位：`home`（左）、`title`（文字）、默认 children（弹性的中间区）、`right`（右）。放在 app 外壳的顶部。
+
+## 功能特性
+
+- **四个内容槽**：`home` snippet、`title` 字符串、默认 `children` snippet、`right` snippet —— 全部可选，按左 → 右顺序渲染
+- **固定高度**：由 `--topside-app-top-bar-height` 令牌驱动
+- **中间区吸收剩余空间**：默认 `children` 区是 `flex: 1 1 auto` 并裁剪溢出；`home` / `title` / `right` 保持内容宽度
+- **`home` 内置点击反馈**：home 槽的外壳有 `cursor: pointer` 和 `:active` 时 1px 下沉动画 —— 专为 logo / 菜单按钮设计
+- **主题钩子**：外层 wrapper 暴露 `data-theme="{theme}"`
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 导入
+
+```typescript
+import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+```
+
+## 基本用法
+
+```svelte
+<script>
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+</script>
+
+<AppTopBar title="我的应用">
+  {#snippet home()}
+    <img src="/logo.png" alt="Logo" style="height: 28px;" />
+  {/snippet}
+
+  {#snippet right()}
+    <button>用户菜单</button>
+  {/snippet}
+</AppTopBar>
+```
+
+> **Svelte 5 用 snippet，不是 slot。** 用 `{#snippet home()}…{/snippet}` 和 `{#snippet right()}…{/snippet}`。标签之间的默认（未命名）内容进入 `children` snippet。**没有名为 `left` 的 slot** —— 最左边的槽叫 `home`。
+
+## 属性
+
+| 属性 | 类型 | 默认值 | 描述 |
+|------|------|---------|-------------|
+| `title` | `string` | `''` | 标题文字，渲染在 `.bar-title` 槽中（`home` 与 `children` 之间）。空字符串 → 不渲染标题块 |
+| `style` | `string` | `''` | 外层 wrapper 的内联 CSS |
+| `theme` | `string \| undefined` | `undefined` | 设为外层 wrapper 的 `data-theme`，便于作用域化 CSS 覆盖 |
+| `home` | `Snippet \| undefined` | `undefined` | 最左边的内容（logo、菜单按钮等）。外层 `<div>` 有 `cursor: pointer` + 按下反馈 |
+| `children` | `Snippet \| undefined` | `undefined` | 中间内容。外壳是 `flex: 1 1 auto` 且裁剪溢出 |
+| `right` | `Snippet \| undefined` | `undefined` | 右对齐内容（操作、用户菜单） |
+
+## 布局
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│ [home] [title] [          children (flex 1)          ] [right]│
+└─────────────────────────────────────────────────────────────┘
+  flex:0    flex:0   flex:1 1 auto, overflow:hidden      flex:0
+```
+
+bar 本身：
+
+```css
+.topside-top-bar {
+  width: 100%;
+  height: var(--topside-app-top-bar-height);
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  padding: 0 var(--topside-app-top-bar-margin);
+  gap: var(--topside-app-top-bar-spacing, 8px);
+}
+```
+
+需要知道的几点：
+
+- **标题不居中。** 它在 `home` 与 `children` 之间。需要居中标题的话，省掉 `home` 和 `children`，标题自然就落在左边
+- **`children` 裁剪溢出**（`overflow: hidden`）。别在里面放宽内容而不自带滚动容器
+- **bar 高度精确等于 `--topside-app-top-bar-height`。** 超高的内容会被 flex 布局裁掉
+
+## 示例
+
+### 菜单按钮 + 标题 + 用户
+
+```svelte
+<AppTopBar title="Dashboard">
+  {#snippet home()}
+    <button class="menu-toggle" onclick={toggleDrawer}>☰</button>
+  {/snippet}
+
+  {#snippet right()}
+    <button class="user-menu" onclick={openProfile}>个人资料</button>
+  {/snippet}
+</AppTopBar>
+```
+
+### Logo + 导航 + 右侧操作
+
+```svelte
+<script>
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+  import Icon from '@ticatec/topside-elements/Icon';
+</script>
+
+<AppTopBar title="项目管理器">
+  {#snippet home()}
+    <img src="/logo.svg" alt="Logo" style="height: 28px;" />
+  {/snippet}
+
+  <!-- 默认 children：中间导航 -->
+  <nav style="display: flex; gap: 16px;">
+    <a href="/dashboard">仪表板</a>
+    <a href="/projects">项目</a>
+    <a href="/team">团队</a>
+  </nav>
+
+  {#snippet right()}
+    <Icon name="icon_google_notifications" onclick={openNotifications} />
+    <img src="/avatar.jpg" alt="User" style="height: 32px; border-radius: 50%;" />
+  {/snippet}
+</AppTopBar>
+```
+
+### 中间放搜索框
+
+```svelte
+<script>
+  import AppTopBar from '@ticatec/topside-elements/AppTopBar';
+  import TextEditor from '@ticatec/topside-elements/TextEditor';
+
+  let searchTerm = $state('');
+</script>
+
+<AppTopBar title="搜索">
+  {#snippet home()}
+    <button onclick={toggleDrawer}>☰</button>
+  {/snippet}
+
+  <!-- 中间：搜索 -->
+  <TextEditor
+    placeholder="搜索..."
+    style="max-width: 480px; width: 100%;"
+    bind:value={searchTerm}
+  />
+
+  {#snippet right()}
+    <button onclick={handleSearch}>搜索</button>
+  {/snippet}
+</AppTopBar>
+```
+
+### 仅标题（无槽）
+
+```svelte
+<AppTopBar title="设置" />
+```
+
+只在 bar 左边渲染标题。
+
+### 通过内联 style 自定义主题
+
+```svelte
+<AppTopBar
+  title="暗色仪表板"
+  style="background-color: #1a1a2e; color: #eaeaea;"
+>
+  {#snippet home()}
+    <img src="/logo-white.svg" alt="Logo" style="height: 28px;" />
+  {/snippet}
+  {#snippet right()}
+    <button onclick={toggleDarkMode}>🌙</button>
+  {/snippet}
+</AppTopBar>
+```
+
+## DOM 结构与 CSS
+
+实际渲染：
+
+```html
+<div class="topside-top-bar" data-theme="..." style="...">
+  <!-- 仅当提供了 `home` snippet -->
+  <div class="bar-home">{@render home()}</div>
+
+  <!-- 仅当 `title` 非空 -->
+  <div class="bar-title"><span>{title}</span></div>
+
+  <!-- 总是渲染；内容来自默认 children snippet -->
+  <div class="main-content">{@render children()}</div>
+
+  <!-- 仅当提供了 `right` snippet -->
+  <div class="bar-right">{@render right()}</div>
+</div>
+```
+
+### CSS 类
+
+| 类 | 用途 |
+|----|------|
+| `.topside-top-bar` | 外层 wrapper（flex row） |
+| `.bar-home` | 包裹 `home` snippet；`cursor: pointer`、`:active { top: 1px }` |
+| `.bar-title` | 包裹 `<span>{title}</span>` |
+| `.main-content` | 包裹默认 children；`flex: 1 1 auto`、`overflow: hidden` |
+| `.bar-right` | 包裹 `right` snippet |
+
+### CSS 变量
+
+| 变量 | 用途 |
+|------|------|
+| `--topside-top-bar-color-surface` | 背景色 |
+| `--topside-top-bar-color-text` | 文字色 |
+| `--topside-app-top-bar-height` | bar 高度 |
+| `--topside-app-top-bar-font-size` | 基础字号 |
+| `--topside-app-top-bar-margin` | 水平内边距（左右） |
+| `--topside-app-top-bar-spacing` | 槽位间距（未设时默认 `8px`） |
+
+全局或按主题覆盖：
+
+```css
+:root {
+  --topside-app-top-bar-height: 56px;
+  --topside-app-top-bar-margin: 16px;
+}
+
+[data-theme='dark'] {
+  --topside-top-bar-color-surface: #1f2937;
+  --topside-top-bar-color-text: #f9fafb;
+}
+```
+
+## 行为说明
+
+- **Snippet 门控**：`home` 和 `right` 只在提供了 snippet 时才渲染外层 `<div>`。`title` 只在非空时渲染。中间的 `main-content` 外壳**总是渲染**（即使为空），保证 flex 布局把 `right` 推到右边缘
+- **`home` 默认是交互的**：外壳有 `cursor: pointer` 和按下动画。如果你放的是非交互内容（如 logo），光标还是会显示手型 —— 在 snippet 根元素上覆盖 `style="cursor: default"` 即可
+- **不自带 sticky 定位**：bar 是普通块级元素。需要吸顶就自己包一个 sticky/fixed 容器
+
+## 无障碍访问
+
+- 外层 wrapper 是普通 `<div>`，无 role。需要 landmark 语义时自己加 `role="banner"`
+- `home` 槽的光标 / active 样式纯视觉 —— 没有自动键盘处理。`home` snippet 里放真正的 `<button>` 才能键盘激活
+- 长标题会被邻接元素裁掉，而不是 `…` 截断。标题可能很长的话，自己用 `text-overflow: ellipsis` 包一层
+
+## 最佳实践
+
+1. **用 snippet，不是 slot。** Svelte 5 弃用了 `slot="..."` 语法，具名 slot 现在是具名 snippet
+2. **`home` 留给导航入口**（logo、汉堡按钮）。它自带 pointer 光标 + 按下反馈
+3. **`children` 别放超宽内容**，除非自己管理滚动 —— `overflow: hidden` 会裁掉
+4. **统一用 `--topside-app-top-bar-*` 令牌**，全应用保持 bar 高度/间距一致
+5. **暗色模式**通过 `data-theme="dark"` 作用域，覆盖两个颜色令牌
+
+## 相关组件
+
+- [ActionBar](../action_bar/README_CN.md) —— 水平按钮行，常放在 `right` snippet 里
+- [Icon](../../general/icon/README_CN.md) —— 菜单 / 通知等图标

package/dist/layouts/app_top_bar/index.d.ts

@@ -0,0 +1,2 @@
+import AppTopBar from "./AppTopBar.svelte";
+export default AppTopBar;

package/dist/layouts/app_top_bar/index.js

@@ -0,0 +1,2 @@
+import AppTopBar from "./AppTopBar.svelte";
+export default AppTopBar;