react-rubiks-cube 0.1.0

package/src/RubiksCube.jsx

@@ -0,0 +1,109 @@
+import { useRef, useEffect, useState, useCallback } from 'react'
+import { Canvas } from '@react-three/fiber'
+import { Lights } from './primitives.jsx'
+import { AutoCubeScene } from './AutoCubeScene.jsx'
+import { CubeOverlay } from './CubeOverlay.jsx'
+import { resolvePalette } from './palette.js'
+
+// ══════════════════════════════════════════════════════════
+// <RubiksCube /> — the drop-in component.
+//
+// Renders a self-contained auto-solving 3D cube. Optionally click it to open a
+// fullscreen interactive overlay (drag a face to turn, or use the buttons).
+// ══════════════════════════════════════════════════════════
+export function RubiksCube({
+  size = 400,
+  height,
+  palette: paletteProp,
+  accent = '#E05C28',
+  autoplay = true,
+  tumble = true,
+  interactive = true,
+  scrollTilt = false,
+  scale = 0.72,
+  cameraPosition = [7, 6, 7],
+  fov = 24,
+  background = 'transparent',
+  ambient = 0.22,
+  className,
+  style,
+  onExpand,
+  ...rest
+}) {
+  const scrollRef = useRef(0)
+  const wrapRef = useRef(null)
+  const [expanded, setExpanded] = useState(false)
+
+  const palette = resolvePalette(paletteProp)
+  const w = typeof size === 'number' ? `${size}px` : size
+  const h = height != null ? (typeof height === 'number' ? `${height}px` : height) : w
+
+  // Optional scroll-driven tilt: 0..1 progress as the element scrolls up.
+  useEffect(() => {
+    if (!scrollTilt) return
+    const el = wrapRef.current
+    const update = () => {
+      if (!el) return
+      const rect = el.getBoundingClientRect()
+      const vh = window.innerHeight || 1
+      scrollRef.current = Math.max(0, Math.min(1, (vh - rect.top) / (vh + rect.height) - 0.1))
+    }
+    update()
+    window.addEventListener('scroll', update, { passive: true })
+    window.addEventListener('resize', update)
+    return () => {
+      window.removeEventListener('scroll', update)
+      window.removeEventListener('resize', update)
+    }
+  }, [scrollTilt])
+
+  // Lock body scroll while the overlay is open + close on Escape.
+  useEffect(() => {
+    if (!expanded) return
+    const scrollY = window.scrollY
+    document.body.style.position = 'fixed'
+    document.body.style.top = `-${scrollY}px`
+    document.body.style.width = '100%'
+    const onKey = e => e.key === 'Escape' && setExpanded(false)
+    window.addEventListener('keydown', onKey)
+    return () => {
+      document.body.style.position = ''
+      document.body.style.top = ''
+      document.body.style.width = ''
+      window.scrollTo(0, scrollY)
+      window.removeEventListener('keydown', onKey)
+    }
+  }, [expanded])
+
+  const open = useCallback(() => {
+    setExpanded(true)
+    onExpand?.()
+  }, [onExpand])
+  const close = useCallback(() => setExpanded(false), [])
+
+  return (
+    <>
+      <div ref={wrapRef} className={className} style={{ position: 'relative', width: w, height: h, flexShrink: 0, ...style }} {...rest}>
+        <Canvas flat camera={{ position: cameraPosition, fov }} gl={{ antialias: true, alpha: background === 'transparent' }} style={{ background }}>
+          <Lights ambient={ambient} />
+          <AutoCubeScene palette={palette} scrollRef={scrollTilt ? scrollRef : null} scale={scale} tumble={tumble} autoplay={autoplay} />
+        </Canvas>
+
+        {interactive && (
+          <div
+            style={{ position: 'absolute', inset: 0, cursor: 'pointer', zIndex: 1 }}
+            onClick={open}
+            role="button"
+            aria-label="Explore cube"
+            tabIndex={0}
+            onKeyDown={e => e.key === 'Enter' && open()}
+          />
+        )}
+      </div>
+
+      {interactive && expanded && <CubeOverlay onClose={close} palette={palette} accent={accent} />}
+    </>
+  )
+}
+
+export default RubiksCube

package/src/index.d.ts

