@12-apps/ui 1.0.0 → 1.3.0

package/src/components/form/Calendar/CalendarDay.tsx

@@ -0,0 +1,127 @@
+import type { SxProps, Theme } from '@mui/material';
+import { Box } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import type { DayRenderArgs } from './Calendar.types';
+
+const CELL_SIZE = 40;
+
+interface DayState extends DayRenderArgs {
+  outside: boolean;
+  focused: boolean;
+}
+
+// Order matters: these land on the element in the order listed.
+const CLASS_FLAGS: Array<[keyof DayState, string]> = [
+  ['selected', 'selected'],
+  ['inRange', 'in-range'],
+  ['rangeStart', 'range-start'],
+  ['rangeEnd', 'range-end'],
+  ['disabled', 'disabled'],
+  ['today', 'today'],
+  ['outside', 'outside'],
+  ['hovered', 'hovered'],
+  ['focused', 'focused'],
+];
+
+const dayClassNames = (state: DayState, custom?: string): string =>
+  [
+    'calendar-day',
+    ...CLASS_FLAGS.filter(([flag]) => state[flag]).map(([, name]) => name),
+    ...(custom ? [custom] : []),
+  ].join(' ');
+
+const isEndpoint = (day: DayRenderArgs): boolean =>
+  day.selected || day.rangeStart || day.rangeEnd;
+
+const backgroundFor = (day: DayRenderArgs): string => {
+  if (isEndpoint(day)) return 'primary.main';
+  if (day.inRange || day.hovered) return 'primary.light';
+  return 'transparent';
+};
+
+const colorFor = (day: DayRenderArgs, visible: boolean): string => {
+  if (isEndpoint(day)) return 'primary.contrastText';
+  if (day.disabled) return 'text.disabled';
+  // Outside days that are switched off still occupy the grid, they just have
+  // nothing to show.
+  if (!visible) return 'transparent';
+  return 'text.primary';
+};
+
+const hoverBackgroundFor = (day: DayRenderArgs): string | undefined => {
+  if (day.disabled) return undefined;
+  return day.selected ? 'primary.dark' : 'action.hover';
+};
+
+const dayCellSx = (day: DayRenderArgs, visible: boolean): SxProps<Theme> => ({
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  width: CELL_SIZE,
+  height: CELL_SIZE,
+  border: 'none',
+  borderRadius: 1,
+  cursor: day.disabled ? 'not-allowed' : 'pointer',
+  backgroundColor: backgroundFor(day),
+  color: colorFor(day, visible),
+  opacity: !day.inCurrentMonth && visible ? 0.5 : 1,
+  fontWeight: day.today ? 'bold' : 'normal',
+  '&:hover': {
+    backgroundColor: hoverBackgroundFor(day),
+  },
+  '&:focus': {
+    outline: '2px solid',
+    outlineColor: 'primary.main',
+    outlineOffset: 1,
+  },
+});
+
+export interface CalendarDayProps {
+  day: DayRenderArgs;
+  focused: boolean;
+  showOutsideDays: boolean;
+  dayClassName?: (args: DayRenderArgs) => string;
+  onSelect: (date: Date) => void;
+  onHover: (date: Date) => void;
+  onHoverEnd: () => void;
+}
+
+export const CalendarDay: FC<CalendarDayProps> = ({
+  day,
+  focused,
+  showOutsideDays,
+  dayClassName,
+  onSelect,
+  onHover,
+  onHoverEnd,
+}) => {
+  const visible = day.inCurrentMonth || showOutsideDays;
+  const state: DayState = { ...day, outside: !day.inCurrentMonth, focused };
+
+  return (
+    <Box
+      component="button"
+      role="gridcell"
+      tabIndex={focused ? 0 : -1}
+      aria-selected={day.selected}
+      aria-disabled={day.disabled}
+      aria-current={day.today ? 'date' : undefined}
+      className={dayClassNames(state, dayClassName?.(day))}
+      data-testid={`calendar-date-${day.date.getDate()}`}
+      onClick={() => onSelect(day.date)}
+      onMouseEnter={() => onHover(day.date)}
+      onMouseLeave={onHoverEnd}
+      sx={dayCellSx(day, visible)}
+    >
+      {day.selected && (
+        <Box component="span" data-testid="calendar-selected-date" sx={{ display: 'none' }} />
+      )}
+      {day.today && (
+        <Box component="span" data-testid="calendar-today" sx={{ display: 'none' }} />
+      )}
+      {visible ? day.date.getDate() : ''}
+    </Box>
+  );
+};

