@fvc/checkbox 1.0.1 → 1.0.2-rc.0

package/README.md

@@ -0,0 +1,201 @@
+# @fvc/checkbox
+
+`@fvc/checkbox` provides FE-VIS styled checkbox primitives on top of Ant Design Checkbox. It keeps the Ant Design Checkbox API familiar while adding size variants, visibility control, full-width layout, white-space wrapping, and a grouped layout mode.
+
+## Installation
+
+```bash
+bun add @fvc/checkbox
+```
+
+## Peer Dependencies
+
+```bash
+bun add react antd
+```
+
+## Import
+
+```tsx
+import { Checkbox } from '@fvc/checkbox';
+```
+
+## Quick Start
+
+```tsx
+import { Checkbox } from '@fvc/checkbox';
+
+export function AgreeField() {
+  return (
+    <Checkbox onChange={(e) => setAgreed(e.target.checked)}>
+      I agree to the terms and conditions
+    </Checkbox>
+  );
+}
+```
+
+## Components
+
+| Component | Use case |
+| --- | --- |
+| `Checkbox` | Single checkbox. |
+| `Checkbox.Group` | Group of checkboxes with optional block layout. |
+
+## Common Usage
+
+### Controlled
+
+```tsx
+<Checkbox
+  checked={agreed}
+  onChange={(e) => setAgreed(e.target.checked)}
+>
+  I agree to the terms
+</Checkbox>
+```
+
+### Sizes
+
+```tsx
+<Checkbox size="medium">Medium (default)</Checkbox>
+<Checkbox size="small">Small</Checkbox>
+```
+
+### Indeterminate
+
+```tsx
+<Checkbox indeterminate={someChecked} checked={allChecked} onChange={handleAll}>
+  Select all
+</Checkbox>
+```
+
+### Disabled
+
+```tsx
+<Checkbox disabled>Unavailable option</Checkbox>
+```
+
+### Full Width
+
+```tsx
+<Checkbox fullWidth>Full-width checkbox label</Checkbox>
+```
+
+### Wrapping Long Labels
+
+```tsx
+<Checkbox whiteSpaceWrapped>
+  This is a very long checkbox label that should wrap onto the next line without being truncated.
+</Checkbox>
+```
+
+### Hidden
+
+```tsx
+<Checkbox visible={false}>Hidden but rendered</Checkbox>
+```
+
+### Group
+
+```tsx
+<Checkbox.Group
+  options={[
+    { label: 'Option A', value: 'a' },
+    { label: 'Option B', value: 'b' },
+    { label: 'Option C', value: 'c' },
+  ]}
+  value={selected}
+  onChange={setSelected}
+/>
+```
+
+### Group Block Layout
+
+```tsx
+<Checkbox.Group
+  block
+  options={[
+    { label: 'Read', value: 'read' },
+    { label: 'Write', value: 'write' },
+    { label: 'Delete', value: 'delete' },
+  ]}
+  value={permissions}
+  onChange={setPermissions}
+/>
+```
+
+## Props
+
+### Checkbox
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `size` | `'medium' \| 'small'` | Checkbox size. Defaults to `'medium'`. |
+| `visible` | `boolean` | Controls visibility without removing from DOM. Defaults to `true`. |
+| `fullWidth` | `boolean` | Stretches the checkbox to full container width. |
+| `whiteSpaceWrapped` | `boolean` | Allows the label text to wrap onto multiple lines. |
+| `testId` | `string` | Maps to `data-testid`. |
+| *All `CheckboxProps`* | — | All Ant Design Checkbox props (`checked`, `defaultChecked`, `indeterminate`, `disabled`, `onChange`, etc.). |
+
+### Checkbox.Group
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `block` | `boolean` | Displays each checkbox as a full-width block item. |
+| *All `CheckboxGroupProps`* | — | All Ant Design CheckboxGroup props (`options`, `value`, `defaultValue`, `disabled`, `onChange`, etc.). |
+
+## Consumer Example
+
+```tsx
+import { Checkbox } from '@fvc/checkbox';
+
+export function PermissionsField({ value, onChange }) {
+  return (
+    <Checkbox.Group
+      block
+      options={[
+        { label: 'View records', value: 'view' },
+        { label: 'Create records', value: 'create' },
+        { label: 'Edit records', value: 'edit' },
+        { label: 'Delete records', value: 'delete' },
+      ]}
+      value={value}
+      onChange={onChange}
+    />
+  );
+}
+```
+
+## Testing
+
+```tsx
+<Checkbox testId="agree-checkbox">I agree</Checkbox>
+```
+
+```tsx
+screen.getByTestId('agree-checkbox');
+```
+
+## CSS Customisation
+
+```css
+:root {
+  /* Primary checkbox colour */
+  --blue-500: #1677ff;
+
+  /* Hover and disabled state */
+  --blue-300: #69b1ff;
+
+  /* Checkbox background */
+  --neutral-0: #ffffff;
+}
+```
+
+## Development
+
+```bash
+bun run lint
+bun run type-check
+bun run test
+bun run build
+```

package/package.json

@@ -1,6 +1,16 @@
 {
   "name": "@fvc/checkbox",
-  "version": "1.0.1",
+  "version": "1.0.2-rc.0",
+  "keywords": [
+    "react",
+    "react-component",
+    "fvc",
+    "fe-vis-core",
+    "ui",
+    "checkbox",
+    "design-system",
+    "antd"
+  ],
   "main": "./dist/lib/index.js",
   "types": "./dist/lib/checkbox/src/index.d.ts",
   "files": [