@scm-manager/ui-core 3.7.5 → 3.8.0

package/.turbo/turbo-typecheck.log

@@ -1,2 +1,2 @@
-@scm-manager/ui-core:typecheck: cache hit, replaying output 5c54d242e7b49eb9
+@scm-manager/ui-core:typecheck: cache hit, replaying output 0276ad30237bf6ba
 @scm-manager/ui-core:typecheck: $ tsc

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scm-manager/ui-core",
-  "version": "3.7.5",
+  "version": "3.8.0",
   "main": "./src/index.ts",
   "license": "AGPL-3.0-only",
   "scripts": {
@@ -20,7 +20,7 @@
     "styled-components": "5"
   },
   "dependencies": {
-    "@scm-manager/ui-api": "3.7.5",
+    "@scm-manager/ui-api": "3.8.0",
     "@radix-ui/react-radio-group": "^1.1.3",
     "@radix-ui/react-slot": "^1.0.1",
     "@radix-ui/react-visually-hidden": "^1.0.3",
@@ -37,7 +37,7 @@
     "@scm-manager/eslint-config": "^2.17.0",
     "@scm-manager/tsconfig": "^2.12.0",
     "@scm-manager/babel-preset": "^2.13.1",
-    "@scm-manager/ui-types": "3.7.5",
+    "@scm-manager/ui-types": "3.8.0",
     "@types/mousetrap": "1.6.5",
     "@testing-library/react-hooks": "8.0.1",
     "@testing-library/react": "12.1.5",

package/src/base/buttons/Button.test.stories.mdx

@@ -1,74 +1,87 @@
 import { Meta, Story } from "@storybook/addon-docs";
 import { Button, ButtonVariantList } from "./Button";
 
-<Meta title="Tests"/>
+<Meta title="Buttons" />
 
-<Story name="Light States" parameters={{
-  pseudo: {
-    hover: ButtonVariantList.map(variant => `#${variant}-Hover`),
-    focus: ButtonVariantList.map(variant => `#${variant}-Focus`),
-    active: ButtonVariantList.map(variant => `#${variant}-Active`),
-  },
-  themes: {
-    default: 'light',
-  },
-}}>
-  <table>
-    <tr>
-      <th>STATE</th>
-      {ButtonVariantList.map(variant => <th>{variant.toUpperCase()}</th>)}
-    </tr>
-    {["Normal", "Hover", "Active", "Focus", "Disabled", "Loading"].map(state => <tr>
-      <td>{state}</td>
-      {ButtonVariantList.map(variant => <td><Button id={`${variant}-${state}`} disabled={state === "Disabled"}
-                                                    isLoading={state === "Loading"}
-                                                    variant={variant}>Button</Button></td>)}
-    </tr>)}
-  </table>
+export const renderTableContent = () => (
+  <>
+    {["Normal", "Hover", "Focus", "Active", "Disabled", "Loading"].map((state) => (
+      <tr>
+        <td>{state}</td>
+        {ButtonVariantList.map((variant) => (
+          <td>
+            <Button
+              id={`${variant}-${state}`}
+              disabled={state === "Disabled"}
+              isLoading={state === "Loading"}
+              className={
+                state === "Hover"
+                  ? "is-hovered"
+                  : state === "Focus"
+                  ? "is-focused"
+                  : state === "Active"
+                  ? "is-active"
+                  : ""
+              }
+              variant={variant}
+            >
+              Button
+            </Button>
+          </td>
+        ))}
+      </tr>
+    ))}
+  </>
+);
+
+export const ButtonStates = (args) => {
+  return (
+    <>
+      <table className="table is-narrow">
+        <tr>
+          <th>STATE</th>
+          {ButtonVariantList.map((variant) => (
+            <th>{variant.toUpperCase()}</th>
+          ))}
+        </tr>
+        {renderTableContent()}
+      </table>
+      <table className="table is-narrow has-background-dark has-text-white">
+         {renderTableContent()}
+      </table>
+    </>
+  );
+};
+
+<Story
+  name="Light States"
+  parameters={{
+    themes: {
+      default: "light",
+    },
+  }}
+>
+  <ButtonStates />
 </Story>
 
-<Story name="Dark States" parameters={{
-  pseudo: {
-    hover: ButtonVariantList.map(variant => `#${variant}-Hover`),
-    focus: ButtonVariantList.map(variant => `#${variant}-Focus`),
-    active: ButtonVariantList.map(variant => `#${variant}-Active`),
-  },
-  themes: {
-    default: 'dark',
-  },
-}}>
-  <table>
-    <tr>
-      <th>STATE</th>
-      {ButtonVariantList.map(variant => <th>{variant.toUpperCase()}</th>)}
-    </tr>
-    {["Normal", "Hover", "Active", "Focus", "Disabled"].map(state => <tr>
-      <td>{state}</td>
-      {ButtonVariantList.map(variant => <td><Button id={`${variant}-${state}`} disabled={state === "Disabled"}
-                                                    variant={variant}>Button</Button></td>)}
-    </tr>)}
-  </table>
+<Story
+  name="Dark States"
+  parameters={{
+    themes: {
+      default: "dark",
+    },
+  }}
+>
+  <ButtonStates />
 </Story>
 
-<Story name="High-Contrast States" parameters={{
-  pseudo: {
-    hover: ButtonVariantList.map(variant => `#${variant}-Hover`),
-    focus: ButtonVariantList.map(variant => `#${variant}-Focus`),
-    active: ButtonVariantList.map(variant => `#${variant}-Active`),
-  },
-  themes: {
-    default: 'highcontrast',
-  },
-}}>
-  <table>
-    <tr>
-      <th>STATE</th>
-      {ButtonVariantList.map(variant => <th>{variant.toUpperCase()}</th>)}
-    </tr>
-    {["Normal", "Hover", "Active", "Focus", "Disabled"].map(state => <tr>
-      <td>{state}</td>
-      {ButtonVariantList.map(variant => <td><Button id={`${variant}-${state}`} disabled={state === "Disabled"}
-                                                    variant={variant}>Button</Button></td>)}
-    </tr>)}
-  </table>
+<Story
+  name="High-Contrast States"
+  parameters={{
+    themes: {
+      default: "highcontrast",
+    },
+  }}
+>
+  <ButtonStates />
 </Story>

package/src/base/forms/Form.tsx

@@ -17,7 +17,7 @@
 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 { Level } from "../misc";
 import { ScmFormContextProvider } from "./ScmFormContext";
 import { useTranslation } from "react-i18next";
 import { Button } from "../buttons";
@@ -135,10 +135,10 @@ function Form<FormType extends Record<string, unknown>, DefaultValues extends Fo
 
   // See https://react-hook-form.com/api/useform/reset/
   useEffect(() => {
-    if (isSubmitSuccessful) {
+    if (isSubmitSuccessful && !error) {
       setShowSuccessNotification(true);
     }
-  }, [isSubmitSuccessful]);
+  }, [isSubmitSuccessful, error]);
 
   useEffect(() => reset(defaultValues as never), [defaultValues, reset]);
 

