Giter Club home page Giter Club logo

carbon-components-svelte's Introduction

carbon-components-svelte

NPM GitHub npm downloads to date Chat with us on Discord

Carbon Components Svelte is a Svelte component library that implements the Carbon Design System, an open source design system by IBM.

Design systems facilitate design and development through reuse, consistency, and extensibility.

The Carbon Svelte portfolio also includes:

Other forms of documentation are auto-generated:

Installation

Install carbon-components-svelte as a development dependency.

# Yarn
yarn add -D carbon-components-svelte

# npm
npm i -D carbon-components-svelte

# pnpm
pnpm i -D carbon-components-svelte

Usage

Styling

Before importing components, you will need to first apply Carbon component styles. The Carbon Design System supports five themes (2 light, 3 dark).

  • white.css: Default Carbon theme (light)
  • g10.css: Gray 10 theme (light)
  • g80.css: Gray 80 theme (dark)
  • g90.css: Gray 90 theme (dark)
  • g100.css: Gray 100 theme (dark)
  • all.css: All themes (White, Gray 10, Gray 90, Gray 100) using CSS variables

Each StyleSheet is generated from the flagship carbon-components library.

The compiled CSS is generated from the following .scss files:

CSS StyleSheet

// White theme
import "carbon-components-svelte/css/white.css";

// Gray 10 theme
import "carbon-components-svelte/css/g10.css";

// Gray 80 theme
import "carbon-components-svelte/css/g80.css";

// Gray 90 theme
import "carbon-components-svelte/css/g90.css";

// Gray 100 theme
import "carbon-components-svelte/css/g100.css";

// All themes
import "carbon-components-svelte/css/all.css";

CDN

An alternative to loading styles is to link an external StyleSheet from a Content Delivery Network (CDN) like unpkg.com.

This is best suited for rapid prototyping.

HTML
<!DOCTYPE html>
<html>
  <head>
    <link
      rel="stylesheet"
      href="https://unpkg.com/carbon-components-svelte/css/white.css"
    />
  </head>
</html>
svelte:head
<svelte:head>
  <link
    rel="stylesheet"
    href="https://unpkg.com/carbon-components-svelte/css/white.css"
  />
</svelte:head>

SCSS

The most performant method to load styles is to import SCSS directly from carbon-components. Although it requires more set up, you can reduce the size of the bundle CSS by importing individual component styles instead of a pre-compiled CSS StyleSheet.

Refer to the official Carbon guide on SASS for documentation.

Dynamic theming

Use the "all.css" StyleSheet for dynamic, client-side theming.

import "carbon-components-svelte/css/all.css";

Update the theme by setting the theme attribute on the html element. The default theme is "white".

<!DOCTYPE html>
<html lang="en" theme="g10">
  <body>
    ...
  </body>
</html>

Programmatically switch between each of the five Carbon themes by setting the "theme" attribute on the HTML element.

<script>
  let theme = "white"; // "white" | "g10" | "g80" | "g90" | "g100"

  $: document.documentElement.setAttribute("theme", theme);
</script>

Importing components

Import components from carbon-components-svelte in the script tag of your Svelte file. Visit the documentation site for examples.

<!-- App.svelte -->
<script>
  import { Accordion, AccordionItem } from "carbon-components-svelte";
</script>

<Accordion>
  <AccordionItem title="Section 1" open> Content 1 </AccordionItem>
  <AccordionItem title="Section 2"> Content 2 </AccordionItem>
  <AccordionItem title="Section 3"> Content 3 </AccordionItem>
</Accordion>

Refer to COMPONENT_INDEX.md for component API documentation.

Preprocessors & Plugins

carbon-preprocess-svelte is a collection of Svelte preprocessors for Carbon.

Note

Using carbon-preprocess-svelte is optional and not a prerequisite for this library.

# Yarn
yarn add -D carbon-preprocess-svelte

# npm
npm i -D carbon-preprocess-svelte

# pnpm
pnpm i -D carbon-preprocess-svelte

optimizeImports

optimizeImports is a Svelte preprocessor that rewrites barrel imports from Carbon components/icons/pictograms packages to their source Svelte code paths. This can significantly speed up development and production build compile times while preserving typeahead and autocompletion offered by integrated development environments (IDE) like VS Code.

The preprocessor optimizes imports from the following packages:

Before & After

- import { Button } from "carbon-components-svelte";
+ import Button from "carbon-components-svelte/src/Button/Button.svelte";

- import { Add } from "carbon-icons-svelte";
+ import Add from "carbon-icons-svelte/lib/Add.svelte";

- import { Airplane } from "carbon-pictograms-svelte";
+ import Airplane from "carbon-pictograms-svelte/lib/Airplane.svelte";

Usage

See examples for full configurations.

// svelte.config.js
import { optimizeImports } from "carbon-preprocess-svelte";

