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

package/src/base/buttons/Button.tsx

@@ -0,0 +1,143 @@
+/*
+ * 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, { AnchorHTMLAttributes, ButtonHTMLAttributes } from "react";
+import { Link as ReactRouterLink, LinkProps as ReactRouterLinkProps } from "react-router-dom";
+import classNames from "classnames";
+import { createAttributesForTesting } from "../helpers";
+
+/**
+ * @beta
+ * @since 2.41.0
+ */
+export const ButtonVariants = {
+  PRIMARY: "primary",
+  SECONDARY: "secondary",
+  TERTIARY: "tertiary",
+  SIGNAL: "signal",
+} as const;
+
+export const ButtonVariantList = Object.values(ButtonVariants);
+
+type ButtonVariant = typeof ButtonVariants[keyof typeof ButtonVariants];
+
+const createButtonClasses = (variant?: ButtonVariant, isLoading?: boolean) =>
+  classNames("button", {
+    "is-primary": variant === "primary",
+    "is-primary is-outlined": variant === "secondary",
+    "is-primary is-inverted": variant === "tertiary",
+    "is-warning": variant === "signal",
+    "is-loading": isLoading,
+  });
+
+type BaseButtonProps = {
+  variant?: ButtonVariant;
+  isLoading?: boolean;
+  testId?: string;
+};
+
+type ButtonProps = BaseButtonProps & ButtonHTMLAttributes<HTMLButtonElement>;
+
+/**
+ * Styled html button.
+ *
+ * A button has to declare an `aria-label` if it exclusively contains an {@link Icon} as its children.
+ *
+ * @beta
+ * @since 2.41.0
+ */
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant, isLoading, testId, type, children, ...props }, ref) => (
+    <button
+      type={type ?? "button"}
+      {...props}
+      className={classNames(createButtonClasses(variant, isLoading), className)}
+      ref={ref}
+      {...createAttributesForTesting(testId)}
+    >
+      {children}
+    </button>
+  )
+);
+
+type LinkButtonProps = BaseButtonProps & ReactRouterLinkProps;
+
+/**
+ * Styled react router link.
+ *
+ * A button has to declare an `aria-label` if it exclusively contains an {@link Icon} as its children.
+ *
+ * @beta
+ * @since 2.41.0
+ */
+export const LinkButton = React.forwardRef<HTMLAnchorElement, LinkButtonProps>(
+  ({ className, variant, isLoading, testId, children, ...props }, ref) => (
+    <ReactRouterLink
+      {...props}
+      className={classNames(createButtonClasses(variant, isLoading), className)}
+      ref={ref}
+      {...createAttributesForTesting(testId)}
+    >
+      {children}
+    </ReactRouterLink>
+  )
+);
+
+/**
+ * External links open in a new browser tab with rel flags "noopener" and "noreferrer" set by default.
+ *
+ * @beta
+ * @since 2.44.0
+ */
+export const ExternalLink = React.forwardRef<HTMLAnchorElement, AnchorHTMLAttributes<HTMLAnchorElement>>(
+  ({ children, ...props }, ref) => (
+    <a target="_blank" rel="noreferrer noopener" {...props} ref={ref}>
+      {children}
+    </a>
+  )
+);
+
+type ExternalLinkButtonProps = BaseButtonProps & AnchorHTMLAttributes<HTMLAnchorElement>;
+
+/**
+ * Styled {@link ExternalLink}.
+ *
+ * A button has to declare an `aria-label` if it exclusively contains an {@link Icon} as its children.
+ *
+ * @beta
+ * @since 2.41.0
+ * @see ExternalLink
+ */
+export const ExternalLinkButton = React.forwardRef<HTMLAnchorElement, ExternalLinkButtonProps>(
+  ({ className, variant, isLoading, testId, children, ...props }, ref) => (
+    <ExternalLink
+      {...props}
+      className={classNames(createButtonClasses(variant, isLoading), className)}
+      ref={ref}
+      {...createAttributesForTesting(testId)}
+    >
+      {children}
+    </ExternalLink>
+  )
+);

package/src/base/buttons/Icon.tsx

@@ -0,0 +1,58 @@
+/*
+ * 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 from "react";
+import classNames from "classnames";
+
+type Props = React.HTMLProps<HTMLElement> & {
+  children?: string;
+};
+
+/**
+ * Icons are hidden to assistive technologies by default.
+ *
+ * If your icon does convey a state, unset `aria-hidden` and set an appropriate `aria-label`.
+ *
+ * The children have to be a single text node containing a valid fontawesome icon name.
+ *
+ * @beta
+ * @since 2.44.0
+ * @see https://bulma.io/documentation/elements/icon/
+ * @see https://fontawesome.com/search?o=r&m=free
+ */
+const Icon = React.forwardRef<HTMLElement, Props>(({ children, className, ...props }, ref) => {
+  return (
+    <span className={classNames(className, "icon")} aria-hidden="true" {...props} ref={ref}>
+      <i
+        className={classNames(`fas fa-fw fa-${children}`, {
+          "fa-xs": className?.includes("is-small"),
+          "fa-lg": className?.includes("is-medium"),
+          "fa-2x": className?.includes("is-large"),
+        })}
+      />
+    </span>
+  );
+});
+
+export default Icon;

