# @biomedit/next-widgets

> Commonly used widgets, building blocks for forms, table components and utilities for Next.js.

Latest version **19.2.3** (published 2024-11-25) · LGPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install @biomedit/next-widgets
pnpm add @biomedit/next-widgets
yarn add @biomedit/next-widgets
bun add @biomedit/next-widgets
```

## Health

**Score 40/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 19.2.3 |
| Published | 2024-11-25 |
| First published | 2021-06-18 |
| Weekly downloads | 0 |
| License | LGPL-3.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >= 18.0.0 |
| Dependencies | 16 |
| Unpacked size | 843 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | biomedit |

## Links

- npm: https://www.npmjs.com/package/@biomedit/next-widgets
- Repository: https://gitlab.com/biomedit/next-widgets
- Homepage: https://gitlab.com/biomedit/next-widgets#readme
- Issues: https://gitlab.com/biomedit/next-widgets/issues
- npm.io page: https://npm.io/package/@biomedit/next-widgets

## Dependencies (16)

- [clsx](https://npm.io/package/clsx.md) ^2.1.0
- [dayjs](https://npm.io/package/dayjs.md) ^1.11.10
- [immer](https://npm.io/package/immer.md) ^10.0.4
- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [marked](https://npm.io/package/marked.md) ^15.0.0
- [isemail](https://npm.io/package/isemail.md) ^3.2.0
- [deepmerge](https://npm.io/package/deepmerge.md) ^4.3.1
- [js-cookie](https://npm.io/package/js-cookie.md) ^3.0.5
- [short-uuid](https://npm.io/package/short-uuid.md) ^5.2.0
- [setimmediate](https://npm.io/package/setimmediate.md) ^1.0.5
- [timezone-mock](https://npm.io/package/timezone-mock.md) ^1.3.6
- [fast-deep-equal](https://npm.io/package/fast-deep-equal.md) ^3.1.3
- [http-status-codes](https://npm.io/package/http-status-codes.md) ^2.3.0
- [redux-saga-tester](https://npm.io/package/redux-saga-tester.md) ^1.0.874
- [use-deep-compare-effect](https://npm.io/package/use-deep-compare-effect.md) ^1.8.1
- [awesome-debounce-promise](https://npm.io/package/awesome-debounce-promise.md) ^2.1.0

## Recent versions

- 19.2.3 (latest) — 2024-11-25
- 19.2.2 — 2024-11-04
- 19.2.1 — 2024-10-22
- 19.2.0 — 2024-10-17
- 19.1.0 — 2024-10-08
- 19.0.0 — 2024-10-04
- 18.4.1 — 2024-09-10
- 18.4.0 — 2024-09-10
- 18.3.0 — 2024-09-06
- 18.2.1 — 2024-07-22
- 18.2.0 — 2024-06-26
- 18.1.2 — 2024-06-10
- 18.1.1 — 2024-05-17
- 18.1.0 — 2024-05-15
- 18.0.5 — 2024-04-29
- … 129 more at https://npm.io/package/@biomedit/next-widgets/versions

## README

<h1 align="center">next-widgets</h1>

<p align="center">Commonly used widgets, building blocks for forms, table components and utilities for Next.js.</p>

<p align="center">
    <a href="https://www.npmjs.com/package/@biomedit/next-widgets"><img src="https://img.shields.io/npm/v/@biomedit/next-widgets/latest.svg?style=flat-square" alt="NPM Version" /></a>
    <a href="https://www.npmjs.com/package/@biomedit/next-widgets"><img src="https://img.shields.io/npm/dm/@biomedit/next-widgets.svg?style=flat-square" alt="NPM Downloads" /></a>
    <a href="https://master--6169af96fe171f004a2c1224.chromatic.com"><img src="https://img.shields.io/badge/docs-storybook-blue?style=flat-square" alt="Storybook Documentation" /></a>
    <a href="https://gitlab.com/biomedit/next-widgets/-/pipelines"><img src="https://img.shields.io/gitlab/pipeline/biomedit/next-widgets/main?style=flat-square" alt="GitLab CI Build Status" /></a>
    <a href="https://gitlab.com/biomedit/next-widgets/-/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@biomedit/next-widgets?style=flat-square" alt="GitLab license" /></a>
    <a href="http://commitizen.github.io/cz-cli/"><img src="https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=flat-square" alt="Commitizen friendly" /></a>
</p>

## Installation

This project follows the [semantic versioning
specification](https://semver.org/) for its releases.

To install, run the following command:

```bash
npm install @biomedit/next-widgets
```

## Usage

### Logging

To get logs from `next-widgets`, use the `onLog` and `offLog` methods to
register and unregister a listener, respectively. For example, to log everything
to the console, add the following to `_app.tsx`:

```ts
import { LogListener, onLog, offLog } from '@biomedit/next-widgets';

