reactigoded 1.0.0-beta.26

package/dist/components/floating/Menu/MenuTrigger.d.ts

@@ -0,0 +1,53 @@
+import { ButtonHTMLAttributes, Ref } from 'react';
+export interface MenuTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    ref?: Ref<HTMLButtonElement> | undefined;
+    /**
+     * Slot pattern (D14 Bloque D beta.27): si `true`, clona el child del
+     * consumer y le aplica trigger semantics (id, aria-haspopup, aria-expanded
+     * via `useRole`, aria-controls, click + keyboard handlers de FUI) sin
+     * renderizar un `<button>` propio ni aplicar `ig-menu-trigger`.
+     *
+     * Permite usar cualquier elemento como trigger (`<Button>` del DS,
+     * `<a>`, custom component) preservando su tipo, styling y eventos.
+     *
+     * Sin `asChild`, MenuTrigger renderiza un `<button>` plano con clase
+     * `ig-menu-trigger` (comportamiento backwards-compat con 1.0.0-beta.26).
+     *
+     * @example
+     * // Slot pattern (recomendado con Button del DS):
+     * <MenuTrigger asChild>
+     *   <Button variant="brand">Abrir menú</Button>
+     * </MenuTrigger>
+     *
+     * @example
+     * // Default (backwards-compat):
+     * <MenuTrigger>Opciones</MenuTrigger>
+     */
+    asChild?: boolean | undefined;
+}
+/**
+ * MenuTrigger — botón que abre/cierra el menú. Dos modos de render:
+ *
+ * - **Default** (`asChild=false`): renderiza un `<button class="ig-menu-trigger">`
+ *   plano. Comportamiento idéntico al de 1.0.0-beta.26.
+ *
+ * - **Slot pattern** (`asChild=true`, D14 Bloque D): clona el child del
+ *   consumer y le aplica id + ARIA + handlers FUI. El child es
+ *   renderizado directamente (no wrapper). Patrón canónico Radix/shadcn.
+ *
+ * **C-03 (RC1)**: internals via `@floating-ui/react`. `useClick` ya
+ * cubre toggle por click + Space/Enter (estándar `<button>`).
+ * `useListNavigation` con `focusItemOnOpen: "auto"` foca primer/último
+ * item según la tecla que abrió el menú.
+ *
+ * ARIA inyectada por `useRole({ role: "menu" })`:
+ * - `aria-haspopup="menu"`
+ * - `aria-expanded={open}`
+ *
+ * `aria-controls={menuId}` se inyecta explícitamente para enlace al
+ * MenuContent (no lo cubre useRole por defecto).
+ *
+ * Es client-component (`"use client"`) porque consume `MenuContext` via
+ * hook — NO marcado server-safe.
+ */
+export declare function MenuTrigger({ asChild, className, children, type, ref, ...rest }: MenuTriggerProps): import("react").JSX.Element;

package/dist/components/floating/Menu/index.d.ts

@@ -0,0 +1,12 @@
+export { Menu } from './Menu.js';
+export type { MenuProps, MenuAlign, MenuDirection, } from './Menu.js';
+export { MenuTrigger } from './MenuTrigger.js';
+export type { MenuTriggerProps } from './MenuTrigger.js';
+export { MenuContent } from './MenuContent.js';
+export type { MenuContentProps } from './MenuContent.js';
+export { MenuItem } from './MenuItem.js';
+export type { MenuItemProps } from './MenuItem.js';
+export { MenuSeparator } from './MenuSeparator.js';
+export type { MenuSeparatorProps } from './MenuSeparator.js';
+export { MenuLabel } from './MenuLabel.js';
+export type { MenuLabelProps } from './MenuLabel.js';

package/dist/components/floating/Menu/menuSelectors.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Selector compartido por MenuTrigger y MenuItem para localizar
+ * los items navegables del menú.
+ *
+ * Excluye:
+ *  - `[disabled]` — los <button> nativos disabled no son focuseables.
+ *  - `[aria-disabled="true"]` — los <a> y custom items que se marcan
+ *    deshabilitados por ARIA pero NO por el atributo HTML `disabled`.
+ *
+ * Tener UN solo selector evita que trigger e item se desincronicen
+ * (el bug histórico era que ↓ desde trigger saltaba a un item con
+ * aria-disabled, y luego ArrowDown desde ahí lo saltaba — comportamiento
+ * inconsistente).
+ */
+export declare const NAVIGABLE_ITEM_SELECTOR = "[role=\"menuitem\"]:not([disabled]):not([aria-disabled=\"true\"])";

