////
/// Internsal functions and mixing for setting up `@font-face` declariations.
///
/// @group typography
/// @access private
////


/// Takes a list of local font names and formats them into
/// a list like: `local("name 1"), local("name 2"), ...`
///
/// This is intended for `@font-face` declarations, where we may need to specify
/// one or more `local()` names for a font.
///
/// Refer to te `grav-font-face()` mixin's documentation for more info on where
/// to find the local font names.
///
/// @param {list | string} $local-names - (List of) local font name(s).
///
@function grav-format-local-names($local-names) {
  $output: local('#{nth($local-names, 1)}');

  @for $i from 2 to length($local-names)+1 {
    $output: $output,
    local('#{nth($local-names, $i)}');
  }

  @return $output;
}

/// Generates an `@font-face` declaration.
///
/// Used internally by Gravity to generate all necessary `@font-face` declarations.
///
/// Intentionally only uses WOFF2 and WOFF formats. This has sufficiently broad browser support,
/// so there's little point bloating our CSS with additional EOT or TTF sources.
///
/// You can find a font file's local name in macOS by opening the "Font Book" app, selecting the
/// font you're after and clicking the 'i' (info) button in the toolbar. The "PostScript name" is
/// the value you're after.
///
/// `$src-path` may be an absolute or relative URL path and should exclude the trailing slash.
///
/// See:
/// - https://css-tricks.com/snippets/css/using-font-face/
/// - https://stackoverflow.com/a/18134406
///
/// @param {string} $font-family - The font family name,
///     which can later be used in `font-family` CSS rules to use this font.
/// @param {string} $font-weight - The CSS `font-weight` value that these font files are for.
/// @param {string} $font-style - The CSS `font-style` value that these font files are for.
/// @param {string} $src-path - The URL path to the directory containing the font files
///     (excluding a trailing slash).
/// @param {string} $src-basename - The base filename (excluding the file extension) shared by
///     `.woff2` and `.woff` font files that will be referenced.
/// @param {list | string} $local-names - (List of) local font name(s).
@mixin grav-font-face($font-family, $font-weight, $font-style, $src-path, $src-basename, $local-names) {
  @font-face {
    font-family: '#{$font-family}';
    font-style: $font-style;
    font-weight: $font-weight;
    src: grav-format-local-names($local-names),
    url('#{$src-path}/#{$src-basename}.woff2') format('woff2'),
    url('#{$src-path}/#{$src-basename}.woff') format('woff');
  }
}