@node-core/ui-components 1.0.1-a459447336d99556960d6f9e1c997327b29e4974 → 1.0.1-ab0ba1dcb1d91392c44e91b1e74e9f565e460543

package/src/Common/BasePagination/useGetPageElements.tsx

@@ -0,0 +1,132 @@
+import type { ComponentProps } from 'react';
+
+import type BasePagination from '#ui/Common/BasePagination';
+import Ellipsis from '#ui/Common/BasePagination/Ellipsis';
+import type { PaginationListItemProps } from '#ui/Common/BasePagination/PaginationListItem';
+import PaginationListItem from '#ui/Common/BasePagination/PaginationListItem';
+import type { LinkLike } from '#ui/types';
+
+const parsePages = (
+  pages: ComponentProps<typeof BasePagination>['pages'],
+  currentPage: number,
+  totalPages: number,
+  as: LinkLike,
+  getLabel: (pageNumber: number) => string
+): Array<PaginationListItemProps> =>
+  pages.map(({ url }, index) => ({
+    url,
+    pageNumber: index + 1,
+    currentPage,
+    totalPages,
+    label: getLabel(index + 1),
+    as,
+  }));
+
+const createPaginationListItems = (
+  parsedPages: Array<PaginationListItemProps>
+) => parsedPages.map(page => <PaginationListItem key={page.url} {...page} />);
+
+// The minimum amount of elements are first page, current page, and last page
+const MINIMUM_AMOUNT_OF_ELEMENTS = 3;
+
+// Not more than two ellipses will be shown at the same time
+const MAXIMUM_AMOUNT_OF_ELLIPSES = 2;
+
+// The logic of this custom hook has taken the internal logic of
+// React MUI's Pagination component as reference. More info here:
+// https://github.com/mui/material-ui/blob/master/packages/mui-material/src/usePagination/usePagination.js
+export const useGetPageElements = (
+  currentPage: ComponentProps<typeof BasePagination>['currentPage'],
+  pages: ComponentProps<typeof BasePagination>['pages'],
+  currentPageSiblingsCount: number,
+  as: LinkLike,
+  getLabel: (pageNumber: number) => string
+) => {
+  const totalPages = pages.length;
+  const parsedPages = parsePages(pages, currentPage, totalPages, as, getLabel);
+  const currentPageIndex = currentPage - 1;
+
+  // We multiply it by two (2) as siblings are located on both left and right sides
+  // of the current page
+  const totalSiblingsCount = 2 * currentPageSiblingsCount;
+
+  const visiblePages =
+    totalSiblingsCount +
+    MINIMUM_AMOUNT_OF_ELEMENTS +
+    MAXIMUM_AMOUNT_OF_ELLIPSES;
+
+  // When there are more pages than the visible pages to be shown
+  // we do not need to perform any calculations
+  if (totalPages <= visiblePages) {
+    return createPaginationListItems(parsedPages);
+  }
+
+  // The index of the far-left sibling of the current page
+  const leftSiblingsFirstIndex = Math.max(
+    currentPageIndex - currentPageSiblingsCount,
+    1
+  );
+
+  // The index of the far-right sibling of the current page
+  const rightSiblingsLastIndex = Math.min(
+    currentPageIndex + currentPageSiblingsCount + 1,
+    totalPages
+  );
+
+  const firstIndex = 0;
+  const lastIndex = totalPages - 1;
+
+  // If there are at least two (2) elements between the far-left sibling of
+  // the current page, and the first page, we should show left ellipsis
+  // between them
+  const hasLeftEllipsis = leftSiblingsFirstIndex > firstIndex + 2;
+
+  // If there are at least two (2) elements between the far-right sibling of
+  // the current page, and the last page, we should show right ellipsis
+  // between them
+  const hasRightEllipsis = rightSiblingsLastIndex < lastIndex - 1;
+
+  if (!hasLeftEllipsis && hasRightEllipsis) {
+    const leftPagesLastIndex = MINIMUM_AMOUNT_OF_ELEMENTS + totalSiblingsCount;
+
+    const leftPages = parsedPages.slice(firstIndex, leftPagesLastIndex);
+
+    return [
+      ...createPaginationListItems(leftPages),
+      <Ellipsis key="ellipsis" />,
+      ...createPaginationListItems(parsedPages.slice(lastIndex)),
+    ];
+  }
+
+  if (hasLeftEllipsis && !hasRightEllipsis) {
+    const rightPagesFirstIndex =
+      MINIMUM_AMOUNT_OF_ELEMENTS + totalSiblingsCount;
+
+    const rightPages = parsedPages.slice(totalPages - rightPagesFirstIndex);
+
+    return [
+      ...createPaginationListItems(
+        parsedPages.slice(firstIndex, firstIndex + 1)
+      ),
+      <Ellipsis key="ellipsis" />,
+      ...createPaginationListItems(rightPages),
+    ];
+  }
+
+  if (hasLeftEllipsis && hasRightEllipsis) {
+    const middlePages = parsedPages.slice(
+      leftSiblingsFirstIndex,
+      rightSiblingsLastIndex
+    );
+
+    return [
+      ...createPaginationListItems(
+        parsedPages.slice(firstIndex, firstIndex + 1)
+      ),
+      <Ellipsis key="ellipsis-1" />,
+      ...createPaginationListItems(middlePages),
+      <Ellipsis key="ellipsis-2" />,
+      ...createPaginationListItems(parsedPages.slice(lastIndex)),
+    ];
+  }
+};

