@financial-times/o-private-foundation 1.0.0

package/src/scss/o-grid/_functions.scss

@@ -0,0 +1,90 @@
+/// Get the grid gutter at a given layout (breakpoint).
+///
+/// @param {String|null|Boolean} $layout-name [default] - One of $o-pf-grid-layouts breakpoints e.g. S, M, L...
+@function oPrivateGridGutter($layout-name: default) {
+	// This layout was assigned a gutter directly
+	@if map-get($o-pf-grid-gutters, $layout-name) {
+		@return map-get($o-pf-grid-gutters, $layout-name);
+	}
+
+	// Checking the position of the layout in the list of layouts
+	$layout-index: index($_o-pf-grid-layout-names, $layout-name);
+
+	// The first layout (S) should get the default gutter
+	@if $layout-index == 1 {
+		@return oPrivateGridGutter();
+	}
+
+	// No gutter found for this layout, let's try again with a smaller one
+	$layout: nth($_o-pf-grid-layout-names, $layout-index - 1);
+	@return oPrivateGridGutter($layout);
+}
+
+/// Get the max width of a layout (breakpoint).
+///
+/// @example
+///  .my-large-container { width: oPrivateGridGetMaxWidthForLayout(L); }
+///
+/// @param {String} $layout-name - one of $o-pf-grid-layouts
+/// @param {String} $grid-mode [$o-pf-grid-mode]
+@function oPrivateGridGetMaxWidthForLayout($layout-name, $grid-mode: $o-pf-grid-mode) {
+	$grid-is-responsive: $grid-mode != 'fixed';
+
+	$index: index($_o-pf-grid-layout-names, $layout-name);
+
+	// Largest layout: return its width directly
+	@if $index == length($_o-pf-grid-layout-names) {
+		@return $_o-pf-grid-max-width;
+	}
+
+	// Smaller layouts:
+	@if $grid-is-responsive {
+		// - The grid is responsive (fluid or snappy):
+		//   return the next larger layout width
+		$next-layout: nth($_o-pf-grid-layout-names, $index + 1);
+		@return map-get($o-pf-grid-layouts, $next-layout);
+	} @else {
+		// - The grid is fixed, return the current layout width
+		@return map-get($o-pf-grid-layouts, $layout-name);
+	}
+}
+
+/// % width of an element in the grid
+///
+/// @example
+///  .one-half   { width: oPrivateGridColspan(1/2); }      // 50%
+///  .other-half { width: oPrivateGridColspan(one-half); } // 50%
+///  .sidebar    { width: oPrivateGridColspan(5); }        // 41.66667%
+///  .two-thirds { width: oPrivateGridColspan(2/3); }      // 66.66667%
+///  .4-out-of-6 { width: oPrivateGridColspan(4, 6); }     // 66.66667%
+///
+/// @param {Number | String} $span - Number of columns the element spans over
+/// @param {Number} $total-cols [$_o-pf-grid-columns] - Number of columns in the grid
+///
+/// @returns {Number} width of the element in the grid, in percents
+@function oPrivateGridColspan($span, $total-cols: $_o-pf-grid-columns) {
+	// Match the HTML helper API with human-friendly numbers
+	@if $span == 'one-half' { $span: div(1, 2); }
+	@if $span == 'one-quarter' { $span: div(1, 4); }
+	@if $span == 'one-third' { $span: div(1, 3); }
+	@if $span == 'two-thirds' { $span: div(2, 3); }
+	@if $span == 'three-quarters' { $span: div(3, 4); }
+
+	@if $span == 'full-width' {
+		@return 100%;
+	} @else {
+		@if $span >= 1 {
+			// A number of columns is supplied: converting it into a fraction
+			// of the total number of columns
+			@return percentage(div($span, $total-cols));
+		} @else {
+			// A fraction (1/2) or a number (0.5) is supplied:
+			// converting it into a percentage
+			@return percentage($span);
+		}
+	}
+}
+
+@function _oPrivateGridQuoteString($value) {
+	@return '"#{$value}"';
+}

package/src/scss/o-grid/_mixins.scss