package/dist/components/floating/Tooltip/Tooltip.d.ts

@@ -0,0 +1,194 @@
+import { HTMLProps, ReactElement, ReactNode } from 'react';
+export type TooltipPlacement = "top" | "top-start" | "top-end" | "right" | "right-start" | "right-end" | "bottom" | "bottom-start" | "bottom-end" | "left" | "left-start" | "left-end";
+export type TooltipVariant = "brand" | "secondary" | "success" | "warning" | "danger" | "info";
+export interface TooltipProps {
+    /**
+     * Contenido del tooltip. Acepta `string` (recomendado para a11y) o
+     * `ReactNode` para casos con formatting (negrita, links, fragmentos).
+     *
+     * **A11y — preferir string**: el SR-only `<span role="tooltip">` que
+     * contiene este valor es el referente de `aria-describedby` del child.
+     * Los SR (NVDA, VoiceOver, JAWS) leen el contenido del elemento. Con
+     * `string` el comportamiento está garantizado. Con `ReactNode`
+     * (`<strong>`, `<a>`, fragments) los SR pueden saltar nodos o leer
+     * en orden inesperado dependiendo del rol semántico — el consumer
+     * es responsable de que el contenido sea announce-friendly.
+     *
+     * Si necesitas formatting rich con interacción (links clickables,
+     * botones), considera `Popover` (1.1.0+) en lugar de Tooltip.
+     *
+     * C-01 (gate review): pre-RC1 era `string` puro. Ampliado a
+     * `string | ReactNode` para alinear con `Popover.content` y
+     * `HoverCard.content` futuros (evitar dos APIs hermanas con tipos
+     * incompatibles para conceptos similares).
+     */
+    text: string | ReactNode;
+    /** Posición preferida relativa al child. Por defecto `"top"`. */
+    placement?: TooltipPlacement | undefined;
+    /** Color del tooltip. */
+    variant?: TooltipVariant | undefined;
+    /**
+     * Elemento envuelto (típicamente un `<button>` o `<a>`). Debe ser
+     * un único `ReactElement` HTML — no string, fragment, array ni
+     * `ReactNode` arbitrario. El componente inyecta refs / handlers /
+     * `aria-describedby` vía `cloneElement`, lo que requiere un nodo
+     * elemento concreto.
+     *
+     * H-18 (gate review): el tipo previo `ReactNode` permitía
+     * `<Tooltip text="x">texto</Tooltip>` o arrays/fragments en
+     * tiempo de tipos, pero el control no quedaba asociado al SR.
+     * `ReactElement<HTMLProps<HTMLElement>>` rechaza ese caso en
+     * compile-time.
+     *
+     * D-01 / M-05 (gate review, RC1): el child se renderiza directo
+     * (Slot pattern) — no envuelto en un `<span>`. Tooltip era pre-RC1
+     * un wrapper `<span class="ig-tooltip-wrapper">` que rompía
+     * block-level layouts y obligaba a CSS extra. La eliminación es
+     * **breaking** (consumer con reglas dirigidas a `.ig-tooltip-wrapper`
+     * pierden el target) y se refleja en CHANGELOG.
+     */
+    children: ReactElement<HTMLProps<HTMLElement>>;
+    /** Delay en ms antes de mostrar al hover. Por defecto `0`. */
+    openDelay?: number | undefined;
+    /** Delay en ms antes de ocultar al desactivar. Por defecto `0`. */
+    closeDelay?: number | undefined;
+    /**
+     * Contenedor donde se monta el portal del tooltip. Por defecto
+     * `document.body`. También aplica para CSS containment / shadow roots.
+     *
+     * **Caso típico — Tooltip dentro de Dialog**: `<Dialog>` usa
+     * `<dialog>.showModal()` que crea un top-layer del browser. Si el
+     * portal del tooltip queda en `document.body`, aparece *detrás* del
+     * backdrop del dialog (invisible al usuario). Pasar el ref del
+     * dialog como container hace que el portal viva dentro del top-layer
+     * y se renderice por encima del backdrop.
+     *
+     * Patrón canónico (decisión C-02 documentada en
+     * `docs/decisions/C-02-modal-tooltip-portal.md`):
+     *
+     * ```tsx
+     * function MiPantalla() {
+     *   const dialogRef = useRef<HTMLDialogElement>(null);
+     *   return (
+     *     <Dialog ref={dialogRef} open onClose={...}>
+     *       <DialogBody>
+     *         <Tooltip text="Eliminar" container={dialogRef}>
+     *           <Button>×</Button>
+     *         </Tooltip>
+     *       </DialogBody>
+     *     </Dialog>
+     *   );
+     * }
+     * ```
+     *
+     * Acepta `HTMLElement` directo o un `RefObject` (Floating UI
+     * resuelve ambos).
+     */
+    container?: HTMLElement | React.RefObject<HTMLElement | null> | null | undefined;
+    /**
+     * Cualquier prop adicional (event handlers, `ref`, aria-*, data-*,
+     * etc.) que el consumer pase a Tooltip se forwardea al elemento child
+     * final via el `<Slot>` primitive (D14 Bloque C beta.27).
+     *
+     * Habilita el patrón **nested asChild** crítico para el refactor Slot
+     * DS-wide:
+     *
+     * ```tsx
+     * <DialogClose asChild>
+     *   <Tooltip text="Cancela y cierra">
+     *     <Button variant="danger">×</Button>
+     *   </Tooltip>
+     * </DialogClose>
+     * ```
+     *
+     * El outer Slot de DialogClose pasa props al `<Tooltip>` (close
+     * onClick, ref); Tooltip los recibe en este index signature y los
+     * forwardea al `<Button>` final via su Slot interno. Resultado: el
+     * click en el botón cierra el dialog Y el botón sigue siendo el
+     * anchor del tooltip. Pre-D14 Bloque C: Tooltip dropeaba props del
+     * outer Slot (codex P2 round 2 sobre #109).
+     */
+    [key: string]: unknown;
+}
+/**
+ * Tooltip — wrapper que muestra un texto contextual al hacer hover/focus
+ * sobre el child. Usa **Floating UI** (`@floating-ui/react`) para
+ * positioning robusto:
+ *
+ * - **Portal-out**: el tooltip vive en un `<FloatingPortal>` al final
+ *   de `<body>`, escapando overflow:hidden de cualquier ancestor.
+ * - **`flip` + `shift`**: si no cabe en el placement preferido, salta
+ *   al opuesto o se desplaza para mantenerse visible en el viewport.
+ * - **`offset(8px)`**: separación entre el child y el tooltip.
+ * - **`autoUpdate`**: reposicionamiento al scroll/resize/transform.
+ *
+ * **A11y**:
+ * - El child recibe `aria-describedby` apuntando al span sr-only que
+ *   contiene el `text`. Los lectores de pantalla siempre tienen
+ *   acceso al texto (incluso cuando el portal no está montado).
+ * - El portal flotante usa `role="tooltip"` (gestionado por `useRole`).
+ * - `useDismiss` cierra con Escape. `outsidePress` desactivado: un
+ *   tooltip hover/focus-only no puede dejarse "abierto" por error —
+ *   sale del hover/focus ya cierra. Sin esto, FUI montaría un listener
+ *   global de pointerdown sobre `document` mientras open, ruido sin
+ *   beneficio. Si en el futuro hay un Tooltip click-trigger (poco
+ *   probable; usa Popover para eso), reabrir como prop opt-in.
+ *
+ * **D-01 / M-05 / B-03 / H-01 (RC1)**: refactor a Slot pattern +
+ * primitives layer. El Tooltip ya **no renderiza wrapper span**:
+ * devuelve el child clonado + un sr-only span sibling + el portal.
+ * Esto cierra:
+ *   - **D-01 / M-05**: rompía block-level layouts del consumer porque
+ *     todo se envolvía en `<span class="ig-tooltip-wrapper">`.
+ *   - **H-01 / B-03**: cascade dismiss vía `<FloatingTreeRoot>` +
+ *     `useFloatingNode()` + `<FloatingNode>`. Sin tree, sigue
+ *     funcionando independiente.
+ *
+ * **Migración desde CSS-only (pre-1.0.0-rc.1)**: la API pública
+ * (props text/placement/variant) NO cambia. Las clases
+ * `ig-tooltip-place-*` y `ig-tooltip-*` ahora se aplican al
+ * elemento del portal en lugar del wrapper. Si tenías reglas CSS
+ * dirigidas al wrapper `.ig-tooltip-wrapper` o ref / className en el
+ * `<Tooltip>`, ese wrapper ya no existe: aplica los estilos directo
+ * al child o envuélvelo manualmente.
+ *
+ * **Caveat — Tooltip sobre `<button disabled>` en Firefox** (L-03
+ * gate review): Firefox NO dispara `mouseenter` / `pointerenter` /
+ * `focus` sobre `<button disabled>` (Chrome/Safari sí). El SR-only
+ * span con `aria-describedby` sigue funcionando para lectores de
+ * pantalla, pero el portal visual no aparece al hover. Workaround
+ * canónico: envolver el botón en un `<span>` y aplicar
+ * `pointer-events: none` al botón disabled (el span recibe los
+ * eventos):
+ *
+ * ```tsx
+ * <Tooltip text="Acción no disponible">
+ *   <span style={{ display: "inline-block" }}>
+ *     <Button disabled style={{ pointerEvents: "none" }}>X</Button>
+ *   </span>
+ * </Tooltip>
+ * ```
+ *
+ * El DS no aplica este wrapper automáticamente (Slot pattern: cero
+ * elementos extras silenciosos).
+ *
+ * @example
+ * <Tooltip text="Eliminar" placement="top">
+ *   <Button icon aria-label="Eliminar">×</Button>
+ * </Tooltip>
+ *
+ * @example // overflow:hidden ya NO recorta el tooltip (portal-out)
+ * <div style={{ overflow: "hidden", width: 100 }}>
+ *   <Tooltip text="Texto largo que escapa">
+ *     <Button>Hover</Button>
+ *   </Tooltip>
+ * </div>
+ *
+ * @example // cascade dismiss con FloatingTreeRoot
+ * <FloatingTreeRoot>
+ *   <Popover content={<Tooltip text="..."><Button>Y</Button></Tooltip>}>
+ *     <Button>X</Button>
+ *   </Popover>
+ * </FloatingTreeRoot>
+ */
+export declare function Tooltip({ text, placement, variant, children, openDelay, closeDelay, container, ...outerSlotProps }: TooltipProps): import("react").JSX.Element;

