@12-apps/ui 1.0.0 → 1.3.1

package/src/components/form/total-form/SubmitButton.tsx

@@ -9,18 +9,41 @@ import { useFormContext } from './FormContext';
 export interface SubmitButtonProps {
   /** Button label. */
   children: React.ReactNode;
+  /** Test id; defaults to `total-form-submit`. Override when a page renders more than one form. */
+  dataTestId?: string;
 }
 
+/**
+ * The height of a form input control (see `Input` — `.MuiInputBase-root`), so a
+ * submit button placed inline with fields lines up with them instead of sitting
+ * shorter. Kept in sync with that value by hand.
+ */
+const FIELD_HEIGHT = 56;
+
 /**
  * Submit control wired to {@link useFormContext}. Wraps the existing `@12-apps/ui`
  * `Button` as a `type="submit"` button (testid `total-form-submit`) and
  * reflects the form's `submitting` state via `loading`/`disabled`.
+ *
+ * It matches the form field height and never wraps its label, so it aligns with
+ * an adjacent input on the same row (and stays full-width when the row stacks).
  */
-export function SubmitButton({ children }: SubmitButtonProps): React.ReactElement {
+export function SubmitButton({
+  children,
+  dataTestId = 'total-form-submit',
+}: SubmitButtonProps): React.ReactElement {
   const { submitting } = useFormContext();
 
   return (
-    <Button type="submit" dataTestId="total-form-submit" loading={submitting} disabled={submitting}>
+    <Button
+      type="submit"
+      dataTestId={dataTestId}
+      loading={submitting}
+      disabled={submitting}
+      // `Button` replaces (not merges) its size styles with this `sx`, so restate
+      // the md padding/font here alongside the field-height + no-wrap alignment.
+      sx={{ height: FIELD_HEIGHT, px: 2, fontSize: '1rem', flexShrink: 0, whiteSpace: 'nowrap' }}
+    >
       {children}
     </Button>
   );

package/src/components/form/total-form/total-form.test.tsx

@@ -1,9 +1,10 @@
 import { describe, it, expect, vi } from "vitest";
 import { fireEvent, render, screen, waitFor } from "@testing-library/react";
-import { email, required } from "@12-apps/shared-helpers/forms";
+import { email, required } from "@12-apps/forms-core";
 
 import { FormContainer, Fields, FormErrorSnackbar, SubmitButton } from "./index";
 import type { FormSubmitHelpers } from "./index";
+import type { CepAddress } from "../CepField";
 
 interface LoginValues extends Record<string, string> {
   email: string;
@@ -95,3 +96,119 @@ describe("total-form (RTL)", () => {
     });
   });
 });
