annil 1.0.0

package/src/api/DefineComponent/NameOrPage/NameOrPathOption.ts

@@ -0,0 +1,24 @@
+import type { IfExtends } from "hry-types/src/Any/IfExtends";
+import type { RootComponentDoc } from "../../RootComponent/RootComponentDoc";
+
+/**
+ * 根据TRootComponent类型,生成name或path字段
+ * @remarks RootComponentDoc为页面时(isPage为true),返回path字段,否则返回name字段
+ * @returns  `{ name: TName } or { path: TPage }`
+ */
+export type NameOrPageOption<
+  TName extends string,
+  TPath extends `/${string}`,
+  TRootComponent extends RootComponentDoc,
+> = TRootComponent["isPage"] extends true ? {
+    /**
+     * 页面路径已'/'开头
+     */
+    path: TPath;
+  }
+  : {
+    /**
+     * 组件名不可为空
+     */
+    name: TName & IfExtends<TName, "", () => "⚠️组件名不可为空⚠️", unknown>;
+  };

package/src/api/DefineComponent/NameOrPage/test/error.test.ts

@@ -0,0 +1,26 @@
+import type { RootComponentDoc } from "../../../RootComponent/RootComponentDoc";
+import { DefineComponent } from "../..";
+
+DefineComponent({
+  // @ts-expect-error RootComponentDoc中isPage为true时 应该书写page字段
+  name: "test",
+  rootComponent: { isPage: true } satisfies RootComponentDoc,
+});
+
+DefineComponent({
+  // @ts-expect-error RootComponentDoc中isPage不为true时 应该书写name字段
+  path: "/pages/index/index",
+  rootComponent: {} satisfies RootComponentDoc,
+});
+
+DefineComponent({
+  // @ts-expect-error 页面路径已'/'开头
+  path: "pages/index/index",
+  rootComponent: { isPage: true } satisfies RootComponentDoc,
+});
+
+DefineComponent({
+  // @ts-expect-error 组件名不可为空
+  name: "",
+  rootComponent: {} satisfies RootComponentDoc,
+});

package/src/api/DefineComponent/NameOrPage/test/normal.test.ts

@@ -0,0 +1,13 @@
+import { DefineComponent } from "../..";
+
+//  RootComponentDoc的isPage类型为true时,必写path字段.
+DefineComponent({
+  path: "/pages/index/index",
+  rootComponent: { isPage: true },
+});
+
+//  RootComponentDoc的isPage类型不为true时,必写name字段.
+DefineComponent({
+  name: "test",
+  rootComponent: {},
+});

package/src/api/DefineComponent/ReturnType/ComponentDoc.ts

@@ -0,0 +1,25 @@
+type PrefixKeys = `${string}_${string}`;
+
+type _ComponentDoc = {
+  properties?: Record<PrefixKeys, any>;
+  customEvents?: Record<PrefixKeys, any>;
+};
+
+type Error = "{ properties?: Record<PrefixKeys, any>; customEvents?: Record<PrefixKeys, any>;}";
+
+type _Validator<O> = keyof O extends keyof _ComponentDoc
+  // @ts-ignore 要求ComponentDoc有前缀
+  ? keyof (O["properties"] & O["customEvents"]) extends PrefixKeys ? _ComponentDoc
+  : Error
+  : Error;
+
+/**
+ * RootComponent Api 返回的类型
+ * ```ts
+ * RootComponentDoc = {
+ * properties?: Record<PrefixKeys, any>;
+ * customEvents?: Record<PrefixKeys, any>;
+ * };
+ * ```
+ */
+export type ComponentDoc<O extends _Validator<O> = _ComponentDoc> = O;

package/src/api/DefineComponent/ReturnType/CreateComponentDoc.ts

