@12-apps/ui 1.0.0 → 1.3.1

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

@@ -0,0 +1,281 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import React, { useState } from 'react';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { CepField } from './CepField';
+import type { CepAddress } from './CepField.types';
+
+const ADDRESS: CepAddress = {
+  cep: '01310100',
+  street: 'Avenida Paulista',
+  neighborhood: 'Bela Vista',
+  city: 'São Paulo',
+  state: 'SP',
+};
+
+const meta: Meta<typeof CepField> = {
+  title: 'Form/CepField/Tests',
+  component: CepField,
+  parameters: {
+    layout: 'centered',
+    chromatic: { disableSnapshot: false },
+    docs: {
+      description: { component: 'Test stories for CepField masking, lookup and race-safety' },
+    },
+  },
+  tags: ['autodocs', 'test'],
+};
+
+export default meta;
+export type Story = StoryObj<typeof meta>;
+
+/** Controlled harness — the field is controlled, so tests need real state. */
+function Harness({
+  onLookup,
+  onResolved,
+  onNotFound,
+  debounceMs = 0,
+  initial = '',
+  disabled = false,
+}: {
+  onLookup?: (cep: string) => Promise<CepAddress | null>;
+  onResolved?: (address: CepAddress) => void;
+  onNotFound?: () => void;
+  debounceMs?: number;
+  initial?: string;
+  disabled?: boolean;
+}): React.ReactElement {
+  const [value, setValue] = useState(initial);
+  return (
+    <CepField
+      value={value}
+      onChange={setValue}
+      onLookup={onLookup}
+      onResolved={onResolved}
+      onNotFound={onNotFound}
+      debounceMs={debounceMs}
+      disabled={disabled}
+    />
+  );
+}
+
+// 1. Masking
+
+export const MasksWhileTyping: Story = {
+  render: () => <Harness />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '01310100');
+    await expect(input).toHaveValue('01310-100');
+  },
+};
+
+export const StripsNonDigitsAndCaps: Story = {
+  render: () => <Harness />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, 'ab01310100999');
+    await expect(input).toHaveValue('01310-100');
+  },
+};
+
+// 2. Lookup
+
+export const ResolvesACompleteCep: Story = {
+  render: function ResolvesStory() {
+    const onResolved = fn();
+    return (
+      <Harness onLookup={async () => ADDRESS} onResolved={onResolved} />
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '01310100');
+    await waitFor(() => expect(canvas.getByTestId('cep-field-postalCode-found')).toBeInTheDocument());
+  },
+};
+
+export const DoesNotLookUpAnIncompleteCep: Story = {
+  render: function IncompleteStory() {
+    const lookup = fn(async () => ADDRESS);
+    return <Harness onLookup={lookup} />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '0131');
+    // Presence evidence first: the field really did take the partial value…
+    await expect(input).toHaveValue('0131');
+    // …and no status line ever appears, because an incomplete CEP is never
+    // queried. waitFor gives the (absent) debounce a chance to fire first.
+    await waitFor(() => {
+      expect(canvas.queryByTestId('cep-field-postalCode-loading')).toBeNull();
+      expect(canvas.queryByTestId('cep-field-postalCode-found')).toBeNull();
+    });
+  },
+};
+
+export const ReportsAnUnknownCep: Story = {
+  render: () => <Harness onLookup={async () => null} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '00000000');
+    await waitFor(() =>
+      expect(canvas.getByTestId('cep-field-postalCode-notfound')).toBeInTheDocument(),
+    );
+  },
+};
+
+/**
+ * A miss must be REPORTED, not just displayed: callers that auto-filled from a
+ * previous CEP rely on `onNotFound` to undo it, so the form never shows one
+ * CEP's street under another's.
+ */
+export const ReportsAMissToTheCaller: Story = {
+  render: function ReportsMissStory() {
+    const [missed, setMissed] = useState(false);
+    return (
+      <div>
+        <Harness onLookup={async () => null} onNotFound={() => setMissed(true)} />
+        <span data-testid="miss-flag">{missed ? 'missed' : 'clean'}</span>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '00000000');
+    await waitFor(() => expect(canvas.getByTestId('miss-flag')).toHaveTextContent('missed'));
+  },
+};
+
+/** …and a resolved CEP must NOT report a miss. */
+export const DoesNotReportAMissOnSuccess: Story = {
+  render: function NoMissStory() {
+    const [missed, setMissed] = useState(false);
+    return (
+      <div>
+        <Harness onLookup={async () => ADDRESS} onNotFound={() => setMissed(true)} />
+        <span data-testid="miss-flag">{missed ? 'missed' : 'clean'}</span>
+      </div>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '01310100');
+    await waitFor(() => expect(canvas.getByTestId('cep-field-postalCode-found')).toBeInTheDocument());
+    await expect(canvas.getByTestId('miss-flag')).toHaveTextContent('clean');
+  },
+};
+
+/** A lookup that throws is indistinguishable from "not found" — never a crash. */
+export const SurvivesAThrowingLookup: Story = {
+  render: () => (
+    <Harness
+      onLookup={async () => {
+        throw new Error('provider down');
+      }}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '01310100');
+    await waitFor(() =>
+      expect(canvas.getByTestId('cep-field-postalCode-notfound')).toBeInTheDocument(),
+    );
+  },
+};
+
+/**
+ * …including a lookup that throws BEFORE returning a promise, which is what a
+ * misconfigured adapter does. Awaiting the call and catching on its result
+ * would miss this one entirely and surface it as an unhandled rejection.
+ */
+export const SurvivesASynchronousThrow: Story = {
+  render: () => (
+    <Harness
+      onLookup={() => {
+        throw new Error('adapter misconfigured');
+      }}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '01310100');
+    await waitFor(() =>
+      expect(canvas.getByTestId('cep-field-postalCode-notfound')).toBeInTheDocument(),
+    );
+  },
+};
+
+// 3. State
+
+export const DisabledSuppressesLookup: Story = {
+  render: () => <Harness initial="01310-100" disabled onLookup={async () => ADDRESS} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await expect(input).toBeDisabled();
+    await expect(input).toHaveValue('01310-100');
+    // A complete CEP, but disabled suppresses the lookup entirely.
+    await waitFor(() => expect(canvas.queryByTestId('cep-field-postalCode-found')).toBeNull());
+  },
+};
+
+export const ClearsStatusWhenEditedBackToIncomplete: Story = {
+  render: () => <Harness onLookup={async () => ADDRESS} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await userEvent.type(input, '01310100');
+    await waitFor(() => expect(canvas.getByTestId('cep-field-postalCode-found')).toBeInTheDocument());
+
+    await userEvent.type(input, '{backspace}');
+    await waitFor(() => expect(canvas.queryByTestId('cep-field-postalCode-found')).toBeNull());
+  },
+};
+
+// 4. Accessibility
+
+export const ExposesAccessibleStatus: Story = {
+  render: () => <Harness onLookup={async () => ADDRESS} />,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByTestId('cep-field-postalCode');
+
+    await expect(input).toHaveAttribute('aria-describedby', 'cep-field-postalCode-status');
+    await userEvent.type(input, '01310100');
+    await waitFor(() => expect(canvas.getByRole('status')).toBeInTheDocument());
+  },
+};
+
+export const RendersACallerError: Story = {
+  render: function ErrorStory() {
+    const [value, setValue] = useState('123');
+    return <CepField value={value} onChange={setValue} error="CEP inválido." />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByTestId('cep-field-postalCode-message')).toHaveTextContent(
+      'CEP inválido.',
+    );
+  },
+};

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

