react-solidlike 2.3.0 → 2.5.0

package/README.zh.md

@@ -0,0 +1,456 @@
+# react-solidlike
+
+[English](./README.md) | 中文
+
+声明式 React 控制流组件库，灵感来源于 Solid.js。用于替代 JSX 中的三元表达式和 `array.map()`，让你的组件代码更加清晰易读。支持 React 和 React Native。
+
+## 安装
+
+```bash
+npm install react-solidlike
+# 或
+bun add react-solidlike
+```
+
+## 组件
+
+### `<Show>` - 条件渲染
+
+替代三元表达式进行条件渲染。
+
+```tsx
+import { Show } from "react-solidlike";
+
+// 基础用法
+<Show when={isLoggedIn}>
+  <UserProfile />
+</Show>
+
+// 带 fallback
+<Show when={isLoggedIn} fallback={<LoginButton />}>
+  <UserProfile />
+</Show>
+
+// 使用 render props 获取类型安全的值
+<Show when={user}>
+  {(user) => <UserProfile name={user.name} />}
+</Show>
+
+// 带 onFallback 回调（用于重定向等副作用）
+<Show when={isAuthenticated} fallback={<Loading />} onFallback={() => navigate('/login')}>
+  <Dashboard />
+</Show>
+```
+
+### `<For>` - 列表渲染
+
+替代 `array.map()` 进行列表渲染。
+
+```tsx
+import { For } from "react-solidlike";
+
+// 基础用法
+<For each={items}>
+  {(item) => <ListItem {...item} />}
+</For>
+
+// 带 keyExtractor
+<For each={users} keyExtractor={(user) => user.id}>
+  {(user) => <UserCard user={user} />}
+</For>
+
+// 带 fallback 处理空数组
+<For each={items} fallback={<EmptyState />}>
+  {(item, index) => <ListItem item={item} index={index} />}
+</For>
+
+// 使用 wrapper 包装元素
+<For each={items} wrapper={<ul className="list" />}>
+  {(item) => <li>{item.name}</li>}
+</For>
+
+// 倒序渲染
+<For each={messages} reverse>
+  {(msg) => <Message {...msg} />}
+</For>
+
+// 使用 array 参数获取上下文信息
+<For each={steps}>
+  {(step, index, array) => (
+    <Step
+      data={step}
+      isFirst={index === 0}
+      isLast={index === array.length - 1}
+    />
+  )}
+</For>
+```
+
+### `<Switch>` / `<Match>` / `<Default>` - 多分支渲染
+
+替代多个 `if-else` 或 `switch` 语句。
+
+```tsx
+import { Switch, Match, Default } from "react-solidlike";
+
+<Switch>
+  <Match when={status === "loading"}>
+    <LoadingSpinner />
+  </Match>
+  <Match when={status === "error"}>
+    <ErrorMessage />
+  </Match>
+  <Match when={status === "success"}>
+    <SuccessContent />
+  </Match>
+  <Default>
+    <IdleState />
+  </Default>
+</Switch>
+```
+
+### `<Await>` - 异步等待
+
+等待 Promise resolve 后渲染内容。
+
+```tsx
+import { Await } from "react-solidlike";
+
+// 基础用法
+<Await promise={fetchUser()} loading={<Spinner />}>
+  {(user) => <UserProfile user={user} />}
+</Await>
+
+// 带错误处理
+<Await
+  promise={fetchData()}
+  loading={<Loading />}
+  error={(err) => <ErrorMessage message={err.message} />}
+>
+  {(data) => <DataView data={data} />}
+</Await>
+
+// 支持非 Promise 值（用于缓存场景）
+<Await promise={cache ?? fetchData()} loading={<Spinner />}>
+  {(data) => <DataView data={data} />}
+</Await>
+```
+
+### `<Repeat>` - 重复渲染
+
+替代 `Array.from({ length: n }).map()`。
+
+```tsx
+import { Repeat } from "react-solidlike";
+
+// 渲染星级评分
+<Repeat times={5}>
+  {(i) => <Star key={i} filled={i < rating} />}
+</Repeat>
+
+// 生成骨架屏占位
+<Repeat times={3}>
+  {(i) => <SkeletonCard key={i} />}
+</Repeat>
+
+// 使用 wrapper 包装元素
+<Repeat times={5} wrapper={<div className="stars" />}>
+  {(i) => <Star key={i} />}
+</Repeat>
+
+// 倒序渲染
+<Repeat times={5} reverse>
+  {(i) => <div key={i}>倒序 {i}</div>}
+</Repeat>
+
+// 使用 length 参数显示进度
+<Repeat times={totalSteps}>
+  {(i, length) => (
+    <Step key={i} current={i + 1} total={length} />
+  )}
+</Repeat>
+```
+
+### `<Split>` - 字符串切割渲染
+
+按分隔符切割字符串并渲染每个部分。
+
+```tsx
+import { Split } from "react-solidlike";
+
+// 基础用法 - 切割后不保留分隔符
+<Split string="a,b,c" separator=",">
+  {(part) => <span>{part}</span>}
+</Split>
+// 渲染: ["a", "b", "c"]
+
+// 保留分隔符
+<Split string="9+5=(9+1)+4" separator="=" keepSeparator>
+  {(part) => <span>{part}</span>}
+</Split>
+// 渲染: ["9+5", "=", "(9+1)+4"]
+
+// 使用正则表达式分隔符
+<Split string="a1b2c3" separator={/\d/} keepSeparator>
+  {(part) => <span>{part}</span>}
+</Split>
+// 渲染: ["a", "1", "b", "2", "c", "3"]
+
+// 带 wrapper 包装元素
+<Split string="hello world" separator=" " wrapper={<div className="words" />}>
+  {(word) => <span>{word}</span>}
+</Split>
+
+// 带 fallback 处理空字符串
+<Split string={text} separator="," fallback={<EmptyState />}>
+  {(part) => <Tag>{part}</Tag>}
+</Split>
+
+// 倒序渲染
+<Split string="a,b,c" separator="," reverse>
+  {(part) => <span>{part}</span>}
+</Split>
+// 渲染顺序: ["c", "b", "a"]
+```
+
+### `<Dynamic>` - 动态组件
+
+根据条件动态选择要渲染的组件类型。
+
+```tsx
+import { Dynamic } from "react-solidlike";
+
+// 动态选择按钮或链接
+<Dynamic
+  component={href ? 'a' : 'button'}
+  href={href}
+  onClick={onClick}
+>
+  {label}
+</Dynamic>
+
+// 配合自定义组件
+<Dynamic
+  component={isAdmin ? AdminPanel : UserPanel}
+  user={currentUser}
+/>
+
+// React Native 中使用
+<Dynamic
+  component={isPressable ? Pressable : View}
+  onPress={handlePress}
+>
+  <Text>Content</Text>
+</Dynamic>
+```
+
+### `<ErrorBoundary>` - 错误边界
+
+捕获子组件树中的 JavaScript 错误，防止整个应用崩溃。
+
+```tsx
+import { ErrorBoundary } from "react-solidlike";
+
+// 基础用法
+<ErrorBoundary fallback={<ErrorPage />}>
+  <App />
+</ErrorBoundary>
+
+// 使用 render props 获取错误信息和重置函数
+<ErrorBoundary
+  fallback={(error, reset) => (
+    <div>
+      <p>Error: {error.message}</p>
+      <button onClick={reset}>Retry</button>
+    </div>
+  )}
+>
+  <App />
+</ErrorBoundary>
+
+// resetKey 变化时自动重置
+<ErrorBoundary fallback={<Error />} resetKey={userId}>
+  <UserProfile />
+</ErrorBoundary>
+```
+
+### `<QueryBoundary>` - 查询边界
+
+处理异步查询的各种状态（加载中、错误、空数据、成功）。可与 `@tanstack/react-query`、SWR、RTK Query 等配合使用。
+
+```tsx
+import { QueryBoundary } from "react-solidlike";
+import { useQuery } from "@tanstack/react-query";
+
+function UserList() {
+  const query = useQuery({ queryKey: ["users"], queryFn: fetchUsers });
+
+  return (
+    <QueryBoundary
+      query={query}
+      loading={<Spinner />}
+      error={<ErrorMessage />}
+      empty={<NoData />}
+    >
+      {(users) => (
+        <ul>
+          {users.map((user) => (
+            <li key={user.id}>{user.name}</li>
+          ))}
+        </ul>
+      )}
+    </QueryBoundary>
+  );
+}
+```
+
+#### Props
+
+| 属性        | 类型                                  | 描述         |
+| ----------- | ------------------------------------- | ------------ |
+| `query`     | `QueryResult<T>`                      | 查询结果对象 |
+| `loading`   | `ReactNode`                           | 加载中显示   |
+| `error`     | `ReactNode`                           | 错误时显示   |
+| `empty`     | `ReactNode`                           | 空数据显示   |
+| `children`  | `ReactNode \| (data: T) => ReactNode` | 成功时渲染   |
+| `isEmptyFn` | `(data: T) => boolean`                | 自定义空判断 |
+
+### `<Once>` - 单次渲染
+
+只渲染一次子元素，忽略后续更新。适用于昂贵的计算或不应重新渲染的内容。
+
+```tsx
+import { Once } from "react-solidlike";
+
+// 渲染昂贵的组件
+<Once>
+  <ExpensiveChart data={data} />
+</Once>
+
+// 防止父组件更新导致的重新渲染
+function Parent() {
+  const [count, setCount] = useState(0);
+  return (
+    <div>
+      <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+      <Once>
+        <Child initialCount={count} />
+      </Once>
+    </div>
+  );
+}
+```
+
+### `<ClientOnly>` - 仅客户端渲染
+
+仅在客户端（hydration 之后）渲染子元素。适用于依赖浏览器 API 或需要避免 SSR hydration 不匹配的场景。
+
+```tsx
+import { ClientOnly } from "react-solidlike";
+
+// 基础用法
+<ClientOnly>
+  <BrowserOnlyComponent />
+</ClientOnly>
+
+// 带 SSR 备选内容
+<ClientOnly fallback={<Skeleton />}>
+  <DynamicChart />
+</ClientOnly>
+
+// 使用渲染函数延迟求值（避免访问 window）
+<ClientOnly fallback={<Loading />}>
+  {() => <ComponentUsingWindow width={window.innerWidth} />}
+</ClientOnly>
+
+// 避免 hydration 不匹配
+<ClientOnly fallback={<span>--:--</span>}>
+  <CurrentTime />
+</ClientOnly>
+```
+
+### `<Timeout>` - 超时渲染
+
+在指定延迟后显示或隐藏内容。适用于自动消失的通知、延迟加载的场景。
+
+```tsx
+import { Timeout } from "react-solidlike";
+
+// 延迟后显示（mode="after"，默认）
+<Timeout ms={1000} mode="after" fallback={<Spinner />}>
+  <DelayedContent />
+</Timeout>
+
+// 延迟后隐藏（mode="before"）
+<Timeout ms={3000} mode="before">
+  <Toast message="操作成功！" />
+</Timeout>
+
+// 自动消失的提示
+<Timeout ms={5000} mode="before" onTimeout={() => console.log("已消失")}>
+  <Notification type="success">保存成功</Notification>
+</Timeout>
+
+// 带加载状态的延迟渲染
+<Timeout ms={2000} mode="after" fallback={<Skeleton />}>
+  <ExpensiveComponent />
+</Timeout>
+```
+
+#### Props
+
+| 属性        | 类型                  | 描述                                                            |
+| ----------- | --------------------- | --------------------------------------------------------------- |
+| `ms`        | `number`              | 延迟时间（毫秒）                                                |
+| `mode`      | `'after' \| 'before'` | `'after'` = 延迟后显示，`'before'` = 延迟后隐藏，默认 `'after'` |
+| `children`  | `ReactNode`           | 要渲染的内容                                                    |
+| `fallback`  | `ReactNode`           | 等待时显示的内容（仅 `after` 模式）                             |
+| `onTimeout` | `() => void`          | 超时发生时的回调                                                |
+
+### `<Visible>` - 可见性渲染（仅 Web）
+
+基于 IntersectionObserver 的可见性渲染，进入视口才渲���。在 React Native 或不支持的环境中会直接渲染 children（优雅降级）。
+
+```tsx
+import { Visible } from "react-solidlike";
+
+// 基础用法 - 进入视口时渲染
+<Visible>
+  <HeavyComponent />
+</Visible>
+
+// 带占位符
+<Visible fallback={<Skeleton />}>
+  <Image src={url} />
+</Visible>
+
+// 提前预加载（rootMargin）
+<Visible rootMargin="200px" fallback={<Placeholder />}>
+  <LazyImage />
+</Visible>
+
+// 切换可见性（once=false 时离开视口会卸载）
+<Visible once={false} onVisibilityChange={(v) => console.log(v)}>
+  <VideoPlayer />
+</Visible>
+```
+
+## 开发
+
+```bash
+# 安装依赖
+bun install
+
+# 运行测试
+bun test
+
+# 代码检查
+bun run lint
+
+# 构建
+bun run build
+```
+
+## License
+
+MIT

