# @american-heart/aui

#### A unified experience, across all sites.

As a non-profit organization, American Heart Association has been at the forefront of promoting cardiovascular health and reducing the risks of heart disease and stroke for nearly 100 years.

One of the key strengths of AHA is its UI components, which provide a powerful and flexible set of tools for building customized workflows.

AHA's UI components are designed to be modular and easy to use, allowing users to quickly build and customize their own views of project data. These components include everythingÊfrom **Dropdowns** and **Buttons** to custom fields and filters, making it easy to organize and analyze the data in a way that works best for the internal teams.

In addition to its powerful customization options, AHA's UI components are also designed with usability and accessibility in mind, making it easy for users to navigate the website and find the information they are looking for.

The tool is fully responsive, meaning that it works equally well on desktop and mobile devices, and it provides a range of accessibility features to ensure that it is usable for everyone, regardless of their abilities.

Overall, AHA's UI components provide a robust and flexible set of tools for managing projects and collaborating with team members.

## Features

* Highly optimized and accessibility compliance components built with [Stencil](https://stenciljs.com/)
* [AUI V2.0](https://www.aui-dev-v2.heartblr.org/) is an App Development Framework that makes it easy to build top quality Native and Progressive Web Apps with web technologies.
* The AUI package contains the Web Components that make up the reusable UI building blocks for any application. These components are designed to be used in traditional frontend view libraries/frameworks (such as [Stencil](https://stenciljs.com/), React, Angular, or Next), or on their own through traditional JavaScript in the browser.



## How to use

### Vanilla HTML

Easiest way to start using @american-heart/aui components is by adding a script tag to the CDN:

```html
<script type="module" src="https://cdn.jsdelivr.net/npm/@american-heart/aui/dist/american-heart-aui/american-heart-aui.esm.js"></script>
```

Any AUI component added to the webpage will automatically load. This includes writing the component tag directly in HTML, or using JavaScript such as `document.createElement('aui-button')`.


AUI also has packages that make it easier to integrate AUI into a framework's traditional ecosystem and patterns. (However, at the lowest-level framework bindings are still just using Web Components).

### React JS


```typescript
// Import this in the index.tsx file or the parent file as per the project
import { defineCustomElements } from '@american-heart/aui/loader';


//  Defines all the web component to the global window object
defineCustomElements(window);
```

The `defineCustomElements` function will automatically define the component as well as any child components that may be required.

One additional thing which we need to do while using react with typescript is to extend the HTML Elements with custom web components created with stencil.

```typescript
// store in registerWebComponents.js or any file name;
import type { JSX as LocalJSX } from '@american-heart/aui/loader';
import type { DetailedHTMLProps, HTMLAttributes } from 'react';

type StencilProps<T> = {
  [P in keyof T]?: Omit<T[P], 'ref'> | HTMLAttributes<T>;
};

type ReactProps<T> = {
  [P in keyof T]?: DetailedHTMLProps<HTMLAttributes<T[P]>, T[P]>;
};

type StencilToReact<
  T = LocalJSX.IntrinsicElements,
  U = HTMLElementTagNameMap
> = StencilProps<T> & ReactProps<U>;

declare global {
  export namespace JSX {
    interface IntrinsicElements extends StencilToReact {}
  }
}
```

Store the above code in a seperate file and then import it in the main parent file example - `index.tsx`

```typescript
// registerWebComponents.ts file contains the above code
import './registerWebComponents.ts';
```

```typescript
// Example how to use any AUI component

import React from "react";

function App() {
  return (
    <aui-button variant="secondary">Click Me<aui-button>
  );
}

export default App;
```


### AUI web components doesn't supports `objects` and `arrays` as props to the components. Instead, it should be passed as `JSON strings` to those properties.


```typescript
// Example for how to pass properties with JSON strings
import React from "react";
const values = [
  { title: 'Example 1', url: '/#' },
  {
    title: 'Example 2',
    url: '/path2',
  },
];
function App() {
  return (
    <aui-breadcrumb previouspages={JSON.stringify(values)} currentpage="Current"/>
  );
}

export default App;
```


### NextJS


```typescript
// Import this in the _app.tsx file or the parent file as per the project
import { defineCustomElements } from '@american-heart/aui/loader';


//  Defines all the web component to the global window object inside the useEffect
useEffect(() => {
  defineCustomElements(window);
},[])
```

The `defineCustomElements` function will automatically define the component as well as any child components that may be required.

One additional thing which we need to do while using nextjs with typescript is to extend the HTML Elements with custom web components created with stencil.

```typescript
// store in registerWebComponents.js or any file name
import type { JSX as LocalJSX } from '@american-heart/aui/loader';
import type { DetailedHTMLProps, HTMLAttributes } from 'react';

type StencilProps<T> = {
  [P in keyof T]?: Omit<T[P], 'ref'> | HTMLAttributes<T>;
};

type ReactProps<T> = {
  [P in keyof T]?: DetailedHTMLProps<HTMLAttributes<T[P]>, T[P]>;
};

type StencilToReact<
  T = LocalJSX.IntrinsicElements,
  U = HTMLElementTagNameMap
> = StencilProps<T> & ReactProps<U>;

declare global {
  export namespace JSX {
    interface IntrinsicElements extends StencilToReact {}
  }
}
```

Store the above code in a seperate file and then import it in the main parent file example - `_app.tsx`

```typescript
// registerWebComponents.ts file contains the above code
import './registerWebComponents.ts';
```

Example how to use any AUI component

```typescript
import React from "react";

function App() {
  return (
    <aui-alert type="info">
      <div>
        <h1>This is the alert heading<h1>
        <h2>This is the alert subheading<h2>
      <div>
    <aui-alert/>
  );
}

export default App;
```

### AUI web components doesn't supports `objects` and `arrays` as props to the components. Instead, it should be passed as `JSON strings` to those properties.


```typescript
// Example for how to pass properties with JSON strings
import React from "react";
const values = [
  { label: 'Active', value: '1' },
  { label: 'Not Active', value: '2' },
];
function App() {
  return (
    <aui-dropdown options={JSON.stringify(values)} dropdownid="primary" label="Primary"/>
  );
}

export default App;
```

#### Components having objects or arrays as properties/props
- aui-breadcrumb
  - previouspages [Object](https://www.aui-dev-v2.heartblr.org/?path=/docs/components-breadcrumb--breadcrumb-primary)
- aui-dropdown
  - options [Array](https://www.aui-dev-v2.heartblr.org/?path=/docs/components-form-elements-dropdown--dropdown-primary)
  - value [Object](https://www.aui-dev-v2.heartblr.org/?path=/docs/components-form-elements-dropdown--dropdown-primary)
- aui-radio
  - options [Array](https://www.aui-dev-v2.heartblr.org/?path=/docs/components-form-elements-radiobuttons--primary)  


### Angular JS


```typescript
// Import this in the main.ts file or the parent file as per the project
import { defineCustomElements } from '@american-heart/aui/loader';


//  Defines all the web component to the global window object
  defineCustomElements(window);
```

The `defineCustomElements` function will automatically define the component as well as any child components that may be required.

Defines a schema that allows an `NgModule` to contain the following:

Non-Angular elements named with dash case (-).
Element properties named with dash case (-). Dash case is the naming convention for custom elements.

```typescript
import { BrowserModule } from '@angular/platform-browser';
import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule],
  providers: [],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}
```


## Related

- [Stencil](https://stenciljs.com/)
- [General Accessbility](https://company-106155.frontify.com/d/k7zQoGxTtXh1/style-guide#/accessibility/1-general-accessibility)
- [Frontend Checklist](https://company-106155.frontify.com/d/k7zQoGxTtXh1/style-guide#/style-guide/front-end-checklist-1533840788)