create-bubbles 0.1.27 → 0.1.28

package/template-pnpm-vp-monorepo/apps/docs/guide/workspace.md

@@ -0,0 +1,84 @@
+# 工作区约定
+
+## 目录职责
+
+```text
+apps/
+  playground/       示例应用
+  docs/             VitePress 文档站点
+packages/
+  utils/            内部共享工具包
+tsconfig/           共享 TypeScript 配置（base / node / vue）
+```
+
+`apps/*` 和 `packages/*` 由 `pnpm-workspace.yaml` 纳入工作区。根目录负责公共命令、依赖版本目录、锁文件、质量检查和 CI；每个子项目维护自己的入口、依赖和脚本。
+
+根项目、`docs`、`playground` 和 `@bubblesjs/utils` 均为 `private: true`，目前没有 npm 发布对象。应用名称可继续使用 `playground`、`docs` 等，`@bubblesjs` scope 同样用于内部共享包标识。共享包放在 `packages/`，提供明确的 `exports` 和类型入口。共享 TypeScript 配置放在根目录 `tsconfig/`，通过相对路径复用。
+
+## 外部依赖使用 `catalog:`
+
+所有工作区共享的第三方依赖版本统一声明在根 `pnpm-workspace.yaml` 的 `catalog` 中：
+
+```yaml
+catalog:
+  vue: ^3.5.0
+```
+
+子项目只声明需要哪些依赖：
+
+```json
+{
+  "dependencies": {
+    "vue": "catalog:"
+  }
+}
+```
+
+上面的版本仅用于展示格式；以仓库内的目录配置为准。添加外部依赖时，先在 `catalog` 中确定版本，再在实际使用它的项目中写 `catalog:`。运行 `pnpm install`，将清单和根锁文件一起提交。
+
+## 内部依赖使用 `workspace:*`
+
+应用或其他包依赖共享包时，按包名声明。例如 Playground 的内部依赖：
+
+```json
+{
+  "dependencies": {
+    "@bubblesjs/utils": "workspace:*"
+  }
+}
+```
+
+`workspace:*` 要求使用当前仓库内的包，避免安装同名的远程包。打包或发布时，pnpm 会把该协议转换为实际版本。
+
+应用可配置源码别名获得即时开发反馈；发布包仍需要正确的 `exports`、构建结果和类型声明。使用者导入包名，避免引用其他项目的内部文件路径。
+
+## 添加共享包
+
+1. 在 `packages/` 中创建目录，例如 `packages/math/`。
+2. 添加 `package.json`，设置唯一的包名，例如 `@bubblesjs/math`。内部共享包设置 `private: true`。若将来需要 npm 发布，须显式移除 `private: true`，设置 `publishConfig.access` 为 `public`，并完善 `version`、`type`、`files`、`exports` 和发布元信息；复制 utils 创建公开包时同样需要这些步骤。
+3. 添加 `src/index.ts` 作为公共入口，将需要对外开放的 API 显式导出。
+4. 参考 `packages/utils/` 配置构建、测试和类型检查，继承根目录 `tsconfig/` 中适用的配置。
+5. 在使用它的项目中添加 `workspace:*` 依赖。需要源码开发时，同步配置 Vite 与 TypeScript 别名。
+6. 执行 `pnpm install`、`pnpm typecheck`、`pnpm test`、`pnpm build`。为新共享包补充本地产物检查，再执行 `pnpm verify:packages`；这个命令不执行 npm 发布。
+7. 如需 npm 发布，补充发布元信息，并添加 changeset。
+
+一个包只对外公开稳定的入口。把业务代码拆成包时，先确认它需要独立复用或发布，再划定依赖边界。
+
+## 添加应用
+
+1. 在 `apps/` 中创建目录，例如 `apps/admin/`。
+2. 添加唯一的 `package.json` 名称和 `private: true`。声明 `dev`、`build`、`typecheck` 等实际需要的脚本。
+3. 使用 `catalog:` 引用外部依赖，使用 `workspace:*` 引用共享包。
+4. 继承共享 TypeScript 配置，并添加对应框架的构建配置。
+5. 执行 `pnpm install`，然后通过 `pnpm --filter admin dev` 启动该应用。
+6. 将常用入口补充到根脚本或文档中，确保全工作区构建和类型检查都能运行。
+
+应用之间通过共享包复用代码，避免一个应用直接导入另一个应用的源码。
+
+## 共享配置和文档
+
+Vue 应用与文档通过 `"extends": "../../tsconfig/vue.json"` 继承共享配置；Node / 库使用 `tsconfig/node.json`，基础约束定义在 `tsconfig/base.json`。覆盖配置时只声明项目所需的差异。
+
+`tsconfig/` 是普通配置目录，没有 `package.json`，不参与工作区依赖管理或 npm 发布。子项目通过相对路径继承，无需声明配置包依赖。
+
+文档页面放在 `apps/docs/`，使用 Markdown 编写并由 VitePress 构建。当前文档站点独立运行；共享包的实际使用由 Playground 示例应用展示。