@@ -0,0 +1,384 @@
+/// Apply styles at a given layout size (breakpoint) as the grid. It should be
+// passed one of $o-pf-grid-layouts e.g. `S`, `M`, etc... depending on which layout
+// size the style should apply at.
+///
+/// @example
+///  // Turn the color of an element red at medium layout size and up
+///  @include oPrivateGridRespondTo(M) {
+///  	element {
+///  		color: red;
+///  	}
+///  }
+///  // Turn the color of an element blue until medium layout
+///  element {
+///  	@include oPrivateGridRespondTo($until: M) {
+///  		color: blue;
+///  	}
+///  }
+///  // Turn the color of an element green from small layout until medium layout
+///  element {
+///  	@include oPrivateGridRespondTo($from: S, $until: M) {
+///  		color: green;
+///  	}
+///  }
+///
+/// @param {String} from - one of $o-pf-grid-layouts
+/// @param {String} until - one of $o-pf-grid-layouts
+@mixin oPrivateGridRespondTo($from: false, $until: false) {
+	$grid-is-responsive: $o-pf-grid-mode != 'fixed';
+	@include mq(
+		$from: $from,
+		$until: $until,
+		$responsive: $grid-is-responsive,
+		$breakpoints: $o-pf-grid-layouts,
+		$static-breakpoint: $o-pf-grid-fixed-layout
+	) {
+		@content;
+	}
+}
+
+/// Base column styles and responsive layout width
+///
+/// @example scss Block has column styles
+///   el { @include oPrivateGridColspan(); }
+///
+/// @example scss 4-column wide block
+///   el { @include oPrivateGridColspan(4); }
+///
+/// @example scss Half-width block
+///   el { @include oPrivateGridColspan(1/2); }
+///
+/// @example scss Block is full-width by default, 8-column wide on Medium layouts and hidden on Large layouts
+///   el { @include oPrivateGridColspan((default: 12, M: 8, L: hide)); }
+///
+/// @param {Number | Map} $span [null]
+@mixin oPrivateGridColspan($span: null, $width-only: false) {
+	@if not $width-only {
+		box-sizing: border-box;
+		float: left;
+		flex: 1 1 0%;
+		position: relative; // Required for push and pull
+
+		@if $o-pf-grid-mode == 'fixed' {
+			padding-left: oPrivateGridGutter($o-pf-grid-fixed-layout);
+		} @else {
+			@each $layout-name in map-keys($o-pf-grid-gutters) {
+				@if $layout-name == 'default' {
+					padding-left: oPrivateGridGutter();
+				} @else {
+					@include oPrivateGridRespondTo($layout-name) {
+						padding-left: oPrivateGridGutter($layout-name);
+					}
+				}
+			}
+		}
+	}
+	@if $span {
+		@include _oPrivateGridColumnWidth($span);
+	}
+}
+
+/// Grid container
+///
+/// @param {String} $grid-mode [$o-pf-grid-mode]
+/// @param {Boolean} $bleed [false]
+@mixin oPrivateGridContainer($grid-mode: $o-pf-grid-mode, $bleed: false) {
+	box-sizing: border-box;
+	margin-left: auto;
+	margin-right: auto;
+	min-width: $_o-pf-grid-min-width;
+	// Older browsers get a fixed-width layout
+	max-width: oPrivateGridGetMaxWidthForLayout($o-pf-grid-fixed-layout);
+	position: relative;
+
+	@if $bleed {
+		padding-left: 0;
+		padding-right: 0;
+	}
+
+	@if $grid-mode == 'fixed' {
+		// If the grid isn't fluid, we set it to a certain width
+		width: oPrivateGridGetMaxWidthForLayout(
+			$o-pf-grid-fixed-layout,
+			$grid-mode: 'fixed'
+		);
+		@if not $bleed {
+			padding-left: oPrivateGridGutter($o-pf-grid-fixed-layout);
+			padding-right: oPrivateGridGutter($o-pf-grid-fixed-layout);
+		}
+	} @else {
+		max-width: $_o-pf-grid-max-width;
+
+		@each $layout-name in map-keys($o-pf-grid-gutters) {
+			@if $layout-name == 'default' {
+				@if not $bleed {
+					padding-left: oPrivateGridGutter();
+					padding-right: oPrivateGridGutter();
+				}
+			} @else {
+				@include oPrivateGridRespondTo($layout-name) {
+					@if not $bleed {
+						padding-left: oPrivateGridGutter($layout-name);
+						padding-right: oPrivateGridGutter($layout-name);
+					}
+				}
+			}
+		}
+
+		@each $layout-name in $_o-pf-grid-layout-names {
+			@if index($_o-pf-grid-layout-names, $layout-name) >=
+				index($_o-pf-grid-layout-names, $_o-pf-grid-start-snappy-mode-at)
+			{
+				@include oPrivateGridRespondTo($layout-name) {
+					@if $grid-mode == 'snappy' {
+						max-width: map-get($o-pf-grid-layouts, $layout-name);
+					}
+					@if $grid-mode == 'fluid' {
+						// If the grid mode is fluid, then use a class to make a row or a set of rows snappy
+						.o-grid-snappy &,
+						&--snappy {
+							max-width: map-get($o-pf-grid-layouts, $layout-name);
+						}
+					}
+				}
+			}
+		}
+	}
+}
+
+/// Base row styles
+@mixin oPrivateGridRow {
+	clear: both;
+	flex-wrap: wrap; // Note that this breaks in old Firefox
+	display: flex;
+
+	@media print {
+		display: inherit;
+	}
+
+	@if $o-pf-grid-mode == 'fixed' {
+		margin-left: -1 * oPrivateGridGutter($o-pf-grid-fixed-layout);
+	} @else {
+		@each $layout-name in map-keys($o-pf-grid-gutters) {
+			@if $layout-name == 'default' {
+				margin-left: -1 * oPrivateGridGutter();
+			} @else {
+				@include oPrivateGridRespondTo($layout-name) {
+					margin-left: -1 * oPrivateGridGutter($layout-name);
+				}
+			}
+		}
+	}
+
+	// Clearfix for IE9 and below
+	zoom: 1;
+
+	&:before,
+	&:after {
+		content: '';
+		display: table;
+		display: flex; // stylelint-disable-line declaration-block-no-duplicate-properties
+	}
+	&:after {
+		clear: both;
+	}
+}
+
+/// Surface the layout currently displayed to make it readable in JS.
+///
+/// @example js
+///  // your-app/main.js
+///  // Return the current layout (e.g. default, S, M, L, XL)
+///  import oPrivateGrid from 'o-private-foundation/o-grid';
+///  let currentLayout = oPrivateGrid.getCurrentLayout();
+///  console.log(currentLayout);
+///
+///  // Return the current gutter (e.g. 10px, 20px)
+///  import oPrivateGrid from 'o-private-foundation/o-grid';
+///  let currentGutter = oPrivateGrid.getCurrentGutter();
+///  console.log(currentGutter);
+@mixin oPrivateGridSurfaceCurrentLayout {
+	html:after {
+		content: '{ "layout": "default", "gutter": "' + oPrivateGridGutter() + '" }';
+		display: none;
+
+		@each $breakpoint in $_o-pf-grid-layout-names {
+			@include oPrivateGridRespondTo($breakpoint) {
+				content: '{ "layout": "' + $breakpoint + '", "gutter": "' +
+					oPrivateGridGutter($breakpoint) + '" }';
+			}
+		}
+	}
+}
+
+/// Fix a bug in Safari where items wouldn't wrap properly
+/// Remove when Safari 10 support is no longer required.
+/// @link https://github.com/philipwalton/flexbugs#11-min-and-max-size-declarations-are-ignored-when-wrapping-flex-items
+/// @access private
+@mixin _oPrivateGridFixSafariWrap($args...) {
+	flex-basis: oPrivateGridColspan($args...);
+}
+
+/// Cross browser column widths across layouts
+///
+/// @access private
+///
+/// @example scss
+///   el { @include _oPrivateGridColumnWidth(4); }
+///   el { @include _oPrivateGridColumnWidth(1/2); }
+///   el { @include _oPrivateGridColumnWidth(hide); }
+///   el { @include _oPrivateGridColumnWidth((default: 12, M: 8, L: hide)); }
+///
+/// @param {Number | Map} $span
+@mixin _oPrivateGridColumnWidth($span) {
+	// Special case: the column is hidden by default
+	@if $span == 'hide' {
+		display: none;
+	} @else {
+		// $span is a number or a keyword, so we're outputting the default width for that column
+		@if type-of($span) == number or type-of($span) == string {
+			// Restore visibility from `display: none`
+			// if `data-o-grid-colspan` was set to `0` or `hide`
+			display: block;
+
+			// Define width in %
+			@include _oPrivateGridFixSafariWrap(
+				$span
+			); //stylelint-disable-line order/order
+			min-width: oPrivateGridColspan($span);
+			max-width: oPrivateGridColspan($span);
+		}
+	}
+
+	// $span is a map, we're looping through all of the layouts
+	@if type-of($span) == map {
+		@each $layout-name, $layout-span in $span {
+			@if $layout-name == 'default' {
+				@include _oPrivateGridColumnWidth($layout-span);
+			} @else {
+				@if $layout-span == 'hide' {
+					@include oPrivateGridRespondTo($layout-name) {
+						display: none;
+					}
+				} @else {
+					@include oPrivateGridRespondTo($layout-name) {
+						// Restore visibility from `display: none`
+						// if `data-o-grid-colspan` was set to `0` or `hide`
+						display: block;
+						// Define width in %
+						@include _oPrivateGridFixSafariWrap(
+							$layout-span
+						); // stylelint-disable-line order/order
+						min-width: oPrivateGridColspan($layout-span);
+						max-width: oPrivateGridColspan($layout-span);
+					}
+				}
+			}
+		}
+	}
+}
+
+/// Remove gutters from columns in a row
+///
+/// @param {string} $column-selector ["[o-grid-colspan]"] - CSS selector for row element
+@mixin oPrivateGridRowCompact($column-selector: '[o-grid-colspan]') {
+	margin-left: 0;
+
+	> #{unquote($column-selector)} {
+		padding-left: 0;
+	}
+}
+
+/// Add a layout (breakpoint). This can be used to add a new breakpoint to a
+/// project, in addition to the default layouts (S, M, L, XL).
+///
+/// @example scss
+///  @include oGridAddLayout($layout-name: P, $layout-width: 600px);
+///  @include oGridAddLayout($layout-name: XXL, $layout-width: 1600px, $gutter-width: 30px);
+///
+/// @param {String} $layout-name - Name of the layout (e.g. S)
+/// @param {Number} $layout-width - Layout width in px
+/// @param {Number} $gutter-width [null] - Gutter width in px
+@mixin oPrivateGridAddLayout($layout-name, $layout-width, $gutter-width: null) {
+	$temp-layouts: ();
+	$temp-gutters: (
+		default: oGridGutter(),
+	);
+	$current-max-width: map-get(
+		$o-pf-grid-layouts,
+		nth($_o-pf-grid-layout-names, -1)
+	);
+
+	// Add the new layout in the correct position:
+	// (we want $o-grid-layouts and $o-grid-gutters to be ordered from the smallest to the largest layout)
+	@if ($layout-width >= $current-max-width) {
+		$temp-layouts: map-merge(
+			$o-pf-grid-layouts,
+			(
+				$layout-name: $layout-width,
+			)
+		);
+		$temp-gutters: map-merge(
+			$o-pf-grid-gutters,
+			(
+				$layout-name: $gutter-width,
+			)
+		);
+	} @else {
+		@for $index from 1 through length($o-pf-grid-layouts) {
+			$previous-layout-width: if(
+				$index == 1,
+				0,
+				map-get($o-pf-grid-layouts, nth($_o-pf-grid-layout-names, $index - 1))
+			);
+			$current-layout-name: nth($_o-pf-grid-layout-names, $index);
+			$current-layout-width: map-get($o-pf-grid-layouts, $current-layout-name);
+
+			$current-gutter-width: map-get($o-pf-grid-gutters, $current-layout-name);
+
+			// Assumes all layouts use the same unit e.g. px or rem (as does the JavaScript)
+			@if not(
+				$previous-layout-width >
+					$layout-width or
+					$current-layout-width <
+					$layout-width
+			)
+			{
+				$temp-layouts: map-merge(
+					$temp-layouts,
+					(
+						$layout-name: $layout-width,
+					)
+				);
+				$temp-gutters: map-merge(
+					$temp-gutters,
+					(
+						$layout-name: $gutter-width,
+					)
+				);
+			}
+
+			$temp-layouts: map-merge(
+				$temp-layouts,
+				(
+					$current-layout-name: $current-layout-width,
+				)
+			);
+
+			@if $current-gutter-width {
+				$temp-gutters: map-merge(
+					$temp-gutters,
+					(
+						$current-layout-name: $current-gutter-width,
+					)
+				);
+			}
+		}
+	}
+	$o-pf-grid-layouts: $temp-layouts !global;
+	$_o-pf-grid-layout-names: map-keys($o-pf-grid-layouts) !global;
+
+	@if $gutter-width {
+		$o-pf-grid-gutters: $temp-gutters !global;
+	}
+}

