Improve API

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>

packages/canon/report.api.md

@@ -129,6 +129,35 @@ export interface ButtonProps {
   variant?: 'primary' | 'secondary' | 'tertiary';
 }
 
+// @public (undocumented)
+export const Checkbox: React_2.ForwardRefExoticComponent<
+  CheckboxProps & React_2.RefAttributes<HTMLButtonElement>
+>;
+
+// @public (undocumented)
+export interface CheckboxProps {
+  // (undocumented)
+  checked?: boolean;
+  // (undocumented)
+  className?: string;
+  // (undocumented)
+  defaultChecked?: boolean;
+  // (undocumented)
+  disabled?: boolean;
+  // (undocumented)
+  label?: string;
+  // (undocumented)
+  name?: string;
+  // (undocumented)
+  onChange?: (checked: boolean) => void;
+  // (undocumented)
+  required?: boolean;
+  // (undocumented)
+  style?: React.CSSProperties;
+  // (undocumented)
+  value?: string;
+}
+
 // @public (undocumented)
 export type Color =
   | 'primary'
@@ -237,7 +266,10 @@ export interface GridProps extends SpaceProps, ColorProps {
 }
 
 // @public (undocumented)
-export const Icon: ({ name }: { name: IconNames }) => React_2.JSX.Element;
+export const Icon: (props: {
+  name: IconNames;
+  size?: number;
+}) => React_2.JSX.Element;
 
 // @public (undocumented)
 export type IconMap = Partial<Record<IconNames, React.ComponentType>>;
@@ -252,6 +284,7 @@ export type IconNames =
   | 'arrowLeftCircle'
   | 'arrowRightCircle'
   | 'arrowUpCircle'
+  | 'check'
   | 'chevronDown'
   | 'chevronLeft'
   | 'chevronRight'

packages/canon/src/components/Checkbox/Checkbox.stories.tsx

@@ -30,6 +30,6 @@ type Story = StoryObj<typeof meta>;
 
 export const Primary: Story = {
   args: {
-    children: 'Primary button',
+    label: 'Accept terms and conditions',
   },
 };

packages/canon/src/components/Checkbox/Checkbox.tsx

@@ -17,16 +17,48 @@ import React from 'react';
 
 import { CheckboxRoot, CheckboxIndicator } from '@base_ui/react';
 import { Icon } from '@backstage/canon';
+import type { CheckboxProps } from './types';
 
-export const Checkbox = () => {
-  return (
-    <label className="checkbox-label">
-      <CheckboxRoot className="checkbox">
+/** @public */
+export const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
+  (props, ref) => {
+    const {
+      label,
+      checked,
+      onChange,
+      disabled,
+      required,
+      className,
+      name,
+      value,
+      style,
+    } = props;
+
+    const checkboxElement = (
+      <CheckboxRoot
+        ref={ref}
+        className={`checkbox ${className}`}
+        checked={checked}
+        onCheckedChange={onChange}
+        disabled={disabled}
+        required={required}
+        name={name}
+        value={value}
+        style={style}
+      >
         <CheckboxIndicator className="checkbox-indicator">
           <Icon name="check" size={12} />
         </CheckboxIndicator>
       </CheckboxRoot>
-      Label
-    </label>
-  );
-};
+    );
+
+    return label ? (
+      <label className="checkbox-label">
+        {checkboxElement}
+        {label}
+      </label>
+    ) : (
+      checkboxElement
+    );
+  },
+);

packages/canon/src/components/Checkbox/Docs.mdx

@@ -0,0 +1,66 @@
+import { Canvas, Meta, Unstyled, Source } from '@storybook/blocks';
+import * as CheckboxStories from './Checkbox.stories';
+import { Title, Text } from '../../../docs/components';
+import { PropsTable } from '../../../docs/components/PropsTable';
+
+<Meta of={CheckboxStories} />
+
+<Unstyled>
+
+<Title type="h1">Checkbox</Title>
+<Text>A checkbox component that can be used to trigger actions.</Text>
+
+<Canvas of={CheckboxStories.Primary} />
+
+<Source of={CheckboxStories.Primary} dark />
+
+<Title type="h2" style={{ marginBottom: '16px' }}>
+  API reference
+</Title>
+
+<PropsTable
+  data={{
+    label: {
+      type: 'string',
+      responsive: false,
+    },
+    defaultChecked: {
+      type: ['boolean', "'indeterminate'"],
+      responsive: false,
+    },
+    checked: {
+      type: ['boolean', "'indeterminate'"],
+      responsive: false,
+    },
+    onChange: {
+      type: "(checked: boolean | 'indeterminate') => void",
+      responsive: false,
+    },
+    disabled: {
+      type: 'boolean',
+      responsive: false,
+    },
+    required: {
+      type: 'boolean',
+      responsive: false,
+    },
+    name: {
+      type: 'string',
+      responsive: false,
+    },
+    value: {
+      type: 'string',
+      responsive: false,
+    },
+    className: {
+      type: 'string',
+      responsive: false,
+    },
+    style: {
+      type: 'CSSProperties',
+      responsive: false,
+    },
+  }}
+/>
+
+</Unstyled>

packages/canon/src/components/Checkbox/index.ts

@@ -14,3 +14,4 @@
  * limitations under the License.
  */
 export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './types';

packages/canon/src/components/Checkbox/types.ts

@@ -0,0 +1,29 @@
+/*
+ * Copyright 2024 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.
+ */
+
+/** @public */
+export interface CheckboxProps {
+  label?: string;
+  defaultChecked?: boolean;
+  checked?: boolean;
+  onChange?: (checked: boolean) => void;
+  disabled?: boolean;
+  required?: boolean;
+  className?: string;
+  name?: string;
+  value?: string;
+  style?: React.CSSProperties;
+}

packages/canon/src/index.ts

@@ -33,3 +33,4 @@ export * from './components/Container';
 // UI components
 export * from './components/Button';
 export * from './components/Icon';
+export * from './components/Checkbox';