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
+  }
+};