Meet Coral Spectrum

Coral Spectrum is a JavaScript library of Web Components following Spectrum design patterns.

Showcase

All components can be seen in action here. These are only examples and don't cover all scenarios. The API documentation can be found in the references.
A playground is available here 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.

Spectrum

The current default theme is is an implementation of the Spectrum 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.

Coral Spectrum leverages the Spectrum CSS framework to style components including the Spectrum SVG icons.

Angular, React, Vue.js compatibility

Our vision is to create consistent Adobe experiences by providing a complete, easy to use library of HTML components compatible with major frameworks.

To reach the goal, Coral Spectrum derives from Custom Elements v1 with native support 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.

» Overview

Vision and goals

» Manual

Get you started. How to consume and build the project

» Upgrade

Helping you upgrade from CoralUI3

» Styles

Theme, public CSS and Typekit

» Architecture

Technical decisions behind the architecture

» Contribution

Open development principles

Important

Please follow the Commit Message Conventions. To easily comply, it is recommended to use cz-cli.

Showcase

Component Examples

To see all components in action. These are only examples and don't cover all scenarios.

API References

Covers the API for all components including properties, events and more.

Playground

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.

Spectrum

Coral Spectrum leverages the Spectrum CSS framework to style components including the Spectrum SVG icons.

Angular, React, Vue.js compatibility

Our vision is to create consistent Adobe experiences by providing a complete, easy to use library of HTML components compatible with major frameworks.

Browser support

Coral Spectrum is designed to support the following browsers:

Chrome (latest)
Safari (latest)
Firefox (latest)
Edge (latest)
IE 11
iOS 7+
Android 4.4+

Theme (light, dark, lightest, darkest)

The default Coral Spectrum styles cascade from coral--light, coral--lightest, coral--dark and coral--darkest theme, so that class must be specified at a higher level.

<body class="coral--light">
    <!-- light theme -->
    <div class="container"></div>
    <div class="coral--dark">
        <!-- dark theme -->
    </div>
</body>

Large scale support

For mobile, Spectrum has a larger scale that enables larger tap targets on all controls. To enable it, the class coral--large must be specified at a higher level.

<body class="coral--light coral--large">
   <!-- light theme -->
   <!-- large scale -->
</body>

Built-in Accessibility and Keyboard support

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.

Internationalization support

Coral Spectrum provides a robust internal system for internationalization of its strings. This is done via an internal Adobe process.

Supported languages are :

Language family	Language tag	Language variant
English	en-US	American English
French	fr-FR	Standard French
German	de-DE	Standard German
Italian	it-IT	Standard Italian
Spanish	es-ES	Castilian Spanish
Portuguese	pt-BR	Brazilian Portuguese
Japanese	ja-JP	Standard Japanese
Korean	ko-KR	Standard Korean
Chinese	zh-CN	Mainland China, simplified characters
Chinese	zh-TW	Taiwan, traditional characters
Dutch	nl-NL	Netherlands Dutch
Danish	da-DK	Standard Danish
Finnish	fi-FI	Standard Finnish
Norwegian	no-NO	Standard Norwegian
Swedish	sv-SE	Standard Swedish
Czech	cs-CZ	Standard Czech
Polish	pl-PL	Standard Polish
Russian	ru-RU	Standard Russian
Turkish	tr-TR	Standard Turkish

Using Coral Spectrum

Easiest way via a CDN

The easiest way to consume Coral Spectrum is to use a CDN e.g. copy these lines into your html file.

<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>

Copying the distribution files

You can download a packaged/published version of @adobe/coral-spectrum from npm:

npm pack @adobe/coral-spectrum

After you've unzipped the downloaded package, look for the dist folder and :

Copy the files from dist/css, dist/js and dist/resources in your project.
Reference the files in your page e.g

<link rel="stylesheet" href="css/coral.min.css">
<script src="js/coral.min.js"></script>

Including entire library with a bundler like parcel

npm install @adobe/coral-spectrum

then in your main js, use:

require("@adobe/coral-spectrum/dist/js/coral.js");
require("@adobe/coral-spectrum/dist/css/coral.css");

Including only the components you need

If your project only requires a few components, you can use a module bundler like Webpack to only import the components needed. Below is an example of a Webpack config:

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 } }],
      }
    })
  ]
};

Then in your index.js file, you can import and use single components :

// Import Component
import {Button} from '@adobe/coral-spectrum/coral-component-button';

const button = new Button();

