@synergy-design-system/components 2.22.6 → 2.24.0

package/code-quality/html-validate/.eslintrc.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@synergy-design-system/eslint-config-syn"]
+}

package/code-quality/html-validate/.htmlvalidate.js

@@ -0,0 +1,16 @@
+import { defineConfig } from "html-validate";
+import { createElements } from "./scripts/createElements.js";
+
+export default defineConfig({
+  extends: ["html-validate:recommended"],
+  elements: [
+    "html5",
+    createElements(),
+  ],
+  root: true,
+  rules: {
+    'wcag/h32': 'off',
+    'no-deprecated-attr': 'warn',
+    'no-inline-style': 'off'
+  },
+});

package/code-quality/html-validate/DEVELOPMENT.md

@@ -0,0 +1,59 @@
+## About html-validate
+
+Provided rules are created dynamically with some static overrides that cannot be obtained from the components manifest.
+Each element has its own custom configuration that overrides all dynamically created settings.
+Custom rules for each element can be found in `scripts/synergy-element-rules.js`.
+Most of those rules adjust the [Content category](https://html-validate.org/usage/elements.html#content-categories) used for the element. It also keeps track for various other actions like flagging a custom element as [`formAssociated`](https://html-validate.org/usage/elements.html#formassociated).
+
+> The configuration is created on the fly via a function.
+> This may have to reload your IDEs plugin for the change to take effect.
+> For development purposes, it is advised to rely on the command line interface instead!
+
+### Deprecating properties for future releases
+
+For future releases where an attribute is phased out, it is desirable to flag the attribute as [`deprecated`](https://html-validate.org/usage/elements.html#deprecated). This can be done in the custom configuration like this:
+
+```javascript
+// Example: <syn-header>
+// Synergy@1.x still has the attribute show-burger-menu for syn-header,
+// but we know we want to remove it in version 2.0
+/**
+ * @type {import('html-validate').MetaElement}
+ */
+const SynHeader = {
+  attributes: {
+    "show-burger-menu": {
+      boolean: true,
+      deprecated: willDeprecateInRelease(
+        "2.0",
+        "Will be replaced with `burger-menu`",
+      ),
+    },
+  },
+  flow: true,
+  heading: true,
+  sectioning: true,
+};
+```
+
+When the new Synergy major version is released, you can finally deprecate the property:
+
+```javascript
+// Example: <syn-header>
+// Synergy@2.x removed the attribute show-burger-menu for syn-header,
+// so we replace the warning with a hard error
+const SynHeader = {
+  attributes: {
+    "show-burger-menu": {
+      allowed: deprecatedForRelease(
+        "2.0",
+        "Please use the `burger-menu` attribute instead.",
+      ),
+      boolean: true,
+    },
+  },
+  flow: true,
+  heading: true,
+  sectioning: true,
+};
+```

package/code-quality/html-validate/README.md

@@ -0,0 +1,64 @@
+# Linting HTML
+
+The components package also comes with its own set of linting rules that make it possible to automatically check for invalid, deprecated or removed properties. This feature uses [html-validate](https://html-validate.org/) underneath. Rule updates are always shipped with the component release of Synergy to make sure rules are always running against your current Synergy version.
+
+> Linting is only available for static HTML assets. When running `html-validate` via command line, it will only check files with an ending of `.htm` and `.html`.
+> It is currently not planned to support custom framework languages like `JSX` or `VUE`!
+
+## 1. Features
+
+The Synergy ruleset include various rules that make it more secure to use Synergy Web-Components in context of static HTML:
+
+### Property type checking
+
+All attributes are checked for their type (e.g. `Boolean`).
+Also, if the attribute only allows a list of predefined values, it will also show errors via the [`attribute-allowed-values rule`](https://html-validate.org/rules/attribute-allowed-values.html) when providing an unknown value.
+
+### Future deprecations
+
+Future deprecations are flagged as warnings via the [`no-deprecated-attr rule`](https://html-validate.org/rules/no-deprecated-attr.html).
+This will make it easier to spot deprecations for future major releases of Synergy.
+
+### Deprecated attributes
+
+Flags attributes that where removed in major versions as removed via the [`attribute-misuse rule`](https://html-validate.org/rules/attribute-misuse.html). This will help you identify any attributes that have been removed following a major update of Synergy.
+
+## 2. Installation
+
+Please issue one of the following commands to install the linting toolchain (assuming `@synergy-design-system/components` is already installed):
+
+```bash
+npm install --save-dev html-validate
+yarn add --dev html-validate
+pnpm i -D html-validate
+```
+
+## 3. Configuration
+
+### Using the Synergy Default Configuration
+
+The default configuration that may be used as a drop-in setting for getting started. It is based on the [html-validate recommended settings](https://html-validate.org/rules/presets.html#html-validate-recommended). You may use it in the following way:
+
+1. Make sure you have `type="module"` set in your projects `package.json`.
+2. Create a new file `.htmlvalidate.js`
+3. Open the new file and load the synergy configuration: `import synConfig from '@synergy-design-system/components/html-validate.js'; export default synConfig;`
+
+### Adjusting an existing configuration
+
+If you already have a configuration for `html-validate` in place, just add the missing elements to your configuration:
+
+```javascript
+// .htmlvalidate.js
+import { defineConfig } from "html-validate";
+import { createElements } from "@synergy-design-system/components/html-validate/scripts/createElements.js";
+
+export default defineConfig({
+  extends: ["html-validate:recommended"],
+  elements: [
+    "html5",
+    // 👇 Add this statement to make synergy elements work
+    createElements(),
+  ],
+  root: true,
+});
+```

package/code-quality/html-validate/scripts/createElements.js

@@ -0,0 +1,118 @@
+/* eslint-disable import/no-extraneous-dependencies */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { defineMetadata } from 'html-validate';
+import { mergeDeep } from './mergeDeep.js';
+import { rules } from './synergy-element-rules.js';
+
+// Get the destination of the custom elements file
+// Note we need to use relative module imports here
+// as we don´t know the location of the file when it is imported
+const fileSystemDestinationOfCustomElements = import.meta.resolve('../../../dist/custom-elements.json');
+const metadata = JSON.parse(readFileSync(fileURLToPath(fileSystemDestinationOfCustomElements), 'utf-8'));
+
+/**
+ * Creates the attributes for a given declaration
+ * @returns {Record<string, import('html-validate').MetaAttribute>}
+ */
+const createAttributes = (declaration) => {
+  const attributes = (declaration.attributes || [])
+    .filter(attr => !!attr?.type?.text)
+    .map(attr => {
+      // Special case for boolean attributes
+      if (attr.type.text === 'boolean') {
+        return {
+          [attr.name]: {
+            boolean: true,
+          },
+        };
+      }
+
+      // Special case for attributes that have a fixed set of values
+      if (attr.type.text.includes('|')) {
+        const values = attr
+          .type
+          .text
+          .split('|')
+          .filter(value => value.includes("'"))
+          .map(value => value.trim().replaceAll("'", ''))
+          .filter(Boolean);
+
+        if (values.length === 0) {
+          return {
+            [attr.name]: {},
+          };
+        }
+
+        return {
+          [attr.name]: {
+            enum: values,
+            omit: false,
+          },
+        };
+      }
+
+      // Value is a number
+      if (attr.type.text === 'number') {
+        return {
+          [attr.name]: {
+            enum: [/^[+-]?(\d+(\.\d*)?|\.\d+)$/],
+          },
+        };
+      }
+
+      // Default case, just flag all empty values as invalid,
+      // e.g. <syn-input value=""> is invalid, as is <syn-input value>
+      return {
+        [attr.name]: {
+          enum: [/.+/],
+        },
+      };
+    })
+    .filter(Boolean)
+    .reduce((acc, curr) => ({
+      ...acc,
+      ...curr,
+    }), {});
+
+  return attributes;
+};
+
+const createTextContent = (declaration) => {
+  const { slots } = declaration;
+
+  // If the element does not have slots, disallow text content
+  if (!slots || slots.length === 0) {
+    return 'none';
+  }
+  return 'default';
+};
+
+const createMetaElement = (declaration) => ({
+  ...rules[declaration.name],
+  attributes: mergeDeep(
+    createAttributes(declaration),
+    rules[declaration.name]?.attributes || {},
+  ),
+  textContent: createTextContent(declaration),
+});
+
+export const createMetaData = () => {
+  const elements = metadata
+    .modules
+    .filter(module => module.declarations.filter(kind => kind === 'class'))
+    .map(module => module.declarations)
+    .flatMap(declaration => declaration)
+    .map(declaration => [declaration.tagName, createMetaElement(declaration)]);
+
+  const output = Object.fromEntries(elements);
+  // console.log(JSON.stringify(output, null, 2));
+  return output;
+};
+
+export const createElements = () => defineMetadata({
+  ...createMetaData(),
+});
+
+// Enable for debugging
+// console.log(createMetaData());

package/code-quality/html-validate/scripts/deprecation.js

@@ -0,0 +1,28 @@
+/**
+ * Creates a deprecation message for a given synergy version
+ * @param {string} version The Synergy Version the attribute will be deprecated in
+ * @param {string} reason [optional]
+ * @returns {string} The final deprecation message
+ */
+export const willDeprecateInRelease = (version, reason = '') => `
+  This attribute is deprecated and will be removed in Synergy version ${version}!
+  ${reason}
+`.trim();
+
+/**
+ * Creates a deprecation message for a given synergy version
+ * @param {string} version The Synergy Version the attribute was deprecated in
+ * @param {string} reason [optional]
+ * @returns {string} The final deprecation message
+ */
+export const deprecatedForRelease = (version, reason = '') => `
+This attribute was deprecated in Synergy version ${version}!
+${reason}
+Further information can be found at https://github.com/synergy-design-system/synergy-design-system/blob/main/packages/components/BREAKING_CHANGES.md#version-${version.replaceAll('.', '')} for further information.
+`.trim();
+
+// Utility classes for deprecation.
+// Please add one deprecation warning per major version.
+// Also note that you have to return a function that calls
+// deprecateIn, otherwise the message will not be displayed.
+export const deprecatedForV2 = (reason = '') => () => deprecatedForRelease('2.0', reason);

package/code-quality/html-validate/scripts/mergeDeep.js

@@ -0,0 +1,25 @@
+/**
+ * Creates a deep merged clone of the given objects.
+ * @param  {...any} objects The objects to merge
+ * @returns {object} The new object
+ */
+export const mergeDeep = (...objects) => {
+  const isObject = obj => obj && typeof obj === 'object';
+
+  return objects.reduce((acc, obj) => {
+    Object.keys(obj).forEach(key => {
+      const accValue = acc[key];
+      const objValue = obj[key];
+
+      if (Array.isArray(objValue)) {
+        acc[key] = Array.isArray(accValue) ? [...accValue, ...objValue] : [...objValue];
+      } else if (isObject(objValue)) {
+        acc[key] = isObject(accValue) ? mergeDeep(accValue, objValue) : { ...objValue };
+      } else {
+        acc[key] = objValue;
+      }
+    });
+
+    return acc;
+  }, {});
+};