carbon-components-svelte 0.109.0 → 0.110.0

package/README.md

@@ -6,13 +6,16 @@
 <img src="https://img.shields.io/discord/689212587170201628?color=5865F2&style=for-the-badge" alt="Chat with us on Discord">
 </a>
 
-Carbon Components Svelte is a [Svelte](https://github.com/sveltejs/svelte) component library that implements the [Carbon Design System](https://github.com/carbon-design-system), an open source design system by IBM.
+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.
 
-Design systems facilitate design and development through reuse, consistency, and extensibility.
+- **70+ 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
 
 The Carbon Svelte ecosystem also includes:
 
-- **[Carbon Icons Svelte](https://github.com/carbon-design-system/carbon-icons-svelte)**: 2,600+ Carbon icons as Svelte components
+- **[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
@@ -26,7 +29,7 @@ The Carbon Svelte ecosystem also includes:
 npm i carbon-components-svelte
 
 # pnpm
-pnpm i carbon-components-svelte
+pnpm add carbon-components-svelte
 
 # Yarn
 yarn add carbon-components-svelte
@@ -46,9 +49,9 @@ Before importing components, you will need to first apply Carbon component style
 - **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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties)
+- **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.js) from the flagship [carbon-components](https://github.com/carbon-design-system/carbon/tree/main/packages/carbon-components) library.
+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.
 
 The compiled CSS is generated from the following `.scss` files:
 
@@ -59,6 +62,8 @@ The compiled CSS is generated from the following `.scss` files:
 - [css/g100.scss](css/g100.scss)
 - [css/all.scss](css/all.scss)
 
+Import one theme once at the top-level entry point of your app, like `index.js` or `src/+layout.svelte`.
+
 #### CSS StyleSheet
 
 ```js
@@ -89,7 +94,7 @@ Refer to the [official Carbon guide on SASS](https://github.com/carbon-design-sy
 
 ### Dynamic theming
 
-Use the "all.css" StyleSheet for dynamic, client-side theming.
+To switch themes at runtime, import the combined "all.css" StyleSheet instead of a single theme. It bundles all five themes and toggles between them through a `theme` attribute on the HTML element.
 
 ```js
 import "carbon-components-svelte/css/all.css";
@@ -106,7 +111,7 @@ Update the theme by setting the `theme` attribute on the `html` element. The def
 </html>
 ```
 
-Programmatically switch between each of the five Carbon themes by setting the "theme" attribute on the HTML element.
+Or programmatically switch between each of the five Carbon themes by setting the `theme` attribute on the HTML element.
 
 ```html
 <script>
@@ -116,6 +121,8 @@ Programmatically switch between each of the five Carbon themes by setting the "t
 </script>
 ```
 
+Alternatively, use the [Theme component](https://svelte.carbondesignsystem.com/components/Theme) to manage the theme reactively.
+
 ### Importing components
 
 Import components from `carbon-components-svelte` in the `script` tag of your Svelte file. Visit the [documentation site](https://svelte.carbondesignsystem.com) for examples.
@@ -137,7 +144,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.
+[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.
 
 > [!NOTE]
 > Using `carbon-preprocess-svelte` is optional and not a prerequisite for this library. It should be installed as a development dependency.
@@ -147,7 +154,7 @@ Import components from `carbon-components-svelte` in the `script` tag of your Sv
 npm i -D carbon-preprocess-svelte
 
 # pnpm
-pnpm i -D carbon-preprocess-svelte
+pnpm add -D carbon-preprocess-svelte
 
 # Yarn
 yarn add -D carbon-preprocess-svelte
@@ -179,39 +186,9 @@ The preprocessor optimizes imports from the following packages:
 + import Airplane from "carbon-pictograms-svelte/lib/Airplane.svelte";
 ```
 
-#### Usage
-
-See [examples](examples) for full configurations.
-
-```js
-// 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`.
-
-```diff
-// 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](https://vitejs.dev/guide/api-plugin) extends the Rollup plugin API).
+`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).
 
 `carbon-components-svelte@0.85.0` or greater is required.
 
@@ -230,9 +207,42 @@ 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
+### Configure your bundler
+
+Add `optimizeImports` to your Svelte preprocessor and `optimizeCss` to your bundler plugins. See [examples](examples) for full configurations.
 
-See [examples](examples) for full configurations.
+**Vite**
+
+```js
+// vite.config.js
+import { svelte, vitePreprocess } from "@sveltejs/vite-plugin-svelte";
+import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";
+
+export default {
+  plugins: [
+    svelte({
+      preprocess: [vitePreprocess(), optimizeImports()],
+    }),
+    optimizeCss(),
+  ],
+};
+```
+
+**SvelteKit**
+
+```js
+// svelte.config.js
+import adapter from "@sveltejs/adapter-static";
+import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";
+import { optimizeImports } from "carbon-preprocess-svelte";
+
+const config = {
+  preprocess: [vitePreprocess(), optimizeImports()],
+  kit: { adapter: adapter() },
+};
+
+export default config;
+```
 
 ```js
 // vite.config.js
@@ -245,6 +255,112 @@ export default defineConfig({
 });
 ```
 
+**Rollup**
+
+```js
+// rollup.config.js
+import svelte from "rollup-plugin-svelte";
+import { optimizeCss, optimizeImports } from "carbon-preprocess-svelte";
+
+const production = !process.env.ROLLUP_WATCH;
+
+export default {
+  plugins: [
+    svelte({
+      preprocess: [optimizeImports()],
+    }),
+    production && optimizeCss(),
+  ],
+};
+```
+
+**Webpack**
+
+```js
+// webpack.config.mjs
+import { OptimizeCssPlugin, optimizeImports } from "carbon-preprocess-svelte";
+
+export default {
+  module: {
+    rules: [
+      {
+        test: /\.svelte$/,
+        use: {
+          loader: "svelte-loader",
+          options: {
+            preprocess: [optimizeImports()],
+          },
+        },
+      },
+    ],
+  },
+  plugins: [new OptimizeCssPlugin()],
+};
+```
+
+## Icons and pictograms
+
+The icon and pictogram sets ship as separate packages of individual Svelte components. Each is optional, so install only what you need.
+
+### Icons
+
+2,700+ icons designed for product UI, in four sizes (16, 20, 24, and 32 pixels), set with a single prop.
+
+```sh
+# npm
+npm i carbon-icons-svelte
+
+# pnpm
+pnpm add carbon-icons-svelte
+
+# Yarn
+yarn add carbon-icons-svelte
+
+# Bun
+bun add carbon-icons-svelte
+```
+
+```svelte
+<script>
+  import Add from "carbon-icons-svelte/lib/Add.svelte";
+</script>
+
+<Add size={24} />
+```
+
+### Pictograms
+
+1,500+ illustrative pictograms for empty states, onboarding, hero sections, and feature callouts. Larger than icons, 64px by default.
+
+```sh
+# npm
+npm i carbon-pictograms-svelte
+
+# pnpm
+pnpm add carbon-pictograms-svelte
+
+# Yarn
+yarn add carbon-pictograms-svelte
+
+# Bun
+bun add carbon-pictograms-svelte
+```
+
+```svelte
+<script>
+  import Cloud from "carbon-pictograms-svelte/lib/Cloud.svelte";
+</script>
+
+<Cloud />
+```
+
+## Documentation for LLMs
+
+Documentation is available in LLM-friendly plain text for use with coding assistants, plus a standalone Markdown document for every component. Append `.md` to any component's URL to read it.
+
+- **[llms.txt](https://svelte.carbondesignsystem.com/llms.txt)**: a component index where each entry links to its per-component Markdown doc, sized for model context windows.
+- **[llms-full.txt](https://svelte.carbondesignsystem.com/llms-full.txt)**: the full component documentation in a single plain-text file.
+
 ## Examples
 
 - [examples/rollup](examples/rollup/)

package/css/_code-snippet.scss

@@ -0,0 +1,46 @@
+@import "carbon-components/scss/globals/scss/vars";
+
+/// Edge fade for code snippets (Carbon React v11 parity). v10 uses
+/// `--overflow-indicator` gradient elements that this library's markup does not
+/// render. v11 masks the scroll container instead, which is background-agnostic
+/// and works across themes, the light variant, and skeleton state.
+/// @access private
+/// @group components
+@mixin code-snippet-fade {
+  .#{$prefix}--snippet--single .#{$prefix}--snippet-container {
+    mask-image: linear-gradient(
+      90deg,
+      $black-100 calc(100% - #{$carbon--spacing-07}),
+      transparent 100%
+    );
+
+    // The focus outline is drawn on this same element, so the edge fade would
+    // clip the ring. Drop the mask while focused so the outline is unbroken.
+    &:focus {
+      mask-image: none;
+    }
+  }
+
+  // Expanded multi-line adds padding-bottom: $spacing-05, so the bottom fade
+  // offset matches that padding when content no longer scrolls.
+  .#{$prefix}--snippet--multi .#{$prefix}--snippet-container {
+    mask-image: linear-gradient(
+        90deg,
+        $black-100 calc(100% - #{$carbon--spacing-07}),
+        transparent 100%
+      ),
+      linear-gradient(
+        $black-100 calc(100% - #{$spacing-05}),
+        transparent 100%
+      );
+    mask-composite: intersect;
+
+    &:focus {
+      mask-image: none;
+    }
+  }
+}
+
+@include exports("code-snippet-fade") {
+  @include code-snippet-fade;
+}

package/css/_combo-button.scss

@@ -0,0 +1,50 @@
+@import "carbon-components/scss/globals/scss/vars";
+@import "carbon-components/scss/globals/scss/helper-mixins";
+@import "carbon-components/scss/globals/scss/vendor/@carbon/elements/scss/import-once/import-once";
+
+/// Groups a `ComboButton`'s primary action and icon-only trigger button into
+/// a single visual unit. The divider mirrors v10's own `.bx--btn-set`
+/// technique (a box-shadow on the trigger, since adjacent buttons have no
+/// margin between them); the chevron rotates on open.
+/// @access private
+/// @group components
+@mixin combo-button {
+  .#{$prefix}--combo-button {
+    display: inline-flex;
+  }
+
+  .#{$prefix}--combo-button .#{$prefix}--combo-button__trigger:not(:focus) {
+    box-shadow: to-rem(-1px) 0 0 0 $button-separator;
+  }
+
+  .#{$prefix}--combo-button
+    .#{$prefix}--combo-button__trigger.#{$prefix}--btn--disabled {
+    box-shadow: to-rem(-1px) 0 0 0 $disabled-03;
+  }
+
+  .#{$prefix}--combo-button__trigger .#{$prefix}--btn__icon {
+    transition: transform $duration--fast-01 motion(standard, productive);
+  }
+
+  .#{$prefix}--combo-button__trigger--open .#{$prefix}--btn__icon {
+    transform: rotate(180deg);
+  }
+
+  // Extra-small (Carbon React size="xs", 24px). Neither Button's "small"
+  // class (32px) nor any other Button size lands on 24px, so shrink further
+  // on top of the "small" size already passed to both buttons.
+  .#{$prefix}--combo-button--xs .#{$prefix}--btn {
+    min-height: to-rem(24px);
+    padding-top: 0;
+    padding-bottom: 0;
+  }
+
+  .#{$prefix}--combo-button--xs .#{$prefix}--btn--icon-only {
+    padding-right: to-rem(4px);
+    padding-left: to-rem(4px);
+  }
+}
+
+@include exports("combo-button") {
+  @include combo-button;
+}

