@js-empire/emperor-ui 1.2.3 → 1.2.5

package/.cursor/rules/code-conventions.mdc

@@ -0,0 +1,50 @@
+---
+name: code-conventions
+description: This rule is for Cursor to follow code conventions we have.
+---
+
+# Overview
+
+Whenever you write a code, follow these rules:
+
+## Conventions
+
+Follow all the codebase conventions like how functions and variables are written, where to place everything, ...etc. Follow the SOLID coding principles in all code.
+
+## Imports & Exports
+
+Every module (or directory) should have an "index.ts" file that exports all the files and sub modules inside it using ('export \* from "./file-or-dir-name";'), where every file should export all its functions and variables to be exported. Never use relative imports but rather use the absolute ones for better readability and easier importation.
+
+## Utilities
+
+All types, constants, enums, hooks, utility functions, and configs should be defined in their relative packages or modules. Utility functions should always have a short description (function annotation or documentation) that summarizes what is does and what it needs.
+
+## Complexity
+
+Try to always find the easiest, simplest, and most efficient solution with the least amount of code rather than the most complex one.
+
+## File Size
+
+Every file should never be more than 300 lines of code. Whenever a code exceeds 250 to 300 lines, try to optimize it or split it into multiple files following the codebase conventions.
+
+## Single Responsibility
+
+Each function should only have one purpose and each component file should only exports one component.
+
+## Naming
+
+The exported component must have the same name as its file's name. Follow these rules for naming:
+
+- Files: kebab-case
+- Directories: kebab-case
+- Types & Interfaces: PascalCase
+- Constants: PascalCase
+- Hooks: useCamelCase
+- Pages and Layouts' Components: PascalCase
+- Enums:
+  - Enum name: PascalCase
+  - Enum key: UPPER_SNAKE_CASE
+
+## Parameters
+
+All parameters across the project should be implemented as one object that has the parameters in it so we can modify them easily in the future, like this: `({ param1, param2 = false }:{ param1: string, param2?: boolean })`. Never define them as multiple parameters like this: `(param1: string, param2?: boolean)`. That applies to functions, arrow functions, components, hooks, and anything takes parameters.

package/README.md

@@ -1,47 +1,238 @@
-# Emperor UI
+<p align="center">
+  <img src="./public/images/emperor-ui-logo.png" alt="Emperor UI Logo" width="120" />
+</p>
 
-![Emperor UI Logo](./public/images/emperor-ui-logo.png)
+<h1 align="center">Emperor UI</h1>
 
-## Intro
+<p align="center">
+  <strong>They provide the atoms, we provide the empire.</strong>
+</p>
 
-A modular UI library built for React and Nextjs. It depends on HeroUI to implement advanced organisms and pages.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@js-empire/emperor-ui">
+    <img src="https://img.shields.io/npm/v/@js-empire/emperor-ui.svg" alt="npm version" />
+  </a>
+  <a href="https://github.com/MustafaHasanat/emperor-ui/blob/main/package.json">
+    <img src="https://img.shields.io/npm/l/@js-empire/emperor-ui" alt="license" />
+  </a>
+</p>
 