export default {
  preprocess: [optimizeImports()],
};

Any other preprocessors that transpile code in the script block should be invoked before optimizeImports.

For example, vitePreprocess should precede optimizeImports.

// svelte.config.js
+ import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
import { optimizeImports } from "carbon-preprocess-svelte";

export default {
  preprocess: [
+   vitePreprocess(),
    optimizeImports()
  ],
};

optimizeCss

optimizeCss is a Vite plugin that removes unused Carbon styles at build time. The plugin is compatible with Rollup (Vite extends the Rollup plugin API).

[email protected] or greater is required.

$ vite build

Optimized index-CU4gbKFa.css
- Before: 606.26 kB
+ After:   53.22 kB (-91.22%)

dist/index.html                  0.34 kB │ gzip:  0.24 kB
dist/assets/index-CU4gbKFa.css  53.22 kB │ gzip:  6.91 kB
dist/assets/index-Ceijs3eO.js   53.65 kB │ gzip: 15.88 kB

Note

This is a plugin and not a Svelte preprocessor. It should be added to the list of vite.plugins. For Vite set-ups, this plugin is only run when building the app. For Rollup and Webpack, you should conditionally apply the plugin to only execute when building for production.

Usage

See examples for full configurations.

// vite.config.js
import { sveltekit } from "@sveltejs/kit/vite";
import { optimizeCss } from "carbon-preprocess-svelte";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [sveltekit(), optimizeCss()],
});

Examples

TypeScript support

TypeScript definitions are generated by sveld.

Contributing

Refer to the Contributing guidelines.

License

Apache 2.0

IBM Telemetry IBM Telemetry

This package uses IBM Telemetry to collect anonymous metrics data in CI environments. By installing this package as a dependency you are agreeing to telemetry collection. To opt out, see Opting out of IBM Telemetry data collection. For more information on the data being collected, please see the IBM Telemetry documentation.

carbon-components-svelte's People

Contributors

adanug avatar albertms10 avatar andreancardona avatar asakuramizu avatar brunnerh avatar danielboven avatar dependabot-preview[bot] avatar dependabot[bot] avatar gregorw avatar heydan83 avatar hslee2008 avatar ibilux avatar imgbotapp avatar josefaidt avatar jqlio18 avatar koichikiyokawa avatar mabentley85 avatar malinowskip avatar mattrosno avatar metonym avatar mfeitoza avatar miedzikd avatar naegelin avatar overbryd avatar patoi avatar pbxothi avatar rafadess avatar theetrain avatar tmarsik42 avatar weaseldotro avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

carbon-components-svelte's Issues

Attributes need to be unique

I'm running into an error when using anything that touches SkeletonText component:
$ (plugin svelte) ParseError: Attributes need to be unique

/src/components/SkeletonText/SkeletonText.svelte

...
  <p
    on:click
    on:mouseover
    on:mouseenter
    on:mouseleave
    class={cx('--skeleton__text', heading && '--skeleton__heading', className)}
    style={`width: ${width};`}
    {style} />

There are basically two "style" props.

release: v0.2.0