@@ -0,0 +1,211 @@
+'use client';
+
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+
+import { cepDigits, formatCep, isValidCep } from '@12-apps/forms-core';
+
+import { FormControl, FormLabel, FormMessage } from '../Form';
+import { Input } from '../Input';
+import type { CepAddress, CepFieldProps, CepLookupStatus } from './CepField.types';
+
+/** What the user is told for each non-idle outcome. */
+const STATUS_TEXT: Record<Exclude<CepLookupStatus, 'idle'>, string> = {
+  loading: 'Buscando endereço…',
+  found: 'Endereço preenchido pelo CEP.',
+  notfound: 'CEP não encontrado — preencha o endereço manualmente.',
+};
+
+/** Everything {@link useCepLookup} needs, so the hook signature stays flat. */
+interface LookupOptions {
+  digits: string;
+  complete: boolean;
+  disabled: boolean;
+  debounceMs: number;
+  onLookup?: (cep: string) => Promise<CepAddress | null>;
+  onResolved?: (address: CepAddress) => void;
+  onNotFound?: () => void;
+}
+
+/**
+ * Debounced, race-safe CEP resolution.
+ *
+ * Two guards earn their keep here: a monotonic sequence id, bumped
+ * synchronously on every new query, so a slow response for a since-edited CEP
+ * can never land; and a "last queried" marker, so re-rendering (or the caller
+ * re-masking the same value) never re-hits the provider.
+ */
+function useCepLookup({
+  digits,
+  complete,
+  disabled,
+  debounceMs,
+  onLookup,
+  onResolved,
+  onNotFound,
+}: LookupOptions): CepLookupStatus {
+  const [status, setStatus] = useState<CepLookupStatus>('idle');
+  const lastQueriedRef = useRef('');
+  const seqRef = useRef(0);
+  // Latest callbacks, read at call time — keeps them out of the effect deps so
+  // an inline arrow from the caller doesn't re-trigger the lookup every render.
+  const lookupRef = useRef(onLookup);
+  const resolvedRef = useRef(onResolved);
+  const notFoundRef = useRef(onNotFound);
+  lookupRef.current = onLookup;
+  resolvedRef.current = onResolved;
+  notFoundRef.current = onNotFound;
+
+  useEffect(() => {
+    if (!complete || disabled || !lookupRef.current) {
+      // Editing away from a complete CEP drops any stale status and forgets the
+      // last query, so re-typing the same CEP resolves again.
+      seqRef.current += 1;
+      setStatus('idle');
+      lastQueriedRef.current = '';
+      return;
+    }
+    if (lastQueriedRef.current === digits) return;
+
+    const mySeq = (seqRef.current += 1);
+    const handle = setTimeout(() => {
+      lastQueriedRef.current = digits;
+      setStatus('loading');
+      void (async () => {
+        // A failing lookup is treated exactly like "not found" — the user types
+        // the address instead. Never surfaced as a crash. Going through
+        // `Promise.resolve().then` rather than calling directly covers the two
+        // failure modes an `await … .catch()` misses: a lookup that throws
+        // SYNCHRONOUSLY, and one that returns something other than a promise.
+        const address = await Promise.resolve()
+          .then(() => lookupRef.current?.(digits))
+          .catch(() => null);
+        if (seqRef.current !== mySeq) return;
+        setStatus(address ? 'found' : 'notfound');
+        // A miss is reported too, so a caller that filled from a PREVIOUS CEP
+        // can undo it rather than leaving that address under this CEP.
+        if (address) resolvedRef.current?.(address);
+        else notFoundRef.current?.();
+      })();
+    }, debounceMs);
+
+    return () => clearTimeout(handle);
+  }, [digits, complete, disabled, debounceMs]);
+
+  return status;
+}
+
+/**
+ * The lookup outcome as a live region, so screen readers announce it without
+ * stealing focus. Silent while idle, and while the caller is showing its own
+ * validation error (which would otherwise stack two messages).
+ */
+function CepStatus({
+  status,
+  testId,
+  suppressed,
+}: {
+  status: CepLookupStatus;
+  testId: string;
+  suppressed: boolean;
+}): React.ReactElement {
+  const visible = !suppressed && status !== 'idle';
+  return (
+    <span id={`${testId}-status`} role="status" aria-live="polite">
+      {visible && (
+        <FormMessage error={status === 'notfound'} dataTestId={`${testId}-${status}`}>
+          {STATUS_TEXT[status as Exclude<CepLookupStatus, 'idle'>]}
+        </FormMessage>
+      )}
+    </span>
+  );
+}
+
+/**
+ * A CEP input that fills the rest of the address in.
+ *
+ * The pattern every Brazilian form has used for twenty years: type eight
+ * digits, and logradouro/bairro/cidade/UF arrive on their own. This is the
+ * reusable half — masking, validation, debouncing, race-safety and status —
+ * with the actual lookup injected via `onLookup`, so the same component serves
+ * a supplier form, a store-location form or a delivery checkout without
+ * knowing anything about providers or auth.
+ *
+ * Resolution is best-effort by design. A provider outage, an unknown CEP or a
+ * timeout leaves the field exactly as usable as a plain text input — the user
+ * types the address themselves. Autofill never blocks.
+ *
+ * @example
+ * ```tsx
+ * <CepField
+ *   value={cep}
+ *   onChange={setCep}
+ *   onLookup={(c) => fetch(`/api/…/lookup/cep/${c}`).then((r) => r.json()).then((b) => b.data)}
+ *   onResolved={(a) => { setStreet(a.street ?? ''); setCity(a.city ?? ''); }}
+ * />
+ * ```
+ */
+export function CepField({
+  value,
+  onChange,
+  onLookup,
+  onResolved,
+  onNotFound,
+  label = 'CEP',
+  placeholder = '00000-000',
+  error,
+  disabled = false,
+  debounceMs = 500,
+  name = 'postalCode',
+  dataTestId,
+}: CepFieldProps): React.ReactElement {
+  const testId = dataTestId ?? `cep-field-${name}`;
+
+  const status = useCepLookup({
+    digits: cepDigits(value),
+    complete: isValidCep(value),
+    disabled,
+    debounceMs,
+    onLookup,
+    onResolved,
+    onNotFound,
+  });
+
+  const handleChange = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => onChange(formatCep(event.target.value)),
+    [onChange],
+  );
+
+  return (
+    <FormControl fullWidth>
+      {label && (
+        <FormLabel htmlFor={name} error={Boolean(error)}>
+          {label}
+        </FormLabel>
+      )}
+      <Input
+        id={name}
+        name={name}
+        type="text"
+        inputMode="numeric"
+        autoComplete="postal-code"
+        placeholder={placeholder}
+        value={value}
+        error={Boolean(error)}
+        disabled={disabled}
+        loading={status === 'loading'}
+        onChange={handleChange}
+        data-testid={testId}
+        aria-describedby={`${testId}-status`}
+        aria-busy={status === 'loading'}
+      />
+      {error && (
+        <FormMessage error dataTestId={`${testId}-message`}>
+          {error}
+        </FormMessage>
+      )}
+      <CepStatus status={status} testId={testId} suppressed={Boolean(error)} />
+    </FormControl>
+  );
+}
+
+export default CepField;

