astro-openmoji 0.0.0-stage → 0.1.1

package/ATTRIBUTION.md

@@ -0,0 +1,18 @@
+# OpenMoji attribution
+
+This package uses SVG artwork from the OpenMoji project:
+
+- Project: [OpenMoji](https://openmoji.org/)
+- Source: [`openmoji` on npm](https://www.npmjs.com/package/openmoji)
+- Creators: HfG Schwäbisch Gmünd, Benedikt Groß, Daniel Utz, 70+ students, and external contributors
+- Artwork license: [Creative Commons Attribution-ShareAlike 4.0 International](https://creativecommons.org/licenses/by-sa/4.0/)
+
+`astro-openmoji` copies only the SVG files used by a site's Markdown from the installed `openmoji` package into the site's build output. The SVG artwork is copied unchanged by this integration.
+
+Suggested visible website credit:
+
+```text
+Emoji by OpenMoji — CC BY-SA 4.0
+```
+
+The integration code itself is licensed under the MIT License. See [LICENSE](./LICENSE).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 astro-openmoji contributors
+
+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

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# astro-openmoji
 
-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.
+在 Astro 构建 Markdown 时，把源码中的原生 Unicode Emoji 转换为本地 [OpenMoji](https://openmoji.org/) SVG。
+
+- Markdown 源文件保持不变
+- 不使用客户端 JavaScript
+- 不依赖 CDN，可离线部署
+- 支持 ZWJ、肤色、旗帜及变体选择符等完整 Emoji 序列
+- `astro dev` 按需提供 SVG，`astro build` 只复制实际使用的资源
+
+## 安装
+
+```bash
+npm install astro-openmoji
+```
+
+本包面向 Astro 7 和 Node.js 22.12 或更高版本。
+
+## 配置
+
+```ts
+// astro.config.ts
+import { defineConfig } from "astro/config";
+import openmoji from "astro-openmoji";
+
+export default defineConfig({
+  integrations: [openmoji()],
+});
+```
+
+之后正常在 Markdown 中输入原生 Emoji：
+
+```md
+今天学 CMake 学得有些 😵‍💫，但总算跑通了 🚀
+```
+
+构建后的 HTML 类似：
+
+```html
+<p>
+  今天学 CMake 学得有些
+  <img class="openmoji" src="/openmoji/1F635-200D-1F4AB.svg" alt="😵‍💫" style="width:1em;height:1em;vertical-align:-0.125em;display:inline-block">
+  ，但总算跑通了
+  <img class="openmoji" src="/openmoji/1F680.svg" alt="🚀" style="width:1em;height:1em;vertical-align:-0.125em;display:inline-block">
+</p>
+```
+
+`alt` 始终保留原 Emoji。内联样式只负责把一 em 大小的图片与文字基线自然对齐。
+
+## 配置项
+
+```ts
+openmoji({
+  style: "color",
+  assetDir: "openmoji",
+  className: "openmoji",
+});
+```
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `style` | `"color" \| "black"` | `"color"` | 使用 OpenMoji 彩色或黑色 SVG |
+| `assetDir` | `string` | `"openmoji"` | 输出目录和公共 URL 路径，可使用 `emoji/assets` 这样的相对路径 |
+| `className` | `string` | `"openmoji"` | 生成的 `<img>` 使用的单个 CSS 类名 |
+
+Astro 的 `base` 会自动加入图片 URL。例如 `base: "/blog"` 时，图片地址为 `/blog/openmoji/1F680.svg`，资源仍输出到 `dist/openmoji/`。
+
+## 转换范围
+
+插件只处理 HAST 普通文本节点，因此段落、标题、列表、引用和链接文字中的 Emoji 会被替换。以下内容不会被替换：
+
+- 行内代码和代码块中的文本
+- 原始 HTML 属性
+- URL 属性
+- frontmatter
+- OpenMoji 中不存在的 Emoji；这类字符会原样保留
+
+匹配使用 `emoji-regex`，不会把 ZWJ、肤色或旗帜序列拆成单个字符。插件先查找完整码点文件；如果不存在，再去除 `FE0E` / `FE0F` 变体选择符重试。例如 `❤️` 会使用 `2764.svg`。
+
+## 开发与生产构建
+
+在 `astro dev` 中，integration 通过 Vite 开发服务器中间件从已安装的 `openmoji/<style>/svg/` 按需返回 `/openmoji/*.svg`，无需复制到 `public/`。
+
+在 `astro build` 中，Rehype 转换会记录本次构建实际引用的文件；构建完成后仅将这些 SVG 复制到 `dist/<assetDir>/`。Markdown、`public/` 和其他工作区文件均不会被修改。
+
+Astro 7 默认使用 Sätteri，而 Rehype 插件只能运行在 Unified 流水线中。因此 integration 会自动选择官方 `@astrojs/markdown-remark` Unified processor；如果项目已经配置 Unified，则会保留现有选项并追加本插件。显式使用 Sätteri 插件的项目需要先确认改用 Unified 后功能仍符合预期。
+
+## 单独使用 Rehype 插件
+
+高级用户可以直接注册底层插件：
+
+```ts
+import { rehypeOpenmoji } from "astro-openmoji/rehype";
+
+// unified().use(rehypeOpenmoji, { style: "black", base: "/blog" })
+```
+
+直接使用时支持与 integration 相同的三个选项，另可通过 `base` 设置 URL 前缀。单独使用 Rehype 插件只转换 HAST，不负责开发服务器或生产资源复制。
+
+## 本项目开发
+
+```bash
+npm install
+npm test
+npm run build
+npm pack --dry-run
+```
+
+测试包含独立 Rehype 转换、真实 `astro build` fixture、`base: "/blog"`、最小资源输出，以及真实 `astro dev` SVG 请求。
+
+## 许可证与署名
+
+`astro-openmoji` 插件代码使用 [MIT License](./LICENSE)。OpenMoji 图形资产由 OpenMoji 项目提供，使用 [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)；详情见 [ATTRIBUTION.md](./ATTRIBUTION.md)。
+
+建议在网站页脚或关于页面中显示：
+
+```text
+Emoji by OpenMoji — CC BY-SA 4.0
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import { n as OpenmojiStyle, t as OpenmojiOptions } from "./options-DnDZhR4N.js";
+import { AstroIntegration } from "astro";
+export default function openmoji(options?: OpenmojiOptions): AstroIntegration;
+export type { OpenmojiOptions, OpenmojiStyle };

package/dist/index.js

@@ -0,0 +1,82 @@
+import { i as openmojiAssetRoot, n as normalizeBase, r as resolveOptions, t as transformOpenmojiTree } from "./transform-CnWUZewM.js";
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import { isUnifiedProcessor, unified } from "@astrojs/markdown-remark";
+// src/index.ts
+const svgFilenamePattern = /^[0-9A-F]{4,6}(?:-[0-9A-F]{4,6})*\.svg$/;
+function openmoji(options = {}) {
+	const resolved = resolveOptions(options);
+	const assetRoot = openmojiAssetRoot(resolved.style);
+	const usedAssets = /* @__PURE__ */ new Set();
+	const state = { base: "/" };
+	const plugin = () => (tree) => {
+		transformOpenmojiTree(tree, {
+			...resolved,
+			base: state.base,
+			assetRoot,
+			onAsset: (filename) => usedAssets.add(filename)
+		});
+	};
+	return {
+		name: "astro-openmoji",
+		hooks: {
+			"astro:config:setup": ({ config, updateConfig }) => {
+				state.base = normalizeBase(config.base);
+				const processor = config.markdown?.processor;
+				if (processor === void 0 || !isUnifiedProcessor(processor)) {
+					updateConfig({ markdown: { processor: unified({ rehypePlugins: [plugin] }) } });
+					return;
+				}
+				processor.options.rehypePlugins.push(plugin);
+			},
+			"astro:config:done": ({ config }) => {
+				state.base = normalizeBase(config.base);
+			},
+			"astro:server:setup": ({ server }) => {
+				const assetPrefix = `${state.base}${resolved.assetDir}/`;
+				server.middlewares.use(async (request, response, next) => {
+					if (request.method !== "GET" && request.method !== "HEAD") {
+						next();
+						return;
+					}
+					let pathname;
+					try {
+						pathname = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname);
+					} catch {
+						next();
+						return;
+					}
+					if (!pathname.startsWith(assetPrefix)) {
+						next();
+						return;
+					}
+					const filename = pathname.slice(assetPrefix.length);
+					if (!svgFilenamePattern.test(filename)) {
+						next();
+						return;
+					}
+					try {
+						const svg = await readFile(new URL(filename, assetRoot));
+						response.statusCode = 200;
+						response.setHeader("Content-Type", "image/svg+xml; charset=utf-8");
+						response.setHeader("Cache-Control", "public, max-age=3600");
+						response.setHeader("Content-Length", svg.byteLength);
+						response.end(request.method === "HEAD" ? void 0 : svg);
+					} catch (error) {
+						if (error.code === "ENOENT") next();
+						else next(error);
+					}
+				});
+			},
+			"astro:build:start": () => {
+				usedAssets.clear();
+			},
+			"astro:build:done": async ({ dir }) => {
+				if (usedAssets.size === 0) return;
+				const outputRoot = new URL(`${resolved.assetDir}/`, dir);
+				await mkdir(outputRoot, { recursive: true });
+				await Promise.all([...usedAssets].map((filename) => copyFile(new URL(filename, assetRoot), new URL(filename, outputRoot))));
+			}
+		}
+	};
+}
+export { openmoji as default };

package/dist/options-DnDZhR4N.d.ts

@@ -0,0 +1,10 @@
+type OpenmojiStyle = "color" | "black";
+interface OpenmojiOptions {
+  /** OpenMoji artwork style. @default "color" */
+  style?: OpenmojiStyle;
+  /** Public URL directory for emitted SVG files. @default "openmoji" */
+  assetDir?: string;
+  /** CSS class placed on generated image elements. @default "openmoji" */
+  className?: string;
+}
+export { OpenmojiStyle as n, OpenmojiOptions as t };