package/css/_copy-button.scss

@@ -0,0 +1,68 @@
+// CopyButton variants: a `ghost` kind and a set of square sizes that mirror
+// `Button`. Carbon ships a single, fixed-size `bx--copy-btn` (a 2.5rem square
+// with a `$layer` fill), so these modifiers extend it to match the `Button`
+// API. The ghost kind reuses Button's ghost theme (transparent fill, subtle
+// hover) so a CopyButton can sit beside a ghost Button without a seam; the
+// sizes scale the square to Button's small/lg/xl heights.
+//
+// Loaded after Carbon's base styles (see all.scss), so each modifier is
+// double-classed to win at equal specificity against the base `bx--copy-btn`
+// declarations it overrides.
+
+@import "carbon-components/scss/globals/scss/vars";
+@import "carbon-components/scss/globals/scss/vendor/@carbon/elements/scss/import-once/import-once";
+
+/// CopyButton ghost kind and square sizes.
+/// @access private
+/// @group copy-button
+@mixin copy-button {
+  //--------------------------------------------------------------------------
+  // Ghost kind (mirrors Button's ghost theme)
+  //--------------------------------------------------------------------------
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--ghost {
+    background-color: transparent;
+  }
+
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--ghost:hover {
+    background-color: $hover-ui;
+  }
+
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--ghost:active {
+    background-color: $active-ui;
+  }
+
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--ghost .#{$prefix}--snippet__icon {
+    fill: $icon-01;
+  }
+
+  //--------------------------------------------------------------------------
+  // Sizes (square dimensions matching Button's small/lg/xl heights;
+  // `default` keeps Carbon's native 2.5rem)
+  //--------------------------------------------------------------------------
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--sm {
+    width: 2rem;
+    height: 2rem;
+  }
+
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--lg {
+    width: 3rem;
+    height: 3rem;
+  }
+
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--xl {
+    width: 4rem;
+    height: 4rem;
+  }
+
+  // Grow the icon on the larger squares so it stays visually centered rather
+  // than marooned in whitespace.
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--lg .#{$prefix}--snippet__icon,
+  .#{$prefix}--copy-btn.#{$prefix}--copy-btn--xl .#{$prefix}--snippet__icon {
+    width: 1.25rem;
+    height: 1.25rem;
+  }
+}
+
+@include exports("copy-button-variants") {
+  @include copy-button;
+}

