@walrosproject/ui 0.3.3 → 0.4.0

package/README.md

@@ -1,271 +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
-
-```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" }}
-/>
-```
+## Cambio de tema completo
 
-## 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` une la entrada negra con la silueta de la morsa, el glitch visual y el sonido de walros.org. El portal acelera durante **900 ms** con la curva `power2.in`; 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 imagen del logo se precarga y la pantalla permanece negra mientras termina de cargar, como en la portada.
 
 ```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`,
-guarda el valor en `localStorage` con la clave `walros-theme` y conserva los
-tiempos oficiales de WalrOS Forum: cambio a los 220 ms y final a los 720 ms.
-
+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.
 
-## Modos del glitch de tema
-
-### `body`: comportamiento original de WalrOS Forum
-
-Para páginas normales, sin escenas fijadas ni parallax complejo:
+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
-const {
-  theme,
-  glitching,
-  toggleTheme,
-} = useWalrosTheme({
-  mode: "body",
+const theme = useWalrosTheme({
+  mode: "viewport",
+  shakeTargets: [sceneRef],
+  onAfterUnlock: () => ScrollTrigger.update(),
 });
 ```
 
-El paquete aplica el shake al `body`, mantiene los tiempos oficiales y cada
-producto sigue diseñando su propio botón.
+`WalrosThemeGlitch` sigue disponible como componente individual para proyectos que solo necesiten ese efecto.
 
-### `viewport`: páginas con parallax, sticky o GSAP ScrollTrigger
+## Portal de entrada
 
-Usa una capa estable que cubra la escena visible. No apuntes a un elemento que
-GSAP esté transformando directamente; utiliza preferiblemente un wrapper.
+El componente completo muestra el logo cromado bajo la máscara negra y calcula el punto de partida con sus proporciones visibles:
 
 ```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>
-  );
-}
+<WalrosPortalTransition storageMode="always" />
 ```
 
-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.
-
-Los tiempos predeterminados siguen siendo 220 ms para cambiar el tema y
-720 ms para terminar la transición.
-
-## 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.
-
-El resultado es una única silueta que crece y revela la aplicación. La duración
-oficial por defecto es `900` ms.
+`storageMode` acepta `always`, `session` y `once`. La duración predeterminada es **900 ms**. 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
+<Walros3DPortalTransition
+  origin={{ centerX, centerY, width, height }}
+  onComplete={() => setIntroComplete(true)}
+/>
+```
 
+`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.
 
-## Valores predeterminados del portal desde 0.3.3
+## Cursor
 
-`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

@@ -10,7 +10,42 @@ type WalrosPortalTransitionProps = {
     storageKey?: string;
     zIndex?: number;
 };
-declare function WalrosPortalTransition({ duration, onComplete, backgroundColor, enabled, storageMode, storageKey, zIndex, }: WalrosPortalTransitionProps): react.JSX.Element | null;
+/** Exact walros.org black portal, including its chrome logo and 900 ms curve. */
+declare function WalrosPortalTransition({ duration, onComplete, backgroundColor, enabled, storageMode, storageKey, zIndex, }: WalrosPortalTransitionProps): react.ReactPortal | null;
+
+type PortalOrigin = {
+    centerX: number;
+    centerY: number;
+    width: number;
+    height: number;
+};
+type Walros3DPortalTransitionProps = {
+    origin: PortalOrigin;
+    onComplete?: () => void;
+    duration?: number;
+    backgroundColor?: string;
+    zIndex?: number;
+    lockScroll?: boolean;
+};
+declare function Walros3DPortalTransition({ origin, onComplete, duration, backgroundColor, zIndex, lockScroll, }: Walros3DPortalTransitionProps): react.JSX.Element | null;
+
+type WalrosThemeTransitionProps = {
+    /** Pass the `glitching` value returned by `useWalrosTheme`. */
+    active: boolean;
+    /** The walros.org portal takes 900 ms. */
+    portalDuration?: number;
+    /** The same chrome logo used under the portal on walros.org. */
+    logoUrl?: string;
+    zIndex?: number;
+};
+/**
+ * A ready-to-use walros.org theme transition. The portal runs for 900 ms,
+ * while the matching glitch and sound from useWalrosTheme run for 1,500 ms.
+ * Mount once near the app root and pass `active={glitching}`.
+ */
+declare function WalrosThemeTransition({ active, portalDuration, logoUrl, 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;
@@ -20,11 +55,6 @@ type WalrosWordmarkProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> & {
 };
 declare function WalrosWordmark({ variant, alt, draggable, ...props }: WalrosWordmarkProps): react.JSX.Element;
 
-declare const walrosPortalSilhouetteUrl: string;
-declare const walrosLogoChromeUrl: string;
-declare const walrosWordmarkLightUrl: string;
-declare const walrosWordmarkDarkUrl: string;
-
 type WalrosThemeGlitchProps = {
     active: boolean;
     zIndex?: number;
@@ -42,6 +72,10 @@ type UseWalrosThemeOptions = {
     useSystemPreference?: boolean;
     swapDelay?: number;
     totalDuration?: number;
+    /** Set to false to disable audio, or provide a custom sound URL. */
+    soundUrl?: string | false;
+    /** Playback volume from 0 to 1. Defaults to the WalrOS site mix. */
+    soundVolume?: number;
     applyTheme?: (theme: WalrosTheme) => void;
     /**
      * `body` reproduce el comportamiento original de WalrOS Forum.
@@ -67,6 +101,12 @@ type UseWalrosThemeResult = {
     toggleTheme: () => void;
     setTheme: (theme: WalrosTheme) => void;
 };
-declare function useWalrosTheme({ storageKey, defaultTheme, useSystemPreference, swapDelay, totalDuration, applyTheme, mode, shakeTargets, lockScroll, onAfterUnlock, }?: UseWalrosThemeOptions): UseWalrosThemeResult;
+declare function useWalrosTheme({ storageKey, defaultTheme, useSystemPreference, swapDelay, totalDuration, soundUrl, soundVolume, applyTheme, mode, shakeTargets, lockScroll, onAfterUnlock, }?: UseWalrosThemeOptions): UseWalrosThemeResult;
+
+declare const walrosPortalSilhouetteUrl: string;
+declare const walrosLogoChromeUrl: string;
+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, 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 };