rough-emoji-draw 0.2.1 → 0.2.3

package/README.en.md

@@ -7,11 +7,10 @@ Rough Emoji Draw is a lightweight frontend library that renders Unicode flag emo
 ## Features
 
 - Draw Unicode flag emojis onto a given `canvas`.
-- Hand-drawn templates for common flags such as China, Japan, the United States, Australia, Thailand, France, Italy, Spain, and Vatican City.
-- A unified fallback pipeline via emoji rasterization and pixel sampling for flags without dedicated templates.
+- About 100 hand-drawn flag templates (including China, Japan, the United States, Australia, Thailand, France, Italy, Spain, Vatican City, and more); remaining regions use a unified emoji rasterization and pixel-sampling fallback.
 - Three integration paths: npm `import` / Node `require`, and browser `<script>` with the global `window.RoughEmoji`.
 - TypeScript declaration files for API autocomplete in TS projects.
-- An `index.html` batch QA page to visually inspect 240+ country/region flags.
+- An `index.html` batch QA page to preview 240+ country/region flags, with search by region code or localized name, and one-click copy of transparent-background SVG.
 
 ## Tech Stack
 
@@ -73,6 +72,12 @@ const canvas = document.querySelector<HTMLCanvasElement>("#flag-canvas")!;
 RoughEmoji.draw(canvas, "🇨🇳");
 ```
 
+You can also import utility functions directly:
+
+```ts
+import { isFlagEmoji, resolveFlag } from "rough-emoji-draw";
+```
+
 ### npm package (CommonJS / Node)
 
 ```js
@@ -96,11 +101,17 @@ Load the IIFE bundle only; it automatically attaches `window.RoughEmoji`:
 </script>
 ```
 
-If the page includes the demo form DOM (`#rough-canvas`, `#emoji-form`, etc.), load the root-level `rough-emoji-app.js` to wire up interaction and download handlers:
+You can also reference the same IIFE file via the package export subpath:
+
+```html
+<script src="./node_modules/rough-emoji-draw/dist/rough-emoji.js"></script>
+```
+
+If the page includes the demo form DOM (`#rough-canvas`, `#emoji-form`, etc.), load `demo/rough-emoji-app.js` to wire up interaction and PNG download handlers:
 
 ```html
 <script src="./dist/rough-emoji.js"></script>
-<script src="./rough-emoji-app.js"></script>
+<script type="module" src="./demo/rough-emoji-app.js"></script>
 ```
 
 ## API
