Size

The Size Service and Directive provide a robust system for monitoring and reacting to dimensional changes of HTML elements and the browser window. It allows developers to subscribe to size changes, receive debounced updates, and automatically determine an element's "width zone" (e.g., 'sm', 'md', 'lg') based on its width. This is crucial for creating responsive components and layouts that adapt to different container sizes or the browser viewport.

Technical Overview

This feature consists of two main parts: LmnSizeService and LmnSizeDirective.

LmnSizeService is an injectable root service that manages "size watchers." It uses ResizeObserver for individual elements and listens to window resize events for the main viewport. It calculates element dimensions and determines their width zone. The service also calculates and provides the window's scrollbar width, which can be used as a threshold.

LmnSizeDirective is an attribute directive ([lmnSize]) that simplifies the use of LmnSizeService on specific HTML elements. It handles the registration and unregistration of size watchers for its host element, provides the size change information as an output event (lmnSizeListener) and a signal (size), and can automatically apply CSS classes (lmn-media-sm, lmn-media-md, lmn-media-lg) to the host element based on its current width zone.

Key Features

• Element and Window Size Monitoring: Tracks width and height changes for both specific HTML elements (via ResizeObserver) and the browser window.
• Width Zone Calculation: Automatically determines if an element or the window falls into predefined width zones ('sm', 'md', 'lg') based on its width. Delimiters are WIDTH_ZONE_DELIMITER_SM = 600 and WIDTH_ZONE_DELIMITER_LG = 1024.
• Debounced Updates: Size change emissions are debounced (defaulting to 100ms in the service, configurable via options) to prevent performance issues from rapid-firing events.
• Threshold Adjustments:
  • Supports applying a numeric threshold or the window's scrollbar width as a threshold to the width calculation before determining the width zone. This can help prevent "flickering" between zones when an element's size is close to a breakpoint, especially when scrollbars appear/disappear.
  • The sizeChangesWithThreshold RxJS operator is used for this logic.
• Directive for Easy Integration (lmnSize):
  • Automatically manages watcher registration and unregistration.
  • Outputs an Observable<LmnSizeChange> for custom subscription.
  • Provides a Signal<LmnSizeChange> for reactive consumption of size information.
  • Applies lmn-media-sm/md/lg CSS classes to the host element based on its widthZone.
• Server-Side Rendering (SSR) Safe: Service logic includes checks for isServerRendering() to provide default values and avoid browser-specific API errors.
• Unique Watcher IDs: Each watcher, whether for the window or an element, is identified by a unique ID. The directive generates one or accepts a custom ID. Elements being watched by the service have a data-lmn-size-element-id attribute.

When to Use

• When components need to adapt their layout or behavior based on their own dimensions (container queries philosophy) or the window size.
• To apply responsive styling or logic based on predefined width zones ('sm', 'md', 'lg').
• When you need an observable stream of size changes for an element or the window, with debouncing and threshold options.
• To simplify the process of monitoring element sizes without directly managing ResizeObserver instances (use the directive).
• For more programmatic control or when monitoring elements without a direct template presence (use the service).

Implementation

LmnSizeDirective

Apply the [lmnSize] directive to an HTML element to monitor its size.

Selector: [lmnSize]

Export As: lmnSize

Inputs:

• lmnSize (alias for watcherId): Optional (string, default: auto-generated unique ID like 'lmn-size-X'). A specific ID to use for registering the size watcher.
• LmnSizeWithWindowScrollBarThreshold: Optional (boolean, default: false). If true, the current window scrollbar width is used as a threshold for width zone calculation.
• LmnSizeThreshold: Optional (number, default: 0). A custom numeric threshold (Signal or number) to subtract from the width before determining the width zone.

Outputs:

• lmnSizeListener: Emits an Observable<LmnSizeChange> that consumers can subscribe to for detailed size change events. This observable is already configured with debouncing and any specified thresholds by the service.

Properties (via exportAs):

• size: A Signal<LmnSizeChange> providing the latest size information (width, height, widthZone) of the host element.

CSS Classes Applied to Host Element:

• lmn-media-sm: When widthZone is 'sm'.
• lmn-media-md: When widthZone is 'md'.
• lmn-media-lg: When widthZone is 'lg'.