feat(core): slot controller ssr hint attributes

.changeset/all-tigers-wear.md

@@ -0,0 +1,4 @@
+---
+"@patternfly/elements": patch
+---
+**SSR**: enable more elements and more features to be rendered server-side

.changeset/clear-pugs-make.md

@@ -1,6 +1,5 @@
 ---
 "@patternfly/pfe-core": major
-"@patternfly/elements": patch
 ---
 Enable `connectedCallback()` and context protocol in SSR scenarios.
 
@@ -15,7 +14,7 @@ Before:
 ```js
 connectedCallback() {
   super.connectedCallback();
-  this.items = this.querySelectorAll('my-item');
+  this.items = [...this.querySelectorAll('my-item')];
 }
 ```
 
@@ -24,8 +23,7 @@ After:
 connectedCallback() {
   super.connectedCallback();
   if (!isServer) {
-    this.items = this.querySelectorAll('my-item');
+    this.items = isServer ? [] : [...this.querySelectorAll('my-item')];
   }
 }
 ```
-

core/pfe-core/controllers/slot-controller-server.ts

@@ -0,0 +1,43 @@
+import type { ReactiveElement } from 'lit';
+import {
+  type SlotControllerArgs,
+  type SlotControllerPublicAPI,
+} from './slot-controller.js';
+
+export class SlotController implements SlotControllerPublicAPI {
+  public static default = Symbol('default slot') satisfies symbol as symbol;
+
+  /** @deprecated use `default` */
+  public static anonymous: symbol = this.default;
+
+  static attribute = 'ssr-hint-has-slotted' as const;
+
+  static anonymousAttribute = 'ssr-hint-has-slotted-default' as const;
+
+  constructor(public host: ReactiveElement, ..._: SlotControllerArgs) {
+    host.addController(this);
+  }
+
+  hostConnected?(): Promise<void>;
+
+  private fromAttribute(slots: string | null) {
+    return (slots ?? '')
+        .split(/[, ]/)
+        .map(x => x.trim());
+  }
+
+  getSlotted<T extends Element = Element>(..._: string[]): T[] {
+    return [];
+  }
+
+  hasSlotted(...names: (string | null)[]): boolean {
+    const attr = this.host.getAttribute(SlotController.attribute);
+    const anon = this.host.hasAttribute(SlotController.anonymousAttribute);
+    const hints = new Set(this.fromAttribute(attr));
+    return names.every(x => x === null ? anon : hints.has(x));
+  }
+
+  isEmpty(...names: (string | null)[]): boolean {
+    return !this.hasSlotted(...names);
+  }
+}

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

@@ -1,4 +1,4 @@
-import { isServer, type ReactiveController, type ReactiveElement } from 'lit';
+import type { ReactiveController, ReactiveElement } from 'lit';
 
 interface AnonymousSlot {
   hasContent: boolean;
@@ -49,7 +49,56 @@ const isSlot =
         n === SlotController.default ? !child.hasAttribute('slot')
       : child.getAttribute('slot') === n;
 
-export class SlotController implements ReactiveController {
+export declare class SlotControllerPublicAPI implements ReactiveController {
+  static default: symbol;
+
+  public host: ReactiveElement;
+
+  constructor(host: ReactiveElement, ...args: SlotControllerArgs);
+
+  hostConnected?(): Promise<void>;
+
+  hostDisconnected?(): void;
+
+  hostUpdated?(): void;
+
+  /**
+   * Given a slot name or slot names, returns elements assigned to the requested slots as an array.
+   * If no value is provided, it returns all children not assigned to a slot (without a slot attribute).
+   * @param slotNames slots to query
+   * @example Get header-slotted elements
+   *          ```js
+   *          this.getSlotted('header')
+   *          ```
+   * @example Get header- and footer-slotted elements
+   *          ```js
+   *          this.getSlotted('header', 'footer')
+   *          ```
+   * @example Get default-slotted elements
+   *          ```js
+   *          this.getSlotted();
+   *          ```
+   */
+  getSlotted<T extends Element = Element>(...slotNames: string[]): T[];
+
+  /**
+   * Returns a boolean statement of whether or not any of those slots exists in the light DOM.
+   * @param names The slot names to check.
+   * @example this.hasSlotted('header');
+   */
+  hasSlotted(...names: (string | null | undefined)[]): boolean;
+
+  /**
+   * Whether or not all the requested slots are empty.
+   * @param  names The slot names to query.  If no value is provided, it returns the default slot.
+   * @example this.isEmpty('header', 'footer');
+   * @example this.isEmpty();
+   * @returns
+   */
+  isEmpty(...names: (string | null | undefined)[]): boolean;
+}
+
+export class SlotController implements SlotControllerPublicAPI {
   public static default = Symbol('default slot') satisfies symbol as symbol;
 
   /** @deprecated use `default` */
@@ -94,16 +143,16 @@ export class SlotController implements ReactiveController {
     this.host.requestUpdate();
   }
 
-  hostDisconnected(): void {
-    this.#mo.disconnect();
-  }
-
   hostUpdated(): void {
     if (!this.#slotMapInitialized) {
       this.#initSlotMap();
     }
   }
 
+  hostDisconnected(): void {
+    this.#mo.disconnect();
+  }
+
   #initSlotMap() {
     // Loop over the properties provided by the schema
     for (const slotName of this.#slotNames
@@ -113,31 +162,23 @@ export class SlotController implements ReactiveController {
       const elements = this.#getChildrenForSlot(slotId);
       const slot = this.#getSlotElement(slotId);
       const hasContent =
-          !isServer
-          && !!elements.length
-          || !!slot?.assignedNodes?.()?.filter(x => x.textContent?.trim()).length;
+        !!elements.length || !!slot?.assignedNodes?.()?.filter(x => x.textContent?.trim()).length;
       this.#nodes.set(slotId, { elements, name, hasContent, slot });
     }
     this.host.requestUpdate();
     this.#slotMapInitialized = true;
   }
 
   #getSlotElement(slotId: string | symbol) {
-    if (isServer) {
-      return null;
-    } else {
-      const selector =
+    const selector =
       slotId === SlotController.default ? 'slot:not([name])' : `slot[name="${slotId as string}"]`;
-      return this.host.shadowRoot?.querySelector?.<HTMLSlotElement>(selector) ?? null;
-    }
+    return this.host.shadowRoot?.querySelector?.<HTMLSlotElement>(selector) ?? null;
   }
 
   #getChildrenForSlot<T extends Element = Element>(
     name: string | typeof SlotController.default,
   ): T[] {
-    if (isServer) {
-      return [];
-    } else if (this.#nodes.has(name)) {
+    if (this.#nodes.has(name)) {
       return (this.#nodes.get(name)!.slot?.assignedElements?.() ?? []) as T[];
     } else {
       const children = Array.from(this.host.children) as T[];

core/pfe-core/package.json

@@ -33,6 +33,7 @@
     "./controllers/roving-tabindex-controller.js": "./controllers/roving-tabindex-controller.js",
     "./controllers/scroll-spy-controller.js": "./controllers/scroll-spy-controller.js",
     "./controllers/slot-controller.js": {
+      "node": "./controllers/slot-controller-server.js",
       "import": "./controllers/slot-controller.js",
       "default": "./controllers/slot-controller.js"
     },

docs/components/demos.11tydata.cjs

@@ -0,0 +1,10 @@
+module.exports = {
+  templateEngineOverride: 'njk',
+  permalink: '{{ demo.permalink }}',
+  pagination: {
+    data: 'demos',
+    alias: 'demo',
+    size: 1,
+    before: xs => xs.filter(x => x.permalink),
+  },
+};

docs/components/demos.html

@@ -1,93 +1,52 @@
----js
-{
-templateEngineOverride: 'njk',
-permalink: '{{ demo.permalink }}',
-pagination: {
-  data: 'demos',
-  alias: 'demo',
-  size: 1,
-  before: xs => xs.filter(x => x.permalink),
-},
-preloads: [
-  '@lit/[email protected]/development/css-tag.js',
-  '@lit/[email protected]/development/decorators/base.js',
-  '@lit/[email protected]/development/decorators/custom-element.js',
-  '@lit/[email protected]/development/decorators/event-options.js',
-  '@lit/[email protected]/development/decorators/property.js',
-  '@lit/[email protected]/development/decorators/query-all.js',
-  '@lit/[email protected]/development/decorators/query-assigned-nodes.js',
-  '@lit/[email protected]/development/decorators/query-async.js',
-  '@lit/[email protected]/development/decorators/query.js',
-  '@lit/[email protected]/development/decorators/state.js',
-  '@lit/[email protected]/development/reactive-element.js',
-  '[email protected]/development/experimental-hydrate-support.js',
-  '[email protected]/development/lit-element.js',
-  '[email protected]/_/a39ea7cf.js',
-  '[email protected]/development/async-directive.js',
-  '[email protected]/development/directive-helpers.js',
-  '[email protected]/development/directive.js',
-  '[email protected]/development/directives/guard.js',
-  '[email protected]/development/directives/if-defined.js',
-  '[email protected]/development/directives/live.js',
-  '[email protected]/development/directives/ref.js',
-  '[email protected]/development/directives/repeat.js',
-  '[email protected]/development/directives/style-map.js',
-  '[email protected]/development/directives/template-content.js',
-  '[email protected]/development/directives/unsafe-html.js',
-  '[email protected]/development/directives/unsafe-svg.js',
-  '[email protected]/development/directives/until.js',
-  '[email protected]/development/experimental-hydrate.js',
-  '[email protected]/development/lit-html.js',
-  '[email protected]/development/static.js',
-  '[email protected]/async-directive.js',
-  '[email protected]/decorators.js',
-  '[email protected]/decorators/query-all.js',
-  '[email protected]/decorators/query-assigned-nodes.js',
-  '[email protected]/decorators/query-async.js',
-  '[email protected]/decorators/query.js',
-  '[email protected]/directives/guard.js',
-  '[email protected]/directives/if-defined.js',
-  '[email protected]/directives/live.js',
-  '[email protected]/directives/ref.js',
-  '[email protected]/directives/repeat.js',
-  '[email protected]/directives/style-map.js',
-  '[email protected]/directives/template-content.js',
-  '[email protected]/directives/unsafe-html.js',
-  '[email protected]/directives/unsafe-svg.js',
-  '[email protected]/directives/until.js',
-  '[email protected]/experimental-hydrate-support.js',
-  '[email protected]/experimental-hydrate.js',
-  '[email protected]/html.js',
-  '[email protected]/index.js',
-  '[email protected]/polyfill-support.js',
-  '[email protected]/static-html.js',
-]
-}
----
 <!DOCTYPE html>
-<html lang="en" dir="ltr" style="height: 100%">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-    <meta name="description" content="PatternFly Elements: A set of community-created web components based on PatternFly design.">
-    <link href="{{ '/brand/logo/svg/pfe-icon-blue.svg' | url }}" rel="shortcut icon">
-    <title>{{ demo.title or (demo.tagName) }} | PatternFly Elements</title>
-    <link rel="preconnect" href="https://ga.jspm.io">
-    <link rel="preconnect" href="https://fonts.gstatic.com">
-    <script type="importmap">{{ importMap | dump | safe }}</script>
-    {%- for path in preloads -%}
-    <link rel="modulepreload" href="https://ga.jspm.io/npm:{{ path }}">
-    {%- endfor -%}
-    <link rel="stylesheet" href="{{ '/main.css' | url }}">
-    <noscript><link href="{{ '/core/styles/pf--noscript.min.css' | url }}" rel="stylesheet"></noscript>
-    <script async src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js"></script>
-    <script type="module">import 'element-internals-polyfill';</script>
-  </head>
-  <body style="height: 100%">
-    <main style="height: 100%">
-      <div data-demo="{{demo.tagName}}">{% if demo.filePath %}
-        {%- include demo.filePath -%}{% endif %}
-      </div>
-    </main>
-  </body>
+<html lang="en"
+      dir="ltr">
+
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport"
+        content="width=device-width, initial-scale=1">
+  <meta name="description"
+        content="PatternFly Elements: A set of community-created web components based on PatternFly design.">
+  <link href="/brand/logo/svg/pfe-icon-blue.svg"
+        rel="shortcut icon">
+  <title>{{ demo.title or (demo.tagName) }} | PatternFly Elements</title>
+  <link rel="preconnect"
+        href="https://ga.jspm.io">
+  <link rel="preconnect"
+        href="https://fonts.gstatic.com">
+  <script type="importmap">{{ importMap | dump | safe }}</script>
+  <link rel="stylesheet"
+        href="/main.css">
+  <noscript>
+    <link href="/core/styles/pf--noscript.min.css"
+          rel="stylesheet">
+  </noscript>
+  <script async
+          src="https://ga.jspm.io/npm:[email protected]/dist/es-module-shims.js"></script>
+  <script type="module">import 'element-internals-polyfill';</script>
+  <style>
+    html,
+    body,
+    main {
+      min-height: 100%;
+    }
+  </style>
+  <noscript>
+    <style>
+      :not(:defined) {
+        opacity: 1;
+      }
+    </style>
+  </noscript>
+</head>
+
+<body>
+  <main>
+    <div data-demo="{{demo.tagName}}">{% if demo.filePath %}
+      {%- include demo.filePath -%}{% endif %}
+    </div>
+  </main>
+</body>
+
 </html>