package/template-pnpm-vp-monorepo/apps/docs/index.md

@@ -0,0 +1,22 @@
+---
+layout: home
+title: 首页
+hero:
+  name: Monorepo Starter
+  text: 把应用、共享包与文档放进同一个工作区
+  tagline: pnpm 管理依赖，Vite+ 编排质量与构建，Changesets 记录版本变更。复制模板后即可开始自己的项目。
+  actions:
+    - theme: brand
+      text: 开始使用
+      link: /guide/getting-started
+    - theme: alt
+      text: 查看工作区约定
+      link: /guide/workspace
+features:
+  - title: 应用与共享包
+    details: apps/ 放置应用和独立运行的文档站点，packages/ 放置可独立构建的内部共享代码。
+  - title: 集中管理依赖
+    details: 外部依赖使用 catalog:，工作区依赖使用 workspace:*，在根目录维护版本与锁文件。
+  - title: 可验证的包产物
+    details: 类型、测试、构建与包产物检查贯穿本地和 CI，Changesets 为将来的公开包保留版本变更流程。
+---

package/template-pnpm-vp-monorepo/apps/docs/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "docs",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vp run bundle",
+    "dev": "vitepress dev . --port 5174 --strictPort",
+    "preview": "vitepress preview .",
+    "typecheck": "vue-tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "vue": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plus": "catalog:",
+    "vitepress": "catalog:",
+    "vue-tsc": "catalog:"
+  }
+}

package/template-pnpm-vp-monorepo/apps/docs/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig/vue.json",
+  "compilerOptions": {
+    "types": ["node", "vite/client"]
+  },
+  "include": ["vite.config.ts", ".vitepress/**/*.ts", ".vitepress/**/*.mts", ".vitepress/**/*.vue"]
+}

package/template-pnpm-vp-monorepo/apps/docs/vite.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vite-plus";
+
+export default defineConfig({
+  run: {
+    tasks: {
+      bundle: {
+        command: "vitepress build .",
+        cache: { env: ["DOCS_BASE", "NODE_ENV"] },
+      },
+    },
+  },
+});

package/template-pnpm-vp-monorepo/apps/playground/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#edf3f9" />
+    <meta name="description" content="Vue 与共享工具包组成的 Monorepo 模板开发工作台。" />
+    <title>Mono · 开发工作台</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template-pnpm-vp-monorepo/apps/playground/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "playground",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "vp run bundle",
+    "dev": "vp dev",
+    "preview": "vp preview",
+    "typecheck": "vue-tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@bubblesjs/utils": "workspace:*",
+    "vue": "catalog:"
+  },
+  "devDependencies": {
+    "@types/node": "catalog:",
+    "@vitejs/plugin-vue": "catalog:",
+    "typescript": "catalog:",
+    "vite": "catalog:",
+    "vite-plus": "catalog:",
+    "vue-tsc": "catalog:"
+  }
+}

package/template-pnpm-vp-monorepo/apps/playground/src/App.vue

