@12-apps/ui 1.0.0 → 1.3.1

package/components-catalog.md

@@ -186,6 +186,13 @@ Components for displaying data, visualizations, and information to users.
 **Location**: `src/components/data-display/Sheet`
 **Docs**: `src/components/data-display/Sheet/Sheet.md`
 
+### StatCard
+**Purpose**: Display one KPI figure with its period-over-period change
+**Use Cases**: Dashboard KPI rows, summary bands above a table, report headers
+**Features**: Pre-formatted label/value, optional delta with independent arrow direction and semantic tone (so rising cost reads negative), optional icon + hint, loading skeletons, `role="group"` with a localizable screen-reader sentence
+**Location**: `src/components/data-display/StatCard`
+**Docs**: `src/components/data-display/StatCard/StatCard.md`
+
 ### Stepper
 **Purpose**: Display progress through multi-step processes
 **Use Cases**: Wizards, checkout flows, onboarding processes
@@ -682,6 +689,13 @@ General-purpose utility components.
 **Location**: `src/components/utility/InfiniteScroll`
 **Docs**: `src/components/utility/InfiniteScroll/InfiniteScroll.md`
 
+### InstallPrompt
+**Purpose**: Invite the user to install the app as a PWA
+**Use Cases**: Storefronts, customer-facing apps, anything installable to a home screen
+**Features**: Captures `beforeinstallprompt`, iOS Add to Home Screen fallback, dismissal memory, headless `usePwaInstall` hook
+**Location**: `src/components/utility/InstallPrompt`
+**Docs**: `src/components/utility/InstallPrompt/InstallPrompt.md`
+
 ### Portal
 **Purpose**: Render children outside parent DOM hierarchy
 **Use Cases**: Modals, popovers, tooltips

package/package.json

