kigumi 0.9.0 → 0.9.2

package/dist/index.js

@@ -517,7 +517,7 @@ var ConfigNotFoundError = class extends KigumiError {
 // src/errors/validation.ts
 var ValidationError = class extends KigumiError {
   constructor(field, value, validValues, zodError) {
-    const errorMessages = zodError?.errors.map((err) => {
+    const errorMessages = zodError?.issues.map((err) => {
       return `${err.path.join(".")}: ${err.message}`;
     }) || [];
     const suggestions = [
@@ -779,10 +779,10 @@ function handleError(error, output) {
 import { z } from "zod";
 var FRAMEWORKS = ["react", "vue", "svelte", "angular"];
 var frameworkSchema = z.enum(FRAMEWORKS, {
-  errorMap: () => ({ message: `Must be one of: ${FRAMEWORKS.join(", ")}` })
+  error: () => `Must be one of: ${FRAMEWORKS.join(", ")}`
 });
 var tierSchema = z.enum(["free", "pro"], {
-  errorMap: () => ({ message: 'Must be either "free" or "pro"' })
+  error: () => 'Must be either "free" or "pro"'
 });
 var themeConfigSchema = z.object({
   selected: z.string().min(1, "Theme name cannot be empty"),
@@ -796,7 +796,7 @@ var webAwesomeConfigSchema = z.object({
 var kigumiConfigSchema = z.object({
   framework: frameworkSchema,
   typescript: z.boolean({
-    errorMap: () => ({ message: "Must be a boolean (true or false)" })
+    error: () => "Must be a boolean (true or false)"
   }),
   componentsDir: z.string().min(1, "Components directory cannot be empty"),
   utilsDir: z.string().min(1, "Utils directory cannot be empty").optional(),
@@ -875,7 +875,7 @@ var listOptionsSchema = z2.object({
 function validateOptions(schema, options) {
   const result = schema.safeParse(options);
   if (!result.success) {
-    const errors = result.error.errors.map((err) => {
+    const errors = result.error.issues.map((err) => {
       const path15 = err.path.join(".");
       return path15 ? `${path15}: ${err.message}` : err.message;
     });
@@ -917,14 +917,10 @@ var AVAILABLE_BRAND_COLORS = [
   "gray"
 ];
 var paletteSchema = z3.enum(AVAILABLE_PALETTES, {
-  errorMap: () => ({
-    message: `Palette must be one of: ${AVAILABLE_PALETTES.join(", ")}`
-  })
+  error: () => `Palette must be one of: ${AVAILABLE_PALETTES.join(", ")}`
 });
 var brandColorSchema = z3.enum(AVAILABLE_BRAND_COLORS, {
-  errorMap: () => ({
-    message: `Brand color must be one of: ${AVAILABLE_BRAND_COLORS.join(", ")}`
-  })
+  error: () => `Brand color must be one of: ${AVAILABLE_BRAND_COLORS.join(", ")}`
 });
 var componentNameSchema = z3.string().min(1, "Component name cannot be empty");
 

package/dist/skills/kigumi-react/references/event-mapping.md

@@ -1,26 +1,45 @@
 # Event Mapping
 
-Web Awesome components emit custom events prefixed with `wa-`. These are mapped to React event handlers.
+Web Awesome components use two different event systems depending on the component type.
 
-## Standard Events
+## Form Controls — Native DOM Events
 
-| Web Awesome Event | React Handler         | Type                           |
-| ----------------- | --------------------- | ------------------------------ |
-| `wa-change`       | `onChange`            | `(event: CustomEvent) => void` |
-| `wa-input`        | `onInput`             | `(event: CustomEvent) => void` |
-| `wa-show`         | `onShow`              | `(event: CustomEvent) => void` |
-| `wa-hide`         | `onHide`              | `(event: CustomEvent) => void` |
-| `wa-after-show`   | `onAfterShow`         | `(event: CustomEvent) => void` |
-| `wa-after-hide`   | `onAfterHide`         | `(event: CustomEvent) => void` |
-| `wa-blur`         | `onBlur`              | `(event: FocusEvent) => void`  |
-| `wa-focus`        | `onFocus`             | `(event: FocusEvent) => void`  |
-| Standard events   | Standard React events | Native types                   |
+`wa-button`, `wa-input`, `wa-number-input`, `wa-file-input`, `wa-textarea`, `wa-select`, `wa-checkbox`, `wa-switch` emit **native browser events** (no `wa-` prefix). Event handlers receive standard `Event` / `FocusEvent` objects — use `e.target.value`, `e.target.files`, etc.
 
-## Example Usage
+| Native Event | React Handler | Type         |
+| ------------ | ------------- | ------------ |
+| `blur`       | `onBlur`      | `FocusEvent` |
+| `focus`      | `onFocus`     | `FocusEvent` |
+| `input`      | `onInput`     | `Event`      |
+| `change`     | `onChange`    | `Event`      |
 
 ```tsx
-import { useState } from "react";
-import { Dialog, Button } from "@/components/ui";
+// Correct: native events
+<Input
+  onInput={(e) => console.log((e.target as HTMLInputElement).value)}
+  onChange={(e) => console.log((e.target as HTMLInputElement).value)}
+/>
+
+// Wrong: these events don't fire on form controls
+<Input onInput={(e: CustomEvent) => console.log(e.detail.value)} />
+```
+
+## Overlay / Complex Components — Custom `wa-` Events
+
+`wa-dialog`, `wa-drawer`, `wa-dropdown`, `wa-popup`, `wa-tooltip`, etc. emit **custom events** prefixed with `wa-`. Event handlers receive `CustomEvent` objects.
+
+| Web Awesome Event | React Handler | Type          |
+| ----------------- | ------------- | ------------- |
+| `wa-show`         | `onShow`      | `CustomEvent` |
+| `wa-hide`         | `onHide`      | `CustomEvent` |
+| `wa-after-show`   | `onAfterShow` | `CustomEvent` |
+| `wa-after-hide`   | `onAfterHide` | `CustomEvent` |
+| `wa-clear`        | `onClear`     | `CustomEvent` |
+| `wa-invalid`      | `onInvalid`   | `CustomEvent` |
+
+```tsx
+import { useState } from 'react';
+import { Dialog, Button } from '@/components/ui';
 
 function Example() {
   const [open, setOpen] = useState(false);
@@ -31,7 +50,7 @@ function Example() {
       <Dialog
         open={open}
         onHide={() => setOpen(false)}
-        onAfterShow={(e) => console.log("Dialog shown", e)}
+        onAfterShow={(e) => console.log('Dialog shown', e)}
       >
         Dialog content
       </Dialog>

package/dist/templates/AGENTS.md

@@ -141,14 +141,25 @@ const { forwardRef, useRef, useEffect } = React;
 
 ### 3. Event Naming Convention
 
-| Web Awesome     | React Prop    |
-| --------------- | ------------- |
-| `wa-show`       | `onShow`      |
-| `wa-hide`       | `onHide`      |
-| `wa-after-show` | `onAfterShow` |
-| `wa-blur`       | `onBlur`      |
-| `wa-focus`      | `onFocus`     |
-| `wa-change`     | `onChange`    |
+**Form controls** (wa-button, wa-input, wa-number-input, wa-file-input, wa-textarea, wa-select, wa-checkbox, wa-switch) emit **native DOM events** — no `wa-` prefix:
+
+| Native Event | React Prop |
+| ------------ | ---------- |
+| `blur`       | `onBlur`   |
+| `focus`      | `onFocus`  |
+| `input`      | `onInput`  |
+| `change`     | `onChange` |
+
+**Overlay/complex components** (wa-dialog, wa-drawer, wa-dropdown, wa-popup, etc.) emit **custom `wa-` events**:
+
+| Web Awesome Event | React Prop    |
+| ----------------- | ------------- |
+| `wa-show`         | `onShow`      |
+| `wa-hide`         | `onHide`      |
+| `wa-after-show`   | `onAfterShow` |
+| `wa-after-hide`   | `onAfterHide` |
+| `wa-clear`        | `onClear`     |
+| `wa-invalid`      | `onInvalid`   |
 
 ### 4. Always Cleanup Event Listeners
 

package/dist/templates/react/Button/Button.jsx.hbs

@@ -82,12 +82,12 @@ export const Button = React.forwardRef(
         if (onFocus) onFocus(e);
       };
 
-      el.addEventListener('wa-blur', handleBlur);
-      el.addEventListener('wa-focus', handleFocus);
+      el.addEventListener('blur', handleBlur);
+      el.addEventListener('focus', handleFocus);
 
       return () => {
-        el.removeEventListener('wa-blur', handleBlur);
-        el.removeEventListener('wa-focus', handleFocus);
+        el.removeEventListener('blur', handleBlur);
+        el.removeEventListener('focus', handleFocus);
       };
     }, [onBlur, onFocus]);
 

package/dist/templates/react/Dialog/Dialog.jsx.hbs

@@ -1,28 +1,40 @@
 import React from 'react';
+import { createPortal } from 'react-dom';
 import clsx from 'clsx';
 import '{{{importPath}}}';
 import './Dialog.css';
 
 /**
- * Dialogs display important prompts and information
+ * // Using data-dialog attribute (recommended)
+ * import { Dialog } from './components/ui';
+ * import { Button } from './components/ui';
  *
- * @example
- * // Using ref methods
- * const dialogRef = React.useRef(null);
- * <Dialog ref={dialogRef} label="Dialog Title">
- *   <p>Dialog content</p>
- *   <div slot="footer">
- *     <Button data-dialog="close">Close</Button>
- *   </div>
+ * <Button data-dialog="open dialog">Open FAQ</Button>
+ * <Dialog id="dialog" label="FAQ">
+ *   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
+ *   <Button slot="footer" variant="brand" data-dialog="close">
+ *     Close
+ *   </Button>
  * </Dialog>
- * dialogRef.current?.show();
+ * Dialogs display important prompts and information
  *
+ * @example
  * // Using open prop (recommended)
  * const [open, setOpen] = React.useState(false);
  * <Dialog open={open} label="Dialog Title" onHide={() => setOpen(false)}>
  *   <p>Dialog content</p>
+ *   <Button slot="footer" variant="brand" onClick={() => setOpen(false)}>
+ *     Close
+ *   </Button>
  * </Dialog>
  *
+ * // Using ref methods (alternative)
+ * const dialogRef = React.useRef(null);
+ * <Dialog ref={dialogRef} label="Dialog Title">
+ *   <p>Dialog content</p>
+ * </Dialog>
+ * dialogRef.current?.show();
+ *
  * @param {Object} props
  * @param {boolean} [props.open] - Indicates whether or not the dialog is open
  * @param {string} props.label - The dialog's label as displayed in the header
@@ -32,33 +44,21 @@ import './Dialog.css';
  * @param {function} [props.onAfterShow] - Event fired after the dialog is shown
  * @param {function} [props.onHide] - Event fired when the dialog is about to hide
  * @param {function} [props.onAfterHide] - Event fired after the dialog is hidden
+ * @param {string | string[]} [props['data-dialog']] - Data attribute for opening and closing declaratively
  * @param {string} [props.className] - Additional CSS classes
  * @param {React.ReactNode} [props.children] - Dialog content
  * @param {React.Ref} ref - Ref with methods: show(), hide(), requestClose()
  */
 export const Dialog = React.forwardRef(
-  ({ children, className, onShow, onAfterShow, onHide, onAfterHide, ...props }, ref) => {
+  ({ children, className, open, onShow, onAfterShow, onHide, onAfterHide, ...props }, ref) => {
     const dialogRef = React.useRef(null);
 
     React.useImperativeHandle(
       ref,
       () => ({
-        show: () => {
-          if (dialogRef.current && typeof dialogRef.current.show === 'function') {
-            dialogRef.current.show();
-          }
-        },
-        hide: () => {
-          // hide is an alias for requestClose for consistency with other components
-          if (dialogRef.current && typeof dialogRef.current.requestClose === 'function') {
-            dialogRef.current.requestClose();
-          }
-        },
-        requestClose: () => {
-          if (dialogRef.current && typeof dialogRef.current.requestClose === 'function') {
-            dialogRef.current.requestClose();
-          }
-        },
+        show: () => dialogRef.current?.show?.(),
+        hide: () => dialogRef.current?.requestClose?.(),
+        requestClose: () => dialogRef.current?.requestClose?.(),
         get element() {
           return dialogRef.current;
         },
@@ -66,26 +66,28 @@ export const Dialog = React.forwardRef(
       []
     );
 
-    // Setup event listeners
+    // Sync open prop with dialog element
     React.useEffect(() => {
       const el = dialogRef.current;
-      if (!el) return;
-
-      const handleShow = (e) => {
-        if (onShow) onShow(e);
-      };
+      if (!el || open === undefined) return;
 
-      const handleAfterShow = (e) => {
-        if (onAfterShow) onAfterShow(e);
-      };
+      const isOpen = el.open ?? false;
+      if (open && !isOpen) {
+        el.show?.();
+      } else if (!open && isOpen) {
+        el.requestClose?.();
+      }
+    }, [open]);
 
-      const handleHide = (e) => {
-        if (onHide) onHide(e);
-      };
+    // Setup event listeners
+    React.useEffect(() => {
+      const el = dialogRef.current;
+      if (!el) return;
 
-      const handleAfterHide = (e) => {
-        if (onAfterHide) onAfterHide(e);
-      };
+      const handleShow = (e) => onShow?.(e);
+      const handleAfterShow = (e) => onAfterShow?.(e);
+      const handleHide = (e) => onHide?.(e);
+      const handleAfterHide = (e) => onAfterHide?.(e);
 
       el.addEventListener('wa-show', handleShow);
       el.addEventListener('wa-after-show', handleAfterShow);
@@ -100,14 +102,15 @@ export const Dialog = React.forwardRef(
       };
     }, [onShow, onAfterShow, onHide, onAfterHide]);
 
-    return (
+    return createPortal(
       <wa-dialog
         ref={dialogRef}
         class={clsx('Dialog', className)}
         {...props}
       >
         {children}
-      </wa-dialog>
+      </wa-dialog>,
+      document.body
     );
   }
 );

package/dist/templates/react/Dialog/Dialog.tsx.hbs

@@ -1,20 +1,55 @@
 import { forwardRef, useRef, useImperativeHandle, useEffect, type HTMLAttributes } from 'react';
+import { createPortal } from 'react-dom';
 import clsx from 'clsx';
 import '{{{importPath}}}';
 import './Dialog.css';
 
 /**
+ * // Using data-dialog attribute (recommended)
+ * import { Dialog } from './components/ui';
+ * import { Button } from './components/ui';
+ *
+ * <Button data-dialog="open dialog">Open FAQ</Button>
+ * <Dialog id="dialog" label="FAQ">
+ *   <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
+ *   <Button slot="footer" variant="brand" data-dialog="close">
+ *     Close
+ *   </Button>
+ * </Dialog>
  * Dialogs display important prompts and information
  *
  * @example
  * ```tsx
- * // Basic usage
- * <Dialog />
+ * // Using open prop (recommended)
+ * import { useState } from 'react';
+ *
+ * function App() {
+ *   const [open, setOpen] = useState(false);
  *
- * // With event handlers
- * <Dialog
- *   onShow={(e) => console.log(e)} />
+ *   return (
+ *     <>
+ *       <Button onClick={() => setOpen(true)}>Open Dialog</Button>
+ *       <Dialog open={open} label="Dialog Title" onHide={() => setOpen(false)}>
+ *         <p>Dialog content</p>
+ *         <Button slot="footer" variant="brand" onClick={() => setOpen(false)}>
+ *           Close
+ *         </Button>
+ *       </Dialog>
+ *     </>
+ *   );
+ * }
  *
+ * // Using ref methods (alternative)
+ * import { useRef } from 'react';
+ * const dialogRef = useRef<DialogRef>(null);
+ *
+ * <Button onClick={() => dialogRef.current?.show()}>Open Dialog</Button>
+ * <Dialog ref={dialogRef} label="Dialog Title">
+ *   <p>Dialog content</p>
+ *   <Button slot="footer" variant="brand" onClick={() => dialogRef.current?.hide()}>
+ *     Close
+ *   </Button>
+ * </Dialog>
  * ```
  */
 export interface DialogProps extends Omit<HTMLAttributes<HTMLElement>, 'onShow' | 'onAfterShow' | 'onHide' | 'onAfterHide' | 'dir'> {
@@ -42,21 +77,33 @@ export interface DialogProps extends Omit<HTMLAttributes<HTMLElement>, 'onShow'
 
   /** Emitted after the dialog closes and all animations are complete. */
   onAfterHide?: (event: CustomEvent) => void;
+
+  /** Data attribute for opening and closing declaratively. */
+  'data-dialog'?: string | string[];
 }
 
 export interface DialogRef {
+  show: () => void;
+  hide: () => void;
+  requestClose: () => void;
   /** Reference to the underlying HTML element */
   element: HTMLElement | null;
 }
 
 export const Dialog = forwardRef<DialogRef, DialogProps>(
-  ({ children, className, onShow, onAfterShow, onHide, onAfterHide, ...props }, ref) => {
+  ({ children, className, open, onShow, onAfterShow, onHide, onAfterHide, ...props }, ref) => {
     const dialogRef = useRef<HTMLElement & {
+      show?: () => void;
+      requestClose?: () => void;
+      open?: boolean;
     }>(null);
 
     useImperativeHandle(
       ref,
       () => ({
+        show: () => dialogRef.current?.show?.(),
+        hide: () => dialogRef.current?.requestClose?.(),
+        requestClose: () => dialogRef.current?.requestClose?.(),
         get element() {
           return dialogRef.current;
         },
@@ -64,25 +111,28 @@ export const Dialog = forwardRef<DialogRef, DialogProps>(
       []
     );
 
+    // Sync open prop with dialog element
     useEffect(() => {
       const el = dialogRef.current;
-      if (!el) return;
+      if (!el || open === undefined) return;
 
-      const handleShow = (e: Event) => {
-        if (onShow) onShow(e as CustomEvent);
-      };
+      const isOpen = el.open ?? false;
+      if (open && !isOpen) {
+        el.show?.();
+      } else if (!open && isOpen) {
+        el.requestClose?.();
+      }
+    }, [open]);
 
-      const handleAfterShow = (e: Event) => {
-        if (onAfterShow) onAfterShow(e as CustomEvent);
-      };
-
-      const handleHide = (e: Event) => {
-        if (onHide) onHide(e as CustomEvent);
-      };
+    // Setup event listeners
+    useEffect(() => {
+      const el = dialogRef.current;
+      if (!el) return;
 
-      const handleAfterHide = (e: Event) => {
-        if (onAfterHide) onAfterHide(e as CustomEvent);
-      };
+      const handleShow = (e: Event) => onShow?.(e as CustomEvent);
+      const handleAfterShow = (e: Event) => onAfterShow?.(e as CustomEvent);
+      const handleHide = (e: Event) => onHide?.(e as CustomEvent);
+      const handleAfterHide = (e: Event) => onAfterHide?.(e as CustomEvent);
 
       el.addEventListener('wa-show', handleShow);
       el.addEventListener('wa-after-show', handleAfterShow);
@@ -97,14 +147,15 @@ export const Dialog = forwardRef<DialogRef, DialogProps>(
       };
     }, [onShow, onAfterShow, onHide, onAfterHide]);
 
-    return (
+    return createPortal(
       <wa-dialog
         ref={dialogRef}
         class={clsx('Dialog', className)}
         {...(props as Record<string, unknown>)}
       >
         {children}
-      </wa-dialog>
+      </wa-dialog>,
+      document.body
     );
   }
 );

package/dist/templates/react/Drawer/Drawer.jsx.hbs

@@ -1,15 +1,55 @@
 import React from 'react';
+import { createPortal } from 'react-dom';
 import clsx from 'clsx';
 import '{{{importPath}}}';
 import './Drawer.css';
 
 /**
+ * // Using data-drawer attribute (recommended)
+ * import { Drawer } from './components/ui';
+ * import { Button } from './components/ui';
+ *
+ * <Button data-drawer="open drawer">Open Drawer</Button>
+ * <Drawer id="drawer" label="Drawer Title">
+ *   <p>Drawer content</p>
+ *   <Button slot="footer" variant="brand" data-drawer="close">Close</Button>
+ * </Drawer>
+ * Drawers slide in from a container edge to expose additional options
+ *
+ * @example
+ * // Using open prop (recommended)
+ * const [open, setOpen] = React.useState(false);
+ * <Drawer open={open} label="Drawer Title" onHide={() => setOpen(false)}>
+ *   <p>Drawer content</p>
+ * </Drawer>
+ *
+ * // Using ref methods (alternative)
+ * const drawerRef = React.useRef(null);
+ * <Drawer ref={drawerRef} label="Drawer Title">
+ *   <p>Drawer content</p>
+ * </Drawer>
+ * drawerRef.current?.show();
+ *
  * @typedef {Object} DrawerRef
  * @property {() => void} show
  * @property {() => void} hide
  * @property {HTMLElement | null} element
+ *
+ * @param {Object} props
+ * @param {boolean} [props.open] - Indicates whether the drawer is open
+ * @param {string} [props.label] - The drawer's label as displayed in the header
+ * @param {'top' | 'end' | 'bottom' | 'start'} [props.placement] - The direction from which the drawer will open
+ * @param {boolean} [props['light-dismiss']] - Closes the drawer when the user clicks outside of it
+ * @param {boolean} [props['without-header']] - Removes the header
+ * @param {function} [props.onShow] - Event fired when the drawer is shown
+ * @param {function} [props.onAfterShow] - Event fired after the drawer is shown
+ * @param {function} [props.onHide] - Event fired when the drawer is about to hide
+ * @param {function} [props.onAfterHide] - Event fired after the drawer is hidden
+ * @param {string | string[]} [props['data-drawer']] - Data attribute for opening and closing declaratively
+ * @param {string} [props.className] - Additional CSS classes
+ * @param {React.ReactNode} [props.children] - Drawer content
+ * @param {React.Ref} ref - Ref with methods: show(), hide()
  */
-
 export const Drawer = React.forwardRef(
   ({ children, className, open, onShow, onAfterShow, onHide, onAfterHide, ...props }, ref) => {
     const drawerRef = React.useRef(null);
@@ -26,6 +66,7 @@ export const Drawer = React.forwardRef(
       []
     );
 
+    // Sync open prop with drawer element
     React.useEffect(() => {
       const el = drawerRef.current;
       if (!el || open === undefined) return;
@@ -38,6 +79,7 @@ export const Drawer = React.forwardRef(
       }
     }, [open]);
 
+    // Setup event listeners
     React.useEffect(() => {
       const el = drawerRef.current;
       if (!el) return;
@@ -60,14 +102,15 @@ export const Drawer = React.forwardRef(
       };
     }, [onShow, onAfterShow, onHide, onAfterHide]);
 
-    return (
+    return createPortal(
       <wa-drawer
         ref={drawerRef}
         class={clsx('Drawer', className)}
         {...props}
       >
         {children}
-      </wa-drawer>
+      </wa-drawer>,
+      document.body
     );
   }
 );