ui-optago 1.2.3 → 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/ui-optago.d.ts ADDED
@@ -0,0 +1,204 @@
1
+ // Tipos da API global do UI Óptago 2.0 (window.OptagoUI). Licença MIT.
2
+ // A biblioteca é um script clássico: inclua ui-optago.js no <head> e use o
3
+ // objeto global. Este arquivo só descreve a API para o editor e o TypeScript.
4
+
5
+ export type OptagoToastType = 'success' | 'error' | 'warning' | 'info' | 'loading';
6
+ export type OptagoTheme = 'light' | 'dark' | 'system';
7
+
8
+ /** Valores de uma mensagem: por posição (`[3]`) ou por nome (`{ nome: 'Ana' }`). */
9
+ export type OptagoMessageArgs = ReadonlyArray<string | number> | Record<string, string | number>;
10
+
11
+ /** Textos traduzidos: chaves com ponto ou objetos aninhados (como um arquivo de idioma do CodeIgniter). */
12
+ export interface OptagoMessages { [key: string]: string | OptagoMessages; }
13
+
14
+ export interface OptagoToastOptions {
15
+ /** Tempo na tela, em ms (padrão: 4000). `0` mantém o toast até ser fechado. */
16
+ duration?: number;
17
+ /** Botão de ação dentro do toast, como "Desfazer". */
18
+ action?: { label: string; onClick?: () => void };
19
+ }
20
+
21
+ /** O elemento do toast, com dois métodos a mais. */
22
+ export interface OptagoToastElement extends HTMLDivElement {
23
+ update(message: string, type?: OptagoToastType, options?: number | OptagoToastOptions): void;
24
+ dismiss(): void;
25
+ }
26
+
27
+ export interface OptagoToast {
28
+ (message: string, type?: OptagoToastType, options?: number | OptagoToastOptions): OptagoToastElement;
29
+ /** Mostra "carregando" e troca para sucesso ou erro quando a Promise termina. */
30
+ promise<T>(promise: Promise<T>, texts?: {
31
+ loading?: string;
32
+ success?: string | ((result: T) => string);
33
+ error?: string | ((error: unknown) => string);
34
+ }): Promise<T>;
35
+ }
36
+
37
+ export interface OptagoConfirmOptions {
38
+ title?: string;
39
+ confirmText?: string;
40
+ cancelText?: string;
41
+ /** `false` usa o botão primário no lugar do de perigo. */
42
+ danger?: boolean;
43
+ }
44
+
45
+ export interface OptagoCommand {
46
+ label: string;
47
+ /** Palavras extras para a busca; não aparecem na tela. */
48
+ desc?: string;
49
+ /** Classes do ícone, ex.: "ph ph-plus". */
50
+ icon?: string;
51
+ href?: string;
52
+ run?: () => void;
53
+ }
54
+
55
+ export interface OptagoShortcut {
56
+ /** Ex.: "Ctrl+S", "Ctrl+Shift+P", "?". */
57
+ keys: string;
58
+ label: string;
59
+ run?: (event: KeyboardEvent) => void;
60
+ }
61
+
62
+ export interface OptagoEditorOptions {
63
+ /** Formato gravado no <textarea>. Padrão: o do atributo data-op-editor, ou "markdown". */
64
+ format?: 'markdown' | 'html';
65
+ /** Conteúdo inicial, no formato escolhido. Padrão: o valor do <textarea>. */
66
+ value?: string;
67
+ /** Altura, ex.: "320px". */
68
+ height?: string;
69
+ /** Opções repassadas ao Toast UI Editor. */
70
+ editor?: Record<string, unknown>;
71
+ }
72
+
73
+ export interface OptagoEditor {
74
+ /** A instância do Toast UI Editor. */
75
+ editor: unknown;
76
+ getHTML(): string;
77
+ getMarkdown(): string;
78
+ setHTML(html: string): void;
79
+ setMarkdown(markdown: string): void;
80
+ focus(): void;
81
+ destroy(): void;
82
+ }
83
+
84
+ /** Nomes das cores prontas das duas cores da marca. */
85
+ export type OptagoPalette = 'lime' | 'cyan' | 'blue' | 'violet' | 'rose' | 'orange' | 'teal' | 'yellow' | 'graphite';
86
+
87
+ /** Tokens soltos pela pessoa: `all` vale nos dois temas; `dark` e `light`, só no tema. Valor vazio ou `null` apaga. */
88
+ export interface OptagoTokens {
89
+ all: Record<string, string | null>;
90
+ dark: Record<string, string | null>;
91
+ light: Record<string, string | null>;
92
+ }
93
+
94
+ /**
95
+ * Opções de aparência (atributos `data-op-*` no `<html>`). `main` e `secondary` são as duas cores da marca
96
+ * (nomes antigos: `accent` e `cyan`) e aceitam uma cor pronta ou um hexadecimal.
97
+ */
98
+ export interface OptagoAppearance {
99
+ main: OptagoPalette | `#${string}`;
100
+ secondary: OptagoPalette | `#${string}`;
101
+ radius: 'sharp' | 'soft' | 'default' | 'round';
102
+ shape: 'pill' | 'round' | 'square';
103
+ font: 'default' | 'system' | 'serif' | 'mono';
104
+ text: 'sm' | 'default' | 'lg' | 'xl';
105
+ width: 'narrow' | 'default' | 'wide' | 'full';
106
+ aurora: 'off' | 'soft' | 'default';
107
+ surface: 'glass' | 'solid';
108
+ }
109
+
110
+ /** O que `OptagoUI.appearance()` aceita: as opções, os nomes antigos e `tokens` (objeto plano vale nos dois temas). */
111
+ export type OptagoAppearanceChanges = Partial<OptagoAppearance> & {
112
+ /** Nome antigo de `main`. */
113
+ accent?: OptagoAppearance['main'];
114
+ /** Nome antigo de `secondary`. */
115
+ cyan?: OptagoAppearance['secondary'];
116
+ tokens?: Record<string, string | null> | Partial<OptagoTokens>;
117
+ };
118
+
119
+ export interface OptagoUIApi {
120
+ readonly version: string;
121
+
122
+ // Idioma
123
+ /** Texto do dicionário, com os valores no lugar de `{0}`, `{nome}` e dos plurais. */
124
+ t(key: string, args?: OptagoMessageArgs | string | number): string;
125
+ /** Com um objeto, acrescenta traduções; sem argumento, devolve o dicionário em uso. */
126
+ locale(messages: OptagoMessages): OptagoUIApi;
127
+ locale(): Record<string, string>;
128
+
129
+ // Preferências
130
+ setTheme(theme: OptagoTheme): void;
131
+ toggleTheme(): void;
132
+ /** Sobrescreve tokens: `{ main: '#FF6B00' }` (ou o nome antigo `accent`) ou `{ '--op-radius': '6px' }`. */
133
+ customize(tokens: Record<string, string>): void;
134
+ /** Lê ou aplica as opções de aparência; a escolha fica salva no navegador. Devolve as opções em uso. */
135
+ appearance(changes?: OptagoAppearanceChanges): OptagoAppearance & { tokens: OptagoTokens };
136
+ /** Apaga a escolha salva e volta ao que a página definiu. Com `'tokens'`, apaga só os tokens soltos. */
137
+ resetAppearance(only?: 'tokens'): void;
138
+ /** Painel "Personalizar" (tema, cor de destaque, cantos, fonte, tamanho do texto...). */
139
+ customizer: { open(opener?: Element): void; close(): void };
140
+ setMotion(on: boolean): void;
141
+ toggleMotion(): void;
142
+ setPrivacy(on: boolean): void;
143
+ togglePrivacy(): void;
144
+ setDensity(mode: 'compact' | 'default'): void;
145
+
146
+ // Sidebar
147
+ toggleSidebar(): void;
148
+ toggleSidebarMobile(): void;
149
+ closeSidebarMobile(): void;
150
+
151
+ // Avisos
152
+ toast: OptagoToast;
153
+ /** Mensagem só para leitores de tela. */
154
+ announce(message: string): void;
155
+ showLoading(message?: string): void;
156
+ hideLoading(): void;
157
+ /** Tela de abertura com o logo animado. Por marcação, use `<div class="op-splash" data-op-splash>`. */
158
+ splash: {
159
+ show(message?: string, options?: { variant?: 'ripple' | 'draw' | 'orbit' | 'counter' | 'minimal'; exit?: 'fade' | 'up' | 'iris'; brand?: string }): void;
160
+ /** Só na variação `counter`: de 0 a 100. */
161
+ progress(value: number): void;
162
+ hide(): void;
163
+ };
164
+ setOffline(offline: boolean): void;
165
+ sessionWarning(options?: { seconds?: number; onExtend?: () => void; onExpire?: () => void }): { close(): void };
166
+
167
+ // Sobreposições
168
+ openModal(target: string | Element, opener?: Element): void;
169
+ closeModal(target: string | Element): void;
170
+ confirm(message: string, options?: OptagoConfirmOptions): Promise<boolean>;
171
+ commands(list: OptagoCommand[]): void;
172
+ openCommandPalette(): void;
173
+ shortcuts(list: OptagoShortcut[]): void;
174
+ openShortcuts(): void;
175
+
176
+ // Formulários
177
+ validate(form: string | HTMLFormElement): boolean;
178
+ setDirty(form: string | HTMLFormElement, dirty: boolean): void;
179
+ setStep(wizard: string | Element, index: number): void;
180
+ editor(target: string | Element, options?: OptagoEditorOptions): Promise<OptagoEditor>;
181
+
182
+ // Bibliotecas carregadas sob demanda
183
+ /** Devolve a instância do Tabulator. */
184
+ tabulator(target: string | Element, options?: Record<string, unknown>): Promise<unknown>;
185
+ /**
186
+ * Gráfico do Chart.js com o tema Óptago (carrega a biblioteca do CDN, se preciso).
187
+ * O segundo argumento é a configuração normal do Chart.js; o que você definir vence.
188
+ * Devolve a instância do Chart.js.
189
+ */
190
+ chart(target: string | Element, config: Record<string, unknown>): Promise<unknown>;
191
+ /** Devolve a instância do driver.js. */
192
+ tour(steps: Array<Record<string, unknown>>, options?: Record<string, unknown>): Promise<unknown>;
193
+
194
+ // Geral
195
+ /** Reaplica ARIA e nomes acessíveis. Só é preciso com data-op-observe="off". */
196
+ refresh(root?: Element | Document): void;
197
+ copyHTML(selector: string, feedbackButton?: Element): void;
198
+ toggleCode(selector: string, button: Element): void;
199
+ }
200
+
201
+ declare global {
202
+ interface Window { OptagoUI: OptagoUIApi; }
203
+ const OptagoUI: OptagoUIApi;
204
+ }