package/src/components/form/Calendar/CalendarDayCell.tsx

@@ -0,0 +1,52 @@
+import type { FC } from 'react';
+import React from 'react';
+
+import { isSameDay } from './Calendar.dates';
+import { buildDayArgs } from './Calendar.selection';
+import type { CalendarProps, DateRange, MonthMatrixDay, SelectionMode } from './Calendar.types';
+import { CalendarDay } from './CalendarDay';
+
+// Everything a cell needs that is the same for every cell in the calendar.
+export interface DayCellContext {
+  selectionMode: SelectionMode;
+  value: Date | null;
+  range: DateRange;
+  hoveredDate: Date | null;
+  focusedDate: Date;
+  today: Date;
+  showOutsideDays: boolean;
+  isDisabled: (date: Date) => boolean;
+  renderDay?: CalendarProps['renderDay'];
+  dayClassName?: CalendarProps['dayClassName'];
+  onSelect: (date: Date) => void;
+  onHover: (date: Date) => void;
+  onHoverEnd: () => void;
+}
+
+export const CalendarDayCell: FC<DayCellContext & { day: MonthMatrixDay }> = ({
+  day,
+  focusedDate,
+  showOutsideDays,
+  renderDay,
+  dayClassName,
+  onSelect,
+  onHover,
+  onHoverEnd,
+  ...context
+}) => {
+  const args = buildDayArgs({ day, ...context });
+
+  if (renderDay) return <>{renderDay(args)}</>;
+
+  return (
+    <CalendarDay
+      day={args}
+      focused={isSameDay(args.date, focusedDate)}
+      showOutsideDays={showOutsideDays}
+      dayClassName={dayClassName}
+      onSelect={onSelect}
+      onHover={onHover}
+      onHoverEnd={onHoverEnd}
+    />
+  );
+};

package/src/components/form/Calendar/CalendarMonth.tsx

