From c1fa37da987bb42ef46f8153ae6b17d833d889e5 Mon Sep 17 00:00:00 2001
From: Jackson Morgan <jaxoncreed@gmail.com>
Date: Wed, 2 Apr 2025 11:00:10 -0400
Subject: [PATCH] Documentation for @ldo/react

---
 packages/react/src/createLdoReactMethods.tsx  | 46 ++++++++++++++++
 packages/react/src/methods/useLdo.ts          | 52 ++++++++++++++++++-
 packages/react/src/methods/useMatchObject.ts  |  9 ++++
 packages/react/src/methods/useMatchSubject.ts |  9 ++++
 packages/react/src/methods/useResource.ts     |  8 +++
 packages/react/src/methods/useSubject.ts      |  9 ++++
 .../src/methods/useSubscribeToResource.ts     |  8 +++
 packages/react/src/util/TrackingSetProxy.ts   |  6 +++
 .../react/src/util/TrackingSubjectProxy.ts    |  6 +++
 packages/react/src/util/useTrackingProxy.ts   |  5 ++
 10 files changed, 156 insertions(+), 2 deletions(-)

diff --git a/packages/react/src/createLdoReactMethods.tsx b/packages/react/src/createLdoReactMethods.tsx
index 57e3f2d..eee6e21 100644
--- a/packages/react/src/createLdoReactMethods.tsx
+++ b/packages/react/src/createLdoReactMethods.tsx
@@ -10,6 +10,52 @@ import { createUseResource } from "./methods/useResource";
 import { createUseSubject } from "./methods/useSubject";
 import { createUseSubscribeToResource } from "./methods/useSubscribeToResource";
 