package/src/components/form/CepField/CepField.types.ts

@@ -0,0 +1,73 @@
+/**
+ * Types for {@link CepField} — the reusable CEP auto-completer.
+ */
+
+/**
+ * A resolved CEP.
+ *
+ * Structurally identical to what the app's `/lookup/cep` endpoint returns, but
+ * declared here so the component stays independent of any particular backend:
+ * anything that can produce this shape can drive the field.
+ *
+ * `número` and `complemento` are deliberately absent — no CEP database holds
+ * them, so they are always the user's to type.
+ */
+export interface CepAddress {
+  /** The CEP that resolved, bare digits. */
+  cep: string;
+  /** Logradouro (street name, no number). */
+  street: string | null;
+  /** Bairro. */
+  neighborhood: string | null;
+  /** Município. */
+  city: string | null;
+  /** UF. */
+  state: string | null;
+}
+
+/** What the field is currently doing, surfaced as a status line. */
+export type CepLookupStatus = 'idle' | 'loading' | 'found' | 'notfound';
+
+export interface CepFieldProps {
+  /** Current field value. Masked (`01310-100`) or bare — the field re-masks. */
+  value: string;
+  /**
+   * Called on every keystroke with the MASKED value, so the caller's state and
+   * what the user sees never diverge.
+   */
+  onChange: (masked: string) => void;
+  /**
+   * Resolve a complete CEP to an address, or `null` when it is unknown.
+   *
+   * Injected rather than hard-wired: the component knows nothing about
+   * providers, transport or auth. Omit it to get a masked, validated CEP input
+   * with no lookup at all.
+   */
+  onLookup?: (cep: string) => Promise<CepAddress | null>;
+  /**
+   * Called once a CEP resolves — this is where the caller fills the address
+   * fields. Never called for an incomplete, unchanged or unknown CEP.
+   */
+  onResolved?: (address: CepAddress) => void;
+  /**
+   * Called when a COMPLETE CEP fails to resolve (unknown, or every provider
+   * down). The counterpart to `onResolved`: a caller that auto-filled from a
+   * previous CEP should undo that here, so the form never shows one CEP's
+   * street under a different CEP.
+   */
+  onNotFound?: () => void;
+  /** Visible label. Defaults to `CEP`. */
+  label?: string;
+  /** Placeholder. Defaults to `00000-000`. */
+  placeholder?: string;
+  /** Validation error from the caller's form, shown below the input. */
+  error?: string;
+  /** Disables the input and suppresses lookups. */
+  disabled?: boolean;
+  /** Milliseconds to wait after the last keystroke before looking up. */
+  debounceMs?: number;
+  /** Field name / input id. Defaults to `postalCode`. */
+  name?: string;
+  /** Test id for the input. Defaults to `cep-field-<name>`. */
+  dataTestId?: string;
+}

