@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/dist/components/core/tooltip/TooltipAnchor.js

@@ -0,0 +1,69 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import './tooltip-anchor.css';
+import { cloneElement } from 'react';
+import { Tooltip } from './Tooltip.js';
+import { tooltipDefaults } from './Tooltip.types.js';
+import { useTooltip } from './use-tooltip.js';
+/**
+ * The two boxes this renders. Written here and in tooltip-anchor.css, and nowhere
+ * else — there is no generated constant for them, because they are this module's own
+ * DOM rather than parts the contract declares. A part declared in the contract has to
+ * appear in Tooltip's own markup, and keeping a positioning wrapper out of Tooltip is
+ * what this module is for.
+ */
+const parts = {
+    root: 'dds-tooltip-anchor',
+    tip: 'dds-tooltip-anchor__tip',
+};
+/**
+ * Both handlers, the trigger's own first.
+ *
+ * cloneElement replaces rather than merges, so a trigger that already listened for the
+ * pointer would silently stop doing so — the kind of loss that shows up as a bug in
+ * the consumer's own code, nowhere near here.
+ */
+function chain(theirs, ours) {
+    if (theirs === undefined)
+        return ours;
+    return (event) => {
+        theirs(event);
+        ours(event);
+    };
+}
+/**
+ * A trigger and its tooltip, placed against each other.
+ *
+ * `Tooltip` is the chip and nothing else, and `useTooltip` is when it arrives. This is
+ * the third thing neither of them does: where it lands. It is a wrapper rather than
+ * anything cleverer because the placement is pure CSS — one positioning context around
+ * both boxes, and `placement` read by a stylesheet — so there is nothing to measure,
+ * nothing to watch for resizes, and no layout pass to be one frame behind.
+ *
+ * What that buys is that the caret now lands on the point it names. What it does not
+ * buy is flipping: a chip whose named side has no room overflows rather than moving to
+ * the side that does, because knowing there is no room means measuring the viewport.
+ * The contract says as much in its own guidance, and this module does not retract it.
+ *
+ * Reach past this to `useTooltip` when the trigger is not something this can wrap —
+ * one already inside another component, or one that is not an element at all. That is
+ * the whole of what an external anchor needs: the hook's `anchorProps` go on whatever
+ * the trigger turns out to be, and `tooltipProps` on a chip rendered wherever suits.
+ */
+export function TooltipAnchor({ children, content, placement = tooltipDefaults.placement, alignment = tooltipDefaults.alignment, showCaret = tooltipDefaults.showCaret, ...options }) {
+    const { anchorProps, tooltipProps } = useTooltip(options);
+    const own = children.props;
+    const described = own['aria-describedby'];
+    const trigger = cloneElement(children, {
+        // Appended rather than replaced. A trigger that already carries a description has
+        // two of them, and a reader is meant to hear both.
+        'aria-describedby': described === undefined
+            ? anchorProps['aria-describedby']
+            : `${described} ${anchorProps['aria-describedby']}`,
+        onPointerEnter: chain(own.onPointerEnter, anchorProps.onPointerEnter),
+        onPointerLeave: chain(own.onPointerLeave, anchorProps.onPointerLeave),
+        onFocus: chain(own.onFocus, anchorProps.onFocus),
+        onBlur: chain(own.onBlur, anchorProps.onBlur),
+    });
+    return (_jsxs("span", { className: parts.root, children: [trigger, _jsx("span", { className: parts.tip, "data-placement": placement, "data-alignment": alignment, children: _jsx(Tooltip, { ...tooltipProps, placement: placement, alignment: alignment, showCaret: showCaret, children: content }) })] }));
+}

package/dist/components/core/tooltip/tooltip-anchor.css

