@grupo-elo-editorial/shared-ui-react 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog — `@grupo-elo-editorial/shared-ui-react`
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) · Versioning: [SemVer](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [1.2.0] — 2026-05-24 (HeroCarousel aspect ratios + RSC compatibility)
+
+### Fixed
+
+- **`TopAccessibilityBar`**: the bar background was `var(--background)` — identical to the page background, so the bar blended in and visually disappeared. The "Ferramentas de Acessibilidade" label was also hidden below the `md:` (768px) breakpoint. Switched the bar to `var(--card)` so it sits on the elevated surface (matching the mockup), and dropped the label breakpoint from `md:` to `sm:` (640px) so the label is visible on most desktops/tablets, hiding only on narrow phones.
+
+- **`Footer`**: the catalog navigation column had two entries pointing to the same `href` (`/livros/catalogo` for both "Livros" and "Mais Vendidos"), and the `<li>` `map` used `key={link.href}` — triggering a React duplicate-key warning on every render. Switched the key to `link.label` (unique within a column) and made "Mais Vendidos" point to `/livros/catalogo?ordem=mais_vendidos`. Also redirected "Lançamentos" from the non-existent `/lancamentos` route to `/livros/catalogo?ordem=recentes`, so the link now lands on the catalog with the right sort applied instead of 404'ing.
+
+- **`HeroCarousel`**: the `<img>` aspect ratio was `aspect-[3/4] md:aspect-video` for every breakpoint ≥768px. On desktop this produced a ~720px-tall hero in a 1280px viewport — significantly taller than the mockup (440px) and mismatched against the panoramic desktop banner artwork specified by the site-multibrand PRD (F3 — desktop 1920×700, ratio ~2.74:1). Updated to `aspect-[5/6] md:aspect-video lg:aspect-[1920/700]`, which now matches the PRD-specified artwork dimensions at each breakpoint: mobile 750×900, tablet 1024×576, desktop 1920×700.
+
+- **React Server Components compatibility**: six components used React hooks (`useState`, `useEffect`) without a `'use client'` directive. When consumed from npm as built `dist/` they worked because Vite preserved the runtime behavior, but when resolved via the `development` export condition to the raw `src/` (e.g. when linked into a Next.js App Router project from the workspace) they failed with *"You're importing a component that needs `useState`. This React Hook only works in a Client Component."* Added `'use client'` to:
+  - `atoms/Avatar.tsx`
+  - `atoms/Rating.tsx`
+  - `figma/ImageWithFallback.tsx`
+  - `molecules/SearchBar.tsx`
+  - `prd/HeroCarousel.tsx`
+  - `prd/TopAccessibilityBar.tsx`
+
+  Other client components (`prd/Footer.tsx`, `prd/MegaMenu.tsx`, plus the `ui/` Radix wrappers) already had the directive.
+
+### Migration
+
+No API change. Consumers passing custom `className` to `<HeroCarousel>` continue to work as before. Visual change only — the hero will be shorter on desktop and slightly less tall on mobile. If a consumer was depending on the previous heights, override via `className` on the wrapper to constrain max-height.
+
+### Changed
+
+- `package.json` `version` bumped `1.1.0 → 1.2.0`.
+
+---
+
+## [1.1.0] — 2026-05-20 (Layout primitives + Figma shared-ui sync)
+
+Additive sync with the upstream Figma shared-ui file (`q4V5CYymU4oU5nlbbHNmh8`) and with `@grupo-elo-editorial/design-tokens@3.1.0`. No breaking changes; consumers of `^1.0.0` can bump to `^1.1.0` with zero code changes.
+
+### Added — Layout primitives
+
+Three new layout components that consume the breakpoint/container/grid tokens introduced in `design-tokens@3.1.0`:
+
+- **`Container`** — page-level wrapper. Centers content within `var(--container-max)` (1280px) with responsive `var(--container-px)` (1.5rem) horizontal padding. Polymorphic via the `as` prop (defaults to `'div'`).
+- **`Grid`** — responsive grid primitive. Default progression: `grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4` with `gap-[var(--grid-gutter)]` (1.5rem). Override via `className`.
+- **`Col`** — grid cell with explicit column span (1–6). Always includes `min-w-0` to prevent overflow on wide content (long text, large images) — addresses the implicit `min-width: auto` gotcha on grid items.
+
+```tsx
+import { Container, Grid, Col } from '@grupo-elo-editorial/shared-ui-react';
+
+<Container as="section">
+  <Grid>
+    <Col><ProductCard ... /></Col>
+    <Col><ProductCard ... /></Col>
+    <Col span={2}>Wide cell</Col>
+  </Grid>
+</Container>
+```
+
+### Added — docs
+
+- `docs/SHARED_UI_STANDARDS.md` — prescriptive guide for the package: filosofia, naming conventions, design tokens, A11y WCAG 2.2 AA, estados de componentes, props API, composição, testes, performance, checklist de qualidade, versionamento.
+
+### Changed
+
+- `package.json` `version` bumped `1.0.0 → 1.1.0`.
+- `package.json` `description` updated to mention layout primitives + new `design-tokens@^3.1.0` minimum.
+- `src/index.ts` now re-exports `Container`, `Grid`, `Col` (and their `ContainerProps`/`GridProps`/`ColProps` types) from `./components/layout`.
+- `repository.url` now uses canonical `git+https://` scheme (eliminates `npm publish` warning).
+
+### Compat with design-tokens v3.1.0
+
+`@grupo-elo-editorial/design-tokens@^3.1.0` is the minimum effective dependency now (the layout primitives use `var(--container-max)`, `var(--container-px)`, and `var(--grid-gutter)` which were introduced in 3.1.0). Older 3.0.x of design-tokens still works for everything _except_ the layout primitives, which will render with browser-default sizing if the consumer hasn't bumped design-tokens.
+
+---
+
+## [1.0.0] — 2026-05-13 (Initial release — port from Figma)
+
+First public release. 42 components ported 1:1 from the Figma Make export `loEUZ5dnW0f4e8GwQIEWSz`.
+
+### Added
+
+- **7 custom atoms**: Button, Textarea, Badge, Avatar, Spinner, Divider, Rating
+- **5 custom molecules**: ProductCard, SearchBar, PriceDisplay, QuantitySelector, FormGroup
+- **4 custom organisms**: Hero, EmptyState, ErrorState, ProductGrid
+- **2 PRD domain components**: TopAccessibilityBar, HeroCarousel
+- **~50 shadcn/ui primitives** in `components/ui/` — Radix wrappers (Dialog, Sheet, Select, Tooltip, Accordion, Checkbox, Switch, RadioGroup, Breadcrumb, Progress, Calendar, Carousel, Chart, Command, ContextMenu, Drawer, DropdownMenu, Form, HoverCard, InputOTP, Menubar, NavigationMenu, Pagination, Popover, Resizable, ScrollArea, Separator, Sidebar, Skeleton, Slider, Sonner, Table, Tabs, ToggleGroup, …).
+- **Re-exports** from atoms/molecules/organisms barrels: `Input`, `Select*`, `Checkbox`, `RadioGroup*`, `Toggle (= Switch)`, `Breadcrumb*`, `Accordion*`, `Tooltip*`, `ProgressBar`, `toast (sonner)`, `Modal (= Dialog)`, `Drawer (= Sheet)`.
+- **`figma/ImageWithFallback`** helper.
+- **Util**: `cn` (clsx + tailwind-merge).
+- **Bundled CSS**: `dist/style.css` (96 kB, gzip 9 kB) — Lato fonts + Tailwind v4 + multibrand theme tokens with `[data-brand]` / `[data-theme]` selectors (aligned with `@grupo-elo-editorial/design-tokens@^3.0.0`).
+- **Docs imported from Figma**: `docs/COMPONENT_LIBRARY.md`, `docs/CORRECTIONS.md`, `docs/GUIDELINES.md`.
+
+### Notes
+
+- Stack: React 18+/19, TypeScript, Tailwind CSS v4, Radix UI, Lucide icons, Sonner toasts, `class-variance-authority` for variants.
+- Brand + theme contract: `<html data-brand="elo-editora|perabook" data-theme="light|dark">` — same as design-tokens.
+- The Figma export used `.brand-elo` / `.brand-pera` / `.dark` class selectors; this port adapted to `[data-brand]` / `[data-theme]` attribute selectors to match the design-tokens v3 contract. Component code consumes `var(--brand-*)` so the visual result is identical.

package/dist/components/layout/Col.d.ts

@@ -0,0 +1,29 @@
+import { type ReactNode } from 'react';
+export interface ColProps {
+    children: ReactNode;
+    /**
+     * How many grid columns this cell spans (1–6). When omitted, the cell takes
+     * one column at every breakpoint.
+     */
+    span?: 1 | 2 | 3 | 4 | 5 | 6;
+    className?: string;
+}
+/**
+ * Grid cell with explicit column span. Always includes `min-w-0` to prevent
+ * grid items from overflowing when their content (long text, large images) is
+ * wider than the available column — without this the implicit `min-width: auto`
+ * on grid items would push the cell beyond its grid track.
+ *
+ * Use inside `<Grid>`. Not strictly required (you can use a plain `<div>` for
+ * 1-column cells), but recommended for any cell that spans multiple columns.
+ *
+ * @example
+ * ```tsx
+ * <Grid>
+ *   <Col span={2}>Wide cell</Col>
+ *   <Col>Standard cell</Col>
+ *   <Col>Standard cell</Col>
+ * </Grid>
+ * ```
+ */
+export declare function Col({ children, span, className }: ColProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/layout/Container.d.ts

@@ -0,0 +1,21 @@
+import { type ElementType, type ReactNode } from 'react';
+export interface ContainerProps {
+    children: ReactNode;
+    /** Override the wrapper element. Default `'div'`. */
+    as?: ElementType;
+    className?: string;
+}
+/**
+ * Page-level content wrapper. Centers content within `var(--container-max)`
+ * (1280px by default in `@grupo-elo-editorial/design-tokens@^3.1.0`) and applies
+ * the responsive `var(--container-px)` horizontal padding.
+ *
+ * @example
+ * ```tsx
+ * <Container as="section">
+ *   <h2>Section heading</h2>
+ *   <p>Body content stays within the centered, padded container.</p>
+ * </Container>
+ * ```
+ */
+export declare function Container({ children, as: Tag, className }: ContainerProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/layout/Grid.d.ts

@@ -0,0 +1,24 @@
+import { type ReactNode } from 'react';
+export interface GridProps {
+    children: ReactNode;
+    /**
+     * Override the default responsive column progression
+     * (`grid-cols-1 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4`) by appending Tailwind utility classes here.
+     */
+    className?: string;
+}
+/**
+ * Responsive grid primitive. Defaults to the progression defined by the
+ * `--grid-cols-{default,sm,md,lg}` tokens (1 → 2 → 3 → 4 columns) and the
+ * `--grid-gutter` (1.5rem) gap, both shipped by
+ * `@grupo-elo-editorial/design-tokens@^3.1.0`.
+ *
+ * @example
+ * ```tsx
+ * <Grid>
+ *   <Col><ProductCard ... /></Col>
+ *   <Col><ProductCard ... /></Col>
+ * </Grid>
+ * ```
+ */
+export declare function Grid({ children, className }: GridProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/layout/index.d.ts

@@ -0,0 +1,6 @@
+export { Container } from './Container';
+export type { ContainerProps } from './Container';
+export { Grid } from './Grid';
+export type { GridProps } from './Grid';
+export { Col } from './Col';
+export type { ColProps } from './Col';

package/dist/components/molecules/ProductCard.d.ts

@@ -2,6 +2,7 @@ import { HTMLAttributes } from 'react';
 export interface ProductCardProps extends HTMLAttributes<HTMLDivElement> {
     image: string;
     title: string;
+    author?: string;
     price: number;
     originalPrice?: number;
     rating?: number;
@@ -13,6 +14,10 @@ export interface ProductCardProps extends HTMLAttributes<HTMLDivElement> {
     onAddToCart?: () => void;
     onToggleFavorite?: () => void;
     isFavorite?: boolean;
+    /** Makes the card image and title clickable as a link. */
+    href?: string;
+    /** 'vertical' (default) stacks image above content; 'horizontal' places a compact image to the left. */
+    orientation?: 'vertical' | 'horizontal';
 }
 declare const ProductCard: import("react").ForwardRefExoticComponent<ProductCardProps & import("react").RefAttributes<HTMLDivElement>>;
 export { ProductCard };

package/dist/components/prd/Footer.d.ts

@@ -0,0 +1,10 @@
+import { HTMLAttributes } from 'react';
+export interface FooterProps extends HTMLAttributes<HTMLElement> {
+    brand?: 'elo-editora' | 'perabook';
+    onNewsletterSubmit?: (email: string) => void;
+}
+declare const Footer: {
+    ({ brand, onNewsletterSubmit, className, ...props }: FooterProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export { Footer };

package/dist/components/prd/MegaMenu.d.ts

@@ -0,0 +1,16 @@
+import { HTMLAttributes } from 'react';
+export interface NavItem {
+    id: string;
+    label: string;
+    href?: string;
+    children?: NavItem[];
+}
+export interface MegaMenuProps extends HTMLAttributes<HTMLElement> {
+    items: NavItem[];
+    logo?: React.ReactNode;
+    rightSlot?: React.ReactNode;
+    searchSlot?: React.ReactNode;
+    drawerFooter?: React.ReactNode;
+}
+declare const MegaMenu: import("react").ForwardRefExoticComponent<MegaMenuProps & import("react").RefAttributes<HTMLElement>>;
+export { MegaMenu };

package/dist/components/prd/TopAccessibilityBar.d.ts

@@ -2,6 +2,7 @@ import { HTMLAttributes } from 'react';
 export interface TopAccessibilityBarProps extends HTMLAttributes<HTMLDivElement> {
     onThemeChange?: (theme: 'light' | 'dark') => void;
     onFontSizeChange?: (size: number) => void;
+    showA11yLink?: boolean;
 }
 declare const TopAccessibilityBar: import("react").ForwardRefExoticComponent<TopAccessibilityBarProps & import("react").RefAttributes<HTMLDivElement>>;
 export { TopAccessibilityBar };

package/dist/components/prd/index.d.ts

@@ -2,3 +2,7 @@ export { TopAccessibilityBar } from './TopAccessibilityBar';
 export type { TopAccessibilityBarProps } from './TopAccessibilityBar';
 export { HeroCarousel } from './HeroCarousel';
 export type { HeroCarouselProps, HeroSlide } from './HeroCarousel';
+export { MegaMenu } from './MegaMenu';
+export type { MegaMenuProps, NavItem } from './MegaMenu';
+export { Footer } from './Footer';
+export type { FooterProps } from './Footer';

package/dist/index.d.ts

@@ -3,4 +3,5 @@ export * from './components/atoms';
 export * from './components/molecules';
 export * from './components/organisms';
 export * from './components/prd';
+export * from './components/layout';
 export { cn } from './components/ui/utils';