@canonical/react-components 1.6.0 → 1.7.0

package/dist/esm/components/Navigation/types.d.ts

@@ -0,0 +1,64 @@
+import type { HTMLAttributes, HTMLProps, ReactNode } from "react";
+import { PropsWithSpread } from "../../types";
+export type NavLinkBase = {
+    /**
+     * Whether this nav item is currently selected.
+     */
+    isSelected?: boolean;
+    /**
+     * The label of the link.
+     */
+    label: ReactNode;
+    /**
+     * The URL of the link.
+     */
+    url?: string;
+};
+export type NavLinkAnchor = PropsWithSpread<NavLinkBase & {
+    url: string;
+}, HTMLAttributes<HTMLAnchorElement>>;
+export type NavLinkButton = PropsWithSpread<NavLinkBase & {
+    url?: never;
+}, HTMLAttributes<HTMLButtonElement>>;
+export type NavLink = NavLinkAnchor | NavLinkButton;
+export type NavMenu = {
+    /**
+     * Whether to align the dropdown to the right edge of the navigation item.
+     */
+    alignRight?: boolean;
+    /**
+     * The links to appear in the dropdown.
+     */
+    items: NavLink[];
+    /**
+     * The label of the navigation item that opens the menu.
+     */
+    label: string;
+};
+/**
+ * Navigation items which can be either a link or a menu containing links.
+ */
+export type NavItem = NavLink | NavMenu;
+/**
+ * A function that can be used to generate link elements when you don't want to
+ * use a standard HTML anchor.
+ */
+export type GenerateLink = (item: NavLink) => ReactNode;
+export type LogoProps = PropsWithSpread<{
+    /**
+     * An icon to display in the tag.
+     */
+    icon?: ReactNode;
+    /**
+     * The logo image source URL.
+     */
+    src?: string;
+    /**
+     * The site's title.
+     */
+    title: string;
+    /**
+     * The URL to navigate to when the logo is clicked.
+     */
+    url: string;
+}, HTMLProps<HTMLDivElement>>;

package/dist/esm/components/Navigation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/components/Notification/Notification.d.ts

@@ -0,0 +1,110 @@
+import { ElementType } from "react";
+import type { HTMLProps, ReactNode } from "react";
+import type { ClassName, PropsWithSpread, ValueOf } from "../../types";
+export declare enum Label {
+    Close = "Close notification"
+}
+export declare const NotificationSeverity: {
+    readonly CAUTION: "caution";
+    readonly INFORMATION: "information";
+    readonly NEGATIVE: "negative";
+    readonly POSITIVE: "positive";
+};
+export declare const DefaultTitles: {
+    caution: string;
+    information: string;
+    negative: string;
+    positive: string;
+};
+type NotificationAction = {
+    label: string;
+    onClick: () => void;
+};
+/**
+ * The props for the Notification component.
+ */
+export type Props = PropsWithSpread<{
+    /**
+     * A list of up to two actions that the notification can perform.
+     */
+    actions?: NotificationAction[];
+    /**
+     * Whether the notification should not have a border.
+     */
+    borderless?: boolean;
+    /**
+     * The notification message content.
+     */
+    children?: ReactNode;
+    /**
+     * Optional class(es) to apply to the parent notification element.
+     */
+    className?: ClassName;
+    /**
+     * **Deprecated**. Use `onDismiss` instead.
+     */
+    close?: never;
+    /**
+     * Whether the title should display inline with the message.
+     */
+    inline?: boolean;
+    /**
+     * The function to run when dismissing/closing the notification.
+     */
+    onDismiss?: () => void;
+    /**
+     * The severity of the notification.
+     */
+    severity?: ValueOf<typeof NotificationSeverity>;
+    /**
+     * **Deprecated**. Use `title` instead.
+     */
+    status?: never;
+    /**
+     * The amount of time (in ms) until the notification is automatically dismissed.
+     */
+    timeout?: number;
+    /**
+     * A relevant timestamp for the notification, e.g. when it was created.
+     */
+    timestamp?: ReactNode;
+    /**
+     * The title of the notification.
+     */
+    title?: ReactNode;
+    /**
+     * Optional element or component to use for the title.
+     */
+    titleElement?: ElementType;
+    /**
+     * **Deprecated**. Use `severity` instead.
+     */
+    type?: never;
+}, HTMLProps<HTMLDivElement>>;
+/**
+This is a [React](https://reactjs.org/) component for the Vanilla [Notification](https://docs.vanillaframework.io/patterns/notification/).
+
+Notifications are used to display global information, our notification variants consist of default, caution, negative or positive.
+
+The `NotificationProvider` component can be used to manage the notification state globally. Wrap your application components with it and then in any child component you can get the helper with `const notify = useNotify()` to easily trigger notifications:
+
+* `notify.info("You should keep this in mind")`
+* `notify.failure("Error when fooing a bar", errorObjectFromCatch)`
+* `notify.success("The bar was foo'd", "Success")`
+
+The `NotificationConsumer` component can be used to display notifications. It will automatically display any notifications that are added to the `NotificationProvider` state.
+
+The Notification API has changed since v0.18 in order to support new variants
+and align with our component prop naming conventions.
+
+| Deprecated prop names | Replaced by |
+| --------------------- | ----------- |
+| `type`                | `severity`  |
+| `status`              | `title`     |
+| `close`               | `onDismiss` |
+
+The `notificationTypes` const has also been replaced with `NotificationSeverity`
+to reflect the new prop name.
+ */
+declare const Notification: ({ actions, borderless, children, className, close, inline, onDismiss, severity, status, timeout, timestamp, title, titleElement: TitleComponent, type, ...props }: Props) => JSX.Element;
+export default Notification;

