@12-apps/ui 3.2.0 → 3.4.0

package/src/components/navigation/AppHeader/AppHeader.details.tsx

@@ -0,0 +1,227 @@
+'use client';
+
+import { Box, Typography, useMediaQuery, useTheme } from '@mui/material';
+import React from 'react';
+
+import { accentFor } from '../../../tokens/scales';
+import { Sheet } from '../../data-display/Sheet/Sheet';
+import { Button } from '../../form/Button/Button';
+import { Dialog } from '../../feedback/Dialog/Dialog';
+
+import type {
+  AppHeaderDetailRow,
+  AppHeaderDetailsAction,
+  AppHeaderDetailsProps,
+} from './AppHeader.types';
+
+/** How wide the dialog presentation grows before it stops. */
+const DIALOG_WIDTH = 460;
+
+/**
+ * Where the smallest phones stop. The theme's scale starts at `xs`/`sm`, so
+ * there is no `xxs` breakpoint to ask for — this is that boundary, named once
+ * rather than inlined at the place it decides something.
+ */
+const XXS_MAX_WIDTH = 360;
+
+/**
+ * The sheet grows to its content and stops at the viewport; it does not take a
+ * fixed slab of height.
+ *
+ * `Sheet`'s vertical presets are absolute (`md` is 400px), which on a phone is
+ * shorter than six detail rows plus a button — so the panel scrolled INSIDE a
+ * screen that had room to spare, putting the address and the way out below the
+ * fold of a sheet using two thirds of the display. `height: auto` sizes it to
+ * what is in it, and the cap keeps a long panel on-screen: 100dvh on the
+ * smallest phones where every pixel counts, 90dvh above that so the panel still
+ * reads as a sheet over a page rather than as a new screen.
+ *
+ * `dvh` and not `vh` — mobile browser chrome makes `vh` overshoot, which would
+ * reintroduce exactly the scroll this removes.
+ */
+function sheetHeight(xxs: boolean): { height: string; maxHeight: string } {
+  return { height: 'auto', maxHeight: xxs ? '100dvh' : '90dvh' };
+}
+
+/** Which surface this viewport calls for. Lifted out to keep the component lean. */
+function usesSheet(presentation: AppHeaderDetailsProps['presentation'], compact: boolean): boolean {
+  if (presentation === 'sheet') return true;
+  if (presentation === 'dialog') return false;
+  return compact;
+}
+
+/** One label/value line. The value may wrap to two lines; the label may not. */
+const DetailRow: React.FC<{ row: AppHeaderDetailRow; last: boolean; dataTestId: string }> = ({
+  row,
+  last,
+  dataTestId,
+}) => {
+  const theme = useTheme();
+  return (
+    <Box
+      data-testid={`${dataTestId}-row`}
+      data-row={row.id ?? row.label}
+      sx={{
+        display: 'flex',
+        alignItems: 'flex-start',
+        justifyContent: 'space-between',
+        gap: 2,
+        py: 1.5,
+        borderBottom: last ? 'none' : `1px solid ${theme.palette.divider}`,
+      }}
+    >
+      <Typography variant="body1" color="text.secondary" component="span" sx={{ flex: '0 0 auto' }}>
+        {row.label}
+      </Typography>
+      <Typography
+        variant="body1"
+        component="span"
+        sx={{
+          minWidth: 0,
+          textAlign: 'right',
+          fontWeight: row.tone ? 700 : 500,
+          color: row.tone ? accentFor(theme, row.tone).main : 'text.primary',
+          // Newlines in a value are meaningful — an address is two lines.
+          whiteSpace: 'pre-line',
+        }}
+      >
+        {row.value}
+      </Typography>
+    </Box>
+  );
+};
+
+/** The rows plus whatever the caller put under them. */
+const DetailsBody: React.FC<
+  Pick<AppHeaderDetailsProps, 'rows' | 'children'> & { dataTestId: string }
+> = ({ rows, children, dataTestId }) => (
+  <Box data-testid={`${dataTestId}-body`}>
+    {(rows ?? []).map((row, index) => (
+      <DetailRow
+        key={row.id ?? row.label}
+        row={row}
+        last={index === (rows?.length ?? 0) - 1 && !children}
+        dataTestId={dataTestId}
+      />
+    ))}
+    {children}
+  </Box>
+);
+
+/**
+ * The single full-width call to action, or nothing.
+ *
+ * `padded` is for the dialog, which has no footer slot of its own — and the
+ * padding lives here rather than at the call site so an action-less panel does
+ * not end in a strip of empty space.
+ */
+const DetailsAction: React.FC<{
+  action?: AppHeaderDetailsAction;
+  dataTestId: string;
+  padded?: boolean;
+}> = ({ action, dataTestId, padded = false }) =>
+  action ? (
+    <Box sx={padded ? { pt: 2 } : undefined}>
+      <Button
+        variant="solid"
+        color={action.color ?? 'primary'}
+        size="lg"
+        fullWidth
+        disabled={action.disabled}
+        onClick={action.onClick}
+        dataTestId={action.dataTestId ?? `${dataTestId}-action`}
+      >
+        {action.label}
+      </Button>
+    </Box>
+  ) : null;
+
+/**
+ * The panel behind the header's disclosure — the hours, the address, the way
+ * out — in the shape the viewport calls for.
+ *
+ * ONE component with two presentations, because they are one thing to the user
+ * and one thing to the caller: a bottom sheet within reach of a thumb, a centred
+ * dialog under a pointer. `auto` picks by viewport, so nobody writes that branch
+ * at a call site and nobody ships a phone-shaped sheet stretched across a
+ * desktop. Force either one with `presentation` when the surrounding layout
+ * already decides (a preview frame, a story, a kiosk).
+ */
+export const AppHeaderDetails: React.FC<AppHeaderDetailsProps> = ({
+  open,
+  onClose,
+  title,
+  subtitle,
+  rows,
+  children,
+  action,
+  presentation = 'auto',
+  breakpoint = 'sm',
+  className,
+  dataTestId = 'app-header-details',
+}) => {
+  const theme = useTheme();
+  const asSheet = usesSheet(presentation, useMediaQuery(theme.breakpoints.down(breakpoint)));
+  const xxs = useMediaQuery(`(max-width:${XXS_MAX_WIDTH - 0.05}px)`);
+
+  // Split once, not per branch: a STRING subtitle is the panel's own
+  // `description` (both surfaces style it as part of their header), anything
+  // richer is a node we render ourselves above the rows.
+  const description = typeof subtitle === 'string' ? subtitle : undefined;
+  const richSubtitle = description === undefined ? subtitle : null;
+
+  const body = (
+    <DetailsBody rows={rows} dataTestId={dataTestId}>
+      {children}
+    </DetailsBody>
+  );
+  const footer = <DetailsAction action={action} dataTestId={dataTestId} />;
+
+  if (asSheet) {
+    // No `showHandle`. The grab bar promises a drag this panel does not answer:
+    // its height is its content's, so there is no second position to drag it
+    // to, and the handle sat above a ✕ that already closes it. Swipe-to-dismiss
+    // is `Sheet`'s default and still works — it just stops being advertised by
+    // a control that looked resizable and was not.
+    return (
+      <Sheet
+        open={open}
+        onClose={onClose}
+        onOpenChange={(next) => !next && onClose()}
+        position="bottom"
+        size="md"
+        style={sheetHeight(xxs)}
+        className={className}
+        title={title}
+        description={description}
+        showCloseButton
+        rounded
+        footer={footer}
+        dataTestId={dataTestId}
+      >
+        {richSubtitle}
+        {body}
+      </Sheet>
+    );
+  }
+
+  return (
+    <Dialog
+      open={open}
+      onClose={onClose}
+      title={title}
+      description={description}
+      showCloseButton
+      fullWidth
+      className={className}
+      dataTestId={dataTestId}
+      PaperProps={{ sx: { maxWidth: DIALOG_WIDTH, borderRadius: 3 } }}
+    >
+      {richSubtitle}
+      {body}
+      <DetailsAction action={action} dataTestId={dataTestId} padded />
+    </Dialog>
+  );
+};
+
+AppHeaderDetails.displayName = 'AppHeaderDetails';

