@node-core/ui-components 0.0.1 → 1.0.1-df203d0fe21ee5d80d258c60dc821e8ac0601ce4

package/Common/BasePagination/PaginationListItem/index.tsx

@@ -0,0 +1,39 @@
+import type { FC } from 'react';
+
+import type { LinkLike } from '#ui/types';
+
+import styles from './index.module.css';
+
+export type PaginationListItemProps = {
+  url: string;
+  pageNumber: number;
+  // One-based number of the current page
+  currentPage: number;
+  totalPages: number;
+  as?: LinkLike;
+  label: string;
+};
+
+const PaginationListItem: FC<PaginationListItemProps> = ({
+  url,
+  pageNumber,
+  currentPage,
+  totalPages,
+  as: Component = 'a',
+  label,
+}) => {
+  return (
+    <li key={pageNumber} aria-setsize={totalPages} aria-posinset={pageNumber}>
+      <Component
+        href={url}
+        aria-label={label}
+        className={styles.listItem}
+        {...(pageNumber === currentPage && { 'aria-current': 'page' })}
+      >
+        <span>{pageNumber}</span>
+      </Component>
+    </li>
+  );
+};
+
+export default PaginationListItem;

package/Common/BasePagination/PrevNextArrow.tsx

@@ -0,0 +1,15 @@
+import { ChevronLeftIcon, ChevronRightIcon } from '@heroicons/react/24/solid';
+import type { FC, SVGAttributes } from 'react';
+
+type PrevNextArrowProps = {
+  type: 'previous' | 'next';
+} & SVGAttributes<SVGSVGElement>;
+
+const PrevNextArrow: FC<PrevNextArrowProps> = ({ type, ...extra }) => {
+  const ChevronComponent =
+    type === 'previous' ? ChevronLeftIcon : ChevronRightIcon;
+
+  return <ChevronComponent {...extra} />;
+};
+
+export default PrevNextArrow;

package/Common/BasePagination/__tests__/index.test.jsx

