mtrl 0.3.0 → 0.3.2

package/src/components/list/index.ts

@@ -1,12 +1,67 @@
 // src/components/list/index.ts
+
+/**
+ * @module List
+ * 
+ * List component following Material Design 3 guidelines.
+ * Lists are continuous, vertical indexes of text or images.
+ * 
+ * Features:
+ * - Multiple selection modes (single, multiple, none)
+ * - Horizontal and vertical layouts
+ * - Support for sections and dividers
+ * - Leading and trailing elements (icons, avatars, etc.)
+ * - Customizable item content (headline, supporting text, etc.)
+ * - Keyboard navigation and accessibility
+ * 
+ * @example
+ * ```typescript
+ * // Create a simple list with items
+ * const userList = createList({
+ *   type: 'single', // Single selection mode
+ *   items: [
+ *     {
+ *       id: 'user1',
+ *       headline: 'Jane Smith',
+ *       supportingText: 'Software Engineer',
+ *       leading: '<svg>...</svg>'
+ *     },
+ *     {
+ *       id: 'user2',
+ *       headline: 'John Doe',
+ *       supportingText: 'Product Manager',
+ *       leading: '<svg>...</svg>'
+ *     }
+ *   ]
+ * });
+ * 
+ * // Attach to DOM and add selection handler
+ * container.appendChild(userList.element);
+ * userList.on('selectionChange', (event) => {
+ *   console.log('Selected:', event.selected);
+ * });
+ * ```
+ * 
+ * @category Components
+ */
+
 export { default } from './list';
 export { default as createListItem } from './list-item';
 export {
+  // Types
   ListConfig,
   ListComponent,
   ListItemConfig,
   ListSectionConfig,
   ListType,
   ListLayout,
-  ListItemLayout
+  ListItemLayout,
+
+  // Constants
+  LIST_TYPES,
+  LIST_LAYOUTS,
+  LIST_ITEM_LAYOUTS,
+  LIST_CLASSES,
+  LIST_SCHEMA,
+  LIST_ITEM_STATES
 } from './types';

package/src/components/list/list-item.ts

