Merge pull request #2459 from zetkin/release-250107

250107 Release

Author: richardolsson

.gitignore

@@ -43,4 +43,8 @@ yarn-error.log*
 .idea
 
 # typescript
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# generated docs
+public/docs
+public/storybook

docs/environment-variables/environment-variables.md

@@ -0,0 +1,71 @@
+---
+title: Environment Variables
+category: Environment Variables
+---
+
+# Environment Variables
+
+## Build-Time vs Runtime Environment Variables
+
+Next.js is designed around Vercel's Platform-as-a-Service (PaaS) hosting
+business. Apps on Vercel can have multiple deployment environments such as
+staging and production, and a different build of the app is compiled for each
+environment. Next.js includes functionality to support Vercel's
+one-environment-per-build deployment model, where any environment variables
+needed by client-side code are [inlined directly into the compiled JavaScript](https://nextjs.org/docs/pages/building-your-application/configuring/environment-variables#bundling-environment-variables-for-the-browser)
+bundle at build time.
+
+Outside of Vercel's hosting platform, Docker images are a common way to
+distribute and deploy software. Self-hosted open source software is often
+distributed as pre-built Docker images whose operators apply environment
+variables to them at runtime. This is a deployment model with multiple
+environments per build, where environment variables cannot be known at build
+time. It also happens to be Zetkin's deployment model.
+
+The emphasis that Next.js places on the Vercel platform's deployment
+model in its architecture and documentation can easily lead to confusion when
+working on an app like Zetkin with a different deployment model. The fact that
+handling runtime environment variables looks different under the newer app
+router paradigm compared to the older pages router code also adds to the sense
+of complexity here. So here's how Zetkin's runtime environment variables work in
+both Next.js routing paradigms.
+
+## Runtime Environment Variables In App Router Code
+
+The `<RootLayout>` component in `src/app/layout.tsx` makes a set of runtime
+environment variables from the Node.js process on the server available to
+client-side code by adding them as values to a `ClientContext` provider.
+
+The [`EnvVars`](../types/EnvVars.html) type alias is a good starting point when
+adding a new runtime environment variable to app router code. Add your variable
+there and then fix any resulting type errors and you'll be up and running.
+
+## Runtime Environment Variables In Pages Router Code
+
+Just about every page component in `src/pages/` uses the `scaffold()` function
+to generate its [`getServerSideProps()`](https://nextjs.org/docs/pages/building-your-application/data-fetching/get-server-side-props) function.
+
+The [`EnvVars`](../types/EnvVars.html) type alias is also the place to look
+first when adding a new runtime environment variable to pages router code.
+
+## Accessing Runtime Environment Variables In Components
+
+The [`useEnv`](../functions/useEnv.html) hook returns an
+[`Environment`](../classes/Environment.html) instance which provides reads access to runtime environment variables via its [`vars` property](../classes/Environment.html#vars).
+
+```typescript
+const Component = () => {
+  const env = useEnv();
+  return (
+    <a href={env.vars.ZETKIN_GEN2_ORGANIZE_URL}>Go to the old interface</a>
+  );
+};
+```
+
+## Further Reading
+
+Zetkin's far from the only project to have solved this problem.
+
+- [NextJS on Docker: Managing Environment Variables Across Different Environments](https://medium.com/@ihcnemed/nextjs-on-docker-managing-environment-variables-across-different-environments-972b34a76203)
+- [Next.js with Public Environment Variables in Docker](https://dev.to/vorillaz/nextjs-with-public-environment-variables-in-docker-4ogf)
+- [Runtime Environment Variables in Next.js](https://notes.dt.in.th/NextRuntimeEnv)

docs/index.ts

@@ -0,0 +1,14 @@
+import Environment from 'core/env/Environment';
+import { useEnv } from 'core/hooks';
+
+export { type RemoteItem, type RemoteList } from 'utils/storeUtils';
+export {
+  loadItemIfNecessary,
+  loadListIfNecessary,
+} from 'core/caching/cacheUtils';
+export { default as shouldLoad } from 'core/caching/shouldLoad';
+export { default as ZUIFuture, type ZUIFutureProps } from 'zui/ZUIFuture';
+export { type IFuture } from 'core/caching/futures';
+export { removeOffset } from 'utils/dateUtils';
+export { type EnvVars } from 'core/env/Environment';
+export { Environment, useEnv };

docs/testing/jest.md

@@ -0,0 +1,32 @@
+---
+title: Jest
+category: Testing
+---
+
+# Jest
+
+## Running Jest
+
+### Run all tests
+
+```
+yarn test
+```
+
+It can be useful to run the whole test suite if you've changed a few files as part of whatever you're working on.
+
+### Run one test
+
+```
+yarn test src/utils/dateUtils.spec.ts
+```
+
+When you're working on one particular file, you can run its tests by putting the path to them after `yarn test`.
+
+### Watch mode
+
+```
+yarn test --watch src/utils/dateUtils.spec.ts
+```
+
+During focused work on a single file, it can be helpful to use the `--watch` flag to re-run the tests automatically every time you change something.

docs/testing/playwright.md

@@ -0,0 +1,77 @@
+---
+title: Playwright
+category: Testing
+---
+
+# Playwright
+
+## Running Playwright
+
+### Run all tests
+
+```
+yarn playwright
+```
+
+It can be useful to run the whole playwright suite if you've changed a few features as part of whatever you're working on.
+
+### Run one test
+
+```
+yarn playwright tests/organize/views/detail/display.spec.ts
+```
+
+When you're working on one particular feature, you can run its playwright tests by putting the path to them after `yarn playwright`.
+
+### Skip the build
+
+```
+yarn playwright:skipbuild tests/organize/views/detail/display.spec.ts
+```
+
+The `yarn playwright` script builds the Next.js app before running the tests. This takes several minutes, and isn't useful if you're only changing test code (code in a `.spec.ts` file). You can tell playwright not to include this build step with the `playwright:skipbuild` script.
+
+### Debug mode
+
+```
+yarn playwright:skipbuild --debug tests/organize/views/detail/display.spec.ts
+```
+
+In its default mode of execution, Playwright runs the tests in a headless browser. This means you can't see them running or interact with the browser's developer tools to debug any problems that arise. By adding the `--debug` flag, you can tell Playwright to run the tests visually in a Chrome window so you can see what's happening and debug any problems.
+
+## Writing Playwright tests
+
+### Moxy
+
+Zetkins Playwright tests isolate the Next.js app from the back end very thoroughly by using [moxy](https://github.com/zetkin/moxy) to set up placeholder responses. This means the tests can run without the app ever actually communicating with the real back end. The purpose of this is to make the tests more deterministic, which means they should only break because of a problem with the code, because nobody can break them by mistake by changing something in the dev server's database that they depend on.
+
+The [code search results for `moxy.setZetkinApiMock`](https://github.com/search?q=repo%3Azetkin%2Fapp.zetkin.org%20moxy.setZetkinApiMock&type=code) are a great starting point to learn about setting up these API mocks.
+
+### waitForNavigation
+
+A common step in a Playwright test is to trigger a click on a link and then continue after the page load has completed. The intuitive way to write this code would be like so.
+
+```typescript
+await page.click(`text=Next Page`);
+await page.waitForNavigation();
+```
+
+You won't find any examples of code written that way in Zetkin though. The problem with writing it like that is that the navigation can sometimes complete before the `await page.waitForNavigation()` has even happened, leaving the test stranded waiting for a navigation that's already happened. Instead, we set up both steps simultaneously like this.
+
+```typescript
+await Promise.all([
+  page.waitForNavigation(),
+  page.click(`text=${AllMembers.title}`),
+]);
+```
+
+### Locators
+
+Browser automation tests like these are notorious for sometimes failing randomly. It's difficult to avoid making subtle mistakes and introducing race conditions like the `waitForNavigation` issue above. One general-purpose technique that can help with this is to prefer using [locators](https://playwright.dev/docs/locators) instead of `page.click()`. The first thing Playwright's own [documentation for `page.click`](https://playwright.dev/docs/api/class-page#page-click) says is not to use it.
+
+> **Discouraged**<br />
+> Use locator-based [locator.click()](https://playwright.dev/docs/api/class-locator#locator-click) instead. Read more about [locators](https://playwright.dev/docs/locators).
+
+Using locators instead of `page.click()` maximizes our chances of Playwright's auto-waiting and auto-retrying saving us from a meaningless random test failure resulting from a race condition.
+
+There are lots of examples to learn from in the [code search results for `page.locator`](https://github.com/search?q=repo%3Azetkin%2Fapp.zetkin.org%20page.locator&type=code).

docs/time/time.md

@@ -0,0 +1,14 @@
+---
+title: Time
+category: Time
+---
+
+# Time
+
+## Day.js
+
+Zetkin uses [Day.js](https://day.js.org/) to work with times and dates. Plugins used include [UTC](https://day.js.org/docs/en/plugin/utc), [IsoWeek](https://day.js.org/docs/en/plugin/iso-week), and [CustomParseFormat](https://day.js.org/docs/en/plugin/custom-parse-format).
+
+## Serialization Format
+
+The most commonly used date serialization format around the Zetkin front end is `2024-07-23T12:55:14.279Z`. A code search for [`new Date().toISOString()`](<https://github.com/search?q=repo%3Azetkin%2Fapp.zetkin.org%20%22new%20Date().toISOString()%22&type=code>) shows all the places where the current date & time are being serialized using this format by the front end code.

next.config.js

@@ -13,6 +13,16 @@ module.exports = {
   },
   async redirects() {
     return [
+      {
+        source: '/storybook',
+        destination: '/storybook/index.html',
+        permanent: true,
+      },
+      {
+        source: '/docs',
+        destination: '/docs/index.html',
+        permanent: true,
+      },
       {
         source: '/my',
         destination: '/my/home',

package.json

@@ -7,6 +7,7 @@
     "build": "next build",
     "start": "next start -p 80",
     "devserver": "next dev -p 3000",
+    "docs:build": "storybook build -o public/storybook && typedoc",
     "lint:eslint": "eslint src integrationTesting",
     "lint:prettier": "prettier --check src integrationTesting",
     "lint:translations": "ts-node src/tools/lint-translations",
@@ -21,8 +22,7 @@
     "playwright:skipbuild": "cross-env NODE_ENV=production SKIP_BUILD=1 playwright test",
     "playwright:ci": "cross-env NODE_ENV=production playwright test",
     "storybook": "storybook dev -p 6006",
-    "make-yaml": "ts-node src/tools/make-yaml.ts",
-    "build-storybook": "storybook build"
+    "make-yaml": "ts-node src/tools/make-yaml.ts"
   },
   "dependencies": {
     "@date-io/date-fns": "1.x",
@@ -155,6 +155,7 @@
     "ts-mockito": "^2.6.1",
     "ts-node": "^10.9.1",
     "tsconfig-paths-webpack-plugin": "^3.5.2",
+    "typedoc": "^0.26.5",
     "typescript": "^5.4.3"
   },
   "engines": {

src/app/layout.tsx

@@ -32,8 +32,14 @@ export default async function RootLayout({
         <AppRouterCacheProvider>
           <ClientContext
             envVars={{
-              MUIX_LICENSE_KEY: process.env.MUIX_LICENSE_KEY || null,
-              ZETKIN_APP_DOMAIN: process.env.ZETKIN_APP_DOMAIN || null,
+              FEAT_AREAS: process.env.FEAT_AREAS,
+              INSTANCE_OWNER_HREF: process.env.INSTANCE_OWNER_HREF,
+              INSTANCE_OWNER_NAME: process.env.INSTANCE_OWNER_NAME,
+              MUIX_LICENSE_KEY: process.env.MUIX_LICENSE_KEY,
+              ZETKIN_APP_DOMAIN: process.env.ZETKIN_APP_DOMAIN,
+              ZETKIN_GEN2_ORGANIZE_URL: process.env.ZETKIN_GEN2_ORGANZE_URL,
+              ZETKIN_PRIVACY_POLICY_LINK:
+                process.env.ZETKIN_PRIVACY_POLICY_LINK,
             }}
             headers={headersObject}
             lang={lang}