forked from oddbird/susy
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathx-normal.html
1 lines (1 loc) · 18.8 KB
/
x-normal.html
1
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>susy Documentation</title><link href="assets/img/favicon.ico" rel="shortcut icon"><link href="https://fonts.googleapis.com/css?family=Source+Code+Pro:400,700|Source+Sans+Pro:400,400i,700,700i" rel="stylesheet"><link rel="stylesheet" href="assets/css/main.css"></head><body><svg xmlns="http://www.w3.org/2000/svg" hidden><symbol id="icon-menu" viewBox="0 0 24 28"><title>menu icon</title><path d="M24 21v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1V5c0-.547.453-1 1-1h22c.547 0 1 .453 1 1z"/></symbol><symbol id="icon-search" viewBox="0 0 24 28"><title>search icon</title><path d="M24 21v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1v-2c0-.547.453-1 1-1h22c.547 0 1 .453 1 1zm0-8v2c0 .547-.453 1-1 1H1c-.547 0-1-.453-1-1V5c0-.547.453-1 1-1h22c.547 0 1 .453 1 1z"/></symbol></svg><div data-sassdoc-region="app"><header role="banner" data-sassdoc-region="banner"><button data-nav-toggle="small" data-toggle="button" aria-controls="nav-small" aria-pressed="false" data-toggle-synced="false"><svg data-icon="menu" data-icon-size="icon-small"><title>menu</title><use xlink:href="#icon-menu"/></svg></button> <button data-nav-toggle="large" data-toggle="button" aria-controls="nav-large" aria-pressed="true" data-toggle-synced="false"><svg data-icon="menu" data-icon-size="icon-small"><title>menu</title><use xlink:href="#icon-menu"/></svg></button><h1 data-sassdoc="project-title"><a href="index.html" rel="home" data-sassdoc="project-name">susy</a> <span data-sassdoc="project-version">3.0.1</span></h1></header><div data-sassdoc-region="container"><nav role="navigation" data-nav-menu="small" data-toggle="target" id="nav-small" data-target-id="nav-small" aria-expanded="false" data-auto-closing="false" data-auto-closing-on-any-click="false"><h3 data-sassdoc="nav-title"><a href="index.html" data-sassdoc-nav="is-not-active">susy</a></h3><ul><li data-sassdoc="nav-item"><a href="a-config.html" data-sassdoc-nav="is-not-active">Configuration</a></li><li data-sassdoc="nav-item"><a href="b-api.html" data-sassdoc-nav="is-not-active">Grid Functions</a></li><li data-sassdoc="nav-item"><a href="plugin-utils.html" data-sassdoc-nav="is-not-active">Plugin Utilities</a></li><li data-sassdoc="nav-item"><a href="plugin_svg-grid.html" data-sassdoc-nav="is-not-active">Plugin: SVG Grid Image</a></li><li data-sassdoc="nav-item"><a href="su-math.html" data-sassdoc-nav="is-not-active">Su: Core Math Engine</a></li><li data-sassdoc="nav-item"><a href="x-normal.html" data-sassdoc-nav="is-active">[Susy Normalization]</a></li><li data-sassdoc="nav-item"><a href="x-parser.html" data-sassdoc-nav="is-not-active">[Susy Syntax Parser]</a></li><li data-sassdoc="nav-item"><a href="x-validation.html" data-sassdoc-nav="is-not-active">[Su Input Validation]</a></li><li data-sassdoc="nav-item"><a href="x-version.html" data-sassdoc-nav="is-not-active">[Release Notes]</a></li></ul></nav><nav role="navigation" data-nav-menu="large" data-toggle="target" id="nav-large" data-target-id="nav-large" aria-expanded="true" data-auto-closing="false" data-auto-closing-on-any-click="false"><h3 data-sassdoc="nav-title"><a href="index.html" data-sassdoc-nav="is-not-active">susy</a></h3><ul><li data-sassdoc="nav-item"><a href="a-config.html" data-sassdoc-nav="is-not-active">Configuration</a></li><li data-sassdoc="nav-item"><a href="b-api.html" data-sassdoc-nav="is-not-active">Grid Functions</a></li><li data-sassdoc="nav-item"><a href="plugin-utils.html" data-sassdoc-nav="is-not-active">Plugin Utilities</a></li><li data-sassdoc="nav-item"><a href="plugin_svg-grid.html" data-sassdoc-nav="is-not-active">Plugin: SVG Grid Image</a></li><li data-sassdoc="nav-item"><a href="su-math.html" data-sassdoc-nav="is-not-active">Su: Core Math Engine</a></li><li data-sassdoc="nav-item"><a href="x-normal.html" data-sassdoc-nav="is-active">[Susy Normalization]</a></li><li data-sassdoc="nav-item"><a href="x-parser.html" data-sassdoc-nav="is-not-active">[Susy Syntax Parser]</a></li><li data-sassdoc="nav-item"><a href="x-validation.html" data-sassdoc-nav="is-not-active">[Su Input Validation]</a></li><li data-sassdoc="nav-item"><a href="x-version.html" data-sassdoc-nav="is-not-active">[Release Notes]</a></li></ul></nav><main role="main"><nav data-sassdoc-region="breadcrumb"><a href="index.html">susy</a> » <strong>[Susy Normalization]</strong></nav><div data-sassdoc-region="main" data-sassdoc-page="x-normal"><section class="item"><div data-item-section="prose" class="text-block"><h1 id="syntax-normalization">Syntax Normalization</h1><p>Susy is divided into two layers: "Su" provides the core math functions with a stripped-down syntax, while "Susy" adds global settings, shorthand syntax, and other helpers. Each setting (e.g. span, location, columns, spread, etc.) has a single canonical syntax in Su.</p><p>This normalization module helps translate between those layers, transforming parsed Susy input into values that Su will understand.</p></div><div data-item-section="related"><h3 class="item-subtitle">related</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize" class="item-name">susy-normalize()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-span" class="item-name">susy-normalize-span()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-columns" class="item-name">susy-normalize-columns()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-spread" class="item-name">susy-normalize-spread()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-location" class="item-name">susy-normalize-location()</a></h4></div></div></section><section class="item" id="function--susy-normalize"><header data-item-section="header"><h2 class="item-title"><span class="item-type">@function</span> <a href="#function--susy-normalize" class="item-name">susy-normalize()</a></h2></header><div data-item-section="summary"><h3 class="item-subtitle">Description</h3><div class="text-block"><p>Normalize the values in a configuration map. In addition to the global <code>$susy</code> properties, this map can include local span-related imformation, like <code>span</code> and <code>location</code>.</p><p>Normalization does not check that values are valid, which will happen in the Su math layer. These functions merely look for known Susy syntax – returning a map with those shorthand values converted into low-level data for Su. For example <code>span: all</code> and <code>location: first</code> will be converted into specific numbers.</p></div></div><div data-item-section="parameter"><h3 class="item-subtitle">Parameters & Return</h3><div class="param-list"><h4 class="param-title"><span class="item-name">$config:</span> <span class="value-type">(map)</span></h4><div class="param-details text-block"><p>Map of Susy configuration settings to normalize. See <code>$susy</code> and <code>susy-parse()</code> documentation for details.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">$context:</span> <span class="item-value">null</span> <span class="value-type">(map | null)</span></h4><div class="param-details text-block"><p>Map of Susy configuration settings to use as global reference, or <code>null</code> to use global settings.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">@return</span> <span class="value-type">(map)</span></h4><div class="param-details text-block"><p>Map of Susy configuration settings, with all values normalized for Su math functions.</p></div></div></div><div data-item-section="related"><h3 class="item-subtitle">related</h3><div class="param-list"><h4 class="param-title"><a href="a-config.html#variable--susy" class="item-name">$susy</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-parser.html#function--susy-parse" class="item-name">susy-parse()</a></h4></div></div><div class="requires-wrapper"><div data-item-section="requires"><h3 class="item-subtitle">requires</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-spread" class="item-name">susy-normalize-spread()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-columns" class="item-name">susy-normalize-columns()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="a-config.html#function--susy-get" class="item-name">susy-get()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-span" class="item-name">susy-normalize-span()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize-location" class="item-name">susy-normalize-location()</a></h4></div></div><div data-item-section="used by"><h3 class="item-subtitle">used by</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="plugin-utils.html#function--susy-compile" class="item-name">susy-compile()</a></h4></div></div></div></section><section class="item" id="function--susy-normalize-span"><header data-item-section="header"><h2 class="item-title"><span class="item-type">@function</span> <a href="#function--susy-normalize-span" class="item-name">susy-normalize-span()</a></h2></header><div data-item-section="summary"><h3 class="item-subtitle">Description</h3><div class="text-block"><p>Normalize <code>span</code> shorthand for Su. Su span syntax allows an explicit length (e.g. <code>3em</code>), unitless column-span number (e.g. <code>3</code> columns), or an explicit list of columns (e.g. <code>(3 5 8)</code>).</p><p>Susy span syntax also allows the <code>all</code> keyword, which will be converted to a slice of the context in normalization.</p></div></div><div data-item-section="parameter"><h3 class="item-subtitle">Parameters & Return</h3><div class="param-list"><h4 class="param-title"><span class="item-name">$span:</span> <span class="value-type">(number | list | 'all')</span></h4><div class="param-details text-block"><p>Span value to normalize.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">$columns:</span> <span class="value-type">(list)</span></h4><div class="param-details text-block"><p>Normalized list of columns in the grid</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">@return</span> <span class="value-type">(number | list)</span></h4><div class="param-details text-block"><p>Number or list value for <code>$span</code></p></div></div></div><div data-item-section="used by"><h3 class="item-subtitle">used by</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize" class="item-name">susy-normalize()</a></h4></div></div></section><section class="item" id="function--susy-normalize-columns"><header data-item-section="header"><h2 class="item-title"><span class="item-type">@function</span> <a href="#function--susy-normalize-columns" class="item-name">susy-normalize-columns()</a></h2></header><div data-item-section="summary"><h3 class="item-subtitle">Description</h3><div class="text-block"><p>Normalize <code>column</code> shorthand for Su. Su column syntax only allows column lists (e.g. <code>120px 1 1 1 120px</code>).</p><p>Susy span syntax also allows a unitless <code>slice</code> number (e.g <code>of 5</code>), which will be converted to a slice of the context in normalization.</p></div></div><div data-item-section="parameter"><h3 class="item-subtitle">Parameters & Return</h3><div class="param-list"><h4 class="param-title"><span class="item-name">$columns:</span> <span class="value-type">(list | integer)</span></h4><div class="param-details text-block"><p>List of available columns, or unitless integer representing a slice of the available context.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">$context:</span> <span class="item-value">null</span> <span class="value-type">(map | null)</span></h4><div class="param-details text-block"><p>Map of Susy configuration settings to use as global reference, or <code>null</code> to access global settings.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">@return</span> <span class="value-type">(list)</span></h4><div class="param-details text-block"><p>Columns list value, normalized for Su input.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">@error</span></h4><div class="param-details text-block"><p>when attempting to access a slice of asymmetrical context</p></div></div></div><div class="requires-wrapper"><div data-item-section="requires"><h3 class="item-subtitle">requires</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="a-config.html#function--susy-settings" class="item-name">susy-settings()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <span class="item-name">_susy-flatten()</span> <span class="item-note">[private]</span></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="a-config.html#function--susy-repeat" class="item-name">susy-repeat()</a></h4></div><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <span class="item-name">_susy-error()</span> <span class="item-note">[private]</span></h4></div></div><div data-item-section="used by"><h3 class="item-subtitle">used by</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize" class="item-name">susy-normalize()</a></h4></div></div></div></section><section class="item" id="function--susy-normalize-spread"><header data-item-section="header"><h2 class="item-title"><span class="item-type">@function</span> <a href="#function--susy-normalize-spread" class="item-name">susy-normalize-spread()</a></h2></header><div data-item-section="summary"><h3 class="item-subtitle">Description</h3><div class="text-block"><p>Normalize <code>spread</code> shorthand for Su. Su spread syntax only allows the numbers <code>-1</code>, <code>0</code>, or <code>1</code> – representing the number of gutters covered in relation to columns spanned.</p><p>Susy spread syntax also allows keywords for each value – <code>narrow</code> for <code>-1</code>, <code>wide</code> for <code>0</code>, or <code>wider</code> for <code>1</code> – which will be converted to their respective integers in normalization.</p></div></div><div data-item-section="parameter"><h3 class="item-subtitle">Parameters & Return</h3><div class="param-list"><h4 class="param-title"><span class="item-name">$spread:</span> <span class="value-type">(0 | 1 | -1 | 'narrow' | 'wide' | 'wider')</span></h4><div class="param-details text-block"><p>Spread across adjacent gutters, relative to a column-count — either <code>narrow</code> (-1), <code>wide</code> (0), or <code>wider</code> (1)</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">@return</span> <span class="value-type">(number)</span></h4><div class="param-details text-block"><p>Numeric value for <code>$spread</code></p></div></div></div><div data-item-section="used by"><h3 class="item-subtitle">used by</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize" class="item-name">susy-normalize()</a></h4></div></div></section><section class="item" id="function--susy-normalize-location"><header data-item-section="header"><h2 class="item-title"><span class="item-type">@function</span> <a href="#function--susy-normalize-location" class="item-name">susy-normalize-location()</a></h2></header><div data-item-section="summary"><h3 class="item-subtitle">Description</h3><div class="text-block"><p>Normalize <code>location</code> shorthand for Su. Su location syntax requires the (1-indexed) number for a column.</p><p>Susy also allows the <code>first</code> and <code>last</code> keywords, where <code>first</code> is always <code>1</code>, and <code>last</code> is calculated based on span and column values. Both keywords are normalized into an integer index in normalization.</p></div></div><div data-item-section="parameter"><h3 class="item-subtitle">Parameters & Return</h3><div class="param-list"><h4 class="param-title"><span class="item-name">$span:</span> <span class="value-type">(number)</span></h4><div class="param-details text-block"><p>Number of grid-columns to be spanned</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">$location:</span> <span class="value-type">(integer | 'first' | 'last')</span></h4><div class="param-details text-block"><p>Starting (1-indexed) column position of a span, or a named location keyword.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">$columns:</span> <span class="value-type">(list)</span></h4><div class="param-details text-block"><p>Already-normalized list of columns in the grid.</p></div></div><div class="param-list"><h4 class="param-title"><span class="item-name">@return</span> <span class="value-type">(integer)</span></h4><div class="param-details text-block"><p>Numeric value for <code>$location</code></p></div></div></div><div data-item-section="used by"><h3 class="item-subtitle">used by</h3><div class="param-list"><h4 class="param-title"><span class="item-type">@function</span> <a href="x-normal.html#function--susy-normalize" class="item-name">susy-normalize()</a></h4></div></div></section></div></main></div></div><script type="text/javascript" src="assets/js/jquery-3.1.1.slim.js"></script><script type="text/javascript" src="assets/js/srcdoc-polyfill.min.js"></script><script type="text/javascript" src="assets/js/highlight.js"></script><script type="text/javascript" src="assets/js/base.js"></script><script type="text/javascript" src="assets/js/init.js"></script></body></html>