useEffect(() => {
  const listener: LogListener = (data) => {
    console.log(data);
  };
  onLog(listener);
  return () => {
    offLog(listener);
  };
}, []);
```

To use the logger from `next-widgets` in your application, pass a namespace to
the `logger` function to get a logger. Then, you can call the log levels as
methods on that logger:

```ts
import { logger } from '@biomedit/next-widgets';

const log = logger('Example');

log.silly(message);
log.verbose(message);
log.info(message);
log.http(message);
log.warn(message);
log.error(message);
```

### ToastBar

To use the `ToastBar`, first add the component to your `_app.tsx`:

```tsx
function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <ToastBar
        subjectPrefix={'subjectPrefix'}
        contactEmail={'chuck@norris.gov'}
      />
      <Component {...pageProps} />
    </>
  );
}
```

Then, add the `toast` reducer to your reducers in `redux`:

```ts
import { toast } from '@biomedit/next-widgets';

export const reducers = combineReducers({
  ...,
  toast,
});
```

Finally, add a typing declaration file with the following content (for example
`next-widgets.d.ts`), replacing
`RootState` with the type of your redux store's state:

```ts
import 'next-widgets';
import { RootState } from './store';
declare module 'next-widgets' {
  // eslint-disable-next-line @typescript-eslint/no-empty-interface
  export interface DefaultRootState extends RootState {}
}
```

### Customizing

The unique validation that is performed in `LabelledField` when the `unique`
property is specified performs debouncing, which is set to **750 ms** by
default. To change the debouncing time, set the environment variable
`NEXT_PUBLIC_UNIQUE_VALIDATION_DEBOUNCE` to the desired amount of milliseconds.

### Styling

When importing a component from this library, if the component exposes the `sx`
property, be aware that using it completely replaces the internal `sx` property
of the component (if present).

Therefore, stick to the following guidelines:

- To extend the component's styling, while preserving the component's internal
  `sx` property, use the [styled API](https://mui.com/system/styled/#api).
- To completely replace the internal `sx` property of the component, use the
  exposed `sx` property.

## Generating Typing Documentation

To generate typing documentation, clone this repository locally, then run the
following commands:

```bash
npm install
npm run doc
```

Finally, open the `build/docs/index.html` file in your browser.

## Development

### Requirements

- NodeJS == 22

### Setting up development environment

1. Clone this repository locally
2. Run `npm install`

### Running tests

Run: `npm test`

This will do the following:

- Build the source files
- Run ESLint (check only)
- Run prettier (check only)
- Run unit tests using jest

### Running tests in watch mode

Run: `npm run watch`

### Automatically fixing eslint and reformat using prettier

To automatically fix errors by eslint (limited to those that can be fixed
automatically) and have the code get reformatted using prettier, run the
following command:

```bash
npm run fix
```

### Trying out changes locally

There are two ways to try out your changes locally, you can either use
Storybook, or you can build and publish an npm package to a local registry, so
you can install it as a dependency in a different NodeJS application.

Storybook is recommended, as it's the fastest way to try out changes locally.

In some special cases it might be necessary to publish a package, but this will
require you to build the source files every time you make a change.

#### Storybook

Run storybook using the following command:

```bash
npm run storybook
```

After building the storybook, it will automatically open it in your browser.

If the component you want to try out doesn't exist yet, you need to create a
`.stories.tsx` file in the same folder as the component.

After making changes to either the stories or the source files, storybook will
automatically rebuild and refresh upon saving, so there is no need to refresh
the page or rerun the command.

#### Publishing a package locally

##### First time setup

Run the following commands to install and run a local npm registry:

```bash
npm install -g verdaccio
verdaccio
```

##### Publishing to the local npm registry

1. Make sure the local npm registry is running and the current registry of npm
   is set to your local one by running `npm run verdaccio:up`
2. Change the version number in `package.json` to one that doesn't exist yet.
3. Run `npm run build` (or `npm run watch:build` if you plan on making further
   changes)
4. Run `npm publish`
5. In your application, change the version of `@biomedit/next-widgets` in your
   `package.json` which you defined in a previous step and run `npm i`
6. Change back to the original npm registry by running `npm run verdaccio:down`.

Make sure you don't commit your `package-lock.json` with your npm registry set
to your local registry, always make sure to change back to the original npm
registry first and run `npm i`. It's always a good idea to search the
`package-lock.json` for `localhost:4873` to make sure you don't accidentally
include anything from a local registry.

## Release

To release a new version of the package:

```bash
git checkout main
git pull
./bumpversion.sh
git push --follow-tags origin main
```

---
_Source: https://npm.io/package/@biomedit/next-widgets · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._