@show-docs/docusaurus-theme-copy-button 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @show-docs/docusaurus-theme-copy-button
 
-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.
+在页脚那一格加一颗复制按钮：点一下把此刻地址栏里的页面地址写进剪贴板，成败都给一条提示。
+页脚原本的文案一个字都不改。
+
+## 安装
+
+```bash
+pnpm add @show-docs/docusaurus-theme-copy-button
+```
+
+## 使用
+
+### 注册插件
+
+```js
+// docusaurus.config.mjs
+export default {
+  plugins: ['@show-docs/docusaurus-theme-copy-button']
+};
+```
+
+### 页脚要有内容
+
+这一层覆盖的是页脚里的 `Footer/Copyright` 那一格，所以站点得给它东西渲染：
+`themeConfig.footer.copyright` 写过才看得见这一格，没写的站点里这一层等于不存在。
+
+## 层栈
+
+本层提供 `theme/Footer/Copyright/index.tsx`：它先向下面那一层要 `Footer/Copyright` 的实现
+（`@theme-prev/Footer/Copyright`），把文案原样交下去，只在它前面多摆一颗按钮。
+这一层不读 frontmatter，也没有插件选项。
+
+层栈怎么推导、谁能盖住谁，是核心解析器那一格的事，见
+[`plugin-prev-layer-resolver` 的 README](../../plugins/plugin-prev-layer-resolver/README.md)；
+这一层自己只负责「挂在哪一格」。
+
+## 工作方式
+
+- 按钮是 `<button type="button">`，图标是 `styles/copy-button.css` 里纯 CSS 画的一份形状，
+  不请求图标字体也不带图片；按钮上没有文字，读屏拿到的名字是 `aria-label` 那一句。
+- 复制走 `navigator.clipboard.writeText()`，提示条由 [`sonner`](https://sonner.emilkowal.ski/)
+  给（`<Toaster position="bottom-right" richColors />`，跟按钮一起挂在这一格里）。
+- 写进剪贴板的是 `window.location.href` 解码之后那一份，所以地址里带 `?path=` 这类编码参数时，
+  复制出来的是看得懂的那一份。
+- `styles/copy-button.css` 由入口的 `getClientModules()` 交给站点的样式表管线；
+  提示条自己的样式由 `sonner` 在浏览器里注入，不经过这一格。
+- 主题层与 `components/` 是未编译的 `.tsx`，随包发布、由用它们的站点编译；
+  本包只编译 `src/index.mts` 那一份入口（`pnpm build` → `dist/`）。
+
+## 已知限制
+
+- 只在页脚有 `Footer/Copyright` 那一格时出现；页脚整块关掉（`themeConfig.footer: null`）的站点看不到它。
+- `navigator.clipboard` 只在安全上下文（https 或 localhost）里存在。用 http 打开的站点上，
+  点击只会给一条「复制失败」的提示，按钮本身照常可点。
+- 静态渲染出来的 HTML 里没有提示条：这一层是浏览器里的行为。
+- 提示文案（成功与失败各一句）写死在 `components/copy-button.tsx`，不跟站点语言切换。
+
+## 相关文档
+
+- [`plugin-prev-layer-resolver` 的 README](../../plugins/plugin-prev-layer-resolver/README.md)：`@theme-prev/*` 的语义与层栈。
+- [`sonner` 文档](https://sonner.emilkowal.ski/)：提示条的选项与样式。

package/components/copy-button.tsx

@@ -0,0 +1,45 @@
+import { toast } from 'sonner';
+
+const ACCESSIBLE_NAME = '复制当前页地址';
+const SUCCESS_MESSAGE = '已复制当前页地址';
+const FAILURE_MESSAGE = '复制失败';
+
+/**
+把此刻地址栏里那份地址写进剪贴板，成败都给一条提示。
+
+`navigator.clipboard` 只在这个页面是安全上下文（https，或 localhost）时才存在，
+用 http 打开的站点拿到的就是 `undefined` —— 这一格要单独判，不能只靠 `catch`。
+*/
+async function copyPageUrl(): Promise<void> {
+  if (!navigator.clipboard) {
+    toast.error(FAILURE_MESSAGE);
+    return;
+  }
+  try {
+    await navigator.clipboard.writeText(
+      decodeURIComponent(window.location.href),
+    );
+    toast.success(SUCCESS_MESSAGE);
+  } catch (error) {
+    toast.error(FAILURE_MESSAGE);
+    console.error(error);
+  }
+}
+
+/**
+页脚那一格右侧的按钮：图标是 `styles/copy-button.css` 里 `.gg-copy` 画出来的那一份，
+按钮自己不带文字，读屏拿到的名字是 `aria-label` 那一句。用 `<button>` 而不是一个可点的
+`<span>`，键盘才按得动；图标那一格是纯装饰，标 `aria-hidden` 让读屏跳过它。
+*/
+export function CopyButton() {
+  return (
+    <button
+      type="button"
+      className="footer-copy-btn"
+      aria-label={ACCESSIBLE_NAME}
+      onClick={copyPageUrl}
+    >
+      <span className="gg-copy" aria-hidden="true" />
+    </button>
+  );
+}

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import type { Plugin } from '@docusaurus/types';
+export default function theme(): Plugin;

package/dist/index.mjs

@@ -0,0 +1,39 @@
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// 包出口是 `dist/`，所以这里的路径都相对**产物**目录算，不是相对 `src/`。
+const thisDir = dirname(fileURLToPath(import.meta.url));
+export default function theme() {
+    return {
+        name: '@show-docs/docusaurus-theme-copy-button',
+        // 主题层与 `components/` 是**源码**，站在包根上，不经 `tsc`：用本包的 Docusaurus
+        // 项目会用自己的 babel 编译它们。这里只编译 `src/` 那一份入口。
+        getThemePath() {
+            return resolve(thisDir, '../theme');
+        },
+        // 层里放的是 `.tsx`，这条给 `docusaurus swizzle` 用
+        getTypeScriptThemePath() {
+            return resolve(thisDir, '../theme');
+        },
+        // 样式表不是模块，`tsc` 不会把它搬进 `dist/`：作为 client module 交给站点的样式表管线。
+        // 提示条自己的样式由 `sonner` 在浏览器里注入，不经过这一格。
+        getClientModules() {
+            return [resolve(thisDir, '../styles/copy-button.css')];
+        },
+        configureWebpack(_config, isServer, utils) {
+            return {
+                module: {
+                    rules: [
+                        {
+                            // 官方那条 babel 规则排除整个 node_modules、只放行 `docusaurus*.js`，本包从
+                            // npm 安装后的 `.tsx` 会报 `Module parse failed`。补一条只覆盖本包的规则
+                            //（理由与代价见 theme-iframe 的 `lib/api-frame-theme.mts` 里同一条）。
+                            test: /\.tsx?$/,
+                            include: [resolve(thisDir, '..')],
+                            use: [utils.getJSLoader({ isServer })],
+                        },
+                    ],
+                },
+            };
+        },
+    };
+}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@show-docs/docusaurus-theme-copy-button",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "页脚版权那一格右边加一颗按钮，点一下把当前页地址写进剪贴板",
+  "keywords": [],
+  "homepage": "https://github.com/show-docs/docusaurus/tree/master/theme/theme-copy-button",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/show-docs/docusaurus.git",
+    "directory": "theme/theme-copy-button"
+  },
+  "bugs": {
+    "url": "https://github.com/show-docs/docusaurus/issues"
+  },
+  "types": "dist/index.d.mts",
+  "main": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "default": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "components",
+    "dist",
+    "styles",
+    "theme"
+  ],
+  "type": "module",
+  "dependencies": {
+    "sonner": "^2.0.8"
+  },
+  "peerDependencies": {
+    "@docusaurus/types": "^3.9.2",
+    "react": "~18.3.1"
+  },
+  "peerDependenciesMeta": {
+    "@docusaurus/types": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
 }

