Skip to content

Docs: Sheath

Jump to bottom
ng-druid edited this page Aug 8, 2025 · 1 revision

Documentation for Angular Sheath Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Core Module
  5. Key Services
  6. Models
  7. Helpers
  8. Usage Examples
  9. Testing

1. Introduction

The Angular Sheath Library provides advanced utilities for monitoring, transforming, and dynamically manipulating DOM elements, CSS classes, and inline styles. It includes services and helpers for tracking DOM mutations, performing dynamic style overlay modifications, and classifying CSS classes.

2. Installation

Install the library using npm:

npm install @your-org/sheath

3. Overview

The Sheath Library empowers Angular developers to interact with the DOM dynamically. It includes two core services:

  1. ClassifyService: Tracks mutations in CSS classes and applies classifications (Keep, Add, or Remove).
  2. StylizerService: Tracks mutations in inline styles and generates dynamic overlay stylesheets.

The library also provides utility helpers for selector validation and managing complex CSS structures.

4. Core Module

SheathModule

The SheathModule is the central Angular module exported by the library. While it does not contain any standalone components, you should import this module to access the library's services.

Module Setup

import { SheathModule } from '@your-org/sheath';

@NgModule({
  imports: [SheathModule],
})
export class AppModule {}

5. Key Services

5.1 ClassifyService

The ClassifyService provides functionality to track changes in an element's CSS classes. It utilizes a MutationObserver to monitor attributes and class mutations.

Features:

  • Tracks class mutations on DOM elements.
  • Categorizes classes into Keep, Add, or Remove classifications using ClassClassification.
  • Generates a class overlay map (ClassMap) for dynamic manipulation.

Example Usage:

import { ClassifyService } from '@your-org/sheath';

constructor(private classifyService: ClassifyService) {}

ngOnInit() {
  const targetNode = document.querySelector('#target-element');
  
  // Initializes class mutation tracking
  this.classifyService.classify({ targetNode });
  
  // Subscribe to mutated class overlays
  this.classifyService.mutated$.subscribe(({ classes }) => {
    console.log(classes); // Output: Map of classified CSS classes
  });
}

5.2 StylizerService

The StylizerService dynamically tracks and generates stylesheets based on mutations to inline styles. It monitors the style attribute using MutationObserver and creates an overlay stylesheet for runtime manipulation.

Features:

  • Tracks inline style mutations on DOM elements.
  • Dynamically merges old and new inline style changes.
  • Generates optimized CSS selectors and builds a dynamic stylesheet.

Example Usage:

import { StylizerService } from '@your-org/sheath';

constructor(private stylizerService: StylizerService) {}

ngOnInit() {
  const targetNode = document.querySelector('#target-element');
  
  // Initializes style mutation tracking
  this.stylizerService.stylize({ targetNode });
  
  // Subscribe to mutated stylesheets
  this.stylizerService.mutated$.subscribe(({ stylesheet }) => {
    console.log(stylesheet); // Output: Generated dynamic CSS
  });
}

6. Models

6.1 ClassClassification

An enumeration for CSS class tracking classifications:

  • KEEP: Class is retained.
  • ADD: Class is newly added.
  • REMOVE: Class is removed.
export enum ClassClassification {
  KEEP,
  ADD,
  REMOVE
}

6.2 ClassMap

A ClassMap is a mapping of selectors to a secondary mapping of CSS classes and their classifications.

export type ClassMap = Map<string, Map<string, ClassClassification>>;

7. Helpers

7.1 isSelectorValid

The isSelectorValid helper checks the validity of a CSS selector.

Syntax:

isSelectorValid({ selector, document }: { selector: string, document: Document }): boolean

Example Usage:

import { isSelectorValid } from '@your-org/sheath';

const valid = isSelectorValid({
  selector: '.container div',
  document: document,
});

console.log(valid); // true or false

8. Usage Examples

Example: Classify DOM Elements

Track class mutations and dynamically classify CSS classes.

constructor(private classifyService: ClassifyService) {}

ngOnInit() {
  const targetNode = document.querySelector('#element-to-observe');
  
  this.classifyService.classify({ targetNode });
  
  this.classifyService.mutated$.subscribe(({ classes }) => {
    console.log(classes); // Example output: Map { '.container': Map { 'example-class' => KEEP } }
  });
}

Example: Stylize DOM Elements

Track style mutations and dynamically generate overlay stylesheets.

constructor(private stylizerService: StylizerService) {}

ngOnInit() {
  const targetNode = document.querySelector('#element-with-inline-styles');
  
  this.stylizerService.stylize({ targetNode });
  
  this.stylizerService.mutated$.subscribe(({ stylesheet }) => {
    console.log(stylesheet); // Example output: Optimized dynamic CSS rules.
  });
}

Example: Validate CSS Selector

Use the isSelectorValid helper to validate a selector.

import { isSelectorValid } from '@your-org/sheath';

const selector = '.invalid-selector::after';

if (isSelectorValid({ selector, document })) {
  console.log('Valid CSS Selector');
} else {
  console.log('Invalid CSS Selector');
}

9. Testing

The Sheath Library includes unit tests that validate its core functionality. Use Jasmine and Karma for testing components and services.

Example Test for ClassifyService

import { TestBed } from '@angular/core/testing';
import { ClassifyService } from '@your-org/sheath';

describe('ClassifyService', () => {
  let service: ClassifyService;

  beforeEach(() => {
    TestBed.configureTestingModule({});
    service = TestBed.inject(ClassifyService);
  });

  it('should classify elements', () => {
    const dummyNode = document.createElement('div');
    service.classify({ targetNode: dummyNode });
    expect(service).toBeTruthy();
  });
});

Example Test for StylizerService

import { TestBed } from '@angular/core/testing';
import { StylizerService } from '@your-org/sheath';

describe('StylizerService', () => {
  let service: StylizerService;

  beforeEach(() => {
    TestBed.configureTestingModule({});
    service = TestBed.inject(StylizerService);
  });

  it('should stylize elements', () => {
    const dummyNode = document.createElement('div');
    service.stylize({ targetNode: dummyNode });
    expect(service).toBeTruthy();
  });
});

Execute tests using:

npm run test

Conclusion

The Angular Sheath Library is a powerful tool for DOM manipulation and real-time modifications to CSS classes and inline styles within Angular applications. It can be integrated seamlessly for advanced CSS tracking and overlay creation.

For feature requests or contributions, feel free to contact the development team!

Clone this wiki locally