@ds-gn/ui 0.9.0 → 0.10.0

package/custom-elements.json

@@ -1219,6 +1219,22 @@
               "description": "Space below the content.",
               "attribute": "padding-bottom",
               "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "motion",
+              "type": {
+                "text": "MotionType"
+              },
+              "description": "Animate the section in when it scrolls into view. Each heading block\ninside fades in its eyebrow, writes its heading letter by letter, then\nfades in its description and actions; each form block then fades in its\ninput and button together, then its note. A section already in view when\nit loads, and reduced motion, stay static.",
+              "attribute": "motion",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "_entrance",
+              "privacy": "private",
+              "default": "new SectionEntranceController( this, () => this.motion === motionValues.ON, )"
             }
           ],
           "superclass": {
@@ -1268,6 +1284,14 @@
                 "text": "SectionSpaceType | undefined"
               },
               "description": "Space below the content."
+            },
+            {
+              "name": "motion",
+              "fieldName": "motion",
+              "type": {
+                "text": "MotionType"
+              },
+              "description": "Animate the section in when it scrolls into view. Each heading block\ninside fades in its eyebrow, writes its heading letter by letter, then\nfades in its description and actions; each form block then fades in its\ninput and button together, then its note. A section already in view when\nit loads, and reduced motion, stay static."
             }
           ]
         }

package/dist/common/controllers/SectionEntranceController.d.ts

@@ -0,0 +1,37 @@
+import type { ReactiveController, ReactiveControllerHost } from 'lit';
+type EntrancePart = {
+    kind: 'fade';
+    els: HTMLElement[];
+} | {
+    kind: 'letters';
+    el: HTMLElement;
+};
+/**
+ * The entrance parts inside `root`, in document order. Each heading block
+ * contributes its eyebrow (fade), heading (letter by letter), description,
+ * then actions; each form block its input and button together, then its note.
+ */
+export declare function sectionEntranceParts(root: Element): EntrancePart[];
+/**
+ * Plays a section's entrance when it scrolls into view: the heading blocks
+ * and form blocks it contains animate in one timeline (see
+ * `sectionEntranceParts`). Decided from the first visibility report: a
+ * section already on screen, and reduced motion, stay static; one off screen
+ * holds its parts hidden (from script, so nothing is hidden when scripts do
+ * not run) and plays once when it comes into view.
+ */
+export declare class SectionEntranceController implements ReactiveController {
+    private readonly host;
+    private readonly enabled;
+    private readonly motion;
+    private observer?;
+    private state?;
+    private parts;
+    constructor(host: ReactiveControllerHost & HTMLElement, enabled: () => boolean);
+    hostUpdated(): void;
+    hostDisconnected(): void;
+    private report;
+    private play;
+    private stopObserving;
+}
+export {};

package/dist/components/Container/src/Container.d.ts

@@ -1,6 +1,7 @@
 import '../../../types/global.d.ts';
 import { type CSSResultGroup } from 'lit';
 import { Base } from '../../../common/Base/Base.js';
