mostly filebased Content Presentation System

330 líneas
10KB

  1. /// Susy3 Configuration
  2. /// ===================
  3. /// Susy3 has 4 core settings, in a single settings map.
  4. /// You'll notice a few differences from Susy2:
  5. ///
  6. /// **Columns** no longer accept a single number, like `12`,
  7. /// but use a syntax more similar to the new
  8. /// CSS [grid-template-columns][columns] –
  9. /// a list of relative sizes for each column on the grid.
  10. /// Unitless numbers in Susy act very similar to `fr` units in CSS,
  11. /// and the `susy-repeat()` function (similar to the css `repeat()`)
  12. /// helps quickly establish equal-width columns.
  13. ///
  14. /// [columns]: https://developer.mozilla.org/en-US/docs/Web/CSS/grid-template-columns
  15. ///
  16. /// - `susy-repeat(12)` will create 12 fluid, equal-width columns
  17. /// - `susy-repeat(6, 120px)` will create 6 equal `120px`-wide columns
  18. /// - `120px susy-repeat(4) 120px` will create 6 columns,
  19. /// the first and last are `120px`,
  20. /// while the middle 4 are equal fractions of the remainder.
  21. /// Susy will output `calc()` values in order to achieve this.
  22. ///
  23. /// **Gutters** haven't changed –
  24. /// a single fraction or explicit width –
  25. /// but the `calc()` output feature
  26. /// means you can now use any combination of units and fractions
  27. /// to create static-gutters on a fluid grid, etc.
  28. ///
  29. /// **Spread** existed in the Susy2 API as a span option,
  30. /// and was otherwise handled behind the scenes.
  31. /// Now we're giving you full control over all spread issues.
  32. /// You can find a more [detailed explanation of spread on the blog][spread].
  33. ///
  34. /// [spread]: http://oddbird.net/2017/06/13/susy-spread/
  35. ///
  36. /// You can access your global settings at any time
  37. /// with the `susy-settings()` function,
  38. /// or grab a single setting from the global scope
  39. /// with `susy-get('columns')`, `susy-get('gutters')` etc.
  40. ///
  41. /// @group config
  42. /// @link http://oddbird.net/2017/06/13/susy-spread/
  43. /// Article: Understanding Spread in Susy3
  44. ///
  45. /// @see $susy
  46. /// @see susy-settings
  47. /// @see susy-get
  48. // Susy
  49. // ----
  50. /// The grid is defined in a single map variable,
  51. /// with four initial properties:
  52. /// `columns`, `gutters`, `spread` and `container-spread`.
  53. /// Anything you put in the root `$susy` variable map
  54. /// will be treated as a global project default.
  55. /// You can create similar configuration maps
  56. /// under different variable names,
  57. /// to override the defaults as-needed.
  58. ///
  59. /// @group config
  60. /// @type Map
  61. ///
  62. /// @see $_susy-defaults
  63. /// @see {function} susy-repeat
  64. /// @link
  65. /// https://codepen.io/mirisuzanne/pen/EgmJJp?editors=1100
  66. /// Spread examples on CodePen
  67. ///
  68. /// @prop {list} columns -
  69. /// Columns are described by a list of numbers,
  70. /// representing the relative width of each column.
  71. /// The syntax is a simplified version of CSS native
  72. /// `grid-template-columns`,
  73. /// expecting a list of grid-column widths.
  74. /// Unitless numbers create fractional fluid columns
  75. /// (similar to the CSS-native `fr` unit),
  76. /// while length values (united numbers)
  77. /// are used to define static columns.
  78. /// You can mix-and match units and fractions,
  79. /// to create a mixed grid.
  80. /// Susy will generate `calc()` values when necessary,
  81. /// to make all your units work together.
  82. ///
  83. /// Use the `susy-repeat($count, $value)` function
  84. /// to more easily repetative columns,
  85. /// similar to the CSS-native `repeat()`.
  86. ///
  87. /// - `susy-repeat(8)`:
  88. /// an 8-column, symmetrical, fluid grid.
  89. /// <br />Identical to `(1 1 1 1 1 1 1 1)`.
  90. /// - `susy-repeat(6, 8em)`:
  91. /// a 6-column, symmetrical, em-based grid.
  92. /// <br />Identical to `(8em 8em 8em 8em 8em 8em)`.
  93. /// - `(300px susy-repeat(4) 300px)`:
  94. /// a 6-column, asymmetrical, mixed fluid/static grid
  95. /// using `calc()` output.
  96. /// <br />Identical to `(300px 1 1 1 1 300px)`.
  97. ///
  98. /// **NOTE** that `12` is no longer a valid 12-column grid definition,
  99. /// and you must list all the columns individually
  100. /// (or by using the `susy-repeat()` function).
  101. ///
  102. /// @prop {number} gutters -
  103. /// Gutters are defined as a single width,
  104. /// or fluid ratio, similar to the native-CSS
  105. /// `grid-column-gap` syntax.
  106. /// Similar to columns,
  107. /// gutters can use any valid CSS length unit,
  108. /// or unitless numbers to define a relative fraction.
  109. ///
  110. /// - `0.5`:
  111. /// a fluid gutter, half the size of a single-fraction column.
  112. /// - `1em`:
  113. /// a static gutter, `1em` wide.
  114. ///
  115. /// Mix static gutters with fluid columns, or vice versa,
  116. /// and Susy will generate the required `calc()` to make it work.
  117. ///
  118. /// @prop {string} spread [narrow] -
  119. /// Spread of an element across adjacent gutters:
  120. /// either `narrow` (none), `wide` (one), or `wider` (two)
  121. ///
  122. /// - Both spread settings default to `narrow`,
  123. /// the most common use-case.
  124. /// A `narrow` spread only has gutters *between* columns
  125. /// (one less gutter than columns).
  126. /// This is how all css-native grids work,
  127. /// and most margin-based grid systems.
  128. /// - A `wide` spread includes the same number of gutters as columns,
  129. /// spanning across a single side-gutter.
  130. /// This is how most padding-based grid systems often work,
  131. /// and is also useful for pushing and pulling elements into place.
  132. /// - The rare `wider` spread includes gutters
  133. /// on both sides of the column-span
  134. /// (one more gutters than columns).
  135. ///
  136. /// @prop {string} container-spread [narrow] -
  137. /// Spread of a container around adjacent gutters:
  138. /// either `narrow` (none), `wide` (one), or `wider` (two).
  139. /// See `spread` property for details.
  140. ///
  141. /// @since 3.0.0-beta.1 -
  142. /// `columns` setting no longer accepts numbers
  143. /// (e.g. `12`) for symmetrical fluid grids,
  144. /// or the initial `12 x 120px` syntax for
  145. /// symmetrical fixed-unit grids.
  146. /// Use `susy-repeat(12)` or `susy-repeat(12, 120px)` instead.
  147. ///
  148. /// @example scss - default values
  149. /// // 4 symmetrical, fluid columns
  150. /// // gutters are 1/4 the size of a column
  151. /// // elements span 1 less gutter than columns
  152. /// // containers span 1 less gutter as well
  153. /// $susy: (
  154. /// 'columns': susy-repeat(4),
  155. /// 'gutters': 0.25,
  156. /// 'spread': 'narrow',
  157. /// 'container-spread': 'narrow',
  158. /// );
  159. ///
  160. /// @example scss - inside-static gutters
  161. /// // 6 symmetrical, fluid columns…
  162. /// // gutters are static, triggering calc()…
  163. /// // elements span equal columns & gutters…
  164. /// // containers span equal columns & gutters…
  165. /// $susy: (
  166. /// 'columns': susy-repeat(6),
  167. /// 'gutters': 0.5em,
  168. /// 'spread': 'wide',
  169. /// 'container-spread': 'wide',
  170. /// );
  171. $susy: () !default;
  172. // Susy Repeat
  173. // -----------
  174. /// Similar to the `repeat(<count>, <value>)` function
  175. /// that is available in native CSS Grid templates,
  176. /// the `susy-repeat()` function helps generate repetative layouts
  177. /// by repeating any value a given number of times.
  178. /// Where Susy previously allowed `8` as a column definition
  179. /// for 8 equal columns, you should now use `susy-repeat(8)`.
  180. ///
  181. /// @group config
  182. ///
  183. /// @param {integer} $count -
  184. /// The number of repetitions, e.g. `12` for a 12-column grid.
  185. /// @param {*} $value [1] -
  186. /// The value to be repeated.
  187. /// Technically any value can be repeated here,
  188. /// but the function exists to repeat column-width descriptions:
  189. /// e.g. the default `1` for single-fraction fluid columns,
  190. /// `5em` for a static column,
  191. /// or even `5em 120px` if you are alternating column widths.
  192. ///
  193. /// @return {list} -
  194. /// List of repeated values
  195. ///
  196. /// @example scss
  197. /// // 12 column grid, with 5em columns
  198. /// $susy: (
  199. /// columns: susy-repeat(12, 5em),
  200. /// );
  201. ///
  202. /// @example scss
  203. /// // asymmetrical 5-column grid
  204. /// $susy: (
  205. /// columns: 20px susy-repeat(3, 100px) 20px,
  206. /// );
  207. ///
  208. /// /* result: #{susy-get('columns')} */
  209. @function susy-repeat(
  210. $count,
  211. $value: 1
  212. ) {
  213. $return: ();
  214. @for $i from 1 through $count {
  215. $return: join($return, $value);
  216. }
  217. @return $return;
  218. }
  219. // Susy Defaults
  220. // -------------
  221. /// Configuration map of Susy factory defaults.
  222. /// Do not override this map directly –
  223. /// use `$susy` for user and project setting overrides.
  224. ///
  225. /// @access private
  226. /// @type Map
  227. ///
  228. /// @see $susy
  229. ///
  230. /// @prop {number | list} columns [susy-repeat(4)]
  231. /// @prop {number} gutters [0.25]
  232. /// @prop {string} spread ['narrow']
  233. /// @prop {string} container-spread ['narrow']
  234. $_susy-defaults: (
  235. 'columns': susy-repeat(4),
  236. 'gutters': 0.25,
  237. 'spread': 'narrow',
  238. 'container-spread': 'narrow',
  239. );
  240. // Susy Settings
  241. // -------------
  242. /// Return a combined map of Susy settings,
  243. /// based on the factory defaults (`$_susy-defaults`),
  244. /// user-defined project configuration (`$susy`),
  245. /// and any local overrides required –
  246. /// such as a configuration map passed into a function.
  247. ///
  248. /// @group config
  249. ///
  250. /// @param {maps} $overrides… -
  251. /// Optional map override of global configuration settings.
  252. /// See `$susy` above for properties.
  253. ///
  254. /// @return {map} -
  255. /// Combined map of Susy configuration settings,
  256. /// in order of specificity:
  257. /// any `$overrides...`,
  258. /// then `$susy` project settings,
  259. /// and finally the `$_susy-defaults`
  260. ///
  261. /// @example scss - global settings
  262. /// @each $key, $value in susy-settings() {
  263. /// /* #{$key}: #{$value} */
  264. /// }
  265. ///
  266. /// @example scss - local settings
  267. /// $local: ('columns': 1 2 3 5 8);
  268. ///
  269. /// @each $key, $value in susy-settings($local) {
  270. /// /* #{$key}: #{$value} */
  271. /// }
  272. @function susy-settings(
  273. $overrides...
  274. ) {
  275. $settings: map-merge($_susy-defaults, $susy);
  276. @each $config in $overrides {
  277. $settings: map-merge($settings, $config);
  278. }
  279. @return $settings;
  280. }
  281. // Susy Get
  282. // --------
  283. /// Return the current global value of any Susy setting
  284. ///
  285. /// @group config
  286. ///
  287. /// @param {string} $key -
  288. /// Setting to retrieve from the configuration.
  289. ///
  290. /// @return {*} -
  291. /// Value mapped to `$key` in the configuration maps,
  292. /// in order of specificity:
  293. /// `$susy`, then `$_susy-defaults`
  294. ///
  295. /// @example scss -
  296. /// /* columns: #{susy-get('columns')} */
  297. /// /* gutters: #{susy-get('gutters')} */
  298. @function susy-get(
  299. $key
  300. ) {
  301. $settings: susy-settings();
  302. @if not map-has-key($settings, $key) {
  303. @return _susy-error(
  304. 'There is no Susy setting called `#{$key}`',
  305. 'susy-get');
  306. }
  307. @return map-get($settings, $key);
  308. }