@scm-manager/ui-core 3.0.0-20240024-101702

package/src/base/forms/Form.stories.tsx

@@ -0,0 +1,453 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2020-present Cloudogu GmbH and Contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/* eslint-disable no-console */
+import React, { useRef, useState } from "react";
+import { storiesOf } from "@storybook/react";
+import Form from "./Form";
+import FormRow from "./FormRow";
+import ControlledInputField from "./input/ControlledInputField";
+import ControlledSecretConfirmationField from "./input/ControlledSecretConfirmationField";
+import ControlledCheckboxField from "./checkbox/ControlledCheckboxField";
+import ControlledList from "./list/ControlledList";
+import ControlledSelectField from "./select/ControlledSelectField";
+import ControlledColumn from "./table/ControlledColumn";
+import ControlledTable from "./table/ControlledTable";
+import AddListEntryForm from "./AddListEntryForm";
+import { ScmFormListContextProvider } from "./ScmFormListContext";
+import { HalRepresentation } from "@scm-manager/ui-types";
+import ControlledChipInputField from "./chip-input/ControlledChipInputField";
+import Combobox from "./combobox/Combobox";
+import ControlledComboboxField from "./combobox/ControlledComboboxField";
+import { defaultOptionFactory } from "./helpers";
+import ChipInput from "./headless-chip-input/ChipInput";
+
+export type SimpleWebHookConfiguration = {
+  urlPattern: string;
+  executeOnEveryCommit: boolean;
+  sendCommitData: boolean;
+  method: string;
+  headers: WebhookHeader[];
+};
+
+export type WebhookHeader = {
+  key: string;
+  value: string;
+  concealed: boolean;
+};
+
+storiesOf("Forms", module)
+  .add("Creation", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        name: "",
+        password: "",
+        active: true,
+      }}
+    >
+      <FormRow>
+        <ControlledInputField rules={{ required: true }} name="name" />
+      </FormRow>
+      <FormRow>
+        <ControlledSecretConfirmationField name="password" />
+      </FormRow>
+      <FormRow>
+        <ControlledCheckboxField name="active" />
+      </FormRow>
+    </Form>
+  ))
+  .add("Editing", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        name: "trillian",
+        password: "secret",
+        passwordConfirmation: "",
+        active: true,
+      }}
+    >
+      <FormRow>
+        <ControlledInputField name="name" />
+      </FormRow>
+      <FormRow>
+        <ControlledSecretConfirmationField name="password" />
+      </FormRow>
+      <FormRow>
+        <ControlledCheckboxField name="active" />
+      </FormRow>
+    </Form>
+  ))
+  .add("Reset", () => {
+    type FormType = {
+      name: string;
+      password: string;
+      passwordConfirmation: string;
+      active: boolean;
+      date: string;
+    };
+    const [defaultValues, setValues] = useState({
+      name: "trillian",
+      password: "secret",
+      passwordConfirmation: "secret",
+      active: true,
+      date: "",
+    });
+    const resetValues = useRef({
+      name: "",
+      password: "",
+      passwordConfirmation: "",
+      active: false,
+      date: "",
+    });
+    return (
+      <Form<FormType>
+        onSubmit={(vals) => {
+          console.log(vals);
+          setValues(vals);
+        }}
+        translationPath={["sample", "form"]}
+        defaultValues={defaultValues as HalRepresentation & FormType}
+        withResetTo={resetValues.current}
+        withDiscardChanges
+      >
+        <FormRow>
+          <ControlledInputField name="name" />
+        </FormRow>
+        <FormRow>
+          <ControlledSecretConfirmationField name="password" rules={{ required: true }} />
+        </FormRow>
+        <FormRow>
+          <ControlledCheckboxField name="active" />
+        </FormRow>
+        <FormRow>
+          <ControlledInputField name="date" type="date" />
+        </FormRow>
+      </Form>
+    );
+  })
+  .add("Layout", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        name: "",
+        password: "",
+        method: "",
+      }}
+    >
+      <FormRow>
+        <ControlledInputField name="name" />
+        <ControlledSelectField name="method">
+          {["", "post", "get", "put"].map((value) => (
+            <option value={value} key={value}>
+              {value}
+            </option>
+          ))}
+        </ControlledSelectField>
+        <ControlledSecretConfirmationField name="password" />
+      </FormRow>
+    </Form>
+  ))
+  .add("GlobalConfiguration", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        url: "",
+        filter: "",
+        username: "",
+        password: "",
+        roleLevel: "",
+        updateIssues: false,
+        disableRepoConfig: false,
+      }}
+    >
+      {({ watch }) => (
+        <>
+          <FormRow>
+            <ControlledInputField name="url" label="URL" helpText="URL of Jira installation (with context path)." />
+          </FormRow>
+          <FormRow>
+            <ControlledInputField name="filter" label="Project Filter" helpText="Filters for jira project key." />
+          </FormRow>
+          <FormRow>
+            <ControlledCheckboxField
+              name="updateIssues"
+              label="Update Jira Issues"
+              helpText="Enable the automatic update function."
+            />
+          </FormRow>
+          <FormRow hidden={watch("filter")}>
+            <ControlledInputField
+              name="username"
+              label="Username"
+              helpText="Jira username for connection."
+              className="is-half"
+            />
+            <ControlledInputField
+              name="password"
+              label="Password"
+              helpText="Jira password for connection."
+              type="password"
+              className="is-half"
+            />
+          </FormRow>
+          <FormRow hidden={watch("filter")}>
+            <ControlledInputField
+              name="roleLevel"
+              label="Role Visibility"
+              helpText="Defines for which Project Role the comments are visible."
+            />
+          </FormRow>
+          <FormRow>
+            <ControlledCheckboxField
+              name="disableRepoConfig"
+              label="Do not allow repository configuration"
+              helpText="Do not allow repository owners to configure jira instances."
+            />
+          </FormRow>
+        </>
+      )}
+    </Form>
+  ))
+  .add("RepoConfiguration", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        url: "",
+        option: "",
+        anotherOption: "",
+        disableA: false,
+        disableB: false,
+        disableC: true,
+        labels: ["test"],
+        people: [{ displayName: "Trillian", id: 2 }],
+        author: null,
+      }}
+    >
+      <ControlledInputField name="url" />
+      <ControlledInputField name="option" />
+      <ControlledInputField name="anotherOption" />
+      <ControlledCheckboxField name="disableA" />
+      <ControlledCheckboxField name="disableB" />
+      <ControlledCheckboxField name="disableC" />
+      <ControlledChipInputField name="labels" />
+      <ControlledChipInputField
+        name="people"
+        optionFactory={(person) => ({ label: person.displayName, value: person })}
+      >
+        <Combobox
+          options={[
+            { label: "Zenod", value: { id: 1, displayName: "Zenod" } },
+            { label: "Arthur", value: { id: 3, displayName: "Arthur" } },
+            { label: "Cookie Monster", value: { id: 4, displayName: "Cookie Monster" } },
+          ]}
+        />
+      </ControlledChipInputField>
+      <ControlledComboboxField
+        options={["Zenod", "Arthur", "Trillian"].map(defaultOptionFactory)}
+        name="author"
+        nullable
+      />
+    </Form>
+  ))
+  .add("ReadOnly", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        name: "trillian",
+        password: "secret",
+        active: true,
+        labels: ["test", "hero"],
+      }}
+      readOnly
+    >
+      <FormRow>
+        <ControlledInputField name="name" />
+      </FormRow>
+      <FormRow>
+        <ControlledSecretConfirmationField name="password" />
+      </FormRow>
+      <FormRow>
+        <ControlledCheckboxField name="active" />
+      </FormRow>
+      <FormRow>
+        <ControlledChipInputField name="labels" aria-label="Test" placeholder="New label..." />
+      </FormRow>
+    </Form>
+  ))
+  .add("Nested", () => (
+    <Form
+      onSubmit={console.log}
+      translationPath={["sample", "form"]}
+      defaultValues={{
+        webhooks: [
+          {
+            urlPattern: "https://hitchhiker.com",
+            executeOnEveryCommit: false,
+            sendCommitData: false,
+            method: "post",
+            headers: [
+              {
+                key: "test",
+                value: "val",
+                concealed: false,
+              },
+              {
+                key: "secret",
+                value: "password",
+                concealed: true,
+              },
+            ],
+          },
+          {
+            urlPattern: "http://test.com",
+            executeOnEveryCommit: false,
+            sendCommitData: false,
+            method: "get",
+            headers: [
+              {
+                key: "other",
+                value: "thing",
+                concealed: true,
+              },
+              {
+                key: "stuff",
+                value: "haha",
+                concealed: false,
+              },
+            ],
+          },
+        ],
+      }}
+      withResetTo={{
+        webhooks: [
+          {
+            urlPattern: "https://other.com",
+            executeOnEveryCommit: true,
+            sendCommitData: true,
+            method: "get",
+            headers: [
+              {
+                key: "change",
+                value: "new",
+                concealed: true,
+              },
+            ],
+          },
+          {
+            urlPattern: "http://things.com",
+            executeOnEveryCommit: false,
+            sendCommitData: true,
+            method: "put",
+            headers: [
+              {
+                key: "stuff",
+                value: "haha",
+                concealed: false,
+              },
+            ],
+          },
+        ],
+      }}
+    >
+      <ScmFormListContextProvider name="webhooks">
+        <ControlledList withDelete>
+          {({ value: webhook }) => (
+            <>
+              <FormRow>
+                <ControlledSelectField name="method">
+                  {["post", "get", "put"].map((value) => (
+                    <option value={value} key={value}>
+                      {value}
+                    </option>
+                  ))}
+                </ControlledSelectField>
+                <ControlledInputField name="urlPattern" />
+              </FormRow>
+              <FormRow>
+                <ControlledCheckboxField name="executeOnEveryCommit" />
+              </FormRow>
+              <FormRow>
+                <ControlledCheckboxField name="sendCommitData" />
+              </FormRow>
+              <details className="has-background-dark-25 mb-2 p-2">
+                <summary className="is-clickable">Headers</summary>
+                <div>
+                  <ScmFormListContextProvider name="headers">
+                    <ControlledTable withDelete>
+                      <ControlledColumn name="key" />
+                      <ControlledColumn name="value" />
+                      <ControlledColumn name="concealed">{(value) => (value ? <b>Hallo</b> : null)}</ControlledColumn>
+                    </ControlledTable>
+                    <AddListEntryForm defaultValues={{ key: "", value: "", concealed: false }}>
+                      <FormRow>
+                        <ControlledInputField
+                          name="key"
+                          rules={{
+                            validate: (newKey) =>
+                              !(webhook as SimpleWebHookConfiguration).headers.some(({ key }) => newKey === key),
+                            required: true,
+                          }}
+                        />
+                      </FormRow>
+                      <FormRow>
+                        <ControlledInputField name="value" />
+                      </FormRow>
+                      <FormRow>
+                        <ControlledCheckboxField name="concealed" />
+                      </FormRow>
+                    </AddListEntryForm>
+                  </ScmFormListContextProvider>
+                </div>
+              </details>
+            </>
+          )}
+        </ControlledList>
+      </ScmFormListContextProvider>
+    </Form>
+  ))
+  .add("Controlled Chip Input with add", () => {
+    const ref = useRef<HTMLInputElement>(null);
+    return (
+      <Form
+        onSubmit={console.log}
+        translationPath={["sample", "form"]}
+        defaultValues={{
+          branches: ["main", "develop"],
+        }}
+      >
+        <FormRow>
+          <ControlledChipInputField name="branches" ref={ref} />
+        </FormRow>
+        <FormRow>
+          <ChipInput.AddButton inputRef={ref}>Add</ChipInput.AddButton>
+        </FormRow>
+      </Form>
+    );
+  });

