@luscii-healthtech/web-ui 0.0.0-alpha.ab3fdb2 → 0.0.0-alpha.ccdf511

package/README.md

@@ -1,109 +1,113 @@
-# web-ui
+# WebUI
 
-The web-ui repository contains the web UI components for Luscii's front end projects. It is published to NPM for inclusion into our projects. It also uses storybook and is published to chromatic for easy review of changes.
+The `web-ui` repository contains the UI components for Luscii's frontend projects. It is published to NPM for usage into our projects. It uses Storybook and is published to Chromatic for easy review and tracking of visual changes.
 
-## Running locally
+## Table of contents
 
-If you want to run storybook locally you can use
+- 🚀 [Getting started](#getting-started)
+  - 📖 [Fonts](#fonts)
+- 📦 [How to use](#how-to-use)
+- 🤝 [Contributing](#contributing)
 
-```bash
-yarn install
-yarn storybook
-```
-
-## Testing your production build
+## Getting started
 
-Assuming the following setup:
+To use WebUI, you need to add it as a dependency to your project:
 
-- The `web-ui` and `cVitals-Web` repositories are siblings are in the same folder
-- You have ran `yarn install` on `cVitals-Web`
-- You have ran `yarn build` on `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
+```bash
+yarn add @luscii-healthtech/web-ui
 ```
 
-Or use the shortcut:
+Then you can use components like this:
 
-```
-yarn test-copy-build
-```
-
-When you run cVitals again, it should contain your latest updates in the component library. Use this to make sure your changes are solid before merging a pull request.
-
-## Contributing
-
-Make sure you understand our design system and follow its guidelines. They are document in storybook. We value consistency, simplicity and usability highly. Don't mess it up.
-
-If you want to add components, do so in
+```tsx
+import { Text } from "@luscii-healthtech/web-ui";
 
+function MyComponent() {
+  return <Text>Some beautiful text from WebUI!</Text>;
+}
 ```
-/src/components
-```
-
-Please stay vigilant when adding components that we implement them consistently in our projects and that it is clear when and where they have to be used. We want to avoid a lot of components that are similar.
 
-When you create new components, you must add them to storybook as well. Stories go in
-
-```
-/stories
+### Fonts
+
+WebUI uses the Avenir Next LT Pro font family for some headings. If you want to use these, you need to make them available in your project. You can do this by declaring the following `@font-face` rules in your CSS:
+
+```css
+@font-face {
+  font-family: "AvenirNextLTPro-Regular";
+  src:
+    url("./<regular-font-file>.eot") format("embedded-opentype"),
+    url("./<regular-font-file>.woff2") format("woff2"),
+    url("./<regular-font-file>.woff") format("woff"),
+    url("./<regular-font-file>.ttf") format("truetype");
+}
+
+@font-face {
+  font-family: "AvenirNextLTPro-Bold";
+  src:
+    url("./<bold-font-file>.eot") format("embedded-opentype"),
+    url("./<bold-font-file>.woff2") format("woff2"),
+    url("./<bold-font-file>.woff") format("woff"),
+    url("./<bold-font-file>.ttf") format("truetype");
+}
 ```
 
-### Adding icons
+The `font-family` property value is important, as this is what WebUI is referencing to use the font. The `src` property values should point to the font files you want to use.
 
-Add new icons by:
+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.
 
-- Add the svg file(s) in `src/components/Icons/icons`
-- Run `yarn icons`
+## How to use
 
-The icons are optimized by SVGO and transformed into React components by [SVGR](https://react-svgr.com) which are placed in `src/components/Icons`.
+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/).
 
-## CI setup
+### Example scenario
 
-#### Branching
+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:
 
-The `main` branch is our default branch. When you contribute, branch from there and name your branch
+```tsx
+import { Card, Text, Button } from "@luscii-healthtech/web-ui";
 
+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>
+  );
+}
 ```
-  //Branch names convention (enforced)
 
-  major/*      //for a new design system or changes that effect our foundations (typography, color)
-  minor/*      //for new components and stories
-  patch/*      //for small improvements to existing components, stories
-  bug/*        //for bugs, fixes
-```
+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.
 
-We have configured at lot of magic for your convenience.
+## Frequently asked questions
 
-#### On every PR
+<details>
+<summary>The feature I'm building needs a component from WebUI that doesn't exist.</summary>
 
-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
+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.
 
-#### On merge to main
+</details>
 
-1. Draft a github release
-2. Version bump of the package
-3. Publish new package to NPM
+<details>
+<summary>The component I'm using doesn't have the props/subcomponents to build my feature.</summary>
 
----
+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.
 
-## IE11
+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.
 
-This package includes [dnd-kit](https://dndkit.com) as a peer dependency. The bundle of dnd-kit contains syntax which isn't compatible with IE11, therefore any application needing to support IE11 has to transpile dnd-kit.
+</details>
 
-It should also at least include the following polyfills to make it work:
-
-- [core-js](https://www.npmjs.com/package/core-js)
-- [regenerator-runtime](https://www.npmjs.com/package/regenerator-runtime)
-- [smoothscroll-polyfill](https://www.npmjs.com/package/smoothscroll-polyfill)
+## Contributing
 
-Optional:
+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).
 
-- [web-animations-js](https://www.npmjs.com/package/web-animations-js)
+### Reporting bugs
 
-This isn't necessary if the [drop animation is disabled](https://github.com/clauderic/dnd-kit/issues/705#issuecomment-1103056336). Check out [this ticket](https://github.com/clauderic/dnd-kit/issues/271) for more information on IE11.
+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

@@ -3,6 +3,7 @@ import { AccordionProps } from "../Accordion/Accordion";
 import { DraggableListProps, ListItemProps, SortableListProps } from "../List/List.types";
 import { AccordionItemProps } from "../Accordion/AccordionItem";
 import { BaseButtonProps } from "../ButtonV2/ButtonProps.type";
+import { AccordionListActions } from "./subcomponents/AccordionListActions";
 export interface AccordionListProps extends Omit<AccordionProps, "items"> {
     localisations: {
         title: string;
@@ -10,23 +11,35 @@ export interface AccordionListProps extends Omit<AccordionProps, "items"> {
         emptyListText?: string;
     };
     accordionItems: AccordionItem[];
+    /**
+     * @deprecated
+     * Use the `actions` prop to render any button(s)
+     * or other component(s) automatically in the correct area.
+     */
     buttonProps?: BaseButtonProps;
     isSearchEnabled?: boolean;
     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;
-export declare const AccordionList: React.FC<AccordionListProps>;
+interface StaticComponents {
+    Actions: typeof AccordionListActions;
+}
+export declare const AccordionList: React.FC<AccordionListProps> & StaticComponents;
 export default AccordionList;

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

@@ -0,0 +1,18 @@
+import React from "react";
+/**
+ * Use in the actions of an AccordionList. Spaces out the action
+ * components correctly in relation to the styling of the AccordionList component.
+ *
+ * @usage
+ * ```tsx
+ * <AccordionList
+ *   actions={
+ *     <AccordionList.Actions>
+ *       <PrimaryButton />
+ *       <SecondaryButton />
+ *     </AccordionList.Actions>
+ *   }
+ * />
+ * ```
+ */
+export declare const AccordionListActions: React.FC<React.PropsWithChildren>;

package/dist/components/Avatar/Avatar.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+type AvatarSize = "large" | "medium" | "small";
+type Props = {
+    initials: string;
+    src?: string;
+    /**
+     * Put the name of the person here, so less sighted
+     * users can know who the avatar belongs to.
+     *
+     * In case of rendering the default image or the
+     * initials, this will also be used as the `alt` text.
+     */
+    alt?: string;
+    size?: AvatarSize;
+    /**
+     * URL to an image to be used as the default image.
+     * If this is set, the image provided via `src` will never render.
+     */
+    defaultImage?: string;
+    className?: string;
+};
+export declare const Avatar: ({ size, src, alt, defaultImage, initials, className, }: Props) => React.JSX.Element;
+export {};

package/dist/components/ButtonV2/ButtonProps.type.d.ts

@@ -6,6 +6,11 @@ import { TextColor, TextHoverColor } from "../Text/Text";
  *
  */
 export interface BaseButtonProps extends React.ComponentPropsWithRef<"button"> {
+    size?: "medium" | "large";
+    children?: React.ReactNode;
+    /**
+     * @deprecated Use `children` instead.
+     */
     text?: string;
     icon?: React.FunctionComponent<IconProps> | IconKey;
     isDisabled?: boolean;

package/dist/components/Card/Actions.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export declare const Actions: React.FC<React.ComponentPropsWithoutRef<"div">>;

package/dist/components/Card/Card.d.ts

@@ -1,12 +1,57 @@
 import React from "react";
-export type CardProps = {
+import { TitleProps } from "../Title/Title";
+type TitleAndMaybeActions = {
     title: string;
-    children: React.ReactNode;
-    dataTestId?: string;
+    /**
+     * Spaces and positions the action components correctly in relation to
+     * the styling of the card.
+     *
+     * @usage
+     * ```tsx
+     * <Card
+     *   actions={
+     *     <Card.Actions>
+     *       <PrimaryButton />
+     *       <SecondaryButton />
+     *     </Card.Actions>
+     *   }
+     * />
+     * ```
+     */
+    actions: React.ReactNode;
+} | {
+    title: undefined;
+    actions: undefined;
+} | {
+    title?: string;
+    /**
+     * The `actions` prop can only be used in conjunction with the `title` prop.
+     */
+    actions?: never;
 };
-/**
- * Card component that centralizes itself inside a container.
- * Specific variant made with w-135 to suffice the use case needed,
- * more variants can be added.
- */
-export declare const Card: React.FC<CardProps>;
+export type Props<C extends React.ElementType> = React.ComponentPropsWithoutRef<C> & {
+    as?: C;
+    children: React.ReactNode;
+    /**
+     * Whether or not to add the default padding to the card. Set this
+     * to `false` if you want to render something full width inside of the
+     * card, like an image or a list. You have access to the `Card.Padding`
+     * subcomponent to then add back the default padding wherever needed.
+     *
+     * @default true
+     */
+    padding?: boolean;
+} & TitleAndMaybeActions;
+export declare function Card<C extends React.ElementType = "div">(props: Props<C>): React.JSX.Element;
+export declare namespace Card {
+    var Title: (props: TitleProps) => React.JSX.Element;
+    var TopBar: typeof import("./TopBar").TopBar;
+    var Padding: React.FC<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+        children?: React.ReactNode;
+    }>;
+    var Section: React.FC<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
+        children?: React.ReactNode;
+    }>;
+    var Actions: React.FC<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">>;
+}
+export {};

package/dist/components/Card/Padding.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+type Props = React.ComponentPropsWithoutRef<"div"> & {
+    children?: React.ReactNode;
+};
+export declare const Padding: React.FC<Props>;
+export {};

package/dist/components/Card/Section.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+type Props = React.ComponentPropsWithoutRef<"div"> & {
+    children?: React.ReactNode;
+};
+export declare const Section: React.FC<Props>;
+export {};

package/dist/components/Card/TopBar.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+type Props = React.ComponentPropsWithoutRef<"div"> & {
+    children?: React.ReactNode;
+};
+export declare function TopBar(props: Props): React.JSX.Element;
+export declare namespace TopBar {
+    var Actions: React.FC<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">>;
+}
+export {};

package/dist/components/Carousel/Carousel.d.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import "glider-js/glider.min.css";
 interface CarouselProps {
     id: string;
     slides: React.ReactNode[];

package/dist/components/Checkbox/Checkbox.d.ts

@@ -1,19 +1,64 @@
 import React from "react";
 import "./Checkbox.scss";
 export interface CheckboxProps {
+    /**
+     * ID used for semantic targeting, as can be used in attributes like `<label htmlFor="some-id">`.
+     */
     id?: string;
+    /**
+     * The visible text labeling the checkbox element.
+     */
     text?: string;
+    /**
+     * Helper text that adds some more information on what the option means, or inform
+     * the user about the consequences of the checkbox.
+     *
+     * Only works if the `renderLabel` prop isn't set.
+     */
     explanation?: string;
+    /**
+     * Shows a different checkbox variant. `type="switch"` shows a switch-like component
+     * without a visual label.
+     */
     type?: "regular" | "switch";
+    /**
+     * Set the value.
+     * Same as `checked` on `<input type="checkbox" />`.
+     */
     isChecked?: boolean;
+    /**
+     * Value for when it is not clear if the state of this checkbox
+     * is "checked" or not (for hierarchical checkboxes).
+     */
     isIndeterminate?: boolean;
+    /**
+     * Disallow the user to change the checkbox value.
+     * Same as `disabled` on `<input type="checkbox" />`.
+     */
     isDisabled?: boolean;
+    /**
+     * The name that the value of the checkbox will be associated with.
+     * Same as `name` on `<input type="checkbox" />`.
+     */
     name?: string;
+    /**
+     * This can be used to retrieve the value it is referring to through onChange.
+     */
     value?: string;
     onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
     className?: string;
+    classNameCheckboxLabel?: string;
+    /**
+     * Visually show that the currently selected value has an issue the user needs to attend to.
+     */
     error?: boolean;
     innerRef?: React.Ref<HTMLInputElement>;
+    /**
+     * Renders a completely custom label. Can change its contents or
+     * appearance based on the props of the checkbox item.
+     *
+     * Overrides the `text` prop.
+     */
+    renderLabel?: (props: CheckboxProps) => JSX.Element | null;
 }
 export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
-export default Checkbox;

package/dist/components/CheckboxList/CheckboxGroup.d.ts

@@ -1,3 +1,3 @@
 /// <reference types="react" />
 import { CheckboxGroupProps } from "./CheckboxList.types";
-export declare const CheckboxGroup: ({ title, items, onChange, className, hasDividers, isCollapsed, collapsible, }: CheckboxGroupProps) => JSX.Element;
+export declare const CheckboxGroup: ({ title, items, onChange, className, isCollapsed, collapsible, }: CheckboxGroupProps) => JSX.Element;

package/dist/components/CheckboxList/CheckboxList.d.ts

@@ -1,5 +1,4 @@
 /// <reference types="react" />
 import { CheckboxListProps } from "./CheckboxList.types";
 export { CheckboxListProps };
-export declare const CheckboxList: ({ groups, onChange, className, hasDividers, }: CheckboxListProps) => JSX.Element;
-export default CheckboxList;
+export declare const CheckboxList: ({ groups, onChange, className, }: CheckboxListProps) => JSX.Element;

package/dist/components/CheckboxList/CheckboxList.types.d.ts

@@ -4,34 +4,47 @@ export declare enum CheckboxState {
     UNCHECKED = "unchecked"
 }
 export interface CheckboxListProps {
+    /**
+     * An array of items to render as checkboxes. Each item can be a single item or a group. When the
+     * title isn't specified, the group will render as a non-collapsible list. This is the way to
+     * render a regular list of checkboxes.
+     *
+     * @example
+     * Single list of checkboxes without visual grouping.
+     *
+     * ```tsx
+     * const groups = [{
+     *   items: [
+     *     {
+     *       id: "1",
+     *       label: "Item 1",
+     *     },
+     *     {
+     *       id: "2",
+     *       label: "Item 2",
+     *     },
+     *   ],
+     * }]
+     * ```
+     */
     groups: CheckboxGroup[];
     onChange: (event: CheckboxChangeEvent) => void;
-    hasDividers?: boolean;
     className?: string;
 }
 type WithCollapsible = {
     /**
-     * When `false`, will prevent the checkbox list from being collapsed (also disabling clicking to expand/collapse)
+     * When `false` will prevent the checkbox list from being collapsed (also disabling clicking to expand/collapse)
      * in the component and it will be displayed expanded by default.
      * @default true
      */
     collapsible?: boolean;
 };
-export type CheckboxGroupProps = {
-    title?: string;
-    items: CheckboxListItem[];
+export type CheckboxGroupProps = CheckboxGroup & {
     onChange: (event: CheckboxChangeEvent) => void;
-    hasDividers?: boolean;
     className?: string;
-    isCollapsed?: boolean;
 } & WithCollapsible;
-export interface CheckboxGroupItemProps {
-    id: string;
-    label: string;
-    isChecked?: boolean;
-    isDisabled?: boolean;
+export interface CheckboxGroupItemProps extends CheckboxListItem {
     onChange: (event: CheckboxChangeEvent) => void;
-    className?: string;
 }
 export interface CheckboxListItem {
     id: string;
@@ -41,8 +54,17 @@ export interface CheckboxListItem {
     className?: string;
 }
 export type CheckboxGroup = {
+    /**
+     * When the title isn't specified, the group will render as a non-collapsible list.
+     */
     title?: string;
+    /**
+     * The checkbox items to be shown inside of this group.
+     */
     items: CheckboxListItem[];
+    /**
+     * Whether the group is initially collapsed or not.
+     */
     isCollapsed?: boolean;
 } & WithCollapsible;
 export interface CheckboxChangeEvent {

package/dist/components/Container/types/FlexContainerProps.type.d.ts

@@ -7,12 +7,12 @@ type FlexContainerBase = {
     verticalSpacing?: Spacing;
     horizontalSpacing?: Spacing;
     /**
-     * Applies the default padding (`"p-4"`) inside the container.
+     * Applies the default padding (`"ui-p-4"`) inside the container.
      */
     hasPadding?: boolean;
     backgroundColor?: string;
     /**
-     * If `true`, will make the flexbox full width and not size it relative to its content.
+     * If `true`, will make the flexbox full width and not size itui-relative to its content.
      * @default true
      */
     stretch?: boolean;

package/dist/components/Divider/Divider.d.ts

@@ -1,6 +1,17 @@
 import React from "react";
-type DividerProps = {
+type DividerProps = React.ComponentPropsWithoutRef<"div"> & {
     dark?: boolean;
 };
-export declare const Divider: React.FC<DividerProps>;
+type HrProps = React.ComponentPropsWithoutRef<"hr"> & {
+    /**
+     * Request the v2 version of the divider, which has the following benefits:
+     * - Uses an `<hr>` tag instead of a `<div>`.
+     * - Uses the border color from the design system, and doesn't have a prop
+     *   to change it.
+     * - Doesn't contain any logic about when it should be hidden.
+     */
+    version: "v2";
+};
+type Props = DividerProps | HrProps;
+export declare const Divider: React.FC<Props>;
 export {};

package/dist/components/FilterBar/ActiveFilters.d.ts

@@ -0,0 +1,9 @@
+import React from "react";
+import { CategorizedFilters, FilterBarLocalization, OnFilterBarFilterChange } from "./FilterBarProps.type";
+type ActiveFiltersProps = {
+    filters: CategorizedFilters;
+    onRemoveActiveFilter: OnFilterBarFilterChange;
+    localization: Pick<FilterBarLocalization, "filtersLabel">;
+};
+export declare const ActiveFilters: React.FC<ActiveFiltersProps>;
+export {};