@zerodep-dev/vue-tsx-pro-tsx 0.0.0-stage → 0.1.0

package/types/jsx-runtime.d.ts

@@ -0,0 +1,174 @@
+/**
+ * JSX 类型入口（tsconfig 的 jsxImportSource 指向本包时由 TypeScript 读取）。
+ *
+ * 在 Vue 自带的 JSX 类型（vue/jsx-runtime）上做三处调整：
+ *   1. 内容即 props：JSX 子节点按组件的 children prop 检查
+ *   2. _component 定义的组件：属性直接按 setup 参数的类型检查，泛型也能推导；
+ *      其他 Vue 组件（Transition、Teleport 等内置组件）的子节点照常走默认插槽
+ *   3. 原生元素的事件参数带上具体的 currentTarget：<input onInput={(e) => e.currentTarget.value} />
+ *
+ * 双向绑定写在下划线属性上：组件的可绑定 prop 本身以下划线开头（_value、_open），值是可写的变量或对象属性时
+ * 自动绑定，onUpdate:_value 按 prop 的类型检查；原生元素另有绑定专用的 _value、_checked、_open、_files（见文件末尾）。
+ */
+// 顺带加载符文的全局类型：只要配置了 jsxImportSource，就能直接使用 _state 等
+import type {} from './runes';
+import type { VNodeChild } from 'vue';
+import type { JSX as VueJSX } from 'vue/jsx-runtime';
+
+/**
+ * _component 定义的组件：返回值带 '~tsx' 标记（见 runtime/component.ts）。
+ * Vue 的 FunctionalComponent 返回 any，要先排除，否则会被误判。
+ */
+type IsTsxComponent<C> = C extends (...args: any) => infer R
+  ? 0 extends 1 & R
+    ? false
+    : R extends { readonly '~tsx': true }
+      ? true
+      : false
+  : false;
+
+type ElementOf<Tag> = Tag extends keyof HTMLElementTagNameMap
+  ? HTMLElementTagNameMap[Tag]
+  : Tag extends keyof SVGElementTagNameMap
+    ? SVGElementTagNameMap[Tag]
+    : Element;
+
+/** onXxx 事件处理函数的参数补上 currentTarget 的元素类型 */
+type WithCurrentTarget<Attributes, El> = {
+  [Name in keyof Attributes]: Name extends `on${string}`
+    ? NonNullable<Attributes[Name]> extends (event: infer E) => unknown
+      ? (event: E & { currentTarget: El }) => void
+      : Attributes[Name]
+    : Attributes[Name];
+};
+
+type VueTag = keyof VueJSX.IntrinsicElements;
+type UnionToIntersection<U> = (U extends unknown ? (value: U) => void : never) extends (
+  value: infer I,
+) => void
+  ? I
+  : never;
+type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
+
+/** 某个属性在每个标签上的取值类型，各包一层元组，交叉时才不会把各标签的 undefined 等混在一起 */
+type ValuePerTag<Tag, Name> = Tag extends VueTag
+  ? [VueJSX.IntrinsicElements[Tag][Name & keyof VueJSX.IntrinsicElements[Tag]]]
+  : never;
+
+/**
+ * 可绑定的 prop（下划线开头）的更新回调：写了 onUpdate:_value 就由它处理更新，不再自动写回。
+ * 回调写成方法签名（参数双向协变，同 React 类型里事件回调的做法）：值的类型是几种形态的联合时
+ * （单选是字符串、区间是对象），只处理其中一种的回调也能传。
+ * 泛型组件里把 props 原样转交给另一个泛型组件时，TypeScript 推不动依赖类型参数的这一层：展开的对象写成
+ * `{...(rest as ComboboxProps<T> & UpdateHandlers<ComboboxProps<T>>)}`
+ */
+export type UpdateHandlers<P> = {
+  // Extract<keyof P, string> 而不是 keyof P：不在联合上分配，单选 / 多选两种形态的值并成一个参数类型（分配后回调推不出参数）
+  [K in Extract<keyof P, string> as K extends `_${string}` ? `onUpdate:${K}` : never]?: {
+    bivarianceHack(value: Exclude<P[K], undefined>): void;
+  }['bivarianceHack'];
+};
+
+/** 几个标签共有的属性，每个属性取所有标签都接受的值：<a> 与 <button> 的 type 取 'button' | 'submit' | 'reset' */
+type SharedAttributes<Tag extends VueTag> = {
+  [Name in keyof VueJSX.IntrinsicElements[Tag]]: UnionToIntersection<ValuePerTag<Tag, Name>>[0];
+};
+
+/**
+ * 原生元素的属性。Tag 可以是几个标签的联合（一个工厂生成几个元素的组件、共用实现时，如 ui 的 H1–H6）：
+ * 属性取这些标签共有的部分、取值是每个标签都接受的值，事件参数的 currentTarget 是这几种元素的联合，
+ * 所以属性能直接展开到 `<Tag {...props} />` 上（Tag 是同一组标签之一）。
+ */
+export type IntrinsicProps<Tag extends VueTag> = WithCurrentTarget<
+  IsUnion<Tag> extends true ? SharedAttributes<Tag> : VueJSX.IntrinsicElements[Tag],
+  ElementOf<Tag>
+> & { children?: VNodeChild };
+
+export declare namespace JSX {
+  /** JSX 表达式的结果：同 Vue 的 VNode */
+  interface Element extends VueJSX.Element {}
+  /** 可以当标签用的类组件，同 Vue */
+  interface ElementClass extends VueJSX.ElementClass {}
+  /** 类组件的属性从哪里取，同 Vue */
+  interface ElementAttributesProperty extends VueJSX.ElementAttributesProperty {}
+  /** 子节点对应的 prop 名 */
+  interface ElementChildrenAttribute {
+    children: {};
+  }
+  /** 原生元素的属性：Vue 的定义加上 children 与精确的事件 currentTarget（见 IntrinsicProps） */
+  type IntrinsicElements = {
+    [Tag in keyof VueJSX.IntrinsicElements]: IntrinsicProps<Tag>;
+  };
+  /** 所有元素与组件都接受的属性（key、ref 等），同 Vue */
+  interface IntrinsicAttributes extends VueJSX.IntrinsicAttributes {}
+  /** 组件的属性类型：_component 按参数检查，其他 Vue 组件另外接受插槽内容 */
+  type LibraryManagedAttributes<C, P> = C extends string
+    ? P
+    : IsTsxComponent<C> extends true
+      ? // _component：setup 参数就是全部属性（子节点即 children prop），加上可绑定 prop 的 onUpdate:_x
+        P & UpdateHandlers<P>
+      : // 其他 Vue 组件：内容走默认插槽
+        P & { children?: unknown };
+}
+
+// Vue 3.5 的 HTML 属性类型还没有原生 Popover API 的属性，这里补上（只是类型，运行时原样交给浏览器）
+declare module 'vue' {
+  interface HTMLAttributes {
+    /** 原生弹层：auto 自带 Esc 与点击外部关闭，manual 只由代码开关，hint 不关闭其他 auto 弹层 */
+    popover?: 'auto' | 'manual' | 'hint' | '' | undefined;
+    /** hidden="until-found" 的元素被页内搜索、锚点命中时触发，随后浏览器去掉 hidden */
+    onBeforematch?: (event: Event) => void;
+  }
+  interface ButtonHTMLAttributes {
+    /** 点击时开关的弹层元素 id */
+    popovertarget?: string | undefined;
+    /** 点击时对弹层做什么，默认 toggle */
+    popovertargetaction?: 'toggle' | 'show' | 'hide' | undefined;
+    /** 点击时对哪个元素下命令（Invoker Commands）：目标元素的 id，配合 command */
+    commandfor?: string | undefined;
+    /**
+     * 下的命令：对话框 show-modal / close / request-close，弹层 toggle-popover / show-popover / hide-popover；
+     * 自定义命令以 -- 开头，目标元素在 command 事件里处理
+     */
+    command?:
+      | 'show-modal'
+      | 'close'
+      | 'request-close'
+      | 'toggle-popover'
+      | 'show-popover'
+      | 'hide-popover'
+      | `--${string}`
+      | undefined;
+  }
+  interface HTMLAttributes {
+    /** 收到按钮下的命令（Invoker Commands）：event.command 是命令，event.source 是按下的按钮 */
+    onCommand?: (
+      event: Event & { readonly command: string; readonly source: Element | null },
+    ) => void;
+  }
+  interface DialogHTMLAttributes {
+    /** 哪些操作能关闭对话框：any（Esc、点外面）、closerequest（只有 Esc）、none（只能代码关） */
+    closedby?: 'any' | 'closerequest' | 'none' | undefined;
+  }
+  // 原生元素的双向绑定：_value={x} 编译成 v-model，其余在元素事件之后读回（见 compiler/bind.ts）
+  interface InputHTMLAttributes {
+    /** 双向绑定输入的值：_value={x}，type="number" / "range" 自动按数字；修饰符写 _value={_bind.trim(x)} */
+    _value?: unknown;
+    /** 双向绑定勾选：复选框绑布尔，或绑数组（多选组：勾选时把 value 加进数组） */
+    _checked?: unknown;
+    /** 选中的文件（文件输入）：_files={x}，只读，用户选了文件后写回 x */
+    _files?: FileList | null | undefined;
+  }
+  interface TextareaHTMLAttributes {
+    /** 双向绑定输入的值：_value={x} */
+    _value?: unknown;
+  }
+  interface SelectHTMLAttributes {
+    /** 双向绑定选中的值：_value={x}（多选时绑数组） */
+    _value?: unknown;
+  }
+  interface DetailsHTMLAttributes {
+    /** 双向绑定展开状态：代码设置会展开，用户展开收起后写回 */
+    _open?: boolean | undefined;
+  }
+}

