fix(core)!: deprecate cascades decorator (#2729)

Lit context provides us with an easier to manage and more robust alternative
to the imperative cascades system, let's migrate to that and remove this in PFE 4

.changeset/great-badgers-build.md

@@ -0,0 +1,48 @@
+---
+"@patternfly/pfe-core": major
+---
+`@cascades`: deprecated `@cascades` decorator and `CascadeController`. Use context instead.
+
+**BEFORE**: The element in charge of the context cascades data down to
+specifically named children.
+
+```ts
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators/property.js';
+import { cascades } from '@patternfly/pfe-core/decorators/cascades.js';
+
+class MyMood extends LitElement {
+  @cascades('my-eyes', 'my-mouth')
+  @property() mood: 'happy'|'sad'|'mad'|'glad';
+}
+```
+
+**AFTER**: children subscribe to updates from the context provider.
+
+```ts
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators/property.js';
+import { provide } from '@lit/context';
+import { createContextWithRoot } from '@patternfly/pfe-core/functions/context.js';
+
+export type Mood = 'happy'|'sad'|'mad'|'glad';
+
+export const moodContext = createContextWithRoot<Mood>(Symbol('mood'));
+
+class MyMood extends LitElement {
+  @provide({ context: moodContext })
+  @property() mood: Mood;
+}
+```
+
+```ts
+import { LitElement } from 'lit';
+import { property } from 'lit/decorators/property.js';
+import { consume } from '@lit/context';
+import { moodContext, type Mood } from './my-mood.js';
+
+class MyEyes extends LitElement {
+  @consume({ context: moodContext, subscribe: true })
+  @state() private mood: Mood;
+}
+```

core/pfe-core/controllers/cascade-controller.ts

@@ -4,11 +4,17 @@ import { bound } from '../decorators/bound.js';
 import { debounce } from '../functions/debounce.js';
 import { Logger } from './logger.js';
 
+/**
+ * @deprecated: use context, especially via `@patternfly/pfe-core/functions/context.js`;
+ */
 export interface Options<E extends ReactiveElement> {
   properties: Partial<Record<keyof E, string | string[]>>;
   prefix?: string;
 }
 
+/**
+ * @deprecated: use context, especially via `@patternfly/pfe-core/functions/context.js`;
+ */
 export class CascadeController<E extends ReactiveElement> implements ReactiveController {
   private class: typeof ReactiveElement;
 

core/pfe-core/decorators/cascades.ts

@@ -4,6 +4,7 @@ import { CascadeController } from '../controllers/cascade-controller.js';
 
 /**
  * Cascades the decorated attribute to children
+ * @deprecated: use context, especially via `@patternfly/pfe-core/functions/context.js`;
  */
 export function cascades<T extends ReactiveElement>(...items: string[]): PropertyDecorator {
   return function(proto: T, key: string & keyof T) {