@deriv-com/dds-marketing 0.1.0 → 1.0.0

package/dist/components/core/tooltip/use-tooltip.d.ts

@@ -0,0 +1,111 @@
+import type { FocusEventHandler, PointerEventHandler } from 'react';
+import type { TooltipProps } from './Tooltip.types.js';
+export interface UseTooltipOptions {
+    /**
+     * Revealed on mount, and dismissible from there like any other. Read once, when
+     * the hook first runs — changing it later is not a way to open a tooltip, because
+     * a default that keeps applying is not a default.
+     */
+    isDefaultOpen?: boolean;
+    /**
+     * Whether the anchor answers the pointer and the keyboard at all. `false` also
+     * closes a tooltip that is already open: a description left on screen by a
+     * control that has stopped responding describes something no longer happening.
+     */
+    isEnabled?: boolean;
+    /**
+     * How long a reveal waits, in milliseconds. This is what keeps a pointer crossing
+     * the anchor on its way somewhere else from flashing a description nobody asked
+     * for, and it applies to focus for the same reason — tabbing through a row of
+     * controls passes through each one.
+     */
+    delay?: number;
+    /**
+     * How long a dismissal waits, in milliseconds. Zero is the useful default: the
+     * gap this protects against is the one between anchor and chip, and this system
+     * has no positioning layer to open one.
+     */
+    hideDelay?: number;
+    /**
+     * Which focus reveals the tooltip. `auto` is keyboard focus only, which is the
+     * one that needs it — a mouse that has just clicked the control has hover
+     * already. `always` includes focus a click caused, for an anchor that is
+     * programmatically focused and has no pointer behind it. `never` leaves the
+     * description to the pointer, and means a keyboard reaches it not at all.
+     */
+    focusTrigger?: 'auto' | 'always' | 'never';
+    /** Called with the new visibility, once per change, after any delay has elapsed. */
+    onOpenChange?: (isOpen: boolean) => void;
+}
+export interface UseTooltipResult {
+    /** Whether the chip is revealed. The inverse of what `tooltipProps.hidden` carries. */
+    isOpen: boolean;
+    /**
+     * Reveal now, ignoring `delay`. For an anchor whose trigger is neither pointer nor
+     * focus — a tooltip a validation result opens. `isEnabled: false` refuses it, for
+     * the same reason it refuses the pointer.
+     */
+    show: () => void;
+    /** Dismiss now, ignoring `hideDelay`, and drop any reveal still waiting on `delay`. */
+    hide: () => void;
+    /**
+     * Spread onto the element the tooltip describes — which has to be something focus
+     * can rest on, or the description is one no keyboard ever reaches. The
+     * `aria-describedby` is here rather than applied conditionally because a
+     * reference that exists only while the chip is visible is one assistive
+     * technology never sees.
+     */
+    anchorProps: {
+        'aria-describedby': string;
+        onPointerEnter: PointerEventHandler<HTMLElement>;
+        onPointerLeave: PointerEventHandler<HTMLElement>;
+        onFocus: FocusEventHandler<HTMLElement>;
+        onBlur: FocusEventHandler<HTMLElement>;
+    };
+    /**
+     * Spread onto `Tooltip`. Typed off the component's own generated props, so a
+     * renamed prop fails here rather than spreading an attribute nothing reads.
+     */
+    tooltipProps: Required<Pick<TooltipProps, 'id' | 'hidden'>>;
+}
+/**
+ * What every option falls back to. The values match the ones a consumer would
+ * otherwise write out every time — 200ms to reveal, nothing to dismiss.
+ *
+ * A named object rather than five literals in the destructuring below, so anything
+ * that has to *show* a default reads the same one the hook falls back to. The preview
+ * panel is the caller that forced this: a harness holding its own 200 agrees with this
+ * file right up until one of them changes, which is a copy reveal.tsx records having
+ * already made once with the state machine itself. Same reason `Tooltip.tsx` takes its
+ * own defaults from the generated `tooltipDefaults` rather than repeating them.
+ *
+ * `onOpenChange` is absent because a callback has no default worth naming — its
+ * absence is the behaviour, not a value standing in for one.
+ */
+export declare const useTooltipDefaults: {
+    readonly isDefaultOpen: false;
+    readonly isEnabled: true;
+    readonly delay: 200;
+    readonly hideDelay: 0;
+    readonly focusTrigger: "auto";
+};
+/**
+ * The reveal a tooltip does not do for itself.
+ *
+ * `Tooltip` is the chip and nothing else — it takes `hidden` and does not decide
+ * when to flip it, because a component that owned that would own a behaviour no
+ * other component could reuse. This is that behaviour, kept headless: it returns
+ * props rather than rendering anything, so the anchor stays whatever the consumer
+ * already had, and this hook never needs an opinion about what a trigger looks
+ * like.
+ *
+ * It positions nothing. Where the chip lands is still the anchor's own layout, and
+ * `placement` is still a value the consumer names rather than one measured from the
+ * anchor — the contract's `neverUseFor` says so, and this module does not retract
+ * it.
+ *
+ * Defaults live in `useTooltipDefaults` rather than in the contract because a
+ * contract carries no numbers: `api.props` is `enum | boolean | string | node`, which
+ * is the schema saying that a duration is not a design decision a variant can express.
+ */
+export declare function useTooltip({ isDefaultOpen, isEnabled, delay, hideDelay, focusTrigger, onOpenChange, }?: UseTooltipOptions): UseTooltipResult;

