diff --git a/README.md b/README.md index 41107d4..a7f7e4f 100644 --- a/README.md +++ b/README.md @@ -78,15 +78,21 @@ export const GALLERY_ITEMS = [ // your-gallery.js import { GALLERY_ITEMS } from "./some-data" -import { Gallery, GalleryMain, GalleryNav, GalleryPagination, GalleryItem } from "@wethegit/react-gallery" +import { Gallery, + GalleryMain, + GalleryNav, + GalleryPagination, + GalleryPaginationItem, + GalleryItem, +} from "@wethegit/react-gallery" const YourGallery = () => { return ( ( - + renderGalleryItem={({ item, index, active }) => ( + {item.alt} )} @@ -96,8 +102,10 @@ const YourGallery = () => { ➡️ ( - {i + 1} + renderPaginationItem={({ item, index, active }) => ( + + {i + 1} + )} /> @@ -110,11 +118,11 @@ export default YourGallery The first step is to give your data to the `` component via the `items` prop. At the very least, `items` is expected to be an Array. From there, you're free to arrange the child components this package provides as you see fit. Below is a brief description of each of the child components' usage. For a detailed breakdown of this component, jump ahead to the [Gallery](#gallery) section. -`` is the primary gallery view where your item data is rendered. It receives a render prop, `renderGalleryItem`, which exposes a few arguments you can use in the JSX you return: `item`, `i`, `activeIndex`, and `active` and expects a `` to be returned. For a detailed breakdown of this component, jump ahead to the [GalleryMain](#gallerymain) section. +`` is the primary gallery view where your item data is rendered. It receives a render prop, `renderGalleryItem`, which exposes a few arguments you can use in the JSX you return: `item`, `index`, `activeIndex`, and `active` and expects a `` to be returned. For a detailed breakdown of this component, jump ahead to the [GalleryMain](#gallerymain) section. We're using the `` component to define our "next" and "previous" buttons. These components receive a `direction` prop, which expects either a `1` or a `0`, and corresponds to the direction the gallery should move in when the button in question is clicked (where `0` maps to "previous", and `1` maps to "next"). For a detailed breakdown of this component, see the [GalleryNav](#gallerynav) section. -We're also using the `` component here. If you're not familiar, "pagination" refers to what is often rendered as a set of "dots" below a gallery — but this can be _anything_ (thumbnails, icons, and so on). This component receives the render prop, `renderPaginationItem`, which exposes a few arguments you can use in the JSX you return: `item`, `i`, `activeIndex`, and `active`. For a detailed breakdown of this component, jump ahead to the [GalleryPagination](#gallerypagination) section. +We're also using the `` and `GalleryPaginationItem` components here. If you're not familiar, "pagination" refers to what is often rendered as a set of "dots" below a gallery — but this can be _anything_ (thumbnails, icons, and so on). This component receives the render prop, `renderPaginationItem`, which exposes a few arguments you can use in the JSX you return: `item`, `i`, `activeIndex`, and `active`. The easiest way to link up you pagination is to use the `` component, as shown in the example above. For a detailed breakdown of this component, jump ahead to the [GalleryPagination](#gallerypagination) section. ## Custom layouts @@ -188,7 +196,7 @@ This render prop expects a `` to be returned, and receives a handfu | ----------- | ------- | -------------------------------------------------------------------------------------------------------------- | | active | Boolean | Whether the current item being iterated over is the active item. | | activeIndex | Number | The index of the currently active gallery item. | -| i | Number | The index of the current item being iterated over. | +| index | Number | The index of the current item being iterated over. | | item | Any | The current item being iterated over, as defined by the Array fed to the `` component's `items` prop. | ### <GalleryItem> @@ -237,15 +245,62 @@ Renders an unordered list (`
    `) of pagination items. Must be used within a `< #### `renderPaginationItem` -This render prop wraps its return value in a list item (`
  • `) and a `
) diff --git a/src/lib/components/gallery-pagination-item.jsx b/src/lib/components/gallery-pagination-item.jsx index a34397b..7f361ca 100644 --- a/src/lib/components/gallery-pagination-item.jsx +++ b/src/lib/components/gallery-pagination-item.jsx @@ -11,19 +11,28 @@ export const GalleryPaginationItem = ({ index, active, className, + buttonClassName, + buttonProps, children, + onClick, ...props }) => { const { goToIndex, itemNodes } = useGallery() - const handleClick = (i) => { + const handleClick = (i) => (event) => { goToIndex(i) itemNodes.current[i].focus({ preventScroll: true }) + onClick?.({ event, index }) } return (
  • -
    • @@ -34,5 +43,8 @@ GalleryPaginationItem.propTypes = { index: PropTypes.number.isRequired, active: PropTypes.bool.isRequired, className: PropTypes.string, + buttonClassName: PropTypes.string, + buttonProps: PropTypes.object, children: PropTypes.node, + onClick: PropTypes.func, } diff --git a/src/lib/components/gallery-pagination.jsx b/src/lib/components/gallery-pagination.jsx index 14475ff..7f9f76d 100644 --- a/src/lib/components/gallery-pagination.jsx +++ b/src/lib/components/gallery-pagination.jsx @@ -4,24 +4,43 @@ import PropTypes from "prop-types" // hooks import { useGallery } from "../hooks/use-gallery" -// components -import { GalleryPaginationItem } from "./gallery-pagination-item" - // utils import classnames from "../utils/classnames" +/*** + * + * Pagination Item component callback + * --- + * @callback renderPaginationItem - Expects a component of GalleryPaginationItem + * @param {number} index - The index of the current pagination item being iterated over. + * @param {boolean} active - Whether the current pagination item being iterated over corresponds to the active gallery item. + * @param {number} activeIndex - The index of the currently active gallery item. + * @param {any} item - The current pagination item being iterated over, as defined by the Array fed to the `` component's `items` prop. + */ + +/** + * Pagination Component + * --- + * @param {object} props + * @param {renderPaginationItem} props.renderPaginationItem - The component to be rendered. This expects the main wrapper to be a GalleryPaginationItem component + * @param {string} [props.className] - Pass classname to
      element + * @example + * ( + * + * {index + 1} + * + * )} + * /> + */ export const GalleryPagination = ({ renderPaginationItem, className, ...props }) => { const { activeIndex, galleryItems } = useGallery() return (
        - {galleryItems.map((item, i) => { - const active = activeIndex === i - return ( - - {renderPaginationItem({ item, i, activeIndex, active })} - - ) + {galleryItems.map((item, index) => { + const active = activeIndex === index + return renderPaginationItem({ index, active, activeIndex, item }) })}
      ) diff --git a/src/lib/index.js b/src/lib/index.js index 7110467..031ac1b 100644 --- a/src/lib/index.js +++ b/src/lib/index.js @@ -1,6 +1,7 @@ export { Gallery } from "./components/gallery-context" export { GalleryMain } from "./components/gallery-main" export { GalleryPagination } from "./components/gallery-pagination" +export { GalleryPaginationItem } from "./components/gallery-pagination-item" export { GalleryNav } from "./components/gallery-nav" export { GalleryItem } from "./components/gallery-item" export { useGallery } from "./hooks/use-gallery" diff --git a/src/main.jsx b/src/main.jsx index 8f37bc0..b9431c8 100644 --- a/src/main.jsx +++ b/src/main.jsx @@ -6,6 +6,7 @@ import { GalleryItem, GalleryNav, GalleryPagination, + GalleryPaginationItem, useGallery, } from "./lib" @@ -48,11 +49,16 @@ function GalleryDescription() { } function App() { + // Example of custom onClick handler + const handlePaginationItemClick = ({ event, index }) => { + console.log(event, index) + } + return ( ( - + renderGalleryItem={({ item, index, active }) => ( + {item.alt} )} @@ -61,7 +67,18 @@ function App() { ⬅️ ➡️ - {i + 1}} /> + ( + + {index + 1} + + )} + /> )