documentation/components/source/width-control.ts

1/**
2 * Asking for an example's width: a grip to drag and a number field to type in.
3 *
4 * This is interaction state only. It reads one rectangle when a drag begins
5 * and afterwards turns pointer positions into requested widths. The owner
6 * applies a request to its host; CSS and the composition do the rest.
7 */
8
9export const minimumWidth = 160,
10  maximumWidth = 720;
11
12/** A whole width between the smallest useful example and `maximum`. */
13export function clampWidth(width: number, maximum: number): number {
14  return Math.round(
15    Math.min(maximum, Math.max(Math.min(minimumWidth, maximum), width)),
16  );
17}
18
19export interface WidthControlOptions {
20  /** The grip. It tracks the pointer while linked hosts reflow around it. */
21  readonly handle: HTMLElement;
22  /** The box whose inline size is being requested. */
23  readonly viewport: HTMLElement;
24  /** The number field showing that size. */
25  readonly input: HTMLInputElement;
26  /** The widest request the surrounding stage allows now. */
27  limit(): number;
28  /**
29   * Receives a requested width, which may not be finite when the field holds
30   * no number. `settled` is false during a drag. A drag passes the `maximum`
31   * it began with, so the limit cannot move under the pointer.
32   */
33  request(width: number, settled: boolean, maximum?: number): void;
34  /** Shows the actual width again when the reader leaves the field. */
35  restore(): void;
36  readonly signal: AbortSignal;
37}
38
39export interface WidthControl {
40  /** True from pointer down on the grip until the drag ends. */
41  readonly dragging: boolean;
42  /** Abandons a drag in progress without requesting a width. */
43  cancel(): void;
44}
45
46export function widthControl({
47  handle,
48  viewport,
49  input,
50  limit,
51  request,
52  restore,
53  signal,
54}: WidthControlOptions): WidthControl {
55  let frame = 0;
56  let drag:
57    | {
58        pointer: number;
59        direction: number;
60        x: number;
61        width: number;
62        maximum: number;
63        nextWidth: number;
64      }
65    | undefined;
66
67  input.addEventListener(
68    "input",
69    () => {
70      if (Number.isFinite(input.valueAsNumber))
71        request(input.valueAsNumber, true);
72    },
73    { signal },
74  );
75  input.addEventListener("change", () => request(input.valueAsNumber, true), {
76    signal,
77  });
78  input.addEventListener("blur", () => restore(), { signal });
79  input.addEventListener(
80    "keydown",
81    (event) => {
82      if (event.key === "Enter") input.blur();
83    },
84    { signal },
85  );
86  handle.addEventListener(
87    "pointerdown",
88    (event) => {
89      if (event.button !== 0) return;
90      const initialWidth = viewport.getBoundingClientRect().width;
91      drag = {
92        pointer: event.pointerId,
93        direction: getComputedStyle(viewport).direction === "rtl" ? -1 : 1,
94        x: event.clientX,
95        width: initialWidth,
96        nextWidth: initialWidth,
97        maximum: limit(),
98      };
99      handle.dataset.dragging = "true";
100      handle.style.setProperty("--grip-y", `${event.clientY}px`);
101      handle.setPointerCapture(event.pointerId);
102      event.preventDefault();
103    },
104    { signal },
105  );
106  handle.addEventListener(
107    "pointermove",
108    (event) => {
109      if (drag?.pointer !== event.pointerId) return;
110      drag.nextWidth = drag.width + (event.clientX - drag.x) * drag.direction;
111      handle.style.setProperty("--grip-y", `${event.clientY}px`);
112      if (!frame)
113        frame = requestAnimationFrame(() => {
114          frame = 0;
115          if (drag) request(drag.nextWidth, false, drag.maximum);
116        });
117    },
118    { signal },
119  );
120  const release = () => {
121    cancelAnimationFrame(frame);
122    frame = 0;
123    drag = undefined;
124    delete handle.dataset.dragging;
125    handle.style.removeProperty("--grip-y");
126  };
127  const end = () => {
128    if (!drag) return;
129    cancelAnimationFrame(frame);
130    frame = 0;
131    request(drag.nextWidth, true, drag.maximum);
132    release();
133  };
134  handle.addEventListener("pointerup", end, { signal });
135  handle.addEventListener("pointercancel", end, { signal });
136  handle.addEventListener("lostpointercapture", end, { signal });
137
138  return {
139    get dragging() {
140      return drag !== undefined;
141    },
142    cancel: release,
143  };
144}