+
+/**
+ * `Fields.CepField` autofill ownership (FUT-306). The adapter writes resolved
+ * address parts into sibling fields, and the rule that keeps it honest runs in
+ * BOTH directions: it must never overwrite what the user typed, and it must
+ * never leave one CEP's address sitting under a different CEP.
+ */
+interface AddressValues extends Record<string, string> {
+  postalCode: string;
+  addressLine1: string;
+  neighborhood: string;
+  city: string;
+  state: string;
+}
+
+const CEP_FILLS = {
+  street: "addressLine1",
+  neighborhood: "neighborhood",
+  city: "city",
+  state: "state",
+} as const;
+
+const PAULISTA: CepAddress = {
+  cep: "01310100",
+  street: "Avenida Paulista",
+  neighborhood: "Bela Vista",
+  city: "São Paulo",
+  state: "SP",
+};
+
+/** A "CEP geral" — a small município's catch-all, which has no logradouro. */
+const CEP_GERAL: CepAddress = {
+  cep: "13800000",
+  street: null,
+  neighborhood: null,
+  city: "Mogi Mirim",
+  state: "SP",
+};
+
+function renderAddressForm(lookup: (cep: string) => Promise<CepAddress | null>) {
+  return render(
+    <FormContainer<AddressValues>
+      initialValues={{
+        postalCode: "",
+        addressLine1: "",
+        neighborhood: "",
+        city: "",
+        state: "",
+      }}
+      onSubmit={() => undefined}
+    >
+      <Fields.CepField name="postalCode" lookup={lookup} fills={CEP_FILLS} debounceMs={0} />
+      <Fields.TextField name="addressLine1" label="Endereço" />
+      <Fields.TextField name="neighborhood" label="Bairro" />
+      <Fields.TextField name="city" label="Cidade" />
+    </FormContainer>,
+  );
+}
+
+const cepField = (name: string): HTMLInputElement =>
+  screen.getByTestId(`total-form-field-${name}`) as HTMLInputElement;
+
+const setCep = (value: string): void => {
+  fireEvent.change(cepField("postalCode"), { target: { value } });
+};
+
+describe("Fields.CepField autofill ownership", () => {
+  it("fills the mapped address fields from a resolved CEP", async () => {
+    renderAddressForm(async () => PAULISTA);
+
+    setCep("01310100");
+
+    await waitFor(() => expect(cepField("addressLine1").value).toBe("Avenida Paulista"));
+    expect(cepField("neighborhood").value).toBe("Bela Vista");
+    expect(cepField("city").value).toBe("São Paulo");
+  });
+
+  it("clears parts the replacement CEP has no value for", async () => {
+    renderAddressForm(async (cep) => (cep === "01310100" ? PAULISTA : CEP_GERAL));
+
+    setCep("01310100");
+    await waitFor(() => expect(cepField("addressLine1").value).toBe("Avenida Paulista"));
+
+    setCep("13800000");
+
+    // The new CEP names no logradouro or bairro, so the old ones must go —
+    // otherwise Avenida Paulista would sit under a Mogi Mirim CEP.
+    await waitFor(() => expect(cepField("city").value).toBe("Mogi Mirim"));
+    expect(cepField("addressLine1").value).toBe("");
+    expect(cepField("neighborhood").value).toBe("");
+  });
+
+  it("undoes its own autofill when a CEP stops resolving", async () => {
+    let hit = true;
+    renderAddressForm(async () => (hit ? PAULISTA : null));
+
+    setCep("01310100");
+    await waitFor(() => expect(cepField("city").value).toBe("São Paulo"));
+
+    hit = false;
+    setCep("99999999");
+
+    await waitFor(() => expect(cepField("city").value).toBe(""));
+    expect(cepField("addressLine1").value).toBe("");
+  });
+
+  it("leaves a field the user typed themselves alone", async () => {
+    renderAddressForm(async () => PAULISTA);
+
+    fireEvent.change(cepField("addressLine1"), { target: { value: "Rua que eu digitei" } });
+    setCep("01310100");
+
+    await waitFor(() => expect(cepField("city").value).toBe("São Paulo"));
+    expect(cepField("addressLine1").value).toBe("Rua que eu digitei");
+  });
+});

package/src/components/layout/Accordion/Accordion.md

