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

package/README.md

@@ -1,109 +1,181 @@
-# 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
-```
+## Getting started
 
-## Testing your production build
+To use WebUI, you need to add it as a dependency to your project:
 
-Assuming the following setup:
+```bash
+yarn add @luscii-healthtech/web-ui
+```
 
-- 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`
+Then you can use components like this:
 
-Run the script below in your terminal, _in the parent folder of the repositories_.
+```tsx
+import { Text } from "@luscii-healthtech/web-ui";
 
-```
-cp -a web-ui/dist/. cVitals-Web/node_modules/@luscii-healthtech/web-ui/dist
+function MyComponent() {
+  return <Text>Some beautiful text from WebUI!</Text>;
+}
 ```
 
-Or use the shortcut:
+### Fonts
 
+WebUI uses the Inter font family for most of its text. This font should be provided by your application if you're using WebUI. The weights needed to show the full gamut of weights in the design system are 400, 500, 600 and 700. One way of doing this is using a Google Fonts link in your HTML file:
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
+  rel="stylesheet"
+/>
 ```
-yarn test-copy-build
+
+For some headings WebUI uses the Avenir Next LT Pro font family. 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");
+}
 ```
 
-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.
+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.
 
-## Contributing
+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.
 
-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.
+### LocaleProvider
 
-If you want to add components, do so in
+WebUI exposes a `LocaleProvider`, which is used to make components adjust their data formats to the locale of the application.
+You should wrap your app with the `LocaleProvider`.
 
-```
-/src/components
+```tsx
+import { LocaleProvider } from "@luscii-healthtech/web-ui";
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+function start() {
+  const root = createRoot(document.querySelector("#root"));
+  root.render(
+    <LocaleProvider value="nl-NL">
+      <App />
+    </LocaleProvider>
+  );
+}
 ```
 
-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.
+The locale passed should adhere to the `{language}-{region}` format, for example:
 
-When you create new components, you must add them to storybook as well. Stories go in
+- `nl-NL`
+- `en-GB`
+- `pt-PT`
+- `de-DE`
+- `fr-FR`
 
-```
-/stories
-```
+### Tooltip Provider
 
-### Adding icons
+Install the `@radix-ui/react-tooltip` peer dependency into your project:
 
-Add new icons by:
+```bash
+yarn add @radix-ui/react-tooltip
+```
 
-- Add the svg file(s) in `src/components/Icons/icons`
-- Run `yarn icons`
+Wrap your app with the `Tooltip.Provider` component:
+
+```tsx
+import * as Tooltip from "@radix-ui/react-tooltip";
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./App";
+
+function start() {
+  const root = createRoot(document.querySelector("#root"));
+  root.render(
+    <Tooltip.Provider delayDuration={800} skipDelayDuration={500}>
+      <App />
+    </Tooltip.Provider>
+  );
+}
+```
 
-The icons are optimized by SVGO and transformed into React components by [SVGR](https://react-svgr.com) which are placed in `src/components/Icons`.
+More about this component can be found in its [documentation](https://www.radix-ui.com/primitives/docs/components/tooltip).
 
-## CI setup
+## How to use
 
-#### Branching
+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/).
 
-The `main` branch is our default branch. When you contribute, branch from there and name your branch
+### Example scenario
 
-```
-  //Branch names convention (enforced)
+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:
 
-  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
+```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>
+  );
+}
 ```
 
-We have configured at lot of magic for your convenience.
+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.
 
-#### On every PR
+## Frequently asked questions
 
-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
+<details>
+<summary>The feature I'm building needs a component from WebUI that doesn't exist.</summary>
 
-#### On merge to main
+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.
 
-1. Draft a github release
-2. Version bump of the package
-3. Publish new package to NPM
+</details>
 
----
+<details>
+<summary>The component I'm using doesn't have the props/subcomponents to build my feature.</summary>
 
-## IE11
+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.
 
-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.
+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.
 
-It should also at least include the following polyfills to make it work:
+</details>
 
-- [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/.storybook/constants.d.ts

@@ -0,0 +1,35 @@
+import { type Meta } from "@storybook/react-webpack5";
+export declare const BADGES: {
+    readonly NEEDS_REVISION: "needs-revision";
+    readonly DOCUMENTED: "documented";
+    readonly STABLE: "stable";
+    readonly NEW: "new";
+    readonly DEPRECATED: "deprecated";
+};
+type TAGS = (typeof BADGES)[keyof typeof BADGES][];
+/**
+ * A drop-in replacements for `"@storybook/react-webpack5"`'s Meta type which extends the type with web-ui's tags.
+ *
+ * @example
+ *
+ * const meta = {
+ *  title: "Layout/SplitViewLayout",
+ *  component: Component,
+ *  tags: ["new"], // `tags` is now type-checked and auto-completes
+ * } satisfies MMeta<typeof Component>;
+ */
+export type MMeta<T> = Meta<T> & {
+    tags: TAGS;
+};
+/**
+ * For stories specifically used in the Docs page that are not intended
+ * to be used for snapshots. E.g. stories that are used to demonstrate
+ * what NOT to do, or stories that are used to demonstrate a component
+ * and that don't need to show up in snapshots.
+ */
+export declare const NO_SNAPSHOT_PARAMS: {
+    chromatic: {
+        disableSnapshot: boolean;
+    };
+};
+export {};

package/dist/.storybook/decorators.d.ts

@@ -0,0 +1,31 @@
+import { Decorator } from "@storybook/react-webpack5";
+import { ModalDialog } from "../src";
+import { ComponentProps, HTMLAttributes, ReactNode } from "react";
+export declare const LocaleDecorator: Decorator;
+export declare const TooltipDecorator: Decorator;
+export declare const createHoverCardDecorator: (trigger: ReactNode) => Decorator;
+export declare const CenteredDecorator: Decorator;
+/**
+ * Wraps the story in a div with the provided role.
+ *
+ * @example // Wrap the story within <div role="status"><Story /></div>
+ *
+ * const story = {
+ *   // ...
+ *   decorators: [createRoleDecorator("status")]
+ * }
+ *
+ */
+export declare const createRoleDecorator: (role: HTMLAttributes<HTMLDivElement>["role"]) => Decorator;
+/**
+ * Wraps the story in a ModalDialog.
+ *
+ * @example // Wrap the story within <ModalDialog variant="side-modal" size="l"><ModalDialog.Body><Story /></ModalDialog.Body></ModalDialog>
+ *
+ * const story = {
+ *   // ...
+ *   decorators: [createModalDialogDecorator({ size: "l", variant: "side-modal" })]
+ * }
+ *
+ */
+export declare const createModalDialogDecorator: (options?: Pick<ComponentProps<typeof ModalDialog>, "variant" | "size">) => Decorator;