package/css/_datepicker.scss

@@ -65,3 +65,73 @@
 @include exports('datepicker-month-nav-disabled') {
   @include date-picker-month-nav-disabled;
 }
+
+// Carbon ships no styles for flatpickr's monthSelect plugin (used by
+// `datePickerType="month"`), so style its raw classes directly, matching
+// the token usage of the day-cell styles Carbon backports from v11.
+@mixin date-picker-month-select {
+  .flatpickr-monthSelect-months {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+    margin: 0.625rem 0.0625rem 0.1875rem;
+  }
+
+  .flatpickr-monthSelect-month {
+    box-sizing: border-box;
+    display: flex;
+    padding: 0.625rem;
+    align-items: center;
+    justify-content: center;
+    border: 0;
+    border-radius: 0;
+    background: none;
+    color: $text-01;
+    cursor: pointer;
+    font-weight: 400;
+    text-align: center;
+
+    &:hover {
+      background: $hover-ui;
+    }
+
+    &:focus {
+      outline: 1px solid $focus;
+      outline-offset: -1px;
+    }
+
+    &.selected {
+      background-color: $interactive-01;
+      color: $text-04;
+    }
+
+    &.disabled {
+      color: $disabled-02;
+      cursor: not-allowed;
+
+      &:hover {
+        background: none;
+      }
+    }
+  }
+}
+
+@include exports('datepicker-month-select') {
+  @include date-picker-month-select;
+}
+
+// The month grid is shorter than the day grid Carbon sizes `.flatpickr-calendar.open`
+// for (21rem), which leaves a large empty gap below the 4x3 month layout.
+// `updateClasses` in createCalendar.js marks the container with
+// `.#{$prefix}--date-picker__calendar--month` so this can scope the shorter
+// height without `:has()` (unsupported at the Svelte 5 browser baseline);
+// the extra class also out-specifies the base `.flatpickr-calendar.open` rule
+// (which loads before this partial).
+@mixin date-picker-month-select-height {
+  .flatpickr-calendar.open.#{$prefix}--date-picker__calendar--month {
+    height: 14rem;
+  }
+}
+
+@include exports('datepicker-month-select-height') {
+  @include date-picker-month-select-height;
+}

