@adobe/coral-spectrum

<!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" 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" data-ice="content"><h1 id="upgrade">Upgrade</h1><h2 id="from-coralui3-to-coral-spectrum">From CoralUI3 to Coral Spectrum</h2><h3 id="custom-elements-v1">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 id="spectrum">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 id="performance">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 id="overlay-mechanism">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 id="upgrade-changes">Upgrade changes</h2><h3 id="custom-elements-v1">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 id="spectrum">Spectrum</h3><p>Due to the new Spectrum design, some components were updated to accommodate design pattern changes:</p> <h4 id="selection-pattern-for-table--columnview-and-masonry">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 id="svg-icons">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 id="unsupported-styles">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 id="internal-private-markup-and-classes">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 id="parent-child-component-events">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 id="dependencies">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 id="api-changes">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 id="compatibility-with-coralui3">Compatibility with CoralUI3</h2><h3 id="coral-register">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 id="coral-commons-ready">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 id="off-line-custom-elements-v0-creation">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> </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>