@@ -0,0 +1,145 @@
+/*
+ * Placement for TooltipAnchor, which no contract describes.
+ *
+ * These two boxes are a behaviour module's own DOM rather than parts of the
+ * component's anatomy, and the difference is load-bearing: a part declared in the
+ * contract has to appear in Tooltip's own markup — the generated behaviour test
+ * asserts exactly that — and keeping a positioning wrapper out of Tooltip is the
+ * whole reason this module exists. So the classes are written here and in
+ * TooltipAnchor.tsx, and nowhere else.
+ *
+ * Every value is a token, read through the same custom properties the chip's own
+ * generated stylesheet reads. Nothing here is a raw dimension: `100%`, `50%`, `0`
+ * and `max-content` are the geometry of "beside the anchor", not sizes anyone would
+ * want to tune per brand.
+ */
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor {
+  /* The positioning context. Inline-block so it hugs the trigger rather than
+     whatever column the trigger sits in — otherwise a chip centred on the anchor
+     centres on the column, and lands nowhere near the thing it describes. */
+  position: relative;
+  display: inline-block;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip {
+  position: absolute;
+
+  /* Out of the flow means shrink-to-fit, and shrink-to-fit against a single inset is
+     measured from that inset to the containing block's edge — so a wide chip on a
+     narrow trigger would wrap at whatever that distance happened to be. max-content
+     puts the measure back on the text, and the chip's own max-inline-size still caps
+     it. This is the one thing the preview harness that prototyped this never hit,
+     because its trigger was always wider than its sample sentence. */
+  width: max-content;
+
+  /* Never a target. The chip already refuses the pointer, but this box is larger than
+     the chip's ink and sits over content the pointer does need. */
+  pointer-events: none;
+
+  /* How far the chip clears the anchor: the caret's own height, so that the gap and
+     the thing crossing it scale together. It stays the same with showCaret false —
+     a description touching the control it describes reads as part of it. */
+  --dds-tooltip-anchor-gap: var(--space-gap-xs);
+
+  /*
+     Above the page it floats over.
+     `position: absolute` alone leaves this at `z-index: auto`, which paints in tree
+     order among positioned elements — so any positioned sibling declared later covers
+     the chip, and a tooltip on the first of two cards loses to the second. Measured
+     before this line existed: `tipZ: auto`.
+     `layer.popup` rather than a number chosen here. The primitive ramp has carried
+     0/100/200/300/400/800/1600 all along, and the reason components reach for bare
+     integers is that no semantic role pointed at it — so this is the first consumer of
+     the role rather than the eighth hand-picked value.
+     It does not make the chip immune. A z-index only orders siblings within a stacking
+     context, so an ancestor that creates one — a transform, a filter, an opacity below
+     1, an isolation — still traps the chip inside it however high this goes. The only
+     thing that escapes that is the top layer, which means the popover API and a
+     different positioning story. Worth knowing before this is trusted absolutely. */
+  z-index: var(--layer-popup);
+}
+
+/*
+ * Which side the chip sits on, read from `placement` directly rather than through a
+ * vocabulary of its own — that prop already names where the tooltip is, which is why
+ * it names the placement and not the caret's edge. A lookup translating one name into
+ * another is a second opinion waiting to disagree with the contract.
+ *
+ * Logical insets, because `left` and `right` name the leading and trailing side rather
+ * than two points of the compass: a leading-side tooltip is on the right in Arabic, and
+ * `inset-inline-end` puts it there with nothing here to help it. The block axis is not
+ * mirrored by direction, so `top` and `bottom` mean what they say.
+ */
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='top'] {
+  inset-block-end: 100%;
+  margin-block-end: var(--dds-tooltip-anchor-gap);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='bottom'] {
+  inset-block-start: 100%;
+  margin-block-start: var(--dds-tooltip-anchor-gap);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='left'] {
+  inset-inline-end: 100%;
+  margin-inline-end: var(--dds-tooltip-anchor-gap);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='right'] {
+  inset-inline-start: 100%;
+  margin-inline-start: var(--dds-tooltip-anchor-gap);
+}
+
+/*
+ * Where along that side, which is the axis the placement did not use: the inline axis
+ * for a chip above or below, the block axis for one beside. Twelve arrangements in all,
+ * which is the number the contract's own guidance names.
+ *
+ * Centring is the one place a physical inset is correct. `left: 50%` puts the chip's
+ * left edge on the anchor's middle and the shift takes back half the chip's width, and
+ * those two cancel in either direction — a logical inset would need the shift to change
+ * sign with the direction, which is two rules to say what one says here.
+ *
+ * `start` and `end` share an edge with the anchor instead: the chip's leading edge on
+ * the anchor's leading edge, its trailing on the trailing. What they did before was hold
+ * the caret's point over the anchor's middle, which is what `center` is already for —
+ * two of the three values agreed about the caret and disagreed about the chip, and the
+ * chip wider than its anchor hung back across the layout it came from. An inset of zero
+ * is the whole rule now, and the caret lands wherever its own inset from that edge puts
+ * it: inside any anchor wider than the corner it clears.
+ */
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='top'][data-alignment='center'],
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='bottom'][data-alignment='center'] {
+  left: 50%;
+  translate: -50% 0;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='top'][data-alignment='start'],
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='bottom'][data-alignment='start'] {
+  inset-inline-start: 0;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='top'][data-alignment='end'],
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='bottom'][data-alignment='end'] {
+  inset-inline-end: 0;
+}
+
+/* The same three arrangements on the block axis, for a chip beside its anchor. The
+   harness that prototyped this placed those centred whatever the alignment said, which
+   left four of the twelve points unreachable. */
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='left'][data-alignment='center'],
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='right'][data-alignment='center'] {
+  inset-block-start: 50%;
+  translate: 0 -50%;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='left'][data-alignment='start'],
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='right'][data-alignment='start'] {
+  inset-block-start: 0;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='left'][data-alignment='end'],
+:where([data-dds-context="marketing"]) .dds-tooltip-anchor__tip[data-placement='right'][data-alignment='end'] {
+  inset-block-end: 0;
+}