package/dist/esm/components/Notification/Notification.js

@@ -0,0 +1,119 @@
+var _excluded = ["actions", "borderless", "children", "className", "close", "inline", "onDismiss", "severity", "status", "timeout", "timestamp", "title", "titleElement", "type"];
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], t.indexOf(o) >= 0 || {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (e.indexOf(n) >= 0) continue; t[n] = r[n]; } return t; }
+import classNames from "classnames";
+import React, { useEffect, useRef } from "react";
+import Button, { ButtonAppearance } from "../Button";
+import { IS_DEV } from "../../utils";
+export var Label = /*#__PURE__*/function (Label) {
+  Label["Close"] = "Close notification";
+  return Label;
+}({});
+export var NotificationSeverity = {
+  CAUTION: "caution",
+  INFORMATION: "information",
+  NEGATIVE: "negative",
+  POSITIVE: "positive"
+};
+export var DefaultTitles = {
+  [NotificationSeverity.CAUTION]: "Warning",
+  [NotificationSeverity.INFORMATION]: "Info",
+  [NotificationSeverity.NEGATIVE]: "Error",
+  [NotificationSeverity.POSITIVE]: "Success"
+};
+
+/**
+ * The props for the Notification component.
+ */
+
+/**
+This is a [React](https://reactjs.org/) component for the Vanilla [Notification](https://docs.vanillaframework.io/patterns/notification/).
+
+Notifications are used to display global information, our notification variants consist of default, caution, negative or positive.
+
+The `NotificationProvider` component can be used to manage the notification state globally. Wrap your application components with it and then in any child component you can get the helper with `const notify = useNotify()` to easily trigger notifications:
+
+* `notify.info("You should keep this in mind")`
+* `notify.failure("Error when fooing a bar", errorObjectFromCatch)`
+* `notify.success("The bar was foo'd", "Success")`
+
+The `NotificationConsumer` component can be used to display notifications. It will automatically display any notifications that are added to the `NotificationProvider` state.
+
+The Notification API has changed since v0.18 in order to support new variants
+and align with our component prop naming conventions.
+
+| Deprecated prop names | Replaced by |
+| --------------------- | ----------- |
+| `type`                | `severity`  |
+| `status`              | `title`     |
+| `close`               | `onDismiss` |
+
+The `notificationTypes` const has also been replaced with `NotificationSeverity`
+to reflect the new prop name.
+ */
+var Notification = _ref => {
+  var {
+      actions,
+      borderless = false,
+      children,
+      className,
+      close,
+      inline = false,
+      onDismiss,
+      severity = NotificationSeverity.INFORMATION,
+      status,
+      timeout,
+      timestamp,
+      title,
+      titleElement: TitleComponent = "h5",
+      type
+    } = _ref,
+    props = _objectWithoutProperties(_ref, _excluded);
+  var timeoutId = useRef(null);
+  var hasActions = (actions === null || actions === void 0 ? void 0 : actions.length) > 0;
+  var showMeta = !!timestamp || hasActions;
+  useEffect(() => {
+    if (timeout && onDismiss) {
+      timeoutId.current = setTimeout(() => onDismiss(), timeout);
+    }
+    return () => clearTimeout(timeoutId.current);
+  }, [onDismiss, timeout]);
+  if (IS_DEV && (close || status || type)) {
+    console.warn("The Notification component is using deprecated props. Refer to the deprecated list for details: https://canonical.github.io/react-components/?path=/docs/notification--information#deprecated");
+  }
+  return /*#__PURE__*/React.createElement("div", _extends({
+    className: classNames(className, {
+      ["p-notification--".concat(severity)]: !!severity,
+      "p-notification": !severity,
+      "is-borderless": borderless,
+      "is-inline": inline
+    })
+  }, props), /*#__PURE__*/React.createElement("div", {
+    className: "p-notification__content"
+  }, title && /*#__PURE__*/React.createElement(TitleComponent, {
+    className: "p-notification__title",
+    "data-testid": "notification-title"
+  }, title), inline && /*#__PURE__*/React.createElement(React.Fragment, null, "\u2002"), /*#__PURE__*/React.createElement("p", {
+    className: "p-notification__message"
+  }, children), onDismiss && /*#__PURE__*/React.createElement("button", {
+    className: "p-notification__close",
+    "data-testid": "notification-close-button",
+    onClick: onDismiss
+  }, Label.Close)), showMeta && /*#__PURE__*/React.createElement("div", {
+    className: "p-notification__meta",
+    "data-testid": "notification-meta"
+  }, timestamp && /*#__PURE__*/React.createElement("span", {
+    className: "p-notification__timestamp",
+    "data-testid": "notification-timestamp"
+  }, timestamp), hasActions ? /*#__PURE__*/React.createElement("div", {
+    className: "p-notification__actions"
+  }, actions.map((action, i) => /*#__PURE__*/React.createElement(Button, {
+    appearance: ButtonAppearance.LINK,
+    className: "p-notification__action",
+    "data-testid": "notification-action",
+    key: "".concat(action.label, "-").concat(i),
+    onClick: action.onClick
+  }, action.label))) : null));
+};
+export default Notification;

