feat: add RowActions component for enhanced row-level actions in data grids

- Introduced RowActions component to manage row-level actions with tooltips and dropdown menus. - Created types for row actions and page actions to standardize action properties. - Implemented utility function to map action intents to Mantine theme colors. - Updated CoreAppShell component to support optional slots for better flexibility. - Added enterprise module structure with context hooks for managing module state and actions. - Implemented draft management for forms to enhance user experience during data entry. - Established context providers for detail, form, and index pages to streamline data handling. - Updated dependencies to ensure compatibility with the latest versions.
2026-07-01 17:04:20 +07:00
parent 1c2090f4fb
commit 8f14c4bc7b
60 changed files with 2188 additions and 442 deletions
@@ -0,0 +1,4 @@
+export * from './types';
+export * from './utils';
+export * from './page-actions';
+export * from './row-actions';
@@ -0,0 +1,150 @@
+import { memo, Fragment } from 'react';
+import { Group, Button, Menu, Divider, ActionIcon, Box } from '@mantine/core';
+import { ChevronDown, MoreVertical, X } from 'lucide-react';
+import { PageAction } from './types';
+import { getIntentColor } from './utils';
+
+export interface PageActionsProps {
+  /** Array of configured page-level actions. */
+  actions: PageAction[];
+  /** Optional callback triggered when the close (X) button is clicked. */
+  onClose?: () => void;
+}
+
+/**
+ * A responsive and flexible presentational component for page-level actions.
+ * Automatically adapts layout based on screen size:
+ * - Desktop: Renders a horizontal toolbar with buttons and dividers.
+ * - Mobile: Renders a single Menu dropdown containing all actions.
+ *
+ * @performance Wrapped in React.memo to prevent unnecessary re-renders.
+ */
+export const PageActions = memo(function PageActions({ actions }: PageActionsProps) {
+  return (
+    <Box style={{ display: 'inline-flex' }}>
+      {/* --- DESKTOP VIEW (hidden on mobile devices) --- */}
+      <Group gap="xs" wrap="nowrap" visibleFrom="sm">
+        {actions.map((action, index) => {
+          if (action.type === 'divider') {
+            return <Divider key={`divider-${index}`} orientation="vertical" mr="sm" ml="sm" />;
+          }
+
+          // Render Dropdown Menu for actions with children
+          if (action.children && action.children.length > 0) {
+            return (
+              <Menu key={action.key} position="bottom-start" withArrow withinPortal trigger="hover">
+                <Menu.Target>
+                  <Button
+                    variant={action.variant || 'transparent'}
+                    color={getIntentColor(action.intent)}
+                    leftSection={action.icon}
+                    rightSection={<ChevronDown size={14} />}
+                    disabled={action.disabled}
+                    size="xs"
+                    pr="sm"
+                    pl="sm"
+                  >
+                    {action.label}
+                  </Button>
+                </Menu.Target>
+                <Menu.Dropdown>
+                  {action.children.map((child, childIndex) => {
+                    if (child.type === 'divider') {
+                      return <Menu.Divider key={`child-divider-${childIndex}`} />;
+                    }
+                    return (
+                      <Menu.Item
+                        key={child.key}
+                        leftSection={child.icon}
+                        color={getIntentColor(child.intent)}
+                        disabled={child.disabled}
+                        onClick={() => child.onClick?.(child.key || '')}
+                      >
+                        {child.label}
+                      </Menu.Item>
+                    );
+                  })}
+                </Menu.Dropdown>
+              </Menu>
+            );
+          }
+
+          return (
+            <Button
+              key={action.key}
+              variant={action.variant || 'transparent'}
+              color={getIntentColor(action.intent)}
+              leftSection={action.icon}
+              disabled={action.disabled}
+              onClick={() => action.onClick?.(action.key || '')}
+              size="xs"
+              pr="sm"
+              pl="sm"
+            >
+              {action.label}
+            </Button>
+          );
+        })}
+      </Group>
+
+      {/* --- MOBILE VIEW (hidden on desktop devices) --- */}
+      <Group gap="xs" wrap="nowrap" hiddenFrom="sm">
+        <Menu position="bottom-end" withArrow withinPortal>
+          <Menu.Target>
+            <ActionIcon variant="transparent" size="md">
+              <MoreVertical size={16} />
+            </ActionIcon>
+          </Menu.Target>
+          <Menu.Dropdown>
+            {actions.map((action, index) => {
+              if (action.type === 'divider') {
+                return <Menu.Divider key={`mobile-divider-${index}`} mt="sm" mb="sm" />;
+              }
+
+              if (action.children && action.children.length > 0) {
+                return (
+                  <Fragment key={action.key}>
+                    <Menu.Label>{action.label}</Menu.Label>
+                    {action.children.map((child, childIndex) => {
+                      if (child.type === 'divider') {
+                        return <Menu.Divider key={`mobile-child-divider-${childIndex}`} mt="xs" mb="xs" />;
+                      }
+                      return (
+                        <Menu.Item
+                          key={child.key}
+                          leftSection={child.icon}
+                          color={getIntentColor(child.intent)}
+                          disabled={child.disabled}
+                          onClick={() => child.onClick?.(child.key || '')}
+                          style={{ paddingLeft: '1.5rem' }} // Indent nested items
+                          mt="sm"
+                          mb="sm"
+                        >
+                          {child.label}
+                        </Menu.Item>
+                      );
+                    })}
+                  </Fragment>
+                );
+              }
+
+              return (
+                <Menu.Item
+                  key={action.key}
+                  leftSection={action.icon}
+                  color={getIntentColor(action.intent)}
+                  disabled={action.disabled}
+                  onClick={() => action.onClick?.(action.key || '')}
+                  mt="sm"
+                  mb="sm"
+                >
+                  {action.label}
+                </Menu.Item>
+              );
+            })}
+          </Menu.Dropdown>
+        </Menu>
+      </Group>
+    </Box>
+  );
+});
@@ -0,0 +1,154 @@
+import { Fragment, memo } from 'react';
+import { Group, ActionIcon, Tooltip, Menu, Divider, Box, Button } from '@mantine/core';
+import { RowAction } from './types';
+import { getIntentColor } from './utils';
+import { MoreVertical } from 'lucide-react';
+
+export interface RowActionsProps {
+  /** Array of configured row-level actions. */
+  actions: RowAction[];
+  showLabels?: boolean;
+}
+
+/**
+ * A lightweight presentational component optimized for rendering inside data grid rows.
+ * Automatically handles tooltip generation and constructs dropdown menus for nested actions.
+ *
+ * @performance Wrapped in React.memo to guarantee zero overhead inside large lists/grids.
+ */
+export const RowActions = memo(function RowActions({ actions = [], showLabels = false }: RowActionsProps) {
+  /**
+   * Helper function to render a standalone icon button.
+   * Wraps the icon in a Tooltip if the configuration provides one.
+   */
+  const renderIcon = (action: RowAction, fallbackKey: string) => {
+    const actionKey = action.key || fallbackKey;
+
+    const iconBtn = (
+      <Button
+        key={action.key}
+        variant={'transparent'}
+        color={getIntentColor(action.intent)}
+        leftSection={action.icon}
+        disabled={action.disabled}
+        onClick={() => action.onClick?.(action.key || '')}
+        size="xs"
+        pr="xs"
+        pl="xs"
+        pt={0}
+        pb={0}
+      >
+        {showLabels && action.label}
+      </Button>
+    );
+
+    return action.tooltip ? (
+      <Tooltip key={`tooltip-${actionKey}`} label={action.tooltip} withArrow withinPortal>
+        {iconBtn}
+      </Tooltip>
+    ) : (
+      iconBtn
+    );
+  };
+
+  return (
+    <Box style={{ display: 'inline-flex' }}>
+      {/* --- DESKTOP VIEW (hidden on mobile devices) --- */}
+      <Group gap={0} wrap="nowrap" visibleFrom="sm">
+        {actions.map((action, index) => {
+          if (action.type === 'divider') {
+            return <Divider key={`divider-${index}`} orientation="vertical" mr="xs" ml="xs" />;
+          }
+
+          // Render Dropdown Menu for actions with children
+          if (action.children && action.children.length > 0) {
+            return (
+              <Menu key={action.key} position="bottom-start" withArrow withinPortal trigger="hover">
+                <Menu.Target>{renderIcon(action, `action-${index}`)}</Menu.Target>
+                <Menu.Dropdown>
+                  {action.children.map((child, childIndex) => {
+                    if (child.type === 'divider') {
+                      return <Menu.Divider key={`child-divider-${childIndex}`} />;
+                    }
+                    return (
+                      <Menu.Item
+                        key={child.key}
+                        leftSection={child.icon}
+                        color={getIntentColor(child.intent)}
+                        disabled={child.disabled}
+                        onClick={() => child.onClick?.(child.key || '')}
+                      >
+                        {child.label}
+                      </Menu.Item>
+                    );
+                  })}
+                </Menu.Dropdown>
+              </Menu>
+            );
+          }
+
+          return renderIcon(action, `action-${index}`);
+        })}
+      </Group>
+
+      {/* --- MOBILE VIEW (hidden on desktop devices) --- */}
+      <Group gap={0} wrap="nowrap" hiddenFrom="sm">
+        <Menu position="bottom-end" withArrow withinPortal>
+          <Menu.Target>
+            <ActionIcon variant="transparent" size="md">
+              <MoreVertical size={16} />
+            </ActionIcon>
+          </Menu.Target>
+          <Menu.Dropdown>
+            {actions.map((action, index) => {
+              if (action.type === 'divider') {
+                return <Menu.Divider key={`mobile-divider-${index}`} mt="sm" mb="sm" />;
+              }
+
+              if (action.children && action.children.length > 0) {
+                return (
+                  <Fragment key={action.key}>
+                    <Menu.Label>{action.label}</Menu.Label>
+                    {action.children.map((child, childIndex) => {
+                      if (child.type === 'divider') {
+                        return <Menu.Divider key={`mobile-child-divider-${childIndex}`} mt="xs" mb="xs" />;
+                      }
+                      return (
+                        <Menu.Item
+                          key={child.key}
+                          leftSection={child.icon}
+                          color={getIntentColor(child.intent)}
+                          disabled={child.disabled}
+                          onClick={() => child.onClick?.(child.key || '')}
+                          style={{ paddingLeft: '1.5rem' }} // Indent nested items
+                          mt="sm"
+                          mb="sm"
+                        >
+                          {child.label}
+                        </Menu.Item>
+                      );
+                    })}
+                  </Fragment>
+                );
+              }
+
+              return (
+                <Menu.Item
+                  key={action.key}
+                  leftSection={action.icon}
+                  color={getIntentColor(action.intent)}
+                  disabled={action.disabled}
+                  onClick={() => action.onClick?.(action.key || '')}
+                  mt="sm"
+                  mb="sm"
+                >
+                  {action.label}
+                </Menu.Item>
+              );
+            })}
+          </Menu.Dropdown>
+        </Menu>
+      </Group>
+    </Box>
+  );
+});
@@ -0,0 +1,57 @@
+import { ReactNode } from 'react';
+
+/**
+ * Defines the semantic intent of an action.
+ * The UI component will map these intents to specific theme colors
+ * (e.g., 'destructive' translates to red, 'success' translates to teal).
+ */
+export type ActionIntent = 'default' | 'success' | 'warning' | 'destructive' | 'primary';
+
+/**
+ * Base Action Entity.
+ * Contains fundamental properties shared across all action types within the system.
+ */
+export interface BaseAction {
+  /** Unique identifier for the action. Required for 'action', optional for 'divider'. */
+  key?: string;
+  /** Type of action. Use 'divider' to render a separator. Defaults to 'action'. */
+  type?: 'action' | 'divider';
+  /** Visual representation of the action. Optional for dividers. */
+  icon?: ReactNode;
+  /** Disables interaction if set to true. */
+  disabled?: boolean;
+
+  /** Semantic context to determine visual emphasis (color mapping). */
+  intent?: ActionIntent;
+  /** Callback triggered upon action execution. */
+  onClick?: (key: string) => void;
+}
+
+/**
+ * Page-Level Action Entity.
+ * Specifically designed for toolbars, page headers, or detailed forms.
+ * Enforces the presence of a text label (unless type is divider) and supports button-specific visual variants.
+ */
+export interface PageAction extends BaseAction {
+  /** Text label displayed on the button. Required for 'action' type. */
+  label?: string;
+  /** Specifies the Mantine button variant. Defaults to 'subtle'. */
+  variant?: 'filled' | 'light' | 'outline' | 'default' | 'subtle' | 'transparent';
+  /** Nested actions rendered as a Dropdown Menu below the main button. */
+  children?: PageAction[];
+}
+
+/**
+ * Row-Level Action Entity.
+ * Specifically optimized for dense areas like data grids or list items.
+ * Labels are optional (utilized inside dropdowns), supports hover tooltips,
+ * and allows nested action hierarchies (e.g., Kebab menus).
+ */
+export interface RowAction extends BaseAction {
+  /** Optional text, primarily used when rendered inside a nested menu item. */
+  label?: string;
+  /** Optional text displayed on hover. */
+  tooltip?: string;
+  /** Nested actions that will be rendered inside a dropdown menu. */
+  children?: RowAction[];
+}
@@ -0,0 +1,23 @@
+import { ActionIntent } from './types';
+
+/**
+ * Maps semantic intents to corresponding Mantine theme colors.
+ * Ensures consistent color application across different action components.
+ * * @param intent The semantic intent of the action.
+ * @returns A valid Mantine color string, or undefined to fallback to theme defaults.
+ */
+export const getIntentColor = (intent?: ActionIntent): string | undefined => {
+  switch (intent) {
+    case 'destructive':
+      return 'red';
+    case 'warning':
+      return 'yellow';
+    case 'success':
+      return 'teal';
+    case 'primary':
+      return undefined; // Default primary color
+
+    default:
+      return 'default'; // Fallback to theme default color if no intent is specified
+  }
+};
@@ -3,7 +3,6 @@ import { AppShell, Flex, Box, Button } from '@mantine/core';
 import { CoreAppShellProvider, useCoreAppShell } from './core-app-shell-context';
 import { CoreAppShellConfig, CoreAppShellSlots, CoreAppShellDimensions } from './types';