If icons are not displayed, ensure the path to the styles and icons are set e.g. :

<link rel="stylesheet" href="dist/style.min.css">
<script data-coral-icons="dist/icons/" src="dist/bundle.min.js"></script>

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:

<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>

Note: Calendar, Clock and Datepicker components will leverage moment.js if available.

Contributing

Check out the contributing guidelines.

Building and Testing

Run the following commands first :

npm install -g gulp-cli
npm install

You can use below tasks to get started:

gulp to generate the build in the dist folder and run the dev server on localhost:9001 by default.
gulp build to generate the build in the dist folder.
gulp dev to run the dev server on localhost:9001 by default.
gulp test to run the tests. Test reports are in dist/coverage.
gulp docs to build the documentation in dist/documentation.
gulp axe to run the accessibility checks.

Each component can be built independently e.g. cd coral-component-button && gulp.

Releasing

Automatic release:

Merging the PR to master will trigger an automatic release Github Action. It is important to follow Angular Commit Message Conventions. It is recommended to use cz-cli for easy commits. Only fix and feat can trigger a release. If you want to skip release add [skip release] or [release skip] to the commit message

Manual releasing:

We are currently releasing this package on npm.

Before we get started, clean up your dependencies with the following command :

git checkout master
rm -rf node_modules && npm install

Then run gulp release. You'll be asked to bump the version (minor version bump by default). Coral Spectrum is following semantic versioning (either patch, minor or major).

The command will take care of increasing, tagging the version and publishing the package to npm.

If everything went well, run gulp deploy to publish the documentation on the gh-pages branch else revert the version bump.

Overview

Introduction

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.

Unified Experience

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.

Enhanced API

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.

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.

Future Thinking

Coral Spectrum is pushing the web forward by leveraging the Web Components specification. However, given the landscape of browser implementation and the state of the polyfill ecosystem, we decided to only implement Custom Elements v1 at this time.

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.

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.

Spectrum

Coral Spectrum leverages the Spectrum CSS framework to style components including the Spectrum SVG icons.

Built-in Accessibility and Keyboard support

Internationalization support

Coral Spectrum provides a robust internal system for internationalization of its strings. This is done via an internal Adobe process.

Supported languages are :

Language family	Language tag	Language variant
English	en-US	American English
French	fr-FR	Standard French
German	de-DE	Standard German
Italian	it-IT	Standard Italian
Spanish	es-ES	Castilian Spanish
Portuguese	pt-BR	Brazilian Portuguese
Japanese	ja-JP	Standard Japanese
Korean	ko-KR	Standard Korean
Chinese	zh-CN	Mainland China, simplified characters
Chinese	zh-TW	Taiwan, traditional characters
Dutch	nl-NL	Netherlands Dutch
Danish	da-DK	Standard Danish
Finnish	fi-FI	Standard Finnish
Norwegian	no-NO	Standard Norwegian
Swedish	sv-SE	Standard Swedish
Czech	cs-CZ	Standard Czech
Polish	pl-PL	Standard Polish
Russian	ru-RU	Standard Russian
Turkish	tr-TR	Standard Turkish

Browser Support

Coral Spectrum is designed to support the following browsers:

Chrome (latest)
Safari (latest)
Firefox (latest)
Edge (latest)
IE 11
iOS 7+
Android 4.4+

Backwards Compatibility

Coral Spectrum ships by default a compatibility package to support the CoralUI 3.x way to register elements Coral.register. 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.

Manual

Using Coral Spectrum

Easiest way via a CDN

The easiest way to consume Coral Spectrum is to use a CDN e.g. copy these lines into your html file.

<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>

Copying the distribution files

You can also download the distribution package of the latest release by running npm i @adobe/coral-spectrum. It includes all components and styles.

After you've unzipped the package, look for the dist folder and :

Copy the files from dist/css, dist/js and dist/resources in your project.

Reference the files in your page with :

<link rel="stylesheet" href="css/coral.min.css">
<script src="js/coral.min.js"></script>

Using a bundler like Webpack

If your project only requires a few components, you can use a module bundler like Webpack to only import the components needed. Below is an example of a Webpack config:

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 } }],
      }
    })
  ]
};

Then in your index.js file, you can import and use single components :

// Import Component
import {Button} from '@adobe/coral-spectrum/coral-component-button';

const button = new Button();

If icons are not displayed, ensure the path to the styles and icons are set e.g. :