package/dist/components/floating/Tooltip/index.d.ts

@@ -0,0 +1,2 @@
+export { Tooltip } from './Tooltip.js';
+export type { TooltipProps, TooltipPlacement, TooltipVariant, } from './Tooltip.js';

package/dist/components/floating/index.d.ts

@@ -0,0 +1,3 @@
+export * from './primitives/index.js';
+export * from './Tooltip/index.js';
+export * from './Menu/index.js';

package/dist/components/floating/primitives/FloatingTreeRoot.d.ts

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+export interface FloatingTreeRootProps {
+    children: ReactNode;
+}
+/**
+ * FloatingTreeRoot — habilita el cascade dismiss entre `Tooltip`,
+ * `Popover`, `Dropdown` (FUI) y similares cuando se anidan.
+ *
+ * **Comportamiento sin el root**: cada float funciona independiente —
+ * un `Escape` cierra solo el float más interno. Si el consumer abre un
+ * Popover dentro de un Dialog y un Tooltip dentro del Popover, cada
+ * Escape requiere acción separada y los floats no comparten estado de
+ * dismiss.
+ *
+ * **Comportamiento con el root**: los floats se registran en el árbol
+ * de `@floating-ui/react` y comparten el ciclo de dismiss. Un `Escape`
+ * cierra todos los floats abiertos en cascada (más interno → más
+ * externo). `outsidePress` también respeta la jerarquía: clicar dentro
+ * de un float anidado no cierra al ancestro.
+ *
+ * **Cuándo usarlo**: opt-in por consumer. Si tu app no anida floats
+ * (típico en formularios planos / dashboards simples), no lo necesitas
+ * y pagas un context extra sin beneficio. Si tienes Dialog con
+ * Tooltips/Popovers, o menús contextuales con sub-menús, envuelve la
+ * raíz de la app.
+ *
+ * @example
+ * ```tsx
+ * import { FloatingTreeRoot } from "reactigoded";
+ *
+ * function App() {
+ *   return (
+ *     <FloatingTreeRoot>
+ *       <RouterProvider router={router} />
+ *     </FloatingTreeRoot>
+ *   );
+ * }
+ * ```
+ *
+ * H-01 / B-03 (gate review): pre-RC1 los floats no se registraban en
+ * tree, lo que dejaba un bug latente: anidación profunda no cerraba
+ * en cascada. Este wrapper expone la primitiva de FUI sin acoplar al
+ * design system al import específico de `@floating-ui/react` desde el
+ * consumer (le ofrecemos un nombre estable del DS).
+ *
+ * D11 (beta.24 gate review): `FloatingTreeRoot` queda como símbolo
+ * canónico para anidación de floats del DS. El hook subyacente
+ * `useFloatingNode` permanece internal (consumido sólo por Tooltip
+ * / Menu / Popover roadmap del DS via path directo). Si en el
+ * futuro abrimos hooks custom de floats al consumer, este símbolo
+ * sigue siendo el entrypoint.
+ *
+ * @public
+ */
+export declare function FloatingTreeRoot({ children }: FloatingTreeRootProps): import("react").JSX.Element;

