@tremolo-ui/dom 0.7.0 → 0.9.0

package/dist/internal.d.cts

@@ -0,0 +1,365 @@
+import { C as pianoWidth, D as ModifierState, O as ModifierValue, a as POINTS_EDITOR_DEFAULT_WHEEL, b as fitWhiteKeyWidth, d as clampPoint, g as toXY, i as POINTS_EDITOR_DEFAULT_KEYBOARD, k as selectModifier, n as SliderMark, o as POINT_AXIS, r as sliderMarks, w as InputEventOption, x as getNoteRangeArray, y as blackKeyWidth } from "./marks-DK7xJmGM.cjs";
+import { Scale, ValueRange } from "@tremolo-ui/functions";
+//#region src/file/accept.d.ts
+/**
+ * What an `accept` rule is matched against.
+ *
+ * `File` satisfies it, and so does `DataTransferItem` — which matters while a
+ * drag is still in the air, since the browser reports the type of what is
+ * being dragged but withholds the name.
+ */
+interface AcceptCandidate {
+  /** The file name, when it is known. */
+  name?: string;
+  /** The MIME type, or `''` when the browser has no type for it. */
+  type: string;
+}
+/**
+ * Split files into those that satisfy `accept` and those that do not, keeping
+ * their order. See {@link matchesAccept}.
+ */
+export declare function partitionByAccept(files: Iterable<File>, accept?: string): {
+  accepted: File[];
+  rejected: File[];
+};
+//#endregion
+//#region src/input/apply-delta.d.ts
+/**
+ * Move a value by an amount of input, as reported by a wheel or an arrow key.
+ *
+ * The pipeline matches {@link createDragValue}: scale, then step, then clamp.
+ * Which key or which sign of `deltaY` counts as which direction is left to the
+ * caller, since it differs per component.
+ *
+ * @param direction which way, and how many times, to apply the option. The
+ * size of one step is `option[1]`, so this is normally `1` or `-1`.
+ *
+ * @param modifiers the event, for `options` that name a modifier key. See
+ * {@link selectModifier}.
+ *
+ * @example
+ * // ArrowDown on a slider whose keyboard option is ['raw', 1]
+ * applyDelta(value, -1, keyboard, { min, max, step, scale })
+ *
+ * @example
+ * // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
+ * applyDelta(value, -1, keyboard, range, event)
+ */
+export declare function applyDelta(value: number, direction: number, options: ModifierValue<InputEventOption>, { min, max, step, scale }: ValueRange, modifiers?: ModifierState): number;
+//#endregion
+//#region src/input/check-steps.d.ts
+interface CheckStepsOptions {
+  /** The component, for the message. */
+  component: string;
+  /** The axis, for a component that has more than one. */
+  axis?: string;
+  /**
+   * The range to probe, or `null` to check nothing. An unbounded input has no
+   * travel to sample, so `NumberInput` passes `null` when `min` and `max` are
+   * not both there.
+   */
+  range: ValueRange | null;
+  keyboard?: ModifierValue<InputEventOption> | null;
+  wheel?: ModifierValue<InputEventOption> | null;
+  /**
+   * How the value is displayed, where the component shows one. Called with
+   * probe values only.
+   */
+  format?: (value: number) => string;
+}
+/**
+ * The warnings to show when a key press or a wheel notch cannot produce a
+ * change the user can see. Empty when there is nothing to say.
+ *
+ * Two settings that are each fine on their own can cancel out, and nothing
+ * fails when they do — the control simply sits there:
+ *
+ * - **`step` coarser than the amount.** `keyboard={['raw', 0.1]}` with
+ *   `step={1}` rounds every press straight back to where it started
+ * - **the display coarser than the amount.** A `format` showing two decimals
+ *   of a kHz value cannot show a press worth 1 Hz
+ *
+ * The second is only reported when the press is invisible at *every* point
+ * along the travel. A display that rounds is a deliberate choice and is
+ * normally right — it is being too coarse everywhere that makes it a mistake.
+ *
+ * **Meant for development builds only.** It probes the whole travel, so call
+ * it behind an inline `process.env.NODE_ENV` check: the bundler then drops
+ * the call, and this function and its messages with it.
+ */
+export declare function checkSteps({ component, axis, range, keyboard, wheel, format }: CheckStepsOptions): string[];
+//#endregion
+//#region src/input/direction.d.ts
+/** A move along one of the two axes of a position on screen. */
+interface AxisMove {
+  /** 0 = x, 1 = y. */
+  axis: 0 | 1;
+  /** `1` towards the right or the bottom, `-1` towards the left or the top. */
+  direction: 1 | -1;
+}
+/**
+ * The direction an arrow key moves a single value: right and up raise it.
+ * `null` for any other key.
+ */
+export declare function arrowKeyDirection(key: string): 1 | -1 | null;
+/**
+ * The axis and direction an arrow key moves a position on screen. `null` for
+ * any other key.
+ *
+ * The key picks the axis, whichever element inside the control holds the
+ * focus: a two-dimensional control is one control to the person moving it.
+ */
+export declare function arrowKeyMove(key: string): AxisMove | null;
+interface WheelDirectionOptions {
+  /**
+   * Read horizontal scrolling as well, for a control laid out horizontally:
+   * scrolling right raises the value. Vertical scrolling still counts when
+   * there is no horizontal movement.
+   *
+   * @default false
+   */
+  horizontal?: boolean;
+}
+/**
+ * The direction one wheel event moves a single value: scrolling up raises it.
+ * `null` when the event carries no movement the control reads.
+ */
+export declare function wheelDirection(event: Pick<WheelEvent, 'deltaX' | 'deltaY'>, { horizontal }?: WheelDirectionOptions): 1 | -1 | null;
+/**
+ * The axis and direction one wheel event moves a position on screen. `null`
+ * when the event carries no movement.
+ *
+ * Scrolling moves y, and shift switches to x. Browsers turn shift+wheel into
+ * horizontal scrolling: `deltaY` comes out empty and `deltaX` carries the
+ * movement. Reading whichever axis moved keeps shift working as the x-axis
+ * modifier — and picks up a trackpad's own horizontal gesture, which never
+ * had a modifier.
+ */
+export declare function wheelMove(event: Pick<WheelEvent, 'deltaX' | 'deltaY' | 'shiftKey'>): AxisMove | null;
+//#endregion
+//#region src/number-input/stepper-drag.d.ts
+interface StepperDragOptions {
+  /** The value now, read when the drag starts moving it. */
+  getValue: () => number;
+  /**
+   * The range the value moves across. Its `step` is what one step of the drag
+   * is worth; see `numberInputRanges` for the one a number input uses.
+   */
+  range: ValueRange;
+  /**
+   * How many pixels of vertical movement make one step.
+   *
+   * @default 1
+   */
+  pixels?: number;
+  /**
+   * How much a step is worth, per modifier key: `0.1` makes the same movement
+   * count a tenth as much. Pressing or releasing the key mid-drag does not
+   * move the value.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  sensitivity?: ModifierValue<number>;
+  /** Hide the pointer and keep it from hitting the edge of the screen. */
+  pointerLock?: boolean;
+  /**
+   * The cursor to show while dragging. Applied to the element itself, as
+   * `createDrag` does.
+   *
+   * @default 'ns-resize'
+   */
+  cursor?: string;
+  /** Called with the new value whenever the drag moves it. */
+  onChange: (value: number) => void;
+}
+interface StepperDragInstance {
+  /** Replace the given options. `pointerLock` reaches the next drag. */
+  update: (options: Partial<StepperDragOptions>) => void;
+  /**
+   * Whether the drag in progress has moved the value. A stepper button's
+   * press-and-hold repeat stands down once it has, so the value is not moved
+   * twice.
+   */
+  moved: () => boolean;
+  destroy: () => void;
+}
+/**
+ * Drag up and down on the steppers of a number input to move its value, one
+ * `step` every `pixels` — up raises it, as on a knob.
+ *
+ * Counted from where the drag started moving rather than added up per
+ * event, so rounding cannot accumulate. The start is taken on the first
+ * move, not on pointerdown: a stepper button acts on pointerdown, so by then
+ * the value may already have been nudged once, and the drag carries on from
+ * there.
+ */
+export declare function createStepperDrag(element: Element, options: StepperDragOptions): StepperDragInstance;
+//#endregion
+//#region src/number-input/value.d.ts
+/**
+ * The value a number input edits, and how far it may go.
+ *
+ * Unlike a slider, either end may be left open, and `clampValue: false` lets
+ * the value past the ends that are set.
+ */
+interface NumberInputValueOptions {
+  min?: number;
+  max?: number;
+  step?: number;
+  scale?: Scale;
+  /**
+   * Keep the value between `min` and `max`.
+   *
+   * @default true
+   */
+  clampValue?: boolean;
+}
+/** The ranges {@link nudgeNumberInput} moves a value across. */
+interface NumberInputRanges {
+  /** For a `normalized` amount, which needs a finite span to take a share of. */
+  normalized: ValueRange;
+  /** For a `raw` amount, which does not. */
+  raw: ValueRange;
+}
+/**
+ * The ranges a number input moves its value across, with the open ends
+ * filled in.
+ *
+ * A normalized amount needs a finite span even when an end is unbounded or
+ * clamping is off. Safe integers provide one without overflowing the span a
+ * scale calculates. A raw amount needs no span, so its open ends can cover
+ * every finite number instead of stopping at the safe-integer range.
+ */
+export declare function numberInputRanges({ min, max, step, scale, clampValue }: NumberInputValueOptions): NumberInputRanges;
+/**
+ * Move a number input's value by one press of a key, a wheel notch or a
+ * stepper, picking the range that suits the kind of amount. See `applyDelta`.
+ */
+export declare function nudgeNumberInput(value: number, direction: number, options: ModifierValue<InputEventOption>, ranges: NumberInputRanges, modifiers?: ModifierState): number;
+/**
+ * Where the value stands against the ends: whether it can go no further
+ * down or up, and whether it lies outside them — which only an unclamped
+ * input, or a value set from outside, can do.
+ */
+export declare function numberInputBounds(value: number, { min, max, clampValue }: NumberInputValueOptions): {
+  atMin: boolean;
+  atMax: boolean;
+  outOfRange: boolean;
+};
+/**
+ * The value typed text commits to, or `null` when there is no number in it.
+ *
+ * Text with no number is not a value: the input should go back to what it
+ * was showing rather than commit a zero the user never typed. What is read
+ * is clamped here and not while typing, since clamping as the user types
+ * would make "1500" impossible to enter into an input whose max is 100.
+ */
+export declare function commitNumberInputText(text: string, parse: (text: string) => number, { min, max, clampValue }: NumberInputValueOptions): number | null;
+//#endregion
+//#region src/number-input/text.d.ts
+/**
+ * Reading a number out of the text of a number input, and keeping the caret
+ * in place while the number under it changes.
+ *
+ * The text is whatever `format` made of the value — `"440 Hz"`, `"-6.0 dB"` —
+ * or a half-typed entry, so none of this assumes the text is a number alone.
+ */
+/** Where the number is in the text; the rest, on either side, is the unit. */
+interface NumberSpan {
+  start: number;
+  end: number;
+}
+/**
+ * Where the number is in the text: from its first digit to its last, with the
+ * sign and the decimal point in front of it. Whatever is left on either side
+ * is taken for the unit, so it does not matter whether a space separates them,
+ * or what the number looks like — `+6.0`, `1e+21`, `1,000` and `1:30` are each
+ * one number. `null` when the text has no digit at all.
+ */
+export declare function numberSpan(text: string): NumberSpan | null;
+/**
+ * The number in the text, with the unit after it ignored: the default `parse`
+ * of a number input.
+ *
+ * `NaN`, which leaves the value alone, whenever the number cannot be read
+ * safely, rather than a part of it: text with no number, a number that is not
+ * a plain one (`1,000` would otherwise read as 1, and `1:30` as 1), and text
+ * with something in front of the number, which can change what it means (the
+ * `L` of a pan reading `L 30`). A `format` that writes any of those needs its
+ * own `parse`.
+ */
+export declare function parseNumberText(text: string): number;
+/**
+ * Where the caret is, relative to the decimal point, so that it can be put
+ * back at the same digit once the value has changed. See
+ * {@link caretAtDecimalOffset}.
+ */
+export declare function caretDecimalOffset(text: string, caret: number): number;
+/**
+ * The caret position `offset` characters from the decimal point of the new
+ * text, kept within the number.
+ *
+ * @example
+ * // The caret sits in front of the point of "9.9" when ArrowUp turns it
+ * // into "10.0"
+ * const offset = caretDecimalOffset('9.9', 1) // 0
+ * caretAtDecimalOffset('10.0', offset) // 2: still in front of the point
+ */
+export declare function caretAtDecimalOffset(text: string, offset: number): number;
+//#endregion
+//#region src/options/replace.d.ts
+/**
+ * The `update()` argument that leaves an instance with exactly `next` as its
+ * options.
+ *
+ * `update()` merges into what the instance has, which suits a wrapper that
+ * pushes one setting at a time. A wrapper handed the whole new set instead —
+ * a Svelte action, a Vue composable — has to clear what the new set no longer
+ * carries, or a handler taken away, or an option left to its default, keeps
+ * working.
+ *
+ * @example
+ * instance.update(replaceOptions(previous, next))
+ */
+export declare function replaceOptions<T extends object>(previous: T | undefined, next: T | undefined): Partial<T>;
+//#endregion
+//#region src/style.d.ts
+/**
+ * A number as a CSS length, for a custom property.
+ *
+ * A custom property takes whatever text it is given, so `--size: 50` comes out
+ * as the invalid `50` rather than `50px`. React appends `px` to a bare number
+ * only for the properties it knows take a length, and a custom property is
+ * never one of them; Vue and Svelte append nothing at all. Anything already a
+ * string is passed through, so `'3rem'` and `'100%'` still work.
+ */
+export declare function cssLength(value: number | string | undefined): string | undefined;
+/**
+ * Take an element out of sight while leaving it in the accessibility tree and
+ * in the tab order.
+ *
+ * `display: none` and `visibility: hidden` would remove it from both, and the
+ * native control underneath a headless component is what carries the ARIA and
+ * the keyboard behaviour. `pointer-events: none` is safe because nothing is
+ * ever clicked here directly: a `<label>` forwards its click, and a drag is
+ * handled by the part that is visible.
+ *
+ * Every value is a string with its unit, so the object can be handed to any
+ * framework's `style` binding as it is.
+ */
+export declare const visuallyHiddenStyle: {
+  readonly position: "absolute";
+  readonly width: "1px";
+  readonly height: "1px";
+  readonly padding: "0";
+  readonly margin: "-1px";
+  readonly overflow: "hidden";
+  readonly clip: "rect(0, 0, 0, 0)";
+  readonly clipPath: "inset(50%)";
+  readonly whiteSpace: "nowrap";
+  readonly border: "0";
+  readonly pointerEvents: "none";
+};
+//#endregion
+export { type AcceptCandidate, type AxisMove, type CheckStepsOptions, type NumberInputRanges, type NumberInputValueOptions, type NumberSpan, POINTS_EDITOR_DEFAULT_KEYBOARD, POINTS_EDITOR_DEFAULT_WHEEL, POINT_AXIS, type SliderMark, type StepperDragInstance, type StepperDragOptions, type WheelDirectionOptions, blackKeyWidth, clampPoint, fitWhiteKeyWidth, getNoteRangeArray, pianoWidth, selectModifier, sliderMarks, toXY };
+//# sourceMappingURL=internal.d.cts.map

