@12-apps/ui 1.0.0

package/src/components/layout/Dashboard/DashboardParts.tsx

@@ -0,0 +1,216 @@
+'use client';
+
+import {
+  Close as CloseIcon,
+  ExpandMore as ExpandMoreIcon,
+  FileDownloadOutlined as ExportIcon,
+  FilterListRounded as FilterIcon,
+  InfoOutlined as InfoIcon,
+  SettingsOutlined as SettingsIcon,
+} from '@mui/icons-material';
+import {
+  Badge,
+  Box,
+  Button,
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  IconButton,
+  Menu,
+  MenuItem,
+  Popover,
+  Tooltip,
+  Typography,
+} from '@mui/material';
+import React, { useState } from 'react';
+
+import { useDashboardContext } from './DashboardContext';
+import type {
+  DashboardActionProps,
+  DashboardExportFormat,
+  DashboardExportProps,
+  DashboardFilterToggleProps,
+  DashboardInfoProps,
+  DashboardSettingsProps,
+} from './Dashboard.types';
+
+/** Flexible spacer — everything composed after it is pushed to the right. */
+export const DashboardSpacer = (): React.JSX.Element => <Box sx={{ flex: 1 }} aria-hidden />;
+DashboardSpacer.displayName = 'Dashboard.Spacer';
+
+export const DashboardInfo = ({
+  title = 'About this page',
+  children,
+  ariaLabel = 'Page information',
+}: DashboardInfoProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  const [anchorEl, setAnchorEl] = useState<HTMLButtonElement | null>(null);
+  const open = Boolean(anchorEl);
+  return (
+    <>
+      <Tooltip title={ariaLabel}>
+        <IconButton
+          size="small"
+          aria-label={ariaLabel}
+          aria-haspopup="dialog"
+          onClick={(e) => setAnchorEl(e.currentTarget)}
+          data-testid={`${testIdPrefix}-info-trigger`}
+          sx={{ color: 'text.secondary' }}
+        >
+          <InfoIcon fontSize="small" />
+        </IconButton>
+      </Tooltip>
+      <Popover
+        open={open}
+        anchorEl={anchorEl}
+        onClose={() => setAnchorEl(null)}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'left' }}
+        slotProps={{ paper: { sx: { width: 360, maxWidth: '90vw' } } }}
+        data-testid={`${testIdPrefix}-info-popover`}
+      >
+        <Box sx={{ px: 2, py: 1.5, borderBottom: 1, borderColor: 'divider', display: 'flex', gap: 1, alignItems: 'center' }}>
+          <InfoIcon fontSize="small" sx={{ color: 'text.secondary' }} />
+          <Typography sx={{ fontWeight: 600 }}>{title}</Typography>
+        </Box>
+        <Box sx={{ px: 2, py: 1.5, fontSize: '0.875rem', color: 'text.secondary' }}>{children}</Box>
+      </Popover>
+    </>
+  );
+};
+DashboardInfo.displayName = 'Dashboard.Info';
+
+export const DashboardFilterToggle = ({ ariaLabel }: DashboardFilterToggleProps): React.JSX.Element => {
+  const { filtersVisible, toggleFilters, activeFilterCount, testIdPrefix } = useDashboardContext();
+  const label = ariaLabel ?? (filtersVisible ? 'Hide filters' : 'Show filters');
+  return (
+    <Tooltip title={label}>
+      <IconButton
+        size="small"
+        aria-label={label}
+        aria-pressed={filtersVisible}
+        onClick={toggleFilters}
+        data-testid={`${testIdPrefix}-filter-toggle`}
+        sx={{ color: filtersVisible ? 'primary.main' : 'text.secondary', bgcolor: filtersVisible ? 'action.selected' : 'transparent' }}
+      >
+        <Badge badgeContent={activeFilterCount} color="primary" overlap="circular">
+          <FilterIcon fontSize="small" />
+        </Badge>
+      </IconButton>
+    </Tooltip>
+  );
+};
+DashboardFilterToggle.displayName = 'Dashboard.FilterToggle';
+
+export const DashboardSettings = ({
+  title = 'Settings',
+  children,
+  ariaLabel = 'Settings',
+  href,
+  linkComponent,
+}: DashboardSettingsProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  const [open, setOpen] = useState(false);
+
+  // Link mode: the gear navigates to a settings route (e.g. the page's
+  // Configuração section) instead of opening an in-page dialog.
+  if (href) {
+    const LinkComponent = linkComponent ?? 'a';
+    return (
+      <Tooltip title={ariaLabel}>
+        <IconButton
+          size="small"
+          aria-label={ariaLabel}
+          component={LinkComponent}
+          href={href}
+          data-testid={`${testIdPrefix}-settings-trigger`}
+          sx={{ color: 'text.secondary' }}
+        >
+          <SettingsIcon fontSize="small" />
+        </IconButton>
+      </Tooltip>
+    );
+  }
+
+  return (
+    <>
+      <Tooltip title={ariaLabel}>
+        <IconButton
+          size="small"
+          aria-label={ariaLabel}
+          aria-haspopup="dialog"
+          onClick={() => setOpen(true)}
+          data-testid={`${testIdPrefix}-settings-trigger`}
+          sx={{ color: 'text.secondary' }}
+        >
+          <SettingsIcon fontSize="small" />
+        </IconButton>
+      </Tooltip>
+      <Dialog open={open} onClose={() => setOpen(false)} maxWidth="sm" fullWidth data-testid={`${testIdPrefix}-settings-dialog`}>
+        <DialogTitle sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+          {title}
+          <IconButton aria-label="Close" size="small" onClick={() => setOpen(false)}>
+            <CloseIcon fontSize="small" />
+          </IconButton>
+        </DialogTitle>
+        <DialogContent dividers>{children}</DialogContent>
+      </Dialog>
+    </>
+  );
+};
+DashboardSettings.displayName = 'Dashboard.Settings';
+
+const DEFAULT_EXPORT_FORMATS: DashboardExportFormat[] = [
+  { id: 'csv', label: 'CSV (.csv)' },
+  { id: 'xlsx', label: 'Excel (.xlsx)' },
+  { id: 'json', label: 'JSON (.json)' },
+];
+
+export const DashboardExport = ({
+  formats = DEFAULT_EXPORT_FORMATS,
+  onExport,
+  label = 'Export',
+}: DashboardExportProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+  const open = Boolean(anchorEl);
+  return (
+    <>
+      <Button
+        variant="outlined"
+        size="medium"
+        color="inherit"
+        startIcon={<ExportIcon fontSize="small" />}
+        endIcon={<ExpandMoreIcon fontSize="small" />}
+        onClick={(e) => setAnchorEl(e.currentTarget)}
+        aria-haspopup="menu"
+        aria-expanded={open}
+        data-testid={`${testIdPrefix}-export-trigger`}
+        // Match the sibling primary action button (repo Button `md`): same
+        // padding/height and a 1rem non-uppercased label.
+        sx={{ py: 1, px: 2, fontSize: '1rem', textTransform: 'none' }}
+      >
+        {label}
+      </Button>
+      <Menu anchorEl={anchorEl} open={open} onClose={() => setAnchorEl(null)} data-testid={`${testIdPrefix}-export-menu`}>
+        {formats.map((format) => (
+          <MenuItem
+            key={format.id}
+            onClick={() => {
+              onExport(format.id);
+              setAnchorEl(null);
+            }}
+            data-testid={`${testIdPrefix}-export-${format.id}`}
+          >
+            {format.label}
+          </MenuItem>
+        ))}
+      </Menu>
+    </>
+  );
+};
+DashboardExport.displayName = 'Dashboard.Export';
+
+export const DashboardAction = ({ children }: DashboardActionProps): React.JSX.Element => (
+  <Box sx={{ display: 'inline-flex' }}>{children}</Box>
+);
+DashboardAction.displayName = 'Dashboard.Action';

