Commit 6506aa6f authored by David Sveningsson's avatar David Sveningsson
Browse files

feat(meta): extend element attribute metadata

fixes #71

BREAKING CHANGE: `MetaElement.attribute` has changed from `string[]` to
`MetaAttribute[]` and both `requiredAttributes` and `deprecatedAttributes` has
been merged into object. This only affects API usage, primarily custom rules
accessing attribute metadata.See `MIGRATION.md` for details.

The old format is deprecated but is internally converted as to not break user
configuration. For compatibility it will probably be around for quite a while
but users should try to migrate as soon as possible.
parent 1f992736
# Migration guide
## Upgrading to `%version%`
### Configuration changes
The format for specifying attribute metadata has changed.
This will probably not affect most users but if you have custom element metadata (e.g. `elements.json`) and specify attribute restrictions you should migrate to the new format.
If you do not use custom element metadata you can safely upgrade to this version without any changes.
If you need to maintain backwards compatibility with older versions of `html-validate` you can safely hold of the migration (e.g. you publish a component framework with bundled element metadata and don't want to force an update for end users).
The old format is deprecated but will continue to be supported for now.
Previously the attributes was specified as an array of possible values (strings or regular expressions).
Boolean attributes was specified as `[]` and when value could be omitted it used the magic value `[""]`.
```jsonc
{
"my-custom-input": {
"attributes": {
/* enumeration: must have one of the specified values */
"type": ["text", "email", "tel"],
/* boolean: should not have a value */
"disabled": [],
/* allow omitting value, e.g. it can be set as a boolean or it should be "true" or "false" */
"multiline": ["", "true", "false"]
}
}
}
```
To migrate the array is changed to an object with the properties `enum`, `boolean` and `omit`:
```diff
{
"my-custom-input": {
"attributes": {
/* enumeration: must have one of the specified values */
- "type": ["text", "email", "tel"],
+ "type": {
+ "enum": ["text", "email", "tel"]
+ },
/* boolean: should not have a value */
- "disabled": [],
+ "disabled": {
+ "boolean": true
+ },
/* allow omitting value, e.g. it can be set as a boolean or it should be "true" or "false" */
- "multiline": ["", "true", "false"]
+ "multiline": {
+ "omit": true,
+ "enum": ["true", "false"] // the value "" is no longer specified in the enumeration
+ }
}
}
}
```
The properties `requiredAttributes` and `deprecatedAttributes` have been integrated into the same object:
```diff
{
"my-custom-input": {
- "requiredAttributes": ["type"],
- "deprecatedAttributes": ["autocorrect"]
+ "attributes": {
+ "type": {
+ "required": true
+ },
+ "autocorrect": {
+ "deprecated": true
+ }
+ }
}
}
```
It is perfectly valid to specify attributes as an empty object which is used to signal that an attribute is exists.
When [#68](https://gitlab.com/html-validate/html-validate/-/issues/68) (validate know attributes) is implemented it will be required to list all known attributes but for now no validation will happen without any properties set.
```jsonc
{
"my-custom-input": {
"attributes": {
/* signal that the "foobar" attribute exists but no validation will occur */
"foobar": {}
}
}
}
```
### API changes
If you use `MetaElement` to query attribute metadata you must use the new object.
Typically this should only be if you have a custom rule dealing with attributes.
While the old format is supported in userland internally it is converted to the new format.
For instance, given a rule such as:
```ts
function myCustomRule(node: DOMNode, attr: Attribute, rule: string[]): void {
/* ... */
}
const meta = node.meta.attributes;
for (const attr of node.attributes) {
if (meta[attr.key]) {
myCustomRule(node, attr, meta[attr.key]);
}
}
```
The signature of the function must be changed to:
```diff
-function myCustomRule(node: DOMNode, attr: Attribute, rule: string[]): void {
+function myCustomRule(node: DOMNode, attr: Attribute, rule: MetaAttribute): void {
/* ... */
}
```
If you want backwards compatibility you must handle both `string[]` and `MetaAttribute`, `Array.isArray` can be used to distinguish between the two:
```ts
function myCustomRule(node: DOMNode, attr: Attribute, rule: string[] | MetaAttribute): void {
if (Array.isArray(rule)) {
/* legacy code path */
} else {
/* modern code path */
}
}
```
If the rule used logic to determine if the attribute is boolean it must be changed to use the `boolean` property:
```diff
-const isBoolean = rule.length === 0;
+const isBoolean = rule.boolean;
```
If the rule used logic to determine if the attribute value can be omitted it must be changed to use the `omitted` property:
```diff
-const canOmit = rule.includes("");
+const canOmit = rule.omit;
```
The list of allowed values are must be read from the `enum` property but rules must take care to ensure they work even if `enum` is not set (`undefined`):
```diff
-const valid = rule.includes(attr.value);
+const valid = !rule.enum || rule.enum.includes(attr.value);
```
If you used `requiredAttributes` or `deprecatedAttributes` these have now been integrated into the same object:
```diff
-const isDeprecated = meta.deprecatedAttributes.includes(attr.key);
+const isDeprecated = meta.attribute[attr.key]?.deprecated;
```
......@@ -21,7 +21,9 @@ Array [
Object {
"column": 23,
"context": Object {
"allowed": Array [],
"allowed": Object {
"boolean": true,
},
"attribute": "quacks",
"element": "my-component",
"value": "duck",
......@@ -78,11 +80,13 @@ Array [
Object {
"column": 21,
"context": Object {
"allowed": Array [
"huey",
"dewey",
"louie",
],
"allowed": Object {
"enum": Array [
"huey",
"dewey",
"louie",
],
},
"attribute": "duck",
"element": "my-component",
"value": "flintheart",
......@@ -104,6 +108,8 @@ Array [
]
`;
exports[`docs/guide/metadata/restrict-attributes.md inline validation: omit 1`] = `Array []`;
exports[`docs/guide/metadata/restrict-attributes.md inline validation: regexp 1`] = `
Array [
Object {
......@@ -113,9 +119,11 @@ Array [
Object {
"column": 22,
"context": Object {
"allowed": Array [
/\\^\\\\d\\+\\$/,
],
"allowed": Object {
"enum": Array [
/\\^\\\\d\\+\\$/,
],
},
"attribute": "ducks",
"element": "my-component",
"value": "huey",
......
......@@ -7,6 +7,8 @@ markup["regexp"] = `<my-component ducks="3">...</my-component>
<my-component ducks="huey">...</my-component>`;
markup["boolean"] = `<my-component quacks>...</my-component>
<my-component quacks="duck">...</my-component>`;
markup["omit"] = `<my-component quacks>...</my-component>
<my-component quacks="duck">...</my-component>`;
markup["required"] = `<my-component duck="dewey">...</my-component>
<my-component>...</my-component>`;
markup["deprecated"] = `<my-component duck="dewey">...</my-component>
......@@ -15,31 +17,37 @@ markup["deprecated"] = `<my-component duck="dewey">...</my-component>
describe("docs/guide/metadata/restrict-attributes.md", () => {
it("inline validation: enum", () => {
expect.assertions(1);
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"duck":["huey","dewey","louie"]}}}],"extends":["html-validate:recommended"]});
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"duck":{"enum":["huey","dewey","louie"]}}}}],"extends":["html-validate:recommended"]});
const report = htmlvalidate.validateString(markup["enum"]);
expect(report.results).toMatchSnapshot();
});
it("inline validation: regexp", () => {
expect.assertions(1);
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"ducks":["/\\d+/"]}}}],"extends":["html-validate:recommended"]});
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"ducks":{"enum":["/\\d+/"]}}}}],"extends":["html-validate:recommended"]});
const report = htmlvalidate.validateString(markup["regexp"]);
expect(report.results).toMatchSnapshot();
});
it("inline validation: boolean", () => {
expect.assertions(1);
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"quacks":[]}}}],"extends":["html-validate:recommended"]});
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"quacks":{"boolean":true}}}}],"extends":["html-validate:recommended"]});
const report = htmlvalidate.validateString(markup["boolean"]);
expect(report.results).toMatchSnapshot();
});
it("inline validation: omit", () => {
expect.assertions(1);
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"quacks":{"omit":true,"enum":["duck","dog"]}}}}],"extends":["html-validate:recommended"]});
const report = htmlvalidate.validateString(markup["omit"]);
expect(report.results).toMatchSnapshot();
});
it("inline validation: required", () => {
expect.assertions(1);
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"requiredAttributes":["duck"]}}],"extends":["html-validate:recommended"]});
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"duck":{"required":true}}}}],"extends":["html-validate:recommended"]});
const report = htmlvalidate.validateString(markup["required"]);
expect(report.results).toMatchSnapshot();
});
it("inline validation: deprecated", () => {
expect.assertions(1);
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"deprecatedAttributes":["duck"]}}],"extends":["html-validate:recommended"]});
const htmlvalidate = new HtmlValidate({"elements":["html5",{"my-component":{"flow":true,"attributes":{"duck":{"deprecated":true}}}}],"extends":["html-validate:recommended"]});
const report = htmlvalidate.validateString(markup["deprecated"]);
expect(report.results).toMatchSnapshot();
});
......
......@@ -2,7 +2,9 @@
"my-component": {
"flow": true,
"attributes": {
"quacks": []
"quacks": {
"boolean": true
}
}
}
}
{
"my-component": {
"flow": true,
"deprecatedAttributes": ["duck"]
"attributes": {
"duck": {
"deprecated": true
}
}
}
}
......@@ -2,7 +2,9 @@
"my-component": {
"flow": true,
"attributes": {
"duck": ["huey", "dewey", "louie"]
"duck": {
"enum": ["huey", "dewey", "louie"]
}
}
}
}
{
"my-component": {
"flow": true,
"attributes": {
"quacks": {
"omit": true,
"enum": ["duck", "dog"]
}
}
}
}
......@@ -2,7 +2,9 @@
"my-component": {
"flow": true,
"attributes": {
"ducks": ["/\\d+/"]
"ducks": {
"enum": ["/\\d+/"]
}
}
}
}
{
"my-component": {
"flow": true,
"requiredAttributes": ["duck"]
"attributes": {
"duck": {
"required": true
}
}
}
}
......@@ -17,7 +17,9 @@ Assuming our `<my-component>` element has a `duck` attribute which can take the
"my-component": {
"flow": true,
"attributes": {
"duck": ["huey", "dewey", "louie"]
"duck": {
"enum": ["huey", "dewey", "louie"]
}
}
}
}
......@@ -35,7 +37,9 @@ We can also specify regular expressions by surrounding the string with `/` (reme
"my-component": {
"flow": true,
"attributes": {
"ducks": ["/\\d+/"]
"ducks": {
"enum": ["/\\d+/"]
}
}
}
}
......@@ -51,18 +55,19 @@ We can also specify regular expressions by surrounding the string with `/` (reme
<strong>Tips</strong>
<ul>
<li>Regular expressions and enumeration can be used at the same time.</li>
<li>The empty string <code>""</code> is also valid and means that the value must be empty, e.g. <code>ducks=""</code></li>
</ul>
</div>
To force a boolean value similar to `disabled`, `selected` etc use an empty array `[]`:
To force a boolean value similar to `disabled`, `selected` etc instead set the `boolean` property to `true`.
```json
{
"my-component": {
"flow": true,
"attributes": {
"quacks": []
"quacks": {
"boolean": true
}
}
}
}
......@@ -73,15 +78,43 @@ To force a boolean value similar to `disabled`, `selected` etc use an empty arra
<my-component quacks="duck">...</my-component>
</validate>
## Define required attributes
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.
To define a list of required attributes use `requiredAttributes`:
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.
```json
{
"my-component": {
"flow": true,
"requiredAttributes": ["duck"]
"attributes": {
"quacks": {
"omit": true,
"enum": ["duck", "dog"]
}
}
}
}
```
<validate name="omit" elements="restrict-attributes-omit.json">
<my-component quacks>...</my-component>
<my-component quacks="duck">...</my-component>
</validate>
## Required attributes
Required attributes (attributes that must be set on an element) can be specified by setting `required` to `true`:
```json
{
"my-component": {
"flow": true,
"attributes": {
"duck": {
"required": true
}
}
}
}
```
......@@ -93,13 +126,17 @@ To define a list of required attributes use `requiredAttributes`:
## Deprecating attributes
Similar to required attribute we can use `deprecatedAttributes` to deprecate attributes:
Similar to required attribute we can set `deprecated` to true or a message to mark an attribute as deprecated:
```json
{
"my-component": {
"flow": true,
"deprecatedAttributes": ["duck"]
"attributes": {
"duck": {
"deprecated": true
}
}
}
}
```
......
......@@ -11,9 +11,11 @@ Array [
Object {
"column": 4,
"context": Object {
"allowed": Array [
/\\^\\.\\*\\$/,
],
"allowed": Object {
"enum": Array [
/\\^\\.\\*\\$/,
],
},
"attribute": "href",
"element": "a",
"value": "",
......@@ -30,30 +32,33 @@ Array [
Object {
"column": 14,
"context": Object {
"allowed": Array [
"button",
"checkbox",
"color",
"date",
"datetime-local",
"email",
"file",
"hidden",
"image",
"month",
"number",
"password",
"radio",
"range",
"reset",
"search",
"submit",
"tel",
"text",
"time",
"url",
"week",
],
"allowed": Object {
"enum": Array [
"button",
"checkbox",
"color",
"date",
"datetime-local",
"email",
"file",
"hidden",
"image",
"month",
"number",
"password",
"radio",
"range",
"reset",
"search",
"submit",
"tel",
"text",
"time",
"url",
"week",
],
"required": true,
},
"attribute": "type",
"element": "input",
"value": "foobar",
......
......@@ -9,11 +9,14 @@ Array [
Object {
"column": 17,
"context": Object {
"allowed": Array [
"submit",
"reset",
"button",
],
"allowed": Object {
"enum": Array [
"submit",
"reset",
"button",
],
"required": true,
},
"attribute": "type",
"element": "button",
"value": "foo",
......@@ -30,11 +33,14 @@ Array [
Object {
"column": 15,
"context": Object {
"allowed": Array [
"submit",
"reset",
"button",
],
"allowed": Object {
"enum": Array [
"submit",
"reset",
"button",
],
"required": true,
},
"attribute": "type",
"element": "button",
"value": "spam",
......
......@@ -41,9 +41,7 @@ export interface MetaElement {
labelable?: boolean;
/* attributes */
deprecatedAttributes?: string[];
requiredAttributes?: string[];
attributes?: PermittedAttribute;
attributes?: Record<string, MetaAttribute>;
/* permitted data */
permittedContent?: Permitted;
......@@ -194,65 +192,105 @@ This is typically elements input elements such as `<input>`.
An object with allowed attribute values.
```js
"custom-element": {
"attributes": {
"foo": [
"bar",
"baz"
]
```typescript
export interface MetaAttribute {
boolean?: boolean;
deprecated?: boolean | string;
enum?: Array<string | RegExp>;
required?: boolean;
omit?: boolean;
}
```
```json
{
"custom-element": {
"attributes": {