Controller: @phase2/outline-controller-slot-manager

packages/controllers/slot-manager/README.md

@@ -0,0 +1,47 @@
+# Slot Manager
+
+The `SlotManager` is a utility class for managing slots in Lit web components. It provides several methods to interact with and manipulate slots.
+
+## Installation
+
+To use the `SlotManager`, you need to install the required dependencies:
+
+```bash
+yarn add -D @phase2/outline-controller-slot-manager
+```
+
+## Usage
+
+### Importing `SlotManager`
+
+```typescript
+import { SlotManager } from '@phase2/outline-controller-slot-manager';
+```
+
+### Instantiating `SlotManager`
+
+```typescript
+import { LitElement, html } from 'lit';
+import { SlotManager } from '@phase2/outline-controller-slot-manager';
+
+class MyElement extends LitElement {
+  slotManager: SlotManager;
+
+  constructor() {
+    super();
+    this.slotManager = new SlotManager(this);
+  }
+}
+```
+
+## Details
+
+- `getSlottedNodes(slotName: SlotName = null)`: This method retrieves all nodes slotted under the given slot name. If the slot name is null or an empty string, it returns the default slot nodes. If no slotted nodes are found, it returns `false`.
+
+- `doesSlotExist(slotName: SlotName = null)`: This method checks if a slot with the given name exists in the host element. It returns `true` if the slot exists, `false` otherwise.
+
+- `isDefaultSlotText(node: Node)`: This method checks if a given node is a default slot text. It returns `true` if the node is a default slot text, `false` otherwise.
+
+- `isDefaultSlotElement(node: Node)`: This method checks if a given node is a default slot element. It returns `true` if the node is a default slot element, `false` otherwise.
+
+- `conditionalSlot(slotName: SlotName = null, extraClasses: string | null = null)`: This method conditionally renders a slot with a wrapper and additional classes. It returns the rendered slot or `null` if the slot does not exist.

packages/controllers/slot-manager/index.ts

@@ -0,0 +1 @@
+export { SlotManager } from './src/slot-manager';

packages/controllers/slot-manager/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@phase2/outline-controller-slot-manager",
+  "version": "0.0.0",
+  "description": "Slot management utilities for web components.",
+  "keywords": [
+    "outline components",
+    "outline design",
+    "slots",
+    "shadow DOM"
+  ],
+  "main": "index.ts",
+  "types": "index.ts",
+  "typings": "index.d.ts",
+  "files": [
+    "/dist/",
+    "/src/",
+    "!/dist/tsconfig.build.tsbuildinfo"
+  ],
+  "author": "Phase2 Technology",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/phase2/outline.git",
+    "directory": "packages/controllers/slot-manager"
+  },
+  "license": "BSD-3-Clause",
+  "scripts": {
+    "build": "node ../../../scripts/build.js",
+    "package": "yarn publish"
+  },
+  "dependencies": {
+    "lit": "^2.3.1"
+  },
+  "devDependencies": {
+    "tslib": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./index.ts"
+  }
+}

packages/controllers/slot-manager/src/slot-manager.ts

@@ -0,0 +1,117 @@
+import { ReactiveControllerHost } from 'lit';
+import { classMap } from 'lit/directives/class-map.js';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import { html } from 'lit/static-html.js';
+
+/**
+ * @typedef SlotName
+ * @type {string | null}
+ * @description A type for slot name.
+ */
+type SlotName = string | null;
+
+/**
+ * @class SlotManager
+ * @description Slot management utilities for Lit web components.
+ *
+ * @param {ReactiveControllerHost & Element} host - The host element.
+ */
+export class SlotManager {
+  host: ReactiveControllerHost & Element;
+
+  /**
+   * @constructor
+   * @description Store a reference to the host.
+   * @param {ReactiveControllerHost & Element} host - The host element.
+   */
+  constructor(host: ReactiveControllerHost & Element) {
+    this.host = host;
+  }
+
+  /**
+   * @method getSlottedNodes
+   * @description Get slotted nodes by slot name.
+   * @param {SlotName} slotName - The name of the slot to search for. If null or empty string, the method will return the default slot nodes.
+   * @returns {Node[] | false} An array of slotted nodes if any are found, or `false` if no slotted nodes are found.
+   */
+  getSlottedNodes(slotName: SlotName = null) {
+    const defaultSlot = slotName === '' || slotName === null;
+    let slottedNodes = [];
+
+    if (defaultSlot) {
+      slottedNodes = Array.from(this.host.childNodes).filter(
+        node => this.isDefaultSlotText(node) || this.isDefaultSlotElement(node)
+      );
+    } else {
+      slottedNodes = Array.from(
+        this.host.querySelectorAll(`[slot=${slotName}]`)
+      );
+    }
+
+    if (slottedNodes.length) {
+      return slottedNodes;
+    } else {
+      return false;
+    }
+  }
+
+  /**
+   * @method doesSlotExist
+   * @description Check if a slot exists.
+   * @param {SlotName} slotName - The slot name to check for.
+   * @returns {boolean} True if the slot exists, false otherwise.
+   */
+  doesSlotExist(slotName: SlotName = null) {
+    return Boolean(this.getSlottedNodes(slotName));
+  }
+
+  /**
+   * @method isDefaultSlotText
+   * @description Check if a node is a default slot text.
+   * @param {Node} node - The node to check.
+   * @returns {boolean} True if the node is a default slot text, false otherwise.
+   */
+  isDefaultSlotText(node: Node) {
+    return node.nodeType === node.TEXT_NODE && node.textContent!.trim() !== '';
+  }
+
+  /**
+   * @method isDefaultSlotElement
+   * @description Check if a node is a default slot element.
+   * @param {Node} node - The node to check.
+   * @returns {boolean} True if the node is a default slot element, false otherwise.
+   */
+  isDefaultSlotElement(node: Node) {
+    return (
+      node.nodeType === node.ELEMENT_NODE &&
+      (node as HTMLElement).getAttribute('slot') === null
+    );
+  }
+
+  /**
+   * @method conditionalSlot
+   * @description Conditionally render a slot with a wrapper and additional classes.
+   * @param {SlotName} slotName - The slot name.
+   * @param {string | null} [extraClasses=null] - Additional classes to add to the wrapper.
+   * @returns {TemplateResult | null} The rendered slot or null if the slot does not exist.
+   */
+  conditionalSlot(
+    slotName: SlotName = null,
+    extraClasses: string | null = null
+  ) {
+    const defaultSlot = slotName === '' || slotName === null;
+    const wrapperClasses = {
+      'slot-default': defaultSlot,
+      [`slot-${slotName}`]: !defaultSlot,
+      [`${extraClasses}`]: extraClasses !== null,
+    };
+
+    if (this.doesSlotExist(slotName)) {
+      return html`<div class="${classMap(wrapperClasses)}">
+        <slot name="${ifDefined(defaultSlot ? undefined : slotName)}"></slot>
+      </div>`;
+    } else {
+      return null;
+    }
+  }
+}

packages/controllers/slot-manager/tsconfig.build.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "./dist"
+  },
+  "include": ["index.ts", "src/**/*", "tests/**/*"],
+  "references": [{ "path": "../../outline-core/tsconfig.build.json" }]
+}