From 57a9e0ce45ea37ae939feced8c6704b16b688297 Mon Sep 17 00:00:00 2001
From: Huw Wilkins <huw.wilkins@canonical.com>
Date: Fri, 17 May 2024 10:31:50 +1000
Subject: [PATCH] feat: add application layout Panel component

---
 src/components/Panel/Panel.stories.tsx |  62 +++++++
 src/components/Panel/Panel.test.tsx    |  78 ++++++++
 src/components/Panel/Panel.tsx         | 244 +++++++++++++++++++++++++
 src/components/Panel/index.ts          |   5 +
 src/index.ts                           |   2 +
 src/types/index.ts                     |   8 +
 src/utils.ts                           |   7 +
 7 files changed, 406 insertions(+)
 create mode 100644 src/components/Panel/Panel.stories.tsx
 create mode 100644 src/components/Panel/Panel.test.tsx
 create mode 100644 src/components/Panel/Panel.tsx
 create mode 100644 src/components/Panel/index.ts

diff --git a/src/components/Panel/Panel.stories.tsx b/src/components/Panel/Panel.stories.tsx
new file mode 100644
index 000000000..6c81efdbc
--- /dev/null
+++ b/src/components/Panel/Panel.stories.tsx
@@ -0,0 +1,62 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+
+import Panel from "./Panel";
+import Button from "components/Button";
+import Icon from "components/Icon";
+
+const meta: Meta<typeof Panel> = {
+  component: Panel,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Panel>;
+
+export const Default: Story = {
+  args: {
+    children: "Panel content",
+    title: "Panel",
+  },
+};
+
+export const Header: Story = {
+  args: {
+    controls: (
+      <Button appearance="positive">
+        <Icon name="plus" light /> Create
+      </Button>
+    ),
+    title: "Panel title",
+    titleComponent: "h1",
+  },
+};
+
+/**
+ * The logo may be provided as attributes to use the standard logo. If this is
+ * not sufficient the a `ReactNode` can be passed to the `logo` prop instead.
+ */
+export const Logo: Story = {
+  args: {
+    logo: {
+      icon: "https://assets.ubuntu.com/v1/7144ec6d-logo-jaas-icon.svg",
+      name: "https://assets.ubuntu.com/v1/a85f7947-juju_black-text-only.svg",
+      nameAlt: "Juju",
+    },
+  },
+};
+
+/**
+ * If the default header does not meet your needs then a `ReactNode` can be
+ * passed to the `header` prop to replace the header.
+ */
+export const CustomHeader: Story = {
+  args: {
+    header: (
+      <div className="p-panel__header">
+        This header replaces the entire header area
+      </div>
+    ),
+  },
+};
diff --git a/src/components/Panel/Panel.test.tsx b/src/components/Panel/Panel.test.tsx
new file mode 100644
index 000000000..c7cbd5312
--- /dev/null
+++ b/src/components/Panel/Panel.test.tsx
@@ -0,0 +1,78 @@
+import React from "react";
+import { render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { ButtonHTMLAttributes } from "react";
+
+import Panel from "./Panel";
+
+it("displays a title", () => {
+  const title = "Test Panel";
+  render(<Panel title={title} />);
+  expect(screen.getByText(title)).toHaveClass("p-panel__title");
+});
+
+it("displays a logo", () => {
+  render(
+    <Panel
+      logo={{
+        href: "http://example.com",
+        icon: "icon.svg",
+        iconAlt: "Icon SVG",
+        name: "name.svg",
+        nameAlt: "Name SVG",
+      }}
+    />
+  );
+  const link = screen.getByRole("link", { name: "Icon SVG Name SVG" });
+  expect(link).toHaveAttribute("href", "http://example.com");
+  expect(within(link).getByRole("img", { name: "Icon SVG" })).toHaveAttribute(
+    "src",
+    "icon.svg"
+  );
+  expect(within(link).getByRole("img", { name: "Name SVG" })).toHaveAttribute(
+    "src",
+    "name.svg"
+  );
+});
+
+it("logo handles different components", () => {
+  const Link = ({ ...props }: ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button {...props} />
+  );
+  render(
+    <Panel
+      logo={{
+        title: "http://example.com",
+        component: Link,
+        icon: "icon.svg",
+        iconAlt: "Icon SVG",
+        name: "name.svg",
+        nameAlt: "Name SVG",
+      }}
+    />
+  );
+  expect(
+    screen.getByRole("button", { name: "Icon SVG Name SVG" })
+  ).toHaveAttribute("title", "http://example.com");
+});
+
+it("displays a toggle", async () => {
+  const onClick = jest.fn();
+  render(<Panel title="Test panel" toggle={{ label: "Toggle", onClick }} />);
+  const toggle = screen.getByRole("button", { name: "Toggle" });
+  await userEvent.click(toggle);
+  expect(onClick).toHaveBeenCalled();
+});
+
+it("handles key presses on the toggle", async () => {
+  const onClick = jest.fn();
+  render(<Panel title="Test panel" toggle={{ label: "Toggle", onClick }} />);
+  const toggle = screen.getByRole("button", { name: "Toggle" });
+  await userEvent.type(toggle, "{Space}");
+  expect(onClick).toHaveBeenCalled();
+});
+
+it("displays a panel with no header", async () => {
+  render(<Panel>Content</Panel>);
+  expect(screen.getByText("Content")).toBeInTheDocument();
+});
diff --git a/src/components/Panel/Panel.tsx b/src/components/Panel/Panel.tsx
new file mode 100644
index 000000000..e227f9b0f
--- /dev/null
+++ b/src/components/Panel/Panel.tsx
@@ -0,0 +1,244 @@
+import React from "react";
+import type { PropsWithSpread } from "types";
+import classNames from "classnames";
+import type {
+  ComponentType,
+  ElementType,
+  HTMLProps,
+  PropsWithChildren,
+  ReactNode,
+} from "react";
+
+import type { ExclusiveProps } from "types";
+import { isReactNode } from "utils";
+
+export type LogoDefaultElement = HTMLProps<HTMLAnchorElement>;
+
+type PanelLogo<L = LogoDefaultElement> =
+  | ReactNode
+  | PropsWithSpread<
+      {
+        /**
+         * The url of the icon image.
+         */
+        icon: string;
+        /**
+         * The alt text for the icon image.
+         */
+        iconAlt?: string;
+        /**
+         * The url of the name image.
+         */
+        name: string;
+        /**
+         * The alt text for the name image.
+         */
+        nameAlt?: string;
+        /**
+         * The element or component to use for displaying the logo e.g. `a` or `NavLink`.
+         * @default a
+         */
+        component?: ElementType | ComponentType<L>;
+      },
+      L
+    >;
+
+type PanelToggle = {
+  /**
+   * The panel toggle label.
+   */
+  label: string;
+  /**
+   * The function to call when clicking the panel toggle.
+   */
+  onClick: () => void;
+};
+
+type LogoProps<L = LogoDefaultElement> = {
+  /**
+   * The panel logo content or attributes.
+   */
+  logo?: PanelLogo<L>;
+};
+
+type TitleProps = {
+  /**
+   * The panel title.
+   */
+  title: ReactNode;
+  /**
+   * Classes to apply to the title element.
+   */
+  titleClassName?: string;
+  /**
+   * The element to use for the panel title e.g. `h1`.
+   * @default h4
+   */
+  titleComponent?: ElementType;
+};
+
+type HeaderProps<L = LogoDefaultElement> = ExclusiveProps<
+  {
+    /**
+     * This prop can be used to replace the header area of the panel when the default implementation is not sufficient.
+     */
+    header: ReactNode;
+  },
+  {
+    /**
+     * Content that will be displayed in the controls area.
+     */
+    controls?: ReactNode;
+    /**
+     * Classes that will be applied to the controls element.
+     */
+    controlsClassName?: string;
+    /**
+     * Whether the header should be sticky.
+     */
+    stickyHeader?: boolean;
+    /**
+     * The panel toggle attributes.
+     */
+    toggle?: PanelToggle;
+  } & ExclusiveProps<LogoProps<L>, TitleProps>
+>;
+
+export type Props<L = LogoDefaultElement> = {
+  /**
+   * The panel content.
+   */
+  children?: PropsWithChildren["children"];
+  /**
+   * Classes that are applied to the content container (when using `wrapContent`).
+   */
+  contentClassName?: string | null;
+  /**
+   * Classes that are applied to the top level panel element.
+   */
+  className?: string | null;
+  /**
+   * Whether to use the dark theme.
+   */
+  dark?: boolean;
+  /**
+   * Whether the panel should wrap the content in the `p-panel__content` element.
+   * @default true
+   */
+  wrapContent?: boolean;
+  /**
+   * A ref to pass to the top level panel element.
+   */
+  forwardRef?: React.Ref<HTMLDivElement> | null;
+} & HeaderProps<L>;
+
+const generateLogo = <L = LogoDefaultElement,>(logo: PanelLogo<L>) => {
+  if (isReactNode(logo)) {
+    return logo;
+  }
+  const {
+    icon,
+    iconAlt,
+    name,
+    nameAlt,
+    component: Component = "a",
+    ...props
+  } = logo;
+  return (
+    <Component className="p-panel__logo" {...props}>
+      <img
+        className="p-panel__logo-icon"
+        src={icon}
+        alt={iconAlt}
+        width="24"
+        height="24"
+      />
+      <img
+        className="p-panel__logo-name is-fading-when-collapsed"
+        src={name}
+        alt={nameAlt}
+        height="16"
+      />
+    </Component>
+  );
+};
+
+/**
+ * This is a [React](https://reactjs.org/) component for panels in the
+ * [Vanilla](https://vanillaframework.io/docs/) layouts.
+ *
+ * The Panel component can be used in many areas of the application layout. It
+ * can be the child element of `AppAside`, `AppMain`, `AppNavigation`, `AppNavigationBar`
+ * and `AppStatus`.
+ */
+const Panel = <L = LogoDefaultElement,>({
+  forwardRef,
+  children,
+  className,
+  contentClassName,
+  controlsClassName,
+  controls,
+  dark,
+  header,
+  logo,
+  stickyHeader,
+  title,
+  titleClassName,
+  titleComponent: TitleComponent = "h4",
+  toggle,
+  wrapContent = true,
+  ...props
+}: Props<L>) => {
+  return (
+    <div
+      {...props}
+      className={classNames("p-panel", className, {
+        "is-dark": dark,
+      })}
+      ref={forwardRef}
+    >
+      {logo || title || controls || toggle ? (
+        <div
+          className={classNames("p-panel__header", {
+            "is-sticky": stickyHeader,
+          })}
+        >
+          {logo ? (
+            generateLogo<L>(logo)
+          ) : (
+            <TitleComponent
+              className={classNames("p-panel__title", titleClassName)}
+            >
+              {title}
+            </TitleComponent>
+          )}
+          <div className={classNames("p-panel__controls", controlsClassName)}>
+            {toggle ? (
+              <span
+                role="button"
+                tabIndex={0}
+                className="p-panel__toggle"
+                onClick={() => toggle.onClick()}
+                onKeyDown={() => toggle.onClick()}
+              >
+                {toggle.label}
+              </span>
+            ) : null}
+            {controls}
+          </div>
+        </div>
+      ) : (
+        header
+      )}
+      {children && wrapContent ? (
+        <div className={classNames("p-panel__content", contentClassName)}>
+          {children}
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  );
+};
+
+export default Panel;
diff --git a/src/components/Panel/index.ts b/src/components/Panel/index.ts
new file mode 100644
index 000000000..273a8b533
--- /dev/null
+++ b/src/components/Panel/index.ts
@@ -0,0 +1,5 @@
+export {
+  default,
+  type Props as PanelProps,
+  type LogoDefaultElement as PanelLogoDefaultElement,
+} from "./Panel";
diff --git a/src/index.ts b/src/index.ts
index f2ef9e83e..48e96ccbe 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -45,6 +45,7 @@ export {
 } from "./components/NotificationProvider";
 export { default as LoginPageLayout } from "./components/LoginPageLayout";
 export { default as Pagination } from "./components/Pagination";
+export { default as Panel } from "./components/Panel";
 export { default as PasswordToggle } from "./components/PasswordToggle";
 export { default as RadioInput } from "./components/RadioInput";
 export { default as Row } from "./components/Row";
@@ -123,6 +124,7 @@ export type {
 } from "./components/NotificationProvider";
 export type { LoginPageLayoutProps } from "./components/LoginPageLayout";
 export type { PaginationProps } from "./components/Pagination";
+export type { PanelProps } from "./components/Panel";
 export type { RadioInputProps } from "./components/RadioInput";
 export type { RowProps } from "./components/Row";
 export type { SearchAndFilterProps } from "./components/SearchAndFilter";
diff --git a/src/types/index.ts b/src/types/index.ts
index fc142c0e5..839d59485 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -39,3 +39,11 @@ export type TSFixMe = any; // eslint-disable-line @typescript-eslint/no-explicit
  * defined in EnumLike.
  */
 export type ValueOf<T> = T[keyof T];
+
+/*
+ * This type can be used for React props where a component needs to provide the
+ * props from either A or B, but prevent a mix of both.
+ */
+export type ExclusiveProps<A, B> =
+  | (A & Partial<Record<keyof B, never>>)
+  | (B & Partial<Record<keyof A, never>>);
diff --git a/src/utils.ts b/src/utils.ts
index 62749c5b6..9d487486c 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -1,4 +1,5 @@
 import { NavLink, NavLinkAnchor, NavLinkButton } from "components/Navigation";
+import { isValidElement, ReactNode } from "react";
 
 export const IS_DEV = process.env.NODE_ENV === "development";
 
@@ -43,3 +44,9 @@ export const isNavigationAnchor = (link: NavLink): link is NavLinkAnchor =>
  */
 export const isNavigationButton = (link: NavLink): link is NavLinkButton =>
   !link.url;
+
+/**
+ * A typeguard for whether an element is a ReactNode.
+ */
+export const isReactNode = (element: unknown): element is ReactNode =>
+  isValidElement(element);