@archoleat/next-accordion 1.0.1 → 1.1.0

package/README.md

@@ -13,7 +13,9 @@
 
 - [Installation](#installation)
 - [Usage](#usage)
+- [Styling](#styling)
 - [Props](#props)
+- [Types](#types)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -60,56 +62,229 @@ const Example = () => <Accordion exclusive items={items} />;
 export { Example };
 ```
 
-## Props
+`Accordion` renders each item as an `<li>` inside a wrapping `<ul>` (with
+`className` applied to that `<ul>`), since a set of panels is semantically
+a list. Browsers apply default list styling (markers, indent) to `<ul>`,
+so reset it yourself — see [Styling](#styling).
 
-### `Accordion`
+### Compound components
 
-- `items` (`AccordionItemData[]`, required): data rendered as a list
-  of `AccordionItem`s. Each entry accepts `id` (`number`), `trigger`,
-  `content`, plus every `AccordionItem` prop below (except `children`,
-  which maps to `content`).
+Instead of `items`, compose `AccordionItem`s directly as children.
+`Accordion` still coordinates the `exclusive` behavior between them:
 
-- `className` (`string`): class applied to the wrapping `div`.
+```tsx
+import { Accordion, AccordionItem } from '@archoleat/next-accordion';
 
-- `exclusive` (`boolean`, default `false`): when `true`, opening one
-  item closes the others.
+const Example = () => (
+  <Accordion exclusive>
+    <AccordionItem trigger="First">
+      <p>First content</p>
+    </AccordionItem>
+    <AccordionItem trigger="Second">
+      <p>Second content</p>
+    </AccordionItem>
+  </Accordion>
+);
 
-### `AccordionItem`
+export { Example };
+```
+
+Give each `AccordionItem` a `key` when the list can be reordered or
+filtered; otherwise `Accordion` falls back to positional indexes to tell
+items apart. `Accordion` accepts either `items` or `children`, not both.
 
-- `trigger` (`ReactNode`, required): content rendered inside
-  the `summary` element.
+### Controlling the open item from outside
 
-- `children` (`ReactNode`, required): content rendered inside
-  the accordion panel.
+In `exclusive` mode, which item is open lives inside `Accordion` by
+default. Pass `openId` (paired with `onOpenIdChange`) to read or drive it
+from outside — the same controlled/uncontrolled split `AccordionItem`
+uses for `open`/`onOpenChange`:
 
-- `defaultOpen` (`boolean`, default `false`): initial expanded state
-  (uncontrolled).
+```tsx
+import { useState } from 'react';
 
-- `open` (`boolean`): expanded state (controlled). Pair
-  with `onOpenChange`.
+import type { AccordionOpenIdType } from '@archoleat/next-accordion';
+import { Accordion } from '@archoleat/next-accordion';
 
-- `onOpenChange` (`(isOpen: boolean) => void`): called when the trigger
-  is clicked.
+const items = [
+  { id: 1, trigger: 'First', content: <p>First content</p> },
+  { id: 2, trigger: 'Second', content: <p>Second content</p> },
+];
+
+const Example = () => {
+  const [openId, setOpenId] = useState<AccordionOpenIdType>(1);
 
-- `disabled` (`boolean`, default `false`): ignores clicks on the trigger.
+  return (
+    <Accordion
+      exclusive
+      items={items}
+      openId={openId}
+      onOpenIdChange={setOpenId}
+    />
+  );
+};
 
-- `duration` (`number`, default `300`): animation duration
-  in milliseconds.
+export { Example };
+```
 
-- `easing` (`string`, default `'ease-out'`): animation easing, passed
-  to the Web Animations API.
+Uncontrolled usage works the same way `defaultOpen` does on `AccordionItem`:
+pass `defaultOpenId` for the initial open item and read subsequent changes
+through `onOpenIdChange`, without taking over the state yourself.
 
-- `icon` (`ReactNode` or `(isOpen: boolean) => ReactNode`): rendered
-  after `trigger`; the function form receives the open state.
+## Styling
 
-- `disableTriggerSelection` (`boolean`, default `false`): prevents text
-  selection on the trigger (e.g. on double-click).
+The library ships no CSS of its own beyond what's needed for the open/close
+animation, so every visual aspect is yours to style. The rendered markup
+gives you the following hooks:
+
+- `Accordion`'s `className` targets the wrapping `<ul>`.
+
+- `AccordionItem`'s `className` (a forwarded native `details` attribute)
+  targets that item's `<details>`.
+
+- `AccordionItem`'s `triggerClassName` and `contentClassName` target
+  the `<summary>` and the panel wrapper `<div>` directly — no need to
+  reach for descendant selectors.
+
+- `trigger` is a `ReactNode`, so wrap it in your own elements to style
+  the label.
+
+- `<details open>` and a disabled item's `data-disabled` are both plain
+  attributes, so Tailwind's `open:` and `data-[disabled]:` variants apply
+  directly — no need for the `icon` function-of-`isOpen` form just to
+  rotate a chevron.
+
+The example below uses [`cn`](https://ui.shadcn.com/docs/installation/manual#add-a-cn-helper),
+the common `clsx` + `tailwind-merge` helper, to combine a shared base
+class with any per-item override:
+
+```tsx
+import { Accordion } from '@archoleat/next-accordion';
+
+import { cn } from './lib/cn';
+
+const ChevronIcon = () => (
+  <svg
+    aria-hidden
+    className="size-4 shrink-0 transition-transform duration-300 group-open:rotate-180"
+    height="16"
+    viewBox="0 0 16 16"
+    width="16"
+  >
+    <path d="M4 6l4 4 4-4" fill="none" stroke="currentColor" strokeWidth="2" />
+  </svg>
+);
+
+const items = [
+  { id: 1, trigger: 'First', content: <p>First content</p> },
+  { id: 2, trigger: 'Second', content: <p>Second content</p> },
+];
+
+const Example = () => (
+  <Accordion
+    className="m-0 flex list-none flex-col gap-2 p-0"
+    exclusive
+    items={items.map((item) => ({
+      ...item,
+      className: 'overflow-hidden rounded-lg border border-slate-200',
+      contentClassName: 'p-4 pt-0',
+      duration: 250,
+      easing: 'ease-in-out',
+      icon: <ChevronIcon />,
+      triggerClassName: cn(
+        'flex cursor-pointer items-center justify-between p-4',
+        'aria-disabled:pointer-events-none aria-disabled:opacity-50',
+      ),
+    }))}
+  />
+);
+
+export { Example };
+```
+
+## Props
+
+<!-- lint disable maximum-line-length -->
+
+### `Accordion`
+
+| Prop        | Type                | Default | Description                                                                                                                                            |
+| ----------- | ------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`     | `AccordionItemDataType[]` | —       | Data rendered as a list of `AccordionItem`s. Each entry accepts `id` (`number`), `trigger`, `content`, plus every `AccordionItem` prop below (except `children`, which maps to `content`). Mutually exclusive with `children`. |
+| `children`  | `ReactNode`         | —       | `AccordionItem` elements composed directly (compound component pattern). Mutually exclusive with `items`.                                            |
+| `className` | `string`            | —       | Class applied to the wrapping `ul`. Each item is rendered inside its own `li`.                                                                        |
+| `exclusive` | `boolean`           | `false` | When `true`, opening one item closes the others.                                                                                                       |
+| `openId`    | `AccordionOpenIdType`   | —       | Id of the currently open item (controlled). Only meaningful when `exclusive` is `true`. Pair with `onOpenIdChange`.                                   |
+| `defaultOpenId` | `AccordionOpenIdType` | `null` | Initial open item id (uncontrolled). Only meaningful when `exclusive` is `true`.                                                                  |
+| `onOpenIdChange` | `(openId: AccordionOpenIdType) => void` | — | Called when the open item changes in `exclusive` mode.                                                                                     |
+
+### `AccordionItem`
+
+| Prop                      | Type                                          | Default        | Description                                                                                   |
+| ------------------------- | ---------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
+| `trigger`                 | `ReactNode`                                    | —              | Content rendered inside the `summary` element. **Required.**                                    |
+| `children`                | `ReactNode`                                    | —              | Content rendered inside the accordion panel. **Required.**                                       |
+| `defaultOpen`              | `boolean`                                      | `false`        | Initial expanded state (uncontrolled).                                                          |
+| `open`                    | `boolean`                                      | —              | Expanded state (controlled). Pair with `onOpenChange`.                                          |
+| `onOpenChange`             | `(isOpen: boolean) => void`                    | —              | Called when the trigger is clicked.                                                             |
+| `disabled`                | `boolean`                                      | `false`        | Ignores clicks on the trigger.                                                                   |
+| `duration`                | `number`                                       | `300`          | Animation duration in milliseconds.                                                              |
+| `easing`                  | `string`                                       | `'ease-in-out'` | Animation easing, passed to the Web Animations API.                                            |
+| `icon`                    | `ReactNode \| (isOpen: boolean) => ReactNode`  | —              | Rendered after `trigger`; the function form receives the open state.                            |
+| `disableTriggerSelection` | `boolean`                                      | `false`        | Prevents text selection on the trigger (e.g. on double-click).                                  |
+| `triggerClassName`        | `string`                                       | —              | Class applied to the `summary` element.                                                         |
+| `contentClassName`        | `string`                                       | —              | Class applied to the panel wrapper `div`.                                                        |
+
+<!-- lint enable maximum-line-length -->
 
 All other native `details` attributes (`id`, `className`, and so on) are
 forwarded to the underlying `<details>` element. The animation is skipped
 in favor of an instant toggle when the user has `prefers-reduced-motion`
 enabled.
 
+## Types
+
+`@archoleat/next-accordion` exports the prop types for both components,
+plus the shape used by `items` and by the open-item id, so you can type
+your own code around them without redeclaring the definitions.
+
+`AccordionOpenIdType` (`number | string | null`) is the type of `openId`,
+`defaultOpenId`, and the argument passed to `onOpenIdChange` — see
+[Controlling the open item from outside](#controlling-the-open-item-from-outside).
+
+Type an `items` array built outside JSX with `AccordionItemDataType`:
+
+```tsx
+import type { AccordionItemDataType } from '@archoleat/next-accordion';
+
+const items: AccordionItemDataType[] = [
+  { id: 1, trigger: 'First', content: <p>First content</p> },
+  { id: 2, trigger: 'Second', content: <p>Second content</p> },
+];
+
+export { items };
+```
+
+Type a wrapper component with `AccordionProps` / `AccordionItemProps`:
+
+```tsx
+import { Accordion, AccordionItem } from '@archoleat/next-accordion';
+import type {
+  AccordionItemProps,
+  AccordionProps,
+} from '@archoleat/next-accordion';
+
+const FaqAccordion = (props: AccordionProps) => (
+  <Accordion className="faq" {...props} />
+);
+
+const FaqItem = (props: AccordionItemProps) => (
+  <AccordionItem duration={300} {...props} />
+);
+
+export { FaqAccordion, FaqItem };
+```
+
 ## Contributing
 
 Please read [**CONTRIBUTING**](https://github.com/archoleat/.github/blob/main/CONTRIBUTING.md)

package/index.d.ts

@@ -1,8 +1,9 @@
 import * as react from 'react';
 import { DetailsHTMLAttributes, ReactNode } from 'react';
 
-type AccordionItemProps = Omit<DetailsHTMLAttributes<HTMLDetailsElement>, 'children' | 'onToggle' | 'open'> & {
+type Props$1 = Omit<DetailsHTMLAttributes<HTMLDetailsElement>, 'children' | 'onToggle' | 'open'> & {
     children: ReactNode;
+    contentClassName?: string;
     defaultOpen?: boolean;
     disabled?: boolean;
     disableTriggerSelection?: boolean;
@@ -12,21 +13,34 @@ type AccordionItemProps = Omit<DetailsHTMLAttributes<HTMLDetailsElement>, 'child
     onOpenChange?: (isOpen: boolean) => void;
     open?: boolean;
     trigger: ReactNode;
+    triggerClassName?: string;
 };
 
-type AccordionItemData = Omit<AccordionItemProps, 'children' | 'content' | 'id'> & {
+type AccordionItemDataType = Omit<Props$1, 'children' | 'content' | 'id'> & {
     content: ReactNode;
     id: number;
 };
-type AccordionProps = {
+type OpenIdType = number | string | null;
+type SharedProps = {
     className?: string;
+    defaultOpenId?: OpenIdType;
     exclusive?: boolean;
-    items: AccordionItemData[];
+    onOpenIdChange?: (openId: OpenIdType) => void;
+    openId?: OpenIdType;
 };
+type ItemsProps = SharedProps & {
+    children?: never;
+    items: AccordionItemDataType[];
+};
+type ChildrenProps = SharedProps & {
+    children: ReactNode;
+    items?: never;
+};
+type Props = ChildrenProps | ItemsProps;
 
-declare const Accordion: (props: AccordionProps) => react.JSX.Element;
+declare const Accordion: (props: Props) => react.JSX.Element;
 
-declare const AccordionItem: (props: AccordionItemProps) => react.JSX.Element;
+declare const AccordionItem: (props: Props$1) => react.JSX.Element;
 
 export { Accordion, AccordionItem };
-export type { AccordionItemData, AccordionItemProps, AccordionProps };
+export type { AccordionItemDataType, Props$1 as AccordionItemProps, OpenIdType as AccordionOpenIdType, Props as AccordionProps };

package/index.js

@@ -1 +1 @@
-import{jsxs as F,jsx as x}from"react/jsx-runtime";import{useState as T,useRef as l,useLayoutEffect as P}from"react";const U=()=>typeof window<"u"&&typeof window.matchMedia=="function"&&window.matchMedia("(prefers-reduced-motion: reduce)").matches,$=300,D="ease-out",b=m=>{const{children:g,defaultOpen:f=!1,disabled:o=!1,disableTriggerSelection:u=!1,duration:i=$,easing:c=D,icon:r,onOpenChange:d,open:a,trigger:H,...I}=m,[p,L]=T(f),h=l(null),R=l(null),v=l(null),t=l(null),N=l(!0),O=a!==void 0,n=O?a:p,M=e=>{if(e.preventDefault(),h.current&&(h.current.open=n),o)return;const s=!n;O||L(s),d?.(s)};return P(()=>{const e=h.current,s=R.current,E=v.current;if(!e||!s||!E)return;if(N.current){N.current=!1,e.open=n;return}if(e.open===n)return;if(t.current?.cancel(),U()||i<=0){e.open=n;return}e.style.overflow="hidden";const S=()=>{e.open=n,e.style.height="",e.style.overflow="",t.current?.cancel(),t.current=null};let y;if(n)e.style.height=`${e.offsetHeight}px`,e.open=!0,y=window.requestAnimationFrame(()=>{const w=`${e.offsetHeight}px`,A=`${s.offsetHeight+E.offsetHeight}px`;t.current=e.animate({height:[w,A]},{duration:i,easing:c,fill:"forwards"}),t.current.addEventListener("finish",S)});else{const w=`${e.offsetHeight}px`,A=`${s.offsetHeight}px`;t.current=e.animate({height:[w,A]},{duration:i,easing:c,fill:"forwards"}),t.current.addEventListener("finish",S)}return()=>{y!==void 0&&window.cancelAnimationFrame(y),t.current?.cancel()}},[n,i,c]),F("details",{...I,"data-disabled":o||void 0,ref:h,children:[F("summary",{"aria-disabled":o,onClick:M,ref:R,style:{cursor:o?void 0:"pointer",listStyle:"none",userSelect:u?"none":void 0,WebkitUserSelect:u?"none":void 0},children:[H,typeof r=="function"?r(n):r]}),x("div",{ref:v,style:{display:"flow-root"},children:g})]})},_=m=>{const{className:g,exclusive:f=!1,items:o}=m,[u,i]=T(null);return x("div",{className:g,children:o.map(({content:c,id:r,onOpenChange:d,...a})=>x(b,{...a,...!f&&d?{onOpenChange:d}:{},...f?{onOpenChange:p=>{i(p?r:null),d?.(p)},open:u===r}:{},children:c},r))})};export{_ as Accordion,b as AccordionItem};
+import{jsxs as U,jsx as l}from"react/jsx-runtime";import{useState as b,useRef as g,useLayoutEffect as $,Children as k,isValidElement as L,cloneElement as D}from"react";const _=300,j="ease-in-out",q=()=>typeof window<"u"&&typeof window.matchMedia=="function"&&window.matchMedia("(prefers-reduced-motion: reduce)").matches,E=o=>{const{children:y,contentClassName:A,defaultOpen:m=!1,disabled:d=!1,disableTriggerSelection:w=!1,duration:a=_,easing:u=j,icon:f,onOpenChange:I,open:n,trigger:s,triggerClassName:t,...N}=o,[h,R]=b(m),c=g(null),x=g(null),v=g(null),i=g(null),P=g(!0),S=n!==void 0,r=S?n:h,M=e=>{if(e.preventDefault(),c.current&&(c.current.open=r),d)return;const p=!r;S||R(p),I?.(p)};return $(()=>{const e=c.current,p=x.current,F=v.current;if(!e||!p||!F)return;if(P.current){P.current=!1,e.open=r;return}if(e.open===r)return;if(i.current?.cancel(),q()||a<=0){e.open=r;return}e.style.overflow="hidden";const T=()=>{e.open=r,e.style.height="",e.style.overflow="",i.current?.cancel(),i.current=null};let O;if(r)e.style.height=`${e.offsetHeight}px`,e.open=!0,O=window.requestAnimationFrame(()=>{const C=`${e.offsetHeight}px`,H=`${p.offsetHeight+F.offsetHeight}px`;i.current=e.animate({height:[C,H]},{duration:a,easing:u,fill:"forwards"}),i.current.addEventListener("finish",T)});else{const C=`${e.offsetHeight}px`,H=`${p.offsetHeight}px`;i.current=e.animate({height:[C,H]},{duration:a,easing:u,fill:"forwards"}),i.current.addEventListener("finish",T)}return()=>{O!==void 0&&window.cancelAnimationFrame(O),i.current?.cancel()}},[r,a,u]),U("details",{...N,"data-disabled":d||void 0,ref:c,children:[U("summary",{"aria-disabled":d,className:t,onClick:M,ref:x,style:{cursor:d?void 0:"pointer",listStyle:"none",userSelect:w?"none":void 0,WebkitUserSelect:w?"none":void 0},children:[s,typeof f=="function"?f(r):f]}),l("div",{className:A,ref:v,style:{display:"flow-root"},children:y})]})},G=o=>{const{className:y,defaultOpenId:A=null,exclusive:m=!1,onOpenIdChange:d}=o,[w,a]=b(A),u=o.openId!==void 0,f=u?o.openId:w,I=n=>{u||a(n),d?.(n)};return o.items?l("ul",{className:y,children:o.items.map(({content:n,id:s,onOpenChange:t,...N})=>l("li",{children:l(E,{...N,...!m&&t?{onOpenChange:t}:{},...m?{onOpenChange:c=>{I(c?s:null),t?.(c)},open:f===s}:{},children:n})},s))}):l("ul",{className:y,children:k.map(o.children,(n,s)=>{const t=L(n)?n.key??s:s;return!L(n)||n.type!==E?l("li",{children:n},t):l("li",{children:D(n,m?{onOpenChange:h=>{I(h?t:null),n.props.onOpenChange?.(h)},open:f===t}:{})},t)})})};export{G as Accordion,E as AccordionItem};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@archoleat/next-accordion",
   "description": "Animated React accordion using details and summary",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "license": "MIT",
   "author": {
     "email": "nikkeyl.me@gmail.com",