xxf_react 0.3.6 → 0.3.7

package/dist/foundation/LayoutSize.d.ts

@@ -0,0 +1,5 @@
+export interface LayoutSize {
+    width: number;
+    height: number;
+}
+//# sourceMappingURL=LayoutSize.d.ts.map

package/dist/foundation/LayoutSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LayoutSize.d.ts","sourceRoot":"","sources":["../../src/foundation/LayoutSize.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAClB"}

package/dist/foundation/LayoutSize.js

@@ -0,0 +1 @@
+export {};

package/dist/layout/index.d.ts

@@ -0,0 +1,6 @@
+export * from './resize/core/SizedLayoutProps';
+export * from './resize/core/SizedLayoutContext';
+export * from './resize/core/ResizeObserverHook';
+export * from './resize/impl/SizedContainer';
+export * from './resize/impl/SizedLayout';
+//# sourceMappingURL=index.d.ts.map

package/dist/layout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/layout/index.ts"],"names":[],"mappings":"AAAA,cAAc,gCAAgC,CAAA;AAC9C,cAAc,kCAAkC,CAAA;AAChD,cAAc,kCAAkC,CAAA;AAChD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2BAA2B,CAAA"}

package/dist/layout/index.js

@@ -0,0 +1,5 @@
+export * from './resize/core/SizedLayoutProps';
+export * from './resize/core/SizedLayoutContext';
+export * from './resize/core/ResizeObserverHook';
+export * from './resize/impl/SizedContainer';
+export * from './resize/impl/SizedLayout';

package/dist/layout/resize/core/ResizeObserverHook.d.ts

@@ -0,0 +1,41 @@
+import { RefObject } from 'react';
+import { LayoutSize } from "../../../foundation/LayoutSize";
+interface UseResizeObserverOptions {
+    /** 防抖延迟，默认 0（不防抖） */
+    debounce?: number;
+    /** 初始尺寸 */
+    initialSize?: LayoutSize;
+}
+interface UseResizeObserverReturn<T extends HTMLElement> {
+    /** 绑定到容器元素的 ref */
+    containerRef: RefObject<T | null>;
+    /** 容器宽度 */
+    containerWidth: number;
+    /** 容器高度 */
+    containerHeight: number;
+    /** 是否已获取到尺寸 */
+    isContainerReady: boolean;
+}
+/**
+ * 基于 ResizeObserver 监听容器尺寸变化
+ *
+ * @example
+ * ```tsx
+ * const { containerRef, containerWidth, containerHeight, isContainerReady } = useResizeObserver();
+ *
+ * return (
+ *   <div ref={containerRef}>
+ *     {isContainerReady && <Chart width={containerWidth} height={containerHeight} />}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带防抖
+ * const { containerRef, containerHeight } = useResizeObserver({ debounce: 100 });
+ * ```
+ */
+export declare function useResizeObserver<T extends HTMLElement = HTMLDivElement>(options?: UseResizeObserverOptions): UseResizeObserverReturn<T>;
+export {};
+//# sourceMappingURL=ResizeObserverHook.d.ts.map

package/dist/layout/resize/core/ResizeObserverHook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResizeObserverHook.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/core/ResizeObserverHook.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,SAAS,EAAC,MAAM,OAAO,CAAC;AAC7D,OAAO,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAG1D,UAAU,wBAAwB;IAC9B,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW;IACX,WAAW,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,UAAU,uBAAuB,CAAC,CAAC,SAAS,WAAW;IACnD,mBAAmB;IACnB,YAAY,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAClC,WAAW;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe;IACf,gBAAgB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,WAAW,GAAG,cAAc,EACpE,OAAO,GAAE,wBAA6B,GACvC,uBAAuB,CAAC,CAAC,CAAC,CAqC5B"}

package/dist/layout/resize/core/ResizeObserverHook.js

@@ -0,0 +1,57 @@
+import { useState, useEffect, useRef } from 'react';
+/**
+ * 基于 ResizeObserver 监听容器尺寸变化
+ *
+ * @example
+ * ```tsx
+ * const { containerRef, containerWidth, containerHeight, isContainerReady } = useResizeObserver();
+ *
+ * return (
+ *   <div ref={containerRef}>
+ *     {isContainerReady && <Chart width={containerWidth} height={containerHeight} />}
+ *   </div>
+ * );
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带防抖
+ * const { containerRef, containerHeight } = useResizeObserver({ debounce: 100 });
+ * ```
+ */
+export function useResizeObserver(options = {}) {
+    const { debounce = 0, initialSize = { width: 0, height: 0 } } = options;
+    const containerRef = useRef(null);
+    const [size, setSize] = useState(initialSize);
+    const timeoutRef = useRef(null);
+    useEffect(() => {
+        const element = containerRef.current;
+        if (!element)
+            return;
+        const updateSize = (entries) => {
+            var _a, _b;
+            const { width, height } = (_b = (_a = entries[0]) === null || _a === void 0 ? void 0 : _a.contentRect) !== null && _b !== void 0 ? _b : { width: 0, height: 0 };
+            if (debounce > 0) {
+                if (timeoutRef.current)
+                    clearTimeout(timeoutRef.current);
+                timeoutRef.current = setTimeout(() => setSize({ width, height }), debounce);
+            }
+            else {
+                setSize({ width, height });
+            }
+        };
+        const observer = new ResizeObserver(updateSize);
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+            if (timeoutRef.current)
+                clearTimeout(timeoutRef.current);
+        };
+    }, [debounce]);
+    return {
+        containerRef,
+        containerWidth: size.width,
+        containerHeight: size.height,
+        isContainerReady: size.width > 0 && size.height > 0,
+    };
+}

