@ticatec/topside-elements 1.0.0

package/dist/overlay/drawer/README.md

@@ -0,0 +1,249 @@
+# Drawer
+
+A slide-out side panel that overlays the page with a full-screen backdrop. Click the backdrop to close, or control visibility programmatically through a two-way bindable `visible` prop. Built with Svelte 5 runes and the snippet API.
+
+## Features
+
+- **Left or Right Positioning**: Slides in from either side via `position`.
+- **Bindable Visibility**: `visible` is two-way bindable — the drawer sets it to `false` when the backdrop is clicked.
+- **Custom Width**: `width` prop in pixels.
+- **Per-Instance Theme**: `theme` prop renders as `data-theme` on the root, enabling theme isolation (e.g. a dark menu drawer on a light page).
+- **Snippet Content**: Svelte 5 children snippet for the panel body.
+- **Fly Transition**: Panel flies in/out with configurable direction derived from `position`.
+- **Scrollable Body**: Content overflowing the viewport scrolls inside the panel.
+
+## Installation
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## Import
+
+```typescript
+import Drawer from "@ticatec/topside-elements/Drawer";
+```
+
+## Basic Usage
+
+`visible` is bindable — use `bind:visible` so the drawer can close itself when the backdrop is clicked.
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let visible = $state(false);
+</script>
+
+<button onclick={() => (visible = true)}>Open</button>
+
+<Drawer bind:visible>
+  <div style="padding: 16px;">
+    <h2>Menu</h2>
+    <p>Drawer content goes here.</p>
+    <button onclick={() => (visible = false)}>Close</button>
+  </div>
+</Drawer>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `visible` | `boolean` | `false` | Two-way bindable. Controls whether the panel is shown. Set to `false` by the component on backdrop click. |
+| `position` | `"left" \| "right"` | `"left"` | Side the panel slides in from. |
+| `width` | `number` | `300` | Panel width in pixels. |
+| `theme` | `string \| undefined` | `undefined` | Rendered as `data-theme` on the root element for scoped theme overrides. |
+
+### Snippet
+
+Panel body is provided as the default `children` snippet — content placed between `<Drawer>` tags is rendered inside the sliding panel.
+
+## Behavior
+
+### Visibility and the Backdrop
+
+- The component renders a full-screen fixed backdrop at `z-index: 99`.
+- Clicking the backdrop sets `visible = false` (via `bind:visible`).
+- Clicks inside the panel are stopped from reaching the backdrop.
+- After `visible` flips to `false`, the panel plays its outro transition before the wrapper is hidden (`display: none`).
+
+### Animation
+
+The panel uses Svelte's `fly` transition:
+
+| `position` | Flies in from |
+|------------|----------------|
+| `"left"` | `x = -width` (just off the left edge) |
+| `"right"` | `x = 100%` (just off the right edge) |
+
+Both directions use `duration: 1000ms` and an opacity ramp from `0.5 → 1.0`.
+
+## Theming
+
+The `theme` prop is rendered as a `data-theme` attribute on the root wrapper. Combined with a matching CSS rule, this lets one drawer use a different theme than the page — useful for menu drawers that should stay dark on a light page (or vice versa).
+
+```svelte
+<!-- Light page, dark menu drawer -->
+<Drawer bind:visible theme="dark">
+  <NavigatorMenu />
+</Drawer>
+```
+
+```css
+/* Defined by topside-root.scss — overrides variables within the drawer subtree */
+[data-theme="dark"] {
+  --topside-color-surface: #1a1a1a;
+  --topside-color-primary: #ffffff;
+  /* ... */
+}
+```
+
+**Note**: only `[data-theme="dark"]` is shipped by the library. Setting `theme="light"` on a dark page currently has no effect because no `[data-theme="light"]` rule exists. Define your own `[data-theme="..."]` blocks to enable other theme names.
+
+## Styling
+
+The drawer reads these CSS custom properties (declared on `:root` by `topside-root.scss`):
+
+```css
+:root {
+  --topside-drawer-color-surface: var(--topside-color-surface);
+  --topside-drawer-left-shadow:
+    rgba(0, 0, 0, 0.08) 6px 0px 16px,
+    rgba(0, 0, 0, 0.04) 16px 0px 48px;
+  --topside-drawer-right-shadow:
+    rgba(0, 0, 0, 0.08) 6px 0px 16px,
+    rgba(0, 0, 0, 0.04) 16px 0px 48px;
+}
+```
+
+| Variable | Used for |
+|----------|----------|
+| `--topside-drawer-color-surface` | Panel background. |
+| `--topside-drawer-left-shadow` | Drop shadow when `position="left"`. |
+| `--topside-drawer-right-shadow` | Drop shadow when `position="right"`. |
+| `--topside-color-primary` | Default text color inside the panel. |
+| `--topside-color-border-secondary` | Inner edge border between panel and page. |
+
+### Custom Styling
+
+Override the variables globally, scope them via a `data-theme` block, or target the panel directly:
+
+```css
+/* Wider, warmer panel everywhere */
+:root {
+  --topside-drawer-color-surface: #fff8f0;
+}
+
+/* Rounded inner corners on left drawer */
+.topside-drawer > div.left {
+  border-radius: 0 12px 12px 0;
+}
+
+/* Tinted backdrop with blur */
+.topside-drawer {
+  background-color: rgba(0, 0, 0, 0.45);
+  backdrop-filter: blur(4px);
+}
+```
+
+## Examples
+
+### Navigation Menu (Left)
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let menuOpen = $state(false);
+</script>
+
+<button onclick={() => (menuOpen = true)}>☰ Menu</button>
+
+<Drawer bind:visible={menuOpen}>
+  <nav style="padding: 16px;">
+    <h3>Navigation</h3>
+    <ul>
+      <li><a href="/" onclick={() => (menuOpen = false)}>Home</a></li>
+      <li><a href="/about" onclick={() => (menuOpen = false)}>About</a></li>
+      <li><a href="/contact" onclick={() => (menuOpen = false)}>Contact</a></li>
+    </ul>
+  </nav>
+</Drawer>
+```
+
+### Settings Panel (Right)
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let settingsOpen = $state(false);
+  let notifications = $state(true);
+  let compact = $state(false);
+</script>
+
+<button onclick={() => (settingsOpen = true)}>⚙ Settings</button>
+
+<Drawer bind:visible={settingsOpen} position="right" width={360}>
+  <div style="padding: 16px;">
+    <h3>Settings</h3>
+    <label><input type="checkbox" bind:checked={notifications} /> Notifications</label><br/>
+    <label><input type="checkbox" bind:checked={compact} /> Compact mode</label>
+  </div>
+</Drawer>
+```
+
+### Themed Menu Drawer
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let menuOpen = $state(false);
+</script>
+
+<Drawer bind:visible={menuOpen} theme="dark" width={280}>
+  <!-- Dark panel regardless of page theme -->
+</Drawer>
+```
+
+### Programmatic Close from Inside
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let open = $state(false);
+</script>
+
+<Drawer bind:visible={open}>
+  <div style="padding: 16px;">
+    <button onclick={() => (open = false)}>✕ Close</button>
+    <!-- ... -->
+  </div>
+</Drawer>
+```
+
+## Accessibility
+
+- The root and the panel both carry `aria-hidden="true"`. **Note**: these attributes are currently static and do not reflect `visible` — consumers needing correct ARIA state should add their own attribute management.
+- The drawer does not trap focus. For modal-style usage, wrap the content in a focus-trap.
+- Keyboard dismissal (Escape) is not built in — add a `<svelte:window onkeydown={...}>` handler if needed.
+
+## Best Practices
+
+1. **Always use `bind:visible`** (not one-way `visible={...}`) — otherwise backdrop clicks can't update your state and the panel gets out of sync.
+2. **Reset content state on close** if the drawer holds ephemeral form state, so the next open doesn't show stale values.
+3. **Pick `width` for context**: 240–300px for navigation menus, 360–480px for forms/settings, ≤85% viewport on mobile.
+4. **Use `theme` for inverted panels** (e.g. branded dark nav on a light app), defining `[data-theme="..."]` rules in your app CSS.
+5. **Don't stack drawers** — `z-index: 99` is shared, and backdrop click handling assumes a single open instance.
+
+## Related Components
+
+- [Dialog](../dialog/README.md) — Centered modal for custom content.
+- [MessageBox](../message-box/README.md) — Modal confirmations and acknowledged messages.
+- [Toast](../toast/README.md) — Transient notifications.
+- [Indicator](../indicator/README.md) — Full-screen loading spinner.
+- [ContextMenu](../context-menu/README.md) — Right-click context menu.
+- [Tooltip](../tooltip/README.md) — Hover-based contextual hints.