@@ -111,11 +122,11 @@ Normalizes the input to a flag emoji and draws it on the given `HTMLCanvasElemen
 
 ### `RoughEmoji.isFlagEmoji(value)`
 
-Returns whether the string is a flag emoji composed of two regional indicator symbols.
+Returns whether the string is a flag emoji composed of two regional indicator symbols. Also available as the named export `isFlagEmoji`.
 
 ### `RoughEmoji.resolveFlag(value)`
 
-Converts arbitrary input into a drawable flag emoji. Only valid flag emojis are accepted; invalid values fall back to `🇨🇳`.
+Converts arbitrary input into a drawable flag emoji. Only valid flag emojis are accepted; invalid values fall back to `🇨🇳`. Also available as the named export `resolveFlag`.
 
 ### Type exports
 
@@ -132,12 +143,16 @@ You can also import `RoughOptions`, `Point`, and `RoughCanvasLike` as needed.
 ├── src/
 │   ├── index.ts           # npm library entry; exports API and types
 │   ├── browser.ts         # browser IIFE entry; mounts window.RoughEmoji
-│   ├── rough-emoji.ts     # core drawing logic
+│   ├── rough-emoji.ts     # drawing facade and render dispatch
+│   ├── flag-drawers.ts    # per-flag hand-drawn templates and fallback drawing
 │   ├── flag-utils.ts      # flag emoji parsing and validation
 │   ├── render-context.ts  # canvas context switching
 │   ├── constant.ts        # static constants and template map
 │   └── types.ts           # public type declarations
-├── rough-emoji-app.js     # index.html demo DOM bindings (not in npm artifacts)
+├── demo/
+│   ├── index.js              # index.html batch QA script (search, render, copy SVG)
+│   ├── index-svg-export.js   # canvas flag crop and transparent SVG export
+│   └── rough-emoji-app.js    # single-page demo form bindings and PNG download (not in npm artifacts)
 ├── index.html             # batch visual QA page
 ├── rslib.config.ts        # Rslib multi-format build config
 ├── tsconfig.json          # TypeScript config
@@ -146,7 +161,7 @@ You can also import `RoughOptions`, `Point`, and `RoughCanvasLike` as needed.
 
 ## Development Notes
 
-- Add new flags in `src/rough-emoji.ts` with dedicated draw functions and register them in the template dispatch table.
+- Add new flags in `src/flag-drawers.ts` with dedicated draw functions and register them in the `templateDrawers` dispatch table; `src/rough-emoji.ts` handles orchestration and does not contain per-flag drawing logic.
 - Draw functions use a square canvas coordinate system; derive new coordinates from `size` or existing flag layout variables.
-- After changing drawing behavior, run `pnpm run typecheck`, then `pnpm run build`, and inspect results in `index.html`.
-- `dist/` is build output and is usually not maintained as source; run `pnpm run build` before publishing or local preview.
+- After changing drawing behavior, run `pnpm run typecheck`, then `pnpm run build`, and inspect results via `pnpm run dev` on `index.html`.
+- Scripts under `demo/` are for local demo and QA only and are not published with the npm package; `dist/` is build output and is usually not maintained as source.

package/README.md

@@ -7,11 +7,10 @@ Rough Emoji Draw 是一个把 Unicode 国旗 emoji 绘制成 Rough.js 手写风
 ## 功能特性
 
 - 将 Unicode 国旗 emoji 绘制到指定 `canvas`。
-- 内置中国、日本、美国、澳大利亚、泰国、法国、意大利、西班牙、梵蒂冈等常见旗帜的手写模板。
-- 对未单独适配的国旗使用 emoji 栅格化与像素采样流程生成统一风格的 fallback 图像。
+- 内置约 100 面国旗的手写模板（含中国、日本、美国、澳大利亚、泰国、法国、意大利、西班牙、梵蒂冈等），其余地区走统一的 emoji 栅格化与像素采样 fallback。
 - 支持三种接入方式：npm `import` / Node `require`、浏览器 `<script>` 全局变量 `window.RoughEmoji`。
 - 提供 TypeScript 类型声明，可在 TS 项目中直接获得 API 提示。
-- 提供 `index.html` 批量 QA 页面，用于检查 240+ 国家/地区旗帜绘制效果。
+- 提供 `index.html` 批量 QA 页面，预览 240+ 国家/地区旗帜，支持按地区码或中文名搜索，并可一键复制透明背景 SVG。
 
 ## 技术栈
 
@@ -73,6 +72,12 @@ const canvas = document.querySelector<HTMLCanvasElement>("#flag-canvas")!;
 RoughEmoji.draw(canvas, "🇨🇳");
 ```
 
+也可按需导入独立工具函数：
+
+```ts
+import { isFlagEmoji, resolveFlag } from "rough-emoji-draw";
+```
+
 ### npm 包（CommonJS / Node）
 
 ```js
@@ -96,11 +101,17 @@ console.log(typeof RoughEmoji.draw); // "function"
 </script>
 ```
 
-若页面包含演示表单 DOM（`#rough-canvas`、`#emoji-form` 等），可额外加载根目录下的 `rough-emoji-app.js` 绑定交互与下载逻辑：
+也可通过包导出子路径引用同一 IIFE 文件：
+
+```html
+<script src="./node_modules/rough-emoji-draw/dist/rough-emoji.js"></script>
+```
+
+若页面包含演示表单 DOM（`#rough-canvas`、`#emoji-form` 等），可额外加载 `demo/rough-emoji-app.js` 绑定交互与 PNG 下载逻辑：
 
 ```html
 <script src="./dist/rough-emoji.js"></script>
-<script src="./rough-emoji-app.js"></script>
+<script type="module" src="./demo/rough-emoji-app.js"></script>
 ```
 
 ## API
