@universityofmaryland/web-feeds-library 1.0.6 → 1.0.7

package/README.md

@@ -1,217 +1,379 @@
 # University of Maryland Feeds Library
 
-[![Feeds Version](https://img.shields.io/badge/Feeds-v1.0.6-blue)](https://www.npmjs.com/package/@universityofmaryland/web-feeds-library)
+[![Feeds Version](https://img.shields.io/badge/Feeds-v1.0.7-blue)](https://www.npmjs.com/package/@universityofmaryland/web-feeds-library)
 
-A collection of dynamic feed components for displaying University of Maryland content feeds including news articles, events, and academic information. This library simplifies the integration of live, updating content from UMD sources while maintaining brand consistency and performance optimization.
+Dynamic content feed components for displaying University of Maryland news, events, and academic information with automatic updates, caching, and brand-compliant styling.
 
 ## Overview
 
-The UMD Feeds Library provides ready-to-use feed components that can be integrated into any web project. These components are designed to follow UMD brand guidelines and accessibility standards while providing a seamless way to display dynamic content. The library handles all aspects of content fetching, caching, error handling, and rendering, allowing developers to focus on integration rather than implementation details.
+The UMD Feeds Library simplifies the integration of dynamic UMD content into any web application. It provides pre-built components for displaying news articles, event calendars, and academic program information that automatically sync with UMD data sources. Built on the Elements Library and styled with the Styles Library, these components ensure consistent presentation while handling all complexities of data fetching, caching, error handling, and responsive layouts.
 
 ## Installation
 
 ```bash
+# Using npm
 npm install @universityofmaryland/web-feeds-library
-# or
+
+# Using yarn
 yarn add @universityofmaryland/web-feeds-library
 ```
 
-## Features
+### Peer Dependencies
 
-- **Responsive Layouts**: Grid, list, and featured layouts that work across all screen sizes
-- **Multiple Feed Types**: Support for news, events, and academic content
-- **Customizable**: Theme options, column configuration, and layout variations
-- **Accessibility**: ARIA-compliant with screen reader support
-- **Lazy Loading**: Optional lazy loading for improved performance
+For complete styling and functionality:
 
-## Usage
+```bash
+npm install @universityofmaryland/web-styles-library
+npm install @universityofmaryland/web-elements-library
+```
 
-### Basic Example
+## Quick Start
 
-```typescript
-import * as Feeds from '@universityofmaryland/web-feeds-library';
+```javascript
+import { news, events } from '@universityofmaryland/web-feeds-library';
 
-// Create a news grid component
-const newsGrid = Feeds.news.grid({
+// Create a news grid
+const newsGrid = news.grid({
   token: 'your-api-token',
   numberOfColumnsToShow: 3,
-  isThemeDark: false,
+  isThemeDark: false
 });
 
-// Add to DOM
+// Add to your page
 document.querySelector('.news-container').appendChild(newsGrid.element);
 ```
 
-## Available Feed Components
+## Feed Types
 
 ### News Feeds
 
-```typescript
-// Grid layout for news
-const newsGrid = Feeds.news.grid({ token: 'your-api-token' });
+Display UMD news articles in various layouts:
 
-// List layout for news
-const newsList = Feeds.news.list({ token: 'your-api-token' });
+```javascript
+import { news } from '@universityofmaryland/web-feeds-library';
 
-// Featured news layout with prominent article
-const newsFeatured = Feeds.news.featured({
+// Grid layout - Responsive card grid
+const newsGrid = news.grid({
+  token: 'your-api-token',
+  numberOfColumnsToShow: 3,
+  isThemeDark: false,
+  isTransparent: false
+});
+
+// List layout - Vertical article list
+const newsList = news.list({
+  token: 'your-api-token',
+  showImages: true,
+  showDates: true
+});
+
+// Featured layout - Hero article with sidebar
+const newsFeatured = news.featured({
   token: 'your-api-token',
   isLazyLoad: true,
+  isLayoutReversed: false,
+  overwriteStickyPosition: 100
 });
 ```
 
 ### Event Feeds
 
-```typescript
-// Grid layout for events
-const eventsGrid = Feeds.events.grid({ token: 'your-api-token' });
+Display UMD events with calendar integration:
 
-// List layout for events
-const eventsList = Feeds.events.list({ token: 'your-api-token' });
+```javascript
+import { events } from '@universityofmaryland/web-feeds-library';
 
-// Slider for events
-const eventsSlider = Feeds.events.slider({ token: 'your-api-token' });
+// Grid layout - Event cards
+const eventsGrid = events.grid({
+  token: 'your-api-token',
+  numberOfColumnsToShow: 3,
+  showPastEvents: false
+});
+
+// List layout - Chronological list
+const eventsList = events.list({
+  token: 'your-api-token',
+  groupByDate: true,
+  maxEvents: 10
+});
+
+// Slider - Horizontal scroll
+const eventsSlider = events.slider({
+  token: 'your-api-token',
+  slidesToShow: 4,
+  autoPlay: true
+});
 ```
 
 ### Academic Feeds
 
-```typescript
-// Slider for academic events
-const academicSlider = Feeds.academic.slider({ token: 'your-api-token' });
+Display academic programs and information:
+
+```javascript
+import { academic } from '@universityofmaryland/web-feeds-library';
+
+// Academic event slider
+const academicSlider = academic.slider({
+  token: 'your-api-token',
+  department: 'engineering',
+  programType: 'graduate'
+});
 ```
 
-## Component Configuration
+## Integration with Other Packages
 
-All feed components accept these common properties:
+### Styles Package Integration
 
-- `token` (required): API token for authentication
-- `isThemeDark`: Enable dark theme styling (default: false)
-- `isTransparent`: Use transparent background for cards (default: false)
+Feeds automatically use UMD styles for consistent appearance:
 
-Grid-specific options:
+```html
+<!-- Feeds inherit grid and spacing utilities -->
+<div class="umd-layout-space-vertical-landing">
+  <div id="news-feed"></div>
+</div>
+```
+
+### Elements Package Usage
+
+Feeds are built using Elements for rendering:
+- Card elements for item display
+- Grid layouts from layout elements
+- Typography from text elements
 
-- `numberOfColumnsToShow`: Number of columns to display (default: 3)
+### Components Package Compatibility
 
-Featured layout options:
+Feeds can be wrapped in web components:
+
+```javascript
+import { Components } from '@universityofmaryland/web-components-library';
+import { news } from '@universityofmaryland/web-feeds-library';
+
+// Initialize feed component wrapper
+Components.feed.newsList();
+// Feed will render inside the component
+```
 
-- `isLazyLoad`: Enable lazy loading of additional content
-- `isLayoutReversed`: Reverse the layout order
-- `overwriteStickyPosition`: Custom sticky position value
+## Configuration Options
 
-### Custom Filtering and Sorting
+### Common Properties
 
-You can customize how feed items are filtered and sorted:
+All feeds accept these base properties:
 
 ```typescript
-import * as Feeds from '@universityofmaryland/web-feeds-library';
+interface BaseFeedProps {
+  token: string;              // Required: API authentication token
+  isThemeDark?: boolean;      // Dark theme styling
+  isTransparent?: boolean;    // Transparent card backgrounds
+  onError?: (error: Error) => void; // Error handler
+  onLoad?: (items: any[]) => void;  // Load complete handler
+}
+```
+
+### Layout-Specific Options
+
+**Grid Layout:**
+```typescript
+interface GridProps extends BaseFeedProps {
+  numberOfColumnsToShow?: number; // 1-4, default: 3
+  gapSize?: 'small' | 'medium' | 'large';
+  minCardHeight?: number;
+}
+```
+
+**List Layout:**
+```typescript
+interface ListProps extends BaseFeedProps {
+  showImages?: boolean;
+  showDates?: boolean;
+  showExcerpts?: boolean;
+  maxItems?: number;
+}
+```
+
+**Featured Layout:**
+```typescript
+interface FeaturedProps extends BaseFeedProps {
+  isLazyLoad?: boolean;
+  isLayoutReversed?: boolean;
+  overwriteStickyPosition?: number;
+  sidebarItemCount?: number;
+}
+```
 
-const newsGrid = Feeds.news.grid({
+## Advanced Features
+
+### Filtering and Sorting
+
+```javascript
+const filteredNews = news.grid({
   token: 'your-api-token',
   filters: {
     categories: ['research', 'campus-life'],
-    tags: ['featured'],
+    tags: ['featured', 'students'],
     dateRange: {
-      start: '2023-01-01',
-      end: '2023-12-31',
+      start: new Date('2024-01-01'),
+      end: new Date('2024-12-31')
     },
+    author: 'John Doe'
   },
-  sortBy: 'date', // 'date', 'title', 'popularity'
-  sortDirection: 'desc', // 'asc' or 'desc'
+  sortBy: 'date', // 'date' | 'title' | 'popularity'
+  sortDirection: 'desc' // 'asc' | 'desc'
 });
 ```
 
 ### Event Handling
 
-All feed components emit events that you can listen for. You can use the standard event listeners or our utility functions for better TypeScript support:
-
-```typescript
-import * as Feeds from '@universityofmaryland/web-feeds-library';
-import { events } from '@universityofmaryland/web-feeds-library/utilities';
-
-const eventsFeed = Feeds.events.list({ token: 'your-api-token' });
-const container = document.querySelector('.events-container');
-container.appendChild(eventsFeed.element);
+```javascript
+import { events } from '@universityofmaryland/web-feeds-library';
 
-// Method 1: Standard event listener approach
-eventsFeed.element.addEventListener(events.eventNames.FEED_LOADED, (event) => {
-  console.log('Feed loaded with', event.detail.items.length, 'items');
+const eventsFeed = events.list({
+  token: 'your-api-token',
+  onLoad: (items) => {
+    console.log(`Loaded ${items.length} events`);
+  },
+  onError: (error) => {
+    console.error('Feed error:', error);
+    // Show fallback content
+  },
+  onItemClick: (item) => {
+    // Custom click handler
+    console.log('Clicked:', item.title);
+  }
 });
 
-eventsFeed.element.addEventListener(events.eventNames.FEED_ERROR, (event) => {
-  console.error('Feed error:', event.detail.error);
+// Listen for feed updates
+eventsFeed.element.addEventListener('feed:update', (e) => {
+  console.log('Feed updated with new items');
 });
+```
 
-// Method 2: Using the utility helper (provides proper type information)
-events.listen(eventsFeed.element, events.eventNames.FEED_LOADED, (detail) => {
-  console.log('Feed loaded with', detail.items.length, 'items');
+### Pagination
+
+```javascript
+const paginatedNews = news.list({
+  token: 'your-api-token',
+  itemsPerPage: 10,
+  showPagination: true,
+  onPageChange: (page) => {
+    console.log(`Navigated to page ${page}`);
+  }
 });
+```
 
-// With cleanup function for easy removal
-const removeListener = events.listen(
-  eventsFeed.element,
-  events.eventNames.FEED_ERROR,
-  (detail) => {
-    console.error('Feed error:', detail.error);
-  },
-);
+### Custom Templates
+
+Override default item rendering:
 
-// Later you should remove the listener if needed
-// removeListener();
+```javascript
+const customNews = news.grid({
+  token: 'your-api-token',
+  renderItem: (item) => {
+    return `
+      <div class="custom-news-item">
+        <h3>${item.title}</h3>
+        <time>${item.date}</time>
+        <p>${item.excerpt}</p>
+      </div>
+    `;
+  }
+});
 ```
 
-## Performance Considerations
+## Performance Features
 
-The Feeds library is optimized for performance:
+### Lazy Loading
 
-- Content is lazy-loaded when elements enter the viewport
-- Network requests are cached and debounced
-- Images are optimized and responsive
-- Content is efficiently rendered with minimal DOM operations
+Load content as users scroll:
 
-## Accessibility
+```javascript
+const lazyFeed = news.featured({
+  token: 'your-api-token',
+  isLazyLoad: true,
+  lazyLoadOffset: 200 // pixels before viewport
+});
+```
 
-All feed components are built with accessibility in mind:
+### Caching
 
-- WCAG 2.1 AA compliant
-- Proper semantic markup with ARIA attributes
-- Keyboard navigable
-- Screen reader announcements for dynamic content updates
-- Support for reduced motion preferences
+Automatic caching reduces API calls:
 
-## Testing
+```javascript
+const cachedFeed = events.grid({
+  token: 'your-api-token',
+  cacheTimeout: 300000, // 5 minutes
+  forceFresh: false // Use cache if available
+});
+```
 
-The library uses Jest for unit testing. To run tests:
+### Infinite Scroll
 
-```bash
-# Run all tests
-npm run test
+```javascript
+const infiniteFeed = news.list({
+  token: 'your-api-token',
+  enableInfiniteScroll: true,
+  infiniteScrollThreshold: 100 // pixels from bottom
+});
+```
 
-# Run tests in watch mode during development
-npm run test:watch
+## TypeScript Support
 
-# Run tests with coverage report
-npm run test:coverage
+Full TypeScript definitions included:
+
+```typescript
+import type { 
+  NewsFeedProps,
+  EventsFeedProps,
+  FeedItem,
+  FeedEvents 
+} from '@universityofmaryland/web-feeds-library';
+
+const newsProps: NewsFeedProps = {
+  token: 'token',
+  numberOfColumnsToShow: 3,
+  isThemeDark: false
+};
 ```
 
-## Release Process
+## Browser Support
 
-The release process requires all tests to pass before publishing:
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Accessibility
+
+All feed components are WCAG 2.1 AA compliant:
+- Semantic HTML markup
+- ARIA live regions for updates
+- Keyboard navigation
+- Screen reader announcements
+- Skip links for long lists
+
+## Documentation
+
+- **[Feed Components](https://umd-digital.github.io/design-system/docs/feeds/)** - Complete reference
+- **[API Documentation](https://umd-digital.github.io/design-system/docs/feeds/modules/)** - TypeScript APIs
+- **[Integration Examples](https://github.com/umd-digital/design-system/tree/main/packages/feeds/examples)** - Sample implementations
+- **[Design System](https://designsystem.umd.edu)** - Full design system docs
+
+## Testing
 
 ```bash
-npm run release
-```
+# Run tests
+npm test
 
-This will:
+# Watch mode
+npm run test:watch
 
-1. Run all tests (and abort if any tests fail)
-2. Clean the distribution directory
-3. Build the project
-4. Publish the package
+# Coverage report
+npm run test:coverage
+```
 
 ## 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

package/dist/composite/events/common/data.d.ts

@@ -39,6 +39,7 @@ export declare const display: ({ entry, isThemeDark, }: {
     text: HTMLDivElement | null;
     eventMeta: {
         element: HTMLElement;
+        className: string;
         styles: string;
     };
     isThemeDark: boolean | undefined;

package/dist/composite/events/common/data.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../../../source/composite/events/common/data.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,SAAS,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,WAAW,EACZ,MAAM,WAAW,CAAC;AAEnB,UAAU,aAAc,SAAQ,YAAY;IAC1C,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,UAAU,YAAa,SAAQ,WAAW;CAAG;AAE7C,eAAO,MAAM,iBAAiB,UAAW,aAAa;;;;;;;;;;;;;;;;;;;;;;;CAMpD,CAAC;AAEH,eAAO,MAAM,YAAY,UAChB,YAAY,KAClB,SAAS,CAAC,oBAuBZ,CAAC;AAEF,eAAO,MAAM,OAAO,4BAGjB;IACD,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;;;;;;;;CAWC,CAAC"}
+{"version":3,"file":"data.d.ts","sourceRoot":"","sources":["../../../../source/composite/events/common/data.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,SAAS,MAAM,SAAS,CAAC;AACrC,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,WAAW,EACZ,MAAM,WAAW,CAAC;AAEnB,UAAU,aAAc,SAAQ,YAAY;IAC1C,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,UAAU,YAAa,SAAQ,WAAW;CAAG;AAE7C,eAAO,MAAM,iBAAiB,UAAW,aAAa;;;;;;;;;;;;;;;;;;;;;;;CAMpD,CAAC;AAEH,eAAO,MAAM,YAAY,UAChB,YAAY,KAClB,SAAS,CAAC,oBAuBZ,CAAC;AAEF,eAAO,MAAM,OAAO,4BAGjB;IACD,KAAK,EAAE,SAAS,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;;;;;;;;;CAWC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@universityofmaryland/web-feeds-library",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "UMD Feed Elements",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -24,12 +24,6 @@
     "test:snapshot": "jest --updateSnapshot"
   },
   "dependencies": {
-    "@types/postcss-js": "^4.0.4",
-    "postcss-js": "^4.0.1",
-    "tw-to-css": "^0.0.12"
-  },
-  "peerDependencies": {
-    "@universityofmaryland/web-elements-library": "*",
-    "@universityofmaryland/web-styles-library": "^1.1.0"
+    "@types/postcss-js": "^4.0.4"
   }
 }