package/src/scss/o-grid/_variables.scss

@@ -0,0 +1,105 @@
+// ----------------------------------------------------------------------------
+// Responsive behaviour configuration
+// ----------------------------------------------------------------------------
+
+/// Grid mode
+/// - fluid: full width up to the largest layout's width
+/// - snappy: fluid width until the layout defined in $_o-pf-grid-start-snappy-mode-at (default: M),
+///           and then snaps into a larger fixed layout at each breakpoint
+/// - fixed: always fixed-width with the layout defined by $o-pf-grid-fixed-layout (default: L)
+///
+/// @type String - one of fluid (default), snappy, fixed
+$o-pf-grid-mode: if(
+	global-variable-exists(o-grid-mode),
+	$o-grid-mode,
+	'fluid'
+) !default;
+
+/// Layout to default to when the grid has a fixed width (not fluid)
+///
+/// @type String - One of $o-pf-grid-layouts
+$o-pf-grid-fixed-layout: if(
+	global-variable-exists(o-grid-fixed-layout),
+	$o-grid-fixed-layout,
+	'L'
+) !default;
+
+/// When the grid start snapping between fixed-width layouts
+/// in the case where a row has the `o-grid-row--snappy` class
+///
+/// @type String
+$_o-pf-grid-start-snappy-mode-at: 'M' !default;
+
+// ----------------------------------------------------------------------------
+// Grid settings and dimensions
+// ----------------------------------------------------------------------------
+
+/// Number of columns
+///
+/// @type Number (unitless)
+$_o-pf-grid-columns: 12 !default;
+
+/// Minimum width, in pixels
+///
+/// @type Number
+$_o-pf-grid-min-width: 240px !default;
+
+/// Layouts
+///
+/// Each layout is calculated following a specific column width,
+/// in order to base breakpoints on the structure of the grid itself
+///
+/// @type Map
+$o-pf-grid-layouts: if(
+	global-variable-exists(o-grid-layouts),
+	$o-grid-layouts,
+	(
+		S: 490px,
+		// column-width: 30px, inner width: 470px
+		M: 740px,
+		// column-width: 40px, inner width: 700px
+		L: 980px,
+		// column-width: 60px, inner width: 940px
+		XL: 1220px,
+		// column-width: 80px, inner width: 1180px
+	)
+) !default;
+
+/// Layout names
+///
+/// @access private
+/// @type List
+$_o-pf-grid-layout-names: map-keys($o-pf-grid-layouts);
+
+/// Gutter sizes
+///
+/// @type Map
+
+$o-pf-grid-gutters: if(
+	global-variable-exists(o-grid-gutters),
+	$o-grid-gutters,
+	(
+		default: 10px,
+		M: 20px,
+	)
+) !default;
+
+// If layouts have changed but gutters haven't,
+// prune non-existant layouts.
+@each $layout-name, $gutter-size in $o-pf-grid-gutters {
+	@if ($layout-name != 'default') and
+		(not map-has-key($o-pf-grid-layouts, $layout-name))
+	{
+		$o-pf-grid-gutters: map-remove($o-pf-grid-gutters, $layout-name);
+	}
+}
+
+/// Maximum grid width
+/// Defaults to the largest layout width
+///
+/// @access private
+/// @type Number
+$_o-pf-grid-max-width: map-get(
+	$o-pf-grid-layouts,
+	nth($_o-pf-grid-layout-names, -1)
+);

