docs: finish drafts for hooks/types README files

coder · Parkreiner · Mar 11, 2024 · Mar 4, 2024 · Mar 4, 2024 · Mar 4, 2024
commit 7153251058ddc80012cf7eec59057e23b8bc4d97
diff --git a/plugins/backstage-plugin-coder/docs/api-reference/README.md b/plugins/backstage-plugin-coder/docs/api-reference/README.md
@@ -0,0 +1,9 @@
+# Plugin API Reference – Coder for Backstage
+
+For users who need more information about how to extend and modify the Coder plugin. For general setup, please see our main [README](link goes here).
+
+## Documentation directory
+
+- [Components](./components.md)
+- [Custom React hooks](./hooks.md)
+- [General types](./types.md)
diff --git a/plugins/backstage-plugin-coder/docs/api-reference/hooks.md b/plugins/backstage-plugin-coder/docs/api-reference/hooks.md
@@ -0,0 +1,129 @@
+# Plugin API reference – React hooks
+
+This is the main documentation page for the Coder plugin's React hooks.

+## Hook list
+
+- [`useCoderEntityConfig`](#useCoderEntityConfig)
+- [`useCoderWorkspaces`](#useCoderWorkspaces)
+
+## `useCoderEntityConfig`
+
+This hook gives you access to compiled [`CoderEntityConfig`](./types.md#coderentityconfig) data.
+
+### Type signature
+
+```tsx
+declare function useCoderEntityConfig(): CoderEntityConfig;
+```
+
+[Type definition for `CoderEntityConfig`](./types.md#coderentityconfig)
+
+### Example usage
+
+```tsx
+function YourComponent() {
+  const config = useCoderEntityConfig();
+  return <p>Your repo URL is {config.repoUrl}</p>;
+}
+
+// All other components provided via @backstage/plugin-catalog
+// and should be statically initialized
+const overviewContent = (
+  <Grid container spacing={3} alignItems="stretch">
+    <Grid item md={6} xs={12}>
+      <YourComponent />
+    </Grid>
+  </Grid>
+);
+
+const serviceEntityPage = (
+  <EntityLayout>
+    <EntityLayout.Route path="/" title="Overview">
+      {overviewContent}
+    </EntityLayout.Route>
+  </EntityLayout>
+);
+
+// etc.
+```
+
+### Throws
+
+- Will throw an error if called outside a React component
+- Will throw an error if called outside an `EntityLayout` (or any other Backstage component that exposes `Entity` data via React Context)
+
+### Notes
+
+- The type definition for `CoderEntityConfig` [can be found here](./types.md#coderentityconfig). That section also includes info on the heuristic used for compiling the data
+- The hook tries to ensure that the returned value maintains a stable memory reference as much as possible, if you ever need to use that value in other React hooks that use dependency arrays (e.g., `useEffect`, `useCallback`)
+
+## `useCoderWorkspaces`
+
+This hook gives you access to all workspaces that match a given query string. If
+[`repoConfig`](#usecoderentityconfig) is defined via `options`, the workspaces returned will be filtered down further to only those that match the the repo.
+
+### Type signature
+
+```ts
+type UseCoderWorkspacesOptions = Readonly<
+  Partial<{
+    repoConfig: CoderEntityConfig;
+  }>
+>;
+
+declare function useCoderEntityConfig(
+  coderQuery: string,
+  options?: UseCoderWorkspacesOptions,
+): UseQueryResult<readonly Workspace[]>;
+```
+
+### Example usage
+
+```tsx
+function YourComponent() {
+  const entityConfig = useCoderEntityConfig();
+  const [filter, setFilter] = useState('owner:me');
+
+  const query = useCoderWorkspaces(filter, {
+    repoConfig: entityConfig,
+  });
+
+  return (
+    <>
+      {query.isLoading && <YourLoadingIndicator />}
+      {query.isError && <YourErrorDisplay />}
+
+      {query.data?.map(workspace => (
+        <ol>
+          <li key={workspace.key}>{workspace.name}</li>
+        </ol>
+      ))}
+    </>
+  );
+}
+
+const coderAppConfig: CoderAppConfig = {
+  // ...Properties go here
+};
+
+<CoderProvider appConfig={coderAppConfig}>
+  <CoderAuthWrapper>
+    <YourComponent />
+  </CoderAuthWrapper>
+</CoderProvider>;
+```
+
+### Throws
+
+- Will throw an error if called outside a React component
+- Will throw an error if the component calling the hook is not wrapped inside a [`CoderProvider`](./components.md#CoderProvider)
+
+### Notes
+
+- `UseQueryResult` is taken from [React Query v4](https://tanstack.com/query/v4/docs/framework/react/reference/useQuery)
+  - We recommend [TK Dodo's Practical React Query blog series](https://tkdodo.eu/blog/practical-react-query) for how to make the most of its features. (Particularly the article on [React Query status checks](https://tkdodo.eu/blog/status-checks-in-react-query))
+- The underlying query will not be enabled if:
+  1.  The user is not currently authenticated (We recommend wrapping your component inside [`CoderAuthWrapper`](./components.md#coderauthwrapper) to make these checks easier)
+  2.  If `repoConfig` is passed in via `options`: when the value of `coderQuery` is an empty string
+- `CoderEntityConfig` is the return type of [`useCoderEntityConfig`](#usecoderentityconfig)
diff --git a/plugins/backstage-plugin-coder/docs/api-reference/types.md b/plugins/backstage-plugin-coder/docs/api-reference/types.md
@@ -0,0 +1,169 @@
+# Plugin API reference – Important types
+
+## Types directory
+
+- [`CoderAppConfig`](#coderappconfig)
+- [`CoderEntityConfig`](#coderentityconfig)
+- [`Workspace`](#workspace)
+- [`WorkspaceResponse`](#workspaceresponse)
+
+## `CoderAppConfig`
+
+## `CoderEntityConfig`
+
+Represents the result of compiling Coder plugin configuration data. All data will be compiled from the following sources:
+
+1. The [`CoderAppConfig`](#coderappconfig) passed to [`CoderProvider`](./components.md#coderprovider)
+2. The entity-specific fields for a given repo's `catalog-info.yaml` file
+3. The entity's location metadata (corresponding to the repo)
+
+### Type definition
+
+```tsx
+type CoderEntityConfig = Readonly<{
+  mode: 'manual' | 'auto';
+  params: Record<string, string | undefined>;
+  repoUrl: string | undefined;
  repoUrlParamKeys: [string, ...string[]][];
+  templateName: string;
+}>;
+```
+
+### Example
+
+Let's say that you have these inputs:
+
+```tsx
+const appConfig: CoderAppConfig = {
+  deployment: {
+    accessUrl: 'https://dev.coder.com',
+  },
+
+  workspaces: {
+    templateName: 'devcontainers',
+    mode: 'manual',
+    repoUrlParamKeys: ['custom_repo', 'repo_url'],
+    params: {
+      repo: 'custom',
+      region: 'eu-helsinki',
+    },
+  },
+};
+```
+
+```yaml
+# https://github.com/Parkreiner/python-project/blob/main/catalog-info.yaml
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: python-project
+spec:
+  type: other
+  lifecycle: unknown
+  owner: pms
+  coder:
+    templateName: 'devcontainers'
+    mode: 'auto'
+    params:
+      repo: 'custom'
+      region: 'us-pittsburgh'
+```
+
+Your output will look like this:
+
+```tsx
+const config: CoderEntityConfig = {
+  mode: 'auto',
+  params: {
+    repo: 'custom',
+    region: 'us-pittsburgh',
+    custom_repo: 'https://github.com/Parkreiner/python-project/',
+    repo_url: 'https://github.com/Parkreiner/python-project/',
+  },
+  repoUrl: 'https://github.com/Parkreiner/python-project/',
+  repoUrlParamKeys: ['custom_repo', 'repo_url'],
+  templateName: 'devcontainers',
+};
+```
+
+### Notes
+
+- See the notes for [`CoderAppConfig`](#coderappconfig) for additional information on some of the fields.
+- The value of the `repoUrl` property is derived from [Backstage's `getEntitySourceLocation`](https://backstage.io/docs/reference/plugin-catalog-react.getentitysourcelocation/), which does not guarantee that a URL will always be defined.
+- This is the current order of operations used to reconcile param data between `CoderAppConfig`, `catalog-info.yaml`, and the entity location data:
+  1. Start with an empty `Record<string, string | undefined>` value
+  2. Populate the record with the data from `CoderAppConfig`
+  3. Go through all properties parsed from `catalog-info.yaml` and inject those. If the properties are already defined, overwrite them
+  4. Grab the repo URL from the entity's location fields.
+  5. For each key in `CoderAppConfig`'s `workspaces.repoUrlParamKeys` property, take that key, and inject it as a key-value pair, using the URL as the value. If the key already exists, always override it with the URL
+
+## `Workspace`
+
+Represents a single Coder workspace.
+
+### Type definition
+
+The below type definitions are likely to be split up at a later date. They are currently defined together for convenience.
+
+```tsx
+type WorkspaceAgentStatus =
+  | 'connected'
+  | 'connecting'
+  | 'disconnected'
+  | 'timeout';
+
+type WorkspaceAgent = {
+  id: string;
+  status: WorkspaceAgentStatus;
+};
+
+type WorkspaceResource = {
+  id: string;
+  agents: WorkspaceAgent[];
+};
+
+type WorkspaceStatus =
+  | 'canceled'
+  | 'canceling'
+  | 'deleted'
+  | 'deleting'
+  | 'failed'
+  | 'pending'
+  | 'running'
+  | 'starting'
+  | 'stopped'
+  | 'stopping';
+
+type Workspace = {
+  name: string;
+  id: string;
+  template_icon: string;
+  owner_name: string;
+  latest_build: {
+    id: string;
+    status: WorkspaceStatus;
+    resources: WorkspaceResource[];
+  };
+};
+```
+
+### Notes
+
+- Right now, the number of fields is limited. One planned feature is to expand the type definition to make all Coder workspace properties available
+
+## `WorkspaceResponse`
+
+Represents the JSON value that will be part of the response to any workspace API call.
+
+### Type definition
+
+```tsx
+type WorkspaceResponse = {
+  count: number;
+  workspaces: Workspace[];
+};
+```
+
+### Notes
+
+- `count` is the total number of workspaces in the response