npm package: @lydio/semantics
Description: HTML standard nodes extension for Lydio
Author: Alex Stevovich
Latest version: 1.0.0

# @lydio/semantics

**Canonical URL:**
[https://alexstevovich.com/r/lydio-semantics-nodejs](https://alexstevovich.com/r/lydio-semantics-nodejs)

HTML standard nodes extension for [Lydio](https://alexstevovich.com/r/lydio-nodejs)

`@lydio/semantics` provides a structured approach to HTML generation, emphasizing semantic correctness and hierarchical meaning extraction. It extends Lydio’s core capabilities by introducing specialized semantic node classes that mirror real-world document structure.

## **Features:**

- **Semantic Elements** – Direct representations of `<article>`, `<section>`, `<nav>`, and more.

- **Extract Meaning** – Convert Lydio structures into meaningful JSON representations.

- **Accessible Defaults** – Encourages `aria-label` and `alt` attributes where relevant.

- **Audit** - Automatically audits semantic components for correctness.

## Installation

```bash

npm  install  @lydio/semantics

```

## Usage

```js

import  semantics  from  '@lydio/semantics';


const  mySite  =  new  Site('example.com', 'Example Site');
const  homepage  =  mySite.addNode(new  Page())
homepage.route = '/'
homepage.description =  'A demo page'
homepage.html.head.addNode(new  Nav());
homepage.html.body
.addNode(new  Main())
.addNode(new  Article())
.addNode(new  P())
.addText('Welcome to our site!')
mySite.addNode(homepage);
mySite.audit();

console.log(mySite.toHtml());
console.log(mySite.toMeaning());

```

## **Semantic Elements Overview**

### **Page Composition**

- **`Site(domain, name)`** → Represents a website structure.

- **`Page(route, options)`** → A structured page with metadata.

- **`Html(lang)`** → The root `<html>` element with language attributes.

- **`Head()`** → The `<head>` section.

- **`Body()`** → The `<body>` section.

### **Document Structure Elements**

- **`Main()`** → `<main>` wrapper.

- **`Article()`** → `<article>` content block.

- **`Section()`** → `<section>` element.

- **`Nav()`** → `<nav>` for navigation menus.

- **`Header()` / `Footer()`** → `<header>` and `<footer>`.

### **Content Elements**

- **`H1` - `H6`** → Headings (`<h1>` to `<h6>`).

- **`P()`** → Paragraph (`<p>`).

- **`Ul()` / `Ol()`** → Unordered and ordered lists.

- **`A().href(value)`** → `<a>` link with an optional `aria-label`.

- **`Img().src(value).alt(value)`** → `<img>` with required `alt`.

- **`Button().ariaLabel(value)`** → `<button>` element with `aria-label`.

## Auditing and Meaning Extraction

Lydio Semantics extends Lydio’s core auditing and meaning extraction capabilities, providing richer analysis and more structured insights into semantic correctness.

### Audit

Every semantic node can be audited to provide feedback on best practices, accessibility compliance, and SEO optimizations.

### Semantic Meaning

Every semantic node can be converted into a structured JSON representation using `toMeaning()`. This ensures that content retains its logical intent when processed, analyzed, or repurposed.

```js
const section = new Section();
section.addNode(new H1().addText('Our Services'));
section.addNode(new P().addText('We offer high-quality software solutions.'));

console.log(section.toMeaning());
```

**Output**

```json
{
    "type": "section",
    "content": [
        { "type": "h", "depth": 1, "content": "Our Services" },
        { "type": "p", "content": "We offer high-quality software solutions." }
    ]
}
```

### See Everything At Once

Unlike raw HTML, which can obscure important attributes or dynamically hidden text, structured meaning extraction allows you to see all relevant content at once. This includes:

- **ARIA labels, alt text, and metadata** that might not be visible in a normal rendered page.

- **Nested content relationships**, showing how different elements fit together.

- **Full textual content**, making proofreading and editing easier.

This is particularly useful for:

- **SEO analysis**

- **Accessibility verification**

- **Large-scale content audits**

- **Machine-readable site overviews**

### Futurism

By pairing layout and meaning as structured data, `@lydio/semantics` enables **new possibilities** for web rendering and accessibility:

- **Adaptive Browsing** – Users could define how they want content presented, separating structure from display.

- **Intelligent Content Processing** – Meaningful data extraction makes websites more interpretable by AI and assistive technologies.

- **Editable JSON-Based Site Representation** – Websites could be edited as structured meaning rather than raw HTML.

## License

Licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

## Trademark

“Lydio” and related marks are trademarks of Alex Stevovich.

See [TRADEMARK.md](./TRADEMARK.md) for details.