@@ -0,0 +1,46 @@
+import type { IfExtends } from "hry-types/src/Any/IfExtends";
+import type { ComputeIntersectionDeep } from "hry-types/src/Object/ComputeIntersectionDeep";
+import type { AddNullForObject } from "../../../types/AddNullForObject";
+import type { RootComponentDoc } from "../../RootComponent/RootComponentDoc";
+import type { SubComponentDoc } from "../../SubComponent/SubComponentDoc";
+import type { GetCustomEventDocOfSubDoc } from "./GetCustomEventDocOfSubDoc";
+
+// 获取RootComponetDoc中events字段类型阻止事件(后最为catch)的key `${ 组件前缀 }_${infer Key}_${ bubbles | capture }_catch`
+type GetStopKeys<O> = { [k in keyof O]: k extends `${string}_${infer Key}_${string}_catch` ? Key : never }[keyof O];
+
+export type CreateComponentDoc<
+  TRootDoc extends RootComponentDoc,
+  TName extends string,
+  TSubComponentTuple extends SubComponentDoc[],
+  // 获取RootDoc和SubComponent[]中所有的properties字段类型
+  AllPropertiesDoc extends unknown | object = TRootDoc["properties"],
+  AllCustomEventsDoc extends unknown | object =
+    & TRootDoc["customEvents"]
+    & GetCustomEventDocOfSubDoc<TSubComponentTuple[number]>,
+  StopKeys extends string = GetStopKeys<TRootDoc["events"]>,
+  FinalCustomEventDoc extends object = Omit<AllCustomEventsDoc, StopKeys>,
+> = ComputeIntersectionDeep<
+  & IfExtends<
+    unknown,
+    AllPropertiesDoc,
+    {},
+    {
+      properties: {
+        // AddNullForObject 为了给子组件传值时,可以让异步对象数据初始值为null。
+        [k in keyof AllPropertiesDoc as `${TName}_${k & string}`]: AddNullForObject<
+          AllPropertiesDoc[k]
+        >;
+      };
+    }
+  >
+  & IfExtends<
+    {},
+    FinalCustomEventDoc,
+    {},
+    {
+      customEvents: {
+        [k in keyof FinalCustomEventDoc as `${TName}_${k & string}`]: FinalCustomEventDoc[k];
+      };
+    }
+  >
+>;

package/src/api/DefineComponent/ReturnType/CreatePageDoc.ts

@@ -0,0 +1,26 @@
+import type { IfExtends } from "hry-types/src/Any/IfExtends";
+import type { ComputeIntersectionDeep } from "hry-types/src/Object/ComputeIntersectionDeep";
+import type { RemoveNullOfRequired } from "../../../types/RemoveNullOfRequired";
+import type { RootComponentDoc } from "../../RootComponent/RootComponentDoc";
+import type { SubComponentDoc } from "../../SubComponent/SubComponentDoc";
+import type { GetPropertiesDocOfSubDoc } from "./GetPropertiesDocOfSubDoc";
+
+export type CreatePageDoc<
+  TRootDoc extends RootComponentDoc,
+  TPath extends string,
+  TSubComponentTuple extends SubComponentDoc[],
+  // 获取所有properties字段
+  AllPropertiesDoc = TRootDoc["properties"] & GetPropertiesDocOfSubDoc<TSubComponentTuple>,
+> = ComputeIntersectionDeep<
+  & { path: TPath }
+  & IfExtends<
+    unknown,
+    AllPropertiesDoc,
+    unknown,
+    {
+      // @ts-ignore AllPropertiesDoc 必为 object
+      //  RemoveNullOfRequired 页面传值时必传字段不需要RootComponent返回时为对象加入的null类型
+      properties: RemoveNullOfRequired<AllPropertiesDoc>;
+    }
+  >
+>;

package/src/api/DefineComponent/ReturnType/GetCustomEventDocOfSubDoc.ts

@@ -0,0 +1,20 @@
+import type { IsNever, IsUnion } from "hry-types/src/Any/_api";
+import type { UnionTwoObject } from "hry-types/src/Object/UnionTwoObject";
+import type { Last } from "hry-types/src/Union/Last";
+import type { SubComponentDoc } from "../../SubComponent/SubComponentDoc";
+
+/**
+ * 因为子组件文档customEvents字段有可能相同(无前缀),所以使用UnionTwoObject
+ * 由于SubComponentDoc为空时返回never而不`{}`,所以`Exclude<U, TLast>`不影响结果。
+ */
+type _GetCustomEventDocOfSubDoc<U extends SubComponentDoc, Result = {}, TLast = Last<U>> = IsNever<U> extends true
+  ? Result
+  : _GetCustomEventDocOfSubDoc<Exclude<U, TLast>, UnionTwoObject<Result, TLast>>;
+
+/**
+ * 获取子组件自定义事件文档
+ * @remarks U 中 相同字段类型联合,所以使用元组推导不如Last性能好。
+ */
+export type GetCustomEventDocOfSubDoc<UnionSubDoc extends SubComponentDoc> = IsUnion<UnionSubDoc> extends true
+  ? _GetCustomEventDocOfSubDoc<UnionSubDoc>
+  : UnionSubDoc;