@@ -0,0 +1,214 @@
+<script setup lang="ts">
+import { clamp } from "@bubblesjs/utils";
+import { computed, ref } from "vue";
+
+const inputValue = ref<number | string>(128);
+const minimum = ref<number | string>(0);
+const maximum = ref<number | string>(100);
+const presets = [
+  { label: "低于下限", value: -24 },
+  { label: "落在区间", value: 48 },
+  { label: "高于上限", value: 128 },
+];
+
+function isValidNumber(value: number | string) {
+  return value !== "" && Number.isFinite(Number(value)) && Math.abs(Number(value)) <= 1000;
+}
+
+const error = computed(() => {
+  if (![inputValue.value, minimum.value, maximum.value].every(isValidNumber)) {
+    return "请为三个输入填写 −1000 到 1000 之间的数值。";
+  }
+  if (Number(minimum.value) > Number(maximum.value)) {
+    return "下限不能大于上限，请调整区间。";
+  }
+  return "";
+});
+
+const result = computed(() =>
+  error.value
+    ? null
+    : clamp(Number(inputValue.value), Number(minimum.value), Number(maximum.value)),
+);
+
+const scale = computed(() => {
+  if (error.value) return { start: -40, end: 160 };
+  const start = Math.min(Number(inputValue.value), Number(minimum.value), 0);
+  const end = Math.max(Number(inputValue.value), Number(maximum.value), 100);
+  const padding = Math.max((end - start) * 0.12, 10);
+  return { start: start - padding, end: end + padding };
+});
+
+function position(value: number | string) {
+  return `${((Number(value) - scale.value.start) / (scale.value.end - scale.value.start)) * 100}%`;
+}
+
+function displayNumber(value: number) {
+  return String(value);
+}
+
+const ticks = computed(() =>
+  Array.from({ length: 9 }, (_, index) => ({
+    position: `${(index / 8) * 100}%`,
+    label: new Intl.NumberFormat("zh-CN", { maximumFractionDigits: 1 }).format(
+      scale.value.start + ((scale.value.end - scale.value.start) * index) / 8,
+    ),
+  })),
+);
+
+const resultHint = computed(() => {
+  if (result.value === null) return "填写有效数值后查看结果";
+  if (Number(inputValue.value) < Number(minimum.value)) return "低于下限，返回区间起点";
+  if (Number(inputValue.value) > Number(maximum.value)) return "高于上限，返回区间终点";
+  return "位于区间内，保留原值";
+});
+
+function selectPreset(value: number) {
+  inputValue.value = value;
+  minimum.value = 0;
+  maximum.value = 100;
+}
+</script>
+
+<template>
+  <div class="workbench">
+    <header class="site-header">
+      <a class="brand" href="#main" aria-label="Mono 开发工作台，跳至主要内容">
+        <span class="brand-symbol" aria-hidden="true"><span /><span /><span /></span>
+        <span class="brand-name">mono<span class="brand-dot">.</span></span>
+        <span class="brand-caption">开发工作台</span>
+      </a>
+      <div class="workspace-tag"><span aria-hidden="true" />Vue · pnpm workspace</div>
+    </header>
+
+    <main id="main">
+      <section class="intro" aria-labelledby="page-title">
+        <p class="eyebrow">你的下一个项目，从这里开始</p>
+        <h1 id="page-title">应用各司其职，<br />代码共同生长。</h1>
+        <p class="intro-copy">
+          在应用中探索，在共享包中沉淀。这个工作台展示了它们如何连接，也为你的下一步留好了位置。
+        </p>
+        <a class="text-link" href="#workspace">查看工作区分工 <span aria-hidden="true">↗</span></a>
+      </section>
+
+      <section class="demo-panel" aria-labelledby="demo-title">
+        <div class="panel-heading">
+          <div>
+            <p class="eyebrow">共享包 · 即时演示</p>
+            <h2 id="demo-title">把数值留在区间内。</h2>
+          </div>
+          <code class="package-tag">@bubblesjs/utils</code>
+        </div>
+        <p class="demo-description">调整数值与上下限，看看 <code>clamp()</code> 如何处理边界。</p>
+
+        <div class="presets" role="group" aria-label="选择示例数值">
+          <button v-for="preset in presets" :key="preset.value" type="button" :aria-pressed="Number(inputValue) === preset.value &&
+            Number(minimum) === 0 &&
+            Number(maximum) === 100
+            " @click="selectPreset(preset.value)">
+            {{ preset.label }}
+          </button>
+        </div>
+
+        <div class="number-fields">
+          <div class="number-field input-field">
+            <label for="value">输入值 <span>value</span></label>
+            <input id="value" v-model="inputValue" type="number" min="-1000" max="1000" step="any"
+              :aria-invalid="!isValidNumber(inputValue)" aria-describedby="demo-help demo-error" />
+          </div>
+          <div class="number-field">
+            <label for="minimum">下限 <span>min</span></label>
+            <input id="minimum" v-model="minimum" type="number" min="-1000" max="1000" step="any"
+              :aria-invalid="!isValidNumber(minimum) || Number(minimum) > Number(maximum)"
+              aria-describedby="demo-help demo-error" />
+          </div>
+          <div class="number-field">
+            <label for="maximum">上限 <span>max</span></label>
+            <input id="maximum" v-model="maximum" type="number" min="-1000" max="1000" step="any"
+              :aria-invalid="!isValidNumber(maximum) || Number(minimum) > Number(maximum)"
+              aria-describedby="demo-help demo-error" />
+          </div>
+        </div>
+        <p id="demo-help" class="field-help">
+          支持 −1000 到 1000，可输入小数；下限应小于或等于上限。
+        </p>
+        <p id="demo-error" class="field-error" role="status">
+          {{ error }}
+        </p>
+
+        <div class="ruler" aria-hidden="true">
+          <div v-if="!error" class="allowed-range" :style="{
+            left: position(minimum),
+            width: `${Number.parseFloat(position(maximum)) - Number.parseFloat(position(minimum))}%`,
+          }" />
+          <div class="ruler-line" />
+          <div v-for="tick in ticks" :key="tick.position" class="ruler-tick" :style="{ left: tick.position }">
+            <span>{{ tick.label }}</span>
+          </div>
+          <div v-if="!error" class="input-marker" :style="{ left: position(inputValue) }">
+            <span>输入 {{ inputValue }}</span><i />
+          </div>
+          <div v-if="result !== null" class="result-marker" :style="{ left: position(result) }">
+            <i /><span>结果 {{ displayNumber(result) }}</span>
+          </div>
+        </div>
+
+        <div class="result-row" aria-live="polite" aria-atomic="true">
+          <div>
+            <span class="result-label">返回值</span><output for="value minimum maximum">{{
+              result === null ? "—" : displayNumber(result)
+              }}</output>
+          </div>
+          <p>{{ resultHint }}</p>
+        </div>
+        <div class="code-line">
+          <code>clamp({{ inputValue === "" ? "value" : inputValue }},
+            {{ minimum === "" ? "min" : minimum }}, {{ maximum === "" ? "max" : maximum }})</code><span>来自共享包源码</span>
+        </div>
+      </section>
+
+      <section id="workspace" class="workspace-section" aria-labelledby="workspace-title">
+        <div class="section-heading">
+          <h2 id="workspace-title">一个仓库，清楚的分工。</h2>
+          <p>应用消费包，配置统一管理。</p>
+        </div>
+        <div class="workspace-grid">
+          <article class="workspace-item">
+            <span class="folder-label">apps/</span>
+            <h3>让想法可见</h3>
+            <p>Playground 用来交互演示，Docs 用来记录约定。应用通过工作区依赖连接共享包。</p>
+            <code>playground · docs</code>
+          </article>
+          <article class="workspace-item">
+            <span class="folder-label">packages/</span>
+            <h3>让代码可复用</h3>
+            <p>把通用逻辑放进独立包，按需构建、测试与发布。上方的数值示例就来自这里。</p>
+            <code>@bubblesjs/utils</code>
+          </article>
+          <article class="workspace-item">
+            <span class="folder-label">tsconfig/</span>
+            <h3>让约定保持一致</h3>
+            <p>集中维护 TypeScript 配置。格式、检查与任务编排由根目录统一管理。</p>
+            <code>tsconfig</code>
+          </article>
+        </div>
+      </section>
+
+      <section class="next-step" aria-labelledby="next-title">
+        <div>
+          <p class="eyebrow">接下来</p>
+          <h2 id="next-title">从一个共享函数开始。</h2>
+          <p>编辑 <code>packages/utils/src/index.ts</code>，回到这里查看变化。</p>
+        </div>
+        <div class="command-list">
+          <div><span>运行工作台</span><code>pnpm dev</code></div>
+          <div><span>检查整个仓库</span><code>pnpm check</code></div>
+        </div>
+      </section>
+    </main>
+
+    <footer class="site-footer">
+      <span>少一点重复，多一点专注。</span><span>MONOREPO STARTER / PLAYGROUND</span>
+    </footer>
+  </div>
+</template>

package/template-pnpm-vp-monorepo/apps/playground/src/env.d.ts

@@ -0,0 +1,6 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent<object, object, unknown>;
+  export default component;
+}

package/template-pnpm-vp-monorepo/apps/playground/src/main.ts

@@ -0,0 +1,6 @@
+import { createApp } from "vue";
+
+import App from "./App.vue";
+import "./style.css";
+
+createApp(App).mount("#app");