package/src/components/form/CepField/index.ts

@@ -0,0 +1,2 @@
+export { CepField } from './CepField';
+export type { CepAddress, CepFieldProps, CepLookupStatus } from './CepField.types';

package/src/components/form/Checkbox/Checkbox.helpers.ts

@@ -0,0 +1,28 @@
+import type { CheckboxProps } from './Checkbox.types';
+
+type CheckboxDefaultedKeys = 'variant' | 'ripple' | 'glow' | 'pulse';
+
+type ResolvedCheckboxProps = CheckboxProps &
+  Required<Pick<CheckboxProps, CheckboxDefaultedKeys>>;
+
+const CHECKBOX_DEFAULTS: Pick<CheckboxProps, CheckboxDefaultedKeys> = {
+  variant: 'default',
+  ripple: true,
+  glow: false,
+  pulse: false,
+};
+
+// Strips explicitly-undefined props before the merge, so `ripple={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: CheckboxProps): Partial<CheckboxProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<CheckboxProps>;
+
+export const resolveCheckboxProps = (props: CheckboxProps): ResolvedCheckboxProps =>
+  ({ ...CHECKBOX_DEFAULTS, ...definedProps(props) }) as ResolvedCheckboxProps;
+
+export const makeTestId =
+  (dataTestId?: string) =>
+  (suffix: string): string =>
+    dataTestId ? `${dataTestId}-${suffix}` : `checkbox-${suffix}`;

