@react-fabric/core 1.0.0-beta.9 → 1.0.2

package/src/components/panel/Panel.tsx

@@ -21,53 +21,30 @@
  * 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 { useMemo } from "react";
-import { type ContentProps } from "../../core/content/Content";
-import { type HeadFootProps } from "../../core/headfoot/HeadFoot";
+import { cn } from "@react-fabric/utilities";
+import { useHotkeySequences } from "@tanstack/react-hotkeys";
+import { Activity, useMemo } from "react";
+import type { ContentProps } from "../../core/content/Content";
+import type { HeadFootProps } from "../../core/headfoot/HeadFoot";
 import { usePropToggle } from "../../hooks/usePropToggle";
-import {
-  type AriaProps,
-  type ChildrenProp,
-  type CollapseProps,
-  type CssProp,
-  type ExpandProps,
-  type IconProps,
-  type TestProps,
-} from "../../types";
-import { CoreIcons } from "../../types/icons";
-import { Loading } from "../animations/Animations";
+import type { ChildrenProp, CollapseProps, CssPropWithMap, ExpandProps, TestProps } from "../../types";
+import { LoadingLine } from "../animations/LoadingLine";
 import { Icon } from "../icon/Icon";
-import classes from "./Panel.module.css";
+import type { TitlebarProps } from "../titlebar/Titlebar";
+import { Titlebar } from "../titlebar/Titlebar";
 
 export interface PanelProps
-  extends CssProp,
-    AriaProps,
+  extends
+    CssPropWithMap<{ root: string; body?: string; titlebar?: string; title?: string; icon?: string }>,
     TestProps,
-    IconProps,
     ExpandProps,
     CollapseProps,
+    TitlebarProps,
     ChildrenProp<HeadFootProps | ContentProps> {
   /**
    * panel id used by panel stack
    */
-  panelId?: string;
-  /**
-   * panel title
-   */
-  title?: string;
-  /**
-   * header actions
-   */
-  actions?: JSX.Element;
-  /**
-   * header css classname(s)
-   */
-  headerClassName?: string;
-  /**
-   * title css classname(s)
-   */
-  titleClassName?: string;
+  panelId?: string | number;
   /**
    * loading state
    */
@@ -102,17 +79,43 @@ export interface PanelProps
   onClose?: () => void;
 }
 