@@ -111,11 +122,11 @@ console.log(typeof RoughEmoji.draw); // "function"
 
 ### `RoughEmoji.isFlagEmoji(value)`
 
-判断字符串是否为由两个区域指示符组成的国旗 emoji。
+判断字符串是否为由两个区域指示符组成的国旗 emoji。也可作为命名导出 `isFlagEmoji` 直接使用。
 
 ### `RoughEmoji.resolveFlag(value)`
 
-把任意输入转换为可绘制的国旗 emoji；当前只接受合法国旗 emoji，非法值回退为 `🇨🇳`。
+把任意输入转换为可绘制的国旗 emoji；当前只接受合法国旗 emoji，非法值回退为 `🇨🇳`。也可作为命名导出 `resolveFlag` 直接使用。
 
 ### 类型导出
 
@@ -132,12 +143,16 @@ import type { RoughEmojiApi } from "rough-emoji-draw";
 ├── src/
 │   ├── index.ts          # npm 库入口，导出 API 与类型
 │   ├── browser.ts        # 浏览器 IIFE 入口，挂载 window.RoughEmoji
-│   ├── rough-emoji.ts    # 核心绘制逻辑
+│   ├── rough-emoji.ts    # 绘制门面与渲染调度
+│   ├── flag-drawers.ts   # 各国旗手写模板与 fallback 绘制
 │   ├── flag-utils.ts     # 国旗 emoji 解析与校验
 │   ├── render-context.ts # Canvas 上下文切换
 │   ├── constant.ts       # 静态常量与模板映射
 │   └── types.ts          # 对外类型声明
-├── rough-emoji-app.js    # index.html 演示页 DOM 绑定（不进入 npm 产物）
+├── demo/
+│   ├── index.js              # index.html 批量 QA 页脚本（搜索、渲染、复制 SVG）
+│   ├── index-svg-export.js   # Canvas 旗面裁剪与透明 SVG 导出
+│   └── rough-emoji-app.js    # 单页演示表单绑定与 PNG 下载（不进入 npm 产物）
 ├── index.html            # 批量视觉 QA 页面
 ├── rslib.config.ts       # Rslib 多格式构建配置
 ├── tsconfig.json         # TypeScript 配置
@@ -146,7 +161,7 @@ import type { RoughEmojiApi } from "rough-emoji-draw";
 
 ## 开发说明
 
-- 新增旗帜优先在 `src/rough-emoji.ts` 中补充独立绘制函数，并在模板分发表中接入。
+- 新增旗帜优先在 `src/flag-drawers.ts` 中补充独立绘制函数，并在 `templateDrawers` 分发表中接入；`src/rough-emoji.ts` 负责调度，不直接承载具体旗面绘制。
 - 绘制函数按正方形画布坐标系工作，新增坐标建议基于当前 `size` 或已有旗帜区域变量推导。
-- 修改绘制效果后，先运行 `pnpm run typecheck`，再运行 `pnpm run build` 并打开 `index.html` 进行视觉检查。
-- `dist/` 为构建产物，通常不作为源码维护对象；发布或本地预览前执行 `pnpm run build` 即可。
+- 修改绘制效果后，先运行 `pnpm run typecheck`，再运行 `pnpm run build`，并通过 `pnpm run dev` 打开 `index.html` 进行视觉检查。
+- `demo/` 下的页面脚本仅用于本地演示与 QA，不随 npm 包发布；`dist/` 为构建产物，通常不作为源码维护对象。

package/dist/flag-drawers.d.ts

@@ -0,0 +1,9 @@
+import { TEMPLATE_FLAGS } from "./constant";
+/** 专门模板绘制函数签名。 */
+export type FlagDrawer = () => void;
+/** 专门模板覆盖的国旗 emoji 联合类型。 */
+export type TemplateFlag = (typeof TEMPLATE_FLAGS)[keyof typeof TEMPLATE_FLAGS];
+/** 未覆盖输入的兜底绘制流程，保留较克制的细节数量以控制性能。 */
+export declare function drawGenericFlag(flagEmoji: string): void;
+/** 专门模板分发表：每个标准国旗都有独立绘制入口，避免大量 if 分支。 */
+export declare const templateDrawers: Record<TemplateFlag, FlagDrawer>;