@snap-rail/framework-shadcn 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,21 @@
-# Temporary Holding Version
+# snap-rail-framework-shadcn
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+界面框架插件（clientOnly、单活 `snapRail.exclusive: 'framework'`）：槽位词汇、
+renderer runtime + Shell、shadcn 风格共享原语、主题令牌（预编译 tailwind 输出
+随 zip 内联）、settings/session/variables/workflows 服务与 fallback 布局。
+
+组件插件经 `requires: ['@snap-rail/framework-shadcn@^0.1']` 绑定本框架（绑定即依赖）；框架不匹配装不上。
+构建链：tsc（lib/types）→ tailwind（lib-client/theme.css）→ tsdown（lib 面 +
+clientBundle 工厂包）。
+
+```sh
+pnpm install   # @snap-rail/* 来自 Gitea npm registry（见 .npmrc）
+pnpm build     # tsc + tailwind + tsdown
+pnpm test      # 槽位/主题/原语/变量/工作流/fallback/binding（happy-dom）
+pnpm pack      # snap-rail-plugin pack . --out dist（本地）
+```
+
+发版：打 `v*` tag → CI 构建、测试、签名打包并上传到本仓 Release。
+
+注：跨套件的集成用例（引导整套件页面的 boot）随套件仓走——框架仓只测
+框架自身与通用住户缝。

package/docs/framework-authoring.md

@@ -0,0 +1,59 @@
+# 框架作者指南
+
+snap-rail 的 UI 框架是**普通插件**：zip 发行、互斥组 `framework` 单活、
+clientOnly。任何满足这份契约的包都能与官方框架平权竞争——换框架 = 换生态
+是双向的。本指南是一个框架包要对外承诺的全部面。
+
+## 一、框架包 = 一包一体两面
+
+- **运行时（终端 zip）**：clientOnly，client 入口默认导出
+  `{ seeds: { ui, slots, semantic, settings-pages?, session?, workflows?,
+  variables?, runtime, fallback? } }`——壳 require 后逐 id
+  `system.seed('<包>/<key>', 实例)`，所有 Component 与你共享同一份实例。
+  词汇表是**运行时值**（`register(ctx, IDS.menu, …)` 的参数），所以 SDK
+  不是附带类型，就是这份代码。
+- **开发期 SDK（npm 包）**：同一个包的 `exports` 子路径——
+  `./slots`（词汇 + 类型）、`./semantic`（view/layout/navigation 贡献
+  契约）、`./ui`（原语类型）、`./templates`（脚手架）、`./docs`（本指南
+  与 token 参考）。组件作者 devDependency 你的包，构建期拿类型，运行期
+  从种子表拿实例。
+
+## 二、插槽词汇与占位模式
+
+- 词汇用 `as const` 对象 + 字面量联合声明（新框架用
+  `@snap-rail/plugin-kit` 的 `defineSlotVocabulary`——定义即校验形状，
+  消费者得到自动补全与编译期防错；`custom:<publisher>.<name>` 是保留的
+  扩展命名空间）。
+- 每个槽声明占位模式：`stack`（全部住户按 order 渲染——菜单、动作区）
+  或 `single`（按 `precedence` 选出唯一胜者——titlebar、main）。single
+  槽的内置默认注册 `precedence: 0`，三方覆盖者注册更高值，**卸载覆盖者
+  自动回退默认**（默认只是被遮蔽，不被销毁）。
+- 禁止裸字符串槽 id——一律走词汇常量（doctor 会扫）。
+
+## 三、作者模式规约（重要）
+
+框架包只含：Shell + 槽注册表 + runtime + fallback 兜底。**一切具体住户
+（默认菜单组件、默认 titlebar）都是独立组件插件**——于是「卸掉默认
+titlebar、装一个三方新 titlebar」就是普通插件装卸。fallback 是降解地板
+（零布局时兜底、其他 layout 注册即让位），不算住户。
+
+## 四、生态三层
+
+1. 框架作者：发 zip（feed）+ 发 npm（SDK 面）。
+2. 组件/扩展库作者：`snap-rail-plugin init --template ui-view|ui-extension
+   --framework <你的包>`；manifest 声明 `requires: ['<你的包>@^0.1']`
+   （绑定即依赖，启用预检强制；主版本不匹配拒装）与 `client.externalSeeds`
+   （require 的贡献种子 id——打包器据此 externalize，运行期共享你的单
+   实例；提供方缺席时启用被拒绝）。
+3. 终端用户：装你的框架 + 装任意绑定它的组件，即装即用；装了别的框架，
+   绑定不匹配的组件不挂载（fail-loud，双向保护）。
+
+## 五、发布检查单
+
+- [ ] `snapRail.exclusive: 'framework'`、`clientOnly: true`、
+      `client.seeds` 完整
+- [ ] zip 内预编译 tailwind 输出（theme 令牌随 zip）
+- [ ] npm 包 exports 齐全（slots/semantic/ui/templates/docs）
+- [ ] 模板与指南随包（`snap-rail-plugin init --framework <你的包>` 可用）
+- [ ] 版本 semver：种子 id 集或词汇变更 = minor+；破坏性 = major
+      （组件的 externalSeeds 声明会因 major 不满足而拒绝启用）