package/dist/ClientOnly.d.ts

@@ -0,0 +1,43 @@
+import { type ReactNode } from "react";
+export interface ClientOnlyProps {
+    /** Content to render only on client side | 仅在客户端渲染的内容 */
+    children: ReactNode | (() => ReactNode);
+    /** Fallback content during SSR | SSR 期间渲染的备选内容 */
+    fallback?: ReactNode;
+}
+/**
+ * Component that renders children only on the client side (after hydration)
+ *
+ * 仅在客户端（hydration 之后）渲染子元素的组件
+ *
+ * Useful for components that rely on browser APIs, window object,
+ * or need to avoid SSR hydration mismatches.
+ *
+ * 适用于依赖浏览器 API、window 对象的组件，
+ * 或需要避免 SSR hydration 不匹配的场景。
+ *
+ * @example
+ * // Basic usage | 基础用法
+ * <ClientOnly>
+ *   <BrowserOnlyComponent />
+ * </ClientOnly>
+ *
+ * @example
+ * // With fallback for SSR | 带 SSR 备选内容
+ * <ClientOnly fallback={<Skeleton />}>
+ *   <DynamicChart />
+ * </ClientOnly>
+ *
+ * @example
+ * // Using render function for lazy evaluation | 使用渲染函数延迟求值
+ * <ClientOnly fallback={<Loading />}>
+ *   {() => <ComponentUsingWindow width={window.innerWidth} />}
+ * </ClientOnly>
+ *
+ * @example
+ * // Avoid hydration mismatch | 避免 hydration 不匹配
+ * <ClientOnly fallback={<span>--:--</span>}>
+ *   <CurrentTime />
+ * </ClientOnly>
+ */
+export declare function ClientOnly({ children, fallback }: ClientOnlyProps): ReactNode;

