refactor(Font): consolidate API layer and update type structure

src/entities/Font/lib/getFontUrl/getFontUrl.ts

@@ -3,13 +3,31 @@ import type {
     UnifiedFont,
 } from '../../model';
 
+/** Valid font weight values (100-900 in increments of 100) */
 const SIZES = [100, 200, 300, 400, 500, 600, 700, 800, 900];
 
 /**
- * Constructs a URL for a font based on the provided font and weight.
- * @param font - The font object.
- * @param weight - The weight of the font.
- * @returns The URL for the font.
+ * Gets the URL for a font file at a specific weight
+ *
+ * Constructs the appropriate URL for loading a font file based on
+ * the font object and requested weight. Handles variable fonts and
+ * provides fallbacks for static fonts.
+ *
+ * @param font - Unified font object containing style URLs
+ * @param weight - Font weight (100-900)
+ * @returns URL string for the font file, or undefined if not found
+ * @throws Error if weight is not a valid value (100-900)
+ *
+ * @example
+ * ```ts
+ * const url = getFontUrl(roboto, 700); // Returns URL for Roboto Bold
+ *
+ * // Variable fonts: backend maps weight to VF URL
+ * const vfUrl = getFontUrl(inter, 450); // Returns variable font URL
+ *
+ * // Fallback for missing weights
+ * const fallback = getFontUrl(font, 900); // Falls back to regular/400 if 900 missing
+ * ```
  */
 export function getFontUrl(font: UnifiedFont, weight: number): string | undefined {
     if (!SIZES.includes(weight)) {
@@ -18,12 +36,11 @@ export function getFontUrl(font: UnifiedFont, weight: number): string | undefine
 
     const weightKey = weight.toString() as FontWeight;
 
-    // 1. Try exact match (Backend now maps "100".."900" to VF URL if variable)
+    // Try exact match (backend maps weight to VF URL for variable fonts)
     if (font.styles.variants?.[weightKey]) {
         return font.styles.variants[weightKey];
     }
 
-    // 2. Fallbacks for Static Fonts (if exact weight missing)
-    // Try 'regular' or '400' as safe defaults
+    // Fallbacks for static fonts when exact weight is missing
     return font.styles.regular || font.styles.variants?.['400'] || font.styles.variants?.['regular'];
 }