package/dist/components/core/tooltip/tooltip-impl.css

@@ -0,0 +1,54 @@
+/* Implementation CSS that the contract's staticCss cannot express. */
+
+/*
+ * The caret's drawing, mirrored for right-to-left.
+ *
+ * `placement` left and right name the leading and trailing side, not two fixed
+ * points of the compass, and the chip's own `flex-direction` is already logical —
+ * `row` and `row-reverse` follow the inline direction. So the caret's *box* moves to
+ * the correct edge under RTL with nothing here to help it: a tooltip on the leading
+ * side is on the right in Arabic, and its caret lands on the left, which is the edge
+ * facing the anchor.
+ *
+ * What cannot follow is the triangle. It is one of four fixed paths in Tooltip.tsx,
+ * drawn rather than rotated because an angle is not something a contract can carry,
+ * and a path has no way to flip itself. Without this rule the box arrives on the
+ * correct edge with the point aimed away from the anchor — the one arrangement worse
+ * than having no caret at all.
+ *
+ * The inline axis only. `top` and `bottom` sit on the block axis, which right-to-left
+ * does not mirror; scaling those would take a caret that already points at its anchor
+ * and turn it around.
+ *
+ * `scale` rather than `transform`, so that a consumer's own transform on the part is
+ * not silently replaced by this one.
+ */
+:where([data-dds-context="marketing"]) .dds-tooltip:dir(rtl)[data-placement='left'] .dds-tooltip__caret,
+:where([data-dds-context="marketing"]) .dds-tooltip:dir(rtl)[data-placement='right'] .dds-tooltip__caret {
+  scale: -1 1;
+}
+
+/*
+ * The transform origin's inline half, mirrored for right-to-left.
+ *
+ * The chip scales up out of the edge nearest its anchor, and the contract names that
+ * edge per placement — `left` places the chip on the leading side, so the edge facing
+ * the anchor is its `right`. That holds in English and inverts in Arabic: the leading
+ * side is the right, the chip sits there, and the edge facing the anchor is its `left`.
+ *
+ * `transform-origin` has no logical keyword to say this with. It takes `left` and
+ * `right`, never `inline-start` — so unlike `flex-direction` and the logical insets in
+ * tooltip-anchor.css, the generated rule cannot follow the direction on its own, and
+ * this is the same gap the caret's path above falls into.
+ *
+ * The inline axis only, for the same reason: `top` and `bottom` sit on the block axis,
+ * which right-to-left does not mirror. Without this the chip grows out of the edge
+ * facing away from its anchor, which reads as retreating from the control it describes.
+ */
+:where([data-dds-context="marketing"]) .dds-tooltip:dir(rtl)[data-placement='left'] {
+  transform-origin: left;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip:dir(rtl)[data-placement='right'] {
+  transform-origin: right;
+}

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-family);
+  font-size: var(--font-eyebrow-size);
+  font-weight: var(--font-eyebrow-weight);
+  letter-spacing: var(--font-eyebrow-letter-spacing);
+  line-height: var(--font-eyebrow-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);
+}
+