npmpackage.info

Gathering detailed insights and metrics for @universityofmaryland/web-components-library

@universityofmaryland/web-components-library - 1.12.8 | npmpackage.info

@universityofmaryland/web-components-library

1.12.8

4.68 MB

Installations

npm install @universityofmaryland/web-components-library

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS

Node Version

20.19.2

NPM Version

10.8.2 Releases

Unable to fetch releases

Download Statistics

Total Downloads

Last Day

Last Week

Last Month

Last Year

Maintainers

Package Meta Information

Latest Version

1.12.8

Package Id

@universityofmaryland/web-components-library@1.12.8

Unpacked Size

4.68 MB

Size

1.30 MB

File Count

348

NPM Version

10.8.2

Node Version

20.19.2

Published on

Jul 16, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

NaN

Compared to previous day

Last Week

NaN

Compared to previous week

Last Month

NaN

Compared to previous month

Last Year

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

@types/postcss-js jest-dom postcss-js tw-to-css

University of Maryland Web Components Library

High-level web components built from the elements library for interfaces, interactivity, layout, and data feeds. This library provides ready-to-use web components that follow the University of Maryland's design guidelines and accessibility standards. These components are designed to work seamlessly together to create consistent, branded UMD web experiences while maintaining performance and usability across all devices.

Installation

1# Using npm
2npm install @universityofmaryland/web-components-library
3
4# Using yarn
5yarn add @universityofmaryland/web-components-library

Usage

Loading All Components

The simplest way to use the components is to load all of them at once. This approach is ideal for applications that use many UMD components.

1import LoadUmdComponents from '@universityofmaryland/web-components-library';
2
3document.addEventListener('DOMContentLoaded', () => {
4  LoadUmdComponents();
5  // All components are now registered and available in the DOM
6});

Tree-Shaking (Loading Individual Components)

For better performance, you can import only the components you need:

1import {
2  card,
3  navigation,
4  hero,
5} from '@universityofmaryland/web-components-library/Components';
6
7// Initialize specific components
8card.standard();
9navigation.header();
10hero.minimal();

Available Components

The library includes a wide range of components organized by type:

Layout Components

layout.boxLogo - Box with logo layout
layout.imageExpand - Expandable image layout
layout.modal - Modal dialog
layout.scrollTop - Scroll to top button
layout.stickyColumns - Sticky columns layout

UI Components

accordion - Collapsible content panels
actions - Action buttons and links
alert - Alert notifications
card - Various card styles (standard, article, overlay)
carousel - Image and content carousels
hero - Hero sections (standard, minimal, expand, logo)
navigation - Navigation components (header, drawer, breadcrumb)
person - Person/profile components
quote - Quote/testimonial components
stat - Statistics display
tab - Tabbed interface
text - Text components

Example Usage

Card Component

1<umd-element-card>
2  <img slot="image" src="path/to/image.jpg" alt="Card image" />
3  <p slot="eyebrow">Category</p>
4  <h3 slot="headline">Card Title</h3>
5  <p slot="text">
6    Card description text goes here with details about the card content.
7  </p>
8  <div slot="actions">
9    <a href="#">Learn More</a>
10  </div>
11</umd-element-card>

Component Model System

The library uses a sophisticated model system for creating and registering web components with consistent behavior, validation, and lifecycle management.

Registration System

Components are registered using the Register.webComponent() utility:

1import { Register } from 'model';
2
3export default Register.webComponent({
4  tagName: 'umd-element-example',
5  slots: slotConfiguration,
6  createComponent: componentFactory,
7  attributes: attributeHandlers, // Optional: reactive attribute observers
8  afterConnect: lifecycleCallback, // Optional: lifecycle hooks
9});

Attribute System

The library uses two types of attributes:

Configuration Attributes (data-*)

Set initial component state and configuration:

1<umd-element-card data-theme="dark">
2  <!-- Content -->
3</umd-element-card>

Common configuration attributes:

data-theme - Color theme (light, dark)
data-display - Display style (grid, list, inline)
data-visual-open - Initial open state
data-size - Component size (small, medium, large)