package/src/scss/o-grid/main.scss

@@ -0,0 +1,5 @@
+@import '@financial-times/math';
+@import '@financial-times/sass-mq';
+@import 'variables';
+@import 'functions';
+@import 'mixins';

package/src/scss/o-icons/_mixins.scss

@@ -0,0 +1,71 @@
+/// Output styles for an SVG icon.
+/// Styles the icon as a background image, setting a width and height on the element as requested.
+/// A fallback background for Windows High Contrast mode is also output.
+///
+/// @access public
+/// @param {String} $icon-name - This should be a reference to an icon included in o-icons eg arrow-down
+/// @param {String} $color - This should be a hex colour value. Used to color the icon. We suggest using an o-colors function.
+/// @param {Number|Null} $size [128] - The width and height of the icon (units optional, defaults to px). Set to `null` to set no width or height.
+/// @param {Bool} $include-base-styles [true] - If true, will output style rules for the container. If false will only output the background-image property
+/// @param {Bool} $high-contrast-fallback [true] - To output Microsoft High Contrast fallback for accessibility reasons or not.
+/// @param {Number} $iconset-version [1] - At present only 1 version of the icon set is available.
+@mixin oPrivateIconsContent($icon-name, $color: null, $size: 128, $include-base-styles: true, $high-contrast-fallback: true, $iconset-version: 1) {
+	// Error if the global $system-code variable is not set.
+	// This is required for image service requests.
+	@if(global-variable-exists('system-code') == false or type-of($system-code) != 'string') {
+		@error 'A global "$system-code" Sass variable must be set to a valid [Bizops system code](https://biz-ops.in.ft.com/list/Systems).';
+	}
+
+	// If the size of the icons has been given without a unit, default to px.
+	@if (type-of($size) == 'number' and unitless($size)) {
+		$size: $size + 0px;
+	}
+
+	// Define base image service path.
+	$scheme: "fticon-v#{$iconset-version}";
+	$service-url: "https://www.ft.com/__origami/service/image/v2/images/raw/#{$scheme}:#{$icon-name}";
+
+	// Include base styles shared by all icons.
+	@if ($include-base-styles == true) {
+		@include oPrivateIconsContentBaseStyles;
+	}
+
+	// Set the icon dimentions.
+	width: $size;
+	height: $size;
+
+	// Include the icon via the image service.
+	// Build an image service url for the requested icon.
+	$query: "?source=#{$system-code}";
+	@if $color != null {
+		$color: str-slice(ie-hex-str($color), 4);
+		$query: $query + "&tint=%23#{$color},%23#{$color}";
+	}
+	background-image: url($service-url + $query + "&format=svg");
+
+	// Include a fallback for Window's high contrast mode.
+	// This mode removes background images unless specifcally included
+	// for high contrast mode.
+	// sass-lint:disable no-vendor-prefixes
+	@if $high-contrast-fallback {
+		@media screen and (-ms-high-contrast: active) {
+			background-image: url($service-url + "?source=#{$system-code}&tint=%23ffffff,%23ffffff&format=svg");
+		}
+
+		@media screen and (-ms-high-contrast: black-on-white) {
+			background-image: url($service-url + "?source=#{$system-code}&tint=%23000000,%23000000&format=svg");
+		}
+	}
+	// sass-lint:enable no-vendor-prefixes
+}
+
+/// Base styles for all icons
+/// @access public
+@mixin oPrivateIconsContentBaseStyles() {
+	display: inline-block;
+	background-repeat: no-repeat;
+	background-size: contain;
+	background-position: 50%;
+	background-color: transparent;
+	vertical-align: baseline;
+}

package/src/scss/o-icons/main.scss

@@ -0,0 +1 @@
+@import "mixins";