package/dist/esm/components/Notification/Notification.stories.d.ts

@@ -0,0 +1,45 @@
+import { Meta, StoryObj } from "@storybook/react";
+import Notification from "./Notification";
+declare const meta: Meta<typeof Notification>;
+export default meta;
+type Story = StoryObj<typeof Notification>;
+/**
+ * The information severity should be used to convey an information message.
+ */
+export declare const Information: Story;
+/**
+ * The caution severity should be used to convey information that is not critical but the user should be aware of.
+ */
+export declare const Caution: Story;
+/**
+ * The negative severity should be used to convey information that is critical and the user should take action.
+ */
+export declare const Negative: Story;
+/**
+ * The positive severity should be used to convey success or completion.
+ */
+export declare const Positive: Story;
+/**
+ * When vertical space is limited, you can use the inline variant.
+ */
+export declare const Inline: Story;
+/**
+ * In cases where a notification sits inside another component, such as a table cell or a card, it may be useful to remove the outer border and highlight bar.
+ */
+export declare const Borderless: Story;
+/**
+ * Actions will appear below the notification message.
+ */
+export declare const Actions: Story;
+/**
+ * Notifications that can be dismissed should be given an onDismiss function.
+ */
+export declare const Dismissible: Story;
+/**
+ * Notifications can be automatically dismissed after a timeout interval.
+ */
+export declare const Timeout: Story;
+/**
+ * For notifications in which recency is important, you can include a section for time.
+ */
+export declare const Timestamp: Story;

package/dist/esm/components/Notification/Notification.stories.js

