-
Notifications
You must be signed in to change notification settings - Fork 55
chore(docs): clean up miscellaneous component documentation #1992
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -45,7 +45,7 @@ export interface AlertProps | |
*/ | ||
accessibility?: Accessibility | ||
|
||
/** An Alert can contain action buttons. */ | ||
/** An alert can contain action buttons. */ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. We should standardize on capitalization conventions across all components, but for now I think it's sufficient to ensure they are consistent within a single component. In this case, most were already lowercase. |
||
actions?: ShorthandValue<ButtonGroupProps> | ShorthandCollection<ButtonProps> | ||
|
||
/** An alert may contain an icon. */ | ||
|
@@ -54,7 +54,7 @@ export interface AlertProps | |
/** An alert may contain a header. */ | ||
header?: ShorthandValue<TextProps> | ||
|
||
/** Controls Alert's relation to neighboring items. */ | ||
/** An alert's position relative to neighboring items. */ | ||
attached?: boolean | 'top' | 'bottom' | ||
|
||
/** An alert can only take up the width of its content. */ | ||
|
@@ -86,22 +86,22 @@ export interface AlertProps | |
onDismiss?: ComponentEventHandler<AlertProps> | ||
|
||
/** | ||
* Called after user's focus. | ||
* Called after the alert is focused. | ||
* @param {SyntheticEvent} event - React's original SyntheticEvent. | ||
* @param {object} data - All props. | ||
*/ | ||
onFocus?: ComponentEventHandler<AlertProps> | ||
|
||
/** An alert may be formatted to display a successful message. */ | ||
/** An alert can be formatted to display a successful message. */ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Minor consistency change: "may" and "can" were used interchangeably, so I just picked one. |
||
success?: boolean | ||
|
||
/** An alert can be set to visible to force itself to be shown. */ | ||
visible?: boolean | ||
|
||
/** An alert may be formatted to display a warning message. */ | ||
/** An alert can be formatted to display a warning message. */ | ||
warning?: boolean | ||
|
||
/** Body contains header and content elements. */ | ||
/** An alert can have a body that contains header and content elements. */ | ||
body?: ShorthandValue<BoxProps> | ||
} | ||
|
||
|
@@ -256,7 +256,7 @@ class Alert extends AutoControlledComponent<WithAsProp<AlertProps>, AlertState> | |
} | ||
|
||
/** | ||
* An Alert displays a brief, important message to attract the user's attention without interrupting the user's task. | ||
* An Alert displays a brief, important message to attract a user's attention without interrupting their current task. | ||
* | ||
* @accessibility | ||
* Implements [ARIA Alert](https://www.w3.org/TR/wai-aria-practices-1.1/#alert) design pattern. | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -24,42 +24,42 @@ export interface AnimationProps | |
/** The name for the animation that should be applied, defined in the theme. */ | ||
name?: string | ||
|
||
/** The delay property specifies a delay for the start of an animation. Negative values are | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Most components don't reiterate the name of the property in the doc string, which I think is a good thing. I've removed it from Animation to make it consistent with the rest of the components. |
||
/** Specifies a delay for the start of an animation. Negative values are | ||
* also allowed. If using negative values, the animation will start as if it had already been | ||
* playing for N seconds. | ||
* playing for that amount of time. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Since this is a string, it's not necessarily in seconds. |
||
*/ | ||
delay?: string | ||
|
||
/** The direction property specifies whether an animation should be played forwards, backwards | ||
* or in alternate cycles. It can have the following values: | ||
* - normal - The animation is played as normal (forwards). This is default | ||
/** Specifies whether an animation should be played forwards, backwards or in alternate cycles. | ||
* It can have the following values: | ||
* - normal (default) - The animation is played as normal (forwards) | ||
* - reverse - The animation is played in reverse direction (backwards) | ||
* - alternate - The animation is played forwards first, then backwards | ||
* - alternate-reverse - The animation is played backwards first, then forwards. | ||
* - alternate-reverse - The animation is played backwards first, then forwards | ||
*/ | ||
direction?: string | ||
|
||
/** The duration property defines how long time an animation should take to complete. */ | ||
/** Specifies how long an animation should take to complete. */ | ||
duration?: string | ||
|
||
/** | ||
* The fillMode property specifies a style for the target element when the animation | ||
* is not playing (before it starts, after it ends, or both). It can have the following values: | ||
* - none - Default value. Animation will not apply any styles to the element before or after it is executing | ||
* Specifies a style for the target element when the animation is not playing (i.e. before it starts, after it ends, or both). | ||
* It can have the following values: | ||
* - none (default) - Animation will not apply any styles to the element before or after it is executing | ||
* - forwards - The element will retain the style values that is set by the last keyframe (depends on animation-direction and animation-iteration-count) | ||
* - backwards - The element will get the style values that is set by the first keyframe (depends on animation-direction), and retain this during the animation-delay period | ||
* - both - The animation will follow the rules for both forwards and backwards, extending the animation properties in both directions | ||
* */ | ||
fillMode?: string | ||
|
||
/** The animation-iteration-count property specifies the number of times an animation should run. */ | ||
/** Specifies the number of times an animation should run. */ | ||
iterationCount?: string | ||
|
||
/** Custom parameters for the keyframe defined for the animation. */ | ||
keyframeParams?: object | ||
|
||
/** | ||
* The playState property specifies whether the animation is running or paused. It can have the following values: | ||
* Specifies whether the animation is running or paused. It can have the following values: | ||
* - paused - Specifies that the animation is paused | ||
* - running - Default value. Specifies that the animation is running | ||
* - initial - Sets this property to its default value. | ||
|
@@ -68,7 +68,7 @@ export interface AnimationProps | |
playState?: string | ||
|
||
/** | ||
* The timingFunction property specifies the speed curve of the animation. It can have the following values: | ||
* Specifies the speed curve of the animation. It can have the following values: | ||
* - ease - Specifies an animation with a slow start, then fast, then end slowly (this is default) | ||
* - linear - Specifies an animation with the same speed from start to end | ||
* - ease-in - Specifies an animation with a slow start | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -27,39 +27,39 @@ export interface CheckboxProps extends UIComponentProps, ChildrenComponentProps | |
/** Accessibility behavior if overridden by the user. */ | ||
accessibility?: Accessibility | ||
|
||
/** Initial checked value. */ | ||
/** A checkbox can be checked by default. */ | ||
defaultChecked?: SupportedIntrinsicInputProps['defaultChecked'] | ||
|
||
/** Whether or not item is checked. */ | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I believe |
||
/** A checkbox's checked state can be controlled. */ | ||
checked?: SupportedIntrinsicInputProps['checked'] | ||
|
||
/** An item can appear disabled and be unable to change states. */ | ||
/** A checkbox can appear disabled and be unable to change states. */ | ||
disabled?: SupportedIntrinsicInputProps['disabled'] | ||
|
||
/** The item indicator can be user-defined icon. */ | ||
/** A checkbox's indicator icon can be customized. */ | ||
icon?: ShorthandValue<IconProps> | ||
|
||
/** The label of the item. */ | ||
/** A checkbox can render a label next to its indicator. */ | ||
label?: ShorthandValue<TextProps> | ||
|
||
/** A label in the loader can have different positions. */ | ||
/** A checkbox's label can be rendered in different positions. */ | ||
labelPosition?: 'start' | 'end' | ||
|
||
/** | ||
* Called after item checked state is changed. | ||
* Called after a checkbox's checked state is changed. | ||
* @param {SyntheticEvent} event - React's original SyntheticEvent. | ||
* @param {object} data - All props. | ||
*/ | ||
onChange?: ComponentEventHandler<CheckboxProps> | ||
|
||
/** | ||
* Called after click. | ||
* Called after a checkbox is clicked. | ||
* @param {SyntheticEvent} event - React's original SyntheticEvent. | ||
* @param {object} data - All props. | ||
*/ | ||
onClick?: ComponentEventHandler<CheckboxProps> | ||
|
||
/** A checkbox can be formatted to show an on or off choice. */ | ||
/** A checkbox can be formatted to show an "on or off" choice. */ | ||
toggle?: boolean | ||
} | ||
|
||
|
@@ -185,7 +185,7 @@ Checkbox.create = createShorthandFactory({ | |
}) | ||
|
||
/** | ||
* A Checkbox allows to toggle between two choices -- checked and not checked. | ||
* A Checkbox allows a user to make a choice between two mutually exclusive options. | ||
* | ||
* @accessibility | ||
* Implements [ARIA Checkbox](https://www.w3.org/TR/wai-aria-practices-1.1/#checkbox) design pattern. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Consistency: Accordion uses the word
expanded
to describe its panels' open states, and that term is also already used in describing other props.