package/dist/components/floating/primitives/index.d.ts

@@ -0,0 +1,2 @@
+export { FloatingTreeRoot } from './FloatingTreeRoot.js';
+export type { FloatingTreeRootProps } from './FloatingTreeRoot.js';

package/dist/components/floating/primitives/useFloatingNode.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/components/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Barrel de componentes del design system.
+ *
+ * Cada componente exporta su tipo de props y el componente en sí desde
+ * `./<Componente>/index.ts`.
+ */
+export * from './Accordion/index.js';
+export * from './Alert/index.js';
+export * from './AlertDialog/index.js';
+export * from './Avatar/index.js';
+export * from './Badge/index.js';
+export * from './Breadcrumb/index.js';
+export * from './Button/index.js';
+export * from './Card/index.js';
+export * from './Checkbox/index.js';
+export * from './Chip/index.js';
+export * from './Divider/index.js';
+export * from './Input/index.js';
+export * from './Dialog/index.js';
+export * from './Navbar/index.js';
+export * from './Pagination/index.js';
+export * from './Progress/index.js';
+export * from './Radio/index.js';
+export * from './Rating/index.js';
+export * from './NativeSelect/index.js';
+export * from './Sidebar/index.js';
+export * from './Skeleton/index.js';
+export * from './Slider/index.js';
+export * from './Spinner/index.js';
+export * from './Stepper/index.js';
+export * from './Switch/index.js';
+export * from './Table/index.js';
+export * from './Tabs/index.js';
+export * from './Textarea/index.js';
+export * from './ThemeToggle/index.js';
+export * from './Timeline/index.js';
+export * from './Toast/index.js';
+export * from './floating/index.js';