package/css/_dialog.scss

@@ -0,0 +1,47 @@
+@import "carbon-components/scss/globals/scss/vars";
+@import "carbon-components/scss/globals/scss/helper-mixins";
+@import "carbon-components/scss/globals/scss/vendor/@carbon/elements/scss/import-once/import-once";
+
+/// Dialog primitive. carbon-components@10.58 ships no <dialog> styles, so
+/// layout, background, and backdrop dimming are authored from scratch here,
+/// using the closest v10 token equivalents ($ui-01, $text-01, $ui-03, $overlay-01).
+/// @access private
+/// @group components
+@mixin dialog {
+  .#{$prefix}--dialog {
+    position: fixed;
+    top: 0;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    box-sizing: border-box;
+    width: rem(768px);
+    max-width: 100%;
+    max-height: 100%;
+    margin: auto;
+    padding: $carbon--spacing-05;
+    border: 1px solid $ui-03;
+    background-color: $ui-01;
+    color: $text-01;
+
+    @include carbon--breakpoint(md) {
+      max-width: 84%;
+    }
+
+    @include carbon--breakpoint(lg) {
+      max-width: 60%;
+    }
+
+    @include carbon--breakpoint(xlg) {
+      max-width: 48%;
+    }
+  }
+
+  .#{$prefix}--dialog::backdrop {
+    background-color: $overlay-01;
+  }
+}
+
+@include exports("dialog") {
+  @include dialog;
+}