feat(hooks): refactor useAutoId for better SSR and type safety

- Refactor useAutoId to always return a string (no undefined)
- Add support for custom ID length via options parameter
- Improve SSR safety by generating IDs during initialization
- Add new utility functions: generateUUID
- Update tests to cover all ID generation scenarios
- Fix React.useId detection for better compatibility
- Add proper TypeScript types and documentation

BREAKING CHANGE: useAutoId now always returns a string instead of string | undefined

Author: João Dias

cypress/test/functions/utlities/generate-uuid.cy.ts

@@ -0,0 +1,26 @@
+/**
+ * The copyright of this file belongs to Feedzai. The file cannot be
+ * reproduced in whole or in part, stored in a retrieval system, transmitted
+ * in any form, or by any means electronic, mechanical, or otherwise, without
+ * the prior permission of the owner. Please refer to the terms of the license
+ * agreement.
+ *
+ * (c) 2025 Feedzai, Rights Reserved.
+ */
+
+import { generateUUID } from "src/functions";
+
+describe("generateUUID", () => {
+  it("generates a UUID", () => {
+    const id = generateUUID();
+    expect(id).to.exist;
+    expect(typeof id).to.equal("string");
+  });
+
+  it("should generate a compliant RFC 4122 UUID", () => {
+    const id = generateUUID();
+    expect(id).to.match(
+      /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/
+    );
+  });
+});

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

@@ -4,9 +4,9 @@
  * (c) 2024 Feedzai, Rights Reserved.
  */
 import React from "react";
-import { useAutoId } from "src/hooks";
+import { useAutoId, generateFallbackId, generateUUIDFragment, initializeState } from "src/hooks";
 
