react-essentials

Provides essential structural components like IF, SWITCH and FOROF and helpers such as classList for declarative code.

Install

npm install @enterprize/react-essentials

Usage

If (Structural)

Description

Conditionally renders its children. Accepts an optional else element to be shown. The children can be a factory, so it properly prevents React from parsing the children and causing code that relies on values that can be undefined/null to throw exceptions.

Props

Props marked with * are required.

| Prop | Default | Description | |---|---|---| | expression * | | Expression to conditionally show the children. If true shows the children, otherwise if else is defined, will show its element, otherwise will not render anything. | | else | | The "else" of the "if..else" statement. JSX.Element to show when the expression results in false. |

Example

const [ifExampleShow, setIfExampleShow] = useState<boolean>(true);
const ifExampleOuter = ifExampleShow ? { message: 'Outer dependency works' } : null;

return (
    <div>
        <button
            type="button"
            onClick={() => setIfExampleShow(old => !old)}>
            Toggle show/hide
        </button>
        <br/>

        {/*It is important to use factories as body to prevent React from processing the JSX.*/}
        {/*Doing this allows us to use the "!" TS operator to easier catch logic bugs.*/}
        <If expression={ifExampleShow}>
            {() => <>I am displayed! {ifExampleOuter!.message}</>}
        </If>
        <br/>
        
        {/*The else can also be a factories to prevent React from processing the JSX.*/}
        {/*Otherwise safe navigation must always be used if something might be null/undefined.*/}
        <If
            expression={ifExampleShow}
            else={<>I am the else. {ifExampleOuter?.message}</>}>
            I am displayed!
        </If>
    </div>
);

Switch (Structural)

Description

Use Switch to dynamically show or hide pieces of JSX using a switch..case..default approach. Use SwitchCase as case statement and optionally SwitchCaseDefault for default statement. The children of SwitchCase and SwitchCaseDefault can be a factory, similar to If.

Props

Props marked with * are required.

| Prop | Default | Description | |---|---|---| | expression * | | Expression to evaluate. Can be any value. This value will be compared on each SwitchCase block and if matches will display the assigned content. If none matches and a SwitchCaseDefault is set, will display its contents instead. | | children | | List ofSwitchCaseorSwitchCaseDefault`` child/children. |

Example

const [switchExampleValue, setSwitchExampleValue] = useState('');
const switchExampleOuter = switchExampleValue === 'value_1' ? { message: 'Outer dependency works' } : null;

return (
  <div>
    <select
      onChange={event => setSwitchExampleValue(event.target.value)}>
      <option value="">- None -</option>
      <option value="value_1">Value 1</option>
      <option value="value_2">Value 2</option>
      <option value="value_3">Value 3</option>
    </select>

    <br/>
    <Switch expression={switchExampleValue}>
      {/*It is important to use factories as body to prevent React from processing the JSX.*/}
      {/*Doing this allows us to use the "!" TS operator to easier catch logic bugs.*/}
      <SwitchCase when={'value_1'}>
        {() => <>Case: Value 1 selected {switchExampleOuter!.message}</>}
      </SwitchCase>
      
      {/*The else can also be a factories to prevent React from processing the JSX.*/}
      {/*Otherwise safe navigation must always be used if something might be null/undefined.*/}
      <SwitchCase when={'value_2'}>
        Case: Value 2 selected {switchExampleOuter?.message}
      </SwitchCase>
      
      <SwitchCase when={'value_3'}>Case: Value 3 selected</SwitchCase>
      
      <SwitchCaseDefault>Default: None selected</SwitchCaseDefault>
    </Switch>
  </div>
);

ForOf (Structural)

Description

Use ForOf to iterate over Arrays to generate a list of elements. Can be configured to use different types of keys: index, object property and a computed value.

Props

Props marked with * are required.

