@canonical/react-components 0.56.0 → 0.57.0

package/dist/components/Panel/Panel.d.ts

@@ -0,0 +1,123 @@
+import React from "react";
+import type { PropsWithSpread } from "../../types";
+import type { ComponentType, ElementType, HTMLProps, PropsWithChildren, ReactNode } from "react";
+import type { ExclusiveProps } from "../../types";
+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;
+    /**
+     * An ID for the title element.
+     */
+    titleId?: string;
+};
+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>;
+/**
+ * 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`.
+ */
+declare const Panel: <L = LogoDefaultElement>({ forwardRef, children, className, contentClassName, controlsClassName, controls, dark, header, logo, stickyHeader, title, titleClassName, titleComponent: TitleComponent, titleId, toggle, wrapContent, ...props }: Props<L>) => React.JSX.Element;
+export default Panel;

package/dist/components/Panel/Panel.js

@@ -0,0 +1,92 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _classnames = _interopRequireDefault(require("classnames"));
+var _utils = require("../../utils");
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+function _extends() { _extends = Object.assign ? Object.assign.bind() : function (target) { for (var i = 1; i < arguments.length; i++) { var source = arguments[i]; for (var key in source) { if (Object.prototype.hasOwnProperty.call(source, key)) { target[key] = source[key]; } } } return target; }; return _extends.apply(this, arguments); }
+const generateLogo = logo => {
+  if ((0, _utils.isReactNode)(logo)) {
+    return logo;
+  }
+  const {
+    icon,
+    iconAlt,
+    name,
+    nameAlt,
+    component: Component = "a",
+    ...props
+  } = logo;
+  return /*#__PURE__*/_react.default.createElement(Component, _extends({
+    className: "p-panel__logo"
+  }, props), /*#__PURE__*/_react.default.createElement("img", {
+    className: "p-panel__logo-icon",
+    src: icon,
+    alt: iconAlt,
+    width: "24",
+    height: "24"
+  }), /*#__PURE__*/_react.default.createElement("img", {
+    className: "p-panel__logo-name is-fading-when-collapsed",
+    src: name,
+    alt: nameAlt,
+    height: "16"
+  }));
+};
+
+/**
+ * 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 = _ref => {
+  let {
+    forwardRef,
+    children,
+    className,
+    contentClassName,
+    controlsClassName,
+    controls,
+    dark,
+    header,
+    logo,
+    stickyHeader,
+    title,
+    titleClassName,
+    titleComponent: TitleComponent = "h4",
+    titleId,
+    toggle,
+    wrapContent = true,
+    ...props
+  } = _ref;
+  return /*#__PURE__*/_react.default.createElement("div", _extends({}, props, {
+    className: (0, _classnames.default)("p-panel", className, {
+      "is-dark": dark
+    }),
+    ref: forwardRef
+  }), logo || title || controls || toggle ? /*#__PURE__*/_react.default.createElement("div", {
+    className: (0, _classnames.default)("p-panel__header", {
+      "is-sticky": stickyHeader
+    })
+  }, logo ? generateLogo(logo) : /*#__PURE__*/_react.default.createElement(TitleComponent, {
+    className: (0, _classnames.default)("p-panel__title", titleClassName),
+    id: titleId
+  }, title), /*#__PURE__*/_react.default.createElement("div", {
+    className: (0, _classnames.default)("p-panel__controls", controlsClassName)
+  }, toggle ? /*#__PURE__*/_react.default.createElement("span", {
+    role: "button",
+    tabIndex: 0,
+    className: "p-panel__toggle",
+    onClick: () => toggle.onClick(),
+    onKeyDown: () => toggle.onClick()
+  }, toggle.label) : null, controls)) : header, children && wrapContent ? /*#__PURE__*/_react.default.createElement("div", {
+    className: (0, _classnames.default)("p-panel__content", contentClassName)
+  }, children) : children);
+};
+var _default = exports.default = Panel;

package/dist/components/Panel/Panel.stories.d.ts

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import Panel from "./Panel";
+declare const meta: Meta<typeof Panel>;
+export default meta;
+type Story = StoryObj<typeof Panel>;
+export declare const Default: Story;
+export declare const Header: Story;
+/**
+ * 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 declare const Logo: Story;
+/**
+ * If the default header does not meet your needs then a `ReactNode` can be
+ * passed to the `header` prop to replace the header.
+ */
+export declare const CustomHeader: Story;

package/dist/components/Panel/Panel.stories.js