@@ -0,0 +1,128 @@
+import ChevronLeft from '@mui/icons-material/ChevronLeft';
+import ChevronRight from '@mui/icons-material/ChevronRight';
+import { Box, IconButton, Typography } from '@mui/material';
+import type { FC } from 'react';
+import React from 'react';
+
+import { getMonthName } from './Calendar.dates';
+import type { CalendarProps, MonthMatrix } from './Calendar.types';
+import type { DayCellContext } from './CalendarDayCell';
+import { CalendarDayCell } from './CalendarDayCell';
+
+const SPACER_WIDTH = 32;
+
+const GRID_SX = { display: 'grid', gridTemplateColumns: 'repeat(7, 1fr)', gap: 0.5 } as const;
+
+// Only the outermost months carry arrows; the ones between get a spacer so their
+// titles stay centred.
+const MonthNavHeader: FC<{
+  title: React.ReactNode;
+  showPrevious: boolean;
+  showNext: boolean;
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+}> = ({ title, showPrevious, showNext, onPreviousMonth, onNextMonth }) => (
+  <Box
+    sx={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', mb: 2 }}
+    data-testid="calendar-header"
+  >
+    {showPrevious && (
+      <IconButton onClick={onPreviousMonth} size="small" data-testid="calendar-prev-month">
+        <ChevronLeft />
+      </IconButton>
+    )}
+
+    <Typography
+      variant="h6"
+      component="h2"
+      sx={{ fontWeight: 'bold', flex: 1, textAlign: 'center' }}
+    >
+      {title}
+    </Typography>
+
+    {showNext && (
+      <IconButton onClick={onNextMonth} size="small" data-testid="calendar-next-month">
+        <ChevronRight />
+      </IconButton>
+    )}
+
+    {!showPrevious && !showNext && <Box sx={{ width: SPACER_WIDTH }} />}
+  </Box>
+);
+
+const WeekdayHeader: FC<{ weekdayNames: string[] }> = ({ weekdayNames }) => (
+  <Box sx={{ ...GRID_SX, mb: 1 }}>
+    {weekdayNames.map((weekday, index) => (
+      <Box
+        // Narrow weekday names repeat within a week ('S', 'T'), so position is
+        // the only stable key here.
+        key={`weekday-${index}`}
+        role="columnheader"
+        data-testid={`calendar-weekday-${index}`}
+        sx={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          height: SPACER_WIDTH,
+          fontSize: '0.875rem',
+          fontWeight: 'bold',
+          color: 'text.secondary',
+        }}
+      >
+        {weekday}
+      </Box>
+    ))}
+  </Box>
+);
+
+export interface CalendarMonthProps {
+  matrix: MonthMatrix;
+  monthIndex: number;
+  monthsToShow: number;
+  locale: string;
+  weekdayNames: string[];
+  renderHeader?: CalendarProps['renderHeader'];
+  onPreviousMonth: () => void;
+  onNextMonth: () => void;
+  dayContext: DayCellContext;
+}
+
+export const CalendarMonth: FC<CalendarMonthProps> = ({
+  matrix,
+  monthIndex,
+  monthsToShow,
+  locale,
+  weekdayNames,
+  renderHeader,
+  onPreviousMonth,
+  onNextMonth,
+  dayContext,
+}) => {
+  const monthName = getMonthName(matrix.month, matrix.year, locale);
+  const title = renderHeader ? renderHeader({ month: matrix.month, year: matrix.year }) : monthName;
+
+  return (
+    <Box sx={{ minWidth: 280 }}>
+      <MonthNavHeader
+        title={title}
+        showPrevious={monthIndex === 0}
+        showNext={monthIndex === monthsToShow - 1}
+        onPreviousMonth={onPreviousMonth}
+        onNextMonth={onNextMonth}
+      />
+
+      <WeekdayHeader weekdayNames={weekdayNames} />
+
+      <Box
+        role="grid"
+        aria-labelledby={`month-${monthIndex}`}
+        data-testid="calendar-grid"
+        sx={GRID_SX}
+      >
+        {matrix.weeks.flat().map((day) => (
+          <CalendarDayCell key={day.key} day={day} {...dayContext} />
+        ))}
+      </Box>
+    </Box>
+  );
+};

package/src/components/form/CepField/CepField.md

