@atlaskit/ads-mcp 0.17.0 → 0.17.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/README.md +88 -0
- package/dist/cjs/index.js +5 -18
- package/dist/cjs/tools/get-all-icons/icons.js +43 -0
- package/dist/cjs/tools/get-all-icons/index.js +4 -19
- package/dist/cjs/tools/get-all-tokens/index.js +3 -6
- package/dist/cjs/tools/get-all-tokens/tokens.js +18 -0
- package/dist/cjs/tools/get-components/components.codegen.js +3984 -0
- package/dist/cjs/tools/get-components/components.js +423 -235
- package/dist/cjs/tools/get-components/index.js +2 -2
- package/dist/cjs/tools/get-components/load-all-components.js +16 -0
- package/dist/cjs/tools/get-guidelines/guidelines-structured-content.codegen.js +72 -6
- package/dist/cjs/tools/get-lint-rules/lint-rules-structured-content.codegen.js +7 -7
- package/dist/cjs/tools/search-components/index.js +13 -12
- package/dist/cjs/tools/search-icons/index.js +7 -24
- package/dist/es2019/index.js +5 -17
- package/dist/es2019/tools/get-all-icons/icons.js +25 -0
- package/dist/es2019/tools/get-all-icons/index.js +1 -10
- package/dist/es2019/tools/get-all-tokens/index.js +2 -5
- package/dist/es2019/tools/get-all-tokens/tokens.js +13 -0
- package/dist/es2019/tools/get-components/components.codegen.js +3978 -0
- package/dist/es2019/tools/get-components/components.js +423 -235
- package/dist/es2019/tools/get-components/index.js +11 -9
- package/dist/es2019/tools/get-components/load-all-components.js +10 -0
- package/dist/es2019/tools/get-guidelines/guidelines-structured-content.codegen.js +72 -6
- package/dist/es2019/tools/get-lint-rules/lint-rules-structured-content.codegen.js +7 -7
- package/dist/es2019/tools/search-components/index.js +2 -1
- package/dist/es2019/tools/search-icons/index.js +1 -10
- package/dist/esm/index.js +5 -18
- package/dist/esm/tools/get-all-icons/icons.js +37 -0
- package/dist/esm/tools/get-all-icons/index.js +3 -18
- package/dist/esm/tools/get-all-tokens/index.js +2 -5
- package/dist/esm/tools/get-all-tokens/tokens.js +13 -0
- package/dist/esm/tools/get-components/components.codegen.js +3978 -0
- package/dist/esm/tools/get-components/components.js +423 -235
- package/dist/esm/tools/get-components/index.js +2 -2
- package/dist/esm/tools/get-components/load-all-components.js +10 -0
- package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js +72 -6
- package/dist/esm/tools/get-lint-rules/lint-rules-structured-content.codegen.js +7 -7
- package/dist/esm/tools/search-components/index.js +9 -8
- package/dist/esm/tools/search-icons/index.js +3 -20
- package/dist/types/tools/get-all-icons/icons.d.ts +11 -0
- package/dist/types/tools/get-all-tokens/tokens.d.ts +7 -0
- package/dist/types/tools/get-components/components.codegen.d.ts +10 -0
- package/dist/types/tools/get-components/components.d.ts +1 -1
- package/dist/types/tools/get-components/load-all-components.d.ts +2 -0
- package/dist/types/tools/get-components/types.d.ts +20 -14
- package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +1 -1
- package/dist/types/tools/get-lint-rules/lint-rules-structured-content.codegen.d.ts +1 -1
- package/dist/types-ts4.5/tools/get-all-icons/icons.d.ts +11 -0
- package/dist/types-ts4.5/tools/get-all-tokens/tokens.d.ts +7 -0
- package/dist/types-ts4.5/tools/get-components/components.codegen.d.ts +10 -0
- package/dist/types-ts4.5/tools/get-components/components.d.ts +1 -1
- package/dist/types-ts4.5/tools/get-components/load-all-components.d.ts +2 -0
- package/dist/types-ts4.5/tools/get-components/types.d.ts +20 -14
- package/dist/types-ts4.5/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +1 -1
- package/dist/types-ts4.5/tools/get-lint-rules/lint-rules-structured-content.codegen.d.ts +1 -1
- package/package.json +5 -3
- package/dist/cjs/tools/get-icons/icon-mcp-structured-content.codegen.js +0 -8
- package/dist/cjs/tools/get-icons/icon-structured-content.codegen.js +0 -8
- package/dist/cjs/tools/get-icons/index.js +0 -135
- package/dist/cjs/tools/get-tokens/index.js +0 -125
- package/dist/cjs/tools/get-tokens/token-mcp-structured-content.codegen.js +0 -2356
- package/dist/cjs/tools/get-tokens/token-structured-content.codegen.js +0 -2356
- package/dist/es2019/tools/get-icons/icon-mcp-structured-content.codegen.js +0 -8
- package/dist/es2019/tools/get-icons/icon-structured-content.codegen.js +0 -8
- package/dist/es2019/tools/get-icons/index.js +0 -110
- package/dist/es2019/tools/get-tokens/index.js +0 -100
- package/dist/es2019/tools/get-tokens/token-mcp-structured-content.codegen.js +0 -2350
- package/dist/es2019/tools/get-tokens/token-structured-content.codegen.js +0 -2350
- package/dist/esm/tools/get-icons/icon-mcp-structured-content.codegen.js +0 -8
- package/dist/esm/tools/get-icons/icon-structured-content.codegen.js +0 -8
- package/dist/esm/tools/get-icons/index.js +0 -128
- package/dist/esm/tools/get-tokens/index.js +0 -118
- package/dist/esm/tools/get-tokens/token-mcp-structured-content.codegen.js +0 -2350
- package/dist/esm/tools/get-tokens/token-structured-content.codegen.js +0 -2350
- package/dist/types/tools/get-icons/icon-mcp-structured-content.codegen.d.ts +0 -13
- package/dist/types/tools/get-icons/icon-structured-content.codegen.d.ts +0 -13
- package/dist/types/tools/get-icons/index.d.ts +0 -35
- package/dist/types/tools/get-tokens/index.d.ts +0 -35
- package/dist/types/tools/get-tokens/token-mcp-structured-content.codegen.d.ts +0 -13
- package/dist/types/tools/get-tokens/token-structured-content.codegen.d.ts +0 -13
- package/dist/types-ts4.5/tools/get-icons/icon-mcp-structured-content.codegen.d.ts +0 -13
- package/dist/types-ts4.5/tools/get-icons/icon-structured-content.codegen.d.ts +0 -13
- package/dist/types-ts4.5/tools/get-icons/index.d.ts +0 -35
- package/dist/types-ts4.5/tools/get-tokens/index.d.ts +0 -35
- package/dist/types-ts4.5/tools/get-tokens/token-mcp-structured-content.codegen.d.ts +0 -13
- package/dist/types-ts4.5/tools/get-tokens/token-structured-content.codegen.d.ts +0 -13
|
@@ -0,0 +1,3984 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
|
|
3
|
+
Object.defineProperty(exports, "__esModule", {
|
|
4
|
+
value: true
|
|
5
|
+
});
|
|
6
|
+
exports.components = void 0;
|
|
7
|
+
/**
|
|
8
|
+
* THIS FILE WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
9
|
+
*
|
|
10
|
+
* Structured content components from design-system *.docs.tsx files
|
|
11
|
+
*
|
|
12
|
+
* @codegen <<SignedSource::e95f33d4763be141adff38f29074981c>>
|
|
13
|
+
* @codegenCommand yarn workspace @af/ads-ai-tooling codegen:structured-docs-components
|
|
14
|
+
*/
|
|
15
|
+
/* eslint-disable @repo/internal/react/boolean-prop-naming-convention -- not our types */
|
|
16
|
+
|
|
17
|
+
var components = exports.components = [{
|
|
18
|
+
name: 'Avatar',
|
|
19
|
+
package: '@atlaskit/avatar',
|
|
20
|
+
description: 'A component for displaying user avatars with support for images, initials, and status indicators.',
|
|
21
|
+
status: 'general-availability',
|
|
22
|
+
usageGuidelines: ['Use for user or entity (repo, space). Circle = person; hexagon = agent/AI; square = project/repo/space', 'Use presence for availability; status for approval/permission states', 'Use consistent sizing within the same context', 'Place avatars in logical groupings (e.g., team members)', 'Use presence indicators sparingly for real-time status only', 'Provide fallback initials when images fail to load', 'Always provide meaningful names for accessibility', 'Use the `name` prop to include alternative text for screen readers', 'For decorative images, remove the `name` prop or leave it empty so it will be ignored by assistive technologies', "Don't use a tooltip with an avatar when it's non-interactive or disabled. The tooltip won't work for keyboard users and screen readers"],
|
|
23
|
+
contentGuidelines: ['Use full names when possible for better recognition', 'For companies/projects, use descriptive names', "Avoid generic terms like 'User' or 'Admin'", 'Use consistent naming conventions across your app', 'Keep names concise but meaningful'],
|
|
24
|
+
keywords: ['avatar', 'user', 'profile', 'image', 'presence', 'status', 'representation'],
|
|
25
|
+
category: 'images',
|
|
26
|
+
examples: ['import Avatar from \'@atlaskit/avatar\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Avatar src="https://example.com/avatar.jpg" name="John Doe" />\n\t\t<Avatar name="Jane Smith" appearance="hexagon" size="large" status="locked" />\n\t\t<Avatar\n\t\t\tname="Bob Wilson"\n\t\t\tappearance="square"\n\t\t\tsize="small"\n\t\t\tpresence="online"\n\t\t\tstatus="approved"\n\t\t/>\n\t</>\n);\nexport default Examples;'],
|
|
27
|
+
props: [{
|
|
28
|
+
name: 'appearance',
|
|
29
|
+
type: '"circle" | "square" | "hexagon"',
|
|
30
|
+
description: "Indicates the shape of the avatar. Most avatars are circular, but square avatars\ncan be used for 'container' objects."
|
|
31
|
+
}, {
|
|
32
|
+
name: 'aria-controls',
|
|
33
|
+
type: 'string',
|
|
34
|
+
description: 'Identifies the popup element that the avatar controls.\nUsed when Avatar is a trigger for a popup.'
|
|
35
|
+
}, {
|
|
36
|
+
name: 'aria-expanded',
|
|
37
|
+
type: 'boolean',
|
|
38
|
+
description: 'Announces to assistive technology whether the controlled popup is currently open or closed.'
|
|
39
|
+
}, {
|
|
40
|
+
name: 'aria-haspopup',
|
|
41
|
+
type: 'boolean | "dialog"',
|
|
42
|
+
description: 'Informs assistive technology that this element triggers a popup.\nWhen set, Avatar will render as a `<button>` element even without `onClick`.'
|
|
43
|
+
}, {
|
|
44
|
+
name: 'as',
|
|
45
|
+
type: 'keyof global.JSX.IntrinsicElements | ComponentType<AllHTMLAttributes<HTMLElement>>',
|
|
46
|
+
description: 'Replace the wrapping element. This accepts the name of a html tag which will\nbe used to wrap the element.'
|
|
47
|
+
}, {
|
|
48
|
+
name: 'borderColor',
|
|
49
|
+
type: 'string',
|
|
50
|
+
description: 'Used to override the default border color around the avatar body.\nAccepts any color argument that the border-color CSS property accepts.'
|
|
51
|
+
}, {
|
|
52
|
+
name: 'children',
|
|
53
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
54
|
+
description: 'Supply a custom avatar component instead of the default.'
|
|
55
|
+
}, {
|
|
56
|
+
name: 'href',
|
|
57
|
+
type: 'string',
|
|
58
|
+
description: 'Provides a url for avatars being used as a link.'
|
|
59
|
+
}, {
|
|
60
|
+
name: 'imgLoading',
|
|
61
|
+
type: '"lazy" | "eager"',
|
|
62
|
+
description: 'Defines the loading behaviour of the avatar image. Default value is eager.'
|
|
63
|
+
}, {
|
|
64
|
+
name: 'isDecorative',
|
|
65
|
+
type: 'boolean',
|
|
66
|
+
description: 'whether disable aria-labelledby for avatar img'
|
|
67
|
+
}, {
|
|
68
|
+
name: 'isDisabled',
|
|
69
|
+
type: 'boolean',
|
|
70
|
+
description: 'Change the style to indicate the avatar is disabled.'
|
|
71
|
+
}, {
|
|
72
|
+
name: 'label',
|
|
73
|
+
type: 'string',
|
|
74
|
+
description: 'Used to provide custom content to screen readers.\nStatus or presence is not added to the label by default if it passed as nodes.\nIf status or presence is passed as a string, the default content format is "John Smith (online)".'
|
|
75
|
+
}, {
|
|
76
|
+
name: 'name',
|
|
77
|
+
type: 'string',
|
|
78
|
+
description: 'Provides alt text for the avatar image.'
|
|
79
|
+
}, {
|
|
80
|
+
name: 'onClick',
|
|
81
|
+
type: '(event: MouseEvent<Element, globalThis.MouseEvent>, analyticsEvent?: UIAnalyticsEvent) => void',
|
|
82
|
+
description: 'Handler to be called on click.'
|
|
83
|
+
}, {
|
|
84
|
+
name: 'presence',
|
|
85
|
+
type: 'Presence | Omit<ReactNode, string> | (string & {})',
|
|
86
|
+
description: "Indicates a user's online status by showing a small icon on the avatar.\nRefer to presence values on the presence component.\nAlternatively accepts any React element. For best results, it is recommended to\nuse square content with height and width of 100%."
|
|
87
|
+
}, {
|
|
88
|
+
name: 'size',
|
|
89
|
+
type: '"small" | "xsmall" | "medium" | "large" | "xlarge" | "xxlarge"',
|
|
90
|
+
description: "Defines the size of the avatar. Default value is `medium`.\n\nThis can also be controlled by the `size` property of the\n`AvatarContext` export from this package. If no prop is given when the\n`size` is set via this context, the context's value will be used."
|
|
91
|
+
}, {
|
|
92
|
+
name: 'src',
|
|
93
|
+
type: 'string',
|
|
94
|
+
description: 'A url to load an image from (this can also be a base64 encoded image).'
|
|
95
|
+
}, {
|
|
96
|
+
name: 'stackIndex',
|
|
97
|
+
type: 'number',
|
|
98
|
+
description: 'The index of where this avatar is in the group `stack`.'
|
|
99
|
+
}, {
|
|
100
|
+
name: 'status',
|
|
101
|
+
type: 'Omit<ReactNode, string> | (string & {}) | Status',
|
|
102
|
+
description: 'Indicates contextual information by showing a small icon on the avatar.\nRefer to status values on the Status component.'
|
|
103
|
+
}, {
|
|
104
|
+
name: 'tabIndex',
|
|
105
|
+
type: 'number',
|
|
106
|
+
description: 'Assign specific tabIndex order to the underlying node.'
|
|
107
|
+
}, {
|
|
108
|
+
name: 'target',
|
|
109
|
+
type: '"_blank" | "_self" | "_top" | "_parent"',
|
|
110
|
+
description: 'Pass target down to the anchor, if href is provided.'
|
|
111
|
+
}]
|
|
112
|
+
}, {
|
|
113
|
+
name: 'AvatarGroup',
|
|
114
|
+
package: '@atlaskit/avatar-group',
|
|
115
|
+
description: 'A component for displaying multiple avatars in a group with overlap and overflow handling.',
|
|
116
|
+
status: 'general-availability',
|
|
117
|
+
usageGuidelines: ['Use for displaying multiple users or team members', 'Consider overflow behavior for large groups', 'Use appropriate sizing for context', 'Provide clear user identification'],
|
|
118
|
+
contentGuidelines: ['Use meaningful names for users', 'Consider group context and purpose', 'Provide clear overflow indicators', 'Use consistent naming patterns'],
|
|
119
|
+
accessibilityGuidelines: ['Provide clear labels for avatar groups', 'Use appropriate overflow handling', 'Ensure keyboard navigation support', 'Provide clear user identification'],
|
|
120
|
+
keywords: ['avatar', 'group', 'multiple', 'users', 'team', 'overlap'],
|
|
121
|
+
category: 'data-display',
|
|
122
|
+
examples: ["import AvatarGroup from '@atlaskit/avatar-group';\nconst Example = (): React.JSX.Element => (\n\t<AvatarGroup\n\t\tappearance=\"stack\"\n\t\tsize=\"large\"\n\t\tonAvatarClick={console.log}\n\t\tdata={[\n\t\t\t{ key: 'uid1', name: 'Bob Smith' },\n\t\t\t{ key: 'uid2', name: 'Design System Team', appearance: 'square' },\n\t\t\t{ key: 'uid3', name: 'Review Agent', appearance: 'hexagon' },\n\t\t\t{ key: 'uid4', name: 'Carol Davis' },\n\t\t]}\n\t\tmaxCount={3}\n\t/>\n);\nexport default Example;"],
|
|
123
|
+
props: [{
|
|
124
|
+
name: 'appearance',
|
|
125
|
+
type: '"grid" | "stack"',
|
|
126
|
+
description: 'Indicates the layout of the avatar group.\nAvatars will either be overlapped in a stack, or\nlaid out in an even grid formation.\nDefaults to "stack".',
|
|
127
|
+
defaultValue: '"stack"'
|
|
128
|
+
}, {
|
|
129
|
+
name: 'avatar',
|
|
130
|
+
type: 'React.ForwardRefExoticComponent<AvatarPropTypes & React.RefAttributes<HTMLElement>> | React.ElementType<AvatarProps, keyof React.JSX.IntrinsicElements>',
|
|
131
|
+
description: 'Component used to render each avatar.',
|
|
132
|
+
defaultValue: 'Avatar'
|
|
133
|
+
}, {
|
|
134
|
+
name: 'borderColor',
|
|
135
|
+
type: 'string',
|
|
136
|
+
description: 'Typically the background color that the avatar is presented on.\nAccepts any color argument that the CSS border-color property accepts.'
|
|
137
|
+
}, {
|
|
138
|
+
name: 'boundariesElement',
|
|
139
|
+
type: '"viewport" | "window" | "scrollParent"',
|
|
140
|
+
description: 'Element the overflow popup should be attached to.\nDefaults to "viewport".'
|
|
141
|
+
}, {
|
|
142
|
+
name: 'data',
|
|
143
|
+
type: '(AvatarPropTypes & { name: string; key?: string | number; })[]',
|
|
144
|
+
description: "An array of avatar prop data, that are spread onto each `avatar` component.\n\nFor further usage information on AvatarPropTypes, the supported props for `avatar`, refer to [Avatar's prop documentation](https://atlassian.design/components/avatar/code).",
|
|
145
|
+
isRequired: true
|
|
146
|
+
}, {
|
|
147
|
+
name: 'isTooltipDisabled',
|
|
148
|
+
type: 'boolean',
|
|
149
|
+
description: 'Disables tooltips.'
|
|
150
|
+
}, {
|
|
151
|
+
name: 'label',
|
|
152
|
+
type: 'string',
|
|
153
|
+
description: 'Text to be used as aria-label for the list of avatars.\nScreen reader announcement with default label, which is `avatar group`, is `list, avatar group, X items`.\n\nThe label should describe the `AvatarGroup`\'s entities, for instance:\n- `label="team members"`, screen reader announcement would be `list team members, X items`\n- `label="reviewers"` screen reader announcement would be `list reviewers, X items`\n\nWhen there are several AvatarGroups on the page you should use a unique label to let users distinguish different lists.',
|
|
154
|
+
defaultValue: '"avatar group"'
|
|
155
|
+
}, {
|
|
156
|
+
name: 'maxCount',
|
|
157
|
+
type: 'number',
|
|
158
|
+
description: 'The maximum number of avatars allowed in the list.\nDefaults to 5 when displayed as a stack,\nand 11 when displayed as a grid.'
|
|
159
|
+
}, {
|
|
160
|
+
name: 'moreIndicatorLabel',
|
|
161
|
+
type: 'string',
|
|
162
|
+
description: 'Text to be used as aria-label for the more indicator.\nIf provided, this will be used exactly as-is for the aria-label.\nIf not provided, but an `aria-label` is provided via `showMoreButtonProps`, that will be used instead.\nIf neither is provided, the aria-label will default to "N more people" where N is the number of people that are not visible (e.g. "5 more people").'
|
|
163
|
+
}, {
|
|
164
|
+
name: 'onAvatarClick',
|
|
165
|
+
type: '(event: React.MouseEvent<Element, MouseEvent>, analyticsEvent: AnalyticsEvent, index: number) => void',
|
|
166
|
+
description: 'Handle the click event on the avatar item.\nNote that if an onClick prop is provided as part of avatar data, it will take precedence over onAvatarClick.'
|
|
167
|
+
}, {
|
|
168
|
+
name: 'onMoreClick',
|
|
169
|
+
type: '(event: React.MouseEvent<Element, MouseEvent>) => void',
|
|
170
|
+
description: 'Take control of the click event on the more indicator.\nThis will cancel the default dropdown behavior.'
|
|
171
|
+
}, {
|
|
172
|
+
name: 'overrides',
|
|
173
|
+
type: 'AvatarGroupOverrides',
|
|
174
|
+
description: 'Custom overrides for the composed components.'
|
|
175
|
+
}, {
|
|
176
|
+
name: 'shouldPopupRenderToParent',
|
|
177
|
+
type: 'boolean',
|
|
178
|
+
description: "Determines whether the 'show more' popup has `shouldRenderToParent` applied.",
|
|
179
|
+
defaultValue: 'false'
|
|
180
|
+
}, {
|
|
181
|
+
name: 'showMoreButtonProps',
|
|
182
|
+
type: '{ defaultChecked?: boolean; defaultValue?: string | number | readonly string[]; suppressContentEditableWarning?: boolean; suppressHydrationWarning?: boolean; accessKey?: string; autoCapitalize?: (string & {}) | ... 5 more ... | "characters"; ... 257 more ...; onTransitionEndCapture?: React.TransitionEventHandler<......',
|
|
183
|
+
description: 'Provide additional props to the MoreButton.\nExample use cases: altering tab order by providing tabIndex;\nadding onClick behaviour without losing the default dropdown',
|
|
184
|
+
defaultValue: '{}'
|
|
185
|
+
}, {
|
|
186
|
+
name: 'size',
|
|
187
|
+
type: '"small" | "medium" | "large" | "xlarge" | "xxlarge"',
|
|
188
|
+
description: 'Defines the size of the avatar.\nDefaults to "medium".\n\nNote: The "xsmall" size that exists on Avatar is not supported here because elements such as the more indicator cannot be displayed in an accessible manner at that size.',
|
|
189
|
+
defaultValue: '"medium"'
|
|
190
|
+
}, {
|
|
191
|
+
name: 'tooltipPosition',
|
|
192
|
+
type: '"top" | "bottom"',
|
|
193
|
+
description: 'Where the tooltip should appear relative to its target.\nDefaults to tooltip position "bottom".',
|
|
194
|
+
defaultValue: '"bottom"'
|
|
195
|
+
}]
|
|
196
|
+
}, {
|
|
197
|
+
name: 'Badge',
|
|
198
|
+
package: '@atlaskit/badge',
|
|
199
|
+
description: 'A badge is a visual indicator for numeric values such as tallies and scores, providing quick visual feedback.',
|
|
200
|
+
status: 'general-availability',
|
|
201
|
+
usageGuidelines: ['Use for displaying counts, scores, or status indicators for a single item or label', 'Use with one item/label only to avoid ambiguity', 'Keep badge content concise and meaningful', 'Use appropriate appearance variants for different contexts', 'Position badges near relevant content', 'Consider maximum value display limits', 'Use Lozenge for non-numeric status; use Tag for labels'],
|
|
202
|
+
contentGuidelines: ['Use clear, concise numeric or text values', 'Ensure values are meaningful to users', 'Use consistent formatting across similar badges', 'Consider localization for number formatting (locale-aware numbers)'],
|
|
203
|
+
accessibilityGuidelines: ['Ensure badge content is announced by screen readers', 'Do not rely on color alone for positive/negative meaning', 'Use appropriate color contrast for text readability', 'Provide meaningful context for numeric values', 'Consider alternative text for non-numeric badges'],
|
|
204
|
+
keywords: ['badge', 'indicator', 'numeric', 'tally', 'score', 'count', 'status'],
|
|
205
|
+
category: 'status-indicators',
|
|
206
|
+
examples: ['import Badge from \'@atlaskit/badge\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Badge appearance="primary">5</Badge>\n\t\t<Badge appearance="important" max={99}>\n\t\t\t150\n\t\t</Badge>\n\t</>\n);\nexport default Examples;'],
|
|
207
|
+
props: [{
|
|
208
|
+
name: 'appearance',
|
|
209
|
+
type: '"added" | "default" | "important" | "primary" | "primaryInverted" | "removed" | "warning" | "discovery" | "danger" | "neutral" | "success" | "information" | "inverse"',
|
|
210
|
+
description: 'Affects the visual style of the badge.'
|
|
211
|
+
}, {
|
|
212
|
+
name: 'children',
|
|
213
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
214
|
+
description: 'The value displayed within the badge. A `ReactNode` can be provided for\ncustom-formatted numbers, however, badge should only be used in cases where you want to represent\na number.\nUse a [lozenge](/packages/design-system/lozenge) for non-numeric information.'
|
|
215
|
+
}, {
|
|
216
|
+
name: 'max',
|
|
217
|
+
type: 'number | false',
|
|
218
|
+
description: 'The maximum value to display. Defaults to `99`. If the value is 100, and max is 50, "50+" will be displayed.\nThis value should be greater than 0. If set to `false` the original value will be displayed regardless of\nwhether it is larger than the default maximum value.'
|
|
219
|
+
}]
|
|
220
|
+
}, {
|
|
221
|
+
name: 'Banner',
|
|
222
|
+
package: '@atlaskit/banner',
|
|
223
|
+
description: 'A banner displays a prominent message at the top of the screen to communicate important information to users.',
|
|
224
|
+
status: 'general-availability',
|
|
225
|
+
usageGuidelines: ['Use only for critical messaging: loss of data/functionality or important site-wide information', 'Show one banner at a time and push content down', 'Place at the top of the screen for maximum visibility', 'Keep messaging concise and actionable', 'Consider dismissibility for non-critical messages', 'Use Flag for confirmations or minimal interaction; use Inline message when action is required'],
|
|
226
|
+
contentGuidelines: ['Use "we" not "you" in error messages', 'Write clear, concise, scannable messages', 'Include follow-up actions where relevant', 'Use action-oriented language when appropriate', 'Ensure messages are relevant to the current context'],
|
|
227
|
+
accessibilityGuidelines: ['Do not rely on color alone for severity; provide accessible label for warning/error icons', 'Alert role is a live region and very noisy—use only when the message is very important', 'Keep content concise to avoid truncation (truncation is not accessible)', 'Use appropriate color contrast for text readability', 'Provide clear, actionable messaging', 'Consider keyboard navigation for interactive banners'],
|
|
228
|
+
keywords: ['banner', 'message', 'notification', 'alert', 'prominent', 'top', 'screen'],
|
|
229
|
+
category: 'messaging',
|
|
230
|
+
examples: ['import Banner from \'@atlaskit/banner\';\nimport WarningIcon from \'@atlaskit/icon/core/status-warning\';\nimport Box from \'@atlaskit/primitives/box\';\nexport default (): React.JSX.Element => (\n\t<Box>\n\t\t<Banner icon={<WarningIcon label="Warning" spacing="spacious" />} testId="basicTestId">\n\t\t\tYour license is about to expire. Please renew your license within the next week.\n\t\t</Banner>\n\t</Box>\n);'],
|
|
231
|
+
props: [{
|
|
232
|
+
name: 'appearance',
|
|
233
|
+
type: '"warning" | "error" | "announcement"',
|
|
234
|
+
description: 'Visual style to be used for the banner'
|
|
235
|
+
}, {
|
|
236
|
+
name: 'children',
|
|
237
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
238
|
+
description: 'Content to be shown next to the icon. Typically text content but can contain links.'
|
|
239
|
+
}, {
|
|
240
|
+
name: 'icon',
|
|
241
|
+
type: 'ReactElement<any, string | JSXElementConstructor<any>>',
|
|
242
|
+
description: 'Icon to be shown left of the main content. Typically an Atlaskit [@atlaskit/icon](packages/design-system/icon)'
|
|
243
|
+
}]
|
|
244
|
+
}, {
|
|
245
|
+
name: 'Blanket',
|
|
246
|
+
package: '@atlaskit/blanket',
|
|
247
|
+
description: 'A component for creating overlay backgrounds behind modals and other layered content.',
|
|
248
|
+
status: 'general-availability',
|
|
249
|
+
usageGuidelines: ['Use behind modals and overlays', 'Consider click-to-dismiss behavior', 'Use appropriate tinting for context', 'Ensure proper z-index layering'],
|
|
250
|
+
contentGuidelines: ['Use consistently across similar overlay contexts', 'Consider visual hierarchy with overlays', 'Ensure appropriate contrast with content'],
|
|
251
|
+
accessibilityGuidelines: ["Ensure blanket doesn't interfere with focus management", 'Provide appropriate click handling for dismissal', 'Consider screen reader experience with overlays'],
|
|
252
|
+
keywords: ['blanket', 'overlay', 'backdrop', 'modal', 'layer'],
|
|
253
|
+
category: 'overlay',
|
|
254
|
+
examples: ["import Blanket from '@atlaskit/blanket';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Blanket />\n\t\t<Blanket isTinted onBlanketClicked={() => console.log('Blanket clicked')} />\n\t</>\n);\nexport default Examples;"],
|
|
255
|
+
props: [{
|
|
256
|
+
name: 'children',
|
|
257
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
258
|
+
description: 'The children to be rendered within the blanket.'
|
|
259
|
+
}, {
|
|
260
|
+
name: 'isTinted',
|
|
261
|
+
type: 'boolean',
|
|
262
|
+
description: 'Sets whether the blanket has a tinted background color.'
|
|
263
|
+
}, {
|
|
264
|
+
name: 'onBlanketClicked',
|
|
265
|
+
type: '(event: MouseEvent<HTMLDivElement, globalThis.MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
266
|
+
description: 'Handler function to be called when the blanket is clicked.'
|
|
267
|
+
}, {
|
|
268
|
+
name: 'shouldAllowClickThrough',
|
|
269
|
+
type: 'boolean',
|
|
270
|
+
description: 'Whether mouse events can pass through the blanket. If `true`, `onBlanketClicked` will not be called.'
|
|
271
|
+
}]
|
|
272
|
+
}, {
|
|
273
|
+
name: 'Breadcrumbs',
|
|
274
|
+
package: '@atlaskit/breadcrumbs',
|
|
275
|
+
description: 'A navigation component showing the current page hierarchy.',
|
|
276
|
+
status: 'general-availability',
|
|
277
|
+
usageGuidelines: ['Use for orientation; supplement main nav, do not replace it', 'Hierarchy from top to current; each item is a link', 'Place top left, above page title; use when user lands from external or on large/hierarchical sites', 'Do not overwhelm; in-app avoid topmost level unless sidebar is collapsed'],
|
|
278
|
+
contentGuidelines: ['Use page or section titles for items', 'Keep labels concise but meaningful', 'Use consistent naming conventions'],
|
|
279
|
+
accessibilityGuidelines: ['Ensure separator contrast; separators are not announced to screen readers', 'Collapsed state = single item (e.g. "Show more breadcrumbs")', 'Use isNavigation={false} when breadcrumbs are not main nav (e.g. search results) to reduce assistive tech noise', 'Provide clear navigation labels', 'Use appropriate ARIA landmarks', 'Ensure keyboard navigation support', 'Provide clear path context'],
|
|
280
|
+
keywords: ['breadcrumbs', 'navigation', 'hierarchy', 'path', 'location'],
|
|
281
|
+
category: 'navigation',
|
|
282
|
+
examples: ['import Breadcrumbs, { BreadcrumbsItem } from \'@atlaskit/breadcrumbs\';\nconst Example = (): React.JSX.Element => (\n\t<Breadcrumbs maxItems={3}>\n\t\t<BreadcrumbsItem href="/" text="Home" />\n\t\t<BreadcrumbsItem href="/category" text="Category" />\n\t\t<BreadcrumbsItem href="/category/products" text="Products" />\n\t\t<BreadcrumbsItem text="Current Page" />\n\t</Breadcrumbs>\n);\nexport default Example;'],
|
|
283
|
+
props: [{
|
|
284
|
+
name: 'children',
|
|
285
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
286
|
+
description: 'The items to be included inside the Breadcrumbs wrapper.'
|
|
287
|
+
}, {
|
|
288
|
+
name: 'defaultExpanded',
|
|
289
|
+
type: 'boolean'
|
|
290
|
+
}, {
|
|
291
|
+
name: 'ellipsisLabel',
|
|
292
|
+
type: 'string',
|
|
293
|
+
description: 'Text to be used as an accessible label for the ellipsis button.'
|
|
294
|
+
}, {
|
|
295
|
+
name: 'isExpanded',
|
|
296
|
+
type: 'boolean',
|
|
297
|
+
description: 'Override collapsing of the nav when there are more than the maximum number of items.'
|
|
298
|
+
}, {
|
|
299
|
+
name: 'itemsAfterCollapse',
|
|
300
|
+
type: 'number',
|
|
301
|
+
description: 'If max items is exceeded, the number of items to show after the ellipsis.'
|
|
302
|
+
}, {
|
|
303
|
+
name: 'itemsBeforeCollapse',
|
|
304
|
+
type: 'number',
|
|
305
|
+
description: 'If max items is exceeded, the number of items to show before the ellipsis.'
|
|
306
|
+
}, {
|
|
307
|
+
name: 'label',
|
|
308
|
+
type: 'string',
|
|
309
|
+
description: 'Text to be used as label of navigation region that wraps the breadcrumbs.'
|
|
310
|
+
}, {
|
|
311
|
+
name: 'maxItems',
|
|
312
|
+
type: 'number',
|
|
313
|
+
description: 'Set the maximum number of breadcrumbs to display. When there are more\nthan the maximum number, only the first and last will be shown, with an\nellipsis in between.'
|
|
314
|
+
}, {
|
|
315
|
+
name: 'onExpand',
|
|
316
|
+
type: '(event: MouseEvent<Element, globalThis.MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
317
|
+
description: 'A function to be called when you are in the collapsed view and click the ellipsis.'
|
|
318
|
+
}]
|
|
319
|
+
}, {
|
|
320
|
+
name: 'ButtonGroup',
|
|
321
|
+
package: '@atlaskit/button',
|
|
322
|
+
description: 'A component for grouping related buttons together with consistent spacing and alignment.',
|
|
323
|
+
status: 'general-availability',
|
|
324
|
+
usageGuidelines: ['Use for related actions that belong together', 'Group buttons that perform similar or complementary actions', 'Maintain consistent spacing and alignment', 'Consider the visual hierarchy within the group', "Don't group unrelated actions together", 'Use when you have multiple related actions that should be visually grouped', 'Provides consistent spacing and alignment between buttons'],
|
|
325
|
+
contentGuidelines: ['Ensure button labels are consistent in tone and style', 'Use parallel structure for related actions', 'Keep labels concise but descriptive', 'Consider the order of actions within the group'],
|
|
326
|
+
keywords: ['button', 'group', 'container', 'layout', 'spacing'],
|
|
327
|
+
category: 'form',
|
|
328
|
+
examples: ['import { ButtonGroup } from \'@atlaskit/button\';\nimport Button from \'@atlaskit/button/new\';\nconst _default_1: React.JSX.Element[] = [\n\t<ButtonGroup titleId="heading-options">\n\t\t<Button appearance="primary">Save</Button>\n\t\t<Button appearance="danger">Delete</Button>\n\t\t<Button appearance="subtle">Cancel</Button>\n\t</ButtonGroup>,\n];\nexport default _default_1;'],
|
|
329
|
+
props: [{
|
|
330
|
+
name: 'children',
|
|
331
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
332
|
+
description: 'The buttons to render inside the button group.'
|
|
333
|
+
}, {
|
|
334
|
+
name: 'label',
|
|
335
|
+
type: 'string',
|
|
336
|
+
description: 'Refers to an `aria-label` attribute. Sets an accessible name for the button group wrapper to announce it to users of assistive technology.\nUsage of either this, or the `titleId` attribute is strongly recommended.'
|
|
337
|
+
}, {
|
|
338
|
+
name: 'titleId',
|
|
339
|
+
type: 'string',
|
|
340
|
+
description: "ID referenced by the button group wrapper's `aria-labelledby` attribute. This ID should be assigned to the group-button title element.\nUsage of either this, or the `label` attribute is strongly recommended."
|
|
341
|
+
}]
|
|
342
|
+
}, {
|
|
343
|
+
name: 'Button',
|
|
344
|
+
package: '@atlaskit/button',
|
|
345
|
+
description: 'A versatile button component with multiple appearances and states for triggering actions. A button triggers an event or action. They let users know what will happen next. Note the root entrypoint of `@atlaskit/button` is deprecated and being replaced with `@atlaskit/button/new`.',
|
|
346
|
+
status: 'general-availability',
|
|
347
|
+
usageGuidelines: ['Use primary buttons for the main action on a page', 'Limit to one primary button per section', 'Use compact size for tight spaces', 'Use subtle buttons for secondary actions', 'Use danger buttons sparingly for destructive actions', 'Group related buttons together with ButtonGroup', 'Use buttons for actions; use links for navigation (different semantics and assistive tech behavior)'],
|
|
348
|
+
contentGuidelines: ['Use action verbs that describe the interaction', 'Keep text concise (1-3 words ideal)', 'Avoid generic terms like "Submit" or "Click here"', 'Use sentence case', 'Keep button labels consistent with surrounding UI (e.g. modal primary button should reflect modal intent)', 'Use buttons for actions, links for navigation', 'Only include one primary call to action (CTA) per area', "Start with the verb and specify what's being acted on", "Don't use punctuation in button labels"],
|
|
349
|
+
accessibilityGuidelines: ['Always provide meaningful labels for screen readers', 'Provide loading state announcements for async actions'],
|
|
350
|
+
keywords: ['button', 'action', 'click', 'submit', 'form', 'interactive', 'cta'],
|
|
351
|
+
category: 'form',
|
|
352
|
+
examples: ['import Button from \'@atlaskit/button/new\';\nexport default function ButtonDisabledExample(): React.JSX.Element {\n\treturn (\n\t\t<Button appearance="primary" isDisabled>\n\t\t\tDisabled button\n\t\t</Button>\n\t);\n}', 'import Button from \'@atlaskit/button/new\';\nexport default function ButtonDangerExample(): React.JSX.Element {\n\treturn <Button appearance="danger">Danger button</Button>;\n}', "import Button from '@atlaskit/button/new';\nimport StarIcon from '@atlaskit/icon/core/star-starred';\nexport default function ButtonIconAfterExample(): React.JSX.Element {\n\treturn (\n\t\t<Button iconAfter={StarIcon} appearance=\"primary\">\n\t\t\tIcon after\n\t\t</Button>\n\t);\n}"],
|
|
353
|
+
props: [{
|
|
354
|
+
name: 'appearance',
|
|
355
|
+
type: '"default" | "danger" | "primary" | "subtle" | "warning" | "discovery"',
|
|
356
|
+
description: 'The button style variation.'
|
|
357
|
+
}, {
|
|
358
|
+
name: 'autoFocus',
|
|
359
|
+
type: 'boolean',
|
|
360
|
+
description: 'Set the button to autofocus on mount.'
|
|
361
|
+
}, {
|
|
362
|
+
name: 'children',
|
|
363
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
364
|
+
description: 'Text content to be rendered in the button.',
|
|
365
|
+
isRequired: true
|
|
366
|
+
}, {
|
|
367
|
+
name: 'iconAfter',
|
|
368
|
+
type: 'ComponentClass<Omit<IconProps, "size"> | Omit<NewIconProps, "spacing" | "size">, any> | FunctionComponent<Omit<IconProps, "size"> | Omit<...>>',
|
|
369
|
+
description: "Places an icon within the button, after the button's text."
|
|
370
|
+
}, {
|
|
371
|
+
name: 'iconBefore',
|
|
372
|
+
type: 'ComponentClass<Omit<IconProps, "size"> | Omit<NewIconProps, "spacing" | "size">, any> | FunctionComponent<Omit<IconProps, "size"> | Omit<...>>',
|
|
373
|
+
description: "Places an icon within the button, before the button's text."
|
|
374
|
+
}, {
|
|
375
|
+
name: 'isDisabled',
|
|
376
|
+
type: 'boolean',
|
|
377
|
+
description: 'Disable the button to prevent user interaction.'
|
|
378
|
+
}, {
|
|
379
|
+
name: 'isLoading',
|
|
380
|
+
type: 'boolean',
|
|
381
|
+
description: 'Conditionally show a spinner over the top of a button'
|
|
382
|
+
}, {
|
|
383
|
+
name: 'isSelected',
|
|
384
|
+
type: 'boolean',
|
|
385
|
+
description: 'Indicates that the button is selected.'
|
|
386
|
+
}, {
|
|
387
|
+
name: 'onBlur',
|
|
388
|
+
type: '(event: FocusEvent<HTMLButtonElement, Element>) => void',
|
|
389
|
+
description: 'Handler called on blur.'
|
|
390
|
+
}, {
|
|
391
|
+
name: 'onClick',
|
|
392
|
+
type: '(e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
393
|
+
description: 'Handler called on click. You can use the second argument to fire Atlaskit analytics events on custom channels. They could then be routed to GASv3 analytics. See the pressable or anchor primitive code examples for information on [firing Atlaskit analytics events](https://atlassian.design/components/primitives/pressable/examples#atlaskit-analytics) or [routing these to GASv3 analytics](https://atlassian.design/components/primitives/pressable/examples#gasv3-analytics).'
|
|
394
|
+
}, {
|
|
395
|
+
name: 'onFocus',
|
|
396
|
+
type: '(event: FocusEvent<HTMLButtonElement, Element>) => void',
|
|
397
|
+
description: 'Handler called on focus.'
|
|
398
|
+
}, {
|
|
399
|
+
name: 'shouldFitContainer',
|
|
400
|
+
type: 'boolean',
|
|
401
|
+
description: 'Option to fit button width to its parent width.'
|
|
402
|
+
}, {
|
|
403
|
+
name: 'spacing',
|
|
404
|
+
type: '"compact" | "default"',
|
|
405
|
+
description: 'Controls the amount of padding in the button.'
|
|
406
|
+
}]
|
|
407
|
+
}, {
|
|
408
|
+
name: 'IconButton',
|
|
409
|
+
package: '@atlaskit/button',
|
|
410
|
+
description: 'A button that displays only an icon with an optional tooltip. Perfect for toolbar actions, compact interfaces, and when space is limited.',
|
|
411
|
+
status: 'general-availability',
|
|
412
|
+
usageGuidelines: ['Use for toolbar actions and compact interfaces', 'Choose icons that clearly represent their function', 'Group related icon buttons together', 'Use sparingly to avoid visual clutter', 'Consider using tooltips for additional context', 'Always provide a meaningful label for accessibility', 'The icon should clearly represent the action it performs'],
|
|
413
|
+
contentGuidelines: ['Use clear, concise, descriptive labels', 'Use action verbs (e.g., "Edit item", "Delete comment")', 'Choose icons that are universally understood', 'Avoid using icons without labels in critical actions'],
|
|
414
|
+
keywords: ['button', 'icon', 'action', 'click', 'interactive', 'toolbar'],
|
|
415
|
+
category: 'form',
|
|
416
|
+
examples: ['import { IconButton } from \'@atlaskit/button/new\';\nimport AddIcon from \'@atlaskit/icon/core/add\';\nimport DeleteIcon from \'@atlaskit/icon/core/delete\';\nimport InfoIcon from \'@atlaskit/icon/core/status-information\';\nconst _default_1: React.JSX.Element[] = [\n\t<IconButton icon={AddIcon} label="Add new item" appearance="primary" />,\n\t<IconButton icon={InfoIcon} label="Show information" appearance="subtle" spacing="compact" />,\n\t<IconButton icon={DeleteIcon} label="Delete permanently" appearance="discovery" shape="circle" />,\n];\nexport default _default_1;'],
|
|
417
|
+
props: [{
|
|
418
|
+
name: 'appearance',
|
|
419
|
+
type: '"default" | "primary" | "discovery" | "subtle"',
|
|
420
|
+
description: 'The button style variation.\nThe button style variation.'
|
|
421
|
+
}, {
|
|
422
|
+
name: 'autoFocus',
|
|
423
|
+
type: 'boolean',
|
|
424
|
+
description: 'Set the button to autofocus on mount.'
|
|
425
|
+
}, {
|
|
426
|
+
name: 'icon',
|
|
427
|
+
type: 'ComponentClass<Omit<IconProps, "size"> | Omit<NewIconProps, "spacing" | "size">, any> | FunctionComponent<Omit<IconProps, "size"> | Omit<...>>',
|
|
428
|
+
description: 'Places an icon within the button.',
|
|
429
|
+
isRequired: true
|
|
430
|
+
}, {
|
|
431
|
+
name: 'isDisabled',
|
|
432
|
+
type: 'boolean',
|
|
433
|
+
description: 'Disable the button to prevent user interaction.'
|
|
434
|
+
}, {
|
|
435
|
+
name: 'isLoading',
|
|
436
|
+
type: 'boolean',
|
|
437
|
+
description: 'Conditionally show a spinner over the top of a button'
|
|
438
|
+
}, {
|
|
439
|
+
name: 'isSelected',
|
|
440
|
+
type: 'boolean',
|
|
441
|
+
description: 'Indicates that the button is selected.'
|
|
442
|
+
}, {
|
|
443
|
+
name: 'isTooltipDisabled',
|
|
444
|
+
type: 'boolean',
|
|
445
|
+
description: 'Prevents a tooltip with the label text from showing. Use sparingly, as most icon-only buttons benefit from a tooltip or some other text clarifying the action.'
|
|
446
|
+
}, {
|
|
447
|
+
name: 'label',
|
|
448
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
449
|
+
description: 'Provide an accessible label, often used by screen readers.',
|
|
450
|
+
isRequired: true
|
|
451
|
+
}, {
|
|
452
|
+
name: 'onBlur',
|
|
453
|
+
type: '(event: FocusEvent<HTMLButtonElement, Element>) => void',
|
|
454
|
+
description: 'Handler called on blur.'
|
|
455
|
+
}, {
|
|
456
|
+
name: 'onClick',
|
|
457
|
+
type: '(e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
458
|
+
description: 'Handler called on click. You can use the second argument to fire Atlaskit analytics events on custom channels. They could then be routed to GASv3 analytics. See the pressable or anchor primitive code examples for information on [firing Atlaskit analytics events](https://atlassian.design/components/primitives/pressable/examples#atlaskit-analytics) or [routing these to GASv3 analytics](https://atlassian.design/components/primitives/pressable/examples#gasv3-analytics).'
|
|
459
|
+
}, {
|
|
460
|
+
name: 'onFocus',
|
|
461
|
+
type: '(event: FocusEvent<HTMLButtonElement, Element>) => void',
|
|
462
|
+
description: 'Handler called on focus.'
|
|
463
|
+
}, {
|
|
464
|
+
name: 'shape',
|
|
465
|
+
type: '"default" | "circle"',
|
|
466
|
+
description: 'Set the shape of the icon, defaults to square with rounded corners.'
|
|
467
|
+
}, {
|
|
468
|
+
name: 'spacing',
|
|
469
|
+
type: '"default" | "compact"',
|
|
470
|
+
description: 'Controls the amount of padding in the button.'
|
|
471
|
+
}, {
|
|
472
|
+
name: 'tooltip',
|
|
473
|
+
type: '{ testId?: string; analyticsContext?: Record<string, any>; content?: ReactNode | (({ update }: { update?: () => void; }) => ReactNode); component?: ComponentType<TooltipPrimitiveProps> | ForwardRefExoticComponent<...>; ... 15 more ...; UNSAFE_shouldRenderToParent?: boolean; }',
|
|
474
|
+
description: 'Props passed down to the Tooltip component.'
|
|
475
|
+
}]
|
|
476
|
+
}, {
|
|
477
|
+
name: 'Calendar',
|
|
478
|
+
package: '@atlaskit/calendar',
|
|
479
|
+
description: "A calendar component for date selection and display. This component is in Beta phase, meaning it's stable at version 1.0+ but may receive improvements based on customer feedback.",
|
|
480
|
+
status: 'general-availability',
|
|
481
|
+
usageGuidelines: ['Use for date selection interfaces', 'Consider date range limitations', 'Provide clear visual feedback for selected dates', 'Handle disabled dates appropriately'],
|
|
482
|
+
contentGuidelines: ['Use clear date formatting', 'Provide helpful date labels', 'Use consistent date terminology', 'Consider localization for date display (e.g. locale prop, month/day names, first day of week)'],
|
|
483
|
+
accessibilityGuidelines: ['Provide clear date selection feedback', 'Ensure keyboard navigation between dates', 'Use appropriate ARIA labels for dates', 'Support screen reader announcements for date changes'],
|
|
484
|
+
keywords: ['calendar', 'date', 'picker', 'selection', 'month', 'year', 'beta'],
|
|
485
|
+
category: 'form',
|
|
486
|
+
examples: ["import Calendar from '@atlaskit/calendar';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Calendar\n\t\t\tselected={['2024-03-15']}\n\t\t\tonChange={(dates) => console.log('Selected dates:', dates)}\n\t\t/>\n\t\t<Calendar\n\t\t\tselected={['2024-03-20', '2024-03-21', '2024-03-22']}\n\t\t\tonChange={(dates) => console.log('Multiple dates:', dates)}\n\t\t\tdefaultMonth={3}\n\t\t\tdefaultYear={2024}\n\t\t/>\n\t\t<Calendar\n\t\t\tselected={[]}\n\t\t\tdisabled={['2024-03-10', '2024-03-11']}\n\t\t\tminDate=\"2024-03-01\"\n\t\t\tmaxDate=\"2024-03-31\"\n\t\t\tonChange={(dates) => console.log('Constrained dates:', dates)}\n\t\t/>\n\t</>\n);\nexport default Examples;"],
|
|
487
|
+
props: [{
|
|
488
|
+
name: 'day',
|
|
489
|
+
type: 'number',
|
|
490
|
+
description: 'The number of the day currently focused. Places border around the date. Enter `0` to highlight no date.'
|
|
491
|
+
}, {
|
|
492
|
+
name: 'defaultDay',
|
|
493
|
+
type: 'number',
|
|
494
|
+
description: 'Sets the default value for `day`.'
|
|
495
|
+
}, {
|
|
496
|
+
name: 'defaultMonth',
|
|
497
|
+
type: 'number',
|
|
498
|
+
description: 'Sets the default value for `month`.'
|
|
499
|
+
}, {
|
|
500
|
+
name: 'defaultPreviouslySelected',
|
|
501
|
+
type: 'string[]',
|
|
502
|
+
description: 'Sets the default value for `previouslySelected`.'
|
|
503
|
+
}, {
|
|
504
|
+
name: 'defaultSelected',
|
|
505
|
+
type: 'string[]',
|
|
506
|
+
description: 'Sets the default value for `selected`.'
|
|
507
|
+
}, {
|
|
508
|
+
name: 'defaultYear',
|
|
509
|
+
type: 'number',
|
|
510
|
+
description: 'Sets the default value for `year`.'
|
|
511
|
+
}, {
|
|
512
|
+
name: 'disabled',
|
|
513
|
+
type: 'string[]',
|
|
514
|
+
description: "Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates provided are greyed out and not selectable."
|
|
515
|
+
}, {
|
|
516
|
+
name: 'disabledDateFilter',
|
|
517
|
+
type: '(date: string) => boolean',
|
|
518
|
+
description: "A filter function that takes a date string in the format 'YYYY-MM-DD' and returns true if that date should be disabled."
|
|
519
|
+
}, {
|
|
520
|
+
name: 'locale',
|
|
521
|
+
type: 'string',
|
|
522
|
+
description: 'BCP 47 language tag (e.g. `ja-JP`) that ensures dates are in the official format for the locale.'
|
|
523
|
+
}, {
|
|
524
|
+
name: 'maxDate',
|
|
525
|
+
type: 'string',
|
|
526
|
+
description: 'The latest enabled date. All dates in the future after this date will be disabled.'
|
|
527
|
+
}, {
|
|
528
|
+
name: 'minDate',
|
|
529
|
+
type: 'string',
|
|
530
|
+
description: 'The earliest enabled date. All dates in the past before this date will be disabled.'
|
|
531
|
+
}, {
|
|
532
|
+
name: 'month',
|
|
533
|
+
type: 'number',
|
|
534
|
+
description: 'The number of the month (from 1 to 12) which the calendar should be on.'
|
|
535
|
+
}, {
|
|
536
|
+
name: 'nextMonthLabel',
|
|
537
|
+
type: 'string',
|
|
538
|
+
description: 'The aria-label attribute associated with the next month arrow, to describe it to assistive technology.'
|
|
539
|
+
}, {
|
|
540
|
+
name: 'onBlur',
|
|
541
|
+
type: '(event: FocusEvent<Element, Element>) => void',
|
|
542
|
+
description: 'Function which is called when the calendar is no longer focused.'
|
|
543
|
+
}, {
|
|
544
|
+
name: 'onChange',
|
|
545
|
+
type: '(event: ChangeEvent, analyticsEvent: UIAnalyticsEvent) => void',
|
|
546
|
+
description: "Called when the calendar is navigated. This can be triggered by the keyboard, or by clicking the navigational buttons.\nThe 'interface' property indicates the the direction the calendar was navigated whereas the 'iso' property is a string of the format YYYY-MM-DD."
|
|
547
|
+
}, {
|
|
548
|
+
name: 'onFocus',
|
|
549
|
+
type: '(event: FocusEvent<Element, Element>) => void',
|
|
550
|
+
description: 'Called when the calendar receives focus. This could be called from a mouse event on the container, or by tabbing into it.'
|
|
551
|
+
}, {
|
|
552
|
+
name: 'onSelect',
|
|
553
|
+
type: '(event: SelectEvent, analyticsEvent: UIAnalyticsEvent) => void',
|
|
554
|
+
description: "Function called when a day is clicked on. Calls with an object that has\na day, month and year property as numbers, representing the date just clicked.\nIt also has an 'iso' property, which is a string of the selected date in the\nformat YYYY-MM-DD."
|
|
555
|
+
}, {
|
|
556
|
+
name: 'previouslySelected',
|
|
557
|
+
type: 'string[]',
|
|
558
|
+
description: "Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates\nprovided are given a background color."
|
|
559
|
+
}, {
|
|
560
|
+
name: 'previousMonthLabel',
|
|
561
|
+
type: 'string',
|
|
562
|
+
description: 'The aria-label attribute associated with the previous month arrow, to describe it to assistive technology.'
|
|
563
|
+
}, {
|
|
564
|
+
name: 'selected',
|
|
565
|
+
type: 'string[]',
|
|
566
|
+
description: "Takes an array of dates as string in the format 'YYYY-MM-DD'. All dates\nprovided are given a background color."
|
|
567
|
+
}, {
|
|
568
|
+
name: 'shouldSetFocusOnCurrentDay',
|
|
569
|
+
type: 'boolean',
|
|
570
|
+
description: 'This allows the calendar to automatically set the focus to the current day.\nThe default is false.'
|
|
571
|
+
}, {
|
|
572
|
+
name: 'tabIndex',
|
|
573
|
+
type: '0 | -1',
|
|
574
|
+
description: 'Indicates if the calendar can be focused by keyboard or only\nprogrammatically. Defaults to "0".'
|
|
575
|
+
}, {
|
|
576
|
+
name: 'today',
|
|
577
|
+
type: 'string',
|
|
578
|
+
description: "Value of current day, as a string in the format 'YYYY-MM-DD'."
|
|
579
|
+
}, {
|
|
580
|
+
name: 'weekStartDay',
|
|
581
|
+
type: '0 | 1 | 2 | 3 | 4 | 5 | 6',
|
|
582
|
+
description: 'Start day of the week for the calendar. The mapping between numbers and days of the week is as follows:\n- `0` Sunday (default value)\n- `1` Monday\n- `2` Tuesday\n- `3` Wednesday\n- `4` Thursday\n- `5` Friday\n- `6` Saturday'
|
|
583
|
+
}, {
|
|
584
|
+
name: 'year',
|
|
585
|
+
type: 'number',
|
|
586
|
+
description: 'Year to display the calendar for.'
|
|
587
|
+
}]
|
|
588
|
+
}, {
|
|
589
|
+
name: 'Checkbox',
|
|
590
|
+
package: '@atlaskit/checkbox',
|
|
591
|
+
description: 'A checkbox is an input control that allows a user to select one or more options from a number of choices.',
|
|
592
|
+
status: 'general-availability',
|
|
593
|
+
usageGuidelines: ['Use for multiple choice selections from a list, or for explicit confirmation (e.g. settings)', 'Use indeterminate state when some but not all children in a group are selected', 'Group related checkboxes logically', 'Provide clear labels for each option', 'Consider default states carefully', 'Use Radio for single selection; Dropdown for compact single choice; Toggle for on/off'],
|
|
594
|
+
contentGuidelines: ['Write short, descriptive labels; no punctuation after labels', 'Use consistent language across related options', 'Avoid negative phrasing when possible', 'Group related options together'],
|
|
595
|
+
accessibilityGuidelines: ['Include error messages for required or invalid checkbox state', 'Do not use disabled if the control must stay in tab order; use validation and error message so screen reader users hear why and how to proceed', 'Ensure proper labeling for all checkboxes', 'Use clear, descriptive labels that explain the choice', 'Provide keyboard navigation support', 'Indicate required fields clearly', 'Use appropriate error states and messaging'],
|
|
596
|
+
keywords: ['checkbox', 'input', 'form', 'selection', 'choice', 'option', 'multiple'],
|
|
597
|
+
category: 'forms-and-input',
|
|
598
|
+
examples: ['import Checkbox from \'@atlaskit/checkbox\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Checkbox label="Basic checkbox" />\n\t\t<Checkbox label="Checked checkbox" isChecked />\n\t</>\n);\nexport default Examples;'],
|
|
599
|
+
props: [{
|
|
600
|
+
name: 'defaultChecked',
|
|
601
|
+
type: 'boolean',
|
|
602
|
+
description: 'Sets whether the checkbox begins as checked or unchecked.'
|
|
603
|
+
}, {
|
|
604
|
+
name: 'id',
|
|
605
|
+
type: 'string',
|
|
606
|
+
description: 'The ID assigned to the input.'
|
|
607
|
+
}, {
|
|
608
|
+
name: 'isChecked',
|
|
609
|
+
type: 'boolean',
|
|
610
|
+
description: 'Sets whether the checkbox is checked or unchecked.'
|
|
611
|
+
}, {
|
|
612
|
+
name: 'isDisabled',
|
|
613
|
+
type: 'boolean',
|
|
614
|
+
description: 'Sets whether the checkbox is disabled. Don’t use a disabled checkbox if it needs to remain in the tab order for assistive technologies.'
|
|
615
|
+
}, {
|
|
616
|
+
name: 'isIndeterminate',
|
|
617
|
+
type: 'boolean',
|
|
618
|
+
description: 'Sets whether the checkbox is indeterminate. This only affects the\nstyle and does not modify the isChecked property.'
|
|
619
|
+
}, {
|
|
620
|
+
name: 'isInvalid',
|
|
621
|
+
type: 'boolean',
|
|
622
|
+
description: 'Marks the field as invalid. Changes style of unchecked component.'
|
|
623
|
+
}, {
|
|
624
|
+
name: 'isRequired',
|
|
625
|
+
type: 'boolean',
|
|
626
|
+
description: 'Marks the field as required & changes the label style.'
|
|
627
|
+
}, {
|
|
628
|
+
name: 'label',
|
|
629
|
+
type: 'string | number | ReactElement<any, string | JSXElementConstructor<any>>',
|
|
630
|
+
description: 'The label to be displayed to the right of the checkbox. The label is part\nof the clickable element to select the checkbox.'
|
|
631
|
+
}, {
|
|
632
|
+
name: 'name',
|
|
633
|
+
type: 'string',
|
|
634
|
+
description: 'The name of the submitted field in a checkbox.'
|
|
635
|
+
}, {
|
|
636
|
+
name: 'onChange',
|
|
637
|
+
type: '(e: ChangeEvent<HTMLInputElement>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
638
|
+
description: 'Function that is called whenever the state of the checkbox changes. It will\nbe called with an object containing the react synthetic event. Use `currentTarget` to get value, name and checked.'
|
|
639
|
+
}, {
|
|
640
|
+
name: 'value',
|
|
641
|
+
type: 'string | number',
|
|
642
|
+
description: 'The value to be used in the checkbox input. This is the value that will be returned on form submission.'
|
|
643
|
+
}, {
|
|
644
|
+
name: 'xcss',
|
|
645
|
+
type: 'false | (XCSSValue<"alignItems", DesignTokenStyles, ""> & {} & XCSSPseudo<"alignItems", never, never, DesignTokenStyles> & XCSSMediaQuery<...> & { ...; } & { ...; })',
|
|
646
|
+
description: 'Bounded style API. Defining allowed styles through this prop will be supported for future component\niterations. Any styles that are not allowed by this API will result in type and land blocking violations.'
|
|
647
|
+
}]
|
|
648
|
+
}, {
|
|
649
|
+
name: 'Code',
|
|
650
|
+
package: '@atlaskit/code',
|
|
651
|
+
description: 'Use for short code snippets inline with body text.',
|
|
652
|
+
status: 'general-availability',
|
|
653
|
+
usageGuidelines: ['Use for short, inline code snippets with body text', 'Default styling is overridable', 'Consider code block vs inline code'],
|
|
654
|
+
contentGuidelines: ['Use clear, readable code examples', 'Keep code snippets concise', 'Use meaningful variable names in examples'],
|
|
655
|
+
accessibilityGuidelines: ['When overriding styles, ensure contrast ratio ≥ 4.5:1 for text readability', 'Ensure code content is announced properly by screen readers', 'Consider code context and meaning'],
|
|
656
|
+
keywords: ['code', 'snippet', 'inline', 'syntax', 'programming'],
|
|
657
|
+
category: 'data-display',
|
|
658
|
+
examples: ["import { Code } from '@atlaskit/code';\nconst _default_1: React.JSX.Element[] = [<Code>{`<Code />`}</Code>];\nexport default _default_1;"],
|
|
659
|
+
props: [{
|
|
660
|
+
name: 'children',
|
|
661
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
662
|
+
description: 'Content to be rendered in the inline code block.'
|
|
663
|
+
}, {
|
|
664
|
+
name: 'codeBidiWarningLabel',
|
|
665
|
+
type: 'string',
|
|
666
|
+
description: 'Label for the bidi warning tooltip.\n\nDefaults to `Bidirectional characters change the order that text is rendered.\nThis could be used to obscure malicious code.`'
|
|
667
|
+
}, {
|
|
668
|
+
name: 'hasBidiWarnings',
|
|
669
|
+
type: 'boolean',
|
|
670
|
+
description: 'When set to `false`, disables code decorating with bidi warnings. Defaults to `true`.'
|
|
671
|
+
}, {
|
|
672
|
+
name: 'isBidiWarningTooltipEnabled',
|
|
673
|
+
type: 'boolean',
|
|
674
|
+
description: 'Sets whether to render tooltip with the warning or not. Intended to be\ndisabled when used in a mobile view, such as in the editor via mobile\nbridge, where the tooltip could end up being cut off or otherwise not work\nas expected. Defaults to `true`.'
|
|
675
|
+
}]
|
|
676
|
+
}, {
|
|
677
|
+
name: 'CodeBlock',
|
|
678
|
+
package: '@atlaskit/code',
|
|
679
|
+
description: 'A component for displaying multi-line code blocks with syntax highlighting.',
|
|
680
|
+
status: 'general-availability',
|
|
681
|
+
usageGuidelines: ['Use for multi-line code examples', 'Specify appropriate language for syntax highlighting', 'Consider code block sizing and scrolling', 'Use for code snippets that need formatting'],
|
|
682
|
+
contentGuidelines: ['Use clear, readable code examples', 'Consider code formatting and indentation', 'Use meaningful variable names in examples', 'Keep code blocks focused and relevant'],
|
|
683
|
+
accessibilityGuidelines: ['Ensure code blocks are announced properly by screen readers', 'Use appropriate contrast for code readability', 'Consider code context and meaning', 'Provide proper language identification'],
|
|
684
|
+
keywords: ['code', 'block', 'syntax', 'highlighting', 'multiline'],
|
|
685
|
+
category: 'data-display',
|
|
686
|
+
examples: ['import { CodeBlock } from \'@atlaskit/code\';\nconst exampleCodeBlock = `export default ({ name }: { name: string }) => <div>Hello {name}</div>;`;\nconst _default_1: React.JSX.Element[] = [\n\t<CodeBlock highlight="15" language="tsx" text={exampleCodeBlock} />,\n];\nexport default _default_1;'],
|
|
687
|
+
props: [{
|
|
688
|
+
name: 'codeBidiWarningLabel',
|
|
689
|
+
type: 'string',
|
|
690
|
+
description: 'Label for the bidi warning tooltip.',
|
|
691
|
+
defaultValue: "'Bidirectional characters change the order that text is rendered. This could be used to obscure malicious code.'"
|
|
692
|
+
}, {
|
|
693
|
+
name: 'firstLineNumber',
|
|
694
|
+
type: 'number',
|
|
695
|
+
description: 'Sets the number of the first line, if showLineNumbers is set to true.',
|
|
696
|
+
defaultValue: '1'
|
|
697
|
+
}, {
|
|
698
|
+
name: 'hasBidiWarnings',
|
|
699
|
+
type: 'boolean',
|
|
700
|
+
description: 'When set to `false`, disables code decorating with bidi warnings.',
|
|
701
|
+
defaultValue: 'true'
|
|
702
|
+
}, {
|
|
703
|
+
name: 'highlight',
|
|
704
|
+
type: 'string',
|
|
705
|
+
description: 'Comma delimited lines to highlight.\n\nExample uses:\n- To highlight one line `highlight="3"`\n- To highlight a group of lines `highlight="1-5"`\n- To highlight multiple groups `highlight="1-5,7,10,15-20"`'
|
|
706
|
+
}, {
|
|
707
|
+
name: 'highlightedEndText',
|
|
708
|
+
type: 'string',
|
|
709
|
+
description: 'Screen reader text for the end of a highlighted line.'
|
|
710
|
+
}, {
|
|
711
|
+
name: 'highlightedStartText',
|
|
712
|
+
type: 'string',
|
|
713
|
+
description: 'Screen reader text for the start of a highlighted line.'
|
|
714
|
+
}, {
|
|
715
|
+
name: 'isBidiWarningTooltipEnabled',
|
|
716
|
+
type: 'boolean',
|
|
717
|
+
description: 'Sets whether to render tooltip with the warning or not.\nIntended to be disabled when used in a mobile view, such as in the editor via mobile bridge,\nwhere the tooltip could end up being cut off or otherwise not work as expected.',
|
|
718
|
+
defaultValue: 'true'
|
|
719
|
+
}, {
|
|
720
|
+
name: 'label',
|
|
721
|
+
type: 'string',
|
|
722
|
+
description: "Text used to describe that the content of the code block is scrollable.\nSet only if the code block is scrollable. Defaults to 'Scrollable content'."
|
|
723
|
+
}, {
|
|
724
|
+
name: 'language',
|
|
725
|
+
type: '"PHP" | "php" | "php3" | "php4" | "php5" | "Java" | "java" | "CSharp" | "csharp" | "c#" | "Python" | "python" | "py" | "JavaScript" | "javascript" | "js" | "Html" | "html" | "xml" | ... 234 more ... | "markdown"',
|
|
726
|
+
description: 'Language reference designed to be populated from `SUPPORTED_LANGUAGES` in\n`design-system/code`. Run against language grammars from PrismJS (full list\navailable at [PrismJS documentation](https://prismjs.com/#supported-languages)).\n\nWhen set to "text" will not perform highlighting. If unsupported language\nprovided - code will be treated as "text" with no highlighting.',
|
|
727
|
+
defaultValue: "'text'"
|
|
728
|
+
}, {
|
|
729
|
+
name: 'shouldShowLineNumbers',
|
|
730
|
+
type: 'boolean',
|
|
731
|
+
description: 'Sets whether to display code line numbers or not.',
|
|
732
|
+
defaultValue: 'true'
|
|
733
|
+
}, {
|
|
734
|
+
name: 'shouldWrapLongLines',
|
|
735
|
+
type: 'boolean',
|
|
736
|
+
description: 'Sets whether long lines will create a horizontally scrolling container.\nWhen set to `true`, these lines will visually wrap instead.',
|
|
737
|
+
defaultValue: 'false'
|
|
738
|
+
}, {
|
|
739
|
+
name: 'text',
|
|
740
|
+
type: 'string',
|
|
741
|
+
description: 'The code to be formatted.',
|
|
742
|
+
isRequired: true
|
|
743
|
+
}]
|
|
744
|
+
}, {
|
|
745
|
+
name: 'Comment',
|
|
746
|
+
package: '@atlaskit/comment',
|
|
747
|
+
description: 'A component for displaying comments and discussions.',
|
|
748
|
+
status: 'general-availability',
|
|
749
|
+
usageGuidelines: ['Use for comment threads and discussions', 'Provide clear comment attribution', 'Handle comment nesting appropriately', 'Consider comment moderation features'],
|
|
750
|
+
contentGuidelines: ['Use clear, constructive comment content', 'Provide meaningful comment attribution', 'Use appropriate comment formatting', 'Consider comment context and purpose'],
|
|
751
|
+
accessibilityGuidelines: ['Ensure proper comment structure', 'Provide clear comment attribution', 'Use appropriate heading hierarchy', 'Consider screen reader navigation'],
|
|
752
|
+
keywords: ['comment', 'discussion', 'thread', 'conversation', 'chat'],
|
|
753
|
+
category: 'data-display',
|
|
754
|
+
examples: ['import Comment from \'@atlaskit/comment\';\nconst Example = (): React.JSX.Element => (\n\t<Comment\n\t\tauthor="Bob Johnson"\n\t\ttime="30 minutes ago"\n\t\tcontent="Another comment in the thread"\n\t\tavatar="https://picsum.photos/32/32"\n\t/>\n);\nexport default Example;'],
|
|
755
|
+
props: [{
|
|
756
|
+
name: 'actions',
|
|
757
|
+
type: 'React.ReactNode[]',
|
|
758
|
+
description: 'A list of `CommentAction` items rendered as a row of buttons below the content.',
|
|
759
|
+
defaultValue: '[]'
|
|
760
|
+
}, {
|
|
761
|
+
name: 'afterContent',
|
|
762
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
763
|
+
description: "Content that is rendered after the comment's content."
|
|
764
|
+
}, {
|
|
765
|
+
name: 'author',
|
|
766
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
767
|
+
description: 'A `CommentAuthor` element containing the name of the author.'
|
|
768
|
+
}, {
|
|
769
|
+
name: 'avatar',
|
|
770
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
771
|
+
description: "The element to display as the avatar. It's best to use `@atlaskit/avatar`.",
|
|
772
|
+
isRequired: true
|
|
773
|
+
}, {
|
|
774
|
+
name: 'children',
|
|
775
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
776
|
+
description: 'Provide nested comments as children.'
|
|
777
|
+
}, {
|
|
778
|
+
name: 'content',
|
|
779
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
780
|
+
description: 'The main content for the comment.'
|
|
781
|
+
}, {
|
|
782
|
+
name: 'edited',
|
|
783
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
784
|
+
description: 'A `CommentEdited` element which displays next to the time. Indicates whether the comment has been edited.'
|
|
785
|
+
}, {
|
|
786
|
+
name: 'errorActions',
|
|
787
|
+
type: 'React.ReactNode[]',
|
|
788
|
+
description: 'A list of `CommentAction` items rendered with a warning icon instead of the actions.',
|
|
789
|
+
defaultValue: '[]'
|
|
790
|
+
}, {
|
|
791
|
+
name: 'errorIconLabel',
|
|
792
|
+
type: 'string',
|
|
793
|
+
description: 'Text to show in the error icon label.',
|
|
794
|
+
defaultValue: '""'
|
|
795
|
+
}, {
|
|
796
|
+
name: 'headingLevel',
|
|
797
|
+
type: '"3" | "1" | "2" | "4" | "5" | "6"',
|
|
798
|
+
description: 'Use this to set the semantic heading level of the comment. The default comment heading has an `h3` tag. Make sure that headings are in the correct order and don’t skip levels.',
|
|
799
|
+
defaultValue: '"3"'
|
|
800
|
+
}, {
|
|
801
|
+
name: 'highlighted',
|
|
802
|
+
type: 'boolean',
|
|
803
|
+
description: 'Sets whether this comment should be highlighted.',
|
|
804
|
+
defaultValue: 'false'
|
|
805
|
+
}, {
|
|
806
|
+
name: 'id',
|
|
807
|
+
type: 'string',
|
|
808
|
+
description: 'An ID to be applied to the comment.'
|
|
809
|
+
}, {
|
|
810
|
+
name: 'isError',
|
|
811
|
+
type: 'boolean',
|
|
812
|
+
description: 'Indicates whether the component is in an error state. Hides actions and time.',
|
|
813
|
+
defaultValue: 'false'
|
|
814
|
+
}, {
|
|
815
|
+
name: 'isSaving',
|
|
816
|
+
type: 'boolean',
|
|
817
|
+
description: 'Enables "optimistic saving" mode which removes actions and displays text from the `savingText` prop.',
|
|
818
|
+
defaultValue: 'false'
|
|
819
|
+
}, {
|
|
820
|
+
name: 'restrictedTo',
|
|
821
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
822
|
+
description: 'Text for the "restricted to" label. This will display in the top items, before the main content.',
|
|
823
|
+
defaultValue: '""'
|
|
824
|
+
}, {
|
|
825
|
+
name: 'savingText',
|
|
826
|
+
type: 'string',
|
|
827
|
+
description: 'Text to show when in "optimistic saving" mode.',
|
|
828
|
+
defaultValue: '"Sending..."'
|
|
829
|
+
}, {
|
|
830
|
+
name: 'shouldHeaderWrap',
|
|
831
|
+
type: 'boolean',
|
|
832
|
+
description: 'Controls if the comment header should wrap.'
|
|
833
|
+
}, {
|
|
834
|
+
name: 'shouldRenderNestedCommentsInline',
|
|
835
|
+
type: 'boolean',
|
|
836
|
+
description: 'Controls if nested comments are rendered at the same depth as the parent comment.'
|
|
837
|
+
}, {
|
|
838
|
+
name: 'time',
|
|
839
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
840
|
+
description: 'A `CommentTime` element containing the time to display.'
|
|
841
|
+
}, {
|
|
842
|
+
name: 'type',
|
|
843
|
+
type: 'string',
|
|
844
|
+
description: 'The type of comment. This will be rendered in a lozenge at the top of the comment, before the main content.'
|
|
845
|
+
}]
|
|
846
|
+
}, {
|
|
847
|
+
name: 'DatePicker',
|
|
848
|
+
package: '@atlaskit/datetime-picker',
|
|
849
|
+
description: 'A component for selecting date values with calendar support.',
|
|
850
|
+
status: 'general-availability',
|
|
851
|
+
usageGuidelines: ['Use for date selection only', 'Provide clear date formats', 'Handle date validation appropriately', 'Consider calendar button visibility'],
|
|
852
|
+
contentGuidelines: ['Use clear, descriptive labels', 'Provide helpful placeholder text', 'Keep labels concise but descriptive', 'Use locale prop for date format localization'],
|
|
853
|
+
accessibilityGuidelines: ['Ensure proper keyboard navigation', 'Use appropriate date formats', 'Provide clear date labels', 'Consider screen reader announcements'],
|
|
854
|
+
keywords: ['date', 'picker', 'calendar', 'selection', 'form'],
|
|
855
|
+
category: 'form',
|
|
856
|
+
examples: ['import { DatePicker } from \'@atlaskit/datetime-picker\';\nimport __noop from \'@atlaskit/ds-lib/noop\';\nconst Example = (): React.JSX.Element => (\n\t<DatePicker\n\t\tclearControlLabel="Clear select date"\n\t\tonChange={__noop}\n\t\tshouldShowCalendarButton\n\t\topenCalendarLabel="open calendar"\n\t/>\n);\nexport default Example;'],
|
|
857
|
+
props: [{
|
|
858
|
+
name: 'aria-describedby',
|
|
859
|
+
type: 'string',
|
|
860
|
+
description: 'Used to associate accessible descriptions to the date picker.'
|
|
861
|
+
}, {
|
|
862
|
+
name: 'autoFocus',
|
|
863
|
+
type: 'boolean',
|
|
864
|
+
description: 'Set the picker to autofocus on mount.'
|
|
865
|
+
}, {
|
|
866
|
+
name: 'clearControlLabel',
|
|
867
|
+
type: 'string',
|
|
868
|
+
description: 'Set the `aria-label` for the clear button.\nAdd the word "Clear" at the beginning of the clearControlLabel.\nFor instance, for a field to set an appointment, use "Clear appointment date and time".'
|
|
869
|
+
}, {
|
|
870
|
+
name: 'dateFormat',
|
|
871
|
+
type: 'string',
|
|
872
|
+
description: "Format the date with a string that is accepted by [date-fns's format\nfunction](https://date-fns.org/v1.29.0/docs/format). **This does not affect\nhow the input is parsed.** This must be done using the `parseInputValue`\nprop.\n\nNote that though we are using `date-fns` version 2, we use [the tokens from\n`date-fns` version 1](https://date-fns.org/v1.30.1/docs/format) under the\nhood."
|
|
873
|
+
}, {
|
|
874
|
+
name: 'defaultValue',
|
|
875
|
+
type: 'string',
|
|
876
|
+
description: 'The default for `value`.'
|
|
877
|
+
}, {
|
|
878
|
+
name: 'disabled',
|
|
879
|
+
type: 'string[]',
|
|
880
|
+
description: 'An array of ISO dates that should be disabled on the calendar. This does not affect what users can type into the picker.'
|
|
881
|
+
}, {
|
|
882
|
+
name: 'disabledDateFilter',
|
|
883
|
+
type: '(date: string) => boolean',
|
|
884
|
+
description: 'A filter function for disabling dates on the calendar. This does not affect what users can type into the picker.\n\nThe function is called with a date string in the format `YYYY-MM-DD` and should return `true` if the date should be disabled.'
|
|
885
|
+
}, {
|
|
886
|
+
name: 'formatDisplayLabel',
|
|
887
|
+
type: '(value: string, dateFormat: string) => string',
|
|
888
|
+
description: "A function for formatting the date displayed in the input. By default composes together [`date-fns`'s parse method](https://date-fns.org/v1.29.0/docs/parse) and [`date-fns`'s format method](https://date-fns.org/v1.29.0/docs/format) to return a correctly formatted date string.\n\nNote that this does not affect how the input is parsed. This must be done using the `parseInputValue` prop."
|
|
889
|
+
}, {
|
|
890
|
+
name: 'id',
|
|
891
|
+
type: 'string',
|
|
892
|
+
description: 'Set the id of the field.\nAssociates a `<label></label>` with the field.'
|
|
893
|
+
}, {
|
|
894
|
+
name: 'inputLabel',
|
|
895
|
+
type: 'string',
|
|
896
|
+
description: 'The name of the input, used when `shouldShowCalendarButton` is true. See `shouldShowCalendarButton` description for more details.',
|
|
897
|
+
defaultValue: "'Date picker'"
|
|
898
|
+
}, {
|
|
899
|
+
name: 'inputLabelId',
|
|
900
|
+
type: 'string',
|
|
901
|
+
description: 'The ID of the label for the input, used when `shouldShowCalendarButton` is\ntrue. See `shouldShowCalendarButton` description for more details.'
|
|
902
|
+
}, {
|
|
903
|
+
name: 'isDisabled',
|
|
904
|
+
type: 'boolean',
|
|
905
|
+
description: 'Set if the picker is disabled.'
|
|
906
|
+
}, {
|
|
907
|
+
name: 'isInvalid',
|
|
908
|
+
type: 'boolean',
|
|
909
|
+
description: 'Set if the picker has an invalid value.'
|
|
910
|
+
}, {
|
|
911
|
+
name: 'isOpen',
|
|
912
|
+
type: 'boolean',
|
|
913
|
+
description: 'Set if the picker is open.'
|
|
914
|
+
}, {
|
|
915
|
+
name: 'isRequired',
|
|
916
|
+
type: 'boolean',
|
|
917
|
+
description: 'Set the field as required.'
|
|
918
|
+
}, {
|
|
919
|
+
name: 'label',
|
|
920
|
+
type: 'string',
|
|
921
|
+
description: 'Accessible name for the Date Picker Select, rendered as `aria-label`. This will override any other method of providing a label.'
|
|
922
|
+
}, {
|
|
923
|
+
name: 'locale',
|
|
924
|
+
type: 'string',
|
|
925
|
+
description: 'Locale used to format the date and calendar. See [DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat).'
|
|
926
|
+
}, {
|
|
927
|
+
name: 'maxDate',
|
|
928
|
+
type: 'string',
|
|
929
|
+
description: 'The latest enabled date. Dates after this are disabled on the calendar. This does not affect what users can type into the picker.'
|
|
930
|
+
}, {
|
|
931
|
+
name: 'menuInnerWrapper',
|
|
932
|
+
type: 'ComponentClass<{ children: ReactNode; }, any> | FunctionComponent<{ children: ReactNode; }>',
|
|
933
|
+
description: 'This overrides the inner wrapper the Calendar.\n@private Please use this with extreme caution, this API may be changed in the future.'
|
|
934
|
+
}, {
|
|
935
|
+
name: 'minDate',
|
|
936
|
+
type: 'string',
|
|
937
|
+
description: 'The earliest enabled date. Dates before this are disabled on the calendar. This does not affect what users can type into the picker.'
|
|
938
|
+
}, {
|
|
939
|
+
name: 'name',
|
|
940
|
+
type: 'string',
|
|
941
|
+
description: 'The name of the field.'
|
|
942
|
+
}, {
|
|
943
|
+
name: 'nextMonthLabel',
|
|
944
|
+
type: 'string',
|
|
945
|
+
description: 'The aria-label attribute associated with the next-month arrow.'
|
|
946
|
+
}, {
|
|
947
|
+
name: 'onBlur',
|
|
948
|
+
type: '(event: FocusEvent<HTMLInputElement, Element>) => void',
|
|
949
|
+
description: 'Called when the field is blurred.'
|
|
950
|
+
}, {
|
|
951
|
+
name: 'onChange',
|
|
952
|
+
type: '(value: string) => void',
|
|
953
|
+
description: 'Called when the value changes. The only argument is an ISO time or empty string.'
|
|
954
|
+
}, {
|
|
955
|
+
name: 'onFocus',
|
|
956
|
+
type: '(event: FocusEvent<HTMLInputElement, Element>) => void',
|
|
957
|
+
description: 'Called when the field is focused.'
|
|
958
|
+
}, {
|
|
959
|
+
name: 'openCalendarLabel',
|
|
960
|
+
type: 'string',
|
|
961
|
+
description: 'The label associated with the button to open the calendar, rendered via the\n`shouldShowCalendarButton` prop. If a `label` prop is provided, this\ncalendar button label will be prefixed by the value of `label`. If no\n`label` prop is provided, this prefix should be manually added. For\nexample,\n\n```tsx\n<label id="label" htmlFor="datepicker">Desired Appointment Date</label>\n<DatePicker\n\tid="datepicker"\n\tshouldShowCalendarButton\n\tinputLabel="Desired Appointment Date"\n\topenCalendarLabel="open calendar"\n/>\n```',
|
|
962
|
+
defaultValue: "'open calendar'"
|
|
963
|
+
}, {
|
|
964
|
+
name: 'parseInputValue',
|
|
965
|
+
type: '(date: string, dateFormat: string) => Date',
|
|
966
|
+
description: 'A function for parsing input characters and transforming them into a Date object.\nBy default parses the date string based off the locale. Note that this does\nnot affect how the resulting value is displayed in the input. Use the\n`dateFormat` or `formatDisplayLabel` prop to handle how the value is\ndisplayed.'
|
|
967
|
+
}, {
|
|
968
|
+
name: 'placeholder',
|
|
969
|
+
type: 'string',
|
|
970
|
+
description: 'Placeholder text displayed in input.'
|
|
971
|
+
}, {
|
|
972
|
+
name: 'previousMonthLabel',
|
|
973
|
+
type: 'string',
|
|
974
|
+
description: 'The aria-label attribute associated with the previous-month arrow.'
|
|
975
|
+
}, {
|
|
976
|
+
name: 'selectProps',
|
|
977
|
+
type: 'Omit<SelectProps<OptionType, false>, "aria-label" | "aria-describedby" | "inputId" | "placeholder"> & { \'aria-describedby\'?: never; \'aria-label\'?: never; inputId?: never; placeholder?: never; } & { ...; }',
|
|
978
|
+
description: ''
|
|
979
|
+
}, {
|
|
980
|
+
name: 'shouldShowCalendarButton',
|
|
981
|
+
type: 'boolean',
|
|
982
|
+
description: 'Provides a functional calendar button that opens the calendar picker that\nlives on the right side of the date picker.\n\nThe accessible name for this button is caculated using either the `label`,\n`inputLabel`, or `inputLabelId` props, along with the `openCalendarLabel`\nprop.',
|
|
983
|
+
defaultValue: 'false'
|
|
984
|
+
}, {
|
|
985
|
+
name: 'spacing',
|
|
986
|
+
type: '"default" | "compact"',
|
|
987
|
+
description: 'The spacing for the select control.\n\nCompact is `gridSize() * 4`, default is `gridSize * 5`.'
|
|
988
|
+
}, {
|
|
989
|
+
name: 'value',
|
|
990
|
+
type: 'string',
|
|
991
|
+
description: 'The ISO time used as the input value.'
|
|
992
|
+
}, {
|
|
993
|
+
name: 'weekStartDay',
|
|
994
|
+
type: '0 | 1 | 2 | 3 | 4 | 5 | 6',
|
|
995
|
+
description: 'Start day of the week for the calendar.\n- `0` sunday (default value)\n- `1` monday\n- `2` tuesday\n- `3` wednesday\n- `4` thursday\n- `5` friday\n- `6` saturday'
|
|
996
|
+
}]
|
|
997
|
+
}, {
|
|
998
|
+
name: 'DateTimePicker',
|
|
999
|
+
package: '@atlaskit/datetime-picker',
|
|
1000
|
+
description: 'A component for selecting both date and time values.',
|
|
1001
|
+
status: 'general-availability',
|
|
1002
|
+
usageGuidelines: ['Use for combined date and time selection', 'Provide clear date/time formats', 'Handle timezone considerations', 'Consider validation requirements'],
|
|
1003
|
+
contentGuidelines: ['Use clear, descriptive labels', 'Provide helpful placeholder text', 'Use appropriate date/time formats', 'Keep labels concise but descriptive', 'Use locale prop for date and time format localization'],
|
|
1004
|
+
accessibilityGuidelines: ['Ensure proper keyboard navigation', 'Use appropriate date/time formats', 'Provide clear date/time labels', 'Consider screen reader announcements'],
|
|
1005
|
+
keywords: ['datetime', 'picker', 'date', 'time', 'calendar'],
|
|
1006
|
+
category: 'form',
|
|
1007
|
+
examples: ["import { DateTimePicker } from '@atlaskit/datetime-picker';\nimport __noop from '@atlaskit/ds-lib/noop';\nconst Example = (): React.JSX.Element => (\n\t<DateTimePicker\n\t\tclearControlLabel=\"Clear date / time picker (editable times)\"\n\t\tdefaultValue=\"2018-01-02T14:30+10:00\"\n\t\tonChange={__noop}\n\t\ttimePickerProps={{\n\t\t\ttimeIsEditable: true,\n\t\t\tlabel: 'Time picker (editable)',\n\t\t}}\n\t\tdatePickerProps={{\n\t\t\tlabel: 'Date picker (editable times)',\n\t\t\tshouldShowCalendarButton: true,\n\t\t\topenCalendarLabel: 'open calendar',\n\t\t}}\n\t/>\n);\nexport default Example;"],
|
|
1008
|
+
props: [{
|
|
1009
|
+
name: 'aria-describedby',
|
|
1010
|
+
type: 'string',
|
|
1011
|
+
description: 'Used to associate accessible descriptions to both the date and time\npicker. If you want to associate individual accessible descriptions, this\nshould be done through the `aria-describedby` props on the\n`datePickerProps` and `timePickerProps`.'
|
|
1012
|
+
}, {
|
|
1013
|
+
name: 'autoFocus',
|
|
1014
|
+
type: 'boolean',
|
|
1015
|
+
description: 'Set the picker to autofocus on mount.'
|
|
1016
|
+
}, {
|
|
1017
|
+
name: 'clearControlLabel',
|
|
1018
|
+
type: 'string',
|
|
1019
|
+
description: 'Set the `aria-label` for the clear button.\nAdd the word "Clear" at the beginning of the clearControlLabel.\nFor instance, for a field to set an appointment, use "Clear appointment date and time".'
|
|
1020
|
+
}, {
|
|
1021
|
+
name: 'datePickerProps',
|
|
1022
|
+
type: 'DatePickerBaseProps',
|
|
1023
|
+
description: 'Props applied to the `DatePicker`.'
|
|
1024
|
+
}, {
|
|
1025
|
+
name: 'defaultValue',
|
|
1026
|
+
type: 'string',
|
|
1027
|
+
description: 'The default for `value`.'
|
|
1028
|
+
}, {
|
|
1029
|
+
name: 'id',
|
|
1030
|
+
type: 'string',
|
|
1031
|
+
description: 'Set the id of the field.'
|
|
1032
|
+
}, {
|
|
1033
|
+
name: 'isDisabled',
|
|
1034
|
+
type: 'boolean',
|
|
1035
|
+
description: 'Set if the field is disabled.'
|
|
1036
|
+
}, {
|
|
1037
|
+
name: 'isInvalid',
|
|
1038
|
+
type: 'boolean',
|
|
1039
|
+
description: 'Set if the picker has an invalid value.'
|
|
1040
|
+
}, {
|
|
1041
|
+
name: 'isRequired',
|
|
1042
|
+
type: 'boolean',
|
|
1043
|
+
description: 'Set the field as required.'
|
|
1044
|
+
}, {
|
|
1045
|
+
name: 'locale',
|
|
1046
|
+
type: 'string',
|
|
1047
|
+
description: 'Locale used for formatting dates and times. See [DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat).'
|
|
1048
|
+
}, {
|
|
1049
|
+
name: 'name',
|
|
1050
|
+
type: 'string',
|
|
1051
|
+
description: 'The name of the field.'
|
|
1052
|
+
}, {
|
|
1053
|
+
name: 'onBlur',
|
|
1054
|
+
type: '(event: FocusEvent<HTMLInputElement, Element>) => void',
|
|
1055
|
+
description: 'Called when the field is blurred.'
|
|
1056
|
+
}, {
|
|
1057
|
+
name: 'onChange',
|
|
1058
|
+
type: '((value: string) => void) & ((value: string) => void)',
|
|
1059
|
+
description: 'Called when the value changes and the date / time is a complete value, or empty. The only value is an ISO string or empty string.'
|
|
1060
|
+
}, {
|
|
1061
|
+
name: 'onFocus',
|
|
1062
|
+
type: '(event: FocusEvent<HTMLInputElement, Element>) => void',
|
|
1063
|
+
description: 'Called when the field is focused.'
|
|
1064
|
+
}, {
|
|
1065
|
+
name: 'parseValue',
|
|
1066
|
+
type: '((dateTimeValue: string, date: string, time: string, timezone: string) => { dateValue: string; timeValue: string; zoneValue: string; }) & ((dateTimeValue: string, date: string, time: string, timezone: string) => { ...; })',
|
|
1067
|
+
description: 'Function used to parse datetime values into their date, time and timezone sub-values. *'
|
|
1068
|
+
}, {
|
|
1069
|
+
name: 'spacing',
|
|
1070
|
+
type: '"default" | "compact"',
|
|
1071
|
+
description: 'The spacing for the select control.\n\nCompact is `gridSize() * 4`, default is `gridSize() * 5`.'
|
|
1072
|
+
}, {
|
|
1073
|
+
name: 'timePickerProps',
|
|
1074
|
+
type: 'TimePickerBaseProps',
|
|
1075
|
+
description: 'Props applied to the `TimePicker`.'
|
|
1076
|
+
}, {
|
|
1077
|
+
name: 'value',
|
|
1078
|
+
type: 'string',
|
|
1079
|
+
description: 'The ISO time that should be used as the input value.'
|
|
1080
|
+
}]
|
|
1081
|
+
}, {
|
|
1082
|
+
name: 'TimePicker',
|
|
1083
|
+
package: '@atlaskit/datetime-picker',
|
|
1084
|
+
description: 'A component for selecting time values with clock interface.',
|
|
1085
|
+
status: 'general-availability',
|
|
1086
|
+
usageGuidelines: ['Use for time selection only', 'Provide clear time formats', 'Handle time validation appropriately', 'Consider editable time input'],
|
|
1087
|
+
contentGuidelines: ['Use clear, descriptive labels', 'Provide helpful placeholder text', 'Use appropriate time formats', 'Keep labels concise but descriptive', 'Use locale prop for time format localization (e.g. 12h vs 24h)'],
|
|
1088
|
+
accessibilityGuidelines: ['Ensure proper keyboard navigation', 'Use appropriate time formats', 'Provide clear time labels', 'Consider screen reader announcements'],
|
|
1089
|
+
keywords: ['time', 'picker', 'clock', 'selection', 'form'],
|
|
1090
|
+
category: 'form',
|
|
1091
|
+
examples: ['import { TimePicker } from \'@atlaskit/datetime-picker\';\nimport __noop from \'@atlaskit/ds-lib/noop\';\nconst Example = (): React.JSX.Element => (\n\t<TimePicker\n\t\tclearControlLabel="Clear select time (editable)"\n\t\tdefaultValue="14:30"\n\t\tonChange={__noop}\n\t\ttimeFormat="HH:mm:ss A"\n\t\ttimeIsEditable\n\t\tselectProps={{\n\t\t\tclassNamePrefix: \'timepicker-select\',\n\t\t}}\n\t/>\n);\nexport default Example;'],
|
|
1092
|
+
props: [{
|
|
1093
|
+
name: 'aria-describedby',
|
|
1094
|
+
type: 'string',
|
|
1095
|
+
description: 'Used to associate accessible descriptions to the time picker.'
|
|
1096
|
+
}, {
|
|
1097
|
+
name: 'autoFocus',
|
|
1098
|
+
type: 'boolean',
|
|
1099
|
+
description: 'Set the picker to autofocus on mount.'
|
|
1100
|
+
}, {
|
|
1101
|
+
name: 'clearControlLabel',
|
|
1102
|
+
type: 'string',
|
|
1103
|
+
description: 'Set the `aria-label` for the clear button.\nAdd the word "Clear" at the beginning of the clearControlLabel.\nFor instance, for a field to set an appointment, use "Clear appointment date and time".'
|
|
1104
|
+
}, {
|
|
1105
|
+
name: 'defaultValue',
|
|
1106
|
+
type: 'string',
|
|
1107
|
+
description: 'The default for `value`.'
|
|
1108
|
+
}, {
|
|
1109
|
+
name: 'formatDisplayLabel',
|
|
1110
|
+
type: '(time: string, timeFormat: string) => string',
|
|
1111
|
+
description: 'A function for formatting the displayed time value in the input. By default\nparses with an internal time parser, and formats using the [date-fns format\nfunction]((https://date-fns.org/v1.29.0/docs/format)).\n\nNote that this does not affect how the input is parsed. This must be done\nusing the `parseInputValue` prop.'
|
|
1112
|
+
}, {
|
|
1113
|
+
name: 'hideIcon',
|
|
1114
|
+
type: 'boolean',
|
|
1115
|
+
description: 'Hides icon for dropdown indicator.'
|
|
1116
|
+
}, {
|
|
1117
|
+
name: 'id',
|
|
1118
|
+
type: 'string',
|
|
1119
|
+
description: 'Set the id of the field.\nAssociates a `<label></label>` with the field.'
|
|
1120
|
+
}, {
|
|
1121
|
+
name: 'isDisabled',
|
|
1122
|
+
type: 'boolean',
|
|
1123
|
+
description: 'Set if the field is disabled.'
|
|
1124
|
+
}, {
|
|
1125
|
+
name: 'isInvalid',
|
|
1126
|
+
type: 'boolean',
|
|
1127
|
+
description: 'Set if the picker has an invalid value.'
|
|
1128
|
+
}, {
|
|
1129
|
+
name: 'isOpen',
|
|
1130
|
+
type: 'boolean',
|
|
1131
|
+
description: 'Set if the dropdown is open. Will be `false` if not provided.'
|
|
1132
|
+
}, {
|
|
1133
|
+
name: 'isRequired',
|
|
1134
|
+
type: 'boolean',
|
|
1135
|
+
description: 'Set the field as required.'
|
|
1136
|
+
}, {
|
|
1137
|
+
name: 'label',
|
|
1138
|
+
type: 'string',
|
|
1139
|
+
description: 'Accessible name for the Time Picker Select, rendered as `aria-label`. This will override any other method of providing a label.'
|
|
1140
|
+
}, {
|
|
1141
|
+
name: 'locale',
|
|
1142
|
+
type: 'string',
|
|
1143
|
+
description: 'Locale used to format the time. See [DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DateTimeFormat).'
|
|
1144
|
+
}, {
|
|
1145
|
+
name: 'name',
|
|
1146
|
+
type: 'string',
|
|
1147
|
+
description: 'The name of the field.'
|
|
1148
|
+
}, {
|
|
1149
|
+
name: 'onBlur',
|
|
1150
|
+
type: '(event: FocusEvent<HTMLElement, Element>) => void',
|
|
1151
|
+
description: 'Called when the field is blurred.'
|
|
1152
|
+
}, {
|
|
1153
|
+
name: 'onChange',
|
|
1154
|
+
type: '(value: string) => void',
|
|
1155
|
+
description: 'Called when the value changes. The only argument is an ISO time or empty string.'
|
|
1156
|
+
}, {
|
|
1157
|
+
name: 'onFocus',
|
|
1158
|
+
type: '(event: FocusEvent<HTMLElement, Element>) => void',
|
|
1159
|
+
description: 'Called when the field is focused.'
|
|
1160
|
+
}, {
|
|
1161
|
+
name: 'parseInputValue',
|
|
1162
|
+
type: '(time: string, timeFormat: string) => string | Date',
|
|
1163
|
+
description: 'A function for parsing input characters and transforming them into either a\nstring or a Date object. By default parses the string based off the locale.\nNote that this does not affect how the resulting value is displayed in the\ninput. To handle this, use either the `timeFormat` or `formatDisplayLabel`\nprop.'
|
|
1164
|
+
}, {
|
|
1165
|
+
name: 'placeholder',
|
|
1166
|
+
type: 'string',
|
|
1167
|
+
description: 'Placeholder text displayed in input.'
|
|
1168
|
+
}, {
|
|
1169
|
+
name: 'selectProps',
|
|
1170
|
+
type: 'Omit<SelectProps<OptionType, false>, "aria-describedby" | "placeholder" | "aria-label" | "inputId"> & { \'aria-describedby\'?: never; \'aria-label\'?: never; inputId?: never; placeholder?: never; }'
|
|
1171
|
+
}, {
|
|
1172
|
+
name: 'spacing',
|
|
1173
|
+
type: '"default" | "compact"',
|
|
1174
|
+
description: 'The spacing for the select control.\n\nCompact is `gridSize() * 4`, default is `gridSize * 5`.'
|
|
1175
|
+
}, {
|
|
1176
|
+
name: 'timeFormat',
|
|
1177
|
+
type: 'string',
|
|
1178
|
+
description: "Format the time with a string that is accepted by [date-fns's format\nfunction](https://date-fns.org/v1.29.0/docs/format). **This does not affect\nhow the input is parsed.** This must be done using the `parseInputValue`\nprop.\n\nNote that though we are using `date-fns` version 2, we use [the tokens from\n`date-fns` version 1](https://date-fns.org/v1.30.1/docs/format) under the\nhood."
|
|
1179
|
+
}, {
|
|
1180
|
+
name: 'timeIsEditable',
|
|
1181
|
+
type: 'boolean',
|
|
1182
|
+
description: 'Set if users can edit the input, allowing them to add custom times.'
|
|
1183
|
+
}, {
|
|
1184
|
+
name: 'times',
|
|
1185
|
+
type: 'string[]',
|
|
1186
|
+
description: 'The times shown in the dropdown.'
|
|
1187
|
+
}, {
|
|
1188
|
+
name: 'value',
|
|
1189
|
+
type: 'string',
|
|
1190
|
+
description: 'The ISO time that should be used as the input value.'
|
|
1191
|
+
}]
|
|
1192
|
+
}, {
|
|
1193
|
+
name: 'DropdownMenu',
|
|
1194
|
+
package: '@atlaskit/dropdown-menu',
|
|
1195
|
+
description: 'A dropdown menu component for displaying contextual actions and options.',
|
|
1196
|
+
status: 'general-availability',
|
|
1197
|
+
usageGuidelines: ['Use for 5–15 items; navigation or command (action on selection)', 'Avoid truncation—check max width; avoid truncated labels', 'Nested menu: maximum two layers', 'In a modal, use shouldRenderToParent for correct focus and screen reader behavior', 'Disabled triggers are not supported (see Button a11y)', 'Use Select for search/select; Checkbox for multiple from list; Radio for short single choice'],
|
|
1198
|
+
contentGuidelines: ['Logical order (e.g. most selected first); group with uppercase section title', 'Use verbs for actions, nouns for links; no articles; single line per item', 'Use clear, descriptive menu item labels', 'Keep menu item text concise', 'Group related actions logically', 'Use consistent terminology across menu items'],
|
|
1199
|
+
accessibilityGuidelines: ['Avoid truncation—ensure max width does not cut off labels', 'Focus lock when open; keyboard open should focus first item', 'Nested menu: maximum two layers', 'In modal use shouldRenderToParent for focus and voicing', 'Provide clear labels for dropdown triggers', 'Ensure keyboard navigation with arrow keys', 'Use appropriate ARIA attributes'],
|
|
1200
|
+
keywords: ['dropdown', 'menu', 'actions', 'options', 'popup', 'contextual'],
|
|
1201
|
+
category: 'navigation',
|
|
1202
|
+
examples: ['import { IconButton } from \'@atlaskit/button/new\';\nimport DropdownMenu, { DropdownItem, DropdownItemGroup } from \'@atlaskit/dropdown-menu\';\nimport MoreIcon from \'@atlaskit/icon/core/show-more-horizontal\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<DropdownMenu\n\t\t\tshouldRenderToParent\n\t\t\ttrigger={({ triggerRef, ...props }) => (\n\t\t\t\t<IconButton ref={triggerRef} {...props} icon={MoreIcon} label="More" />\n\t\t\t)}\n\t\t>\n\t\t\t<DropdownItemGroup>\n\t\t\t\t<DropdownItem href="/dashboard">Dashboard</DropdownItem>\n\t\t\t\t<DropdownItem>Create</DropdownItem>\n\t\t\t\t<DropdownItem>Delete</DropdownItem>\n\t\t\t</DropdownItemGroup>\n\t\t</DropdownMenu>\n\t\t<DropdownMenu shouldRenderToParent trigger="Actions">\n\t\t\t<DropdownItemGroup>\n\t\t\t\t<DropdownItem>Export</DropdownItem>\n\t\t\t\t<DropdownItem>Share</DropdownItem>\n\t\t\t</DropdownItemGroup>\n\t\t</DropdownMenu>\n\t</>\n);\nexport default Examples;'],
|
|
1203
|
+
props: [{
|
|
1204
|
+
name: 'appearance',
|
|
1205
|
+
type: '"default" | "tall"',
|
|
1206
|
+
description: "Controls the appearance of the menu.\nThe default menu will scroll after its height exceeds the pre-defined amount.\nThe tall menu won't scroll until the height exceeds the height of the viewport."
|
|
1207
|
+
}, {
|
|
1208
|
+
name: 'autoFocus',
|
|
1209
|
+
type: 'boolean',
|
|
1210
|
+
description: 'Controls if the first menu item receives focus when menu is opened. Note that the menu has a focus lock\nwhich traps the focus within the menu. The first item gets focus automatically\nif the menu is triggered using the keyboard.',
|
|
1211
|
+
defaultValue: 'false'
|
|
1212
|
+
}, {
|
|
1213
|
+
name: 'children',
|
|
1214
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1215
|
+
description: 'Content that will be rendered inside the layer element. Should typically be\n`DropdownItemGroup` or `DropdownItem`, or the checkbox and radio variants of those.'
|
|
1216
|
+
}, {
|
|
1217
|
+
name: 'defaultOpen',
|
|
1218
|
+
type: 'boolean',
|
|
1219
|
+
description: 'Controls the initial open state of the dropdown. If provided, the component is considered to be controlled\nwhich means that the user is responsible for managing the open and close state of the menu.\nUsing `defaultOpen` may cause accessiblity issues because it will automatically shift focus to the first menu item; which can be disorienting.\nOnly use this if action on the menu is required to proceed.',
|
|
1220
|
+
defaultValue: 'false'
|
|
1221
|
+
}, {
|
|
1222
|
+
name: 'isLoading',
|
|
1223
|
+
type: 'boolean',
|
|
1224
|
+
description: 'If true, a spinner is rendered instead of the items.',
|
|
1225
|
+
defaultValue: 'false'
|
|
1226
|
+
}, {
|
|
1227
|
+
name: 'isOpen',
|
|
1228
|
+
type: 'boolean',
|
|
1229
|
+
description: 'Controls the open state of the dropdown.'
|
|
1230
|
+
}, {
|
|
1231
|
+
name: 'label',
|
|
1232
|
+
type: 'string',
|
|
1233
|
+
description: 'Provide an accessible label via `aria-label` for assistive technology.'
|
|
1234
|
+
}, {
|
|
1235
|
+
name: 'menuLabel',
|
|
1236
|
+
type: 'string',
|
|
1237
|
+
description: 'Provide an accessible label for the menu element for assistive technology.'
|
|
1238
|
+
}, {
|
|
1239
|
+
name: 'onOpenChange',
|
|
1240
|
+
type: '(args: OnOpenChangeArgs) => void',
|
|
1241
|
+
description: 'Called when the menu should be open/closed. Receives an object with `isOpen` state.\n\nIf the dropdown was closed programatically, the `event` parameter will be `null`.',
|
|
1242
|
+
defaultValue: 'noop'
|
|
1243
|
+
}, {
|
|
1244
|
+
name: 'placement',
|
|
1245
|
+
type: '"auto-start" | "auto" | "auto-end" | "top-start" | "top" | "top-end" | "right-start" | "right" | "right-end" | "bottom-end" | "bottom" | "bottom-start" | "left-end" | "left" | "left-start"',
|
|
1246
|
+
description: 'Position of the menu.',
|
|
1247
|
+
defaultValue: '"bottom-start"'
|
|
1248
|
+
}, {
|
|
1249
|
+
name: 'returnFocusRef',
|
|
1250
|
+
type: 'React.RefObject<HTMLElement>',
|
|
1251
|
+
description: 'If ref is passed, focus returns to that specific ref element after dropdown dismissed.'
|
|
1252
|
+
}, {
|
|
1253
|
+
name: 'shouldFitContainer',
|
|
1254
|
+
type: 'boolean',
|
|
1255
|
+
description: "This fits the dropdown menu width to its parent's width.\nWhen set to `true`, the trigger and dropdown menu elements will be wrapped in a `div` with `position: relative`.\nThe dropdown menu will be rendered as a sibling to the trigger element, and will be full width.\nThe default is `false`.\n\nThis fits the dropdown menu width to its parent's width.\nWhen set to `true`, the trigger and dropdown menu elements will be wrapped in a `div` with `position: relative`.\nThe dropdown menu will be rendered as a sibling to the trigger element, and will be full width.\nThe default is `false`.",
|
|
1256
|
+
defaultValue: 'false'
|
|
1257
|
+
}, {
|
|
1258
|
+
name: 'shouldFlip',
|
|
1259
|
+
type: 'boolean',
|
|
1260
|
+
description: 'Allows the dropdown menu to be placed on the opposite side of its trigger if it does not\nfit in the viewport.',
|
|
1261
|
+
defaultValue: 'true'
|
|
1262
|
+
}, {
|
|
1263
|
+
name: 'shouldPreventEscapePropagation',
|
|
1264
|
+
type: 'boolean',
|
|
1265
|
+
description: 'When set to true, will call stopPropagation on the ESCAPE key event.\nThis prevents the ESCAPE event from bubbling up to parent elements.',
|
|
1266
|
+
defaultValue: 'false'
|
|
1267
|
+
}, {
|
|
1268
|
+
name: 'shouldRenderToParent',
|
|
1269
|
+
type: 'boolean',
|
|
1270
|
+
description: 'Controls whether the popup is rendered inline within its parent component or in a portal at the document root.\n`true` renders the dropdown menu in the DOM node closest to the trigger; focus is not trapped inside the element.\n`false` renders the dropdown menu in React.Portal and focus is trapped inside the element.\nDefaults to `false`.\nControls whether the popup is rendered inline within its parent component or in a portal at the document root.\n`true` renders the dropdown menu in the DOM node closest to the trigger; focus is not trapped inside the element.\n`false` renders the dropdown menu in React.Portal and focus is trapped inside the element.\nDefaults to `false`.',
|
|
1271
|
+
defaultValue: 'false'
|
|
1272
|
+
}, {
|
|
1273
|
+
name: 'spacing',
|
|
1274
|
+
type: '"compact" | "cozy"',
|
|
1275
|
+
description: 'Controls the spacing density of the menu.'
|
|
1276
|
+
}, {
|
|
1277
|
+
name: 'statusLabel',
|
|
1278
|
+
type: 'string',
|
|
1279
|
+
description: 'Text to be used as status for assistive technologies. Defaults to "Loading".'
|
|
1280
|
+
}, {
|
|
1281
|
+
name: 'strategy',
|
|
1282
|
+
type: '"absolute" | "fixed"',
|
|
1283
|
+
description: 'This controls the positioning strategy to use. Can vary between `absolute` and `fixed`.\nThe default is `fixed`.\nThis controls the positioning strategy to use. Can vary between `absolute` and `fixed`.\nThe default is `fixed`.'
|
|
1284
|
+
}, {
|
|
1285
|
+
name: 'trigger',
|
|
1286
|
+
type: 'string | ((triggerButtonProps: CustomTriggerProps<T>) => React.ReactElement<any, string | React.JSXElementConstructor<any>>)',
|
|
1287
|
+
description: 'Content that triggers the dropdown menu to open and close. Use with\n`triggerType` to get a button trigger. To customize the trigger element,\nprovide a function to this prop. You can find\n[examples for custom triggers](https://atlassian.design/components/dropdown-menu/examples#custom-triggers)\nin our documentation.'
|
|
1288
|
+
}, {
|
|
1289
|
+
name: 'zIndex',
|
|
1290
|
+
type: 'number',
|
|
1291
|
+
description: 'Z-index that the popup should be displayed in.\nThis is passed to the portal component.\nDefaults to `layers.modal()` from `@atlaskit/theme` which is 510.',
|
|
1292
|
+
defaultValue: '510'
|
|
1293
|
+
}]
|
|
1294
|
+
}, {
|
|
1295
|
+
name: 'EmptyState',
|
|
1296
|
+
package: '@atlaskit/empty-state',
|
|
1297
|
+
description: 'A component for when there is nothing to display (no tasks, cleared inbox, no results).',
|
|
1298
|
+
status: 'general-availability',
|
|
1299
|
+
usageGuidelines: ['Use when nothing to display in a view (no tasks, no results, cleared inbox)', 'Header is required; illustration, description, and buttons are optional', 'Use wide (464px) or narrow (304px) layout as appropriate', 'Provide one primary CTA; do not stack multiple primary buttons', 'Use illustration as spot only—do not resize; keep relevant, neutral or humorous', 'Explain why the state is empty and provide clear next steps', 'Consider i18n for illustrations (e.g. culturally neutral imagery, translatable alt text)'],
|
|
1300
|
+
contentGuidelines: ['Blank slate: inspirational, motivating tone', 'All done: celebratory tone', 'No results: neutral tone with next steps', 'Use clear, descriptive headers', 'Provide specific next steps; avoid negative language'],
|
|
1301
|
+
accessibilityGuidelines: ['Avoid jargon; use simple language', 'Use descriptive link text (not "click here")', 'Add alt text only if the illustration is meaningful; otherwise omit or mark decorative', 'Provide clear empty state messaging', 'Use appropriate headings and structure', 'Ensure actionable content is accessible'],
|
|
1302
|
+
keywords: ['empty', 'state', 'placeholder', 'no-content', 'void'],
|
|
1303
|
+
category: 'status',
|
|
1304
|
+
examples: ['import EmptyState from \'@atlaskit/empty-state\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<EmptyState header="No items" description="Add items to get started" />\n\t\t<EmptyState\n\t\t\theader="No search results"\n\t\t\tdescription="Try adjusting your search criteria or browse all items."\n\t\t/>\n\t\t<EmptyState\n\t\t\theader="Welcome to your dashboard"\n\t\t\tdescription="Create your first project to get started with the platform."\n\t\t/>\n\t</>\n);\nexport default Examples;'],
|
|
1305
|
+
props: [{
|
|
1306
|
+
name: 'buttonGroupLabel',
|
|
1307
|
+
type: 'string',
|
|
1308
|
+
description: 'Accessible name for the action buttons group of empty state. Can be used for internationalization. Default is "Button group".'
|
|
1309
|
+
}, {
|
|
1310
|
+
name: 'description',
|
|
1311
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1312
|
+
description: 'The main block of text that holds additional supporting information.'
|
|
1313
|
+
}, {
|
|
1314
|
+
name: 'header',
|
|
1315
|
+
type: 'string',
|
|
1316
|
+
description: 'Title that briefly describes the page to the user.',
|
|
1317
|
+
isRequired: true
|
|
1318
|
+
}, {
|
|
1319
|
+
name: 'headingLevel',
|
|
1320
|
+
type: 'number',
|
|
1321
|
+
description: 'The value used to set the heading level of the header element.\nMust be in the range of 1 to 6. Defaults to 4.',
|
|
1322
|
+
defaultValue: '4'
|
|
1323
|
+
}, {
|
|
1324
|
+
name: 'headingSize',
|
|
1325
|
+
type: '"xsmall" | "medium"',
|
|
1326
|
+
description: 'The keyword used to set the visual appearance of the header element.\nDefaults to "medium". "xsmall" can be used for empty states in smaller contexts such as popups.',
|
|
1327
|
+
defaultValue: '"medium"'
|
|
1328
|
+
}, {
|
|
1329
|
+
name: 'imageHeight',
|
|
1330
|
+
type: 'number',
|
|
1331
|
+
description: 'Height of the image that is rendered in EmptyState component.\nUseful when you want image to be of exact height to stop it bouncing around when loading in.\nOnly set `height` if you want the image to resize down on smaller devices.'
|
|
1332
|
+
}, {
|
|
1333
|
+
name: 'imageUrl',
|
|
1334
|
+
type: 'string',
|
|
1335
|
+
description: 'The url of image that will be shown above the title, fed directly into the `src` prop of an <img> element.\nNote, this image will be constrained by the `maxWidth` and `maxHeight` props.'
|
|
1336
|
+
}, {
|
|
1337
|
+
name: 'imageWidth',
|
|
1338
|
+
type: 'number',
|
|
1339
|
+
description: 'Width of the image that is rendered in EmptyState component.\nUseful when you want image to be of exact width to stop it bouncing around when loading in.'
|
|
1340
|
+
}, {
|
|
1341
|
+
name: 'isLoading',
|
|
1342
|
+
type: 'boolean',
|
|
1343
|
+
description: 'Used to indicate a loading state. Will show a spinner next to the action buttons when true.'
|
|
1344
|
+
}, {
|
|
1345
|
+
name: 'maxImageHeight',
|
|
1346
|
+
type: 'number',
|
|
1347
|
+
description: 'Maximum height (in pixels) of the image, default value is 160.',
|
|
1348
|
+
defaultValue: '160'
|
|
1349
|
+
}, {
|
|
1350
|
+
name: 'maxImageWidth',
|
|
1351
|
+
type: 'number',
|
|
1352
|
+
description: 'Maximum width (in pixels) of the image, default value is 160.',
|
|
1353
|
+
defaultValue: '160'
|
|
1354
|
+
}, {
|
|
1355
|
+
name: 'primaryAction',
|
|
1356
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1357
|
+
description: 'Primary action button for the page, usually it will be something like "Create" (or "Retry" for error pages).'
|
|
1358
|
+
}, {
|
|
1359
|
+
name: 'renderImage',
|
|
1360
|
+
type: '(props: RenderImageProps) => React.ReactNode',
|
|
1361
|
+
description: 'An alternative API to supply an image using a render prop. Only rendered if no `imageUrl` is supplied.'
|
|
1362
|
+
}, {
|
|
1363
|
+
name: 'secondaryAction',
|
|
1364
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1365
|
+
description: 'Secondary action button for the page.'
|
|
1366
|
+
}, {
|
|
1367
|
+
name: 'tertiaryAction',
|
|
1368
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1369
|
+
description: 'Button with link to some external resource like documentation or tutorial, it will be opened in a new tab.'
|
|
1370
|
+
}, {
|
|
1371
|
+
name: 'width',
|
|
1372
|
+
type: '"narrow" | "wide"',
|
|
1373
|
+
description: 'Controls how much horizontal space the component fills. Defaults to "wide".'
|
|
1374
|
+
}]
|
|
1375
|
+
}, {
|
|
1376
|
+
name: 'Flag',
|
|
1377
|
+
package: '@atlaskit/flag',
|
|
1378
|
+
description: 'A component for displaying brief messages.',
|
|
1379
|
+
status: 'general-availability',
|
|
1380
|
+
usageGuidelines: ['Use for confirmations and alerts needing minimal interaction', 'Position at bottom left; overlays content', 'Default: dismissible, event-driven (e.g. avatar update). Bold: not dismissible, severity (success/loading/warning/error), collapsed/expanded', 'Use Banner for critical/system messages; Inline message when action is required; Modal for immediate action'],
|
|
1381
|
+
contentGuidelines: ['Be clear about what went wrong for errors', 'Provide specific steps to resolve issues', 'Use a helpful, non-threatening tone', 'Clearly state potential consequences for warnings', 'Confirm outcome then get out of the way for success messages', 'Information: inform, no action needed', 'Warning: before action, empathy, offer alternative', 'Error: explain what went wrong and next step; use "we" not "you"', 'Success: confirm outcome, then get out of the way; option to view details', 'Be clear and concise; use a helpful, non-threatening tone'],
|
|
1382
|
+
accessibilityGuidelines: ['Keep copy concise for zoom and long words', 'Use h2 for title via `headingLevel` prop; maintain heading hierarchy', 'Do not stack dismissible and non-dismissible flags', 'Do not rely on color alone for severity', 'Avoid dead ends—always indicate how to proceed', 'Do not use auto-dismiss for critical messages', 'Use descriptive link text that describes the destination', 'Ensure flag content is announced by screen readers', 'Consider screen reader announcement conflicts'],
|
|
1383
|
+
keywords: ['flag', 'message', 'notification', 'alert', 'toast'],
|
|
1384
|
+
category: 'feedback',
|
|
1385
|
+
examples: ['import Flag, { FlagGroup } from \'@atlaskit/flag\';\nimport InfoIcon from \'@atlaskit/icon/core/status-information\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<FlagGroup>\n\t\t\t<Flag\n\t\t\t\tid="flag-1"\n\t\t\t\ticon={<InfoIcon label="Info" />}\n\t\t\t\ttitle="Success"\n\t\t\t\tdescription="Your changes have been saved successfully."\n\t\t\t\tappearance="success"\n\t\t\t/>\n\t\t</FlagGroup>\n\t\t<FlagGroup>\n\t\t\t<Flag\n\t\t\t\tid="flag-2"\n\t\t\t\ticon={<InfoIcon label="Warning" />}\n\t\t\t\ttitle="Warning"\n\t\t\t\tdescription="This action cannot be undone."\n\t\t\t\tappearance="warning"\n\t\t\t\tactions={[\n\t\t\t\t\t{\n\t\t\t\t\t\tcontent: \'Proceed\',\n\t\t\t\t\t\tonClick: () => console.log(\'Proceed clicked\'),\n\t\t\t\t\t},\n\t\t\t\t]}\n\t\t\t/>\n\t\t</FlagGroup>\n\t\t<FlagGroup>\n\t\t\t<Flag\n\t\t\t\tid="flag-3"\n\t\t\t\ticon={<InfoIcon label="Error" />}\n\t\t\t\ttitle="Error"\n\t\t\t\tdescription="Something went wrong. Please try again."\n\t\t\t\tappearance="error"\n\t\t\t\tactions={[\n\t\t\t\t\t{\n\t\t\t\t\t\tcontent: \'Retry\',\n\t\t\t\t\t\tonClick: () => console.log(\'Retry clicked\'),\n\t\t\t\t\t},\n\t\t\t\t]}\n\t\t\t/>\n\t\t</FlagGroup>\n\t</>\n);\nexport default Examples;'],
|
|
1386
|
+
props: [{
|
|
1387
|
+
name: 'actions',
|
|
1388
|
+
type: 'ActionType[]',
|
|
1389
|
+
description: "Array of clickable actions to be shown at the bottom of the flag. For flags where appearance\nis 'normal', actions will be shown as links. For all other appearance values, actions will\nshown as buttons.\nIf href is passed the action will be shown as a link with the passed href prop."
|
|
1390
|
+
}, {
|
|
1391
|
+
name: 'appearance',
|
|
1392
|
+
type: '"error" | "info" | "success" | "warning" | "normal"',
|
|
1393
|
+
description: "Makes the flag appearance bold. Setting this to anything other than 'normal' hides the\ndismiss button."
|
|
1394
|
+
}, {
|
|
1395
|
+
name: 'autoDismissSeconds',
|
|
1396
|
+
type: 'number',
|
|
1397
|
+
description: 'Duration in seconds before flag gets auto dismissed.\nDefault is 8 seconds. For a11y reasons 8s is also a strongly-suggested minimum.\nOnly applies to auto-dismissable flags.'
|
|
1398
|
+
}, {
|
|
1399
|
+
name: 'delayAnnouncement',
|
|
1400
|
+
type: 'number',
|
|
1401
|
+
description: 'Milliseconds to delay the screen reader announcement due to announcement conflict.'
|
|
1402
|
+
}, {
|
|
1403
|
+
name: 'description',
|
|
1404
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1405
|
+
description: 'The secondary content shown below the flag title.'
|
|
1406
|
+
}, {
|
|
1407
|
+
name: 'headingLevel',
|
|
1408
|
+
type: '1 | 2 | 3 | 4 | 5 | 6',
|
|
1409
|
+
description: 'Specifies the heading level in the document structure.\nIf not specified, the default is `2`.'
|
|
1410
|
+
}, {
|
|
1411
|
+
name: 'icon',
|
|
1412
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1413
|
+
description: 'The icon displayed in the top-left of the flag. Should be an instance of `@atlaskit/icon`.\nYour icon will receive the appropriate default color, which you can override by setting\nthe `color` prop on the icon to your preferred icon color.\nIf no icon is provided, a default icon will be used based on the appearance prop.'
|
|
1414
|
+
}, {
|
|
1415
|
+
name: 'id',
|
|
1416
|
+
type: 'string | number',
|
|
1417
|
+
description: 'A unique identifier used for rendering and onDismissed callbacks.',
|
|
1418
|
+
isRequired: true
|
|
1419
|
+
}, {
|
|
1420
|
+
name: 'linkComponent',
|
|
1421
|
+
type: 'React.ComponentClass<CustomThemeButtonProps, any> | React.FunctionComponent<CustomThemeButtonProps>',
|
|
1422
|
+
description: 'A link component that is passed down to the `@atlaskit/button` used by actions,\nto allow custom routers to be used. See the\n[button with router](https://atlaskit.atlassian.com/packages/design-system/button/example/ButtonWithRouter)\nexample of what this component should look like.'
|
|
1423
|
+
}, {
|
|
1424
|
+
name: 'onBlur',
|
|
1425
|
+
type: '(e: React.FocusEvent<HTMLElement, Element>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
1426
|
+
description: 'Standard onBlur event, applied to Flag by AutoDismissFlag.'
|
|
1427
|
+
}, {
|
|
1428
|
+
name: 'onDismissed',
|
|
1429
|
+
type: '(id: string | number, analyticsEvent: UIAnalyticsEvent) => void',
|
|
1430
|
+
description: "Handler which will be called when a Flag's dismiss button is clicked.\nReceives the id of the dismissed Flag as a parameter."
|
|
1431
|
+
}, {
|
|
1432
|
+
name: 'onFocus',
|
|
1433
|
+
type: '(e: React.FocusEvent<HTMLElement, Element>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
1434
|
+
description: 'Standard onFocus event, applied to Flag by AutoDismissFlag.'
|
|
1435
|
+
}, {
|
|
1436
|
+
name: 'onMouseOut',
|
|
1437
|
+
type: '(event: React.MouseEvent<Element, MouseEvent>) => void',
|
|
1438
|
+
description: 'Standard onMouseOut event, applied to Flag by AutoDismissFlag.'
|
|
1439
|
+
}, {
|
|
1440
|
+
name: 'onMouseOver',
|
|
1441
|
+
type: '(event: React.MouseEvent<Element, MouseEvent>) => void',
|
|
1442
|
+
description: 'Standard onMouseOver event, applied to Flag by AutoDismissFlag.'
|
|
1443
|
+
}, {
|
|
1444
|
+
name: 'title',
|
|
1445
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1446
|
+
description: 'The bold text shown at the top of the flag.',
|
|
1447
|
+
isRequired: true
|
|
1448
|
+
}]
|
|
1449
|
+
}, {
|
|
1450
|
+
name: 'Form',
|
|
1451
|
+
package: '@atlaskit/form',
|
|
1452
|
+
description: 'A component for building forms with validation and state management.',
|
|
1453
|
+
status: 'general-availability',
|
|
1454
|
+
usageGuidelines: ['Use when users need to provide and submit information (settings, create work item)', 'Use with textfield, select, radio, checkbox and other form controls', 'Structure: title, description, required legend, asterisk, helper text, labels above fields, character counter where needed, sections, footer with primary/secondary actions', 'Provide clear field labels and instructions', 'Mark required fields with asterisk (*)', 'Provide specific error messages'],
|
|
1455
|
+
contentGuidelines: ['Use clear, concise labels', 'Use labels and helper text for critical info—not placeholder alone (exception: search with icon + label)', 'Provide specific error messages', 'Use consistent terminology', 'Always include a visible label (exception: search fields)', 'Match field length to intended content length'],
|
|
1456
|
+
accessibilityGuidelines: ['Autofocus the first field when appropriate', 'Use visible labels for all fields (search is the exception)', 'Never disable the submit button—use validation and instructions so users know how to proceed', 'Support autofill tokens and persist form state on refresh where appropriate', 'Use inline validation with clear instructions', 'Provide clear labels for all form fields', 'Ensure keyboard navigation between fields', 'Mark required fields clearly'],
|
|
1457
|
+
keywords: ['form', 'validation', 'field', 'input', 'submit', 'state'],
|
|
1458
|
+
category: 'form',
|
|
1459
|
+
examples: ['import Button from \'@atlaskit/button/new\';\nimport { Checkbox } from \'@atlaskit/checkbox\';\nimport Form, { CheckboxField, ErrorMessage, Field, FormFooter, FormHeader } from \'@atlaskit/form\';\nimport TextField from \'@atlaskit/textfield\';\nconst Example = (): React.JSX.Element => (\n\t<Form onSubmit={(data) => console.log(\'validated form\', data)}>\n\t\t<FormHeader title="Basic Form">\n\t\t\t<p>Fill out the form below</p>\n\t\t</FormHeader>\n\t\t<Field\n\t\t\tname="username"\n\t\t\tlabel="Username"\n\t\t\tisRequired\n\t\t\tvalidate={(value) => (value && value.length < 3 ? \'Too short\' : undefined)}\n\t\t>\n\t\t\t{({ fieldProps, error }) => (\n\t\t\t\t<>\n\t\t\t\t\t<TextField {...fieldProps} />\n\t\t\t\t\t{error && <ErrorMessage>Username must be at least 3 characters</ErrorMessage>}\n\t\t\t\t</>\n\t\t\t)}\n\t\t</Field>\n\t\t<CheckboxField name="terms" value="terms">\n\t\t\t{({ fieldProps }) => <Checkbox {...fieldProps} label="I accept the terms" />}\n\t\t</CheckboxField>\n\t\t<FormFooter>\n\t\t\t<Button type="submit" appearance="primary">\n\t\t\t\tCreate Account\n\t\t\t</Button>\n\t\t</FormFooter>\n\t</Form>\n);\nexport default Example;'],
|
|
1460
|
+
props: [{
|
|
1461
|
+
name: 'autocomplete',
|
|
1462
|
+
type: '"off" | "on"',
|
|
1463
|
+
description: "Indicates whether the value of the form's controls can be automatically completed by the browser. It is `on` by default."
|
|
1464
|
+
}, {
|
|
1465
|
+
name: 'children',
|
|
1466
|
+
type: '(() => void) | React.ReactNode | ((args: FormChildrenArgs<FormValues>) => React.ReactNode)',
|
|
1467
|
+
description: 'The contents rendered inside of the form. This is a function where the props will be passed from the form. The function props you can access are `dirty`, `submitting` and `disabled`.\nYou can read more about these props in [react-final form documentation](https://final-form.org/docs/final-form/types/FormState).\n\nIf you are only spreading `formProps` onto the HTML `<form>` element and not using any of the other props (like `submitting`, etc.), `children` can be plain JSX. All of the children will be wrapped within an HTML `<form>` element that includes all necessary props, including those provided on the form component.',
|
|
1468
|
+
isRequired: true
|
|
1469
|
+
}, {
|
|
1470
|
+
name: 'formProps',
|
|
1471
|
+
type: '{ [x: string]: any; } & ExcludeReservedFormProps',
|
|
1472
|
+
description: 'When `Form` renders JSX children directly and not using a function to\nspread `formProps` manually, the properties in this `formProps` prop will\nbe spread on an internally rendered HTML `form` element.'
|
|
1473
|
+
}, {
|
|
1474
|
+
name: 'id',
|
|
1475
|
+
type: 'string',
|
|
1476
|
+
description: '`id` attribute applied to the `form` element.'
|
|
1477
|
+
}, {
|
|
1478
|
+
name: 'isDisabled',
|
|
1479
|
+
type: 'boolean',
|
|
1480
|
+
description: 'Sets the form and its fields as disabled. Users cannot edit or focus on the fields.'
|
|
1481
|
+
}, {
|
|
1482
|
+
name: 'label',
|
|
1483
|
+
type: 'string',
|
|
1484
|
+
description: 'Accessible name to be applied to the form element. Maps to the `aria-label` attribute.'
|
|
1485
|
+
}, {
|
|
1486
|
+
name: 'labelId',
|
|
1487
|
+
type: 'string',
|
|
1488
|
+
description: 'ID of the element that has the accessible name to be applied to the form element. Maps to the `aria-labelledby` attribute.'
|
|
1489
|
+
}, {
|
|
1490
|
+
name: 'name',
|
|
1491
|
+
type: 'string',
|
|
1492
|
+
description: '`name` attribute applied to the `form` element.'
|
|
1493
|
+
}, {
|
|
1494
|
+
name: 'noValidate',
|
|
1495
|
+
type: 'boolean',
|
|
1496
|
+
description: 'Indicates if the inputs within the form will bypass HTML5 constraint\nvalidation when submitted. This is not recommended to be used because it\ncan cause experiences to be inaccessible. It is `false` by default but will\nbe set to `true` in the future to increase accessibility, so it is **not recommended**.'
|
|
1497
|
+
}, {
|
|
1498
|
+
name: 'onSubmit',
|
|
1499
|
+
type: '(values: FormValues, form: FormApi<FormValues>, callback?: (errors?: Record<string, string>) => void) => void | Object | Promise<...>',
|
|
1500
|
+
description: 'Event handler called when the form is submitted. Fields must be free of validation errors.',
|
|
1501
|
+
isRequired: true
|
|
1502
|
+
}, {
|
|
1503
|
+
name: 'xcss',
|
|
1504
|
+
type: 'false | (XCSSValue<"flex" | "grid" | "fill" | "stroke" | "all" | "bottom" | "left" | "right" | "top" | "clip" | "overlay" | "accentColor" | "alignContent" | "alignItems" | "alignSelf" | ... 486 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
1505
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
1506
|
+
}]
|
|
1507
|
+
}, {
|
|
1508
|
+
name: 'Heading',
|
|
1509
|
+
package: '@atlaskit/heading',
|
|
1510
|
+
description: 'A component for creating accessible, consistently styled headings with proper hierarchy. Headings are sized to contrast with content, increase visual hierarchy, and help readers easily understand the structure of content.',
|
|
1511
|
+
status: 'general-availability',
|
|
1512
|
+
usageGuidelines: ['Use the `HeadingContextProvider` offering to maintain heading levels in complex layouts', 'Maintain proper heading hierarchy', 'Keep headings concise and meaningful', 'Use sentence case for most headings', 'Use the `color` prop for inverse text on dark backgrounds', 'Do NOT use any inline styles, you must use the `size` (required) and `color` (optional) props available'],
|
|
1513
|
+
contentGuidelines: ['Use clear, descriptive heading text', 'Maintain proper heading hierarchy', 'Keep headings concise and meaningful', 'Use sentence case for most headings', 'Make headings descriptive of the content that follows'],
|
|
1514
|
+
accessibilityGuidelines: ['Maintain proper heading hierarchy (h1 to h6)', 'Use only one h1 per page for main page titles', 'Ensure minimum 4.5:1 color contrast for text readability', 'Use clear, descriptive heading text that describes the content below'],
|
|
1515
|
+
keywords: ['heading', 'title', 'header', 'typography', 'text', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
|
|
1516
|
+
category: 'primitive',
|
|
1517
|
+
examples: ['import Heading from \'@atlaskit/heading\';\nconst _default_1: React.JSX.Element[] = [\n\t<Heading size="xxlarge">Page Title</Heading>,\n\t<Heading size="large" color="color.text.inverse">\n\t\tInverted section title\n\t</Heading>,\n];\nexport default _default_1;'],
|
|
1518
|
+
props: [{
|
|
1519
|
+
name: 'as',
|
|
1520
|
+
type: '"h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "div" | "span"',
|
|
1521
|
+
description: 'Allows the component to be rendered as the specified HTML element, overriding a default element set by the `size` prop.'
|
|
1522
|
+
}, {
|
|
1523
|
+
name: 'children',
|
|
1524
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
1525
|
+
description: 'The text of the heading.',
|
|
1526
|
+
isRequired: true
|
|
1527
|
+
}, {
|
|
1528
|
+
name: 'color',
|
|
1529
|
+
type: '"color.text" | "color.text.inverse" | "color.text.warning.inverse"',
|
|
1530
|
+
description: 'Token representing text color with a built-in fallback value.\nWill apply inverse text color automatically if placed within a Box with bold background color.\nDefaults to `color.text`.'
|
|
1531
|
+
}, {
|
|
1532
|
+
name: 'id',
|
|
1533
|
+
type: 'string',
|
|
1534
|
+
description: 'Unique identifier for the heading HTML element.'
|
|
1535
|
+
}, {
|
|
1536
|
+
name: 'size',
|
|
1537
|
+
type: '"xxlarge" | "xlarge" | "large" | "medium" | "small" | "xsmall" | "xxsmall"',
|
|
1538
|
+
description: 'Determines which text styles are applied. A corresponding HTML element is automatically applied from h1 to h6 based on the size.\nThis can be overriden using the `as` prop to allow for more flexibility.',
|
|
1539
|
+
isRequired: true
|
|
1540
|
+
}]
|
|
1541
|
+
}, {
|
|
1542
|
+
name: 'HeadingContextProvider',
|
|
1543
|
+
package: '@atlaskit/heading',
|
|
1544
|
+
description: 'A context provider that allows you to configure the default HTML heading level for all headings within its subtree. Useful for maintaining proper heading hierarchy in complex layouts.',
|
|
1545
|
+
status: 'general-availability',
|
|
1546
|
+
usageGuidelines: ['Wrap sections that need different heading hierarchy', 'Use for complex layouts where heading levels need adjustment'],
|
|
1547
|
+
contentGuidelines: ['Ensure proper heading hierarchy is maintained', 'Use clear, descriptive heading text', 'Keep headings concise and meaningful'],
|
|
1548
|
+
keywords: ['heading', 'context', 'provider', 'hierarchy', 'accessibility'],
|
|
1549
|
+
category: 'primitive',
|
|
1550
|
+
examples: ['import Heading, { HeadingContextProvider } from \'@atlaskit/heading\';\nconst _default_1: React.JSX.Element[] = [\n\t<HeadingContextProvider>\n\t\t<Heading size="xxlarge">h1</Heading>\n\t\t<Heading size="medium">h2</Heading>\n\t\t<Heading size="large">h3</Heading>\n\t</HeadingContextProvider>,\n];\nexport default _default_1;'],
|
|
1551
|
+
props: [{
|
|
1552
|
+
name: 'children',
|
|
1553
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1554
|
+
description: 'Semantic hierarchy of content below the heading context.',
|
|
1555
|
+
isRequired: true
|
|
1556
|
+
}, {
|
|
1557
|
+
name: 'value',
|
|
1558
|
+
type: '0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9',
|
|
1559
|
+
description: 'Optional - only apply this value if the intent is to reset the heading context outside the normal content flow, for example inside a `section`.'
|
|
1560
|
+
}]
|
|
1561
|
+
}, {
|
|
1562
|
+
name: 'Icon',
|
|
1563
|
+
package: '@atlaskit/icon',
|
|
1564
|
+
description: 'An icon is a symbol representing a command, device, directory, or common action.',
|
|
1565
|
+
status: 'general-availability',
|
|
1566
|
+
usageGuidelines: ['Use icons to enhance visual communication', 'Choose icons that clearly represent their function', 'Maintain consistent icon style and size', 'Use appropriate icon sizes for different contexts', 'Consider cultural and contextual icon meanings'],
|
|
1567
|
+
contentGuidelines: ['Use clear, recognizable icon symbols', 'Ensure icons are culturally appropriate', 'Maintain visual consistency across icon sets', 'Use appropriate icon labels and descriptions'],
|
|
1568
|
+
accessibilityGuidelines: ['Provide appropriate alt text or labels for icons', 'Use meaningful icon choices that convey clear meaning', 'Ensure sufficient color contrast for icon visibility', 'Consider icon size for touch targets', 'Use consistent iconography across the interface'],
|
|
1569
|
+
keywords: ['icon', 'symbol', 'command', 'device', 'directory', 'action', 'visual'],
|
|
1570
|
+
category: 'images-and-icons',
|
|
1571
|
+
examples: ["import AddIcon from '@atlaskit/icon/core/add';\nimport DeleteIcon from '@atlaskit/icon/core/delete';\nimport StarIcon from '@atlaskit/icon/core/star-starred';\nimport { token } from '@atlaskit/tokens';\nconst _default_1: React.JSX.Element[] = [\n\t<AddIcon label=\"Add\" />,\n\t<StarIcon label=\"Star\" color=\"currentColor\" />,\n\t<DeleteIcon label=\"Delete\" color={token('color.icon.danger')} />,\n];\nexport default _default_1;"],
|
|
1572
|
+
props: [{
|
|
1573
|
+
name: 'children',
|
|
1574
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
1575
|
+
description: "The content to be rendered inside the glyph component.\nOnly for legacy icons that used R16's implicit children prop.\nIt doesn't actually serve any purpose, but is required to resolve R18 type errors\nwithout updating all the legacy icon usages."
|
|
1576
|
+
}, {
|
|
1577
|
+
name: 'glyph',
|
|
1578
|
+
type: 'ComponentClass<CustomGlyphProps, any> | FunctionComponent<CustomGlyphProps>',
|
|
1579
|
+
description: 'Custom icon component that returns an SVG element with set `viewBox`,\n`width`, and `height` props.'
|
|
1580
|
+
}, {
|
|
1581
|
+
name: 'isFacadeDisabled',
|
|
1582
|
+
type: 'boolean',
|
|
1583
|
+
description: 'Used to opt out of the icon facade.'
|
|
1584
|
+
}, {
|
|
1585
|
+
name: 'label',
|
|
1586
|
+
type: 'string',
|
|
1587
|
+
description: 'Text used to describe what the icon is in context.',
|
|
1588
|
+
isRequired: true
|
|
1589
|
+
}, {
|
|
1590
|
+
name: 'primaryColor',
|
|
1591
|
+
type: 'string',
|
|
1592
|
+
description: 'Primary color for the icon.\nInherits the current font color by default.'
|
|
1593
|
+
}, {
|
|
1594
|
+
name: 'secondaryColor',
|
|
1595
|
+
type: 'string',
|
|
1596
|
+
description: 'Secondary color for the icon.\nDefaults to the page background for an icon that supports two colors.'
|
|
1597
|
+
}, {
|
|
1598
|
+
name: 'size',
|
|
1599
|
+
type: '"small" | "medium" | "large" | "xlarge"',
|
|
1600
|
+
description: 'There are three icon sizes – small (16px), medium (24px), and large (32px).\nThis pixel size refers to the canvas the icon sits on,\nnot the size of the icon shape itself.'
|
|
1601
|
+
}]
|
|
1602
|
+
}, {
|
|
1603
|
+
name: 'IconTile',
|
|
1604
|
+
package: '@atlaskit/icon',
|
|
1605
|
+
description: 'A tile component that displays an icon with customizable background, shape, and appearance.',
|
|
1606
|
+
status: 'release-candidate',
|
|
1607
|
+
usageGuidelines: ['Use for icon presentation with background styling', 'Choose appropriate shapes and appearances', 'Maintain consistent sizing across tiles', 'Use for visual emphasis or categorization'],
|
|
1608
|
+
contentGuidelines: ['Use clear, recognizable icons', 'Choose appropriate colors and shapes', 'Ensure visual consistency across tiles'],
|
|
1609
|
+
accessibilityGuidelines: ['Provide appropriate labels for icon tiles', 'Ensure sufficient color contrast', 'Use meaningful icon choices', 'Consider touch target sizes'],
|
|
1610
|
+
keywords: ['icon', 'tile', 'container', 'background', 'shape', 'appearance'],
|
|
1611
|
+
category: 'images-and-icons',
|
|
1612
|
+
examples: ['import { IconTile } from \'@atlaskit/icon\';\nimport AddIcon from \'@atlaskit/icon/core/add\';\nconst _default_1: React.JSX.Element[] = [\n\t<IconTile icon={AddIcon} label="Add" appearance="redBold" />,\n\t<IconTile icon={AddIcon} label="Add" shape="circle" appearance="blue" />,\n];\nexport default _default_1;'],
|
|
1613
|
+
props: [{
|
|
1614
|
+
name: 'appearance',
|
|
1615
|
+
type: '"gray" | "blue" | "teal" | "green" | "lime" | "yellow" | "orange" | "red" | "magenta" | "purple" | "grayBold" | "blueBold" | "tealBold" | "greenBold" | "limeBold" | "yellowBold" | "orangeBold" | "redBold" | "magentaBold" | "purpleBold"',
|
|
1616
|
+
description: 'The appearance of the tile',
|
|
1617
|
+
isRequired: true
|
|
1618
|
+
}, {
|
|
1619
|
+
name: 'icon',
|
|
1620
|
+
type: 'React.ComponentClass<NewCoreIconProps, any> | React.FunctionComponent<NewCoreIconProps>',
|
|
1621
|
+
description: 'The icon to display',
|
|
1622
|
+
isRequired: true
|
|
1623
|
+
}, {
|
|
1624
|
+
name: 'label',
|
|
1625
|
+
type: 'string',
|
|
1626
|
+
description: 'The label for the icon',
|
|
1627
|
+
isRequired: true
|
|
1628
|
+
}, {
|
|
1629
|
+
name: 'size',
|
|
1630
|
+
type: 'NewIconTileSize | LegacyIconTileSize',
|
|
1631
|
+
description: 'Size of the tile, in pixels. Defaults to `24`.\n\nNow supports both semantic t-shirt size names and pixel number values. Pixel number values are deprecated and will be removed in a future release, however they will both be available and backwards-compatible during a transition period.\n\nSize `16` will not have a replacement after deprecation, and should be replaced with direct icons without a tile or enlarging to the next available size `xsmall`.\n\nAll available sizes:\n- `16` (deprecated)\n- `xsmall` (new)\n- `small` or `24`\n- `medium` or `32`\n- `large` or `40`\n- `xlarge` or `48`'
|
|
1632
|
+
}]
|
|
1633
|
+
}, {
|
|
1634
|
+
name: 'Image',
|
|
1635
|
+
package: '@atlaskit/image',
|
|
1636
|
+
description: 'A component for displaying images with theme support.',
|
|
1637
|
+
status: 'open-beta',
|
|
1638
|
+
usageGuidelines: ['Use for displaying images in content', 'Provide appropriate alt text', 'Consider responsive image sizing', 'Handle loading and error states'],
|
|
1639
|
+
contentGuidelines: ['Use clear, descriptive alt text', 'Choose appropriate image dimensions', 'Consider image quality and file size', 'Use meaningful image content'],
|
|
1640
|
+
accessibilityGuidelines: ['Always provide meaningful alt text', 'Ensure appropriate image sizing', 'Consider loading states and error handling', 'Use appropriate image formats'],
|
|
1641
|
+
keywords: ['image', 'picture', 'photo', 'visual', 'media'],
|
|
1642
|
+
category: 'data-display',
|
|
1643
|
+
examples: ['import Image from \'@atlaskit/image\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Image src="https://picsum.photos/300/150" alt="Wide view" width={300} height={150} />\n\t\t<Image src="https://picsum.photos/100/100" alt="User profile" width={100} height={100} />\n\t</>\n);\nexport default Examples;'],
|
|
1644
|
+
props: [{
|
|
1645
|
+
name: 'srcDark',
|
|
1646
|
+
type: 'string',
|
|
1647
|
+
description: 'Image URL to use for dark mode. This overrides `src` when the user\nhas selected dark mode either in the app or on their operating system.'
|
|
1648
|
+
}]
|
|
1649
|
+
}, {
|
|
1650
|
+
name: 'InlineDialog',
|
|
1651
|
+
package: '@atlaskit/inline-dialog',
|
|
1652
|
+
description: 'A component opened by user action (e.g. click) for further info or actions for a section—not crucial to the whole page.',
|
|
1653
|
+
status: 'general-availability',
|
|
1654
|
+
usageGuidelines: ['Trigger by user action (e.g. click); do not open automatically', 'Use for section-level info or actions, not page-critical content', 'Keep content concise; only one inline dialog open at a time', 'Good for feature discovery and contextual controls', 'Anatomy: trigger, window, controls (buttons, checkboxes, text fields)', 'Use Inline message for alerts; Flag for confirmations; Modal for complex or long content'],
|
|
1655
|
+
contentGuidelines: ['Use clear, concise dialog content', 'Provide meaningful dialog titles', 'Keep content focused and relevant', 'Use appropriate dialog sizing'],
|
|
1656
|
+
accessibilityGuidelines: ['Ensure proper focus management', 'Provide clear dialog labels', 'Use appropriate ARIA attributes', 'Consider keyboard navigation'],
|
|
1657
|
+
keywords: ['dialog', 'inline', 'popup', 'overlay', 'tooltip'],
|
|
1658
|
+
category: 'overlay',
|
|
1659
|
+
examples: ["import Button from '@atlaskit/button/new';\nimport Heading from '@atlaskit/heading';\nimport InlineDialog from '@atlaskit/inline-dialog';\nimport { Text } from '@atlaskit/primitives/compiled';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<InlineDialog content={<div>This is an inline dialog</div>} isOpen={true}>\n\t\t\t<Button>Trigger</Button>\n\t\t</InlineDialog>\n\t\t<InlineDialog\n\t\t\tcontent={\n\t\t\t\t<div>\n\t\t\t\t\t<Heading size=\"large\">Dialog Title</Heading>\n\t\t\t\t\t<Text>Dialog content goes here</Text>\n\t\t\t\t</div>\n\t\t\t}\n\t\t\tisOpen={false}\n\t\t>\n\t\t\t<Button>Open Dialog</Button>\n\t\t</InlineDialog>\n\t</>\n);\nexport default Examples;"],
|
|
1660
|
+
props: [{
|
|
1661
|
+
name: 'children',
|
|
1662
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
1663
|
+
description: 'The elements that the InlineDialog will be positioned relative to.',
|
|
1664
|
+
isRequired: true
|
|
1665
|
+
}, {
|
|
1666
|
+
name: 'content',
|
|
1667
|
+
type: 'ReactNode | (() => ReactNode)',
|
|
1668
|
+
description: 'The elements to be displayed within the InlineDialog.',
|
|
1669
|
+
isRequired: true
|
|
1670
|
+
}, {
|
|
1671
|
+
name: 'fallbackPlacements',
|
|
1672
|
+
type: 'Placement[]',
|
|
1673
|
+
description: "This is a list of backup placements to try.\nWhen the preferred placement doesn't have enough space,\nthe modifier will test the ones provided in the list, and use the first suitable one.\nIf no fallback placements are suitable, it reverts back to the original placement."
|
|
1674
|
+
}, {
|
|
1675
|
+
name: 'isOpen',
|
|
1676
|
+
type: 'boolean',
|
|
1677
|
+
description: 'Sets whether to show or hide the dialog.'
|
|
1678
|
+
}, {
|
|
1679
|
+
name: 'onClose',
|
|
1680
|
+
type: '(obj: { isOpen: boolean; event: Event; }) => void',
|
|
1681
|
+
description: 'Function called when the dialog is open and a click occurs anywhere outside\nthe dialog.'
|
|
1682
|
+
}, {
|
|
1683
|
+
name: 'onContentBlur',
|
|
1684
|
+
type: '() => void',
|
|
1685
|
+
description: 'Function called when you lose focus on the object.'
|
|
1686
|
+
}, {
|
|
1687
|
+
name: 'onContentClick',
|
|
1688
|
+
type: '() => void',
|
|
1689
|
+
description: 'Function called when user clicks on the open dialog.'
|
|
1690
|
+
}, {
|
|
1691
|
+
name: 'onContentFocus',
|
|
1692
|
+
type: '() => void',
|
|
1693
|
+
description: 'Function called when user focuses on the open dialog.'
|
|
1694
|
+
}, {
|
|
1695
|
+
name: 'placement',
|
|
1696
|
+
type: '"auto-start" | "auto" | "auto-end" | "top-start" | "top" | "top-end" | "right-start" | "right" | "right-end" | "bottom-end" | "bottom" | "bottom-start" | "left-end" | "left" | "left-start"',
|
|
1697
|
+
description: 'Where the dialog should appear, relative to the contents of the children.'
|
|
1698
|
+
}, {
|
|
1699
|
+
name: 'strategy',
|
|
1700
|
+
type: '"fixed" | "absolute"',
|
|
1701
|
+
description: "Placement strategy used. Can be 'fixed' or 'absolute'. Defaults to 'fixed'."
|
|
1702
|
+
}]
|
|
1703
|
+
}, {
|
|
1704
|
+
name: 'InlineEdit',
|
|
1705
|
+
package: '@atlaskit/inline-edit',
|
|
1706
|
+
description: 'A component for inline editing of text content.',
|
|
1707
|
+
status: 'general-availability',
|
|
1708
|
+
usageGuidelines: ['Use for inline text editing', 'Provide clear edit state indicators', 'Handle save and cancel actions', 'Consider validation requirements'],
|
|
1709
|
+
contentGuidelines: ['Use clear, descriptive text content', 'Provide helpful placeholder text', 'Use appropriate validation messages', 'Keep content concise but meaningful'],
|
|
1710
|
+
accessibilityGuidelines: ['Ensure proper focus management', 'Provide clear edit state indicators', 'Use appropriate ARIA attributes', 'Consider keyboard navigation'],
|
|
1711
|
+
keywords: ['inline', 'edit', 'editable', 'text', 'input'],
|
|
1712
|
+
category: 'form',
|
|
1713
|
+
examples: ['import InlineEdit from \'@atlaskit/inline-edit\';\nconst Example = (): React.JSX.Element => (\n\t<InlineEdit\n\t\tonConfirm={() => {}}\n\t\tonCancel={() => {}}\n\t\tdefaultValue="Editable text"\n\t\teditView={() => <div>Edit view</div>}\n\t\treadView={() => <div>Read view</div>}\n\t/>\n);\nexport default Example;'],
|
|
1714
|
+
props: [{
|
|
1715
|
+
name: 'cancelButtonLabel',
|
|
1716
|
+
type: 'string',
|
|
1717
|
+
description: 'Accessibility label for the cancel action button.'
|
|
1718
|
+
}, {
|
|
1719
|
+
name: 'confirmButtonLabel',
|
|
1720
|
+
type: 'string',
|
|
1721
|
+
description: 'Accessibility label for the confirm action button, which saves the field value into `editValue`.'
|
|
1722
|
+
}, {
|
|
1723
|
+
name: 'defaultValue',
|
|
1724
|
+
type: 'any',
|
|
1725
|
+
description: 'The user input entered into the field during `editView`. This value is updated and saved by `onConfirm`.',
|
|
1726
|
+
isRequired: true
|
|
1727
|
+
}, {
|
|
1728
|
+
name: 'editButtonLabel',
|
|
1729
|
+
type: 'string',
|
|
1730
|
+
description: 'Accessibility label for button, which is used to enter `editView` from keyboard.'
|
|
1731
|
+
}, {
|
|
1732
|
+
name: 'editLabel',
|
|
1733
|
+
type: 'string',
|
|
1734
|
+
description: "Append 'edit' to the end of the button label (`editButtonLabel`)which allows\nusers of assistive technologies to understand the purpose of the button"
|
|
1735
|
+
}, {
|
|
1736
|
+
name: 'editView',
|
|
1737
|
+
type: '(fieldProps: ExtendedFieldProps<FieldValue>, ref: React.RefObject<any>) => React.ReactNode',
|
|
1738
|
+
description: 'The component shown when user is editing (when the inline edit is not in `readView`).',
|
|
1739
|
+
isRequired: true
|
|
1740
|
+
}, {
|
|
1741
|
+
name: 'hideActionButtons',
|
|
1742
|
+
type: 'boolean',
|
|
1743
|
+
description: 'Sets whether the confirm and cancel action buttons are displayed in the bottom right of the field.'
|
|
1744
|
+
}, {
|
|
1745
|
+
name: 'isEditing',
|
|
1746
|
+
type: 'boolean',
|
|
1747
|
+
description: 'Sets whether the component shows the `readView` or the `editView`. This is used to manage the state of the input in stateless inline edit.'
|
|
1748
|
+
}, {
|
|
1749
|
+
name: 'isRequired',
|
|
1750
|
+
type: 'boolean',
|
|
1751
|
+
description: 'Determines whether the input value can be confirmed as empty.'
|
|
1752
|
+
}, {
|
|
1753
|
+
name: 'keepEditViewOpenOnBlur',
|
|
1754
|
+
type: 'boolean',
|
|
1755
|
+
description: 'Sets the view when the element blurs and loses focus (this can happen when a user clicks away).\nWhen set to true, inline edit stays in `editView` when blurred.'
|
|
1756
|
+
}, {
|
|
1757
|
+
name: 'label',
|
|
1758
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1759
|
+
description: 'Label above the input field that communicates what value should be entered.'
|
|
1760
|
+
}, {
|
|
1761
|
+
name: 'onCancel',
|
|
1762
|
+
type: '() => void',
|
|
1763
|
+
description: 'Exits `editView` and switches back to `readView`. This is called when the cancel action button (x) is clicked.'
|
|
1764
|
+
}, {
|
|
1765
|
+
name: 'onConfirm',
|
|
1766
|
+
type: '(value: any, analyticsEvent: UIAnalyticsEvent) => void',
|
|
1767
|
+
description: 'Saves and confirms the value entered into the field. It exits `editView` and returns to `readView`.',
|
|
1768
|
+
isRequired: true
|
|
1769
|
+
}, {
|
|
1770
|
+
name: 'onEdit',
|
|
1771
|
+
type: '() => void',
|
|
1772
|
+
description: 'Handler called when readView is clicked.'
|
|
1773
|
+
}, {
|
|
1774
|
+
name: 'readView',
|
|
1775
|
+
type: '() => React.ReactNode',
|
|
1776
|
+
description: 'The component shown when not in `editView`. This is when the inline edit is read-only and not being edited.',
|
|
1777
|
+
isRequired: true
|
|
1778
|
+
}, {
|
|
1779
|
+
name: 'readViewFitContainerWidth',
|
|
1780
|
+
type: 'boolean',
|
|
1781
|
+
description: 'Determines whether the `readView` has 100% width within its container, or whether it fits the content.'
|
|
1782
|
+
}, {
|
|
1783
|
+
name: 'startWithEditViewOpen',
|
|
1784
|
+
type: 'boolean',
|
|
1785
|
+
description: 'Determines whether it begins in `editView` or `readView`. When set to true, `isEditing` begins as true and the inline edit\nstarts in `editView`.'
|
|
1786
|
+
}, {
|
|
1787
|
+
name: 'validate',
|
|
1788
|
+
type: '(value: any, formState: {}, fieldState: {}) => string | void | Promise<string | void>',
|
|
1789
|
+
description: 'Displays an inline dialog with a message when the field input is invalid. This is handled by `react-final-form`.'
|
|
1790
|
+
}]
|
|
1791
|
+
}, {
|
|
1792
|
+
name: 'InlineMessage',
|
|
1793
|
+
package: '@atlaskit/inline-message',
|
|
1794
|
+
description: 'In-context notification for more info, warning, error, or confirmation.',
|
|
1795
|
+
status: 'general-availability',
|
|
1796
|
+
usageGuidelines: ['Use for in-context notifications: more info, warning, error, confirmation', 'Icon/title/secondary can be used to reveal full message in a popup with context/links', 'Keep content to a maximum of five lines (truncation is not accessible)', 'Use Flag for minimal interaction; Banner for critical/system; Modal when immediate action is required'],
|
|
1797
|
+
contentGuidelines: ['Use clear, concise message text', 'Provide specific, actionable feedback', 'Use appropriate tone for message type', 'Keep messages focused and relevant', 'Warning: before action, empathy, offer alternative', 'Error: explain and next step; use "we" not "you"', 'Confirmation: confirm, then get out of the way', 'Information: inform, no action needed', 'Use clear, concise message text; keep focused and relevant'],
|
|
1798
|
+
accessibilityGuidelines: ['Keep to max five lines—truncation is not accessible', 'Recommend a title; icon-only is easily missed by screen readers', 'Use iconLabel when there is no title or when the icon adds context (e.g. error)', 'Ensure message content is announced by screen readers', 'Use appropriate message types and colors'],
|
|
1799
|
+
keywords: ['message', 'inline', 'feedback', 'status', 'alert'],
|
|
1800
|
+
category: 'feedback',
|
|
1801
|
+
examples: ['import InlineMessage from \'@atlaskit/inline-message\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<InlineMessage\n\t\t\ttitle="Success"\n\t\t\tsecondaryText="Your changes have been saved successfully."\n\t\t\tappearance="confirmation"\n\t\t/>\n\t\t<InlineMessage\n\t\t\ttitle="Warning"\n\t\t\tsecondaryText="This action cannot be undone."\n\t\t\tappearance="warning"\n\t\t/>\n\t\t<InlineMessage\n\t\t\ttitle="Error"\n\t\t\tsecondaryText="Something went wrong. Please try again."\n\t\t\tappearance="error"\n\t\t/>\n\t</>\n);\nexport default Examples;'],
|
|
1802
|
+
props: [{
|
|
1803
|
+
name: 'appearance',
|
|
1804
|
+
type: '"connectivity" | "confirmation" | "info" | "warning" | "error"',
|
|
1805
|
+
description: 'Set the icon to be used before the title. Options are: connectivity,\nconfirmation, info, warning, and error.',
|
|
1806
|
+
defaultValue: '"connectivity"'
|
|
1807
|
+
}, {
|
|
1808
|
+
name: 'children',
|
|
1809
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.ReactPortal',
|
|
1810
|
+
description: 'The elements to be displayed by the popup.'
|
|
1811
|
+
}, {
|
|
1812
|
+
name: 'fallbackPlacements',
|
|
1813
|
+
type: 'PopupPlacement[]',
|
|
1814
|
+
description: "This is a list of backup placements for the popup to try.\nWhen the preferred placement doesn't have enough space,\nthe modifier will test the ones provided in the list, and use the first suitable one.\nIf no fallback placements are suitable, it reverts back to the original placement."
|
|
1815
|
+
}, {
|
|
1816
|
+
name: 'iconLabel',
|
|
1817
|
+
type: 'string',
|
|
1818
|
+
description: 'Text to be used as the label for the button icon. You must use this to provide information for people who use assistive technology when there is no title and/or secondaryText.'
|
|
1819
|
+
}, {
|
|
1820
|
+
name: 'placement',
|
|
1821
|
+
type: 'AutoPlacement | BasePlacement | VariationPlacement',
|
|
1822
|
+
description: 'The placement to be passed to the popup. Determines where around\nthe text the dialog is displayed.',
|
|
1823
|
+
defaultValue: '"bottom-start"'
|
|
1824
|
+
}, {
|
|
1825
|
+
name: 'secondaryText',
|
|
1826
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.ReactPortal',
|
|
1827
|
+
description: 'Text to display second.',
|
|
1828
|
+
defaultValue: '""'
|
|
1829
|
+
}, {
|
|
1830
|
+
name: 'spacing',
|
|
1831
|
+
type: '"spacious" | "compact"',
|
|
1832
|
+
description: 'The spacing of the underlying icon button. Options are: spacious and compact.',
|
|
1833
|
+
defaultValue: '"spacious"'
|
|
1834
|
+
}, {
|
|
1835
|
+
name: 'title',
|
|
1836
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.ReactPortal',
|
|
1837
|
+
description: 'Text to display first, bolded for emphasis.',
|
|
1838
|
+
defaultValue: '""'
|
|
1839
|
+
}]
|
|
1840
|
+
}, {
|
|
1841
|
+
name: 'Link',
|
|
1842
|
+
package: '@atlaskit/link',
|
|
1843
|
+
description: 'A component for navigation links.',
|
|
1844
|
+
status: 'general-availability',
|
|
1845
|
+
usageGuidelines: ['Use for navigation to other pages or sections, downloads, or contact (phone, email)', 'Use default (underlined) with regular text so links are distinguishable', 'Use subtle appearance only when context already indicates it is a link (e.g. nav, breadcrumbs)', 'Use Link button when the link should look like a button', 'Do not open in a new window without warning (e.g. icon or explicit indication)'],
|
|
1846
|
+
contentGuidelines: ['Use clear, descriptive link text that describes the destination', 'Do not confuse with buttons—links navigate, buttons perform actions', "Avoid generic text like 'click here'"],
|
|
1847
|
+
accessibilityGuidelines: ['Do not use subtle appearance with regular body text—default has underline/color for distinguishability', 'Use subtle only when context already indicates it is a link (e.g. nav, breadcrumbs)', 'Provide clear link text that describes the destination', 'Use appropriate ARIA attributes for links', 'Ensure keyboard navigation support', 'Provide clear visual indicators for link state'],
|
|
1848
|
+
keywords: ['link', 'navigation', 'href', 'anchor', 'url'],
|
|
1849
|
+
category: 'navigation',
|
|
1850
|
+
examples: ['import Link from \'@atlaskit/link\';\nconst _default_1: React.JSX.Element[] = [\n\t<Link href="/dashboard">Go to Dashboard</Link>,\n\t<Link href="https://atlassian.design" target="_blank">\n\t\tAtlassian Design System\n\t</Link>,\n];\nexport default _default_1;'],
|
|
1851
|
+
props: [{
|
|
1852
|
+
name: 'appearance',
|
|
1853
|
+
type: '"default" | "subtle" | "inverse"',
|
|
1854
|
+
description: 'The appearance of the link. Defaults to `default`. A `subtle` appearance will render the link with a lighter color and no underline in resting state. Use `inverse` when rendering on bold backgrounds to ensure that the link is easily visible.'
|
|
1855
|
+
}, {
|
|
1856
|
+
name: 'children',
|
|
1857
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal'
|
|
1858
|
+
}, {
|
|
1859
|
+
name: 'href',
|
|
1860
|
+
type: 'string | RouterLinkConfig',
|
|
1861
|
+
description: 'Standard links can be provided as a string, which should be mapped to the\nunderlying router link component.\n\nAlternatively, you can provide an object for advanced link configurations\nby supplying the expected object type to the generic.\n\n@example\n```\nconst MyRouterLink = forwardRef(\n(\n {\n href,\n children,\n ...rest\n }: RouterLinkComponentProps<{\n href: string;\n replace: boolean;\n }>,\n ref: Ref<HTMLAnchorElement>,\n) => { ...\n```',
|
|
1862
|
+
isRequired: true
|
|
1863
|
+
}, {
|
|
1864
|
+
name: 'newWindowLabel',
|
|
1865
|
+
type: 'string',
|
|
1866
|
+
description: 'Override the default text to signify that a link opens in a new window.\nThis is appended to the `aria-label` attribute when the `target` prop is set to `_blank`.'
|
|
1867
|
+
}, {
|
|
1868
|
+
name: 'onClick',
|
|
1869
|
+
type: '(e: React.MouseEvent<HTMLAnchorElement, MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
1870
|
+
description: "Handler called on click. The second argument provides an Atlaskit UI analytics event that can be fired to a listening channel. See the ['analytics-next' package](https://atlaskit.atlassian.com/packages/analytics/analytics-next) documentation for more information."
|
|
1871
|
+
}]
|
|
1872
|
+
}, {
|
|
1873
|
+
name: 'AtlassianIcon',
|
|
1874
|
+
package: '@atlaskit/logo',
|
|
1875
|
+
description: 'A component for displaying the Atlassian icon.',
|
|
1876
|
+
status: 'general-availability',
|
|
1877
|
+
usageGuidelines: ['Use for Atlassian brand representation', 'Choose appropriate icon variants', 'Consider icon sizing and placement', 'Maintain brand consistency'],
|
|
1878
|
+
accessibilityGuidelines: ['Provide appropriate alt text for the icon', 'Ensure icon visibility and contrast', 'Consider icon sizing and placement', 'Use appropriate icon variants'],
|
|
1879
|
+
keywords: ['logo', 'brand', 'atlassian', 'identity', 'header'],
|
|
1880
|
+
category: 'brand',
|
|
1881
|
+
examples: ['import { AtlassianIcon } from \'@atlaskit/logo\';\nconst _default_1: React.JSX.Element[] = [\n\t<AtlassianIcon appearance="brand" shouldUseNewLogoDesign />,\n\t<AtlassianIcon appearance="neutral" shouldUseNewLogoDesign />,\n];\nexport default _default_1;'],
|
|
1882
|
+
props: [{
|
|
1883
|
+
name: 'appearance',
|
|
1884
|
+
type: '"brand" | "neutral" | "inverse"',
|
|
1885
|
+
description: 'Choice of logo appearance between 3 brand-approved color combinations that will be hooked up to design tokens and theming.'
|
|
1886
|
+
}, {
|
|
1887
|
+
name: 'label',
|
|
1888
|
+
type: 'string',
|
|
1889
|
+
description: "Accessible text to be used for screen readers (it's optional since the default props provide a label that matches the logo).",
|
|
1890
|
+
defaultValue: '"Atlassian"'
|
|
1891
|
+
}, {
|
|
1892
|
+
name: 'shouldUseNewLogoDesign',
|
|
1893
|
+
type: 'boolean',
|
|
1894
|
+
description: 'For logos that support it, enables the new logo design ahead of an upcoming feature flag roll-out.'
|
|
1895
|
+
}, {
|
|
1896
|
+
name: 'size',
|
|
1897
|
+
type: '"xxsmall" | "xsmall" | "small" | "medium" | "large" | "xlarge"',
|
|
1898
|
+
description: 'The size of the icon.',
|
|
1899
|
+
defaultValue: 'defaultLogoParams.size'
|
|
1900
|
+
}]
|
|
1901
|
+
}, {
|
|
1902
|
+
name: 'Lozenge',
|
|
1903
|
+
package: '@atlaskit/lozenge',
|
|
1904
|
+
description: 'A lozenge is a small visual indicator used to show status, category, or other short text labels.',
|
|
1905
|
+
status: 'general-availability',
|
|
1906
|
+
usageGuidelines: ['Subtle (default): for long tables and general use', 'Bold: use sparingly (e.g. Pipeline/Jira status)', 'Always combine color with a concise, accurate label', 'Use Badge for tallies/counts; use Tag for labels'],
|
|
1907
|
+
contentGuidelines: ['Use clear, concise text; use accurate labels (e.g. "Error", "Warning")', 'Do not use for long text—lozenge is not focusable and truncation at ~200px is not accessible', 'Ensure text is meaningful and descriptive', 'Use consistent terminology across lozenges'],
|
|
1908
|
+
accessibilityGuidelines: ['Do not rely on color alone; always pair with an accurate text label', 'Ensure sufficient color contrast for text readability', 'Do not use for long text—truncation is not accessible and lozenge is not focusable', 'Provide appropriate labels for screen readers', 'Consider color-blind users when choosing colors'],
|
|
1909
|
+
keywords: ['lozenge', 'badge', 'label', 'status', 'indicator', 'pill'],
|
|
1910
|
+
category: 'status-indicators',
|
|
1911
|
+
examples: ['import Lozenge from \'@atlaskit/lozenge\';\nexport default [\n\t<Lozenge appearance="success">Done</Lozenge>,\n\t<Lozenge appearance="inprogress" isBold>\n\t\tIn Progress\n\t</Lozenge>,\n];'],
|
|
1912
|
+
props: [{
|
|
1913
|
+
name: 'appearance',
|
|
1914
|
+
type: 'ThemeAppearance | "warning" | "danger" | "information" | "neutral" | "discovery" | AccentColor',
|
|
1915
|
+
description: 'The appearance type.\nThe appearance of the lozenge. Supports legacy semantic appearances and new semantic colors.\nAccent appearance values.'
|
|
1916
|
+
}, {
|
|
1917
|
+
name: 'children',
|
|
1918
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
1919
|
+
description: 'Elements to be rendered inside the lozenge. This should ideally be just a word or two.\nElements to be rendered inside the lozenge. This should ideally be just a word or two.'
|
|
1920
|
+
}, {
|
|
1921
|
+
name: 'maxWidth',
|
|
1922
|
+
type: 'string | number',
|
|
1923
|
+
description: 'max-width of lozenge container. Default to 200px.\nmax-width of lozenge container. Default to 200px.'
|
|
1924
|
+
}]
|
|
1925
|
+
}, {
|
|
1926
|
+
name: 'MenuGroup',
|
|
1927
|
+
package: '@atlaskit/menu',
|
|
1928
|
+
description: 'A list of options to action or navigate.',
|
|
1929
|
+
status: 'general-availability',
|
|
1930
|
+
usageGuidelines: ['Use for list of options to action or navigate', 'Button items = actions (e.g. Copy); Link items = navigate (e.g. Team Spaces)', 'Group related menu items together', 'Use clear section titles'],
|
|
1931
|
+
contentGuidelines: ['Use clear, descriptive menu item labels', 'Group related items logically', 'Use consistent terminology', 'Keep menu structure simple'],
|
|
1932
|
+
accessibilityGuidelines: ['Provide clear menu item labels', 'Use appropriate ARIA attributes', 'Ensure keyboard navigation with arrow keys', 'Provide clear section titles'],
|
|
1933
|
+
keywords: ['menu', 'group', 'navigation', 'section', 'items'],
|
|
1934
|
+
category: 'navigation',
|
|
1935
|
+
examples: ['import { ButtonItem, LinkItem, MenuGroup, Section } from \'@atlaskit/menu\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<MenuGroup spacing="cozy">\n\t\t\t<Section title="Navigation">\n\t\t\t\t<LinkItem href="/dashboard">Dashboard</LinkItem>\n\t\t\t\t<LinkItem href="/projects">Projects</LinkItem>\n\t\t\t\t<LinkItem href="/settings">Settings</LinkItem>\n\t\t\t</Section>\n\t\t</MenuGroup>\n\t\t<MenuGroup spacing="compact">\n\t\t\t<Section title="Actions">\n\t\t\t\t<ButtonItem>Create New</ButtonItem>\n\t\t\t\t<ButtonItem>Import</ButtonItem>\n\t\t\t\t<ButtonItem>Export</ButtonItem>\n\t\t\t</Section>\n\t\t\t<Section title="Help">\n\t\t\t\t<LinkItem href="/docs">Documentation</LinkItem>\n\t\t\t\t<LinkItem href="/support">Support</LinkItem>\n\t\t\t</Section>\n\t\t</MenuGroup>\n\t</>\n);\nexport default Examples;'],
|
|
1936
|
+
props: [{
|
|
1937
|
+
name: 'children',
|
|
1938
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1939
|
+
description: 'Children of the menu group.\nThis should generally be `Section` components.',
|
|
1940
|
+
isRequired: true
|
|
1941
|
+
}, {
|
|
1942
|
+
name: 'isLoading',
|
|
1943
|
+
type: 'boolean',
|
|
1944
|
+
description: 'Used this to tell assistive technologies that the menu group is loading.'
|
|
1945
|
+
}, {
|
|
1946
|
+
name: 'maxHeight',
|
|
1947
|
+
type: 'string | number',
|
|
1948
|
+
description: "Use this to constrain the menu group's height to a specific value.\nThis must be set if you want to have scrollable sections."
|
|
1949
|
+
}, {
|
|
1950
|
+
name: 'maxWidth',
|
|
1951
|
+
type: 'string | number',
|
|
1952
|
+
description: "Use this to constrain the menu group's maximum width to a specific value."
|
|
1953
|
+
}, {
|
|
1954
|
+
name: 'menuLabel',
|
|
1955
|
+
type: 'string',
|
|
1956
|
+
description: 'Provide an accessible label via `aria-label` for the menu element for assistive technology.'
|
|
1957
|
+
}, {
|
|
1958
|
+
name: 'minHeight',
|
|
1959
|
+
type: 'string | number',
|
|
1960
|
+
description: "Use this to constrain the menu group's minimum height to a specific value."
|
|
1961
|
+
}, {
|
|
1962
|
+
name: 'minWidth',
|
|
1963
|
+
type: 'string | number',
|
|
1964
|
+
description: "Use this to constrain the menu group's minimum width to a specific value."
|
|
1965
|
+
}, {
|
|
1966
|
+
name: 'onClick',
|
|
1967
|
+
type: '(event: React.MouseEvent<Element, MouseEvent> | React.KeyboardEvent<Element>) => void',
|
|
1968
|
+
description: 'Handler called when clicking on this element,\nor any children elements.\nUseful when needing to stop propagation of child events.'
|
|
1969
|
+
}, {
|
|
1970
|
+
name: 'role',
|
|
1971
|
+
type: 'string',
|
|
1972
|
+
description: 'Use this to override the accessibility role for the element.'
|
|
1973
|
+
}, {
|
|
1974
|
+
name: 'spacing',
|
|
1975
|
+
type: '"cozy" | "compact"',
|
|
1976
|
+
description: 'Configure the density of the menu group content.',
|
|
1977
|
+
defaultValue: '"cozy"'
|
|
1978
|
+
}]
|
|
1979
|
+
}, {
|
|
1980
|
+
name: 'Modal',
|
|
1981
|
+
package: '@atlaskit/modal-dialog',
|
|
1982
|
+
description: 'A modal dialog component for important content.',
|
|
1983
|
+
status: 'general-availability',
|
|
1984
|
+
usageGuidelines: ['Use for immediate task or critical/warning requiring a response; blocking until closed', 'Use sparingly—modals are invasive', 'One task per modal; limit interactions; no nested modals (inaccessible)', 'Anatomy: header (h1 title), close button, body, footer with primary + cancel/close', 'Footer: primary button on the right of secondary; multiple dismissal methods (close button, Esc, blanket click, Cancel/Close)', 'Use Popup for smaller info + controls; Spotlight for onboarding; Inline message for alert/action'],
|
|
1985
|
+
contentGuidelines: ['Use clear, descriptive titles', 'Primary button label should reflect the modal title', 'Use action verbs in button labels', 'Keep content focused on a single task or message', 'Use sentence case for all text'],
|
|
1986
|
+
accessibilityGuidelines: ['Modal must have a title: use title component, or titleId from useModal, or label (avoid if no visual title)', 'Close button is required (except rare cases—consult a11y team)', 'Do not rely on color alone for severity; provide accessible label for icons', 'Focus order: 1) close (or title or container), 2) first focusable, 3) secondary button, 4) primary, 5) return focus to trigger on close', 'Dismiss via: close button, Esc, click blanket, Cancel/Close in footer', 'Ensure modal content is announced by screen readers', 'Ensure keyboard navigation and escape key support', 'Maintain focus within modal when open'],
|
|
1987
|
+
keywords: ['modal', 'dialog', 'popup', 'overlay', 'focused', 'interaction', 'layer'],
|
|
1988
|
+
category: 'overlay',
|
|
1989
|
+
examples: ['import React, { Fragment, useCallback, useState } from \'react\';\nimport Button from \'@atlaskit/button/new\';\nimport Modal, {\n\tModalBody,\n\tModalFooter,\n\tModalHeader,\n\tModalTitle,\n\tModalTransition,\n} from \'@atlaskit/modal-dialog\';\nimport { Text } from \'@atlaskit/primitives/compiled\';\nexport default function Example(): React.JSX.Element {\n\tconst [isOpen, setIsOpen] = useState(false);\n\tconst openModal = useCallback(() => setIsOpen(true), []);\n\tconst closeModal = useCallback(() => setIsOpen(false), []);\n\treturn (\n\t\t<Fragment>\n\t\t\t<Button aria-haspopup="dialog" appearance="primary" onClick={openModal}>\n\t\t\t\tOpen modal\n\t\t\t</Button>\n\t\t\t<ModalTransition>\n\t\t\t\t{isOpen && (\n\t\t\t\t\t<Modal onClose={closeModal}>\n\t\t\t\t\t\t<ModalHeader hasCloseButton>\n\t\t\t\t\t\t\t<ModalTitle>Duplicate this page</ModalTitle>\n\t\t\t\t\t\t</ModalHeader>\n\t\t\t\t\t\t<ModalBody>\n\t\t\t\t\t\t\tDuplicating this page will make it a child page of{\' \'}\n\t\t\t\t\t\t\t<Text weight="bold">Search - user exploration</Text>, in the{\' \'}\n\t\t\t\t\t\t\t<Text weight="bold">Search & Smarts</Text> space.\n\t\t\t\t\t\t</ModalBody>\n\t\t\t\t\t\t<ModalFooter>\n\t\t\t\t\t\t\t<Button appearance="subtle" onClick={closeModal}>\n\t\t\t\t\t\t\t\tCancel\n\t\t\t\t\t\t\t</Button>\n\t\t\t\t\t\t\t<Button appearance="primary" onClick={closeModal}>\n\t\t\t\t\t\t\t\tDuplicate\n\t\t\t\t\t\t\t</Button>\n\t\t\t\t\t\t</ModalFooter>\n\t\t\t\t\t</Modal>\n\t\t\t\t)}\n\t\t\t</ModalTransition>\n\t\t</Fragment>\n\t);\n}'],
|
|
1990
|
+
props: [{
|
|
1991
|
+
name: 'children',
|
|
1992
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
1993
|
+
description: 'Contents of the modal dialog.'
|
|
1994
|
+
}, {
|
|
1995
|
+
name: 'focusLockAllowlist',
|
|
1996
|
+
type: '(element: HTMLElement) => boolean',
|
|
1997
|
+
description: 'Callback function which lets you allowlist nodes so they can be interacted with outside of the focus lock.\nReturn `true` if focus lock should handle element, `false` if not.'
|
|
1998
|
+
}, {
|
|
1999
|
+
name: 'height',
|
|
2000
|
+
type: 'string | number',
|
|
2001
|
+
description: 'Height of the modal dialog.\nWhen unset the modal dialog will grow to fill the viewport and then start overflowing its contents.'
|
|
2002
|
+
}, {
|
|
2003
|
+
name: 'isBlanketHidden',
|
|
2004
|
+
type: 'boolean',
|
|
2005
|
+
description: 'Will remove the blanket tinted background color.'
|
|
2006
|
+
}, {
|
|
2007
|
+
name: 'label',
|
|
2008
|
+
type: 'string',
|
|
2009
|
+
description: 'The label of the modal dialog that is announced to users of assistive\ntechnology. This should only be used if there is no modal title being\nassociated to your modal, either via using the modal title component or the\n`titleId` prop within the `useModal` context.'
|
|
2010
|
+
}, {
|
|
2011
|
+
name: 'onClose',
|
|
2012
|
+
type: '(e: KeyboardOrMouseEvent, analyticEvent: UIAnalyticsEvent) => void',
|
|
2013
|
+
description: 'Callback function called when the modal dialog is requesting to be closed.'
|
|
2014
|
+
}, {
|
|
2015
|
+
name: 'onCloseComplete',
|
|
2016
|
+
type: '(element: HTMLElement) => void',
|
|
2017
|
+
description: 'Callback function called when the modal dialog has finished closing.'
|
|
2018
|
+
}, {
|
|
2019
|
+
name: 'onOpenComplete',
|
|
2020
|
+
type: '(node: HTMLElement, isAppearing: boolean) => void',
|
|
2021
|
+
description: 'Callback function called when the modal dialog has finished opening.'
|
|
2022
|
+
}, {
|
|
2023
|
+
name: 'onStackChange',
|
|
2024
|
+
type: '(stackIndex: number) => void',
|
|
2025
|
+
description: 'Callback function called when the modal changes position in the stack.'
|
|
2026
|
+
}, {
|
|
2027
|
+
name: 'shouldCloseOnEscapePress',
|
|
2028
|
+
type: 'boolean',
|
|
2029
|
+
description: 'Calls `onClose` when pressing escape.'
|
|
2030
|
+
}, {
|
|
2031
|
+
name: 'shouldCloseOnOverlayClick',
|
|
2032
|
+
type: 'boolean',
|
|
2033
|
+
description: 'Calls `onClose` when clicking the blanket behind the modal dialog.'
|
|
2034
|
+
}, {
|
|
2035
|
+
name: 'shouldReturnFocus',
|
|
2036
|
+
type: 'boolean | React.RefObject<HTMLElement>',
|
|
2037
|
+
description: 'ReturnFocus controls what happens when the user exits\nfocus lock mode. If true, focus returns to the element that had focus before focus lock\nwas activated. If false, focus remains where it was when the FocusLock was deactivated.\nIf ref is passed, focus returns to that specific ref element.'
|
|
2038
|
+
}, {
|
|
2039
|
+
name: 'shouldScrollInViewport',
|
|
2040
|
+
type: 'boolean',
|
|
2041
|
+
description: 'Will set the scroll boundary to the viewport.\nIf set to false, the scroll boundary is set to the modal dialog body.'
|
|
2042
|
+
}, {
|
|
2043
|
+
name: 'stackIndex',
|
|
2044
|
+
type: 'number',
|
|
2045
|
+
description: "The stackIndex is a reference to the position (index) of the calling dialog in a modal dialog stack.\nNew modals added to the stack receive the highest stack index of 0. As more modals are added to the stack, their index is dynamically increased according to their new position.\nDon't alter the modal stack position using `stackIndex` in implementations of third-party libraries (e.g. AUI modal), it may lead to unpredictable bugs, especially if the third party library has its own focus lock.\nAdditionally, each modal in the stack gets a vertical offset based on `stackIndex` value."
|
|
2046
|
+
}, {
|
|
2047
|
+
name: 'width',
|
|
2048
|
+
type: 'string | number',
|
|
2049
|
+
description: 'Width of the modal dialog.\nThe recommended way to specify modal width is using named size options.'
|
|
2050
|
+
}]
|
|
2051
|
+
}, {
|
|
2052
|
+
name: 'PageHeader',
|
|
2053
|
+
package: '@atlaskit/page-header',
|
|
2054
|
+
description: 'A component for page headers.',
|
|
2055
|
+
status: 'general-availability',
|
|
2056
|
+
usageGuidelines: ['Use for consistent page header layout', 'Include breadcrumbs for navigation context', 'Provide relevant page actions', 'Use appropriate header hierarchy'],
|
|
2057
|
+
contentGuidelines: ['Use clear, descriptive page titles', 'Provide meaningful breadcrumb labels', 'Use action-oriented button text', 'Keep header content focused'],
|
|
2058
|
+
accessibilityGuidelines: ['Provide clear page titles', 'Use appropriate heading hierarchy', 'Ensure breadcrumb navigation is accessible', 'Provide clear action labels'],
|
|
2059
|
+
keywords: ['page', 'header', 'title', 'breadcrumbs', 'actions'],
|
|
2060
|
+
category: 'layout',
|
|
2061
|
+
examples: ['import Breadcrumbs, { BreadcrumbsItem } from \'@atlaskit/breadcrumbs\';\nimport Button from \'@atlaskit/button/new\';\nimport PageHeader from \'@atlaskit/page-header\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<PageHeader>Page Title</PageHeader>\n\t\t<PageHeader\n\t\t\tbreadcrumbs={\n\t\t\t\t<Breadcrumbs>\n\t\t\t\t\t<BreadcrumbsItem href="/" text="Home" />\n\t\t\t\t\t<BreadcrumbsItem href="/projects" text="Projects" />\n\t\t\t\t\t<BreadcrumbsItem text="Current Project" />\n\t\t\t\t</Breadcrumbs>\n\t\t\t}\n\t\t\tactions={<Button appearance="primary">Create</Button>}\n\t\t>\n\t\t\tProject Settings\n\t\t</PageHeader>\n\t\t<PageHeader\n\t\t\tactions={\n\t\t\t\t<>\n\t\t\t\t\t<Button appearance="subtle">Cancel</Button>\n\t\t\t\t\t<Button appearance="primary">Save Changes</Button>\n\t\t\t\t</>\n\t\t\t}\n\t\t>\n\t\t\tEdit Profile\n\t\t</PageHeader>\n\t</>\n);\nexport default Examples;'],
|
|
2062
|
+
props: [{
|
|
2063
|
+
name: 'actions',
|
|
2064
|
+
type: 'React.ReactElement<any, string | React.JSXElementConstructor<any>>',
|
|
2065
|
+
description: 'Contents of the action bar to be rendered next to the page title.'
|
|
2066
|
+
}, {
|
|
2067
|
+
name: 'bottomBar',
|
|
2068
|
+
type: 'React.ReactElement<any, string | React.JSXElementConstructor<any>>',
|
|
2069
|
+
description: 'Contents of the action bar to be rendered next to the page title. Typically a button group.'
|
|
2070
|
+
}, {
|
|
2071
|
+
name: 'breadcrumbs',
|
|
2072
|
+
type: 'React.ReactElement<any, string | React.JSXElementConstructor<any>>',
|
|
2073
|
+
description: 'Page breadcrumbs to be rendered above the title.'
|
|
2074
|
+
}, {
|
|
2075
|
+
name: 'children',
|
|
2076
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
2077
|
+
description: 'Contents of the bottom bar to be rendered below the page title. Typically contains a search bar and/or filters.'
|
|
2078
|
+
}, {
|
|
2079
|
+
name: 'disableTitleStyles',
|
|
2080
|
+
type: 'boolean',
|
|
2081
|
+
description: 'Content of the page title. The text wraps by default.',
|
|
2082
|
+
defaultValue: 'false'
|
|
2083
|
+
}, {
|
|
2084
|
+
name: 'id',
|
|
2085
|
+
type: 'string',
|
|
2086
|
+
description: 'Used as the ID of the inner h1 tag. This is exposed so the header text can be used as label of other elements by aria-labelledby.'
|
|
2087
|
+
}, {
|
|
2088
|
+
name: 'innerRef',
|
|
2089
|
+
type: '(element: HTMLElement) => void',
|
|
2090
|
+
description: 'Returns the inner ref to the DOM element of the title. This is exposed so the focus can be set.'
|
|
2091
|
+
}, {
|
|
2092
|
+
name: 'truncateTitle',
|
|
2093
|
+
type: 'boolean',
|
|
2094
|
+
description: 'Prevent the title from wrapping across lines. Avoid using this wherever possible, as truncation can make page headings inaccessible.',
|
|
2095
|
+
defaultValue: 'false'
|
|
2096
|
+
}]
|
|
2097
|
+
}, {
|
|
2098
|
+
name: 'Pagination',
|
|
2099
|
+
package: '@atlaskit/pagination',
|
|
2100
|
+
description: 'A component for pagination controls.',
|
|
2101
|
+
status: 'general-availability',
|
|
2102
|
+
usageGuidelines: ['Use for navigating through paged content', 'Provide clear page indicators', 'Consider total page count display', 'Use appropriate page limits'],
|
|
2103
|
+
contentGuidelines: ['Use clear page labels', 'Provide meaningful navigation text', 'Use consistent pagination terminology', 'Consider page context information'],
|
|
2104
|
+
accessibilityGuidelines: ['Provide clear page navigation labels', 'Use appropriate ARIA labels for pagination', 'Ensure keyboard navigation support', 'Announce page changes to screen readers'],
|
|
2105
|
+
keywords: ['pagination', 'pages', 'navigation', 'paging', 'controls'],
|
|
2106
|
+
category: 'navigation',
|
|
2107
|
+
examples: ["import Pagination from '@atlaskit/pagination';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Pagination\n\t\t\tpages={[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]}\n\t\t\tdefaultSelectedIndex={2}\n\t\t\tmax={7}\n\t\t\tonChange={(_event, page) => console.log('Page selected:', page)}\n\t\t/>\n\t\t<Pagination\n\t\t\tpages={['A', 'B', 'C', 'D']}\n\t\t\tdefaultSelectedIndex={1}\n\t\t\tonChange={(_event, page) => console.log('Letter page:', page)}\n\t\t/>\n\t</>\n);\nexport default Examples;"],
|
|
2108
|
+
props: [{
|
|
2109
|
+
name: 'components',
|
|
2110
|
+
type: '{ Page?: React.ElementType<any, keyof React.JSX.IntrinsicElements>; Previous?: React.ElementType<any, keyof React.JSX.IntrinsicElements>; Next?: React.ElementType<...>; }',
|
|
2111
|
+
description: 'Replace the built-in page, previous, next and/ or ellipsis component'
|
|
2112
|
+
}, {
|
|
2113
|
+
name: 'defaultSelectedIndex',
|
|
2114
|
+
type: 'number',
|
|
2115
|
+
description: 'Index of the page to be selected by default.'
|
|
2116
|
+
}, {
|
|
2117
|
+
name: 'getPageLabel',
|
|
2118
|
+
type: '(page: T, pageIndex: number) => string | number',
|
|
2119
|
+
description: 'Helper function to get text displayed on the page button. This is helpful in scenarios when page the page passed in is an object.'
|
|
2120
|
+
}, {
|
|
2121
|
+
name: 'isDisabled',
|
|
2122
|
+
type: 'boolean',
|
|
2123
|
+
description: 'Sets whether the Paginator is disabled'
|
|
2124
|
+
}, {
|
|
2125
|
+
name: 'label',
|
|
2126
|
+
type: 'string',
|
|
2127
|
+
description: 'The aria-label for the pagination nav wrapper.\nThe default value is "pagination".'
|
|
2128
|
+
}, {
|
|
2129
|
+
name: 'max',
|
|
2130
|
+
type: 'number',
|
|
2131
|
+
description: 'Maximum number of pages to be displayed in the pagination.'
|
|
2132
|
+
}, {
|
|
2133
|
+
name: 'nextLabel',
|
|
2134
|
+
type: 'string',
|
|
2135
|
+
description: 'The aria-label for the next button.\nThe default value is "next".'
|
|
2136
|
+
}, {
|
|
2137
|
+
name: 'onChange',
|
|
2138
|
+
type: '(event: React.SyntheticEvent<Element, Event>, page: T, analyticsEvent?: UIAnalyticsEvent) => void',
|
|
2139
|
+
description: 'The onChange handler which is called when the page is changed.'
|
|
2140
|
+
}, {
|
|
2141
|
+
name: 'pageLabel',
|
|
2142
|
+
type: 'string',
|
|
2143
|
+
description: 'The aria-label for the individual page numbers.\nThe default value is "page".\nThe page number is automatically appended to the pageLabel.\nFor Example, pageLabel="página" will render aria-label="página 1"\nas the label for page 1.'
|
|
2144
|
+
}, {
|
|
2145
|
+
name: 'pages',
|
|
2146
|
+
type: 'T[]',
|
|
2147
|
+
description: 'Array of the pages to display.',
|
|
2148
|
+
isRequired: true
|
|
2149
|
+
}, {
|
|
2150
|
+
name: 'previousLabel',
|
|
2151
|
+
type: 'string',
|
|
2152
|
+
description: 'The aria-label for the previous button.\nThe default value is "previous".'
|
|
2153
|
+
}, {
|
|
2154
|
+
name: 'renderEllipsis',
|
|
2155
|
+
type: '(arg: { key: string; from: number; to: number; }) => React.ReactElement<any, string | React.JSXElementConstructor<any>>',
|
|
2156
|
+
description: 'The react Node returned from the function is rendered instead of the default ellipsis node.'
|
|
2157
|
+
}, {
|
|
2158
|
+
name: 'selectedIndex',
|
|
2159
|
+
type: 'number',
|
|
2160
|
+
description: 'Index of the selected page. This will make this pagination controlled.'
|
|
2161
|
+
}]
|
|
2162
|
+
}, {
|
|
2163
|
+
name: 'Popper',
|
|
2164
|
+
package: '@atlaskit/popper',
|
|
2165
|
+
description: 'A component for positioning elements relative to other elements.',
|
|
2166
|
+
status: 'general-availability',
|
|
2167
|
+
usageGuidelines: ['Use for positioning overlays and tooltips', 'Consider positioning constraints', 'Handle responsive positioning', 'Use appropriate z-index management'],
|
|
2168
|
+
contentGuidelines: ['Ensure positioned content is accessible', 'Use appropriate positioning strategies', 'Consider content visibility and readability'],
|
|
2169
|
+
accessibilityGuidelines: ['Ensure proper positioning and visibility', 'Consider screen reader accessibility', 'Use appropriate ARIA attributes', 'Handle focus management'],
|
|
2170
|
+
keywords: ['popper', 'positioning', 'tooltip', 'popup', 'overlay'],
|
|
2171
|
+
category: 'utility',
|
|
2172
|
+
examples: ['import { Manager, Popper, Reference } from \'@atlaskit/popper\';\nexport default (): React.JSX.Element => (\n\t<Manager>\n\t\t<Reference>\n\t\t\t{({ ref }) => (\n\t\t\t\t<button ref={ref} type="button">\n\t\t\t\t\tReference element\n\t\t\t\t</button>\n\t\t\t)}\n\t\t</Reference>\n\t\t<Popper placement="right">\n\t\t\t{({ ref, style }) => (\n\t\t\t\t<div ref={ref} style={style} >\n\t\t\t\t\t↔ This text is a popper placed to the right\n\t\t\t\t</div>\n\t\t\t)}\n\t\t</Popper>\n\t</Manager>\n);'],
|
|
2173
|
+
props: [{
|
|
2174
|
+
name: 'children',
|
|
2175
|
+
type: '(childrenProps: PopperChildrenProps) => React.ReactNode',
|
|
2176
|
+
description: 'Returns the element to be positioned.',
|
|
2177
|
+
defaultValue: 'defaultChildrenFn'
|
|
2178
|
+
}, {
|
|
2179
|
+
name: 'modifiers',
|
|
2180
|
+
type: 'readonly Modifier<CustomModifiers, object>[]',
|
|
2181
|
+
description: 'Additional modifiers and modifier overwrites.'
|
|
2182
|
+
}, {
|
|
2183
|
+
name: 'offset',
|
|
2184
|
+
type: '[number, number]',
|
|
2185
|
+
description: 'Distance the popup should be offset from the reference in the format of [along, away] (units in px).\nDefaults to [0, 8] - which means the popup will be 8px away from the edge of the reference specified\nby the `placement` prop.',
|
|
2186
|
+
defaultValue: 'defaultOffset'
|
|
2187
|
+
}, {
|
|
2188
|
+
name: 'placement',
|
|
2189
|
+
type: 'AutoPlacement | BasePlacement | VariationPlacement',
|
|
2190
|
+
description: 'Which side of the Reference to show on.',
|
|
2191
|
+
defaultValue: '"bottom-start"'
|
|
2192
|
+
}, {
|
|
2193
|
+
name: 'referenceElement',
|
|
2194
|
+
type: 'HTMLElement | VirtualElement',
|
|
2195
|
+
description: 'Replacement reference element to position popper relative to.',
|
|
2196
|
+
defaultValue: 'undefined'
|
|
2197
|
+
}, {
|
|
2198
|
+
name: 'shouldFitViewport',
|
|
2199
|
+
type: 'boolean',
|
|
2200
|
+
description: 'Determines if the popper will have a `max-width` and `max-height` set to\nconstrain it to the viewport.',
|
|
2201
|
+
defaultValue: 'false'
|
|
2202
|
+
}, {
|
|
2203
|
+
name: 'strategy',
|
|
2204
|
+
type: '"fixed" | "absolute"',
|
|
2205
|
+
description: "Placement strategy used. Can be 'fixed' or 'absolute'",
|
|
2206
|
+
defaultValue: '"fixed"'
|
|
2207
|
+
}]
|
|
2208
|
+
}, {
|
|
2209
|
+
name: 'Popup',
|
|
2210
|
+
package: '@atlaskit/popup',
|
|
2211
|
+
description: 'A component for displaying popup content relative to a trigger element.',
|
|
2212
|
+
status: 'general-availability',
|
|
2213
|
+
usageGuidelines: ['Use for contextual content that appears on demand', 'Position appropriately relative to trigger', 'Consider dismissal behavior', 'Use appropriate content sizing'],
|
|
2214
|
+
contentGuidelines: ['Keep popup content focused and relevant', 'Use clear, concise content', 'Provide appropriate actions when needed', 'Consider content hierarchy'],
|
|
2215
|
+
accessibilityGuidelines: ['Provide appropriate focus management', 'Use clear trigger labels', 'Ensure keyboard navigation support', 'Provide escape key dismissal'],
|
|
2216
|
+
keywords: ['popup', 'overlay', 'floating', 'content', 'trigger'],
|
|
2217
|
+
category: 'overlay',
|
|
2218
|
+
examples: ["import React, { useState } from 'react';\nimport Button from '@atlaskit/button/new';\nimport Popup from '@atlaskit/popup';\nexport default (): React.JSX.Element => {\n\tconst [isOpen, setIsOpen] = useState(false);\n\treturn (\n\t\t<Popup\n\t\t\tcontent={() => <div>Basic popup content</div>}\n\t\t\tisOpen={isOpen}\n\t\t\tonClose={() => setIsOpen(false)}\n\t\t\tplacement=\"bottom-start\"\n\t\t\ttrigger={(triggerProps) => (\n\t\t\t\t<Button {...triggerProps} onClick={() => setIsOpen(!isOpen)}>\n\t\t\t\t\tToggle Popup\n\t\t\t\t</Button>\n\t\t\t)}\n\t\t\tshouldRenderToParent\n\t\t/>\n\t);\n};"],
|
|
2219
|
+
props: [{
|
|
2220
|
+
name: 'appearance',
|
|
2221
|
+
type: '"default" | "UNSAFE_modal-below-sm"',
|
|
2222
|
+
description: 'The "default" appearance is used for standard popups.\nThe "UNSAFE_modal-below-sm" appearance makes the popup appear as a modal when the viewport is smaller than "sm".'
|
|
2223
|
+
}, {
|
|
2224
|
+
name: 'autoFocus',
|
|
2225
|
+
type: 'boolean',
|
|
2226
|
+
description: 'This controls whether the popup takes focus when opening.\nThis changes the `popupComponent` component tabIndex to `null`.\nThe default is `true`.'
|
|
2227
|
+
}, {
|
|
2228
|
+
name: 'boundary',
|
|
2229
|
+
type: '"clippingParents" | HTMLElement',
|
|
2230
|
+
description: 'The boundary element that the popup will check for overflow.\nThe default is `"clippingParents"` which are parent scroll containers,\nbut can be set to any element.'
|
|
2231
|
+
}, {
|
|
2232
|
+
name: 'content',
|
|
2233
|
+
type: '(props: ContentProps) => ReactNode',
|
|
2234
|
+
description: 'Render props for content that is displayed inside the popup.',
|
|
2235
|
+
isRequired: true
|
|
2236
|
+
}, {
|
|
2237
|
+
name: 'fallbackPlacements',
|
|
2238
|
+
type: 'Placement[]',
|
|
2239
|
+
description: "This is a list of backup placements for the popup to try.\nWhen the preferred placement doesn't have enough space,\nthe modifier will test the ones provided in the list, and use the first suitable one.\nIf no fallback placements are suitable, it reverts back to the original placement."
|
|
2240
|
+
}, {
|
|
2241
|
+
name: 'id',
|
|
2242
|
+
type: 'string',
|
|
2243
|
+
description: 'ID that is assigned to the popup container element.'
|
|
2244
|
+
}, {
|
|
2245
|
+
name: 'isOpen',
|
|
2246
|
+
type: 'boolean',
|
|
2247
|
+
description: 'Use this to either show or hide the popup.\nWhen set to `false` the popup will not render anything to the DOM.',
|
|
2248
|
+
isRequired: true
|
|
2249
|
+
}, {
|
|
2250
|
+
name: 'label',
|
|
2251
|
+
type: 'string',
|
|
2252
|
+
description: 'Refers to an `aria-label` attribute. Sets an accessible name for the popup to announce it to users of assistive technology.\nUsage of either this, or the `titleId` attribute is strongly recommended.'
|
|
2253
|
+
}, {
|
|
2254
|
+
name: 'modifiers',
|
|
2255
|
+
type: 'Partial<Partial<Modifier<string, object>>>[]',
|
|
2256
|
+
description: 'Additional modifiers and modifier overwrites.\nfor more details - https://popper.js.org/docs/v1/#modifiers'
|
|
2257
|
+
}, {
|
|
2258
|
+
name: 'offset',
|
|
2259
|
+
type: '[number, number]',
|
|
2260
|
+
description: 'The distance the popup should be offset from the reference in the format of [along, away] (units in px).\nThe default is `[0, 8]`, which means the popup will be `8px` away from the edge of the reference specified\nby the `placement` prop.'
|
|
2261
|
+
}, {
|
|
2262
|
+
name: 'onClose',
|
|
2263
|
+
type: '(event: Event | MouseEvent<Element, globalThis.MouseEvent> | KeyboardEvent<Element>, currentLevel?: any) => void',
|
|
2264
|
+
description: "Handler that is called when the popup wants to close itself.\nThis can happen when:\n- the user clicks away from the popup\n- the user presses the escape key\n- the popup is closed programatically. In this case, the `event` argument will be `null`.\n\nYou'll want to use this to set open state accordingly, and then pump it back into the `isOpen` prop."
|
|
2265
|
+
}, {
|
|
2266
|
+
name: 'placement',
|
|
2267
|
+
type: 'AutoPlacement | BasePlacement | VariationPlacement',
|
|
2268
|
+
description: 'Placement of where the popup should be displayed relative to the trigger element.\nThe default is `"auto"`.'
|
|
2269
|
+
}, {
|
|
2270
|
+
name: 'popupComponent',
|
|
2271
|
+
type: 'ComponentType<PopupComponentProps> | ForwardRefExoticComponent<Omit<PopupComponentProps, "ref"> & RefAttributes<HTMLDivElement>>',
|
|
2272
|
+
description: 'The element that is shown when `isOpen` prop is `true`.\nThe result of the `content` prop will be placed as children here.\nThe default is an element with an elevation of `e200` with _no padding_.'
|
|
2273
|
+
}, {
|
|
2274
|
+
name: 'role',
|
|
2275
|
+
type: 'string',
|
|
2276
|
+
description: 'Use this to set the accessibility role for the popup.\nWe strongly recommend using only `menu` or `dialog`.\nMust be used along with `label` or `titleId`.'
|
|
2277
|
+
}, {
|
|
2278
|
+
name: 'rootBoundary',
|
|
2279
|
+
type: '"viewport" | "document"',
|
|
2280
|
+
description: 'The root boundary that the popup will check for overflow.\nThe default is `"viewport"` but it can be set to `"document"`.'
|
|
2281
|
+
}, {
|
|
2282
|
+
name: 'shouldDisableFocusLock',
|
|
2283
|
+
type: 'boolean',
|
|
2284
|
+
description: 'This makes the popup close on Tab key press. It will only work when `shouldRenderToParent` is `true`.\nThe default is `false`.'
|
|
2285
|
+
}, {
|
|
2286
|
+
name: 'shouldFitContainer',
|
|
2287
|
+
type: 'boolean',
|
|
2288
|
+
description: "This fits the popup width to its parent's width.\nWhen set to `true`, the trigger and popup elements will be wrapped in a `div` with `position: relative`.\nThe popup will be rendered as a sibling to the trigger element, and will be full width.\nThe default is `false`.\n\nThis fits the popup width to its parent's width.\nWhen set to `true`, the trigger and popup elements will be wrapped in a `div` with `position: relative`.\nThe popup will be rendered as a sibling to the trigger element, and will be full width.\nThe default is `false`."
|
|
2289
|
+
}, {
|
|
2290
|
+
name: 'shouldFitViewport',
|
|
2291
|
+
type: 'boolean',
|
|
2292
|
+
description: 'Determines if the popup will have a `max-width` and `max-height` set to\nconstrain it to the viewport.'
|
|
2293
|
+
}, {
|
|
2294
|
+
name: 'shouldFlip',
|
|
2295
|
+
type: 'boolean',
|
|
2296
|
+
description: "Allows the popup to be placed on the opposite side of its trigger if it doesn't fit in the viewport.\nThe default is `true`."
|
|
2297
|
+
}, {
|
|
2298
|
+
name: 'shouldRenderToParent',
|
|
2299
|
+
type: 'boolean',
|
|
2300
|
+
description: 'The root element where the popup should be rendered.\nDefaults to `false`.\nThe root element where the popup should be rendered.\nDefaults to `false`.'
|
|
2301
|
+
}, {
|
|
2302
|
+
name: 'shouldReturnFocus',
|
|
2303
|
+
type: 'boolean',
|
|
2304
|
+
description: 'This determines whether the popup trigger will be focused when the popup content closes.\nThe default is `true`.'
|
|
2305
|
+
}, {
|
|
2306
|
+
name: 'shouldUseCaptureOnOutsideClick',
|
|
2307
|
+
type: 'boolean',
|
|
2308
|
+
description: 'This controls if the event which handles clicks outside the popup is be bound with\n `capture: true`.'
|
|
2309
|
+
}, {
|
|
2310
|
+
name: 'strategy',
|
|
2311
|
+
type: '"absolute" | "fixed"',
|
|
2312
|
+
description: 'This controls the positioning strategy to use. Can vary between `absolute` and `fixed`.\nThe default is `fixed`.\nThis controls the positioning strategy to use. Can vary between `absolute` and `fixed`.\nThe default is `fixed`.'
|
|
2313
|
+
}, {
|
|
2314
|
+
name: 'titleId',
|
|
2315
|
+
type: 'string',
|
|
2316
|
+
description: 'Id referenced by the popup `aria-labelledby` attribute.\nUsage of either this, or the `label` attribute is strongly recommended.'
|
|
2317
|
+
}, {
|
|
2318
|
+
name: 'trigger',
|
|
2319
|
+
type: '(props: TriggerProps) => ReactNode',
|
|
2320
|
+
description: 'Render props used to anchor the popup to your content.\nMake this an interactive element,\nsuch as an `@atlaskit/button` component.',
|
|
2321
|
+
isRequired: true
|
|
2322
|
+
}, {
|
|
2323
|
+
name: 'xcss',
|
|
2324
|
+
type: 'false | (XCSSValue<"paddingBlockEnd" | "paddingBlockStart" | "paddingInlineEnd" | "paddingInlineStart" | "width" | "padding" | "paddingBlock" | "paddingInline", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2325
|
+
description: 'Bounded style overrides.'
|
|
2326
|
+
}, {
|
|
2327
|
+
name: 'zIndex',
|
|
2328
|
+
type: 'number',
|
|
2329
|
+
description: 'Z-index that the popup should be displayed in.\nThis is passed to the portal component.\nThe default is 400.'
|
|
2330
|
+
}]
|
|
2331
|
+
}, {
|
|
2332
|
+
name: 'Portal',
|
|
2333
|
+
package: '@atlaskit/portal',
|
|
2334
|
+
description: 'A component for rendering content outside the normal DOM hierarchy.',
|
|
2335
|
+
status: 'general-availability',
|
|
2336
|
+
usageGuidelines: ['Use for rendering content outside normal DOM', 'Consider z-index and positioning', 'Handle focus management appropriately', 'Use for modals and overlays'],
|
|
2337
|
+
contentGuidelines: ['Ensure portaled content is accessible', 'Consider content context and purpose', 'Use appropriate portal placement'],
|
|
2338
|
+
accessibilityGuidelines: ['Ensure proper focus management', 'Consider screen reader accessibility', 'Use appropriate ARIA attributes', 'Handle keyboard navigation'],
|
|
2339
|
+
keywords: ['portal', 'render', 'dom', 'mount', 'teleport'],
|
|
2340
|
+
category: 'utility',
|
|
2341
|
+
examples: ["import Portal from '@atlaskit/portal';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Portal>\n\t\t\t<div>This content is rendered in a portal</div>\n\t\t</Portal>\n\t\t<Portal zIndex={1000}>\n\t\t\t<div>This content has a custom z-index</div>\n\t\t</Portal>\n\t</>\n);\nexport default Examples;"],
|
|
2342
|
+
props: [{
|
|
2343
|
+
name: 'children',
|
|
2344
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
2345
|
+
isRequired: true
|
|
2346
|
+
}, {
|
|
2347
|
+
name: 'mountStrategy',
|
|
2348
|
+
type: '"effect" | "layoutEffect"',
|
|
2349
|
+
description: 'Specify the mount strategy: useEffect or useLayoutEffect.\nNote: UseLayoutEffect can lead to performance issues and is discouraged.',
|
|
2350
|
+
defaultValue: '"effect"'
|
|
2351
|
+
}, {
|
|
2352
|
+
name: 'zIndex',
|
|
2353
|
+
type: 'string | number',
|
|
2354
|
+
defaultValue: '0'
|
|
2355
|
+
}]
|
|
2356
|
+
}, {
|
|
2357
|
+
name: 'Anchor',
|
|
2358
|
+
package: '@atlaskit/primitives',
|
|
2359
|
+
description: 'A primitive Anchor component for navigation links with compiled styling support.',
|
|
2360
|
+
status: 'general-availability',
|
|
2361
|
+
usageGuidelines: ['Use for navigation links to other pages or sections', 'Leverage compiled styling for performance', 'Use appropriate link styling and states', 'Consider link behavior and target attributes'],
|
|
2362
|
+
contentGuidelines: ['Use clear, descriptive link text', 'Maintain consistent link styling', 'Consider link context and destination'],
|
|
2363
|
+
accessibilityGuidelines: ['Provide clear link text that describes the destination', 'Use appropriate ARIA attributes for links', 'Ensure keyboard navigation support', 'Provide clear visual indicators for link state', 'Use descriptive link text for screen readers'],
|
|
2364
|
+
keywords: ['anchor', 'link', 'navigation', 'href', 'url', 'primitive', 'compiled'],
|
|
2365
|
+
category: 'primitive',
|
|
2366
|
+
examples: ['import { Anchor } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Anchor href="https://atlassian.design">Atlassian Design System</Anchor>,\n\t<Anchor href="/docs" target="_blank">\n\t\tOpen docs\n\t</Anchor>,\n];\nexport default _default_1;'],
|
|
2367
|
+
props: [{
|
|
2368
|
+
name: 'children',
|
|
2369
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.ReactPortal',
|
|
2370
|
+
description: 'Elements to be rendered inside the Anchor.'
|
|
2371
|
+
}, {
|
|
2372
|
+
name: 'href',
|
|
2373
|
+
type: 'string | RouterLinkConfig',
|
|
2374
|
+
description: 'Standard links can be provided as a string, which should be mapped to the\nunderlying router link component.\n\nAlternatively, you can provide an object for advanced link configurations\nby supplying the expected object type to the generic.\n\n@example\n```\nconst MyRouterLink = forwardRef(\n(\n {\n href,\n children,\n ...rest\n }: RouterLinkComponentProps<{\n href: string;\n replace: boolean;\n }>,\n ref: Ref<HTMLAnchorElement>,\n) => { ...\n```',
|
|
2375
|
+
isRequired: true
|
|
2376
|
+
}, {
|
|
2377
|
+
name: 'newWindowLabel',
|
|
2378
|
+
type: 'string',
|
|
2379
|
+
description: 'Override the default text to signify that a link opens in a new window.\nThis is appended to the `aria-label` attribute when the `target` prop is set to `_blank`.'
|
|
2380
|
+
}, {
|
|
2381
|
+
name: 'onClick',
|
|
2382
|
+
type: '(e: React.MouseEvent<HTMLAnchorElement, MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
2383
|
+
description: "Handler called on click. The second argument provides an Atlaskit UI analytics event that can be fired to a listening channel. See the ['analytics-next' package](https://atlaskit.atlassian.com/packages/analytics/analytics-next) documentation for more information."
|
|
2384
|
+
}, {
|
|
2385
|
+
name: 'xcss',
|
|
2386
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "translate" | "content" | "color" | "grid" | "flex" | "fill" | "stroke" | "all" | "bottom" | "left" | "right" | "top" | ... 485 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2387
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2388
|
+
}]
|
|
2389
|
+
}, {
|
|
2390
|
+
name: 'Bleed',
|
|
2391
|
+
package: '@atlaskit/primitives',
|
|
2392
|
+
description: 'A primitive Bleed component for extending content beyond container boundaries with compiled styling support.',
|
|
2393
|
+
status: 'general-availability',
|
|
2394
|
+
usageGuidelines: ['Use for extending content beyond container margins', 'Leverage compiled styling for performance', 'Use appropriate bleed directions and amounts', 'Consider responsive behavior and container constraints'],
|
|
2395
|
+
contentGuidelines: ['Use for appropriate layout bleeding', 'Maintain consistent bleeding patterns', 'Consider content hierarchy and visual flow'],
|
|
2396
|
+
keywords: ['bleed', 'layout', 'margin', 'spacing', 'edge', 'primitive', 'compiled'],
|
|
2397
|
+
category: 'primitive',
|
|
2398
|
+
examples: ['import { Bleed, Box } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Box padding="space.200" backgroundColor="color.background.neutral.subtle">\n\t\t<Bleed inline="space.100">\n\t\t\t<Box backgroundColor="color.background.brand.bold" padding="space.100">\n\t\t\t\tBleed content\n\t\t\t</Box>\n\t\t</Bleed>\n\t</Box>,\n];\nexport default _default_1;'],
|
|
2399
|
+
props: [{
|
|
2400
|
+
name: 'all',
|
|
2401
|
+
type: '"space.025" | "space.050" | "space.100" | "space.150" | "space.200"',
|
|
2402
|
+
description: 'Bleed along both axis.'
|
|
2403
|
+
}, {
|
|
2404
|
+
name: 'block',
|
|
2405
|
+
type: '"space.025" | "space.050" | "space.100" | "space.150" | "space.200"',
|
|
2406
|
+
description: 'Bleed along the block axis'
|
|
2407
|
+
}, {
|
|
2408
|
+
name: 'children',
|
|
2409
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2410
|
+
description: 'Elements to be rendered inside the Flex.',
|
|
2411
|
+
isRequired: true
|
|
2412
|
+
}, {
|
|
2413
|
+
name: 'inline',
|
|
2414
|
+
type: '"space.025" | "space.050" | "space.100" | "space.150" | "space.200"',
|
|
2415
|
+
description: 'Bleed along the inline axis.'
|
|
2416
|
+
}, {
|
|
2417
|
+
name: 'role',
|
|
2418
|
+
type: 'string',
|
|
2419
|
+
description: 'Accessible role.'
|
|
2420
|
+
}, {
|
|
2421
|
+
name: 'xcss',
|
|
2422
|
+
type: 'false | (XCSSValue<"all" | "flex" | "grid" | "fill" | "stroke" | "bottom" | "left" | "right" | "top" | "clip" | "overlay" | "accentColor" | "alignContent" | "alignItems" | "alignSelf" | ... 486 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2423
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2424
|
+
}]
|
|
2425
|
+
}, {
|
|
2426
|
+
name: 'Box',
|
|
2427
|
+
package: '@atlaskit/primitives',
|
|
2428
|
+
description: 'A primitive Box component for layout and container purposes with compiled styling support.',
|
|
2429
|
+
status: 'general-availability',
|
|
2430
|
+
usageGuidelines: ['Use for basic layout and container needs', 'Leverage compiled styling for performance', 'Use appropriate spacing and layout props', 'Consider semantic HTML when possible'],
|
|
2431
|
+
contentGuidelines: ['Use for appropriate layout purposes', 'Maintain consistent spacing and layout patterns', 'Consider accessibility and semantic structure'],
|
|
2432
|
+
keywords: ['box', 'container', 'div', 'layout', 'primitive', 'compiled'],
|
|
2433
|
+
category: 'primitive',
|
|
2434
|
+
examples: ["/**\n * @jsxRuntime classic\n * @jsx jsx\n */\nimport { cssMap, jsx } from '@atlaskit/css';\nimport { Box } from '@atlaskit/primitives/compiled';\nimport { token } from '@atlaskit/tokens';\nconst styles = cssMap({\n\tbox: {\n\t\tpaddingTop: token('space.200'),\n\t\tpaddingRight: token('space.200'),\n\t\tpaddingBottom: token('space.200'),\n\t\tpaddingLeft: token('space.200'),\n\t\tbackgroundColor: token('color.background.neutral.subtle'),\n\t},\n});\nconst _default_1: JSX.Element[] = [\n\t<Box padding=\"space.200\" backgroundColor=\"color.background.neutral.subtle\">\n\t\tBasic box\n\t</Box>,\n\t<Box xcss={styles.box}>Styled box</Box>,\n];\nexport default _default_1;"],
|
|
2435
|
+
props: [{
|
|
2436
|
+
name: 'as',
|
|
2437
|
+
type: '"object" | "style" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "canvas" | "caption" | "center" | ... 98 more ... | "set"',
|
|
2438
|
+
description: "The DOM element to render as the Box.\n- This cannot be any SVG-related element such as `'svg'`, `'animate', `'circle'`, and many more\n- This cannot be a `'a'` (use the `Anchor` primitive instead)\n- This cannot be a `'button'` (use the `Anchor` primitive instead)",
|
|
2439
|
+
defaultValue: "'div'"
|
|
2440
|
+
}, {
|
|
2441
|
+
name: 'backgroundColor',
|
|
2442
|
+
type: '"utility.elevation.surface.current" | "elevation.surface" | "elevation.surface.overlay" | "elevation.surface.raised" | "elevation.surface.sunken" | "color.background.accent.lime.subtlest" | ... 205 more ... | "elevation.surface.raised.pressed"',
|
|
2443
|
+
description: 'Token representing background color with a built-in fallback value.'
|
|
2444
|
+
}, {
|
|
2445
|
+
name: 'xcss',
|
|
2446
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "height" | "width" | "translate" | "content" | "color" | "border" | "alignmentBaseline" | "baselineShift" | "clip" | ... 487 more ... | "viewTimeline", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2447
|
+
description: "Apply a subset of permitted styles powered by Atlassian Design System design tokens.\nIt's preferred you do not use `background` in `xcss` or `cssMap()` and instead use `props.backgroundColor` for surface awareness."
|
|
2448
|
+
}]
|
|
2449
|
+
}, {
|
|
2450
|
+
name: 'Flex',
|
|
2451
|
+
package: '@atlaskit/primitives',
|
|
2452
|
+
description: 'A primitive Flex component for flexbox layout with compiled styling support.',
|
|
2453
|
+
status: 'general-availability',
|
|
2454
|
+
usageGuidelines: ['Use for flexbox layout needs', 'Leverage compiled styling for performance', 'Use appropriate flex properties and alignment', 'Consider responsive behavior'],
|
|
2455
|
+
contentGuidelines: ['Use for appropriate flex layout', 'Maintain consistent flex patterns', 'Consider content alignment and distribution'],
|
|
2456
|
+
keywords: ['flex', 'layout', 'flexbox', 'alignment', 'primitive', 'compiled'],
|
|
2457
|
+
category: 'primitive',
|
|
2458
|
+
examples: ['import { Box, Flex } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Flex gap="space.100" alignItems="center">\n\t\t<Box backgroundColor="color.background.accent.blue.subtle" padding="space.100">\n\t\t\tItem 1\n\t\t</Box>\n\t\t<Box backgroundColor="color.background.accent.green.subtle" padding="space.100">\n\t\t\tItem 2\n\t\t</Box>\n\t</Flex>,\n];\nexport default _default_1;'],
|
|
2459
|
+
props: [{
|
|
2460
|
+
name: 'alignItems',
|
|
2461
|
+
type: '"center" | "start" | "stretch" | "end" | "baseline"',
|
|
2462
|
+
description: 'Used to align children along the cross axis.'
|
|
2463
|
+
}, {
|
|
2464
|
+
name: 'as',
|
|
2465
|
+
type: '"div" | "dl" | "li" | "ol" | "span" | "ul"',
|
|
2466
|
+
description: 'The DOM element to render as the Flex. Defaults to `div`.'
|
|
2467
|
+
}, {
|
|
2468
|
+
name: 'children',
|
|
2469
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2470
|
+
description: 'Elements to be rendered inside the Flex.',
|
|
2471
|
+
isRequired: true
|
|
2472
|
+
}, {
|
|
2473
|
+
name: 'columnGap',
|
|
2474
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2475
|
+
description: 'Represents the space between each child.'
|
|
2476
|
+
}, {
|
|
2477
|
+
name: 'direction',
|
|
2478
|
+
type: '"column" | "row"',
|
|
2479
|
+
description: 'Represents the flex direction property of CSS flexbox.'
|
|
2480
|
+
}, {
|
|
2481
|
+
name: 'gap',
|
|
2482
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2483
|
+
description: 'Represents the space between each child.'
|
|
2484
|
+
}, {
|
|
2485
|
+
name: 'justifyContent',
|
|
2486
|
+
type: '"center" | "start" | "space-around" | "space-between" | "space-evenly" | "stretch" | "end"',
|
|
2487
|
+
description: 'Used to align children along the main axis.'
|
|
2488
|
+
}, {
|
|
2489
|
+
name: 'role',
|
|
2490
|
+
type: 'string',
|
|
2491
|
+
description: 'Accessible role.'
|
|
2492
|
+
}, {
|
|
2493
|
+
name: 'rowGap',
|
|
2494
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2495
|
+
description: 'Represents the space between each child.'
|
|
2496
|
+
}, {
|
|
2497
|
+
name: 'wrap',
|
|
2498
|
+
type: '"wrap" | "nowrap"',
|
|
2499
|
+
description: 'Represents the flex wrap property of CSS flexbox.'
|
|
2500
|
+
}, {
|
|
2501
|
+
name: 'xcss',
|
|
2502
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "justifyContent" | "alignItems" | "columnGap" | "gap" | "rowGap" | "direction" | "flex" | "grid" | "fill" | "stroke" | ... 487 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2503
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2504
|
+
}]
|
|
2505
|
+
}, {
|
|
2506
|
+
name: 'Focusable',
|
|
2507
|
+
package: '@atlaskit/primitives',
|
|
2508
|
+
description: 'A primitive Focusable component for keyboard navigation and focus management with compiled styling support.',
|
|
2509
|
+
status: 'general-availability',
|
|
2510
|
+
usageGuidelines: ['Use for elements that need keyboard focus', 'Leverage compiled styling for performance', 'Use appropriate focus management', 'Consider keyboard navigation patterns'],
|
|
2511
|
+
contentGuidelines: ['Use for appropriate focusable content', 'Maintain consistent focus patterns', 'Consider keyboard navigation flow'],
|
|
2512
|
+
accessibilityGuidelines: ['Provide clear focus indicators', 'Use appropriate tab order and navigation', 'Ensure keyboard accessibility', 'Provide clear visual feedback for focus state', 'Use appropriate ARIA attributes'],
|
|
2513
|
+
keywords: ['focusable', 'focus', 'keyboard', 'navigation', 'accessibility', 'primitive', 'compiled'],
|
|
2514
|
+
category: 'primitive',
|
|
2515
|
+
examples: ['import { Box, Focusable } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Focusable>\n\t\t<Box padding="space.200" backgroundColor="color.background.neutral.subtle">\n\t\t\tFocusable content\n\t\t</Box>\n\t</Focusable>,\n];\nexport default _default_1;'],
|
|
2516
|
+
props: [{
|
|
2517
|
+
name: 'as',
|
|
2518
|
+
type: '"symbol" | "object" | "style" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "canvas" | "caption" | ... 156 more ... | "view"',
|
|
2519
|
+
description: 'The DOM element to render as the Focusable element.',
|
|
2520
|
+
defaultValue: "'button'"
|
|
2521
|
+
}, {
|
|
2522
|
+
name: 'children',
|
|
2523
|
+
type: 'string | number | boolean | ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.ReactPortal'
|
|
2524
|
+
}, {
|
|
2525
|
+
name: 'isInset',
|
|
2526
|
+
type: 'boolean',
|
|
2527
|
+
description: 'Controls whether the focus ring should be applied around or within the composed element.'
|
|
2528
|
+
}, {
|
|
2529
|
+
name: 'xcss',
|
|
2530
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "color" | "height" | "width" | "alignmentBaseline" | "baselineShift" | "clip" | "clipRule" | "colorInterpolation" | ... 489 more ... | "viewTimeline", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2531
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2532
|
+
}]
|
|
2533
|
+
}, {
|
|
2534
|
+
name: 'Grid',
|
|
2535
|
+
package: '@atlaskit/primitives',
|
|
2536
|
+
description: 'A primitive Grid component for CSS Grid layout with compiled styling support.',
|
|
2537
|
+
status: 'general-availability',
|
|
2538
|
+
usageGuidelines: ['Use for CSS Grid layout needs', 'Leverage compiled styling for performance', 'Use appropriate grid properties and alignment', 'Consider responsive behavior'],
|
|
2539
|
+
contentGuidelines: ['Use for appropriate grid layout', 'Maintain consistent grid patterns', 'Consider content alignment and distribution'],
|
|
2540
|
+
keywords: ['grid', 'layout', 'css-grid', 'alignment', 'primitive', 'compiled'],
|
|
2541
|
+
category: 'primitive',
|
|
2542
|
+
examples: ['import { cssMap } from \'@atlaskit/css\';\nimport { Box, Grid } from \'@atlaskit/primitives/compiled\';\nconst styles = cssMap({\n\tgrid: {\n\t\tgridTemplateColumns: \'1fr 1fr\',\n\t},\n});\nconst _default_1: React.JSX.Element[] = [\n\t<Grid gap="space.200" xcss={styles.grid}>\n\t\t<Box backgroundColor="color.background.accent.blue.subtle" padding="space.200">\n\t\t\tGrid item 1\n\t\t</Box>\n\t\t<Box backgroundColor="color.background.accent.green.subtle" padding="space.200">\n\t\t\tGrid item 2\n\t\t</Box>\n\t</Grid>,\n];\nexport default _default_1;'],
|
|
2543
|
+
props: [{
|
|
2544
|
+
name: 'alignContent',
|
|
2545
|
+
type: '"center" | "start" | "space-around" | "space-between" | "space-evenly" | "stretch" | "end"',
|
|
2546
|
+
description: 'Used to align the grid along the block axis.'
|
|
2547
|
+
}, {
|
|
2548
|
+
name: 'alignItems',
|
|
2549
|
+
type: '"center" | "start" | "stretch" | "end" | "baseline"',
|
|
2550
|
+
description: 'Used to align children along the block axis.'
|
|
2551
|
+
}, {
|
|
2552
|
+
name: 'as',
|
|
2553
|
+
type: '"div" | "ol" | "span" | "ul"',
|
|
2554
|
+
description: 'The DOM element to render as the Flex. Defaults to `div`.'
|
|
2555
|
+
}, {
|
|
2556
|
+
name: 'autoFlow',
|
|
2557
|
+
type: '"column" | "row" | "dense" | "row dense" | "column dense"',
|
|
2558
|
+
description: 'Specifies how auto-placed items get flowed into the grid. CSS `grid-auto-flow`.'
|
|
2559
|
+
}, {
|
|
2560
|
+
name: 'children',
|
|
2561
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2562
|
+
description: 'Elements to be rendered inside the grid. Required as a grid without children should not be a grid.',
|
|
2563
|
+
isRequired: true
|
|
2564
|
+
}, {
|
|
2565
|
+
name: 'columnGap',
|
|
2566
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2567
|
+
description: 'Represents the space between each column.'
|
|
2568
|
+
}, {
|
|
2569
|
+
name: 'gap',
|
|
2570
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2571
|
+
description: 'Represents the space between each child across both axes.'
|
|
2572
|
+
}, {
|
|
2573
|
+
name: 'id',
|
|
2574
|
+
type: 'string',
|
|
2575
|
+
description: 'HTML id attrubute.'
|
|
2576
|
+
}, {
|
|
2577
|
+
name: 'justifyContent',
|
|
2578
|
+
type: '"center" | "start" | "space-around" | "space-between" | "space-evenly" | "stretch" | "end"',
|
|
2579
|
+
description: 'Used to align children along the inline axis.'
|
|
2580
|
+
}, {
|
|
2581
|
+
name: 'role',
|
|
2582
|
+
type: 'string',
|
|
2583
|
+
description: 'Accessible role.'
|
|
2584
|
+
}, {
|
|
2585
|
+
name: 'rowGap',
|
|
2586
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2587
|
+
description: 'Represents the space between each row.'
|
|
2588
|
+
}, {
|
|
2589
|
+
name: 'xcss',
|
|
2590
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "justifyContent" | "justifyItems" | "alignItems" | "alignContent" | "columnGap" | "gap" | "rowGap" | "flex" | "grid" | ... 488 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2591
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2592
|
+
}]
|
|
2593
|
+
}, {
|
|
2594
|
+
name: 'Inline',
|
|
2595
|
+
package: '@atlaskit/primitives',
|
|
2596
|
+
description: 'A primitive Inline component for horizontal layout with consistent spacing.',
|
|
2597
|
+
status: 'general-availability',
|
|
2598
|
+
usageGuidelines: ['Use for horizontal layout needs', 'Leverage compiled styling for performance', 'Use appropriate spacing and alignment props', 'Consider wrapping behavior'],
|
|
2599
|
+
contentGuidelines: ['Use for appropriate horizontal grouping', 'Maintain consistent spacing patterns', 'Consider content flow and readability'],
|
|
2600
|
+
keywords: ['inline', 'layout', 'horizontal', 'spacing', 'primitive', 'compiled'],
|
|
2601
|
+
category: 'primitive',
|
|
2602
|
+
examples: ['import AddIcon from \'@atlaskit/icon/core/add\';\nimport { Inline, Text } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Inline space="space.100">\n\t\t<AddIcon label="Add item" />\n\t\t<Text>Add item</Text>\n\t</Inline>,\n];\nexport default _default_1;'],
|
|
2603
|
+
props: [{
|
|
2604
|
+
name: 'alignBlock',
|
|
2605
|
+
type: '"center" | "start" | "end" | "baseline" | "stretch"',
|
|
2606
|
+
description: 'Used to align children along the block axis (typically vertical).'
|
|
2607
|
+
}, {
|
|
2608
|
+
name: 'alignInline',
|
|
2609
|
+
type: '"center" | "start" | "end" | "stretch"',
|
|
2610
|
+
description: 'Used to align children along the inline axis (typically horizontal).'
|
|
2611
|
+
}, {
|
|
2612
|
+
name: 'as',
|
|
2613
|
+
type: '"div" | "dl" | "li" | "ol" | "span" | "ul"',
|
|
2614
|
+
description: 'The DOM element to render as the Inline. Defaults to `div`.'
|
|
2615
|
+
}, {
|
|
2616
|
+
name: 'children',
|
|
2617
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2618
|
+
description: 'Elements to be rendered inside the Inline.',
|
|
2619
|
+
isRequired: true
|
|
2620
|
+
}, {
|
|
2621
|
+
name: 'grow',
|
|
2622
|
+
type: '"hug" | "fill"',
|
|
2623
|
+
description: 'Used to set whether the container should grow to fill the available space.'
|
|
2624
|
+
}, {
|
|
2625
|
+
name: 'role',
|
|
2626
|
+
type: 'string',
|
|
2627
|
+
description: 'Accessible role.'
|
|
2628
|
+
}, {
|
|
2629
|
+
name: 'rowSpace',
|
|
2630
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2631
|
+
description: 'Represents the space between rows when content wraps.\nUsed to override the `space` value in between rows.'
|
|
2632
|
+
}, {
|
|
2633
|
+
name: 'separator',
|
|
2634
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2635
|
+
description: 'Renders a separator string between each child. Avoid using `separator="•"` when `as="ul" | "ol" | "dl"` to preserve proper list semantics.'
|
|
2636
|
+
}, {
|
|
2637
|
+
name: 'shouldWrap',
|
|
2638
|
+
type: 'boolean',
|
|
2639
|
+
description: 'Used to set whether children are forced onto one line or will wrap onto multiple lines.'
|
|
2640
|
+
}, {
|
|
2641
|
+
name: 'space',
|
|
2642
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2643
|
+
description: 'Represents the space between each child.'
|
|
2644
|
+
}, {
|
|
2645
|
+
name: 'spread',
|
|
2646
|
+
type: 'string',
|
|
2647
|
+
description: 'Used to distribute the children along the main axis.'
|
|
2648
|
+
}, {
|
|
2649
|
+
name: 'xcss',
|
|
2650
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "fill" | "gap" | "rowGap" | "flex" | "grid" | "stroke" | "all" | "bottom" | "left" | "right" | "top" | "clip" | "overlay" | ... 484 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2651
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2652
|
+
}]
|
|
2653
|
+
}, {
|
|
2654
|
+
name: 'MetricText',
|
|
2655
|
+
package: '@atlaskit/primitives',
|
|
2656
|
+
description: 'A primitive Text component for typography with compiled styling support.',
|
|
2657
|
+
status: 'general-availability',
|
|
2658
|
+
usageGuidelines: ['Use for text content with consistent typography', 'Leverage compiled styling for performance', 'Use appropriate font size and weight props', 'Consider semantic HTML elements'],
|
|
2659
|
+
contentGuidelines: ['Use for appropriate text content', 'Maintain consistent typography patterns', 'Consider readability and hierarchy'],
|
|
2660
|
+
keywords: ['text', 'typography', 'font', 'primitive', 'compiled'],
|
|
2661
|
+
category: 'primitive',
|
|
2662
|
+
examples: ['import { MetricText } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<MetricText size="small">42</MetricText>,\n\t<MetricText size="large">1,234</MetricText>,\n];\nexport default _default_1;'],
|
|
2663
|
+
props: [{
|
|
2664
|
+
name: 'align',
|
|
2665
|
+
type: '"center" | "end" | "start"',
|
|
2666
|
+
description: 'Text alignment.'
|
|
2667
|
+
}, {
|
|
2668
|
+
name: 'as',
|
|
2669
|
+
type: '"div" | "span"',
|
|
2670
|
+
description: 'HTML tag to be rendered. Defaults to `span`.'
|
|
2671
|
+
}, {
|
|
2672
|
+
name: 'children',
|
|
2673
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2674
|
+
description: 'Elements rendered within the Text element.',
|
|
2675
|
+
isRequired: true
|
|
2676
|
+
}, {
|
|
2677
|
+
name: 'id',
|
|
2678
|
+
type: 'string',
|
|
2679
|
+
description: 'The [HTML `id` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).'
|
|
2680
|
+
}, {
|
|
2681
|
+
name: 'role',
|
|
2682
|
+
type: 'string',
|
|
2683
|
+
description: 'Accessible role.'
|
|
2684
|
+
}, {
|
|
2685
|
+
name: 'size',
|
|
2686
|
+
type: '"small" | "medium" | "large"',
|
|
2687
|
+
description: 'Text size.',
|
|
2688
|
+
isRequired: true
|
|
2689
|
+
}]
|
|
2690
|
+
}, {
|
|
2691
|
+
name: 'Pressable',
|
|
2692
|
+
package: '@atlaskit/primitives',
|
|
2693
|
+
description: 'A primitive Pressable component for handling touch and click interactions with compiled styling support.',
|
|
2694
|
+
status: 'general-availability',
|
|
2695
|
+
usageGuidelines: ['Use for interactive elements that need press feedback', 'Leverage compiled styling for performance', 'Use appropriate press states and feedback', 'Consider touch target accessibility'],
|
|
2696
|
+
contentGuidelines: ['Use for appropriate interactive content', 'Maintain consistent press patterns', 'Consider user interaction expectations'],
|
|
2697
|
+
accessibilityGuidelines: ['Provide clear visual feedback for press states', 'Ensure appropriate touch target sizes', 'Use appropriate ARIA attributes for interactive elements', 'Provide keyboard navigation support'],
|
|
2698
|
+
keywords: ['pressable', 'interaction', 'touch', 'click', 'primitive', 'compiled'],
|
|
2699
|
+
category: 'primitive',
|
|
2700
|
+
examples: ["import { Pressable } from '@atlaskit/primitives/compiled';\nconst _default_1: React.JSX.Element[] = [\n\t<Pressable onClick={() => alert('Pressed!')}>Custom button</Pressable>,\n];\nexport default _default_1;"],
|
|
2701
|
+
props: [{
|
|
2702
|
+
name: 'isDisabled',
|
|
2703
|
+
type: 'boolean',
|
|
2704
|
+
description: 'Whether the button is disabled.'
|
|
2705
|
+
}, {
|
|
2706
|
+
name: 'onClick',
|
|
2707
|
+
type: '(e: MouseEvent<HTMLButtonElement, globalThis.MouseEvent>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
2708
|
+
description: "Handler called on click. The second argument provides an Atlaskit UI analytics event that can be fired to a listening channel. See the ['analytics-next' package](https://atlaskit.atlassian.com/packages/analytics/analytics-next) documentation for more information."
|
|
2709
|
+
}, {
|
|
2710
|
+
name: 'xcss',
|
|
2711
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "translate" | "content" | "color" | "grid" | "flex" | "fill" | "stroke" | "all" | "bottom" | "left" | "right" | "top" | ... 485 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2712
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2713
|
+
}]
|
|
2714
|
+
}, {
|
|
2715
|
+
name: 'Stack',
|
|
2716
|
+
package: '@atlaskit/primitives',
|
|
2717
|
+
description: 'A primitive Stack component for vertical and horizontal layout with consistent spacing.',
|
|
2718
|
+
status: 'general-availability',
|
|
2719
|
+
usageGuidelines: ['Use for consistent vertical or horizontal layouts', 'Leverage compiled styling for performance', 'Use appropriate spacing and alignment props', 'Consider responsive behavior'],
|
|
2720
|
+
contentGuidelines: ['Use for appropriate layout grouping', 'Maintain consistent spacing patterns', 'Consider content hierarchy and flow'],
|
|
2721
|
+
keywords: ['stack', 'layout', 'vertical', 'horizontal', 'spacing', 'primitive', 'compiled'],
|
|
2722
|
+
category: 'primitive',
|
|
2723
|
+
examples: ['import Heading from \'@atlaskit/heading\';\nimport { Stack, Text } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Stack space="space.100">\n\t\t<Heading size="medium">User name</Heading>\n\t\t<Text>Description</Text>\n\t</Stack>,\n];\nexport default _default_1;'],
|
|
2724
|
+
props: [{
|
|
2725
|
+
name: 'alignBlock',
|
|
2726
|
+
type: '"center" | "start" | "end" | "stretch"',
|
|
2727
|
+
description: 'Used to align children along the block axis (typically vertical).'
|
|
2728
|
+
}, {
|
|
2729
|
+
name: 'alignInline',
|
|
2730
|
+
type: '"center" | "start" | "end" | "stretch"',
|
|
2731
|
+
description: 'Used to align children along the inline axis (typically horizontal).'
|
|
2732
|
+
}, {
|
|
2733
|
+
name: 'as',
|
|
2734
|
+
type: '"div" | "dl" | "ol" | "span" | "ul"',
|
|
2735
|
+
description: 'The DOM element to render as the Stack. Defaults to `div`.'
|
|
2736
|
+
}, {
|
|
2737
|
+
name: 'children',
|
|
2738
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2739
|
+
description: 'Elements to be rendered inside the Stack.',
|
|
2740
|
+
isRequired: true
|
|
2741
|
+
}, {
|
|
2742
|
+
name: 'grow',
|
|
2743
|
+
type: '"hug" | "fill"',
|
|
2744
|
+
description: 'Used to set whether the container should grow to fill the available space.'
|
|
2745
|
+
}, {
|
|
2746
|
+
name: 'role',
|
|
2747
|
+
type: 'string',
|
|
2748
|
+
description: 'Accessible role.'
|
|
2749
|
+
}, {
|
|
2750
|
+
name: 'space',
|
|
2751
|
+
type: '"space.0" | "space.025" | "space.050" | "space.075" | "space.100" | "space.150" | "space.200" | "space.250" | "space.300" | "space.400" | "space.500" | "space.600" | "space.800" | "space.1000"',
|
|
2752
|
+
description: 'Represents the space between each child.'
|
|
2753
|
+
}, {
|
|
2754
|
+
name: 'spread',
|
|
2755
|
+
type: 'string',
|
|
2756
|
+
description: 'Used to distribute the children along the main axis.'
|
|
2757
|
+
}, {
|
|
2758
|
+
name: 'xcss',
|
|
2759
|
+
type: 'false | (XCSSValue<"clipPath" | "filter" | "marker" | "mask" | "fill" | "gap" | "flex" | "grid" | "stroke" | "all" | "bottom" | "left" | "right" | "top" | "clip" | "overlay" | "accentColor" | ... 484 more ... | "glyphOrientationVertical", DesignTokenStyles, ""> & ... 4 more ... & { ...; })',
|
|
2760
|
+
description: 'Apply a subset of permitted styles powered by Atlassian Design System design tokens.'
|
|
2761
|
+
}]
|
|
2762
|
+
}, {
|
|
2763
|
+
name: 'Text',
|
|
2764
|
+
package: '@atlaskit/primitives',
|
|
2765
|
+
description: 'A primitive Text component for typography with compiled styling support.',
|
|
2766
|
+
status: 'general-availability',
|
|
2767
|
+
usageGuidelines: ['Use for text content with consistent typography', 'Leverage compiled styling for performance', 'Use appropriate font size and weight props', 'Consider semantic HTML elements'],
|
|
2768
|
+
contentGuidelines: ['Use for appropriate text content', 'Maintain consistent typography patterns', 'Consider readability and hierarchy'],
|
|
2769
|
+
keywords: ['text', 'typography', 'font', 'primitive', 'compiled'],
|
|
2770
|
+
category: 'primitive',
|
|
2771
|
+
examples: ['import { Text } from \'@atlaskit/primitives/compiled\';\nconst _default_1: React.JSX.Element[] = [\n\t<Text>Default text</Text>,\n\t<Text size="large" weight="bold">\n\t\tLarge bold text\n\t</Text>,\n];\nexport default _default_1;'],
|
|
2772
|
+
props: [{
|
|
2773
|
+
name: 'align',
|
|
2774
|
+
type: '"center" | "end" | "start"',
|
|
2775
|
+
description: 'Text alignment.'
|
|
2776
|
+
}, {
|
|
2777
|
+
name: 'as',
|
|
2778
|
+
type: '"em" | "p" | "span" | "strong"',
|
|
2779
|
+
description: 'HTML tag to be rendered. Defaults to `span`.'
|
|
2780
|
+
}, {
|
|
2781
|
+
name: 'children',
|
|
2782
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
2783
|
+
description: 'Elements rendered within the Text element.',
|
|
2784
|
+
isRequired: true
|
|
2785
|
+
}, {
|
|
2786
|
+
name: 'color',
|
|
2787
|
+
type: '"inherit" | TextColor',
|
|
2788
|
+
description: 'Token representing text color with a built-in fallback value.\nWill apply inverse text color automatically if placed within a Box with bold background color.\nDefaults to `color.text` if not nested in other Text components.'
|
|
2789
|
+
}, {
|
|
2790
|
+
name: 'id',
|
|
2791
|
+
type: 'string',
|
|
2792
|
+
description: 'The [HTML `id` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).'
|
|
2793
|
+
}, {
|
|
2794
|
+
name: 'maxLines',
|
|
2795
|
+
type: 'number',
|
|
2796
|
+
description: 'The number of lines to limit the provided text to. Text will be truncated with an ellipsis.\n\nWhen `maxLines={1}`, `wordBreak` defaults to `break-all` to match the behaviour of `text-overflow: ellipsis`.'
|
|
2797
|
+
}, {
|
|
2798
|
+
name: 'role',
|
|
2799
|
+
type: 'string',
|
|
2800
|
+
description: 'Accessible role.'
|
|
2801
|
+
}, {
|
|
2802
|
+
name: 'size',
|
|
2803
|
+
type: '"small" | "large" | "medium" | "UNSAFE_small"',
|
|
2804
|
+
description: 'Text size.'
|
|
2805
|
+
}, {
|
|
2806
|
+
name: 'weight',
|
|
2807
|
+
type: '"medium" | "bold" | "regular" | "semibold"',
|
|
2808
|
+
description: 'The [HTML `font-weight` attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight).'
|
|
2809
|
+
}, {
|
|
2810
|
+
name: 'xcss',
|
|
2811
|
+
type: 'false | (XCSSValue<"fontVariantNumeric" | "overflowWrap" | "textDecorationLine", DesignTokenStyles, ""> & {} & XCSSPseudo<"fontVariantNumeric" | "overflowWrap" | "textDecorationLine", never, never, DesignTokenStyles> & XCSSMediaQuery<...> & { ...; } & { ...; })',
|
|
2812
|
+
description: 'Bounded style overrides.'
|
|
2813
|
+
}]
|
|
2814
|
+
}, {
|
|
2815
|
+
name: 'ProgressBar',
|
|
2816
|
+
package: '@atlaskit/progress-bar',
|
|
2817
|
+
description: 'A progress bar communicates the status of a system process, showing completion percentage or indeterminate progress.',
|
|
2818
|
+
status: 'general-availability',
|
|
2819
|
+
usageGuidelines: ['Use for showing progress of known duration', 'Provide clear progress indicators', 'Use indeterminate state for unknown duration', 'Position progress bars prominently when active', 'Consider providing percentage or time estimates'],
|
|
2820
|
+
contentGuidelines: ['Use clear, descriptive progress messages', 'Provide meaningful context for progress', 'Consider showing estimated time remaining', 'Use consistent progress terminology'],
|
|
2821
|
+
accessibilityGuidelines: ['Provide appropriate ARIA labels for progress bars', 'Announce progress changes to screen readers', 'Use appropriate color contrast for visibility', 'Provide alternative text for progress status'],
|
|
2822
|
+
keywords: ['progress', 'bar', 'loading', 'status', 'completion', 'indeterminate'],
|
|
2823
|
+
category: 'loading',
|
|
2824
|
+
examples: ['import ProgressBar from \'@atlaskit/progress-bar\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<ProgressBar value={0.5} />\n\t\t<ProgressBar value={0.8} appearance="success" />\n\t</>\n);\nexport default Examples;'],
|
|
2825
|
+
props: [{
|
|
2826
|
+
name: 'appearance',
|
|
2827
|
+
type: '"default" | "success" | "inverse"',
|
|
2828
|
+
description: 'The visual style of the progress bar.',
|
|
2829
|
+
defaultValue: '"default"'
|
|
2830
|
+
}, {
|
|
2831
|
+
name: 'ariaLabel',
|
|
2832
|
+
type: 'string',
|
|
2833
|
+
description: "This is the descriptive label that's associated with the progress bar.\nAlways include useful information on the current state of the progress bar so that people who use assistive technology can understand what the current state of the progress bar is."
|
|
2834
|
+
}, {
|
|
2835
|
+
name: 'isIndeterminate',
|
|
2836
|
+
type: 'boolean',
|
|
2837
|
+
description: 'Shows the progress bar in an indeterminate state when `true`.',
|
|
2838
|
+
defaultValue: 'false'
|
|
2839
|
+
}, {
|
|
2840
|
+
name: 'value',
|
|
2841
|
+
type: 'number',
|
|
2842
|
+
description: 'Sets the value of the progress bar, between `0` and `1` inclusive.',
|
|
2843
|
+
defaultValue: '0'
|
|
2844
|
+
}]
|
|
2845
|
+
}, {
|
|
2846
|
+
name: 'SuccessProgressBar',
|
|
2847
|
+
package: '@atlaskit/progress-bar',
|
|
2848
|
+
description: 'A progress bar variant that indicates successful completion of a process.',
|
|
2849
|
+
status: 'general-availability',
|
|
2850
|
+
usageGuidelines: ['Use to indicate successful completion', 'Show briefly before transitioning to next state', 'Use appropriate success styling', 'Consider providing success message'],
|
|
2851
|
+
contentGuidelines: ['Use clear success messaging', 'Indicate what was completed successfully', 'Provide next steps if applicable'],
|
|
2852
|
+
keywords: ['progress', 'bar', 'success', 'complete', 'finished'],
|
|
2853
|
+
category: 'loading',
|
|
2854
|
+
examples: ["import { SuccessProgressBar } from '@atlaskit/progress-bar';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<SuccessProgressBar value={1.0} />\n\t\t<SuccessProgressBar value={0.9} />\n\t</>\n);\nexport default Examples;"],
|
|
2855
|
+
props: [{
|
|
2856
|
+
name: 'ariaLabel',
|
|
2857
|
+
type: 'string',
|
|
2858
|
+
description: "This is the descriptive label that's associated with the progress bar.\nAlways include useful information on the current state of the progress bar so that people who use assistive technology can understand what the current state of the progress bar is."
|
|
2859
|
+
}, {
|
|
2860
|
+
name: 'isIndeterminate',
|
|
2861
|
+
type: 'boolean',
|
|
2862
|
+
description: 'Shows the progress bar in an indeterminate state when `true`.',
|
|
2863
|
+
defaultValue: 'false'
|
|
2864
|
+
}, {
|
|
2865
|
+
name: 'value',
|
|
2866
|
+
type: 'number',
|
|
2867
|
+
description: 'Sets the value of the progress bar, between `0` and `1` inclusive.',
|
|
2868
|
+
defaultValue: '0'
|
|
2869
|
+
}]
|
|
2870
|
+
}, {
|
|
2871
|
+
name: 'TransparentProgressBar',
|
|
2872
|
+
package: '@atlaskit/progress-bar',
|
|
2873
|
+
description: 'A progress bar variant with transparent background for overlay contexts.',
|
|
2874
|
+
status: 'general-availability',
|
|
2875
|
+
usageGuidelines: ['Use in overlay or modal contexts', 'Ensure sufficient contrast with background', 'Use for subtle progress indication', 'Consider backdrop visibility'],
|
|
2876
|
+
contentGuidelines: ['Ensure progress is visible against background', 'Use appropriate contrast for readability', 'Keep progress indication clear'],
|
|
2877
|
+
keywords: ['progress', 'bar', 'transparent', 'overlay', 'subtle'],
|
|
2878
|
+
category: 'loading',
|
|
2879
|
+
examples: ["import { TransparentProgressBar } from '@atlaskit/progress-bar';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<TransparentProgressBar value={0.6} />\n\t\t<TransparentProgressBar value={0.3} />\n\t</>\n);\nexport default Examples;"],
|
|
2880
|
+
props: [{
|
|
2881
|
+
name: 'ariaLabel',
|
|
2882
|
+
type: 'string',
|
|
2883
|
+
description: "This is the descriptive label that's associated with the progress bar.\nAlways include useful information on the current state of the progress bar so that people who use assistive technology can understand what the current state of the progress bar is."
|
|
2884
|
+
}, {
|
|
2885
|
+
name: 'isIndeterminate',
|
|
2886
|
+
type: 'boolean',
|
|
2887
|
+
description: 'Shows the progress bar in an indeterminate state when `true`.',
|
|
2888
|
+
defaultValue: 'false'
|
|
2889
|
+
}, {
|
|
2890
|
+
name: 'value',
|
|
2891
|
+
type: 'number',
|
|
2892
|
+
description: 'Sets the value of the progress bar, between `0` and `1` inclusive.',
|
|
2893
|
+
defaultValue: '0'
|
|
2894
|
+
}]
|
|
2895
|
+
}, {
|
|
2896
|
+
name: 'ProgressIndicator',
|
|
2897
|
+
package: '@atlaskit/progress-indicator',
|
|
2898
|
+
description: 'A component for displaying progress through steps or completion status.',
|
|
2899
|
+
status: 'general-availability',
|
|
2900
|
+
usageGuidelines: ['Use for step-by-step processes', 'Provide clear progress indicators', 'Handle progress updates appropriately', 'Consider progress completion states'],
|
|
2901
|
+
contentGuidelines: ['Use clear, descriptive step labels', 'Provide meaningful progress descriptions', 'Use appropriate progress terminology', 'Keep progress information concise'],
|
|
2902
|
+
accessibilityGuidelines: ['Ensure progress is announced by screen readers', 'Use appropriate progress indicators', 'Provide clear progress context', 'Consider progress timing and updates'],
|
|
2903
|
+
keywords: ['progress', 'indicator', 'steps', 'completion', 'status'],
|
|
2904
|
+
category: 'feedback',
|
|
2905
|
+
examples: ["import { ProgressIndicator } from '@atlaskit/progress-indicator';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<ProgressIndicator selectedIndex={1} values={['Step 1', 'Step 2', 'Step 3']} />\n\t\t<ProgressIndicator selectedIndex={2} values={['Start', 'In Progress', 'Complete']} />\n\t</>\n);\nexport default Examples;"],
|
|
2906
|
+
props: [{
|
|
2907
|
+
name: 'appearance',
|
|
2908
|
+
type: '"default" | "help" | "inverted" | "primary"',
|
|
2909
|
+
description: 'Sets the color of the indicators.',
|
|
2910
|
+
defaultValue: '"default"'
|
|
2911
|
+
}, {
|
|
2912
|
+
name: 'ariaControls',
|
|
2913
|
+
type: 'string',
|
|
2914
|
+
description: 'If interaction is enabled, use `ariaControls` to tell assistive technology what elements are controlled by the progress indicator.',
|
|
2915
|
+
defaultValue: '"panel"'
|
|
2916
|
+
}, {
|
|
2917
|
+
name: 'ariaLabel',
|
|
2918
|
+
type: 'string',
|
|
2919
|
+
description: 'Describes what the indicator represents to assistive technology. The selected index number will be appended to the label.',
|
|
2920
|
+
defaultValue: '"tab"'
|
|
2921
|
+
}, {
|
|
2922
|
+
name: 'onSelect',
|
|
2923
|
+
type: '(eventData: { event: React.MouseEvent<HTMLButtonElement, MouseEvent>; index: number; }, analyticsEvent: UIAnalyticsEvent) => void',
|
|
2924
|
+
description: 'Function called when an indicator is selected.'
|
|
2925
|
+
}, {
|
|
2926
|
+
name: 'selectedIndex',
|
|
2927
|
+
type: 'number',
|
|
2928
|
+
description: 'Which indicator is currently selected.',
|
|
2929
|
+
isRequired: true
|
|
2930
|
+
}, {
|
|
2931
|
+
name: 'size',
|
|
2932
|
+
type: '"default" | "large"',
|
|
2933
|
+
description: 'Sets the width and height of each indicator.',
|
|
2934
|
+
defaultValue: '"default"'
|
|
2935
|
+
}, {
|
|
2936
|
+
name: 'spacing',
|
|
2937
|
+
type: '"comfortable" | "cozy" | "compact"',
|
|
2938
|
+
description: 'Specifies how much of a gutter there is between indicators.'
|
|
2939
|
+
}, {
|
|
2940
|
+
name: 'values',
|
|
2941
|
+
type: 'any[]',
|
|
2942
|
+
description: 'An array of values mapped over to create the indicators.',
|
|
2943
|
+
isRequired: true
|
|
2944
|
+
}]
|
|
2945
|
+
}, {
|
|
2946
|
+
name: 'ProgressTracker',
|
|
2947
|
+
package: '@atlaskit/progress-tracker',
|
|
2948
|
+
description: 'A component for tracking progress through multi-step processes.',
|
|
2949
|
+
status: 'general-availability',
|
|
2950
|
+
usageGuidelines: ['Use for multi-step workflows', 'Provide clear progress tracking', 'Handle progress updates appropriately', 'Consider progress completion states'],
|
|
2951
|
+
contentGuidelines: ['Use clear, descriptive step labels', 'Provide meaningful progress descriptions', 'Use appropriate progress terminology', 'Keep progress information concise'],
|
|
2952
|
+
accessibilityGuidelines: ['Ensure progress is announced by screen readers', 'Use appropriate progress indicators', 'Provide clear progress context', 'Consider progress timing and updates'],
|
|
2953
|
+
keywords: ['progress', 'tracker', 'steps', 'completion', 'workflow'],
|
|
2954
|
+
category: 'feedback',
|
|
2955
|
+
examples: ["import { ProgressTracker } from '@atlaskit/progress-tracker';\nconst Example = (): React.JSX.Element => (\n\t<ProgressTracker\n\t\titems={[\n\t\t\t{ id: 'step1', label: 'Step 1', status: 'visited', percentageComplete: 100 },\n\t\t\t{ id: 'step2', label: 'Step 2', status: 'current', percentageComplete: 40 },\n\t\t\t{ id: 'step3', label: 'Step 3', status: 'disabled', percentageComplete: 0 },\n\t\t\t{ id: 'step4', label: 'Step 4', status: 'unvisited', percentageComplete: 0 },\n\t\t]}\n\t/>\n);\nexport default Example;"],
|
|
2956
|
+
props: [{
|
|
2957
|
+
name: 'animated',
|
|
2958
|
+
type: 'boolean',
|
|
2959
|
+
description: 'Turns off transition animations if set to false.',
|
|
2960
|
+
defaultValue: 'true'
|
|
2961
|
+
}, {
|
|
2962
|
+
name: 'items',
|
|
2963
|
+
type: 'Stage[]',
|
|
2964
|
+
description: 'Ordered list of stage data.',
|
|
2965
|
+
defaultValue: '[]',
|
|
2966
|
+
isRequired: true
|
|
2967
|
+
}, {
|
|
2968
|
+
name: 'label',
|
|
2969
|
+
type: 'string',
|
|
2970
|
+
description: 'Use this to provide an aria-label for the overall progress tracker, so that people who use assistive technology get an overview of the tracker\'s purpose. For example, "Sign up progress".',
|
|
2971
|
+
defaultValue: '"Progress"'
|
|
2972
|
+
}, {
|
|
2973
|
+
name: 'spacing',
|
|
2974
|
+
type: '"cozy" | "comfortable" | "compact"',
|
|
2975
|
+
description: 'Sets the amount of spacing between the steps.',
|
|
2976
|
+
defaultValue: '"cozy"'
|
|
2977
|
+
}]
|
|
2978
|
+
}, {
|
|
2979
|
+
name: 'Radio',
|
|
2980
|
+
package: '@atlaskit/radio',
|
|
2981
|
+
description: 'A radio button component for single selection from a set of mutually exclusive choices. Use for custom radio button presentations like options in tables or when you need fine control over individual radio buttons.',
|
|
2982
|
+
status: 'general-availability',
|
|
2983
|
+
usageGuidelines: ['Use for custom radio button presentations (e.g., options in tables)', 'Use when you need fine control over individual radio buttons', 'List options in logical order (most likely to least likely)', 'Make one option the default (safest, most secure option)', "Add 'None' option if unselected state is needed", "Add 'Other' option if not all options can be listed"],
|
|
2984
|
+
contentGuidelines: ['Use clear, descriptive labels that provide context', 'Keep labels concise but informative', 'Use sentence case for labels', 'Avoid overlapping or skipping numeric choices'],
|
|
2985
|
+
accessibilityGuidelines: ['Include error messages for required or invalid radio fields', 'Never preselect high-risk options for payment, privacy, or security', "Don't use disabled radio buttons if they need to remain in tab order", 'Use validation instead of disabled state for better accessibility'],
|
|
2986
|
+
keywords: ['radio', 'button', 'input', 'form', 'selection', 'choice', 'option'],
|
|
2987
|
+
category: 'form',
|
|
2988
|
+
examples: ['import { Radio } from \'@atlaskit/radio\';\nexport default (): React.JSX.Element => (\n\t<Radio value="option1" label="Option 1" name="choices" onChange={() => console.log(\'Changed!\')} />\n);'],
|
|
2989
|
+
props: [{
|
|
2990
|
+
name: 'ariaLabel',
|
|
2991
|
+
type: 'string',
|
|
2992
|
+
description: 'The `aria-label` attribute associated with the radio element.'
|
|
2993
|
+
}, {
|
|
2994
|
+
name: 'isChecked',
|
|
2995
|
+
type: 'boolean',
|
|
2996
|
+
description: 'Set the field as checked.'
|
|
2997
|
+
}, {
|
|
2998
|
+
name: 'isDisabled',
|
|
2999
|
+
type: 'boolean',
|
|
3000
|
+
description: 'Makes a `Radio` field unselectable when true. Overridden by `isDisabled` prop of `RadioGroup`.'
|
|
3001
|
+
}, {
|
|
3002
|
+
name: 'isInvalid',
|
|
3003
|
+
type: 'boolean',
|
|
3004
|
+
description: 'Marks this as an invalid field.'
|
|
3005
|
+
}, {
|
|
3006
|
+
name: 'isRequired',
|
|
3007
|
+
type: 'boolean',
|
|
3008
|
+
description: 'Marks this as a required field.'
|
|
3009
|
+
}, {
|
|
3010
|
+
name: 'label',
|
|
3011
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
3012
|
+
description: 'The label value for the input rendered to the DOM.'
|
|
3013
|
+
}, {
|
|
3014
|
+
name: 'labelId',
|
|
3015
|
+
type: 'string',
|
|
3016
|
+
description: 'This sets the `aria-labelledby` attribute. It sets an accessible name for\nthe radio, for people who use assistive technology. Use of a visible label\nis highly recommended for greater accessibility support.'
|
|
3017
|
+
}, {
|
|
3018
|
+
name: 'onChange',
|
|
3019
|
+
type: '(e: ChangeEvent<HTMLInputElement>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
3020
|
+
description: '`onChange` event handler, passed into the props of each `Radio` Component instantiated within `RadioGroup`.'
|
|
3021
|
+
}, {
|
|
3022
|
+
name: 'value',
|
|
3023
|
+
type: 'string',
|
|
3024
|
+
description: 'Field value.'
|
|
3025
|
+
}]
|
|
3026
|
+
}, {
|
|
3027
|
+
name: 'RadioGroup',
|
|
3028
|
+
package: '@atlaskit/radio',
|
|
3029
|
+
description: 'A radio group component that presents a list of options where only one choice can be selected. Use for most radio button scenarios where you want a simple list of mutually exclusive options.',
|
|
3030
|
+
status: 'general-availability',
|
|
3031
|
+
usageGuidelines: ['Use for most radio button scenarios with simple option lists', 'List options in logical order (most likely to least likely)', 'Make one option the default (safest, most secure option)', "Add 'None' option if unselected state is needed", "Add 'Other' option if not all options can be listed", 'Use select component for longer lists of options'],
|
|
3032
|
+
contentGuidelines: ['Use clear, descriptive labels that provide context', 'Keep labels concise but informative', 'Use sentence case for labels', 'Avoid overlapping or skipping numeric choices'],
|
|
3033
|
+
accessibilityGuidelines: ['Include error messages for required or invalid radio fields', 'Never preselect high-risk options for payment, privacy, or security', "Don't use disabled radio buttons if they need to remain in tab order", 'Use validation instead of disabled state for better accessibility', 'Ensure proper keyboard navigation with arrow keys'],
|
|
3034
|
+
keywords: ['radio', 'group', 'form', 'selection', 'choice', 'options', 'list'],
|
|
3035
|
+
category: 'form',
|
|
3036
|
+
examples: ["import { RadioGroup } from '@atlaskit/radio';\n// Radio group with options\nconst options = [\n\t{ name: 'color', value: 'red', label: 'Red' },\n\t{ name: 'color', value: 'blue', label: 'Blue' },\n];\nexport default (): React.JSX.Element => {\n\tconst [value, setValue] = React.useState('red');\n\treturn (\n\t\t<RadioGroup options={options} value={value} onChange={(e) => setValue(e.currentTarget.value)} />\n\t);\n};"],
|
|
3037
|
+
props: [{
|
|
3038
|
+
name: 'defaultValue',
|
|
3039
|
+
type: 'string',
|
|
3040
|
+
description: 'Sets the initial selected value on the `RadioGroup`.'
|
|
3041
|
+
}, {
|
|
3042
|
+
name: 'id',
|
|
3043
|
+
type: 'string'
|
|
3044
|
+
}, {
|
|
3045
|
+
name: 'isDisabled',
|
|
3046
|
+
type: 'boolean',
|
|
3047
|
+
description: 'Sets the disabled state of all `Radio` elements in the group. Overrides the `isDisabled` setting of all child `Radio` items.'
|
|
3048
|
+
}, {
|
|
3049
|
+
name: 'isInvalid',
|
|
3050
|
+
type: 'boolean',
|
|
3051
|
+
description: 'Sets the invalid state of all `Radio` elements in the group.'
|
|
3052
|
+
}, {
|
|
3053
|
+
name: 'isRequired',
|
|
3054
|
+
type: 'boolean',
|
|
3055
|
+
description: 'Sets the required state of all `Radio` elements in the group.'
|
|
3056
|
+
}, {
|
|
3057
|
+
name: 'labelId',
|
|
3058
|
+
type: 'string',
|
|
3059
|
+
description: 'This sets the `aria-labelledby` attribute. It sets an accessible name for\nthe radio, for people who use assistive technology. Use of a visible label\nis highly recommended for greater accessibility support.'
|
|
3060
|
+
}, {
|
|
3061
|
+
name: 'name',
|
|
3062
|
+
type: 'string',
|
|
3063
|
+
description: 'Sets the `name` prop on each of the `Radio` elements in the group.'
|
|
3064
|
+
}, {
|
|
3065
|
+
name: 'onChange',
|
|
3066
|
+
type: '(e: React.ChangeEvent<HTMLInputElement>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
3067
|
+
description: 'Function that gets after each change event.'
|
|
3068
|
+
}, {
|
|
3069
|
+
name: 'onInvalid',
|
|
3070
|
+
type: '(event: React.SyntheticEvent<any, Event>) => void',
|
|
3071
|
+
description: 'Function that gets fired after each invalid event.'
|
|
3072
|
+
}, {
|
|
3073
|
+
name: 'options',
|
|
3074
|
+
type: 'OptionPropType[]',
|
|
3075
|
+
description: 'An array of objects, each object is mapped onto a `Radio` element within the group. Name must be unique to the group.',
|
|
3076
|
+
isRequired: true
|
|
3077
|
+
}, {
|
|
3078
|
+
name: 'value',
|
|
3079
|
+
type: 'string',
|
|
3080
|
+
description: 'Once set, controls the selected value on the `RadioGroup`.'
|
|
3081
|
+
}]
|
|
3082
|
+
}, {
|
|
3083
|
+
name: 'Range',
|
|
3084
|
+
package: '@atlaskit/range',
|
|
3085
|
+
description: 'A component for selecting a value from a range of values.',
|
|
3086
|
+
status: 'general-availability',
|
|
3087
|
+
usageGuidelines: ['Use for selecting numeric values within a range', 'Provide clear min/max boundaries', 'Use appropriate step increments', 'Consider showing current value'],
|
|
3088
|
+
contentGuidelines: ['Use clear range labels', 'Provide meaningful min/max labels', 'Show current value when helpful', 'Use consistent range terminology'],
|
|
3089
|
+
accessibilityGuidelines: ['Provide clear labels for range inputs', 'Use appropriate ARIA attributes', 'Ensure keyboard navigation support', 'Provide value announcements for screen readers'],
|
|
3090
|
+
keywords: ['range', 'slider', 'input', 'form', 'value', 'selection'],
|
|
3091
|
+
category: 'form',
|
|
3092
|
+
examples: ["import Range from '@atlaskit/range';\nconst Example = (): React.JSX.Element => (\n\t<Range\n\t\tvalue={25}\n\t\tmin={0}\n\t\tmax={50}\n\t\tstep={5}\n\t\tonChange={(value) => console.log('Stepped value:', value)}\n\t/>\n);\nexport default Example;"],
|
|
3093
|
+
props: [{
|
|
3094
|
+
name: 'defaultValue',
|
|
3095
|
+
type: 'number',
|
|
3096
|
+
description: 'Sets the default value if range is not set.'
|
|
3097
|
+
}, {
|
|
3098
|
+
name: 'isDisabled',
|
|
3099
|
+
type: 'boolean',
|
|
3100
|
+
description: 'Sets whether the field range is disabled.'
|
|
3101
|
+
}, {
|
|
3102
|
+
name: 'max',
|
|
3103
|
+
type: 'number',
|
|
3104
|
+
description: 'Sets the maximum value of the range.'
|
|
3105
|
+
}, {
|
|
3106
|
+
name: 'min',
|
|
3107
|
+
type: 'number',
|
|
3108
|
+
description: 'Sets the minimum value of the range.'
|
|
3109
|
+
}, {
|
|
3110
|
+
name: 'onChange',
|
|
3111
|
+
type: '(value: number) => void',
|
|
3112
|
+
description: 'Hook to be invoked on change of the range.'
|
|
3113
|
+
}, {
|
|
3114
|
+
name: 'step',
|
|
3115
|
+
type: 'number',
|
|
3116
|
+
description: 'Sets the step value for the range.'
|
|
3117
|
+
}, {
|
|
3118
|
+
name: 'value',
|
|
3119
|
+
type: 'number',
|
|
3120
|
+
description: 'Sets the value of the range.'
|
|
3121
|
+
}]
|
|
3122
|
+
}, {
|
|
3123
|
+
name: 'SectionMessage',
|
|
3124
|
+
package: '@atlaskit/section-message',
|
|
3125
|
+
description: 'A component for section-level messages.',
|
|
3126
|
+
status: 'general-availability',
|
|
3127
|
+
usageGuidelines: ['Use for section-level important info that persists until action or resolution', 'Use when: destructive consequences, action needed to proceed, connectivity or auth issues', 'Anatomy: icon+color, title (optional), description, actions (optional)', 'Use Banner for site-wide; Flag after an event; Inline message for smaller context'],
|
|
3128
|
+
contentGuidelines: ['Title: state the issue or reason', 'Description: clear, concise, empathetic; use active verbs', 'Avoid blame—use "we\'re having trouble" not "you\'re having issues"', 'Provide clear next steps when needed'],
|
|
3129
|
+
accessibilityGuidelines: ['Do not rely on color alone for severity', 'Avoid dead ends—always indicate how to proceed', 'Use descriptive link text that describes the destination', 'Ensure section message content is announced by screen readers', 'Use appropriate color contrast for text readability', 'Provide clear, actionable messaging', 'Consider keyboard navigation for interactive section messages'],
|
|
3130
|
+
keywords: ['section', 'message', 'alert', 'notification', 'contextual', 'information'],
|
|
3131
|
+
category: 'feedback',
|
|
3132
|
+
examples: ['import { Text } from \'@atlaskit/primitives/compiled\';\nimport SectionMessage, { SectionMessageAction } from \'@atlaskit/section-message\';\nexport default [\n\t<SectionMessage appearance="information" title="Information">\n\t\t<Text>This is an informational message to help users understand something important.</Text>\n\t</SectionMessage>,\n\t<SectionMessage appearance="warning" title="Warning">\n\t\t<Text>Please review your settings before proceeding with this action.</Text>\n\t</SectionMessage>,\n\t<SectionMessage\n\t\tappearance="success"\n\t\ttitle="Success"\n\t\tactions={[\n\t\t\t<SectionMessageAction href="#">View Details</SectionMessageAction>,\n\t\t\t<SectionMessageAction href="#">Share Results</SectionMessageAction>,\n\t\t]}\n\t>\n\t\t<Text>Your changes have been saved successfully!</Text>\n\t</SectionMessage>,\n];'],
|
|
3133
|
+
props: [{
|
|
3134
|
+
name: 'actions',
|
|
3135
|
+
type: 'ReactElement<any, string | JSXElementConstructor<any>> | ReactElement<SectionMessageActionProps, string | JSXElementConstructor<...>>[]',
|
|
3136
|
+
description: 'Actions for the user to take after reading the section message. Accepts a ReactElement\nor an array of one or more SectionMessageAction React elements, which are applied as link buttons.\nMiddle dots are automatically added between multiple link buttons, so no elements\nshould be present between multiple actions.\n\nIn general, avoid using more than two actions.'
|
|
3137
|
+
}, {
|
|
3138
|
+
name: 'appearance',
|
|
3139
|
+
type: '"information" | "warning" | "error" | "success" | "discovery"',
|
|
3140
|
+
description: 'The appearance styling to use for the section message.'
|
|
3141
|
+
}, {
|
|
3142
|
+
name: 'children',
|
|
3143
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
3144
|
+
description: 'The main content of the section message. This accepts a react node, although\nwe recommend that this should be a paragraph.',
|
|
3145
|
+
isRequired: true
|
|
3146
|
+
}, {
|
|
3147
|
+
name: 'icon',
|
|
3148
|
+
type: '"symbol" | "object" | "title" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 159 more ... | ComponentType<...>',
|
|
3149
|
+
description: 'An Icon component to be rendered instead of the default icon for the component.\nThis should only be an `@atlaskit/icon` icon. You can check out [this example](/packages/design-system/section-message/example/custom-icon)\nto see how to provide this icon.'
|
|
3150
|
+
}, {
|
|
3151
|
+
name: 'isDismissible',
|
|
3152
|
+
type: 'boolean',
|
|
3153
|
+
description: 'Displays a dismiss button, that allows the user to dismiss the message.\nIt will be removed from the DOM immediately and will not be re-rendered.\nIt does not handle persistence of the dismissed state across page reloads or remounts.'
|
|
3154
|
+
}, {
|
|
3155
|
+
name: 'onDismiss',
|
|
3156
|
+
type: '() => void',
|
|
3157
|
+
description: 'A callback function that is called when the user dismisses the message.'
|
|
3158
|
+
}, {
|
|
3159
|
+
name: 'title',
|
|
3160
|
+
type: 'string',
|
|
3161
|
+
description: 'The heading of the section message.'
|
|
3162
|
+
}]
|
|
3163
|
+
}, {
|
|
3164
|
+
name: 'Select',
|
|
3165
|
+
package: '@atlaskit/select',
|
|
3166
|
+
description: 'A flexible select component for single and multi-selection.',
|
|
3167
|
+
status: 'general-availability',
|
|
3168
|
+
usageGuidelines: ['Use for choosing one or more from a list; common in forms and inline edit', 'Use a visible label for the field—do not use placeholder as the only label (placeholder disappears and is not accessible)', 'Use logical order (e.g. most selected first, numeric)', 'Do not overwhelm with too many options', 'Enable search for long option lists', 'Consider loading states for async data', 'Avoid alphabetical ordering (not localizable); use logical order for translatable option lists'],
|
|
3169
|
+
contentGuidelines: ['Write clear, descriptive option labels', 'Use consistent terminology across options', 'Keep option text concise but meaningful', 'Group related options only when all items are groupable; use well-known categories or for disambiguation (e.g. Portland ME vs OR); no group of one'],
|
|
3170
|
+
accessibilityGuidelines: ['Use labels and helper text for the field—do not use placeholder as label (disappears on focus, not accessible)', 'Clear control is removed from tab order; keyboard users clear selection via Delete', 'Provide clear labels for all selects', 'Ensure keyboard navigation with arrow keys', 'Support screen reader announcements'],
|
|
3171
|
+
keywords: ['select', 'dropdown', 'form', 'input', 'options', 'choice', 'picker'],
|
|
3172
|
+
category: 'form',
|
|
3173
|
+
examples: ["import { Label } from '@atlaskit/form';\nimport Select from '@atlaskit/select';\nexport default function SelectAppearanceDefault(): React.JSX.Element {\n\treturn (\n\t\t<>\n\t\t\t<Label htmlFor=\"default-appearance-example\">Favorite fruit</Label>\n\t\t\t<Select\n\t\t\t\tinputId=\"default-appearance-example\"\n\t\t\t\tappearance=\"default\"\n\t\t\t\toptions={[\n\t\t\t\t\t{ label: 'Apple', value: 'a' },\n\t\t\t\t\t{ label: 'Banana', value: 'b' },\n\t\t\t\t]}\n\t\t\t/>\n\t\t</>\n\t);\n}"],
|
|
3174
|
+
props: [{
|
|
3175
|
+
name: 'allowCreateWhileLoading',
|
|
3176
|
+
type: 'any',
|
|
3177
|
+
description: 'Allow options to be created while the `isLoading` prop is true. Useful to\nprevent the "create new ..." option being displayed while async results are\nstill being loaded.'
|
|
3178
|
+
}, {
|
|
3179
|
+
name: 'appearance',
|
|
3180
|
+
type: '"default" | "subtle" | "none"'
|
|
3181
|
+
}, {
|
|
3182
|
+
name: 'autoFocus',
|
|
3183
|
+
type: 'boolean',
|
|
3184
|
+
description: 'Focus the control when it is mounted. There are very few cases that this should be used, and using incorrectly may violate accessibility guidelines.'
|
|
3185
|
+
}, {
|
|
3186
|
+
name: 'blurInputOnSelect',
|
|
3187
|
+
type: 'boolean',
|
|
3188
|
+
description: 'Remove focus from the input when the user selects an option (handy for dismissing the keyboard on touch devices)'
|
|
3189
|
+
}, {
|
|
3190
|
+
name: 'cacheOptions',
|
|
3191
|
+
type: 'any',
|
|
3192
|
+
description: 'If cacheOptions is truthy, then the loaded data will be cached. The cache\nwill remain until `cacheOptions` changes value.'
|
|
3193
|
+
}, {
|
|
3194
|
+
name: 'classNamePrefix',
|
|
3195
|
+
type: 'string',
|
|
3196
|
+
description: 'If provided, all inner components will be given a prefixed className attribute.\n\nThis is useful when styling via CSS classes instead of the Styles API approach.'
|
|
3197
|
+
}, {
|
|
3198
|
+
name: 'classNames',
|
|
3199
|
+
type: '{ clearIndicator?: (props: ClearIndicatorProps<Option, IsMulti, GroupBase<Option>>) => string; container?: (props: ContainerProps<Option, IsMulti, GroupBase<...>>) => string; ... 18 more ...; valueContainer?: (props: ValueContainerProps<...>) => string; }',
|
|
3200
|
+
description: 'Provide classNames based on state for each inner component'
|
|
3201
|
+
}, {
|
|
3202
|
+
name: 'clearControlLabel',
|
|
3203
|
+
type: 'string',
|
|
3204
|
+
description: 'Set the `aria-label` for the clear icon button.'
|
|
3205
|
+
}, {
|
|
3206
|
+
name: 'closeMenuOnSelect',
|
|
3207
|
+
type: 'boolean',
|
|
3208
|
+
description: 'Close the select menu when the user selects an option'
|
|
3209
|
+
}, {
|
|
3210
|
+
name: 'components',
|
|
3211
|
+
type: '{ Option?: React.ComponentType<OptionProps<Option, IsMulti, GroupBase<Option>>>; Group?: React.ComponentType<GroupProps<Option, IsMulti, GroupBase<...>>>; ... 19 more ...; ValueContainer?: React.ComponentType<...>; }',
|
|
3212
|
+
description: 'This complex object includes all the compositional components that are used\nin `react-select`. If you wish to overwrite a component, pass in an object\nwith the appropriate namespace. If you wish to restyle a component, we recommend\nusing this prop with the `xcss` prop.'
|
|
3213
|
+
}, {
|
|
3214
|
+
name: 'createOptionPosition',
|
|
3215
|
+
type: 'any',
|
|
3216
|
+
description: "Sets the position of the createOption element in your options list. Defaults to 'last'"
|
|
3217
|
+
}, {
|
|
3218
|
+
name: 'defaultInputValue',
|
|
3219
|
+
type: 'string'
|
|
3220
|
+
}, {
|
|
3221
|
+
name: 'defaultMenuIsOpen',
|
|
3222
|
+
type: 'boolean'
|
|
3223
|
+
}, {
|
|
3224
|
+
name: 'defaultOptions',
|
|
3225
|
+
type: 'any',
|
|
3226
|
+
description: "The default set of options to show before the user starts searching. When\nset to `true`, the results for loadOptions('') will be autoloaded."
|
|
3227
|
+
}, {
|
|
3228
|
+
name: 'defaultValue',
|
|
3229
|
+
type: 'Option | MultiValue<Option>'
|
|
3230
|
+
}, {
|
|
3231
|
+
name: 'descriptionId',
|
|
3232
|
+
type: 'string',
|
|
3233
|
+
description: "This sets the aria-describedby attribute. It sets an accessible description for the select, for people who use assistive technology. Use '<HelperMessage>' from '@atlaskit/form' is preferred."
|
|
3234
|
+
}, {
|
|
3235
|
+
name: 'filterOption',
|
|
3236
|
+
type: '(option: FilterOptionOption<Option>, inputValue: string) => boolean',
|
|
3237
|
+
description: 'Custom method to filter whether an option should be displayed in the menu'
|
|
3238
|
+
}, {
|
|
3239
|
+
name: 'form',
|
|
3240
|
+
type: 'string',
|
|
3241
|
+
description: 'Sets the form attribute on the input'
|
|
3242
|
+
}, {
|
|
3243
|
+
name: 'formatCreateLabel',
|
|
3244
|
+
type: 'any',
|
|
3245
|
+
description: 'Gets the label for the "create new ..." option in the menu. Is given the\ncurrent input value.'
|
|
3246
|
+
}, {
|
|
3247
|
+
name: 'formatGroupLabel',
|
|
3248
|
+
type: '(group: GroupBase<Option>) => React.ReactNode',
|
|
3249
|
+
description: 'Formats group labels in the menu as React components\n\nAn example can be found in the [Replacing builtins](https://react-select.com/advanced#replacing-builtins) documentation.'
|
|
3250
|
+
}, {
|
|
3251
|
+
name: 'formatOptionLabel',
|
|
3252
|
+
type: '((data: Option, formatOptionLabelMeta: FormatOptionLabelMeta<Option>) => React.ReactNode) | ((data: Option, formatOptionLabelMeta: FormatOptionLabelMeta<Option>) => React.ReactNode)',
|
|
3253
|
+
description: 'Formats option labels in the menu and control as React components'
|
|
3254
|
+
}, {
|
|
3255
|
+
name: 'getNewOptionData',
|
|
3256
|
+
type: 'any',
|
|
3257
|
+
description: 'Returns the data for the new option when it is created. Used to display the\nvalue, and is passed to `onChange`.'
|
|
3258
|
+
}, {
|
|
3259
|
+
name: 'getOptionLabel',
|
|
3260
|
+
type: '(option: Option) => string',
|
|
3261
|
+
description: 'Resolves option data to a string to be displayed as the label by components\n\nNote: Failure to resolve to a string type can interfere with filtering and\nscreen reader support.'
|
|
3262
|
+
}, {
|
|
3263
|
+
name: 'getOptionValue',
|
|
3264
|
+
type: '(option: Option) => string',
|
|
3265
|
+
description: 'Resolves option data to a string to compare options and specify value attributes'
|
|
3266
|
+
}, {
|
|
3267
|
+
name: 'hideSelectedOptions',
|
|
3268
|
+
type: 'boolean',
|
|
3269
|
+
description: 'Hide the selected option from the menu'
|
|
3270
|
+
}, {
|
|
3271
|
+
name: 'id',
|
|
3272
|
+
type: 'string',
|
|
3273
|
+
description: 'The id to set on the SelectContainer component.'
|
|
3274
|
+
}, {
|
|
3275
|
+
name: 'inputId',
|
|
3276
|
+
type: 'string',
|
|
3277
|
+
description: 'The id of the search input'
|
|
3278
|
+
}, {
|
|
3279
|
+
name: 'inputValue',
|
|
3280
|
+
type: 'string',
|
|
3281
|
+
description: 'The value of the search input'
|
|
3282
|
+
}, {
|
|
3283
|
+
name: 'instanceId',
|
|
3284
|
+
type: 'string | number',
|
|
3285
|
+
description: 'Define an id prefix for the select components e.g. {your-id}-value'
|
|
3286
|
+
}, {
|
|
3287
|
+
name: 'isClearable',
|
|
3288
|
+
type: 'boolean',
|
|
3289
|
+
description: 'Is the select value clearable'
|
|
3290
|
+
}, {
|
|
3291
|
+
name: 'isDisabled',
|
|
3292
|
+
type: 'boolean',
|
|
3293
|
+
description: 'Is the select disabled'
|
|
3294
|
+
}, {
|
|
3295
|
+
name: 'isInvalid',
|
|
3296
|
+
type: 'boolean',
|
|
3297
|
+
description: 'Is the select invalid'
|
|
3298
|
+
}, {
|
|
3299
|
+
name: 'isLoading',
|
|
3300
|
+
type: 'boolean',
|
|
3301
|
+
description: 'Is the select in a state of loading (async)\nIs the select in a state of loading (async)\nWill cause the select to be displayed in the loading state, even if the\nAsync select is not currently waiting for loadOptions to resolve'
|
|
3302
|
+
}, {
|
|
3303
|
+
name: 'isMulti',
|
|
3304
|
+
type: 'boolean',
|
|
3305
|
+
description: 'Support multiple selected options'
|
|
3306
|
+
}, {
|
|
3307
|
+
name: 'isOptionDisabled',
|
|
3308
|
+
type: '(option: Option, selectValue: Options<Option>) => boolean',
|
|
3309
|
+
description: 'Override the built-in logic to detect whether an option is disabled\n\nAn example can be found in the [Replacing builtins](https://react-select.com/advanced#replacing-builtins) documentation.'
|
|
3310
|
+
}, {
|
|
3311
|
+
name: 'isOptionSelected',
|
|
3312
|
+
type: '(option: Option, selectValue: Options<Option>) => boolean',
|
|
3313
|
+
description: 'Override the built-in logic to detect whether an option is selected'
|
|
3314
|
+
}, {
|
|
3315
|
+
name: 'isRequired',
|
|
3316
|
+
type: 'boolean',
|
|
3317
|
+
description: 'This prop indicates if the component is required.'
|
|
3318
|
+
}, {
|
|
3319
|
+
name: 'isSearchable',
|
|
3320
|
+
type: 'boolean',
|
|
3321
|
+
description: 'Whether to enable search functionality'
|
|
3322
|
+
}, {
|
|
3323
|
+
name: 'isValidNewOption',
|
|
3324
|
+
type: 'any',
|
|
3325
|
+
description: 'Determines whether the "create new ..." option should be displayed based on\nthe current input value, select value and options array.'
|
|
3326
|
+
}, {
|
|
3327
|
+
name: 'label',
|
|
3328
|
+
type: 'string',
|
|
3329
|
+
description: 'This sets the aria-label attribute. It sets an accessible name for the select, for people who use assistive technology. Use of a visible label is highly recommended for greater accessibility support.'
|
|
3330
|
+
}, {
|
|
3331
|
+
name: 'labelId',
|
|
3332
|
+
type: 'string',
|
|
3333
|
+
description: 'This sets the aria-labelledby attribute. It sets an accessible name for the select, for people who use assistive technology. Use of a visible label is highly recommended for greater accessibility support.'
|
|
3334
|
+
}, {
|
|
3335
|
+
name: 'loadingMessage',
|
|
3336
|
+
type: '(obj: { inputValue: string; }) => React.ReactNode',
|
|
3337
|
+
description: 'Async: Text to display when loading options'
|
|
3338
|
+
}, {
|
|
3339
|
+
name: 'loadOptions',
|
|
3340
|
+
type: 'any',
|
|
3341
|
+
description: 'Function that returns a promise, which is the set of options to be used\nonce the promise resolves.'
|
|
3342
|
+
}, {
|
|
3343
|
+
name: 'maxMenuHeight',
|
|
3344
|
+
type: 'number',
|
|
3345
|
+
description: 'Maximum height of the menu before scrolling'
|
|
3346
|
+
}, {
|
|
3347
|
+
name: 'menuIsOpen',
|
|
3348
|
+
type: 'boolean',
|
|
3349
|
+
description: 'Whether the menu is open'
|
|
3350
|
+
}, {
|
|
3351
|
+
name: 'menuPlacement',
|
|
3352
|
+
type: '"auto" | "bottom" | "top"',
|
|
3353
|
+
description: "Default placement of the menu in relation to the control. 'auto' will flip\nwhen there isn't enough space below the control."
|
|
3354
|
+
}, {
|
|
3355
|
+
name: 'menuPortalTarget',
|
|
3356
|
+
type: 'HTMLElement',
|
|
3357
|
+
description: 'Whether the menu should use a portal, and where it should attach\n\nAn example can be found in the [Portaling](https://react-select.com/advanced#portaling) documentation'
|
|
3358
|
+
}, {
|
|
3359
|
+
name: 'menuPosition',
|
|
3360
|
+
type: '"absolute" | "fixed"',
|
|
3361
|
+
description: 'The CSS position value of the menu, when "fixed" extra layout management is required'
|
|
3362
|
+
}, {
|
|
3363
|
+
name: 'menuShouldScrollIntoView',
|
|
3364
|
+
type: 'boolean',
|
|
3365
|
+
description: 'Whether the menu should be scrolled into view when it opens'
|
|
3366
|
+
}, {
|
|
3367
|
+
name: 'minMenuHeight',
|
|
3368
|
+
type: 'number',
|
|
3369
|
+
description: 'Minimum height of the menu before flipping'
|
|
3370
|
+
}, {
|
|
3371
|
+
name: 'name',
|
|
3372
|
+
type: 'string',
|
|
3373
|
+
description: 'Name of the HTML Input (optional - without this, no input will be rendered)'
|
|
3374
|
+
}, {
|
|
3375
|
+
name: 'noOptionsMessage',
|
|
3376
|
+
type: '((obj: { inputValue: string; }) => React.ReactNode) | ((obj: { inputValue: string; }) => React.ReactNode)',
|
|
3377
|
+
description: 'Text to display when there are no options'
|
|
3378
|
+
}, {
|
|
3379
|
+
name: 'onBlur',
|
|
3380
|
+
type: '(event: React.FocusEvent<HTMLInputElement, Element>) => void',
|
|
3381
|
+
description: 'Handle blur events on the control'
|
|
3382
|
+
}, {
|
|
3383
|
+
name: 'onChange',
|
|
3384
|
+
type: '(newValue: OnChangeValue<Option, IsMulti>, actionMeta: ActionMeta<Option>) => void',
|
|
3385
|
+
description: 'Handle change events on the select'
|
|
3386
|
+
}, {
|
|
3387
|
+
name: 'onClickPreventDefault',
|
|
3388
|
+
type: 'boolean'
|
|
3389
|
+
}, {
|
|
3390
|
+
name: 'onCreateOption',
|
|
3391
|
+
type: 'any',
|
|
3392
|
+
description: 'If provided, this will be called with the input value when a new option is\ncreated, and `onChange` will **not** be called. Use this when you need more\ncontrol over what happens when new options are created.'
|
|
3393
|
+
}, {
|
|
3394
|
+
name: 'onFocus',
|
|
3395
|
+
type: '(event: React.FocusEvent<HTMLInputElement, Element>) => void',
|
|
3396
|
+
description: 'Handle focus events on the control'
|
|
3397
|
+
}, {
|
|
3398
|
+
name: 'onInputChange',
|
|
3399
|
+
type: '(newValue: string, actionMeta: InputActionMeta) => void',
|
|
3400
|
+
description: 'Handle change events on the input'
|
|
3401
|
+
}, {
|
|
3402
|
+
name: 'onKeyDown',
|
|
3403
|
+
type: '(event: React.KeyboardEvent<HTMLDivElement>) => void',
|
|
3404
|
+
description: 'Handle key down events on the select'
|
|
3405
|
+
}, {
|
|
3406
|
+
name: 'onMenuClose',
|
|
3407
|
+
type: '() => void',
|
|
3408
|
+
description: 'Handle the menu closing'
|
|
3409
|
+
}, {
|
|
3410
|
+
name: 'onMenuOpen',
|
|
3411
|
+
type: '() => void',
|
|
3412
|
+
description: 'Handle the menu opening'
|
|
3413
|
+
}, {
|
|
3414
|
+
name: 'onMenuScrollToBottom',
|
|
3415
|
+
type: '(event: WheelEvent | TouchEvent) => void',
|
|
3416
|
+
description: 'Fired when the user scrolls to the bottom of the menu'
|
|
3417
|
+
}, {
|
|
3418
|
+
name: 'onMenuScrollToTop',
|
|
3419
|
+
type: '(event: WheelEvent | TouchEvent) => void',
|
|
3420
|
+
description: 'Fired when the user scrolls to the top of the menu'
|
|
3421
|
+
}, {
|
|
3422
|
+
name: 'options',
|
|
3423
|
+
type: 'readonly (Option | GroupBase<Option>)[]',
|
|
3424
|
+
description: 'Array of options that populate the select menu'
|
|
3425
|
+
}, {
|
|
3426
|
+
name: 'pageSize',
|
|
3427
|
+
type: 'number',
|
|
3428
|
+
description: 'Number of options to jump in menu when page{up|down} keys are used'
|
|
3429
|
+
}, {
|
|
3430
|
+
name: 'placeholder',
|
|
3431
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
3432
|
+
description: 'Placeholder for the select value'
|
|
3433
|
+
}, {
|
|
3434
|
+
name: 'shouldKeepInputOnSelect',
|
|
3435
|
+
type: 'boolean',
|
|
3436
|
+
description: 'If `true`, the input value will be kept when an option is selected and isMulti is `true`. The default is `false`.'
|
|
3437
|
+
}, {
|
|
3438
|
+
name: 'shouldPreventEscapePropagation',
|
|
3439
|
+
type: 'boolean',
|
|
3440
|
+
description: 'Prevents "Escape" keydown event propagation'
|
|
3441
|
+
}, {
|
|
3442
|
+
name: 'spacing',
|
|
3443
|
+
type: '"compact" | "default"',
|
|
3444
|
+
description: 'This prop affects the height of the select control. Compact is gridSize() * 4, default is gridSize * 5'
|
|
3445
|
+
}, {
|
|
3446
|
+
name: 'tabIndex',
|
|
3447
|
+
type: 'number',
|
|
3448
|
+
description: "Sets the tabIndex attribute on the input for focus. Since focus is already managed, the only acceptable value to be used is '-1' in rare cases when removing this field from the document tab order is required."
|
|
3449
|
+
}, {
|
|
3450
|
+
name: 'value',
|
|
3451
|
+
type: 'Option | MultiValue<Option>',
|
|
3452
|
+
description: 'The value of the select; reflected by the selected option'
|
|
3453
|
+
}]
|
|
3454
|
+
}, {
|
|
3455
|
+
name: 'Skeleton',
|
|
3456
|
+
package: '@atlaskit/skeleton',
|
|
3457
|
+
description: 'A skeleton acts as a placeholder for content, usually while the content loads.',
|
|
3458
|
+
status: 'early-access',
|
|
3459
|
+
usageGuidelines: ['Use to indicate content is loading', 'Match skeleton structure to actual content layout', 'Use appropriate animation and timing', 'Replace with actual content when ready', 'Consider different skeleton patterns for different content types'],
|
|
3460
|
+
contentGuidelines: ['Use skeleton patterns that represent actual content structure', 'Maintain consistent skeleton styling', 'Consider content hierarchy in skeleton design', 'Use appropriate animation timing'],
|
|
3461
|
+
accessibilityGuidelines: ['Provide appropriate loading announcements', 'Use skeleton patterns that match actual content structure', 'Ensure skeleton content is not announced as actual content', 'Consider screen reader experience during loading states'],
|
|
3462
|
+
keywords: ['skeleton', 'placeholder', 'loading', 'content', 'shimmer', 'animation'],
|
|
3463
|
+
category: 'loading',
|
|
3464
|
+
examples: ['import Skeleton from \'@atlaskit/skeleton\';\nconst _default_1: React.JSX.Element[] = [<Skeleton width="200px" height="100px" isShimmering />];\nexport default _default_1;'],
|
|
3465
|
+
props: [{
|
|
3466
|
+
name: 'borderRadius',
|
|
3467
|
+
type: 'string | number',
|
|
3468
|
+
description: "Controls the border radius, or rounding of the skeleton's corners.",
|
|
3469
|
+
defaultValue: '"var(--ds-radius-small)"'
|
|
3470
|
+
}, {
|
|
3471
|
+
name: 'color',
|
|
3472
|
+
type: 'string',
|
|
3473
|
+
description: 'Overrides the default color of skeleton, and overrides the default shimmering start color if ShimmeringEndColor also provided.'
|
|
3474
|
+
}, {
|
|
3475
|
+
name: 'groupName',
|
|
3476
|
+
type: 'string',
|
|
3477
|
+
description: 'Applied as a data-attribute. Use this to target groups of skeletons with the same name (e.g. for applying custom styles)\n```\ngroupName="my-skeleton" -> <div data-my-skeleton>\n```'
|
|
3478
|
+
}, {
|
|
3479
|
+
name: 'height',
|
|
3480
|
+
type: 'string | number',
|
|
3481
|
+
isRequired: true
|
|
3482
|
+
}, {
|
|
3483
|
+
name: 'isShimmering',
|
|
3484
|
+
type: 'boolean',
|
|
3485
|
+
description: 'Enables the shimmering animation.',
|
|
3486
|
+
defaultValue: 'false'
|
|
3487
|
+
}, {
|
|
3488
|
+
name: 'ShimmeringEndColor',
|
|
3489
|
+
type: 'string',
|
|
3490
|
+
description: 'Overrides the default shimmering ending color of skeleton.'
|
|
3491
|
+
}, {
|
|
3492
|
+
name: 'width',
|
|
3493
|
+
type: 'string | number',
|
|
3494
|
+
isRequired: true
|
|
3495
|
+
}]
|
|
3496
|
+
}, {
|
|
3497
|
+
name: 'Spinner',
|
|
3498
|
+
package: '@atlaskit/spinner',
|
|
3499
|
+
description: 'A loading spinner component.',
|
|
3500
|
+
status: 'general-availability',
|
|
3501
|
+
usageGuidelines: ['Use for loading states of unknown duration', 'Consider delay before showing spinner', 'Use appropriate size for context', 'Provide loading context when possible'],
|
|
3502
|
+
contentGuidelines: ['Use consistent spinner sizing', 'Consider spinner placement and context', 'Provide loading feedback when appropriate'],
|
|
3503
|
+
accessibilityGuidelines: ['Provide appropriate loading announcements', 'Use appropriate timing for spinner display', 'Ensure spinner is announced to screen readers', 'Consider alternative loading indicators'],
|
|
3504
|
+
keywords: ['spinner', 'loading', 'progress', 'wait', 'activity'],
|
|
3505
|
+
category: 'feedback',
|
|
3506
|
+
examples: ['import Spinner from \'@atlaskit/spinner\';\nconst _default_1: React.JSX.Element[] = [\n\t<Spinner size="small" />,\n\t<Spinner size="medium" />,\n\t<Spinner size="large" />,\n];\nexport default _default_1;'],
|
|
3507
|
+
props: [{
|
|
3508
|
+
name: 'appearance',
|
|
3509
|
+
type: '"inherit" | "invert"',
|
|
3510
|
+
description: 'You can use this to invert the current theme.\nThis is useful when you are displaying a spinner on a background that is not the same background color scheme as the main content.'
|
|
3511
|
+
}, {
|
|
3512
|
+
name: 'delay',
|
|
3513
|
+
type: 'number',
|
|
3514
|
+
description: 'Delay the intro animation of `Spinner`.\nThis is not to be used to avoid quick flickering of `Spinner`.\n`Spinner` will automatically fade in and takes ~200ms to become partially visible.\nThis prop can be helpful for **long delays** such as `500-1000ms` for when you want to not\nshow a `Spinner` until some longer period of time has elapsed.'
|
|
3515
|
+
}, {
|
|
3516
|
+
name: 'label',
|
|
3517
|
+
type: 'string',
|
|
3518
|
+
description: 'Describes what the spinner is doing for assistive technologies. For example, "loading", "submitting", or "processing".'
|
|
3519
|
+
}, {
|
|
3520
|
+
name: 'size',
|
|
3521
|
+
type: 'number | PresetSize',
|
|
3522
|
+
description: 'Size of the spinner. The available sizes are `xsmall`, `small`, `medium`, `large`, and `xlarge`. For most use cases, we recommend `medium`.'
|
|
3523
|
+
}]
|
|
3524
|
+
}, {
|
|
3525
|
+
name: 'Tabs',
|
|
3526
|
+
package: '@atlaskit/tabs',
|
|
3527
|
+
description: 'Tabs are used to organize content by grouping similar information on the same page.',
|
|
3528
|
+
status: 'general-availability',
|
|
3529
|
+
usageGuidelines: ['Use to organize related content on the same page without navigating away', 'Use for concise content or content users access regularly', 'Limit the number of tabs to avoid overcrowding', 'Keep tab labels concise and descriptive', 'Use consistent tab ordering and grouping', 'Consider responsive behavior for many tabs'],
|
|
3530
|
+
contentGuidelines: ['Write clear, descriptive tab labels', 'Group related content logically', 'Use consistent naming conventions', 'Ensure tab content is relevant and complete'],
|
|
3531
|
+
accessibilityGuidelines: ['Ensure proper keyboard navigation between tabs', 'Use appropriate ARIA attributes for tab panels', 'Provide clear focus indicators', 'Announce tab changes to screen readers', 'Ensure tab content is accessible'],
|
|
3532
|
+
keywords: ['tabs', 'navigation', 'content', 'organization', 'grouping'],
|
|
3533
|
+
category: 'navigation',
|
|
3534
|
+
examples: ['import Tabs, { Tab, TabList, TabPanel } from \'@atlaskit/tabs\';\nconst Example = (): React.JSX.Element => (\n\t<Tabs id="tabs">\n\t\t<TabList>\n\t\t\t<Tab>Tab 1</Tab>\n\t\t\t<Tab>Tab 2</Tab>\n\t\t</TabList>\n\t\t<TabPanel>Content for Tab 1</TabPanel>\n\t\t<TabPanel>Content for Tab 2</TabPanel>\n\t</Tabs>\n);\nexport default Example;'],
|
|
3535
|
+
props: [{
|
|
3536
|
+
name: 'children',
|
|
3537
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<ReactNode> | React.ReactPortal',
|
|
3538
|
+
description: "The children of Tabs. The first child should be a `TabList` filled with `Tab`'s.\nSubsequent children should be `TabPanel`'s. There should be a `Tab` for each `TabPanel`.\nIf you want to customize `Tab` or `TabPanel`, refer to the examples in the documentation.",
|
|
3539
|
+
isRequired: true
|
|
3540
|
+
}, {
|
|
3541
|
+
name: 'defaultSelected',
|
|
3542
|
+
type: 'number',
|
|
3543
|
+
description: 'The index of the tab that will be selected by default when the component mounts.\nIf not set the first tab will be displayed by default.'
|
|
3544
|
+
}, {
|
|
3545
|
+
name: 'id',
|
|
3546
|
+
type: 'string',
|
|
3547
|
+
description: 'A unique ID that will be used to generate IDs for tabs and tab panels.\nThis is required for accessibility purposes.',
|
|
3548
|
+
isRequired: true
|
|
3549
|
+
}, {
|
|
3550
|
+
name: 'onChange',
|
|
3551
|
+
type: '(index: number, analyticsEvent: UIAnalyticsEvent) => void',
|
|
3552
|
+
description: 'A callback function which will be fired when a changed. It will be passed\nthe index of the selected tab and a `UIAnalyticsEvent`.'
|
|
3553
|
+
}, {
|
|
3554
|
+
name: 'selected',
|
|
3555
|
+
type: 'number',
|
|
3556
|
+
description: "The selected tab's index. If this prop is set the component behaves as a\ncontrolled component. It will be up to you to listen to `onChange`."
|
|
3557
|
+
}, {
|
|
3558
|
+
name: 'shouldUnmountTabPanelOnChange',
|
|
3559
|
+
type: 'boolean',
|
|
3560
|
+
description: "Tabs by default leaves `TabPanel`'s mounted on the page after they have been selected.\nIf you would like to unmount a `TabPanel` when it is not selected, set this prop to\nbe true."
|
|
3561
|
+
}]
|
|
3562
|
+
}, {
|
|
3563
|
+
name: 'Tag',
|
|
3564
|
+
package: '@atlaskit/tag',
|
|
3565
|
+
description: 'A tag is a compact element used to categorize, label, or organize content.',
|
|
3566
|
+
status: 'general-availability',
|
|
3567
|
+
usageGuidelines: ['Use to categorize or label content', 'Keep tag text concise and meaningful', 'Use appropriate colors and appearances', 'Consider tag removal functionality', 'Group related tags logically'],
|
|
3568
|
+
contentGuidelines: ['Use clear, descriptive tag labels', 'Keep tag text concise', 'Use consistent terminology across tags', 'Consider tag hierarchy and grouping'],
|
|
3569
|
+
accessibilityGuidelines: ['Provide appropriate labels for tags', 'Ensure sufficient color contrast for text readability', 'Use clear, descriptive tag text', 'Consider keyboard navigation for interactive tags', 'Provide alternative text for tag removal actions'],
|
|
3570
|
+
keywords: ['tag', 'label', 'category', 'filter', 'chip', 'badge'],
|
|
3571
|
+
category: 'data-display',
|
|
3572
|
+
examples: ['import Tag from \'@atlaskit/tag\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Tag text="Basic tag" />\n\t\t<Tag text="Bug" color="red" />\n\t\t<Tag text="Removable tag" removeButtonLabel="Remove" />\n\t</>\n);\nexport default Examples;'],
|
|
3573
|
+
props: [{
|
|
3574
|
+
name: 'appearance',
|
|
3575
|
+
type: '"default" | "rounded"',
|
|
3576
|
+
description: 'Set whether tags are rounded.'
|
|
3577
|
+
}, {
|
|
3578
|
+
name: 'color',
|
|
3579
|
+
type: '"standard" | "green" | "lime" | "blue" | "red" | "purple" | "magenta" | "grey" | "gray" | "teal" | "orange" | "yellow" | "limeLight" | "orangeLight" | "magentaLight" | "greenLight" | ... 5 more ... | "yellowLight"',
|
|
3580
|
+
description: 'The color theme to apply. This sets both the background and text color.'
|
|
3581
|
+
}, {
|
|
3582
|
+
name: 'elemBefore',
|
|
3583
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
3584
|
+
description: 'The component to be rendered before the tag.'
|
|
3585
|
+
}, {
|
|
3586
|
+
name: 'href',
|
|
3587
|
+
type: 'string',
|
|
3588
|
+
description: 'URI or path. If provided, the tag will be a link.'
|
|
3589
|
+
}, {
|
|
3590
|
+
name: 'isRemovable',
|
|
3591
|
+
type: 'boolean',
|
|
3592
|
+
description: 'Flag to indicate if a tag is removable.'
|
|
3593
|
+
}, {
|
|
3594
|
+
name: 'linkComponent',
|
|
3595
|
+
type: 'ComponentClass<any, any> | FunctionComponent<any>'
|
|
3596
|
+
}, {
|
|
3597
|
+
name: 'maxWidth',
|
|
3598
|
+
type: 'string | number',
|
|
3599
|
+
description: "Maximum width of the tag text. When exceeded, text will be truncated with ellipsis.\nAccepts any valid CSS max-width value (e.g., '200px', '15rem', '100%')."
|
|
3600
|
+
}, {
|
|
3601
|
+
name: 'migration_fallback',
|
|
3602
|
+
type: 'string',
|
|
3603
|
+
description: "@internal\n**Temporary / Internal only for migration.**\n\nWhen set to `'lozenge'` and the feature flag `platform-dst-lozenge-tag-badge-visual-uplifts`\nis OFF, renders as a Lozenge component instead of Tag. This enables safe, staged migration\nfrom Lozenge to Tag for large consumers.\n\nThis prop will be removed via codemod after migration is complete."
|
|
3604
|
+
}, {
|
|
3605
|
+
name: 'onAfterRemoveAction',
|
|
3606
|
+
type: '(text: string) => void',
|
|
3607
|
+
description: "Handler to be called after tag is removed. Called with the string 'Post\nRemoval Hook'."
|
|
3608
|
+
}, {
|
|
3609
|
+
name: 'onBeforeRemoveAction',
|
|
3610
|
+
type: '() => boolean',
|
|
3611
|
+
description: 'Handler to be called before the tag is removed. If it does not return a\ntruthy value, the tag will not be removed.'
|
|
3612
|
+
}, {
|
|
3613
|
+
name: 'removeButtonLabel',
|
|
3614
|
+
type: 'string',
|
|
3615
|
+
description: 'Text rendered as the aria-label for remove button.'
|
|
3616
|
+
}, {
|
|
3617
|
+
name: 'text',
|
|
3618
|
+
type: 'string',
|
|
3619
|
+
description: 'Text to be displayed in the tag.',
|
|
3620
|
+
isRequired: true
|
|
3621
|
+
}]
|
|
3622
|
+
}, {
|
|
3623
|
+
name: 'TagGroup',
|
|
3624
|
+
package: '@atlaskit/tag-group',
|
|
3625
|
+
description: 'A component for managing multiple tags.',
|
|
3626
|
+
status: 'general-availability',
|
|
3627
|
+
usageGuidelines: ['Use for grouping related tags', 'Consider tag alignment and spacing', 'Use for categorizing content', 'Provide clear tag relationships'],
|
|
3628
|
+
contentGuidelines: ['Use consistent tag naming', 'Keep tag text concise', 'Use meaningful tag categories', 'Consider tag hierarchy'],
|
|
3629
|
+
accessibilityGuidelines: ['Provide clear tag labels', 'Ensure proper keyboard navigation', 'Use appropriate grouping semantics', 'Consider screen reader announcements'],
|
|
3630
|
+
keywords: ['tag', 'group', 'multiple', 'labels', 'chips'],
|
|
3631
|
+
category: 'data-display',
|
|
3632
|
+
examples: ['import Tag from \'@atlaskit/tag\';\nimport TagGroup from \'@atlaskit/tag-group\';\nconst Example = (): React.JSX.Element => (\n\t<TagGroup label="Tags for work item">\n\t\t<Tag text="Priority: High" color="red" />\n\t\t<Tag text="Status: Active" color="green" />\n\t\t<Tag text="Type: Bug" color="blue" />\n\t</TagGroup>\n);\nexport default Example;'],
|
|
3633
|
+
props: [{
|
|
3634
|
+
name: 'alignment',
|
|
3635
|
+
type: '"start" | "end"',
|
|
3636
|
+
description: 'Sets whether the tags should be aligned to the start or the end of the component.'
|
|
3637
|
+
}, {
|
|
3638
|
+
name: 'children',
|
|
3639
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
3640
|
+
description: 'Tags to render within the tag group.',
|
|
3641
|
+
isRequired: true
|
|
3642
|
+
}, {
|
|
3643
|
+
name: 'label',
|
|
3644
|
+
type: 'string',
|
|
3645
|
+
description: 'Refers to an `aria-label` attribute. Sets an accessible name for the tags group wrapper to announce it to users of assistive technology.\nUsage of either this, or the `titleId` attribute is strongly recommended.'
|
|
3646
|
+
}, {
|
|
3647
|
+
name: 'titleId',
|
|
3648
|
+
type: 'string',
|
|
3649
|
+
description: "ID referenced by the tag group wrapper's `aria-labelledby` attribute. This ID should be assigned to the group-button title element.\nUsage of either this, or the `label` attribute is strongly recommended."
|
|
3650
|
+
}]
|
|
3651
|
+
}, {
|
|
3652
|
+
name: 'Textarea',
|
|
3653
|
+
package: '@atlaskit/textarea',
|
|
3654
|
+
description: 'A textarea is a multiline text input control for longer text content.',
|
|
3655
|
+
status: 'general-availability',
|
|
3656
|
+
usageGuidelines: ['Use for long-form, multi-line text in forms', 'Expandable height; label and optional helper text', 'Do not use placeholder for critical info—use label or helper text', 'Use TextField for short, single-line input'],
|
|
3657
|
+
contentGuidelines: ['Label as noun string (e.g. "Description" not "Modal title + Description")', 'Use helper text to clarify; do not put critical info in placeholder', 'Provide appropriate error messages', 'Consider content length and formatting'],
|
|
3658
|
+
accessibilityGuidelines: ['Ensure label is associated with the textarea', 'Do not use placeholder for critical info—use label or helper (search exception only with icon + accessible label)', 'Provide clear labels for all textareas', 'Provide keyboard navigation support', 'Indicate required fields clearly', 'Use appropriate error states and messaging'],
|
|
3659
|
+
keywords: ['textarea', 'input', 'form', 'text', 'multiline', 'input', 'field'],
|
|
3660
|
+
category: 'forms-and-input',
|
|
3661
|
+
examples: ['import Textarea from \'@atlaskit/textarea\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Textarea placeholder="Enter your text..." />\n\t\t<Textarea placeholder="Required field" isRequired resize="auto" name="comments" />\n\t</>\n);\nexport default Examples;'],
|
|
3662
|
+
props: [{
|
|
3663
|
+
name: 'appearance',
|
|
3664
|
+
type: '"standard" | "subtle" | "none"',
|
|
3665
|
+
description: "Controls the appearance of the field.\nSubtle shows styling on hover.\nNone prevents all field styling. Take care when using the none appearance as this doesn't include accessible interactions."
|
|
3666
|
+
}, {
|
|
3667
|
+
name: 'defaultValue',
|
|
3668
|
+
type: 'string',
|
|
3669
|
+
description: 'The default value of the text area.'
|
|
3670
|
+
}, {
|
|
3671
|
+
name: 'isCompact',
|
|
3672
|
+
type: 'boolean',
|
|
3673
|
+
description: 'Sets whether the field should expand to fill available horizontal space.'
|
|
3674
|
+
}, {
|
|
3675
|
+
name: 'isDisabled',
|
|
3676
|
+
type: 'boolean',
|
|
3677
|
+
description: 'Sets the field as uneditable, with a changed hover state, and prevents it from showing in the focus order.\nWherever possible, prefer using validation and error messaging over disabled fields for a more accessible experience.'
|
|
3678
|
+
}, {
|
|
3679
|
+
name: 'isInvalid',
|
|
3680
|
+
type: 'boolean',
|
|
3681
|
+
description: 'Sets styling to indicate that the input is invalid.'
|
|
3682
|
+
}, {
|
|
3683
|
+
name: 'isMonospaced',
|
|
3684
|
+
type: 'boolean',
|
|
3685
|
+
description: 'Sets the content text value to monospace.'
|
|
3686
|
+
}, {
|
|
3687
|
+
name: 'isReadOnly',
|
|
3688
|
+
type: 'boolean',
|
|
3689
|
+
description: 'If true, prevents the value of the input from being edited.'
|
|
3690
|
+
}, {
|
|
3691
|
+
name: 'isRequired',
|
|
3692
|
+
type: 'boolean',
|
|
3693
|
+
description: 'Sets whether the field is required for form that the field is part of.'
|
|
3694
|
+
}, {
|
|
3695
|
+
name: 'maxHeight',
|
|
3696
|
+
type: 'string',
|
|
3697
|
+
description: 'The maximum height of the text area.'
|
|
3698
|
+
}, {
|
|
3699
|
+
name: 'minimumRows',
|
|
3700
|
+
type: 'number',
|
|
3701
|
+
description: 'The minimum number of rows of text to display.'
|
|
3702
|
+
}, {
|
|
3703
|
+
name: 'name',
|
|
3704
|
+
type: 'string',
|
|
3705
|
+
description: 'Name of the input form control.'
|
|
3706
|
+
}, {
|
|
3707
|
+
name: 'onBlur',
|
|
3708
|
+
type: '(event: FocusEvent<HTMLTextAreaElement, Element>) => void',
|
|
3709
|
+
description: 'Handler to be called when the input is blurred.'
|
|
3710
|
+
}, {
|
|
3711
|
+
name: 'onChange',
|
|
3712
|
+
type: '(event: ChangeEvent<HTMLTextAreaElement>) => void',
|
|
3713
|
+
description: 'Handler to be called when the input changes.'
|
|
3714
|
+
}, {
|
|
3715
|
+
name: 'onFocus',
|
|
3716
|
+
type: '(event: FocusEvent<HTMLTextAreaElement, Element>) => void',
|
|
3717
|
+
description: 'Handler to be called when the input is focused.'
|
|
3718
|
+
}, {
|
|
3719
|
+
name: 'placeholder',
|
|
3720
|
+
type: 'string',
|
|
3721
|
+
description: "The placeholder text within the text area. Don't use placeholder text to provide instructions as it disappears on data entry."
|
|
3722
|
+
}, {
|
|
3723
|
+
name: 'resize',
|
|
3724
|
+
type: '"none" | "auto" | "vertical" | "horizontal" | "smart"',
|
|
3725
|
+
description: 'Enables resizing of the text area. The default setting is `smart`.\nAuto enables resizing in both directions.\nHorizontal enables resizing only along the X axis.\nVertical enables resizing only along the Y axis.\nSmart vertically grows and shrinks the text area automatically to wrap your input text.\nNone explicitly disallows resizing of the text area.'
|
|
3726
|
+
}, {
|
|
3727
|
+
name: 'spellCheck',
|
|
3728
|
+
type: 'boolean',
|
|
3729
|
+
description: 'Enables native spell check on the `textarea` element.'
|
|
3730
|
+
}, {
|
|
3731
|
+
name: 'theme',
|
|
3732
|
+
type: 'any',
|
|
3733
|
+
description: 'The theme function `TextArea` consumes to derive theming constants for use in styling its components'
|
|
3734
|
+
}, {
|
|
3735
|
+
name: 'value',
|
|
3736
|
+
type: 'string',
|
|
3737
|
+
description: 'The value of the text area.'
|
|
3738
|
+
}]
|
|
3739
|
+
}, {
|
|
3740
|
+
name: 'TextField',
|
|
3741
|
+
package: '@atlaskit/textfield',
|
|
3742
|
+
description: 'A single-line text input component.',
|
|
3743
|
+
status: 'general-availability',
|
|
3744
|
+
usageGuidelines: ['Use for single-line text in forms, modals, search, cards', 'Label is required (above input); helper text optional', 'Do not use placeholder for critical info—use label or helper text (search exception: search icon + accessible label)', 'Consider character limits and validation'],
|
|
3745
|
+
contentGuidelines: ['Write clear, short labels', 'Use helper text for examples/formatting; keep helper visible after input', 'Provide appropriate error messages', 'Consider content length and formatting'],
|
|
3746
|
+
accessibilityGuidelines: ['Use visible label or proper association; do not use placeholder for critical info—use label or helper (search is exception with icon + accessible label)', 'Do not nest interactive elements (causes focus issues)', 'Custom validation: validate onBlur; use error container with aria-live="polite" and aria-relevant/aria-atomic for dynamic announcements', 'Provide clear labels for all textfields', 'Provide keyboard navigation support', 'Indicate required fields clearly', 'Use appropriate error states and messaging'],
|
|
3747
|
+
keywords: ['textfield', 'input', 'form', 'text', 'field', 'single-line'],
|
|
3748
|
+
category: 'form',
|
|
3749
|
+
examples: ['import TextField from \'@atlaskit/textfield\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<TextField label="Name" placeholder="Enter your name" />\n\t\t<TextField label="Email" type="email" placeholder="Enter your email address" isRequired />\n\t\t<TextField label="Password" type="password" placeholder="Enter your password" isRequired />\n\t</>\n);\nexport default Examples;'],
|
|
3750
|
+
props: [{
|
|
3751
|
+
name: 'appearance',
|
|
3752
|
+
type: '"subtle" | "standard" | "none"',
|
|
3753
|
+
description: "Controls the appearance of the field.\nSubtle shows styling on hover.\nNone prevents all field styling. Take care when using the none appearance as this doesn't include accessible interactions."
|
|
3754
|
+
}, {
|
|
3755
|
+
name: 'elemAfterInput',
|
|
3756
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
3757
|
+
description: 'Element after input in text field.'
|
|
3758
|
+
}, {
|
|
3759
|
+
name: 'elemBeforeInput',
|
|
3760
|
+
type: 'string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | Iterable<ReactNode> | ReactPortal',
|
|
3761
|
+
description: 'Element before input in text field.'
|
|
3762
|
+
}, {
|
|
3763
|
+
name: 'isCompact',
|
|
3764
|
+
type: 'boolean',
|
|
3765
|
+
description: 'Applies compact styling, making the field smaller.'
|
|
3766
|
+
}, {
|
|
3767
|
+
name: 'isDisabled',
|
|
3768
|
+
type: 'boolean',
|
|
3769
|
+
description: "Sets the field as to appear disabled,\npeople will not be able to interact with the text field and it won't appear in the focus order.\nWherever possible, prefer using validation and error messaging over disabled fields for a more accessible experience."
|
|
3770
|
+
}, {
|
|
3771
|
+
name: 'isInvalid',
|
|
3772
|
+
type: 'boolean',
|
|
3773
|
+
description: 'Changes the text field to have a border indicating that its value is invalid.'
|
|
3774
|
+
}, {
|
|
3775
|
+
name: 'isMonospaced',
|
|
3776
|
+
type: 'boolean',
|
|
3777
|
+
description: 'Sets content text value to appear monospaced.'
|
|
3778
|
+
}, {
|
|
3779
|
+
name: 'isReadOnly',
|
|
3780
|
+
type: 'boolean',
|
|
3781
|
+
description: 'If true, prevents the value of the input from being edited.'
|
|
3782
|
+
}, {
|
|
3783
|
+
name: 'isRequired',
|
|
3784
|
+
type: 'boolean',
|
|
3785
|
+
description: 'Set required for form that the field is part of.'
|
|
3786
|
+
}, {
|
|
3787
|
+
name: 'name',
|
|
3788
|
+
type: 'string',
|
|
3789
|
+
description: 'Name of the input element.'
|
|
3790
|
+
}, {
|
|
3791
|
+
name: 'onChange',
|
|
3792
|
+
type: '(event: FormEvent<HTMLInputElement>) => void',
|
|
3793
|
+
description: 'Handler called when the inputs value changes.'
|
|
3794
|
+
}, {
|
|
3795
|
+
name: 'onMouseDown',
|
|
3796
|
+
type: '(event: MouseEvent<HTMLElement, globalThis.MouseEvent>) => void',
|
|
3797
|
+
description: 'Handler called when the mouse down event is triggered on the input element.'
|
|
3798
|
+
}, {
|
|
3799
|
+
name: 'placeholder',
|
|
3800
|
+
type: 'string',
|
|
3801
|
+
description: 'Placeholder text to display in the text field whenever it is empty.'
|
|
3802
|
+
}, {
|
|
3803
|
+
name: 'width',
|
|
3804
|
+
type: 'string | number',
|
|
3805
|
+
description: 'Sets maximum width of input.'
|
|
3806
|
+
}]
|
|
3807
|
+
}, {
|
|
3808
|
+
name: 'Toggle',
|
|
3809
|
+
package: '@atlaskit/toggle',
|
|
3810
|
+
description: 'A toggle is used to view or switch between enabled or disabled states.',
|
|
3811
|
+
status: 'general-availability',
|
|
3812
|
+
usageGuidelines: ['Use for binary on/off states', "Provide clear labels that describe the toggle's function", 'Use appropriate default states', 'Consider immediate vs. delayed state changes', 'Use consistent toggle behavior across the interface'],
|
|
3813
|
+
contentGuidelines: ['Write clear, descriptive labels', 'Use action-oriented language when appropriate', 'Ensure labels clearly indicate what the toggle controls', 'Use consistent terminology across toggles'],
|
|
3814
|
+
accessibilityGuidelines: ['Provide clear labels for all toggles', 'Use appropriate ARIA attributes for toggle state', 'Ensure keyboard navigation support', 'Provide clear visual feedback for state changes', "Use descriptive labels that explain the toggle's purpose"],
|
|
3815
|
+
keywords: ['toggle', 'switch', 'on-off', 'enabled', 'disabled', 'state'],
|
|
3816
|
+
category: 'forms-and-input',
|
|
3817
|
+
examples: ['import Toggle from \'@atlaskit/toggle\';\nconst Examples = (): React.JSX.Element => (\n\t<>\n\t\t<Toggle label="Basic toggle" />\n\t\t<Toggle label="Checked toggle" isChecked />\n\t</>\n);\nexport default Examples;'],
|
|
3818
|
+
props: [{
|
|
3819
|
+
name: 'defaultChecked',
|
|
3820
|
+
type: 'boolean',
|
|
3821
|
+
description: 'Sets whether the toggle is initially checked or not.\nAfter the initial interaction, whether the component is checked or not is\ncontrolled by the component.'
|
|
3822
|
+
}, {
|
|
3823
|
+
name: 'descriptionId',
|
|
3824
|
+
type: 'string',
|
|
3825
|
+
description: "Use this when you need to provide an extended description about how the toggle works using aria-describedby.\n\nIt's important to use this prop if the meaning of the toggle with the only a label would be unclear to people who use assistive technology."
|
|
3826
|
+
}, {
|
|
3827
|
+
name: 'id',
|
|
3828
|
+
type: 'string',
|
|
3829
|
+
description: 'Use a pairing label with your toggle using `id` and `htmlFor` props to set the relationship.\nFor more information see [labels on MDN web docs](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label).'
|
|
3830
|
+
}, {
|
|
3831
|
+
name: 'isChecked',
|
|
3832
|
+
type: 'boolean',
|
|
3833
|
+
description: 'If defined, it takes precedence over defaultChecked, and the toggle acts\nas a controlled component.\n\nYou can provide a onChange function to be notified of checked value changes'
|
|
3834
|
+
}, {
|
|
3835
|
+
name: 'isDisabled',
|
|
3836
|
+
type: 'boolean',
|
|
3837
|
+
description: 'Sets if the toggle is disabled or not. This prevents any interaction.\nDisabled toggles will not appear in the tab order for assistive technology.'
|
|
3838
|
+
}, {
|
|
3839
|
+
name: 'isLoading',
|
|
3840
|
+
type: 'boolean',
|
|
3841
|
+
description: "If defined, it displays a spinner within the toggle.\nThis prop is useful when the toggle's state is being fetched or updated asynchronously."
|
|
3842
|
+
}, {
|
|
3843
|
+
name: 'label',
|
|
3844
|
+
type: 'string',
|
|
3845
|
+
description: "Text value which will be associated with toggle input using aria-labelledby attribute.\n\nUse only when you can't use a visible label for the toggle."
|
|
3846
|
+
}, {
|
|
3847
|
+
name: 'name',
|
|
3848
|
+
type: 'string',
|
|
3849
|
+
description: 'Descriptive name for the value property, to be submitted in a form.'
|
|
3850
|
+
}, {
|
|
3851
|
+
name: 'onBlur',
|
|
3852
|
+
type: '(event: FocusEvent<HTMLInputElement, Element>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
3853
|
+
description: 'Handler to be called when toggle is unfocused.'
|
|
3854
|
+
}, {
|
|
3855
|
+
name: 'onChange',
|
|
3856
|
+
type: '(event: ChangeEvent<HTMLInputElement>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
3857
|
+
description: "Handler to be called when native 'change' event happens internally."
|
|
3858
|
+
}, {
|
|
3859
|
+
name: 'onFocus',
|
|
3860
|
+
type: '(event: FocusEvent<HTMLInputElement, Element>, analyticsEvent: UIAnalyticsEvent) => void',
|
|
3861
|
+
description: 'Handler to be called when toggle is focused.'
|
|
3862
|
+
}, {
|
|
3863
|
+
name: 'size',
|
|
3864
|
+
type: '"regular" | "large"',
|
|
3865
|
+
description: 'Toggle size.'
|
|
3866
|
+
}, {
|
|
3867
|
+
name: 'value',
|
|
3868
|
+
type: 'string',
|
|
3869
|
+
description: 'Value to be submitted in a form.'
|
|
3870
|
+
}]
|
|
3871
|
+
}, {
|
|
3872
|
+
name: 'Tooltip',
|
|
3873
|
+
package: '@atlaskit/tooltip',
|
|
3874
|
+
description: 'A tooltip is a floating, non-actionable label used to explain a user interface element or feature.',
|
|
3875
|
+
status: 'general-availability',
|
|
3876
|
+
usageGuidelines: ['Use only on interactive elements (must be focusable for keyboard and screen readers)', 'Opens on hover or focus; content is text only', 'Use with icon buttons for labels; for useful but non-essential info (e.g. shortcuts); for truncated text when truncation is unavoidable', 'Never use on disabled elements (see Button a11y)', 'Do not put critical info in tooltip—use labels, helper text, or inline message', 'No interactive or visual content inside (no links/buttons/icons)—use Popup or Modal', 'Use Inline message for richer/longer content; Popup/Modal for interactive content'],
|
|
3877
|
+
contentGuidelines: ['Keep concise; do not repeat the visible label', 'Use helpful, non-essential information only', 'Icon button and link icon button have their own content guidelines'],
|
|
3878
|
+
accessibilityGuidelines: ['Use only on interactive elements (keyboard focusable; screen reader can reach them)', 'Never use tooltips on disabled elements', 'Do not put critical information in tooltips—use visible labels, helper text, or inline message', 'No links, buttons, or icons inside tooltip—use Popup or Modal for interactive content', 'Keyboard shortcuts shown in tooltip are not exposed to assistive tech—provide an alternative (e.g. panel, dialog)', 'Ensure tooltip content is announced by screen readers', 'Provide keyboard access (hover + focus trigger)'],
|
|
3879
|
+
keywords: ['tooltip', 'hint', 'help', 'floating', 'label', 'explanation'],
|
|
3880
|
+
category: 'overlays-and-layering',
|
|
3881
|
+
examples: ['import Button from \'@atlaskit/button/new\';\nimport Tooltip from \'@atlaskit/tooltip\';\nexport default function DefaultTooltipExample(): React.JSX.Element {\n\treturn (\n\t\t<Tooltip content="This is a tooltip" testId="default-tooltip">\n\t\t\t{(tooltipProps) => <Button {...tooltipProps}>Hover over me</Button>}\n\t\t</Tooltip>\n\t);\n}'],
|
|
3882
|
+
props: [{
|
|
3883
|
+
name: 'canAppear',
|
|
3884
|
+
type: '() => boolean',
|
|
3885
|
+
description: 'Whether or not the tooltip can be displayed. Once a tooltip\nis scheduled to be displayed, or is already displayed, it will\ncontinue to be shown.\n\n@description\n\n`canAppear()` is called in response to user events, and\nnot during the rendering of components.'
|
|
3886
|
+
}, {
|
|
3887
|
+
name: 'children',
|
|
3888
|
+
type: 'React.ReactNode | ((props: TriggerProps) => React.ReactNode)',
|
|
3889
|
+
description: 'Elements to be wrapped by the tooltip.\nIt can be either a:\n1. `ReactNode`\n2. Function which returns a `ReactNode`',
|
|
3890
|
+
isRequired: true
|
|
3891
|
+
}, {
|
|
3892
|
+
name: 'component',
|
|
3893
|
+
type: 'React.ComponentType<TooltipPrimitiveProps> | React.ForwardRefExoticComponent<Omit<TooltipPrimitiveProps, "ref"> & React.RefAttributes<HTMLDivElement>>',
|
|
3894
|
+
description: 'Extend `TooltipPrimitive` to create your own tooltip and pass it as component.'
|
|
3895
|
+
}, {
|
|
3896
|
+
name: 'content',
|
|
3897
|
+
type: 'React.ReactNode | (({ update }: { update?: () => void; }) => React.ReactNode)',
|
|
3898
|
+
description: 'The content of the tooltip. It can be either a:\n1. `ReactNode`\n2. Function which returns a `ReactNode`\nThe benefit of the second approach is that it allows you to consume the `update` render prop.\nThis `update` function can be called to manually recalculate the position of the tooltip.\n\nThis content will be rendered into two places:\n1. Into the tooltip\n2. Into a hidden element for screen readers (unless `isScreenReaderAnnouncementDisabled` is set to `true`)',
|
|
3899
|
+
isRequired: true
|
|
3900
|
+
}, {
|
|
3901
|
+
name: 'delay',
|
|
3902
|
+
type: 'number',
|
|
3903
|
+
description: 'Time in milliseconds to wait before showing and hiding the tooltip. Defaults to 300.',
|
|
3904
|
+
defaultValue: '300'
|
|
3905
|
+
}, {
|
|
3906
|
+
name: 'hideTooltipOnClick',
|
|
3907
|
+
type: 'boolean',
|
|
3908
|
+
description: 'Hide the tooltip when the click event is triggered. Use this when the tooltip should be hidden if `onClick` react synthetic event\nis triggered, which happens after `onMouseDown` event.',
|
|
3909
|
+
defaultValue: 'false'
|
|
3910
|
+
}, {
|
|
3911
|
+
name: 'hideTooltipOnMouseDown',
|
|
3912
|
+
type: 'boolean',
|
|
3913
|
+
description: 'Hide the tooltip when the mousedown event is triggered. This should be\nused when tooltip should be hidden if `onMouseDown` react synthetic event\nis triggered, which happens before `onClick` event.',
|
|
3914
|
+
defaultValue: 'false'
|
|
3915
|
+
}, {
|
|
3916
|
+
name: 'ignoreTooltipPointerEvents',
|
|
3917
|
+
type: 'boolean',
|
|
3918
|
+
description: 'Adds `pointer-events: none` to the tooltip itself. Setting this to true will also prevent the tooltip from persisting when hovered.',
|
|
3919
|
+
defaultValue: 'false'
|
|
3920
|
+
}, {
|
|
3921
|
+
name: 'isScreenReaderAnnouncementDisabled',
|
|
3922
|
+
type: 'boolean',
|
|
3923
|
+
description: 'By default tooltip content will be duplicated into a hidden element so\nit can be read out by a screen reader. Sometimes this is not ideal as\nit can result in the same content be announced twice. For those situations,\nyou can leverage this prop to disable the duplicate hidden text.',
|
|
3924
|
+
defaultValue: 'false'
|
|
3925
|
+
}, {
|
|
3926
|
+
name: 'mousePosition',
|
|
3927
|
+
type: 'AutoPlacement | BasePlacement | VariationPlacement',
|
|
3928
|
+
description: 'Where the tooltip should appear relative to the mouse pointer.\nOnly use this when the `position` prop is set to `"mouse"`, `"mouse-y"`, or `"mouse-x"`.\nWhen interacting with the target element using a keyboard, it will use this position against the target element instead.',
|
|
3929
|
+
defaultValue: '"bottom"'
|
|
3930
|
+
}, {
|
|
3931
|
+
name: 'onHide',
|
|
3932
|
+
type: '(analyticsEvent: UIAnalyticsEvent) => void',
|
|
3933
|
+
description: "Function to be called when the tooltip will be hidden. It's called after the\ndelay, when the tooltip begins to animate out.",
|
|
3934
|
+
defaultValue: 'noop'
|
|
3935
|
+
}, {
|
|
3936
|
+
name: 'onShow',
|
|
3937
|
+
type: '(analyticsEvent: UIAnalyticsEvent) => void',
|
|
3938
|
+
description: "Function to be called when the tooltip will be shown. It's called when the\ntooltip begins to animate in.",
|
|
3939
|
+
defaultValue: 'noop'
|
|
3940
|
+
}, {
|
|
3941
|
+
name: 'position',
|
|
3942
|
+
type: 'Placement | "mouse" | "mouse-y" | "mouse-x"',
|
|
3943
|
+
description: 'Where the tooltip should appear relative to its target.\nIf set to `"mouse"`, the tooltip will display next to the mouse pointer instead.\nIf set to `"mouse-y"`, the tooltip will use the mouse Y coordinate but the target X coordinate.\nIf set to `"mouse-x"`, the tooltip will use the mouse X coordinate but the target Y coordinate.\nMake sure to utilize the `mousePosition` if you want to customize where the tooltip will show in relation to the mouse.',
|
|
3944
|
+
defaultValue: '"bottom"'
|
|
3945
|
+
}, {
|
|
3946
|
+
name: 'shortcut',
|
|
3947
|
+
type: 'string[]',
|
|
3948
|
+
description: 'Display a keyboard shortcut in the tooltip.\n\nKeys will be displayed as individual keyboard key segments after the tooltip content.'
|
|
3949
|
+
}, {
|
|
3950
|
+
name: 'strategy',
|
|
3951
|
+
type: '"fixed" | "absolute"',
|
|
3952
|
+
description: 'Use this to define the strategy of popper.',
|
|
3953
|
+
defaultValue: '"fixed"'
|
|
3954
|
+
}, {
|
|
3955
|
+
name: 'tag',
|
|
3956
|
+
type: 'keyof JSX.IntrinsicElements | React.ComponentType<React.AllHTMLAttributes<HTMLElement> & { ref: React.Ref<HTMLElement>; }> | React.ForwardRefExoticComponent<...>',
|
|
3957
|
+
description: 'Replace the wrapping element. This accepts the name of a html tag which will\nbe used to wrap the element.\nIf you provide a component, it needs to support a ref prop which is used by popper for positioning.'
|
|
3958
|
+
}]
|
|
3959
|
+
}, {
|
|
3960
|
+
name: 'VisuallyHidden',
|
|
3961
|
+
package: '@atlaskit/visually-hidden',
|
|
3962
|
+
description: 'Content hidden from sight but available to screen readers. Use when meaning is clear visually but not to assistive technology.',
|
|
3963
|
+
status: 'general-availability',
|
|
3964
|
+
usageGuidelines: ['Use when meaning is clear visually but not to assistive technology', 'Avoid clutter—verbose screen-reader-only text can be more harmful than helpful', 'Use the role prop for semantic meaning when needed'],
|
|
3965
|
+
contentGuidelines: ['Use clear, descriptive hidden content', 'Ensure content adds value for screen readers', 'Keep content concise but meaningful'],
|
|
3966
|
+
accessibilityGuidelines: ['Use for screen reader only content when visual context is insufficient for AT', 'Use role prop for semantic meaning when appropriate', 'Balance clarity with brevity—avoid overwhelming screen reader users', 'Prefer over aria-label in some cases when screen readers need to translate or announce full phrasing'],
|
|
3967
|
+
keywords: ['hidden', 'accessibility', 'screen-reader', 'aria', 'utility'],
|
|
3968
|
+
category: 'utility',
|
|
3969
|
+
examples: ["import VisuallyHidden from '@atlaskit/visually-hidden';\nexport default (): React.JSX.Element => {\n\treturn (\n\t\t<div style={{ border: '1px solid black' }}>\n\t\t\tThere is text hidden between the brackets [<VisuallyHidden>Can't see me!</VisuallyHidden>]\n\t\t</div>\n\t);\n};"],
|
|
3970
|
+
props: [{
|
|
3971
|
+
name: 'children',
|
|
3972
|
+
type: 'string | number | boolean | React.ReactElement<any, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | React.ReactPortal',
|
|
3973
|
+
description: 'The element or elements that should be hidden.',
|
|
3974
|
+
isRequired: true
|
|
3975
|
+
}, {
|
|
3976
|
+
name: 'id',
|
|
3977
|
+
type: 'string',
|
|
3978
|
+
description: 'An id may be appropriate for this component if used in conjunction with `aria-describedby`\non a paired element.'
|
|
3979
|
+
}, {
|
|
3980
|
+
name: 'role',
|
|
3981
|
+
type: 'string',
|
|
3982
|
+
description: 'An ARIA role attribute to aid screen readers.'
|
|
3983
|
+
}]
|
|
3984
|
+
}];
|