@rinova/playground 0.1.4 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @rinova/playground
 
-Vue3 的「文件即场景」组件演示框架。往 `src/scenes/` 里放 `.vue` 文件，侧栏、预览、源码面板、入参/出参面板自己就长出来了 —— 没有注册 API，没有配置要改。
+Vue3 的「文件即场景」组件演示框架。往 `src/scenes/` 里放 `.vue` 文件，侧栏、预览、源码面板、输入/输出面板自己就长出来了 —— 没有注册 API，没有配置要改。
 
 ```bash
 pnpm add @rinova/playground
@@ -83,12 +83,13 @@ const size = ref<'sm' | 'md' | 'lg'>('lg')
 | `sources` | `true` | 是否显示源码面板 |
 | `codeViewer` | `'monaco'` | `'monaco'` 只读编辑器 / `'shiki'` 静态高亮块（更轻，不加载编辑器 worker） |
 | `theme.ui` | `'auto'` | `'light' \| 'dark' \| 'auto'` |
-| `theme.code` | 随明暗用 `vitesse-light` / `vitesse-dark` | **v0.1 尚未接线，改这个值暂时无效** |
 | `exclude` | — | 排除的 glob（相对 `scenes` 根） |
 | `base` | Vite 默认 | 部署子路径 |
 | `port` | Vite 默认（5173） | dev server 端口 |
 | `components` | — | 契约清单要扫的组件 glob；不配则不生成 `.playground/manifest.json` |
 | `tsconfig` | 项目根 `tsconfig.json` | 组件契约提取用的 tsconfig |
+| `groups` | — | 分组（`scenes` 下一级目录名）→ 侧栏显示名，**声明顺序即侧栏顺序**：`{ 'tao-common': 'Tao 通用组件' }` |
+| `groupIndex` | `false` | 为每个分组自动合成一个「概览」落地页，点分组标题即可进入 |
 
 ## 场景内 API
 
@@ -105,7 +106,7 @@ const size = ref<'sm' | 'md' | 'lg'>('lg')
 
 `SceneMeta` 类型里还有 `payload` 字段，但构建期拿不到组件状态，**请改用下面的 `useSceneArgs` / `useSceneOutput`**。
 
-### useSceneArgs —— 入参面板
+### useSceneArgs —— 输入面板
 
 ```ts
 const args = useSceneArgs(
@@ -123,13 +124,28 @@ const args = useSceneArgs(
 
 > 字面量会被拓宽成 `string`，直接传给只接受联合类型的 prop 会报 TS2322，所以写 `'md' as 'sm' | 'md' | 'lg'`。
 
-### useSceneOutput —— 出参快照
+### useSceneOutput —— 输出快照
 
 ```ts
 useSceneOutput(() => ({ size: args.size, clicked: count.value }))
 ```
 
-面板以 400ms 轮询这个 getter，把返回值显示在出参区。
+面板以 400ms 轮询这个 getter，把返回值显示在输出区。
+
+### 一个场景多个 demo —— 参数槽位
+
+同一场景里放多个 demo 时，各自调用一次并在选项里写 `slot`，面板会按槽位名分块，
+互不干扰（改一块的输入只影响那一个 demo）：
+
+```ts
+const primary = useSceneArgs({ label: '主按钮', size: 'md' }, { slot: '主按钮' })
+const ghost = useSceneArgs({ label: '次按钮', size: 'sm' }, { slot: '次按钮' })
+
+useSceneOutput(() => ({ clicked: primaryCount.value }), '主按钮')
+useSceneOutput(() => ({ clicked: ghostCount.value }), '次按钮')
+```
+
+槽位按代码里声明的顺序排列；只有一块时不显示槽位标题。
 
 ### toast
 
@@ -142,6 +158,7 @@ toast('保存失败', 'error')     // 'info' | 'success' | 'warning' | 'error'
 
 ## 样式约定
 
+- 只需引入一次 `@rinova/playground/style.css`（外壳样式）。**编辑器界面样式由包内按需加载**：打开代码面板时才会去拉 `@rinova/playground/editor.css`（≈125 KB gzip），不用手动引入；配 `codeViewer: 'shiki'` 的项目则永远不加载它。
 - 场景写 `<style scoped lang="less">`（使用方需要装 `less`）。**v0.1 没有 DOM 隔离**，非 scoped 样式会污染外壳。
 - 不要硬编码颜色，用外壳暴露的 12 个变量，明暗主题自动切换：
 
@@ -156,7 +173,7 @@ toast('保存失败', 'error')     // 'info' | 'success' | 'warning' | 'error'
 
 - 场景与外壳无 DOM 隔离，必须写 scoped
 - 源码面板只读，不支持编辑（实时预览也已明确不做：只在 dev 可用，价值不足）
-- `theme.code` 未接线
+- 代码配色随外壳明暗固定使用 `light-plus` / `tokyo-night`，暂不提供配置项
 - 只支持 Vue3，不支持 React / Svelte
 
 ## 相关包