Merge pull request #11378 from linode/staging

Release v1.133.0 - `staging` → `master`

Author: hkhalil-akamai

docs/PULL_REQUEST_TEMPLATE.md

@@ -1,15 +1,20 @@
 ## Description 📝
+
 Highlight the Pull Request's context and intentions.
 
 ## Changes  🔄
-List any change relevant to the reviewer.
+
+List any change(s) relevant to the reviewer.
+
 - ...
 - ...
 
 ## Target release date 🗓️
-Please specify a release date to guarantee timely review of this PR. If exact date is not known, please approximate and update it as needed.
+
+Please specify a release date (and environment, if applicable) to guarantee timely review of this PR. If exact date is not known, please approximate and update it as needed.
 
 ## Preview 📷
+
 **Include a screenshot or screen recording of the change.**
 
 :lock: Use the [Mask Sensitive Data](https://cloud.linode.com/profile/settings) setting for security.
@@ -23,38 +28,58 @@ Please specify a release date to guarantee timely review of this PR. If exact da
 ## How to test 🧪
 
 ### Prerequisites
+
 (How to setup test environment)
+
 - ...
 - ...
 
 ### Reproduction steps
+
 (How to reproduce the issue, if applicable)
-- ...
-- ...
+
+- [ ] ...
+- [ ] ...
 
 ### Verification steps
+
 (How to verify changes)
-- ...
-- ...
 
-## As an Author I have considered 🤔
+- [ ] ...
+- [ ] ...
+
+<details>
+<summary> Author Checklists </summary>
+
+## As an Author, to speed up the review process, I considered 🤔
+
+👀 Doing a self review
+❔ Our [contribution guidelines](https://github.com/linode/manager/blob/develop/docs/CONTRIBUTING.md)
+🤏 Splitting feature into small PRs
+➕ Adding a [changeset](https://github.com/linode/manager/blob/develop/docs/CONTRIBUTING.md#writing-a-changeset)
+🧪 Providing/improving test coverage
+ 🔐 Removing all sensitive information from the code and PR description
+🚩 Using a feature flag to protect the release
+👣 Providing comprehensive reproduction steps
+📑 Providing or updating our documentation
+🕛 Scheduling a pair reviewing session
+📱 Providing mobile support
+♿  Providing accessibility support
 
-*Check all that apply*
+<br/>
 
-- [ ] 👀 Doing a self review
-- [ ] ❔ Our [contribution guidelines](https://github.com/linode/manager/blob/develop/docs/CONTRIBUTING.md)
-- [ ] 🤏 Splitting feature into small PRs
-- [ ] ➕ Adding a [changeset](https://github.com/linode/manager/blob/develop/docs/CONTRIBUTING.md#writing-a-changeset)
-- [ ] 🧪 Providing/Improving test coverage
-- [ ] 🔐 Removing all sensitive information from the code and PR description
-- [ ] 🚩 Using a feature flag to protect the release
-- [ ] 👣 Providing comprehensive reproduction steps
-- [ ] 📑 Providing or updating our documentation
-- [ ] 🕛 Scheduling a pair reviewing session
-- [ ] 📱 Providing mobile support
-- [ ] ♿  Providing accessibility support
+- [ ] I have read and considered all applicable items listed above.
+
+## As an Author, before moving this PR from Draft to Open, I confirmed ✅
+
+- [ ] All unit tests are passing
+- [ ] TypeScript compilation succeeded without errors
+- [ ] Code passes all linting rules
+
+</details>
 
 ---
+
 ## Commit message and pull request title format standards
 
 > **Note**: Remove this section before opening the pull request
@@ -63,6 +88,7 @@ Please specify a release date to guarantee timely review of this PR. If exact da
 `<commit type>: [JIRA-ticket-number] - <description>`
 
 **Commit Types:**
+
 - `feat`: New feature for the user (not a part of the code, or ci, ...).
 - `fix`: Bugfix for the user (not a fix to build something, ...).
 - `change`: Modifying an existing visual UI instance. Such as a component or a feature.

docs/development-guide/04-component-library.md

@@ -7,7 +7,7 @@ We use [Material-UI](https://mui.com/material-ui/getting-started/overview/) as t
 All MUI components have abstractions in the Cloud Manager codebase, meaning you will use relative imports to use them instead of importing from MUI directly:
 
 ```ts
-import { Typography } from "src/components/Typography"; // NOT from '@mui/material/Typography'
+import { Typography } from "@linode/ui"; // NOT from '@mui/material/Typography'
 ```
 
 We do this because it gives us the ability to customize the component and still keep imports consistent. It also gives us flexibility if we ever wanted to change out the underlying component library.

docs/development-guide/08-testing.md

@@ -6,38 +6,38 @@ The unit tests for Cloud Manager are written in Typescript using the [Vitest](ht
 
 To run tests, first build the **api-v4** package:
 
-```
+```shell
 yarn install:all && yarn workspace @linode/api-v4 build
 ```
 
 Then you can start the tests:
 
-```
+```shell
 yarn test
 ```
 
 Or you can run the tests in watch mode with:
 
-```
+```shell
 yarn test:watch
 ```
 
 To run a specific file or files in a directory:
 
-```
+```shell
 yarn test myFile.test.tsx
 yarn test src/some-folder
 ```
 
 Vitest has built-in pattern matching, so you can also do things like run all tests whose filename contains "Linode" with:
 
-```
+```shell
 yarn test linode
 ```
 
 To run a test in debug mode, add a `debugger` breakpoint inside one of the test cases, then run:
 
-```
+```shell
 yarn workspace linode-manager run test:debug
 ```
 
@@ -64,31 +64,25 @@ describe("My component", () => {
 Handling events such as clicks is a little more involved:
 
 ```js
-import { fireEvent } from "@testing-library/react";
+import { userEvent } from '@testing-library/user-event';
 import { renderWithTheme } from "src/utilities/testHelpers";
 import Component from "./wherever";
 
 const props = { onClick: vi.fn() };
 
 describe("My component", () => {
-  it("should have some text", () => {
+  it("should have some text", async () => {
     const { getByText } = renderWithTheme(<Component {...props} />);
     const button = getByText("Submit");
-    fireEvent.click(button);
+    await userEvent.click(button);
     expect(props.onClick).toHaveBeenCalled();
   });
 });
 ```
 
-If, while using the Testing Library, your tests trigger a warning in the console from React ("Warning: An update to Component inside a test was not wrapped in act(...)"), first check out the library author's [blog post](https://kentcdodds.com/blog/fix-the-not-wrapped-in-act-warning) about this. Depending on your situation, you probably will have to `wait` for something in your test:
-
-```js
-import { fireEvent, wait } from '@testing-library/react';
+We recommend using `userEvent` rather than `fireEvent` where possible. This is a [React Testing Library best practice](https://testing-library.com/docs/user-event/intro#differences-from-fireevent), because `userEvent` more accurately simulates user interactions in a browser and makes the test more reliable in catching unintended event handler behavior.
 
-...
-await wait(() => fireEvent.click(getByText('Delete')));
-...
-```
+If, while using the Testing Library, your tests trigger a warning in the console from React ("Warning: An update to Component inside a test was not wrapped in act(...)"), first check out the library author's [blog post](https://kentcdodds.com/blog/fix-the-not-wrapped-in-act-warning) about this. Depending on your situation, you probably will have to use [`findBy`](https://testing-library.com/docs/dom-testing-library/api-async/#findby-queries) or [`waitFor`](https://testing-library.com/docs/dom-testing-library/api-async/) for something in your test to ensure asynchronous side-effects have completed.
 
 ### Mocking
 
@@ -108,7 +102,9 @@ vi.mock('@linode/api-v4/lib/kubernetes', async () => {
 
 Some components, such as our ActionMenu, don't lend themselves well to unit testing (they often have complex DOM structures from MUI and it's hard to target). We have mocks for most of these components in a `__mocks__` directory adjacent to their respective components. To make use of these, just tell Vitest to use the mock:
 
+```js
     vi.mock('src/components/ActionMenu/ActionMenu');
+```
 
 Any `<ActionMenu>`s rendered by the test will be simplified versions that are easier to work with.
 
@@ -157,6 +153,7 @@ We use [Cypress](https://cypress.io) for end-to-end testing. Test files are foun
     * Select a reasonable expiry time (avoid "Never") and make sure that every permission is set to "Read/Write".
 3. Set the `MANAGER_OAUTH` environment variable in your `.env` file using your new personal access token.
     * Example of `.env` addition:
+
         ```shell
         # Manager OAuth token for Cypress tests:
         # (The real token will be a 64-digit string of hexadecimals).
@@ -174,16 +171,19 @@ We use [Cypress](https://cypress.io) for end-to-end testing. Test files are foun
 Cloud Manager UI tests can be configured using environment variables, which can be defined in `packages/manager/.env` or specified when running Cypress.
 
 ##### Cypress Environment Variables
+
 These environment variables are used by Cypress out-of-the-box to override the default configuration. Cypress exposes many other options that can be configured with environment variables, but the items listed below are particularly relevant for Cloud Manager testing. More information can be found at [docs.cypress.io](https://docs.cypress.io/guides/guides/environment-variables).
 
 | Environment Variable | Description                                | Example                    | Default                 |
 |----------------------|--------------------------------------------|----------------------------|-------------------------|
 | `CYPRESS_BASE_URL`   | URL to Cloud Manager environment for tests | `https://cloud.linode.com` | `http://localhost:3000` |
 
 ##### Cloud Manager-specific Environment Variables
+
 These environment variables are specific to Cloud Manager UI tests. They can be distinguished from out-of-the-box Cypress environment variables by their `CY_TEST_` prefix.
 
 ###### General
+
 Environment variables related to the general operation of the Cloud Manager Cypress tests.
 
 | Environment Variable | Description                                                                                           | Example      | Default                         |
@@ -192,6 +192,7 @@ Environment variables related to the general operation of the Cloud Manager Cypr
 | `CY_TEST_TAGS`       | Query identifying tests that should run by specifying allowed and disallowed tags.                    | `method:e2e` | Unset; all tests run by default |
 
 ###### Overriding Behavior
+
 These environment variables can be used to override some behaviors of Cloud Manager's UI tests. This can be useful when testing Cloud Manager for nonstandard or work-in-progress functionality.
 
 | Environment Variable    | Description                                     | Example   | Default                                    |
@@ -200,6 +201,7 @@ These environment variables can be used to override some behaviors of Cloud Mana
 | `CY_TEST_FEATURE_FLAGS` | JSON string containing feature flag data        | `{}`      | Unset; feature flag data is not overridden |
 
 ###### Run Splitting
+
 These environment variables facilitate splitting the Cypress run between multiple runners without the use of any third party services. This can be useful for improving Cypress test performance in some circumstances. For additional performance gains, an optional test weights file can be specified using `CY_TEST_SPLIT_RUN_WEIGHTS` (see `CY_TEST_GENWEIGHTS` to generate test weights).
 
 | Environment Variable        | Description                                | Example          | Default                    |
@@ -210,6 +212,7 @@ These environment variables facilitate splitting the Cypress run between multipl
 | `CY_TEST_SPLIT_RUN_WEIGHTS` | Path to test weights file                  | `./weights.json` | Unset; disabled by default |
 
 ###### Development, Logging, and Reporting
+
 Environment variables related to Cypress logging and reporting, as well as report generation.
 
 | Environment Variable            | Description                                        | Example          | Default                    |
@@ -222,6 +225,7 @@ Environment variables related to Cypress logging and reporting, as well as repor
 | `CY_TEST_GENWEIGHTS`            | Generate and output test weights to the given path | `./weights.json` | Unset; disabled by default |
 
 ###### Performance
+
 Environment variables that can be used to improve test performance in some scenarios.
 
 | Environment Variable            | Description                                   | Example            | Default                    |
@@ -233,6 +237,7 @@ Environment variables that can be used to improve test performance in some scena
 
 1. Look here for [Cypress Best Practices](https://docs.cypress.io/guides/references/best-practices)
 2. Test Example:
+
    ```tsx
     /* this test will not pass on cloud manager.
     it is only intended to show correct test structure, syntax,
@@ -293,13 +298,15 @@ Environment variables that can be used to improve test performance in some scena
       });
     });
     ```
+
 3. How to use intercepts:
+
     ```tsx
       // stub response syntax:
       cy.intercept('POST', ‘/path’, {response}) or cy.intercept(‘/path’, (req) => { req.reply({response})}).as('something');
-	    // edit and end response syntax: 
+     // edit and end response syntax: 
       cy.intercept('GET', ‘/path’, (req) => { req.send({edit: something})}).as('something');
-	    // edit request syntax:
+     // edit request syntax:
       cy.intercept('POST', ‘/path’, (req) => { req.body.storyName = 'some name'; req.continue().as('something');
   
       // use alias syntax:

docs/development-guide/15-composition.md

@@ -52,3 +52,74 @@ The Linode Create Page is a good example of a complex form that is built using r
 ### Uncontrolled Forms
 Uncontrolled forms are a type of form that does not have a state for its values. It is often used for simple forms that do not need to be controlled, such as forms with a single input field or call to action.
 
+## Form Validation (React Hook Form)
+### Best Practices
+1. Keep API validation in `@linode/validation` package
+2. Create extended schemas in `@linode/manager` package when you need validation beyond the API contract
+3. Use yup.concat() to extend existing schemas
+4. Add custom validation logic within the resolver function
+5. Include type definitions for form values and context
+
+### Simple Schema Extension
+For basic form validation, extend the API schema directly:
+
+```typescript
+import { CreateWidgetSchema } from '@linode/validation';
+import { object, string } from 'yup';
+import { yupResolver } from '@hookform/resolvers/yup';
+
+const extendedSchema = CreateWidgetSchema.concat(
+  object({
+    customField: string().required('Required field'),
+  })
+);
+
+const form = useForm({
+  resolver: yupResolver(extendedSchema)
+});
+```
+
+### Complex Schema Extensions
+You may create a `resolver` function that handles the validation (see: [ManageImageRegionsForm.tsx](https://github.com/linode/manager/blob/develop/packages/manager/src/features/Images/ImagesLanding/ImageRegions/ManageImageRegionsForm.tsx#L189-L213)):
+
+```typescript
+// Step 1: Create a Resolver Function
+// This function validates your form data against specific requirements
+
+type Resolver<FormData, Context> = (values: FormData, context: Context) => {
+  errors: Record<string, any>;
+  values: FormData;
+};
+
+// Example resolver that checks if at least one item from a list is selected
+const resolver: Resolver<YourFormData, YourContext> = (values, context) => {
+  // Check if at least one valid option is selected
+  const hasValidSelection = values.selectedItems.some(
+    item => context.availableItems.includes(item)
+  );
+
+  if (!hasValidSelection) {
+    return {
+      errors: {
+        selectedItems: {
+          message: 'Please select at least one valid option',
+          type: 'validate'
+        }
+      },
+      values
+    };
+  }
+
+  return { errors: {}, values };
+};
+
+// Step 2: Use the Resolver in Your Form
+const form = useForm({
+  resolver,
+  defaultValues: { selectedItems: [] },
+  context: { availableItems: ['item1', 'item2'] }
+});
+```
+
+### Additional Complexity
+When working with multiple sequential schemas that require validation, you can create a resolver map and function (see: [LinodeCreate/resolvers.ts](https://github.com/linode/manager/blob/develop/packages/manager/src/features/Linodes/LinodeCreate/resolvers.ts])).