@12-apps/ui 5.0.1 → 5.1.0

package/src/components/layout/SettingsLayout/SettingsLayout.filters.ts

@@ -0,0 +1,21 @@
+import type { SettingsNavGroup, SettingsNavItem } from './SettingsLayout.types';
+
+/** 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 `switcher`'s collapsed header. */
+export function activeItemLabel(
+  groups: SettingsNavGroup[],
+  activeItemId?: string,
+): string | undefined {
+  return groups.flatMap((group) => group.items).find((item) => item.id === activeItemId)?.label;
+}

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

@@ -0,0 +1,228 @@
+'use client';
+
+import {
+  alpha,
+  Box,
+  List,
+  ListItem,
+  ListItemButton,
+  ListItemIcon,
+  ListItemText,
+  Typography,
+  useTheme,
+} from '@mui/material';
+import React from 'react';
+
+import { atLeastRail, TOUCH_TARGET } from './SettingsLayout.styles';
+import { SettingsStatusMarker } from './SettingsStatusMarker';
+import type {
+  SettingsLayoutProps,
+  SettingsNavGroup,
+  SettingsNavItem,
+  SettingsNavVariant,
+  SettingsRailBreakpoint,
+} from './SettingsLayout.types';
+
+/** The shape-deciding inputs every rail part needs to know about. */
+export interface RailShape {
+  variant: SettingsNavVariant;
+  breakpoint: SettingsRailBreakpoint;
+  atIndex: boolean;
+}
+
+interface RailItemProps extends RailShape {
+  item: SettingsNavItem;
+  active: boolean;
+  linkComponent?: SettingsLayoutProps['linkComponent'];
+  onSelectItem?: (id: string) => void;
+  /** Called on activation so the `switcher`'s rail can collapse after a choice. */
+  onNavigate?: () => void;
+  testIdPrefix: string;
+}
+
+/** Label, plus the situation marker when the host resolved one. */
+function RailItemContent({
+  item,
+  active,
+  testIdPrefix,
+}: {
+  item: SettingsNavItem;
+  active: boolean;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  return (
+    <>
+      {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 }}
+      />
+      {item.status ? (
+        <SettingsStatusMarker
+          status={item.status}
+          label={item.statusLabel}
+          testId={`${testIdPrefix}-status-${item.id}`}
+        />
+      ) : null}
+    </>
+  );
+}
+
+/** One rail entry — a link when it has `href`, inert text when it says so, else a button. */
+export function SettingsRailItem({
+  item,
+  active,
+  linkComponent,
+  onSelectItem,
+  onNavigate,
+  testIdPrefix,
+  variant,
+  breakpoint,
+}: RailItemProps): React.JSX.Element {
+  const theme = useTheme();
+  // In `drilldown` the narrow rail IS the page's list, so its rows are the
+  // primary touch targets rather than a secondary column — hence the 44px floor
+  // below the breakpoint. Above it, the row goes back to rail density.
+  const touchFloor =
+    variant === 'drilldown'
+      ? { minHeight: TOUCH_TARGET, [atLeastRail(theme, breakpoint)]: { minHeight: 'auto' } }
+      : null;
+  const shared = {
+    'data-testid': `${testIdPrefix}-item-${item.id}`,
+    sx: {
+      borderRadius: 1.5,
+      mb: 0.25,
+      gap: 1.5,
+      ...touchFloor,
+      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 = <RailItemContent item={item} active={active} testIdPrefix={testIdPrefix} />;
+
+  // Listed but not reachable from here. Deliberately not a disabled button: a
+  // disabled control says "you may not", and the true statement is "not from
+  // this screen" — the section exists and someone else's screen owns it.
+  if (item.inert) {
+    return (
+      <ListItem {...shared} data-inert="true">
+        {content}
+      </ListItem>
+    );
+  }
+
+  const interactive = {
+    ...shared,
+    selected: active,
+    'aria-current': active ? ('page' as const) : undefined,
+  };
+
+  if (item.href && linkComponent) {
+    const LinkComponent = linkComponent;
+    return (
+      <ListItemButton
+        component={LinkComponent}
+        href={item.href}
+        onClick={onNavigate}
+        {...interactive}
+      >
+        {content}
+      </ListItemButton>
+    );
+  }
+  return (
+    <ListItemButton
+      onClick={() => {
+        onSelectItem?.(item.id);
+        onNavigate?.();
+      }}
+      {...interactive}
+    >
+      {content}
+    </ListItemButton>
+  );
+}
+
+interface RailGroupProps extends RailShape {
+  group: SettingsNavGroup;
+  activeItemId?: string;
+  linkComponent?: SettingsLayoutProps['linkComponent'];
+  onSelectItem?: (id: string) => void;
+  onNavigate?: () => void;
+  testIdPrefix: string;
+}
+
+/**
+ * The list's own grid, in `drilldown` at the index only.
+ *
+ * At the index on a wide phone or a tablet the list has room for two columns;
+ * the rail column never does, so the second column is undone at exactly the
+ * width where this stops being the page.
+ */
+function indexListSx(shape: RailShape) {
+  if (shape.variant !== 'drilldown' || !shape.atIndex) return null;
+  return (theme: import('@mui/material').Theme) => ({
+    display: 'grid',
+    gridTemplateColumns: '1fr',
+    columnGap: 8,
+    [theme.breakpoints.up('sm')]: { gridTemplateColumns: '1fr 1fr' },
+    [atLeastRail(theme, shape.breakpoint)]: { gridTemplateColumns: '1fr' },
+  });
+}
+
+/** A category: header + optional description + its items. */
+export function SettingsRailGroup({
+  group,
+  activeItemId,
+  linkComponent,
+  onSelectItem,
+  onNavigate,
+  testIdPrefix,
+  ...shape
+}: RailGroupProps): React.JSX.Element {
+  const grid = indexListSx(shape);
+  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={(theme) => ({ mt: 0.5, ...(grid ? grid(theme) : null) })}
+      >
+        {group.items.map((item) => (
+          <SettingsRailItem
+            key={item.id}
+            item={item}
+            active={item.id === activeItemId}
+            linkComponent={linkComponent}
+            onSelectItem={onSelectItem}
+            onNavigate={onNavigate}
+            testIdPrefix={testIdPrefix}
+            {...shape}
+          />
+        ))}
+      </List>
+    </Box>
+  );
+}

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

@@ -19,9 +19,77 @@ it themes automatically in light/dark.
 - **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
+- **Responsive** — below `railBreakpoint` the rail either stacks above the panel
+  (`switcher`) or hands the width to a list→detail drilldown (`drilldown`)
+- **Situation markers** per item — host-resolved, with the meaning in text
+- **Section chip strip** on narrow widths, scrolling itself to the open section
 - **Agnostic** — no app-specific content; drive it with any `groups` data
 
+## The two narrow-width shapes
+
+`navVariant` decides what happens below `railBreakpoint`.
+
+**`switcher`** (default) folds the rail into a disclosure stacked above the
+panel. Right when the panel is always the point and the rail is a chooser.
+
+**`drilldown`** gives the shape every mobile settings app has: the list first,
+then the screen, with a way back.
+
+| where | below `railBreakpoint` | at and above it |
+| --- | --- | --- |
+| at the index (`atIndex`) | the grouped **list is the page** | rail + panel |
+| inside a section | back link, **chip strip**, panel | rail + panel |
+
+Pass `atIndex` from the router, `indexHref` for the back link, and
+`sectionChips` with the sibling sections the strip should carry (usually the
+open item's own group).
+
+### Why the width decision is CSS, never a JS media query
+
+Both navigation forms — the rail and the chip strip — are mounted at every
+width, and only `display` moves between them.
+
+A layout that RENDERS one navigation and not the other can offer the narrow
+width less than the wide one, and nothing catches it: the missing control is not
+in the tree to be asserted about, so no test fails and no review notices. With
+one tree, "the phone reaches everything the desktop reaches" holds by
+construction. `DrilldownBothNavigations` in the test stories is the assertion
+that keeps it that way.
+
+The one media query that IS read in JavaScript is `prefers-reduced-motion`, in
+the chip strip — a motion preference has no CSS equivalent at the point where
+`scrollTo` picks its behaviour.
+
+## Situation markers
+
+An item may carry a host-resolved `status`, shown as a marker beside its label:
+
+| `status` | drawn as | means |
+| --- | --- | --- |
+| `ok` | green dot | set up and working |
+| `off` | grey dot | exists, switched off |
+| `new` | red dot | never opened |
+| `locked` | padlock | the plan does not include it |
+
+`locked` is a padlock rather than a fourth colour on purpose: a locked section
+has no configuration state at all, and a grey dot would claim it is merely off.
+
+**`statusLabel` is not optional in practice.** It is rendered as visually-hidden
+text inside the row, so the row's accessible name reads "Endereço, desligado".
+Colour alone never carries the meaning, and a marker without a label is
+decoration.
+
+The layout never derives `status` — it cannot know what "configured" means for a
+screen it does not own, and a rail that guesses disagrees with the screen the
+moment the rule moves.
+
+## Inert items
+
+`inert: true` renders an entry as listed text rather than a control — for a
+section that exists but is not reachable from here. It is deliberately not a
+disabled button: disabled says "you may not", and the honest statement is "not
+from this screen".
+
 ## Usage
 
 ### Route-based (recommended for app settings)
@@ -81,9 +149,16 @@ const [active, setActive] = useState('profile');
 | 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                             |
+| emptySearchAction | `{ label: ReactNode; onClear?: () => void }`            | -                   | The way out, rendered inside the empty-search state                |
 | 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                                |
+| railBreakpoint    | `'sm' \| 'md' \| 'lg' \| 'xl'`                          | `'md'`              | Width at which the rail takes its own column                       |
+| navVariant        | `'switcher' \| 'drilldown'`                            | `'switcher'`        | Narrow-width navigation shape                                      |
+| atIndex           | boolean                                                | `false`             | `drilldown`: the router is at the area's index, not in a section    |
+| indexHref         | string                                                 | -                   | `drilldown`: where the back link goes                              |
+| backLabel         | string                                                 | `'Back'`            | Label on the back control                                          |
+| sectionChips      | SettingsNavItem[]                                      | -                   | Sections carried by the narrow-width chip strip                    |
 
 ### SettingsNavGroup
 
@@ -103,6 +178,9 @@ const [active, setActive] = useState('profile');
 | icon     | ReactNode | Optional leading icon                                  |
 | href     | string    | Optional link target (rendered via `linkComponent`)   |
 | keywords | string[]  | Extra search terms beyond the label                   |
+| status   | `'ok' \| 'off' \| 'new' \| 'locked'` | Host-resolved situation marker    |
+| statusLabel | string | What the marker means — read aloud with the row        |
+| inert    | boolean   | Listed, but not a control (not the same as disabled)  |
 
 ## Accessibility
 
@@ -111,6 +189,14 @@ const [active, setActive] = useState('profile');
 - 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.
+- A situation marker puts its meaning in visually-hidden text inside the row, so
+  the situation is part of the row's accessible name rather than a colour.
+- The chip strip is its own labelled `<nav>`, and the open chip carries
+  `aria-current="page"`.
+- Every control in the `drilldown` shape holds a 44px minimum target below the
+  breakpoint, including the back link and the chips.
+- The chip strip honours `prefers-reduced-motion`: with it set, the scroll to
+  the open section is a jump rather than an animation.
 
 ## Best Practices
 
@@ -134,6 +220,12 @@ const [active, setActive] = useState('profile');
 | Group          | `{testIdPrefix}-group-{groupId}`   |
 | Item           | `{testIdPrefix}-item-{itemId}`     |
 | Empty state    | `{testIdPrefix}-empty`             |
+| Empty-state exit | `{testIdPrefix}-empty-action`    |
+| Situation marker | `{testIdPrefix}-status-{itemId}` |
 | Central panel  | `{testIdPrefix}-panel`             |
+| Back link      | `{testIdPrefix}-back`              |
+| Chip strip     | `{testIdPrefix}-chips`             |
+| Chip           | `{testIdPrefix}-chip-{itemId}`     |
+| Chip marker    | `{testIdPrefix}-chip-status-{itemId}` |
 
 `testIdPrefix` defaults to `settings`.

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

@@ -0,0 +1,279 @@
+'use client';
+
+import ExpandMoreIcon from '@mui/icons-material/ExpandMore';
+import SearchIcon from '@mui/icons-material/Search';
+import { Box, Button, InputAdornment, TextField, Typography } from '@mui/material';
+import React from 'react';
+
+import { SettingsRailGroup, type RailShape } from './SettingsLayout.items';
+import { atLeastRail, displayAcrossRail, RAIL_WIDTH, TOUCH_TARGET } from './SettingsLayout.styles';
+import type {
+  SettingsEmptySearchAction,
+  SettingsLayoutProps,
+  SettingsNavGroup,
+  SettingsRailBreakpoint,
+} from './SettingsLayout.types';
+
+interface RailToggleProps {
+  title?: React.ReactNode;
+  activeLabel?: string;
+  open: boolean;
+  onToggle: () => void;
+  breakpoint: SettingsRailBreakpoint;
+  testIdPrefix: string;
+}
+
+/**
+ * `switcher`-only collapse control: shows the current section (a compact
+ * switcher) so the panel content stays at the top of the screen. Hidden once the
+ * rail has its own column.
+ */
+function SettingsRailToggle({
+  title,
+  activeLabel,
+  open,
+  onToggle,
+  breakpoint,
+  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={(theme) => ({
+        ...displayAcrossRail(theme, breakpoint, 'flex', 'none'),
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: 1,
+        width: '100%',
+        minHeight: TOUCH_TARGET,
+        px: 1.5,
+        py: 1,
+        mb: 1,
+        textAlign: 'left',
+        cursor: 'pointer',
+        color: 'text.primary',
+        background: 'transparent',
+        border: `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',
+          '@media (prefers-reduced-motion: reduce)': { transition: 'none' },
+        }}
+      />
+    </Box>
+  );
+}
+
+/** The empty-search state, with the way out of it rendered inside. */
+function SettingsSearchEmpty({
+  label,
+  action,
+  onClear,
+  testIdPrefix,
+}: {
+  label: React.ReactNode;
+  action?: SettingsEmptySearchAction;
+  onClear: () => void;
+  testIdPrefix: string;
+}): React.JSX.Element {
+  return (
+    <Box data-testid={`${testIdPrefix}-empty`} sx={{ px: 1, py: 2 }}>
+      <Typography variant="body2" color="text.secondary">
+        {label}
+      </Typography>
+      {action ? (
+        <Button
+          size="small"
+          variant="outlined"
+          onClick={() => {
+            onClear();
+            action.onClear?.();
+          }}
+          data-testid={`${testIdPrefix}-empty-action`}
+          sx={{ mt: 1.5, minHeight: TOUCH_TARGET }}
+        >
+          {action.label}
+        </Button>
+      ) : null}
+    </Box>
+  );
+}
+
+export interface RailBodyProps extends RailShape {
+  navOpen: boolean;
+  query: string;
+  onQueryChange: (value: string) => void;
+  searchPlaceholder: string;
+  emptySearchLabel: React.ReactNode;
+  emptySearchAction?: SettingsEmptySearchAction;
+  filteredGroups: SettingsNavGroup[];
+  activeItemId?: string;
+  linkComponent?: SettingsLayoutProps['linkComponent'];
+  onSelectItem?: (id: string) => void;
+  onNavigate?: () => void;
+  testIdPrefix: string;
+}
+
+/** The searchable rail body (search + groups). */
+function SettingsRailBody({
+  navOpen,
+  query,
+  onQueryChange,
+  searchPlaceholder,
+  emptySearchLabel,
+  emptySearchAction,
+  filteredGroups,
+  activeItemId,
+  linkComponent,
+  onSelectItem,
+  onNavigate,
+  testIdPrefix,
+  ...shape
+}: RailBodyProps): React.JSX.Element {
+  // `drilldown` has no disclosure to be closed behind: below the breakpoint the
+  // body is the page, above it the rail. Only `switcher` hides it.
+  const hidden = navOpen ? 'block' : 'none';
+  return (
+    <Box
+      data-testid={`${testIdPrefix}-rail-body`}
+      sx={(theme) =>
+        shape.variant === 'drilldown'
+          ? { display: 'block' }
+          : displayAcrossRail(theme, shape.breakpoint, hidden, '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 ? (
+        <SettingsSearchEmpty
+          label={emptySearchLabel}
+          action={emptySearchAction}
+          onClear={() => onQueryChange('')}
+          testIdPrefix={testIdPrefix}
+        />
+      ) : (
+        filteredGroups.map((group) => (
+          <SettingsRailGroup
+            key={group.id}
+            group={group}
+            activeItemId={activeItemId}
+            linkComponent={linkComponent}
+            onSelectItem={onSelectItem}
+            onNavigate={onNavigate}
+            testIdPrefix={testIdPrefix}
+            {...shape}
+          />
+        ))
+      )}
+    </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 navigation column: title, the `switcher`'s disclosure, and the body. */
+export function SettingsRail({
+  title,
+  activeLabel,
+  navOpen,
+  onToggleNav,
+  testIdPrefix,
+  ...bodyProps
+}: SettingsRailProps): React.JSX.Element {
+  const { variant, breakpoint, atIndex } = bodyProps;
+  // In `drilldown` the rail is the index's list below the breakpoint and the
+  // left column above it — so inside a section it steps aside for the chip
+  // strip. It is `display: none`, never unmounted: the two navigation forms
+  // both stay in the DOM at every width, which is what makes "the narrow width
+  // offers what the wide one offers" true by construction instead of by review.
+  const hiddenWhileInSection = variant === 'drilldown' && !atIndex;
+
+  return (
+    <Box
+      component="nav"
+      aria-label={typeof title === 'string' ? title : 'Settings'}
+      data-testid={`${testIdPrefix}-rail`}
+      sx={(theme) => ({
+        display: hiddenWhileInSection ? 'none' : 'block',
+        flex: '0 0 auto',
+        width: '100%',
+        [atLeastRail(theme, breakpoint)]: {
+          display: 'block',
+          flex: `0 0 ${RAIL_WIDTH}px`,
+          width: RAIL_WIDTH,
+          borderRight: `1px solid ${theme.palette.divider}`,
+          pr: 2,
+        },
+      })}
+    >
+      {title ? (
+        <Typography
+          variant="h6"
+          data-testid={`${testIdPrefix}-title`}
+          sx={(theme) => ({
+            ...(variant === 'drilldown'
+              ? { display: 'block' }
+              : displayAcrossRail(theme, breakpoint, 'none', 'block')),
+            fontWeight: 700,
+            mb: 1.5,
+          })}
+        >
+          {title}
+        </Typography>
+      ) : null}
+      {variant === 'switcher' ? (
+        <SettingsRailToggle
+          title={title}
+          activeLabel={activeLabel}
+          open={navOpen}
+          onToggle={onToggleNav}
+          breakpoint={breakpoint}
+          testIdPrefix={testIdPrefix}
+        />
+      ) : null}
+      <SettingsRailBody navOpen={navOpen} testIdPrefix={testIdPrefix} {...bodyProps} />
+    </Box>
+  );
+}