@12-apps/ui 1.0.0

package/src/components/layout/Separator/Separator.tsx

@@ -0,0 +1,187 @@
+import { Box, Typography,useTheme } from '@mui/material';
+import React from 'react';
+
+import type { SeparatorProps } from './Separator.types';
+
+export const Separator: React.FC<SeparatorProps> = ({
+  variant = 'solid',
+  orientation = 'horizontal',
+  size = 'md',
+  color,
+  margin,
+  length,
+  children,
+  className,
+  'data-testid': dataTestId,
+}) => {
+  const theme = useTheme();
+
+  const getThickness = () => {
+    switch (size) {
+      case 'xs':
+        return 1;
+      case 'sm':
+        return 2;
+      case 'md':
+        return 3;
+      case 'lg':
+        return 4;
+      case 'xl':
+        return 6;
+      default:
+        return 3;
+    }
+  };
+
+  const getMargin = () => {
+    if (margin !== undefined) return margin;
+    switch (size) {
+      case 'xs':
+        return 4; // 0.5 * 8 = 4px
+      case 'sm':
+        return 8; // 1 * 8 = 8px
+      case 'md':
+        return 16; // 2 * 8 = 16px
+      case 'lg':
+        return 24; // 3 * 8 = 24px
+      case 'xl':
+        return 32; // 4 * 8 = 32px
+      default:
+        return 16;
+    }
+  };
+
+  const getBorderStyle = () => {
+    switch (variant) {
+      case 'dashed':
+        return 'dashed';
+      case 'dotted':
+        return 'dotted';
+      case 'gradient':
+        return 'solid';
+      default:
+        return 'solid';
+    }
+  };
+
+  const getColor = () => {
+    if (color) return color;
+    return theme.palette.divider;
+  };
+
+  const getGradientBackground = () => {
+    if (variant !== 'gradient') return undefined;
+
+    if (orientation === 'horizontal') {
+      return `linear-gradient(90deg, transparent 0%, ${getColor()} 50%, transparent 100%)`;
+    } else {
+      return `linear-gradient(180deg, transparent 0%, ${getColor()} 50%, transparent 100%)`;
+    }
+  };
+
+  const getSeparatorStyles = () => {
+    const isHorizontal = orientation === 'horizontal';
+    const thickness = getThickness();
+    const marginValue = getMargin();
+
+    // Handle margin - if it's a string with units, use as-is, otherwise add px
+    const marginStr = typeof marginValue === 'string' ? marginValue : `${marginValue}px`;
+
+    const baseStyles = {
+      display: 'flex' as const,
+      alignItems: 'center' as const,
+      margin: isHorizontal ? `${marginStr} 0` : `0 ${marginStr}`,
+      width: isHorizontal ? length || '100%' : `${thickness}px`,
+      height: isHorizontal ? `${thickness}px` : length || '100%',
+      boxSizing: 'border-box' as const,
+    };
+
+    if (variant === 'gradient') {
+      return {
+        ...baseStyles,
+        background: getGradientBackground(),
+      };
+    }
+
+    // Apply border styles separately for better compatibility with MUI's sx prop
+    const borderStyle = getBorderStyle();
+    const borderColor = getColor();
+
+    const borderStyles = isHorizontal
+      ? {
+          borderTopWidth: thickness,
+          borderTopStyle: borderStyle,
+          borderTopColor: borderColor,
+          borderBottomWidth: 0,
+          borderLeftWidth: 0,
+          borderRightWidth: 0,
+          borderBottomStyle: 'none',
+          borderLeftStyle: 'none',
+          borderRightStyle: 'none',
+          borderBottomColor: 'transparent',
+          borderLeftColor: 'transparent',
+          borderRightColor: 'transparent',
+        }
+      : {
+          borderLeftWidth: thickness,
+          borderLeftStyle: borderStyle,
+          borderLeftColor: borderColor,
+          borderTopWidth: 0,
+          borderBottomWidth: 0,
+          borderRightWidth: 0,
+          borderTopStyle: 'none',
+          borderBottomStyle: 'none',
+          borderRightStyle: 'none',
+          borderTopColor: 'transparent',
+          borderBottomColor: 'transparent',
+          borderRightColor: 'transparent',
+        };
+
+    return {
+      ...baseStyles,
+      backgroundColor: 'transparent' as const,
+      ...borderStyles,
+    };
+  };
+
+  if (children) {
+    const isHorizontal = orientation === 'horizontal';
+
+    return (
+      <Box
+        className={className}
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          margin: getMargin(),
+          flexDirection: isHorizontal ? 'row' : 'column',
+          gap: theme.spacing(2),
+        }}
+      >
+        <Box sx={getSeparatorStyles()} />
+        <Typography
+          variant="body2"
+          color="text.secondary"
+          sx={{
+            flexShrink: 0,
+            padding: theme.spacing(0, 1),
+            backgroundColor: theme.palette.background.default,
+          }}
+        >
+          {children}
+        </Typography>
+        <Box sx={getSeparatorStyles()} />
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      className={className}
+      sx={getSeparatorStyles()}
+      role="separator"
+      aria-orientation={orientation}
+      data-testid={dataTestId}
+    />
+  );
+};

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

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+
+export type SeparatorVariant = 'solid' | 'dashed' | 'dotted' | 'gradient';
+export type SeparatorOrientation = 'horizontal' | 'vertical';
+export type SeparatorSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface SeparatorProps {
+  variant?: SeparatorVariant;
+  orientation?: SeparatorOrientation;
+  size?: SeparatorSize;
+  color?: string;
+  margin?: number | string;
+  length?: number | string;
+  children?: ReactNode;
+  className?: string;
+  'data-testid'?: string;
+}

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

