Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
810 lines (549 loc) · 43 KB

CONTRIBUTING.md

File metadata and controls

810 lines (549 loc) · 43 KB

Contributing

If you're not sure what to build or how to approach a change, file an issue before opening a PR.

Prerequisites

Codebase:

Use Bun as the package manager and task runner. Run package scripts with bun <script> and one-off binaries with bunx <bin>.

Project set-up

Fork the repo and clone your fork:

git clone <YOUR_FORK>
cd carbon-components-svelte

Set the original repository as the upstream:

git remote add upstream git@github.com:carbon-design-system/carbon-components-svelte.git
# verify that the upstream is added
git remote -v

Set up

bun setup

This installs root and docs dependencies and generates TypeScript definitions and docs/src/COMPONENT_API.json.

Component documentation lives in docs/. The site uses Vite, Routify 3, Svelte 5, and MDsveX. The Vite config resolves carbon-components-svelte to the repository root, so edits under src/ show up in the docs without a separate package link.

To preview the docs site locally:

cd docs
bun dev

The site serves at http://localhost:5173/ (or the next available port).

Best practices

Conventions used across src/. Follow them in new and changed code.

Code style

Comments:

  • Do not add trivial comments. If a comment restates what the code already says, delete it or improve the code instead.
  • Reserve comments for non-obvious behavior: Svelte reactivity edge cases, ARIA placement, workarounds for Carbon v10 gaps. See loop guards in ContentSwitcher.svelte and the duplicate-dispatch guard in Checkbox.svelte.