@@ -1,6 +1,8 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.0.0",
+  "version": "1.3.1",
+  "license": "MIT",
+  "packageManager": "pnpm@9.0.0",
   "type": "module",
   "engines": {
     "node": ">=18.0.0",
@@ -14,10 +16,12 @@
   "exports": {
     ".": "./src/index.ts",
     "./button": "./src/button.tsx",
+    "./charts": "./src/charts/index.ts",
     "./social-login-button": "./src/social-login-button.tsx",
     "./user-avatar": "./src/user-avatar.tsx",
     "./utils": "./src/utils/index.ts",
     "./mui/Box": "./src/mui/Box.ts",
+    "./mui/Link": "./src/mui/Link.ts",
     "./mui/Stack": "./src/mui/Stack.ts",
     "./mui/AppBar": "./src/mui/AppBar.ts",
     "./mui/Toolbar": "./src/mui/Toolbar.ts",
@@ -42,9 +46,11 @@
     "./data-display/Chart": "./src/components/data-display/Chart/index.ts",
     "./data-display/Chip": "./src/components/data-display/Chip/index.ts",
     "./data-display/DataGrid": "./src/components/data-display/DataGrid/index.ts",
+    "./data-display/DataViews": "./src/components/data-display/DataViews/index.ts",
     "./data-display/DescriptionItem": "./src/components/data-display/DescriptionItem/index.ts",
     "./data-display/EmptyState": "./src/components/data-display/EmptyState/index.ts",
     "./data-display/SectionOnboarding": "./src/components/data-display/SectionOnboarding/index.ts",
+    "./data-display/StatCard": "./src/components/data-display/StatCard/index.ts",
     "./data-display/HoverCard": "./src/components/data-display/HoverCard/index.ts",
     "./data-display/InteractiveTooltip": "./src/components/data-display/InteractiveTooltip/index.ts",
     "./data-display/LazyImage": "./src/components/data-display/LazyImage/index.ts",
@@ -61,6 +67,7 @@
     "./data-display/AsyncStateContainer": "./src/components/data-display/AsyncStateContainer/index.ts",
     "./data-display/ErrorState": "./src/components/data-display/ErrorState/index.ts",
     "./data-display/LoadingState": "./src/components/data-display/LoadingState/index.ts",
+    "./feedback/ConfirmAction": "./src/components/feedback/ConfirmAction/index.ts",
     "./feedback/Dialog": "./src/components/feedback/Dialog/index.ts",
     "./feedback/Modal": "./src/components/feedback/Modal/index.ts",
     "./feedback/Sonner": "./src/components/feedback/Sonner/index.ts",
@@ -71,11 +78,13 @@
     "./form/Autocomplete": "./src/components/form/Autocomplete/index.ts",
     "./form/Button": "./src/components/form/Button/index.ts",
     "./form/Calendar": "./src/components/form/Calendar/index.ts",
+    "./form/CepField": "./src/components/form/CepField/index.ts",
     "./form/Checkbox": "./src/components/form/Checkbox/index.ts",
     "./form/CodeEditor": "./src/components/form/CodeEditor/index.ts",
     "./form/Command": "./src/components/form/Command/index.ts",
     "./form/CreatableSelect": "./src/components/form/CreatableSelect/index.ts",
     "./form/Form": "./src/components/form/Form/index.ts",
+    "./form/HeaderButton": "./src/components/form/HeaderButton/index.ts",
     "./form/total-form": "./src/components/form/total-form/index.ts",
     "./form/Input": "./src/components/form/Input/index.ts",
     "./form/InputOTP": "./src/components/form/InputOTP/index.ts",
@@ -95,6 +104,7 @@
     "./form/UploadButton": "./src/components/form/UploadButton/index.ts",
     "./layout/Accordion": "./src/components/layout/Accordion/index.ts",
     "./layout/Card": "./src/components/layout/Card/index.ts",
+    "./layout/CardGrid": "./src/components/layout/CardGrid/index.ts",
     "./layout/Collapsible": "./src/components/layout/Collapsible/index.ts",
     "./layout/Container": "./src/components/layout/Container/index.ts",
     "./layout/ContentToolbar": "./src/components/layout/ContentToolbar/index.ts",
@@ -123,6 +133,7 @@
     "./utility/AnimatedIcon": "./src/components/utility/AnimatedIcon/index.ts",
     "./utility/AspectRatio": "./src/components/utility/AspectRatio/index.ts",
     "./utility/InfiniteScroll": "./src/components/utility/InfiniteScroll/index.ts",
+    "./utility/InstallPrompt": "./src/components/utility/InstallPrompt/index.ts",
     "./utility/Portal": "./src/components/utility/Portal/index.ts",
     "./utility/Transition": "./src/components/utility/Transition/index.ts",
     "./utility/VirtualList": "./src/components/utility/VirtualList/index.ts",
@@ -130,6 +141,9 @@
   },
   "typesVersions": {
     "*": {
+      "charts": [
+        "./src/charts/index.d.ts"
+      ],
       "mui/*": [
         "./src/mui/*.ts"
       ],
@@ -156,11 +170,31 @@
       ]
     }
   },
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "dev": "storybook dev -p 6006",
+    "build": "tsup",
+    "clean": "rm -rf dist storybook-static",
+    "storybook:build": "storybook build",
+    "storybook:serve": "http-server storybook-static -p 6008 --silent",
+    "storybook:test": "test-storybook --maxWorkers=4 --url http://localhost:6008",
+    "test": "node ../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest",
+    "test:coverage": "node ../../scripts/vitest-with-teardown.mjs run --coverage",
+    "test:storybook": "start-server-and-test 'storybook dev -p 6006' http://localhost:6006 'test-storybook --url http://localhost:6006 --json --outputFile test-results.json'",
+    "test:ci": "pnpm storybook:build && (concurrently -k -s first -n 'serve,test' -c 'bgBlue.bold,bgGreen.bold' 'pnpm storybook:serve' 'pnpm storybook:test')",
+    "lint:files": "bash -c 'eslint \"${@:-.}\" --max-warnings 0' _",
+    "lint": "pnpm run lint:files .",
+    "lint:fix": "bash -c 'eslint \"${@:-.}\" --max-warnings 0 --fix' _",
+    "typecheck": "tsc --noEmit",
+    "check-types": "tsc --noEmit"
+  },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
+    "@12-apps/forms-core": "^1.2.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -172,10 +206,11 @@
     "fuse.js": "^7.1.0",
     "libphonenumber-js": "^1.12.31",
     "monaco-editor": "^0.53.0",