@@ -0,0 +1,2 @@
+export { Separator } from './Separator';
+export type { SeparatorProps } from './Separator.types';

package/src/components/layout/SettingsLayout/SettingsLayout.md

@@ -0,0 +1,139 @@
+# SettingsLayout Component
+
+## Overview
+
+`SettingsLayout` is a reusable, agnostic, data-driven **two-pane settings shell**
+(Facebook-style): a searchable left rail of grouped categories/subcategories and a
+central panel that renders the selected configuration screen. Navigation is
+described entirely by data (`groups`); the host owns routing — either by passing a
+`linkComponent` (e.g. a Next.js `Link`) with per-item `href`s, or by handling
+`onSelectItem` for in-place selection.
+
+It composes MUI primitives and semantic theme tokens only (no hardcoded colors), so
+it themes automatically in light/dark.
+
+## Features
+
+- **Search field** filtering the rail by item `label` + optional `keywords`
+- **Grouped navigation** with category headers and optional descriptions
+- **Central panel** (`children`) — a custom screen per configuration
+- **Link or button mode** per item (`href` + `linkComponent`, or `onSelectItem`)
+- **Active highlight** via `activeItemId` (`aria-current="page"`, semantic tint)
+- **Responsive** — below `md` the rail stacks full-width above the panel
+- **Agnostic** — no app-specific content; drive it with any `groups` data
+
+## Usage
+
+### Route-based (recommended for app settings)
+
+```tsx
+import NextLink from 'next/link';
+import { usePathname } from 'next/navigation';
+import { SettingsLayout, type SettingsNavGroup } from '@12-apps/ui/layout/SettingsLayout';
+
+const groups: SettingsNavGroup[] = [
+  {
+    id: 'operations',
+    label: 'Operação',
+    items: [
+      { id: 'inventory', label: 'Estoque & custo', href: '/admin/acme/config/inventory' },
+      { id: 'orders', label: 'Pedidos', href: '/admin/acme/config/orders' },
+    ],
+  },
+];
+
+function ConfigShell({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname();
+  const active = groups.flatMap((g) => g.items).find((i) => pathname.startsWith(i.href!))?.id;
+  return (
+    <SettingsLayout
+      title="Configuração"
+      searchPlaceholder="Pesquisar configurações"
+      groups={groups}
+      activeItemId={active}
+      linkComponent={NextLink}
+    >
+      {children}
+    </SettingsLayout>
+  );
+}
+```
+
+### Selection-based (no routing)
+
+```tsx
+const [active, setActive] = useState('profile');
+
+<SettingsLayout groups={groups} activeItemId={active} onSelectItem={setActive}>
+  <ProfilePanel />
+</SettingsLayout>;
+```
+
+## Props
+
+### SettingsLayoutProps
+
+| Prop              | Type                                                   | Default             | Description                                                        |
+| ----------------- | ------------------------------------------------------ | ------------------- | ------------------------------------------------------------------ |
+| title             | ReactNode                                              | -                   | Heading shown above the search field                               |
+| groups            | SettingsNavGroup[]                                     | -                   | Grouped navigation for the left rail                               |
+| activeItemId      | string                                                 | -                   | Id of the currently-open item (highlighted)                        |
+| onSelectItem      | (id: string) => void                                   | -                   | Fired when a non-link item is chosen                               |
+| searchPlaceholder | string                                                 | `'Search settings'` | Placeholder for the search field                                   |
+| emptySearchLabel  | ReactNode                                              | generic string      | Shown when the search matches no items                             |
+| linkComponent     | ElementType                                            | -                   | Element used to render items that have an `href` (e.g. Next `Link`)|
+| children          | ReactNode                                              | -                   | Central panel content (the selected screen)                        |
+| testIdPrefix      | string                                                 | `'settings'`        | Prefix for `data-testid` attributes                                |
+
+### SettingsNavGroup
+
+| Prop        | Type              | Description                              |
+| ----------- | ----------------- | ---------------------------------------- |
+| id          | string            | Stable id (drives the group `data-testid`)|
+| label       | string            | Category header (uppercased in the rail) |
+| description | string            | Optional one-line description            |
+| items       | SettingsNavItem[] | The items in this group                  |
+
+### SettingsNavItem
+
+| Prop     | Type      | Description                                            |
+| -------- | --------- | ----------------------------------------------------- |
+| id       | string    | Stable id (drives active highlight + `data-testid`)   |
+| label    | string    | Visible label; matched by the search field            |
+| icon     | ReactNode | Optional leading icon                                  |
+| href     | string    | Optional link target (rendered via `linkComponent`)   |
+| keywords | string[]  | Extra search terms beyond the label                   |
+
+## Accessibility
+
+- The rail is a `<nav>` labelled by the `title`.
+- The active item exposes `aria-current="page"`.
+- Items with `href` render as a single interactive anchor (via `linkComponent`),
+  avoiding nested interactive elements.
+- The search field carries an accessible label matching its placeholder.
+
+## Best Practices
+
+1. **Keep it agnostic** — pass content through `groups`/`children`; don't hardcode
+   app specifics into the component.
+2. **Deep-linkable** — prefer route-based navigation (`linkComponent` + `href`) so
+   each section has its own URL.
+3. **Searchability** — add `keywords` to items whose label alone won't be typed.
+4. **Grouping** — use a small number of balanced groups; single-item groups are fine.
+
+## Testing
+
+### Test IDs
+
+| Element        | Test ID                            |
+| -------------- | ---------------------------------- |
+| Root           | `{testIdPrefix}`                   |
+| Left rail      | `{testIdPrefix}-rail`              |
+| Title          | `{testIdPrefix}-title`             |
+| Search field   | `{testIdPrefix}-search`            |
+| Group          | `{testIdPrefix}-group-{groupId}`   |
+| Item           | `{testIdPrefix}-item-{itemId}`     |
+| Empty state    | `{testIdPrefix}-empty`             |
+| Central panel  | `{testIdPrefix}-panel`             |
+
+`testIdPrefix` defaults to `settings`.

