@12-apps/ui 1.0.0

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

@@ -0,0 +1,297 @@
+'use client';
+
+import {
+  ExpandLess as ExpandLessIcon,
+  ExpandMore as ExpandMoreIcon,
+  FilterListRounded as FilterIcon,
+  NavigateNext as NavigateNextIcon,
+} from '@mui/icons-material';
+import {
+  Box,
+  Breadcrumbs as MuiBreadcrumbs,
+  Button,
+  Collapse,
+  Link as MuiLink,
+  Typography,
+} from '@mui/material';
+import { styled } from '@mui/material/styles';
+import React, { useMemo, useState } from 'react';
+
+import { DashboardContext, useDashboardContext } from './DashboardContext';
+import {
+  DashboardAction,
+  DashboardExport,
+  DashboardFilterToggle,
+  DashboardInfo,
+  DashboardSettings,
+  DashboardSpacer,
+} from './DashboardParts';
+import type {
+  DashboardBodyProps,
+  DashboardBreadcrumbProps,
+  DashboardFiltersProps,
+  DashboardHeaderProps,
+  DashboardMoreFiltersProps,
+  DashboardProps,
+} from './Dashboard.types';
+
+/**
+ * Ordered slot keys. The root reorders composed children into this sequence so
+ * authoring order in JSX never matters — a `<Dashboard.Filters>` placed above
+ * a `<Dashboard.Header>` still renders below it.
+ */
+const SLOT_ORDER = ['breadcrumb', 'header', 'filters', 'body'] as const;
+type SlotKey = (typeof SLOT_ORDER)[number];
+
+/** Marker attached to each sub-component so the root can rank it by slot. */
+type SlottedComponent = { dashboardSlot?: SlotKey };
+
+const Root = styled(Box)(({ theme }) => ({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: theme.spacing(2),
+  width: '100%',
+}));
+
+function slotRank(node: React.ReactNode): number {
+  if (React.isValidElement(node)) {
+    const slot = (node.type as SlottedComponent).dashboardSlot;
+    if (slot) {
+      const rank = SLOT_ORDER.indexOf(slot);
+      if (rank >= 0) {
+        return rank;
+      }
+    }
+  }
+  // Unknown / arbitrary children keep their relative position after the
+  // recognised slots.
+  return SLOT_ORDER.length;
+}
+
+/**
+ * Composable page shell. `<Dashboard>` provides shared state through context
+ * and renders whichever sub-components you compose — nothing is implied. Drop
+ * in only the parts you need; omit `<Dashboard.Filters>` and there is simply no
+ * filter UI.
+ *
+ * @example
+ * ```tsx
+ * <Dashboard activeFilterCount={2}>
+ *   <Dashboard.Breadcrumb items={[{ label: 'Admin', href: '/admin' }, { label: 'Products' }]} />
+ *   <Dashboard.Header title="Products">
+ *     <Dashboard.Info>What this page does…</Dashboard.Info>
+ *     <Dashboard.FilterToggle />
+ *     <Dashboard.Settings>In development</Dashboard.Settings>
+ *     <Dashboard.Spacer />
+ *     <Dashboard.Export onExport={handleExport} />
+ *     <Dashboard.Action><Button variant="contained">New product</Button></Dashboard.Action>
+ *   </Dashboard.Header>
+ *   <Dashboard.Filters>{/* search + pills *\/}</Dashboard.Filters>
+ *   <Dashboard.Body>{table}</Dashboard.Body>
+ * </Dashboard>
+ * ```
+ */
+export const Dashboard = ({
+  children,
+  defaultFiltersVisible = true,
+  activeFilterCount = 0,
+  testIdPrefix = 'dashboard',
+  className,
+}: DashboardProps): React.JSX.Element => {
+  const [filtersVisible, setFiltersVisible] = useState(defaultFiltersVisible);
+  const [moreFiltersOpen, setMoreFiltersOpen] = useState(false);
+
+  const value = useMemo(
+    () => ({
+      filtersVisible,
+      toggleFilters: () => setFiltersVisible((v) => !v),
+      moreFiltersOpen,
+      toggleMoreFilters: () => setMoreFiltersOpen((v) => !v),
+      activeFilterCount,
+      testIdPrefix,
+    }),
+    [filtersVisible, moreFiltersOpen, activeFilterCount, testIdPrefix],
+  );
+
+  // Stable sort recognised slots into canonical order, preserving the original
+  // order of anything unrecognised.
+  const ordered = useMemo(() => {
+    const arr = React.Children.toArray(children);
+    return arr
+      .map((node, index) => ({ node, index, rank: slotRank(node) }))
+      .sort((a, b) => (a.rank === b.rank ? a.index - b.index : a.rank - b.rank))
+      .map((entry) => entry.node);
+  }, [children]);
+
+  return (
+    <DashboardContext.Provider value={value}>
+      <Root className={className} data-testid={testIdPrefix}>
+        {ordered}
+      </Root>
+    </DashboardContext.Provider>
+  );
+};
+
+Dashboard.displayName = 'Dashboard';
+
+/* -------------------------------------------------------------------------- */
+/* Breadcrumb                                                                 */
+/* -------------------------------------------------------------------------- */
+
+const DashboardBreadcrumb = ({
+  items,
+  renderLink,
+  className,
+}: DashboardBreadcrumbProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  return (
+    <MuiBreadcrumbs
+      separator={<NavigateNextIcon fontSize="small" />}
+      className={className}
+      aria-label="breadcrumb"
+      data-testid={`${testIdPrefix}-breadcrumb`}
+      sx={{ fontSize: '0.875rem', color: 'text.secondary' }}
+    >
+      {items.map((item, index) => {
+        const isLast = index === items.length - 1;
+        if (isLast || !item.href) {
+          return (
+            <Typography
+              key={`${item.label}-${index}`}
+              component="span"
+              sx={{ fontSize: '0.875rem', color: isLast ? 'text.primary' : 'text.secondary' }}
+              aria-current={isLast ? 'page' : undefined}
+            >
+              {item.label}
+            </Typography>
+          );
+        }
+        const linkContent = item.label;
+        if (renderLink) {
+          return <React.Fragment key={`${item.label}-${index}`}>{renderLink(item, linkContent)}</React.Fragment>;
+        }
+        return (
+          <MuiLink
+            key={`${item.label}-${index}`}
+            href={item.href}
+            underline="hover"
+            color="inherit"
+            sx={{ fontSize: '0.875rem' }}
+          >
+            {linkContent}
+          </MuiLink>
+        );
+      })}
+    </MuiBreadcrumbs>
+  );
+};
+DashboardBreadcrumb.displayName = 'Dashboard.Breadcrumb';
+(DashboardBreadcrumb as SlottedComponent).dashboardSlot = 'breadcrumb';
+
+/* -------------------------------------------------------------------------- */
+/* Header + action parts                                                      */
+/* -------------------------------------------------------------------------- */
+
+const DashboardHeader = ({ title, children, className }: DashboardHeaderProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  return (
+    <Box
+      className={className}
+      data-testid={`${testIdPrefix}-header`}
+      sx={{ display: 'flex', alignItems: 'center', gap: 1, flexWrap: 'wrap', minHeight: 40 }}
+    >
+      <Typography variant="h5" component="h1" sx={{ fontWeight: 600, mr: 0.5 }}>
+        {title}
+      </Typography>
+      {children}
+    </Box>
+  );
+};
+DashboardHeader.displayName = 'Dashboard.Header';
+(DashboardHeader as SlottedComponent).dashboardSlot = 'header';
+
+/** Flexible spacer — everything composed after it is pushed to the right. */
+/* -------------------------------------------------------------------------- */
+/* Filters                                                                    */
+/* -------------------------------------------------------------------------- */
+
+const DashboardFilters = ({ children, className }: DashboardFiltersProps): React.JSX.Element => {
+  const { filtersVisible, testIdPrefix } = useDashboardContext();
+  return (
+    <Collapse in={filtersVisible} unmountOnExit data-testid={`${testIdPrefix}-filters`}>
+      <Box
+        className={className}
+        sx={{
+          display: 'flex',
+          flexDirection: 'column',
+          gap: 1.5,
+          p: 2,
+          borderRadius: 1,
+          border: 1,
+          borderColor: 'divider',
+          bgcolor: 'action.hover',
+        }}
+      >
+        {children}
+      </Box>
+    </Collapse>
+  );
+};
+DashboardFilters.displayName = 'Dashboard.Filters';
+(DashboardFilters as SlottedComponent).dashboardSlot = 'filters';
+
+const DashboardMoreFilters = ({ children, label = 'More filters' }: DashboardMoreFiltersProps): React.JSX.Element => {
+  const { moreFiltersOpen, toggleMoreFilters, testIdPrefix } = useDashboardContext();
+  return (
+    <Box>
+      <Button
+        variant="text"
+        size="small"
+        startIcon={<FilterIcon fontSize="small" />}
+        endIcon={moreFiltersOpen ? <ExpandLessIcon fontSize="small" /> : <ExpandMoreIcon fontSize="small" />}
+        onClick={toggleMoreFilters}
+        aria-expanded={moreFiltersOpen}
+        data-testid={`${testIdPrefix}-more-filters-toggle`}
+      >
+        {label}
+      </Button>
+      <Collapse in={moreFiltersOpen} unmountOnExit data-testid={`${testIdPrefix}-more-filters-panel`}>
+        <Box sx={{ mt: 1.5, p: 2, borderRadius: 1, border: 1, borderColor: 'divider', bgcolor: 'background.paper' }}>
+          {children}
+        </Box>
+      </Collapse>
+    </Box>
+  );
+};
+DashboardMoreFilters.displayName = 'Dashboard.MoreFilters';
+
+/* -------------------------------------------------------------------------- */
+/* Body                                                                       */
+/* -------------------------------------------------------------------------- */
+
+const DashboardBody = ({ children, className }: DashboardBodyProps): React.JSX.Element => {
+  const { testIdPrefix } = useDashboardContext();
+  return (
+    <Box className={className} data-testid={`${testIdPrefix}-body`}>
+      {children}
+    </Box>
+  );
+};
+DashboardBody.displayName = 'Dashboard.Body';
+(DashboardBody as SlottedComponent).dashboardSlot = 'body';
+
+/* -------------------------------------------------------------------------- */
+/* Attach sub-components as dot-notation parts                                */
+/* -------------------------------------------------------------------------- */
+
+Dashboard.Breadcrumb = DashboardBreadcrumb;
+Dashboard.Header = DashboardHeader;
+Dashboard.Spacer = DashboardSpacer;
+Dashboard.Info = DashboardInfo;
+Dashboard.FilterToggle = DashboardFilterToggle;
+Dashboard.Settings = DashboardSettings;
+Dashboard.Export = DashboardExport;
+Dashboard.Action = DashboardAction;
+Dashboard.Filters = DashboardFilters;
+Dashboard.MoreFilters = DashboardMoreFilters;
+Dashboard.Body = DashboardBody;

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