package/src/api/DefineComponent/ReturnType/GetPropertiesDocOfSubDoc.ts

@@ -0,0 +1,7 @@
+import type { SubComponentDoc } from "../../SubComponent/SubComponentDoc";
+
+// 获取元组中所有SubComponentDoc的properties字段类型。这里忽略相同key的情况,结果为各个properties对象交叉类型。因为DefinComopnent API 在获取 SubComponentDoc字段类型时做了相同字段类型报错。
+export type GetPropertiesDocOfSubDoc<Tuple extends SubComponentDoc[], Result = unknown> = Tuple extends
+  [infer Head extends SubComponentDoc, ...infer Rest extends SubComponentDoc[]]
+  ? GetPropertiesDocOfSubDoc<Rest, Result & Head["properties"]>
+  : Result;

package/src/api/DefineComponent/ReturnType/PageDoc.ts

@@ -0,0 +1,19 @@
+type _PageDoc = {
+  path: `/${string}`;
+  properties?: object;
+};
+
+type Error = "{ path: `/${string}`; properties?: object;}";
+
+type _Validator<O> = keyof O extends keyof _PageDoc ? _PageDoc : Error;
+
+/**
+ * 页面文档类型
+ * ```ts
+ * PageDoc = {
+ *   path: `/${string}`;
+ *   properties?: object;
+ * };
+ * ```
+ */
+export type PageDoc<O extends _Validator<O> = _PageDoc> = O;

package/src/api/DefineComponent/ReturnType/test/normalComponentDoc.test.ts

