@dxc-technology/halstack-react-hal v5.2.1

Halstack React HAL

Halstack React HAL is an npm library of reusable React components. It brings together two different responsibilities:

• Consuming HAL REST APIs implemented following the DXC API Guidelines.

• Rendering these API resources as UI components that are compliant with the DXC UX Guidelines.

We have other libraries that will help you handling these responsibilities individually (Halstack Client / Halstack React). Halstack React HAL uses them under the hood, but it is a higher level abstraction that puts both responsibilities together using the most common association patterns.

For example, collection resources are often associated with tables, and there are a lot of semantics in the standards described by the DXC API guidelines for collections (sorting, paginating...) that could be associated with UI interactions (clicking a table header for sorting, clicking pages for paginating)

Usage

Halstack React HAL is distributed as an npm library. In order to use it in an existing project, you must install it first. You also need to install styled-components and Halstack React CDK, which are peer dependencies.

npm install @dxc-technology/halstack-react-hal styled-components @dxc-technology/halstack-react

The library provides the following components and hooks to be used in your React application:

Components

• HalTable
• HalAutocomplete

Hooks

• useHalResource

HalTable Component

HalTable Props

HalTable Example

import React from "react";
import { HalTable } from "@dxc-technology/halstack-react-hal";

export default () => (
  <HalTable
    collectionUrl={"https://..."}
    columns={[
      {
        header: "Username",
        displayProperty: "username",
        sortProperty: "username"
      },
      {
        header: "Status",
        displayProperty: "status",
      },
      {
        header: "Enabled",
        displayProperty: "enabled",
      },
    ]}
  />
);

HalAutocomplete Component

HalAutocomplete Props

In addition to these component-specific properties you will also have all the properties of the Text Input component that can be found on its site.

HalAutocomplete Example

import React, { useState } from "react";
import { HalAutocomplete } from "@dxc-technology/halstack-react-hal";

export default () => {
  const [autocompleteValue, changeAutocompleteValue] = useState("");
  const onChange = ({ newValue }) => {
    changeAutocompleteValue(newValue);
  };

  return (
    <HalAutocomplete
      collectionUrl="https://..."
      propertyName="full-name"
      label="Full Name"
      onChange={onChange}
      value={autocompleteValue}
    />
  );
};

useHalResource Hook

useHalResource Parameters

useHalResource Return Array

The return value of this hook is an array with the following stateful variables. The property names in this table are just a reference, and you will need to identify them by item position. The table is sorted by item position within the array.

useHalResource Example

import React from "react";
import { useHalResource } from "@dxc-technology/halstack-react-hal";

export default () => {
  const [
    resource,
    requestStatus,
    requestError,
    resourceInteractions,
  ] = useHalResource({
    url: "https://...",
  });

  return <div>{requestStatus}</div>;
};

Contributing

Before opening new issues or pull requests, please refer to CONTRIBUTING.MD.

Development Setup

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

The project is divided in two main folders. One is for the actual library, and the other one is a React application using the library.

Project

Install the dependencies for the library and the example project.

npm install

Library

Contained in the lib folder.

Run the build process updating the bundled files inside the dist folder.

nx build halstack-react-hal #`npx nx build halstack-react-hal` if nx is not recognized as a command.

Example Application

Contained in the app folder.

Start the application.

nx serve app #`npx nx serve app` if nx is not recognized as a command.

Now, anytime you make a change to the library or the app, nx will live-reload your local dev server so you can iterate on your component in real-time.