Skip to content
This repository has been archived by the owner on Feb 24, 2023. It is now read-only.

Latest commit

 

History

History
270 lines (198 loc) · 18 KB

README.md

File metadata and controls

270 lines (198 loc) · 18 KB
Raw

ARCHIVED

Salesforce Lightning Design System for React – Integration with UXPin Merge

alt text

About Salesforce Lightning Design System for React and this repository.

Salesforce Lightning Design System for React is the React implementation of the Salesforce Lightning Design System.

This repository represents a test implementation of Salesforce Lightning components with UXPin Merge Technology. To make this implementation few changes were introduced to Salesforce Lighting:

  • Every component is now stored in an individual directory – e.g. ./components/accordion/accordion-panel.
  • In order to preserve all the component imports – index.js files were introduced. Index files are only importing and exporting a component in a given directory.
  • Preset directories were introduced. Preset files tell UXPin Merge how to initially render every component. E.g. .componnets/accordion/presets/0-default.jsx (both name of the directory – presets and name of the file 0-default.jsx are UXPin Merge conventions)

About UXPin Merge

Merge is a revolutionary technology that lets users import (and keep in sync) coded React.js components from GIT repositories to UXPin editor. The imported components are 100% identical to components used by developers during the development process. It means that components are going to look and, function (interactions, data) identical to the real product experienced by the users.

UXPin is a leading code–based design platform.

How to use Merge integration with Salesforce Lightning?

Merge is currently only available for selected beta users.

  1. Fork this repository and clone it to your computer.
  2. Install dependencies with npm install
  3. Log in to your UXPin beta account (approved for alpha and beta tests by UXPin Inc.)
  4. Start Merge dev environment with npm run uxpin:experiment

If you wish to push Salesforce Lightning React components to your UXPin account or set-up a continues integration with a CI server - contact UXPin on Merge alpha Slack community.

Supported components

Component SF DS React Link Components Status in Merge
Accordion Accordion ✅ Full Support
Alerts Alerts ✅ Full Support
Avatars Avatars ✅ Full Support
BrandBand Brand Band ✅ Full Support
Breadcrumbs Breadcrumbs ✅ Full Support
ButtonGroup Breadcrumbs ✅ Full Support
Button Buttons ✅ Full Support
Card Cards ✅ Full Support
Checkbox Checkboxes ✅ Full Support
ColorPicker Color Pickers ✅ Full Support
Combobox Comboboxes ✅ Full Support. Additional interactivity added in CombovoxInteractive component.
DataTable DataTables Not supported yet
Datepicker Datepickers ✅ Full Support
DropdownMenu Dropdown Menus ✅ Full Support
Icon Icons ✅ Full Support
Illustration Illustrations ✅ Full Support
Input Inputs ✅ Full Support
MediaObject Media Objects ✅ Full Support
Modals Modals 🔻 Not Supported. Issues with absolutely positioned elements.
PageHeader Page Headers 🔻 Not Supported. Issues with absolutely positioned elements.
PillContainer Pill Container ✅ Full Support
Pill Pills ✅ Full Support
Popover Popovers ✅ Full Support
ProgressIndicator Progress Indicators ✅ Full Support. Additional interactivity added in CombovoxInteractive component.
ProgressRring Progress Rings ✅ Full Support
RadioButtonGroup Radio Button Groups ✅ Full Support
RadioGroup Radio Groups ✅ Full Support
Radio Radios ✅ Full Support
Slider Slider ✅ Full Support
Spinner Spinners ✅ Full Support
Spinner Spinners ✅ Full Support
SplitView Split Views Not supported yet
StatefulButton Stateful Buttons ✅ Full Support
Tabs Tabs ✅ Full Support
Textarea Textareas ✅ Full Support
Timepicker Timepickers ✅ Full Support
Toast Toasts ✅ Full Support
Tooltip Tooltips ✅ Full Support
Tree Trees ✅ Full Support
VerticalNavigation Vertical Navigation Not supported yet.
AppLauncher App Launcher ✅ Full Support
GlobalHeader Global Header 🔻 Not Supported. Issues with automatically rendered – not compatible with Merge

Examples

alt text alt text

CI Server Integration (available only for beta users)

The recommended approach to integrating React.js components with UXPin is via Continues Integration server (Circle CI, Travis...). This approach provides an opportunity to establish a real single source of truth for design and development.

After the integration with a CI server every commit to master can (if this is how your CI is configured) automatically update library in UXPin.

This repository consits of an example of integration with Circle CI. If you wish to reuse it follow these steps:

  1. Make sure that you forked this repository.
  2. Go to https://circleci.com and sign-up for an account with your Github credentials.
  3. Start a new project and track your fork of this repository.
  4. Go into your UXPin account, enter UXPin editor (in any project).
  5. While inside of UXPin editor open Design Systems Libraries panel and create a new library. Copy the library token (keep it secure it provides access to your library!)

alt text

