Adds Checkbox as a new web component (microsoft#27450)

* radio init * styles radio * reverts branch * input spec init * cleans up spec * formatting * updates component name to text input * updates component name in spec * checkbox init * updats checkbox styles * checkbox: adds attributes to Checkbox * checkbox: updates checked-indicator svg and storybook templates * checkbox: updates styles * checkbox: adds exports * checkbox: organizes css * checkbox: updates styles * checkbox: adds README * checkbox: formats README * deletes dead file * checkbox: cleans up * checkbox: updates storybook content * checkbox: removes file * checkbox: yarn change * checkbox: updates README * checkbox: updates styles * checkbox: fixes styling bug * checkbox: optimze css * checkbox: updates storybook * checkbox: adds required story * checkbox: updates stories * Update change/@fluentui-web-components-eba99a5e-947a-4735-815b-86d613000d31.json Co-authored-by: Miroslav Stastny <[email protected]> * checkbox: updates README, adds focus styles * checkbox: api-report * reverts api report * checkbox: updates styles --------- Co-authored-by: Miroslav Stastny <[email protected]>
radium-v · Apr 29, 2024 · 40ad1a4 · 40ad1a4
1 parent a91b91a
commit 40ad1a4
Show file tree

Hide file tree

Showing 12 changed files with 695 additions and 0 deletions.
diff --git a/change/@fluentui-web-components-eba99a5e-947a-4735-815b-86d613000d31.json b/change/@fluentui-web-components-eba99a5e-947a-4735-815b-86d613000d31.json
@@ -0,0 +1,7 @@
+{
+  "type": "prerelease",
+  "comment": "feat(checkbox): Add checkbox web component",
+  "packageName": "@fluentui/web-components",
+  "email": "[email protected]",
+  "dependentChangeType": "patch"
+}
diff --git a/packages/web-components/package.json b/packages/web-components/package.json
@@ -48,6 +48,10 @@
       "types": "./dist/esm/button/define.d.ts",
       "default": "./dist/esm/button/define.js"
     },
