@cupcodev/ui 7.0.0 → 8.0.0

package/README.md

@@ -1,239 +1,239 @@
-## @cupcodev/ui
-
-Design system Cupcode pronto para uso (componentes React + estilos + preset Tailwind).
-
-### Instalação
-
-```bash
-npm install @cupcodev/ui
-```
-
-Além do pacote, instale as peer dependencies listadas em `peerDependencies` (React 18, Tailwind 3, Radix UI, etc.). Um comando típico:
-
-```bash
-npm install react react-dom tailwindcss class-variance-authority tailwind-merge lucide-react \
-cmdk date-fns embla-carousel-react input-otp react-day-picker react-resizable-panels recharts sonner vaul \
-@radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-aspect-ratio @radix-ui/react-avatar \
-@radix-ui/react-checkbox @radix-ui/react-collapsible @radix-ui/react-context-menu @radix-ui/react-dialog \
-@radix-ui/react-dropdown-menu @radix-ui/react-hover-card @radix-ui/react-label @radix-ui/react-menubar \
-@radix-ui/react-navigation-menu @radix-ui/react-popover @radix-ui/react-progress @radix-ui/react-radio-group \
-@radix-ui/react-scroll-area @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-slider \
-@radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-toggle \
-@radix-ui/react-toggle-group @radix-ui/react-tooltip tailwindcss-animate @tailwindcss/typography
-```
-
-Compatibilidade de runtime: Node.js `>=18.18.0`.
-Compatibilidade de estilo: Tailwind CSS v3 (`tailwindcss@^3.4.x`).
-Gerenciador oficial: `npm` (lockfile único: `package-lock.json`).
-
-### Styles (`styles.css` compilado)
-
-Para carregar o visual completo dos componentes (incluindo `UserMenuCupcode`, chat, modal Telescup e classes do Dock), basta:
-
-```ts
-import "@cupcodev/ui/styles.css";
-```
-
-Se o app também usa Tailwind, o preset continua disponível:
-
-```js
-// tailwind.config.js
-module.exports = {
-  presets: [require("@cupcodev/ui/tailwind-preset.cjs")],
-  content: ["./src/**/*.{ts,tsx}"],
-};
-```
-
-Se voce quiser apenas variaveis + base minima (sem classes utilitarias/glass/dock), use:
-
-```ts
-import "@cupcodev/ui/styles/base.css";
-```
-
-Importante:
-- `styles.css` agora ja vem compilado para uso direto no app consumidor.
-- O build de `styles.css` usa `styles/index.css` como source of truth (tokens + global + dock).
-- `styles/global.css` nao deve ser usado isoladamente, porque nao inclui os tokens.
-- `styles/base.css` e o entrypoint seguro para tema/tokens quando voce nao quer carregar o pacote visual completo.
-- `JellyButton` (Blob CTA), `VideoWatchButton` e classes visuais do Dock dependem de `styles.css`.
-- Politica de cor: use `cupcode-hover`/`--cc-hover-overlay` (`#975ab6` a `30%`) para hover/interacao e reserve `cupcode-pink` para destaques fortes (ex.: badges).
-
-### Config de runtime (env no app consumidor)
-
-Para componentes que dependem de env em runtime (chat/supabase/telescup), configure uma vez no bootstrap do app:
-
-```ts
-import { setCupcodeRuntimeEnv } from "@cupcodev/ui";
-
-setCupcodeRuntimeEnv({
-  VITE_APP_VERSION: import.meta.env.VITE_APP_VERSION,
-  VITE_SUPABASE_URL: import.meta.env.VITE_SUPABASE_URL,
-  VITE_SUPABASE_ANON_KEY: import.meta.env.VITE_SUPABASE_ANON_KEY,
-  VITE_TELESCUP_BASE_URL: import.meta.env.VITE_TELESCUP_BASE_URL,
-  VITE_TELESCUP_API_BASE: import.meta.env.VITE_TELESCUP_API_BASE,
-});
-```
-
-Para manter a versão do menu do usuário sincronizada com o `package.json` do app consumidor, injete `VITE_APP_VERSION` via Vite:
-
-```ts
-// vite.config.ts
-import packageJson from "./package.json" with { type: "json" };
-
-export default defineConfig({
-  define: {
-    "import.meta.env.VITE_APP_VERSION": JSON.stringify(packageJson.version),
-  },
-});
-```
-
-`UserMenuCupcode` (e `MainNavbar`) aceitam `appVersion` para override explícito. Sem prop, o menu resolve a versão via runtime env pelas chaves exportadas em `CUPCODE_APP_VERSION_ENV_KEYS`.
-
-Observação:
-- Ao instalar/atualizar `@cupcodev/ui`, o pacote exibe esse lembrete no `postinstall`.
-- Se o projeto usa `npm install --ignore-scripts`, esse aviso não aparece; nesse caso, aplique a configuração manualmente.
-
-### Uso básico
-
-```tsx
-import { Button } from "@cupcodev/ui";
-
-export default function Example() {
-  return <Button variant="default">Oi Cupcode</Button>;
-}
-```
-
-Todos os componentes Cupcode e shadcn/ui base são reexportados de `@cupcodev/ui`.
-
-### Contrato de API (Source of Truth do DS)
-
-Para manter layout/CSS 100% padronizado nos apps consumidores:
-
-1. Sempre importe os estilos globais do pacote uma única vez no bootstrap:
-
-```ts
-import "@cupcodev/ui/styles.css";
-```
-
-2. Use os componentes canonicos do DS no import principal:
-   - `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` (versao Cupcode)
-   - `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent` (versao Cupcode)
-   - `Skeleton` e `SkeletonText` (versao Cupcode)
-
-3. Se realmente precisar do comportamento visual bruto do shadcn, use os exports `Primitive*`:
-   - `PrimitiveTabs`, `PrimitiveTabsList`, `PrimitiveTabsTrigger`, `PrimitiveTabsContent`
-   - `PrimitiveTooltip`, `PrimitiveTooltipProvider`, `PrimitiveTooltipTrigger`, `PrimitiveTooltipContent`
-   - `PrimitiveSkeleton`
-
-Assim evitamos drift visual entre apps e garantimos o DS como fonte unica de verdade.
-
-### MainNavbar sem router obrigatório
-
-`MainNavbar` não depende de `react-router-dom`. Para integração SPA, passe `pathname` e `onNavigate`.  
-O pacote não injeta logo da Cupcode por padrão. Se quiser ocupar a área de marca, passe `logo` com o visual do seu app:
-
-```tsx
-import { MainNavbar, TelescupImage } from "@cupcodev/ui";
-import { useLocation, useNavigate } from "react-router-dom";
-
-export function Header() {
-  const location = useLocation();
-  const navigate = useNavigate();
-  const appLogo = (
-    <TelescupImage
-      apiId="SEU-LOGO-ID"
-      imageWidth={120}
-      imageHeight={32}
-      alt="Meu app"
-      className="h-8 w-auto"
-    />
-  );
-
-  return (
-    <MainNavbar
-      logo={appLogo}
-      pathname={location.pathname}
-      onNavigate={(href) => navigate(href)}
-    />
-  );
-}
-```
-
-### ThemeToggle sem next-themes obrigatório
-
-`ThemeToggle` alterna a classe `dark` no `document.documentElement` quando usado de forma não-controlada:
-
-```tsx
-import { ThemeToggle } from "@cupcodev/ui";
-
-export function HeaderActions() {
-  return <ThemeToggle />;
-}
-```
-
-Modo controlado (opcional):
-
-```tsx
-<ThemeToggle theme={theme} onThemeChange={setTheme} />
-```
-
-### Qualidade e CI
-
-Validações automatizadas disponíveis no projeto:
-
-```bash
-npm run lint
-npm run typecheck
-npm run check:exports
-npm run build:lib
-npm run build:site
-npm run test:consumer
-```
-
-- `lint` roda com `--max-warnings=0` (qualquer warning quebra o gate).
-- `typecheck`: valida tipos com `tsc -b` usando as configs estritas do projeto.
-- `check:exports`: garante que modulos DS Core com exports nomeados estao representados na API publica (`src/index.ts`).
-- `build:lib`: gera o pacote publicável (`dist`) via `tsup` sem sourcemaps.
-- `build:site`: gera somente o site/docs via Vite.
-- `test:consumer`: cria um projeto externo temporário, instala o tarball de `@cupcodev/ui`, valida imports do pacote e valida `typecheck + build` (incluindo snippets CSS do Dock no bundle final).
-- `prepublishOnly` executa `check:release` (`lint + typecheck + check:exports + build:lib`) antes de qualquer publicação.
-- Pipeline CI em `.github/workflows/ci.yml` roda `check:release`, `build:site` e `test:consumer` em todo push/PR.
-
-App de consumo real versionado: `examples/vite-consumer`.
-
-### Setup do chat (Supabase + Realtime)
-
-Para configurar o chat com dados reais e notificacoes em tempo real:
-
-1. Use `.env.chat.example` como referencia para preencher seu `.env.local`.
-2. Rode no SQL Editor do Supabase:
-   - `scripts/supabase/chat/00_bootstrap_chat_public.sql`
-   - `scripts/supabase/chat/01_confirm_tables.sql`
-   - `scripts/supabase/chat/02_confirm_columns.sql`
-   - `scripts/supabase/chat/03_enable_realtime.sql`
-   - `scripts/supabase/chat/04_verify_realtime.sql`
-   - `scripts/supabase/chat/06_fix_rls_and_avatars_for_external_auth.sql` (se usar auth externa)
-   - `scripts/supabase/chat/15_enable_presence_global_realtime.sql` (presenca global com idle auto)
-   - `scripts/supabase/chat/16_verify_presence_global_realtime.sql`
-3. Reinicie o app: `npm run dev`.
-4. Valide o fluxo com `scripts/supabase/chat/05_acceptance_checks.sql`.
-
-Guia completo: `docs/chat-supabase-setup.md`.
-
-### Peers
-
-| Pacote | Versão mínima | Uso no DS |
-| --- | --- | --- |
-| `react`, `react-dom` | ^18.3.1 | base dos componentes |
-| `tailwindcss` | ^3.4.17 | util classes + preset |
-| `class-variance-authority`, `tailwind-merge` | ^0.7.1 / ^2.6.0 | variantes e merge de classes |
-| `lucide-react` | ^0.462.0 | ícones |
-| `@radix-ui/*` | conforme `package.json` | primitives dos componentes shadcn |
-| `cmdk`, `date-fns`, `embla-carousel-react`, `react-day-picker`, `input-otp`, `react-resizable-panels`, `recharts`, `sonner`, `vaul` | conforme `package.json` | componentes específicos |
-| `tailwindcss-animate`, `@tailwindcss/typography` | ^1.0.7 / ^0.5.16 | plugins usados pelo preset |
-
-Consulte `peerDependencies` para a lista completa ao instalar.
-
-### Tipos e superfícies
-
-Importe de `@cupcodev/ui` para manter tipos e estilos alinhados. Para gráficos, use também o submódulo `@cupcodev/ui/charts`.
+## @cupcodev/ui
+
+Design system Cupcode pronto para uso (componentes React + estilos + preset Tailwind).
+
+### Instalação
+
+```bash
+npm install @cupcodev/ui
+```
+
+Além do pacote, instale as peer dependencies listadas em `peerDependencies` (React 18, Tailwind 3, Radix UI, etc.). Um comando típico:
+
+```bash
+npm install react react-dom tailwindcss class-variance-authority tailwind-merge lucide-react \
+cmdk date-fns embla-carousel-react input-otp react-day-picker react-resizable-panels recharts sonner vaul \
+@radix-ui/react-accordion @radix-ui/react-alert-dialog @radix-ui/react-aspect-ratio @radix-ui/react-avatar \
+@radix-ui/react-checkbox @radix-ui/react-collapsible @radix-ui/react-context-menu @radix-ui/react-dialog \
+@radix-ui/react-dropdown-menu @radix-ui/react-hover-card @radix-ui/react-label @radix-ui/react-menubar \
+@radix-ui/react-navigation-menu @radix-ui/react-popover @radix-ui/react-progress @radix-ui/react-radio-group \
+@radix-ui/react-scroll-area @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-slider \
+@radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-toggle \
+@radix-ui/react-toggle-group @radix-ui/react-tooltip tailwindcss-animate @tailwindcss/typography
+```
+
+Compatibilidade de runtime: Node.js `>=18.18.0`.
+Compatibilidade de estilo: Tailwind CSS v3 (`tailwindcss@^3.4.x`).
+Gerenciador oficial: `npm` (lockfile único: `package-lock.json`).
+
+### Styles (`styles.css` compilado)
+
+Para carregar o visual completo dos componentes (incluindo `UserMenuCupcode`, chat, modal Telescup e classes do Dock), basta:
+
+```ts
+import "@cupcodev/ui/styles.css";
+```
+
+Se o app também usa Tailwind, o preset continua disponível:
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require("@cupcodev/ui/tailwind-preset.cjs")],
+  content: ["./src/**/*.{ts,tsx}"],
+};
+```
+
+Se voce quiser apenas variaveis + base minima (sem classes utilitarias/glass/dock), use:
+
+```ts
+import "@cupcodev/ui/styles/base.css";
+```
+
+Importante:
+- `styles.css` agora ja vem compilado para uso direto no app consumidor.
+- O build de `styles.css` usa `styles/index.css` como source of truth (tokens + global + dock).
+- `styles/global.css` nao deve ser usado isoladamente, porque nao inclui os tokens.
+- `styles/base.css` e o entrypoint seguro para tema/tokens quando voce nao quer carregar o pacote visual completo.
+- `JellyButton` (Blob CTA), `VideoWatchButton` e classes visuais do Dock dependem de `styles.css`.
+- Politica de cor: use `cupcode-hover`/`--cc-hover-overlay` (`#975ab6` a `30%`) para hover/interacao e reserve `cupcode-pink` para destaques fortes (ex.: badges).
+
+### Config de runtime (env no app consumidor)
+
+Para componentes que dependem de env em runtime (chat/supabase/telescup), configure uma vez no bootstrap do app:
+
+```ts
+import { setCupcodeRuntimeEnv } from "@cupcodev/ui";
+
+setCupcodeRuntimeEnv({
+  VITE_APP_VERSION: import.meta.env.VITE_APP_VERSION,
+  VITE_SUPABASE_URL: import.meta.env.VITE_SUPABASE_URL,
+  VITE_SUPABASE_ANON_KEY: import.meta.env.VITE_SUPABASE_ANON_KEY,
+  VITE_TELESCUP_BASE_URL: import.meta.env.VITE_TELESCUP_BASE_URL,
+  VITE_TELESCUP_API_BASE: import.meta.env.VITE_TELESCUP_API_BASE,
+});
+```
+
+Para manter a versão do menu do usuário sincronizada com o `package.json` do app consumidor, injete `VITE_APP_VERSION` via Vite:
+
+```ts
+// vite.config.ts
+import packageJson from "./package.json" with { type: "json" };
+
+export default defineConfig({
+  define: {
+    "import.meta.env.VITE_APP_VERSION": JSON.stringify(packageJson.version),
+  },
+});
+```
+
+`UserMenuCupcode` (e `MainNavbar`) aceitam `appVersion` para override explícito. Sem prop, o menu resolve a versão via runtime env pelas chaves exportadas em `CUPCODE_APP_VERSION_ENV_KEYS`.
+
+Observação:
+- Ao instalar/atualizar `@cupcodev/ui`, o pacote exibe esse lembrete no `postinstall`.
+- Se o projeto usa `npm install --ignore-scripts`, esse aviso não aparece; nesse caso, aplique a configuração manualmente.
+
+### Uso básico
+
+```tsx
+import { Button } from "@cupcodev/ui";
+
+export default function Example() {
+  return <Button variant="default">Oi Cupcode</Button>;
+}
+```
+
+Todos os componentes Cupcode e shadcn/ui base são reexportados de `@cupcodev/ui`.
+
+### Contrato de API (Source of Truth do DS)
+
+Para manter layout/CSS 100% padronizado nos apps consumidores:
+
+1. Sempre importe os estilos globais do pacote uma única vez no bootstrap:
+
+```ts
+import "@cupcodev/ui/styles.css";
+```
+
+2. Use os componentes canonicos do DS no import principal:
+   - `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` (versao Cupcode)
+   - `Tooltip`, `TooltipProvider`, `TooltipTrigger`, `TooltipContent` (versao Cupcode)
+   - `Skeleton` e `SkeletonText` (versao Cupcode)
+
+3. Se realmente precisar do comportamento visual bruto do shadcn, use os exports `Primitive*`:
+   - `PrimitiveTabs`, `PrimitiveTabsList`, `PrimitiveTabsTrigger`, `PrimitiveTabsContent`
+   - `PrimitiveTooltip`, `PrimitiveTooltipProvider`, `PrimitiveTooltipTrigger`, `PrimitiveTooltipContent`
+   - `PrimitiveSkeleton`
+
+Assim evitamos drift visual entre apps e garantimos o DS como fonte unica de verdade.
+
+### MainNavbar sem router obrigatório
+
+`MainNavbar` não depende de `react-router-dom`. Para integração SPA, passe `pathname` e `onNavigate`.  
+O pacote não injeta logo da Cupcode por padrão. Se quiser ocupar a área de marca, passe `logo` com o visual do seu app:
+
+```tsx
+import { MainNavbar, TelescupImage } from "@cupcodev/ui";
+import { useLocation, useNavigate } from "react-router-dom";
+
+export function Header() {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const appLogo = (
+    <TelescupImage
+      apiId="SEU-LOGO-ID"
+      imageWidth={120}
+      imageHeight={32}
+      alt="Meu app"
+      className="h-8 w-auto"
+    />
+  );
+
+  return (
+    <MainNavbar
+      logo={appLogo}
+      pathname={location.pathname}
+      onNavigate={(href) => navigate(href)}
+    />
+  );
+}
+```
+
+### ThemeToggle sem next-themes obrigatório
+
+`ThemeToggle` alterna a classe `dark` no `document.documentElement` quando usado de forma não-controlada:
+
+```tsx
+import { ThemeToggle } from "@cupcodev/ui";
+
+export function HeaderActions() {
+  return <ThemeToggle />;
+}
+```
+
+Modo controlado (opcional):
+
+```tsx
+<ThemeToggle theme={theme} onThemeChange={setTheme} />
+```
+
+### Qualidade e CI
+
+Validações automatizadas disponíveis no projeto:
+
+```bash
+npm run lint
+npm run typecheck
+npm run check:exports
+npm run build:lib
+npm run build:site
+npm run test:consumer
+```
+
+- `lint` roda com `--max-warnings=0` (qualquer warning quebra o gate).
+- `typecheck`: valida tipos com `tsc -b` usando as configs estritas do projeto.
+- `check:exports`: garante que modulos DS Core com exports nomeados estao representados na API publica (`src/index.ts`).
+- `build:lib`: gera o pacote publicável (`dist`) via `tsup` sem sourcemaps.
+- `build:site`: gera somente o site/docs via Vite.
+- `test:consumer`: cria um projeto externo temporário, instala o tarball de `@cupcodev/ui`, valida imports do pacote e valida `typecheck + build` (incluindo snippets CSS do Dock no bundle final).
+- `prepublishOnly` executa `check:release` (`lint + typecheck + check:exports + build:lib`) antes de qualquer publicação.
+- Pipeline CI em `.github/workflows/ci.yml` roda `check:release`, `build:site` e `test:consumer` em todo push/PR.
+
+App de consumo real versionado: `examples/vite-consumer`.
+
+### Setup do chat (Supabase + Realtime)
+
+Para configurar o chat com dados reais e notificacoes em tempo real:
+
+1. Use `.env.chat.example` como referencia para preencher seu `.env.local`.
+2. Rode no SQL Editor do Supabase:
+   - `scripts/supabase/chat/00_bootstrap_chat_public.sql`
+   - `scripts/supabase/chat/01_confirm_tables.sql`
+   - `scripts/supabase/chat/02_confirm_columns.sql`
+   - `scripts/supabase/chat/03_enable_realtime.sql`
+   - `scripts/supabase/chat/04_verify_realtime.sql`
+   - `scripts/supabase/chat/06_fix_rls_and_avatars_for_external_auth.sql` (se usar auth externa)
+   - `scripts/supabase/chat/15_enable_presence_global_realtime.sql` (presenca global com idle auto)
+   - `scripts/supabase/chat/16_verify_presence_global_realtime.sql`
+3. Reinicie o app: `npm run dev`.
+4. Valide o fluxo com `scripts/supabase/chat/05_acceptance_checks.sql`.
+
+Guia completo: `docs/chat-supabase-setup.md`.
+
+### Peers
+
+| Pacote | Versão mínima | Uso no DS |
+| --- | --- | --- |
+| `react`, `react-dom` | ^18.3.1 | base dos componentes |
+| `tailwindcss` | ^3.4.17 | util classes + preset |
+| `class-variance-authority`, `tailwind-merge` | ^0.7.1 / ^2.6.0 | variantes e merge de classes |
+| `lucide-react` | ^0.462.0 | ícones |
+| `@radix-ui/*` | conforme `package.json` | primitives dos componentes shadcn |
+| `cmdk`, `date-fns`, `embla-carousel-react`, `react-day-picker`, `input-otp`, `react-resizable-panels`, `recharts`, `sonner`, `vaul` | conforme `package.json` | componentes específicos |
+| `tailwindcss-animate`, `@tailwindcss/typography` | ^1.0.7 / ^0.5.16 | plugins usados pelo preset |
+
+Consulte `peerDependencies` para a lista completa ao instalar.
+
+### Tipos e superfícies
+
+Importe de `@cupcodev/ui` para manter tipos e estilos alinhados. Para gráficos, use também o submódulo `@cupcodev/ui/charts`.