package/src/components/layout/Dashboard/index.ts

@@ -0,0 +1,18 @@
+export { Dashboard } from './Dashboard';
+export { DashboardContext, useDashboardContext } from './DashboardContext';
+export type { DashboardContextValue } from './DashboardContext';
+export type {
+  DashboardActionProps,
+  DashboardBodyProps,
+  DashboardBreadcrumbItem,
+  DashboardBreadcrumbProps,
+  DashboardExportFormat,
+  DashboardExportProps,
+  DashboardFiltersProps,
+  DashboardFilterToggleProps,
+  DashboardHeaderProps,
+  DashboardInfoProps,
+  DashboardMoreFiltersProps,
+  DashboardProps,
+  DashboardSettingsProps,
+} from './Dashboard.types';

package/src/components/layout/Dashboard/tests.md

@@ -0,0 +1,46 @@
+# Dashboard Test Status Tracking
+
+## Test Files Status
+
+- [x] Dashboard.test.stories.tsx created
+- [x] Core interaction categories implemented
+
+## Storybook Tests Status
+
+### Test Results
+
+| Test Name                       | Status  | Pass/Fail | Notes                                   |
+| ------------------------------- | ------- | --------- | --------------------------------------- |
+| Filter toggle shows/hides       | Pending | -         | Toggles `Dashboard.Filters` visibility  |
+| Info popover opens              | Pending | -         | `[i]` opens page-summary popover        |
+| Settings gear opens dialog      | Pending | -         | Gear opens dialog (in-dev placeholder)  |
+| Export menu invokes handler     | Pending | -         | CSV item calls `onExport('csv')`        |
+| More filters expands panel      | Pending | -         | Advanced range panel toggles            |
+| Order-independent rendering     | Pending | -         | Slot order enforced regardless of JSX   |
+
+Legend: Pending | Running | PASS | FAIL
+
+## Static Stories Status
+
+- [x] FullComposition story
+- [x] HeaderOnly (opt-out of filters/breadcrumb)
+- [x] WithoutFilters
+- [x] OrderIndependent authoring
+
+## Lint Status
+
+- [ ] No lint errors
+- [ ] No warnings
+
+## TypeCheck Status
+
+- [ ] No type errors
+- [ ] All props properly typed
+
+## Overall Component Status
+
+- [ ] All tests passing
+- [ ] Lint clean
+- [ ] TypeCheck clean
+- [ ] Stories working
+- [ ] Ready for production