package/dist/hooks/useControllableState.d.ts

@@ -0,0 +1,152 @@
+export type UseControllableStateBaseOptions<T> = {
+    /**
+     * Valor controlado. Si está definido (≠ undefined), el componente es
+     * controlled — el valor externo manda y `setValue` solo dispara
+     * `onChange`.
+     */
+    value?: T | undefined;
+    /** Callback al cambiar el valor. Disparado en ambos modos. */
+    onChange?: ((value: T) => void) | undefined;
+} & {};
+export interface UseControllableStateInternalOptions<T> extends UseControllableStateBaseOptions<T> {
+    /** Valor inicial uncontrolled. Ignorado si `value` está definido. */
+    defaultValue?: T | undefined;
+    derive?: never;
+    setDerivedValue?: never;
+}
+export interface UseControllableStateDerivedOptions<T> extends UseControllableStateBaseOptions<T> {
+    /**
+     * Valor uncontrolled derivado en cada render desde fuentes externas
+     * (storage, MediaQueryList, otro hook). Debe ser **puro**: no
+     * escribas storage, DOM ni estado dentro.
+     */
+    derive: () => T;
+    /**
+     * Setter de la fuente local React que alimenta `derive()`.
+     *
+     * IMPORTANTE: debe actualizar una fuente React/local que `derive()`
+     * lea. No debe escribir únicamente en una fuente externa como
+     * `localStorage`, porque `useSyncExternalStore` no notifica cambios
+     * same-tab en browsers reales y la UI no se actualizaría tras una
+     * interacción del usuario.
+     *
+     * Ejemplo correcto en ThemeSwitch:
+     *
+     * ```ts
+     * const [override, setOverride] = useState<Theme | null>(null);
+     *
+     * useControllableState({
+     *   derive: () => override ?? stored ?? defaultTheme ?? "dark",
+     *   setDerivedValue: setOverride,
+     * });
+     * ```
+     */
+    setDerivedValue: (next: T) => void;
+    defaultValue?: never;
+}
+/**
+ * Opciones de `useControllableState`.
+ *
+ * Dos modos mutuamente excluyentes garantizados por unión discriminada:
+ *
+ * **Modo interno clásico** — para componentes con state interno simple.
+ *
+ * ```ts
+ * useControllableState({
+ *   value,
+ *   defaultValue,
+ *   onChange,
+ * });
+ * ```
+ *
+ * **Modo derivado** — para componentes cuyo valor uncontrolled deriva de
+ * fuentes externas o compuestas.
+ *
+ * ```ts
+ * useControllableState({
+ *   value,
+ *   derive: () => override ?? stored ?? defaultValue ?? "fallback",
+ *   setDerivedValue: setOverride,
+ *   onChange,
+ * });
+ * ```
+ *
+ * En modo derivado NO pases `defaultValue`; mete el fallback dentro de
+ * `derive()`. TypeScript impide la combinación inválida vía `never`.
+ */
+export type UseControllableStateOptions<T> = UseControllableStateInternalOptions<T> | UseControllableStateDerivedOptions<T>;
+export interface SetValueOptions {
+    /**
+     * Si `true`, NO se invoca `onChange`. Útil para auto-selects internos
+     * y rehidrataciones desde storage que NO son acción del usuario.
+     */
+    silent?: boolean | undefined;
+}
+/**
+ * Acción aceptada por `setValue`: un valor directo `T` o una función
+ * updater `(prev: T) => T` (M-06, RC1) — mismo patrón que `useState`
+ * de React. La updater function recibe el `value` actual del hook
+ * (controlled, derivado o internal según el modo) y debe retornar el
+ * siguiente valor sin mutar el anterior.
+ *
+ * Útil para updates que no dependen del closure del callback:
+ *
+ * ```tsx
+ * <button onClick={() => setValue((prev) => !prev)}>Toggle</button>
+ * ```
+ *
+ * vs. el equivalente con valor directo (depende del closure):
+ *
+ * ```tsx
+ * <button onClick={() => setValue(!value)}>Toggle</button>
+ * ```
+ */
+export type SetValueAction<T> = T | ((prev: T) => T);
+export interface UseControllableStateReturn<T> {
+    /** Valor actual (controlled, derivado o internal). */
+    value: T;
+    /**
+     * Setter que respeta el modo. En controlled solo dispara `onChange`.
+     * Pasa `{ silent: true }` para no notificar al consumer.
+     *
+     * Acepta valor directo `T` o updater function `(prev: T) => T`
+     * (M-06, RC1) — mismo patrón que `useState`.
+     */
+    setValue: (action: SetValueAction<T>, options?: SetValueOptions) => void;
+    /** True si el componente está en modo controlled. */
+    isControlled: boolean;
+}
+/**
+ * Hook para componentes con patrón controlled/uncontrolled.
+ *
+ * Dos modos:
+ * - **Internal** (default): `useState(defaultValue)` para uncontrolled.
+ * - **Derived** (opt-in): `derive()` se computa en render desde una
+ *   fuente externa (storage, MediaQueryList…) y `setDerivedValue` la
+ *   actualiza. Útil cuando el origen del valor uncontrolled es un
+ *   sistema externo y no queremos un `useState` espejo que se
+ *   desincronice.
+ *
+ * `setValue` mantiene identidad estable entre renders (útil para
+ * pasarlo a contextos sin invalidar consumers). `onChange` y el modo
+ * se sincronizan vía refs.
+ *
+ * @example // Modo internal (la mayoría de componentes)
+ * const { value, setValue } = useControllableState({
+ *   value: checked,
+ *   defaultValue: defaultChecked ?? false,
+ *   onChange: onCheckedChange,
+ * });
+ *
+ * @example // Modo derive (ThemeSwitch con useStoredTheme)
+ * const stored = useStoredTheme(storageKey);
+ * const { value, setValue } = useControllableState<Theme>({
+ *   value: themeProp,
+ *   derive: () => stored ?? defaultTheme ?? "dark",
+ *   setDerivedValue: (next) => writeStoredTheme(storageKey, next),
+ *   onChange: onValueChange,
+ * });
+ *
+ * @public
+ */
+export declare function useControllableState<T>(options: UseControllableStateOptions<T>): UseControllableStateReturn<T>;