@@ -0,0 +1,138 @@
+# CepField Component
+
+## Purpose
+
+A CEP input that fills the rest of the address in — the autofill pattern every
+Brazilian form has used for twenty years. The user types eight digits and the
+logradouro, bairro, cidade and UF arrive on their own; only `número` and
+`complemento` are left to type, because no CEP database holds them.
+
+The component owns the *interaction* — masking, validation, debouncing,
+race-safety, status — and takes the *lookup* as a prop. It therefore knows
+nothing about providers, transport or authentication, and the same component
+serves a supplier form, a store-location form or a delivery checkout.
+
+## Features
+
+- Masks to `#####-###` on every keystroke, tolerant of pasted/messy input
+- Fires the lookup only once the CEP is complete, after a debounce
+- Never re-queries a CEP it already resolved
+- Race-safe: a slow response for a since-edited CEP can never overwrite a newer one
+- Degrades to a plain masked input when the lookup fails, throws, or is absent
+- Accessible status via `role="status"` / `aria-live="polite"` and `aria-busy`
+- Works uncontrolled-by-a-form (props) or bound to `total-form` (`Fields.CepField`)
+
+## Props Documentation
+
+### Core Props
+
+- `value`: Current value, masked or bare — the field re-masks it
+- `onChange`: Called on every keystroke with the **masked** value
+- `onLookup`: `(cep: string) => Promise<CepAddress | null>` — resolve a complete
+  CEP. Omit for a masked, validated input with no lookup at all
+- `onResolved`: `(address: CepAddress) => void` — called once a CEP resolves.
+  This is where the caller fills its address fields
+- `onNotFound`: `() => void` — called when a **complete** CEP fails to resolve.
+  The counterpart to `onResolved`: a caller that auto-filled from a previous CEP
+  should undo that here (see *Behaviour notes*)
+
+### Display Props
+
+- `label`: Visible label (default `CEP`)
+- `placeholder`: Placeholder text (default `00000-000`)
+- `name`: Field name / input id (default `postalCode`)
+- `dataTestId`: Test id for the input (default `cep-field-<name>`)
+
+### State Props
+
+- `error`: Validation error from the caller's form, shown below the input
+- `disabled`: Disables the input and suppresses lookups
+- `debounceMs`: Delay after the last keystroke before looking up (default `500`)
+
+### The `CepAddress` shape
+
+```ts
+interface CepAddress {
+  cep: string;              // bare digits
+  street: string | null;    // logradouro
+  neighborhood: string | null; // bairro
+  city: string | null;      // município
+  state: string | null;     // UF
+}
+```
+
+## Usage
+
+### Standalone
+
+```tsx
+const [cep, setCep] = useState('');
+
+<CepField
+  value={cep}
+  onChange={setCep}
+  onLookup={(c) =>
+    fetch(`/api/admin/${slug}/lookup/cep/${c}`)
+      .then((r) => (r.ok ? r.json() : null))
+      .then((body) => body?.data ?? null)
+  }
+  onResolved={(address) => {
+    setStreet(address.street ?? '');
+    setCity(address.city ?? '');
+  }}
+/>
+```
+
+### Bound to `total-form`
+
+`Fields.CepField` wires the field to the surrounding `FormContainer` and writes
+the resolved parts straight into sibling fields:
+
+```tsx
+<Fields.CepField
+  name="postalCode"
+  lookup={lookupCep}
+  fills={{
+    street: 'addressLine1',
+    neighborhood: 'neighborhood',
+    city: 'city',
+    state: 'state',
+  }}
+/>
+```
+
+Omit a key from `fills` to leave that part alone — a form with no bairro column
+simply doesn't map `neighborhood`.
+
+## Behaviour notes
+
+**Autofill never blocks.** A provider outage, an unknown CEP, a timeout or a
+lookup that throws all land in the same place: a `notfound` status and a field
+that behaves exactly like a plain text input. Saving is never gated on a
+third-party service being up.
+
+**It will not overwrite the user's work.** `Fields.CepField` writes a target
+field only when it is empty, or when it still holds the exact value that the
+component put there. So correcting the CEP re-fills the address, but a
+hand-edited street survives the next lookup.
+
+**It will not leave one CEP's address under another's.** When a complete CEP
+fails to resolve, `Fields.CepField` undoes its own autofill (again, only the
+fields still holding what it wrote). Otherwise typing CEP A, getting a hit, then
+correcting to an unknown CEP B would silently save A's street and city against
+B — a plausible wrong address, which is worse than an empty one. The same rule
+governs the CNPJ autofill on the fornecedores form.
+
+**Validation is shape-only.** A CEP is a postal range, not a checksummed
+document — there is no check digit to verify. Whether it *exists* is answered by
+the lookup. The pure helpers (`formatCep`, `isValidCep`) live in
+`@12-apps/forms-core` so the browser mask and any server-side guard share one rule.
+
+## Accessibility
+
+- The status line is a `role="status"` live region, so screen readers announce
+  "Buscando endereço…" / "Endereço preenchido pelo CEP" without stealing focus
+- `aria-busy` reflects the in-flight lookup
+- `aria-describedby` links the input to its status region
+- `inputMode="numeric"` brings up the numeric keypad on mobile
+- `autoComplete="postal-code"` lets the browser's own autofill participate

package/src/components/form/CepField/CepField.stories.tsx

