@mlola-ui/scene 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mlola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# @mlola-ui/scene
+
+Optional, lightweight spatial presentation for Mlola UI: perspective stages,
+depth layers, card stacks, and mesh gradients. WebGL is not required, and a
+scene effect always has a static fallback for reduced motion, reduced data, and
+assistive technology.
+
+## Install
+
+```bash
+npm install @mlola-ui/scene
+```
+
+## Use
+
+```tsx
+import { CardStack3D, MeshGradient, Stage } from "@mlola-ui/scene";
+
+<Stage depth={2}><CardStack3D cards={cards} /></Stage>;
+```
+
+## Exports
+
+| Path | What it is |
+| --- | --- |
+| `@mlola-ui/scene` | `Stage`, `CardStack3D`, `MeshGradient`, `SpatialToggle` |
+| `@mlola-ui/scene/scene.css` | the scene layer |
+
+Requires React and ReactDOM 18 or newer as peers. Scene effects are
+non-semantic and never the only way to reach content.
+
+MIT licensed. Part of [Mlola UI](https://ui.mlola.com).

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@mlola-ui/scene",
+  "version": "1.0.0",
+  "description": "Optional lightweight spatial presentation for Mlola UI",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "sideEffects": [
+    "./src/scene.css"
+  ],
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./stage": "./src/stage.tsx",
+    "./primitives": "./src/primitives.tsx",
+    "./scene.css": "./src/scene.css"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "license": "MIT",
+  "author": "Mlola",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mlolahq/mlola-ui.git",
+    "directory": "packages/scene"
+  },
+  "homepage": "https://ui.mlola.com",
+  "bugs": {
+    "url": "https://github.com/mlolahq/mlola-ui/issues"
+  },
+  "keywords": [
+    "mlola",
+    "ui",
+    "3d",
+    "scene",
+    "perspective",
+    "css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module"
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./primitives";
+export * from "./spatial-toggle";
+export * from "./stage";

package/src/primitives.tsx

@@ -0,0 +1,156 @@
+"use client";
+
+import * as React from "react";
+import { useReducedMotion } from "./use-reduced-motion";
+
+export interface MeshGradientProps extends React.HTMLAttributes<HTMLDivElement> {
+  animated?: boolean;
+  blur?: number;
+}
+
+export const MeshGradient = React.forwardRef<HTMLDivElement, MeshGradientProps>(
+  ({ animated = true, blur = 50, style, ...props }, ref) => {
+    const reducedMotion = useReducedMotion();
+    const shouldAnimate = animated && !reducedMotion;
+    return (
+      <div
+        {...props}
+        ref={ref}
+        aria-hidden="true"
+        style={{
+          position: "absolute",
+          inset: 0,
+          pointerEvents: "none",
+          overflow: "hidden",
+          backgroundImage: `
+            radial-gradient(circle at 18% 25%, color-mix(in srgb, var(--ml-primary) 22%, transparent), transparent 55%),
+            radial-gradient(circle at 82% 70%, color-mix(in srgb, var(--ml-primary, var(--primary)) 14%, transparent), transparent 60%),
+            radial-gradient(circle at 50% 90%, color-mix(in srgb, var(--ml-accent, var(--accent)) 30%, transparent), transparent 70%)
+          `,
+          filter: `blur(${Math.max(0, Math.min(160, Number.isFinite(blur) ? blur : 50))}px)`,
+          animation: shouldAnimate ? "float-3d 14s ease-in-out infinite" : undefined,
+          ...style,
+        }}
+      />
+    );
+  }
+);
+MeshGradient.displayName = "MeshGradient";
+
+export interface CardStack3DItem {
+  title: string;
+  subtitle: string;
+  tag: string;
+}
+
+export interface CardStack3DProps extends React.HTMLAttributes<HTMLDivElement> {
+  cards: CardStack3DItem[];
+}
+
+function joinClasses(...values: Array<string | false | null | undefined>) {
+  return values.filter(Boolean).join(" ");
+}
+
+export function CardStack3D({
+  cards,
+  className = "",
+  onPointerEnter,
+  onPointerLeave,
+  onFocus,
+  onBlur,
+  ...props
+}: CardStack3DProps) {
+  const [active, setActive] = React.useState(false);
+  const reducedMotion = useReducedMotion();
+  return (
+    <div
+      {...props}
+      tabIndex={props.tabIndex ?? 0}
+      aria-label={props["aria-label"] ?? "Card stack"}
+      onPointerEnter={(event) => {
+        onPointerEnter?.(event);
+        if (event.pointerType !== "touch") setActive(true);
+      }}
+      onPointerLeave={(event) => {
+        onPointerLeave?.(event);
+        setActive(false);
+      }}
+      onFocus={(event) => {
+        onFocus?.(event);
+        setActive(true);
+      }}
+      onBlur={(event) => {
+        onBlur?.(event);
+        if (!event.currentTarget.contains(event.relatedTarget)) setActive(false);
+      }}
+      className={joinClasses("ml-scene-card-stack", className)}
+    >
+      {cards.slice(0, 3).map((card, index) => {
+        const layer = 2 - index;
+        const fanDown = active ? layer * 18 : layer * 6;
+        const fanScale = active ? 1 - layer * 0.03 : 1 - layer * 0.04;
+        const rotateZ = active ? (index - 1) * 2.5 : 0;
+        return (
+          <div
+            key={`${card.title}-${index}`}
+            className="ml-scene-card-stack-item"
+            style={{
+              transform: `translate3d(0, ${fanDown}px, ${index * 12}px) rotateZ(${rotateZ}deg) scale(${fanScale})`,
+              transformOrigin: "top center",
+              zIndex: index + 10,
+              boxShadow: active
+                ? "0 18px 38px -10px color-mix(in srgb, var(--foreground) 14%, transparent), 0 0 0 1px color-mix(in srgb, var(--border) 90%, transparent)"
+                : "0 8px 20px -6px color-mix(in srgb, var(--foreground) 8%, transparent), 0 0 0 1px color-mix(in srgb, var(--border) 70%, transparent)",
+              transition: reducedMotion
+                ? "none"
+                : "transform 300ms cubic-bezier(0.16, 1, 0.3, 1), box-shadow 300ms cubic-bezier(0.16, 1, 0.3, 1)",
+            }}
+          >
+            <div className="ml-scene-card-stack-header">
+              <span className="ml-scene-card-stack-tag">{card.tag}</span>
+              <span className="ml-scene-card-stack-index">0{index + 1}</span>
+            </div>
+            <div>
+              <p className="ml-scene-card-stack-title">{card.title}</p>
+              <p className="ml-scene-card-stack-subtitle">{card.subtitle}</p>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+export interface DeviceFrame3DProps extends React.HTMLAttributes<HTMLDivElement> {
+  tilt?: boolean;
+}
+
+export function DeviceFrame3D({
+  children,
+  className = "",
+  tilt = true,
+  style,
+  ...props
+}: DeviceFrame3DProps) {
+  const reducedMotion = useReducedMotion();
+  return (
+    <div
+      {...props}
+      className={joinClasses("ml-scene-device-frame", className)}
+      style={{
+        background: "linear-gradient(145deg, oklch(35% 0.02 260), oklch(18% 0.015 260))",
+        boxShadow: "0 30px 70px -15px oklch(0% 0 0 / 0.5), inset 0 1px 2px oklch(100% 0 0 / 0.2)",
+        transform: tilt && !reducedMotion ? "rotateX(1deg) rotateY(-2deg)" : undefined,
+        transformStyle: "preserve-3d",
+        ...style,
+      }}
+    >
+      <div className="ml-scene-device-screen">
+        <div className="ml-scene-device-notch">
+          <span className="ml-scene-device-notch-dot" aria-hidden="true" />
+        </div>
+        <div className="ml-scene-device-content">{children}</div>
+      </div>
+    </div>
+  );
+}

package/src/scene.css

@@ -0,0 +1,140 @@
+@layer mlola.scene {
+  .ml-scene-card-stack {
+    position: relative;
+    width: 100%;
+    height: 11rem;
+    cursor: pointer;
+    perspective: 1000px;
+    user-select: none;
+  }
+
+  .ml-scene-card-stack-item {
+    position: absolute;
+    inset-inline: 0;
+    top: 0;
+    display: flex;
+    flex-direction: column;
+    justify-content: space-between;
+    height: 9rem;
+    padding: 1.25rem;
+    border: 1px solid color-mix(in srgb, var(--border) 90%, transparent);
+    border-radius: var(--ml-radius-lg, 1rem);
+    background: var(--card);
+  }
+
+  .ml-scene-card-stack-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  .ml-scene-card-stack-tag {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.125rem 0.625rem;
+    border-radius: 9999px;
+    background: color-mix(in srgb, var(--signal) 15%, transparent);
+    color: var(--signal);
+    font-family: var(--ml-font-mono);
+    font-size: 10px;
+    font-weight: 600;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+  }
+
+  .ml-scene-card-stack-index {
+    color: var(--muted-foreground);
+    font-family: var(--ml-font-mono);
+    font-size: 0.75rem;
+  }
+
+  .ml-scene-card-stack-title {
+    color: var(--foreground);
+    font-size: 0.875rem;
+    font-weight: 700;
+    letter-spacing: -0.025em;
+  }
+
+  .ml-scene-card-stack-subtitle {
+    margin-top: 0.125rem;
+    color: var(--muted-foreground);
+    font-size: 0.75rem;
+  }
+
+  .ml-scene-device-frame {
+    position: relative;
+    margin-inline: auto;
+    padding: 0.75rem;
+    border-radius: 38px;
+    perspective: 1000px;
+    box-shadow: 0 25px 50px -12px oklch(0% 0 0 / 0.25);
+  }
+
+  .ml-scene-device-screen {
+    position: relative;
+    overflow: hidden;
+    border: 1px solid color-mix(in srgb, var(--border) 80%, transparent);
+    border-radius: 28px;
+    background: var(--background);
+  }
+
+  .ml-scene-device-notch {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 7rem;
+    height: 1rem;
+    margin: 0.625rem auto;
+    border-radius: 9999px;
+    background: color-mix(in srgb, var(--foreground) 20%, transparent);
+  }
+
+  .ml-scene-device-notch-dot {
+    width: 0.5rem;
+    height: 0.5rem;
+    border-radius: 9999px;
+    background: color-mix(in srgb, var(--foreground) 40%, transparent);
+  }
+
+  .ml-scene-device-content {
+    padding: 1rem;
+  }
+
+  .ml-scene-spatial-toggle {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.75rem;
+    user-select: none;
+  }
+
+  .ml-scene-spatial-switch {
+    position: relative;
+    width: 3rem;
+    height: 1.75rem;
+    padding: 0.25rem;
+    border: none;
+    border-radius: 9999px;
+    box-shadow: inset 0 2px 4px oklch(0% 0 0 / 0.25);
+    cursor: pointer;
+  }
+
+  .ml-scene-spatial-switch:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+
+  .ml-scene-spatial-thumb {
+    display: block;
+    width: 1.25rem;
+    height: 1.25rem;
+    border-radius: 9999px;
+    background: oklch(1 0 0);
+    box-shadow: 0 2px 6px oklch(0% 0 0 / 0.3);
+  }
+
+  .ml-scene-spatial-label {
+    color: var(--foreground);
+    font-size: 0.75rem;
+    font-weight: 600;
+  }
+}

package/src/spatial-toggle.tsx

@@ -0,0 +1,78 @@
+"use client";
+
+import * as React from "react";
+import { useReducedMotion } from "./use-reduced-motion";
+
+export interface SpatialToggleProps {
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  label?: React.ReactNode;
+  className?: string;
+  disabled?: boolean;
+  id?: string;
+  name?: string;
+}
+
+function joinClasses(...values: Array<string | false | null | undefined>) {
+  return values.filter(Boolean).join(" ");
+}
+
+export const SpatialToggle = React.forwardRef<HTMLButtonElement, SpatialToggleProps>(
+  (
+    {
+      checked = false,
+      onChange,
+      label,
+      className = "",
+      disabled = false,
+      id,
+      name,
+    },
+    ref
+  ) => {
+    const reducedMotion = useReducedMotion();
+    return (
+      <span className={joinClasses("ml-scene-spatial-toggle", className)}>
+        <button
+          ref={ref}
+          id={id}
+          name={name}
+          type="button"
+          role="switch"
+          aria-checked={checked}
+          aria-label={typeof label === "string" ? label : undefined}
+          disabled={disabled}
+          onClick={() => onChange?.(!checked)}
+          className="ml-scene-spatial-switch"
+          style={{
+            background: checked
+              ? "var(--ml-primary)"
+              : "var(--ml-background-subtle)",
+            transition: reducedMotion ? "none" : "background 240ms ease",
+          }}
+        >
+          <span
+            aria-hidden="true"
+            className="ml-scene-spatial-thumb"
+            style={{
+              transform: checked ? "translate3d(20px, 0, 0)" : "translate3d(0, 0, 0)",
+              transition: reducedMotion
+                ? "none"
+                : "transform 300ms cubic-bezier(0.16, 1, 0.3, 1)",
+            }}
+          />
+        </button>
+        {label ? (
+          <span aria-hidden="true" className="ml-scene-spatial-label">
+            {label}
+          </span>
+        ) : null}
+      </span>
+    );
+  }
+);
+SpatialToggle.displayName = "SpatialToggle";
+
+/** @deprecated Use SpatialToggle. Kept as a source-compatible scene export. */
+export const Toggle3D = SpatialToggle;
+export type Toggle3DProps = SpatialToggleProps;

package/src/stage.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+import * as React from "react";
+import { useReducedMotion } from "./use-reduced-motion";
+
+function finite(value: number, fallback: number): number {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+export interface Stage3DProps extends React.HTMLAttributes<HTMLDivElement> {
+  perspective?: number;
+  interactive?: boolean;
+  maxRotationX?: number;
+  maxRotationY?: number;
+}
+
+export const Stage3D = React.forwardRef<HTMLDivElement, Stage3DProps>(
+  (
+    {
+      perspective = 1200,
+      interactive = true,
+      maxRotationX = 12,
+      maxRotationY = 14,
+      children,
+      style,
+      onPointerMove,
+      onPointerLeave,
+      onPointerCancel,
+      ...props
+    },
+    forwardedRef
+  ) => {
+    const reducedMotion = useReducedMotion();
+    const stageRef = React.useRef<HTMLDivElement>(null);
+    const contentRef = React.useRef<HTMLDivElement>(null);
+    const frameRef = React.useRef<number | null>(null);
+    const setRef = React.useCallback(
+      (node: HTMLDivElement | null) => {
+        stageRef.current = node;
+        if (typeof forwardedRef === "function") forwardedRef(node);
+        else if (forwardedRef) forwardedRef.current = node;
+      },
+      [forwardedRef]
+    );
+
+    const renderRotation = React.useCallback((x: number, y: number, active: boolean) => {
+      const content = contentRef.current;
+      if (!content) return;
+      if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+      if (typeof requestAnimationFrame === "undefined") return;
+      frameRef.current = requestAnimationFrame(() => {
+        content.style.transform = `rotateX(${x.toFixed(2)}deg) rotateY(${y.toFixed(2)}deg)`;
+        content.style.transition = active
+          ? "transform 80ms linear"
+          : "transform 360ms cubic-bezier(0.16, 1, 0.3, 1)";
+        frameRef.current = null;
+      });
+    }, []);
+
+    React.useEffect(
+      () => () => {
+        if (frameRef.current !== null) cancelAnimationFrame(frameRef.current);
+      },
+      []
+    );
+
+    React.useEffect(() => {
+      if (reducedMotion || !interactive) renderRotation(0, 0, false);
+    }, [interactive, reducedMotion, renderRotation]);
+
+    const reset = () => renderRotation(0, 0, false);
+
+    return (
+      <div
+        {...props}
+        ref={setRef}
+        onPointerMove={(event) => {
+          onPointerMove?.(event);
+          const stage = stageRef.current;
+          if (
+            event.defaultPrevented ||
+            !interactive ||
+            reducedMotion ||
+            event.pointerType === "touch" ||
+            !stage
+          ) return;
+          const rect = stage.getBoundingClientRect();
+          if (rect.width <= 0 || rect.height <= 0) return;
+          const px = (event.clientX - rect.left) / rect.width - 0.5;
+          const py = (event.clientY - rect.top) / rect.height - 0.5;
+          renderRotation(
+            -py * finite(maxRotationX, 12),
+            px * finite(maxRotationY, 14),
+            true
+          );
+        }}
+        onPointerLeave={(event) => {
+          onPointerLeave?.(event);
+          reset();
+        }}
+        onPointerCancel={(event) => {
+          onPointerCancel?.(event);
+          reset();
+        }}
+        style={{
+          perspective: `${Math.max(1, finite(perspective, 1200))}px`,
+          transformStyle: "preserve-3d",
+          ...style,
+        }}
+      >
+        <div
+          ref={contentRef}
+          style={{
+            width: "100%",
+            height: "100%",
+            transform: "rotateX(0deg) rotateY(0deg)",
+            transformStyle: "preserve-3d",
+            transition: reducedMotion
+              ? "none"
+              : "transform 360ms cubic-bezier(0.16, 1, 0.3, 1)",
+            willChange: interactive && !reducedMotion ? "transform" : undefined,
+          }}
+        >
+          {children}
+        </div>
+      </div>
+    );
+  }
+);
+Stage3D.displayName = "Stage3D";
+
+export interface FloatingLayerProps extends React.HTMLAttributes<HTMLDivElement> {
+  depth?: number;
+}
+
+export const FloatingLayer = React.forwardRef<HTMLDivElement, FloatingLayerProps>(
+  ({ depth = 30, children, style, ...props }, ref) => {
+    const safeDepth = Math.max(-1000, Math.min(1000, finite(depth, 30)));
+    return (
+      <div
+        {...props}
+        ref={ref}
+        style={{
+          transform: `translateZ(${safeDepth}px)`,
+          transformStyle: "preserve-3d",
+          ...style,
+        }}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+FloatingLayer.displayName = "FloatingLayer";

package/src/use-reduced-motion.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import * as React from "react";
+
+const query = "(prefers-reduced-motion: reduce)";
+
+export function useReducedMotion(): boolean {
+  return React.useSyncExternalStore(
+    (listener) => {
+      if (typeof window === "undefined") return () => {};
+      const media = window.matchMedia(query);
+      media.addEventListener("change", listener);
+      return () => media.removeEventListener("change", listener);
+    },
+    () => typeof window !== "undefined" && window.matchMedia(query).matches,
+    () => false
+  );
+}