@fvc/accordion 1.1.1 → 1.1.2-rc.0

package/README.md

@@ -0,0 +1,294 @@
+# @fvc/accordion
+
+`@fvc/accordion` provides FE-VIS styled accordion primitives on top of Ant Design Collapse. It keeps the Ant Design Collapse API familiar while adding the design-system behaviour used across FE-VIS applications: bordered and transparent variants, item-level border and background controls, header alignment options, collapse layout mode, and a disabled state.
+
+## Installation
+
+```bash
+bun add @fvc/accordion
+```
+
+## Peer Dependencies
+
+The package expects these dependencies to be available in the consuming application:
+
+```bash
+bun add react antd
+```
+
+## Import
+
+```tsx
+import { Accordion } from '@fvc/accordion';
+```
+
+## Quick Start
+
+```tsx
+import { Accordion } from '@fvc/accordion';
+
+export function FaqSection() {
+  return (
+    <Accordion
+      defaultActiveKey="1"
+      items={[
+        { key: '1', label: 'What is FE-VIS?', children: 'FE-VIS is a design system for enterprise applications.' },
+        { key: '2', label: 'How do I install it?', children: 'Run bun add @fvc/accordion.' },
+      ]}
+    />
+  );
+}
+```
+
+## Common Usage
+
+### Bordered and Borderless
+
+Bordered is the default. Pass `bordered: false` inside `collapseProps` to remove the outer border.
+
+```tsx
+<Accordion
+  collapseProps={{ bordered: false }}
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+```
+
+### Transparent Background
+
+```tsx
+<Accordion
+  collapseProps={{ transparent: true }}
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+```
+
+### Collapse Layout Mode
+
+Use `collapse` for a flat, continuous layout without rounded corners — suitable for panels embedded inside cards or drawers.
+
+```tsx
+<Accordion
+  collapse
+  items={[
+    { key: '1', label: 'Details', children: 'Content' },
+    { key: '2', label: 'More', children: 'Content' },
+  ]}
+/>
+```
+
+### Header Vertical Alignment
+
+By default the header text and expand icon are top-aligned. Use `center` to flex-center them — useful when the label contains multi-line or rich content.
+
+```tsx
+<Accordion
+  collapseHeaderProps={{ verticalAlign: 'center' }}
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+```
+
+### Multiple Open Panels
+
+```tsx
+<Accordion
+  defaultActiveKey={['1', '2']}
+  items={[
+    { key: '1', label: 'First', children: 'Content' },
+    { key: '2', label: 'Second', children: 'Content' },
+    { key: '3', label: 'Third', children: 'Content' },
+  ]}
+/>
+```
+
+### Disabled State
+
+Disable the entire accordion with the `disabled` prop, or disable individual items via the `items` array.
+
+```tsx
+{/* Entire accordion disabled */}
+<Accordion
+  disabled
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+
+{/* Single item disabled */}
+<Accordion
+  items={[
+    { key: '1', label: 'Available', children: 'Content' },
+    { key: '2', label: 'Unavailable', children: 'Content', disabled: true },
+  ]}
+/>
+```
+
+### Custom Header Content
+
+The `label` field accepts any React node.
+
+```tsx
+<Accordion
+  items={[
+    {
+      key: '1',
+      label: <span style={{ fontWeight: 700 }}>Custom Header</span>,
+      children: 'Content',
+    },
+  ]}
+/>
+```
+
+### Expand Icon Position
+
+```tsx
+<Accordion
+  expandIconPosition="end"
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+```
+
+### Item-level Border and Background
+
+Override border and background for individual items using `collapseItemProps`.
+
+```tsx
+<Accordion
+  collapseItemProps={{ bordered: false, transparent: true }}
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+```
+
+### Nested Components
+
+Use `forceRender` to prevent lazy unmounting when the panel closes — required when the child component holds internal state.
+
+```tsx
+<Accordion
+  items={[
+    {
+      key: '1',
+      label: 'Data table',
+      children: <Table columns={columns} dataSource={data} />,
+      forceRender: true,
+    },
+  ]}
+/>
+```
+
+### Controlled
+
+```tsx
+<Accordion
+  activeKey={activeKey}
+  onChange={(key) => setActiveKey(key)}
+  items={[
+    { key: '1', label: 'Section', children: 'Content' },
+  ]}
+/>
+```
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `collapseProps` | `{ bordered?: boolean; transparent?: boolean }` | Styling for the outer collapse container. |
+| `collapseItemProps` | `{ bordered?: boolean; transparent?: boolean }` | Styling applied to every accordion item. |
+| `collapseHeaderProps` | `{ verticalAlign?: 'default' \| 'center' }` | Header alignment. Defaults to `'default'` (top-aligned). |
+| `disabled` | `boolean` | Disables the entire accordion. |
+| `collapse` | `boolean` | Flat, borderless collapse layout mode. |
+| `testId` | `string` | Maps to `data-testid`. Defaults to `'accordion'`. |
+| *All `CollapseProps`* | — | All Ant Design Collapse props are supported (`items`, `activeKey`, `defaultActiveKey`, `expandIcon`, `expandIconPosition`, `onChange`, etc.). |
+
+> **Deprecated props:** `children` (use `items` instead) and the `onChange` wrapper (use the native `CollapseProps.onChange` directly).
+
+## Consumer Example
+
+```tsx
+import { Accordion } from '@fvc/accordion';
+
+export function ContractDetails({ contract }) {
+  return (
+    <Accordion
+      collapse
+      collapseHeaderProps={{ verticalAlign: 'center' }}
+      defaultActiveKey="general"
+      items={[
+        {
+          key: 'general',
+          label: 'General information',
+          children: <GeneralInfoPanel data={contract.general} />,
+        },
+        {
+          key: 'parties',
+          label: 'Parties',
+          children: <PartiesPanel data={contract.parties} />,
+        },
+        {
+          key: 'attachments',
+          label: 'Attachments',
+          children: <AttachmentsTable data={contract.attachments} />,
+          forceRender: true,
+        },
+      ]}
+    />
+  );
+}
+```
+
+## Testing
+
+Use `testId` when a stable test selector is needed.
+
+```tsx
+<Accordion
+  testId="faq-accordion"
+  items={[
+    { key: '1', label: 'Question', children: 'Answer' },
+  ]}
+/>
+```
+
+```tsx
+screen.getByTestId('faq-accordion');
+```
+
+## CSS Customisation
+
+The component consumes global design tokens. Override them in your application's global styles to retheme the accordion:
+
+```css
+:root {
+  /* Border */
+  --blue-gray-200: #c9d3e0;
+
+  /* Backgrounds */
+  --neutral-0: #ffffff;
+
+  /* Active header text */
+  --link-on-light-bg-color-500: #0057b7;
+
+  /* Content text */
+  --body-text-color-1000: #1a1a1a;
+}
+```
+
+For the full style reference see [`src/Accordion.scss`](./src/Accordion.scss).
+
+## Development
+
+```bash
+bun run lint
+bun run type-check
+bun run test
+bun run build
+```

package/package.json

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