package/src/components/navigation/AppHeader/AppHeader.identity.tsx

@@ -0,0 +1,251 @@
+'use client';
+
+import KeyboardArrowDown from '@mui/icons-material/KeyboardArrowDown';
+import { Box, Skeleton, Typography, useTheme } from '@mui/material';
+import React from 'react';
+
+import { accentFor, type SizeValue } from '../../../tokens/scales';
+
+import { AppHeaderBrand } from './AppHeader.brand';
+import type { AppHeaderIdentityProps, AppHeaderStatusProps } from './AppHeader.types';
+
+/** Title type scale, per house size step. */
+const TITLE_PX: Record<SizeValue, number> = { xs: 14, sm: 15, md: 17, lg: 20, xl: 24 };
+
+/** One line, ellipsised — a long store name must not push the actions off-screen. */
+const ONE_LINE = {
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+} as const;
+
+/**
+ * The dotted state line: "● Aberto agora · Retirada no balcão".
+ *
+ * Segments are joined here rather than by the caller because the separator is a
+ * presentational choice — a caller that pre-joins its own string can never be
+ * restyled, and each segment loses the chance to carry its own markup.
+ */
+export const AppHeaderStatus: React.FC<AppHeaderStatusProps> = ({
+  tone,
+  items,
+  separator = '·',
+  className,
+  dataTestId = 'app-header-status',
+}) => {
+  const theme = useTheme();
+  const visible = items.filter((item) => item !== null && item !== undefined && item !== '');
+  if (visible.length === 0) return null;
+
+  return (
+    <Box
+      className={className}
+      data-testid={dataTestId}
+      sx={{ display: 'flex', alignItems: 'center', gap: 0.75, ...ONE_LINE }}
+    >
+      {tone && (
+        <Box
+          aria-hidden
+          data-testid={`${dataTestId}-dot`}
+          sx={{
+            width: 8,
+            height: 8,
+            flex: '0 0 auto',
+            borderRadius: '50%',
+            backgroundColor: accentFor(theme, tone).main,
+          }}
+        />
+      )}
+      <Typography variant="body2" color="text.secondary" component="span" sx={ONE_LINE}>
+        {visible.map((item, index) => (
+          // Index keys: the segments are positional presentation, and nothing
+          // here reorders or is keyed on identity elsewhere.
+          <React.Fragment key={index}>
+            {index > 0 && (
+              <>
+                {/* Real spaces, not margin. A screen reader reads `textContent`,
+                    and a CSS-only gap runs "Aberto agora" straight into
+                    "Retirada no balcão" as one word. The glyph itself is
+                    hidden — it is punctuation, not something to announce. */}
+                {' '}
+                <Box component="span" aria-hidden>
+                  {separator}
+                </Box>{' '}
+              </>
+            )}
+            {item}
+          </React.Fragment>
+        ))}
+      </Typography>
+    </Box>
+  );
+};
+
+AppHeaderStatus.displayName = 'AppHeaderStatus';
+
+/** Title + chevron + the quieter lines under them. */
+const IdentityText: React.FC<
+  Pick<AppHeaderIdentityProps, 'title' | 'subtitle' | 'status' | 'size'> & {
+    interactive: boolean;
+    disclosed: boolean;
+    dataTestId: string;
+  }
+> = ({ title, subtitle, status, size = 'md', interactive, disclosed, dataTestId }) => (
+  <Box sx={{ minWidth: 0, display: 'flex', flexDirection: 'column', gap: 0.25 }}>
+    <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.25, minWidth: 0 }}>
+      <Typography
+        component="span"
+        data-testid={`${dataTestId}-title`}
+        sx={{ fontSize: TITLE_PX[size], fontWeight: 700, lineHeight: 1.2, ...ONE_LINE }}
+      >
+        {title}
+      </Typography>
+      {interactive && (
+        <KeyboardArrowDown
+          aria-hidden
+          data-testid={`${dataTestId}-chevron`}
+          sx={{
+            flex: '0 0 auto',
+            fontSize: 20,
+            opacity: 0.7,
+            transition: 'transform 150ms ease',
+            transform: disclosed ? 'rotate(180deg)' : 'none',
+          }}
+        />
+      )}
+    </Box>
+    {subtitle && (
+      <Typography variant="body2" color="text.secondary" component="span" sx={ONE_LINE}>
+        {subtitle}
+      </Typography>
+    )}
+    {status}
+  </Box>
+);
+
+/** The placeholder held while the identity is still resolving. */
+const IdentitySkeleton: React.FC<{ size: SizeValue; dataTestId: string }> = ({
+  size,
+  dataTestId,
+}) => (
+  <Box
+    data-testid={`${dataTestId}-loading`}
+    sx={{ display: 'flex', alignItems: 'center', gap: 1.25, minWidth: 0 }}
+  >
+    <Skeleton variant="rounded" width={40} height={40} sx={{ flex: '0 0 auto' }} />
+    <Box sx={{ minWidth: 0, flex: 1 }}>
+      <Skeleton variant="text" width={140} height={TITLE_PX[size] * 1.4} />
+      <Skeleton variant="text" width={180} height={16} />
+    </Box>
+  </Box>
+);
+
+/**
+ * Row styling shared by the static and the button rendering.
+ *
+ * `width: '100%'` is load-bearing, not cosmetic. A `<button>` sizes to
+ * max-content and — unlike the `div` the non-interactive path renders — does
+ * not stretch to fill its block container, so without it the DISCLOSING
+ * identity measured its widest possible line at every viewport: the row's
+ * right edge stayed pinned at 564px while the bar narrowed, `ONE_LINE` never
+ * had a constraint to ellipsise against, and the title and state line ran
+ * straight under the actions — 327px of overlap at 320px wide. Filling the
+ * wrapper is what lets `minWidth: 0` bite and the ellipsis engage.
+ */
+const rowSx = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 1.25,
+  width: '100%',
+  minWidth: 0,
+  textAlign: 'left',
+} as const;
+
+/**
+ * Mark + title + state line, and — when it can be opened — the whole block as
+ * one button.
+ *
+ * The button wraps EVERYTHING rather than sitting next to the title, because on
+ * a phone the chevron alone is a 20px target next to a 40px one that does
+ * nothing. A shopper aiming at the store's name expects the store's details.
+ */
+export const AppHeaderIdentity: React.FC<AppHeaderIdentityProps> = ({
+  title,
+  subtitle,
+  status,
+  mark,
+  logoUrl,
+  seedColor,
+  onDisclose,
+  disclosed = false,
+  discloseLabel,
+  loading = false,
+  size = 'md',
+  className,
+  dataTestId = 'app-header-identity',
+}) => {
+  if (loading) return <IdentitySkeleton size={size} dataTestId={dataTestId} />;
+
+  const body = (
+    <>
+      {mark ?? (
+        <AppHeaderBrand
+          name={title}
+          logoUrl={logoUrl}
+          seedColor={seedColor}
+          size={size}
+          dataTestId={`${dataTestId}-brand`}
+        />
+      )}
+      <IdentityText
+        title={title}
+        subtitle={subtitle}
+        status={status}
+        size={size}
+        interactive={Boolean(onDisclose)}
+        disclosed={disclosed}
+        dataTestId={dataTestId}
+      />
+    </>
+  );
+
+  if (!onDisclose) {
+    return (
+      <Box className={className} data-testid={dataTestId} sx={rowSx}>
+        {body}
+      </Box>
+    );
+  }
+
+  return (
+    <Box
+      component="button"
+      type="button"
+      className={className}
+      data-testid={dataTestId}
+      onClick={onDisclose}
+      aria-haspopup="dialog"
+      aria-expanded={disclosed}
+      aria-label={discloseLabel ?? `Detalhes de ${title}`}
+      sx={{
+        ...rowSx,
+        appearance: 'none',
+        p: 0.5,
+        ml: -0.5,
+        border: 'none',
+        borderRadius: 1.5,
+        background: 'none',
+        color: 'inherit',
+        font: 'inherit',
+        cursor: 'pointer',
+        '&:hover': { backgroundColor: 'action.hover' },
+        '&:focus-visible': { outline: '2px solid', outlineColor: 'primary.main', outlineOffset: 2 },
+      }}
+    >
+      {body}
+    </Box>
+  );
+};
+
+AppHeaderIdentity.displayName = 'AppHeaderIdentity';

