Skip to content

Commit 0315a17

Browse files
metonymmetonym
authored
Update examples, update README documentation (#772)
* chore(examples): update example set-ups * chore: update readme docs
1 parent d24c608 commit 0315a17

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

97 files changed

+6882
-15925
lines changed

‎README.md‎

Lines changed: 110 additions & 124 deletions
Original file line numberDiff line numberDiff line change
@@ -46,53 +46,9 @@ npm i -D carbon-components-svelte
4646

4747
## Usage
4848

49-
The quickest way to get started is to customize a template from the [examples](examples/) folder.
49+
### Styling
5050

51-
Example set-ups demonstrate usage with popular application bundlers and frameworks. They include a mix of client-side rendering (CSR) and server-side rendering (SSR) approaches.
52-
53-
- **[examples/rollup](examples/rollup/)**: SPA bundled using [Rollup](https://github.com/rollup/rollup)
54-
- **[examples/rollup-typescript](examples/rollup-typescript/)**: SPA bundled using [Rollup](https://github.com/rollup/rollup) with TypeScript support
55-
- **[examples/routify](examples/routify/)**: SPA + static export using [Routify](https://github.com/roxiness/routify)
56-
- **[examples/sapper](examples/sapper/)**: SSR + static export using [Sapper](https://github.com/sveltejs/sapper)
57-
- **[examples/svite](examples/svite/)**: SPA developed with Svite, bundled with [Rollup](https://github.com/rollup/rollup)
58-
- **[examples/webpack](examples/webpack/)**: SPA bundled with [webpack](https://github.com/webpack/webpack)
59-
60-
### Scaffolding
61-
62-
Each example is published in a dedicated branch of the same name.
63-
64-
Use [degit](https://github.com/Rich-Harris/degit) to scaffold a new project:
65-
66-
For example, to use the `svite` template, run the following commands:
67-
68-
```sh
69-
npx degit ibm/carbon-components-svelte#svite svelte-app
70-
cd svelte-app
71-
yarn install
72-
```
73-
74-
### Importing components
75-
76-
Import components from `carbon-components-svelte` in the `script` tag of your Svelte file.
77-
78-
```html
79-
<!-- App.svelte -->
80-
<script>
81-
import { Accordion, AccordionItem } from "carbon-components-svelte";
82-
</script>
83-
84-
<Accordion>
85-
<AccordionItem title="Section 1" open> Content 1 </AccordionItem>
86-
<AccordionItem title="Section 2"> Content 2 </AccordionItem>
87-
<AccordionItem title="Section 3"> Content 3 </AccordionItem>
88-
</Accordion>
89-
```
90-
91-
**Refer to [COMPONENT_INDEX.md](COMPONENT_INDEX.md) for component API documentation.**
92-
93-
### Pre-compiled CSS StyleSheets
94-
95-
`carbon-components-svelte` includes pre-compiled CSS StyleSheets for each Carbon theme:
51+
Before importing components, you will need to first apply Carbon component styles. The Carbon Design System supports five themes (2 light, 3 dark).
9652

9753
- **white.css**: Default Carbon theme (light)
9854
- **g10.css**: Gray 10 theme (light)
@@ -112,44 +68,72 @@ The compiled CSS is generated from the following `.scss` files:
11268
- [css/g100.scss](css/g100.scss)
11369
- [css/all.scss](css/all.scss)
11470

115-
#### Usage
71+
#### CSS StyleSheet
11672

117-
##### `svelte-preprocess`
73+
```js
74+
// White theme
75+
import "carbon-components-svelte/css/white.css";
11876

119-
The easiest way to import a StyleSheet is with [svelte-preprocess](https://github.com/sveltejs/svelte-preprocess).
77+
// Gray 10 theme
78+
import "carbon-components-svelte/css/g10.css";
12079

121-
```js
122-
const svelteOptions = {
123-
preprocess: require("svelte-preprocess")(),
124-
};
80+
// Gray 80 theme
81+
import "carbon-components-svelte/css/g80.css";
82+
83+
// Gray 90 theme
84+
import "carbon-components-svelte/css/g90.css";
85+
86+
// Gray 100 theme
87+
import "carbon-components-svelte/css/g100.css";
88+
89+
// All themes
90+
import "carbon-components-svelte/css/all.css";
12591
```
12692

93+
#### CDN
94+
95+
An alternative to loading styles is to link an external StyleSheet from a Content Delivery Network (CDN) like [unpkg.com](https://unpkg.com/).
96+
97+
This is best suited for rapid prototyping.
98+
99+
##### HTML
100+
127101
```html
128-
<!-- App.svelte -->
129-
<style lang="scss" global>
130-
/** Gray 10 theme **/
131-
@import "carbon-components-svelte/css/g10";
132-
</style>
102+
<!DOCTYPE html>
103+
<html>
104+
<head>
105+
<link
106+
rel="stylesheet"
107+
href="https://unpkg.com/carbon-components-svelte/css/white.css"
108+
/>
109+
</head>
110+
</html>
133111
```
134112

135-
##### JavaScript import
113+
##### `svelte:head`
136114

137-
Importing a CSS file in a JavaScript file will require the appropriate file loader(s).
115+
```html
116+
<svelte:head>
117+
<link
118+
rel="stylesheet"
119+
href="https://unpkg.com/carbon-components-svelte/css/white.css"
120+
/>
121+
</svelte:head>
122+
```
138123

139-
```js
140-
import "carbon-components-svelte/css/all.css";
141-
import App from "./App.svelte";
124+
### SCSS
142125

143-
const app = new App({ target: document.body });
126+
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.
144127

145-
export default app;
146-
```
128+
Refer to the [official Carbon guide on SASS](https://github.com/carbon-design-system/carbon/blob/main/docs/guides/sass.md) for documentation.
147129

148-
See [webpack.config.js](examples/webpack/webpack.config.js) in [examples/webpack](examples/webpack).
130+
### Dynamic theming
149131

150-
#### Dynamic theming
132+
Use the "all.css" StyleSheet for dynamic, client-side theming.
151133

152-
Use `carbon-components-svelte/css/all.css` for dynamic, client-side styling.
134+
```js
135+
import "carbon-components-svelte/css/all.css";
136+
```
153137

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

@@ -162,89 +146,91 @@ Update the theme by setting the `theme` attribute on the `html` element. The def
162146
</html>
163147
```
164148

165-
Using JavaScript:
149+
Programmatically switch between each of the five Carbon themes by setting the "theme" attribute on the HTML element.
166150

167-
```svelte
151+
```html
168152
<script>
169-
/** @type {"white" | "g10" | "g80" | "g90" | "g100"} */
170-
let theme = "white";
153+
let theme = "white"; // "white" | "g10" | "g80" | "g90" | "g100"
171154
172155
$: document.documentElement.setAttribute("theme", theme);
173156
</script>
157+
```
174158

175-
<button on:click="{() => (theme = 'g90')}">Update theme</button>
159+
### Importing components
160+
161+
Import components from `carbon-components-svelte` in the `script` tag of your Svelte file. Visit the [documentation site](http://ibm.biz/carbon-svelte) for examples.
162+
163+
```html
164+
<!-- App.svelte -->
165+
<script>
166+
import { Accordion, AccordionItem } from "carbon-components-svelte";
167+
</script>
168+
169+
<Accordion>
170+
<AccordionItem title="Section 1" open> Content 1 </AccordionItem>
171+
<AccordionItem title="Section 2"> Content 2 </AccordionItem>
172+
<AccordionItem title="Section 3"> Content 3 </AccordionItem>
173+
</Accordion>
176174
```
177175

176+
**Refer to [COMPONENT_INDEX.md](COMPONENT_INDEX.md) for component API documentation.**
177+
178178
## Preprocessors
179179

180-
### optimizeCarbonImports
180+
[carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte) is a collection of Svelte preprocessors for Carbon.
181181

182-
`optimizeCarbonImports` is a Svelte preprocessor that optimizes base imports inside the `script` block of a Svelte file from the following libraries:
182+
**Yarn**
183183

184-
- carbon-components-svelte
185-
- carbon-icons-svelte
186-
- carbon-pictograms-svelte
184+
```sh
185+
yarn add -D carbon-preprocess-svelte
186+
```
187187

188-
The preprocessor rewrites base imports to directly import the source Svelte file. This may lead to faster complile times **during development**.
188+
**NPM**
189189

190-
Example:
190+
```sh
191+
npm i -D carbon-preprocess-svelte
192+
```
191193

192-
**Before**
194+
### `optimizeImports`
193195

194-
```js
195-
import { Button, Header } from "carbon-components-svelte";
196-
import { Notification20 } from "carbon-icons-svelte";
197-
import { Airplane } from "carbon-pictograms-svelte";
198-
```
196+
`optimizeImports` is a script preprocessor that rewrites base imports from Carbon components/icons/pictograms packages to their source Svelte code paths. This can greatly speed up compile times during development while preserving typeahead and autocompletion hinting offered by integrated development environments (IDE) like VSCode.
199197

200-
**After**
198+
The preprocessor optimizes imports from the following packages:
201199

202-
```js
203-
import Button from "carbon-components-svelte/Button/Button.svelte";
204-
import Header from "carbon-components-svelte/UIShell/GlobalHeader/Header.svelte";
205-
import Notification20 from "carbon-icons-svelte/lib/Notification20/Notification20.svelte";
206-
import Airplane from "carbon-pictograms-svelte/lib/Airplane/Airplane.svelte";
200+
- [carbon-components-svelte](https://github.com/IBM/carbon-components-svelte)
201+
- [carbon-icons-svelte](https://github.com/IBM/carbon-icons-svelte)
202+
- [carbon-pictograms-svelte](https://github.com/IBM/carbon-pictograms-svelte)
203+
204+
**Example**
205+
206+
```diff
207+
- import { Button } from "carbon-components-svelte";
208+
- import { Add16 } from "carbon-icons-svelte";
209+
- import { Airplane } from "carbon-pictograms-svelte";
210+
+ import Button from "carbon-components-svelte/Button/Button.svelte";
211+
+ import Add16 from "carbon-icons-svelte/lib/Add16/Add16.svelte";
212+
+ import Airplane from "carbon-pictograms-svelte/lib/Airplane/Airplane.svelte";
207213
```
208214

209-
#### svelte.config.js
215+
#### Usage
210216

211217
```js
212218
// svelte.config.js
213-
const {
214-
optimizeCarbonImports,
215-
} = require("carbon-components-svelte/preprocess");
219+
import { optimizeImports } from "carbon-preprocess-svelte";
216220

217-
module.exports = {
218-
preprocess: [optimizeCarbonImports()],
221+
export default {
222+
preprocess: [optimizeImports()],
219223
};
220224
```
221225

222-
#### svelte-loader
226+
## Examples
223227

224-
```js
225-
// webpack.config.js
226-
const {
227-
optimizeCarbonImports,
228-
} = require("carbon-components-svelte/preprocess");
229-
230-
module.exports = {
231-
// ...
232-
module: {
233-
rules: [
234-
{
235-
test: /\.svelte$/,
236-
use: {
237-
loader: "svelte-loader",
238-
options: {
239-
hotReload: true,
240-
preprocess: [optimizeCarbonImports()],
241-
},
242-
},
243-
},
244-
],
245-
},
246-
};
247-
```
228+
- [examples/rollup](examples/rollup/)
229+
- [examples/sapper](examples/sapper/)
230+
- [examples/snowpack](examples/snowpack/)
231+
- [examples/sveltekit](examples/sveltekit/)
232+
- [examples/vite](examples/vite/)
233+
- [examples/webpack](examples/webpack/)
248234

249235
## TypeScript support
250236

‎examples/rollup-typescript/.gitignore‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎examples/rollup-typescript/README.md‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎examples/rollup-typescript/package.json‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

‎examples/rollup-typescript/public/favicon.ico‎

-5.3 KB
Binary file not shown.

‎examples/rollup-typescript/public/index.html‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

0 commit comments

Comments
 (0)