package/src/base/forms/Form.tsx

@@ -0,0 +1,215 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2020-present Cloudogu GmbH and Contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import React, { FC, useCallback, useEffect, useState } from "react";
+import { DeepPartial, SubmitHandler, useForm, UseFormReturn } from "react-hook-form";
+import { ErrorNotification } from "../notifications";
+import { Level } from  "../misc";
+import { ScmFormContextProvider } from "./ScmFormContext";
+import { useTranslation } from "react-i18next";
+import { Button } from "../buttons";
+import styled from "styled-components";
+import { setValues } from "./helpers";
+
+type RenderProps<T extends Record<string, unknown>> = Omit<
+  UseFormReturn<T>,
+  "register" | "unregister" | "handleSubmit" | "control"
+>;
+
+const ButtonsContainer = styled.div`
+  display: flex;
+  gap: 0.75rem;
+`;
+
+const SuccessNotification: FC<{ label?: string; hide: () => void }> = ({ label, hide }) => {
+  if (!label) {
+    return null;
+  }
+
+  return (
+    <div className="notification is-success">
+      <button className="delete" onClick={hide} />
+      {label}
+    </div>
+  );
+};
+
+type Props<FormType extends Record<string, unknown>, DefaultValues extends FormType> = {
+  children: ((renderProps: RenderProps<FormType>) => React.ReactNode | React.ReactNode[]) | React.ReactNode;
+  translationPath: [namespace: string, prefix: string];
+  onSubmit: SubmitHandler<FormType>;
+  defaultValues: DefaultValues;
+  readOnly?: boolean;
+  submitButtonTestId?: string;
+  /**
+   * Renders a button which resets the form to its default.
+   * This reflects the default browser behavior for a form *reset*.
+   *
+   * @since 2.43.0
+   */
+  withDiscardChanges?: boolean;
+  /**
+   * Renders a button which acts as if a user manually updated all fields to supplied values.
+   * The default use-case for this is to clear forms and this is also how the button is labelled.
+   * You can also use it to reset the form to an original state, but it is then advised to change the button label
+   * to *Reset to Defaults* by defining the *reset* translation in the form's translation object's root.
+   *
+   * > *Important Note:* This mechanism cannot be used to change the number of items in lists,
+   * > neither on the root level nor nested.
+   * > It is therefore advised not to use this property when lists or nested forms are involved.
+   *
+   * @since 2.43.0
+   */
+  withResetTo?: DefaultValues;
+  /**
+   * Message to display after a successful submit if no translation key is defined.
+   *
+   * If this is not supplied and the root level `submit-success-notification` translation key is not set,
+   * no message is displayed at all.
+   *
+   * @since 2.43.0
+   */
+  successMessageFallback?: string;
+};
+
+/**
+ * @beta
+ * @since 2.41.0
+ */
+function Form<FormType extends Record<string, unknown>, DefaultValues extends FormType = FormType>({
+  children,
+  onSubmit,
+  defaultValues,
+  translationPath,
+  readOnly,
+  withResetTo,
+  withDiscardChanges,
+  successMessageFallback,
+  submitButtonTestId,
+}: Props<FormType, DefaultValues>) {
+  const form = useForm<FormType>({
+    mode: "onChange",
+    defaultValues: defaultValues as DeepPartial<FormType>,
+  });
+  const { formState, handleSubmit, reset, setValue } = form;
+  const [ns, prefix] = translationPath;
+  const { t } = useTranslation(ns, { keyPrefix: prefix });
+  const [defaultTranslate] = useTranslation("commons", { keyPrefix: "form" });
+  const translateWithFallback = useCallback<typeof t>(
+    (key, ...args) => {
+      const translation = t(key, ...(args as any));
+      if (translation === `${prefix}.${key}`) {
+        return "";
+      }
+      return translation;
+    },
+    [prefix, t]
+  );
+  const { isDirty, isValid, isSubmitting, isSubmitSuccessful } = formState;
+  const [error, setError] = useState<Error | null | undefined>();
+  const [showSuccessNotification, setShowSuccessNotification] = useState(false);
+  const submitButtonLabel = t("submit", { defaultValue: defaultTranslate("submit") });
+  const resetButtonLabel = t("reset", { defaultValue: defaultTranslate("reset") });
+  const discardChangesButtonLabel = t("discardChanges", { defaultValue: defaultTranslate("discardChanges") });
+  const successNotification = translateWithFallback("submit-success-notification", {
+    defaultValue: successMessageFallback,
+  });
+  const overwriteValues = useCallback(() => {
+    if (withResetTo) {
+      setValues(withResetTo, setValue);
+    }
+  }, [setValue, withResetTo]);
+
+  // See https://react-hook-form.com/api/useform/reset/
+  useEffect(() => {
+    if (isSubmitSuccessful) {
+      setShowSuccessNotification(true);
+    }
+  }, [isSubmitSuccessful]);
+
+  useEffect(() => reset(defaultValues as never), [defaultValues, reset]);
+
+  useEffect(() => {
+    if (isDirty) {
+      setShowSuccessNotification(false);
+    }
+  }, [isDirty]);
+
+  const submit = useCallback(
+    async (data) => {
+      setError(null);
+      try {
+        return await onSubmit(data);
+      } catch (e) {
+        if (e instanceof Error) {
+          setError(e);
+        } else {
+          throw e;
+        }
+      }
+    },
+    [onSubmit]
+  );
+
+  return (
+    <ScmFormContextProvider {...form} readOnly={isSubmitting || readOnly} t={translateWithFallback} formId={prefix}>
+      <form onSubmit={handleSubmit(submit)} onReset={() => reset()} id={prefix} noValidate></form>
+      {showSuccessNotification ? (
+        <SuccessNotification label={successNotification} hide={() => setShowSuccessNotification(false)} />
+      ) : null}
+      {typeof children === "function" ? children(form) : children}
+      {error ? <ErrorNotification error={error} /> : null}
+      {!readOnly ? (
+        <Level
+          right={
+            <ButtonsContainer>
+              <Button
+                type="submit"
+                variant="primary"
+                testId={submitButtonTestId ?? "submit-button"}
+                disabled={!isDirty || !isValid}
+                isLoading={isSubmitting}
+                form={prefix}
+              >
+                {submitButtonLabel}
+              </Button>
+              {withDiscardChanges ? (
+                <Button type="reset" form={prefix} testId={`${prefix}-discard-changes-button`}>
+                  {discardChangesButtonLabel}
+                </Button>
+              ) : null}
+              {withResetTo ? (
+                <Button form={prefix} onClick={overwriteValues} testId={`${prefix}-reset-button`}>
+                  {resetButtonLabel}
+                </Button>
+              ) : null}
+            </ButtonsContainer>
+          }
+        />
+      ) : null}
+    </ScmFormContextProvider>
+  );
+}
+
+export default Form;