devex: Add frontend code snippet & update dev docs (#2494)

- Adds VSCode file template for component unit testing.
- Updates development docs with details on UI dev

.vscode/snippets.code-snippets

@@ -2,6 +2,7 @@
   "Btrix Component": {
     "scope": "javascript,typescript",
     "prefix": ["component", "@customElement"],
+    "isFileTemplate": true,
     "body": [
       "import { localized } from \"@lit/localize\";",
       "import { html } from \"lit\";",
@@ -18,5 +19,40 @@
       "}",
       ""
     ]
+  },
+  "Btrix Component Test": {
+    "scope": "javascript,typescript",
+    "prefix": ["test","describe"],
+    "isFileTemplate": true,
+    "body": [
+      "import { expect, fixture } from \"@open-wc/testing\";",
+      "import { html } from \"lit/static-html.js\";",
+      "import { restore, stub } from \"sinon\";",
+      "",
+      "import { ${1:Component} } from \"./${TM_FILENAME_BASE/\\.test(.*)/$1/}\";",
+      "",
+      "import { AppStateService } from \"@/utils/state\";",
+      "",
+      "describe(\"<btrix-${TM_FILENAME_BASE/\\.test(.*)/$1/}>\", () => {",
+      "  beforeEach(() => {",
+      "    AppStateService.resetAll();",
+      "    stub(window.history, \"pushState\");",
+      "  });",
+      "",
+      "  afterEach(() => {",
+      "    restore();",
+      "  });",
+      "",
+      "  it(\"is defined\", async () => {",
+      "    const el = await fixture<${1:Component}>(",
+      "      html`<btrix-${TM_FILENAME_BASE/\\.test(.*)/$1/}></btrix-${TM_FILENAME_BASE/\\.test(.*)/$1/}>`,",
+      "    );",
+      "",
+      "    expect(el).instanceOf(${1:Component});",
+      "  });",
+      "});",
+      ""
+    ],
+    "description": "Unit test for custom component that extends `BtrixComponent`"
   }
 }

frontend/docs/docs/develop/frontend-dev.md

@@ -1,8 +1,8 @@
-# Developing the Frontend UI
+# Developing with Yarn
 
