@progressiveui/react 1.22.0

package/src/components/Item/Item.tsx

@@ -0,0 +1,134 @@
+import * as React from "react";
+import classNames from "classnames";
+import { ChevronRight } from "@progressiveui/icons-react";
+import useSettings from "../../hooks/useSettings";
+import { IIcon } from "../../utils";
+
+interface ItemProps extends Omit<React.ComponentPropsWithRef<"div">, "title"> {
+  /**
+   * Provide the title for the item contet
+   */
+  title?: React.ReactNode;
+  /**
+   * Provide the description for the item content
+   */
+  children?: React.ReactNode;
+  /**
+   * Provide the icon for the item content
+   */
+  icon?: React.ReactNode | IIcon;
+  /**
+   * Provide a kind to use different appearances.
+   */
+  kind?: "undefined" | "horizontal" | "large";
+  /**
+   * Provide a wrap to use different borders.
+   */
+  wrapper?: "undefined" | "sidebar" | "repeater";
+  /**
+   * Show an additional chevron icon on the right side
+   */
+  showAdditionalIcon?: boolean;
+  /**
+   * Additional content shown underneath the regular content (children)
+   */
+  subContent?: React.ReactNode;
+  /**
+   * Provide a hint to the item shown on the right bottom corner
+   */
+  hint?: React.ReactNode;
+  /**
+   * Enable the active state to the item
+   */
+  active?: boolean;
+  /**
+   * Provide additional info on the top right corner of the item
+   */
+  additional?: React.ReactNode;
+  /**
+   * Provide an image to the item
+   */
+  image?: React.ReactNode;
+  /**
+   * Disable the image to the item
+   */
+  noImage?: boolean;
+  /**
+   * Enable an unread state to the item
+   */
+  unread?: boolean;
+}
+/** The item component to show entries inside a list, like a sidebar or an overview page. */
+const Item: React.FC<ItemProps> = React.forwardRef(
+  (
+    {
+      active,
+      additional,
+      children,
+      className,
+      subContent,
+      image,
+      hint,
+      noImage,
+      unread,
+      showAdditionalIcon,
+      title,
+      kind = "large",
+      wrapper = "none",
+      ...other
+    },
+    ref
+  ) =>
+    //TODO:  ref
+    {
+      const { prefix } = useSettings();
+
+      const classes = classNames(
+        {
+          [`${prefix}--item`]: true,
+          [`${prefix}--item--${kind}`]: kind,
+          [`${prefix}--item--${wrapper}`]: wrapper,
+          [`${prefix}--item--active`]: active,
+          [`${prefix}--item--unread`]: unread,
+        },
+        className
+      );
+      return (
+        <div className={classes} {...other} ref={ref}>
+          {image ? (
+            <div className={`${prefix}--item__image`}>{image}</div>
+          ) : noImage ? (
+            <div
+              className={`${prefix}--item__image ${prefix}--item__image-empty`}
+            ></div>
+          ) : null}
+
+          {title && (
+            <div className={`${prefix}--item__title-wrapper`}>
+              <h2 className={`${prefix}--item__title`}>{title}</h2>
+            </div>
+          )}
+          {additional && (
+            <div className={`${prefix}--item__additional`}>
+              {additional}
+              {showAdditionalIcon && (
+                <ChevronRight className={`${prefix}--item__additional-icon`} />
+              )}
+            </div>
+          )}
+          {children && (
+            <div className={`${prefix}--item__text`}>{children}</div>
+          )}
+          {subContent && (
+            <div className={`${prefix}--item__sub-content`}>{subContent}</div>
+          )}
+          {hint && <div className={`${prefix}--item__hint`}>{hint}</div>}
+          {unread && <div className={`${prefix}--item__unread`} />}
+        </div>
+      );
+    }
+);
+
+Item.displayName = "Item";
+
+export default Item;

package/src/components/Item/README.mdx