package/src/components/navigation/AppHeader/AppHeader.md

@@ -0,0 +1,138 @@
+# AppHeader
+
+The application bar, as a set of slots on one surface — plus the identity block,
+the state line and the disclosure panel that usually fill them.
+
+It is deliberately ignorant. There is no router in it, no session, no cart, no
+store: every slot is a `ReactNode` and every behaviour is a callback. That is
+what lets one bar serve a storefront, a back office and a platform console
+without any of the three leaking into the other two.
+
+```tsx
+import {
+  AppHeader,
+  AppHeaderDetails,
+  AppHeaderIdentity,
+  AppHeaderStatus,
+} from '@12-apps/ui/navigation/AppHeader';
+
+const [open, setOpen] = useState(false);
+
+<AppHeader
+  meta="Build 18"
+  actions={<Button onClick={signIn}>Entrar</Button>}
+  below={<SearchField />}
+>
+  <AppHeaderIdentity
+    title={store.name}
+    logoUrl={store.logoUrl}
+    seedColor={store.primaryColor}
+    status={<AppHeaderStatus tone="success" items={['Aberto agora', 'Retirada no balcão']} />}
+    disclosed={open}
+    onDisclose={() => setOpen(true)}
+  />
+</AppHeader>
+
+<AppHeaderDetails
+  open={open}
+  onClose={() => setOpen(false)}
+  title={store.name}
+  subtitle={store.tagline}
+  rows={[
+    { label: 'Agora', value: 'Aberto até 22h', tone: 'success' },
+    { label: 'Endereço', value: `${store.street}\n${store.district}` },
+  ]}
+  action={{ label: 'Trocar de loja', onClick: goToStorePicker }}
+/>;
+```
+
+## The parts
+
+| Component            | What it is                                                       |
+| -------------------- | ---------------------------------------------------------------- |
+| `AppHeader`          | The bar: `leading`, the identity (children), `actions`, `meta`, `below` |
+| `AppHeaderIdentity`  | Mark + title + state line, and the disclosure when it can open one |
+| `AppHeaderBrand`     | The mark alone — a logo, or initials on a gradient derived from one colour |
+| `AppHeaderStatus`    | The dotted state line: `● Aberto agora · Retirada no balcão`      |
+| `AppHeaderDetails`   | The panel behind the disclosure — a sheet on phones, a dialog on large screens |
+
+Each is exported on its own, so a bar that wants only the mark, or only the
+state line, takes just that.
+
+## One bar, every width
+
+The SURFACE always spans the viewport; the CONTENT stops at `maxWidth` (1200 by
+default) and centres. So the same element reads as a phone header and as a
+desktop one, with no breakpoint at the call site and no second component.
+
+`AppHeaderDetails` follows the same rule one level down. It is one component
+with two presentations because it is one thing to the user — a bottom sheet
+within reach of a thumb, a centred dialog under a pointer — and `presentation:
+'auto'` (the default) picks by viewport. Force it with `'sheet'` or `'dialog'`
+when the surrounding layout has already decided: a preview frame, a kiosk, a
+story.
+
+The sheet is **as tall as what is in it**, capped at the viewport — `100dvh`
+below 360px, `90dvh` above it. It does not take a fixed slab of height:
+`Sheet`'s vertical presets are absolute (`md` is 400px), which is shorter than
+six rows plus a button, so the panel scrolled INSIDE a screen that had room to
+spare and left the address and the way out below its own fold. `dvh` and not
+`vh`, because mobile browser chrome makes `vh` overshoot and would put that
+scroll straight back.
+
+It carries no grab handle either. There is no second position to drag the panel
+to now that its height is its content's, so the handle promised a resize it
+could not answer while sitting directly above a ✕ that already closes it.
+Swipe-to-dismiss is `Sheet`'s default and still works.
+
+## One brand colour is enough
+
+`seedColor` takes a single hex and the mark derives its own gradient from it, by
+rotating the seed's hue toward the warm side and lifting its lightness. With no
+seed it derives from the theme's primary instead, so an app with no per-tenant
+colour needs to pass nothing.
+
+The alternative — a second "highlight" prop — asks every caller to pick a colour
+that pairs with a colour they already picked, and in a multi-tenant app it asks
+that of people who will never see this component. A seed with no hue worth
+rotating (a grey, a black) stays grey: a hueless brand is not given a colour it
+never chose. A seed the browser cannot parse is returned untouched rather than
+throwing.
+
+## What it will not do
+
+- **Navigate.** There is no `href` on the identity. An `href` would have to guess
+  whose link component it is being handed — `to` for one router, `href` for
+  another — and would half-work for everybody. A title that navigates is one line
+  of your own router in the `leading` slot.
+- **Fetch anything.** `loading` on the identity holds a skeleton the size of the
+  real block; you decide when that is true. It exists because the obvious
+  fallback is actively wrong on a white-label storefront: painting a placeholder
+  name flashes the platform's brand for a frame on every load, on a page a
+  merchant pays for it not to appear on.
+- **Own its own open state.** `AppHeaderDetails` is controlled. The disclosure
+  and the panel are separate components precisely so the panel can live wherever
+  the layout needs it.
+
+## Accessibility
+
+- The mark is `role="img"` labelled with the name, so a screen reader says
+  "Future Drink" rather than spelling out "F D".
+- With `onDisclose`, the whole identity block is one `<button>` with
+  `aria-haspopup="dialog"` and a live `aria-expanded`. The button wraps
+  everything rather than sitting beside the title: on a phone the chevron alone
+  is a 20px target next to a 40px one that does nothing, and a shopper aiming at
+  the store's name expects the store's details.
+- The state line separates its segments with real whitespace, not CSS margin —
+  a screen reader reads `textContent`, and a margin-only gap runs "Aberto agora"
+  straight into "Retirada no balcão" as one word. The separator glyph itself is
+  `aria-hidden`: it is punctuation, not something to announce.
+- A `fixed` bar renders a spacer of its own MEASURED height. A constant cannot
+  do it — the height is whatever your slots add up to, and a search field in
+  `below` moves it — so the bar observes itself and republishes. Where
+  `ResizeObserver` does not exist (jsdom, so: your tests) it measures once
+  instead of throwing.
+
+## Props
+
+See `AppHeader.types.ts`. Every prop is documented at its declaration.