@griddo/ax 12.9.0 → 12.9.1-rc.0

package/src/components/ConfigPanel/Form/ConnectedField/PageConnectedField/TemplateManager/index.tsx

@@ -7,7 +7,7 @@ import Field from "../Field";
 
 import * as S from "./style";
 
-export const TemplateManager = (props: IProps): JSX.Element => {
+export const TemplateManager = (props: IProps) => {
 	const {
 		template,
 		selectedTab,
@@ -52,13 +52,8 @@ export const TemplateManager = (props: IProps): JSX.Element => {
 		const isComputedField = Object.prototype.hasOwnProperty.call(field, "computed");
 
 		const addedModules: string[] = modulesDataPacks.reduce((acc: string[], current: any) => {
-			if (
-				current.sectionList &&
-				current.sectionList[template.component] &&
-				current.sectionList[template.component].includes(key) &&
-				!acc.includes(current.id)
-			) {
-				return [...acc, current.id];
+			if (current.sectionList?.[template.component]?.includes(key) && !acc.includes(current.id)) {
+				acc.push(current.id);
 			}
 			return acc;
 		}, []);
@@ -84,57 +79,56 @@ export const TemplateManager = (props: IProps): JSX.Element => {
 	return (
 		<>
 			{isConfig && templateFields && !isForm && <S.Title>Template Options</S.Title>}
-			{templateFields &&
-				templateFields
-					.filter((templateField: ISchemaField) => {
-						const isHidden = templateField.hidden || (isForm && !templateField.overwrite);
-						return !isHidden;
-					})
-					.map((templateField: ISchemaField, index: number) => {
-						const {
-							whiteList,
-							categories,
-							key,
-							fieldObjKey,
-							mappedField,
-							currentContent,
-							handleUpdate,
-							error,
-							readonly,
-							disabledField,
-						} = getFieldProps(templateField);
+			{templateFields
+				?.filter((templateField: ISchemaField) => {
+					const isHidden = templateField.hidden || (isForm && !templateField.overwrite);
+					return !isHidden;
+				})
+				.map((templateField: ISchemaField, index: number) => {
+					const {
+						whiteList,
+						categories,
+						key,
+						fieldObjKey,
+						mappedField,
+						currentContent,
+						handleUpdate,
+						error,
+						readonly,
+						disabledField,
+					} = getFieldProps(templateField);
 
-						return (
-							<Field
-								whiteList={whiteList}
-								key={`${objKey}.${key}${index}`}
-								objKey={fieldObjKey}
-								field={mappedField}
-								selectedContent={currentContent}
-								goTo={goTo}
-								updateValue={handleUpdate}
-								pages={pages}
-								actions={actions}
-								site={site}
-								disabled={disabled || disabledField}
-								activatedModules={activatedModules}
-								isTemplateActivated={isTemplateActivated}
-								categories={categories}
-								error={error}
-								deleteError={deleteError}
-								errors={errors}
-								theme={theme}
-								moduleCopy={moduleCopy}
-								availableDataPacks={availableDataPacks}
-								template={template}
-								setHistoryPush={setHistoryPush}
-								lang={lang}
-								readonly={readonly}
-								scrollEditorID={scrollEditorID}
-								languages={languages}
-							/>
-						);
-					})}
+					return (
+						<Field
+							whiteList={whiteList}
+							key={`${objKey}.${key}${index}`}
+							objKey={fieldObjKey}
+							field={mappedField}
+							selectedContent={currentContent}
+							goTo={goTo}
+							updateValue={handleUpdate}
+							pages={pages}
+							actions={actions}
+							site={site}
+							disabled={disabled || disabledField}
+							activatedModules={activatedModules}
+							isTemplateActivated={isTemplateActivated}
+							categories={categories}
+							error={error}
+							deleteError={deleteError}
+							errors={errors}
+							theme={theme}
+							moduleCopy={moduleCopy}
+							availableDataPacks={availableDataPacks}
+							template={template}
+							setHistoryPush={setHistoryPush}
+							lang={lang}
+							readonly={readonly}
+							scrollEditorID={scrollEditorID}
+							languages={languages}
+						/>
+					);
+				})}
 		</>
 	);
 };

package/src/hooks/shortcuts/README.md

@@ -0,0 +1,515 @@
+# Keyboard Shortcuts
+
+Sistema declarativo de atajos de teclado para Griddo AX. Registra shortcuts en componentes React con cleanup automático, soporte de secuencias (chords) y resolución de conflictos por prioridad.
+
+```
+import { useShortcuts, shortcut } from "@ax/hooks";
+```
+
+---
+
+## Tabla de contenidos
+
+1. [Inicio rápido](#inicio-rápido)
+2. [Conceptos clave](#conceptos-clave)
+3. [API base: `useShortcuts` + `shortcut`](#api-base)
+4. [Presets](#presets)
+5. [Global shortcuts (safety net)](#global-shortcuts)
+6. [Prioridad](#prioridad)
+7. [Secuencias de teclas (chords)](#secuencias-de-teclas-chords)
+8. [Scoped shortcuts (ref)](#scoped-shortcuts)
+9. [Iframe bridge](#iframe-bridge)
+10. [Comportamiento en inputs](#comportamiento-en-inputs)
+11. [Arquitectura](#arquitectura)
+12. [Referencia de archivos](#referencia-de-archivos)
+13. [Recetas](#recetas)
+
+---
+
+## Inicio rápido
+
+```tsx
+import { useSaveShortcut } from "@ax/hooks";
+
+function MyEditor() {
+  const canSave = /* ... */;
+
+  useSaveShortcut(() => {
+    saveDocument();
+  }, canSave);
+
+  return <div>...</div>;
+}
+```
+
+Eso es todo. `mod+s` queda registrado, funciona dentro de inputs, y se desregistra automáticamente al desmontar el componente.
+
+---
+
+## Conceptos clave
+
+### `mod` = Cmd (Mac) / Ctrl (Windows/Linux)
+
+Usa `"mod"` en vez de `"ctrl"` o `"meta"`. El engine detecta la plataforma automáticamente.
+
+### Cleanup automático
+
+Los shortcuts se desregistran cuando el componente se desmonta o cuando cambian las dependencias del hook. No necesitas hacer cleanup manual.
+
+### Prioridad
+
+Cuando dos shortcuts compiten por la misma combinación de teclas, gana el de mayor prioridad. Si un handler retorna `false`, el engine pasa al siguiente en la cola.
+
+---
+
+## API base
+
+### `shortcut(id, keys, handler, overrides?)`
+
+Crea un objeto `ShortcutConfig`. No registra nada por sí solo — es solo un builder.
+
+```tsx
+shortcut("save", "mod+s", () => handleSave());
+shortcut("delete", "del", () => handleDelete());
+shortcut("find", "mod+shift+f", () => openSearch());
+shortcut("goto-list", "g l", () => navigateToList()); // chord: pulsa g, luego l
+```
+
+**Parámetros:**
+
+| Param       | Tipo                                      | Descripción                                              |
+| ----------- | ----------------------------------------- | -------------------------------------------------------- |
+| `id`        | `string`                                  | Identificador único (ej. `"save"`, `"close:modal"`)      |
+| `keys`      | `string`                                  | Combinación de teclas (ver [sintaxis](#sintaxis-de-keys)) |
+| `handler`   | `(event: KeyboardEvent) => void \| false` | Callback. Retorna `false` para no hacer `preventDefault`  |
+| `overrides` | `object` (opcional)                       | Ver tabla abajo                                          |
+
+**Overrides:**
+
+| Campo          | Tipo      | Default     | Descripción                                              |
+| -------------- | --------- | ----------- | -------------------------------------------------------- |
+| `allowInInput` | `boolean` | `false`     | Si `true`, funciona dentro de `<input>`, `<textarea>`, etc |
+| `priority`     | `number`  | `0`         | Mayor = más prioridad en conflictos                       |
+| `enabled`      | `boolean` | `true`      | `false` desactiva sin desregistrar                        |
+| `description`  | `string`  | `undefined` | Texto descriptivo (para debug o UI de shortcuts)          |
+
+### Sintaxis de keys
+
+```
+"mod+s"         → Cmd+S / Ctrl+S
+"shift+alt+n"   → Shift+Alt+N
+"escape"        → Escape
+"del"           → Delete
+"mod+shift+z"   → Cmd+Shift+Z / Ctrl+Shift+Z
+"g l"           → Chord: pulsa G, luego L (ver sección de chords)
+```
+
+Modificadores disponibles: `mod`, `shift`, `alt`.
+
+---
+
+### `useShortcuts(shortcuts, options?)`
+
+Registra un array de shortcuts en el engine. Es la API de bajo nivel.
+
+```tsx
+useShortcuts([
+  shortcut("bold", "mod+b", () => toggleBold()),
+  shortcut("italic", "mod+i", () => toggleItalic()),
+  shortcut("underline", "mod+u", () => toggleUnderline()),
+]);
+```
+
+**Options:**
+
+| Campo     | Tipo                    | Default    | Descripción                                       |
+| --------- | ----------------------- | ---------- | ------------------------------------------------- |
+| `enabled` | `boolean`               | `true`     | Desregistra todos los shortcuts cuando es `false`  |
+| `ref`     | `RefObject<HTMLElement>` | `window`   | Elemento donde escuchar keydown (ver [ref](#scoped-shortcuts)) |
+
+> **Nota sobre `enabled`:** Cuando es `false`, los shortcuts se **desregistran por completo**.
+> Esto significa que el browser default no se previene. Si necesitas bloquear el browser
+> default incluso cuando el shortcut no está activo (ej. `mod+s` → Save As), usa
+> `useGlobalShortcuts()` en el root (ver [Global shortcuts](#global-shortcuts)).
+
+---
+
+## Presets
+
+Hooks preconfigurados para shortcuts comunes. Encapsulan la combinación de teclas, el id y las opciones — solo pasas el handler.
+
+### `useSaveShortcut(handler, enabled?)`
+
+```tsx
+useSaveShortcut(() => {
+  isPublished ? publishChanges() : saveDraft();
+}, canSave);
+```
+
+- Tecla: `mod+s`
+- `allowInInput`: siempre `true`
+- Id: `"save"`
+
+### `useEscapeShortcut(handler, enabled?)`
+
+```tsx
+useEscapeShortcut(() => {
+  closePanel();
+}, isPanelOpen);
+```
+
+- Tecla: `Escape`
+- `allowInInput`: siempre `true`
+- Id: `"escape"`
+
+### `useUndoRedoShortcuts(onUndo, onRedo, enabled?)`
+
+```tsx
+useUndoRedoShortcuts(
+  () => dispatch(undo()),
+  () => dispatch(redo()),
+  isEditing,
+);
+```
+
+- Teclas: `mod+z` / `mod+shift+z`
+- `allowInInput`: siempre `true`
+- Ids: `"undo"`, `"redo"`
+
+---
+
+## Global shortcuts
+
+`useGlobalShortcuts()` es un safety net que se monta **una vez en el root de la app**
+(`App/index.tsx`). Registra shortcuts con prioridad baja (`-1`) que solo hacen
+`preventDefault` para bloquear defaults del navegador.
+
+```tsx
+// App/index.tsx — ya está configurado
+const App = (props: IProps) => {
+  useGlobalShortcuts();
+  // ...
+};
+```
+
+### Cómo funciona
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Usuario pulsa Cmd+S                                     │
+│                                                         │
+│  ┌─ ShortcutEngine (prioridad descendente) ───────────┐ │
+│  │                                                     │ │
+│  │  1. useSaveShortcut (priority: 0) ← si está        │ │
+│  │     montado, ejecuta el handler del componente      │ │
+│  │                                                     │ │
+│  │  2. useGlobalShortcuts (priority: -1) ← fallback   │ │
+│  │     si ningún componente lo maneja, solo hace       │ │
+│  │     preventDefault (bloquea Save As)                │ │
+│  │                                                     │ │
+│  └─────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Escenarios
+
+| Ruta/estado            | `mod+s` lo maneja...     | Resultado                |
+| ---------------------- | ------------------------ | ------------------------ |
+| PageEditor montado     | `useSaveShortcut` (p:0)  | Guarda la página         |
+| PageEditor con `enabled=false` | `useGlobalShortcuts` (p:-1) | Bloquea Save As, no hace nada más |
+| Cualquier otra ruta    | `useGlobalShortcuts` (p:-1) | Bloquea Save As          |
+
+---
+
+## Prioridad
+
+El engine despacha shortcuts por **prioridad descendente**. El primero que matchea gana y hace `preventDefault` + `stopPropagation`. Si su handler retorna `false`, el engine continúa al siguiente.
+
+```tsx
+// Este shortcut SIEMPRE gana sobre otro "mod+s" con priority < 10
+shortcut("save:critical", "mod+s", handler, { priority: 10 });
+```
+
+**Valores de referencia:**
+
+| Nivel      | Valor | Uso                                      |
+| ---------- | ----- | ---------------------------------------- |
+| Global     | `-1`  | Safety nets (ej. `useGlobalShortcuts`)   |
+| Default    | `0`   | Shortcuts normales de componente          |
+| Override   | `> 0` | Modales, overlays que deben ganar siempre |
+
+### Ejemplo: modal que captura Escape
+
+```tsx
+function ConfirmModal({ isOpen, onClose }) {
+  // priority: 10 — gana sobre cualquier otro Escape
+  useShortcuts(
+    [shortcut("close:confirm-modal", "escape", () => onClose(), { priority: 10 })],
+    { enabled: isOpen },
+  );
+
+  return isOpen ? <div>...</div> : null;
+}
+```
+
+---
+
+## Secuencias de teclas (chords)
+
+Un chord es una secuencia de teclas que se pulsan una tras otra (no simultáneamente). Se definen separando combinaciones con espacio:
+
+```tsx
+shortcut("goto:list", "g l", () => navigateTo("/list"));
+// Pulsa G, luego L (en menos de 1 segundo)
+
+shortcut("goto:settings", "g s", () => navigateTo("/settings"));
+// Pulsa G, luego S
+```
+
+### Cómo funciona
+
+1. Pulsas `G` → el engine detecta que hay un chord en progreso y hace `preventDefault`
+2. Tienes **1 segundo** para pulsar `L`
+3. Si pulsas `L` a tiempo → se ejecuta el handler
+4. Si pulsas otra tecla o pasa el timeout → el chord se cancela
+
+### Chords con modificadores
+
+```tsx
+shortcut("debug:panel", "mod+k mod+d", () => openDebugPanel());
+// Cmd+K, luego Cmd+D
+```
+
+---
+
+## Scoped shortcuts
+
+Por defecto, los shortcuts escuchan en `window`. Puedes limitarlos a un elemento específico con `ref`:
+
+```tsx
+function TextEditor() {
+  const editorRef = useRef<HTMLDivElement>(null);
+
+  useShortcuts(
+    [
+      shortcut("bold", "mod+b", () => toggleBold()),
+      shortcut("italic", "mod+i", () => toggleItalic()),
+    ],
+    { ref: editorRef },
+  );
+
+  return <div ref={editorRef} tabIndex={0}>...</div>;
+}
+```
+
+Los shortcuts con ref solo se disparan cuando el evento se origina dentro de ese elemento. Gracias a `stopPropagation`, si el scoped shortcut matchea, no llega a los shortcuts globales en `window`.
+
+---
+
+## Iframe bridge
+
+Los eventos `keydown` dentro de un `<iframe>` no llegan al `window` del padre — el browser los confina al documento del iframe. Esto significa que shortcuts como `mod+s` no se disparan si el foco está en el iframe de preview.
+
+Para resolverlo, el sistema usa un puente de dos hooks que conectan el iframe con el engine del padre vía `postMessage`:
+
+### `useForwardShortcutKeys()` (lado iframe)
+
+Se usa dentro del iframe (ej. `FramePreview`). Escucha `keydown` y reenvía los eventos relevantes al padre.
+
+```tsx
+// FramePreview/index.tsx
+import { useForwardShortcutKeys } from "@ax/hooks";
+
+const FramePreview = () => {
+  useForwardShortcutKeys();
+  // ...
+};
+```
+
+**Qué reenvía:** Eventos con `metaKey`/`ctrlKey` o `Escape`.
+
+**Qué no reenvía:** Shortcuts de clipboard (`mod+c`, `mod+v`, `mod+x`, `mod+a`) para que funcionen normalmente en el iframe.
+
+### `useIframeShortcutBridge()` (lado padre)
+
+Se usa una vez en el root de la app, junto a `useGlobalShortcuts()`. Escucha los mensajes del iframe y re-despacha un `KeyboardEvent` sintético en `window`, donde el `ShortcutEngine` lo procesa normalmente.
+
+```tsx
+// App/index.tsx — ya está configurado
+const App = (props: IProps) => {
+  useGlobalShortcuts();
+  useIframeShortcutBridge();
+  // ...
+};
+```
+
+### Flujo
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Usuario pulsa Cmd+S dentro del iframe                        │
+│                                                              │
+│  ┌─ Iframe (FramePreview) ──────────────────────────────┐   │
+│  │  useForwardShortcutKeys()                             │   │
+│  │    → captura keydown                                  │   │
+│  │    → preventDefault (bloquea Save As en el iframe)    │   │
+│  │    → postMessage({ type: "shortcut-keydown", ... })   │   │
+│  └───────────────────────────────────────────────────────┘   │
+│                          │                                   │
+│                          ▼                                   │
+│  ┌─ Parent (App) ────────────────────────────────────────┐   │
+│  │  useIframeShortcutBridge()                            │   │
+│  │    → recibe message                                   │   │
+│  │    → window.dispatchEvent(new KeyboardEvent(...))     │   │
+│  │                                                       │   │
+│  │  ShortcutEngine                                       │   │
+│  │    → procesa el evento como cualquier otro keydown    │   │
+│  │    → useSaveShortcut handler se ejecuta               │   │
+│  └───────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Comportamiento en inputs
+
+Por defecto, los shortcuts **no se disparan** cuando el foco está en:
+
+- `<input>`
+- `<textarea>`
+- `<select>`
+- Elementos con `contentEditable`
+
+**Excepciones:**
+
+1. **`allowInInput: true`** — El shortcut funciona en cualquier contexto. Todos los presets lo activan.
+2. **`Escape`** — Siempre funciona en inputs, incluso sin `allowInInput`. Es una decisión de UX: Escape se usa para cerrar/cancelar y nunca produce texto.
+
+```tsx
+// Funciona siempre, incluso dentro de un input
+shortcut("save", "mod+s", handler, { allowInInput: true });
+
+// Solo funciona fuera de inputs
+shortcut("delete", "del", handler);
+
+// Escape siempre funciona (caso especial del engine)
+shortcut("close", "escape", handler);
+```
+
+---
+
+## Arquitectura
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Componente React                                            │
+│                                                              │
+│  useShortcuts([...])     ← Hook (registra/desregistra)       │
+│       │                                                      │
+│       │  usa ref-based handlers para evitar stale closures   │
+│       ▼                                                      │
+│  shortcutEngine.register(config, target)                     │
+│       │                                                      │
+│       │  un solo listener `keydown` por target               │
+│       ▼                                                      │
+│  ┌─ ShortcutEngine ──────────────────────────────────────┐   │
+│  │                                                        │   │
+│  │  keydown event                                         │   │
+│  │    → recopila shortcuts del target                     │   │
+│  │    → ordena por prioridad (desc)                       │   │
+│  │    → itera: el primero que matchea, gana               │   │
+│  │    → execute(): handler() + preventDefault + stopProp  │   │
+│  │    → si handler retorna false: continúa al siguiente   │   │
+│  │                                                        │   │
+│  └────────────────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Un solo listener por target
+
+El engine **no** crea un `addEventListener` por shortcut. Mantiene un solo listener por cada target (`window`, o un ref de elemento). Cuando llega un `keydown`, recorre los shortcuts registrados en ese target ordenados por prioridad.
+
+Esto garantiza que:
+
+- La resolución de prioridad funciona correctamente
+- No hay race conditions entre listeners independientes
+- El cleanup es eficiente (el listener se remueve solo cuando el último shortcut del target se desregistra)
+
+---
+
+## Referencia de archivos
+
+| Archivo            | Responsabilidad                                              |
+| ------------------ | ------------------------------------------------------------ |
+| `types.ts`         | Tipos: `KeyCombo`, `ModifierKey`, `ShortcutConfig`, `UseShortcutsOptions` |
+| `engine.ts`        | `ShortcutEngine` (singleton), `parseShortcut`, matching de teclas |
+| `useShortcuts.ts`  | Hook base `useShortcuts` + builder `shortcut()` |
+| `presets.ts`       | Hooks preconfigurados: `useSaveShortcut`, `useEscapeShortcut`, `useUndoRedoShortcuts`, `useGlobalShortcuts`, `useIframeShortcutBridge`, `useForwardShortcutKeys` — lado iframe del bridge |
+| `index.ts`         | Barrel export |
+
+---
+
+## Recetas
+
+### Shortcut condicional
+
+```tsx
+const isAdmin = usePermission("admin");
+
+useShortcuts([
+  shortcut("admin:panel", "mod+shift+a", () => openAdminPanel()),
+], { enabled: isAdmin });
+```
+
+### Múltiples shortcuts en un componente
+
+```tsx
+useShortcuts([
+  shortcut("save", "mod+s", handleSave, { allowInInput: true }),
+  shortcut("close", "escape", handleClose),
+  shortcut("search", "mod+k", handleSearch, { allowInInput: true }),
+  shortcut("delete", "del", handleDelete),
+]);
+```
+
+### Shortcut que no previene el default del browser
+
+Si necesitas que el browser siga procesando la tecla después de tu handler, retorna `false`:
+
+```tsx
+shortcut("log-typing", "mod+a", (event) => {
+  analytics.track("select-all");
+  return false; // deja que el browser haga Select All
+});
+```
+
+### Combinar preset + shortcuts custom
+
+```tsx
+function PageEditor() {
+  useSaveShortcut(() => savePage(), canSave);
+  useEscapeShortcut(() => closePanel(), isPanelOpen);
+
+  // Shortcuts adicionales específicos de este componente
+  useShortcuts([
+    shortcut("preview", "mod+shift+p", () => togglePreview()),
+    shortcut("publish", "mod+shift+enter", () => publish()),
+  ]);
+}
+```
+
+### Modal con Escape de alta prioridad
+
+```tsx
+function DeleteConfirmModal({ isOpen, onConfirm, onCancel }) {
+  useShortcuts(
+    [
+      shortcut("cancel:delete", "escape", () => onCancel(), { priority: 10 }),
+      shortcut("confirm:delete", "enter", () => onConfirm(), { priority: 10 }),
+    ],
+    { enabled: isOpen },
+  );
+
+  // ...
+}
+```