@keycloakify/keycloak-account-ui 25.0.1-rc.0

package/src/ui-shared/alerts/Alerts.tsx

@@ -0,0 +1,86 @@
+import {
+  Alert,
+  AlertActionCloseButton,
+  AlertGroup,
+  AlertVariant,
+} from "@patternfly/react-core";
+import { createContext, PropsWithChildren, useContext, useState } from "react";
+
+export type AddAlertFunction = (
+  message: string,
+  variant?: AlertVariant,
+  description?: string,
+) => void;
+
+export type AddErrorFunction = (message: string) => void;
+
+export type AlertProps = {
+  addAlert: AddAlertFunction;
+  addError: AddErrorFunction;
+};
+
+export const AlertContext = createContext<AlertProps | undefined>(undefined);
+
+export const useAlerts = () => useContext(AlertContext)!;
+
+export type AlertType = {
+  id: number;
+  message: string;
+  variant: AlertVariant;
+  description?: string;
+};
+
+export const AlertProvider = ({ children }: PropsWithChildren) => {
+  const [alerts, setAlerts] = useState<AlertType[]>([]);
+
+  const hideAlert = (id: number) => {
+    setAlerts((alerts) => alerts.filter((alert) => alert.id !== id));
+  };
+
+  const addAlert = (
+    message: string,
+    variant: AlertVariant = AlertVariant.success,
+    description?: string,
+  ) => {
+    setAlerts([
+      {
+        id: Math.random() * 100,
+        message,
+        variant,
+        description,
+      },
+      ...alerts,
+    ]);
+  };
+
+  const addError = (message: string) => {
+    addAlert(message, AlertVariant.danger);
+  };
+
+  return (
+    <AlertContext.Provider value={{ addAlert, addError }}>
+      <AlertGroup isToast data-testid="alerts">
+        {alerts.map(({ id, variant, message, description }) => (
+          <Alert
+            key={id}
+            isLiveRegion
+            variant={AlertVariant[variant]}
+            variantLabel=""
+            title={message}
+            actionClose={
+              <AlertActionCloseButton
+                title={message}
+                onClose={() => hideAlert(id)}
+              />
+            }
+            timeout
+            onTimeout={() => hideAlert(id)}
+          >
+            {description && <p>{description}</p>}
+          </Alert>
+        ))}
+      </AlertGroup>
+      {children}
+    </AlertContext.Provider>
+  );
+};

package/src/ui-shared/buttons/FormSubmitButton.tsx

@@ -0,0 +1,47 @@
+import { Button, ButtonProps } from "@patternfly/react-core";
+import { PropsWithChildren } from "react";
+import { FieldValues, FormState } from "react-hook-form";
+
+export type FormSubmitButtonProps = Omit<ButtonProps, "isDisabled"> & {
+  formState: FormState<FieldValues>;
+  allowNonDirty?: boolean;
+  allowInvalid?: boolean;
+  isDisabled?: boolean;
+};
+
+const isSubmittable = (
+  formState: FormState<FieldValues>,
+  allowNonDirty: boolean,
+  allowInvalid: boolean,
+) => {
+  return (
+    (formState.isValid || allowInvalid) &&
+    (formState.isDirty || allowNonDirty) &&
+    !formState.isLoading &&
+    !formState.isValidating &&
+    !formState.isSubmitting
+  );
+};
+
+export const FormSubmitButton = ({
+  formState,
+  isDisabled = false,
+  allowInvalid = false,
+  allowNonDirty = false,
+  children,
+  ...rest
+}: PropsWithChildren<FormSubmitButtonProps>) => {
+  return (
+    <Button
+      variant="primary"
+      isDisabled={
+        (formState && !isSubmittable(formState, allowNonDirty, allowInvalid)) ||
+        isDisabled
+      }
+      {...rest}
+      type="submit"
+    >
+      {children}
+    </Button>
+  );
+};

package/src/ui-shared/context/ErrorPage.tsx