Observed Attributes

Trigger component behavior when changed:

1// Programmatic control
2element.setAttribute('is-visual-open', 'true');
3element.setAttribute('resize', 'true');

Common observed attributes:

is-visual-open - Opens component
is-visual-closed - Closes component
resize - Triggers resize calculation
load - Triggers load event

Attribute Handlers

The library provides pre-built attribute handlers:

1import { Attributes } from 'model';
2
3// Single handler
4const resizeHandler = Attributes.handler.common.resize();
5
6// Combined handlers
7const multiHandler = Attributes.handler.combine([
8  Attributes.handler.common.resize(),
9  Attributes.handler.common.visualToggle(),
10]);
11
12// Custom handler with callback
13const customHandler = Attributes.handler.common.resize((element) => {
14  element.events?.recalculate();
15});

Available handlers:

resize() - Handles component resizing
visualToggle() - Open/close animations
visualShowHide() - Show/hide visibility
accordion() - Complete accordion behavior

Slot System

Components use a slot-based content distribution system with validation:

1import { Slots } from 'model';
2
3const slots = {
4  headline: {
5    allowedElements: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
6    required: true,
7  },
8  text: {
9    allowedElements: ['div', 'p'],
10    required: false,
11  },
12  actions: {
13    allowedElements: ['div', 'nav'],
14    deprecated: { replacement: 'cta' },
15  },
16};

Using slots in HTML:

1<umd-element-example>
2  <h3 slot="headline">Title</h3>
3  <p slot="text">Content text</p>
4  <div slot="actions">
5    <a href="#">Learn More</a>
6  </div>
7</umd-element-example>

Lifecycle Hooks

Pre-built lifecycle hooks for common initialization patterns:

1import { Lifecycle } from 'model';
2
3// Available hooks
4afterConnect: Lifecycle.hooks.loadOnConnect,      // Calls load event
5afterConnect: Lifecycle.hooks.loadAnimation,      // Sets up animations
6afterConnect: Lifecycle.hooks.resizeOnConnect,    // Triggers resize

Creating Custom Components

Example of a complete component implementation:

1import { Composite } from '@universityofmaryland/web-elements-library';
2import { Attributes, Slots, Register, Lifecycle } from 'model';
3import type { CreateComponentFunction, SlotConfiguration } from '../_types';
4
5// Define the custom element tag name
6const tagName = 'umd-custom-component';
7
8// Configure slots with validation
9const slots: SlotConfiguration = {
10  headline: {
11    allowedElements: ['h2', 'h3', 'h4'],
12    required: true,
13  },
14  text: {
15    allowedElements: ['p', 'div'],
16  },
17  image: {
18    allowedElements: ['img', 'picture'],
19    required: false,
20  },
21};
22
23// Create the component factory function
24const createComponent: CreateComponentFunction = (element) => {
25  // Extract validated slot content
26  const headline = Slots.headline.default({ element });
27  const text = Slots.text.default({ element });
28  const image = Slots.query.elements({ element, name: 'image' });
29
30  // Extract configuration attributes
31  const isThemeDark = Attributes.isTheme.dark({ element });
32  const displayStyle = element.getAttribute('data-display') || 'default';
33
34  // Create component using the Elements library
35  return Composite.customComponent.create({
36    headline,
37    text,
38    image,
39    isThemeDark,
40    displayStyle,
41  });
42};
43
44// Register the web component with all features
45export default Register.webComponent({
46  tagName,
47  slots,
48  createComponent,
49  attributes: [
50    Attributes.handler.common.resize(),
51    Attributes.handler.common.visualToggle(),
52  ],
53  afterConnect: Lifecycle.hooks.loadOnConnect,
54});

Component Events

Components dispatch custom events for state changes:

1// Listen for component events
2element.addEventListener('component:ready', (e) => {
3  console.log('Component initialized');
4});
5
6element.addEventListener('component:resize', (e) => {
7  console.log('Component resized');
8});
9
10element.addEventListener('component:error', (e) => {
11  console.error('Component error:', e.detail);
12});