@@ -0,0 +1,180 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { render, screen } from '@testing-library/react';
+
+import { isVisible } from '../../../../../tests/utilities.mjs';
+
+import BasePagination from '#ui/Common/BasePagination';
+
+const getPageLabel = number => number.toString();
+const labels = {
+  aria: 'Aria',
+  prevAria: 'Previous Aria',
+  prev: 'Previous',
+  nextAria: 'Next Aria',
+  next: 'Next',
+};
+
+function renderPagination({
+  currentPage = 1,
+  pages,
+  currentPageSiblingsCount,
+}) {
+  const parsedPages = new Array(pages)
+    .fill({ url: 'page' })
+    .map(item => ({ url: `${item.url}-${Math.random()}` }));
+
+  render(
+    <BasePagination
+      currentPage={currentPage}
+      pages={parsedPages}
+      currentPageSiblingsCount={currentPageSiblingsCount}
+      getPageLabel={getPageLabel}
+      labels={labels}
+    />
+  );
+
+  return {
+    currentPage,
+    parsedPages,
+  };
+}
+
+describe('Pagination', () => {
+  describe('Rendering', () => {
+    it('Renders the navigation buttons even if no pages are passed to it', () => {
+      renderPagination({ currentPage: 0, pages: 0 });
+
+      assert.ok(isVisible(screen.getByRole('navigation')));
+      assert.ok(
+        isVisible(
+          screen.getByRole('button', {
+            name: labels.prevAria,
+          })
+        )
+      );
+      assert.ok(
+        isVisible(
+          screen.getByRole('button', {
+            name: labels.nextAria,
+          })
+        )
+      );
+    });
+
+    it('Renders the passed pages and current page', () => {
+      const { currentPage, parsedPages } = renderPagination({
+        pages: 4,
+      });
+
+      const pageElements = screen.getAllByRole('link');
+
+      assert.equal(pageElements.length, parsedPages.length);
+
+      pageElements.forEach((page, index) => {
+        if (index + 1 === currentPage) {
+          assert.strictEqual(page.getAttribute('aria-current'), 'page');
+        }
+
+        assert.ok(isVisible(page));
+      });
+    });
+  });
+
+  describe('Ellipsis behavior', () => {
+    it('When the pages size is equal or smaller than currentPageSiblingsCount + 5, all pages are shown', () => {
+      renderPagination({
+        pages: 6,
+      });
+
+      assert.ok(!screen.queryByText('...')?.ownerDocument);
+
+      const pageElements = screen.getAllByRole('link');
+
+      assert.deepEqual(
+        pageElements.map(element => element.textContent),
+        ['1', '2', '3', '4', '5', '6']
+      );
+    });
+
+    it('Shows left ellipsis when the left sibling of the current page is at least two pages away from the first page', () => {
+      renderPagination({
+        currentPage: 5,
+        pages: 8,
+      });
+
+      assert.ok(isVisible(screen.getByText('...')));
+
+      const pageElements = screen.getAllByRole('link');
+
+      assert.deepEqual(
+        pageElements.map(element => element.textContent),
+        ['1', '4', '5', '6', '7', '8']
+      );
+    });
+
+    it('Shows right ellipsis when the right sibling of the current page is at least two pages away from the last page', () => {
+      renderPagination({
+        currentPage: 3,
+        pages: 8,
+      });
+
+      assert.ok(isVisible(screen.getByText('...')));
+
+      const pageElements = screen.getAllByRole('link');
+
+      assert.deepEqual(
+        pageElements.map(element => element.textContent),
+        ['1', '2', '3', '4', '5', '8']
+      );
+    });
+
+    it('Shows right and left ellipses when the current page siblings are both at least two pages away from the first and last pages', () => {
+      renderPagination({
+        currentPage: 5,
+        pages: 10,
+      });
+
+      assert.equal(screen.getAllByText('...').length, 2);
+
+      const pageElements = screen.getAllByRole('link');
+
+      assert.deepEqual(
+        pageElements.map(element => element.textContent),
+        ['1', '4', '5', '6', '10']
+      );
+    });
+  });
+
+  describe('Navigation buttons', () => {
+    it('Disables "Previous" button when the currentPage is equal to the first page', () => {
+      renderPagination({
+        pages: 2,
+      });
+
+      assert.ok(
+        screen
+          .getByRole('button', {
+            name: labels.prevAria,
+          })
+          .getAttribute('aria-disabled')
+      );
+    });
+
+    it('Disables "Next" button when the currentPage is equal to the last page', () => {
+      renderPagination({
+        currentPage: 2,
+        pages: 2,
+      });
+
+      assert.ok(
+        screen
+          .getByRole('button', {
+            name: labels.nextAria,
+          })
+          .getAttribute('aria-disabled')
+      );
+    });
+  });
+});

package/Common/BasePagination/index.module.css

@@ -0,0 +1,39 @@
+@reference "../../styles/index.css";
+
+.pagination {
+  @apply grid
+    items-center
+    justify-between
+    gap-y-5
+    [grid-template-areas:'pages_pages_pages''prev_._next']
+    md:gap-y-0
+    md:[grid-template-areas:'prev_pages_next'];
+}
+
+.previousButton,
+.nextButton {
+  @apply text-sm;
+}
+
+.previousButton {
+  @apply [grid-area:prev];
+}
+
+.nextButton {
+  @apply [grid-area:next];
+}
+
+.arrowIcon {
+  @apply h-5
+    shrink-0
+    text-neutral-600
+    dark:text-neutral-400;
+}
+
+.list {
+  @apply flex
+    list-none
+    justify-center
+    gap-1
+    [grid-area:pages];
+}

package/Common/BasePagination/index.stories.tsx

