@jsweb/ui 1.2.8 → 1.3.1

package/README.md

@@ -28,21 +28,110 @@ npm i @jsweb/ui
 <script src="https://unpkg.com/@jsweb/ui"></script>
 ```
 
-## Diretivas Disponíveis (v0.1.0)
-
-O framework utiliza um sistema de atributos customizados para declaratividade no HTML.
-
-| Diretiva              | Descrição                                                                       | Exemplo                               |
-| :-------------------- | :------------------------------------------------------------------------------ | :------------------------------------ |
-| `ui:scope` / `:scope` | Define o objeto de estado para o elemento e seus filhos.                        | `<div :scope="{ count: 0 }">`         |
-| `ui:text` / `:text`   | Sincroniza o `textContent` com uma variável.                                    | `<span :text="count"></span>`         |
-| `:attr`               | Shorthand para bind de atributos HTML nativos.                                  | `<button :disabled="count > 10">`     |
-| `:class` / `:style`   | Bind dinâmico avançado para classes CSS e Estilos Inline (dicionários, arrays). | `<div :class="{ active: isActive }">` |
-| `@event`              | Shorthand para event listeners (com suporte a modificadores).                   | `<button @click.prevent="save">`      |
-| `$emit`               | Despacha CustomEvents a partir do escopo atual. (Exposto no contexto)           | `<button @click="$emit('custom')">`   |
-| `:bind`               | Two-way data binding para inputs, checkboxes, radios e selects.                 | `<input :bind="name">`                |
-| `ui:if` / `:if`       | Adiciona/Remove o elemento do DOM (via Comment Node placeholder).               | `<div :if="count > 0">`               |
-| `ui:for` / `:for`     | Renderiza uma lista de elementos a partir de um array.                          | `<li :for="item in items">`           |
+## Diretivas Disponíveis
+
+O framework utiliza um sistema de atributos customizados para declaratividade no HTML, suportando tanto o prefixo completo (`ui:`, `ui@`) quanto a sintaxe simplificada (`:`, `@`).
+
+| Diretiva     | Atalho     | Descrição                                                                         | Exemplo                                    |
+| :----------- | :--------- | :-------------------------------------------------------------------------------- | :----------------------------------------- |
+| `ui:scope`   | `:scope`   | Define o objeto de estado/contexto para o elemento e seus filhos.                 | `<div :scope="{ count: 0 }">`              |
+| `ui:text`    | `:text`    | Sincroniza o `textContent` com uma variável ou expressão.                         | `<span :text="count"></span>`              |
+| `ui:bind`    | `:bind`    | Two-way data binding para inputs, checkboxes, radios, selects e textarea.         | `<input :bind="name">`                     |
+| `ui:if`      | `:if`      | Renderização condicional no DOM (via Comment Node placeholder).                   | `<div :if="count > 0">`                    |
+| `ui:for`     | `:for`     | Renderiza listas com suporte a `in` e `of`, expondo `$index`.                     | `<li :for="item of items">`                |
+| `ui:key`     | `:key`     | Identificador único para reconciliação e reciclagem eficiente de nós DOM.         | `<li :for="item of items" :key="item.id">` |
+| `ui:class`   | `:class`   | Bind reativo para classes CSS (suporta String, Array ou Objeto booleano).         | `<div :class="{ active: isActive }">`      |
+| `ui:style`   | `:style`   | Bind reativo para estilos inline (recebe objeto chave/valor de propriedades CSS). | `<div :style="{ color: textColor }">`      |
+| `ui:ref`     | `:ref`     | Referencia elementos HTML indexados em um Map acessível via `$refs`.              | `<input :ref="myInput">`                   |
+| `ui:[attr]`  | `:[attr]`  | Bind de atributos HTML nativos (remove se falsy, ativa se booleano `true`).       | `<button :disabled="count > 10">`          |
+| `ui@[event]` | `@[event]` | Escuta eventos DOM nativos ou customizados (com suporte a modificadores).         | `<button @click.prevent="save">`           |
+
+### Modificadores de Eventos
+
+É possível encadear modificadores diretamente na sintaxe do evento (`@event.modificador` ou `ui@event.modificador`):
+
+- **`.prevent`**: Executa `$event.preventDefault()`.
+- **`.stop`**: Executa `$event.stopPropagation()`.
+- **`.self`**: Dispara o manipulador apenas quando o evento se originou exatamente no próprio elemento (`$event.target === el`).
+- **`.outside`**: Dispara quando o evento ocorre fora do elemento (ideal para fechar menus, modais e dropdowns). Gerencia o ouvinte no `document` com remoção e limpeza automáticas quando o elemento for desconectado.
+
+### Variáveis e Helpers de Contexto
+
+Dentro das expressões declaradas no HTML, o framework disponibiliza variáveis e métodos contextuais:
+
+- **`$refs`**: Objeto `Map` nativo contendo as referências registradas via `ui:ref` / `:ref`. Em elementos simples, retorna diretamente o elemento (`this.$refs.get('name')`). Em elementos dentro de loops `ui:for` com `:key`, retorna um `Map` aninhado indexado pela chave (`this.$refs.get('name').get($key)`).
+- **`$emit(eventName, detail?)`**: Função injetada em todos os escopos para disparar `CustomEvent` nativos (`bubbles: true`, `composed: true`), facilitando a comunicação com elementos ancestrais (`@custom-event="handle"`).
+- **`$event`**: Objeto nativo do evento disparado, disponível nas expressões de manipuladores (`@click="handle($event)"`). Se você referenciar apenas a função (`@click="handle"`), ela receberá `$event` automaticamente como primeiro argumento.
+- **`$index`**: Índice numérico (base 0) da iteração atual, disponível dentro do escopo de um `ui:for` / `:for`.
+
+### Detalhes de Comportamento
+
+#### Two-Way Data Binding (`ui:bind` / `:bind`)
+
+Detecta e trata o elemento de acordo com seu tipo:
+
+- **`input[type="checkbox"]`**: Sincroniza a propriedade booleana `checked` e atualiza no evento `change`.
+- **`input[type="radio"]`**: Marca como selecionado caso `el.value === String(valor)` e atualiza no evento `change`.
+- **`<select>`**: Sincroniza o `value` selecionado e escuta o evento `change`.
+- **`<input>` (texto, número, cor, data, etc.) e `<textarea>`**: Sincroniza `value` e atualiza em tempo real no evento `input`.
+
+#### Classes Dinâmicas (`ui:class` / `:class`)
+
+Atualiza classes reativas preservando classes estáticas já presentes no elemento:
+
+- **Objeto**: `:class="{ active: isActive, 'has-error': error }"`
+- **Array**: `:class="['badge', isActive && 'badge-success']"`
+- **String**: `:class="currentClass"`
+
+#### Reconciliação Inteligente em Listas (`ui:for` / `:for` e `ui:key` / `:key`)
+
+```html
+<ul>
+  <li :for="item of items" :key="item.id">
+    <span :text="$index"></span>: <strong :text="item.title"></strong>
+  </li>
+</ul>
+```
+
+Ao atualizar arrays reativos, o motor rastreia os nós pelo `:key` (ou índice por padrão) e reaproveita as instâncias existentes no DOM, evitando reflows desnecessários e mantendo estados de foco/interação.
+
+#### Referências a Elementos (`ui:ref` / `:ref` e `$refs`)
+
+O atributo `ui:ref` ou `:ref` indexa o elemento diretamente em um objeto `Map` acessível via `this.$refs` em métodos ou `$refs` em templates:
+
+1. **Uso Simples (Elemento Único)**:
+
+   ```html
+   <input type="text" :ref="searchBox" />
+   <button @click="$refs.get('searchBox').focus()">Focar</button>
+   ```
+
+   No código do componente:
+
+   ```javascript
+   this.$refs.get('searchBox').focus()
+   ```
+
+2. **Uso em Listas (`ui:for` com `:key`)**:
+   Quando utilizado dentro de um loop com `:key`, o framework cria automaticamente um `Map` aninhado mapeando cada elemento pela chave do item:
+
+   ```html
+   <ul>
+     <li :for="user of users" :key="user.id">
+       <input type="text" :value="user.name" :ref="userInput" />
+     </li>
+   </ul>
+   ```
+
+   Para resgatar o elemento de um item específico:
+
+   ```javascript
+   const input = this.$refs.get('userInput').get(user.id)
+   input?.focus()
+   ```
+
+3. **Limpeza Automática**:
+   Quando um elemento referenciado sai do DOM (seja por remoção do item em lista ou por `ui:if`), ele é desregistrado automaticamente do `Map`, evitando vazamentos de memória e referências a nós órfãos.
 
 ## Exemplo de Uso
 
@@ -85,6 +174,10 @@ O framework utiliza um sistema de atributos customizados para declaratividade no
 
 ### TypeScript / ESM
 
+#### Abordagem com Objeto Literal (`ThisType`)
+
+Graças ao utilitário `ThisType<T & ScopeContext>`, dentro dos métodos e _getters_ do objeto literal você tem autocomplete e tipagem estrita de `this`, incluindo as propriedades do objeto e os helpers `$refs` e `$emit`:
+
 ```typescript
 import { createScope, reactive, watch } from '@jsweb/ui'
 