v0.2.0 release

  • Include 'src' folder when publishing to npm (#102 )
  • Include usage documentation
  • Include example set-ups (#6 ) Provide REPL
  • Revise README to list components/features not yet supported (roadmap for v1.0, post-v1.0) Link to ongoing v1.0.0 project

docs: replace Storybook with plain webpack app

Although Storybook has been useful in guiding the initial development of the library, it would be more realistic if the library is consumed directly in a plain webpack application.

Particularly for Svelte, Storybook does not illustrate usage of components in a deliberate way. The consumption of components is currently hidden in .Story.svelte files.


Pain points of Storybook/Svelte

  • Clicking a knob reloads the entire Story (does not preserve two-way binding)
  • Expensive set-up (multiple addons... etc) and large build size
  • Not as "real world" as a barebones webpack set-up
  • Addon source plugin does not reveal the source code of invoking Svelte components

Benefits of using a plain webpack set-up

  • More configuration control
  • More "real world" because it IS an application
  • Better optimized final build output
  • Illustrate two-way binding (one of the features of Svelte)
  • Provide real code snippet of usage per component

Features

  • Quick/Slow Start guides on initial set-up
  • Documentation on why carbon-components, carbon-icons-svelte are peer deps
  • Component documentation
    -- API (props)
    -- metadata (approximate non-gzip size, registry)
    -- recipes

Plan

  • Develop an alternative documentation app in a subfolder and a locally linked library
  • Replace Storybook with the alternative documentation when complete
  • Remove Storybook and its dependencies

feat(component): DataTable

Supported

  • DataTable (read-only, sortable)
  • DataTableSkeleton
  • Expandable DataTable + batch expansion
  • Selectable DataTable + batch selection
  • Radio DataTable
  • Table toolbar (#349 )
  • Toolbar action menu
  • Empty columns

No plans to support

  • Filterable ToolbarSearch: opt-in filtering behavior where the value from Search filters the current rows supplied to the DataTable
    • IMO, any row filtering logic should be deferred to the consumer.

CSS and Performance Improvement

At the moment, recommended way of importing styles of this library is by literally linking to the compiled and minified stylesheet file (~400kb). This file, as far as I understand, includes styles of all of the components.

While this is totally fine/usual way to deal with the css in react, it also kinda defeats the purpose of using svelte. It should not be necessary to include 400kb of CSS for a simple component which would take five carbon components and 15kb of JS.

Is there a consideration to allow building a css bundle of the used components (and dependancies) only?

feat: remove exported "props" for all components

Before a stable release, the exported "props" value should be removed.

<script>
  export let props = {};
</script>

<div {...props}></div>

The initial purpose was to pass "remaining" props not explicitly defined to a specific element via Object spread (e.g. '...').

The goal was to avoid accessing $$props.

Proposed Solution

For each component, remove props and explicitly define and export individual variables.

For example:

<script>
-  export let props = {};
+ export let title = undefined;
</script>

- <div {...props}></div>
+ <div title={title}></div>

Drawbacks

on:click on:mouseover on:mouseenter on:mouseleave {style}

Codify forwarded events for semantic HTML elements

Related #169

Description

For the 1.0 release, forwarded events should be codified and made consistent.

For example, a component in which the underlying element is a button or link should forward the following:

  • on:click
  • on:mouseover
  • on:mouseenter
  • on:mouseout
  • on:focus
  • on:blur
  • on:keydown

Whereas, an input or select element may only forward certain events:

  • on:input
  • on:change
  • on:focus
  • on:blur
  • on:keydown

error importing in svelte project

just trying out library for first time in a svelte project

 ENOENT: no such file or directory, open 'node_modules/carbon-components-svelte/src/index.js'

I believe the package.json svelte property references src/index.js which is not published to npm

Clean way to use Grid with Sapper?

Is there a clean way to use the Grid with Sapper? It appears that I need to use Sass, but is there a way to avoid using Sass and just use Sapper for this?

DatePicker broken?

I just tested carbon with few components.
I got it running (Buttons, Dropdown)

But DatePicker was added by svelte as empty <div> - i do not see ui

I used simple <DatePicker /> as code with import for this.

bug?

Composed DataTable

At moment only DataTable is exported, but there an example of composed DataTable in story file? Is finished?

Button with Icon does not obey Icon Spacing

In 0.5.1 when a Button is used with text and an Icon, the Icon appears right next to the text, rather than the Icon being offset.

<Button kind="primary" type="submit" icon={ArrowRight16}>
        Let's Play!
      </Button>

Theme support

How do we apply themes as described here?

Using:

<style type="text/sass" global>
@import "node_modules/carbon-components/scss/globals/scss/vendor/@carbon/themes/scss/themes";

$carbon--theme: $carbon--theme--g100;
@include carbon--theme();

@import 'node_modules/carbon-components/scss/globals/scss/styles';
</style>

Seems to have no effect at all.

Appropriate way to ensure Grid shows up below Header

When using a Header, followed by a Grid as in the following, the content of the Grid may hid underneath the Header, what's the appropriate way to deal with this?

<Header company="something" platformName="Something else"></Header>
<div class="bx--grid">
....
</div>

add utility selector for containing element for each component?

Background

When using automated testing tools, a common practice is to define a data- selector to an element and query it like so: document.querySelector('[data-]').

Since $$props won't be spread to the parent element of a component (and there's no guarantee of that regardless), the parent element should contain some selector that is easy to query.

Additionally, the carbon-specific class name (e.g. "bx--") for the parent element is not reliable as it may change with future releases.

Possible Solutions

  • Add id prop to each component and leave it up to the consumer to pass an id
  • Add data attribute unique to the component (but not necessarily a unique selector)

I believe a component-specific data attribute is ideal.

Data attribute

<div data-component-accordion>...</div>

OR with a shorthand/namespace

<div data-c-accordion>...</div>

Query the node like so: document.querySelectorAll('[data-c-accordion]')

Perhaps an arbitrary value can be passed to the data attribute. This can help distinguish between multiple component instances.

<script>
  export let id = "";
  export let data = undefined;
</script>

<div data-c-accordion={data || id}>...</div>

UIShellSideNav bug

Hi!

when Shell Side Nav have two itens with same name both show as active:

Opera Snapshot_2020-02-12_205503_localhost

And any plans to make a UIShell compoments based too?

Add dropdown component

  • single select dropdown
  • multi-select dropdown

Considerations:

  • dropdown list as a separate component (carbon-angular style)? Or dropdown types as separate components (carbon-react style)?
  • dropdown items as array vs component?
  • base bx--listbox components?
  • take advantage of svelte binding and events ... value binding for selected items?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.