| Prop | Default | Description | |---|---|---| | items * | | List of item to iterate. | | children * | | Factory for JSX.Element to be rendered. This function will be called with the iteration object with the ForOfIteration<T> shape. | | keyAttribute | | The attribute to be used as key or a factory (invoked with ForOfIteration<T>) to generate a value. If not set, will cause the React warning about keys. You can return the index provided on the iteration object as a fallback in case no other value is acceptable. | | useIndexAsKey | false | Flag that indicates to use the array index as key. | | useItselfAsKey | false | Flag that indicates to use the iteration "item" as key. Only use this if the item is a primitive. |

Classes and Interfaces

ForOfIteration<T>

• Type params:
  • T - The type of each item in the iteration
• Properties:
  • item: T - The item in the current loop iteration.
  • index: number - The index position of the item.
  • length: number - The length of the array being iterated.
  • isOdd: number - If the index is odd.
  • isEven: number - If the index is even.
  • isFirst: boolean - If the index is the last position of the array.
  • isLast: boolean - If the index is the first position of the array.

Example 1:

const items = ['One', 'Two', 'Tree']; 

return (
  <ForOf
    items={items}
    useItselfAsKey={true}>
    {/*The child of a ForOf must be a factory. It is invoked with the iteration information.*/}
    {iteration => (
      <div>
        {iteration.item} | Index {iteration.index} | Length {iteration.length} | Is
        Odd? {String(iteration.isOdd)} | Is Even {String(iteration.isEven)} | Is
        First? {String(iteration.isFirst)} | Is Last {String(iteration.isLast)}
      </div>
    )}
  </ForOf>
);

Example 2:

const items = [
  { id: 1, value: 'One' },
  { id: 2, value: 'Two' }, 
  { id: 3, value: 'Tree'}
];

return (
  <ForOf
    items={items}
    keyAttribute={'id'}>{/*You can use an object's property name as key*/}
    {iteration => (
      <div>
        {JSON.stringify(iteration.item)} | Index {iteration.index} |
        Length {iteration.length} |
        Is Odd? {String(iteration.isOdd)} | Is Even {String(iteration.isEven)} | Is
        First? {String(iteration.isFirst)} | Is Last {String(iteration.isLast)}
      </div>
    )}
  </ForOf>
);

Example 3:

const items = [
  { id: 1, value: 'One' },
  { id: 1, value: 'Two' }, 
  { id: 3, value: 'Tree'}
];

return (
  <ForOf
    items={items}
    keyAttribute={({item, index}) => item.value ?? index }>{/*You can provide a key factory*/}
    {iteration => (
      <div>
        {JSON.stringify(iteration.item)} | Index {iteration.index} |
        Length {iteration.length} |
        Is Odd? {String(iteration.isOdd)} | Is Even {String(iteration.isEven)} | Is
        First? {String(iteration.isFirst)} | Is Last {String(iteration.isLast)}
      </div>
    )}
  </ForOf>
);

classList (Helper)

Description

Helper function to compile list of classes, give it be a string or a map to apply classes conditionally.

Signature

function classList(...classes: Array<string | ClassMap>): string;

Classes and Interfaces

ClassMap

A hash where each key is the name of the class and the value is a boolean expression that when true indicates to apply the class and false to remove.

Example

const [classListOption, setClassListOption] = useState<string>('');

return (
  <div>
    <select
      onChange={event => setClassListOption(event.target.value)}>
      <option value="">- None -</option>
      <option value="red">Red</option>
      <option value="green">Green</option>
      <option value="blue">Blue</option>
      <option value="global">Global</option>
    </select>

    <br/>
    {/*Each param can be a string (or css module ref) or a map */}
    <p className={classList(
      classes.baseClass,
      {
        [classes.class1]: classListOption === 'red',
        [classes.class2]: classListOption === 'green',
        [classes.class3]: classListOption === 'blue',
        'global-css': classListOption === 'global'
      })}>
      Dynamically colored text using css classes with css modules
    </p>
  </div>
);

Running the Playground

Clone the project and run:

cd lib
pnpm install
pnpm run build

cd ../playground
pnpm run dev

License

MIT © Enterprize Systems