@@ -92,17 +185,108 @@ const scope = reactive({
   count: 0,
   inc: 'Incremento',
   dec: 'Decremento',
+
+  get double() {
+    return this.count * 2
+  },
+
   increment() {
     this.count++
+    this.$emit('changed', this.count)
+    this.$refs.get('meuInput')?.focus()
   },
   decrement() {
     this.count--
   },
 })
 
-watch(() => scope.count, (newVal, oldVal) => {
-  console.log(`Contador mudou de ${oldVal} para ${newVal}`)
-})
+// Observa mudanças com suporte a tipagem genérica, oldValue/newValue e disparo imediato
+const unwatch = watch(
+  () => scope.count,
+  (newVal, oldVal) => {
+    console.log(`Contador mudou de ${oldVal} para ${newVal}`)
+  },
+  { immediate: true },
+)
+
+createScope('#container', { scope })
+```
+
+#### Abordagem Orientada a Objetos com a Classe `Scope`
+
+Você também pode utilizar classes TypeScript estendendo a classe base `Scope` fornecida pelo framework:
+
+```typescript
+import { createScope, reactive, Scope } from '@jsweb/ui'
+
+class ContadorScope extends Scope {
+  count = 0
+  inc = 'Incremento'
+  dec = 'Decremento'
+
+  get double() {
+    return this.count * 2
+  }
+
+  increment() {
+    this.count++
+    this.$emit('changed', this.count)
+    this.$refs.get('meuInput')?.focus()
+  }
+
+  decrement() {
+    this.count--
+  }
+
+  // É possível sobrescrever o método $emit se desejar lógica customizada:
+  protected override $emit(event: string, detail?: any) {
+    console.log(`[Contador] Evento disparado: ${event}`, detail)
+    super.$emit(event, detail)
+  }
+}
 