package/src/base/buttons/a11y.test.ts

@@ -0,0 +1,34 @@
+/*
+ * 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 initStoryshots from "@storybook/addon-storyshots";
+import { axeTest } from "@storybook/addon-storyshots-puppeteer";
+import path from "path";
+
+initStoryshots({
+  suite: "A11y checks",
+  test: axeTest({
+    storybookUrl: `file://${path.resolve(__dirname, "../storybook-static")}`,
+  }),
+  storyNameRegex: /High-Contrast States/,
+});

package/src/base/buttons/docs/introduction.stories.mdx

@@ -0,0 +1,64 @@
+import { Meta } from "@storybook/addon-docs";
+import { Button } from "../";
+
+<Meta title="Introduction"/>
+
+# Buttons
+
+The `@scm-manager/ui-core` library provides [atoms](https://atomicdesign.bradfrost.com/chapter-2/#atoms) implemented
+as minimal wrappers around native html elements styled to match the general SCM-Manager aesthetic.
+
+## Components
+
+There are three actionable components available. Styling is consistent amongst them and all have the required `variant` property.
+
+1. [Button](?path=/story/components--button)
+2. [Link Button](?path=/story/components--link-button)
+3. [External Link Button](?path=/story/components--external-link-button)
+
+## Usage
+
+Actionable components serve a dedicated purpose. It is therefore important to know when and how to use them.
+
+### Variants
+
+There are four variants available to each of the three button types, varying in importance.
+
+<table>
+  <thead>
+  <tr>
+    <th>Emphasis</th>
+    <th>Button Variant</th>
+    <th>Usage Examples</th>
+  </tr>
+  </thead>
+  <tbody>
+  <tr>
+    <td>Very High</td>
+    <td><Button variant="signal">Signal</Button></td>
+    <td>Destructive actions</td>
+  </tr>
+  <tr>
+    <td>High</td>
+    <td><Button variant="primary">Primary</Button></td>
+    <td>Form submit</td>
+  </tr>
+  <tr>
+    <td>Normal</td>
+    <td><Button variant="secondary">Secondary</Button></td>
+    <td>Cancel action in dialog</td>
+  </tr>
+  <tr>
+    <td>Low</td>
+    <td><Button variant="tertiary">Tertiary</Button></td>
+    <td>Circumstantially relevant action on page with many actionable elements</td>
+  </tr>
+  </tbody>
+</table>
+
+## Content
+
+Buttons exclusively contain text and no icons. Icons tend to be ambiguous and not always applicable which leads to inconsistent
+and cluttered layouts.
+
+Button text should be short, concise and describe the action performed.

package/src/base/buttons/docs/usage.stories.mdx

@@ -0,0 +1,22 @@
+import { Meta, Story } from "@storybook/addon-docs";
+import { Button } from "../";
+
+<Meta title="Usage" parameters={{
+  storyshots: { disable: true }
+}} />
+
+In confirmation dialogs, there are two actions.<br/>
+One to cancel the current process and one to confirm it.<br/>
+Aborting is always the secondary action, confirmation always the primary.
+Focus is always on the cancelling action.
+
+<Story name="Confirmation Dialog">
+  <div>
+    <h4>Delete User</h4>
+    <p>Do you really want to delete this user ?</p>
+    <div>
+      <Button variant="secondary">Cancel</Button>
+      <Button variant="primary">Delete</Button>
+    </div>
+  </div>
+</Story>

package/src/base/buttons/image-snapshot.test.ts

@@ -0,0 +1,33 @@
+/*
+ * 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 path from "path";
+import initStoryshots from "@storybook/addon-storyshots";
+import { imageSnapshot } from "@storybook/addon-storyshots-puppeteer";
+
+initStoryshots({
+  suite: "Image snapshots",
+  test: imageSnapshot({
+    storybookUrl: `file://${path.resolve(__dirname, "../storybook-static")}`,
+  })
+});

package/src/base/buttons/index.ts

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+export { Button, LinkButton, ExternalLinkButton, ExternalLink, ButtonVariants } from "./Button";
+export { default as Icon } from "./Icon";

package/src/base/forms/AddListEntryForm.tsx

@@ -0,0 +1,127 @@
+/*
+ * 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, { useCallback, useEffect } from "react";
+import { ScmFormPathContextProvider, useScmFormPathContext } from "./FormPathContext";
+import { ScmFormContextProvider, useScmFormContext } from "./ScmFormContext";
+import { DeepPartial, UseFieldArrayReturn, useForm, UseFormReturn } from "react-hook-form";
+import { Button } from "../buttons";
+import { prefixWithoutIndices } from "./helpers";
+import { useScmFormListContext } from "./ScmFormListContext";
+import { useTranslation } from "react-i18next";
+import styled from "styled-components";
+
+const StyledHr = styled.hr`
+  &:last-child {
+    display: none;
+  }
+`;
+
+type RenderProps<T extends Record<string, unknown>> = Omit<
+  UseFormReturn<T>,
+  "register" | "unregister" | "handleSubmit" | "control"
+>;
+
+type Props<FormType extends Record<string, unknown>, DefaultValues extends FormType> = {
+  children: ((renderProps: RenderProps<FormType>) => React.ReactNode | React.ReactNode[]) | React.ReactNode;
+  defaultValues: DefaultValues;
+  submit?: (data: FormType, append: UseFieldArrayReturn["append"]) => unknown;
+  /**
+   * @default true
+   */
+  disableSubmitWhenDirty?: boolean;
+};
+
+/**
+ * @beta
+ * @since 2.43.0
+ */
+function AddListEntryForm<FormType extends Record<string, unknown>, DefaultValues extends FormType>({
+  children,
+  defaultValues,
+  submit,
+  disableSubmitWhenDirty = true,
+}: Props<FormType, DefaultValues>) {
+  const [defaultTranslate] = useTranslation("commons", { keyPrefix: "form" });
+  const { readOnly, t } = useScmFormContext();
+  const nameWithPrefix = useScmFormPathContext();
+  const prefixedNameWithoutIndices = prefixWithoutIndices(nameWithPrefix);
+  const { append, isNested } = useScmFormListContext();
+  const form = useForm<FormType, DefaultValues>({
+    mode: "onChange",
+    defaultValues: defaultValues as DeepPartial<FormType>,
+  });
+
+  const {
+    reset,
+    formState: { isSubmitSuccessful, isDirty, isValid },
+  } = form;
+
+  const translateWithExtraPrefix = useCallback<typeof t>(
+    (key, ...args) => t(`${prefixedNameWithoutIndices}.${key}`, ...(args as any)),
+    [prefixedNameWithoutIndices, t]
+  );
+
+  const onSubmit = useCallback((data) => (submit ? submit(data, append) : append(data)), [append, submit]);
+
+  const submitButtonLabel = translateWithExtraPrefix("add", {
+    defaultValue: defaultTranslate("list.add.label", { entity: translateWithExtraPrefix("entity") }),
+  });
+  const titleLabel = translateWithExtraPrefix("title", {
+    defaultValue: defaultTranslate("list.title.label", { entity: translateWithExtraPrefix("entity") }),
+  });
+
+  useEffect(() => {
+    if (isSubmitSuccessful) {
+      reset(defaultValues);
+    }
+  }, [defaultValues, isSubmitSuccessful, reset]);
+
+  if (readOnly) {
+    return null;
+  }
+
+  return (
+    <ScmFormContextProvider {...form} t={translateWithExtraPrefix} formId={nameWithPrefix}>
+      <ScmFormPathContextProvider path="">
+        <h3 className="subtitle is-5">{titleLabel}</h3>
+        <form id={nameWithPrefix} onSubmit={form.handleSubmit(onSubmit)} noValidate></form>
+        {typeof children === "function" ? children(form) : children}
+        <div className="level-left">
+          <Button
+            form={nameWithPrefix}
+            type="submit"
+            variant={isNested ? undefined : "secondary"}
+            disabled={(disableSubmitWhenDirty && !isDirty) || !isValid}
+          >
+            {submitButtonLabel}
+          </Button>
+        </div>
+        <StyledHr />
+      </ScmFormPathContextProvider>
+    </ScmFormContextProvider>
+  );
+}
+
+export default AddListEntryForm;

