lkd-web-kit 0.10.6 → 0.10.8

package/src/distributed-skills/lkd-rhf-lkd-forms/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: lkd-rhf-lkd-forms
+description: Crear y revisar formularios, filtros, campos controlados, integraciones con React Hook Form, validaciones Zod, reglas superRefine, botones de submit y patrones Form* de lkd-web-kit. Usar cuando Codex trabaje en interfaces de formularios, filtros, wrappers de campos, schemas, valores iniciales, mapeo de payloads, flujos de submit o comportamiento de validación en proyectos que usan React Hook Form, Zod y lkd-web-kit.
+---
+
+# Formularios RHF + lkd-web-kit
+
+Usar este skill para formularios, filtros y campos controlados construidos con React Hook Form, Zod y `lkd-web-kit`.
+
+## Workflow obligatorio
+
+1. Leer primero la documentación de formularios del proyecto: `docs/lkd-web-kit.md` o el equivalente local.
+2. Reutilizar la familia `Form*` existente antes de crear algo nuevo:
+   `Form`, `FormTextInput`, `FormSelect`, `FormMultiSelect`, `FormTextarea`,
+   `FormNumberInput`, `FormMonthPickerInput`, `FormCheckbox`,
+   `FormRadioGroup`, `FormSubmitButton` y wrappers cercanos del proyecto.
+3. Importar primero desde `lkd-web-kit`. Usar wrappers locales solo cuando el proyecto ya los tenga y agreguen estilos o comportamiento propio.
+4. No crear un wrapper nuevo si el kit o el proyecto ya tienen un campo equivalente.
+5. Para formularios con validación, usar `useForm` con `zodResolver(schema)`.
+6. Pasar `mode` solo cuando la API del componente lo soporte. No inventar props.
+
+## Estructura recomendada
+
+- Mantener formularios triviales inline.
+- Cuando un formulario mapea datos de API o construye un payload, separar lo repetitivo:
+  - `schema`: objeto Zod y tipo inferido.
+  - `createDefaultValues`: datos de API/dominio a valores del formulario.
+  - `createPayload`: valores del formulario a payload de API.
+- Usar `z.input<typeof schema>` para defaults cuando haya transforms o preprocess.
+- Usar `z.infer<typeof schema>` para datos ya validados en submit.
+- Colocar el código privado junto a la ruta o feature, salvo que sea realmente compartido.
+
+## Validaciones con Zod
+
+- Poner reglas de campo en el schema base.
+- No poner mensajes textuales en reglas base de Zod como `min(1, "Texto")`; usar la configuración global de errores o la capa de traducciones del proyecto.
+- Usar `superRefine` para reglas cruzadas entre campos y reglas de negocio.
+- En `superRefine`, asociar el issue al campo que el usuario puede corregir usando `path`.
+- Permitir mensajes custom en `superRefine` cuando el proyecto no tenga un mapeo de códigos para esa regla de negocio.
+- Preferir `ctx.addIssue(...)`; usar `ctx.issues.push(...)` solo si ya es el patrón local.
+
+## Campos y filtros
+
+- Todo input que modifique estado de React Hook Form debe ser un componente `Form*`.
+- Usar `My*` o inputs Mantine solo para UI standalone fuera de React Hook Form.
+- Preferir componentes de campo del proyecto, como `NameField` o `StatusField`, cuando ya provean `name`, labels, opciones traducidas o carga de datos.
+- Los filtros siguen el mismo patrón: `useForm` + `Form` + `Form*`.
+- El submit de filtros puede actualizar query params, estado local o estado del padre según el proyecto; no agregar una librería de estado solo por un filtro.
+- Si un campo client lee catálogos o datos cacheados, verificar que la página o el padre carguen esos datos según la convención del proyecto.
+
+## Submit y errores
+
+- Usar `FormSubmitButton` para acciones de submit. No usar aliases como `FormButtonSubmit` salvo que el proyecto realmente los exporte.
+- Dejar que `FormSubmitButton` maneje el loading de submit mediante React Hook Form.
+- En submits async, mostrar la notificación de éxito o error esperada por el proyecto.
+- En `catch`, mostrar la notificación de error y luego hacer `throw error` para que el wrapper del formulario pueda reaccionar visualmente.
+- Recortar o normalizar valores en el límite donde se arma el payload de API, no en handlers sueltos de campos.
+
+## Antipatrones
+
+- No usar `register` directamente para campos ya cubiertos por `Form*`.
+- No duplicar wrappers tipo `FormTextInput` o `FormSelect`.
+- No usar `any`; tipar valores del formulario desde el schema.
+- No agregar helpers custom de validación cuando Zod ya cubre la regla.
+- No mezclar campos Mantine no controlados dentro de un formulario de React Hook Form.
+- No agregar dependencias nuevas para estado de formulario, validación de campos o filtros comunes.
+
+## Ejemplos mínimos
+
+Formulario de edición:
+
+```tsx
+"use client";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import {
+  FormSelect,
+  FormSubmitButton,
+  FormTextInput,
+} from "lkd-web-kit";
+import { useForm } from "react-hook-form";
+import z from "zod";
+import Form from "src/components/form/Form";
+
+const editSchema = z.object({
+  name: z.string().min(1),
+  status: z.string().nullable(),
+});
+
+type EditValues = z.infer<typeof editSchema>;
+
+const createDefaultValues = (item: { name: string; status: string | null }): EditValues => ({
+  name: item.name,
+  status: item.status,
+});
+
+const createPayload = (data: EditValues) => ({
+  name: data.name.trim(),
+  status: data.status || undefined,
+});
+
+export function EditItemForm({ item }: { item: { name: string; status: string | null } }) {
+  const methods = useForm<EditValues>({
+    defaultValues: createDefaultValues(item),
+    resolver: zodResolver(
+      editSchema.superRefine((data, ctx) => {
+        if (data.status === "published" && data.name.trim().length < 3) {
+          ctx.addIssue({
+            code: "custom",
+            message: "El nombre es demasiado corto para publicar",
+            path: ["name"],
+          });
+        }
+      }),
+    ),
+  });
+
+  return (
+    <Form
+      methods={methods}
+      onSubmit={async (data) => {
+        try {
+          await updateItem(createPayload(data));
+        } catch (error) {
+          showErrorNotification();
+          throw error;
+        }
+      }}
+    >
+      <FormTextInput name="name" label="Nombre" />
+      <FormSelect
+        name="status"
+        label="Estado"
+        data={[
+          { value: "draft", label: "Borrador" },
+          { value: "published", label: "Publicado" },
+        ]}
+      />
+      <FormSubmitButton>Guardar</FormSubmitButton>
+    </Form>
+  );
+}
+```
+
+Filtro:
+
+```tsx
+"use client";
+
+import { FormSelect, FormSubmitButton, FormTextInput } from "lkd-web-kit";
+import { useForm } from "react-hook-form";
+import Form from "src/components/form/Form";
+
+type FilterValues = {
+  search: string;
+  status: string | null;
+};
+
+export function ItemFilters({
+  onApply,
+}: {
+  onApply: (values: FilterValues) => void;
+}) {
+  const methods = useForm<FilterValues>({
+    defaultValues: {
+      search: "",
+      status: null,
+    },
+  });
+
+  return (
+    <Form methods={methods} onSubmit={onApply}>
+      <FormTextInput name="search" label="Buscar" />
+      <FormSelect
+        name="status"
+        label="Estado"
+        data={[
+          { value: "draft", label: "Borrador" },
+          { value: "published", label: "Publicado" },
+        ]}
+      />
+      <FormSubmitButton>Aplicar</FormSubmitButton>
+    </Form>
+  );
+}
+```