package/dist/Once.d.ts

@@ -0,0 +1,43 @@
+import { type ReactNode } from "react";
+export interface OnceProps {
+    /** Content to render only once | 只渲染一次的内容 */
+    children: ReactNode;
+}
+/**
+ * Component that renders children only once and ignores subsequent updates
+ *
+ * 只渲染一次子元素并忽略后续更新的组件
+ *
+ * Useful for expensive computations or content that should not re-render.
+ * The initial render result is cached and returned on subsequent renders.
+ *
+ * 适用于昂贵的计算或不应重新渲染的内容。
+ * 初始渲染结果会被缓存并在后续渲染时返回。
+ *
+ * @example
+ * // Render expensive component only once | 只渲染一次昂贵的组件
+ * <Once>
+ *   <ExpensiveChart data={data} />
+ * </Once>
+ *
+ * @example
+ * // Static content that shouldn't update | 不应更新的静态内容
+ * <Once>
+ *   <Header title={initialTitle} />
+ * </Once>
+ *
+ * @example
+ * // Prevent re-renders from parent updates | 防止父组件更新导致的重新渲染
+ * function Parent() {
+ *   const [count, setCount] = useState(0);
+ *   return (
+ *     <div>
+ *       <button onClick={() => setCount(c => c + 1)}>Count: {count}</button>
+ *       <Once>
+ *         <Child initialCount={count} />
+ *       </Once>
+ *     </div>
+ *   );
+ * }
+ */
+export declare function Once({ children }: OnceProps): ReactNode;