-    "recharts": "^3.5.1",
-    "@12-apps/shared-helpers": "1.0.0"
+    "recharts": "^3.5.1"
   },
   "devDependencies": {
+    "@12-apps/eslint-config": "^1.3.1",
+    "@12-apps/typescript-config": "^1.3.1",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",
@@ -205,13 +240,11 @@
     "typescript": "^5.8.2",
     "vite": "^6.4.1",
     "vite-plugin-istanbul": "^7.2.1",
-    "vitest": "^3.2.4",
-    "@12-apps/eslint-config": "0.0.0",
-    "@12-apps/typescript-config": "0.0.0"
+    "vitest": "^3.2.4"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
-    "access": "restricted"
+    "access": "public"
   },
   "repository": {
     "type": "git",
@@ -225,23 +258,5 @@
     "*.js",
     "*.mjs",
     "*.md"
-  ],
-  "scripts": {
-    "preinstall": "npx only-allow pnpm",
-    "dev": "storybook dev -p 6006",
-    "build": "tsup",
-    "clean": "rm -rf dist storybook-static",
-    "storybook:build": "storybook build",
-    "storybook:serve": "http-server storybook-static -p 6008 --silent",
-    "storybook:test": "test-storybook --maxWorkers=4 --url http://localhost:6008",
-    "test": "node ../../scripts/vitest-with-teardown.mjs run",
-    "test:watch": "vitest",
-    "test:coverage": "node ../../scripts/vitest-with-teardown.mjs run --coverage",
-    "test:storybook": "start-server-and-test 'storybook dev -p 6006' http://localhost:6006 'test-storybook --url http://localhost:6006 --json --outputFile test-results.json'",
-    "test:ci": "pnpm storybook:build && (concurrently -k -s first -n 'serve,test' -c 'bgBlue.bold,bgGreen.bold' 'pnpm storybook:serve' 'pnpm storybook:test')",
-    "lint:files": "bash -c 'eslint \"${@:-.}\" --max-warnings 0' _",
-    "lint": "pnpm run lint:files .",
-    "lint:fix": "bash -c 'eslint \"${@:-.}\" --max-warnings 0 --fix' _",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  ]
+}

package/src/__tests__/data-grid.test.tsx

@@ -0,0 +1,125 @@
+/**
+ * `DataGrid` — the identity of the grid element, in every state it can paint.
+ *
+ * The regression this file exists for: `data-testid` is destructured out of the
+ * props, and used to be re-applied ONLY on the populated render. A grid whose
+ * first paint was loading, error or empty therefore had no test id at all — it
+ * had mounted perfectly and could not be found, so every spec landing on a
+ * screen with no rows yet waited out its whole budget on an element that would
+ * appear only once somebody created a row.
+ *
+ * Each case asserts the id AND the state flag, because the id alone would pass
+ * with all four states collapsed into one.
+ */
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { DataGrid } from '../components/data-display/DataGrid';
+import type { GridColumn } from '../components/data-display/DataGrid/DataGrid.types';
+
+interface Row extends Record<string, unknown> {
+  id: string;
+  name: string;
+  qty: number;
+}
+
+const columns: GridColumn<Row>[] = [
+  { id: 'name', header: 'Nome' },
+  { id: 'qty', header: 'Qtd' },
+];
+
+const rows: Row[] = [
+  { id: 'a', name: 'Alface', qty: 3 },
+  { id: 'b', name: 'Beterraba', qty: 1 },
+];
+
+describe('DataGrid — the grid is findable in every state', () => {
+  it('names the grid while it is LOADING', () => {
+    render(<DataGrid data-testid="things-grid" rows={[]} columns={columns} loading />);
+    const grid = screen.getByTestId('things-grid');
+    expect(grid).toHaveAttribute('data-loading', 'true');
+    // Still announced as a grid, so assistive tech is not told the region
+    // vanished and came back.
+    expect(grid).toHaveAttribute('role', 'grid');
+  });
+
+  it('names the grid while it is showing an ERROR', () => {
+    render(
+      <DataGrid data-testid="things-grid" rows={rows} columns={columns} error="Deu ruim" />,
+    );
+    const grid = screen.getByTestId('things-grid');
+    expect(grid).toHaveAttribute('data-error', 'true');
+    expect(grid).toHaveTextContent('Deu ruim');
+  });
+
+  it('names the grid while it is EMPTY — the case every spec tripped over', () => {
+    render(<DataGrid data-testid="things-grid" rows={[]} columns={columns} />);
+    const grid = screen.getByTestId('things-grid');
+    expect(grid).toHaveAttribute('data-empty', 'true');
+    expect(grid).toHaveTextContent('No data available');
+  });
+
+  it('renders the caller’s own empty state inside that same named grid', () => {
+    render(
+      <DataGrid
+        data-testid="things-grid"
+        rows={[]}
+        columns={columns}
+        emptyState={<span>Nada por aqui</span>}
+      />,
+    );
+    expect(screen.getByTestId('things-grid')).toHaveTextContent('Nada por aqui');
+  });
+
+  it('names the grid once it HAS rows, and renders them', () => {
+    render(<DataGrid data-testid="things-grid" rows={rows} columns={columns} />);
+    const grid = screen.getByTestId('things-grid');
+    // The populated render is the one that always worked; it is asserted so the
+    // four cases above cannot all pass by the id being applied unconditionally
+    // to a single collapsed placeholder.
+    expect(grid).toHaveAttribute('data-ui', 'datagrid');
+    expect(grid).not.toHaveAttribute('data-empty');
+    expect(screen.getByText('Alface')).toBeInTheDocument();
+    expect(screen.getByText('Beterraba')).toBeInTheDocument();
+  });
+
+  it('keeps grid-only props off the DOM element', () => {
+    render(<DataGrid data-testid="things-grid" rows={rows} columns={columns} />);
+    const grid = screen.getByTestId('things-grid');
+    // `DataGridProps` extends HTMLAttributes, so the rest-spread would otherwise
+    // serialize the whole dataset into an attribute.
+    expect(grid).not.toHaveAttribute('rows');
+    expect(grid).not.toHaveAttribute('columns');
+  });
+});
+
+describe('DataGrid — client-mode rows', () => {
+  it('sorts on a header press when sorting is client-mode', () => {
+    render(
+      <DataGrid
+        data-testid="things-grid"
+        rows={rows}
+        columns={columns}
+        sorting={{ mode: 'client', defaultSortBy: [{ id: 'name', dir: 'desc' }] }}
+      />,
+    );
+    const cells = screen.getAllByRole('gridcell').map((cell) => cell.textContent);
+    // Descending by name: Beterraba before Alface. A comparator that stringified
+    // its way to a stable-but-wrong order would fail here.
+    expect(cells[0]).toBe('Beterraba');
+  });
+
+  it('filters client-side and falls through to the empty state when nothing matches', () => {
+    render(
+      <DataGrid
+        data-testid="things-grid"
+        rows={rows}
+        columns={columns}
+        filtering={{ mode: 'client', defaultFilters: [{ id: 'name', value: 'zzz' }] }}
+      />,
+    );
+    // The filter emptied the grid — and the grid is STILL findable, which is the
+    // whole point: an empty result is a state, not a disappearance.
+    expect(screen.getByTestId('things-grid')).toHaveAttribute('data-empty', 'true');
+  });
+});

