@adobe/coral-spectrum
Version:
Coral Spectrum is a JavaScript library of Web Components following Spectrum design patterns.
1,037 lines • 80.8 kB
HTML
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<base data-ice="baseUrl" href="./">
<title data-ice="title">Manual | Coral Spectrum</title>
<link type="text/css" rel="stylesheet" href="css/style.css">
<link type="text/css" rel="stylesheet" href="css/prettify-tomorrow.css">
<script src="script/prettify/prettify.js"></script>
<script src="script/manual.js"></script>
<script src="./inject/script/0-typekit.js"></script><script src="./inject/script/0-guide.js"></script><link rel="stylesheet" href="./inject/css/0-guide.css"><meta name="description" content="Coral Spectrum is a JavaScript library of Web Components following Spectrum design patterns."><meta property="twitter:card" content="summary"><meta property="twitter:title" content="Coral Spectrum"><meta property="twitter:description" content="Coral Spectrum is a JavaScript library of Web Components following Spectrum design patterns."></head>
<body class="layout-container manual-root manual-index" data-ice="rootContainer">
<header>
<a href="./" style="display: flex; align-items: center;"><img src="./image/brand_logo.svg" style="width:34px;"></a>
<a href="identifiers.html">Reference</a>
<a href="source.html">Source</a>
<div class="search-box">
<span>
<img src="./image/search.png">
<span class="search-input-edge"></span><input class="search-input"><span class="search-input-edge"></span>
</span>
<ul class="search-result"></ul>
</div>
<a style="position:relative; top:3px;" href="https://github.com/adobe/coral-spectrum"><img width="20px" src="./image/github.png"></a></header>
<nav class="navigation" data-ice="nav"><div class="manual-toc-root">
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/README.html"><a href="manual/README.html#coral-spectrum--img-src--https---github-com-adobe-coral-spectrum-workflows-unit-20tests-20and-20accessibility-20ci-badge-svg--alt--build-status--" data-ice="link">Coral Spectrum </a></li>
<li data-ice="manualNav" class="indent-h1" data-link="manual/README.html"><a href="manual/README.html#important" data-ice="link">Important</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#showcase" data-ice="link">Showcase</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/README.html"><a href="manual/README.html#-a-href--http---opensource-adobe-com-coral-spectrum-examples--component-examples--a-" data-ice="link">Component Examples</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/README.html"><a href="manual/README.html#-a-href--http---opensource-adobe-com-coral-spectrum-documentation-identifiers-html--api-references--a-" data-ice="link">API References</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/README.html"><a href="manual/README.html#-a-href--http---opensource-adobe-com-coral-spectrum-playground--playground--a-" data-ice="link">Playground</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#spectrum" data-ice="link">Spectrum</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#angular--react--vue-js-compatibility" data-ice="link">Angular, React, Vue.js compatibility</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#browser-support" data-ice="link">Browser support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#theme--light--dark--lightest--darkest-" data-ice="link">Theme (light, dark, lightest, darkest)</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#large-scale-support" data-ice="link">Large scale support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#built-in-accessibility-and-keyboard-support" data-ice="link">Built-in Accessibility and Keyboard support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#internationalization-support" data-ice="link">Internationalization support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#using-coral-spectrum" data-ice="link">Using Coral Spectrum</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/README.html"><a href="manual/README.html#easiest-way-via-a-cdn" data-ice="link">Easiest way via a CDN</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/README.html"><a href="manual/README.html#copying-the-distribution-files" data-ice="link">Copying the distribution files</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/README.html"><a href="manual/README.html#including-entire-library-with-a-bundler-like-parcel" data-ice="link">Including entire library with a bundler like parcel</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/README.html"><a href="manual/README.html#including-only-the-components-you-need" data-ice="link">Including only the components you need</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/README.html"><a href="manual/README.html#contributing" data-ice="link">Contributing</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/README.html"><a href="manual/README.html#building-and-testing" data-ice="link">Building and Testing</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/README.html"><a href="manual/README.html#releasing" data-ice="link">Releasing</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/README.html"><a href="manual/README.html#automatic-release-" data-ice="link">Automatic release:</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/README.html"><a href="manual/README.html#manual-releasing-" data-ice="link">Manual releasing:</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/overview.html"><a href="manual/overview.html" data-ice="link">Overview</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#introduction" data-ice="link">Introduction</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#unified-experience" data-ice="link">Unified Experience</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#enhanced-api" data-ice="link">Enhanced API</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#future-thinking" data-ice="link">Future Thinking</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#spectrum" data-ice="link">Spectrum</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#built-in-accessibility-and-keyboard-support" data-ice="link">Built-in Accessibility and Keyboard support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#internationalization-support" data-ice="link">Internationalization support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#browser-support" data-ice="link">Browser Support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/overview.html"><a href="manual/overview.html#backwards-compatibility" data-ice="link">Backwards Compatibility</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/manual.html"><a href="manual/manual.html" data-ice="link">Manual</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/manual.html"><a href="manual/manual.html#using-coral-spectrum" data-ice="link">Using Coral Spectrum</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/manual.html"><a href="manual/manual.html#easiest-way-via-a-cdn" data-ice="link">Easiest way via a CDN</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/manual.html"><a href="manual/manual.html#copying-the-distribution-files" data-ice="link">Copying the distribution files</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/manual.html"><a href="manual/manual.html#using-a-bundler-like-webpack" data-ice="link">Using a bundler like Webpack</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/manual.html"><a href="manual/manual.html#building-and-testing" data-ice="link">Building and Testing</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/manual.html"><a href="manual/manual.html#releasing" data-ice="link">Releasing</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/upgrade.html"><a href="manual/upgrade.html" data-ice="link">Upgrade</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/upgrade.html"><a href="manual/upgrade.html#from-coralui3-to-coral-spectrum" data-ice="link">From CoralUI3 to Coral Spectrum</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#custom-elements-v1" data-ice="link">Custom Elements v1</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#spectrum" data-ice="link">Spectrum</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#performance" data-ice="link">Performance</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#overlay-mechanism" data-ice="link">Overlay mechanism</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/upgrade.html"><a href="manual/upgrade.html#upgrade-changes" data-ice="link">Upgrade changes</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#custom-elements-v1" data-ice="link">Custom Elements v1</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#spectrum" data-ice="link">Spectrum</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/upgrade.html"><a href="manual/upgrade.html#selection-pattern-for-table--columnview-and-masonry" data-ice="link">Selection pattern for Table, ColumnView and Masonry</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/upgrade.html"><a href="manual/upgrade.html#svg-icons" data-ice="link">SVG Icons</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/upgrade.html"><a href="manual/upgrade.html#unsupported-styles" data-ice="link">Unsupported styles</a></li>
<li data-ice="manualNav" class="indent-h4" data-link="manual/upgrade.html"><a href="manual/upgrade.html#internal-private-markup-and-classes" data-ice="link">Internal private markup and classes</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#parent-child-component-events" data-ice="link">Parent-child component events</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#dependencies" data-ice="link">Dependencies</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#api-changes" data-ice="link">API changes</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/upgrade.html"><a href="manual/upgrade.html#compatibility-with-coralui3" data-ice="link">Compatibility with CoralUI3</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#coral-register" data-ice="link">Coral.register</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#coral-commons-ready" data-ice="link">Coral.commons.ready</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/upgrade.html"><a href="manual/upgrade.html#off-line-custom-elements-v0-creation" data-ice="link">Off-line Custom Elements v0 creation</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/styles.html"><a href="manual/styles.html" data-ice="link">Styles</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/styles.html"><a href="manual/styles.html#theme--light--dark--lightest--darkest-" data-ice="link">Theme (light, dark, lightest, darkest)</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/styles.html"><a href="manual/styles.html#large-scale-support" data-ice="link">Large scale support</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/styles.html"><a href="manual/styles.html#css-utility-classes" data-ice="link">CSS utility classes</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-clearfix" data-ice="link">u-coral-clearFix</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-noborder" data-ice="link">u-coral-noBorder</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-noscroll" data-ice="link">u-coral-noScroll</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-screenreaderonly" data-ice="link">u-coral-screenReaderOnly</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-closedhand" data-ice="link">u-coral-closedHand</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-openhand" data-ice="link">u-coral-openHand</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-pullleft" data-ice="link">u-coral-pullLeft</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-pullright" data-ice="link">u-coral-pullRight</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-padding" data-ice="link">u-coral-padding</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-padding-horizontal" data-ice="link">u-coral-padding-horizontal</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-padding-vertical" data-ice="link">u-coral-padding-vertical</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-margin" data-ice="link">u-coral-margin</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-nopadding" data-ice="link">u-coral-noPadding</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-nopadding-horizontal" data-ice="link">u-coral-noPadding-horizontal</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-nopadding-vertical" data-ice="link">u-coral-noPadding-vertical</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-nomargin" data-ice="link">u-coral-noMargin</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-ellipsis" data-ice="link">u-coral-ellipsis</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-visiblexs---u-coral-hiddenxs" data-ice="link">u-coral-visibleXS | u-coral-hiddenXS</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-visibles---u-coral-hiddens" data-ice="link">u-coral-visibleS | u-coral-hiddenS</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-visiblem---u-coral-hiddenm" data-ice="link">u-coral-visibleM | u-coral-hiddenM</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-visiblel---u-coral-hiddenl" data-ice="link">u-coral-visibleL | u-coral-hiddenL</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-visiblexl---u-coral-hiddenxl" data-ice="link">u-coral-visibleXL | u-coral-hiddenXL</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#u-coral-visiblexxl---u-coral-hiddenxxl" data-ice="link">u-coral-visibleXXL | u-coral-hiddenXXL</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/styles.html"><a href="manual/styles.html#fonts-via-typekit" data-ice="link">Fonts via Typekit</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#domains" data-ice="link">Domains</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#using-a-custom-kit-with-coral-spectrum" data-ice="link">Using a Custom Kit with Coral Spectrum</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/styles.html"><a href="manual/styles.html#font-loading" data-ice="link">Font loading</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/architecture.html"><a href="manual/architecture.html" data-ice="link">Architecture</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/architecture.html"><a href="manual/architecture.html#web-components" data-ice="link">Web Components</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/architecture.html"><a href="manual/architecture.html#content-zones" data-ice="link">Content Zones</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/architecture.html"><a href="manual/architecture.html#dependencies" data-ice="link">Dependencies</a></li>
</ul>
</div>
<div data-ice="manual">
<ul class="manual-toc">
<li data-ice="manualNav" class="indent-h1" data-link="manual/contribution.html"><a href="manual/contribution.html" data-ice="link">Contribution</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/contribution.html"><a href="manual/contribution.html#code-of-conduct" data-ice="link">Code Of Conduct</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/contribution.html"><a href="manual/contribution.html#have-a-question-" data-ice="link">Have A Question?</a></li>
<li data-ice="manualNav" class="indent-h3" data-link="manual/contribution.html"><a href="manual/contribution.html#security-issues" data-ice="link">Security Issues</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/contribution.html"><a href="manual/contribution.html#contributor-license-agreement" data-ice="link">Contributor License Agreement</a></li>
<li data-ice="manualNav" class="indent-h2" data-link="manual/contribution.html"><a href="manual/contribution.html#code-reviews" data-ice="link">Code Reviews</a></li>
</ul>
</div>
</div>
</nav>
<div class="content" data-ice="content"><div class="github-markdown">
<div class="manual-user-index" data-ice="manualUserIndex"><h1 id="meet-coral-spectrum">Meet Coral Spectrum</h1><p>Coral Spectrum is a JavaScript library of Web Components following Spectrum design patterns.</p>
<p><img class="logo" src="./manual/asset/spectrum_illustration_2x.png"></p>
<h2 id="showcase">Showcase</h2><p>All components can be seen in action <a href="../examples" target="_blank">here</a>. These are only examples and
don't cover all scenarios. The API documentation can be found in the <a href="./identifiers.html" target="_blank">references</a>.<br>A playground is available <a href="../playground" target="_blank">here</a> to experiment and preview code with the latest Coral Spectrum version.
Code can be shared by copy pasting the URL. The playground is sandboxed to prevent security risks.</p>
<h2 id="spectrum">Spectrum</h2><p>The current default theme is is an implementation of the <a href="https://spectrum.adobe.com">Spectrum</a> design
specifications, Adobe’s design system. Spectrum provides elements and tools to help product teams work more
efficiently, and to make Adobe’s applications more cohesive.</p>
<p>Coral Spectrum leverages the <a href="https://github.com/adobe/spectrum-css">Spectrum CSS</a> framework to style
components including the <a href="https://spectrum.adobe.com/page/icons">Spectrum SVG icons</a>. </p>
<h2 id="angular--react--vue-js-compatibility">Angular, React, Vue.js compatibility</h2><p>Our vision is to create consistent Adobe experiences by providing a complete, easy to use library of HTML components
compatible with <a href="https://custom-elements-everywhere.com/">major frameworks</a>.</p>
<p>To reach the goal, Coral Spectrum derives from <a href="https://html.spec.whatwg.org/multipage/custom-elements.html">Custom Elements v1</a> with
<a href="https://caniuse.com/#feat=custom-elementsv1">native support</a> thanks to broad collaboration between browser vendors.
The use of custom elements gives us the ability to hide many implementation details from the consumer, allowing much
more freedom to change the underlying markup that supports those elements.
This makes the exposed API smaller and more explicit, resulting in a lower risk of updates to Coral Spectrum needing to
introduce breaking changes.</p>
<hr>
<h3 id="-a-href----manual-overview-html--»-overview--a-"><a href="./manual/overview.html">» Overview</a></h3><p>Vision and goals</p>
<h3 id="-a-href----manual-manual-html--»-manual--a-"><a href="./manual/manual.html">» Manual</a></h3><p>Get you started. How to consume and build the project</p>
<h3 id="-a-href----manual-upgrade-html--»-upgrade--a-"><a href="./manual/upgrade.html">» Upgrade</a></h3><p>Helping you upgrade from CoralUI3</p>
<h3 id="-a-href----manual-styles-html--»-styles--a-"><a href="./manual/styles.html">» Styles</a></h3><p>Theme, public CSS and Typekit</p>
<h3 id="-a-href----manual-architecture-html--»-architecture--a-"><a href="./manual/architecture.html">» Architecture</a></h3><p>Technical decisions behind the architecture</p>
<h3 id="-a-href----manual-contribution-html--»-contribution--a-"><a href="./manual/contribution.html">» Contribution</a></h3><p>Open development principles</p>
</div>
<div class="manual-cards">
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Important</h1><p>Please follow the <a href="https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines">Commit Message Conventions</a>. To easily comply, it is recommended to use <a href="https://github.com/commitizen/cz-cli">cz-cli</a>.</p><h2>Showcase</h2><h4><a href="http://opensource.adobe.com/coral-spectrum/examples">Component Examples</a></h4><p>To see all components in action. These are only examples and don't cover all scenarios.</p><h4><a href="http://opensource.adobe.com/coral-spectrum/documentation/identifiers.html">API References</a></h4><p>Covers the API for all components including properties, events and more.</p><h4><a href="http://opensource.adobe.com/coral-spectrum/playground">Playground</a></h4><p>Experiment and preview code with the latest Coral Spectrum version.
Code can be shared by copy pasting the URL. The playground is sandboxed to prevent security risks.</p><h2>Spectrum</h2><p>The current default theme is is an implementation of the <a href="https://spectrum.adobe.com">Spectrum</a> design
specifications, Adobe’s design system. Spectrum provides elements and tools to help product teams work more
efficiently, and to make Adobe’s applications more cohesive.</p><p>Coral Spectrum leverages the <a href="https://github.com/adobe/spectrum-css">Spectrum CSS</a> framework to style
components including the <a href="https://spectrum.adobe.com/page/icons">Spectrum SVG icons</a>.</p><h2>Angular, React, Vue.js compatibility</h2><p>Our vision is to create consistent Adobe experiences by providing a complete, easy to use library of HTML components
compatible with <a href="https://custom-elements-everywhere.com/">major frameworks</a>.</p><p>To reach the goal, Coral Spectrum derives from <a href="https://html.spec.whatwg.org/multipage/custom-elements.html">Custom Elements v1</a> with
<a href="https://caniuse.com/#feat=custom-elementsv1">native support</a> thanks to broad collaboration between browser vendors.
The use of custom elements gives us the ability to hide many implementation details from the consumer, allowing much
more freedom to change the underlying markup that supports those elements.
This makes the exposed API smaller and more explicit, resulting in a lower risk of updates to Coral Spectrum needing to
introduce breaking changes.</p><h2>Browser support</h2><p>Coral Spectrum is designed to support the following browsers:</p><ul>
<li>Chrome (latest)</li>
<li>Safari (latest)</li>
<li>Firefox (latest)</li>
<li>Edge (latest)</li>
<li>IE 11</li>
<li>iOS 7+</li>
<li>Android 4.4+</li>
</ul><h2>Theme (light, dark, lightest, darkest)</h2><p>The default Coral Spectrum styles cascade from <code>coral--light</code>, <code>coral--lightest</code>, <code>coral--dark</code> and <code>coral--darkest</code> theme, so that class must be specified at a higher level.</p><pre><code class="lang-html"><code class="source-code prettyprint"><body class="coral--light">
<!-- light theme -->
<div class="container"></div>
<div class="coral--dark">
<!-- dark theme -->
</div>
</body></code>
</code></pre><h2>Large scale support</h2><p>For mobile, Spectrum has a larger scale that enables larger tap targets on all controls. To enable it, the class <code>coral--large</code> must be specified at a higher level.</p><pre><code class="lang-html"><code class="source-code prettyprint"><body class="coral--light coral--large">
<!-- light theme -->
<!-- large scale -->
</body></code>
</code></pre><h2>Built-in Accessibility and Keyboard support</h2><p>Having an inaccessible application can mean thousands of dollars of fines if you land a government contract.
It also means alienating an entire segment of society by making your application completely unusable to them.
To help you avoid this, we’ve made it a rule that every Coral Spectrum component should be accessible.</p><h2>Internationalization support</h2><p>Coral Spectrum provides a robust internal system for internationalization of its strings.
This is done via an internal Adobe process.</p><p>Supported languages are :</p><table>
<thead>
<tr>
<th>Language family</th>
<th>Language tag</th>
<th>Language variant</th>
</tr>
</thead>
<tbody>
<tr>
<td>English</td>
<td>en-US</td>
<td>American English</td>
</tr>
<tr>
<td>French</td>
<td>fr-FR</td>
<td>Standard French</td>
</tr>
<tr>
<td>German</td>
<td>de-DE</td>
<td>Standard German</td>
</tr>
<tr>
<td>Italian</td>
<td>it-IT</td>
<td>Standard Italian</td>
</tr>
<tr>
<td>Spanish</td>
<td>es-ES</td>
<td>Castilian Spanish</td>
</tr>
<tr>
<td>Portuguese</td>
<td>pt-BR</td>
<td>Brazilian Portuguese</td>
</tr>
<tr>
<td>Japanese</td>
<td>ja-JP</td>
<td>Standard Japanese</td>
</tr>
<tr>
<td>Korean</td>
<td>ko-KR</td>
<td>Standard Korean</td>
</tr>
<tr>
<td>Chinese</td>
<td>zh-CN</td>
<td>Mainland China, simplified characters</td>
</tr>
<tr>
<td>Chinese</td>
<td>zh-TW</td>
<td>Taiwan, traditional characters</td>
</tr>
<tr>
<td>Dutch</td>
<td>nl-NL</td>
<td>Netherlands Dutch</td>
</tr>
<tr>
<td>Danish</td>
<td>da-DK</td>
<td>Standard Danish</td>
</tr>
<tr>
<td>Finnish</td>
<td>fi-FI</td>
<td>Standard Finnish</td>
</tr>
<tr>
<td>Norwegian</td>
<td>no-NO</td>
<td>Standard Norwegian</td>
</tr>
<tr>
<td>Swedish</td>
<td>sv-SE</td>
<td>Standard Swedish</td>
</tr>
<tr>
<td>Czech</td>
<td>cs-CZ</td>
<td>Standard Czech</td>
</tr>
<tr>
<td>Polish</td>
<td>pl-PL</td>
<td>Standard Polish</td>
</tr>
<tr>
<td>Russian</td>
<td>ru-RU</td>
<td>Standard Russian</td>
</tr>
<tr>
<td>Turkish</td>
<td>tr-TR</td>
<td>Standard Turkish</td>
</tr>
</tbody>
</table><h2>Using Coral Spectrum</h2><h3>Easiest way via a CDN</h3><p>The easiest way to consume Coral Spectrum is to use a CDN e.g. copy these lines into your html file.</p><pre><code class="lang-html"><code class="source-code prettyprint"><head>
<!-- 4.x.x means latest major 4 version release, adjust version if you need a specific one -->
<link rel="stylesheet" href="https://unpkg.com/@adobe/coral-spectrum@4.x.x/dist/css/coral.min.css">
<script src="https://unpkg.com/@adobe/coral-spectrum@4.x.x/dist/js/coral.min.js" data-coral-icons-external="js"></script>
</head>
<body class="coral--light">
<button is="coral-button" icon="add">My Button</button>
</body></code>
</code></pre><h3>Copying the distribution files</h3><p>You can download a packaged/published version of <code>@adobe/coral-spectrum</code> from npm:</p><pre><code><code class="source-code prettyprint">npm pack @adobe/coral-spectrum</code>
</code></pre><p>After you've unzipped the downloaded package, look for the <code>dist</code> folder and :</p><ul>
<li>Copy the files from <code>dist/css</code>, <code>dist/js</code> and <code>dist/resources</code> in your project.</li>
<li>Reference the files in your page e.g</li>
</ul><pre><code class="lang-html"><code class="source-code prettyprint"><link rel="stylesheet" href="css/coral.min.css">
<script src="js/coral.min.js"></script></code>
</code></pre><h3>Including entire library with a bundler like parcel</h3><p><code>npm install @adobe/coral-spectrum</code></p><p>then in your main js, use:</p><pre><code><code class="source-code prettyprint">require("@adobe/coral-spectrum/dist/js/coral.js");
require("@adobe/coral-spectrum/dist/css/coral.css");</code>
</code></pre><h3>Including only the components you need</h3><p>If your project only requires a few components, you can use a module bundler like <a href="https://webpack.js.org/">Webpack</a> to only import the components needed.
Below is an example of a Webpack config:</p><pre><code class="lang-js"><code class="source-code prettyprint">const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');
module.exports = {
mode: 'production',
devtool: 'source-map',
entry: './src/index.js',
output: {
filename: 'bundle.min.js',
path: path.resolve(__dirname, 'dist')
},
module: {
rules: [
{
test: /\.js$/,
use: {
loader: 'babel-loader',
options: {
presets: ['@babel/preset-env']
}
}
},
{
test: /\.svg$/,
use: [
{
loader: 'file-loader',
options: {
name: 'icons/[name].[ext]'
},
},
]
},
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, 'css-loader']
}
]
},
plugins: [
new MiniCssExtractPlugin({
filename: 'style.min.css'
}),
new OptimizeCssAssetsPlugin({
assetNameRegExp: /style\.min\.css$/g,
cssProcessor: require('cssnano'),
cssProcessorPluginOptions: {
preset: ['default', { discardComments: { removeAll: true } }],
}
})
]
};</code>
</code></pre><p>Then in your <code>index.js</code> file, you can import and use single components :</p><pre><code class="lang-js"><code class="source-code prettyprint">// Import Component
import {Button} from '@adobe/coral-spectrum/coral-component-button';
const button = new Button();</code>
</code></pre><p>If icons are not displayed, ensure the path to the styles and icons are set e.g. :</p><pre><code class="lang-html"><code class="source-code prettyprint"><link rel="stylesheet" href="dist/style.min.css">
<script data-coral-icons="dist/icons/" src="dist/bundle.min.js"></script></code>
</code></pre><p>If icons still do not display, you can try setting them to display as inline
SVGs, instead of external resources. Coral Spectrum will default to external
resources on browsers other than IE11. Using the previous example, this option
can be set with:</p><pre><code class="lang-html"><code class="source-code prettyprint"><link rel="stylesheet" href="dist/style.min.css">
<script data-coral-icons="dist/icons/" data-coral-icons-external="off" src="dist/bundle.min.js"></script></code>
</code></pre><p><strong>Note:</strong> Calendar, Clock and Datepicker components will leverage <a href="http://momentjs.com/">moment.js</a> if available.</p><h2>Contributing</h2><p>Check out the <a href="https://github.com/adobe/coral-spectrum/blob/master/.github/CONTRIBUTING.md">contributing guidelines</a>.</p><h3>Building and Testing</h3><p>Run the following commands first :</p><pre><code><code class="source-code prettyprint">npm install -g gulp-cli
npm install</code>
</code></pre><p>You can use below tasks to get started:</p><ul>
<li><code>gulp</code> to generate the build in the <code>dist</code> folder and run the dev server on <code>localhost:9001</code> by default.</li>
<li><code>gulp build</code> to generate the build in the <code>dist</code> folder.</li>
<li><code>gulp dev</code> to run the dev server on <code>localhost:9001</code> by default.</li>
<li><code>gulp test</code> to run the tests. Test reports are in <code>dist/coverage</code>.</li>
<li><code>gulp docs</code> to build the documentation in <code>dist/documentation</code>.</li>
<li><code>gulp axe</code> to run the accessibility checks.</li>
</ul><p>Each component can be built independently e.g. <code>cd coral-component-button && gulp</code>.</p><h3>Releasing</h3><h4>Automatic release:</h4><p>Merging the PR to master will trigger an automatic release Github Action. It is important to follow <a href="https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines">Angular Commit Message Conventions</a>. It is recommended to use <a href="https://github.com/commitizen/cz-cli">cz-cli</a> for easy commits.
Only <strong>fix</strong> and <strong>feat</strong> can trigger a release. If you want to skip release <a href="https://semantic-release.gitbook.io/semantic-release/support/faq#can-i-exclude-commits-from-the-analysis">add [skip release] or [release skip] to the commit message</a></p><h4>Manual releasing:</h4><p>We are currently releasing this package on <code>npm</code>.</p><p>Before we get started, clean up your dependencies with the following command :</p><pre><code><code class="source-code prettyprint">git checkout master
rm -rf node_modules && npm install</code>
</code></pre><p>Then run <code>gulp release</code>. You'll be asked to bump the version (minor version bump by default). Coral Spectrum is following
<a href="https://docs.npmjs.com/about-semantic-versioning">semantic versioning</a> (either patch, minor or major).</p><p>The command will take care of increasing, tagging the version and publishing the package to <code>npm</code>.</p><p>If everything went well, run <code>gulp deploy</code> to publish the documentation on the <code>gh-pages</code> branch else revert the version bump.</p></div>
<a data-ice="link" href="manual/README.html#important"></a>
</div>
</div>
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Overview</h1><h2>Introduction</h2><p>Coral Spectrum has roots as an internal Open Development project, with core volunteers working on this problem since 2012.
As of 2016, the effort has become part of the One Adobe & Cloud Platform effort, which means building a full Coral Spectrum
team that includes Exec Leadership, PgM, PM, EM, Dev, and QE members. Coral Spectrum is also becoming a One Adobe Technical
Standard, meaning it will be used as the default platform for web projects.</p><h2>Unified Experience</h2><p>Our vision is to create consistent Adobe experiences by providing a complete, easy to use library of HTML components.
Standardization on Coral Spectrum allows teams to reduce code duplication and variation and encourages company wide collaboration.
This reduction in effort means teams can focus on meeting customer needs, not reinventing the wheel. Use of Coral Spectrum also
enables easy, unified design updates, and provides a library that is under Adobe’s full control.</p><h2>Enhanced API</h2><p>Coral Spectrum's components are essentially extended DOM elements. We enhance the existing API with additional functionality,
as well as providing some patterns that aren't available with native HTML alone. Since we expose a JavaScript API that’s
based on the native DOM API and has all of the same methods as any other HTML element instance, anyone familiar with the
DOM already knows most of the API works. </p><p>Most API is available via markup, so don’t have to write JavaScript for most basic uses. All you have to do is write
the markup for a component, just like you would a normal HTML element.</p><h2>Future Thinking</h2><p>Coral Spectrum is pushing the web forward by leveraging the <a href="https://www.webcomponents.org/introduction">Web Components</a> specification.
However, given the landscape of browser implementation and the state of the polyfill ecosystem, we decided to only implement
<a href="https://html.spec.whatwg.org/multipage/custom-elements.html">Custom Elements v1</a> at this time.</p><p>A strong advantage Coral Spectrum derives from custom elements is the ability to hide many implementation details from the consumer.
More to the point, we found that designs become closely tied to their markup. The use of custom elements allows much more
freedom to change the underlying markup that supports those elements. This makes the exposed API smaller and more explicit,
resulting in a lower risk of updates to Coral Spectrum needing to introduce breaking changes.</p><p>In addition, every Coral component is an HTML element. This give us the ability to create components from markup or JavaScript
and lets us treat them like any other native element, setting properties, appending them in the DOM, etc. </p><h2>Spectrum</h2><p>The current default theme is is an implementation of the <a href="https://spectrum.adobe.com">Spectrum</a> design specifications, Adobe’s design system.
Spectrum provides elements and tools to help product teams work more efficiently, and to make Adobe’s applications more cohesive.</p><p>Coral Spectrum leverages the <a href="https://github.com/adobe/spectrum-css">Spectrum CSS</a> framework to style
components including the <a href="https://spectrum.adobe.com/page/icons">Spectrum SVG icons</a>. </p><h2>Built-in Accessibility and Keyboard support</h2><p>Having an inaccessible application can mean thousands of dollars of fines if you land a government contract.
It also means alienating an entire segment of society by making your application completely unusable to them.
To help you avoid this, we’ve made it a rule that every Coral Spectrum component should be accessible. We’ve also built a few
things into Coral Spectrum to make implementing accessibility easier for component authors and consumers alike.</p><h2>Internationalization support</h2><p>Coral Spectrum provides a robust internal system for internationalization of its strings.
This is done via an internal Adobe process.</p><p>Supported languages are :</p><table>
<thead>
<tr>
<th>Language family</th>
<th>Language tag</th>
<th>Language variant</th>
</tr>
</thead>
<tbody>
<tr>
<td>English</td>
<td>en-US</td>
<td>American English</td>
</tr>
<tr>
<td>French</td>
<td>fr-FR</td>
<td>Standard French</td>
</tr>
<tr>
<td>German</td>
<td>de-DE</td>
<td>Standard German</td>
</tr>
<tr>
<td>Italian</td>
<td>it-IT</td>
<td>Standard Italian</td>
</tr>
<tr>
<td>Spanish</td>
<td>es-ES</td>
<td>Castilian Spanish</td>
</tr>
<tr>
<td>Portuguese</td>
<td>pt-BR</td>
<td>Brazilian Portuguese</td>
</tr>
<tr>
<td>Japanese</td>
<td>ja-JP</td>
<td>Standard Japanese</td>
</tr>
<tr>
<td>Korean</td>
<td>ko-KR</td>
<td>Standard Korean</td>
</tr>
<tr>
<td>Chinese</td>
<td>zh-CN</td>
<td>Mainland China, simplified characters</td>
</tr>
<tr>
<td>Chinese</td>
<td>zh-TW</td>
<td>Taiwan, traditional characters</td>
</tr>
<tr>
<td>Dutch</td>
<td>nl-NL</td>
<td>Netherlands Dutch</td>
</tr>
<tr>
<td>Danish</td>
<td>da-DK</td>
<td>Standard Danish</td>
</tr>
<tr>
<td>Finnish</td>
<td>fi-FI</td>
<td>Standard Finnish</td>
</tr>
<tr>
<td>Norwegian</td>
<td>no-NO</td>
<td>Standard Norwegian</td>
</tr>
<tr>
<td>Swedish</td>
<td>sv-SE</td>
<td>Standard Swedish</td>
</tr>
<tr>
<td>Czech</td>
<td>cs-CZ</td>
<td>Standard Czech</td>
</tr>
<tr>
<td>Polish</td>
<td>pl-PL</td>
<td>Standard Polish</td>
</tr>
<tr>
<td>Russian</td>
<td>ru-RU</td>
<td>Standard Russian</td>
</tr>
<tr>
<td>Turkish</td>
<td>tr-TR</td>
<td>Standard Turkish</td>
</tr>
</tbody>
</table><h2>Browser Support</h2><p>Coral Spectrum is designed to support the following browsers:</p><ul>
<li>Chrome (latest)</li>
<li>Safari (latest)</li>
<li>Firefox (latest)</li>
<li>Edge (latest)</li>
<li>IE 11</li>
<li>iOS 7+</li>
<li>Android 4.4+</li>
</ul><h2>Backwards Compatibility</h2><p>Coral Spectrum ships by default a compatibility package to support the CoralUI 3.x way to register elements <code>Coral.register</code>.
Custom Coral components using Custom Elements v0 are therefore still supported although we highly encourage to migrate
to Custom Elements v1 as it'll become the Web standard. </p></div>
<a data-ice="link" href="manual/overview.html"></a>
</div>
</div>
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Manual</h1><h2>Using Coral Spectrum</h2><h3>Easiest way via a CDN</h3><p>The easiest way to consume Coral Spectrum is to use a CDN e.g. copy these lines into your html file. </p><pre><code><code class="source-code prettyprint"><head>
<!-- Adjust version accordingly -->
<link rel="stylesheet" href="https://unpkg.com/@adobe/coral-spectrum@4.5.0/dist/css/coral.min.css">
<script src="https://unpkg.com/@adobe/coral-spectrum@4.5.0/dist/js/coral.min.js" data-coral-icons-external="js"></script>
</head>
<body class="coral--light">
<button is="coral-button" icon="add">My Button</button>
</body> </code>
</code></pre><h3>Copying the distribution files</h3><p>You can also download the distribution package of the
latest release by running <code>npm i @adobe/coral-spectrum</code>. It includes all components and styles.</p><p>After you've unzipped the package, look for the <code>dist</code> folder and :</p><ul>
<li>Copy the files from <code>dist/css</code>, <code>dist/js</code> and <code>dist/resources</code> in your project.</li>
<li>Reference the files in your page with :<pre><code><code class="source-code prettyprint"><link rel="stylesheet" href="css/coral.min.css">
<script src="js/coral.min.js"></script></code>
</code></pre></li>
</ul><h3>Using a bundler like Webpack</h3><p>If your project only requires a few components, you can use a module bundler like <a href="https://webpack.js.org/">Webpack</a> to only import the components needed.
Below is an example of a Webpack config:</p><pre><code><code class="source-code prettyprint">const path = require('path');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');
const OptimizeCssAssetsPlugin = require('optimize-css-assets-webpack-plugin');
module.exports = {
mode: 'production',
devtool: 'source-map',
entry: './src/index.js',
output: {
filename: 'bundle.min.js',
path: path.resolve(__dirname, 'dist')
},
module: {
rules: [
{
test: /\.js$/,
use: {
loader: 'babel-loader',
options: {
presets: ['@babel/preset-env']
}
}
},
{
test: /\.svg$/,
use: [
{
loader: 'file-loader',
options: {
name: 'icons/[name].[ext]'
},
},
]
},
{
test: /\.css$/,
use: [MiniCssExtractPlugin.loader, 'css-loader']
}
]
},
plugins: [
new MiniCssExtractPlugin({
filename: 'style.min.css'
}),
new OptimizeCssAssetsPlugin({
assetNameRegExp: /style\.min\.css$/g,
cssProcessor: require('cssnano'),
cssProcessorPluginOptions: {
preset: ['default', { discardComments: { removeAll: true } }],
}
})
]
}; </code>
</code></pre><p>Then in your <code>index.js</code> file, you can import and use single components :</p><pre><code><code class="source-code prettyprint">// Import Component
import {Button} from '@adobe/coral-spectrum/coral-component-button';
const button = new Button();</code>
</code></pre><p>If icons are not displayed, ensure the path to the styles and icons are set e.g. :</p><pre><code><code class="source-code prettyprint"><link rel="stylesheet" href="dist/style.min.css">
<script data-coral-icons="dist/icons/" src="dist/bundle.min.js"></script></code>
</code></pre><p><strong>Note:</strong> Calendar, Clock and Datepicker components will leverage <a href="http://momentjs.com/">moment.js</a> if available.</p><h2>Building and Testing</h2><p>Run the following commands first :</p><pre><code><code class="source-code prettyprint">npm install -g gulp-cli
npm install</code>
</code></pre><p>You can use below tasks to get started:</p><ul>
<li><code>gulp</code> to generate the build in the <code>dist</code> folder and run the dev server on <code>localhost:9001</code> by default.</li>
<li><code>gulp build</code> to generate the build in the <code>dist</code> folder.</li>
<li><code>gulp dev</code> to run the dev server on <code>localhost:9001</code> by default. </li>
<li><code>gulp test</code> to run the tests. Test reports are in <code>dist/coverage</code>.</li>
<li><code>gulp docs</code> to build the documentation in <code>dist/documentation</code>. </li>
<li><code>gulp axe</code> to run the accessibility checks.</li>
</ul><p>Each component can be built independently e.g. <code>cd coral-component-button && gulp</code>.</p><h2>Releasing</h2><p>We are currently releasing this package on <code>npm</code>.</p><p>Before we get started, clean up your dependencies with the following command :</p><pre><code><code class="source-code prettyprint">git checkout master
rm -rf node_modules && npm install</code>
</code></pre><p>Then run <code>gulp release</code>. You'll be asked to bump the version (minor version bump by default). Coral Spectrum is following
<a href="https://docs.npmjs.com/about-semantic-versioning">semantic versioning</a> (either patch, minor or major).</p><p>The command will take care of increasing, tagging the version and publishing the package to <code>npm</code>. </p><p>If everything went well, run <code>gulp deploy</code> to publish the documentation on the <code>gh-pages</code> branch else revert the version bump.</p></div>
<a data-ice="link" href="manual/manual.html"></a>
</div>
</div>
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Upgrade</h1><h2>From CoralUI3 to Coral Spectrum</h2><h3>Custom Elements v1</h3><p>CoralUI 3.x relies on Custom Elements v0 which is an outdated spec which won't be implemented natively in major browsers while
Coral Spectrum derives from <a href="https://html.spec.whatwg.org/multipage/custom-elements.html">Custom Elements v1</a> with
<a href="https://caniuse.com/#feat=custom-elementsv1">native support</a> thanks to broad collaboration between browser vendors.
The use of custom elements gives us the ability to hide many implementation details from the consumer, allowing much
more freedom to change the underlying markup that supports those elements.
This makes the exposed API smaller and more explicit, resulting in a lower risk of updates to Coral Spectrum needing to
introduce breaking changes.</p><h3>Spectrum</h3><p>The current default theme is is an implementation of the <a href="https://spectrum.adobe.com">Spectrum</a> design
specifications, Adobe’s design system. Spectrum provides elements and tools to help product teams work more
efficiently, and to make Adobe’s applications more cohesive.</p><p>From the Adobe Design perspective, there's a long standing directive which prohibits AD to design any New Product
using anything less than the latest Spectrum theme. The concern in the Design Org is so high that there is an actual
live form where AD is asked to enter products in order to be evaluated for Spectrum Theme Compliance.
Needless to say, the Spectrum Theme is the only theme currently being supported and updated, with designers from all EC
contributing to its features.</p><p>Coral Spectrum leverages the <a href="https://github.com/adobe/spectrum-css">Spectrum CSS</a> framework to style
components including the <a href="https://spectrum.adobe.com/page/icons">Spectrum SVG icons</a>.</p><h3>Performance</h3><p>CoralUI3 components are upgraded asynchronously due to limitation of Custom Elements v0. Custom Elements v1 are upgraded synchronously
if the definition is loaded before any usage of the component. </p><p>Essentially this means that users will be able to view the components rendered faster when the page loads with Coral Spectrum than with CoralUI3.
Code-wise, it means that <code>Coral.commons.ready()</code> becomes obsolete in most cases.</p><p>On the other hand, all Coral Spectrum parent-child components are using asynchronous Mutation Observers replacing the
slow and synchronous events <code>coral-component:attached</code> and <code>coral-component:detached</code>.</p><p>Also, new technologies were introduced to take advantage of browsers new capabilities to reduce performance issues for
certain components (e.g resizeListenerObserver for Coral.ActionBar). </p><p>The performance boost is visible by the test execution time: </p><p><em>CoralUI 3 UTs results</em></p><pre><code><code class="source-code prettyprint">HeadlessChrome 70.0.3538 (Mac OS X 10.13.6): 3516 tests executed (2 mins 28.947 secs / 1 min 43.192 secs)
Firefox 63.0.0 (Mac OS X 10.13.0): 3516 tests executed (2 mins 14.507 secs / 1 min 35.82 secs)</code>
</code></pre><p><em>Coral Spectrum UTs results (contains more tests due to full clone node support but still performs faster)</em></p><pre><code><code class="source-code prettyprint">HeadlessChrome 70.0.3538 (Mac OS X 10.13.6): 4481 tests executed (49.697 secs / 30.759 secs)
Firefox 63.0.0 (Mac OS X 10.13.0): Executed 4481 tests executed (1 min 1.791 secs / 36.38 secs)</code>
</code></pre><h3>Overlay mechanism</h3><p>CoralUI3's positioning system for overlays was based on jQueryUI which is known to have limited functionality compared
to today's existing solutions. Replacing it by a modern solution (PopperJS) has proven that it can solve common
overlay/positioning issues previously occurring with CoralUI3.</p><h2>Upgrade changes</h2><h3>Custom Elements v1</h3><p>A major change in v1 is that component initialization is now done in an ES6 class constructor. The list of
<a href="http://w3c.github.io/webcomponents/spec/custom/#custom-element-conformance">Requirements for custom element constructors</a>
prohibits a new component from setting attributes or adding child nodes in its constructor. </p><p><strong>Let's have a look at a concrete example</strong></p><p>With 3.x you could do following: </p><pre><code><code class="source-code prettyprint">var alert = new Coral.Alert();
var header = alert.querySelector('coral-alert-header');
header.textContent = 'Info';</code>
</code></pre><p>With Coral Spectrum and Custom Elements v1, this is not possible anymore since the tag is empty when created. You'll have
to use the JavaScript API provided by the component instead.</p><pre><code><code class="source-code prettyprint">var alert = new Coral.Alert();
var header = alert.header; // Use the JS API to access the content zone
header.textContent = 'Info';</code>
</code></pre><h3>Spectrum</h3><p>Due to the new Spectrum design, some components were updated to accommodate design pattern changes:</p><h4>Selection pattern for Table, ColumnView and Masonry</h4><p>The concept of selectable thumbnails for Table and ColumnView was replaced with checkboxes. Masonry still supports the old
way of selection since Card selection via checkbox was not implemented yet. </p><h4>SVG Icons</h4><p>Coral Spectrum ships SVG icons that need to be loaded first before being displayed.
There are several ways to load the icons: </p><ul>
<li>Reuse the same file structure as in the <code>dist</code> folder with <code>css/coral.css</code>, <code>js/coral.js</code> and <code>resources/*.svg</code>. </li>
<li>Add <code>data-coral-icons="PATH_TO_RESOURCES_FOLDER"</code> to the <code><script></code> loading Coral Spectrum. See <a href="./manual/../class/coral-spectrum/coral-utils/src/scripts/Commons.js~Commons.html#instance-member-options">options</a> for details.</li>
<li>Use <a href="./manual/../class/coral-spectrum/coral-component-icon/src/scripts/Icon.js~Icon.html#static-method-load">Coral.Icon#load</a> to load the icon set on demand.</li>
</ul><h4>Unsupported styles</h4><p>Some components e.g Wait lost their variants due to the Spectrum update. For compatibility reasons, the APIs were left
untouched but will fallback to default supported options. </p><p>Below the full list of unsupported options: </p><table>
<thead>
<tr>
<th>Component</th>
<th>Property</th>
<th>Value</th>
</tr>
</thead>
<tbody>
<tr>
<td>Accordion</td>
<td><code>variant</code></td>
<td><code>QUIET</code>, <code>LARGE</code></td>
</tr>
<tr>
<td>Alert</td>
<td><code>size</code></td>
<td><code>LARGE</code></td>
</tr>
<tr>
<td>AnchorButton</td>
<td><code>size</code></td>
<td><code>LARGE</code></td>
</tr>
<tr>
<td>Autocomplete</td>
<td><code>icon</code></td>
<td></td>
</tr>
<tr>
<td>Button</td>
<td><code>size</code></td>
<td><code>LARGE</code></td>
</tr>
<tr>
<td>Popover</td>
<td><code>icon</code></td>
<td></td>
</tr>
<tr>
<td>Progress</td>
<td><code>size</code></td>
<td><code>LARGE</code></td>
</tr>
<tr>
<td>Progress</td>
<td><code>labelPosition</code></td>
<td><code>BOTTOM</code></td>
</tr>
<tr>
<td>Search</td>
<td><code>icon</code></td>
<td></td>
</tr>
<tr>
<td>Slider</td>
<td><code>vertical</code></td>
<td></td>
</tr>
<tr>
<td>Slider</td>
<td><code>tooltips</code></td>
<td></td>
</tr>
<tr>
<td>Table</td>
<td><code>variant</code></td>
<td><code>LIST</code></td>
</tr>
<tr>
<td>Tag</td>
<td><code>color</code></td>
<td><code>LIGHT_BLUE</code>, <code>PERIWINKLE</code>, <code>CYAN</code>, <code>PLUM</code>, <code>FUCHSIA</code>, <code>MAGENTA</code>, <code>TANGERINE</code>, <code>YELLOW</code>, <code>CHARTREUSE</code>, <code>KELLY_GREEN</code>, <code>SEA_FOAM</code></td>
</tr>
<tr>
<td>Tooltip</td>
<td><code>variant</code></td>
<td><code>WARNING</code></td>
</tr>
<tr>
<td>Tooltip</td>
<td><code>variant</code></td>
<td><code>INSPECT</code></td>
</tr>
<tr>
<td>Wait</td>
<td><code>variant</code></td>
<td><code>DOTS</code></td>
</tr>
</tbody>
</table><h4>Internal private markup and classes</h4><p>Due to the Spectrum CSS update, the internals of components changed e.g classes
or internal markup is different.</p><p>For instance the example below will produce a different result in Coral Spectrum compared to CoralUI3: </p><pre><code><code class="source-code prettyprint"><button is="coral-button" icon="add">Button</button></code>
</code></pre><p><em>produces in CoralUI3</em></p><pre><code><code class="source-code prettyprint"><button is="coral-button" icon="add" class="coral3-Button coral3-Button--secondary" size="M" variant="secondary">
<coral-icon class="coral3-Icon coral3-Icon--sizeS coral3-Icon--add" icon="add" size="S" alt=""></coral-icon>
<coral-button-label>Button</coral-button-label>
</button></code>
</code></pre><p><em>produces in Coral Spectrum</em></p><pre><code><code class="source-code prettyprint"><button is="coral-button" icon="add" variant="default" class="_coral-Button _coral-Button--primary" size="M">
<coral-icon size="S" class="_coral-Icon--sizeS _coral-Icon" icon="add" alt="">
<svg focusable="false" aria-hidden="true" class="_coral-Icon--svg _coral-Icon">
<use xlink:href="#spectrum-icon-18-Add"></use>
</svg>
</coral-icon>
<coral-button-label>Button</coral-button-label>
</button></code>
</code></pre><h3>Parent-child component events</h3><p>Coral Spectrum parent-child components are relying on Mutation Observers for child mutation detection (ie. child node addition/removal).
Mutation Observers are asynchronous therefore parent-child component events triggered on child mutation are triggered asynchronously e.g. :</p><pre><code><code class="source-code prettyprint">var cyclebutton = document.body.appendChild(new Coral.CycleButton());
cyclebutton.items.add({selected: true})
document.body.addEventListener('coral-cyclebutton:change', function() {
// This will be called in the next frame although it was registered after. This might be unexpected and confusing.
});
// In above situation, it's recommended to add the child component in a first step and append the parent component to the DOM in a second step
var cyclebutton = new Coral.CycleButton();
cyclebutton.items.add({selected: true});
document.body.appendChild(cyclebutton);
document.body.addEventListener('coral-cyclebutton:change', function() {
// This won't be called in the next frame because the event is silenced on purpose
});</code>
</code></pre><h3>Dependencies</h3><p>Coral Spectrum has a few dependencies and polyfills. Some are actually written and maintained by the Coral Spectrum team, and are included
without being considered an external dependency.</p><p>These dependencies are:</p><ul>
<li><a href="https://github.com/adobe/spectrum-css">Spectrum CSS</a> for the Spectrum theme and icons</li>
<li><a href="https://github.com/webcomponents/custom-elements/">Custom Elements v1 polyfill</a> with built-in components support</li>
<li><a href="https://www.npmjs.com/package/promise-polyfill">Promise polyfill</a> for IE11 support</li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill">CustomEvent polyfill</a> for IE11 support</li>
<li><a href="https://github.com/que-etc/resize-observer-polyfill">ResizeObserver polyfill</a> to detect element size changes</li>
<li>Element <code>closest(), matches(), remove() and classList</code> polyfills for IE11 support</li>
<li><a href="https://github.com/lazd/domly">DOMly</a> to render HTML templates</li>
<li><a href="https://github.com/adobe/vent">Vent</a> for DOM event delegation</li>
<li><a href="https://popper.js.org/">PopperJS</a> to manage poppers</li>
<li><a href="https://typekit.com/">Typekit</a> to load Adobe Clean fonts</li>
</ul><p><strong>Note:</strong> Calendar, Clock and Datepicker components will leverage <a href="http://momentjs.com/">moment.js</a> if loaded on the page. </p><h3>API changes</h3><ul>
<li><code>window.CustomElements</code> is removed, <code>use window.customElements</code> instead.</li>
<li><code>Coral.mixins.*</code> is removed.</li>
<li><code>coral-component:attached</code> is removed.</li>
<li><code>coral-component:detached</code> is removed.</li>
<li><code>alignMy</code> and <code>alignAt</code> are deprecated, use <code>placement</code> instead.</li>
</ul><h2>Compatibility with CoralUI3</h2><h3>Coral.register</h3><p>Coral Spectrum ships by default a compatibility package to support the 3.x way to register elements <code>Coral.register</code>.
Unfortunately, components registered with <code>Coral.register</code> can't extend Coral components e.g :</p><pre><code><code class="source-code prettyprint">Coral.register({
name: 'Element',
namespace: 'X',
tagName: 'x-element',
extend: Coral.Alert
});</code>
</code></pre><p>will not extend <code>Coral.Alert</code>. In general, it's not recommended to extend Coral components.</p><p>You can still extend other components defined via <code>Coral.register</code>:</p><pre><code><code class="source-code prettyprint">Coral.register({
name: 'Alert',
namespace: X,
tagName: 'x-alert'
});
Coral.register({
name: 'Element',
namespace: X,
tagName: 'x-element',
extend: X.Alert
});</code>
</code></pre><p>Ideally, you should not use <code>Coral.register</code> to define Custom Elements. The recommended approach is to use the native ES6
behavior : </p><pre><code><code class="source-code prettyprint">class Alert extends HTMLElement {}
// Set Alert on the X namespace
X.Alert = Alert;
// Define the custom element
customElements.define('x-alert', X.Alert);
class Element extends Alert {}
X.Element = Element;
customElements.define('x-element', X.Element);</code>
</code></pre><h3>Coral.commons.ready</h3><p>Again, the recommended approach is to use the native behavior :</p><pre><code><code class="source-code prettyprint">window.customElements.whenDefined('x-element', callback);</code>
</code></pre><p> <strong>Caution</strong>: not every Coral components is a Custom Element, some components are simple lightweight tags. They are used
for content zones and are referenced as <code>Function</code> in the documentation. </p><h3>Off-line Custom Elements v0 creation</h3><p>Another caveat is the creation of Custom Elements v0 via <code>innerHTML</code>. This is natively not supported. The compatibility
package provides a helper script to support this use case :</p><pre><code><code class="source-code prettyprint">document.registerElement("x-element", {
prototype: Prototype
});
d = document.createElement('div');
d.innerHTML = '<x-element></x-element>';
// The component is not initialized above. The workaround is to use the helper script instead as below :
document.registerElement.innerHTML(d, '<x-element></x-element>'); </code>
</code></pre></div>
<a data-ice="link" href="manual/upgrade.html"></a>
</div>
</div>
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Styles</h1><h2>Theme (light, dark, lightest, darkest)</h2><p>The default Coral Spectrum styles cascade from <code>coral--light</code>, <code>coral--lightest</code>, <code>coral--dark</code> and <code>coral--darkest</code> theme, so that class must be specified at a higher level.</p><pre><code><code class="source-code prettyprint"><body class="coral--light">
<!-- light theme -->
<div class="container"></div>
<div class="coral--dark">
<!-- dark theme -->
</div>
</body></code>
</code></pre><h2>Large scale support</h2><p>For mobile, Spectrum has a larger scale that enables larger tap targets on all controls. To enable it, the class <code>coral--large</code> must be specified at a higher level.</p><pre><code><code class="source-code prettyprint"><body class="coral--light coral--large">
<!-- light theme -->
<!-- large scale -->
</body></code>
</code></pre><h2>CSS utility classes</h2><p>Coral Spectrum provides some CSS utility classes that can be applied to any DOM element. </p><h3>u-coral-clearFix</h3><p>Applies the clearfix hack.</p><h3>u-coral-noBorder</h3><p>Removes all the borders of an element.</p><h3>u-coral-noScroll</h3><p>Stops an element from scrolling.</p><h3>u-coral-screenReaderOnly</h3><p>Hides elements from visual browsers.</p><h3>u-coral-closedHand</h3><p>A closed hand cursor that indicates an item is current grabbed.</p><h3>u-coral-openHand</h3><p>An open hand cursor to indicate that an item can be grabbed.</p><h3>u-coral-pullLeft</h3><p>Floats the content to the left.</p><h3>u-coral-pullRight</h3><p>Floats the content to the right.</p><h3>u-coral-padding</h3><p>Adds the default padding on all sides.</p><h3>u-coral-padding-horizontal</h3><p>Adds the default padding to left and right.</p><h3>u-coral-padding-vertical</h3><p>Adds the default padding to top and bottom.</p><h3>u-coral-margin</h3><p>Adds the default the margin on all sides.</p><h3>u-coral-noPadding</h3><p>Removes the padding on all sides.</p><h3>u-coral-noPadding-horizontal</h3><p>Removes the padding on the left and right side.</p><h3>u-coral-noPadding-vertical</h3><p>Removes the padding on the top and bottom side.</p><h3>u-coral-noMargin</h3><p>Removes the margin on all sides.</p><h3>u-coral-ellipsis</h3><p>Prevent text from wrapping, use an ellipsis to truncate.</p><h3>u-coral-visibleXS | u-coral-hiddenXS</h3><p>Extra small device.</p><h3>u-coral-visibleS | u-coral-hiddenS</h3><p>Small device.</p><h3>u-coral-visibleM | u-coral-hiddenM</h3><p>Medium device.</p><h3>u-coral-visibleL | u-coral-hiddenL</h3><p>Large device.</p><h3>u-coral-visibleXL | u-coral-hiddenXL</h3><p>Extra large device.</p><h3>u-coral-visibleXXL | u-coral-hiddenXXL</h3><p>Above extra large device.</p><h2>Fonts via Typekit</h2><p>Coral Spectrum uses Typekit to securely deliver the Adobe Clean corporate font.</p><h3>Domains</h3><p>It comes pre-configured with a kit that is limited to certain domains including :</p><ul>
<li>localhost</li>
<li>127.0.0.1</li>
<li>0.0.0.0</li>
<li>*.adobe.com</li>
</ul><p>If you are using Coral Spectrum on a server on a domain other than these, you will need to request and configure your own Typekit kit.
Reach out to the Typekit team on <a href="https://fonts.adobe.com/">https://fonts.adobe.com/</a>.</p><h3>Using a Custom Kit with Coral Spectrum</h3><p>Include your Typekit ID as a Coral Spectrum option e.g. :</p><pre><code><code class="source-code prettyprint"><script src="js/coral.min.js" data-coral-typekit="TYPEKIT_ID"></script></code>
</code></pre><h3>Font loading</h3><p>Typekit typically relies on a <code>.wf-loading</code> selector to hide content and prevent the Flash Of Unstyled Text (FOUT) that
is associated with web fonts.</p><pre><code><code class="source-code prettyprint">.wf-loading {
visibility: hidden;
}</code>
</code></pre><p>That selector would work in conjunction with the function in the typekit.js JavaScript file to remove the selector from
the DOM when Typekit has loaded. However, experience has shown that hiding content and blocking until Typekit loads can
make the page or app unresponsive on initial load.</p><p>Coral Spectrum remains agnostic. Consumers must implement their own solution to avoid Flash Of Unstyled Text during font loading.</p></div>
<a data-ice="link" href="manual/styles.html"></a>
</div>
</div>
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Architecture</h1><h2>Web Components</h2><p>Coral Spectrum hides implementation detail from consumers by leveraging the <a href="https://html.spec.whatwg.org/multipage/custom-elements.html">Custom Elements v1</a>
specification, which is part of the emerging <a href="https://www.webcomponents.org/introduction">Web Components</a> standard.</p><p><strong>Therefore any Coral CSS classes and attributes not explicitly mentioned in the public documentation are private and subject to change.
Their direct use is not recommended and at high risk of breaking after subsequent updates of Coral Spectrum library.</strong></p><p>Custom elements allow Coral Spectrum to define new types of DOM elements to be used in an HTML document. As a result, Coral Spectrum
can extend native elements like a button or text input to provide additional functionality or it can provide completely
new elements like a progress indicator. Consumers can then use these elements using their custom tags (e.g., <code><coral-progress></code>)
and directly interact with their custom properties.</p><p>A strong advantage Coral Spectrum derives from Custom Elements is the ability to hide many implementation details from the consumer.
While a progress indicator may be composed of a variety of spans, divs, or images, these are underlying details that shouldn't
concern consumers. Rather than consumers copying and maintaining large swaths of code containing all these elements with their
various attributes, they are typically able to use a simple Custom Element tag and the underlying elements are seamlessly
produced by Coral Spectrum on their behalf. By keeping implementation details internal to components, the exposed public API is
minimized and more explicit resulting in a lower risk of introducing breaking changes. </p><p>For now, we have not implemented Shadow DOM or other aspects of the Web Components specification due to lack of browser
native support but also polyfill performance issues. </p><p>Custom Elements can be used before their definition is registered. Progressive enhancement is a feature of Custom Elements.
To know when an element or a set of elements becomes defined, you can use <code>Coral.commons.ready(el, callback)</code>;</p><h2>Content Zones</h2><p>Without shadow DOM, we need some way to mix user-provided content with presentational elements. Our answer to this is content zones.
Essentially, we have simple, brainless HTML tags that serve as wrappers for content.
Users provide these tags when creating elements from markup, and after we render the template, we simply move these content zones into place.</p><p>This <code>Coral.Alert</code> markup shows content zones for header and content areas of the component:</p><pre><code><code class="source-code prettyprint"><coral-alert>
<coral-alert-header>INFO</coral-alert-header>
<coral-alert-content>This is is an alert.</coral-alert-content>
</coral-alert></code>
</code></pre><p>Additionally, in the same way you can access the body of the HTML document with document.body, we create references for
each content zone on the JavaScript object that corresponds to the component. You can access the header content zone with
<code>alert.header</code> and change its content e.g append elements or do whatever else you need to do.</p><h2>Dependencies</h2><p>Coral Spectrum has a few dependencies and polyfills. Some are actually written and maintained by the Coral Spectrum team, and are included
without being considered an external dependency.</p><p>These dependencies are:</p><ul>
<li><a href="https://github.com/adobe/spectrum-css">Spectrum CSS</a> for the Spectrum theme and icons</li>
<li><a href="https://github.com/webcomponents/custom-elements/">Custom Elements v1 polyfill</a> with built-in components support</li>
<li><a href="https://www.npmjs.com/package/promise-polyfill">Promise polyfill</a> for IE11 support</li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent#Polyfill">CustomEvent polyfill</a> for IE11 support</li>
<li><a href="https://github.com/que-etc/resize-observer-polyfill">ResizeObserver polyfill</a> to detect element size changes</li>
<li>Element <code>closest(), matches(), remove() and classList</code> polyfills for IE11 support</li>
<li><a href="https://github.com/lazd/domly">DOMly</a> to render HTML templates</li>
<li><a href="https://github.com/adobe/vent">Vent</a> for DOM event delegation</li>
<li><a href="https://popper.js.org/">PopperJS</a> to manage poppers</li>
<li><a href="https://typekit.com/">Typekit</a> to load Adobe Clean fonts</li>
</ul><p><strong>Note:</strong> Calendar, Clock and Datepicker components will leverage <a href="http://momentjs.com/">moment.js</a> if loaded on the page. </p></div>
<a data-ice="link" href="manual/architecture.html"></a>
</div>
</div>
<div class="manual-card-wrap" data-ice="cards">
<div class="manual-card">
<div data-ice="card"><h1>Contribution</h1><p>We love pull requests from everyone.</p><p>The following are a set of guidelines to follow when contributing to this project.</p><h2>Code Of Conduct</h2><p>This project adheres to the Adobe <a href="./manual/CODE_OF_CONDUCT.md">code of conduct</a>. By participating,
you are expected to uphold this code. Please report unacceptable behavior to
<a href="./manual/mailto:Grp-opensourceoffice@adobe.com">Grp-opensourceoffice@adobe.com</a>.</p><h2>Have A Question?</h2><p>Start by filing an issue. The existing committers on this project work to reach
consensus around project direction and issue solutions within issue threads
(when appropriate).</p><h3>Security Issues</h3><p>Security issues shouldn't be reported on this issue tracker. Instead, <a href="https://helpx.adobe.com/security/alertus.html">file an issue to our security experts</a>.</p><h2>Contributor License Agreement</h2><p>All third-party contributions to this project must be accompanied by a signed contributor
license agreement. This gives Adobe permission to redistribute your contributions
as part of the project. <a href="http://opensource.adobe.com/cla.html">Sign our CLA</a>. You
only need to submit an Adobe CLA one time, so if you have submitted one previously,
you are good to go!</p><h2>Code Reviews</h2><p>All submissions should come in the form of pull requests and need to be reviewed
by project committers.</p><p>Start by <a href="https://help.github.com/articles/fork-a-repo/">forking</a> the repo, then <a href="https://help.github.com/articles/cloning-a-repository/">clone</a> your fork:</p><pre><code><code class="source-code prettyprint">git clone git@github.com:yourusername/coral-spectrum.git</code>
</code></pre><p>Set up a branch for your feature or bug fix, push it to your fork, and set up a remote for the upstream repo:</p><pre><code><code class="source-code prettyprint">git checkout -b my-awesome-new-feature
git push -u origin my-awesome-new-feature
git remote add upstream git@github.com:adobe/coral-spectrum.git</code>
</code></pre><p>Install dependencies:</p><pre><code><code class="source-code prettyprint">npm install</code>
</code></pre><p>Make sure the <a href="https://github.com/gulpjs/gulp-cli">gulp-cli</a> is installed globally:</p><pre><code><code class="source-code prettyprint">npm install -g gulp-cli</code>
</code></pre><p>Build the project, open a browser window, and watch for changes:</p><pre><code><code class="source-code prettyprint">gulp</code>
</code></pre><p>Commit changes, referencing the relevant issue number (if any):</p><pre><code><code class="source-code prettyprint">git commit -m "Cool stuff, closes #250, fixes #252"</code>
</code></pre><p>Consider starting the commit message with an applicable emoji:</p><ul>
<li>:art: <code>:art:</code> when improving the format/structure of the code</li>
<li>:zap: <code>:zap:</code> when improving performance</li>
<li>:non-potable_water: <code>:non-potable_water:</code> when plugging memory leaks</li>
<li>:memo: <code>:memo:</code> when writing docs</li>
<li>:ambulance: <code>:ambulance:</code> a critical hotfix.</li>
<li>:sparkles: <code>:sparkles:</code> when introducing new features</li>
<li>:bookmark: <code>:bookmark:</code> when releasing / version tags</li>
<li>:rocket: <code>:rocket:</code> when deploying stuff</li>
<li>:penguin: <code>:penguin:</code> when fixing something on Android</li>
<li>:apple: <code>:apple:</code> when fixing something on iOS</li>
<li>:checkered_flag: <code>:checkered_flag:</code> when fixing something on Windows</li>
<li>:bug: <code>:bug:</code> when fixing a bug</li>
<li>:fire: <code>:fire:</code> when removing code or files</li>
<li>:green_heart: <code>:green_heart:</code> when fixing the CI build</li>
<li>:white_check_mark: <code>:white_check_mark:</code> when adding tests</li>
<li>:lock: <code>:lock:</code> when dealing with security</li>
<li>:arrow_up: <code>:arrow_up:</code> when upgrading dependencies</li>
<li>:arrow_down: <code>:arrow_down:</code> when downgrading dependencies</li>
<li>:shirt: <code>:shirt:</code> when removing linter warnings</li>
<li>:hammer: <code>:hammer:</code> when doing heavy refactoring</li>
<li>:heavy_minus_sign: <code>:heavy_minus_sign:</code> when removing a dependency.</li>
<li>:heavy_plus_sign: <code>:heavy_plus_sign:</code> when adding a dependency.</li>
<li>:wrench: <code>:wrench:</code> when changing configuration files.</li>
<li>:globe_with_meridians: <code>:globe_with_meridians:</code> when dealing with internationalization and localization.</li>
<li>:pencil2: <code>:pencil2:</code> when fixing typos.</li>
<li>:hankey: <code>:hankey:</code> when writing bad code that needs to be improved.</li>
<li>:package: <code>:package:</code> when updating compiled files or packages.</li>
</ul><p>Make sure your branch is up to date with the original repo:</p><pre><code><code class="source-code prettyprint">git fetch upstream
git merge upstream/master</code>
</code></pre><p>Review your changes and any possible conflicts and push to your fork:</p><pre><code><code class="source-code prettyprint">git push origin</code>
</code></pre><p><a href="https://help.github.com/articles/creating-a-pull-request/">Submit a pull request</a>.</p><p>At this point you're waiting on us. We do our best to keep on top of all the pull requests. We may suggest some changes, improvements or alternatives.</p><p>Some things that will increase the chance that your pull request is accepted:</p><ul>
<li>Write a <a href="http://chris.beams.io/posts/git-commit/">good commit message</a>.</li>
<li>Make sure the PR merges cleanly with the latest master.</li>
<li>Describe your feature/bugfix and why it's needed/important in the pull request description. </li>
</ul></div>
<a data-ice="link" href="manual/contribution.html"></a>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
Generated by <a href="https://esdoc.org">ESDoc<span data-ice="esdocVersion">(1.1.0)</span><img src="./image/esdoc-logo-mini-black.png"></a>
</footer>
<script src="script/search_index.js"></script>
<script src="script/search.js"></script>
<script src="script/pretty-print.js"></script>
<script src="script/inherited-summary.js"></script>
<script src="script/test-summary.js"></script>
<script src="script/inner-link.js"></script>
<script src="script/patch-for-local.js"></script>
</body>
</html>