feat(appsscript/sheet): Add extractSheetNameFromA1Notation utility function

Author: MaksymStoianov

src/appsscript/sheet/extractSheetNameFromA1Notation.ts

@@ -1,19 +1,47 @@
 import { IllegalArgumentException } from "../../exception";
-import { requireNonEmptyString } from "../../lang";
+import { isString } from "../../lang";
 import { isValidSheetName } from "./isValidSheetName";
 import { parseA1Notation } from "./parseA1Notation";
 
-export function extractSheetNameFromA1Notation(a1Notation: string): string {
+/**
+ * ## extractSheetNameFromA1Notation
+ *
+ * Extracts the sheet name from an A1 notation string (e.g., `Sheet1!A1:B2`).
+ *
+ * This function returns the sheet name as a clean string, or `null` if the
+ * notation contains only the range part (e.g., `A1:B2`).
+ *
+ * @param       {string} a1Notation - The A1 notation string (e.g., `SheetName!A1`, `Sheet Name'!A:A`).
+ * @returns     {string|null} The extracted sheet name, or `null` if no sheet name is present in the notation.
+ * @throws      {Error}
+ * @throws      {IllegalArgumentException}
+ * @see         {@link parseA1Notation}
+ * @see         {@link GridRange}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Range|Range}
+ * @see         {@link GoogleAppsScript.Spreadsheet.Sheet|Sheet}
+ * @see         [Class Range](https://developers.google.com/apps-script/reference/spreadsheet/range)
+ * @see         [Class Sheet](https://developers.google.com/apps-script/reference/spreadsheet/sheet)
+ * @since       1.6.0
+ * @version     1.0.0
+ * @environment `Google Apps Script`, `Browser`
+ * @author      Maksym Stoianov <stoianov.maksym@gmail.com>
+ * @license     Apache-2.0
+ */
+export function extractSheetNameFromA1Notation(
+  a1Notation: string
+): string | null {
   if (arguments.length === 0) {
     throw new IllegalArgumentException();
   }
 
-  const gridRange = parseA1Notation(a1Notation);
+  const { sheetName } = parseA1Notation(a1Notation);
 
-  const sheetName = requireNonEmptyString(gridRange.sheetName);
+  if (!isString(sheetName)) {
+    return null;
+  }
 
   if (!isValidSheetName(sheetName)) {
-    throw new Error();
+    throw new Error("Expected a valid sheet name");
   }
 
   return sheetName;