-
 const DEFAULT_DIMENSIONS: Required<CoreAppShellDimensions> = {
  utilityBarHeight: 32,
  headerHeight: 60,
@@ -14,12 +13,13 @@ const DEFAULT_DIMENSIONS: Required<CoreAppShellDimensions> = {
 };

 interface CoreAppShellInnerProps {
-  slots: CoreAppShellSlots;
+  slots?: CoreAppShellSlots;
  children: React.ReactNode;
 }

-function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
-  const { mobileOpened, desktopOpened, sidebarVariant, asideOpened, navbarPanelOpened, config, toggleMobile } = useCoreAppShell();
+function CoreAppShellInner({ slots = {}, children }: CoreAppShellInnerProps) {
+  const { mobileOpened, desktopOpened, sidebarVariant, asideOpened, navbarPanelOpened, config, toggleMobile } =
+    useCoreAppShell();
  const { variant, dimensions, features } = config;
  const dims = { ...DEFAULT_DIMENSIONS, ...dimensions };

@@ -27,7 +27,7 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
  const isTopNav = variant === 'top-nav';
  const isFooterOffset = variant === 'header-first';
  const isSidebarFirst = variant === 'sidebar-first';
-  
+
  // Calculate Navbar Width based on states
  const navbarWidth = useMemo(() => {
    let desktopWidth = dims.sidebarWidth;
@@ -46,13 +46,12 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {

  // Determine AppShell Layout
  const appShellLayout = variant === 'sidebar-first' ? 'alt' : 'default';
-  
+
  // Smart defaults for slots
  const showUtilityBar = (features?.withUtilityBar ?? Boolean(slots.utilityBar)) && Boolean(slots.utilityBar);
  const showAside = (features?.withAside ?? Boolean(slots.aside)) && Boolean(slots.aside);
  const showFooter = (features?.withFooter ?? Boolean(slots.footer)) && Boolean(slots.footer);

-  
  // Header height needs to account for utility bar if present
  const totalHeaderHeight = useMemo(() => {
    if (!showUtilityBar) return dims.headerHeight;
@@ -63,6 +62,7 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
    return `calc(${dims.headerHeight}${typeof dims.headerHeight === 'number' ? 'px' : ''} + ${dims.utilityBarHeight}${typeof dims.utilityBarHeight === 'number' ? 'px' : ''})`;
  }, [dims.headerHeight, dims.utilityBarHeight, showUtilityBar]);

+  console.log({ totalHeaderHeight, dimensions });
  return (
    <AppShell
      layout={appShellLayout}
@@ -74,7 +74,7 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
        breakpoint: 'sm',
        collapsed: {
          mobile: !mobileOpened,
-          desktop: isTopNav ? true : (features?.desktopCollapseVariant === 'hide' ? !desktopOpened : false),
+          desktop: isTopNav ? true : features?.desktopCollapseVariant === 'hide' ? !desktopOpened : false,
        },
      }}
      aside={
@@ -100,9 +100,7 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
              {slots.utilityBar}
            </Box>
          )}
-          <Box flex={1}>
-            {slots.header}
-          </Box>
+          <Box flex={1}>{slots.header}</Box>
        </Flex>
      </AppShell.Header>

@@ -121,12 +119,12 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
        <Box visibleFrom="sm" h="100%" display={isTopNav ? 'none' : undefined}>
          {isDoubleSidebar ? (
            <Flex h="100%" direction="row" wrap="nowrap">
-              <Box 
-                w={dims.sidebarRailWidth} 
-                h="100%" 
-                style={{ 
+              <Box
+                w={dims.sidebarRailWidth}
+                h="100%"
+                style={{
                  flexShrink: 0,
-                  borderRight: '1px solid var(--mantine-color-default-border)' 
+                  borderRight: '1px solid var(--mantine-color-default-border)',
                }}
              >
                {slots.sidebarRail}
@@ -143,15 +141,13 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
        </Box>
        <Box hiddenFrom="sm" h="100%">
          <Flex direction="column" h="100%">
-            {
-              isSidebarFirst && (
-                <Box p="md" style={{ borderTop: '1px solid var(--mantine-color-default-border)' }}>
-                  <Button fullWidth variant="default" onClick={toggleMobile}>
-                    Close
-                  </Button>
-                </Box>
-              )
-            }
+            {isSidebarFirst && (
+              <Box p="md" style={{ borderTop: '1px solid var(--mantine-color-default-border)' }}>
+                <Button fullWidth variant="default" onClick={toggleMobile}>
+                  Close
+                </Button>
+              </Box>
+            )}
            <Box flex={1} style={{ overflowY: 'auto' }}>
              {slots.sidebarMobile || slots.sidebar}
            </Box>
@@ -175,9 +171,7 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {
        </AppShell.Aside>
      )}

-      <AppShell.Main>
-        {children}
-      </AppShell.Main>
+      <AppShell.Main>{children}</AppShell.Main>

      {showFooter && (
        <AppShell.Footer
@@ -204,16 +198,14 @@ function CoreAppShellInner({ slots, children }: CoreAppShellInnerProps) {

 export interface CoreAppShellProps {
  config: CoreAppShellConfig;
-  slots: CoreAppShellSlots;
+  slots?: CoreAppShellSlots;
  children: React.ReactNode;
 }

 export function CoreAppShell({ config, slots, children }: CoreAppShellProps) {
  return (
    <CoreAppShellProvider config={config}>
-      <CoreAppShellInner slots={slots}>
-        {children}
-      </CoreAppShellInner>
+      <CoreAppShellInner slots={slots}>{children}</CoreAppShellInner>
    </CoreAppShellProvider>
  );
 }
@@ -10,3 +10,4 @@ export * from './system-pages/forbidden';
 export * from './system-pages/maintenance';
 export * from './system-pages/not-found';
 export * from './core-app-shell';
+export * from './actions-tools';