@jouwomgeving/react-cardsort

@jouwomgeving/react-cardsort

Jouw Omgeving React Cardsort component.

Installation

Install this package and its peerDependencies:

$ npm i -S @jouwomgeving/react-cardsort \
    classnames \
    react \
    react-dnd \
    react-dnd-html5-backend \
    react-dnd-touch-backend \
    react-motion

Usage

import Cardsort /* component */, {
  // state reducers
  drop, // drop card in a pile
  pull, // (optional) pull highest card in stack to bottom
  push  // (optional) push lowest card in stack to top
} from '@jouwomgeving/react-cardsort';

This automatically wraps the Cardsort board with react-dnd's DragDropContext. If you already have an existing DragDropContext higher up the component hierarchy (e.g. at route level), you should just import the Board component:

import { 
  Board,
  drop, 
  // ...
},  from '@jouwomgeving/react-cardsort';

Provide the following props with your Cardsort HoC:

• {Object} actions: state manager methods that wrap the component methods with the same name
  • {Function} drop
  • {Function} [pull]
  • {Function} [push]
• {Object} board: state
• {Object} [content] (optional):
  • object of custom content formatters where the key is a pile value and the value a function that receives the card props and returns a React element
• {Function} [formatSourceCaption]: add a caption to the start pile
• {Function} [formatTargetCaption]: format the target pile label
• {boolean} [hasRedo=true]: prevents dragging a dropped card again if false
• {boolean} [isCompact=true]: expands all cards in a pile if false
• next / prev: React elements that trigger the pull/push actions from the UI
• {Object} theme: CSS module selectors
  • .Board
  • .Board-group
  • .Board-compact
  • .Pile
  • .Pile-hover
  • .Card
  • .Card-figure
  • .Card-image
  • .Card-text
  • .Card-valid
  • .Card-wallpaper

State signature

Note: this state can be serialized; for complex card formatting options, see the content property above.

const myState = {
  cards: [
    {
      {string} id, // unique identifier
      {string} pile, // current pile value
      {string} [image], // image URL, takes precedence over 'text'
        // - set as a background image because of cross browser problems with SVG dragging
        // - 'text' is used for the title attribute
      {string} [template=wallpaper], // fills the card with 'image' 
      {string} [template=figure], // like wallpaper, but displays 'text' as a caption 
      {string} [text], // text content 
      {Array} [values], // valid pile values 
    },
    // ...
  ],
  piles: [
    {
      image: "", // optional
      label: "", // optional
      text: "",
      value: "",
    },
    // ...
  ],
  groups: [ // optional
    [0],
    [1, 2],
    // ...
  ],
};

If groups is omitted, it defaults to

[
  [0],
  [/* the remaining card indices */],
]

Run the example (sources and hot-loader)

$ npm install
$ cd ./example
$ npm start

TODO

• it would probably be better to refactor the rendering configuration (template in the card properties and the custom formatter mapping of the component's content prop) as a single formatter
• there's too much data mapping required in consuming components (e.g. JO treatments); if the application state just contains the card data, (almost) everything else should be done by this package

License

UNLICENSED