@deriv-com/dds-marketing 0.1.0 → 0.2.0

package/dist/components/core/text-input/TextInput.js

@@ -0,0 +1,130 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from 'react';
+import { CircleCheckSolidIcon, CircleExclamationSolidIcon, CircleInfoRegularIcon, CircleXmarkSolidIcon, TriangleExclamationSolidIcon, } from '@deriv-com/quill-icons-web';
+import './TextInput.css';
+import './text-input-impl.css';
+import { Icon } from '../icon/Icon.js';
+import { TooltipAnchor } from '../tooltip/TooltipAnchor.js';
+import { given } from '../../given.js';
+import { textInputDefaults, textInputGlyphStep, textInputParts } from './TextInput.types.js';
+/**
+ * What each reported status looks like.
+ *
+ * Circle for error, triangle for warning: the two colours are close enough that a
+ * red-green deficiency can converge them, so the shape is what separates the pair at a
+ * glance and neither should be varied to match the other.
+ *
+ * No entry for `pending`. Product turns a Spinner there and marketing has none to turn —
+ * see the note at `reporting` below for what that costs.
+ */
+const statusGlyph = {
+    error: _jsx(CircleExclamationSolidIcon, {}),
+    warning: _jsx(TriangleExclamationSolidIcon, {}),
+    success: _jsx(CircleCheckSolidIcon, {}),
+};
+/**
+ * The step a mark inside the field takes, against the value's own type rather than the
+ * page's. `textInputGlyphStep` is the contract's, for the ornaments a consumer supplies;
+ * this is for the two marks the component draws itself, which track the text beside them.
+ */
+const fieldGlyphStep = { sm: 'xs', md: 'xs', lg: 'sm' };
+export function TextInput({ size = textInputDefaults.size, status = textInputDefaults.status, type = textInputDefaults.type, label, labelTooltip, placeholder, helperText, statusMessage, leadingIcon, prefix, suffix, trailingIcon, clearable = textInputDefaults.clearable, clearLabel, required = textInputDefaults.required, requiredMark = textInputDefaults.requiredMark, optional = textInputDefaults.optional, ...rest }) {
+    /**
+     * One id for the field, and one for whichever line is describing it.
+     *
+     * `useId` rather than a prop, because a marketing page renders the same form in a hero
+     * and again in the footer, and two fields sharing a `for` means clicking the second
+     * label focuses the first.
+     */
+    const base = useId();
+    const fieldId = `${base}-field`;
+    /**
+     * Whether there is anything to clear.
+     *
+     * Observed rather than owned. A consumer controlling the field passes `value`, so that is
+     * read directly; one that does not keeps the value in the DOM, so the element is watched
+     * for its own input events. Either way this component never sets it — a clear button that
+     * appears on an empty field is a button that does nothing.
+     *
+     * The ref is on the box rather than the input, because in React 19 `ref` is an ordinary
+     * prop and `rest` would overwrite one placed on the input the moment a consumer passed
+     * their own.
+     */
+    const controlRef = useRef(null);
+    const [typed, setTyped] = useState(false);
+    const controlled = 'value' in rest;
+    const held = controlled ? String(rest.value ?? '') : '';
+    useEffect(() => {
+        if (controlled)
+            return undefined;
+        const field = controlRef.current?.querySelector('input');
+        if (field === null || field === undefined)
+            return undefined;
+        const sync = () => setTyped(field.value !== '');
+        sync();
+        field.addEventListener('input', sync);
+        return () => field.removeEventListener('input', sync);
+    }, [controlled]);
+    const hasValue = controlled ? held !== '' : typed;
+    /**
+     * Whether the value is the reader's to change.
+     *
+     * Read out of `rest` rather than declared as props, because both arrive through
+     * InputHTMLAttributes and belong to the element — declaring them here would give the
+     * field two sources for one attribute.
+     *
+     * The clear button goes when this is false, which the contract states as the `clear`
+     * part's `absentWhen`. Dimming it was not enough: the button sits inside the control, so
+     * the disabled state's opacity made it look unavailable while it stayed a live button
+     * that emptied the field.
+     */
+    const editable = rest.disabled !== true && rest.readOnly !== true;
+    /**
+     * The message replaces the helper rather than joining it.
+     *
+     * Both at once is two lines of small text under a field the reader is trying to fix, and
+     * the one that matters is the one they did not expect. So only one is ever rendered, and
+     * `aria-describedby` points at whichever it is.
+     *
+     * Gated on the status rather than on the message existing: a form library may hold a
+     * message for a field that is not currently reporting anything, and rendering it then
+     * shows a verdict to people reading the form while nothing is announced to people
+     * hearing it.
+     *
+     * `pending` is the one status with nothing of its own to show. Product turns a Spinner
+     * beside the message, or in the field when there is no message to sit beside; marketing
+     * has no Spinner, so a pending check reaches the eye only through the words in its
+     * message, and reaches a screen reader through `aria-busy` either way. A pending status
+     * with no message is currently invisible — the gap closes when marketing has a Spinner.
+     */
+    const reporting = status !== 'none';
+    const showsMessage = reporting && given(statusMessage);
+    const showsHelper = given(helperText) && !reporting;
+    const described = showsMessage ? 'message' : showsHelper ? 'helper' : undefined;
+    const mark = status === 'error' || status === 'warning' || status === 'success';
+    return (_jsxs("div", { className: textInputParts.root, "data-size": size, "data-status": status, children: [_jsxs("div", { className: textInputParts['label-row'], children: [_jsxs("label", { className: textInputParts.label, htmlFor: fieldId, children: [label, required ? (_jsx("span", { className: textInputParts['required-mark'], "aria-hidden": "true", children: requiredMark === 'asterisk' ? '*' : 'required' })) : null, optional ? _jsx("span", { className: textInputParts['optional-mark'], children: "optional" }) : null] }), given(labelTooltip) ? (_jsx(TooltipAnchor, { content: labelTooltip, placement: "top", children: _jsx("button", { type: "button", className: textInputParts['label-tooltip'], "aria-label": `About ${label}`, children: _jsx(Icon, { size: fieldGlyphStep[size], children: _jsx(CircleInfoRegularIcon, {}) }) }) })) : null] }), _jsxs("div", { ref: controlRef, className: textInputParts.control, 
+                // The inset belongs to the box, so an affix sits inside it — which leaves a strip
+                // of the box that is not the input, and clicking it would do nothing where a
+                // native input's own padding puts the caret in. Only when the box itself was hit:
+                // anything inside it has its own business.
+                onMouseDown: (event) => {
+                    if (event.target === event.currentTarget) {
+                        event.currentTarget.querySelector('input')?.focus();
+                    }
+                }, children: [leadingIcon === undefined || leadingIcon === null ? null : (_jsx("span", { className: textInputParts['leading-icon'], children: _jsx(Icon, { size: textInputGlyphStep[size], children: leadingIcon }) })), given(prefix) ? _jsx("span", { className: textInputParts.prefix, children: prefix }) : null, _jsx("input", { ...rest, id: fieldId, className: textInputParts.field, type: type, placeholder: placeholder, "aria-invalid": status === 'error' || undefined, "aria-required": required || undefined, "aria-busy": status === 'pending' || undefined, "aria-describedby": described === undefined ? undefined : `${base}-${described}` }), given(suffix) ? _jsx("span", { className: textInputParts.suffix, children: suffix }) : null, clearable && hasValue && editable ? (_jsx("button", { type: "button", className: textInputParts.clear, "aria-label": clearLabel, 
+                        // Emptying a field is a change to its value, so it is reported the way every
+                        // other change is — through onChange, which arrives from api.extends. The
+                        // component owns no value and cannot clear one: it sets the element's value
+                        // through the prototype's own setter and dispatches the event React listens
+                        // for, which is what makes a controlled consumer see it as their own change.
+                        onClick: (event) => {
+                            const field = event.currentTarget.parentElement?.querySelector('input');
+                            if (field === null || field === undefined)
+                                return;
+                            const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value')?.set;
+                            setter?.call(field, '');
+                            field.dispatchEvent(new Event('input', { bubbles: true }));
+                            field.focus();
+                        }, children: _jsx(Icon, { size: fieldGlyphStep[size], children: _jsx(CircleXmarkSolidIcon, {}) }) })) : null, trailingIcon === undefined || trailingIcon === null ? null : (_jsx("span", { className: textInputParts['trailing-icon'], children: _jsx(Icon, { size: textInputGlyphStep[size], children: trailingIcon }) }))] }), showsMessage ? (_jsxs("span", { id: `${base}-message`, className: textInputParts.message, children: [mark ? (_jsx("span", { className: textInputParts['message-icon'], children: _jsx(Icon, { size: "xs", children: statusGlyph[status] }) })) : null, statusMessage] })) : null, showsHelper ? (_jsx("span", { id: `${base}-helper`, className: textInputParts.helper, children: helperText })) : null] }));
+}

