@aiqfome-org/geraldo-ui

v0.3.0

Published

21 days ago

Geraldo UI — Web Components (Lit) + design tokens for aiqfome; optional @aiqfome-org/geraldo-ui/auth (Magalu ID + Geraldo OAuth/postMessage helpers, browser-only)

0High
0Medium
0Low

picoloto-aiqfome

bgouveia-aiq

aiqfome geraldo design-system web-components lit magalu oauth marketplace lojista

Geraldo UI (`@aiqfome-org/geraldo-ui`)

SDK de Web Components (Lit + TypeScript) com tokens CSS do guia Geraldo, para apps aiqfome (incluindo Loja de APPs no portal do lojista). O pacote é ESM, publicado no npm e consumível em qualquer stack web (React, Vue, Svelte, HTML estático).

| Recurso | Descrição | | -------- | ----------- | | Design system | Tags geraldo-* (botões, tipografia, cartões, formulário, etc.) | | Auth (opcional) | Subpath @aiqfome-org/geraldo-ui/auth — Magalu ID + Geraldo (postMessage, popup OAuth code) | | Repositório | github.com/aiqfome/aiqfome-ui-sdk |

Prévia: smoke test com o pacote via npm — botões, card, formulário, rádios e badges

Índice

Requisitos

Node 18+
lit como dependência da aplicação (peer dependency deste pacote)

Instalação e entrypoints

npm install @aiqfome-org/geraldo-ui lit

O package.json do pacote expõe três superfícies principais:

| Import | Conteúdo | | ------ | -------- | | @aiqfome-org/geraldo-ui | Bundle dos Web Components + defineGeraldoUI | | @aiqfome-org/geraldo-ui/tokens.css | Variáveis CSS (cores, tipografia, espaçamentos) | | @aiqfome-org/geraldo-ui/auth | Helpers apenas browser para OAuth Magalu + postMessage no Geraldo (sem lit) |

Tipos TypeScript: dist/index.d.ts e dist/auth/index.d.ts (resolvidos automaticamente pelos exports do npm).

Autenticação Magalu e Geraldo

Import: @aiqfome-org/geraldo-ui/auth.

O que o módulo faz (e o que não faz)

| Faz | Não faz | | --- | ------- | | Monta a URL de autorização Magalu ID (response_type=code, escopos, redirect_uri do Geraldo quando aplicável) | Troca do code por access token (usa o teu servidor + client_secret) | | Abre o popup de login (window.open) | Validação de sessão ou refresh token | | Escuta postMessage com authCode e magaluAuthDone com lista de origens permitidas | Pedidos HTTP à API aiqfome |

APIs de baixo nível

Úteis quando precisas de controlo fino (por exemplo só montar URL, ou subscrever mensagens sem abrir popup de imediato):

buildGeraldoOAuthRedirectUri, buildMagaluAuthorizeUrl
openMagaluLoginWindow
parseAllowedOrigins, subscribeMagaluAuthMessages, isTrustedOrigin
Constantes: DEFAULT_GERALDO_BASE_URL, GERALDO_OAUTH_CALLBACK_PATH, MAGALU_ID_LOGIN_BASE

Exemplo mínimo (listener + URL + popup):

import {
  buildGeraldoOAuthRedirectUri,
  buildMagaluAuthorizeUrl,
  openMagaluLoginWindow,
  parseAllowedOrigins,
  subscribeMagaluAuthMessages,
} from '@aiqfome-org/geraldo-ui/auth';

const unsubscribe = subscribeMagaluAuthMessages(
  (msg) => {
    if (msg.kind === 'authCode') {
      // POST msg.code + redirectUri para o teu servidor (mesmo redirect_uri usado no authorize)
    }
  },
  { allowedOrigins: parseAllowedOrigins('https://geraldo-restaurantes.aiqfome.com,http://localhost:5175') }
);

const url = buildMagaluAuthorizeUrl({
  clientId: '…',
  redirectUri: buildGeraldoOAuthRedirectUri(),
  scopes: ['aqf:store:read'],
});
openMagaluLoginWindow(url);
unsubscribe();

Preset recomendado: `createGeraldoMagaluAuth`