@@ -0,0 +1,28 @@
+Empty states are a way to improve the user experience of your product, from onboarding to encouraging users to interact with your app. They are screens in your UI that are not yet full of information. That is to say, they will eventually have content on them when the user populates them.
+
+The component should usually cover the whole area of the section and have a slightly darker background than the regular content. It can be also used for large notification messages.
+
+### Types of empty states
+
+- **First use** – Occurs with a new product or service when there is still nothing to show, such as a new Evernote or Dropbox account.
+- **User cleared** – Occurs when users complete actions such as clearing their inbox or task list, and the result is an empty screen.
+- **Errors** – These occur when something goes wrong, or when there are issues such as a mobile phone going offline due to network problems.
+- **No results/No data** – Occurs when there is nothing to show. This can happen if someone performs a search and the query is empty or there isn’t data available to show (when filtering for a date-range that has no data for example).
+
+### When to use
+
+- ✓ Can be the case for a empty list table or search results
+- ✓ Cover the whole area where normally content would be displayed
+- ✓ Add personality by adding an illustration or icon (for example by using FontAwesome)
+- ✓ Tell your user to do something: provide a call-to-action button
+- ✓ Can be also used for large notification messages
+
+### Related
+
+[Button](?path=/docs/components-button--button-regular)
+
+### Reference
+
+[Breakfree Graphics Empty States – The Most Overlooked Aspect of UX](https://www.breakfreegraphics.com/design-blog/empty-states-the-most-overlooked-aspect-of-ux/)
+
+[justinmind Everything you need to know about empty state design](https://www.justinmind.com/blog/everything-you-need-to-know-about-empty-state-design/)

package/src/components/Item/index.ts

@@ -0,0 +1 @@
+export { default } from './Item';

package/src/components/Link/Link-test.e2e.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright IBM Corp. 2016, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import 'carbon-components/scss/components/link/_link.scss';
+import { Download16 } from '@carbon/icons-react';
+
+import React from 'react';
+import { mount } from '@cypress/react';
+import Link from '../Link';
+
+describe('Link', () => {
+  beforeEach(() => {
+    mount(
+      <>
+        <Link href="http://www.carbondesignsystem.com">Link</Link>
+        <Link href="http://www.carbondesignsystem.com" renderIcon={Download16}>
+          Download
+        </Link>
+      </>
+    );
+  });
+
+  it('should render', () => {
+    cy.findByText(/Link/).should('be.visible');
+
+    // snapshots should always be taken _after_ an assertion that
+    // a element/component should be visible. This is to ensure
+    // the DOM has settled and the element has fully loaded.
+    cy.percySnapshot();
+  });
+});

package/src/components/Link/Link-test.js

@@ -0,0 +1,115 @@
+/**
+ * Copyright IBM Corp. 2016, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import '@testing-library/jest-dom/extend-expect';
+import React from 'react';
+import Link from '../Link';
+import { shallow } from 'enzyme';
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, document } from 'window-or-global';
+import settings from '../../globals/js/settings';
+
+const { prefix } = settings;
+
+describe('Link', () => {
+  afterEach(cleanup);
+
+  describe('Renders as expected', () => {
+    const link = shallow(
+      <Link href="www.google.com" className="some-class">
+        A simple link
+      </Link>
+    );
+
+    it('should use the appropriate link class', () => {
+      expect(link.name()).toEqual('a');
+      expect(link.hasClass(`${prefix}--link`)).toEqual(true);
+    });
+
+    it('should inherit the href property', () => {
+      expect(link.props().href).toEqual('www.google.com');
+    });
+
+    it('should include child content', () => {
+      expect(link.text()).toEqual('A simple link');
+    });
+
+    it('should all for custom classes to be applied', () => {
+      expect(link.hasClass('some-class')).toEqual(true);
+    });
+
+    it('should support disabled link', () => {
+      link.setProps({ disabled: true });
+      expect(link.name()).toEqual('p');
+      expect(link.hasClass(`${prefix}--link--disabled`)).toEqual(true);
+    });
+
+    it('should support inline link', () => {
+      link.setProps({ inline: true });
+      expect(link.hasClass(`${prefix}--link--inline`)).toEqual(true);
+    });
+    it('should add support for different link sizes', () => {
+      link.setProps({ size: 'lg' });
+      expect(link.hasClass(`${prefix}--link--lg`)).toEqual(true);
+    });
+    it('should add rel="noopener" automatically if target="_blank"', () => {
+      link.setProps({ target: '_blank' });
+      expect(link.props().rel).toEqual('noopener');
+    });
+  });
+
+  // describe('automated verification testing', () => {
+  //   it('should have no Axe violations', async () => {
+  //     render(
+  //       <Link href="/" className="some-class">
+  //         A simple link
+  //       </Link>
+  //     );
+
+  //     await expect(screen.getByText('A simple link')).toHaveNoAxeViolations();
+  //   });
+
+  //   it('should have no Accessibility Checker violations', async () => {
+  //     render(
+  //       <main>
+  //         <Link href="/" className="some-class">
+  //           A simple link
+  //         </Link>
+  //       </main>
+  //     );
+
+  //     await expect(screen.getByText('A simple link')).toHaveNoACViolations(
+  //       'Link'
+  //     );
+  //   });
+  // });
+
+  describe('keyboard support', () => {
+    it('should receive keyboard focus', () => {
+      render(
+        <Link href="/" className="some-class">
+          A simple link
+        </Link>
+      );
+
+      expect(document.body).toHaveFocus();
+      userEvent.tab();
+      expect(screen.getByText('A simple link')).toHaveFocus();
+    });
+
+    it('should not receive keyboard focus when disabled', () => {
+      render(
+        <Link href="/" disabled className="some-class">
+          A simple link
+        </Link>
+      );
+      expect(document.body).toHaveFocus();
+      userEvent.tab();
+      expect(document.body).toHaveFocus();
+    });
+  });
+});

package/src/components/Link/Link.mdx

@@ -0,0 +1,41 @@
+import { Props, Preview, Story } from '@storybook/addon-docs/blocks';
+
+# Link
+
+[Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Link)
+ | 
+[Usage guidelines](https://www.carbondesignsystem.com/components/link/usage)
+ | 
+[Accessibility](https://www.carbondesignsystem.com/components/link/accessibility)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Component API](#component-api)
+- [Feedback](#feedback)
+
+## Overview
+
+Links are used as navigational elements and can be used on their own or inline
+with text. They provide a lightweight option for navigation but like other
+interactive elements, too many links will clutter a page and make it difficult
+for users to identify their next steps. This is especially true for inline
+links, which should be used sparingly.
+
+<Preview>
+  <Story id="components-link--default" />
+</Preview>
+
+## Component API
+
+<Props />
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions on Slack,
+or updating this file on
+[GitHub](https://github.com/carbon-design-system/carbon/edit/main/packages/react/src/components/Link/Link.mdx).
+
+```
+
+```

package/src/components/Link/Link.stories.tsx

@@ -0,0 +1,95 @@
+import React from "react";
+import Link from ".";
+
+export default {
+  title: "Components/UI Elements/Link",
+  component: Link,
+  parameters: {
+    componentSubtitle: "Component",
+    status: "released",
+  },
+};
+
+export const LinkDefault = (args) => <Link {...args} />;
+
+LinkDefault.args = { children: "WFP Homepage", href: "https://www.wfp.org" };
+
+export const States = (args) => (
+  <>
+    <Link {...args} className="wfp--link">
+      :default
+    </Link>
+    <Link {...args} className="wfp--link--hover">
+      :hover
+    </Link>
+    <Link {...args} className="wfp--link--focus">
+      :focus
+    </Link>
+    <Link {...args} className="wfp--link--active">
+      :active
+    </Link>
+    <Link {...args} className="wfp--link--visited">
+      :visited
+    </Link>
+    <Link {...args} disabled>
+      :disabled
+    </Link>
+  </>
+);
+
+States.args = { ...LinkDefault.args, style: { marginRight: "1rem" } };
+
+States.story = {
+  parameters: {
+    docs: {
+      storyDescription: `The link component only uses minimalistic styles to indicate different states. By default, the link component does not use a visited style. Visited links indicate that a user has already opened the link so they can be a helpful indicator during task completion. Visited styles should be used sparingly because they often clutter the the page and add further visual noise as users are trying to navigate a product. They can be used if it is important that a user knows they have already clicked on a link.
+      `,
+    },
+  },
+};
+
+export const LinkSolid = (args) => (
+  <div
+    style={{
+      width: "100%",
+      height: "70px",
+      backgroundColor: "#04193b",
+      padding: "20px",
+    }}
+  >
+    <Link {...args} className="wfp--link--solid">
+      :default
+    </Link>
+    <Link {...args} className="wfp--link--solid--hover">
+      :hover
+    </Link>
+
+    <Link {...args} className="wfp--link--solid--active">
+      :active
+    </Link>
+    <Link {...args} className="wfp--link--solid--focus">
+      :focus
+    </Link>
+    <Link {...args} className="wfp--link--solid--visited">
+      :visited
+    </Link>
+    <Link {...args} className="wfp--link--solid" disabled>
+      :disabled
+    </Link>
+  </div>
+);
+
+LinkSolid.args = {
+  ...LinkDefault.args,
+  linkSolid: true,
+  style: { marginRight: "1rem" },
+};
+
+LinkSolid.story = {
+  parameters: {
+    docs: {
+      storyDescription: `The link component only uses minimalistic styles to indicate different states. By default, the link component does not use a visited style. Visited links indicate that a user has already opened the link so they can be a helpful indicator during task completion. Visited styles should be used sparingly because they often clutter the the page and add further visual noise as users are trying to navigate a product. They can be used if it is important that a user knows they have already clicked on a link.
+      `,
+    },
+  },
+};

package/src/components/Link/Link.test.tsx

@@ -0,0 +1,100 @@
+//import React from "react";
+import "@testing-library/jest-dom";
+import { render, screen } from "@testing-library/react";
+// import userEvent from "@testing-library/user-event";
+import Link from "./Link";
+
+describe("Link Component", () => {
+  // Test basic rendering
+  it("renders a link", () => {
+    render(<Link href="https://example.com">Visit Example</Link>);
+    expect(screen.getByRole("link")).toHaveTextContent("Visit Example");
+    expect(screen.getByRole("link")).toHaveAttribute(
+      "href",
+      "https://example.com"
+    );
+  });
+
+  // Test disabled link
+  it("renders a disabled link", () => {
+    render(<Link disabled>Disabled Link</Link>);
+    expect(screen.getByText("Disabled Link")).toHaveAttribute(
+      "aria-disabled",
+      "true"
+    );
+  });
+
+  // Test inline link
+  it("renders an inline link", () => {
+    render(<Link inline>Inline Link</Link>);
+    expect(screen.getByText("Inline Link")).toHaveClass("wfp--link--inline");
+  });
+
+  // Test visited link
+  it("renders a visited link", () => {
+    render(<Link visited>Visited Link</Link>);
+    expect(screen.getByText("Visited Link")).toHaveClass("wfp--link--visited");
+  });
+
+  // Test different sizes of links
+  it("renders a small link", () => {
+    render(<Link size="sm">Small Link</Link>);
+    expect(screen.getByText("Small Link")).toHaveClass("wfp--link--sm");
+  });
+
+  it("renders a medium link", () => {
+    render(<Link size="md">Medium Link</Link>);
+    expect(screen.getByText("Medium Link")).toHaveClass("wfp--link--md");
+  });
+
+  it("renders a large link", () => {
+    render(<Link size="lg">Large Link</Link>);
+    expect(screen.getByText("Large Link")).toHaveClass("wfp--link--lg");
+  });
+
+  // Test link with icon
+  it("renders a link with an icon", () => {
+    const MockIcon = () => <svg data-testid="mock-icon"></svg>;
+    render(<Link icon={<MockIcon />}>Link with Icon</Link>);
+    expect(screen.getByTestId("mock-icon")).toBeInTheDocument();
+    expect(screen.getByText("Link with Icon")).toBeInTheDocument();
+  });
+
+  // Test custom class name
+  it("applies custom class names", () => {
+    const customClass = "my-custom-class";
+    render(<Link className={customClass}>Custom Class Link</Link>);
+    expect(screen.getByText("Custom Class Link")).toHaveClass(customClass);
+  });
+
+  // Test keyboard interaction
+  /*
+  TODO: Fix this test https://github.com/testing-library/user-event/issues/820
+  it("handles keyboard events", () => {
+    render(<Link href="https://example.com">Keyboard Link</Link>);
+    userEvent.tab();
+    expect(screen.getByText("Keyboard Link")).toHaveFocus();
+  });
+  */
+
+  // Test rel attribute for security when target is "_blank"
+  it("adds rel='noopener' when target='_blank'", () => {
+    render(
+      <Link href="https://example.com" target="_blank">
+        External Link
+      </Link>
+    );
+    expect(screen.getByText("External Link")).toHaveAttribute(
+      "rel",
+      "noopener"
+    );
+  });
+
+  // Snapshot test
+  it("matches snapshot", () => {
+    const { asFragment } = render(
+      <Link href="https://example.com">Snapshot Link</Link>
+    );
+    expect(asFragment()).toMatchSnapshot();
+  });
+});