package/src/components/layout/SettingsLayout/SettingsLayout.parts.tsx

@@ -0,0 +1,357 @@
+'use client';
+
+import { ExpandMore as ExpandMoreIcon, Search as SearchIcon } from '@mui/icons-material';
+import {
+  alpha,
+  Box,
+  InputAdornment,
+  List,
+  ListItemButton,
+  ListItemIcon,
+  ListItemText,
+  TextField,
+  Typography,
+  useTheme,
+} from '@mui/material';
+import React from 'react';
+
+import type { SettingsLayoutProps, SettingsNavGroup, SettingsNavItem } from './SettingsLayout.types';
+
+/** Fixed width of the left navigation rail on `md`+ screens. */
+const RAIL_WIDTH = 300;
+
+/** Case-insensitive filter over item label + keywords; drops emptied groups. */
+export function filterGroups(groups: SettingsNavGroup[], query: string): SettingsNavGroup[] {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return groups;
+  const matches = (item: SettingsNavItem): boolean =>
+    item.label.toLowerCase().includes(needle) ||
+    (item.keywords ?? []).some((keyword) => keyword.toLowerCase().includes(needle));
+  return groups
+    .map((group) => ({ ...group, items: group.items.filter(matches) }))
+    .filter((group) => group.items.length > 0);
+}
+
+/** Label of the active item, shown in the mobile section-switcher header. */
+export function activeItemLabel(
+  groups: SettingsNavGroup[],
+  activeItemId?: string,
+): string | undefined {
+  return groups.flatMap((group) => group.items).find((item) => item.id === activeItemId)?.label;
+}
+
+interface RailItemProps {
+  item: SettingsNavItem;
+  active: boolean;
+  linkComponent?: SettingsLayoutProps['linkComponent'];
+  onSelectItem?: (id: string) => void;
+  /** Called on activation so the mobile rail can collapse after a choice. */
+  onNavigate?: () => void;
+  testIdPrefix: string;
+}
+
+/** One rail entry — rendered as a link when it has `href`, else a button. */
+function SettingsRailItem({
+  item,
+  active,
+  linkComponent,
+  onSelectItem,
+  onNavigate,
+  testIdPrefix,
+}: RailItemProps): React.JSX.Element {
+  const theme = useTheme();
+  const shared = {
+    selected: active,
+    'aria-current': active ? ('page' as const) : undefined,
+    'data-testid': `${testIdPrefix}-item-${item.id}`,
+    sx: {
+      borderRadius: 1.5,
+      mb: 0.25,
+      gap: 1.5,
+      color: active ? 'primary.main' : 'text.secondary',
+      '&.Mui-selected': {
+        bgcolor: alpha(theme.palette.primary.main, 0.12),
+        '&:hover': { bgcolor: alpha(theme.palette.primary.main, 0.18) },
+      },
+    },
+  };
+  const content = (
+    <>
+      {item.icon ? (
+        <ListItemIcon sx={{ minWidth: 0, color: 'inherit' }}>{item.icon}</ListItemIcon>
+      ) : null}
+      <ListItemText
+        primary={item.label}
+        primaryTypographyProps={{ variant: 'body2', noWrap: true, fontWeight: active ? 600 : 500 }}
+      />
+    </>
+  );
+
+  if (item.href && linkComponent) {
+    const LinkComponent = linkComponent;
+    return (
+      <ListItemButton component={LinkComponent} href={item.href} onClick={onNavigate} {...shared}>
+        {content}
+      </ListItemButton>
+    );
+  }
+  return (
+    <ListItemButton
+      onClick={() => {
+        onSelectItem?.(item.id);
+        onNavigate?.();
+      }}
+      {...shared}
+    >
+      {content}
+    </ListItemButton>
+  );
+}
+
+interface RailGroupProps {
+  group: SettingsNavGroup;
+  activeItemId?: string;
+  linkComponent?: SettingsLayoutProps['linkComponent'];
+  onSelectItem?: (id: string) => void;
+  onNavigate?: () => void;
+  testIdPrefix: string;
+}
+
+/** A category: header + optional description + its items. */
+function SettingsRailGroup({
+  group,
+  activeItemId,
+  linkComponent,
+  onSelectItem,
+  onNavigate,
+  testIdPrefix,
+}: RailGroupProps): React.JSX.Element {
+  return (
+    <Box data-testid={`${testIdPrefix}-group-${group.id}`} sx={{ mb: 2 }}>
+      <Typography
+        variant="caption"
+        sx={{
+          display: 'block',
+          px: 1,
+          color: 'text.secondary',
+          fontWeight: 600,
+          textTransform: 'uppercase',
+          letterSpacing: '0.06em',
+        }}
+      >
+        {group.label}
+      </Typography>
+      {group.description ? (
+        <Typography variant="caption" component="p" sx={{ px: 1, mt: 0.25, color: 'text.disabled' }}>
+          {group.description}
+        </Typography>
+      ) : null}
+      <List disablePadding sx={{ mt: 0.5 }}>
+        {group.items.map((item) => (
+          <SettingsRailItem
+            key={item.id}
+            item={item}
+            active={item.id === activeItemId}
+            linkComponent={linkComponent}
+            onSelectItem={onSelectItem}
+            onNavigate={onNavigate}
+            testIdPrefix={testIdPrefix}
+          />
+        ))}
+      </List>
+    </Box>
+  );
+}
+
+interface RailToggleProps {
+  title?: React.ReactNode;
+  activeLabel?: string;
+  open: boolean;
+  onToggle: () => void;
+  testIdPrefix: string;
+}
+
+/**
+ * Mobile-only collapse control: shows the current section (a compact switcher)
+ * so the panel content stays at the top of the screen. Hidden on `md`+.
+ */
+function SettingsRailToggle({
+  title,
+  activeLabel,
+  open,
+  onToggle,
+  testIdPrefix,
+}: RailToggleProps): React.JSX.Element {
+  return (
+    <Box
+      component="button"
+      type="button"
+      onClick={onToggle}
+      aria-expanded={open}
+      aria-label={typeof title === 'string' ? title : 'Settings'}
+      data-testid={`${testIdPrefix}-toggle`}
+      sx={{
+        display: { xs: 'flex', md: 'none' },
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: 1,
+        width: '100%',
+        px: 1.5,
+        py: 1,
+        mb: 1,
+        textAlign: 'left',
+        cursor: 'pointer',
+        color: 'text.primary',
+        background: 'transparent',
+        border: (theme) => `1px solid ${theme.palette.divider}`,
+        borderRadius: 1.5,
+      }}
+    >
+      <Box sx={{ minWidth: 0 }}>
+        {title ? (
+          <Typography variant="caption" sx={{ display: 'block', color: 'text.secondary' }}>
+            {title}
+          </Typography>
+        ) : null}
+        <Typography variant="body2" noWrap sx={{ fontWeight: 600 }}>
+          {activeLabel ?? ''}
+        </Typography>
+      </Box>
+      <ExpandMoreIcon
+        fontSize="small"
+        sx={{
+          flex: '0 0 auto',
+          color: 'text.secondary',
+          transition: 'transform 150ms ease',
+          transform: open ? 'rotate(180deg)' : 'none',
+        }}
+      />
+    </Box>
+  );
+}
+
+interface RailBodyProps {
+  navOpen: boolean;
+  query: string;
+  onQueryChange: (value: string) => void;
+  searchPlaceholder: string;
+  emptySearchLabel: React.ReactNode;
+  filteredGroups: SettingsNavGroup[];
+  activeItemId?: string;
+  linkComponent?: SettingsLayoutProps['linkComponent'];
+  onSelectItem?: (id: string) => void;
+  onNavigate?: () => void;
+  testIdPrefix: string;
+}
+
+/** The searchable rail body (search + groups); hidden on mobile until expanded. */
+function SettingsRailBody({
+  navOpen,
+  query,
+  onQueryChange,
+  searchPlaceholder,
+  emptySearchLabel,
+  filteredGroups,
+  activeItemId,
+  linkComponent,
+  onSelectItem,
+  onNavigate,
+  testIdPrefix,
+}: RailBodyProps): React.JSX.Element {
+  return (
+    <Box
+      data-testid={`${testIdPrefix}-rail-body`}
+      sx={{ display: { xs: navOpen ? 'block' : 'none', md: 'block' } }}
+    >
+      <TextField
+        value={query}
+        onChange={(event) => onQueryChange(event.target.value)}
+        placeholder={searchPlaceholder}
+        size="small"
+        fullWidth
+        aria-label={searchPlaceholder}
+        data-testid={`${testIdPrefix}-search`}
+        InputProps={{
+          startAdornment: (
+            <InputAdornment position="start">
+              <SearchIcon fontSize="small" sx={{ color: 'text.secondary' }} />
+            </InputAdornment>
+          ),
+        }}
+        sx={{ mb: 2 }}
+      />
+      {filteredGroups.length === 0 ? (
+        <Typography
+          variant="body2"
+          color="text.secondary"
+          data-testid={`${testIdPrefix}-empty`}
+          sx={{ px: 1, py: 2 }}
+        >
+          {emptySearchLabel}
+        </Typography>
+      ) : (
+        filteredGroups.map((group) => (
+          <SettingsRailGroup
+            key={group.id}
+            group={group}
+            activeItemId={activeItemId}
+            linkComponent={linkComponent}
+            onSelectItem={onSelectItem}
+            onNavigate={onNavigate}
+            testIdPrefix={testIdPrefix}
+          />
+        ))
+      )}
+    </Box>
+  );
+}
+
+/** Props for {@link SettingsRail}: the rail body's inputs plus the mobile chrome. */
+export type SettingsRailProps = RailBodyProps & {
+  title?: React.ReactNode;
+  activeLabel?: string;
+  onToggleNav: () => void;
+};
+
+/** The left navigation column: desktop title, mobile switcher, and the body. */
+export function SettingsRail({
+  title,
+  activeLabel,
+  navOpen,
+  onToggleNav,
+  testIdPrefix,
+  ...bodyProps
+}: SettingsRailProps): React.JSX.Element {
+  const theme = useTheme();
+  return (
+    <Box
+      component="nav"
+      aria-label={typeof title === 'string' ? title : 'Settings'}
+      data-testid={`${testIdPrefix}-rail`}
+      sx={{
+        flex: { xs: '0 0 auto', md: `0 0 ${RAIL_WIDTH}px` },
+        width: { xs: '100%', md: RAIL_WIDTH },
+        borderRight: { md: `1px solid ${theme.palette.divider}` },
+        pr: { md: 2 },
+      }}
+    >
+      {title ? (
+        <Typography
+          variant="h6"
+          data-testid={`${testIdPrefix}-title`}
+          sx={{ display: { xs: 'none', md: 'block' }, fontWeight: 700, mb: 1.5 }}
+        >
+          {title}
+        </Typography>
+      ) : null}
+      <SettingsRailToggle
+        title={title}
+        activeLabel={activeLabel}
+        open={navOpen}
+        onToggle={onToggleNav}
+        testIdPrefix={testIdPrefix}
+      />
+      <SettingsRailBody navOpen={navOpen} testIdPrefix={testIdPrefix} {...bodyProps} />
+    </Box>
+  );
+}