package/lib/fallback.js

@@ -0,0 +1,307 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import "@snap-rail/cordis";
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+import { Fragment, useEffect, useState } from "react";
+import { Slot } from "@radix-ui/react-slot";
+import { cva } from "class-variance-authority";
+import "@radix-ui/react-switch";
+import "@radix-ui/react-tooltip";
+import "@radix-ui/react-scroll-area";
+import "@radix-ui/react-dialog";
+import "@radix-ui/react-label";
+import "@radix-ui/react-checkbox";
+import "@radix-ui/react-progress";
+import "@radix-ui/react-radio-group";
+import "@radix-ui/react-tabs";
+import "@radix-ui/react-collapsible";
+import { z } from "zod";
+//#region lib/types/slots.js
+/** Stable semantic slot names shared by every layout implementation. */
+const UI_SLOT_IDS = {
+	layout: "shell.layout",
+	titlebar: "shell.titlebar",
+	titlebarActions: "shell.titlebar.actions",
+	menu: "shell.menu",
+	sidebar: "shell.sidebar",
+	main: "shell.main",
+	view: "shell.view",
+	statusbar: "shell.statusbar",
+	overlay: "shell.overlay"
+};
+new Set(Object.values(UI_SLOT_IDS));
+/**
+* The mode table for the standard slots — the framework owns it.
+*
+* `titlebar` and `main` are `single`: exactly one tenant renders (a skin or
+* replacement displaces the default and falls back on unload). `layout`
+* stays `stack` on purpose — the settings dialog is a permanent overlay
+* occupant beside the active layout, and the fallback shell yields by
+* counting; every other slot collects contributions.
+*/
+const UI_SLOT_MODES = {
+	[UI_SLOT_IDS.layout]: "stack",
+	[UI_SLOT_IDS.titlebar]: "single",
+	[UI_SLOT_IDS.titlebarActions]: "stack",
+	[UI_SLOT_IDS.menu]: "stack",
+	[UI_SLOT_IDS.sidebar]: "stack",
+	[UI_SLOT_IDS.main]: "single",
+	[UI_SLOT_IDS.view]: "stack",
+	[UI_SLOT_IDS.statusbar]: "stack",
+	[UI_SLOT_IDS.overlay]: "stack"
+};
+new Map(Object.entries(UI_SLOT_MODES));
+//#endregion
+//#region lib/types/ui/utils.js
+/**
+* Class-name combiner: clsx joins, tailwind-merge resolves conflicting
+* Tailwind utilities with the last one winning — the shadcn convention.
+*
+* @module @snap-rail/framework-shadcn/ui/utils
+*/
+/**
+* Merge conditional class names into one Tailwind-aware string.
+* @param inputs - class values (strings, arrays, conditional objects).
+* @returns the merged class string.
+*/
+function cn(...inputs) {
+	return twMerge(clsx(inputs));
+}
+//#endregion
+//#region lib/types/ui/hooks.js
+/**
+* Shared React recipes over the client runtime's event fabric.
+*
+* @module @snap-rail/framework-shadcn/ui/hooks
+*/
+/**
+* Re-render the component whenever any of the named ctx events fires —
+* the standard "surface follows the seam" tick. The cordis import is
+* type-only: this module stays a pure React utility at runtime.
+*
+* @param ctx - the plugin context whose events drive the refresh.
+* @param events - event names to listen on (identity is not part of the
+* effect key; a freshly built array literal is fine).
+*/
+function useRefresh(ctx, events) {
+	const [, setTick] = useState(0);
+	const key = events.join("\n");
+	useEffect(() => {
+		const bump = () => setTick((value) => value + 1);
+		const detachers = (key === "" ? [] : key.split("\n")).map((event) => ctx.on(event, bump));
+		return () => {
+			for (const detach of detachers) detach();
+		};
+	}, [ctx, key]);
+}
+//#endregion
+//#region lib/types/ui/button.js
+/**
+* Button: cva variants over a native button. Ghost/outline cover chrome
+* surfaces (titlebar, panel toggles); `icon` size squares the padding for
+* glyph-only controls.
+*
+* @module @snap-rail/framework-shadcn/ui/button
+*/
+const buttonVariants = cva("inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-base font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0", {
+	variants: {
+		variant: {
+			default: "bg-primary text-primary-foreground hover:bg-primary/90",
+			destructive: "bg-destructive/90 text-destructive-foreground hover:bg-destructive",
+			outline: "border border-border bg-transparent hover:bg-accent hover:text-accent-foreground",
+			secondary: "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+			ghost: "hover:bg-accent hover:text-accent-foreground",
+			link: "text-primary underline-offset-4 hover:underline"
+		},
+		size: {
+			xl: "h-16 px-8 text-lg",
+			lg: "h-14 px-6 text-lg",
+			default: "h-12 px-5 py-1.5",
+			sm: "h-10 px-4 text-sm",
+			icon: "h-12 w-12"
+		}
+	},
+	defaultVariants: {
+		variant: "default",
+		size: "default"
+	}
+});
+/** A themed button; `asChild` renders the child element instead. */
+function Button({ className, variant, size, asChild = false, ...props }) {
+	return jsx(asChild ? Slot : "button", {
+		className: cn(buttonVariants({
+			variant,
+			size
+		}), className),
+		...props
+	});
+}
+cva("inline-flex items-center gap-1 rounded-md border px-2.5 py-1 text-sm font-medium whitespace-nowrap", {
+	variants: { variant: {
+		default: "border-transparent bg-primary text-primary-foreground",
+		secondary: "border-transparent bg-secondary text-secondary-foreground",
+		success: "border-transparent bg-success/15 text-success",
+		warning: "border-transparent bg-warning/15 text-warning",
+		destructive: "border-transparent bg-destructive/15 text-destructive",
+		outline: "text-muted-foreground"
+	} },
+	defaultVariants: { variant: "default" }
+});
+z.object({ mode: z.enum([
+	"system",
+	"light",
+	"dark"
+]) });
+//#endregion
+//#region lib/types/fallback.js
+/** The settings dialog's occupant id (a Dialog portal, not a layout). */
+const SETTINGS_OCCUPANT_ID = "settings-dialog";
+/** Window-control glyphs; inline so the shell needs no icon dependency. */
+function ControlIcons(props) {
+	const base = "flex h-10 w-10 items-center justify-center text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground";
+	return jsxs("div", {
+		className: "flex items-center",
+		children: [
+			jsx("button", {
+				type: "button",
+				"aria-label": "最小化",
+				className: base,
+				onClick: props.onMinimize,
+				children: jsx("svg", {
+					viewBox: "0 0 12 12",
+					className: "h-3 w-3",
+					fill: "none",
+					children: jsx("path", {
+						d: "M2 6h8",
+						stroke: "currentColor",
+						strokeWidth: "1.4"
+					})
+				})
+			}),
+			jsx("button", {
+				type: "button",
+				"aria-label": "最大化",
+				className: base,
+				onClick: props.onToggleMaximize,
+				children: jsx("svg", {
+					viewBox: "0 0 12 12",
+					className: "h-3 w-3",
+					fill: "none",
+					children: jsx("rect", {
+						x: "2.5",
+						y: "2.5",
+						width: "7",
+						height: "7",
+						stroke: "currentColor",
+						strokeWidth: "1.2"
+					})
+				})
+			}),
+			jsx("button", {
+				type: "button",
+				"aria-label": "关闭",
+				className: `${base} hover:bg-destructive hover:text-white`,
+				onClick: props.onClose,
+				children: jsx("svg", {
+					viewBox: "0 0 12 12",
+					className: "h-3 w-3",
+					fill: "none",
+					children: jsx("path", {
+						d: "m3 3 6 6M9 3l-6 6",
+						stroke: "currentColor",
+						strokeWidth: "1.4"
+					})
+				})
+			})
+		]
+	});
+}
+/** The fallback body: minimal titlebar + install guidance. */
+function FallbackShell(props) {
+	useRefresh(props.ctx, ["ui/slot-changed", "settings/open-changed"]);
+	if (props.ctx.uiSlots.list(UI_SLOT_IDS.layout).filter((occupant) => occupant.id !== SETTINGS_OCCUPANT_ID).length > 1) return null;
+	const windowControl = (action) => {
+		props.link.call("window.control", { action }).catch(() => void 0);
+	};
+	return jsxs("div", {
+		className: "flex h-full flex-col",
+		"data-region": "fallback-shell",
+		children: [jsxs("div", {
+			className: "flex h-10 shrink-0 items-center justify-between border-b border-border pl-4 select-none",
+			style: { WebkitAppRegion: "drag" },
+			children: [jsx("span", {
+				className: "text-sm text-muted-foreground",
+				children: "snap-rail"
+			}), jsxs("div", {
+				className: "flex items-center",
+				style: { WebkitAppRegion: "no-drag" },
+				children: [
+					props.ctx.uiSlots.list(UI_SLOT_IDS.titlebarActions).map((occupant) => jsx(Fragment, { children: occupant.render() }, occupant.id)),
+					jsx("button", {
+						type: "button",
+						"aria-label": "设置",
+						className: "flex h-10 w-10 items-center justify-center text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground",
+						onClick: () => props.ctx.settingsPages.open(),
+						children: jsxs("svg", {
+							viewBox: "0 0 24 24",
+							className: "h-5 w-5",
+							fill: "none",
+							stroke: "currentColor",
+							strokeWidth: "1.6",
+							children: [jsx("circle", {
+								cx: "12",
+								cy: "12",
+								r: "3.2"
+							}), jsx("path", { d: "M19.4 15a1.7 1.7 0 0 0 .34 1.87l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.7 1.7 0 0 0-1.87-.34 1.7 1.7 0 0 0-1 1.55V21a2 2 0 1 1-4 0v-.09a1.7 1.7 0 0 0-1-1.55 1.7 1.7 0 0 0-1.87.34l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.7 1.7 0 0 0 .34-1.87 1.7 1.7 0 0 0-1.55-1H3a2 2 0 1 1 0-4h.09a1.7 1.7 0 0 0 1.55-1 1.7 1.7 0 0 0-.34-1.87l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.7 1.7 0 0 0 1.87.34h0a1.7 1.7 0 0 0 1-1.55V3a2 2 0 1 1 4 0v.09a1.7 1.7 0 0 0 1 1.55h0a1.7 1.7 0 0 0 1.87-.34l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.7 1.7 0 0 0-.34 1.87v0a1.7 1.7 0 0 0 1.55 1H21a2 2 0 1 1 0 4h-.09a1.7 1.7 0 0 0-1.55 1Z" })]
+						})
+					}),
+					jsx(ControlIcons, {
+						onMinimize: () => windowControl("minimize"),
+						onToggleMaximize: () => windowControl("toggle-maximize"),
+						onClose: () => windowControl("close")
+					})
+				]
+			})]
+		}), jsx("div", {
+			className: "flex min-h-0 flex-1 items-center justify-center p-6",
+			children: jsxs("div", {
+				className: "grid max-w-md gap-4 text-center",
+				children: [
+					jsx("div", {
+						className: "text-xl font-medium text-foreground",
+						children: "尚未激活业务套件"
+					}),
+					jsx("p", {
+						className: "text-sm text-muted-foreground",
+						children: "打开设置的「插件管理」页，安装并激活一个业务套件；通讯驱动也在同一处安装。"
+					}),
+					jsx("div", { children: jsx(Button, {
+						"data-fallback-open-settings": true,
+						onClick: () => props.ctx.settingsPages.open(),
+						children: "打开设置"
+					}) })
+				]
+			})
+		})]
+	});
+}
+/** The fallback shell occupant. */
+const fallbackShellPlugin = {
+	name: "framework fallback",
+	inject: ["uiSlots", "settingsPages"],
+	apply(ctx) {
+		const client = ctx.get("client");
+		ctx.uiSlots.register(ctx, UI_SLOT_IDS.layout, {
+			id: "fallback-shell",
+			order: 200,
+			render() {
+				return jsx(FallbackShell, {
+					ctx,
+					link: client.link
+				});
+			}
+		});
+	}
+};
+//#endregion
+export { fallbackShellPlugin as default };