-Each one of them has props to control every aspect pf the component, with enabling/disabling the optional features.
+---
+
+## Introduction
+
+**Emperor UI** is a modular React component library built for modern web applications. It sits on top of [HeroUI](https://www.heroui.com/) to deliver ready-made organisms and page-level building blocks—so you can ship features faster without rebuilding common patterns from scratch.
+
+Every component is designed with full control in mind: optional features can be enabled or disabled via props, and styling is customizable through `className` and `classNames` for fine-grained overrides.
+
+Ideal for **React** and **Next.js** projects that use **Tailwind CSS** and HeroUI.
+
+---
+
+## Installation
+
+Install the package from npm:
+
+```bash
+npm install @js-empire/emperor-ui
+```
+
+Or with yarn:
+
+```bash
+yarn add @js-empire/emperor-ui
+```
+
+Or with pnpm:
+
+```bash
+pnpm add @js-empire/emperor-ui
+```
+
+### Peer dependencies
+
+Emperor UI depends on **React**, **HeroUI**, **Tailwind CSS**, and related tooling. Ensure your project has compatible versions. For theme switching, **next-themes** is used.
+
+### Styles
+
+Import the library’s global styles in your app root (e.g. `layout.tsx` or `_app.tsx`):
+
+```tsx
+import "@js-empire/emperor-ui/globals.css";
+```
 
 ---
 
 ## Components
 
-### Item Card
+Components are grouped by complexity: **Atoms** (small building blocks), **Molecules** (combinations of atoms), **Organisms** (sections and features), and **Templates** (full page layouts).
+
+---
+
+### Atoms
+
+| Component       | Description                                                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Brand**       | Logo and brand mark for headers and sidebars.                                                                                                                                  |
+| **ColorPicker** | Color selection with preset or free (input) modes. Use `inputType="preset"` for predefined colors.                                                                             |
+| **Container**   | Centered layout wrapper with consistent padding.                                                                                                                               |
+| **Column**      | Flex column layout primitive.                                                                                                                                                  |
+| **Row**         | Flex row layout primitive.                                                                                                                                                     |
+| **CopyButton**  | Button that copies a given string to the clipboard and shows copy/success state. Pass `value` to copy.                                                                         |
+| **Field**       | Form field / sorter wrapper.                                                                                                                                                   |
+| **Filter**      | Single filter unit. Types: `search`, `select`, `autocomplete`, `date`, `numeric`, `checkbox`, `checkboxGroup`, `switch`, `range`. Use with `paramKey` and type-specific props. |
+| **Portal**      | Renders children into a DOM node (e.g. modals, tooltips).                                                                                                                      |
+| **ThemeSwitch** | Toggle between light and dark theme (works with `next-themes`).                                                                                                                |
+| **Uploader**    | File upload with label, listing, and optional avatar mode. Use with `useUpload` and pass the returned props.                                                                   |
+
+**Example — Theme switch**
+
+```tsx
+import { ThemeSwitch } from "@js-empire/emperor-ui";
+
+<ThemeSwitch />;
+```
+
+**Example — Copy button**
+
+```tsx
+import { CopyButton } from "@js-empire/emperor-ui";
+
+<CopyButton value="Text to copy" />;
+```
+
+**Example — Filter**
+
+```tsx
+import { Filter } from "@js-empire/emperor-ui";
+
+<Filter
+  type="search"
+  paramKey="q"
+  searchProps={{ placeholder: "Search..." }}
+/>;
+```
+
+**Example — Uploader**
+
+```tsx
+import { Uploader, useUpload } from "@js-empire/emperor-ui";
 
-- Image
-- Title
-- Subtitle (for description)
-- Price
-- Drop-down with actions and a dots-icon for opening it
+const uploadProps = useUpload({
+  labelId: "uploaded-file",
+  fileTypes: ["image", "pdf"],
+  isRequired: true,
+  isMulti: true,
+});
 
-### Listings
+<Uploader {...uploadProps} />;
+```
 
-- Listing any type of components
-- Pagination or infinite scrolling
-- Specifying the page size
-- View controller: list, grid, carousel (swiper)
+---
+
+### Molecules
+
+| Component    | Description                                                                                                                   |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| **ItemCard** | Card for list/grid items: header, body, footer, optional actions and hover effects. Supports vertical/horizontal orientation. |
+| **NavBar**   | Horizontal navigation with items and optional hover effects.                                                                  |
+| **Scaffold** | Main content wrapper; respects Emperor UI config (e.g. `dir` for RTL).                                                        |
+| **SideBar**  | Collapsible sidebar with drawer on mobile; use with header, items, and trigger.                                               |
+
+**Example — Item card**
+
+```tsx
+import { ItemCard } from "@js-empire/emperor-ui";
+
+<ItemCard
+  item={{ key: "1", title: "Item", subtitle: "Description" }}
+  orientation="vertical"
+  actions={[{ key: "edit", label: "Edit" }]}
+  onActionClick={(key) => console.log(key)}
+/>;
+```
+
+**Example — Scaffold**
+
+```tsx
+import { Scaffold } from "@js-empire/emperor-ui";
+
+<Scaffold>
+  <YourPageContent />
+</Scaffold>;
+```
+
+---
+
+### Organisms
+
+| Component       | Description                                                                                     |
+| --------------- | ----------------------------------------------------------------------------------------------- |
+| **Filters**     | Container for multiple `Filter` components. Children must be `Filter` only.                     |
+| **Footer**      | Site footer with quick links, social links, policies, and copyright.                            |
+| **Header**      | App header with sidebar (drawer on mobile), nav bar, and optional glass effect.                 |
+| **ItemDetails** | Details view block (e.g. breadcrumbs, media, title, price).                                     |
+| **Listings**    | Grid or list of items with `ItemCard`, loading skeletons, empty state, and optional pagination. |
+
+**Example — Filters**
+
+```tsx
+import { Filters, Filter } from "@js-empire/emperor-ui";
+
+<Filters>
+  <Filter type="search" paramKey="q" />
+  <Filter type="select" paramKey="category" options={[...]} />
+</Filters>
+```
+
+**Example — Listings**
 
-### Details page
+```tsx
+import { Listings } from "@js-empire/emperor-ui";
 
-- Breadcrumbs
-- Image or carousel
-- Title
-- Subtitle
-- Description
-- Price
+<Listings
+  items={items}
+  layout="grid"
+  isLoading={isLoading}
+  pagination={{ page: 1, total: 10, pageSize: 12 }}
+/>;
+```
 
-### Filter
+**Example — Header**
+
+```tsx
+import { Header } from "@js-empire/emperor-ui";
+
+<Header variant="default" glassEffect />;
+```
+
+---
+
+### Templates
+
+| Component       | Description                                                     |
+| --------------- | --------------------------------------------------------------- |
+| **LandingPage** | Full landing page layout composing header, content, and footer. |
+
+---
+
+## Documentation & development
+
+- **Storybook** — Run `npm run storybook` to browse and test components locally.
+- **Issues** — [GitHub Issues](https://github.com/MustafaHasanat/emperor-ui/issues)
+- **Repository** — [GitHub](https://github.com/MustafaHasanat/emperor-ui)
+
+---
+
+## Author
+
+**JS Empire — Mustafa Alhasanat**
+
+- [GitHub](https://github.com/MustafaHasanat)
+- [npm](https://www.npmjs.com/~js-empire)
+
+---
 
-- Filter layouts: side box on desktop, drawer on mobile
-- Custom filter items with different types:
-  - search term
-  - checkbox
-  - Multiple checkboxes under an accordion
-  - autocomplete or select box
-- Action buttons: apply filters, reset filters
+<p align="center">
+  <sub>Built with React, HeroUI, and Tailwind.</sub>
+</p>

package/dist/emperor-ui.js

@@ -1,75 +1,123 @@
-import { bB as e, bz as b, bA as o, bg as i, ba as r, bb as l, bQ as t, bc as d, br as E, bJ as p, bR as c, by as n, bx as _, b3 as I, bp as S, bu as g, b4 as C, bn as L, b2 as U, bo as A, c5 as P, c3 as T, c4 as m, c2 as F, c6 as M, b5 as x, b7 as B, bK as u, bS as v, bC as D, c9 as O, bq as N, be as f, c8 as R, bt as K, bd as k, b9 as y, b8 as H, bs as G, b6 as W, bk as Y, bl as h, bh as w, bj as q, bf as z, bL as Q, bT as V, bm as j, bi as J, bU as X, bW as Z, bH as $, bG as aa, bv as sa, bw as ea, bD as ba, bY as oa, c7 as ia, bV as ra, bZ as la, b_ as ta, bX as da, c1 as Ea, bF as pa, bE as ca, c0 as na, bI as _a, bM as Ia, bN as Sa, bP as ga, bO as Ca, b$ as La } from "./index-BY47HgaP.js";
+import { dB as s, dC as i, dD as o, dE as r, dF as t, dG as l, dH as d, dI as E, dJ as C, dK as I, dL as _, dM as n, dN as S, dO as f, dP as M, dQ as p, dR as T, dS as c, dT as g, dU as O, dV as m, dW as F, dX as L, dY as A, dZ as P, d_ as R, d$ as K, e0 as U, e1 as B, e2 as D, e3 as N, e4 as u, e5 as x, e6 as k, e7 as v, e8 as h, e9 as y, ea as G, eb as H, ec as W, ed as b, ee as w, ef as V, eg as Y, eh as q, ei as z, ej as Q, ek as j, el as J, em as X, en as Z, eo as $, ep as ee, eq as ae, er as se, es as ie, et as oe, eu as re, ev as te, ew as le, ex as de, ey as Ee, ez as Ce, eA as Ie, eB as _e, eC as ne, eD as Se, eE as fe, eF as Me, eG as pe, eH as Te, eI as ce, eJ as ge, eK as Oe, eL as me, eM as Fe, eN as Le, eO as Ae, eP as Pe, eQ as Re, eR as Ke, eS as Ue, eT as Be, eU as De, eV as Ne, eW as ue, eX as xe, eY as ke, eZ as ve, e_ as he, e$ as ye, f0 as Ge, f1 as He, f2 as We, f3 as be, f4 as we, f5 as Ve, f6 as Ye, f7 as qe, f8 as ze, f9 as Qe, fa as je, fb as Je, fc as Xe, fd as Ze, fe as $e, ff as ea, fg as aa, fh as sa, fi as ia, fj as oa, fk as ra, fl as ta, fm as la, fn as da, fo as Ea, fp as Ca, fq as Ia, fr as _a, fs as na } from "./index-CDB93OLO.js";
 export {
-  e as ALLOWED_DOC_TYPES,
-  b as ALLOWED_IMAGES_TYPES,
+  s as ALLOWED_DOC_TYPES,
+  i as ALLOWED_IMAGES_TYPES,
   o as ALLOWED_PDF_TYPES,
-  i as AvatarLabel,
-  r as Brand,
-  l as Column,
-  t as ConfigProvider,
-  d as Container,
-  E as CopyRightsBox,
+  r as AutocompleteFilter,
+  t as AvatarLabel,
+  l as Brand,
+  d as CheckboxFilter,
+  E as CheckboxGroupFilter,
+  C as ColorPicker,
+  I as Column,
+  _ as ConfigProvider,
+  n as Container,
+  S as CopyButton,
+  f as CopyRightsBox,
+  M as DateFilter,
   p as EmperorUIContext,
-  c as EmperorUIProvider,
-  n as FAKE_PARAGRAPH,
-  _ as FAKE_SENTENCE,
-  I as Filter,
-  S as Footer,
-  g as Header,
-  C as ItemCard,
-  L as ItemDetails,
-  U as LandingPage,
-  A as Listings,
-  P as MOCK_HEADER_ACTIONS,
-  T as MOCK_HEADER_ITEMS,
-  m as MOCK_HEADER_ITEMS_WITH_SUB_ITEMS,
-  F as MOCK_HEADER_SUB_ITEMS,
-  M as MOCK_LISTINGS,
-  x as NavBar,
-  B as NavBarItem,
-  u as NavigationContext,
-  v as NavigationProvider,
-  D as ONE_MEGABYTE,
-  O as Placeholders,
-  N as PoliciesBox,
-  f as Portal,
-  R as PreservedKeys,
-  K as QuickLinksBox,
-  k as Row,
-  y as Scaffold,
-  H as SideBar,
-  G as SocialLinksBox,
-  W as SubItemsBox,
-  Y as UploadFileErrorBox,
-  h as UploadFileInput,
-  w as UploadFileLabel,
-  q as UploadFileListing,
-  z as Uploader,
-  Q as UploaderContext,
-  V as UploaderProvider,
-  j as UploaderTitle,
-  J as ViewImageModal,
-  X as cn,
-  Z as compressImage,
-  $ as contacts,
-  aa as copyRights,
-  sa as defaultColorsPalette,
-  ea as defaultEmperorUIConfig,
-  ba as fileTypesMapping,
-  oa as getAllowedTypes,
-  ia as getListings,
-  ra as getStorybookDecorators,
-  la as isFileDuplicated,
-  ta as isMaxFileSizeExceeded,
-  da as mapFileType,
-  Ea as mergeLocales,
-  pa as policies,
-  ca as quickLinks,
-  na as refineUploadedFiles,
-  _a as socialLinks,
-  Ia as useEmperorUI,
-  Sa as useNavigation,
-  ga as useUploader,
-  Ca as useUploaderContext,
-  La as validateUploadedFiles
+  T as EmperorUIProvider,
+  c as EmptyListings,
+  g as FAKE_PARAGRAPH,
+  O as FAKE_SENTENCE,
+  m as Field,
+  F as Filter,
+  L as Filters,
+  A as Footer,
+  P as FreeColorPicker,
+  R as Header,
+  K as ITEM_CARD_ACTIONS,
+  U as ItemActionsDropdown,
+  B as ItemBanner,
+  D as ItemCard,
+  N as ItemCardBody,
+  u as ItemCardFooter,
+  x as ItemCardHeader,
+  k as ItemDetails,
+  v as LandingPage,
+  h as Listings,
+  y as LoadingItem,
+  G as MOCK_BASE_DATE,
+  H as MOCK_COLORS,
+  W as MOCK_HEADER_ACTIONS,
+  b as MOCK_HEADER_ITEMS,
+  w as MOCK_HEADER_ITEMS_WITH_SUB_ITEMS,
+  V as MOCK_HEADER_SUB_ITEMS,
+  Y as MOCK_ITEM_BRANDS,
+  q as MOCK_ITEM_CATEGORIES,
+  z as MOCK_ITEM_REVIEWS_1,
+  Q as MOCK_ITEM_REVIEWS_2,
+  j as MOCK_ITEM_REVIEWS_3,
+  J as MOCK_LISTINGS,
+  X as MOCK_LISTING_DESCRIPTIONS,
+  Z as MOCK_LISTING_IMAGES,
+  $ as MOCK_LISTING_TITLES,
+  ee as MOCK_REVIEW_AUTHORS,
+  ae as MOCK_REVIEW_COMMENTS,
+  se as NavBar,
+  ie as NavBarItem,
+  oe as NavigationContext,
+  re as NavigationProvider,
+  te as NumericFilter,
+  le as ONE_MEGABYTE,
+  de as Placeholders,
+  Ee as PoliciesBox,
+  Ce as Portal,
+  Ie as PreservedKeys,
+  _e as PresetColorPicker,
+  ne as QuickLinksBox,
+  Se as RangeFilter,
+  fe as Row,
+  Me as Scaffold,
+  pe as SearchFilter,
+  Te as SelectFilter,
+  ce as SideBar,
+  ge as SocialLinksBox,
+  Oe as SubItemsBox,
+  me as SwitchFilter,
+  Fe as ThemeProvider,
+  Le as ThemeSwitch,
+  Ae as UploadFileErrorBox,
+  Pe as UploadFileInput,
+  Re as UploadFileLabel,
+  Ke as UploadFileListing,
+  Ue as Uploader,
+  Be as UploaderContext,
+  De as UploaderProvider,
+  Ne as UploaderTitle,
+  ue as ViewImageModal,
+  xe as cn,
+  ke as compressImage,
+  ve as contacts,
+  he as copyRights,
+  ye as defaultEmperorUIConfig,
+  Ge as emptyListingsClasses,
+  He as fileTypesMapping,
+  We as filterClasses,
+  be as getAllowedTypes,
+  we as getCardMotion,
+  Ve as getListing,
+  Ye as getListings,
+  qe as getStorybookDecorators,
+  ze as isFileDuplicated,
+  Qe as isMaxFileSizeExceeded,
+  je as listingsClasses,
+  Je as listingsItemClasses,
+  Xe as listingsPaginationClasses,
+  Ze as listingsStyles,
+  $e as mapFileType,
+  ea as mergeLocales,
+  aa as policies,
+  sa as quickLinks,
+  ia as refineUploadedFiles,
+  oa as scaffoldClasses,
+  ra as socialLinks,
+  ta as useEmperorUI,
+  la as useFilters,
+  da as useNavigation,
+  Ea as useSearchParamsHandler,
+  Ca as useUploader,
+  Ia as useUploaderContext,
+  _a as useWindowSize,
+  na as validateUploadedFiles
 };