package/src/components/form/Checkbox/Checkbox.tsx

@@ -8,6 +8,7 @@ import {
   styled} from '@mui/material';
 import React from 'react';
 
+import { makeTestId, resolveCheckboxProps } from './Checkbox.helpers';
 import type { CheckboxProps } from './Checkbox.types';
 
 const pulse = keyframes`
@@ -99,21 +100,23 @@ const StyledFormHelperText = styled(FormHelperText)(({ theme }) => ({
 }));
 
 export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
-  ({ 
-    variant = 'default', 
-    label, 
-    error, 
-    helperText, 
-    loading, 
-    ripple = true,
-    glow = false,
-    pulse = false,
-    disabled,
-    'data-testid': dataTestId,
-    ...props 
-  }, ref) => {
+  (rawProps, ref) => {
+    const {
+      variant,
+      label,
+      error,
+      helperText,
+      loading,
+      ripple,
+      glow,
+      pulse,
+      disabled,
+      'data-testid': dataTestId,
+      ...props
+    } = resolveCheckboxProps(rawProps);
     const isDisabled = disabled || loading;
-    
+    const testId = makeTestId(dataTestId);
+
     const checkbox = (
       <div style={{ position: 'relative', display: 'inline-flex' }}>
         <StyledCheckbox
@@ -144,7 +147,7 @@ export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
     
     if (label) {
       return (
-        <div data-testid={dataTestId ? `${dataTestId}-container` : 'checkbox-container'}>
+        <div data-testid={testId('container')}>
           <StyledFormControlLabel
             control={checkbox}
             label={label}
@@ -154,7 +157,7 @@ export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
           {helperText && (
             <StyledFormHelperText 
               error={error}
-              data-testid={dataTestId ? `${dataTestId}-helper` : 'checkbox-helper'}
+              data-testid={testId('helper')}
             >
               {helperText}
             </StyledFormHelperText>