package/dist/overlay/drawer/README_CN.md

@@ -0,0 +1,249 @@
+# Drawer 侧边面板
+
+从页面侧边滑出的面板组件，遮罩覆盖整个视窗。点击遮罩即可关闭，也可以通过双向绑定的 `visible` 属性用代码控制可见性。基于 Svelte 5 runes 与 snippet API 实现。
+
+## 特性
+
+- **左侧 / 右侧滑出**：通过 `position` 控制从哪一侧滑入
+- **双向绑定可见性**：`visible` 支持双向绑定——用户点击遮罩时组件会将其设为 `false`
+- **自定义宽度**：`width` 属性按像素设置
+- **实例级主题**：`theme` 属性会渲染为根节点的 `data-theme`，便于局部主题隔离（比如浅色页面里的深色菜单 Drawer）
+- **Snippet 内容**：使用 Svelte 5 children snippet 渲染面板内容
+- **Fly 过渡**：面板按 `position` 自动选择方向滑入/滑出
+- **可滚动主体**：超出视口高度的内容在面板内滚动
+
+## 安装
+
+```bash
+npm install @ticatec/topside-elements
+```
+
+## 引入
+
+```typescript
+import Drawer from "@ticatec/topside-elements/Drawer";
+```
+
+## 基础用法
+
+`visible` 支持双向绑定——使用 `bind:visible`，这样点击遮罩时 Drawer 才能把状态同步回去。
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let visible = $state(false);
+</script>
+
+<button onclick={() => (visible = true)}>打开</button>
+
+<Drawer bind:visible>
+  <div style="padding: 16px;">
+    <h2>菜单</h2>
+    <p>这里是 Drawer 内容。</p>
+    <button onclick={() => (visible = false)}>关闭</button>
+  </div>
+</Drawer>
+```
+
+## 属性（Props）
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `visible` | `boolean` | `false` | 支持双向绑定。控制面板是否显示；用户点击遮罩时组件会将其置为 `false` |
+| `position` | `"left" \| "right"` | `"left"` | 面板从哪一侧滑入 |
+| `width` | `number` | `300` | 面板宽度（像素） |
+| `theme` | `string \| undefined` | `undefined` | 渲染为根元素的 `data-theme`，用于作用域内的主题覆盖 |
+
+### Snippet
+
+面板内容通过默认的 `children` snippet 提供——直接写在 `<Drawer>` 标签之间的内容会渲染到滑出面板里。
+
+## 行为
+
+### 可见性与遮罩
+
+- 组件会渲染一个 `z-index: 99` 的全屏固定遮罩
+- 点击遮罩会把 `visible` 设为 `false`（通过 `bind:visible` 回写）
+- 面板内部的点击会被阻止冒泡到遮罩
+- `visible` 翻为 `false` 后，面板会先播完出场过渡，然后外层容器才真正 `display: none`
+
+### 动画
+
+面板使用 Svelte 的 `fly` 过渡：
+
+| `position` | 滑入起点 |
+|------------|----------|
+| `"left"` | `x = -width`（左边缘外） |
+| `"right"` | `x = 100%`（右边缘外） |
+
+两个方向都用 `duration: 1000ms`，透明度从 `0.5 → 1.0` 渐变。
+
+## 主题
+
+`theme` 属性会作为 `data-theme` 渲染到根容器上。配合对应的 CSS 规则，可以让某个 Drawer 用与页面不同的主题——非常适合"浅色页面里的深色菜单 Drawer"（或反过来）。
+
+```svelte
+<!-- 浅色页面 + 深色菜单 Drawer -->
+<Drawer bind:visible theme="dark">
+  <NavigatorMenu />
+</Drawer>
+```
+
+```css
+/* 由 topside-root.scss 定义——在 Drawer 子树内覆盖变量 */
+[data-theme="dark"] {
+  --topside-color-surface: #1a1a1a;
+  --topside-color-primary: #ffffff;
+  /* ... */
+}
+```
+
+**注意**：库目前只内置了 `[data-theme="dark"]`。在深色页面里设 `theme="light"` 暂时无效，因为没有对应的 `[data-theme="light"]` 规则。如需其它主题名，请自行定义 `[data-theme="..."]` 块。
+
+## 样式
+
+Drawer 读取以下 CSS 自定义属性（由 `topside-root.scss` 在 `:root` 上声明）：
+
+```css
+:root {
+  --topside-drawer-color-surface: var(--topside-color-surface);
+  --topside-drawer-left-shadow:
+    rgba(0, 0, 0, 0.08) 6px 0px 16px,
+    rgba(0, 0, 0, 0.04) 16px 0px 48px;
+  --topside-drawer-right-shadow:
+    rgba(0, 0, 0, 0.08) 6px 0px 16px,
+    rgba(0, 0, 0, 0.04) 16px 0px 48px;
+}
+```
+
+| 变量 | 用途 |
+|------|------|
+| `--topside-drawer-color-surface` | 面板背景色 |
+| `--topside-drawer-left-shadow` | `position="left"` 时的投影 |
+| `--topside-drawer-right-shadow` | `position="right"` 时的投影 |
+| `--topside-color-primary` | 面板默认文字颜色 |
+| `--topside-color-border-secondary` | 面板与页面相邻边的边框色 |
+
+### 自定义样式
+
+全局覆盖变量、用 `data-theme` 块做作用域覆盖，或直接针对面板写样式：
+
+```css
+/* 全局面板换色 */
+:root {
+  --topside-drawer-color-surface: #fff8f0;
+}
+
+/* 左侧面板内侧圆角 */
+.topside-drawer > div.left {
+  border-radius: 0 12px 12px 0;
+}
+
+/* 带模糊的着色遮罩 */
+.topside-drawer {
+  background-color: rgba(0, 0, 0, 0.45);
+  backdrop-filter: blur(4px);
+}
+```
+
+## 示例
+
+### 导航菜单（左侧）
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let menuOpen = $state(false);
+</script>
+
+<button onclick={() => (menuOpen = true)}>☰ 菜单</button>
+
+<Drawer bind:visible={menuOpen}>
+  <nav style="padding: 16px;">
+    <h3>导航</h3>
+    <ul>
+      <li><a href="/" onclick={() => (menuOpen = false)}>首页</a></li>
+      <li><a href="/about" onclick={() => (menuOpen = false)}>关于</a></li>
+      <li><a href="/contact" onclick={() => (menuOpen = false)}>联系</a></li>
+    </ul>
+  </nav>
+</Drawer>
+```
+
+### 设置面板（右侧）
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let settingsOpen = $state(false);
+  let notifications = $state(true);
+  let compact = $state(false);
+</script>
+
+<button onclick={() => (settingsOpen = true)}>⚙ 设置</button>
+
+<Drawer bind:visible={settingsOpen} position="right" width={360}>
+  <div style="padding: 16px;">
+    <h3>设置</h3>
+    <label><input type="checkbox" bind:checked={notifications} /> 启用通知</label><br/>
+    <label><input type="checkbox" bind:checked={compact} /> 紧凑模式</label>
+  </div>
+</Drawer>
+```
+
+### 带主题的菜单 Drawer
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let menuOpen = $state(false);
+</script>
+
+<Drawer bind:visible={menuOpen} theme="dark" width={280}>
+  <!-- 不论页面主题如何，面板都是深色 -->
+</Drawer>
+```
+
+### 面板内主动关闭
+
+```svelte
+<script>
+  import Drawer from "@ticatec/topside-elements/Drawer";
+
+  let open = $state(false);
+</script>
+
+<Drawer bind:visible={open}>
+  <div style="padding: 16px;">
+    <button onclick={() => (open = false)}>✕ 关闭</button>
+    <!-- ... -->
+  </div>
+</Drawer>
+```
+
+## 无障碍
+
+- 根节点和面板都带 `aria-hidden="true"`。**注意**：当前这两个属性是静态的，并不跟随 `visible` 变化——如果需要正确的 ARIA 状态，使用方需自行管理
+- Drawer 不做焦点陷阱。如果是模态场景，请在内容外层包一个 focus trap
+- 不内置 Escape 关闭——需要的话请自行加 `<svelte:window onkeydown={...}/> ` 处理
+
+## 最佳实践
+
+1. **始终使用 `bind:visible`**（不要单向 `visible={...}`）——否则点击遮罩无法回写状态，面板会与外部状态脱节
+2. **关闭时重置内部状态**——如果 Drawer 里放了临时表单，关闭时记得清掉，避免下次打开还显示旧值
+3. **按场景选 `width`**：导航菜单 240–300px，表单/设置 360–480px，移动端 ≤85% 视口宽度
+4. **反向面板用 `theme`**（比如浅色应用里的品牌色深色导航），并在应用 CSS 中定义对应的 `[data-theme="..."]` 规则
+5. **不要嵌套 Drawer**——`z-index: 99` 是共享的，遮罩点击逻辑也假设同时只有一个 Drawer 打开
+
+## 相关组件
+
+- [Dialog](../dialog/README_CN.md) — 居中模态框，可承载任意自定义内容
+- [MessageBox](../message-box/README_CN.md) — 全局模态确认和消息
+- [Toast](../toast/README_CN.md) — 非阻塞的临时通知
+- [Indicator](../indicator/README_CN.md) — 全屏加载指示器
+- [ContextMenu](../context-menu/README_CN.md) — 带键盘导航的右键菜单
+- [Tooltip](../tooltip/README_CN.md) — 悬停式上下文提示

