@react-fabric/core 1.0.0-beta.6 → 1.0.0-beta.60

package/src/core/page/Page.tsx

@@ -23,11 +23,13 @@
 
 import classNames from "classnames";
 import { Loading } from "../../components/animations/Animations";
-import { Icon } from "../../components/icon/Icon";
-import { type ChildrenProp, type IconProps, type TestProps } from "../../types";
-import classes from "./Page.module.css";
+import { getIconProps, Icon, type IconProps } from "../../components/icon/Icon";
+import { type ChildrenProp, type RefProp, type TestProps } from "../../types";
 
-export interface PageProps extends IconProps, ChildrenProp, TestProps {
+export interface PageProps
+  extends ChildrenProp,
+    TestProps,
+    RefProp<HTMLDivElement> {
   /**
    * page title
    */
@@ -40,6 +42,10 @@ export interface PageProps extends IconProps, ChildrenProp, TestProps {
    * paper style drop shadow
    */
   paper?: boolean;
+  /**
+   * icon path or props
+   */
+  icon?: IconProps;
   /**
    * loading indicator
    */
@@ -47,20 +53,42 @@ export interface PageProps extends IconProps, ChildrenProp, TestProps {
 }
 
 /**
- * The page component used typically for routes, is a structured layout used within an application to organize and display content in a sectioned format, ensuring a consistent and intuitive user experience.
+ * Page component that wraps children in a div element.
+ * It includes a title section with an optional icon and a loading indicator.
+ * The component can be styled with a paper effect, page icon and title.
+ * It also accepts a loading prop to display a loading indicator.
+ *
+ * @param {PageProps} props - The properties for the Page component.
+ * @returns A div element containing the title and children, with optional loading indicator.
+ *
+ * @example
+ * ```jsx
+ * <Page
+ *   title="My Page"
+ *   icon="home"
+ *   loading={false}
+ *   paper={true}
+ *   data-testid="my-page"
+ *   data-test-value="page-value"
+ * >
+ *   <p>This is the content of the page.</p>
+ * </Page>
+ * // Renders a page with a title, icon, and content.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-application--page} for more details.
  */
 export const Page = ({
+  ref,
   children,
   paper,
   title,
   titleClassName,
   icon,
-  rtlFlip,
-  iconBg,
-  iconColor,
   loading,
   "data-testid": testId,
   "data-test-value": testValue,
+  ...rest
 }: PageProps) => {
   return (
     <div
@@ -68,29 +96,23 @@ export const Page = ({
       data-test-value={testValue}
       data-loading={loading}
       className={classNames(
-        classes.page,
+        "fabric-page relative",
         "overflow-hidden grid area-content",
-        paper && "shadow-paper m-[6px] rounded-capped",
+        paper && "shadow-paper m-1.5 rounded-capped",
       )}
+      ref={ref}
+      {...rest}
     >
       {title && (
         <div
           data-ref="pageTitle"
           className={classNames(
-            classes.pageTitle,
+            "fabric-pageTitle",
             "select-none flex gap-1 items-center justify-center px-1 py-0.5 font-medium text-center",
             titleClassName,
           )}
         >
-          {icon && (
-            <Icon
-              icon={icon}
-              size="1.25em"
-              rtlFlip={rtlFlip}
-              bg={iconBg}
-              color={iconColor}
-            />
-          )}
+          {icon && <Icon size="1.25em" {...getIconProps(icon)} />}
           {title}
         </div>
       )}

package/src/core/responsive/Responsive.tsx

@@ -29,7 +29,6 @@ import {
   type SizeTypeWithZero,
   type TestProps,
 } from "../../types";
-import classes from "./Responsive.module.css";
 
 export interface ContainerProps
   extends AriaProps,
@@ -81,15 +80,32 @@ export interface ColProps
   /**
    * column flex
    */
-  flex?: "auto" | "fill" | "full";
+  flex?: "auto" | "fill" | "full" | "initial" | "content";
   /**
    * stretch inner content
    */
   stretchContent?: boolean;
+  /**
+   * truncate text
+   */
+  truncate?: boolean;
 }
 
 /**
- * Responsive layout container
+ * Container component that wraps children in a div element.
+ * It supports full width, gutter size, and additional CSS classes.
+ * It can be used to create a responsive layout with optional gutters for spacing.
+ * It accepts properties for full width, gutter size, and additional CSS classes.
+ *
+ * @param {ContainerProps} props - The properties for the Container component.
+ * @returns A div element containing the children with optional full width and gutter size.
+ *
+ * @example
+ * ```jsx
+ * <Container fullWidth={true} gutter="16px" className="custom-container">
+ *   <p>This is a container with full width and gutter.</p>
+ * </Container>
+ * ```
  */
 export const Container = ({
   children,
@@ -101,7 +117,7 @@ export const Container = ({
   return (
     <div
       className={classNames(
-        classes.container,
+        "fabric-container",
         className,
         !fullWidth && "container mx-auto",
       )}
@@ -113,6 +129,26 @@ export const Container = ({
   );
 };
 
+/**
+ * Row component that allows for flexible layout of columns.
+ * It supports various flex properties, alignment, and wrapping.
+ * It can be used to create a responsive layout with optional gutters for spacing.
+ * It accepts properties for gutter size, orientation, alignment, justification, and additional CSS classes.
+ *
+ * @param {RowProps} props - The properties for the Row component.
+ * @returns A div element representing a row with the specified flex and alignment properties.
+ *
+ * @example
+ * ```jsx
+ * <Row gutter="16px" orient="row" align="center" justify="between">
+ *   <Col flex="fill">Column 1</Col>
+ *   <Col flex="fill">Column 2</Col>
+ * </Row>
+ * // Renders a row with two columns, each taking equal space, centered vertically and spaced evenly.
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-application--responsive} for more details.
+ */
 export const Row = ({
   children,
   gutter,
@@ -126,7 +162,7 @@ export const Row = ({
   return (
     <div
       className={classNames(
-        classes.row,
+        "fabric-row",
         className,
         "flex",
         orient === "row" && "flex-row",
@@ -145,10 +181,29 @@ export const Row = ({
   );
 };
 
+/**
+ * Column component that allows for flexible layout within a row.
+ * It supports various flex properties, alignment, and truncation.
+ * It can be used to create a responsive layout with optional stretching of inner content.
+ * It accepts properties for flex size, alignment, truncation, and additional CSS classes.
+ *
+ * @param {ColProps} props - The properties for the Col component.
+ * @returns A div element representing a column with the specified flex and alignment properties.
+ *
+ * @example
+ * ```jsx
+ * <Col flex="fill" align="center" truncate className="custom-col">
+ *   <p>This is a column with flexible layout.</p>
+ * </Col>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-application--responsive} for more details.
+ */
 export const Col = ({
   children,
   flex,
   align,
+  truncate,
   className,
   stretchContent,
   ...aria
@@ -156,13 +211,16 @@ export const Col = ({
   return (
     <div
       className={classNames(
-        classes.col,
+        "fabric-col",
         className,
-        stretchContent && classes.stretchContent,
-        flex === "auto" && "flex-content",
+        stretchContent && "stretchContent",
         flex === "fill" && "flex-1",
         flex === "full" && "flex-full",
+        flex === "auto" && "flex-auto",
+        flex === "initial" && "flex-initial",
+        flex === "content" && "flex-content",
         align && `self-${align}`,
+        truncate && "truncate",
       )}
       {...aria}
     >

package/src/core/section/Section.tsx

@@ -22,28 +22,50 @@
  */
 
 import classNames from "classnames";
-import { type ChildrenProp, type CssProp, type RefProp } from "../../types";
+import {
+  type TestProps,
+  type ChildrenProp,
+  type CssProp,
+  type RefProp,
+} from "../../types";
 import { ErrorBoundary } from "../boundary/ErrorBoundary";
-import classes from "./Section.module.css";
 
 /**
- * The section component provides a structured layout used within a page to organize and display content in a sectioned format, ensuring a consistent and intuitive user experience.
+ * A component that represents a section of content within a page, with templated grid layout.
+ * It can be used to group related content together and can be styled with additional CSS classes.
+ * It supports RTL (right-to-left) text direction.
+ *
+ * @param {ChildrenProp} children - The children to be rendered inside the section.
+ * @param {CssProp} className - Additional CSS classes to apply to the section.
+ * @param {RefProp<HTMLDivElement>} ref - A ref to the section element.
+ *
+ * @example
+ * ```jsx
+ * <Section className="my-section" ref={sectionRef}>
+ *   <p>This is a section.</p>
+ * </Section>
+ * ```
+ *
+ *  @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-application--section} for more details.
  */
 export const Section = ({
   children,
   className,
   dir,
   ref,
+  ...rest
 }: ChildrenProp &
   CssProp &
+  TestProps &
   RefProp<HTMLDivElement> & { dir?: "ltr" | "rtl" }) => {
   return (
     <div
       data-ref="section"
       dir={dir}
       ref={ref}
+      {...rest}
       className={classNames(
-        classes.section,
+        "fabric-section",
         className,
         "grid area-content overflow-hidden",
       )}

package/src/core/theme/ThemeProvider.tsx

@@ -25,7 +25,7 @@ import { isColor } from "@react-fabric/utilities";
 import classNames from "classnames";
 import { useMemo } from "react";
 import { type ChildrenProp } from "../../types";
-import classes from "./Theme.module.css";
+import { useApplicationContext } from "../../context/Global";
 
 export interface ThemeProps {
   /**
@@ -36,9 +36,9 @@ export interface ThemeProps {
    * branding css className
    *
    * .branding {
-   *  --primary: #color;
-   *  --accent: #color;
-   *  --tint: #color;
+   *  --color-primary: #color;
+   *  --color-accent: #color;
+   *  --color-tint: #color;
    * }
    */
   branding?: string;
@@ -57,11 +57,31 @@ export interface ThemeProps {
   /**
    * component rounding
    */
-  rounding?: "minimal" | "normal" | "full";
+  rounding?: "sm" | "md" | "full";
 }
 
 /**
- * Theme override
+ * This component provides a way to set the theme for the application.
+ * It allows you to set the primary, accent, and tint colors, as well as the color scheme and rounding.
+ * It uses CSS variables to apply the colors and styles.
+ * It also applies the branding className to the root element.
+ * The component uses the `useApplicationContext` hook to get the current color scheme from the application context.
+ *
+ * @example
+ * ```jsx
+ * <ThemeProvider
+ *   branding="my-branding"
+ *   primaryColor="#ff0000"
+ *   accentColor="#00ff00"
+ *   tintColor="#0000ff"
+ *   colorScheme="dark"
+ *   rounding="md"
+ * >
+ *   <div>Your content here</div>
+ * </ThemeProvider>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-application--theme-provider} for more details.
  */
 export const ThemeProvider = ({
   children,
@@ -72,25 +92,26 @@ export const ThemeProvider = ({
   colorScheme,
   rounding,
 }: ThemeProps & ChildrenProp) => {
+  const { currentColorScheme } = useApplicationContext();
   const styles = useMemo(() => {
     const ret: KeyValue = {};
     if (primaryColor && isColor(primaryColor)) {
-      ret["--primary"] = primaryColor;
+      ret["--color-primary"] = primaryColor;
     }
     if (primaryColor && !isColor(primaryColor)) {
-      ret["--primary"] = `var(--${primaryColor})`;
+      ret["--color-primary"] = `var(--color-${primaryColor})`;
     }
     if (accentColor && isColor(accentColor)) {
-      ret["--accent"] = accentColor;
+      ret["--color-accent"] = accentColor;
     }
     if (accentColor && !isColor(accentColor)) {
-      ret["--accent"] = `var(--${accentColor})`;
+      ret["--color-accent"] = `var(--color-${accentColor})`;
     }
     if (tintColor && isColor(tintColor)) {
-      ret["--tint"] = tintColor;
+      ret["--color-tint"] = tintColor;
     }
     if (tintColor && !isColor(tintColor)) {
-      ret["--tint"] = `var(--${tintColor})`;
+      ret["--color-tint"] = `var(--color-${tintColor})`;
     }
     return ret;
   }, [primaryColor, accentColor, tintColor]);
@@ -98,10 +119,10 @@ export const ThemeProvider = ({
   return (
     <div
       style={styles}
-      data-color-scheme={colorScheme}
+      data-color-scheme={colorScheme ?? currentColorScheme}
       data-rounding={rounding}
       className={classNames(
-        classes.themeProvider,
+        "fabric-themeProvider",
         "contents theme-base",
         branding,
       )}

package/src/core/viewport/Viewport.tsx

@@ -23,17 +23,30 @@
 
 import classNames from "classnames";
 import { type PropsWithChildren } from "react";
-import classes from "./Viewport.module.css";
 
 /**
- * The application viewport is the main container that defines the visible area where content is displayed and interacted with.
+ * This component is used to create a full-screen viewport
+ * that can be used to display content in a grid layout.
+ * It is typically used as a container for the main content of the application.
+ * It is styled to take up the full width and height of the viewport,
+ * and it uses absolute positioning to ensure it covers the entire screen.
+ * The component accepts children as props, allowing you to nest other components inside it.
+ *
+ * @example
+ * ```jsx
+ * <Viewport>
+ *   <YourContentComponent />
+ * </Viewport>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-application--viewport} for more details.
  */
 export const Viewport = ({ children }: PropsWithChildren) => {
   return (
     <div
       data-ref="viewport"
       className={classNames(
-        classes.viewport,
+        "fabric-viewport",
         "grid overflow-hidden absolute inset-0",
       )}
     >

package/src/hooks/useControlledValue.tsx

@@ -24,6 +24,18 @@
 import { useDeferredValue, useState } from "react";
 import { useEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to manage a controlled value with a default fallback for inputs.
+ * It updates the current value whenever the deferred value changes.
+ * This is useful for scenarios where you want to control the value of a component
+ * while also providing a default value if the controlled value is not set.
+ * This hook is particularly useful for form inputs or components that require a controlled value
+ * but also need to handle cases where the value might not be immediately available.
+ *
+ * @param value - The controlled value that may change.
+ * @param defaultValue - The default value to use if the controlled value is not set.
+ * @returns An object containing the current value and a function to update it.
+ */
 export const useControlledValue = <T extends AnyObject = string>(
   value: T,
   defaultValue: T,

package/src/hooks/useDebounce.ts

@@ -23,12 +23,24 @@
 
 import { useMemo, useRef } from "react";
 
+/**
+ * Custom hook to debounce a function.
+ * This hook delays the processing of the function until after a specified delay period
+ * has elapsed since the last time the function was invoked. This is useful for optimizing
+ * performance in scenarios where a function may be called frequently, such as during
+ * user input or window resizing events.
+ *
+ * @param callback - The function to debounce.
+ * @param deps - The dependency array for the hook.
+ * @param delay - The debounce delay in milliseconds.
+ * @returns A debounced version of the callback function.
+ */
 export const useDebounce = (
   callback: undefined | ((...rest: AnyObject) => AnyObject),
   deps: AnyObject[],
   delay: number = 100,
 ) => {
-  const timerRef = useRef<AnyObject>();
+  const timerRef = useRef<AnyObject>(null);
 
   const cb = useMemo(() => {
     if (typeof window !== "undefined") {

package/src/hooks/useEffectDebugger.ts

@@ -44,10 +44,9 @@ const compareInputs = (
   logger: ReturnType<typeof useLogger>,
 ) => {
   if (
-    process.env.NODE_ENV === "production" &&
     typeof window !== "undefined" &&
     // @ts-expect-error ignore
-    window.DEBUG_HOOKS !== true
+    window.DEBUG_EFFECTS !== true
   )
     return;
 
@@ -87,6 +86,19 @@ const compareInputs = (
   });
 };
 
+/**
+ * Custom hook to debug useMemo hooks.
+ * It compares the current and previous dependency arrays and logs any differences.
+ * @param func - The function to be memoized or executed in the effect.
+ * @param inputs - The dependency array for the hook.
+ * @param prefix - A prefix for the log messages to identify the hook.
+ * @returns The result of the memoized function or the effect.
+ *
+ * @example
+ * ```jsx
+ * const value = useMemoDebugger(() => computeValue(), [dependency1, dependency2], "MyComponent");
+ * ```
+ */
 export const useMemoDebugger = <T>(
   func: () => T,
   inputs: DependencyList,
@@ -109,6 +121,24 @@ export const useMemoDebugger = <T>(
   }, inputs);
 };
 
+/**
+ * Custom hook to debug useEffect and useLayoutEffect hooks.
+ * It compares the current and previous dependency arrays and logs any differences.
+ * @param func - The effect function to be executed.
+ * @param inputs - The dependency array for the effect.
+ * @param prefix - A prefix for the log messages to identify the effect.
+ * @returns A cleanup function if the effect returns one.
+ *
+ * @example
+ * ```jsx
+ * useEffectDebugger(() => {
+ *   // Effect logic here
+ *   return () => {
+ *     // Cleanup logic here
+ *   };
+ * }, [dependency1, dependency2], "MyComponent");
+ * ```
+ */
 export const useEffectDebugger = (
   func: EffectCallback,
   inputs: DependencyList,
@@ -131,6 +161,24 @@ export const useEffectDebugger = (
   }, inputs);
 };
 
+/**
+ * Custom hook to debug useLayoutEffect hooks.
+ * It compares the current and previous dependency arrays and logs any differences.
+ * @param func - The layout effect function to be executed.
+ * @param inputs - The dependency array for the layout effect.
+ * @param prefix - A prefix for the log messages to identify the layout effect.
+ * @returns A cleanup function if the layout effect returns one.
+ *
+ * @example
+ * ```jsx
+ * useLayoutEffectDebugger(() => {
+ *   // Layout effect logic here
+ *   return () => {
+ *     // Cleanup logic here
+ *   };
+ * }, [dependency1, dependency2], "MyComponent");
+ * ```
+ */
 export const useLayoutEffectDebugger = (
   func: EffectCallback,
   inputs: DependencyList,

package/src/hooks/useIsDark.ts

@@ -24,6 +24,14 @@
 import { useCallback, useState } from "react";
 import { useLayoutEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to determine if the current theme is dark.
+ * It checks the background color of the document's root element
+ * and sets the `isDark` state based on the red component of the RGB color.
+ * If the red component is less than 50, it considers the theme to be dark.
+ *
+ * @returns {boolean} - Returns true if the theme is dark, false otherwise.
+ */
 export const useIsDark = () => {
   const [isDark, setDark] = useState(false);
   const checkTheme = useCallback(() => {

package/src/hooks/useIsRtl.ts

@@ -25,6 +25,18 @@ import { useState } from "react";
 import { useTranslation } from "react-i18next";
 import { useLayoutEffectDebugger } from "./useEffectDebugger";
 
+/**
+ * Custom hook to determine if the current locale is RTL (Right-to-Left).
+ * It uses the i18n instance from react-i18next to check the direction.
+ *
+ * @returns {boolean} - Returns true if the current locale is RTL, false otherwise.
+ *
+ * @example
+ * ```jsx
+ * const isRtl = useIsRtl();
+ * // This will return true if the current locale is RTL, false otherwise.
+ * ```
+ */
 export const useIsRtl = () => {
   const { i18n } = useTranslation("core");
   const [isRtl, setIsRtl] = useState(false);

package/src/hooks/useNavigator.tsx

@@ -21,24 +21,47 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 
+/**
+ * Custom hook to manage navigation through a list of items.
+ * It provides functionality to navigate forward and backward,
+ * and keeps track of the current index and total count of items.
+ *
+ * @param totalCount - Total number of items to navigate through.
+ * @param defaultIndex - Initial index to start navigation from.
+ * @returns An object containing the current index, a function to navigate,
+ *          a label for the current position, and a function to set the current index.
+ *
+ * @example
+ * ```jsx
+ * const { headLabel, onNavigate, currentIndex, setCurrentIndex } = useNavigator(5, 0);
+ * // headLabel will show "1/5"
+ * // onNavigate(1) will move to the next item, and onNavigate(-1) will move to the previous item.
+ * // currentIndex will be updated accordingly.
+ * ```
+ */
 export const useNavigator = (totalCount = 0, defaultIndex = 0) => {
   const [currentIndex, setCurrentIndex] = useState(defaultIndex);
+  const refCurrent = useRef(defaultIndex);
+
   const onNavigate = useCallback(
     (dir: 1 | -1) => {
       if (dir === -1) {
-        setCurrentIndex(currentIndex > 0 ? currentIndex - 1 : totalCount - 1);
+        refCurrent.current =
+          refCurrent.current > 0 ? refCurrent.current - 1 : totalCount - 1;
       }
       if (dir === 1) {
-        setCurrentIndex(currentIndex + 1 < totalCount ? currentIndex + 1 : 0);
+        refCurrent.current =
+          refCurrent.current + 1 < totalCount ? refCurrent.current + 1 : 0;
       }
+      setCurrentIndex(refCurrent.current);
     },
-    [currentIndex, totalCount],
+    [totalCount],
   );
   const headLabel = useMemo(
     () => (
-      <span className="text-muted leading-none">
+      <span className="text-muted leading-none select-none">
         {currentIndex + 1}/{totalCount}
       </span>
     ),