@yunzai-ng/jsx 0.1.0

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@yunzai-ng/jsx",
+  "version": "0.1.0",
+  "description": "Yunzai NG 模板用 JSX 运行时（字符串直出，无虚拟 DOM）",
+  "type": "module",
+  "license": "AGPL-3.0-or-later",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./jsx-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./jsx-dev-runtime": {
+      "types": "./dist/jsx-runtime.d.ts",
+      "import": "./dist/jsx-runtime.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@yunzai-ng/types": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}

package/src/element.ts

@@ -0,0 +1,100 @@
+/**
+ * 模块职责：把标签名与属性对象序列化成 HTML 文本
+ * 依赖方向：仅依赖同包的 `html.ts`
+ * 生命周期：无状态，纯函数
+ * 注意事项：标签名与属性名均须通过白名单校验。属性名并非全部来自源码字面量 ——
+ *          `{...props}` 展开可以把任意键带进来，其中若含空格或引号，即可在生成的标签里
+ *          插入一个新属性。此处直接抛错而非静默丢弃：这类问题在模板作者一侧一次性可修，
+ *          悄悄少输出一个属性反而要到成品图上才被发现。
+ */
+import { children, cx, escape, style } from "./html.js"
+import type { Child, ClassValue, StyleDict } from "./types.js"
+
+/**
+ * 空元素（HTML 规范中不允许有内容、也不写闭合标签的那些）
+ *
+ * 为它们补一个 `</img>` 会被解析器当作多余的结束标签忽略，看似无害；但 `<br></br>`
+ * 在部分场景下会被解析成两个换行。按规范只输出开始标签。
+ */
+const VOID_TAGS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+])
+
+/** React 为规避 JS 保留字而改名的两个属性，作为别名接纳 */
+const ALIASES: Readonly<Record<string, string>> = { className: "class", htmlFor: "for" }
+
+/** 不参与属性输出的键 */
+const DROPPED = new Set(["children", "key", "class", "className"])
+
+/** 合法标签名 */
+const VALID_TAG = /^[A-Za-z][\w.:-]*$/
+
+/** 合法属性名；与 HTML 规范一致地允许连字符、点与冒号 */
+const VALID_ATTR = /^[A-Za-z_:][\w.:-]*$/
+
+/**
+ * 序列化属性
+ * @param props 属性对象
+ * @returns 以空格开头的属性串；无属性时为空串
+ * @throws 属性名不合法时抛出 TypeError
+ */
+export function attributes(props: Readonly<Record<string, unknown>>): string {
+  let out = ""
+
+  // class 与 className 合并后一次输出：两者都写时分别输出会得到两个 class 属性，
+  // 浏览器只认第一个，后一个静默丢失
+  const classes = cx(props["class"] as ClassValue, props["className"] as ClassValue)
+  if (classes) out += ` class="${escape(classes)}"`
+
+  for (const [key, value] of Object.entries(props)) {
+    if (DROPPED.has(key)) continue
+    if (value === null || value === undefined || value === false) continue
+
+    const name = ALIASES[key] ?? key
+    if (!VALID_ATTR.test(name)) throw new TypeError(`非法的属性名：${JSON.stringify(key)}`)
+
+    // 布尔属性（hidden、disabled 之类）输出裸属性名。写成 `hidden="false"` 反而是生效的，
+    // 因为 HTML 只看属性是否存在
+    if (value === true) {
+      out += ` ${name}`
+      continue
+    }
+
+    if (name === "style") {
+      const css = style(value as string | StyleDict)
+      if (css) out += ` style="${escape(css)}"`
+      continue
+    }
+
+    out += ` ${name}="${escape(value)}"`
+  }
+
+  return out
+}
+
+/**
+ * 序列化一个元素
+ * @param tag 标签名
+ * @param props 属性对象（含 `children`）
+ * @returns HTML 文本
+ * @throws 标签名不合法时抛出 TypeError
+ */
+export function element(tag: string, props: Readonly<Record<string, unknown>>): string {
+  if (!VALID_TAG.test(tag)) throw new TypeError(`非法的标签名：${JSON.stringify(tag)}`)
+  const head = `<${tag}${attributes(props)}>`
+  if (VOID_TAGS.has(tag.toLowerCase())) return head
+  return `${head}${children(props["children"] as Child)}</${tag}>`
+}

