chore: integrate firestore for particles (#32)

* plumb for firestore

* chore: cleanup orion api to only include essentials

* setup boilerplate for data and rendering

This includes zod types creation for API response validation, and
exploration of path based resolution of rendering particles.

* chore: structure container particles for rendering children

* wire firestore crud for particles

* integrate visibility to particles

* docs: explain particle view resolver

js/src/hooks/use-create-particle.ts

@@ -0,0 +1,24 @@
+import { useMutation } from "@tanstack/react-query";
+import { createParticle } from "@/lib/firestore-particles";
+import type { ParticleType, ParticlePropertiesMap } from "@/api/types";
+
+interface CreateParticleParams<T extends ParticleType = ParticleType> {
+  collectionPath: string;
+  type: T;
+  properties: ParticlePropertiesMap[T];
+  createdByEmail: string;
+  visibleTo: string[];
+}
+
+export function useCreateParticle() {
+  return useMutation({
+    mutationFn: (params: CreateParticleParams) =>
+      createParticle(
+        params.collectionPath,
+        params.type,
+        params.properties,
+        params.createdByEmail,
+        params.visibleTo,
+      ),
+  });
+}

js/src/hooks/use-particle-children.ts

@@ -0,0 +1,46 @@
+import { useState, useEffect, useMemo } from "react";
+import { subscribeToParticleChildren } from "@/lib/firestore-particles";
+import { firestorePath } from "@/lib/firestore-paths";
+import type { Particle } from "@/api/types";
+
+interface UseParticleChildrenResult {
+  children: Particle[];
+  isLoading: boolean;
+  error: Error | null;
+}
+
+export function useParticleChildren(
+  networkId: string,
+  parentSegments: string[],
+): UseParticleChildrenResult {
+  const [children, setChildren] = useState<Particle[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const collectionPath = useMemo(() => {
+    if (parentSegments.length === 0) return firestorePath(networkId, []);
+    return `${firestorePath(networkId, parentSegments)}/children`;
+  }, [networkId, parentSegments.join("/")]);
+
+  useEffect(() => {
+    setIsLoading(true);
+    setError(null);
+    setChildren([]);
+
+    const unsubscribe = subscribeToParticleChildren(
+      collectionPath,
+      (data) => {
+        setChildren(data);
+        setIsLoading(false);
+      },
+      (err) => {
+        setError(err);
+        setIsLoading(false);
+      },
+    );
+
+    return unsubscribe;
+  }, [collectionPath]);
+
+  return { children, isLoading, error };
+}

js/src/hooks/use-particle.ts

@@ -0,0 +1,46 @@
+import { useState, useEffect, useMemo } from "react";
+import { subscribeToParticle } from "@/lib/firestore-particles";
+import { firestorePath } from "@/lib/firestore-paths";
+import type { Particle } from "@/api/types";
+
+interface UseParticleResult {
+  particle: Particle | null;
+  isLoading: boolean;
+  error: Error | null;
+}
+
+export function useParticle(
+  networkId: string,
+  segments: string[],
+): UseParticleResult {
+  const [particle, setParticle] = useState<Particle | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const path = useMemo(
+    () => firestorePath(networkId, segments),
+    [networkId, segments.join("/")],
+  );
+
+  useEffect(() => {
+    setIsLoading(true);
+    setError(null);
+    setParticle(null);
+
+    const unsubscribe = subscribeToParticle(
+      path,
+      (data) => {
+        setParticle(data);
+        setIsLoading(false);
+      },
+      (err) => {
+        setError(err);
+        setIsLoading(false);
+      },
+    );
+
+    return unsubscribe;
+  }, [path]);
+
+  return { particle, isLoading, error };
+}