package/src/Common/Blockquote/index.module.css

@@ -0,0 +1,29 @@
+@reference "../../styles/index.css";
+
+.wrapper {
+  @apply flex
+    max-w-2xl
+    flex-col
+    items-start
+    gap-4
+    self-stretch
+    border-l-2
+    border-green-600
+    py-2
+    pl-5
+    text-lg
+    font-semibold
+    text-neutral-900
+    dark:border-green-400
+    dark:text-white;
+
+  & cite {
+    @apply font-regular
+      text-base
+      not-italic;
+
+    &::before {
+      @apply content-['—_'];
+    }
+  }
+}

package/src/Common/Blockquote/index.stories.tsx

@@ -0,0 +1,45 @@
+import type { Meta as MetaObj, StoryObj } from '@storybook/react';
+
+import Blockquote from '#ui/Common/Blockquote';
+
+type Story = StoryObj<typeof Blockquote>;
+type Meta = MetaObj<typeof Blockquote>;
+
+export const Default: Story = {
+  args: {
+    children: (
+      <>
+        “An expert is a person who has made all the mistakes that can be made in
+        a very narrow field.”
+        <cite>Niels Bohr</cite>
+      </>
+    ),
+  },
+};
+
+export const WithoutAttribution: Story = {
+  args: {
+    children:
+      '“Commander Keen soared through the stars, leaving behind a galaxy of memories, adventure, and boundless imagination. In the realm of gaming, his farewell echoes as a timeless voyage into the hearts of those who dare to dream and explore the unknown.”',
+  },
+};
+
+export const Nested: Story = {
+  args: {
+    children: (
+      <>
+        “Words can be like X-rays, if you use them properly—they’ll go through
+        anything. You read and you’re pierced.”
+        <Blockquote>
+          “A thinker sees his own actions as experiments and questions--as
+          attempts to find out something. Success and failure are for him
+          answers above all.”
+          <cite>Friedrich Nietzsche</cite>
+        </Blockquote>
+        <cite>Aldous Huxley, Brave New World</cite>
+      </>
+    ),
+  },
+};
+
+export default { component: Blockquote } as Meta;

package/src/Common/Blockquote/index.tsx

@@ -0,0 +1,11 @@
+import type { ComponentProps, FC, PropsWithChildren } from 'react';
+
+import styles from './index.module.css';
+
+type BlockquoteProps = ComponentProps<'blockquote'>;
+
+const Blockquote: FC<PropsWithChildren<BlockquoteProps>> = ({ children }) => (
+  <blockquote className={styles.wrapper}>{children}</blockquote>
+);
+
+export default Blockquote;

