@react-fabric/core 1.0.0-beta.8 → 1.0.1

package/src/core/boundary/ErrorIcon.tsx

@@ -1,47 +1,49 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/**
+ * Error icon displayed within the ErrorBoundary fallback UI.
+ *
+ * Renders a circular icon with a red background and a white information
+ * symbol (an "i" inside a rectangle), used to visually indicate an error state.
  *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
+ * @example
+ * ```tsx
+ * import { ErrorIcon } from "@react-fabric/core";
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * <ErrorIcon />
+ * ```
  */
-
-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")}
-  >
-    <path
-      fill="#808080"
-      d="M64 32c0 17.673-14.327 32-32 32s-32-14.327-32-32 14.327-32 32-32 32 14.327 32 32z"
-    />
+  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" className="fabric-boundaryIcon size-6 m-2">
+    <path fill="#808080" d="M64 32c0 17.673-14.327 32-32 32s-32-14.327-32-32 14.327-32 32-32 32 14.327 32 32z" />
     <path
       fill="#fff"
       d="M63.5 32c0 17.397-14.103 31.5-31.5 31.5s-31.5-14.103-31.5-31.5 14.103-31.5 31.5-31.5 31.5 14.103 31.5 31.5z"
     />
-    <path
-      fill="#f44336"
-      d="M60 32c0 15.464-12.536 28-28 28s-28-12.536-28-28c0-15.464 12.536-28 28-28s28 12.536 28 28z"
-    />
+    <path fill="#f44336" d="M60 32c0 15.464-12.536 28-28 28s-28-12.536-28-28c0-15.464 12.536-28 28-28s28 12.536 28 28z" />
     <path
       fill="#fff"
       d="M50.667 35.733h-37.333c-1.031 0-1.867-0.835-1.867-1.867v-3.733c0-1.031 0.835-1.867 1.867-1.867h37.333c1.031 0 1.867 0.835 1.867 1.867v3.733c0 1.031-0.835 1.867-1.867 1.867z"

package/src/core/content/Content.tsx

@@ -1,50 +1,40 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
- *
- *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
-import classNames from "classnames";
-import { type MouseEvent, useImperativeHandle } from "react";
+import { cn } from "@react-fabric/utilities";
+import { useImperativeHandle } from "react";
 import { useDebounce } from "../../hooks/useDebounce";
 import { useResizeObserver } from "../../hooks/useResizeObserver";
-import {
-  type ChildrenProp,
-  type CssProp,
-  type RefProp,
-  type ScrollObject,
-  type SizeObject,
-  type TestProps,
-} from "../../types";
+import type { ChildrenProp, CssProp, RefProp, ScrollObject, SizeObject, TestProps } from "../../types";
 import { ErrorBoundary } from "../boundary/ErrorBoundary";
-import classes from "./Content.module.css";
 
