YAML.js is a JavaScript framework that renders YAML documents into interactive DOM controls and serializes edited data back into YAML. The library preserves leading comments as human friendly labels and understands validation directives embedded in comments.

• Comment driven labels with tooltips that include the canonical key
• Validation directives (#:spec:...) enforced at input time
• Editable primitives with type aware controls (string, number, boolean, enum)
• Collapsible list and nested map rendering with natural key ordering
• Round trip YAML -> DOM -> YAML with comments and directives preserved
• Add new keys or list items on the fly while editing
• Express based example application for hands-on testing

1. File comment: The first comment line in the file is treated as the document description.
2. Key label: A comment directly above a key: line becomes the label shown in the UI.
3. Fallback: If no comment is provided, the raw key name is used as the label.
4. Tooltip: Tooltips always include the canonical key name along with any gathered comments.

Example:

# Application Configuration File

#:spec:range:1024,65535
# Server port number
port: 3000

# Environment name
environment: production

• Label: "Server port number"
• Tooltip: includes "Server port number" and "Key: port"
• Directive: :spec:range:1024,65535 limits the numeric input

npm install

const YAMLFramework = require('yaml.js');

const yamlContent = `
# Application Configuration
#:spec:range:1024,65535
# Server port
port: 3000
#:spec:list:development,production
# Environment
environment: development
`;

const parsed = YAMLFramework.parse(yamlContent);

const renderer = new YAMLFramework.DOMRenderer({
  collapsible: true,
  sortKeys: true,
  editable: true
});
const container = document.getElementById('yaml-container');
renderer.render(parsed, container);

const data = renderer.getData();
const yamlString = YAMLFramework.serialize(data, parsed.comments);

Directives use the form #:spec:<name>:<arguments> and apply to the next key.

Supported directives:

• #:spec:range:min,max restricts numeric values to the provided range (leave one side empty to omit it).
• #:spec:list:option1,option2 renders a dropdown with the allowed values.
• #:spec:positive: enforces values greater than zero.
• #:spec:negative: enforces values less than zero.
• #:spec:count:max warns when a list or map exceeds the maximum length.

const YAMLFramework = require('yaml.js');
const result = YAMLFramework.YAMLParser.parse(yamlContent);
// { data, comments, fileComment }

comments contains { fileComment, keyLabels, keyComments, directives }.

const YAMLFramework = require('yaml.js');

const renderer = new YAMLFramework.DOMRenderer({
  collapsible: true,
  sortKeys: true,
  editable: true,
  allowAdditions: true
});

renderer.render(result, containerElement);
const updated = renderer.getData();
const comments = renderer.getComments();

// With allowAdditions enabled, the DOM controls include affordances to add
// new map keys or list items while editing.

const YAMLFramework = require('yaml.js');
const yamlOutput = YAMLFramework.YAMLSerializer.serialize(updated, comments);

const YAMLFramework = require('yaml.js');

const framework = new YAMLFramework({ editable: true });
framework.render(yamlContent, containerElement);
const yamlOutput = framework.serialize();

Static helpers:

• YAMLFramework.parse(yamlContent)
• YAMLFramework.serialize(data, comments)

Run the demo server:

npm start

Visit http://localhost:3000 to load sample files, edit values with validation, and serialize the results.

• config.yaml - application configuration with numeric ranges and enumerations
• products.yaml - nested catalog data with list and map directives
• users.yaml - sample user directory

YAML.js/
├── src/
│   ├── index.js
│   ├── yaml-parser.js
│   ├── dom-renderer.js
│   └── yaml-serializer.js
├── example/
│   ├── server.js
│   ├── public/
│   │   ├── index.html
│   │   ├── app.js
│   │   └── styles.css
│   └── yaml-samples/
│       ├── config.yaml
│       ├── products.yaml
│       └── users.yaml
├── package.json
└── README.md

ISC