@12-apps/ui 3.2.0 → 3.4.0

package/components-catalog.md

@@ -569,6 +569,14 @@ Components for structuring and organizing page layouts.
 
 Components for site and app navigation.
 
+### AppHeader
+**Purpose**: The application bar — brand identity, state line, actions, and the details panel behind them
+**Use Cases**: Storefront header, back-office top bar, platform console header; any app bar that must serve a phone and a desktop from one component
+**Features**: Slot-based (`leading` / identity / `actions` / `meta` / `below`), context-agnostic (no router, session or data), brand mark with a gradient derived from ONE seed colour, dotted state line, disclosure panel that is a bottom sheet on phones and a centred dialog on large screens, sticky/fixed positioning with a self-measured spacer
+**Types**: `AppHeaderProps`, `AppHeaderIdentityProps`, `AppHeaderBrandProps`, `AppHeaderStatusProps`, `AppHeaderDetailsProps`, `AppHeaderDetailRow`
+**Location**: `src/components/navigation/AppHeader`
+**Docs**: `src/components/navigation/AppHeader/AppHeader.md`
+
 ### Breadcrumbs
 **Purpose**: Display navigation path
 **Use Cases**: Hierarchical navigation, page location indicator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -120,6 +120,7 @@
     "./layout/Skeleton": "./src/components/layout/Skeleton/index.ts",
     "./layout/Spacer": "./src/components/layout/Spacer/index.ts",
     "./layout/TableFilter": "./src/components/layout/TableFilter/index.ts",
+    "./navigation/AppHeader": "./src/components/navigation/AppHeader/index.ts",
     "./navigation/Breadcrumbs": "./src/components/navigation/Breadcrumbs/index.ts",
     "./navigation/CommandPalette": "./src/components/navigation/CommandPalette/index.ts",
     "./navigation/ContextMenu": "./src/components/navigation/ContextMenu/index.ts",

package/src/components/data-display/Chart/Chart.tsx