package/src/html.ts

@@ -0,0 +1,162 @@
+/**
+ * 模块职责：HTML 文本的载体、转义，以及 `class` / `style` / 子节点的求值
+ * 依赖方向：叶子模块，仅取同包的类型
+ * 生命周期：无状态，全部为纯函数
+ * 注意事项：默认行为是**转义**，`raw()` 是唯一的逃生口。反过来（默认原样输出、需要时
+ *          显式转义）在实践中必然遗漏 —— 米游社返回的昵称含一个尖括号即可破坏整张图的
+ *          结构，而这种数据只在真机上才会出现，单测覆盖不到。
+ */
+import type { Child, ClassValue, StyleDict } from "./types.js"
+
+/** 需要转义的五个字符 */
+const ENTITIES: Readonly<Record<string, string>> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+}
+
+/** 转义匹配式；单引号一并处理，使属性值以单引号包裹时同样安全 */
+const NEED_ESCAPE = /[&<>"']/g
+
+/**
+ * 已完成转义、可直接写入文档的 HTML 文本
+ *
+ * 仅是一个带类型标记的字符串包装：模板的产物是一次性的文本，虚拟 DOM 的 diff 能力在此
+ * 毫无用处，而 react / preact 会为此引入数十个传递依赖。Termux 上包体越小越好，
+ * 这笔交换不成立。
+ */
+export class Html {
+  /** HTML 文本 */
+  readonly value: string
+
+  /**
+   * @param value 已转义的 HTML 文本
+   */
+  constructor(value: string) {
+    this.value = value
+  }
+
+  /**
+   * 判定任意值是否为 Html
+   * @param input 待判定的值
+   * @returns 是 Html 则为真
+   */
+  static is(input: unknown): input is Html {
+    return input instanceof Html
+  }
+
+  /**
+   * 取 HTML 文本
+   * @returns HTML 文本
+   */
+  toString(): string {
+    return this.value
+  }
+
+  /**
+   * 参与 `JSON.stringify` 时退化为文本，使快照测试可直接序列化
+   * @returns HTML 文本
+   */
+  toJSON(): string {
+    return this.value
+  }
+}
+
+/**
+ * 转义为 HTML 文本
+ *
+ * `null` 与 `undefined` 转为空串而非字面量 "null" —— 模板里 `{user.nick}` 取到空值时
+ * 应当什么都不显示，打印出 "undefined" 只会出现在成品图上。
+ * @param input 任意值
+ * @returns 转义后的文本
+ */
+export function escape(input: unknown): string {
+  if (input === null || input === undefined) return ""
+  return String(input).replace(NEED_ESCAPE, ch => ENTITIES[ch] ?? ch)
+}
+
+/**
+ * 声明一段文本已经是安全的 HTML，跳过转义
+ *
+ * 唯一的逃生口，仅用于本模块自己生成的标签、`<!DOCTYPE html>`，以及编译产物这类
+ * 确定安全的内容。**不要**用它包裹任何来自接口的数据。
+ * @param value HTML 文本
+ * @returns 载体
+ */
+export function raw(value: string): Html {
+  return new Html(value)
+}
+
+/**
+ * 求值类名
+ *
+ * 接纳字符串、条件字典与任意嵌套数组三种形态，使 `class={["cont", full && "full"]}`
+ * 与 `class={{ up: delta > 0 }}` 都可直接书写，无需在模板里拼字符串。
+ * @param inputs 任意个类名输入
+ * @returns 以空格分隔、已去重的类名串
+ */
+export function cx(...inputs: ClassValue[]): string {
+  const out: string[] = []
+  push(inputs, out)
+  return [...new Set(out)].join(" ")
+}
+
+/**
+ * `cx` 的递归收集部分
+ * @param input 类名输入
+ * @param out 收集容器
+ */
+function push(input: ClassValue, out: string[]): void {
+  if (input === null || input === undefined || input === false || input === "") return
+  if (typeof input === "string") {
+    for (const part of input.split(/\s+/)) if (part) out.push(part)
+    return
+  }
+  if (typeof input === "number") {
+    out.push(String(input))
+    return
+  }
+  if (Array.isArray(input)) {
+    for (const item of input) push(item, out)
+    return
+  }
+  for (const [name, on] of Object.entries(input)) if (on) push(name, out)
+}
+
+/**
+ * 求值内联样式
+ *
+ * 数值不会被自动补上 `px`：React 的这套隐式补单位规则需要一张"哪些属性是长度"的名单，
+ * 名单不全时表现为样式静默失效。此处要求显式书写单位，宽度写成百分号模板串一目了然。
+ * 以 `--` 开头的自定义属性保留原始大小写 —— 它们区分大小写，转换会改变含义。
+ * @param input 样式字符串或字典
+ * @returns CSS 声明串
+ */
+export function style(input: string | StyleDict): string {
+  if (typeof input === "string") return input
+  const out: string[] = []
+  for (const [property, value] of Object.entries(input)) {
+    if (value === null || value === undefined || value === false || value === "") continue
+    const name = property.startsWith("--") ? property : property.replace(/[A-Z]/g, ch => `-${ch.toLowerCase()}`)
+    out.push(`${name}: ${String(value)}`)
+  }
+  return out.join("; ")
+}
+
+/**
+ * 求值子节点
+ * @param child 子节点
+ * @returns 拼接好的 HTML 文本
+ */
+export function children(child: Child): string {
+  if (child === null || child === undefined || typeof child === "boolean") return ""
+  if (child instanceof Html) return child.value
+  if (Array.isArray(child)) {
+    let out = ""
+    for (const item of child) out += children(item)
+    return out
+  }
+  return escape(child)
+}

package/src/index.test.ts

@@ -0,0 +1,170 @@
+/**
+ * 模块职责：`@yunzai-ng/jsx` 的行为固定
+ * 依赖方向：测试文件，只引本包
+ * 生命周期：无状态
+ * 注意事项：此处固定的是"默认转义"这一安全口径。米游社返回的昵称、公告标题、兑换码
+ *          说明均为用户可控文本，其中出现一个尖括号即可破坏整张图的结构，而这种数据
+ *          只在真机上才会出现 —— 必须由单测把住。
+ */
+import { describe, expect, it } from "vitest"
+import { attributes, children, cx, defineTemplate, element, escape, Fragment, Html, jsx, jsxs, raw, style } from "./index.js"
+
+describe("escape", () => {
+  it("转义五个危险字符", () => {
+    expect(escape(`&<>"'`)).toBe("&amp;&lt;&gt;&quot;&#39;")
+  })
+
+  it("空值转为空串而不是字面量", () => {
+    expect(escape(null)).toBe("")
+    expect(escape(undefined)).toBe("")
+  })
+
+  it("数字与零照常输出", () => {
+    expect(escape(0)).toBe("0")
+    expect(escape(12.5)).toBe("12.5")
+  })
+})
+
+describe("Html", () => {
+  it("raw 跳过转义", () => {
+    expect(raw("<b>x</b>").toString()).toBe("<b>x</b>")
+  })
+
+  it("可被 JSON 序列化为文本，便于快照", () => {
+    expect(JSON.stringify(raw("<i>"))).toBe('"<i>"')
+  })
+
+  it("能被判定", () => {
+    expect(Html.is(raw(""))).toBe(true)
+    expect(Html.is("<b>")).toBe(false)
+    expect(Html.is(null)).toBe(false)
+  })
+})
+
+describe("cx", () => {
+  it("接纳字符串、字典与嵌套数组", () => {
+    expect(cx("cont", ["full", ["wide"]], { up: true, down: false })).toBe("cont full wide up")
+  })
+
+  it("丢弃空值", () => {
+    expect(cx(null, undefined, false, "")).toBe("")
+  })
+
+  it("去重", () => {
+    expect(cx("cont", "cont cell")).toBe("cont cell")
+  })
+})
+
+describe("style", () => {
+  it("驼峰键转为连字符", () => {
+    expect(style({ fontSize: "13px", backgroundColor: "red" })).toBe("font-size: 13px; background-color: red")
+  })
+
+  it("自定义属性保留原始大小写", () => {
+    expect(style({ "--gapX": "4px" })).toBe("--gapX: 4px")
+  })
+
+  it("数值原样输出，不自动补 px", () => {
+    expect(style({ "z-index": 3 })).toBe("z-index: 3")
+  })
+
+  it("字符串原样通过", () => {
+    expect(style("width: 50%")).toBe("width: 50%")
+  })
+})
+
+describe("children", () => {
+  it("布尔与空值渲染为空串，使短路写法可直接书写", () => {
+    expect(children([true, false, null, undefined])).toBe("")
+  })
+
+  it("文本被转义，Html 原样通过", () => {
+    expect(children(["<b>", raw("<b>")])).toBe("&lt;b&gt;<b>")
+  })
+
+  it("数组任意嵌套", () => {
+    expect(children([["a", ["b"]], "c"])).toBe("abc")
+  })
+
+  it("零会被渲染出来", () => {
+    expect(children(0)).toBe("0")
+  })
+})
+
+describe("attributes", () => {
+  it("class 与 className 合并成一个属性", () => {
+    expect(attributes({ class: "cont", className: { full: true } })).toBe(' class="cont full"')
+  })
+
+  it("htmlFor 映射为 for", () => {
+    expect(attributes({ htmlFor: "x" })).toBe(' for="x"')
+  })
+
+  it("true 输出裸属性名，false 与空值整项省略", () => {
+    expect(attributes({ hidden: true, disabled: false, title: null })).toBe(" hidden")
+  })
+
+  it("style 接受字典", () => {
+    expect(attributes({ style: { width: "50%" } })).toBe(' style="width: 50%"')
+  })
+
+  it("属性值被转义，无法逃出引号", () => {
+    expect(attributes({ title: 'a" onload="alert(1)' })).toBe(' title="a&quot; onload=&quot;alert(1)"')
+  })
+
+  it("children 与 key 不进属性", () => {
+    expect(attributes({ children: "x", key: 1 })).toBe("")
+  })
+
+  it("非法属性名直接抛错，而不是静默丢弃", () => {
+    expect(() => attributes({ "a b": "1" })).toThrow(/非法的属性名/)
+  })
+})
+
+describe("element", () => {
+  it("空元素不输出闭合标签", () => {
+    expect(element("img", { src: "a.png" })).toBe('<img src="a.png">')
+    expect(element("br", {})).toBe("<br>")
+  })
+
+  it("普通元素带闭合标签与子节点", () => {
+    expect(element("div", { class: "cont", children: "文本" })).toBe('<div class="cont">文本</div>')
+  })
+
+  it("非法标签名直接抛错", () => {
+    expect(() => element("div onload=x", {})).toThrow(/非法的标签名/)
+  })
+})
+
+describe("jsx 运行时", () => {
+  it("按编译器实际发出的形态调用", () => {
+    expect(jsx("span", { children: "x" }).toString()).toBe("<span>x</span>")
+    expect(jsxs("ul", { children: [jsx("li", { children: 1 }), jsx("li", { children: 2 })] }).toString()).toBe(
+      "<ul><li>1</li><li>2</li></ul>"
+    )
+  })
+
+  it("jsxs 与 jsx 是同一实现", () => {
+    expect(jsxs).toBe(jsx)
+  })
+
+  it("函数组件被调用并展开", () => {
+    const Card = (props: { title: string }): Html => jsx("h1", { children: props.title })
+    expect(jsx(Card, { title: "深渊" }).toString()).toBe("<h1>深渊</h1>")
+  })
+
+  it("Fragment 只拼接子节点，不产生标签", () => {
+    expect(jsx(Fragment, { children: ["a", "b"] }).toString()).toBe("ab")
+  })
+
+  it("属性缺省时也能渲染", () => {
+    expect(jsx("hr").toString()).toBe("<hr>")
+  })
+})
+
+describe("defineTemplate", () => {
+  it("产出带 doctype 的完整页面与页面名", () => {
+    const Page = defineTemplate("demo", (props: { uid: string }) => jsx("html", { children: props.uid }))
+    expect(Page({ uid: "1" })).toEqual({ name: "demo", html: "<!DOCTYPE html><html>1</html>" })
+  })
+})

package/src/index.ts

@@ -0,0 +1,40 @@
+/**
+ * 模块职责：`@yunzai-ng/jsx` 的公开入口
+ * 依赖方向：仅依赖 `@yunzai-ng/types`（取 `RenderablePage` 的形状）
+ * 生命周期：无状态
+ * 注意事项：本包独立于 `@yunzai-ng/core` 而非作为它的一个子路径导出。分层门禁把
+ *          `@yunzai-ng/core/*` 的任意子路径判为"深引内核内部实现"，为一个 JSX 运行时
+ *          给门禁开洞并不划算；独立成包后第三方插件也可单独依赖它而不必牵入整个内核。
+ */
+import type { RenderablePage } from "@yunzai-ng/types"
+import { children } from "./html.js"
+import type { Child } from "./types.js"
+
+export { Html, escape, raw, cx, style, children } from "./html.js"
+export { attributes, element } from "./element.js"
+export { Fragment, jsx, jsxs, jsxDEV } from "./jsx-runtime.js"
+export type { ElementType } from "./jsx-runtime.js"
+export type { Child, ClassDict, ClassValue, Component, HtmlAttributes, StyleDict } from "./types.js"
+
+/** HTML5 文档类型声明；缺了它浏览器进入怪异模式，盒模型与行高全部改变 */
+const DOCTYPE = "<!DOCTYPE html>"
+
+/**
+ * 把一个组件封装成模板
+ *
+ * 产物可直接交给 `ctx.render()` / `e.renderReply()`：
+ *
+ * ```tsx
+ * export const Abyss = defineTemplate("abyss", (view: AbyssView) => <Page>…</Page>)
+ * await e.renderReply(Abyss(view))
+ * ```
+ *
+ * 由此模板数据的类型在调用处即被检查 —— 视图层改了字段名，编译当场失败，而不是等到
+ * 真机出图时得到一张空白图。模板同时退化成纯函数，可直接快照测试，不需要浏览器。
+ * @param name 页面名，用于日志、临时文件名与统计
+ * @param component 组件；返回整份文档（不含 doctype，由本函数补上）
+ * @returns 接受同样属性、返回可渲染页面的函数
+ */
+export function defineTemplate<P>(name: string, component: (props: P) => Child): (props: P) => RenderablePage {
+  return (props: P): RenderablePage => ({ name, html: DOCTYPE + children(component(props)) })
+}

package/src/jsx-runtime.ts

@@ -0,0 +1,85 @@
+/**
+ * 模块职责：TypeScript 自动 JSX 转换所要求的运行时入口（`jsx` / `jsxs` / `Fragment`）
+ * 依赖方向：仅依赖同包的 `html.ts` 与 `element.ts`
+ * 生命周期：无状态，纯函数
+ * 注意事项：`jsx` 与 `jsxs` 为同一实现。二者的区别在于 `jsxs` 保证 `children` 已是数组
+ *          且不会被改写，React 借此跳过 key 校验；此处不存在协调过程，无从利用该保证。
+ *
+ *          `jsx-dev-runtime` 亦指向本文件：开发版签名多出 `isStaticChildren` / `source`
+ *          / `self` 三个参数，全部用于 React 的错误提示，与产出的 HTML 无关。
+ */
+import { children, Html, raw } from "./html.js"
+import { element } from "./element.js"
+import type { Child, HtmlAttributes } from "./types.js"
+
+/**
+ * JSX 标签位置可出现的类型
+ *
+ * 函数组件的属性类型声明为 `never`：函数类型的参数按逆变判定，`never` 可被任意参数类型
+ * 接受，因此这是"任意一元函数"的写法。真正的属性类型检查由 TSX 在标签处完成，
+ * 与此签名无关。
+ */
+export type ElementType = string | ((props: never) => Child)
+
+/**
+ * 片段：把多个同级节点合成一个返回值
+ *
+ * 它就是一个普通函数组件，`<>…</>` 编译成 `jsx(Fragment, { children })` 后自然生效，
+ * 无需在 `jsx()` 里为它开特例。
+ * @param props 仅取 `children`
+ * @returns 拼接好的子节点
+ */
+export function Fragment(props: { children?: Child }): Html {
+  return raw(children(props.children))
+}
+
+/**
+ * 创建一个节点
+ * @param type 标签名或函数组件
+ * @param props 属性；`children` 亦在其中
+ * @returns 渲染好的 HTML
+ * @throws 标签名或属性名不合法时抛出 TypeError
+ */
+export function jsx(type: ElementType, props: Readonly<Record<string, unknown>> = {}): Html {
+  if (typeof type === "function") {
+    return raw(children((type as (props: Readonly<Record<string, unknown>>) => Child)(props)))
+  }
+  return raw(element(type, props))
+}
+
+export { jsx as jsxs, jsx as jsxDEV }
+
+/**
+ * TSX 类型契约
+ *
+ * TypeScript 在 `jsxImportSource` 指向的模块上查找这个命名空间，用它判定标签合法性、
+ * 子节点属性名与元素类型。
+ */
+export namespace JSX {
+  /** 一次渲染的产物 */
+  export interface Element extends Html {}
+
+  /** 告知 TypeScript 以 `children` 属性接收子节点 */
+  export interface ElementChildrenAttribute {
+    /** 属性名本身才是这里唯一有意义的信息，类型不参与判定 */
+    children: object
+  }
+
+  /**
+   * 内建标签
+   *
+   * 以索引签名放开全部标签：逐一枚举 HTML 元素及其专属属性需要数千行声明，而模板作者
+   * 真正需要的约束是 `class` / `style` / `children` 的形态，这三项已在 `HtmlAttributes`
+   * 中给出。拼错标签名的代价是浏览器把它当作未知内联元素，肉眼可见，不必由类型系统兜住。
+   */
+  export interface IntrinsicElements {
+    /** 任意标签 */
+    [tag: string]: HtmlAttributes
+  }
+
+  /** 所有元素隐含允许的属性 */
+  export interface IntrinsicAttributes {
+    /** 兼容 React 写法而接纳，渲染时丢弃 */
+    key?: string | number
+  }
+}

package/src/types.ts

@@ -0,0 +1,53 @@
+/**
+ * 模块职责：JSX 层的公共类型契约
+ * 依赖方向：仅依赖同包的 `html.ts`（取 `Html` 作为节点类型），不引任何工作区包
+ * 生命周期：纯类型，编译后不留痕迹
+ * 注意事项：属性名**不作 camelCase 转换**，一律按真实 HTML 书写（`stroke-width`、
+ *          `tabindex`、`data-x`）。TSX 语法本身允许带连字符的属性名，无需转换即可书写；
+ *          而一旦引入转换，`viewBox` 这类 SVG 属性与 `data-camelCase` 就会出现两套
+ *          互相冲突的规则。唯二的例外是 `className` 与 `htmlFor` —— 它们是 React 为
+ *          规避 JS 保留字留下的历史包袱，作为别名接纳以降低迁移成本。
+ */
+import type { Html } from "./html.js"
+
+/** 以键为类名、值为是否启用的字典 */
+export interface ClassDict {
+  /** 类名 → 是否启用 */
+  [name: string]: boolean | null | undefined
+}
+
+/** `class` 属性可接受的形态：字符串、条件字典、以及两者的任意嵌套数组 */
+export type ClassValue = string | number | false | null | undefined | ClassDict | ClassValue[]
+
+/** 内联样式字典；键为 CSS 属性名或 `--` 自定义属性 */
+export interface StyleDict {
+  /** CSS 属性名 → 取值；数值不会被自动补单位，需要单位时自行拼接 */
+  [property: string]: string | number | null | undefined | false
+}
+
+/**
+ * 子节点
+ *
+ * `null` / `undefined` / 布尔值渲染为空串，使 `{cond && <div/>}` 与 `{value ?? null}`
+ * 这两种最常用的条件写法无需额外处理。
+ */
+export type Child = Html | string | number | bigint | boolean | null | undefined | Child[]
+
+/** 元素属性 */
+export interface HtmlAttributes {
+  /** 类名 */
+  class?: ClassValue
+  /** 类名，`class` 的别名 */
+  className?: ClassValue
+  /** 内联样式 */
+  style?: string | StyleDict
+  /** 子节点 */
+  children?: Child
+  /** 兼容 React 写法而接纳，渲染时丢弃 —— 此处没有需要复用节点的协调过程 */
+  key?: string | number
+  /** 其余属性原样输出；值为 `true` 输出裸属性名，为 `false`/`null`/`undefined` 则整项省略 */
+  [attr: string]: unknown
+}
+
+/** 函数组件：接收属性、返回一段 HTML */
+export type Component<P = Record<string, never>> = (props: P) => Html