@@ -0,0 +1,157 @@
+import type { ElementType, ReactNode } from 'react';
+
+/** A single breadcrumb entry for `<Dashboard.Breadcrumb>`. */
+export interface DashboardBreadcrumbItem {
+  /** Visible label. */
+  label: string;
+  /** Optional link target; omit for the current (last) crumb. */
+  href?: string;
+}
+
+/** Props for the root `<Dashboard>` provider/layout. */
+export interface DashboardProps {
+  /** Composed sub-components (`Dashboard.Header`, `Dashboard.Filters`, …). */
+  children?: ReactNode;
+  /**
+   * Whether the filter region starts expanded. Uncontrolled default only —
+   * toggled thereafter by `<Dashboard.FilterToggle>`. Defaults to `true`.
+   */
+  defaultFiltersVisible?: boolean;
+  /** Count shown as a badge on `<Dashboard.FilterToggle>`. Defaults to `0`. */
+  activeFilterCount?: number;
+  /** Prefix for `data-testid` attributes. Defaults to `"dashboard"`. */
+  testIdPrefix?: string;
+  /** Extra class on the root element. */
+  className?: string;
+}
+
+/** Props for `<Dashboard.Breadcrumb>`. */
+export interface DashboardBreadcrumbProps {
+  /** Ordered crumbs, root first. */
+  items: DashboardBreadcrumbItem[];
+  /** Render function for links, e.g. a Next.js `<Link>`. Defaults to `<a>`. */
+  renderLink?: (item: DashboardBreadcrumbItem, children: ReactNode) => ReactNode;
+  className?: string;
+}
+
+/** Props for `<Dashboard.Header>` — the title row that hosts action parts. */
+export interface DashboardHeaderProps {
+  /** Page title. */
+  title: ReactNode;
+  /**
+   * Header controls, composed left-to-right (e.g. `<Dashboard.Info>`,
+   * `<Dashboard.FilterToggle>`, `<Dashboard.Settings>`, `<Dashboard.Export>`,
+   * `<Dashboard.Action>`). Anything after a `<Dashboard.Spacer>` is pushed to
+   * the right edge.
+   */
+  children?: ReactNode;
+  className?: string;
+}
+
+/** Props for `<Dashboard.Info>` — an `[i]` popover summarising the page. */
+export interface DashboardInfoProps {
+  /** Popover heading. Defaults to `"About this page"`. */
+  title?: ReactNode;
+  /** Popover body content. */
+  children: ReactNode;
+  /** Accessible label for the trigger. Defaults to `"Page information"`. */
+  ariaLabel?: string;
+}
+
+/** Props for `<Dashboard.FilterToggle>` — the funnel icon. */
+export interface DashboardFilterToggleProps {
+  /** Accessible label. Defaults to a show/hide string based on state. */
+  ariaLabel?: string;
+}
+
+/** Shared props for both modes of `<Dashboard.Settings>`. */
+interface DashboardSettingsBaseProps {
+  /** Accessible label for the trigger. Defaults to `"Settings"`. */
+  ariaLabel?: string;
+}
+
+/**
+ * Dialog mode of `<Dashboard.Settings>` — the gear opens an in-page settings
+ * dialog rendering `children`. Mutually exclusive with link mode.
+ */
+export interface DashboardSettingsDialogProps extends DashboardSettingsBaseProps {
+  /** Dialog title. Defaults to `"Settings"`. */
+  title?: ReactNode;
+  /** Dialog body. */
+  children: ReactNode;
+  href?: never;
+  linkComponent?: never;
+}
+
+/**
+ * Link mode of `<Dashboard.Settings>` — the gear renders as a link to a settings
+ * route (e.g. a page's Configuração section); no dialog is shown. Mutually
+ * exclusive with dialog mode, so `title`/`children` are not accepted.
+ */
+export interface DashboardSettingsLinkProps extends DashboardSettingsBaseProps {
+  /** Link target settings route. */
+  href: string;
+  /**
+   * Element type used to render the gear — e.g. a Next.js `<Link>` — so
+   * navigation is client-side and the whole gear is one interactive element.
+   * Defaults to a plain `<a>`.
+   */
+  linkComponent?: ElementType;
+  title?: never;
+  children?: never;
+}
+
+/**
+ * Props for `<Dashboard.Settings>` — the gear icon. A discriminated union of two
+ * mutually exclusive modes: dialog mode (`children`, no `href`) opens an in-page
+ * settings dialog; link mode (`href`) renders the gear as a link to a settings
+ * route with no dialog. The compiler rejects mixing the two (e.g. an empty
+ * `<Dashboard.Settings />` with neither `children` nor `href`).
+ */
+export type DashboardSettingsProps =
+  | DashboardSettingsDialogProps
+  | DashboardSettingsLinkProps;
+
+/** A single export format offered by `<Dashboard.Export>`. */
+export interface DashboardExportFormat {
+  /** Stable id passed back to `onExport`, e.g. `"csv"`. */
+  id: string;
+  /** Menu item label, e.g. `"CSV (.csv)"`. */
+  label: string;
+}
+
+/** Props for `<Dashboard.Export>` — the export dropdown. */
+export interface DashboardExportProps {
+  /** Offered formats. Defaults to CSV, Excel and JSON. */
+  formats?: DashboardExportFormat[];
+  /** Invoked with the chosen format id. */
+  onExport: (formatId: string) => void;
+  /** Button label. Defaults to `"Export"`. */
+  label?: ReactNode;
+}
+
+/** Props for `<Dashboard.Action>` — a slot for a primary/secondary button. */
+export interface DashboardActionProps {
+  children: ReactNode;
+}
+
+/** Props for `<Dashboard.Filters>` — the collapsible search/filter region. */
+export interface DashboardFiltersProps {
+  /** Filter controls (search input, pills, `<Dashboard.MoreFilters>`, …). */
+  children: ReactNode;
+  className?: string;
+}
+
+/** Props for `<Dashboard.MoreFilters>` — the advanced, expandable panel. */
+export interface DashboardMoreFiltersProps {
+  /** Advanced controls, e.g. numeric min/max ranges or date pickers. */
+  children: ReactNode;
+  /** Toggle label. Defaults to `"More filters"`. */
+  label?: ReactNode;
+}
+
+/** Props for `<Dashboard.Body>` — the main content area below the header. */
+export interface DashboardBodyProps {
+  children: ReactNode;
+  className?: string;
+}

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