package/dist/hooks/useTheme.d.ts

@@ -0,0 +1,44 @@
+export type Theme = "light" | "dark";
+export interface UseThemeReturn {
+    theme: Theme;
+    setTheme: (theme: Theme) => void;
+    toggleTheme: () => void;
+}
+/**
+ * Hook para manejar el tema (light/dark).
+ *
+ * El atributo `data-theme` de `<html>` es la única fuente de verdad: el
+ * hook lo observa con un `MutationObserver` vía `useSyncExternalStore`
+ * y se mantiene sincronizado con cualquier escritor (otro `useTheme`,
+ * `<ThemeSwitch>`, el script anti-flash del README o código del
+ * consumer). `setTheme` escribe el atributo y deja que el observer
+ * propague el cambio.
+ *
+ * **SSR**: en el servidor devuelve `dark` (default dark-first del DS
+ * desde `1.0.0-beta.3`). Hidrata en cliente leyendo el atributo. Para
+ * evitar el flash inicial, inyecta el script anti-flash documentado en
+ * el README §"Tema light/dark".
+ *
+ * @example
+ * function ThemeToggle() {
+ *   const { theme, toggleTheme } = useTheme();
+ *   return (
+ *     <button type="button" onClick={toggleTheme} aria-label={`Tema actual: ${theme}`}>
+ *       {theme === "dark" ? "☀" : "🌙"}
+ *     </button>
+ *   );
+ * }
+ *
+ * @example
+ * // Forzar tema desde una preferencia de usuario.
+ * function SettingsPanel({ pref }: { pref: "light" | "dark" | "auto" }) {
+ *   const { setTheme } = useTheme();
+ *   useEffect(() => {
+ *     if (pref !== "auto") setTheme(pref);
+ *   }, [pref, setTheme]);
+ *   return null;
+ * }
+ *
+ * @public
+ */
+export declare function useTheme(): UseThemeReturn;

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Igoded Design System — entry point del paquete.
+ *
+ * Arquitectura CSS modular (estable desde `1.0.0-beta.3`):
+ *
+ *   tokens.css       solo variables --ig-* + keyframes + @font-face
+ *                    (cero selectores globales, ~98 KB).
+ *   base.css         globales mínimos: box-sizing + html + scrollbars +
+ *                    ::selection + prefers-reduced-motion / contrast /
+ *                    forced-colors. Garantías a11y. Requiere tokens.
+ *   components.css   utilities + componentes (clases .ig-*). Requiere
+ *                    tokens + base.
+ *   design.css       meta: @import de tokens + base + components.
+ *
+ *   reset.css        estilos por defecto para HTML nativo (h1-h6, p, a,
+ *                    button, input, table…). Opt-in.
+ *   state.css        utilities pseudo-class (hover:, focus:). ~6.5 MB sin gzip / ~700 KB gzipped. Opt-in.
+ *   all.css          atajo: design + reset + state.
+ *
+ * USO POR ESCENARIO:
+ *
+ *   import "reactigoded/styles/design.css";              // DS completo
+ *
+ *   import "reactigoded/styles/design.css";
+ *   import "reactigoded/styles/reset.css";               // DS + HTML nativo
+ *
+ *   import "reactigoded/styles/tokens.css";              // solo tokens
+ *
+ *   import "reactigoded/styles/tokens.css";
+ *   import "reactigoded/styles/base.css";                // tokens + a11y
+ *                                                        // baseline
+ */
+export * from './components/index.js';
+export { useTheme, type Theme, type UseThemeReturn } from './hooks/useTheme.js';
+export { useControllableState, type SetValueOptions, type UseControllableStateOptions, type UseControllableStateReturn, } from './hooks/useControllableState.js';
+export { cn } from './utils/cn.js';