@@ -50,7 +50,7 @@ The Accordion component provides expandable/collapsible content sections with sm
 
 ```tsx
 import { Accordion, AccordionSummary, AccordionDetails } from '@mui/material';
-import { ExpandMore } from '@mui/icons-material';
+import ExpandMore from '@mui/icons-material/ExpandMore';
 
 function BasicAccordion() {
   return (

package/src/components/layout/Accordion/Accordion.stories.tsx

@@ -1,4 +1,8 @@
-import { ExpandMore, Help,Info, Security, Settings } from '@mui/icons-material';
+import ExpandMore from '@mui/icons-material/ExpandMore';
+import Help from '@mui/icons-material/Help';
+import Info from '@mui/icons-material/Info';
+import Security from '@mui/icons-material/Security';
+import Settings from '@mui/icons-material/Settings';
 import { Box, Button, Stack,Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';

package/src/components/layout/Accordion/Accordion.styles.ts

@@ -0,0 +1,80 @@
+import { alpha } from '@mui/material';
+import type { Theme } from '@mui/material';
+
+import type { AccordionVariant } from './Accordion.types';
+
+const BASE_TRANSITION = 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)';
+
+// Deliberately unannotated: the inferred union of literals assigns to MUI's
+// `sx`, whereas a `CSSObject` return type does not survive being spread into it.
+export const accordionVariantStyles = (theme: Theme, variant: AccordionVariant) => {
+  switch (variant) {
+    case 'glass':
+      return {
+        backgroundColor: alpha(theme.palette.background.paper, 0.08),
+        backdropFilter: 'blur(24px) saturate(180%)',
+        border: `1px solid ${alpha(theme.palette.primary.main, 0.15)}`,
+        borderRadius: theme.spacing(1.5),
+        transition: BASE_TRANSITION,
+        '&:before': {
+          display: 'none',
+        },
+        '&:hover': {
+          backgroundColor: alpha(theme.palette.background.paper, 0.12),
+          border: `1px solid ${alpha(theme.palette.primary.main, 0.25)}`,
+          transform: 'translateY(-1px)',
+          boxShadow: `0 8px 32px ${alpha(theme.palette.primary.main, 0.12)}`,
+        },
+        '&.Mui-expanded': {
+          backgroundColor: alpha(theme.palette.background.paper, 0.15),
+          border: `1px solid ${alpha(theme.palette.primary.main, 0.3)}`,
+        },
+      };
+    case 'bordered':
+      return {
+        border: `1px solid ${theme.palette.divider}`,
+        borderRadius: theme.spacing(1),
+        transition: BASE_TRANSITION,
+        '&:before': {
+          display: 'none',
+        },
+        '&:not(:last-child)': {
+          marginBottom: theme.spacing(1),
+        },
+        '&:hover': {
+          borderColor: theme.palette.primary.main,
+          boxShadow: `0 0 0 1px ${alpha(theme.palette.primary.main, 0.1)}`,
+        },
+        '&.Mui-expanded': {
+          borderColor: theme.palette.primary.main,
+        },
+      };
+    case 'separated':
+      return {
+        boxShadow: theme.shadows[2],
+        borderRadius: theme.spacing(1.5),
+        transition: BASE_TRANSITION,
+        '&:before': {
+          display: 'none',
+        },
+        '&:not(:last-child)': {
+          marginBottom: theme.spacing(2),
+        },
+        '&:hover': {
+          boxShadow: theme.shadows[4],
+          transform: 'translateY(-2px)',
+        },
+        '&.Mui-expanded': {
+          boxShadow: theme.shadows[6],
+          transform: 'translateY(-1px)',
+        },
+      };
+    default:
+      return {
+        transition: BASE_TRANSITION,
+        '&:hover': {
+          backgroundColor: alpha(theme.palette.action.hover, 0.04),
+        },
+      };
+  }
+};

package/src/components/layout/Accordion/Accordion.test.stories.tsx

@@ -1,4 +1,5 @@
-import { ExpandMore, Settings } from '@mui/icons-material';
+import ExpandMore from '@mui/icons-material/ExpandMore';
+import Settings from '@mui/icons-material/Settings';
 import { Box, Button, Stack,Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useState } from 'react';
@@ -215,18 +216,22 @@ export const KeyboardNavigation: Story = {
       const firstSummary = canvas.getByTestId('first-summary');
       const secondSummary = canvas.getByTestId('second-summary');
 
-      // Focus first summary
-      firstSummary.focus();
-      await expect(firstSummary).toHaveFocus();
+      // Tab in from the body rather than calling .focus() — the old first
+      // assertion only proved the DOM honours focus().
+      await userEvent.tab();
+      await waitFor(() => expect(firstSummary).toHaveFocus());
 
       // Tab to second summary
       await userEvent.tab();
-      await expect(secondSummary).toHaveFocus();
+      await waitFor(() => expect(secondSummary).toHaveFocus());
     });
 
     await step('Enter key to expand accordion', async () => {
       const firstSummary = canvas.getByTestId('first-summary');
-      firstSummary.focus();
+
+      // Focus is on the second summary from the previous step; shift-tab back.
+      await userEvent.tab({ shift: true });
+      await waitFor(() => expect(firstSummary).toHaveFocus());
 
       await userEvent.keyboard('{Enter}');
 
@@ -239,12 +244,15 @@ export const KeyboardNavigation: Story = {
     await step('Tab into expanded content', async () => {
       const firstButton = canvas.getByTestId('first-button');
       await userEvent.tab();
-      await expect(firstButton).toHaveFocus();
+      await waitFor(() => expect(firstButton).toHaveFocus());
     });
 
     await step('Space key to expand accordion', async () => {
       const secondSummary = canvas.getByTestId('second-summary');
-      secondSummary.focus();
+
+      // Continue the journey forward from the button inside the first panel.
+      await userEvent.tab();
+      await waitFor(() => expect(secondSummary).toHaveFocus());
 
       await userEvent.keyboard(' ');
 
@@ -351,14 +359,14 @@ export const FocusManagement: Story = {
 
     await step('Initial focus state', async () => {
       const externalTrigger = canvas.getByTestId('external-trigger');
-      externalTrigger.focus();
-      await expect(externalTrigger).toHaveFocus();
+      await userEvent.tab();
+      await waitFor(() => expect(externalTrigger).toHaveFocus());
     });
 
     await step('Focus on accordion summary', async () => {
       const summary = canvas.getByTestId('focus-summary');
-      summary.focus();
-      await expect(summary).toHaveFocus();
+      await userEvent.tab();
+      await waitFor(() => expect(summary).toHaveFocus());
     });
 
     await step('Expand accordion and check focus flow', async () => {
@@ -375,9 +383,6 @@ export const FocusManagement: Story = {
         { timeout: 1000 },
       );
 
-      // Small delay to ensure DOM is stable after animation
-      await new Promise((resolve) => setTimeout(resolve, 150));
-
       // Tab through the expanded content with proper focus waiting
       await userEvent.tab();
       await waitFor(
@@ -438,15 +443,8 @@ export const FocusManagement: Story = {
     await step('Focus restoration after collapse', async () => {
       const summary = canvas.getByTestId('focus-summary');
 
-      // First ensure summary has focus before clicking
-      summary.focus();
-      await waitFor(
-        () => {
-          expect(summary).toHaveFocus();
-        },
-        { timeout: 500 },
-      );
-
+      // No pre-focus: clicking the summary focuses it, so calling .focus()
+      // first only asserted that focus() works.
       // Click to collapse
       await userEvent.click(summary);
 
@@ -527,8 +525,9 @@ export const VisualStates: Story = {
       await expect(styles.pointerEvents).toBe('none');
 
       // Content should remain hidden since it can't be clicked
-      const details = canvas.queryByText('This should not be accessible');
-      await expect(details).not.toBeVisible();
+      await waitFor(() =>
+        expect(canvas.queryByText('This should not be accessible')).not.toBeVisible(),
+      );
     });
 
     await step('Expand animation test', async () => {
@@ -811,8 +810,6 @@ export const FormInteraction: Story = {
                 variant="contained"
                 onClick={() => {
                   // Form submission handler
-                  // eslint-disable-next-line no-console
-                  console.log('Form submitted:', formData);
                 }}
               >
                 Submit
@@ -1319,44 +1316,29 @@ export const PerformanceTest: Story = {
 
     await step('Measure initial render time', async () => {
 
-      const startTime = performance.now();
+      // No wall-clock budget: getAllByTestId queries DOM that has already
+      // rendered, so timing around it measured query time, and any threshold is
+      // really a bet on how loaded the runner is. The count is the real check.
       const accordions = canvas.getAllByTestId(/^perf-accordion-\d+$/);
-
-      const endTime = performance.now();
-
-      const renderTime = endTime - startTime;
-      // eslint-disable-next-line no-console
-      console.log(`Render time for ${accordions.length} accordions: ${renderTime}ms`);
-
       await expect(accordions.length).toBe(20);
-      // Assert reasonable render time (lenient threshold for CI/CD variability)
-      await expect(renderTime).toBeLessThan(500);
     });
 
     await step('Test rapid expand/collapse performance', async () => {
 
-      const startTime = performance.now();
-
-      // Rapidly expand/collapse multiple accordions
+      // Expand then collapse each accordion, waiting on the state the click is
+      // supposed to produce rather than sleeping 50ms and hoping it landed.
       for (let i = 0; i < 5; i++) {
         const accordion = canvas.getByTestId(`perf-accordion-${i}`);
         const summary = accordion.querySelector('.MuiAccordionSummary-root');
 
         if (summary) {
           await userEvent.click(summary);
+          await waitFor(() => expect(summary).toHaveAttribute('aria-expanded', 'true'));
 
-          await new Promise((resolve) => setTimeout(resolve, 50));
           await userEvent.click(summary);
+          await waitFor(() => expect(summary).toHaveAttribute('aria-expanded', 'false'));
         }
       }
-
-      const endTime = performance.now();
-      const interactionTime = endTime - startTime;
-      // eslint-disable-next-line no-console
-      console.log(`Interaction time for 5 accordions: ${interactionTime}ms`);
-
-      // Verify no performance issues (lenient threshold for CI/CD variability)
-      await expect(interactionTime).toBeLessThan(3000);
     });
   },
 };

package/src/components/layout/Accordion/Accordion.tsx

@@ -8,6 +8,7 @@ import {
   useTheme} from '@mui/material';
 import React from 'react';
 
+import { accordionVariantStyles } from './Accordion.styles';
 import type { 
   AccordionActionsProps, 
   AccordionDetailsProps, 
@@ -27,80 +28,6 @@ export const Accordion: React.FC<AccordionProps> = ({
 }) => {
   const theme = useTheme();
 
-  const getVariantStyles = () => {
-    const baseTransition = 'all 0.3s cubic-bezier(0.4, 0, 0.2, 1)';
-    
-    switch (variant) {
-      case 'glass':
-        return {
-          backgroundColor: alpha(theme.palette.background.paper, 0.08),
-          backdropFilter: 'blur(24px) saturate(180%)',
-          border: `1px solid ${alpha(theme.palette.primary.main, 0.15)}`,
-          borderRadius: theme.spacing(1.5),
-          transition: baseTransition,
-          '&:before': {
-            display: 'none',
-          },
-          '&:hover': {
-            backgroundColor: alpha(theme.palette.background.paper, 0.12),
-            border: `1px solid ${alpha(theme.palette.primary.main, 0.25)}`,
-            transform: 'translateY(-1px)',
-            boxShadow: `0 8px 32px ${alpha(theme.palette.primary.main, 0.12)}`,
-          },
-          '&.Mui-expanded': {
-            backgroundColor: alpha(theme.palette.background.paper, 0.15),
-            border: `1px solid ${alpha(theme.palette.primary.main, 0.3)}`,
-          },
-        };
-      case 'bordered':
-        return {
-          border: `1px solid ${theme.palette.divider}`,
-          borderRadius: theme.spacing(1),
-          transition: baseTransition,
-          '&:before': {
-            display: 'none',
-          },
-          '&:not(:last-child)': {
-            marginBottom: theme.spacing(1),
-          },
-          '&:hover': {
-            borderColor: theme.palette.primary.main,
-            boxShadow: `0 0 0 1px ${alpha(theme.palette.primary.main, 0.1)}`,
-          },
-          '&.Mui-expanded': {
-            borderColor: theme.palette.primary.main,
-          },
-        };
-      case 'separated':
-        return {
-          boxShadow: theme.shadows[2],
-          borderRadius: theme.spacing(1.5),
-          transition: baseTransition,
-          '&:before': {
-            display: 'none',
-          },
-          '&:not(:last-child)': {
-            marginBottom: theme.spacing(2),
-          },
-          '&:hover': {
-            boxShadow: theme.shadows[4],
-            transform: 'translateY(-2px)',
-          },
-          '&.Mui-expanded': {
-            boxShadow: theme.shadows[6],
-            transform: 'translateY(-1px)',
-          },
-        };
-      default:
-        return {
-          transition: baseTransition,
-          '&:hover': {
-            backgroundColor: alpha(theme.palette.action.hover, 0.04),
-          },
-        };
-    }
-  };
-
   return (
     <MuiAccordion
       disabled={disabled}
@@ -109,7 +36,7 @@ export const Accordion: React.FC<AccordionProps> = ({
       onChange={onChange}
       data-testid={testId}
       sx={{
-        ...getVariantStyles(),
+        ...accordionVariantStyles(theme, variant),
         ...sx,
       }}
       {...props}

package/src/components/layout/Card/Card.helpers.ts

@@ -0,0 +1,30 @@
+import type { CardProps } from './Card.types';
+
+type CardDefaultedKeys =
+  | 'variant'
+  | 'interactive'
+  | 'glow'
+  | 'pulse'
+  | 'borderRadius'
+  | 'loading';
+
+type ResolvedCardProps = CardProps & Required<Pick<CardProps, CardDefaultedKeys>>;
+
+const CARD_DEFAULTS: Pick<CardProps, CardDefaultedKeys> = {
+  variant: 'elevated',
+  interactive: false,
+  glow: false,
+  pulse: false,
+  borderRadius: 'md',
+  loading: false,
+};
+
+// Strips explicitly-undefined props before the merge, so `glow={undefined}` still
+// falls back to the default exactly as a destructuring default would.
+const definedProps = (props: CardProps): Partial<CardProps> =>
+  Object.fromEntries(
+    Object.entries(props).filter(([, value]) => value !== undefined),
+  ) as Partial<CardProps>;
+
+export const resolveCardProps = (props: CardProps): ResolvedCardProps =>
+  ({ ...CARD_DEFAULTS, ...definedProps(props) }) as ResolvedCardProps;

package/src/components/layout/Card/Card.stories.tsx

@@ -1,14 +1,12 @@
-import {
-  Edit,
-  Email,
-  Favorite,
-  LocationOn,
-  MoreVert,
-  Phone,
-  Share,
-  ShoppingCart,
-  Star,
-} from '@mui/icons-material';
+import Edit from '@mui/icons-material/Edit';
+import Email from '@mui/icons-material/Email';
+import Favorite from '@mui/icons-material/Favorite';
+import LocationOn from '@mui/icons-material/LocationOn';
+import MoreVert from '@mui/icons-material/MoreVert';
+import Phone from '@mui/icons-material/Phone';
+import Share from '@mui/icons-material/Share';
+import ShoppingCart from '@mui/icons-material/ShoppingCart';
+import Star from '@mui/icons-material/Star';
 import { Avatar, Box, Button, Chip, Grid,IconButton, Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';