@@ -0,0 +1,116 @@
+import type { CSSProperties, HTMLAttributes } from 'react'
+
+export interface FaceMaterial {
+  color: string
+  roughness: number
+  metalness: number
+}
+
+export interface Palette {
+  right: FaceMaterial
+  left: FaceMaterial
+  up: FaceMaterial
+  down: FaceMaterial
+  front: FaceMaterial
+  back: FaceMaterial
+  inner: FaceMaterial
+}
+
+/** A partial palette. `base` selects which built-in palette to merge onto. */
+export type PaletteInput = Partial<{
+  base: 'brand' | 'classic'
+  right: Partial<FaceMaterial>
+  left: Partial<FaceMaterial>
+  up: Partial<FaceMaterial>
+  down: Partial<FaceMaterial>
+  front: Partial<FaceMaterial>
+  back: Partial<FaceMaterial>
+  inner: Partial<FaceMaterial>
+}>
+
+export interface RubiksCubeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'style'> {
+  /** Width in px (number) or any CSS size (string). Default 400. */
+  size?: number | string
+  /** Height. Defaults to `size` (square). */
+  height?: number | string
+  /** Palette override, merged onto the `brand` (default) or `classic` base. */
+  palette?: PaletteInput
+  /** Accent colour for the overlay's active mode toggle. Default '#E05C28'. */
+  accent?: string
+  /** Run the scramble → solve loop. Default true. */
+  autoplay?: boolean
+  /** Slowly tumble the whole cube. Default true. */
+  tumble?: boolean
+  /** Click to open the fullscreen interactive overlay. Default true. */
+  interactive?: boolean
+  /** Tilt the cube as the element scrolls through the viewport. Default false. */
+  scrollTilt?: boolean
+  /** Cube scale inside the canvas. Default 0.72. */
+  scale?: number
+  /** Camera position [x, y, z]. Default [7, 6, 7]. */
+  cameraPosition?: [number, number, number]
+  /** Camera field of view. Default 24. */
+  fov?: number
+  /** Canvas background. Default 'transparent'. */
+  background?: string
+  /** Ambient light intensity. Default 0.22. */
+  ambient?: number
+  style?: CSSProperties
+  /** Called when the interactive overlay opens. */
+  onExpand?: () => void
+}
+
+export declare function RubiksCube(props: RubiksCubeProps): JSX.Element
+export default RubiksCube
+
+export interface Move {
+  axis: 'x' | 'y' | 'z'
+  /** -1, 0, 1 for a layer; null for a whole-cube rotation. */
+  layer: -1 | 0 | 1 | null
+  dir: 1 | -1
+}
+
+export interface AutoCubeSceneProps {
+  palette: Palette
+  scrollRef?: { current: number } | null
+  scale?: number
+  tumble?: boolean
+  autoplay?: boolean
+}
+export declare function AutoCubeScene(props: AutoCubeSceneProps): JSX.Element
+
+export interface InteractiveCubeSceneProps {
+  palette: Palette
+  queueRef: { current: Move[] }
+  modeRef?: { current: 'orbit' | 'move' }
+  autoReturnAfter?: number
+  idleSpin?: number
+}
+export declare function InteractiveCubeScene(props: InteractiveCubeSceneProps): JSX.Element
+
+export interface CubeOverlayProps {
+  onClose: () => void
+  palette: Palette
+  accent?: string
+  cameraPosition?: [number, number, number]
+  fov?: number
+}
+export declare function CubeOverlay(props: CubeOverlayProps): JSX.Element
+
+export declare const MOVE_GROUPS: Array<{
+  id: string
+  label: string
+  accent: string
+  pairs: Array<Array<{ n: string } & Move>>
+}>
+
+export declare function Cubelet(props: { px: number; py: number; pz: number; palette: Palette }): JSX.Element
+export declare function Lights(props: { ambient?: number }): JSX.Element
+export declare function useCubePositions(): [number, number, number][]
+export declare function smoother(t: number): number
+export declare const CUBELET_GEO: import('three').BufferGeometry
+
+export declare const BRAND_PALETTE: Palette
+export declare const CLASSIC_PALETTE: Palette
+export declare const FACE_ORDER: Array<keyof Palette>
+export declare function resolvePalette(palette?: PaletteInput): Palette

package/src/index.js

@@ -0,0 +1,11 @@
+// Public API
+export { RubiksCube, default } from './RubiksCube.jsx'
+
+// Advanced building blocks — bring your own <Canvas>.
+export { AutoCubeScene } from './AutoCubeScene.jsx'
+export { InteractiveCubeScene, MOVE_GROUPS } from './InteractiveCubeScene.jsx'
+export { CubeOverlay } from './CubeOverlay.jsx'
+export { Cubelet, Lights, CUBELET_GEO, smoother, useCubePositions } from './primitives.jsx'
+
+// Theming
+export { BRAND_PALETTE, CLASSIC_PALETTE, FACE_ORDER, resolvePalette } from './palette.js'

package/src/palette.js