@@ -93,7 +93,7 @@ export const Chart: React.FC<ChartProps> = (props) => {
       <ChartContainer
         responsive={props.responsive ?? true}
         width={props.width ?? '100%'}
-        height={sizeStyles.height}
+        height={props.fillHeight === true ? '100%' : sizeStyles.height}
         data-testid={`${dataTestId}-container`}
       >
         {renderChartByType(props, theme)}

package/src/components/data-display/Chart/Chart.types.ts

@@ -83,6 +83,16 @@ export interface ChartProps {
   maxCategoryTicks?: number;
   /** Category tick labels longer than this are truncated with an ellipsis. Default 12. */
   tickLabelMaxChars?: number;
+  /**
+   * Take the height of the box this chart is placed in, rather than the size
+   * preset's fixed one.
+   *
+   * For a host that has already sized the chart's container — a dashboard cell
+   * with a chosen height, say. The preset is a sensible default precisely
+   * because most callers have NOT sized anything, so this is opt-in: without
+   * it a chart in a box with no definite height would collapse to nothing.
+   */
+  fillHeight?: boolean;
   /** Bar corner radius in px (top corners only; stacked segments stay square). Default 3. */
   barRadius?: number;
   /**

package/src/components/data-display/Chart/ChartComposables.tsx

@@ -15,7 +15,16 @@ export const ChartTooltip = Tooltip;
 export const ChartLegend = Legend;
 
 export interface ChartContainerProps {
-  height: number;
+  /**
+   * A number of pixels, or a PERCENTAGE of the box this container is given.
+   *
+   * The difference is not cosmetic: Recharts sizes the chart from the number
+   * when it is one and only MEASURES its own box when it is a percentage
+   * (`calculateChartDimensions`). So a container stretched by its parent's
+   * layout goes on drawing a 300px chart inside a 600px box — visibly, as
+   * blank space under the plot — until the height is handed over as a percent.
+   */
+  height: number | `${number}%`;
   width?: number | string;
   responsive?: boolean;
   children: React.ReactElement;

package/src/components/data-display/Chart/SpecChart.tsx

@@ -12,6 +12,8 @@ export interface SpecChartProps {
   spec: ChartSpec;
   data: ChartDataPoint[];
   size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Take the height of the box this chart is placed in — see `ChartProps`. */
+  fillHeight?: boolean;
   loading?: boolean;
   className?: string;
   onClick?: (point: ChartDataPoint) => void;
@@ -27,6 +29,7 @@ export const SpecChart: React.FC<SpecChartProps> = ({
   spec,
   data,
   size,
+  fillHeight,
   loading,
   className,
   onClick,
@@ -45,6 +48,7 @@ export const SpecChart: React.FC<SpecChartProps> = ({
     <Chart
       {...chartProps}
       size={size}
+      fillHeight={fillHeight}
       loading={loading}
       className={className}
       onClick={onClick}

package/src/components/data-display/DataViews/data-views-display-tabs.tsx

@@ -2,6 +2,8 @@
 
 import ArrowDownwardRoundedIcon from "@mui/icons-material/ArrowDownwardRounded";
 import ArrowUpwardRoundedIcon from "@mui/icons-material/ArrowUpwardRounded";
+import useMediaQuery from "@mui/material/useMediaQuery";
+import type { Theme } from "@mui/material/styles";
 
 import type { SortFieldDefinition } from "../../layout/ContentToolbar";
 import { Box } from "../../../mui/Box";
@@ -286,9 +288,44 @@ const LAYOUT_TILE_LABELS: Record<DataViewsLayout, string> = {
  * `data-views-glyphs.tsx` for why. A layout this table cannot render is simply
  * not offered, and the panel says why rather than leaving a gap.
  */
+/**
+ * The three density tiles — or, on a phone, a line saying why there are none:
+ * the card grid is `1fr` there, so all three would draw one card per row. Says
+ * so rather than vanishing, for the same reason as the board note below it.
+ */
+function DensityTiles({ testIdPrefix }: { testIdPrefix: string }): React.JSX.Element {
+  const { layout, density, setDensity } = useDataViewsLayout();
+  // Matches the card grid's own `xs: "1fr"` track, so the control and the thing
+  // it controls agree on where density stops meaning anything.
+  const isOneColumn = useMediaQuery((t: Theme) => t.breakpoints.down("sm"));
+  if (layout === "cards" && isOneColumn) {
+    return (
+      <Text variant="caption" as="p">
+        <Box component="span" sx={{ px: 0.5, pt: 0.5, display: "block", color: "text.disabled" }}>
+          Um card por linha nesta largura — a densidade volta em telas maiores.
+        </Box>
+      </Text>
+    );
+  }
+  return (
+    <Box sx={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 0.75, mt: 0.5 }}>
+      {densityTiles(layout).map((tile) => (
+        <Tile
+          key={tile.value}
+          active={density === tile.value}
+          label={tile.label}
+          onClick={() => setDensity(tile.value)}
+          testId={`${testIdPrefix}-density-${tile.value}`}
+        >
+          {densityGlyph(layout, tile, density === tile.value)}
+        </Tile>
+      ))}
+    </Box>
+  );
+}
+
 export function DisplayTab({ testIdPrefix }: { testIdPrefix: string }): React.JSX.Element {
-  const { layout, setLayout, canUseCards, canUseList, canUseBoard, density, setDensity } =
-    useDataViewsLayout();
+  const { layout, setLayout, canUseCards, canUseList, canUseBoard } = useDataViewsLayout();
   const available: DataViewsLayout[] = [
     "table",
     ...(canUseList ? (["list"] as const) : []),
@@ -336,19 +373,7 @@ export function DisplayTab({ testIdPrefix }: { testIdPrefix: string }): React.JS
           {DENSITY_HEADINGS[layout]}
         </Box>
       </Text>
-      <Box sx={{ display: "grid", gridTemplateColumns: "repeat(3, 1fr)", gap: 0.75, mt: 0.5 }}>
-        {densityTiles(layout).map((tile) => (
-          <Tile
-            key={tile.value}
-            active={density === tile.value}
-            label={tile.label}
-            onClick={() => setDensity(tile.value)}
-            testId={`${testIdPrefix}-density-${tile.value}`}
-          >
-            {densityGlyph(layout, tile, density === tile.value)}
-          </Tile>
-        ))}
-      </Box>
+      <DensityTiles testIdPrefix={testIdPrefix} />
       {!canUseBoard && (
         <Text variant="caption" as="p">
           <Box component="span" sx={{ px: 0.5, pt: 1.25, display: "block", color: "text.disabled" }}>

package/src/components/data-display/DataViews/data-views-grid-bodies.tsx

@@ -6,14 +6,14 @@ import { DataGrid, type GridColumn, type GridSort } from "../DataGrid";
 import { Box } from "../../../mui/Box";
 
 import {
-  cardMinWidthForZoom,
+  cardTargetWidthFor,
   cardScaleForZoom,
   DENSITY_BOARD_SCALE,
-  DENSITY_CARD_COLUMNS,
   DENSITY_ROW_PADDING,
   useDataViewsLayout,
   type DataViewsDensity,
 } from "./data-views-layout-context";
+import { cardGridTracks } from "./data-views-grid-helpers";
 import { DataViewsBoard, type BoardConfig } from "./DataViewsBoard";
 import { SelectAllStrip } from "./data-views-select-all-strip";
 import { ListCardGroup, type ListGroupConfig } from "./list-card-rails";
@@ -90,9 +90,8 @@ interface CardBodyProps<T extends Record<string, unknown>> {
   getRowId: (row: T) => string | number;
   selectedIds: Set<string | number>;
   onToggleId: (id: string | number) => void;
-  minCardWidth: number;
-  /** Cap on cards per row, from the density preference. */
-  maxColumns: number;
+  /** The width each card asks for; `auto-fill` turns it into a column count. */
+  targetCardWidth: number;
   /** Content scale (padding + type) handed to each card, from the zoom slider. */
   cardScale: number;
   dataTestId?: string;
@@ -112,8 +111,7 @@ function CardBody<T extends Record<string, unknown>>({
   getRowId,
   selectedIds,
   onToggleId,
-  minCardWidth,
-  maxColumns,
+  targetCardWidth,
   cardScale,
   dataTestId,
   emptyState,
@@ -129,12 +127,7 @@ function CardBody<T extends Record<string, unknown>>({
         // Fixed inter-card gap — deliberately NOT scaled by the zoom slider, so
         // only the cards grow while the space between them stays constant.
         gap: 1.5,
-        // `auto-fill` still decides how many FIT; density caps how many are
-        // ALLOWED, so "Poucos" reads as bigger cards rather than more of them.
-        gridTemplateColumns: {
-          xs: "1fr",
-          sm: `repeat(auto-fill, minmax(max(${minCardWidth}px, calc((100% - ${(maxColumns - 1) * 12}px) / ${maxColumns})), 1fr))`,
-        },
+        ...cardGridTracks(targetCardWidth),
       }}
       data-testid={dataTestId ? `${dataTestId}-cards` : "data-views-cards"}
     >
@@ -353,8 +346,7 @@ function headerlessBody<T extends Record<string, unknown>>(
         getRowId={getRowId}
         selectedIds={c.selectedIds}
         onToggleId={c.toggleId}
-        minCardWidth={cardMinWidthForZoom(zoom)}
-        maxColumns={DENSITY_CARD_COLUMNS[density]}
+        targetCardWidth={cardTargetWidthFor(zoom, density)}
         cardScale={cardScaleForZoom(zoom)}
         dataTestId={dataTestId}
         emptyState={emptyState}

package/src/components/data-display/DataViews/data-views-grid-helpers.tsx

@@ -246,3 +246,24 @@ export function togglePillValues(current: string[] | undefined, value: string, c
   const list = current ?? [];
   return checked ? [...list, value] : list.filter((v) => v !== value);
 }
+
+/**
+ * The card grid's `grid-template-columns`, as an sx fragment.
+ *
+ * One rule at every width: each card asks for `targetWidth` and `auto-fill`
+ * decides how many fit. Density moves the target, so it changes the count at
+ * every size — which the previous column-count cap could not do, because its
+ * track floor bottomed out at a constant shared by all three densities.
+ *
+ * Below `sm` this is a single column, and no target changes that. That is why
+ * the density control hides itself there rather than offering three settings
+ * that all draw the same thing.
+ */
+export function cardGridTracks(targetWidth: number) {
+  return {
+    gridTemplateColumns: {
+      xs: "1fr",
+      sm: `repeat(auto-fill, minmax(${targetWidth}px, 1fr))`,
+    },
+  };
+}

package/src/components/data-display/DataViews/data-views-layout-context.tsx

@@ -81,13 +81,32 @@ export const DENSITY_ROW_PADDING: Record<DataViewsDensity, number> = {
   comfortable: 1.5,
 };
 
-/** Card grid columns per density — how many cards land on one row. */
-export const DENSITY_CARD_COLUMNS: Record<DataViewsDensity, number> = {
-  compact: 5,
-  cozy: 4,
-  comfortable: 3,
+/**
+ * The card WIDTH each density aims for, as a multiple of the base card width.
+ *
+ * Density used to cap the column COUNT, with a track floor of
+ * `max(baseWidth, 100% / count)`. That base is a constant, so wherever it won
+ * the arithmetic every density produced an identical track — "Muitos" and
+ * "Medio" both drew 3 cards of 279px at md — and where the percentage won
+ * instead, on a wide screen, the count was pinned and each card grew to a share
+ * of the viewport: ~430px of card holding one chip and two lines of text.
+ *
+ * One width per density fixes both, because the number `auto-fill` divides by
+ * now differs per density at every size. The spread is chosen so the three land
+ * on DIFFERENT column counts across the range rather than by eye — 4/3/2 at md,
+ * 6/4/3 at lg, 7/5/4 at xl, 13/9/8 at 2560.
+ */
+export const DENSITY_CARD_SCALE: Record<DataViewsDensity, number> = {
+  compact: 0.84,
+  cozy: 1.15,
+  comfortable: 1.4,
 };
 
+/** The width a card aims for: the base width, scaled by zoom, then by density. */
+export function cardTargetWidthFor(zoom: number, density: DataViewsDensity): number {
+  return Math.round(cardMinWidthForZoom(zoom) * DENSITY_CARD_SCALE[density]);
+}
+
 /**
  * The BOARD's column-width multiplier per density.
  *

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

@@ -0,0 +1,102 @@
+'use client';
+
+import { Box, useTheme } from '@mui/material';
+import type { Theme } from '@mui/material/styles';
+import React from 'react';
+
+import type { SizeValue } from '../../../tokens/scales';
+
+import { brandGradient, initialsOf } from './AppHeader.colors';
+import type { AppHeaderBrandProps } from './AppHeader.types';
+
+/** The mark's edge, per house size step. */
+const MARK_PX: Record<SizeValue, number> = { xs: 24, sm: 32, md: 40, lg: 48, xl: 56 };
+
+/** Initials are set at 40% of the mark so a two-letter pair never touches the edge. */
+const INITIALS_RATIO = 0.4;
+
+/** The mark's box, lifted out of the component to keep it inside the complexity bar. */
+function markSx(
+  theme: Theme,
+  { edge, round, showLogo, seed }: { edge: number; round: boolean; showLogo: boolean; seed: string },
+): Record<string, unknown> {
+  return {
+    width: edge,
+    height: edge,
+    flex: '0 0 auto',
+    overflow: 'hidden',
+    borderRadius: round ? '50%' : '30%',
+    display: 'flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    // Only the initials need the gradient; a logo covers it entirely, and
+    // painting it underneath would show at the corners of a transparent PNG.
+    backgroundImage: showLogo ? 'none' : brandGradient(seed),
+    backgroundColor: showLogo ? theme.palette.action.hover : 'transparent',
+    color: theme.palette.getContrastText(seed),
+    fontSize: Math.round(edge * INITIALS_RATIO),
+    fontWeight: 700,
+    lineHeight: 1,
+    letterSpacing: '0.02em',
+    userSelect: 'none',
+  };
+}
+
+/**
+ * The mark that opens the header: the logo when there is one, the name's
+ * initials on a gradient derived from the brand colour when there is not.
+ *
+ * Both branches occupy the SAME box, so a header does not resize when a logo
+ * arrives — or when one fails to load and the initials take over, which is the
+ * case a plain `<img>` renders as a torn-page glyph beside the store's name.
+ */
+export const AppHeaderBrand: React.FC<AppHeaderBrandProps> = ({
+  name,
+  logoUrl,
+  seedColor,
+  size = 'md',
+  shape = 'rounded',
+  className,
+  dataTestId = 'app-header-brand',
+}) => {
+  const theme = useTheme();
+  const [broken, setBroken] = React.useState(false);
+  // Keyed on the URL so a store that swaps its logo gets a fresh attempt rather
+  // than inheriting the previous one's failure.
+  React.useEffect(() => setBroken(false), [logoUrl]);
+
+  const edge = MARK_PX[size];
+  const seed = seedColor || theme.palette.primary.main;
+  const showLogo = Boolean(logoUrl) && !broken;
+
+  return (
+    <Box
+      className={className}
+      data-testid={dataTestId}
+      // `role="img"` + the name: the initials are a picture of the brand, not
+      // two letters a screen reader should spell out.
+      role="img"
+      aria-label={name}
+      sx={markSx(theme, { edge, round: shape === 'circle', showLogo, seed })}
+    >
+      {showLogo ? (
+        <Box
+          component="img"
+          src={logoUrl ?? undefined}
+          alt=""
+          onError={() => setBroken(true)}
+          data-testid={`${dataTestId}-logo`}
+          sx={{ width: '100%', height: '100%', objectFit: 'cover', display: 'block' }}
+        />
+      ) : (
+        <Box component="span" aria-hidden data-testid={`${dataTestId}-initials`}>
+          {initialsOf(name)}
+        </Box>
+      )}
+    </Box>
+  );
+};
+
+AppHeaderBrand.displayName = 'AppHeaderBrand';
+
+export default AppHeaderBrand;

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

@@ -0,0 +1,120 @@
+import { decomposeColor } from '@mui/material/styles';
+
+/**
+ * Turning ONE brand colour into the mark's fill.
+ *
+ * The alternative — a second "highlight" prop — reads reasonable and is a trap:
+ * it asks every caller to pick a colour that pairs with a colour they already
+ * picked, and a multi-tenant app asks that of people who will never see this
+ * component. Most would leave it unset, some would set it to the same value
+ * (a gradient that is a flat fill), and the rest would get a pairing nobody
+ * checked. So the highlight is DERIVED, and a store configures one hex.
+ *
+ * The derivation moves the seed's HUE rather than only its lightness. A
+ * lighten-only gradient reads as a lit sphere — the same effect at every seed,
+ * and a weak one at the light end where there is little room left to lighten.
+ * Rotating toward the warm side gives the mark a direction the eye follows, and
+ * because the rotation is fixed the two stops stay recognisably one colour.
+ */
+
+/** Degrees the highlight is rotated from the seed. Warm, and short of a clash. */
+const HIGHLIGHT_HUE_SHIFT = 42;
+
+/** The highlight sits this much lighter than the seed. */
+const HIGHLIGHT_LIGHTEN = 0.12;
+
+/**
+ * A near-grey seed has no hue to rotate, so rotating it produces the same grey
+ * twice. Below this saturation the mark falls back to a lightness-only ramp,
+ * which is the honest rendering of "this brand has no colour".
+ */
+const HUELESS = 0.08;
+
+/** The angle light appears to come from — matches the house elevation. */
+const GRADIENT_ANGLE = '135deg';
+
+interface Hsl {
+  h: number;
+  s: number;
+  l: number;
+}
+
+/** `[r, g, b]` in 0–255 from any CSS colour MUI can parse, or `null`. */
+function toRgb(color: string): [number, number, number] | null {
+  try {
+    const { values } = decomposeColor(color);
+    const [r, g, b] = values;
+    if (r === undefined || g === undefined || b === undefined) return null;
+    return [r, g, b];
+  } catch {
+    // A CSS variable, a colour name MUI does not know, a typo in a tenant's
+    // config. The caller falls back to the theme rather than painting nothing.
+    return null;
+  }
+}
+
+function rgbToHsl([r255, g255, b255]: [number, number, number]): Hsl {
+  const [r, g, b] = [r255 / 255, g255 / 255, b255 / 255];
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const delta = max - min;
+  if (delta === 0) return { h: 0, s: 0, l };
+  const s = delta / (1 - Math.abs(2 * l - 1));
+  return { h: hueOf(r, g, b, max, delta), s, l };
+}
+
+/** Split out so {@link rgbToHsl} stays inside the complexity bar. */
+function hueOf(r: number, g: number, b: number, max: number, delta: number): number {
+  let h: number;
+  if (max === r) h = 60 * (((g - b) / delta) % 6);
+  else if (max === g) h = 60 * ((b - r) / delta + 2);
+  else h = 60 * ((r - g) / delta + 4);
+  return (h + 360) % 360;
+}
+
+function hslToHex({ h, s, l }: Hsl): string {
+  const a = s * Math.min(l, 1 - l);
+  const channel = (n: number): string => {
+    const k = (n + h / 30) % 12;
+    const value = l - a * Math.max(-1, Math.min(k - 3, Math.min(9 - k, 1)));
+    return Math.round(value * 255)
+      .toString(16)
+      .padStart(2, '0');
+  };
+  return `#${channel(0)}${channel(8)}${channel(4)}`;
+}
+
+const clamp01 = (value: number): number => Math.min(1, Math.max(0, value));
+
+/**
+ * The seed's companion stop: rotated toward the warm side and lightened, or —
+ * for a seed with no hue worth rotating — lightened alone.
+ */
+export function highlightOf(seed: string): string {
+  const rgb = toRgb(seed);
+  if (!rgb) return seed;
+  const { h, s, l } = rgbToHsl(rgb);
+  const lightened = clamp01(l + HIGHLIGHT_LIGHTEN);
+  if (s < HUELESS) return hslToHex({ h, s, l: lightened });
+  return hslToHex({ h: (h + HIGHLIGHT_HUE_SHIFT) % 360, s, l: lightened });
+}
+
+/** The mark's fill: the seed, running into its derived highlight. */
+export function brandGradient(seed: string): string {
+  return `linear-gradient(${GRADIENT_ANGLE}, ${seed} 0%, ${highlightOf(seed)} 100%)`;
+}
+
+/**
+ * Up to two initials for `name`, or `·` when there is nothing to take.
+ *
+ * First + last rather than first two: "Future Drink" is FD, and a one-word name
+ * still yields its single letter instead of a pair that reads as two words.
+ */
+export function initialsOf(name: string): string {
+  const parts = name.trim().split(/\s+/u).filter(Boolean);
+  if (parts.length === 0) return '·';
+  const first = parts[0]?.[0] ?? '';
+  const last = parts.length > 1 ? (parts[parts.length - 1]?.[0] ?? '') : '';
+  return (first + last).toUpperCase();
+}