@@ -0,0 +1,60 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = exports.Logo = exports.Header = exports.Default = exports.CustomHeader = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _Panel = _interopRequireDefault(require("./Panel"));
+var _Button = _interopRequireDefault(require("../Button"));
+var _Icon = _interopRequireDefault(require("../Icon"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+const meta = {
+  component: _Panel.default,
+  tags: ["autodocs"]
+};
+var _default = exports.default = meta;
+const Default = exports.Default = {
+  args: {
+    children: "Panel content",
+    title: "Panel"
+  }
+};
+const Header = exports.Header = {
+  args: {
+    controls: /*#__PURE__*/_react.default.createElement(_Button.default, {
+      appearance: "positive"
+    }, /*#__PURE__*/_react.default.createElement(_Icon.default, {
+      name: "plus",
+      light: true
+    }), " Create"),
+    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.
+ */
+const Logo = exports.Logo = {
+  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.
+ */
+const CustomHeader = exports.CustomHeader = {
+  args: {
+    header: /*#__PURE__*/_react.default.createElement("div", {
+      className: "p-panel__header"
+    }, "This header replaces the entire header area")
+  }
+};

package/dist/components/Panel/index.d.ts

@@ -0,0 +1 @@
+export { default, type Props as PanelProps, type LogoDefaultElement as PanelLogoDefaultElement, } from "./Panel";

package/dist/components/Panel/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "default", {
+  enumerable: true,
+  get: function () {
+    return _Panel.default;
+  }
+});
+var _Panel = _interopRequireDefault(require("./Panel"));
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export { default as Notification, NotificationSeverity, } from "./components/Not
 export { NotificationConsumer, NotificationProvider, useNotify, info, success, failure, queue, } 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";
@@ -82,6 +83,7 @@ export type { NotificationProps } from "./components/Notification";
 export type { NotificationAction, NotificationType, QueuedNotification, NotificationHelper, } 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";

package/dist/index.js

@@ -46,6 +46,7 @@ var _exportNames = {
   queue: true,
   LoginPageLayout: true,
   Pagination: true,
+  Panel: true,
   PasswordToggle: true,
   RadioInput: true,
   Row: true,
@@ -302,6 +303,12 @@ Object.defineProperty(exports, "Pagination", {
     return _Pagination.default;
   }
 });
+Object.defineProperty(exports, "Panel", {
+  enumerable: true,
+  get: function () {
+    return _Panel.default;
+  }
+});
 Object.defineProperty(exports, "PasswordToggle", {
   enumerable: true,
   get: function () {
@@ -574,6 +581,7 @@ var _Notification = _interopRequireWildcard(require("./components/Notification")
 var _NotificationProvider = require("./components/NotificationProvider");
 var _LoginPageLayout = _interopRequireDefault(require("./components/LoginPageLayout"));
 var _Pagination = _interopRequireDefault(require("./components/Pagination"));
+var _Panel = _interopRequireDefault(require("./components/Panel"));
 var _PasswordToggle = _interopRequireDefault(require("./components/PasswordToggle"));
 var _RadioInput = _interopRequireDefault(require("./components/RadioInput"));
 var _Row = _interopRequireDefault(require("./components/Row"));

package/dist/types/index.d.ts

@@ -35,3 +35,4 @@ export type TSFixMe = any;
  * defined in EnumLike.
  */
 export type ValueOf<T> = T[keyof T];
+export type ExclusiveProps<A, B> = (A & Partial<Record<keyof B, never>>) | (B & Partial<Record<keyof A, never>>);

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import { NavLink, NavLinkAnchor, NavLinkButton } from "./components/Navigation";
+import { ReactNode } from "react";
 export declare const IS_DEV: boolean;
 /**
  * Find substring and wrap in <strong /> tag
@@ -20,3 +21,7 @@ export declare const isNavigationAnchor: (link: NavLink) => link is NavLinkAncho
  * @param link - The navigation item.
  */
 export declare const isNavigationButton: (link: NavLink) => link is NavLinkButton;
+/**
+ * A typeguard for whether an element is a ReactNode.
+ */
+export declare const isReactNode: (element: unknown) => element is ReactNode;

package/dist/utils.js

@@ -3,7 +3,8 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.isNavigationButton = exports.isNavigationAnchor = exports.highlightSubString = exports.IS_DEV = void 0;
+exports.isReactNode = exports.isNavigationButton = exports.isNavigationAnchor = exports.highlightSubString = exports.IS_DEV = void 0;
+var _react = require("react");
 const IS_DEV = exports.IS_DEV = process.env.NODE_ENV === "development";
 
 /**
@@ -40,4 +41,10 @@ const isNavigationAnchor = link => !!link.url;
  */
 exports.isNavigationAnchor = isNavigationAnchor;
 const isNavigationButton = link => !link.url;
-exports.isNavigationButton = isNavigationButton;
+
+/**
+ * A typeguard for whether an element is a ReactNode.
+ */
+exports.isNavigationButton = isNavigationButton;
+const isReactNode = element => /*#__PURE__*/(0, _react.isValidElement)(element);
+exports.isReactNode = isReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@canonical/react-components",
-  "version": "0.56.0",
+  "version": "0.57.0",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "author": "Huw Wilkins <huw.wilkins@canonical.com>",