package/dist/overlay/drawer/index.d.ts

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

package/dist/overlay/drawer/index.js

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

package/dist/overlay/indicator/Indicator.svelte.d.ts

@@ -0,0 +1,14 @@
+declare class IndicatorController {
+    message: string;
+    visible: boolean;
+    /**
+     * 显示加载指示器
+     */
+    show(msg: string): void;
+    /**
+     * 隐藏加载指示器
+     */
+    hide(): void;
+}
+declare const indicator: IndicatorController;
+export default indicator;

package/dist/overlay/indicator/Indicator.svelte.js

@@ -0,0 +1,27 @@
+import IndicatorPanel from './IndicatorPanel.svelte';
+import { createSingletonMounter } from '../common/mountSingleton';
+/**
+ * 懒挂载：第一次 show() 时把面板挂到 document.body，后续复用同一个实例。
+ * 不需要用户在 app 根节点手动挂 <IndicatorBoard />。
+ */
+const ensureMounted = createSingletonMounter(() => IndicatorPanel);
+class IndicatorController {
+    message = $state('');
+    visible = $state(false);
+    /**
+     * 显示加载指示器
+     */
+    show(msg) {
+        ensureMounted();
+        this.message = msg;
+        this.visible = true;
+    }
+    /**
+     * 隐藏加载指示器
+     */
+    hide() {
+        this.visible = false;
+    }
+}
+const indicator = new IndicatorController();
+export default indicator;