package/src/base/forms/checkbox/Checkbox.tsx

@@ -33,6 +33,7 @@ const StyledLabel = styled.label`
 type InputFieldProps = {
   label: string;
   helpText?: string;
+  descriptionText?: string;
   testId?: string;
   labelClassName?: string;
 } & Omit<InputHTMLAttributes<HTMLInputElement>, "type">;
@@ -45,6 +46,7 @@ const Checkbox = React.forwardRef<HTMLInputElement, InputFieldProps>(
     {
       readOnly,
       label,
+      descriptionText,
       className,
       labelClassName,
       value,
@@ -57,54 +59,63 @@ const Checkbox = React.forwardRef<HTMLInputElement, InputFieldProps>(
       ...props
     },
     ref
-  ) => (
-    <StyledLabel
-      className={classNames("checkbox is-align-items-center", labelClassName)}
-      // @ts-ignore bulma uses the disabled attribute on labels, although it is not part of the html spec
-      disabled={readOnly || props.disabled}
-    >
-      {readOnly ? (
-        <>
-          <input
-            type="hidden"
-            name={name}
-            value={value}
-            defaultValue={defaultValue}
-            checked={checked}
-            defaultChecked={defaultChecked}
-            readOnly
-          />
-          <StyledInput
-            type="checkbox"
-            className={classNames("m-3", className)}
-            ref={ref}
-            value={value}
-            defaultValue={defaultValue}
-            checked={checked}
-            defaultChecked={defaultChecked}
-            {...props}
-            {...createAttributesForTesting(testId)}
-            disabled
-          />
-        </>
-      ) : (
-        <StyledInput
-          type="checkbox"
-          className={classNames("m-3", className)}
-          ref={ref}
-          name={name}
-          value={value}
-          defaultValue={defaultValue}
-          checked={checked}
-          defaultChecked={defaultChecked}
-          {...props}
-          {...createAttributesForTesting(testId)}
-        />
-      )}
+  ) => {
+    const descriptionId = descriptionText ? `checkbox-description-${name}` : undefined;
+    return (
+      <>
+        {descriptionText ? <p id={descriptionId}>{descriptionText}</p> : null}
+        <StyledLabel
+          className={classNames("checkbox is-align-items-center", labelClassName)}
+          // @ts-ignore bulma uses the disabled attribute on labels, although it is not part of the html spec
+          disabled={readOnly || props.disabled}
+        >
+          {readOnly ? (
+            <>
+              <input
+                type="hidden"
+                name={name}
+                value={value}
+                defaultValue={defaultValue}
+                checked={checked}
+                defaultChecked={defaultChecked}
+                aria-describedby={descriptionId}
+                readOnly
+              />
+              <StyledInput
+                type="checkbox"
+                className={classNames("m-3", className)}
+                ref={ref}
+                value={value}
+                defaultValue={defaultValue}
+                checked={checked}
+                defaultChecked={defaultChecked}
+                aria-describedby={descriptionId}
+                {...props}
+                {...createAttributesForTesting(testId)}
+                disabled
+              />
+            </>
+          ) : (
+            <StyledInput
+              type="checkbox"
+              className={classNames("m-3", className)}
+              ref={ref}
+              name={name}
+              value={value}
+              defaultValue={defaultValue}
+              checked={checked}
+              defaultChecked={defaultChecked}
+              aria-describedby={descriptionId}
+              {...props}
+              {...createAttributesForTesting(testId)}
+            />
+          )}
 
-      {label}
-      {helpText ? <Help className="ml-1" text={helpText} /> : null}
-    </StyledLabel>
-  )
+          {label}
+          {helpText ? <Help className="ml-1" text={helpText} /> : null}
+        </StyledLabel>
+      </>
+    );
+  }
 );
 export default Checkbox;

package/src/base/forms/checkbox/ControlledCheckboxField.tsx

@@ -35,6 +35,7 @@ function ControlledInputField<T extends Record<string, unknown>>({
   name,
   label,
   helpText,
+  descriptionText,
   rules,
   testId,
   defaultChecked,
@@ -48,6 +49,8 @@ function ControlledInputField<T extends Record<string, unknown>>({
   const prefixedNameWithoutIndices = prefixWithoutIndices(nameWithPrefix);
   const labelTranslation = label || t(`${prefixedNameWithoutIndices}.label`) || "";
   const helpTextTranslation = helpText || t(`${prefixedNameWithoutIndices}.helpText`);
+  const descriptionTextTranslation = descriptionText || t(`${prefixedNameWithoutIndices}.descriptionText`);
+
   return (
     <Controller
       control={control}
@@ -64,6 +67,7 @@ function ControlledInputField<T extends Record<string, unknown>>({
           {...field}
           label={labelTranslation}
           helpText={helpTextTranslation}
+          descriptionText={descriptionTextTranslation}
           testId={testId ?? `checkbox-${nameWithPrefix}`}
         />
       )}

package/src/base/forms/chip-input/ChipInputField.tsx

@@ -28,7 +28,6 @@ import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { useTranslation } from "react-i18next";
 import { withForwardRef } from "../helpers";
 import { Option } from "@scm-manager/ui-types";
-import { waitForRestartAfter } from "@scm-manager/ui-api";
 
 const StyledChipInput: typeof ChipInput = styled(ChipInput)`
   min-height: 40px;

