@universityofmaryland/web-elements-library 1.3.6 → 1.4.0

package/README.md

@@ -1,8 +1,12 @@
 # University of Maryland Web Elements Library
 
-[![Elements Version](https://img.shields.io/badge/Elements-v1.3.6-blue)](https://www.npmjs.com/package/@universityofmaryland/web-elements-library)
+[![Elements Version](https://img.shields.io/badge/Elements-v1.4.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.
+Foundational UI building blocks for the UMD Design System, providing atomic elements that combine to create complex, accessible, and brand-compliant University of Maryland digital experiences.
+
+## Overview
+
+The UMD Web Elements Library provides the essential building blocks used to construct the UMD Web Components Library. Think of elements as atoms in a design system - they are the smallest, indivisible units that maintain meaning and functionality. These elements handle core UI patterns like buttons, images, text layouts, and containers while remaining unopinionated about their final appearance, relying on the Styles Library for visual presentation.
 
 ## Installation
 
@@ -14,505 +18,318 @@ npm install @universityofmaryland/web-elements-library
 yarn add @universityofmaryland/web-elements-library
 ```
 
-## Quick Start
+### Peer Dependencies
+
+Elements are styled by the Styles package:
+
+```bash
+npm install @universityofmaryland/web-styles-library
+```
 
-Here's a simple example to get you started with the Elements library:
+## Quick Start
 
 ```javascript
-import { Composite } from '@universityofmaryland/web-elements-library';
+import { Composite, Atomic } from '@universityofmaryland/web-elements-library';
 
-// Create a hero section
-const hero = Composite.hero.standard({
-  headline: document.createElement('h1'),
+// Create a card element
+const card = Composite.card.block({
+  headline: document.createElement('h3'),
   text: document.createElement('p'),
   image: document.querySelector('img'),
-  isThemeDark: true
+  isThemeDark: true,
 });
 
-// Add the hero to your page
-document.getElementById('hero-container').appendChild(hero.element);
+// Add to DOM
+document.querySelector('.container').appendChild(card.element);
 
-// Inject the associated styles
-const styleElement = document.createElement('style');
-styleElement.textContent = hero.styles;
-document.head.appendChild(styleElement);
+// Apply associated styles
+const style = document.createElement('style');
+style.textContent = card.styles;
+document.head.appendChild(style);
 ```
 
-## Usage
+## Architecture
 
-### Importing Elements
+### Element Categories
 
-```javascript
-// Import specific element categories
-import { Atomic, Composite, Layout } from '@universityofmaryland/web-elements-library';
+#### Atomic Elements
 
-// Example: Using an atomic element
-const buttonElement = Atomic.actions.text({
-  text: 'Click Me',
-  url: '#',
-  isStyled: true
-});
+The most basic building blocks:
 
-// Add the element to the DOM
-document.body.appendChild(buttonElement.element);
-```
+- **actions** - Buttons and interactive elements
+- **animations** - Animation patterns and effects
+- **assets** - Images, videos, and media handling
+- **buttons** - Specialized button components
+- **events** - Event-related display elements
+- **layout** - Basic layout structures
+- **textLockup** - Text grouping patterns
 
-## Element Categories
+#### Composite Elements
 
-The library organizes elements into several categories:
+Combinations of atomic elements forming UI patterns:
 
-### Atomic Elements
+- **accordion** - Expandable content sections
+- **alert** - Notification and alert displays
+- **banner** - Banner and promotional elements
+- **card** - Content cards (block, list, overlay)
+- **carousel** - Image and content sliders
+- **footer** - Footer compositions
+- **hero** - Hero sections (see detailed documentation below)
+- **layout** - Complex layout patterns
+- **media** - Media display compositions
+- **navigation** - Navigation structures
+- **pathway** - User journey elements
+- **person** - Profile and bio displays
+- **quote** - Quote and testimonial blocks
+- **slider** - Content slider variations
+- **social** - Social media integrations
+- **stat** - Statistics displays
+- **tabs** - Tabbed interfaces
 
-Atomic elements are the most basic building blocks that cannot be broken down further:
+### Element Return Structure
 
-```javascript
-import { Atomic } from '@universityofmaryland/web-elements-library';
+All elements return a consistent interface:
 
-// 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
-});
+```typescript
+interface ElementModel {
+  element: HTMLElement | DocumentFragment;
+  styles: string;
+  events?: {
+    load?: () => void;
+    resize?: () => void;
+    destroy?: () => void;
+  };
+}
 ```
 
-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
+## Integration with Other Packages
 
-### Composite Elements
+### Styles Package Dependency
 
-Composite elements are combinations of atomic elements that form more complex UI patterns:
+Elements rely entirely on the Styles package for visual presentation:
 
 ```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')
-});
+// Styles are automatically included in the element.styles property
 ```
 
-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:
+### Components Package Relationship
 
-```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
-});
-```
+Components are built using Elements:
 
-##### Minimal Hero
-A simplified hero with essential content only:
+- Elements provide structure and behavior
+- Components add web component wrapper and lifecycle
+- Elements can be used standalone for custom implementations
 
-```javascript
-const heroMinimal = Composite.hero.minimal({
-  headline: document.createElement('h1'),
-  text: document.createElement('p'),
-  eyebrow: document.createElement('span'),
-  isThemeDark: false
-});
-```
+### Usage in Feeds Package
 
-##### Stacked Hero
-Hero with vertically stacked content and media:
+Feed layouts use Elements for content display:
 
 ```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
-});
+// Feeds internally use card and grid elements
+import { card } from '@universityofmaryland/web-elements-library/Composite';
 ```
 
-##### Overlay Hero
-Hero with overlay effects and advanced styling options:
+## Common Element Patterns
+
+### Actions Elements
 
 ```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
+import { Atomic } from '@universityofmaryland/web-elements-library';
+
+// Text-based action
+const textAction = Atomic.actions.text({
+  text: 'Learn More',
+  url: '/learn-more',
+  isStyled: true,
+});
+
+// Icon action
+const iconAction = Atomic.actions.icon({
+  icon: 'arrow-right',
+  url: '#',
+  ariaLabel: 'Next page',
 });
 ```
 
-##### Logo Hero
-Hero featuring institutional branding:
+### Card Elements
 
 ```javascript
-const heroLogo = Composite.hero.logo({
-  headline: document.createElement('h1'),
-  logo: document.createElement('div'), // Logo element
-  text: document.createElement('p'),
-  actions: document.createElement('div'),
+import { Composite } from '@universityofmaryland/web-elements-library';
+
+// Block card
+const blockCard = Composite.card.block({
+  headline: document.querySelector('h3'),
+  text: document.querySelector('p'),
   image: document.querySelector('img'),
+  actions: document.querySelector('.actions'),
+  isThemeDark: false,
+});
+
+// Overlay card
+const overlayCard = Composite.card.overlay({
+  headline: headlineElement,
+  text: textElement,
+  image: imageElement,
+  isTypeColor: true,
   isThemeDark: true,
-  isThemeLight: false,
-  isThemeMaryland: false
 });
 ```
 
-##### Custom Hero Variations
+### Hero Elements
 
-The library also provides specialized hero patterns for specific use cases:
+The hero category offers multiple variations for impactful layouts:
 
-###### Expand Hero
-Hero with expandable content sections:
+#### Standard Hero
 
 ```javascript
-const heroExpand = Composite.hero.custom.expand({
+const hero = Composite.hero.standard({
   headline: document.createElement('h1'),
+  eyebrow: document.createElement('span'),
   text: document.createElement('p'),
-  expandedContent: document.createElement('div'), // Content revealed on expand
+  actions: document.createElement('div'),
+  image: imageElement,
   includesAnimation: true,
-  isThemeDark: true
+  isThemeDark: true,
 });
 ```
 
-###### Grid Hero
-Hero with content blocks arranged in a grid:
+#### Minimal Hero
 
 ```javascript
-const heroGrid = Composite.hero.custom.grid({
+const minimalHero = Composite.hero.minimal({
   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
+  eyebrow: document.createElement('span'),
 });
 ```
 
-###### Video Arrow Hero
-Hero with prominent video playback controls:
+#### Overlay Hero
 
 ```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
+const overlayHero = Composite.hero.overlay({
+  headline: headlineElement,
+  text: textElement,
+  image: imageElement,
+  hasBorder: true,
+  isTransparent: false,
+  isSticky: true,
+  isTextCenter: 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
+#### Custom Variations
 
-Elements specifically designed for controlling page layout:
+**Grid Hero** - Content blocks in grid layout:
 
 ```javascript
-import { Layout } from '@universityofmaryland/web-elements-library';
-
-const imageLayout = Layout.image({
-  image: document.querySelector('img'),
-  align: 'left'
+const gridHero = Composite.hero.custom.grid({
+  headline: headlineElement,
+  blocks: [block1, block2, block3, block4],
+  image: backgroundImage,
+  isThemeDark: true,
 });
 ```
 
-### Model Elements
-
-Elements for creating and interacting with the component model:
+**Expand Hero** - With expandable content:
 
 ```javascript
-import { Model } from '@universityofmaryland/web-elements-library';
-
-// Create model elements
-const actionElement = Model.elements.actions({ url: '#', text: 'Click' });
+const expandHero = Composite.hero.custom.expand({
+  headline: headlineElement,
+  text: textElement,
+  expandedContent: hiddenContent,
+  includesAnimation: true,
+});
 ```
 
-### Utilities
-
-Helper functions for working with elements:
+### Layout Elements
 
 ```javascript
-import { Utilities } from '@universityofmaryland/web-elements-library';
+import { Composite } from '@universityofmaryland/web-elements-library';
 
-// Accessibility utilities
-Utilities.accessibility.focusable(element);
+// Sticky columns
+const stickyLayout = Composite.layout.stickyColumns({
+  leftColumn: sidebarContent,
+  rightColumn: mainContent,
+  stickyOffset: 100,
+});
 
-// DOM manipulation
-Utilities.markup.create.element('div', { class: 'container' });
+// Image expand layout
+const imageExpand = Composite.layout.image.expand({
+  image: imageElement,
+  caption: 'Image caption',
+  isExpanded: false,
+});
 ```
 
-## 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
-}
-```
+## TypeScript Support
 
-Example of using the update method:
+Full TypeScript definitions for type safety:
 
-```javascript
-const button = Atomic.buttons.primary({
-  text: 'Learn More',
-  url: '#'
-});
+```typescript
+import type {
+  ElementModel,
+  HeroStandardProps,
+  CardBlockProps,
+  ThemeProps,
+} from '@universityofmaryland/web-elements-library';
 
-// Update properties later
-button.update({
-  text: 'View Details',
-  isDisabled: true
-});
+const heroProps: HeroStandardProps = {
+  headline: document.createElement('h1'),
+  isThemeDark: true,
+  includesAnimation: false,
+};
 ```
 
 ## Browser Support
 
-This library supports all modern browsers, including:
-- Chrome
-- Firefox
-- Safari
-- Edge
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
 
 ## 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
+- **Lightweight** - Minimal JavaScript, no framework dependencies
+- **Tree-shakeable** - Import only needed elements
+- **Efficient** - Reusable element instances
+- **Lazy-loadable** - Load elements on demand
 
 ## Accessibility
 
-All elements are built with accessibility as a priority:
-- WCAG 2.1 AA compliant
-- Proper semantic markup
-- ARIA attributes where appropriate
+All elements follow WCAG 2.1 AA standards:
+
+- Semantic HTML structure
+- ARIA attributes where needed
 - Keyboard navigation support
+- Screen reader compatibility
 - 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/).
+- **[Element Reference](./)** - Complete API documentation
+- **[Design System](https://designsystem.umd.edu)** - Full design system docs
 
 ## 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
+# Run tests
 npm test
 
-# Run tests in watch mode
+# Watch mode
 npm run test:watch
 
-# Run tests with coverage
+# Coverage report
 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
-};
+# Test specific category
+npm test -- composite/hero
 ```
 
 ## Contributing
 
-For contribution guidelines, please refer to the main repository README.
+See the [main repository](https://github.com/umd-digital/design-system) for contribution guidelines.
 
 ## License
 
-This project is licensed under the University of Maryland license.
+University of Maryland