<link rel="stylesheet" href="dist/style.min.css">
<script data-coral-icons="dist/icons/" src="dist/bundle.min.js"></script>

Note: Calendar, Clock and Datepicker components will leverage moment.js if available.

Building and Testing

Run the following commands first :

npm install -g gulp-cli
npm install

You can use below tasks to get started:

gulp to generate the build in the dist folder and run the dev server on localhost:9001 by default.
gulp build to generate the build in the dist folder.
gulp dev to run the dev server on localhost:9001 by default.
gulp test to run the tests. Test reports are in dist/coverage.
gulp docs to build the documentation in dist/documentation.
gulp axe to run the accessibility checks.

Each component can be built independently e.g. cd coral-component-button && gulp.

Releasing

We are currently releasing this package on npm.

Before we get started, clean up your dependencies with the following command :

git checkout master
rm -rf node_modules && npm install

Then run gulp release. You'll be asked to bump the version (minor version bump by default). Coral Spectrum is following semantic versioning (either patch, minor or major).

The command will take care of increasing, tagging the version and publishing the package to npm.

If everything went well, run gulp deploy to publish the documentation on the gh-pages branch else revert the version bump.

Upgrade

From CoralUI3 to Coral Spectrum

Custom Elements v1

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 Custom Elements v1 with native support 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.

Spectrum

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.

Coral Spectrum leverages the Spectrum CSS framework to style components including the Spectrum SVG icons.

Performance

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.

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 Coral.commons.ready() becomes obsolete in most cases.

On the other hand, all Coral Spectrum parent-child components are using asynchronous Mutation Observers replacing the slow and synchronous events coral-component:attached and coral-component:detached.

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).

The performance boost is visible by the test execution time:

CoralUI 3 UTs results

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)

Coral Spectrum UTs results (contains more tests due to full clone node support but still performs faster)

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)

Overlay mechanism

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.

Upgrade changes

Custom Elements v1

A major change in v1 is that component initialization is now done in an ES6 class constructor. The list of Requirements for custom element constructors prohibits a new component from setting attributes or adding child nodes in its constructor.

Let's have a look at a concrete example

With 3.x you could do following:

var alert = new Coral.Alert();
var header = alert.querySelector('coral-alert-header');
header.textContent = 'Info';

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.

var alert = new Coral.Alert();
var header = alert.header; // Use the JS API to access the content zone
header.textContent = 'Info';

Spectrum

Due to the new Spectrum design, some components were updated to accommodate design pattern changes:

Selection pattern for Table, ColumnView and Masonry

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.

SVG Icons

Coral Spectrum ships SVG icons that need to be loaded first before being displayed. There are several ways to load the icons:

