mav-expandable 1.0.0 → 1.0.1

package/README.md

@@ -1,2 +1,141 @@
-//animation on chevron (checkbox)
-//u can use hook inside another component calling this expandable
+# mav-expandable
+
+a lightweight, composable expandable/collapsible component for react
+
+## installation
+
+```bash
+npm install mav-expandable
+```
+
+**peer dependencies** — make sure react 19 is installed in your project
+
+```bash
+npm install react react-dom
+```
+
+install from gh instead of npm
+
+```bash
+npm install github:xmavv/expandable
+```
+
+## requirements
+
+- React 19+
+- [Tailwind CSS](https://tailwindcss.com/)
+
+## usage
+
+### basic example
+
+wrap your content in `Expandable`, use `Expandable.Content` to define what stays visible, and `expand` prop to define what appears when expanded, additionally add `Expandable.Chevron` as the toggle
+
+```tsx
+import { Expandable } from "mav-expandable";
+
+function App() {
+  return (
+    <Expandable>
+      <Expandable.Content expand={<p>this content is shown when expanded</p>}>
+        <div className="flex items-center gap-2">
+          <Expandable.Chevron />
+          <span>click the chevron to expand</span>
+        </div>
+      </Expandable.Content>
+    </Expandable>
+  );
+}
+```
+
+### start expanded
+
+pass `expanded` prop to open the section by default:
+
+```tsx
+<Expandable expanded>
+  <Expandable.Content expand={<p>already visible on mount</p>}>
+    <Expandable.Chevron />
+    <span>Section title</span>
+  </Expandable.Content>
+</Expandable>
+```
+
+### custom toggle with `useExpandable`
+
+you are not limited to `Expandable.Chevron`
+
+use the `useExpandable` hook inside any child component rendered within `Expandable` to build your own toggle
+
+```tsx
+import { Expandable, useExpandable } from "mav-expandable";
+
+function CustomToggle() {
+  const { isExpanded, onExpand } = useExpandable();
+
+  return (
+    <button onClick={() => onExpand((open) => !open)}>
+      {isExpanded ? "Collapse" : "Expand"}
+    </button>
+  );
+}
+
+function App() {
+  return (
+    <Expandable>
+      <Expandable.Content expand={<p>extra details go here</p>}>
+        <CustomToggle />
+        <h3>my section</h3>
+      </Expandable.Content>
+    </Expandable>
+  );
+}
+```
+
+`useExpandable` must be called within an `Expandable` provider , calling it elsewhere throws an error
+
+what is more as said before, you must use this hook inside a child component of `Expandable` caller 
+
+## API
+
+### `<Expandable>`
+
+root provider that holds expand/collapse state
+
+| prop       | type        | default | description            |
+|------------|-------------|---------|------------------------|
+| `children` | `ReactNode` | —       | child components       |
+| `expanded` | `boolean`   | `false` | initial expanded state |
+
+### `<Expandable.Content>`
+
+renders always-visible `children`, and `expand` component when expanded
+
+| prop       ** | type           | default | description                                 |
+|---------------|----------------|---------|---------------------------------------------|
+| `children`    | `ReactNode`    | —       | content shown whether expanded or collapsed |
+| `expand`      | `ReactElement` | —       | content rendered only when expanded         |
+| `...rest`     | `div` props    | —       | spread onto the wrapper `<div>`             |
+
+### `<Expandable.Chevron>`
+
+built-in toggle button with Lucide chevron icons (`ChevronRight` / `ChevronDown`).
+
+### `useExpandable()`
+
+returns:
+
+| property     | type                                | description                              |
+|--------------|-------------------------------------|------------------------------------------|
+| `isExpanded` | `boolean`                           | current expanded state                   |
+| `onExpand`   | `Dispatch<SetStateAction<boolean>>` | setter to expand or collapse the section |
+
+## roadmap
+
+planned improvements:
+
+- **chevron animation** — smooth rotation/transition on the chevron toggle
+
+## license
+
+Apache-2.0

package/dist/index.cjs

@@ -20,7 +20,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  Expandable: () => Expandable
+  Expandable: () => Expandable,
+  useExpandable: () => useExpandable
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -67,5 +68,6 @@ Expandable.Content = ExpandableContent;
 Expandable.Chevron = ExpandableChevron;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  Expandable
+  Expandable,
+  useExpandable
 });

package/dist/index.d.cts

@@ -1,6 +1,10 @@
 import * as react from 'react';
-import { PropsWithChildren, ComponentPropsWithoutRef, ReactElement } from 'react';
+import { PropsWithChildren, ComponentPropsWithoutRef, ReactElement, Dispatch, SetStateAction } from 'react';
 
+declare function useExpandable(): {
+    isExpanded: boolean;
+    onExpand: Dispatch<SetStateAction<boolean>>;
+};
 interface ExpandableProps extends PropsWithChildren {
     expanded?: boolean;
 }
@@ -15,4 +19,4 @@ interface ExpandableContentProps extends PropsWithChildren, ComponentPropsWithou
 declare function ExpandableContent({ children, expand, ...rest }: ExpandableContentProps): react.JSX.Element;
 declare function ExpandableChevron(): react.JSX.Element;
 
-export { Expandable };
+export { Expandable, useExpandable };

package/dist/index.d.ts

@@ -1,6 +1,10 @@
 import * as react from 'react';
-import { PropsWithChildren, ComponentPropsWithoutRef, ReactElement } from 'react';
+import { PropsWithChildren, ComponentPropsWithoutRef, ReactElement, Dispatch, SetStateAction } from 'react';
 
+declare function useExpandable(): {
+    isExpanded: boolean;
+    onExpand: Dispatch<SetStateAction<boolean>>;
+};
 interface ExpandableProps extends PropsWithChildren {
     expanded?: boolean;
 }
@@ -15,4 +19,4 @@ interface ExpandableContentProps extends PropsWithChildren, ComponentPropsWithou
 declare function ExpandableContent({ children, expand, ...rest }: ExpandableContentProps): react.JSX.Element;
 declare function ExpandableChevron(): react.JSX.Element;
 
-export { Expandable };
+export { Expandable, useExpandable };

package/dist/index.js

@@ -44,5 +44,6 @@ function ExpandableChevron() {
 Expandable.Content = ExpandableContent;
 Expandable.Chevron = ExpandableChevron;
 export {
-  Expandable
+  Expandable,
+  useExpandable
 };

package/package.json

@@ -1,6 +1,14 @@
 {
   "name": "mav-expandable",
-  "version": "1.0.0",
+  "version": "1.0.1",
+  "description": "Expandable component for React",
+  "keywords": ["react", "expand", "expandable", "lightweight", "component", "ui"],
+  "homepage": "https://github.com/xmavv/expandable",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xmavv/expandable.git"
+  },
+  "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",