@trunkjs/element-relocator 1.0.0

package/README.md

@@ -0,0 +1,52 @@
+# @trunkjs/element-relocator
+
+A small Custom Element for temporarily moving an existing DOM element to a responsive destination and restoring its exact original position afterwards.
+
+## Usage
+
+```html
+<tj-responsive>
+  <header>
+    <nav id="navigation">...</nav>
+  </header>
+
+  <aside>
+    <tj-element-relocator
+      source="#navigation"
+      class="md:relocate"
+    ></tj-element-relocator>
+  </aside>
+</tj-responsive>
+```
+
+`tj-element-relocator` itself has no breakpoint logic. `@trunkjs/responsive` (or any other mechanism) controls whether the `relocate` class is present.
+
+When `relocate` appears, the element selected by `source` is moved to the relocator. When it disappears, the source is restored to its exact original DOM position using an internal comment anchor.
+
+## Placement
+
+`placement` controls where the source is placed relative to `<tj-element-relocator>`:
+
+- `inside` (default): source becomes a child of the relocator.
+- `before`: source becomes the previous sibling of the relocator.
+- `after`: source becomes the next sibling of the relocator.
+
+Sibling placement is useful for Web Components and slots because the relocated source remains in the relocator's parent light DOM.
+
+```html
+<my-layout>
+  <tj-element-relocator
+    source="#actions"
+    placement="after"
+    class="md:relocate"
+  ></tj-element-relocator>
+
+  <div id="actions" slot="toolbar">...</div>
+</my-layout>
+```
+
+## Class contract
+
+The element observes changes to `class`, `source`, and `placement`.
+
+The only supported plain class is `relocate`. Class names containing `:` are accepted as responsive expressions. Any other class name without `:` causes a `console.warn`, but does not prevent relocation.

package/index.d.ts

@@ -0,0 +1,22 @@
+export type TjElementRelocatorPlacement = 'inside' | 'before' | 'after';
+export declare class TjElementRelocatorElement extends HTMLElement {
+    static get observedAttributes(): string[];
+    private sourceElement;
+    private sourceAnchor;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(): void;
+    private sync;
+    private relocate;
+    private matchesCurrentSource;
+    private placeSource;
+    private restore;
+    private get placement();
+    private warn;
+    private warnAboutUnsupportedClasses;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'tj-element-relocator': TjElementRelocatorElement;
+    }
+}

package/index.js

@@ -0,0 +1,96 @@
+const n = "relocate", o = "<tj-element-relocator> warning";
+class c extends HTMLElement {
+  constructor() {
+    super(...arguments), this.sourceElement = null, this.sourceAnchor = null;
+  }
+  static get observedAttributes() {
+    return ["class", "source", "placement"];
+  }
+  connectedCallback() {
+    this.sync();
+  }
+  disconnectedCallback() {
+    this.restore();
+  }
+  attributeChangedCallback() {
+    this.isConnected && this.sync();
+  }
+  sync() {
+    this.warnAboutUnsupportedClasses(), this.classList.contains(n) ? this.relocate() : this.restore();
+  }
+  relocate() {
+    var t;
+    const e = (t = this.getAttribute("source")) == null ? void 0 : t.trim();
+    if (!e) {
+      this.warn('Missing "source" selector.');
+      return;
+    }
+    if (this.sourceElement && !this.matchesCurrentSource(e) && this.restore(), !this.sourceElement) {
+      let r;
+      try {
+        r = this.ownerDocument.querySelector(e);
+      } catch {
+        this.warn(`Invalid "source" selector: "${e}".`);
+        return;
+      }
+      if (!r) {
+        this.warn(`Source not found: "${e}".`);
+        return;
+      }
+      if (r === this || r.contains(this)) {
+        this.warn("Source is the relocator or one of its ancestors.");
+        return;
+      }
+      const s = r.parentNode;
+      if (!s) {
+        this.warn(`Source is detached: "${e}".`);
+        return;
+      }
+      this.sourceAnchor = this.ownerDocument.createComment("tj-element-relocator:source"), s.insertBefore(this.sourceAnchor, r), this.sourceElement = r;
+    }
+    this.placeSource();
+  }
+  matchesCurrentSource(e) {
+    var t;
+    try {
+      return ((t = this.sourceElement) == null ? void 0 : t.matches(e)) ?? !1;
+    } catch {
+      return !1;
+    }
+  }
+  placeSource() {
+    if (this.sourceElement)
+      switch (this.placement) {
+        case "before":
+          this.before(this.sourceElement);
+          break;
+        case "after":
+          this.after(this.sourceElement);
+          break;
+        case "inside":
+          this.append(this.sourceElement);
+          break;
+      }
+  }
+  restore() {
+    var e, t;
+    this.sourceElement && ((e = this.sourceAnchor) != null && e.parentNode) && this.sourceAnchor.parentNode.insertBefore(this.sourceElement, this.sourceAnchor.nextSibling), (t = this.sourceAnchor) == null || t.remove(), this.sourceAnchor = null, this.sourceElement = null;
+  }
+  get placement() {
+    const e = this.getAttribute("placement");
+    return e === "before" || e === "after" || e === "inside" ? e : (e && this.warn(`Unsupported placement: "${e}".`), "inside");
+  }
+  warn(e) {
+    console.warn(o, { reason: e, element: this });
+  }
+  warnAboutUnsupportedClasses() {
+    const e = Array.from(this.classList).filter(
+      (t) => t !== n && !t.includes(":")
+    );
+    e.length && this.warn(`Unsupported classes: ${e.join(", ")}.`);
+  }
+}
+customElements.get("tj-element-relocator") || customElements.define("tj-element-relocator", c);
+export {
+  c as TjElementRelocatorElement
+};

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@trunkjs/element-relocator",
+  "version": "1.0.0",
+  "main": "./index.js",
+  "repository": {
+    "directory": "packages/element-relocator",
+    "type": "git",
+    "url": "git+https://github.com/trunkjs/trunkjs-monorepo.git"
+  },
+  "devDependencies": {
+    "@types/jsdom": "^21.1.7",
+    "jsdom": "^26.0.0",
+    "vitest": "^3.2.4"
+  },
+  "type": "module",
+  "types": "./index.d.ts",
+  "web-types": "./web-types.json"
+}

