Dha-columns NPM

dha-columns

Provides user controls to dynamically change the number of columns that content is laid out in.

Getting Started

Install

Install from npm:

npm i dha-columns

Using with tailwindcss

If you plan on using this module in the pwa-starter, make sure to edit the starter's 'tailwind.config.cjs' file with the following code (to tell tailwind to scan dha-columns for tailwind classes):

module.exports = {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}', './node_modules/dha-columns/**/*.js'],
};

see https://tailwindcss.com/docs/content-configuration#working-with-third-party-libraries for more information.

Quick Usage Notes

Use buttons prop to change between the default tabs or button user input styles
You can use the multiple ClassName props to style using Tailwind. Example, Invisible or Hidden can be used to hide unwanted elements
Use ! with Tailwind styles if your styling isn't applying correctly within Columns
Simple Mode will render an amount of columns appropriate for the window width, with button options for more or less columns
A callback function can be passed in if internal status of Columns is needed for the currently active selection
Use resizeBiasAmount to adjust default settings if using larger or smaller than average content
Automatic reacting to window resizing can be disabled if needed

Columns Component/Module

Columns Props:

children ReactNodes to render in columns
className? ClassName that wraps the whole module
titleClassName? ClassName to style title
controlClassName? ClassName to style control area of buttons
btnClassName? ClassName to style buttons
contentsClassName? ClassName to style column grid
title? string to display as title
noTitle? boolean to disable the display of the title
simpleMode? boolean to enable simpleMode
simpleModeText? string[] Pass in 3 strings to display on the inputs with simpleMode enabled
noControls? boolean to remove the user input controls
buttons? boolean changes column count controls from tabs to buttons
minColumnValueLimit? number the lowest allowed option for columns, default: 1
maxColumnValueLimit? number the highest allowed option for columns, default: 6
defaultCol? number value for initially selected column and number of column options if one isn't explicitly defined
columnOptions? number maximum amount of column selection options provided. Options won't display when set to 1, default: 6
resizeBiasAmount? number bumps the automatically determined values by this amount, negative values accepted
disableResizing? boolean to disable reacting to window resizing
debounceDelay? number of milliseconds to wait before responding to window resizing, default 50ms
customBreakpoints? CustomColumnBreakpoints object with 5 values used as width breakpoints to override the default values that match TailwindCSS default values.
callback? function used as a callback to fetch status of Columns returning a ColumnInfo object containing the current active column, lowest input button option provided that total starts from, total number of options provided

Code samples

Callback Usage Example

Typically the callback prop won't need to be used. It can be useful information if you are trying to make your children content respond to Columns. For instance, you could use simpleMode with 'Small', 'Normal', 'Large' simpleModeText and adjust the size or layout of your content based on the activeColumn.

// Pass this into callback to be able to see the ColumnInfo data returned in payload
const callback = ((payload: ColumnInfo) => { setStatus(payload) })

/**
 * Object returned from callback to fetch info about Columns status
 *
 * activeColumn is the currently selected amount of columns displayed
 * startingColumnOptions lowest input button option provided that total starts from
 * totalColumnOptions total number of options provided
 */
export type ColumnInfo = {
  activeColumn: number;
  startingColumnOption: number;
  totalColumnOptions: number;
};

// Example usage below
import type { ColumnInfo} from 'dha-columns';
import { Columns } from 'dha-columns';
export default function Parent() {
  const [columnsInfo, setColumnsInfo] = useState({});
  // Pass this callback function into Columns callback prop to see status in payload
  const callback = (payload: ColumnInfo) => { setColumnsInfo(payload) }
  return (
    <Columns callback={callback} >{children}</Columns>
    <p>{columnsInfo.activeColumn}</p>
  );
};

Custom Breakpoints Override Object for Responsive Layout Defaults

/**
 * Set the window.innerWidth to change the default column at.
 * Default breakpoints match TailwindCSS Breakpoints.
 * The 6 default ranges can be overridden by providing the 5 options to reference
 * if the window is above or below the given sizes to adjust the breakpoint ranges
 * for each default column count value. A default of 3 will be used when the width
 * falls between the values for 2 and 4, otherwise it will trigger when below the values
 * for 1,2 and if above the values for 4,5,6
 *
 * resizeBiasAmount can be used to shift the amount of columns set for each range
 */
export type CustomColumnBreakpoints = {
  1: number;
  2: number;
  4: number;
  5: number;
  6: number;
};

Home.tsx - Functional Component

import { Columns } from 'dha-columns';

export const Home = () => {
  return (
    <div>
      <Columns buttons simpleMode titleClassName="text-blue-600">
        <div>Content</div>
        <div>to render</div>
        <div>in columns</div>
      </Columns>
    </div>
  );
};

Contribute

Build

The package uses the Typescript compiler (TSC) to build the source code and Rollup to bundle the module into modern JS. To build the project run the following command:

npm run build

Storybook

The package uses Storybook to develop and test components. To start Storybook run the following command:

npm run storybook

Storybook allows you to develop and test components in isolation. It also allows you to view the component documentation and props. Storybook is also useful for testing components in different screen sizes and themes. See more information about Storybook here.

Link peerDependencies

Note: You must tell the local dha-columns to use all peerDependencies from the app you are including the dha-columns into using npm link (the example below is for using the dha-columns in the pwa-starter).

See the dha-columns package.json peerDependencies section.

"peerDependencies": {
  "react": "^X.X.X",
  "react-dom": "^X.X.X"
}

npm link ../pwa-starter/node_modules/react
npm link ../pwa-starter/node_modules/react-dom
Repeat for any remaining peerDependencies that are not listed.

Install Local

You can install the package into your own React application/pwa-starter as a dependency. After you build the dha-columns, install the package into the app using the following commands:

cd pwa-starter
npm i /abs/or/rel/path/to/dha-columns or npm link /abs/or/rel/path/to/dha-columns
- ex. npm i ../dha-columns or npm link ../dha-columns
  - pwa-starter and dha-columns are sibling folders in the example. Adjust this to your project name and directory structure.

Alternative method:

npm run build
npm pack
- Take the newly created .tgz file and copy it into the root folder of the application it will be installed in
npm install dha-columns-1.0.0.tgz
- Use the full name of the file to install from the packed file instead of npm, press tab to auto complete full name

Note about tailwindcss

The dha-columns uses tailwindcss. If you are using the dha-columns in a project that also uses tailwindcss, you may run into some issues with Tailwinds preflight styles. To fix this, It is most common when styling buttons, to fix this just make sure that you add the important attribute to your background styles on button elements by prepending the utility class with !. For example:

<button className="!bg-blue-500 hover:!bg-blue-700 text-white font-bold py-2 px-4 rounded">
  Button
</button>

Troubleshooting

Npm Install Issues

Clearing the package-lock.json and node_modules folder can help ensure that an app or package starts in a clean state.
- rm -rf package-lock.json node_modules

Hook Errors

Hook errors can be caused when a local package is installed into an application where the package devDependencies conflict with the application dependencies by having multiple instances of the same dependency.
You must tell the local dha-columns to use peerDependencies from the app you are including the dha-columns into using npm link (the example below is for using the dha-columns in the pwa-starter).
- Refer to "Link peerDependencies" section above.