@fvc/radio 1.0.1 → 1.0.2-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997

package/README.md

@@ -0,0 +1,195 @@
+# @fvc/radio
+
+`@fvc/radio` provides FE-VIS styled radio button primitives on top of Ant Design. It keeps the Ant Design Radio API familiar while applying the design-system token palette used across FE-VIS applications: themed border and dot colors, a disabled state, a block layout option for full-width groups, and a test-friendly `testId` prop.
+
+## Installation
+
+```bash
+bun add @fvc/radio
+```
+
+## Peer Dependencies
+
+The package expects these dependencies to be available in the consuming application:
+
+```bash
+bun add react antd
+```
+
+## Import
+
+```tsx
+import { Radio } from '@fvc/radio';
+```
+
+## Quick Start
+
+```tsx
+import { Radio } from '@fvc/radio';
+import { useState } from 'react';
+
+export function AgreementForm() {
+  const [value, setValue] = useState('yes');
+
+  return (
+    <Radio.Group value={value} onChange={(e) => setValue(e.target.value)}>
+      <Radio value="yes">Yes</Radio>
+      <Radio value="no">No</Radio>
+    </Radio.Group>
+  );
+}
+```
+
+## Common Usage
+
+### Standalone Radio
+
+```tsx
+<Radio value="a">Option A</Radio>
+```
+
+### Controlled Group
+
+Wrap multiple `Radio` items in `Radio.Group` to manage a set of mutually exclusive choices.
+
+```tsx
+const [value, setValue] = useState('a');
+
+<Radio.Group value={value} onChange={(e) => setValue(e.target.value)}>
+  <Radio value="a">Option A</Radio>
+  <Radio value="b">Option B</Radio>
+  <Radio value="c">Option C</Radio>
+</Radio.Group>;
+```
+
+### Block Group
+
+The `block` prop stretches every radio item to fill the full width of its container.
+
+```tsx
+<Radio.Group block value={value} onChange={(e) => setValue(e.target.value)}>
+  <Radio value="a">Option A</Radio>
+  <Radio value="b">Option B</Radio>
+</Radio.Group>
+```
+
+### Disabled
+
+Both individual radios and the entire group can be disabled.
+
+```tsx
+<Radio disabled value="a">Disabled option</Radio>
+
+<Radio.Group disabled value={value}>
+  <Radio value="a">Option A</Radio>
+  <Radio value="b">Option B</Radio>
+</Radio.Group>
+```
+
+## Props
+
+### `<Radio>`
+
+Extends all [Ant Design `RadioProps`](https://ant-design.antgroup.com/components/radio#api).
+
+| Prop       | Type        | Description                                       |
+| ---------- | ----------- | ------------------------------------------------- |
+| `value`    | `any`       | The value bound to the radio input.               |
+| `checked`  | `boolean`   | Whether the radio is selected (controlled).       |
+| `disabled` | `boolean`   | Disables the radio and removes it from tab order. |
+| `onChange` | `function`  | Callback fired when the radio selection changes.  |
+| `testId`   | `string`    | Maps to `data-testid` on the inner `<input>`.     |
+| `children` | `ReactNode` | Label displayed alongside the radio.              |
+
+### `<Radio.Group>`
+
+Extends all [Ant Design `RadioGroupProps`](https://ant-design.antgroup.com/components/radio#radiogroup).
+
+| Prop           | Type       | Description                                        |
+| -------------- | ---------- | -------------------------------------------------- |
+| `value`        | `any`      | Currently selected value (controlled).             |
+| `defaultValue` | `any`      | Initially selected value (uncontrolled).           |
+| `disabled`     | `boolean`  | Disables all radios within the group.              |
+| `onChange`     | `function` | Callback fired when selection changes.             |
+| `block`        | `boolean`  | Stretches each radio item to full container width. |
+| `className`    | `string`   | Additional CSS class names on the group wrapper.   |
+
+## TypeScript
+
+The package ships with type definitions. No `@types/` install needed.
+
+```ts
+import type { RadioProps, GroupProps } from '@fvc/radio/types';
+```
+
+## Consumer Example
+
+```tsx
+import { Radio } from '@fvc/radio';
+import { useState } from 'react';
+
+export function NotificationSettings({ onChange }) {
+  const [frequency, setFrequency] = useState('daily');
+
+  function handleChange(e) {
+    setFrequency(e.target.value);
+    onChange(e.target.value);
+  }
+
+  return (
+    <Radio.Group block value={frequency} onChange={handleChange}>
+      <Radio value="realtime">Real-time</Radio>
+      <Radio value="daily">Daily digest</Radio>
+      <Radio value="weekly">Weekly summary</Radio>
+      <Radio value="never" disabled>
+        Never (disabled by admin)
+      </Radio>
+    </Radio.Group>
+  );
+}
+```
+
+## Testing
+
+Use `testId` when a stable test selector is needed.
+
+```tsx
+<Radio testId="agree-radio" value="agree">
+  I agree
+</Radio>
+```
+
+```tsx
+screen.getByTestId('agree-radio');
+```
+
+## CSS Customisation
+
+The component reads the following CSS custom properties from the `@fvc` design token palette. These tokens are provided by `@fvc/utils` — no manual `:root` definition is needed unless you want to override the defaults.
+
+| Token         | Used for                           |
+| ------------- | ---------------------------------- |
+| `--blue-500`  | Default border color and dot fill  |
+| `--blue-300`  | Disabled border color and dot fill |
+| `--neutral-0` | Inner circle background            |
+
+To override, set them in your global styles:
+
+```css
+:root {
+  --blue-500: #395ca6;
+  --blue-300: #cdd1e4;
+  --neutral-0: #ffffff;
+}
+```
+
+For the full token list see [`src/Radio.scss`](./src/Radio.scss).
+
+## Development
+
+```bash
+bun run lint
+bun run type-check
+bun run test
+bun run build
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fvc/radio",
-  "version": "1.0.1",
+  "version": "1.0.2-next-ec65dfb844e6183b3d7f417eee613cfe5ecfd997",
   "main": "./dist/lib/index.js",
   "types": "./dist/lib/radio/src/index.d.ts",
   "files": [
@@ -26,6 +26,16 @@
     "type-check": "tsc --noEmit",
     "test": "bun test --preload ../../tests/happydom.ts --preload ../../tests/testing-library.tsx"
   },
+  "keywords": [
+    "react",
+    "react-component",
+    "fvc",
+    "fe-vis-core",
+    "ui",
+    "radio",
+    "design-system",
+    "antd"
+  ],
   "peerDependencies": {
     "react": "^18.0.0",
     "antd": "^5.0.0"