PM-17068-Implement Docs for Lit Storybook Instance (#12912)

* PM-17068 -add mdx path to lit main file - Add button docs * temp remove meta to fix main storybook * cipher docs composed * icons doc * notification docs composed * convert to hidden files * isolate hidden files * isolate docs within hidden folder and change doc files to not be hidden for build
bitwarden · Jan 31, 2025 · 1d71212 · 1d71212
1 parent ca53ecc
commit 1d71212
Show file tree

Hide file tree

Showing 12 changed files with 739 additions and 1 deletion.
diff --git a/apps/browser/src/autofill/content/components/.lit-storybook/main.ts b/apps/browser/src/autofill/content/components/.lit-storybook/main.ts
@@ -8,7 +8,7 @@ const getAbsolutePath = (value: string): string =>
   dirname(require.resolve(join(value, "package.json")));
 
 const config: StorybookConfig = {
-  stories: ["../lit-stories/**/*.lit-stories.@(js|jsx|ts|tsx)"],
+  stories: ["../lit-stories/**/*.lit-stories.@(js|jsx|ts|tsx)", "../lit-stories/**/*.mdx"],
   addons: [
     getAbsolutePath("@storybook/addon-links"),
     getAbsolutePath("@storybook/addon-essentials"),

diff --git a/...browser/src/autofill/content/components/lit-stories/.lit-docs/action-button.mdx b/...browser/src/autofill/content/components/lit-stories/.lit-docs/action-button.mdx
@@ -0,0 +1,64 @@
+import { Meta, Controls, Primary } from "@storybook/addon-docs";
+
+import * as stories from "./action-button.lit-stories";
+
+<Meta title="Components/Buttons/Action Button" of={stories} />
+
+## Action Button
+
+The `ActionButton` component is a customizable button built using the `lit` library and styled with
+`@emotion/css`. This component supports themes, handles click events, and includes a disabled state.
+It is designed with accessibility and responsive design in mind.
+
+<Primary />
+<Controls />
+
+## Props
+
+| **Prop**       | **Type**                   | **Required** | **Description**                                             |
+| -------------- | -------------------------- | ------------ | ----------------------------------------------------------- |
+| `buttonAction` | `(e: Event) => void`       | Yes          | The function to execute when the button is clicked.         |
+| `buttonText`   | `string`                   | Yes          | The text to display on the button.                          |
+| `disabled`     | `boolean` (default: false) | No           | Disables the button when set to `true`.                     |
+| `theme`        | `Theme`                    | Yes          | The theme to style the button. Must match the `Theme` enum. |
+
+## Installation and Setup
+
+1. Ensure you have the necessary dependencies installed:
+
+   - `lit`: Used to render the component.
+   - `@emotion/css`: Used for styling the component.
+
+2. Pass the required props to the component when rendering:
+   - `buttonAction`: A function that handles the click event.
+   - `buttonText`: The text displayed on the button.
+   - `disabled` (optional): A boolean indicating whether the button is disabled.
+   - `theme`: The theme to style the button (must be a valid `Theme`).
+
+## Accessibility (WCAG) Compliance
+
+The `ActionButton` component follows the
+[W3C ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/). Below is a breakdown of
+key accessibility considerations:
+
+### Keyboard Accessibility
+
+- The button supports keyboard interaction through the `@click` event.
+- Users can activate the button using the `Enter` or `Space` key.
+
+### Screen Reader Compatibility
+
+- The `title` attribute is dynamically set to the button's text (`buttonText`), ensuring it is read
+  by screen readers.
+- The semantic `<button>` element is used, which is natively recognized by assistive technologies.
+
+### Focus Management
+
+- Ensure proper focus management when interacting with the button, especially when navigating using
+  a keyboard.
+
+### Visual Feedback
+
+- The button provides clear visual states for hover and disabled states:
+  - **Hover:** Changes background color, border color, and text contrast.
+  - **Disabled:** Muted background and text colors with no pointer events.
diff --git a/.../browser/src/autofill/content/components/lit-stories/.lit-docs/badge-button.mdx b/.../browser/src/autofill/content/components/lit-stories/.lit-docs/badge-button.mdx
@@ -0,0 +1,64 @@
+import { Meta, Controls, Primary } from "@storybook/addon-docs";
+
+import * as stories from "./badge-button.lit-stories";
+
+<Meta title="Components/Buttons/Badge Button" of={stories} />
+
+## Badge Button
+
+The `BadgeButton` component is a compact, styled button built using the `lit` library and styled
+with `@emotion/css`. It is designed to display concise text and supports themes, click event
+handling, and a disabled state. The component is optimized for accessibility and responsive design.
+
+<Primary />
+<Controls />
+
+## Props
+
+| **Prop**       | **Type**                   | **Required** | **Description**                                             |
+| -------------- | -------------------------- | ------------ | ----------------------------------------------------------- |
+| `buttonAction` | `(e: Event) => void`       | Yes          | The function to execute when the button is clicked.         |
+| `buttonText`   | `string`                   | Yes          | The text to display on the badge button.                    |
+| `disabled`     | `boolean` (default: false) | No           | Disables the button when set to `true`.                     |
+| `theme`        | `Theme`                    | Yes          | The theme to style the button. Must match the `Theme` enum. |
+
+## Installation and Setup
+
+1. Ensure you have the necessary dependencies installed:
+
+   - `lit`: Used to render the component.
+   - `@emotion/css`: Used for styling the component.
+
+2. Pass the required props to the component when rendering:
+   - `buttonAction`: A function that handles the click event.
+   - `buttonText`: The text displayed on the badge button.
+   - `disabled` (optional): A boolean indicating whether the button is disabled.
+   - `theme`: The theme to style the button (must be a valid `Theme`).
+
+## Accessibility (WCAG) Compliance
+
+The `BadgeButton` component follows the
+[W3C ARIA button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/). Below is a breakdown of
+key accessibility considerations:
+
+### Keyboard Accessibility
+
+- The button supports keyboard interaction through the `@click` event.
+- Users can activate the button using the `Enter` or `Space` key.
+
+### Screen Reader Compatibility
+
+- The `title` attribute is dynamically set to the button's text (`buttonText`), ensuring it is read
+  by screen readers.
+- The semantic `<button>` element is used, which is natively recognized by assistive technologies.
+
+### Focus Management
+
+- Ensure proper focus management when interacting with the button, especially when navigating using
+  a keyboard.
+
+### Visual Feedback
+
+- The button provides clear visual states for hover and disabled states:
+  - **Hover:** Changes background color, border color, and text contrast.
+  - **Disabled:** Muted background and text colors with no pointer events.
diff --git a/apps/browser/src/autofill/content/components/lit-stories/.lit-docs/body.mdx b/apps/browser/src/autofill/content/components/lit-stories/.lit-docs/body.mdx
@@ -0,0 +1,70 @@
+import { Meta, Controls, Primary } from "@storybook/addon-docs";
+
+import * as stories from "./body.lit-stories";
+
+<Meta title="Components/Notifications/Notification Body" of={stories} />
+
+## Notification Body
+
+The `NotificationBody` component displays a detailed notification with a list of associated ciphers,
+notification type, and styling based on the selected theme. It is a flexible component for
+presenting actionable information.
+
+<Primary />
+<Controls />
+
+## Props
+
+| **Prop**           | **Type**           | **Required** | **Description**                                                                                           |
+| ------------------ | ------------------ | ------------ | --------------------------------------------------------------------------------------------------------- |
+| `ciphers`          | `CipherData[]`     | Yes          | An array of cipher data objects. Each cipher includes metadata such as ID, name, type, and login details. |
+| `notificationType` | `NotificationType` | Yes          | Specifies the type of notification, such as `add`, `change`, `unlock`, or `fileless-import`.              |
+| `theme`            | `Theme`            | Yes          | Defines the theme used for styling the notification. Must match the `Theme` enum.                         |
+
+---
+
+## Usage Example
+
+```tsx
+import { NotificationBody } from "../../notification/body";
+import { ThemeTypes } from "@bitwarden/common/platform/enums/theme-type.enum";
+
+<NotificationBody
+  ciphers={[
+    {
+      id: "1",
+      name: "Example Cipher",
+      type: "Login",
+      favorite: false,
+      reprompt: "None",
+      icon: {
+        imageEnabled: true,
+        image: "",
+        fallbackImage: "https://example.com/fallback.png",
+        icon: "icon-class",
+      },
+      login: { username: "[email protected]", passkey: null },
+    },
+  ]}
+  notificationType="add"
+  theme={ThemeTypes.Dark}
+/>;
+```
+
+### Accessibility (WCAG) Compliance
+
+The NotificationBody component is designed to be accessible and adheres to WCAG guidelines:
+
+## Screen Reader Compatibility
+
+- Ciphers are presented with clear labeling to ensure context for assistive technologies.
+- Icons include fallback options for better accessibility.
+
+## Visual Feedback
+
+- `notificationType` adjusts the visual presentation for contextually relevant feedback.
+
+### Notes
+
+- ciphers: Ensure the array includes well-defined cipher objects to avoid rendering issues.
+- notificationType: This prop influences the messaging and appearance of the notification body.
diff --git a/...browser/src/autofill/content/components/lit-stories/.lit-docs/cipher-action.mdx b/...browser/src/autofill/content/components/lit-stories/.lit-docs/cipher-action.mdx
@@ -0,0 +1,83 @@
+import { Meta, Controls, Primary } from "@storybook/addon-docs";
+
+import * as stories from "./cipher-action.lit-stories";
+
+<Meta title="Components/Ciphers/Cipher Action" of={stories} />
+
+## Cipher Action
+
+The `CipherAction` component is a functional UI element that handles actions related to ciphers in a
+secure environment. Built with the `lit` library and styled for consistency across themes, it
+provides flexibility and accessibility while supporting various notification types.
+
+<Primary />
+<Controls />
+
+## Props
+
+| **Prop**           | **Type**                                            | **Required** | **Description**                                                |
+| ------------------ | --------------------------------------------------- | ------------ | -------------------------------------------------------------- |
+| `handleAction`     | `(e: Event) => void`                                | No           | Function to execute when an action is triggered.               |
+| `notificationType` | `NotificationTypes.Change \| NotificationTypes.Add` | Yes          | Specifies the type of notification associated with the action. |
+| `theme`            | `Theme`                                             | Yes          | The theme to style the component. Must match the `Theme` enum. |
+
+## Installation and Setup
+
+1. Ensure the necessary dependencies are installed:
+
+   - `lit`: Used to render the component.
+
+2. Pass the required props when rendering the component:
+   - `handleAction`: Optional function to handle the triggered action.
+   - `notificationType`: Mandatory type from `NotificationTypes` to define the action context.
+   - `theme`: The styling theme (must be a valid `Theme` enum value).
+
+## Accessibility (WCAG) Compliance
+
+The `CipherAction` component is designed to be accessible, ensuring usability across diverse user
+bases. Below are the key considerations for accessibility:
+
+### Keyboard Accessibility
+
+- Fully navigable using the keyboard.
+- The action can be triggered using the `Enter` or `Space` key for users relying on keyboard
+  interaction.
+
+### Screen Reader Compatibility
+
+- The semantic elements used in the `CipherAction` component ensure that assistive technologies can
+  interpret the component correctly.
+- Text associated with the `notificationType` is programmatically linked, providing clarity for
+  screen reader users.
+
+### Focus Management
+
+- The component includes focus styles to ensure visibility during navigation.
+- Proper focus management ensures the component works seamlessly with keyboard navigation.
+
+### Visual Feedback
+
+- Provides distinct visual states for different themes and states:
+  - **Hover:** Adjustments to background, border, and text for enhanced visibility.
+  - **Active:** Highlights the button with a focus state when activated.
+  - **Disabled:** Grays out the component to indicate inactivity.
+
+## Usage Example
+
+Here's an example of how to integrate the `CipherAction` component:
+
+```ts
+import { CipherAction } from "../../cipher/cipher-action";
+import { ThemeTypes } from "@bitwarden/common/platform/enums/theme-type.enum";
+import { NotificationTypes } from "../../../../notification/abstractions/notification-bar";
+
+const handleAction = (e: Event) => {
+  console.log("Cipher action triggered!", e);
+};
+
+<CipherAction
+  handleAction={handleAction}
+  notificationType={NotificationTypes.Change}
+  theme={ThemeTypes.Dark}
+/>;
+```
diff --git a/apps/browser/src/autofill/content/components/lit-stories/.lit-docs/cipher-icon.mdx b/apps/browser/src/autofill/content/components/lit-stories/.lit-docs/cipher-icon.mdx
@@ -0,0 +1,90 @@
+import { Meta, Controls, Primary } from "@storybook/addon-docs";
+
+import * as stories from "./cipher-icon.lit-stories";
+
+<Meta title="Components/Ciphers/Cipher Icon" of={stories} />
+
+## Cipher Icon
+
+The `CipherIcon` component is a versatile icon renderer designed for secure environments. It
+dynamically supports custom icons provided via URIs or displays a default icon (`Globe`) styled
+based on the theme and provided properties.
+
+<Primary />
+<Controls />
+
+## Props
+
+| **Prop** | **Type**            | **Required** | **Description**                                                                                                                                                 |
+| -------- | ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `color`  | `string`            | Yes          | A contextual color override applied when the `uri` is not provided, ensuring consistent styling of the default icon.                                            |
+| `size`   | `string`            | Yes          | A valid CSS `width` value representing the width basis of the graphic. The height adjusts to maintain the original aspect ratio of the graphic.                 |
+| `theme`  | `Theme`             | Yes          | The styling theme for the icon, matching the `Theme` enum.                                                                                                      |
+| `uri`    | `string` (optional) | No           | A URL to an external graphic. If provided, the component displays this icon. If omitted, a default icon (`Globe`) styled with the provided `color` and `theme`. |
+
+## Installation and Setup
+
+1. Ensure the necessary dependencies are installed:
+
+   - `lit`: Renders the component.
+   - `@emotion/css`: Styles the component.
+
+2. Pass the necessary props when using the component:
+   - `color`: Used when no `uri` is provided to style the default icon.
+   - `size`: Defines the width of the icon. Height maintains aspect ratio.
+   - `theme`: Specifies the theme for styling.
+   - `uri` (optional): If provided, this URI is used to display a custom icon.
+
+## Accessibility (WCAG) Compliance
+
+The `CipherIcon` component ensures accessible and user-friendly interactions through thoughtful
+design:
+
+### Semantic Rendering
+
+- When the `uri` is provided, the component renders an `<img>` element, which is semantically
+  appropriate for external graphics.
+- If no `uri` is provided, the default icon is wrapped in a `<span>`, ensuring proper context for
+  screen readers.
+
+### Visual Feedback
+
+- The component visually adjusts based on the `size`, `color`, and `theme`, ensuring the icon
+  remains clear and legible across different environments.
+
+### Keyboard and Screen Reader Support
+
+- Ensure that any container or parent component provides appropriate `alt` text or labeling when
+  `uri` is used with an `<img>` tag for additional accessibility.
+
+## Usage Example
+
+Here's an example of how to integrate the `CipherIcon` component:
+
+```ts
+import { CipherIcon } from "./cipher-icon";
+import { ThemeTypes } from "@bitwarden/common/platform/enums/theme-type.enum";
+
+<CipherIcon
+  color="blue"
+  size="32px"
+  theme={ThemeTypes.Light}
+  uri="https://example.com/icon.png"
+/>;
+```
+
+This configuration displays a custom icon from the provided URI with a width of 32px, styled for the
+light theme. If the URI is omitted, the Globe icon is used as the fallback, colored in blue.
+
+### Default Styles
+
+- The default styles ensure responsive and clean design:
+
+- Width: Defined by the size prop.
+- Height: Automatically adjusts to maintain the aspect ratio.
+- Fit Content: Ensures the icon does not overflow or distort its container.
+
+### Notes
+
+- Always validate the uri provided to ensure it points to a secure and accessible location.
+- Use the color and theme props for consistent fallback styling when uri is not provided.