enjanga-components-library 1.0.4

package/README.md

@@ -0,0 +1,159 @@
+# enjanga-components-library
+
+[![npm version](https://img.shields.io/npm/v/enjanga-components-library?color=blue)](https://www.npmjs.com/package/enjanga-components-library)
+
+A reusable React component library built for Next.js 13+ applications, implementing the IBM Carbon Design System. This library is designed for **consumption only** — JavaScript and CSS files are pre-built, minified, and optimized for production use.
+
+> ⚠️ **Important:** This library is built on top of the [IBM Carbon Design System](https://carbondesignsystem.com/). To function correctly, **Carbon must be installed and configured** in the consuming project.
+
+## 📚 Live Storybook
+
+Explore the interactive documentation and try all components in Storybook, hosted on Chromatic:  
+**[https://6856ac512f4faa67a7d9c5c2-ijmvkylkad.chromatic.com/](https://6856ac512f4faa67a7d9c5c2-ijmvkylkad.chromatic.com/)**
+
+## 🚀 Stack & Features
+
+- **Framework:** Next.js 13+ (App Router), React 18+
+- **Language:** TypeScript
+- **Design System:** IBM Carbon Design System
+- **Styling:** SASS
+- **Development & Testing:** Storybook, Chromatic, React Testing Library, Vitest
+- **Build Tool:** Tsup
+
+## 📦 Installation
+
+1. **Install the library and peer dependencies:**
+
+   ```bash
+   npm install enjanga-components-library next@^15.0.0 react@^18.0.0 react-dom@^18.0.0
+   # or
+   yarn add enjanga-components-library next@^15.0.0 react@^18.0.0 react-dom@^18.0.0
+   ```
+
+2. **Install and configure IBM Carbon:**
+   Follow the [official Carbon React setup guide](https://carbondesignsystem.com/developing/frameworks/react#install).
+   ```bash
+   npm install @carbon/react @carbon/styles
+   # or
+   yarn add @carbon/react @carbon/styles
+   ```
+   Import Carbon’s global styles (e.g., in `app/layout.tsx`):
+   ```tsx
+   import '@carbon/styles/css/index.css';
+   ```
+
+## 🔧 Usage
+
+Import components directly from the package. Only components listed in the public API (`src/components/index.ts`) are exposed.
+
+```tsx
+// Example: Using the ContactButton component
+import { ContactButton } from 'enjanga-components-library';
+
+export default function MyPage() {
+  return <ContactButton text="Get in Touch" />;
+}
+```
+
+✅ **Note:** Component CSS is automatically included — no manual CSS imports needed.
+
+## 🧪 Testing
+
+This library is tested for quality and reliability:
+
+- **Unit Tests**: React Testing Library + Vitest
+- **Interaction Tests**: Covers complex user flows
+- **Accessibility (a11y)**: Validated via Storybook’s a11y addon
+- **Visual Regression**: Chromatic snapshots prevent UI regressions
+
+Run tests locally:
+
+```bash
+yarn test
+# or in watch mode
+yarn test:watch
+```
+
+## 🛠 Development
+
+For contributors and maintainers.
+
+### Prerequisites
+
+- Node.js (LTS recommended)
+- Yarn
+
+### Local Setup
+
+```bash
+git clone https://github.com/ericnjanga/enjanga-components-library.git
+cd enjanga-components-library
+yarn install
+yarn storybook
+```
+
+Visit **http://localhost:6006** to start developing components.
+
+### Key Scripts
+
+| Command                | Description                          |
+| ---------------------- | ------------------------------------ |
+| `yarn storybook`       | Start Storybook dev server           |
+| `yarn build`           | Build the library (TypeScript + CSS) |
+| `yarn build-storybook` | Export static Storybook site         |
+| `yarn chromatic`       | Publish Storybook to Chromatic       |
+| `yarn lint`            | Run ESLint + TypeScript checks       |
+| `yarn format`          | Format code with Prettier            |
+
+### Project Structure
+
+```txt
+enjanga-components-library/
+├── .storybook/        # Storybook config
+├── src/
+│   ├── app/           # Next.js App Router setup
+│   ├── components/    # React components
+│   │   ├── ContactButton/
+│   │   │   ├── ContactButton.tsx
+│   │   │   ├── _ContactButton.scss
+│   │   │   └── index.ts
+│   │   └── index.ts   # Public API (exports components)
+│   ├── stories/       # Storybook stories
+│   ├── tests/         # Component tests
+│   ├── styles/        # Global styles + SASS utilities
+│   └── utils/         # Shared utilities
+├── package.json
+└── tsconfig.json
+```
+
+## 🧠 Philosophy
+
+### Carbon as Foundation
+
+This library builds on [Carbon](https://carbondesignsystem.com/) to create opinionated, purpose-driven components.  
+For example, `ContactButton` wraps Carbon’s `Button`, exposing only a simplified prop API for consistency.
+
+### Design Principles
+
+- **Modularity** – Components built in isolation, easily extended
+- **Reusability** – Single-purpose, but broadly applicable
+- **Robustness** – Strong typing & validated props
+- **Performance** – Memoized components minimize re-renders
+- **Flexibility** – Smart defaults, minimal configuration needed
+
+### Component Types
+
+- **Public Components** – Exported via `src/components/index.ts` (documented, tested, stable)
+- **Internal Components** – Used only inside the library (not exported)
+
+## 📄 License
+
+Licensed under the **Apache License 2.0**. See [LICENSE](./LICENSE).
+
+## 🤝 Contributing
+
+This is primarily a personal portfolio/project library. Contributions are welcome — open an issue before major changes.
+
+## 🐛 Reporting Issues
+
+Please report bugs or request features via [GitHub Issues](https://github.com/ericnjanga/enjanga-components-library/issues).

package/dist/index.d.mts

@@ -0,0 +1,208 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Node } from '@contentful/rich-text-types';
+import { ComponentType, SVGProps } from 'react';
+
+interface AH_propsType {
+    brandLabel: string;
+    brandRoute: string;
+    brand: React.ReactNode;
+    navigation: React.ReactNode;
+    globalBarItems: React.ReactNode;
+}
+
+declare const AppHeader: ({ brand, brandLabel, brandRoute, navigation, }: AH_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const BL_roleOpt: readonly ["img", "presentation", "none"];
+type BL_roleOptPropsType = (typeof BL_roleOpt)[number];
+interface BL_propsType {
+    value: string | React.ReactNode | React.ReactElement;
+    className?: string;
+    style?: React.CSSProperties;
+    alt?: string;
+    role?: BL_roleOptPropsType;
+}
+
+declare const BrandLogo: ({ value, className, style, alt, role, }: BL_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const HDG_levelOpt: readonly [1, 2, 3, 4, 5, 6];
+type HDG_levelPropsType = (typeof HDG_levelOpt)[number];
+type HDG_propsType = {
+    className?: string;
+    level?: HDG_levelPropsType;
+    children?: React.ReactNode;
+};
+
+interface SMT_propsType {
+    className?: string;
+    plainText?: string;
+    richText?: {
+        json: {
+            content: Node[];
+        };
+    };
+}
+
+interface FTX_propsType {
+    className?: string;
+    heading: HDG_propsType;
+    smartText: SMT_propsType;
+    headingMaxLength?: number;
+    plainTextMaxLength?: number;
+    isHidden?: 'heading' | 'smartText';
+}
+
+declare const BNN_roleOpt: readonly ["banner", "presentation", "none"];
+type BNN_roleOptPropsType = (typeof BNN_roleOpt)[number];
+interface BNN_propsType {
+    className?: string;
+    featuredText: FTX_propsType;
+    isHuge?: boolean;
+    role?: BNN_roleOptPropsType;
+}
+
+declare const Banner: ({ className, featuredText, isHuge, role, }: BNN_propsType) => react_jsx_runtime.JSX.Element;
+
+interface CBNN_propsType {
+    btnText: string;
+    btnIcon?: 'Email' | 'Chat' | 'CustomerService' | 'CommunicationUnified';
+    btnKind?: 'primary' | 'secondary';
+    btnSize?: 'sm' | 'md';
+    modalLabel: string;
+    modalHeading: string;
+    modalSubHeading: string;
+    modalPrimaryButtonText: string;
+    modalSecondaryButtonText: string;
+}
+
+declare const ContactButton: ({ btnText, btnIcon, btnKind, btnSize, modalLabel, modalHeading, modalSubHeading, modalPrimaryButtonText, modalSecondaryButtonText, }: CBNN_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const CP_nameOpt: readonly ["Hills", "App Developer", "Leadership", "DevicePairing", "CodeExplanation", "MagicWand", "Question", "User", "UserInterface", "Collaboration", "Presentation", "Transform_01", "Networking_04", "Goals", "TransactionalTrust", "Teacher", "Carbon", "Multitask", "PoughkeepsieBridge", "AssetManagement", "Presenter"];
+declare const CP_sizeOpt: readonly ["sm", "md", "lg", "xl"];
+type CP_nameType = (typeof CP_nameOpt)[number];
+type CP_sizeType = (typeof CP_sizeOpt)[number];
+interface CP_propsType {
+    name: CP_nameType;
+    size?: CP_sizeType;
+    className?: string;
+}
+
+declare const CustomPictogram: ({ name, size, className }: CP_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const CP_pictogramMap: Record<CP_nameType, // CP_propsType['name'],
+ComponentType<SVGProps<SVGSVGElement>>>;
+declare const CP_getPictogram: ({ name, }: {
+    name: string;
+}) => ComponentType<SVGProps<SVGSVGElement>>;
+
+/**
+ * Props validations rules
+ * ----------
+ * CustomTile must be either:
+ * - A link (provide 'linksTo' and optionally 'linkTarget')
+ * - A modal trigger (provide 'modalIsAvailable')
+ * But cannot be both at the same time
+ */
+type ErrorMessage<T extends string> = `🚨 Prop Validation Error: ${T}`;
+/** Normal link props (default case, modalIsAvailable omitted or false) */
+interface LinkProps {
+    linksTo?: CTL_valid_linkTo;
+    linkTarget?: CTL_LinkTargetType;
+    modalIsAvailable?: false;
+}
+/** Strict modal props (only when true) */
+interface ModalProps {
+    modalIsAvailable: true;
+    linksTo?: ErrorMessage<"Modal version cannot have 'linksTo' - remove this prop">;
+    linkTarget?: ErrorMessage<"Modal version cannot have 'linkTarget' - remove this prop">;
+}
+type CTL_propsType1Validation = LinkProps | ModalProps;
+
+declare const CTL_LayoutStyleOpt: readonly ["card", "banner"];
+declare const CTL_LinkTargetOpt: readonly ["_blank", "_self"];
+declare const CTL_MediaOpt: readonly ["pictogram", "image"];
+type CTL_LayoutStyleType = (typeof CTL_LayoutStyleOpt)[number];
+type CTL_LinkTargetType = (typeof CTL_LinkTargetOpt)[number];
+type CTL_MediaType = (typeof CTL_MediaOpt)[number];
+
+type ValidRoute = `/${string}`;
+type ExternalLink = `https://${string}` | `http://${string}`;
+type CTL_valid_linkTo = ValidRoute | ExternalLink;
+type CTL_propsType = {
+    className?: string;
+    featuredText: FTX_propsType;
+    layoutStyle?: CTL_LayoutStyleType;
+    media?: CTL_MediaType;
+    mediaPictogram?: CP_nameType;
+    mediaImage?: string;
+    modalIsAvailable?: boolean;
+    modalPlainDescription?: string;
+    modalRichDescription?: {
+        json: {
+            content: Node[];
+        };
+    };
+    linksTo?: CTL_valid_linkTo;
+    linkTarget?: CTL_LinkTargetType;
+} & CTL_propsType1Validation;
+
+declare const CustomTile: ({ className, featuredText, layoutStyle, media, mediaPictogram, mediaImage, modalIsAvailable, modalPlainDescription, modalRichDescription, linksTo, linkTarget, }: CTL_propsType) => react_jsx_runtime.JSX.Element;
+
+interface LIT_propsType {
+    content?: string;
+    href?: string;
+    id?: string;
+    className?: string;
+    children?: React.ReactNode;
+}
+
+declare const LST_typeOpt: readonly ["unordered", "ordered"];
+type LST_typePropsType = (typeof LST_typeOpt)[number];
+interface LST_propsType {
+    type?: LST_typePropsType;
+    className?: string;
+    content?: LIT_propsType[];
+}
+
+declare const HDL_tagOpt: readonly ["div", "section"];
+type HDL_tagPropsType = (typeof HDL_tagOpt)[number];
+interface HDL_propsType {
+    wrapper?: {
+        tag: HDL_tagPropsType;
+        cssClass?: string;
+    };
+    heading: HDG_propsType;
+    list?: LST_propsType;
+}
+
+declare const HeadlinedList: ({ wrapper, heading, list, }: HDL_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const List: ({ type, className, content }: LST_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const SmartText: ({ className, plainText, richText }: SMT_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const FeatureText: ({ className, heading, smartText, headingMaxLength, plainTextMaxLength, isHidden, }: FTX_propsType) => react_jsx_runtime.JSX.Element;
+
+interface CRT_propsType {
+    className?: string;
+    data?: {
+        json: {
+            content: Node[];
+        };
+        links?: {
+            assets: {
+                block: {
+                    sys: {
+                        id: string;
+                    };
+                    url: string;
+                    title: string;
+                    description?: string;
+                }[];
+            };
+        };
+    };
+}
+
+declare const CMSRichText: ({ data, className }: CRT_propsType) => react_jsx_runtime.JSX.Element;
+
+export { AppHeader, Banner, BrandLogo, CMSRichText, CP_getPictogram, type CP_nameType, CP_pictogramMap, type CTL_valid_linkTo, ContactButton, CustomPictogram, CustomTile, FeatureText, HeadlinedList, List, SmartText };

package/dist/index.d.ts

@@ -0,0 +1,208 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Node } from '@contentful/rich-text-types';
+import { ComponentType, SVGProps } from 'react';
+
+interface AH_propsType {
+    brandLabel: string;
+    brandRoute: string;
+    brand: React.ReactNode;
+    navigation: React.ReactNode;
+    globalBarItems: React.ReactNode;
+}
+
+declare const AppHeader: ({ brand, brandLabel, brandRoute, navigation, }: AH_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const BL_roleOpt: readonly ["img", "presentation", "none"];
+type BL_roleOptPropsType = (typeof BL_roleOpt)[number];
+interface BL_propsType {
+    value: string | React.ReactNode | React.ReactElement;
+    className?: string;
+    style?: React.CSSProperties;
+    alt?: string;
+    role?: BL_roleOptPropsType;
+}
+
+declare const BrandLogo: ({ value, className, style, alt, role, }: BL_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const HDG_levelOpt: readonly [1, 2, 3, 4, 5, 6];
+type HDG_levelPropsType = (typeof HDG_levelOpt)[number];
+type HDG_propsType = {
+    className?: string;
+    level?: HDG_levelPropsType;
+    children?: React.ReactNode;
+};
+
+interface SMT_propsType {
+    className?: string;
+    plainText?: string;
+    richText?: {
+        json: {
+            content: Node[];
+        };
+    };
+}
+
+interface FTX_propsType {
+    className?: string;
+    heading: HDG_propsType;
+    smartText: SMT_propsType;
+    headingMaxLength?: number;
+    plainTextMaxLength?: number;
+    isHidden?: 'heading' | 'smartText';
+}
+
+declare const BNN_roleOpt: readonly ["banner", "presentation", "none"];
+type BNN_roleOptPropsType = (typeof BNN_roleOpt)[number];
+interface BNN_propsType {
+    className?: string;
+    featuredText: FTX_propsType;
+    isHuge?: boolean;
+    role?: BNN_roleOptPropsType;
+}
+
+declare const Banner: ({ className, featuredText, isHuge, role, }: BNN_propsType) => react_jsx_runtime.JSX.Element;
+
+interface CBNN_propsType {
+    btnText: string;
+    btnIcon?: 'Email' | 'Chat' | 'CustomerService' | 'CommunicationUnified';
+    btnKind?: 'primary' | 'secondary';
+    btnSize?: 'sm' | 'md';
+    modalLabel: string;
+    modalHeading: string;
+    modalSubHeading: string;
+    modalPrimaryButtonText: string;
+    modalSecondaryButtonText: string;
+}
+
+declare const ContactButton: ({ btnText, btnIcon, btnKind, btnSize, modalLabel, modalHeading, modalSubHeading, modalPrimaryButtonText, modalSecondaryButtonText, }: CBNN_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const CP_nameOpt: readonly ["Hills", "App Developer", "Leadership", "DevicePairing", "CodeExplanation", "MagicWand", "Question", "User", "UserInterface", "Collaboration", "Presentation", "Transform_01", "Networking_04", "Goals", "TransactionalTrust", "Teacher", "Carbon", "Multitask", "PoughkeepsieBridge", "AssetManagement", "Presenter"];
+declare const CP_sizeOpt: readonly ["sm", "md", "lg", "xl"];
+type CP_nameType = (typeof CP_nameOpt)[number];
+type CP_sizeType = (typeof CP_sizeOpt)[number];
+interface CP_propsType {
+    name: CP_nameType;
+    size?: CP_sizeType;
+    className?: string;
+}
+
+declare const CustomPictogram: ({ name, size, className }: CP_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const CP_pictogramMap: Record<CP_nameType, // CP_propsType['name'],
+ComponentType<SVGProps<SVGSVGElement>>>;
+declare const CP_getPictogram: ({ name, }: {
+    name: string;
+}) => ComponentType<SVGProps<SVGSVGElement>>;
+
+/**
+ * Props validations rules
+ * ----------
+ * CustomTile must be either:
+ * - A link (provide 'linksTo' and optionally 'linkTarget')
+ * - A modal trigger (provide 'modalIsAvailable')
+ * But cannot be both at the same time
+ */
+type ErrorMessage<T extends string> = `🚨 Prop Validation Error: ${T}`;
+/** Normal link props (default case, modalIsAvailable omitted or false) */
+interface LinkProps {
+    linksTo?: CTL_valid_linkTo;
+    linkTarget?: CTL_LinkTargetType;
+    modalIsAvailable?: false;
+}
+/** Strict modal props (only when true) */
+interface ModalProps {
+    modalIsAvailable: true;
+    linksTo?: ErrorMessage<"Modal version cannot have 'linksTo' - remove this prop">;
+    linkTarget?: ErrorMessage<"Modal version cannot have 'linkTarget' - remove this prop">;
+}
+type CTL_propsType1Validation = LinkProps | ModalProps;
+
+declare const CTL_LayoutStyleOpt: readonly ["card", "banner"];
+declare const CTL_LinkTargetOpt: readonly ["_blank", "_self"];
+declare const CTL_MediaOpt: readonly ["pictogram", "image"];
+type CTL_LayoutStyleType = (typeof CTL_LayoutStyleOpt)[number];
+type CTL_LinkTargetType = (typeof CTL_LinkTargetOpt)[number];
+type CTL_MediaType = (typeof CTL_MediaOpt)[number];
+
+type ValidRoute = `/${string}`;
+type ExternalLink = `https://${string}` | `http://${string}`;
+type CTL_valid_linkTo = ValidRoute | ExternalLink;
+type CTL_propsType = {
+    className?: string;
+    featuredText: FTX_propsType;
+    layoutStyle?: CTL_LayoutStyleType;
+    media?: CTL_MediaType;
+    mediaPictogram?: CP_nameType;
+    mediaImage?: string;
+    modalIsAvailable?: boolean;
+    modalPlainDescription?: string;
+    modalRichDescription?: {
+        json: {
+            content: Node[];
+        };
+    };
+    linksTo?: CTL_valid_linkTo;
+    linkTarget?: CTL_LinkTargetType;
+} & CTL_propsType1Validation;
+
+declare const CustomTile: ({ className, featuredText, layoutStyle, media, mediaPictogram, mediaImage, modalIsAvailable, modalPlainDescription, modalRichDescription, linksTo, linkTarget, }: CTL_propsType) => react_jsx_runtime.JSX.Element;
+
+interface LIT_propsType {
+    content?: string;
+    href?: string;
+    id?: string;
+    className?: string;
+    children?: React.ReactNode;
+}
+
+declare const LST_typeOpt: readonly ["unordered", "ordered"];
+type LST_typePropsType = (typeof LST_typeOpt)[number];
+interface LST_propsType {
+    type?: LST_typePropsType;
+    className?: string;
+    content?: LIT_propsType[];
+}
+
+declare const HDL_tagOpt: readonly ["div", "section"];
+type HDL_tagPropsType = (typeof HDL_tagOpt)[number];
+interface HDL_propsType {
+    wrapper?: {
+        tag: HDL_tagPropsType;
+        cssClass?: string;
+    };
+    heading: HDG_propsType;
+    list?: LST_propsType;
+}
+
+declare const HeadlinedList: ({ wrapper, heading, list, }: HDL_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const List: ({ type, className, content }: LST_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const SmartText: ({ className, plainText, richText }: SMT_propsType) => react_jsx_runtime.JSX.Element;
+
+declare const FeatureText: ({ className, heading, smartText, headingMaxLength, plainTextMaxLength, isHidden, }: FTX_propsType) => react_jsx_runtime.JSX.Element;
+
+interface CRT_propsType {
+    className?: string;
+    data?: {
+        json: {
+            content: Node[];
+        };
+        links?: {
+            assets: {
+                block: {
+                    sys: {
+                        id: string;
+                    };
+                    url: string;
+                    title: string;
+                    description?: string;
+                }[];
+            };
+        };
+    };
+}
+
+declare const CMSRichText: ({ data, className }: CRT_propsType) => react_jsx_runtime.JSX.Element;
+
+export { AppHeader, Banner, BrandLogo, CMSRichText, CP_getPictogram, type CP_nameType, CP_pictogramMap, type CTL_valid_linkTo, ContactButton, CustomPictogram, CustomTile, FeatureText, HeadlinedList, List, SmartText };