+const scope = reactive(new ContadorScope())
 createScope('#container', { scope })
 ```
+
+## API JavaScript / TypeScript
+
+### `createScope<T>(selectorOrElement, context?)`
+
+Inicializa e amarra a reatividade ao elemento DOM ou seletor especificado.
+
+- **`selectorOrElement`**: Seletor CSS (ex: `'#app'`, `'body'`) ou instância de `HTMLElement`.
+- **`context`**: Objeto inicial de contexto/estado compartilhado (opcional), tipado contextualmente com `ThisType<T & ScopeContext>`. Injeta automaticamente os helpers `$emit` e `$refs`.
+
+### `reactive(target)`
+
+Envolve um objeto ou array em um `Proxy` de reatividade de grão fino (_fine-grained_).
+
+- **Objeto Literal**: Tipado com `ThisType<T & ScopeContext>` para inferência e autocomplete de `this` (incluindo computeds via _getters_ e helpers contextuais `$refs`, `$emit` e `$el` prontos para uso sem necessidade de `?.`).
+- **Instâncias de Classes**: Suporta instâncias que estendem `Scope` ou classes POJO personalizadas.
+- **Arrays**: Intercepta métodos de mutação (`push`, `pop`, `splice`, etc.) e gerencia dependências de tamanho (`length`).
+- **Suporta reatividade profunda** (_deep reactivity_).
+
+### `Scope`
+
+Classe base utilitária para definição de escopos orientados a objetos em TypeScript. Já possui `$el` e `$refs` implementados como somente leitura e `$emit` com implementação padrão como método `protected`, permitindo sobrescrita (`override`) nas subclasses.
+
+```typescript
+export class Scope {
+  readonly $el: HTMLElement
+  protected readonly $refs: Map<string, any>
+  protected $emit(event: string, detail?: any): void
+  declare $index?: number
+  declare $key?: any
+  constructor(init?: Record<string, any>)
+}
+```
+
+### `watch<T>(source, callback, options?)`
+
+Observa alterações reativas e executa uma função de callback quando o valor mudar.
+
+- **`source`**: Objeto reativo completo ou função getter que retorna o valor a ser observado (ex: `() => state.count`).
+- **`callback`**: `(newValue: T, oldValue: T | undefined) => void`.
+- **`options`**: `{ immediate?: boolean }` para acionar a callback imediatamente na primeira execução.
+- **Retorno**: Função de cancelamento `stop()` que encerra a observação e limpa dependências.