@luscii-healthtech/web-ui 20.2.0 → 20.3.0

package/README.md

@@ -4,18 +4,12 @@ The `web-ui` repository contains the UI components for Luscii's frontend project
 
 ## Table of contents
 
-- 📦 [Installation](#installation)
-- 💻 [Running locally](#running-locally)
-- 🏭 [Testing your production build](#testing-your-production-build)
+- 🚀 [Getting started](#getting-started)
+  - 📖 [Fonts](#fonts)
+- 📦 [How to use](#how-to-use)
 - 🤝 [Contributing](#contributing)
-  - 📖 [Documentation](#documentation)
-  - 🌈 [Accessibility](#accessibility)
-  - 🧪 [Testing](#testing)
-  - 🔰 [Adding icons](#adding-icons)
-- ♻️ [CI setup](#ci-setup)
-- 📗 [Stories](#stories)
 
-## Installation
+## Getting started
 
 To use WebUI, you need to add it as a dependency to your project:
 
@@ -61,178 +55,59 @@ The `font-family` property value is important, as this is what WebUI is referenc
 
 If you don't declare these `@font-face` rules, the font will not be available and the headings will gracefully fall back to next available font in your application.
 
-## Running locally
+## How to use
 
-If you want to run Storybook locally you can use:
+The primary goal of WebUI is to make frontend development faster. It does this by providing a set of commonly used components that can be composed together to build user interfaces.  
+WebUI aims to have every component well documented, both in the code and in Storybook. You can find all available components and documentation on how to
+use them at [design.luscii.com](https://design.luscii.com/).
 
-```bash
-yarn install
-yarn dev # runs a Tailwind watcher and Storybook
-```
-
-## Testing your production build
-
-Assuming the following setup:
-
-- The `web-ui` and `cVitals-Web` repositories are siblings in the same folder.
-- You ran `yarn install` in `cVitals-Web`.
-- You ran `yarn build` in `web-ui`.
-
-Run the script below in your terminal, _in the parent folder of the repositories_.
-
-```
-cp -a web-ui/dist/. cVitals-Web/node_modules/@luscii-healthtech/web-ui/dist
-```
+### Example scenario
 
-Or use the shortcut:
+Say you're tasked with building a UI that contains a card. This card has a title, a subtitle, some body text and a button. You could build this UI by writing the following code:
 
-```
-yarn test-copy-build
-```
-
-When you run `cVitals-Web` again, it should contain your latest updates in the component library. Use this to make sure your changes are solid before opening a pull request.
-
-## Contributing
-
-Thank you for your help in keeping our component library organized and easy to use!
-
-When adding components, please make sure to implement them consistently in our projects and that it is clear where and when they should be used. We want to avoid having many similar components. If you want to add components, do so in the `/src/components` directory. When you create new components, add them to Storybook as well. Stories go in the `/stories` directory.
-
-If you add new components, please make sure they fit in with our existing ones and that it's clear where and when they should be used. We want to avoid having too many similar components.
-
-### Documentation
-
-Every component should have proper documentation that explains when, where and how to use it. This sounds like a lot of work, but it doesn't have to be. And it's important, also for you, to quickly see how to best use a component.
-
-Component documentation should include the following parts:
-
-- A short explanation of each prop in a JSDoc comment style.
-- A stories file (`<ComponentName>.stories.tsx`).
-- A docs file (`<ComponentName>.docs.mdx`).
-
-Below is an explanation of each.
-
-#### Props documented via JSDoc comments
-
-A short explanation of each prop in a JSDoc comment style. These will show up in your IDE for on the fly documentation when you need it. It will also show up in Storybook, so this is a double-whammy and provides documentation exactly where you need it.
+```tsx
+import { Card, Text, Button } from "@luscii-healthtech/web-ui";
 
-```ts
-type Props = {
-  /**
-   * Optional description that will be shown close to the label, used to provide more
-   * detail about the field next to the concise text of the label.
-   */
-  helperText?: string;
-};
+function MyComponent() {
+  return (
+    <div className="my-layout">
+      <Card>
+        <Card.Title>Heart program</Card.Title>
+        <Card.Subtitle>79 participants</Card.Subtitle>
+        <Card.Text>Some description of how great this program is.</Card.Text>
+        <Card.Button>View program</Card.Button>
+      </Card>
+    </div>
+  );
+}
 ```
 
-#### Stories file
+Often times WebUI will provide a component that is a composition of other components. In this case, the `Card` component is a composition of `Card.Title`, `Card.Subtitle`, `Card.Text` and `Card.Button`. This allows you to build UIs faster, as you don't have to think about where to get a certain component. You can just use `Card` and its subcomponents and everything will be styled correctly.
 
-Stories files (`*stories.tsx`) will show up in Storybook as separate entries/pages for each component. Each component can have multiple stories defined for it, showing different use cases, variants and states of that component.  
-It is important to include stories for a lot of these different variants and states, because visual snapshots will be created of these stories by a tool called Chromatic. This allows us to visually track changes to the component over time, and ensure that it looks and behaves correctly across different use cases. By writing stories that showcase all the different ways your component can be used, you can catch issues early and ensure that your component is robust and reliable.
+## Frequently asked questions
 
-You can find the Chromatic project for WebUI [here](https://www.chromatic.com/library?appId=62b0c4d5afd432f7ee70a740).
+<details>
+<summary>The feature I'm building needs a component from WebUI that doesn't exist.</summary>
 
-#### Docs file
+Please get in touch with the design system circle by sending us a message in the [#design-system-circle channel](https://luscii.slack.com/archives/C03507ZKRCY). We'll discuss your needs and see what would be the best way to move forward.
 
-The component docs file brings everything together and should be considered the source of truth about the component. What should be documented:
+</details>
 
-- Why we have the component and where it should be used.
-- An overview of the different variants and states.
-- Usage guidelines of when and where to use the component.
-- Best practices to show what to do and what not do when working with the component.
+<details>
+<summary>The component I'm using doesn't have the props/subcomponents to build my feature.</summary>
 
-> 🔎 If you need to e.g. create a story to show how NOT to use a component, you might not want
-> to create a snapshot for that component or show it in the sidebar of Storybook. To omit a story
-> from snapshots, add the following to its parameters:
->
-> ```ts
-> chromatic: { disableSnapshot: true },
-> ```
->
-> To hide a story from the sidebar, prefix the story (variable) name
-> with `HIDE_`.
+In most cases you can build the UI you need by composing the components that are available. If for instance `Card.Text` doesn't exist, go "one level up" and find the component that is closest to what you need. In this case, you can use the `Text` component and configure it with the correct props to match the design.
 
-Please see examples of other components' docs files for inspiration and try to stay consistent with how they are documented.
+In case the component is missing a prop that you need, please get in touch with the design system circle by sending us a message in the [#design-system-circle channel](https://luscii.slack.com/archives/C03507ZKRCY). We'll discuss your needs and see what would be the best way to move forward.
 
-### Accessibility
+</details>
 
-WebUI is not currently designed to support screen reader usage. This is because our application is designed specifically for healthcare providers and is not publicly accessible. Our primary users are caregivers who work in healthcare and do not rely on screen readers to be able to use our application.  
-However, it is important for developers to write accessible frontend code. Even if our current application is not designed to support screen reader usage. This means following best practices for web accessibility, such as using semantic HTML, providing alternative text for images, and ensuring keyboard navigation is possible. While our primary users may not rely on screen readers, it is important to make our application as inclusive as possible to all users.
-
-### Testing
-
-WebUI relies on two types of testing: Visual snapshot testing via Chromatic and interaction testing via Storybook.
-
-Visual snapshot testing is handled for you. Any story you write will be picked up by Chromatic and it will create a snapshot for it.
-
-Interaction testing via Storybook allows to programmatically interact with the component. This is very helpful in testing any logic that the component may use internally and any states of the component that might be hard/impossible to trigger from the outside.  
-More information on how to approach writing interaction tests can be found in [this page of the Storybook documentation](https://storybook.js.org/docs/react/writing-tests/interaction-testing#write-an-interaction-test).
-
-### Adding icons
-
-Add new icons by following these steps:
-
-- Add the svg file(s) in `src/components/Icons/icons`.
-- Run `yarn icons`.
-
-The icons are optimized by SVGO and transformed into React components by [SVGR](https://react-svgr.com) which are placed in `src/components/Icons`.
-
-## CI setup
-
-### Branching
-
-The `main` branch is our default branch. When you contribute, branch from there and use the following branch naming convention:
-
-```
-  // Branch naming convention (enforced)
-
-  major/*      // For a new design system or changes that effect our foundations (e.g. typography, color).
-  minor/*      // For new components and stories.
-  patch/*      // For small improvements to existing components or stories.
-  bug/*        // For bugs or fixes.
-  chore/*      // For things related to development that don't impact the output for consumers and/or users.
-```
-
-We have configured at lot of magic for your convenience.
-
-### On every PR
-
-1. The module build, lint and tests are checked.
-2. The Storybook build is published to Chromatic.
-3. Labels are added based on the branch name and PR size.
-4. Branch names must follow the convention and are checked.
-
-### On merge to main
-
-1. Drafts a GitHub release.
-2. Bumps the version of the package.
-3. Publishes the new package version to NPM.
-
-## Stories
-
-### Stories using deprecated props
-
-When creating new stories for components with deprecated functionality please prefix the story name with `Deprecated`. In addition, also mark it with a "DEPRECATED" badge via the story's parameters.
+## Contributing
 
-For example a story of a `FullPageModal` component using the deprecated `primaryButtonProps` prop would look like this:
+Great to have you help making WebUI better! We have a few guidelines and tips
+to make sure we can keep the library consistent and easy to use. You can find
+them in our [contributing guide](CONTRIBUTING.md).
 
-```tsx
-import { BADGES } from "../.storybook/constants";
-
-export const DeprecatedWithPrimaryButtonProps = {
-  render: OneColumTemplate,
-  args: {
-    isOpen: true,
-    primaryButtonProps: {
-      onClick: action("onClick Primary Button"),
-      text: "Primary",
-    },
-  },
-  parameters: {
-    badges: [BADGES.DEPRECATED],
-  },
-};
-```
+### Reporting bugs
 
-This groups deprecated stories together and will make it easier to remove them later on.
+If you find a bug, please report it by sending us a message in the [#design-system-circle channel](https://luscii.slack.com/archives/C03507ZKRCY). It helps us a lot knowing of anything that is not working as expected.

package/dist/components/Accordion/Accordion.d.ts

@@ -5,6 +5,11 @@ export interface AccordionProps {
     items: AccordionItemProps[];
     className?: string;
     isCollapsedByDefault?: boolean;
+    /**
+     * A section at the bottom of the accordion that is
+     * always visible, even when the accordion is closed.
+     */
+    footer?: React.ReactNode;
 }
-declare const Accordion: React.VFC<AccordionProps>;
+declare const Accordion: React.FC<AccordionProps>;
 export default Accordion;

package/dist/components/Accordion/AccordionItem.d.ts

@@ -1,9 +1,17 @@
 import React from "react";
 export interface AccordionItemProps {
     id: string | number;
-    title: string;
+    title: React.ReactNode;
     content: React.ReactNode;
     className?: string;
     isCollapsedByDefault?: boolean;
+    /**
+     * Called when the accordion item opens.
+     */
+    onOpened?: () => void;
+    /**
+     * Called when the accordion item closes.
+     */
+    onClosed?: () => void;
 }
-export declare const AccordionItem: React.VFC<AccordionItemProps>;
+export declare const AccordionItem: React.FC<AccordionItemProps>;

package/dist/components/AccordionList/AccordionList.d.ts

@@ -21,18 +21,21 @@ export interface AccordionListProps extends Omit<AccordionProps, "items"> {
     isLoading?: boolean;
     actions?: React.ReactNode;
 }
-export type AccordionListItemProps<T = ListItemProps> = Omit<AccordionItemProps, "content"> & {
+export type AccordionListItemProps<T = ListItemProps> = Omit<AccordionItemProps, "title" | "content"> & {
     listItems: T[];
     draggableListType?: "default";
+    title: string;
 };
-export type DraggableAccordionListItemProps = Omit<AccordionItemProps, "content"> & {
+export type DraggableAccordionListItemProps = Omit<AccordionItemProps, "title" | "content"> & {
     draggableListType: "draggable";
     listItems: DraggableListProps["items"];
+    title: string;
 };
-export type SortableAccordionListItemProps = Omit<AccordionItemProps, "content"> & {
+export type SortableAccordionListItemProps = Omit<AccordionItemProps, "title" | "content"> & {
     draggableListType: "sortable";
     draggableIdentifier: string;
     listItems: SortableListProps["items"];
+    title: string;
 };
 export type AccordionItem = AccordionListItemProps | DraggableAccordionListItemProps | SortableAccordionListItemProps;
 interface StaticComponents {

package/dist/index.d.ts

@@ -3,6 +3,13 @@ export { FlexRow } from "./components/Container/FlexRow";
 export type { FlexContainerProps } from "./components/Container/types/FlexContainerProps.type";
 export { default as Toaster, TOASTER_TYPE_OPTIONS, } from "./components/Toaster/Toaster";
 export { toast } from "./components/Toaster/toast";
+/**
+ * We want a better version for the Accordion component, so we're
+ * only temporarily exporting the current version. The new version
+ * will be called `Accordion`, which will allow us to slowly migrate
+ * to the new version.
+ */
+export { default as AccordionTemporary } from "./components/Accordion/Accordion";
 export { AccordionList, AccordionListItemProps, AccordionListProps, } from "./components/AccordionList/AccordionList";
 export { Modal, ModalProps } from "./components/Modal/Modal";
 export { ModalSize, ModalBaseProps } from "./components/Modal/ModalBase";

package/dist/index.development.js

@@ -2,6 +2,7 @@
 
 var React = require('react');
 var classNames = require('classnames');
+var isString = require('lodash/isString');
 var lodash = require('lodash');
 var core = require('@dnd-kit/core');
 var sortable = require('@dnd-kit/sortable');
@@ -49,6 +50,7 @@ function _interopNamespace(e) {
 
 var React__namespace = /*#__PURE__*/_interopNamespace(React);
 var classNames__default = /*#__PURE__*/_interopDefault(classNames);
+var isString__default = /*#__PURE__*/_interopDefault(isString);
 var ReactTooltip__default = /*#__PURE__*/_interopDefault(ReactTooltip);
 var ReactModal__default = /*#__PURE__*/_interopDefault(ReactModal);
 var Glider__default = /*#__PURE__*/_interopDefault(Glider);
@@ -1073,8 +1075,16 @@ Title.defaultProps = {
   type: "base"
 };
 
-const AccordionItem = ({ id, title, content, isCollapsedByDefault = false }) => {
-  const [isCollapsed, toggleIsCollapsed] = React.useReducer((state) => !state, isCollapsedByDefault);
+const AccordionItem = ({ id, title, content, isCollapsedByDefault = false, onClosed, onOpened }) => {
+  const [isCollapsed, toggleIsCollapsed] = React.useReducer((isCol) => {
+    const newStateIsCollapsed = !isCol;
+    if (newStateIsCollapsed) {
+      onClosed === null || onClosed === void 0 ? void 0 : onClosed();
+    } else {
+      onOpened === null || onOpened === void 0 ? void 0 : onOpened();
+    }
+    return newStateIsCollapsed;
+  }, isCollapsedByDefault);
   const Chevron = isCollapsed ? RightArrowIcon : ChevronDownIcon;
   return React__namespace.default.createElement(
     "li",
@@ -1085,18 +1095,23 @@ const AccordionItem = ({ id, title, content, isCollapsedByDefault = false }) =>
         "ui-border-b ui-border-slate-200": !isCollapsed
       }) },
       React__namespace.default.createElement(Chevron, { className: "ui-text-slate-300" }),
-      React__namespace.default.createElement(Title, { text: title, type: "xs" })
+      isString__default.default(title) ? React__namespace.default.createElement(Title, { type: "xs" }, title) : title
     ),
     React__namespace.default.createElement("div", { className: classNames__default.default({ "ui-hidden": isCollapsed }) }, content)
   );
 };
 
-const Accordion = ({ dataTestId, isCollapsedByDefault = false, items, className }) => {
+const Accordion = ({ dataTestId, isCollapsedByDefault = false, items, className, footer }) => {
   var _a;
-  return React__namespace.default.createElement("ul", { "data-test-id": dataTestId, className }, (_a = items.map) === null || _a === void 0 ? void 0 : _a.call(items, (item) => {
-    var _a2;
-    return React__namespace.default.createElement(AccordionItem, Object.assign({}, item, { key: item.id, isCollapsedByDefault: (_a2 = item.isCollapsedByDefault) !== null && _a2 !== void 0 ? _a2 : isCollapsedByDefault }));
-  }));
+  return React__namespace.default.createElement(
+    "ul",
+    { "data-test-id": dataTestId, className },
+    (_a = items.map) === null || _a === void 0 ? void 0 : _a.call(items, (item) => {
+      var _a2;
+      return React__namespace.default.createElement(AccordionItem, Object.assign({}, item, { key: item.id, isCollapsedByDefault: (_a2 = item.isCollapsedByDefault) !== null && _a2 !== void 0 ? _a2 : isCollapsedByDefault }));
+    }),
+    footer && React__namespace.default.createElement("div", { className: "ui-p-4" }, footer)
+  );
 };
 
 var css_248z$j = ".list-skeleton .skeleton-box {\n  display: inline-block;\n  height: 1em;\n  position: relative;\n  overflow: hidden;\n  background-color: #cbd5e1;\n  border-radius: 3px;\n}\n.list-skeleton .skeleton-box::after {\n  position: absolute;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  left: 0;\n  transform: translateX(-100%);\n  background-image: linear-gradient(90deg, rgba(255, 255, 255, 0) 0, rgba(255, 255, 255, 0.2) 20%, rgba(255, 255, 255, 0.5) 60%, rgba(255, 255, 255, 0));\n  animation: shimmer 800ms infinite;\n  content: \"\";\n}\n.list-skeleton .skeleton-box.is-circle {\n  border-radius: 50%;\n}\n.list-skeleton .skeleton-box.is-button {\n  background-color: #e2e8f0;\n  border-radius: 9999px;\n}\n.list-skeleton .skeleton-box.is-button::after {\n  position: absolute;\n  top: 0;\n  right: 0;\n  bottom: 0;\n  left: 0;\n  transform: translateX(-100%);\n  background-image: linear-gradient(90deg, rgba(221, 221, 221, 0) 0, rgba(221, 221, 221, 0.2) 20%, rgba(221, 221, 221, 0.5) 60%, rgba(221, 221, 221, 0));\n  animation: shimmer 800ms infinite;\n  content: \"\";\n}\n@keyframes shimmer {\n  100% {\n    transform: translateX(100%);\n  }\n}";
@@ -5807,6 +5822,7 @@ WeekdaysPicker.weekdayNameToIndex = weekdayNameToIndex;
 WeekdaysPicker.indexToWeekdayName = indexToWeekdayName;
 
 exports.AccordionList = AccordionList;
+exports.AccordionTemporary = Accordion;
 exports.AddIcon = AddIcon;
 exports.AlertsIcon = BellIcon;
 exports.Avatar = Avatar;