-function DemoComponent({ value = null, prefix }: { value?: string | null; prefix?: string }) {
+function DemoComponent({ value, prefix }: { value?: string | null; prefix?: string }) {
   const firstId = useAutoId(value, prefix);
   const secondId = useAutoId();
   return (
@@ -21,88 +21,132 @@ function FallbackDemo({
   value = "feedzai-fallback-id",
   prefix,
 }: {
-  value?: string | null;
+  value?: string;
   prefix?: string;
 }) {
   const id = useAutoId(value, prefix);
   return <h1 id={id}>Feedzai</h1>;
 }
 
+describe("generateFallbackId", () => {
+  it("generates a fallback ID", () => {
+    const id = generateFallbackId();
+    expect(id).to.exist;
+    expect(typeof id).to.equal("string");
+  });
+});
+
+describe("generateUUIDFragment", () => {
+  it("generates a UUID fragment", () => {
+    const id = generateUUIDFragment();
+    expect(id).to.exist;
+    expect(typeof id).to.equal("string");
+    expect(id.length).to.equal(8);
+  });
+
+  it("generates a UUID fragment of a given length", () => {
+    const id = generateUUIDFragment(16);
+    expect(id).to.exist;
+    expect(typeof id).to.equal("string");
+    expect(id.length).to.equal(16);
+  });
+});
+
+describe("initializeState", () => {
+  it("generates a UUID fragment if no ID is provided", () => {
+    // @ts-expect-error - This is a test for the fallback behavior
+    const id = initializeState();
+    expect(id).to.exist;
+    expect(typeof id).to.equal("string");
+  });
+
+  it("generates a UUID fragment of a given length if no ID is provided", () => {
+    const id = initializeState(undefined, { length: 16 });
+    expect(id).to.exist;
+    expect(typeof id).to.equal("string");
+    expect(id.length).to.equal(16);
+  });
+
+  it("returns the provided ID if it is a string", () => {
+    const id = initializeState("feedzai-id");
+    expect(id).to.equal("feedzai-id");
+  });
+});
+
 describe("useAutoId", () => {
-  context("React pre-useId", () => {
+  it("generates a prefixed fallback ID", () => {
+    cy.mount(<DemoComponent prefix="fdz-prefix" />);
+
+    console.log(process.env.NODE_ENV);
+
+    cy.findByText("A paragraph")
+      .invoke("attr", "id")
+      .should("match", /^fdz-prefix--:?[a-z0-9:]+:?$/);
+  });
+
+  context("React <18 (no useId support)", () => {
     beforeEach(() => {
-      // Mock React.useId to be undefined
       cy.stub(React, "useId").as("useIdStub").value(undefined);
     });
 
-    it("should generate a unique ID value", () => {
+    it("generates unique IDs using fallback generator", () => {
       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} />);
+        .then((firstId) => {
+          expect(firstId).to.exist;
 
-      cy.findByText("A paragraph").invoke("attr", "id").should("contain", expected);
+          cy.findByText("An inline span element")
+            .invoke("attr", "id")
+            .should("exist")
+            .and("not.equal", firstId);
+        });
     });
 
-    it("uses a fallback ID", () => {
+    it("uses a static fallback ID if provided", () => {
       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" />);
+    it("applies a prefix to the custom fallback ID", () => {
+      cy.mount(<FallbackDemo value="423696e5" prefix="js-prefix" />);
 
       cy.findByText("Feedzai").should("have.id", "js-prefix--423696e5");
     });
   });
 
-  context("React 18+ with useId", () => {
-    const GENERATED_ID = ":r0:";
-
-    beforeEach(() => {
-      // Mock React.useId to return a predictable value
-      cy.stub(React, "useId").as("useIdStub").returns(GENERATED_ID);
-    });
-
-    it("should use React.useId for generating IDs", () => {
+  context("React 18+ (with useId)", () => {
+    it("uses React.useId to generate consistent IDs", () => {
       cy.mount(<DemoComponent />);
 
-      cy.findByText("A paragraph").invoke("attr", "id").should("equal", GENERATED_ID);
-      cy.findByText("An inline span element").invoke("attr", "id").should("equal", GENERATED_ID);
-      cy.get("@useIdStub").should("be.calledTwice");
+      cy.findByText("A paragraph")
+        .invoke("attr", "id")
+        .should("match", /^:?[a-z0-9:]+:?$/);
+      cy.findByText("An inline span element")
+        .invoke("attr", "id")
+        .should("match", /^:?[a-z0-9:]+:?$/);
     });
 
-    it("should generate a prefixed unique ID value using React.useId", () => {
-      const expected = "feedzai-a-prefix";
-      cy.mount(<DemoComponent value={undefined} prefix={expected} />);
+    it("applies prefix to ID generated by React.useId", () => {
+      cy.mount(<DemoComponent prefix="fdz-js-prefix" />);
 
       cy.findByText("A paragraph")
         .invoke("attr", "id")
-        .should("equal", `${expected}--${GENERATED_ID}`);
-      cy.get("@useIdStub").should("be.called");
+        .should("match", /^fdz-js-prefix--:?[a-z0-9:]+:?$/);
     });
 
-    it("uses a fallback ID even when React.useId is available", () => {
+    it("uses static fallback ID when explicitly provided", () => {
       cy.mount(<FallbackDemo />);
 
       cy.findByText("Feedzai").should("have.id", "feedzai-fallback-id");
-      cy.get("@useIdStub").should("not.be.called");
     });
 
-    it("should return a prefixed fallback ID and not use React.useId", () => {
-      cy.mount(<FallbackDemo prefix="js-prefix" value="423696e5" />);
+    it("applies prefix to provided fallback ID (ignoring useId)", () => {
+      cy.mount(<FallbackDemo value="423696e5" prefix="fdz-js-prefix" />);
 
-      cy.findByText("Feedzai").should("have.id", "js-prefix--423696e5");
-      cy.get("@useIdStub").should("not.be.called");
+      cy.findByText("Feedzai").should("have.id", "fdz-js-prefix--423696e5");
     });
   });
 });

src/functions/string/make-id.ts

@@ -9,11 +9,8 @@
  * 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));
+ * makeId("fdz-js-tabbable-button", "123")
+ * // => "fdz-js-tabbable--button-123"
  *
  * @param args
  * @returns {string}

src/functions/utilities/generate-uuid.ts

@@ -0,0 +1,81 @@
+/**
+ * The copyright of this file belongs to Feedzai. The file cannot be
+ * reproduced in whole or in part, stored in a retrieval system, transmitted
+ * in any form, or by any means electronic, mechanical, or otherwise, without
+ * the prior permission of the owner. Please refer to the terms of the license
+ * agreement.
+ *
+ * (c) 2025 Feedzai, Rights Reserved.
+ */
+
+import { isFunction, isNil } from "../typed";
+
+let cryptoRef: Crypto | undefined;
+
+try {
+  cryptoRef =
+    typeof globalThis !== "undefined" && globalThis.crypto ? globalThis.crypto : undefined;
+} catch {
+  cryptoRef = undefined;
+}
+
+const CAN_USE_CRYPTO = !isNil(cryptoRef);
+const CAN_USE_CRYPTO_RANDOM_UUID = Boolean(
+  CAN_USE_CRYPTO && isFunction(globalThis.crypto.randomUUID)
+);
+const CAN_USE_CRYPTO_GET_RANDOM_VALUES = Boolean(
+  CAN_USE_CRYPTO && isFunction(globalThis.crypto.getRandomValues)
+);
+
+/**
+ * Generates a UUID using the fallback implementation (RFC 4122 version 4)
+ *
+ * @returns {string} A unique identifier
+ */
+function generateFallbackUUID() {
+  // Fallback implementation (RFC 4122 version 4)
+  const bytes = CAN_USE_CRYPTO_GET_RANDOM_VALUES
+    ? cryptoRef!.getRandomValues(new Uint8Array(16))
+    : Array.from({ length: 16 }, () => Math.floor(Math.random() * 256));
+
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // Set version to 0100
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // Set variant to 10
+
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0"));
+
+  return (
+    hex.slice(0, 4).join("") +
+    "-" +
+    hex.slice(4, 6).join("") +
+    "-" +
+    hex.slice(6, 8).join("") +
+    "-" +
+    hex.slice(8, 10).join("") +
+    "-" +
+    hex.slice(10, 16).join("")
+  );
+}
+
+/**
+ * Generates a UUID using crypto.randomUUID if available, otherwise falls back to a fallback ID
+ *
+ * @example
+ * ```ts
+ * import { generateUUID } from "@feedzai/react-utilities";
+ *
+ * const uuid = generateUUID(); // "123e4567-e89b-12d3-a456-426614174000"
+ * ```
+ *
+ * @returns {string} A unique identifier
+ */
+export function generateUUID() {
+  if (CAN_USE_CRYPTO_RANDOM_UUID) {
+    try {
+      return cryptoRef!.randomUUID();
+    } catch {
+      return generateFallbackUUID();
+    }
+  }
+
+  return generateFallbackUUID();
+}

src/functions/utilities/index.ts

@@ -2,3 +2,4 @@ export * from "./call-if-exists";
 export * from "./empty-function";
 export * from "./make-cancelable";
 export * from "./throw-error";
+export * from "./generate-uuid";