rough-emoji-draw 0.1.0

package/README.md

@@ -0,0 +1,145 @@
+# Rough Emoji Draw
+
+Rough Emoji Draw 是一个把 Unicode 国旗 emoji 绘制成 Rough.js 手写风格 Canvas 图像的轻量前端库。项目使用 TypeScript 编写核心绘制逻辑，通过 Rslib 同时输出 ESM、CommonJS 与 IIFE 产物；Rough.js 会随库一并打包，安装或引用构建产物即可使用，无需额外引入 CDN。
+
+## 功能特性
+
+- 将 Unicode 国旗 emoji 绘制到指定 `canvas`。
+- 内置中国、日本、美国、澳大利亚、泰国、法国、意大利、西班牙、梵蒂冈等常见旗帜的手写模板。
+- 对未单独适配的国旗使用 emoji 栅格化与像素采样流程生成统一风格的 fallback 图像。
+- 支持三种接入方式：npm `import` / Node `require`、浏览器 `<script>` 全局变量 `window.RoughEmoji`。
+- 提供 TypeScript 类型声明，可在 TS 项目中直接获得 API 提示。
+- 提供 `index.html` 批量 QA 页面，用于检查 240+ 国家/地区旗帜绘制效果。
+
+## 技术栈
+
+- TypeScript
+- DOM Canvas
+- Rough.js
+- Rslib
+
+## 环境要求
+
+- Node.js 20 及以上（可用 `.nvmrc`：`nvm use`）
+- [pnpm](https://pnpm.io/) 9 及以上（推荐通过 Corepack：`corepack enable`）
+
+## 快速开始
+
+安装依赖：
+
+```bash
+pnpm install
+```
+
+执行类型检查：
+
+```bash
+pnpm run typecheck
+```
+
+构建产物：
+
+```bash
+pnpm run build
+```
+
+构建完成后会生成：
+
+| 文件 | 格式 | 用途 |
+| --- | --- | --- |
+| `dist/index.js` | ESM | `import` 引入 |
+| `dist/index.cjs` | CJS | Node.js `require()` |
+| `dist/index.d.ts` | 类型 | TypeScript 类型入口 |
+| `dist/rough-emoji.js` | IIFE（压缩） | 浏览器 `<script>` 标签 |
+
+本地预览 QA 页面（不要用 `file://` 直接打开 HTML，浏览器会拦截本地 JS）：
+
+```bash
+pnpm run dev
+```
+
+然后在浏览器访问 [http://localhost:3000/](http://localhost:3000/)。
+
+## 使用方式
+
+### npm 包（ESM）
+
+```ts
+import { RoughEmoji } from "rough-emoji-draw";
+
+const canvas = document.querySelector<HTMLCanvasElement>("#flag-canvas")!;
+RoughEmoji.draw(canvas, "🇨🇳");
+```
+
+### npm 包（CommonJS / Node）
+
+```js
+const { RoughEmoji } = require("rough-emoji-draw");
+
+console.log(typeof RoughEmoji.draw); // "function"
+```
+
+> 绘制依赖 Canvas 与 DOM 环境。Node 侧可正常加载 API，实际调用 `draw` 时需要在浏览器、jsdom 或 `node-canvas` 等具备 Canvas 的运行时中使用。
+
+### 浏览器 `<script>` 标签
+
+页面只需加载 IIFE 产物，会自动挂载 `window.RoughEmoji`：
+
+```html
+<script src="./dist/rough-emoji.js"></script>
+<canvas id="flag-canvas" width="720" height="720"></canvas>
+<script>
+  const canvas = document.querySelector("#flag-canvas");
+  window.RoughEmoji.draw(canvas, "🇨🇳");
+</script>
+```
+
+若页面包含演示表单 DOM（`#rough-canvas`、`#emoji-form` 等），还会自动绑定交互与下载逻辑。
+
+## API
+
+### `RoughEmoji.draw(canvasElement, value)`
+
+把输入值规范化为国旗 emoji，并绘制到传入的 `HTMLCanvasElement`。非法输入会回退为中国国旗。
+
+### `RoughEmoji.isFlagEmoji(value)`
+
+判断字符串是否为由两个区域指示符组成的国旗 emoji。
+
+### `RoughEmoji.resolveFlag(value)`
+
+把任意输入转换为可绘制的国旗 emoji；当前只接受合法国旗 emoji，非法值回退为 `🇨🇳`。
+
+### 类型导出
+
+```ts
+import type { RoughEmojiApi } from "rough-emoji-draw";
+```
+
+还可按需导入 `RoughOptions`、`Point`、`RoughCanvasLike`，以及演示页入口 `RoughEmojiApp`。
+
+## 项目结构
+
+```text
+.
+├── src/
+│   ├── index.ts          # npm 库入口，导出 API 与类型
+│   ├── browser.ts        # 浏览器 IIFE 入口，挂载 window.RoughEmoji
+│   ├── rough-emoji.ts    # 核心绘制逻辑
+│   ├── rough-emoji-app.ts # 单页演示 DOM 绑定
+│   ├── flag-utils.ts     # 国旗 emoji 解析与校验
+│   ├── render-context.ts # Canvas 上下文切换
+│   ├── constant.ts       # 静态常量与模板映射
+│   └── types.ts          # 对外类型声明
+├── index.html            # 批量视觉 QA 页面
+├── rslib.config.ts       # Rslib 多格式构建配置
+├── tsconfig.json         # TypeScript 配置
+└── package.json          # 脚本、依赖与 exports 字段
+```
+
+## 开发说明
+
+- 新增旗帜优先在 `src/rough-emoji.ts` 中补充独立绘制函数，并在模板分发表中接入。
+- 绘制函数按正方形画布坐标系工作，新增坐标建议基于当前 `size` 或已有旗帜区域变量推导。
+- 修改绘制效果后，先运行 `pnpm run typecheck`，再运行 `pnpm run build` 并打开 `index.html` 进行视觉检查。
+- `dist/` 为构建产物，通常不作为源码维护对象；发布或本地预览前执行 `pnpm run build` 即可。

package/dist/browser.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/constant.d.ts

@@ -0,0 +1,279 @@
+/** 单页演示入口使用的 DOM 选择器，QA 页面不存在这些节点时只暴露全局 API。 */
+export declare const ELEMENT_SELECTORS: {
+    readonly canvas: "#rough-canvas";
+    readonly form: "#emoji-form";
+    readonly input: "#emoji-input";
+    readonly downloadButton: "#download-button";
+};
+/** 默认绘制国旗，供首次打开页面、prompt 默认值和非法输入回退共用。 */
+export declare const DEFAULT_FLAG = "\uD83C\uDDE8\uD83C\uDDF3";
+/** 下载文件名前缀，最终文件名会追加当前绘制的国旗 emoji。 */
+export declare const DOWNLOAD_FILE_PREFIX = "rough-flag";
+/** 首次进入单页演示时提示用户输入国旗的文案。 */
+export declare const FLAG_PROMPT_MESSAGE = "\u8BF7\u8F93\u5165\u8981\u7ED8\u5236\u7684\u56FD\u65D7";
+/** 已有专门手写模板的国旗 emoji，避免绘制分支散落字面量。 */
+export declare const TEMPLATE_FLAGS: {
+    readonly ad: "🇦🇩";
+    readonly ae: "🇦🇪";
+    readonly af: "🇦🇫";
+    readonly ag: "🇦🇬";
+    readonly ai: "🇦🇮";
+    readonly al: "🇦🇱";
+    readonly am: "🇦🇲";
+    readonly ao: "🇦🇴";
+    readonly aq: "🇦🇶";
+    readonly ar: "🇦🇷";
+    readonly as: "🇦🇸";
+    readonly at: "🇦🇹";
+    readonly australia: "🇦🇺";
+    readonly aw: "🇦🇼";
+    readonly ax: "🇦🇽";
+    readonly az: "🇦🇿";
+    readonly ba: "🇧🇦";
+    readonly bb: "🇧🇧";
+    readonly bd: "🇧🇩";
+    readonly be: "🇧🇪";
+    readonly bf: "🇧🇫";
+    readonly bg: "🇧🇬";
+    readonly bh: "🇧🇭";
+    readonly bi: "🇧🇮";
+    readonly bj: "🇧🇯";
+    readonly bl: "🇧🇱";
+    readonly bm: "🇧🇲";
+    readonly bn: "🇧🇳";
+    readonly bo: "🇧🇴";
+    readonly bq: "🇧🇶";
+    readonly br: "🇧🇷";
+    readonly bs: "🇧🇸";
+    readonly bt: "🇧🇹";
+    readonly bv: "🇧🇻";
+    readonly bw: "🇧🇼";
+    readonly by: "🇧🇾";
+    readonly bz: "🇧🇿";
+    readonly ca: "🇨🇦";
+    readonly cc: "🇨🇨";
+    readonly cd: "🇨🇩";
+    readonly cf: "🇨🇫";
+    readonly cg: "🇨🇬";
+    readonly ch: "🇨🇭";
+    readonly ci: "🇨🇮";
+    readonly ck: "🇨🇰";
+    readonly cl: "🇨🇱";
+    readonly cm: "🇨🇲";
+    readonly china: "🇨🇳";
+    readonly co: "🇨🇴";
+    readonly cr: "🇨🇷";
+    readonly cu: "🇨🇺";
+    readonly cv: "🇨🇻";
+    readonly cw: "🇨🇼";
+    readonly cx: "🇨🇽";
+    readonly cy: "🇨🇾";
+    readonly cz: "🇨🇿";
+    readonly de: "🇩🇪";
+    readonly dj: "🇩🇯";
+    readonly dk: "🇩🇰";
+    readonly dm: "🇩🇲";
+    readonly do: "🇩🇴";
+    readonly dz: "🇩🇿";
+    readonly ec: "🇪🇨";
+    readonly ee: "🇪🇪";
+    readonly eg: "🇪🇬";
+    readonly eh: "🇪🇭";
+    readonly er: "🇪🇷";
+    readonly spain: "🇪🇸";
+    readonly et: "🇪🇹";
+    readonly fi: "🇫🇮";
+    readonly fj: "🇫🇯";
+    readonly fk: "🇫🇰";
+    readonly fm: "🇫🇲";
+    readonly fo: "🇫🇴";
+    readonly france: "🇫🇷";
+    readonly ga: "🇬🇦";
+    readonly gb: "🇬🇧";
+    readonly gd: "🇬🇩";
+    readonly ge: "🇬🇪";
+    readonly gf: "🇬🇫";
+    readonly gg: "🇬🇬";
+    readonly gh: "🇬🇭";
+    readonly gi: "🇬🇮";
+    readonly gl: "🇬🇱";
+    readonly gm: "🇬🇲";
+    readonly gn: "🇬🇳";
+    readonly gp: "🇬🇵";
+    readonly gq: "🇬🇶";
+    readonly gr: "🇬🇷";
+    readonly gs: "🇬🇸";
+    readonly gt: "🇬🇹";
+    readonly gu: "🇬🇺";
+    readonly gw: "🇬🇼";
+    readonly gy: "🇬🇾";
+    readonly hk: "🇭🇰";
+    readonly hm: "🇭🇲";
+    readonly hn: "🇭🇳";
+    readonly hr: "🇭🇷";
+    readonly ht: "🇭🇹";
+    readonly hu: "🇭🇺";
+    readonly id: "🇮🇩";
+    readonly ie: "🇮🇪";
+    readonly il: "🇮🇱";
+    readonly im: "🇮🇲";
+    readonly in: "🇮🇳";
+    readonly io: "🇮🇴";
+    readonly iq: "🇮🇶";
+    readonly ir: "🇮🇷";
+    readonly is: "🇮🇸";
+    readonly italy: "🇮🇹";
+    readonly je: "🇯🇪";
+    readonly jm: "🇯🇲";
+    readonly jo: "🇯🇴";
+    readonly japan: "🇯🇵";
+    readonly ke: "🇰🇪";
+    readonly kg: "🇰🇬";
+    readonly kh: "🇰🇭";
+    readonly ki: "🇰🇮";
+    readonly km: "🇰🇲";
+    readonly kn: "🇰🇳";
+    readonly kp: "🇰🇵";
+    readonly kr: "🇰🇷";
+    readonly kw: "🇰🇼";
+    readonly ky: "🇰🇾";
+    readonly kz: "🇰🇿";
+    readonly la: "🇱🇦";
+    readonly lb: "🇱🇧";
+    readonly lc: "🇱🇨";
+    readonly li: "🇱🇮";
+    readonly lk: "🇱🇰";
+    readonly lr: "🇱🇷";
+    readonly ls: "🇱🇸";
+    readonly lt: "🇱🇹";
+    readonly lu: "🇱🇺";
+    readonly lv: "🇱🇻";
+    readonly ly: "🇱🇾";
+    readonly ma: "🇲🇦";
+    readonly mc: "🇲🇨";
+    readonly md: "🇲🇩";
+    readonly me: "🇲🇪";
+    readonly mf: "🇲🇫";
+    readonly mg: "🇲🇬";
+    readonly mh: "🇲🇭";
+    readonly mk: "🇲🇰";
+    readonly ml: "🇲🇱";
+    readonly mm: "🇲🇲";
+    readonly mn: "🇲🇳";
+    readonly mo: "🇲🇴";
+    readonly mp: "🇲🇵";
+    readonly mq: "🇲🇶";
+    readonly mr: "🇲🇷";
+    readonly ms: "🇲🇸";
+    readonly mt: "🇲🇹";
+    readonly mu: "🇲🇺";
+    readonly mv: "🇲🇻";
+    readonly mw: "🇲🇼";
+    readonly mx: "🇲🇽";
+    readonly my: "🇲🇾";
+    readonly mz: "🇲🇿";
+    readonly na: "🇳🇦";
+    readonly nc: "🇳🇨";
+    readonly ne: "🇳🇪";
+    readonly nf: "🇳🇫";
+    readonly ng: "🇳🇬";
+    readonly ni: "🇳🇮";
+    readonly nl: "🇳🇱";
+    readonly no: "🇳🇴";
+    readonly np: "🇳🇵";
+    readonly nr: "🇳🇷";
+    readonly nu: "🇳🇺";
+    readonly nz: "🇳🇿";
+    readonly om: "🇴🇲";
+    readonly pa: "🇵🇦";
+    readonly pe: "🇵🇪";
+    readonly pf: "🇵🇫";
+    readonly pg: "🇵🇬";
+    readonly ph: "🇵🇭";
+    readonly pk: "🇵🇰";
+    readonly pl: "🇵🇱";
+    readonly pm: "🇵🇲";
+    readonly pn: "🇵🇳";
+    readonly pr: "🇵🇷";
+    readonly ps: "🇵🇸";
+    readonly pt: "🇵🇹";
+    readonly pw: "🇵🇼";
+    readonly py: "🇵🇾";
+    readonly qa: "🇶🇦";
+    readonly re: "🇷🇪";
+    readonly ro: "🇷🇴";
+    readonly rs: "🇷🇸";
+    readonly ru: "🇷🇺";
+    readonly rw: "🇷🇼";
+    readonly sa: "🇸🇦";
+    readonly sb: "🇸🇧";
+    readonly sc: "🇸🇨";
+    readonly sd: "🇸🇩";
+    readonly se: "🇸🇪";
+    readonly sg: "🇸🇬";
+    readonly sh: "🇸🇭";
+    readonly si: "🇸🇮";
+    readonly sj: "🇸🇯";
+    readonly sk: "🇸🇰";
+    readonly sl: "🇸🇱";
+    readonly sm: "🇸🇲";
+    readonly sn: "🇸🇳";
+    readonly so: "🇸🇴";
+    readonly sr: "🇸🇷";
+    readonly ss: "🇸🇸";
+    readonly st: "🇸🇹";
+    readonly sv: "🇸🇻";
+    readonly sx: "🇸🇽";
+    readonly sy: "🇸🇾";
+    readonly sz: "🇸🇿";
+    readonly tc: "🇹🇨";
+    readonly td: "🇹🇩";
+    readonly tf: "🇹🇫";
+    readonly tg: "🇹🇬";
+    readonly thailand: "🇹🇭";
+    readonly tj: "🇹🇯";
+    readonly tk: "🇹🇰";
+    readonly tl: "🇹🇱";
+    readonly tm: "🇹🇲";
+    readonly tn: "🇹🇳";
+    readonly to: "🇹🇴";
+    readonly tr: "🇹🇷";
+    readonly tt: "🇹🇹";
+    readonly tv: "🇹🇻";
+    readonly tw: "";
+    readonly tz: "🇹🇿";
+    readonly ua: "🇺🇦";
+    readonly ug: "🇺🇬";
+    readonly um: "🇺🇲";
+    readonly un: "🇺🇳";
+    readonly unitedStates: "🇺🇸";
+    readonly uy: "🇺🇾";
+    readonly uz: "🇺🇿";
+    readonly vatican: "🇻🇦";
+    readonly vc: "🇻🇨";
+    readonly ve: "🇻🇪";
+    readonly vg: "🇻🇬";
+    readonly vi: "🇻🇮";
+    readonly vn: "🇻🇳";
+    readonly vu: "🇻🇺";
+    readonly wf: "🇼🇫";
+    readonly ws: "🇼🇸";
+    readonly xk: "🇽🇰";
+    readonly ye: "🇾🇪";
+    readonly yt: "🇾🇹";
+    readonly za: "🇿🇦";
+    readonly zm: "🇿🇲";
+    readonly zw: "🇿🇼";
+};
+/** Unicode 区域指示符起始码点，两个区域指示符组成国旗 emoji。 */
+export declare const REGION_INDICATOR_MIN_CODE_POINT = 127462;
+/** Unicode 区域指示符结束码点，用于限制国旗 emoji 的合法范围。 */
+export declare const REGION_INDICATOR_MAX_CODE_POINT = 127487;
+/** 离屏 emoji 栅格化时使用的像素倍率，保证高分屏采样足够细。 */
+export declare const DEVICE_PIXEL_RATIO: number;
+/** 全局视觉色板：纸张、边框和投影色在多个旗帜绘制函数中复用。 */
+export declare const PALETTE: {
+    readonly paper: "#fbfdfa";
+    readonly frame: "#d9e3db";
+    readonly shadow: "rgba(36, 49, 44, 0.08)";
+};

package/dist/flag-utils.d.ts

@@ -0,0 +1,4 @@
+/** 把任意输入规范化为可绘制的国旗 emoji；非法输入回退到中国国旗。 */
+export declare function resolveFlag(value: unknown): string;
+/** 判断字符串是否由两个区域指示符组成，这是 Unicode 国旗 emoji 的编码形式。 */
+export declare function isFlagEmoji(value: string): boolean;