package/dist/internal.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal.d.cts","names":[],"sources":["../src/file/accept.ts","../src/input/apply-delta.ts","../src/input/check-steps.ts","../src/input/direction.ts","../src/number-input/stepper-drag.ts","../src/number-input/value.ts","../src/number-input/text.ts","../src/options/replace.ts","../src/style.ts"],"mappings":";;;;;;;;;;UAOiB;;EAEf;;EAEA;;;;;;wBAoDc,kBACd,OAAO,SAAS,OAChB;EACG,UAAU;EAAQ,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;wBC9BjB,WACd,eACA,mBACA,SAAS,cAAc,qBACrB,KAAK,KAAK,MAAM,SAAuB,YACzC,YAAY;;;UC4BG;;EAEf;;EAEA;;;;;;EAMA,OAAO;EACP,WAAW,cAAc;EACzB,QAAQ,cAAc;;;;;EAKtB,UAAU;;;;;;;;;;;;;;;;;;;;;;wBAuBI,aACd,WACA,MACA,OACA,UACA,OACA,UACC;;;;UCrFc;;EAEf;;EAEA;;;;;;wBAOc,kBAAkB;;;;;;;;wBAYlB,aAAa,cAAc;UAQ1B;;;;;;;;EAQf;;;;;;wBAOc,eACd,OAAO,KAAK,oCACV,eAAsB;;;;;;;;;;;wBAiBV,UACd,OAAO,KAAK,gDACX;;;UCtFc;;EAEf;;;;;EAKA,OAAO;;;;;;EAMP;;;;;;;;EAQA,cAAc;;EAEd;;;;;;;EAOA;;EAEA,WAAW;;UAGI;;EAEf,SAAS,SAAS,QAAQ;;;;;;EAM1B;EACA;;;;;;;;;;;;wBAac,kBACd,SAAS,SACT,SAAS,qBACR;;;;;;;;;UCxDc;EACf;EACA;EACA;EACA,QAAQ;;;;;;EAMR;;;UAIe;;EAEf,YAAY;;EAEZ,KAAK;;;;;;;;;;;wBAYS,oBACd,KACA,KACA,MACA,OACA,cACC,0BAA0B;;;;;wBAuBb,iBACd,eACA,mBACA,SAAS,cAAc,mBACvB,QAAQ,mBACR,YAAY;;;;;;wBAiBE,kBACd,iBACE,KAAK,KAAK,cAAqB;;;;;;;;;;;;;wBAkBnB,sBACd,cACA,QAAQ,2BACN,KAAK,KAAK,cAAqB;;;;;;;;;;;UC5GlB;EACf;EACA;;;;;;;;;wBAUc,WAAW,eAAe;;;;;;;;;;;;wBAwB1B,gBAAgB;;;;;;wBAiChB,mBAAmB,cAAc;;;;;;;;;;;wBAcjC,qBAAqB,cAAc;;;;;;;;;;;;;;;;wBClFnC,eAAe,kBAC7B,UAAU,eACV,MAAM,gBACL,QAAQ;;;;;;;;;;;;wBCPK,UACd;;;;;;;;;;;;;;qBAkBW"}