@universityofmaryland/web-elements-library 1.2.1 → 1.3.1

package/README.md

@@ -1,6 +1,6 @@
 # University of Maryland Web Elements Library
 
-[![Elements Version](https://img.shields.io/badge/Elements-v1.2.1-blue)](https://www.npmjs.com/package/@universityofmaryland/web-elements-library)
+[![Elements Version](https://img.shields.io/badge/Elements-v1.3.1-blue)](https://www.npmjs.com/package/@universityofmaryland/web-elements-library)
 
 Foundational UI elements that make up the University of Maryland Components Library. This library provides the building blocks used to create more complex UI components while maintaining consistent design patterns across all UMD digital properties. Elements are crafted to be lightweight, accessible, and easily combinable into larger structures while adhering to UMD brand guidelines.
 
@@ -14,6 +14,30 @@ npm install @universityofmaryland/web-elements-library
 yarn add @universityofmaryland/web-elements-library
 ```
 
+## Quick Start
+
+Here's a simple example to get you started with the Elements library:
+
+```javascript
+import { Composite } from '@universityofmaryland/web-elements-library';
+
+// Create a hero section
+const hero = Composite.hero.standard({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  image: document.querySelector('img'),
+  isThemeDark: true
+});
+
+// Add the hero to your page
+document.getElementById('hero-container').appendChild(hero.element);
+
+// Inject the associated styles
+const styleElement = document.createElement('style');
+styleElement.textContent = hero.styles;
+document.head.appendChild(styleElement);
+```
+
 ## Usage
 
 ### Importing Elements
@@ -88,7 +112,7 @@ Available composite elements:
 - `banner` - Banner elements
 - `card` - Card elements (block, list, overlay)
 - `carousel` - Carousel/slider elements
-- `hero` - Hero section elements
+- `hero` - Hero section elements (see detailed section below)
 - `layout` - Layout compositions
 - `media` - Media display elements
 - `navigation` - Navigation elements
@@ -99,6 +123,171 @@ Available composite elements:
 - `social` - Social media elements
 - `tabs` - Tabbed interface elements
 
+#### Hero Elements
+
+The hero category provides multiple variations for creating impactful page headers and feature sections:
+
+##### Standard Hero
+The default hero pattern with flexible content and media options:
+
+```javascript
+const heroStandard = Composite.hero.standard({
+  headline: document.createElement('h1'),
+  eyebrow: document.createElement('span'),
+  text: document.createElement('p'),
+  actions: document.createElement('div'),
+  image: document.querySelector('img'),
+  video: document.querySelector('video'),
+  includesAnimation: true,
+  isHeightSmall: false,
+  isHeightFull: false,
+  isTextCenter: false,
+  isTextRight: false,
+  isThemeDark: true
+});
+```
+
+##### Minimal Hero
+A simplified hero with essential content only:
+
+```javascript
+const heroMinimal = Composite.hero.minimal({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  eyebrow: document.createElement('span'),
+  isThemeDark: false
+});
+```
+
+##### Stacked Hero
+Hero with vertically stacked content and media:
+
+```javascript
+const heroStacked = Composite.hero.stacked({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  image: document.querySelector('img'),
+  includesAnimation: true,
+  isHeightSmall: false,
+  isHeightFull: true,
+  isWidthLarge: true,  // Stacked-specific property
+  isThemeDark: true
+});
+```
+
+##### Overlay Hero
+Hero with overlay effects and advanced styling options:
+
+```javascript
+const heroOverlay = Composite.hero.overlay({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  image: document.querySelector('img'),
+  hasBorder: true,
+  isTransparent: false,
+  isSticky: false,
+  isTextCenter: true,
+  isThemeDark: true
+});
+```
+
+##### Logo Hero
+Hero featuring institutional branding:
+
+```javascript
+const heroLogo = Composite.hero.logo({
+  headline: document.createElement('h1'),
+  logo: document.createElement('div'), // Logo element
+  text: document.createElement('p'),
+  actions: document.createElement('div'),
+  image: document.querySelector('img'),
+  isThemeDark: true,
+  isThemeLight: false,
+  isThemeMaryland: false
+});
+```
+
+##### Custom Hero Variations
+
+The library also provides specialized hero patterns for specific use cases:
+
+###### Expand Hero
+Hero with expandable content sections:
+
+```javascript
+const heroExpand = Composite.hero.custom.expand({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  expandedContent: document.createElement('div'), // Content revealed on expand
+  includesAnimation: true,
+  isThemeDark: true
+});
+```
+
+###### Grid Hero
+Hero with content blocks arranged in a grid:
+
+```javascript
+const heroGrid = Composite.hero.custom.grid({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  blocks: [
+    document.createElement('div'), // Grid block 1
+    document.createElement('div'), // Grid block 2
+    document.createElement('div'), // Grid block 3
+    document.createElement('div')  // Grid block 4
+  ],
+  image: document.querySelector('img'),
+  isThemeDark: true
+});
+```
+
+###### Video Arrow Hero
+Hero with prominent video playback controls:
+
+```javascript
+const heroVideoArrow = Composite.hero.custom.videoArrow({
+  headline: document.createElement('h1'),
+  text: document.createElement('p'),
+  video: document.querySelector('video'),
+  image: document.querySelector('img'), // Poster image
+  videoControls: true,
+  includesAnimation: true,
+  isThemeDark: true
+});
+```
+
+##### Hero Properties Reference
+
+Common properties across hero variants:
+- `headline` - Main heading element
+- `eyebrow` - Small text above headline
+- `text` - Descriptive paragraph text
+- `actions` - CTA buttons or links
+- `image` - Hero image element
+- `video` - Hero video element
+- `includesAnimation` - Enable entrance animations
+- `isThemeDark` - Dark theme styling
+
+Size properties (Standard, Stacked, Overlay):
+- `isHeightSmall` - Reduced height variant
+- `isHeightFull` - Full viewport height
+
+Layout properties (Standard, Overlay):
+- `isTextCenter` - Center-aligned text
+- `isTextRight` - Right-aligned text
+
+Theme properties (Logo):
+- `isThemeLight` - Light theme variant
+- `isThemeMaryland` - Maryland brand theme
+
+Unique properties:
+- `isWidthLarge` (Stacked) - Extended width layout
+- `hasBorder`, `isTransparent`, `isSticky` (Overlay) - Styling options
+- `expandedContent` (Expand) - Hidden content section
+- `blocks` (Grid) - Array of content blocks
+- `videoControls` (Video Arrow) - Show video controls
+
 ### Layout Elements
 
 Elements specifically designed for controlling page layout:
@@ -195,6 +384,131 @@ All elements are built with accessibility as a priority:
 
 For complete documentation of all available elements and their options, see the [official UMD Design System documentation](https://umd-digital.github.io/design-system/).
 
+## Testing
+
+The Elements library includes comprehensive test coverage for all components. Tests are written using Jest and follow a consistent pattern:
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run specific test file
+npm test -- source/composite/__tests__/hero/standard.test.ts
+```
+
+### Test Structure
+
+Tests are organized by component category and located in `__tests__` directories:
+
+```
+source/
+├── composite/
+│   └── __tests__/
+│       ├── hero/
+│       │   ├── standard.test.ts
+│       │   ├── minimal.test.ts
+│       │   ├── stacked.test.ts
+│       │   ├── overlay.test.ts
+│       │   ├── logo.test.ts
+│       │   └── custom/
+│       │       ├── expand.test.ts
+│       │       ├── grid.test.ts
+│       │       └── video-arrow.test.ts
+│       ├── card/
+│       │   ├── block.test.ts
+│       │   ├── list.test.ts
+│       │   └── overlay.test.ts
+│       └── types/
+│           ├── hero-types.test.ts
+│           └── card-types.test.ts
+```
+
+### Writing Tests
+
+When adding new elements, include tests that cover:
+
+1. **Basic Structure** - Element creation with minimal props
+2. **Content Properties** - All content variations
+3. **Asset Properties** - Image and video handling
+4. **Animation Properties** - Animation flags and behaviors
+5. **Theme Properties** - Theme variations
+6. **Edge Cases** - Null/undefined handling
+7. **Type Safety** - TypeScript interface compliance
+
+Example test pattern:
+
+```javascript
+import { Composite } from '@universityofmaryland/web-elements-library';
+import type { HeroStandardProps } from '../../hero/_types';
+
+describe('Hero Standard Component', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should create a standard hero with minimal props', () => {
+    const props: HeroStandardProps = {
+      isThemeDark: true
+    };
+    
+    const result = Composite.hero.standard(props);
+    
+    expect(result).toBeDefined();
+    expect(result.element).toBeInstanceOf(HTMLElement);
+    expect(typeof result.styles).toBe('string');
+  });
+});
+```
+
+## TypeScript Support
+
+The library is written in TypeScript and provides comprehensive type definitions for all elements:
+
+### Import Types
+
+```typescript
+import type {
+  HeroStandardProps,
+  HeroMinimalProps,
+  HeroStackedProps,
+  HeroOverlayProps,
+  HeroLogoProps,
+  HeroGridProps,
+  HeroExpandProps,
+  HeroVideoArrowProps,
+  CardBlockProps,
+  CardListProps,
+  CardOverlayProps
+} from '@universityofmaryland/web-elements-library';
+```
+
+### Type Safety
+
+All element functions are strictly typed to ensure proper usage:
+
+```typescript
+// TypeScript will enforce required properties
+const hero: HeroStandardProps = {
+  headline: document.createElement('h1'),
+  // isThemeDark is optional with boolean type
+  isThemeDark: true
+};
+
+// Type error if invalid property is provided
+const invalidHero: HeroStandardProps = {
+  headline: document.createElement('h1'),
+  invalidProp: true // TypeScript error
+};
+```
+
 ## Contributing
 
 For contribution guidelines, please refer to the main repository README.

package/dist/__tests__/examples/component-test.example.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=component-test.example.d.ts.map

package/dist/__tests__/examples/component-test.example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-test.example.d.ts","sourceRoot":"","sources":["../../../source/__tests__/examples/component-test.example.ts"],"names":[],"mappings":""}

package/dist/__tests__/fixtures/content.d.ts

@@ -0,0 +1,62 @@
+export declare const testContent: {
+    text: {
+        headline: string;
+        subheadline: string;
+        eyebrow: string;
+        description: string;
+        longDescription: string;
+        cta: string;
+    };
+    urls: {
+        internal: string;
+        external: string;
+        anchor: string;
+        image: string;
+        video: string;
+        document: string;
+    };
+    media: {
+        image: {
+            src: string;
+            alt: string;
+            srcset: string;
+        };
+        video: {
+            src: string;
+            poster: string;
+            sources: {
+                src: string;
+                type: string;
+            }[];
+        };
+    };
+    person: {
+        name: string;
+        title: string;
+        description: string;
+        email: string;
+        phone: string;
+        image: string;
+        link: string;
+    };
+    event: {
+        title: string;
+        date: Date;
+        location: string;
+        description: string;
+        link: string;
+    };
+    lists: {
+        links: {
+            text: string;
+            url: string;
+        }[];
+        items: string[];
+        social: {
+            platform: string;
+            url: string;
+        }[];
+    };
+};
+export default testContent;
+//# sourceMappingURL=content.d.ts.map

package/dist/__tests__/fixtures/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../../source/__tests__/fixtures/content.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwEvB,CAAC;AAEF,eAAe,WAAW,CAAC"}

package/dist/__tests__/fixtures/elements.d.ts

@@ -0,0 +1,48 @@
+export declare function createContainer(className?: string): HTMLElement;
+export declare function createCardStructure(): {
+    container: HTMLElement;
+    image: HTMLImageElement;
+    content: HTMLElement;
+    headline: HTMLElement;
+    description: HTMLElement;
+    link: HTMLAnchorElement;
+};
+export declare function createHeroStructure(): {
+    container: HTMLElement;
+    background: HTMLElement;
+    content: HTMLElement;
+    headline: HTMLElement;
+    subheadline: HTMLElement;
+    description: HTMLElement;
+    cta: HTMLAnchorElement;
+};
+export declare function createListStructure(itemCount?: number): {
+    container: HTMLElement;
+    items: HTMLElement[];
+};
+export declare function createMediaStructure(type?: 'image' | 'video'): {
+    container: HTMLElement;
+    media: HTMLImageElement | HTMLVideoElement;
+    caption: HTMLElement;
+};
+export declare function createNavStructure(): {
+    nav: HTMLElement;
+    list: HTMLElement;
+    items: HTMLCollection;
+};
+export declare function createFormStructure(): {
+    form: HTMLFormElement;
+    input: HTMLInputElement;
+    button: HTMLButtonElement;
+};
+declare const _default: {
+    createContainer: typeof createContainer;
+    createCardStructure: typeof createCardStructure;
+    createHeroStructure: typeof createHeroStructure;
+    createListStructure: typeof createListStructure;
+    createMediaStructure: typeof createMediaStructure;
+    createNavStructure: typeof createNavStructure;
+    createFormStructure: typeof createFormStructure;
+};
+export default _default;
+//# sourceMappingURL=elements.d.ts.map

package/dist/__tests__/fixtures/elements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"elements.d.ts","sourceRoot":"","sources":["../../../source/__tests__/fixtures/elements.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,WAAW,CAK/D;AAKD,wBAAgB,mBAAmB;;;;;;;EAgBlC;AAKD,wBAAgB,mBAAmB;;;;;;;;EAkBlC;AAKD,wBAAgB,mBAAmB,CAAC,SAAS,GAAE,MAAU;;;EAaxD;AAKD,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,OAAO,GAAG,OAAiB;;;;EAWrE;AAKD,wBAAgB,kBAAkB;;;;EAmBjC;AAKD,wBAAgB,mBAAmB;;;;EAoBlC;;;;;;;;;;AAED,wBAQE"}

package/dist/__tests__/helpers/element.d.ts

@@ -0,0 +1,23 @@
+import type { ContentElement, ElementModel } from '../../_types';
+export interface TestElementConfig {
+    element?: HTMLElement;
+    className?: string;
+    styles?: string;
+    attributes?: Record<string, string>;
+}
+export declare function createElement(tagName?: string, content?: string, attributes?: Record<string, string>): HTMLElement;
+export declare function createContentElement(tagName?: string, content?: string): ContentElement;
+export declare function createImageElement(src?: string, alt?: string): HTMLImageElement;
+export declare function createVideoElement(src?: string): HTMLVideoElement;
+export declare function createLinkElement(href?: string, text?: string): HTMLAnchorElement;
+export declare function validateElementStructure(result: any, expectedConfig: {
+    hasElement?: boolean;
+    hasStyles?: boolean;
+    className?: string;
+    tagName?: string;
+}): void;
+export declare function getChildByClass(parent: HTMLElement, className: string): HTMLElement | null;
+export declare function countChildren(parent: HTMLElement): number;
+export declare function containsText(element: HTMLElement, text: string): boolean;
+export declare function createMockElementModel(config?: TestElementConfig): ElementModel;
+//# sourceMappingURL=element.d.ts.map

package/dist/__tests__/helpers/element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../../source/__tests__/helpers/element.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjE,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAKD,wBAAgB,aAAa,CAC3B,OAAO,GAAE,MAAc,EACvB,OAAO,CAAC,EAAE,MAAM,EAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,WAAW,CAcb;AAKD,wBAAgB,oBAAoB,CAClC,OAAO,GAAE,MAAY,EACrB,OAAO,CAAC,EAAE,MAAM,GACf,cAAc,CAGhB;AAKD,wBAAgB,kBAAkB,CAChC,GAAG,GAAE,MAAmB,EACxB,GAAG,GAAE,MAAqB,GACzB,gBAAgB,CAKlB;AAKD,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAmB,GAAG,gBAAgB,CAI7E;AAKD,wBAAgB,iBAAiB,CAC/B,IAAI,GAAE,MAAY,EAClB,IAAI,GAAE,MAAoB,GACzB,iBAAiB,CAKnB;AAKD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,GAAG,EACX,cAAc,EAAE;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GACA,IAAI,CAsBN;AAKD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,MAAM,GAChB,WAAW,GAAG,IAAI,CAEpB;AAKD,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,CAEzD;AAKD,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAExE;AAKD,wBAAgB,sBAAsB,CACpC,MAAM,GAAE,iBAAsB,GAC7B,YAAY,CAKd"}

package/dist/__tests__/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export * from './element';
+//# sourceMappingURL=index.d.ts.map

package/dist/__tests__/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../source/__tests__/helpers/index.ts"],"names":[],"mappings":"AAKA,cAAc,WAAW,CAAC"}

package/dist/__tests__/helpers/setup.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=setup.d.ts.map

package/dist/__tests__/helpers/setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../../source/__tests__/helpers/setup.ts"],"names":[],"mappings":""}

package/dist/__tests__/jest.setup.d.ts

@@ -0,0 +1,6 @@
+import './helpers/setup';
+declare global {
+    const testUtils: typeof import('./utils');
+    const testHelpers: typeof import('./helpers');
+}
+//# sourceMappingURL=jest.setup.d.ts.map

package/dist/__tests__/jest.setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jest.setup.d.ts","sourceRoot":"","sources":["../../source/__tests__/jest.setup.ts"],"names":[],"mappings":"AAMA,OAAO,iBAAiB,CAAC;AAOzB,OAAO,CAAC,MAAM,CAAC;IACb,MAAM,SAAS,EAAE,cAAc,SAAS,CAAC,CAAC;IAC1C,MAAM,WAAW,EAAE,cAAc,WAAW,CAAC,CAAC;CAC/C"}