@12-apps/ui 1.0.0

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

@@ -0,0 +1,194 @@
+import {
+  LanguageOutlined,
+  LockOutlined,
+  NotificationsOutlined,
+  PaletteOutlined,
+  PaymentOutlined,
+  PersonOutlined,
+} from '@mui/icons-material';
+import { Box, Stack, Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { SettingsLayout } from './SettingsLayout';
+import type { SettingsNavGroup } from './SettingsLayout.types';
+
+const GROUPS: SettingsNavGroup[] = [
+  {
+    id: 'account',
+    label: 'Account',
+    items: [
+      { id: 'profile', label: 'Profile', icon: <PersonOutlined fontSize="small" /> },
+      {
+        id: 'security',
+        label: 'Security',
+        icon: <LockOutlined fontSize="small" />,
+        keywords: ['password', 'two-factor', '2fa'],
+      },
+      {
+        id: 'notifications',
+        label: 'Notifications',
+        icon: <NotificationsOutlined fontSize="small" />,
+      },
+    ],
+  },
+  {
+    id: 'workspace',
+    label: 'Workspace',
+    description: 'Preferences that apply to this workspace only.',
+    items: [
+      { id: 'appearance', label: 'Appearance', icon: <PaletteOutlined fontSize="small" /> },
+      {
+        id: 'billing',
+        label: 'Billing',
+        icon: <PaymentOutlined fontSize="small" />,
+        keywords: ['invoice', 'plan', 'payment'],
+      },
+    ],
+  },
+  {
+    id: 'advanced',
+    label: 'Advanced',
+    items: [
+      { id: 'language', label: 'Language & region', icon: <LanguageOutlined fontSize="small" /> },
+    ],
+  },
+];
+
+const ALL_ITEMS = GROUPS.flatMap((group) => group.items);
+
+/** A minimal example panel that reflects the selected item. */
+function ExamplePanel({ itemId }: { itemId: string }): React.JSX.Element {
+  const item = ALL_ITEMS.find((candidate) => candidate.id === itemId) ?? ALL_ITEMS[0];
+  return (
+    <Stack spacing={1} sx={{ p: 1 }}>
+      <Typography variant="h6">{item?.label}</Typography>
+      <Typography variant="body2" color="text.secondary">
+        This central panel renders a custom screen for “{item?.label}”. In a real app each item
+        maps to its own route/component.
+      </Typography>
+      <Box
+        sx={{
+          mt: 1,
+          height: 160,
+          borderRadius: 1,
+          border: (theme) => `1px dashed ${theme.palette.divider}`,
+        }}
+      />
+    </Stack>
+  );
+}
+
+const meta: Meta<typeof SettingsLayout> = {
+  title: 'Layout/SettingsLayout',
+  component: SettingsLayout,
+  parameters: {
+    layout: 'fullscreen',
+  },
+  tags: ['autodocs', 'component:SettingsLayout'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Controlled example: clicking a rail item swaps the central panel. */
+export const Default: Story = {
+  render: () => {
+    const InteractiveSettings = (): React.JSX.Element => {
+      const [active, setActive] = useState('profile');
+      return (
+        <Box sx={{ p: 3, minHeight: 480 }}>
+          <SettingsLayout
+            title="Settings"
+            searchPlaceholder="Search settings"
+            groups={GROUPS}
+            activeItemId={active}
+            onSelectItem={setActive}
+          >
+            <ExamplePanel itemId={active} />
+          </SettingsLayout>
+        </Box>
+      );
+    };
+    return <InteractiveSettings />;
+  },
+};
+
+/** Group headers can carry a one-line description (Facebook-style). */
+export const WithDescriptions: Story = {
+  render: () => (
+    <Box sx={{ p: 3, minHeight: 480 }}>
+      <SettingsLayout title="Settings" groups={GROUPS} activeItemId="billing">
+        <ExamplePanel itemId="billing" />
+      </SettingsLayout>
+    </Box>
+  ),
+};
+
+/** A single group renders as a flat list under the search field. */
+export const FlatSingleGroup: Story = {
+  render: () => (
+    <Box sx={{ p: 3, minHeight: 480 }}>
+      <SettingsLayout
+        title="Settings"
+        groups={[{ id: 'all', label: 'All settings', items: ALL_ITEMS }]}
+        activeItemId="profile"
+      >
+        <ExamplePanel itemId="profile" />
+      </SettingsLayout>
+    </Box>
+  ),
+};
+
+/** Items with `href` + a `linkComponent` render as navigation links. */
+export const AsLinks: Story = {
+  render: () => {
+    const linkedGroups: SettingsNavGroup[] = GROUPS.map((group) => ({
+      ...group,
+      items: group.items.map((item) => ({ ...item, href: `#/settings/${item.id}` })),
+    }));
+    return (
+      <Box sx={{ p: 3, minHeight: 480 }}>
+        <SettingsLayout
+          title="Settings"
+          groups={linkedGroups}
+          activeItemId="security"
+          linkComponent="a"
+        >
+          <ExamplePanel itemId="security" />
+        </SettingsLayout>
+      </Box>
+    );
+  },
+};
+
+/** Items without icons still align cleanly. */
+export const NoIcons: Story = {
+  render: () => {
+    const plainGroups: SettingsNavGroup[] = GROUPS.map((group) => ({
+      ...group,
+      items: group.items.map(({ icon: _icon, ...rest }) => rest),
+    }));
+    return (
+      <Box sx={{ p: 3, minHeight: 480 }}>
+        <SettingsLayout title="Settings" groups={plainGroups} activeItemId="appearance">
+          <ExamplePanel itemId="appearance" />
+        </SettingsLayout>
+      </Box>
+    );
+  },
+};
+
+/** Below `md` the rail stacks full-width above the panel. */
+export const Responsive: Story = {
+  parameters: {
+    viewport: { defaultViewport: 'mobile1' },
+  },
+  render: () => (
+    <Box sx={{ p: 2, minHeight: 480 }}>
+      <SettingsLayout title="Settings" groups={GROUPS} activeItemId="profile">
+        <ExamplePanel itemId="profile" />
+      </SettingsLayout>
+    </Box>
+  ),
+};

package/src/components/layout/SettingsLayout/SettingsLayout.test.stories.tsx

@@ -0,0 +1,175 @@
+import { Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { SettingsLayout } from './SettingsLayout';
+import type { SettingsNavGroup } from './SettingsLayout.types';
+
+const GROUPS: SettingsNavGroup[] = [
+  {
+    id: 'account',
+    label: 'Account',
+    items: [
+      { id: 'profile', label: 'Profile' },
+      { id: 'security', label: 'Security', keywords: ['password', '2fa'] },
+    ],
+  },
+  {
+    id: 'workspace',
+    label: 'Workspace',
+    description: 'Workspace-only preferences.',
+    items: [{ id: 'billing', label: 'Billing' }],
+  },
+];
+
+const meta: Meta<typeof SettingsLayout> = {
+  title: 'Layout/SettingsLayout/Tests',
+  component: SettingsLayout,
+  parameters: {
+    layout: 'fullscreen',
+    chromatic: { disableSnapshot: false },
+  },
+  tags: ['autodocs', 'test', 'component:SettingsLayout'],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const panel = <Typography data-testid="demo-panel">Panel content</Typography>;
+
+export const StructureRender: Story = {
+  name: '🧪 Structure Render Test',
+  render: () => (
+    <SettingsLayout title="Settings" groups={GROUPS} activeItemId="profile">
+      {panel}
+    </SettingsLayout>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Rail, search, groups and panel render', async () => {
+      await expect(canvas.getByTestId('settings-rail')).toBeInTheDocument();
+      await expect(canvas.getByTestId('settings-search')).toBeInTheDocument();
+      await expect(canvas.getByTestId('settings-group-account')).toBeInTheDocument();
+      await expect(canvas.getByTestId('settings-group-workspace')).toBeInTheDocument();
+      await expect(canvas.getByTestId('settings-item-profile')).toBeInTheDocument();
+      await expect(canvas.getByTestId('settings-panel')).toBeInTheDocument();
+      await expect(canvas.getByTestId('demo-panel')).toBeInTheDocument();
+    });
+  },
+};
+
+export const ActiveHighlight: Story = {
+  name: '🎯 Active Item Highlight Test',
+  render: () => (
+    <SettingsLayout title="Settings" groups={GROUPS} activeItemId="security">
+      {panel}
+    </SettingsLayout>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Active item carries aria-current=page', async () => {
+      const active = canvas.getByTestId('settings-item-security');
+      await expect(active).toHaveAttribute('aria-current', 'page');
+      const inactive = canvas.getByTestId('settings-item-profile');
+      await expect(inactive).not.toHaveAttribute('aria-current');
+    });
+  },
+};
+
+export const SelectionCallback: Story = {
+  name: '🖱️ Selection Callback Test',
+  args: { onSelectItem: fn() },
+  render: (args) => (
+    <SettingsLayout title="Settings" groups={GROUPS} activeItemId="profile" {...args}>
+      {panel}
+    </SettingsLayout>
+  ),
+  play: async ({ canvasElement, step, args }) => {
+    const canvas = within(canvasElement);
+
+    await step('Clicking a button item fires onSelectItem with its id', async () => {
+      await userEvent.click(canvas.getByTestId('settings-item-billing'));
+      await expect(args.onSelectItem).toHaveBeenCalledWith('billing');
+    });
+  },
+};
+
+export const SearchFilters: Story = {
+  name: '🔎 Search Filter Test',
+  render: () => (
+    <SettingsLayout title="Settings" groups={GROUPS} activeItemId="profile">
+      {panel}
+    </SettingsLayout>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const search = canvas.getByTestId('settings-search').querySelector('input');
+
+    await step('Typing a label narrows the rail', async () => {
+      await userEvent.type(search as HTMLInputElement, 'secur');
+      await expect(canvas.getByTestId('settings-item-security')).toBeInTheDocument();
+      await waitFor(() => {
+        expect(canvas.queryByTestId('settings-item-profile')).not.toBeInTheDocument();
+        expect(canvas.queryByTestId('settings-group-workspace')).not.toBeInTheDocument();
+      });
+    });
+
+    await step('Keywords are matched too', async () => {
+      await userEvent.clear(search as HTMLInputElement);
+      await userEvent.type(search as HTMLInputElement, 'password');
+      await expect(canvas.getByTestId('settings-item-security')).toBeInTheDocument();
+    });
+
+    await step('No match shows the empty state', async () => {
+      await userEvent.clear(search as HTMLInputElement);
+      await userEvent.type(search as HTMLInputElement, 'zzzzz');
+      await expect(canvas.getByTestId('settings-empty')).toBeInTheDocument();
+    });
+  },
+};
+
+export const LinkMode: Story = {
+  name: '🔗 Link Mode Test',
+  render: () => {
+    const linked: SettingsNavGroup[] = GROUPS.map((group) => ({
+      ...group,
+      items: group.items.map((item) => ({ ...item, href: `#/settings/${item.id}` })),
+    }));
+    return (
+      <SettingsLayout title="Settings" groups={linked} activeItemId="profile" linkComponent="a">
+        {panel}
+      </SettingsLayout>
+    );
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Items with href render as anchors', async () => {
+      const item = canvas.getByTestId('settings-item-security');
+      await expect(item.tagName.toLowerCase()).toBe('a');
+      await expect(item).toHaveAttribute('href', '#/settings/security');
+    });
+  },
+};
+
+export const KeyboardNavigation: Story = {
+  name: '⌨️ Keyboard Navigation Test',
+  render: () => (
+    <SettingsLayout title="Settings" groups={GROUPS} activeItemId="profile">
+      {panel}
+    </SettingsLayout>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step('Search field is focusable and typeable', async () => {
+      const input = canvas.getByTestId('settings-search').querySelector('input') as HTMLInputElement;
+      await userEvent.click(input);
+      await waitFor(() => expect(input).toHaveFocus());
+      await userEvent.keyboard('pro');
+      await expect(canvas.getByTestId('settings-item-profile')).toBeInTheDocument();
+    });
+  },
+};

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