package/dist/components/core/tooltip/use-tooltip.js

@@ -0,0 +1,189 @@
+'use client';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+/**
+ * Whether this focus came from the keyboard, as far as the runtime will say.
+ *
+ * `:focus-visible` is the browser's own answer to the question `focusTrigger:
+ * "auto"` asks — it is what decides whether this particular focus draws a ring —
+ * so asking it is better than keeping a second opinion here in the shape of a
+ * global "was the last input a key" flag, which is what a hand-rolled version of
+ * this always becomes.
+ *
+ * A runtime that does not know the selector throws rather than answering, and the
+ * honest reading of a throw is not "this was a mouse". A description withheld is
+ * worse than one shown early, so an unanswerable question reveals the tooltip.
+ */
+function isKeyboardFocus(target) {
+    try {
+        return target.matches(':focus-visible');
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * What every option falls back to. The values match the ones a consumer would
+ * otherwise write out every time — 200ms to reveal, nothing to dismiss.
+ *
+ * A named object rather than five literals in the destructuring below, so anything
+ * that has to *show* a default reads the same one the hook falls back to. The preview
+ * panel is the caller that forced this: a harness holding its own 200 agrees with this
+ * file right up until one of them changes, which is a copy reveal.tsx records having
+ * already made once with the state machine itself. Same reason `Tooltip.tsx` takes its
+ * own defaults from the generated `tooltipDefaults` rather than repeating them.
+ *
+ * `onOpenChange` is absent because a callback has no default worth naming — its
+ * absence is the behaviour, not a value standing in for one.
+ */
+export const useTooltipDefaults = {
+    isDefaultOpen: false,
+    isEnabled: true,
+    delay: 200,
+    hideDelay: 0,
+    focusTrigger: 'auto',
+};
+/**
+ * The reveal a tooltip does not do for itself.
+ *
+ * `Tooltip` is the chip and nothing else — it takes `hidden` and does not decide
+ * when to flip it, because a component that owned that would own a behaviour no
+ * other component could reuse. This is that behaviour, kept headless: it returns
+ * props rather than rendering anything, so the anchor stays whatever the consumer
+ * already had, and this hook never needs an opinion about what a trigger looks
+ * like.
+ *
+ * It positions nothing. Where the chip lands is still the anchor's own layout, and
+ * `placement` is still a value the consumer names rather than one measured from the
+ * anchor — the contract's `neverUseFor` says so, and this module does not retract
+ * it.
+ *
+ * Defaults live in `useTooltipDefaults` rather than in the contract because a
+ * contract carries no numbers: `api.props` is `enum | boolean | string | node`, which
+ * is the schema saying that a duration is not a design decision a variant can express.
+ */
+export function useTooltip({ isDefaultOpen = useTooltipDefaults.isDefaultOpen, isEnabled = useTooltipDefaults.isEnabled, delay = useTooltipDefaults.delay, hideDelay = useTooltipDefaults.hideDelay, focusTrigger = useTooltipDefaults.focusTrigger, onOpenChange, } = {}) {
+    const id = useId();
+    // Disabled at mount means closed at mount, rather than open for one frame and
+    // then shut by the effect below.
+    const [isOpen, setIsOpen] = useState(isDefaultOpen && isEnabled);
+    // The same fact as `isOpen`, readable synchronously. Two events in one tick — a
+    // pointer leaving as focus lands — would both read a stale `isOpen` and both
+    // report a change that only happened once.
+    const open = useRef(isDefaultOpen && isEnabled);
+    // `onOpenChange` is the one option a consumer will pass as an inline arrow, so it
+    // is read through a ref: `show` and `hide` stay the same functions across renders
+    // and are safe in a consumer's own dependency list.
+    const notify = useRef(onOpenChange);
+    useEffect(() => {
+        notify.current = onOpenChange;
+    }, [onOpenChange]);
+    // One timer, because a pending reveal and a pending dismissal are never both
+    // wanted — whichever intent arrives last is the one that is true.
+    const timer = useRef(undefined);
+    const cancel = useCallback(() => {
+        if (timer.current === undefined)
+            return;
+        clearTimeout(timer.current);
+        timer.current = undefined;
+    }, []);
+    const commit = useCallback((next) => {
+        if (open.current === next)
+            return;
+        open.current = next;
+        setIsOpen(next);
+        notify.current?.(next);
+    }, []);
+    const schedule = useCallback((next, ms) => {
+        cancel();
+        // No delay means no timer. Routing zero through setTimeout would defer the
+        // change by a task, which is a different behaviour from the one asked for and
+        // one that shows up as a frame of the wrong state.
+        if (ms <= 0) {
+            commit(next);
+            return;
+        }
+        timer.current = setTimeout(() => {
+            timer.current = undefined;
+            commit(next);
+        }, ms);
+    }, [cancel, commit]);
+    const show = useCallback(() => {
+        cancel();
+        if (isEnabled)
+            commit(true);
+    }, [cancel, commit, isEnabled]);
+    const hide = useCallback(() => {
+        cancel();
+        commit(false);
+    }, [cancel, commit]);
+    useEffect(() => {
+        if (isEnabled)
+            return;
+        cancel();
+        commit(false);
+    }, [isEnabled, cancel, commit]);
+    // Escape dismisses, which is the one keyboard behaviour the WAI-ARIA tooltip
+    // pattern asks for. Listened for on the document rather than on the anchor
+    // because a tooltip the pointer revealed can be on screen while focus is
+    // somewhere else entirely, and a handler on the anchor would never hear the key.
+    //
+    // Nothing re-reveals it afterwards until the pointer leaves and returns, or focus
+    // does. That is the point: a description the user has dismissed stays dismissed
+    // while they are still pointing at the thing it describes.
+    useEffect(() => {
+        if (!isOpen)
+            return;
+        const dismiss = (event) => {
+            if (event.key !== 'Escape')
+                return;
+            cancel();
+            commit(false);
+        };
+        document.addEventListener('keydown', dismiss);
+        return () => document.removeEventListener('keydown', dismiss);
+    }, [isOpen, cancel, commit]);
+    // A timer outliving the component would commit into a hook that renders nothing.
+    useEffect(() => cancel, [cancel]);
+    const onPointerEnter = (event) => {
+        // A tap is not a hover. Touch fires this with nothing that will ever undo it —
+        // no pointerleave, and no keyboard to press Escape on — so the chip would be
+        // stuck on screen, which is worse than the contract's own position that on
+        // touch there is no hover to reveal it. A pointer that does not name itself is
+        // treated as a mouse: a runtime that cannot say is not a reason to withhold a
+        // description.
+        if (event.pointerType === 'touch')
+            return;
+        if (!isEnabled)
+            return;
+        schedule(true, delay);
+    };
+    const onPointerLeave = (event) => {
+        if (event.pointerType === 'touch')
+            return;
+        schedule(false, hideDelay);
+    };
+    const onFocus = (event) => {
+        if (!isEnabled || focusTrigger === 'never')
+            return;
+        if (focusTrigger === 'auto' && !isKeyboardFocus(event.currentTarget))
+            return;
+        schedule(true, delay);
+    };
+    const onBlur = () => {
+        // Immediately, rather than through `hideDelay`. That delay exists so a pointer
+        // can cross the gap between anchor and chip without the description vanishing;
+        // focus has no gap to cross, and focus leaving is unambiguous.
+        cancel();
+        commit(false);
+    };
+    // A fresh object each render, and deliberately not memoised: these are spread
+    // onto an element that re-renders with its parent regardless, so a dependency
+    // list here would buy nothing and be one more thing to keep true.
+    return {
+        isOpen,
+        show,
+        hide,
+        anchorProps: { 'aria-describedby': id, onPointerEnter, onPointerLeave, onFocus, onBlur },
+        tooltipProps: { id, hidden: !isOpen },
+    };
+}

package/dist/components/core/typography/Typography.css

@@ -0,0 +1,96 @@
+/* GENERATED from typography.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-typography {
+  margin: unset;
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="eyebrow"] {
+  text-transform: uppercase;
+  font-family: var(--font-eyebrow-sm-family);
+  font-size: var(--font-eyebrow-sm-size);
+  font-weight: var(--font-eyebrow-sm-weight);
+  letter-spacing: var(--font-eyebrow-sm-letter-spacing);
+  line-height: var(--font-eyebrow-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="figure"] {
+  font-variant-numeric: tabular-nums;
+  font-family: var(--font-figure-family);
+  font-size: var(--font-figure-size);
+  font-weight: var(--font-figure-weight);
+  letter-spacing: var(--font-figure-letter-spacing);
+  line-height: var(--font-figure-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="body-lg"] {
+  font-family: var(--font-body-lg-family);
+  font-size: var(--font-body-lg-size);
+  font-weight: var(--font-body-lg-weight);
+  letter-spacing: var(--font-body-lg-letter-spacing);
+  line-height: var(--font-body-lg-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="body-md"] {
+  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-typography[data-variant="body-sm"] {
+  font-family: var(--font-body-sm-family);
+  font-size: var(--font-body-sm-size);
+  font-weight: var(--font-body-sm-weight);
+  letter-spacing: var(--font-body-sm-letter-spacing);
+  line-height: var(--font-body-sm-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="h1"] {
+  font-family: var(--font-h1-family);
+  font-size: var(--font-h1-size);
+  font-weight: var(--font-h1-weight);
+  letter-spacing: var(--font-h1-letter-spacing);
+  line-height: var(--font-h1-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="h2"] {
+  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);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="h3"] {
+  font-family: var(--font-h3-family);
+  font-size: var(--font-h3-size);
+  font-weight: var(--font-h3-weight);
+  letter-spacing: var(--font-h3-letter-spacing);
+  line-height: var(--font-h3-line-height);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="h4"] {
+  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-typography[data-variant="h5"] {
+  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);
+}
+
+:where([data-dds-context="marketing"]) .dds-typography[data-variant="subtitle"] {
+  font-family: var(--font-subtitle-family);
+  font-size: var(--font-subtitle-size);
+  font-weight: var(--font-subtitle-weight);
+  letter-spacing: var(--font-subtitle-letter-spacing);
+  line-height: var(--font-subtitle-line-height);
+}
+