// JSON Export Utilities
// ---------------------

@use 'json-encode' as json;

/// # Exporting Styles to JSON
///
/// While many UX patterns will be rendered as HTML components,
/// there are several abstract style patterns --
/// like color-palettes and font-specimens --
/// that never appear as components in the application.
///
/// Herman provides several annotations
/// to help visualize these abstract patterns,
/// but they require access to the raw Sass data.
/// We do that using Sass maps
/// (`key:value` object variables)
/// and the `export` mixin
/// to generate JSON out of Sass variables.
///
/// See the [`sass.jsonFile` configuration][json]
/// to ensure that Herman has access
/// to your exported Sass data.
///
/// [json]: https://www.oddbird.net/herman/docs/configuration#sass-jsonfile
///
/// @group api_json-export
/// @see export
///
/// @example scss
///   // To import from Herman installed via npm,
///   // replace the following 'utilities' import with:
///   // @use 'pkg:sassdoc-theme-herman' as herman;
///   @use 'utilities' as herman;
///
///   herman.$herman: (
///     'colors': (
///       'brand-colors': (
///         'brand-orange': #c75000,
///         'brand-blue': #0d7fa5,
///       ),
///     ),
///   );
///
///   @include herman.export(herman.$herman);

// Herman
// ------
/// Use the `$herman` map variable to collect and organize
/// color, font, size, and ratio values for export.
///
/// The `$herman` map should be structured
/// with top-level keys for each type of data,
/// and nested maps of the individual items to preview.
/// Use the `add` mixin to automatically populate
/// fonts, colors, sizes, and ratios from existing maps --
/// or construct your `$herman` map by hand,
/// following these guidelines...
///
/// ### Map structure
///
/// Each type of preview value should be nested
/// under a key that describes what type of data is being stored:
///
/// ```scss
/// $herman: (
///   'colors': (
///     /* color maps */
///   ),
///   'sizes': (
///     /* size maps */
///   ),
///   'ratios': (
///     /* ratio maps */
///   ),
///   'fonts': (
///     /* font maps */
///   ),
/// );
/// ```
///
/// ### Colors
///
/// Each color has an access name and value.
/// The key will be used to identify the correct data
/// for a given color-palette,
/// and the data includes color `name:value` pairs,
/// both in string format.
///
/// ```scss
/// 'brand-colors': (
///   'brand-orange': #c75000,
///   'brand-blue': #0d7fa5,
/// )
/// ```
///
/// Color values can be in any valid web-color format --
/// hex, hsl/a, rgba/a, etc.
///
/// ### Sizes & Ratios
///
/// Size and ratio data is similar to colors,
/// organized into top-level groups that may contain
/// one or more `name:value` pairs:
///
/// ```scss
/// 'font-ratios': (
///   'line-height': 1.4,
///   'minor-seventh': 16/9,
/// ),
/// 'text-sizes': (
///   'root': 18px,
///   'large': calc(1rem + 1.5vw),
/// )
/// ```
///
/// Ratio values can be in any valid number,
/// and size values should be valid CSS lengths.
///
/// ### Fonts
///
/// Each font should have a top-level key of its own,
/// since font-previews display a single font at a time.
/// The data map accepts:
///
/// - `name`: how the font should be referenced in CSS
///   (if omitted, defaults to top-level key)
/// - `stack`: optional string or list of font-stack fallbacks
/// - `source`: link to more information on the font,
///    or typekit/googlefonts as useful
/// - `formats`: font format (or space-separated list of font formats)
///   for locally-hosted fonts -- valid format options are
///   `ttf`, `otf`, `woff`, `woff2`, `svg`, `svgz`, and `eot`
/// - `<variant>`: describe any number of relative paths to locally-hosted
///   font-files, or embedded `data:...` font strings
///   per variant (e.g. `normal`, `bold italic`, etc.).
///   Multi-word variants can be space-separated or comma-separated
///   (e.g. `bold italic` or `bold, italic` or `bold,italic`),
///   and non-standard variants are also accepted
///   (e.g. `extra-bold`, `thin`, `light`, etc.).
///   Optionally, the value can also be a nested object
///   with the following variant-specific keys:
///   - `path`: variant-specific relative path to locally-hosted font-files
///   - `local`: font name (or space-separated list of font names)
///     used to look for local user fonts
///   - `svgid`: optional suffix value for local SVG font `src`,
///     e.g. `font-file.svg#svgid` (if omitted, defaults to `name`)
///   - `<format>`: describe any number of relative paths to locally-hosted
///     font-files, or embedded `data:...` font strings
///     per format (e.g. `ttf`, `otf`, `woff2`, etc.)
///
///
/// ```scss
/// 'body-font': (
///   'name': 'Source Sans 3',
///   'stack': ('Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif'),
///   'formats': 'woff' 'woff2' 'ttf',
///   'normal': 'sans/sourcesans3-regular-webfont',
///   'italic': 'sans/sourcesans3-italic-webfont',
///   'bold': (
///     'path': 'sans/sourcesans3-bold-webfont',
///     'local': 'source-sans-3-bold',
///     'ttf': 'sans-ttf/sourcesans3-bold-webfont',
///     'woff': 'data:application/x-font-woff;charset=utf-8;base64...',
///   ),
/// )
/// ```
///
/// @group api_json-export
///
/// @example scss - sample map structure
///   // To import from Herman installed via npm,
///   // replace the following 'utilities' import with:
///   // @use 'pkg:sassdoc-theme-herman' as herman;
///   @use 'utilities' as herman;
///
///   herman.$herman: (
///     'colors': (
///       'brand-colors': (
///         'brand-orange': '#c75000',
///         'brand-blue': '#0d7fa5',
///       ),
///       'status-colors': (
///         'go': '#657e1b',
///         'yield': '#c75000',
///       ),
///     ),
///     'fonts': (
///       'body-font': (
///         'name': 'Source Sans 3',
///         'stack': ('Helvetica Neue', 'Helvetica', 'Arial', 'sans-serif'),
///         'formats': 'woff' 'woff2' 'ttf',
///         'normal': 'sans/sourcesans3-regular-webfont',
///         'italic': 'sans/sourcesans3-italic-webfont',
///         'bold': (
///           'path': 'sans/sourcesans3-bold-webfont',
///           'local': 'source-sans-3-bold',
///           'ttf': 'sans-ttf/sourcesans3-bold-webfont',
///           'woff': 'data:application/x-font-woff;charset=utf-8;base64...',
///         ),
///       ),
///     ),
///     'sizes': (
///       'text-sizes': (
///         'root': '18px',
///         'large': 'calc(1rem + 1.5vw)',
///       ),
///     ),
///   );
$herman: () !default;

// Herman Export
// -------------
/// Encode a Sass map as a JSON-ready string,
/// and print to CSS output as a persistent comment.
///
/// @group api_json-export
/// @since 4.0.0 Name changed from `herman-export`
///
/// @param {map} $map [$herman] -
///   Map to be encoded for JSON exporting
///
/// @example scss
///   // To import from Herman installed via npm,
///   // replace the following 'utilities' import with:
///   // @use 'pkg:sassdoc-theme-herman' as herman;
///   @use 'utilities' as herman;
///
///   // Export to JSON
///   @include herman.export;
@mixin export($map: $herman) {
  /*! json-encode: #{json.encode($map)} */
}