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

package/README.md

@@ -1,23 +1,23 @@
-# 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
 
-If you want to run storybook locally you can use
+If you want to run Storybook locally you can use:
 
 ```bash
 yarn install
-yarn storybook
+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 are in the same folder
-- You have ran `yarn install` on `cVitals-Web`
-- You have ran `yarn build` on `web-ui`
+- 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_.
 
@@ -31,79 +31,149 @@ Or use the shortcut:
 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.
+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
 
-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.
+Thank you for your help in keeping our component library organized and easy to use!
 
-If you want to add components, do so in
+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.
 
-```
-/src/components
-```
+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.
 
-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.
+### Documentation
 
-When you create new components, you must add them to storybook as well. Stories go in
+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.
+
+```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;
+};
 ```
-/stories
-```
+
+#### Stories file
+
+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.
+
+You can find the Chromatic project for WebUI [here](https://www.chromatic.com/library?appId=62b0c4d5afd432f7ee70a740).
+
+#### Docs file
+
+The component docs file brings everything together and should be considered the source of truth about the component. What should be documented:
+
+- 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.
+
+> 🔎 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_`.
+
+Please see examples of other components' docs files for inspiration and try to stay consistent with how they are documented.
+
+### Accessibility
+
+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:
+Add new icons by following these steps:
 
-- Add the svg file(s) in `src/components/Icons/icons`
-- Run `yarn icons`
+- 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
+### Branching
 
-The `main` branch is our default branch. When you contribute, branch from there and name your branch
+The `main` branch is our default branch. When you contribute, branch from there and use the following branch naming convention:
 
 ```
-  //Branch names convention (enforced)
+  // Branch naming 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
+  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
+### On every PR
 
-1. the module build, lint and tests are checked.
-2. The storybook build is published to chromatic.
+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
+4. Branch names must follow the convention and are checked.
 
-1. Draft a github release
-2. Version bump of the package
-3. Publish new package to NPM
+### On merge to main
 
----
+1. Drafts a GitHub release.
+2. Bumps the version of the package.
+3. Publishes the new package version to NPM.
 
-## IE11
+## Stories
 
-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.
+### Stories using deprecated props
 
-It should also at least include the following polyfills to make it work:
+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.
 
-- [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)
+For example a story of a `FullPageModal` component using the deprecated `primaryButtonProps` prop would look like this:
 
-Optional:
+```tsx
+import { BADGES } from "../.storybook/constants";
 
-- [web-animations-js](https://www.npmjs.com/package/web-animations-js)
+export const DeprecatedWithPrimaryButtonProps = {
+  render: OneColumTemplate,
+  args: {
+    isOpen: true,
+    primaryButtonProps: {
+      onClick: action("onClick Primary Button"),
+      text: "Primary",
+    },
+  },
+  parameters: {
+    badges: [BADGES.DEPRECATED],
+  },
+};
+```
 
-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.
+This groups deprecated stories together and will make it easier to remove them later on.

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,9 +11,15 @@ 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"> & {
     listItems: T[];
@@ -28,5 +35,8 @@ export type SortableAccordionListItemProps = Omit<AccordionItemProps, "content">
     listItems: SortableListProps["items"];
 };
 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/Card/Card.d.ts

@@ -6,7 +6,7 @@ export type CardProps = {
 };
 /**
  * Card component that centralizes itself inside a container.
- * Specific variant made with w-135 to suffice the use case needed,
+ * Specific variant made with ui-w-135 to suffice the use case needed,
  * more variants can be added.
  */
 export declare const Card: React.FC<CardProps>;

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/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 {};

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