package/.agents/skills/create-nextjs-page/SKILL.md

@@ -1,104 +0,0 @@
----
-name: create-nextjs-page
-description: Crear o refactorizar paginas de Next.js App Router manteniendo app limpio y delegando la UI a componentes de pagina en src/components/pages. Usar cuando Codex deba crear page.tsx, mover UI fuera de app, organizar subcomponentes privados de una pagina, envolver paginas con PageProviders o normalizar nombres/rutas de componentes Page en proyectos que consumen lkd-web-kit.
----
-
-# Create Next.js Page
-
-Usar este skill para crear o refactorizar paginas de Next.js App Router en proyectos que usan `lkd-web-kit`.
-
-## Lectura obligatoria
-
-1. Leer la documentacion relevante de Next.js antes de tocar rutas. Si existe `node_modules/next/dist/docs/`, usarla como fuente local.
-2. Leer la documentacion local del proyecto sobre `lkd-web-kit`, componentes compartidos y patrones de UI si existe.
-3. Revisar una pagina cercana antes de editar para respetar imports, providers, carga de datos, traducciones y convenciones del proyecto.
-
-## Regla principal
-
-- Mantener `app` como capa de routing de Next.js.
-- En `app`, dejar solo `layout.tsx`, `page.tsx` y archivos especiales de Next.js cuando correspondan: `not-found.tsx`, `loading.tsx`, `error.tsx`, `route.ts`, `template.tsx`, `default.tsx` o metadata files.
-- No colocar vistas, subcomponentes, hooks privados, helpers de UI, schemas, columnas de tabla ni componentes de pagina dentro de `app`.
-- Colocar la UI real de cada ruta en `src/components/pages`.
-
-## Estructura de pagina
-
-Para una pagina simple:
-
-```txt
-src/app/[locale]/(app-layout)/development/page.tsx
-src/components/pages/app/DevelopmentPage.tsx
-```
-
-Para una pagina con subcomponentes privados:
-
-```txt
-src/app/[locale]/(app-layout)/development/page.tsx
-src/components/pages/app/DevelopmentPage/index.tsx
-src/components/pages/app/DevelopmentPage/Header.tsx
-src/components/pages/app/DevelopmentPage/helpers.ts
-```
-
-- Usar archivo plano `{PageName}Page.tsx` si el componente es de una pieza.
-- Usar carpeta `{PageName}Page/index.tsx` si hay subcomponentes, helpers, schemas o piezas privadas.
-- Mantener dentro de esa carpeta solo lo privado de esa pagina.
-- Mover a componentes compartidos solo cuando exista reutilizacion real.
-
-## PageProviders
-
-Cada `page.tsx` debe retornar el componente Page envuelto con `PageProviders`.
-
-```tsx
-import PageProviders from "src/app/PageProviders";
-import DevelopmentPage from "src/components/pages/app/DevelopmentPage";
-
-const Page = async () => {
-  return (
-    <PageProviders>
-      <DevelopmentPage />
-    </PageProviders>
-  );
-};
-
-export default Page;
-```
-
-- Usar el import real de `PageProviders` del proyecto si difiere del ejemplo.
-- Pasar a `PageProviders` solo las props que existan y sean necesarias en ese proyecto.
-- Mantener en `page.tsx` solo responsabilidades de entrypoint: params, metadata, fetch server-side, redirects/notFound y providers.
-- No duplicar providers dentro del componente de pagina salvo que el proyecto tenga una razon documentada.
-
-## Mapeo de area
-
-Derivar `{area}` desde el route group principal cuando exista:
-
-- `(app-layout)` -> `app`
-- `(admin-layout)` -> `admin`
-- `(home-layout)` -> `home`
-- `(developer-layout)` -> `developer`
-- `(agency-layout)` -> `agency`
-
-Regla general:
-
-- Si el route group termina en `-layout`, quitar ese sufijo.
-- Si no termina en `-layout`, usar el nombre limpio del group sin parentesis.
-- Si no hay route group claro, usar el primer segmento estable de la ruta.
-- Ignorar `[locale]`, route groups y segmentos dinamicos para elegir el area.
-
-## Nombres
-
-- Usar PascalCase y sufijo `Page`.
-- Para rutas estaticas, usar el ultimo segmento estable: `(app-layout)/development/page.tsx` -> `DevelopmentPage`.
-- Para rutas dinamicas, usar el ultimo segmento estatico util y agregar `DetailPage`: `development/[development_slug]/page.tsx` -> `DevelopmentDetailPage`.
-- Para rutas dinamicas anidadas, preferir el ultimo segmento estatico util: `development/[development_slug]/property/[property_slug]` -> `PropertyDetailPage`.
-- Si el nombre colisiona o pierde contexto, anteponer el segmento padre: `DevelopmentPropertyDetailPage`.
-- No incluir nombres de route groups, `[locale]` ni nombres de parametros como `Slug` salvo que haga falta para evitar ambiguedad real.
-
-## Checklist
-
-- `app` queda limpio y sin UI privada.
-- `page.tsx` importa un componente desde `src/components/pages/{area}`.
-- `page.tsx` envuelve siempre con `PageProviders`.
-- Las props de `PageProviders` corresponden al proyecto actual, no a otro consumidor.
-- El componente de pagina no usa `any`.
-- Los subcomponentes privados viven junto a la pagina, no en `app`.
-- Se ejecuta una verificacion focalizada cuando el cambio toca codigo de aplicacion.

