From 5fbc298d18622d135c0383b9fc0476266e1b3540 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Thu, 19 Nov 2026 11:53:06 -0600 Subject: [PATCH 01/10] docs: add *.docs.ts convention --- .../react/src/ActionBar/ActionBar.docs.ts | 157 ++++ .../react/src/ActionList/ActionList.docs.ts | 395 ++++++++++ .../react/src/ActionMenu/ActionMenu.docs.ts | 110 +++ .../AnchoredOverlay/AnchoredOverlay.docs.ts | 176 +++++ .../src/Autocomplete/Autocomplete.docs.ts | 168 ++++ packages/react/src/Avatar/Avatar.docs.ts | 40 + .../react/src/AvatarStack/AvatarStack.docs.ts | 73 ++ packages/react/src/Banner/Banner.docs.ts | 144 ++++ .../react/src/Blankslate/Blankslate.docs.ts | 71 ++ .../react/src/BranchName/BranchName.docs.ts | 31 + .../react/src/Breadcrumbs/Breadcrumbs.docs.ts | 84 ++ packages/react/src/Button/Button.docs.ts | 130 ++++ packages/react/src/Button/IconButton.docs.ts | 117 +++ .../react/src/ButtonGroup/ButtonGroup.docs.ts | 20 + packages/react/src/Card/Card.docs.ts | 219 ++++++ packages/react/src/Checkbox/Checkbox.docs.ts | 76 ++ .../src/CheckboxGroup/CheckboxGroup.docs.ts | 110 +++ .../react/src/CircleBadge/CircleBadge.docs.ts | 62 ++ .../ConfirmationDialog.docs.ts | 69 ++ .../src/CounterLabel/CounterLabel.docs.ts | 40 + .../react/src/DataTable/DataTable.docs.ts | 736 ++++++++++++++++++ packages/react/src/Details/Details.docs.ts | 32 + packages/react/src/Dialog/Dialog.docs.ts | 188 +++++ .../src/FeatureFlags/FeatureFlags.docs.ts | 19 + packages/react/src/Flash/Flash.docs.ts | 43 + .../react/src/FormControl/FormControl.docs.ts | 209 +++++ packages/react/src/Header/Header.docs.ts | 41 + packages/react/src/Heading/Heading.docs.ts | 26 + packages/react/src/Hidden/Hidden.docs.ts | 24 + .../src/InlineMessage/InlineMessage.docs.ts | 39 + .../src/KeybindingHint/KeybindingHint.docs.ts | 40 + packages/react/src/Label/Label.docs.ts | 40 + .../react/src/LabelGroup/LabelGroup.docs.ts | 43 + packages/react/src/Link/Link.docs.ts | 57 ++ packages/react/src/NavList/NavList.docs.ts | 303 +++++++ packages/react/src/Octicon/Octicon.docs.ts | 42 + packages/react/src/Overlay/Overlay.docs.ts | 182 +++++ .../react/src/PageHeader/PageHeader.docs.ts | 295 +++++++ .../react/src/PageLayout/PageLayout.docs.ts | 439 +++++++++++ packages/react/src/Pagehead/Pagehead.docs.ts | 20 + .../react/src/Pagination/Pagination.docs.ts | 69 ++ packages/react/src/Popover/Popover.docs.ts | 94 +++ packages/react/src/Portal/Portal.docs.ts | 33 + .../react/src/ProgressBar/ProgressBar.docs.ts | 86 ++ packages/react/src/Radio/Radio.docs.ts | 67 ++ .../react/src/RadioGroup/RadioGroup.docs.ts | 117 +++ .../src/RelativeTime/RelativeTime.docs.ts | 153 ++++ .../SegmentedControl/SegmentedControl.docs.ts | 175 +++++ packages/react/src/Select/Select.docs.ts | 55 ++ .../react/src/SelectPanel/SelectPanel.docs.ts | 272 +++++++ .../react/src/Skeleton/SkeletonBox.docs.ts | 45 ++ .../src/SkeletonAvatar/SkeletonAvatar.docs.ts | 34 + .../src/SkeletonText/SkeletonText.docs.ts | 47 ++ packages/react/src/Spinner/Spinner.docs.ts | 55 ++ .../SplitPageLayout/SplitPageLayout.docs.ts | 352 +++++++++ packages/react/src/Stack/Stack.docs.ts | 94 +++ .../react/src/StateLabel/StateLabel.docs.ts | 54 ++ packages/react/src/SubNav/SubNav.docs.ts | 65 ++ packages/react/src/TabNav/TabNav.docs.ts | 47 ++ packages/react/src/Text/Text.docs.ts | 49 ++ .../react/src/TextInput/TextInput.docs.ts | 220 ++++++ .../TextInputWithTokens.docs.ts | 89 +++ packages/react/src/Textarea/Textarea.docs.ts | 101 +++ packages/react/src/Timeline/Timeline.docs.ts | 60 ++ .../src/ToggleSwitch/ToggleSwitch.docs.ts | 134 ++++ packages/react/src/Token/Token.docs.ts | 107 +++ packages/react/src/Tooltip/Tooltip.docs.ts | 35 + packages/react/src/TooltipV2/Tooltip.docs.ts | 55 ++ packages/react/src/TopicTag/TopicTag.docs.ts | 38 + packages/react/src/TreeView/TreeView.docs.ts | 226 ++++++ packages/react/src/Truncate/Truncate.docs.ts | 47 ++ .../src/UnderlineNav/UnderlineNav.docs.ts | 116 +++ .../src/deprecated/DialogV1/Dialog.docs.ts | 55 ++ .../FilteredSearch/FilteredSearch.docs.ts | 19 + .../UnderlineNav/UnderlineNav.docs.ts | 51 ++ packages/react/src/docs/component.ts | 45 ++ packages/react/src/docs/deprecated.ts | 0 packages/react/src/docs/experimental.ts | 0 packages/react/src/docs/index.ts | 0 packages/react/src/docs/next.ts | 0 .../IssueLabel/IssueLabel.docs.ts | 32 + .../SelectPanel2/SelectPanel.docs.ts | 205 +++++ .../UnderlinePanels/UnderlinePanels.docs.ts | 160 ++++ .../react/src/live-region/AriaAlert.docs.ts | 28 + .../react/src/live-region/AriaStatus.docs.ts | 34 + 85 files changed, 8930 insertions(+) create mode 100644 packages/react/src/ActionBar/ActionBar.docs.ts create mode 100644 packages/react/src/ActionList/ActionList.docs.ts create mode 100644 packages/react/src/ActionMenu/ActionMenu.docs.ts create mode 100644 packages/react/src/AnchoredOverlay/AnchoredOverlay.docs.ts create mode 100644 packages/react/src/Autocomplete/Autocomplete.docs.ts create mode 100644 packages/react/src/Avatar/Avatar.docs.ts create mode 100644 packages/react/src/AvatarStack/AvatarStack.docs.ts create mode 100644 packages/react/src/Banner/Banner.docs.ts create mode 100644 packages/react/src/Blankslate/Blankslate.docs.ts create mode 100644 packages/react/src/BranchName/BranchName.docs.ts create mode 100644 packages/react/src/Breadcrumbs/Breadcrumbs.docs.ts create mode 100644 packages/react/src/Button/Button.docs.ts create mode 100644 packages/react/src/Button/IconButton.docs.ts create mode 100644 packages/react/src/ButtonGroup/ButtonGroup.docs.ts create mode 100644 packages/react/src/Card/Card.docs.ts create mode 100644 packages/react/src/Checkbox/Checkbox.docs.ts create mode 100644 packages/react/src/CheckboxGroup/CheckboxGroup.docs.ts create mode 100644 packages/react/src/CircleBadge/CircleBadge.docs.ts create mode 100644 packages/react/src/ConfirmationDialog/ConfirmationDialog.docs.ts create mode 100644 packages/react/src/CounterLabel/CounterLabel.docs.ts create mode 100644 packages/react/src/DataTable/DataTable.docs.ts create mode 100644 packages/react/src/Details/Details.docs.ts create mode 100644 packages/react/src/Dialog/Dialog.docs.ts create mode 100644 packages/react/src/FeatureFlags/FeatureFlags.docs.ts create mode 100644 packages/react/src/Flash/Flash.docs.ts create mode 100644 packages/react/src/FormControl/FormControl.docs.ts create mode 100644 packages/react/src/Header/Header.docs.ts create mode 100644 packages/react/src/Heading/Heading.docs.ts create mode 100644 packages/react/src/Hidden/Hidden.docs.ts create mode 100644 packages/react/src/InlineMessage/InlineMessage.docs.ts create mode 100644 packages/react/src/KeybindingHint/KeybindingHint.docs.ts create mode 100644 packages/react/src/Label/Label.docs.ts create mode 100644 packages/react/src/LabelGroup/LabelGroup.docs.ts create mode 100644 packages/react/src/Link/Link.docs.ts create mode 100644 packages/react/src/NavList/NavList.docs.ts create mode 100644 packages/react/src/Octicon/Octicon.docs.ts create mode 100644 packages/react/src/Overlay/Overlay.docs.ts create mode 100644 packages/react/src/PageHeader/PageHeader.docs.ts create mode 100644 packages/react/src/PageLayout/PageLayout.docs.ts create mode 100644 packages/react/src/Pagehead/Pagehead.docs.ts create mode 100644 packages/react/src/Pagination/Pagination.docs.ts create mode 100644 packages/react/src/Popover/Popover.docs.ts create mode 100644 packages/react/src/Portal/Portal.docs.ts create mode 100644 packages/react/src/ProgressBar/ProgressBar.docs.ts create mode 100644 packages/react/src/Radio/Radio.docs.ts create mode 100644 packages/react/src/RadioGroup/RadioGroup.docs.ts create mode 100644 packages/react/src/RelativeTime/RelativeTime.docs.ts create mode 100644 packages/react/src/SegmentedControl/SegmentedControl.docs.ts create mode 100644 packages/react/src/Select/Select.docs.ts create mode 100644 packages/react/src/SelectPanel/SelectPanel.docs.ts create mode 100644 packages/react/src/Skeleton/SkeletonBox.docs.ts create mode 100644 packages/react/src/SkeletonAvatar/SkeletonAvatar.docs.ts create mode 100644 packages/react/src/SkeletonText/SkeletonText.docs.ts create mode 100644 packages/react/src/Spinner/Spinner.docs.ts create mode 100644 packages/react/src/SplitPageLayout/SplitPageLayout.docs.ts create mode 100644 packages/react/src/Stack/Stack.docs.ts create mode 100644 packages/react/src/StateLabel/StateLabel.docs.ts create mode 100644 packages/react/src/SubNav/SubNav.docs.ts create mode 100644 packages/react/src/TabNav/TabNav.docs.ts create mode 100644 packages/react/src/Text/Text.docs.ts create mode 100644 packages/react/src/TextInput/TextInput.docs.ts create mode 100644 packages/react/src/TextInputWithTokens/TextInputWithTokens.docs.ts create mode 100644 packages/react/src/Textarea/Textarea.docs.ts create mode 100644 packages/react/src/Timeline/Timeline.docs.ts create mode 100644 packages/react/src/ToggleSwitch/ToggleSwitch.docs.ts create mode 100644 packages/react/src/Token/Token.docs.ts create mode 100644 packages/react/src/Tooltip/Tooltip.docs.ts create mode 100644 packages/react/src/TooltipV2/Tooltip.docs.ts create mode 100644 packages/react/src/TopicTag/TopicTag.docs.ts create mode 100644 packages/react/src/TreeView/TreeView.docs.ts create mode 100644 packages/react/src/Truncate/Truncate.docs.ts create mode 100644 packages/react/src/UnderlineNav/UnderlineNav.docs.ts create mode 100644 packages/react/src/deprecated/DialogV1/Dialog.docs.ts create mode 100644 packages/react/src/deprecated/FilteredSearch/FilteredSearch.docs.ts create mode 100644 packages/react/src/deprecated/UnderlineNav/UnderlineNav.docs.ts create mode 100644 packages/react/src/docs/component.ts create mode 100644 packages/react/src/docs/deprecated.ts create mode 100644 packages/react/src/docs/experimental.ts create mode 100644 packages/react/src/docs/index.ts create mode 100644 packages/react/src/docs/next.ts create mode 100644 packages/react/src/experimental/IssueLabel/IssueLabel.docs.ts create mode 100644 packages/react/src/experimental/SelectPanel2/SelectPanel.docs.ts create mode 100644 packages/react/src/experimental/UnderlinePanels/UnderlinePanels.docs.ts create mode 100644 packages/react/src/live-region/AriaAlert.docs.ts create mode 100644 packages/react/src/live-region/AriaStatus.docs.ts diff --git a/packages/react/src/ActionBar/ActionBar.docs.ts b/packages/react/src/ActionBar/ActionBar.docs.ts new file mode 100644 index 00000000000..85726f7f7df --- /dev/null +++ b/packages/react/src/ActionBar/ActionBar.docs.ts @@ -0,0 +1,157 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'actionbar', + name: 'ActionBar', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: ['experimental-components-actionbar--default'], + importPath: '@primer/react', + props: [ + { + name: 'aria-label', + type: 'string', + required: false, + description: 'When provided, a label is added to the action bar', + }, + { + name: 'aria-labelledby', + type: 'string', + required: false, + description: 'When provided, uses the element with that ID as the accessible name for the ActionBar', + }, + {name: 'children', type: 'ReactNode', required: false, description: 'Buttons in the action bar', defaultValue: ''}, + { + name: 'size', + type: "'small' | 'large' | 'medium'", + required: false, + defaultValue: "'medium'", + description: 'Size of the action bar', + }, + { + name: 'flush', + type: 'boolean', + required: false, + defaultValue: 'false', + description: 'Allows ActionBar to be flush with the container', + }, + {name: 'className', type: 'string', required: false, description: 'Custom className', defaultValue: ''}, + { + name: 'gap', + type: "'none' | 'condensed'", + required: false, + defaultValue: "'condensed'", + description: 'Horizontal gap scale between items (restricted to none or condensed).', + }, + ], + subcomponents: [ + { + name: 'ActionBar.IconButton', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + required: true, + description: 'This will be the Button description.', + }, + { + name: 'icon', + type: 'Component', + defaultValue: '', + description: 'Provide an octicon. It will be placed in the center of the button', + required: true, + }, + { + name: 'aria-label', + type: 'string', + defaultValue: '', + description: + 'Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text.', + required: false, + }, + { + name: 'disabled', + type: 'boolean', + defaultValue: '', + description: + 'Provides a disabled state for the button. The button will remain focusable, and have `aria-disabled` applied.', + required: false, + }, + ], + passthrough: {element: 'IconButton', url: '/react/IconButton'}, + displayName: 'IconButton', + }, + { + name: 'ActionBar.Button', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + required: true, + description: 'The text content of the button.', + }, + { + name: 'leadingVisual', + type: 'Component', + defaultValue: '', + description: + 'Provide an octicon to render before the button text. It will also be shown when the button overflows into the menu.', + required: false, + }, + { + name: 'disabled', + type: 'boolean', + defaultValue: '', + description: + 'Provides a disabled state for the button. The button will remain focusable, and have `aria-disabled` applied.', + required: false, + }, + ], + passthrough: {element: 'Button', url: '/react/Button'}, + displayName: 'Button', + }, + {name: 'ActionBar.Divider', props: [], displayName: 'Divider'}, + { + name: 'ActionBar.Group', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + description: 'Content rendered inside the action bar group.', + required: false, + }, + ], + displayName: 'Group', + }, + { + name: 'ActionBar.Menu', + props: [ + {name: 'aria-label', type: 'string', required: true, description: 'Accessible label for the menu button.'}, + {name: 'icon', type: 'Component', required: true, description: 'Icon for the menu button.'}, + { + name: 'items', + type: 'ActionBarMenuItemProps[]', + required: true, + description: 'Array of menu items to render in the menu. Each item can be an action, group, or divider.', + }, + { + name: 'overflowIcon', + type: "Component | 'none'", + required: false, + description: + "Icon displayed when the menu item is within the overflow menu. If 'none' is provided, no icon will be shown in the overflow menu.", + }, + { + name: 'returnFocusRef', + type: 'React.RefObject', + required: false, + description: 'A ref to an element that should receive focus when the menu is closed.', + }, + ], + displayName: 'Menu', + }, + ], +}) diff --git a/packages/react/src/ActionList/ActionList.docs.ts b/packages/react/src/ActionList/ActionList.docs.ts new file mode 100644 index 00000000000..dd0eaa87398 --- /dev/null +++ b/packages/react/src/ActionList/ActionList.docs.ts @@ -0,0 +1,395 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'action_list', + name: 'ActionList', + status: 'beta', + a11yReviewed: '2025-01-08', + stories: [], + importPath: '@primer/react', + props: [ + { + name: 'children', + type: 'ActionList.Item[] | ActionList.LinkItem[] | ActionList.Group[]', + defaultValue: '', + required: true, + description: '', + }, + { + name: 'variant', + type: "'inset' | 'horizontal-inset' | 'full'", + defaultValue: "'inset'", + description: + '`inset` children are offset (vertically and/or horizontally) from list edges. `full` children are flush (vertically and horizontally) with list edges', + required: false, + }, + { + name: 'selectionVariant', + type: "'single' | 'multiple'", + defaultValue: '', + description: 'Whether multiple items or a single item can be selected.', + required: false, + }, + { + name: 'showDividers', + type: 'boolean', + description: + 'Display a divider above each `Item` in this `List` when it does not follow a `Header` or `Divider`.', + defaultValue: '', + required: false, + }, + { + name: 'role', + type: 'AriaRole', + defaultValue: '', + description: 'ARIA role describing the function of the list. `listbox` and `menu` are a common values.', + required: false, + }, + { + name: 'disableItemGap', + type: 'boolean', + description: 'Disable the gap between items when this `ActionList` is rendered in a `NavList`.', + defaultValue: 'false', + required: false, + }, + ], + subcomponents: [ + { + name: 'ActionList.Item', + props: [ + { + name: 'children', + type: 'React.ReactNode | ActionList.LeadingVisual | ActionList.Description | ActionList.TrailingVisual', + defaultValue: '', + required: true, + description: 'Primary content for an Item', + }, + { + name: 'variant', + type: "'default' | 'danger'", + defaultValue: "'default'", + description: '`danger` indicates that the item is destructive.', + required: false, + }, + { + name: 'size', + type: "'small' | 'medium' | 'large'", + defaultValue: "'medium'", + description: 'The block size of the ActionList item. The `small` size also uses small body text.', + required: false, + }, + { + name: 'onSelect', + type: '(event: React.MouseEvent | React.KeyboardEvent) => void', + defaultValue: '', + description: + 'Callback that is called when the item is selected using either the mouse or keyboard. `event.preventDefault()` will prevent a menu from closing when within an ``. This is not called for disabled or inactive items.', + required: false, + }, + { + name: 'selected', + type: 'boolean', + defaultValue: 'false', + description: 'Indicate whether the item is selected. Only applies to items that can be selected.', + required: false, + }, + { + name: 'active', + type: 'boolean', + defaultValue: 'false', + description: 'Indicate whether the item is active. There should never be more than one active item.', + required: false, + }, + { + name: 'disabled', + type: 'boolean', + defaultValue: 'false', + description: 'Items that are disabled can not be clicked, selected, or navigated to.', + required: false, + }, + { + name: 'inactiveText', + type: 'string', + defaultValue: '', + description: + "Text describing why the item is inactive. This may be used when an item's usual functionality is unavailable due to a system error such as a database outage.\nIf there is a leading visual, the alert icon will replace the leading visual.\nIf there is a trailing visual, it will replace the trailing visual.\nIf there is no visual passed, it will be shown in the trailing visual slot to preserve left alignment of item content.\nText will appear in a tooltip triggered by the alert icon in ActionList items, but text will appear below the description or title on ActionMenu items.", + required: false, + }, + {name: 'loading', type: 'boolean', description: 'Whether the item is loading.', required: false}, + { + name: 'role', + type: 'AriaRole', + defaultValue: '', + description: 'ARIA role describing the function of the item. `option` is a common value.', + required: false, + }, + { + name: 'id', + type: 'string', + required: false, + description: 'id to attach to the root element of the Item', + defaultValue: '', + }, + ], + displayName: 'Item', + }, + { + name: 'ActionList.Heading', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + required: true, + description: 'Use to give a heading to list', + }, + { + name: 'as', + type: 'h1 | h2 | h3 | h4 | h5 | h6', + defaultValue: 'h3', + required: false, + description: 'The level of the heading', + }, + {name: 'visuallyHidden', type: 'boolean', required: false, description: '', defaultValue: ''}, + ], + displayName: 'Heading', + }, + { + name: 'ActionList.LinkItem', + props: [ + { + name: 'children', + type: 'React.ReactNode | ActionList.LeadingVisual | ActionList.Description | ActionList.TrailingVisual', + defaultValue: '', + required: true, + description: '', + }, + { + name: 'active', + type: 'boolean', + defaultValue: 'false', + description: 'Indicate whether the item is active. There should never be more than one active item.', + required: false, + }, + { + name: 'size', + type: "'small' | 'medium' | 'large'", + defaultValue: "'medium'", + description: 'The block size of the ActionList item. The `small` size also uses small body text.', + required: false, + }, + { + name: 'ref', + type: 'React.RefObject', + required: false, + description: + 'Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).', + }, + { + name: 'as', + type: 'React.ElementType', + defaultValue: '"a"', + description: 'Element or component used to render the link.', + required: false, + }, + { + name: 'inactiveText', + type: 'string', + required: false, + description: + "Text describing why the item is inactive. This may be used when an item's usual functionality\nis unavailable due to a system error such as a database outage.", + defaultValue: '', + }, + ], + passthrough: {element: 'a', url: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes'}, + displayName: 'LinkItem', + }, + { + name: 'ActionList.LeadingVisual', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + required: true, + description: 'Icon (or similar) positioned before item text.', + }, + ], + displayName: 'LeadingVisual', + }, + { + name: 'ActionList.TrailingVisual', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + required: true, + description: 'Visual positioned after item text.', + }, + ], + displayName: 'TrailingVisual', + }, + { + name: 'ActionList.TrailingAction', + props: [ + { + name: 'as', + type: 'a | button', + defaultValue: 'button', + required: false, + description: 'HTML element to render as.', + }, + { + name: 'label', + type: 'string', + defaultValue: '', + required: true, + description: 'Accessible name for the control.', + }, + { + name: 'icon', + type: 'string', + defaultValue: '', + required: true, + description: + 'Octicon to pass into IconButton. When this is not set, TrailingAction renders as a `Button` instead of an `IconButton`.', + }, + { + name: 'href', + type: 'string', + description: 'href when the TrailingAction is rendered as a link.', + required: false, + }, + { + name: 'loading', + type: 'boolean', + defaultValue: 'false', + description: + "Whether the TrailingAction is in a loading state. When true, the TrailingAction will render a spinner instead of an icon. Only available when `as` is 'button'.", + required: false, + }, + { + name: 'tooltipDirection', + type: "'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w' | 'nw'", + defaultValue: "'w'", + description: + 'Direction of the tooltip shown when hovering over the TrailingAction. Only applies when `icon` is set.', + required: false, + }, + ], + displayName: 'TrailingAction', + }, + { + name: 'ActionList.Description', + props: [ + {name: 'children', type: 'React.ReactNode', defaultValue: '', required: true, description: ''}, + { + name: 'variant', + type: "'inline' | 'block'", + defaultValue: "'inline'", + description: + '`inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text.', + required: false, + }, + {name: 'className', type: 'string | undefined', defaultValue: '', description: 'CSS string', required: false}, + { + name: 'truncate', + type: 'boolean', + defaultValue: 'false', + description: 'Whether the inline description should truncate the text on overflow.', + required: false, + }, + ], + displayName: 'Description', + }, + { + name: 'ActionList.GroupHeading', + props: [ + { + name: 'children', + type: 'React.ReactNode', + defaultValue: '', + required: true, + description: 'Use to give a heading to the groups', + }, + { + name: 'variant', + type: "'filled' | 'subtle'", + defaultValue: "'subtle'", + description: + '`filled` style has a background color and top and bottom borders. Subtle style has no background or borders.', + required: false, + }, + { + name: 'auxiliaryText', + type: 'string', + required: false, + description: 'Secondary text which provides additional information about a `Group`.', + defaultValue: '', + }, + {name: 'visuallyHidden', type: 'boolean', required: false, description: '', defaultValue: ''}, + { + name: 'as', + type: 'h1 | h2 | h3 | h4 | h5 | h6', + defaultValue: 'h3', + required: false, + description: + 'The level of the heading and it is only required (enforce by runtime warning) for lists. (i.e. not required for ActionMenu or listbox roles)', + }, + ], + displayName: 'GroupHeading', + }, + { + name: 'ActionList.Group', + props: [ + { + name: 'children', + type: 'ActionList.Item[] | ActionList.LinkItem[]', + defaultValue: '', + required: true, + description: '', + }, + { + name: 'title', + type: 'string', + defaultValue: '', + description: 'Please use `ActionList.GroupHeading` instead.', + deprecated: true, + required: false, + }, + { + name: 'auxiliaryText', + type: 'string', + defaultValue: '', + description: 'Secondary text that provides additional information about the group.', + required: false, + }, + { + name: 'variant', + type: "'filled' | 'subtle'", + defaultValue: "'subtle'", + description: + '`inline` descriptions are positioned beside primary text. `block` descriptions are positioned below primary text.', + required: false, + }, + { + name: 'selectionVariant', + type: "'single' | 'multiple' | false", + defaultValue: '', + description: 'Set `selectionVariant` at the group level.', + required: false, + }, + { + name: 'role', + type: 'AriaRole', + defaultValue: '', + description: + 'ARIA role describing the function of the list inside the group. `listbox` and `menu` are a common values.', + required: false, + }, + ], + displayName: 'Group', + }, + ], +}) diff --git a/packages/react/src/ActionMenu/ActionMenu.docs.ts b/packages/react/src/ActionMenu/ActionMenu.docs.ts new file mode 100644 index 00000000000..7aa525407c0 --- /dev/null +++ b/packages/react/src/ActionMenu/ActionMenu.docs.ts @@ -0,0 +1,110 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'action_menu', + name: 'ActionMenu', + status: 'beta', + a11yReviewed: '2025-01-08', + stories: [ + 'components-actionmenu--default', + 'components-actionmenu-features--links-and-actions', + 'components-actionmenu-features--single-select', + 'components-actionmenu-features--multi-select', + 'components-actionmenu-features--inactive-items', + 'components-actionmenu-features--loading-items', + 'components-actionmenu-features--submenus', + ], + importPath: '@primer/react', + props: [ + { + name: 'children', + type: 'React.ReactElement[]', + defaultValue: '', + required: true, + description: 'Recommended: `ActionMenu.Button` or `ActionMenu.Anchor` with `ActionMenu.Overlay`', + }, + { + name: 'open', + type: 'boolean', + defaultValue: 'false', + description: + 'If defined, will control the open/closed state of the overlay. Must be used in conjuction with `onOpenChange`.', + required: false, + }, + { + name: 'onOpenChange', + type: '(open: boolean) => void', + defaultValue: '', + description: + 'If defined, will control the open/closed state of the overlay. Must be used in conjuction with `open`.', + required: false, + }, + { + name: 'anchorRef', + type: 'React.RefObject', + defaultValue: '', + description: 'Useful for defining an external anchor', + required: false, + }, + ], + subcomponents: [ + { + name: 'ActionMenu.Button', + props: [{name: 'children', type: 'React.ReactElement', defaultValue: '', required: true, description: ''}], + passthrough: {element: 'Button', url: '/react/Button'}, + displayName: 'Button', + }, + { + name: 'ActionMenu.Anchor', + props: [ + { + name: 'children', + type: 'React.ReactElement', + defaultValue: '', + required: true, + description: 'Accepts a single child element', + }, + {name: 'id', type: 'string', description: '', defaultValue: '', required: false}, + ], + displayName: 'Anchor', + }, + { + name: 'ActionMenu.Overlay', + props: [ + {name: 'children', type: 'React.ReactNode', defaultValue: '', required: true, description: ''}, + {name: 'align', type: 'start | center | end', defaultValue: 'start', description: '', required: false}, + { + name: 'side', + type: "| 'inside-top' | 'inside-bottom' | 'inside-left' | 'inside-right' | 'inside-center' | 'outside-top' | 'outside-bottom' | 'outside-left' | 'outside-right'", + defaultValue: "'outside-bottom'", + description: 'Controls which side of the anchor the menu will appear', + required: false, + }, + { + name: 'onPositionChange', + type: '({ position }: { position: AnchorPosition }) => void', + defaultValue: '', + description: 'Callback that is called when the position of the overlay changes', + required: false, + }, + { + name: 'preventFocusOnClose', + type: 'boolean', + defaultValue: 'false', + description: + 'If true, focus will not be returned to the anchor or returnFocusRef when the menu closes. Consumers must manage focus themselves.', + required: false, + }, + { + name: 'data-test-id', + type: 'unknown', + required: false, + description: 'ID to use for React testing utilities.', + defaultValue: '', + }, + ], + passthrough: {element: 'Overlay', url: '/react/Overlay'}, + displayName: 'Overlay', + }, + ], +}) diff --git a/packages/react/src/AnchoredOverlay/AnchoredOverlay.docs.ts b/packages/react/src/AnchoredOverlay/AnchoredOverlay.docs.ts new file mode 100644 index 00000000000..ce4987d7744 --- /dev/null +++ b/packages/react/src/AnchoredOverlay/AnchoredOverlay.docs.ts @@ -0,0 +1,176 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'anchored_overlay', + name: 'AnchoredOverlay', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: [ + 'components-anchoredoverlay--default', + 'components-anchoredoverlay-features--portal-inside-scrolling-element', + 'components-anchoredoverlay-features--custom-anchor-id', + 'components-anchoredoverlay-features--height', + 'components-anchoredoverlay-features--width', + 'components-anchoredoverlay-features--anchor-alignment', + 'components-anchoredoverlay-features--anchor-side', + 'components-anchoredoverlay-features--offset-position-from-anchor', + 'components-anchoredoverlay-features--offset-alignment-from-anchor', + 'components-anchoredoverlay-features--focus-trap-overrides', + 'components-anchoredoverlay-features--focus-zone-overrides', + 'components-anchoredoverlay-features--overlay-props-overrides', + ], + importPath: '@primer/react', + props: [ + { + name: 'open', + type: 'boolean', + required: true, + defaultValue: 'false', + description: 'Determines whether the overlay portion of the component should be shown or not.', + }, + { + name: 'onOpen', + type: "(gesture: 'anchor-click' | 'anchor-key-press', event?: KeyboardEvent | undefined) => unknown", + defaultValue: '', + description: + 'A callback that is called whenever the overlay is currently closed and an "open gesture" is detected.', + required: false, + }, + { + name: 'onClose', + type: "(gesture: 'anchor-click' | 'click-outside' | 'escape') => unknown", + defaultValue: '', + description: + 'A callback that is called whenever the overlay is currently open and a "close gesture" is detected.', + required: false, + }, + { + name: 'renderAnchor', + type: '>(props: T) => JSX.Element', + defaultValue: '', + description: + 'A custom function component used to render the anchor element. When renderAnchor is null, an anchorRef is required.', + required: true, + }, + { + name: 'anchorRef', + type: 'React.RefObject', + defaultValue: '', + description: + 'An override to the internal `renderAnchor` ref that will be used to position the overlay. When `renderAnchor` is `null`, this can be used to make an anchor that is detached from ` AnchoredOverlay `.', + required: false, + }, + { + name: 'anchorId', + type: 'string', + defaultValue: '', + description: 'An override to the internal id that will be passed to the anchor.', + required: false, + }, + { + name: 'side', + type: "| 'inside-top' | 'inside-bottom' | 'inside-left' | 'inside-right' | 'inside-center' | 'outside-top' | 'outside-bottom' | 'outside-left' | 'outside-right'", + defaultValue: "'outside-bottom'", + description: '', + required: false, + }, + {name: 'align', type: "'start' | 'center' | 'end'", defaultValue: "'start'", description: '', required: false}, + { + name: 'alignmentOffset', + type: 'number', + defaultValue: '4', + description: + "An additional offset, in pixels, to move the floating element from the aligning edge. Positive values move the floating element in the direction of center-alignment. Negative values move the floating element away from center-alignment. When align is `'center`, positive offsets move the floating element right (top or bottom anchor side) or down (left or right anchor side). If using outside positioning, or if `align` is set to `'center'`, this defaults to `0` instead of `4`.", + required: false, + }, + { + name: 'anchorOffset', + type: 'number', + defaultValue: '4', + description: + "The number of pixels between the anchor edge and the floating element. Positive values move the floating element farther from the anchor element (for outside positioning) or further inside the anchor element (for inside positioning). Negative values have the opposite effect. If `side` is set to `'inside-center'`, this defaults to `0` instead of `4`.", + required: false, + }, + { + name: 'overlayProps', + type: 'Partial', + defaultValue: '', + description: 'Props to be spread on the internal `Overlay` component.', + required: false, + }, + { + name: 'focusTrapSettings', + type: 'Partial', + defaultValue: '', + description: 'Settings to apply to the focus trap on the internal `Overlay` component.', + required: false, + }, + { + name: 'focusZoneSettings', + type: 'Partial', + defaultValue: '', + description: 'Settings to apply to the focus zone on the internal `Overlay` component.', + required: false, + }, + { + name: 'className', + type: 'string', + defaultValue: '', + description: 'Class name for custom styling.', + required: false, + }, + { + name: 'preventOverflow', + type: 'boolean', + defaultValue: 'true', + description: + 'Determines if the Overlay width should be adjusted responsively if there is not enough space to display the Overlay. If `preventOverflow` is set to `false`, the Overlay will be displayed at the maximum width that fits within the viewport.', + required: false, + }, + { + name: 'height', + type: "'small' | 'initial' | 'large' | 'medium' | 'auto' | 'fit-content' | 'xsmall' | 'xlarge'", + required: false, + description: '', + defaultValue: '', + }, + { + name: 'width', + type: "'small' | 'large' | 'medium' | 'auto' | 'xlarge' | 'xxlarge'", + required: false, + description: '', + defaultValue: '', + }, + { + name: 'pinPosition', + type: 'boolean', + required: false, + description: + 'If true, the overlay will attempt to prevent position shifting when sitting at the top of the anchor.', + defaultValue: 'false', + }, + { + name: 'variant', + type: "{ regular?: 'anchored', narrow?: 'anchored' | 'fullscreen' }", + required: false, + description: 'Optional prop to set variant for narrow screen sizes', + defaultValue: "{ regular: 'anchored', narrow: 'anchored' }", + }, + { + name: 'displayCloseButton', + type: 'boolean', + required: false, + description: + 'If true, a close button will be displayed in the top right corner of the overlay when on fullscreen mode.', + defaultValue: 'true', + }, + { + name: 'closeButtonProps', + type: 'Partial', + required: false, + description: 'Props to be spread on the close button in fullscreen mode.', + defaultValue: '{}', + }, + ], + subcomponents: [], +}) diff --git a/packages/react/src/Autocomplete/Autocomplete.docs.ts b/packages/react/src/Autocomplete/Autocomplete.docs.ts new file mode 100644 index 00000000000..b5aa7c56cb7 --- /dev/null +++ b/packages/react/src/Autocomplete/Autocomplete.docs.ts @@ -0,0 +1,168 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'autocomplete', + name: 'Autocomplete', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: [ + 'components-autocomplete--default', + 'components-autocomplete-features--with-token-input', + 'components-autocomplete-features--add-new-item', + 'components-autocomplete-features--custom-search-filter-fn', + 'components-autocomplete-features--custom-sort-after-menu-close', + 'components-autocomplete-features--with-callback-when-overlay-open-state-changes', + 'components-autocomplete-features--async-loading-of-items', + 'components-autocomplete-features--rendering-the-menu-outside-an-overlay', + 'components-autocomplete-features--custom-overlay-menu-anchor', + 'components-autocomplete-features--in-overlay-with-custom-scroll-container-ref', + 'components-autocomplete-features--in-a-dialog', + ], + importPath: '@primer/react', + props: [ + { + name: 'children', + type: 'React.ReactNode', + description: 'Content rendered within the autocomplete context.', + required: false, + }, + { + name: 'id', + type: 'string', + description: + 'May be used to customize how the ID is set on the text input to be used by ARIA attributes on related elements.', + defaultValue: '', + required: false, + }, + ], + subcomponents: [ + { + name: 'Autocomplete.Input', + props: [ + { + name: 'as', + type: 'React.ElementType', + defaultValue: 'TextInput', + description: 'Component used to render the autocomplete input.', + required: false, + }, + { + name: 'openOnFocus', + type: 'boolean', + defaultValue: 'false', + description: 'Whether the associated autocomplete menu should open on an input focus event', + deprecated: true, + required: false, + }, + ], + passthrough: {element: 'TextInput', url: '/react/TextInput'}, + displayName: 'Input', + }, + { + name: 'Autocomplete.Overlay', + props: [ + { + name: 'menuAnchorRef', + type: 'React.RefObject', + required: false, + description: + 'The ref of the element that the position of the menu is based on. By default, the menu is positioned based on the text input', + }, + { + name: 'children', + type: 'React.ReactNode', + description: 'Content rendered inside the overlay when it is open.', + required: false, + }, + { + name: 'overlayProps', + deprecated: true, + type: 'Partial', + description: 'Props to be spread on the internal `Overlay` component.', + required: false, + }, + ], + passthrough: {element: 'Overlay', url: '/react/Overlay'}, + displayName: 'Overlay', + }, + { + name: 'Autocomplete.Menu', + props: [ + { + name: 'items', + required: true, + type: 'T[]', + description: + 'The options for field values that are displayed in the dropdown menu. One or more may be selected depending on the value of the `selectionVariant` prop.', + }, + {name: 'selectedItemIds', required: true, type: 'string[]', description: 'The IDs of the selected items'}, + { + name: 'aria-labelledby', + required: true, + type: 'string', + description: 'ID of the element that labels the listbox.', + }, + { + name: 'addNewItem', + type: "Omit & { handleAddItem: (item: Omit) => void; }", + description: + 'A menu item that is used to allow users make a selection that is not available in the array passed to the `items` prop. This menu item gets appended to the end of the list of options.', + required: false, + }, + { + name: 'emptyStateText', + type: 'React.ReactNode | false', + description: + 'The text that appears in the menu when there are no options in the array passed to the `items` prop.', + required: false, + }, + { + name: 'filterFn', + type: '(item: T, i: number) => boolean', + description: + "A custom function used to filter the options in the array passed to the `items` prop. By default, we filter out items that don't match the value of the autocomplete text input. The default filter is not case-sensitive.", + required: false, + }, + { + name: 'loading', + type: 'boolean', + description: 'Whether the data is loading for the menu items', + required: false, + }, + { + name: 'sortOnCloseFn', + type: '(itemIdA: string | number, itemIdB: string | number) => number', + description: + 'The sort function that is applied to the options in the array passed to the `items` prop after the user closes the menu. By default, selected items are sorted to the top after the user closes the menu.', + required: false, + }, + { + name: 'selectionVariant', + type: "'single' | 'multiple'", + description: 'Whether there can be one item selected from the menu or multiple items selected from the menu', + required: false, + }, + { + name: 'onOpenChange', + type: '(open: boolean) => void', + description: 'Function that gets called when the menu is opened or closed', + required: false, + }, + { + name: 'onSelectedChange', + type: '(item: T | T[]) => void', + description: 'The function that is called when an item in the list is selected or deselected', + required: false, + }, + { + name: 'customScrollContainerRef', + type: 'React.MutableRefObject', + description: + 'If the menu is rendered in a scrolling element other than the `Autocomplete.Overlay` component, pass the ref of that element to `customScrollContainerRef` to ensure the container automatically scrolls when the user highlights an item in the menu that is outside the scroll container', + required: false, + }, + ], + displayName: 'Menu', + }, + ], +}) diff --git a/packages/react/src/Avatar/Avatar.docs.ts b/packages/react/src/Avatar/Avatar.docs.ts new file mode 100644 index 00000000000..0f8dadd3682 --- /dev/null +++ b/packages/react/src/Avatar/Avatar.docs.ts @@ -0,0 +1,40 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'avatar', + name: 'Avatar', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: [ + 'components-avatar--default', + 'components-avatar-features--square', + 'components-avatar-features--size', + 'components-avatar-features--size-responsive', + ], + importPath: '@primer/react', + props: [ + { + name: 'alt', + type: 'string', + defaultValue: "''", + description: 'Provide alt text when the avatar is used without a name next to it.', + required: false, + }, + { + name: 'size', + type: 'number | { narrow?: number; regular?: number; wide?: number; }', + defaultValue: '20', + description: 'The size of the avatar in pixels.', + required: false, + }, + { + name: 'square', + type: 'boolean', + defaultValue: 'false', + description: 'If true, the avatar will be square instead of circular.', + required: false, + }, + {name: 'src', type: 'string', required: false, description: 'URL of the avatar image.', defaultValue: ''}, + ], + subcomponents: [], +}) diff --git a/packages/react/src/AvatarStack/AvatarStack.docs.ts b/packages/react/src/AvatarStack/AvatarStack.docs.ts new file mode 100644 index 00000000000..64babd14684 --- /dev/null +++ b/packages/react/src/AvatarStack/AvatarStack.docs.ts @@ -0,0 +1,73 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'avatar_stack', + name: 'AvatarStack', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: [ + 'components-avatarstack--default', + 'components-avatarstack-features--align-left', + 'components-avatarstack-features--align-right', + 'components-avatarstack-features--disable-expand-on-hover', + 'components-avatarstack-features--custom-size-on-parent', + 'components-avatarstack-features--custom-size-on-parent-responsive', + 'components-avatarstack-features--custom-size-on-children', + 'components-avatarstack-features--custom-size-on-children-responsive', + 'components-avatarstack-features--with-single-avatar', + ], + importPath: '@primer/react', + props: [ + { + name: 'children', + type: 'ReactNode', + description: 'A set of Avatar components to stack', + defaultValue: '', + required: true, + }, + { + name: 'alignRight', + type: 'boolean', + defaultValue: 'false', + description: 'Align the avatars to the right', + required: false, + }, + { + name: 'disableExpand', + type: 'boolean', + defaultValue: 'false', + description: 'Do not spread the avatars on hover', + required: false, + }, + { + name: 'variant', + type: "'cascade' | 'stack'", + defaultValue: "'cascade'", + description: + "The style of overlapping avatars. 'cascade' increases the overlap for 3rd+ avatars, while 'stack' uses a uniform overlap.", + required: false, + }, + { + name: 'shape', + type: "'circle' | 'square'", + defaultValue: "'circle'", + description: 'The shape of the avatars.', + required: false, + }, + { + name: 'size', + type: 'number | { narrow?: number; regular?: number; wide?: number; }', + defaultValue: '20', + description: 'The size of the avatar children in pixels.', + required: false, + }, + { + name: 'className', + type: 'string', + description: 'Class name for custom styling.', + defaultValue: '', + required: false, + }, + ], + subcomponents: [], +}) diff --git a/packages/react/src/Banner/Banner.docs.ts b/packages/react/src/Banner/Banner.docs.ts new file mode 100644 index 00000000000..c437fe38588 --- /dev/null +++ b/packages/react/src/Banner/Banner.docs.ts @@ -0,0 +1,144 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'banner', + name: 'Banner', + status: 'alpha', + a11yReviewed: '2025-01-08', + importPath: '@primer/react', + stories: [ + 'components-banner--default', + 'components-banner-features--critical', + 'components-banner-features--info', + 'components-banner-features--success', + 'components-banner-features--upsell', + 'components-banner-features--warning', + 'components-banner-features--dismiss', + 'components-banner-features--dismiss-with-actions', + 'components-banner-features--with-hidden-title', + 'components-banner-features--with-hidden-title-and-actions', + 'components-banner-features--dismissible-with-hidden-title-and-actions', + 'components-banner-features--dismissible-with-hidden-title-and-secondary-action', + 'components-banner-features--with-actions', + 'components-banner-features--custom-icon', + 'components-banner-examples--with-announcement', + ], + props: [ + { + name: 'aria-label', + type: 'string', + description: 'Provide an optional label to override the default name for the Banner landmark region', + required: false, + }, + { + name: 'className', + type: 'string', + description: 'Provide an optional className to add to the outermost element rendered by the Banner', + required: false, + }, + { + name: 'description', + type: 'React.ReactNode', + description: + 'Provide an optional description for the Banner. This should provide supplemental information about the Banner', + required: false, + }, + {name: 'hideTitle', type: 'boolean', description: 'Whether to hide the title visually.', required: false}, + { + name: 'icon', + type: 'React.ReactNode', + description: 'Provide a custom icon for the Banner. This is only available when `variant` is `info` or `upsell`', + deprecated: true, + required: false, + }, + { + name: 'leadingVisual', + type: 'React.ReactNode', + description: + 'Provide a custom leading visual for the Banner. This is only available when `variant` is `info` or `upsell`', + required: false, + }, + { + name: 'onDismiss', + type: '() => void', + description: + 'Optionally provide a handler to be called when the banner is dismissed. Providing this prop will show a dismiss button', + required: false, + }, + {name: 'primaryAction', type: 'React.ReactNode', description: '', required: false}, + {name: 'secondaryAction', type: 'React.ReactNode', description: '', required: false}, + { + name: 'title', + type: 'React.ReactNode', + description: + 'The title for the Banner. This will be used as the accessible name and is required unless `Banner.Title` is used as a child', + required: false, + }, + { + name: 'variant', + type: "'critical' | 'info' | 'success' | 'upsell' | 'warning'", + description: 'Specify the type of the Banner', + required: false, + }, + { + name: 'layout', + type: "'default' | 'compact'", + description: 'Specify the layout of the Banner. Compact layout will reduce the padding.', + required: false, + }, + { + name: 'actionsLayout', + type: "'default' | 'inline' | 'stacked'", + description: + "Override the responsive layout of the action buttons. 'inline' layout will display the buttons inline with the title and description, while 'stacked' layout will always render the buttons in a new row.", + required: false, + }, + { + name: 'flush', + type: 'boolean', + defaultValue: 'false', + description: + 'Full width banner specifically for use within confined spaces, such as dialogs, tables, cards, or boxes where available space is limited.', + required: false, + }, + ], + subcomponents: [ + { + name: 'Banner.Title', + props: [ + { + name: 'as', + type: "'h2' | 'h3' | 'h4' | 'h5' | 'h6'", + description: 'HTML heading element used to render the banner title.', + required: false, + }, + ], + displayName: 'Title', + }, + { + name: 'Banner.Description', + props: [ + { + name: 'className', + type: 'string', + description: 'Class name(s) for custom styling.', + defaultValue: '', + required: false, + }, + ], + displayName: 'Description', + }, + { + name: 'Banner.PrimaryAction', + props: [], + passthrough: {element: 'Button', url: '/react/Button'}, + displayName: 'PrimaryAction', + }, + { + name: 'Banner.SecondaryAction', + props: [], + passthrough: {element: 'Button', url: '/react/Button'}, + displayName: 'SecondaryAction', + }, + ], +}) diff --git a/packages/react/src/Blankslate/Blankslate.docs.ts b/packages/react/src/Blankslate/Blankslate.docs.ts new file mode 100644 index 00000000000..decdf470b50 --- /dev/null +++ b/packages/react/src/Blankslate/Blankslate.docs.ts @@ -0,0 +1,71 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'blankslate', + name: 'Blankslate', + status: 'draft', + a11yReviewed: '2025-01-08', + stories: [ + 'experimental-components-blankslate--default', + 'experimental-components-blankslate-features--with-visual', + 'experimental-components-blankslate-features--with-primary-action-as-link', + 'experimental-components-blankslate-features--with-primary-action-as-button', + 'experimental-components-blankslate-features--with-secondary-action', + 'experimental-components-blankslate-features--with-border', + 'experimental-components-blankslate-features--narrow', + 'experimental-components-blankslate-features--spacious', + ], + importPath: '@primer/react/experimental', + props: [ + {name: 'border', type: 'boolean', description: 'Add a border around this component', required: false}, + {name: 'narrow', type: 'boolean', description: '', required: false}, + {name: 'spacious', type: 'boolean', description: '', required: false}, + { + name: 'className', + type: 'string', + description: 'Class name(s) for custom styling.', + defaultValue: '', + required: false, + }, + { + name: 'size', + type: "'small' | 'medium' | 'large'", + description: 'The size of the componeont', + defaultValue: "'medium'", + required: false, + }, + ], + subcomponents: [ + {name: 'Blankslate.Visual', props: [], displayName: 'Visual'}, + { + name: 'Blankslate.Heading', + props: [ + { + name: 'as', + type: "'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'", + description: 'HTML heading element used to render the blankslate heading.', + required: false, + }, + ], + displayName: 'Heading', + }, + {name: 'Blankslate.Description', props: [], displayName: 'Description'}, + { + name: 'Blankslate.PrimaryAction', + props: [ + { + name: 'href', + type: 'string', + required: false, + description: 'Link to complete primary action. If defined, will render as an anchor instead of a button.', + }, + ], + displayName: 'PrimaryAction', + }, + { + name: 'Blankslate.SecondaryAction', + props: [{name: 'href', type: 'string', description: 'Link to complete secondary action', required: true}], + displayName: 'SecondaryAction', + }, + ], +}) diff --git a/packages/react/src/BranchName/BranchName.docs.ts b/packages/react/src/BranchName/BranchName.docs.ts new file mode 100644 index 00000000000..0235a1ad575 --- /dev/null +++ b/packages/react/src/BranchName/BranchName.docs.ts @@ -0,0 +1,31 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'branch_name', + name: 'BranchName', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: [ + 'components-branchname--default', + 'components-branchname-features--with-branch-icon', + 'components-branchname-features--not-a-link', + ], + importPath: '@primer/react', + props: [ + { + name: 'ref', + type: 'React.RefObject', + required: false, + description: + 'Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).', + }, + { + name: 'as', + type: 'React.ElementType', + defaultValue: '"a"', + description: 'HTML element or React component to render instead of the default anchor.', + required: false, + }, + ], + subcomponents: [], +}) diff --git a/packages/react/src/Breadcrumbs/Breadcrumbs.docs.ts b/packages/react/src/Breadcrumbs/Breadcrumbs.docs.ts new file mode 100644 index 00000000000..d0cd5fa7830 --- /dev/null +++ b/packages/react/src/Breadcrumbs/Breadcrumbs.docs.ts @@ -0,0 +1,84 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'breadcrumbs', + name: 'Breadcrumbs', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: ['components-breadcrumbs--default'], + importPath: '@primer/react', + props: [ + { + name: 'className', + type: 'string', + required: false, + description: 'Additional CSS class names to apply to the breadcrumbs container', + defaultValue: '', + }, + { + name: 'children', + type: 'Breadcrumbs.Item[]', + defaultValue: '', + description: 'Breadcrumb items to render. Each item should be a Breadcrumbs.Item component.', + required: false, + }, + { + name: 'overflow', + type: "'wrap' | 'menu' | 'menu-with-root'", + required: false, + description: + "How to handle overflow when breadcrumbs don't fit in the container. 'wrap' allows items to wrap to new lines. 'menu' collapses items into an overflow menu. 'menu-with-root' also collapses items into an overflow menu but includes the root (first) breadcrumb in the menu so only the last items remain visible.", + defaultValue: "'wrap'", + }, + ], + subcomponents: [ + { + name: 'Breadcrumbs.Item', + props: [ + { + name: 'selected', + type: 'boolean', + defaultValue: 'false', + description: "Whether this item represents the current page. Sets aria-current='page' for accessibility.", + required: false, + }, + { + name: 'to', + type: 'string | Partial', + required: false, + description: + "Used when the item is rendered using a component like React Router's `Link`. The path to navigate to.", + defaultValue: '', + }, + { + name: 'href', + type: 'string', + required: false, + description: 'The URL that the breadcrumb item links to. Used with regular anchor elements.', + }, + { + name: 'children', + type: 'React.ReactNode', + required: true, + description: 'The content to display inside the breadcrumb item, typically text.', + }, + { + name: 'ref', + type: 'React.RefObject', + required: false, + description: + 'Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).', + }, + { + name: 'as', + type: 'React.ElementType', + defaultValue: '"a"', + description: 'HTML element or React component to render instead of the default anchor.', + required: false, + }, + ], + passthrough: {element: 'a', url: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#Attributes'}, + displayName: 'Item', + }, + ], +}) diff --git a/packages/react/src/Button/Button.docs.ts b/packages/react/src/Button/Button.docs.ts new file mode 100644 index 00000000000..1638294f712 --- /dev/null +++ b/packages/react/src/Button/Button.docs.ts @@ -0,0 +1,130 @@ +import {defineComponent} from '../docs/component' + +export default defineComponent({ + id: 'button', + name: 'Button', + status: 'alpha', + a11yReviewed: '2025-01-08', + stories: [ + 'components-button--default', + 'components-button-features--primary', + 'components-button-features--danger', + 'components-button-features--invisible', + 'components-button-features--link', + 'components-button-features--leading-visual', + 'components-button-features--trailing-visual', + 'components-button-features--trailing-counter', + 'components-button-features--trailing-counter-with-no-text', + 'components-button-features--trailing-counter-all-variants', + 'components-button-features--trailing-action', + 'components-button-features--block', + 'components-button-features--disabled', + 'components-button-features--inactive', + 'components-button-features--small', + 'components-button-features--medium', + 'components-button-features--large', + 'components-button-features--loading', + 'components-button-features--loading-custom-announcement', + 'components-button-features--loading-with-leading-visual', + 'components-button-features--loading-with-trailing-visual', + 'components-button-features--loading-with-trailing-action', + 'components-button-features--loading-trigger', + 'components-button-features--label-wrap', + 'components-button-features--inactive-button-with-tooltip', + 'components-button-features--expanded-button', + ], + importPath: '@primer/react', + props: [ + { + name: 'alignContent', + type: "'start' | 'center'", + description: 'Content alignment for when visuals are present.', + required: false, + }, + { + name: 'as', + type: 'React.ElementType', + defaultValue: "'button'", + description: 'Element or component to render instead of the default