@@ -0,0 +1,226 @@
+import { Checking, type Test } from "hry-types";
+import { type ComputeIntersectionDeep } from "hry-types/src/Object/ComputeIntersectionDeep";
+import { RootComponent, type SpecificType } from "../../../..";
+import type { CustomEventConstraint } from "../../../RootComponent/CustomEvents/CustomEventConstraint";
+import type {
+  Bubbles,
+  BubblesCapture,
+  BubblesCaptureComposed,
+  BubblesComposed,
+  Capture,
+  CaptureComposed,
+  Composed,
+} from "../../../RootComponent/CustomEvents/CustomEventsTag";
+import type { Mock_User } from "../../../RootComponent/Properties/expected/normalRequired";
+import type { PropertiesConstraint } from "../../../RootComponent/Properties/PropertiesConstraint";
+import type { RootComponentDoc } from "../../../RootComponent/RootComponentDoc";
+import type { SubComponentDoc } from "../../../SubComponent/SubComponentDoc";
+import { DefineComponent } from "../..";
+
+const properties = {
+  str: String,
+  obj: Object as SpecificType<Mock_User>,
+  optionalObj: {
+    type: Object as SpecificType<Mock_User>,
+    value: {} as Mock_User,
+  },
+  optionalObjOrNull: {
+    type: Object as SpecificType<Mock_User | null>,
+    value: null,
+  },
+} satisfies PropertiesConstraint;
+const customEvents = {
+  str: String,
+  null: null,
+  unionStr: String as SpecificType<"male" | "female">,
+  list: [String, Number as SpecificType<0 | 1 | 2>, null],
+  bubbles: {
+    detailType: String,
+    options: { bubbles: true },
+  },
+  capturePhase: {
+    detailType: null,
+    options: { capturePhase: true },
+  },
+  bubbles_capturePhase: {
+    detailType: [String, Number],
+    options: { bubbles: true, capturePhase: true },
+  },
+  bubbles_composed: {
+    detailType: String as SpecificType<"male" | "female">,
+    options: { bubbles: true, composed: true },
+  },
+  capturePhase_composed: {
+    detailType: [String, Number as SpecificType<0 | 1 | 2>, null],
+    options: { capturePhase: true, composed: true },
+  },
+  bubbles_capturePhase_composed: {
+    detailType: Boolean,
+    options: { bubbles: true, capturePhase: true, composed: true },
+  },
+} satisfies CustomEventConstraint;
+// 只有Properties字段
+const OnlyPropsRootDoc = RootComponent()({
+  properties,
+});
+
+const onlyProperties = DefineComponent({
+  name: "test",
+  rootComponent: OnlyPropsRootDoc,
+});
+
+// 可传对象字段加入null,(rootDoc中必传对象加入null了)
+type OnlyPropertiesExpected = {
+  properties: {
+    test_optionalObj?: Mock_User | null; // 多了null
+    test_optionalObjOrNull?: Mock_User | null;
+    test_str: string;
+    test_obj: Mock_User | null;
+  };
+};
+
+Checking<typeof onlyProperties, OnlyPropertiesExpected, Test.Pass>;
+
+// 只有customEvents字段
+const OnlyCustomEventsRootDoc = RootComponent()({
+  customEvents,
+});
+
+const compOnlyCustomEvents = DefineComponent({
+  name: "test",
+  rootComponent: OnlyCustomEventsRootDoc,
+});
+
+type CompOnlyCustomEventsExpected = {
+  customEvents: {
+    test_str: string;
+    test_null: null;
+    test_unionStr: "male" | "female";
+    test_list: string | 0 | 1 | 2 | null;
+    test_bubbles: string | Bubbles;
+    test_capturePhase: Capture | null;
+    test_bubbles_capturePhase: string | number | BubblesCapture;
+    test_bubbles_composed: "male" | "female" | BubblesComposed;
+    test_capturePhase_composed: string | 0 | 1 | 2 | CaptureComposed | null;
+    test_bubbles_capturePhase_composed: boolean | BubblesCaptureComposed;
+  };
+};
+
+Checking<typeof compOnlyCustomEvents, CompOnlyCustomEventsExpected, Test.Pass>;
+
+// 都有
+const rootComponent = RootComponent()({
+  properties,
+  customEvents,
+});
+
+const compDoc = DefineComponent({
+  name: "test",
+  rootComponent,
+});
+
+Checking<typeof compDoc, ComputeIntersectionDeep<CompOnlyCustomEventsExpected & OnlyPropertiesExpected>, Test.Pass>;
+
+// rootComponent字段和SubComponents字段同时具有properties字段时
+// const A = {} as { properties: { str: string; obj: { age: number } } };
+
+// const B = {} as { properties: { num: number } };
+
+// const C = {} as { properties: { bool: boolean } };
+
+// const CompDoc = DefineComponent({
+//   name: "test",
+//   subComponents: [A, B, C],
+// });
+
+// // 因为子组件中properties不存在相同key,所以返回类型是交叉的。
+// type CompDocExpect = ComputeIntersectionDeep<
+//   {
+//     properties: {
+//       test_str: string;
+//       test_obj: {
+//         age: number;
+//       } | null;
+//       test_num: number;
+//       test_bool: boolean;
+//     };
+//   }
+// >;
+
+// Checking<typeof CompDoc, CompDocExpect, Test.Pass>;
+
+type D = SubComponentDoc<{
+  str: string | Bubbles | Composed;
+  num: number | Capture | Composed;
+  null: null | Bubbles | Capture | Composed;
+}>;
+
+const customEventsRootDoc = DefineComponent({
+  name: "test",
+  subComponents: [{} as D],
+});
+
+// 预期添加组件名做为前缀
+type customEventsRootDocExpect = {
+  customEvents: {
+    test_str: string | Bubbles | Composed;
+    test_num: number | Capture | Composed;
+    test_null: null | Bubbles | Capture | Composed;
+  };
+};
+
+Checking<typeof customEventsRootDoc, customEventsRootDocExpect, Test.Pass>;
+
+type E = SubComponentDoc<{
+  str: number | Bubbles | Composed;
+  num: string | Capture | Composed;
+  null: boolean | Bubbles | Capture | Composed;
+}>;
+
+// 子组件有相同自定义字段时
+const WhenSameKeyOfCustomEventsRootDoc = DefineComponent({
+  name: "test",
+  subComponents: [{} as D, {} as E],
+});
+
+// customEvents相同key类型联合
+type WhenSameKeyOfCustomEventsRootDocExpect = {
+  customEvents: {
+    test_str: string | number | Bubbles | Composed;
+    test_num: string | number | Capture | Composed;
+    test_null: boolean | Bubbles | Capture | Composed | null;
+  };
+};
+
+Checking<typeof WhenSameKeyOfCustomEventsRootDoc, WhenSameKeyOfCustomEventsRootDocExpect, Test.Pass>;
+
+type RootDocCatch = RootComponentDoc<{
+  events: {
+    aaa_str_bubbles_catch: () => void;
+  };
+}>;
+
+// 根组件有阻止(catch)子组件事件时
+const whenRootDocCatch = DefineComponent({
+  name: "test",
+  rootComponent: {} as RootDocCatch,
+  subComponents: [{} as D],
+});
+
+type whenRootDocCatchExpect = {
+  customEvents: {
+    test_num: number | Composed | Capture;
+    test_null: Bubbles | Composed | Capture | null;
+  };
+};
+
+Checking<typeof whenRootDocCatch, whenRootDocCatchExpect, Test.Pass>;
+
+// ComponetDoc可能返回类型为{}
+const ComponetDoc = DefineComponent({
+  name: "test",
+  rootComponent: {},
+  subComponents: [],
+});
+
+Checking<typeof ComponetDoc, {}, Test.Pass>;