@@ -0,0 +1,194 @@
+import React from "react";
+import { useState } from "react";
+import Notification, { NotificationSeverity } from "./Notification";
+var meta = {
+  component: Notification,
+  tags: ["autodocs"],
+  argTypes: {
+    borderless: {
+      control: {
+        type: "boolean"
+      }
+    },
+    children: {
+      control: {
+        type: "text"
+      }
+    },
+    inline: {
+      control: {
+        type: "boolean"
+      }
+    },
+    severity: {
+      control: {
+        type: "radio"
+      },
+      options: Object.values(NotificationSeverity)
+    },
+    timestamp: {
+      control: {
+        type: "text"
+      }
+    },
+    title: {
+      control: {
+        type: "text"
+      }
+    }
+  },
+  args: {
+    borderless: false,
+    inline: false,
+    severity: NotificationSeverity.INFORMATION
+  }
+};
+export default meta;
+/**
+ * The information severity should be used to convey an information message.
+ */
+export var Information = {
+  name: "Information",
+  args: {
+    children: "Anyone with access can view your invited users.",
+    severity: "information",
+    title: "Permissions changed"
+  }
+};
+
+/**
+ * The caution severity should be used to convey information that is not critical but the user should be aware of.
+ */
+export var Caution = {
+  name: "Caution",
+  args: {
+    children: "Custom storage configuration is only supported on Ubuntu, CentOS and RHEL.",
+    severity: "caution",
+    title: "Blocked"
+  }
+};
+
+/**
+ * The negative severity should be used to convey information that is critical and the user should take action.
+ */
+export var Negative = {
+  name: "Negative",
+  args: {
+    children: "Node must be connected to a network.",
+    severity: "negative",
+    title: "Error"
+  }
+};
+
+/**
+ * The positive severity should be used to convey success or completion.
+ */
+export var Positive = {
+  name: "Positive",
+  args: {
+    children: "Code successfully reformatted.",
+    severity: "positive",
+    title: "Success"
+  }
+};
+
+/**
+ * When vertical space is limited, you can use the inline variant.
+ */
+export var Inline = {
+  name: "Inline",
+  args: {
+    children: "Not enough space.",
+    inline: true,
+    severity: "negative",
+    title: "Error:"
+  }
+};
+
+/**
+ * In cases where a notification sits inside another component, such as a table cell or a card, it may be useful to remove the outer border and highlight bar.
+ */
+export var Borderless = {
+  name: "Borderless",
+  args: {
+    borderless: true,
+    children: "Only 8GB storage remaining.",
+    severity: "caution",
+    title: "Warning"
+  }
+};
+
+/**
+ * Actions will appear below the notification message.
+ */
+export var Actions = {
+  name: "Actions",
+  args: {
+    actions: [{
+      label: "Action 1",
+      onClick: () => null
+    }, {
+      label: "Action 2",
+      onClick: () => null
+    }],
+    children: "Body lorem ipsum dolor sit amet consequiteor. Lorem ipsum dolor sit amet consequiteor.",
+    severity: "information",
+    title: "Title"
+  }
+};
+
+/**
+ * Notifications that can be dismissed should be given an onDismiss function.
+ */
+export var Dismissible = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var [show, setShow] = useState(true);
+    if (!show) {
+      return null;
+    }
+    return /*#__PURE__*/React.createElement(Notification, {
+      onDismiss: () => setShow(false),
+      title: "Dismissible"
+    }, "Click the dismiss button to get rid of me.");
+  },
+  name: "Dismissible"
+};
+
+/**
+ * Notifications can be automatically dismissed after a timeout interval.
+ */
+export var Timeout = {
+  render: () => {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var [show, setShow] = useState(true);
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    var [timer, setTimer] = useState(0);
+    if (!show) {
+      return null;
+    }
+    return /*#__PURE__*/React.createElement(Notification, {
+      actions: [{
+        label: "Start timer",
+        onClick: () => setTimer(3000)
+      }],
+      onDismiss: () => setShow(false),
+      timeout: timer,
+      title: "Timeout"
+    }, "Click the action to start a 3 second timer.");
+  },
+  name: "Timeout"
+};
+
+/**
+ * For notifications in which recency is important, you can include a section for time.
+ */
+export var Timestamp = {
+  name: "Timestamp",
+  args: {
+    children: "Body lorem ipsum dolor sit amet consequiteor. Lorem ipsum dolor sit amet consequiteor.",
+    severity: "information",
+    timestamp: "1h ago",
+    title: "Title"
+  }
+};

package/dist/esm/components/Notification/Notification.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/components/Notification/index.d.ts

@@ -0,0 +1,2 @@
+export { default, NotificationSeverity } from "./Notification";
+export type { Props as NotificationProps } from "./Notification";

package/dist/esm/components/Notification/index.js

@@ -0,0 +1 @@
+export { default, NotificationSeverity } from "./Notification";

package/dist/esm/components/NotificationProvider/NotificationProvider.d.ts

@@ -0,0 +1,5 @@
+import { FC } from "react";
+import { NotificationHelper, NotifyProviderProps } from "./types";
+export declare const NotificationProvider: FC<NotifyProviderProps>;
+export declare function useNotify(): NotificationHelper;
+export declare const NotificationConsumer: FC;

package/dist/esm/components/NotificationProvider/NotificationProvider.js