package/dist/layout/resize/core/SizedLayoutContext.d.ts

@@ -0,0 +1,23 @@
+import { LayoutSize } from "../../../foundation/LayoutSize";
+/** Context 中的尺寸状态 */
+export interface SizedLayoutContextValue extends LayoutSize {
+    /** 是否已获取到有效尺寸 */
+    isReady: boolean;
+}
+export declare const SizedLayoutContext: import("react").Context<SizedLayoutContextValue | null>;
+/**
+ * 获取父级容器（SizedLayout 或 SizedContainer）的尺寸
+ *
+ * @throws 如果不在 SizedLayout 或 SizedContainer 内部使用会抛出错误
+ *
+ * @example
+ * ```tsx
+ * function ChildComponent() {
+ *   const { width, height, isReady } = useContextLayoutSize();
+ *   if (!isReady) return <Loading />;
+ *   return <div style={{ width, height }}>...</div>;
+ * }
+ * ```
+ */
+export declare function useContextLayoutSize(): SizedLayoutContextValue;
+//# sourceMappingURL=SizedLayoutContext.d.ts.map

package/dist/layout/resize/core/SizedLayoutContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SizedLayoutContext.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/core/SizedLayoutContext.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAG1D,qBAAqB;AACrB,MAAM,WAAW,uBAAwB,SAAQ,UAAU;IACvD,iBAAiB;IACjB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,kBAAkB,yDAAsD,CAAC;AAEtF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,IAAI,uBAAuB,CAM9D"}

package/dist/layout/resize/core/SizedLayoutContext.js

@@ -0,0 +1,23 @@
+import { createContext, useContext } from "react";
+export const SizedLayoutContext = createContext(null);
+/**
+ * 获取父级容器（SizedLayout 或 SizedContainer）的尺寸
+ *
+ * @throws 如果不在 SizedLayout 或 SizedContainer 内部使用会抛出错误
+ *
+ * @example
+ * ```tsx
+ * function ChildComponent() {
+ *   const { width, height, isReady } = useContextLayoutSize();
+ *   if (!isReady) return <Loading />;
+ *   return <div style={{ width, height }}>...</div>;
+ * }
+ * ```
+ */
+export function useContextLayoutSize() {
+    const context = useContext(SizedLayoutContext);
+    if (!context) {
+        throw new Error('useContextLayoutSize must be used within a SizedLayout or SizedContainer');
+    }
+    return context;
+}

package/dist/layout/resize/core/SizedLayoutProps.d.ts

@@ -0,0 +1,19 @@
+import { CSSProperties, ElementType, ReactNode } from "react";
+import { LayoutSize } from "../../../foundation/LayoutSize";
+export interface SizedLayoutProps {
+    /** 子元素 */
+    children: ReactNode;
+    /** 容器的 className */
+    className?: string;
+    /** 容器的 style */
+    style?: CSSProperties;
+    /** 自定义容器元素类型，默认 div */
+    as?: ElementType;
+    /** 防抖延迟（毫秒） */
+    debounce?: number;
+    /** 尺寸未就绪时显示的占位内容 */
+    fallback?: ReactNode;
+    /** 尺寸变化时的回调 */
+    onResize?: (size: LayoutSize) => void;
+}
+//# sourceMappingURL=SizedLayoutProps.d.ts.map

package/dist/layout/resize/core/SizedLayoutProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SizedLayoutProps.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/core/SizedLayoutProps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,aAAa,EAAE,WAAW,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC5D,OAAO,EAAC,UAAU,EAAC,MAAM,gCAAgC,CAAC;AAE1D,MAAM,WAAW,gBAAgB;IAC7B,UAAU;IACV,QAAQ,EAAE,SAAS,CAAC;IACpB,oBAAoB;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,uBAAuB;IACvB,EAAE,CAAC,EAAE,WAAW,CAAC;IACjB,eAAe;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,eAAe;IACf,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;CACzC"}