Advanced Component Features

Reactive Updates

Components automatically update when observed attributes change:

1// Triggers resize handler
2element.setAttribute('resize', 'true');
3
4// Triggers visual state change
5element.setAttribute('is-visual-open', 'true');

Shadow DOM

All components use Shadow DOM for style encapsulation:

1// Access shadow root
2const shadowRoot = element.shadowRoot;
3
4// Query within shadow DOM
5const internalElement = shadowRoot.querySelector('.component-part');

Development

Setting Up a Development Environment

1# Clone the repository
2git clone https://github.com/umd-digital/design-system.git
3cd design-system/packages/components
4
5# Install dependencies
6npm install
7
8# Start development server
9npm start

Building Components

1# Production build
2npm run build
3
4# Build and publish to npm
5npm run release

Testing

The library uses Jest with jsdom for testing web components:

1# Run all tests
2npm test
3
4# Run tests in watch mode
5npm run test:watch
6
7# Generate coverage report
8npm run test:coverage
9
10# Run specific test file
11npm test -- source/api/__tests__/card/standard.test.ts

Test Structure

Each component test validates:

Component registration with customElements
Slot configuration and validation
Attribute handling (both configuration and observed)
Deprecation warnings
Event dispatching
Error handling

Type System

The library is built with TypeScript and provides comprehensive type definitions:

1import type {
2  ComponentRef,
3  CreateComponentFunction,
4  ComponentRegistration,
5  SlotConfiguration,
6  ThemeProps,
7  VisualStateProps,
8  ComponentEvents,
9} from '@universityofmaryland/web-components-library';

Key interfaces:

ComponentRef - Reference returned by component factories
SlotConfiguration - Slot validation rules
CreateComponentFunction - Component factory signature
ComponentRegistration - Registration function type
AttributeHandler - Attribute observer configuration

Common Patterns

Using Common Slots

1import { CommonSlots } from 'model/slots/common';
2
3const slots = {
4  headline: CommonSlots.headline, // Pre-configured headline slot
5  text: CommonSlots.text, // Pre-configured text slot
6  actions: CommonSlots.actions, // Pre-configured actions slot
7  customSlot: {
8    // Custom slot definition
9    allowedElements: ['div', 'section'],
10    required: false,
11  },
12};

Component Composition

Components can be composed from other components:

1import {
2  card,
3  hero,
4} from '@universityofmaryland/web-components-library/Components';
5
6// Initialize multiple components
7card.standard();
8card.overlay();
9hero.minimal();
10
11// Components work together
12const heroWithCards = `
13  <umd-element-hero>
14    <h1 slot="headline">Welcome</h1>
15    <div slot="actions">
16      <umd-element-call-to-action>
17        <!-- CTA Slot Options -->
18      </umd-element-call-to-action>
19    </div>
20  </umd-element-hero>
21`;

Browser Support

The UMD Web Components Library supports all modern browsers that support Web Components, including:

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

For older browsers, consider using the Web Components polyfills.

Dependencies

This library depends on:

@universityofmaryland/web-elements-library (^1.2.0) - For foundational UI elements
@universityofmaryland/web-styles-library (^1.4.2) - For styling and theming
TypeScript (^5.0.0) - For type safety
PostCSS & Tailwind CSS - For styling processing

Performance Considerations

Components are lazy-loaded when first used
Shadow DOM provides style isolation without global CSS pollution
Slot validation happens once during initialization
Attribute observers only trigger for registered attributes
Components dispatch events for async operations

Accessibility

All components in this library are designed with accessibility in mind:

WCAG 2.1 AA compliant
Keyboard navigable interfaces with visible focus indicators
Screen reader friendly with proper ARIA attributes and live regions
Focus management for interactive elements
Color contrast ratios that meet accessibility standards
Reduced motion support via prefers-reduced-motion
Semantic HTML structure

Documentation

Contributing

For contribution guidelines, please refer to the main repository README.

License

This project is licensed under the University of Maryland license.

No vulnerabilities found.

No security vulnerabilities found.