package/src/components/layout/Dashboard/track.md

@@ -0,0 +1,50 @@
+# Dashboard
+
+Composable page-shell component: a context provider (`<Dashboard>`) plus opt-in
+dot-notation parts. Pages compose only the chrome they need; recognised parts
+render in a fixed slot order (Breadcrumb → Header → Filters → Body) irrespective
+of authoring order. Framework-agnostic (pure MUI) so it is reusable across
+projects.
+
+## Props (root)
+
+- `defaultFiltersVisible` — initial expanded state of the filter region.
+- `activeFilterCount` — number badged onto `Dashboard.FilterToggle`.
+- `testIdPrefix` — prefix for `data-testid` across all parts.
+
+## Parts
+
+- `Dashboard.Breadcrumb` — breadcrumb trail; `renderLink` for router links.
+- `Dashboard.Header` — title row hosting action parts.
+- `Dashboard.Info` — `[i]` page-summary popover.
+- `Dashboard.FilterToggle` — funnel; toggles filters, badges active count.
+- `Dashboard.Settings` — gear; opens a dialog.
+- `Dashboard.Export` — export dropdown; `onExport(id)`.
+- `Dashboard.Spacer` — right-aligns following controls.
+- `Dashboard.Action` — button slot.
+- `Dashboard.Filters` — collapsible search/filter region.
+- `Dashboard.MoreFilters` — advanced expandable panel (min/max ranges, dates).
+- `Dashboard.Body` — main content.
+
+## Lint
+
+- Pending first `pnpm dev:check`.
+
+## Type Errors
+
+- Pending first `pnpm dev:check`.
+
+## Testing Scenarios
+
+- Filter toggle, info popover, settings dialog, export menu, more-filters expand,
+  order-independent slot rendering.
+
+## Storybook Tests List
+
+- Layout/Dashboard/Tests → 6 interaction stories.
+
+## Current
+
+- v1 authored. Wired into the admin Products page as the first consumer.
+- TODO: roll out to Inventory and Suppliers; add range-filter helpers if the
+  admin needs a shared min/max control.