feat(hooks): adds useAutoId hook

Author: JoaoTMDias

cypress/test/hooks/use-auto-id.cy.tsx

@@ -0,0 +1,59 @@
+/*
+ * Please refer to the terms of the license agreement.
+ *
+ * (c) 2024 Feedzai, Rights Reserved.
+ */
+import { useAutoId } from "src/hooks";
+
+function DemoComponent({ value = null, prefix }: { value?: string | null; prefix?: string }) {
+  const firstId = useAutoId(value, prefix);
+  const secondId = useAutoId();
+  return (
+    <div>
+      <p id={firstId}>A paragraph</p>
+      <span id={secondId}>An inline span element</span>
+    </div>
+  );
+}
+
+function FallbackDemo({
+  value = "feedzai-fallback-id",
+  prefix,
+}: {
+  value?: string | null;
+  prefix?: string;
+}) {
+  const id = useAutoId(value, prefix);
+  return <h1 id={id}>Feedzai</h1>;
+}
+
+describe("useAutoId", () => {
+  it("should generate a unique ID value", () => {
+    cy.mount(<DemoComponent />);
+
+    cy.findByText("A paragraph")
+      .invoke("attr", "id")
+      .then((idOne) => {
+        cy.findByText("An inline span element").invoke("attr", "id").should("not.equal", idOne);
+      });
+  });
+
+  it("should generate a prefixed unique ID value", () => {
+    const expected = "feedzai-a-prefix";
+    cy.mount(<DemoComponent value={undefined} prefix={expected} />);
+
+    cy.findByText("A paragraph").invoke("attr", "id").should("contain", expected);
+  });
+
+  it("uses a fallback ID", () => {
+    cy.mount(<FallbackDemo />);
+
+    cy.findByText("Feedzai").should("have.id", "feedzai-fallback-id");
+  });
+
+  it("should return a prefixed fallback ID", () => {
+    cy.mount(<FallbackDemo prefix="js-prefix" value="423696e5" />);
+
+    cy.findByText("Feedzai").should("have.id", "js-prefix--423696e5");
+  });
+});

src/functions/string/index.ts

@@ -7,6 +7,7 @@ export * from "./camel-case";
 export * from "./capitalize";
 export * from "./escape-reg-exp";
 export * from "./kebab-case";
+export * from "./make-id";
 export * from "./pascal-case";
 export * from "./readable-string-list";
 export * from "./strip-unit";

src/functions/string/make-id.ts

@@ -0,0 +1,23 @@
+/*
+ * Please refer to the terms of the license
+ * agreement.
+ *
+ * (c) 2024 Feedzai, Rights Reserved.
+ */
+
+/**
+ * Joins strings to format IDs for compound components.
+ *
+ * @example
+ *
+ * // Custom generated id by using the `useAutoId` hook and the `makeId` function
+ * // to join the auto-generated id with a custom string
+ * const autoId = useAutoId(id);
+ * const { current: generatedId } = useRef(makeId("fdz-js-tabbable-button-", autoId));
+ *
+ * @param args
+ * @returns {string}
+ */
+export function makeId(...args: (string | number | null | undefined)[]) {
+  return args.filter((val) => val !== null).join("--");
+}

src/hooks/index.ts

@@ -3,6 +3,7 @@
  *
  * (c) 2024 Feedzai
  */
+export * from "./use-auto-id";
 export * from "./use-click-outside";
 export * from "./use-constant";
 export * from "./use-container-query";

src/hooks/use-auto-id.ts

@@ -0,0 +1,85 @@
+/*
+ * Please refer to the terms of the license
+ * agreement.
+ *
+ * (c) 2024 Feedzai, Rights Reserved.
+ */
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useSafeLayoutEffect } from ".";
+import { makeId } from "..";
+
+let hasHydrated = false;
+let id = 0;
+
+/**
+ * Returns an incremented id number
+ *
+ * @returns {number}
+ */
+const generateIncrementalId = () => ++id;
+
+/**
+ * Generate automatic IDs to facilitate WAI-ARIA
+ *
+ * The returned ID will initially be `null` and will update after a
+ * component mounts. Users may need to supply their own ID if they need
+ * consistent values for SSR.
+ *
+ * @example
+ *
+ * // Generating an id (no pre-defined id and no prefix)
+ * const id1 = useAutoId(); // will return, for example, "0"
+ *
+ * // Using a pre-defined id (no prefix)
+ * const id2 = useAutoId("8e88aa2e-e6a8") // will return "8e88aa2e-e6a8"
+ *
+ * // Using a prefix with an auto-generated id (no pre-defined id)
+ * const id3 = useAutoId(undefined, "fdz-prefix") // will return, for example, "fdz-prefix--10"
+ *
+ * // Using a prefix with a pre-defined id
+ * const id4 = useAutoId("6949d175", "fdz-js-checkbox") // will return "fdz-js-checkbox--6949d175"
+ *
+ * @param {string | null | undefined} customId - You can pass an previously defined value
+ * and that value will be used as the value of the returned id.
+ * @param {string | undefined} prefix - If necessary, you can prepend a generated id with a prefix.
+ * @returns {string | undefined} an auto/self-generated id with a possible prefix
+ */
+function useAutoId(customId?: string | null, prefix?: string): string | undefined {
+  const { current: idPrefix } = useRef(prefix);
+  const initialId = customId || (hasHydrated ? generateIncrementalId() : null);
+  const [id, setId] = useState(initialId);
+
+  /*
+   * Patch the ID after render to avoid any rendering flicker.
+   */
+  useSafeLayoutEffect(() => {
+    if (id === null) {
+      setId(generateIncrementalId());
+    }
+  }, []);
+
+  /*
+   * Flag all future uses of `useAutoId` to skip the updating cycle.
+   * We use `useEffect` because it happens after `useLayoutEffect`.
+   * This way we make sure that we complete the patch process until the end.
+   */
+  useEffect(() => {
+    if (hasHydrated === false) {
+      hasHydrated = true;
+    }
+  }, []);
+
+  const finalId = useMemo(() => {
+    if (!id) {
+      return undefined;
+    }
+
+    const finalId = String(id);
+
+    return idPrefix ? makeId(idPrefix, finalId) : finalId;
+  }, [id, idPrefix]);
+
+  return finalId;
+}
+
+export { useAutoId };