@codelaw/rules-stencil 0.0.0-stage → 0.2.0

package/rules/stencil/methods-must-be-public.md

@@ -0,0 +1,69 @@
+---
+id: stencil/methods-must-be-public
+title: "@Method() members are public"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "whether the method is public API needs the author"
+stability: preview
+ported_from: [stencil/methods-must-be-public]
+since: 0.1.0
+---
+
+A `@Method()` isn't marked `private` or `protected`.
+
+**Why:** A `@Method()` is part of the element's public API; hiding it in TypeScript contradicts
+that.
+
+```codelaw
+native: stencil/methods-must-be-public
+```
+
+## How to fix
+
+1. Remove `private`/`protected`, or remove `@Method()` if it isn't public API.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Opens the card. */
+  @Method() private async open() {}
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Opens the card. */
+  @Method() async open() {}
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Opens the card. */
+  @Method() private async open() {}
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** Opens the card. */
+  @Method() async open() {}
+}
+```

package/rules/stencil/no-unused-watch.md

@@ -0,0 +1,68 @@
+---
+id: stencil/no-unused-watch
+title: "@Watch watches a @Prop or @State"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "which member was meant needs the author"
+stability: preview
+ported_from: [stencil/no-unused-watch]
+since: 0.1.0
+---
+
+`@Watch('name')` names a `@Prop` or `@State` of the same component.
+
+**Why:** Watching anything else never fires, so the handler is dead code.
+
+```codelaw
+native: stencil/no-unused-watch
+```
+
+## How to fix
+
+1. Correct the name to the @Prop or @State it should watch, or remove the watcher.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  @State() open = false;
+  @Watch('opened') onOpen() {}
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  @State() open = false;
+  @Watch('open') onOpen() {}
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  @State() open = false;
+  @Watch('opened') onOpen() {}
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  @State() open = false;
+  @Watch('open') onOpen() {}
+}
+```

package/rules/stencil/own-methods-must-be-private.md

@@ -0,0 +1,68 @@
+---
+id: stencil/own-methods-must-be-private
+title: "A component's own methods are private"
+languages: [typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [stencil/own-methods-must-be-private]
+since: 0.1.0
+---
+
+A method of a component that isn't a `@Method()`, a lifecycle method or `render()` is `private`.
+
+**Why:** Only `@Method()` members reach users of the element; a public own method suggests an API
+that isn't there.
+
+```codelaw
+native: stencil/own-methods-must-be-private
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  helper() {
+    return 1;
+  }
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  private helper() {
+    return 1;
+  }
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  helper() {
+    return 1;
+  }
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  private helper() {
+    return 1;
+  }
+}
+```

package/rules/stencil/own-props-must-be-private.md

@@ -0,0 +1,60 @@
+---
+id: stencil/own-props-must-be-private
+title: "A component's own fields are private"
+languages: [typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [stencil/own-props-must-be-private]
+since: 0.1.0
+---
+
+A class field of a component without a Stencil decorator is `private`.
+
+**Why:** Only `@Prop()` fields reach users of the element; a public plain field suggests an API that
+isn't there.
+
+```codelaw
+native: stencil/own-props-must-be-private
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  cache = new Map();
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  private cache = new Map();
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  cache = new Map();
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  private cache = new Map();
+}
+```

package/rules/stencil/prefer-vdom-listener.md

@@ -0,0 +1,67 @@
+---
+id: stencil/prefer-vdom-listener
+title: "DOM events are handled in render(), not with @Listen"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "the handler moves into the rendered markup by hand"
+stability: preview
+ported_from: [stencil/prefer-vdom-listener]
+since: 0.1.0
+---
+
+A component handles DOM events on itself (`click`, `keydown`, …) with an `on…` handler in
+`render()`, not `@Listen`; `@Listen` with a `target` is fine.
+
+**Why:** Handlers in `render()` are scoped to the element they're on and cheaper than a host-wide
+listener.
+
+```codelaw
+native: stencil/prefer-vdom-listener
+```
+
+## How to fix
+
+1. Attach the handler in `render()` (e.g. `onClick={…}` on `<Host>`).
+2. Remove the `@Listen`.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  @Listen('click') onClick() {}
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  @Listen('resize', { target: 'window' }) onResize() {}
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  @Listen('click') onClick() {}
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  @Listen('resize', { target: 'window' }) onResize() {}
+}
+```

package/rules/stencil/prop-readonly.md

@@ -0,0 +1,63 @@
+---
+id: stencil/prop-readonly
+title: "@Prop() members are readonly unless mutable"
+languages: [typescript, tsx]
+fix: auto
+stability: preview
+ported_from: [stencil/props-must-be-readonly]
+since: 0.1.0
+---
+
+A `@Prop()` is `readonly`, unless its options say `mutable: true`.
+
+**Why:** Props are set from outside; a component that writes one by accident fights its parent.
+
+```codelaw
+native: stencil/prop-readonly
+```
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() heading: string;
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() readonly heading: string;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() heading: string;
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() readonly heading: string;
+}
+```

package/rules/stencil/props-must-be-public.md

@@ -0,0 +1,68 @@
+---
+id: stencil/props-must-be-public
+title: "@Prop() members are public"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "whether the field is public API needs the author"
+stability: preview
+ported_from: [stencil/props-must-be-public]
+since: 0.1.0
+---
+
+A `@Prop()` isn't marked `private` or `protected`.
+
+**Why:** A prop is set from outside the component; hiding it in TypeScript contradicts that.
+
+```codelaw
+native: stencil/props-must-be-public
+```
+
+## How to fix
+
+1. Remove `private`/`protected`, or make it a `@State()` if it is internal.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() private readonly heading: string;
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() readonly heading: string;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() private readonly heading: string;
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading. */
+  @Prop() readonly heading: string;
+}
+```

package/rules/stencil/required-jsdoc.md

@@ -0,0 +1,66 @@
+---
+id: stencil/required-jsdoc
+title: "Public members have JSDoc"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "the documentation text needs the author"
+stability: preview
+ported_from: [stencil/required-jsdoc]
+since: 0.1.0
+---
+
+Every `@Prop()`, `@Method()` and `@Event()` has a `/** … */` comment.
+
+**Why:** Stencil turns these comments into the component's documentation and editor hints.
+
+```codelaw
+native: stencil/required-jsdoc
+```
+
+## How to fix
+
+1. Write a `/** … */` comment above the member saying what it is for.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  @Prop() readonly heading: string;
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading shown at the top. */
+  @Prop() readonly heading: string;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  @Prop() readonly heading: string;
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The heading shown at the top. */
+  @Prop() readonly heading: string;
+}
+```

