@cupcodev/ui

Design system Cupcode pronto para uso (componentes React + estilos + preset Tailwind).

Instalação

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:

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:

import "@cupcodev/ui/styles.css";

Se o app também usa Tailwind, o preset continua disponível:

// 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:

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:

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:

// 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

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.

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:

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:

import { ThemeToggle } from "@cupcodev/ui";

export function HeaderActions() {
  return <ThemeToggle />;
}

Modo controlado (opcional):

<ThemeToggle theme={theme} onThemeChange={setTheme} />

Qualidade e CI

Validações automatizadas disponíveis no projeto:

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.