Writing custom element metadata: Restricting element attributes

Similar to restricting content restricting attributes comes in a few different versions. To define what values attribute accept the attributes property is used, to define what attributes are required use requiredAttributes and to mark an attribute as deprecated use deprecatedAttributes.

Define attribute values

Assuming our <my-component> element has a duck attribute which can take the value huey, dewey or louie we can use the attributes property to define an enumerated list of allowed values:

const { defineMetadata } = require("html-validate");

module.exports = defineMetadata({
  "my-component": {
    flow: true,
    attributes: {
      duck: {
        enum: ["huey", "dewey", "louie"],
      },
    },
  },
});

<my-component duck="dewey">...</my-component>
<my-component duck="flintheart">...</my-component>

error: Attribute "duck" has invalid value "flintheart" (attribute-allowed-values) at inline:2:21:
  1 | <my-component duck="dewey">...</my-component>
> 2 | <my-component duck="flintheart">...</my-component>
    |                     ^^^^^^^^^^


1 error found.

We can also specify regular expressions by surrounding the string with / (remember to escape special characters properly):

 const { defineMetadata } = require("html-validate");

 module.exports = defineMetadata({
   "my-component": {
     flow: true,
     attributes: {
       duck: {
-        enum: ["huey", "dewey", "louie"],
+        enum: ["/\\d+/"],
       },
     },
   },
 });

<my-component ducks="3">...</my-component>
<my-component ducks="huey">...</my-component>

error: Attribute "ducks" has invalid value "huey" (attribute-allowed-values) at inline:2:22:
  1 | <my-component ducks="3">...</my-component>
> 2 | <my-component ducks="huey">...</my-component>
    |                      ^^^^


1 error found.

To force a boolean value similar to disabled, selected etc instead set the boolean property to true.

const { defineMetadata } = require("html-validate");

module.exports = defineMetadata({
  "my-component": {
    flow: true,
    attributes: {
      quacks: {
        boolean: true,
      },
    },
  },
});

<my-component quacks>...</my-component>
<my-component quacks="duck">...</my-component>

error: Attribute "quacks" should omit value (attribute-boolean-style) at inline:2:15:
  1 | <my-component quacks>...</my-component>
> 2 | <my-component quacks="duck">...</my-component>
    |               ^^^^^^


error: Attribute "quacks" has invalid value "duck" (attribute-allowed-values) at inline:2:23:
  1 | <my-component quacks>...</my-component>
> 2 | <my-component quacks="duck">...</my-component>
    |                       ^^^^


2 errors found.

If the value can be omitted (same as the empty value "") set the omit property to true. This is often combined with enum but it should have a default value.

For instance, to allow the quacks attribute to be set to either duck or dog but at the same time not require a value to be set at all omit can be used.

const { defineMetadata } = require("html-validate");

module.exports = defineMetadata({
  "my-component": {
    flow: true,
    attributes: {
      quacks: {
        omit: true,
        enum: ["duck", "dog"],
      },
    },
  },
});

<my-component quacks>...</my-component>
<my-component quacks="duck">...</my-component>

Required attributes

Required attributes (attributes that must be set on an element) can be specified by setting required to true:

const { defineMetadata } = require("html-validate");

module.exports = defineMetadata({
  "my-component": {
    flow: true,
    attributes: {
      duck: {
        required: true,
      },
    },
  },
});

<my-component duck="dewey">...</my-component>
<my-component>...</my-component>

error: <my-component> is missing required "duck" attribute (element-required-attributes) at inline:2:2:
  1 | <my-component duck="dewey">...</my-component>
> 2 | <my-component>...</my-component>
    |  ^^^^^^^^^^^^


1 error found.

Deprecating attributes

Similar to required attribute we can set deprecated to true or a message to mark an attribute as deprecated:

const { defineMetadata } = require("html-validate");

module.exports = defineMetadata({
  "my-component": {
    flow: true,
    attributes: {
      duck: {
        deprecated: true,
      },
    },
  },
});

<my-component duck="dewey">...</my-component>
<my-component>...</my-component>

error: Attribute "duck" is deprecated on <my-component> element (no-deprecated-attr) at inline:1:15:
> 1 | <my-component duck="dewey">...</my-component>
    |               ^^^^
  2 | <my-component>...</my-component>


1 error found.