package/styles/copy-button.css

@@ -0,0 +1,67 @@
+/* 页脚那一格右侧的复制按钮。图标 `gg-copy` 是一份纯 CSS 画的形状（不请求图标字体，
+   也不带图片）：颜色取 `currentColor`，所以它跟着页脚文字自己深浅。
+   写法是摊平的（`.gg-copy::before` 而不是嵌套），站点的样式表管线不必为它补插件。 */
+
+.gg-copy {
+  display: inline-block;
+  position: relative;
+  transform: scale(var(--ggs, 1));
+  box-sizing: border-box;
+  margin-top: -4px;
+  margin-left: -5px;
+  border: 2px solid;
+  width: 14px;
+  height: 18px;
+}
+
+.gg-copy::after,
+.gg-copy::before {
+  display: block;
+  position: absolute;
+  box-sizing: border-box;
+  content: '';
+}
+
+.gg-copy::before {
+  right: -6px;
+  bottom: -6px;
+  box-shadow: inset -4px -4px 0 -2px;
+  background:
+    linear-gradient(to left, currentColor 5px, transparent 0) no-repeat right
+      top/5px 2px,
+    linear-gradient(to left, currentColor 5px, transparent 0) no-repeat left
+      bottom/ 2px 5px;
+  width: 14px;
+  height: 18px;
+}
+
+.gg-copy::after {
+  top: 2px;
+  left: 2px;
+  box-shadow:
+    0 4px 0,
+    0 8px 0;
+  background: currentColor;
+  width: 6px;
+  height: 2px;
+}
+
+/* 这是页脚文案里的一颗按钮：去掉浏览器给 `<button>` 的那圈默认外观，让它只剩图标本身。 */
+.footer-copy-btn {
+  float: right;
+  cursor: pointer;
+  margin-left: 2em;
+  border: 0;
+  background: none;
+  padding: 0;
+  color: inherit;
+  font: inherit;
+}
+
+.footer-copy-btn:hover {
+  opacity: 0.5;
+}
+
+.footer-copy-btn:active .gg-copy {
+  transform: scale(0.9);
+}

package/theme/Footer/Copyright/index.tsx

@@ -0,0 +1,20 @@
+import Copyright from '@theme-prev/Footer/Copyright';
+import { Toaster } from 'sonner';
+
+import type { ReactNode } from 'react';
+
+import { CopyButton } from '../../../components/copy-button.tsx';
+
+type Props = Record<string, unknown>;
+
+export default function CopyrightWrapper(props: Props): ReactNode {
+  // 这一层不改页脚那一格的内容：文案照旧交给下面那一层渲染，只在它前面多摆一颗按钮。
+  // 提示条的挂载点整站只需要一个，跟着按钮放在这里（`sonner` 把它渲染在页面末尾）。
+  return (
+    <>
+      <CopyButton />
+      <Toaster position="bottom-right" richColors />
+      <Copyright {...props} />
+    </>
+  );
+}