@@ -0,0 +1,96 @@
+import { ReactElement } from "react";
+import { CategorizedFilters, FilterBarLocalization, TransformedSortingOptions } from "./FilterBarProps.type";
+type FilterBarProps<SortableEntity extends object> = {
+    /**
+     * A list of grouped filters to be displayed in the FilterBar.
+     *
+     * This is an array with items shaped as:
+     * ```ts
+     * type CategorizedFilter = {
+     *    key: string;
+     *    label: string;
+     *    options: TransformedFilterOptions;
+     * }
+     * ```
+     *
+     * You can choose to manually create this option or use the `getFilterGroups` helper function that will do the same
+     * for you based on your data.
+     *
+     * @example
+     *
+     * If you decided to use the `getFilterGroups` function:
+     *
+     *
+     * ```ts
+     * const items = []; // any list of object you are working with
+     *
+     * // the list of filter generators, the `filterValuePredicate` will be the displayed
+     * // value in the filter dropdown, so you can map and transform it to any custom string if necessary, or use
+     * // the value from the object entry
+     *
+     * const filterGenerators: FilterGenerator<TShirtFromApi>[] = [
+     *   {
+     *     id: "brand",
+     *     label: "Brand",
+     *     filterValuePredicate: (tshirt) => tshirt.brand,
+     *   },
+     *   {
+     *     id: "size",
+     *     label: "Size",
+     *     filterValuePredicate: (tshirt) => tshirt.size,
+     *   },
+     *   {
+     *     id: "color",
+     *     label: "Color",
+     *     filterValuePredicate: (tshirt) => tshirt.color,
+     *   },
+     * ];
+     *
+     * const categorizedFilters = getFilterGroups(items, filterGenerators);
+     * ```
+     *
+     *
+     * A compliant entry in the `categorizedFilters` has a shape like the object below:
+     *
+     *
+     * ```json
+     * {
+     *  "key": "color",
+     *  "label": "Color",
+     *  "options": [
+     *     {
+     *         "isChecked": false,
+     *         "id": "yellow",
+     *         "label": "yellow",
+     *         "value": "yellow"
+     *     },
+     *     {
+     *         "isChecked": false,
+     *         "id": "red",
+     *         "label": "red",
+     *         "value": "red"
+     *     },
+     *     {
+     *         "isChecked": false,
+     *         "id": "green",
+     *         "label": "green",
+     *         "value": "green"
+     *     }
+     *   ]
+     * }
+     *```
+     */
+    categorizedFilters: CategorizedFilters;
+    /**
+     * For more details, see {@link TransformedSortingOptions}.
+     */
+    sortingOptions: TransformedSortingOptions<SortableEntity>;
+    onFilterChange: (updatedFilters: CategorizedFilters) => void;
+    onSortingChange: (updatedSortingOptions: TransformedSortingOptions<SortableEntity>) => void;
+    /**
+     * See {@link FilterBarLocalization}.
+     */
+    localization: FilterBarLocalization;
+};
+export declare const FilterBar: <SortableEntity extends object>({ localization, categorizedFilters, sortingOptions, ...props }: FilterBarProps<SortableEntity>) => ReactElement | null;
+export {};

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

@@ -0,0 +1,32 @@
+import { CategorizedFilters, FilterGenerator, TransformedSortingOptions } from "./FilterBarProps.type";
+/**
+ * Generates the list of filters based on the data (see this as what you'd like to be filtered in your component).
+ *
+ * @param dataToGenerateFiltersFrom  - The data (list of entities) that will be used to create the filters.
+ * @param groupers a list of functions used to create the filters dropdown
+ * @returns {CategorisedFilters} a list of filters properly grouped.
+ */
+export declare function getFilterGroups<T extends unknown[]>(dataToGenerateFiltersFrom: T, groupers: FilterGenerator<T[number]>[]): CategorizedFilters;
+/**
+ *
+ * @param filterKey the key of the categorized filter (eg. color, size, brand) - which one of them are you gonna check.
+ * @param categorizedFilters the array of categorized filters the FilterBar component needs
+ * @param attributeGetter the getter to retrieve the attribute to be filtered on, this allow maximum flexibility on how to process
+ * filters on any level of nesting if necessary.
+ * @returns a predicate to be used in the filter function
+ * @example
+ *
+ *   const sizeFilterPredicate = createFilterPredicate<TShirtFromApi>("size", filtersOptions, (item) => item.meta.size);
+ *   const filteredBySize = items.filter(sizeFilterPredicate);
+ *
+ */
+export declare const createFilterPredicate: <T extends object>(filterKey: string, categorizedFilters: CategorizedFilters, attributeGetter: (item: T) => string) => (item: T) => boolean;
+/**
+ * Creates a sorting function to be used on a specific object attribute.
+ *
+ * @param getter the getter function to retrieve the attribute used in the sorting
+ * @param order if ascending or descending
+ * @returns the sorting comparer function to be used in Array.sort
+ */
+export declare const createSortingComparer: <T extends object>(getter: (item: T) => string | number, order?: "asc" | "desc") => (itemA: T, itemB: T) => number;
+export declare const applySorting: <T extends object[]>(sortable: T, sortingOptions: TransformedSortingOptions<T[number]>) => T;