package/src/Common/Breadcrumbs/BreadcrumbHomeLink/index.module.css

@@ -0,0 +1,5 @@
+@reference "../../../styles/index.css";
+
+.icon {
+  @apply size-4;
+}

package/src/Common/Breadcrumbs/BreadcrumbHomeLink/index.tsx

@@ -0,0 +1,30 @@
+import HomeIcon from '@heroicons/react/24/outline/HomeIcon';
+import type { ComponentProps, FC } from 'react';
+
+import BreadcrumbLink from '#ui/Common/Breadcrumbs/BreadcrumbLink';
+
+import styles from './index.module.css';
+
+type BreadcrumbHomeLinkProps = Omit<
+  ComponentProps<typeof BreadcrumbLink>,
+  'href'
+> &
+  Partial<Pick<ComponentProps<typeof BreadcrumbLink>, 'href'>>;
+
+const BreadcrumbHomeLink: FC<BreadcrumbHomeLinkProps> = ({
+  href = '/',
+  ...props
+}) => {
+  const ariaLabel = props['aria-label'];
+  return (
+    <BreadcrumbLink href={href} {...props}>
+      <HomeIcon
+        title={ariaLabel}
+        aria-label={ariaLabel}
+        className={styles.icon}
+      />
+    </BreadcrumbLink>
+  );
+};
+
+export default BreadcrumbHomeLink;

package/src/Common/Breadcrumbs/BreadcrumbItem/index.module.css

@@ -0,0 +1,41 @@
+@reference "../../../styles/index.css";
+
+.item {
+  @apply flex
+    max-w-fit
+    items-center
+    gap-5
+    truncate
+    text-sm
+    font-medium;
+
+  &:last-child {
+    @apply w-full;
+  }
+
+  a {
+    @apply shrink
+      grow;
+  }
+
+  &,
+  > a,
+  > a:hover {
+    @apply text-neutral-800
+      motion-safe:transition-colors
+      dark:text-neutral-200;
+  }
+
+  &.visuallyHidden {
+    @apply hidden;
+  }
+
+  .separator {
+    @apply size-4
+      max-w-fit
+      shrink-0
+      grow
+      text-neutral-600
+      dark:text-neutral-400;
+  }
+}

package/src/Common/Breadcrumbs/BreadcrumbItem/index.tsx

@@ -0,0 +1,42 @@
+import ChevronRightIcon from '@heroicons/react/24/outline/ChevronRightIcon';
+import classNames from 'classnames';
+import type { ComponentProps, FC, PropsWithChildren } from 'react';
+
+import styles from './index.module.css';
+
+type BreadcrumbItemProps = {
+  disableMicrodata?: boolean;
+  hidden?: boolean;
+  hideSeparator?: boolean;
+  position?: number;
+} & ComponentProps<'li'>;
+
+const BreadcrumbItem: FC<PropsWithChildren<BreadcrumbItemProps>> = ({
+  disableMicrodata,
+  children,
+  hidden = false,
+  hideSeparator = false,
+  position,
+  ...props
+}) => (
+  <li
+    {...props}
+    itemProp={!disableMicrodata ? 'itemListElement' : undefined}
+    itemScope={!disableMicrodata ? true : undefined}
+    itemType={!disableMicrodata ? 'https://schema.org/ListItem' : undefined}
+    className={classNames(
+      styles.item,
+      { [styles.visuallyHidden]: hidden },
+      props.className
+    )}
+    aria-hidden={hidden ? 'true' : undefined}
+  >
+    {children}
+    {position && <meta itemProp="position" content={`${position}`} />}
+    {!hideSeparator && (
+      <ChevronRightIcon aria-hidden="true" className={styles.separator} />
+    )}
+  </li>
+);
+
+export default BreadcrumbItem;

package/src/Common/Breadcrumbs/BreadcrumbLink/index.module.css