package/dist/layout/resize/core/SizedLayoutProps.js

@@ -0,0 +1 @@
+export {};

package/dist/layout/resize/impl/SizedContainer.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import { SizedLayoutProps } from "../core/SizedLayoutProps";
+/**
+ * 自动测量尺寸的容器组件（基于 react-resize-detector）
+ *
+ * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
+ * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <SizedContainer className="h-full w-full">
+ *   <ChartComponent />
+ * </SizedContainer>
+ *
+ * // ChartComponent 内部
+ * function ChartComponent() {
+ *   const { width, height, isReady } = useContextLayoutSize();
+ *   if (!isReady) return <Skeleton />;
+ *   return <Chart width={width} height={height} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带 fallback 的用法
+ * <SizedContainer fallback={<Loading />} className="h-full">
+ *   <VirtualList />
+ * </SizedContainer>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 自定义元素类型 + 尺寸变化回调
+ * <SizedContainer
+ *   as="section"
+ *   debounce={100}
+ *   onResize={({ width, height }) => console.log(width, height)}
+ * >
+ *   <Content />
+ * </SizedContainer>
+ * ```
+ */
+export declare function SizedContainer({ children, className, style, as: Component, debounce, fallback, onResize, }: SizedLayoutProps): React.JSX.Element;
+//# sourceMappingURL=SizedContainer.d.ts.map

package/dist/layout/resize/impl/SizedContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SizedContainer.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/impl/SizedContainer.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AAK1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,cAAc,CAAC,EACI,QAAQ,EACR,SAAS,EACT,KAAK,EACL,EAAE,EAAE,SAAiB,EACrB,QAAQ,EACR,QAAQ,EACR,QAAQ,GACX,EAAE,gBAAgB,qBA2BjD"}

package/dist/layout/resize/impl/SizedContainer.js

@@ -0,0 +1,65 @@
+'use client';
+import { useResizeDetector } from 'react-resize-detector';
+import React from "react";
+import { SizedLayoutContext } from "../core/SizedLayoutContext";
+/**
+ * 自动测量尺寸的容器组件（基于 react-resize-detector）
+ *
+ * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
+ * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <SizedContainer className="h-full w-full">
+ *   <ChartComponent />
+ * </SizedContainer>
+ *
+ * // ChartComponent 内部
+ * function ChartComponent() {
+ *   const { width, height, isReady } = useContextLayoutSize();
+ *   if (!isReady) return <Skeleton />;
+ *   return <Chart width={width} height={height} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带 fallback 的用法
+ * <SizedContainer fallback={<Loading />} className="h-full">
+ *   <VirtualList />
+ * </SizedContainer>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 自定义元素类型 + 尺寸变化回调
+ * <SizedContainer
+ *   as="section"
+ *   debounce={100}
+ *   onResize={({ width, height }) => console.log(width, height)}
+ * >
+ *   <Content />
+ * </SizedContainer>
+ * ```
+ */
+export function SizedContainer({ children, className, style, as: Component = 'div', debounce, fallback, onResize, }) {
+    const { width, height, ref } = useResizeDetector({
+        refreshMode: debounce ? 'debounce' : undefined,
+        refreshRate: debounce,
+        onResize: onResize
+            ? ({ width: w, height: h }) => {
+                if (w !== null && h !== null) {
+                    onResize({ width: w, height: h });
+                }
+            }
+            : undefined,
+    });
+    const size = {
+        width: width !== null && width !== void 0 ? width : 0,
+        height: height !== null && height !== void 0 ? height : 0,
+    };
+    const isReady = size.width > 0 && size.height > 0;
+    return (React.createElement(Component, { ref: ref, className: className, style: style },
+        React.createElement(SizedLayoutContext.Provider, { value: { ...size, isReady } }, fallback && !isReady ? fallback : children)));
+}

package/dist/layout/resize/impl/SizedLayout.d.ts

@@ -0,0 +1,45 @@
+import React from "react";
+import { SizedLayoutProps } from "../core/SizedLayoutProps";
+/**
+ * 自动测量尺寸的布局容器
+ *
+ * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
+ * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <SizedLayout className="h-full w-full">
+ *   <ChartComponent />
+ * </SizedLayout>
+ *
+ * // ChartComponent 内部
+ * function ChartComponent() {
+ *   const { width, height, isReady } = useContextLayoutSize();
+ *   if (!isReady) return <Skeleton />;
+ *   return <Chart width={width} height={height} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带 fallback 的用法
+ * <SizedLayout fallback={<Loading />} className="h-full">
+ *   <VirtualList />
+ * </SizedLayout>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 自定义元素类型 + 尺寸变化回调
+ * <SizedLayout
+ *   as="section"
+ *   debounce={100}
+ *   onResize={({ width, height }) => console.log(width, height)}
+ * >
+ *   <Content />
+ * </SizedLayout>
+ * ```
+ */
+export declare function SizedLayout({ children, className, style, as: Component, debounce, fallback, onResize, }: SizedLayoutProps): React.JSX.Element;
+//# sourceMappingURL=SizedLayout.d.ts.map

