@walrosproject/ui 0.3.4 → 0.4.1

package/README.md

@@ -1,280 +1,89 @@
 # @walrosproject/ui
 
-Componentes y recursos visuales oficiales del ecosistema **WalrOS**.
-
-## Contenido inicial
-
-- `WalrosPortalTransition`
-- `WalrosLogo`
-- `WalrosWordmark`
-- URLs exportadas de los assets oficiales
-
-## Instalación
+Transición, cambio de tema y cursor oficiales de WalrOS para proyectos React.
 
 ```bash
 npm install @walrosproject/ui
 ```
 
-## Transición de entrada
+## Cambio de tema completo
 
-```tsx
-import { WalrosPortalTransition } from "@walrosproject/ui";
-
-export default function App() {
-  return (
-    <>
-      <WalrosPortalTransition storageMode="always" />
-      <main>Contenido de la aplicación</main>
-    </>
-  );
-}
-```
-
-Modos disponibles:
-
-```tsx
-<WalrosPortalTransition storageMode="always" />
-<WalrosPortalTransition storageMode="session" />
-<WalrosPortalTransition storageMode="once" />
-```
-
-- `always`: se reproduce en cada carga completa.
-- `session`: una vez por pestaña o sesión.
-- `once`: una sola vez mediante `localStorage`.
-
-## Logo
-
-```tsx
-import { WalrosLogo } from "@walrosproject/ui";
-
-<WalrosLogo
-  style={{ width: 120, height: "auto" }}
-/>
-```
-
-## Wordmark
-
-```tsx
-import { WalrosWordmark } from "@walrosproject/ui";
-
-<WalrosWordmark
-  variant="light"
-  style={{ width: 320, height: "auto" }}
-/>
-
-<WalrosWordmark
-  variant="dark"
-  style={{ width: 320, height: "auto" }}
-/>
-```
-
-## Desarrollo
-
-```bash
-npm install
-npm run check
-npm run build
-npm run pack:check
-```
-
-## Primera publicación
-
-Activa 2FA en npm y ejecuta:
-
-```bash
-npm login
-npm publish --access public
-```
-
-El script `prepublishOnly` valida TypeScript y genera `dist` automáticamente.
-
-## Publicaciones posteriores
-
-Actualiza la versión antes de publicar:
-
-```bash
-npm version patch
-npm publish
-```
-
-Usa `minor` para nuevas funciones compatibles y `major` para cambios incompatibles.
-
-## Marca y licencia
-
-El código y los recursos se distribuyen bajo los términos indicados en `LICENSE`.
-WalrOS, su nombre y sus recursos gráficos siguen siendo propiedad de Alexander Calle.
-
-## Transición oficial de tema
-
-Cada producto diseña su propio botón, pero todos disparan la misma animación:
+`WalrosThemeTransition` muestra exclusivamente el glitch visual de walros.org: bandas, destellos y sacudida de la página, sin silueta ni logo. El glitch dura **1.500 ms**; el tema cambia a los **610 ms** y el audio se detiene al concluir los **1.500 ms**. La entrada de la página es un componente independiente.
 
 ```tsx
 import {
-  WalrosThemeGlitch,
+  WalrosThemeTransition,
+  DirectionalCursor,
   useWalrosTheme,
 } from "@walrosproject/ui";
 
-export default function App() {
-  const {
-    theme,
-    isDark,
-    mounted,
-    glitching,
-    toggleTheme,
-  } = useWalrosTheme();
-
-  if (!mounted) return null;
+export function App() {
+  const { theme, glitching, toggleTheme } = useWalrosTheme();
 
   return (
     <>
-      <button
-        type="button"
-        onClick={toggleTheme}
-        disabled={glitching}
-        style={{
-          background: isDark ? "#1d4ed8" : "#06b6d4",
-          color: "#fff",
-        }}
-      >
-        Cambiar tema
+      <button type="button" onClick={toggleTheme} disabled={glitching}>
+        Tema: {theme}
       </button>
-
-      <WalrosThemeGlitch active={glitching} />
-
-      <main>Tema actual: {theme}</main>
+      <WalrosThemeTransition active={glitching} />
+      <DirectionalCursor />
     </>
   );
 }
 ```
 