@@ -0,0 +1,22 @@
+@reference "../../../styles/index.css";
+
+.link {
+  @apply max-w-fit
+    truncate;
+
+  &.active {
+    @apply rounded
+      bg-green-600
+      px-2
+      py-1
+      font-semibold
+      text-white
+      motion-safe:transition-colors
+      dark:text-white;
+
+    &:hover {
+      @apply bg-green-700
+        text-white;
+    }
+  }
+}

package/src/Common/Breadcrumbs/BreadcrumbLink/index.tsx

@@ -0,0 +1,37 @@
+import classNames from 'classnames';
+import type { ComponentProps, FC } from 'react';
+
+import type { LinkLike } from '#ui/types';
+
+import styles from './index.module.css';
+
+type BreadcrumbLinkProps = {
+  active?: boolean;
+  as: LinkLike;
+} & ComponentProps<LinkLike>;
+
+const BreadcrumbLink: FC<BreadcrumbLinkProps> = ({
+  href,
+  active,
+  as: Component = 'a',
+  ...props
+}) => (
+  <Component
+    itemScope
+    itemType="http://schema.org/Thing"
+    itemProp="item"
+    itemID={href?.toString()}
+    href={href}
+    className={classNames(
+      styles.link,
+      { [styles.active]: active },
+      props.className
+    )}
+    aria-current={active ? 'page' : undefined}
+    {...props}
+  >
+    <span itemProp="name">{props.children}</span>
+  </Component>
+);
+
+export default BreadcrumbLink;

package/src/Common/Breadcrumbs/BreadcrumbRoot/index.module.css

@@ -0,0 +1,9 @@
+@reference "../../../styles/index.css";
+
+.list {
+  @apply xs:w-full
+    flex
+    w-screen
+    gap-5
+    px-6;
+}

package/src/Common/Breadcrumbs/BreadcrumbRoot/index.tsx

@@ -0,0 +1,20 @@
+import type { FC, PropsWithChildren, ComponentProps } from 'react';
+
+import styles from './index.module.css';
+
+const BreadcrumbRoot: FC<PropsWithChildren<ComponentProps<'nav'>>> = ({
+  children,
+  ...props
+}) => (
+  <nav aria-label="breadcrumb" {...props}>
+    <ol
+      itemScope
+      itemType="https://schema.org/BreadcrumbList"
+      className={styles.list}
+    >
+      {children}
+    </ol>
+  </nav>
+);
+
+export default BreadcrumbRoot;

package/src/Common/Breadcrumbs/BreadcrumbTruncatedItem/index.tsx

@@ -0,0 +1,9 @@
+import BreadcrumbItem from '#ui/Common/Breadcrumbs/BreadcrumbItem';
+
+const BreadcrumbTruncatedItem = () => (
+  <BreadcrumbItem disableMicrodata>
+    <button disabled>…</button>
+  </BreadcrumbItem>
+);
+
+export default BreadcrumbTruncatedItem;