@@ -0,0 +1,47 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+/**
+ * Value shared across every `Dashboard` sub-component through React context.
+ *
+ * The root `<Dashboard>` owns this state; opt-in parts such as
+ * `<Dashboard.FilterToggle>` and `<Dashboard.Filters>` read from and write to
+ * it so they stay in sync without the caller wiring anything up. Nothing here
+ * is required — a `Dashboard` composed of only a `<Dashboard.Header>` simply
+ * never touches the filter fields.
+ */
+export interface DashboardContextValue {
+  /** Whether the `<Dashboard.Filters>` region is currently expanded. */
+  filtersVisible: boolean;
+  /** Toggles {@link filtersVisible}. Bound to `<Dashboard.FilterToggle>`. */
+  toggleFilters: () => void;
+  /** Whether the advanced `<Dashboard.MoreFilters>` panel is expanded. */
+  moreFiltersOpen: boolean;
+  /** Toggles {@link moreFiltersOpen}. Bound to `<Dashboard.MoreFiltersToggle>`. */
+  toggleMoreFilters: () => void;
+  /**
+   * Count of active filters, surfaced as a badge on `<Dashboard.FilterToggle>`.
+   * Supplied by the caller via the `activeFilterCount` prop on `<Dashboard>`.
+   */
+  activeFilterCount: number;
+  /** Stable prefix for `data-testid` attributes across sub-components. */
+  testIdPrefix: string;
+}
+
+/** Backing context. `null` when a sub-component is used outside `<Dashboard>`. */
+export const DashboardContext = createContext<DashboardContextValue | null>(null);
+
+/**
+ * Reads the nearest {@link DashboardContext}.
+ *
+ * @throws If called outside a `<Dashboard>` provider.
+ * @returns The current dashboard context value.
+ */
+export function useDashboardContext(): DashboardContextValue {
+  const context = useContext(DashboardContext);
+  if (!context) {
+    throw new Error('Dashboard sub-components must be used within a <Dashboard>');
+  }
+  return context;
+}