@phcdevworks/spectre-components 1.11.0 → 1.12.0

package/README.md

@@ -16,7 +16,7 @@ themselves — can consume Spectre without a framework-specific adapter.
 | Project team           | `project-design`                    |
 | Repository role        | Spectre L3a Lit web component layer |
 | Package/artifact       | `@phcdevworks/spectre-components`   |
-| Current version/status | 1.11.0                              |
+| Current version/status | 1.12.0                              |
 
 ## Standard Workflow
 
@@ -906,6 +906,48 @@ etc.).
 
 ---
 
+### sp-nav-item
+
+Renders a nav link that can optionally become a dropdown trigger, backed by
+the same Spectre dropdown recipe as `sp-dropdown`. Place it inside `sp-nav`
+alongside plain `<a>` links.
+
+**Attributes**
+
+| Attribute                 | Type    | Default          | Description                                                         |
+| ------------------------- | ------- | ---------------- | ------------------------------------------------------------------- |
+| `dropdown`                | boolean | `false`          | Renders a dropdown trigger + menu instead of a plain `<a>`          |
+| `href`                    | string  | —                | Link target when `dropdown` is `false`                              |
+| `label`                   | string  | —                | Trigger/link text when no content is projected                      |
+| `open`                    | boolean | `false`          | Open/closed menu state (dropdown mode only)                         |
+| `placement`               | string  | `'bottom-start'` | Menu position: `bottom-start`, `bottom-end`, `top-start`, `top-end` |
+| `id` / `title` / `aria-*` | string  | —                | Forwarded to the rendered `<a>` or trigger `<button>`               |
+
+**Content projection** — in dropdown mode, children become the menu content;
+a child with `slot="trigger"` becomes the trigger content instead of `label`.
+Menu content can be a plain list of links or an `sp-grid` for a full mega-menu
+layout. In link mode, children become the link's content.
+
+**Events** — `sp-open` and `sp-close` (dropdown mode only), both `bubbles`.
+
+**Internal targets** — `[data-sp-nav-item-trigger]` selects the trigger
+button; `[data-sp-nav-item-menu]` selects the menu panel.
+
+```html
+<sp-nav>
+  <sp-nav-item href="/">Home</sp-nav-item>
+  <sp-nav-item dropdown label="Products">
+    <sp-grid columns="3" gap="lg">
+      <div>Column one</div>
+      <div>Column two</div>
+      <div>Column three</div>
+    </sp-grid>
+  </sp-nav-item>
+</sp-nav>
+```
+
+---
+
 ### sp-sidebar
 
 Renders an off-canvas `<aside>` with a toggle button and backdrop, backed by the
@@ -1169,6 +1211,7 @@ Each entry point registers only that component and exports only its surface:
 | `.../section`      | `sp-section`      | `defineSpectreSection`, `SpectreSectionElement`, `SpectreSectionProps`                   |
 | `.../stack`        | `sp-stack`        | `defineSpectreStack`, `SpectreStackElement`, stack constants and types                   |
 | `.../nav`          | `sp-nav`          | `defineSpectreNav`, `SpectreNavElement`, `SpectreNavProps`                               |
+| `.../nav-item`     | `sp-nav-item`     | `defineSpectreNavItem`, `SpectreNavItemElement`, `SpectreNavItemProps`                   |
 | `.../sidebar`      | `sp-sidebar`      | `defineSpectreSidebar`, `SpectreSidebarElement`, `SpectreSidebarProps`                   |
 | `.../dropdown`     | `sp-dropdown`     | `defineSpectreDropdown`, `SpectreDropdownElement`, dropdown constants and types          |
 | `.../footer`       | `sp-footer`       | `defineSpectreFooter`, `SpectreFooterElement`, `SpectreFooterProps`                      |

package/dist/index.cjs

@@ -3452,6 +3452,208 @@ function defineSpectreNav(tagName = "sp-nav") {
   customElements.define(tagName, SpectreNavElement);
   return SpectreNavElement;
 }
