issue-#34 - Progress on initial design spec finalization - Added prop…

…erties.

- Added event handling example.
- Added doc. statements to component source.

apps/atomic-ui-js-site/src/app/components/x-toggleclassonscroll/page.tsx → apps/atomic-ui-js-site/src/app/components/x-toggleonscroll/page.tsx

@@ -1,16 +1,19 @@
-import XToggleClassOnScrollComponent from 'atomic-ui-js-next/x-toggleclassonscroll';
+import XToggleClassOnScrollComponent from 'atomic-ui-js-next/x-toggleonscroll';
 import XRippleComponent from 'atomic-ui-js-next/x-ripple';
 import styles from './page.module.scss';
 
-const triggerThresholds = Array(10).fill(null, 0, 10).map((_, i) => i * 0.1);
+// const triggerThresholds = Array(10).fill(null, 0, 10).map((_, i) => i * 0.1);
 
-interface LipsumArticleProps extends IntersectionObserverInit {
+interface LipsumArticleProps /*extends IntersectionObserverInit*/ {
   anchorTarget?: string;
   className?: string;
   classNameToToggle?: string;
   scrollableParent?: string;
   title?: string;
   triggerTarget?: string;
+  root?: Element | Document | null;
+  rootMargin?: string;
+  threshold?: number | number[];
 }
 
 const lipsumArticle = ({

apps/atomic-ui-js-site/src/data/generated/navigation-items.ts

@@ -77,8 +77,8 @@ export const navigationItems: NavItem[] = [{
         },
         {
           'label': 'X-toggleclassonscroll',
-          'uri': '/components/x-toggleclassonscroll/',
-          'alias': 'x-toggleclassonscroll'
+          'uri': '/components/x-toggleonscroll/',
+          'alias': 'x-toggleonscroll'
         }
       ]
     },

apps/atomic-ui-js-site/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../base.tsconfig.json",
+  "extends": "../../tsconfig.json",
   "module": "esnext",
   "compilerOptions": {
     "target": "es5",

packages/atomic-ui-js-next/x-toggleclassonscroll/index.js → packages/atomic-ui-js-next/x-toggleonscroll/index.js

@@ -1,6 +1,6 @@
 import lazy from 'next/dynamic';
 
-const XToggleClassOnScrollComponent = lazy(() => import('atomic-ui-js-react/x-toggleclassonscroll'), {
+const XToggleClassOnScrollComponent = lazy(() => import('atomic-ui-js-react/x-toggleonscroll'), {
   ssr: false
 });
 

packages/atomic-ui-js-react/index.js

@@ -1,3 +1,3 @@
 export * from './x-field/index.js';
 export * from './x-ripple/index.js';
-export * from './x-toggleclassonscroll/index.js';
+export * from './x-toggleonscroll/index.js';

packages/atomic-ui-js-react/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../base.tsconfig.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "types": [
       "atomic-ui-js"

packages/atomic-ui-js-react/x-toggleclassonscroll/index.js → packages/atomic-ui-js-react/x-toggleonscroll/index.js

@@ -2,7 +2,7 @@
 
 import React from 'react';
 import {createComponent} from '@lit-labs/react';
-import {XToggleClassOnScrollElement} from 'atomic-ui-js/x-toggleclassonscroll/index.js';
+import {XToggleClassOnScrollElement} from 'atomic-ui-js/x-toggleonscroll/index.js';
 
 const XToggleClassOnScrollComponent = createComponent({
   tagName: XToggleClassOnScrollElement.localName,

packages/atomic-ui-js/css/modules/index.css

@@ -18,4 +18,4 @@
 @import url("form.css");
 @import url("menu.css");
 @import url("table.css");
-@import url("../../x-toggleclassonscroll/index.css");
+@import url("../../x-toggleonscroll/index.css");

packages/atomic-ui-js/tsconfig.json

@@ -1,5 +1,5 @@
 {
-  "extends": "../../base.tsconfig.json",
+  "extends": "../../tsconfig.json",
   "compilerOptions": {
     "esModuleInterop": true,
     "lib": [

packages/atomic-ui-js/x-toggleonscroll/README.md

@@ -0,0 +1,119 @@
+# x-toggleonscroll
+
+Toggles a classname on an element (itself by default) when ever target 'trigger' element is scrolled in, and/or out, from the 'container' element (default element used by `IntersectionObserver` (body/html element), by default).
+
+## Potential Alternate Names
+
+- `x-with-intersection-observer`.
+- `x-intersection-observer`.
+
+## Design
+
+### Initially Identified Use Cases
+
+- To show a "back to top" button which only slides into view when a target element is taking a specific percent of a view pane's visible space, or vice-versa.
+- To show a "Feedback" tab (on the side of browser screen) "".
+- For any effect "".
+
+### Properties. 
+
+- `rootSelector: string` - Scrollable ancestor element to observe intersections on;  Documents scroll/view pane, by default.
+- `root(): Element | Document` - Scroll element getter;  Default `Document`.
+- `rootMargin: string` - Padding to add to the root bounds view pane (see MDN Intersection Observer docs for more).
+- `targetSelector: string` - Element to observe for intersections on `root`
+- `target(): Element` - Target element getter;  Default `self`.
+- `threshold: number | number[]` - Intersection threshold(s) on which to trigger observer callback.
+- `axis: 'x' | 'y' | 'xy'` - Axis we're allowing user-land callback to be triggered on;  E.g., when 
+- `classNameToToggle: string` - Optional classname to toggle on 
+- `classNameToggleTargetSelector: string` - Used in conjunction with `classNameToToggle` -
+- `classNameToggleTarget(): string` - Getter.
+- `onintersection: (event: CustomEvent<{records: IntersectionObserverEntry}>) => void` - Intersection event handling prop.
+
+### Events
+
+- `'x-toggleonscroll-intersection': CustomEvent<{records: IntersectionObserverEntry}>`  - Custom intersection event.
+
+### Basic Use Case Example
+
+In this example component should toggle `.some-css-class`, on itself. whenever the `header` element scrolls in/out of the ('default') scrollpane view.
+
+```html
+<!doctype>
+<html lang="en">
+<title>Example</title>
+<head>
+  <!-- Setup styles -->
+  <style>
+    .back-to-top-container {
+      display: inline-flex;
+      justify-content: flex-end;
+      flex-flow: row nowrap;
+      position: sticky;
+      left: 100%;
+      bottom: 1.5rem;
+    }
+
+    .back-to-top-btn {
+      transition: transform 0.21s ease-in-out, opacity 0.21s;
+      transform: translateX(0);
+      opacity: 1;
+    }
+
+    .back-to-top-btn--visible {
+      transform: translateX(100%);
+      opacity: 0;
+    }
+  </style>
+  <title>Example</title>
+</head>
+<body>
+<header>
+  <h1>Header</h1>
+</header>
+
+<x-toggleonscroll
+  classNameToToggle="back-to-top-btn--visible"
+  classNameToggleTarget="back-to-top-btn"
+  target="header"
+  threshold="[0.5, 1]"
+  rootMargin="16% 0% 0% 0%">
+  <p>Lorem Ipsum ...</p>
+
+  <p>...</p>
+
+  <div class="back-to-top-container">
+    <a href="#" class="back-to-top-btn x-btn x-filled x-theme-primary">
+      <x-ripple></x-ripple>
+      <span>Back to top</span>
+    </a>
+  </div>
+</x-toggleonscroll>
+
+<script type="module">
+  import {XToggleClassOnScrollElement} from "atomic-ui-js/x-toggleonscroll";
+
+  const {localName: xToggleClassOnScrollName} = XToggleClassOnScrollElement;
+  
+  window.addEventListener('DOMContentLoaded', () => {
+      document.querySelector(xToggleClassOnScrollName)
+              .addEventListener(`${xToggleClassOnScrollName}-intersection`, e => {
+                  const {currentTarget, detail: {records}} = e;
+                  // Handle intersection observer callback result (records)
+                  records.forEach(r => {
+                      // In this scenario, toggle DOM rendering of our '.back-to-top-container' 
+                      (currentTarget.classNameToggleTarget ?? r.target).hidden = r.isIntersecting;
+                  });
+              });
+  }, {once: true});
+</script>
+</body>
+</html>
+```
+
+## Notes:
+
+- `#IntersectionObserverEntry.intersectionRatio` is the ratio for the entire element (along both axis).
+
+## References:
+
+- IntersectionObserver API: https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API

packages/atomic-ui-js/x-toggleonscroll/index.css

@@ -0,0 +1,3 @@
+x-toggleonscroll {
+  display: block;
+}

packages/atomic-ui-js/x-toggleonscroll/index.js

@@ -0,0 +1,2 @@
+export * from './x-toggleonscroll.js';
+export * from './register.js';

packages/atomic-ui-js/x-toggleclassonscroll/register.js → packages/atomic-ui-js/x-toggleonscroll/register.js

@@ -1,4 +1,4 @@
-import {XToggleClassOnScrollElement} from './x-toggleclassonscroll.js';
+import {XToggleClassOnScrollElement} from './x-toggleonscroll.js';
 import {registerCustomElement} from '../utils/index.js';
 
 registerCustomElement(XToggleClassOnScrollElement.localName, XToggleClassOnScrollElement);

packages/atomic-ui-js/x-toggleclassonscroll/x-toggleclassonscroll.js → packages/atomic-ui-js/x-toggleonscroll/x-toggleonscroll.js

@@ -15,7 +15,7 @@ import {
   typeOf
 } from '../utils/index.js';
 
-export const xToggleClassOnScrollName = 'x-toggleclassonscroll';
+export const xToggleClassOnScrollName = 'x-toggleonscroll';
 
 const
 
@@ -28,11 +28,15 @@ const
 
 /**
  * @class XToggleClassOnScrollElement
- * @element x-toggleclassonscroll
+ * @element x-toggleonscroll
  *
  * An element for quickly setting up a classname toggle when a trigger element scrolls in/out from view.
  *
  * @extends {ReactiveElement & HTMLElement}
+ *
+ * @shadowdom - None.
+ *
+ * @event 'x-toggleonscroll-intersection' {CustomEvent<{records: IntersectionObserverEntry}>} - Custom intersection event.
  */
 export class XToggleClassOnScrollElement extends ReactiveElement {
   static localName = xToggleClassOnScrollName;