rootzz-layout 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduzz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+# rootzz-layout
+
+Shell de aplicação da Eduzz para React: **Topbar + Sidebar + área de conteúdo**.
+Leve (zero dependências de runtime), com tema claro/escuro, drawer mobile, e **sem conflitar com o Tailwind** (ou qualquer CSS) do projeto consumidor.
+
+> **Para agentes de IA:** a API é **composta**. Use `<RootzzLayout>` como casca e
+> `RootzzLayout.Topbar`, `RootzzLayout.Sidebar`, `RootzzLayout.Content` como filhos —
+> cada um com suas próprias props. Copie o exemplo de [Uso rápido](#uso-rápido), troque os
+> dados. Todas as props têm JSDoc — confie no autocompletar/tipos.
+
+---
+
+## Por que não quebra o seu projeto
+
+- **CSS já compilado e prefixado.** Você importa **um** arquivo (`rootzz-layout/styles.css`). Não precisa de Tailwind, PostCSS ou config no seu projeto.
+- **Classes prefixadas com `rzl-`** → não colidem com `flex`, `bg-*`, etc. do seu app.
+- **Tudo escopado em `.rootzz-layout`** (inclusive os defaults internos do Tailwind). Nada vaza para fora do shell. O reset do Tailwind (preflight) **não** é incluído.
+- **Customização por CSS variables** (`--rzl-*`) — sem precisar tocar no seu build.
+
+---
+
+## Instalação
+
+```bash
+pnpm add rootzz-layout
+# ou: npm i rootzz-layout / yarn add rootzz-layout
+```
+
+`react` e `react-dom` (>= 17) são peer dependencies. Importe o CSS **uma vez** na raiz do app:
+
+```ts
+import 'rootzz-layout/styles.css';
+```
+
+Builds suportados: **ESM** (`.mjs`), **CJS** (`.cjs`) e **tipos** (`.d.ts`). Funciona em Vite, Next.js (App e Pages Router), CRA, etc. Os componentes já vêm com a diretiva `"use client"` (Next App Router).
+
+---
+
+## Uso rápido
+
+```tsx
+import { RootzzLayout, SearchBar, IconButton } from 'rootzz-layout';
+import 'rootzz-layout/styles.css';
+
+export default function App() {
+  return (
+    <RootzzLayout>
+      <RootzzLayout.Topbar
+        logo={{ src: 'https://cdn.eduzzcdn.com/topbar/orbita-new.svg', alt: 'MyEduzz', href: '/' }}
+        apps                       // botão de apps (busca a lista oficial da Eduzz no CDN)
+        showThemeToggle            // botão de tema claro/escuro
+        search={<SearchBar placeholder="Buscar…" shortcut="⌘K" />}
+        actions={<IconButton aria-label="Notificações" badge={8}>{/* ícone */}</IconButton>}
+        user={{
+          name: 'Designers da Eduzz',
+          initials: 'Dd',
+          menu: [
+            { label: 'Meu perfil', onClick: () => {} },
+            { type: 'divider' },
+            { label: 'Sair', danger: true, onClick: () => {} },
+          ],
+        }}
+      />
+
+      <RootzzLayout.Sidebar
+        activeKey="resumo"
+        menu={[
+          { key: 'resumo', label: 'Resumo', href: '/' },
+          { key: 'compras', label: 'Minhas Compras', href: '/compras' },
+          {
+            type: 'group',
+            key: 'vendas',
+            label: 'Vendas',
+            defaultCollapsed: true,
+            items: [{ key: 'pedidos', label: 'Pedidos', href: '/pedidos' }],
+          },
+        ]}
+      />
+
+      <RootzzLayout.Content>
+        <h1>Novo produto</h1>
+      </RootzzLayout.Content>
+    </RootzzLayout>
+  );
+}
+```
+
+A ordem dos filhos não importa — a Topbar fica sempre no topo e a Sidebar à esquerda do conteúdo.
+Cada subcomponente também é exportado individualmente (`Topbar`, `Sidebar`, `Content`).
+
+---
+
+## API
+
+### `<RootzzLayout>` — casca (configs de nível de shell)
+
+| Prop | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Os subcomponentes: `.Topbar`, `.Sidebar`, `.Content`. |
+| `theme` | `'light' \| 'dark'` | — | Tema **controlado** (você gerencia via `onThemeChange`). |
+| `defaultTheme` | `'light' \| 'dark'` | `'light'` | Tema inicial quando **não-controlado**. |
+| `onThemeChange` | `(theme) => void` | — | Disparado quando o tema muda. |
+| `linkComponent` | `ElementType` | `'a'` | Componente de link (topbar + sidebar). Passe o `Link` do seu router para SPA. |
+| `className` / `style` / `id` | — | — | Aplicados ao elemento raiz `.rootzz-layout`. Use `style` para sobrescrever tokens. |
+
+### `<RootzzLayout.Topbar>`
+
+| Prop | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `logo` | `LogoConfig \| ReactNode` | — | `{src, alt?, href?, onClick?, height?}` ou um nó React. |
+| `apps` | `boolean \| string \| AppItem[] \| {url?, items?}` | — | `true` busca a lista oficial no CDN; array = lista estática; string/`{url}` busca de uma URL; `false`/omitido esconde. |
+| `search` | `ReactNode` | — | Barra de busca opcional (centro). Use [`<SearchBar>`](#searchbar) ou um nó próprio. |
+| `actions` | `ReactNode` | — | Ícones/ações custom à direita. Use [`<IconButton>`](#iconbutton). |
+| `user` | `UserConfig` | — | `{name, email?, avatarUrl?, initials?, menu?, onClick?}`. |
+| `showThemeToggle` | `boolean` | `false` | Exibe o botão de tema claro/escuro. |
+| `showMenuButton` | `boolean` | `true` | Exibe o hambúrguer no mobile (desligue se não houver Sidebar). |
+| `appsLabel` / `menuButtonLabel` | `string` | — | Rótulos acessíveis. |
+
+### `<RootzzLayout.Sidebar>`
+
+| Prop | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `menu` | `MenuItem[]` | — | Itens (links, grupos colapsáveis, divisores). |
+| `activeKey` | `string` | — | `key` do item ativo. |
+| `header` / `footer` | `ReactNode` | — | Conteúdo fixo no topo / rodapé. |
+| `mobileTitle` | `ReactNode` | — | Título exibido no topo do drawer mobile. |
+| `children` | `ReactNode` | — | Conteúdo custom (substitui `menu`). |
+| `ariaLabel` / `className` | — | — | Acessibilidade / classe extra. |
+
+### `<RootzzLayout.Content>`
+
+| Prop | Tipo | Padrão | Descrição |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Conteúdo da página. |
+| `maxWidth` | `number \| string \| false` | token | Largura máx. `false` = 100%. Omitido usa `--rzl-content-max-width`. |
+| `noPadding` | `boolean` | `false` | Remove o padding padrão. |
+| `className` | `string` | — | Classe extra no wrapper interno. |
+
+### Tipos do menu
+
+```ts
+// Item simples (link ou botão)
+{ key: string; label: ReactNode; icon?: ReactNode; href?: string; target?: string;
+  onClick?: (e) => void; active?: boolean; badge?: ReactNode; disabled?: boolean }
+
+// Grupo colapsável
+{ type: 'group'; key: string; label: ReactNode; icon?: ReactNode; items: MenuLink[];
+  defaultCollapsed?: boolean; collapsible?: boolean }
+
+// Divisor
+{ type: 'divider'; key?: string }
+```
+
+O item ativo é resolvido por `Sidebar.activeKey === item.key` **ou** `item.active === true`.
+
+---
+
+## Customização (tema)
+
+Sobrescreva as **CSS variables** `--rzl-*` no seu CSS:
+
+```css
+.rootzz-layout {
+  --rzl-primary: #6d2bcf;
+  --rzl-sidebar-width: 280px;
+  --rzl-radius: 12px;
+  --rzl-duration: 160ms;
+  --rzl-font: 'Inter', sans-serif;
+}
+```
+
+…ou pontualmente via `style`:
+
+```tsx
+<RootzzLayout style={{ ['--rzl-primary' as string]: '#10b981' }}>…</RootzzLayout>
+```
+
+### Tokens disponíveis
+
+| Token | Padrão (claro) | Uso |
+| --- | --- | --- |
+| `--rzl-primary` / `--rzl-primary-hover` / `--rzl-primary-contrast` | `#2b4acf` / `#2540b5` / `#fff` | Cor de marca |
+| `--rzl-active-bg` / `--rzl-active-fg` | `#eef1fc` / `#2b4acf` | Item ativo da sidebar |
+| `--rzl-bg` / `--rzl-surface` | `#fff` / `#fff` | Conteúdo / topbar e sidebar |
+| `--rzl-fg` / `--rzl-fg-muted` / `--rzl-fg-subtle` | `#0f1324` / 65% / 50% | Textos |
+| `--rzl-border` / `--rzl-hover-bg` | `#e5e7eb` / 4.5% | Linhas / hover |
+| `--rzl-danger` / `--rzl-danger-bg` | `#e11d48` / 8% | Ações destrutivas |
+| `--rzl-badge-bg` / `--rzl-badge-fg` | `#e11d48` / `#fff` | Badge (ex.: sino) |
+| `--rzl-overlay` | `rgba(15,19,36,.45)` | Overlay mobile |
+| `--rzl-topbar-height` / `--rzl-sidebar-width` / `--rzl-content-max-width` | `60px` / `260px` / `1200px` | Dimensões |
+| `--rzl-radius` / `--rzl-radius-lg` | `8px` / `12px` | Arredondamento |
+| `--rzl-duration` / `--rzl-ease` | `200ms` / `cubic-bezier(.4,0,.2,1)` | Movimento |
+| `--rzl-font` | Google Sans + fallback | Fonte |
+
+O tema **escuro** redefine esses tokens em `.rootzz-layout[data-theme="dark"]`.
+Animações respeitam `prefers-reduced-motion`.
+
+---
+
+## Tema claro/escuro
+
+O estado do tema fica no `<RootzzLayout>`; o botão de alternância (`showThemeToggle`) fica na Topbar.
+
+```tsx
+// Não-controlado (a lib gerencia)
+<RootzzLayout defaultTheme="light">
+  <RootzzLayout.Topbar showThemeToggle … />
+  …
+</RootzzLayout>
+
+// Controlado (você gerencia o estado)
+const [theme, setTheme] = useState<'light' | 'dark'>('light');
+<RootzzLayout theme={theme} onThemeChange={setTheme}>
+  <RootzzLayout.Topbar showThemeToggle … />
+  …
+</RootzzLayout>
+```
+
+---
+
+## Integração com router (SPA)
+
+Por padrão os links são `<a>`. Para navegação SPA, passe o `Link` do seu router no `<RootzzLayout>`:
+
+```tsx
+// Next.js
+import Link from 'next/link';
+<RootzzLayout linkComponent={Link}>…</RootzzLayout>
+
+// React Router v6
+import { Link } from 'react-router-dom';
+const RouterLink = ({ href, ...p }) => <Link to={href} {...p} />;
+<RootzzLayout linkComponent={RouterLink}>…</RootzzLayout>
+```
+
+---
+
+## Menu de aplicativos
+
+```tsx
+<RootzzLayout.Topbar apps />                              // lista oficial da Eduzz (CDN)
+<RootzzLayout.Topbar apps={[{ label: 'App', icon: '/i.svg', url: 'https://…' }]} />  // estática
+<RootzzLayout.Topbar apps="https://meu-cdn/apps.json" />  // URL custom
+<RootzzLayout.Topbar apps={false} />                      // sem botão de apps
+```
+
+Formato de `AppItem`: `{ application?, label, icon, description?, url }`.
+
+---
+
+## `<SearchBar>` e `<IconButton>`
+
+Helpers para a Topbar (também exportados):
+
+```tsx
+<RootzzLayout.Topbar
+  search={<SearchBar placeholder="Buscar…" shortcut="⌘K" value={q} onChange={e => setQ(e.target.value)} />}
+  actions={<IconButton aria-label="Notificações" badge={8}>{<MeuIconeSino />}</IconButton>}
+/>
+```
+
+Outros exports: `LayoutProvider`, hooks `useLayout` e `useApps`, util `cx`, e todos os tipos.
+
+---
+
+## Mobile
+
+Abaixo de `768px`: a sidebar vira **drawer** com botão hambúrguer na topbar, **overlay** com fade, scroll travado e fechamento por clique no overlay, `Esc` ou ao navegar. Tudo automático.
+
+---
+
+## Desenvolvimento
+
+Requer **Node 18+** e **pnpm**.
+
+```bash
+pnpm install
+pnpm run example     # playground em http://localhost:5183 — watch: TS e CSS recarregam ao vivo
+pnpm run build       # typecheck + build (ESM/CJS/d.ts/css) + testes Playwright
+pnpm run test        # testes e2e (Playwright)
+```
+
+Os testes rodam automaticamente no `build` e no `prepublishOnly` — a publicação trava se algo quebrar.
+
+## Licença
+
+MIT © Eduzz