feat: add reference page (#47)

### Explanation

_No response_

### Issue

_No response_

### Attestations

- [x] I have read and agree to the [Code of Conduct](https://docs.nhcarrigan.com/community/coc/)
- [x] I have read and agree to the [Community Guidelines](https://docs.nhcarrigan.com/community/guide/).
- [x] My contribution complies with the [Contributor Covenant](https://docs.nhcarrigan.com/dev/covenant/).

### Dependencies

- [x] I have pinned the dependencies to a specific patch version.

### Style

- [x] I have run the linter and resolved any errors.
- [x] My pull request uses an appropriate title, matching the conventional commit standards.
- [x] My scope of feat/fix/chore/etc. correctly matches the nature of changes in my pull request.

### Tests

- [x] My contribution adds new code, and I have added tests to cover it.
- [x] My contribution modifies existing code, and I have updated the tests to reflect these changes.
- [x] All new and existing tests pass locally with my changes.
- [x] Code coverage remains at or above the configured threshold.

### Documentation

_No response_

### Versioning

_No response_

Reviewed-on: https://codeberg.org/nhcarrigan/portfolio/pulls/47
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>

package.json

@@ -16,10 +16,14 @@
     "@fortawesome/free-brands-svg-icons": "6.6.0",
     "@fortawesome/free-solid-svg-icons": "6.6.0",
     "@fortawesome/react-fontawesome": "0.2.2",
+    "@pixiv/three-vrm": "3.1.6",
+    "@react-three/drei": "9.117.2",
+    "@react-three/fiber": "9.0.0-beta.1",
     "next": "15.0.2",
     "next-plausible": "3.12.2",
     "react": "18.3.1",
-    "react-dom": "18.3.1"
+    "react-dom": "18.3.1",
+    "three": "0.170.0"
   },
   "devDependencies": {
     "@aws-sdk/client-s3": "3.693.0",
@@ -28,6 +32,7 @@
     "@types/node": "22.8.4",
     "@types/react": "18.3.12",
     "@types/react-dom": "18.3.1",
+    "@types/three": "0.170.0",
     "@vitest/coverage-istanbul": "2.1.4",
     "eslint": "9.13.0",
     "jsdom": "25.0.1",
@@ -36,5 +41,10 @@
     "tsx": "4.19.2",
     "typescript": "5.6.3",
     "vitest": "2.1.4"
+  },
+  "resolutions": {
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "next": "15.0.2"
   }
 }

src/app/ref/page.tsx

@@ -0,0 +1,137 @@
+/**
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+/* eslint-disable react/no-unknown-property, react/no-multi-comp */
+"use client";
+import { VRMLoaderPlugin, type VRM } from "@pixiv/three-vrm";
+import { OrbitControls } from "@react-three/drei";
+// @ts-expect-error -- It seems like the beta version has type-def issues.
+import { Canvas } from "@react-three/fiber";
+import { useState, useRef, type ChangeEvent, type JSX, useEffect } from "react";
+import { PerspectiveCamera } from "three";
+// eslint-disable-next-line import/extensions -- We need this apparently.
+import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { Rule } from "../../components/rule";
+import { MainVRoid, VRoid } from "../../config/Vroid";
+
+const concatenated = [
+  MainVRoid,
+  ...VRoid.toSorted((a, b) => {
+    return a.name.localeCompare(b.name);
+  }),
+];
+
+/**
+ * Scene setup component for lighting and controls.
+ * @returns The Three.JS scene.
+ */
+const SceneSetup = (): JSX.Element => {
+  return (
+    <>
+      {/* Main directional light from front-top */}
+      { /* @ts-expect-error -- why */}
+      <directionalLight
+        castShadow={true}
+        intensity={1}
+        position={[ 0, 5, 5 ]}
+      />
+      {/* Fill light from back */}
+      { /* @ts-expect-error -- why */}
+      <directionalLight
+        intensity={0.5}
+        position={[ 0, 3, -5 ]}
+      />
+      {/* Ambient light for overall scene brightness */}
+      { /* @ts-expect-error -- why */}
+      <ambientLight intensity={0.5} />
+      {/* Orbit controls for camera manipulation */}
+      <OrbitControls
+        enablePan={true}
+        enableRotate={true}
+        enableZoom={true}
+        maxDistance={20}
+        minDistance={1}
+        target={[ 0, 0.8, 0 ]}
+      />
+    </>
+  );
+};
+
+/**
+ * Reference component for displaying and interacting with VRM models.
+ * @returns The reference page.
+ */
+const Reference = (): JSX.Element => {
+  const [ selected, setSelected ] = useState<string>(MainVRoid.file);
+  const aspect = 1920 / 1080;
+  const { current: camera }
+    = useRef(new PerspectiveCamera(30, aspect, 0.1, 1000));
+
+  const handleChange = (event: ChangeEvent): void => {
+    const { target } = event;
+    if (target instanceof HTMLSelectElement) {
+      setSelected(target.value);
+    }
+  };
+
+  const loader = new GLTFLoader();
+  loader.register((parser) => {
+    return new VRMLoaderPlugin(parser);
+  });
+
+  const [ model, setModel ] = useState<JSX.Element | null>(null);
+
+  useEffect(() => {
+    loader.load(`https://cdn.nhcarrigan.com/vrm/${selected}`, (gltf) => {
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+      const { vrm } = gltf.userData as { vrm: VRM };
+      if (vrm.lookAt) {
+        vrm.lookAt.target = camera;
+      }
+      // Center the model
+      vrm.scene.position.set(0, 0, 0);
+      // Add rotation if needed
+      vrm.scene.rotation.y = Math.PI;
+
+      /* @ts-expect-error -- why */
+      setModel(<primitive object={vrm.scene} />);
+    });
+  }, [ selected ]);
+
+  useEffect(() => {
+    // Position camera to better frame the model
+    camera.position.set(0, 0, 3);
+  }, [ camera ]);
+
+  return (
+    <main className="w-4/5 text-center max-w-4xl m-auto mt-16 mb-16 rounded-lg">
+      <h1 className="text-5xl">{`Reference`}</h1>
+      <section>
+        <p className="mb-2">{`Want to draw art of Naomi? Here's a fully interactive reference page with all of her model's outfits!`}</p>
+        <select
+          className="px-2 bg-[--background] border-2
+            border-solid border-[--foreground]"
+          // eslint-disable-next-line react/jsx-no-bind
+          onChange={handleChange}
+        >
+          {concatenated.map((vroid) => {
+            return <option key={vroid.name} value={vroid.file}>
+              {vroid.name}
+            </option>;
+          })}
+        </select>
+        <Rule />
+      </section>
+      <div className="h-[600px]">
+        <Canvas camera={camera}>
+          <SceneSetup />
+          {model}
+        </Canvas>
+      </div>
+    </main>
+  );
+};
+
+export default Reference;

src/config/NavItems.ts

@@ -26,6 +26,7 @@ export const NavItems = [
   { href: "/tech", text: "Technologies" },
   { href: "/contribute", text: "Contribute to our Projects" },
   { href: "/koikatsu", text: "Koikatsu Scenes" },
+  { href: "/ref", text: "Reference Sheet" },
 ].sort((a, b) => {
   return a.text.localeCompare(b.text);
 });

src/config/Vroid.ts

@@ -0,0 +1,38 @@
+/**
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+
+/**
+ * List of vroid models to render.
+ */
+const VRoid = [
+  {
+    file: "business.vrm",
+    name: "Business Suit",
+  },
+  {
+    file: "casual.vrm",
+    name: "Casual Outfit",
+  },
+  {
+    file: "formal.vrm",
+    name: "Formal Outfit",
+  },
+  {
+    file: "sleep.vrm",
+    name: "Sleepwear",
+  },
+  {
+    file: "swim.vrm",
+    name: "Swimsuit",
+  },
+];
+
+const MainVRoid = {
+  file: "main.vrm",
+  name: "Main Outfit",
+};
+
+export { VRoid, MainVRoid };

test/config/VRoid.spec.ts

@@ -0,0 +1,36 @@
+/**
+ * @copyright nhcarrigan
+ * @license Naomi's Public License
+ * @author Naomi Carrigan
+ */
+import { describe, it, expect } from "vitest";
+import { MainVRoid, VRoid } from "../../src/config/Vroid";
+
+const concatenated = [
+  MainVRoid,
+  ...VRoid.sort((a, b) => {
+    return a.name.localeCompare(b.name);
+  }),
+];
+
+describe("vroid objects", () => {
+  it("should have unique names", () => {
+    expect.assertions(1);
+    const set = new Set(
+      concatenated.map((a) => {
+        return a.name;
+      }),
+    );
+    expect(set, "are not unique").toHaveLength(concatenated.length);
+  });
+
+  it("should have unique file properties", () => {
+    expect.assertions(1);
+    const set = new Set(
+      concatenated.map((a) => {
+        return a.file;
+      }),
+    );
+    expect(set, "are not unique").toHaveLength(concatenated.length);
+  });
+});