ui-optago 1.2.4 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/llms.txt CHANGED
@@ -1,203 +1,464 @@
1
- # UI Óptago
2
-
3
- > Design system em CSS puro + JavaScript vanilla (sem build, sem dependências de framework) da Óptago. Todas as classes usam o prefixo `op-`, estados usam `is-` (`is-open`, `is-active`, `is-error`...), e a maior parte dos comportamentos interativos liga sozinha via atributos `data-op-*`, sem precisar escrever JS. API global em `window.OptagoUI`. Versão atual: `1.2.4`.
4
-
5
- Este arquivo é a referência otimizada para agentes de IA/LLMs que forem gerar HTML usando esta biblioteca. Para a documentação em prosa (humanos), veja [README.md](README.md). Para ver todos os componentes renderizados com exemplo de código, veja [index.html](index.html) (showcase).
6
-
7
- ## Instalação (escolha uma)
8
-
9
- CDN, versão fixa (recomendado em produção, sem definir versão especifica ele estará sempre na versão mais atual da biblioteca):
10
-
11
- ```html
12
- <link rel="stylesheet" href="https://unpkg.com/ui-optago@1.2.4/ui-optago.css">
13
- <script src="https://unpkg.com/ui-optago@1.2.4/ui-optago.js"></script>
14
- ```
15
-
16
- npm:
17
-
18
- ```bash
19
- npm install ui-optago
20
- ```
21
- ```html
22
- <link rel="stylesheet" href="node_modules/ui-optago/ui-optago.css">
23
- <script src="node_modules/ui-optago/ui-optago.js"></script>
24
- ```
25
-
26
- Arquivos locais: copie `ui-optago.css` e `ui-optago.js` para o projeto e sirva localmente.
27
-
28
- ## Regras que um agente NÃO pode quebrar
29
-
30
- 1. **Sempre incluir os dois arquivos juntos**: `ui-optago.css` E `ui-optago.js`. O JS não é opcional: ele aplica o tema salvo, injeta fontes/ícones e liga todos os `data-op-*`. Sem ele, os componentes ficam sem interatividade e sem tema.
31
- 2. **NUNCA usar `defer` ou `async` no `<script>` do `ui-optago.js`, nem movê-lo pro fim do `<body>`.** Ele precisa rodar antes do primeiro paint pra aplicar a classe `light`/tema no `<html>` e evitar flash de tema errado (FOUC). Carregue no `<head>`, na ordem: `<link>` do CSS primeiro, depois `<script>` do JS.
32
- 3. **Todo elemento raiz da página precisa da estrutura de app shell** (`body.op-app` > `.op-app-body` + `aside.op-sidebar`) se for usar header/sidebar fixos; ver seção "Layout" abaixo. Componentes isolados (um card, um modal, um formulário) NÃO precisam do app shell, funcionam soltos em qualquer página.
33
- 4. **A sidebar (`.op-sidebar`) fica à DIREITA da tela**, não à esquerda. É fixa, colapsa para só ícones no desktop (clique em `[data-op-sidebar-toggle]`) e vira drawer no mobile (`[data-op-sidebar-mobile]`). Por padrão ela inicia **colapsada** (só ícones); o estado escolhido pelo usuário fica salvo em `localStorage`.
34
- 5. **Não hardcode cores em `style=""` nos componentes.** Use as classes de variante (`op-btn-danger`, `op-alert-warning`...) ou, se precisar de cor customizada, sobrescreva os tokens `--op-*` (ver seção Tokens). Isso garante que o componente continue correto nos dois temas.
35
- 6. **`op-btn-primary` e `op-btn-secondary` têm cor FIXA, igual nos dois temas** (não seguem a variável `--op-primary`, que muda por tema e é usada só internamente por outros componentes como checkbox/switch/paginação). Primário = sempre verde-lima `#C0FF6B` com texto preto. Secundário = sempre cinza-chumbo `#656565` com texto branco. Não tente "corrigir" isso pra usar `var(--op-primary)`, é proposital.
36
- 7. **Tema claro/escuro é controlado só pela classe `light` no `<html>`**, aplicada automaticamente pelo JS (lê cookie/`localStorage`, senão `prefers-color-scheme`). Não escreva lógica própria de tema; use `OptagoUI.setTheme('light'|'dark')` se precisar forçar via JS.
37
- 10. **Tema compartilhado entre subdomínios**: adicione `data-op-theme-domain` no `<script>` da lib (ex.: `<script src="ui-optago.js" data-op-theme-domain=".seusite.com"></script>`) e o tema passa a ser salvo num cookie com esse `Domain`, em vez de só `localStorage`. Assim, `app1.seusite.com` e `app2.seusite.com` compartilham a mesma escolha de tema automaticamente. Sem esse atributo, o comportamento continua sendo só `localStorage` (por app, isolado). O valor precisa começar com `.` e ser um domínio de verdade que a página atual pertence (não use domínios de terceiros).
38
- 8. **Ícones**: a lib usa Phosphor Icons (`<i class="ph ph-nome-do-icone"></i>`), injetado automaticamente via CDN pelo JS. Não precisa adicionar `<link>`/`<script>` do Phosphor manualmente.
39
- 9. **Fontes**: Chakra Petch (títulos, `--op-font-display`), Inter (corpo, `--op-font-sans`), JetBrains Mono (mono/labels/botões, `--op-font-mono`), injetadas automaticamente via Google Fonts pelo JS.
40
-
41
- ## Layout obrigatório (app shell)
42
-
43
- Use isto quando a página precisar de header + sidebar fixos (painel administrativo, dashboard, showcase):
44
-
45
- ```html
46
- <body class="op-app">
47
- <div class="op-app-body">
48
- <header class="op-header">...</header>
49
- <main class="op-main">CONTEÚDO ROLÁVEL AQUI</main>
50
- <footer class="op-footer">...</footer>
51
- </div>
52
- <aside class="op-sidebar">
53
- <div class="op-sidebar-header">...<button data-op-sidebar-toggle><i class="ph ph-sidebar-simple"></i></button></div>
54
- <nav class="op-sidebar-nav">
55
- <a class="op-nav-item" href="#secao">
56
- <i class="ph ph-palette"></i>
57
- <span class="op-nav-text">Título</span>
58
- <span class="op-nav-tooltip">Título</span>
59
- </a>
60
- </nav>
61
- </aside>
62
- </body>
63
- ```
64
-
65
- Só `.op-main` rola (scroll interno). Header, footer e sidebar são fixos. `.op-nav-item.is-active` marca o item ativo (pílula preenchida com a cor de marca, igual nos dois temas).
66
-
67
- ## Catálogo de componentes (classes `op-*`)
68
-
69
- | Grupo | Classes |
70
- |---|---|
71
- | Botões | `op-btn` + `op-btn-primary` (verde-lima fixo) / `op-btn-secondary` (cinza-chumbo fixo) / `op-btn-success` / `op-btn-danger` / `op-btn-warning` / `op-btn-info` / `op-btn-cyan`; ghosts: `op-btn-ghost`, `op-btn-ghost-info/success/danger/warning/cyan`; tamanhos `op-btn-sm`/`op-btn-lg`; `op-btn-icon` (só ícone); `op-btn-group` (agrupa vários `.op-btn` colados); estado `is-loading`; `disabled` ou `is-disabled` |
72
- | Badges | `op-badge` + `op-badge-brand/info/success/warning/danger/cyan`, `op-badge-pill` (arredondado total), `op-dot` (bolinha de status, some com `op-dot-pulse` pra pulsar) |
73
- | Alertas | `op-alert` + `op-alert-info/success/warning/danger`; filhos: `op-alert-title`, `op-alert-text`, `op-alert-close` (com `data-op-dismiss`) |
74
- | Formulários | `op-field` (wrapper), `op-label` (+ `<span class="req">` pro asterisco obrigatório), `op-input`/`op-select`/`op-textarea`, `op-help` (+ `is-error`/`is-success`), `op-check` (checkbox/radio customizado), `op-switch` (toggle), `op-range` (slider), `op-input-icon` (input com ícone à esquerda), `op-input-group` + `op-input-addon` (prefixo/sufixo), `[data-op-reveal]` + `op-reveal-btn` (mostrar/ocultar senha), `op-combobox` (input com busca/filtro de opções, ver seção própria abaixo); estados `is-error`/`is-success` nos inputs; tamanhos `op-input-xs`/`op-input-sm`/`op-input-lg` em `op-input`, `op-select` e `op-textarea` (sem modificador = tamanho normal, o padrão) |
75
- | Tabelas | `op-table` (+ `op-table-hover`, `op-table-striped`) para tabela HTML simples; `OptagoUI.tabulator()` para tabela avançada (ordenação/paginação) com tema Óptago aplicado |
76
- | Cards | `op-card`, `op-card-hover` (efeito hover), `op-card-title`, `op-card-text`, `op-stat` (cartão de KPI/métrica) |
77
- | Feedback | `op-progress` + `op-progress-bar` (+ `is-info/success/warning/danger`), `op-spinner` (+ `op-spinner-sm/lg`, `op-spinner-dots`), `op-skeleton` (+ `-thumb`/`-title`/`-btn`/`-badge`/`-row`), toasts (via JS, não classe direta) |
78
- | Navegação | `op-tabs` (sublinhado) / `op-tabs-pills` (pílulas) / `op-tabs-vertical` + `op-tabs-col` (vertical, tipo settings-page); todas usam `.op-tab` + `.op-tab.is-active` (pílula preenchida com cor de marca) e `.op-tab-panel.is-active`; `op-accordion` (usa `<details>` nativo); `op-breadcrumb`; `op-pagination` + `op-page.is-active`; `op-dropdown` + `op-menu` (abre alinhado à esquerda do gatilho por padrão; use `op-menu-end` se precisar abrir alinhado à direita) |
79
- | Overlays | `op-modal` (+ `op-modal-drawer` lateral, `op-modal-centered` sem header, `op-modal-sm`/`op-modal-lg`); tooltip 100% CSS via atributo `data-op-tip="texto"` (+ variante `op-tip-bottom`) |
80
- | Tela de carregamento | `OptagoUI.showLoading('mensagem')` / `OptagoUI.hideLoading()`, ou `data-op-loading-form` no `<form>` pra acionar sozinho no submit; overlay full-screen com blur, criado e destruído automaticamente pelo JS |
81
- | Extras | `op-timeline` (marcadores octogonais; some `op-timeline-horizontal` junto pra virar linha do tempo horizontal, itens em coluna), `op-glow` (+ `-sm`/`-lg`/`-strong`/`-info`/`-cyan`, manchas desfocadas de fundo; precisa de um ancestral `position:relative`), `op-avatar` (+ `-sm`/`-lg`, `-ring`), `op-avatar-group` |
82
- | Layout/utilitários | `op-row` (flex wrap), `op-stack` (flex column), `op-grid-2/3/4` (grid responsivo), `op-mobile-only` (visível SÓ abaixo de 1024px, ex.: hambúrguer que abre o drawer) e `op-desktop-only` (o inverso: some abaixo de 1024px, ex.: badge de versão no header; mesmo corte da sidebar; ambas com `!important`), `op-text-muted`/`op-text-accent`/`op-text-mono`/`op-text-sm`/`op-text-xs`, `op-mt-1..4`/`op-mb-1..4` |
83
-
84
- ## Combobox (input com busca)
85
-
86
- Estrutura obrigatória (o JS liga sozinho via `data-op-*`, não precisa de mais nada):
87
-
88
- ```html
89
- <div class="op-combobox" data-op-combobox>
90
- <input class="op-input" data-op-combobox-input type="text" placeholder="Buscar..." autocomplete="off">
91
- <div class="op-combobox-menu" data-op-combobox-menu>
92
- <button type="button" class="op-combobox-option" data-op-combobox-option data-value="br">Brasil</button>
93
- <button type="button" class="op-combobox-option" data-op-combobox-option data-value="pt">Portugal</button>
94
- <div class="op-combobox-empty" hidden>Nenhum resultado</div>
95
- </div>
96
- </div>
97
- ```
98
-
99
- Abre no foco do input, filtra as opções pelo texto digitado (case-insensitive), navega com seta pra cima/baixo, seleciona com clique ou Enter, fecha com ESC/clique fora. Ao selecionar: o `<input>` recebe o texto da opção, e o `data-value` da opção escolhida fica disponível em `elementoComCombobox.dataset.value`. Dispara um evento `change` no input ao selecionar, pra quem quiser ouvir. Não cria `<select>`/`<option>` nativos, é só `<div>`/`<button>`; se precisar enviar o valor num `<form>` tradicional, leia `dataset.value` no submit ou espelhe num `<input type="hidden">`.
100
-
101
- ## Atributos `data-op-*` (comportamento sem escrever JS)
102
-
103
- | Atributo | Ação |
104
- |---|---|
105
- | `data-op-theme-toggle` | Alterna tema claro/escuro no elemento clicado (persiste em `localStorage`) |
106
- | `data-op-sidebar-toggle` | Colapsa/expande a sidebar (desktop) |
107
- | `data-op-sidebar-mobile` | Abre/fecha a sidebar como drawer (mobile) |
108
- | `data-op-modal-open="#id"` | Abre o modal com esse id |
109
- | `data-op-modal-close` | Fecha o modal ancestral (ESC e clique no backdrop também fecham) |
110
- | `data-op-tab="nome"` | Botão de aba; use `data-op-tab-group="grupo"` no container pai quando houver mais de um grupo de tabs na mesma página |
111
- | `data-op-tab-panel="nome"` | Painel correspondente a `data-op-tab="nome"` |
112
- | `data-op-dropdown-toggle` | Abre/fecha o `.op-dropdown` ancestral mais próximo |
113
- | `data-op-dismiss` | Remove o `.op-alert` (ou o pai direto) com animação |
114
- | `data-op-tip="texto"` | Tooltip em CSS puro no elemento (hover) |
115
- | `data-op-copy="#seletor"` | Copia o HTML do elemento alvo pro clipboard |
116
- | `data-op-code="#seletor"` | Mostra/esconde um bloco `<pre>` com o código-fonte do elemento alvo |
117
- | `data-op-loading-form` | No `<form>`: mostra a tela de carregamento sozinho ao submeter |
118
- | `data-op-loading-message="texto"` | Mensagem customizada pro `data-op-loading-form` (padrão: "Carregando...") |
119
- | `data-op-reveal` (no wrapper) + `data-op-reveal-toggle` (no botão dentro) | Mostrar/ocultar senha; o wrapper envolve o `<input type="password">` e o botão |
120
- | `data-op-toast='[{"type":"success","message":"Oi"}]'` | Dispara toast(s) a partir de flash messages vindas do servidor, sem `<script>` inline (funciona sob CSP estrito). Aceita um objeto único ou array. Campos: `type` (`success`/`error`/`warning`/`info`), `message`, `duration` (ms, opcional) |
121
- | `data-op-version` | Elemento cujo texto é substituído pela versão da lib (ex.: `v1.2.4`) no carregamento |
122
- | `data-op-combobox` (wrapper) + `data-op-combobox-input` + `data-op-combobox-menu` + `data-op-combobox-option` | Combobox com busca/filtro; ver seção "Combobox" acima pra estrutura completa |
123
-
124
- ## API JavaScript (`window.OptagoUI`)
125
-
126
- ```js
127
- OptagoUI.toast(mensagem, tipo, duracaoMs); // tipo: 'success' | 'error' | 'warning' | 'info' (padrão 'info'); duração padrão 4000ms
128
- // toast pausa o contador ao passar o mouse ou focar nele, e mostra barra de progresso
129
- OptagoUI.openModal('#idDoModal');
130
- OptagoUI.closeModal('#idDoModal');
131
- OptagoUI.setTheme('light'); // 'dark' | 'light', também persiste em localStorage
132
- OptagoUI.toggleTheme();
133
- OptagoUI.customize({ accent: '#FF6B00', radius: '6px' }); // sobrescreve tokens (--op-*) em runtime;
134
- // chave sem prefixo vira --op-<chave>, ou passe o nome completo (ex. '--op-accent')
135
- OptagoUI.toggleSidebar(); // desktop: colapsa/expande; mobile: chama toggleSidebarMobile()
136
- OptagoUI.toggleSidebarMobile();
137
- OptagoUI.closeSidebarMobile();
138
- OptagoUI.showLoading('Salvando...'); // mostra overlay de carregamento full-screen; mensagem opcional
139
- OptagoUI.hideLoading();
140
- OptagoUI.copyHTML('#seletor', botaoOpcional); // usado internamente por data-op-copy
141
- OptagoUI.toggleCode('#seletor', botao); // usado internamente por data-op-code
142
- OptagoUI.version; // string, ex. "1.2.4"
143
-
144
- // Tour guiado: carrega driver.js via CDN sob demanda, já com tema Óptago aplicado
145
- // Cada step: { element: '#seletor', popover: { title: 'Título', description: 'Texto' } }
146
- // Step sem `element` vira modal genérico centralizado.
147
- // Qualquer opção nativa do driver.js é aceita no segundo argumento (options).
148
- OptagoUI.tour([
149
- { element: '#meu-el', popover: { title: 'Passo 1', description: 'Explicação.' } },
150
- { popover: { title: 'Fim', description: 'Tour concluído.' } }
151
- ]).then(instanciaDriver => { /* ... */ });
152
-
153
- // Tabela avançada: carrega Tabulator via CDN sob demanda, já com tema Óptago aplicado
154
- OptagoUI.tabulator('#minhaTabela', {
155
- layout: 'fitColumns',
156
- pagination: true,
157
- data: [...],
158
- columns: [...]
159
- }).then(instanciaTabulator => { /* ... */ });
160
- ```
161
-
162
- ## Tokens CSS (design tokens, sobrescrevíveis)
163
-
164
- Sobrescreva no seu próprio CSS, depois de importar `ui-optago.css`:
165
-
166
- ```css
167
- :root {
168
- --op-accent: #C0FF6B; /* verde-lima, cor primária da marca */
169
- --op-cyan: #6BE0FF; /* ciano, cor secundária da marca */
170
- --op-info: #3B82F6;
171
- --op-success: #10B981;
172
- --op-warning: #F59E0B;
173
- --op-danger: #EF4444;
174
- --op-radius: 12px; /* --op-radius-sm: 8px, --op-radius-lg: 16px */
175
- /* superfícies (mudam por tema, não sobrescreva sem pensar nos dois): */
176
- /* --op-bg, --op-panel, --op-panel-2, --op-panel-3, --op-border, --op-border-2, --op-text, --op-strong, --op-muted */
177
- }
178
- ```
179
-
180
- Tema escuro é o `:root` (padrão). Tema claro redefine as mesmas variáveis dentro de `html.light { ... }`, aplicado automaticamente pelo JS.
181
-
182
- ## Selo "Desenvolvido por Óptago"
183
-
184
- Para rodapé de QUALQUER site da Óptago, mesmo sites que não usam o resto da lib. Dois arquivos autocontidos (não dependem de `ui-optago.css`/`.js`): `optago-credit-dark.html` (fundos escuros/neutros) e `optago-credit-light.html` (fundos claros).
185
-
186
- ```html
187
- <div id="optago-credit"></div>
188
- <script>
189
- fetch('https://unpkg.com/ui-optago@1.2.4/optago-credit-dark.html')
190
- .then(r => r.text())
191
- .then(html => document.getElementById('optago-credit').innerHTML = html);
192
- </script>
193
- ```
194
-
195
- Ou copie o arquivo direto pro projeto e inclua localmente (`include` no PHP, import estático etc.).
196
-
197
- ## Arquivos do pacote
198
-
199
- - `ui-optago.css`, `ui-optago.js`: a lib em si (obrigatórios, sempre os dois juntos)
200
- - `optago-credit-dark.html`, `optago-credit-light.html`: selo de rodapé, independentes da lib
201
- - `index.html`: showcase com todos os componentes renderizados e botão "Copiar" pra cada exemplo
202
- - `README.md`: documentação em prosa para humanos
203
- - `llms.txt`: este arquivo
1
+ # UI Óptago
2
+
3
+ > Biblioteca de interface do usuário leve e moderna, em CSS puro + JavaScript vanilla (sem build, sem dependências de framework), da Óptago. Todas as classes usam o prefixo `op-`, estados usam `is-` (`is-open`, `is-active`, `is-error`...), e a maior parte dos comportamentos interativos liga sozinha via atributos `data-op-*`, sem precisar escrever JS. API global em `window.OptagoUI`. Versão atual: `2.0.0`.
4
+
5
+ Este arquivo é a referência otimizada para agentes de IA/LLMs que forem gerar HTML usando esta biblioteca. Para a documentação em prosa (humanos), veja [README.md](README.md). Para ver todos os componentes renderizados com exemplo de código, veja [index.html](index.html) (resumo) e as páginas em `capitulos/`.
6
+
7
+ ## Instalação (escolha uma)
8
+
9
+ CDN, versão fixa (recomendado em produção, sem definir versão especifica ele estará sempre na versão mais atual da biblioteca):
10
+
11
+ ```html
12
+ <link rel="stylesheet" href="https://unpkg.com/ui-optago@2.0.0/ui-optago.css">
13
+ <script src="https://unpkg.com/ui-optago@2.0.0/ui-optago.js"></script>
14
+ ```
15
+
16
+ npm:
17
+
18
+ ```bash
19
+ npm install ui-optago
20
+ ```
21
+ ```html
22
+ <link rel="stylesheet" href="node_modules/ui-optago/ui-optago.css">
23
+ <script src="node_modules/ui-optago/ui-optago.js"></script>
24
+ ```
25
+
26
+ Arquivos locais: copie `ui-optago.css` e `ui-optago.js` para o projeto e sirva localmente.
27
+
28
+ ## Regras que um agente NÃO pode quebrar
29
+
30
+ 1. **Sempre incluir os dois arquivos juntos**: `ui-optago.css` E `ui-optago.js`. O JS não é opcional: ele aplica o tema salvo, injeta fontes/ícones e liga todos os `data-op-*`. Sem ele, os componentes ficam sem interatividade e sem tema.
31
+ 2. **NUNCA usar `defer` ou `async` no `<script>` do `ui-optago.js`, nem movê-lo pro fim do `<body>`.** Ele precisa rodar antes do primeiro paint pra aplicar a classe `light`/tema no `<html>` e evitar flash de tema errado (FOUC). Carregue no `<head>`, na ordem: `<link>` do CSS primeiro, depois `<script>` do JS.
32
+ 3. **Todo elemento raiz da página precisa da estrutura de app shell** (`body.op-app` > `.op-app-body` + `aside.op-sidebar`) se for usar header/sidebar fixos; ver seção "Layout" abaixo. Componentes isolados (um card, um modal, um formulário) NÃO precisam do app shell, funcionam soltos em qualquer página.
33
+ 4. **A sidebar (`.op-sidebar`) fica à DIREITA da tela**, não à esquerda. É fixa, colapsa para só ícones no desktop (clique em `[data-op-sidebar-toggle]`) e vira drawer no mobile (`[data-op-sidebar-mobile]`). Por padrão ela inicia **colapsada** (só ícones); o estado escolhido pelo usuário fica salvo em `localStorage`.
34
+ 5. **Não hardcode cores em `style=""` nos componentes.** Use as classes de variante (`op-btn-danger`, `op-alert-warning`...) ou, se precisar de cor customizada, sobrescreva os tokens `--op-*` (ver seção Tokens). Isso garante que o componente continue correto nos dois temas.
35
+ 6. **`op-btn-primary` e `op-btn-secondary` têm cor FIXA, igual nos dois temas** (não seguem a variável `--op-primary`, que muda por tema e é usada só internamente por outros componentes como checkbox/switch/paginação). Primário = sempre verde-lima `#C0FF6B` com texto preto. Secundário = sempre cinza-chumbo `#656565` com texto branco. Não tente "corrigir" isso pra usar `var(--op-primary)`, é proposital.
36
+ 7. **Tema claro/escuro é controlado só pela classe `light` no `<html>`**, aplicada automaticamente pelo JS (lê cookie/`localStorage`, senão `prefers-color-scheme`). Não escreva lógica própria de tema; use `OptagoUI.setTheme('light'|'dark')` se precisar forçar via JS.
37
+ 10. **Tema compartilhado entre subdomínios**: adicione `data-op-theme-domain` no `<script>` da lib (ex.: `<script src="ui-optago.js" data-op-theme-domain=".seusite.com"></script>`) e o tema passa a ser salvo num cookie com esse `Domain`, em vez de só `localStorage`. Assim, `app1.seusite.com` e `app2.seusite.com` compartilham a mesma escolha de tema automaticamente. Sem esse atributo, o comportamento continua sendo só `localStorage` (por app, isolado). O valor precisa começar com `.` e ser um domínio de verdade que a página atual pertence (não use domínios de terceiros).
38
+ 8. **Ícones**: a lib usa Phosphor Icons (`<i class="ph ph-nome-do-icone"></i>`), injetado automaticamente via CDN pelo JS (versão fixa, só folhas de estilo). Não precisa adicionar `<link>`/`<script>` do Phosphor manualmente. Ícone dentro de botão ou link é decorativo: o texto ou o `aria-label` do controle é que dá o nome.
39
+ 9. **Fontes**: Chakra Petch (títulos, `--op-font-display`), Inter (corpo, `--op-font-sans`), JetBrains Mono (mono/labels/botões, `--op-font-mono`), injetadas automaticamente via Google Fonts pelo JS. Para hospedar fontes e ícones por conta própria (sem conexão a terceiros), use `<script src="ui-optago.js" data-op-assets="off">`.
40
+ 11. **Acessibilidade é requisito, não opcional** (meta: WCAG 2.2 AA). Ao gerar uma página, siga a seção "Acessibilidade" abaixo: `lang`, link de pular para o conteúdo, `<label for>` em todo campo, `aria-label` em botão só com ícone, erro de formulário com `aria-invalid` + `aria-describedby`.
41
+ 12. **Ofereça um jeito de pausar as animações** em toda página com app shell: um botão `data-op-motion-toggle` ou o botão do painel Personalizar (`data-op-customizer-open`, que já tem "Pausar animações"). O fundo aurora é animado e precisa poder ser pausado.
42
+ 13. **Ação destrutiva (excluir, descartar, sobrescrever) pede confirmação**: use `OptagoUI.confirm()` ou `data-op-confirm="Mensagem"` no `<form>`/`<a>`.
43
+ 14. **HTML inserido depois do carregamento é tratado sozinho** (ARIA, nomes acessíveis, componentes desenhados pela lib). Não chame `OptagoUI.refresh()`, a não ser que a página use `data-op-observe="off"`.
44
+ 15. **Todo `op-nav-item` da sidebar tem NOME e DESCRIÇÃO, sempre os dois.** O nome é o texto em `.op-nav-text` (aparece no botão). A descrição vai em `data-op-desc="..."`: não aparece na tela e é o que a busca do menu e a paleta de comandos usam para achar a tela por outras palavras. Nunca gere um item de menu sem `data-op-desc`. Como escrever: ver a seção "Sidebar: nome, descrição e submenu".
45
+ 16. **Valor sensível (saldo, valor em dinheiro, CPF, dados bancários) leva `data-op-sensitive`**, sempre em um `<span>`, e a página precisa ter um botão `data-op-privacy-toggle` (no header).
46
+ 17. **Formulário que precisa de validação leva `data-op-validate`** e as regras nativas do HTML nos campos. Não escreva mensagens de erro nem o resumo à mão, e não use `alert()`.
47
+ 18. **Gráfico (`<canvas data-op-chart>`) leva `aria-label` com os números** (o canvas não tem texto; sem ele a lib escreve um). Mais de uma série: deixe a legenda ligada, para a cor não ser a única informação.
48
+ 19. **Dados de exemplo são sempre fictícios e obviamente falsos** (nomes genéricos, `@exemplo.com.br`, CPF `111.222.333-44`). Nunca use dados de pessoas reais.
49
+ 20. **Não escreva à mão o que a lib gera**: casas do código de verificação, controles do carrossel, botões do kanban, resumo de erros, campo de busca do menu, contador de caracteres. Escreva só a marcação do catálogo.
50
+ 21. **Texto com formatação usa o editor (`data-op-editor`), e o servidor limpa o HTML recebido** antes de salvar e de mostrar. Nunca imprima esse HTML sem limpar.
51
+ 22. **Textos da lib em outro idioma vão por `OptagoUI.locale()` ou `<script type="application/json" data-op-locale>`**, nunca editando o `ui-optago.js`. O formato das mensagens é o do CodeIgniter 4: `{0}`, `{nome}` e `{0, plural, one{...} other{...}}`.
52
+
53
+ ## Layout obrigatório (app shell)
54
+
55
+ Use isto quando a página precisar de header + sidebar fixos (painel administrativo, dashboard, showcase):
56
+
57
+ ```html
58
+ <body class="op-app">
59
+ <div class="op-app-body">
60
+ <header class="op-header">...</header>
61
+ <main class="op-main">CONTEÚDO ROLÁVEL AQUI</main>
62
+ <footer class="op-footer">...</footer>
63
+ </div>
64
+ <aside class="op-sidebar">
65
+ <div class="op-sidebar-header">...<button data-op-sidebar-toggle><i class="ph ph-sidebar-simple"></i></button></div>
66
+ <nav class="op-sidebar-nav">
67
+ <a class="op-nav-item" href="#secao" data-op-desc="palavras-chave para a busca do menu">
68
+ <i class="ph ph-palette"></i>
69
+ <span class="op-nav-text">Título</span>
70
+ <span class="op-nav-tooltip">Título</span>
71
+ </a>
72
+ </nav>
73
+ </aside>
74
+ </body>
75
+ ```
76
+
77
+ Só `.op-main` rola (scroll interno). Header, footer e sidebar são fixos. `.op-nav-item.is-active` marca o item ativo (pílula preenchida com a cor de marca, igual nos dois temas).
78
+
79
+ ## Catálogo de componentes (classes `op-*`)
80
+
81
+ | Grupo | Classes |
82
+ |---|---|
83
+ | Botões | `op-btn` + `op-btn-primary` (verde-lima fixo) / `op-btn-secondary` (cinza-chumbo fixo) / `op-btn-success` / `op-btn-danger` / `op-btn-warning` / `op-btn-info` / `op-btn-cyan`; ghosts: `op-btn-ghost`, `op-btn-ghost-info/success/danger/warning/cyan`; tamanhos `op-btn-sm`/`op-btn-lg`; `op-btn-icon` (só ícone); `op-btn-group` (agrupa vários `.op-btn` colados); estado `is-loading`; `disabled` ou `is-disabled` |
84
+ | Badges | `op-badge` + `op-badge-brand/info/success/warning/danger/cyan`, `op-badge-pill` (arredondado total), `op-dot` (bolinha de status, some com `op-dot-pulse` pra pulsar) |
85
+ | Alertas | `op-alert` + `op-alert-info/success/warning/danger`; filhos: `op-alert-title`, `op-alert-text`, `op-alert-close` (com `data-op-dismiss`) |
86
+ | Formulários | `op-field` (wrapper), `op-label` (+ `<span class="req">` pro asterisco obrigatório), `op-input`/`op-select`/`op-textarea`, `op-help` (+ `is-error`/`is-success`), `op-check` (checkbox/radio customizado), `op-switch` (toggle), `op-range` (slider), `op-input-icon` (input com ícone à esquerda), `op-input-group` + `op-input-addon` (prefixo/sufixo), `[data-op-reveal]` + `op-reveal-btn` (mostrar/ocultar senha), `op-combobox` (input com busca/filtro de opções, ver seção própria abaixo); estados `is-error`/`is-success` nos inputs; tamanhos `op-input-xs`/`op-input-sm`/`op-input-lg` em `op-input`, `op-select` e `op-textarea` (sem modificador = tamanho normal, o padrão) |
87
+ | Tabelas | `op-table` (+ `op-table-hover`, `op-table-striped`) para tabela HTML simples; `OptagoUI.tabulator()` para tabela avançada (ordenação/paginação) com tema Óptago aplicado |
88
+ | Gráficos com Chart.js | Para mais de uma série, eixos e dica ao passar o mouse: `<div class="op-chart-canvas"><canvas data-op-chart="bar" data-op-labels="Seg,Ter,Qua" data-op-series='[{"label":"Pedidos","data":[40,65,52]}]' aria-label="descrição com os números"></canvas></div>`. Tipos: `bar`, `line`, `area`, `doughnut`, `pie`, `radar`, `polar`; `data-op-stacked`, `data-op-horizontal`, `data-op-height`, `data-op-options` (JSON do Chart.js). Por código: `OptagoUI.chart('#id', { type, data, options })`. O Chart.js vem do CDN sozinho; cores e troca de tema são automáticas |
89
+ | Cards | `op-card`, `op-card-hover` (efeito hover), `op-card-title`, `op-card-text`, `op-stat` (cartão de KPI/métrica) |
90
+ | Feedback | `op-progress` + `op-progress-bar` (+ `is-info/success/warning/danger`), `op-spinner` (+ `op-spinner-sm/lg`, `op-spinner-dots`), `op-skeleton` (+ `-thumb`/`-title`/`-btn`/`-badge`/`-row`), toasts (via JS, não classe direta) |
91
+ | Navegação | `op-tabs` (sublinhado) / `op-tabs-pills` (pílulas) / `op-tabs-vertical` + `op-tabs-col` (vertical, tipo settings-page); todas usam `.op-tab` + `.op-tab.is-active` (pílula preenchida com cor de marca) e `.op-tab-panel.is-active`; `op-accordion` (usa `<details>` nativo); `op-breadcrumb`; `op-pagination` + `op-page.is-active`; `op-dropdown` + `op-menu` (abre alinhado à esquerda do gatilho por padrão; use `op-menu-end` se precisar abrir alinhado à direita) |
92
+ | Overlays | `op-modal` (+ `op-modal-drawer` lateral, que abre pela ESQUERDA; some `op-modal-drawer-end` para abrir pela direita; `op-modal-centered` sem header, `op-modal-sm`/`op-modal-lg`); tooltip 100% CSS via atributo `data-op-tip="texto"` (+ variante `op-tip-bottom`) |
93
+ | Tela de carregamento | `OptagoUI.showLoading('mensagem')` / `OptagoUI.hideLoading()`, ou `data-op-loading-form` no `<form>` pra acionar sozinho no submit; overlay full-screen com blur e o logo animado da Óptago, criado e destruído automaticamente pelo JS |
94
+ | Aparência (personalização) | Atributos no `<html>`: `data-op-main="lime|cyan|blue|violet|rose|orange|teal|yellow|graphite"` (cor principal) e `data-op-secondary="..."` (cor secundária; `data-op-accent` é o nome antigo da principal), `data-op-radius="sharp|soft|round"`, `data-op-shape="round|square"` (botões e etiquetas; padrão pílula), `data-op-font="system|serif|mono"`, `data-op-text="sm|lg|xl"`, `data-op-width="narrow|wide|full"`, `data-op-aurora="off|soft"`, `data-op-surface="solid"`. O padrão é não pôr o atributo. Cor livre: `OptagoUI.customize({ main: '#FF6B00', secondary: '#7C3AED' })`. Qualquer token: `OptagoUI.appearance({ tokens: { '--op-info': '#1E90FF' } })`. A pessoa escolhe pelo painel (`<button data-op-customizer-open>` ou `OptagoUI.customizer.open()`) ou pelo editor `<div data-op-token-editor></div>`; `OptagoUI.appearance({...})` aplica e guarda no navegador |
95
+ | Tela de abertura (splash) | Por marcação, a primeira coisa do `<body>`, com a div vazia (a lib monta o conteúdo): `<div class="op-splash" data-op-splash data-op-splash-variant="draw" data-op-splash-exit="iris" data-op-splash-min="800" data-op-splash-message="Preparando..." role="status"></div>`. `data-op-splash-variant`: `ripple` (padrão), `draw`, `orbit`, `counter`, `minimal`. `data-op-splash-exit`: `fade` (padrão), `up`, `iris`. Some sozinha ao carregar a página. Sem texto de marca por padrão: `data-op-splash-brand="Meu sistema"` escreve um nome sob o logo. Por código: `OptagoUI.splash.show('mensagem', { variant, exit })`, `OptagoUI.splash.progress(60)` (só `counter`) e `OptagoUI.splash.hide()` |
96
+ | Extras | `op-timeline` (marcadores octogonais; some `op-timeline-horizontal` junto pra virar linha do tempo horizontal, itens em coluna), `op-glow` (+ `-sm`/`-lg`/`-strong`/`-info`/`-cyan`, manchas desfocadas de fundo; precisa de um ancestral `position:relative`), `op-avatar` (+ `-sm`/`-lg`, `-ring`), `op-avatar-group` |
97
+ | Layout/utilitários | `op-row` (flex wrap), `op-stack` (flex column), `op-grid-2/3/4` (grid responsivo), `op-mobile-only` (visível SÓ abaixo de 1024px, ex.: hambúrguer que abre o drawer) e `op-desktop-only` (o inverso: some abaixo de 1024px, ex.: badge de versão no header; mesmo corte da sidebar; ambas com `!important`), `op-text-muted`/`op-text-accent`/`op-text-mono`/`op-text-sm`/`op-text-xs`, `op-mt-1..4`/`op-mb-1..4` |
98
+ | Estados | `op-empty` + `op-empty-icon` / `op-empty-title` / `op-empty-text` (estado vazio: sem dados, busca sem resultado); variante `op-empty is-error` (falha ou indisponível). Sempre diga o que aconteceu e ofereça o próximo passo |
99
+ | Acessibilidade | `op-skip-link` (link "pular para o conteúdo", primeiro elemento do `<body>`), `op-sr-only` (texto visível só para leitores de tela) |
100
+ | Valores sensíveis | `<span data-op-sensitive>R$ 1.250,00</span>` vira um borrão quando o modo privacidade está ligado (o que aparece desfocado é um texto de preenchimento, não o valor real); texto próprio no lugar do borrão com `data-op-mask="•••.•••.•••-••"`. Valor com botão próprio: `<span class="op-sensitive-group"><span data-op-sensitive>...</span><button class="op-btn op-btn-icon op-btn-sm" data-op-sensitive-toggle><i class="ph ph-eye op-icon-eye"></i><i class="ph ph-eye-slash op-icon-eye-slash" style="display:none"></i></button></span>` |
101
+ | Movimento | `op-reveal` (bloco entra subindo quando chega à tela; use em blocos no fluxo da página, não dentro de modal ou tabela), `op-stagger` (no contêiner: os filhos diretos entram em cascata), `op-text-gradient` (texto em degradê da marca, para títulos curtos), `op-btn-block` (botão na largura toda) |
102
+ | Submenu da sidebar | `<details class="op-nav-group"><summary class="op-nav-item" data-op-desc="...">` + `<i class="ph ph-caret-down op-nav-caret">` + `<div class="op-nav-sub">` com os `op-nav-item` filhos (ver seção "Sidebar") |
103
+ | Cabeçalho de página | `<header class="op-page-header"><div class="op-page-header-main"><h1 class="op-page-title">Título</h1><p class="op-page-desc">Descrição</p></div><div class="op-page-header-actions">botões</div></header>` |
104
+ | Lista de definição | `<dl class="op-dl"><div><dt>Rótulo</dt><dd>Valor</dd></div>...</dl>`; some `op-dl-inline` para rótulo à esquerda e valor à direita |
105
+ | Etapas (stepper) | `<ol class="op-steps"><li class="op-step is-done"><span class="op-step-marker" aria-hidden="true"></span><span class="op-step-label">Dados</span></li><li class="op-step is-active" aria-current="step">...</li></ol>`; vertical com `op-steps-vertical`. Assistente: envolva em `<div data-op-wizard="0">`, um `<div data-op-step-panel>` por etapa e botões `data-op-step-prev` / `data-op-step-next` (a lib cuida de `is-done`, `is-active` e do painel) |
106
+ | Chips | `<span class="op-chip">Texto</span>`; removível: `<span class="op-chip">Texto<button type="button" class="op-chip-remove" aria-label="Remover Texto"><i class="ph ph-x"></i></button></span>`; filtro selecionável: `<label class="op-chip-check"><input type="checkbox"><span>Pagos</span></label>` |
107
+ | Campo de tags | `<div class="op-tags" data-op-tags><input class="op-tags-input" id="x" type="text"><input type="hidden" name="tags"></div>` (Enter ou vírgula cria o chip; o hidden recebe os valores separados por vírgula) |
108
+ | Controle segmentado | `<div class="op-segmented" role="radiogroup" aria-label="Período"><label><input type="radio" name="p" checked><span>Dia</span></label>...</div>` |
109
+ | Cartões de opção | `<div class="op-options" role="radiogroup" aria-label="Plano"><label class="op-option"><input type="radio" name="plano"><span class="op-option-body"><span class="op-option-title">Título</span><span class="op-option-text">Apoio</span></span></label>...</div>` (aceita `type="checkbox"`) |
110
+ | Upload | `<div class="op-upload" data-op-upload><input class="op-upload-input" type="file" id="arq" multiple><label class="op-upload-drop" for="arq"><i class="ph ph-upload-simple"></i><strong>Arraste ou clique</strong></label><ul class="op-upload-list" aria-label="Arquivos escolhidos"></ul></div>`. O `<input>` vem ANTES do `<label>`. A lib só lista e remove; o envio é do formulário |
111
+ | Máscaras de campo | `<input class="op-input" data-op-format="cpf">`. Valores: `cpf`, `cnpj`, `telefone`, `cep`, `data`, `moeda`, ou um padrão com `0` para cada dígito (`00:00`). Só formata; a validação é do servidor |
112
+ | Data e período | `<input class="op-input" type="date">` (sempre o campo nativo). Período: `<div class="op-date-range" data-op-date-range role="group" aria-label="Período"><input class="op-input" type="date" aria-label="Data inicial"><span class="op-date-range-sep">até</span><input class="op-input" type="date" aria-label="Data final"></div>` |
113
+ | Código de verificação | `<div class="op-otp" data-op-otp><input id="codigo" type="text" inputmode="numeric" autocomplete="one-time-code" maxlength="6" pattern="[0-9]*"></div>` com `<label class="op-label" for="codigo">`. É UM input só dentro do `op-otp`: a lib desenha as casas (uma por dígito, a partir do `maxlength`). NÃO gere um campo por dígito nem escreva as casas à mão. Estados: `is-error` / `is-success` no `op-otp`. Evento `op:otp-complete` (`event.detail.value`) quando todas as casas são preenchidas |
114
+ | Popover | `<button class="op-btn" popovertarget="p1">Abrir</button><div class="op-popover" id="p1" popover><p class="op-popover-title">Título</p>conteúdo</div>` (API nativa; não precisa de JS) |
115
+ | Copiar | `<button class="op-btn" data-op-clipboard="texto"><i class="ph ph-copy"></i> Copiar</button>` ou `data-op-clipboard-target="#id"` |
116
+ | Paleta de comandos | `<button class="op-btn op-btn-icon" data-op-command-open data-op-tip="Buscar (Ctrl+K)"><i class="ph ph-magnifying-glass"></i></button>` no header. Lista sozinha os itens da sidebar; mais ações com `OptagoUI.commands([...])` |
117
+ | Barra de ferramentas | `<div class="op-toolbar"><div class="op-input-icon op-toolbar-grow"><i class="ph ph-magnifying-glass"></i><input class="op-input" type="search" aria-label="Filtrar pedidos" data-op-table-filter="#tabela"></div><div class="op-toolbar-end">botões</div></div>` |
118
+ | Seleção de linhas | Envolva barra e tabela em `<div data-op-table-select>`. Cabeçalho: `<th><label class="op-check"><input type="checkbox" data-op-select-all aria-label="Selecionar todos"></label></th>`. Linha: `<td><label class="op-check"><input type="checkbox" data-op-select-row aria-label="Selecionar pedido 1042"></label></td>`. Ações em lote: `<div class="op-bulk-bar" hidden><span data-op-selected-count aria-live="polite"></span><div class="op-toolbar-end">botões</div></div>`. Evento `op:selection-change` (`event.detail.count`) |
119
+ | Tabela que vira cartões | Some `op-table-stack` à `<table class="op-table">`: até 640px cada linha vira um cartão com o título da coluna ao lado do valor (a lib preenche `data-label`) |
120
+ | Validação de formulário | `<form data-op-validate>` com as regras nativas (`required`, `type="email"`, `pattern`, `min`, `max`). A lib marca `aria-invalid`, escreve a mensagem em cada campo e cria o resumo `op-error-summary` no topo. Mensagem própria: `data-op-error="Informe um e-mail válido."` no campo. NÃO escreva o resumo nem as mensagens à mão. A validação no servidor continua obrigatória |
121
+ | Barra de ações | `<div class="op-action-bar"><span class="op-action-bar-info">Campos com * são obrigatórios</span><button class="op-btn op-btn-ghost" type="reset">Limpar</button><button class="op-btn op-btn-primary" type="submit">Salvar</button></div>` como último filho do `<form>` longo (fica fixa no fim da área visível) |
122
+ | Campo numérico | `<div class="op-number" data-op-number><button type="button" class="op-number-btn" data-op-number-down aria-label="Diminuir quantidade"><i class="ph ph-minus"></i></button><input class="op-input" id="qtd" type="number" value="1" min="1" max="10"><button type="button" class="op-number-btn" data-op-number-up aria-label="Aumentar quantidade"><i class="ph ph-plus"></i></button></div>` |
123
+ | Avaliação (estrelas) | `<fieldset class="op-rating"><legend class="op-label">Como foi?</legend><label><input type="radio" name="nota" value="1" aria-label="1 estrela"></label>...até 5</fieldset>` |
124
+ | Força da senha | Depois do campo `id="senha"`: `<div class="op-strength" data-op-strength="#senha"><div class="op-strength-bar" aria-hidden="true"><span></span><span></span><span></span><span></span></div><p class="op-help" aria-live="polite"></p></div>`. É só orientação; a regra de senha é do servidor |
125
+ | Contador de caracteres | `<textarea class="op-textarea" maxlength="120" data-op-counter></textarea>` (a lib cria o “0 / 120”) |
126
+ | Notificações | `<div data-op-notify><button class="op-btn op-btn-icon op-btn-ghost op-notify-btn" type="button" popovertarget="notif"><i class="ph ph-bell"></i><span class="op-count">2</span></button><div class="op-popover op-notify" id="notif" popover><div class="op-notify-head"><strong>Notificações</strong><button class="op-btn op-btn-ghost op-btn-sm" type="button" data-op-notify-read-all>Marcar como lidas</button></div><ul class="op-notify-list"><li><button type="button" class="op-notify-item is-unread">Texto<small>há 5 minutos</small></button></li></ul></div></div>`. A lib mantém o número e o nome acessível do sino |
127
+ | Menu de conta | `<div class="op-dropdown"><button class="op-account-btn" type="button" data-op-dropdown-toggle><span class="op-avatar">AS</span> Ana Souza <i class="ph ph-caret-down"></i></button><div class="op-menu op-menu-end"><div class="op-menu-header"><strong>Ana Souza</strong><span>ana@exemplo.com.br</span></div><button class="op-menu-item">...</button></div></div>` |
128
+ | Banner da página | `<div class="op-banner op-banner-info" data-op-banner-id="manutencao"><i class="ph ph-megaphone"></i><div class="op-banner-body">Texto <a href="...">Saiba mais</a></div><button type="button" class="op-alert-close" data-op-dismiss aria-label="Fechar aviso"><i class="ph ph-x"></i></button></div>`. Variantes `-info/-success/-warning/-danger`. Com `data-op-banner-id` não reaparece depois de fechado |
129
+ | Consentimento (cookies) | `<div class="op-consent" data-op-banner-id="cookies" role="region" aria-label="Uso de cookies"><p>Texto</p><div class="op-consent-actions"><button class="op-btn op-btn-secondary" type="button" data-op-dismiss="recusado">Recusar</button><button class="op-btn op-btn-secondary" type="button" data-op-dismiss="aceito">Aceitar</button></div></div>`. Os dois botões com a MESMA classe (mesmo peso visual) e nenhuma opção pré-marcada. A resposta fica em `localStorage` (`op-banner-cookies`) e no evento `op:banner-dismiss` (`event.detail.value`); só carregue cookies não essenciais depois de “aceito” |
130
+ | Sessão expirando | `OptagoUI.sessionWarning({ seconds: 60, onExtend: fn, onExpire: fn })` (diálogo com contagem e botão “Continuar conectado”) |
131
+ | Aviso de conexão | `<body class="op-app" data-op-offline>`: a lib avisa quando a conexão cai e quando volta |
132
+ | Navegação inferior (celular) | Dentro de `body.op-app`: `<nav class="op-bottom-nav" aria-label="Navegação principal"><a class="op-bottom-nav-item is-active" href="/" aria-current="page"><i class="ph ph-house"></i>Início</a>...</nav>` com 3 a 5 destinos. Aparece até 1023px; acima disso some |
133
+ | Modo compacto | `<button class="op-btn op-btn-icon" data-op-density-toggle data-op-tip="Modo compacto"><i class="ph ph-arrows-in-line-vertical"></i></button>` |
134
+ | Kanban | `<div class="op-kanban" data-op-kanban><section class="op-kanban-col" aria-labelledby="c1"><h3 class="op-kanban-title" id="c1">A fazer <span class="op-badge" data-op-kanban-count></span></h3><ul class="op-kanban-list"><li class="op-kanban-card">Tarefa</li></ul></section>...</div>`. A lib põe os botões ← → em cada cartão (NÃO os escreva). Evento `op:kanban-move` no cartão: salve a nova coluna no servidor |
135
+ | Calendário | `<div class="op-calendar" data-op-calendar data-op-events='{"2026-11-18":"Entrega do projeto"}'></div>` (a lib desenha o mês). Data escolhida em `data-value`; evento `op:calendar-select` (`event.detail.date`). Para só escolher uma data em formulário, use `<input type="date">` |
136
+ | Galeria | `<div class="op-gallery" data-op-gallery><a class="op-gallery-item" href="grande.jpg"><img src="miniatura.jpg" alt="Descrição"></a>...</div>` (o `alt` vira a legenda do visualizador) |
137
+ | Árvore | `<ul class="op-tree" aria-label="Pastas"><li><details open><summary><i class="ph ph-folder"></i> Financeiro</summary><ul><li><a class="op-tree-item is-active" href="..." aria-current="page"><i class="ph ph-file-text"></i> Relatório</a></li></ul></details></li></ul>` |
138
+ | Bloco de código | `<div class="op-code"><pre><code>npm install ui-optago</code></pre></div>` (a lib põe o botão de copiar; escape `<` e `&` no conteúdo) |
139
+ | Tabela ordenável | `<th data-op-sort>Cliente</th>` (texto), `<th data-op-sort="number">Valor</th>`, `<th data-op-sort="date">Data</th>` (dd/mm/aaaa ou ISO). Valor exato para comparar: `<td data-sort-value="1250">R$ 1.250,00</td>`. Cabeçalho fixo: `<div class="op-table-wrap op-table-scroll" style="--op-table-height:320px"><table class="op-table op-table-sticky">`. Evento `op:sort` |
140
+ | Linha de detalhe | Na linha: `<button class="op-btn op-btn-icon op-btn-ghost op-btn-sm" type="button" data-op-row-toggle aria-label="Detalhes do pedido 1042"><i class="ph ph-caret-right"></i></button>`; logo abaixo: `<tr class="op-row-detail" hidden><td colspan="4">...</td></tr>` |
141
+ | Filtros ativos | `<div class="op-filter-bar" role="group" aria-label="Filtros aplicados"><span class="op-filter-bar-label">Filtros</span><span class="op-chip" data-value="status:pago">Status: Pago<button type="button" class="op-chip-remove" aria-label="Remover o filtro Status: Pago"><i class="ph ph-x"></i></button></span><button class="op-btn op-btn-ghost op-btn-sm" type="button" data-op-filter-clear>Limpar tudo</button></div>`. Eventos `op:filter-remove` (`event.detail.value`) e `op:filters-clear`: refaça a busca neles. O painel de filtros é um `op-modal op-modal-drawer` comum |
142
+ | Lista de itens | `<ul class="op-list"><li class="op-list-item"><span class="op-avatar">AS</span><span class="op-list-body"><span class="op-list-title">Ana Souza</span><span class="op-list-text">Administradora</span></span><span class="op-list-actions">botões</span></li></ul>`. Linha clicável: `<li><a class="op-list-item" href="...">...</a></li>` |
143
+ | Texto longo | `<article class="op-prose">` em volta de títulos, parágrafos, listas e tabelas comuns. Cortar: `op-truncate` (uma linha), `op-clamp-2`, `op-clamp-3`. Ver mais: `<div class="op-more" data-op-more><div class="op-more-content">texto</div><button type="button" class="op-btn op-btn-ghost op-btn-sm" data-op-more-toggle>Ver mais</button></div>` |
144
+ | Campos repetíveis | `<div data-op-repeater data-op-min="1" data-op-max="5"><div class="op-repeater-list"><div class="op-repeater-item">campos com índice 0 + <button type="button" class="op-btn op-btn-icon op-btn-ghost" data-op-repeater-remove aria-label="Remover contato"><i class="ph ph-trash"></i></button></div></div><template><div class="op-repeater-item">os mesmos campos com __i__ no lugar do índice: id="c-__i__-nome" name="contatos[__i__][nome]"</div></template><button type="button" class="op-btn op-btn-secondary" data-op-repeater-add><i class="ph ph-plus"></i> Adicionar contato</button></div>` |
145
+ | Faixa de valores | `<div class="op-range-dual" data-op-range-dual data-op-output="R$ {0} a R$ {1}" role="group" aria-label="Faixa de preço"><input type="range" min="0" max="1000" value="200" aria-label="Preço mínimo"><input type="range" min="0" max="1000" value="700" aria-label="Preço máximo"><output></output></div>` |
146
+ | Lista de transferência | `<div class="op-transfer" data-op-transfer><div class="op-transfer-col"><label class="op-label" for="a">Disponíveis</label><select multiple class="op-transfer-list" id="a" data-op-transfer-source>options</select></div><div class="op-transfer-actions"><button type="button" class="op-btn op-btn-icon op-btn-secondary" data-op-transfer-add aria-label="Adicionar os marcados"><i class="ph ph-caret-right"></i></button><button type="button" class="op-btn op-btn-icon op-btn-secondary" data-op-transfer-remove aria-label="Remover os marcados"><i class="ph ph-caret-left"></i></button></div><div class="op-transfer-col"><label class="op-label" for="b">Escolhidos</label><select multiple class="op-transfer-list" id="b" data-op-transfer-target></select></div><input type="hidden" name="perfis"></div>` |
147
+ | Editor de texto | `<div class="op-editor" data-op-editor="markdown"><textarea class="op-textarea" id="descricao" name="descricao"></textarea><input type="hidden" name="descricao_html" data-op-editor-html></div>` com `<label class="op-label" for="descricao">`. `data-op-editor="html"` grava HTML no textarea; os hidden `data-op-editor-html` / `data-op-editor-markdown` recebem o outro formato. O servidor PRECISA limpar o HTML recebido |
148
+ | Alterações não salvas | `<form data-op-unsaved>` + opcional `<span class="op-unsaved-note"><i class="ph ph-warning"></i> Alterações não salvas</span>`. Depois de salvar por AJAX: `OptagoUI.setDirty(form, false)` |
149
+ | Escolha de tema | `<div class="op-btn-group" role="group" aria-label="Tema"><button class="op-btn op-btn-secondary" type="button" data-op-theme="light">Claro</button><button ... data-op-theme="dark">Escuro</button><button ... data-op-theme="system">Sistema</button></div>` |
150
+ | Carrossel | `<div class="op-carousel" data-op-carousel data-op-autoplay="5000" aria-label="Novidades"><div class="op-carousel-track"><div class="op-card">slide 1</div><div class="op-card">slide 2</div></div></div>`. A lib cria os controles (NÃO os escreva). Sem `data-op-autoplay` ele não troca sozinho |
151
+ | Painéis redimensionáveis | `<div class="op-split" data-op-split="35"><div class="op-split-pane">A</div><div class="op-split-handle"></div><div class="op-split-pane">B</div></div>` |
152
+ | Menu de contexto | Área: `<ul class="op-list" data-op-context-menu="#ctx">`. Menu: `<div class="op-menu op-context-menu" id="ctx"><button class="op-menu-item" type="button">Renomear</button></div>`. Evento `op:context-select` no menu (`event.detail.item`, `event.detail.target`). SEMPRE ofereça as mesmas ações em um botão visível |
153
+ | Botão dividido | `<div class="op-dropdown op-btn-split"><button class="op-btn op-btn-primary" type="button">Salvar</button><button class="op-btn op-btn-primary" type="button" data-op-dropdown-toggle aria-label="Mais opções de salvar"><i class="ph ph-caret-down"></i></button><div class="op-menu op-menu-end">itens</div></div>` |
154
+ | Botão flutuante e voltar ao topo | Dentro de `.op-app-body`: `<button class="op-fab" type="button" aria-label="Novo pedido"><i class="ph ph-plus"></i></button>` (um por tela) e `<button class="op-fab op-back-top" type="button" data-op-back-top hidden><i class="ph ph-arrow-up"></i></button>` |
155
+ | Toast com ação | `OptagoUI.toast('Pedido excluído', 'info', { action: { label: 'Desfazer', onClick: fn } })`; operação em andamento: `OptagoUI.toast.promise(promessa, { loading, success, error })` |
156
+ | Atalhos de teclado | `OptagoUI.shortcuts([{ keys: 'Ctrl+S', label: 'Salvar', run: fn }])` + `<button class="op-btn op-btn-icon" data-op-shortcuts-open data-op-tip="Atalhos de teclado"><i class="ph ph-keyboard"></i></button>` |
157
+ | Página de resultado | `<main class="op-center-page"><div class="op-result is-success"><div class="op-result-icon" aria-hidden="true"><i class="ph ph-check"></i></div><h1 class="op-result-title">Pedido enviado</h1><p class="op-result-text">...</p><div class="op-result-actions"><a class="op-btn op-btn-primary" href="/">Ver o pedido</a></div></div></main>`. Variações `is-success`, `is-warning` (acesso negado), `is-error` (erro do servidor); sem variação para manutenção |
158
+ | Blocos de site | Hero: `<section class="op-hero"><p class="op-hero-kicker">...</p><h1 class="op-hero-title">...</h1><p class="op-hero-text">...</p><div class="op-hero-actions">botões</div></section>`. Planos: `<div class="op-pricing"><div class="op-card op-price-card is-featured"><h3 class="op-price-name">Nome</h3><p class="op-price">R$ 129 <small>por mês</small></p><ul class="op-price-features"><li><i class="ph ph-check"></i> Item</li></ul><a class="op-btn op-btn-primary op-btn-block" href="...">Escolher</a></div></div>`. Rodapé: `<footer class="op-site-footer"><div><p class="op-site-footer-title">Produto</p><ul><li><a href="...">Planos</a></li></ul></div><p class="op-site-footer-bottom">© ...</p></footer>` |
159
+ | Impressão | Automática (sem app shell, tema claro). `op-no-print` esconde no papel; `op-print-only` mostra só no papel |
160
+ | Páginas prontas | Login simples: `<main class="op-center-page"><form class="op-card op-auth-card">...</form></main>`. Login completo (igual ao login único da Óptago: marca no topo, luzes de fundo, botões Google e GitHub, divisor "ou", rodapé): copie `exemplos/login.html` (`op-auth-glows`, `op-auth-theme`, `op-auth-page`, `op-auth-brand`, `op-auth-social`, `op-auth-divider`, `op-auth-footer`). Erro: `<main class="op-center-page"><div class="op-error-page"><p class="op-error-code op-text-gradient">404</p><h1 class="op-h3">Página não encontrada</h1><p class="op-text-muted">...</p><a class="op-btn op-btn-primary" href="/">Voltar ao início</a></div></main>` |
161
+
162
+ ## Combobox (input com busca)
163
+
164
+ Estrutura obrigatória (o JS liga sozinho via `data-op-*`, não precisa de mais nada):
165
+
166
+ ```html
167
+ <div class="op-combobox" data-op-combobox>
168
+ <input class="op-input" data-op-combobox-input type="text" placeholder="Buscar..." autocomplete="off">
169
+ <div class="op-combobox-menu" data-op-combobox-menu>
170
+ <button type="button" class="op-combobox-option" data-op-combobox-option data-value="br">Brasil</button>
171
+ <button type="button" class="op-combobox-option" data-op-combobox-option data-value="pt">Portugal</button>
172
+ <div class="op-combobox-empty" hidden>Nenhum resultado</div>
173
+ </div>
174
+ </div>
175
+ ```
176
+
177
+ Seleção múltipla: some `data-op-multiple` ao wrapper e troque o input por uma área de chips. A lib cria um chip por opção escolhida, mantém o menu aberto e grava os valores (separados por vírgula) no `<input type="hidden">` e em `dataset.value`:
178
+
179
+ ```html
180
+ <div class="op-combobox" data-op-combobox data-op-multiple>
181
+ <div class="op-tags">
182
+ <input class="op-tags-input" id="resp" data-op-combobox-input type="text" placeholder="Buscar pessoa..." autocomplete="off">
183
+ </div>
184
+ <input type="hidden" name="responsaveis">
185
+ <div class="op-combobox-menu" data-op-combobox-menu>
186
+ <button type="button" class="op-combobox-option" data-op-combobox-option data-value="ana">Ana Souza</button>
187
+ <button type="button" class="op-combobox-option is-selected" data-op-combobox-option data-value="bruno">Bruno Lima</button>
188
+ </div>
189
+ </div>
190
+ ```
191
+
192
+ Seleção simples (sem `data-op-multiple`): abre no foco do input, filtra as opções pelo texto digitado (case-insensitive), navega com seta pra cima/baixo, seleciona com clique ou Enter, fecha com ESC/clique fora. Ao selecionar: o `<input>` recebe o texto da opção, e o `data-value` da opção escolhida fica disponível em `elementoComCombobox.dataset.value`. Dispara um evento `change` no input ao selecionar, pra quem quiser ouvir. Não cria `<select>`/`<option>` nativos, é só `<div>`/`<button>`; se precisar enviar o valor num `<form>` tradicional, leia `dataset.value` no submit ou espelhe num `<input type="hidden">`.
193
+
194
+ ## Atributos `data-op-*` (comportamento sem escrever JS)
195
+
196
+ | Atributo | Ação |
197
+ |---|---|
198
+ | `data-op-theme-toggle` | Alterna tema claro/escuro no elemento clicado (persiste em `localStorage`) |
199
+ | `data-op-sidebar-toggle` | Colapsa/expande a sidebar (desktop) |
200
+ | `data-op-sidebar-mobile` | Abre/fecha a sidebar como drawer (mobile) |
201
+ | `data-op-modal-open="#id"` | Abre o modal com esse id |
202
+ | `data-op-modal-close` | Fecha o modal ancestral (ESC e clique no backdrop também fecham) |
203
+ | `data-op-tab="nome"` | Botão de aba; use `data-op-tab-group="grupo"` no container pai quando houver mais de um grupo de tabs na mesma página |
204
+ | `data-op-tab-panel="nome"` | Painel correspondente a `data-op-tab="nome"` |
205
+ | `data-op-dropdown-toggle` | Abre/fecha o `.op-dropdown` ancestral mais próximo |
206
+ | `data-op-dismiss` | Remove o `.op-alert` (ou o pai direto) com animação |
207
+ | `data-op-tip="texto"` | Tooltip em CSS puro no elemento (hover) |
208
+ | `data-op-copy="#seletor"` | Copia o HTML do elemento alvo pro clipboard |
209
+ | `data-op-code="#seletor"` | Mostra/esconde um bloco `<pre>` com o código-fonte do elemento alvo |
210
+ | `data-op-loading-form` | No `<form>`: mostra a tela de carregamento sozinho ao submeter |
211
+ | `data-op-loading-message="texto"` | Mensagem customizada pro `data-op-loading-form` (padrão: "Carregando...") |
212
+ | `data-op-reveal` (no wrapper) + `data-op-reveal-toggle` (no botão dentro) | Mostrar/ocultar senha; o wrapper envolve o `<input type="password">` e o botão |
213
+ | `data-op-toast='[{"type":"success","message":"Oi"}]'` | Dispara toast(s) a partir de flash messages vindas do servidor, sem `<script>` inline (funciona sob CSP estrito). Aceita um objeto único ou array. Campos: `type` (`success`/`error`/`warning`/`info`), `message`, `duration` (ms, opcional) |
214
+ | `data-op-version` | Elemento cujo texto é substituído pela versão da lib (ex.: `v2.0.0`) no carregamento |
215
+ | `data-op-combobox` (wrapper) + `data-op-combobox-input` + `data-op-combobox-menu` + `data-op-combobox-option` | Combobox com busca/filtro; ver seção "Combobox" acima pra estrutura completa |
216
+ | `data-op-motion-toggle` | Botão que pausa/retoma as animações decorativas (fundo aurora, pulsos). Persiste em `localStorage`; a lib mantém `aria-pressed` e, se houver, alterna os ícones `.op-icon-pause` / `.op-icon-play` dentro do botão |
217
+ | `data-op-confirm="Mensagem"` | Em `<form>` ou `<a>`: abre um diálogo de confirmação antes de enviar/navegar. Opcionais: `data-op-confirm-title="Título"`, `data-op-confirm-button="Texto do botão"` |
218
+ | `data-op-privacy-toggle` | Botão que liga/desliga o modo privacidade (oculta todo `data-op-sensitive`). A lib mantém `aria-pressed` e alterna os ícones `.op-icon-eye` / `.op-icon-eye-slash` dentro do botão |
219
+ | `data-op-sensitive` | Marca um valor sensível, em um `<span>`. Opcionais: `data-op-mask="texto da máscara"`, `data-op-sensitive-label="texto para leitor de tela"` |
220
+ | `data-op-sensitive-toggle` | Botão que mostra/oculta só o valor do mesmo `.op-sensitive-group` (ou o do seletor: `data-op-sensitive-toggle="#saldo"`) |
221
+ | `data-op-desc="palavras-chave"` | No `.op-nav-item`: descrição invisível usada pela busca do menu |
222
+ | `data-op-search="off"` | No `<aside class="op-sidebar">`: desliga o campo de busca do menu |
223
+ | `data-op-format="cpf"` | Máscara de campo (`cpf`, `cnpj`, `telefone`, `cep`, `data`, `moeda` ou padrão com `0`) |
224
+ | `data-op-upload` | No `.op-upload`: lista e remove os arquivos escolhidos |
225
+ | `data-op-tags` | No `.op-tags`: campo de tags |
226
+ | `data-op-wizard="0"` + `data-op-step-panel` + `data-op-step-next` / `data-op-step-prev` | Assistente em etapas; o valor é o índice da etapa inicial |
227
+ | `data-op-date-range` | Par de datas em que a final nunca fica antes da inicial |
228
+ | `data-op-clipboard="texto"` / `data-op-clipboard-target="#id"` | Copia para a área de transferência |
229
+ | `data-op-command-open` | Abre a paleta de comandos e habilita o atalho Ctrl+K |
230
+ | `data-op-chart="bar"` + `data-op-labels` + `data-op-data` ou `data-op-series` | Gráfico do Chart.js no `<canvas>` (dentro de `op-chart-canvas`) |
231
+ | `data-op-splash` (+ `-variant`, `-exit`, `-min`, `-message`) | Tela de abertura `op-splash` que some quando a página carrega |
232
+ | `data-op-otp` | No `.op-otp`: desenha as casas do código de verificação |
233
+ | `data-op-table-select` + `data-op-select-all` + `data-op-select-row` + `data-op-selected-count` | Seleção de linhas e barra de ações em lote |
234
+ | `data-op-table-filter="#tabela"` | Campo que filtra as linhas da tabela |
235
+ | `data-op-validate` (no `<form>`) + `data-op-error="mensagem"` (no campo, opcional) | Validação com resumo de erros |
236
+ | `data-op-number` + `data-op-number-down` / `data-op-number-up` | Campo numérico com − e + |
237
+ | `data-op-multiple` | No combobox: seleção múltipla com chips |
238
+ | `data-op-strength="#senha"` | Medidor de força da senha |
239
+ | `data-op-counter` | Contador de caracteres (precisa de `maxlength`) |
240
+ | `data-op-notify` + `data-op-notify-read-all` | Central de notificações |
241
+ | `data-op-banner-id="x"` + `data-op-dismiss="valor"` | Banner/consentimento que lembra a resposta |
242
+ | `data-op-offline` | No `<body>`: aviso de queda e de volta da conexão |
243
+ | `data-op-density-toggle` | Liga/desliga o modo compacto |
244
+ | `data-op-kanban` + `data-op-kanban-count` | Quadro kanban |
245
+ | `data-op-calendar` + `data-op-events='{...}'` | Calendário do mês |
246
+ | `data-op-gallery` | Galeria com visualizador de imagem |
247
+ | `data-op-theme="light"` / `"dark"` / `"system"` | Botão que escolhe o tema direto |
248
+ | `data-op-sort` / `data-op-sort="number"` / `"date"` | No `<th>`: coluna ordenável |
249
+ | `data-op-row-toggle` | Abre a linha `.op-row-detail` seguinte |
250
+ | `data-op-unsaved` | No `<form>`: avisa antes de sair sem salvar |
251
+ | `data-op-repeater` + `data-op-repeater-add` / `-remove` | Campos repetíveis |
252
+ | `data-op-range-dual` + `data-op-output="{0} a {1}"` | Faixa com duas alças |
253
+ | `data-op-more` + `data-op-more-toggle` | Ver mais / ver menos |
254
+ | `data-op-filter-clear` | Limpa a `.op-filter-bar` |
255
+ | `data-op-carousel` + `data-op-autoplay="5000"` | Carrossel |
256
+ | `data-op-context-menu="#menu"` | Menu de contexto |
257
+ | `data-op-split="35"` | Painéis redimensionáveis |
258
+ | `data-op-transfer` | Lista de transferência |
259
+ | `data-op-back-top` | Botão de voltar ao topo |
260
+ | `data-op-shortcuts-open` | Abre a lista de atalhos |
261
+ | `data-op-editor="markdown"` / `"html"` | Editor de texto sobre um `<textarea>` |
262
+ | `<script type="application/json" data-op-locale>` | Traduções dos textos da lib |
263
+
264
+ ## API JavaScript (`window.OptagoUI`)
265
+
266
+ ```js
267
+ OptagoUI.toast(mensagem, tipo, duracaoMs); // tipo: 'success' | 'error' | 'warning' | 'info' (padrão 'info'); duração padrão 4000ms
268
+ // toast pausa o contador ao passar o mouse ou focar nele, e mostra barra de progresso
269
+ OptagoUI.openModal('#idDoModal');
270
+ OptagoUI.closeModal('#idDoModal');
271
+ OptagoUI.setTheme('light'); // 'dark' | 'light', também persiste em localStorage
272
+ OptagoUI.toggleTheme();
273
+ OptagoUI.customize({ main: '#FF6B00', radius: '6px' }); // sobrescreve tokens (--op-*) em runtime;
274
+ // chave sem prefixo vira --op-<chave>, ou passe o nome completo (ex. '--op-main'); accent e cyan seguem valendo
275
+ OptagoUI.toggleSidebar(); // desktop: colapsa/expande; mobile: chama toggleSidebarMobile()
276
+ OptagoUI.toggleSidebarMobile();
277
+ OptagoUI.closeSidebarMobile();
278
+ OptagoUI.showLoading('Salvando...'); // mostra overlay de carregamento full-screen; mensagem opcional
279
+ OptagoUI.hideLoading();
280
+ OptagoUI.splash.show('Abrindo...', { variant: 'orbit', exit: 'up' }); // tela de abertura com o logo animado; .hide() fecha
281
+ OptagoUI.splash.hide();
282
+ OptagoUI.chart('#vendas', { type: 'bar', data: { labels: [...], datasets: [{ label: 'Pedidos', data: [...] }] } }); // Chart.js com tema Óptago
283
+ OptagoUI.copyHTML('#seletor', botaoOpcional); // usado internamente por data-op-copy
284
+ OptagoUI.toggleCode('#seletor', botao); // usado internamente por data-op-code
285
+ OptagoUI.version; // string, ex. "2.0.0"
286
+ OptagoUI.confirm('Mensagem', { title: 'Excluir?', confirmText: 'Excluir', cancelText: 'Cancelar', danger: true })
287
+ // Promise<boolean>; foco começa em "Cancelar"; ESC e clique fora = false
288
+ OptagoUI.setMotion(false); // pausa animações decorativas; true retoma; OptagoUI.toggleMotion() alterna
289
+ OptagoUI.setPrivacy(true); // oculta os valores data-op-sensitive; false mostra; OptagoUI.togglePrivacy() alterna
290
+ OptagoUI.announce('3 itens encontrados'); // aviso só para leitor de tela (região aria-live)
291
+ OptagoUI.setStep('#cadastro', 2); // vai para a etapa de índice 2 de um [data-op-wizard]
292
+ OptagoUI.commands([{ label: 'Novo pedido', desc: 'criar venda', icon: 'ph ph-plus', run: function () {} }]);
293
+ // ações extras da paleta; use href em vez de run para navegar
294
+ OptagoUI.openCommandPalette(); // abre a paleta de comandos
295
+ OptagoUI.validate('#form'); // valida um form[data-op-validate]; true se não houver erro
296
+ OptagoUI.sessionWarning({ seconds: 60, onExtend: function () {}, onExpire: function () {} });
297
+ // diálogo "sua sessão vai expirar" com contagem regressiva
298
+ OptagoUI.setOffline(true); // mostra o aviso de conexão; false mostra "conexão restabelecida" e some
299
+ OptagoUI.setDensity('compact'); // modo compacto; 'default' volta ao normal
300
+ OptagoUI.setTheme('system'); // 'light' | 'dark' | 'system' (segue o sistema operacional)
301
+ OptagoUI.toast('Excluído', 'info', { duration: 8000, action: { label: 'Desfazer', onClick: function () {} } });
302
+ OptagoUI.toast.promise(promessa, { loading: 'Salvando...', success: 'Salvo', error: 'Falhou' }); // devolve a própria promessa
303
+ OptagoUI.locale({ common: { close: 'Close' } }); // traduções: objeto aninhado ou chaves com ponto
304
+ OptagoUI.t('table.selected', [3]); // texto do dicionário, com valores e plural
305
+ OptagoUI.setDirty(form, false); // form[data-op-unsaved] salvo por AJAX
306
+ OptagoUI.shortcuts([{ keys: 'Ctrl+S', label: 'Salvar', run: function () {} }]);
307
+ OptagoUI.openShortcuts();
308
+ OptagoUI.editor('#caixa', { format: 'html' }) // Promise com getHTML(), getMarkdown(), setHTML(), setMarkdown(), focus(), destroy()
309
+ OptagoUI.refresh(elementoRaizOpcional); // só é preciso com data-op-observe="off": HTML inserido depois já é tratado sozinho
310
+
311
+ // Tour guiado: carrega driver.js via CDN sob demanda, já com tema Óptago aplicado
312
+ // Cada step: { element: '#seletor', popover: { title: 'Título', description: 'Texto' } }
313
+ // Step sem `element` vira modal genérico centralizado.
314
+ // Qualquer opção nativa do driver.js é aceita no segundo argumento (options).
315
+ OptagoUI.tour([
316
+ { element: '#meu-el', popover: { title: 'Passo 1', description: 'Explicação.' } },
317
+ { popover: { title: 'Fim', description: 'Tour concluído.' } }
318
+ ]).then(instanciaDriver => { /* ... */ });
319
+
320
+ // Tabela avançada: carrega Tabulator via CDN sob demanda, já com tema Óptago aplicado
321
+ OptagoUI.tabulator('#minhaTabela', {
322
+ layout: 'fitColumns',
323
+ pagination: true,
324
+ data: [...],
325
+ columns: [...]
326
+ }).then(instanciaTabulator => { /* ... */ });
327
+ ```
328
+
329
+ ## Tokens CSS (design tokens, sobrescrevíveis)
330
+
331
+ Sobrescreva no seu próprio CSS, depois de importar `ui-optago.css`:
332
+
333
+ ```css
334
+ :root {
335
+ --op-main: #C0FF6B; /* cor principal da marca (nome antigo: --op-accent, continua valendo) */
336
+ --op-secondary: #6BE0FF; /* cor secundária da marca (nome antigo: --op-cyan, continua valendo) */
337
+ --op-info: #3B82F6;
338
+ --op-success: #10B981;
339
+ --op-warning: #F59E0B;
340
+ --op-danger: #EF4444;
341
+ --op-radius: 18px; /* --op-radius-sm: 12px, --op-radius-lg: 24px, --op-radius-pill: 999px */
342
+ /* superfícies (mudam por tema, não sobrescreva sem pensar nos dois): */
343
+ /* --op-bg, --op-panel, --op-panel-2, --op-panel-3, --op-border, --op-border-2, --op-text, --op-strong, --op-muted */
344
+ }
345
+ ```
346
+
347
+ Tema escuro é o `:root` (padrão). Tema claro redefine as mesmas variáveis dentro de `html.light { ... }`, aplicado automaticamente pelo JS.
348
+
349
+ ## Idioma (CodeIgniter 4)
350
+
351
+ Os arquivos de idioma vêm prontos em `codeigniter/Language/<idioma>/OptagoUI.php` (copie para `app/Language/`). No layout:
352
+
353
+ ```php
354
+ <script type="application/json" data-op-locale><?= json_encode(lang('OptagoUI.ui'), JSON_UNESCAPED_UNICODE | JSON_HEX_TAG) ?></script>
355
+ ```
356
+
357
+ O mesmo texto no PHP: `lang('OptagoUI.ui.table.selected', [3])`; na tela: `OptagoUI.t('table.selected', [3])`. O atributo `lang` do `<html>` precisa estar certo: ele define plural, números e datas. Sem CodeIgniter: `OptagoUI.locale(objeto)` com o conteúdo de `locales/en.json`.
358
+
359
+ ## Sidebar: nome, descrição e submenu
360
+
361
+ Cada item do menu tem duas informações, e as duas são obrigatórias:
362
+
363
+ - **Nome**: o texto dentro de `<span class="op-nav-text">`. É o que aparece no botão. Curto: 1 a 3 palavras.
364
+ - **Descrição**: o atributo `data-op-desc`. NÃO aparece na tela. É usada pela busca do menu (campo que a lib insere sozinha no topo da sidebar) e pela paleta de comandos.
365
+
366
+ ```html
367
+ <a class="op-nav-item" href="/pedidos" data-op-desc="vendas compras nota fiscal nf faturar">
368
+ <i class="ph ph-receipt"></i>
369
+ <span class="op-nav-text">Pedidos</span>
370
+ <span class="op-nav-tooltip">Pedidos</span>
371
+ </a>
372
+ ```
373
+
374
+ Como escrever a descrição:
375
+
376
+ - Ponha as palavras que alguém digitaria para achar a tela e que NÃO estão no nome: sinônimos, termos do negócio, siglas e ações que se faz ali.
377
+ - De 3 a 8 palavras, em minúsculas, separadas por espaço. Não é uma frase.
378
+ - Não repita o nome. Não use dados pessoais nem nomes de clientes.
379
+ - Exemplos: Pedidos → `vendas compras nota fiscal nf faturar`; Usuários → `pessoas equipe acessos permissões convites`; Relatórios → `exportar planilha indicadores gráficos kpi`.
380
+
381
+ Submenu (grupo recolhível, com `<details>` nativo). O título do grupo e cada item filho também levam `data-op-desc`:
382
+
383
+ ```html
384
+ <details class="op-nav-group">
385
+ <summary class="op-nav-item" data-op-desc="ajustes preferências sistema">
386
+ <i class="ph ph-gear"></i>
387
+ <span class="op-nav-text">Configurações</span>
388
+ <i class="ph ph-caret-down op-nav-caret"></i>
389
+ <span class="op-nav-tooltip">Configurações</span>
390
+ </summary>
391
+ <div class="op-nav-sub">
392
+ <a class="op-nav-item" href="/usuarios" data-op-desc="pessoas equipe acessos permissões convites">
393
+ <span class="op-nav-text">Usuários</span>
394
+ </a>
395
+ <a class="op-nav-item" href="/cobranca" data-op-desc="plano fatura boleto cartão pagamento">
396
+ <span class="op-nav-text">Cobrança</span>
397
+ </a>
398
+ </div>
399
+ </details>
400
+ ```
401
+
402
+ Não escreva o campo de busca à mão: a lib o insere. Para uma sidebar sem busca, use `<aside class="op-sidebar" data-op-search="off">`.
403
+
404
+ ## Acessibilidade (siga ao gerar qualquer página)
405
+
406
+ Meta: WCAG 2.2 nível AA. A lib já cuida de foco visível, teclado e ARIA dos próprios componentes (abas, modal, dropdown, combobox, toasts), de contraste e de nomes para os botões dela que só têm ícone. O HTML que você gerar precisa trazer:
407
+
408
+ ```html
409
+ <html lang="pt-BR">
410
+ <body class="op-app">
411
+ <a class="op-skip-link" href="#conteudo">Pular para o conteúdo</a>
412
+ <div class="op-app-body">
413
+ <header class="op-header">
414
+ ...
415
+ <button class="op-btn op-btn-icon" data-op-motion-toggle data-op-tip="Pausar ou retomar animações">
416
+ <i class="ph ph-pause op-icon-pause"></i><i class="ph ph-play op-icon-play" style="display:none"></i>
417
+ </button>
418
+ <button class="op-btn op-btn-icon" data-op-theme-toggle data-op-tip="Alternar tema">
419
+ <i class="ph ph-moon op-icon-moon"></i><i class="ph ph-sun op-icon-sun" style="display:none"></i>
420
+ </button>
421
+ </header>
422
+ <main class="op-main" id="conteudo" tabindex="-1">...</main>
423
+ </div>
424
+ </body>
425
+ ```
426
+
427
+ - Todo campo tem `<label class="op-label" for="id">`. Placeholder não substitui rótulo.
428
+ - Campo obrigatório: atributo `required` no campo; o asterisco é `<span class="req" aria-hidden="true">*</span>`.
429
+ - Erro de campo: use `data-op-validate` no `<form>` (a lib cuida do resto). Erro vindo do servidor: `aria-invalid="true"` no campo (já aplica o estilo de erro) e `aria-describedby="id-da-mensagem"`; a mensagem (`<p class="op-help is-error" id="...">`) diz o que está errado e como corrigir.
430
+ - Botão só com ícone: `data-op-tip="Texto"` (vira também o nome acessível) ou `aria-label="Texto"`.
431
+ - Imagem com informação: `alt` descritivo; imagem decorativa: `alt=""`.
432
+ - Um único `<h1>` por página e títulos em ordem (`h2`, depois `h3`), sem pular níveis. Para dar aparência de título a um texto que não é título, use `op-h1` a `op-h4` em um `<p>`.
433
+ - Não transmita informação só por cor: acompanhe com texto ou ícone (ex.: badge "Erro", não só um ponto vermelho).
434
+ - Tela sem dados ou com falha: use `op-empty` (ver catálogo), nunca uma área em branco.
435
+
436
+ ## Selo "Desenvolvido por Óptago"
437
+
438
+ Para rodapé de QUALQUER site da Óptago, mesmo sites que não usam o resto da lib. Dois arquivos autocontidos (não dependem de `ui-optago.css`/`.js`): `optago-credit-dark.html` (fundos escuros/neutros) e `optago-credit-light.html` (fundos claros).
439
+
440
+ ```html
441
+ <div id="optago-credit"></div>
442
+ <script>
443
+ fetch('https://unpkg.com/ui-optago@2.0.0/optago-credit-dark.html')
444
+ .then(r => r.text())
445
+ .then(html => document.getElementById('optago-credit').innerHTML = html);
446
+ </script>
447
+ ```
448
+
449
+ Ou copie o arquivo direto pro projeto e inclua localmente (`include` no PHP, import estático etc.).
450
+
451
+ ## Arquivos do pacote
452
+
453
+ - `ui-optago.css`, `ui-optago.js`: a lib em si (obrigatórios, sempre os dois juntos)
454
+ - `optago-credit-dark.html`, `optago-credit-light.html`: selo de rodapé, independentes da lib
455
+ - `index.html`: resumo do manual (números, capítulos e modelos de tela)
456
+ - `capitulos/`: uma página por capítulo, com todos os componentes renderizados e botão "Copiar" pra cada exemplo; `capitulos/capitulos.json` é a fonte do menu e do índice
457
+ - `README.md`: documentação em prosa para humanos
458
+ - `llms.txt`: este arquivo
459
+ - `ui-optago.d.ts`: tipos da API para TypeScript e para o editor de código
460
+ - `ui-optago.layer.css`: a mesma folha de estilo dentro de `@layer optago` (o CSS da aplicação sempre vence; não use com Tabulator, tour ou editor)
461
+ - `locales/` e `codeigniter/Language/`: textos da lib em pt-BR e en
462
+ - `tokens.json`: os tokens `--op-*` dos dois temas
463
+ - `exemplos/`: telas completas (painel, relatórios com Chart.js, lista com detalhe, tarefas em kanban, agenda, perfil, assinatura, configurações, página de site, login) para copiar
464
+ - No repositório (fora do pacote npm): `scripts/` (geração e verificação), `CHANGELOG.md` e `auditoria.html`, uma página que confere nomes acessíveis, rótulos, contraste e tamanho dos alvos de uma página do projeto. Depois de gerar uma tela, vale abri-la por ali