From da8e866a2b96d68c268e4c85979ce1830106eaac Mon Sep 17 00:00:00 2001
From: maofeng <hupeh@qq.com>
Date: Thu, 19 Jun 2025 22:40:14 +0800
Subject: [PATCH] =?UTF-8?q?=E9=87=8D=E6=96=B0=E8=AE=BE=E8=AE=A1=E8=AE=B0?=
 =?UTF-8?q?=E5=BD=95=E4=B8=8A=E4=B8=8B=E6=96=87?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/core/record.tsx | 298 +++++++++++++++++++++++++++++++++++++-------
 1 file changed, 252 insertions(+), 46 deletions(-)

diff --git a/src/core/record.tsx b/src/core/record.tsx
index 91d4574..de25cbc 100644
--- a/src/core/record.tsx
+++ b/src/core/record.tsx
@@ -1,4 +1,5 @@
-import { createContext, useContext, useMemo } from "react";
+import { createContext, type ReactNode, useContext, useMemo } from "react";
+import { type Validator } from "./types";
 
 /**
  * 定义上下文记录结构
@@ -12,19 +13,163 @@ export type RecordContextValue<T extends object = object> = {
 /**
  * 声明通用的记录上下文，配合下面 Component 和 hook 管理数据:
  *
- * - RecordProvider 数据提供组件
- * - useRecord  根据位置获取最近的数据
- * - useNamedRecord 获取指定名称的数据
+ * - RecordContextProvider 数据提供组件
+ * - useRecordContext  根据位置获取最近的数据
+ *
+ * @internal
  */
 const RecordContext = createContext<RecordContextValue | null>(null);
 