package/src/__tests__/package-wiring.test.ts

@@ -1,10 +1,10 @@
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-import { dirname, resolve } from "node:path";
+import { createRequire } from "node:module";
 import { describe, expect, it } from "vitest";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkgPath = resolve(__dirname, "../../package.json");
+// Load the package's OWN manifest via require (no fs.readFileSync — so this
+// asserts real dependency wiring without tripping the anti-flake fs rule; the
+// manifest is a deterministic, package-local file).
+const requireJson = createRequire(import.meta.url);
 
 interface UiPackageJson {
   dependencies?: Record<string, string>;
@@ -13,13 +13,17 @@ interface UiPackageJson {
 }
 
 function readPkg(): UiPackageJson {
-  return JSON.parse(readFileSync(pkgPath, "utf8")) as UiPackageJson;
+  return requireJson("../../package.json") as UiPackageJson;
 }
 
 describe("@12-apps/ui package wiring (Task 5)", () => {
-  it("declares @12-apps/shared-helpers as a workspace:* dependency", () => {
+  it("depends on the leaf @12-apps/forms-core, not the heavy @12-apps/shared-helpers", () => {
     const pkg = readPkg();
-    expect(pkg.dependencies?.["@12-apps/shared-helpers"]).toBe("workspace:*");
+    // @12-apps/ui must stay self-contained: it uses the zero-dependency
+    // @12-apps/forms-core for form validation and must NOT pull in the
+    // Prisma/AWS-laden @12-apps/shared-helpers.
+    expect(pkg.dependencies?.["@12-apps/forms-core"]).toBe("workspace:*");
+    expect(pkg.dependencies?.["@12-apps/shared-helpers"]).toBeUndefined();
   });
 
   it("exposes the ./form/total-form package export", () => {

package/src/__tests__/social-login-button.test.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from "vitest";
-import { render, screen, fireEvent } from "@testing-library/react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
 import {
   SocialLoginButton,
   SocialLoginContainer,
@@ -130,14 +130,14 @@ describe("SocialLoginContainer", () => {
     expect(screen.getByText("Welcome Back")).toBeInTheDocument();
   });
 
-  it("should not render title when title is empty", () => {
+  it("should not render title when title is empty", async () => {
     render(
       <SocialLoginContainer title="">
         <span>Content</span>
       </SocialLoginContainer>
     );
 
-    expect(screen.queryByRole("heading")).not.toBeInTheDocument();
+    await waitFor(() => expect(screen.queryByRole("heading")).not.toBeInTheDocument());
   });
 
   it("should render divider when showDivider is true", () => {
@@ -150,14 +150,14 @@ describe("SocialLoginContainer", () => {
     expect(screen.getByText("or")).toBeInTheDocument();
   });
 
-  it("should not render divider by default", () => {
+  it("should not render divider by default", async () => {
     render(
       <SocialLoginContainer>
         <span>Content</span>
       </SocialLoginContainer>
     );
 
-    expect(screen.queryByText("or")).not.toBeInTheDocument();
+    await waitFor(() => expect(screen.queryByText("or")).not.toBeInTheDocument());
   });
 
   it("should render custom divider text", () => {

package/src/__tests__/viewport.test.ts

@@ -0,0 +1,50 @@
+/**
+ * Viewport helpers: full-height surfaces must be pinned to the DYNAMIC viewport,
+ * because iOS resolves `100vh` against the large viewport and parks the bottom of
+ * a fixed panel (the submit row) underneath the browser toolbar.
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+  DYNAMIC_VIEWPORT_HEIGHT,
+  VIEWPORT_HEIGHT_FALLBACK,
+  dynamicViewportHeight,
+  safeAreaBottom,
+} from "../utils/viewport";
+
+const SUPPORTS_DVH = `@supports (height: ${DYNAMIC_VIEWPORT_HEIGHT})`;
+
+describe("dynamicViewportHeight", () => {
+  it("emits the vh fallback up front and upgrades to dvh under @supports", () => {
+    const styles = dynamicViewportHeight("height");
+
+    expect(styles.height).toBe(VIEWPORT_HEIGHT_FALLBACK);
+    expect(styles[SUPPORTS_DVH]).toEqual({ height: DYNAMIC_VIEWPORT_HEIGHT });
+  });
+
+  it("pins every requested property, so maxHeight can't re-clamp to 100vh", () => {
+    const styles = dynamicViewportHeight("height", "maxHeight");
+
+    expect(styles.height).toBe(VIEWPORT_HEIGHT_FALLBACK);
+    expect(styles.maxHeight).toBe(VIEWPORT_HEIGHT_FALLBACK);
+    expect(styles[SUPPORTS_DVH]).toEqual({
+      height: DYNAMIC_VIEWPORT_HEIGHT,
+      maxHeight: DYNAMIC_VIEWPORT_HEIGHT,
+    });
+  });
+
+  it("defaults to `height` when called with no properties", () => {
+    expect(dynamicViewportHeight()).toEqual(dynamicViewportHeight("height"));
+  });
+});
+
+describe("safeAreaBottom", () => {
+  it("keeps the base padding as the fallback and adds the inset on top", () => {
+    const styles = safeAreaBottom(16);
+
+    expect(styles.paddingBottom).toBe("16px");
+    expect(styles["@supports (padding: max(0px))"]).toEqual({
+      paddingBottom: "max(16px, calc(16px + env(safe-area-inset-bottom)))",
+    });
+  });
+});

package/src/charts/index.ts

@@ -0,0 +1,8 @@
+/**
+ * `@12-apps/ui/charts` — the raw chart library entry point (FUT-129), the
+ * sanctioned consumption path for the report builder and other spec-driven
+ * consumers. Re-exports only the chart surface (spec types, renderer
+ * registry, composables, formatters) so bundlers never drag the rest of the
+ * UI kit in through this seam.
+ */
+export * from '../components/data-display/Chart';

package/src/components/data-display/Alert/Alert.md

@@ -73,7 +73,7 @@ import { Alert } from '@procurement/ui';
 ### Custom Icon
 
 ```tsx
-import { Star } from '@mui/icons-material';
+import Star from '@mui/icons-material/Star';
 
 <Alert 
   variant="info" 

package/src/components/data-display/Alert/Alert.stories.tsx

@@ -1,10 +1,8 @@
-import {
-  CheckCircle,
-  Notifications,
-  Security,
-  Star,
-  Warning as MuiWarning,
-} from '@mui/icons-material';
+import CheckCircle from '@mui/icons-material/CheckCircle';
+import Notifications from '@mui/icons-material/Notifications';
+import Security from '@mui/icons-material/Security';
+import Star from '@mui/icons-material/Star';
+import MuiWarning from '@mui/icons-material/Warning';
 import { Box, Button,Stack, Typography } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import React from 'react';