package/src/api/DefineComponent/ReturnType/test/normalPageDoc.test.ts

@@ -0,0 +1,39 @@
+import { Checking, type Test } from "hry-types";
+import { RootComponent, type SpecificType } from "../../../..";
+import type { Mock_User } from "../../../RootComponent/Properties/expected/normalRequired";
+import { DefineComponent } from "../..";
+
+const OnlyPropsRootDoc = RootComponent()({
+  isPage: true,
+  properties: {
+    str: String,
+    obj: Object as SpecificType<Mock_User>,
+    optionalObj: {
+      type: Object as SpecificType<Mock_User>,
+      value: {} as Mock_User,
+    },
+    optionalObjOrNull: {
+      type: Object as SpecificType<Mock_User | null>,
+      value: null,
+    },
+  },
+  customEvents: {}, // EmptyObject
+});
+
+const compDocOnlyProperties = DefineComponent({
+  path: "/pages/index/index",
+  rootComponent: OnlyPropsRootDoc,
+});
+
+// 页面时返回的propertiesDoc无前缀
+type CompDocOnlyPropertiesExpected = {
+  path: "/pages/index/index";
+  properties: {
+    optionalObj?: Mock_User;
+    optionalObjOrNull?: Mock_User | null;
+    str: string;
+    obj: Mock_User;
+  };
+};
+
+Checking<typeof compDocOnlyProperties, CompDocOnlyPropertiesExpected, Test.Pass>;

package/src/api/DefineComponent/RootComponent/RootComponentOption.ts

@@ -0,0 +1,8 @@
+import type { RootComponentDoc } from "../../RootComponent/RootComponentDoc";
+
+/**
+ * DefineComponent API`rootComponent`字段配置
+ */
+export type RootComponentOption<TRootComponent extends RootComponentDoc> = {
+  rootComponent?: TRootComponent;
+};

package/src/api/DefineComponent/SubComponents/SubComponentsOption.ts

@@ -0,0 +1,24 @@
+// import type { Extends } from "hry-types/src/Any/Extends";
+// import type { IfExtends } from "hry-types/src/Any/IfExtends";
+// import type { GetPropertiesDuplicatedKeys } from "../../../types/GetPropertiesDuplicatedKeys";
+// import type { Shift } from "../../../types/Shift";
+// import type { UnionToComma } from "../../../types/UnionToComma.test";
+import type { SubComponentDoc } from "../../SubComponent/SubComponentDoc";
+
+/**
+ * RootComponent API 的`subComponents`字段配置
+ */
+export type SubComponentsOption<
+  TSubComponentTuple extends SubComponentDoc[],
+> // // 子组件中properties字段重复的key,用做验证(报错)
+ = // PropertiesDuplicatedKeys extends string = Extends<TSubComponentTuple["length"], 0 | 1> extends true ? never
+  //   : GetPropertiesDuplicatedKeys<Shift<TSubComponentTuple>, keyof TSubComponentTuple[0]["properties"]>,
+  {
+    subComponents?: [...TSubComponentTuple];
+    // & IfExtends<
+    //   PropertiesDuplicatedKeys,
+    //   never,
+    //   unknown,
+    //   `⚠️重复的字段:${UnionToComma<PropertiesDuplicatedKeys>}⚠️`
+    // >;
+  };

package/src/api/DefineComponent/SubComponents/test/error.test.ts

@@ -0,0 +1,14 @@
+// import type { SubComponentDoc } from "../../../SubComponent/SubComponentDoc";
+// import { DefineComponent } from "../..";
+
+// const B = { properties: { aaa: 456 } } satisfies SubComponentDoc;
+// const C = { properties: { aaa: 456 } } satisfies SubComponentDoc;
+// const D = { properties: { bbb: 456 } } satisfies SubComponentDoc;
+// const E = { properties: { bbb: 456 } } satisfies SubComponentDoc;
+// const A = { properties: { ccc: 123 } } satisfies SubComponentDoc;
+
+// DefineComponent({
+//   name: "test",
+//   // @ts-expect-error 重复的properties字段  aaa 、 bbb
+//   subComponents: [A, B, C, D, E],
+// });