@@ -8,9 +8,15 @@ import { createElement, getListClass } from './utils';
 
 /**
  * Creates list item content based on configuration
- * @param {BaseComponent} component - Component to enhance
+ * 
+ * Higher-order function that enhances a component with list item content structure
+ * according to Material Design 3 guidelines. Handles the creation and arrangement of
+ * item elements like headline text, supporting text, leading/trailing components, etc.
+ * 
  * @param {ListItemConfig} config - List item configuration
- * @returns {BaseComponent} Enhanced component
+ * @returns {Function} Function that enhances a component with list item content
+ * 
+ * @internal
  */
 const withItemContent = (config: ListItemConfig) => (component: any): any => {
   const { element } = component;
@@ -89,8 +95,46 @@ const withItemContent = (config: ListItemConfig) => (component: any): any => {
 
 /**
  * Creates a list item component
+ * 
+ * Creates an individual list item with customizable content following Material Design 3
+ * list item patterns. List items can have different layouts, content structures, and 
+ * visual states (selected, disabled, etc.).
+ * 
  * @param {ListItemConfig} config - List item configuration
  * @returns {Object} List item component instance
+ * 
+ * @category Components
+ * 
+ * @example
+ * ```typescript
+ * // Create a standard list item
+ * const listItem = createListItem({
+ *   id: 'user1',
+ *   headline: 'Alex Johnson',
+ *   supportingText: 'Software Engineer',
+ *   leading: '<span class="material-icons">person</span>'
+ * });
+ * 
+ * // Create a vertical layout list item with more content
+ * const detailedItem = createListItem({
+ *   id: 'event1',
+ *   layout: 'vertical',
+ *   overline: 'UPCOMING EVENT',
+ *   headline: 'Team Meeting',
+ *   supportingText: 'Discussion of quarterly goals',
+ *   meta: 'Tomorrow, 2:00 PM',
+ *   leading: '<span class="material-icons">event</span>',
+ *   trailing: '<span class="material-icons">more_vert</span>'
+ * });
+ * 
+ * // Create a selected list item
+ * const selectedItem = createListItem({
+ *   id: 'file1',
+ *   headline: 'Project Proposal.pdf',
+ *   supportingText: '2.4 MB',
+ *   selected: true
+ * });
+ * ```
  */
 const createListItem = (config: ListItemConfig): any => {
   const baseConfig = {

package/src/components/list/list.ts

@@ -9,8 +9,79 @@ import { createBaseConfig, getElementConfig } from './config';
 
 /**
  * Creates a List component
- * @param {ListConfig} config - List configuration
- * @returns {Object} List component instance
+ * 
+ * Lists display a collection of items in a vertical arrangement. They can be configured
+ * with different selection modes, layouts, and content structures following Material
+ * Design 3 guidelines.
+ * 
+ * @param {ListConfig} config - List configuration options
+ * @returns {ListComponent} List component instance with methods for managing items and selection
+ * 
+ * @throws {Error} If list creation fails due to invalid configuration
+ * 
+ * @category Components
+ * 
+ * @example
+ * ```typescript
+ * // Create a simple list with single selection
+ * const contactList = createList({
+ *   type: 'single',
+ *   items: [
+ *     {
+ *       id: 'contact1',
+ *       headline: 'Alex Johnson',
+ *       supportingText: 'alex@example.com',
+ *       leading: '<span class="material-icons">person</span>',
+ *       trailing: '<span class="material-icons">chevron_right</span>'
+ *     },
+ *     {
+ *       id: 'contact2',
+ *       headline: 'Sam Taylor',
+ *       supportingText: 'sam@example.com',
+ *       leading: '<span class="material-icons">person</span>',
+ *       trailing: '<span class="material-icons">chevron_right</span>'
+ *     }
+ *   ]
+ * });
+ * 
+ * // Create a list with sections
+ * const categorizedList = createList({
+ *   type: 'multi',
+ *   sections: [
+ *     {
+ *       id: 'section1',
+ *       title: 'Favorites',
+ *       items: [
+ *         { id: 'item1', headline: 'Item 1' },
+ *         { id: 'item2', headline: 'Item 2' }
+ *       ]
+ *     },
+ *     {
+ *       id: 'section2',
+ *       title: 'Recent',
+ *       items: [
+ *         { id: 'item3', headline: 'Item 3' },
+ *         { id: 'item4', headline: 'Item 4' }
+ *       ]
+ *     }
+ *   ]
+ * });
+ * 
+ * // Handle selection change
+ * contactList.on('selectionChange', (event) => {
+ *   console.log('Selected IDs:', event.selected);
+ * });
+ * 
+ * // Programmatically select items
+ * contactList.setSelected(['contact2']);
+ * 
+ * // Add a new item
+ * contactList.addItem({
+ *   id: 'contact3',
+ *   headline: 'Jamie Smith',
+ *   supportingText: 'jamie@example.com'
+ * });
+ * ```
  */
 const createList = (config: ListConfig = {}): any => {
   const baseConfig = createBaseConfig(config);

package/src/components/list/types.ts

@@ -1,5 +1,144 @@
 // src/components/list/types.ts
 
+/**
+ * List types/variants
+ * 
+ * Different selection modes available for lists.
+ * 
+ * @category Components
+ */
+export const LIST_TYPES = {
+  DEFAULT: 'default', // Standard list
+  SINGLE_SELECT: 'single', // Single selection list
+  MULTI_SELECT: 'multi', // Multiple selection list
+  RADIO: 'radio' // Radio button list
+} as const;
+
+/**
+ * List layout variants
+ * 
+ * Layout options for list items and content arrangement.
+ * 
+ * @category Components
+ */
+export const LIST_LAYOUTS = {
+  HORIZONTAL: 'horizontal', // Default horizontal layout
+  VERTICAL: 'vertical' // Items with more content stacked vertically
+} as const;
+
+/**
+ * List item layouts
+ * 
+ * Individual item layout options controlling content arrangement.
+ * 
+ * @category Components
+ */
+export const LIST_ITEM_LAYOUTS = {
+  HORIZONTAL: 'horizontal', // Default horizontal layout
+  VERTICAL: 'vertical' // Stacked layout with vertical alignment
+} as const;
+
+/**
+ * List element class names
+ * 
+ * CSS class names for the various elements that make up a list.
+ * 
+ * @internal
+ */
+export const LIST_CLASSES = {
+  ROOT: 'list',
+  GROUP: 'list-group',
+  GROUP_TITLE: 'list-group-title',
+  DIVIDER: 'list-divider',
+  SECTION: 'list-section',
+  SECTION_TITLE: 'list-section-title',
+  ITEM: 'list-item',
+  ITEM_CONTENT: 'list-item-content',
+  ITEM_LEADING: 'list-item-leading',
+  ITEM_TEXT: 'list-item-text',
+  ITEM_OVERLINE: 'list-item-overline',
+  ITEM_HEADLINE: 'list-item-headline',
+  ITEM_SUPPORTING: 'list-item-supporting',
+  ITEM_META: 'list-item-meta',
+  ITEM_TRAILING: 'list-item-trailing'
+} as const;
+
+/**
+ * List validation schema
+ * 
+ * JSON Schema for validating list configuration options.
+ * 
+ * @internal
+ */
+export const LIST_SCHEMA = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      enum: Object.values(LIST_TYPES),
+      default: LIST_TYPES.DEFAULT
+    },
+    layout: {
+      type: 'string',
+      enum: Object.values(LIST_LAYOUTS),
+      default: LIST_LAYOUTS.HORIZONTAL
+    },
+    items: {
+      type: 'array',
+      items: {
+        type: 'object'
+      },
+      default: []
+    },
+    groups: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', required: true },
+          title: { type: 'string' },
+          items: { type: 'array' }
+        }
+      },
+      optional: true
+    },
+    sections: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string', required: true },
+          title: { type: 'string', required: true },
+          items: { type: 'array', required: true }
+        }
+      },
+      optional: true
+    },
+    disabled: {
+      type: 'boolean',
+      default: false
+    },
+    class: {
+      type: 'string',
+      optional: true
+    }
+  }
+} as const;
+
+/**
+ * List item states
+ * 
+ * Visual states that list items can have.
+ * 
+ * @category Components
+ */
+export const LIST_ITEM_STATES = {
+  SELECTED: 'selected',
+  DISABLED: 'disabled',
+  FOCUSED: 'focused',
+  HOVERED: 'hovered'
+} as const;
+
 /**
  * List type variants
  * @category Components
@@ -48,6 +187,11 @@ export type ListItemState = 'selected' | 'disabled' | 'focused' | 'hovered';
 
 /**
  * List item configuration
+ * 
+ * Configuration options for creating a list item with customizable content
+ * and appearance following Material Design 3 guidelines.
+ * 
+ * @category Components
  */
 export interface ListItemConfig {
   /** Unique identifier for the item */
@@ -92,6 +236,11 @@ export interface ListItemConfig {
 
 /**
  * List section configuration
+ * 
+ * Configuration for a list section, which groups items under a title.
+ * Sections help organize list content into logical groups.
+ * 
+ * @category Components
  */
 export interface ListSectionConfig {
   /** Unique identifier for the section */
@@ -106,6 +255,11 @@ export interface ListSectionConfig {
 
 /**
  * Selection change event data
+ * 
+ * Data structure provided with selectionChange events
+ * when list items are selected or deselected.
+ * 
+ * @category Components
  */
 export interface SelectionChangeEvent {
   /** Array of selected item IDs */
@@ -120,6 +274,10 @@ export interface SelectionChangeEvent {
 
 /**
  * List item data
+ * 
+ * Internal data structure for tracking list items and their state.
+ * 
+ * @internal
  */
 export interface ListItemData {
   /** The item's DOM element */
@@ -134,6 +292,11 @@ export interface ListItemData {
 
 /**
  * Configuration interface for the List component
+ * 
+ * Comprehensive options for creating and customizing a List
+ * according to Material Design 3 guidelines.
+ * 
+ * @category Components
  */
 export interface ListConfig {
   /** List selection type */
@@ -163,6 +326,11 @@ export interface ListConfig {
 
 /**
  * List component interface
+ * 
+ * Public API for the List component, providing methods for
+ * item management, selection handling, and event management.
+ * 
+ * @category Components
  */
 export interface ListComponent {
   /** The root element of the list */
@@ -204,6 +372,10 @@ export interface ListComponent {
 
 /**
  * Base component interface
+ * 
+ * Internal interface for component composition in the List component.
+ * 
+ * @internal
  */
 export interface BaseComponent {
   element: HTMLElement;

package/src/components/list/utils.ts

@@ -20,9 +20,15 @@ const LIST_CLASS_NAMES = {
 };
 
 /**
- * Creates a divider element
+ * Creates a divider element for lists
+ * 
+ * Creates a horizontal divider that can be used to separate list items
+ * following Material Design 3 guidelines.
+ * 
  * @param {string} prefix - CSS class prefix
  * @returns {HTMLElement} Divider element
+ * 
+ * @internal
  */
 export const createDivider = (prefix: string): HTMLElement => {
   const divider = document.createElement('div');
@@ -32,10 +38,16 @@ export const createDivider = (prefix: string): HTMLElement => {
 };
 
 /**
- * Creates a section title element
+ * Creates a section title element for lists
+ * 
+ * Creates a section header element used to group list items into logical sections
+ * following Material Design 3 guidelines for list organization.
+ * 
  * @param {string} title - Section title text
  * @param {string} prefix - CSS class prefix
  * @returns {HTMLElement} Section title element
+ * 
+ * @internal
  */
 export const createSectionTitle = (title: string, prefix: string): HTMLElement => {
   const titleEl = document.createElement('div');
@@ -46,10 +58,16 @@ export const createSectionTitle = (title: string, prefix: string): HTMLElement =
 
 /**
  * Creates a DOM element with optional class and content
+ * 
+ * Utility function for creating DOM elements with proper class names and content
+ * for list items and their sub-elements.
+ * 
  * @param {string} tag - HTML tag name
  * @param {string} className - CSS class name
  * @param {string|HTMLElement} [content] - Element content or child element
  * @returns {HTMLElement} Created element
+ * 
+ * @internal
  */
 export const createElement = (tag: string, className: string, content?: string | HTMLElement): HTMLElement => {
   const element = document.createElement(tag);
@@ -66,8 +84,14 @@ export const createElement = (tag: string, className: string, content?: string |
 
 /**
  * Gets the class name for a list element
+ * 
+ * Retrieves the standard class name for list elements from a consistent
+ * centralized naming scheme.
+ * 
  * @param {string} element - Element name
  * @returns {string} The class name string
+ * 
+ * @internal
  */
 export const getListClass = (element: keyof typeof LIST_CLASS_NAMES): string => {
   return LIST_CLASS_NAMES[element];