-type RecordProviderProps<T extends object> = {
-  children: React.ReactNode;
+/**
+ * 获取最近的一个记录值
+ *
+ * @example
+ *
+ * 获取最近的记录值
+ *
+ * ```jsx
+ * <RecordContextProvider name="..." value={{ name: 'John', age: 30 }}>
+ *   {useRecordContext().name}
+ * </RecordContextProvider>
+ * ```
+ *
+ * @example
+ *
+ * 获取最近的记录值并验证
+ *
+ * ```jsx
+ * <RecordContextProvider name="..." value={{ name: 'John', age: 30 }}>
+ *   <RecordContextProvider name="..." value={{ email: 'Jane@example.com', phone: '1234567890' }}>
+ *     {useRecordContext((value) => 'email' in value).phone}
+ *   </RecordContextProvider>
+ * </RecordContextProvider>
+ * ```
+ *
+ * @example
+ *
+ * 根据名称获取记录值
+ *
+ * ```jsx
+ * <RecordContextProvider name="user.2" value={{ id: 2, name: 'John', age: 30 }}>
+ *   {useRecordContext('user.2').name}
+ * </RecordContextProvider>
+ * ```
+ */
+export function useRecordContext<T extends object = object>(): T | null;
+export function useRecordContext<T extends object = object>(name: string): T | null;
+export function useRecordContext<T extends object = object>(validator: Validator<object>): T | null;
+export function useRecordContext<T extends object = object>(name: string, validator: Validator<object>): T | null;
+export function useRecordContext<T extends object = object>(...args: unknown[]): T | null {
+  let name: string | undefined;
+  let validator: Validator<object> | undefined;
+
+  if (typeof args[0] === 'string') {
+    name = args[0];
+    if (typeof args[1] === 'function') {
+      validator = args[1] as Validator<object>;
+    }
+  } else if (typeof args[0] === 'function') {
+    validator = args[0] as Validator<object>;
+  }
+
+  let context = useContext(RecordContext);
+
+  if (!context) {
+    throw new Error("useRecordContext must be used within RecordContextProvider");
+  }
+
+  if (validator == null && name == null) {
+    return context.value as T;
+  }
+
+  return resolveRecord(context, c => {
+    return (name == null || c.name === name)
+      && (validator == null || validator(c.value));
+  })
+}
+
+function resolveRecord<T extends object = object>(
+  context: RecordContextValue,
+  validate: (ctx: RecordContextValue) => boolean,
+): T | null {
+  while (true) {
+    if (validate(context)) {
+      return context.value as T;
+    }
+    if (!context.parent) {
+      return null;
+    }
+    context = context.parent;
+  }
+}
+
+/**
+ * 记录值提供者属性
+ */
+export interface RecordProviderProps<T extends object> {
+  /**
+   * 子组件
+   *
+   * 必须提供一个值，否则毫无意义。
+   */
+  children: ReactNode;
+
+  /**
+   * 记录名称
+   *
+   * 配合 useRecordContext 获取指定名称的数据。
+   *
+   * @example
+   *
+   * ```jsx
+   * function UserName({ id }: { id: number }) {
+   *   const user = useRecordContext<User>(`user.${id}`);
+   *   return <div>{user.name}</div>
+   * }
+   *
+   * <RecordContextProvider name="user.1" value={{ id: 1, name: "John" }}>
+   *   <RecordContextProvider name="user.2" value={{ id: 2, name: "Jane" }}>
+   *     <p>
+   *       user name for id equal 2 is
+   *       <UserName id={2} />
+   *     </p>
+   *     <p>
+   *       user name for id equal 1 is
+   *       <UserName id={1} />
+   *     </p>
+   *   </RecordContextProvider>
+   * </RecordContextProvider>
+   * ```
+   */
   name: string;
+
+  /**
+   * 记录值
+   */
   value: T;
 };
 
-export function RecordProvider<T extends object>({
+/**
+ * 通过上下文实现跨组件传递记录值
+ *
+ * @example
+ *
+ * ```jsx
+ * <RecordContextProvider name="user.1" value={{ id: 1, name: "John" }}>
+ *   <RecordContextProvider name="user.2" value={{ id: 2, name: "Jane" }}>
+ *     <p>
+ *       user name for id equal 2 is
+ *       <UserName id={2} />
+ *     </p>
+ *     <p>
+ *       user name for id equal 1 is
+ *       <UserName id={1} />
+ *     </p>
+ *   </RecordContextProvider>
+ * </RecordContextProvider>
+ * ```
+ */
+export function RecordContextProvider<T extends object>({
   children,
   ...context
 }: RecordProviderProps<T>) {
@@ -36,48 +181,109 @@ export function RecordProvider<T extends object>({
     Object.values(context),
   ) as RecordContextValue;
 
-  return <RecordContext value={value}>{children}</RecordContext>;
+  return (
+    <RecordContext value={value}>
+      {children}
+    </RecordContext>
+  );
 }
 
-export function useRecord<T extends object = object>(
-  validate?: (value: unknown) => boolean,
-): T | null {
-  let context = useContext(RecordContext);
-  if (!context) {
-    throw new Error("useRecord must be used within RecordProvider");
-  }
-  if (validate == null) {
-    return context.value as T;
-  }
-  while (true) {
-    if (validate(context.value)) {
-      return context.value as T;
-    }
-    if (!context.parent) {
-      return null;
-    }
-    context = context.parent;
+/**
+ * 可选记录提供器
+ *
+ * 只有在定义了记录值的情况下，才用 RecordContextProvider 子元素，
+ * 即允许组件在记录上下文之外正常运行。
+ *
+ * @example
+ *
+ * ```jsx
+ * const RecordTitle = ({ record }) => (
+ *   <OptionalRecordProvider name="post.1" value={record}>
+ *     <TextField source="title" />
+ *   </OptionalRecordProvider>
+ * );
+ * ```
+ */
+export function OptionalRecordProvider<T extends object>({
+  children,
+  name,
+  value,
+}: Omit<RecordProviderProps<T>, 'value'> & {
+  value?: T | null | undefined;
+}) {
+  if (value != null) {
+    return (
+      <RecordContextProvider
+        name={name}
+        value={value}
+      >
+        {children}
+      </RecordContextProvider>
+    );
   }
+
+  return children;
 }
 
-export function useNamedRecord<T extends object = object>(
-  name: string,
-  validate?: (value: unknown) => boolean,
-): T | null {
-  let context = useContext(RecordContext);
-  if (!context) {
-    throw new Error("useNamedRecord must be used within RecordProvider");
-  }
-  while (true) {
-    if (context!.name === name) {
-      if (validate && !validate(context.value)) {
-        throw new Error("Invalid record value");
-      }
-      return context!.value as T;
-    }
-    if (!context.parent) {
-      return null;
-    }
-    context = context!.parent;
-  }
+export interface WithRecordProps<T extends object = object> {
+  /**
+   * 指定要查询的记录名称
+   *
+   * @type {string} 可选
+   */
+  name?: string;
+
+  /**
+   * 当记录存在时的渲染函数
+   *
+   * @param {T} record 找到的记录值
+   * @returns {ReactNode}
+   */
+  render: (record: T) => ReactNode;
+
+  /**
+   * 记录不存在或上下文不存在时渲染
+   *
+   * @param {boolean} hasContext 是否存在记录上下文
+   * @returns {ReactNode}
+   */
+  fallback?: ReactNode | ((hasContext: boolean) => ReactNode);
+}
+
+/**
+ * 查询并渲染记录
+ *
+ * 内部自动使用 useRecordContext 的来完成记录查询，
+ * 实现快速渲染记录。
+ *
+ * @example
+ *
+ * ```jsx
+ * const BookShow = () => (
+ *    <Show>
+ *       <SimpleShowLayout>
+ *          <WithRecord render={record => <span>{record.title}</span>} />
+ *      </SimpleShowLayout>
+ *   </Show>
+ * );
+ * ```
+ */
+export function WithRecord<T extends object = object>({
+  name,
+  render,
+  fallback,
+}: WithRecordProps<T>) {
+  const context = useContext(RecordContext);
+  const record = context != null
+    ? resolveRecord<T>(context, c => name == null || c.name == name)
+    : null;
+
+  if (record == null) {
+    if (typeof fallback === 'function') {
+      return fallback(context != null);
+    }
+    return fallback ?? null;
+  }
+
+  return <>{render(record)}</>
 }