package/types/runes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 符文的类型：在类型层面它们都是“普通值”，编译后才变成 Vue 的 Ref。
+ */
+import type { Ref } from 'vue';
+
+/**
+ * _fromRef 解构时只接受 Ref 属性：编译后每个解构出的变量都按 .value 读写，
+ * 函数等非 Ref 属性会变成 never，提示从原对象单独解构，例如 const { reset } = useX()
+ */
+type UnwrapRefs<T> = { [K in keyof T]: T[K] extends Ref<infer V> ? V : never };
+
+/** 原生输入框绑定的修饰符（可以连写：_bind.lazy.trim）；类型上就是传入的值本身 */
+interface BindModifiers {
+  /** 去掉首尾空白 */
+  readonly trim: BindModifier;
+  /** 转成数字（<input type="number"> 与 type="range" 不用写，自动按数字） */
+  readonly number: BindModifier;
+  /** change 时才同步，而不是每次输入 */
+  readonly lazy: BindModifier;
+}
+
+/** 一个修饰符：_value={_bind.trim(name)}，参数是可写的变量或对象属性 */
+interface BindModifier extends BindModifiers {
+  <T>(target: T): T;
+}
+
+declare global {
+  /**
+   * 响应式状态 → ref，之后像普通变量一样读写。
+   * let 可以整体替换；const 不能整体替换，对象的属性照常可改。
+   * 跨文件共享：`export const settings = _state({...})` 可以直接导出（导出的是 ref 里的对象本身）。
+   */
+  function _state<T>(initial: T): T;
+  /** 没有初始值的响应式状态 → ref()，初始为 undefined */
+  function _state<T>(): T | undefined;
+  namespace _state {
+    /** 只能整体替换的状态 → shallowRef */
+    function raw<T>(initial: T): T;
+    /** 没有初始值、只能整体替换的状态 → shallowRef()：DOM 元素、第三方实例 */
+    function raw<T>(): T | undefined;
+    /** 去掉响应式代理的静态深拷贝，交给 structuredClone、第三方库或日志 */
+    function snapshot<T>(value: T): T;
+  }
+
+  /**
+   * 派生值。const → computed，只读；let → 可以临时覆盖（乐观更新），依赖变化后重新跟随。
+   */
+  function _derived<T>(expression: T): T;
+  namespace _derived {
+    /** 复杂派生：派生逻辑写成函数，其余同 _derived */
+    function by<T>(fn: () => T): T;
+  }
+
+  /**
+   * 副作用（同 Svelte 的 $effect）：挂载后、每次 DOM 更新后执行，读到的响应式变量自动成为依赖。
+   * 返回的函数在下次执行前、销毁时调用。只用于副作用（DOM、订阅、日志）；派生值请用 _derived。
+   * 只想监听指定的值时用 Vue 的 watch(() => x, cb)。
+   */
+  function _effect(fn: () => void | (() => void)): void;
+  namespace _effect {
+    /** DOM 更新前执行，例如自动滚动前先测量 */
+    function pre(fn: () => void | (() => void)): void;
+    /** 不随组件销毁的副作用作用域，返回清理函数；里面可以创建 _effect */
+    function root(fn: () => void | (() => void)): () => void;
+  }
+
+  /**
+   * 组件参数默认值：可双向绑定的 prop，键名以下划线开头、本地变量不带下划线：({ _checked: checked = _bindable(false) })；
+   * 父级传可写的变量或对象属性就双向绑定（_checked={on}），传别的值只是初始值或受控值，都不传就是组件自己的状态
+   */
+  function _bindable<T>(fallback?: T): T;
+
+  /**
+   * 原生输入框绑定的修饰符：<input _value={_bind.trim(name)} />、<input _value={_bind.lazy(note)} />。
+   * 一般的双向绑定不用它：下划线属性的值是可写的变量或对象属性时自动绑定（<Switch _checked={on} />）
+   */
+  const _bind: BindModifiers;
+
+  /**
+   * Ref → 变量：持有外部 Ref（组合式函数、storeToRefs 的返回值），之后像普通变量一样读写，写入直接落到原 Ref。
+   * 与 _toRef 互逆：`let theme = _fromRef(useStorage('theme', 'dark'))`、`const { x, y } = _fromRef(useMouse())`
+   */
+  function _fromRef<T>(source: Ref<T>): T;
+  /** 解构持有对象里的多个 Ref：`const { x, y } = _fromRef(useMouse())`，每个变量读写对应的 Ref */
+  function _fromRef<T extends object>(source: T): UnwrapRefs<T>;
+
+  /**
+   * 变量 → Ref：取回响应式变量背后的 Ref，交给需要可写 Ref 的 API。与 _fromRef 互逆：`useIncrement(_toRef(count))`。
+   * 只读的场合传 getter 就够了：`watch(() => count, …)`
+   */
+  function _toRef<T>(value: T): Ref<T>;
+
+  /**
+   * 只取当前值、不追踪（同 Svelte 的 untrack）：写在 _effect、_derived 里时不会因为它重新执行；
+   * 写在组件函数体里表示有意只要初始值，例如 `let collapsed = _state(_untrack(!open))`，编译器不再警告
+   */
+  function _untrack<T>(value: T): T;
+}
+
+export {};