From d20b36c365c5a7cdbc3d4d5c0b6205e7e172dffe Mon Sep 17 00:00:00 2001 From: Ben Elan Date: Wed, 27 Sep 2023 18:09:55 -0700 Subject: [PATCH] ci: add markdownlint config file and generate/lint component docs (#7887) **Related Issue:** #7662 ## Summary - Add project markdownlint config - Set rules for project consistency (versus the default file consistency) - Generate component READMEs - Lint markdown files and fix some issues manually --- .lintstagedrc.json | 2 +- .markdownlintrc | 13 ++ packages/calcite-components/.gitignore | 1 + .../Accessibility/AccessibilityDesign.md | 57 ++++++- .../Accessibility/AccessibilityDeveloper.md | 16 +- .../Accessibility/AccessibilityRoles.md | 58 +++++-- .../calcite-components/conventions/README.md | 10 +- packages/calcite-components/package.json | 2 +- .../src/components/accordion-item/readme.md | 8 +- .../src/components/action-bar/readme.md | 50 +++--- .../src/components/action-group/readme.md | 36 ++-- .../src/components/action-menu/readme.md | 2 +- .../src/components/action-pad/readme.md | 26 ++- .../src/components/action/readme.md | 45 ++--- .../src/components/alert/readme.md | 26 +-- .../src/components/avatar/readme.md | 20 ++- .../src/components/block-section/readme.md | 26 ++- .../src/components/block/readme.md | 70 +++++--- .../src/components/button/readme.md | 47 +++--- .../src/components/card/readme.md | 2 +- .../src/components/checkbox/readme.md | 16 +- .../src/components/chip-group/readme.md | 64 ++++--- .../src/components/chip/readme.md | 36 ++-- .../color-picker-hex-input/readme.md | 29 ++-- .../components/color-picker-swatch/readme.md | 2 - .../src/components/color-picker/readme.md | 48 +++--- .../components/combobox-item-group/readme.md | 8 +- .../src/components/combobox-item/readme.md | 29 ++-- .../src/components/combobox/readme.md | 62 ++++--- .../src/components/date-picker/readme.md | 18 +- .../src/components/dropdown-group/readme.md | 9 +- .../src/components/dropdown/readme.md | 40 +++-- .../src/components/fab/readme.md | 12 +- .../src/components/filter/readme.md | 28 +++- .../src/components/flow-item/readme.md | 53 +++--- .../src/components/flow/readme.md | 110 +++++++++--- .../src/components/handle/readme.md | 16 +- .../src/components/icon/readme.md | 12 +- .../src/components/inline-editable/readme.md | 30 ++-- .../components/input-date-picker/readme.md | 24 ++- .../src/components/input-message/readme.md | 12 +- .../src/components/input-number/readme.md | 94 +++++++---- .../src/components/input-text/readme.md | 70 ++++---- .../components/input-time-picker/readme.md | 54 +++--- .../src/components/input-time-zone/readme.md | 13 +- .../src/components/input/readme.md | 46 +++-- .../src/components/label/readme.md | 2 + .../src/components/list-item-group/readme.md | 6 + .../src/components/list-item/readme.md | 29 +++- .../src/components/list/readme.md | 90 +++++++--- .../src/components/menu-item/readme.md | 59 +++---- .../src/components/menu/readme.md | 10 +- .../src/components/meter/readme.md | 15 +- .../src/components/modal/readme.md | 46 ++--- .../src/components/navigation-user/readme.md | 2 +- .../src/components/navigation/readme.md | 22 ++- .../src/components/notice/readme.md | 30 ++-- .../src/components/pagination/readme.md | 31 +++- .../src/components/panel/readme.md | 49 +++--- .../src/components/pick-list-group/readme.md | 6 + .../src/components/pick-list-item/readme.md | 9 +- .../src/components/pick-list/readme.md | 7 + .../src/components/popover/readme.md | 4 +- .../components/radio-button-group/readme.md | 28 +++- .../src/components/radio-button/readme.md | 1 + .../src/components/rating/readme.md | 23 +-- .../src/components/scrim/readme.md | 10 +- .../components/segmented-control/readme.md | 27 +-- .../src/components/select/readme.md | 19 ++- .../src/components/sheet/readme.md | 2 +- .../src/components/shell-panel/readme.md | 37 ++-- .../src/components/shell/readme.md | 35 ++-- .../src/components/slider/readme.md | 53 +++--- .../src/components/sortable-list/readme.md | 2 + .../src/components/split-button/readme.md | 10 ++ .../src/components/stack/readme.md | 69 +++++++- .../src/components/stepper/readme.md | 2 +- .../src/components/switch/readme.md | 17 +- .../src/components/tab-nav/readme.md | 10 +- .../src/components/tab-title/readme.md | 20 ++- .../src/components/table-cell/readme.md | 16 +- .../src/components/table-header/readme.md | 27 +-- .../src/components/table-row/readme.md | 9 +- .../src/components/table/readme.md | 158 +++++++++++++++--- .../src/components/text-area/readme.md | 53 +++--- .../src/components/time-picker/readme.md | 14 +- .../src/components/tip-manager/readme.md | 10 +- .../src/components/tip/readme.md | 16 +- .../src/components/tooltip/readme.md | 18 +- .../src/components/tree/readme.md | 12 +- .../src/components/value-list-item/readme.md | 14 +- .../src/components/value-list/readme.md | 37 ++-- 92 files changed, 1689 insertions(+), 929 deletions(-) create mode 100644 .markdownlintrc diff --git a/.lintstagedrc.json b/.lintstagedrc.json index ccfc4ea149f..d1ce70ece5f 100644 --- a/.lintstagedrc.json +++ b/.lintstagedrc.json @@ -3,5 +3,5 @@ "*.scss": ["stylelint --fix", "prettier --write"], "packages/**/*.{ts,tsx}": ["eslint --ext .ts,.tsx --fix", "prettier --write"], ".github/scripts/*.js": ["eslint --ext .js", "prettier --write"], - "*.md": ["markdownlint --fix --disable MD024 MD013 MD041 MD033", "prettier --write"] + "*.md": ["markdownlint --fix", "prettier --write"] } diff --git a/.markdownlintrc b/.markdownlintrc new file mode 100644 index 00000000000..c75a3ecaeb9 --- /dev/null +++ b/.markdownlintrc @@ -0,0 +1,13 @@ +{ + "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json", + "first-line-heading": false, + "no-inline-html": false, + "line-length": false, + "code-block-style": { "style": "fenced" }, + "code-fence-style": { "style": "backtick" }, + "heading-style": { "style": "atx" }, + "no-duplicate-heading": { "siblings_only": true }, + "emphasis-style": { "style": "underscore" }, + "strong-style": { "style": "underscore" }, + "ul-style": { "style": "dash" } +} diff --git a/packages/calcite-components/.gitignore b/packages/calcite-components/.gitignore index 21d2801f286..99ebe35f344 100644 --- a/packages/calcite-components/.gitignore +++ b/packages/calcite-components/.gitignore @@ -3,4 +3,5 @@ docs/ hydrate/ *.js src/components/icon/assets +node_modules www/ diff --git a/packages/calcite-components/conventions/Accessibility/AccessibilityDesign.md b/packages/calcite-components/conventions/Accessibility/AccessibilityDesign.md index 666c5cdf2d5..704fc3a50ad 100644 --- a/packages/calcite-components/conventions/Accessibility/AccessibilityDesign.md +++ b/packages/calcite-components/conventions/Accessibility/AccessibilityDesign.md @@ -1,12 +1,53 @@ # Design Quick Start Guide -1. **[Color](#1-color)**: [Color contrast](#color-contrast) | [Color and state](#color--state) -2. **[Typography](#2-typography)**: [Text styling](#text-styling) | [Text resizing](#text-resizing) -3. **[Information hierarchy](#3-information-hierarchy)**: [Semantic structure](#semantic-structure) | [Headings](#headings) | [Links](#links) | [Navigation](#navigation) | [Focus order](#focus-order) -4. **[Forms](#4-forms)**: [Labels](#labels) | [Grouping controls](#grouping-controls) | [Form fields](#form-fields) | [Buttons and disabled buttons](#buttons) | [User notifications](#user-notifications) | [Touch zones](#touch-zones) -5. **[Images](#5-images)**: [Background images](#background-images) | [Icons](#icons) -6. **[Animation](#6-animation)** -7. **[Writing and labels](#7-writing-and-labels)**: [Error messaging](#error-messaging) +
+ Table of Contents + +- [Design Quick Start Guide](#design-quick-start-guide) + - [1. Color](#1-color) + - [Color contrast](#color-contrast) + - [Color and state](#color-and-state) + - [Who does color help?](#who-does-color-help) + - [Color resources](#color-resources) + - [WCAG Success Criteria for Color](#wcag-success-criteria-for-color) + - [2. Typography](#2-typography) + - [Text styling](#text-styling) + - [Text resizing](#text-resizing) + - [Who does typography help?](#who-does-typography-help) + - [Typography resources](#typography-resources) + - [3. Information hierarchy](#3-information-hierarchy) + - [Semantic structure](#semantic-structure) + - [Headings](#headings) + - [Links](#links) + - [Navigation](#navigation) + - [Focus order](#focus-order) + - [Who does information hierarchy help?](#who-does-information-hierarchy-help) + - [Information hierarchy resources](#information-hierarchy-resources) + - [WCAG Success Criteria for Information hierarchy](#wcag-success-criteria-for-information-hierarchy) + - [4. Forms](#4-forms) + - [Labels](#labels) + - [Grouping controls](#grouping-controls) + - [Form fields](#form-fields) + - [Buttons](#buttons) + - [Disabled buttons](#disabled-buttons) + - [User notifications](#user-notifications) + - [Touch zones](#touch-zones) + - [Who does form accessibility help?](#who-does-form-accessibility-help) + - [WCAG Success Criteria for Forms](#wcag-success-criteria-for-forms) + - [5. Images](#5-images) + - [Background images](#background-images) + - [Icons](#icons) + - [Who does image accessibility help?](#who-does-image-accessibility-help) + - [WCAG Success Criteria for Images](#wcag-success-criteria-for-images) + - [6. Animation](#6-animation) + - [Who does animation help?](#who-does-animation-help) + - [WCAG Success Criteria for Animation](#wcag-success-criteria-for-animation) + - [7. Writing and labels](#7-writing-and-labels) + - [Error messaging](#error-messaging) + - [Who does writing and labels help?](#who-does-writing-and-labels-help) + - [WCAG Success Criteria for Writing and labels](#wcag-success-criteria-for-writing-and-labels) + +
## 1. Color @@ -18,7 +59,7 @@ Large text equates 18pt or 14pt bold and greater. Regular sized text is anything > Note: Windows also provides a high contrast mode that is designed to improve text legibility and readability. It is often used by people with low-vision. High contrast mode will force a preset color palette on the browsing experience, but it also disables background images. -### Color & state +### Color and state When designing components, it is important to use a combination of color, shapes, and text to indicate states and statuses, such as keyboard focus, form validation, and alerts. Using these other elements provides a secondary indicator in the event a color cannot be seen. diff --git a/packages/calcite-components/conventions/Accessibility/AccessibilityDeveloper.md b/packages/calcite-components/conventions/Accessibility/AccessibilityDeveloper.md index 0fba906328c..9d0aa9bf49e 100644 --- a/packages/calcite-components/conventions/Accessibility/AccessibilityDeveloper.md +++ b/packages/calcite-components/conventions/Accessibility/AccessibilityDeveloper.md @@ -1,8 +1,18 @@ # Developer Quick Start Guide -1. **[Shadow DOM](#1-shadow-dom)** -2. **[Tests](#2-tests)**: [Adding a test](#adding-a-test) | [Failed test example](#failed-test-example) | [How to test](#how-to-test) -3. **[Storybook](#3-storybook)**: [Adding a new story](#adding-a-new-story) +
+ Table of Contents + +- [Developer Quick Start Guide](#developer-quick-start-guide) + - [1. Shadow DOM](#1-shadow-dom) + - [2. Tests](#2-tests) + - [Adding a test](#adding-a-test) + - [Failed test example](#failed-test-example) + - [How to test](#how-to-test) + - [3. Storybook](#3-storybook) + - [Adding a new story](#adding-a-new-story) + +
## 1. Shadow DOM diff --git a/packages/calcite-components/conventions/Accessibility/AccessibilityRoles.md b/packages/calcite-components/conventions/Accessibility/AccessibilityRoles.md index e3f91fbcf47..a25b6360502 100644 --- a/packages/calcite-components/conventions/Accessibility/AccessibilityRoles.md +++ b/packages/calcite-components/conventions/Accessibility/AccessibilityRoles.md @@ -1,17 +1,51 @@ # Roles -1. [Widget Roles](#1-widget-roles) -2. [Abstract Roles](#2-abstract-roles) -3. [Composite Roles](#3-composite-roles) - - i. [combobox](#i-combobox) - - ii. [grid](#ii-grid) - - iii. [listbox](#iii-listbox) - - iv. [menu](#iv-menu) - - v. [menubar](#v-menubar) - - vi. [radiogroup](#vi-radiogroup) - - vii. [tablist](#vii-tablist) - - viii. [tree](#viii-tree) - - ix. [treegrid](#ix-treegrid) +
+ Table of Contents + +- [Roles](#roles) + - [1. Widget Roles](#1-widget-roles) + - [2. Abstract Roles](#2-abstract-roles) + - [3. Composite Roles](#3-composite-roles) + - [i. combobox](#i-combobox) + - [Combobox example](#combobox-example) + - [Combobox code](#combobox-code) + - [Keyboard functionality for Combobox](#keyboard-functionality-for-combobox) + - [ii. grid](#ii-grid) + - [Grid Example](#grid-example) + - [Grid Code](#grid-code) + - [Keyboard functionality for Grid](#keyboard-functionality-for-grid) + - [iii. listbox](#iii-listbox) + - [Listbox Example](#listbox-example) + - [Listbox Code](#listbox-code) + - [Keyboard functionality for Listbox](#keyboard-functionality-for-listbox) + - [iv. menu](#iv-menu) + - [Menu Example](#menu-example) + - [Menu Code](#menu-code) + - [Keyboard functionality for Menu](#keyboard-functionality-for-menu) + - [v. menubar](#v-menubar) + - [Menubar Example](#menubar-example) + - [Menubar Code](#menubar-code) + - [Keyboard functionality for Menubar](#keyboard-functionality-for-menubar) + - [vi. radiogroup](#vi-radiogroup) + - [Radiogroup Example](#radiogroup-example) + - [a. Radiogroup Code](#a-radiogroup-code) + - [b. Radiogroup Code in Semantic HTML](#b-radiogroup-code-in-semantic-html) + - [Keyboard functionality for Radiogroup](#keyboard-functionality-for-radiogroup) + - [vii. tablist](#vii-tablist) + - [Tablist Example](#tablist-example) + - [Tablist Code](#tablist-code) + - [Keyboard functionality for Tablist](#keyboard-functionality-for-tablist) + - [viii. tree](#viii-tree) + - [Tree Example](#tree-example) + - [Tree Code](#tree-code) + - [Keyboard functionality for Tree](#keyboard-functionality-for-tree) + - [ix. treegrid](#ix-treegrid) + - [Treegrid Example](#treegrid-example) + - [Treegrid Code](#treegrid-code) + - [Keyboard functionality for Treegrid](#keyboard-functionality-for-treegrid) + +
## 1. Widget Roles diff --git a/packages/calcite-components/conventions/README.md b/packages/calcite-components/conventions/README.md index e39cbb2a186..8ccd849b295 100644 --- a/packages/calcite-components/conventions/README.md +++ b/packages/calcite-components/conventions/README.md @@ -79,7 +79,7 @@ Only attach additional data to your event if that data cannot be determined from `` is also an example of this. The `event.details.tab` item contains the index of the selected tab or the tab name which cannot be easily determined from the state of `` in some cases so it makes sense to include in the event. -### Native event cancelation +### Native event cancellation When a component **handles events for its own interaction** (e.g., moving between list items, closing an open menu), if the event is tied to default browser behavior (e.g., space key scrolling the page), `Event.preventDefault()` must be called to avoid mixed behavior. @@ -421,22 +421,22 @@ For such cases, the following pattern will enable developers to create custom ch - Must provide a `customItemSelectors` property to allow querying for custom elements in addition to their expected children. - An interface for the class (used by custom item classes) and element (used by parent component APIs) must be created in the parent's `interfaces.d.ts` file, where the necessary child APIs must be extracted. -**Example** +##### Example -**`parent/interfaces.d.ts`** +###### `parent/interfaces.d.ts` ```ts type ChildComponentLike = Pick; type ChildComponentLikeElement = ChilcComponentLike & HTMLElement; ``` -**`parent/parent.tsx`** +###### `parent/parent.tsx` ```tsx @Prop() selectedItem: HTMLChildComponentElement | ChildComponentLikeElement; ``` -**`custom-item/custom-item.tsx`** +###### `custom-item/custom-item.tsx` ```tsx export class CustomItem implements ChildComponentLike { diff --git a/packages/calcite-components/package.json b/packages/calcite-components/package.json index 6aa79d65642..ce28f8d9c22 100644 --- a/packages/calcite-components/package.json +++ b/packages/calcite-components/package.json @@ -31,7 +31,7 @@ "lint": "concurrently npm:lint:*", "lint:html": "prettier --write \"**/*.html\" >/dev/null", "lint:json": "prettier --write \"**/*.json\" >/dev/null", - "lint:md": "markdownlint \"**/*.md\" --fix --ignore node_modules --disable MD024 MD013 MD041 MD033 && prettier --write \"**/*.md\" >/dev/null", + "lint:md": "markdownlint \"**/*.md\" --fix --dot --ignore-path .gitignore && prettier --write \"**/*.md\" >/dev/null", "lint:scss": "stylelint --fix \"src/**/*.scss\" && prettier --write \"**/*.scss\" >/dev/null", "lint:ts": "eslint --ext .ts,.tsx --fix . && prettier --write \"**/*.ts?(x)\" >/dev/null", "posttest": "npm run test:prerender", diff --git a/packages/calcite-components/src/components/accordion-item/readme.md b/packages/calcite-components/src/components/accordion-item/readme.md index c498ed3c1f5..64efb1018eb 100644 --- a/packages/calcite-components/src/components/accordion-item/readme.md +++ b/packages/calcite-components/src/components/accordion-item/readme.md @@ -17,9 +17,11 @@ A child component of `calcite-accordion`, where some behavior is inherited from ## Slots -| Slot | Description | -| ---- | ----------------------------------------------------------------------------- | -| | A slot for adding custom content, including nested `calcite-accordion-item`s. | +| Slot | Description | +| ----------------- | ------------------------------------------------------------------------------------------- | +| | A slot for adding custom content, including nested `calcite-accordion-item`s. | +| `"actions-end"` | A slot for adding `calcite-action`s or content to the end side of the component's header. | +| `"actions-start"` | A slot for adding `calcite-action`s or content to the start side of the component's header. | ## Dependencies diff --git a/packages/calcite-components/src/components/action-bar/readme.md b/packages/calcite-components/src/components/action-bar/readme.md index 5837c506c58..34339db97f7 100755 --- a/packages/calcite-components/src/components/action-bar/readme.md +++ b/packages/calcite-components/src/components/action-bar/readme.md @@ -8,25 +8,25 @@ The `calcite-action-bar` component is made up of multiple `calcite-action`s in t ## Usage -### Basic +### Actions-end -Renders `calcite-action`s that stick to the top of the bar. +The actions-end slot renders `calcite-action`s that stick to the end of the bar prior to the expand/collapse icon. ```html - - + + ``` -### Actions-end +### Basic -The actions-end slot renders `calcite-action`s that stick to the end of the bar prior to the expand/collapse icon. +Renders `calcite-action`s that stick to the top of the bar. ```html - - + + ``` @@ -47,12 +47,12 @@ Renders a group of `calcite-action`s contained in a `calcite-action-group`. Acti ```html - + - + @@ -61,15 +61,16 @@ Renders a group of `calcite-action`s contained in a `calcite-action-group`. Acti ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ---------------------------- | ------------ | -| `expandDisabled` | `expand-disabled` | When `true`, the expand-toggling behavior is disabled. | `boolean` | `false` | -| `expanded` | `expanded` | When `true`, the component is expanded. | `boolean` | `false` | -| `layout` | `layout` | The layout direction of the actions. | `"horizontal" \| "vertical"` | `"vertical"` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ActionBarMessages` | `undefined` | -| `overflowActionsDisabled` | `overflow-actions-disabled` | Disables automatically overflowing `calcite-action`s that won't fit into menus. | `boolean` | `false` | -| `position` | `position` | Arranges the component depending on the element's `dir` property. | `"end" \| "start"` | `undefined` | -| `scale` | `scale` | Specifies the size of the expand `calcite-action`. | `"l" \| "m" \| "s"` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------------- | --------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- | ------------ | +| `actionsEndGroupLabel` | `actions-end-group-label` | Specifies the accessible label for the last action-group. | `string` | `undefined` | +| `expandDisabled` | `expand-disabled` | When `true`, the expand-toggling behavior is disabled. | `boolean` | `false` | +| `expanded` | `expanded` | When `true`, the component is expanded. | `boolean` | `false` | +| `layout` | `layout` | The layout direction of the actions. | `"horizontal" \| "vertical"` | `"vertical"` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ expand?: string; collapse?: string; }` | `undefined` | +| `overflowActionsDisabled` | `overflow-actions-disabled` | Disables automatically overflowing `calcite-action`s that won't fit into menus. | `boolean` | `false` | +| `position` | `position` | Arranges the component depending on the element's `dir` property. | `"end" \| "start"` | `undefined` | +| `scale` | `scale` | Specifies the size of the expand `calcite-action`. | `"l" \| "m" \| "s"` | `undefined` | ## Events @@ -89,11 +90,12 @@ Type: `Promise` ## Slots -| Slot | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| | A slot for adding `calcite-action`s that will appear at the top of the component. | -| `"actions-end"` | A slot for adding `calcite-action`s that will appear at the bottom of the component, above the collapse/expand button. | -| `"expand-tooltip"` | A slot to set the `calcite-tooltip` for the expand toggle. | +| Slot | Description | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| | A slot for adding `calcite-action`s that will appear at the top of the component. | +| `"actions-end"` | A slot for adding `calcite-action`s that will appear at the end of the component, prior to the collapse/expand button. | +| `"bottom-actions"` | [Deprecated] Use the `"actions-end"` slot instead. A slot for adding `calcite-action`s that will appear at the bottom of the component, above the collapse/expand button. | +| `"expand-tooltip"` | A slot to set the `calcite-tooltip` for the expand toggle. | ## CSS Custom Properties diff --git a/packages/calcite-components/src/components/action-group/readme.md b/packages/calcite-components/src/components/action-group/readme.md index 442f3184180..3829e28254d 100755 --- a/packages/calcite-components/src/components/action-group/readme.md +++ b/packages/calcite-components/src/components/action-group/readme.md @@ -6,14 +6,26 @@ The `calcite-action-group` is a wrapper for multiple `calcite-action`s and house ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ----------------------------------------------------------------------- | -------------------------------------- | ------------ | -| `columns` | `columns` | Indicates number of columns. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | -| `expanded` | `expanded` | When `true`, the component is expanded. | `boolean` | `false` | -| `layout` | `layout` | Indicates the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"vertical"` | -| `menuOpen` | `menu-open` | When `true`, the `calcite-action-menu` is open. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ActionGroupMessages` | `undefined` | -| `scale` | `scale` | Specifies the size of the `calcite-action-menu`. | `"l" \| "m" \| "s"` | `undefined` | +| Property | Attribute | Description | Type | Default | +| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------ | +| `columns` | `columns` | Indicates number of columns. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +| `expanded` | `expanded` | When `true`, the component is expanded. | `boolean` | `false` | +| `label` | `label` | Specifies the label of the component. Required for accessibility. | `string` | `undefined` | +| `layout` | `layout` | **[DEPRECATED]** Use the `layout` property on the component's parent instead.

Indicates the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"vertical"` | +| `menuOpen` | `menu-open` | When `true`, the `calcite-action-menu` is open. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ more?: string; }` | `undefined` | +| `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | +| `scale` | `scale` | Specifies the size of the `calcite-action-menu`. | `"l" \| "m" \| "s"` | `undefined` | + +## Methods + +### `setFocus() => Promise` + +Sets focus on the component's first focusable element. + +#### Returns + +Type: `Promise` ## Slots @@ -25,9 +37,11 @@ The `calcite-action-group` is a wrapper for multiple `calcite-action`s and house ## CSS Custom Properties -| Name | Description | -| -------------------------------- | ---------------------------------------------------------------------------- | -| `--calcite-action-group-columns` | Sets number of grid-template-columns when the `layout` property is `"grid"`. | +| Name | Description | +| -------------------------------- | --------------------------------------------------------------------------------------- | +| `--calcite-action-group-columns` | Sets number of grid-template-columns when the `layout` property is `"grid"`. | +| `--calcite-action-group-gap` | Sets the gap (gutters) between rows and columns when the `layout` property is `"grid"`. | +| `--calcite-action-group-padding` | Sets the padding when the `layout` property is `"grid"`. | ## Dependencies diff --git a/packages/calcite-components/src/components/action-menu/readme.md b/packages/calcite-components/src/components/action-menu/readme.md index 3fb14fdce5f..46680498666 100644 --- a/packages/calcite-components/src/components/action-menu/readme.md +++ b/packages/calcite-components/src/components/action-menu/readme.md @@ -11,7 +11,7 @@ | `label` _(required)_ | `label` | Specifies the text string for the component. | `string` | `undefined` | | `open` | `open` | When `true`, the component is open. | `boolean` | `false` | | `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | -| `placement` | `placement` | Determines where the component will be positioned relative to the `referenceElement`. | `"auto" \| "top" \| "left" \| "right" \| "bottom-start" \| "leading-start" \| "bottom" \| "top-start" \| "top-end" \| "left-start" \| "left-end" \| "right-start" \| "right-end" \| "bottom-end" \| "auto-start" \| "auto-end" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `"auto"` | +| `placement` | `placement` | Determines where the component will be positioned relative to the `referenceElement`. | `"auto" \| "top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end" \| "auto-start" \| "auto-end" \| "leading-start" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `"auto"` | | `scale` | `scale` | Specifies the size of the component's trigger `calcite-action`. | `"l" \| "m" \| "s"` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/action-pad/readme.md b/packages/calcite-components/src/components/action-pad/readme.md index 31c0440b51b..23d07522622 100755 --- a/packages/calcite-components/src/components/action-pad/readme.md +++ b/packages/calcite-components/src/components/action-pad/readme.md @@ -24,13 +24,8 @@ Renders an action pad with a tooltip on the expand action. ```html + Let's expand -Expand - ``` ### With-grouping @@ -39,7 +34,7 @@ Renders a group of `calcite-action`s contained in a `calcite-action-group`. Acti ```html - + @@ -50,14 +45,15 @@ Renders a group of `calcite-action`s contained in a `calcite-action-group`. Acti ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ----------------------------------------------------------------------- | -------------------------------------- | ------------ | -| `expandDisabled` | `expand-disabled` | When `true`, the expand-toggling behavior is disabled. | `boolean` | `false` | -| `expanded` | `expanded` | When `true`, the component is expanded. | `boolean` | `false` | -| `layout` | `layout` | Indicates the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"vertical"` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ActionPadMessages` | `undefined` | -| `position` | `position` | Arranges the component depending on the element's `dir` property. | `"end" \| "start"` | `undefined` | -| `scale` | `scale` | Specifies the size of the expand `calcite-action`. | `"l" \| "m" \| "s"` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ---------------------- | ------------------------- | ----------------------------------------------------------------------- | ----------------------------------------- | ------------ | +| `actionsEndGroupLabel` | `actions-end-group-label` | Specifies the accessible label for the last action-group. | `string` | `undefined` | +| `expandDisabled` | `expand-disabled` | When `true`, the expand-toggling behavior is disabled. | `boolean` | `false` | +| `expanded` | `expanded` | When `true`, the component is expanded. | `boolean` | `false` | +| `layout` | `layout` | Indicates the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"vertical"` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ expand?: string; collapse?: string; }` | `undefined` | +| `position` | `position` | Arranges the component depending on the element's `dir` property. | `"end" \| "start"` | `undefined` | +| `scale` | `scale` | Specifies the size of the expand `calcite-action`. | `"l" \| "m" \| "s"` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/action/readme.md b/packages/calcite-components/src/components/action/readme.md index 0f4e39d7517..074b0c71773 100755 --- a/packages/calcite-components/src/components/action/readme.md +++ b/packages/calcite-components/src/components/action/readme.md @@ -42,22 +42,22 @@ Renders a `calcite-action` that displays only an icon. ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------- | -| `active` | `active` | When `true`, the component is highlighted. | `boolean` | `false` | -| `alignment` | `alignment` | Specifies the horizontal alignment of button elements with text content. | `"center" \| "end" \| "start"` | `undefined` | -| `appearance` | `appearance` | Specifies the appearance of the component. | `"solid" \| "transparent"` | `"solid"` | -| `compact` | `compact` | When `true`, the side padding of the component is reduced. Compact mode is used internally by components, e.g. `calcite-block-section`. | `boolean` | `false` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `icon` | `icon` | Specifies an icon to display. | `string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `indicator` | `indicator` | When `true`, displays a visual indicator. | `boolean` | `false` | -| `label` | `label` | Specifies the label of the component. If no label is provided, the label inherits what's provided for the `text` prop. | `string` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ActionMessages` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `text` _(required)_ | `text` | Specifies text that accompanies the icon. | `string` | `undefined` | -| `textEnabled` | `text-enabled` | Indicates whether the text is displayed. | `boolean` | `false` | +| Property | Attribute | Description | Type | Default | +| ------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------- | +| `active` | `active` | When `true`, the component is highlighted. | `boolean` | `false` | +| `alignment` | `alignment` | Specifies the horizontal alignment of button elements with text content. | `"center" \| "end" \| "start"` | `undefined` | +| `appearance` | `appearance` | Specifies the appearance of the component. | `"solid" \| "transparent"` | `"solid"` | +| `compact` | `compact` | When `true`, the side padding of the component is reduced. Compact mode is used internally by components, e.g. `calcite-block-section`. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `icon` | `icon` | Specifies an icon to display. | `string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `indicator` | `indicator` | When `true`, displays a visual indicator. | `boolean` | `false` | +| `label` | `label` | Specifies the label of the component. If no label is provided, the label inherits what's provided for the `text` prop. | `string` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ loading?: string; indicator?: string; }` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `text` _(required)_ | `text` | Specifies text that accompanies the icon. | `string` | `undefined` | +| `textEnabled` | `text-enabled` | Indicates whether the text is displayed. | `boolean` | `false` | ## Methods @@ -71,9 +71,10 @@ Type: `Promise` ## Slots -| Slot | Description | -| ---- | ----------------------------------- | -| | A slot for adding a `calcite-icon`. | +| Slot | Description | +| ----------- | -------------------------------------- | +| | A slot for adding a `calcite-icon`. | +| `"tooltip"` | A slot for adding a `calcite-tooltip`. | ## CSS Custom Properties @@ -90,6 +91,9 @@ Type: `Promise` - [calcite-action-menu](../action-menu) - [calcite-action-pad](../action-pad) - [calcite-flow-item](../flow-item) +- [calcite-list-item](../list-item) +- [calcite-menu-item](../menu-item) +- [calcite-navigation](../navigation) - [calcite-panel](../panel) - [calcite-pick-list-item](../pick-list-item) - [calcite-popover](../popover) @@ -112,6 +116,9 @@ graph TD; calcite-action-menu --> calcite-action calcite-action-pad --> calcite-action calcite-flow-item --> calcite-action + calcite-list-item --> calcite-action + calcite-menu-item --> calcite-action + calcite-navigation --> calcite-action calcite-panel --> calcite-action calcite-pick-list-item --> calcite-action calcite-popover --> calcite-action diff --git a/packages/calcite-components/src/components/alert/readme.md b/packages/calcite-components/src/components/alert/readme.md index 9825a6983dc..79c5b27ed63 100644 --- a/packages/calcite-components/src/components/alert/readme.md +++ b/packages/calcite-components/src/components/alert/readme.md @@ -18,19 +18,19 @@ A single instance of an alert. Multiple alerts will aggregate in a queue. ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | -| `autoClose` | `auto-close` | When `true`, the component closes automatically (recommended for passive, non-blocking alerts). | `boolean` | `false` | -| `autoCloseDuration` | `auto-close-duration` | Specifies the duration before the component automatically closes (only use with `autoClose`). | `"fast" \| "medium" \| "slow"` | `this.autoClose ? "medium" : null` | -| `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `kind` | `kind` | Specifies the kind of the component (will apply to top border and icon). | `"brand" \| "danger" \| "info" \| "success" \| "warning"` | `"brand"` | -| `label` _(required)_ | `label` | Specifies an accessible name for the component. | `string` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `AlertMessages` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | -| `placement` | `placement` | Specifies the placement of the component | `"bottom" \| "bottom-end" \| "bottom-start" \| "top" \| "top-end" \| "top-start"` | `"bottom"` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| Property | Attribute | Description | Type | Default | +| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `autoClose` | `auto-close` | When `true`, the component closes automatically (recommended for passive, non-blocking alerts). | `boolean` | `false` | +| `autoCloseDuration` | `auto-close-duration` | Specifies the duration before the component automatically closes (only use with `autoClose`). | `"fast" \| "medium" \| "slow"` | `"medium"` | +| `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `kind` | `kind` | Specifies the kind of the component (will apply to top border and icon). | `"brand" \| "danger" \| "info" \| "success" \| "warning"` | `"brand"` | +| `label` _(required)_ | `label` | Specifies an accessible name for the component. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | +| `placement` | `placement` | Specifies the placement of the component | `"bottom" \| "bottom-end" \| "bottom-start" \| "top" \| "top-end" \| "top-start"` | `"bottom"` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | ## Events diff --git a/packages/calcite-components/src/components/avatar/readme.md b/packages/calcite-components/src/components/avatar/readme.md index 23fa34e2be7..bc74ebadf60 100644 --- a/packages/calcite-components/src/components/avatar/readme.md +++ b/packages/calcite-components/src/components/avatar/readme.md @@ -39,16 +39,21 @@ When no thumbnail is provided, the avatar component will construct a useful plac ## Properties -| Property | Attribute | Description | Type | Default | -| ----------- | ----------- | --------------------------------------------------------------------------------- | ------------------- | ----------- | -| `fullName` | `full-name` | Specifies the full name of the user. | `string` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `thumbnail` | `thumbnail` | Specifies the `src` to an image (remember to add a token if the user is private). | `string` | `undefined` | -| `userId` | `user-id` | Specifies the unique id of the user. | `string` | `undefined` | -| `username` | `username` | Specifies the username of the user. | `string` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | +| `fullName` | `full-name` | Specifies the full name of the user. When `label` and `thumbnail` are not defined, specifies the accessible name for the component. | `string` | `undefined` | +| `label` | `label` | Specifies alternative text when `thumbnail` is defined, otherwise specifies an accessible label. | `string` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `thumbnail` | `thumbnail` | Specifies the `src` to an image (remember to add a token if the user is private). | `string` | `undefined` | +| `userId` | `user-id` | Specifies the unique id of the user. | `string` | `undefined` | +| `username` | `username` | Specifies the username of the user. | `string` | `undefined` | ## Dependencies +### Used by + +- [calcite-navigation-user](../navigation-user) + ### Depends on - [calcite-icon](../icon) @@ -58,6 +63,7 @@ When no thumbnail is provided, the avatar component will construct a useful plac ```mermaid graph TD; calcite-avatar --> calcite-icon + calcite-navigation-user --> calcite-avatar style calcite-avatar fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/block-section/readme.md b/packages/calcite-components/src/components/block-section/readme.md index 48728bfefc2..3ba41844617 100644 --- a/packages/calcite-components/src/components/block-section/readme.md +++ b/packages/calcite-components/src/components/block-section/readme.md @@ -6,13 +6,13 @@ The `calcite-block-section` component is a child element of `calcite-block`. Sec ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `BlockSectionMessages` | `undefined` | -| `open` | `open` | When `true`, expands the component and its contents. | `boolean` | `false` | -| `status` | `status` | Displays a status-related indicator icon. | `"idle" \| "invalid" \| "valid"` | `undefined` | -| `text` | `text` | The component header text. | `string` | `undefined` | -| `toggleDisplay` | `toggle-display` | Specifies the component's toggle display - `"button"` (selectable header), or `"switch"` (toggle switch). | `"button" \| "switch"` | `"button"` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ---------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------- | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ collapse?: string; expand?: string; }` | `undefined` | +| `open` | `open` | When `true`, expands the component and its contents. | `boolean` | `false` | +| `status` | `status` | Displays a status-related indicator icon. | `"idle" \| "invalid" \| "valid"` | `undefined` | +| `text` | `text` | The component header text. | `string` | `undefined` | +| `toggleDisplay` | `toggle-display` | Specifies the component's toggle display - `"button"` (selectable header), or `"switch"` (toggle switch). | `"button" \| "switch"` | `"button"` | ## Events @@ -20,6 +20,16 @@ The `calcite-block-section` component is a child element of `calcite-block`. Sec | --------------------------- | --------------------------------------- | ------------------- | | `calciteBlockSectionToggle` | Emits when the header has been clicked. | `CustomEvent` | +## Methods + +### `setFocus() => Promise` + +Sets focus on the component's first tabbable element. + +#### Returns + +Type: `Promise` + ## Slots | Slot | Description | @@ -31,6 +41,7 @@ The `calcite-block-section` component is a child element of `calcite-block`. Sec ### Depends on - [calcite-icon](../icon) +- [calcite-label](../label) - [calcite-switch](../switch) ### Graph @@ -38,6 +49,7 @@ The `calcite-block-section` component is a child element of `calcite-block`. Sec ```mermaid graph TD; calcite-block-section --> calcite-icon + calcite-block-section --> calcite-label calcite-block-section --> calcite-switch style calcite-block-section fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/block/readme.md b/packages/calcite-components/src/components/block/readme.md index 07b3ffb8c2b..f53ad3c933f 100644 --- a/packages/calcite-components/src/components/block/readme.md +++ b/packages/calcite-components/src/components/block/readme.md @@ -11,8 +11,12 @@ The `calcite-block` component is intended for displaying a heading and content. Renders a header and content that remains open - no collapsible option. ```html - -
Father or Son?
+ +
    +
  • The first species to be domesticated
    • +
  • Domesticated from wolves over 15,000 years ago
    • +
  • Adapted to human behavior performing many roles such as hunting, protection, military, therapy, etc.
    • +
``` @@ -30,7 +34,13 @@ Renders a header with a clickable icon to toggle the block open and closed. ```html - + +
    +
  • The first species to be domesticated
    • +
  • Domesticated from wolves over 15,000 years ago
    • +
  • Adapted to human behavior performing many roles such as hunting, protection, military, therapy, etc.
    • +
+ ``` @@ -39,7 +49,7 @@ Renders a header with a clickable icon to toggle the block open and closed. Renders a header and control with a slot for adding a single HTML element (in the header). ```html - + ``` @@ -49,31 +59,45 @@ Renders a header and control with a slot for adding a single HTML element (in th Renders a header and icon with the icon. ```html - -
🤯
+ +
🐕
 ``` ## Properties -| Property | Attribute | Description | Type | Default | -| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------- | -------------------------------- | ----------- | -| `collapsible` | `collapsible` | When `true`, the component is collapsible. | `boolean` | `false` | -| `description` | `description` | A description for the component, which displays below the heading. | `string` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `dragHandle` | `drag-handle` | When `true`, displays a drag handle in the header. | `boolean` | `false` | -| `heading` _(required)_ | `heading` | The component header text. | `string` | `undefined` | -| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `BlockMessages` | `undefined` | -| `open` | `open` | When `true`, expands the component and its contents. | `boolean` | `false` | -| `status` | `status` | Displays a status-related indicator icon. | `"idle" \| "invalid" \| "valid"` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ---------------------- | --------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------- | +| `collapsible` | `collapsible` | When `true`, the component is collapsible. | `boolean` | `false` | +| `description` | `description` | A description for the component, which displays below the heading. | `string` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `dragHandle` | `drag-handle` | When `true`, displays a drag handle in the header. | `boolean` | `false` | +| `heading` _(required)_ | `heading` | The component header text. | `string` | `undefined` | +| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ collapse?: string; expand?: string; loading?: string; options?: string; }` | `undefined` | +| `open` | `open` | When `true`, expands the component and its contents. | `boolean` | `false` | +| `status` | `status` | Displays a status-related indicator icon. | `"idle" \| "invalid" \| "valid"` | `undefined` | ## Events -| Event | Description | Type | -| -------------------- | --------------------------------------------- | ------------------- | -| `calciteBlockToggle` | Emits when the component's header is clicked. | `CustomEvent` | +| Event | Description | Type | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | +| `calciteBlockBeforeClose` | Fires when the component is requested to be closed and before the closing transition begins. | `CustomEvent` | +| `calciteBlockBeforeOpen` | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | `CustomEvent` | +| `calciteBlockClose` | Fires when the component is closed and animation is complete. | `CustomEvent` | +| `calciteBlockOpen` | Fires when the component is open and animation is complete. | `CustomEvent` | +| `calciteBlockToggle` | **[DEPRECATED]** use `openClose` events: `calciteBlock[Before]Open` and `calciteBlock[Before]Close` instead.

Emits when the component's header is clicked. | `CustomEvent` | + +## Methods + +### `setFocus() => Promise` + +Sets focus on the component's first tabbable element. + +#### Returns + +Type: `Promise` ## Slots @@ -95,9 +119,9 @@ Renders a header and icon with the icon. ### Depends on - [calcite-scrim](../scrim) +- [calcite-loader](../loader) - [calcite-icon](../icon) - [calcite-handle](../handle) -- [calcite-loader](../loader) - [calcite-action-menu](../action-menu) ### Graph @@ -105,9 +129,9 @@ Renders a header and icon with the icon. ```mermaid graph TD; calcite-block --> calcite-scrim + calcite-block --> calcite-loader calcite-block --> calcite-icon calcite-block --> calcite-handle - calcite-block --> calcite-loader calcite-block --> calcite-action-menu calcite-scrim --> calcite-loader calcite-handle --> calcite-icon diff --git a/packages/calcite-components/src/components/button/readme.md b/packages/calcite-components/src/components/button/readme.md index 1d814218174..3f6e5c149e3 100644 --- a/packages/calcite-components/src/components/button/readme.md +++ b/packages/calcite-components/src/components/button/readme.md @@ -55,33 +55,34 @@ Any additional attributes set on `` are passed to the internal ` I should reset the form (type reset) I should not submit the form (type button) - Submit + Submit ``` ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------- | -| `alignment` | `alignment` | Specifies the alignment of the component's elements. | `"center" \| "end" \| "icon-end-space-between" \| "icon-start-space-between" \| "space-between" \| "start"` | `"center"` | -| `appearance` | `appearance` | Specifies the appearance style of the component. | `"outline" \| "outline-fill" \| "solid" \| "transparent"` | `"solid"` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `href` | `href` | Specifies the URL of the linked resource, which can be set as an absolute or relative path. | `string` | `undefined` | -| `iconEnd` | `icon-end` | Specifies an icon to display at the end of the component. | `string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`). | `"both" \| "end" \| "start"` | `undefined` | -| `iconStart` | `icon-start` | Specifies an icon to display at the start of the component. | `string` | `undefined` | -| `kind` | `kind` | Specifies the kind of the component (will apply to border and background if applicable). | `"brand" \| "danger" \| "inverse" \| "neutral"` | `"brand"` | -| `label` | `label` | Accessible name for the component. | `string` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed and interaction is disabled. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ButtonMessages` | `undefined` | -| `name` | `name` | Specifies the name of the component on form submission. | `string` | `undefined` | -| `rel` | `rel` | Defines the relationship between the `href` value and the current document. | `string` | `undefined` | -| `round` | `round` | When `true`, adds a round style to the component. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `splitChild` | `split-child` | Specifies if the component is a child of a `calcite-split-button`. | `"primary" \| "secondary" \| boolean` | `false` | -| `target` | `target` | Specifies where to open the linked document defined in the `href` property. | `string` | `undefined` | -| `type` | `type` | Specifies the default behavior of the button. | `string` | `"button"` | -| `width` | `width` | Specifies the width of the component. | `"auto" \| "full" \| "half"` | `"auto"` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------- | +| `alignment` | `alignment` | Specifies the alignment of the component's elements. | `"center" \| "end" \| "icon-end-space-between" \| "icon-start-space-between" \| "space-between" \| "start"` | `"center"` | +| `appearance` | `appearance` | Specifies the appearance style of the component. | `"outline" \| "outline-fill" \| "solid" \| "transparent"` | `"solid"` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `href` | `href` | Specifies the URL of the linked resource, which can be set as an absolute or relative path. | `string` | `undefined` | +| `iconEnd` | `icon-end` | Specifies an icon to display at the end of the component. | `string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`). | `"both" \| "end" \| "start"` | `undefined` | +| `iconStart` | `icon-start` | Specifies an icon to display at the start of the component. | `string` | `undefined` | +| `kind` | `kind` | Specifies the kind of the component (will apply to border and background if applicable). | `"brand" \| "danger" \| "inverse" \| "neutral"` | `"brand"` | +| `label` | `label` | Accessible name for the component. | `string` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed and interaction is disabled. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ loading?: string; }` | `undefined` | +| `name` | `name` | Specifies the name of the component on form submission. | `string` | `undefined` | +| `rel` | `rel` | Defines the relationship between the `href` value and the current document. | `string` | `undefined` | +| `round` | `round` | When `true`, adds a round style to the component. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `splitChild` | `split-child` | Specifies if the component is a child of a `calcite-split-button`. | `"primary" \| "secondary" \| boolean` | `false` | +| `target` | `target` | Specifies where to open the linked document defined in the `href` property. | `string` | `undefined` | +| `type` | `type` | Specifies the default behavior of the button. | `string` | `"button"` | +| `width` | `width` | Specifies the width of the component. | `"auto" \| "full" \| "half"` | `"auto"` | ## Methods @@ -107,6 +108,7 @@ Type: `Promise` - [calcite-fab](../fab) - [calcite-inline-editable](../inline-editable) - [calcite-split-button](../split-button) +- [calcite-table](../table) ### Depends on @@ -123,6 +125,7 @@ graph TD; calcite-fab --> calcite-button calcite-inline-editable --> calcite-button calcite-split-button --> calcite-button + calcite-table --> calcite-button style calcite-button fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/card/readme.md b/packages/calcite-components/src/components/card/readme.md index bea5c421a51..f74c6f459ab 100644 --- a/packages/calcite-components/src/components/card/readme.md +++ b/packages/calcite-components/src/components/card/readme.md @@ -22,7 +22,7 @@ | Property | Attribute | Description | Type | Default | | ------------------- | -------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------- | | `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `CardMessages` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ select?: string; deselect?: string; loading?: string; }` | `undefined` | | `selectable` | `selectable` | When `true`, the component is selectable. | `boolean` | `false` | | `selected` | `selected` | When `true`, the component is selected. | `boolean` | `false` | | `thumbnailPosition` | `thumbnail-position` | Sets the placement of the thumbnail defined in the `thumbnail` slot. | `"block-end" \| "block-start" \| "inline-end" \| "inline-start"` | `"block-start"` | diff --git a/packages/calcite-components/src/components/checkbox/readme.md b/packages/calcite-components/src/components/checkbox/readme.md index 5da9b4edf3d..78ba267d225 100644 --- a/packages/calcite-components/src/components/checkbox/readme.md +++ b/packages/calcite-components/src/components/checkbox/readme.md @@ -19,22 +19,11 @@ ``` -### Hovered-with-calcite-label - -```html - - - To do - -``` - ### Indeterminate-with-native-label ```html - +Status + ``` ## Properties @@ -43,6 +32,7 @@ | --------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | | `checked` | `checked` | When `true`, the component is checked. | `boolean` | `false` | | `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | | `guid` | `guid` | The `id` attribute of the component. When omitted, a globally unique identifier is used. | `string` | `undefined` | | `indeterminate` | `indeterminate` | When `true`, the component is initially indeterminate, which is independent from its `checked` value. The state is visual only, and can look different across browsers. | `boolean` | `false` | | `name` | `name` | Specifies the name of the component on form submission. | `any` | `undefined` | diff --git a/packages/calcite-components/src/components/chip-group/readme.md b/packages/calcite-components/src/components/chip-group/readme.md index 1f9a2b74ef2..b316f3695c8 100644 --- a/packages/calcite-components/src/components/chip-group/readme.md +++ b/packages/calcite-components/src/components/chip-group/readme.md @@ -2,39 +2,61 @@ +## Usage + +### Basic + +```html + + Topographic + Navigation + Streets + Imagery + +``` + +### SinglePersist + +```html + + Topographic + Navigation + Streets + Imagery + +``` + ## Properties -| Property | Attribute | Description | Type | Default | -| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | -------- | -| `disabled` | `disabled` | When true, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectionMode` | `selection-mode` | Specifies the selection mode - "multiple" (allow any number of selected items), "single" (allow one selected item), or "single-persist" (allow and require one selected item). | `"multiple" \| "none" \| "single" \| "single-persist"` | `"none"` | +| Property | Attribute | Description | Type | Default | +| -------------------- | ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------- | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. Child `calcite-chip`s inherit the component's value. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteChipElement[]` | `[]` | +| `selectionMode` | `selection-mode` | Specifies the selection mode of the component. | `"multiple" \| "none" \| "single" \| "single-persist"` | `"none"` | ## Events -| Event | Description | Type | -| ------------------------ | -------------------------------------- | ---------------------------- | -| `calciteChipGroupChange` | emitted when the selected items change | `CustomEvent` | +| Event | Description | Type | +| ------------------------ | --------------------------------------------- | ------------------- | +| `calciteChipGroupSelect` | Emits when the component's selection changes. | `CustomEvent` | -## Slots +## Methods -| Slot | Description | -| ---- | ---------------------------------- | -| | A slot for adding `calcite-chip`s. | +### `setFocus() => Promise` -## Dependencies +Sets focus on the component's first focusable element. -### Used by +#### Returns -- [calcite-combobox](../combobox) +Type: `Promise` -### Graph +## Slots -```mermaid -graph TD; - calcite-combobox --> calcite-chip-group - style calcite-chip-group fill:#f9f,stroke:#333,stroke-width:4px -``` +| Slot | Description | +| ---- | ---------------------------------------------- | +| | A slot for adding one or more `calcite-chip`s. | --- diff --git a/packages/calcite-components/src/components/chip/readme.md b/packages/calcite-components/src/components/chip/readme.md index 16db6823357..5a17395d5e4 100644 --- a/packages/calcite-components/src/components/chip/readme.md +++ b/packages/calcite-components/src/components/chip/readme.md @@ -12,29 +12,33 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | ------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------- | -| `appearance` | `appearance` | Specifies the appearance style of the component. | `"outline" \| "outline-fill" \| "solid"` | `"solid"` | -| `closable` | `closable` | When `true`, a close button is added to the component. | `boolean` | `false` | -| `closed` | `closed` | When `true`, hides the component. | `boolean` | `false` | -| `icon` | `icon` | Specifies an icon to display. | `string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `kind` | `kind` | Specifies the kind of the component (will apply to border and background if applicable). | `"brand" \| "inverse" \| "neutral"` | `"neutral"` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ChipMessages` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` _(required)_ | `value` | The component's value. | `any` | `undefined` | +| Property | Attribute | Description | Type | Default | +| -------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ----------- | +| `appearance` | `appearance` | Specifies the appearance style of the component. | `"outline" \| "outline-fill" \| "solid"` | `"solid"` | +| `closable` | `closable` | When `true`, a close button is added to the component. | `boolean` | `false` | +| `closed` | `closed` | When `true`, hides the component. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `icon` | `icon` | Specifies an icon to display. | `string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `kind` | `kind` | Specifies the kind of the component (will apply to border and background if applicable). | `"brand" \| "inverse" \| "neutral"` | `"neutral"` | +| `label` | `label` | Accessible name for the component. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ dismissLabel?: string; }` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. When contained in a parent `calcite-chip-group` inherits the parent's `scale` value. | `"l" \| "m" \| "s"` | `"m"` | +| `selected` | `selected` | When `true`, the component is selected. | `boolean` | `false` | +| `value` _(required)_ | `value` | The component's value. | `any` | `undefined` | ## Events -| Event | Description | Type | -| ------------------ | --------------------------------------- | ------------------- | -| `calciteChipClose` | Fires when the close button is clicked. | `CustomEvent` | +| Event | Description | Type | +| ------------------- | ------------------------------------------------------- | ------------------- | +| `calciteChipClose` | Fires when the component's close button is selected. | `CustomEvent` | +| `calciteChipSelect` | Fires when the selected state of the component changes. | `CustomEvent` | ## Methods ### `setFocus() => Promise` -When `closable` is `true`, sets focus on the component's "close" button (the first focusable item). +Sets focus on the component. #### Returns @@ -54,6 +58,7 @@ Type: `Promise` - [calcite-alert](../alert) - [calcite-combobox](../combobox) - [calcite-rating](../rating) +- [calcite-table](../table) ### Depends on @@ -67,6 +72,7 @@ graph TD; calcite-alert --> calcite-chip calcite-combobox --> calcite-chip calcite-rating --> calcite-chip + calcite-table --> calcite-chip style calcite-chip fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/color-picker-hex-input/readme.md b/packages/calcite-components/src/components/color-picker-hex-input/readme.md index a8b36cd068d..7d658527dc8 100644 --- a/packages/calcite-components/src/components/color-picker-hex-input/readme.md +++ b/packages/calcite-components/src/components/color-picker-hex-input/readme.md @@ -4,13 +4,14 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -| `allowEmpty` | `allow-empty` | When `false`, an empty color (`null`) will be allowed as a `value`. Otherwise, a color value is enforced on the component. When `true`, a color value is enforced, and clearing the input or blurring will restore the last valid `value`. When `false`, an empty color (`null`) will be allowed as a `value`. | `boolean` | `false` | -| `hexLabel` | `hex-label` | Specifies accessible label for the input field. | `string` | `"Hex"` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` | `value` | The Hex value. | `string` | `normalizeHex(DEFAULT_COLOR.hex())` | +| Property | Attribute | Description | Type | Default | +| ----------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `allowEmpty` | `allow-empty` | When `false`, an empty color (`null`) will be allowed as a `value`. Otherwise, a color value is enforced on the component. When `true`, a color value is enforced, and clearing the input or blurring will restore the last valid `value`. When `false`, an empty color (`null`) will be allowed as a `value`. | `boolean` | `false` | +| `alphaChannel` | `alpha-channel` | When true, the component will allow updates to the color's alpha value. | `boolean` | `false` | +| `hexLabel` | `hex-label` | **[DEPRECATED]** use `messages` instead

Specifies accessible label for the input field. | `string` | `"Hex"` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `value` | `value` | The hex value. | `string` | `normalizeHex( hexify(DEFAULT_COLOR, this.alphaChannel), this.alphaChannel, true )` | ## Events @@ -36,17 +37,19 @@ Type: `Promise` ### Depends on -- [calcite-input](../input) -- [calcite-color-picker-swatch](../color-picker-swatch) +- [calcite-input-text](../input-text) +- [calcite-input-number](../input-number) ### Graph ```mermaid graph TD; - calcite-color-picker-hex-input --> calcite-input - calcite-color-picker-hex-input --> calcite-color-picker-swatch - calcite-input --> calcite-progress - calcite-input --> calcite-icon + calcite-color-picker-hex-input --> calcite-input-text + calcite-color-picker-hex-input --> calcite-input-number + calcite-input-text --> calcite-progress + calcite-input-text --> calcite-icon + calcite-input-number --> calcite-progress + calcite-input-number --> calcite-icon calcite-color-picker --> calcite-color-picker-hex-input style calcite-color-picker-hex-input fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/color-picker-swatch/readme.md b/packages/calcite-components/src/components/color-picker-swatch/readme.md index 0566fd943db..59dabac656f 100644 --- a/packages/calcite-components/src/components/color-picker-swatch/readme.md +++ b/packages/calcite-components/src/components/color-picker-swatch/readme.md @@ -15,14 +15,12 @@ ### Used by - [calcite-color-picker](../color-picker) -- [calcite-color-picker-hex-input](../color-picker-hex-input) ### Graph ```mermaid graph TD; calcite-color-picker --> calcite-color-picker-swatch - calcite-color-picker-hex-input --> calcite-color-picker-swatch style calcite-color-picker-swatch fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/color-picker/readme.md b/packages/calcite-components/src/components/color-picker/readme.md index f6729bbece5..f5a12f6af1f 100644 --- a/packages/calcite-components/src/components/color-picker/readme.md +++ b/packages/calcite-components/src/components/color-picker/readme.md @@ -12,19 +12,23 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | -| `allowEmpty` | `allow-empty` | When `false`, an empty color (`null`) will be allowed as a `value`. Otherwise, a color value is enforced on the component. When `true`, a color value is enforced, and clearing the input or blurring will restore the last valid `value`. When `false`, an empty color (`null`) will be allowed as a `value`. | `boolean` | `false` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `format` | `format` | The format of `value`. When `"auto"`, the format will be inferred from `value` when set. | `"auto" \| "hex" \| "hexa" \| "hsl" \| "hsl-css" \| "hsla" \| "hsla-css" \| "hsv" \| "hsva" \| "rgb" \| "rgb-css" \| "rgba" \| "rgba-css"` | `defaultFormat` | -| `hideChannels` | `hide-channels` | When `true`, hides the RGB/HSV channel inputs. | `boolean` | `false` | -| `hideHex` | `hide-hex` | When `true`, hides the Hex input. | `boolean` | `false` | -| `hideSaved` | `hide-saved` | When `true`, hides the saved colors section. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ColorPickerMessages` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `storageId` | `storage-id` | Specifies the storage ID for colors. | `string` | `undefined` | -| `value` | `value` | The component's value, where the value can be a CSS color string, or a RGB, HSL or HSV object. The type will be preserved as the color is updated. | `HSL \| HSL & ObjectWithAlpha \| HSV \| HSV & ObjectWithAlpha \| RGB \| RGB & ObjectWithAlpha \| string` | `defaultValue` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `allowEmpty` | `allow-empty` | When `true`, an empty color (`null`) will be allowed as a `value`. When `false`, a color value is enforced, and clearing the input or blurring will restore the last valid `value`. | `boolean` | `false` | +| `alphaChannel` | `alpha-channel` | When true, the component will allow updates to the color's alpha value. | `boolean` | `false` | +| `channelsDisabled` | `channels-disabled` | When true, hides the RGB/HSV channel inputs | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `format` | `format` | The format of `value`. When `"auto"`, the format will be inferred from `value` when set. | `"auto" \| "hex" \| "hexa" \| "hsl" \| "hsl-css" \| "hsla" \| "hsla-css" \| "hsv" \| "hsva" \| "rgb" \| "rgb-css" \| "rgba" \| "rgba-css"` | `"auto"` | +| `hexDisabled` | `hex-disabled` | When true, hides the hex input | `boolean` | `false` | +| `hideChannels` | `hide-channels` | **[DEPRECATED]** use `channelsDisabled` instead

When `true`, hides the RGB/HSV channel inputs. | `boolean` | `false` | +| `hideHex` | `hide-hex` | **[DEPRECATED]** use `hexDisabled` instead

When `true`, hides the hex input. | `boolean` | `false` | +| `hideSaved` | `hide-saved` | **[DEPRECATED]** use `savedDisabled` instead

When `true`, hides the saved colors section. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ b?: string; blue?: string; deleteColor?: string; g?: string; green?: string; h?: string; hsv?: string; hex?: string; hue?: string; noColor?: string; opacity?: string; r?: string; red?: string; rgb?: string; s?: string; saturation?: string; saveColor?: string; saved?: string; v?: string; value?: string; }` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `savedDisabled` | `saved-disabled` | When true, hides the saved colors section | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `storageId` | `storage-id` | Specifies the storage ID for colors. | `string` | `undefined` | +| `value` | `value` | The component's value, where the value can be a CSS color string, or a RGB, HSL or HSV object. The type will be preserved as the color is updated. | `HSL \| HSL & ObjectWithAlpha \| HSV \| HSV & ObjectWithAlpha \| RGB \| RGB & ObjectWithAlpha \| string` | `normalizeHex( hexify(DEFAULT_COLOR, this.alphaChannel) )` | ## Events @@ -49,12 +53,12 @@ Type: `Promise` - [calcite-tab-title](../tab-title) - [calcite-tab](../tab) -- [calcite-input](../input) +- [calcite-input-number](../input-number) +- [calcite-color-picker-swatch](../color-picker-swatch) - [calcite-color-picker-hex-input](../color-picker-hex-input) - [calcite-tabs](../tabs) - [calcite-tab-nav](../tab-nav) - [calcite-button](../button) -- [calcite-color-picker-swatch](../color-picker-swatch) ### Graph @@ -62,17 +66,19 @@ Type: `Promise` graph TD; calcite-color-picker --> calcite-tab-title calcite-color-picker --> calcite-tab - calcite-color-picker --> calcite-input + calcite-color-picker --> calcite-input-number + calcite-color-picker --> calcite-color-picker-swatch calcite-color-picker --> calcite-color-picker-hex-input calcite-color-picker --> calcite-tabs calcite-color-picker --> calcite-tab-nav calcite-color-picker --> calcite-button - calcite-color-picker --> calcite-color-picker-swatch calcite-tab-title --> calcite-icon - calcite-input --> calcite-progress - calcite-input --> calcite-icon - calcite-color-picker-hex-input --> calcite-input - calcite-color-picker-hex-input --> calcite-color-picker-swatch + calcite-input-number --> calcite-progress + calcite-input-number --> calcite-icon + calcite-color-picker-hex-input --> calcite-input-text + calcite-color-picker-hex-input --> calcite-input-number + calcite-input-text --> calcite-progress + calcite-input-text --> calcite-icon calcite-button --> calcite-loader calcite-button --> calcite-icon style calcite-color-picker fill:#f9f,stroke:#333,stroke-width:4px diff --git a/packages/calcite-components/src/components/combobox-item-group/readme.md b/packages/calcite-components/src/components/combobox-item-group/readme.md index f477263b0a0..1d74717a335 100644 --- a/packages/calcite-components/src/components/combobox-item-group/readme.md +++ b/packages/calcite-components/src/components/combobox-item-group/readme.md @@ -4,10 +4,10 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | --------- | --------------------------------------------------------------------------------------------------- | -------- | ----------- | -| `ancestors` | -- | Specifies the parent and grandparent `calcite-combobox-item`s, which are set on `calcite-combobox`. | `any[]` | `undefined` | -| `label` _(required)_ | `label` | Specifies the title of the component. | `string` | `undefined` | +| Property | Attribute | Description | Type | Default | +| -------------------- | --------- | --------------------------------------------------------------------------------------------------- | ------------------------ | ----------- | +| `ancestors` | -- | Specifies the parent and grandparent `calcite-combobox-item`s, which are set on `calcite-combobox`. | `ComboboxChildElement[]` | `undefined` | +| `label` _(required)_ | `label` | Specifies the title of the component. | `string` | `undefined` | ## Slots diff --git a/packages/calcite-components/src/components/combobox-item/readme.md b/packages/calcite-components/src/components/combobox-item/readme.md index 11cf119eb06..36d05a2006e 100644 --- a/packages/calcite-components/src/components/combobox-item/readme.md +++ b/packages/calcite-components/src/components/combobox-item/readme.md @@ -4,18 +4,18 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------------ | ----------------- | -------------------------------------------------------------------------------------------- | --------- | ----------- | -| `active` | `active` | When `true`, the component is active. | `boolean` | `false` | -| `ancestors` | -- | Specifies the parent and grandparent items, which are set on `calcite-combobox`. | `any[]` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `filterDisabled` | `filter-disabled` | When `true`, omits the component from the `calcite-combobox` filtered search results. | `boolean` | `undefined` | -| `guid` | `guid` | The `id` attribute of the component. When omitted, a globally unique identifier is used. | `string` | `guid()` | -| `icon` | `icon` | Specifies an icon to display. | `string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `selected` | `selected` | When `true`, the component is selected. | `boolean` | `false` | -| `textLabel` _(required)_ | `text-label` | The component's text. | `string` | `undefined` | -| `value` _(required)_ | `value` | The component's value. | `any` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------------ | ----------------- | -------------------------------------------------------------------------------------------- | ------------------------ | ----------- | +| `active` | `active` | When `true`, the component is active. | `boolean` | `false` | +| `ancestors` | -- | Specifies the parent and grandparent items, which are set on `calcite-combobox`. | `ComboboxChildElement[]` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `filterDisabled` | `filter-disabled` | When `true`, omits the component from the `calcite-combobox` filtered search results. | `boolean` | `undefined` | +| `guid` | `guid` | The `id` attribute of the component. When omitted, a globally unique identifier is used. | `string` | `guid()` | +| `icon` | `icon` | Specifies an icon to display. | `string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `selected` | `selected` | When `true`, the component is selected. | `boolean` | `false` | +| `textLabel` _(required)_ | `text-label` | The component's text. | `string` | `undefined` | +| `value` _(required)_ | `value` | The component's value. | `any` | `undefined` | ## Events @@ -31,6 +31,10 @@ ## Dependencies +### Used by + +- [calcite-input-time-zone](../input-time-zone) + ### Depends on - [calcite-icon](../icon) @@ -40,6 +44,7 @@ ```mermaid graph TD; calcite-combobox-item --> calcite-icon + calcite-input-time-zone --> calcite-combobox-item style calcite-combobox-item fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/combobox/readme.md b/packages/calcite-components/src/components/combobox/readme.md index 44e27821cb7..feb20053e60 100644 --- a/packages/calcite-components/src/components/combobox/readme.md +++ b/packages/calcite-components/src/components/combobox/readme.md @@ -53,27 +53,46 @@ ``` +### SinglePersist + +```html + + + + + + + + +``` + ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------ | -| `allowCustomValues` | `allow-custom-values` | When `true`, allows entry of custom values, which are not in the original set of items. | `boolean` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `filteredItems` | -- | Specifies the component's filtered items. | `HTMLCalciteComboboxItemElement[]` | `[]` | -| `flipPlacements` | -- | Defines the available placements that can be used when a flip occurs. | `Placement[]` | `undefined` | -| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | -| `maxItems` | `max-items` | Specifies the maximum number of `calcite-combobox-item`s (including nested children) to display before displaying a scrollbar. | `number` | `0` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ComboboxMessages` | `undefined` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | -| `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | -| `placeholder` | `placeholder` | Specifies the placeholder text for the input. | `string` | `undefined` | -| `placeholderIcon` | `placeholder-icon` | Specifies the placeholder icon for the input. | `string` | `undefined` | -| `placeholderIconFlipRtl` | `placeholder-icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteComboboxItemElement[]` | `[]` | -| `selectionMode` | `selection-mode` | specify the selection mode - multiple: allow any number of selected items (default) - single: only one selection) - ancestors: like multiple, but show ancestors of selected items as selected, only deepest children shown in chips | `"ancestors" \| "multiple" \| "single"` | `"multiple"` | -| `value` | `value` | The component's value(s) from the selected `calcite-combobox-item`(s). | `string \| string[]` | `null` | +| Property | Attribute | Description | Type | Default | +| ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------ | +| `allowCustomValues` | `allow-custom-values` | When `true`, allows entry of custom values, which are not in the original set of items. | `boolean` | `undefined` | +| `clearDisabled` | `clear-disabled` | When `true`, the value-clearing will be disabled. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `filteredItems` | -- | Specifies the component's filtered items. | `HTMLCalciteComboboxItemElement[]` | `[]` | +| `flipPlacements` | -- | Defines the available placements that can be used when a flip occurs. | `Placement[]` | `undefined` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | +| `maxItems` | `max-items` | Specifies the maximum number of `calcite-combobox-item`s (including nested children) to display before displaying a scrollbar. | `number` | `0` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ clear?: string; removeTag?: string; }` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | +| `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | +| `placeholder` | `placeholder` | Specifies the placeholder text for the input. | `string` | `undefined` | +| `placeholderIcon` | `placeholder-icon` | Specifies the placeholder icon for the input. | `string` | `undefined` | +| `placeholderIconFlipRtl` | `placeholder-icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteComboboxItemElement[]` | `[]` | +| `selectionMode` | `selection-mode` | Specifies the selection mode: - "multiple" allows any number of selected items (default), - "single" allows only one selection, - "single-persist" allow and require one open item, - "ancestors" is like multiple, but shows ancestors of selected items as selected, with only deepest children shown in chips. | `"ancestors" \| "multiple" \| "single" \| "single-persist"` | `"multiple"` | +| `value` | `value` | The component's value(s) from the selected `calcite-combobox-item`(s). | `string \| string[]` | `null` | ## Events @@ -119,6 +138,10 @@ Type: `Promise` ## Dependencies +### Used by + +- [calcite-input-time-zone](../input-time-zone) + ### Depends on - [calcite-chip](../chip) @@ -131,6 +154,7 @@ graph TD; calcite-combobox --> calcite-chip calcite-combobox --> calcite-icon calcite-chip --> calcite-icon + calcite-input-time-zone --> calcite-combobox style calcite-combobox fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/date-picker/readme.md b/packages/calcite-components/src/components/date-picker/readme.md index 2d9a4fefd58..26c913e073e 100644 --- a/packages/calcite-components/src/components/date-picker/readme.md +++ b/packages/calcite-components/src/components/date-picker/readme.md @@ -19,7 +19,11 @@ You can set a min and max range, as well as an initial value with ISO 8601 forma You can also add range property to activate date range mode. In this mode, you will have to set the value property directly on the component's instance to an array of date strings. ```html - + +``` + +```js +document.querySelector("calcite-date-picker").value = ["2020-01-03", "2020-01-05"]; ``` ## Properties @@ -31,7 +35,7 @@ You can also add range property to activate date range mode. In this mode, you w | `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | | `max` | `max` | Specifies the latest allowed date (`"yyyy-mm-dd"`). | `string` | `undefined` | | `maxAsDate` | -- | Specifies the latest allowed date as a full date object (`new Date("yyyy-mm-dd")`). | `Date` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `DatePickerMessages` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ nextMonth?: string; prevMonth?: string; year?: string; }` | `undefined` | | `min` | `min` | Specifies the earliest allowed date (`"yyyy-mm-dd"`). | `string` | `undefined` | | `minAsDate` | -- | Specifies the earliest allowed date as a full date object (`new Date("yyyy-mm-dd")`). | `Date` | `undefined` | | `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. This property cannot be dynamically changed. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | @@ -48,6 +52,16 @@ You can also add range property to activate date range mode. In this mode, you w | `calciteDatePickerChange` | Emits when a user changes the component's date. For `range` events, use `calciteDatePickerRangeChange`. | `CustomEvent` | | `calciteDatePickerRangeChange` | Emits when a user changes the component's date `range`. For components without `range` use `calciteDatePickerChange`. | `CustomEvent` | +## Methods + +### `setFocus() => Promise` + +Sets focus on the component's first focusable element. + +#### Returns + +Type: `Promise` + ## Dependencies ### Used by diff --git a/packages/calcite-components/src/components/dropdown-group/readme.md b/packages/calcite-components/src/components/dropdown-group/readme.md index 9464283d9ee..895d50cd9d2 100644 --- a/packages/calcite-components/src/components/dropdown-group/readme.md +++ b/packages/calcite-components/src/components/dropdown-group/readme.md @@ -4,11 +4,10 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| --------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ----------- | -| `groupTitle` | `group-title` | Specifies and displays a group title. | `string` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `undefined` | -| `selectionMode` | `selection-mode` | Specifies the component's selection mode, where `"multiple"` allows any number of (or no) selected `calcite-dropdown-item`s, `"single"` allows and requires one selected `calcite-dropdown-item`, and `"none"` does not allow selection on `calcite-dropdown-item`s. | `"multiple" \| "none" \| "single"` | `"single"` | +| Property | Attribute | Description | Type | Default | +| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ----------- | +| `groupTitle` | `group-title` | Specifies and displays a group title. | `string` | `undefined` | +| `selectionMode` | `selection-mode` | Specifies the selection mode for `calcite-dropdown-item` children, defaults to `single`: - `multiple` allows any number of selected items, - `single` allows only one selection (default), - `none` doesn't allow for any selection. | `"multiple" \| "none" \| "single"` | `"single"` | ## Slots diff --git a/packages/calcite-components/src/components/dropdown/readme.md b/packages/calcite-components/src/components/dropdown/readme.md index 63253d6f886..ce18fec25e2 100644 --- a/packages/calcite-components/src/components/dropdown/readme.md +++ b/packages/calcite-components/src/components/dropdown/readme.md @@ -8,45 +8,47 @@ A `calcite-dropdown` can be used to provide an absolutely positioned set of sele ### Basic +Every `calcite-dropdown-item` must have a parent `calcite-dropdown-group`. + ```html - Open Dropdown + Choose a fruit - Relevance - Date modified - Title + Apple + Orange + Banana ``` ### Disabling-close-on-select -You can choose to leave the dropdown open when an item is selected with the `close-on-select-disabled` attribute. Note that this will only apply when the `calcite-dropdown-group` selection mode is set to `single` or `multi` - dropdowns will always close when an item in `none` selection mode is selected. +You can choose to leave the Dropdown open when an item is selected with the `close-on-select-disabled` attribute. Note that this will only apply when the `calcite-dropdown-group`'s `selectionMode` is set to `"single"` or `"multiple"`. Dropdowns will always close when the `calcite-dropdown-group`'s `selectionMode` is `"none"`. ```html - Open dropdown - - Dropdown Item Content - Dropdown Item Content - Dropdown Item Content + Choose a fruit + + Apple + Orange + Banana ``` ### Groups -You can combine groups in a single dropdown, with varying selection modes: +You can combine groups in a single Dropdown, with different `selectionMode`s: ```html - Open Dropdown - + Add to cart + Apple Orange - Grape + Banana - + Asparagus Potato Yam @@ -94,6 +96,14 @@ Updates the position of the component. Type: `Promise` +### `setFocus() => Promise` + +Sets focus on the component's first focusable element. + +#### Returns + +Type: `Promise` + ## Slots | Slot | Description | diff --git a/packages/calcite-components/src/components/fab/readme.md b/packages/calcite-components/src/components/fab/readme.md index f3812c7f8c0..d6f0374dd82 100644 --- a/packages/calcite-components/src/components/fab/readme.md +++ b/packages/calcite-components/src/components/fab/readme.md @@ -14,15 +14,23 @@ Renders a `calcite-fab` that displays only an icon and a tooltip label. ### Loading-and-disabled -Renders a `calcite-fab` that is loading and disabled. +Renders a `calcite-fab` that is `loading` and `disabled`. ```html ``` +### Styling + +Configure styling for a `calcite-fab` to fit your UI and branding with the `appearance` and `kind` attributes/properties: + +```html + +``` + ### With-text -Renders a `calcite-fab` that displays text along side an icon and a tooltip label. +Renders a `calcite-fab` that displays text alongside an icon. ```html diff --git a/packages/calcite-components/src/components/filter/readme.md b/packages/calcite-components/src/components/filter/readme.md index e8a83fcca5f..b8de1c0fb86 100644 --- a/packages/calcite-components/src/components/filter/readme.md +++ b/packages/calcite-components/src/components/filter/readme.md @@ -4,15 +4,15 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `filteredItems` | -- | The component's resulting items after filtering. | `object[]` | `[]` | -| `items` | -- | Defines the items to filter. The component uses the values as the starting point, and returns items that contain the string entered in the input, using a partial match and recursive search. This property is needed to conduct filtering. | `object[]` | `[]` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `FilterMessages` | `undefined` | -| `placeholder` | `placeholder` | Specifies placeholder text for the input element. | `string` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` | `value` | The component's value. | `string` | `""` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------- | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `filteredItems` | -- | The component's resulting items after filtering. | `object[]` | `[]` | +| `items` | -- | Defines the items to filter. The component uses the values as the starting point, and returns items that contain the string entered in the input, using a partial match and recursive search. This property is needed to conduct filtering. | `object[]` | `[]` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ label?: string; clear?: string; }` | `undefined` | +| `placeholder` | `placeholder` | Specifies placeholder text for the input element. | `string` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `value` | `value` | The component's value. | `string` | `""` | ## Events @@ -22,6 +22,16 @@ ## Methods +### `filter(value?: string) => Promise` + +Performs a filter on the component. + +This method can be useful because filtering is delayed and asynchronous. + +#### Returns + +Type: `Promise` + ### `setFocus() => Promise` Sets focus on the component. diff --git a/packages/calcite-components/src/components/flow-item/readme.md b/packages/calcite-components/src/components/flow-item/readme.md index 728e3ce2cff..3d2b08bec13 100644 --- a/packages/calcite-components/src/components/flow-item/readme.md +++ b/packages/calcite-components/src/components/flow-item/readme.md @@ -4,18 +4,18 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | --------------------------------------------------------------------------------------------- | ---------------------------- | ----------- | -| `beforeBack` | -- | When provided, the method will be called before it is removed from its parent `calcite-flow`. | `() => Promise` | `undefined` | -| `closable` | `closable` | When `true`, displays a close button in the trailing side of the component's header. | `boolean` | `false` | -| `closed` | `closed` | When `true`, the component will be hidden. | `boolean` | `false` | -| `description` | `description` | A description for the component. | `string` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `heading` | `heading` | The component header text. | `string` | `undefined` | -| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `menuOpen` | `menu-open` | When `true`, the action menu items in the `header-menu-actions` slot are open. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `FlowItemMessages` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------- | +| `beforeBack` | -- | When provided, the method will be called before it is removed from its parent `calcite-flow`. | `() => Promise` | `undefined` | +| `closable` | `closable` | When `true`, displays a close button in the trailing side of the component's header. | `boolean` | `false` | +| `closed` | `closed` | When `true`, the component will be hidden. | `boolean` | `false` | +| `description` | `description` | A description for the component. | `string` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `heading` | `heading` | The component header text. | `string` | `undefined` | +| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `menuOpen` | `menu-open` | When `true`, the action menu items in the `header-menu-actions` slot are open. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ back?: string; close?: string; options?: string; }` | `undefined` | ## Events @@ -45,16 +45,23 @@ Type: `Promise` ## Slots -| Slot | Description | -| ------------------------ | ------------------------------------------------------------------------------------------- | -| | A slot for adding custom content. | -| `"fab"` | A slot for adding a `calcite-fab` (floating action button) to perform an action. | -| `"footer"` | A slot for adding custom content to the component's footer. | -| `"footer-actions"` | A slot for adding `calcite-button`s to the component's footer. | -| `"header-actions-end"` | A slot for adding `calcite-action`s or content to the end side of the component's header. | -| `"header-actions-start"` | A slot for adding `calcite-action`s or content to the start side of the component's header. | -| `"header-content"` | A slot for adding custom content to the component's header. | -| `"header-menu-actions"` | A slot for adding an overflow menu with `calcite-action`s inside a `calcite-dropdown`. | +| Slot | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------ | +| | A slot for adding custom content. | +| `"action-bar"` | A slot for adding a `calcite-action-bar` to the component. | +| `"fab"` | A slot for adding a `calcite-fab` (floating action button) to perform an action. | +| `"footer"` | A slot for adding custom content to the component's footer. | +| `"footer-actions"` | [Deprecated] Use the `"footer"` slot instead. A slot for adding `calcite-button`s to the component's footer. | +| `"header-actions-end"` | A slot for adding `calcite-action`s or content to the end side of the component's header. | +| `"header-actions-start"` | A slot for adding `calcite-action`s or content to the start side of the component's header. | +| `"header-content"` | A slot for adding custom content to the component's header. | +| `"header-menu-actions"` | A slot for adding an overflow menu with `calcite-action`s inside a `calcite-dropdown`. | + +## CSS Custom Properties + +| Name | Description | +| ------------------------------------ | ------------------------------------------------ | +| `--calcite-flow-item-footer-padding` | Specifies the padding of the component's footer. | ## Dependencies @@ -62,7 +69,6 @@ Type: `Promise` - [calcite-action](../action) - [calcite-panel](../panel) -- [calcite-tooltip](../tooltip) ### Graph @@ -70,7 +76,6 @@ Type: `Promise` graph TD; calcite-flow-item --> calcite-action calcite-flow-item --> calcite-panel - calcite-flow-item --> calcite-tooltip calcite-action --> calcite-loader calcite-action --> calcite-icon calcite-panel --> calcite-action diff --git a/packages/calcite-components/src/components/flow/readme.md b/packages/calcite-components/src/components/flow/readme.md index 1623380bce5..605b4801658 100644 --- a/packages/calcite-components/src/components/flow/readme.md +++ b/packages/calcite-components/src/components/flow/readme.md @@ -8,43 +8,111 @@ The `calcite-flow` component is a series of panels that provides a user with a w ### Basic -Renders a basic flow with a couple `calcite-panel`s. +Populate Flow with `calcite-flow-item`s to step inside a `calcite-panel` element with HTML and JavaScript: ```html - - - - - - - - + + + + + + + + + + + + + + + + + ``` -### Menu-actions-and-footer +```js +const flow = document.getElementById("example-flow"); +const items = document.querySelectorAll("calcite-list-item"); + +items?.forEach((item) => { + item.addEventListener("calciteListItemSelect", (event) => { + createFlowItem(event, event.target.label, event.target.description, false); + }); +}); + +function createFlowItem(event, title, description, isLastLevel) { + const newFlowItem = document.createElement("calcite-flow-item"); + newFlowItem.heading = !isLastLevel ? title : "Even more details"; + newFlowItem.description = !isLastLevel ? description : title; + + const block = document.createElement("calcite-block"); + block.open = true; + block.heading = "Details"; + newFlowItem.append(block); + + const notice = document.createElement("calcite-notice"); + notice.open = true; + notice.width = "full"; + block.append(notice); + + const noticeMessage = document.createElement("span"); + noticeMessage.slot = "message"; + noticeMessage.innerText = !isLastLevel ? `A new Flow Item for ${title}.` : "You've reached the end of the line."; + notice.append(noticeMessage); + + if (!isLastLevel) { + const button = document.createElement("calcite-button"); + button.slot = "footer"; + button.width = "full"; + button.innerText = "Move to a third Flow Item"; + button.addEventListener("click", (event) => createFlowItem(event, title, description, true)); + if (!isLastLevel) newFlowItem.append(button); + } + + flow.append(newFlowItem); +} +``` + +### Menu-actions-and-footer-actions -Renders a flow with menu-actions and footer in the form of buttons. +Renders a flow with `"header-actions-start"`, `"header-actions-end"`, `"header-menu-actions"`, `"fab"`, and `"footer"` slots. ```html - - - - - - - - + + + + + + + + + + Cancel + Next + + + + + ``` ## Methods -### `back() => Promise` +### `back() => Promise` Removes the currently active `calcite-flow-item`. #### Returns -Type: `Promise` +Type: `Promise` + +### `setFocus() => Promise` + +Sets focus on the component. + +#### Returns + +Type: `Promise` ## Slots diff --git a/packages/calcite-components/src/components/handle/readme.md b/packages/calcite-components/src/components/handle/readme.md index 3f5a01d7946..b51d9d8149b 100644 --- a/packages/calcite-components/src/components/handle/readme.md +++ b/packages/calcite-components/src/components/handle/readme.md @@ -4,15 +4,17 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ----------- | ------------ | ------------------------------------ | -------- | ---------- | -| `textTitle` | `text-title` | Value for the button title attribute | `string` | `"handle"` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------- | +| `dragHandle` | `drag-handle` | Value for the button title attribute | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ dragHandle?: string; dragHandleActive?: string; dragHandleChange?: string; dragHandleCommit?: string; dragHandleIdle?: string; }` | `undefined` | ## Events -| Event | Description | Type | -| -------------------- | ----------------------------------------------------------------------------- | -------------------------- | -| `calciteHandleNudge` | Emitted when the handle is activated and the up or down arrow key is pressed. | `CustomEvent` | +| Event | Description | Type | +| ----------------------------- | ----------------------------------------------------------------------------- | --------------------------- | +| `calciteHandleNudge` | Emitted when the handle is activated and the up or down arrow key is pressed. | `CustomEvent` | +| `calciteInternalHandleChange` | Emitted when the handle is activated or deactivated. | `CustomEvent` | ## Methods @@ -29,6 +31,7 @@ Type: `Promise` ### Used by - [calcite-block](../block) +- [calcite-list-item](../list-item) ### Depends on @@ -40,6 +43,7 @@ Type: `Promise` graph TD; calcite-handle --> calcite-icon calcite-block --> calcite-handle + calcite-list-item --> calcite-handle style calcite-handle fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/icon/readme.md b/packages/calcite-components/src/components/icon/readme.md index 5bdf2ed1870..fda0908d166 100644 --- a/packages/calcite-components/src/components/icon/readme.md +++ b/packages/calcite-components/src/components/icon/readme.md @@ -6,7 +6,7 @@ ### Custom-icon-color -To use a custom color for the icon fill, you can add a class to the `calcite-icon` component with the desired color. +To use a custom color for the icon fill, you can supply your desired color to the `--calcite-ui-icon-color` CSS variable: ```html @@ -14,7 +14,7 @@ To use a custom color for the icon fill, you can add a class to the `calcite-ico ```css .my-icon-color-class { - color: #007ac2; + --calcite-ui-icon-color: #007ac2; } ``` @@ -55,8 +55,10 @@ To use a custom color for the icon fill, you can add a class to the `calcite-ico - [calcite-input-message](../input-message) - [calcite-input-number](../input-number) - [calcite-input-text](../input-text) +- [calcite-input-time-picker](../input-time-picker) - [calcite-link](../link) - [calcite-list-item](../list-item) +- [calcite-menu-item](../menu-item) - [calcite-modal](../modal) - [calcite-notice](../notice) - [calcite-pagination](../pagination) @@ -67,6 +69,8 @@ To use a custom color for the icon fill, you can add a class to the `calcite-ico - [calcite-select](../select) - [calcite-stepper-item](../stepper-item) - [calcite-tab-title](../tab-title) +- [calcite-table-header](../table-header) +- [calcite-table-row](../table-row) - [calcite-tile](../tile) - [calcite-time-picker](../time-picker) - [calcite-tip-manager](../tip-manager) @@ -95,8 +99,10 @@ graph TD; calcite-input-message --> calcite-icon calcite-input-number --> calcite-icon calcite-input-text --> calcite-icon + calcite-input-time-picker --> calcite-icon calcite-link --> calcite-icon calcite-list-item --> calcite-icon + calcite-menu-item --> calcite-icon calcite-modal --> calcite-icon calcite-notice --> calcite-icon calcite-pagination --> calcite-icon @@ -107,6 +113,8 @@ graph TD; calcite-select --> calcite-icon calcite-stepper-item --> calcite-icon calcite-tab-title --> calcite-icon + calcite-table-header --> calcite-icon + calcite-table-row --> calcite-icon calcite-tile --> calcite-icon calcite-time-picker --> calcite-icon calcite-tip-manager --> calcite-icon diff --git a/packages/calcite-components/src/components/inline-editable/readme.md b/packages/calcite-components/src/components/inline-editable/readme.md index 2b3b2c38942..dbe5e7042b4 100644 --- a/packages/calcite-components/src/components/inline-editable/readme.md +++ b/packages/calcite-components/src/components/inline-editable/readme.md @@ -10,7 +10,7 @@ There is no need to set a theme or scale on the `` comp ```html - + ``` @@ -18,32 +18,34 @@ There is no need to set a theme or scale on the `` comp ```html - My great label - - + Survey name + + ``` ### With-save-and-cancel-controls +Add "Save" and "Cancel" controls: + ```html - + ``` ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ | ----------- | -| `afterConfirm` | -- | Specifies a callback to be executed prior to disabling editing via the controls. When provided, the component's loading state will be handled automatically. | `() => Promise` | `undefined` | -| `controls` | `controls` | When `true` and `editingEnabled` is `true`, displays save and cancel controls on the component. | `boolean` | `false` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `editingEnabled` | `editing-enabled` | When `true`, inline editing is enabled on the component. | `boolean` | `false` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `InlineEditableMessages` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. Defaults to the scale of the wrapped `calcite-input` or the scale of the closest wrapping component with a set scale. | `"l" \| "m" \| "s"` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ----------- | +| `afterConfirm` | -- | Specifies a callback to be executed prior to disabling editing via the controls. When provided, the component's loading state will be handled automatically. | `() => Promise` | `undefined` | +| `controls` | `controls` | When `true` and `editingEnabled` is `true`, displays save and cancel controls on the component. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `editingEnabled` | `editing-enabled` | When `true`, inline editing is enabled on the component. | `boolean` | `false` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ enableEditing?: string; cancelEditing?: string; confirmChanges?: string; }` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. Defaults to the scale of the wrapped `calcite-input` or the scale of the closest wrapping component with a set scale. | `"l" \| "m" \| "s"` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/input-date-picker/readme.md b/packages/calcite-components/src/components/input-date-picker/readme.md index be7d4292e2b..49c05c524f9 100644 --- a/packages/calcite-components/src/components/input-date-picker/readme.md +++ b/packages/calcite-components/src/components/input-date-picker/readme.md @@ -10,28 +10,36 @@
Date - +
``` +### Range + +Add a `range` to the component. To set the component's value use the JavaScript `value` property with an array of strings: + +```html + +``` + +```js +document.querySelector("calcite-input-date-picker").value = ["2023-10-01", "2023-11-30"]; +``` + ## Properties | Property | Attribute | Description | Type | Default | | ---------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | | `flipPlacements` | -- | Defines the available placements that can be used when a flip occurs. | `Placement[]` | `undefined` | +| `focusTrapDisabled` | `focus-trap-disabled` | When `true`, prevents focus trapping. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | | `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | | `layout` | `layout` | Defines the layout of the component. | `"horizontal" \| "vertical"` | `"horizontal"` | | `max` | `max` | Specifies the latest allowed date ("yyyy-mm-dd"). | `string` | `undefined` | | `maxAsDate` | -- | Specifies the latest allowed date as a full date object. | `Date` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `DatePickerMessages` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ chooseDate?: string; dateFormat?: string; nextMonth?: string; prevMonth?: string; year?: string; }` | `undefined` | | `min` | `min` | Specifies the earliest allowed date ("yyyy-mm-dd"). | `string` | `undefined` | | `minAsDate` | -- | Specifies the earliest allowed date as a full date object. | `Date` | `undefined` | | `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | diff --git a/packages/calcite-components/src/components/input-message/readme.md b/packages/calcite-components/src/components/input-message/readme.md index bb9dfec0bb4..6e0ae0de028 100644 --- a/packages/calcite-components/src/components/input-message/readme.md +++ b/packages/calcite-components/src/components/input-message/readme.md @@ -10,12 +10,12 @@ Displays a contextual message to a user. Allows the passing of content, links, e ```html - My great label - - That's not going to work out. - Learn more + Desired subdomain + + + + Excellent news - this domain is available. + ``` diff --git a/packages/calcite-components/src/components/input-number/readme.md b/packages/calcite-components/src/components/input-number/readme.md index 045f0c905db..94050497103 100644 --- a/packages/calcite-components/src/components/input-number/readme.md +++ b/packages/calcite-components/src/components/input-number/readme.md @@ -2,40 +2,61 @@ +## Usage + +### Basic + +```html + +``` + +### Integer + +Restrict the component to integer numbers only with `integer`, which will disable exponential notation. + +```html + + Birds observed + + +``` + ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -| `alignment` | `alignment` | Specifies the text alignment of the component's value. | `"end" \| "start"` | `"start"` | -| `autocomplete` | `autocomplete` | Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | -| `autofocus` | `autofocus` | When `true`, the component is focused on page load. | `boolean` | `false` | -| `clearable` | `clearable` | When `true`, a clear button is displayed when the component has a value. | `boolean` | `false` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `enterKeyHint` | `enter-key-hint` | Specifies the action label or icon for the Enter key on virtual keyboards. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | -| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | -| `hidden` | `hidden` | When `true`, the component will not be visible. | `boolean` | `false` | -| `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `inputMode` | `input-mode` | Specifies the type of content to help devices display an appropriate virtual keyboard. Read the native attribute's documentation on MDN for more info. | `string` | `"decimal"` | -| `label` | `label` | Accessible name for the component's button or hyperlink. | `string` | `undefined` | -| `loading` | `loading` | When `true`, the component is in the loading state and `calcite-progress` is displayed. | `boolean` | `false` | -| `max` | `max` | Specifies the maximum value. | `number` | `undefined` | -| `maxLength` | `max-length` | Specifies the maximum length of text for the component's value. | `number` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `InputNumberMessages` | `undefined` | -| `min` | `min` | Specifies the minimum value. | `number` | `undefined` | -| `minLength` | `min-length` | Specifies the minimum length of text for the component's value. | `number` | `undefined` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `numberButtonType` | `number-button-type` | Specifies the placement of the buttons. | `"horizontal" \| "none" \| "vertical"` | `"vertical"` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `placeholder` | `placeholder` | Specifies placeholder text for the component. | `string` | `undefined` | -| `prefixText` | `prefix-text` | Adds text to the start of the component. | `string` | `undefined` | -| `readOnly` | `read-only` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | -| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `status` | `status` | Specifies the status of the input field, which determines message and icons. | `"idle" \| "invalid" \| "valid"` | `"idle"` | -| `step` | `step` | Specifies the granularity that the component's value must adhere to. | `"any" \| number` | `undefined` | -| `suffixText` | `suffix-text` | Adds text to the end of the component. | `string` | `undefined` | -| `value` | `value` | The component's value. | `string` | `""` | +| Property | Attribute | Description | Type | Default | +| ------------------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | +| `alignment` | `alignment` | Specifies the text alignment of the component's value. | `"end" \| "start"` | `"start"` | +| `autocomplete` | `autocomplete` | Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | +| `autofocus` | `autofocus` | When `true`, the component is focused on page load. Only one element can contain `autofocus`. If multiple elements have `autofocus`, the first element will receive focus. | `boolean` | `false` | +| `clearable` | `clearable` | When `true`, a clear button is displayed when the component has a value. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `enterKeyHint` | `enter-key-hint` | Specifies the action label or icon for the Enter key on virtual keyboards. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | +| `hidden` | `hidden` | When `true`, the component will not be visible. | `boolean` | `false` | +| `icon` | `icon` | Specifies an icon to display. | `boolean \| string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `inputMode` | `input-mode` | Specifies the type of content to help devices display an appropriate virtual keyboard. Read the native attribute's documentation on MDN for more info. | `string` | `"decimal"` | +| `integer` | `integer` | When `true`, restricts the component to integer numbers only and disables exponential notation. | `boolean` | `false` | +| `label` | `label` | Accessible name for the component's button or hyperlink. | `string` | `undefined` | +| `loading` | `loading` | When `true`, the component is in the loading state and `calcite-progress` is displayed. | `boolean` | `false` | +| `max` | `max` | Specifies the maximum value. | `number` | `undefined` | +| `maxLength` | `max-length` | Specifies the maximum length of text for the component's value. | `number` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ clear?: string; loading?: string; }` | `undefined` | +| `min` | `min` | Specifies the minimum value. | `number` | `undefined` | +| `minLength` | `min-length` | Specifies the minimum length of text for the component's value. | `number` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `numberButtonType` | `number-button-type` | Specifies the placement of the buttons. | `"horizontal" \| "none" \| "vertical"` | `"vertical"` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `placeholder` | `placeholder` | Specifies placeholder text for the component. | `string` | `undefined` | +| `prefixText` | `prefix-text` | Adds text to the start of the component. | `string` | `undefined` | +| `readOnly` | `read-only` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | +| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `status` | `status` | Specifies the status of the input field, which determines message and icons. | `"idle" \| "invalid" \| "valid"` | `"idle"` | +| `step` | `step` | Specifies the granularity that the component's value must adhere to. | `"any" \| number` | `undefined` | +| `suffixText` | `suffix-text` | Adds text to the end of the component. | `string` | `undefined` | +| `value` | `value` | The component's value. | `string` | `""` | ## Events @@ -48,7 +69,7 @@ ### `selectText() => Promise` -Selects all text of the component's `value`. +Selects the text of the component's `value`. #### Returns @@ -70,6 +91,11 @@ Type: `Promise` ## Dependencies +### Used by + +- [calcite-color-picker](../color-picker) +- [calcite-color-picker-hex-input](../color-picker-hex-input) + ### Depends on - [calcite-progress](../progress) @@ -81,6 +107,8 @@ Type: `Promise` graph TD; calcite-input-number --> calcite-progress calcite-input-number --> calcite-icon + calcite-color-picker --> calcite-input-number + calcite-color-picker-hex-input --> calcite-input-number style calcite-input-number fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/input-text/readme.md b/packages/calcite-components/src/components/input-text/readme.md index 5bee3c2ee9f..879da52731b 100644 --- a/packages/calcite-components/src/components/input-text/readme.md +++ b/packages/calcite-components/src/components/input-text/readme.md @@ -2,35 +2,44 @@ +## Usage + +### Basic + +```html + +``` + ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ----------- | -| `alignment` | `alignment` | Specifies the text alignment of the component's value. | `"end" \| "start"` | `"start"` | -| `autocomplete` | `autocomplete` | Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | -| `autofocus` | `autofocus` | When `true`, the component is focused on page load. | `boolean` | `false` | -| `clearable` | `clearable` | When `true`, a clear button is displayed when the component has a value. | `boolean` | `false` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `enterKeyHint` | `enter-key-hint` | Specifies the action label or icon for the Enter key on virtual keyboards. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | -| `hidden` | `hidden` | When `true`, the component will not be visible. | `boolean` | `false` | -| `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `inputMode` | `input-mode` | Specifies the type of content to help devices display an appropriate virtual keyboard. Read the native attribute's documentation on MDN for more info. | `string` | `"text"` | -| `label` | `label` | Accessible name for the component's button or hyperlink. | `string` | `undefined` | -| `loading` | `loading` | When `true`, the component is in the loading state and `calcite-progress` is displayed. | `boolean` | `false` | -| `maxLength` | `max-length` | Specifies the maximum length of text for the component's value. | `number` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `InputTextMessages` | `undefined` | -| `minLength` | `min-length` | Specifies the minimum length of text for the component's value. | `number` | `undefined` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `pattern` | `pattern` | Specifies a regex pattern the component's `value` must match for validation. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | -| `placeholder` | `placeholder` | Specifies placeholder text for the component. | `string` | `undefined` | -| `prefixText` | `prefix-text` | Adds text to the start of the component. | `string` | `undefined` | -| `readOnly` | `read-only` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | -| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `status` | `status` | Specifies the status of the input field, which determines message and icons. | `"idle" \| "invalid" \| "valid"` | `"idle"` | -| `suffixText` | `suffix-text` | Adds text to the end of the component. | `string` | `undefined` | -| `value` | `value` | The component's value. | `string` | `""` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------- | +| `alignment` | `alignment` | Specifies the text alignment of the component's value. | `"end" \| "start"` | `"start"` | +| `autocomplete` | `autocomplete` | Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | +| `autofocus` | `autofocus` | When `true`, the component is focused on page load. Only one element can contain `autofocus`. If multiple elements have `autofocus`, the first element will receive focus. | `boolean` | `false` | +| `clearable` | `clearable` | When `true`, a clear button is displayed when the component has a value. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `enterKeyHint` | `enter-key-hint` | Specifies the action label or icon for the Enter key on virtual keyboards. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `hidden` | `hidden` | When `true`, the component will not be visible. | `boolean` | `false` | +| `icon` | `icon` | Specifies an icon to display. | `boolean \| string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `inputMode` | `input-mode` | Specifies the type of content to help devices display an appropriate virtual keyboard. Read the native attribute's documentation on MDN for more info. | `string` | `"text"` | +| `label` | `label` | Accessible name for the component's button or hyperlink. | `string` | `undefined` | +| `loading` | `loading` | When `true`, the component is in the loading state and `calcite-progress` is displayed. | `boolean` | `false` | +| `maxLength` | `max-length` | Specifies the maximum length of text for the component's value. | `number` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ clear?: string; loading?: string; }` | `undefined` | +| `minLength` | `min-length` | Specifies the minimum length of text for the component's value. | `number` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `pattern` | `pattern` | Specifies a regex pattern the component's `value` must match for validation. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | +| `placeholder` | `placeholder` | Specifies placeholder text for the component. | `string` | `undefined` | +| `prefixText` | `prefix-text` | Adds text to the start of the component. | `string` | `undefined` | +| `readOnly` | `read-only` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | +| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `status` | `status` | Specifies the status of the input field, which determines message and icons. | `"idle" \| "invalid" \| "valid"` | `"idle"` | +| `suffixText` | `suffix-text` | Adds text to the end of the component. | `string` | `undefined` | +| `value` | `value` | The component's value. | `string` | `""` | ## Events @@ -43,7 +52,7 @@ ### `selectText() => Promise` -Selects all text of the component's `value`. +Selects the text of the component's `value`. #### Returns @@ -65,6 +74,10 @@ Type: `Promise` ## Dependencies +### Used by + +- [calcite-color-picker-hex-input](../color-picker-hex-input) + ### Depends on - [calcite-progress](../progress) @@ -76,6 +89,7 @@ Type: `Promise` graph TD; calcite-input-text --> calcite-progress calcite-input-text --> calcite-icon + calcite-color-picker-hex-input --> calcite-input-text style calcite-input-text fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/input-time-picker/readme.md b/packages/calcite-components/src/components/input-time-picker/readme.md index 0d8bb686077..1fac6c3e97a 100644 --- a/packages/calcite-components/src/components/input-time-picker/readme.md +++ b/packages/calcite-components/src/components/input-time-picker/readme.md @@ -7,36 +7,42 @@ ### Basic ```html - + +``` + +### Fractional-seconds + +```html + ``` ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `messagesOverrides` | `messages-overrides` | Use this property to override individual strings used by the component. | `TimePickerMessages` | `undefined` | -| `name` | `name` | Specifies the name of the component on form submission. | `string` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `open` | `open` | When `true`, displays the `calcite-time-picker` component. | `boolean` | `false` | -| `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | -| `placement` | `placement` | Determines where the popover will be positioned relative to the input. | `"auto" \| "top" \| "left" \| "right" \| "bottom-start" \| "leading-start" \| "bottom" \| "top-start" \| "top-end" \| "left-start" \| "left-end" \| "right-start" \| "right-end" \| "bottom-end" \| "auto-start" \| "auto-end" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `"auto"` | -| `readOnly` | `read-only` | When `true`, the component's value can be read, but controls are not accessible and the value cannot be modified. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `step` | `step` | Specifies the granularity the component's `value` must adhere to (in seconds). | `number` | `60` | -| `value` | `value` | The component's value in UTC (always 24-hour format). | `string` | `null` | +| Property | Attribute | Description | Type | Default | +| -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `focusTrapDisabled` | `focus-trap-disabled` | When `true`, prevents focus trapping. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ chooseTime?: string; fractionalSecond?: string; fractionalSecondDown?: string; fractionalSecondUp?: string; hour?: string; hourDown?: string; hourUp?: string; meridiem?: string; meridiemDown?: string; meridiemUp?: string; minute?: string; minuteDown?: string; minuteUp?: string; second?: string; secondDown?: string; secondUp?: string; }` | `undefined` | +| `name` | `name` | Specifies the name of the component on form submission. | `string` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `open` | `open` | When `true`, displays the `calcite-time-picker` component. | `boolean` | `false` | +| `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | +| `placement` | `placement` | Determines where the popover will be positioned relative to the input. | `"auto" \| "top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end" \| "auto-start" \| "auto-end" \| "leading-start" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `"auto"` | +| `readOnly` | `read-only` | When `true`, the component's value can be read, but controls are not accessible and the value cannot be modified. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `step` | `step` | Specifies the granularity the component's `value` must adhere to (in seconds). | `number` | `60` | +| `value` | `value` | The time value in ISO (24-hour) format. | `string` | `null` | ## Events -| Event | Description | Type | -| ------------------------------ | --------------------------------------------------------------- | ------------------- | -| `calciteInputTimePickerChange` | Fires when the time value is changed as a result of user input. | `CustomEvent` | +| Event | Description | Type | +| ----------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- | +| `calciteInputTimePickerBeforeClose` | Fires when the component is requested to be closed and before the closing transition begins. | `CustomEvent` | +| `calciteInputTimePickerBeforeOpen` | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | `CustomEvent` | +| `calciteInputTimePickerChange` | Fires when the time value is changed as a result of user input. | `CustomEvent` | +| `calciteInputTimePickerClose` | Fires when the component is closed and animation is complete. | `CustomEvent` | +| `calciteInputTimePickerOpen` | Fires when the component is open and animation is complete. | `CustomEvent` | ## Methods @@ -63,6 +69,7 @@ Type: `Promise` - [calcite-input](../input) - [calcite-popover](../popover) - [calcite-time-picker](../time-picker) +- [calcite-icon](../icon) ### Graph @@ -71,6 +78,7 @@ graph TD; calcite-input-time-picker --> calcite-input calcite-input-time-picker --> calcite-popover calcite-input-time-picker --> calcite-time-picker + calcite-input-time-picker --> calcite-icon calcite-input --> calcite-progress calcite-input --> calcite-icon calcite-popover --> calcite-action diff --git a/packages/calcite-components/src/components/input-time-zone/readme.md b/packages/calcite-components/src/components/input-time-zone/readme.md index 251187524f8..d99a175436c 100644 --- a/packages/calcite-components/src/components/input-time-zone/readme.md +++ b/packages/calcite-components/src/components/input-time-zone/readme.md @@ -2,16 +2,27 @@ +## Usage + +### Basic + +```html + +``` + ## Properties | Property | Attribute | Description | Type | Default | | -------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ | | `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `maxItems` | `max-items` | Specifies the component's maximum number of options to display before displaying a scrollbar. | `number` | `0` | | `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ chooseTimeZone?: string; timeZoneLabel?: string; "Africa/Abidjan"?: string; "Africa/Accra"?: string; "Africa/Addis_Ababa"?: string; "Africa/Algiers"?: string; "Africa/Asmera"?: string; "Africa/Bamako"?: string; "Africa/Bangui"?: string; "Africa/Banjul"?: string; "Africa/Bissau"?: string; "Africa/Blantyre"?: string; "Africa/Brazzaville"?: string; "Africa/Bujumbura"?: string; "Africa/Cairo"?: string; "Africa/Casablanca"?: string; "Africa/Ceuta"?: string; "Africa/Conakry"?: string; "Africa/Dakar"?: string; "Africa/Dar_es_Salaam"?: string; "Africa/Djibouti"?: string; "Africa/Douala"?: string; "Africa/El_Aaiun"?: string; "Africa/Freetown"?: string; "Africa/Gaborone"?: string; "Africa/Harare"?: string; "Africa/Johannesburg"?: string; "Africa/Juba"?: string; "Africa/Kampala"?: string; "Africa/Khartoum"?: string; "Africa/Kigali"?: string; "Africa/Kinshasa"?: string; "Africa/Lagos"?: string; "Africa/Libreville"?: string; "Africa/Lome"?: string; "Africa/Luanda"?: string; "Africa/Lubumbashi"?: string; "Africa/Lusaka"?: string; "Africa/Malabo"?: string; "Africa/Maputo"?: string; "Africa/Maseru"?: string; "Africa/Mbabane"?: string; "Africa/Mogadishu"?: string; "Africa/Monrovia"?: string; "Africa/Nairobi"?: string; "Africa/Ndjamena"?: string; "Africa/Niamey"?: string; "Africa/Nouakchott"?: string; "Africa/Ouagadougou"?: string; "Africa/Porto-Novo"?: string; "Africa/Sao_Tome"?: string; "Africa/Tripoli"?: string; "Africa/Tunis"?: string; "Africa/Windhoek"?: string; "America/Adak"?: string; "America/Anchorage"?: string; "America/Anguilla"?: string; "America/Antigua"?: string; "America/Araguaina"?: string; "America/Argentina/La_Rioja"?: string; "America/Argentina/Rio_Gallegos"?: string; "America/Argentina/Salta"?: string; "America/Argentina/San_Juan"?: string; "America/Argentina/San_Luis"?: string; "America/Argentina/Tucuman"?: string; "America/Argentina/Ushuaia"?: string; "America/Aruba"?: string; "America/Asuncion"?: string; "America/Bahia"?: string; "America/Bahia_Banderas"?: string; "America/Barbados"?: string; "America/Belem"?: string; "America/Belize"?: string; "America/Blanc-Sablon"?: string; "America/Boa_Vista"?: string; "America/Bogota"?: string; "America/Boise"?: string; "America/Buenos_Aires"?: string; "America/Cambridge_Bay"?: string; "America/Campo_Grande"?: string; "America/Cancun"?: string; "America/Caracas"?: string; "America/Catamarca"?: string; "America/Cayenne"?: string; "America/Cayman"?: string; "America/Chicago"?: string; "America/Chihuahua"?: string; "America/Ciudad_Juarez"?: string; "America/Coral_Harbour"?: string; "America/Cordoba"?: string; "America/Costa_Rica"?: string; "America/Creston"?: string; "America/Cuiaba"?: string; "America/Curacao"?: string; "America/Danmarkshavn"?: string; "America/Dawson"?: string; "America/Dawson_Creek"?: string; "America/Denver"?: string; "America/Detroit"?: string; "America/Dominica"?: string; "America/Edmonton"?: string; "America/Eirunepe"?: string; "America/El_Salvador"?: string; "America/Fort_Nelson"?: string; "America/Fortaleza"?: string; "America/Glace_Bay"?: string; "America/Godthab"?: string; "America/Goose_Bay"?: string; "America/Grand_Turk"?: string; "America/Grenada"?: string; "America/Guadeloupe"?: string; "America/Guatemala"?: string; "America/Guayaquil"?: string; "America/Guyana"?: string; "America/Halifax"?: string; "America/Havana"?: string; "America/Hermosillo"?: string; "America/Indiana/Knox"?: string; "America/Indiana/Marengo"?: string; "America/Indiana/Petersburg"?: string; "America/Indiana/Tell_City"?: string; "America/Indiana/Vevay"?: string; "America/Indiana/Vincennes"?: string; "America/Indiana/Winamac"?: string; "America/Indianapolis"?: string; "America/Inuvik"?: string; "America/Iqaluit"?: string; "America/Jamaica"?: string; "America/Jujuy"?: string; "America/Juneau"?: string; "America/Kentucky/Monticello"?: string; "America/Kralendijk"?: string; "America/La_Paz"?: string; "America/Lima"?: string; "America/Los_Angeles"?: string; "America/Louisville"?: string; "America/Lower_Princes"?: string; "America/Maceio"?: string; "America/Managua"?: string; "America/Manaus"?: string; "America/Marigot"?: string; "America/Martinique"?: string; "America/Matamoros"?: string; "America/Mazatlan"?: string; "America/Mendoza"?: string; "America/Menominee"?: string; "America/Merida"?: string; "America/Metlakatla"?: string; "America/Mexico_City"?: string; "America/Miquelon"?: string; "America/Moncton"?: string; "America/Monterrey"?: string; "America/Montevideo"?: string; "America/Montreal"?: string; "America/Montserrat"?: string; "America/Nassau"?: string; "America/New_York"?: string; "America/Nipigon"?: string; "America/Nome"?: string; "America/Noronha"?: string; "America/North_Dakota/Beulah"?: string; "America/North_Dakota/Center"?: string; "America/North_Dakota/New_Salem"?: string; "America/Ojinaga"?: string; "America/Panama"?: string; "America/Pangnirtung"?: string; "America/Paramaribo"?: string; "America/Phoenix"?: string; "America/Port-au-Prince"?: string; "America/Port_of_Spain"?: string; "America/Porto_Velho"?: string; "America/Puerto_Rico"?: string; "America/Punta_Arenas"?: string; "America/Rainy_River"?: string; "America/Rankin_Inlet"?: string; "America/Recife"?: string; "America/Regina"?: string; "America/Resolute"?: string; "America/Rio_Branco"?: string; "America/Santa_Isabel"?: string; "America/Santarem"?: string; "America/Santiago"?: string; "America/Santo_Domingo"?: string; "America/Sao_Paulo"?: string; "America/Scoresbysund"?: string; "America/Sitka"?: string; "America/St_Barthelemy"?: string; "America/St_Johns"?: string; "America/St_Kitts"?: string; "America/St_Lucia"?: string; "America/St_Thomas"?: string; "America/St_Vincent"?: string; "America/Swift_Current"?: string; "America/Tegucigalpa"?: string; "America/Thule"?: string; "America/Thunder_Bay"?: string; "America/Tijuana"?: string; "America/Toronto"?: string; "America/Tortola"?: string; "America/Vancouver"?: string; "America/Whitehorse"?: string; "America/Winnipeg"?: string; "America/Yakutat"?: string; "America/Yellowknife"?: string; "Antarctica/Casey"?: string; "Antarctica/Davis"?: string; "Antarctica/DumontDUrville"?: string; "Antarctica/Macquarie"?: string; "Antarctica/Mawson"?: string; "Antarctica/McMurdo"?: string; "Antarctica/Palmer"?: string; "Antarctica/Rothera"?: string; "Antarctica/Syowa"?: string; "Antarctica/Troll"?: string; "Antarctica/Vostok"?: string; "Arctic/Longyearbyen"?: string; "Asia/Aden"?: string; "Asia/Almaty"?: string; "Asia/Amman"?: string; "Asia/Anadyr"?: string; "Asia/Aqtau"?: string; "Asia/Aqtobe"?: string; "Asia/Ashgabat"?: string; "Asia/Atyrau"?: string; "Asia/Baghdad"?: string; "Asia/Bahrain"?: string; "Asia/Baku"?: string; "Asia/Bangkok"?: string; "Asia/Barnaul"?: string; "Asia/Beirut"?: string; "Asia/Bishkek"?: string; "Asia/Brunei"?: string; "Asia/Calcutta"?: string; "Asia/Chita"?: string; "Asia/Choibalsan"?: string; "Asia/Colombo"?: string; "Asia/Damascus"?: string; "Asia/Dhaka"?: string; "Asia/Dili"?: string; "Asia/Dubai"?: string; "Asia/Dushanbe"?: string; "Asia/Famagusta"?: string; "Asia/Gaza"?: string; "Asia/Hebron"?: string; "Asia/Hong_Kong"?: string; "Asia/Hovd"?: string; "Asia/Irkutsk"?: string; "Asia/Jakarta"?: string; "Asia/Jayapura"?: string; "Asia/Jerusalem"?: string; "Asia/Kabul"?: string; "Asia/Kamchatka"?: string; "Asia/Karachi"?: string; "Asia/Katmandu"?: string; "Asia/Khandyga"?: string; "Asia/Krasnoyarsk"?: string; "Asia/Kuala_Lumpur"?: string; "Asia/Kuching"?: string; "Asia/Kuwait"?: string; "Asia/Macau"?: string; "Asia/Magadan"?: string; "Asia/Makassar"?: string; "Asia/Manila"?: string; "Asia/Muscat"?: string; "Asia/Nicosia"?: string; "Asia/Novokuznetsk"?: string; "Asia/Novosibirsk"?: string; "Asia/Omsk"?: string; "Asia/Oral"?: string; "Asia/Phnom_Penh"?: string; "Asia/Pontianak"?: string; "Asia/Pyongyang"?: string; "Asia/Qatar"?: string; "Asia/Qostanay"?: string; "Asia/Qyzylorda"?: string; "Asia/Rangoon"?: string; "Asia/Riyadh"?: string; "Asia/Saigon"?: string; "Asia/Sakhalin"?: string; "Asia/Samarkand"?: string; "Asia/Seoul"?: string; "Asia/Shanghai"?: string; "Asia/Singapore"?: string; "Asia/Srednekolymsk"?: string; "Asia/Taipei"?: string; "Asia/Tashkent"?: string; "Asia/Tbilisi"?: string; "Asia/Tehran"?: string; "Asia/Thimphu"?: string; "Asia/Tokyo"?: string; "Asia/Tomsk"?: string; "Asia/Ulaanbaatar"?: string; "Asia/Urumqi"?: string; "Asia/Ust-Nera"?: string; "Asia/Vientiane"?: string; "Asia/Vladivostok"?: string; "Asia/Yakutsk"?: string; "Asia/Yekaterinburg"?: string; "Asia/Yerevan"?: string; "Atlantic/Azores"?: string; "Atlantic/Bermuda"?: string; "Atlantic/Canary"?: string; "Atlantic/Cape_Verde"?: string; "Atlantic/Faeroe"?: string; "Atlantic/Madeira"?: string; "Atlantic/Reykjavik"?: string; "Atlantic/South_Georgia"?: string; "Atlantic/St_Helena"?: string; "Atlantic/Stanley"?: string; "Australia/Adelaide"?: string; "Australia/Brisbane"?: string; "Australia/Broken_Hill"?: string; "Australia/Currie"?: string; "Australia/Darwin"?: string; "Australia/Eucla"?: string; "Australia/Hobart"?: string; "Australia/Lindeman"?: string; "Australia/Lord_Howe"?: string; "Australia/Melbourne"?: string; "Australia/Perth"?: string; "Australia/Sydney"?: string; "Europe/Amsterdam"?: string; "Europe/Andorra"?: string; "Europe/Astrakhan"?: string; "Europe/Athens"?: string; "Europe/Belgrade"?: string; "Europe/Berlin"?: string; "Europe/Bratislava"?: string; "Europe/Brussels"?: string; "Europe/Bucharest"?: string; "Europe/Budapest"?: string; "Europe/Busingen"?: string; "Europe/Chisinau"?: string; "Europe/Copenhagen"?: string; "Europe/Dublin"?: string; "Europe/Gibraltar"?: string; "Europe/Guernsey"?: string; "Europe/Helsinki"?: string; "Europe/Isle_of_Man"?: string; "Europe/Istanbul"?: string; "Europe/Jersey"?: string; "Europe/Kaliningrad"?: string; "Europe/Kiev"?: string; "Europe/Kirov"?: string; "Europe/Lisbon"?: string; "Europe/Ljubljana"?: string; "Europe/London"?: string; "Europe/Luxembourg"?: string; "Europe/Madrid"?: string; "Europe/Malta"?: string; "Europe/Mariehamn"?: string; "Europe/Minsk"?: string; "Europe/Monaco"?: string; "Europe/Moscow"?: string; "Europe/Oslo"?: string; "Europe/Paris"?: string; "Europe/Podgorica"?: string; "Europe/Prague"?: string; "Europe/Riga"?: string; "Europe/Rome"?: string; "Europe/Samara"?: string; "Europe/San_Marino"?: string; "Europe/Sarajevo"?: string; "Europe/Saratov"?: string; "Europe/Simferopol"?: string; "Europe/Skopje"?: string; "Europe/Sofia"?: string; "Europe/Stockholm"?: string; "Europe/Tallinn"?: string; "Europe/Tirane"?: string; "Europe/Ulyanovsk"?: string; "Europe/Uzhgorod"?: string; "Europe/Vaduz"?: string; "Europe/Vatican"?: string; "Europe/Vienna"?: string; "Europe/Vilnius"?: string; "Europe/Volgograd"?: string; "Europe/Warsaw"?: string; "Europe/Zagreb"?: string; "Europe/Zaporozhye"?: string; "Europe/Zurich"?: string; "Indian/Antananarivo"?: string; "Indian/Chagos"?: string; "Indian/Christmas"?: string; "Indian/Cocos"?: string; "Indian/Comoro"?: string; "Indian/Kerguelen"?: string; "Indian/Mahe"?: string; "Indian/Maldives"?: string; "Indian/Mauritius"?: string; "Indian/Mayotte"?: string; "Indian/Reunion"?: string; "Pacific/Apia"?: string; "Pacific/Auckland"?: string; "Pacific/Bougainville"?: string; "Pacific/Chatham"?: string; "Pacific/Easter"?: string; "Pacific/Efate"?: string; "Pacific/Enderbury"?: string; "Pacific/Fakaofo"?: string; "Pacific/Fiji"?: string; "Pacific/Funafuti"?: string; "Pacific/Galapagos"?: string; "Pacific/Gambier"?: string; "Pacific/Guadalcanal"?: string; "Pacific/Guam"?: string; "Pacific/Honolulu"?: string; "Pacific/Johnston"?: string; "Pacific/Kiritimati"?: string; "Pacific/Kosrae"?: string; "Pacific/Kwajalein"?: string; "Pacific/Majuro"?: string; "Pacific/Marquesas"?: string; "Pacific/Midway"?: string; "Pacific/Nauru"?: string; "Pacific/Niue"?: string; "Pacific/Norfolk"?: string; "Pacific/Noumea"?: string; "Pacific/Pago_Pago"?: string; "Pacific/Palau"?: string; "Pacific/Pitcairn"?: string; "Pacific/Ponape"?: string; "Pacific/Port_Moresby"?: string; "Pacific/Rarotonga"?: string; "Pacific/Saipan"?: string; "Pacific/Tahiti"?: string; "Pacific/Tarawa"?: string; "Pacific/Tongatapu"?: string; "Pacific/Truk"?: string; "Pacific/Wake"?: string; "Pacific/Wallis"?: string; }` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | | `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | | `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | | `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` | `value` | The component's value, where the value is the time zone offset or the difference, in minutes, between the selected time zone and UTC. If no value is provided, the user's time zone offset will be selected by default | `string` | `null` | +| `value` | `value` | The component's value, where the value is the time zone offset or the difference, in minutes, between the selected time zone and UTC. If no value is provided, the user's time zone offset will be selected by default. | `string` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/input/readme.md b/packages/calcite-components/src/components/input/readme.md index 139b7647e8d..f79126c163c 100644 --- a/packages/calcite-components/src/components/input/readme.md +++ b/packages/calcite-components/src/components/input/readme.md @@ -7,15 +7,17 @@ ### Basic ```html - + ``` ### Clearable +Display a clear button when the component has a value with the `clearable` attribute: + ```html - Clearable item - + Full name + ``` @@ -28,11 +30,14 @@ You must use `focusin`/`focusout` instead of `focus`/`blur` because these events All events return an element and a value: ```js -input.addEventListener("focusin", logFocus); -input.addEventListener("focusout", logBlur); +inputEl.addEventListener("focusin", logFocus); +inputEl.addEventListener("focusout", logBlur); + +function logFocus() { + console.log(event.target); +} -function logChange() { - console.log(event.target.element); +function logBlur() { console.log(event.target.value); } ``` @@ -50,10 +55,17 @@ function logChange() { ### With-message ```html - - My great label - - Here's something you should know about this input + + Desired subdomain + + + Apologies, this subdomain has already been registered. + ``` @@ -64,10 +76,12 @@ function logChange() { | `accept` | `accept` | Specifies a comma separated list of unique file type specifiers for limiting accepted file types. This property only has an effect when `type` is "file". Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | | `alignment` | `alignment` | Specifies the text alignment of the component's value. | `"end" \| "start"` | `"start"` | | `autocomplete` | `autocomplete` | Specifies the type of content to autocomplete, for use in forms. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | -| `autofocus` | `autofocus` | When `true`, the component is focused on page load. | `boolean` | `false` | +| `autofocus` | `autofocus` | When `true`, the component is focused on page load. Only one element can contain `autofocus`. If multiple elements have `autofocus`, the first element will receive focus. | `boolean` | `false` | | `clearable` | `clearable` | When `true`, a clear button is displayed when the component has a value. The clear button shows by default for `"search"`, `"time"`, and `"date"` types, and will not display for the `"textarea"` type. | `boolean` | `false` | | `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | | `enterKeyHint` | `enter-key-hint` | Specifies the action label or icon for the Enter key on virtual keyboards. Read the native attribute's documentation on MDN for more info. | `string` | `undefined` | +| `files` | -- | When `type` is `"file"`, specifies the component's selected files. | `FileList` | `undefined` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | | `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | | `hidden` | `hidden` | When `true`, the component will not be visible. | `boolean` | `false` | | `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | @@ -77,7 +91,7 @@ function logChange() { | `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | | `max` | `max` | Specifies the maximum value for type "number". | `number` | `undefined` | | `maxLength` | `max-length` | Specifies the maximum length of text for the component's value. | `number` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `InputMessages` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ clear?: string; loading?: string; }` | `undefined` | | `min` | `min` | Specifies the minimum value for `type="number"`. | `number` | `undefined` | | `minLength` | `min-length` | Specifies the minimum length of text for the component's value. | `number` | `undefined` | | `multiple` | `multiple` | When `true`, the component can accept more than one value. This property only has an effect when `type` is "email" or "file". Read the native attribute's documentation on MDN for more info. | `boolean` | `false` | @@ -107,7 +121,7 @@ function logChange() { ### `selectText() => Promise` -Selects all text of the component's `value`. +Selects the text of the component's `value`. #### Returns @@ -131,8 +145,6 @@ Type: `Promise` ### Used by -- [calcite-color-picker](../color-picker) -- [calcite-color-picker-hex-input](../color-picker-hex-input) - [calcite-filter](../filter) - [calcite-input-date-picker](../input-date-picker) - [calcite-input-time-picker](../input-time-picker) @@ -148,8 +160,6 @@ Type: `Promise` graph TD; calcite-input --> calcite-progress calcite-input --> calcite-icon - calcite-color-picker --> calcite-input - calcite-color-picker-hex-input --> calcite-input calcite-filter --> calcite-input calcite-input-date-picker --> calcite-input calcite-input-time-picker --> calcite-input diff --git a/packages/calcite-components/src/components/label/readme.md b/packages/calcite-components/src/components/label/readme.md index a344cdd742c..f22f44a1581 100644 --- a/packages/calcite-components/src/components/label/readme.md +++ b/packages/calcite-components/src/components/label/readme.md @@ -52,12 +52,14 @@ When using the `default`, `inline` or `inline-space-between` layout option with ### Used by +- [calcite-block-section](../block-section) - [calcite-card](../card) ### Graph ```mermaid graph TD; + calcite-block-section --> calcite-label calcite-card --> calcite-label style calcite-label fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/list-item-group/readme.md b/packages/calcite-components/src/components/list-item-group/readme.md index d1fa8f5ebdc..f1366a09705 100644 --- a/packages/calcite-components/src/components/list-item-group/readme.md +++ b/packages/calcite-components/src/components/list-item-group/readme.md @@ -9,6 +9,12 @@ | `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | | `heading` | `heading` | The header text for all nested `calcite-list-item` rows. | `string` | `undefined` | +## Events + +| Event | Description | Type | +| ----------------------------------------------- | -------------------------------------------------------------------------- | ------------------------ | +| `calciteInternalListItemGroupDefaultSlotChange` | Emitted when the default slot has changes in order to notify parent lists. | `CustomEvent` | + ## Slots | Slot | Description | diff --git a/packages/calcite-components/src/components/list-item/readme.md b/packages/calcite-components/src/components/list-item/readme.md index 6cd00e05d98..521362378b2 100644 --- a/packages/calcite-components/src/components/list-item/readme.md +++ b/packages/calcite-components/src/components/list-item/readme.md @@ -8,20 +8,24 @@ If you are looking for a list that handles more advanced usage like selection, s ## Properties -| Property | Attribute | Description | Type | Default | -| ------------- | ------------- | -------------------------------------------------------------------------------------------------------- | --------------------------- | ----------- | -| `description` | `description` | A description for the component. Displays below the label text. | `string` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `label` | `label` | The label text of the component. Displays above the description text. | `string` | `undefined` | -| `metadata` | -- | Provides additional metadata to the component. Primary use is for a filter on the parent `calcite-list`. | `{ [x: string]: unknown; }` | `undefined` | -| `open` | `open` | When `true`, the item is open to show child components. | `boolean` | `false` | -| `selected` | `selected` | When `true`, the component is selected. | `boolean` | `false` | -| `value` | `value` | The component's value. | `any` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ----------- | +| `closable` | `closable` | When `true`, a close button is added to the component. | `boolean` | `false` | +| `closed` | `closed` | When `true`, hides the component. | `boolean` | `false` | +| `description` | `description` | A description for the component. Displays below the label text. | `string` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `label` | `label` | The label text of the component. Displays above the description text. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | +| `metadata` | -- | Provides additional metadata to the component. Primary use is for a filter on the parent `calcite-list`. | `{ [x: string]: unknown; }` | `undefined` | +| `open` | `open` | When `true`, the item is open to show child components. | `boolean` | `false` | +| `selected` | `selected` | When `true` and the parent `calcite-list`'s `selectionMode` is `"single"`, `"single-persist"', or`"multiple"`, the component is selected. | `boolean` | `false` | +| `value` | `value` | The component's value. | `any` | `undefined` | ## Events | Event | Description | Type | | ----------------------- | ------------------------------------------ | ------------------- | +| `calciteListItemClose` | Fires when the close button is clicked. | `CustomEvent` | | `calciteListItemSelect` | Emits when the item's content is selected. | `CustomEvent` | ## Methods @@ -50,12 +54,19 @@ Type: `Promise` ### Depends on - [calcite-icon](../icon) +- [calcite-handle](../handle) +- [calcite-action](../action) ### Graph ```mermaid graph TD; calcite-list-item --> calcite-icon + calcite-list-item --> calcite-handle + calcite-list-item --> calcite-action + calcite-handle --> calcite-icon + calcite-action --> calcite-loader + calcite-action --> calcite-icon style calcite-list-item fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/list/readme.md b/packages/calcite-components/src/components/list/readme.md index f7081ad5f80..507f2663f61 100644 --- a/packages/calcite-components/src/components/list/readme.md +++ b/packages/calcite-components/src/components/list/readme.md @@ -77,6 +77,47 @@ A general purpose list that enables users to construct list items that conform t ``` +### DragEnabled + +```html + + + + + + + + + + + + + + +``` + +### DragEnabledNested + +```html + + + + + + + + + + + + + + + + + +``` + ### Grouped ```html @@ -122,25 +163,32 @@ A general purpose list that enables users to construct list items that conform t ## Properties -| Property | Attribute | Description | Type | Default | -| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- | ----------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `filterEnabled` | `filter-enabled` | When `true`, an input appears at the top of the component that can be used by end users to filter `calcite-list-item`s. | `boolean` | `false` | -| `filterPlaceholder` | `filter-placeholder` | Placeholder text for the component's filter input field. | `string` | `undefined` | -| `filterText` | `filter-text` | Text for the component's filter input field. | `string` | `undefined` | -| `filteredData` | -- | The currently filtered `calcite-list-item` data. | `{ label: string; description: string; metadata: Record; value: string; }[]` | `[]` | -| `filteredItems` | -- | The currently filtered `calcite-list-item`s. | `HTMLCalciteListItemElement[]` | `[]` | -| `label` | `label` | Specifies an accessible name for the component. | `string` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `selectedItems` | -- | The currently selected items. | `HTMLCalciteListItemElement[]` | `[]` | -| `selectionAppearance` | `selection-appearance` | Specifies the selection appearance - `"icon"` (displays a checkmark or dot) or `"border"` (displays a border). | `"border" \| "icon"` | `"icon"` | -| `selectionMode` | `selection-mode` | Specifies the selection mode - `"multiple"` (allow any number of selected items), `"single"` (allows and require one selected item), `"none"` (no selected items). | `"multiple" \| "none" \| "single"` | `"none"` | +| Property | Attribute | Description | Type | Default | +| --------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------- | +| `canPull` | -- | When provided, the method will be called to determine whether the element can move from the list. | `(detail: DragDetail) => boolean` | `undefined` | +| `canPut` | -- | When provided, the method will be called to determine whether the element can be added from another list. | `(detail: DragDetail) => boolean` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `dragEnabled` | `drag-enabled` | When `true`, `calcite-list-item`s are sortable via a draggable button. | `boolean` | `false` | +| `filterEnabled` | `filter-enabled` | When `true`, an input appears at the top of the component that can be used by end users to filter `calcite-list-item`s. | `boolean` | `false` | +| `filterPlaceholder` | `filter-placeholder` | Placeholder text for the component's filter input field. | `string` | `undefined` | +| `filterText` | `filter-text` | Text for the component's filter input field. | `string` | `undefined` | +| `filteredData` | -- | The currently filtered `calcite-list-item` data. | `{ label: string; description: string; metadata: Record; value: string; }[]` | `[]` | +| `filteredItems` | -- | The currently filtered `calcite-list-item`s. | `HTMLCalciteListItemElement[]` | `[]` | +| `group` | `group` | The list's group identifier. To drag elements from one list into another, both lists must have the same group value. | `string` | `undefined` | +| `label` | `label` | Specifies an accessible name for the component. | `string` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `selectedItems` | -- | The currently selected items. | `HTMLCalciteListItemElement[]` | `[]` | +| `selectionAppearance` | `selection-appearance` | Specifies the selection appearance - `"icon"` (displays a checkmark or dot) or `"border"` (displays a border). | `"border" \| "icon"` | `"icon"` | +| `selectionMode` | `selection-mode` | Specifies the selection mode - `"multiple"` (allow any number of selected items), `"single"` (allow one selected item), `"single-persist"` (allow one selected item and prevent de-selection), or `"none"` (no selected items). | `"multiple" \| "none" \| "single" \| "single-persist"` | `"none"` | ## Events -| Event | Description | Type | -| ------------------- | ---------------------------------------------- | ------------------- | -| `calciteListFilter` | Emits when the component's filter has changed. | `CustomEvent` | +| Event | Description | Type | +| -------------------------------------- | -------------------------------------------------------------------------- | ------------------------- | +| `calciteInternalListDefaultSlotChange` | Emitted when the default slot has changes in order to notify parent lists. | `CustomEvent` | +| `calciteListChange` | Emits when any of the list item selections have changed. | `CustomEvent` | +| `calciteListFilter` | Emits when the component's filter has changed. | `CustomEvent` | +| `calciteListOrderChange` | Emitted when the order of the list has changed. | `CustomEvent` | ## Methods @@ -154,15 +202,18 @@ Type: `Promise` ## Slots -| Slot | Description | -| ---- | ----------------------------------------------- | -| | A slot for adding `calcite-list-item` elements. | +| Slot | Description | +| ------------------------ | ----------------------------------------------------------------------------------- | +| | A slot for adding `calcite-list-item` elements. | +| `"filter-actions-end"` | A slot for adding actionable `calcite-action` elements after the filter component. | +| `"filter-actions-start"` | A slot for adding actionable `calcite-action` elements before the filter component. | ## Dependencies ### Depends on - [calcite-scrim](../scrim) +- [calcite-stack](../stack) - [calcite-filter](../filter) ### Graph @@ -170,6 +221,7 @@ Type: `Promise` ```mermaid graph TD; calcite-list --> calcite-scrim + calcite-list --> calcite-stack calcite-list --> calcite-filter calcite-scrim --> calcite-loader calcite-filter --> calcite-input diff --git a/packages/calcite-components/src/components/menu-item/readme.md b/packages/calcite-components/src/components/menu-item/readme.md index 108ee444acd..93fa5266afe 100644 --- a/packages/calcite-components/src/components/menu-item/readme.md +++ b/packages/calcite-components/src/components/menu-item/readme.md @@ -2,47 +2,28 @@ -## Usage - -### Basic - -```html - -``` - -### Nested-With-Href - -Nested submenu with href. - -```html - - - - - -``` - ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- | -| `active` | `active` | When `true`, the component is highlighted. | `boolean` | `undefined` | -| `breadcrumb` | `breadcrumb` | When true, the component displays a visual indication of breadcrumb | `boolean` | `undefined` | -| `href` | `href` | Specifies the URL destination of the component, which can be set as an absolute or relative path. | `string` | `undefined` | -| `iconEnd` | `icon-end` | Specifies an icon to display at the end of the component. | `string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`). | `"both" \| "end" \| "start"` | `undefined` | -| `iconStart` | `icon-start` | Specifies an icon to display at the start of the component. | `string` | `undefined` | -| `label` _(required)_ | `label` | Specifices accessible name for the component. | `string` | `undefined` | -| `open` | `open` | /_When true, the menu item will display any slotted `calcite-menu-item` in an open overflow menu_ | `boolean` | `false` | -| `rel` | `rel` | Defines the relationship between the `href` value and the current document. | `string` | `undefined` | -| `target` | `target` | Specifies where to open the linked document defined in the `href` property. | `string` | `undefined` | -| `text` | `text` | Specifies the text to display. | `string` | `undefined` | +| Property | Attribute | Description | Type | Default | +| -------------------- | --------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------- | +| `active` | `active` | When `true`, the component is highlighted. | `boolean` | `undefined` | +| `breadcrumb` | `breadcrumb` | When `true`, the component displays a breadcrumb trail for use as a navigational aid. | `boolean` | `undefined` | +| `href` | `href` | Specifies the URL destination of the component, which can be set as an absolute or relative path. | `string` | `undefined` | +| `iconEnd` | `icon-end` | Specifies an icon to display at the end of the component. | `string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`). | `"both" \| "end" \| "start"` | `undefined` | +| `iconStart` | `icon-start` | Specifies an icon to display at the start of the component. | `string` | `undefined` | +| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ submenu?: string; open?: string; }` | `undefined` | +| `open` | `open` | When `true`, the component will display any slotted `calcite-menu-item` in an open overflow menu. | `boolean` | `false` | +| `rel` | `rel` | Defines the relationship between the `href` value and the current document. | `string` | `undefined` | +| `target` | `target` | Specifies where to open the linked document defined in the `href` property. | `string` | `undefined` | +| `text` | `text` | Specifies the text to display. | `string` | `undefined` | ## Events -| Event | Description | Type | -| ----------------------- | -------------------------------------- | ------------------- | -| `calciteMenuItemSelect` | Emits when user selects the component. | `CustomEvent` | +| Event | Description | Type | +| ----------------------- | ------------------------------------- | ------------------- | +| `calciteMenuItemSelect` | Emits when the component is selected. | `CustomEvent` | ## Methods @@ -54,6 +35,12 @@ Sets focus on the component. Type: `Promise` +## Slots + +| Slot | Description | +| ---------------- | ---------------------------------------------------- | +| `"submenu-item"` | A slot for adding `calcite-menu-item`s in a submenu. | + ## Dependencies ### Depends on diff --git a/packages/calcite-components/src/components/menu/readme.md b/packages/calcite-components/src/components/menu/readme.md index c762d016648..95857b6dbcf 100644 --- a/packages/calcite-components/src/components/menu/readme.md +++ b/packages/calcite-components/src/components/menu/readme.md @@ -2,19 +2,11 @@ -## Usage - -### Basic - -```html - -``` - ## Properties | Property | Attribute | Description | Type | Default | | -------------------- | --------- | ----------------------------------------------------------------------- | ---------------------------- | -------------- | -| `label` _(required)_ | `label` | Specifies accessible label for the component. | `string` | `undefined` | +| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | | `layout` | `layout` | Specifies the layout of the component. | `"horizontal" \| "vertical"` | `"horizontal"` | | `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ more?: string; }` | `undefined` | diff --git a/packages/calcite-components/src/components/meter/readme.md b/packages/calcite-components/src/components/meter/readme.md index 9ab808686df..81398efb994 100644 --- a/packages/calcite-components/src/components/meter/readme.md +++ b/packages/calcite-components/src/components/meter/readme.md @@ -6,7 +6,7 @@ ### Advanced -A complex meter component. +A complex meter component, which includes value and custom unit labels. ```html Promise` | `() => Promise.resolve()` | -| `closeButtonDisabled` | `close-button-disabled` | When `true`, disables the component's close button. | `boolean` | `false` | -| `docked` | `docked` | When `true`, prevents the component from expanding to the entire screen on mobile devices. | `boolean` | `undefined` | -| `escapeDisabled` | `escape-disabled` | When `true`, disables the default close on escape behavior. | `boolean` | `false` | -| `focusTrapDisabled` | `focus-trap-disabled` | When `true`, prevents focus trapping. | `boolean` | `false` | -| `fullscreen` | `fullscreen` | Sets the component to always be fullscreen (overrides `width` and `--calcite-modal-width` / `--calcite-modal-height`). | `boolean` | `undefined` | -| `kind` | `kind` | Specifies the kind of the component (will apply to top border). | `"brand" \| "danger" \| "info" \| "success" \| "warning"` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ModalMessages` | `undefined` | -| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | -| `outsideCloseDisabled` | `outside-close-disabled` | When `true`, disables the closing of the component when clicked outside. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `width` | `width` | Specifies the width of the component. | `"l" \| "m" \| "s"` | `"m"` | +| Property | Attribute | Description | Type | Default | +| ---------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- | +| `beforeClose` | -- | Passes a function to run before the component closes. | `(el: HTMLCalciteModalElement) => Promise` | `undefined` | +| `closeButtonDisabled` | `close-button-disabled` | When `true`, disables the component's close button. | `boolean` | `false` | +| `docked` | `docked` | When `true`, prevents the component from expanding to the entire screen on mobile devices. | `boolean` | `undefined` | +| `escapeDisabled` | `escape-disabled` | When `true`, disables the default close on escape behavior. | `boolean` | `false` | +| `focusTrapDisabled` | `focus-trap-disabled` | When `true`, prevents focus trapping. | `boolean` | `false` | +| `fullscreen` | `fullscreen` | Sets the component to always be fullscreen (overrides `width` and `--calcite-modal-width` / `--calcite-modal-height`). | `boolean` | `undefined` | +| `kind` | `kind` | Specifies the kind of the component (will apply to top border). | `"brand" \| "danger" \| "info" \| "success" \| "warning"` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | +| `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | +| `outsideCloseDisabled` | `outside-close-disabled` | When `true`, disables the closing of the component when clicked outside. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `width` | `width` | Specifies the width of the component. | `"l" \| "m" \| "s"` | `"m"` | ## Events @@ -107,13 +107,15 @@ Type: `Promise` ## Slots -| Slot | Description | -| ------------- | ------------------------------------------ | -| `"back"` | A slot for adding a back button. | -| `"content"` | A slot for adding the component's content. | -| `"header"` | A slot for adding header text. | -| `"primary"` | A slot for adding a primary button. | -| `"secondary"` | A slot for adding a secondary button. | +| Slot | Description | +| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| `"back"` | A slot for adding a back button. | +| `"content"` | A slot for adding the component's content. | +| `"content-bottom"` | A slot for adding content to the component's sticky footer, where content remains at the bottom of the component when scrolling up and down. | +| `"content-top"` | A slot for adding content to the component's sticky header, where content remains at the top of the component when scrolling up and down. | +| `"header"` | A slot for adding header text. | +| `"primary"` | A slot for adding a primary button. | +| `"secondary"` | A slot for adding a secondary button. | ## CSS Custom Properties diff --git a/packages/calcite-components/src/components/navigation-user/readme.md b/packages/calcite-components/src/components/navigation-user/readme.md index 96954180d49..ca8f09c7024 100644 --- a/packages/calcite-components/src/components/navigation-user/readme.md +++ b/packages/calcite-components/src/components/navigation-user/readme.md @@ -18,7 +18,7 @@ | `fullName` | `full-name` | Specifies the full name of the user. | `string` | `undefined` | | `label` | `label` | Describes the appearance of the avatar. If no label is provided, context will not be provided to assistive technologies. | `string` | `undefined` | | `textDisabled` | `text-disabled` | When `true`, hides the `fullName` and `username` contents. | `boolean` | `false` | -| `thumbnail` | `thumbnail` | Specifies the`src` to an image (remember to add a token if the user is private). | `string` | `undefined` | +| `thumbnail` | `thumbnail` | Specifies the `src` to an image (remember to add a token if the user is private). | `string` | `undefined` | | `userId` | `user-id` | Specifies the unique id of the user. | `string` | `undefined` | | `username` | `username` | Specifies the username of the user. | `string` | `undefined` | diff --git a/packages/calcite-components/src/components/navigation/readme.md b/packages/calcite-components/src/components/navigation/readme.md index b5ff48e548a..48fc8055d6f 100644 --- a/packages/calcite-components/src/components/navigation/readme.md +++ b/packages/calcite-components/src/components/navigation/readme.md @@ -20,10 +20,10 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | ------------------- | -------------------------------------------------------------------------------------------------------- | --------- | ----------- | -| `label` _(required)_ | `label` | When `navigationAction` is `true`, specifies the label of the `calcite-action`. | `string` | `undefined` | -| `navigationAction` | `navigation-action` | When `true`, displays a `calcite-action` and emits a `calciteNavActionSelect` event on selection change. | `boolean` | `false` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------------- | -------------------------------------------------------------------------------------------------------- | --------- | ----------- | +| `label` | `label` | When `navigationAction` is `true`, specifies the label of the `calcite-action`. | `string` | `undefined` | +| `navigationAction` | `navigation-action` | When `true`, displays a `calcite-action` and emits a `calciteNavActionSelect` event on selection change. | `boolean` | `false` | ## Events @@ -41,6 +41,20 @@ When `navigation-action` is `true`, sets focus on the component's action element Type: `Promise` +## Slots + +| Slot | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `"content-center"` | A slot for adding a `calcite-menu`, `calcite-action`, or other interactive elements in the center position of the primary navigation level. | +| `"content-end"` | A slot for adding a `calcite-menu`, `calcite-action`, or other interactive elements in the end position of any navigation level. | +| `"content-start"` | A slot for adding a `calcite-menu`, `calcite-action`, or other interactive elements in the start position of any navigation level. | +| `"logo"` | A slot for adding a `calcite-logo` component to the primary navigation level. | +| `"navigation-action"` | A slot for adding a `calcite-action` component to the primary navigation level. | +| `"navigation-secondary"` | A slot for adding a `calcite-navigation` component in the secondary navigation level. Components rendered here will not display `calcite-navigation-logo` or `calcite-navigation-user` components. | +| `"navigation-tertiary"` | A slot for adding a `calcite-navigation` component in the tertiary navigation level. Components rendered here will not display `calcite-navigation-logo` or `calcite-navigation-user` components. | +| `"progress"` | A slot for adding a `calcite-progress` component to the primary navigation level. | +| `"user"` | A slot for adding a `calcite-user` component to the primary navigation level. | + ## CSS Custom Properties | Name | Description | diff --git a/packages/calcite-components/src/components/notice/readme.md b/packages/calcite-components/src/components/notice/readme.md index 43e35ab6863..57c3e5d8b49 100644 --- a/packages/calcite-components/src/components/notice/readme.md +++ b/packages/calcite-components/src/components/notice/readme.md @@ -25,23 +25,25 @@ You can programmatically focus the close button of a `dismissible` `calcite-noti ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- | -| `closable` | `closable` | When `true`, a close button is added to the component. | `boolean` | `false` | -| `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | -| `kind` | `kind` | Specifies the kind of the component (will apply to top border and icon). | `"brand" \| "danger" \| "info" \| "success" \| "warning"` | `"brand"` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `NoticeMessages` | `undefined` | -| `open` | `open` | When `true`, the component is visible. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `width` | `width` | Specifies the width of the component. | `"auto" \| "full" \| "half"` | `"auto"` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ----------- | +| `closable` | `closable` | When `true`, a close button is added to the component. | `boolean` | `false` | +| `icon` | `icon` | When `true`, shows a default recommended icon. Alternatively, pass a Calcite UI Icon name to display a specific icon. | `boolean \| string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | +| `kind` | `kind` | Specifies the kind of the component (will apply to top border and icon). | `"brand" \| "danger" \| "info" \| "success" \| "warning"` | `"brand"` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | +| `open` | `open` | When `true`, the component is visible. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `width` | `width` | Specifies the width of the component. | `"auto" \| "full" \| "half"` | `"auto"` | ## Events -| Event | Description | Type | -| -------------------- | ----------------------------------- | ------------------- | -| `calciteNoticeClose` | Fired when the component is closed. | `CustomEvent` | -| `calciteNoticeOpen` | Fired when the component is opened. | `CustomEvent` | +| Event | Description | Type | +| -------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- | +| `calciteNoticeBeforeClose` | Fires when the component is requested to be closed and before the closing transition begins. | `CustomEvent` | +| `calciteNoticeBeforeOpen` | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | `CustomEvent` | +| `calciteNoticeClose` | Fires when the component is closed and animation is complete. | `CustomEvent` | +| `calciteNoticeOpen` | Fires when the component is open and animation is complete. | `CustomEvent` | ## Methods diff --git a/packages/calcite-components/src/components/pagination/readme.md b/packages/calcite-components/src/components/pagination/readme.md index e3caaa2f471..48c8c993e31 100644 --- a/packages/calcite-components/src/components/pagination/readme.md +++ b/packages/calcite-components/src/components/pagination/readme.md @@ -27,15 +27,15 @@ For example, after querying the search API, you'll get back a response similar t ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `PaginationMessages` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `pageSize` | `page-size` | Specifies the number of items per page. | `number` | `20` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `startItem` | `start-item` | Specifies the starting item number. | `number` | `1` | -| `totalItems` | `total-items` | Specifies the total number of items. | `number` | `0` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ next?: string; previous?: string; }` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `pageSize` | `page-size` | Specifies the number of items per page. | `number` | `20` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `startItem` | `start-item` | Specifies the starting item number. | `number` | `1` | +| `totalItems` | `total-items` | Specifies the total number of items. | `number` | `0` | ## Events @@ -61,8 +61,20 @@ Go to the previous page of results. Type: `Promise` +### `setFocus() => Promise` + +Sets focus on the component's first focusable element. + +#### Returns + +Type: `Promise` + ## Dependencies +### Used by + +- [calcite-table](../table) + ### Depends on - [calcite-icon](../icon) @@ -72,6 +84,7 @@ Type: `Promise` ```mermaid graph TD; calcite-pagination --> calcite-icon + calcite-table --> calcite-pagination style calcite-pagination fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/panel/readme.md b/packages/calcite-components/src/components/panel/readme.md index 056a095addb..a86a5e934a8 100644 --- a/packages/calcite-components/src/components/panel/readme.md +++ b/packages/calcite-components/src/components/panel/readme.md @@ -67,17 +67,17 @@ Renders a panel with a header and a footer. ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ---------------------------------------------------------------------------------------- | ---------------------------- | ----------- | -| `closable` | `closable` | When `true`, displays a close button in the trailing side of the header. | `boolean` | `false` | -| `closed` | `closed` | When `true`, the component will be hidden. | `boolean` | `false` | -| `description` | `description` | A description for the component. | `string` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `heading` | `heading` | The component header text. | `string` | `undefined` | -| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `menuOpen` | `menu-open` | When `true`, the action menu items in the `header-menu-actions` slot are open. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `PanelMessages` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------------- | ---------------------------------------------------------------------------------------- | --------------------------------------- | ----------- | +| `closable` | `closable` | When `true`, displays a close button in the trailing side of the header. | `boolean` | `false` | +| `closed` | `closed` | When `true`, the component will be hidden. | `boolean` | `false` | +| `description` | `description` | A description for the component. | `string` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `heading` | `heading` | The component header text. | `string` | `undefined` | +| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `menuOpen` | `menu-open` | When `true`, the action menu items in the `header-menu-actions` slot are open. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; options?: string; }` | `undefined` | ## Events @@ -106,16 +106,23 @@ Type: `Promise` ## Slots -| Slot | Description | -| ------------------------ | -------------------------------------------------------------------------------- | -| | A slot for adding custom content. | -| `"fab"` | A slot for adding a `calcite-fab` (floating action button) to perform an action. | -| `"footer"` | A slot for adding custom content to the footer. | -| `"footer-actions"` | A slot for adding buttons to the footer. | -| `"header-actions-end"` | A slot for adding actions or content to the end side of the header. | -| `"header-actions-start"` | A slot for adding actions or content to the start side of the header. | -| `"header-content"` | A slot for adding custom content to the header. | -| `"header-menu-actions"` | A slot for adding an overflow menu with actions inside a `calcite-dropdown`. | +| Slot | Description | +| ------------------------ | ------------------------------------------------------------------------------------------------------------ | +| | A slot for adding custom content. | +| `"action-bar"` | A slot for adding a `calcite-action-bar` to the component. | +| `"fab"` | A slot for adding a `calcite-fab` (floating action button) to perform an action. | +| `"footer"` | A slot for adding custom content to the footer. | +| `"footer-actions"` | [Deprecated] Use the `"footer"` slot instead. A slot for adding `calcite-button`s to the component's footer. | +| `"header-actions-end"` | A slot for adding actions or content to the end side of the header. | +| `"header-actions-start"` | A slot for adding actions or content to the start side of the header. | +| `"header-content"` | A slot for adding custom content to the header. | +| `"header-menu-actions"` | A slot for adding an overflow menu with actions inside a `calcite-dropdown`. | + +## CSS Custom Properties + +| Name | Description | +| -------------------------------- | ------------------------------------------------ | +| `--calcite-panel-footer-padding` | Specifies the padding of the component's footer. | ## Dependencies diff --git a/packages/calcite-components/src/components/pick-list-group/readme.md b/packages/calcite-components/src/components/pick-list-group/readme.md index 567ceb896f5..0756deb4e2c 100644 --- a/packages/calcite-components/src/components/pick-list-group/readme.md +++ b/packages/calcite-components/src/components/pick-list-group/readme.md @@ -13,6 +13,12 @@ | `groupTitle` | `group-title` | Specifies the title for all nested `calcite-pick-list-item`s. | `string` | `undefined` | | `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +## Slots + +| Slot | Description | +| ---- | ---------------------------------------------------- | +| | A slot for adding `calcite-pick-list-item` elements. | + --- _Built with [StencilJS](https://stenciljs.com/)_ diff --git a/packages/calcite-components/src/components/pick-list-item/readme.md b/packages/calcite-components/src/components/pick-list-item/readme.md index e05d8e23567..39e824a5f7a 100644 --- a/packages/calcite-components/src/components/pick-list-item/readme.md +++ b/packages/calcite-components/src/components/pick-list-item/readme.md @@ -16,7 +16,7 @@ | `icon` | `icon` | Determines the icon SVG symbol that will be shown. Options are `"circle"`, `"square"`, `"grip"` or `null`. | `ICON_TYPES.circle \| ICON_TYPES.grip \| ICON_TYPES.square` | `null` | | `iconFlipRtl` | `icon-flip-rtl` | When `true`, the icon will be flipped when the element direction is right-to-left (`"rtl"`). | `boolean` | `false` | | `label` _(required)_ | `label` | Label and accessible name for the component. Appears next to the icon. | `string` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `PickListItemMessages` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ remove?: string; }` | `undefined` | | `metadata` | -- | Provides additional metadata to the component. Primary use is for a filter on the parent list. | `{ [x: string]: unknown; }` | `undefined` | | `removable` | `removable` | When `true`, displays a remove action that removes the item from the list. | `boolean` | `false` | | `selected` | `selected` | When `true`, selects an item. Toggles when an item is checked/unchecked. | `boolean` | `false` | @@ -48,6 +48,13 @@ The first argument allows the value to be coerced, rather than swapping values. Type: `Promise` +## Slots + +| Slot | Description | +| ----------------- | ---------------------------------------------------------------------------------- | +| `"actions-end"` | A slot for adding `calcite-action`s or content to the end side of the component. | +| `"actions-start"` | A slot for adding `calcite-action`s or content to the start side of the component. | + ## Dependencies ### Used by diff --git a/packages/calcite-components/src/components/pick-list/readme.md b/packages/calcite-components/src/components/pick-list/readme.md index 5ef862fe476..eb8060dcebc 100644 --- a/packages/calcite-components/src/components/pick-list/readme.md +++ b/packages/calcite-components/src/components/pick-list/readme.md @@ -109,6 +109,13 @@ Sets focus on the component's first focusable element. Type: `Promise` +## Slots + +| Slot | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------- | +| | A slot for adding `calcite-pick-list-item` or `calcite-pick-list-group` elements. Items are displayed as a vertical list. | +| `"menu-actions"` | A slot for adding a button and menu combination for performing actions, such as sorting. | + ## Dependencies ### Depends on diff --git a/packages/calcite-components/src/components/popover/readme.md b/packages/calcite-components/src/components/popover/readme.md index f494db89799..4d5d05ed72f 100644 --- a/packages/calcite-components/src/components/popover/readme.md +++ b/packages/calcite-components/src/components/popover/readme.md @@ -53,12 +53,12 @@ | `heading` | `heading` | The component header text. | `string` | `undefined` | | `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | | `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `PopoverMessages` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | | `offsetDistance` | `offset-distance` | Offsets the position of the popover away from the `referenceElement`. | `number` | `defaultOffsetDistance` | | `offsetSkidding` | `offset-skidding` | Offsets the position of the component along the `referenceElement`. | `number` | `0` | | `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | | `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. `"fixed"` value should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | -| `placement` | `placement` | Determines where the component will be positioned relative to the `referenceElement`. | `"auto" \| "top" \| "left" \| "right" \| "bottom-start" \| "leading-start" \| "bottom" \| "top-start" \| "top-end" \| "left-start" \| "left-end" \| "right-start" \| "right-end" \| "bottom-end" \| "auto-start" \| "auto-end" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `defaultPopoverPlacement` | +| `placement` | `placement` | Determines where the component will be positioned relative to the `referenceElement`. | `"auto" \| "top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end" \| "auto-start" \| "auto-end" \| "leading-start" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `defaultPopoverPlacement` | | `pointerDisabled` | `pointer-disabled` | When `true`, removes the caret pointer. | `boolean` | `false` | | `referenceElement` _(required)_ | `reference-element` | The `referenceElement` used to position the component according to its `placement` value. Setting to an `HTMLElement` is preferred so the component does not need to query the DOM. However, a string `id` of the reference element can also be used. | `Element \| VirtualElement \| string` | `undefined` | | `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | diff --git a/packages/calcite-components/src/components/radio-button-group/readme.md b/packages/calcite-components/src/components/radio-button-group/readme.md index aa3357c712c..2298e473c26 100644 --- a/packages/calcite-components/src/components/radio-button-group/readme.md +++ b/packages/calcite-components/src/components/radio-button-group/readme.md @@ -75,15 +75,15 @@ Renders all radio button inputs disabled, first one checked ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------- | --------------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `hidden` | `hidden` | When `true`, the component is not displayed and its `calcite-radio-button`s are not focusable or checkable. | `boolean` | `false` | -| `layout` | `layout` | Defines the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"horizontal"` | -| `name` _(required)_ | `name` | Specifies the name of the component on form submission. Must be unique to other component instances. | `string` | `undefined` | -| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedItem` | `selected-item` | Specifies the component's selected item. | `HTMLCalciteRadioButtonElement` | `null` | +| Property | Attribute | Description | Type | Default | +| ------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------- | -------------- | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `hidden` | `hidden` | When `true`, the component is not displayed and its `calcite-radio-button`s are not focusable or checkable. | `boolean` | `false` | +| `layout` | `layout` | Defines the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"horizontal"` | +| `name` _(required)_ | `name` | Specifies the name of the component on form submission. Must be unique to other component instances. | `string` | `undefined` | +| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedItem` | -- | Specifies the component's selected item. | `HTMLCalciteRadioButtonElement` | `null` | ## Events @@ -91,6 +91,16 @@ Renders all radio button inputs disabled, first one checked | ------------------------------- | ------------------------------------- | ------------------- | | `calciteRadioButtonGroupChange` | Fires when the component has changed. | `CustomEvent` | +## Methods + +### `setFocus() => Promise` + +Sets focus on the fist focusable `calcite-radio-button` element in the component. + +#### Returns + +Type: `Promise` + ## Slots | Slot | Description | diff --git a/packages/calcite-components/src/components/radio-button/readme.md b/packages/calcite-components/src/components/radio-button/readme.md index f4fa5bdd21a..e02184336a6 100644 --- a/packages/calcite-components/src/components/radio-button/readme.md +++ b/packages/calcite-components/src/components/radio-button/readme.md @@ -19,6 +19,7 @@ | -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | | `checked` | `checked` | When `true`, the component is checked. | `boolean` | `false` | | `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | | `guid` | `guid` | The `id` of the component. When omitted, a globally unique identifier is used. | `string` | `undefined` | | `hidden` | `hidden` | When `true`, the component is not displayed and is not focusable or checkable. | `boolean` | `false` | | `name` | `name` | Specifies the name of the component. Can be inherited from `calcite-radio-button-group`. Required to pass the component's `value` on form submission. | `string` | `undefined` | diff --git a/packages/calcite-components/src/components/rating/readme.md b/packages/calcite-components/src/components/rating/readme.md index fa2c4bec3c3..2528d06a499 100644 --- a/packages/calcite-components/src/components/rating/readme.md +++ b/packages/calcite-components/src/components/rating/readme.md @@ -12,17 +12,18 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------ | ------------------- | ----------- | -| `average` | `average` | Specifies a cumulative average from previous ratings to display. | `number` | `undefined` | -| `count` | `count` | Specifies the number of previous ratings to display. | `number` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `RatingMessages` | `undefined` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `readOnly` | `read-only` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `showChip` | `show-chip` | When `true`, and if available, displays the `average` and/or `count` data summary in a `calcite-chip`. | `boolean` | `false` | -| `value` | `value` | The component's value. | `number` | `0` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----------- | +| `average` | `average` | Specifies a cumulative average from previous ratings to display. | `number` | `undefined` | +| `count` | `count` | Specifies the number of previous ratings to display. | `number` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ rating?: string; stars?: string; }` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `readOnly` | `read-only` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `showChip` | `show-chip` | When `true`, and if available, displays the `average` and/or `count` data summary in a `calcite-chip`. | `boolean` | `false` | +| `value` | `value` | The component's value. | `number` | `0` | ## Events diff --git a/packages/calcite-components/src/components/scrim/readme.md b/packages/calcite-components/src/components/scrim/readme.md index b5f089e3351..13aa765fd67 100644 --- a/packages/calcite-components/src/components/scrim/readme.md +++ b/packages/calcite-components/src/components/scrim/readme.md @@ -36,10 +36,10 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ----------------------------------------------------------------------- | --------------- | ----------- | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ScrimMessages` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------- | ----------------------------------------------------------------------- | ----------------------- | ----------- | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ loading?: string; }` | `undefined` | ## Slots @@ -62,6 +62,7 @@ - [calcite-modal](../modal) - [calcite-panel](../panel) - [calcite-pick-list](../pick-list) +- [calcite-sheet](../sheet) - [calcite-value-list](../value-list) ### Depends on @@ -78,6 +79,7 @@ graph TD; calcite-modal --> calcite-scrim calcite-panel --> calcite-scrim calcite-pick-list --> calcite-scrim + calcite-sheet --> calcite-scrim calcite-value-list --> calcite-scrim style calcite-scrim fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/segmented-control/readme.md b/packages/calcite-components/src/components/segmented-control/readme.md index ad793f85f9a..7c3f2a9d028 100644 --- a/packages/calcite-components/src/components/segmented-control/readme.md +++ b/packages/calcite-components/src/components/segmented-control/readme.md @@ -17,22 +17,23 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| -------------- | --------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | -| `appearance` | `appearance` | Specifies the appearance style of the component. | `"outline" \| "outline-fill" \| "solid"` | `"solid"` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `layout` | `layout` | Defines the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"horizontal"` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedItem` | `selected-item` | The component's selected item `HTMLElement`. | `HTMLCalciteSegmentedControlItemElement` | `undefined` | -| `value` | `value` | The component's `selectedItem` value. | `string` | `null` | -| `width` | `width` | Specifies the width of the component. | `"auto" \| "full"` | `"auto"` | +| Property | Attribute | Description | Type | Default | +| -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------- | +| `appearance` | `appearance` | Specifies the appearance style of the component. | `"outline" \| "outline-fill" \| "solid"` | `"solid"` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `layout` | `layout` | Defines the layout of the component. | `"grid" \| "horizontal" \| "vertical"` | `"horizontal"` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedItem` | -- | The component's selected item `HTMLElement`. | `HTMLCalciteSegmentedControlItemElement` | `undefined` | +| `value` | `value` | The component's `selectedItem` value. | `string` | `null` | +| `width` | `width` | Specifies the width of the component. | `"auto" \| "full"` | `"auto"` | ## Events -| Event | Description | Type | -| ------------------------------- | -------------------------------------------------------------------------------- | ------------------- | -| `calciteSegmentedControlChange` | Fires when the selected option changes, where the event detail is the new value. | `CustomEvent` | +| Event | Description | Type | +| ------------------------------- | ------------------------------------------------------------------ | ------------------- | +| `calciteSegmentedControlChange` | Fires when the `calcite-segmented-control-item` selection changes. | `CustomEvent` | ## Methods diff --git a/packages/calcite-components/src/components/select/readme.md b/packages/calcite-components/src/components/select/readme.md index bcdef61db32..3df11c76a19 100644 --- a/packages/calcite-components/src/components/select/readme.md +++ b/packages/calcite-components/src/components/select/readme.md @@ -106,15 +106,16 @@ Specify the underlying value for each option. ## Properties -| Property | Attribute | Description | Type | Default | -| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedOption` | `selected-option` | The component's selected option `HTMLElement`. | `HTMLCalciteOptionElement` | `undefined` | -| `value` | `value` | The component's `selectedOption` value. | `string` | `null` | -| `width` | `width` | Specifies the width of the component. | `"auto" \| "full" \| "half"` | `"auto"` | +| Property | Attribute | Description | Type | Default | +| -------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedOption` | -- | The component's selected option `HTMLElement`. | `HTMLCalciteOptionElement` | `undefined` | +| `value` | `value` | The component's `selectedOption` value. | `string` | `null` | +| `width` | `width` | Specifies the width of the component. | `"auto" \| "full" \| "half"` | `"auto"` | ## Events diff --git a/packages/calcite-components/src/components/sheet/readme.md b/packages/calcite-components/src/components/sheet/readme.md index cc6ae5b50fd..2b5ad005ea6 100644 --- a/packages/calcite-components/src/components/sheet/readme.md +++ b/packages/calcite-components/src/components/sheet/readme.md @@ -80,7 +80,7 @@ sheet.beforeClose = beforeClose; | `label` _(required)_ | `label` | Specifies the label of the component. | `string` | `undefined` | | `open` | `open` | When `true`, displays and positions the component. | `boolean` | `false` | | `outsideCloseDisabled` | `outside-close-disabled` | When `true`, disables the closing of the component when clicked outside. | `boolean` | `false` | -| `position` | `position` | When `true`, disables the closing of the component when clicked outside. | `"block-end" \| "block-start" \| "inline-end" \| "inline-start"` | `"inline-start"` | +| `position` | `position` | Determines where the component will be positioned. | `"block-end" \| "block-start" \| "inline-end" \| "inline-start"` | `"inline-start"` | | `widthScale` | `width-scale` | When `position` is `"inline-start"` or `"inline-end"`, specifies the width of the component. | `"l" \| "m" \| "s"` | `"m"` | ## Events diff --git a/packages/calcite-components/src/components/shell-panel/readme.md b/packages/calcite-components/src/components/shell-panel/readme.md index 022d4414e74..3183ac50aad 100644 --- a/packages/calcite-components/src/components/shell-panel/readme.md +++ b/packages/calcite-components/src/components/shell-panel/readme.md @@ -78,15 +78,18 @@ Add `calcite-match-height` to a wrapping element to ensure proper height, scroll ## Properties -| Property | Attribute | Description | Type | Default | -| --------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------- | ----------- | -| `collapsed` | `collapsed` | When `true`, hides the component's content area. | `boolean` | `false` | -| `detached` | `detached` | When `true`, the content area displays like a floating panel. | `boolean` | `false` | -| `detachedHeightScale` | `detached-height-scale` | When `detached`, specifies the maximum height of the component. | `"l" \| "m" \| "s"` | `"l"` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ShellPanelMessages` | `undefined` | -| `position` | `position` | Specifies the component's position. Will be flipped when the element direction is right-to-left (`"rtl"`). | `"end" \| "start"` | `undefined` | -| `resizable` | `resizable` | When `true` and not `detached`, the component's content area is resizable. | `boolean` | `false` | -| `widthScale` | `width-scale` | Specifies the width of the component's content area. | `"l" \| "m" \| "s"` | `"m"` | +| Property | Attribute | Description | Type | Default | +| --------------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------ | +| `collapsed` | `collapsed` | When `true`, hides the component's content area. | `boolean` | `false` | +| `detached` | `detached` | **[DEPRECATED]** use `displayMode` instead.

When `true`, the content area displays like a floating panel. | `boolean` | `false` | +| `detachedHeightScale` | `detached-height-scale` | **[DEPRECATED]** use `heightScale` instead.

When `displayMode` is `float`, specifies the maximum height of the component. | `"l" \| "m" \| "s"` | `undefined` | +| `displayMode` | `display-mode` | Specifies the display mode - `"dock"` (full height, displays adjacent to center content), `"float"` (not full height, content is separated detached from `calcite-action-bar`, displays on top of center content), or `"overlay"` (full height, displays on top of center content). | `"dock" \| "float" \| "overlay"` | `"dock"` | +| `heightScale` | `height-scale` | When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float`, specifies the maximum height of the component. | `"l" \| "m" \| "s"` | `undefined` | +| `layout` | `layout` | The direction of the component. | `"horizontal" \| "vertical"` | `"vertical"` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ resize?: string; }` | `undefined` | +| `position` | `position` | Specifies the component's position. Will be flipped when the element direction is right-to-left (`"rtl"`). | `"end" \| "start"` | `"start"` | +| `resizable` | `resizable` | When `true` and `displayMode` is not `float`, the component's content area is resizable. | `boolean` | `false` | +| `widthScale` | `width-scale` | When `layout` is `vertical`, specifies the width of the component. | `"l" \| "m" \| "s"` | `"m"` | ## Slots @@ -97,12 +100,16 @@ Add `calcite-match-height` to a wrapping element to ensure proper height, scroll ## CSS Custom Properties -| Name | Description | -| ------------------------------------------- | ------------------------------------------------------------ | -| `--calcite-shell-panel-detached-max-height` | The maximum height of the component when `detached` is true. | -| `--calcite-shell-panel-max-width` | The maximum width of the component. | -| `--calcite-shell-panel-min-width` | The minimum width of the component. | -| `--calcite-shell-panel-width` | The width of the component. | +| Name | Description | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| `--calcite-shell-panel-detached-max-height` | [Deprecated] Use the `heightScale` property instead. When `displayMode` is `float`, specifies the maximum height of the component. | +| `--calcite-shell-panel-height` | When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float`, specifies the height of the component. | +| `--calcite-shell-panel-max-height` | When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float`, specifies the maximum height of the component. | +| `--calcite-shell-panel-max-width` | Specifies the maximum width of the component. | +| `--calcite-shell-panel-min-height` | When `layout` is `horizontal`, or `layout` is `vertical` and `displayMode` is `float`, specifies the minimum height of the component. | +| `--calcite-shell-panel-min-width` | Specifies the minimum width of the component. | +| `--calcite-shell-panel-width` | Specifies the width of the component. | +| `--calcite-shell-panel-z-index` | Specifies the z-index value for the component. | --- diff --git a/packages/calcite-components/src/components/shell/readme.md b/packages/calcite-components/src/components/shell/readme.md index f7afb330f33..8564b76cf50 100644 --- a/packages/calcite-components/src/components/shell/readme.md +++ b/packages/calcite-components/src/components/shell/readme.md @@ -14,14 +14,14 @@ Renders a shell with leading and trailing floating panels, action bar/pad, block ```html - + - + - + @@ -40,14 +40,14 @@ Renders a shell with leading and trailing floating panels, action bar/pad, block - + - + - + @@ -145,16 +145,19 @@ Renders a shell with a header and panels on the left and right sides of the app. ## Slots -| Slot | Description | -| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| | A slot for adding custom content. This content will appear between any leading and trailing panels added to the component, such as a map. | -| `"alerts"` | A slot for adding `calcite-alert` components. When placed in this slot, the alert position will be constrained to the extent of the shell. | -| `"center-row"` | A slot for adding content to the center row. | -| `"footer"` | A slot for adding footer content. This content will be positioned at the bottom of the component. | -| `"header"` | A slot for adding header content. This content will be positioned at the top of the component. | -| `"modals"` | A slot for adding `calcite-modal` components. When placed in this slot, the modal position will be constrained to the extent of the shell. | -| `"panel-end"` | A slot for adding the ending `calcite-shell-panel`. | -| `"panel-start"` | A slot for adding the starting `calcite-shell-panel`. | +| Slot | Description | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| | A slot for adding custom content. This content will appear between any leading and trailing panels added to the component, such as a map. | +| `"alerts"` | A slot for adding `calcite-alert` components. When placed in this slot, the alert position will be constrained to the extent of the shell. | +| `"center-row"` | [Deprecated] Use the `"panel-bottom"` slot instead. A slot for adding the bottom `calcite-shell-center-row`. | +| `"footer"` | A slot for adding footer content. This content will be positioned at the bottom of the component. | +| `"header"` | A slot for adding header content. This content will be positioned at the top of the component. | +| `"modals"` | A slot for adding `calcite-modal` components. When placed in this slot, the modal position will be constrained to the extent of the shell. | +| `"panel-bottom"` | A slot for adding the bottom `calcite-shell-center-row`. | +| `"panel-end"` | A slot for adding the ending `calcite-shell-panel`. | +| `"panel-start"` | A slot for adding the starting `calcite-shell-panel`. | +| `"panel-top"` | A slot for adding the top `calcite-shell-center-row`. | +| `"sheets"` | A slot for adding `calcite-sheet` components. When placed in this slot, the sheet position will be constrained to the extent of the shell. | ## CSS Custom Properties diff --git a/packages/calcite-components/src/components/slider/readme.md b/packages/calcite-components/src/components/slider/readme.md index e90fedfe3f2..7386326e611 100644 --- a/packages/calcite-components/src/components/slider/readme.md +++ b/packages/calcite-components/src/components/slider/readme.md @@ -30,32 +30,33 @@ If you'd like to allow an upper and lower value selection (two handles), you can ## Properties -| Property | Attribute | Description | Type | Default | -| ----------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | -| `hasHistogram` | `has-histogram` | When `true`, indicates a histogram is present. | `boolean` | `false` | -| `histogram` | -- | A list of the histogram's x,y coordinates within the component's `min` and `max`. Displays above the component's track. | `Point[]` | `undefined` | -| `histogramStops` | -- | A set of single color stops for a histogram, sorted by offset ascending. | `ColorStop[]` | `undefined` | -| `labelHandles` | `label-handles` | When `true`, displays label handles with their numeric value. | `boolean` | `false` | -| `labelTicks` | `label-ticks` | When `true` and `ticks` is specified, displays label tick marks with their numeric value. | `boolean` | `false` | -| `max` | `max` | The component's maximum selectable value. | `number` | `100` | -| `maxLabel` | `max-label` | For multiple selections, the accessible name for the second handle, such as `"Temperature, upper bound"`. | `string` | `undefined` | -| `maxValue` | `max-value` | For multiple selections, the component's upper value. | `number` | `undefined` | -| `min` | `min` | The component's minimum selectable value. | `number` | `0` | -| `minLabel` | `min-label` | Accessible name for first (or only) handle, such as `"Temperature, lower bound"`. | `string` | `undefined` | -| `minValue` | `min-value` | For multiple selections, the component's lower value. | `number` | `undefined` | -| `mirrored` | `mirrored` | When `true`, the slider will display values from high to low. Note that this value will be ignored if the slider has an associated histogram. | `boolean` | `false` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `pageStep` | `page-step` | Specifies the interval to move with the page up, or page down keys. | `number` | `undefined` | -| `precise` | `precise` | When `true`, sets a finer point for handles. | `boolean` | `false` | -| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `snap` | `snap` | When `true`, enables snap selection in coordination with `step` via a mouse. | `boolean` | `false` | -| `step` | `step` | Specifies the interval to move with the up, or down keys. | `number` | `1` | -| `ticks` | `ticks` | Displays tick marks on the number line at a specified interval. | `number` | `undefined` | -| `value` | `value` | The component's value. | `number \| number[]` | `0` | +| Property | Attribute | Description | Type | Default | +| ----------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | +| `hasHistogram` | `has-histogram` | When `true`, indicates a histogram is present. | `boolean` | `false` | +| `histogram` | -- | A list of the histogram's x,y coordinates within the component's `min` and `max`. Displays above the component's track. | `Point[]` | `undefined` | +| `histogramStops` | -- | A set of single color stops for a histogram, sorted by offset ascending. | `ColorStop[]` | `undefined` | +| `labelHandles` | `label-handles` | When `true`, displays label handles with their numeric value. | `boolean` | `false` | +| `labelTicks` | `label-ticks` | When `true` and `ticks` is specified, displays label tick marks with their numeric value. | `boolean` | `false` | +| `max` | `max` | The component's maximum selectable value. | `number` | `100` | +| `maxLabel` | `max-label` | For multiple selections, the accessible name for the second handle, such as `"Temperature, upper bound"`. | `string` | `undefined` | +| `maxValue` | `max-value` | For multiple selections, the component's upper value. | `number` | `undefined` | +| `min` | `min` | The component's minimum selectable value. | `number` | `0` | +| `minLabel` | `min-label` | Accessible name for first (or only) handle, such as `"Temperature, lower bound"`. | `string` | `undefined` | +| `minValue` | `min-value` | For multiple selections, the component's lower value. | `number` | `undefined` | +| `mirrored` | `mirrored` | When `true`, the slider will display values from high to low. Note that this value will be ignored if the slider has an associated histogram. | `boolean` | `false` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `pageStep` | `page-step` | Specifies the interval to move with the page up, or page down keys. | `number` | `undefined` | +| `precise` | `precise` | When `true`, sets a finer point for handles. | `boolean` | `false` | +| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `snap` | `snap` | When `true`, enables snap selection in coordination with `step` via a mouse. | `boolean` | `false` | +| `step` | `step` | Specifies the interval to move with the up, or down keys. | `number` | `1` | +| `ticks` | `ticks` | Displays tick marks on the number line at a specified interval. | `number` | `undefined` | +| `value` | `value` | The component's value. | `number \| number[]` | `0` | ## Events diff --git a/packages/calcite-components/src/components/sortable-list/readme.md b/packages/calcite-components/src/components/sortable-list/readme.md index 9a4c7029775..c695d5550ba 100644 --- a/packages/calcite-components/src/components/sortable-list/readme.md +++ b/packages/calcite-components/src/components/sortable-list/readme.md @@ -6,6 +6,8 @@ | Property | Attribute | Description | Type | Default | | ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ------------------ | +| `canPull` | -- | When provided, the method will be called to determine whether the element can move from the list. | `(detail: DragDetail) => boolean` | `undefined` | +| `canPut` | -- | When provided, the method will be called to determine whether the element can be added from another list. | `(detail: DragDetail) => boolean` | `undefined` | | `disabled` | `disabled` | When true, disabled prevents interaction. This state shows items with lower opacity/grayed. | `boolean` | `false` | | `dragSelector` | `drag-selector` | Specifies which items inside the element should be draggable. | `string` | `undefined` | | `group` | `group` | The list's group identifier. To drag elements from one list into another, both lists must have the same group value. | `string` | `undefined` | diff --git a/packages/calcite-components/src/components/split-button/readme.md b/packages/calcite-components/src/components/split-button/readme.md index 4b1fc2ad89a..e4fcf829d53 100644 --- a/packages/calcite-components/src/components/split-button/readme.md +++ b/packages/calcite-components/src/components/split-button/readme.md @@ -44,6 +44,16 @@ The calcite-split-button control is one that combines a button with a dropdown m | `calciteSplitButtonPrimaryClick` | Fires when the primary button is clicked. | `CustomEvent` | | `calciteSplitButtonSecondaryClick` | Fires when the dropdown menu is clicked. | `CustomEvent` | +## Methods + +### `setFocus() => Promise` + +Sets focus on the component's first focusable element. + +#### Returns + +Type: `Promise` + ## Slots | Slot | Description | diff --git a/packages/calcite-components/src/components/stack/readme.md b/packages/calcite-components/src/components/stack/readme.md index af63210adbb..1398d8ac883 100644 --- a/packages/calcite-components/src/components/stack/readme.md +++ b/packages/calcite-components/src/components/stack/readme.md @@ -1,3 +1,70 @@ # calcite-stack -Renders a component to help users be able to layout content with slots. + + +## Usage + +### Basic + +```html + + + My great chip + Hello World + + + +``` + +### Disabled + +```html + + + Hello World + + My great chip + + +``` + +## Properties + +| Property | Attribute | Description | Type | Default | +| ---------- | ---------- | ------------------------------------------------------------------------------- | --------- | ------- | +| `disabled` | `disabled` | When `true`, content interaction is prevented and displayed with lower opacity. | `boolean` | `false` | + +## Slots + +| Slot | Description | +| ----------------- | ------------------------------------------------------------------------------------------- | +| | A slot for adding content. | +| `"actions-end"` | A slot for adding actionable `calcite-action` elements after the content of the component. | +| `"actions-start"` | A slot for adding actionable `calcite-action` elements before the content of the component. | +| `"content-end"` | A slot for adding non-actionable elements after content of the component. | +| `"content-start"` | A slot for adding non-actionable elements before content of the component. | + +## CSS Custom Properties + +| Name | Description | +| -------------------------------- | -------------------------------------------------------- | +| `--calcite-stack-padding-block` | Specifies the block padding of the component's content. | +| `--calcite-stack-padding-inline` | Specifies the inline padding of the component's content. | + +## Dependencies + +### Used by + +- [calcite-list](../list) + +### Graph + +```mermaid +graph TD; + calcite-list --> calcite-stack + style calcite-stack fill:#f9f,stroke:#333,stroke-width:4px +``` + +--- + +_Built with [StencilJS](https://stenciljs.com/)_ diff --git a/packages/calcite-components/src/components/stepper/readme.md b/packages/calcite-components/src/components/stepper/readme.md index d405bf79104..216179af8b1 100644 --- a/packages/calcite-components/src/components/stepper/readme.md +++ b/packages/calcite-components/src/components/stepper/readme.md @@ -32,7 +32,7 @@ Calcite stepper can be used to present a stepper workflow to a user. It has conf | `numbered` | `numbered` | When `true`, displays the step number in the `calcite-stepper-item` heading. | `boolean` | `false` | | `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | | `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedItem` | `selected-item` | Specifies the component's selected item. | `HTMLCalciteStepperItemElement` | `null` | +| `selectedItem` | -- | Specifies the component's selected item. | `HTMLCalciteStepperItemElement` | `null` | ## Events diff --git a/packages/calcite-components/src/components/switch/readme.md b/packages/calcite-components/src/components/switch/readme.md index 8dffdb73c7b..35ef50a4696 100644 --- a/packages/calcite-components/src/components/switch/readme.md +++ b/packages/calcite-components/src/components/switch/readme.md @@ -14,14 +14,15 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ---------- | ---------- | ------------------------------------------------------------------------------------------------- | ------------------- | ----------- | -| `checked` | `checked` | When `true`, the component is checked. | `boolean` | `false` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `label` | `label` | Accessible name for the component. | `string` | `undefined` | -| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` | `value` | The component's value. | `any` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | ----------- | +| `checked` | `checked` | When `true`, the component is checked. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `label` | `label` | Accessible name for the component. | `string` | `undefined` | +| `name` | `name` | Specifies the name of the component. Required to pass the component's `value` on form submission. | `string` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `value` | `value` | The component's value. | `any` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/tab-nav/readme.md b/packages/calcite-components/src/components/tab-nav/readme.md index 7140f882603..58098465d28 100644 --- a/packages/calcite-components/src/components/tab-nav/readme.md +++ b/packages/calcite-components/src/components/tab-nav/readme.md @@ -20,11 +20,11 @@ When tab-nav is the only parent, tab-title can inherit its `scale` and `position ## Properties -| Property | Attribute | Description | Type | Default | -| --------------- | ---------------- | ----------------------------------------------------------------------------- | ---------------------------- | ----------- | -| `selectedTitle` | `selected-title` | Specifies the component's selected tab-title. | `HTMLCalciteTabTitleElement` | `null` | -| `storageId` | `storage-id` | Specifies the name when saving selected `calcite-tab` data to `localStorage`. | `string` | `undefined` | -| `syncId` | `sync-id` | Specifies text to update multiple components to keep in sync if one changes. | `string` | `undefined` | +| Property | Attribute | Description | Type | Default | +| --------------- | ------------ | ----------------------------------------------------------------------------- | ---------------------------- | ----------- | +| `selectedTitle` | -- | Specifies the component's selected tab-title. | `HTMLCalciteTabTitleElement` | `null` | +| `storageId` | `storage-id` | Specifies the name when saving selected `calcite-tab` data to `localStorage`. | `string` | `undefined` | +| `syncId` | `sync-id` | Specifies text to update multiple components to keep in sync if one changes. | `string` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/tab-title/readme.md b/packages/calcite-components/src/components/tab-title/readme.md index 679692f844c..a8909c4100b 100644 --- a/packages/calcite-components/src/components/tab-title/readme.md +++ b/packages/calcite-components/src/components/tab-title/readme.md @@ -6,20 +6,24 @@ The tab-title is the link that switches between panes in [calcite-tabs](../tabs) ## Properties -| Property | Attribute | Description | Type | Default | -| ------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `iconEnd` | `icon-end` | Specifies an icon to display at the end of the component. | `string` | `undefined` | -| `iconFlipRtl` | `icon-flip-rtl` | Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`). | `"both" \| "end" \| "start"` | `undefined` | -| `iconStart` | `icon-start` | Specifies an icon to display at the start of the component. | `string` | `undefined` | -| `selected` | `selected` | When `true`, the component and its respective `calcite-tab` contents are selected. Only one tab can be selected within the `calcite-tabs` parent. | `boolean` | `false` | -| `tab` | `tab` | Specifies a unique name for the component. When specified, use the same value on the `calcite-tab`. | `string` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | ----------- | +| `closable` | `closable` | When `true`, a close button is added to the component. | `boolean` | `false` | +| `closed` | `closed` | When `true`, does not display or position the component. | `boolean` | `false` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `iconEnd` | `icon-end` | Specifies an icon to display at the end of the component. | `string` | `undefined` | +| `iconFlipRtl` | `icon-flip-rtl` | Displays the `iconStart` and/or `iconEnd` as flipped when the element direction is right-to-left (`"rtl"`). | `"both" \| "end" \| "start"` | `undefined` | +| `iconStart` | `icon-start` | Specifies an icon to display at the start of the component. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | +| `selected` | `selected` | When `true`, the component and its respective `calcite-tab` contents are selected. Only one tab can be selected within the `calcite-tabs` parent. | `boolean` | `false` | +| `tab` | `tab` | Specifies a unique name for the component. When specified, use the same value on the `calcite-tab`. | `string` | `undefined` | ## Events | Event | Description | Type | | --------------------- | --------------------------------------- | ------------------- | | `calciteTabsActivate` | Fires when a `calcite-tab` is selected. | `CustomEvent` | +| `calciteTabsClose` | Fires when a `calcite-tab` is closed. | `CustomEvent` | ## Methods diff --git a/packages/calcite-components/src/components/table-cell/readme.md b/packages/calcite-components/src/components/table-cell/readme.md index 7c9c20fd6bc..01e2451f518 100644 --- a/packages/calcite-components/src/components/table-cell/readme.md +++ b/packages/calcite-components/src/components/table-cell/readme.md @@ -4,20 +4,18 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ----------- | ----------------------------------------------------------------------------------------- | ------------------------------ | ----------- | -| `alignment` | `alignment` | Specifies the alignment of the component. | `"center" \| "end" \| "start"` | `"start"` | -| `colSpan` | `col-span` | | `number` | `undefined` | -| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ focusReadout?: string; }` | `undefined` | -| `rowSpan` | `row-span` | | `number` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` | `value` | Provide a value to the component - used to sort when table header is sortable and active. | `""` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ----------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- | +| `alignment` | `alignment` | Specifies the alignment of the component. | `"center" \| "end" \| "start"` | `"start"` | +| `colSpan` | `col-span` | Specifies the number of columns the component should span. | `number` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ keyboardDeselect?: string; keyboardSelect?: string; row?: string; selected?: string; unselected?: string; }` | `undefined` | +| `rowSpan` | `row-span` | Specifies the number of rows the component should span. | `number` | `undefined` | ## Methods ### `setFocus() => Promise` -Sets focus on the component's first focusable element. +Sets focus on the component. #### Returns diff --git a/packages/calcite-components/src/components/table-header/readme.md b/packages/calcite-components/src/components/table-header/readme.md index 308975e0e20..f0b3d5eb9c7 100644 --- a/packages/calcite-components/src/components/table-header/readme.md +++ b/packages/calcite-components/src/components/table-header/readme.md @@ -4,34 +4,25 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------- | -| `alignment` | `alignment` | Specifies the alignment of the component. | `"center" \| "end" \| "start"` | `"start"` | -| `colSpan` | `col-span` | | `number` | `undefined` | -| `description` | `description` | A description to display beneath heading content. | `string` | `undefined` | -| `heading` | `heading` | A heading to display above description content. | `string` | `undefined` | -| `label` | `label` | | `string` | `""` | -| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ focusReadout?: string; sortAscending?: string; sortDescending?: string; sortNone?: string; }` | `undefined` | -| `rowSpan` | `row-span` | | `number` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `sortable` | `sortable` | Specifies if the component should be able to sort associated `calcite-table-cell` ascending or descending | `boolean` | `false` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `alignment` | `alignment` | Specifies the alignment of the component. | `"center" \| "end" \| "start"` | `"start"` | +| `colSpan` | `col-span` | Specifies the number of columns the component should span. | `number` | `undefined` | +| `description` | `description` | A description to display beneath heading content. | `string` | `undefined` | +| `heading` | `heading` | A heading to display above description content. | `string` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ all?: string; keyboardDeselectAll?: string; keyboardSelectAll?: string; rowNumber?: string; selected?: string; selectionColumn?: string; }` | `undefined` | +| `rowSpan` | `row-span` | Specifies the number of rows the component should span. | `number` | `undefined` | ## Methods ### `setFocus() => Promise` -Sets focus on the component's first focusable element. +Sets focus on the component. #### Returns Type: `Promise` -## Slots - -| Slot | Description | -| --------------- | ------------------------------------------------ | -| `"actions-end"` | A slot for adding content, usually text content. | - ## CSS Custom Properties | Name | Description | diff --git a/packages/calcite-components/src/components/table-row/readme.md b/packages/calcite-components/src/components/table-row/readme.md index 48216d72890..1bbc3275331 100644 --- a/packages/calcite-components/src/components/table-row/readme.md +++ b/packages/calcite-components/src/components/table-row/readme.md @@ -4,11 +4,10 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ---------- | ---------- | ---------------------------------------------------------------------------------------- | ------------------- | ------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selected` | `selected` | Is the component selected. | `boolean` | `false` | +| Property | Attribute | Description | Type | Default | +| ---------- | ---------- | ---------------------------------------------------------------------------------------- | --------- | ------- | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `selected` | `selected` | When `true`, the component is selected. | `boolean` | `false` | ## Events diff --git a/packages/calcite-components/src/components/table/readme.md b/packages/calcite-components/src/components/table/readme.md index 4912fd5b0b5..58a8a94787f 100644 --- a/packages/calcite-components/src/components/table/readme.md +++ b/packages/calcite-components/src/components/table/readme.md @@ -2,46 +2,166 @@ +## Usage + +### Advanced + +A complex table component, with selection modes and slotted actions, pagination, and various display options configured. + +```html + + + + + + + + + + + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + + 24,212 + 58% happiness + + + +``` + +### Basic + +A simple table component. + +```html + + + + + + + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + + cell + cell + cell + cell + + +``` + ## Properties -| Property | Attribute | Description | Type | Default | -| ---------------------- | ---------------- | ------------------------------------------------------------- | -------------------------------------------------------------- | ----------- | -| `appearance` | `appearance` | Specifies the appearance of the component. | `"bordered" \| "bordered-zebra" \| "simple" \| "simple-zebra"` | `"simple"` | -| `caption` _(required)_ | `caption` | Specifies an accessible title for the component. | `string` | `undefined` | -| `layout` | `layout` | Specifies the layout of the component. | `"auto" \| "fixed"` | `"auto"` | -| `numbered` | `numbered` | When `true`, displays the position of the row in numeric form | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteTableRowElement[]` | `[]` | -| `selectionMode` | `selection-mode` | Specifies the selection mode of the component. | `"multiple" \| "none" \| "single"` | `"none"` | +| Property | Attribute | Description | Type | Default | +| ---------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `bordered` | `bordered` | When `true`, displays borders in the component. | `boolean` | `false` | +| `caption` _(required)_ | `caption` | Specifies an accessible title for the component. | `string` | `undefined` | +| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | +| `layout` | `layout` | Specifies the layout of the component. | `"auto" \| "fixed"` | `"auto"` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ clear?: string; hiddenSelected?: string; page?: string; row?: string; selected?: string; }` | `undefined` | +| `numbered` | `numbered` | When `true`, displays the position of the row in numeric form. | `boolean` | `false` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `pageSize` | `page-size` | Specifies the page size of the component. When `true`, renders `calcite-pagination` | `number` | `0` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteTableRowElement[]` | `[]` | +| `selectionMode` | `selection-mode` | Specifies the selection mode of the component. | `"multiple" \| "none" \| "single"` | `"none"` | +| `zebra` | `zebra` | When `true`, displays zebra styling in the component. | `boolean` | `false` | ## Events -| Event | Description | Type | -| -------------------- | --------------------------------------------- | ------------------- | -| `calciteTableSelect` | Emits when the component's selection changes. | `CustomEvent` | +| Event | Description | Type | +| ------------------------ | -------------------------------------------------- | ------------------- | +| `calciteTablePageChange` | Emits when the component's page selection changes. | `CustomEvent` | +| `calciteTableSelect` | Emits when the component's selected rows change. | `CustomEvent` | ## Slots -| Slot | Description | -| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| | A slot for adding `calcite-table-row` or nested `calcite-table` elements. Content placed here will be rendered in a `table-body` tag. | -| `"selection-actions"` | A slot for adding a `calcite-action` or other element to display when `selectionMode !== "none"` and `calcite-table-row` are selected. | -| `"selection-actions"` | A slot for adding a `calcite-action` or other element to display when `selectionMode !== "none"` and `calcite-table-row` are selected. | -| `"table-foot- A slot for adding`calcite-table-row`and nested`calcite-table-header`elements."` | | -| `"table-head- A slot for adding`calcite-table-row`and nested`calcite-table-header`elements."` | | +| Slot | Description | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | +| | A slot for adding `calcite-table-row` elements containing `calcite-table-cell` and/or `calcite-table-header` elements. | +| `"selection-actions"` | A slot for adding a `calcite-action-bar` or other elements to display when `selectionMode` is not `"none"`. | +| `"table-footer"` | A slot for adding `calcite-table-row` elements containing `calcite-table-cell` and/or `calcite-table-header` elements. | +| `"table-header"` | A slot for adding `calcite-table-row` elements containing `calcite-table-header` elements. | ## Dependencies ### Depends on - [calcite-chip](../chip) +- [calcite-button](../button) +- [calcite-pagination](../pagination) ### Graph ```mermaid graph TD; calcite-table --> calcite-chip + calcite-table --> calcite-button + calcite-table --> calcite-pagination calcite-chip --> calcite-icon + calcite-button --> calcite-loader + calcite-button --> calcite-icon + calcite-pagination --> calcite-icon style calcite-table fill:#f9f,stroke:#333,stroke-width:4px ``` diff --git a/packages/calcite-components/src/components/text-area/readme.md b/packages/calcite-components/src/components/text-area/readme.md index f42babb0af6..51029af48c4 100644 --- a/packages/calcite-components/src/components/text-area/readme.md +++ b/packages/calcite-components/src/components/text-area/readme.md @@ -12,7 +12,7 @@ ### Exceeding-max-length -Renders text-area with +Renders text-area with character limit counter. ```html @@ -20,25 +20,26 @@ Renders text-area with ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -| `autofocus` | `autofocus` | When `true`, the component is focused on page load. | `boolean` | `false` | -| `columns` | `columns` | Specifies the number or columns allowed. | `number` | `undefined` | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | -| `label` | `label` | Accessible name for the component. | `string` | `undefined` | -| `maxLength` | `max-length` | Specifies the maximum number of characters allowed. | `number` | `undefined` | -| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ invalid?: string; overLimit?: string; }` | `undefined` | -| `name` | `name` | Specifies the name of the component | `string` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `placeholder` | `placeholder` | Specifies the placeholder text for the component. | `string` | `undefined` | -| `readonly` | `readonly` | When `true`, the component's value can be read, but cannot be modified. | `boolean` | `false` | -| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | -| `resize` | `resize` | When `true`, disables horizontally and vertically resizing the component. | `"both" \| "horizontal" \| "none" \| "vertical"` | `"both"` | -| `rows` | `rows` | Specifies the number or rows allowed. | `number` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `value` | `value` | The component's value. | `string` | `undefined` | -| `wrap` | `wrap` | Specifies the wrapping mechanism for the text. | `"hard" \| "soft"` | `"soft"` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `autofocus` | `autofocus` | When `true`, the component is focused on page load. Only one element can contain `autofocus`. If multiple elements have `autofocus`, the first element will receive focus. | `boolean` | `false` | +| `columns` | `columns` | Specifies the component's number of columns. | `number` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `form` | `form` | The ID of the form that will be associated with the component. When not set, the component will be associated with its ancestor form element, if any. | `string` | `undefined` | +| `groupSeparator` | `group-separator` | When `true`, number values are displayed with a group separator corresponding to the language and country format. | `boolean` | `false` | +| `label` | `label` | Accessible name for the component. | `string` | `undefined` | +| `maxLength` | `max-length` | Specifies the maximum number of characters allowed. | `number` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ invalid?: string; tooLong?: string; }` | `undefined` | +| `name` | `name` | Specifies the name of the component. | `string` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `placeholder` | `placeholder` | Specifies the placeholder text for the component. | `string` | `undefined` | +| `readOnly` | `read-only` | When `true`, the component's `value` can be read, but cannot be modified. | `boolean` | `false` | +| `required` | `required` | When `true`, the component must have a value in order for the form to submit. | `boolean` | `false` | +| `resize` | `resize` | Specifies if the component is resizable. | `"both" \| "horizontal" \| "none" \| "vertical"` | `"both"` | +| `rows` | `rows` | Specifies the component's number of rows. | `number` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `value` | `value` | The component's value. | `string` | `undefined` | +| `wrap` | `wrap` | Specifies the wrapping mechanism for the text. | `"hard" \| "soft"` | `"soft"` | ## Events @@ -51,7 +52,7 @@ Renders text-area with ### `selectText() => Promise` -Selects all text of the component's `value`. +Selects the text of the component's `value`. #### Returns @@ -67,11 +68,11 @@ Type: `Promise` ## Slots -| Slot | Description | -| ---------------- | ------------------------------------ | -| | A slot for adding text. | -| `"footer-end"` | A slot for adding a trailing footer. | -| `"footer-start"` | A slot for adding a leading footer. | +| Slot | Description | +| ---------------- | ----------------------------------------------------------------- | +| | A slot for adding text. | +| `"footer-end"` | A slot for adding content to the end of the component's footer. | +| `"footer-start"` | A slot for adding content to the start of the component's footer. | --- diff --git a/packages/calcite-components/src/components/time-picker/readme.md b/packages/calcite-components/src/components/time-picker/readme.md index 1d299d9833f..c44b6192a42 100644 --- a/packages/calcite-components/src/components/time-picker/readme.md +++ b/packages/calcite-components/src/components/time-picker/readme.md @@ -4,13 +4,13 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `TimePickerMessages` | `undefined` | -| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `step` | `step` | Specifies the granularity the `value` must adhere to (in seconds). | `number` | `60` | -| `value` | `value` | The component's value in UTC (always 24-hour format). | `string` | `null` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ fractionalSecond?: string; fractionalSecondDown?: string; fractionalSecondUp?: string; hour?: string; hourDown?: string; hourUp?: string; meridiem?: string; meridiemDown?: string; meridiemUp?: string; minute?: string; minuteDown?: string; minuteUp?: string; second?: string; secondDown?: string; secondUp?: string; }` | `undefined` | +| `numberingSystem` | `numbering-system` | Specifies the Unicode numeral system used by the component for localization. | `"arab" \| "arabext" \| "bali" \| "beng" \| "deva" \| "fullwide" \| "gujr" \| "guru" \| "hanidec" \| "khmr" \| "knda" \| "laoo" \| "latn" \| "limb" \| "mlym" \| "mong" \| "mymr" \| "orya" \| "tamldec" \| "telu" \| "thai" \| "tibt"` | `undefined` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `step` | `step` | Specifies the granularity the `value` must adhere to (in seconds). | `number` | `60` | +| `value` | `value` | The component's value in UTC (always 24-hour format). | `string` | `null` | ## Methods diff --git a/packages/calcite-components/src/components/tip-manager/readme.md b/packages/calcite-components/src/components/tip-manager/readme.md index 25b8a14a799..e475aad20b1 100644 --- a/packages/calcite-components/src/components/tip-manager/readme.md +++ b/packages/calcite-components/src/components/tip-manager/readme.md @@ -56,11 +56,11 @@ Renders a tip manager using a group of tips as well as a single tip. ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ----------------------------------------------------------------------- | ---------------------------- | ----------- | -| `closed` | `closed` | When `true`, does not display or position the component. | `boolean` | `false` | -| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `TipManagerMessages` | `undefined` | +| Property | Attribute | Description | Type | Default | +| ------------------ | --------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------- | +| `closed` | `closed` | When `true`, does not display or position the component. | `boolean` | `false` | +| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ defaultGroupTitle?: string; defaultPaginationLabel?: string; close?: string; previous?: string; next?: string; }` | `undefined` | ## Events diff --git a/packages/calcite-components/src/components/tip/readme.md b/packages/calcite-components/src/components/tip/readme.md index 12d633dd185..5702fd5794c 100644 --- a/packages/calcite-components/src/components/tip/readme.md +++ b/packages/calcite-components/src/components/tip/readme.md @@ -20,14 +20,14 @@ Renders a close-disabled tip with a heading, thumbnail, info and a link. ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ----------- | -| `closeDisabled` | `close-disabled` | When `true`, the close button is not present on the component. | `boolean` | `false` | -| `closed` | `closed` | When `true`, the component does not display. | `boolean` | `false` | -| `heading` | `heading` | The component header text. | `string` | `undefined` | -| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `TipMessages` | `undefined` | -| `selected` | `selected` | When `true`, the component is selected if it has a parent `calcite-tip-manager`. Only one tip can be selected within the `calcite-tip-manager` parent. | `boolean` | `false` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- | ----------- | +| `closeDisabled` | `close-disabled` | When `true`, the close button is not present on the component. | `boolean` | `false` | +| `closed` | `closed` | When `true`, the component does not display. | `boolean` | `false` | +| `heading` | `heading` | The component header text. | `string` | `undefined` | +| `headingLevel` | `heading-level` | Specifies the number at which section headings should start. | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `undefined` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ close?: string; }` | `undefined` | +| `selected` | `selected` | When `true`, the component is selected if it has a parent `calcite-tip-manager`. Only one tip can be selected within the `calcite-tip-manager` parent. | `boolean` | `false` | ## Events diff --git a/packages/calcite-components/src/components/tooltip/readme.md b/packages/calcite-components/src/components/tooltip/readme.md index 071cac4f4dc..e421ed63d8c 100644 --- a/packages/calcite-components/src/components/tooltip/readme.md +++ b/packages/calcite-components/src/components/tooltip/readme.md @@ -48,12 +48,12 @@ | Property | Attribute | Description | Type | Default | | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- | | `closeOnClick` | `close-on-click` | Closes the component when the `referenceElement` is clicked. | `boolean` | `false` | -| `label` _(required)_ | `label` | Accessible name for the component. | `string` | `undefined` | +| `label` | `label` | **[DEPRECATED]** No longer necessary. Overrides the context of the component's description, which could confuse assistive technology users.

Accessible name for the component. | `string` | `undefined` | | `offsetDistance` | `offset-distance` | Offset the position of the component away from the `referenceElement`. | `number` | `defaultOffsetDistance` | | `offsetSkidding` | `offset-skidding` | Offset the position of the component along the `referenceElement`. | `number` | `0` | | `open` | `open` | When `true`, the component is open. | `boolean` | `false` | | `overlayPositioning` | `overlay-positioning` | Determines the type of positioning to use for the overlaid content. Using `"absolute"` will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout. The `"fixed"` value should be used to escape an overflowing parent container, or when the reference element's `position` CSS property is `"fixed"`. | `"absolute" \| "fixed"` | `"absolute"` | -| `placement` | `placement` | Determines where the component will be positioned relative to the `referenceElement`. | `"auto" \| "top" \| "left" \| "right" \| "bottom-start" \| "leading-start" \| "bottom" \| "top-start" \| "top-end" \| "left-start" \| "left-end" \| "right-start" \| "right-end" \| "bottom-end" \| "auto-start" \| "auto-end" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `"auto"` | +| `placement` | `placement` | Determines where the component will be positioned relative to the `referenceElement`. | `"auto" \| "top" \| "right" \| "bottom" \| "left" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-start" \| "bottom-end" \| "left-start" \| "left-end" \| "auto-start" \| "auto-end" \| "leading-start" \| "leading" \| "leading-end" \| "trailing-end" \| "trailing" \| "trailing-start"` | `"auto"` | | `referenceElement` | `reference-element` | The `referenceElement` to position the component according to its `"placement"` value. Setting to the `HTMLElement` is preferred so the component does not need to query the DOM for the `referenceElement`. However, a string ID of the reference element can be used. | `Element \| VirtualElement \| string` | `undefined` | ## Events @@ -87,20 +87,6 @@ Type: `Promise` | --------------------------- | ----------------------------------------- | | `--calcite-tooltip-z-index` | Sets the z-index value for the component. | -## Dependencies - -### Used by - -- [calcite-flow-item](../flow-item) - -### Graph - -```mermaid -graph TD; - calcite-flow-item --> calcite-tooltip - style calcite-tooltip fill:#f9f,stroke:#333,stroke-width:4px -``` - --- _Built with [StencilJS](https://stenciljs.com/)_ diff --git a/packages/calcite-components/src/components/tree/readme.md b/packages/calcite-components/src/components/tree/readme.md index a96067adb4e..8f4bfbf3a57 100644 --- a/packages/calcite-components/src/components/tree/readme.md +++ b/packages/calcite-components/src/components/tree/readme.md @@ -26,12 +26,12 @@ ## Properties -| Property | Attribute | Description | Type | Default | -| --------------- | ---------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- | -| `lines` | `lines` | Displays indentation guide lines. | `boolean` | `false` | -| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | -| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteTreeItemElement[]` | `[]` | -| `selectionMode` | `selection-mode` | Customize how the component's selection works. | `"ancestors" \| "children" \| "multichildren" \| "multiple" \| "none" \| "single" \| "single-persist"` | `"single"` | +| Property | Attribute | Description | Type | Default | +| --------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- | +| `lines` | `lines` | Displays indentation guide lines. | `boolean` | `false` | +| `scale` | `scale` | Specifies the size of the component. | `"l" \| "m" \| "s"` | `"m"` | +| `selectedItems` | -- | Specifies the component's selected items. | `HTMLCalciteTreeItemElement[]` | `[]` | +| `selectionMode` | `selection-mode` | Specifies the selection mode, where `"ancestors"` displays with a checkbox and allows any number of selections from corresponding parent and child selections, `"children"` allows any number of selections from one parent from corresponding parent and child selections, `"multichildren"` allows any number of selections from corresponding parent and child selections, `"multiple"` allows any number of selections, `"none"` allows no selections, `"single"` allows one selection, and `"single-persist"` allows and requires one selection. | `"ancestors" \| "children" \| "multichildren" \| "multiple" \| "none" \| "single" \| "single-persist"` | `"single"` | ## Events diff --git a/packages/calcite-components/src/components/value-list-item/readme.md b/packages/calcite-components/src/components/value-list-item/readme.md index d73409c5519..f25d0377bf0 100644 --- a/packages/calcite-components/src/components/value-list-item/readme.md +++ b/packages/calcite-components/src/components/value-list-item/readme.md @@ -23,9 +23,10 @@ ## Events -| Event | Description | Type | -| ----------------------- | ---------------------------------------- | ------------------- | -| `calciteListItemRemove` | Fires when the remove button is pressed. | `CustomEvent` | +| Event | Description | Type | +| ----------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `calciteListItemChange` | Fires when the component is selected or unselected. | `CustomEvent<{ item: HTMLCalciteValueListItemElement; value: any; selected: boolean; shiftPressed: boolean; }>` | +| `calciteListItemRemove` | Fires when the remove button is pressed. | `CustomEvent` | ## Methods @@ -46,6 +47,13 @@ The first argument allows the value to be coerced, rather than swapping values. Type: `Promise` +## Slots + +| Slot | Description | +| ----------------- | ---------------------------------------------------------------------------------- | +| `"actions-end"` | A slot for adding `calcite-action`s or content to the end side of the component. | +| `"actions-start"` | A slot for adding `calcite-action`s or content to the start side of the component. | + ## Dependencies ### Depends on diff --git a/packages/calcite-components/src/components/value-list/readme.md b/packages/calcite-components/src/components/value-list/readme.md index b2f5c210577..45c1ba6bf11 100644 --- a/packages/calcite-components/src/components/value-list/readme.md +++ b/packages/calcite-components/src/components/value-list/readme.md @@ -46,20 +46,22 @@ Renders a value list with drag and drop capability between the items. ## Properties -| Property | Attribute | Description | Type | Default | -| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------- | -| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | -| `dragEnabled` | `drag-enabled` | When `true`, `calcite-value-list-item`s are sortable via a draggable button. | `boolean` | `false` | -| `filterEnabled` | `filter-enabled` | When `true`, an input appears at the top of the component that can be used by end users to filter list items. | `boolean` | `false` | -| `filterPlaceholder` | `filter-placeholder` | Placeholder text for the filter's input field. | `string` | `undefined` | -| `filterText` | `filter-text` | Text for the filter input field. | `string` | `undefined` | -| `filteredData` | -- | The currently filtered data. | `{ label: string; description: string; metadata: Record; value: string; }[]` | `[]` | -| `filteredItems` | -- | The currently filtered items. | `HTMLCalciteValueListItemElement[]` | `[]` | -| `group` | `group` | The component's group identifier. To drag elements from one list into another, both lists must have the same group value. | `string` | `undefined` | -| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | -| `messageOverrides` | `message-overrides` | Use this property to override individual strings used by the component. | `ValueListMessages` | `undefined` | -| `multiple` | `multiple` | Similar to standard radio buttons and checkboxes. When `true`, a user can select multiple `calcite-value-list-item`s at a time. When `false`, only a single `calcite-value-list-item` can be selected at a time, and a new selection will deselect previous selections. | `boolean` | `false` | -| `selectionFollowsFocus` | `selection-follows-focus` | When `true` and single-selection is enabled, the selection changes when navigating `calcite-value-list-item`s via keyboard. | `boolean` | `false` | +| Property | Attribute | Description | Type | Default | +| ----------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------- | +| `canPull` | -- | When provided, the method will be called to determine whether the element can move from the list. | `(detail: DragDetail) => boolean` | `undefined` | +| `canPut` | -- | When provided, the method will be called to determine whether the element can be added from another list. | `(detail: DragDetail) => boolean` | `undefined` | +| `disabled` | `disabled` | When `true`, interaction is prevented and the component is displayed with lower opacity. | `boolean` | `false` | +| `dragEnabled` | `drag-enabled` | When `true`, `calcite-value-list-item`s are sortable via a draggable button. | `boolean` | `false` | +| `filterEnabled` | `filter-enabled` | When `true`, an input appears at the top of the component that can be used by end users to filter list items. | `boolean` | `false` | +| `filterPlaceholder` | `filter-placeholder` | Placeholder text for the filter's input field. | `string` | `undefined` | +| `filterText` | `filter-text` | Text for the filter input field. | `string` | `undefined` | +| `filteredData` | -- | The currently filtered data. | `{ label: string; description: string; metadata: Record; value: string; }[]` | `[]` | +| `filteredItems` | -- | The currently filtered items. | `HTMLCalciteValueListItemElement[]` | `[]` | +| `group` | `group` | The component's group identifier. To drag elements from one list into another, both lists must have the same group value. | `string` | `undefined` | +| `loading` | `loading` | When `true`, a busy indicator is displayed. | `boolean` | `false` | +| `messageOverrides` | -- | Use this property to override individual strings used by the component. | `{ dragHandleActive?: string; dragHandleChange?: string; dragHandleCommit?: string; dragHandleIdle?: string; }` | `undefined` | +| `multiple` | `multiple` | Similar to standard radio buttons and checkboxes. When `true`, a user can select multiple `calcite-value-list-item`s at a time. When `false`, only a single `calcite-value-list-item` can be selected at a time, and a new selection will deselect previous selections. | `boolean` | `false` | +| `selectionFollowsFocus` | `selection-follows-focus` | When `true` and single-selection is enabled, the selection changes when navigating `calcite-value-list-item`s via keyboard. | `boolean` | `false` | ## Events @@ -87,6 +89,13 @@ Sets focus on the component's first focusable element. Type: `Promise` +## Slots + +| Slot | Description | +| ---------------- | -------------------------------------------------------------------------------------------------- | +| | A slot for adding `calcite-value-list-item` elements. List items are displayed as a vertical list. | +| `"menu-actions"` | A slot for adding a button and menu combination for performing actions, such as sorting. | + ## Dependencies ### Depends on