+import { type MotionType } from '../../../common/props/motion/motion.props.js';
 import { type ContainerPaddingType, type ContainerSizeType, type SectionSpaceType } from './Container.props.js';
 /** @slot - Constrained page content. */
 export declare class Container extends Base {
@@ -22,6 +23,15 @@ export declare class Container extends Base {
     paddingTop?: SectionSpaceType;
     /** Space below the content. */
     paddingBottom?: SectionSpaceType;
+    /**
+     * Animate the section in when it scrolls into view. Each heading block
+     * inside fades in its eyebrow, writes its heading letter by letter, then
+     * fades in its description and actions; each form block then fades in its
+     * input and button together, then its note. A section already in view when
+     * it loads, and reduced motion, stay static.
+     */
+    motion: MotionType;
+    private _entrance;
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/Container/src/Container.js

@@ -91,6 +91,146 @@ class Base extends LitElement {
 }
 defineElement("dsgn-base", Base);
 
+// common/controllers/SectionEntranceController.ts
+import {
+  prefersReducedMotion,
+  splitText
+} from "@ds-gn/motion";
+import { MotionController } from "@ds-gn/motion/lit";
+var HEADING_STAGGER = 20;
+var HEADING_MAX_SPREAD = 500;
+var HEADING_RISE = 4;
+var MOTION_OVERLAP = 160;
+var holdHidden = (el) => el.style.setProperty("opacity", "0");
+var releaseHidden = (el) => el.style.removeProperty("opacity");
+var ENTRANCE_BLOCKS = new Set(["dsgn-heading-block", "dsgn-form-block"]);
+var hasContent = (el) => !["div", "span"].includes(el.localName) || el.children.length > 0 || (el.textContent ?? "").trim() !== "";
+var childrenIn = (parent, ...slots) => Array.from(parent.children).filter((child) => child instanceof HTMLElement && slots.includes(child.slot) && hasContent(child));
+function sectionEntranceParts(root) {
+  const parts = [];
+  const fade = (els) => {
+    if (els.length > 0)
+      parts.push({ kind: "fade", els });
+  };
+  Array.from(root.querySelectorAll("*")).filter((el) => ENTRANCE_BLOCKS.has(el.localName)).forEach((block) => {
+    if (block.localName === "dsgn-form-block") {
+      fade(childrenIn(block, "input", "button"));
+      fade(childrenIn(block, "note"));
+      return;
+    }
+    fade(childrenIn(block, "eyebrow"));
+    const [heading] = childrenIn(block, "heading");
+    if (heading)
+      parts.push({ kind: "letters", el: heading });
+    fade(childrenIn(block, "description"));
+    fade(childrenIn(block, "action-primary", "action-secondary"));
+  });
+  return parts;
+}
+var elementsOf = (part) => part.kind === "fade" ? part.els : [part.el];
+
+class SectionEntranceController {
+  constructor(host, enabled) {
+    this.parts = [];
+    this.host = host;
+    this.enabled = enabled;
+    this.motion = new MotionController(host);
+    host.addController(this);
+  }
+  hostUpdated() {
+    if (this.observer || this.state !== undefined || !this.enabled())
+      return;
+    if (typeof IntersectionObserver === "undefined") {
+      this.state = "static";
+      return;
+    }
+    this.observer = new IntersectionObserver((entries) => {
+      const entry = entries[entries.length - 1];
+      if (entry)
+        this.report(entry.isIntersecting);
+    });
+    this.observer.observe(this.host);
+  }
+  hostDisconnected() {
+    this.stopObserving();
+    if (this.state === "held") {
+      this.parts.flatMap(elementsOf).forEach(releaseHidden);
+      this.state = undefined;
+    }
+  }
+  report(inView) {
+    if (this.state === undefined) {
+      const play = !inView && !prefersReducedMotion();
+      this.state = play ? "held" : "static";
+      if (!play)
+        return this.stopObserving();
+      this.parts = sectionEntranceParts(this.host);
+      this.parts.flatMap(elementsOf).forEach(holdHidden);
+    }
+    if (this.state === "held" && inView) {
+      this.state = "played";
+      this.stopObserving();
+      this.play();
+    }
+  }
+  play() {
+    this.parts.flatMap(elementsOf).forEach(releaseHidden);
+    const splits = [];
+    const steps = this.parts.map((part, index) => {
+      const overlap = index === 0 ? undefined : MOTION_OVERLAP;
+      if (part.kind === "fade") {
+        return { targets: part.els, preset: "fade", stagger: 0, overlap };
+      }
+      const split = splitText(part.el);
+      splits.push(split);
+      return {
+        targets: split.chars,
+        preset: "fade",
+        y: HEADING_RISE,
+        stagger: HEADING_STAGGER,
+        maxDuration: HEADING_MAX_SPREAD
+      };
+    });
+    if (steps.length === 0)
+      return;
+    this.motion.timeline(steps).finished.then(() => splits.forEach((split) => split.revert()));
+  }
+  stopObserving() {
+    this.observer?.disconnect();
+    this.observer = undefined;
+  }
+}
+
+// common/helpers/enum-validator.ts
+var enumValidator = (propName, enumSet, candidateValue) => {
+  if (!enumSet.has(candidateValue)) {
+    throw new Error(`Invalid prop ${propName} of value ${candidateValue}. Expected one of: ${Array.from(enumSet).join(", ")}`);
+  }
+};
+
+// common/helpers/enum-creator.ts
+var enumCreator = (acceptableValues, propName, type, other = {}) => {
+  const acceptableValuesSet = new Set(acceptableValues);
+  return {
+    type,
+    hasChanged(newValue, oldValue) {
+      if (newValue !== oldValue) {
+        enumValidator(propName, acceptableValuesSet, newValue);
+        return true;
+      }
+      return false;
+    },
+    ...other
+  };
+};
+
+// common/props/motion/motion.props.ts
+var motionValues = {
+  ON: "on",
+  OFF: "off"
+};
+var motionProps = enumCreator(Object.values(motionValues), "motion", String, { reflect: true });
+
 // components/Container/src/Container.css
 import { css as css2 } from "lit";
 var styles2 = css2`/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.com */
@@ -138,6 +278,9 @@ var styles2 = css2`/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.co
   .mx-auto {
     margin-inline: auto;
   }
+  .block {
+    display: block;
+  }
   .w-full {
     width: 100%;
   }
@@ -229,29 +372,6 @@ var styles2 = css2`/*! tailwindcss v4.3.0 | MIT License | https://tailwindcss.co
 `;
 var Container_default = styles2;
 
-// common/helpers/enum-validator.ts
-var enumValidator = (propName, enumSet, candidateValue) => {
-  if (!enumSet.has(candidateValue)) {
-    throw new Error(`Invalid prop ${propName} of value ${candidateValue}. Expected one of: ${Array.from(enumSet).join(", ")}`);
-  }
-};
-
-// common/helpers/enum-creator.ts
-var enumCreator = (acceptableValues, propName, type, other = {}) => {
-  const acceptableValuesSet = new Set(acceptableValues);
-  return {
-    type,
-    hasChanged(newValue, oldValue) {
-      if (newValue !== oldValue) {
-        enumValidator(propName, acceptableValuesSet, newValue);
-        return true;
-      }
-      return false;
-    },
-    ...other
-  };
-};
-
 // components/Container/src/Container.props.ts
 var containerSizeValues = {
   SM: "sm",
@@ -341,6 +461,8 @@ class Container extends Base {
     super(...arguments);
     this.size = containerSizeValues.LG;
     this.section = false;
+    this.motion = motionValues.OFF;
+    this._entrance = new SectionEntranceController(this, () => this.motion === motionValues.ON);
   }
   static styles = [Base.styles, Container_default];
   render() {
@@ -366,6 +488,9 @@ __legacyDecorateClassTS([
 __legacyDecorateClassTS([
   property({ ...paddingBottomProps })
 ], Container.prototype, "paddingBottom", undefined);
+__legacyDecorateClassTS([
+  property({ ...motionProps })
+], Container.prototype, "motion", undefined);
 defineElement("dsgn-container", Container);
 export {
   Container

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-gn/ui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "UI components for the DS-GN Design System",
   "type": "module",
   "exports": {