n-ui-foundations
v10.1.0
Published
Sass & JS foundations and utilities for the FT.com front end
Downloads
10,848
Readme
n-ui-foundations
Sass and JS utilities for the next front-end for use by components and apps.
Sass
This package includes and configures several low-level Origami components required by all of the front-end of FT.com and ensures they maintain compatible versions. This includes colors, typography, grid, and normalising styles.
There are two Sass partials provided by this package which may be integrated with your codebase:
Components should integrate via the mixins only, it can be imported many times:
@import "n-ui-foundations/mixins";
Apps should integrate via the main entrypoint, which will output all of the base CSS rulesets. It should be imported once:
@import "n-ui-foundations/main";
Critical & modular CSS
Applications using n-ui
are able to split Sass output into multiple output files. This is done using an opening and closing code comment which act as delimiters for a PostCSS script to find and extract the rules between them.
@include nUiStylesheetStart('stylesheet-name');
.my-stylesheet-rule {
content: 'this will be output in stylesheet-name.css';
}
@include nUiStylesheetEnd('stylesheet-name');
Please note if your application is using Page Kit this feature is not available and these mixins should not be used.
Caveats and customisations
o-grid
Human readable classes (e.g. data-o-grid-colspan="half"
) have all been disabled to minimise the output size of o-grid
, with the exception of center
.
To avoid shipping unused rulesets offset
pull
and push
column selectors are disabled. To use these a mixin is provided nUiGridOffset($layout-name, $columns, $mode)
@include nUiGridOffset('M', 3, 'pull');
logos
A mixin for getting logos (or other Origami imageset images)
@include nGetImage(
$image-type,
$image-name,
$color: null,
$container-width: 128,
$container-height: null
)
utilities
See https://github.com/Financial-Times/n-ui-foundations/blob/HEAD/util/README.md for a full list of utility classes.
JS
This package includes several commonly used utility functions to avoid repeating boilerplate code.
import { $, $$ } from 'n-ui-foundations';
$(sel, [context])
Equivalent tocontext.querySelector(sel)
(context
defaults todocument
)$$(sel, [context])
Equivalent toArray.from(context.querySelectorAll(sel))
(context
defaults todocument
)throttle(func, wait)
Creates a throttled copy of a function, re-exported fromo-utils
debounce(func, wait)
Creates a debounced copy of a function, re-exported fromo-utils
uuid()
- generates a random UUIDascii(str)
converts non-ascii unicode characters to ascii equivalentsbroadcast(name, data, bubbles = true)
fires a custom event. The event is fired fromdocument.body
by default but if called with the context of aHtmlElement
it will be fired from that instead.perfMark(name)
- log a performance mark.sampleUsers(pct, seed)
- select a % of users to target behaviour at (returnsBool
)
Cookie store
Useful methods for working with cookies.
import { cookieStore } from 'n-ui-foundations');
get(name)
Get the value of the given cookie.
set(name, value, [options])
Set a cookie. Available options are domain
, path
, expires
, secure
and maxAge
.
Note it is "maxAge" not "max-age". If you don't specify either expires or maxAge the cookie will expire at the end of the session.
has(name)
Returns true if the given cookie exists.
remove(name)
Delete the given cookie by setting the expiry to the past.
Migration guides
v5 to v6
v6 of n-ui-foundations no longer outputs a snappy grid by default, as it is deprecated. This means your grid container elements will be wider when the viewport width is at a grid breakpoint. Where the grid CSS class o-grid-container
or Sass mixin oGridContainer
is used check your project at different breakpoints for visual regressions. If your project looks good no action is needed.
If your project looks broken, you may choose to switch to a snappy
grid. This will allow us to find where the snappy grid is used and remove it in the future:
- Find and replace
o-grid-container
classes witho-grid-container o-grid-container--snappy
.
-<div class="o-grid-container"></div>
+<div class="o-grid-container o-grid-container--snappy"></div>
- Find
oGridContainer
mixin uses and passsnappy
as the first argument.
-@include oGridContainer();
+@include oGridContainer($grid-mode: 'snappy');
If your app uses Page Kit's dotcom-build-sass
package and needs to maintain a snappy
grid, then ensure you are using Page Kit >= v2.0.1 and make the following change in the app's webpack.config.js
:
-new PageKitSassPlugin()
+new PageKitSassPlugin({ prependData: '$o-grid-mode: \'snappy\';' })
v4 to v5
- No manual changes required, but font changes will occur:
- Added: Financier Medium.
- Removed: Metric Medium.
v3 to v4
- All color use cases have been removed as many of these are already defined by
o-
components and should be used instead. - The
.n-ui-text-*
rules have been removed, useo-typography
instead. - The
getColor()
andgetColorFor()
Sass functions have been removed, use the equivalent functions provided byo-colors
instead.