Version 1.1.0
github.com/NYCPlanning/labs-uiLabs UI is an Ember.js addon containing common components and design patterns used across NYC Planning Labs digital products, incorporating styles from our Digital Style Guide.
See the style guide docs for more information on its features, classes, typography, color, layout…
The NYC Planning Digital Style Guide is built with Foundation for Sites. Consult the Foundation docs for features not covered in the style guide's docs. Note: Labs UI only consumes styles from the style guide/Foundation, it not its JavaScript.
Use the site-header
component to add a branded banner at the top of apps. It includes Planning Labs' beta notice and a logo that links to NYC Planning's main site. Its optional responsive parameters automatically add a menu button to toggle the navigation on smaller screens, and define the screen size at which that happens.
To add an app name and menu items to the header, include the site-title
and site-nav
contextual components, using the .site-title
and .site-subtitle
Labs UI classes and Foundation's menu classes.
arg | type | default | description |
responsiveNav |
boolean | false | Adds menu button to toggle nav |
responsiveSize |
string | large |
Screen size at which nav is always visible |
betaNotice |
boolean | false | Adds a beta notice above header |
<LabsUi::SiteHeader
@responsiveNav={{true}}
@responsiveSize="medium"
@betaNotice={{true}}
as |banner|
>
<banner.title>
<a href="#" class="site-title">App Name <small class="site-subtitle show-for-medium">Subtitle</small></a>
</banner.title>
<banner.nav>
<ul class="menu vertical medium-horizontal">
<li><LinkTo @route="index">One</LinkTo></li>
<li><LinkTo @route="index">Two</LinkTo></li>
<li class="external-nav-item"><a href="mailto:email@example.org">Email</a></li>
</ul>
</banner.nav>
</LabsUi::SiteHeader>
Renders a Font Awesome icon with Ember Tooltips.
arg | type | default | description |
tip |
string | null | Tooltip text |
icon |
string | info-circle |
Font Awesome icon name |
side |
string | top |
top, right, bottom, or left |
transform |
string | null |
Font Awesome "Power Transforms" |
fixedWith |
boolean | null |
Makes icon occupy same width as other fixed-width icons |
Here is an info tooltip on a "map-marked-alt" icon
<LabsUi::IconTooltip
@tip="This is the tooltip text."
@icon="map-marked-alt"
@side="bottom"
@transform="shrink-2 up-2"
@fixedWidth={{true}}
/>
in the middle of some text.
Here is an info tooltip on a "map-marked-alt" icon
This component is always used in block form. The label
param renders a clickable label and switch. When either are clicked, the active
boolean is reversed and the visibility of the component's yielded content is toggled.
Optional tooltip parameters can be passed:
Typically used to show meta info, tooltip
renders a dark blue info circle icon that is always visible, regardless of the active state. Override the icon with tooltipIcon
.
Typically used to indicate a warning, activeTooltip
renders an orange exclamation triangle icon that is only visible when the active state is true. Override the icon with activeTooltipIcon
.
arg | type | default | description |
label |
string | null | Clickable label text (required) |
active |
boolean | true | Sets default state of component |
icon |
object | null | Structured data, renders a legend icon |
tooltip |
string | null | Adds a tooltip that's always visible |
tooltipIcon |
string | info-circle |
Font Awesome icon |
activeTooltip |
string | null | Tooltip text |
activeTooltipIcon |
string | exclamation-triangle |
Font Awesome icon |
Note: Since the yielded content can be anything, its layout is unopinionated (e.g. it needs its own padding to align text with the label/switch).
<LabsUi::LayerGroupToggle
@label="Layer Group Label"
@active={{true}}
@tooltip="This is the layer group tooltip."
@icon={{exampleIcon}}
@activeTooltip="This is the layer group warning message."
>
yielded content goes here
</LabsUi::LayerGroupToggle>
<LabsUi::LayerGroupToggle
@label="Layer Group Label"
@active={{false}}
@infoLink="https://planninglabs.nyc/"
@tooltip="I show up regardless of the active state."
@tooltipIcon="tree"
@activeTooltip="I only show up when the layer group is active."
@activeTooltipIcon="hand-peace"
>
yielded content goes here
</LabsUi::LayerGroupToggle>
A group of layer groups… Set of groups? A toggleable container, this component is always used in block form. Its title
param renders a clickable title which toggles the visibility of its yielded content. When its title is clicked, the open
boolean is reversed and the visibility of the component's yielded content is toggled.
For full functionality, use Layer Group Toggles as contextual components.
arg | type | default | description |
title |
string | null | Clickable title text (required) |
open |
boolean | true | Sets default state of component |
<LabsUi::LayerGroupsContainer
@title="Layer Groups Container Title"
@open={{true}}
as |container|
>
<container.layer-group-toggle @label="Layer Group One" @active={{true}} />
<container.layer-group-toggle @label="Layer Group Two" @active={{false}} />
</LabsUi::LayerGroupsContainer>
The legend-items
component does not yield any content directly. It simply loops through the array of legend objects and passes each one to the labs-ui/legend-item
component.
arg | type | default | description |
items |
object | null | Structured data, array of legend objects (required) |
<LabsUi::LegendItems @items={{exampleItems}} />
The legend-item
component is called by the each
loop in the legend-items
component. It renders a label (required), tooltip, and icon.
arg | type | default | description |
item |
object | null | Structured data, legend object (required) |
<LabsUi::LegendItem @item={{exampleItem}} />
The legend-icon
component renders a layered stack of icons. The icon.type
can be line
, rectangle
, or fa-icon
, and determines if the layers are made of SVGs or Font Awesome icons. The icon.layers
array of objects describes each of the layers in the stack — e.g. a dark red line over a thicker transparent pink line.
arg | type | default | description |
icon |
object | null | Structured data, (required) |
<LabsUi::LegendIcon @icon={{exampleLine}} />
<LabsUi::LegendIcon @icon={{exampleRectangle}} />
<LabsUi::LegendIcon @icon={{exampleCircle}} />
Labs UI depends on the Ember Power Select addon in place of <select>
elements, often to allow for typeahead results. See the docs for how to use Ember Power Select.
Labs UI depends on the Ember Tooltips addon for its tooltips. This addon also has Popovers. What's the difference? Tooltips are for read-only purposes, whereas Popovers can contain interactive elements. See the docs for how to use Ember Tooltips.
Labs UI also has a custom Sass module which helps Ember Tooltips more closely match our styles.
By default, Tooltips have a dark background and Popovers have a light background:
The Popover can be given a dark background with the .dark
class:
<EmberPopover @_tooltipVariantClass="ember-popover dark">
...
</EmberPopover>
Labs UI depends the Ember Flatpicker addon for its date picker. See the docs for how to use Ember Flatpicker.
Labs UI also has a custom Sass module which helps Ember Flatpicker more closely match our styles.
Note: The @date
and @onChange
arguments are required.
<EmberFlatpickr
@date={{this.dateValue}}
@onChange{{this.onDateChange}}
@enableTime{{true}}
placeholder="Choose a date and time..."
>