-El hook aplica por defecto la clase `dark` en `document.documentElement` y
-guarda el valor en `localStorage` con la clave `walros-theme`. El cambio visual
-se ejecuta con la transición de 1,5 s de WalrOS; el tema cambia a los 610 ms y
-el sonido oficial se reproduce al activar `toggleTheme()` desde una interacción
-del usuario. El volumen predeterminado es 0,52.
+El hook guarda `walros-theme` en `localStorage` y aplica la clase `dark` al elemento raíz. Usa `applyTheme` si tu proyecto utiliza otra convención. El sonido oficial está incluido, a volumen `0.52`. Puedes desactivarlo o sustituirlo con `soundUrl: false` o una URL propia. La reproducción debe iniciarse con `toggleTheme()` desde una interacción del usuario para respetar las restricciones de audio de los navegadores.
 
-El efecto de sonido se puede desactivar o sustituir:
+Para escenas parallax o GSAP, utiliza `mode: "viewport"` y pasa un wrapper estable en `shakeTargets`. `onAfterUnlock` permite actualizar ScrollTrigger después de restaurar el scroll. En páginas convencionales, el modo predeterminado `body` reproduce el movimiento de WalrOS.
 
 ```tsx
-useWalrosTheme({ soundUrl: false });
-useWalrosTheme({ soundUrl: "/audio/mi-cambio-de-tema.mp3", soundVolume: 0.4 });
+const theme = useWalrosTheme({
+  mode: "viewport",
+  shakeTargets: [sceneRef],
+  onAfterUnlock: () => ScrollTrigger.update(),
+});
 ```
 
+`WalrosThemeGlitch` sigue disponible como componente individual para proyectos que solo necesiten ese efecto.
 
-## Modos del glitch de tema
-
-### `body`: comportamiento original de WalrOS Forum
+## Portal de entrada
 
-Para páginas normales, sin escenas fijadas ni parallax complejo:
+`WalrosPortalTransition` muestra la morsa cromada **debajo** de la máscara negra y la acerca al centro mientras se abre el portal. Dura **900 ms** y no espera a que se descargue la imagen para iniciar; el logo desaparece antes de que se revele la página.
 
 ```tsx
-const {
-  theme,
-  glitching,
-  toggleTheme,
-} = useWalrosTheme({
-  mode: "body",
-});
+<WalrosPortalTransition storageMode="always" />
 ```
 
-El paquete aplica el shake al `body`, mantiene los tiempos oficiales y cada
-producto sigue diseñando su propio botón.
-
-### `viewport`: páginas con parallax, sticky o GSAP ScrollTrigger
-
-Usa una capa estable que cubra la escena visible. No apuntes a un elemento que
-GSAP esté transformando directamente; utiliza preferiblemente un wrapper.
+`storageMode` acepta `always`, `session` y `once`. Para usar el modelo 3D real de walros.org como fondo, renderízalo en tu escena y pasa sus límites proyectados a `Walros3DPortalTransition`:
 
 ```tsx
-import { useRef } from "react";
-import {
-  WalrosThemeGlitch,
-  useWalrosTheme,
-} from "@walrosproject/ui";
-
-export function Hero() {
-  const sceneRef = useRef<HTMLDivElement>(null);
-  const buttonRef = useRef<HTMLButtonElement>(null);
-
-  const {
-    theme,
-    glitching,
-    toggleTheme,
-  } = useWalrosTheme({
-    mode: "viewport",
-    shakeTargets: [sceneRef, buttonRef],
-    onAfterUnlock: () => {
-      // Opcional: ScrollTrigger.update();
-    },
-  });
-
-  return (
-    <section className="relative overflow-hidden">
-      <div ref={sceneRef} className="absolute inset-0">
-        {/* escena visible */}
-      </div>
-
-      <button
-        ref={buttonRef}
-        type="button"
-        onClick={toggleTheme}
-        disabled={glitching}
-      >
-        Tema: {theme}
-      </button>
-
-      <WalrosThemeGlitch active={glitching} />
-    </section>
-  );
-}
+<Walros3DPortalTransition
+  origin={{ centerX, centerY, width, height }}
+  onComplete={() => setIntroComplete(true)}
+/>
 ```
 