@@ -0,0 +1,83 @@
+import React, { createContext, useContext, useEffect, useRef, useState } from "react";
+import isEqual from "lodash/isEqual";
+import { info as _info, failure as _failure, success as _success, queue } from "./messageBuilder";
+import Notification, { DefaultTitles } from "../Notification/Notification";
+var NotifyContext = /*#__PURE__*/createContext({
+  notification: null,
+  clear: () => undefined,
+  failure: () => undefined,
+  success: () => undefined,
+  info: () => undefined,
+  queue: () => undefined,
+  setDeduplicated: () => undefined
+});
+export var NotificationProvider = _ref => {
+  var {
+    children,
+    state,
+    pathname
+  } = _ref;
+  var [notification, setNotification] = useState(null);
+  var clear = () => notification !== null && setNotification(null);
+  var setDeduplicated = value => {
+    if (!isEqual(value, notification)) {
+      setNotification(value);
+    }
+    return value;
+  };
+  useEffect(() => {
+    if (state !== null && state !== void 0 && state.queuedNotification) {
+      setDeduplicated(state.queuedNotification);
+      window.history.replaceState({}, "");
+    } else {
+      clear();
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state, pathname]);
+  var helper = {
+    notification,
+    clear,
+    queue,
+    failure: (title, error, message, actions) => setDeduplicated(_failure(title, error, message, actions)),
+    info: (message, title) => setDeduplicated(_info(message, title)),
+    success: (message, title) => setDeduplicated(_success(message, title)),
+    setDeduplicated
+  };
+  return /*#__PURE__*/React.createElement(NotifyContext.Provider, {
+    value: helper
+  }, children);
+};
+export function useNotify() {
+  return useContext(NotifyContext);
+}
+export var NotificationConsumer = () => {
+  var notify = useNotify();
+  var ref = useRef(null);
+  useEffect(() => {
+    var _ref$current;
+    if ((_ref$current = ref.current) !== null && _ref$current !== void 0 && _ref$current.hasAttribute("scrollIntoView")) {
+      ref.current.scrollIntoView({
+        behavior: "smooth",
+        block: "center",
+        inline: "start"
+      });
+    }
+  }, [notify.notification]);
+  if (!notify.notification) {
+    return null;
+  }
+  var {
+    actions,
+    title,
+    type,
+    message
+  } = notify.notification;
+  return /*#__PURE__*/React.createElement("div", {
+    ref: ref
+  }, /*#__PURE__*/React.createElement(Notification, {
+    title: title !== null && title !== void 0 ? title : DefaultTitles[type],
+    actions: actions,
+    severity: type,
+    onDismiss: notify.clear
+  }, message));
+};

package/dist/esm/components/NotificationProvider/NotificationProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/components/NotificationProvider/index.d.ts

@@ -0,0 +1,3 @@
+export { NotificationConsumer, NotificationProvider, useNotify, } from "./NotificationProvider";
+export { info, success, failure, queue } from "./messageBuilder";
+export type { NotificationAction, NotificationType, QueuedNotification, NotificationHelper, } from "./types";

package/dist/esm/components/NotificationProvider/index.js

@@ -0,0 +1,2 @@
+export { NotificationConsumer, NotificationProvider, useNotify } from "./NotificationProvider";
+export { info, success, failure, queue } from "./messageBuilder";

package/dist/esm/components/NotificationProvider/messageBuilder.d.ts

@@ -0,0 +1,6 @@
+import { NotificationAction, NotificationType, QueuedNotification } from "./types";
+import { ReactNode } from "react";
+export declare const queue: (notification: NotificationType) => QueuedNotification;
+export declare const info: (message: ReactNode, title?: string) => NotificationType;
+export declare const success: (message: ReactNode, title?: string) => NotificationType;
+export declare const failure: (title: string, error: unknown, message?: ReactNode, actions?: NotificationAction[]) => NotificationType;

package/dist/esm/components/NotificationProvider/messageBuilder.js

@@ -0,0 +1,31 @@
+import React from "react";
+import { NotificationSeverity } from "../Notification";
+export var queue = notification => {
+  return {
+    state: {
+      queuedNotification: notification
+    }
+  };
+};
+export var info = (message, title) => {
+  return {
+    message,
+    title,
+    type: NotificationSeverity.INFORMATION
+  };
+};
+export var success = (message, title) => {
+  return {
+    message,
+    title,
+    type: NotificationSeverity.POSITIVE
+  };
+};
+export var failure = (title, error, message, actions) => {
+  return {
+    actions,
+    message: error && error instanceof Error ? /*#__PURE__*/React.createElement(React.Fragment, null, message, " ", error.message) : message,
+    title,
+    type: NotificationSeverity.NEGATIVE
+  };
+};