package/src/components/Link/Link.tsx

@@ -0,0 +1,91 @@
+import * as React from "react";
+import classNames from "classnames";
+import useSettings from "../../hooks/useSettings";
+
+export interface LinkProps extends React.ComponentPropsWithRef<"a"> {
+  /**
+   * Provide the content for the link element
+   */
+  children?: React.ReactNode;
+  /**
+   * Adds an underline to the link element to better indicate that it is clickable in continuous text. @design
+   */
+  inline?: boolean;
+  /**
+   * Disables the link element. @design
+   */
+  disabled?: boolean;
+  /**
+   * Provide the href for the link element
+   */
+  href?: string;
+  /**
+   * Indicates that the link has been visited.
+   */
+  visited?: boolean;
+  /**
+   * Choose a size for the link element @design
+   */
+  size?: "sm" | "md" | "lg";
+  /**
+   * Use a solid prop for link element on a solid background @design
+   */
+  linkSolid?: boolean;
+  /**
+   * Use an icon with the link element @design
+   */
+  icon?: React.ReactNode | React.ComponentType | React.ElementType;
+}
+
+export const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(
+  function Link(props, ref) {
+    const {
+      children,
+      className,
+      href,
+      disabled,
+      inline,
+      visited,
+      icon,
+      size,
+      linkSolid,
+      ...other
+    } = props;
+
+    const { prefix } = useSettings();
+
+    const classes = classNames(`${prefix}--link`, className, {
+      [`${prefix}--link--disabled`]: disabled,
+      [`${prefix}--link--inline`]: inline,
+      [`${prefix}--link--visited`]: visited,
+      [`${prefix}--link--${size}`]: size,
+      [`${prefix}--link--icon`]: icon,
+      [`${prefix}--link--solid`]: linkSolid,
+    });
+
+    const rel = other.target === "_blank" ? "noopener" : undefined;
+
+    const IconAsComponent = icon as React.ComponentType<any>;
+    return (
+      <a
+        href={disabled ? undefined : href}
+        className={classes}
+        rel={rel}
+        ref={ref}
+        aria-disabled={disabled}
+        {...other}
+      >
+        {children}
+        {icon && React.isValidElement(icon) ? (
+          <span className={`${prefix}--link__icon`}>{icon}</span>
+        ) : icon ? (
+          <IconAsComponent />
+        ) : null}
+      </a>
+    );
+  }
+);
+
+Link.displayName = "Link";
+
+export default Link;