package/.agents/skills/create-nextjs-page/agents/openai.yaml

@@ -1,3 +0,0 @@
-display_name: Create Next.js Page
-short_description: Create clean Next.js App Router pages.
-default_prompt: Create or refactor a Next.js App Router page using the clean PageProviders pattern.

package/.agents/skills/mantine-combobox/SKILL.md

@@ -1,73 +0,0 @@
----
-name: mantine-combobox
-description: >
-  Build custom dropdown/select/autocomplete/multiselect components using Mantine's Combobox
-  primitives. Use this skill when: (1) creating a new custom select-like component with
-  Combobox primitives, (2) building a searchable dropdown, (3) implementing a multi-select
-  or tags input variant, (4) customizing option rendering, (5) adding custom filtering logic,
-  or (6) any task involving useCombobox, Combobox.Target, Combobox.Option, or Combobox.Dropdown.
----
-
-# Mantine Combobox Skill
-
-## Overview
-
-`Combobox` provides low-level primitives for building any select-like UI. The built-in
-`Select`, `Autocomplete`, and `TagsInput` components are all built on top of it.
-
-## Core Workflow
-
-### 1. Create the store
-
-```tsx
-const combobox = useCombobox({
-  onDropdownClose: () => combobox.resetSelectedOption(),
-  onDropdownOpen: () => combobox.selectFirstOption(),
-});
-```
-
-### 2. Render structure
-
-```tsx
-<Combobox store={combobox} onOptionSubmit={handleSubmit}>
-  <Combobox.Target>
-    <InputBase
-      component="button"
-      pointer
-      rightSection={<Combobox.Chevron />}
-      onClick={() => combobox.toggleDropdown()}
-    >
-      {value || <Input.Placeholder>Pick value</Input.Placeholder>}
-    </InputBase>
-  </Combobox.Target>
-  <Combobox.Dropdown>
-    <Combobox.Options>
-      {options.map((item) => (
-        <Combobox.Option value={item} key={item}>{item}</Combobox.Option>
-      ))}
-    </Combobox.Options>
-  </Combobox.Dropdown>
-</Combobox>
-```
-
-### 3. Handle submit
-
-```tsx
-const handleSubmit = (val: string) => {
-  setValue(val);
-  combobox.closeDropdown();
-};
-```
-
-## Target Types
-
-| Scenario | Use |
-|---|---|
-| Button trigger (no text input) | `<Combobox.Target targetType="button">` |
-| Input trigger | `<Combobox.Target>` (default) |
-| Pills + separate input (multi-select) | `<Combobox.DropdownTarget>` + `<Combobox.EventsTarget>` |
-
-## References
-
-- **[`references/api.md`](references/api.md)** — Full API: `useCombobox` options and store, all sub-component props, CSS variables, Styles API selectors
-- **[`references/patterns.md`](references/patterns.md)** — Code examples: searchable select, multi-select with pills, groups, custom rendering, clear button, form integration

