@jsweb/ui 1.2.8 → 1.3.1

package/dist/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+Todas as alterações notáveis neste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) e este projeto adere ao [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+---
+
+## [1.3.1] - 2026-09-24
+
+### Added
+
+- **Tipagem Contextual `ThisType<T & ScopeContext>`**: Inclusão de `ThisType` na assinatura de `reactive` e `createScope`, fornecendo autocomplete e tipagem estrita de `this` em métodos e _getters_ de objetos literais, com acesso direto a `$refs`, `$emit` e `$el` como propriedades não-opcionais.
+- **Classe Base `Scope` e Interface `ScopeContext`**: Exportação da classe utilitária `Scope` e da interface `ScopeContext` para suporte nativo e tipado a arquiteturas orientadas a objetos (`class MyScope extends Scope`). Na classe `Scope`, `$el` e `$refs` são propriedades somente leitura (com `$refs` mantendo sua instância original de Map viva) e `$emit` como método `protected` com disparo nativo em `$el`, permitindo sobrescrita (`override`) nas subclasses.
+- **Tipagem Genérica em `watch<T>`**: Aprimoramento da assinatura de `watch` para inferência de tipos em `newValue` e `oldValue`.
+- **Skill Aberta para Agentes de IA (`SKILL.md`)**: Arquivo [`SKILL.md`](./SKILL.md) na raiz do projeto para integração direta com agentes de IA via `npx skills add @jsweb/ui`.
+- **Skill de Workspace (`update-documentation`)**: Skill em [`.agents/skills/update-documentation/SKILL.md`](./.agents/skills/update-documentation/SKILL.md) para auditoria e sincronização contínua de documentação.
+- **Histórico Semântico de Versões (`CHANGELOG.md`)**: Arquivo [`CHANGELOG.md`](./CHANGELOG.md) baseado no padrão Keep a Changelog.
+- **Automação de Build e Metadados**: Atualização do script [`publish.js`](./publish.js) para sincronizar `SKILL.md` e `CHANGELOG.md` na pasta `dist/` durante o build do pacote NPM.
+- **Script de Publicação**: Adicionado script `npm run push` no `package.json` para automatizar o envio de tags git e publicação no NPM.
+
+---
+
+## [1.3.0] - 2026-09-18
+
+### Added
+
+- **Diretiva `:ref` / `ui:ref`**: Indexação reativa de elementos DOM no helper contextual `$refs` (`Map`).
+- **Refs Aninhadas em Listas**: Em loops `:for` com `:key`, `$refs.get(name)` retorna um `Map` aninhado indexado pela chave do item (`$key`).
+- **Cleanup Automático de Refs**: Remoção de referências do `$refs` quando nós são destruídos por `:if` ou `:for`.
+- **Modificador de Evento `.outside`**: Captura cliques e eventos fora do elemento (ideal para modais e dropdowns) com remoção automática do listener no `document` ao desconectar o nó.
+- **Reconciliação e Reciclagem de Nós DOM em Listas**: Rastreamento de nós pelo `:key` em `:for`, reaproveitando instâncias existentes e evitando reflows desnecessários.
+
+---
+
+## [1.2.8] - 2026-05-20
+
+### Refactored
+
+- Limpeza de imports e remoção de código não utilizado no parser e no core.
+
+---
+
+## [1.2.7] - 2026-05-20
+
+### Added
+
+- Suporte aprimorado à função `watch` com observação profunda (_deep traverse_) e suporte a `{ immediate: true }`.
+
+---
+
+## [1.2.6] - 2026-05-20
+
+### Added
+
+- **Diretiva `:class` / `ui:class`**: Bind reativo de classes CSS via objeto booleano, array ou string, preservando classes estáticas.
+- **Diretiva `:style` / `ui:style`**: Bind reativo para estilos inline com limpeza automática de propriedades removidas.
+
+---
+
+## [1.2.5] - 2026-05-18
+
+### Fixed
+
+- Tratamento de erros nas funções de avaliação (`evaluate` e `evaluateEvent`).
+- Ajuste no contexto `this` para getters em propriedades computadas.
+
+---
+
+## [1.2.4] - 2026-05-18
+
+### Added
+
+- Suporte automático a propriedades computadas via _getters_ nativos (`get prop() { ... }`) em objetos envolvidos por `reactive()`.
+
+---
+
+## [1.2.3] - 2026-05-18
+
+### Added
+
+- Script de automação `preversion` no `package.json` para executar o build antes de gerar versões.
+
+### Refactored
+
+- Remoção da função legada `hasDirective`.
+
+---
+
+## [1.2.2] - 2026-05-18
+
+### Refactored
+
+- Simplificação do logging de avisos no motor de avaliação.
+
+---
+
+## [1.2.1] - 2026-05-17
+
+### Added
+
+- Script `publish.js` para geração de pacote mínimo em `dist/` e automação de publicação NPM.
+
+---
+
+## [1.2.0] - 2026-05-09
+
+### Added
+
+- Exportação da API `watch(source, callback, options?)` para observação de estados reativos.
+- Reorganização dos exports principais (`createScope`, `reactive`, `watch`).
+
+---
+
+## [1.1.0] - 2026-05-09
+
+### Added
+
+- Injeção do helper contextual `$emit(eventName, detail?)` para disparo de `CustomEvent` nativos (`bubbles: true`, `composed: true`).
+- Padronização do nome do método de montagem para `createScope`.
+
+---
+
+## [1.0.0] - 2026-05-07
+
+### Added
+
+- Primeiro lançamento estável do `@jsweb/ui`.
+- Motor de reatividade de grão fino baseado em `Proxy` e `ReactiveEffect` (sem Virtual DOM).
+- Avaliador de expressões dinâmicas em sandbox.
+- Diretivas fundamentais: `ui:scope`, `ui:text`, `ui:bind`, `ui:if`, `ui:for`, `ui:[attr]` e `ui@[event]`.
+- Modificadores de evento `.prevent`, `.stop` e `.self`.
+- Distribuição dual: ESM para bundlers e UMD/Standalone para uso direto via CDN.

package/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jsweb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/README.md

@@ -0,0 +1,292 @@
+# @jsweb/ui
+
+## Introdução
+
+O `@jsweb/ui` é um micro-framework frontend escrito em TypeScript, projetado para ser uma ferramenta leve, rápida e flexível para o desenvolvimento de interfaces de usuário. Ele combina a reatividade moderna de frameworks como Vue 3 (Composition API) com a simplicidade de uso direto no HTML, semelhante ao Alpine.js.
+
+### Pilares Arquiteturais
+
+- **Sem Virtual DOM**: Utiliza reatividade de grão fino (Fine-grained reactivity) via `Proxy` para atualizações diretas no DOM real.
+- **Distribuição Dupla**:
+  - **Standalone**: Arquivo único (IIFE/UMD) para inclusão via `<script src="...">`.
+  - **Module**: Pacote ESM com exports nomeados para suporte a Tree-Shaking.
+- **Contexto Híbrido**: Suporta definição de estado via Objetos Literais (POJOs) ou Classes TypeScript.
+- **Template Engine**: Baseado em atributos customizados no HTML (`ui:*` para diretivas e `ui@*` para eventos, com shorthands `@`, `:`).
+  - Suporte completo a **modificadores de eventos** encadeados (`.prevent`, `.stop`, `.self`, `.outside`).
+
+## Instalação
+
+### NPM
+
+```bash
+npm i @jsweb/ui
+```
+
+### CDN
+
+```html
+<script src="https://unpkg.com/@jsweb/ui"></script>
+```
+
+## 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
+
+### HTML
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>JS Web UI</title>
+    <script src="https://unpkg.com/@jsweb/ui"></script>
+    <script>
+      const scope = {
+        count: 0,
+        inc: 'Incremento',
+        dec: 'Decremento',
+        increment() {
+          this.count++
+        },
+        decrement() {
+          this.count--
+        },
+      }
+
+      jsweb.ui.createScope('body', { scope })
+    </script>
+  </head>
+  <body>
+    <div ui:scope="scope">
+      <h1>JS Web UI</h1>
+      <p>Contador: <span ui:text="count"></span></p>
+      <button ui:text="inc" @click="increment()"></button>
+      <button ui:text="dec" @click="decrement()"></button>
+    </div>
+  </body>
+</html>
+```
+
+### 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'
+
+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--
+  },
+})
+
+// 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.