@shohojdhara/atomix 0.1.30 → 0.2.1

package/src/components/Navigation/SideMenu/SideMenu.tsx

@@ -0,0 +1,101 @@
+import React, { useState, useEffect, useRef, forwardRef } from 'react';
+import { SideMenuProps } from '../../../lib/types/components';
+import { useSideMenu } from '../../../lib/composables/useSideMenu';
+import { SIDE_MENU } from '../../../lib/constants/components';
+import { Icon } from '../../Icon';
+
+/**
+ * SideMenu component provides a collapsible navigation menu with title and menu items.
+ * Automatically collapses on mobile devices and can be toggled via a header button.
+ *
+ * @example
+ * ```tsx
+ * <SideMenu title="Navigation">
+ *   <SideMenuList>
+ *     <SideMenuItem href="/" active>Home</SideMenuItem>
+ *     <SideMenuItem href="/about">About</SideMenuItem>
+ *     <SideMenuItem href="/contact">Contact</SideMenuItem>
+ *   </SideMenuList>
+ * </SideMenu>
+ * ```
+ */
+export const SideMenu = forwardRef<HTMLDivElement, SideMenuProps>(
+  (
+    {
+      title,
+      children,
+      isOpen,
+      onToggle,
+      collapsible = true,
+      className = '',
+      disabled = false,
+      toggleIcon,
+      id,
+    },
+    ref
+  ) => {
+    const {
+      isOpenState,
+      wrapperRef,
+      innerRef,
+      generateSideMenuClass,
+      generateWrapperClass,
+      handleToggle,
+    } = useSideMenu({
+      isOpen,
+      onToggle,
+      collapsible,
+      disabled,
+    });
+
+    const sideMenuClass = generateSideMenuClass({ className, isOpen: isOpenState });
+    const wrapperClass = generateWrapperClass();
+
+    // Default toggle icon using Atomix Icon component
+    const defaultToggleIcon = <Icon name="CaretRight" size="xs" />;
+
+    return (
+      <div ref={ref} className={sideMenuClass} id={id}>
+        {title && collapsible && (
+          <div
+            className="c-side-menu__toggler"
+            onClick={handleToggle}
+            role="button"
+            tabIndex={disabled ? -1 : 0}
+            aria-expanded={isOpenState}
+            aria-controls={id ? `${id}-content` : undefined}
+            aria-disabled={disabled}
+            onKeyDown={e => {
+              if ((e.key === 'Enter' || e.key === ' ') && !disabled) {
+                e.preventDefault();
+                handleToggle();
+              }
+            }}
+          >
+            <span className="c-side-menu__title">{title}</span>
+            <span className="c-side-menu__toggler-icon">{toggleIcon || defaultToggleIcon}</span>
+          </div>
+        )}
+
+        {title && !collapsible && <h3 className="c-side-menu__title">{title}</h3>}
+
+        <div
+          ref={wrapperRef}
+          className={wrapperClass}
+          id={id ? `${id}-content` : undefined}
+          aria-hidden={collapsible ? !isOpenState : false}
+        >
+          <div ref={innerRef} className="c-side-menu__inner">
+            {children}
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+export type { SideMenuProps };
+
+SideMenu.displayName = 'SideMenu';
+
+export default SideMenu;

package/src/components/Navigation/SideMenu/SideMenuItem.tsx

@@ -0,0 +1,103 @@
+import React, { forwardRef } from 'react';
+import { SideMenuItemProps } from '../../../lib/types/components';
+import { useSideMenuItem } from '../../../lib/composables/useSideMenu';
+
+/**
+ * SideMenuItem component represents a single navigation item in a side menu.
+ * Can be rendered as a link or button with active and disabled states.
+ *
+ * @example
+ * ```tsx
+ * // As a link
+ * <SideMenuItem href="/about" active>About</SideMenuItem>
+ *
+ * // As a button
+ * <SideMenuItem onClick={() => console.log('clicked')}>
+ *   Click me
+ * </SideMenuItem>
+ *
+ * // With icon
+ * <SideMenuItem href="/settings" icon={<Icon name="Settings" />}>
+ *   Settings
+ * </SideMenuItem>
+ *
+ * // Disabled
+ * <SideMenuItem href="/disabled" disabled>
+ *   Disabled Item
+ * </SideMenuItem>
+ * ```
+ */
+export const SideMenuItem = forwardRef<HTMLAnchorElement | HTMLButtonElement, SideMenuItemProps>(
+  (
+    {
+      children,
+      href,
+      onClick,
+      active = false,
+      disabled = false,
+      icon,
+      className = '',
+      target,
+      rel,
+      LinkComponent,
+    },
+    ref
+  ) => {
+    const { generateSideMenuItemClass, handleClick } = useSideMenuItem({
+      active,
+      disabled,
+      className,
+    });
+
+    const itemClass = generateSideMenuItemClass();
+
+    const linkProps = {
+      ref: ref as React.Ref<HTMLAnchorElement>,
+      href: disabled ? undefined : href,
+      className: itemClass,
+      onClick: handleClick(onClick),
+      'aria-disabled': disabled,
+      'aria-current': (active ? 'page' : undefined) as React.AriaAttributes['aria-current'],
+      target: target,
+      rel: rel,
+      tabIndex: disabled ? -1 : 0,
+    };
+
+    // Render as link if href is provided
+    if (href) {
+      return LinkComponent ? (
+        <LinkComponent {...linkProps}>
+          {icon && <span className="c-side-menu__link-icon">{icon}</span>}
+          <span className="c-side-menu__link-text">{children}</span>
+        </LinkComponent>
+      ) : (
+        <a {...linkProps}>
+          {icon && <span className="c-side-menu__link-icon">{icon}</span>}
+          <span className="c-side-menu__link-text">{children}</span>
+        </a>
+      );
+    }
+
+    // Render as button if no href
+    return (
+      <button
+        ref={ref as React.Ref<HTMLButtonElement>}
+        type="button"
+        className={itemClass}
+        onClick={handleClick(onClick)}
+        disabled={disabled}
+        aria-current={active ? 'page' : undefined}
+        tabIndex={disabled ? -1 : 0}
+      >
+        {icon && <span className="c-side-menu__link-icon">{icon}</span>}
+        <span className="c-side-menu__link-text">{children}</span>
+      </button>
+    );
+  }
+);
+
+export type { SideMenuItemProps };
+
+SideMenuItem.displayName = 'SideMenuItem';
+
+export default SideMenuItem;

package/src/components/Navigation/SideMenu/SideMenuList.tsx

@@ -0,0 +1,41 @@
+import React, { forwardRef } from 'react';
+import { SideMenuListProps } from '../../../lib/types/components';
+
+/**
+ * SideMenuList component provides a container for side menu items.
+ *
+ * @example
+ * ```tsx
+ * <SideMenuList>
+ *   <SideMenuItem href="/" active>Home</SideMenuItem>
+ *   <SideMenuItem href="/about">About</SideMenuItem>
+ *   <SideMenuItem href="/contact">Contact</SideMenuItem>
+ * </SideMenuList>
+ * ```
+ */
+export const SideMenuList = forwardRef<HTMLUListElement, SideMenuListProps>(
+  ({ children, className = '' }, ref) => {
+    const listClass = `c-side-menu__list ${className}`.trim();
+
+    return (
+      <ul ref={ref} className={listClass} role="list">
+        {React.Children.map(children, (child, index) => {
+          if (React.isValidElement(child)) {
+            return (
+              <li key={index} className="c-side-menu__item" role="listitem">
+                {child}
+              </li>
+            );
+          }
+          return child;
+        })}
+      </ul>
+    );
+  }
+);
+
+export type { SideMenuListProps };
+
+SideMenuList.displayName = 'SideMenuList';
+
+export default SideMenuList;

package/src/components/Navigation/index.ts

@@ -0,0 +1,23 @@
+// React Components
+export { Navbar } from './Navbar/Navbar';
+export { Nav } from './Nav/Nav';
+export { NavItem } from './Nav/NavItem';
+export { NavDropdown } from './Nav/NavDropdown';
+export { Menu, MenuItem, MenuDivider } from './Menu/Menu';
+export { MegaMenu, MegaMenuColumn, MegaMenuLink } from './Menu/MegaMenu';
+
+// SideMenu Components
+export { SideMenu } from './SideMenu/SideMenu';
+export { SideMenuList } from './SideMenu/SideMenuList';
+export { SideMenuItem } from './SideMenu/SideMenuItem';
+
+// Types
+export type {
+  NavbarProps,
+  NavProps,
+  NavItemProps,
+  NavDropdownProps,
+  SideMenuProps,
+  SideMenuListProps,
+  SideMenuItemProps,
+} from '../../lib/types/components';

package/src/components/Pagination/Pagination.stories.tsx

@@ -0,0 +1,188 @@
+import React, { useState } from 'react';
+import { Meta, StoryFn } from '@storybook/react';
+import { fn } from '@storybook/test';
+import { Pagination } from './Pagination';
+import { PaginationProps } from '../../lib/types/components';
+
+export default {
+  title: 'Components/Pagination',
+  component: Pagination,
+  argTypes: {
+    currentPage: {
+      control: 'number',
+      description: 'Current active page',
+    },
+    totalPages: {
+      control: 'number',
+      description: 'Total number of pages',
+    },
+
+    siblingCount: {
+      control: 'number',
+      description: 'Number of page links to show before and after current page',
+    },
+    showFirstLastButtons: {
+      control: 'boolean',
+      description: 'Whether to show first/last page buttons',
+    },
+    showPrevNextButtons: {
+      control: 'boolean',
+      description: 'Whether to show previous/next page buttons',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+      description: 'Size variant for pagination',
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible label for the navigation element',
+    },
+    className: {
+      control: 'text',
+      description: 'Custom class for the pagination container',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'A Pagination component for navigating through pages of content with enhanced accessibility, configurable sizes, and icons for navigation buttons.',
+      },
+    },
+  },
+} as Meta<typeof Pagination>;
+
+// Template with controlled state
+const ControlledTemplate: StoryFn<PaginationProps> = args => {
+  const [currentPage, setCurrentPage] = useState(args.currentPage);
+
+  const handlePageChange = (page: number) => {
+    setCurrentPage(page);
+    args.onPageChange?.(page);
+  };
+
+  return <Pagination {...args} currentPage={currentPage} onPageChange={handlePageChange} />;
+};
+
+export const Default = ControlledTemplate.bind({});
+Default.args = {
+  currentPage: 1,
+  totalPages: 10,
+  siblingCount: 1,
+  showFirstLastButtons: true,
+  showPrevNextButtons: true,
+  size: 'md',
+  ariaLabel: 'Pagination',
+};
+Default.parameters = {
+  docs: {
+    description: {
+      story: 'Default pagination with first/last and previous/next navigation buttons using icons.',
+    },
+  },
+};
+
+export const WithMorePages = ControlledTemplate.bind({});
+WithMorePages.args = {
+  currentPage: 25,
+  totalPages: 50,
+  siblingCount: 2,
+  size: 'md',
+};
+WithMorePages.parameters = {
+  docs: {
+    description: {
+      story: 'Pagination with many pages, showing the ellipsis (dots) for page ranges.',
+    },
+  },
+};
+
+export const SmallSize = ControlledTemplate.bind({});
+SmallSize.args = {
+  currentPage: 4,
+  totalPages: 10,
+  siblingCount: 1,
+  size: 'sm',
+};
+SmallSize.parameters = {
+  docs: {
+    description: {
+      story: 'Small-sized pagination component with smaller icons and buttons.',
+    },
+  },
+};
+
+export const LargeSize = ControlledTemplate.bind({});
+LargeSize.args = {
+  currentPage: 4,
+  totalPages: 10,
+  siblingCount: 1,
+  size: 'lg',
+};
+LargeSize.parameters = {
+  docs: {
+    description: {
+      story: 'Large-sized pagination component with larger icons and buttons.',
+    },
+  },
+};
+
+export const FewPages = ControlledTemplate.bind({});
+FewPages.args = {
+  currentPage: 2,
+  totalPages: 3,
+  siblingCount: 1,
+};
+FewPages.parameters = {
+  docs: {
+    description: {
+      story: 'Pagination with only a few pages, showing all page numbers without ellipsis.',
+    },
+  },
+};
+
+export const NoFirstLastButtons = ControlledTemplate.bind({});
+NoFirstLastButtons.args = {
+  currentPage: 5,
+  totalPages: 15,
+  showFirstLastButtons: false,
+  showPrevNextButtons: true,
+};
+NoFirstLastButtons.parameters = {
+  docs: {
+    description: {
+      story: 'Pagination with only previous/next navigation buttons (no skip to first/last).',
+    },
+  },
+};
+
+export const OnlyPageNumbers = ControlledTemplate.bind({});
+OnlyPageNumbers.args = {
+  currentPage: 5,
+  totalPages: 15,
+  showFirstLastButtons: false,
+  showPrevNextButtons: false,
+};
+OnlyPageNumbers.parameters = {
+  docs: {
+    description: {
+      story: 'Pagination with only page numbers, no navigation buttons.',
+    },
+  },
+};
+
+export const CustomStyling = ControlledTemplate.bind({});
+CustomStyling.args = {
+  currentPage: 5,
+  totalPages: 15,
+  className: 'custom-pagination-class',
+  showFirstLastButtons: false,
+};
+CustomStyling.parameters = {
+  docs: {
+    description: {
+      story: 'Pagination with custom CSS class for additional styling.',
+    },
+  },
+};

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,162 @@
+import React from 'react';
+import { PaginationProps } from '../../lib/types/components';
+import { usePagination, DOTS } from '../../lib/composables/usePagination';
+import { PAGINATION_DEFAULTS } from '../../lib/constants/components';
+import { Icon, IconProps } from '../Icon/Icon';
+
+// @TODO: Add Search functionality for pagination
+
+/**
+ * Navigation button types for pagination
+ */
+type NavButtonType = 'first' | 'prev' | 'next' | 'last';
+
+/**
+ * Props for the PaginationNavButton component
+ */
+interface PaginationNavButtonProps {
+  type: NavButtonType;
+  onClick: () => void;
+  disabled: boolean;
+  label: string;
+  iconName: IconProps['name'];
+}
+
+/**
+ * PaginationNavButton component for rendering first, previous, next, and last buttons
+ */
+export const PaginationNavButton: React.FC<PaginationNavButtonProps> = ({
+  type,
+  onClick,
+  disabled,
+  label,
+  iconName,
+}) => (
+  <li
+    className={`c-pagination__item c-pagination__item--${type} ${disabled ? 'is-disabled' : ''}`}
+    aria-disabled={disabled}
+  >
+    <button
+      type="button"
+      className="c-pagination__link"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={label}
+    >
+      <Icon name={iconName} size="sm" aria-hidden="true" />
+    </button>
+  </li>
+);
+
+/**
+ * Pagination component
+ */
+export const Pagination: React.FC<PaginationProps> = ({
+  currentPage = PAGINATION_DEFAULTS.currentPage,
+  totalPages = PAGINATION_DEFAULTS.totalPages,
+  onPageChange,
+  siblingCount = PAGINATION_DEFAULTS.siblingCount,
+  showFirstLastButtons = PAGINATION_DEFAULTS.showFirstLastButtons,
+  showPrevNextButtons = PAGINATION_DEFAULTS.showPrevNextButtons,
+  size = PAGINATION_DEFAULTS.size,
+  className = '',
+  ariaLabel = 'Pagination',
+}) => {
+  const { paginationRange, goToPage, nextPage, prevPage, firstPage, lastPage } = usePagination({
+    currentPage,
+    totalPages,
+    siblingCount,
+    onPageChange,
+  });
+
+  // Don't render pagination with a single page or no pages
+  if (currentPage === 0 || paginationRange.length < 2) {
+    return null;
+  }
+
+  return (
+    <nav className={`c-pagination c-pagination--${size} ${className}`} aria-label={ariaLabel}>
+      <ul className="c-pagination__items">
+        {showFirstLastButtons && (
+          <PaginationNavButton
+            type="first"
+            onClick={firstPage}
+            disabled={currentPage === 1}
+            label="Go to first page"
+            iconName="SkipBack"
+          />
+        )}
+
+        {showPrevNextButtons && (
+          <PaginationNavButton
+            type="prev"
+            onClick={prevPage}
+            disabled={currentPage === 1}
+            label="Go to previous page"
+            iconName="CaretLeft"
+          />
+        )}
+
+        {paginationRange.map((pageNumber, index) => {
+          if (pageNumber === DOTS) {
+            return (
+              <li
+                key={`dots-${index}`}
+                className="c-pagination__item c-pagination__item--dots"
+                aria-hidden="true"
+              >
+                &#8230;
+              </li>
+            );
+          }
+
+          const isActive = pageNumber === currentPage;
+
+          return (
+            <li
+              key={pageNumber}
+              className={`c-pagination__item ${isActive ? 'is-active' : ''}`}
+              aria-current={isActive ? 'page' : undefined}
+            >
+              <button
+                type="button"
+                className="c-pagination__link"
+                onClick={() => goToPage(pageNumber as number)}
+                aria-label={`Page ${pageNumber}`}
+                aria-current={isActive ? 'page' : undefined}
+              >
+                {pageNumber}
+              </button>
+            </li>
+          );
+        })}
+
+        {showPrevNextButtons && (
+          <PaginationNavButton
+            type="next"
+            onClick={nextPage}
+            disabled={currentPage === totalPages}
+            label="Go to next page"
+            iconName="CaretRight"
+          />
+        )}
+
+        {showFirstLastButtons && (
+          <PaginationNavButton
+            type="last"
+            onClick={lastPage}
+            disabled={currentPage === totalPages}
+            label="Go to last page"
+            iconName="SkipForward"
+          />
+        )}
+      </ul>
+    </nav>
+  );
+};
+
+export type { PaginationProps };
+
+Pagination.displayName = 'Pagination';
+
+export default Pagination;

package/src/components/Pagination/index.ts

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