@aquera/nile-elements 1.8.7 → 1.8.8

package/package.json

@@ -3,7 +3,7 @@
   "description": "Webcomponent nile-elements following open-wc recommendations",
   "license": "MIT",
   "author": "nile-elements",
-  "version": "1.8.7",
+  "version": "1.8.8",
   "main": "dist/src/index.js",
   "type": "module",
   "module": "dist/src/index.js",

package/src/nile-side-bar/nile-side-bar.css.ts

@@ -45,6 +45,35 @@ export const styles = css`
   transform: translateX(calc(var(--sidebar-width) - var(--sidebar-collapsed-width)));
 }
 
+/*
+ * Overlay mode: lift the sidebar out of normal flow so expanding it floats
+ * on top of adjacent content instead of pushing siblings. Anchors to the
+ * nearest positioned ancestor; set --sidebar-overlay-position: fixed to pin
+ * it to the viewport instead.
+ */
+:host([overlay]) {
+  position: var(--sidebar-overlay-position, absolute);
+  top: 0;
+  bottom: 0;
+  height: 100%;
+}
+
+:host([overlay][position='left']) {
+  left: 0;
+}
+
+:host([overlay][position='right']) {
+  right: 0;
+}
+
+/* Elevate while expanded so it reads as floating above the page. */
+:host([overlay]:not([collapsed])) {
+  box-shadow: var(
+    --sidebar-overlay-shadow,
+    0px 8px 24px 0px rgba(119, 125, 130, 0.25)
+  );
+}
+
 :host {
   scrollbar-width: thin;
   scrollbar-color: #64748b transparent;

package/src/nile-side-bar/nile-side-bar.test.ts

@@ -0,0 +1,109 @@
+import { expect, fixture, html, oneEvent } from '@open-wc/testing';
+import './nile-side-bar';
+import '../nile-side-bar-expand/nile-side-bar-expand';
+import type { NileSideBar } from './nile-side-bar';
+
+describe('NileSideBar — collapse/expand API', () => {
+  it('1. defaults to expanded (not collapsed) and not overlay', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar></nile-side-bar>`);
+    expect(el.collapsed).to.be.false;
+    expect(el.overlay).to.be.false;
+    expect(el.hasAttribute('overlay')).to.be.false;
+  });
+
+  it('2. collapse() sets collapsed state + reflects attribute', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar></nile-side-bar>`);
+    el.collapse();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.true;
+    expect(el.hasAttribute('collapsed')).to.be.true;
+  });
+
+  it('3. expand() clears collapsed state', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar collapsed></nile-side-bar>`);
+    expect(el.collapsed).to.be.true;
+    el.expand();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.false;
+    expect(el.hasAttribute('collapsed')).to.be.false;
+  });
+
+  it('4. toggle() flips state', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar></nile-side-bar>`);
+    el.toggle();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.true;
+    el.toggle();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.false;
+  });
+
+  it('5. toggle(force) sets an explicit state', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar></nile-side-bar>`);
+    el.toggle(false); // already expanded -> no-op
+    await el.updateComplete;
+    expect(el.collapsed).to.be.false;
+    el.toggle(true);
+    await el.updateComplete;
+    expect(el.collapsed).to.be.true;
+  });
+
+  it('6. emits nile-toggle with new collapsed state', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar></nile-side-bar>`);
+    setTimeout(() => el.collapse());
+    const ev = await oneEvent(el, 'nile-toggle');
+    expect(ev.detail.collapsed).to.be.true;
+  });
+
+  it('7. does NOT emit nile-toggle when state is unchanged', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar></nile-side-bar>`);
+    let fired = false;
+    el.addEventListener('nile-toggle', () => { fired = true; });
+    el.expand(); // already expanded
+    await el.updateComplete;
+    expect(fired).to.be.false;
+  });
+
+  it('8. built-in expand button toggles the sidebar (normal mode)', async () => {
+    const el = await fixture<NileSideBar>(html`
+      <nile-side-bar>
+        <nile-side-bar-expand slot="expand"></nile-side-bar-expand>
+      </nile-side-bar>
+    `);
+    await el.updateComplete;
+    const expandEl = el.querySelector('nile-side-bar-expand') as HTMLElement & { collapsed: boolean };
+    const btn = expandEl.shadowRoot!.querySelector('.expand-btn') as HTMLElement;
+
+    let detail: any;
+    el.addEventListener('nile-toggle', (e: Event) => { detail = (e as CustomEvent).detail; });
+
+    btn.click();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.true;
+    expect(detail.collapsed).to.be.true;
+    expect(expandEl.collapsed).to.be.true; // arrow icon state stays in sync
+
+    btn.click();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.false;
+    expect(expandEl.collapsed).to.be.false;
+  });
+
+  it('9. overlay attribute is opt-in and reflects', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar overlay></nile-side-bar>`);
+    expect(el.overlay).to.be.true;
+    el.overlay = false;
+    await el.updateComplete;
+    expect(el.hasAttribute('overlay')).to.be.false;
+  });
+
+  it('10. methods work the same with overlay enabled', async () => {
+    const el = await fixture<NileSideBar>(html`<nile-side-bar overlay></nile-side-bar>`);
+    el.collapse();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.true;
+    el.expand();
+    await el.updateComplete;
+    expect(el.collapsed).to.be.false;
+  });
+});

package/src/nile-side-bar/nile-side-bar.ts

@@ -18,6 +18,17 @@ import NileElement from '../internal/nile-element';
  * @attr position - Position of the sidebar ("left" | "right"). Defaults to "left".
  * @attr width - Expanded width of the sidebar (px).
  * @attr collapsed-width - Collapsed width of the sidebar (px).
+ * @attr overlay - When set, the sidebar is taken out of normal flow and floats
+ *   on top of adjacent content, so expanding it overlays the page instead of
+ *   pushing siblings sideways.
+ *
+ * @event nile-toggle - Fired after the collapsed state changes (via the built-in
+ *   expand button or the public expand()/collapse()/toggle() methods).
+ *   `event.detail.collapsed` is the new state.
+ *
+ * @method expand() - Expand the sidebar.
+ * @method collapse() - Collapse the sidebar.
+ * @method toggle(force?) - Toggle, or force a specific collapsed state.
  */
 @customElement('nile-side-bar')
 export class NileSideBar extends NileElement {
@@ -25,6 +36,8 @@ export class NileSideBar extends NileElement {
 
   @property({ type: Boolean, reflect: true, attribute: true })collapsed: boolean = false;
 
+  @property({ type: Boolean, reflect: true, attribute: true })overlay: boolean = false;
+
   @property({ type: Boolean, reflect: true, attribute: true })fullHeight: boolean = false;
    
   @property({ type: Number, attribute: true })width: number | null = null;
@@ -62,6 +75,22 @@ export class NileSideBar extends NileElement {
       this.style.setProperty('--sidebar-collapsed-width', `${this.collapsedWidth}px`);
     }
   }
+  public expand(): void {
+    this.setCollapsed(false);
+  }
+  public collapse(): void {
+    this.setCollapsed(true);
+  }
+
+  public toggle(force?: boolean): void {
+    this.setCollapsed(force ?? !this.collapsed);
+  }
+
+  private setCollapsed(value: boolean): void {
+    if (this.collapsed === value) return;
+    this.collapsed = value;
+    this.emit('nile-toggle', { collapsed: value });
+  }
 
   public render(): TemplateResult {
     return html`

package/src/nile-side-bar-expand/nile-side-bar-expand.ts

@@ -30,17 +30,16 @@ export class NileSideBarExpand extends NileElement {
   }
 
   private toggleSidebar() {
-    const sidebar = this.closest('nile-side-bar');
+    const sidebar = this.closest('nile-side-bar') as
+      | (HTMLElement & { toggle?: (force?: boolean) => void })
+      | null;
     if (!sidebar) return;
-
-    const isCollapsed = sidebar.hasAttribute('collapsed');
-    if (isCollapsed) {
-      sidebar.removeAttribute('collapsed');
-      this.collapsed = false;
+    if (typeof sidebar.toggle === 'function') {
+      sidebar.toggle();
     } else {
-      sidebar.setAttribute('collapsed', '');
-      this.collapsed = true;
+      sidebar.toggleAttribute('collapsed', !sidebar.hasAttribute('collapsed'));
     }
+    this.collapsed = sidebar.hasAttribute('collapsed');
   }
 
   public render(): TemplateResult {

package/vscode-html-custom-data.json

@@ -6340,7 +6340,7 @@
     },
     {
       "name": "nile-side-bar",
-      "description": "Nile side-bar component.\n\nAttributes:\n\n  * `collapsed` {`boolean`} - \n\n  * `fullHeight` {`boolean`} - \n\n  * `collapsedWidth` {`number | null`} - \n\n  * `position` {`\"left\" | \"right\"`} - Position of the sidebar (\"left\" | \"right\"). Defaults to \"left\".\n\n  * `width` {`number | null`} - Expanded width of the sidebar (px).\n\n  * `collapsed-width` - Collapsed width of the sidebar (px).\n\nProperties:\n\n  * `collapsed` {`boolean`} - \n\n  * `fullHeight` {`boolean`} - \n\n  * `collapsedWidth` {`number | null`} - \n\n  * `position` {`\"left\" | \"right\"`} - Position of the sidebar (\"left\" | \"right\"). Defaults to \"left\".\n\n  * `width` {`number | null`} - Expanded width of the sidebar (px).\n\n  * `BUBBLES` {`boolean`} - \n\n  * `COMPOSED` {`boolean`} - \n\n  * `CANCELABLE` {`boolean`} - ",
+      "description": "Nile side-bar component.\n\nEvents:\n\n  * `nile-toggle` {} - Fired after the collapsed state changes (via the built-in\nexpand button or the public expand()/collapse()/toggle() methods).\n`event.detail.collapsed` is the new state.\n\nAttributes:\n\n  * `collapsed` {`boolean`} - \n\n  * `fullHeight` {`boolean`} - \n\n  * `collapsedWidth` {`number | null`} - \n\n  * `position` {`\"left\" | \"right\"`} - Position of the sidebar (\"left\" | \"right\"). Defaults to \"left\".\n\n  * `width` {`number | null`} - Expanded width of the sidebar (px).\n\n  * `overlay` {`boolean`} - When set, the sidebar is taken out of normal flow and floats\non top of adjacent content, so expanding it overlays the page instead of\npushing siblings sideways.\n\n  * `collapsed-width` - Collapsed width of the sidebar (px).\n\nProperties:\n\n  * `collapsed` {`boolean`} - \n\n  * `fullHeight` {`boolean`} - \n\n  * `collapsedWidth` {`number | null`} - \n\n  * `position` {`\"left\" | \"right\"`} - Position of the sidebar (\"left\" | \"right\"). Defaults to \"left\".\n\n  * `width` {`number | null`} - Expanded width of the sidebar (px).\n\n  * `overlay` {`boolean`} - When set, the sidebar is taken out of normal flow and floats\non top of adjacent content, so expanding it overlays the page instead of\npushing siblings sideways.\n\n  * `BUBBLES` {`boolean`} - \n\n  * `COMPOSED` {`boolean`} - \n\n  * `CANCELABLE` {`boolean`} - ",
       "attributes": [
         {
           "name": "collapsed",
@@ -6374,9 +6374,18 @@
           "description": "`width` {`number | null`} - Expanded width of the sidebar (px).\n\nProperty: width\n\nDefault: null",
           "values": []
         },
+        {
+          "name": "overlay",
+          "description": "`overlay` {`boolean`} - When set, the sidebar is taken out of normal flow and floats\non top of adjacent content, so expanding it overlays the page instead of\npushing siblings sideways.\n\nProperty: overlay\n\nDefault: false",
+          "valueSet": "v"
+        },
         {
           "name": "collapsed-width",
           "description": "`collapsed-width` - Collapsed width of the sidebar (px).\n\n"
+        },
+        {
+          "name": "onnile-toggle",
+          "description": "`nile-toggle` {} - Fired after the collapsed state changes (via the built-in\nexpand button or the public expand()/collapse()/toggle() methods).\n`event.detail.collapsed` is the new state."
         }
       ]
     },