package/src/base/forms/index.ts

@@ -36,12 +36,14 @@ import RadioButton from "./radio-button/RadioButton";
 import RadioGroupFieldComponent from "./radio-button/RadioGroupField";
 
 export { default as Field } from "./base/Field";
+export { default as FieldMessage } from "./base/field-message/FieldMessage";
 export { default as Checkbox } from "./checkbox/Checkbox";
 export { default as Combobox } from "./combobox/Combobox";
 export { default as ConfigurationForm } from "./ConfigurationForm";
 export { default as SelectField } from "./select/SelectField";
 export { default as ComboboxField } from "./combobox/ComboboxField";
 export { default as Input } from "./input/Input";
+export { default as InputField } from "./input/InputField";
 export { default as Textarea } from "./input/Textarea";
 export { default as Select } from "./select/Select";
 export * from "./resourceHooks";

package/src/base/forms/input/ControlledInputField.tsx

@@ -29,17 +29,20 @@ type Props<T extends Record<string, unknown>> = Omit<
   rules?: ComponentProps<typeof Controller>["rules"];
   name: Path<T>;
   label?: string;
+  icon?: string;
 };
 
 function ControlledInputField<T extends Record<string, unknown>>({
   name,
   label,
   helpText,
+  descriptionText,
   rules,
   testId,
   defaultValue,
   readOnly,
   className,
+  icon,
   ...props
 }: Props<T>) {
   const { control, t, readOnly: formReadonly, formId } = useScmFormContext();
@@ -48,6 +51,8 @@ function ControlledInputField<T extends Record<string, unknown>>({
   const prefixedNameWithoutIndices = prefixWithoutIndices(nameWithPrefix);
   const labelTranslation = label || t(`${prefixedNameWithoutIndices}.label`) || "";
   const helpTextTranslation = helpText || t(`${prefixedNameWithoutIndices}.helpText`);
+  const descriptionTextTranslation = descriptionText || t(`${prefixedNameWithoutIndices}.descriptionText`);
+
   return (
     <Controller
       control={control}
@@ -63,7 +68,9 @@ function ControlledInputField<T extends Record<string, unknown>>({
           {...field}
           form={formId}
           label={labelTranslation}
+          icon={icon}
           helpText={helpTextTranslation}
+          descriptionText={descriptionTextTranslation}
           error={
             fieldState.error
               ? fieldState.error.message || t(`${prefixedNameWithoutIndices}.error.${fieldState.error.type}`)

package/src/base/forms/input/InputField.stories.mdx

@@ -20,3 +20,7 @@ This will be our first form field molecule
 <Story name="WithWidth">
     <InputField label="MyInput" className="column is-half" />
 </Story>
+
+<Story name="WithIcon">
+  <InputField icon="fas fa-filter" />
+</Story>

package/src/base/forms/input/InputField.tsx

@@ -23,27 +23,41 @@ import Input from "./Input";
 import Help from "../base/help/Help";
 import { useAriaId } from "../../helpers";
 
-type InputFieldProps = {
+export type InputFieldProps = {
   label: string;
+  labelClassName?: string;
   helpText?: string;
+  descriptionText?: string;
   error?: string;
+  icon?: string;
 } & React.ComponentProps<typeof Input>;
 
 /**
  * @see https://bulma.io/documentation/form/input/
  */
 const InputField = React.forwardRef<HTMLInputElement, InputFieldProps>(
-  ({ label, helpText, error, className, id, ...props }, ref) => {
+  ({ name, label, helpText, descriptionText, error, icon, className, labelClassName, id, ...props }, ref) => {
     const inputId = useAriaId(id ?? props.testId);
+    const descriptionId = descriptionText ? `input-description-${name}` : undefined;
     const variant = error ? "danger" : undefined;
     return (
       <Field className={className}>
-        <Label htmlFor={inputId}>
+        <Label htmlFor={inputId} className={labelClassName}>
           {label}
           {helpText ? <Help className="ml-1" text={helpText} /> : null}
         </Label>
-        <Control>
-          <Input variant={variant} ref={ref} id={inputId} {...props}></Input>
+        {descriptionText ? (
+          <p className="mb-2" id={descriptionId}>
+            {descriptionText}
+          </p>
+        ) : null}
+        <Control className="has-icons-left">
+          <Input variant={variant} ref={ref} id={inputId} aria-describedby={descriptionId} {...props}></Input>
+          {icon ? (
+            <span className="icon is-small is-left">
+              <i className={icon} />
+            </span>
+          ) : null}
         </Control>
         {error ? <FieldMessage variant={variant}>{error}</FieldMessage> : null}
       </Field>

package/src/base/notifications/Notification.tsx

@@ -30,7 +30,7 @@ const Notification = React.forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElem
     const color = type !== "inherit" ? "is-" + type : "";
 
     return (
-      <div className={classNames("notification", color, className)} role={role} ref={ref}>
+      <div className={classNames("notification", color, className)} role={role} ref={ref} {...props}>
         {onClose ? <button className="delete" onClick={onClose} /> : null}
         {children}
       </div>

package/src/base/shortcuts/index.ts

@@ -17,4 +17,9 @@
 export { default as useShortcut } from "./useShortcut";
 export { default as useShortcutDocs, ShortcutDocsContextProvider } from "./useShortcutDocs";
 export { default as usePauseShortcuts } from "./usePauseShortcuts";
-export { useKeyboardIteratorTarget, KeyboardIterator, KeyboardSubIterator } from "./iterator/keyboardIterator";
+export {
+  useKeyboardIteratorTarget,
+  KeyboardIterator,
+  KeyboardSubIterator,
+  useKeyboardIteratorTargetV2,
+} from "./iterator/keyboardIterator";

package/src/base/shortcuts/iterator/callbackIterator.ts

@@ -20,6 +20,12 @@ const INACTIVE_INDEX = -1;
 
 export type Callback = () => void;
 
+export type IterableCallback = {
+  item: Callback | CallbackIterator;
+  expectedIndex: number;
+  cleanup?: Callback;
+};
+
 type Direction = "forward" | "backward";
 
 /**
@@ -31,11 +37,18 @@ export type CallbackRegistry = {
    * Registers the given item and returns its index to use in {@link deregister}.
    */
   register: (item: Callback | CallbackIterator) => number;
-
   /**
    * Use the index returned from {@link register} to de-register.
    */
   deregister: (index: number) => void;
+  /**
+   * Registers the given iterable item while maintaining the order of the expected index of each item.
+   */
+  registerItem?: (iterable: IterableCallback) => void;
+  /**
+   * Removes the passed iterable item.
+   */
+  deregisterItem?: (iterable: IterableCallback) => void;
 };
 
 const isSubiterator = (item?: Callback | CallbackIterator): item is CallbackIterator =>
@@ -51,6 +64,8 @@ const offset = (direction: Direction) => (direction === "forward" ? 1 : -1);
  *
  * ## Terminology
  * - Item: Either a callback or a nested iterator
+ * - Cleanup: A callback that is called, if the corresponding item is removed
+ * - Iterable: A wrapper containing an item, a cleanup callback and the index that this iterable is expected to be at
  * - Available: Item is a non-empty iterator OR a regular callback
  * - Inactive: Current index is -1
  * - Activate: Move iterator while in inactive state OR call regular callback
@@ -68,7 +83,7 @@ export class CallbackIterator implements CallbackRegistry {
 
   constructor(
     private readonly activeIndexRef: MutableRefObject<number>,
-    private readonly itemsRef: MutableRefObject<Array<Callback | CallbackIterator>>
+    private readonly itemsRef: MutableRefObject<Array<IterableCallback>>
   ) {}
 
   private get activeIndex() {
@@ -83,7 +98,7 @@ export class CallbackIterator implements CallbackRegistry {
     return this.itemsRef.current;
   }
 
-  private get currentItem(): Callback | CallbackIterator | undefined {
+  private get currentItem(): IterableCallback | undefined {
     return this.items[this.activeIndex];
   }
 
@@ -101,9 +116,9 @@ export class CallbackIterator implements CallbackRegistry {
 
   private firstAvailableIndex = (direction: Direction, fromIndex = this.firstIndex(direction)) => {
     for (; direction === "forward" ? fromIndex < this.items.length : fromIndex >= 0; fromIndex += offset(direction)) {
-      const callback = this.items[fromIndex];
-      if (callback) {
-        if (!isSubiterator(callback) || callback.hasNext(direction)) {
+      const iterableCallback = this.items[fromIndex];
+      if (iterableCallback) {
+        if (!isSubiterator(iterableCallback.item) || iterableCallback.item.hasNext(direction)) {
           return fromIndex;
         }
       }
@@ -116,14 +131,15 @@ export class CallbackIterator implements CallbackRegistry {
   };
 
   private activateCurrentItem = (direction: Direction) => {
-    if (isSubiterator(this.currentItem)) {
-      this.currentItem.move(direction);
+    if (isSubiterator(this.currentItem?.item)) {
+      this.currentItem?.item.move(direction);
     } else if (this.currentItem) {
-      this.currentItem();
+      this.currentItem.item();
     }
   };
 
   private setIndexAndActivateCurrentItem = (index: number | null, direction: Direction) => {
+    this.currentItem?.cleanup?.();
     if (index !== null && index !== INACTIVE_INDEX) {
       this.activeIndex = index;
       this.activateCurrentItem(direction);
@@ -131,11 +147,11 @@ export class CallbackIterator implements CallbackRegistry {
   };
 
   private move = (direction: Direction) => {
-    if (isSubiterator(this.currentItem) && this.currentItem.hasNext(direction)) {
-      this.currentItem.move(direction);
+    if (isSubiterator(this.currentItem?.item) && this.currentItem?.item.hasNext(direction)) {
+      this.currentItem?.item.move(direction);
     } else {
-      if (isSubiterator(this.currentItem)) {
-        this.currentItem.reset();
+      if (isSubiterator(this.currentItem?.item)) {
+        this.currentItem?.item.reset();
       }
       let nextIndex: number | null;
       if (this.isInactive) {
@@ -151,7 +167,7 @@ export class CallbackIterator implements CallbackRegistry {
     if (this.isInactive) {
       return this.hasAvailableIndex(inDirection);
     }
-    if (isSubiterator(this.currentItem) && this.currentItem.hasNext(inDirection)) {
+    if (isSubiterator(this.currentItem?.item) && this.currentItem?.item.hasNext(inDirection)) {
       return true;
     }
     return this.hasAvailableIndex(inDirection, this.activeIndex + offset(inDirection));
@@ -172,41 +188,66 @@ export class CallbackIterator implements CallbackRegistry {
   public reset = () => {
     this.activeIndex = INACTIVE_INDEX;
     for (const cb of this.items) {
-      if (isSubiterator(cb)) {
-        cb.reset();
+      if (isSubiterator(cb.item)) {
+        cb.item.reset();
       }
     }
   };
 
   public register = (item: Callback | CallbackIterator) => {
-    if (isSubiterator(item)) {
-      item.parent = this;
-    }
-    return this.items.push(item) - 1;
+    const expectedIndex = this.items.length;
+    this.registerItem({ item, expectedIndex });
+    return expectedIndex;
   };
 
   public deregister = (index: number) => {
-    this.items.splice(index, 1);
-    if (this.activeIndex === index || this.activeIndex >= this.items.length) {
-      if (this.hasAvailableIndex("backward", index)) {
-        this.setIndexAndActivateCurrentItem(this.firstAvailableIndex("backward", index), "backward");
-      } else if (this.hasAvailableIndex("forward", index)) {
-        this.setIndexAndActivateCurrentItem(this.firstAvailableIndex("forward", index), "backward");
-      } else if (this.parent) {
-        if (this.parent.hasNext("forward")) {
-          this.parent.move("forward");
-        } else if (this.parent.hasNext("backward")) {
-          this.parent.move("backward");
-        }
+    if (this.items[index]) {
+      this.deregisterItem(this.items[index]);
+    }
+  };
+
+  public deregisterItem = (iterable: IterableCallback) => {
+    const itemIndex = this.items.findIndex((value) => value.expectedIndex === iterable.expectedIndex);
+    if (itemIndex === -1) {
+      return;
+    }
+
+    const removedIterable = this.items[itemIndex];
+    removedIterable.cleanup?.();
+
+    this.items.splice(itemIndex, 1);
+    if (this.activeIndex >= itemIndex) {
+      if (this.hasAvailableIndex("backward")) {
+        this.setIndexAndActivateCurrentItem(this.firstAvailableIndex("backward", itemIndex), "backward");
+      } else if (this.hasAvailableIndex("forward")) {
+        this.setIndexAndActivateCurrentItem(this.firstAvailableIndex("forward", itemIndex), "forward");
+      } else if (this.parent?.hasNext("forward")) {
+        this.parent?.move("forward");
+      } else if (this.parent?.hasNext("backward")) {
+        this.parent?.move("backward");
       } else {
         this.reset();
       }
     }
   };
+
+  public registerItem = (iterable: IterableCallback) => {
+    if (isSubiterator(iterable.item)) {
+      iterable.item.parent = this;
+    }
+
+    const insertAt = this.items.findIndex((value) => value.expectedIndex > iterable.expectedIndex);
+
+    if (insertAt === -1) {
+      this.items.push(iterable);
+    } else {
+      this.items.splice(insertAt, 0, iterable);
+    }
+  };
 }
 
 export const useCallbackIterator = (initialIndex = INACTIVE_INDEX) => {
-  const items = useRef<Array<Callback | CallbackIterator>>([]);
+  const items = useRef<Array<IterableCallback>>([]);
   const activeIndex = useRef<number>(initialIndex);
   return useMemo(() => new CallbackIterator(activeIndex, items), [activeIndex, items]);
 };

package/src/base/shortcuts/iterator/keyboardIterator.test.tsx

@@ -277,9 +277,6 @@ describe("shortcutIterator", () => {
       expect(callback).toHaveBeenCalledTimes(1);
       expect(callback2).toHaveBeenCalledTimes(1);
       expect(callback3).toHaveBeenCalledTimes(1);
-
-      expect(callback).toHaveBeenCalledBefore(callback2);
-      expect(callback2).toHaveBeenCalledBefore(callback3);
     });
 
     it("should call first target that is not an empty subiterator", () => {
@@ -378,8 +375,6 @@ describe("shortcutIterator", () => {
       expect(callback3).not.toHaveBeenCalled();
       expect(callback2).toHaveBeenCalledTimes(1);
       expect(callback).toHaveBeenCalledTimes(1);
-
-      expect(callback2).toHaveBeenCalledBefore(callback);
     });
 
     it("should move subiterator if its active callback is de-registered", () => {

package/src/base/shortcuts/iterator/keyboardIterator.tsx

@@ -17,7 +17,13 @@
 import React, { FC, useCallback, useContext, useEffect, useRef } from "react";
 import { useTranslation } from "react-i18next";
 import { useShortcut } from "../index";
-import { Callback, CallbackIterator, CallbackRegistry, useCallbackIterator } from "./callbackIterator";
+import {
+  Callback,
+  CallbackIterator,
+  CallbackRegistry,
+  IterableCallback,
+  useCallbackIterator,
+} from "./callbackIterator";
 
 const KeyboardIteratorContext = React.createContext<CallbackRegistry>({
   register: () => {
@@ -33,6 +39,18 @@ const KeyboardIteratorContext = React.createContext<CallbackRegistry>({
       console.warn("Keyboard iterator targets have to be declared inside a KeyboardIterator");
     }
   },
+  deregisterItem: () => {
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.warn("Keyboard iterator targets have to be declared inside a KeyboardIterator");
+    }
+  },
+  registerItem: () => {
+    if (process.env.NODE_ENV === "development") {
+      // eslint-disable-next-line no-console
+      console.warn("Keyboard iterator targets have to be declared inside a KeyboardIterator");
+    }
+  },
 });
 
 export const useKeyboardIteratorItem = (item: Callback | CallbackIterator) => {
@@ -43,6 +61,14 @@ export const useKeyboardIteratorItem = (item: Callback | CallbackIterator) => {
   }, [item, register, deregister]);
 };
 
+export const useKeyboardIteratorItemV2 = (iterable: IterableCallback) => {
+  const { registerItem, deregisterItem } = useContext(KeyboardIteratorContext);
+  useEffect(() => {
+    registerItem?.(iterable);
+    return () => deregisterItem?.(iterable);
+  }, [iterable, registerItem, deregisterItem]);
+};
+
 export const KeyboardSubIteratorContextProvider: FC<{ initialIndex?: number }> = ({ children, initialIndex }) => {
   const callbackIterator = useCallbackIterator(initialIndex);
 
@@ -73,6 +99,7 @@ export const KeyboardIteratorContextProvider: FC<{ initialIndex?: number }> = ({
 };
 
 /**
+ * @deprecated since version 3.8.0. Use {@link useKeyboardIteratorTargetV2} instead.
  * Use the {@link React.RefObject} returned from this hook to register a target to the nearest enclosing {@link KeyboardIterator} or {@link KeyboardSubIterator}.
  *
  * @example
@@ -91,6 +118,32 @@ export function useKeyboardIteratorTarget(): React.RefCallback<HTMLElement> {
   return refCallback;
 }
 
+/**
+ * @deprecated since version 3.8.0. Use {@link useKeyboardIteratorTargetV2} instead.
+ * Use the {@link React.RefObject} returned from this hook to register a target to the nearest enclosing {@link KeyboardIterator} or {@link KeyboardSubIterator},
+ * while respecting its expected index / position.
+ *
+ * @example
+ * const ref = useKeyboardIteratorTarget({ expectedIndex: 0});
+ * const target = <button ref={ref}>My Iteration Target</button>
+ */
+export function useKeyboardIteratorTargetV2({
+  expectedIndex,
+}: {
+  expectedIndex: number;
+}): React.RefCallback<HTMLElement> {
+  const ref = useRef<HTMLElement>();
+  const callback = useCallback(() => ref.current?.focus(), []);
+  const cleanup = useCallback(() => ref.current?.blur(), []);
+  const refCallback: React.RefCallback<HTMLElement> = useCallback((el) => {
+    if (el) {
+      ref.current = el;
+    }
+  }, []);
+  useKeyboardIteratorItemV2({ item: callback, cleanup, expectedIndex });
+  return refCallback;
+}
+
 /**
  * Allows keyboard users to iterate through a list of items, defined by enclosed {@link useKeyboardIteratorTarget} invocations.
  *

package/src/index.ts

@@ -14,4 +14,4 @@
  * along with this program. If not, see https://www.gnu.org/licenses/.
  */
 
-export * from "./base"
+export * from "./base";