package/src/components/Link/README.mdx

@@ -0,0 +1,35 @@
+Links are typically used as a means of navigation either within the application, to a place outside, or to a resource. For anything else, especially things that change data and actions, you should be using a `button`.
+Links can have the same properties as a regular `<a>`-element.
+
+Links is based on a fork from [Carbon Components](https://www.carbondesignsystem.com/components/link/code)
+
+### When to use
+
+- ✓ Use text for links rather than graphics or icons.
+- ✓ Links should be three words or less.
+- ✓ Text should be consistent with the title of the intended destination.
+- ✓ Navigate to a different page within the application
+- ✓ Navigate to an entirely different site
+- ✓ Jump to an element on the same page
+- ✓ Link to emails or phone numbers
+
+### When not to use
+
+- ✗ Avoid the term “click here“, “other links“ to “here,” or the web address itself. Instead, use a meaningful descriptive label for the link, and match the destination site name.
+- ✗ Use a button instead of a link for actions that will change data or manipulate how it is displayed, change a state, or trigger an action. Buttons should never be used for navigational actions.
+
+### Use with react-router
+
+Use the Link styling by adding the className `wfp--link` to `<NavLink />`
+
+```js
+<NavLink className="wfp--link">Link</NavLink>
+```
+
+### Related
+
+[Button](?path=/docs/components-button--button-regular)
+
+### Reference
+
+[Carbon Design System Usage for Link](https://www.carbondesignsystem.com/components/link/usage)