@universityofmaryland/web-elements-library 1.2.0 → 1.3.0

package/README.md

@@ -0,0 +1,518 @@
+# University of Maryland Web Elements Library
+
+[![Elements Version](https://img.shields.io/badge/Elements-v1.3.0-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.
+
+## Installation
+
+```bash
+# Using npm
+npm install @universityofmaryland/web-elements-library
+
+# Using yarn
+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
+
+```javascript
+// Import specific element categories
+import { Atomic, Composite, Layout } from '@universityofmaryland/web-elements-library';
+
+// Example: Using an atomic element
+const buttonElement = Atomic.actions.text({
+  text: 'Click Me',
+  url: '#',
+  isStyled: true
+});
+
+// Add the element to the DOM
+document.body.appendChild(buttonElement.element);
+```
+
+## Element Categories
+
+The library organizes elements into several categories:
+
+### Atomic Elements
+
+Atomic elements are the most basic building blocks that cannot be broken down further:
+
+```javascript
+import { Atomic } from '@universityofmaryland/web-elements-library';
+
+// Actions
+const buttonElement = Atomic.actions.text({
+  text: 'Learn More',
+  url: '/learn-more',
+  isStyled: true
+});
+
+// Assets
+const imageElement = Atomic.assets.image.background({
+  image: document.querySelector('img'),
+  isScaled: true
+});
+```
+
+Available atomic elements:
+- `actions` - Buttons and interactive elements
+- `animations` - Animation elements
+- `assets` - Images, icons, and media elements
+- `buttons` - Button variations
+- `events` - Event-related elements
+- `layout` - Basic layout elements
+- `textLockup` - Text grouping elements
+
+### Composite Elements
+
+Composite elements are combinations of atomic elements that form more complex UI patterns:
+
+```javascript
+import { Composite } from '@universityofmaryland/web-elements-library';
+
+const cardElement = Composite.card.block({
+  headline: document.querySelector('h3'),
+  text: document.querySelector('p'),
+  image: document.querySelector('img'),
+  actions: document.querySelector('.actions')
+});
+```
+
+Available composite elements:
+- `accordion` - Expandable content sections
+- `alert` - Alert/notification elements
+- `banner` - Banner elements
+- `card` - Card elements (block, list, overlay)
+- `carousel` - Carousel/slider elements
+- `hero` - Hero section elements (see detailed section below)
+- `layout` - Layout compositions
+- `media` - Media display elements
+- `navigation` - Navigation elements
+- `pathway` - Pathway/journey elements
+- `person` - Person/profile elements
+- `quote` - Quote display elements
+- `slider` - Slider 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:
+
+```javascript
+import { Layout } from '@universityofmaryland/web-elements-library';
+
+const imageLayout = Layout.image({
+  image: document.querySelector('img'),
+  align: 'left'
+});
+```
+
+### Model Elements
+
+Elements for creating and interacting with the component model:
+
+```javascript
+import { Model } from '@universityofmaryland/web-elements-library';
+
+// Create model elements
+const actionElement = Model.elements.actions({ url: '#', text: 'Click' });
+```
+
+### Utilities
+
+Helper functions for working with elements:
+
+```javascript
+import { Utilities } from '@universityofmaryland/web-elements-library';
+
+// Accessibility utilities
+Utilities.accessibility.focusable(element);
+
+// DOM manipulation
+Utilities.markup.create.element('div', { class: 'container' });
+```
+
+## Element Structure
+
+Most elements return an object with the following properties:
+
+```javascript
+{
+  element: HTMLElement, // The DOM element
+  styles: string,       // CSS styles associated with the element
+  update: Function,     // Method to update element properties
+  destroy: Function,    // Method to clean up and remove element
+  // Other element-specific properties
+}
+```
+
+Example of using the update method:
+
+```javascript
+const button = Atomic.buttons.primary({
+  text: 'Learn More',
+  url: '#'
+});
+
+// Update properties later
+button.update({
+  text: 'View Details',
+  isDisabled: true
+});
+```
+
+## Browser Support
+
+This library supports all modern browsers, including:
+- Chrome
+- Firefox
+- Safari
+- Edge
+
+## Performance Considerations
+
+The Elements library is designed with performance in mind:
+- Tree-shakable imports to reduce bundle size
+- Optimized rendering through element reuse
+- Minimal DOM operations for updates
+- Efficient event handling patterns
+
+## Accessibility
+
+All elements are built with accessibility as a priority:
+- WCAG 2.1 AA compliant
+- Proper semantic markup
+- ARIA attributes where appropriate
+- Keyboard navigation support
+- Focus management utilities
+
+## Documentation
+
+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.
+
+## License
+
+This project is licensed under the University of Maryland license.

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"}