@@ -0,0 +1,67 @@
+import type { Meta as MetaObj, StoryObj } from '@storybook/react';
+
+import BasePagination from '#ui/Common/BasePagination';
+
+type Story = StoryObj<typeof BasePagination>;
+type Meta = MetaObj<typeof BasePagination>;
+
+export const Default: Story = {
+  args: {
+    currentPage: 1,
+    currentPageSiblingsCount: 1,
+    pages: [{ url: '1' }, { url: '2' }, { url: '3' }],
+    getPageLabel: value => `Page: ${value}`,
+    labels: {
+      aria: 'Aria',
+      prevAria: 'Previous Aria',
+      prev: 'Previous',
+      nextAria: 'Next Aria',
+      next: 'Next',
+    },
+  },
+};
+
+export const LeftEllipsis: Story = {
+  args: {
+    ...Default.args,
+    currentPage: 5,
+    pages: [
+      { url: '1' },
+      { url: '2' },
+      { url: '3' },
+      { url: '4' },
+      { url: '5' },
+      { url: '6' },
+      { url: '7' },
+      { url: '8' },
+    ],
+  },
+};
+
+export const RightEllipsis: Story = {
+  args: {
+    ...LeftEllipsis.args,
+    currentPage: 3,
+  },
+};
+
+export const TwoEllipses: Story = {
+  args: {
+    ...Default.args,
+    currentPage: 5,
+    pages: [
+      { url: '1' },
+      { url: '2' },
+      { url: '3' },
+      { url: '4' },
+      { url: '5' },
+      { url: '6' },
+      { url: '7' },
+      { url: '8' },
+      { url: '9' },
+      { url: '10' },
+    ],
+  },
+};
+
+export default { component: BasePagination } as Meta;

package/Common/BasePagination/index.tsx

@@ -0,0 +1,77 @@
+import { ArrowRightIcon, ArrowLeftIcon } from '@heroicons/react/20/solid';
+import type { FC } from 'react';
+
+import Button from '#ui/Common/BaseButton';
+import { useGetPageElements } from '#ui/Common/BasePagination/useGetPageElements';
+import type { LinkLike } from '#ui/types';
+
+import styles from './index.module.css';
+
+type Page = { url: string };
+
+export type PaginationProps = {
+  // One-based number of the current page
+  currentPage: number;
+  pages: Array<Page>;
+  // The number of page buttons on each side of the current page button
+  // @default 1
+  currentPageSiblingsCount?: number;
+  as?: LinkLike;
+  getPageLabel: (pageNumber: number) => string;
+  labels: {
+    aria: string;
+    prevAria: string;
+    prev: string;
+    nextAria: string;
+    next: string;
+  };
+};
+
+const BasePagination: FC<PaginationProps> = ({
+  currentPage,
+  pages,
+  as = 'a',
+  currentPageSiblingsCount = 1,
+  labels,
+  getPageLabel,
+}) => {
+  const parsedPages = useGetPageElements(
+    currentPage,
+    pages,
+    currentPageSiblingsCount,
+    as,
+    getPageLabel
+  );
+
+  return (
+    <nav aria-label={labels.aria} className={styles.pagination}>
+      <Button
+        as={as}
+        aria-label={labels.prevAria}
+        disabled={currentPage === 1}
+        kind="secondary"
+        className={styles.previousButton}
+        href={pages[currentPage - 2]?.url}
+      >
+        <ArrowLeftIcon className={styles.arrowIcon} />
+        <span>{labels.prev}</span>
+      </Button>
+
+      <ol className={styles.list}>{parsedPages}</ol>
+
+      <Button
+        as={as}
+        aria-label={labels.nextAria}
+        disabled={currentPage === pages.length}
+        kind="secondary"
+        className={styles.nextButton}
+        href={pages[currentPage]?.url}
+      >
+        <span>{labels.next}</span>
+        <ArrowRightIcon className={styles.arrowIcon} />
+      </Button>
+    </nav>
+  );
+};
+
+export default BasePagination;

package/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/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/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/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/Common/Breadcrumbs/BreadcrumbHomeLink/index.module.css

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

package/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;