lkd-web-kit 0.10.2 → 0.10.4

package/.agents/skills/mantine-custom-components/references/patterns.md

@@ -0,0 +1,431 @@
+# Custom Component Patterns
+
+## Table of Contents
+- [Minimal component (no styles API)](#minimal-component-no-styles-api)
+- [Component with CSS variables](#component-with-css-variables)
+- [Compound component with context](#compound-component-with-context)
+- [Polymorphic component](#polymorphic-component)
+- [Generic component](#generic-component)
+- [Theme integration](#theme-integration)
+- [Namespace exports](#namespace-exports)
+
+---
+
+## Minimal component (no styles API)
+
+When you don't need theming/Styles API support — just Box + useProps.
+
+```tsx
+import { Box, BoxProps, ElementProps, factory, Factory, useProps } from '@mantine/core';
+
+export interface MinimalProps extends BoxProps, ElementProps<'div'> {
+  label?: string;
+}
+
+export type MinimalFactory = Factory<{
+  props: MinimalProps;
+  ref: HTMLDivElement;
+}>;
+
+const defaultProps = {} satisfies Partial<MinimalProps>;
+
+export const Minimal = factory<MinimalFactory>((_props) => {
+  const props = useProps('Minimal', defaultProps, _props);
+  const { label, children, ...others } = props;
+
+  return (
+    <Box {...others}>
+      {label && <span>{label}</span>}
+      {children}
+    </Box>
+  );
+});
+
+Minimal.displayName = '@mantine/core/Minimal';
+```
+
+---
+
+## Component with CSS variables
+
+Full example with Styles API, CSS variables, and theme integration.
+
+**MyComponent.module.css:**
+```css
+.root {
+  border-radius: var(--my-radius);
+  padding: var(--my-padding);
+}
+
+.inner {
+  font-size: var(--my-fz);
+}
+```
+
+**MyComponent.tsx:**
+```tsx
+import {
+  Box, BoxProps, createVarsResolver, ElementProps, factory, Factory,
+  getFontSize, getRadius, getSpacing, MantineFontSize, MantineRadius,
+  MantineSpacing, StylesApiProps, useProps, useStyles,
+} from '@mantine/core';
+import classes from './MyComponent.module.css';
+
+export type MyComponentStylesNames = 'root' | 'inner';
+export type MyComponentVariant = 'filled' | 'outline';
+export type MyComponentCssVariables = {
+  root: '--my-radius' | '--my-padding';
+  inner: '--my-fz';
+};
+
+export interface MyComponentProps
+  extends BoxProps, StylesApiProps<MyComponentFactory>, ElementProps<'div'> {
+  radius?: MantineRadius;
+  padding?: MantineSpacing;
+  size?: MantineFontSize;
+  variant?: MyComponentVariant;
+}
+
+export type MyComponentFactory = Factory<{
+  props: MyComponentProps;
+  ref: HTMLDivElement;
+  stylesNames: MyComponentStylesNames;
+  vars: MyComponentCssVariables;
+  variant: MyComponentVariant;
+}>;
+
+const defaultProps = {
+  radius: 'sm',
+  padding: 'md',
+  size: 'md',
+} satisfies Partial<MyComponentProps>;
+
+const varsResolver = createVarsResolver<MyComponentFactory>((_theme, { radius, padding, size }) => ({
+  root: {
+    '--my-radius': getRadius(radius),
+    '--my-padding': getSpacing(padding),
+  },
+  inner: {
+    '--my-fz': getFontSize(size),
+  },
+}));
+
+export const MyComponent = factory<MyComponentFactory>((_props) => {
+  const props = useProps('MyComponent', defaultProps, _props);
+  const {
+    classNames, className, style, styles, unstyled, vars, attributes,
+    radius, padding, size,
+    children,
+    ...others
+  } = props;
+
+  const getStyles = useStyles<MyComponentFactory>({
+    name: 'MyComponent',
+    classes,
+    props,
+    className,
+    style,
+    classNames,
+    styles,
+    unstyled,
+    vars,
+    attributes,
+    varsResolver,
+  });
+
+  return (
+    <Box {...getStyles('root')} {...others}>
+      <div {...getStyles('inner')}>{children}</div>
+    </Box>
+  );
+});
+
+MyComponent.displayName = '@mantine/core/MyComponent';
+MyComponent.classes = classes;
+MyComponent.varsResolver = varsResolver;
+```
+
+---
+
+## Compound component with context
+
+Pattern for components with typed sub-components (e.g. `Card.Section`, `Tabs.Tab`).
+
+**MyCard.context.ts:**
+```ts
+import { createSafeContext, GetStylesApi } from '@mantine/core';
+import type { MyCardFactory } from './MyCard';
+
+interface MyCardContextValue {
+  getStyles: GetStylesApi<MyCardFactory>;
+  orientation: 'horizontal' | 'vertical';
+}
+
+export const [MyCardProvider, useMyCardContext] = createSafeContext<MyCardContextValue>(
+  'MyCard component was not found in tree'
+);
+```
+
+**MyCardSection.tsx** (sub-component):
+```tsx
+import {
+  Box, BoxProps, CompoundStylesApiProps, ElementProps,
+  factory, Factory, useProps, useStyles,
+} from '@mantine/core';
+import { useMyCardContext } from './MyCard.context';
+import classes from './MyCard.module.css';
+
+export type MyCardSectionStylesNames = 'section';
+
+export interface MyCardSectionProps
+  extends BoxProps, CompoundStylesApiProps<MyCardSectionFactory>, ElementProps<'div'> {
+  withBorder?: boolean;
+}
+
+export type MyCardSectionFactory = Factory<{
+  props: MyCardSectionProps;
+  ref: HTMLDivElement;
+  stylesNames: MyCardSectionStylesNames;
+  compound: true;   // marks as a compound sub-component
+}>;
+
+const defaultProps = {} satisfies Partial<MyCardSectionProps>;
+
+export const MyCardSection = factory<MyCardSectionFactory>((_props) => {
+  const props = useProps('MyCardSection', defaultProps, _props);
+  const { className, style, classNames, styles, withBorder, children, ...others } = props;
+
+  // Access styles from parent context
+  const { getStyles } = useMyCardContext();
+
+  return (
+    <Box
+      {...getStyles('section', { className, style, classNames, styles })}
+      data-with-border={withBorder || undefined}
+      {...others}
+    >
+      {children}
+    </Box>
+  );
+});
+
+MyCardSection.displayName = '@mantine/core/MyCardSection';
+```
+
+**MyCard.tsx** (root component):
+```tsx
+import { MyCardProvider } from './MyCard.context';
+
+// ... (same Styles API setup as above)
+
+export type MyCardFactory = Factory<{
+  props: MyCardProps;
+  ref: HTMLDivElement;
+  stylesNames: 'root' | 'section';    // include sub-component selectors too
+  staticComponents: {
+    Section: typeof MyCardSection;
+  };
+}>;
+
+export const MyCard = factory<MyCardFactory>((_props) => {
+  const props = useProps('MyCard', defaultProps, _props);
+  const {
+    classNames, className, style, styles, unstyled, vars, attributes,
+    orientation, children, ...others
+  } = props;
+
+  const getStyles = useStyles<MyCardFactory>({ ... });
+
+  return (
+    <MyCardProvider value={{ getStyles, orientation: orientation ?? 'vertical' }}>
+      <Box {...getStyles('root')} {...others}>{children}</Box>
+    </MyCardProvider>
+  );
+});
+
+MyCard.displayName = '@mantine/core/MyCard';
+MyCard.classes = classes;
+MyCard.Section = MyCardSection;   // attach sub-component
+```
+
+---
+
+## Polymorphic component
+
+Supports `component` prop to render as any element or React component.
+
+```tsx
+import {
+  Box, BoxProps, polymorphicFactory, PolymorphicFactory,
+  StylesApiProps, useProps, useStyles,
+} from '@mantine/core';
+
+export type MyLinkStylesNames = 'root';
+
+export interface MyLinkProps extends BoxProps, StylesApiProps<MyLinkFactory> {
+  active?: boolean;
+}
+
+export type MyLinkFactory = PolymorphicFactory<{
+  props: MyLinkProps;
+  defaultRef: HTMLAnchorElement;
+  defaultComponent: 'a';            // renders as <a> unless component prop is provided
+  stylesNames: MyLinkStylesNames;
+}>;
+
+const defaultProps = {} satisfies Partial<MyLinkProps>;
+
+export const MyLink = polymorphicFactory<MyLinkFactory>((_props) => {
+  const props = useProps('MyLink', defaultProps, _props);
+  const {
+    classNames, className, style, styles, unstyled, vars, attributes,
+    active, ...others
+  } = props;
+
+  const getStyles = useStyles<MyLinkFactory>({
+    name: 'MyLink', classes, props, className, style,
+    classNames, styles, unstyled, vars, attributes,
+  });
+
+  return (
+    <Box
+      component="a"          // default element
+      data-active={active || undefined}
+      {...getStyles('root')}
+      {...others}
+    />
+  );
+});
+
+MyLink.displayName = '@mantine/core/MyLink';
+MyLink.classes = classes;
+```
+
+**Usage:**
+```tsx
+<MyLink href="/about">Link</MyLink>
+<MyLink component="button" onClick={fn}>As button</MyLink>
+<MyLink component={RouterLink} to="/about">Router link</MyLink>
+```
+
+---
+
+## Generic component
+
+For components where prop types depend on a generic parameter.
+
+```tsx
+import { factory, Factory, genericFactory, useProps } from '@mantine/core';
+
+type SelectValue<M extends boolean> = M extends true ? string[] : string | null;
+
+export interface MySelectProps<M extends boolean = false>
+  extends BoxProps, StylesApiProps<MySelectFactory> {
+  multiple?: M;
+  value?: SelectValue<M>;
+  defaultValue?: SelectValue<M>;
+  onChange?: (value: SelectValue<M>) => void;
+}
+
+export type MySelectFactory = Factory<{
+  props: MySelectProps;
+  ref: HTMLDivElement;
+  signature: <M extends boolean = false>(props: MySelectProps<M>) => React.JSX.Element;
+  stylesNames: 'root';
+}>;
+
+const defaultProps = { multiple: false } satisfies Partial<MySelectProps>;
+
+export const MySelect = genericFactory<MySelectFactory>((_props) => {
+  const props = useProps('MySelect', defaultProps as any, _props);
+  const { multiple, value, onChange, ...others } = props;
+  // ...
+});
+
+MySelect.displayName = '@mantine/core/MySelect';
+```
+
+**Usage:**
+```tsx
+// TypeScript infers value as string | null
+<MySelect value={val} onChange={(v) => setVal(v)} />
+
+// TypeScript infers value as string[]
+<MySelect multiple value={vals} onChange={(v) => setVals(v)} />
+```
+
+---
+
+## Theme integration
+
+Components built with `factory()` automatically get `.extend()` and `.withProps()`.
+
+**`.extend()`** — for theme-level configuration in `createTheme`:
+```tsx
+const theme = createTheme({
+  components: {
+    MyComponent: MyComponent.extend({
+      // Override default props
+      defaultProps: {
+        radius: 'xl',
+        size: 'lg',
+      },
+      // Add classes to selectors
+      classNames: {
+        root: 'my-root-class',
+        inner: 'my-inner-class',
+      },
+      // Add inline styles to selectors
+      styles: {
+        root: { border: '1px solid red' },
+      },
+      // Or use a callback for theme-aware styles
+      styles: (theme) => ({
+        root: { background: theme.colors.blue[0] },
+      }),
+      // Override CSS variables
+      vars: (_theme, props) => ({
+        root: { '--my-radius': props.radius ? getRadius(props.radius) : undefined },
+      }),
+    }),
+  },
+});
+```
+
+**`.withProps()`** — create a pre-configured variant at the call site:
+```tsx
+const BigMyComponent = MyComponent.withProps({ size: 'xl', radius: 'lg' });
+
+// Same as MyComponent but with size and radius pre-set
+<BigMyComponent>Content</BigMyComponent>
+```
+
+---
+
+## Namespace exports
+
+Add at the bottom of the component file or `index.ts` to let consumers access types without extra imports.
+
+```tsx
+export namespace MyComponent {
+  export type Props = MyComponentProps;
+  export type StylesNames = MyComponentStylesNames;
+  export type CssVariables = MyComponentCssVariables;
+  export type Factory = MyComponentFactory;
+  export type Variant = MyComponentVariant;
+
+  export namespace Section {
+    export type Props = MyComponentSectionProps;
+    export type StylesNames = MyComponentSectionStylesNames;
+    export type Factory = MyComponentSectionFactory;
+  }
+}
+```
+
+**Usage:**
+```ts
+import { MyComponent } from './MyComponent';
+
+// No need to import MyComponentProps separately
+const props: MyComponent.Props = { radius: 'md' };
+```

package/.agents/skills/publish-lkd-web-kit/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: publish-lkd-web-kit
+description: Versiona y publica lkd-web-kit en npm mediante GitHub Actions y Trusted Publishing. Usar cuando el usuario pida subir la version del paquete, preparar un release, crear el tag vX.Y.Z, configurar el workflow de publicacion o publicar sin login interactivo del navegador.
+---
+
+# Publicar LKD Web Kit
+
+## Principio
+
+Publica solo desde un estado validado y reproducible. No automatices `npm login` en navegador. La ruta preferida es GitHub Actions con npm Trusted Publishing y `npm publish --provenance`.
+
+Para actualizar dependencias antes del release, usa `$update-lkd-dependencies`.
+
+## Preflight obligatorio
+
+Antes de cambiar version o crear tags:
+
+1. Pregunta siempre al usuario a que version quiere subir. No infieras ni elijas version por tu cuenta.
+2. Valida que la version objetivo sea SemVer y mayor que la version publicada/local.
+3. Lee `AGENTS.md`, `package.json`, `package-lock.json` y `docs/generated/lkd-web-kit.md`.
+4. Ejecuta `git status --short` y confirma que el worktree esta limpio o que solo contiene cambios esperados para el release.
+5. Verifica que `package.json` y `package-lock.json` declaran la misma version del paquete.
+6. Revisa si existe `.github/workflows/publish.yml`.
+7. Si Trusted Publishing no esta configurado en npm, lee `references/npm-trusted-publishing.md` y detente antes de publicar hasta que un maintainer/admin lo habilite.
+8. Identifica la version anterior publicada/local y la version nueva objetivo; las necesitaras para la upgrade guide.
+
+## Versionado SemVer cauteloso
+
+Elige el bump por impacto publico:
+
+- `major`: cambia compatibilidad publica, elimina APIs, altera contratos de componentes, o hace incompatible algun rango peer importante.
+- `minor`: agrega soporte compatible, nuevos componentes, nuevas props compatibles o amplia peers sin romper consumers.
+- `patch`: mantenimiento, fixes internos, ajustes de build o dependencia compatible sin impacto publico.
+
+La version exacta debe venir del usuario. Si no la dio en el mensaje inicial, pregunta y espera respuesta antes de ejecutar `npm version`.
+
+Aplica la version sin crear tag automaticamente:
+
+```bash
+npm version <major|minor|patch> --no-git-tag-version
+```
+
+o:
+
+```bash
+npm version <x.y.z> --no-git-tag-version
+```
+
+## Validacion de release
+
+Ejecuta siempre:
+
+```bash
+npm run lint
+npm run test
+npm run build
+npm pack --dry-run
+```
+
+No continues si falla una validacion. Corrige el problema si esta dentro del alcance del release; si no, reporta el bloqueo.
+
+## Upgrade guide obligatoria
+
+Antes de crear el commit/tag de release, crea una guia de migracion para consumidores en:
+
+```text
+docs/generated/upgrade-guides/upgrade-v<version-anterior>-to-v<version-nueva>.md
+```
+
+Ejemplo:
+
+```text
+docs/generated/upgrade-guides/upgrade-v0.8.1-to-v0.9.0.md
+```
+
+La guia debe estar en espanol y contener un prompt listo para copiar y pegar en la IA del proyecto consumidor. Usa esta estructura:
+
+```md
+# Upgrade v<version-anterior> to v<version-nueva>
+
+## Resumen
+
+Describe en 2-4 bullets que cambia en `lkd-web-kit` y el riesgo esperado.
+
+## Dependencias a actualizar
+
+Lista exacta de paquetes y rangos/versiones requeridas:
+- `lkd-web-kit`: `<version-nueva>`
+- `<peer>`: `<rango-nuevo>`
+
+Indica tambien peers que no cambian si son relevantes para evitar confusion.
+
+## Cambios de API o comportamiento
+
+Si hubo cambios de nombres, componentes, props, parametros, tipos, exports, hooks, utils o comportamiento, especifica:
+- Antes: `...`
+- Despues: `...`
+- Accion requerida en consumidores: `...`
+
+Si no hubo cambios de API publica, escribe explicitamente: `No hay cambios de API publica detectados.`
+
+## Cambios requeridos por dependencias peer
+
+Explica si las nuevas versiones de React, Mantine, Next, Zod, React Hook Form, TanStack, Ky u otros peers requieren cambios en los proyectos consumidores. Si no hay cambios esperados, declaralo explicitamente.
+
+## Prompt para IA del proyecto consumidor
+
+Incluye un prompt completo que instruya a la IA del proyecto consumidor a:
+- Leer `package.json`, lockfile, `AGENTS.md` y documentacion local del proyecto.
+- Actualizar `lkd-web-kit` y peers a los rangos indicados.
+- Buscar imports/usos afectados con `rg`.
+- Aplicar cambios de API descritos en esta guia.
+- Ejecutar `npm install`, `npm run lint`, `npm run test` y `npm run build`.
+- Reportar cambios aplicados, archivos modificados, validaciones y bloqueos.
+```
+
+Reglas:
+
+- No inventes breaking changes. Si no hay cambios de nombres, parametros o props, dilo.
+- Si `docs/generated/lkd-web-kit.md` cambio por superficie publica nueva, usa ese diff como fuente para la seccion de API.
+- Si solo cambiaron peers, aun asi crea la guia y enfocate en dependencias y validaciones para consumidores.
+- La guia forma parte del release y debe entrar en el mismo commit `release: vX.Y.Z`.
+
+## Commit, tag y publicacion
+
+1. Revisa el diff final y confirma que incluye la upgrade guide correspondiente y solo cambios esperados.
+2. Crea un commit de release con el formato:
+
+```bash
+git commit -m "release: vX.Y.Z"
+```
+
+3. Crea el tag:
+
+```bash
+git tag vX.Y.Z
+```
+
+4. Empuja commit y tag automaticamente:
+
+```bash
+git push origin HEAD
+git push origin vX.Y.Z
+```
+
+5. La publicacion debe ocurrir en GitHub Actions por el trigger del tag. No ejecutes `npm publish` localmente salvo instruccion explicita y consciente del usuario.
+
+## Reporte final
+
+Reporta en espanol:
+
+- Version anterior y nueva.
+- Tipo de bump y justificacion.
+- Ruta de la upgrade guide generada.
+- Validaciones ejecutadas.
+- Commit/tag creados y push ejecutado, o el bloqueo exacto si fallo.
+- Estado del workflow de Trusted Publishing y si queda algun paso manual en npm.
+- Comandos exactos ejecutados para disparar el workflow de publicacion.
+
+Incluye siempre este bloque, ajustando `vX.Y.Z` por la version real:
+
+```bash
+git push origin HEAD
+git push origin vX.Y.Z
+```

package/.agents/skills/publish-lkd-web-kit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Publicar LKD Web Kit"
+  short_description: "Versiona y publica el kit en npm"
+  default_prompt: "Usa $publish-lkd-web-kit para versionar lkd-web-kit y publicarlo en npm mediante Trusted Publishing."

package/.agents/skills/publish-lkd-web-kit/references/npm-trusted-publishing.md

@@ -0,0 +1,82 @@
+# npm Trusted Publishing para lkd-web-kit
+
+Usa esta referencia cuando el usuario quiera publicar sin `npm login` interactivo o cuando falte `.github/workflows/publish.yml`.
+
+## Configuracion esperada en npm
+
+Un maintainer/admin del paquete debe configurar Trusted Publishing en npm con estos datos:
+
+- Package: `lkd-web-kit`
+- Provider: GitHub Actions
+- Repository owner/name: `jrjais/lkd-web-kit`
+- Workflow file: `publish.yml`
+- Environment: dejar vacio salvo que el repo use environments protegidos
+
+Si npm rechaza la configuracion por permisos, detenerse. No intentes automatizar el navegador ni pedir credenciales. Indica que debe hacerlo una cuenta con permisos de maintainer/admin sobre el paquete.
+
+## Workflow recomendado
+
+Crea `.github/workflows/publish.yml` si no existe:
+
+```yaml
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22.x"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build
+
+      - name: Pack dry run
+        run: npm pack --dry-run
+
+      - name: Publish
+        run: npm publish --provenance
+```
+
+## Primer release
+
+Antes de empujar el tag:
+
+1. Confirma que el paquete existe en npm.
+2. Confirma que Trusted Publishing esta configurado para el workflow exacto.
+3. Confirma que `package.json` no necesita `publishConfig.access` especial. Para este paquete no scoped, normalmente no hace falta.
+4. Empuja primero el commit de release y luego el tag `vX.Y.Z`.
+
+## Fallback con token
+
+Usa `NPM_TOKEN` solo si Trusted Publishing no es viable. Debe ser un automation token guardado como secreto de GitHub Actions. En ese caso:
+
+- Mantener `permissions.contents: read`.
+- Eliminar `id-token: write` si no se usa provenance por OIDC.
+- Agregar `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` al paso `npm publish`.
+
+No guardar tokens en `.npmrc`, `package.json`, logs, scripts ni archivos del repo.