package/skills/element-relocator/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: element-relocator
+description: Use @trunkjs/element-relocator when an existing DOM element must move to another responsive layout position and later return to its exact original position, including Web Component slot and light-DOM sibling scenarios.
+---
+
+# TrunkJS Element Relocator
+
+Use `<tj-element-relocator>` to move an existing element identified by a CSS selector. The relocator does not implement breakpoints itself. Prefer `@trunkjs/responsive` to control when the plain `relocate` class is present.
+
+## Basic usage
+
+```html
+<tj-responsive>
+  <header>
+    <nav id="navigation">...</nav>
+  </header>
+
+  <aside>
+    <tj-element-relocator
+      source="#navigation"
+      class="md:relocate"
+    ></tj-element-relocator>
+  </aside>
+</tj-responsive>
+```
+
+`source` identifies the element being moved. When the relocator has the plain `relocate` class, the source is moved. When `relocate` disappears, the source is restored to its exact original DOM position.
+
+Do not implement separate resize listeners or breakpoint handling around the relocator when `@trunkjs/responsive` can express the condition.
+
+## Placement
+
+Use `placement` to choose where the source is inserted relative to the relocator:
+
+- `inside` (default): the source becomes a child of `<tj-element-relocator>`.
+- `before`: the source becomes its previous sibling.
+- `after`: the source becomes its next sibling.
+
+Prefer `inside` for ordinary DOM relocation. Use `before` or `after` when the source must remain in the surrounding component's light DOM, especially for slot assignment.
+
+```html
+<my-layout>
+  <tj-element-relocator
+    source="#actions"
+    placement="after"
+    class="md:relocate"
+  ></tj-element-relocator>
+
+  <div id="actions" slot="toolbar">...</div>
+</my-layout>
+```
+
+The `slot` attribute remains on the source; sibling placement keeps it a direct light-DOM child of `<my-layout>`.
+
+## Class contract
+
+Treat the relocator's classes as control input, not as general styling classes.
+
+The only supported plain class is `relocate`. Responsive expressions containing `:` are allowed, for example `md:relocate`. Do not add unrelated plain classes such as `hidden`, `toolbar`, or `mobile`; they produce a developer warning.
+
+For implementation details and invariants, see [`ARCHITECTURE.md`](../../ARCHITECTURE.md).

package/web-types.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
+  "name": "@trunkjs/element-relocator",
+  "version": "1.0.0",
+  "contributions": {
+    "html": {
+      "elements": [
+        {
+          "name": "tj-element-relocator",
+          "description": "Relocates a source element when the 'relocate' class is present and restores it to its original DOM position when the class is removed.",
+          "attributes": [
+            {
+              "name": "source",
+              "description": "CSS selector for the element to relocate."
+            },
+            {
+              "name": "placement",
+              "description": "Placement relative to the relocator.",
+              "value": { "type": "enum", "items": ["inside", "before", "after"] }
+            }
+          ]
+        }
+      ]
+    }
+  }
+}