+    "./checkbox": {
+      "types": "./dist/esm/checkbox/define.d.ts",
+      "default": "./dist/esm/checkbox/define.js"
+    },
     "./compound-button": {
       "types": "./dist/esm/compound-button/define.d.ts",
       "default": "./dist/esm/compound-button/define.js"

diff --git a/packages/web-components/src/checkbox/README.md b/packages/web-components/src/checkbox/README.md
@@ -0,0 +1,127 @@
+# Checkbox
+
+> An implementation of a [checkbox](https://w3c.github.io/html-reference/input.checkbox.html) as a form-connected web-component.
+
+<br />
+
+## **Design Spec**
+
+[Link to Checkbox Design Spec in Figma](https://www.figma.com/file/1a1hBVizk7aLH76IvrnPFs/Checkbox?node-id=1666-534&t=Y5ISi4tWguXRFMdP-0)
+
+<br />
+
+## **Engineering Spec**
+
+Fluent WC3 Checkbox extends from the [FAST Checkbox](https://explore.fast.design/components/fast-checkbox) and is intended to be as close to the Fluent UI React 9 Checkbox implementation as possible. However, due to the nature of web components there will not be 100% parity between the two.
+
+<br />
+
+## Class: `Checkbox`
+
+<br />
+
+### **Component Name**
+
+`<fluent-checkbox>`
+
+<br />
+
+### **Component Template**
+
+FAST `checkboxTemplate`
+
+<br />
+
+### **Variables**
+
+| Name                    | Description          | Type                                         |
+| ----------------------- | -------------------- | -------------------------------------------- |
+| `CheckboxLabelPosition` | label position types | `{ before: "before", after: "after" }`       |
+| `CheckboxShape`         | checkbox shape types | `{ square: "square", circular: "circular" }` |
+| `CheckboxSize`          | checkbox size types  | `{ medium: "medium", large: "large" }`       |
+
+<br />
+
+### **Methods**
+
+| Name              | Privacy | Description             |
+| ----------------- | ------- | ----------------------- |
+| `keypressHandler` | public  | fires on keyboard press |
+| `clickHandler `   | public  | fires on mouse click    |
+
+### **Events**
+
+| Name     | Type | Description                 | Inherited From |
+| -------- | ---- | --------------------------- | -------------- |
+| `change` |      | Fires a custom change event | `FASTCheckbox` |
+
+<br />
+
+### **Attributes**
+
+| Name             | Privacy | Type                    | Default                       | Description                                        |
+| ---------------- | ------- | ----------------------- | ----------------------------- | -------------------------------------------------- |
+| `label-position` | public  | `CheckboxLabelPosition` | `CheckboxLabelPosition.after` | Indicates postion of label                         |
+| `checked`        | public  | `boolean`               | `false`                       | Indicates whether input is checked                 |
+| `indeterminate`  | public  | `boolean`               | `false`                       | Indicates whether input is initially indeterminate |
+| `disabled`       | public  | `boolean`               | `false`                       | Indicates whether input is disabled                |
+| `required `      | public  | `boolean`               | `false`                       | Indicates whether input is required                |
+| `size`           | public  | `CheckboxSize`          | `CheckboxSize.medium`         | Indicates the size of the checkbox                 |
+| `shape`          | public  | `CheckboxShape`         | `CheckboxShape.square`        | Indicates shape of the checkbox                    |
+
+<br />
+
+### **IDL Attributes**
+
+| Name            | Field         | Type      | Description                                     |
+| --------------- | ------------- | --------- | ----------------------------------------------- |
+| `checked`       | checked       | `boolean` | The current checked state of the checkbox       |
+| `indeterminate` | indeterminate | `boolean` | The indeterminate state. Independent of checked |
+
+<br />
+
+### **Slots**
+
+| Name                      | Description                                    |
+| ------------------------- | ---------------------------------------------- |
+|                           | The default slot for text input content        |
+| `checked-indicator`       | The named slot for the checked indicator       |
+| `indeterminate-indicator` | The named slot for the indeterminate indicator |
+
+<br />
+<hr />
+<br />
+
+## **Accessibility**
+
+[W3C Checkbox Spec](https://w3c.github.io/html-reference/input.checkbox.html)
+
+<br />
+
+### **WAI-ARIA Roles, States, and Properties**
+
+- `role="checkbox"`
+- `aria-checked`
+- `aria-required`
+- `aria-disabled`
+
+<br />
+
+### **Fluent Web Component v3 v.s Fluent React 9**
+
+<br />
+
+**Component and Slot Mapping**
+
+| Fluent UI React 9 | Fluent Web Components 3         | Description                      |
+| ----------------- | ------------------------------- | -------------------------------- |
+| `<Checkbox>`      | `<fluent-checkbox>`             |
+| n/a               | slot: `checked-indicator`       | slot for checked indicator       |
+| n/a               | slot: `indeterminate-indicator` | slot for indeterminate indicator |
+
+<br />
+
+**Property Mapping**
+| Fluent UI React 9 | Fluent Web Components 3 | Description of difference |
+| ---------------------------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `checked: boolean | 'mixed'` | `checked: boolean` `indeterminate: boolean` | Fluent UI React v9 uses a single property to set the checked and indeterminate states, while Fluent UI Web Components v3 requires separate boolean attributes for each state.
diff --git a/packages/web-components/src/checkbox/checkbox.definition.ts b/packages/web-components/src/checkbox/checkbox.definition.ts
@@ -0,0 +1,17 @@
+import { FluentDesignSystem } from '../fluent-design-system.js';
+import { Checkbox } from './checkbox.js';
+import { template } from './checkbox.template.js';
+import { styles } from './checkbox.styles.js';
+
+/**
+ * The Fluent Checkbox Element
+ *
+ * @public
+ * @remarks
+ * HTML Element: \<fluent-checkbox\>
+ */
+export const definition = Checkbox.compose({
+  name: `${FluentDesignSystem.prefix}-checkbox`,
+  template,
+  styles,
+});
diff --git a/packages/web-components/src/checkbox/checkbox.options.ts b/packages/web-components/src/checkbox/checkbox.options.ts
@@ -0,0 +1,34 @@
+import { ValuesOf } from '@microsoft/fast-foundation';
+
+/**
+ * Checkbox shape
+ * @public
+ */
+export const CheckboxShape = {
+  circular: 'circular',
+  square: 'square',
+} as const;
+
+export type CheckboxShape = ValuesOf<typeof CheckboxShape>;
+
+/**
+ * Checkbox size
+ * @public
+ */
+export const CheckboxSize = {
+  medium: 'medium',
+  large: 'large',
+} as const;
+
+export type CheckboxSize = ValuesOf<typeof CheckboxSize>;
+
+/**
+ * Checkbox label position
+ * @public
+ */
+export const CheckboxLabelPosition = {
+  before: 'before',
+  after: 'after',
+} as const;
+
+export type CheckboxLabelPosition = ValuesOf<typeof CheckboxLabelPosition>;