-En este modo el paquete:
-
-- guarda la posición actual del scroll;
-- la mantiene estable con `requestAnimationFrame` y `window.scrollTo`;
-- no usa `position: fixed` ni transforma el `body`;
-- aplica el shake solamente a `shakeTargets`;
-- restaura `overflow` y la posición al terminar;
-- ejecuta `onAfterUnlock` para actualizar GSAP u otra librería.
-
-La transición dura 1.500 ms por defecto y cambia el tema en el punto de 610 ms,
-sin alterar las opciones de bloqueo de scroll ni las de `ScrollTrigger`.
-
-## Compatibilidad de `WalrosPortalTransition`
-
-Desde la versión `0.3.1`, la silueta del portal se dibuja directamente dentro
-del SVG del componente. La transición ya no depende de que Vite, Bun u otro
-empaquetador resuelva un archivo SVG externo desde `node_modules`, evitando
-portales deformados o sin la morsa al consumir el paquete desde otras apps.
-
-## Portal con una sola silueta
-
-Desde `0.3.2`, `WalrosPortalTransition` usa el SVG oficial exacto de WalrOS
-como una URL de datos dentro de un único elemento SVG `<image>` dentro de la
-máscara. Se ha eliminado la segunda copia azul desenfocada que podía hacer que
-la morsa pareciera doble durante el acercamiento.
+`walrosLogo3DUrl` se importa desde `@walrosproject/ui/model` y exporta el GLB oficial solo cuando un proyecto necesita cargarlo; `walrosPortalSilhouetteUrl` exporta la silueta. El componente ya incluye las tres rutas de la máscara, sin descargar ni analizar un SVG en tiempo de ejecución.
 
-El resultado es una única silueta que crece y revela la aplicación. La duración
-oficial por defecto es `900` ms.
+## Cursor
 
-
-
-## Valores predeterminados del portal desde 0.3.3
-
-`WalrosPortalTransition` usa ahora estos valores cuando no se indican props:
+`DirectionalCursor` copia el cursor ajustado de walros.org: 20 × 22 px, seguimiento suave, orientación según la dirección del ratón y estabilización al detenerse. Solo sustituye el cursor nativo con puntero preciso, hover, pantalla de al menos 1024 px y movimiento permitido. En controles y campos de texto conserva el cursor adecuado.
 
 ```tsx
-<WalrosPortalTransition />
+<DirectionalCursor />
 ```
 
-equivale a:
+## Otros recursos
 
