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

package/src/components/tabpanel/TabPanel.tsx

@@ -33,7 +33,6 @@ import {
 import { type CallbackReturn, type ChildrenProp } from "../../types";
 import { nodeCheck } from "../../utils";
 import { Tab } from "./Tab";
-import classes from "./TabPanel.module.css";
 
 export interface TabPanelProps extends ChildrenProp<typeof Tab> {
   /**
@@ -47,11 +46,15 @@ export interface TabPanelProps extends ChildrenProp<typeof Tab> {
   /**
    * tab variations
    */
-  variant?: "soft" | "solid" | "outline";
+  variant?: "soft" | "solid" | "outline" | "pills";
   /**
    * tab button flex to fill tabs
    */
   tabFlex?: boolean;
+  /**
+   * rotate tab sideways for start/end orientation
+   */
+  tabRotate?: boolean;
   /**
    * tab button gap
    */
@@ -64,6 +67,18 @@ export interface TabPanelProps extends ChildrenProp<typeof Tab> {
    * tab list className
    */
   headerClassName?: string;
+  /**
+   * active tab className
+   */
+  activeClassName?: string;
+  /**
+   * append element
+   */
+  append?: React.ReactNode;
+  /**
+   * prepend element
+   */
+  prepend?: React.ReactNode;
   /**
    * change handler
    */
@@ -76,14 +91,51 @@ export interface TabPanelProps extends ChildrenProp<typeof Tab> {
 
 // TODO: implement append/prepend tab-bar items
 
+/**
+ * A component that provides a tabbed interface for displaying content.
+ * It allows users to switch between different tabs, each containing its own content.
+ * It supports various orientations, justify options, and variants for the tab header.
+ * It also provides hooks for handling tab changes before and after they occur.
+ * This component is useful for organizing content into separate sections that can be easily navigated by the user.
+ * It can be customized with different styles and behaviors to fit the needs of the application.
+ *
+ * @param {TabPanelProps} props - The properties for the TabPanel component.
+ * @returns {JSX.Element} The rendered TabPanel component.
+ *
+ * @example
+ * ```jsx
+ * <TabPanel
+ *   orientation="top"
+ *   activeTab="tab1"
+ *   justify="start"
+ *   variant="solid"
+ *   tabFlex={true}
+ *   onBeforeChange={(nextTab, currentTab) => {
+ *     console.log(`Switching from ${currentTab} to ${nextTab}`);
+ *     return true; // or false to prevent change
+ *   }}
+ *   onChange={(id) => console.log(`Active tab changed to: ${id}`)}
+ * >
+ *   <Tab id="tab1" label="Tab 1">Content for Tab 1</Tab>
+ *   <Tab id="tab2" label="Tab 2">Content for Tab 2</Tab>
+ *   <Tab id="tab3" label="Tab 3">Content for Tab 3</Tab>
+ * </TabPanel>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-tabpanel--docs} for more details.
+ */
 export const TabPanel = ({
   children,
   headerClassName,
   orientation = "top",
   activeTab,
+  activeClassName,
   justify,
   variant,
   tabFlex,
+  append,
+  prepend,
+  tabRotate,
   gap,
   onBeforeChange,
   onChange,
@@ -124,7 +176,7 @@ export const TabPanel = ({
   return (
     <div
       className={classNames(
-        classes.tabPanel,
+        "fabric-tabPanel",
         "area-content grid bg-base overflow-hidden",
       )}
       data-orientation={orientation}
@@ -132,21 +184,35 @@ export const TabPanel = ({
     >
       <div
         className={classNames(
-          classes.tabList,
+          "fabric-tabHeader",
           headerClassName,
+          tabRotate && "tab-rotate",
           justify && `justify-${justify}`,
           ["start", "end"].includes(orientation) && "flex-col",
-          "flex flex-nowrap overflow-auto scroll-thin",
+          "flex flex-nowrap overflow-hidden items-center",
         )}
-        style={{ gap }}
       >
-        {tabs.map((node: AnyObject) =>
-          cloneElement(node, {
-            tabFlex: node.props.tabFlex ?? tabFlex,
-            onClick: handleClick,
-            active: node.props.id === active,
-          }),
-        )}
+        {prepend}
+        <div
+          className={classNames(
+            "fabric-tabList",
+            justify && `justify-${justify}`,
+            ["start", "end"].includes(orientation) && "flex-col",
+            ["bottom", "end"].includes(orientation) ? "self-start" : "self-end",
+            "flex flex-1 flex-nowrap overflow-auto scroll-thin",
+          )}
+          style={{ gap }}
+        >
+          {tabs.map((node: AnyObject) =>
+            cloneElement(node, {
+              tabFlex: node.props.tabFlex ?? tabFlex,
+              activeClassName: node.props.activeClassName ?? activeClassName,
+              onClick: handleClick,
+              active: node.props.id === active,
+            }),
+          )}
+        </div>
+        {append}
       </div>
       {rest}
       {activeTabPanel}

package/src/context/Global.tsx

@@ -146,6 +146,10 @@ export const ApplicationProvider: FC<GlobalProps> = ({
     defaultLocale ?? systemLocale(),
   );
 
+  useEffect(() => {
+    defaultColorScheme && setColorScheme(defaultColorScheme);
+  }, [defaultColorScheme]);
+
   /** ***************** set initial theme and locale dir  *******************/
   useEffect(() => {
     document.documentElement.lang = locale;
@@ -228,13 +232,36 @@ export const ApplicationProvider: FC<GlobalProps> = ({
 export const useGlobals = () => useContext(GlobalContext);
 
 /**
- * global application context
+ * Hook to access the global application context.
+ * This hook provides access to the global context values, including the current locale, calendar, and color scheme.
+ *
+ * @returns {GlobalContextType} The global context values excluding the error element.
+ *
+ * @example
+ * ```jsx
+ * const { changeLocale, currentLocale, toggleColorScheme } = useApplicationContext();
+ * ```
  */
 export const useApplicationContext = () => {
   const { errorElement, ...rest } = useContext(GlobalContext);
   return rest;
 };
 
+/**
+ * Hook to access the notification manager from the global context.
+ * This hook provides methods to show alerts, errors, messages, and toasts.
+ * It returns a reference to the notification manager, which can be used to display notifications in the application.
+ *
+ * @returns {NotificationManagerRef} The notification manager reference.
+ *
+ * @example
+ * ```jsx
+ * const notificationService = useNotificationService();
+ * notificationService.showMessage("Hello World");
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/docs/core-components-notifications--notifications} for more details on available methods.
+ */
 export const useNotificationService = () => {
   const { notificationManager } = useContext(GlobalContext);
   return notificationManager ?? {};

package/src/context/NotificationCenter.tsx

@@ -194,7 +194,7 @@ export const NotificationManager = ({ onLoad }: KeyValue) => {
       {createPortal(
         <div
           style={{ zIndex: "var(--z-overlay)" }}
-          className="ruf-container__overlays pointer-events-none fixed inset-0 p-4 bg-transparent"
+          className="fabric-container__overlays pointer-events-none fixed inset-0 p-4 bg-transparent"
         >
           {Object.values(alerts).map(([el]: AnyObject) => el)}
         </div>,
@@ -203,7 +203,7 @@ export const NotificationManager = ({ onLoad }: KeyValue) => {
       {createPortal(
         <div
           style={{ zIndex: "var(--z-notifications)" }}
-          className="ruf-container__notifs flex flex-nowrap pointer-events-none fixed inset-0 p-2 bg-transparent flex-col-reverse items-center justify-end"
+          className="fabric-container__notifs flex flex-nowrap pointer-events-none fixed inset-0 p-2 bg-transparent flex-col-reverse items-center justify-end"
         >
           {Object.values(messages).map(([el]: AnyObject) => el)}
         </div>,
@@ -212,7 +212,7 @@ export const NotificationManager = ({ onLoad }: KeyValue) => {
       {createPortal(
         <div
           style={{ zIndex: "var(--z-notifications)" }}
-          className="ruf-container__toasts flex flex-nowrap pointer-events-none fixed inset-0 p-4 bg-transparent flex-col items-end justify-end overflow-auto scroll-hide"
+          className="fabric-container__toasts flex flex-nowrap pointer-events-none fixed inset-0 p-4 bg-transparent flex-col items-end justify-end overflow-auto scroll-hide"
         >
           {Object.values(toasts).map(([el]: AnyObject) => el)}
         </div>,

package/src/core/aside/Aside.tsx

@@ -22,16 +22,9 @@
  */
 
 import classNames from "classnames";
-import {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  type ReactNode,
-} from "react";
-import { Loading } from "../../components/animations/Animations";
-import { Icon } from "../../components/icon/Icon";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { LoadingLine } from "../../components/animations/Animations";
+import { getIconProps, Icon, type IconProps } from "../../components/icon/Icon";
 import { useLayoutEffectDebugger } from "../../hooks/useEffectDebugger";
 import { usePropToggle } from "../../hooks/usePropToggle";
 import { useResize } from "../../hooks/useResize";
@@ -40,27 +33,27 @@ import {
   type CollapseProps,
   type CssProp,
   type Elements,
-  type IconProps,
   type TestProps,
 } from "../../types";
-import { CoreIcons } from "../../types/icons";
 import { ErrorBoundary } from "../boundary/ErrorBoundary";
-import classes from "./Aside.module.css";
 
 export interface AsideProps
-  extends IconProps,
-    ChildrenProp,
+  extends ChildrenProp,
     CollapseProps,
     CssProp,
     TestProps {
   /**
    * page title
    */
-  title?: ReactNode;
+  title?: React.ReactNode;
   /**
    * align inline-end
    */
   align?: "start" | "end";
+  /**
+   * icon path or props
+   */
+  icon?: IconProps;
   /**
    * header actions
    */
@@ -106,15 +99,47 @@ export interface AsideProps
 }
 
 /**
- * Side panel
+ * A sidebar component that can be collapsed, resized, and has a flyout feature.
+ * It supports a title, icon, actions, and loading state.
+ * It can be aligned to the start or end of the page.
+ *
+ * @param {AsideProps} props - The properties for the Aside component.
+ * @returns {JSX.Element} The rendered Aside component.
+ *
+ * @example
+ * ```jsx
+ * <Aside
+ *   title="Sidebar Title"
+ *   icon=icon-[mdi--menu]
+ *   rtlFlip={true}
+ *   className="custom-aside"
+ *   bodyClassName="custom-aside-body"
+ *   headerClassName="custom-aside-header"
+ *   resizeable={true}
+ *   flyout={true}
+ *   onFlyout={() => console.log("Flyout triggered")}
+ *   collapsed={false}
+ *   collapsable={true}
+ *   onCollapse={() => console.log("Collapsed toggled")}
+ *   actions={<button>Action</button>}
+ *   loading={false}
+ *   align="start"
+ *   width="20rem"
+ *   minWidth="2rem"
+ *   maxWidth="30vw"
+ *   data-testid="aside-test"
+ *   data-test-value="aside-value"
+ * >
+ *   <Content>This is the content of the aside.</Content>
+ * </Aside>
+ * ```
+ *
+ * @see {@link https://adarshpastakia.github.io/react-fabric/?path=/story/core-application--aside} for more details.
  */
 export const Aside = ({
   children,
   title,
   icon,
-  iconBg,
-  iconColor,
-  rtlFlip,
   className,
   bodyClassName,
   headerClassName,
@@ -197,7 +222,7 @@ export const Aside = ({
 
   return (
     <aside
-      className={classNames(classes.aside, className, "overflow-hidden grid")}
+      className={classNames("fabric-aside", className, "overflow-hidden grid")}
       data-align={align}
       data-flyout={peek}
       data-loading={loading}
@@ -208,16 +233,16 @@ export const Aside = ({
     >
       <header
         className={classNames(
-          classes.asideHeader,
+          "fabric-asideHeader",
           headerClassName,
           "grid area-head items-center",
         )}
-        data-testid="aside-header"
+        data-ref="asideHeader"
       >
         {title && (
           <div
             className={classNames(
-              classes.asideTitle,
+              "fabric-asideTitle",
               "truncate py-0.5 px-1 select-none pointer-events-none",
             )}
           >
@@ -227,8 +252,8 @@ export const Aside = ({
         {collapsable && (
           <Icon
             aria-label={isCollapsed ? "expand" : "collapse"}
-            className={classNames(classes.asideCollapse, "p-2 select-none")}
-            icon={CoreIcons.chevronLeft}
+            className={classNames("fabric-asideCollapse", "p-2 select-none")}
+            icon="icon-[mdi--chevron-left]"
             rtlFlip
             onClick={toggleCollapse}
             data-ref="asideToggle"
@@ -236,37 +261,33 @@ export const Aside = ({
         )}
         {icon && (
           <Icon
-            icon={icon}
-            bg={iconBg}
-            color={iconColor}
-            rtlFlip={rtlFlip}
             className={classNames(
-              classes.asideIcon,
+              "fabric-asideIcon",
               "p-1 text-lg select-none pointer-events-none",
             )}
+            {...getIconProps(icon)}
           />
         )}
-        {actions && <div className={classes.asideActions}>{actions}</div>}
+        {actions && <div className={"fabric-asideActions"}>{actions}</div>}
       </header>
-      {loading && <Loading />}
+      {loading && <LoadingLine />}
       {isCollapsed && (
         <div
           role="none"
           onClick={tryPeek}
           data-ref="asidePlaceholder"
-          className={classes.asidePlaceholder}
+          className={"fabric-asidePlaceholder"}
         />
       )}
       <section
         ref={elementRef}
         data-ref="asideBody"
         className={classNames(
-          classes.asideBody,
+          "fabric-asideBody",
           bodyClassName,
           "overflow-hidden grid",
         )}
         style={isCollapsed ? widthStyles : undefined}
-        data-testid="aside-body"
       >
         <ErrorBoundary>{children}</ErrorBoundary>
       </section>
@@ -274,8 +295,8 @@ export const Aside = ({
         <div
           {...resizeHandleProps}
           className={classNames(
-            classes.asideResizer,
-            "before:absolute before:inset-0 before:w-1 before:top-1/2 before:-translate-y-1/2 before:transition-all",
+            "fabric-asideResizer",
+            "before:absolute before:inset-0 before:w-1 before:top-1/2 before:-translate-y-1/2 before:transition-all before:delay-150",
           )}
         />
       )}

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<
   {
@@ -114,6 +131,7 @@ export class ErrorBoundary extends Component<
     this.setState({ hasError: true, error: error.message, stack: error.stack });
   }
 
+  // eslint-disable-next-line @typescript-eslint/promise-function-async
   render() {
     const env = process.env.NODE_ENV;
     if (this.state.hasError) {
@@ -122,13 +140,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

@@ -34,7 +34,6 @@ import {
   type TestProps,
 } from "../../types";
 import { ErrorBoundary } from "../boundary/ErrorBoundary";
-import classes from "./Content.module.css";
 
 export interface ContentProps
   extends ChildrenProp,
@@ -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,
@@ -89,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} />
+  <HeadFoot as="header" area="head" data-ref="header" {...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} />
+  <HeadFoot as="footer" area="foot" data-ref="footer" {...props} />
 );