@alessiofrittoli/react-components v0.2.0

React Components 🧩

TypeScript React Components

Table of Contents

• Getting started
• API Reference
  • High Order Components
    • <InView />
    • <Stack />
    • WithGenerator
• Development
  • Install depenendencies
  • Build the source code
  • ESLint
  • Jest
• Contributing
• Security
• Credits

Getting started

Run the following command to start using react-components in your projects:

npm i @alessiofrittoli/react-components

or using pnpm

pnpm i @alessiofrittoli/react-components

API Reference

Components

High Order Components

<InView />

A React higher-order component that renders its children based on their visibility within the viewport.

This Component uses useInView hook under-the-hood so it may worth to take a look at the useInView API Reference for a deep understanding on how it actually works.

Basic usage

'use client'

// ClientComponent.tsx
const ClientComponent: React.FC = () => {

  useEffect( () => {
    console.log( 'ClientComponent entered viewport.' )
    return () => {
      console.log( 'ClientComponent exited viewport.' )
    }
  }, [] )

  return (
    <div>ClientComponent</div>
  )

}

// ServerComponent.tsx
const ServerComponent: React.FC = () => (
  <InView>
    <ClientComponent />
  </InView>
)

Server-Render initial value

By default <InView /> mounts/unmounts its children based on intersection within the viewport. If your component renders important SEO informations, mounting/unmounting yout component only when is in the viewport may not the best option since the rendered content won't be part of the server-rendered web page.

To ensure your content is delivered in the server-rendered web page, you may want to set the initial prop to true.

const Component: React.FC = () => (
  <InView initial>
    <h1>I&apos;ll be in the source page!</h1>
  </InView>
)

Alternatively you can set the mountInView prop to false, which prevents the mount/unmount life-cycle, and then pass a callable function as children.

By passing a callable function as children you'll earn access to the useInView result data.

const Component: React.FC = () => (
  <InView mountInView={ false }>
    { ( { inView, enabled, isExiting, setEnabled, setInView, observer } ) => (
      <h1 style={ {
        opacity     : inView ? 1 : 0,
        transition  : 'opacity 1s ease',
      } }>I&apos;ll be in the source page!</h1>
    ) }
  </InView>
)

<Stack />

Easily stack components avoiding creating a big Component stack pyramid.

Basic usage

import { Stack } from '@alessiofrittoli/react-components'

export const ProviderExample: React.FC<React.PropsWithChildren> = ( { children } ) => {
  // ...
  return (
    <div>{ children }</div>
  )
}

export const AppProviders: React.FC<React.PropsWithChildren> = ( { children } ) => (
  <Stack components={ [
    ProviderExample,
    AppProvider1,
    AppProvider2,
    AppProvider3,
    // ...
  ] }>{ children }</Stack>
)

Component with props

Use StackComponent<typeof ComponentReference> to add type safety to the passed props.

import { Stack, type StackComponent } from '@alessiofrittoli/react-components'

type ProviderExampleProps = React.PropsWithChildren<{
  /** Example required prop */
  className: string
}>


export const ProviderExample: React.FC<React.PropsWithChildren> = (
  { className, children }
) => (
  <div className={ className }>{ children }</div>
)

export const AppProviders: React.FC<React.PropsWithChildren> = ( { children } ) => (
  <Stack components={ [
    [ ProviderExample, { className: 'some-class-name' } ] as StackComponent<typeof ProviderExample>,
    AppProvider1,
    AppProvider2,
    AppProvider3,
    // ...
  ] }>{ children }</Stack>
)

WithGenerator

Transform your generator function into a React.js Component.

Stream Content from a React Component

import { WithGenerator } from '@alessiofrittoli/react-components'

interface StepProps
{
  someProp: string
}

export const Steps = WithGenerator<StepProps>(
  async function* ( { someProp } )
  {
    let i = 0

    yield <h1>Step { ++i } - { someProp }</h1>

    // simulate an async task by awaiting a void Promise
    await new Promise<void>( resolve => setTimeout( resolve, 2000 ) )

    yield <h1>Step { ++i } - { someProp }</h1>

    // simulate an async task by awaiting a void Promise
    await new Promise<void>( resolve => setTimeout( resolve, 2000 ) )

    return <h1>Step { ++i } - { someProp } - Stream finished</h1>
  }
)

Development

Install depenendencies

npm install

or using pnpm

pnpm i

Build the source code

Run the following command to test and build code for distribution.

pnpm build

ESLint

warnings / errors check.

pnpm lint

Jest

Run all the defined test suites by running the following:

# Run tests and watch file changes.
pnpm test:watch

# Run tests in a CI environment.
pnpm test:ci

• See package.json file scripts for more info.

Run tests with coverage.

An HTTP server is then started to serve coverage files from ./coverage folder.

⚠️ You may see a blank page the first time you run this command. Simply refresh the browser to see the updates.

test:coverage:serve

Contributing

Contributions are truly welcome!

Please refer to the Contributing Doc for more information on how to start contributing to this project.

Help keep this project up to date with GitHub Sponsor.

Security

If you believe you have found a security vulnerability, we encourage you to responsibly disclose this and NOT open a public issue. We will investigate all legitimate reports. Email security@alessiofrittoli.it to disclose any security vulnerabilities.

Made with ☕