-This guide explains how to run the Browsertrix frontend development server with [Yarn](https://classic.yarnpkg.com).
+This guide explains how to build and serve the Browsertrix user interface with [Yarn](https://classic.yarnpkg.com).
 
-Instead of rebuilding the entire frontend image to view your UI changes, you can use the included local development server to access the frontend from your browser. This setup is ideal for rapid UI development that does not rely on any backend changes.
+Developing the user interface with Yarn bypasses the need to rebuild the entire frontend Docker image to view your UI changes. This setup is ideal for rapid UI development that does not rely on any backend changes.
 
 ## Requirements
 
@@ -10,6 +10,8 @@ Instead of rebuilding the entire frontend image to view your UI changes, you can
 
 The frontend development server requires an existing backend that has been deployed locally or is in production. See [Deploying Browsertrix](../deploy/index.md).
 
+Once deployed, make note of the URL to the backend API. If you've deployed the backend locally using default values, the URL will be `http://localhost:30870`.
+
 ### 2. Node.js ≥20
 
 To check if you already have Node.js installed, run the following command in your command line terminal:
@@ -71,17 +73,7 @@ Copy environment variables from the sample file:
 cp sample.env.local .env.local
 ```
 
-Update `API_BASE_URL` in `.env.local` to point to your backend API host. For example:
-
-```
-API_BASE_URL=http://dev.example.com
-```
-
-!!! note
-
-    This setup assumes that your API endpoints are available under `/api`, which is the default configuration for the Browsertrix backend.
-
-If connecting to a local deployment cluster, set `API_BASE_URL` to:
+Update `API_BASE_URL` in `.env.local` to point to your backend API URL noted earlier. For example, if connecting to your local deployment cluster:
 
 ```
 API_BASE_URL=http://localhost:30870
@@ -94,6 +86,10 @@ API_BASE_URL=http://localhost:30870
 
     Set API_BASE_URL to provided URL instead, eg. `API_BASE_URL=http://127.0.0.1:<TUNNEL_PORT>`
 
+!!! note
+
+    This setup assumes that your API endpoints are available under `/api`, which is the default configuration for the Browsertrix backend.
+
 Start the frontend development server:
 
 ```sh

frontend/docs/docs/develop/ui/components.md

@@ -0,0 +1,67 @@
+# Writing Components
+
+The Browsertrix UI is composed of [web components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) written in [TypeScript](https://www.typescriptlang.org/).
+
+Primary UI tools are:
+
+- **[Lit](https://lit.dev/docs/)** — TypeScript framework for building reactive web components. All web application logic and templating is handled in Lit-enhanced web components.
+- **[Shoelace](https://shoelace.style/)** — Web component library of common UI components like buttons and form elements. These components are themed with custom CSS variables.
+- **[Tailwind](https://tailwindcss.com/)** — CSS utility library of composable classes. Browsertrix components are primarily styled by including Tailwind utility classes in HTML markup, which is rendered by Lit's template system.
+- **[`@open-wc/testing`](https://open-wc.org/docs/testing/testing-package/)** — Test helpers for writing web component unit tests.
+
+## Create a New Component
+
+### Directory Structure
+
+Component files should be created under `frontend/src` in the relevant folder:
+
+- **`/components`** — Common UI elements that can be reused throughout the web app.
+- **`/features`** — Specialized UI components that can be reused within a particular Browsertrix feature, but aren't generic enough to be reused across the web app. These components usually rely on specific data from the Browsertrix API.
+- **`/pages`** — Web components that correspond to a route.
+
+### Naming Convention
+
+Web components names are written are in kebab case (ex: `my-custom-component`). The component file is named after the component (ex: `my-custom-component.ts`).
+
+When defining a custom web component in Browsertrix, the `btrix-` prefix is added to the tag to distinguish Browsertrix components from third-party web components. Using the `my-custom-component` example, the component would appear in markup as such:
+
+```html
+<btrix-my-custom-component></btrix-my-custom-component>
+```
+
+### Defining a Custom Component
+
+Browsertrix includes extensible TypeScript classes for defining custom components. One of the following classes should be used to define a web component, rather than extending `LitElement` directly.
+
+- **`TailwindElement`** — Components that are styled with Tailwind CSS utility classes. Use to define simple, styled UI elements that do not need access to global UI state, do not make API calls, and do not have any global side effects (like navigation.)
+- **`BtrixElement`** — Styled components that are contextualized with shared UI state. Use to define complex components that need access to global state to make API calls, and produce global side effects like navigation, toast alerts, or user locale changes.
+
+Regardless of the base class, Browsertrix components are composable. A common pattern is to create a `BtrixElement` that composes multiple `TailwindElement` components or Shoelace components.
+
+The following example is of a component that extends `BtrixElement` to access the current user's name in global state (`this.appState.userInfo`) and renders it as a custom confirmation composed of multiple `TailwindElement` components (`<btrix-alert>`, `<btrix-button>`).
+
+```ts
+// my-custom-component.ts
+@customElement("btrix-my-custom-component")
+class MyCustomComponent extends BtrixElement {
+  render() {
+    return html`
+      <btrix-alert>
+        Hello, are you ${this.appState.userInfo.name}?
+
+        <btrix-button>Yes</btrix-button>
+      </btrix-alert>
+    `;
+  }
+}
+```
+
+### VS Code Snippet
+
+If developing with [Visual Studio Code](https://code.visualstudio.com/), you can generate boilerplate for a `BtrixElement` Browsertrix component by typing in `component` to any TypeScript file and selecting "Btrix Component". Hit ++tab++ to move your cursor between fillable fields in the boilerplate code.
+
+### Unit Testing
+
+Unit test files live next to the component file and are suffixed with `.test` (ex: `my-custom-component.test.ts`).
+
+You can also generate boilerplate for a component test in VS Code by creating a new `.test.ts` file, then typing `test` and selecting "Btrix Component Test".

frontend/docs/mkdocs.yml

@@ -89,9 +89,11 @@ nav:
   - Development:
       - develop/index.md
       - develop/local-dev-setup.md
-      - develop/frontend-dev.md
-      - develop/localization.md
       - develop/docs.md
+      - UI Development:
+        - develop/frontend-dev.md
+        - develop/ui/components.md
+        - develop/localization.md
 
   - API Reference: !ENV [ API_DOCS_URL, "/api/" ]