@luscii-healthtech/web-ui 7.6.2 → 8.0.0

package/README.md

@@ -1,6 +1,6 @@
-# web-ui
+# WebUI
 
-The web-ui repository contains the UI components for Luscii's front-end projects. It is published to NPM for usage into our projects. It uses Storybook and is published to Chromatic for easy review of visual 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
 
@@ -31,17 +31,84 @@ 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 opening 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 documented in Storybook. We highly value consistency, simplicity and usability. 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 the `/src/components` directory.
+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.
 
-Please stay vigilant when adding components that we implement them consistently in our projects and that it is clear where and when they have to be used. We want to avoid a lot of components that are similar.
+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.
 
-When you create new components, you must add them to Storybook as well. Stories go in the `/stories` directory.
+### 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.
+
+```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 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
 
@@ -79,27 +146,9 @@ We have configured at lot of magic for your convenience.
 
 ### On merge to main
 
-1. Draft a GitHub release.
-2. Version bump of the package.
-3. Publish new package to NPM.
-
----
-
-## IE11
-
-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.
-
-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)
-
-Optional:
-
-- [web-animations-js](https://www.npmjs.com/package/web-animations-js)
-
-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.
+1. Drafts a GitHub release.
+2. Bumps the version of the package.
+3. Publishes the new package version to NPM.
 
 ## Stories
 

package/dist/components/Text/Text.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="react" />
+import React from "react";
 import { RestPropped } from "../../types/general.types";
 import "./Text.css";
 /**
@@ -8,14 +8,14 @@ import "./Text.css";
  * https://v1.tailwindcss.com/docs/controlling-file-size
  */
 declare const allowedTextStyles: {
-    sm: string;
-    "sm-strong": string;
-    base: string;
-    strong: string;
-    lg: string;
-    "lg-strong": string;
-    xl: string;
-    "xl-strong": string;
+    readonly sm: "ui-text-xs ui-font-medium";
+    readonly "sm-strong": "ui-text-xs ui-font-semibold";
+    readonly base: "ui-text-sm";
+    readonly strong: "ui-text-sm ui-font-semibold";
+    readonly lg: "";
+    readonly "lg-strong": "ui-font-semibold";
+    readonly xl: "ui-text-lg";
+    readonly "xl-strong": "ui-font-semibold ui-text-lg";
 };
 export declare const allowedColors: {
     readonly base: "ui-text-slate-800";
@@ -35,20 +35,72 @@ declare const allowedHoverColors: {
 export type TextColor = keyof typeof allowedColors;
 export type TextHoverColor = keyof typeof allowedHoverColors;
 export type TextStyle = keyof typeof allowedTextStyles;
-export interface TextProps extends RestPropped {
-    text: string;
+export interface TextProps extends RestPropped, React.ComponentPropsWithoutRef<"p"> {
+    /**
+     * @deprecated
+     * Use `children` instead, as you would with a regular `<p>` tag.
+     */
+    text?: string;
+    /**
+     * @deprecated
+     * Use `variant` instead. "type" is a word that is too ambiguous and
+     * is also often used as an attribute name in HTML.
+     *
+     * @default "base"
+     */
     type?: TextStyle;
+    /**
+     * The styling variant of the text.
+     *
+     * @default "base"
+     */
+    variant?: TextStyle;
+    /**
+     * Changes the component to be rendered inline. This is useful for
+     * using this component inside of itself, for example, when you want
+     * to render bold text inside of a paragraph rendered by this same component.
+     *
+     * @default false
+     */
     inline?: boolean;
+    /**
+     * @default "base"
+     */
     color?: TextColor;
+    /**
+     * @default "base"
+     */
     hoverColor?: TextHoverColor;
+    /**
+     * Tailwind class modifier that allows you to apply hover styles on this component
+     * based on the styles of its parent.
+     * https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state
+     *
+     * @deprecated
+     * Since this is a Tailwind specific feature we should not expose this to the consumer. We
+     * should only use group-hover styles in the components in WebUI instead.
+     */
     hoverInGroup?: boolean;
     className?: string;
+    /**
+     * Interpret an HTML string as regular markup, instead of rendering it as a string.
+     *
+     * @default false
+     */
     containsDangerousHtml?: boolean;
+    /**
+     * With this prop enabled, text won't wrap to the next line but instead
+     * will be truncated with an ellipsis.
+     *
+     * @default false
+     */
     truncate?: boolean;
     /**
-     * When `true` will work together with the `truncate` props
+     * When `true` will work together with the `truncate` prop
      * and allow a max of two lines when breaking text before applying
-     * elipsis. Defaults to "`false`"
+     * ellipsis.
+     *
+     * @default false
      */
     clampLines?: boolean;
     "data-test-id"?: string;
@@ -56,11 +108,8 @@ export interface TextProps extends RestPropped {
 export declare const Text: {
     (props: TextProps): JSX.Element;
     defaultProps: {
-        type: string;
-        inline: boolean;
-        color: string;
-        containsDangerousHtml: boolean;
-        truncate: boolean;
+        variant: "base";
+        color: "base";
     };
 };
 export default Text;

package/dist/index.development.js

@@ -212,7 +212,10 @@ const allowedGroupHoverColors = {
   white: "ui-group-hover:ui-text-white"
 };
 const Text = (props) => {
-  var _a, _b;
+  var _a, _b, _c;
+  const { children } = props, rest = __rest(props, ["children"]);
+  const Component = props.inline ? "span" : "p";
+  const resolvedVariant = (_a = props.type) !== null && _a !== void 0 ? _a : props.variant;
   const selectedHoverColor = props.hoverColor && !props.hoverInGroup && allowedHoverColors[props.hoverColor];
   const selectedGroupHoverColor = props.hoverColor && props.hoverInGroup && allowedGroupHoverColors[props.hoverColor];
   const containerProps = {
@@ -222,7 +225,7 @@ const Text = (props) => {
       // apply different style classes
       // for now we stick with ui-font-size 16px on the body
       // so I am adjusting our styles accordingly (one step down)
-      allowedTextStyles[(_a = props.type) !== null && _a !== void 0 ? _a : "base"],
+      allowedTextStyles[resolvedVariant !== null && resolvedVariant !== void 0 ? resolvedVariant : "base"],
       allowedColors[(_b = props.color) !== null && _b !== void 0 ? _b : "base"],
       selectedHoverColor,
       selectedGroupHoverColor,
@@ -237,14 +240,11 @@ const Text = (props) => {
       props.className
     )
   };
-  return props.containsDangerousHtml ? React__namespace.default.createElement("p", Object.assign({}, containerProps, { dangerouslySetInnerHTML: { __html: props.text } })) : React__namespace.default.createElement("p", Object.assign({}, containerProps), props.text);
+  return props.containsDangerousHtml ? React__namespace.default.createElement(Component, Object.assign({}, rest, containerProps, { dangerouslySetInnerHTML: { __html: (_c = children !== null && children !== void 0 ? children : props.text) !== null && _c !== void 0 ? _c : "" } })) : React__namespace.default.createElement(Component, Object.assign({}, rest, containerProps), children !== null && children !== void 0 ? children : props.text);
 };
 Text.defaultProps = {
-  type: "base",
-  inline: false,
-  color: "base",
-  containsDangerousHtml: false,
-  truncate: false
+  variant: "base",
+  color: "base"
 };
 
 const IconWrapper = (SVGComponent) => (props) => React__namespace.default.createElement(SVGComponent, Object.assign({}, props, { role: props.onClick ? "button" : void 0 }));