Patterns:

  • Use function declarations in <script>. Declare handlers, defaults, and logic as functions rather than inline in markup. Named functions give stable references for default prop values (see defaultShouldFilter in ComboBox.svelte).
  • Avoid afterUpdate. It runs after every DOM update and is easy to loop in Svelte 5. Prefer $: reactive statements with guards, event handlers, onMount, or tick() for DOM reads. Legacy code may still use afterUpdate for scroll-sync or measurement; do not add new uses without a strong reason.
  • When moving a dispatch(...) from afterUpdate to $:, timing changes. afterUpdate ran after the DOM commit; $: runs during the flush. A throwing handler can abort the rest of that flush. Update internal prev state first, then tick().then(() => dispatch(...)), and snapshot values for the callback (const next = value). See FileUploader.svelte, the storage components, and Theme.svelte. Keep cancelable, user-driven dispatches synchronous.
  • Reset cached positional state (scroll offset, highlighted index, measured sizes) reactively when its source collection changes, not just on open/close. A value cached against the old list, such as a scroll position into pre-filter results, silently points past the end of the new one. Use a $: guard comparing against the previous length or identity.
  • Put component-level JSDoc first (@restProps, @slot, @template), then all export let props (each with its own JSDoc), then imports, then local logic. See Button.svelte and Box.svelte.
  • Keep small, component-specific helpers inline in the <script> block. Extract to src/utils/ only when the logic is shared across components or complex enough to unit-test in isolation. See debounce.js and isOutsideClick.js. Token primitives such as Text.svelte and Box.svelte map props to utility classes and inline styles directly; their themeable rules live in css/_type.scss, css/_box.scss, and related partials.
  • Forward DOM events with bare on:click / on:focus (no handler) on the underlying element (Button.svelte).
  • Interpolate attribute values with Svelte's attribute syntax, not template literals: id="{treeId}-{id}-subtree", not id={`${treeId}-${id}-subtree`}. Keep template literals only when a value needs nested quotes or logic the shorthand can't express (see aria-label in PinCodeInput.svelte).
  • Compound components use setContext / getContext with carbon: keys (CheckboxGroup.svelte).
  • Default element IDs use ccs-${Math.random().toString(36)}.
  • Key {#each} blocks, for example (item.id ?? index) (see RecursiveList.svelte).
  • Put shared logic in src/utils/, for example debounce.js and isOutsideClick.js. Prefer pure, DOM-free functions for layout, geometry, and state-decision math (see virtualize.js). They are unit-testable in isolation, so edge cases get covered once in a util test instead of through expensive component renders.
  • ComboBox, Dropdown, and MultiSelect share listbox behavior (virtualization, keyboard navigation, outside-click) through src/utils/. When you change shared menu behavior, apply and test the change in all three. The per-component wiring is parallel but not abstracted.
  • Use Carbon v10 markup: bx-- BEM classes in templates; SCSS patches use $prefix and tokens. See Custom styles.
  • Do not add themeable styles in per-component <style> blocks (see Custom styles).
  • Use the legacy Svelte 5 API. Components use export let, $:, and createEventDispatcher. Do not introduce runes ($state, $derived, $effect) unless the project explicitly migrates.
  • Bind per-iteration values once with {@const} inside {#each} blocks, then reuse them across the markup instead of recomputing inline. See isSelected / isExpanded / rowClassValue in DataTable.svelte and actualIndex in ComboBox.svelte.
  • Use Set / Map for membership and id lookups instead of .includes() / .find(). The O(1) lookup matters in components that can hold large datasets. See the selectedRowIdsSet / nonSelectableRowIdsSet sets in DataTable.svelte and the itemsById map in ComboBox.svelte.
  • Gate expensive lookups by state. When an O(n) array computation is only needed in a certain state (on open, on hover), compute it imperatively in that state rather than in an always-on reactive statement or derivation. See filteredItems = open ? items.filter(...) : [] in ComboBox.svelte.
  • Do not clobber external props. Never write internal or measured values back into an exported prop. A consumer may bind: to a prop to control behavior, and overwriting it silently breaks that control. Measure into an internal fallback and fall back to it only when the public prop is unset. See measuredMaxHeight / measuredPadding in ExpandableTile.svelte and the showMoreLess handling in CodeSnippet.svelte. This is the prop-facing counterpart to the afterUpdate guidance above.
  • Name booleans and predicates with an is prefix. Use is<Verb> / is<Adjective> for boolean state and predicate functions. See the isOutsideClick util, isSelected / isExpanded in DataTable.svelte, and isFluid in TextInput.svelte.
  • Prefer enums over booleans for props. When a prop selects among mutually exclusive variants, or the set of variants may grow, use a string-union prop instead of several boolean flags. It keeps states exclusive and extensible. See kind and size in Button.svelte. Keep booleans for genuinely binary, independent toggles such as disabled and open.
  • Apply classes with the class: directive, not string concatenation or template literals. Use class:bx--name={true} for classes that are always present and class:bx--name--modifier={condition} for conditional ones. This keeps each class on its own line and the toggling logic readable. See TextInput.svelte: class:bx--form-item={true} (always) alongside class:bx--text-input-wrapper--inline={inline} (conditional).
  • Forward $$restProps to the most important element. When a component has a clear primary element with the most customizable props, such as the <input> or <button>, spread {...$$restProps} onto it so consumers can set attributes like name, placeholder, or data-* on the element they care about. See the <input> in TextInput.svelte. Only when there is no such element does it go to the wrapper (top-level element), as in Tile.svelte.
  • Name slots in camelCase. No dashes: a hyphenated slot name will not map to a Svelte 5 Snippet. Use labelChildren, not label-children.
  • Mirror the shadowed prop in the slot name. When a slot overrides the content a prop renders, name it after that prop. Svelte forbids a slot from matching an exported prop name exactly, so suffix it with Children: the labelChildren slot shadows the labelText prop. See <slot name="labelChildren"> in TextInput.svelte.
  • Set dynamic styles with the style: directive, not inline style strings or template literals: style:left="{x}px". See ContextMenu.svelte and the thumb position in Slider.svelte.

The {#if skeleton} early-return pattern is being phased out. Follow it only when maintaining existing skeleton code.

API, docs, and workflow:

  • Never hand-edit generated files. src/**/*.svelte.d.ts, src/index.d.ts, and docs/src/COMPONENT_API.json are produced by sveld and are gitignored.
  • Document the public API in JSDoc. Cover every exported prop, event, slot, and rest-props target. See Typing with JSDoc.
  • Update component docs when appropriate. New props, features, and behavior changes need matching .svx updates. See Component documentation.
  • Use $$restProps + @restProps for passthrough attributes (see Search.svelte).
  • Scope lint and tests to what you changed. See Checks and Unit tests.

Development workflow

Create a topic branch from master. Keep your PR focused and your branch current with upstream master.

git checkout -b new-feature

Component format

Put each component in this layout:

src/Component
│
└───Component.svelte // main component
└───ComponentSkeleton.svelte // Skeleton component (if applicable)
└───index.js // export components

Type definitions are generated by sveld. See Typing with JSDoc.

Typing with JSDoc

Types live in JSDoc comments, not TypeScript inside .svelte files. sveld (via bun build:docs) reads those comments and writes:

  • src/**/*.svelte.d.ts and src/index.d.ts (consumer types)
  • docs/src/COMPONENT_API.json (docs site API tables)

The auto-generated Props / Typedefs / Slots / Events tables at the bottom of each docs page come from COMPONENT_API.json. JSDoc is the source of truth for API tables; the .svx file covers usage examples and prose.

JSDoc tags

Tag Purpose
@type Prop type
@template Generic type params (supports defaults: @template {ComboBoxItem<any>} [Item=ComboBoxItem<any>])
@typedef / @property Item/shape types, event payloads
@bindable writable / @bindable readonly Two-way and element refs
@event Dispatched custom events (with payload type)
@slot Named/default slot props
@restProps Where $$restProps land
@extends Inherit props from another component (skeleton wrappers)
@default, @example Docs metadata

Reference ComboBox.svelte for @template, @typedef, @event, @slot, and typed props. For generics in plain JS, see src/utils/debounce.js.

Example

/**
 * Specify the size of the component
 * @type {"sm" | "default" | "lg"}
 */
export let size = "default";

After changing a component's API

Whenever you add, remove, or retype an exported prop, slot, or event (including its JSDoc @type), regenerate and verify:

bun build:docs   # sveld: types + COMPONENT_API.json
bun test:types   # svelte-check on tests/

bun setup already runs build:docs once. Repeat build:docs only when the component API changes.

Creating a component

File an issue first.

If you add a new component, export it from src/index.js:

export { CopyButton } from "./CopyButton";
export { ComboBox } from "./ComboBox";
+ export { FixedComboBox } from "./FixedComboBox";
export {
  ComposedModal,
  ModalHeader,
  ModalBody,
  ModalFooter,
} from "./ComposedModal";

See Component documentation for the docs checklist.

Component documentation

Update documentation when the change is user-facing:

  • New component: add a new page
  • New prop, event, or slot: document usage (JSDoc covers the API table; add an example if non-obvious)
  • New feature or variant: add or extend an example section
  • Notable behavioral change: update existing prose/examples so they stay accurate

Skip doc updates for internal refactors with no API or behavior change.

Where docs live

Path Purpose
docs/src/pages/components/{Component}.svx Main component page (for example Button.svx): prose + examples
docs/src/pages/framed/{Component}/{Example}.svelte Interactive demos referenced by <FileSource>

Routify picks up new .svx files automatically. docs/scripts/index-docs.ts indexes each page and its ## headings for search. No separate nav registration is required.

Prose conventions (backticks, plain language, SVX gotchas): see docs/COMPONENT_DOCS_STYLE.md.

Preview locally with cd docs && bun dev.

Example conventions

Before adding an example, read the component's .svx and follow its order, grouping, and voice. Reference pages: Button.svx, ComboBox.svx.

Page structure:

  1. Frontmatter block at the very top: a description: field, plus components: when the page renders an API table or imports components in a <script>.
  2. Optional <script> imports (components + icons used inline).
  3. ## Basic first, then one ## Section title per variant/feature, each with a short description then the demo.

Frontmatter description:

The lead sentence lives in the frontmatter description: field, not in body prose. It renders in the page hero.

  • 1–2 plain sentences, ~180 characters max.
  • Describe what the component is for, not how it works. No implementation details ("resize observer", "forwards mouse events", "keyed for performance").
  • Renders as plain text: no inline code or [links].
  • The body must start with a ## heading. A leading body paragraph is re-extracted by the heroIntro remark plugin in svelte.config.ts and silently overrides the frontmatter description. When lifting an old intro, fold any trailing sentences or links into the ## Basic prose.
---
components: ["Dropdown", "DropdownSkeleton", "FluidDropdownSkeleton"]
description: Dropdowns provide a select input with a dropdown menu, with multiple states, sizes, and customization options.
---

Headings and grouping:

  • The first, plainest example is ## Basic — never ## Default.
  • Keep headings concise. The page title already names the component, so drop the repeated component-noun prefix (Header with app switcher → App switcher) and trailing state / variant / size (Invalid state → Invalid, Light variant → Light, Small size → Small).
  • Group related examples under a ## Group heading with ### children when several share an axis: Sizes, States (invalid / warning / disabled / read-only), Fluid, Variants, Skeleton, Selectable, Filterable, Low contrast, and the like. Prefer this over a long flat list of ## headings. Lead each group with its simplest member using a descriptive label (never Default); the group's base example can sit directly under the ## Group heading. See TextInput.svx (Sizes / States / Fluid), Tag.svx (Filterable / Selectable), and TreeView.svx.
  • Name variant families with a Base (qualifier) form: Fluid (invalid), Icon-only (large).

Renaming headings (anchors):

Heading slugs are GitHub-style (rehype-slug): lowercase, spaces to -, parentheses and punctuation stripped (Fluid variant (invalid) → fluid-invalid). When you rename a heading that is a link target:

  • Fix in-page links: grep -nE '\(#' <file>.svx
  • Fix cross-page links: grep -rn '<Component>#<old-anchor>' docs/src/pages
  • To keep an anchor while grouping, demote the heading to ### with its text unchanged — the slug is preserved. See #selectable / #radio-group in ContextMenu.svx and Portal#custom-target.

Description language: imperative, prop-focused. See Writing style for Carbon content rules.

  • "Set kind="secondary" for secondary actions."
  • "Hide the label visually by setting hideLabel to true. The label remains available to screen readers."

Typical section order (follow sibling sections on that page):

  1. ## Basic
  2. Core variants grouped (kinds, sizes)
  3. Feature sections (slots, filtering, typeahead, portal, etc.)
  4. Layout options (direction, light)
  5. Validation states (invalid, warn)
  6. Interaction states (disabled, readonly)
  7. Skeleton (if applicable)
  8. Advanced / performance (virtualization, async)
  9. Programmatic or reactive behavior last

Insert new sections in the logical group, and nest the variants above under ## Group + ### children (see Headings and grouping). Do not append every example to the end if it belongs with related variants. Reactive / bind:-driven examples belong high up near the basics; loading / skeleton examples go last.

Inline vs framed:

  • Inline: simple, static demos directly in the .svx file
  • <FileSource src="/framed/Component/Example" />: reactive state, bind:this, events, async behavior, or demos too large for inline. Add the Svelte file under docs/src/pages/framed/{Component}/ (PascalCase name, for example ReactiveComboBox.svelte)

Use a framed example whenever the demo contains script logic (state, handlers, async work). The full source shows in the docs, so keep it readable:

  • Do not add JSDoc to framed examples. They are usage demos, not the public API. Save typed JSDoc for the components under src/.
  • Add short, concise, high-value code comments only where they earn their place, such as flagging that demo code is not production guidance: // For demo purposes only: NEVER hardcode secrets in production. Skip comments that restate the code.
  • Simulate API or async behavior with await new Promise((resolve) => setTimeout(resolve, 300)) rather than wiring up a real network call. See CopyInputAsync.svelte.

Other patterns:

  • No admonitions. Fold accessibility notes and non-obvious caveats into the relevant example's prose. Do not use > [!NOTE] / > [!WARNING] / > [!TIP] / > [!CAUTION] blocks.
  • Keyboard keys in prose: use <DocKbd label="Enter" /> for named keys (Enter, Escape, Shift, Ctrl, Space, etc.). mdsvex auto-imports DocKbd; do not add a manual import. Do not use backticks (Escape), raw <kbd>, or bold (**Enter**). For combinations, use one component per key: <DocKbd label="⌘" />+<DocKbd label="C" />. Keep collective phrases as plain text ("arrow keys", "modifier keys", "keyboard navigation"). Prop values and UI copy inside component examples are out of scope (e.g. placeholder="Enter user name...", shortcutText="⌘C").
  • Cross-links to related components: [Modal](/components/Modal#modal-with-dropdowns)
  • Reuse the same sample data shapes as neighboring examples on that page
  • For layout and spacing (flex, gap, stacked elements), use the Stack component rather than raw HTML with ad-hoc inline styles. Reserve hand-written layout markup for cases Stack cannot express.
  • Add data-outline to an element when an outline makes the demo clearer, for example marking a right-click target in a context menu. The framed module provides the global style; see <p data-outline …> in ContextMenuTarget.svelte.

Writing style

Follow Carbon's writing style: direct, concise, present tense. Section descriptions explain what a prop does and when to use it, not what the component "allows."

Prose and inline code

Inline code in .svx prose is styled as Carbon code tokens. Keep backticks sparse so section intros stay readable.

Split of responsibilities:

  • JSDoc + auto-generated API tables = exhaustive identifier reference
  • .svx prose = readable explanation; examples = copy-paste usage

Backtick when essential (one primary target per paragraph):

  • The prop/API being configured in that section
  • Literal values the reader copies (true, "compact")
  • Methods/utilities (TreeView.expandAll())
  • Svelte/HTML tokens (let:node, bind:checked, role="treeitem")

Use plain language instead:

  • Data shape in words ("unique id and display text") rather than listing id, text, disabled in one sentence
  • Drop filler: "the prop", "the method" (prefer "Set activeId" not "Set the activeId prop")
  • Cross-link sibling sections by name instead of inline prop lists

Do not edit in prose-only passes:

  • Live Svelte examples, <FileSource />, fenced code blocks, reference tables (events/gestures/slot vars)

SVX gotchas

In .svx files, markdown prose is compiled as Svelte. Bare { ... } in prose is parsed as JavaScript, not displayed text.

Bad (runtime error) Good
`event.detail` as { key, direction } `event.detail` shaped like `{ key, direction }`
receives (a, b, { key, ascending }) receives `(a, b, { key, ascending })`

Always wrap object literals and expressions in backticks, or rephrase without braces. See DataTable.svx sort section for a real incident.

Avoid Prefer
Trivializers: "easy", "easily", "makes it easier to", "for performance reasons" State the behavior directly
Latin abbreviations: e.g., i.e. "for example", "that is" (or rephrase without)
Indirect phrasing: "allows you to", "allowing you to", "allows for" Direct imperative: "Set … to …", "Use … to …"
Filler tails that restate the obvious: "This provides more visual emphasis.", "This prevents user interaction." Cut unless it adds when-to-use guidance
Passive or future tense in intros Present tense, active voice
Varied hideLabel / hideLegend wording Standard boilerplate (below)
Listing every prop in backticks in one intro sentence Plain-language data shape; one configuring prop backtick per paragraph
`selectedIds` tracks a single id` (implementation narration) "Only one node is selected at a time"
Prop laundry lists in intros Links to sibling sections (TreeView Basic pattern)

Standard boilerplate for hidden labels (copy verbatim):

Hide the label visually by setting hideLabel to true. The label remains available to screen readers.

Use hideLegend analogously for legend-hiding props.

Before / after examples:

# Before
Create a basic tree view using the `nodes` prop. Each node requires a unique `id` and `text`, with optional properties for `disabled`, `icon`, and child `nodes`.

# After
Create a basic tree view using the `nodes` prop. Each node needs a unique id and display text; icons, disabled state, and nested children are optional.

# Before
Set the initial active node using the `activeId` prop.

# After
Set the initial active node using `activeId`.

# Before
Set openOnClear to true to allow users to immediately see all available items.

# After
Set `openOnClear` to `true` to reopen the dropdown menu after clearing the selection.
This lets users immediately browse all available items without clicking the input again.

# Before
For async (e.g., server-side) filtering, bind to value…

# After
For async (for example, server-side) filtering, bind to `value`…

# Before
Virtualization allows you to render large lists efficiently for performance reasons.

# After
Virtualization renders only the items currently visible in the viewport, improving performance for large lists.

# Before
The menu closes from the trigger, the `Escape` key, or an outside click.

# After
The menu closes from the trigger, <DocKbd label="Escape" />, or an outside click.

New component checklist

  1. Export from src/index.js
  2. JSDoc all public API → bun build:docs
  3. Create docs/src/pages/components/{Component}.svx modeled on a similar existing component: a frontmatter description:, then ## Basic first (see Example conventions for structure and grouping). Follow prose conventions in COMPONENT_DOCS_STYLE.md.
  4. Add framed examples only where interactivity requires them
  5. Preview with cd docs && bun dev

Custom styles (patching Carbon v10)

The library pins carbon-components to v10 (10.58.x). When a style fix or feature from newer Carbon is missing from the v10 SCSS, or when the Svelte components need a tweak Carbon does not provide, put the patch in a hand-authored SCSS partial under css/. These compile into the shipped theme stylesheets. Use them instead of per-component <style> blocks for anything that should be themeable.

Anatomy of a partial

Each patch is a leading-underscore partial (for example css/_breadcrumb.scss, css/_tag.scss) that imports the Carbon variables and mixins it needs, defines a single named mixin, and emits it through Carbon's exports() import-once guard:

@import "carbon-components/scss/globals/scss/vars";
@import "carbon-components/scss/globals/scss/typography";

/// Small breadcrumb variant (Carbon React `size="sm"` parity)
/// @access private
/// @group components
@mixin breadcrumb-sm {
  .#{$prefix}--breadcrumb--sm {
    @include type-style("label-01");
    margin-right: $carbon--spacing-02;
  }
}

@include exports("breadcrumb-sm") {
  @include breadcrumb-sm;
}

Conventions

Style only through Carbon tokens and mixins: spacing ($carbon--spacing-*), type (type-style(...)), to-rem(...), and theme color tokens. Do not hardcode raw px or hex values. Tokens keep themes consistent and survive a future Carbon upgrade.

Reference classes through $prefix (.#{$prefix}--breadcrumb), never a literal .bx--….

Do not use :has(). It exceeds the Svelte 5 browserslist baseline (Firefox 83/Safari 14) the CSS targets, and Lightning CSS cannot prefix or polyfill it. Mark parents explicitly instead (for example a hasLeftIcon prop emitting a marker class). Same rule for any selector newer than that baseline.

Wrap output in @include exports("name") so a partial imported by multiple theme entry files emits its rules only once.

Document the mixin with SassDoc (/// @access private, /// @group components).

Token utility partials (css/_type.scss, css/_box.scss, …) emit bx--type-* and bx--box-* classes. Map v11 token names in docs and props to v10 theme variables in SCSS where needed (for example layer-01 → $ui-01). Share spacing scale values through css/_spacing-scale.scss when multiple partials use the same rem steps.

Registering a partial

A partial ships only after a theme entry file imports it. Add @import "./name"; to the custom component overrides block, which comes after Carbon's own globals/scss/styles, in all six entry files. Keep import order identical across them:

  • css/all.scss
  • css/white.scss
  • css/g10.scss
  • css/g80.scss
  • css/g90.scss
  • css/g100.scss

Rebuild

After editing any .scss under css/, you must run bun build:css locally:

bun build:css

The compiled css/*.css are not committed (they are gitignored) — but they are still required at runtime, so without this step your local docs site and e2e tests will use stale (or missing) styles. bun setup runs build:css once on a fresh clone, and CI/release run it on demand; neither helps an in-progress local edit.

This compiles every non-partial *.scss (sass, compressed) through Lightning CSS and writes css/*.css plus css/css.d.ts. Commit only the .scss source — never the generated *.css. The small css/css.d.ts (module declarations) is committed, so type-checks resolve the CSS imports without a build; commit it too if adding or removing a theme entry changes it.

The prebundled CSS targets the Svelte 5 browser support baseline (Firefox 83/Safari 14), not older browsers. Matching that baseline lets Lightning CSS drop legacy fallbacks. Author SCSS to that baseline; see the :has() note in Conventions.

Checks

See Best practices for scoping. Run checks against what you changed. Full-repo runs are slow and surface unrelated failures.

For format and lint, scope Biome to what you touched:

# Specific paths — always lints the current working tree
bunx biome check --write src/DataTable

# Staged files only (what a commit would include)
bunx biome check --write --staged

# Files committed on this branch relative to master
bunx biome check --write --changed --since=master

Pick the form that matches your state. --changed and --staged resolve their file list from git, so each sees a different slice:

  • Path scoping (src/DataTable) lints whatever is on disk now, committed or not. Use it while editing.
  • --staged lints the git index. Run it after git add.
  • --changed diffs commits against the default branch. It does not see uncommitted or unstaged edits, so it reports nothing until you commit.

bun run lint runs Biome over the entire repository. Reserve it for broad sweeps.

For unit tests, match a pattern against test file paths instead of running the whole suite:

bun run test DataTable

The full suite (bun run test) is slow and can hit unrelated flaky UIShell focus failures. Scope to the component you touched.

Types and E2E:

  • bun test:src-types type-checks src/ (uses tsconfig.types.json)
  • bun test:types runs svelte-check on *.svelte and .ts files in tests/
  • bunx playwright test --grep "Breakpoint" runs a focused E2E pattern (see E2E testing); bun run test:e2e runs the full E2E suite

Testing

Unit tests

Unit tests live in tests/ and use Vitest with @testing-library/svelte. See Checks for scoped runs.

Layout

tests/
  ComponentName/
    ComponentName.test.ts              # assertions
    ComponentName.test.svelte          # default fixture
    ComponentName.custom.test.svelte   # variant fixtures as needed

Mirror src/ component folders. Put complex setups in *.test.svelte, not inline in the .ts file.

Imports

In .test.svelte fixtures, import the component under test directly, not from the barrel:

<script lang="ts">
  import ComboBox from "carbon-components-svelte/ComboBox/ComboBox.svelte";
</script>

Avoid import { ComboBox } from "carbon-components-svelte" in fixtures. Direct paths skip transforming the entire src/index.js barrel and are faster under Vitest. The alias in vite.config.ts resolves carbon-components-svelte to src/.

In .test.ts files, import types from the direct path and render via the fixture:

import type ComboBoxComponent from "carbon-components-svelte/ComboBox/ComboBox.svelte";
import ComboBox from "./ComboBox.test.svelte";

Import shared utilities (for example exported helpers) from the component file or src/utils/ as appropriate.

Queries and interactions

  • Prefer accessible queries: getByRole, getByLabelText, getByText with exact: true when needed (ComboBox.test.ts).
  • Use data-testid in unit tests only when roles are insufficient. E2E fixtures use data-testid routinely.
  • Use the shared user helper from tests/utils/user.ts for clicks and keyboard input.
  • Type fixture props with ComponentProps<typeof Component> from svelte where helpful.

What to test

Prioritize high-value coverage:

  • Default render and primary user interactions (open, select, submit, keyboard)
  • Accessibility roles, labels, and ARIA state changes
  • Regressions for bugs you fix
  • Boundary inputs to pure utils: zero or negative sizes, empty collections, divide-by-zero, and out-of-range indices. Assert the defined fallback (clamp, empty, identity) rather than only that it doesn't throw.
  • Generic/type contracts when adding @template props (see below)

Skip or avoid:

  • Tests that mirror implementation details without asserting user-visible behavior
  • Redundant permutations of the same code path
  • Large fixture setups when a focused unit test on a util suffices

Add tests proportional to the change. Not every prop variant needs its own case.

Generics and type tests

Vitest exposes expectTypeOf globally (see tests/utils/setup-globals.ts). Use it in a describe("Generics", …) block to verify @template JSDoc flows through to consumer types. Pure type assertions do not require a runtime render.

Pattern from Button.test.ts and ComboBox.test.ts:

import type ComboBoxComponent from "carbon-components-svelte/ComboBox/ComboBox.svelte";
import type { ComponentProps } from "svelte";

describe("Generics", () => {
  it("should support custom item types with generics", () => {
    type Product = { id: string; text: string; price: number };

    type ComponentType = ComboBoxComponent<Product>;
    type Props = ComponentProps<ComponentType>;

    expectTypeOf<Props["items"]>().toEqualTypeOf<readonly Product[]>();

    const itemToString = (item: Product) => item.text;
    expectTypeOf(itemToString).parameter(0).toEqualTypeOf<Product>();
  });
});

Use ComponentProps and ComponentEvents from svelte for props and event payloads. For runtime smoke tests with custom item shapes, add a *Generics.test.svelte fixture (ComboBoxGenerics.test.svelte).

Common expectTypeOf matchers: .toEqualTypeOf, .toExtend, .parameter(n), .returns, .toHaveProperty.

Other patterns

  • beforeEach(() => vi.clearAllMocks()) when tests use spies.
  • Scope runs: bun run test ComboBox (see Checks).

Svelte 3 and Svelte 4 compatibility tests

The default bun run test harness uses Svelte 5. Separate workspaces under tests-svelte3/ and tests-svelte4/ run the same tests against older Svelte versions.

You only need these when fixing a failure reported from bun run test:svelte3, bun run test:svelte4, or their type-check scripts. Most changes do not require them.

Before running a compatibility script, install that workspace's dependencies. Without a local node_modules, the run may fall back to the Svelte 5 harness:

cd tests-svelte3 && bun install
cd ../tests-svelte4 && bun install

Then from the repo root:

bun run test:svelte3
bun run test:svelte4

E2E testing with Playwright

E2E tests run in a real browser against HTML fixtures served by Vite. The Playwright config is in playwright.config.ts; the Vite config for fixtures is in e2e/vite.config.ts.

Run the full suite:

bun run test:e2e

Run a focused component or pattern:

# Single test file
bunx playwright test e2e/breakpoint.test.ts

# Tests matching a grep pattern (for example "Breakpoint" or "sm breakpoint")
bunx playwright test --grep "Breakpoint"

How fixtures are served (local vs CI)

The fixtures are a Vite multi-page app, one .html entry per fixture. How they are served depends on the environment, controlled by the CI env var in playwright.config.ts:

  • Locally: Playwright starts the Vite dev server. It transforms modules on demand, so there is no build step and edits show up immediately.
  • In CI: Playwright runs vite build once and serves the static output with vite preview. Bundled assets load faster and with less run-to-run variance than the dev server, which transforms unbundled modules on demand through a single process that competes with the browser workers for CPU.

Neither path needs a manual build. To reproduce the CI build locally, for example to debug a build-only failure, build the fixtures once:

bunx vite build --config e2e/vite.config.ts

The output lands in e2e/fixtures/dist/ (gitignored). Serve it with bunx vite preview --config e2e/vite.config.ts, or run the whole CI path in one command:

CI=true bunx playwright test --project=chromium

To add a new E2E test, copy the Breakpoint example. Create these files:

File Purpose
e2e/fixtures/MyComponentFixture.svelte Svelte component that renders the component under test. Use data-testid on elements you want to query.
e2e/fixtures/my-component.ts Entry script that mounts the fixture into #app. Use the shared mount() utility from ./mount.
e2e/fixtures/my-component.html HTML page with <div id="app"></div> and a script tag loading the entry module.
e2e/my-component.test.ts Playwright tests. Use page.goto("/my-component.html") in beforeEach, then page.getByTestId(...) to assert.

Example fixture mount (my-component.ts):

import MyComponentFixture from "./MyComponentFixture.svelte";
import { mount } from "./mount";

mount(MyComponentFixture);

A few gotchas:

For components that hide content with CSS (for example ComposedModal), toBeVisible() can lie because the element stays in the DOM. Prefer toHaveClass(/is-visible/) on the container, or assert on aria-hidden / inert.

getByText("Row 1") also matches "Row 10", "Row 11", and so on. Use getByRole("cell", { name: "Row 1", exact: true }) or a more specific selector when content can overlap.

Add a link to e2e/fixtures/index.html so the fixture is reachable from the index page.

Commit messages

Use Conventional Commits:

<type>(<scope>): <subject>

[optional body]

Subject line:

  • Keep it concise: one line, imperative mood
  • Common types: fix, feat, docs, chore, test, refactor
  • Scope is the component or area; multi-word names are lowercase with dashes: combo-box, code-snippet, data-table, ui-shell, accordion-item
  • Omit scope when the change spans many areas (docs: …, chore: …)
  • Append ! after the scope for breaking changes: fix(accordion-item)!: …

Examples:

fix(combo-box): close dropdown on outside click
docs(tree-view): fix slottable inline editing example
chore(deps-dev): bump vitest, svelte-check

Body (optional):

A body is not required. Add one when context helps reviewers or when closing an issue.

  • Reference the issue: Fixes #1000 or Closes #1000 (GitHub auto-closes on merge)
  • At most 2-3 sentences, full sentences, no bullet lists
  • Wrap lines at 72 characters for readability in git log

Example with body:

fix(data-table): associate cells with column headers

Cells now set aria-labelledby to their column header id.
Fixes #3162

Avoid vague subjects (fix bug), PascalCase or camelCase scopes (fix(ComboBox):), and long subjects. Move detail to the body. Prefer Fixes #N in the body over PR numbers in the subject.

Submit a pull request

Follow Commit messages for each commit in your branch.

Sync your fork

Before you open a PR, sync your fork with upstream:

git fetch upstream
git checkout master
git merge upstream/master

Open a PR

Push your branch, then open a PR comparing <YOUR_USER_ID>/feature to origin/master.

Maintainer guide

The following applies only to project maintainers.

Release

This library publishes to NPM with provenance via a GitHub workflow.

Pushing a tag that starts with v (for example v0.81.1) triggers the workflow. It runs bun ci, bun build:docs, and bunx culls --preserve=svelte before publishing to NPM.

Maintainers still do a few things locally before tagging.

On a clean master branch, run bun run release. That will:

  • Bump the semantic version in package.json
  • Generate notes in CHANGELOG.md
  • Run bun run build:docs to update generated documentation

It does not commit or tag. Do that manually:

# 1. Commit the changes using the new version as the commit message.
git commit -am "v0.81.1"

# 2. Create a tag.
git tag v0.81.1

# 3. Push the tag to the remote.
# This triggers the `release.yml` workflow to publish a new package to NPM (with provenance).
git push origin v0.81.1

If the workflow succeeds, the release.yml workflow publishes the new version to NPM.

Post-release checklist

After the release is on NPM:

  1. Create a new release on GitHub. Click "Generate release notes" to list changes by commit with PR and author metadata. Drop notes that do not matter for the release (for example CI-only changes).

  2. Mark it as the latest release.

  3. On each related PR or issue, confirm the fix shipped. Future readers will want to know which version picked it up.

Released in [v0.81.1](https://github.com/carbon-design-system/carbon-components-svelte/releases/tag/v0.81.1).