arckode-ui 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,19 @@ Cambios entre versiones publicadas. Sigue [keepachangelog](https://keepachangelo
 
 ## [Unreleased]
 
+## [0.2.3] — 2026-05-23
+
+### Fixed
+- **Skills**: eliminada ambigüedad en el patrón de store. El patrón DEFAULT es ahora
+  signals al top-level del módulo (más limpio, sin traps). `useStore()` dentro de
+  callbacks queda como fallback explícito solo para cross-store dependency.
+- **Skills**: eliminada ambigüedad en comunicación hijo→padre. `emit + @event` es el
+  DEFAULT explícito. Callback como prop tiene criterio concreto: solo para primitivos
+  genéricos (Button, Input) sin semántica de negocio.
+- Versión en `§14` del SKILL principal actualizada de `v0.1.1` a `v0.2.2`.
+- Mismas correcciones aplicadas en `skills/SKILL.md` y `skills/components/SKILL.md`
+  (los sub-skills distribuidos con el paquete npm).
+
 ## [0.2.2] — 2026-05-23
 
 ### Fixed
@@ -94,7 +107,8 @@ Cambios entre versiones publicadas. Sigue [keepachangelog](https://keepachangelo
 - TypeScript declarations no se generaban (`vite-plugin-dts` faltaba) —
   arreglado en `0.2.2`.
 
-[Unreleased]: https://gitlab.com/underworf/arckode-ui/-/compare/v0.2.2...HEAD
+[Unreleased]: https://gitlab.com/underworf/arckode-ui/-/compare/v0.2.3...HEAD
+[0.2.3]: https://gitlab.com/underworf/arckode-ui/-/compare/v0.2.2...v0.2.3
 [0.2.2]: https://gitlab.com/underworf/arckode-ui/-/compare/v0.2.1...v0.2.2
 [0.2.1]: https://gitlab.com/underworf/arckode-ui/-/compare/v0.2.0...v0.2.1
 [0.2.0]: https://gitlab.com/underworf/arckode-ui/-/compare/v0.1.1...v0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arckode-ui",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "type": "module",
   "description": "Frontend framework con .ark SFCs, signals, file-system router y analyzer estático con sugerencias concretas de fix. Diseñado para máxima predictibilidad de output de IA.",
   "keywords": [

package/skills/SKILL.md

@@ -625,81 +625,60 @@ export default defineComponent({
 
 ## 7. STORE — estado global compartido
 
+### DEFAULT — signals declarados fuera del defineStore
+
+Usar SIEMPRE este patrón. Los signals viven al top-level del módulo y se pasan al store.
+Es TS-friendly, testeable, y no tiene traps de auto-referencia.
+
 ```typescript
 // stores/user.store.ts
 import { defineStore, signal, computed } from 'arckode-ui'
 
 interface UserDTO { id: string; name: string }
 
+// signals al top-level — accesibles directamente en getters/actions sin llamar useStore()
+const current  = signal<UserDTO | null>(null)
+const loading  = signal(false)
+const isLoggedIn = computed(() => current.value !== null)
+
 export const useUserStore = defineStore('user', {
-  state: {
-    current: signal<UserDTO | null>(null),
-    loading: signal(false),
-  },
-  getters: {
-    isLoggedIn: computed(() => useUserStore().state.current.value !== null),
-  },
+  state:   { current, loading },
+  getters: { isLoggedIn },
   actions: {
     async login(email: string, password: string) {
-      const store = useUserStore()
-      store.state.loading.value = true
+      loading.value = true
       // ...
     },
-    logout() { useUserStore().state.current.value = null },
+    logout() { current.value = null },
   },
 })
 ```
 
-### ⚠ Trap conocido del store — `useStore()` dentro de getters/actions
-
-El patrón `useUserStore()` dentro de getters/actions FUNCIONA porque cuando esos
-callbacks se ejecutan, el registry del store YA tiene la instancia registrada.
-Pero hay dos cosas a saber:
-
-1. **NO lo llames durante la DEFINICIÓN del objeto** — solo dentro del callback.
-   Si lo llamás afuera, el registry todavía no tiene la instancia y devuelve `undefined`
-   o tira error.
-
-   ```typescript
-   // ❌ MAL: useStore() en evaluación del valor del state
-   export const useStore = defineStore('x', {
-     state: {
-       current: useStore().getters.somethingElse,  // ← infinite loop / crash
-     },
-   })
-
-   // ✅ BIEN: useStore() solo dentro del callback (computed/function)
-   export const useStore = defineStore('x', {
-     state: { current: signal(null) },
-     getters: {
-       label: computed(() => useStore().state.current.value ?? 'anonymous'),
-     },
-   })
-   ```
-
-2. **Pattern alternativo más limpio**: declarar los signals fuera del defineStore
-   y referenciarlos directo. Evita el `useStore()` en absoluto:
-
-   ```typescript
-   // signals al top-level del módulo
-   const current = signal<UserDTO | null>(null)
-   const loading = signal(false)
-   const isLoggedIn = computed(() => current.value !== null)
-
-   export const useUserStore = defineStore('user', {
-     state: { current, loading },
-     getters: { isLoggedIn },
-     actions: {
-       async login(...) { loading.value = true; /* ... */ },
-       logout() { current.value = null },
-     },
-   })
-   ```
-
-   Esta forma es más TS-friendly (no requiere casts dentro de callbacks), más
-   testeable (los signals son inspeccionables sin invocar el store) y más legible.
-
-Uso en componente:
+### SI EL DEFAULT FALLA — `useStore()` dentro de getters/actions
+
+Cuándo usarlo: cuando un getter/action necesita acceder al state de OTRO store
+(cross-store dependency). Llamar `useOtroStore()` dentro del callback, nunca en la definición.
+
+```typescript
+// ✅ cross-store: OK dentro del callback
+actions: {
+  syncWithCart() {
+    const cart = useCartStore()          // ← dentro del callback, no en la definición
+    current.value = cart.state.owner.value
+  },
+},
+```
+
+⚠ **NUNCA** llamar `useStore()` fuera de un callback (nivel raíz del objeto state/getters/actions).
+```typescript
+// ❌ MAL: useStore() en la definición del state — crash, registry vacío
+export const useStore = defineStore('x', {
+  state: { ref: useStore().state.something },
+})
+```
+
+### Uso en componente
+
 ```typescript
 const userStore = useUserStore()
 return {
@@ -709,8 +688,6 @@ return {
 }
 ```
 
-**Patrón clave:** dentro de getters/actions, llamar `useUserStore()` para acceder al state. Es feo pero es la API real verificada en tests.
-
 ---
 
 ## 8. SERVICE — HTTP

package/skills/components/SKILL.md

@@ -122,7 +122,8 @@ Detalles:
 - El nombre del evento debe estar en `emits: []` (sino warning runtime)
 - Eventos en kebab-case obligatorio
 
-**Patrón alternativo (callback como prop):** sigue funcionando, útil cuando el child no tiene "ownership" del evento conceptualmente:
+**SI EL DEFAULT FALLA — callback como prop:** usar solo cuando el hijo es un primitivo genérico
+(Button, Input) que no tiene semántica de negocio y el padre necesita pasarle una función directamente.
 ```html
 <TaskForm :onSubmit="actions.handleCreate" :onCancel="actions.closeModal" />
 ```