Carbon v11 style integration (component checklist)

[theetrain]

📣 Status: implementing. Contributions are welcome! See #1872 for details and contribution guide.

This is a placeholder ticket to track the integration of Carbon v11 styles into carbon-components-svelte. Adopting Carbon v11 styles is our highest priority, but shipping components with <style lang="sass"> is currently problematic with Vite as discussed in #1561.

Prior research

I'm currently evaluating @sveltejs/package in the carbon-v11 branch in order to accomodate these aspirational goals:

• ✅ Write components using <script lang="ts"> to distribute as JS Svelte components and companion *.svelte.d.ts files for TypeScript users. See guide on adding types to components
  (works well!)
• ✅ Ensure Sveld can interpret typings to generate documentation
  (yes, but needs enhancements to read in types from svelte/elements)
• ✅ Import Carbon v11 SCSS directly via <style lang="sass">@use ...</style> and rely on @sveltejs/package to compile styles into scoped CSS
  (yes, SCSS builds as scoped CSS)
• ✅ Ensure there's a way to theme components via CSS variables once SCSS compiles to scoped CSS in each component
  (yes, compiled SCSS ships with CSS variables and default values)
• ✅ Test build performance on a plain SvelteKit app
  (it's good because components are precompiled)

If the above goals turn out to be favourable, we'll proceed to implement Carbon v11 styles into every component. Special thanks to @gregorw for early exploration in #1496.

Later, or out of scope:

• Provide general documentation for CSS variables for feature overrides
• Add <Stack /> (Stack component request #1384) to provide custom spacing or sectioning
• Split work into per-component tasks, tracked in this ticket. Open up for contributions

Checklist

• Accordion
• AccordionItem
• AccordionSkeleton
• AspectRatio
• Breadcrumb
• BreadcrumbItem
• BreadcrumbSkeleton
• Breakpoint
• Button v11 #1641
• ButtonSet
• ButtonSkeleton
• Checkbox
• CheckboxSkeleton
• ClickableTile
• CodeSnippet
• CodeSnippetSkeleton
• Column
• ComboBox v11 #1679
• ComposedModal
• Content
• ContentSwitcher
• ContextMenu
• ContextMenuDivider
• ContextMenuGroup
• ContextMenuOption
• ContextMenuRadioGroup
• CopyButton
• DataTable
• DataTableSkeleton
• DatePicker
• DatePickerInput
• DatePickerSkeleton
• Dropdown
• DropdownSkeleton
• ExpandableTile
• FileUploader
• FileUploaderButton
• FileUploaderDropContainer
• FileUploaderItem
• FileUploaderSkeleton
• Filename
• FluidForm
• Form
• FormGroup
• FormItem
• FormLabel
• Grid
• Header
• HeaderAction
• HeaderActionLink
• HeaderGlobalAction
• HeaderNav
• HeaderNavItem
• HeaderNavMenu
• HeaderPanelDivider
• HeaderPanelLink
• HeaderPanelLinks
• HeaderSearch
• HeaderUtilities
• ImageLoader
• InlineLoading
• InlineNotification
• Layer (new component) #1892
• Link
• ListBox
• ListBoxField
• ListBoxMenu
• ListBoxMenuIcon
• ListBoxMenuItem
• ListBoxSelection
• ListItem
• Loading
• LocalStorage
• Modal
• ModalBody
• ModalFooter
• ModalHeader
• MultiSelect
• NotificationActionButton
• NotificationButton
• NotificationIcon
• NumberInput
• NumberInputSkeleton
• OrderedList
• OutboundLink
• OverflowMenu
• OverflowMenuItem
• Pagination
• PaginationNav
• PaginationSkeleton
• PasswordInput v11 #1890
• Popover v11 #1896
• ProgressBar
• ProgressIndicator
• ProgressIndicatorSkeleton
• ProgressStep
• RadioButton
• RadioButtonGroup
• RadioButtonSkeleton
• RadioTile
• RecursiveList
• Row
• Search
• SearchSkeleton
• Select v11 #1675
• SelectItem
• SelectItemGroup
• SelectSkeleton
• SelectableTile
• SideNav
• SideNavDivider
• SideNavItems
• SideNavLink
• SideNavMenu
• SideNavMenuItem
• SkeletonPlaceholder
• SkeletonText
• SkipToContent
• Slider
• SliderSkeleton
• StructuredList
• StructuredListBody
• StructuredListCell
• StructuredListHead
• StructuredListInput
• StructuredListRow
• StructuredListSkeleton
• Switch
• Tab
• TabContent
• Table
• TableBody
• TableCell
• TableContainer
• TableHead
• TableHeader
• TableRow
• Tabs
• TabsSkeleton
• Tag
• TagSkeleton
• TextArea v11 #1668
• TextAreaSkeleton
• Disallow TextArea resize if cols is specified #1661
• TextInput v11 #1888
• TextInputSkeleton
• Theme v11 #1653
• Tile
• TileGroup
• TimePicker
• TimePickerSelect
• ToastNotification
• Toggle
• ToggleSkeleton
• Toolbar
• ToolbarBatchActions
• ToolbarContent
• ToolbarMenu
• ToolbarMenuItem
• ToolbarSearch
• Tooltip
• TooltipDefinition
• TooltipFooter
• TooltipIcon
• TreeView
• Truncate
• UnorderedList
• UIShell v11 #1674
• Change CSS prefix from bx to cds to match flagship

---

New components

• Grid (uses CSS Grid)
• FlexGrid (old grid)
• ContainedList
• Section
• Heading (designed to pair with section)
• MenuButton (mix of Button and OverflowMenu)
• ComboButton (similar to menu button, but the button has a dedicated action instead of just opening the dropdown)
• Stack
• Tag (more variants)
• Icon (for setting size)
• SkeletonIcon

[theetrain]

@metonym some good progress so far (see notes above).

Here's a TypeScript follow up to #1628 (comment)

import type { HTMLLabelAttributes } from "svelte/elements";

export let labelAttributes: HTMLLabelAttributes = {};

This will produce HTML types for the respective element. This will probably improve DX when adding props to components because you'll see the Carbon props as well as labelAttributes instead of carbon props mixed with every possible HTML attribute in alphabetical order. I updated #1621 with the proposed name convention.

We can add lang="ts" gradually as we refactor components since JSDoc compiles fine as is. One thing I'd like to change is place import statements before export statements to follow ESM conventions.

Try this locally:

• checkout the feat/carbon-v11 branch
• run yarn then yarn build:package
• Observe output in package/TextInput/TextInput.svelte.d.ts
• Observe built css in package/Button/Button.svelte

Once I'm finished evaluating and setting up the new project structure with svelte-package, I think we can keep feat/carbon-v11 as a long-running branch and adopt v11 styles one at a time, making pull requests targeting feat/carbon-v11. I can add a task list above to see who's working on which components.

Let me know if you have any feedback.

[metonym]

@theetrain proof-of-concept LGTM