package/src/base/forms/ConfigurationForm.tsx

@@ -0,0 +1,59 @@
+/*
+ * 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 { useConfigLink } from "@scm-manager/ui-api";
+import { Loading } from "../misc";
+import React, { ComponentProps } from "react";
+import { HalRepresentation } from "@scm-manager/ui-types";
+import Form from "./Form";
+import { useTranslation } from "react-i18next";
+
+type Props<T extends HalRepresentation> =
+// eslint-disable-next-line prettier/prettier
+  Omit<ComponentProps<typeof Form<T>>, "onSubmit" | "defaultValues" | "readOnly" | "successMessageFallback">
+  & {
+  link: string;
+};
+
+/**
+ * @beta
+ * @since 2.41.0
+ */
+export function ConfigurationForm<T extends HalRepresentation>({ link, children, ...formProps }: Props<T>) {
+  const { initialConfiguration, isReadOnly, update, isLoading } = useConfigLink<T>(link);
+  const [t] = useTranslation("commons", { keyPrefix: "form" });
+
+  if (isLoading || !initialConfiguration) {
+    return <Loading />;
+  }
+
+  return (
+    <Form onSubmit={update} defaultValues={initialConfiguration} readOnly={isReadOnly}
+          successMessageFallback={t("submit-success-notification")} {...formProps}>
+      {children}
+    </Form>
+  );
+}
+
+export default ConfigurationForm;