Orquestra subscrição + URL + popup numa única API. Ideal para a maioria das integrações no iframe do Geraldo.

Opções (CreateGeraldoMagaluAuthOptions):

| Campo | Obrigatório | Descrição | | ----- | ----------- | --------- | | clientId | sim | string ou () => string (getter para estado reativo; lido em cada openLogin) | | scopes | sim | Lista de escopos Magalu / AIQFOME (ex.: aqf:store:read) | | allowedOrigins | sim | String CSV ou array — mesma regra que parseAllowedOrigins (ex.: Geraldo produção + http://localhost:PORTA) | | onMessage | sim | Callback com MagaluAuthMessage (authCode | magaluAuthDone) | | geraldoBaseUrl | não | Base do Geraldo para o redirect_uri (por omissão: produção .com) | | state | não | OAuth state opcional | | chooseTenants | não | Repasse para a URL Magalu (omissão alinhada ao fluxo lojista multi-tenant) | | openWindowOptions | não | { windowName?, features? } para window.open |

Controller devolvido:

| Método / campo | Descrição | | -------------- | --------- | | redirectUri | Igual ao usado no authorize — envia ao backend na troca do code | | openLogin() | Resultado discriminado (ver tabela abaixo) | | dispose() | Remove o listener de postMessage (chamar ao desmontar a app / rota) |

Resultado de openLogin() (GeraldoMagaluAuthOpenLoginResult):

| Forma | Significado | | ----- | ----------- | | { ok: true, popup } | Popup aberto (Window) | | { ok: false, reason: 'missing_client_id' } | clientId vazio após trim | | { ok: false, reason: 'popup_blocked' } | Browser bloqueou window.open |

import { createGeraldoMagaluAuth, parseAllowedOrigins } from '@aiqfome-org/geraldo-ui/auth';

const auth = createGeraldoMagaluAuth({
  clientId: '…',
  scopes: ['aqf:store:read'],
  allowedOrigins: parseAllowedOrigins(
    'https://geraldo-restaurantes.aiqfome.com,http://localhost:5175'
  ),
  onMessage(msg) {
    if (msg.kind === 'authCode') {
      // POST msg.code + auth.redirectUri ao teu servidor
    }
  },
});

const result = auth.openLogin();
if (result.ok) {
  // result.popup — janela do Magalu ID
}
auth.dispose();

Origens e `postMessage`

Inclui nas origens permitidas o host do Geraldo em produção (https://geraldo-restaurantes.aiqfome.com) e, em desenvolvimento, a origem do teu app (ex.: http://localhost:5180). Mensagens de outras origens são ignoradas.

Uso rápido (design system)

Importa os tokens (CSS variables) uma vez na raiz do app (antes de qualquer componente).
Importa o bundle JS para registrar os custom elements.

Vite / bundlers

import '@aiqfome-org/geraldo-ui/tokens.css';
import '@aiqfome-org/geraldo-ui';

Fonte Ubuntu

Inclui no HTML (recomendado):

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Ubuntu:ital,wght@0,400;0,500;0,700&display=swap"
  rel="stylesheet"
/>

HTML declarativo

<geraldo-button variant="filled" color="primary">Salvar</geraldo-button>
<geraldo-text variant="h3-section" weight="medium">Seção</geraldo-text>

React (exemplo)

import '@aiqfome-org/geraldo-ui/tokens.css';
import '@aiqfome-org/geraldo-ui';

export function Example() {
  return <geraldo-button variant="outline">OK</geraldo-button>;
}

Declara os tipos JSX se necessário (ou estende IntrinsicElements).

Registro dos custom elements

Importar @aiqfome-org/geraldo-ui carrega os módulos dos componentes; o decorator @customElement do Lit regista cada tag. Para registo explícito e idempotente (útil com code-splitting):

import { defineGeraldoUI } from '@aiqfome-org/geraldo-ui';
defineGeraldoUI();

Ícones

O guia referencia Material Symbols e MDI. Este pacote não inclui ícones: usa SVG no slot icon de geraldo-button / geraldo-badge, ou bibliotecas como @mdi/js na tua app.

Tema escuro

Define no ancestral (ex.: <html data-geraldo-theme="dark">) ou usa a classe .geraldo-theme-dark no container. Tokens de superfície e seleção vêm de geraldo-tokens.css.

Componentes exportados

| Tag | Descrição | | ---------------------- | ---------------------------------- | | geraldo-button | CTA: variant, color, size, loading | | geraldo-text | Tipografia: variant, weight, as | | geraldo-badge | tone (primary, developer, …) | | geraldo-card | radius, elevation; slots header, default, footer | | geraldo-text-field | label, description, error, eventos geraldo-input / geraldo-change | | geraldo-checkbox | checked, disabled; geraldo-change | | geraldo-radio-group | value, name, legend | | geraldo-radio | value, checked, name | | geraldo-switch | checked, disabled; geraldo-change |

Exemplos no repositório

Na raiz do clone do aiqfome-ui-sdk:

| Comando | Pasta | O que demonstra | | ------- | ----- | ----------------- | | npm run example:pedidos | examples/pedidos-app | Todos os componentes do DS; alias Vite → src/ | | npm run example:lojista-pedidos | examples/lojista-pedidos-app | API V2 (proxy), Geraldo UI, createGeraldoMagaluAuth; dependência file:../.. + alias para src/ | | npm run example:magalu-auth | examples/magalu-auth-minimal | Só auth + postMessage (sem backend) |

Variáveis de ambiente (exemplos auth / API):

| Variável | Onde | Uso | | -------- | ----- | --- | | VITE_MAGALU_CLIENT_ID | magalu-auth-minimal, lojista-pedidos-app | Client ID do app no portal (OAuth) | | VITE_POSTMESSAGE_ORIGINS | idem | Lista CSV de origens confiáveis para postMessage | | VITE_AIQFOME_ACCESS_TOKEN | lojista-pedidos-app | Bearer da API V2 (demo manual) |

Copia env.sample para .env em cada pasta de exemplo.

Desenvolvimento e Storybook

git clone https://github.com/aiqfome/aiqfome-ui-sdk.git
cd aiqfome-ui-sdk
npm install
npm run build
npm test
npm run storybook

O repositório segue Gitflow: integração em develop, releases estáveis em main. Ramos feature/*, release/*, hotfix/* — ver CONTRIBUTING.md.

Issues e PRs: github.com/aiqfome/aiqfome-ui-sdk.

Publicação no npm (mantenedores)

Pré-requisitos

Organização npm — membro com publish em @aiqfome-org.
Autenticação — npm login localmente, ou GitHub Actions com secret NPM_TOKEN (token npm tipo Automation, permissão de publish no scope).

Checklist antes de publicar

git pull na branch de release (normalmente main após merge).
npm ci (ou npm install) e npm run build — confirmar dist/index.js, dist/index.d.ts, dist/geraldo-tokens.css, dist/auth/index.js, dist/auth/index.d.ts.
npm test — suite Vitest.
Opcional: npm pack --dry-run — rever ficheiros incluídos (files em package.json: dist, docs, LICENSE).
package.json version alinhada à release (ex.: npm version patch|minor|major gera commit/tag local; ou editar versão em branch release/* conforme Gitflow).
Tag Git vX.Y.Z em main (ou fluxo da equipa) igual à versão do npm.
GitHub Release “published” — dispara o workflow .github/workflows/publish.yml, que executa npm ci e npm publish (o script prepublishOnly corre npm run build outra vez).

Publicação manual

npm publish

O pacote tem publishConfig.access: "public" no package.json; o scope @aiqfome-org fica público após a primeira publicação correta da org.

Depois do publish

Verifica a página do pacote: npmjs.com/package/@aiqfome-org/geraldo-ui.
Atualiza o Release no GitHub com notas (breaking changes, novas APIs, exemplos).

Histórico de versões (resumo)

| Versão | Destaques | | ------ | ---------- | | 0.3.0 | Subpath @aiqfome-org/geraldo-ui/auth: preset createGeraldoMagaluAuth (redirectUri, openLogin() com missing_client_id / popup_blocked, dispose()); clientId como string ou getter; exemplos e README atualizados. | | 0.2.x e anteriores | Design system + helpers auth de baixo nível; ver tags Git e changelog de commits para detalhe. |

Licença

MIT — ver LICENSE.