Reuse the same file structure as in the dist folder with css/coral.css, js/coral.js and resources/*.svg.
Add data-coral-icons="PATH_TO_RESOURCES_FOLDER" to the <script> loading Coral Spectrum. See options for details.
Use Coral.Icon#load to load the icon set on demand.

Unsupported styles

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.

Below the full list of unsupported options:

Component	Property	Value
Accordion	`variant`	`QUIET`, `LARGE`
Alert	`size`	`LARGE`
AnchorButton	`size`	`LARGE`
Autocomplete	`icon`
Button	`size`	`LARGE`
Popover	`icon`
Progress	`size`	`LARGE`
Progress	`labelPosition`	`BOTTOM`
Search	`icon`
Slider	`vertical`
Slider	`tooltips`
Table	`variant`	`LIST`
Tag	`color`	`LIGHT_BLUE`, `PERIWINKLE`, `CYAN`, `PLUM`, `FUCHSIA`, `MAGENTA`, `TANGERINE`, `YELLOW`, `CHARTREUSE`, `KELLY_GREEN`, `SEA_FOAM`
Tooltip	`variant`	`WARNING`
Tooltip	`variant`	`INSPECT`
Wait	`variant`	`DOTS`

Internal private markup and classes

Due to the Spectrum CSS update, the internals of components changed e.g classes or internal markup is different.

For instance the example below will produce a different result in Coral Spectrum compared to CoralUI3:

<button is="coral-button" icon="add">Button</button>

produces in CoralUI3

<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>

produces in Coral Spectrum

<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>

Parent-child component events

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. :

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     
});

Dependencies

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.

These dependencies are:

Spectrum CSS for the Spectrum theme and icons
Custom Elements v1 polyfill with built-in components support
Promise polyfill for IE11 support
CustomEvent polyfill for IE11 support
ResizeObserver polyfill to detect element size changes
Element closest(), matches(), remove() and classList polyfills for IE11 support
DOMly to render HTML templates
Vent for DOM event delegation
PopperJS to manage poppers
Typekit to load Adobe Clean fonts

Note: Calendar, Clock and Datepicker components will leverage moment.js if loaded on the page.

API changes

window.CustomElements is removed, use window.customElements instead.
Coral.mixins.* is removed.
coral-component:attached is removed.
coral-component:detached is removed.
alignMy and alignAt are deprecated, use placement instead.

Compatibility with CoralUI3

Coral.register

Coral Spectrum ships by default a compatibility package to support the 3.x way to register elements Coral.register. Unfortunately, components registered with Coral.register can't extend Coral components e.g :

Coral.register({
    name: 'Element',
    namespace: 'X',
    tagName: 'x-element',
    extend: Coral.Alert
});

will not extend Coral.Alert. In general, it's not recommended to extend Coral components.

You can still extend other components defined via Coral.register:

Coral.register({
    name: 'Alert',
    namespace: X,
    tagName: 'x-alert'
});
 Coral.register({
    name: 'Element',
    namespace: X,
    tagName: 'x-element',
    extend: X.Alert
});

Ideally, you should not use Coral.register to define Custom Elements. The recommended approach is to use the native ES6 behavior :

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);

Coral.commons.ready

Again, the recommended approach is to use the native behavior :

window.customElements.whenDefined('x-element', callback);

Caution: not every Coral components is a Custom Element, some components are simple lightweight tags. They are used for content zones and are referenced as Function in the documentation.

Off-line Custom Elements v0 creation

Another caveat is the creation of Custom Elements v0 via innerHTML. This is natively not supported. The compatibility package provides a helper script to support this use case :

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>');

Styles

Theme (light, dark, lightest, darkest)

The default Coral Spectrum styles cascade from coral--light, coral--lightest, coral--dark and coral--darkest theme, so that class must be specified at a higher level.

<body class="coral--light">
    <!-- light theme -->
    <div class="container"></div>
    <div class="coral--dark">
        <!-- dark theme -->
    </div>
</body>

Large scale support

For mobile, Spectrum has a larger scale that enables larger tap targets on all controls. To enable it, the class coral--large must be specified at a higher level.

<body class="coral--light coral--large">
   <!-- light theme -->
   <!-- large scale -->
</body>

CSS utility classes

Coral Spectrum provides some CSS utility classes that can be applied to any DOM element.

u-coral-clearFix

Applies the clearfix hack.

u-coral-noBorder

Removes all the borders of an element.

u-coral-noScroll

Stops an element from scrolling.

u-coral-screenReaderOnly

Hides elements from visual browsers.

u-coral-closedHand

A closed hand cursor that indicates an item is current grabbed.

u-coral-openHand

An open hand cursor to indicate that an item can be grabbed.

u-coral-pullLeft

Floats the content to the left.

u-coral-pullRight

Floats the content to the right.

u-coral-padding

Adds the default padding on all sides.

u-coral-padding-horizontal

Adds the default padding to left and right.

u-coral-padding-vertical

Adds the default padding to top and bottom.

u-coral-margin

Adds the default the margin on all sides.

u-coral-noPadding

Removes the padding on all sides.

u-coral-noPadding-horizontal

Removes the padding on the left and right side.

u-coral-noPadding-vertical

Removes the padding on the top and bottom side.

u-coral-noMargin

Removes the margin on all sides.

u-coral-ellipsis

Prevent text from wrapping, use an ellipsis to truncate.

u-coral-visibleXS | u-coral-hiddenXS

Extra small device.

u-coral-visibleS | u-coral-hiddenS

Small device.

u-coral-visibleM | u-coral-hiddenM

Medium device.

u-coral-visibleL | u-coral-hiddenL

Large device.

u-coral-visibleXL | u-coral-hiddenXL

Extra large device.

u-coral-visibleXXL | u-coral-hiddenXXL

Above extra large device.

Fonts via Typekit

Coral Spectrum uses Typekit to securely deliver the Adobe Clean corporate font.

Domains

It comes pre-configured with a kit that is limited to certain domains including :

localhost
127.0.0.1
0.0.0.0
*.adobe.com

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 https://fonts.adobe.com/.

Using a Custom Kit with Coral Spectrum

Include your Typekit ID as a Coral Spectrum option e.g. :

<script src="js/coral.min.js" data-coral-typekit="TYPEKIT_ID"></script>

Font loading

Typekit typically relies on a .wf-loading selector to hide content and prevent the Flash Of Unstyled Text (FOUT) that is associated with web fonts.

.wf-loading {
  visibility: hidden;
}

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.

Coral Spectrum remains agnostic. Consumers must implement their own solution to avoid Flash Of Unstyled Text during font loading.

Architecture

Web Components

Coral Spectrum hides implementation detail from consumers by leveraging the Custom Elements v1 specification, which is part of the emerging Web Components standard.

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.

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., <coral-progress>) and directly interact with their custom properties.

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.

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.

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 Coral.commons.ready(el, callback);

Content Zones

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.

This Coral.Alert markup shows content zones for header and content areas of the component:

<coral-alert>
  <coral-alert-header>INFO</coral-alert-header>
  <coral-alert-content>This is is an alert.</coral-alert-content>
</coral-alert>

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 alert.header and change its content e.g append elements or do whatever else you need to do.

Dependencies

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.

These dependencies are:

Spectrum CSS for the Spectrum theme and icons
Custom Elements v1 polyfill with built-in components support
Promise polyfill for IE11 support
CustomEvent polyfill for IE11 support
ResizeObserver polyfill to detect element size changes
Element closest(), matches(), remove() and classList polyfills for IE11 support
DOMly to render HTML templates
Vent for DOM event delegation
PopperJS to manage poppers
Typekit to load Adobe Clean fonts

Note: Calendar, Clock and Datepicker components will leverage moment.js if loaded on the page.

Contribution

We love pull requests from everyone.

The following are a set of guidelines to follow when contributing to this project.

Code Of Conduct

This project adheres to the Adobe code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to Grp-opensourceoffice@adobe.com.

Have A Question?

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).

Security Issues

Security issues shouldn't be reported on this issue tracker. Instead, file an issue to our security experts.

Contributor License Agreement

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. Sign our CLA. You only need to submit an Adobe CLA one time, so if you have submitted one previously, you are good to go!

Code Reviews

All submissions should come in the form of pull requests and need to be reviewed by project committers.

Start by forking the repo, then clone your fork:

git clone git@github.com:yourusername/coral-spectrum.git

Set up a branch for your feature or bug fix, push it to your fork, and set up a remote for the upstream repo:

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

Install dependencies:

npm install

Make sure the gulp-cli is installed globally:

npm install -g gulp-cli

Build the project, open a browser window, and watch for changes:

gulp

Commit changes, referencing the relevant issue number (if any):

git commit -m "Cool stuff, closes #250, fixes #252"

Consider starting the commit message with an applicable emoji:

:art: :art: when improving the format/structure of the code
:zap: :zap: when improving performance
:non-potable_water: :non-potable_water: when plugging memory leaks
:memo: :memo: when writing docs
:ambulance: :ambulance: a critical hotfix.
:sparkles: :sparkles: when introducing new features
:bookmark: :bookmark: when releasing / version tags
:rocket: :rocket: when deploying stuff
:penguin: :penguin: when fixing something on Android
:apple: :apple: when fixing something on iOS
:checkered_flag: :checkered_flag: when fixing something on Windows
:bug: :bug: when fixing a bug
:fire: :fire: when removing code or files
:green_heart: :green_heart: when fixing the CI build
:white_check_mark: :white_check_mark: when adding tests
:lock: :lock: when dealing with security
:arrow_up: :arrow_up: when upgrading dependencies
:arrow_down: :arrow_down: when downgrading dependencies
:shirt: :shirt: when removing linter warnings
:hammer: :hammer: when doing heavy refactoring
:heavy_minus_sign: :heavy_minus_sign: when removing a dependency.
:heavy_plus_sign: :heavy_plus_sign: when adding a dependency.
:wrench: :wrench: when changing configuration files.
:globe_with_meridians: :globe_with_meridians: when dealing with internationalization and localization.
:pencil2: :pencil2: when fixing typos.
:hankey: :hankey: when writing bad code that needs to be improved.
:package: :package: when updating compiled files or packages.

Make sure your branch is up to date with the original repo:

git fetch upstream
git merge upstream/master

Review your changes and any possible conflicts and push to your fork:

git push origin

Submit a pull request.

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.

Some things that will increase the chance that your pull request is accepted:

Write a good commit message.
Make sure the PR merges cleanly with the latest master.
Describe your feature/bugfix and why it's needed/important in the pull request description.