package/dist/layout/resize/impl/SizedLayout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SizedLayout.d.ts","sourceRoot":"","sources":["../../../../src/layout/resize/impl/SizedLayout.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAC,gBAAgB,EAAC,MAAM,0BAA0B,CAAC;AAG1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,WAAW,CAAC,EACI,QAAQ,EACR,SAAS,EACT,KAAK,EACL,EAAE,EAAE,SAAiB,EACrB,QAAQ,EACR,QAAQ,EACR,QAAQ,GACX,EAAE,gBAAgB,qBA2B9C"}

package/dist/layout/resize/impl/SizedLayout.js

@@ -0,0 +1,65 @@
+'use client';
+import { useEffect, useRef } from 'react';
+import { useResizeObserver } from '../core/ResizeObserverHook';
+import React from "react";
+import { SizedLayoutContext } from "../core/SizedLayoutContext";
+/**
+ * 自动测量尺寸的布局容器
+ *
+ * 子组件通过 useContextLayoutSize() 获取容器尺寸，适用于需要根据父容器尺寸
+ * 进行布局的场景（如虚拟列表、图表、Canvas 等）。
+ *
+ * @example
+ * ```tsx
+ * // 基础用法
+ * <SizedLayout className="h-full w-full">
+ *   <ChartComponent />
+ * </SizedLayout>
+ *
+ * // ChartComponent 内部
+ * function ChartComponent() {
+ *   const { width, height, isReady } = useContextLayoutSize();
+ *   if (!isReady) return <Skeleton />;
+ *   return <Chart width={width} height={height} />;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带 fallback 的用法
+ * <SizedLayout fallback={<Loading />} className="h-full">
+ *   <VirtualList />
+ * </SizedLayout>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 自定义元素类型 + 尺寸变化回调
+ * <SizedLayout
+ *   as="section"
+ *   debounce={100}
+ *   onResize={({ width, height }) => console.log(width, height)}
+ * >
+ *   <Content />
+ * </SizedLayout>
+ * ```
+ */
+export function SizedLayout({ children, className, style, as: Component = 'div', debounce, fallback, onResize, }) {
+    const { containerRef, containerWidth, containerHeight, isContainerReady } = useResizeObserver({
+        debounce,
+    });
+    const size = {
+        width: containerWidth,
+        height: containerHeight,
+    };
+    // 处理 onResize 回调
+    const onResizeRef = useRef(onResize);
+    onResizeRef.current = onResize;
+    useEffect(() => {
+        if (isContainerReady && onResizeRef.current) {
+            onResizeRef.current(size);
+        }
+    }, [containerWidth, containerHeight, isContainerReady]);
+    return (React.createElement(Component, { ref: containerRef, className: className, style: style },
+        React.createElement(SizedLayoutContext.Provider, { value: { ...size, isReady: isContainerReady } }, fallback && !isContainerReady ? fallback : children)));
+}

package/dist/utils/index.d.ts

@@ -1,4 +1,7 @@
 export * from './ScrollToCenter';
 export * from './Reload';
-export * from './SizedContainer';
+export * from '../layout/resize/core/ResizeObserverHook';
+export * from '../layout/resize/core/SizedLayoutContext';
+export * from '../layout/resize/impl/SizedLayout';
+export * from '../layout/resize/impl/SizedContainer';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,UAAU,CAAA;AACxB,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA,cAAc,kBAAkB,CAAA;AAChC,cAAc,UAAU,CAAA;AACxB,cAAc,0CAA0C,CAAA;AACxD,cAAc,0CAA0C,CAAA;AACxD,cAAc,mCAAmC,CAAA;AACjD,cAAc,sCAAsC,CAAA"}

package/dist/utils/index.js

@@ -1,4 +1,7 @@
 'use client';
 export * from './ScrollToCenter';
 export * from './Reload';
-export * from './SizedContainer';
+export * from '../layout/resize/core/ResizeObserverHook';
+export * from '../layout/resize/core/SizedLayoutContext';
+export * from '../layout/resize/impl/SizedLayout';
+export * from '../layout/resize/impl/SizedContainer';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xxf_react",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -45,9 +45,15 @@
     "./foundation": {
       "types": "./dist/foundation/index.d.ts",
       "import": "./dist/foundation/index.js"
+    },
+    "./layout": {
+      "types": "./dist/layout/index.d.ts",
+      "import": "./dist/layout/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc"
   },