From 2f7273f6e590d9f12ed7e14964b0717a12c85436 Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:02:29 +0300 Subject: [PATCH 1/8] docs: typos, grammar and stylistics fixes and clarifications --- src/components/calendar/base.ts | 2 +- src/components/calendar/calendar.ts | 2 +- src/components/carousel/carousel.ts | 4 ++-- src/components/chat/types.ts | 2 +- src/components/combo/combo.ts | 6 +++--- src/components/combo/types.ts | 2 +- .../common/mixins/forms/associated.ts | 4 ++-- src/components/common/mixins/forms/types.ts | 6 +++--- src/components/date-picker/date-picker.ts | 8 ++++---- .../date-range-picker/date-range-picker.ts | 8 ++++---- src/components/dropdown/dropdown.ts | 6 +++--- src/components/file-input/file-input.ts | 8 +++----- src/components/input/input.ts | 8 ++++---- src/components/mask-input/mask-input.ts | 2 +- .../nav-drawer/nav-drawer-header-item.ts | 2 +- src/components/nav-drawer/nav-drawer-item.ts | 4 ++-- src/components/radio-group/radio-group.ts | 3 ++- src/components/radio/radio.ts | 4 ++-- src/components/rating/rating.ts | 2 +- src/components/ripple/ripple.ts | 2 +- src/components/select/select.ts | 4 ++-- src/components/stepper/stepper.ts | 2 +- src/components/textarea/textarea.ts | 4 ++-- src/components/tile-manager/tile.ts | 2 +- src/components/tooltip/tooltip.ts | 8 ++++---- stories/calendar.stories.ts | 4 ++-- stories/carousel.stories.ts | 4 ++-- stories/combo.stories.ts | 8 ++++---- stories/dropdown.stories.ts | 2 +- stories/file-input.stories.ts | 18 ++++++------------ stories/input.stories.ts | 18 +++++++++--------- stories/mask-input.stories.ts | 4 ++-- stories/radio-group.stories.ts | 7 +++++-- stories/ripple.stories.ts | 2 +- stories/select.stories.ts | 8 ++++---- stories/textarea.stories.ts | 6 +++--- stories/tooltip.stories.ts | 17 ++++++++--------- 37 files changed, 99 insertions(+), 104 deletions(-) diff --git a/src/components/calendar/base.ts b/src/components/calendar/base.ts index 2992641d4a..37642280df 100644 --- a/src/components/calendar/base.ts +++ b/src/components/calendar/base.ts @@ -86,7 +86,7 @@ export class IgcCalendarBaseComponent extends LitElement { /* blazorSuppress */ /** * The current values of the calendar. - * Used when selection is set to multiple of range. + * Used when selection is set to multiple or range. * * @attr values */ diff --git a/src/components/calendar/calendar.ts b/src/components/calendar/calendar.ts index c2ac098a50..c3e3f5d8ed 100644 --- a/src/components/calendar/calendar.ts +++ b/src/components/calendar/calendar.ts @@ -187,7 +187,7 @@ export default class IgcCalendarComponent extends EventEmitterMixin< //#region Public attributes and properties /** - * Whether to show the dates that do not belong to the current active month. + * Whether to hide the dates that do not belong to the current active month. * @attr hide-outside-days * @default false */ diff --git a/src/components/carousel/carousel.ts b/src/components/carousel/carousel.ts index 7b592d970b..d603673c45 100644 --- a/src/components/carousel/carousel.ts +++ b/src/components/carousel/carousel.ts @@ -273,7 +273,7 @@ export default class IgcCarouselComponent extends EventEmitterMixin< public interval: number | undefined; /** - * Controls the maximum indicator controls (dots) that can be shown. Default value is `10`. + * The maximum number of indicator controls (dots) that can be shown. Default value is `10`. * @attr maximum-indicators-count */ @property({ type: Number, attribute: 'maximum-indicators-count' }) @@ -701,7 +701,7 @@ export default class IgcCarouselComponent extends EventEmitterMixin< } /** - * Pauses the carousel rotation of slides. + * Pauses the rotation of the carousel slides. */ public pause(): void { if (this.isPlaying) { diff --git a/src/components/chat/types.ts b/src/components/chat/types.ts index 58cdb5e1af..1a574650d1 100644 --- a/src/components/chat/types.ts +++ b/src/components/chat/types.ts @@ -245,7 +245,7 @@ export interface ChatRenderers { */ message?: ChatTemplateRenderer; /** - * Custom renderer for message-specific actions (e.g., reply or delete buttons). + * Custom renderer for message-specific actions (e.g. reply or delete buttons). */ messageActions?: ChatTemplateRenderer; /** diff --git a/src/components/combo/combo.ts b/src/components/combo/combo.ts index 79bbd0e900..185aff4b4d 100644 --- a/src/components/combo/combo.ts +++ b/src/components/combo/combo.ts @@ -291,7 +291,7 @@ export default class IgcComboComponent< } /** - * The outlined attribute of the control. + * Whether the control has an outlined appearance. * @attr outlined * @default false */ @@ -322,7 +322,7 @@ export default class IgcComboComponent< } /** - * The autofocus attribute of the control. + * Whether the control should receive focus automatically. * @attr autofocus */ @property({ type: Boolean }) @@ -504,7 +504,7 @@ export default class IgcComboComponent< /** * Sets the value (selected items). The passed value must be a valid JSON array. * If the data source is an array of complex objects, the `valueKey` attribute must be set. - * Note that when `displayKey` is not explicitly set, it will fall back to the value of `valueKey`. + * Note that when `displayKey` is not explicitly set, it falls back to the value of `valueKey`. * * @attr value * diff --git a/src/components/combo/types.ts b/src/components/combo/types.ts index 000aee64a1..a9db021260 100644 --- a/src/components/combo/types.ts +++ b/src/components/combo/types.ts @@ -29,7 +29,7 @@ export interface FilteringOptions { filterKey: Keys | undefined; /** Determines whether the filtering operation should be case sensitive. */ caseSensitive?: boolean; - /** If true, the filter distinguishes between accented letters and their base letters */ + /** When true, the filter distinguishes between accented letters and their base letters. */ matchDiacritics?: boolean; } diff --git a/src/components/common/mixins/forms/associated.ts b/src/components/common/mixins/forms/associated.ts index e2ad60fcc9..e500936bf6 100644 --- a/src/components/common/mixins/forms/associated.ts +++ b/src/components/common/mixins/forms/associated.ts @@ -334,14 +334,14 @@ function BaseFormAssociated>(base: T) { //#region Public API - /** Checks for validity of the control and shows the browser message if it invalid. */ + /** Checks for validity of the control and shows the browser message if it's invalid. */ public reportValidity(): boolean { const state = this._internals.reportValidity(); this._invalid = !state; return state; } - /** Checks for validity of the control and emits the invalid event if it invalid. */ + /** Checks for validity of the control and emits the invalid event if it's invalid. */ public checkValidity(): boolean { this._isInternalValidation = true; const state = this._internals.checkValidity(); diff --git a/src/components/common/mixins/forms/types.ts b/src/components/common/mixins/forms/types.ts index acee915447..3cb9f35791 100644 --- a/src/components/common/mixins/forms/types.ts +++ b/src/components/common/mixins/forms/types.ts @@ -87,7 +87,7 @@ declare class BaseFormAssociatedElement { /** * Sets the default value of the component. - * Called in `attributeChangedCallback`(i.e. when the `value` attribute of the control is set). + * Called in `attributeChangedCallback` (i.e. when the `value` attribute of the control is set). */ protected _setDefaultValue(current: string | null): void; @@ -142,10 +142,10 @@ declare class BaseFormAssociatedElement { mode: FormRestoreMode ): void; - /** Checks for validity of the control and emits the invalid event if it invalid. */ + /** Checks for validity of the control and emits the invalid event if it's invalid. */ public checkValidity(): boolean; - /** Checks for validity of the control and shows the browser message if it invalid. */ + /** Checks for validity of the control and shows the browser message if it's invalid. */ public reportValidity(): boolean; /** diff --git a/src/components/date-picker/date-picker.ts b/src/components/date-picker/date-picker.ts index 03c11e667b..33a13334d5 100644 --- a/src/components/date-picker/date-picker.ts +++ b/src/components/date-picker/date-picker.ts @@ -117,10 +117,10 @@ type DatePickerResourceStringsType = IDatePickerResourceStrings & * @slot calendar-icon-open - Renders the icon/content for the picker in open state. * @slot actions - Renders content in the action part of the picker in open state. * - * @fires igcOpening - Emitted just before the calendar dropdown is shown. - * @fires igcOpened - Emitted after the calendar dropdown is shown. - * @fires igcClosing - Emitted just before the calendar dropdown is hidden. - * @fires igcClosed - Emitted after the calendar dropdown is hidden. + * @fires igcOpening - Emitted just before the calendar popover is shown. + * @fires igcOpened - Emitted after the calendar popover is shown. + * @fires igcClosing - Emitted just before the calendar popover is hidden. + * @fires igcClosed - Emitted after the calendar popover is hidden. * @fires igcChange - Emitted when the user modifies and commits the elements's value. * @fires igcInput - Emitted when when the user types in the element. * diff --git a/src/components/date-range-picker/date-range-picker.ts b/src/components/date-range-picker/date-range-picker.ts index 64b8479ee7..89a89e6afa 100644 --- a/src/components/date-range-picker/date-range-picker.ts +++ b/src/components/date-range-picker/date-range-picker.ts @@ -130,10 +130,10 @@ let nextId = 1; * @slot actions - Renders content in the action part of the picker in open state. * @slot separator - Renders the separator element between the two inputs. * - * @fires igcOpening - Emitted just before the calendar dropdown is shown. - * @fires igcOpened - Emitted after the calendar dropdown is shown. - * @fires igcClosing - Emitted just before the calendar dropdown is hidden. - * @fires igcClosed - Emitted after the calendar dropdown is hidden. + * @fires igcOpening - Emitted just before the calendar popover is shown. + * @fires igcOpened - Emitted after the calendar popover is shown. + * @fires igcClosing - Emitted just before the calendar popover is hidden. + * @fires igcClosed - Emitted after the calendar popover is hidden. * @fires igcChange - Emitted when the user modifies and commits the elements's value. * @fires igcInput - Emitted when when the user types in the element. * diff --git a/src/components/dropdown/dropdown.ts b/src/components/dropdown/dropdown.ts index 07be0bfb66..8e1257fe40 100644 --- a/src/components/dropdown/dropdown.ts +++ b/src/components/dropdown/dropdown.ts @@ -56,13 +56,13 @@ export interface IgcDropdownComponentEventMap { } /** - * Represents a DropDown component. + * Represents a Dropdown component. * * @element igc-dropdown * * @fires igcChange - Emitted when the selected item changes. - * @fires igcOpening - Emitted just before the dropdown is open. - * @fires igcOpened - Emitted after the dropdown is open. + * @fires igcOpening - Emitted just before the dropdown is opened. + * @fires igcOpened - Emitted after the dropdown is opened. * @fires igcClosing - Emitter just before the dropdown is closed. * @fires igcClosed - Emitted after closing the dropdown. * diff --git a/src/components/file-input/file-input.ts b/src/components/file-input/file-input.ts index f3379296d5..ac2d416e9f 100644 --- a/src/components/file-input/file-input.ts +++ b/src/components/file-input/file-input.ts @@ -172,8 +172,7 @@ export default class IgcFileInputComponent extends EventEmitterMixin< } /** - * The multiple attribute of the control. - * Used to indicate that a file input allows the user to select more than one file. + * Whether the control allows the user to select more than one file. * * @attr * @default false @@ -182,15 +181,14 @@ export default class IgcFileInputComponent extends EventEmitterMixin< public multiple = false; /** - * The accept attribute of the control. - * Defines the file types as a list of comma-separated values that the file input should accept. + * The file types the control accepts, as a comma-separated list. * @attr */ @property() public accept = ''; /** - * The autofocus attribute of the control. + * Whether the control should receive focus automatically. * @attr */ @property({ type: Boolean }) diff --git a/src/components/input/input.ts b/src/components/input/input.ts index c3894b7b2b..1f849e1715 100644 --- a/src/components/input/input.ts +++ b/src/components/input/input.ts @@ -125,7 +125,7 @@ export default class IgcInputComponent extends IgcInputBaseComponent { public readOnly = false; /** - * The input mode attribute of the control. + * A hint to the browser for which virtual keyboard layout to display. * See [relevant MDN article](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode) * @attr inputmode */ @@ -133,7 +133,7 @@ export default class IgcInputComponent extends IgcInputBaseComponent { public override inputMode!: string; /** - * The pattern attribute of the control. + * The regular expression the value is validated against. * @attr */ @property() @@ -217,14 +217,14 @@ export default class IgcInputComponent extends IgcInputBaseComponent { } /** - * The autofocus attribute of the control. + * Whether the control should receive focus automatically. * @attr */ @property({ type: Boolean }) public override autofocus!: boolean; /** - * The autocomplete attribute of the control. + * A hint for the browser on how to autofill the control. * @attr */ @property() diff --git a/src/components/mask-input/mask-input.ts b/src/components/mask-input/mask-input.ts index e95f9ce28b..0a7e0f0651 100644 --- a/src/components/mask-input/mask-input.ts +++ b/src/components/mask-input/mask-input.ts @@ -114,7 +114,7 @@ export default class IgcMaskInputComponent extends MaskBehaviorMixin( /** * The value of the input. * - * Regardless of the currently set `value-mode`, an empty value will return an empty string. + * Regardless of the currently set `value-mode`, an empty value returns an empty string. * * @attr */ diff --git a/src/components/nav-drawer/nav-drawer-header-item.ts b/src/components/nav-drawer/nav-drawer-header-item.ts index 4b7a2a4e91..80b30b3ea9 100644 --- a/src/components/nav-drawer/nav-drawer-header-item.ts +++ b/src/components/nav-drawer/nav-drawer-header-item.ts @@ -7,7 +7,7 @@ import { all } from './themes/header-item.js'; import { styles as shared } from './themes/shared/header-item/header-item.common.css.js'; /** - * A wrapper for navigation drawer's header. + * Represents a navigation drawer header item. * @element igc-nav-drawer-header-item * * @slot - Renders the header content diff --git a/src/components/nav-drawer/nav-drawer-item.ts b/src/components/nav-drawer/nav-drawer-item.ts index 813a9fcd2f..e5e35f1044 100644 --- a/src/components/nav-drawer/nav-drawer-item.ts +++ b/src/components/nav-drawer/nav-drawer-item.ts @@ -38,14 +38,14 @@ export default class IgcNavDrawerItemComponent extends LitElement { private _hasContent = true; /** - * Determines whether the drawer is disabled. + * Determines whether the drawer item is disabled. * @attr */ @property({ type: Boolean, reflect: true }) public disabled = false; /** - * Determines whether the drawer is active. + * Determines whether the drawer item is active. * @attr */ @property({ type: Boolean, reflect: true }) diff --git a/src/components/radio-group/radio-group.ts b/src/components/radio-group/radio-group.ts index d7fdf8ecea..c9de75f58e 100644 --- a/src/components/radio-group/radio-group.ts +++ b/src/components/radio-group/radio-group.ts @@ -79,7 +79,8 @@ export default class IgcRadioGroupComponent extends LitElement { /* @tsTwoWayProperty(true, "igcChange", "detail.value", false) */ /** - * Gets/Sets the checked igc-radio element that matches `value` + * The value of the group, reflecting the value of the currently checked radio button. + * Setting it checks the radio button in the group with a matching value. * @attr */ @property() diff --git a/src/components/radio/radio.ts b/src/components/radio/radio.ts index 7ed0b4a0ad..e5597d1442 100644 --- a/src/components/radio/radio.ts +++ b/src/components/radio/radio.ts @@ -240,7 +240,7 @@ export default class IgcRadioComponent extends FormAssociatedCheckboxRequiredMix return super.reportValidity(); } - /** Checks for validity of the control and emits the invalid event if it invalid. */ + /** Checks for validity of the control and emits the invalid event if it's invalid. */ public override checkValidity(): boolean { for (const radio of this._siblings) { radio._checkValidity(); @@ -249,7 +249,7 @@ export default class IgcRadioComponent extends FormAssociatedCheckboxRequiredMix return this._checkValidity(); } - /** Checks for validity of the control and shows the browser message if it invalid. */ + /** Checks for validity of the control and shows the browser message if it's invalid. */ public override reportValidity(): boolean { for (const radio of this._siblings) { radio._reportValidity(); diff --git a/src/components/rating/rating.ts b/src/components/rating/rating.ts index 37dd626021..8fe5821e15 100644 --- a/src/components/rating/rating.ts +++ b/src/components/rating/rating.ts @@ -222,7 +222,7 @@ export default class IgcRatingComponent extends FormAssociatedMixin( /* @tsTwoWayProperty(true, "igcChange", "detail", false) */ /** - * The current value of the component + * The value of the component * @attr value * @default 0 */ diff --git a/src/components/ripple/ripple.ts b/src/components/ripple/ripple.ts index a35f3da16d..4833b0bb82 100644 --- a/src/components/ripple/ripple.ts +++ b/src/components/ripple/ripple.ts @@ -29,7 +29,7 @@ function getRippleElement(): HTMLSpanElement { /** * A ripple can be applied to an element to represent - * interactive surface. + * an interactive surface. * * @element igc-ripple */ diff --git a/src/components/select/select.ts b/src/components/select/select.ts index 9b72ffdef8..9d1c4732c9 100644 --- a/src/components/select/select.ts +++ b/src/components/select/select.ts @@ -206,14 +206,14 @@ export default class IgcSelectComponent extends FormAssociatedRequiredMixin( } /** - * The outlined attribute of the control. + * Whether the control has an outlined appearance. * @attr */ @property({ reflect: true, type: Boolean }) public outlined = false; /** - * The autofocus attribute of the control. + * Whether the control should receive focus automatically. * @attr */ @property({ type: Boolean }) diff --git a/src/components/stepper/stepper.ts b/src/components/stepper/stepper.ts index 97a212bfb8..b407b3e653 100644 --- a/src/components/stepper/stepper.ts +++ b/src/components/stepper/stepper.ts @@ -491,7 +491,7 @@ export default class IgcStepperComponent extends EventEmitterMixin< } /** - * Resets the stepper to its initial state i.e. activates the first step. + * Resets the stepper to its initial state, i.e. activates the first step. * * @remarks * The steps' content will not be automatically reset. diff --git a/src/components/textarea/textarea.ts b/src/components/textarea/textarea.ts index 50e5e75c05..3bacc65928 100644 --- a/src/components/textarea/textarea.ts +++ b/src/components/textarea/textarea.ts @@ -60,7 +60,7 @@ const Slots = setSlots( ); /** - * This element represents a multi-line plain-text editing control, + * Represents a multi-line plain-text editing control, * useful when you want to allow users to enter a sizeable amount of free-form text, * for example a comment on a review or feedback form. * @@ -127,7 +127,7 @@ export default class IgcTextareaComponent extends FormAssociatedRequiredMixin( //#region Public properties and attributes /** - * Specifies what if any permission the browser has to provide for automated assistance in filling out form field values, + * Specifies what permission, if any, the browser has to provide automated assistance in filling out form field values, * as well as guidance to the browser as to the type of information expected in the field. * Refer to [this page](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for additional information. * diff --git a/src/components/tile-manager/tile.ts b/src/components/tile-manager/tile.ts index 80be4232e7..9a9790b6af 100644 --- a/src/components/tile-manager/tile.ts +++ b/src/components/tile-manager/tile.ts @@ -313,7 +313,7 @@ export default class IgcTileComponent extends EventEmitterMixin< /** * Indicates whether to disable tile resize behavior regardless - * ot its tile manager parent settings. + * of its tile manager parent settings. * * @attr disable-resize * @default false diff --git a/src/components/tooltip/tooltip.ts b/src/components/tooltip/tooltip.ts index 6e69935bd7..d3659ec52d 100644 --- a/src/components/tooltip/tooltip.ts +++ b/src/components/tooltip/tooltip.ts @@ -167,7 +167,7 @@ export default class IgcTooltipComponent extends EventEmitterMixin< public offset = 6; /** - * Where to place the floating element relative to the parent anchor element. + * Where to place the tooltip relative to its anchor element. * * @attr placement * @default bottom @@ -189,7 +189,7 @@ export default class IgcTooltipComponent extends EventEmitterMixin< /** * Which event triggers will show the tooltip. - * Expects a comma separate string of different event triggers. + * Expects a comma separated string of different event triggers. * * @attr show-triggers * @default pointerenter @@ -205,7 +205,7 @@ export default class IgcTooltipComponent extends EventEmitterMixin< /** * Which event triggers will hide the tooltip. - * Expects a comma separate string of different event triggers. + * Expects a comma separated string of different event triggers. * * @attr hide-triggers * @default pointerleave, click @@ -250,7 +250,7 @@ export default class IgcTooltipComponent extends EventEmitterMixin< } /** - * Specifies a plain text as tooltip content. + * Specifies plain text as the tooltip content. * * @attr message */ diff --git a/stories/calendar.stories.ts b/stories/calendar.stories.ts index 235669f4f9..4e663e41d8 100644 --- a/stories/calendar.stories.ts +++ b/stories/calendar.stories.ts @@ -29,7 +29,7 @@ const metadata: Meta = { hideOutsideDays: { type: 'boolean', description: - 'Whether to show the dates that do not belong to the current active month.', + 'Whether to hide the dates that do not belong to the current active month.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, @@ -131,7 +131,7 @@ const metadata: Meta = { export default metadata; interface IgcCalendarArgs { - /** Whether to show the dates that do not belong to the current active month. */ + /** Whether to hide the dates that do not belong to the current active month. */ hideOutsideDays: boolean; /** * Whether to render the calendar header part. diff --git a/stories/carousel.stories.ts b/stories/carousel.stories.ts index 841c83ae57..7a2f09f996 100644 --- a/stories/carousel.stories.ts +++ b/stories/carousel.stories.ts @@ -96,7 +96,7 @@ const metadata: Meta = { maximumIndicatorsCount: { type: 'number', description: - 'Controls the maximum indicator controls (dots) that can be shown. Default value is `10`.', + 'The maximum number of indicator controls (dots) that can be shown. Default value is `10`.', control: 'number', table: { defaultValue: { summary: '10' } }, }, @@ -155,7 +155,7 @@ interface IgcCarouselArgs { slidesLabelFormat: string; /** The duration in milliseconds between changing the active slide. */ interval: number; - /** Controls the maximum indicator controls (dots) that can be shown. Default value is `10`. */ + /** The maximum number of indicator controls (dots) that can be shown. Default value is `10`. */ maximumIndicatorsCount: number; /** The animation type. */ animationType: 'slide' | 'fade' | 'none'; diff --git a/stories/combo.stories.ts b/stories/combo.stories.ts index aa69db45bb..9b95983cd4 100644 --- a/stories/combo.stories.ts +++ b/stories/combo.stories.ts @@ -46,7 +46,7 @@ const metadata: Meta = { argTypes: { outlined: { type: 'boolean', - description: 'The outlined attribute of the control.', + description: 'Whether the control has an outlined appearance.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, @@ -59,7 +59,7 @@ const metadata: Meta = { }, autofocus: { type: 'boolean', - description: 'The autofocus attribute of the control.', + description: 'Whether the control should receive focus automatically.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, @@ -184,11 +184,11 @@ const metadata: Meta = { export default metadata; interface IgcComboArgs { - /** The outlined attribute of the control. */ + /** Whether the control has an outlined appearance. */ outlined: boolean; /** Enables single selection mode and moves item filtering to the main input. */ singleSelect: boolean; - /** The autofocus attribute of the control. */ + /** Whether the control should receive focus automatically. */ autofocus: boolean; /** Focuses the list of options when the menu opens. */ autofocusList: boolean; diff --git a/stories/dropdown.stories.ts b/stories/dropdown.stories.ts index 9074dc4225..ad94835575 100644 --- a/stories/dropdown.stories.ts +++ b/stories/dropdown.stories.ts @@ -31,7 +31,7 @@ const metadata: Meta = { title: 'Dropdown', component: 'igc-dropdown', parameters: { - docs: { description: { component: 'Represents a DropDown component.' } }, + docs: { description: { component: 'Represents a Dropdown component.' } }, actions: { handles: [ 'igcChange', diff --git a/stories/file-input.stories.ts b/stories/file-input.stories.ts index 1f10314e8a..3bbe77c48d 100644 --- a/stories/file-input.stories.ts +++ b/stories/file-input.stories.ts @@ -46,20 +46,20 @@ const metadata: Meta = { multiple: { type: 'boolean', description: - 'The multiple attribute of the control.\nUsed to indicate that a file input allows the user to select more than one file.', + 'Whether the control allows the user to select more than one file.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, accept: { type: 'string', description: - 'The accept attribute of the control.\nDefines the file types as a list of comma-separated values that the file input should accept.', + 'The file types the control accepts, as a comma-separated list.', control: 'text', table: { defaultValue: { summary: '' } }, }, autofocus: { type: 'boolean', - description: 'The autofocus attribute of the control.', + description: 'Whether the control should receive focus automatically.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, @@ -125,17 +125,11 @@ interface IgcFileInputArgs { value: string; /** Gets/Sets the locale used for getting language, affecting resource strings. */ locale: string; - /** - * The multiple attribute of the control. - * Used to indicate that a file input allows the user to select more than one file. - */ + /** Whether the control allows the user to select more than one file. */ multiple: boolean; - /** - * The accept attribute of the control. - * Defines the file types as a list of comma-separated values that the file input should accept. - */ + /** The file types the control accepts, as a comma-separated list. */ accept: string; - /** The autofocus attribute of the control. */ + /** Whether the control should receive focus automatically. */ autofocus: boolean; /** When set, makes the component a required field for validation. */ required: boolean; diff --git a/stories/input.stories.ts b/stories/input.stories.ts index 5b403d99a9..e4cacd8408 100644 --- a/stories/input.stories.ts +++ b/stories/input.stories.ts @@ -52,12 +52,12 @@ const metadata: Meta = { inputMode: { type: 'string', description: - 'The input mode attribute of the control.\nSee [relevant MDN article](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode)', + 'A hint to the browser for which virtual keyboard layout to display.\nSee [relevant MDN article](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode)', control: 'text', }, pattern: { type: 'string', - description: 'The pattern attribute of the control.', + description: 'The regular expression the value is validated against.', control: 'text', }, minLength: { @@ -82,18 +82,18 @@ const metadata: Meta = { }, step: { type: 'number', - description: 'The step attribute of the control.', + description: 'The granularity the value must adhere to.', control: 'number', }, autofocus: { type: 'boolean', - description: 'The autofocus attribute of the control.', + description: 'Whether the control should receive focus automatically.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, autocomplete: { type: 'string', - description: 'The autocomplete attribute of the control.', + description: 'A hint for the browser on how to autofill the control.', control: 'text', }, validateOnly: { @@ -166,11 +166,11 @@ interface IgcInputArgs { /** Makes the control a readonly field. */ readOnly: boolean; /** - * The input mode attribute of the control. + * A hint to the browser for which virtual keyboard layout to display. * See [relevant MDN article](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode) */ inputMode: string; - /** The pattern attribute of the control. */ + /** The regular expression the value is validated against. */ pattern: string; /** The minimum string length required by the control. */ minLength: number; @@ -182,9 +182,9 @@ interface IgcInputArgs { max: number; /** The step attribute of the control. */ step: number; - /** The autofocus attribute of the control. */ + /** Whether the control should receive focus automatically. */ autofocus: boolean; - /** The autocomplete attribute of the control. */ + /** A hint for the browser on how to autofill the control. */ autocomplete: string; /** * Enables validation rules to be evaluated without restricting user input. This applies to the `maxLength` property for diff --git a/stories/mask-input.stories.ts b/stories/mask-input.stories.ts index 2efaf22e97..6465c89327 100644 --- a/stories/mask-input.stories.ts +++ b/stories/mask-input.stories.ts @@ -43,7 +43,7 @@ const metadata: Meta = { value: { type: 'string', description: - 'The value of the input.\n\nRegardless of the currently set `value-mode`, an empty value will return an empty string.', + 'The value of the input.\n\nRegardless of the currently set `value-mode`, an empty value returns an empty string.', control: 'text', }, mask: { @@ -133,7 +133,7 @@ interface IgcMaskInputArgs { /** * The value of the input. * - * Regardless of the currently set `value-mode`, an empty value will return an empty string. + * Regardless of the currently set `value-mode`, an empty value returns an empty string. */ value: string; /** The masked pattern of the component. */ diff --git a/stories/radio-group.stories.ts b/stories/radio-group.stories.ts index 8b230ccbee..5c50a7e6d4 100644 --- a/stories/radio-group.stories.ts +++ b/stories/radio-group.stories.ts @@ -43,7 +43,7 @@ const metadata: Meta = { value: { type: 'string', description: - 'Gets/Sets the checked igc-radio element that matches `value`', + 'The value of the group, reflecting the value of the currently checked radio button.\nSetting it checks the radio button in the group with a matching value.', control: 'text', }, }, @@ -57,7 +57,10 @@ interface IgcRadioGroupArgs { alignment: 'horizontal' | 'vertical'; /** Gets/Sets the name for all child igc-radio components. */ name: string; - /** Gets/Sets the checked igc-radio element that matches `value` */ + /** + * The value of the group, reflecting the value of the currently checked radio button. + * Setting it checks the radio button in the group with a matching value. + */ value: string; } type Story = StoryObj; diff --git a/stories/ripple.stories.ts b/stories/ripple.stories.ts index e2a8d3536a..9e27e6bb07 100644 --- a/stories/ripple.stories.ts +++ b/stories/ripple.stories.ts @@ -17,7 +17,7 @@ const metadata: Meta = { docs: { description: { component: - 'A ripple can be applied to an element to represent\ninteractive surface.', + 'A ripple can be applied to an element to represent\nan interactive surface.', }, }, }, diff --git a/stories/select.stories.ts b/stories/select.stories.ts index 5406785d3a..b50e9230cd 100644 --- a/stories/select.stories.ts +++ b/stories/select.stories.ts @@ -51,13 +51,13 @@ const metadata: Meta = { }, outlined: { type: 'boolean', - description: 'The outlined attribute of the control.', + description: 'Whether the control has an outlined appearance.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, autofocus: { type: 'boolean', - description: 'The autofocus attribute of the control.', + description: 'Whether the control should receive focus automatically.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, @@ -171,9 +171,9 @@ export default metadata; interface IgcSelectArgs { /** The value attribute of the control. */ value: string; - /** The outlined attribute of the control. */ + /** Whether the control has an outlined appearance. */ outlined: boolean; - /** The autofocus attribute of the control. */ + /** Whether the control should receive focus automatically. */ autofocus: boolean; /** The distance of the select dropdown from its input. */ distance: number; diff --git a/stories/textarea.stories.ts b/stories/textarea.stories.ts index dc02d45c2e..a2f785c273 100644 --- a/stories/textarea.stories.ts +++ b/stories/textarea.stories.ts @@ -26,7 +26,7 @@ const metadata: Meta = { docs: { description: { component: - 'This element represents a multi-line plain-text editing control,\nuseful when you want to allow users to enter a sizeable amount of free-form text,\nfor example a comment on a review or feedback form.', + 'Represents a multi-line plain-text editing control,\nuseful when you want to allow users to enter a sizeable amount of free-form text,\nfor example a comment on a review or feedback form.', }, }, actions: { handles: ['igcInput', 'igcChange'] }, @@ -35,7 +35,7 @@ const metadata: Meta = { autocomplete: { type: 'string', description: - 'Specifies what if any permission the browser has to provide for automated assistance in filling out form field values,\nas well as guidance to the browser as to the type of information expected in the field.\nRefer to [this page](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for additional information.', + 'Specifies what permission, if any, the browser has to provide automated assistance in filling out form field values,\nas well as guidance to the browser as to the type of information expected in the field.\nRefer to [this page](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for additional information.', control: 'text', }, autocapitalize: { @@ -169,7 +169,7 @@ export default metadata; interface IgcTextareaArgs { /** - * Specifies what if any permission the browser has to provide for automated assistance in filling out form field values, + * Specifies what permission, if any, the browser has to provide automated assistance in filling out form field values, * as well as guidance to the browser as to the type of information expected in the field. * Refer to [this page](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) for additional information. */ diff --git a/stories/tooltip.stories.ts b/stories/tooltip.stories.ts index 13c10f9005..204294de11 100644 --- a/stories/tooltip.stories.ts +++ b/stories/tooltip.stories.ts @@ -59,8 +59,7 @@ const metadata: Meta = { }, placement: { type: '"top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "right" | "right-start" | "right-end" | "left" | "left-start" | "left-end"', - description: - 'Where to place the floating element relative to the parent anchor element.', + description: 'Where to place the tooltip relative to its anchor element.', options: [ 'top', 'top-start', @@ -88,14 +87,14 @@ const metadata: Meta = { showTriggers: { type: 'string', description: - 'Which event triggers will show the tooltip.\nExpects a comma separate string of different event triggers.', + 'Which event triggers will show the tooltip.\nExpects a comma separated string of different event triggers.', control: 'text', table: { defaultValue: { summary: 'pointerenter' } }, }, hideTriggers: { type: 'string', description: - 'Which event triggers will hide the tooltip.\nExpects a comma separate string of different event triggers.', + 'Which event triggers will hide the tooltip.\nExpects a comma separated string of different event triggers.', control: 'text', table: { defaultValue: { summary: 'pointerleave, click' } }, }, @@ -115,7 +114,7 @@ const metadata: Meta = { }, message: { type: 'string', - description: 'Specifies a plain text as tooltip content.', + description: 'Specifies plain text as the tooltip content.', control: 'text', table: { defaultValue: { summary: '' } }, }, @@ -150,7 +149,7 @@ interface IgcTooltipArgs { withArrow: boolean; /** The offset of the tooltip from the anchor in pixels. */ offset: number; - /** Where to place the floating element relative to the parent anchor element. */ + /** Where to place the tooltip relative to its anchor element. */ placement: | 'top' | 'top-start' @@ -168,19 +167,19 @@ interface IgcTooltipArgs { anchor: Element | string; /** * Which event triggers will show the tooltip. - * Expects a comma separate string of different event triggers. + * Expects a comma separated string of different event triggers. */ showTriggers: string; /** * Which event triggers will hide the tooltip. - * Expects a comma separate string of different event triggers. + * Expects a comma separated string of different event triggers. */ hideTriggers: string; /** Specifies the number of milliseconds that should pass before showing the tooltip. */ showDelay: number; /** Specifies the number of milliseconds that should pass before hiding the tooltip. */ hideDelay: number; - /** Specifies a plain text as tooltip content. */ + /** Specifies plain text as the tooltip content. */ message: string; /** Specifies if the tooltip remains visible until the user closes it via the close button or Esc key. */ sticky: boolean; From 22360e46765aa3faba180c3f46447717a11e04ef Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:15:19 +0300 Subject: [PATCH 2/8] docs: cleanup explicit igc- tags from descriptions --- src/components/accordion/accordion.ts | 2 +- src/components/badge/badge.ts | 2 +- src/components/button-group/button-group.ts | 4 +-- src/components/button-group/toggle-button.ts | 4 +-- src/components/button/button.ts | 6 ++-- src/components/card/card.content.ts | 2 +- src/components/card/card.media.ts | 2 +- src/components/card/card.ts | 2 +- src/components/carousel/carousel-indicator.ts | 2 +- src/components/carousel/carousel-slide.ts | 2 +- src/components/carousel/carousel.ts | 4 +-- src/components/chat/chat-input.ts | 6 ++-- src/components/chat/chat-message.ts | 2 +- src/components/chat/chat.ts | 2 +- src/components/date-picker/date-picker.ts | 2 +- .../date-range-picker/date-range-picker.ts | 2 +- .../predefined-ranges-area.ts | 2 +- src/components/divider/divider.ts | 3 +- src/components/dropdown/dropdown-group.ts | 4 +-- src/components/dropdown/dropdown-header.ts | 2 +- src/components/dropdown/dropdown-item.ts | 6 ++-- src/components/icon/icon.ts | 2 +- src/components/icon/registry/types.ts | 2 +- src/components/progress/circular-gradient.ts | 4 +-- src/components/progress/circular-progress.ts | 28 +++++++++---------- src/components/progress/linear-progress.ts | 22 +++++++-------- src/components/radio-group/radio-group.ts | 4 +-- src/components/rating/rating-symbol.ts | 2 +- src/components/rating/rating.ts | 2 +- src/components/select/select-group.ts | 2 +- src/components/select/select-header.ts | 2 +- src/components/select/select-item.ts | 6 ++-- src/components/select/select.ts | 18 ++++++------ src/components/splitter/splitter.ts | 2 +- src/components/stepper/step.ts | 2 +- src/components/stepper/stepper.ts | 4 +-- src/components/tabs/tab.ts | 2 +- src/components/tabs/tabs.ts | 4 +-- src/components/textarea/textarea.ts | 10 +++---- src/components/tile-manager/tile-manager.ts | 2 +- src/components/tile-manager/tile.ts | 2 +- src/extras/chat-markdown-renderer.ts | 2 +- stories/button-group.stories.ts | 2 +- stories/carousel.stories.ts | 2 +- stories/date-range-picker.stories.ts | 2 +- stories/divider.stories.ts | 2 +- stories/radio-group.stories.ts | 7 ++--- stories/splitter.stories.ts | 2 +- stories/tabs.stories.ts | 2 +- 49 files changed, 103 insertions(+), 103 deletions(-) diff --git a/src/components/accordion/accordion.ts b/src/components/accordion/accordion.ts index 5d4f3198cb..0bd5f621df 100644 --- a/src/components/accordion/accordion.ts +++ b/src/components/accordion/accordion.ts @@ -59,7 +59,7 @@ export default class IgcAccordionComponent extends LitElement { public singleExpand = false; /* blazorSuppress */ - /** Returns all of the accordions's direct igc-expansion-panel children. */ + /** Returns all of the direct expansion panel children of the accordion. */ public get panels(): IgcExpansionPanelComponent[] { return Array.from(this._panels); } diff --git a/src/components/badge/badge.ts b/src/components/badge/badge.ts index 6b43bab4dc..dd320a09ce 100644 --- a/src/components/badge/badge.ts +++ b/src/components/badge/badge.ts @@ -19,7 +19,7 @@ import { all } from './themes/themes.js'; * @slot - Default slot for the badge content. * * @csspart base - The base wrapper of the badge. - * @csspart icon - The icon container, present when an igc-icon element is slotted. + * @csspart icon - The icon container, present when an icon element is slotted. * * @example * ```html diff --git a/src/components/button-group/button-group.ts b/src/components/button-group/button-group.ts index 8c1a765e54..15126cdf60 100644 --- a/src/components/button-group/button-group.ts +++ b/src/components/button-group/button-group.ts @@ -24,11 +24,11 @@ export interface IgcButtonGroupComponentEventMap { /* blazorAdditionalDependency: IgcToggleButtonComponent */ /** - * The `igc-button-group` groups a series of `igc-toggle-button`s together, exposing features such as layout and selection. + * Groups a series of toggle buttons together, exposing features such as layout and selection. * * @element igc-button-group * - * @slot - Renders `igc-toggle-button` component. + * @slot - Renders the toggle buttons of the group. * * @fires igcSelect - Emitted when a button is selected through user interaction. * @fires igcDeselect - Emitted when a button is deselected through user interaction. diff --git a/src/components/button-group/toggle-button.ts b/src/components/button-group/toggle-button.ts index 3bf9593292..acd2757c9e 100644 --- a/src/components/button-group/toggle-button.ts +++ b/src/components/button-group/toggle-button.ts @@ -11,8 +11,8 @@ import { all } from './themes/button.js'; import { styles as shared } from './themes/shared/button/button.common.css.js'; /** - * The `igc-toggle-button` wraps a native button element and exposes additional `value` and `selected` properties. - * It is used in the context of an `igc-button-group` to facilitate the creation of group/toolbar like UX behaviors. + * The toggle button wraps a native button element and exposes additional `value` and `selected` properties. + * It is used in the context of a button group to facilitate the creation of group/toolbar like UX behaviors. * * @element igc-toggle-button * diff --git a/src/components/button/button.ts b/src/components/button/button.ts index 6ade386922..efd6b635c6 100644 --- a/src/components/button/button.ts +++ b/src/components/button/button.ts @@ -23,9 +23,9 @@ import { all } from './themes/button/themes.js'; * @slot prefix - Renders content before the label of the button. * @slot suffix - Renders content after the label of the button. * - * @csspart base - The native button element of the igc-button component. - * @csspart prefix - The prefix container of the igc-button component. - * @csspart suffix - The suffix container of the igc-button component. + * @csspart base - The native button element of the button component. + * @csspart prefix - The prefix container of the button component. + * @csspart suffix - The suffix container of the button component. */ export default class IgcButtonComponent extends IgcButtonBaseComponent { public static readonly tagName = 'igc-button'; diff --git a/src/components/card/card.content.ts b/src/components/card/card.content.ts index d1ec0e23d6..658da3690d 100644 --- a/src/components/card/card.content.ts +++ b/src/components/card/card.content.ts @@ -8,7 +8,7 @@ import { styles as shared } from './themes/shared/content/card.content.common.cs /** * A container component for the card's main text content. - * This component should be used within an igc-card element to display the primary content. + * This component should be used within a card to display the primary content. * * @element igc-card-content * diff --git a/src/components/card/card.media.ts b/src/components/card/card.media.ts index 09b6ffcb94..35b4feca71 100644 --- a/src/components/card/card.media.ts +++ b/src/components/card/card.media.ts @@ -5,7 +5,7 @@ import { styles } from './themes/card.media.base.css.js'; /** * A container component for card media content such as images, GIFs, or videos. - * This component should be used within an igc-card element to display visual content. + * This component should be used within a card to display visual content. * * @element igc-card-media * diff --git a/src/components/card/card.ts b/src/components/card/card.ts index cabd897634..2a7e325715 100644 --- a/src/components/card/card.ts +++ b/src/components/card/card.ts @@ -18,7 +18,7 @@ import { styles as shared } from './themes/shared/container/card.common.css.js'; * * @element igc-card * - * @slot - Renders the card content. Typically contains igc-card-header, igc-card-media, igc-card-content, and igc-card-actions. + * @slot - Renders the card content. Typically contains the card header, media, content and actions. * * @example * ```html diff --git a/src/components/carousel/carousel-indicator.ts b/src/components/carousel/carousel-indicator.ts index b7b8e05e90..a020363f4b 100644 --- a/src/components/carousel/carousel-indicator.ts +++ b/src/components/carousel/carousel-indicator.ts @@ -10,7 +10,7 @@ import type IgcCarouselComponent from './carousel.js'; import { styles } from './themes/carousel-indicator.base.css.js'; /** - * Used when a custom indicator needs to be passed to the `igc-carousel` component. + * Used when a custom indicator needs to be passed to the carousel component. * * @element igc-carousel-indicator * diff --git a/src/components/carousel/carousel-slide.ts b/src/components/carousel/carousel-slide.ts index bee2938c7c..96cacfc490 100644 --- a/src/components/carousel/carousel-slide.ts +++ b/src/components/carousel/carousel-slide.ts @@ -14,7 +14,7 @@ import { styles } from './themes/carousel-slide.base.css.js'; let nextId = 1; /** - * A single content container within a set of containers used in the context of an `igc-carousel`. + * A single content container within a set of containers used in the context of a carousel. * * @element igc-carousel-slide * diff --git a/src/components/carousel/carousel.ts b/src/components/carousel/carousel.ts index d603673c45..df4010ca48 100644 --- a/src/components/carousel/carousel.ts +++ b/src/components/carousel/carousel.ts @@ -73,11 +73,11 @@ let nextId = 1; const Slots = setSlots('indicator', 'previous-button', 'next-button'); /** - * The `igc-carousel` presents a set of `igc-carousel-slide`s by sequentially displaying a subset of one or more slides. + * The carousel presents a set of slides by sequentially displaying a subset of one or more. * * @element igc-carousel * - * @slot Default slot for the carousel. Any projected `igc-carousel-slide` components should be projected here. + * @slot Default slot for the carousel. Any carousel slides should be projected here. * @slot previous-button - Renders content inside the previous button. * @slot next-button - Renders content inside the next button. * diff --git a/src/components/chat/chat-input.ts b/src/components/chat/chat-input.ts index 57f7996d98..1c13ad3bf6 100644 --- a/src/components/chat/chat-input.ts +++ b/src/components/chat/chat-input.ts @@ -43,7 +43,7 @@ type DefaultInputRenderers = { /* blazorSuppress */ /** - * A web component that provides the input area for the `igc-chat` interface. + * A web component that provides the input area for the chat interface. * * It supports: * - Text input with automatic resizing @@ -60,11 +60,11 @@ type DefaultInputRenderers = { * @fires igcInputBlur - Fired when the input area loses focus * @fires igcAttachmentDrag - Fired when dragging a file over the input * @fires igcAttachmentDrop - Fired when a file is dropped into the input - * @fires igcChange - Fired when file input changes (delegated from ``) + * @fires igcChange - Fired when the file input changes (delegated from the underlying file input). * * @csspart input-container - Container for the input section * @csspart input-wrapper - Wrapper around the text input - * @csspart text-input - The `` component + * @csspart text-input - The underlying textarea component. * @csspart actions-container - Container for file upload/send buttons * @csspart send-button - The send icon button * @csspart attachments - Container for rendering attachments diff --git a/src/components/chat/chat-message.ts b/src/components/chat/chat-message.ts index 176856ea8b..ec54ec9811 100644 --- a/src/components/chat/chat-message.ts +++ b/src/components/chat/chat-message.ts @@ -37,7 +37,7 @@ type DefaultMessageRenderers = { /* blazorSuppress */ /** - * A chat message component for displaying individual messages in ``. + * A chat message component for displaying individual messages in the chat component. * * @element igc-chat-message * diff --git a/src/components/chat/chat.ts b/src/components/chat/chat.ts index 35adc6cf0d..9cde8ec53b 100644 --- a/src/components/chat/chat.ts +++ b/src/components/chat/chat.ts @@ -42,7 +42,7 @@ type DefaultChatRenderers = { }; /** - * Defines the custom events dispatched by the `` component. + * Defines the custom events dispatched by the chat component. */ export interface IgcChatComponentEventMap { /** diff --git a/src/components/date-picker/date-picker.ts b/src/components/date-picker/date-picker.ts index 33a13334d5..1337a45197 100644 --- a/src/components/date-picker/date-picker.ts +++ b/src/components/date-picker/date-picker.ts @@ -96,7 +96,7 @@ type DatePickerResourceStringsType = IDatePickerResourceStrings & /* blazorIndirectRender */ /* blazorSupportsVisualChildren */ /** - * igc-date-picker is a feature rich component used for entering a date through manual text input or + * The date picker is a feature rich component used for entering a date through manual text input or * choosing date values from a calendar dialog that pops up. * * @element igc-date-picker diff --git a/src/components/date-range-picker/date-range-picker.ts b/src/components/date-range-picker/date-range-picker.ts index 89a89e6afa..8f306619a5 100644 --- a/src/components/date-range-picker/date-range-picker.ts +++ b/src/components/date-range-picker/date-range-picker.ts @@ -99,7 +99,7 @@ let nextId = 1; /* blazorIndirectRender */ /* blazorSupportsVisualChildren */ /** - * The igc-date-range-picker allows the user to select a range of dates. + * The Date Range Picker includes a text input and a calendar pop-up, allowing users to easily select start and end dates. * * @element igc-date-range-picker * diff --git a/src/components/date-range-picker/predefined-ranges-area.ts b/src/components/date-range-picker/predefined-ranges-area.ts index b912da076c..69eb3e07bb 100644 --- a/src/components/date-range-picker/predefined-ranges-area.ts +++ b/src/components/date-range-picker/predefined-ranges-area.ts @@ -22,7 +22,7 @@ import { styles as shared } from './themes/shared/predefined-ranges-area.common. /* blazorSuppress */ /** - * The predefined ranges area component is used within the `igc-date-range picker` element and it + * The predefined ranges area component is used within the date range picker and it * displays a set of chips with predefined date ranges. The component allows users to quickly select * a predefined date range value. Users can also provide custom ranges to be displayed as chips. * diff --git a/src/components/divider/divider.ts b/src/components/divider/divider.ts index b774de885e..9567edaaf7 100644 --- a/src/components/divider/divider.ts +++ b/src/components/divider/divider.ts @@ -9,7 +9,8 @@ import { styles as shared } from './themes/shared/divider.common.css.js'; import { all } from './themes/themes.js'; /** - * The igc-divider allows the content author to easily create a horizontal/vertical rule as a break between content to better organize information on a page. + * The divider allows the content author to easily create a horizontal/vertical + * rule as a break between content, to better organize information on a page. * * @element igc-divider * diff --git a/src/components/dropdown/dropdown-group.ts b/src/components/dropdown/dropdown-group.ts index 407c2533a8..0a352b8ae6 100644 --- a/src/components/dropdown/dropdown-group.ts +++ b/src/components/dropdown/dropdown-group.ts @@ -10,7 +10,7 @@ import { all } from './themes/group.js'; import { styles as shared } from './themes/shared/group/dropdown-group.common.css.js'; /** - * A container for a group of `igc-dropdown-item` components. + * A container for a group of dropdown items. * * @element igc-dropdown-group * @@ -29,7 +29,7 @@ export default class IgcDropdownGroupComponent extends LitElement { } /* blazorSuppress */ - /** All child `igc-dropdown-item`s. */ + /** All child dropdown items. */ @queryAssignedElements({ flatten: true, selector: IgcDropdownItemComponent.tagName, diff --git a/src/components/dropdown/dropdown-header.ts b/src/components/dropdown/dropdown-header.ts index 6cb6748321..2631898586 100644 --- a/src/components/dropdown/dropdown-header.ts +++ b/src/components/dropdown/dropdown-header.ts @@ -7,7 +7,7 @@ import { all } from './themes/header.js'; import { styles as shared } from './themes/shared/header/dropdown-header.common.css.js'; /** - * Represents a header item in a igc-dropdown list. + * Represents a header item in a dropdown list. * * @element igc-dropdown-header * diff --git a/src/components/dropdown/dropdown-item.ts b/src/components/dropdown/dropdown-item.ts index 9f299e417c..5bf163e5b3 100644 --- a/src/components/dropdown/dropdown-item.ts +++ b/src/components/dropdown/dropdown-item.ts @@ -14,9 +14,9 @@ import { styles as shared } from './themes/shared/item/dropdown-item.common.css. * @slot - Renders the item's main content. * @slot suffix - Renders content after the item's main content. * - * @csspart prefix - The prefix wrapper of the igc-dropdown-item. - * @csspart content - The main content wrapper of the igc-dropdown-item. - * @csspart suffix - The suffix wrapper of the igc-dropdown-item. + * @csspart prefix - The prefix wrapper of the dropdown item. + * @csspart content - The main content wrapper of the dropdown item. + * @csspart suffix - The suffix wrapper of the dropdown item. */ export default class IgcDropdownItemComponent extends IgcBaseOptionLikeComponent { public static readonly tagName = 'igc-dropdown-item'; diff --git a/src/components/icon/icon.ts b/src/components/icon/icon.ts index b849637dfc..415bc30500 100644 --- a/src/components/icon/icon.ts +++ b/src/components/icon/icon.ts @@ -28,7 +28,7 @@ import { all } from './themes/themes.js'; * - Registered dynamically using `registerIcon` or `registerIconFromText` * - Referenced by aliases that resolve differently based on the active theme * - * Icons automatically adapt to the current theme when used within an `igc-theme-provider`. + * Icons automatically adapt to the current theme when used within a theme provider. * The component subscribes to the icon registry and updates automatically when icons * are registered or references are updated. * diff --git a/src/components/icon/registry/types.ts b/src/components/icon/registry/types.ts index 8c22c75642..589884cf4f 100644 --- a/src/components/icon/registry/types.ts +++ b/src/components/icon/registry/types.ts @@ -82,7 +82,7 @@ export interface RegisterIconOptions { * `` element that pointed to the stripped elements' IDs are cleaned up * so the resulting markup contains no dangling ARIA references. * - The **title text** is still captured and stored as `SvgIcon.title`, which - * the `` component continues to expose as its host `aria-label`. + * the icon component continues to expose as its host `aria-label`. * Accessibility is therefore preserved at the component level while the * browser tooltip is suppressed at the SVG level. * diff --git a/src/components/progress/circular-gradient.ts b/src/components/progress/circular-gradient.ts index 4aee272beb..fec8e947a8 100644 --- a/src/components/progress/circular-gradient.ts +++ b/src/components/progress/circular-gradient.ts @@ -3,8 +3,8 @@ import { property } from 'lit/decorators.js'; import { registerComponent } from '../common/definitions/register.js'; /** - * Used for defining gradient stops in the igc-circular-progress. - * For each `igc-circular-gradient` defined as `gradient` slot of `igc-circular-progress` element would be created a SVG stop element. + * Used for defining gradient stops in the circular progress component. + * For each circular gradient, defined as `gradient` slot of the circular progress, would be created a SVG stop element. * The values passed as `color`, `offset` and `opacity` would be set as * `stop-color`, `offset` and `stop-opacity` of the SVG element without further validations. * diff --git a/src/components/progress/circular-progress.ts b/src/components/progress/circular-progress.ts index 3c5065bd72..d20c3af847 100644 --- a/src/components/progress/circular-progress.ts +++ b/src/components/progress/circular-progress.ts @@ -19,21 +19,21 @@ let nextId = 1; * @element igc-circular-progress * * @slot - The text area container. - * @slot gradient - Customize the progress bar in order to use a color gradient instead of a solid color. Accepts `igc-circular-gradient` elements. + * @slot gradient - Customize the progress bar in order to use a color gradient instead of a solid color. Accepts circular gradient elements. * - * @csspart svg - The igc-circular-progress SVG element. - * @csspart gradient_start - The igc-circular-progress linear-gradient start color. - * @csspart gradient_end - The igc-circular-progress linear-gradient end color. - * @csspart track - The igc-circular-progress ring track area. - * @csspart fill - The igc-circular-progress indicator area. - * @csspart label - The igc-circular-progress label. - * @csspart value - The igc-circular-progress label value. - * @csspart indeterminate - The igc-circular-progress indeterminate state. - * @csspart primary - The igc-circular-progress primary state. - * @csspart danger - The igc-circular-progress error state. - * @csspart warning - The igc-circular-progress warning state. - * @csspart info - The igc-circular-progress info state. - * @csspart success - The igc-circular-progress success state. + * @csspart svg - The circular progress SVG element. + * @csspart gradient_start - The circular progress linear-gradient start color. + * @csspart gradient_end - The circular progress linear-gradient end color. + * @csspart track - The circular progress ring track area. + * @csspart fill - The circular progress indicator area. + * @csspart label - The circular progress label. + * @csspart value - The circular progress label value. + * @csspart indeterminate - The circular progress indeterminate state. + * @csspart primary - The circular progress primary state. + * @csspart danger - The circular progress error state. + * @csspart warning - The circular progress warning state. + * @csspart info - The circular progress info state. + * @csspart success - The circular progress success state. */ export default class IgcCircularProgressComponent extends IgcProgressBaseComponent { public static readonly tagName = 'igc-circular-progress'; diff --git a/src/components/progress/linear-progress.ts b/src/components/progress/linear-progress.ts index a91fffdb0f..a0c6fd0885 100644 --- a/src/components/progress/linear-progress.ts +++ b/src/components/progress/linear-progress.ts @@ -19,17 +19,17 @@ import { all } from './themes/linear/themes.js'; * * @slot - The text area container. * - * @csspart track - The igc-linear-progress track area. - * @csspart fill - The igc-linear-progress indicator area. - * @csspart striped - The igc-linear-progress striped indicator. - * @csspart label - The igc-linear-progress label. - * @csspart value - The igc-linear-progress label value. - * @csspart indeterminate - The igc-linear-progress indeterminate state. - * @csspart primary - The igc-linear-progress indicator primary state. - * @csspart danger - The igc-linear-progress indicator error state. - * @csspart warning - The igc-linear-progress indicator warning state. - * @csspart info - The igc-linear-progress indicator info state. - * @csspart success - The igc-linear-progress indicator success state. + * @csspart track - The linear progress track area. + * @csspart fill - The linear progress indicator area. + * @csspart striped - The linear progress striped indicator. + * @csspart label - The linear progress label. + * @csspart value - The linear progress label value. + * @csspart indeterminate - The linear progress indeterminate state. + * @csspart primary - The linear progress indicator primary state. + * @csspart danger - The linear progress indicator error state. + * @csspart warning - The linear progress indicator warning state. + * @csspart info - The linear progress indicator info state. + * @csspart success - The linear progress indicator success state. */ export default class IgcLinearProgressComponent extends IgcProgressBaseComponent { public static readonly tagName = 'igc-linear-progress'; diff --git a/src/components/radio-group/radio-group.ts b/src/components/radio-group/radio-group.ts index c9de75f58e..bc68d8e38b 100644 --- a/src/components/radio-group/radio-group.ts +++ b/src/components/radio-group/radio-group.ts @@ -12,7 +12,7 @@ import { styles as shared } from './themes/shared/radio-group.common.css.js'; import { all } from './themes/themes.js'; /** - * The igc-radio-group component unifies one or more igc-radio buttons. + * Unifies one or more radio components into a single group. * * @element igc-radio-group * @@ -64,7 +64,7 @@ export default class IgcRadioGroupComponent extends LitElement { } /** - * Gets/Sets the name for all child igc-radio components. + * The name applied to all radio buttons in the group. * @attr */ @property({ reflect: true }) diff --git a/src/components/rating/rating-symbol.ts b/src/components/rating/rating-symbol.ts index 191043bd83..b30829ae89 100644 --- a/src/components/rating/rating-symbol.ts +++ b/src/components/rating/rating-symbol.ts @@ -5,7 +5,7 @@ import { styles } from './themes/rating-symbol.base.css.js'; /** * - * Used when a custom icon/symbol/element needs to be passed to the igc-rating component. + * Used when a custom icon/symbol/element needs to be passed to the rating component. * * @element igc-rating-symbol * diff --git a/src/components/rating/rating.ts b/src/components/rating/rating.ts index 8fe5821e15..57616cf9d3 100644 --- a/src/components/rating/rating.ts +++ b/src/components/rating/rating.ts @@ -81,7 +81,7 @@ const Slots = setSlots('symbol', 'value-label'); * * @element igc-rating * - * @slot symbol - Slot for projecting custom `igc-rating-symbol` elements. When used, the number of symbols determines the `max` value. + * @slot symbol - Slot for projecting custom rating symbol elements. When used, the number of symbols determines the `max` value. * @slot value-label - Slot for custom content displayed alongside the rating value. * * @fires igcChange - Emitted when the value of the control changes. diff --git a/src/components/select/select-group.ts b/src/components/select/select-group.ts index 19e93f37c4..4986283d46 100644 --- a/src/components/select/select-group.ts +++ b/src/components/select/select-group.ts @@ -39,7 +39,7 @@ export default class IgcSelectGroupComponent extends LitElement { private controlledItems!: Array; - /** All child `igc-select-item`s. */ + /** All child select items. */ @queryAssignedElements({ flatten: true, selector: IgcSelectItemComponent.tagName, diff --git a/src/components/select/select-header.ts b/src/components/select/select-header.ts index 268c31a029..25e0dce218 100644 --- a/src/components/select/select-header.ts +++ b/src/components/select/select-header.ts @@ -7,7 +7,7 @@ import { all } from '../dropdown/themes/header.js'; import { styles as shared } from '../dropdown/themes/shared/header/dropdown-header.common.css.js'; /** - * Represents a header item in an igc-select component. + * Represents a header item in a select component. * * @element igc-select-header * diff --git a/src/components/select/select-item.ts b/src/components/select/select-item.ts index 03a789f643..5365c183a4 100644 --- a/src/components/select/select-item.ts +++ b/src/components/select/select-item.ts @@ -15,9 +15,9 @@ import { styles as shared } from '../dropdown/themes/shared/item/dropdown-item.c * @slot prefix - Renders content before the main content area. * @slot suffix - Renders content after the main content area. * - * @csspart prefix - The prefix wrapper of the igc-select-item. - * @csspart content - The main content wrapper of the igc-select-item. - * @csspart suffix - The suffix wrapper of the igc-select-item. + * @csspart prefix - The prefix wrapper of the select item. + * @csspart content - The main content wrapper of the select item. + * @csspart suffix - The suffix wrapper of the select item. */ export default class IgcSelectItemComponent extends IgcBaseOptionLikeComponent { public static readonly tagName = 'igc-select-item'; diff --git a/src/components/select/select.ts b/src/components/select/select.ts index 9d1c4732c9..e2f86ce246 100644 --- a/src/components/select/select.ts +++ b/src/components/select/select.ts @@ -106,13 +106,13 @@ const Slots = setSlots( * @fires igcClosing - Emitter just before the list of options is closed. * @fires igcClosed - Emitted after the list of options is closed. * - * @csspart list - The list wrapping container for the items of the igc-select. - * @csspart input - The encapsulated igc-input of the igc-select. - * @csspart label - The encapsulated text label of the igc-select. - * @csspart prefix - The prefix wrapper of the input of the igc-select. - * @csspart suffix - The suffix wrapper of the input of the igc-select. - * @csspart toggle-icon - The toggle icon wrapper of the igc-select. - * @csspart helper-text - The helper text wrapper of the igc-select. + * @csspart list - The list wrapping container for the items of the select. + * @csspart input - The encapsulated input of the select. + * @csspart label - The encapsulated text label of the select. + * @csspart prefix - The prefix wrapper of the input of the select. + * @csspart suffix - The suffix wrapper of the input of the select. + * @csspart toggle-icon - The toggle icon wrapper of the select. + * @csspart helper-text - The helper text wrapper of the select. */ @blazorAdditionalDependencies( 'IgcIconComponent, IgcInputComponent, IgcSelectGroupComponent, IgcSelectHeaderComponent, IgcSelectItemComponent' @@ -253,14 +253,14 @@ export default class IgcSelectComponent extends FormAssociatedRequiredMixin( @property({ attribute: 'scroll-strategy' }) public scrollStrategy: PopoverScrollStrategy = 'scroll'; - /** Returns the items of the igc-select component. */ + /** Returns the items of the select component. */ public get items(): IgcSelectItemComponent[] { return Array.from( getItems(this, IgcSelectItemComponent.tagName) ); } - /** Returns the groups of the igc-select component. */ + /** Returns the groups of the select component. */ public get groups(): IgcSelectGroupComponent[] { return Array.from( getItems(this, IgcSelectGroupComponent.tagName) diff --git a/src/components/splitter/splitter.ts b/src/components/splitter/splitter.ts index e1d6b08eef..22b4a973e4 100644 --- a/src/components/splitter/splitter.ts +++ b/src/components/splitter/splitter.ts @@ -54,7 +54,7 @@ const DEFAULT_RESIZE_STATE: SplitterResizeState = { }; /** - * The `igc-splitter` component provides a resizable split-pane layout that divides the view + * A splitter component that provides a resizable split-pane layout, dividing the view * into two panels — *start* and *end* — separated by a draggable bar. * * Panels can be resized by dragging the bar, using keyboard shortcuts, or collapsed/expanded diff --git a/src/components/stepper/step.ts b/src/components/stepper/step.ts index 10f7bcdc39..1ab8a610e7 100644 --- a/src/components/stepper/step.ts +++ b/src/components/stepper/step.ts @@ -25,7 +25,7 @@ import { styles } from './themes/step/step.base.css.js'; import { all } from './themes/step/themes.js'; /** - * A step component used within an `igc-stepper` to represent an individual step in a wizard-like workflow. + * A step component used within a stepper to represent an individual step in a wizard-like workflow. * * @remarks * Each step has a header (with an indicator, title, and subtitle) and a content area. diff --git a/src/components/stepper/stepper.ts b/src/components/stepper/stepper.ts index b407b3e653..801020b539 100644 --- a/src/components/stepper/stepper.ts +++ b/src/components/stepper/stepper.ts @@ -59,7 +59,7 @@ const STEPPER_SYNC_PROPERTIES: (keyof IgcStepperComponent)[] = [ * A stepper component that provides a wizard-like workflow by dividing content into logical steps. * * @remarks - * The stepper component allows the user to navigate between multiple `igc-step` elements. + * The stepper component allows the user to navigate between multiple step children. * It supports horizontal and vertical orientation, linear and non-linear navigation, * keyboard navigation, and provides API methods to control the active step. * @@ -68,7 +68,7 @@ const STEPPER_SYNC_PROPERTIES: (keyof IgcStepperComponent)[] = [ * * @element igc-stepper * - * @slot - Renders `igc-step` components inside the default slot. + * @slot - Renders the steps of the stepper inside the default slot. * * @fires igcActiveStepChanging - Emitted when the active step is about to change. Cancelable. * @fires igcActiveStepChanged - Emitted after the active step has changed. diff --git a/src/components/tabs/tab.ts b/src/components/tabs/tab.ts index 556077c833..efa51e0696 100644 --- a/src/components/tabs/tab.ts +++ b/src/components/tabs/tab.ts @@ -10,7 +10,7 @@ import { all } from './themes/tab-themes.js'; let nextId = 1; /** - * A tab element slotted into an `igc-tabs` container. + * A tab nested in a tabs component. * * @element igc-tab * diff --git a/src/components/tabs/tabs.ts b/src/components/tabs/tabs.ts index 20f26a54dc..5ac61b255b 100644 --- a/src/components/tabs/tabs.ts +++ b/src/components/tabs/tabs.ts @@ -59,7 +59,7 @@ export interface IgcTabsComponentEventMap { /** * Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy. * - * The `` component allows the user to navigate between multiple `` elements. + * The tabs component allows the user to navigate between multiple tab children. * It supports keyboard navigation and provides API methods to control the selected tab. * * @element igc-tabs @@ -144,7 +144,7 @@ export default class IgcTabsComponent extends EventEmitterMixin< public activation: TabsActivation = 'auto'; /* blazorSuppress */ - /** Returns the direct `igc-tab` elements that are children of this element. */ + /** Returns the direct tab children of this element. */ public get tabs(): IgcTabComponent[] { return this._tabs; } diff --git a/src/components/textarea/textarea.ts b/src/components/textarea/textarea.ts index 3bacc65928..c952e2c2a3 100644 --- a/src/components/textarea/textarea.ts +++ b/src/components/textarea/textarea.ts @@ -80,11 +80,11 @@ const Slots = setSlots( * @fires igcChange - Emitted when the a change to the control value is committed by the user. * * @csspart container - The main wrapper that holds all main input elements of the textarea. - * @csspart input - The native input element of the igc-textarea. - * @csspart label - The native label element of the igc-textarea. - * @csspart prefix - The prefix wrapper of the igc-textarea. - * @csspart suffix - The suffix wrapper of the igc-textarea. - * @csspart helper-text - The helper text wrapper of the igc-textarea. + * @csspart input - The native input element of the textarea. + * @csspart label - The native label element of the textarea. + * @csspart prefix - The prefix wrapper of the textarea. + * @csspart suffix - The suffix wrapper of the textarea. + * @csspart helper-text - The helper text wrapper of the textarea. */ @shadowOptions({ delegatesFocus: true }) export default class IgcTextareaComponent extends FormAssociatedRequiredMixin( diff --git a/src/components/tile-manager/tile-manager.ts b/src/components/tile-manager/tile-manager.ts index cf0cb3e3ce..207f304029 100644 --- a/src/components/tile-manager/tile-manager.ts +++ b/src/components/tile-manager/tile-manager.ts @@ -30,7 +30,7 @@ import IgcTileComponent from './tile.js'; * * @element igc-tile-manager * - * @slot - Default slot for the tile manager. Only `igc-tile` elements will be projected inside the CSS grid container. + * @slot - Default slot for the tile manager. Only tile elements will be projected inside the CSS grid container. * * @csspart base - The tile manager CSS Grid container. * diff --git a/src/components/tile-manager/tile.ts b/src/components/tile-manager/tile.ts index 9a9790b6af..cfcddeb374 100644 --- a/src/components/tile-manager/tile.ts +++ b/src/components/tile-manager/tile.ts @@ -65,7 +65,7 @@ const Slots = setSlots( ); /** - * The tile component is used within the `igc-tile-manager` as a container + * The tile component is used within the tile manager as a container * for displaying various types of information. * * @element igc-tile diff --git a/src/extras/chat-markdown-renderer.ts b/src/extras/chat-markdown-renderer.ts index a506335cea..3f69174374 100644 --- a/src/extras/chat-markdown-renderer.ts +++ b/src/extras/chat-markdown-renderer.ts @@ -174,7 +174,7 @@ export async function setupMarkdownRenderer( } /** - * Creates a markdown renderer specifically for igc-chat messages. + * Creates a markdown renderer specifically for chat messages. * This function wraps the renderer to work with IgcChatMessage objects * and returns Lit's unsafeHTML directive for rendering. * diff --git a/stories/button-group.stories.ts b/stories/button-group.stories.ts index e49abf5f73..7cf03aac85 100644 --- a/stories/button-group.stories.ts +++ b/stories/button-group.stories.ts @@ -60,7 +60,7 @@ const metadata: Meta = { docs: { description: { component: - 'The `igc-button-group` groups a series of `igc-toggle-button`s together, exposing features such as layout and selection.', + 'Groups a series of toggle buttons together, exposing features such as layout and selection.', }, }, actions: { handles: ['igcSelect', 'igcDeselect'] }, diff --git a/stories/carousel.stories.ts b/stories/carousel.stories.ts index 7a2f09f996..d654201ec8 100644 --- a/stories/carousel.stories.ts +++ b/stories/carousel.stories.ts @@ -28,7 +28,7 @@ const metadata: Meta = { docs: { description: { component: - 'The `igc-carousel` presents a set of `igc-carousel-slide`s by sequentially displaying a subset of one or more slides.', + 'The carousel presents a set of slides by sequentially displaying a subset of one or more.', }, }, actions: { handles: ['igcSlideChanged', 'igcPlaying', 'igcPaused'] }, diff --git a/stories/date-range-picker.stories.ts b/stories/date-range-picker.stories.ts index 4beb56cdcb..b6bb42317d 100644 --- a/stories/date-range-picker.stories.ts +++ b/stories/date-range-picker.stories.ts @@ -29,7 +29,7 @@ const metadata: Meta = { docs: { description: { component: - 'The igc-date-range-picker allows the user to select a range of dates.', + 'The Date Range Picker includes a text input and a calendar pop-up, allowing users to easily select start and end dates.', }, }, actions: { diff --git a/stories/divider.stories.ts b/stories/divider.stories.ts index 934b960086..a408e9501d 100644 --- a/stories/divider.stories.ts +++ b/stories/divider.stories.ts @@ -13,7 +13,7 @@ const metadata: Meta = { docs: { description: { component: - 'The igc-divider allows the content author to easily create a horizontal/vertical rule as a break between content to better organize information on a page.', + 'The divider allows the content author to easily create a horizontal/vertical\nrule as a break between content, to better organize information on a page.', }, }, }, diff --git a/stories/radio-group.stories.ts b/stories/radio-group.stories.ts index 5c50a7e6d4..2b76917cc4 100644 --- a/stories/radio-group.stories.ts +++ b/stories/radio-group.stories.ts @@ -22,8 +22,7 @@ const metadata: Meta = { parameters: { docs: { description: { - component: - 'The igc-radio-group component unifies one or more igc-radio buttons.', + component: 'Unifies one or more radio components into a single group.', }, }, }, @@ -37,7 +36,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'Gets/Sets the name for all child igc-radio components.', + description: 'The name applied to all radio buttons in the group.', control: 'text', }, value: { @@ -55,7 +54,7 @@ export default metadata; interface IgcRadioGroupArgs { /** Alignment of the radio controls inside this group. */ alignment: 'horizontal' | 'vertical'; - /** Gets/Sets the name for all child igc-radio components. */ + /** The name applied to all radio buttons in the group. */ name: string; /** * The value of the group, reflecting the value of the currently checked radio button. diff --git a/stories/splitter.stories.ts b/stories/splitter.stories.ts index 9284c4093d..a8d5432c1f 100644 --- a/stories/splitter.stories.ts +++ b/stories/splitter.stories.ts @@ -17,7 +17,7 @@ const metadata: Meta = { docs: { description: { component: - 'The `igc-splitter` divides the view into two resizable and collapsible panels separated by a draggable bar. ' + + 'The splitter divides the view into two resizable and collapsible panels separated by a draggable bar. ' + 'Use the `start` and `end` slots to project content into each panel. ' + 'Panels can be resized by dragging, using keyboard shortcuts, or collapsed programmatically via `toggle()`.', }, diff --git a/stories/tabs.stories.ts b/stories/tabs.stories.ts index 6369226e49..b6ef25821c 100644 --- a/stories/tabs.stories.ts +++ b/stories/tabs.stories.ts @@ -20,7 +20,7 @@ const metadata: Meta = { docs: { description: { component: - 'Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy.\n\nThe `` component allows the user to navigate between multiple `` elements.\nIt supports keyboard navigation and provides API methods to control the selected tab.', + 'Tabs organize and allow navigation between groups of content that are related and at the same level of hierarchy.\n\nThe tabs component allows the user to navigate between multiple tab children.\nIt supports keyboard navigation and provides API methods to control the selected tab.', }, }, actions: { handles: ['igcChange'] }, From b75ab4b80c14e14fb3de55959abb830e51e095a8 Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:20:49 +0300 Subject: [PATCH 3/8] docs: drop attribute phrasing from descriptions --- src/components/button-group/toggle-button.ts | 2 +- src/components/checkbox/checkbox-base.ts | 2 +- src/components/combo/combo.ts | 8 +++---- .../common/mixins/forms/associated.ts | 2 +- src/components/common/mixins/forms/types.ts | 2 +- src/components/date-picker/date-picker.ts | 2 +- .../date-range-picker/date-range-picker.ts | 10 ++++---- .../date-time-input/date-time-input.base.ts | 2 +- src/components/input/input-base.ts | 4 ++-- src/components/input/input.ts | 8 +++---- src/components/nav-drawer/nav-drawer.ts | 2 +- src/components/radio/radio.ts | 2 +- src/components/select/select.ts | 6 ++--- src/components/textarea/textarea.ts | 2 +- stories/checkbox.stories.ts | 8 +++---- stories/combo.stories.ts | 16 ++++++------- stories/date-range-picker.stories.ts | 24 +++++++++---------- stories/date-time-input.stories.ts | 8 +++---- stories/datepicker.stories.ts | 4 ++-- stories/file-input.stories.ts | 8 +++---- stories/input.stories.ts | 22 ++++++++--------- stories/mask-input.stories.ts | 8 +++---- stories/nav-drawer.stories.ts | 4 ++-- stories/radio.stories.ts | 8 +++---- stories/rating.stories.ts | 8 +++---- stories/select.stories.ts | 16 ++++++------- stories/slider.stories.ts | 4 ++-- stories/switch.stories.ts | 8 +++---- stories/textarea.stories.ts | 8 +++---- 29 files changed, 104 insertions(+), 104 deletions(-) diff --git a/src/components/button-group/toggle-button.ts b/src/components/button-group/toggle-button.ts index acd2757c9e..e98f35b3c8 100644 --- a/src/components/button-group/toggle-button.ts +++ b/src/components/button-group/toggle-button.ts @@ -36,7 +36,7 @@ export default class IgcToggleButtonComponent extends LitElement { private readonly _nativeButton!: HTMLButtonElement; /** - * The value attribute of the control. + * The value of the control. * @attr */ @property() diff --git a/src/components/checkbox/checkbox-base.ts b/src/components/checkbox/checkbox-base.ts index 1572b4c419..0b5d95620f 100644 --- a/src/components/checkbox/checkbox-base.ts +++ b/src/components/checkbox/checkbox-base.ts @@ -54,7 +54,7 @@ export class IgcCheckboxBaseComponent extends FormAssociatedCheckboxRequiredMixi protected _hideLabel = true; /** - * The value attribute of the control. + * The value of the control. * @attr */ @property() diff --git a/src/components/combo/combo.ts b/src/components/combo/combo.ts index 185aff4b4d..f50d039ff7 100644 --- a/src/components/combo/combo.ts +++ b/src/components/combo/combo.ts @@ -351,21 +351,21 @@ export default class IgcComboComponent< } /** - * The label attribute of the control. + * The label of the control. * @attr label */ @property() public label?: string; /** - * The placeholder attribute of the control. + * The placeholder text of the control. * @attr placeholder */ @property() public placeholder?: string; /** - * The placeholder attribute of the search input. + * The placeholder text of the search input. * @attr placeholder-search */ @property({ attribute: 'placeholder-search' }) @@ -503,7 +503,7 @@ export default class IgcComboComponent< /** * Sets the value (selected items). The passed value must be a valid JSON array. - * If the data source is an array of complex objects, the `valueKey` attribute must be set. + * If the data source is an array of complex objects, the `valueKey` must be set. * Note that when `displayKey` is not explicitly set, it falls back to the value of `valueKey`. * * @attr value diff --git a/src/components/common/mixins/forms/associated.ts b/src/components/common/mixins/forms/associated.ts index e500936bf6..a34449f644 100644 --- a/src/components/common/mixins/forms/associated.ts +++ b/src/components/common/mixins/forms/associated.ts @@ -84,7 +84,7 @@ function BaseFormAssociated>(base: T) { //#region Public properties and attributes /** - * The name attribute of the control. + * The name of the control, submitted with the form data. * @attr */ @property({ reflect: true }) diff --git a/src/components/common/mixins/forms/types.ts b/src/components/common/mixins/forms/types.ts index 3cb9f35791..d2420a88e0 100644 --- a/src/components/common/mixins/forms/types.ts +++ b/src/components/common/mixins/forms/types.ts @@ -36,7 +36,7 @@ declare class BaseFormAssociatedElement { public invalid: boolean; /** - * The name attribute of the control. + * The name of the control, submitted with the form data. * @attr */ public name: string; diff --git a/src/components/date-picker/date-picker.ts b/src/components/date-picker/date-picker.ts index 1337a45197..15250bfaf1 100644 --- a/src/components/date-picker/date-picker.ts +++ b/src/components/date-picker/date-picker.ts @@ -406,7 +406,7 @@ export default class IgcDatePickerComponent extends FormAssociatedRequiredMixin( public outlined = false; /** - * The placeholder attribute of the control. + * The placeholder text of the control. * @attr */ @property() diff --git a/src/components/date-range-picker/date-range-picker.ts b/src/components/date-range-picker/date-range-picker.ts index 8f306619a5..87346615f1 100644 --- a/src/components/date-range-picker/date-range-picker.ts +++ b/src/components/date-range-picker/date-range-picker.ts @@ -422,21 +422,21 @@ export default class IgcDateRangePickerComponent extends FormAssociatedRequiredM public label!: string; /** - * The label attribute of the start input. + * The label of the start input. * @attr label-start */ @property({ attribute: 'label-start' }) public labelStart = ''; /** - * The label attribute of the end input. + * The label of the end input. * @attr label-end */ @property({ attribute: 'label-end' }) public labelEnd = ''; /** - * The placeholder attribute of the control (single input). + * The placeholder text of the control (single input). * @attr */ @property() @@ -450,14 +450,14 @@ export default class IgcDateRangePickerComponent extends FormAssociatedRequiredM } /** - * The placeholder attribute of the start input. + * The placeholder text of the start input. * @attr placeholder-start */ @property({ attribute: 'placeholder-start' }) public placeholderStart = ''; /** - * The placeholder attribute of the end input. + * The placeholder text of the end input. * @attr placeholder-end */ @property({ attribute: 'placeholder-end' }) diff --git a/src/components/date-time-input/date-time-input.base.ts b/src/components/date-time-input/date-time-input.base.ts index 1b7848c5aa..090ca12ef1 100644 --- a/src/components/date-time-input/date-time-input.base.ts +++ b/src/components/date-time-input/date-time-input.base.ts @@ -122,7 +122,7 @@ export abstract class IgcDateTimeInputBaseComponent extends MaskBehaviorMixin( public outlined = false; /** - * The placeholder attribute of the control. + * The placeholder text of the control. * @attr */ @property() diff --git a/src/components/input/input-base.ts b/src/components/input/input-base.ts index 6cdc521d86..ceef550a06 100644 --- a/src/components/input/input-base.ts +++ b/src/components/input/input-base.ts @@ -64,7 +64,7 @@ export abstract class IgcInputBaseComponent extends FormAssociatedRequiredMixin( } /* blazorSuppress */ - /** The value attribute of the control. */ + /** The value of the control. */ public abstract value: string; /** @@ -77,7 +77,7 @@ export abstract class IgcInputBaseComponent extends FormAssociatedRequiredMixin( public outlined = false; /** - * The placeholder attribute of the control. + * The placeholder text of the control. * @attr */ @property() diff --git a/src/components/input/input.ts b/src/components/input/input.ts index 1f849e1715..7706471c5a 100644 --- a/src/components/input/input.ts +++ b/src/components/input/input.ts @@ -109,7 +109,7 @@ export default class IgcInputComponent extends IgcInputBaseComponent { /* alternateName: displayType */ /** - * The type attribute of the control. + * The type of the control. * @attr */ @property({ reflect: true }) @@ -175,7 +175,7 @@ export default class IgcInputComponent extends IgcInputBaseComponent { } /** - * The min attribute of the control. + * The minimum value the control accepts. * @attr */ @property({ type: Number }) @@ -189,7 +189,7 @@ export default class IgcInputComponent extends IgcInputBaseComponent { } /** - * The max attribute of the control. + * The maximum value the control accepts. * @attr */ @property({ type: Number }) @@ -203,7 +203,7 @@ export default class IgcInputComponent extends IgcInputBaseComponent { } /** - * The step attribute of the control. + * The granularity the value must adhere to. * @attr */ @property({ type: Number }) diff --git a/src/components/nav-drawer/nav-drawer.ts b/src/components/nav-drawer/nav-drawer.ts index 5669e27d9d..4b074b28c7 100644 --- a/src/components/nav-drawer/nav-drawer.ts +++ b/src/components/nav-drawer/nav-drawer.ts @@ -132,7 +132,7 @@ export default class IgcNavDrawerComponent extends EventEmitterMixin< /** * Determines whether the drawer should remain open when the Escape key is pressed. * - * This attribute is only applicable when the drawer is in a non-relative position, + * This is only applicable when the drawer is in a non-relative position, * as the Escape key does not trigger the closing of relative drawers. * * @attr keep-open-on-escape diff --git a/src/components/radio/radio.ts b/src/components/radio/radio.ts index e5597d1442..e7d916d0d4 100644 --- a/src/components/radio/radio.ts +++ b/src/components/radio/radio.ts @@ -136,7 +136,7 @@ export default class IgcRadioComponent extends FormAssociatedCheckboxRequiredMix } /** - * The value attribute of the control. + * The value of the control. * @attr */ @property() diff --git a/src/components/select/select.ts b/src/components/select/select.ts index e2f86ce246..528b619ecc 100644 --- a/src/components/select/select.ts +++ b/src/components/select/select.ts @@ -191,7 +191,7 @@ export default class IgcSelectComponent extends FormAssociatedRequiredMixin( /* @tsTwoWayProperty(true, "igcChange", "detail.value", false) */ /** - * The value attribute of the control. + * The value of the control. * @attr */ @property() @@ -227,14 +227,14 @@ export default class IgcSelectComponent extends FormAssociatedRequiredMixin( public distance = 0; /** - * The label attribute of the control. + * The label of the control. * @attr */ @property() public label!: string; /** - * The placeholder attribute of the control. + * The placeholder text of the control. * @attr */ @property() diff --git a/src/components/textarea/textarea.ts b/src/components/textarea/textarea.ts index c952e2c2a3..07629c9a03 100644 --- a/src/components/textarea/textarea.ts +++ b/src/components/textarea/textarea.ts @@ -190,7 +190,7 @@ export default class IgcTextareaComponent extends FormAssociatedRequiredMixin( public outlined = false; /** - * The placeholder attribute of the control. + * The placeholder text of the control. * * @attr */ diff --git a/stories/checkbox.stories.ts b/stories/checkbox.stories.ts index 5189fc350f..573c4f645d 100644 --- a/stories/checkbox.stories.ts +++ b/stories/checkbox.stories.ts @@ -39,7 +39,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -56,7 +56,7 @@ const metadata: Meta = { }, value: { type: 'string', - description: 'The value attribute of the control.', + description: 'The value of the control.', control: 'text', }, checked: { @@ -90,13 +90,13 @@ interface IgcCheckboxArgs { indeterminate: boolean; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; /** Sets the control into invalid state (visual state only). */ invalid: boolean; - /** The value attribute of the control. */ + /** The value of the control. */ value: string; /** The checked state of the control. */ checked: boolean; diff --git a/stories/combo.stories.ts b/stories/combo.stories.ts index 9b95983cd4..03be608200 100644 --- a/stories/combo.stories.ts +++ b/stories/combo.stories.ts @@ -77,17 +77,17 @@ const metadata: Meta = { }, label: { type: 'string', - description: 'The label attribute of the control.', + description: 'The label of the control.', control: 'text', }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, placeholderSearch: { type: 'string', - description: 'The placeholder attribute of the search input.', + description: 'The placeholder text of the search input.', control: 'text', }, valueKey: { @@ -143,7 +143,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -194,11 +194,11 @@ interface IgcComboArgs { autofocusList: boolean; /** Gets/Sets the locale used for getting language, affecting resource strings. */ locale: string; - /** The label attribute of the control. */ + /** The label of the control. */ label: string; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; - /** The placeholder attribute of the search input. */ + /** The placeholder text of the search input. */ placeholderSearch: string; /** The key in the data source used when selecting items. */ valueKey: string; @@ -216,7 +216,7 @@ interface IgcComboArgs { disableClear: boolean; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; diff --git a/stories/date-range-picker.stories.ts b/stories/date-range-picker.stories.ts index b6bb42317d..fc9d1d4048 100644 --- a/stories/date-range-picker.stories.ts +++ b/stories/date-range-picker.stories.ts @@ -101,30 +101,30 @@ const metadata: Meta = { }, labelStart: { type: 'string', - description: 'The label attribute of the start input.', + description: 'The label of the start input.', control: 'text', table: { defaultValue: { summary: '' } }, }, labelEnd: { type: 'string', - description: 'The label attribute of the end input.', + description: 'The label of the end input.', control: 'text', table: { defaultValue: { summary: '' } }, }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control (single input).', + description: 'The placeholder text of the control (single input).', control: 'text', }, placeholderStart: { type: 'string', - description: 'The placeholder attribute of the start input.', + description: 'The placeholder text of the start input.', control: 'text', table: { defaultValue: { summary: '' } }, }, placeholderEnd: { type: 'string', - description: 'The placeholder attribute of the end input.', + description: 'The placeholder text of the end input.', control: 'text', table: { defaultValue: { summary: '' } }, }, @@ -227,7 +227,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -311,15 +311,15 @@ interface IgcDateRangePickerArgs { outlined: boolean; /** The label of the control (single input). */ label: string; - /** The label attribute of the start input. */ + /** The label of the start input. */ labelStart: string; - /** The label attribute of the end input. */ + /** The label of the end input. */ labelEnd: string; - /** The placeholder attribute of the control (single input). */ + /** The placeholder text of the control (single input). */ placeholder: string; - /** The placeholder attribute of the start input. */ + /** The placeholder text of the start input. */ placeholderStart: string; - /** The placeholder attribute of the end input. */ + /** The placeholder text of the end input. */ placeholderEnd: string; /** The prompt symbol to use for unfilled parts of the mask. */ prompt: string; @@ -365,7 +365,7 @@ interface IgcDateRangePickerArgs { | 'saturday'; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; diff --git a/stories/date-time-input.stories.ts b/stories/date-time-input.stories.ts index 5c2f30daa7..ec3c43647e 100644 --- a/stories/date-time-input.stories.ts +++ b/stories/date-time-input.stories.ts @@ -58,7 +58,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -81,7 +81,7 @@ const metadata: Meta = { }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, label: { @@ -147,7 +147,7 @@ interface IgcDateTimeInputArgs { prompt: string; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; @@ -155,7 +155,7 @@ interface IgcDateTimeInputArgs { invalid: boolean; /** Whether the control will have outlined appearance. */ outlined: boolean; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** The label for the control. */ label: string; diff --git a/stories/datepicker.stories.ts b/stories/datepicker.stories.ts index 018939ce79..e11b9f04df 100644 --- a/stories/datepicker.stories.ts +++ b/stories/datepicker.stories.ts @@ -129,7 +129,7 @@ const metadata: Meta = { }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, visibleMonths: { @@ -278,7 +278,7 @@ interface IgcDatepickerArgs { hideOutsideDays: boolean; /** Whether the control will have outlined appearance. */ outlined: boolean; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** The number of months displayed in the calendar. */ visibleMonths: number; diff --git a/stories/file-input.stories.ts b/stories/file-input.stories.ts index 3bbe77c48d..97daa34335 100644 --- a/stories/file-input.stories.ts +++ b/stories/file-input.stories.ts @@ -72,7 +72,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -95,7 +95,7 @@ const metadata: Meta = { }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, label: { @@ -133,7 +133,7 @@ interface IgcFileInputArgs { autofocus: boolean; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; @@ -141,7 +141,7 @@ interface IgcFileInputArgs { invalid: boolean; /** Whether the control will have outlined appearance. */ outlined: boolean; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** The label for the control. */ label: string; diff --git a/stories/input.stories.ts b/stories/input.stories.ts index e4cacd8408..86cf4dc652 100644 --- a/stories/input.stories.ts +++ b/stories/input.stories.ts @@ -38,7 +38,7 @@ const metadata: Meta = { }, type: { type: '"text" | "email" | "number" | "password" | "search" | "tel" | "url"', - description: 'The type attribute of the control.', + description: 'The type of the control.', options: ['text', 'email', 'number', 'password', 'search', 'tel', 'url'], control: { type: 'select' }, table: { defaultValue: { summary: 'text' } }, @@ -72,12 +72,12 @@ const metadata: Meta = { }, min: { type: 'number', - description: 'The min attribute of the control.', + description: 'The minimum value the control accepts.', control: 'number', }, max: { type: 'number', - description: 'The max attribute of the control.', + description: 'The maximum value the control accepts.', control: 'number', }, step: { @@ -112,7 +112,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -135,7 +135,7 @@ const metadata: Meta = { }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, label: { @@ -161,7 +161,7 @@ export default metadata; interface IgcInputArgs { /** The value of the control. */ value: string; - /** The type attribute of the control. */ + /** The type of the control. */ type: 'text' | 'email' | 'number' | 'password' | 'search' | 'tel' | 'url'; /** Makes the control a readonly field. */ readOnly: boolean; @@ -176,11 +176,11 @@ interface IgcInputArgs { minLength: number; /** The maximum string length of the control. */ maxLength: number; - /** The min attribute of the control. */ + /** The minimum value the control accepts. */ min: number; - /** The max attribute of the control. */ + /** The maximum value the control accepts. */ max: number; - /** The step attribute of the control. */ + /** The granularity the value must adhere to. */ step: number; /** Whether the control should receive focus automatically. */ autofocus: boolean; @@ -193,7 +193,7 @@ interface IgcInputArgs { validateOnly: boolean; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; @@ -201,7 +201,7 @@ interface IgcInputArgs { invalid: boolean; /** Whether the control will have outlined appearance. */ outlined: boolean; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** The label for the control. */ label: string; diff --git a/stories/mask-input.stories.ts b/stories/mask-input.stories.ts index 6465c89327..9a7dbd53e4 100644 --- a/stories/mask-input.stories.ts +++ b/stories/mask-input.stories.ts @@ -74,7 +74,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -97,7 +97,7 @@ const metadata: Meta = { }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, label: { @@ -144,7 +144,7 @@ interface IgcMaskInputArgs { readOnly: boolean; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; @@ -152,7 +152,7 @@ interface IgcMaskInputArgs { invalid: boolean; /** Whether the control will have outlined appearance. */ outlined: boolean; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** The label for the control. */ label: string; diff --git a/stories/nav-drawer.stories.ts b/stories/nav-drawer.stories.ts index 8d8c54c746..9a81ba1f18 100644 --- a/stories/nav-drawer.stories.ts +++ b/stories/nav-drawer.stories.ts @@ -45,7 +45,7 @@ const metadata: Meta = { keepOpenOnEscape: { type: 'boolean', description: - 'Determines whether the drawer should remain open when the Escape key is pressed.\n\nThis attribute is only applicable when the drawer is in a non-relative position,\nas the Escape key does not trigger the closing of relative drawers.', + 'Determines whether the drawer should remain open when the Escape key is pressed.\n\nThis is only applicable when the drawer is in a non-relative position,\nas the Escape key does not trigger the closing of relative drawers.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, @@ -77,7 +77,7 @@ interface IgcNavDrawerArgs { /** * Determines whether the drawer should remain open when the Escape key is pressed. * - * This attribute is only applicable when the drawer is in a non-relative position, + * This is only applicable when the drawer is in a non-relative position, * as the Escape key does not trigger the closing of relative drawers. */ keepOpenOnEscape: boolean; diff --git a/stories/radio.stories.ts b/stories/radio.stories.ts index 573f2e9bf7..d40f103f41 100644 --- a/stories/radio.stories.ts +++ b/stories/radio.stories.ts @@ -28,7 +28,7 @@ const metadata: Meta = { }, value: { type: 'string', - description: 'The value attribute of the control.', + description: 'The value of the control.', control: 'text', }, checked: { @@ -46,7 +46,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -76,13 +76,13 @@ export default metadata; interface IgcRadioArgs { /** When set, makes the component a required field for validation. */ required: boolean; - /** The value attribute of the control. */ + /** The value of the control. */ value: string; /** The checked state of the control. */ checked: boolean; /** The label position of the radio control. */ labelPosition: 'after' | 'before'; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; diff --git a/stories/rating.stories.ts b/stories/rating.stories.ts index 22d6687c4d..172aed39e9 100644 --- a/stories/rating.stories.ts +++ b/stories/rating.stories.ts @@ -61,7 +61,7 @@ const metadata: Meta = { }, value: { type: 'number', - description: 'The current value of the component', + description: 'The value of the component', control: 'number', table: { defaultValue: { summary: '0' } }, }, @@ -92,7 +92,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -146,7 +146,7 @@ interface IgcRatingArgs { * Important for screen-readers and useful for localization. */ valueFormat: string; - /** The current value of the component */ + /** The value of the component */ value: number; /** Sets hover preview behavior for the component */ hoverPreview: boolean; @@ -156,7 +156,7 @@ interface IgcRatingArgs { single: boolean; /** Whether to reset the rating when the user selects the same value. */ allowReset: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; diff --git a/stories/select.stories.ts b/stories/select.stories.ts index b50e9230cd..0a46688c25 100644 --- a/stories/select.stories.ts +++ b/stories/select.stories.ts @@ -46,7 +46,7 @@ const metadata: Meta = { argTypes: { value: { type: 'string', - description: 'The value attribute of the control.', + description: 'The value of the control.', control: 'text', }, outlined: { @@ -69,12 +69,12 @@ const metadata: Meta = { }, label: { type: 'string', - description: 'The label attribute of the control.', + description: 'The label of the control.', control: 'text', }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, placement: { @@ -115,7 +115,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -169,7 +169,7 @@ const metadata: Meta = { export default metadata; interface IgcSelectArgs { - /** The value attribute of the control. */ + /** The value of the control. */ value: string; /** Whether the control has an outlined appearance. */ outlined: boolean; @@ -177,9 +177,9 @@ interface IgcSelectArgs { autofocus: boolean; /** The distance of the select dropdown from its input. */ distance: number; - /** The label attribute of the control. */ + /** The label of the control. */ label: string; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** The preferred placement of the select dropdown around its input. */ placement: @@ -199,7 +199,7 @@ interface IgcSelectArgs { scrollStrategy: 'scroll' | 'block' | 'close'; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; diff --git a/stories/slider.stories.ts b/stories/slider.stories.ts index 11d13f6dfb..a0548fef70 100644 --- a/stories/slider.stories.ts +++ b/stories/slider.stories.ts @@ -35,7 +35,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -168,7 +168,7 @@ export default metadata; interface IgcSliderArgs { /** The current value of the component. */ value: number; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; diff --git a/stories/switch.stories.ts b/stories/switch.stories.ts index 4c87dcc6ba..e97dda3b3f 100644 --- a/stories/switch.stories.ts +++ b/stories/switch.stories.ts @@ -33,7 +33,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -50,7 +50,7 @@ const metadata: Meta = { }, value: { type: 'string', - description: 'The value attribute of the control.', + description: 'The value of the control.', control: 'text', }, checked: { @@ -81,13 +81,13 @@ export default metadata; interface IgcSwitchArgs { /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; /** Sets the control into invalid state (visual state only). */ invalid: boolean; - /** The value attribute of the control. */ + /** The value of the control. */ value: string; /** The checked state of the control. */ checked: boolean; diff --git a/stories/textarea.stories.ts b/stories/textarea.stories.ts index a2f785c273..631ba95b93 100644 --- a/stories/textarea.stories.ts +++ b/stories/textarea.stories.ts @@ -75,7 +75,7 @@ const metadata: Meta = { }, placeholder: { type: 'string', - description: 'The placeholder attribute of the control.', + description: 'The placeholder text of the control.', control: 'text', }, readOnly: { @@ -135,7 +135,7 @@ const metadata: Meta = { }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { @@ -198,7 +198,7 @@ interface IgcTextareaArgs { minLength: number; /** Whether the control will have outlined appearance. */ outlined: boolean; - /** The placeholder attribute of the control. */ + /** The placeholder text of the control. */ placeholder: string; /** Makes the control a readonly field. */ readOnly: boolean; @@ -229,7 +229,7 @@ interface IgcTextareaArgs { validateOnly: boolean; /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; /** The disabled state of the component. */ disabled: boolean; From dea93af58c97c0ab4c106c866ecd8b1ca48e31d8 Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:22:03 +0300 Subject: [PATCH 4/8] docs: fill in missing docs --- src/components/calendar/types.ts | 9 +++++++++ .../date-range-picker/date-range-picker.ts | 1 + src/components/date-time-input/date-part.ts | 10 ++++++++++ src/components/expansion-panel/expansion-panel.ts | 15 ++++++++++++--- src/components/icon/registry/types.ts | 4 ++++ src/components/input/input.ts | 3 +++ src/components/radio/radio.ts | 2 ++ src/components/select/select-group.ts | 3 ++- stories/input.stories.ts | 7 ++++++- stories/radio.stories.ts | 7 ++++++- 10 files changed, 55 insertions(+), 6 deletions(-) diff --git a/src/components/calendar/types.ts b/src/components/calendar/types.ts index 959113ac5b..75e96b2a25 100644 --- a/src/components/calendar/types.ts +++ b/src/components/calendar/types.ts @@ -8,8 +8,17 @@ export enum DateRangeType { } /* creationType: DateRangeDescriptor */ +/** Describes a set of dates by combining a range type with the dates it applies to. */ export interface DateRangeDescriptor { + /** The kind of range being described, which determines how {@link DateRangeDescriptor.dateRange} is matched. */ type: DateRangeType; + /** + * The date or dates the descriptor applies to, interpreted according to {@link DateRangeDescriptor.type}. + * {@link DateRangeType.After} and {@link DateRangeType.Before} use the first date, + * {@link DateRangeType.Between} uses the first and the last, and + * {@link DateRangeType.Specific} matches every date listed. Not used by + * {@link DateRangeType.Weekdays} and {@link DateRangeType.Weekends}. + */ dateRange?: Date[]; } diff --git a/src/components/date-range-picker/date-range-picker.ts b/src/components/date-range-picker/date-range-picker.ts index 87346615f1..85342ef6b9 100644 --- a/src/components/date-range-picker/date-range-picker.ts +++ b/src/components/date-range-picker/date-range-picker.ts @@ -78,6 +78,7 @@ export interface DateRangeValue { } /* jsonAPIPlainObject */ +/** A predefined date range with label for {@link IgcDateRangePickerComponent.customRanges} */ export interface CustomDateRange { label: string; dateRange: DateRangeValue; diff --git a/src/components/date-time-input/date-part.ts b/src/components/date-time-input/date-part.ts index 1fcd278eee..991017a613 100644 --- a/src/components/date-time-input/date-part.ts +++ b/src/components/date-time-input/date-part.ts @@ -43,12 +43,22 @@ export const DEFAULT_DATE_PARTS_SPIN_DELTAS = Object.freeze({ seconds: 1, }); +/** + * The amounts by which each date or time part is incremented or decremented on + * a step action in date-time input; every part defaults to `1`. + */ export interface DatePartDeltas { + /** The number of days the date part is spun by. */ date?: number; + /** The number of months the month part is spun by. */ month?: number; + /** The number of years the year part is spun by. */ year?: number; + /** The number of hours the hours part is spun by. */ hours?: number; + /** The number of minutes the minutes part is spun by. */ minutes?: number; + /** The number of seconds the seconds part is spun by. */ seconds?: number; } diff --git a/src/components/expansion-panel/expansion-panel.ts b/src/components/expansion-panel/expansion-panel.ts index 28db279a48..f7e32bbb83 100644 --- a/src/components/expansion-panel/expansion-panel.ts +++ b/src/components/expansion-panel/expansion-panel.ts @@ -159,12 +159,18 @@ export default class IgcExpansionPanelComponent extends EventEmitterMixin< await this._setOpenState({ state: false, withEvent: true }); } - /** Toggles the panel open/close state. */ + /** + * Toggles the panel open/close state. + * @returns `true` when the open state was successfully changed. + */ public async toggle(): Promise { return this.open ? this.hide() : this.show(); } - /** Hides the panel content. */ + /** + * Hides the panel content. + * @returns `true` when the panel was successfully closed, or `false` if already closed. + */ public async hide(): Promise { if (!this.open) return false; @@ -172,7 +178,10 @@ export default class IgcExpansionPanelComponent extends EventEmitterMixin< return true; } - /** Shows the panel content. */ + /** + * Shows the panel content. + * @returns `true` when the panel was successfully opened, or `false` if already closed. + */ public async show(): Promise { if (this.open) return false; diff --git a/src/components/icon/registry/types.ts b/src/components/icon/registry/types.ts index 589884cf4f..e64e06108d 100644 --- a/src/components/icon/registry/types.ts +++ b/src/components/icon/registry/types.ts @@ -40,9 +40,13 @@ export interface BroadcastIconsChangeMessage { // Exported public types +/** Identifies a registered icon by its name and the collection it belongs to. */ export interface IconMeta { + /** The name identifier of the icon in the collection. */ name: string; + /** The name of the collection the icon is registered in. */ collection: string; + /** @internal Internal use only. */ external?: boolean; } diff --git a/src/components/input/input.ts b/src/components/input/input.ts index 7706471c5a..26266bf596 100644 --- a/src/components/input/input.ts +++ b/src/components/input/input.ts @@ -37,6 +37,9 @@ const Slots = setSlots( ); /** + * A highly customizable single-line text field for entering and editing data, + * with support for prefix/suffix content, helper text, form integration, and built-in validation. + * * @element igc-input * * @slot prefix - Renders content before the input. diff --git a/src/components/radio/radio.ts b/src/components/radio/radio.ts index e7d916d0d4..8e299c1189 100644 --- a/src/components/radio/radio.ts +++ b/src/components/radio/radio.ts @@ -45,6 +45,8 @@ export interface IgcRadioComponentEventMap { let nextId = 1; /** + * The radio component allows the user to select a single option from an available set of options that are listed side by side. + * * @element igc-radio * * @slot - The radio label. diff --git a/src/components/select/select-group.ts b/src/components/select/select-group.ts index 4986283d46..feefba7200 100644 --- a/src/components/select/select-group.ts +++ b/src/components/select/select-group.ts @@ -15,7 +15,8 @@ import { styles as shared } from '../dropdown/themes/shared/group/dropdown-group import IgcSelectItemComponent from './select-item.js'; /** - * @element igc-select-group - A container for a group of `igc-select-item` components. + * A container for a group of select items. + * @element igc-select-group * * @slot label - Contains the group's label. * @slot - Intended to contain the items belonging to this group. diff --git a/stories/input.stories.ts b/stories/input.stories.ts index 86cf4dc652..6ac0cfa3e7 100644 --- a/stories/input.stories.ts +++ b/stories/input.stories.ts @@ -27,7 +27,12 @@ const metadata: Meta = { title: 'Input', component: 'igc-input', parameters: { - docs: { description: { component: '' } }, + docs: { + description: { + component: + 'A highly customizable single-line text field for entering and editing data,\nwith support for prefix/suffix content, helper text, form integration, and built-in validation.', + }, + }, actions: { handles: ['igcInput', 'igcChange'] }, }, argTypes: { diff --git a/stories/radio.stories.ts b/stories/radio.stories.ts index d40f103f41..7eb4521758 100644 --- a/stories/radio.stories.ts +++ b/stories/radio.stories.ts @@ -15,7 +15,12 @@ const metadata: Meta = { title: 'Radio', component: 'igc-radio', parameters: { - docs: { description: { component: '' } }, + docs: { + description: { + component: + 'The radio component allows the user to select a single option from an available set of options that are listed side by side.', + }, + }, actions: { handles: ['igcChange'] }, }, argTypes: { From b6c3a5d65216688fff8b98521949dfdad56ef45c Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:22:34 +0300 Subject: [PATCH 5/8] docs(chip): correct event description --- src/components/chip/chip.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/components/chip/chip.ts b/src/components/chip/chip.ts index 967bd8bd9e..c635f78171 100644 --- a/src/components/chip/chip.ts +++ b/src/components/chip/chip.ts @@ -34,7 +34,7 @@ export interface IgcChipComponentEventMap { * @slot select - Content to render when the chip in selected state. * @slot remove - Content to override the default remove chip icon. * - * @fires igcRemove - Emits an event when the chip component is removed. Returns the removed chip component. + * @fires igcRemove - Emits an event when the chip component is removed. * @fires igcSelect - Emits event when the chip component is selected/deselected and any related animations and transitions also end. * * @csspart base - The base wrapper of the chip. From fbe999629e7b784c60683348be766c50ac7dceb0 Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:44:15 +0300 Subject: [PATCH 6/8] chore(storybook): fix date picker naming so it generates correctly --- ...cker.stories.ts => date-picker.stories.ts} | 86 +++++++++---------- 1 file changed, 43 insertions(+), 43 deletions(-) rename stories/{datepicker.stories.ts => date-picker.stories.ts} (89%) diff --git a/stories/datepicker.stories.ts b/stories/date-picker.stories.ts similarity index 89% rename from stories/datepicker.stories.ts rename to stories/date-picker.stories.ts index e11b9f04df..abc62cfd8a 100644 --- a/stories/datepicker.stories.ts +++ b/stories/date-picker.stories.ts @@ -18,13 +18,13 @@ defineComponents(IgcDatePickerComponent, IgcButtonComponent); // region default const metadata: Meta = { - title: 'Datepicker', - component: 'igc-datepicker', + title: 'DatePicker', + component: 'igc-date-picker', parameters: { docs: { description: { component: - 'igc-datepicker is a feature rich component used for entering a date through manual text input or\nchoosing date values from a calendar dialog that pops up.', + 'The date picker is a feature rich component used for entering a date through manual text input or\nchoosing date values from a calendar dialog that pops up.', }, }, actions: { @@ -43,7 +43,7 @@ const metadata: Meta = { type: 'boolean', description: 'Sets the state of the datepicker dropdown.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, label: { type: 'string', @@ -62,13 +62,13 @@ const metadata: Meta = { type: 'boolean', description: 'Whether to allow typing in the input.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, readOnly: { type: 'boolean', description: 'Makes the control a readonly field.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, value: { type: 'Date', @@ -94,17 +94,17 @@ const metadata: Meta = { control: 'date', }, headerOrientation: { - type: '"vertical" | "horizontal"', + type: '"horizontal" | "vertical"', description: 'The orientation of the calendar header.', - options: ['vertical', 'horizontal'], + options: ['horizontal', 'vertical'], control: { type: 'inline-radio' }, table: { defaultValue: { summary: 'horizontal' } }, }, orientation: { - type: '"vertical" | "horizontal"', + type: '"horizontal" | "vertical"', description: "The orientation of the multiple months displayed in the calendar's days view.", - options: ['vertical', 'horizontal'], + options: ['horizontal', 'vertical'], control: { type: 'inline-radio' }, table: { defaultValue: { summary: 'horizontal' } }, }, @@ -112,20 +112,20 @@ const metadata: Meta = { type: 'boolean', description: 'Determines whether the calendar hides its header.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, hideOutsideDays: { type: 'boolean', description: 'Controls the visibility of the dates that do not belong to the current month.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, outlined: { type: 'boolean', description: 'Whether the control will have outlined appearance.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, placeholder: { type: 'string', @@ -136,18 +136,18 @@ const metadata: Meta = { type: 'number', description: 'The number of months displayed in the calendar.', control: 'number', - table: { defaultValue: { summary: 1 } }, + table: { defaultValue: { summary: '1' } }, }, showWeekNumbers: { type: 'boolean', description: 'Whether to show the number of the week in the calendar.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, displayFormat: { type: 'string', description: - 'Format to display the value in when not editing.\nDefaults to the input format if not set.', + 'Format to display the value in when not editing.\nDefaults to the locale format if not set.', control: 'text', }, inputFormat: { @@ -156,18 +156,18 @@ const metadata: Meta = { 'The date format to apply on the input.\nDefaults to the current locale Intl.DateTimeFormat', control: 'text', }, - locale: { - type: 'string', - description: 'The locale settings used to display the value.', - control: 'text', - table: { defaultValue: { summary: 'en' } }, - }, prompt: { type: 'string', description: 'The prompt symbol to use for unfilled parts of the mask.', control: 'text', table: { defaultValue: { summary: '_' } }, }, + locale: { + type: 'string', + description: + 'Gets/Sets the locale used for formatting the display value.', + control: 'text', + }, weekStart: { type: '"sunday" | "monday" | "tuesday" | "wednesday" | "thursday" | "friday" | "saturday"', description: 'Sets the start day of the week for the calendar.', @@ -185,40 +185,41 @@ const metadata: Meta = { }, required: { type: 'boolean', - description: 'Makes the control a required field in a form context.', + description: + 'When set, makes the component a required field for validation.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, name: { type: 'string', - description: 'The name attribute of the control.', + description: 'The name of the control, submitted with the form data.', control: 'text', }, disabled: { type: 'boolean', - description: 'The disabled state of the component', + description: 'The disabled state of the component.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, invalid: { type: 'boolean', - description: 'Control the validity of the control.', + description: 'Sets the control into invalid state (visual state only).', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, keepOpenOnSelect: { type: 'boolean', description: 'Whether the component dropdown should be kept open on selection.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, keepOpenOnOutsideClick: { type: 'boolean', description: 'Whether the component dropdown should be kept open on clicking outside of it.', control: 'boolean', - table: { defaultValue: { summary: false } }, + table: { defaultValue: { summary: 'false' } }, }, }, args: { @@ -233,7 +234,6 @@ const metadata: Meta = { outlined: false, visibleMonths: 1, showWeekNumbers: false, - locale: 'en', prompt: '_', weekStart: 'sunday', required: false, @@ -246,7 +246,7 @@ const metadata: Meta = { export default metadata; -interface IgcDatepickerArgs { +interface IgcDatePickerArgs { /** Sets the state of the datepicker dropdown. */ open: boolean; /** The label of the datepicker. */ @@ -269,9 +269,9 @@ interface IgcDatepickerArgs { /** The maximum value required for the date picker to remain valid. */ max: Date; /** The orientation of the calendar header. */ - headerOrientation: 'vertical' | 'horizontal'; + headerOrientation: 'horizontal' | 'vertical'; /** The orientation of the multiple months displayed in the calendar's days view. */ - orientation: 'vertical' | 'horizontal'; + orientation: 'horizontal' | 'vertical'; /** Determines whether the calendar hides its header. */ hideHeader: boolean; /** Controls the visibility of the dates that do not belong to the current month. */ @@ -286,7 +286,7 @@ interface IgcDatepickerArgs { showWeekNumbers: boolean; /** * Format to display the value in when not editing. - * Defaults to the input format if not set. + * Defaults to the locale format if not set. */ displayFormat: string; /** @@ -294,10 +294,10 @@ interface IgcDatepickerArgs { * Defaults to the current locale Intl.DateTimeFormat */ inputFormat: string; - /** The locale settings used to display the value. */ - locale: string; /** The prompt symbol to use for unfilled parts of the mask. */ prompt: string; + /** Gets/Sets the locale used for formatting the display value. */ + locale: string; /** Sets the start day of the week for the calendar. */ weekStart: | 'sunday' @@ -307,20 +307,20 @@ interface IgcDatepickerArgs { | 'thursday' | 'friday' | 'saturday'; - /** Makes the control a required field in a form context. */ + /** When set, makes the component a required field for validation. */ required: boolean; - /** The name attribute of the control. */ + /** The name of the control, submitted with the form data. */ name: string; - /** The disabled state of the component */ + /** The disabled state of the component. */ disabled: boolean; - /** Control the validity of the control. */ + /** Sets the control into invalid state (visual state only). */ invalid: boolean; /** Whether the component dropdown should be kept open on selection. */ keepOpenOnSelect: boolean; /** Whether the component dropdown should be kept open on clicking outside of it. */ keepOpenOnOutsideClick: boolean; } -type Story = StoryObj; +type Story = StoryObj; // endregion From 07c06de7916150e334c81702ff2f0dcf327493a9 Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 16:56:17 +0300 Subject: [PATCH 7/8] docs(skills): updated related component skills to maintain consistency --- .../skills/add-component-property/SKILL.md | 107 ++++++++++++---- .github/skills/create-new-component/SKILL.md | 115 +++++++++++++++++- .github/skills/review-component-pr/SKILL.md | 57 +++++++++ 3 files changed, 252 insertions(+), 27 deletions(-) diff --git a/.github/skills/add-component-property/SKILL.md b/.github/skills/add-component-property/SKILL.md index 4593312886..af9bf0c8c7 100644 --- a/.github/skills/add-component-property/SKILL.md +++ b/.github/skills/add-component-property/SKILL.md @@ -103,7 +103,43 @@ public propertyName = 0; public propertyName: ComplexType = defaultValue; ``` -### 2. Update Component Render Method +### 2. Write the Description + +The JSDoc description is copied **verbatim** into `custom-elements.json`, the generated +Storybook `argTypes`/args interface, and the API docs of every framework wrapper +(Angular / React / Blazor). Write it as product documentation: + +- **No `igc-` tag names in prose.** Use the plain-English component name — "the select + component", "toggle buttons", "the tile manager" — not `igc-select` or + `` `igc-toggle-button` ``. Tag names belong only in `@element` and fenced `@example` + blocks. +- **Don't restate that it is an attribute.** `@attr` already says so. + `The label of the control.` — not `The label attribute of the control.` +- **Don't use `Gets/Sets`.** State what the value is; if the setter has side effects, add a + second sentence for the behavior. +- **Booleans start with "Whether …"** and must describe the `true` state accurately. Verify + against the implementation — a `hide*`/`disable*` name inverts the sentence + (`hideIndicators` → *"Whether the carousel should skip rendering of the indicator + controls."*). +- **Present tense**, not "will" (`an empty value returns an empty string`). + +```typescript +// ❌ Wrong +/** + * The outlined attribute of the control. + * @attr + */ + +// ✅ Right +/** + * Whether the control has an outlined appearance. + * @attr + */ +``` + +Full reference: [create-new-component → Documentation Conventions](../create-new-component/SKILL.md#documentation-conventions) + +### 3. Update Component Render Method If the property affects rendering, update the `render()` method: @@ -117,7 +153,7 @@ protected override render() { } ``` -### 3. Add Property Change Handler (if needed) +### 4. Add Property Change Handler (if needed) If the property requires side effects or needs to sync computed/dependent properties, use Lit's lifecycle hooks. @@ -153,7 +189,7 @@ protected override willUpdate(changedProperties: PropertyValues): void { - Always call `super.update(changedProperties)` when overriding `update()` - Check `changedProperties.has()` to avoid unnecessary work -### 4. Update Tests +### 5. Update Tests Add tests for the new property in `[component-name].spec.ts`: @@ -187,13 +223,23 @@ it('reflects to attribute', async () => { }); ``` -### 5. Update Storybook Story +### 6. Regenerate the Storybook Story Metadata -Add the property to `stories/[component-name].stories.ts`: +The `metadata` object, the `Igc[Component]Args` interface and their descriptions live inside +a **generated** `// region default … // endregion` block in +`stories/[component-name].stories.ts`. Do not hand-edit that block — regenerate it from the +JSDoc you just wrote: -**Update argTypes**: +```bash +npm run cem # regenerates custom-elements.json from the source JSDoc +npm run build:meta # rewrites the `// region default` block of each story +``` + +This produces the `argTypes` entry, the `args` default and the args-interface comment for +the new property, all carrying the description verbatim: ```typescript +// region default argTypes: { propertyName: { type: 'string', // or 'boolean', 'number' @@ -203,28 +249,21 @@ argTypes: { }, // ... other properties } -``` - -**Update args**: - -```typescript -args: { - propertyName: defaultValue, - // ... other properties -} -``` - -**Update interface**: - -```typescript +// ... interface IgcComponentArgs { /** [Property description] */ propertyName: PropertyType; // ... other properties } +// endregion ``` -**Update story template**: +If the generated description reads badly, fix the JSDoc in the component and regenerate — +never patch the story. (`stories/splitter.stories.ts` is the one exception: it has no +`// region default` markers and is maintained by hand.) + +**Update the story template** — this part lives outside the generated region and is edited +by hand: ```typescript export const Basic: Story = { @@ -234,7 +273,7 @@ export const Basic: Story = { }; ``` -### 6. Verify and Test +### 7. Verify and Test Run tests and verify in Storybook: @@ -253,15 +292,16 @@ npm run storybook - [ ] Property added with `@property` decorator - [ ] JSDoc comment includes `@attr` for primitives +- [ ] Description follows the [description rules](#2-write-the-description): no `igc-` tag + names, no "… attribute of the control", no `Gets/Sets`, booleans start with "Whether" + and describe the `true` state correctly - [ ] Type annotation correct - [ ] Default value appropriate - [ ] `reflect: true` only for primitives - [ ] Tests cover default value - [ ] Tests cover property changes - [ ] Tests cover attribute reflection (if applicable) -- [ ] Storybook argTypes updated -- [ ] Storybook args updated -- [ ] Storybook interface updated +- [ ] `npm run cem && npm run build:meta` run; generated story region committed - [ ] Story template uses new property - [ ] All tests pass - [ ] Property works in Storybook @@ -286,7 +326,22 @@ npm run storybook ### 4. Forgetting to Update Storybook **Problem**: New property not controllable in Storybook -**Solution**: Add to argTypes, args, interface, and template +**Solution**: Run `npm run cem && npm run build:meta` to regenerate the `// region default` +block, then wire the property into the story template by hand + +### 5. Hand-Editing the Generated Story Region + +**Problem**: The `argTypes` description is fixed directly in the story; the next +`npm run build:meta` reverts it, or the story and the API docs disagree +**Solution**: The JSDoc in the component is the single source of truth — fix it there and +regenerate + +### 6. Tag Names in the Description + +**Problem**: A description like `Gets/Sets the name for all child igc-radio components.` ships +into `custom-elements.json`, the Storybook docs and every framework wrapper's API docs +**Solution**: `The name applied to all radio buttons in the group.` — see +[Write the Description](#2-write-the-description) ## Reference Examples diff --git a/.github/skills/create-new-component/SKILL.md b/.github/skills/create-new-component/SKILL.md index 15770f3f01..5afa20a7e5 100644 --- a/.github/skills/create-new-component/SKILL.md +++ b/.github/skills/create-new-component/SKILL.md @@ -137,7 +137,7 @@ declare global { - **Organize code with region comments**: Internal state, Public properties, Lit lifecycle, Event handlers, Internal API, Public API - **Prefix internal API** (private properties/methods) with underscore: `_internalMethod()` - Add theming controller in constructor -- Include comprehensive JSDoc comments +- Include comprehensive JSDoc comments — follow [Documentation Conventions](#documentation-conventions) - Declare global HTMLElementTagNameMap interface - Use explicit return types for methods @@ -387,6 +387,104 @@ npm run test npm run storybook ``` +## Documentation Conventions + +Every JSDoc description on a public class, property, method, event, slot, CSS part or +CSS custom property is consumed **verbatim** by downstream tooling: + +- `custom-elements.json` (generated by `npm run cem`) +- the generated `// region default` block in `stories/[name].stories.ts` (`npm run build:meta`) +- the published API docs and the framework wrappers (Angular / React / Blazor), where the + custom element tag name is either wrong or meaningless + +So descriptions must read as product documentation, not as internal notes. + +### Never put `igc-` tag names in prose + +Refer to components by their plain-English name — "the carousel", "the tile manager", +"toggle buttons", "the select component". Never `igc-carousel`, `` `igc-toggle-button` `` +or ``. + +```typescript +// ❌ Wrong — tag names leak into the docs of every framework wrapper +/** + * The `igc-carousel` presents a set of `igc-carousel-slide`s. + * + * @slot - Renders `igc-toggle-button` component. + * @csspart svg - The igc-circular-progress SVG element. + */ + +// ✅ Right +/** + * The carousel presents a set of slides. + * + * @slot - Renders the toggle buttons of the group. + * @csspart svg - The circular progress SVG element. + */ +``` + +Tag names are **only** allowed in: + +- the `@element` tag itself — `@element igc-carousel` +- fenced `@example` code blocks (real markup/JS the user would write) +- literal event or attribute names that happen to contain `igc-` (e.g. the + `"igc-change-theme"` window event) +- `@internal` / `@hidden` members and non-exported internal controllers, mixins and + templates, where naming the concrete element is the point + +### Describe the thing, not the attribute + +The `@attr` tag already says it is an attribute. Don't repeat it in the sentence, and +don't use `Gets/Sets`. + +| ❌ Avoid | ✅ Prefer | +| -------------------------------------------- | --------------------------------------------------------------- | +| `The label attribute of the control.` | `The label of the control.` | +| `The placeholder attribute of the control.` | `The placeholder text of the control.` | +| `The outlined attribute of the control.` | `Whether the control has an outlined appearance.` | +| `The autofocus attribute of the control.` | `Whether the control should receive focus automatically.` | +| `Gets/Sets the name for all child radios.` | `The name applied to all radio buttons in the group.` | +| `an empty value will return an empty string` | `an empty value returns an empty string` | + +- Booleans start with **"Whether …"** and describe the `true` state accurately — check the + implementation, don't trust the property name (`hideIndicators` is *"Whether the carousel + should skip rendering of the indicator controls"*, not *"should render"*). +- Use present tense; avoid "will". +- If a setter has side effects beyond storing the value, state the value in the first + sentence and the behavior in a second one. +- Public methods that return something get an `@returns` tag. + +### Tag layout + +Keep the description as the leading summary paragraph and let the tags carry only their +own data. Don't append a description to `@element`: + +```typescript +// ❌ Wrong +/** + * @element igc-select-group - A container for a group of select items. + */ + +// ✅ Right +/** + * A container for a group of select items. + * + * @element igc-select-group + */ +``` + +### Regenerate after editing docs + +Story metadata is generated, not hand-written. After changing any description run: + +```bash +npm run cem # regenerates custom-elements.json from the JSDoc +npm run build:meta # rewrites the `// region default` block of each story +``` + +Only `stories/splitter.stories.ts` is hand-maintained (it has no `// region default` +markers) — update its descriptions manually. + ## Validation Checklist Verify all of the following: @@ -395,6 +493,8 @@ Verify all of the following: - [ ] Extends `LitElement` (or appropriate mixin) - [ ] `tagName` and `register()` static members defined - [ ] JSDoc comments with `@element`, `@slot`, `@csspart` +- [ ] No `igc-` tag names in any description prose (see [Documentation Conventions](#documentation-conventions)) +- [ ] `npm run cem && npm run build:meta` run, generated story region committed - [ ] Theming controller added in constructor - [ ] SCSS files exist in themes directory - [ ] `themes.ts` aggregator imports all themes @@ -443,6 +543,19 @@ Verify all of the following: **Problem**: Exports not alphabetized in `src/index.ts` **Solution**: Find correct alphabetical position before adding +### 8. Tag Names in Descriptions + +**Problem**: A description reads `The prefix wrapper of the igc-textarea.` — the tag name is +copied verbatim into `custom-elements.json`, the Storybook docs and every framework wrapper's +API docs, where it is wrong or meaningless +**Solution**: Use the plain-English component name. See [Documentation Conventions](#documentation-conventions) + +### 9. Editing Generated Story Metadata by Hand + +**Problem**: A story's `// region default` block is edited directly and gets clobbered on the +next `npm run build:meta`, or the block drifts out of sync with the source JSDoc +**Solution**: Edit the JSDoc in the component, then run `npm run cem && npm run build:meta` + ## Reference Examples ### Simple Display Component: Badge diff --git a/.github/skills/review-component-pr/SKILL.md b/.github/skills/review-component-pr/SKILL.md index f69e038469..dca8767a1f 100644 --- a/.github/skills/review-component-pr/SKILL.md +++ b/.github/skills/review-component-pr/SKILL.md @@ -325,6 +325,10 @@ describe('Component', () => { - [ ] **At least one story** demonstrates basic usage - [ ] **Multiple stories** for different variants (ideal) - [ ] **Story renders correctly** in Storybook +- [ ] **Generated region regenerated, not hand-edited** — the `// region default … // endregion` + block comes from `npm run cem && npm run build:meta`. If a description differs from the + component's JSDoc, the story was edited by hand and will be clobbered. + (`stories/splitter.stories.ts` has no region markers and is maintained manually.) ### 11. Documentation @@ -336,6 +340,10 @@ describe('Component', () => { - [ ] **`@event` tags** for emitted events - [ ] **Property descriptions** clear and complete - [ ] **Examples** in JSDoc if complex usage +- [ ] **No `igc-` tag names in description prose** — see below +- [ ] **Descriptions don't restate the tag** — no "The label *attribute* of the control", + no `Gets/Sets`; booleans start with "Whether" and describe the `true` state accurately +- [ ] **Description is the leading summary paragraph**, not appended to `@element` **Complete Example**: @@ -357,6 +365,42 @@ describe('Component', () => { */ ``` +**No tag names in prose**: every description reaches `custom-elements.json`, the generated +Storybook docs and the Angular / React / Blazor wrapper API docs verbatim, where `igc-*` is +wrong or meaningless. Use the plain-English component name. + +```typescript +// ❌ Reject +/** + * The `igc-carousel` presents a set of `igc-carousel-slide`s. + * + * @slot - Renders `igc-toggle-button` component. + * @csspart base - The native button element of the igc-button component. + */ + +// ✅ Accept +/** + * The carousel presents a set of slides. + * + * @slot - Renders the toggle buttons of the group. + * @csspart base - The native button element of the button component. + */ +``` + +Tag names are allowed **only** in the `@element` tag, inside fenced `@example` code blocks, +in literal event/attribute names that contain `igc-` (e.g. the `"igc-change-theme"` window +event), and in `@internal`/`@hidden` members or non-exported internal controllers, mixins and +templates. + +Quick grep to catch leaks — this should return nothing outside `@element`, `@example` blocks +and internal members: + +```bash +grep -rn "igc-" --include="*.ts" src/ \ + | grep -E "^\S+:[0-9]+:\s*\*" \ + | grep -vE "@element|@example|\.spec\.ts" +``` + ### 12. Form Integration (if applicable) - [ ] **FormAssociatedRequiredMixin** used for form controls @@ -432,6 +476,19 @@ describe('Component', () => { **Problem**: Using `#privateField` syntax **Fix**: Use `_privateField` or TypeScript `private` keyword +### Issue: `igc-` Tag Names in Descriptions + +**Problem**: Prose like ``The `igc-carousel` presents a set of `igc-carousel-slide`s`` or +`The prefix wrapper of the igc-textarea.` ships verbatim into `custom-elements.json`, the +Storybook docs and the Angular / React / Blazor wrapper API docs +**Fix**: Use the plain-English component name. See [Documentation](#11-documentation) + +### Issue: Hand-Edited Story Metadata + +**Problem**: A description inside `// region default` was fixed in the story instead of the +component JSDoc — it reverts on the next `npm run build:meta` +**Fix**: Fix the JSDoc, then run `npm run cem && npm run build:meta` + ## Review Process 1. **Start with structure** - Verify all required files exist From eb7995cba7a9b38cccf1aea99d1c03a4571ebdfc Mon Sep 17 00:00:00 2001 From: damyanpetev Date: Mon, 3 Aug 2026 19:18:17 +0300 Subject: [PATCH 8/8] docs: update splitter docs & story --- .../skills/add-component-property/SKILL.md | 8 +- .github/skills/create-new-component/SKILL.md | 12 +- .github/skills/review-component-pr/SKILL.md | 8 +- src/components/splitter/splitter.ts | 18 +++ stories/splitter.stories.ts | 149 +++++++++++++----- 5 files changed, 147 insertions(+), 48 deletions(-) diff --git a/.github/skills/add-component-property/SKILL.md b/.github/skills/add-component-property/SKILL.md index af9bf0c8c7..2959d1c12d 100644 --- a/.github/skills/add-component-property/SKILL.md +++ b/.github/skills/add-component-property/SKILL.md @@ -259,8 +259,12 @@ interface IgcComponentArgs { ``` If the generated description reads badly, fix the JSDoc in the component and regenerate — -never patch the story. (`stories/splitter.stories.ts` is the one exception: it has no -`// region default` markers and is maintained by hand.) +never patch the story. Every story is generated; there are no hand-maintained exceptions. + +If your new property doesn't appear after regenerating, the story is being skipped silently. +Check that the filename matches the tag name (`igc-date-picker` → `date-picker.stories.ts`) and +that the `// region default` / `// endregion` pair is present — a missing region makes the +generator a no-op with no warning. **Update the story template** — this part lives outside the generated region and is edited by hand: diff --git a/.github/skills/create-new-component/SKILL.md b/.github/skills/create-new-component/SKILL.md index 5afa20a7e5..bc51b4ecfb 100644 --- a/.github/skills/create-new-component/SKILL.md +++ b/.github/skills/create-new-component/SKILL.md @@ -482,8 +482,16 @@ npm run cem # regenerates custom-elements.json from the JSDoc npm run build:meta # rewrites the `// region default` block of each story ``` -Only `stories/splitter.stories.ts` is hand-maintained (it has no `// region default` -markers) — update its descriptions manually. +Every story is generated — there are no hand-maintained exceptions. Two failure modes will +silently skip a story, so check for both when your descriptions don't show up: + +1. **Filename mismatch.** `build-stories.mjs` derives the filename from the tag name, so + `igc-date-picker` must live in `date-picker.stories.ts`. A mismatch logs + *"No story file found for …, skipping."* — easy to miss in the build output. +2. **Missing region markers.** If the file has no `// region default` / `// endregion` pair the + generator finds nothing to replace and writes nothing, **with no warning at all**. Wrap the + region from `const metadata` through `type Story = StoryObj<…>` inclusive — it also owns + `export default metadata;` and the args interface. ## Validation Checklist diff --git a/.github/skills/review-component-pr/SKILL.md b/.github/skills/review-component-pr/SKILL.md index dca8767a1f..370e51455b 100644 --- a/.github/skills/review-component-pr/SKILL.md +++ b/.github/skills/review-component-pr/SKILL.md @@ -327,8 +327,12 @@ describe('Component', () => { - [ ] **Story renders correctly** in Storybook - [ ] **Generated region regenerated, not hand-edited** — the `// region default … // endregion` block comes from `npm run cem && npm run build:meta`. If a description differs from the - component's JSDoc, the story was edited by hand and will be clobbered. - (`stories/splitter.stories.ts` has no region markers and is maintained manually.) + component's JSDoc, the story was edited by hand and will be clobbered. Every story is + generated; there are no hand-maintained exceptions. +- [ ] **Story is actually reachable by the generator** — two failure modes skip it: a filename + that doesn't match the tag name (`igc-date-picker` → `date-picker.stories.ts`, which + *warns*), and a missing `// region default` / `// endregion` pair (which is a **silent** + no-op). A story whose descriptions don't match the source JSDoc is the symptom of both. ### 11. Documentation diff --git a/src/components/splitter/splitter.ts b/src/components/splitter/splitter.ts index 22b4a973e4..81fac1d629 100644 --- a/src/components/splitter/splitter.ts +++ b/src/components/splitter/splitter.ts @@ -252,6 +252,9 @@ export default class IgcSplitterComponent extends EventEmitterMixin< /** * The minimum size of the start pane. * + * Accepts a CSS length, e.g. `100px` or `20%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + * * @attr start-min-size */ @property({ attribute: 'start-min-size' }) @@ -266,6 +269,9 @@ export default class IgcSplitterComponent extends EventEmitterMixin< /** * The minimum size of the end pane. * + * Accepts a CSS length, e.g. `100px` or `20%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + * * @attr end-min-size */ @property({ attribute: 'end-min-size' }) @@ -280,6 +286,9 @@ export default class IgcSplitterComponent extends EventEmitterMixin< /** * The maximum size of the start pane. * + * Accepts a CSS length, e.g. `500px` or `80%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + * * @attr start-max-size */ @property({ attribute: 'start-max-size' }) @@ -294,6 +303,9 @@ export default class IgcSplitterComponent extends EventEmitterMixin< /** * The maximum size of the end pane. * + * Accepts a CSS length, e.g. `500px` or `80%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + * * @attr end-max-size */ @property({ attribute: 'end-max-size' }) @@ -308,6 +320,9 @@ export default class IgcSplitterComponent extends EventEmitterMixin< /** * The size of the start pane. * + * Accepts a CSS length, e.g. `200px` or `50%`. Setting `auto`, a negative + * value, or a percentage above 100 falls back to automatic sizing. + * * @attr start-size */ @property({ attribute: 'start-size' }) @@ -322,6 +337,9 @@ export default class IgcSplitterComponent extends EventEmitterMixin< /** * The size of the end pane. * + * Accepts a CSS length, e.g. `200px` or `50%`. Setting `auto`, a negative + * value, or a percentage above 100 falls back to automatic sizing. + * * @attr end-size */ @property({ attribute: 'end-size' }) diff --git a/stories/splitter.stories.ts b/stories/splitter.stories.ts index a8d5432c1f..802edbd4f8 100644 --- a/stories/splitter.stories.ts +++ b/stories/splitter.stories.ts @@ -10,6 +10,7 @@ import { html } from 'lit'; defineComponents(IgcSplitterComponent, IgcButtonComponent); +// region default const metadata: Meta = { title: 'Splitter', component: 'igc-splitter', @@ -17,105 +18,169 @@ const metadata: Meta = { docs: { description: { component: - 'The splitter divides the view into two resizable and collapsible panels separated by a draggable bar. ' + - 'Use the `start` and `end` slots to project content into each panel. ' + - 'Panels can be resized by dragging, using keyboard shortcuts, or collapsed programmatically via `toggle()`.', + 'A splitter component that provides a resizable split-pane layout, dividing the view\ninto two panels — *start* and *end* — separated by a draggable bar.\n\nPanels can be resized by dragging the bar, using keyboard shortcuts, or collapsed/expanded\nusing the built-in collapse buttons or the programmatic `toggle()` API.\nNested splitters are supported for more complex layouts.', }, }, - actions: { - handles: ['igcResizeStart', 'igcResizing', 'igcResizeEnd'], - }, + actions: { handles: ['igcResizeStart', 'igcResizing', 'igcResizeEnd'] }, }, argTypes: { orientation: { + type: '"horizontal" | "vertical"', + description: + 'The orientation of the splitter, which determines the direction of resizing and collapsing.', options: ['horizontal', 'vertical'], control: { type: 'inline-radio' }, - description: - 'The axis along which the panels are split. `horizontal` places start/end side‑by‑side; `vertical` stacks them.', table: { defaultValue: { summary: 'horizontal' } }, }, disableCollapse: { type: 'boolean', description: - 'When `true`, the collapse/expand buttons are hidden and panes cannot be collapsed.', + 'When true, prevents the user from collapsing either pane.\nThis also hides the expand/collapse buttons on the splitter bar.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, - hideCollapseButtons: { + disableResize: { type: 'boolean', description: - 'When `true`, hides the collapse/expand buttons without disabling the collapse behavior.', + 'When true, prevents the user from resizing the panes by dragging the splitter bar or using keyboard shortcuts.\nThis also hides the drag handle on the splitter bar.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, - hideDragHandle: { + hideCollapseButtons: { type: 'boolean', description: - 'When `true`, hides the drag handle icon on the splitter bar.', + 'When true, hides the expand/collapse buttons on the splitter bar.\n\nNote that the buttons will also be hidden if `disable-collapse` is true or\nif a pane is currently collapsed.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, - disableResize: { + hideDragHandle: { type: 'boolean', description: - 'When `true`, prevents resizing by dragging or keyboard shortcuts.', + 'When true, hides the drag handle on the splitter bar.\n\nNote that the drag handle will also be hidden if `disable-resize` is true.', control: 'boolean', table: { defaultValue: { summary: 'false' } }, }, - startSize: { - control: { type: 'text' }, + startMinSize: { + type: 'string', description: - 'Initial size of the start panel. Accepts CSS length values (`200px`, `50%`) or `auto`.', + 'The minimum size of the start pane.\n\nAccepts a CSS length, e.g. `100px` or `20%`. Setting `auto`, a negative\nvalue, or a percentage above 100 removes the constraint.', + control: 'text', }, - endSize: { - control: { type: 'text' }, + endMinSize: { + type: 'string', description: - 'Initial size of the end panel. Accepts CSS length values (`200px`, `50%`) or `auto`.', - }, - startMinSize: { - control: { type: 'text' }, - description: 'Minimum size of the start panel (`100px`, `20%`).', + 'The minimum size of the end pane.\n\nAccepts a CSS length, e.g. `100px` or `20%`. Setting `auto`, a negative\nvalue, or a percentage above 100 removes the constraint.', + control: 'text', }, startMaxSize: { - control: { type: 'text' }, - description: 'Maximum size of the start panel (`500px`, `80%`).', - }, - endMinSize: { - control: { type: 'text' }, - description: 'Minimum size of the end panel (`100px`, `20%`).', + type: 'string', + description: + 'The maximum size of the start pane.\n\nAccepts a CSS length, e.g. `500px` or `80%`. Setting `auto`, a negative\nvalue, or a percentage above 100 removes the constraint.', + control: 'text', }, endMaxSize: { - control: { type: 'text' }, - description: 'Maximum size of the end panel (`500px`, `80%`).', + type: 'string', + description: + 'The maximum size of the end pane.\n\nAccepts a CSS length, e.g. `500px` or `80%`. Setting `auto`, a negative\nvalue, or a percentage above 100 removes the constraint.', + control: 'text', + }, + startSize: { + type: 'string', + description: + 'The size of the start pane.\n\nAccepts a CSS length, e.g. `200px` or `50%`. Setting `auto`, a negative\nvalue, or a percentage above 100 falls back to automatic sizing.', + control: 'text', + }, + endSize: { + type: 'string', + description: + 'The size of the end pane.\n\nAccepts a CSS length, e.g. `200px` or `50%`. Setting `auto`, a negative\nvalue, or a percentage above 100 falls back to automatic sizing.', + control: 'text', }, }, args: { orientation: 'horizontal', disableCollapse: false, + disableResize: false, hideCollapseButtons: false, hideDragHandle: false, - disableResize: false, }, }; export default metadata; interface IgcSplitterArgs { + /** The orientation of the splitter, which determines the direction of resizing and collapsing. */ orientation: 'horizontal' | 'vertical'; + /** + * When true, prevents the user from collapsing either pane. + * This also hides the expand/collapse buttons on the splitter bar. + */ disableCollapse: boolean; + /** + * When true, prevents the user from resizing the panes by dragging the splitter bar or using keyboard shortcuts. + * This also hides the drag handle on the splitter bar. + */ + disableResize: boolean; + /** + * When true, hides the expand/collapse buttons on the splitter bar. + * + * Note that the buttons will also be hidden if `disable-collapse` is true or + * if a pane is currently collapsed. + */ hideCollapseButtons: boolean; + /** + * When true, hides the drag handle on the splitter bar. + * + * Note that the drag handle will also be hidden if `disable-resize` is true. + */ hideDragHandle: boolean; - disableResize: boolean; - startSize?: string; - endSize?: string; - startMinSize?: string; - startMaxSize?: string; - endMinSize?: string; - endMaxSize?: string; + /** + * The minimum size of the start pane. + * + * Accepts a CSS length, e.g. `100px` or `20%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + */ + startMinSize: string; + /** + * The minimum size of the end pane. + * + * Accepts a CSS length, e.g. `100px` or `20%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + */ + endMinSize: string; + /** + * The maximum size of the start pane. + * + * Accepts a CSS length, e.g. `500px` or `80%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + */ + startMaxSize: string; + /** + * The maximum size of the end pane. + * + * Accepts a CSS length, e.g. `500px` or `80%`. Setting `auto`, a negative + * value, or a percentage above 100 removes the constraint. + */ + endMaxSize: string; + /** + * The size of the start pane. + * + * Accepts a CSS length, e.g. `200px` or `50%`. Setting `auto`, a negative + * value, or a percentage above 100 falls back to automatic sizing. + */ + startSize: string; + /** + * The size of the end pane. + * + * Accepts a CSS length, e.g. `200px` or `50%`. Setting `auto`, a negative + * value, or a percentage above 100 falls back to automatic sizing. + */ + endSize: string; } - type Story = StoryObj; +// endregion + const LOREM = 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque scelerisque elementum ante, et tincidunt eros ultrices sit amet. Mauris non consectetur nunc. In hac habitasse platea dictumst.';