package/src/Common/Breadcrumbs/index.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta as MetaObj, StoryObj } from '@storybook/react';
+
+import Breadcrumbs from '#ui/Common/Breadcrumbs';
+
+type Story = StoryObj<typeof Breadcrumbs>;
+type Meta = MetaObj<typeof Breadcrumbs>;
+
+export const Default: Story = {
+  args: {
+    links: [
+      {
+        label: 'Learn',
+        href: '/learn',
+      },
+      {
+        label: 'Getting Started',
+        href: '/learn/getting-started',
+      },
+      {
+        label: 'Introduction to Node.js',
+        href: '/learn/getting-started/intro',
+      },
+    ],
+  },
+};
+
+export const Linkless: Story = {
+  args: {
+    links: [
+      {
+        label: 'Learn',
+        href: '',
+      },
+      {
+        label: 'Getting Started',
+        href: '',
+      },
+      {
+        label: 'Introduction to Node.js',
+        href: '',
+      },
+    ],
+  },
+};
+
+export const Truncate: Story = {
+  args: {
+    links: [
+      {
+        label: 'Learn',
+        href: '/learn',
+      },
+      {
+        label: 'Getting Started',
+        href: '/learn/getting-started',
+      },
+      {
+        label: 'Introduction to Node.js',
+        href: '/learn/getting-started/intro',
+      },
+      {
+        label: 'Installation',
+        href: '/learn/getting-started/intro/installation',
+      },
+      {
+        label: 'Documentation',
+        href: '/learn/getting-started/intro/installation/documentation',
+      },
+    ],
+    maxLength: 1,
+  },
+};
+
+export const HiddenHome: Story = {
+  args: {
+    hideHome: true,
+    links: [
+      {
+        label: 'Learn',
+        href: '/learn',
+      },
+      {
+        label: 'Getting Started',
+        href: '/learn/getting-started',
+      },
+      {
+        label: 'Introduction to Node.js',
+        href: '/learn/getting-started/intro',
+      },
+    ],
+  },
+};
+
+export default { component: Breadcrumbs } as Meta;

package/src/Common/Breadcrumbs/index.tsx

@@ -0,0 +1,81 @@
+import type { FC } from 'react';
+import { useMemo } from 'react';
+
+import BreadcrumbHomeLink from '#ui/Common/Breadcrumbs/BreadcrumbHomeLink';
+import BreadcrumbItem from '#ui/Common/Breadcrumbs/BreadcrumbItem';
+import BreadcrumbLink from '#ui/Common/Breadcrumbs/BreadcrumbLink';
+import BreadcrumbRoot from '#ui/Common/Breadcrumbs/BreadcrumbRoot';
+import BreadcrumbTruncatedItem from '#ui/Common/Breadcrumbs/BreadcrumbTruncatedItem';
+import type { FormattedMessage, LinkLike } from '#ui/types';
+
+export type BreadcrumbLink = {
+  label: FormattedMessage;
+  href: string | undefined;
+};
+
+type BreadcrumbsProps = {
+  links: Array<BreadcrumbLink>;
+  maxLength?: number;
+  hideHome?: boolean;
+  as: LinkLike;
+  homeLinkAriaLabel?: string;
+};
+
+const Breadcrumbs: FC<BreadcrumbsProps> = ({
+  links = [],
+  maxLength = 5,
+  hideHome = false,
+  as = 'a',
+  homeLinkAriaLabel,
+}) => {
+  const totalLength = links.length + +!hideHome;
+  const lengthOffset = maxLength - totalLength;
+  const isOverflow = lengthOffset < 0;
+
+  const items = useMemo(
+    () =>
+      links.map((link, index, items) => {
+        const position = index + 1;
+        const isLastItem = index === items.length - 1;
+        const hidden =
+          // We add 1 here to take into account of the truncated breadcrumb.
+          position <= Math.abs(lengthOffset) + 1 && isOverflow && !isLastItem;
+
+        return (
+          <BreadcrumbItem
+            key={link.label.toString()}
+            hidden={hidden}
+            hideSeparator={isLastItem}
+            position={position + +!hideHome}
+          >
+            {link.href || isLastItem ? (
+              <BreadcrumbLink
+                as={as}
+                href={link.href || undefined}
+                active={isLastItem}
+              >
+                {link.label}
+              </BreadcrumbLink>
+            ) : (
+              <span className="opacity-70">{link.label}</span>
+            )}
+          </BreadcrumbItem>
+        );
+      }),
+    [hideHome, isOverflow, lengthOffset, links]
+  );
+
+  return (
+    <BreadcrumbRoot>
+      {!hideHome && (
+        <BreadcrumbItem position={1}>
+          <BreadcrumbHomeLink as={as} aria-label={homeLinkAriaLabel} />
+        </BreadcrumbItem>
+      )}
+      {isOverflow && <BreadcrumbTruncatedItem />}
+      {items}
+    </BreadcrumbRoot>
+  );
+};
+
+export default Breadcrumbs;