@12-apps/ui 3.2.0 → 3.4.0

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

@@ -0,0 +1,232 @@
+'use client';
+
+import { Box } from '@mui/material';
+import React from 'react';
+
+import { withDefaults } from '../../../utils/withDefaults';
+
+import type { AppHeaderProps } from './AppHeader.types';
+
+/** Bar height, before the optional `below` row. */
+const BAR_MIN_HEIGHT = { regular: 64, dense: 52 } as const;
+
+/** The props {@link HEADER_DEFAULTS} guarantees a value for. */
+type Defaulted =
+  | 'position'
+  | 'offsetTop'
+  | 'maxWidth'
+  | 'divider'
+  | 'elevateOnScroll'
+  | 'dense'
+  | 'disableSpacer'
+  | 'dataTestId';
+
+/** `AppHeaderProps` as the body sees them: nothing defaulted is still optional. */
+type ResolvedHeaderProps = AppHeaderProps & Required<Pick<AppHeaderProps, Defaulted>>;
+
+const HEADER_DEFAULTS: Pick<ResolvedHeaderProps, Defaulted> = {
+  position: 'sticky',
+  offsetTop: 0,
+  maxWidth: 1200,
+  divider: true,
+  elevateOnScroll: false,
+  dense: false,
+  disableSpacer: false,
+  dataTestId: 'app-header',
+};
+
+/**
+ * Watch the document scroll so a lifted bar can cast a shadow only once there
+ * is something under it. Inert (and never attaches a listener) when off.
+ */
+function useScrolled(enabled: boolean): boolean {
+  const [scrolled, setScrolled] = React.useState(false);
+  React.useEffect(() => {
+    if (!enabled) return undefined;
+    const onScroll = (): void => setScrolled(window.scrollY > 0);
+    onScroll();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    return () => window.removeEventListener('scroll', onScroll);
+  }, [enabled]);
+  return enabled && scrolled;
+}
+
+/**
+ * The bar's own height, republished whenever it changes.
+ *
+ * A `fixed` bar is out of flow, so something has to reserve its space — and a
+ * constant cannot, because this bar's height is whatever the caller's slots add
+ * up to. A search field in `below`, a status line, a wrapped title: each moves
+ * it, and a hard-coded spacer would leave the page's first element under the
+ * bar or floating below a gap.
+ */
+function useMeasuredHeight(enabled: boolean): [React.RefObject<HTMLElement | null>, number] {
+  const ref = React.useRef<HTMLElement | null>(null);
+  const [height, setHeight] = React.useState(0);
+  React.useEffect(() => {
+    const node = ref.current;
+    if (!enabled || !node) return undefined;
+    const measure = (): void => setHeight(node.getBoundingClientRect().height);
+    measure();
+    // Measured once unconditionally, observed only where the API exists. jsdom
+    // has no ResizeObserver, so constructing it unguarded takes down every
+    // consumer's test that happens to render a fixed bar — a crash in THEIR
+    // suite, thrown from a component they only laid out.
+    if (typeof ResizeObserver === 'undefined') return undefined;
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [enabled]);
+  return [ref, height];
+}
+
+/**
+ * The bar's own surface. Lifted out of the component both to keep it inside the
+ * complexity bar and because the positioning rules are the fiddly part: a
+ * `static` bar must claim neither a stacking context nor an offset, and only a
+ * `fixed` one needs pinning to the viewport's edges.
+ */
+function surfaceSx({
+  position,
+  offsetTop,
+  divider,
+  scrolled,
+}: Required<Pick<AppHeaderProps, 'position' | 'offsetTop' | 'divider'>> & {
+  scrolled: boolean;
+}): Record<string, unknown> {
+  return {
+    position,
+    ...(position === 'static' ? {} : { top: offsetTop, zIndex: 'appBar' }),
+    ...(position === 'fixed' ? { left: 0, right: 0 } : {}),
+    backgroundColor: 'background.paper',
+    borderBottom: divider ? 1 : 0,
+    borderColor: 'divider',
+    boxShadow: scrolled ? 2 : 0,
+    transition: 'box-shadow 150ms ease',
+  };
+}
+
+/** The trailing column: the muted note, and the actions under it. */
+const HeaderTrailing: React.FC<Pick<AppHeaderProps, 'meta' | 'actions'>> = ({ meta, actions }) => {
+  if (!meta && !actions) return null;
+  return (
+    <Box
+      sx={{
+        flex: '0 0 auto',
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'flex-end',
+        gap: 0.5,
+      }}
+    >
+      {meta && (
+        <Box
+          data-testid="app-header-meta"
+          sx={{
+            fontSize: 11,
+            fontWeight: 700,
+            letterSpacing: '0.08em',
+            textTransform: 'uppercase',
+            color: 'text.disabled',
+            lineHeight: 1,
+          }}
+        >
+          {meta}
+        </Box>
+      )}
+      {actions && (
+        <Box
+          component="nav"
+          data-testid="app-header-actions"
+          sx={{ display: 'flex', alignItems: 'center', gap: 1 }}
+        >
+          {actions}
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+/**
+ * The application bar: a row of slots on one surface, plus an optional second
+ * row that belongs to it.
+ *
+ * It knows nothing about routers, sessions, carts or stores — every slot is a
+ * `ReactNode` and every behaviour is a callback, which is what lets one bar
+ * serve a storefront, a back office and a platform console without any of them
+ * leaking into the others. Compose it with {@link AppHeaderIdentity},
+ * {@link AppHeaderStatus} and {@link AppHeaderDetails}, or put your own nodes in
+ * the slots.
+ *
+ * The SURFACE always spans the viewport while the CONTENT stops at `maxWidth`
+ * and centres, so the same bar reads as a phone header and as a desktop one
+ * without a second component or a breakpoint at the call site.
+ */
+export const AppHeader: React.FC<AppHeaderProps> = (props) => {
+  // A table of defaults rather than one per destructured prop: each `= default`
+  // is a branch, and nine of them put this component over the complexity bar
+  // before it rendered anything.
+  const {
+    leading,
+    children,
+    actions,
+    meta,
+    below,
+    position,
+    offsetTop,
+    maxWidth,
+    divider,
+    elevateOnScroll,
+    dense,
+    disableSpacer,
+    className,
+    dataTestId,
+    // True by construction — `withDefaults` fills exactly these keys — but not
+    // something TS can follow through a `Partial<T>` table.
+  } = withDefaults(props, HEADER_DEFAULTS) as ResolvedHeaderProps;
+
+  const scrolled = useScrolled(elevateOnScroll);
+  const needsSpacer = position === 'fixed' && !disableSpacer;
+  const [ref, height] = useMeasuredHeight(needsSpacer);
+
+  return (
+    <>
+      <Box
+        ref={ref}
+        component="header"
+        className={className}
+        data-testid={dataTestId}
+        sx={surfaceSx({ position, offsetTop, divider, scrolled })}
+      >
+        <Box sx={{ maxWidth, mx: 'auto', px: { xs: 2, md: 3 } }}>
+          <Box
+            sx={{
+              display: 'flex',
+              alignItems: 'center',
+              gap: { xs: 1, md: 2 },
+              minHeight: dense ? BAR_MIN_HEIGHT.dense : BAR_MIN_HEIGHT.regular,
+              py: 1,
+            }}
+          >
+            {leading}
+            {/* The identity takes the slack and is the only part allowed to
+                shrink — the actions are targets and the meta note is already
+                the smallest thing in the bar. */}
+            <Box sx={{ flex: '1 1 auto', minWidth: 0 }}>{children}</Box>
+            <HeaderTrailing meta={meta} actions={actions} />
+          </Box>
+          {below && (
+            <Box data-testid={`${dataTestId}-below`} sx={{ pb: 1.5 }}>
+              {below}
+            </Box>
+          )}
+        </Box>
+      </Box>
+      {needsSpacer && <Box aria-hidden data-testid={`${dataTestId}-spacer`} sx={{ height }} />}
+    </>
+  );
+};
+
+AppHeader.displayName = 'AppHeader';
+
+export default AppHeader;

package/src/components/navigation/AppHeader/AppHeader.types.ts

@@ -0,0 +1,190 @@
+import type { Breakpoint } from '@mui/material/styles';
+import type { ReactNode } from 'react';
+
+import type { ColorValue, SizeValue } from '../../../tokens/scales';
+
+/**
+ * How the bar sits in the page.
+ *
+ * `fixed` lifts it out of flow, so {@link AppHeaderProps.disableSpacer} aside it
+ * also renders a spacer of its own measured height — a fixed bar with nothing
+ * reserving its space is the classic "first paragraph is under the header" bug.
+ */
+export type AppHeaderPosition = 'static' | 'sticky' | 'fixed';
+
+/** Which surface the details panel takes on this viewport. */
+export type AppHeaderDetailsPresentation = 'auto' | 'sheet' | 'dialog';
+
+/**
+ * The circular mark that opens the header: a logo when there is one, the name's
+ * initials on a derived gradient when there is not.
+ *
+ * The gradient is DERIVED from `seedColor` rather than configured, so a caller
+ * supplies one brand colour and gets a mark that belongs to it. With no seed it
+ * derives from the theme's primary, which is what makes the mark correct in an
+ * app that has no per-tenant colour at all.
+ */
+export interface AppHeaderBrandProps {
+  /** Who the mark stands for. Initials come from it, and it labels the mark. */
+  name: string;
+  /** Logo image; replaces the initials when it loads. */
+  logoUrl?: string | null;
+  /** `#RRGGBB` (or any CSS colour) to derive the gradient from. */
+  seedColor?: string | null;
+  /** @default 'md' */
+  size?: SizeValue;
+  /** @default 'circle' */
+  shape?: 'circle' | 'rounded';
+  className?: string;
+  dataTestId?: string;
+}
+
+/**
+ * The one-line state under the title — a tone dot plus segments read as a
+ * sentence ("Aberto agora · Retirada no balcão").
+ */
+export interface AppHeaderStatusProps {
+  /** The dot's colour. Omit for no dot. */
+  tone?: ColorValue;
+  /** The segments, in reading order. Empty entries are dropped. */
+  items: ReactNode[];
+  /** What goes between segments. @default '·' */
+  separator?: ReactNode;
+  className?: string;
+  dataTestId?: string;
+}
+
+/**
+ * Mark + title + status, optionally the control that discloses the details
+ * panel.
+ *
+ * There is deliberately no `href` here. A title that navigates is one line of
+ * the consumer's own router in the `leading` slot, whereas an `href` prop would
+ * have to guess whose link component it is being handed — `to` for one router,
+ * `href` for another — and would half-work for everybody. `onDisclose` is the
+ * only interaction the block owns: with it the block is a button and a chevron
+ * appears, without it the block is static text.
+ */
+export interface AppHeaderIdentityProps
+  extends Pick<AppHeaderBrandProps, 'logoUrl' | 'seedColor'> {
+  /** The name shown, and the one the mark derives its initials from. */
+  title: string;
+  /** A quieter line under the title — use `status` for the dotted state line. */
+  subtitle?: ReactNode;
+  /** The state line, usually an {@link AppHeaderStatusProps} element. */
+  status?: ReactNode;
+  /** Replaces the derived mark entirely (an icon, an `<img>`, nothing). */
+  mark?: ReactNode;
+  /** Opens the details panel. Renders the block as a button with a chevron. */
+  onDisclose?: () => void;
+  /** Whether the panel `onDisclose` opens is currently open (`aria-expanded`). */
+  disclosed?: boolean;
+  /** Accessible name of the disclosure. @default `Detalhes de {title}` */
+  discloseLabel?: string;
+  /**
+   * The identity is still being resolved — hold a skeleton the size of the real
+   * block rather than a fallback name. An app that paints a placeholder title
+   * flashes the wrong brand for a frame on every load.
+   */
+  loading?: boolean;
+  /** @default 'md' */
+  size?: SizeValue;
+  className?: string;
+  dataTestId?: string;
+}
+
+/**
+ * The bar itself: a row of slots on a surface, with an optional second row that
+ * belongs to the same surface (search, tabs, chips).
+ *
+ * Every slot is a `ReactNode`, so the header knows nothing about sessions,
+ * routers, carts or stores — it lays out what it is handed.
+ */
+export interface AppHeaderProps {
+  /** Before the identity: a back arrow, a menu toggle, a logo. */
+  leading?: ReactNode;
+  /** The identity block. Usually an `AppHeaderIdentity`. */
+  children?: ReactNode;
+  /** Trailing controls: sign-in, cart, account avatar. */
+  actions?: ReactNode;
+  /**
+   * A small muted note pinned to the top-right corner above `actions` — a build
+   * tag, an environment name. Hidden from assistive tech is NOT the default: if
+   * it is worth showing it is worth reading.
+   */
+  meta?: ReactNode;
+  /** A second row inside the same surface: a search field, tabs, filter chips. */
+  below?: ReactNode;
+  /** @default 'sticky' */
+  position?: AppHeaderPosition;
+  /**
+   * A CSS length the bar offsets itself by when `sticky`/`fixed` — for whatever
+   * already occupies the top of the viewport (an impersonation banner, an
+   * offline bar). Accepts a `var(--x, 0px)` so the offset can be published by
+   * the element itself. @default 0
+   */
+  offsetTop?: number | string;
+  /**
+   * How wide the content may grow before it stops and centres. This is what
+   * makes one bar work on a phone and on a desktop: the surface still spans the
+   * viewport, the content does not. @default 1200
+   */
+  maxWidth?: number | string;
+  /** Draw the bottom border. @default true */
+  divider?: boolean;
+  /** Raise a shadow once the page has scrolled under the bar. @default false */
+  elevateOnScroll?: boolean;
+  /** Tighter vertical rhythm, for a bar with no status line. @default false */
+  dense?: boolean;
+  /** Skip the flow spacer a `fixed` bar renders. @default false */
+  disableSpacer?: boolean;
+  className?: string;
+  dataTestId?: string;
+}
+
+/** One label/value line in the details panel. */
+export interface AppHeaderDetailRow {
+  /** Stable key; falls back to the label. */
+  id?: string;
+  label: string;
+  value: ReactNode;
+  /** Accent the value ("Aberto até 22h" in success green). */
+  tone?: ColorValue;
+}
+
+/** The details panel's single full-width call to action. */
+export interface AppHeaderDetailsAction {
+  label: string;
+  onClick: () => void;
+  /** @default 'primary' */
+  color?: ColorValue;
+  disabled?: boolean;
+  dataTestId?: string;
+}
+
+/**
+ * The panel the identity's disclosure opens.
+ *
+ * It is ONE component with two presentations because they are one thing to the
+ * user: a bottom sheet where the thumb is, a centred dialog where the pointer
+ * is. `presentation: 'auto'` picks by viewport so a caller never writes that
+ * branch — and never ships a phone-sized sheet stretched across a desktop.
+ */
+export interface AppHeaderDetailsProps {
+  open: boolean;
+  onClose: () => void;
+  title: string;
+  subtitle?: ReactNode;
+  /** The label/value lines. Rendered above `children`. */
+  rows?: AppHeaderDetailRow[];
+  /** Anything the rows cannot express — a map, a note, a list. */
+  children?: ReactNode;
+  /** The single full-width action at the foot of the panel. */
+  action?: AppHeaderDetailsAction;
+  /** @default 'auto' */
+  presentation?: AppHeaderDetailsPresentation;
+  /** Below this breakpoint `auto` chooses the sheet. @default 'sm' */
+  breakpoint?: Breakpoint;
+  className?: string;
+  dataTestId?: string;
+}

package/src/components/navigation/AppHeader/index.ts

@@ -0,0 +1,16 @@
+export { AppHeader, default } from './AppHeader';
+export { AppHeaderBrand } from './AppHeader.brand';
+export { AppHeaderDetails } from './AppHeader.details';
+export { AppHeaderIdentity, AppHeaderStatus } from './AppHeader.identity';
+export { brandGradient, highlightOf, initialsOf } from './AppHeader.colors';
+export type {
+  AppHeaderBrandProps,
+  AppHeaderDetailRow,
+  AppHeaderDetailsAction,
+  AppHeaderDetailsPresentation,
+  AppHeaderDetailsProps,
+  AppHeaderIdentityProps,
+  AppHeaderPosition,
+  AppHeaderProps,
+  AppHeaderStatusProps,
+} from './AppHeader.types';

package/src/components/navigation/index.ts

@@ -1,3 +1,4 @@
+export * from './AppHeader';
 export * from './Breadcrumbs/Breadcrumbs';
 export * from './CommandPalette';
 export * from './ContextMenu';