diff --git a/.changeset/nine-parrots-melt.md b/.changeset/nine-parrots-melt.md new file mode 100644 index 0000000000..e16cfd3172 --- /dev/null +++ b/.changeset/nine-parrots-melt.md @@ -0,0 +1,5 @@ +--- +'@backstage/ui': patch +--- + +Add an initial CheckboxGroup component implementation and docs coverage. diff --git a/docs-ui/src/app/components/checkbox-group/components.tsx b/docs-ui/src/app/components/checkbox-group/components.tsx new file mode 100644 index 0000000000..4d32bdaf75 --- /dev/null +++ b/docs-ui/src/app/components/checkbox-group/components.tsx @@ -0,0 +1,81 @@ +'use client'; + +import { CheckboxGroup } from '../../../../../packages/ui/src/components/CheckboxGroup/CheckboxGroup'; +import { Checkbox } from '../../../../../packages/ui/src/components/Checkbox/Checkbox'; + +export const Default = () => { + return ( + + GitHub + Slack + Email + + ); +}; + +export const Horizontal = () => ( + + GitHub + Slack + Email + +); + +export const Disabled = () => ( + + GitHub + Slack + Email + +); + +export const DisabledSingle = () => ( + + GitHub + + Slack + + Email + +); + +export const Validation = () => ( + + value.includes('slack') ? 'Slack is not available in your region.' : null + } + > + GitHub + Slack + Email + +); + +export const ReadOnly = () => ( + + GitHub + Slack + Email + +); diff --git a/docs-ui/src/app/components/checkbox-group/page.mdx b/docs-ui/src/app/components/checkbox-group/page.mdx new file mode 100644 index 0000000000..2ff41a5d9b --- /dev/null +++ b/docs-ui/src/app/components/checkbox-group/page.mdx @@ -0,0 +1,110 @@ +import { PropsTable } from '@/components/PropsTable'; +import { Snippet } from '@/components/Snippet'; +import { ReactAriaLink } from '@/components/ReactAriaLink'; +import { checkboxGroupPropDefs } from './props-definition'; +import { + checkboxGroupUsageSnippet, + defaultSnippet, + horizontalSnippet, + disabledSnippet, + disabledSingleSnippet, + validationSnippet, + readOnlySnippet, +} from './snippets'; +import { + Default, + Horizontal, + Disabled, + DisabledSingle, + Validation, + ReadOnly, +} from './components'; +import { PageTitle } from '@/components/PageTitle'; +import { Theming } from '@/components/Theming'; +import { ChangelogComponent } from '@/components/ChangelogComponent'; +import { CodeBlock } from '@/components/CodeBlock'; +import { CheckboxGroupDefinition } from '../../../utils/definitions'; + +export const reactAriaUrls = { + checkboxGroup: 'https://react-aria.adobe.com/CheckboxGroup', +}; + + + +} code={defaultSnippet} /> + +## Usage + + + +## API reference + +### CheckboxGroup + + + + + +## Examples + +### Horizontal + +} + code={horizontalSnippet} +/> + +### Disabled + +} + code={disabledSnippet} +/> + +### Disabled single checkbox + +} + code={disabledSingleSnippet} +/> + +### Validation + +} + code={validationSnippet} +/> + +### Read only + +} + code={readOnlySnippet} +/> + + + + diff --git a/docs-ui/src/app/components/checkbox-group/props-definition.tsx b/docs-ui/src/app/components/checkbox-group/props-definition.tsx new file mode 100644 index 0000000000..09b5aeda4b --- /dev/null +++ b/docs-ui/src/app/components/checkbox-group/props-definition.tsx @@ -0,0 +1,82 @@ +import { + classNamePropDefs, + childrenPropDefs, + stylePropDefs, + type PropDef, +} from '@/utils/propDefs'; +import { Chip } from '@/components/Chip'; + +export const checkboxGroupPropDefs: Record = { + label: { + type: 'string', + description: 'The visible label for the checkbox group.', + }, + 'aria-label': { + type: 'string', + description: + 'Accessible label when a visible label is not provided. Either label, aria-label, or aria-labelledby is required.', + }, + 'aria-labelledby': { + type: 'string', + description: + 'ID of an element that labels the checkbox group. Either label, aria-label, or aria-labelledby is required.', + }, + secondaryLabel: { + type: 'string', + description: ( + <> + Secondary label text. Defaults to Required when isRequired + is true. + + ), + }, + description: { + type: 'string', + description: 'Helper text displayed below the label.', + }, + orientation: { + type: 'enum', + values: ['horizontal', 'vertical'], + default: 'vertical', + description: 'The axis the checkboxes should align with.', + }, + value: { + type: 'enum', + values: ['string[]'], + description: 'The selected values (controlled).', + }, + defaultValue: { + type: 'enum', + values: ['string[]'], + description: 'The initial selected values (uncontrolled).', + }, + onChange: { + type: 'enum', + values: ['(value: string[]) => void'], + description: 'Handler called when the selected values change.', + }, + isDisabled: { + type: 'boolean', + description: 'Whether all checkboxes in the group are disabled.', + }, + isReadOnly: { + type: 'boolean', + description: 'Whether all checkboxes in the group are read-only.', + }, + isRequired: { + type: 'boolean', + description: + 'Whether at least one selection is required for form submission.', + }, + isInvalid: { + type: 'boolean', + description: 'Whether the checkbox group is in an invalid state.', + }, + name: { + type: 'string', + description: 'The name used for form submission.', + }, + ...childrenPropDefs, + ...classNamePropDefs, + ...stylePropDefs, +}; diff --git a/docs-ui/src/app/components/checkbox-group/snippets.ts b/docs-ui/src/app/components/checkbox-group/snippets.ts new file mode 100644 index 0000000000..70104a2458 --- /dev/null +++ b/docs-ui/src/app/components/checkbox-group/snippets.ts @@ -0,0 +1,65 @@ +export const checkboxGroupUsageSnippet = `import { CheckboxGroup, Checkbox } from '@backstage/ui'; + + + GitHub + Slack + Email +`; + +export const defaultSnippet = ` + GitHub + Slack + Email +`; + +export const horizontalSnippet = ` + GitHub + Slack + Email +`; + +export const disabledSnippet = ` + GitHub + Slack + Email +`; + +export const disabledSingleSnippet = ` + GitHub + Slack + Email +`; + +export const validationSnippet = ` + value.includes('slack') ? 'Slack is not available in your region.' : null + } +> + GitHub + Slack + Email +`; + +export const readOnlySnippet = ` + GitHub + Slack + Email +`; diff --git a/docs-ui/src/utils/data.ts b/docs-ui/src/utils/data.ts index 3d958f5b7c..2a16065930 100644 --- a/docs-ui/src/utils/data.ts +++ b/docs-ui/src/utils/data.ts @@ -45,6 +45,10 @@ export const components: Page[] = [ title: 'Checkbox', slug: 'checkbox', }, + { + title: 'CheckboxGroup', + slug: 'checkbox-group', + }, { title: 'Container', slug: 'container', diff --git a/docs-ui/src/utils/types.ts b/docs-ui/src/utils/types.ts index 8e03a1df07..ff1aac2e56 100644 --- a/docs-ui/src/utils/types.ts +++ b/docs-ui/src/utils/types.ts @@ -17,6 +17,7 @@ export type Component = | 'cell-profile' | 'cell-text' | 'checkbox' + | 'checkbox-group' | 'collapsible' | 'column' | 'container' diff --git a/packages/ui/report.api.md b/packages/ui/report.api.md index a2588e22de..f56959fb36 100644 --- a/packages/ui/report.api.md +++ b/packages/ui/report.api.md @@ -5,6 +5,7 @@ ```ts import type { ButtonProps as ButtonProps_2 } from 'react-aria-components'; import { CellProps as CellProps_2 } from 'react-aria-components'; +import type { CheckboxGroupProps as CheckboxGroupProps_2 } from 'react-aria-components'; import type { CheckboxProps as CheckboxProps_2 } from 'react-aria-components'; import { ColumnProps as ColumnProps_2 } from 'react-aria-components'; import type { ColumnSize } from '@react-types/table'; @@ -374,7 +375,7 @@ export interface BgProviderProps { children: ReactNode; } -// @public (undocumented) +// @public export type Border = 'none' | 'base' | 'error' | 'warning' | 'selected'; // @public (undocumented) @@ -879,6 +880,47 @@ export const CheckboxDefinition: { }; }; +// @public +export const CheckboxGroup: ForwardRefExoticComponent< + CheckboxGroupProps & RefAttributes +>; + +// @public +export const CheckboxGroupDefinition: { + readonly styles: { + readonly [key: string]: string; + }; + readonly classNames: { + readonly root: 'bui-CheckboxGroup'; + readonly content: 'bui-CheckboxGroupContent'; + }; + readonly propDefs: { + readonly className: {}; + readonly children: {}; + readonly label: {}; + readonly secondaryLabel: {}; + readonly description: {}; + readonly isRequired: {}; + readonly orientation: {}; + }; +}; + +// @public +export type CheckboxGroupOwnProps = { + className?: string; + children?: ReactNode; + label?: FieldLabelProps['label']; + secondaryLabel?: FieldLabelProps['secondaryLabel']; + description?: FieldLabelProps['description']; + isRequired?: CheckboxGroupProps_2['isRequired']; + orientation?: 'horizontal' | 'vertical'; +}; + +// @public +export interface CheckboxGroupProps + extends Omit, + CheckboxGroupOwnProps {} + // @public (undocumented) export type CheckboxOwnProps = { children?: React.ReactNode; @@ -3284,33 +3326,20 @@ export interface UseTableResult { >; } -// @public (undocumented) +// @public export interface UtilityProps extends SpaceProps { - // (undocumented) alignItems?: Responsive; - // (undocumented) border?: Responsive; - // (undocumented) borderRadius?: Responsive; - // (undocumented) colEnd?: Responsive; - // (undocumented) colSpan?: Responsive; - // (undocumented) colStart?: Responsive; - // (undocumented) columns?: Responsive; - // (undocumented) display?: Responsive; - // (undocumented) flexDirection?: Responsive; - // (undocumented) flexWrap?: Responsive; - // (undocumented) gap?: Responsive; - // (undocumented) justifyContent?: Responsive; - // (undocumented) rowSpan?: Responsive; } diff --git a/packages/ui/src/components/CheckboxGroup/CheckboxGroup.module.css b/packages/ui/src/components/CheckboxGroup/CheckboxGroup.module.css new file mode 100644 index 0000000000..8337ea9b91 --- /dev/null +++ b/packages/ui/src/components/CheckboxGroup/CheckboxGroup.module.css @@ -0,0 +1,19 @@ +@layer tokens, base, components, utilities; + +@layer components { + .bui-CheckboxGroup { + display: flex; + flex-direction: column; + } + + .bui-CheckboxGroup[data-orientation='horizontal'] .bui-CheckboxGroupContent { + flex-direction: row; + gap: var(--bui-space-4); + } + + .bui-CheckboxGroupContent { + display: flex; + flex-direction: column; + gap: var(--bui-space-2); + } +} diff --git a/packages/ui/src/components/CheckboxGroup/CheckboxGroup.stories.tsx b/packages/ui/src/components/CheckboxGroup/CheckboxGroup.stories.tsx new file mode 100644 index 0000000000..673bf479b5 --- /dev/null +++ b/packages/ui/src/components/CheckboxGroup/CheckboxGroup.stories.tsx @@ -0,0 +1,193 @@ +/* + * Copyright 2026 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { useState } from 'react'; +import preview from '../../../../../.storybook/preview'; +import { CheckboxGroup } from './CheckboxGroup'; +import { Checkbox } from '../Checkbox/Checkbox'; +import { Text } from '../Text'; + +const meta = preview.meta({ + title: 'Backstage UI/CheckboxGroup', + component: CheckboxGroup, +}); + +export const Default = meta.story({ + args: { + label: 'Choose platforms for notifications', + defaultValue: ['github'], + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const Controlled = meta.story({ + args: { + label: 'Choose platforms for notifications', + }, + render: args => { + const [values, setValues] = useState(['email']); + + return ( + <> + + GitHub + Slack + Email + + Selected: {values.join(', ') || 'none'} + + ); + }, +}); + +export const Horizontal = meta.story({ + args: { + ...Default.input.args, + orientation: 'horizontal', + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const Disabled = meta.story({ + args: { + ...Default.input.args, + isDisabled: true, + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const DisabledSingle = meta.story({ + args: { + ...Default.input.args, + }, + render: args => ( + + GitHub + + Slack + + Email + + ), +}); + +export const DisabledAndSelected = meta.story({ + args: { + ...Default.input.args, + defaultValue: ['slack'], + }, + render: args => ( + + GitHub + + Slack + + Email + + ), +}); + +export const Invalid = meta.story({ + args: { + ...Default.input.args, + isInvalid: true, + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const ReadOnly = meta.story({ + args: { + ...Default.input.args, + isReadOnly: true, + defaultValue: ['github'], + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const WithDescription = meta.story({ + args: { + ...Default.input.args, + description: 'Select all channels where you want to receive notifications.', + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const Required = meta.story({ + args: { + ...Default.input.args, + isRequired: true, + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); + +export const Validation = meta.story({ + args: { + ...Default.input.args, + defaultValue: ['github', 'slack'], + validationBehavior: 'aria', + validate: (value: string[]) => + value.includes('slack') ? 'Slack is not available in your region.' : null, + }, + render: args => ( + + GitHub + Slack + Email + + ), +}); diff --git a/packages/ui/src/components/CheckboxGroup/CheckboxGroup.tsx b/packages/ui/src/components/CheckboxGroup/CheckboxGroup.tsx new file mode 100644 index 0000000000..708b6e4b86 --- /dev/null +++ b/packages/ui/src/components/CheckboxGroup/CheckboxGroup.tsx @@ -0,0 +1,79 @@ +/* + * Copyright 2026 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { forwardRef, useEffect } from 'react'; +import { CheckboxGroup as RACheckboxGroup } from 'react-aria-components'; +import type { CheckboxGroupProps } from './types'; +import { useDefinition } from '../../hooks/useDefinition'; +import { CheckboxGroupDefinition } from './definition'; +import { FieldLabel } from '../FieldLabel'; +import { FieldError } from '../FieldError'; + +/** + * A group of checkboxes for selecting multiple options from a list. + * @public + */ +export const CheckboxGroup = forwardRef( + (props, ref) => { + const { ownProps, restProps } = useDefinition( + CheckboxGroupDefinition, + props, + ); + const { + classes, + label, + secondaryLabel, + description, + isRequired, + orientation, + children, + } = ownProps; + + const ariaLabel = restProps['aria-label']; + const ariaLabelledBy = restProps['aria-labelledby']; + + useEffect(() => { + if (!label && !ariaLabel && !ariaLabelledBy) { + console.warn( + 'CheckboxGroup requires either a visible label, aria-label, or aria-labelledby for accessibility', + ); + } + }, [label, ariaLabel, ariaLabelledBy]); + + const secondaryLabelText = + secondaryLabel || (isRequired ? 'Required' : null); + + return ( + + +
{children}
+ + + ); + }, +); + +CheckboxGroup.displayName = 'CheckboxGroup'; diff --git a/packages/ui/src/components/CheckboxGroup/definition.ts b/packages/ui/src/components/CheckboxGroup/definition.ts new file mode 100644 index 0000000000..d4f75e1789 --- /dev/null +++ b/packages/ui/src/components/CheckboxGroup/definition.ts @@ -0,0 +1,42 @@ +/* + * Copyright 2026 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { defineComponent } from '../../hooks/useDefinition'; +import type { CheckboxGroupOwnProps } from './types'; +import styles from './CheckboxGroup.module.css'; + +/** + * Component definition for CheckboxGroup + * @public + */ +export const CheckboxGroupDefinition = defineComponent()( + { + styles, + classNames: { + root: 'bui-CheckboxGroup', + content: 'bui-CheckboxGroupContent', + }, + propDefs: { + className: {}, + children: {}, + label: {}, + secondaryLabel: {}, + description: {}, + isRequired: {}, + orientation: {}, + }, + }, +); diff --git a/packages/ui/src/components/CheckboxGroup/index.ts b/packages/ui/src/components/CheckboxGroup/index.ts new file mode 100644 index 0000000000..8483649c4d --- /dev/null +++ b/packages/ui/src/components/CheckboxGroup/index.ts @@ -0,0 +1,18 @@ +/* + * Copyright 2026 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +export { CheckboxGroup } from './CheckboxGroup'; +export { CheckboxGroupDefinition } from './definition'; +export type { CheckboxGroupOwnProps, CheckboxGroupProps } from './types'; diff --git a/packages/ui/src/components/CheckboxGroup/types.ts b/packages/ui/src/components/CheckboxGroup/types.ts new file mode 100644 index 0000000000..70666f01e3 --- /dev/null +++ b/packages/ui/src/components/CheckboxGroup/types.ts @@ -0,0 +1,41 @@ +/* + * Copyright 2026 The Backstage Authors + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import type { CheckboxGroupProps as RACheckboxGroupProps } from 'react-aria-components'; +import type { ReactNode } from 'react'; +import type { FieldLabelProps } from '../FieldLabel/types'; + +/** + * Own props for the CheckboxGroup component. + * @public + */ +export type CheckboxGroupOwnProps = { + className?: string; + children?: ReactNode; + label?: FieldLabelProps['label']; + secondaryLabel?: FieldLabelProps['secondaryLabel']; + description?: FieldLabelProps['description']; + isRequired?: RACheckboxGroupProps['isRequired']; + orientation?: 'horizontal' | 'vertical'; +}; + +/** + * Props for the CheckboxGroup component. + * @public + */ +export interface CheckboxGroupProps + extends Omit, + CheckboxGroupOwnProps {} diff --git a/packages/ui/src/definitions.ts b/packages/ui/src/definitions.ts index 3cc94e1cde..1d16c67f2a 100644 --- a/packages/ui/src/definitions.ts +++ b/packages/ui/src/definitions.ts @@ -34,6 +34,7 @@ export { ButtonIconDefinition } from './components/ButtonIcon/definition'; export { ButtonLinkDefinition } from './components/ButtonLink/definition'; export { CardDefinition } from './components/Card/definition'; export { CheckboxDefinition } from './components/Checkbox/definition'; +export { CheckboxGroupDefinition } from './components/CheckboxGroup/definition'; export { ContainerDefinition } from './components/Container/definition'; export { DialogDefinition } from './components/Dialog/definition'; export { FieldErrorDefinition } from './components/FieldError/definition'; diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts index 464df3a845..708e816349 100644 --- a/packages/ui/src/index.ts +++ b/packages/ui/src/index.ts @@ -41,6 +41,7 @@ export * from './components/Header'; export * from './components/ButtonIcon'; export * from './components/ButtonLink'; export * from './components/Checkbox'; +export * from './components/CheckboxGroup'; export * from './components/RadioGroup'; export * from './components/Slider'; export * from './components/Table'; diff --git a/packages/ui/src/types.ts b/packages/ui/src/types.ts index 7a302e1694..113eb06a5c 100644 --- a/packages/ui/src/types.ts +++ b/packages/ui/src/types.ts @@ -72,7 +72,11 @@ export type BorderRadius = | 'xl' | '2xl'; -/** @public */ +/** + * Border variants available for UI utility props. + * + * @public + */ export type Border = 'none' | 'base' | 'error' | 'warning' | 'selected'; /** @public */ @@ -136,20 +140,37 @@ export type TextColorStatus = 'danger' | 'warning' | 'success' | 'info'; /** @public */ export type TextWeights = 'regular' | 'bold'; -/** @public */ +/** + * Shared utility props supported by layout-oriented UI components. + * + * @public + */ export interface UtilityProps extends SpaceProps { + /** Aligns children on the cross axis in flex and grid layouts. */ alignItems?: Responsive; + /** Applies a semantic border variant. */ border?: Responsive; + /** Applies a semantic border radius token. */ borderRadius?: Responsive; + /** Sets the ending grid column line. */ colEnd?: Responsive; + /** Sets the number of grid columns to span. */ colSpan?: Responsive; + /** Sets the starting grid column line. */ colStart?: Responsive; + /** Sets the number of columns for grid containers. */ columns?: Responsive; + /** Controls the CSS display value. */ display?: Responsive; + /** Controls the direction of flex items. */ flexDirection?: Responsive; + /** Controls how flex items wrap. */ flexWrap?: Responsive; + /** Sets spacing between children in flex and grid layouts. */ gap?: Responsive; + /** Aligns children on the main axis in flex and grid layouts. */ justifyContent?: Responsive; + /** Sets the number of grid rows to span. */ rowSpan?: Responsive; }