+/**
+ * A function that creates all common react functions given specific plugin.
+ *
+ * @example
+ * `methods.ts`
+ * ```tyepscript
+ * import { solidConnectedPlugin } from "@ldo/connected-solid";
+ * import { nextGraphConnectedPlugin } from "@ldo/connected-nextgraph";
+ * import { createLdoReactMethods } from "@ldo/react";
+ *
+ * // Export the results to be used in the reset of the application
+ * export const {
+ *  dataset,
+ *  useLdo,
+ *  useMatchObject,
+ *  useMatchSubject,
+ *  useResource,
+ *  useSubject,
+ *  useSubscribeToResource,
+ * } = createLdoReactMethods([
+ *   solidConnectedPlugin,
+ *   nextGraphConnectedPlugin
+ * ]);
+ * ```
+ *
+ * `App.tsx`
+ * ```typescript
+ * import react, { FunctionComponent } from "react";
+ * import { PostShShapeType } from "./.ldo/posts.shapeType.ts";
+ * import { useResource, useSubject } from "./methods.ts";
+ *
+ * const UseSubjectTest: FunctionComponent = () => {
+ *   const resource = useResource(SAMPLE_DATA_URI);
+ *   const post = useSubject(PostShShapeType, `${SAMPLE_DATA_URI}#Post1`);
+ *   if (resource.isLoading() || !post) return <p>loading</p>;
+ *
+ *   return (
+ *     <ul>
+ *       {post.publisher.map((publisher) => {
+ *         return <li key={publisher["@id"]}>{publisher["@id"]}</li>;
+ *       })}
+ *     </ul>
+ *   );
+ * };
+ * ```
+ */
 export function createLdoReactMethods<
   Plugins extends ConnectedPlugin<any, any, any, any>[],
 >(plugins: Plugins) {
diff --git a/packages/react/src/methods/useLdo.ts b/packages/react/src/methods/useLdo.ts
index 78a6c79..de31a3f 100644
--- a/packages/react/src/methods/useLdo.ts
+++ b/packages/react/src/methods/useLdo.ts
@@ -7,34 +7,79 @@ import {
 import { getDataset, type LdoBase, type ShapeType } from "@ldo/ldo";
 import type { SubjectNode } from "@ldo/rdf-utils";
 
+/**
+ * The methods returned by useLdo
+ */
 export interface UseLdoMethods<Plugins extends ConnectedPlugin[]> {
+  /**
+   * A ConnectedLdoDataset
+   */
   dataset: ConnectedLdoDataset<Plugins>;
+  /**
+   * Retireves a representation of a Resource at the given URI. This resource
+   * represents the current state of the resource: whether it is currently
+   * fetched or in the process of fetching as well as some information about it.
+   *
+   * @param uri - the URI of the resource
+   * @param pluginName - optionally, force this function to choose a specific
+   * plugin to use rather than perform content negotiation.
+   *
+   * @returns a Resource
+   */
   getResource: ConnectedLdoDataset<Plugins>["getResource"];
+  /**
+   * Sets conetext for a specific plugin
+   *
+   * @param pluginName - the name of the plugin
+   * @param context - the context for this specific plugin
+   */
   setContext: ConnectedLdoDataset<Plugins>["setContext"];
+  /**
+   * Gets a linked data object based on the subject
+   */
   getSubject<Type extends LdoBase>(
     shapeType: ShapeType<Type>,
     subject: string | SubjectNode,
   ): Type;
+  /**
+   * Shorthand for connectedLdoDataset
+   *   .usingType(shapeType)
+   *   .write(...resources.map((r) => r.uri))
+   *   .fromSubject(subject);
+   * @param shapeType - The shapetype to represent the data
+   * @param subject - A subject URI
+   * @param resources - The resources changes to should written to
+   */
   createData<Type extends LdoBase>(
     shapeType: ShapeType<Type>,
     subject: string | SubjectNode,
     resource: Plugins[number]["types"]["resource"],
     ...additionalResources: Plugins[number]["types"]["resource"][]
   ): Type;
+  /**
+   * Returns a writable LinkedDataObject given a linked data object
+   */
   changeData<Type extends LdoBase>(
     input: Type,
     resource: Plugins[number]["types"]["resource"],
     ...additionalResources: Plugins[number]["types"]["resource"][]
   ): Type;
+  /**
+   * Commits the data of a writable Linke Data Object back to the remote.
+   */
   commitData(
     input: LdoBase,
   ): ReturnType<ConnectedLdoTransactionDataset<Plugins>["commitToRemote"]>;
 }
 
+/**
+ * @internal
+ * Creates the useLdoHook
+ */
 export function createUseLdo<Plugins extends ConnectedPlugin[]>(
   dataset: ConnectedLdoDataset<Plugins>,
 ) {
-  return (): UseLdoMethods<Plugins> => ({
+  const toReturn = {
     dataset,
     /**
      * Gets a resource
@@ -94,5 +139,8 @@ export function createUseLdo<Plugins extends ConnectedPlugin[]>(
       ) as ConnectedLdoTransactionDataset<Plugins>;
       return inputDataset.commitToRemote();
     },
-  });
+  };
+  return function useLdo(): UseLdoMethods<Plugins> {
+    return toReturn;
+  };
 }
diff --git a/packages/react/src/methods/useMatchObject.ts b/packages/react/src/methods/useMatchObject.ts
index a77ff8a..4934df6 100644
--- a/packages/react/src/methods/useMatchObject.ts
+++ b/packages/react/src/methods/useMatchObject.ts
@@ -5,9 +5,18 @@ import { useCallback } from "react";
 import { useTrackingProxy } from "../util/useTrackingProxy";
 import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
 
+/**
+ * @internal
+ *
+ * Creates a useMatchObject function
+ */
 export function createUseMatchObject<Plugins extends ConnectedPlugin[]>(
   dataset: ConnectedLdoDataset<Plugins>,
 ) {
+  /**
+   * Returns an array of matching items and triggers a rerender when that data
+   * is updated.
+   */
   return function useMatchObject<Type extends LdoBase>(
     shapeType: ShapeType<Type>,
     subject?: QuadMatch[0] | string,
diff --git a/packages/react/src/methods/useMatchSubject.ts b/packages/react/src/methods/useMatchSubject.ts
index 0adac52..9b0b20b 100644
--- a/packages/react/src/methods/useMatchSubject.ts
+++ b/packages/react/src/methods/useMatchSubject.ts
@@ -5,9 +5,18 @@ import { useCallback } from "react";
 import { useTrackingProxy } from "../util/useTrackingProxy";
 import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
 
+/**
+ * @internal
+ *
+ * Creates a useMatchSubject function.
+ */
 export function createUseMatchSubject<Plugins extends ConnectedPlugin[]>(
   dataset: ConnectedLdoDataset<Plugins>,
 ) {
+  /**
+   * Returns an array of matching linked data objects. Triggers a rerender if
+   * the data is updated.
+   */
   return function useMatchSubject<Type extends LdoBase>(
     shapeType: ShapeType<Type>,
     predicate?: QuadMatch[1] | string,
diff --git a/packages/react/src/methods/useResource.ts b/packages/react/src/methods/useResource.ts
index f6d0cf3..d17420d 100644
--- a/packages/react/src/methods/useResource.ts
+++ b/packages/react/src/methods/useResource.ts
@@ -32,9 +32,17 @@ export type useResourceType<Plugins extends ConnectedPlugin[]> = {
   ): GetResourceReturnType<Plugin, UriType> | undefined;
 };
 
+/**
+ * @internal
+ *
+ * Creates a useResource function.
+ */
 export function createUseResource<Plugins extends ConnectedPlugin[]>(
   dataset: ConnectedLdoDataset<Plugins>,
 ): useResourceType<Plugins> {
+  /**
+   * Returns a resource and triggers a rerender if that resource is updated.
+   */
   return function useResource<
     Name extends Plugins[number]["name"],
     Plugin extends Extract<Plugins[number], { name: Name }>,
diff --git a/packages/react/src/methods/useSubject.ts b/packages/react/src/methods/useSubject.ts
index 2969983..8f1768f 100644
--- a/packages/react/src/methods/useSubject.ts
+++ b/packages/react/src/methods/useSubject.ts
@@ -22,9 +22,18 @@ export type useSubjectType = {
   ): Type | undefined;
 };
 
+/**
+ * @internal
+ *
+ * Creates a useSubject function.
+ */
 export function createUseSubject<Plugins extends ConnectedPlugin[]>(
   dataset: ConnectedLdoDataset<Plugins>,
 ): useSubjectType {
+  /**
+   * Returns a Linked Data Object based on the provided subject. Triggers a
+   * rerender if the data is udpated.
+   */
   return function useSubject<Type extends LdoBase>(
     shapeType: ShapeType<Type>,
     subject?: string | SubjectNode,
diff --git a/packages/react/src/methods/useSubscribeToResource.ts b/packages/react/src/methods/useSubscribeToResource.ts
index c9b589e..f2af1ca 100644
--- a/packages/react/src/methods/useSubscribeToResource.ts
+++ b/packages/react/src/methods/useSubscribeToResource.ts
@@ -1,9 +1,17 @@
 import { useEffect, useRef } from "react";
 import type { ConnectedLdoDataset, ConnectedPlugin } from "@ldo/connected";
 
+/**
+ * @internal
+ *
+ * Creates a useSubscribeToResource function.
+ */
 export function createUseSubscribeToResource<Plugins extends ConnectedPlugin[]>(
   dataset: ConnectedLdoDataset<Plugins>,
 ) {
+  /**
+   * Starts a subscription to a resource.
+   */
   return function useSubscribeToResource(...uris: string[]): void {
     const currentlySubscribed = useRef<Record<string, string>>({});
     useEffect(() => {
diff --git a/packages/react/src/util/TrackingSetProxy.ts b/packages/react/src/util/TrackingSetProxy.ts
index 9c34347..cf3e74f 100644
--- a/packages/react/src/util/TrackingSetProxy.ts
+++ b/packages/react/src/util/TrackingSetProxy.ts
@@ -2,6 +2,12 @@ import { createNewSetProxy, type SetProxy } from "@ldo/jsonld-dataset-proxy";
 import type { TrackingProxyContext } from "./TrackingProxyContext";
 import type { QuadMatch } from "@ldo/rdf-utils";
 
+/**
+ * @internal
+ *
+ * Creates a tracking proxy, a proxy that tracks the fields that have been
+ * accessed.
+ */
 export function createTrackingSetProxy(
   proxyContext: TrackingProxyContext,
   quadMatch: QuadMatch,
diff --git a/packages/react/src/util/TrackingSubjectProxy.ts b/packages/react/src/util/TrackingSubjectProxy.ts
index 54fa5fe..74154bf 100644
--- a/packages/react/src/util/TrackingSubjectProxy.ts
+++ b/packages/react/src/util/TrackingSubjectProxy.ts
@@ -7,6 +7,12 @@ import type { BlankNode, NamedNode } from "@rdfjs/types";
 import type { TrackingProxyContext } from "./TrackingProxyContext";
 import { namedNode } from "@rdfjs/data-model";
 
+/**
+ * @internal
+ *
+ * Creates a tracking proxy for a single value, a proxy that tracks the fields
+ * that have been accessed.
+ */
 export function createTrackingSubjectProxy(
   proxyContext: TrackingProxyContext,
   node: NamedNode | BlankNode,
diff --git a/packages/react/src/util/useTrackingProxy.ts b/packages/react/src/util/useTrackingProxy.ts
index 64793e0..33d39e1 100644
--- a/packages/react/src/util/useTrackingProxy.ts
+++ b/packages/react/src/util/useTrackingProxy.ts
@@ -8,6 +8,11 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { TrackingProxyContext } from "./TrackingProxyContext";
 import { defaultGraph } from "@rdfjs/data-model";
 
+/**
+ * @internal
+ *
+ * A hook for tracking proxies
+ */
 export function useTrackingProxy<Type extends LdoBase, ReturnType>(
   shapeType: ShapeType<Type>,
   createLdo: (builder: LdoBuilder<Type>) => ReturnType,