package/.agents/skills/mantine-combobox/references/api.md

@@ -1,199 +0,0 @@
-# Combobox API Reference
-
-## Table of Contents
-- [useCombobox hook](#usecombobox-hook)
-- [Combobox (root)](#combobox-root)
-- [Sub-components](#sub-components)
-- [CSS variables & Styles API](#css-variables--styles-api)
-
----
-
-## useCombobox hook
-
-```tsx
-const combobox = useCombobox(options?: UseComboboxOptions);
-```
-
-**Options:**
-```ts
-interface UseComboboxOptions {
-  defaultOpened?: boolean;
-  opened?: boolean;
-  onOpenedChange?: (opened: boolean) => void;
-  onDropdownClose?: (eventSource: 'keyboard' | 'mouse' | 'unknown') => void;
-  onDropdownOpen?: (eventSource: 'keyboard' | 'mouse' | 'unknown') => void;
-  loop?: boolean;           // Default: true — keyboard nav wraps at boundaries
-  scrollBehavior?: ScrollBehavior; // Default: 'instant'
-}
-```
-
-**Returned store:**
-```ts
-interface ComboboxStore {
-  // Dropdown state
-  dropdownOpened: boolean;
-  openDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;
-  closeDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;
-  toggleDropdown(eventSource?: 'keyboard' | 'mouse' | 'unknown'): void;
-
-  // Option keyboard navigation
-  selectActiveOption(): string | null;
-  selectFirstOption(): string | null;
-  selectNextOption(): string | null;
-  selectPreviousOption(): string | null;
-  resetSelectedOption(): void;
-  clickSelectedOption(): void;
-  updateSelectedOptionIndex(
-    target?: 'active' | 'selected' | number,
-    options?: { scrollIntoView?: boolean }
-  ): void;
-
-  // Programmatic focus
-  focusSearchInput(): void;
-  focusTarget(): void;
-}
-```
-
----
-
-## Combobox (root)
-
-```tsx
-<Combobox
-  store={combobox}              // required — ComboboxStore from useCombobox()
-  onOptionSubmit={fn}           // (value: string, optionProps) => void
-  size="sm"                     // MantineSize | string, default: 'sm'
-  dropdownPadding={4}           // number, default: 4
-  resetSelectionOnOptionHover   // boolean
-  readOnly                      // boolean — disables all interactions
-  // + all Popover props (position, offset, width, withinPortal, etc.)
-/>
-```
-
----
-
-## Sub-components
-
-### Combobox.Target
-```tsx
-<Combobox.Target
-  targetType="input"          // 'button' | 'input', default: 'input'
-  withKeyboardNavigation      // boolean, default: true
-  withAriaAttributes          // boolean, default: true
-  withExpandedAttribute       // boolean, default: false
-  autoComplete="off"          // string
->
-  {/* single child — the trigger element */}
-</Combobox.Target>
-```
-
-Use `targetType="button"` when the trigger is a button (Space key toggles dropdown).
-
-### Combobox.DropdownTarget
-Marks the element used for dropdown positioning when separate from the keyboard events target. Used together with `Combobox.EventsTarget` in multi-select/pills patterns.
-
-### Combobox.EventsTarget
-Receives keyboard events for dropdown navigation. Used alongside `Combobox.DropdownTarget` when the typing input is nested inside the trigger (e.g. inside `PillsInput`).
-
-### Combobox.Dropdown
-```tsx
-<Combobox.Dropdown hidden={false}>
-  {/* dropdown content */}
-</Combobox.Dropdown>
-```
-
-Use `hidden` to hide without unmounting (preserves scroll position).
-
-### Combobox.Options
-```tsx
-<Combobox.Options labelledBy="some-label-id">
-  {/* Combobox.Option or Combobox.Group elements */}
-</Combobox.Options>
-```
-
-### Combobox.Option
-```tsx
-<Combobox.Option
-  value="react"       // string | number, required
-  active={false}      // visually marks as selected; used by selectActiveOption()
-  disabled={false}
->
-  React
-</Combobox.Option>
-```
-
-### Combobox.Search
-Built-in search input, wired to keyboard navigation. Renders sticky at top of dropdown.
-
-```tsx
-<Combobox.Search
-  value={search}
-  onChange={(e) => setSearch(e.currentTarget.value)}
-  placeholder="Search..."
-  withAriaAttributes      // boolean, default: true
-  withKeyboardNavigation  // boolean, default: true
-  // + all Input props
-/>
-```
-
-### Combobox.Empty
-```tsx
-<Combobox.Empty>Nothing found</Combobox.Empty>
-```
-
-### Combobox.Group
-```tsx
-<Combobox.Group label="Frontend">
-  <Combobox.Option value="react">React</Combobox.Option>
-</Combobox.Group>
-```
-
-### Combobox.Header / Combobox.Footer
-```tsx
-<Combobox.Header>Custom header</Combobox.Header>
-<Combobox.Footer>Custom footer</Combobox.Footer>
-```
-
-### Combobox.Chevron
-```tsx
-<Combobox.Chevron size="sm" error={error} color="blue" />
-```
-
-### Combobox.ClearButton
-```tsx
-<Combobox.ClearButton onClear={() => setValue(null)} />
-```
-
-### Combobox.HiddenInput
-```tsx
-<Combobox.HiddenInput
-  value={value}           // string | number | (string | number)[] | null
-  valuesDivider=","       // string, default: ','
-  name="myField"
-  form="myForm"
-/>
-```
-
----
-
-## CSS variables & Styles API
-
-### CSS variables (set on root element)
-| Variable | Description |
-|---|---|
-| `--combobox-option-fz` | Option font size (driven by `size` prop) |
-| `--combobox-option-padding` | Option padding (driven by `size` prop) |
-| `--combobox-padding` | Dropdown padding (driven by `dropdownPadding`, default 4px) |
-
-### Styles API selectors
-| Selector | Element |
-|---|---|
-| `dropdown` | Dropdown container |
-| `options` | Options listbox |
-| `option` | Individual option |
-| `search` | Search input |
-| `empty` | Nothing found message |
-| `header` | Dropdown header |
-| `footer` | Dropdown footer |
-| `group` | Group container |
-| `groupLabel` | Group label text |