@@ -0,0 +1,48 @@
+// ── Palettes ──────────────────────────────────────────────
+// A palette describes the six sticker faces plus the inner body.
+// Faces map to axes: right (+x), left (-x), up (+y), down (-y),
+// front (+z), back (-z). Each entry is { color, roughness, metalness }.
+// metalness stays 0 by default — there is no environment map, so any
+// metalness only deadens the diffuse colour. The plastic sheen comes from
+// crisp specular highlights of the lights at low roughness.
+
+// Warm editorial brand palette (the original cubex look): a "warm side /
+// cool side" read rather than a random rainbow. Opposite faces hold the
+// strongest contrast pairs.
+export const BRAND_PALETTE = {
+  right: { color: '#E05C28', roughness: 0.34, metalness: 0 }, // accent orange
+  left:  { color: '#00C9A7', roughness: 0.34, metalness: 0 }, // mint teal
+  up:    { color: '#EDE3D1', roughness: 0.44, metalness: 0 }, // ink cream
+  down:  { color: '#C8963E', roughness: 0.36, metalness: 0 }, // gold
+  front: { color: '#B23E22', roughness: 0.36, metalness: 0 }, // deep terracotta
+  back:  { color: '#0B7A6E', roughness: 0.38, metalness: 0 }, // deep teal
+  inner: { color: '#1C1A17', roughness: 0.82, metalness: 0 }, // dark body
+}
+
+// Classic Rubik's colours for a traditional look.
+export const CLASSIC_PALETTE = {
+  right: { color: '#B71234', roughness: 0.3, metalness: 0 },  // red
+  left:  { color: '#FF5800', roughness: 0.3, metalness: 0 },  // orange
+  up:    { color: '#FFFFFF', roughness: 0.4, metalness: 0 },  // white
+  down:  { color: '#FFD500', roughness: 0.32, metalness: 0 }, // yellow
+  front: { color: '#009B48', roughness: 0.32, metalness: 0 }, // green
+  back:  { color: '#0046AD', roughness: 0.32, metalness: 0 }, // blue
+  inner: { color: '#111111', roughness: 0.85, metalness: 0 }, // black body
+}
+
+// Face order used everywhere geometry is built. This is the order
+// meshStandardMaterial slots map to on a BoxGeometry:
+//   0 = +x (right), 1 = -x (left), 2 = +y (up),
+//   3 = -y (down),  4 = +z (front), 5 = -z (back)
+export const FACE_ORDER = ['right', 'left', 'up', 'down', 'front', 'back']
+
+// Merge a user-supplied partial palette over a base, per-face.
+export function resolvePalette(palette) {
+  if (!palette) return BRAND_PALETTE
+  const base = palette.base === 'classic' ? CLASSIC_PALETTE : BRAND_PALETTE
+  const out = {}
+  for (const key of [...FACE_ORDER, 'inner']) {
+    out[key] = { ...base[key], ...(palette[key] || {}) }
+  }
+  return out
+}

package/src/primitives.jsx

@@ -0,0 +1,66 @@
+import { useMemo } from 'react'
+import { RoundedBoxGeometry } from 'three/examples/jsm/geometries/RoundedBoxGeometry.js'
+import { FACE_ORDER } from './palette.js'
+
+// ── Shared geometry ───────────────────────────────────────
+// One rounded-box geometry reused by all 27 cubelets. Module-level so it is
+// created once per bundle, never per mount.
+export const CUBELET_GEO = new RoundedBoxGeometry(0.95, 0.95, 0.95, 4, 0.045)
+
+// Smootherstep (Perlin) — zero velocity AND acceleration at both ends, so
+// every turn starts and stops with no perceptible jerk.
+export const smoother = t => {
+  t = Math.max(0, Math.min(1, t))
+  return t * t * t * (t * (t * 6 - 15) + 10)
+}
+
+// One cubelet: outer faces get sticker materials, inner faces get the body.
+export function Cubelet({ px, py, pz, palette }) {
+  // Which of the 6 BoxGeometry face-slots are on the cube's outer surface.
+  const outer = useMemo(
+    () => [px === 1, px === -1, py === 1, py === -1, pz === 1, pz === -1],
+    [px, py, pz],
+  )
+  return (
+    <mesh position={[px, py, pz]} geometry={CUBELET_GEO}>
+      {outer.map((isOuter, i) => {
+        const m = isOuter ? palette[FACE_ORDER[i]] : palette.inner
+        return (
+          <meshStandardMaterial
+            key={i}
+            attach={`material-${i}`}
+            color={m.color}
+            roughness={m.roughness}
+            metalness={m.metalness}
+          />
+        )
+      })}
+    </mesh>
+  )
+}
+
+// Studio lighting tuned for flat (no tone-mapping) rendering: a warm key, a
+// soft warm fill, a cool rim to carve edges out of a dark background, an
+// ambient floor, and a warm front specular for the plastic sheen.
+export function Lights({ ambient = 0.22 }) {
+  return (
+    <>
+      <directionalLight position={[5, 8, 4]} intensity={2.4} color="#fff6ee" />
+      <directionalLight position={[-5, -3, -4]} intensity={0.6} color="#ffe0cf" />
+      <directionalLight position={[-4, 6, -6]} intensity={1.5} color="#cfe4ff" />
+      <ambientLight intensity={ambient} />
+      <pointLight position={[-1, 1, 5]} intensity={0.85} color="#fff5ee" distance={18} />
+    </>
+  )
+}
+
+// The 27 integer grid positions of a 3×3×3 cube.
+export function useCubePositions() {
+  return useMemo(() => {
+    const list = []
+    for (let x = -1; x <= 1; x++)
+      for (let y = -1; y <= 1; y++)
+        for (let z = -1; z <= 1; z++) list.push([x, y, z])
+    return list
+  }, [])
+}