@deriv-com/dds-marketing 1.0.2 → 1.1.0

package/dist/components/blocks/stats/use-wheel.js

@@ -0,0 +1,126 @@
+'use client';
+import { useEffect, useState } from 'react';
+import { milliseconds } from '../../css-time.js';
+/**
+ * The width the figures stop turning at and lay out as a grid: the package's fold, in rem. A
+ * number here rather than a token read, because the stylesheet's container query states the same
+ * width longhand — `var()` is not permitted in one — and the two have to agree.
+ */
+const FOLD_REM = 48;
+/**
+ * A figure's place on the wheel at a given turn: the one in place, the one it replaced above it, the
+ * one coming in below it, and every other figure out of sight.
+ *
+ * With two figures there is no "above" — the one that leaves comes straight back in below — and with
+ * three the one above goes straight to below, which the stylesheet draws as an arrival from below
+ * rather than as a figure crossing the wheel.
+ */
+export function slotOf(at, turn, count) {
+    const place = (((at - turn) % count) + count) % count;
+    if (place === 0)
+        return 'active';
+    if (place === 1)
+        return 'below';
+    if (place === count - 1)
+        return 'above';
+    return 'hidden';
+}
+/**
+ * The phone's wheel of figures — the reference site's mobile stats: one figure in place, the one
+ * before it smaller above and the next smaller below, turning on to the next every
+ * motion.duration.hold plus motion.duration.turn.
+ *
+ * It turns only where every condition for it holds, and otherwise hands back `wheeling: false` and
+ * the figures are the grid they are from the fold:
+ * - the section is narrower than the fold, read off the section itself — a container, not the
+ *   viewport, as the stylesheet reads it;
+ * - there are two figures or more;
+ * - the reader has not asked for less motion — the grid is the still version of the same set;
+ * - the section is on screen. A wheel nobody can see does not turn, and starts again where it was;
+ * - nothing holds or has stopped it — see `hold`.
+ */
+export function useWheel(section, count) {
+    const [narrow, setNarrow] = useState(false);
+    const [seen, setSeen] = useState(false);
+    const [turn, setTurn] = useState(0);
+    const [still, setStill] = useState(false);
+    /*
+      A pointer over the wheel or focus on it holds it for as long as it lasts; a press anywhere on
+      it stops it for good — CtaBannerSlider's rule, by way of the WAI carousel pattern: a reader who
+      has touched the thing is reading it. Together they are the way to stop a wheel that would
+      otherwise turn for as long as it is on screen, which WCAG 2.2.2 asks of anything that moves on
+      its own for more than five seconds: the keyboard's way is the wheel's own tab stop, the
+      pointer's is resting on it, and a touch screen's is a tap.
+    */
+    const [held, setHeld] = useState(false);
+    const [stopped, setStopped] = useState(false);
+    const wheeling = narrow && count > 1 && !still;
+    // Asked live rather than once: a reader who turns on reduced motion mid-visit stops the wheel then.
+    useEffect(() => {
+        if (typeof window.matchMedia !== 'function')
+            return undefined;
+        const query = window.matchMedia('(prefers-reduced-motion: reduce)');
+        const follow = () => setStill(query.matches);
+        follow();
+        query.addEventListener?.('change', follow);
+        return () => query.removeEventListener?.('change', follow);
+    }, []);
+    useEffect(() => {
+        const element = section.current;
+        if (element === null || typeof ResizeObserver === 'undefined')
+            return undefined;
+        const measure = () => {
+            const rem = Number.parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+            // The layout width, not the drawn one: getBoundingClientRect reports the box after
+            // transforms, so a section shown scaled down — a thumbnail of the page, a zoomed preview —
+            // measured as a phone and turned into the wheel at desktop width. offsetWidth is the width
+            // the section is laid out at, the same one its container queries read.
+            setNarrow(element.offsetWidth < FOLD_REM * rem);
+        };
+        measure();
+        const observer = new ResizeObserver(measure);
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [section]);
+    useEffect(() => {
+        const element = section.current;
+        if (element === null || typeof IntersectionObserver === 'undefined')
+            return undefined;
+        const observer = new IntersectionObserver(([entry]) => setSeen(entry?.isIntersecting ?? false));
+        observer.observe(element);
+        return () => observer.disconnect();
+    }, [section]);
+    useEffect(() => {
+        const element = section.current;
+        if (!wheeling || !seen || held || stopped || element === null)
+            return undefined;
+        const style = getComputedStyle(element);
+        const every = (milliseconds(style.getPropertyValue('--motion-duration-hold')) ?? 0) +
+            (milliseconds(style.getPropertyValue('--motion-duration-turn')) ?? 0);
+        if (every <= 0)
+            return undefined;
+        const timer = window.setInterval(() => setTurn((at) => at + 1), every);
+        return () => window.clearInterval(timer);
+    }, [section, wheeling, seen, held, stopped]);
+    /** Spread on the wheel's list: what holds it, and what stops it. */
+    const hold = {
+        onPointerEnter: (event) => {
+            if (event.pointerType === 'mouse')
+                setHeld(true);
+        },
+        onPointerLeave: (event) => {
+            if (event.pointerType === 'mouse')
+                setHeld(false);
+        },
+        onFocus: () => setHeld(true),
+        onBlur: (event) => {
+            if (!event.currentTarget.contains(event.relatedTarget))
+                setHeld(false);
+        },
+        onPointerDownCapture: (event) => {
+            if (event.isPrimary && (event.pointerType !== 'mouse' || event.button === 0))
+                setStopped(true);
+        },
+    };
+    return { wheeling, turn, hold };
+}

package/dist/components/blocks/steps/Steps.css

@@ -0,0 +1,202 @@
+/* GENERATED from steps.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-steps {
+  box-sizing: border-box;
+  container-type: inline-size;
+  display: flex;
+  inline-size: 100%;
+  justify-content: center;
+  overflow-wrap: anywhere;
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__inner {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  inline-size: 100%;
+  min-inline-size: 0;
+  max-inline-size: var(--size-content-max);
+  padding-block: var(--space-section-default);
+  padding-inline: var(--space-inset-page);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__split {
+  align-items: stretch;
+  display: flex;
+  min-inline-size: 0;
+  column-gap: var(--space-gap-3xl);
+  row-gap: var(--space-gap-2xl);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__media {
+  min-inline-size: 0;
+  overflow: hidden;
+  position: relative;
+  aspect-ratio: var(--aspect-square);
+  border-radius: var(--radius-container);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__image {
+  display: block;
+  transition-duration: var(--motion-duration-shift);
+  transition-timing-function: var(--motion-easing-standard);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__content {
+  display: flex;
+  flex-direction: column;
+  min-inline-size: 0;
+  row-gap: var(--space-gap-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__title {
+  margin-block: 0;
+  text-wrap: balance;
+  font-family: var(--font-h2-family);
+  font-size: var(--font-h2-size);
+  font-weight: var(--font-h2-weight);
+  letter-spacing: var(--font-h2-letter-spacing);
+  line-height: var(--font-h2-line-height);
+  margin-block-end: var(--space-heading-content);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__list {
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin-block: 0;
+  padding-inline-start: 0;
+  row-gap: var(--space-gap-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__step {
+  align-items: flex-start;
+  border-block-start-style: solid;
+  box-sizing: border-box;
+  display: flex;
+  position: relative;
+  border-width: var(--border-width-default);
+  column-gap: var(--space-gap-md);
+  padding-block: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__number {
+  flex: none;
+  font-variant-numeric: tabular-nums;
+  font-family: var(--font-h4-family);
+  font-size: var(--font-h4-size);
+  font-weight: var(--font-h4-weight);
+  letter-spacing: var(--font-h4-letter-spacing);
+  line-height: var(--font-h4-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__body {
+  display: flex;
+  flex-direction: column;
+  min-inline-size: 0;
+  row-gap: var(--space-heading-title-description-compact);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__step-title {
+  margin-block: 0;
+  font-family: var(--font-h5-family);
+  font-size: var(--font-h5-size);
+  font-weight: var(--font-h5-weight);
+  letter-spacing: var(--font-h5-letter-spacing);
+  line-height: var(--font-h5-line-height);
+  min-block-size: var(--size-target-min);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__trigger {
+  transition-property: outline-color, outline-width;
+  appearance: none;
+  background: none;
+  border-style: none;
+  color: inherit;
+  cursor: pointer;
+  font: inherit;
+  letter-spacing: inherit;
+  outline-style: solid;
+  padding: 0;
+  text-align: start;
+  border-radius: var(--radius-subtle);
+  min-block-size: var(--size-target-min);
+  min-inline-size: var(--size-target-min);
+  outline-width: var(--border-width-none);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__step-description {
+  margin-block: 0;
+  font-family: var(--font-body-md-family);
+  font-size: var(--font-body-md-size);
+  font-weight: var(--font-body-md-weight);
+  letter-spacing: var(--font-body-md-letter-spacing);
+  line-height: var(--font-body-md-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__progress {
+  display: none;
+  pointer-events: none;
+  position: absolute;
+  background-color: var(--color-bg-brand);
+  block-size: var(--border-width-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-media-position="end"] .dds-steps__split {
+  flex-direction: row-reverse;
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-media-position="start"] .dds-steps__split {
+  flex-direction: row;
+}
+
+:where([data-dds-context="marketing"]) .dds-steps .dds-steps__trigger:focus-visible {
+  outline-color: var(--color-border-focus);
+  outline-width: var(--border-width-focus);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="page"] {
+  background-color: var(--color-bg-page);
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="page"] .dds-steps__number {
+  color: var(--color-fg-brand-accent);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="page"] .dds-steps__step {
+  border-color: var(--color-border-subtle);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="strong"] {
+  background-color: var(--color-bg-brand-strong);
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="strong"] .dds-steps__number {
+  color: var(--color-fg-on-brand-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="strong"] .dds-steps__step {
+  border-color: var(--color-border-subtle-inverse);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="subtle"] {
+  background-color: var(--color-bg-page);
+  background-image: linear-gradient(var(--color-bg-band-subtle), var(--color-bg-band-subtle));
+  color: var(--color-fg-default);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="subtle"] .dds-steps__number {
+  color: var(--color-fg-brand);
+}
+
+:where([data-dds-context="marketing"]) .dds-steps[data-ground="subtle"] .dds-steps__step {
+  border-color: var(--color-border-subtle);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-steps,
+  :where([data-dds-context="marketing"]) .dds-steps * { transition: none !important; }
+}
+

package/dist/components/blocks/steps/Steps.d.ts

@@ -0,0 +1,32 @@
+import './Steps.css';
+import './steps-impl.css';
+import '../block-reveal.css';
+import { type StepsProps } from './Steps.types.js';
+export type { StepsProps };
+/**
+ * A how-it-works section: one picture beside a numbered list of the steps a reader takes.
+ *
+ * The numbers are the argument. They say the order matters and how far there is to go, which is
+ * what separates this from FeatureBullets — the same split, where every line is included rather
+ * than one coming after another. So the list is an `<ol>`, and a screen reader announces the count
+ * and each step's place without being told; the large number drawn beside each step is the
+ * section's own decoration, hidden from assistive technology so the place is not read twice.
+ *
+ * The steps are records rather than children, because the number in front of each is drawn from
+ * its place in the list and a page composing its own would be a page retyping the order.
+ *
+ * The picture comes first in the markup and on a phone, which is the reference design's order and
+ * the one a sequence reads in: the picture sets the scene the steps then walk through. At full
+ * width `mediaPosition` puts it on either side.
+ *
+ * The reference template also carried `embedded`, which dropped the section for a plain `<div>`
+ * inside an article's body, and `titleId`, which let a table of contents target the heading. Both
+ * are gone: this package has no article layout to embed into, and a section here is named by its
+ * own heading through `aria-labelledby` — a `<section>` is only a region landmark once it has one.
+ *
+ * With `autoplay` the steps take their turn: one is current, its rule fills, and the next takes
+ * over — see `useTurn`. Each title becomes a button that makes its step current, and where every
+ * step carries a picture the one beside the list is the current step's. The list is still the
+ * ordered list it always is; only which step is drawn as current moves.
+ */
+export declare function Steps({ ground, mediaPosition, autoplay, title, steps, media, }: StepsProps): import("react").JSX.Element;

package/dist/components/blocks/steps/Steps.js

@@ -0,0 +1,65 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import './Steps.css';
+import './steps-impl.css';
+import '../block-reveal.css';
+import { arriving, useReveal } from '../use-reveal.js';
+import { given } from '../../given.js';
+import { useTurn } from './use-turn.js';
+import { stepsDefaults, stepsParts } from './Steps.types.js';
+/**
+ * A how-it-works section: one picture beside a numbered list of the steps a reader takes.
+ *
+ * The numbers are the argument. They say the order matters and how far there is to go, which is
+ * what separates this from FeatureBullets — the same split, where every line is included rather
+ * than one coming after another. So the list is an `<ol>`, and a screen reader announces the count
+ * and each step's place without being told; the large number drawn beside each step is the
+ * section's own decoration, hidden from assistive technology so the place is not read twice.
+ *
+ * The steps are records rather than children, because the number in front of each is drawn from
+ * its place in the list and a page composing its own would be a page retyping the order.
+ *
+ * The picture comes first in the markup and on a phone, which is the reference design's order and
+ * the one a sequence reads in: the picture sets the scene the steps then walk through. At full
+ * width `mediaPosition` puts it on either side.
+ *
+ * The reference template also carried `embedded`, which dropped the section for a plain `<div>`
+ * inside an article's body, and `titleId`, which let a table of contents target the heading. Both
+ * are gone: this package has no article layout to embed into, and a section here is named by its
+ * own heading through `aria-labelledby` — a `<section>` is only a region landmark once it has one.
+ *
+ * With `autoplay` the steps take their turn: one is current, its rule fills, and the next takes
+ * over — see `useTurn`. Each title becomes a button that makes its step current, and where every
+ * step carries a picture the one beside the list is the current step's. The list is still the
+ * ordered list it always is; only which step is drawn as current moves.
+ */
+export function Steps({ ground = stepsDefaults.ground, mediaPosition = stepsDefaults.mediaPosition, autoplay = stepsDefaults.autoplay, title, steps, media, }) {
+    const titleId = useId();
+    const [band, revealed] = useReveal();
+    // A step with no name is somebody mid-sentence, not a step. The workbench's own control emits
+    // records as they are typed, and a number against nothing is a step the page did not write — so
+    // it is dropped before the count is taken, and the numbers close up rather than skipping one.
+    const shown = steps.filter((step) => given(step.title));
+    const { current, turning, playing, next, choose, section, hold } = useTurn(shown.length, autoplay);
+    // The steps' own pictures replace the one picture only where every step has one: a turn that
+    // reached a step without a picture would show nothing beside it.
+    const pictured = shown.length > 0 && shown.every((step) => given(step.image?.src));
+    return (_jsx("section", { className: stepsParts.root, ref: section, "data-ground": ground, "data-media-position": mediaPosition, "data-autoplay": autoplay || undefined, "aria-labelledby": titleId, ...(autoplay ? hold : {}), children: _jsx("div", { className: stepsParts.inner, ref: band, "data-revealed": revealed, children: _jsxs("div", { className: stepsParts.split, children: [_jsx("div", { className: stepsParts.media, ...arriving(0), "aria-hidden": "true", children: pictured
+                            ? shown.map((step, at) => (_jsx("img", { className: stepsParts.image, src: step.image?.src, alt: "", width: step.image?.width, height: step.image?.height, "data-current": at === current, loading: at === 0 ? undefined : 'lazy' }, `${at}:${step.title}`)))
+                            : media }), _jsxs("div", { className: stepsParts.content, children: [_jsx("h2", { className: stepsParts.title, ...arriving(0), id: titleId, children: title }), _jsx("ol", { className: stepsParts.list, role: "list", "data-turning": autoplay ? turning : undefined, "data-playing": autoplay ? playing : undefined, children: shown.map((step, at) => (
+                                /* Keyed by the step's own name. An index would key the list by position, so
+                                   removing a step would renumber every row under it and React would reconcile
+                                   the wrong ones; two steps with one name are one step written twice.
+              
+                                   The position is still what decides the number and when a row arrives — the
+                                   steps come up in the order they are taken, behind the title and the picture. */
+                                _jsxs("li", { className: stepsParts.step, "data-current": autoplay ? at === current : undefined, ...arriving(2 + at), children: [_jsx("span", { className: stepsParts.number, "aria-hidden": "true", children: at + 1 }), _jsxs("div", { className: stepsParts.body, children: [_jsx("h3", { className: stepsParts['step-title'], children: autoplay ? (_jsx("button", { type: "button", className: stepsParts.trigger, "aria-current": at === current ? 'step' : undefined, onClick: () => choose(at), children: step.title })) : (step.title) }), _jsx("p", { className: stepsParts['step-description'], children: step.description })] }), _jsx("span", { className: stepsParts.progress, "aria-hidden": "true", ref: at === current && playing
+                                                ? (element) => {
+                                                    if (!element)
+                                                        return;
+                                                    element.addEventListener('animationend', next);
+                                                    return () => element.removeEventListener('animationend', next);
+                                                }
+                                                : undefined })] }, `${at}:${step.title}`))) })] })] }) }) }));
+}

package/dist/components/blocks/steps/Steps.types.d.ts

@@ -0,0 +1,48 @@
+import type { ReactNode } from 'react';
+import type { StepsItem } from '../../steps-data.js';
+export interface StepsOwnProps {
+    /**
+     * `page` — The default, and the page's own white. A section that has nothing to separate itself from what is above it — most of them
+     * `subtle` — A quiet step off the page, for a band that wants to read as its own section without changing the page's voice. The reference design paints this section grey, and a page following it closely takes this. Painted as the band's tint laid over the page's own ground, so it is the same grey whatever is behind the section.
+     * `strong` — `color.bg.brand-strong`, the dark band. It stops the page rather than dividing it, so it is for a section a reader should arrive at — and one per page is usually one more than enough
+     */
+    ground?: 'page' | 'subtle' | 'strong';
+    /**
+     * `start` — The default, and the reference design's: the picture first, then the steps it introduces
+     * `end` — The steps first, for a section sitting under a split whose picture is already at the start
+     */
+    mediaPosition?: 'start' | 'end';
+    /** Whether the steps take their turn on their own: one step is current, its rule fills over motion.duration.dwell, then the next takes over, and back to the first after the last. The current step's number is drawn at full strength and the rest recede; with an `image` on each step the picture changes to the current one's. Each step's title becomes a button that makes it current. Off by default, so a list nobody configured stays still. On, it holds while the pointer is over the section or focus is inside it, waits until the section is on screen, never moves for a reader who asked for less motion, and stops for good once the reader presses a step — the WAI carousel rule CtaBannerSlider follows: a reader who has chosen a step is reading it. That gives a reader a way to stop it, which WCAG 2.2.2 asks for, but not a visible one, so a page that needs 2.2.2 met plainly should leave it off. */
+    autoplay?: boolean;
+    /** Always. What the steps get a reader to, in the fewest words that say it — 'Get started in 3 steps' */
+    title: string;
+    /** Always. The steps, in the order a reader takes them — three or four is right, six the most. Each is a short imperative and a sentence under about two hundred characters. The number in front of each is drawn from its place in the list, so reordering the list renumbers it. Give each step an `image` — a screenshot of that step — and the picture beside the list is the current step's: the first while the list is still, and each in turn under `autoplay`. */
+    steps: StepsItem[];
+    /** The one picture beside the steps, where they have no pictures of their own — a screenshot, a photograph. The section is a split and the picture is one half of it: give this or an `image` on each step, because without either the list runs to a measure it was never sized for. Steps that carry their own pictures win over this. */
+    media?: ReactNode;
+}
+export type StepsProps = StepsOwnProps;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const stepsParts: {
+    readonly root: "dds-steps";
+    readonly inner: "dds-steps__inner";
+    readonly split: "dds-steps__split";
+    readonly media: "dds-steps__media";
+    readonly image: "dds-steps__image";
+    readonly content: "dds-steps__content";
+    readonly title: "dds-steps__title";
+    readonly list: "dds-steps__list";
+    readonly step: "dds-steps__step";
+    readonly number: "dds-steps__number";
+    readonly body: "dds-steps__body";
+    readonly 'step-title': "dds-steps__step-title";
+    readonly trigger: "dds-steps__trigger";
+    readonly 'step-description': "dds-steps__step-description";
+    readonly progress: "dds-steps__progress";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const stepsDefaults: {
+    readonly ground: "page";
+    readonly mediaPosition: "start";
+    readonly autoplay: false;
+};

package/dist/components/blocks/steps/Steps.types.js

@@ -0,0 +1,21 @@
+// GENERATED from steps.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const stepsParts = {
+    root: 'dds-steps',
+    inner: 'dds-steps__inner',
+    split: 'dds-steps__split',
+    media: 'dds-steps__media',
+    image: 'dds-steps__image',
+    content: 'dds-steps__content',
+    title: 'dds-steps__title',
+    list: 'dds-steps__list',
+    step: 'dds-steps__step',
+    number: 'dds-steps__number',
+    body: 'dds-steps__body',
+    'step-title': 'dds-steps__step-title',
+    trigger: 'dds-steps__trigger',
+    'step-description': 'dds-steps__step-description',
+    progress: 'dds-steps__progress',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const stepsDefaults = { ground: 'page', mediaPosition: 'start', autoplay: false };