carbon-components-svelte 0.113.1 → 0.114.0

package/README.md

@@ -8,7 +8,7 @@
 
 Carbon Components Svelte is a [Svelte](https://github.com/sveltejs/svelte) component library that implements the [Carbon Design System](https://www.carbondesignsystem.com/), an open source design system by IBM. Ship accessible, consistent, production-ready interfaces.
 
-- **90+ components**: from inputs to data tables
+- **100+ components**: from inputs to data tables
 - **5 built-in themes**: two light, three dark
 - **Fully typed TypeScript API**: props, events, and slots
 - **WCAG 2.1 AA**: keyboard and screen-reader ready
@@ -18,7 +18,7 @@ The Carbon Svelte ecosystem also includes:
 - **[Carbon Icons Svelte](https://github.com/carbon-design-system/carbon-icons-svelte)**: 2,700+ Carbon icons as Svelte components
 - **[Carbon Pictograms Svelte](https://github.com/carbon-design-system/carbon-pictograms-svelte)**: 1,500+ Carbon pictograms as Svelte components
 - **[Carbon Charts Svelte](https://github.com/carbon-design-system/carbon-charts/tree/master/packages/svelte)**: 25+ charts, powered by d3
-- **[Carbon Preprocess Svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte)**: Collection of Svelte preprocessors for Carbon
+- **[Carbon Preprocess Svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte)**: Svelte preprocessors and build plugins for Carbon
 
 ## [Documentation](https://svelte.carbondesignsystem.com)
 
@@ -51,7 +51,9 @@ Before importing components, you will need to first apply Carbon component style
 - **g100.css**: Gray 100 theme (dark)
 - **all.css**: All five themes (White, Gray 10, Gray 80, Gray 90, Gray 100) using [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
 
-Each StyleSheet is [generated](scripts/build-css.ts) from the flagship [carbon-components](https://github.com/carbon-design-system/carbon/tree/main/packages/carbon-components) library.
+Every StyleSheet declares its theme's tokens as custom properties on `:root`, so your own CSS can use `var(--cds-text-primary)`, `var(--cds-spacing-05)` and the rest with any of them.
+
+Each StyleSheet is [compiled](scripts/build-css.ts) from Carbon's component SCSS ([carbon-components@10.58](css/vendor/carbon-components), vendored) themed with Carbon v11 tokens, and this library's own partials in [css](css).
 
 The compiled CSS is generated from the following `.scss` files:
 
@@ -86,11 +88,11 @@ import "carbon-components-svelte/css/g100.css";
 import "carbon-components-svelte/css/all.css";
 ```
 
-### SCSS
+### Smaller CSS
 
-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.
+Each precompiled StyleSheet contains the styles for every component. To ship only the styles your app uses, add [`optimizeCss`](#optimizecss) to your production build. Set `propAware: true` to also drop the styles of prop values your app never passes; see [prop-aware pruning](#prop-aware-pruning).
 
-Refer to the [official Carbon guide on SASS](https://github.com/carbon-design-system/carbon/blob/v10/docs/guides/sass.md) for documentation.
+The SCSS sources are not published. Compiling `carbon-components` v10 SCSS yourself gives v10 colors and type, and misses styles for components and variants that only this library provides.
 
 ### Dynamic theming
 
@@ -144,7 +146,7 @@ Import components from `carbon-components-svelte` in the `script` tag of your Sv
 
 ## Preprocessors & Plugins
 
-[carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte) is a collection of Svelte preprocessors for Carbon. It trims build times and bundle size with two drop-in tools for faster HMR in development and leaner CSS when you ship.
+[carbon-preprocess-svelte](https://github.com/carbon-design-system/carbon-preprocess-svelte) is a collection of Svelte preprocessors and build plugins for Carbon. It trims build times and bundle size with three drop-in tools: faster compiles in development, leaner CSS and leaner JavaScript when you ship. Each works on its own.
 
 > [!NOTE]
 > Using `carbon-preprocess-svelte` is optional and not a prerequisite for this library. It should be installed as a development dependency.
@@ -163,6 +165,12 @@ yarn add -D carbon-preprocess-svelte
 bun add -D carbon-preprocess-svelte
 ```
 
+| Tool | Type | What it does |
+| :--- | :--- | :--- |
+| [`optimizeImports`](#optimizeimports) | Svelte preprocessor | Rewrites barrel imports to source paths, for faster dev and build times |
+| [`optimizeCss`](#optimizecss) | Build plugin | Removes unused Carbon styles from production CSS |
+| [`optimizeComponents`](#optimizecomponents) | Build plugin | Rewrites Carbon components for the props your app passes, removing code it never runs |
+
 ### `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.
@@ -188,24 +196,79 @@ The preprocessor optimizes imports from the following packages:
 
 ### `optimizeCss`
 
-`optimizeCss` is a Vite plugin that removes unused Carbon styles at build time, often removing hundreds of kilobytes from production bundles. The plugin is compatible with Rollup ([Vite](https://vitejs.dev/guide/api-plugin) extends the Rollup plugin API).
+`optimizeCss` is a build plugin that removes unused Carbon styles at build time, often removing hundreds of kilobytes from production bundles. It runs on Vite, Rollup, and Rolldown. For Webpack and Rspack, use `OptimizeCssPlugin`.
 
 `carbon-components-svelte@0.85.0` or greater is required.
 
 ```diff
 $ vite build
 
-Optimized index-CU4gbKFa.css
-- Before: 606.26 kB
-+ After:   53.22 kB (-91.22%)
+Optimized assets/index-Doxsm5Yz.css
+- Before: 557.37 kB
++ After:   46.16 kB (-91.72%)
 
-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
+dist/index.html                  0.33 kB │ gzip:  0.23 kB
+dist/assets/index-Doxsm5Yz.css  46.16 kB │ gzip:  6.12 kB
+dist/assets/index-BoBcXTHi.js   69.61 kB │ gzip: 24.35 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.
+> This is a plugin and not a Svelte preprocessor. Add it to your bundler's `plugins`. Vite runs it on `vite build` only, and `OptimizeCssPlugin` runs in Webpack's production mode only. Under Rollup and Rolldown, add it to production builds only.
+
+#### Prop-aware pruning
+
+Set `propAware: true` to also remove styles for the prop values your app never passes.
+
+```js
+optimizeCss({ propAware: true });
+```
+
+```svelte
+<Button kind="tertiary">Save</Button>
+<!-- kept:   .bx--btn, .bx--btn--tertiary
+     pruned: the other kinds and sizes, .bx--skeleton, the icon-only tooltip -->
+```
+
+It reads literal props, constants and state nothing reassigns (including constants your own modules export), your own wrapper components, props forwarded with `{...$$restProps}` or `...rest`, object and array literals, and your own `{#if}` and `{#each}`. A value it can't read keeps every variant: a reassigned variable, a writable store, `bind:`, a spread of anything but a literal or forwarded props, or data fetched at runtime.
+
+Refer to the [carbon-preprocess-svelte documentation](https://github.com/carbon-design-system/carbon-preprocess-svelte#prop-aware-pruning) for details.
+
+### `optimizeComponents`
+
+`optimizeComponents` rewrites each Carbon component your app renders for the props it passes. Values that never change become literals, and branches that can't run are removed, along with child components only those branches render (a skeleton, a tooltip portal). It is the JavaScript counterpart of prop-aware CSS pruning and uses the same analysis. In typical apps it removes 18–27% of the production JavaScript.
+
+Your own wrapper components are rewritten the same way when every place that renders them is in `content`.
+
+```js
+// vite.config.js
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import {
+  optimizeComponents,
+  optimizeCss,
+  optimizeImports,
+} from "carbon-preprocess-svelte";
+
+export default {
+  plugins: [
+    optimizeComponents(),
+    svelte({ preprocess: [optimizeImports()] }),
+    optimizeCss({ propAware: true }),
+  ],
+};
+```
+
+| Bundler | Set-up | Runs on |
+| :--- | :--- | :--- |
+| Vite, SvelteKit, Astro | add `optimizeComponents()` to `vite.plugins`; it orders itself first | `vite build` only, never `vite dev` |
+| Rollup, Rolldown | list `optimizeComponents()` before the Svelte plugin | production builds only (add it conditionally) |
+| Webpack, Rspack | add `new OptimizeComponentsPlugin()` to `plugins` | `mode: "production"` only |
+
+- It analyzes the files matched by `content` (default: source files under `src/`) before the build. If a module outside `content` renders a Carbon component, or one of your rewritten wrappers, including through a re-export or a dynamic `import()`, the build fails instead of shipping wrong code.
+- Wrappers imported through an alias (`$lib/Card.svelte`, `#lib/Card.svelte`) are resolved with the bundler's own resolver.
+- SvelteKit and Astro server and client builds are rewritten alike, so prerendered pages hydrate as before.
+- Set `report: true` to print what each build rewrote.
+
+Refer to the [carbon-preprocess-svelte documentation](https://github.com/carbon-design-system/carbon-preprocess-svelte#optimizecomponents) for every option.
 
 ### Configure your bundler
 
@@ -236,23 +299,20 @@ import adapter from "@sveltejs/adapter-static";
 import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
 import { optimizeImports } from "carbon-preprocess-svelte";
 
-const config = {
+export default {
   preprocess: [vitePreprocess(), optimizeImports()],
   kit: { adapter: adapter() },
 };
-
-export default config;
 ```
 
 ```js
 // vite.config.js
 import { sveltekit } from "@sveltejs/kit/vite";
 import { optimizeCss } from "carbon-preprocess-svelte";
-import { defineConfig } from "vite";
 
-export default defineConfig({
+export default {
   plugins: [sveltekit(), optimizeCss()],
-});
+};
 ```
 
 **Rollup**
@@ -276,6 +336,8 @@ export default {
 
 **Webpack**
 
+Rspack implements Webpack's plugin and loader APIs, so the same configuration works in `rspack.config.mjs`.
+
 ```js
 // webpack.config.mjs
 import { OptimizeCssPlugin, optimizeImports } from "carbon-preprocess-svelte";
@@ -370,7 +432,7 @@ Documentation is available in LLM-friendly plain text for use with coding assist
 
 ## TypeScript support
 
-[TypeScript definitions](types) are generated by [sveld](https://github.com/carbon-design-system/sveld).
+Every component ships TypeScript definitions for its props, events, and slots (`src/**/*.svelte.d.ts`), generated from the component source by [sveld](https://github.com/carbon-design-system/sveld).
 
 ## Contributing