-export const Panel = ({
+/**
+ * A component that represents a panel with a header, body, and optional actions.
+ * It supports expandable and collapsible functionality, loading state, and customizable styles.
+ * The panel can be resized and has a fixed position when expanded.
+ * It can be customized with different colors, icons, and behaviors.
+ * This component is useful for displaying content in a structured way, allowing users to interact with it through actions and toggles.
+ * It can be used in various applications where panels are needed, such as dashboards, settings pages, or content management systems.
+ *
+ * @example
+ * ```jsx
+ * <Panel
+ *   title="Panel Title"
+ *   icon="icon-[mdi--info]"
+ *   actions={<button>Action</button>}
+ *   expandable
+ *   collapsable
+ *   onExpand={() => console.log("Expanded")}
+ *   onCollapse={() => console.log("Collapsed")}
+ *   onClose={() => console.log("Closed")}
+ *   height="400px"
+ *   width="300px"
+ *   minHeight="200px"
+ *   minWidth="200px"
+ *   maxHeight="600px"
+ *   maxWidth="600px"
+ * >
+ *   <p>This is the content of the panel.</p>
+ * </Panel>
+ * ```
+ */
+export function Panel({
   children,
   className,
-  titleClassName,
-  headerClassName,
+  classNames,
   title,
   actions,
   icon,
-  iconBg,
-  iconColor,
-  rtlFlip,
   panelId,
   height,
   width,
@@ -131,25 +134,26 @@ export const Panel = ({
   // @ts-expect-error ignore
   onBack,
   ...aria
-}: PanelProps) => {
-  const [collapsed, toggleCollapse] = usePropToggle(
-    _collapsed,
-    onCollapse,
-    panelId,
-  );
+}: PanelProps) {
+  const [collapsed, toggleCollapse] = usePropToggle(_collapsed, onCollapse, panelId);
   const [expanded, toggleExpand] = usePropToggle(_expanded, onExpand, panelId);
 
   const hasTools = useMemo(() => {
     return !!expandable || !!collapsable || !!onClose;
   }, [expandable, collapsable, onClose]);
 
+  useHotkeySequences([
+    { sequence: ["Escape"], callback: () => toggleExpand(), options: { enabled: expanded, conflictBehavior: "allow" } },
+  ]);
+
   return (
     <div
-      className={classNames(
-        classes.panel,
+      className={cn(
+        "fabric-panel",
         className,
-        "rounded-capped overflow-hidden outline grid",
+        "rounded-capped overflow-hidden outline grid group",
         expanded ? "fixed inset-4 z-50" : "relative",
+        !collapsed && "not-last:border-b",
       )}
       data-ref="panel"
       data-collapsed={collapsed}
@@ -169,88 +173,76 @@ export const Panel = ({
       }
       {...aria}
     >
-      <header
-        role="none"
-        className={classNames(
-          classes.panelHeader,
-          headerClassName,
-          "flex flex-nowrap items-center area-head",
-        )}
-        data-testid="panel-header"
-        onClick={collapsable ? toggleCollapse : undefined}
-      >
-        {onBack && (
-          <Icon
-            data-ref="panelBack"
-            className={classNames(classes.panelAction, "cursor-pointer")}
-            icon={CoreIcons.chevronLeft}
-            onClick={onBack}
-          />
-        )}
-        {icon && (
-          <Icon
-            icon={icon}
-            bg={iconBg}
-            color={iconColor}
-            rtlFlip={rtlFlip}
-            className="p-2 text-md select-none pointer-events-none"
-          />
-        )}
-        <div
-          className={classNames(
-            titleClassName,
-            "flex-1 select-none truncate",
-            title && "py-1 first:px-2",
-          )}
-        >
-          {title}
-        </div>
-        <div className="px-1">{actions}</div>
-        {hasTools && (
-          <div
-            role="none"
-            className="px-1 gap-px flex"
-            onClick={(e) => e.stopPropagation()}
-          >
-            {expandable && (
-              <Icon
-                data-ref="panelExpand"
-                className={classNames(classes.panelAction, "cursor-pointer")}
-                icon={expanded ? CoreIcons.minimize : CoreIcons.maximize}
-                onClick={toggleExpand}
-              />
+      <Titlebar
+        title={title}
+        icon={icon}
+        onClick={() => toggleCollapse()}
+        prepend={
+          !!onBack && (
+            <Icon
+              rtlFlip
+              data-ref="panelBack"
+              className={cn("fabric-panelAction", "cursor-pointer pointer-events-auto")}
+              icon="icon-[mdi--chevron-left]"
+              // @ts-expect-error ignore
+              // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+              onClick={onBack}
+            />
+          )
+        }
+        actions={
+          <>
+            {actions}
+            {hasTools && (
+              <div role="none" className="px-1 gap-px flex" onClick={(e) => e.stopPropagation()}>
+                {expandable && (
+                  <button
+                    type="button"
+                    className="size-fit cursor-pointer leading-none outline-none"
+                    onClick={() => toggleExpand()}
+                  >
+                    <Icon
+                      data-ref="panelExpand"
+                      className={cn("fabric-panelAction", "cursor-pointer pointer-events-auto")}
+                      icon={expanded ? "icon-[mdi--fullscreen-exit]" : "icon-[mdi--fullscreen]"}
+                    />
+                  </button>
+                )}
+                {!expanded && collapsable && (
+                  <button
+                    type="button"
+                    className="size-fit cursor-pointer leading-none outline-none"
+                    onClick={() => toggleCollapse()}
+                  >
+                    <Icon
+                      data-ref="panelCollapse"
+                      className={cn("fabric-panelAction", "cursor-pointer pointer-events-auto")}
+                      icon={collapsed ? "icon-[mdi--plus-box-outline]" : "icon-[mdi--minus-box-outline]"}
+                    />
+                  </button>
+                )}
+                {!expanded && onClose && (
+                  <button type="button" className="size-fit cursor-pointer leading-none outline-none" onClick={() => onClose()}>
+                    <Icon
+                      data-ref="panelClose"
+                      className={cn("fabric-panelAction", "cursor-pointer pointer-events-auto")}
+                      icon="icon-[mdi--close]"
+                    />
+                  </button>
+                )}
+              </div>
             )}
-            {!expanded && collapsable && (
-              <Icon
-                data-ref="panelCollapse"
-                className={classNames(classes.panelAction, "cursor-pointer")}
-                icon={collapsed ? CoreIcons.expand : CoreIcons.collapse}
-                onClick={toggleCollapse}
-              />
-            )}
-            {!expanded && onClose && (
-              <Icon
-                data-ref="panelClose"
-                className={classNames(classes.panelAction, "cursor-pointer")}
-                icon={CoreIcons.close}
-                onClick={onClose}
-              />
-            )}
-          </div>
-        )}
-      </header>
-      {(!collapsed || expanded) && (
-        <div
-          data-testid="panel-body"
-          className={classNames(
-            classes.panelBody,
-            "area-content grid overflow-hidden",
-          )}
-        >
-          {loading && <Loading />}
+          </>
+        }
+        className={cn(classNames?.titlebar)}
+        classNames={classNames}
+      />
+      <Activity mode={!collapsed || expanded ? "visible" : "hidden"}>
+        <div data-ref="panelBody" className={cn("fabric-panelBody", classNames?.body, "area-content grid overflow-hidden")}>
+          {loading && <LoadingLine />}
           {children}
         </div>
-      )}
+      </Activity>
     </div>
   );
-};
+}

package/src/components/panel/PanelGroup.tsx

@@ -21,14 +21,12 @@
  * 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 { Children, cloneElement, useCallback, useState } from "react";
-import {
-  useEffectDebugger,
-  useMemoDebugger,
-} from "../../hooks/useEffectDebugger";
-import { type ChildrenProp } from "../../types";
-import classes from "./Panel.module.css";
+import { cn } from "@react-fabric/utilities";
+import { Children, cloneElement, isValidElement, useState } from "react";
+import { useEffectDebugger, useMemoDebugger } from "../../hooks/useEffectDebugger";
+import type { ChildrenProp } from "../../types";
+import { cloneChildren } from "../../utils";
+import type { PanelProps } from "./Panel";
 
 export interface PanelGroupProps extends ChildrenProp {
   /**
@@ -38,20 +36,36 @@ export interface PanelGroupProps extends ChildrenProp {
   /**
    * active change callback
    */
-  onActiveChange?: (panelId: string) => void;
+  onActiveChange?: (panelId: string | number) => void;
 }
 
-export const PanelGroup = ({
-  children,
-  activePanel,
-  onActiveChange,
-}: PanelGroupProps) => {
-  const [expandedPanel, setExpandedPanel] = useState<string>();
+/**
+ * A component that groups multiple panels together, allowing for one panel to be expanded at a time.
+ * This component allows you to manage a group of panels where only one can be expanded at a time.
+ * It accepts an `activePanel` prop to control which panel is currently expanded,
+ * and an `onActiveChange` callback that is triggered when the active panel changes.
+ * It uses the `Panel` component to render each individual panel within the group.
+ *
+ * @example
+ * ```jsx
+ * <PanelGroup
+ *   activePanel="panel1"
+ *   onActiveChange={(panelId) => console.log(`Active panel changed to: ${panelId}`)}
+ * >
+ *   <Panel panelId="panel1" title="Panel 1">Content for Panel 1</Panel>
+ *   <Panel panelId="panel2" title="Panel 2">Content for Panel 2</Panel>
+ *   <Panel panelId="panel3" title="Panel 3">Content for Panel 3</Panel>
+ * </PanelGroup>
+ * ```
+ */
+export function PanelGroup({ children, activePanel, onActiveChange }: PanelGroupProps) {
+  const [expandedPanel, setExpandedPanel] = useState<string | number>();
 
   const panels = useMemoDebugger(
     () =>
+      // eslint-disable-next-line @eslint-react/no-children-to-array
       Children.toArray(children).map(
-        (child: AnyObject, index: number) => child.props.panelId || index,
+        (child, index: number) => (isValidElement<{ panelId: string }>(child) ? child.props?.panelId : "") || index,
       ),
     [children],
     "PanelGroup children",
@@ -65,35 +79,27 @@ export const PanelGroup = ({
     "PanelGroup setActive",
   );
 
-  const changeExpanded = useCallback(
-    (collapsed: boolean, id: string, handler?: AnyObject) => {
-      if (!collapsed) {
-        setExpandedPanel(id);
-        onActiveChange?.(id);
-      }
-      handler?.(collapsed);
-      return id !== expandedPanel;
-    },
-    [onActiveChange, expandedPanel],
-  );
+  const changeExpanded = (collapsed: boolean, id: string | number, handler?: (args: boolean) => void) => {
+    if (!collapsed) {
+      setExpandedPanel(id);
+      onActiveChange?.(id);
+    }
+    handler?.(collapsed);
+    return id !== expandedPanel;
+  };
 
   return (
-    <div
-      data-ref="panelGroup"
-      className={classNames(
-        classes.panelGroup,
-        "flex flex-col overflow-auto area-content p-px",
-      )}
-    >
-      {Children.toArray(children).map((child: AnyObject, index: number) =>
-        cloneElement(child, {
-          panelId: child.props.panelId || index,
+    <div data-ref="panelGroup" className={cn("fabric-panelGroup", "flex flex-col overflow-auto scroll-thin area-content p-px")}>
+      {cloneChildren(children)?.map((child, index: number) => {
+        const childEl = child as React.ReactElement<PanelProps>;
+        const id = childEl.props.panelId || index;
+        return cloneElement(childEl, {
+          panelId: id,
           collapsable: true,
-          onCollapse: (b: boolean, id: string) =>
-            changeExpanded(b, id, child.props.onCollapse),
-          collapsed: expandedPanel !== (child.props.panelId || index),
-        }),
-      )}
+          onCollapse: (b: boolean) => changeExpanded(b, id, childEl.props.onCollapse),
+          collapsed: expandedPanel !== (childEl.props.panelId || index),
+        });
+      })}
     </div>
   );
-};
+}

package/src/components/panel/PanelStack.tsx

@@ -21,18 +21,9 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
-import {
-  Children,
-  cloneElement,
-  type MouseEvent,
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-  useTransition,
-} from "react";
-import { type ChildrenProp, type CssProp } from "../../types";
+import { Children, cloneElement, isValidElement, useEffect, useMemo, useRef, useState, useTransition } from "react";
+import type { ChildrenProp, CssProp } from "../../types";
+import type { PanelProps } from "./Panel";
 
 export interface PanelStackProps extends CssProp, ChildrenProp {
   /**
@@ -49,14 +40,33 @@ export interface PanelStackProps extends CssProp, ChildrenProp {
   onBack?: (panelId: string, nextPanelId: string) => boolean | undefined;
 }
 
-export const PanelStack = ({
-  active,
-  children,
-  className,
-  onPanelChange,
-  onBack,
-  ...rest
-}: PanelStackProps) => {
+/**
+ * A component that manages a stack of panels, allowing navigation between them.
+ * This component allows you to manage a stack of panels where you can navigate between them.
+ * It accepts an `active` prop to control which panel is currently active,
+ * an `onPanelChange` callback that is triggered when the active panel changes,
+ * and an `onBack` callback to handle navigation to the previous panel in the history.
+ * It uses the `Panel` component to render each individual panel within the stack.
+ * The component maintains a history of panels to allow back navigation,
+ * and it updates the active panel based on user interactions.
+ *
+ * @example
+ * ```jsx
+ * <PanelStack
+ *   active="panel1"
+ *   onPanelChange={(panelId) => console.log(`Active panel changed to: ${panelId}`)}
+ *   onBack={(currentPanel, nextPanel) => {
+ *     console.log(`Navigating back from ${currentPanel} to ${nextPanel}`);
+ *     return true; // return false to prevent navigation
+ *   }}
+ * >
+ *   <Panel panelId="panel1" title="Panel 1">Content for Panel 1</Panel>
+ *   <Panel panelId="panel2" title="Panel 2">Content for Panel 2</Panel>
+ *   <Panel panelId="panel3" title="Panel 3">Content for Panel 3</Panel>
+ * </PanelStack>
+ * ```
+ */
+export function PanelStack({ children, className, onPanelChange, onBack, ...rest }: PanelStackProps) {
   const stackRef = useRef<HTMLDivElement>(null);
   const [history, setHistory] = useState<string[]>([]);
   const [, startTransition] = useTransition();
@@ -64,10 +74,16 @@ export const PanelStack = ({
   const panels = useMemo(
     () =>
       new Map(
-        Children.toArray(children).map(
-          (child: AnyObject) =>
-            child.props && [child.props.panelId ?? "root", child],
-        ),
+        // eslint-disable-next-line @eslint-react/no-children-to-array
+        Children.toArray(children)
+          // @ts-expect-error ignore
+          .map<[idx: string | number, React.ReactElement<PanelProps>]>((child) => {
+            if (isValidElement(child)) {
+              const childEl = child as React.ReactElement<PanelProps>;
+              return [childEl.props.panelId ?? "root", childEl];
+            }
+          })
+          .filter(Boolean),
       ),
     [children],
   );
@@ -75,59 +91,44 @@ export const PanelStack = ({
   useEffect(() => {
     startTransition(() => {
       onPanelChange?.(history[0] ?? "root");
-      stackRef.current?.dispatchEvent(
-        new Event("updatePopper", { bubbles: true }),
-      );
+      stackRef.current?.dispatchEvent(new Event("updatePopper", { bubbles: true }));
     });
   }, [onPanelChange, history]);
 
-  const goBack = useCallback(() => {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
+  const goBack = () => {
     if (onBack?.(history[0], history[1] ?? "root") !== false) {
       setHistory(history.slice(1));
     }
-  }, [history, onBack]);
+  };
 
-  const currentPanel = useMemo<AnyObject>(
-    () => panels.get(history[0]) ?? panels.values().next().value,
-    [history, panels],
-  );
+  const currentPanel = useMemo(() => panels.get(history[0]) ?? panels.values().next().value, [history, panels]);
 
-  const checkMenuClick = useCallback(
-    (e: MouseEvent) => {
-      const panelKey = (e.target as HTMLElement)?.dataset?.panel;
-      if (panelKey) {
-        if (panelKey === "back") {
-          goBack();
-        } else if (panelKey === "root") {
-          // eslint-disable-next-line @typescript-eslint/no-unnecessary-boolean-literal-compare
-          if (onBack?.(history[0], "root") !== false) {
-            setHistory([]);
-          }
-        } else if (panels.has(panelKey)) {
-          setHistory([panelKey, ...history]);
+  const checkMenuClick = (e: React.MouseEvent) => {
+    const panelKey = (e.target as HTMLElement)?.dataset?.panel;
+    if (panelKey) {
+      if (panelKey === "back") {
+        goBack();
+      } else if (panelKey === "root") {
+        if (onBack?.(history[0], "root") !== false) {
+          setHistory([]);
         }
-        e.stopPropagation();
-        e.preventDefault();
-        return false;
+      } else if (panels.has(panelKey)) {
+        setHistory([panelKey, ...history]);
       }
-      return true;
-    },
-    [goBack, history, panels, onBack],
-  );
+      e.stopPropagation();
+      e.preventDefault();
+      return false;
+    }
+    return true;
+  };
 
   return (
-    <div
-      {...rest}
-      role="none"
-      ref={stackRef}
-      className={className}
-      onClickCapture={checkMenuClick}
-    >
+    <div {...rest} role="none" ref={stackRef} className={className} onClickCapture={checkMenuClick}>
       {currentPanel &&
         cloneElement(currentPanel, {
+          // @ts-expect-error ignore
           onBack: history.length > 0 ? goBack : undefined,
         })}
     </div>
   );
-};
+}