@@ -0,0 +1,138 @@
+import { Paper, Stack, Typography } from '@mui/material';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+
+import { CepField } from './CepField';
+import type { CepAddress } from './CepField.types';
+
+const meta: Meta<typeof CepField> = {
+  title: 'Form/CepField',
+  component: CepField,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'A CEP input that fills the rest of the address in. Masks to `#####-###`, waits for a complete CEP, then calls the injected `onLookup` and hands the result to `onResolved`. The lookup is injected, so the component works with any backend — or none.',
+      },
+    },
+  },
+  tags: ['autodocs', 'component:CepField'],
+  argTypes: {
+    value: { control: 'text', description: 'Current value (masked or bare)' },
+    label: { control: 'text', description: 'Visible label' },
+    placeholder: { control: 'text', description: 'Placeholder text' },
+    error: { control: 'text', description: 'Validation error from the caller' },
+    disabled: { control: 'boolean', description: 'Disable input and lookups' },
+    debounceMs: { control: 'number', description: 'Delay before looking up' },
+    name: { control: 'text', description: 'Field name / input id' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Stand-in for a real provider — resolves one CEP, rejects everything else. */
+const FIXTURES: Record<string, CepAddress> = {
+  '01310100': {
+    cep: '01310100',
+    street: 'Avenida Paulista',
+    neighborhood: 'Bela Vista',
+    city: 'São Paulo',
+    state: 'SP',
+  },
+  '20040020': {
+    cep: '20040020',
+    street: 'Avenida Rio Branco',
+    neighborhood: 'Centro',
+    city: 'Rio de Janeiro',
+    state: 'RJ',
+  },
+};
+
+const fakeLookup = async (cep: string): Promise<CepAddress | null> => {
+  await new Promise((resolve) => setTimeout(resolve, 400));
+  return FIXTURES[cep] ?? null;
+};
+
+/** The whole point: type a CEP, watch the address fields fill themselves. */
+function Demo({
+  lookup = fakeLookup,
+  ...props
+}: {
+  lookup?: (cep: string) => Promise<CepAddress | null>;
+  label?: string;
+  disabled?: boolean;
+}): React.ReactElement {
+  const [cep, setCep] = useState('');
+  const [address, setAddress] = useState<CepAddress | null>(null);
+
+  return (
+    <Stack spacing={2} sx={{ maxWidth: 420 }}>
+      <CepField
+        {...props}
+        value={cep}
+        onChange={setCep}
+        onLookup={lookup}
+        onResolved={setAddress}
+      />
+      <Paper variant="outlined" sx={{ p: 2 }}>
+        <Typography variant="caption" color="text.secondary">
+          Endereço resolvido
+        </Typography>
+        <Typography variant="body2">{address?.street ?? '—'}</Typography>
+        <Typography variant="body2">{address?.neighborhood ?? '—'}</Typography>
+        <Typography variant="body2">
+          {address ? `${address.city ?? '—'} / ${address.state ?? '—'}` : '—'}
+        </Typography>
+      </Paper>
+      <Typography variant="caption" color="text.secondary">
+        Try 01310-100 or 20040-020. Anything else resolves to “não encontrado”.
+      </Typography>
+    </Stack>
+  );
+}
+
+export const Default: Story = {
+  render: () => <Demo />,
+};
+
+export const CustomLabel: Story = {
+  render: () => <Demo label="CEP do fornecedor" />,
+};
+
+export const Disabled: Story = {
+  render: () => <Demo disabled />,
+};
+
+/** Every provider is down. The field degrades to a plain masked input. */
+export const LookupUnavailable: Story = {
+  render: () => <Demo lookup={async () => null} />,
+};
+
+/** No `onLookup` at all — just the mask and validation. */
+export const MaskOnly: Story = {
+  render: function MaskOnlyStory() {
+    const [cep, setCep] = useState('');
+    return (
+      <Stack sx={{ maxWidth: 420 }}>
+        <CepField value={cep} onChange={setCep} />
+      </Stack>
+    );
+  },
+};
+
+export const WithError: Story = {
+  render: function WithErrorStory() {
+    const [cep, setCep] = useState('123');
+    return (
+      <Stack sx={{ maxWidth: 420 }}>
+        <CepField
+          value={cep}
+          onChange={setCep}
+          error="CEP inválido — use o formato 00000-000."
+        />
+      </Stack>
+    );
+  },
+};