diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index df91e1b9..8c7c5b52 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -1,37 +1,60 @@ on: pull_request: + paths-ignore: + - "**.md" + - "docs/**" + - "examples/**" push: branches: [master] + paths-ignore: + - "**.md" + - "docs/**" + - "examples/**" + +permissions: + contents: read jobs: - test: - runs-on: ubuntu-latest + lint: + runs-on: macos-15-xlarge steps: - uses: actions/checkout@v4 - - uses: actions/cache@v4 - id: npm-cache + - uses: actions/setup-node@v4 with: - path: "**/node_modules" - key: ${{ runner.os }}-modules-${{ hashFiles('**/package-lock.json') }} + node-version: "22.x" + cache: "npm" + - run: npm ci + - run: npm run lint - - name: Install dependencies - run: npm install + test: + runs-on: macos-15-xlarge + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "22.x" + cache: "npm" + - run: npm ci + - run: npm run test - - name: Run lint - run: npm run lint - - - name: Unit tests - run: npm run test - - - name: Test generated source types - run: npm run test:src-types - - - name: Test types - run: npm run test:types + types: + runs-on: macos-15-xlarge + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "22.x" + cache: "npm" + - run: npm ci + - run: npm run test:src-types + - run: npm run test:types + deploy-docs: + if: github.ref == 'refs/heads/master' + needs: [lint, test, types] + runs-on: macos-15-xlarge + steps: - name: Trigger deploy - if: github.ref == 'refs/heads/master' env: deploy_url: ${{ secrets.RENDER_DEPLOY_HOOK_URL }} - run: | - curl "$deploy_url" + run: curl -f "$deploy_url" diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index e57dc6ca..e85c95df 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -5,7 +5,7 @@ on: jobs: release: - runs-on: ubuntu-latest + runs-on: macos-latest-xlarge permissions: contents: read id-token: write @@ -13,7 +13,7 @@ jobs: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: - node-version: "20.x" + node-version: "22.x" registry-url: "https://registry.npmjs.org" - name: Install dependencies diff --git a/CHANGELOG.md b/CHANGELOG.md index de42a2b8..6adc2484 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,99 @@ All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines. +### [0.89.7](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.6...v0.89.7) (2025-09-05) + +### Bug Fixes + +- **combo-box:** address accessibility issues ([#2186](https://github.com/carbon-design-system/carbon-components-svelte/issues/2186)) ([2fc884c](https://github.com/carbon-design-system/carbon-components-svelte/commit/2fc884cacabfffcf7779d6ef9ba01dece0bf5d86)), closes [#2172](https://github.com/carbon-design-system/carbon-components-svelte/issues/2172) +- **data-table:** handle dynamic `headers` gracefully ([#2195](https://github.com/carbon-design-system/carbon-components-svelte/issues/2195)) ([6d0d3b1](https://github.com/carbon-design-system/carbon-components-svelte/commit/6d0d3b108bb4595d878fda20736c40b9656d14d7)), closes [#2193](https://github.com/carbon-design-system/carbon-components-svelte/issues/2193) +- **overflow-menu:** avoid dynamic style injection for performance ([#2198](https://github.com/carbon-design-system/carbon-components-svelte/issues/2198)) ([14edf41](https://github.com/carbon-design-system/carbon-components-svelte/commit/14edf41e57fea1ddbb2cf24c37e79475849bdea1)), closes [#2197](https://github.com/carbon-design-system/carbon-components-svelte/issues/2197) +- **pagination:** `on:change` dispatches with correct value ([#2194](https://github.com/carbon-design-system/carbon-components-svelte/issues/2194)) ([44a6cc0](https://github.com/carbon-design-system/carbon-components-svelte/commit/44a6cc0dfcbd3cdad1b442a760c9f604e58d56e6)) + +### [0.89.6](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.5...v0.89.6) (2025-08-16) + +### Bug Fixes + +- **toggle:** avoid dispatching `toggle` event on state change ([#2184](https://github.com/carbon-design-system/carbon-components-svelte/issues/2184)) ([0df727b](https://github.com/carbon-design-system/carbon-components-svelte/commit/0df727b704d6cc577681dc682269a6e224ddbb6e)) + +### [0.89.5](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.4...v0.89.5) (2025-08-05) + +### Bug Fixes + +- **checkbox:** prevent infinite effect loop when binding to same object ([#2178](https://github.com/carbon-design-system/carbon-components-svelte/issues/2178)) ([c7ad1eb](https://github.com/carbon-design-system/carbon-components-svelte/commit/c7ad1ebdd3764235f460abd95cdb7d1d389983d9)), closes [#2177](https://github.com/carbon-design-system/carbon-components-svelte/issues/2177) + +### [0.89.4](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.3...v0.89.4) (2025-06-10) + +### Bug Fixes + +- **multi-select:** forward `on:input` for filterable variant ([#2170](https://github.com/carbon-design-system/carbon-components-svelte/issues/2170)) ([aecc4e8](https://github.com/carbon-design-system/carbon-components-svelte/commit/aecc4e8eec6571515233ec76ca06218814a279a7)) + +### [0.89.3](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.2...v0.89.3) (2025-06-07) + +### Bug Fixes + +- **combo-box:** "Escape" key clears input value ([#2169](https://github.com/carbon-design-system/carbon-components-svelte/issues/2169)) ([632320a](https://github.com/carbon-design-system/carbon-components-svelte/commit/632320ae3b8d9c602add0f4f7c708fc643cb7ffc)), closes [#2167](https://github.com/carbon-design-system/carbon-components-svelte/issues/2167) +- **combo-box:** clear button supports "Space" key ([#2168](https://github.com/carbon-design-system/carbon-components-svelte/issues/2168)) ([95c06a8](https://github.com/carbon-design-system/carbon-components-svelte/commit/95c06a83b3afcbb76acfc0a5efe2f178d333ff19)), closes [#2166](https://github.com/carbon-design-system/carbon-components-svelte/issues/2166) + +### [0.89.2](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.1...v0.89.2) (2025-04-28) + +### Bug Fixes + +- **composed-modal:** ignore a11y warning in Svelte 5 ([#2159](https://github.com/carbon-design-system/carbon-components-svelte/issues/2159)) ([024d774](https://github.com/carbon-design-system/carbon-components-svelte/commit/024d77493c93e7823e4781a1a60aaf350d289d52)) +- **pagination:** use `toLocaleString` for default text formatting ([#2161](https://github.com/carbon-design-system/carbon-components-svelte/issues/2161)) ([cdf5659](https://github.com/carbon-design-system/carbon-components-svelte/commit/cdf5659fa0177da77dc8ea1ccffdec54b746954b)) +- **pagination:** window `totalItems` for performance ([#2160](https://github.com/carbon-design-system/carbon-components-svelte/issues/2160)) ([ed3928b](https://github.com/carbon-design-system/carbon-components-svelte/commit/ed3928bb01ecca2fa63f551938dbee1c1829a978)), closes [#2156](https://github.com/carbon-design-system/carbon-components-svelte/issues/2156) +- **to-hierarchy:** revert to previous implementation ([96d37cc](https://github.com/carbon-design-system/carbon-components-svelte/commit/96d37cc490f28830264c35c84447ee4526256314)) + +### [0.89.1](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.89.0...v0.89.1) (2025-04-21) + +### Bug Fixes + +- **toolbar-search:** re-filter rows if `DataTable` rows change ([#2154](https://github.com/carbon-design-system/carbon-components-svelte/issues/2154)) ([f09c2e2](https://github.com/carbon-design-system/carbon-components-svelte/commit/f09c2e2c311c15f633db8dc45930d8e58a4b362d)), closes [#2143](https://github.com/carbon-design-system/carbon-components-svelte/issues/2143) + +### [0.89.0](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.88.4...v0.89.0) (2025-04-18) + +### Features + +- **combo-box:** add `hideLabel` prop ([#2153](https://github.com/carbon-design-system/carbon-components-svelte/issues/2153)) ([436dea4](https://github.com/carbon-design-system/carbon-components-svelte/commit/436dea47e8da35753a257c9b2bd6f33338e95ba5)) + +### Bug Fixes + +- **select:** falsy item `text` should fallback to `value` ([#2152](https://github.com/carbon-design-system/carbon-components-svelte/issues/2152)) ([61ea8dd](https://github.com/carbon-design-system/carbon-components-svelte/commit/61ea8dd82c2f9863dfe5f8a882e73624b994d9e5)) + +### [0.88.4](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.88.3...v0.88.4) (2025-03-24) + +### Bug Fixes + +- **list-box-selection:** fix `aria-label` for clear button ([#2134](https://github.com/carbon-design-system/carbon-components-svelte/issues/2134)) ([dd1338f](https://github.com/carbon-design-system/carbon-components-svelte/commit/dd1338ffc47926a13e231d4a0f724e923f2219e2)) +- **list-box:** correct button/description translations based on selection count ([#2139](https://github.com/carbon-design-system/carbon-components-svelte/issues/2139)) ([1a5f2d8](https://github.com/carbon-design-system/carbon-components-svelte/commit/1a5f2d8e67734bfda20272ae6a77d13b3837416d)) +- **list-box:** set `aria-disabled` if `disabled` ([#2125](https://github.com/carbon-design-system/carbon-components-svelte/issues/2125)) ([#2138](https://github.com/carbon-design-system/carbon-components-svelte/issues/2138)) ([9b61af0](https://github.com/carbon-design-system/carbon-components-svelte/commit/9b61af0306b422acf1e7cdde278e517740f667c5)), closes [#2130](https://github.com/carbon-design-system/carbon-components-svelte/issues/2130) +- **radio-button:** forward `focus`, `blur` events ([#2135](https://github.com/carbon-design-system/carbon-components-svelte/issues/2135)) ([1462e30](https://github.com/carbon-design-system/carbon-components-svelte/commit/1462e300d69f0cd7ee5476dfe3a7ea892ac8f4ad)), closes [#2131](https://github.com/carbon-design-system/carbon-components-svelte/issues/2131) +- **radio-tile:** allow standalone `RadioTile` usage ([#2136](https://github.com/carbon-design-system/carbon-components-svelte/issues/2136)) ([ca9beeb](https://github.com/carbon-design-system/carbon-components-svelte/commit/ca9beebaeac7eaed8079c010a86a78926b00147f)) +- **text-area:** allow visually hidden label ([#2137](https://github.com/carbon-design-system/carbon-components-svelte/issues/2137)) ([43511e0](https://github.com/carbon-design-system/carbon-components-svelte/commit/43511e09ecf312c1b8e9339856b9d7d0785036de)) + +### [0.88.3](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.88.2...v0.88.3) (2025-03-19) + +### Bug Fixes + +- Revert **list-box:** use `aria-disabled` instead of invalid `disabled` attribute ([#2125](https://github.com/carbon-design-system/carbon-components-svelte/issues/2125)) ([e1b3ef2](https://github.com/carbon-design-system/carbon-components-svelte/commit/e1b3ef22c9ee09474bacadbb0b22b41326566bab)) + +### [0.88.2](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.88.1...v0.88.2) (2025-03-19) + +### Bug Fixes + +- **combo-box:** fix typing when refocusing input ([9e3d830](https://github.com/carbon-design-system/carbon-components-svelte/commit/9e3d83031e69889472c4e84be256ea242854cf81)) +- **list-box:** use `aria-disabled` instead of invalid `disabled` attribute ([#2125](https://github.com/carbon-design-system/carbon-components-svelte/issues/2125)) ([e1b3ef2](https://github.com/carbon-design-system/carbon-components-svelte/commit/e1b3ef22c9ee09474bacadbb0b22b41326566bab)) +- **multi-select:** fix keyboard navigation for disabled items ([#2129](https://github.com/carbon-design-system/carbon-components-svelte/issues/2129)) ([e7939ff](https://github.com/carbon-design-system/carbon-components-svelte/commit/e7939ff0e21c3430c9eea74c503b7c35f6823445)), closes [#2128](https://github.com/carbon-design-system/carbon-components-svelte/issues/2128) +- **notification:** remove invalid `kind` prop from markup ([#2126](https://github.com/carbon-design-system/carbon-components-svelte/issues/2126)) ([e85d7ef](https://github.com/carbon-design-system/carbon-components-svelte/commit/e85d7efc5ed15f5236d074fd7981ae527d9e5ab5)) +- **theme:** remove invalid `themes` prop from markup ([#2127](https://github.com/carbon-design-system/carbon-components-svelte/issues/2127)) ([5987b61](https://github.com/carbon-design-system/carbon-components-svelte/commit/5987b61a5522fff09468bddd586eed4a537edcc8)) + +### [0.88.1](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.88.0...v0.88.1) (2025-03-12) + +### Bug Fixes + +- **select:** falsy item `text` should not override `value` ([#2118](https://github.com/carbon-design-system/carbon-components-svelte/issues/2118)) ([663b79a](https://github.com/carbon-design-system/carbon-components-svelte/commit/663b79ad054d14a91a8bf700feb62dcf50976eb8)), closes [#2117](https://github.com/carbon-design-system/carbon-components-svelte/issues/2117) +- **ui-shell:** `HeaderAction` uses dark color scheme ([#2119](https://github.com/carbon-design-system/carbon-components-svelte/issues/2119)) ([7ff93ad](https://github.com/carbon-design-system/carbon-components-svelte/commit/7ff93ad2dac489859d5b4a83c1e359a6507718b4)) + ### [0.88.0](https://github.com/carbon-design-system/carbon-components-svelte/compare/v0.87.7...v0.88.0) (2025-03-09) ### Features diff --git a/COMPONENT_INDEX.md b/COMPONENT_INDEX.md index f67f99d3..b1f4eb48 100644 --- a/COMPONENT_INDEX.md +++ b/COMPONENT_INDEX.md @@ -1,6 +1,6 @@ # Component Index -> 165 components exported from carbon-components-svelte@0.87.8. +> 165 components exported from carbon-components-svelte@0.89.7. ## Components @@ -671,6 +671,7 @@ export interface ComboBoxItem { | size | No | let | No | "sm" | "xl" | undefined | Set the size of the combobox | | disabled | No | let | No | boolean | false | Set to `true` to disable the combobox | | titleText | No | let | No | string | "" | Specify the title text of the combobox | +| hideLabel | No | let | No | boolean | false | Set to `true` to visually hide the label text | | placeholder | No | let | No | string | "" | Specify the placeholder text | | helperText | No | let | No | string | "" | Specify the helper text | | invalidText | No | let | No | string | "" | Specify the invalid state text | @@ -2418,6 +2419,7 @@ export interface MultiSelectItem { | clear | dispatched | null | | blur | dispatched | FocusEvent | CustomEvent | | keydown | forwarded | -- | +| input | forwarded | -- | | keyup | forwarded | -- | | focus | forwarded | -- | | paste | forwarded | -- | @@ -2680,24 +2682,25 @@ None. ### Props -| Prop name | Required | Kind | Reactive | Type | Default value | Description | -| :-------------------- | :------- | :--------------- | :------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------ | -| pageSize | No | let | Yes | number | 10 | Specify the number of items to display in a page | -| page | No | let | Yes | number | 1 | Specify the current page index | -| totalItems | No | let | No | number | 0 | Specify the total number of items | -| disabled | No | let | No | boolean | false | Set to `true` to disable the pagination | -| forwardText | No | let | No | string | "Next page" | Specify the forward button text | -| backwardText | No | let | No | string | "Previous page" | Specify the backward button text | -| itemsPerPageText | No | let | No | string | "Items per page:" | Specify the items per page text | -| itemText | No | let | No | (min: number, max: number) => string | (min, max) => \`${min}–${max} item${max === 1 ? "" : "s"}\` | Override the item text | -| itemRangeText | No | let | No | (min: number, max: number, total: number) => string | (min, max, total) => \`${min}–${max} of ${total} item${max === 1 ? "" : "s"}\` | Override the item range text | -| pageInputDisabled | No | let | No | boolean | false | Set to `true` to disable the page input | -| pageSizeInputDisabled | No | let | No | boolean | false | Set to `true` to disable the page size input | -| pageSizes | No | let | No | ReadonlyArray | [10] | Specify the available page sizes | -| pagesUnknown | No | let | No | boolean | false | Set to `true` if the number of pages is unknown | -| pageText | No | let | No | (page: number) => string | (page) => \`page ${page}\` | Override the page text | -| pageRangeText | No | let | No | (current: number, total: number) => string | (current, total) => \`of ${total} page${total === 1 ? "" : "s"}\` | Override the page range text | -| id | No | let | No | string | "ccs-" + Math.random().toString(36) | Set an id for the top-level element | +| Prop name | Required | Kind | Reactive | Type | Default value | Description | +| :-------------------- | :------- | :--------------- | :------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| pageSize | No | let | Yes | number | 10 | Specify the number of items to display in a page | +| page | No | let | Yes | number | 1 | Specify the current page index | +| totalItems | No | let | No | number | 0 | Specify the total number of items | +| pageWindow | No | let | No | number | 1000 | If `totalItems` is a large number, it can affect the
rendering performance of this component since its value
is used to calculate the number of pages in the native
select dropdown. This value creates a small window of
pages rendered around the current page. By default,
a maximum of 1000 select items are rendered. | +| disabled | No | let | No | boolean | false | Set to `true` to disable the pagination | +| forwardText | No | let | No | string | "Next page" | Specify the forward button text | +| backwardText | No | let | No | string | "Previous page" | Specify the backward button text | +| itemsPerPageText | No | let | No | string | "Items per page:" | Specify the items per page text | +| itemText | No | let | No | (min: number, max: number) => string | (min, max) => \`${min.toLocaleString()}–${max.toLocaleString()} item${max === 1 ? "" : "s"}\` | Override the item text | +| itemRangeText | No | let | No | (min: number, max: number, total: number) => string | (min, max, total) => \`${min.toLocaleString()}–${max.toLocaleString()} of ${total.toLocaleString()} item${max === 1 ? "" : "s"}\` | Override the item range text | +| pageInputDisabled | No | let | No | boolean | false | Set to `true` to disable the page input | +| pageSizeInputDisabled | No | let | No | boolean | false | Set to `true` to disable the page size input | +| pageSizes | No | let | No | ReadonlyArray | [10] | Specify the available page sizes | +| pagesUnknown | No | let | No | boolean | false | Set to `true` if the number of pages is unknown | +| pageText | No | let | No | (page: number) => string | (page) => \`page ${page.toLocaleString()}\` | Override the page text | +| pageRangeText | No | let | No | (current: number, total: number) => string | (current, total) => \`of ${total.toLocaleString()} page${total === 1 ? "" : "s"}\` | Override the page range text | +| id | No | let | No | string | "ccs-" + Math.random().toString(36) | Set an id for the top-level element | ### Slots @@ -2966,6 +2969,8 @@ None. | Event name | Type | Detail | | :--------- | :-------- | :----- | +| focus | forwarded | -- | +| blur | forwarded | -- | | change | forwarded | -- | ## `RadioButtonGroup` @@ -3218,14 +3223,14 @@ None. ### Props -| Prop name | Required | Kind | Reactive | Type | Default value | Description | -| :-------- | :------- | :--------------- | :------- | --------------------------------- | ---------------------- | ----------------------------------------- | -| value | No | let | No | string | number | "" | Specify the option value | -| text | No | let | No | string | "" | Specify the option text | -| hidden | No | let | No | boolean | false | Set to `true` to hide the option | -| disabled | No | let | No | boolean | false | Set to `true` to disable the option | -| class | No | let | No | string | undefined | Specify the class of the `option` element | -| style | No | let | No | string | undefined | Specify the style of the `option` element | +| Prop name | Required | Kind | Reactive | Type | Default value | Description | +| :-------- | :------- | :--------------- | :------- | --------------------------------- | ---------------------- | ---------------------------------------------------------------------------------- | +| value | No | let | No | string | number | "" | Specify the option value | +| text | No | let | No | string | undefined | Specify the option text
If not specified, the value will be used as the text. | +| hidden | No | let | No | boolean | false | Set to `true` to hide the option | +| disabled | No | let | No | boolean | false | Set to `true` to disable the option | +| class | No | let | No | string | undefined | Specify the class of the `option` element | +| style | No | let | No | string | undefined | Specify the style of the `option` element | ### Slots diff --git a/README.md b/README.md index d79f656e..9433ba03 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ Design systems facilitate design and development through reuse, consistency, and The Carbon Svelte portfolio also includes: -- **[Carbon Icons Svelte](https://github.com/carbon-design-system/carbon-icons-svelte)**: 2,400+ Carbon icons as Svelte components -- **[Carbon Pictograms Svelte](https://github.com/carbon-design-system/carbon-pictograms-svelte)**: 1,200+ Carbon pictograms as Svelte components +- **[Carbon Icons Svelte](https://github.com/carbon-design-system/carbon-icons-svelte)**: 2,500+ Carbon icons as Svelte components +- **[Carbon Pictograms Svelte](https://github.com/carbon-design-system/carbon-pictograms-svelte)**: 1,300+ 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 diff --git a/bun.lockb b/bun.lockb deleted file mode 100755 index 1f96ec1f..00000000 Binary files a/bun.lockb and /dev/null differ diff --git a/docs/package-lock.json b/docs/package-lock.json index b418ab97..343f034b 100644 --- a/docs/package-lock.json +++ b/docs/package-lock.json @@ -17,14 +17,15 @@ "prettier": "^2.8.8", "prettier-plugin-svelte": "^2.10.1", "prism-svelte": "^0.5.0", - "prismjs": "^1.29.0", + "prismjs": "^1.30.0", "remark-slug": "^6.1.0", "svelte": "^4.2.19", - "vite": "^5.4.14" + "vite": "^5.4.19" } }, "..": { - "version": "0.87.7", + "name": "carbon-components-svelte", + "version": "0.89.4", "dev": true, "hasInstallScript": true, "license": "Apache-2.0", @@ -35,25 +36,25 @@ "devDependencies": { "@sveltejs/vite-plugin-svelte": "^3.1.2", "@testing-library/jest-dom": "^6.6.3", - "@testing-library/svelte": "^5.2.7", + "@testing-library/svelte": "^5.2.8", "@testing-library/user-event": "^14.6.1", - "autoprefixer": "^10.4.8", + "autoprefixer": "^10.4.21", "carbon-components": "10.58.12", - "carbon-icons-svelte": "^13.3.0", + "carbon-icons-svelte": "^13.4.0", "carbon-preprocess-svelte": "^0.11.11", "culls": "^0.1.1", - "jsdom": "^26.0.0", - "postcss": "^8.5.3", + "jsdom": "^26.1.0", + "postcss": "^8.5.5", "prettier": "^3.5.3", - "prettier-plugin-svelte": "^3.3.3", + "prettier-plugin-svelte": "^3.4.0", "sass": "^1.49.11", "standard-version": "^9.5.0", "sveld": "^0.22.1", - "svelte": "^4.2.19", - "svelte-check": "^4.1.5", - "tinyglobby": "^0.2.12", - "typescript": "^5.8.2", - "vitest": "^3.0.8" + "svelte": "^4.2.20", + "svelte-check": "^4.2.1", + "tinyglobby": "^0.2.14", + "typescript": "^5.8.3", + "vitest": "^3.2.3" } }, "node_modules/@ampproject/remapping": { @@ -1034,6 +1035,20 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, "node_modules/carbon-components-svelte": { "resolved": "..", "link": true @@ -1396,6 +1411,21 @@ "node": ">=10" } }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "dev": true, + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, "node_modules/error-ex": { "version": "1.3.2", "resolved": "https://registry.npmjs.org/error-ex/-/error-ex-1.3.2.tgz", @@ -1466,13 +1496,11 @@ } }, "node_modules/es-define-property": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.0.tgz", - "integrity": "sha512-jxayLKShrEqqzJ0eumQbVhTYQM27CfT1T35+gCgDFoL82JLsXqTJ76zv6A0YLOgEnLUMvLzsDsGIrl8NFpT2gQ==", + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", "dev": true, - "dependencies": { - "get-intrinsic": "^1.2.4" - }, + "license": "MIT", "engines": { "node": ">= 0.4" } @@ -1487,10 +1515,11 @@ } }, "node_modules/es-object-atoms": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.0.0.tgz", - "integrity": "sha512-MZ4iQ6JwHOBQjahnjwaC1ZtIBH+2ohjamzAO3oaHcXYup7qxjF2fixyH+Q71voWHeOkI2q/TnJao/KfXYIZWbw==", + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz", + "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==", "dev": true, + "license": "MIT", "dependencies": { "es-errors": "^1.3.0" }, @@ -1499,14 +1528,16 @@ } }, "node_modules/es-set-tostringtag": { - "version": "2.0.3", - "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.0.3.tgz", - "integrity": "sha512-3T8uNMC3OQTHkFUsFq8r/BwAXLHvU/9O9mE0fBc/MY5iq/8H7ncvO947LmYA6ldWw9Uh8Yhf25zu6n7nML5QWQ==", + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz", + "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==", "dev": true, + "license": "MIT", "dependencies": { - "get-intrinsic": "^1.2.4", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.6", "has-tostringtag": "^1.0.2", - "hasown": "^2.0.1" + "hasown": "^2.0.2" }, "engines": { "node": ">= 0.4" @@ -1653,14 +1684,17 @@ } }, "node_modules/form-data": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/form-data/-/form-data-3.0.2.tgz", - "integrity": "sha512-sJe+TQb2vIaIyO783qN6BlMYWMw3WBOHA1Ay2qxsnjuafEOQFJ2JakedOQirT6D5XPRxDvS7AHYyem9fTpb4LQ==", + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-3.0.4.tgz", + "integrity": "sha512-f0cRzm6dkyVYV3nPoooP8XlccPQukegwhAnpoLcXy+X+A8KfpGOoXwDr9FLZd3wzgLaBGQBE3lY93Zm/i1JvIQ==", "dev": true, + "license": "MIT", "dependencies": { "asynckit": "^0.4.0", "combined-stream": "^1.0.8", - "mime-types": "^2.1.12" + "es-set-tostringtag": "^2.1.0", + "hasown": "^2.0.2", + "mime-types": "^2.1.35" }, "engines": { "node": ">= 6" @@ -1732,16 +1766,22 @@ } }, "node_modules/get-intrinsic": { - "version": "1.2.4", - "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.2.4.tgz", - "integrity": "sha512-5uYhsJH8VJBTv7oslg4BznJYhDoRI6waYCxMmCdnTrcCrHA/fCFKoTFz2JKKE0HdDFUF7/oQuhzumXJK7paBRQ==", + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", "dev": true, + "license": "MIT", "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", "function-bind": "^1.1.2", - "has-proto": "^1.0.1", - "has-symbols": "^1.0.3", - "hasown": "^2.0.0" + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" }, "engines": { "node": ">= 0.4" @@ -1750,6 +1790,20 @@ "url": "https://github.com/sponsors/ljharb" } }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "dev": true, + "license": "MIT", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, "node_modules/get-symbol-description": { "version": "1.0.2", "resolved": "https://registry.npmjs.org/get-symbol-description/-/get-symbol-description-1.0.2.tgz", @@ -1790,12 +1844,13 @@ } }, "node_modules/gopd": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.0.1.tgz", - "integrity": "sha512-d65bNlIadxvpb/A2abVdlqKqV563juRnZ1Wtk6s1sIR8uNsXR70xqIzVqxVf1eTqDunwT2MkczEeaezCKTZhwA==", + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", "dev": true, - "dependencies": { - "get-intrinsic": "^1.1.3" + "license": "MIT", + "engines": { + "node": ">= 0.4" }, "funding": { "url": "https://github.com/sponsors/ljharb" @@ -1850,10 +1905,11 @@ } }, "node_modules/has-symbols": { - "version": "1.0.3", - "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.0.3.tgz", - "integrity": "sha512-l3LCuF6MgDNwTDKkdYGEihYjt5pRPbEg46rtlmnSPlUbgmB8LOIrKJbYYFBSbnPaJexMKtiPO8hmeRjRz2Td+A==", + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", "dev": true, + "license": "MIT", "engines": { "node": ">= 0.4" }, @@ -2416,6 +2472,16 @@ "@jridgewell/sourcemap-codec": "^1.5.0" } }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, "node_modules/mdast-util-to-string": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-1.1.0.tgz", @@ -2960,10 +3026,11 @@ "dev": true }, "node_modules/prismjs": { - "version": "1.29.0", - "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.29.0.tgz", - "integrity": "sha512-Kx/1w86q/epKcmte75LNrEoT+lX8pBpavuAbvJWRXar7Hz8jrtF+e3vY751p0R8H9HdArwaCTNDDzHg/ScJK1Q==", + "version": "1.30.0", + "resolved": "https://registry.npmjs.org/prismjs/-/prismjs-1.30.0.tgz", + "integrity": "sha512-DEvV2ZF2r2/63V+tK8hQvrR2ZGn10srHbXviTlcv7Kpzw8jWiNTqbVgjO3IY8RxrrOUF8VPMQQFysYYYv0YZxw==", "dev": true, + "license": "MIT", "engines": { "node": ">=6" } @@ -3707,9 +3774,9 @@ } }, "node_modules/vite": { - "version": "5.4.14", - "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.14.tgz", - "integrity": "sha512-EK5cY7Q1D8JNhSaPKVK4pwBFvaTmZxEnoKXLG/U9gmdDcihQGNzFlgIvaxezFR4glP1LsuiedwMBqCXH3wZccA==", + "version": "5.4.19", + "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.19.tgz", + "integrity": "sha512-qO3aKv3HoQC8QKiNSTuUM1l9o/XX3+c+VTgLHbJWHZGeTPVAg2XwazI9UWzoxjIJCGCV2zU60uqMzjeLZuULqA==", "dev": true, "license": "MIT", "dependencies": { diff --git a/docs/package.json b/docs/package.json index 75298254..4f543e57 100644 --- a/docs/package.json +++ b/docs/package.json @@ -22,10 +22,10 @@ "prettier": "^2.8.8", "prettier-plugin-svelte": "^2.10.1", "prism-svelte": "^0.5.0", - "prismjs": "^1.29.0", + "prismjs": "^1.30.0", "remark-slug": "^6.1.0", "svelte": "^4.2.19", - "vite": "^5.4.14" + "vite": "^5.4.19" }, "routify": { "routifyDir": ".routify", diff --git a/docs/src/COMPONENT_API.json b/docs/src/COMPONENT_API.json index d1115787..a31f311f 100644 --- a/docs/src/COMPONENT_API.json +++ b/docs/src/COMPONENT_API.json @@ -1851,6 +1851,18 @@ "constant": false, "reactive": false }, + { + "name": "hideLabel", + "kind": "let", + "description": "Set to `true` to visually hide the label text", + "type": "boolean", + "value": "false", + "isFunction": false, + "isFunctionDeclaration": false, + "isRequired": false, + "constant": false, + "reactive": false + }, { "name": "placeholder", "kind": "let", @@ -8931,6 +8943,11 @@ "name": "keydown", "element": "input" }, + { + "type": "forwarded", + "name": "input", + "element": "input" + }, { "type": "forwarded", "name": "keyup", @@ -10036,6 +10053,18 @@ "constant": false, "reactive": false }, + { + "name": "pageWindow", + "kind": "let", + "description": "If `totalItems` is a large number, it can affect the\nrendering performance of this component since its value\nis used to calculate the number of pages in the native\nselect dropdown. This value creates a small window of\npages rendered around the current page. By default,\na maximum of 1000 select items are rendered.", + "type": "number", + "value": "1000", + "isFunction": false, + "isFunctionDeclaration": false, + "isRequired": false, + "constant": false, + "reactive": false + }, { "name": "disabled", "kind": "let", @@ -10089,7 +10118,7 @@ "kind": "let", "description": "Override the item text", "type": "(min: number, max: number) => string", - "value": "(min, max) =>\n `${min}–${max} item${max === 1 ? \"\" : \"s\"}`", + "value": "(min, max) =>\n `${min.toLocaleString()}–${max.toLocaleString()} item${max === 1 ? \"\" : \"s\"}`", "isFunction": true, "isFunctionDeclaration": false, "isRequired": false, @@ -10101,7 +10130,7 @@ "kind": "let", "description": "Override the item range text", "type": "(min: number, max: number, total: number) => string", - "value": "(\n min,\n max,\n total,\n) =>\n `${min}–${max} of ${total} item${max === 1 ? \"\" : \"s\"}`", + "value": "(\n min,\n max,\n total,\n) =>\n `${min.toLocaleString()}–${max.toLocaleString()} of ${total.toLocaleString()} item${max === 1 ? \"\" : \"s\"}`", "isFunction": true, "isFunctionDeclaration": false, "isRequired": false, @@ -10173,7 +10202,7 @@ "kind": "let", "description": "Override the page text", "type": "(page: number) => string", - "value": "(page) => `page ${page}`", + "value": "(page) => `page ${page.toLocaleString()}`", "isFunction": true, "isFunctionDeclaration": false, "isRequired": false, @@ -10185,7 +10214,7 @@ "kind": "let", "description": "Override the page range text", "type": "(current: number, total: number) => string", - "value": "(\n current,\n total,\n) =>\n `of ${total} page${total === 1 ? \"\" : \"s\"}`", + "value": "(\n current,\n total,\n) =>\n `of ${total.toLocaleString()} page${total === 1 ? \"\" : \"s\"}`", "isFunction": true, "isFunctionDeclaration": false, "isRequired": false, @@ -11389,6 +11418,16 @@ } ], "events": [ + { + "type": "forwarded", + "name": "focus", + "element": "input" + }, + { + "type": "forwarded", + "name": "blur", + "element": "input" + }, { "type": "forwarded", "name": "change", @@ -12509,9 +12548,8 @@ { "name": "text", "kind": "let", - "description": "Specify the option text", + "description": "Specify the option text\nIf not specified, the value will be used as the text.", "type": "string", - "value": "\"\"", "isFunction": false, "isFunctionDeclaration": false, "isRequired": false, diff --git a/docs/src/global.css b/docs/src/global.css index 889d6229..165b2855 100644 --- a/docs/src/global.css +++ b/docs/src/global.css @@ -2,12 +2,19 @@ html[theme="g90"] .code-override { border: 1px solid var(--cds-ui-03); } +.prose > pre, .code-override .bx--snippet { /** Docs code snippet is always dark mode */ color-scheme: dark; max-width: none; } +.prose > pre { + padding: 1rem; + margin-bottom: 1rem; +} + +.prose > pre, .code-override .bx--copy-btn, .code-override .bx--snippet, .code-override button.bx--btn.bx--snippet-btn--expand { @@ -24,6 +31,7 @@ html[theme="g90"] .code-override { fill: #f4f4f4; } +.prose > pre, .code-override .bx--snippet-container pre { font-size: var(--cds-code-02-font-size); line-height: var(--cds-code-02-line-height); diff --git a/docs/src/pages/components/Accordion.svx b/docs/src/pages/components/Accordion.svx index 183b4cbb..a42735db 100644 --- a/docs/src/pages/components/Accordion.svx +++ b/docs/src/pages/components/Accordion.svx @@ -10,8 +10,15 @@ components: ["Accordion", "AccordionItem", "AccordionSkeleton"] import Preview from "../../components/Preview.svelte"; +`Accordion` creates a vertically stacked list of expandable sections that show or hide content. It supports custom titles, different sizes, and various states including disabled and skeleton loading. + ## Default +Use the `Accordion` and `AccordionItem` components to compose a collapsible list of +items. + +By default, the chevron icon is on the right side of the accordion item. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -27,6 +34,10 @@ components: ["Accordion", "AccordionItem", "AccordionSkeleton"] ## Left-aligned chevron +The chevron icon can be aligned to the left side of the accordion item by setting +the `align` prop to "start". This provides an alternative visual style while +maintaining the same functionality. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -42,6 +53,9 @@ components: ["Accordion", "AccordionItem", "AccordionSkeleton"] ## Custom title slot +Customize the title content by using the `title` slot instead of the `title` prop. +This allows for more complex title layouts with multiple elements. + @@ -69,6 +83,9 @@ components: ["Accordion", "AccordionItem", "AccordionSkeleton"] ## First item open +Set the `open` prop on an `AccordionItem` to have it expanded by default when the +accordion is first rendered. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -84,12 +101,18 @@ components: ["Accordion", "AccordionItem", "AccordionSkeleton"] ## Programmatic example -This example demonstrates how a list of items can be programmatically expanded and collapsed. +This example demonstrates how to programmatically control the accordion items using +the `bind:open` directive. Expand and collapse items based on user +interactions or application state. ## Extra-large size +The accordion can be displayed in an extra-large size by setting the `size` prop to +"xl". This provides more visual emphasis and is suitable for prominent content +sections. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -105,6 +128,10 @@ This example demonstrates how a list of items can be programmatically expanded a ## Small size +For more compact layouts, set the `size` prop to "sm" to display the accordion in a +smaller size. This is useful when space is limited or when the accordion is used as +a secondary UI element. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -120,6 +147,9 @@ This example demonstrates how a list of items can be programmatically expanded a ## Disabled +Set the `disabled` prop on the `Accordion` component to disable all items at once. +This prevents users from expanding or collapsing any items in the accordion. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -135,6 +165,10 @@ This example demonstrates how a list of items can be programmatically expanded a ## Disabled (item) +Individual accordion items can be disabled by setting the `disabled` prop on +specific `AccordionItem` components. This allows for more granular control over +which items are interactive. +

Natural Language Classifier uses advanced natural language processing and machine learning techniques to create custom classification models. Users train their data and the service predicts the appropriate category for the inputted text. @@ -150,25 +184,45 @@ This example demonstrates how a list of items can be programmatically expanded a ## Skeleton +The skeleton state provides a loading placeholder for the accordion. It displays a +simplified version of the component while content is being loaded. + ## Skeleton (left-aligned chevron) +The skeleton state can be combined with the left-aligned chevron style by setting +both the `skeleton` and `align="start"` props. + ## Skeleton (custom count) +By default, the skeleton state displays 4 items. + +Specify the number of skeleton items to display using the `count` prop. This is +useful when you know the exact number of items that will be loaded. + ## Skeleton (closed) +By default, the first skeleton item is open. The skeleton state can be displayed +in a collapsed state by setting `open={false}`. + ## Skeleton (extra-large) +The skeleton state supports the extra-large size variant, maintaining visual +consistency with the active component states. + ## Skeleton (small) +The skeleton state also supports the small size variant, providing a compact +loading placeholder for space-constrained layouts. + diff --git a/docs/src/pages/components/AspectRatio.svx b/docs/src/pages/components/AspectRatio.svx index 6de7aafa..0793fca9 100644 --- a/docs/src/pages/components/AspectRatio.svx +++ b/docs/src/pages/components/AspectRatio.svx @@ -3,11 +3,13 @@ import Preview from "../../components/Preview.svelte"; -The `AspectRatio` component is useful for constraining fluid content within an aspect ratio. To demo this, resize your browser for the examples below. +The `AspectRatio` component maintains consistent proportions for content across different screen sizes. It's particularly useful for images, videos, and other media that need to preserve their aspect ratio when resizing. Supported aspect ratios include `"2x1"`, `"2x3"`, `"16x9"`, `"4x3"`, `"1x1"`, `"3x4"`, `"3x2"`, `"9x16"` and `"1x2"`. -## Default (2x1) +## Default + +Display a 2:1 aspect ratio container by default. 2x1 diff --git a/docs/src/pages/components/Breadcrumb.svx b/docs/src/pages/components/Breadcrumb.svx index 75a01c5a..f491e5e0 100644 --- a/docs/src/pages/components/Breadcrumb.svx +++ b/docs/src/pages/components/Breadcrumb.svx @@ -12,8 +12,12 @@ components: ["Breadcrumb", "BreadcrumbItem"] import Preview from "../../components/Preview.svelte"; +`Breadcrumb` displays a hierarchical navigation trail that shows users their current location within an application. It supports current page indication, trailing slash customization, and overflow handling for long navigation paths. + ## Default +Display a hierarchical navigation trail with slashes between items. Mark the current page with `isCurrentPage`. + Dashboard Annual reports @@ -22,6 +26,8 @@ components: ["Breadcrumb", "BreadcrumbItem"] ## No trailing slash +Remove the trailing slash from the last breadcrumb item using `noTrailingSlash`. + Home Profile @@ -29,6 +35,8 @@ components: ["Breadcrumb", "BreadcrumbItem"] ## Overflow menu +Add an `OverflowMenu` to handle long breadcrumb trails. Use `OverflowMenuItem` components for menu options. + Home API documentation @@ -47,4 +55,6 @@ components: ["Breadcrumb", "BreadcrumbItem"] ## Skeleton +Display a loading state with `skeleton` prop. Use `count` to specify the number of items. + \ No newline at end of file diff --git a/docs/src/pages/components/Breakpoint.svx b/docs/src/pages/components/Breakpoint.svx index 134d7a76..c4245ae1 100644 --- a/docs/src/pages/components/Breakpoint.svx +++ b/docs/src/pages/components/Breakpoint.svx @@ -1,12 +1,12 @@ -The [Carbon Design System grid implementation](https://carbondesignsystem.com/guidelines/2x-grid/implementation#responsive-options) defines five responsive breakpoints: +The Carbon Design System [grid implementation](https://carbondesignsystem.com/guidelines/2x-grid/implementation#responsive-options) defines five responsive breakpoints: Small: less than 672px @@ -28,8 +28,8 @@ The `"on:change"` event will fire when the size is initially determined and when ## Store and Breakpoint Values -As an alternative to the component, `breakpointObserver` can be used to get the current size as a Svelte store. The store has two additional functions which create derived stores that return a `boolean` indicating whether the size is smaller/larger than a certain breakpoint. +Use `breakpointObserver` as an alternative to the component to get the current size as a Svelte store. The store provides two additional functions that create derived stores returning a `boolean` indicating whether the size is smaller/larger than a certain breakpoint. -There also exists a `breakpoints` dictionary mapping from `BreakpointSize` to `BreakpointValue`. +Access the `breakpoints` dictionary to map from `BreakpointSize` to `BreakpointValue`. diff --git a/docs/src/pages/components/Button.svx b/docs/src/pages/components/Button.svx index 953d1e0c..f0c7de69 100644 --- a/docs/src/pages/components/Button.svx +++ b/docs/src/pages/components/Button.svx @@ -4,57 +4,73 @@ import TrashCan from "carbon-icons-svelte/lib/TrashCan.svelte"; import Login from "carbon-icons-svelte/lib/Login.svelte"; import Preview from "../../components/Preview.svelte"; - - let index = 1; +Buttons trigger actions in the interface. Use them to submit forms, navigate between pages, or perform specific tasks. Choose from different styles and sizes to match the importance and context of each action. + ## Primary button +The default button style is primary. This should be used for primary actions. + ## Secondary button +Set `kind="secondary"` for secondary actions. + ## Tertiary button +Set `kind="tertiary"` for tertiary actions. + ## Ghost button +Set `kind="ghost"` for ghost-style buttons. + ## Danger button +Set `kind="danger"` for destructive actions. + ## Danger tertiary button +Set `kind="danger-tertiary"` for less prominent destructive actions. + ## Danger tertiary, icon-only button

- You must provide an iconDescription for the button tooltip. + Provide an iconDescription for accessibility. This text will be used as the button's tooltip and screen reader label.
- ## Button with icon +Add an icon to the button using the `icon` prop. + ## Icon-only button
- You must provide an iconDescription for the button tooltip. + Provide an iconDescription for accessibility. This text will be used as the button's tooltip and screen reader label.
@@ -62,11 +78,13 @@ ## Icon-only, link button +Set `href` to create an icon-only link button. + ## Link button with icon +Similarly, link buttons can have icons. + ## Custom element By default, the `Button` will render either a `button` or `a` element. -If you need to render a different element, set `as` to `true` and spread `let:props` to the element. +To render a different element, set `as` to `true` and spread `let:props` to the element. @@ -106,6 +130,8 @@ If you need to render a different element, set `as` to `true` and spread `let:pr ## Small size +Set `size="small"` for small buttons. + @@ -114,6 +140,8 @@ If you need to render a different element, set `as` to `true` and spread `let:pr ## Large size +Set `size="lg"` for large buttons. + @@ -122,6 +150,8 @@ If you need to render a different element, set `as` to `true` and spread `let:pr ## Extra-large size +Set `size="xl"` for extra-large buttons. + @@ -130,6 +160,8 @@ If you need to render a different element, set `as` to `true` and spread `let:pr ## Disabled state +Set `disabled` to disable the button. + @@ -15,7 +17,7 @@ Buttons in a button set are juxtaposed by default. ## Stacked -Set `stacked` to `true` to use the stacked variant. +Set `stacked` to `true` to arrange buttons vertically. diff --git a/docs/src/pages/components/Checkbox.svx b/docs/src/pages/components/Checkbox.svx index f5e7f684..8e66285a 100644 --- a/docs/src/pages/components/Checkbox.svx +++ b/docs/src/pages/components/Checkbox.svx @@ -3,39 +3,53 @@ import Preview from "../../components/Preview.svelte"; -## Default (unchecked) +Checkboxes let users select one or more options from a list. Use them for multiple-choice questions, settings, or to confirm actions. + +## Default + +Create a checkbox with a label using `labelText`. + +By default, the checkbox is unchecked. ## Checked +Set `checked` to `true` to pre-select the checkbox. + ## Indeterminate +Set `indeterminate` to `true` to show a mixed state, typically used in parent checkboxes with some children selected. + ## Hidden label +Set `hideLabel` to `true` to visually hide the label while keeping it accessible to screen readers. + -## Disabled +## Disabled state + +Set `disabled` to `true` to prevent user interaction. ## Reactive example (bind:checked) -The `checked` prop supports two-way binding. +Use two-way binding with `bind:checked` to track the checkbox state. ## Reactive example (bind:group) -An alternative to `checked` is binding an array of values using `group`. This API in inspired by Svelte [group inputs](https://svelte.dev/tutorial/group-inputs). +Bind an array of values using `group` to manage multiple checkboxes. This API is inspired by Svelte [group inputs](https://svelte.dev/tutorial/group-inputs).
- If using bind:group, bind:checked will only support one-way binding. + When using bind:group, bind:checked only supports one-way binding.
@@ -43,4 +57,6 @@ An alternative to `checked` is binding an array of values using `group`. This AP ## Skeleton +Set `skeleton` to `true` to show a loading state. + diff --git a/docs/src/pages/components/ClickableTile.svx b/docs/src/pages/components/ClickableTile.svx index e6ec3bf3..58852fdf 100644 --- a/docs/src/pages/components/ClickableTile.svx +++ b/docs/src/pages/components/ClickableTile.svx @@ -3,15 +3,19 @@ import Preview from "../../components/Preview.svelte"; +Clickable tiles create interactive content areas that link to other pages or trigger actions. Use them to group related content and provide clear navigation targets. + ## Default +Create a clickable tile with an `href` to link to another page. + Carbon Design System ## Prevent default behavior -Use the forwarded `click` event and invoke `e.preventDefault()` to prevent the native link behavior. +Handle the `click` event to override the default link behavior. Use `e.preventDefault()` to stop navigation. Carbon Design System ## Disabled state +Set `disabled` to `true` to prevent interaction. + Carbon Design System diff --git a/docs/src/pages/components/CodeSnippet.svx b/docs/src/pages/components/CodeSnippet.svx index f29d59b1..d1e1dc42 100644 --- a/docs/src/pages/components/CodeSnippet.svx +++ b/docs/src/pages/components/CodeSnippet.svx @@ -27,20 +27,21 @@ let comment = ` ` -This component uses the native, asynchronous [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) to copy text. +Code snippets display and copy code examples. They support single-line, multi-line, and inline formats with customizable copy and expand functionality. -Please note that the `clipboard.writeText` API is not supported in [IE 11 nor Safari iOS version 13.3 or lower](https://caniuse.com/mdn-api_clipboard_writetext). +This component uses the native, asynchronous [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) to copy text. You can override the default copy functionality with your own implementation. See [Overriding copy functionality](#overriding-copy-functionality). +## Default -## Default (single-line) +Display a single-line code snippet by default. ## Overriding copy functionality -To override the default copy behavior, pass a custom function to the `copy` prop. +Pass a custom function to the `copy` prop to override the default copy behavior. In this example, we use the open source module [clipboard-copy](https://github.com/feross/clipboard-copy) to copy the text instead of the default Clipboard API. @@ -48,33 +49,37 @@ In this example, we use the open source module [clipboard-copy](https://github.c ## Preventing copy functionality -To prevent text from being copied entirely, pass a no-op function to the `copy` prop. +Pass a no-op function to the `copy` prop to disable copying. {}} /> ## Inline +Set `type="inline"` to display code inline with text. + ## Multi-line +Set `type="multi"` to display multiple lines of code with expand/collapse functionality. + ## Expanded by default -Use the `expanded` prop to control whether the multi-line code snippet is expanded or not. +Set `expanded` to `true` to show the full multi-line code snippet. ## Reactive example -The multi-line code snippet also dispatches "expand" and "collapse" events. +The multi-line code snippet dispatches "expand" and "collapse" events. ## Custom copy feedback text -Use the `feedback` prop to override the default copy button feedback text. +Set `feedback` to customize the copy button feedback text. @@ -86,23 +91,25 @@ Set `hideCopyButton` to `true` to hide the copy button. ## Hidden show more button -Only multi-line code snippets have a "Show more" button by default. Set `showMoreLess` to `false` to hide it. +Set `showMoreLess` to `false` to hide the expand/collapse button on multi-line snippets. ## Hidden copy, show more buttons +Hide both the copy and expand/collapse buttons. + ## Custom show more/less text -Use the `showMoreText` and `showLessText` props to override the default "Show more" and "Show less" button text. +Set `showMoreText` and `showLessText` to customize the expand/collapse button text. ## Disabled -The `disabled` prop applies only to the `"single"` and `"multi"` code snippet types. +Set `disabled` to `true` to disable interaction. This only applies to `"single"` and `"multi"` types.
@@ -110,30 +117,34 @@ The `disabled` prop applies only to the `"single"` and `"multi"` code snippet ty ## Wrapped text -`wrapText` only applies to the `"multi"` type. +By default, the code snippet preserves text formatting and does not wrap text. + +Set `wrapText` to `true` to wrap long lines in multi-line snippets. ## Dynamic multi-line code -For dynamically updated code, you must use the `code` prop instead of the default slot. +Use the `code` prop instead of the default slot for dynamically updated code. ## Hidden multi-line code -There may be cases where your code snippet is hidden in the DOM. The logic to render the "Show more" button relies on the element's computed height. For hidden content, the button will not appear because the computed height is `0`. +The "Show more" button relies on the element's computed height. For hidden content, the button won't appear because the height is `0`. -The recommended workaround is to re-render the component. See the example below. +Re-render the component to fix this issue. ## Skeleton -The default skeleton type is `"single"`. +Set `skeleton` to `true` to show a loading state. Defaults to `"single"` type. ## Skeleton (multi-line) +Set `type="multi"` with `skeleton` to show a multi-line loading state. + \ No newline at end of file diff --git a/docs/src/pages/components/ComboBox.svx b/docs/src/pages/components/ComboBox.svx index 559b4127..6cce91f4 100644 --- a/docs/src/pages/components/ComboBox.svx +++ b/docs/src/pages/components/ComboBox.svx @@ -3,6 +3,8 @@ import Preview from "../../components/Preview.svelte"; +`ComboBox` combines a text input with a dropdown menu to let users select from predefined options or enter custom values. It supports filtering, custom item rendering, and various states. + `ComboBox` is keyed for performance reasons. @@ -11,6 +13,8 @@ ## Default +Create a combobox with a title and placeholder text. Each item requires a unique `id` and `text`. + +## Hidden label + +Set `hideLabel` to `true` to visually hide the label while keeping it accessible to screen readers. + + + ## Initial selected id +Set `selectedId` to pre-select an item when the combobox loads. + ## Clear selection -To programmatically clear the selection, access the component instance using the [bind:this](https://svelte.dev/docs#bind_element) directive and invoke the `ComboBox.clear()` accessor. +Use `bind:this` to access the component instance and call `ComboBox.clear()` to programmatically clear the selection. -Specify `focus: false` in the method options to avoid re-focusing the input. +Set `focus: false` in the method options to prevent re-focusing the input. ## Multiple combo boxes +See how to manage multiple comboboxes in a form. + ## Filterable +Enable filtering to let users search through the options. + ## Filterable with custom label -Combine a custom label `itemToString` with the filterable option (e.g., internationalization). +Set `itemToString` to customize how items display in the filterable combobox. ## Top direction -Set `direction` to `"top"` for the combobox dropdown menu to appear above the input. +Set `direction` to `"top"` to make the dropdown menu appear above the input. +`ComposedModal` lets you build custom modals by combining `ModalHeader`, `ModalBody`, and `ModalFooter` components. Use it to create focused interactions that require user attention or input. + ## Composed modal +Create a modal with a header, body, and footer. Each section can be customized independently. + ## Multiple secondary buttons -Use the `secondaryButtons` prop in `ModalFooter` to render two secondary buttons for a "3-button modal". The prop is a 2-tuple type that supersedes `secondaryButtonText`. +Set `secondaryButtons` in `ModalFooter` to create a 3-button modal. This prop replaces `secondaryButtonText` and takes a tuple of two button configurations. \ No newline at end of file diff --git a/docs/src/pages/components/ContentSwitcher.svx b/docs/src/pages/components/ContentSwitcher.svx index 5c98d9ba..73d10640 100644 --- a/docs/src/pages/components/ContentSwitcher.svx +++ b/docs/src/pages/components/ContentSwitcher.svx @@ -9,8 +9,12 @@ components: ["ContentSwitcher", "Switch"] import Preview from "../../components/Preview.svelte"; +`ContentSwitcher` lets users switch between different views or sections of content. Use it to organize related content into distinct categories or states. + ## Default +Create a content switcher with `Switch` components. Each switch needs a `text` prop. + @@ -18,6 +22,8 @@ components: ["ContentSwitcher", "Switch"] ## Initial selected index +Set `selectedIndex` to pre-select a switch when the content switcher loads. + @@ -26,10 +32,16 @@ components: ["ContentSwitcher", "Switch"] ## Reactive example +This example demonstrates how to programmatically control the content switcher using +the `bind:selectedIndex` directive. Update the selected index based on user +interactions or application state. + ## Custom switch slot +Override the default slot in `Switch` to customize how each option displays. +
@@ -45,6 +57,8 @@ components: ["ContentSwitcher", "Switch"] ## Extra-large size +Set `size` to `"xl"` for an extra-large content switcher. + @@ -52,6 +66,8 @@ components: ["ContentSwitcher", "Switch"] ## Small size +Set `size` to `"sm"` for a small content switcher. + @@ -59,6 +75,8 @@ components: ["ContentSwitcher", "Switch"] ## Disabled +Set `disabled` to `true` on individual switches to prevent interaction. + diff --git a/docs/src/pages/components/ContextMenu.svx b/docs/src/pages/components/ContextMenu.svx index eacc8ac6..3ef81928 100644 --- a/docs/src/pages/components/ContextMenu.svx +++ b/docs/src/pages/components/ContextMenu.svx @@ -6,26 +6,32 @@ components: ["ContextMenu", "ContextMenuGroup", "ContextMenuRadioGroup", "Contex import Preview from "../../components/Preview.svelte"; +`ContextMenu` displays a menu when users right-click. Use it to provide quick access to contextual actions or options. + In the examples, right click anywhere within the iframe. ## Default -By default, the context menu will trigger when right clicking anywhere in the `window`. +The context menu appears when right-clicking anywhere in the window. Use `ContextMenuOption` for menu items and `ContextMenuDivider` for visual separation. ## Custom target -Specify a custom `HTMLElement` using the `target` prop. +By default, the context menu will trigger when right clicking anywhere in the `window`. + +Set `target` to specify which element triggers the context menu. ## Multiple targets -The `target` prop also accepts an array of elements. +Set `target` to an array of elements to trigger the context menu from multiple sources. ## Radio groups - + +Use `ContextMenuGroup` and `ContextMenuRadioGroup` to organize related options and create radio button selections. + \ No newline at end of file diff --git a/docs/src/pages/components/CopyButton.svx b/docs/src/pages/components/CopyButton.svx index a450d6b7..88eaed24 100644 --- a/docs/src/pages/components/CopyButton.svx +++ b/docs/src/pages/components/CopyButton.svx @@ -3,30 +3,32 @@ import Preview from "../../components/Preview.svelte"; -This component uses the native, asynchronous [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) to copy text. +`CopyButton` lets users copy text to their clipboard with a single click. Use it to provide quick access to code snippets, links, or other text content. -Please note that the `clipboard.writeText` API is not supported in [IE 11 nor Safari iOS version 13.3 or lower](https://caniuse.com/mdn-api_clipboard_writetext). - -You can override the default copy functionality with your own implementation. See [Overriding copy functionality](#overriding-copy-functionality). +This component uses the native [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText) to copy text. Override the default copy functionality with your own implementation. See [Overriding copy functionality](#overriding-copy-functionality). ## Default +Create a copy button with the `text` prop to specify what to copy. + ## Custom feedback text +Set `feedback` to customize the message shown after copying. + ## Overriding copy functionality -To override the default copy behavior, pass a custom function to the `copy` prop. +Pass a custom function to the `copy` prop to override the default copy behavior. -In this example, we use the open source module [clipboard-copy](https://github.com/feross/clipboard-copy) to copy the text instead of the default Clipboard API. +This example uses the NPM package [clipboard-copy](https://github.com/feross/clipboard-copy) to copy the text instead of the default Clipboard API. ## Preventing copy functionality -To prevent text from being copied entirely, pass a no-op function to the `copy` prop. +Pass a no-op function to the `copy` prop to disable copying. - {}} /> \ No newline at end of file + {}} /> diff --git a/docs/src/pages/components/DataTable.svx b/docs/src/pages/components/DataTable.svx index 70c758e3..c3eb1c59 100644 --- a/docs/src/pages/components/DataTable.svx +++ b/docs/src/pages/components/DataTable.svx @@ -8,21 +8,20 @@ components: ["DataTable", "Pagination","Toolbar", "ToolbarContent", "ToolbarSear import Preview from "../../components/Preview.svelte"; -`DataTable` is keyed for performance reasons. +`DataTable` displays structured data in a tabular format. Use it to present large datasets with features like sorting, filtering, pagination, and row selection. -
Every headers object must have a unique "key" property.
- - - -
Every rows object must have a unique "id" property.
+
+ This component is keyed for performance. + + Every headers object must have a unique "key" property. +
Every rows object must have a unique "id" property.
+
## Default -The key value in `headers` corresponds to the key value defined in `rows`. - -For example, the header key `"name"` will use the value of `rows[index].name`. +Create a basic table by providing `headers` and `rows` data. Match the `key` in headers with the corresponding property in rows.
Custom column widths do not work with a sticky header.
@@ -340,9 +337,7 @@ A [table-layout: fixed](https://developer.mozilla.org/en-US/docs/Web/CSS/table-l ## Sticky header -Set `stickyHeader` to `true` for the header to be fixed in place. - -A maximum height will applied to the datatable to force a scrollbar. +Set `stickyHeader` to `true` to fix the header in place. This adds a maximum height to force scrolling. ## Filterable (custom) -`shouldFilterRows` also accepts a function and passes it the current row and search value. It expects the function to return a boolean. +Pass a function to `shouldFilterRows` to implement custom filtering logic. ## Zebra stripes +Set `zebra` to `true` to add alternating row colors. + ## Sortable with custom display and sort methods +Use `display` and `sort` functions in header objects to customize cell rendering and sorting. + ## Empty column with overflow menu -Some use cases require an empty column in the table body without a corresponding table header. - -For an object in the `headers` array, set `empty` to `true` to render an empty column. - -In the following example, each row in the sortable data table has an overflow menu. There isn't a separate, useless table header column for the overflow menu. +Set `empty: true` in a header object to create an empty column. Use this for overflow menus without a header. ## Selectable rows (checkbox) -Set `selectable` to `true` for rows to be multi-selectable. - -Bind to `selectedRowIds` to get the ids of the selected rows. - -To customize the `input` name for the checkbox, use the `inputName` prop. +Set `selectable` to `true` for multi-select functionality. Bind to `selectedRowIds` to track selections. Use `inputName` to customize checkbox names. ## Batch selection -To enable batch selection, set `batchSelection` to `true`. - -This checkbox is used to select all rows. It enters an indeterminate state when some rows are selected. +Set `batchSelection` to `true` to add a checkbox for selecting all rows. The checkbox shows an indeterminate state when some rows are selected. ## Batch selection with initial selected rows -Use the `selectedRowIds` prop to specify which rows should be selected. +Use `selectedRowIds` to specify initially selected rows. ## Batch selection with batch actions toolbar +Add a toolbar for batch actions when rows are selected. + ## Batch selection with controlled toolbar -By default, `ToolbarBatchActions` is activated if one or more rows is selected. Clicking "Cancel" will deactivate it. - -Use the `active` prop to control the toolbar. Note that it will still activate if one or more rows are selected. - -You can prevent the default "Cancel" behavior in the dispatched `on:cancel` event. +Control the batch actions toolbar with the `active` prop. Prevent default cancel behavior in the `on:cancel` event. ## Selectable rows (radio) -Set `radio` to `true` for only one row to be selected at a time. - -Bind to `selectedRowIds` to get the ids of the selected rows. Because it's radio selection, `selectedRowIds` will only contain one id. - -To customize the `input` name for the radio button, use the `inputName` prop. +Set `radio` to `true` for single-row selection. Bind to `selectedRowIds` to track the selected row. Use `inputName` to customize radio button names. ## Non-selectable rows -Use `nonSelectableRowIds` to specify the ids for rows that should not be selectable. +Use `nonSelectableRowIds` to prevent selection of specific rows. ## Expandable rows -Set `expandable` to `true` for rows to be expandable. +Set `expandable` to `true` to make rows expandable. Use the `expanded-row` slot to customize expanded content. ## Expandable (zebra styles) +Combine expandable rows with zebra striping. + ## Expandable (compact size) +Set `size="compact"` for expandable rows with minimal height. + ## Skeleton +Use `DataTableSkeleton` to show a loading state. + ## Skeleton with headers, row count +Specify headers and row count for the skeleton. + ## Skeleton with object headers -`headers` can also be an array of objects. The type is the same as the `headers` prop type used in `DataTable`. +Pass header objects to customize the skeleton. ## Skeleton with empty header -Pass an object with `"empty"` set to `true` to render an empty table header column. +Add an empty header column with `empty: true`. ## Skeleton without header, toolbar +Hide the header and toolbar in the skeleton. + ## Skeleton (tall size) +Set `size="tall"` for a taller skeleton. + ## Skeleton (short size) +Set `size="short"` for a shorter skeleton. + ## Skeleton (compact size) +Set `size="compact"` for a minimal skeleton. + \ No newline at end of file diff --git a/docs/src/pages/components/DatePicker.svx b/docs/src/pages/components/DatePicker.svx index 3e4dbdcf..c7cb9f3f 100644 --- a/docs/src/pages/components/DatePicker.svx +++ b/docs/src/pages/components/DatePicker.svx @@ -7,11 +7,7 @@ components: ["DatePicker", "DatePickerInput", "DatePickerSkeleton"] import Preview from "../../components/Preview.svelte"; -Carbon uses the zero dependency [flatpickr](https://github.com/flatpickr/flatpickr) library for its underlying calendar implementation. - -Set `datePickerType` to `"single"` or `"range"` for the calendar functionality. - -Specify [flatpickr options](https://flatpickr.js.org/options/) through the `flatpickrProps` prop. +`DatePicker` lets users select a date or date range using a calendar interface. It uses the [flatpickr](https://github.com/flatpickr/flatpickr) library for its calendar implementation.
@@ -21,25 +17,27 @@ Specify [flatpickr options](https://flatpickr.js.org/options/) through the `flat ## Single -By default, the `flatpickr` option `static` is set to `true` so that the calendar is positioned inside the wrapper and next to the input element. This is required for the calendar position to work inside a [Modal](/components/Modal). - -Set `flatpickrProps.static` to `false` to opt out of this behavior. +Set `datePickerType` to `"single"` for single date selection. ## Range -Set `datePickerType` to `"range"` for the range variant. +Set `datePickerType` to `"range"` to enable date range selection. ## DatePicker in a modal +The calendar is positioned inside the wrapper by default (`flatpickrProps.static: true`). This ensures proper positioning within a [Modal](/components/Modal). + +Set `flatpickrProps.static` to `false` to position the calendar outside the wrapper. + ## Simple -By default, the "simple" date picker does not have a dropdown calendar. +Create a simple date picker without a dropdown calendar. @@ -47,52 +45,70 @@ By default, the "simple" date picker does not have a dropdown calendar. ## With helper text +Add helper text to provide additional context or formatting instructions. + ## Hidden label +Hide the label while maintaining accessibility. + ## Light variant +Use the light variant for light backgrounds. + ## Extra-large size +Use the extra-large size for more prominent date pickers. + ## Small size +Use the small size for compact date pickers. + ## Invalid state +Show an invalid state when the input value is not valid. + ## Warning state +Show a warning state to indicate potential issues with the input. + ## Disabled state +Disable the date picker to prevent user interaction. + ## Skeleton +Show a loading state with the skeleton component. + diff --git a/docs/src/pages/components/Dropdown.svx b/docs/src/pages/components/Dropdown.svx index 477fcce9..afd5cee2 100644 --- a/docs/src/pages/components/Dropdown.svx +++ b/docs/src/pages/components/Dropdown.svx @@ -7,7 +7,9 @@ components: ["Dropdown", "DropdownSkeleton"] import Preview from "../../components/Preview.svelte"; -`Dropdown` is keyed for performance reasons. +The `Dropdown` component provides a select input with a dropdown menu. It supports +various states, sizes, and customization options. Each item in the dropdown must +have a unique `id` property for proper functionality.
Every items object must have a unique "id" property.
@@ -15,25 +17,33 @@ components: ["Dropdown", "DropdownSkeleton"] ## Default +Use the `Dropdown` component to create a select input with a dropdown menu. Each item +must have a unique `id` property. + ## Custom slot -Override the default slot to customize the display of each item. Access the item and index through the `let:` directive. +Override the default slot to customize the display of each item. Access the item and +index through the `let:` directive. ## Hidden label +Hide the label while maintaining accessibility by setting the `hideLabel` prop to +`true`. The label will still be available to screen readers. + ## Format item display text -Use the `itemToString` prop to format the display of individual items. +Format the display text of items using the `itemToString` prop. This function +receives the item object and returns the formatted string. { return item.text + ' (' + item.id +')' @@ -43,11 +53,15 @@ Use the `itemToString` prop to format the display of individual items. ## Multiple dropdowns +Create multiple dropdowns that work together. This example demonstrates how to +manage the state of multiple dropdowns. + ## Top direction -Set `direction` to `"top"` for the dropdown menu to appear above the input. +Display the dropdown menu above the input by setting the `direction` prop to +`"top"`. This is useful when there's limited space below the input. ## Inline variant +Display the dropdown inline with other content by setting the `type` prop to +`"inline"`. This variant removes the background and border. + ## Extra-large size +Increase the size of the dropdown by setting the `size` prop to `"xl"`. This +provides more visual emphasis for important selections. + ## Small size +Decrease the size of the dropdown by setting the `size` prop to `"sm"`. This is +useful for compact layouts or secondary selections. + ## Invalid state +Indicate an invalid selection by setting the `invalid` prop to `true`. Provide +feedback to users with the `invalidText` prop. + ## Warning state +Indicate a warning state by setting the `warn` prop to `true`. Provide additional +context with the `warnText` prop. + ## Disabled state +Disable the entire dropdown by setting the `disabled` prop to `true`. This prevents +user interaction with the component. + ## Disabled items -Use the `disabled` property in the `items` prop to disable specific items. +Disable specific items in the dropdown by setting the `disabled` property to +`true` in the item object. This allows for more granular control over available +selections. \ No newline at end of file diff --git a/docs/src/pages/components/ExpandableTile.svx b/docs/src/pages/components/ExpandableTile.svx index aca659fa..398d64ee 100644 --- a/docs/src/pages/components/ExpandableTile.svx +++ b/docs/src/pages/components/ExpandableTile.svx @@ -3,11 +3,19 @@ import Preview from "../../components/Preview.svelte"; +The `ExpandableTile` component creates a collapsible content container that can +show and hide content with a smooth animation. It's ideal for managing content +overflow and progressive disclosure of information. The component automatically +measures content height using a resize observer. + ## Default -This component uses a [resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) to determine the height of the above-the-fold content. +Create an expandable tile that shows and hides content. The component uses a +[resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver) +to determine the height of the above-the-fold content. -It's unexpanded by default. +By default, the tile is collapsed. Use the `above` and `below` slots to define the +content that appears before and after expansion.
@@ -25,7 +33,8 @@ It's unexpanded by default. ## Custom tile heights -Set a custom height for the tiles on the "above" and "below" slots. +Set custom heights for the tile content using CSS. This is useful when you need to +control the exact dimensions of the visible and hidden content.
Above the fold content here
@@ -34,6 +43,9 @@ Set a custom height for the tiles on the "above" and "below" slots. ## Expanded +Display the tile in its expanded state by default by setting the `expanded` prop to +`true`. +
Above the fold content here
Below the fold content here
@@ -41,6 +53,9 @@ Set a custom height for the tiles on the "above" and "below" slots. ## Light variant +Use the light variant for expandable tiles on dark backgrounds by setting the +`light` prop to `true`. +
Above the fold content here
Below the fold content here
@@ -48,6 +63,9 @@ Set a custom height for the tiles on the "above" and "below" slots. ## With icon labels +Customize the expand/collapse button labels using the `tileExpandedLabel` and +`tileCollapsedLabel` props. +
Above the fold content here
Below the fold content here
@@ -55,7 +73,9 @@ Set a custom height for the tiles on the "above" and "below" slots. ## With interactive content -For tiles containing interactive content, use `stopPropagation` to prevent the tile from toggling. +Handle interactive content within the tile by preventing event propagation. This +ensures that clicks on interactive elements don't trigger the tile's expand/collapse +behavior.
diff --git a/docs/src/pages/components/FileUploader.svx b/docs/src/pages/components/FileUploader.svx index 961a481d..37e30df5 100644 --- a/docs/src/pages/components/FileUploader.svx +++ b/docs/src/pages/components/FileUploader.svx @@ -7,23 +7,28 @@ components: ["FileUploaderButton", "FileUploader", "FileUploaderDropContainer", import Preview from "../../components/Preview.svelte"; +The `FileUploader` components provide a complete solution for file uploads, including +a button trigger, drag-and-drop container, and file list display. The components +support various states, file validation, and customization options. + ## File uploader (button-only) -By default, the file uploader only accepts one file. - -Set `multiple` to `true` for multiple files to be accepted. +Create a simple file upload button using `FileUploaderButton`. By default, it +accepts a single file. Set `multiple` to `true` to allow multiple file selection. ## Multiple files +Enable multiple file selection by setting the `multiple` prop to `true`. This +allows users to select multiple files at once. + ## Custom button kind, size -By default, the `primary` small button kind is used. - -Use the `kind` and `size` props to customize the button. +Customize the button appearance using the `kind` and `size` props. The default is +a small primary button. @@ -32,17 +37,17 @@ Use the `kind` and `size` props to customize the button. ## File uploader -The `FileUploader` wraps `FileUploaderButton` and lists out uploaded files. +The `FileUploader` component combines a button trigger with a list of uploaded +files. It supports file type restrictions, multiple file selection, and various +upload states. -The example below accepts multiple files with an extension of `.jpg` or `.jpeg`. It sets the status to `"complete"`; by default, the status is `"loading"`. - -See the [item examples below](#item-uploading) for different statuses. +This example accepts multiple JPEG files and displays them in a completed state. ## Clear files -There are two ways to clear files in `FileUploader`: +Remove uploaded files from the `FileUploader` component in two ways: programmatically using the clearFiles accessor @@ -53,21 +58,29 @@ There are two ways to clear files in `FileUploader`: ## File uploader (disabled state) +Disable the file uploader by setting the `disabled` prop to `true`. This prevents +user interaction with the component. + ## Item (uploading) +Display a file upload in progress using the `uploading` status. This shows a +loading indicator and the file name. + ## Item (complete) +Show a successfully uploaded file using the `complete` status. This displays a +checkmark icon next to the file name. + ## Item (edit) -If the `status` is `"edit"`, clicking the close icon will dispatch a `delete` event. - -The event detail contains the item `id`. +Enable file deletion by setting the status to `"edit"`. Clicking the close icon +dispatches a `delete` event with the item's ID. { console.log(e.detail); // "readme" @@ -75,13 +88,15 @@ The event detail contains the item `id`. ## Item (edit status, invalid state) -An item can also have an edit status with an invalid state. +Mark a file as invalid while keeping it editable. This shows an error icon and +allows the user to remove the file. ## Item (edit status, invalid state with subject, body) -Use the `errorSubject` and `errorBody` props to customize the error message. +Provide detailed error messages for invalid files using the `errorSubject` and +`errorBody` props. This helps users understand and resolve upload issues. @@ -103,11 +119,11 @@ The default `FileUploaderItem` size is "default". ## Drop container -The `FileUploaderDropContainer` accepts files through click and drop events. +Use `FileUploaderDropContainer` for drag-and-drop file uploads. It supports file +validation and multiple file selection. -Use the `validateFiles` prop to filter out files before they are set. - -The following example accepts files smaller than 1 kB. +This example accepts files smaller than 1 kB and logs the selected files to the +console. \ No newline at end of file diff --git a/docs/src/pages/components/FluidForm.svx b/docs/src/pages/components/FluidForm.svx index 68dbc604..d05f56d8 100644 --- a/docs/src/pages/components/FluidForm.svx +++ b/docs/src/pages/components/FluidForm.svx @@ -7,9 +7,15 @@ import Preview from "../../components/Preview.svelte"; +The `FluidForm` component provides a fluid-width form layout that adapts to its +container. It's designed for full-width form layouts and works with most Carbon +input components. Note that inline input variants cannot be used within a +`FluidForm`. + ## Fluid form -Note that the `inline` input variants cannot be used within a `FluidForm`. +Create a fluid-width form layout using the `FluidForm` component. This example +shows a basic login form with required fields. @@ -23,4 +29,8 @@ Note that the `inline` input variants cannot be used within a `FluidForm`. ## Invalid state +Handle form validation and display error states using the `invalid` and +`invalidText` props on form inputs. This example demonstrates how to show +validation errors in a fluid form. + \ No newline at end of file diff --git a/docs/src/pages/components/Form.svx b/docs/src/pages/components/Form.svx index 4989c5dd..a0db291b 100644 --- a/docs/src/pages/components/Form.svx +++ b/docs/src/pages/components/Form.svx @@ -14,8 +14,15 @@ components: ["Form", "FormGroup"] import Preview from "../../components/Preview.svelte"; +The `Form` component provides a structured way to collect user input. It works with +various form controls like checkboxes, radio buttons, and select menus. The +`FormGroup` component helps organize related form controls with a legend. + ## Form +Create a form with grouped controls using `Form` and `FormGroup`. This example +shows a form with checkboxes, radio buttons, and a select menu. +
@@ -63,7 +70,9 @@ components: ["Form", "FormGroup"] ## Prevent default behavior -The forwarded `submit` event is not modified. Use `e.preventDefault()` to prevent the native form submission behavior. +Handle form submission by preventing the default browser behavior. Use +`e.preventDefault()` to stop the native form submission and handle the event +programmatically. { e.preventDefault(); diff --git a/docs/src/pages/components/Grid.svx b/docs/src/pages/components/Grid.svx index 0092b662..741eea4d 100644 --- a/docs/src/pages/components/Grid.svx +++ b/docs/src/pages/components/Grid.svx @@ -6,34 +6,62 @@ components: ["Grid", "Row", "Column"] import Preview from "../../components/Preview.svelte"; +The `Grid` system provides a responsive, 12-column layout structure. Use `Row` and +`Column` components to create flexible layouts that adapt to different screen +sizes. The grid supports various spacing options and column configurations. + ## Default +Create a basic grid layout with equal-width columns. This example demonstrates the +default grid behavior. + ## Full width +Use the full-width grid variant for layouts that span the entire viewport width. +This removes the default max-width constraint. + ## Narrow +Create a more compact grid layout using the narrow variant. This reduces the +spacing between columns. + ## Condensed +Use the condensed variant for even tighter spacing between columns. This is ideal +for dense data displays. + ## Responsive +Build responsive layouts by specifying different column widths for different +breakpoints. The grid automatically adjusts based on screen size. + ## Offset columns +Create space between columns using the offset feature. This allows for more +flexible layouts without empty columns. + ## Aspect ratio columns +Maintain consistent column heights using aspect ratio columns. This ensures +content alignment across different column widths. + ## Padded columns +Add padding to columns using the padded variant. This creates more breathing room +between content. + diff --git a/docs/src/pages/components/ImageLoader.svx b/docs/src/pages/components/ImageLoader.svx index f332849c..41f79999 100644 --- a/docs/src/pages/components/ImageLoader.svx +++ b/docs/src/pages/components/ImageLoader.svx @@ -5,15 +5,22 @@ let key = 0; -This utility component uses the [Image API](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image) to programmatically load an image with slottable loading and error states. - +The `ImageLoader` component provides a robust way to load images with built-in +loading and error states. It uses the [Image API](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/Image) +to handle image loading programmatically. The component supports aspect ratios, +fade-in animations, and custom loading/error states. + ## Default - + +Load an image with the default configuration. The component handles the loading +process automatically. + ## Slots -Use the "loading" and "error" named slots to render an element when the image is loading or has an error. +Customize the loading and error states using named slots. This example shows how +to display a loading indicator and error message. @@ -26,27 +33,32 @@ Use the "loading" and "error" named slots to render an element when the image is ## With aspect ratio -If `ratio` is set, this component uses the [AspectRatio](/components/AspectRatio) to constrain the image. +Maintain consistent image dimensions using aspect ratios. The component uses +[AspectRatio](/components/AspectRatio) to constrain the image. -Supported aspect ratios include `"2x1"`, `"2x3"`, `"16x9"`, `"4x3"`, `"1x1"`, `"3x4"`, `"3x2"`, `"9x16"` and `"1x2"`. +Supported aspect ratios include `"2x1"`, `"2x3"`, `"16x9"`, `"4x3"`, `"1x1"`, +`"3x4"`, `"3x2"`, `"9x16"` and `"1x2"`. ## Fade in -Set `fadeIn` to `true` to fade in the image if successfully loaded. +Enable a smooth fade-in animation when the image loads successfully. This provides +a better user experience for image loading. {#key key}{/key} ## Programmatic usage -In this example, a component reference is obtained to programmatically trigger the `loadImage` method. +Control image loading programmatically using component references. This example +demonstrates how to trigger image loading manually. ## Dynamic image source -The same `ImageLoader` instance can be used to load different images. +Update the image source dynamically using the same `ImageLoader` instance. This +allows for smooth transitions between different images. diff --git a/docs/src/pages/components/InlineLoading.svx b/docs/src/pages/components/InlineLoading.svx index 1677b675..be82a72c 100644 --- a/docs/src/pages/components/InlineLoading.svx +++ b/docs/src/pages/components/InlineLoading.svx @@ -1,18 +1,37 @@ +--- +components: ["InlineLoading"] +--- + +The `InlineLoading` component provides a compact loading indicator that can be embedded within content. It's ideal for showing progress during inline operations like form submissions or data updates. + ## Default +Display a basic loading indicator with the default configuration. + ## With description +Add a descriptive text to provide context about the loading operation. + ## Status states +The component supports different status states to indicate progress: + + + active: Shows an animated loading indicator + inactive: Displays a static state + finished: Shows a success state + error: Displays an error state + + @@ -20,4 +39,6 @@ ## UX example +See how to integrate the loading indicator in a real-world scenario. + \ No newline at end of file diff --git a/docs/src/pages/components/InlineNotification.svx b/docs/src/pages/components/InlineNotification.svx index 33482ced..73cc37f7 100644 --- a/docs/src/pages/components/InlineNotification.svx +++ b/docs/src/pages/components/InlineNotification.svx @@ -7,26 +7,29 @@ components: ["InlineNotification", "NotificationActionButton"] import Preview from "../../components/Preview.svelte"; -Notification that appears inline. +The `InlineNotification` component displays contextual messages inline with content. It supports various types of notifications (error, warning, success, info) and can include actions. Use it to provide feedback or important information to users. -See [detailed -usage](https://carbondesignsystem.com/components/notification/usage). +See [detailed usage](https://carbondesignsystem.com/components/notification/usage). See also: [ToastNotification](ToastNotification) -## Default (error) +## Default + +Display a basic error notification with title and subtitle by default. ## Prevent default close behavior -`InlineNotification` is a controlled component. Prevent the default close behavior using the `e.preventDefault()` method in the dispatched `on:close` event. +The component is controlled, allowing you to prevent the default close behavior using `e.preventDefault()`. { e.preventDefault(); // custom close logic (e.g., transitions) }} /> -## Slottable title, subtitle +## Slottable title and subtitle + +Customize the notification content using slots for more flexibility. Error: @@ -35,9 +38,7 @@ See also: [ToastNotification](ToastNotification) ## Accessible icon descriptions -The status icon and close button icon descriptions appear on cursor hover and are read -by assistive technology. Default descriptions are provided in English and can be -overridden via `statusIconDescription` and `closeButtonDescription`. +Make notifications more accessible by providing custom descriptions for icons.