package/dist/overlay/indicator/IndicatorPanel.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+    import indicator from './Indicator.svelte';
+    import iconLoading from '../../assets/loading.gif';
+</script>
+
+<div
+    class="topside-indicator-board"
+    style="display: {indicator.visible ? 'flex' : 'none'}"
+>
+    <div class="indicator-content">
+        <img src={iconLoading} alt="loading" width="32px" height="32px"/>
+        <span class="indicator-text">{indicator.message}</span>
+    </div>
+</div>
+
+<style>.topside-indicator-board {
+  position: fixed;
+  inset: 0;
+  background-color: var(--topside-color-overlay-mask-surface);
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  /* Was a bare 100, accidentally tied with Popover's z-index; centralized
+     scale bumps this to 110 so an Indicator shown while a Popover is
+     open reliably sits above it. */
+  z-index: var(--topside-z-indicator, 110);
+}
+.topside-indicator-board .indicator-content {
+  margin: 0 auto;
+  min-width: var(--topside-indicator-minimal-size);
+  line-height: 1.5em;
+  padding: var(--topside-indicator-content-margin);
+  box-sizing: border-box;
+  border: 1px solid var(--topside-indicator-color-border);
+  background-color: var(--topside-indicator-color-surface);
+  color: var(--topside-indicator-color);
+  border-radius: var(--topside-indicator-border-radius);
+  box-shadow: var(--topside-indicator-box-shadow);
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  gap: var(--topside-indicator-content-spacing);
+}</style>

package/dist/overlay/indicator/IndicatorPanel.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const IndicatorPanel: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type IndicatorPanel = InstanceType<typeof IndicatorPanel>;
+export default IndicatorPanel;