@react-fabric/core 1.0.0-beta.5 → 1.0.0-beta.52

package/src/core/boundary/ErrorBoundary.tsx

@@ -29,7 +29,6 @@ import { Fragment } from "react/jsx-runtime";
 import { useMemoDebugger } from "../../hooks/useEffectDebugger";
 import { usePropToggle } from "../../hooks/usePropToggle";
 import { type ChildrenProp } from "../../types";
-import classes from "./ErrorBoundary.module.css";
 import { ErrorIcon } from "./ErrorIcon";
 import { useGlobals } from "../../context/Global";
 
@@ -53,7 +52,7 @@ const ErrorMessage = ({ error, errorElement }: KeyValue) => {
   return (
     <Fragment>
       <ErrorIcon />
-      <div className={classNames(classes.boundaryMessage, "p-2")}>
+      <div className={classNames("fabric-boundaryMessage", "p-2")}>
         <EE error={error} />
       </div>
     </Fragment>
@@ -64,10 +63,12 @@ const ErrorStack = ({ error, stack }: KeyValue) => {
   const [show, toggleShow] = usePropToggle(false);
   useLogger().error(error, {}, stack);
   return (
-    <div className={classNames(classes.boundaryDetail, "overflow-hidden grid")}>
+    <div
+      className={classNames("fabric-boundaryDetail", "overflow-hidden grid")}
+    >
       <div
         className={classNames(
-          classes.boundaryLink,
+          "fabric-boundaryLink",
           "px-2 py-1 text-xs text-end",
         )}
       >
@@ -78,7 +79,7 @@ const ErrorStack = ({ error, stack }: KeyValue) => {
       {show && (
         <div
           className={classNames(
-            classes.boundaryStack,
+            "fabric-boundaryStack",
             "overflow-auto p-2 text-xs border-t",
           )}
         >
@@ -90,7 +91,23 @@ const ErrorStack = ({ error, stack }: KeyValue) => {
 };
 
 /**
- * An error boundary wrapper higher-order component designed to provide consistent error display across the application will trap runtime errors
+ * ErrorBoundary component to catch JavaScript errors anywhere in the child component tree,
+ * log those errors, and display a fallback UI.
+ * It can also display a custom error element if provided.
+ * This component is useful for preventing the entire application from crashing
+ * when an error occurs in a part of the component tree.
+ * It can be used to wrap any part of the application.
+ * It supports custom error display components and provides a default error message.
+ * It also conditionally displays the error stack trace in development mode.
+ *
+ * @example
+ * ```jsx
+ * <ErrorBoundary errorElement={CustomErrorComponent}>
+ *   <YourComponent />
+ * </ErrorBoundary>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-application--error-boundary}
  */
 export class ErrorBoundary extends Component<
   {
@@ -122,13 +139,13 @@ export class ErrorBoundary extends Component<
       return (
         <div
           className={classNames(
-            classes.errorBoundary,
+            "fabric-errorBoundary",
             "grid grid-rows-1 overflow-hidden p-0.5 rounded-capped",
           )}
         >
           <div
             className={classNames(
-              classes.boundaryContent,
+              "fabric-boundaryContent",
               "overflow-hidden grid rounded-capped",
             )}
           >

package/src/core/boundary/ErrorIcon.tsx

@@ -22,13 +22,12 @@
  */
 
 import classNames from "classnames";
-import classes from "./ErrorBoundary.module.css";
 
 export const ErrorIcon = () => (
   <svg
     xmlns="http://www.w3.org/2000/svg"
     viewBox="0 0 64 64"
-    className={classNames(classes.boundaryIcon, "size-6 m-2")}
+    className={classNames("fabric-boundaryIcon", "size-6 m-2")}
   >
     <path
       fill="#808080"

package/src/core/content/Content.tsx

@@ -22,19 +22,18 @@
  */
 
 import classNames from "classnames";
-import { useImperativeHandle } from "react";
+import { type MouseEvent, useImperativeHandle } from "react";
 import { useDebounce } from "../../hooks/useDebounce";
 import { useResizeObserver } from "../../hooks/useResizeObserver";
 import {
   type ChildrenProp,
   type CssProp,
-  type PositionObject,
   type RefProp,
+  type ScrollObject,
   type SizeObject,
   type TestProps,
 } from "../../types";
 import { ErrorBoundary } from "../boundary/ErrorBoundary";
-import classes from "./Content.module.css";
 
 export interface ContentProps
   extends ChildrenProp,
@@ -44,7 +43,7 @@ export interface ContentProps
   /**
    * scroll vevent handler
    */
-  onScroll?: (event: PositionObject) => void;
+  onScroll?: (scroll: ScrollObject, event: MouseEvent<HTMLDivElement>) => void;
   /**
    * scroll vevent handler
    */
@@ -52,7 +51,12 @@ export interface ContentProps
 }
 
 /**
- * Scrollable content element
+ * Content component that wraps children in a section element.
+ * It uses a resize observer to handle resizing and a debounced scroll handler.
+ * It also includes an error boundary to catch any errors in the children.
+ *
+ * @param {ContentProps} props - The properties for the Content component.
+ * @returns A section element containing the children wrapped in an error boundary.
  */
 export const Content = ({
   ref,
@@ -65,13 +69,19 @@ export const Content = ({
 }: ContentProps) => {
   const resizeHandle = useResizeObserver(onResize);
   const scrollHandler = useDebounce(
-    (e: React.UIEvent<HTMLDivElement>) => {
-      onScroll?.({
-        // @ts-expect-error ignore
-        left: e.target.scrollLeft,
-        // @ts-expect-error ignore
-        top: e.target.scrollTop,
-      });
+    (e: MouseEvent<HTMLDivElement>) => {
+      const el = e.target as HTMLElement;
+      onScroll?.(
+        {
+          left: el.scrollLeft,
+          top: el.scrollTop,
+          scrollHeight: el.scrollHeight,
+          scrollWidth: el.scrollWidth,
+          width: el.offsetWidth,
+          height: el.offsetHeight,
+        },
+        e,
+      );
     },
     [onScroll],
   );
@@ -83,7 +93,7 @@ export const Content = ({
       data-test-value={testValue}
       ref={resizeHandle}
       onScroll={scrollHandler}
-      className={classNames(classes.content, "area-content", className)}
+      className={classNames("fabric-content", "area-content", className)}
     >
       <ErrorBoundary>{children}</ErrorBoundary>
     </section>

package/src/core/headfoot/HeadFoot.tsx

@@ -22,27 +22,15 @@
  */
 
 import classNames from "classnames";
-import { useMemoDebugger } from "../../hooks/useEffectDebugger";
 import {
   type AriaProps,
   type ChildrenProp,
-  type ColorWithGrays,
   type CssProp,
   type TestProps,
 } from "../../types";
-import { getBgClass, getColor, getColorClass } from "../../utils";
-import classes from "./HeadFoot.module.css";
 
 interface BaseProps extends CssProp, AriaProps, ChildrenProp, TestProps {
   dir?: "ltr" | "rtl";
-  /**
-   * background color
-   */
-  bg?: ColorWithGrays | string;
-  /**
-   * background color
-   */
-  color?: ColorWithGrays | string;
 }
 
 type DefaultProps = BaseProps & { flex?: false };
@@ -58,8 +46,6 @@ const HeadFoot = ({
   as: E,
   children,
   className,
-  bg,
-  color,
   flex,
   area,
   dir,
@@ -67,37 +53,18 @@ const HeadFoot = ({
   justify = "start",
   ...aria
 }: KeyValue & { as: "header" | "footer" }) => {
-  /** ***************** style map *******************/
-  const styles = useMemoDebugger(
-    () => {
-      const s: KeyValue = {};
-      if (bg) {
-        s.backgroundColor = getColor(bg);
-      }
-      if (color) {
-        s.color = getColor(color);
-      }
-      return s;
-    },
-    [bg],
-    "HeadFoot styles",
-  );
-
   return (
     <E
       dir={dir}
       className={classNames(
-        classes.headfoot,
+        "fabric-headfoot",
         className,
-        bg && getBgClass(bg),
-        color && getColorClass(color),
         area === "head" ? "area-head" : "area-foot",
         `leading-none`,
-        flex && "flex flex-nowrap gap-px",
+        flex && "flex flex-nowrap",
         align && `items-${align}`,
         justify && `justify-${justify}`,
       )}
-      style={styles}
       {...aria}
     >
       {children}
@@ -105,10 +72,50 @@ const HeadFoot = ({
   );
 };
 
+/**
+ * Header component that wraps children in a header element.
+ * It uses the HeadFoot component to handle layout and styling.
+ * It accepts properties for direction, alignment, and justification,
+ * allowing for flexible layout configurations.
+ * The `as` prop is set to "header" to render the element as a header.
+ * The `area` prop is set to "head" to indicate that this is a header area.
+ * It can be used to create a consistent header layout across an application.
+ *
+ * @param {HeadFootProps} props - The properties for the Header component.
+ * @returns A header element containing the children wrapped in the HeadFoot component.
+ *
+ * @example
+ * ```jsx
+ * <Header className="custom-header" dir="ltr">
+ *   <h1>Header content goes here</h1>
+ * </Header>
+ * ```
+ */
 export const Header = (props: HeadFootProps) => (
   <HeadFoot as="header" area="head" {...props} />
 );
 
+/**
+ * Footer component that wraps children in a footer element.
+ * It uses the HeadFoot component to handle layout and styling.
+ * It accepts properties for direction, alignment, and justification,
+ * allowing for flexible layout configurations.
+ * The `as` prop is set to "footer" to render the element as a footer.
+ * The `area` prop is set to "foot" to indicate that this is a footer area.
+ * It can be used to create a consistent footer layout across an application.
+ * * The Footer component is designed to be flexible and can be styled with custom classes.
+ * It supports both default and flex layouts, allowing for alignment and justification of its children.
+ *
+ * @param {HeadFootProps} props - The properties for the Footer component.
+ * @returns A footer element containing the children wrapped in the HeadFoot component.
+ *
+ * @example
+ * ```jsx
+ * <Footer className="custom-footer" dir="ltr">
+ *   <p>Footer content goes here</p>
+ * </Footer>
+ * ```
+ */
 export const Footer = (props: HeadFootProps) => (
   <HeadFoot as="footer" area="foot" {...props} />
 );

package/src/core/page/Page.tsx

@@ -24,10 +24,18 @@
 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 {
+  type ChildrenProp,
+  type IconProps,
+  type RefProp,
+  type TestProps,
+} from "../../types";
 
-export interface PageProps extends IconProps, ChildrenProp, TestProps {
+export interface PageProps
+  extends IconProps,
+    ChildrenProp,
+    TestProps,
+    RefProp<HTMLDivElement> {
   /**
    * page title
    */
@@ -47,9 +55,35 @@ 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"
+ *   iconBg="bg-blue-500"
+ *   iconColor="text-white"
+ *   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,
@@ -61,22 +95,26 @@ export const Page = ({
   loading,
   "data-testid": testId,
   "data-test-value": testValue,
+  ...rest
 }: PageProps) => {
   return (
     <div
       data-testid={testId}
       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",
       )}
+      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,
           )}

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-none",
         align && `self-${align}`,
+        truncate && "truncate",
       )}
       {...aria}
     >

package/src/core/section/Section.tsx

@@ -24,10 +24,24 @@
 import classNames from "classnames";
 import { 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,
@@ -43,7 +57,7 @@ export const Section = ({
       dir={dir}
       ref={ref}
       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,
       )}