feat(core): slot controller ssr hint attributes

.changeset/clear-pugs-make.md

@@ -15,7 +15,7 @@ Before:
 ```js
 connectedCallback() {
   super.connectedCallback();
-  this.items = this.querySelectorAll('my-item');
+  this.items = [...this.querySelectorAll('my-item')];
 }
 ```
 
@@ -24,8 +24,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,64 @@
+module.exports = {
+  templateEngineOverride: 'njk',
+  permalink: '{{ demo.permalink }}',
+  pagination: {
+    data: 'demos',
+    alias: 'demo',
+    size: 1,
+    before: xs => xs.filter(x => x.permalink),
+  },
+  preloads: [
+    '@lit/reactive-element@1.0.2/development/css-tag.js',
+    '@lit/reactive-element@1.0.2/development/decorators/base.js',
+    '@lit/reactive-element@1.0.2/development/decorators/custom-element.js',
+    '@lit/reactive-element@1.0.2/development/decorators/event-options.js',
+    '@lit/reactive-element@1.0.2/development/decorators/property.js',
+    '@lit/reactive-element@1.0.2/development/decorators/query-all.js',
+    '@lit/reactive-element@1.0.2/development/decorators/query-assigned-nodes.js',
+    '@lit/reactive-element@1.0.2/development/decorators/query-async.js',
+    '@lit/reactive-element@1.0.2/development/decorators/query.js',
+    '@lit/reactive-element@1.0.2/development/decorators/state.js',
+    '@lit/reactive-element@1.0.2/development/reactive-element.js',
+    'lit-element@3.0.2/development/experimental-hydrate-support.js',
+    'lit-element@3.0.2/development/lit-element.js',
+    'lit-html@2.0.2/_/a39ea7cf.js',
+    'lit-html@2.0.2/development/async-directive.js',
+    'lit-html@2.0.2/development/directive-helpers.js',
+    'lit-html@2.0.2/development/directive.js',
+    'lit-html@2.0.2/development/directives/guard.js',
+    'lit-html@2.0.2/development/directives/if-defined.js',
+    'lit-html@2.0.2/development/directives/live.js',
+    'lit-html@2.0.2/development/directives/ref.js',
+    'lit-html@2.0.2/development/directives/repeat.js',
+    'lit-html@2.0.2/development/directives/style-map.js',
+    'lit-html@2.0.2/development/directives/template-content.js',
+    'lit-html@2.0.2/development/directives/unsafe-html.js',
+    'lit-html@2.0.2/development/directives/unsafe-svg.js',
+    'lit-html@2.0.2/development/directives/until.js',
+    'lit-html@2.0.2/development/experimental-hydrate.js',
+    'lit-html@2.0.2/development/lit-html.js',
+    'lit-html@2.0.2/development/static.js',
+    'lit@2.0.2/async-directive.js',
+    'lit@2.0.2/decorators.js',
+    'lit@2.0.2/decorators/query-all.js',
+    'lit@2.0.2/decorators/query-assigned-nodes.js',
+    'lit@2.0.2/decorators/query-async.js',
+    'lit@2.0.2/decorators/query.js',
+    'lit@2.0.2/directives/guard.js',
+    'lit@2.0.2/directives/if-defined.js',
+    'lit@2.0.2/directives/live.js',
+    'lit@2.0.2/directives/ref.js',
+    'lit@2.0.2/directives/repeat.js',
+    'lit@2.0.2/directives/style-map.js',
+    'lit@2.0.2/directives/template-content.js',
+    'lit@2.0.2/directives/unsafe-html.js',
+    'lit@2.0.2/directives/unsafe-svg.js',
+    'lit@2.0.2/directives/until.js',
+    'lit@2.0.2/experimental-hydrate-support.js',
+    'lit@2.0.2/experimental-hydrate.js',
+    'lit@2.0.2/html.js',
+    'lit@2.0.2/index.js',
+    'lit@2.0.2/polyfill-support.js',
+    'lit@2.0.2/static-html.js',
+  ],
+};