@@ -0,0 +1,69 @@
+'use client';
+
+import { Box } from '@mui/material';
+import React, { useMemo, useState } from 'react';
+
+import { activeItemLabel, filterGroups, SettingsRail } from './SettingsLayout.parts';
+import type { SettingsLayoutProps } from './SettingsLayout.types';
+
+/**
+ * A reusable, agnostic Facebook-style settings shell: a searchable left rail of
+ * grouped categories/subcategories and a central panel that renders the selected
+ * configuration screen (`children`). Navigation is data-driven via `groups`; the
+ * host owns routing (pass `linkComponent` + item `href`, or handle `onSelectItem`).
+ *
+ * Below `md` the rail collapses into a compact section-switcher (tap to reveal the
+ * search + groups) so the panel content stays at the top on phones.
+ */
+export const SettingsLayout: React.FC<SettingsLayoutProps> = ({
+  title,
+  groups,
+  activeItemId,
+  onSelectItem,
+  searchPlaceholder = 'Search settings',
+  emptySearchLabel = 'No settings match your search.',
+  linkComponent,
+  children,
+  testIdPrefix = 'settings',
+}) => {
+  const [query, setQuery] = useState('');
+  const [navOpen, setNavOpen] = useState(false);
+  const filteredGroups = useMemo(() => filterGroups(groups, query), [groups, query]);
+  const activeLabel = useMemo(() => activeItemLabel(groups, activeItemId), [groups, activeItemId]);
+
+  return (
+    <Box
+      data-testid={testIdPrefix}
+      sx={{
+        display: 'flex',
+        flexDirection: { xs: 'column', md: 'row' },
+        alignItems: 'stretch',
+        gap: { xs: 1.5, md: 3 },
+        width: '100%',
+      }}
+    >
+      <SettingsRail
+        title={title}
+        activeLabel={activeLabel}
+        navOpen={navOpen}
+        onToggleNav={() => setNavOpen((open) => !open)}
+        query={query}
+        onQueryChange={setQuery}
+        searchPlaceholder={searchPlaceholder}
+        emptySearchLabel={emptySearchLabel}
+        filteredGroups={filteredGroups}
+        activeItemId={activeItemId}
+        linkComponent={linkComponent}
+        onSelectItem={onSelectItem}
+        onNavigate={() => setNavOpen(false)}
+        testIdPrefix={testIdPrefix}
+      />
+
+      <Box data-testid={`${testIdPrefix}-panel`} sx={{ flex: '1 1 auto', minWidth: 0, width: '100%' }}>
+        {children}
+      </Box>
+    </Box>
+  );
+};
+
+SettingsLayout.displayName = 'SettingsLayout';

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

