docs: adds documentation

docs/content/rules/sort-heritage-clauses.mdx

@@ -0,0 +1,249 @@
+---
+title: sort-heritage-clauses
+description: Enforce sorting of heritage clauses for improved readability and maintainability. Use this ESLint rule to keep your heritage clauses well-organized
+shortDescription: Enforce sorted heritage clauses
+keywords:
+  - eslint
+  - sort heritage clauses
+  - sort implements
+  - sort extends
+  - eslint rule
+  - coding standards
+  - code quality
+  - javascript linting
+  - typescript heritage clauses sorting
+---
+
+import CodeExample from '../../components/CodeExample.svelte'
+import Important from '../../components/Important.astro'
+import CodeTabs from '../../components/CodeTabs.svelte'
+import { dedent } from 'ts-dedent'
+
+Enforce sorted heritage clauses.
+
+This rule detects instances where heritage clauses are not sorted and raises linting errors, encouraging developers to arrange elements in the desired order.
+
+## Try it out
+
+<CodeExample
+  alphabetical={dedent`
+    interface Interface extends Logged, Pausable, Startable {
+     // ...
+    }
+
+    class Class implements Logged, Pausable, Startable {
+     // ...
+    }
+  `}
+  lineLength={dedent`
+    interface Interface extends Startable, Pausable, Logged {
+     // ...
+    }
+
+    class Class implements Startable, Pausable, Logged {
+     // ...
+    }
+  `}
+  initial={dedent`
+    interface Interface extends Startable, Logged, Pausable {
+     // ...
+    }
+
+    class Class implements Startable, Logged, Pausable {
+     // ...
+    }
+  `}
+  client:load
+  lang="tsx"
+/>
+
+## Options
+
+This rule accepts an options object with the following properties:
+
+### type
+
+<sub>default: `'alphabetical'`</sub>
+
+Specifies the sorting method.
+
+- `'alphabetical'` — Sort items alphabetically (e.g., “a” < “b” < “c”).
+- `'natural'` — Sort items in a natural order (e.g., “item2” < “item10”).
+- `'line-length'` — Sort items by the length of the code line (shorter lines first).
+
+### order
+
+<sub>default: `'asc'`</sub>
+
+Determines whether the sorted items should be in ascending or descending order.
+
+- `'asc'` — Sort items in ascending order (A to Z, 1 to 9).
+- `'desc'` — Sort items in descending order (Z to A, 9 to 1).
+
+### ignoreCase
+
+<sub>default: `true`</sub>
+
+Controls whether sorting should be case-sensitive or not.
+
+- `true` — Ignore case when sorting alphabetically or naturally (e.g., “A” and “a” are the same).
+- `false` — Consider case when sorting (e.g., “A” comes before “a”).
+
+### specialCharacters
+
+<sub>default: `keep`</sub>
+
+Controls whether special characters should be trimmed, removed or kept before sorting.
+
+- `'keep'` — Keep special characters when sorting (e.g., “_a” comes before “a”).
+- `'trim'` — Trim special characters when sorting alphabetically or naturally (e.g., “_a” and “a” are the same).
+- `'remove'` — Remove special characters when sorting (e.g., “/a/b” and “ab” are the same).
+
+### groups
+
+<sub>
+  type: `Array<string | string[]>`
+</sub>
+<sub>default: `[]`</sub>
+
+Allows you to specify a list of heritage clause groups for sorting.
+
+Predefined groups:
+
+- `'unknown'` — Heritage Clauses that don’t fit into any group specified in the `groups` option.
+
+If the `unknown` group is not specified in the `groups` option, it will automatically be added to the end of the list.
+
+Each heritage clause will be assigned a single group specified in the `groups` option (or the `unknown` group if no match is found).
+The order of items in the `groups` option determines how groups are ordered.
+
+Within a given group, members will be sorted according to the `type`, `order`, `ignoreCase`, etc. options.
+
+Individual groups can be combined together by placing them in an array. The order of groups in that array does not matter.
+All members of the groups in the array will be sorted together as if they were part of a single group.
+
+### customGroups
+
+<sub>
+  type: `{ [groupName: string]: string | string[] }`
+</sub>
+<sub>default: `{}`</sub>
+
+You can define your own groups and use custom glob patterns or regex to match specific heritage clauses.
+
+Use the `matcher` option to specify the pattern matching method.
+
+Each key of `customGroups` represents a group name which you can then use in the `groups` option. The value for each key can either be of type:
+- `string` — A heritage clause's name matching the value will be marked as part of the group referenced by the key.
+- `string[]` — A heritage clause's name matching any of the values of the array will be marked as part of the group referenced by the key.
+The order of values in the array does not matter.
+
+Custom group matching takes precedence over predefined group matching.
+
+#### Example:
+
+Put the `WithId` clause before anything else:
+
+```ts
+interface Interface extends WithId, Logged, Startable {
+ // ...
+}
+```
+
+`groups` and `customGroups` configuration:
+
+```js
+ {
+   groups: [
+     'withIdInterface',           // [!code ++]
+     'unknown'
+   ],
++  customGroups: {                // [!code ++]
++    withIdInterface: 'WithId'   // [!code ++]
++  }                              // [!code ++]
+ }
+```
+
+### matcher
+
+<sub>default: `'minimatch'`</sub>
+
+Determines the matcher used for patterns in the `customGroups` option.
+
+- `'minimatch'` — Use the [minimatch](https://github.com/isaacs/minimatch) library for pattern matching.
+- `'regex'` — Use regular expressions for pattern matching.
+
+## Usage
+
+<CodeTabs
+  code={[
+    {
+      source: dedent`
+        // eslint.config.js
+        import perfectionist from 'eslint-plugin-perfectionist'
+
+        export default [
+          {
+            plugins: {
+              perfectionist,
+            },
+            rules: {
+              'perfectionist/sort-heritage-clauses': [
+                'error',
+                {
+                  type: 'alphabetical',
+                  order: 'asc',
+                  ignoreCase: true,
+                  specialCharacters: 'keep',
+                  matcher: 'minimatch',
+                  groups: [],
+                  customGroups: {}
+                },
+              ],
+            },
+          },
+        ]
+      `,
+      name: 'Flat Config',
+      value: 'flat',
+    },
+    {
+      source: dedent`
+        // .eslintrc.js
+        module.exports = {
+          plugins: [
+            'perfectionist',
+          ],
+          rules: {
+            'perfectionist/sort-heritage-clauses': [
+              'error',
+              {
+                type: 'alphabetical',
+                order: 'asc',
+                ignoreCase: true,
+                specialCharacters: 'keep',
+                matcher: 'minimatch',
+                groups: [],
+                customGroups: {}
+              },
+            ],
+          },
+        }
+      `,
+      name: 'Legacy Config',
+      value: 'legacy',
+    },
+  ]}
+  type="config-type"
+  client:load
+  lang="ts"
+/>
+
+## Version
+
+This rule was introduced in [v4.0.0](https://github.com/azat-io/eslint-plugin-perfectionist/releases/tag/v4.0.0).
+
+## Resources
+
+- [Rule source](https://github.com/azat-io/eslint-plugin-perfectionist/blob/main/rules/sort-heritage-clauses.ts)
+- [Test source](https://github.com/azat-io/eslint-plugin-perfectionist/blob/main/test/sort-heritage-clauses.test.ts)