If you're not seeing the screen above – contact your account manager. You're not in Merge Beta group yet.

  1. Go into settings of your project in Circle CI. Enter section Environment Variables and click on Add new variable.
  2. Name the new variable UXPIN_AUTH_TOKEN and pass your token copied from the UXPin library (#5) as its value.

That's it! The next change in the master branch of your fork will automatically trigger Circle CI and send the newest version of your components to UXPin.

Integration with CI server leads to a powerful workflow, with that however comes couple of dangers, so please be aware of them!

  • ⚠️ Don't share your UXPin authorization token with anyone. It leads straight to your design system library in UXPin. Keep the token safe in the CI app!
  • ⚠️ Don't keep your UXPin authorization token in any file checked into your git repository.
  • ⚠️ Treat contributing to Master branch just like deploying production code. Any change will be automatically reflected in the UXPin library and projects. If you want to experiment with components – start a new branch and use Merge dev environment – experiment mode (in this repository launched via npm start)

Design System for React

Accessible, localization-friendly, presentational React components

Build Status DeepScan Grade Known Vulnerabilities

Install

$ npm install @salesforce-ux/design-system @salesforce/design-system-react

Getting Started

Welcome to the project! 👋 This library is the React implementation of the Salesforce Lightning Design System. This library has a peer dependency on @salesforce-ux/design-system, react, and react-dom. It is tested with React 16 and has a stable API despite its version number. Please polyfill this library in order to meet your target environment needs.

Usage

Quick Setup (CommonJS)

For a no hassle setup and compatibility with Create React App v1, a CommonJS version has been included within the NPM package. If using this setup, please re-write the import statement in the documentation site examples. Use the following named import syntax to access CommonJS components from /lib/index.js:

import { Button } from '@salesforce/design-system-react';

<Button label="Hello Button" />

Please view Create React App Setup for more information on using this library with Create React App.

Advanced (Source code)

Advanced usage requires that your babel presets are set up correctly. create-react-app and environments that do not transpile code within node_modules are not compatible with the component import below. All the examples on the documentation site use this syntax. You can use the Babel preset, @salesforce/babel-preset-design-system-react, to get started. This preset will keep Babel compatible with Design System React and allow ES6 module benefits such as tree-shaking. This library is not browser-ready and should be polyfilled to your target environment.

import Button from '@salesforce/design-system-react/components/button';

<Button label="Hello Button" />

Transpile with .babelrc settings

{
	"presets": ["@salesforce/babel-preset-design-system-react"]
}

Styling

This library does not contain any Cascading Style Sheets (CSS). You will need to add <link rel="stylesheet" type="text/css" href="/node_modules/@salesforce-ux/design-system/assets/styles/salesforce-lightning-design-system.min.css" /> to your page and serve that file from a publicly available folder.

Serve icons publicly

Typically, scripts should be downloaded in the background without blocking the DOM. With React, this works best with server side rendering. SLDS recommends placeholder stencils while scripts are initializing if the HTML cannot be served immediately. If you can serve the HTML, then icon SVGs should not be bundled and served like any other file. Set a path context for all child components with <IconSettings> at the top of your render tree:

import IconSettings from '@salesforce/design-system-react/components/icon-settings';

ReactDOM.render(
  <IconSettings iconPath="/assets/icons">
    <MyApp />
  </IconSettings>,
  document.getElementById('app')
)

// `/assets/icons` will be prepended to `/standard-sprite/svg/symbols.svg#account` within the SVG path
<svg aria-hidden="true" class="slds-icon">
  <use xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="/assets/icons/standard-sprite/svg/symbols.svg#account"></use>
</svg>

// ExpressJS example
app.use('/assets/icons', express.static('node_modules/@salesforce-ux/design-system/assets/icons/'));

Bundle icons

If you use a module bundler, like Webpack, you can let your module bundler manage SVG sprite file paths and send that path into <IconSettings>. This requires configuring your module bundler to manage your public assets.

import IconSettings from '@salesforce/design-system-react/components/icon-settings';
import standardSprite from '@salesforce-ux/design-system/assets/icons/standard-sprite/svg/symbols.svg';
...
...

ReactDOM.render(
  <IconSettings standardSprite={standardSprite}>
    <MyApp />
  </IconSettings>,
  document.getElementById('app')
)

Icon Usage

Prior to v0.7.0, SLDS icons were bundled with the JavaScript. The 400KB+ icons bundle from SLDS is no longer included. You will need to download the SLDS CSS and icons separately.

Bundled script files are provided only for convenience. Do not use in production.

  • design-system-react.min.js (700KB+) - includes icons in the JavaScript
  • design-system-react-components.min.js (~400KB) - no icons.

Contributing to the code base

Clone and develop locally with Storybook and in-browser tests

git clone [email protected]:salesforce/design-system-react.git
npm install
npm start
open http://localhost:9001 http://localhost:8001

Please read the CONTRIBUTING.md and Test README first. Then, create an issue to tell others you are working on a bug. If you would like to contribute a new component, create an issue with a list of proposed props to discuss with maintainers. Issues not addressed with pull requests may be closed eventually. Check out who's contributing to the project.

Got feedback?

If you have support questions, please post a question to StackOverflow and tag with design-system-react. If you find any bugs, create a GitHub Issue.

Security

Please report any security issue to [email protected] as soon as it is discovered. This library limits its runtime dependencies in order to reduce the total cost of ownership as much as can be, but all consumers should remain vigilant and have their security stakeholders review all third-party dependencies.

Contributors

Thank you to all the contributors to this one of many open source projects at Salesforce, but special thanks to the following:

Active Key Contributors

Former Key Contributors

Licenses