@@ -0,0 +1,61 @@
+import type { ElementType, ReactNode } from 'react';
+
+/**
+ * A single navigable configuration entry inside a {@link SettingsNavGroup}. The
+ * `id` drives the active highlight and `data-testid`; `label` (plus optional
+ * `keywords`) is what the rail search field matches against.
+ */
+export interface SettingsNavItem {
+  /** Stable id — drives the active highlight + `data-testid`; never derived from `href`. */
+  id: string;
+  /** Visible label; also matched (case-insensitive) by the search field. */
+  label: string;
+  /** Optional leading icon. */
+  icon?: ReactNode;
+  /** Optional link target; rendered through `linkComponent` when set. */
+  href?: string;
+  /** Extra search terms so an item is findable beyond its visible label. */
+  keywords?: string[];
+}
+
+/** A labelled category grouping related items in the left rail. */
+export interface SettingsNavGroup {
+  /** Stable id for the group header's `data-testid`. */
+  id: string;
+  /** Category header label (uppercased in the rail). */
+  label: string;
+  /** Optional one-line description shown under the header. */
+  description?: string;
+  /** The subcategories/items in this group. */
+  items: SettingsNavItem[];
+}
+
+/**
+ * Props for {@link SettingsLayout} — an agnostic, data-driven two-pane settings
+ * shell (search + grouped left rail, central panel). It renders navigation from
+ * `groups` and the selected screen from `children`; the host owns routing.
+ */
+export interface SettingsLayoutProps {
+  /** Heading shown above the search field (e.g. "Configuração"). */
+  title?: ReactNode;
+  /** Grouped navigation for the left rail. */
+  groups: SettingsNavGroup[];
+  /** Id of the currently-open item — highlighted in the rail. */
+  activeItemId?: string;
+  /** Fired with an item's id when a non-link item is chosen. */
+  onSelectItem?: (id: string) => void;
+  /** Placeholder for the search field. Defaults to `"Search settings"`. */
+  searchPlaceholder?: string;
+  /** Shown when the search matches no items. Defaults to a generic string. */
+  emptySearchLabel?: ReactNode;
+  /**
+   * Element type used to render an item that has an `href` (e.g. a Next.js
+   * `Link`). Rendered as the `ListItemButton` `component`, so navigation stays a
+   * single interactive element. Items without `href` fall back to `onSelectItem`.
+   */
+  linkComponent?: ElementType;
+  /** The central panel content (the selected configuration screen). */
+  children: ReactNode;
+  /** Prefix for `data-testid` attributes. Defaults to `"settings"`. */
+  testIdPrefix?: string;
+}

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

@@ -0,0 +1,6 @@
+export { SettingsLayout } from './SettingsLayout';
+export type {
+  SettingsLayoutProps,
+  SettingsNavGroup,
+  SettingsNavItem,
+} from './SettingsLayout.types';