package/rules/stencil/reserved-member-names.md

@@ -0,0 +1,70 @@
+---
+id: stencil/reserved-member-names
+title: "Public members don't reuse HTML element names"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "renaming a public member changes every user"
+stability: preview
+ported_from: [stencil/reserved-member-names]
+since: 0.1.0
+---
+
+A `@Prop()` or `@Method()` isn't named after an HTML global attribute or an `HTMLElement` member
+(`title`, `hidden`, `id`, `click`, …).
+
+**Why:** The element already has a member of that name, so the component's version clashes with it.
+
+```codelaw
+native: stencil/reserved-member-names
+```
+
+## How to fix
+
+1. Rename the member.
+2. Update its users.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The card's title. */
+  @Prop() readonly title: string;
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The card's heading. */
+  @Prop() readonly heading: string;
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The card's title. */
+  @Prop() readonly title: string;
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The card's heading. */
+  @Prop() readonly heading: string;
+}
+```

package/rules/stencil/strict-mutable.md

@@ -0,0 +1,75 @@
+---
+id: stencil/strict-mutable
+title: "mutable: true only on props the component changes"
+languages: [typescript, tsx]
+fix: manual
+fix_reason: "whether the component should change the prop needs the author"
+stability: preview
+ported_from: [stencil/strict-mutable]
+since: 0.1.0
+---
+
+A `@Prop({ mutable: true })` is assigned somewhere in the component.
+
+**Why:** `mutable: true` says the component changes the prop; if it never does, the flag only hides
+that the prop should be `readonly`.
+
+```codelaw
+native: stencil/strict-mutable
+```
+
+## How to fix
+
+1. Remove `mutable: true` and make the prop `readonly`, or assign it where the component means to.
+
+## Examples
+
+### TypeScript
+
+#### Don't
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The count. */
+  @Prop({ mutable: true }) count = 0;
+}
+```
+
+#### Do
+
+```ts
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The count. */
+  @Prop({ mutable: true }) count = 0;
+  private inc() {
+    this.count++;
+  }
+}
+```
+
+### TSX
+
+#### Don't
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The count. */
+  @Prop({ mutable: true }) count = 0;
+}
+```
+
+#### Do
+
+```tsx
+@Component({ tag: 'my-card' })
+export class Card {
+  /** The count. */
+  @Prop({ mutable: true }) count = 0;
+  private inc() {
+    this.count++;
+  }
+}
+```