@@ -0,0 +1,60 @@
+import {
+  Button,
+  Modal,
+  ModalVariant,
+  Page,
+  Text,
+  TextContent,
+  TextVariants,
+} from "@patternfly/react-core";
+import { useTranslation } from "react-i18next";
+
+type ErrorPageProps = {
+  error?: unknown;
+};
+
+export const ErrorPage = (props: ErrorPageProps) => {
+  const { t } = useTranslation();
+  const error = props.error;
+  const errorMessage = getErrorMessage(error);
+
+  function onRetry() {
+    location.href = location.origin + location.pathname;
+  }
+
+  return (
+    <Page>
+      <Modal
+        variant={ModalVariant.small}
+        title={t("somethingWentWrong")}
+        titleIconVariant="danger"
+        showClose={false}
+        isOpen
+        actions={[
+          <Button key="tryAgain" variant="primary" onClick={onRetry}>
+            {t("tryAgain")}
+          </Button>,
+        ]}
+      >
+        <TextContent>
+          <Text>{t("somethingWentWrongDescription")}</Text>
+          {errorMessage && (
+            <Text component={TextVariants.small}>{errorMessage}</Text>
+          )}
+        </TextContent>
+      </Modal>
+    </Page>
+  );
+};
+
+function getErrorMessage(error: unknown): string | null {
+  if (typeof error === "string") {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return null;
+}

package/src/ui-shared/context/HelpContext.tsx

@@ -0,0 +1,30 @@
+import { PropsWithChildren } from "react";
+import { createNamedContext } from "@keycloakify/keycloak-account-ui/ui-shared/utils/createNamedContext";
+import { useRequiredContext } from "@keycloakify/keycloak-account-ui/ui-shared/utils/useRequiredContext";
+import { useStoredState } from "@keycloakify/keycloak-account-ui/ui-shared/utils/useStoredState";
+
+type HelpContextProps = {
+  enabled: boolean;
+  toggleHelp: () => void;
+};
+
+export const HelpContext = createNamedContext<HelpContextProps | undefined>(
+  "HelpContext",
+  undefined,
+);
+
+export const useHelp = () => useRequiredContext(HelpContext);
+
+export const Help = ({ children }: PropsWithChildren) => {
+  const [enabled, setHelp] = useStoredState(localStorage, "helpEnabled", true);
+
+  function toggleHelp() {
+    setHelp(!enabled);
+  }
+
+  return (
+    <HelpContext.Provider value={{ enabled, toggleHelp }}>
+      {children}
+    </HelpContext.Provider>
+  );
+};

package/src/ui-shared/context/KeycloakContext.tsx

@@ -0,0 +1,97 @@
+import { Spinner } from "@patternfly/react-core";
+import Keycloak from "keycloak-js";
+import {
+  PropsWithChildren,
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { AlertProvider } from "@keycloakify/keycloak-account-ui/ui-shared/alerts/Alerts";
+import { ErrorPage } from "@keycloakify/keycloak-account-ui/ui-shared/context/ErrorPage";
+import { Help } from "@keycloakify/keycloak-account-ui/ui-shared/context/HelpContext";
+import { BaseEnvironment } from "@keycloakify/keycloak-account-ui/ui-shared/context/environment";
+
+export type KeycloakContext<T extends BaseEnvironment = BaseEnvironment> =
+  KeycloakContextProps<T> & {
+    keycloak: Keycloak;
+  };
+
+const createKeycloakEnvContext = <T extends BaseEnvironment>() =>
+  createContext<KeycloakContext<T> | undefined>(undefined);
+
+let KeycloakEnvContext: any;
+
+export const useEnvironment = <
+  T extends BaseEnvironment = BaseEnvironment,
+>() => {
+  const context = useContext<KeycloakContext<T>>(KeycloakEnvContext);
+  if (!context)
+    throw Error(
+      "no environment provider in the hierarchy make sure to add the provider",
+    );
+  return context;
+};
+
+interface KeycloakContextProps<T extends BaseEnvironment> {
+  environment: T;
+}
+
+export const KeycloakProvider = <T extends BaseEnvironment>({
+  environment,
+  children,
+}: PropsWithChildren<KeycloakContextProps<T>>) => {
+  KeycloakEnvContext = createKeycloakEnvContext<T>();
+  const calledOnce = useRef(false);
+  const [init, setInit] = useState(false);
+  const [error, setError] = useState<unknown>();
+  const keycloak = useMemo(() => {
+    const keycloak = new Keycloak({
+      url: environment.serverBaseUrl,
+      realm: environment.realm,
+      clientId: environment.clientId,
+    });
+
+    keycloak.onAuthLogout = () => keycloak.login();
+
+    return keycloak;
+  }, [environment]);
+
+  useEffect(() => {
+    // only needed in dev mode
+    if (calledOnce.current) {
+      return;
+    }
+
+    const init = () =>
+      keycloak.init({
+        onLoad: "check-sso",
+        pkceMethod: "S256",
+        responseMode: "query",
+      });
+
+    init()
+      .then(() => setInit(true))
+      .catch((error) => setError(error));
+
+    calledOnce.current = true;
+  }, [keycloak]);
+
+  if (error) {
+    return <ErrorPage error={error} />;
+  }
+
+  if (!init) {
+    return <Spinner />;
+  }
+
+  return (
+    <KeycloakEnvContext.Provider value={{ environment, keycloak }}>
+      <AlertProvider>
+        <Help>{children}</Help>
+      </AlertProvider>
+    </KeycloakEnvContext.Provider>
+  );
+};

package/src/ui-shared/context/environment.ts

@@ -0,0 +1,50 @@
+/** The base environment variables that are shared between the Admin and Account Consoles. */
+export type BaseEnvironment = {
+  /**
+   * The URL to the root of the Keycloak server, including the path if present, this is **NOT** always equivalent to the URL of the Admin Console.
+   * For example, the Keycloak server could be hosted on `auth.example.com` and Admin Console may be hosted on `admin.example.com/some/path`.
+   *
+   * Note that this URL is normalized not to include a trailing slash, so take this into account when constructing URLs.
+   *
+   * @see {@link https://www.keycloak.org/server/hostname#_administration_console}
+   */
+  serverBaseUrl: string;
+  /** The identifier of the realm used to authenticate the user. */
+  realm: string;
+  /** The identifier of the client used to authenticate the user. */
+  clientId: string;
+  /** The base URL of the resources. */
+  resourceUrl: string;
+  /** The source URL for the the logo image. */
+  logo: string;
+  /** The URL to be followed when the logo is clicked. */
+  logoUrl: string;
+};
+
+/**
+ *  Extracts the environment variables from the document, these variables are injected by Keycloak as a script tag, the contents of which can be parsed as JSON. For example:
+ *
+ *```html
+ * <script id="environment" type="application/json">
+ *   {
+ *     "realm": "master",
+ *     "clientId": "security-admin-console",
+ *     "etc": "..."
+ *   }
+ * </script>
+ * ```
+ */
+export function getInjectedEnvironment<T>(): T {
+  const element = document.getElementById("environment");
+  const contents = element?.textContent;
+
+  if (typeof contents !== "string") {
+    throw new Error("Environment variables not found in the document.");
+  }
+
+  try {
+    return JSON.parse(contents);
+  } catch (error) {
+    throw new Error("Unable to parse environment variables as JSON.");
+  }
+}

package/src/ui-shared/continue-cancel/ContinueCancelModal.tsx

@@ -0,0 +1,75 @@
+import { ReactNode, useState } from "react";
+import { Button, ButtonProps, Modal, ModalProps } from "@patternfly/react-core";
+
+export type ContinueCancelModalProps = Omit<ModalProps, "ref" | "children"> & {
+  modalTitle: string;
+  continueLabel: string;
+  cancelLabel: string;
+  buttonTitle: string | ReactNode;
+  buttonVariant?: ButtonProps["variant"];
+  buttonTestRole?: string;
+  isDisabled?: boolean;
+  onContinue: () => void;
+  component?: React.ElementType<any> | React.ComponentType<any>;
+  children?: ReactNode;
+};
+
+export const ContinueCancelModal = ({
+  modalTitle,
+  continueLabel,
+  cancelLabel,
+  buttonTitle,
+  isDisabled,
+  buttonVariant,
+  buttonTestRole,
+  onContinue,
+  component = Button,
+  children,
+  ...rest
+}: ContinueCancelModalProps) => {
+  const [open, setOpen] = useState(false);
+  const Component = component;
+
+  return (
+    <>
+      <Component
+        variant={buttonVariant}
+        onClick={() => setOpen(true)}
+        isDisabled={isDisabled}
+        data-testrole={buttonTestRole}
+      >
+        {buttonTitle}
+      </Component>
+      <Modal
+        variant="small"
+        {...rest}
+        title={modalTitle}
+        isOpen={open}
+        onClose={() => setOpen(false)}
+        actions={[
+          <Button
+            id="modal-confirm"
+            key="confirm"
+            variant="primary"
+            onClick={() => {
+              setOpen(false);
+              onContinue();
+            }}
+          >
+            {continueLabel}
+          </Button>,
+          <Button
+            id="modal-cancel"
+            key="cancel"
+            variant="secondary"
+            onClick={() => setOpen(false)}
+          >
+            {cancelLabel}
+          </Button>,
+        ]}
+      >
+        {children}
+      </Modal>
+    </>
+  );
+};

package/src/ui-shared/controls/FormErrorText.tsx

@@ -0,0 +1,23 @@
+import {
+  FormHelperText,
+  FormHelperTextProps,
+  HelperText,
+  HelperTextItem,
+} from "@patternfly/react-core";
+import { ExclamationCircleIcon } from "@patternfly/react-icons";
+
+export type FormErrorTextProps = FormHelperTextProps & {
+  message: string;
+};
+
+export const FormErrorText = ({ message, ...props }: FormErrorTextProps) => {
+  return (
+    <FormHelperText {...props}>
+      <HelperText>
+        <HelperTextItem icon={<ExclamationCircleIcon />} variant="error">
+          {message}
+        </HelperTextItem>
+      </HelperText>
+    </FormHelperText>
+  );
+};

package/src/ui-shared/controls/FormLabel.tsx

@@ -0,0 +1,40 @@
+import { FormGroup, FormGroupProps } from "@patternfly/react-core";
+import { PropsWithChildren, ReactNode } from "react";
+import { FieldError, FieldValues, Merge } from "react-hook-form";
+import { FormErrorText } from "@keycloakify/keycloak-account-ui/ui-shared/controls/FormErrorText";
+import { HelpItem } from "@keycloakify/keycloak-account-ui/ui-shared/controls/HelpItem";
+
+export type FieldProps<T extends FieldValues = FieldValues> = {
+  label?: string;
+  name: string;
+  labelIcon?: string | ReactNode;
+  error?: FieldError | Merge<FieldError, T>;
+  isRequired: boolean;
+};
+
+type FormLabelProps = FieldProps & Omit<FormGroupProps, "label" | "labelIcon">;
+
+export const FormLabel = ({
+  name,
+  label,
+  labelIcon,
+  error,
+  children,
+  ...rest
+}: PropsWithChildren<FormLabelProps>) => (
+  <FormGroup
+    label={label || name}
+    fieldId={name}
+    labelIcon={
+      labelIcon ? (
+        <HelpItem helpText={labelIcon} fieldLabelId={name} />
+      ) : undefined
+    }
+    {...rest}
+  >
+    {children}
+    {error && (
+      <FormErrorText data-testid={`${name}-helper`} message={error.message} />
+    )}
+  </FormGroup>
+);

package/src/ui-shared/controls/HelpItem.tsx

@@ -0,0 +1,43 @@
+import { Icon, Popover } from "@patternfly/react-core";
+import { HelpIcon } from "@patternfly/react-icons";
+import { ReactNode } from "react";
+import { useHelp } from "@keycloakify/keycloak-account-ui/ui-shared/context/HelpContext";
+
+type HelpItemProps = {
+  helpText: string | ReactNode;
+  fieldLabelId: string;
+  noVerticalAlign?: boolean;
+  unWrap?: boolean;
+};
+
+export const HelpItem = ({
+  helpText,
+  fieldLabelId,
+  noVerticalAlign = true,
+  unWrap = false,
+}: HelpItemProps) => {
+  const { enabled } = useHelp();
+  return enabled ? (
+    <Popover bodyContent={helpText}>
+      <>
+        {!unWrap && (
+          <button
+            data-testid={`help-label-${fieldLabelId}`}
+            aria-label={fieldLabelId}
+            onClick={(e) => e.preventDefault()}
+            className="pf-v5-c-form__group-label-help"
+          >
+            <Icon isInline={noVerticalAlign}>
+              <HelpIcon />
+            </Icon>
+          </button>
+        )}
+        {unWrap && (
+          <Icon isInline={noVerticalAlign}>
+            <HelpIcon />
+          </Icon>
+        )}
+      </>
+    </Popover>
+  ) : null;
+};

package/src/ui-shared/controls/NumberControl.tsx

@@ -0,0 +1,89 @@
+import {
+  NumberInput,
+  NumberInputProps,
+  ValidatedOptions,
+} from "@patternfly/react-core";
+import {
+  Controller,
+  ControllerProps,
+  FieldPath,
+  FieldValues,
+  UseControllerProps,
+  useFormContext,
+} from "react-hook-form";
+import { FormLabel } from "@keycloakify/keycloak-account-ui/ui-shared/controls/FormLabel";
+
+export type NumberControlOption = {
+  key: string;
+  value: string;
+};
+
+export type NumberControlProps<
+  T extends FieldValues,
+  P extends FieldPath<T> = FieldPath<T>,
+> = Omit<NumberInputProps, "name" | "isRequired" | "required"> &
+  UseControllerProps<T, P> & {
+    name: string;
+    label?: string;
+    labelIcon?: string;
+    controller: Omit<ControllerProps, "name" | "render">;
+  };
+
+export const NumberControl = <
+  T extends FieldValues,
+  P extends FieldPath<T> = FieldPath<T>,
+>({
+  name,
+  label,
+  controller,
+  labelIcon,
+  ...rest
+}: NumberControlProps<T, P>) => {
+  const {
+    control,
+    formState: { errors },
+  } = useFormContext();
+  return (
+    <FormLabel
+      name={name}
+      label={label}
+      isRequired={controller.rules?.required === true}
+      error={errors[name]}
+      labelIcon={labelIcon}
+    >
+      <Controller
+        {...controller}
+        name={name}
+        control={control}
+        render={({ field }) => {
+          const required = !!controller.rules?.required;
+          const min = controller.rules?.min;
+          const value =
+            field.value === 0 ? controller.defaultValue : field.value;
+          const setValue = (newValue: number) =>
+            field.onChange(min ? Math.max(newValue, Number(min)) : newValue);
+
+          return (
+            <NumberInput
+              {...rest}
+              id={name}
+              value={value}
+              validated={
+                errors[name] ? ValidatedOptions.error : ValidatedOptions.default
+              }
+              required={required}
+              min={Number(min)}
+              max={Number(controller.rules?.max)}
+              onPlus={() => setValue(value + 1)}
+              onMinus={() => setValue(value - 1)}
+              onChange={(event) => {
+                const newValue = Number(event.currentTarget.value);
+                setValue(!isNaN(newValue) ? newValue : controller.defaultValue);
+              }}
+            />
+          );
+        }}
+      />
+    </FormLabel>
+  );
+};