oneflow-jekyll 1.0

data/_sass/oneflow/vendor/susy/susy/_settings.scss

@@ -0,0 +1,329 @@
+/// Susy3 Configuration
+/// ===================
+/// Susy3 has 4 core settings, in a single settings map.
+/// You'll notice a few differences from Susy2:
+///
+/// **Columns** no longer accept a single number, like `12`,
+/// but use a syntax more similar to the new
+/// CSS [grid-template-columns][columns] –
+/// a list of relative sizes for each column on the grid.
+/// Unitless numbers in Susy act very similar to `fr` units in CSS,
+/// and the `susy-repeat()` function (similar to the css `repeat()`)
+/// helps quickly establish equal-width columns.
+///
+/// [columns]: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns
+///
+/// - `susy-repeat(12)` will create 12 fluid, equal-width columns
+/// - `susy-repeat(6, 120px)` will create 6 equal `120px`-wide columns
+/// - `120px susy-repeat(4) 120px` will create 6 columns,
+///   the first and last are `120px`,
+///   while the middle 4 are equal fractions of the remainder.
+///   Susy will output `calc()` values in order to achieve this.
+///
+/// **Gutters** haven't changed –
+/// a single fraction or explicit width –
+/// but the `calc()` output feature
+/// means you can now use any combination of units and fractions
+/// to create static-gutters on a fluid grid, etc.
+///
+/// **Spread** existed in the Susy2 API as a span option,
+/// and was otherwise handled behind the scenes.
+/// Now we're giving you full control over all spread issues.
+/// You can find a more [detailed explanation of spread on the blog][spread].
+///
+/// [spread]: http://oddbird.net/2017/06/13/susy-spread/
+///
+/// You can access your global settings at any time
+/// with the `susy-settings()` function,
+/// or grab a single setting from the global scope
+/// with `susy-get('columns')`, `susy-get('gutters')` etc.
+///
+/// @group a-config
+/// @link http://oddbird.net/2017/06/13/susy-spread/
+///   Article: Understanding Spread in Susy3
+///
+/// @see $susy
+/// @see susy-settings
+/// @see susy-get
+
+
+
+// Susy
+// ----
+/// The grid is defined in a single map variable,
+/// with four initial properties:
+/// `columns`, `gutters`, `spread` and `container-spread`.
+/// Anything you put in the root `$susy` variable map
+/// will be treated as a global project default.
+/// You can create similar configuration maps
+/// under different variable names,
+/// to override the defaults as-needed.
+///
+/// @group a-config
+/// @type Map
+///
+/// @see $_susy-defaults
+/// @see {function} susy-repeat
+/// @link
+///   https://codepen.io/mirisuzanne/pen/EgmJJp?editors=1100
+///   Spread examples on CodePen
+///
+/// @prop {list} columns -
+///   Columns are described by a list of numbers,
+///   representing the relative width of each column.
+///   The syntax is a simplified version of CSS native
+///   `grid-template-columns`,
+///   expecting a list of grid-column widths.
+///   Unitless numbers create fractional fluid columns
+///   (similar to the CSS-native `fr` unit),
+///   while length values (united numbers)
+///   are used to define static columns.
+///   You can mix-and match units and fractions,
+///   to create a mixed grid.
+///   Susy will generate `calc()` values when necessary,
+///   to make all your units work together.
+///
+///   Use the `susy-repeat($count, $value)` function
+///   to more easily repetative columns,
+///   similar to the CSS-native `repeat()`.
+///
+///   - `susy-repeat(8)`:
+///     an 8-column, symmetrical, fluid grid.
+///     <br />Identical to `(1 1 1 1 1 1 1 1)`.
+///   - `susy-repeat(6, 8em)`:
+///     a 6-column, symmetrical, em-based grid.
+///     <br />Identical to `(8em 8em 8em 8em 8em 8em)`.
+///   - `(300px susy-repeat(4) 300px)`:
+///     a 6-column, asymmetrical, mixed fluid/static grid
+///     using `calc()` output.
+///     <br />Identical to `(300px 1 1 1 1 300px)`.
+///
+///   **NOTE** that `12` is no longer a valid 12-column grid definition,
+///   and you must list all the columns individually
+///   (or by using the `susy-repeat()` function).
+///
+/// @prop {number} gutters -
+///   Gutters are defined as a single width,
+///   or fluid ratio, similar to the native-CSS
+///   `grid-column-gap` syntax.
+///   Similar to columns,
+///   gutters can use any valid CSS length unit,
+///   or unitless numbers to define a relative fraction.
+///
+///   - `0.5`:
+///     a fluid gutter, half the size of a single-fraction column.
+///   - `1em`:
+///     a static gutter, `1em` wide.
+///
+///   Mix static gutters with fluid columns, or vice versa,
+///   and Susy will generate the required `calc()` to make it work.
+///
+/// @prop {string} spread [narrow] -
+///   Spread of an element across adjacent gutters:
+///   either `narrow` (none), `wide` (one), or `wider` (two)
+///
+///   - Both spread settings default to `narrow`,
+///     the most common use-case.
+///     A `narrow` spread only has gutters *between* columns
+///     (one less gutter than columns).
+///     This is how all css-native grids work,
+///     and most margin-based grid systems.
+///   - A `wide` spread includes the same number of gutters as columns,
+///     spanning across a single side-gutter.
+///     This is how most padding-based grid systems often work,
+///     and is also useful for pushing and pulling elements into place.
+///   - The rare `wider` spread includes gutters
+///     on both sides of the column-span
+///     (one more gutters than columns).
+///
+/// @prop {string} container-spread [narrow] -
+///   Spread of a container around adjacent gutters:
+///   either `narrow` (none), `wide` (one), or `wider` (two).
+///   See `spread` property for details.
+///
+/// @since 3.0.0-beta.1 -
+///   `columns` setting no longer accepts numbers
+///   (e.g. `12`) for symmetrical fluid grids,
+///   or the initial `12 x 120px` syntax for
+///   symmetrical fixed-unit grids.
+///   Use `susy-repeat(12)` or `susy-repeat(12, 120px)` instead.
+///
+/// @example scss - default values
+///   // 4 symmetrical, fluid columns
+///   // gutters are 1/4 the size of a column
+///   // elements span 1 less gutter than columns
+///   // containers span 1 less gutter as well
+///   $susy: (
+///     'columns': susy-repeat(4),
+///     'gutters': 0.25,
+///     'spread': 'narrow',
+///     'container-spread': 'narrow',
+///   );
+///
+/// @example scss - inside-static gutters
+///   // 6 symmetrical, fluid columns…
+///   // gutters are static, triggering calc()…
+///   // elements span equal columns & gutters…
+///   // containers span equal columns & gutters…
+///   $susy: (
+///     'columns': susy-repeat(6),
+///     'gutters': 0.5em,
+///     'spread': 'wide',
+///     'container-spread': 'wide',
+///   );
+$susy: () !default;
+
+
+
+// Susy Repeat
+// -----------
+/// Similar to the `repeat(<count>, <value>)` function
+/// that is available in native CSS Grid templates,
+/// the `susy-repeat()` function helps generate repetative layouts
+/// by repeating any value a given number of times.
+/// Where Susy previously allowed `8` as a column definition
+/// for 8 equal columns, you should now use `susy-repeat(8)`.
+///
+/// @group a-config
+///
+/// @param {integer} $count -
+///   The number of repetitions, e.g. `12` for a 12-column grid.
+/// @param {*} $value [1] -
+///   The value to be repeated.
+///   Technically any value can be repeated here,
+///   but the function exists to repeat column-width descriptions:
+///   e.g. the default `1` for single-fraction fluid columns,
+///   `5em` for a static column,
+///   or even `5em 120px` if you are alternating column widths.
+///
+/// @return {list} -
+///   List of repeated values
+///
+/// @example scss
+///   // 12 column grid, with 5em columns
+///   $susy: (
+///     columns: susy-repeat(12, 5em),
+///   );
+///
+/// @example scss
+///   // asymmetrical 5-column grid
+///   $susy: (
+///     columns: 20px susy-repeat(3, 100px) 20px,
+///   );
+///
+///   /* result: #{susy-get('columns')} */
+@function susy-repeat(
+  $count,
+  $value: 1
+) {
+  $return: ();
+
+  @for $i from 1 through $count {
+    $return: join($return, $value);
+  }
+
+  @return $return;
+}
+
+
+
+// Susy Defaults
+// -------------
+/// Configuration map of Susy factory defaults.
+/// Do not override this map directly –
+/// use `$susy` for user and project setting overrides.
+///
+/// @access private
+/// @type Map
+///
+/// @see $susy
+///
+/// @prop {number | list} columns [susy-repeat(4)]
+/// @prop {number} gutters [0.25]
+/// @prop {string} spread ['narrow']
+/// @prop {string} container-spread ['narrow']
+$_susy-defaults: (
+  'columns': susy-repeat(4),
+  'gutters': 0.25,
+  'spread': 'narrow',
+  'container-spread': 'narrow',
+);
+
+
+
+// Susy Settings
+// -------------
+/// Return a combined map of Susy settings,
+/// based on the factory defaults (`$_susy-defaults`),
+/// user-defined project configuration (`$susy`),
+/// and any local overrides required –
+/// such as a configuration map passed into a function.
+///
+/// @group a-config
+///
+/// @param {maps} $overrides… -
+///   Optional map override of global configuration settings.
+///   See `$susy` above for properties.
+///
+/// @return {map} -
+///   Combined map of Susy configuration settings,
+///   in order of specificity:
+///   any `$overrides...`,
+///   then `$susy` project settings,
+///   and finally the `$_susy-defaults`
+///
+/// @example scss - global settings
+///   @each $key, $value in susy-settings() {
+///     /* #{$key}: #{$value} */
+///   }
+///
+/// @example scss - local settings
+///   $local: ('columns': 1 2 3 5 8);
+///
+///   @each $key, $value in susy-settings($local) {
+///     /* #{$key}: #{$value} */
+///   }
+@function susy-settings(
+  $overrides...
+) {
+  $settings: map-merge($_susy-defaults, $susy);
+
+  @each $config in $overrides {
+    $settings: map-merge($settings, $config);
+  }
+
+  @return $settings;
+}
+
+
+
+// Susy Get
+// --------
+/// Return the current global value of any Susy setting
+///
+/// @group a-config
+///
+/// @param {string} $key -
+///   Setting to retrieve from the configuration.
+///
+/// @return {*} -
+///   Value mapped to `$key` in the configuration maps,
+///   in order of specificity:
+///   `$susy`, then `$_susy-defaults`
+///
+/// @example scss -
+///   /* columns: #{susy-get('columns')} */
+///   /* gutters: #{susy-get('gutters')} */
+@function susy-get(
+  $key
+) {
+  $settings: susy-settings();
+
+  @if not map-has-key($settings, $key) {
+    @return _susy-error(
+      'There is no Susy setting called `#{$key}`',
+      'susy-get');
+  }
+
+  @return map-get($settings, $key);
+}