+var SpectreNavItemElement = class extends SpectreBaseElement {
+  constructor() {
+    super(...arguments);
+    this.dropdown = false;
+    this.href = void 0;
+    this.label = void 0;
+    this.open = false;
+    this.placement = "bottom-start";
+    this.triggerContent = [];
+    this.menuContent = [];
+    this.handleDocumentClick = (event) => {
+      if (!this.open) {
+        return;
+      }
+      if (!event.composedPath().includes(this)) {
+        this.close();
+      }
+    };
+    this.handleDocumentKeydown = (event) => {
+      if (event.key === "Escape" && this.open) {
+        this.close();
+        this.triggerElement?.focus();
+      }
+    };
+  }
+  get id() {
+    return super.id;
+  }
+  set id(value) {
+    super.id = value;
+  }
+  get title() {
+    return super.title;
+  }
+  set title(value) {
+    super.title = value;
+  }
+  isInternalNode(node) {
+    if (node.nodeType !== Node.ELEMENT_NODE) {
+      return false;
+    }
+    const el = node;
+    return el.hasAttribute("data-sp-nav-item-menu") || el.hasAttribute("data-sp-nav-item-trigger");
+  }
+  syncProjectedContent() {
+    const nextTriggerContent = [];
+    const nextMenuContent = [];
+    this.childNodes.forEach((node) => {
+      if (this.isInternalNode(node)) {
+        return;
+      }
+      const isTriggerSlot = node.nodeType === Node.ELEMENT_NODE && node.getAttribute("slot") === "trigger";
+      if (isTriggerSlot) {
+        nextTriggerContent.push(node);
+      } else {
+        nextMenuContent.push(node);
+      }
+    });
+    const changed = nextTriggerContent.length !== this.triggerContent.length || nextTriggerContent.some((n, i) => n !== this.triggerContent[i]) || nextMenuContent.length !== this.menuContent.length || nextMenuContent.some((n, i) => n !== this.menuContent[i]);
+    if (changed) {
+      this.triggerContent = nextTriggerContent;
+      this.menuContent = nextMenuContent;
+    }
+    return changed;
+  }
+  get hasTriggerContent() {
+    return hasMeaningfulContent(this.triggerContent);
+  }
+  get hasMenuContent() {
+    return hasMeaningfulContent(this.menuContent);
+  }
+  connectedCallback() {
+    super.connectedCallback();
+    this.syncProjectedContent();
+    this.startContentObserver();
+    document.addEventListener("click", this.handleDocumentClick);
+    document.addEventListener("keydown", this.handleDocumentKeydown);
+  }
+  disconnectedCallback() {
+    this.stopContentObserver();
+    document.removeEventListener("click", this.handleDocumentClick);
+    document.removeEventListener("keydown", this.handleDocumentKeydown);
+    super.disconnectedCallback();
+  }
+  update(changedProperties) {
+    this.stopContentObserver();
+    super.update(changedProperties);
+    this.startContentObserver();
+  }
+  startContentObserver() {
+    if (this.contentObserver) {
+      return;
+    }
+    this.contentObserver = new MutationObserver(() => {
+      if (this.syncProjectedContent()) {
+        this.requestUpdate();
+      }
+    });
+    this.contentObserver.observe(this, { childList: true });
+  }
+  stopContentObserver() {
+    this.contentObserver?.disconnect();
+    this.contentObserver = void 0;
+  }
+  willUpdate(changedProperties) {
+    if (changedProperties.has("dropdown") && this.dropdown == null) {
+      this.dropdown = false;
+    }
+    if (changedProperties.has("open") && this.open == null) {
+      this.open = false;
+    }
+    if (changedProperties.has("placement") && (this.placement == null || !isDropdownPlacement(this.placement))) {
+      this.placement = "bottom-start";
+    }
+  }
+  get triggerElement() {
+    return this.querySelector("[data-sp-nav-item-trigger]");
+  }
+  toggle() {
+    if (this.open) {
+      this.close();
+    } else {
+      this.openMenu();
+    }
+  }
+  openMenu() {
+    if (this.open) {
+      return;
+    }
+    this.open = true;
+    this.dispatchEvent(new CustomEvent("sp-open", { bubbles: true }));
+  }
+  close() {
+    if (!this.open) {
+      return;
+    }
+    this.open = false;
+    this.dispatchEvent(new CustomEvent("sp-close", { bubbles: true }));
+  }
+  get wrapperClasses() {
+    return spectreUi.getDropdownClasses();
+  }
+  get menuClasses() {
+    return spectreUi.getDropdownMenuClasses({
+      open: this.open ?? false,
+      placement: this.placement
+    });
+  }
+  get navLinkClasses() {
+    return spectreUi.getNavLinkClasses();
+  }
+  renderLink() {
+    return lit.html`<a
+      aria-label="${ifDefined_js.ifDefined(this.forwardedAriaLabel)}"
+      class="${this.navLinkClasses}"
+      href="${ifDefined_js.ifDefined(this.href)}"
+      id="${ifDefined_js.ifDefined(this.id || void 0)}"
+      title="${ifDefined_js.ifDefined(this.title || void 0)}"
+      >${this.hasMenuContent ? this.menuContent : this.label}</a
+    >`;
+  }
+  renderDropdown() {
+    return lit.html`<div
+      class="${this.wrapperClasses}"
+      id="${ifDefined_js.ifDefined(this.id || void 0)}"
+      title="${ifDefined_js.ifDefined(this.title || void 0)}"
+    >
+      <button
+        aria-expanded="${this.open ? "true" : "false"}"
+        aria-haspopup="true"
+        aria-label="${ifDefined_js.ifDefined(this.forwardedAriaLabel ?? this.label)}"
+        class="${this.navLinkClasses}"
+        data-sp-nav-item-trigger
+        type="button"
+        @click="${() => this.toggle()}"
+      >
+        ${this.hasTriggerContent ? this.triggerContent : this.label}
+      </button>
+      <div class="${this.menuClasses}" data-sp-nav-item-menu>
+        ${this.hasMenuContent ? this.menuContent : lit.nothing}
+      </div>
+    </div>`;
+  }
+  render() {
+    return this.dropdown ? this.renderDropdown() : this.renderLink();
+  }
+};
+SpectreNavItemElement.properties = {
+  dropdown: { type: Boolean, reflect: true },
+  href: { type: String },
+  label: { type: String },
+  open: { type: Boolean, reflect: true },
+  placement: { type: String, reflect: true }
+};
+function defineSpectreNavItem(tagName = "sp-nav-item") {
+  const existingElement = customElements.get(tagName);
+  if (existingElement) {
+    return existingElement;
+  }
+  customElements.define(tagName, SpectreNavItemElement);
+  return SpectreNavItemElement;
+}
 var SpectreSidebarElement = class extends SpectreProjectableElement {
   constructor() {
     super(...arguments);
@@ -4012,6 +4214,7 @@ function defineSpectreComponents() {
   defineSpectreFooter();
   defineSpectreModal();
   defineSpectreNav();
+  defineSpectreNavItem();
   defineSpectreSidebar();
   defineSpectreToast();
   defineSpectreTooltip();
@@ -4034,6 +4237,7 @@ exports.SpectreInputElement = SpectreInputElement;
 exports.SpectreLabelElement = SpectreLabelElement;
 exports.SpectreModalElement = SpectreModalElement;
 exports.SpectreNavElement = SpectreNavElement;
+exports.SpectreNavItemElement = SpectreNavItemElement;
 exports.SpectrePricingCardElement = SpectrePricingCardElement;
 exports.SpectreRadioElement = SpectreRadioElement;
 exports.SpectreRatingElement = SpectreRatingElement;
@@ -4065,6 +4269,7 @@ exports.defineSpectreInput = defineSpectreInput;
 exports.defineSpectreLabel = defineSpectreLabel;
 exports.defineSpectreModal = defineSpectreModal;
 exports.defineSpectreNav = defineSpectreNav;
+exports.defineSpectreNavItem = defineSpectreNavItem;
 exports.defineSpectrePricingCard = defineSpectrePricingCard;
 exports.defineSpectreRadio = defineSpectreRadio;
 exports.defineSpectreRating = defineSpectreRating;