@jsweb/ui 1.3.0 → 1.3.1

package/.agents/skills/update-documentation/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: update-documentation
+description: >-
+  Audits recent codebase changes in @jsweb/ui (src/, package.json, config files) and synchronizes all documentation files (README.md, PROJECT.md, SKILL.md, and CHANGELOG.md). Use this skill whenever the user asks to update, synchronize, or refresh documentation, or after adding/modifying directives, reactivity mechanisms, APIs, event modifiers, or releasing new versions.
+---
+
+# Update Documentation Skill (@jsweb/ui)
+
+This skill guides the agent through auditing codebase changes and systematically synchronizing all project documentation files (`README.md`, `PROJECT.md`, `SKILL.md`, `CHANGELOG.md`) to reflect the latest APIs, directives, modifiers, release notes, and architectural behaviors.
+
+---
+
+## Target Documentation Files
+
+| File                                                               | Audience                     | Purpose                                                                                                                                 | Language             |
+| :----------------------------------------------------------------- | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
+| [`README.md`](file:///d:/Projetos/github/jsweb/ui/README.md)       | Developers & End Users       | Public GitHub/NPM documentation, quickstart, installation, directives reference table, and usage examples.                              | Portuguese / English |
+| [`PROJECT.md`](file:///d:/Projetos/github/jsweb/ui/PROJECT.md)     | Maintainers & Architecture   | Technical specification, core engine mechanics (Reactivity, Evaluator, Parser), architectural pillars, and requirements.                | Portuguese           |
+| [`SKILL.md`](file:///d:/Projetos/github/jsweb/ui/SKILL.md)         | AI Coding Agents             | Operational knowledge base installed via `npx skills add @jsweb/ui`, defining rules, directives, APIs, patterns, and agent constraints. | English              |
+| [`CHANGELOG.md`](file:///d:/Projetos/github/jsweb/ui/CHANGELOG.md) | All (Users, Maintainers, AI) | Curated chronological log of notable changes (Added, Changed, Deprecated, Removed, Fixed, Security) adhering to Keep a Changelog.       | Portuguese           |
+
+---
+
+## Workflow: Step-by-Step Procedure
+
+```mermaid
+flowchart TD
+    A["1. Inspect Git Changes & Source Code"] --> B["2. Compare Source with Current Docs"]
+    B --> C["3. Update README.md"]
+    B --> D["4. Update PROJECT.md"]
+    B --> E["5. Update SKILL.md"]
+    B --> F["6. Update CHANGELOG.md"]
+    C & D & E & F --> G["7. Verify Build & Copy with npm run build"]
+    G --> H["8. Report Summary to User"]
+```
+
+### Step 1: Inspect Changes and Current Source
+
+1. Check git status and recent diffs:
+   ```bash
+   git status
+   git diff HEAD
+   ```
+2. Inspect the core implementation files in `src/`:
+   - [`src/reactivity.ts`](file:///d:/Projetos/github/jsweb/ui/src/reactivity.ts): Check `reactive()`, `watch()`, `effect()`, `ReactiveEffect`, tracking, trigger behavior, bypassed types, or computed handling.
+   - [`src/parser.ts`](file:///d:/Projetos/github/jsweb/ui/src/parser.ts): Check directives (`:scope`, `:text`, `:bind`, `:if`, `:for`, `:key`, `:class`, `:style`, `:ref`, `:[attr]`, `@[event]`), event modifiers (`.prevent`, `.stop`, `.self`, `.outside`), and context helpers (`$refs`, `$emit`, `$index`, `$key`).
+   - [`src/evaluator.ts`](file:///d:/Projetos/github/jsweb/ui/src/evaluator.ts): Check expression sandboxing, `evaluate()`, and `evaluateEvent()`.
+   - [`src/index.ts`](file:///d:/Projetos/github/jsweb/ui/src/index.ts): Check public exports and global window attachments (`window.jsweb.ui`).
+   - [`package.json`](file:///d:/Projetos/github/jsweb/ui/package.json): Check version bumps, dependencies, entry points, or scripts.
+
+### Step 2: Identify Discrepancies Across Documentation
+
+Check whether any of the following changed:
+
+- **New or changed directives**: Did the syntax, prefix, or behavior change?
+- **New or changed event modifiers**: Are there new modifiers (e.g. `.debounce`, `.throttle`, `.once`) or modifications to existing ones?
+- **Reactivity enhancements**: Changes to deep reactivity, collections, watch options, or computed getters?
+- **API signatures**: Changes to parameters, options, or return types for `createScope`, `reactive`, or `watch`?
+- **Context helpers**: Any newly exposed helper (like `$parent`, `$root`, `$dispatch`, etc.)?
+- **Distribution / Build**: Changes to UMD/ESM paths, global variable name (`jsweb.ui`), or CDN URLs?
+
+### Step 3: Synchronize Each Documentation File
+
+#### A. Updating `README.md`
+
+- Keep the directive summary table up to date with exact syntax, shorthand, and clear examples.
+- Update code snippets demonstrating CDN standalone usage and ESM bundler usage.
+- Ensure the event modifiers and `$refs` / `$emit` section matches actual runtime behavior.
+- Document any breaking changes or version upgrades clearly.
+
+#### B. Updating `PROJECT.md`
+
+- Update the Technical Specifications (Section 3: Reatividade, Avaliador, Parser).
+- Keep Section 4 (Sintaxe e Diretivas) aligned with the exact implementation in `parser.ts`.
+- Document any architectural decisions (e.g., memory management, cleanup hooks, node recycling).
+
+#### C. Updating `SKILL.md` (Root)
+
+- Ensure YAML frontmatter `description` contains comprehensive trigger keywords.
+- Update the API Reference section with precise TypeScript signatures and return types.
+- Ensure the Template Directives reference accurately describes:
+  - Form controls supported by `:bind` (input types, select, checkbox, radio).
+  - Array and reconciliation behavior of `:for` and `:key`.
+  - Class and style object/array evaluation rules.
+  - `$refs` behavior (single element vs. nested `Map` in keyed loops).
+  - Event modifiers and their exact execution flow.
+- Maintain the "Critical Rules for AI Coding Agents" section (DOs and DON'Ts).
+
+#### D. Updating `CHANGELOG.md`
+
+- Adhere strictly to [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) format.
+- Group changes under `[Unreleased]` (or the specific version header if tagging/bumping version):
+  - `### Added` for new features or capabilities.
+  - `### Changed` for changes in existing functionality.
+  - `### Deprecated` for soon-to-be removed features.
+  - `### Removed` for now removed features.
+  - `### Fixed` for any bug fixes.
+  - `### Security` in case of vulnerabilities.
+- Provide concise, user-focused descriptions with code references.
+
+### Step 4: Validate Formatting and Build
+
+1. Format all modified files with Prettier:
+   ```bash
+   npm run format
+   ```
+2. Run the build to ensure type safety and that `publish.js` syncs `README.md`, `LICENSE`, `SKILL.md`, and `CHANGELOG.md` to `dist/`:
+   ```bash
+   npm run build
+   ```
+3. Verify that `dist/README.md`, `dist/SKILL.md`, and `dist/CHANGELOG.md` contain the updated contents.
+
+### Step 5: Report to User
+
+Present a concise summary of:
+
+- Which files were updated ([README.md](file:///d:/Projetos/github/jsweb/ui/README.md), [PROJECT.md](file:///d:/Projetos/github/jsweb/ui/PROJECT.md), [SKILL.md](file:///d:/Projetos/github/jsweb/ui/SKILL.md), [CHANGELOG.md](file:///d:/Projetos/github/jsweb/ui/CHANGELOG.md)).
+- Specific sections added, modified, or removed in each file.
+- Confirmation that `npm run build` and `npm run format` passed cleanly.
+
+---
+
+## Documentation Checklist
+
+When updating documentation, verify each of these items:
+
+- [ ] All directives in `parser.ts` are listed in both long form (`ui:*`) and shorthand (`:*`).
+- [ ] All event modifiers supported in `processEventBinding` are documented.
+- [ ] `$refs` behavior is accurately described (Map instance; nested Map in `:for` loops with `:key`).
+- [ ] `$emit` parameters and CustomEvent details (`bubbles: true`, `composed: true`) are correct.
+- [ ] Code snippets use valid modern JavaScript/TypeScript syntax.
+- [ ] `CHANGELOG.md` has all notable modifications recorded under `[Unreleased]` or version tag.
+- [ ] Version numbers in examples or text match `package.json`.
+- [ ] Prettier formatting is applied (`npm run format`).
+- [ ] `npm run build` succeeds and copies updated files to `dist/`.

package/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/PROJECT.md

@@ -10,7 +10,7 @@
 - **Dual Distribution:**
   - **Standalone:** Arquivo único (IIFE/UMD) para inclusão via `<script src="...">`.
   - **Module:** Pacote ESM com exports nomeados para suporte a Tree-Shaking.
-- **Hybrid Context:** Suporte a definição de estado via Objetos Literais (POJOs) ou Classes TypeScript.
+- **Hybrid Context:** Suporte a definição de estado via Objetos Literais (POJOs) tipados contextualmente via `ThisType<T & ScopeContext>` ou Classes TypeScript estendendo a classe base `Scope`.
 - **Template Engine:** Baseado em atributos customizados no HTML (`ui:*` para diretivas e `ui@*` para eventos, com shorthands `@`, `:`).
 
 ## 3. Especificações do Motor (Core)
@@ -25,7 +25,8 @@
 - **Lifecycle:** Deve ser possível criar efeitos que reajam a mudanças no ciclo de vida do componente.
 - **Cleanup:** Deve ser possível limpar os efeitos quando os componentes forem removidos do DOM.
 - **Watchers:** Implementado via API `watch`, permitindo reagir a mudanças em propriedades com acesso ao valor anterior/novo e disparo imediato (`immediate`).
-- **Computed:** Deve ser possível criar propriedades computadas que reajam a mudanças em propriedades específicas do estado.
+- **Computed:** Deve ser possível criar propriedades computadas que reajam a mudanças em propriedades específicas do estado (via _getters_ nativos).
+- **TypeScript First DX:** Tipagem estrita de `this` via `ThisType<T & ScopeContext>` para objetos literais e classe utilitária `Scope` para POJOs orientados a objetos.
 - **Composition API:** Deve ser possível usar a Composition API para criar efeitos e reatividade e aninhar efeitos e reatividade em outros efeitos e reatividade.
 
 ### B. Avaliador de Expressões (The Evaluator)

package/README.md

@@ -174,6 +174,10 @@ O atributo `ui:ref` ou `:ref` indexa o elemento diretamente em um objeto `Map` a
 
 ### 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'
 
@@ -181,15 +185,22 @@ 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 oldValue/newValue e disparo imediato opcional
+// Observa mudanças com suporte a tipagem genérica, oldValue/newValue e disparo imediato
 const unwatch = watch(
   () => scope.count,
   (newVal, oldVal) => {
@@ -201,27 +212,81 @@ const unwatch = watch(
 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(selectorOrElement, context?)`
+### `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). Injeta automaticamente o helper `$emit` no escopo.
+- **`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_).
 
-- Suporta reatividade profunda (_deep reactivity_).
-- Intercepta mutações em arrays (`push`, `pop`, `splice`, etc.) e mutações de propriedades em objetos.
+- **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(source, callback, options?)`
+### `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: any, oldValue: any) => void`.
+- **`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.