package/dist/components/core/text-input/TextInput.types.d.ts

@@ -0,0 +1,96 @@
+import type { InputHTMLAttributes, ReactNode } from 'react';
+export interface TextInputOwnProps {
+    /**
+     * `sm` — A field in a dense desktop arrangement — a filter row above a list, a field beside body copy rather than heading a section. Not on a phone, where thirty-two is below what a finger reliably hits
+     * `md` — The default, and nearly every form on a page — an inline signup, a contact form in a section
+     * `lg` — A hero's single field, or a conversion band where the form is the reason the section exists and has to be found from a distance
+     */
+    size?: 'sm' | 'md' | 'lg';
+    /**
+     * `text` — A name, a company, anything with no keypad or validation of its own
+     * `email` — An address. It brings the right keypad on a phone — the @ without a modifier — which is the difference between a typo and a lost signup
+     * `tel` — A phone number, for the numeric keypad. It does no validation and should not pretend to: numbers differ by country and a field that rejects a valid one is worse than a field that accepts anything
+     * `url` — A website, on a form that asks for one
+     */
+    type?: 'text' | 'email' | 'tel' | 'url';
+    /** Always — it names the field, it is drawn, and clicking it focuses the input. One or two words: 'Email', 'Full name', 'Work email' */
+    label: string;
+    /** A field needs a sentence the label has no room for — why the address is being asked for, what happens to it */
+    labelTooltip?: string;
+    /** Showing the shape of the value where the shape is not obvious — 'name@example.com' on an email field. It is an example, and it is allowed to be skipped */
+    placeholder?: string;
+    /** Saying what happens to the value — what the page will send, how often, what it will not do with the address. On a marketing form this is frequently what decides whether the reader types a real one */
+    helperText?: string;
+    /** A mark that says what the field takes at a glance — an envelope on an address, a globe on a site */
+    leadingIcon?: ReactNode;
+    /** A fixed part of the value the reader should not have to type — a currency mark, https:// */
+    prefix?: string;
+    /** A fixed tail — a unit, a domain every address on this form shares */
+    suffix?: string;
+    /** A mark at the far edge that comments on the value rather than introducing it */
+    trailingIcon?: ReactNode;
+    /**
+     * `numeric` — Digits and nothing else — a postcode, a reference number
+     * `decimal` — A number that may carry a separator — an amount
+     */
+    inputMode?: 'numeric' | 'decimal';
+    /**
+     * `text` — The default. The word 'required' says what it means in the reader's own language and needs no key
+     * `asterisk` — A dense form where the word would repeat down the column, and a legend explains the mark once
+     */
+    requiredMark?: 'text' | 'asterisk';
+}
+export type TextInputProps = TextInputOwnProps & Omit<InputHTMLAttributes<HTMLInputElement>, 'className' | 'size' | 'status' | 'type' | 'label' | 'labelTooltip' | 'placeholder' | 'helperText' | 'leadingIcon' | 'prefix' | 'suffix' | 'trailingIcon' | 'clearable' | 'clearLabel' | 'inputMode' | 'statusMessage' | 'required' | 'requiredMark' | 'optional'> & ({
+    status?: 'none' | 'error' | 'warning' | 'success' | 'pending';
+    statusMessage: string;
+} | {
+    status?: Exclude<'none' | 'error' | 'warning' | 'success' | 'pending', 'error' | 'warning'>;
+    statusMessage?: string;
+}) & ({
+    required?: boolean;
+    optional?: false;
+} | {
+    required?: false;
+    optional?: boolean;
+}) & ({
+    clearable?: boolean;
+    clearLabel: string;
+} | {
+    clearable?: false;
+    clearLabel?: string;
+});
+/** The class each part carries. Apply these — do not retype them. */
+export declare const textInputParts: {
+    readonly root: "dds-textinput";
+    readonly 'label-row': "dds-textinput__label-row";
+    readonly label: "dds-textinput__label";
+    readonly 'required-mark': "dds-textinput__required-mark";
+    readonly 'optional-mark': "dds-textinput__optional-mark";
+    readonly 'label-tooltip': "dds-textinput__label-tooltip";
+    readonly control: "dds-textinput__control";
+    readonly 'leading-icon': "dds-textinput__leading-icon";
+    readonly prefix: "dds-textinput__prefix";
+    readonly field: "dds-textinput__field";
+    readonly suffix: "dds-textinput__suffix";
+    readonly clear: "dds-textinput__clear";
+    readonly 'trailing-icon': "dds-textinput__trailing-icon";
+    readonly helper: "dds-textinput__helper";
+    readonly message: "dds-textinput__message";
+    readonly 'message-icon': "dds-textinput__message-icon";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const textInputDefaults: {
+    readonly size: "md";
+    readonly status: "none";
+    readonly type: "text";
+    readonly clearable: false;
+    readonly required: false;
+    readonly requiredMark: "text";
+    readonly optional: false;
+};
+/** The step this component draws a glyph slot at. Generated — do not retype. */
+export declare const textInputGlyphStep: {
+    readonly sm: "xs";
+    readonly md: "sm";
+    readonly lg: "sm";
+};

package/dist/components/core/text-input/TextInput.types.js

@@ -0,0 +1,24 @@
+// GENERATED from text-input.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const textInputParts = {
+    root: 'dds-textinput',
+    'label-row': 'dds-textinput__label-row',
+    label: 'dds-textinput__label',
+    'required-mark': 'dds-textinput__required-mark',
+    'optional-mark': 'dds-textinput__optional-mark',
+    'label-tooltip': 'dds-textinput__label-tooltip',
+    control: 'dds-textinput__control',
+    'leading-icon': 'dds-textinput__leading-icon',
+    prefix: 'dds-textinput__prefix',
+    field: 'dds-textinput__field',
+    suffix: 'dds-textinput__suffix',
+    clear: 'dds-textinput__clear',
+    'trailing-icon': 'dds-textinput__trailing-icon',
+    helper: 'dds-textinput__helper',
+    message: 'dds-textinput__message',
+    'message-icon': 'dds-textinput__message-icon',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const textInputDefaults = { size: 'md', status: 'none', type: 'text', clearable: false, required: false, requiredMark: 'text', optional: false };
+/** The step this component draws a glyph slot at. Generated — do not retype. */
+export const textInputGlyphStep = { sm: 'xs', md: 'sm', lg: 'sm' };

package/dist/components/core/text-input/text-input-impl.css

@@ -0,0 +1,36 @@
+/*
+ * Scoped to this package, like the generated sheet beside it.
+ *
+ * `:where([data-dds-context="marketing"])` confines these rules without contributing
+ * specificity, so the one override below still ties or beats exactly what it did before.
+ */
+
+/*
+ * The status glyph's box is one line of the message tall.
+ *
+ * The contract binds the font size and the line height on this part, which is what makes it
+ * one line — but a line's height is those two multiplied, and a binding carries one token,
+ * not an expression over two. So the multiplication happens here, over the same variables the
+ * contract bound: no measure is declared, and retuning either token moves this with it.
+ *
+ * Why a height at all, when the part could simply hold the glyph: aligned to the start of the
+ * block axis, a glyph is as tall as itself — 16px against a 21px line — so its middle sits
+ * above the first line's and the words beside it read as pushed down. A box one line tall with
+ * the glyph centred in it puts the two middles on each other.
+ *
+ * Centred geometrically rather than on the inline baseline. `vertical-align: middle` is the
+ * usual recipe and it is not the same thing: it puts a glyph's middle on the baseline plus half
+ * an x-height, which lands a pixel or so below the middle of a line of capitals and leaves the
+ * glyph hanging under the baseline where the type has its descender.
+ *
+ * One rule rather than one per size, because the message is font.body.sm at every step — it is
+ * the small print under a field whatever size it is, and the field's own sizes do not reach it. The day
+ * that stops being true this needs a second rule, and naming the role rather than a measure is
+ * what will make that obvious.
+ *
+ * The same problem InlineAlert solved first, and the same answer; the argument in full is in
+ * inline-alert-impl.css.
+ */
+:where([data-dds-context="marketing"]) .dds-textinput__message-icon {
+  block-size: calc(var(--font-body-sm-size) * var(--font-body-sm-line-height));
+}

package/dist/components/core/tooltip/Tooltip.css

@@ -0,0 +1,101 @@
+/* GENERATED from tooltip.contract.json. Do not edit. */
+
+:where([data-dds-context="marketing"]) .dds-tooltip {
+  transition-property: opacity, scale;
+  align-items: center;
+  display: flex;
+  pointer-events: none;
+  width: max-content;
+  font-family: var(--font-body-sm-family);
+  font-size: var(--font-body-sm-size);
+  font-weight: var(--font-body-sm-weight);
+  line-height: var(--font-body-sm-line-height);
+  transition-duration: var(--motion-duration-fast);
+  transition-timing-function: var(--motion-easing-enter);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip .dds-tooltip__caret {
+  box-sizing: content-box;
+  color: var(--color-bg-strong);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip .dds-tooltip__body {
+  box-sizing: border-box;
+  overflow-wrap: break-word;
+  text-wrap: balance;
+  background-color: var(--color-bg-strong);
+  border-radius: var(--radius-subtle);
+  box-shadow: var(--elevation-surface-floating);
+  color: var(--color-fg-on-strong);
+  max-inline-size: var(--size-tooltip-max);
+  padding-block: var(--space-inset-sm);
+  padding-inline: var(--space-inset-md);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="bottom"] {
+  flex-direction: column;
+  transform-origin: top;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="left"] {
+  flex-direction: row-reverse;
+  transform-origin: right;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="right"] {
+  flex-direction: row;
+  transform-origin: left;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="top"] {
+  flex-direction: column-reverse;
+  transform-origin: bottom;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-alignment="center"] .dds-tooltip__caret {
+  align-self: center;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-alignment="end"] .dds-tooltip__caret {
+  align-self: flex-end;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-alignment="start"] .dds-tooltip__caret {
+  align-self: flex-start;
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-hidden="true"] {
+  opacity: var(--opacity-hidden);
+  scale: var(--motion-scale-enter);
+  transition-duration: var(--motion-duration-instant);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="bottom"] .dds-tooltip__caret {
+  height: var(--space-gap-xs);
+  padding-inline: var(--space-inset-sm);
+  width: var(--space-gap-sm);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="left"] .dds-tooltip__caret {
+  height: var(--space-gap-sm);
+  padding-block: var(--space-inset-sm);
+  width: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="right"] .dds-tooltip__caret {
+  height: var(--space-gap-sm);
+  padding-block: var(--space-inset-sm);
+  width: var(--space-gap-xs);
+}
+
+:where([data-dds-context="marketing"]) .dds-tooltip[data-placement="top"] .dds-tooltip__caret {
+  height: var(--space-gap-xs);
+  padding-inline: var(--space-inset-sm);
+  width: var(--space-gap-sm);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :where([data-dds-context="marketing"]) .dds-tooltip,
+  :where([data-dds-context="marketing"]) .dds-tooltip * { transition: none; }
+}
+

package/dist/components/core/tooltip/Tooltip.d.ts

@@ -0,0 +1,51 @@
+import './Tooltip.css';
+import './tooltip-impl.css';
+import { type TooltipProps } from './Tooltip.types.js';
+export type { TooltipProps };
+/**
+ * The chip only. When it appears, and where, is the anchor's decision — this
+ * component has neither a timer nor a position of its own. Both ship beside it, as
+ * `useTooltip` and `TooltipAnchor`, so that a consumer with a trigger this cannot
+ * wrap still has the parts to assemble one.
+ *
+ * `placement` names where the tooltip sits relative to its anchor — `top` is above
+ * it — and the caret is drawn on the opposite edge so it points back at what it
+ * describes. Naming the placement rather than the caret's own edge is what lets the
+ * wrapper pass one value straight through to two readers: the stylesheet that moves
+ * the chip, and this file that picks which triangle to draw. Neither has to remember
+ * to invert it. Nothing here moves the tooltip, so a `placement` that disagrees with
+ * where the chip actually sits is still the consumer's mistake to avoid.
+ *
+ * `role="tooltip"` carries no behaviour of its own; it is what makes the
+ * `aria-describedby` on the anchor announce as a description rather than as a
+ * second, unrelated run of text. Which is why the contract's second `a11y`
+ * requirement has no executable `check`: the association lives on the anchor,
+ * and nothing in this component's own DOM can prove it was made.
+ *
+ * `id` is not a declared prop — it arrives through `HTMLAttributes`, and the
+ * anchor needs it to point here at all. That is the reason this contract has an
+ * `api.extends` where Card deliberately does not.
+ *
+ * `showCaret` decides whether the caret is rendered at all, rather than rendered and
+ * hidden. That is a contract decision and not this file's: the anatomy declares the
+ * part `presentWhen: "showCaret"`, which is how a conditional part is described here
+ * and how the generated stylesheet and behaviour test both come to know about it.
+ * The alternative it replaced — one `placement` value meaning "nowhere", drawing a
+ * caret and then hiding it with `display: none` — spent a whole axis of the variant
+ * matrix on a chip that had no position to point from.
+ *
+ * DOM order is fixed: caret first, always. `flex-direction` carries the side —
+ * `column` and `column-reverse`, `row` and `row-reverse` — so which end of the
+ * chip the caret sits at is decided by the stylesheet from the contract, and this
+ * file never branches on placement.
+ *
+ * `hidden` shadows the native attribute of the same name and does not mean what it
+ * means: native `hidden` is `display: none`, and a tooltip that leaves the layout
+ * has nothing to fade from and no box to fade in. This one is a bound opacity, so
+ * the chip stays where it is, stays measurable, and stays pointed at by the anchor's
+ * `aria-describedby` — the description is still announced with the control it
+ * explains, which is the whole reason that association exists. Shadowing a native
+ * attribute is Input's precedent, where `size` means the control's scale rather than
+ * a character count.
+ */
+export declare function Tooltip({ placement, alignment, showCaret, hidden, children, ...rest }: TooltipProps): import("react").JSX.Element;

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

@@ -0,0 +1,87 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import './Tooltip.css';
+import './tooltip-impl.css';
+import { tooltipDefaults, tooltipParts } from './Tooltip.types.js';
+/**
+ * The caret, once per side the tooltip can sit on.
+ *
+ * Keyed by `placement`, which names where the tooltip is — so each entry holds the
+ * triangle that points back the other way, at the anchor. `top` means the tooltip
+ * is above its anchor, so `top` draws a triangle pointing down. Reading this table
+ * as "the direction the caret points" gets every entry backwards, which is the one
+ * mistake this shape invites.
+ *
+ * Four paths rather than one path rotated four ways, because rotation is not
+ * something a contract can express: `structure` carries CSS keywords, and every
+ * form of `rotate` needs an angle. Drawing each direction moves that decision
+ * into geometry, where it costs nothing — the shape of a triangle is not a design
+ * decision that a designer would ever want to vary by brand or mode.
+ *
+ * Shape is all that is left here. How big the caret is, and how far it sits from
+ * the chip's rounded corner, are both design decisions and both live in the
+ * contract — `width`/`height` per side, and `padding-inline`/`padding-block` for
+ * the inset that keeps the caret clear of the chip's rounded corner. This file
+ * carried the size for one pass, as an `em` ratio on the SVG itself, and that put
+ * a decision where no contract, no generated doc and no Figma push could see it.
+ *
+ * So there is no width or height attribute below. The stylesheet supplies both,
+ * and each direction carries only its own viewBox — the aspect the triangle is
+ * drawn at, which has to agree with the bound box or the shape would be scaled to
+ * fit and stop being the shape that was drawn.
+ */
+const CARET = {
+    top: { viewBox: '0 0 8 4', d: 'M0 0 L4 4 L8 0 Z' },
+    right: { viewBox: '0 0 4 8', d: 'M4 0 L0 4 L4 8 Z' },
+    bottom: { viewBox: '0 0 8 4', d: 'M0 4 L4 0 L8 4 Z' },
+    left: { viewBox: '0 0 4 8', d: 'M0 0 L4 4 L0 8 Z' },
+};
+/**
+ * The chip only. When it appears, and where, is the anchor's decision — this
+ * component has neither a timer nor a position of its own. Both ship beside it, as
+ * `useTooltip` and `TooltipAnchor`, so that a consumer with a trigger this cannot
+ * wrap still has the parts to assemble one.
+ *
+ * `placement` names where the tooltip sits relative to its anchor — `top` is above
+ * it — and the caret is drawn on the opposite edge so it points back at what it
+ * describes. Naming the placement rather than the caret's own edge is what lets the
+ * wrapper pass one value straight through to two readers: the stylesheet that moves
+ * the chip, and this file that picks which triangle to draw. Neither has to remember
+ * to invert it. Nothing here moves the tooltip, so a `placement` that disagrees with
+ * where the chip actually sits is still the consumer's mistake to avoid.
+ *
+ * `role="tooltip"` carries no behaviour of its own; it is what makes the
+ * `aria-describedby` on the anchor announce as a description rather than as a
+ * second, unrelated run of text. Which is why the contract's second `a11y`
+ * requirement has no executable `check`: the association lives on the anchor,
+ * and nothing in this component's own DOM can prove it was made.
+ *
+ * `id` is not a declared prop — it arrives through `HTMLAttributes`, and the
+ * anchor needs it to point here at all. That is the reason this contract has an
+ * `api.extends` where Card deliberately does not.
+ *
+ * `showCaret` decides whether the caret is rendered at all, rather than rendered and
+ * hidden. That is a contract decision and not this file's: the anatomy declares the
+ * part `presentWhen: "showCaret"`, which is how a conditional part is described here
+ * and how the generated stylesheet and behaviour test both come to know about it.
+ * The alternative it replaced — one `placement` value meaning "nowhere", drawing a
+ * caret and then hiding it with `display: none` — spent a whole axis of the variant
+ * matrix on a chip that had no position to point from.
+ *
+ * DOM order is fixed: caret first, always. `flex-direction` carries the side —
+ * `column` and `column-reverse`, `row` and `row-reverse` — so which end of the
+ * chip the caret sits at is decided by the stylesheet from the contract, and this
+ * file never branches on placement.
+ *
+ * `hidden` shadows the native attribute of the same name and does not mean what it
+ * means: native `hidden` is `display: none`, and a tooltip that leaves the layout
+ * has nothing to fade from and no box to fade in. This one is a bound opacity, so
+ * the chip stays where it is, stays measurable, and stays pointed at by the anchor's
+ * `aria-describedby` — the description is still announced with the control it
+ * explains, which is the whole reason that association exists. Shadowing a native
+ * attribute is Input's precedent, where `size` means the control's scale rather than
+ * a character count.
+ */
+export function Tooltip({ placement = tooltipDefaults.placement, alignment = tooltipDefaults.alignment, showCaret = tooltipDefaults.showCaret, hidden = tooltipDefaults.hidden, children, ...rest }) {
+    const caret = CARET[placement];
+    return (_jsxs("div", { className: tooltipParts.root, role: "tooltip", "data-placement": placement, "data-alignment": alignment, "data-hidden": hidden, ...rest, children: [showCaret && (_jsx("svg", { className: tooltipParts.caret, viewBox: caret.viewBox, "aria-hidden": "true", children: _jsx("path", { d: caret.d, fill: "currentColor" }) })), _jsx("div", { className: tooltipParts.body, children: children })] }));
+}

package/dist/components/core/tooltip/Tooltip.types.d.ts

@@ -0,0 +1,38 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export interface TooltipOwnProps {
+    /**
+     * `top` — The tooltip sits above its anchor, so the caret drops from the bottom edge to meet it
+     * `right` — The tooltip sits on the trailing side of its anchor — the right in English, the left in Arabic — so the caret reaches back across to meet it. The name is physical and the behaviour is logical: the chip's own direction mirrors this, caret and all
+     * `bottom` — The tooltip sits below its anchor, so the caret rises from the top edge to meet it
+     * `left` — The tooltip sits on the leading side of its anchor — the left in English, the right in Arabic — so the caret reaches across to meet it. The name is physical and the behaviour is logical: the chip's own direction mirrors this, caret and all
+     */
+    placement?: 'top' | 'right' | 'bottom' | 'left';
+    /**
+     * `center` — The chip is centred on its anchor and the caret's point lands on the middle of it. Use this unless the chip is much wider than the thing it points at
+     * `start` — The chip's leading edge lines up with the anchor's own, so a chip wider than its anchor grows away from it rather than back across the layout. For an anchor at the start of a row
+     * `end` — The mirror of start: the chip's trailing edge lines up with the anchor's, for an anchor at the end of a row
+     */
+    alignment?: 'center' | 'start' | 'end';
+    /** Whatever reveals the tooltip has not revealed it yet, or has dismissed it. Defaults to false, which means visible — so something has to drive this, or the chip is simply on. Keeping it mounted and hidden rather than unmounting it is what lets it fade in, and what keeps the anchor's aria-describedby pointing at something real.
+  
+  Flipping it is the whole animation. The chip fades from opacity.hidden and scales up from motion.scale.enter over motion.duration.fast on motion.easing.enter, growing out of the edge nearest its anchor rather than its own middle. The dismissal is not animated at all — transition-duration is motion.duration.instant while hidden, because by then the pointer has already gone somewhere else. Do not write a transition of your own: the stylesheet declares transition-property from what this axis changes, and a second declaration would both override that list and escape the prefers-reduced-motion guard generated with it. */
+    hidden?: boolean;
+    /** Drawn by default. Leave it on whenever something holds the chip against its anchor — the point is what ties a floating description to the control it belongs to */
+    showCaret?: boolean;
+    /** Allowed: text */
+    children: ReactNode;
+}
+export type TooltipProps = TooltipOwnProps & Omit<HTMLAttributes<HTMLDivElement>, 'className' | 'placement' | 'alignment' | 'hidden' | 'showCaret'>;
+/** The class each part carries. Apply these — do not retype them. */
+export declare const tooltipParts: {
+    readonly root: "dds-tooltip";
+    readonly caret: "dds-tooltip__caret";
+    readonly body: "dds-tooltip__body";
+};
+/** Generated so defaults cannot drift from the contract. */
+export declare const tooltipDefaults: {
+    readonly placement: "top";
+    readonly alignment: "center";
+    readonly hidden: false;
+    readonly showCaret: true;
+};

package/dist/components/core/tooltip/Tooltip.types.js

@@ -0,0 +1,9 @@
+// GENERATED from tooltip.contract.json. Do not edit.
+/** The class each part carries. Apply these — do not retype them. */
+export const tooltipParts = {
+    root: 'dds-tooltip',
+    caret: 'dds-tooltip__caret',
+    body: 'dds-tooltip__body',
+};
+/** Generated so defaults cannot drift from the contract. */
+export const tooltipDefaults = { placement: 'top', alignment: 'center', hidden: false, showCaret: true };

package/dist/components/core/tooltip/TooltipAnchor.d.ts

@@ -0,0 +1,52 @@
+import './tooltip-anchor.css';
+import { type HTMLAttributes, type ReactElement, type ReactNode } from 'react';
+import { type TooltipProps } from './Tooltip.types.js';
+import { type UseTooltipOptions } from './use-tooltip.js';
+export interface TooltipAnchorProps extends UseTooltipOptions {
+    /**
+     * The trigger: one element, which the description is attached to and the pointer and
+     * focus handlers are added to. It has to be something focus can rest on — a button
+     * or a link, not a span — or the description is one no keyboard ever reaches.
+     *
+     * Typed as a single element rather than ReactNode because this clones it. Text, a
+     * fragment or a list has nothing to clone and nowhere to put an aria-describedby, so
+     * the constraint is better carried by the type than discovered at runtime.
+     *
+     * A component works as well as a plain element, provided it forwards the props it is
+     * handed — which is what a contract's `api.extends` promises, and why Button can be a
+     * trigger. One that declares none swallows them silently: the type still fits, and the
+     * description reaches nothing.
+     */
+    children: ReactElement<HTMLAttributes<HTMLElement>>;
+    /** The description. Short — the contract's own guidance is that this is a label, not a panel. */
+    content: ReactNode;
+    /**
+     * Which side of the anchor the chip sits on, passed straight through to the chip so
+     * one value places the box and draws the caret pointing back the other way.
+     */
+    placement?: TooltipProps['placement'];
+    /** Where along that side, which is the axis the placement did not use. */
+    alignment?: TooltipProps['alignment'];
+    /** Passed through to the chip, which renders the caret or leaves it out. */
+    showCaret?: TooltipProps['showCaret'];
+}
+/**
+ * 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 declare function TooltipAnchor({ children, content, placement, alignment, showCaret, ...options }: TooltipAnchorProps): import("react").JSX.Element;