mostly filebased Content Presentation System

214 lines
4.8KB

  1. /// Validation
  2. /// ==========
  3. /// Each argument to Su has a single canonical syntax.
  4. /// These validation functions check to ensure
  5. /// that each argument is valid,
  6. /// in order to provide useful errors
  7. /// before attempting to calculate the results/
  8. ///
  9. /// @group _validation
  10. ///
  11. /// @see su-valid-columns
  12. /// @see su-valid-gutters
  13. /// @see su-valid-spread
  14. /// @see su-valid-location
  15. // Valid Span
  16. // ----------
  17. /// Check that the `span` argument
  18. /// is a number, length, or column-list
  19. ///
  20. /// @group _validation
  21. ///
  22. /// @param {number | list} $span -
  23. /// Number of columns, or length of span
  24. ///
  25. /// @return {number | list} -
  26. /// Validated `$span` number, length, or columns list
  27. ///
  28. /// @throw
  29. /// when span value is not a number, or valid column list
  30. @function su-valid-span(
  31. $span
  32. ) {
  33. $type: type-of($span);
  34. @if ($type == 'number') {
  35. @return $span;
  36. } @else if ($type == 'list') and su-valid-columns($span, 'silent-failure') {
  37. @return $span;
  38. }
  39. $actual: '[#{type-of($span)}] `#{inspect($span)}`';
  40. @return _susy-error(
  41. '#{$actual} is not a valid number, length, or column-list for $span.',
  42. 'su-valid-span');
  43. }
  44. // Valid Columns
  45. // -------------
  46. /// Check that the `columns` argument is a valid
  47. /// list of column-lengths
  48. ///
  49. /// @group _validation
  50. ///
  51. /// @param {list} $columns -
  52. /// List of column-lengths
  53. /// @param {bool} $silent-failure [true] -
  54. /// Set false to return null on failure
  55. ///
  56. /// @return {list} -
  57. /// Validated `$columns` list
  58. ///
  59. /// @throw
  60. /// when column value is not a valid list of numbers
  61. @function su-valid-columns(
  62. $columns,
  63. $silent-failure: false
  64. ) {
  65. @if (type-of($columns) == 'list') {
  66. $fail: false;
  67. @each $col in $columns {
  68. @if (type-of($col) != 'number') {
  69. $fail: true;
  70. }
  71. }
  72. @if not $fail {
  73. @return $columns;
  74. }
  75. }
  76. // Silent Failure
  77. @if $silent-failure {
  78. @return null;
  79. }
  80. // Error Message
  81. $actual: '[#{type-of($columns)}] `#{inspect($columns)}`';
  82. @return _susy-error(
  83. '#{$actual} is not a valid list of numbers for $columns.',
  84. 'su-valid-columns');
  85. }
  86. // Valid Gutters
  87. // -------------
  88. /// Check that the `gutters` argument is a valid number
  89. ///
  90. /// @group _validation
  91. ///
  92. /// @param {number} $gutters -
  93. /// Width of a gutter
  94. ///
  95. /// @return {number} -
  96. /// Validated `$gutters` number
  97. ///
  98. /// @throw
  99. /// when gutter value is not a number
  100. @function su-valid-gutters(
  101. $gutters
  102. ) {
  103. $type: type-of($gutters);
  104. @if ($type == 'number') {
  105. @return $gutters;
  106. }
  107. $actual: '[#{$type}] `#{inspect($gutters)}`';
  108. @return _susy-error(
  109. '#{$actual} is not a number or length for $gutters.',
  110. 'su-valid-gutters');
  111. }
  112. // Valid Spread
  113. // ------------
  114. /// Check that the `spread` argument is a valid
  115. /// intiger between `-1` and `1`
  116. ///
  117. /// @group _validation
  118. ///
  119. /// @param {0 | 1 | -1} $spread -
  120. /// Number of gutters to include in a span,
  121. /// relative to the number columns
  122. ///
  123. /// @return {0 | 1 | -1} -
  124. /// Validated `$spread` number
  125. ///
  126. /// @throw
  127. /// when spread value is not a valid spread
  128. @function su-valid-spread(
  129. $spread
  130. ) {
  131. @if index(0 1 -1, $spread) {
  132. @return $spread;
  133. }
  134. $actual: '[#{type-of($spread)}] `#{inspect($spread)}`';
  135. @return _susy-error(
  136. '#{$actual} is not a normalized [0 | 1 | -1] value for `$spread`.',
  137. 'su-valid-spread');
  138. }
  139. // Valid Location
  140. // --------------
  141. /// Check that the `location` argument is a valid number,
  142. /// within the scope of available columns
  143. ///
  144. /// @group _validation
  145. ///
  146. /// @param {number} $span -
  147. /// Number of grid-columns to be spanned
  148. /// @param {integer | string} $location -
  149. /// Starting (1-indexed) column-position of that span
  150. /// @param {list} $columns -
  151. /// List of available columns in the grid
  152. ///
  153. /// @return {integer} -
  154. /// Validated `$location` intiger
  155. ///
  156. /// @throw
  157. /// when location value is not a valid index,
  158. /// given the context and span.
  159. @function su-valid-location(
  160. $span,
  161. $location,
  162. $columns
  163. ) {
  164. $count: length($columns);
  165. @if $location {
  166. @if (type-of($location) != 'number') or (not unitless($location)) {
  167. $actual: '[#{type-of($location)}] `#{$location}`';
  168. @return _susy-error(
  169. '#{$actual} is not a unitless number for $location.',
  170. 'su-valid-location');
  171. } @else if (round($location) != $location) {
  172. @return _susy-error(
  173. 'Location (`#{$location}`) must be a 1-indexed intiger position.',
  174. 'su-valid-location');
  175. } @else if ($location > $count) or ($location < 1) {
  176. @return _susy-error(
  177. 'Position `#{$location}` does not exist in grid `#{$columns}`.',
  178. 'su-valid-location');
  179. } @else if ($location + $span - 1 > $count) {
  180. $details: 'grid `#{$columns}` for span `#{$span}` at `#{$location}`';
  181. @return _susy-error(
  182. 'There are not enough columns in #{$details}.',
  183. 'su-valid-location');
  184. }
  185. }
  186. @return $location;
  187. }