-```tsx
-<WalrosPortalTransition
-  duration={900}
-  backgroundColor="#000000"
-/>
+El paquete conserva `WalrosLogo`, `WalrosWordmark` y sus URLs de imagen. Todos los componentes funcionan con React 18 y 19. El portal y el glitch respetan `prefers-reduced-motion`.
+
+## Desarrollo y publicación
+
+```bash
+npm install
+npm run check
+npm run build
+npm run pack:check
 ```
 
-Los valores siguen pudiendo sobrescribirse por proyecto mediante props.
+El código y los recursos se distribuyen bajo los términos de `LICENSE`. WalrOS y sus elementos visuales pertenecen a Alexander Calle.

package/dist/index.d.ts

@@ -1,6 +1,24 @@
 import * as react from 'react';
 import { ImgHTMLAttributes, CSSProperties, RefObject } from 'react';
 
+type PortalOrigin = {
+    centerX: number;
+    centerY: number;
+    width: number;
+    height: number;
+};
+type Walros3DPortalTransitionProps = {
+    origin: PortalOrigin;
+    onComplete?: () => void;
+    duration?: number;
+    backgroundColor?: string;
+    zIndex?: number;
+    lockScroll?: boolean;
+    /** An optional image that follows the portal exactly and fades before reveal. */
+    logoUrl?: string | false;
+};
+declare function Walros3DPortalTransition({ origin, onComplete, duration, backgroundColor, zIndex, lockScroll, logoUrl, }: Walros3DPortalTransitionProps): react.JSX.Element | null;
+
 type WalrosPortalTransitionProps = {
     duration?: number;
     onComplete?: () => void;
@@ -9,8 +27,27 @@ type WalrosPortalTransitionProps = {
     storageMode?: "always" | "session" | "once";
     storageKey?: string;
     zIndex?: number;
+    /** Projected bounds of an existing 3D logo, as on walros.org. */
+    origin?: PortalOrigin;
+    /** Intro logo shown beneath the black mask; set false when using an existing 3D logo. */
+    logoUrl?: string | false;
+};
+/** 900 ms walros.org entrance, with the logo confined below its black mask. */
+declare function WalrosPortalTransition({ duration, onComplete, backgroundColor, enabled, storageMode, storageKey, zIndex, origin, logoUrl, }: WalrosPortalTransitionProps): react.ReactPortal | null;
+
+type WalrosThemeTransitionProps = {
+    /** Pass the `glitching` value returned by `useWalrosTheme`. */
+    active: boolean;
+    /** @deprecated The theme change has no portal; retained for source compatibility. */
+    portalDuration?: number;
+    /** @deprecated The theme change has no logo; retained for source compatibility. */
+    logoUrl?: string;
+    zIndex?: number;
 };
-declare function WalrosPortalTransition({ duration, onComplete, backgroundColor, enabled, storageMode, storageKey, zIndex, }: WalrosPortalTransitionProps): react.JSX.Element | null;
+/** The walros.org theme effect is a shake and glitch, without an intro logo. */
+declare function WalrosThemeTransition({ active, zIndex, }: WalrosThemeTransitionProps): react.ReactPortal | null;
+
+declare function DirectionalCursor(): react.JSX.Element;
 
 type WalrosLogoProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src">;
 declare function WalrosLogo({ alt, draggable, ...props }: WalrosLogoProps): react.JSX.Element;
@@ -74,4 +111,4 @@ declare const walrosWordmarkLightUrl: string;
 declare const walrosWordmarkDarkUrl: string;
 declare const walrosThemeGlitchSoundUrl: string;
 
-export { type UseWalrosThemeOptions, type UseWalrosThemeResult, WalrosLogo, type WalrosLogoProps, WalrosPortalTransition, type WalrosPortalTransitionProps, type WalrosTheme, WalrosThemeGlitch, type WalrosThemeGlitchProps, type WalrosThemeMode, type WalrosThemeShakeTarget, WalrosWordmark, type WalrosWordmarkProps, useWalrosTheme, walrosLogoChromeUrl, walrosPortalSilhouetteUrl, walrosThemeGlitchSoundUrl, walrosWordmarkDarkUrl, walrosWordmarkLightUrl };
+export { DirectionalCursor, type PortalOrigin, type UseWalrosThemeOptions, type UseWalrosThemeResult, Walros3DPortalTransition, type Walros3DPortalTransitionProps, WalrosLogo, type WalrosLogoProps, WalrosPortalTransition, type WalrosPortalTransitionProps, type WalrosTheme, WalrosThemeGlitch, type WalrosThemeGlitchProps, type WalrosThemeMode, type WalrosThemeShakeTarget, WalrosThemeTransition, type WalrosThemeTransitionProps, WalrosWordmark, type WalrosWordmarkProps, useWalrosTheme, walrosLogoChromeUrl, walrosPortalSilhouetteUrl, walrosThemeGlitchSoundUrl, walrosWordmarkDarkUrl, walrosWordmarkLightUrl };