feat: explorer package (#3001)

latticexyz · Aug 21, 2024 · f1d8d71 · f1d8d71
1 parent 8878f26
commit f1d8d71
Show file tree

Hide file tree

Showing 96 changed files with 20,945 additions and 4,474 deletions.
diff --git a/.changeset/swift-rabbits-appear.md b/.changeset/swift-rabbits-appear.md
@@ -0,0 +1,7 @@
+---
+"@latticexyz/explorer": minor
+---
+
+Initial release of the @latticexyz/explorer package. Explorer is a standalone tool designed to explore and manage worlds. This initial release supports local worlds, with plans to extend support to any world in the future.
+
+Read more on how to get started or contribute in the [Explorer README](https://github.com/latticexyz/mud/blob/main/packages/explorer/README.md).
diff --git a/examples/local-explorer/.eslintrc b/examples/local-explorer/.eslintrc
@@ -0,0 +1,14 @@
+{
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/eslint-recommended",
+    "plugin:@typescript-eslint/recommended",
+  ],
+  "env": {
+    "browser": true,
+    "node": true,
+  },
+}
diff --git a/examples/local-explorer/.gitattributes b/examples/local-explorer/.gitattributes
@@ -0,0 +1,3 @@
+# suppress diffs for generated files
+**/pnpm-lock.yaml linguist-generated=true
+**/codegen/**/*.sol linguist-generated=true
diff --git a/examples/local-explorer/.gitignore b/examples/local-explorer/.gitignore
@@ -0,0 +1,2 @@
+indexer.db
+node_modules
diff --git a/examples/local-explorer/mprocs.yaml b/examples/local-explorer/mprocs.yaml
@@ -0,0 +1,18 @@
+procs:
+  client:
+    cwd: packages/client
+    shell: pnpm run dev
+  contracts:
+    cwd: packages/contracts
+    shell: pnpm mud dev-contracts --rpc http://127.0.0.1:8545
+  anvil:
+    cwd: packages/contracts
+    shell: anvil --base-fee 0 --block-time 2
+  indexer:
+    shell: rimraf $SQLITE_FILENAME && pnpm sqlite-indexer
+    env:
+      RPC_HTTP_URL: "http://127.0.0.1:8545"
+      FOLLOW_BLOCK_TAG: "latest"
+      SQLITE_FILENAME: "indexer.db"
+  explorer:
+    shell: pnpm explorer --worldsFile packages/contracts/worlds.json
diff --git a/examples/local-explorer/package.json b/examples/local-explorer/package.json
@@ -0,0 +1,31 @@
+{
+  "name": "local-explorer",
+  "private": true,
+  "scripts": {
+    "build": "pnpm recursive run build",
+    "dev": "mprocs",
+    "dev:client": "pnpm --filter 'client' run dev",
+    "dev:contracts": "pnpm --filter 'contracts' dev",
+    "foundry:up": "curl -L https://foundry.paradigm.xyz | bash && bash $HOME/.foundry/bin/foundryup",
+    "mud:up": "pnpm mud set-version --tag main && pnpm install",
+    "prepare": "(forge --version || pnpm foundry:up)",
+    "test": "pnpm recursive run test"
+  },
+  "devDependencies": {
+    "@latticexyz/cli": "link:../../packages/cli",
+    "@latticexyz/common": "link:../../packages/common",
+    "@latticexyz/explorer": "link:../../packages/explorer",
+    "@latticexyz/store-indexer": "link:../../packages/store-indexer",
+    "@types/debug": "4.1.7",
+    "@typescript-eslint/eslint-plugin": "7.1.1",
+    "@typescript-eslint/parser": "7.1.1",
+    "eslint": "8.57.0",
+    "mprocs": "^0.6.4",
+    "rimraf": "^3.0.2",
+    "typescript": "5.4.2"
+  },
+  "engines": {
+    "node": "^18",
+    "pnpm": "^8 || ^9"
+  }
+}
diff --git a/examples/local-explorer/packages/client/.eslintrc b/examples/local-explorer/packages/client/.eslintrc
@@ -0,0 +1,7 @@
+{
+  "extends": ["../../.eslintrc", "plugin:react/recommended", "plugin:react-hooks/recommended"],
+  "plugins": ["react", "react-hooks"],
+  "rules": {
+    "react/react-in-jsx-scope": "off"
+  }
+}
diff --git a/examples/local-explorer/packages/client/.gitignore b/examples/local-explorer/packages/client/.gitignore
@@ -0,0 +1,3 @@
+node_modules
+dist
+.DS_Store
diff --git a/examples/local-explorer/packages/client/index.html b/examples/local-explorer/packages/client/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>a minimal MUD client</title>
+  </head>
+  <body>
+    <div id="react-root"></div>
+    <script type="module" src="/src/index.tsx"></script>
+  </body>
+</html>
diff --git a/examples/local-explorer/packages/client/package.json b/examples/local-explorer/packages/client/package.json
@@ -0,0 +1,36 @@
+{
+  "name": "client",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "dev": "wait-port localhost:8545 && vite",
+    "preview": "vite preview",
+    "test": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@latticexyz/common": "link:../../../../packages/common",
+    "@latticexyz/dev-tools": "link:../../../../packages/dev-tools",
+    "@latticexyz/react": "link:../../../../packages/react",
+    "@latticexyz/schema-type": "link:../../../../packages/schema-type",
+    "@latticexyz/store-sync": "link:../../../../packages/store-sync",
+    "@latticexyz/utils": "link:../../../../packages/utils",
+    "@latticexyz/world": "link:../../../../packages/world",
+    "contracts": "workspace:*",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rxjs": "7.5.5",
+    "viem": "2.19.8"
+  },
+  "devDependencies": {
+    "@types/react": "18.2.22",
+    "@types/react-dom": "18.2.7",
+    "@vitejs/plugin-react": "^3.1.0",
+    "eslint-plugin-react": "7.31.11",
+    "eslint-plugin-react-hooks": "4.6.0",
+    "vite": "^4.2.1",
+    "wait-port": "^1.0.4"
+  }
+}
diff --git a/examples/local-explorer/packages/client/src/App.tsx b/examples/local-explorer/packages/client/src/App.tsx
@@ -0,0 +1,105 @@
+import { useMUD } from "./MUDContext";
+
+const styleUnset = { all: "unset" } as const;
+
+export const App = () => {
+  const {
+    network: { tables, useStore },
+    systemCalls: { addTask, toggleTask, deleteTask },
+  } = useMUD();
+
+  const tasks = useStore((state) => {
+    const records = Object.values(state.getRecords(tables.Tasks));
+    records.sort((a, b) => Number(a.value.createdAt - b.value.createdAt));
+    return records;
+  });
+
+  return (
+    <>
+      <table>
+        <tbody>
+          {tasks.map((task) => (
+            <tr key={task.id}>
+              <td align="right">
+                <input
+                  type="checkbox"
+                  checked={task.value.completedAt > 0n}
+                  title={task.value.completedAt === 0n ? "Mark task as completed" : "Mark task as incomplete"}
+                  onChange={async (event) => {
+                    event.preventDefault();
+                    const checkbox = event.currentTarget;
+
+                    checkbox.disabled = true;
+                    try {
+                      await toggleTask(task.key.id);
+                    } finally {
+                      checkbox.disabled = false;
+                    }
+                  }}
+                />
+              </td>
+              <td>{task.value.completedAt > 0n ? <s>{task.value.description}</s> : <>{task.value.description}</>}</td>
+              <td align="right">
+                <button
+                  type="button"
+                  title="Delete task"
+                  style={styleUnset}
+                  onClick={async (event) => {
+                    event.preventDefault();
+                    if (!window.confirm("Are you sure you want to delete this task?")) return;
+
+                    const button = event.currentTarget;
+                    button.disabled = true;
+                    try {
+                      await deleteTask(task.key.id);
+                    } finally {
+                      button.disabled = false;
+                    }
+                  }}
+                >
+                  &times;
+                </button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+        <tfoot>
+          <tr>
+            <td>
+              <input type="checkbox" disabled />
+            </td>
+            <td colSpan={2}>
+              <form
+                onSubmit={async (event) => {
+                  event.preventDefault();
+                  const form = event.currentTarget;
+                  const fieldset = form.querySelector("fieldset");
+                  if (!(fieldset instanceof HTMLFieldSetElement)) return;
+
+                  const formData = new FormData(form);
+                  const desc = formData.get("description");
+                  if (typeof desc !== "string") return;
+
+                  fieldset.disabled = true;
+                  try {
+                    await addTask(desc);
+                    form.reset();
+                  } finally {
+                    fieldset.disabled = false;
+                  }
+                }}
+              >
+                <fieldset style={styleUnset}>
+                  <input type="text" name="description" />{" "}
+                  <button type="submit" title="Add task">
+                    Add
+                  </button>
+                </fieldset>
+              </form>
+            </td>
+          </tr>
+        </tfoot>
+      </table>
+    </>
+  );
+};
diff --git a/examples/local-explorer/packages/client/src/MUDContext.tsx b/examples/local-explorer/packages/client/src/MUDContext.tsx
@@ -0,0 +1,21 @@
+import { createContext, ReactNode, useContext } from "react";
+import { SetupResult } from "./mud/setup";
+
+const MUDContext = createContext<SetupResult | null>(null);
+
+type Props = {
+  children: ReactNode;
+  value: SetupResult;
+};
+
+export const MUDProvider = ({ children, value }: Props) => {
+  const currentValue = useContext(MUDContext);
+  if (currentValue) throw new Error("MUDProvider can only be used once");
+  return <MUDContext.Provider value={value}>{children}</MUDContext.Provider>;
+};
+
+export const useMUD = () => {
+  const value = useContext(MUDContext);
+  if (!value) throw new Error("Must be used within a MUDProvider");
+  return value;
+};
diff --git a/examples/local-explorer/packages/client/src/index.tsx b/examples/local-explorer/packages/client/src/index.tsx
@@ -0,0 +1,34 @@
+import ReactDOM from "react-dom/client";
+import { App } from "./App";
+import { setup } from "./mud/setup";
+import { MUDProvider } from "./MUDContext";
+import mudConfig from "contracts/mud.config";
+
+const rootElement = document.getElementById("react-root");
+if (!rootElement) throw new Error("React root not found");
+const root = ReactDOM.createRoot(rootElement);
+
+// TODO: figure out if we actually want this to be async or if we should render something else in the meantime
+setup().then(async (result) => {
+  root.render(
+    <MUDProvider value={result}>
+      <App />
+    </MUDProvider>,
+  );
+
+  // https://vitejs.dev/guide/env-and-mode.html
+  if (import.meta.env.DEV) {
+    const { mount: mountDevTools } = await import("@latticexyz/dev-tools");
+    mountDevTools({
+      config: mudConfig,
+      publicClient: result.network.publicClient,
+      walletClient: result.network.walletClient,
+      latestBlock$: result.network.latestBlock$,
+      storedBlockLogs$: result.network.storedBlockLogs$,
+      worldAddress: result.network.worldContract.address,
+      worldAbi: result.network.worldContract.abi,
+      write$: result.network.write$,
+      useStore: result.network.useStore,
+    });
+  }
+});
diff --git a/examples/local-explorer/packages/client/src/mud/createSystemCalls.ts b/examples/local-explorer/packages/client/src/mud/createSystemCalls.ts
@@ -0,0 +1,56 @@
+/*
+ * Create the system calls that the client can use to ask
+ * for changes in the World state (using the System contracts).
+ */
+
+import { Hex } from "viem";
+import { SetupNetworkResult } from "./setupNetwork";
+
+export type SystemCalls = ReturnType<typeof createSystemCalls>;
+
+export function createSystemCalls(
+  /*
+   * The parameter list informs TypeScript that:
+   *
+   * - The first parameter is expected to be a
+   *   SetupNetworkResult, as defined in setupNetwork.ts
+   *
+   *   Out of this parameter, we only care about two fields:
+   *   - worldContract (which comes from getContract, see
+   *     https://github.com/latticexyz/mud/blob/main/templates/react/packages/client/src/mud/setupNetwork.ts#L63-L69).
+   *
+   *   - waitForTransaction (which comes from syncToRecs, see
+   *     https://github.com/latticexyz/mud/blob/main/templates/react/packages/client/src/mud/setupNetwork.ts#L77-L83).
+   *
+   * - From the second parameter, which is a ClientComponent,
+   *   we only care about Counter. This parameter comes to use
+   *   through createClientComponents.ts, but it originates in
+   *   syncToRecs
+   *   (https://github.com/latticexyz/mud/blob/main/templates/react/packages/client/src/mud/setupNetwork.ts#L77-L83).
+   */
+  { tables, useStore, worldContract, waitForTransaction }: SetupNetworkResult,
+) {
+  const addTask = async (label: string) => {
+    const tx = await worldContract.write.app__addTask([label]);
+    await waitForTransaction(tx);
+  };
+
+  const toggleTask = async (id: Hex) => {
+    const isComplete = (useStore.getState().getValue(tables.Tasks, { id })?.completedAt ?? 0n) > 0n;
+    const tx = isComplete
+      ? await worldContract.write.app__resetTask([id])
+      : await worldContract.write.app__completeTask([id]);
+    await waitForTransaction(tx);
+  };
+
+  const deleteTask = async (id: Hex) => {
+    const tx = await worldContract.write.app__deleteTask([id]);
+    await waitForTransaction(tx);
+  };
+
+  return {
+    addTask,
+    toggleTask,
+    deleteTask,
+  };
+}