From 6b2d46b046f683a2a4dab277b1baac9d3e05cd67 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Tue, 10 Dec 2024 08:46:24 +0000
Subject: [PATCH] Improve API

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 packages/canon/report.api.md                  | 35 +++++++++-
 .../components/Checkbox/Checkbox.stories.tsx  |  2 +-
 .../src/components/Checkbox/Checkbox.tsx      | 48 +++++++++++---
 .../canon/src/components/Checkbox/Docs.mdx    | 66 +++++++++++++++++++
 .../canon/src/components/Checkbox/index.ts    |  1 +
 .../canon/src/components/Checkbox/types.ts    | 29 ++++++++
 packages/canon/src/index.ts                   |  1 +
 7 files changed, 172 insertions(+), 10 deletions(-)
 create mode 100644 packages/canon/src/components/Checkbox/Docs.mdx
 create mode 100644 packages/canon/src/components/Checkbox/types.ts

diff --git a/packages/canon/report.api.md b/packages/canon/report.api.md
index c27b8da09b..b314020d81 100644
--- a/packages/canon/report.api.md
+++ b/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'
diff --git a/packages/canon/src/components/Checkbox/Checkbox.stories.tsx b/packages/canon/src/components/Checkbox/Checkbox.stories.tsx
index 7ebe4d3df4..ffd874ffe7 100644
--- a/packages/canon/src/components/Checkbox/Checkbox.stories.tsx
+++ b/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',
   },
 };
diff --git a/packages/canon/src/components/Checkbox/Checkbox.tsx b/packages/canon/src/components/Checkbox/Checkbox.tsx
index 178c3b67ec..3021032421 100644
--- a/packages/canon/src/components/Checkbox/Checkbox.tsx
+++ b/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
+    );
+  },
+);
diff --git a/packages/canon/src/components/Checkbox/Docs.mdx b/packages/canon/src/components/Checkbox/Docs.mdx
new file mode 100644
index 0000000000..9d9b4e4915
--- /dev/null
+++ b/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>
diff --git a/packages/canon/src/components/Checkbox/index.ts b/packages/canon/src/components/Checkbox/index.ts
index 094502442d..f6dfbf6beb 100644
--- a/packages/canon/src/components/Checkbox/index.ts
+++ b/packages/canon/src/components/Checkbox/index.ts
@@ -14,3 +14,4 @@
  * limitations under the License.
  */
 export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './types';
diff --git a/packages/canon/src/components/Checkbox/types.ts b/packages/canon/src/components/Checkbox/types.ts
new file mode 100644
index 0000000000..0240954afa
--- /dev/null
+++ b/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;
+}
diff --git a/packages/canon/src/index.ts b/packages/canon/src/index.ts
index 6497be2945..5d0ebb5a2e 100644
--- a/packages/canon/src/index.ts
+++ b/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';