-export interface ContentProps
-  extends ChildrenProp,
-    CssProp,
-    RefProp,
-    TestProps {
+export interface ContentProps extends ChildrenProp, CssProp, RefProp<HTMLDivElement>, TestProps {
   /**
    * scroll vevent handler
    */
-  onScroll?: (scroll: ScrollObject, event: MouseEvent<HTMLDivElement>) => void;
+  onScroll?: (scroll: ScrollObject, event: React.MouseEvent<HTMLDivElement>) => void;
   /**
    * scroll vevent handler
    */
@@ -52,20 +42,21 @@ 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.
+ *
+ * @example
+ * ```tsx
+ * <Content onScroll={handleScroll} onResize={handleResize}>
+ *   <div>Child content</div>
+ * </Content>
+ * ```
  */
-export const Content = ({
-  ref,
-  children,
-  className,
-  onScroll,
-  onResize,
-  "data-testid": testId,
-  "data-test-value": testValue,
-}: ContentProps) => {
+export function Content({ ref, children, className, onScroll, onResize, ...props }: ContentProps) {
   const resizeHandle = useResizeObserver(onResize);
   const scrollHandler = useDebounce(
-    (e: MouseEvent<HTMLDivElement>) => {
+    (e: React.MouseEvent<HTMLDivElement>) => {
       const el = e.target as HTMLElement;
       onScroll?.(
         {
@@ -81,17 +72,17 @@ export const Content = ({
     },
     [onScroll],
   );
-  useImperativeHandle(ref, () => resizeHandle.current as AnyObject, []);
+  useImperativeHandle(ref, () => resizeHandle.current as HTMLDivElement);
   return (
     <section
       data-ref="content"
-      data-testid={testId}
-      data-test-value={testValue}
+      {...props}
+      aria-roledescription="content-pane"
       ref={resizeHandle}
       onScroll={scrollHandler}
-      className={classNames(classes.content, "area-content", className)}
+      className={cn("fabric-content", className, "area-content @container scrollbar-gutter-stable")}
     >
       <ErrorBoundary>{children}</ErrorBoundary>
     </section>
   );
-};
+}

package/src/core/headfoot/HeadFoot.tsx

@@ -1,114 +1,195 @@
-/*
+/**
  * React Fabric
- * @version: 1.0.0
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
  *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
  *
- * The MIT License (MIT)
- * Copyright (c) 2024 Adarsh Pastakia
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
  *
- * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
- * and associated documentation files (the "Software"), to deal in the Software without restriction,
- * including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
- * and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
- * subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all copies or substantial
- * portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
- * TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
- * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
- * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
  */
 
-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";
+import { cn } from "@react-fabric/utilities";
+import { Activity, useEffect, useLayoutEffect, useState } from "react";
+import { useGlobals } from "../../context/context";
+import { usePropToggle } from "../../hooks/usePropToggle";
+import { useResize } from "../../hooks/useResize";
+import type { ChildrenProp, CollapseProps, CssProp, HeightProps, TestProps } from "../../types";
+
+interface BaseProps extends CssProp, ChildrenProp, TestProps, CollapseProps, HeightProps {
+  flex?: boolean;
+  align?: "start" | "end" | "center" | "stretch";
+  justify?: "start" | "end" | "center" | "between";
+
+  id?: string;
+  hideCollapseHandle?: boolean;
 
-interface BaseProps extends CssProp, AriaProps, ChildrenProp, TestProps {
-  dir?: "ltr" | "rtl";
   /**
-   * background color
+   * resizable header/footer
    */
-  bg?: ColorWithGrays | string;
+  resizeable?: boolean;
+
   /**
-   * background color
+   * Resize event
    */
-  color?: ColorWithGrays | string;
+  onResize?: (height: number) => void;
 }
 
-type DefaultProps = BaseProps & { flex?: false };
-type FlexProps = BaseProps & {
+type DefaultProps = { flex?: false; align?: never; justify?: never };
+type FlexProps = {
   flex: true;
-  align?: "start" | "end" | "center" | "stretch";
-  justify?: "start" | "end" | "center" | "between";
 };
 
-export type HeadFootProps = DefaultProps | FlexProps;
+export type HeadFootProps = BaseProps & (DefaultProps | FlexProps);
 
-const HeadFoot = ({
+const ALIGN_MAP = {
+  start: "items-start",
+  end: "items-end",
+  center: "items-center",
+  stretch: "items-stretch",
+};
+
+const JUSTIFY_MAP = {
+  start: "justify-start",
+  end: "justify-end",
+  center: "justify-center",
+  between: "justify-between",
+};
+
+function HeadFoot({
   as: E,
+  id,
   children,
   className,
-  bg,
-  color,
   flex,
-  area,
-  dir,
+  height: ht,
+  maxHeight = "50vh",
+  minHeight = "10px",
+  collapsed: _collapsed,
+  collapsable,
+  resizeable,
   align = "center",
   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;
+  hideCollapseHandle,
+  onCollapse,
+  onResize,
+  ...props
+}: HeadFootProps & { as: "header" | "footer" }) {
+  const { registerArea, unregisterArea } = useGlobals();
+  const [height, setHeight] = useState<number>();
+  const [collapsed, onToggle] = usePropToggle(_collapsed, onCollapse);
+  const { ref, isResizing, onMouseDown } = useResize(
+    ({ y }) => {
+      setHeight((h = 0) => h + y);
+    },
+    {
+      isVertical: true,
+      isReverse: E === "footer",
+      onEnd() {
+        const height = (ref.current?.previousElementSibling as HTMLElement)?.offsetHeight;
+        setHeight(height);
+        onResize?.(height ?? 0);
+      },
     },
-    [bg],
-    "HeadFoot styles",
   );
+  useLayoutEffect(() => {
+    const height = (ref.current?.previousElementSibling as HTMLElement)?.offsetHeight;
+    if (resizeable && height > 0) {
+      const tmr = setTimeout(() => setHeight(height), 50);
+      return () => clearTimeout(tmr);
+    }
+  }, [ref, resizeable]);
+
+  useEffect(() => {
+    if (id) {
+      registerArea(id, (open) => {
+        onToggle(open);
+      });
+      return () => unregisterArea(id);
+    }
+    // eslint-disable-next-line @eslint-react/exhaustive-deps
+  }, [id]);
 
   return (
     <E
-      dir={dir}
-      className={classNames(
-        classes.headfoot,
-        className,
-        bg && getBgClass(bg),
-        color && getColorClass(color),
-        area === "head" ? "area-head" : "area-foot",
-        `leading-none`,
-        flex && "flex flex-nowrap gap-px",
-        align && `items-${align}`,
-        justify && `justify-${justify}`,
-      )}
-      style={styles}
-      {...aria}
+      {...props}
+      aria-roledescription={E === "header" ? "header-pane" : "footer-pane"}
+      className={cn("fabric-headfoot relative flex z-1", E === "header" ? "area-header flex-col" : "area-footer flex-col-reverse")}
     >
-      {children}
+      <Activity mode={collapsed ? "hidden" : "visible"}>
+        <div
+          className={cn(className, flex && "flex flex-nowrap", align && `${ALIGN_MAP[align]}`, justify && `${JUSTIFY_MAP[justify]}`)}
+          style={{
+            height: height ?? ht,
+            minHeight,
+            maxHeight,
+          }}
+        >
+          {children}
+        </div>
+        <div
+          ref={ref}
+          role="none"
+          data-ref="resize-handle"
+          onMouseDown={onMouseDown}
+          className={cn(
+            "relative",
+            resizeable && "before:absolute before:block before:top-0 before:left-1/2 before:-translate-x-1/2 before:content-['⋯'] before:leading-0",
+            "after:absolute after:transform-[width] after:border-solid after:border-t-2 after:w-0 after:m-auto after:inset-0 after:border-t-primary-500",
+            resizeable && "hover:after:duration-500 hover:after:w-full",
+            isResizing && "after:w-full",
+            collapsed && "pointer-events-none",
+            resizeable ? "h-1 cursor-row-resize bg-tint-50 border-y border-tint-300/50 -my-px" : "h-0 border-0 pointer-events-none",
+          )}
+        />
+      </Activity>
+      {collapsable && !hideCollapseHandle && (
+        <div
+          role="none"
+          className={cn(
+            "absolute z-1 w-16 h-2 leading-0 mx-auto inset-x-0",
+            "bg-dimmed text-dimmed outline outline-tint-200/50 text-center rounded-sm cursor-pointer pointer-events-auto",
+            E === "header" ? "rounded-t-none -bottom-2" : "rounded-b-none -top-2",
+            !collapsed && "opacity-70 hover:opacity-100",
+          )}
+          onMouseDown={(e) => e.stopPropagation()}
+          onClick={() => onToggle()}
+        >
+          <i
+            className={
+              "-mt-1 inline-block " + ((collapsed && E === "header") || (!collapsed && E === "footer") ? "icon-[mdi--chevron-down]" : "icon-[mdi--chevron-up]")
+            }
+          />
+        </div>
+      )}
     </E>
   );
-};
+}
 
-export const Header = (props: HeadFootProps) => (
-  <HeadFoot as="header" area="head" {...props} />
-);
+/**
+ * Header component wrapping children in a header element. Delegates to HeadFoot with `as="header"`.
+ */
+export function Header(props: HeadFootProps) {
+  return <HeadFoot as="header" data-ref="header" {...props} />;
+}
 
-export const Footer = (props: HeadFootProps) => (
-  <HeadFoot as="footer" area="foot" {...props} />
-);
+/**
+ * Footer component wrapping children in a footer element. Delegates to HeadFoot with `as="footer"`.
+ */
+export function Footer(props: HeadFootProps) {
+  return <HeadFoot as="footer" data-ref="footer" {...props} />;
+}

package/src/core/layout/Layout.tsx

@@ -0,0 +1,54 @@
+/**
+ * React Fabric
+ * @version 1.0.0
+ * @license MIT
+ * @copyright 2024 Adarsh Pastakia
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { cn } from "@react-fabric/utilities";
+import type { ChildrenProp, CssProp, RefProp } from "../../types";
+import { ErrorBoundary } from "../boundary/ErrorBoundary";
+
+/**
+ * A component that represents a layout 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.
+ *
+ * @example
+ * ```jsx
+ * <Layout className="my-layout" ref={layoutRef}>
+ *   <p>This is a layout.</p>
+ * </Layout>
+ * ```
+ */
+export function Layout({ children, className, ref, ...rest }: CssProp & ChildrenProp & RefProp<HTMLDivElement>) {
+  return (
+    <section
+      {...rest}
+      data-ref="layout"
+      ref={ref}
+      aria-roledescription="layout-panel"
+      className={cn("fabric-layout", className, "sectioned area-content overflow-hidden")}
+    >
+      <ErrorBoundary>{children}</ErrorBoundary>
+    </section>
+  );
+}