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/README.md CHANGED
@@ -1,197 +1,531 @@
1
- # UI Óptago
2
-
3
- [![npm](https://img.shields.io/npm/v/ui-optago.svg)](https://www.npmjs.com/package/ui-optago)
4
- [![license](https://img.shields.io/npm/l/ui-optago.svg)](./LICENSE)
5
-
6
- Design System da **[Óptago](https://optago.com.br)**: componentes UI em **CSS puro** + **JS vanilla**, sem build obrigatório. Tema escuro por padrão, tema claro automático, verde-lima `#C0FF6B` e ciano `#6BE0FF` como cores de destaque, e o octógono da marca como motivo visual.
7
-
8
- ## Instalação
9
-
10
- **Via npm:**
11
-
12
- ```bash
13
- npm install ui-optago
14
- ```
15
-
16
- ```html
17
- <link rel="stylesheet" href="node_modules/ui-optago/ui-optago.css">
18
- <script src="node_modules/ui-optago/ui-optago.js"></script>
19
- ```
20
-
21
- **Via CDN** (não precisa instalar nada, adicione ao `<head>`):
22
-
23
- ```html
24
- <link rel="stylesheet" href="https://unpkg.com/ui-optago/ui-optago.css">
25
- <script src="https://unpkg.com/ui-optago/ui-optago.js"></script>
26
- ```
27
-
28
- Em produção, fixe a versão para não sofrer quebras em atualizações:
29
-
30
- ```html
31
- <link rel="stylesheet" href="https://unpkg.com/ui-optago@1.0.0/ui-optago.css">
32
- <script src="https://unpkg.com/ui-optago@1.0.0/ui-optago.js"></script>
33
- ```
34
-
35
- > Também funciona via jsDelivr: `https://cdn.jsdelivr.net/npm/ui-optago/ui-optago.css`
36
-
37
- **Ou copie os arquivos direto** (`ui-optago.css` e `ui-optago.js`) para o seu projeto:
38
-
39
- ```html
40
- <head>
41
- <link rel="stylesheet" href="ui-optago.css">
42
- <!-- Carregue no <head> SEM defer: o JS aplica o tema salvo antes do
43
- primeiro paint (evita flash de tema errado) e injeta sozinho as
44
- Google Fonts e os ícones Phosphor. -->
45
- <script src="ui-optago.js"></script>
46
- </head>
47
- ```
48
-
49
- ## Showcase
50
-
51
- Abra **`ui-optago.html`** no navegador: todos os componentes com botões **Copiar** (HTML pronto) e **Ver código**.
52
-
53
- ## Selo "Desenvolvido por Óptago"
54
-
55
- Bloco pronto para o rodapé de qualquer site feito pela Óptago, mesmo sites que **não** usam o resto do design system. São dois arquivos HTML autocontidos (`<style>` + markup, sem depender de nada do site hospedeiro): `optago-credit-dark.html` (chip escuro translúcido, para fundos escuros ou neutros) e `optago-credit-light.html` (chip claro translúcido, para fundos claros). Escolha o que combina com o fundo onde o selo vai ficar.
56
-
57
- **Via CDN**, sem copiar nada:
58
-
59
- ```html
60
- <div id="optago-credit"></div>
61
- <script>
62
- fetch('https://unpkg.com/ui-optago/optago-credit-dark.html')
63
- .then(r => r.text())
64
- .then(html => document.getElementById('optago-credit').innerHTML = html);
65
- </script>
66
- ```
67
-
68
- Fixe a versão em produção: `https://unpkg.com/ui-optago@1.2.4/optago-credit-dark.html` (troque `dark` por `light` conforme o caso). Também funciona via jsDelivr: `https://cdn.jsdelivr.net/npm/ui-optago/optago-credit-dark.html`.
69
-
70
- **Ou copie o arquivo direto** para o seu projeto e sirva/inclua localmente (ex. `include` no PHP, import estático, etc.); cada arquivo já vem com essas instruções comentadas no topo.
71
-
72
- ## Estrutura de layout (app shell)
73
-
74
- Header, footer e sidebar (à direita) fixos: só o `.op-main` rola. A sidebar colapsa no desktop (só ícones + tooltip) e vira drawer no mobile.
75
-
76
- ```html
77
- <body class="op-app">
78
- <div class="op-app-body">
79
- <header class="op-header">...</header>
80
- <main class="op-main">CONTEÚDO ROLÁVEL</main>
81
- <footer class="op-footer">...</footer>
82
- </div>
83
- <aside class="op-sidebar">
84
- <nav class="op-sidebar-nav">
85
- <a class="op-nav-item" href="#secao">
86
- <i class="ph ph-palette"></i>
87
- <span class="op-nav-text">Título</span>
88
- <span class="op-nav-tooltip">Título</span>
89
- </a>
90
- </nav>
91
- </aside>
92
- </body>
93
- ```
94
-
95
- ## Componentes
96
-
97
- Todas as classes usam o prefixo `op-`; estados usam `is-` (`is-open`, `is-active`, `is-error`...).
98
-
99
- | Grupo | Classes principais |
100
- |---|---|
101
- | Botões | `op-btn` + `op-btn-primary/secondary/success/danger/warning/info`, ghosts, `op-btn-sm/lg`, `op-btn-icon`, `op-btn-group`, `is-loading` |
102
- | Badges | `op-badge` + `op-badge-brand/info/success/warning/danger`, `op-badge-pill`, `op-dot` |
103
- | Alertas | `op-alert` + `op-alert-info/success/warning/danger`, `data-op-dismiss` |
104
- | Formulários | `op-field`, `op-label`, `op-input`, `op-select`, `op-textarea`, `op-check`, `op-switch`, `op-range`, `op-input-group`, estados `is-error/is-success` |
105
- | Tabelas | `op-table` (+ `op-table-hover/striped`) e Tabulator com tema Óptago via `OptagoUI.tabulator()` |
106
- | Cards | `op-card`, `op-card-hover`, `op-stat` (KPI) |
107
- | Feedback | `op-progress`, `op-spinner`, `op-skeleton` (+ `-thumb/-title/-btn/-badge/-row`), toasts |
108
- | Navegação | `op-tabs` (linha, `op-tabs-pills`, `op-tabs-vertical`), `op-accordion`, `op-breadcrumb`, `op-pagination`, `op-dropdown` |
109
- | Overlays | `op-modal` (+ `op-modal-drawer`, `op-modal-centered`, `op-modal-sm/lg`), tooltip via `data-op-tip` |
110
- | Visibilidade | `op-mobile-only` (só abaixo de 1024px, onde a sidebar vira drawer), `op-desktop-only` (some abaixo de 1024px); ambas usam `!important`, então vencem o `display` de outra classe |
111
- | Extras | `op-timeline` (marcadores octogonais), `op-glow` (manchas verde-lima desfocadas de fundo), `op-avatar` |
112
-
113
- ## Comportamentos via atributos `data-op-*`
114
-
115
- Nenhum JS manual necessário, basta o atributo:
116
-
117
- | Atributo | Ação |
118
- |---|---|
119
- | `data-op-theme-toggle` | Alterna tema claro/escuro (persiste em `localStorage`) |
120
- | `data-op-sidebar-toggle` | Colapsa/expande a sidebar |
121
- | `data-op-sidebar-mobile` | Abre/fecha o drawer no mobile |
122
- | `data-op-modal-open="#id"` | Abre o modal |
123
- | `data-op-modal-close` | Fecha o modal (dentro dele; ESC e clique no fundo também fecham) |
124
- | `data-op-tab="nome"` | Botão de aba (com `data-op-tab-group` no container) |
125
- | `data-op-dropdown-toggle` | Abre/fecha o `.op-dropdown` |
126
- | `data-op-dismiss` | Remove o `.op-alert` pai |
127
- | `data-op-tip="texto"` | Tooltip em CSS puro (variante `.op-tip-bottom`) |
128
- | `data-op-copy="#sel"` / `data-op-code="#sel"` | Copiar HTML / ver código (showcase) |
129
-
130
- ## API JavaScript (`window.OptagoUI`)
131
-
132
- ```js
133
- OptagoUI.toast('Deploy concluído!', 'success'); // 'success' | 'error' | 'warning' | 'info'
134
- OptagoUI.openModal('#meuModal');
135
- OptagoUI.closeModal('#meuModal');
136
- OptagoUI.setTheme('light'); // 'dark' | 'light'
137
- OptagoUI.toggleSidebar();
138
- OptagoUI.customize({ accent: '#FF6B00', radius: '6px' }); // sobrescreve tokens (--op-*) em runtime
139
-
140
- // Tour guiado (carrega driver.js do CDN sob demanda, já com tema Óptago)
141
- OptagoUI.tour([
142
- { element: '#meu-elemento', popover: { title: 'Passo 1', description: 'Texto explicativo.' } },
143
- { element: '#outro', popover: { title: 'Passo 2', description: 'Continue aqui.' } },
144
- { popover: { title: 'Pronto!', description: 'Tour concluído.' } } // sem element = modal central
145
- ]).then(d => { /* instância driver.js, opcional */ });
146
-
147
- // Tabela avançada (carrega o Tabulator do CDN sob demanda, já com tema Óptago)
148
- OptagoUI.tabulator('#minhaTabela', {
149
- layout: 'fitColumns',
150
- pagination: true,
151
- data: [...],
152
- columns: [...]
153
- }).then(tabela => { /* instância Tabulator */ });
154
- ```
155
-
156
- ## Tokens (CSS Custom Properties)
157
-
158
- Personalize sobrescrevendo as variáveis no seu próprio CSS:
159
-
160
- ```css
161
- :root {
162
- --op-accent: #C0FF6B; /* verde-lima da marca */
163
- --op-cyan: #6BE0FF; /* ciano: cor secundária da marca */
164
- --op-info: #3B82F6;
165
- --op-success: #10B981;
166
- --op-warning: #F59E0B;
167
- --op-danger: #EF4444;
168
- --op-radius: 12px;
169
- /* superfícies: --op-bg, --op-panel, --op-border, --op-text, --op-muted... */
170
- }
171
- ```
172
-
173
- Ou em runtime via JS (ex.: cor por tenant/cliente vinda de uma API), sem precisar de `<style>` próprio:
174
-
175
- ```js
176
- OptagoUI.customize({ accent: '#FF6B00', cyan: '#00B8D9', radius: '6px' });
177
- // nomes curtos viram --op-*, mas o nome completo também funciona:
178
- OptagoUI.customize({ '--op-accent': '#FF6B00' });
179
- ```
180
-
181
- Lista completa de tokens e exemplos ao vivo: seção **Customizando** do [showcase](index.html#customizando).
182
-
183
- Tema claro = classe `light` no `<html>` (gerenciada automaticamente pelo JS).
184
-
185
- ### Tema compartilhado entre subdomínios
186
-
187
- Por padrão, a escolha de tema fica em `localStorage`, isolada por app. Para vários apps sob o mesmo domínio compartilharem a mesma escolha (ex.: `app1.seusite.com` e `app2.seusite.com`), adicione `data-op-theme-domain` no `<script>` da lib:
188
-
189
- ```html
190
- <script src="ui-optago.js" data-op-theme-domain=".seusite.com"></script>
191
- ```
192
-
193
- Com isso, o tema passa a ser salvo também num cookie com `Domain=.seusite.com` (além do `localStorage`, mantido como fallback), lido por qualquer subdomínio que carregue a lib com o mesmo atributo. Use um domínio de verdade, começando com `.`; não use o domínio de outro site.
194
-
195
- ## Dependências em runtime
196
-
197
- Injetadas automaticamente pelo `ui-optago.js` (CDN): Google Fonts (Chakra Petch, Inter, JetBrains Mono) e Phosphor Icons. Tabulator só é baixado se `OptagoUI.tabulator()` for chamado.
1
+ # UI Óptago
2
+
3
+ [![npm](https://img.shields.io/npm/v/ui-optago.svg)](https://www.npmjs.com/package/ui-optago)
4
+ [![license](https://img.shields.io/npm/l/ui-optago.svg)](./LICENSE)
5
+
6
+ Biblioteca de interface do usuário **leve e moderna**, da **[Óptago](https://optago.com.br)**: componentes em **CSS puro** + **JS vanilla**, sem build obrigatório e sem dependências. Tema escuro por padrão, tema claro automático, verde-lima `#C0FF6B` e ciano `#6BE0FF` como cores de destaque, e o octógono da marca como motivo visual. O visual é o **Aurora**: painéis translúcidos sobre um fundo com as luzes da marca, cantos amplos e controles em pílula. A meta de acessibilidade é a WCAG 2.2 nível AA (ver [Acessibilidade](#acessibilidade)).
7
+
8
+ ## Visão geral
9
+
10
+ A UI Óptago distribui tokens, estilos, componentes e interações reutilizáveis para interfaces web. O pacote inclui declarações de tipo e integração para CodeIgniter. A biblioteca mobile `ui-optago-rn` segue a mesma identidade visual.
11
+
12
+ ## Tecnologias e versões
13
+
14
+ A versão deste checkout é **2.0.0**, conforme [`package.json`](package.json). CSS e JavaScript vanilla formam a distribuição. O manifesto não exige dependências npm para consumo. Node.js e npm executam a geração e a verificação do manual.
15
+
16
+ As integrações servidas por CDN têm versões próprias: Phosphor 2.1.2, Tabulator 6.3.1, Chart.js 4.6.1, driver.js 1.14.0 e Toast UI Editor 3.2.2. Veja [Recursos de terceiros e privacidade](#recursos-de-terceiros-e-privacidade) para saber em que momento cada recurso é carregado.
17
+
18
+ ## Instalação
19
+
20
+ **Via npm:**
21
+
22
+ ```bash
23
+ npm install ui-optago
24
+ ```
25
+
26
+ ```html
27
+ <link rel="stylesheet" href="node_modules/ui-optago/ui-optago.css">
28
+ <script src="node_modules/ui-optago/ui-optago.js"></script>
29
+ ```
30
+
31
+ **Via CDN** (não precisa instalar nada, adicione ao `<head>`):
32
+
33
+ ```html
34
+ <link rel="stylesheet" href="https://unpkg.com/ui-optago/ui-optago.css">
35
+ <script src="https://unpkg.com/ui-optago/ui-optago.js"></script>
36
+ ```
37
+
38
+ Em produção, fixe a versão para não sofrer quebras em atualizações:
39
+
40
+ ```html
41
+ <link rel="stylesheet" href="https://unpkg.com/ui-optago@1.0.0/ui-optago.css">
42
+ <script src="https://unpkg.com/ui-optago@1.0.0/ui-optago.js"></script>
43
+ ```
44
+
45
+ Nos apps da Óptago (CodeIgniter 4) a versão não é escrita na view: vem da variável `uioptago.versao` do `.env` (na VPS, `APP_<ID>_ENV_uioptago_versao`) e as views montam a URL com `ui_optago_url('ui-optago.css')`. Para adotar uma versão nova, publique no npm e troque essa variável em cada app.
46
+
47
+ > Também funciona via jsDelivr: `https://cdn.jsdelivr.net/npm/ui-optago/ui-optago.css`
48
+
49
+ **Ou copie os arquivos direto** (`ui-optago.css` e `ui-optago.js`) para o seu projeto:
50
+
51
+ ```html
52
+ <head>
53
+ <link rel="stylesheet" href="ui-optago.css">
54
+ <!-- Carregue no <head> SEM defer: o JS aplica o tema salvo antes do
55
+ primeiro paint (evita flash de tema errado) e injeta sozinho as
56
+ Google Fonts e os ícones Phosphor. -->
57
+ <script src="ui-optago.js"></script>
58
+ </head>
59
+ ```
60
+
61
+ ## Showcase
62
+
63
+ Abra **`index.html`** no navegador: o resumo do manual, com os números, os capítulos e os modelos de tela. Cada capítulo é uma página em `capitulos/` (por exemplo `capitulos/dados.html`), com todos os componentes e botões **Copiar** (HTML pronto) e **Ver código**. O menu e o índice de cada capítulo vêm de `capitulos/capitulos.json`: ao criar ou renomear uma seção, ajuste esse arquivo e rode `npm run gerar`.
64
+
65
+ ## Selo "Desenvolvido por Óptago"
66
+
67
+ Bloco pronto para o rodapé de qualquer site feito pela Óptago, mesmo sites que **não** usam o resto da biblioteca. São dois arquivos HTML autocontidos (`<style>` + markup, sem depender de nada do site hospedeiro): `optago-credit-dark.html` (chip escuro translúcido, para fundos escuros ou neutros) e `optago-credit-light.html` (chip claro translúcido, para fundos claros). Escolha o que combina com o fundo onde o selo vai ficar.
68
+
69
+ **Via CDN**, sem copiar nada:
70
+
71
+ ```html
72
+ <div id="optago-credit"></div>
73
+ <script>
74
+ fetch('https://unpkg.com/ui-optago/optago-credit-dark.html')
75
+ .then(r => r.text())
76
+ .then(html => document.getElementById('optago-credit').innerHTML = html);
77
+ </script>
78
+ ```
79
+
80
+ Fixe a versão em produção: `https://unpkg.com/ui-optago@2.0.0/optago-credit-dark.html` (troque `dark` por `light` conforme o caso). Também funciona via jsDelivr: `https://cdn.jsdelivr.net/npm/ui-optago/optago-credit-dark.html`.
81
+
82
+ **Ou copie o arquivo direto** para o seu projeto e sirva/inclua localmente (ex. `include` no PHP, import estático, etc.); cada arquivo já vem com essas instruções comentadas no topo.
83
+
84
+ ## Estrutura de layout (app shell)
85
+
86
+ Header, footer e sidebar (à direita) fixos: só o `.op-main` rola. A sidebar colapsa no desktop (só ícones + tooltip) e vira drawer no mobile.
87
+
88
+ ```html
89
+ <body class="op-app">
90
+ <div class="op-app-body">
91
+ <header class="op-header">...</header>
92
+ <main class="op-main">CONTEÚDO ROLÁVEL</main>
93
+ <footer class="op-footer">...</footer>
94
+ </div>
95
+ <aside class="op-sidebar">
96
+ <nav class="op-sidebar-nav">
97
+ <a class="op-nav-item" href="#secao" data-op-desc="palavras-chave para a busca">
98
+ <i class="ph ph-palette"></i>
99
+ <span class="op-nav-text">Título</span>
100
+ <span class="op-nav-tooltip">Título</span>
101
+ </a>
102
+ </nav>
103
+ </aside>
104
+ </body>
105
+ ```
106
+
107
+ ## Componentes
108
+
109
+ Todas as classes usam o prefixo `op-`; estados usam `is-` (`is-open`, `is-active`, `is-error`...).
110
+
111
+ | Grupo | Classes principais |
112
+ |---|---|
113
+ | Botões | `op-btn` + `op-btn-primary/secondary/success/danger/warning/info`, ghosts, `op-btn-sm/lg`, `op-btn-icon`, `op-btn-group`, `is-loading` |
114
+ | Badges | `op-badge` + `op-badge-brand/info/success/warning/danger`, `op-badge-pill`, `op-dot` |
115
+ | Alertas | `op-alert` + `op-alert-info/success/warning/danger`, `data-op-dismiss` |
116
+ | Formulários | `op-field`, `op-label`, `op-input`, `op-select`, `op-textarea`, `op-check`, `op-switch`, `op-range`, `op-input-group`, estados `is-error/is-success` |
117
+ | Tabelas | `op-table` (+ `op-table-hover/striped`) e Tabulator com tema Óptago via `OptagoUI.tabulator()` |
118
+ | Gráficos com Chart.js | `data-op-chart="bar"` em um `<canvas>` (ou `OptagoUI.chart(alvo, configuração)`): `bar`, `line`, `area`, `doughnut`, `pie`, `radar`, `polar`; dados em `data-op-labels` e `data-op-series`; tema e troca de tema automáticos |
119
+ | Aparência | Atributos no `<html>`: `data-op-main` e `data-op-secondary` (as duas cores da marca), `data-op-radius`, `data-op-shape`, `data-op-font`, `data-op-text`, `data-op-width`, `data-op-aurora`, `data-op-surface`; `OptagoUI.appearance()`; painel `OptagoUI.customizer.open()` (`data-op-customizer-open`) e editor de tokens `data-op-token-editor` |
120
+ | Tela de abertura | `op-splash` com `data-op-splash` (some ao carregar) ou `OptagoUI.splash.show(msg, { variant, exit })` / `.hide()`. Variações `ripple`, `draw`, `orbit`, `counter` e `minimal`; saídas `fade`, `up` e `iris`; logo animado `op-logo-loader` |
121
+ | Cards | `op-card`, `op-card-hover`, `op-stat` (KPI) |
122
+ | Feedback | `op-progress`, `op-spinner`, `op-skeleton` (+ `-thumb/-title/-btn/-badge/-row`), toasts |
123
+ | Navegação | `op-tabs` (linha, `op-tabs-pills`, `op-tabs-vertical`), `op-accordion`, `op-breadcrumb`, `op-pagination`, `op-dropdown` |
124
+ | Overlays | `op-modal` (+ `op-modal-drawer` à esquerda, `op-modal-drawer-end` à direita, `op-modal-centered`, `op-modal-sm/lg`), tooltip via `data-op-tip` |
125
+ | Visibilidade | `op-mobile-only` (só abaixo de 1024px, onde a sidebar vira drawer), `op-desktop-only` (some abaixo de 1024px); ambas usam `!important`, então vencem o `display` de outra classe |
126
+ | Extras | `op-timeline` (marcadores octogonais), `op-glow` (manchas verde-lima desfocadas de fundo), `op-avatar` |
127
+ | Estados | `op-empty` (+ `op-empty-icon/-title/-text`, variante `is-error`): o que mostrar quando não há dados ou o recurso está indisponível |
128
+ | Acessibilidade | `op-skip-link` (link “pular para o conteúdo”), `op-sr-only` (texto só para leitores de tela), `op-h1` a `op-h4` (aparência de título sem ser título) |
129
+ | Movimento | `op-reveal` (o bloco sobe e aparece ao entrar na tela), `op-stagger` (os filhos entram em cascata), `op-text-gradient` (texto em degradê da marca) |
130
+ | Botão largo | `op-btn-block` (ocupa a largura do contêiner) |
131
+ | Valores sensíveis | `data-op-sensitive` no valor (saldo, dinheiro, CPF) + um botão `data-op-privacy-toggle`; `op-sensitive-group` para um valor com botão próprio |
132
+ | Busca no menu | Campo de busca inserido na sidebar automaticamente; cada `op-nav-item` é achado pelo nome e por `data-op-desc` |
133
+ | Submenu da sidebar | `<details class="op-nav-group">` + `<summary class="op-nav-item">` + `op-nav-sub` |
134
+ | Cabeçalho de página | `op-page-header` (+ `-main`, `-actions`), `op-page-title`, `op-page-desc` |
135
+ | Lista de definição | `op-dl` em um `<dl>` (colunas) e `op-dl-inline` (rótulo à esquerda, valor à direita) |
136
+ | Etapas | `op-steps` + `op-step` (`is-done`, `is-active`), `op-steps-vertical`; assistente com `data-op-wizard` |
137
+ | Chips e tags | `op-chip` (+ `op-chip-remove`), `op-chip-check` (checkbox nativo), campo de tags com `data-op-tags` |
138
+ | Segmentado e opções | `op-segmented` e `op-option` (radio ou checkbox nativos) |
139
+ | Upload | `op-upload` + `data-op-upload` sobre um `<input type="file">` |
140
+ | Máscaras de campo | `data-op-format="cpf"` (também `cnpj`, `telefone`, `cep`, `data`, `moeda` ou um padrão como `00:00`) |
141
+ | Data e período | `op-input` com `type="date"`; `op-date-range` + `data-op-date-range` |
142
+ | Código de verificação | `op-otp` + `data-op-otp` em volta de um único `<input>`: a lib desenha uma casa por dígito; evento `op:otp-complete` |
143
+ | Popover | `op-popover` com o atributo nativo `popover` e `popovertarget` no botão |
144
+ | Copiar | `data-op-clipboard="texto"` ou `data-op-clipboard-target="#id"` |
145
+ | Paleta de comandos | `data-op-command-open` e Ctrl+K; `OptagoUI.commands([...])` |
146
+ | Gráficos | Chart.js com tema Óptago: `data-op-chart` em um `<canvas>` ou `OptagoUI.chart()`; cores das séries em `--op-series-1` a `6` |
147
+ | Páginas prontas | `op-center-page`, `op-auth-card`, `op-error-page`, `op-error-code`; login completo com marca, luzes de fundo e rodapé (`op-auth-page`, `op-auth-glows`, `op-auth-theme`, `op-auth-divider`, `op-auth-social`, `op-auth-footer`), como em `exemplos/login.html` |
148
+ | Tabela de trabalho | `op-toolbar`, filtro com `data-op-table-filter`, seleção e ações em lote com `data-op-table-select` + `op-bulk-bar`, `op-table-stack` (linhas viram cartões no celular) |
149
+ | Validação de formulário | `data-op-validate` no `<form>`, resumo `op-error-summary`, barra de ações fixa `op-action-bar` |
150
+ | Campos extras | `op-number` (− e +), combobox com `data-op-multiple` (seleção múltipla com chips), `op-rating` (estrelas), `op-strength` (força da senha), `data-op-counter` (contador de caracteres) |
151
+ | Notificações e conta | `data-op-notify` + `op-notify` (sino com popover), `op-account-btn` + `op-menu-header` (menu de conta) |
152
+ | Banners e avisos | `op-banner` (aviso da página), `op-consent` (cookies), `OptagoUI.sessionWarning()` (sessão expirando), `data-op-offline` (queda de conexão) |
153
+ | Navegação inferior | `op-bottom-nav` + `op-bottom-nav-item` (celular) |
154
+ | Modo compacto | `data-op-density-toggle` / classe `op-dense` no `<html>` |
155
+ | Kanban | `data-op-kanban` + `op-kanban-col`, `op-kanban-list`, `op-kanban-card` (arrastar, botões ← → ou Alt + seta) |
156
+ | Calendário | `data-op-calendar` + `data-op-events` (mês com dias marcados) |
157
+ | Galeria | `op-gallery` + `data-op-gallery` (miniaturas com visualizador) |
158
+ | Árvore | `op-tree` (lista com `<details>` aninhados) |
159
+ | Bloco de código | `op-code` em volta de um `<pre>` (botão de copiar automático) |
160
+ | Tabela ordenável | `data-op-sort` no `<th>`, `op-table-sticky` + `op-table-scroll` (cabeçalho fixo), `data-op-row-toggle` + `op-row-detail` (linha de detalhe) |
161
+ | Filtros ativos | `op-filter-bar` com chips removíveis e `data-op-filter-clear` |
162
+ | Lista de itens | `op-list` + `op-list-item` (`-body`, `-title`, `-text`, `-actions`) |
163
+ | Texto | `op-prose` (texto longo), `op-truncate`, `op-clamp-2/3`, `data-op-more` (ver mais) |
164
+ | Campos repetíveis | `data-op-repeater` com um `<template>` |
165
+ | Faixa de valores | `op-range-dual` + `data-op-range-dual` (duas alças) |
166
+ | Lista de transferência | `op-transfer` + `data-op-transfer` (dois `<select multiple>`) |
167
+ | Editor de texto | `op-editor` + `data-op-editor` (HTML e Markdown), `OptagoUI.editor()` |
168
+ | Alterações não salvas | `data-op-unsaved` no `<form>`, `op-unsaved-note` |
169
+ | Carrossel | `op-carousel` + `data-op-carousel` (`data-op-autoplay`) |
170
+ | Painéis redimensionáveis | `op-split` + `data-op-split` |
171
+ | Menu de contexto | `data-op-context-menu="#menu"` + `op-menu op-context-menu` |
172
+ | Botões extras | `op-btn-split` (botão dividido), `op-fab` (flutuante), `data-op-back-top` (voltar ao topo) |
173
+ | Páginas de resultado | `op-result` (+ `-icon`, `-title`, `-text`, `-actions`; `is-success`, `is-warning`, `is-error`) |
174
+ | Blocos de site | `op-hero`, `op-pricing` + `op-price-card`, `op-site-footer` |
175
+ | Impressão | `op-no-print`, `op-print-only` (o resto é automático) |
176
+ | Manual | `op-chapter` e `op-manual`, usados no próprio showcase |
177
+
178
+ ## Comportamentos via atributos `data-op-*`
179
+
180
+ Nenhum JS manual necessário, basta o atributo:
181
+
182
+ | Atributo | Ação |
183
+ |---|---|
184
+ | `data-op-theme-toggle` | Alterna tema claro/escuro (persiste em `localStorage`) |
185
+ | `data-op-sidebar-toggle` | Colapsa/expande a sidebar |
186
+ | `data-op-sidebar-mobile` | Abre/fecha o drawer no mobile |
187
+ | `data-op-modal-open="#id"` | Abre o modal |
188
+ | `data-op-modal-close` | Fecha o modal (dentro dele; ESC e clique no fundo também fecham) |
189
+ | `data-op-tab="nome"` | Botão de aba (com `data-op-tab-group` no container) |
190
+ | `data-op-dropdown-toggle` | Abre/fecha o `.op-dropdown` |
191
+ | `data-op-dismiss` | Remove o `.op-alert` pai |
192
+ | `data-op-tip="texto"` | Tooltip em CSS puro (variante `.op-tip-bottom`) |
193
+ | `data-op-copy="#sel"` / `data-op-code="#sel"` | Copiar HTML / ver código (showcase) |
194
+ | `data-op-motion-toggle` | Pausa/retoma as animações decorativas (fundo aurora, pulsos); a escolha persiste em `localStorage` |
195
+ | `data-op-confirm="Mensagem"` | Em `<form>` ou `<a>`: pede confirmação antes de enviar ou navegar (título e botão opcionais em `data-op-confirm-title` e `data-op-confirm-button`) |
196
+ | `data-op-privacy-toggle` | Liga/desliga o modo privacidade, que oculta todo elemento com `data-op-sensitive` (persiste em `localStorage`) |
197
+ | `data-op-sensitive` | Marca um valor sensível. `data-op-mask="R$ ••••"` troca a máscara; `data-op-sensitive-label` troca o texto lido pelo leitor de tela (padrão: “Valor oculto”) |
198
+ | `data-op-sensitive-toggle` | Botão que mostra/oculta um valor específico: o do mesmo `op-sensitive-group`, ou o do seletor passado no atributo |
199
+ | `data-op-desc="palavras"` | No `op-nav-item`: descrição que não aparece na tela mas é usada pela busca do menu (sinônimos, palavras-chave) |
200
+ | `data-op-search="off"` | No `<aside class="op-sidebar">`: não insere o campo de busca do menu |
201
+ | `data-op-format="cpf"` | Máscara de campo: `cpf`, `cnpj`, `telefone`, `cep`, `data`, `moeda`, ou um padrão com `0` no lugar de cada dígito |
202
+ | `data-op-upload` | No contêiner `op-upload`: lista os arquivos escolhidos e permite remover |
203
+ | `data-op-tags` | Campo de tags: Enter ou vírgula cria o chip; um `<input type="hidden">` dentro recebe os valores |
204
+ | `data-op-wizard` | Assistente em etapas; `data-op-step-next`, `data-op-step-prev` e `data-op-step-panel` |
205
+ | `data-op-date-range` | Par de campos de data em que a final nunca fica antes da inicial |
206
+ | `data-op-clipboard` / `data-op-clipboard-target="#id"` | Copia um texto ou o conteúdo de outro elemento |
207
+ | `data-op-command-open` | Abre a paleta de comandos (e habilita o atalho Ctrl+K na página) |
208
+ | `data-op-chart="bar"` | No `<canvas>`: gráfico do Chart.js com o tema Óptago. Tipos: `bar`, `line`, `area`, `doughnut`, `pie`, `radar`, `polar`. Dados: `data-op-labels="Seg,Ter"` + `data-op-data="1,2"` (uma série) ou `data-op-series='[{"label":"A","data":[1,2]}]'`. Também `data-op-stacked`, `data-op-horizontal`, `data-op-height="300"` e `data-op-options='{...}'` (opções do Chart.js) |
209
+ | `data-op-splash` | No `<div class="op-splash">` (pode ir vazia), no começo do `<body>`: tela de abertura que some quando a página carrega. Opções: `data-op-splash-variant="ripple\|draw\|orbit\|counter\|minimal"`, `data-op-splash-exit="fade\|up\|iris"`, `data-op-splash-min="800"` (tempo mínimo, em ms) e `data-op-splash-message` |
210
+ | `data-op-otp` | No `op-otp`: desenha as casas do código de verificação a partir do `maxlength` do campo |
211
+ | `data-op-table-select` | Em volta da tabela: liga `data-op-select-all`, `data-op-select-row`, a `op-bulk-bar` e `data-op-selected-count` |
212
+ | `data-op-table-filter="#tabela"` | Em um campo de texto: filtra as linhas da tabela enquanto a pessoa digita |
213
+ | `data-op-validate` | No `<form>`: valida com as regras do HTML, marca os campos e mostra o resumo de erros. Mensagem própria por campo em `data-op-error` |
214
+ | `data-op-number` | Campo numérico com botões `data-op-number-down` e `data-op-number-up` |
215
+ | `data-op-multiple` | No combobox: seleção múltipla, com chips e um `<input type="hidden">` com os valores |
216
+ | `data-op-strength="#senha"` | Medidor de força ligado a um campo de senha |
217
+ | `data-op-counter` | Em campo com `maxlength`: mostra o contador de caracteres |
218
+ | `data-op-notify` | Central de notificações: mantém o número do sino e o nome acessível; `data-op-notify-read-all` marca tudo como lido |
219
+ | `data-op-banner-id="x"` | Em `op-banner` ou `op-consent`: lembra que foi fechado. A resposta vem de `data-op-dismiss="valor"` e do evento `op:banner-dismiss` |
220
+ | `data-op-offline` | No `<body>`: mostra um aviso quando a conexão cai e quando volta |
221
+ | `data-op-density-toggle` | Liga/desliga o modo compacto (persiste em `localStorage`) |
222
+ | `data-op-kanban` | Quadro kanban; `data-op-kanban-count` mostra o total de cada coluna |
223
+ | `data-op-calendar` | Calendário do mês; eventos em `data-op-events='{"2026-11-18":"Entrega"}'` |
224
+ | `data-op-gallery` | Na `op-gallery`: abre as imagens no visualizador |
225
+ | `data-op-theme="system"` | Botão que escolhe o tema: `light`, `dark` ou `system` (segue o sistema operacional) |
226
+ | `data-op-sort` | No `<th>`: coluna ordenável. `data-op-sort="number"` ou `"date"` para números e datas; `data-sort-value` na célula dá o valor exato |
227
+ | `data-op-row-toggle` | Botão que abre a linha `op-row-detail` seguinte |
228
+ | `data-op-unsaved` | No `<form>`: o navegador pergunta antes de sair com alterações não enviadas |
229
+ | `data-op-repeater` | Campos repetíveis: `data-op-repeater-add`, `data-op-repeater-remove`, `data-op-min`, `data-op-max` |
230
+ | `data-op-range-dual` | Faixa com duas alças; `data-op-output="R$ {0} a R$ {1}"` define o texto |
231
+ | `data-op-more` | Texto longo com botão `data-op-more-toggle` |
232
+ | `data-op-filter-clear` | Remove todos os chips da `op-filter-bar` |
233
+ | `data-op-carousel` | Carrossel; `data-op-autoplay="5000"` liga a troca automática (com botão de pausar) |
234
+ | `data-op-context-menu="#menu"` | Abre o menu indicado com o botão direito ou Shift+F10 |
235
+ | `data-op-split="35"` | Dois painéis com divisor arrastável; o valor é a largura inicial do primeiro, em % |
236
+ | `data-op-transfer` | Lista de transferência: `data-op-transfer-source`, `-target`, `-add` e `-remove` |
237
+ | `data-op-back-top` | Botão que aparece depois que a página rola e volta ao topo |
238
+ | `data-op-shortcuts-open` | Abre a lista de atalhos de teclado (também com `?`) |
239
+ | `data-op-editor="markdown"` | Editor de texto sobre um `<textarea>`; `"html"` grava HTML |
240
+ | `data-op-locale` | Em um `<script type="application/json">`: traduções dos textos da biblioteca |
241
+ | `data-op-observe="off"` | No `<script>` da lib ou em um trecho da página: desliga o tratamento automático de HTML inserido |
242
+
243
+ ## API JavaScript (`window.OptagoUI`)
244
+
245
+ ```js
246
+ OptagoUI.toast('Deploy concluído!', 'success'); // 'success' | 'error' | 'warning' | 'info'
247
+ OptagoUI.openModal('#meuModal');
248
+ OptagoUI.closeModal('#meuModal');
249
+ OptagoUI.setTheme('light'); // 'dark' | 'light'
250
+ OptagoUI.toggleSidebar();
251
+ OptagoUI.customize({ main: '#FF6B00', radius: '6px' }); // sobrescreve tokens (--op-*) em runtime
252
+
253
+ // Confirmação de ação destrutiva: Promise<boolean>; o foco começa em "Cancelar"
254
+ OptagoUI.confirm('O projeto será excluído. Isso não pode ser desfeito.', {
255
+ title: 'Excluir o projeto?', confirmText: 'Excluir'
256
+ }).then(ok => { if (ok) excluir(); });
257
+
258
+ OptagoUI.setMotion(false); // pausa as animações decorativas (true retoma); toggleMotion() alterna
259
+ OptagoUI.setPrivacy(true); // oculta os valores com data-op-sensitive (false mostra); togglePrivacy() alterna
260
+ OptagoUI.announce('3 itens encontrados'); // aviso só para leitor de tela
261
+ OptagoUI.setStep('#cadastro', 2); // vai para a etapa 3 de um data-op-wizard
262
+ OptagoUI.commands([ // ações extras na paleta de comandos (Ctrl+K)
263
+ { label: 'Novo pedido', desc: 'criar venda', icon: 'ph ph-plus', run: () => abrirPedido() }
264
+ ]);
265
+ OptagoUI.validate('#cadastro'); // valida um form[data-op-validate]; devolve true se estiver tudo certo
266
+ OptagoUI.sessionWarning({ // avisa que a sessão vai expirar e deixa continuar
267
+ seconds: 60, onExtend: () => renovarSessao(), onExpire: () => sair()
268
+ });
269
+ OptagoUI.setOffline(true); // mostra o aviso de conexão (false: "conexão restabelecida")
270
+ OptagoUI.setDensity('compact'); // modo compacto; 'default' volta ao normal
271
+ OptagoUI.setTheme('system'); // volta a seguir o tema do sistema operacional
272
+ OptagoUI.toast('Pedido excluído', 'info', { // toast com botão de ação
273
+ action: { label: 'Desfazer', onClick: () => restaurar() }
274
+ });
275
+ OptagoUI.toast.promise(salvar(), { // "carregando" que vira sucesso ou erro
276
+ loading: 'Salvando...', success: 'Salvo', error: 'Não foi possível salvar'
277
+ });
278
+ OptagoUI.locale({ common: { close: 'Close' } }); // traduções (ver "Idioma")
279
+ OptagoUI.t('table.selected', [3]); // texto do dicionário: "3 selecionadas"
280
+ OptagoUI.setDirty('#form', false); // formulário com data-op-unsaved: salvo por AJAX
281
+ OptagoUI.shortcuts([{ keys: 'Ctrl+S', label: 'Salvar', run: () => salvar() }]);
282
+ OptagoUI.editor('#caixa', { format: 'html' }).then(editor => editor.getMarkdown());
283
+ OptagoUI.refresh(); // só com data-op-observe="off": o HTML inserido depois já é tratado sozinho
284
+
285
+ // Tour guiado (carrega driver.js do CDN sob demanda, já com tema Óptago)
286
+ OptagoUI.tour([
287
+ { element: '#meu-elemento', popover: { title: 'Passo 1', description: 'Texto explicativo.' } },
288
+ { element: '#outro', popover: { title: 'Passo 2', description: 'Continue aqui.' } },
289
+ { popover: { title: 'Pronto!', description: 'Tour concluído.' } } // sem element = modal central
290
+ ]).then(d => { /* instância driver.js, opcional */ });
291
+
292
+ // Tabela avançada (carrega o Tabulator do CDN sob demanda, já com tema Óptago)
293
+ OptagoUI.tabulator('#minhaTabela', {
294
+ layout: 'fitColumns',
295
+ pagination: true,
296
+ data: [...],
297
+ columns: [...]
298
+ }).then(tabela => { /* instância Tabulator */ });
299
+
300
+ // Gráfico (carrega o Chart.js do CDN sob demanda, já com o tema Óptago e a troca de tema)
301
+ OptagoUI.chart('#vendas', {
302
+ type: 'bar',
303
+ data: { labels: ['Seg', 'Ter', 'Qua'], datasets: [{ label: 'Pedidos', data: [40, 65, 52] }] }
304
+ }).then(grafico => { /* instância Chart.js */ });
305
+
306
+ // Aparência: opções nomeadas (a escolha fica salva no navegador)
307
+ OptagoUI.appearance({ main: 'blue', secondary: 'rose', radius: 'soft', font: 'system' });
308
+ OptagoUI.appearance({ main: '#FF6B00' }); // cor livre: hover, texto e tema claro são calculados
309
+ OptagoUI.appearance({ tokens: { '--op-info': '#1E90FF' } }); // qualquer token, salvo no navegador
310
+ OptagoUI.customizer.open(); // painel Personalizar
311
+
312
+ // Tela de abertura por código
313
+ OptagoUI.splash.show('Abrindo o relatório...', { variant: 'draw', exit: 'iris' });
314
+ OptagoUI.splash.hide();
315
+ ```
316
+
317
+ Por marcação, o mesmo gráfico fica `<div class="op-chart-canvas"><canvas data-op-chart="bar" data-op-labels="Seg,Ter,Qua" data-op-data="40,65,52" data-op-label="Pedidos" aria-label="Pedidos por dia: segunda 40, terça 65, quarta 52"></canvas></div>`. O canvas não tem texto: descreva os números em `aria-label` (sem ele, a lib escreve um).
318
+
319
+ ## Tokens (CSS Custom Properties)
320
+
321
+ Personalize sobrescrevendo as variáveis no seu próprio CSS:
322
+
323
+ ```css
324
+ :root {
325
+ --op-main: #C0FF6B; /* cor principal da marca (antes --op-accent, que continua valendo) */
326
+ --op-secondary: #6BE0FF; /* cor secundária da marca (antes --op-cyan, que continua valendo) */
327
+ --op-info: #3B82F6;
328
+ --op-success: #10B981;
329
+ --op-warning: #F59E0B;
330
+ --op-danger: #EF4444;
331
+ --op-radius: 18px; /* --op-radius-sm: 12px, --op-radius-lg: 24px, --op-radius-pill: 999px */
332
+ /* superfícies: --op-bg, --op-panel, --op-border, --op-text, --op-muted... */
333
+ /* Aurora: --op-glass (painel translúcido), --op-glass-line, --op-aurora-1, --op-aurora-2 */
334
+ }
335
+ ```
336
+
337
+ Ou em runtime via JS (ex.: cor por tenant/cliente vinda de uma API), sem precisar de `<style>` próprio:
338
+
339
+ ```js
340
+ OptagoUI.customize({ main: '#FF6B00', secondary: '#00B8D9', radius: '6px' });
341
+ // nomes curtos viram --op-*, mas o nome completo também funciona:
342
+ OptagoUI.customize({ '--op-main': '#FF6B00' });
343
+ // os nomes antigos (accent, cyan, --op-accent, --op-cyan) continuam aceitos e valem o mesmo
344
+ ```
345
+
346
+ As duas cores da marca se chamam pelo papel: **principal** (`--op-main`) e **secundária** (`--op-secondary`). Os nomes antigos `--op-accent` e `--op-cyan` são apelidos deles e seguem funcionando em qualquer CSS que você já tenha. Lista completa de tokens, editor ao vivo e todas as opções de aparência: seção **Customizando** do [manual](capitulos/comecando.html#customizando), ou o painel **Personalizar** (`OptagoUI.customizer.open()`).
347
+
348
+ Tema claro = classe `light` no `<html>` (gerenciada automaticamente pelo JS).
349
+
350
+ ### Tema compartilhado entre subdomínios
351
+
352
+ Por padrão, a escolha de tema fica em `localStorage`, isolada por app. Para vários apps sob o mesmo domínio compartilharem a mesma escolha (ex.: `app1.seusite.com` e `app2.seusite.com`), adicione `data-op-theme-domain` no `<script>` da lib:
353
+
354
+ ```html
355
+ <script src="ui-optago.js" data-op-theme-domain=".seusite.com"></script>
356
+ ```
357
+
358
+ Com isso, o tema passa a ser salvo também num cookie com `Domain=.seusite.com` (além do `localStorage`, mantido como fallback), lido por qualquer subdomínio que carregue a lib com o mesmo atributo. Use um domínio de verdade, começando com `.`; não use o domínio de outro site.
359
+
360
+ ## Acessibilidade
361
+
362
+ A meta é a **WCAG 2.2 nível AA**. Isto é uma meta de projeto, não uma declaração de conformidade: cada tela ainda precisa ser testada com teclado e com leitor de tela.
363
+
364
+ O que a biblioteca resolve sozinha:
365
+
366
+ - **Foco do teclado** sempre visível, com contraste de pelo menos 3:1 nos dois temas.
367
+ - **Teclado:** setas, Home e End nas abas; setas nos menus; combobox; modal com foco preso dentro e devolvido a quem abriu; ESC fecha uma camada por vez.
368
+ - **ARIA:** papéis e estados de abas, modal, dropdown, combobox, switch, barra de progresso e toasts.
369
+ - **Nomes acessíveis** para os botões da própria lib que só têm ícone (fechar, tema, menu) e para controles com `data-op-tip`; ícones ficam ocultos do leitor de tela.
370
+ - **Contraste:** texto com pelo menos 4,5:1 e contorno de campos com pelo menos 3:1.
371
+ - **Movimento:** `data-op-motion-toggle` pausa as animações decorativas, e `prefers-reduced-motion` é respeitado.
372
+
373
+ O que continua com quem monta a tela:
374
+
375
+ - `lang` no `<html>` e um `<title>` que descreva a página.
376
+ - `<a class="op-skip-link" href="#conteudo">Pular para o conteúdo</a>` como primeiro elemento do `<body>`, com `id="conteudo"` no `<main>`.
377
+ - Um `<label for>` para cada campo e texto alternativo nas imagens.
378
+ - Erro de formulário com `aria-invalid="true"` no campo (já aplica o estilo de erro) e `aria-describedby` apontando para a mensagem. Com `data-op-validate` no `<form>`, a lib faz isso e ainda monta o resumo de erros.
379
+ - `aria-label` em botão só com ícone que não tenha `data-op-tip`.
380
+ - Um jeito de pausar as animações em algum lugar da interface: um botão `data-op-motion-toggle` ou o painel Personalizar (`data-op-customizer-open`), que já traz a opção. O fundo aurora se move sozinho por mais de 5 segundos, então precisa poder ser pausado (WCAG 2.2.2).
381
+
382
+ O HTML inserido depois do carregamento (AJAX, telas montadas por código) recebe sozinho o mesmo tratamento do resto da página. `OptagoUI.refresh()` só é necessário com `data-op-observe="off"`.
383
+
384
+ ### Verificação automática
385
+
386
+ O repositório traz `auditoria.html`, uma página que abre o showcase (ou outra página do mesmo endereço) nos dois temas e em duas larguras e confere nomes acessíveis, rótulos, ids, ordem dos títulos, contraste de texto, tamanho dos alvos e rolagem lateral. Ela roda no navegador, sem código de terceiros. Sirva a pasta por HTTP (por exemplo, `python -m http.server`) e abra `/auditoria.html`.
387
+
388
+ É uma primeira triagem: passar nela não significa conformidade. Navegação por teclado, leitor de tela e zoom continuam sendo teste manual.
389
+
390
+ `npm run verificar` (ou `node scripts/verificar.mjs`) roda essa auditoria em um Chrome ou Edge sem janela contra o showcase e os modelos de `exemplos/`, e ainda confere a sintaxe do JS, as chaves do CSS e se os arquivos gerados estão em dia. O mesmo comando roda a cada pull request (`.github/workflows/verificacao.yml`). Não há dependências a instalar.
391
+
392
+ ## Idioma
393
+
394
+ Todo texto que a biblioteca escreve (rótulos, avisos, mensagens para leitor de tela) vem de um dicionário em português. Para traduzir ou ajustar um texto:
395
+
396
+ ```js
397
+ OptagoUI.locale({ common: { close: 'Close' }, table: { empty: 'No results' } });
398
+ ```
399
+
400
+ O formato das mensagens é o do **CodeIgniter 4** (ICU MessageFormat): `{0}` e `{nome}` para valores, `{0, number}` para números e `{0, plural, =0{...} one{...} other{...}}` para plural. Mensagens no estilo do CodeIgniter 3 (`%s`, `%d`) também funcionam.
401
+
402
+ Com o CodeIgniter 4, um arquivo de idioma serve ao PHP e à tela:
403
+
404
+ 1. Copie `codeigniter/Language/` para `app/Language/` (vêm `pt-BR` e `en`).
405
+ 2. No layout, entregue os textos do idioma atual, sem JavaScript inline:
406
+
407
+ ```php
408
+ <script type="application/json" data-op-locale><?= json_encode(lang('OptagoUI.ui'), JSON_UNESCAPED_UNICODE | JSON_HEX_TAG) ?></script>
409
+ ```
410
+
411
+ 3. No PHP, o mesmo texto: `lang('OptagoUI.ui.table.selected', [3])`. Na tela: `OptagoUI.t('table.selected', [3])`.
412
+
413
+ Fora do CodeIgniter, carregue `locales/en.json` e passe o objeto a `OptagoUI.locale()`. O `lang` do `<html>` define plural, números e datas.
414
+
415
+ Para um idioma novo, crie `locales/<idioma>.json` com as chaves de `locales/pt-BR.json` e rode `npm run gerar`: o script gera o arquivo do CodeIgniter e avisa se faltar alguma chave. Os arquivos em `locales/pt-BR.json`, `codeigniter/` e `tokens.json` são gerados a partir do código: não edite à mão.
416
+
417
+ ## Editor de texto
418
+
419
+ Editor visual com modo Markdown, sobre um `<textarea>`. O mesmo conteúdo sai em HTML e em Markdown:
420
+
421
+ ```html
422
+ <div class="op-editor" data-op-editor="markdown">
423
+ <textarea name="descricao" id="descricao"></textarea>
424
+ <input type="hidden" name="descricao_html" data-op-editor-html>
425
+ </div>
426
+ ```
427
+
428
+ - O `<textarea>` recebe o formato de `data-op-editor` (`markdown` ou `html`). Os campos ocultos `data-op-editor-html` e `data-op-editor-markdown` são opcionais e recebem o outro formato.
429
+ - Por código: `OptagoUI.editor('#caixa')` devolve uma Promise com `getHTML()`, `getMarkdown()`, `setHTML()`, `setMarkdown()`, `focus()` e `destroy()`.
430
+ - É o [Toast UI Editor](https://ui.toast.com/tui-editor) 3.2.2 (MIT), baixado só quando a caixa está perto de aparecer na tela. Se ele não carregar, o `<textarea>` continua funcionando.
431
+ - **Limpe o HTML no servidor** antes de salvar e de mostrar a outras pessoas: ele foi escrito por quem usa o sistema. O Markdown também aceita HTML.
432
+ - O envio de estatísticas de uso do editor ao Google Analytics vem desligado.
433
+
434
+ ## Valores sensíveis
435
+
436
+ Para telas vistas por outras pessoas (atendimento, chamada, tela compartilhada):
437
+
438
+ ```html
439
+ <button class="op-btn op-btn-icon" data-op-privacy-toggle data-op-tip="Ocultar ou mostrar valores">
440
+ <i class="ph ph-eye op-icon-eye"></i>
441
+ <i class="ph ph-eye-slash op-icon-eye-slash" style="display:none"></i>
442
+ </button>
443
+
444
+ <span data-op-sensitive>R$ 48.920,15</span>
445
+ <span data-op-sensitive data-op-mask="•••.•••.•••-••">111.222.333-44</span>
446
+ ```
447
+
448
+ - No lugar do valor aparece um borrão de tamanho fixo. O que está desfocado é um texto de preenchimento, não o valor real: não dá para recuperar o valor ampliando a tela nem estimá-lo pelo comprimento.
449
+ - Com `data-op-mask="..."` aparece o texto que você definir (sem borrão), como no CPF do exemplo.
450
+ - O valor oculto não é desenhado na tela, não pode ser selecionado nem copiado, e o leitor de tela anuncia “Valor oculto”.
451
+ - Com o modo ligado, o valor não aparece nem por um instante ao carregar a página.
452
+ - Para começar com tudo oculto: `<script src="ui-optago.js" data-op-privacy="on">`.
453
+ - Use em `<span>`, não direto em `<td>`.
454
+
455
+ O valor continua no HTML da página: isto protege contra quem olha a tela, não contra quem inspeciona o código. Dado que a pessoa não pode ver não deve ser enviado ao navegador.
456
+
457
+ ## Busca no menu
458
+
459
+ A sidebar ganha sozinha um campo de busca acima dos itens. Cada item é encontrado pelo nome (o texto que aparece) e pela descrição em `data-op-desc`, que não aparece na tela:
460
+
461
+ ```html
462
+ <a class="op-nav-item" href="/pedidos" data-op-desc="vendas compras nota fiscal">
463
+ <i class="ph ph-receipt"></i>
464
+ <span class="op-nav-text">Pedidos</span>
465
+ <span class="op-nav-tooltip">Pedidos</span>
466
+ </a>
467
+ ```
468
+
469
+ A busca ignora acentos e maiúsculas. Enter abre o primeiro resultado, ESC limpa e a seta para baixo leva o foco para a lista. Com a sidebar recolhida aparece uma lupa, que a expande e foca o campo. Para não ter a busca: `<aside class="op-sidebar" data-op-search="off">`.
470
+
471
+ ### Nome e descrição de cada item
472
+
473
+ Todo item do menu tem duas informações:
474
+
475
+ - **Nome:** o texto em `op-nav-text`. É o que aparece no botão.
476
+ - **Descrição:** o atributo `data-op-desc`. Não aparece na tela; é usada pela busca do menu e pela paleta de comandos.
477
+
478
+ Escreva na descrição 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. Para “Pedidos”, por exemplo: `vendas compras nota fiscal nf faturar`. Use de 3 a 8 palavras, em minúsculas, separadas por espaço, sem repetir o nome. Itens de submenu e o título do grupo também levam descrição.
479
+
480
+ ### Submenu
481
+
482
+ Grupo recolhível, com `<details>` nativo:
483
+
484
+ ```html
485
+ <details class="op-nav-group">
486
+ <summary class="op-nav-item" data-op-desc="ajustes preferências sistema">
487
+ <i class="ph ph-gear"></i>
488
+ <span class="op-nav-text">Configurações</span>
489
+ <i class="ph ph-caret-down op-nav-caret"></i>
490
+ <span class="op-nav-tooltip">Configurações</span>
491
+ </summary>
492
+ <div class="op-nav-sub">
493
+ <a class="op-nav-item" href="/usuarios" data-op-desc="pessoas equipe acessos permissões">
494
+ <span class="op-nav-text">Usuários</span>
495
+ </a>
496
+ </div>
497
+ </details>
498
+ ```
499
+
500
+ Na busca, o grupo abre sozinho quando um item dele casa com o que foi digitado. Com a sidebar recolhida, clicar no ícone do grupo a expande.
501
+
502
+ ## Recursos de terceiros e privacidade
503
+
504
+ A biblioteca não tem telemetria, não rastreia e não envia dados a ninguém. O que ela carrega e guarda:
505
+
506
+ | O quê | De onde | Quando | Como desligar |
507
+ |---|---|---|---|
508
+ | Fontes (Chakra Petch, Inter, JetBrains Mono) | Google Fonts (`fonts.googleapis.com`, `fonts.gstatic.com`) | Sempre | `data-op-fonts="off"` |
509
+ | Ícones Phosphor 2.1.2 (só folhas de estilo e fontes) | `unpkg.com` | Sempre | `data-op-icons="off"`, ou `data-op-icons="regular,bold"` para carregar só alguns pesos |
510
+ | Tabulator 6.3.1 | `unpkg.com` | Só ao chamar `OptagoUI.tabulator()` | Não chamar |
511
+ | Chart.js 4.6.1 | `cdn.jsdelivr.net` | Só ao chamar `OptagoUI.chart()` ou em páginas com `data-op-chart` | Não usar |
512
+ | driver.js 1.14.0 | `cdn.jsdelivr.net` | Só ao chamar `OptagoUI.tour()` | Não chamar |
513
+ | Toast UI Editor 3.2.2 | `uicdn.toast.com` | Só em páginas com `data-op-editor` ou ao chamar `OptagoUI.editor()` | Não usar, ou hospedar os arquivos e apontar `data-op-editor-base="/sua/pasta/"` |
514
+
515
+ Todas as versões são fixas. Nenhum JavaScript de terceiros é executado no carregamento da página.
516
+
517
+ Os ícones, o Tabulator e o CSS do driver.js são carregados com verificação de integridade (`integrity`): se o CDN servir um arquivo diferente do esperado, o navegador se recusa a usá-lo. Duas exceções: o módulo do driver.js (vem por `import()`, que não aceita integridade) e o editor de texto (o CDN dele não permite a verificação). Para o editor, o mais seguro em produção é hospedar os arquivos por conta própria.
518
+
519
+ Carregar fontes e ícones de um CDN faz o navegador do visitante se conectar a esses servidores, que recebem o endereço IP dele. Para evitar isso, hospede os arquivos por conta própria e desligue a injeção:
520
+
521
+ ```html
522
+ <script src="ui-optago.js" data-op-assets="off"></script>
523
+ ```
524
+
525
+ Com `data-op-assets="off"` a lib não carrega nada de terceiros; forneça você as fontes (famílias `Chakra Petch`, `Inter` e `JetBrains Mono`) e o CSS dos ícones Phosphor.
526
+
527
+ No navegador, a lib guarda apenas preferências de interface, em `localStorage`: `op-theme` (tema), `op-sidebar-collapsed` (sidebar), `op-motion` (animações), `op-privacy` (valores ocultos ou não), `op-density` (modo compacto) e `op-banner-<id>` (banner ou aviso de cookies já respondido, só quando você usa `data-op-banner-id`). Com `data-op-theme-domain`, o tema também vai para um cookie de mesmo nome, válido por um ano. Nada disso identifica a pessoa.
528
+
529
+ ## Licença
530
+
531
+ O UI Óptago é software livre, sob a **licença MIT** (veja [LICENSE](./LICENSE)). Qualquer pessoa pode usar a biblioteca ou reproduzi-la: copiar, modificar, mesclar, publicar, distribuir, sublicenciar e vender cópias, em projetos pessoais ou comerciais, sem pedir permissão e sem pagar nada. A única condição é manter o aviso de copyright e o texto da licença nas cópias ou nas partes substanciais da biblioteca (os cabeçalhos de `ui-optago.css` e `ui-optago.js` já trazem o aviso). O software é fornecido "como está", sem garantia. O selo "Desenvolvido por Óptago" é opcional.