package/dist/Repeat.d.ts

@@ -1,6 +1,6 @@
-import type { ReactNode } from 'react';
-import { type ForProps } from './For';
-export interface RepeatProps extends Omit<ForProps<number>, 'each'> {
+import type { ReactNode } from "react";
+import { type ForProps } from "./For";
+export interface RepeatProps extends Omit<ForProps<number>, "each"> {
     /** Number of times to repeat | 重复次数 */
     times: number;
 }

package/dist/Show.d.ts

@@ -6,6 +6,8 @@ export interface ShowProps<T> {
     children: ReactNode | ((value: NonNullable<T>) => ReactNode);
     /** Fallback content when condition is falsy | 条件为假时渲染的备选内容 */
     fallback?: ReactNode;
+    /** Callback when condition is falsy (called before rendering fallback) | 条件为假时的回调（在渲染 fallback 之前调用） */
+    onFallback?: () => void;
 }
 /**
  * Conditional rendering component, replaces ternary expressions in JSX
@@ -29,5 +31,11 @@ export interface ShowProps<T> {
  * <Show when={user}>
  *   {(user) => <UserProfile name={user.name} />}
  * </Show>
+ *
+ * @example
+ * // With onFallback callback for side effects | 带 onFallback 回调用于副作用
+ * <Show when={isAuthenticated} fallback={<Loading />} onFallback={() => navigate('/login')}>
+ *   <Dashboard />
+ * </Show>
  */
-export declare function Show<T>({ when, children, fallback }: ShowProps<T>): ReactNode;
+export declare function Show<T>({ when, children, fallback, onFallback }: ShowProps<T>): ReactNode;

package/dist/Split.d.ts

@@ -1,6 +1,6 @@
-import type { ReactNode } from 'react';
-import { type ForProps } from './For';
-export interface SplitProps extends Omit<ForProps<string>, 'each'> {
+import type { ReactNode } from "react";
+import { type ForProps } from "./For";
+export interface SplitProps extends Omit<ForProps<string>, "each"> {
     /** String to split | 要切割的字符串 */
     string: string | null | undefined;
     /** Separator to split by, can be string or RegExp | 分隔符，可以是字符串或正则表达式 */

package/dist/Timeout.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+/** Timeout mode | 超时模式 */
+export type TimeoutMode = "after" | "before";
+export interface TimeoutProps {
+    /** Delay time in milliseconds | 延迟时间（毫秒） */
+    ms: number;
+    /** Content to render | 要渲染的内容 */
+    children: ReactNode;
+    /** Display mode: 'after' = show after delay, 'before' = hide after delay | 显示模式：'after' = 延迟后显示，'before' = 延迟后隐藏 */
+    mode?: TimeoutMode;
+    /** Content to show when hidden (only for 'after' mode) | 隐藏时显示的内容（仅 'after' 模式） */
+    fallback?: ReactNode;
+    /** Callback when timeout occurs | 超时发生时的回调 */
+    onTimeout?: () => void;
+}
+/**
+ * Timeout component, shows or hides content after a specified delay
+ *
+ * 超时组件，在指定延迟后显示或隐藏内容
+ *
+ * @example
+ * // Show content after delay (fade-in effect) | 延迟后显示内容（淡入效果）
+ * <Timeout ms={1000} mode="after">
+ *   <DelayedMessage />
+ * </Timeout>
+ *
+ * @example
+ * // Hide content after delay (auto-dismiss) | 延迟后隐藏内容（自动消失）
+ * <Timeout ms={3000} mode="before">
+ *   <Toast message="Saved successfully!" />
+ * </Timeout>
+ *
+ * @example
+ * // With fallback while waiting | 等待时显示 fallback
+ * <Timeout ms={2000} mode="after" fallback={<Spinner />}>
+ *   <SlowComponent />
+ * </Timeout>
+ *
+ * @example
+ * // With onTimeout callback | 带超时回调
+ * <Timeout ms={5000} mode="before" onTimeout={() => console.log("Dismissed")}>
+ *   <Notification />
+ * </Timeout>
+ */
+export declare function Timeout({ ms, children, mode, fallback, onTimeout }: TimeoutProps): ReactNode;

package/dist/Visible.d.ts

@@ -0,0 +1,51 @@
+import { type ReactNode } from "react";
+export interface VisibleProps {
+    /** Content to render when visible | 可见时渲染的内容 */
+    children: ReactNode;
+    /** Fallback content before entering viewport | 进入视口前渲染的备选内容 */
+    fallback?: ReactNode;
+    /** Root margin for intersection observer (e.g., "100px") | 交叉观察器的根边距 */
+    rootMargin?: string;
+    /** Visibility threshold (0-1) | 可见性阈值 */
+    threshold?: number | number[];
+    /** Keep rendered after first visible (default: true) | 首次可见后保持渲染 */
+    once?: boolean;
+    /** Callback when visibility changes | 可见性变化时的回调 */
+    onVisibilityChange?: (isVisible: boolean) => void;
+}
+/**
+ * Visibility-based rendering component using IntersectionObserver (Web only)
+ *
+ * 基于可见性的渲染组件，使用 IntersectionObserver（仅 Web）
+ *
+ * In React Native or environments without IntersectionObserver,
+ * children will be rendered directly (graceful degradation).
+ *
+ * 在 React Native 或不支持 IntersectionObserver 的环境中，
+ * 会直接渲染 children（优雅降级）。
+ *
+ * @example
+ * // Basic usage - render when entering viewport | 基础用法 - 进入视口时渲染
+ * <Visible>
+ *   <HeavyComponent />
+ * </Visible>
+ *
+ * @example
+ * // With fallback placeholder | 带占位符
+ * <Visible fallback={<Skeleton />}>
+ *   <Image src={url} />
+ * </Visible>
+ *
+ * @example
+ * // Preload before entering viewport | 提前预加载
+ * <Visible rootMargin="200px" fallback={<Placeholder />}>
+ *   <LazyImage />
+ * </Visible>
+ *
+ * @example
+ * // Toggle visibility (once=false) | 切换可见性
+ * <Visible once={false} onVisibilityChange={(v) => console.log(v)}>
+ *   <VideoPlayer />
+ * </Visible>
+ */
+export declare function Visible({ children, fallback, rootMargin, threshold, once, onVisibilityChange, }: VisibleProps): ReactNode;

package/dist/index.d.ts

@@ -6,4 +6,6 @@ export { QueryBoundary, type QueryBoundaryProps, type QueryResult } from "./Quer
 export { Repeat, type RepeatProps } from "./Repeat";
 export { Show, type ShowProps } from "./Show";
 export { Split, type SplitProps } from "./Split";
-export { Default, type DefaultProps, Match, type MatchProps, Switch, type SwitchProps } from "./Switch";
+export { Default, type DefaultProps, Match, type MatchProps, Switch, type SwitchProps, } from "./Switch";
+export { Timeout, type TimeoutProps } from "./Timeout";
+export { Visible, type VisibleProps } from "./Visible";