paseo-kanban 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 breathi3552
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# Paseo Kanban
+
+[简体中文](./README.zh-CN.md)
+
+A lightweight, responsive Kanban board plugin for [Paseo](https://paseo.sh) workspaces. Organize tasks across customizable swimlanes, break them down into subtasks, associate cards with native Paseo projects, and manage workflow status with intuitive drag-and-drop.
+
+---
+
+## Features
+
+- **Flexible Swimlanes**: Default lanes (`To Plan`, `In Progress`, `Done`) with full support for adding, renaming, and deleting custom lanes.
+- **Rich Task Cards**:
+  - Task title and multi-line markdown description.
+  - Subtasks checklist with completion toggles and live progress tracking.
+  - Native Paseo project association.
+- **Project Filtering**: Instantly filter board cards by linked Paseo project to keep context focused.
+- **Smooth Drag-and-Drop**: Real-time hit-testing for reordering cards within lanes and moving cards across lanes.
+- **Versioned State Persistence**: Persists board data through Paseo's settings API with optimistic concurrency control (CAS) to prevent race conditions and accidental overwrites.
+
+---
+
+## Requirements
+
+- **Paseo**: `>= 0.8.0`
+- **Node.js**: `>= 20.0.0` (recommended for development)
+
+---
+
+## Installation & Usage
+
+### Quick Install (Recommended)
+
+No manual build or git cloning needed. You can install directly via npm or GitHub:
+
+**Via NPM (Release package):**
+```bash
+paseo plugin install npm:paseo-kanban
+```
+
+**Via GitHub:**
+```bash
+paseo plugin add breathi3552/paseo-kanban
+```
+
+To explicitly track the latest updates on the `main` branch:
+
+```bash
+paseo plugin add breathi3552/paseo-kanban --ref main
+```
+
+Verify that the plugin is running:
+
+```bash
+paseo plugin ls
+```
+
+Once active, open Paseo. The **Kanban** icon (`PanelsTopLeft`) will appear in the sidebar. Click it to launch the board.
+
+### Local Development
+
+To contribute or debug locally:
+
+```bash
+# 1. Clone repository and install dependencies
+git clone https://github.com/breathi3552/paseo-kanban.git
+cd paseo-kanban
+npm install
+
+# 2. Link this directory into your local Paseo daemon
+paseo plugin link .
+```
+---
+
+## Development & Testing
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Run Tests
+
+Runs unit tests for board domain logic, subtask mutations, and drag hit-testing:
+
+```bash
+npm test
+```
+
+### Type Checking
+
+Validates TypeScript types across client and server entry points:
+
+```bash
+npm run typecheck
+```
+
+---
+
+## Architecture & Design
+
+The complete architectural breakdown and interactive visual diagram are archived in the repository:
+
+- **Interactive Architecture Viewer**: Open [`docs/architecture/paseo-kanban.architecture.html`](./docs/architecture/paseo-kanban.architecture.html) in your browser.
+- **Architecture Schema & Model**: [`docs/architecture/paseo-kanban.architecture.json`](./docs/architecture/paseo-kanban.architecture.json).
+
+---
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,111 @@
+# Paseo 看板插件 (Paseo Kanban)
+
+[English](./README.md)
+
+专为 [Paseo](https://paseo.sh) 工作区打造的轻量响应式看板插件。支持自定义泳道分类、任务子步骤细化、原生 Paseo 项目关联筛选，以及跨泳道流畅拖拽管理。
+
+---
+
+## 核心功能
+
+- **灵活的泳道管理**：开箱即用三列基础泳道（`待规划`、`执行中`、`已完成`），支持自由添加、重命名与删除自定义泳道。
+- **丰富的任务卡片**：
+  - 任务标题与多行描述编辑。
+  - 子步骤清单支持独立增删改、完成状态勾选及实时进度展示。
+  - 支持关联本地已有的 Paseo 项目。
+- **项目维度筛选**：一键按关联的 Paseo 项目过滤看板卡片，聚焦当前目标。
+- **流畅拖拽交互**：精准的拖拽命中测试（Hit-Testing），支持同泳道排序与跨泳道状态流转。
+- **版本化数据持久化**：基于 Paseo 原生 settings API 存储，内置乐观并发版本控制（CAS），杜绝多会话覆写与状态不一致。
+
+---
+
+## 环境要求
+
+- **Paseo**：`>= 0.8.0`
+- **Node.js**：`>= 20.0.0`（开发环境推荐）
+
+---
+
+## 安装使用
+
+### 快速安装（推荐）
+
+无需克隆源码或手动编译，推荐直接使用 Paseo CLI 安装：
+
+**方式一：通过 NPM 官方包安装（推荐）**
+```bash
+paseo plugin install npm:paseo-kanban
+```
+
+**方式二：直接通过 GitHub 仓库安装**
+```bash
+paseo plugin add breathi3552/paseo-kanban
+```
+
+若需显式跟踪 `main` 分支最新更新：
+
+```bash
+paseo plugin add breathi3552/paseo-kanban --ref main
+```
+
+安装后可通过以下命令检查运行状态：
+
+```bash
+paseo plugin ls
+```
+
+状态显示为 `running` 后打开 Paseo，侧边栏将出现 **看板** 入口（图标：`PanelsTopLeft`），点击即可进入看板。
+
+### 本地开发与调试
+
+如需进行本地源码调试或二次开发：
+
+```bash
+# 1. 克隆代码仓库并安装依赖
+git clone https://github.com/breathi3552/paseo-kanban.git
+cd paseo-kanban
+npm install
+
+# 2. 将当前开发目录软链接至本地 Paseo 守护进程
+paseo plugin link .
+```
+---
+
+## 开发与测试
+
+### 安装依赖
+
+```bash
+npm install
+```
+
+### 运行单元测试
+
+执行看板状态模型、并发校验、子步骤更新以及拖拽命中测试的自动化用例：
+
+```bash
+npm test
+```
+
+### 类型检查
+
+校验前端组件与服务端扩展的 TypeScript 类型完整性：
+
+```bash
+npm run typecheck
+```
+
+---
+
+## 架构设计
+
+完整的插件架构图景与交互式全景模型已归档于仓库：
+
+- **交互式架构全景图**：直接使用浏览器打开 [`docs/architecture/paseo-kanban.architecture.html`](./docs/architecture/paseo-kanban.architecture.html) 查看。
+- **架构定义元数据**：[`docs/architecture/paseo-kanban.architecture.json`](./docs/architecture/paseo-kanban.architecture.json)。
+
+---
+
+## 开源协议
+
+MIT

package/client/i18n.tsx

@@ -0,0 +1,328 @@
+import * as React from "react";
+import { useState, useEffect, useMemo } from "react";
+
+export type SupportedLanguage = "zh" | "en";
+
+export type TranslationParams = Record<string, string | number | boolean | null | undefined>;
+
+export const translations = {
+  zh: {
+    "kanban.sidebarTitle": "看板",
+    "kanban.title": "任务看板",
+    "kanban.loading": "正在加载看板数据...",
+    "kanban.stats": "{tasks} 任务 · {lanes} 泳道",
+    "kanban.addLane": "+ 新增泳道",
+    "kanban.newTask": "+ 新建任务",
+    "kanban.refresh": "刷新最新数据",
+    "kanban.loadError": "加载看板配置失败：{error}",
+    "kanban.formatError": "看板配置格式异常：{error}",
+    "kanban.formatErrorHint": "数据未被悄悄覆盖。若需使用默认结构可重置，或重试加载。",
+    "kanban.retryLoad": "重试加载",
+    "kanban.resetDefault": "重置为默认结构",
+    "kanban.saveFailed": "保存失败：{error}",
+    "kanban.conflictError": "保存冲突或错误：{error}",
+    "kanban.filterLabel": "项目筛选:",
+    "kanban.filterAll": "全部",
+    "kanban.filterUnassigned": "未关联项目",
+    "kanban.projectsError": "(项目列表更新受限)",
+    "lane.add": "+ 添加",
+    "lane.manage": "管理",
+    "lane.emptyHint": "暂无卡片，可点击右上角添加或拖动卡片至此",
+    "card.dragHandle": "拖动手柄",
+    "card.subtasksCount": "子步骤 {completed}/{total}",
+    "laneModal.titleEdit": "管理泳道",
+    "laneModal.titleCreate": "新增泳道",
+    "laneModal.nameLabel": "泳道名称 *",
+    "laneModal.namePlaceholder": "例如：待测试、发布中...",
+    "laneModal.cannotDeleteLast": "看板必须至少保留一条泳道，无法删除此泳道。",
+    "laneModal.cannotDeleteHasTasks": "此泳道当前包含 {count} 个任务，需清空或移走任务后方可删除。",
+    "laneModal.deleteLane": "删除此泳道",
+    "laneModal.confirmDeletePrompt": "确认删除？",
+    "laneModal.confirmDelete": "确认删除",
+    "laneModal.cancel": "取消",
+    "laneModal.saving": "保存中...",
+    "laneModal.saveChanges": "保存修改",
+    "laneModal.submitCreate": "添加泳道",
+    "taskModal.titleEdit": "编辑任务",
+    "taskModal.titleCreate": "创建任务",
+    "taskModal.titleLabel": "任务标题 *",
+    "taskModal.titlePlaceholder": "输入任务标题",
+    "taskModal.laneLabel": "所属泳道",
+    "taskModal.projectLabel": "关联项目",
+    "taskModal.noProject": "未关联项目",
+    "taskModal.descLabel": "描述",
+    "taskModal.descPlaceholder": "可选的任务补充描述...",
+    "taskModal.subtasksLabel": "子步骤 ({completed}/{total})",
+    "taskModal.subtaskPlaceholder": "子步骤内容",
+    "taskModal.newSubtaskPlaceholder": "添加新的子步骤...",
+    "taskModal.addStep": "添加步骤",
+    "taskModal.deleteTask": "删除此任务",
+    "taskModal.confirmDeletePrompt": "确定删除？",
+    "taskModal.confirmDelete": "确认删除",
+    "taskModal.cancel": "取消",
+    "taskModal.saving": "保存中...",
+    "taskModal.saveChanges": "保存修改",
+    "taskModal.submitCreate": "创建",
+  },
+  en: {
+    "kanban.sidebarTitle": "Kanban",
+    "kanban.title": "Task Kanban",
+    "kanban.loading": "Loading kanban board data...",
+    "kanban.stats": "{tasks} tasks · {lanes} lanes",
+    "kanban.addLane": "+ Add Lane",
+    "kanban.newTask": "+ New Task",
+    "kanban.refresh": "Refresh latest data",
+    "kanban.loadError": "Failed to load kanban settings: {error}",
+    "kanban.formatError": "Kanban settings format error: {error}",
+    "kanban.formatErrorHint": "Data was not silently overwritten. Reset to default structure if needed, or retry loading.",
+    "kanban.retryLoad": "Retry Loading",
+    "kanban.resetDefault": "Reset to Default",
+    "kanban.saveFailed": "Save failed: {error}",
+    "kanban.conflictError": "Save conflict or error: {error}",
+    "kanban.filterLabel": "Project Filter:",
+    "kanban.filterAll": "All",
+    "kanban.filterUnassigned": "No Project",
+    "kanban.projectsError": "(Project list update restricted)",
+    "lane.add": "+ Add",
+    "lane.manage": "Manage",
+    "lane.emptyHint": "No cards yet. Click '+' in the top right or drag cards here.",
+    "card.dragHandle": "Drag handle",
+    "card.subtasksCount": "Subtasks {completed}/{total}",
+    "laneModal.titleEdit": "Manage Lane",
+    "laneModal.titleCreate": "Add Lane",
+    "laneModal.nameLabel": "Lane Name *",
+    "laneModal.namePlaceholder": "e.g., Testing, In Review...",
+    "laneModal.cannotDeleteLast": "A kanban board must retain at least one lane. Cannot delete this lane.",
+    "laneModal.cannotDeleteHasTasks": "This lane currently contains {count} tasks. Clear or move tasks before deleting.",
+    "laneModal.deleteLane": "Delete Lane",
+    "laneModal.confirmDeletePrompt": "Confirm delete?",
+    "laneModal.confirmDelete": "Confirm Delete",
+    "laneModal.cancel": "Cancel",
+    "laneModal.saving": "Saving...",
+    "laneModal.saveChanges": "Save Changes",
+    "laneModal.submitCreate": "Add Lane",
+    "taskModal.titleEdit": "Edit Task",
+    "taskModal.titleCreate": "Create Task",
+    "taskModal.titleLabel": "Task Title *",
+    "taskModal.titlePlaceholder": "Enter task title",
+    "taskModal.laneLabel": "Lane",
+    "taskModal.projectLabel": "Associated Project",
+    "taskModal.noProject": "No Project",
+    "taskModal.descLabel": "Description",
+    "taskModal.descPlaceholder": "Optional task description...",
+    "taskModal.subtasksLabel": "Subtasks ({completed}/{total})",
+    "taskModal.subtaskPlaceholder": "Subtask content",
+    "taskModal.newSubtaskPlaceholder": "Add a new subtask...",
+    "taskModal.addStep": "Add Step",
+    "taskModal.deleteTask": "Delete Task",
+    "taskModal.confirmDeletePrompt": "Confirm delete?",
+    "taskModal.confirmDelete": "Confirm Delete",
+    "taskModal.cancel": "Cancel",
+    "taskModal.saving": "Saving...",
+    "taskModal.saveChanges": "Save Changes",
+    "taskModal.submitCreate": "Create",
+  },
+} as const;
+
+export type TranslationKey = keyof typeof translations.zh;
+
+export function normalizeLanguage(locale?: string | null): SupportedLanguage {
+  if (!locale) return "en";
+  return locale.trim().toLowerCase().startsWith("zh") ? "zh" : "en";
+}
+
+let languageOverride: SupportedLanguage | null = null;
+
+export function setLanguageOverride(lang: SupportedLanguage | null): void {
+  languageOverride = lang;
+  notifyLanguageChange();
+}
+
+export function getLanguageOverride(): SupportedLanguage | null {
+  return languageOverride;
+}
+
+export interface DetectLanguageOptions {
+  locale?: string;
+  language?: string;
+  host?: {
+    id?: string;
+    label?: string;
+    locale?: string;
+    language?: string;
+  };
+}
+
+interface EnvironmentGlobals {
+  localStorage?: {
+    getItem(key: string): string | null;
+  };
+  document?: {
+    documentElement?: {
+      lang?: string;
+    };
+  };
+  navigator?: {
+    language?: string;
+  };
+  window?: {
+    addEventListener(event: string, listener: (event: { key?: string }) => void): void;
+  };
+  i18n?: {
+    language?: string;
+  };
+}
+
+const env = globalThis as typeof globalThis & EnvironmentGlobals;
+
+export function detectPaseoLanguage(hostProps?: DetectLanguageOptions): SupportedLanguage {
+  if (languageOverride) {
+    return languageOverride;
+  }
+
+  const propLocale =
+    hostProps?.locale ??
+    hostProps?.language ??
+    hostProps?.host?.locale ??
+    hostProps?.host?.language;
+  if (propLocale && propLocale !== "system") {
+    return normalizeLanguage(propLocale);
+  }
+
+  if (env.localStorage) {
+    try {
+      const raw = env.localStorage.getItem("@paseo:app-settings");
+      if (raw) {
+        const parsed = JSON.parse(raw);
+        if (parsed?.language && parsed.language !== "system") {
+          return normalizeLanguage(parsed.language);
+        }
+      }
+    } catch {}
+  }
+
+  const docLang = env.document?.documentElement?.lang;
+  if (docLang) {
+    return normalizeLanguage(docLang);
+  }
+
+  const i18nLang = env.i18n?.language;
+  if (i18nLang) {
+    return normalizeLanguage(i18nLang);
+  }
+
+  const intlLocale =
+    typeof Intl?.DateTimeFormat === "function"
+      ? Intl.DateTimeFormat().resolvedOptions().locale
+      : undefined;
+  if (intlLocale) {
+    return normalizeLanguage(intlLocale);
+  }
+
+  const navLocale = env.navigator?.language;
+  if (navLocale) {
+    return normalizeLanguage(navLocale);
+  }
+
+  return "en";
+}
+
+let currentLanguage: SupportedLanguage = detectPaseoLanguage();
+const listeners = new Set<(lang: SupportedLanguage) => void>();
+let globalListenersInitialized = false;
+
+function notifyLanguageChange() {
+  const next = detectPaseoLanguage();
+  if (next !== currentLanguage) {
+    currentLanguage = next;
+    listeners.forEach((fn) => fn(currentLanguage));
+  }
+}
+
+function ensureGlobalListeners() {
+  if (globalListenersInitialized) return;
+  globalListenersInitialized = true;
+
+  env.window?.addEventListener("storage", (e) => {
+    if (e.key === "@paseo:app-settings") {
+      notifyLanguageChange();
+    }
+  });
+
+  env.window?.addEventListener("focus", () => {
+    notifyLanguageChange();
+  });
+}
+
+export function getLanguage(hostProps?: DetectLanguageOptions): SupportedLanguage {
+  if (hostProps) {
+    return detectPaseoLanguage(hostProps);
+  }
+  return currentLanguage;
+}
+
+export function subscribeLanguage(listener: (lang: SupportedLanguage) => void): () => void {
+  listeners.add(listener);
+  ensureGlobalListeners();
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+export function formatString(template: string, params?: TranslationParams): string {
+  if (!params) return template;
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    return params[key] != null ? String(params[key]) : match;
+  });
+}
+
+export function t(
+  key: TranslationKey,
+  langOrParams?: SupportedLanguage | TranslationParams,
+  params?: TranslationParams
+): string {
+  let lang: SupportedLanguage;
+  let finalParams: TranslationParams | undefined;
+
+  if (typeof langOrParams === "string") {
+    lang = langOrParams;
+    finalParams = params;
+  } else {
+    lang = currentLanguage;
+    finalParams = langOrParams;
+  }
+
+  const dict = translations[lang] ?? translations.en;
+  const raw = dict[key] ?? translations.en[key] ?? key;
+  return formatString(raw, finalParams);
+}
+
+export interface I18nContextValue {
+  language: SupportedLanguage;
+  t: (key: TranslationKey, params?: TranslationParams) => string;
+}
+
+export function useI18n(hostProps?: DetectLanguageOptions): I18nContextValue {
+  const [lang, setLang] = useState<SupportedLanguage>(() => detectPaseoLanguage(hostProps));
+
+  useEffect(() => {
+    ensureGlobalListeners();
+    const immediate = detectPaseoLanguage(hostProps);
+    if (immediate !== lang) {
+      setLang(immediate);
+    }
+    return subscribeLanguage((newLang) => {
+      setLang(newLang);
+    });
+  }, [hostProps?.host?.language, hostProps?.locale, hostProps?.language]);
+
+  const tBound = useMemo(
+    () => (key: TranslationKey, params?: TranslationParams) => t(key, lang, params),
+    [lang]
+  );
+
+  return {
+    language: lang,
+    t: tBound,
+  };
+}