@xaui/native 0.9.1-alpha.9 → 0.9.1-alpha.90

package/dist/utils/chart-path.d.cts

@@ -0,0 +1,73 @@
+import type { Point } from './chart-scale';
+/**
+ * How a line travels between two points.
+ *
+ * `linear` joins them with a straight edge. `monotone` bends through them without ever
+ * leaving the interval its neighbours set — which is what a curve through data has to do:
+ * a smooth line that dips below zero between two positive readings is drawing a number
+ * nobody measured, and an area chart doing it puts ink under the axis.
+ */
+export type Curve = 'linear' | 'monotone';
+/**
+ * The path through the points, as an SVG `d`.
+ *
+ * Fewer than two points draws nothing rather than a dot: a chart of one reading has no line
+ * in it, and an empty string is what tells the renderer so.
+ */
+export declare function linePath(points: ReadonlyArray<Point>, curve?: Curve): string;
+/**
+ * The same path, closed down to `baseline` and back — the shape an area chart fills.
+ *
+ * It closes through the **first and last x** rather than through the points themselves, so
+ * the fill has vertical edges at either end instead of a diagonal to the origin.
+ */
+export declare function areaPath(points: ReadonlyArray<Point>, baseline: number, curve?: Curve): string;
+/**
+ * A bar, with the two corners on its far end rounded.
+ *
+ * The radius is **clamped to half the bar's width and to its whole height**, which is what
+ * keeps a short bar a stadium rather than a shape whose arcs cross each other and render as
+ * a knot. A bar shorter than its own corner is a real and common case: it is the first bar
+ * of a chart that starts near zero.
+ */
+export declare function barPath(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, radius: number): string;
+/**
+ * A closed path through the points — the shape a radar series is.
+ *
+ * Always straight edges, never a curve: a radar's vertices are its **axes**, and a curve
+ * between two of them draws a reading on an axis that does not exist.
+ */
+export declare function polygonPath(points: ReadonlyArray<Point>): string;
+/**
+ * A point at `angle` on a circle, **clockwise from twelve o'clock**.
+ *
+ * The quarter turn is baked in here rather than at every call site: a radar's first axis
+ * points up, a pie's first slice starts at the top, and a reader's eye starts there too.
+ */
+export declare function polarPoint(center: Point, radius: number, angle: number): Point;
+/** One slice of a pie, or of a donut when `innerRadius` is above zero. */
+export type Arc = {
+    cx: number;
+    cy: number;
+    outerRadius: number;
+    innerRadius: number;
+    /** Radians, clockwise, zero at twelve o'clock. */
+    startAngle: number;
+    endAngle: number;
+};
+/**
+ * A slice, as an SVG `d`.
+ *
+ * Angles run **clockwise from twelve o'clock**, which is where a reader starts and the
+ * direction they go; the maths below is the quarter turn that puts zero at the top.
+ *
+ * A slice covering the whole circle is drawn as **two half arcs**: an SVG arc from a point
+ * back to itself is a no-op, so a single-category pie would otherwise render as nothing at
+ * all — which is the bug this shape exists to avoid.
+ */
+export declare function arcPath(arc: Arc): string;

package/dist/utils/chart-path.d.ts

@@ -0,0 +1,73 @@
+import type { Point } from './chart-scale';
+/**
+ * How a line travels between two points.
+ *
+ * `linear` joins them with a straight edge. `monotone` bends through them without ever
+ * leaving the interval its neighbours set — which is what a curve through data has to do:
+ * a smooth line that dips below zero between two positive readings is drawing a number
+ * nobody measured, and an area chart doing it puts ink under the axis.
+ */
+export type Curve = 'linear' | 'monotone';
+/**
+ * The path through the points, as an SVG `d`.
+ *
+ * Fewer than two points draws nothing rather than a dot: a chart of one reading has no line
+ * in it, and an empty string is what tells the renderer so.
+ */
+export declare function linePath(points: ReadonlyArray<Point>, curve?: Curve): string;
+/**
+ * The same path, closed down to `baseline` and back — the shape an area chart fills.
+ *
+ * It closes through the **first and last x** rather than through the points themselves, so
+ * the fill has vertical edges at either end instead of a diagonal to the origin.
+ */
+export declare function areaPath(points: ReadonlyArray<Point>, baseline: number, curve?: Curve): string;
+/**
+ * A bar, with the two corners on its far end rounded.
+ *
+ * The radius is **clamped to half the bar's width and to its whole height**, which is what
+ * keeps a short bar a stadium rather than a shape whose arcs cross each other and render as
+ * a knot. A bar shorter than its own corner is a real and common case: it is the first bar
+ * of a chart that starts near zero.
+ */
+export declare function barPath(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, radius: number): string;
+/**
+ * A closed path through the points — the shape a radar series is.
+ *
+ * Always straight edges, never a curve: a radar's vertices are its **axes**, and a curve
+ * between two of them draws a reading on an axis that does not exist.
+ */
+export declare function polygonPath(points: ReadonlyArray<Point>): string;
+/**
+ * A point at `angle` on a circle, **clockwise from twelve o'clock**.
+ *
+ * The quarter turn is baked in here rather than at every call site: a radar's first axis
+ * points up, a pie's first slice starts at the top, and a reader's eye starts there too.
+ */
+export declare function polarPoint(center: Point, radius: number, angle: number): Point;
+/** One slice of a pie, or of a donut when `innerRadius` is above zero. */
+export type Arc = {
+    cx: number;
+    cy: number;
+    outerRadius: number;
+    innerRadius: number;
+    /** Radians, clockwise, zero at twelve o'clock. */
+    startAngle: number;
+    endAngle: number;
+};
+/**
+ * A slice, as an SVG `d`.
+ *
+ * Angles run **clockwise from twelve o'clock**, which is where a reader starts and the
+ * direction they go; the maths below is the quarter turn that puts zero at the top.
+ *
+ * A slice covering the whole circle is drawn as **two half arcs**: an SVG arc from a point
+ * back to itself is a no-op, so a single-category pie would otherwise render as nothing at
+ * all — which is the bug this shape exists to avoid.
+ */
+export declare function arcPath(arc: Arc): string;

package/dist/utils/chart-scale.d.cts

@@ -0,0 +1,63 @@
+/** A closed interval, low first. */
+export type Span = readonly [number, number];
+/** A point in the plot, in the coordinates an SVG path is written in. */
+export type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Maps a value in `domain` onto `range`.
+ *
+ * A **function**, not a table: a chart calls it once per point per render, and returning a
+ * closure is what lets a caller pass it around without carrying the four numbers with it.
+ *
+ * An empty domain maps everything to the middle of the range rather than dividing by zero.
+ * That is the case of a series where every value is the same — a flat line halfway up the
+ * plot, which is what it is.
+ */
+export declare function linearScale(domain: Span, range: Span): (value: number) => number;
+/**
+ * A domain widened to the nearest round numbers, and the ticks inside it.
+ *
+ * **The domain is widened, not the ticks squeezed.** A y axis whose top tick is below the
+ * tallest bar is an axis that lies about the data, so the step is chosen first and the
+ * domain rounded out to a multiple of it.
+ *
+ * `count` is a **target**: the step lands on 1, 2, 5 or 10 times a power of ten, and how
+ * many of those fit is then arithmetic. Forcing an exact count is what produces an axis
+ * labelled 3.33 and 6.67.
+ */
+export declare function niceScale(min: number, max: number, count?: number): {
+    domain: Span;
+    ticks: number[];
+};
+/**
+ * Where each of `count` categories sits along `range`, and how wide one is.
+ *
+ * `padding` is the share of a slot left empty, so `0.4` puts a bar in the middle 60% of its
+ * own column. It is a **fraction** rather than points because the slot's width is the
+ * plot's divided by the data, and a caller cannot know that number.
+ */
+export declare function bandScale(count: number, range: Span, padding?: number): {
+    center: (index: number) => number;
+    width: number;
+    step: number;
+};
+/**
+ * Where each of `count` readings sits along `range`, with the **first and last on the ends**.
+ *
+ * The other half of `bandScale`, and the difference is what the mark is. A bar occupies a
+ * slot, so it is centred in one and the ends of the plot are empty. A line connects
+ * readings, so the first and the last sit on the edges — a line chart inset by half a slot
+ * at either end reads as a chart that has been cut off.
+ *
+ * `width` is the room a label under one of them gets, which is a whole step: the labels are
+ * centred on the readings, so neighbouring ones meet halfway.
+ */
+export declare function pointScale(count: number, range: Span): {
+    center: (index: number) => number;
+    width: number;
+    step: number;
+};
+/** The lowest and highest finite number in the lot, or `[0, 0]` when there are none. */
+export declare function extent(values: ReadonlyArray<number>): Span;

package/dist/utils/chart-scale.d.ts

@@ -0,0 +1,63 @@
+/** A closed interval, low first. */
+export type Span = readonly [number, number];
+/** A point in the plot, in the coordinates an SVG path is written in. */
+export type Point = {
+    x: number;
+    y: number;
+};
+/**
+ * Maps a value in `domain` onto `range`.
+ *
+ * A **function**, not a table: a chart calls it once per point per render, and returning a
+ * closure is what lets a caller pass it around without carrying the four numbers with it.
+ *
+ * An empty domain maps everything to the middle of the range rather than dividing by zero.
+ * That is the case of a series where every value is the same — a flat line halfway up the
+ * plot, which is what it is.
+ */
+export declare function linearScale(domain: Span, range: Span): (value: number) => number;
+/**
+ * A domain widened to the nearest round numbers, and the ticks inside it.
+ *
+ * **The domain is widened, not the ticks squeezed.** A y axis whose top tick is below the
+ * tallest bar is an axis that lies about the data, so the step is chosen first and the
+ * domain rounded out to a multiple of it.
+ *
+ * `count` is a **target**: the step lands on 1, 2, 5 or 10 times a power of ten, and how
+ * many of those fit is then arithmetic. Forcing an exact count is what produces an axis
+ * labelled 3.33 and 6.67.
+ */
+export declare function niceScale(min: number, max: number, count?: number): {
+    domain: Span;
+    ticks: number[];
+};
+/**
+ * Where each of `count` categories sits along `range`, and how wide one is.
+ *
+ * `padding` is the share of a slot left empty, so `0.4` puts a bar in the middle 60% of its
+ * own column. It is a **fraction** rather than points because the slot's width is the
+ * plot's divided by the data, and a caller cannot know that number.
+ */
+export declare function bandScale(count: number, range: Span, padding?: number): {
+    center: (index: number) => number;
+    width: number;
+    step: number;
+};
+/**
+ * Where each of `count` readings sits along `range`, with the **first and last on the ends**.
+ *
+ * The other half of `bandScale`, and the difference is what the mark is. A bar occupies a
+ * slot, so it is centred in one and the ends of the plot are empty. A line connects
+ * readings, so the first and the last sit on the edges — a line chart inset by half a slot
+ * at either end reads as a chart that has been cut off.
+ *
+ * `width` is the room a label under one of them gets, which is a whole step: the labels are
+ * centred on the readings, so neighbouring ones meet halfway.
+ */
+export declare function pointScale(count: number, range: Span): {
+    center: (index: number) => number;
+    width: number;
+    step: number;
+};
+/** The lowest and highest finite number in the lot, or `[0, 0]` when there are none. */
+export declare function extent(values: ReadonlyArray<number>): Span;

package/dist/utils/check-glyph.d.cts

@@ -0,0 +1,29 @@
+import type { ViewStyle } from 'react-native';
+/**
+ * The long stroke of the tick, as a fraction of the box it sits in. Exported because the
+ * `Checkbox`'s indeterminate dash is that same stroke on its own and level, and the two
+ * marks drifting apart would read as two different glyph sets.
+ */
+export declare const CHECK_SPAN = 0.5;
+/**
+ * A tick drawn out of two borders of an empty box, a quarter turn from where they look
+ * like one — so a control can mark itself in a project that has installed no icon set.
+ *
+ * It is **derived from the box** rather than tabulated: half its width, a quarter its
+ * height. Two numbers in a table would drift from the box the day someone changes it, and
+ * a check that is not proportional to its box reads as a different glyph at every size.
+ *
+ * The lift is the part worth having in one place. An "L" has its ink in one corner, not in
+ * the middle of its box, so rotating it about that box's centre leaves the tick sitting
+ * low. Rotating by −45° maps a point to `(dy − dx)·√2/2`, and over the two strokes that
+ * spans `H` at the top and `H − t − W` at the bottom — an ink centre `(H − t)·√2/4`
+ * **below** the box centre, which flexbox then dutifully centres. Lifting by exactly that
+ * is what makes the mark look centred rather than measure centred.
+ *
+ * Both transforms are returned together, and never split across two style objects:
+ * `transform` is a whole value, so a later step replaces it rather than blending into it.
+ *
+ * The colour is not here. A mark takes it from the variant that owns it — the box it fills
+ * for a `Checkbox`, the accent's contrast for a completed `Stepper` step.
+ */
+export declare function checkGlyph(side: number, stroke: number): ViewStyle;

package/dist/utils/check-glyph.d.ts

@@ -0,0 +1,29 @@
+import type { ViewStyle } from 'react-native';
+/**
+ * The long stroke of the tick, as a fraction of the box it sits in. Exported because the
+ * `Checkbox`'s indeterminate dash is that same stroke on its own and level, and the two
+ * marks drifting apart would read as two different glyph sets.
+ */
+export declare const CHECK_SPAN = 0.5;
+/**
+ * A tick drawn out of two borders of an empty box, a quarter turn from where they look
+ * like one — so a control can mark itself in a project that has installed no icon set.
+ *
+ * It is **derived from the box** rather than tabulated: half its width, a quarter its
+ * height. Two numbers in a table would drift from the box the day someone changes it, and
+ * a check that is not proportional to its box reads as a different glyph at every size.
+ *
+ * The lift is the part worth having in one place. An "L" has its ink in one corner, not in
+ * the middle of its box, so rotating it about that box's centre leaves the tick sitting
+ * low. Rotating by −45° maps a point to `(dy − dx)·√2/2`, and over the two strokes that
+ * spans `H` at the top and `H − t − W` at the bottom — an ink centre `(H − t)·√2/4`
+ * **below** the box centre, which flexbox then dutifully centres. Lifting by exactly that
+ * is what makes the mark look centred rather than measure centred.
+ *
+ * Both transforms are returned together, and never split across two style objects:
+ * `transform` is a whole value, so a later step replaces it rather than blending into it.
+ *
+ * The colour is not here. A mark takes it from the variant that owns it — the box it fills
+ * for a `Checkbox`, the accent's contrast for a completed `Stepper` step.
+ */
+export declare function checkGlyph(side: number, stroke: number): ViewStyle;

package/dist/utils/children.d.cts

@@ -0,0 +1,14 @@
+import type { ElementType, ReactNode } from 'react';
+/**
+ * Whether one of the direct children is an element of `type`.
+ *
+ * It is what `isLoading` asks before inserting a spinner: composing one yourself is how you
+ * put it after the label rather than before it, and the root has to know that before it
+ * renders. §8 of the plan takes this scan as the price of `<Button isLoading>Envoi…</Button>`
+ * working at all, which is the majority case.
+ *
+ * **Direct children only.** A spinner buried inside a wrapper is not the composition the
+ * auto-insert is about, and a deep walk would make "did I compose one?" depend on how many
+ * layers deep it sits.
+ */
+export declare function containsElementOfType(children: ReactNode, type: ElementType): boolean;

package/dist/utils/children.d.ts

@@ -0,0 +1,14 @@
+import type { ElementType, ReactNode } from 'react';
+/**
+ * Whether one of the direct children is an element of `type`.
+ *
+ * It is what `isLoading` asks before inserting a spinner: composing one yourself is how you
+ * put it after the label rather than before it, and the root has to know that before it
+ * renders. §8 of the plan takes this scan as the price of `<Button isLoading>Envoi…</Button>`
+ * working at all, which is the majority case.
+ *
+ * **Direct children only.** A spinner buried inside a wrapper is not the composition the
+ * auto-insert is about, and a deep walk would make "did I compose one?" depend on how many
+ * layers deep it sits.
+ */
+export declare function containsElementOfType(children: ReactNode, type: ElementType): boolean;

package/dist/utils/clock.d.cts

@@ -0,0 +1,45 @@
+/** A point on the dial, in the view's own coordinates. */
+export type ClockPoint = {
+    x: number;
+    y: number;
+};
+/**
+ * Where a value sits on the dial, in degrees **clockwise from twelve o'clock**.
+ *
+ * The quarter turn is baked in here rather than at every call site, for `polarPoint`'s
+ * reason: a clock's first mark is at the top, and so is a reader's eye.
+ *
+ * `count` is how many marks go all the way round — 12 for the hours, 60 for the minutes —
+ * and the value wraps, so hour 12 and hour 0 are the same place.
+ */
+export declare function clockAngle(value: number, count: number): number;
+/**
+ * The mark nearest that angle — the inverse, rounded.
+ *
+ * Rounded rather than floored: a finger halfway between two marks belongs to the one it is
+ * nearer, and a dial that always rounded down would feel like it lagged the touch by half a
+ * step.
+ */
+export declare function valueAtAngle(angle: number, count: number): number;
+/**
+ * A point at `angle` on a circle, **clockwise from twelve o'clock**.
+ *
+ * Screen coordinates grow downwards, which is why the cosine is subtracted rather than
+ * added: twelve o'clock is *above* the centre, and a plus there puts it below.
+ */
+export declare function clockPoint(center: ClockPoint, radius: number, angle: number): ClockPoint;
+/**
+ * Which way a point lies from the centre, in the same degrees `clockAngle` speaks.
+ *
+ * `atan2` measures from three o'clock and anticlockwise; the quarter turn and the sign here
+ * are what turn that into "clockwise from twelve", so a touch anywhere on the dial can be
+ * compared against a mark without either side knowing about the other's convention.
+ */
+export declare function angleAtPoint(center: ClockPoint, point: ClockPoint): number;
+/**
+ * How far a point is from the centre, for a dial with two rings.
+ *
+ * A twenty-four hour clock writes 1–12 on the outside and 13–00 on the inside, and which
+ * ring a touch landed on is the only thing that tells them apart.
+ */
+export declare function distanceFrom(center: ClockPoint, point: ClockPoint): number;

package/dist/utils/clock.d.ts

@@ -0,0 +1,45 @@
+/** A point on the dial, in the view's own coordinates. */
+export type ClockPoint = {
+    x: number;
+    y: number;
+};
+/**
+ * Where a value sits on the dial, in degrees **clockwise from twelve o'clock**.
+ *
+ * The quarter turn is baked in here rather than at every call site, for `polarPoint`'s
+ * reason: a clock's first mark is at the top, and so is a reader's eye.
+ *
+ * `count` is how many marks go all the way round — 12 for the hours, 60 for the minutes —
+ * and the value wraps, so hour 12 and hour 0 are the same place.
+ */
+export declare function clockAngle(value: number, count: number): number;
+/**
+ * The mark nearest that angle — the inverse, rounded.
+ *
+ * Rounded rather than floored: a finger halfway between two marks belongs to the one it is
+ * nearer, and a dial that always rounded down would feel like it lagged the touch by half a
+ * step.
+ */
+export declare function valueAtAngle(angle: number, count: number): number;
+/**
+ * A point at `angle` on a circle, **clockwise from twelve o'clock**.
+ *
+ * Screen coordinates grow downwards, which is why the cosine is subtracted rather than
+ * added: twelve o'clock is *above* the centre, and a plus there puts it below.
+ */
+export declare function clockPoint(center: ClockPoint, radius: number, angle: number): ClockPoint;
+/**
+ * Which way a point lies from the centre, in the same degrees `clockAngle` speaks.
+ *
+ * `atan2` measures from three o'clock and anticlockwise; the quarter turn and the sign here
+ * are what turn that into "clockwise from twelve", so a touch anywhere on the dial can be
+ * compared against a mark without either side knowing about the other's convention.
+ */
+export declare function angleAtPoint(center: ClockPoint, point: ClockPoint): number;
+/**
+ * How far a point is from the centre, for a dial with two rings.
+ *
+ * A twenty-four hour clock writes 1–12 on the outside and 13–00 on the inside, and which
+ * ring a touch landed on is the only thing that tells them apart.
+ */
+export declare function distanceFrom(center: ClockPoint, point: ClockPoint): number;

package/dist/utils/colors.d.cts

@@ -0,0 +1,22 @@
+export type Rgb = [number, number, number];
+export type Oklab = [number, number, number];
+/** Callers that can give a better error than `hexToRgb`'s test the value first. */
+export declare function isHex(value: string): boolean;
+export declare function hexToRgb(hex: string): Rgb;
+export declare function rgbToHex([r, g, b]: Rgb): string;
+export declare function rgbToOklab([r, g, b]: Rgb): Oklab;
+export declare function oklabToRgb([L, a, b]: Oklab): Rgb;
+/** `oklch()` from the design source, converted once — React Native cannot parse it. */
+export declare function oklchToHex(lightness: number, chroma: number, hueDeg: number): string;
+/**
+ * `color-mix(in oklab, base (1 - amount), other amount)`.
+ * Mixing in OKLab rather than sRGB is what keeps blends from turning grey.
+ */
+export declare function mix(base: string, other: string, amount: number): string;
+/** `color-mix(in oklab, colour X%, transparent)` — RN needs the rgba() form. */
+export declare function alpha(hex: string, amount: number): string;
+export declare function lightnessOf(hex: string): number;
+/** Picks the readable text colour on `hex` between two primitives. */
+export declare function contrastOn(hex: string, light: string, dark: string): string;
+/** WCAG 2.x contrast ratio, 1 to 21. Used by the CI contrast guard. */
+export declare function contrastRatio(a: string, b: string): number;

package/dist/utils/colors.d.ts

@@ -0,0 +1,22 @@
+export type Rgb = [number, number, number];
+export type Oklab = [number, number, number];
+/** Callers that can give a better error than `hexToRgb`'s test the value first. */
+export declare function isHex(value: string): boolean;
+export declare function hexToRgb(hex: string): Rgb;
+export declare function rgbToHex([r, g, b]: Rgb): string;
+export declare function rgbToOklab([r, g, b]: Rgb): Oklab;
+export declare function oklabToRgb([L, a, b]: Oklab): Rgb;
+/** `oklch()` from the design source, converted once — React Native cannot parse it. */
+export declare function oklchToHex(lightness: number, chroma: number, hueDeg: number): string;
+/**
+ * `color-mix(in oklab, base (1 - amount), other amount)`.
+ * Mixing in OKLab rather than sRGB is what keeps blends from turning grey.
+ */
+export declare function mix(base: string, other: string, amount: number): string;
+/** `color-mix(in oklab, colour X%, transparent)` — RN needs the rgba() form. */
+export declare function alpha(hex: string, amount: number): string;
+export declare function lightnessOf(hex: string): number;
+/** Picks the readable text colour on `hex` between two primitives. */
+export declare function contrastOn(hex: string, light: string, dark: string): string;
+/** WCAG 2.x contrast ratio, 1 to 21. Used by the CI contrast guard. */
+export declare function contrastRatio(a: string, b: string): number;

package/dist/utils/date-range.d.cts

@@ -0,0 +1,43 @@
+/** Two ends, either of which may be missing while the other is not. */
+export type DateRange = {
+    start: Date | null;
+    end: Date | null;
+};
+/** Where a day falls in a range — what a cell needs to know to draw itself. */
+export type RangePosition = 'none' | 'start' | 'end' | 'middle' | 'single';
+/** Nothing chosen, as one shared object — a new `{}` per call re-renders forty-two cells. */
+export declare const EMPTY_RANGE: DateRange;
+/**
+ * The range after pressing a day.
+ *
+ * Three cases, and the third is the one every range picker gets wrong:
+ *
+ * 1. **Nothing, or both ends already set** → this day becomes the start, and the end is
+ *    cleared. A reader who has a range and presses a day is starting a new one; asking them
+ *    to clear it first is asking them to find a control that should not need to exist.
+ * 2. **A start and no end, and the day is on or after it** → this day becomes the end.
+ * 3. **A start and no end, and the day is *before* it** → this day becomes the **start**
+ *    rather than an end that precedes it. A backwards range is not a range, and silently
+ *    swapping the two would move a bound the reader did not touch.
+ *
+ * Pressing the start again gives a single-day range rather than nothing: a one-night stay
+ * and a one-day event are real, and a range picker that cannot express them is one a caller
+ * has to work around.
+ *
+ * Every date is taken to midnight, for `startOfDay`'s reason: a `Date` is an instant and a
+ * calendar day is not, and a range whose ends carry the moment they were pressed compares
+ * unequal to the same two days written by the caller.
+ */
+export declare function nextRange(current: DateRange, day: Date): DateRange;
+/** Whether a day is inside the range, ends included. A half range contains only its start. */
+export declare function isInRange(day: Date, range: DateRange): boolean;
+/**
+ * Where a day sits in the range, which is the whole of what a cell needs.
+ *
+ * `single` is its own answer rather than "start and end at once": the two ends of a one-day
+ * range are the same cell, and a cell told it is both would have to decide which half of its
+ * own shape to draw.
+ */
+export declare function rangePosition(day: Date, range: DateRange): RangePosition;
+/** Whether two ranges name the same two days, either of which may be absent. */
+export declare function isSameRange(a: DateRange, b: DateRange): boolean;

package/dist/utils/date-range.d.ts

@@ -0,0 +1,43 @@
+/** Two ends, either of which may be missing while the other is not. */
+export type DateRange = {
+    start: Date | null;
+    end: Date | null;
+};
+/** Where a day falls in a range — what a cell needs to know to draw itself. */
+export type RangePosition = 'none' | 'start' | 'end' | 'middle' | 'single';
+/** Nothing chosen, as one shared object — a new `{}` per call re-renders forty-two cells. */
+export declare const EMPTY_RANGE: DateRange;
+/**
+ * The range after pressing a day.
+ *
+ * Three cases, and the third is the one every range picker gets wrong:
+ *
+ * 1. **Nothing, or both ends already set** → this day becomes the start, and the end is
+ *    cleared. A reader who has a range and presses a day is starting a new one; asking them
+ *    to clear it first is asking them to find a control that should not need to exist.
+ * 2. **A start and no end, and the day is on or after it** → this day becomes the end.
+ * 3. **A start and no end, and the day is *before* it** → this day becomes the **start**
+ *    rather than an end that precedes it. A backwards range is not a range, and silently
+ *    swapping the two would move a bound the reader did not touch.
+ *
+ * Pressing the start again gives a single-day range rather than nothing: a one-night stay
+ * and a one-day event are real, and a range picker that cannot express them is one a caller
+ * has to work around.
+ *
+ * Every date is taken to midnight, for `startOfDay`'s reason: a `Date` is an instant and a
+ * calendar day is not, and a range whose ends carry the moment they were pressed compares
+ * unequal to the same two days written by the caller.
+ */
+export declare function nextRange(current: DateRange, day: Date): DateRange;
+/** Whether a day is inside the range, ends included. A half range contains only its start. */
+export declare function isInRange(day: Date, range: DateRange): boolean;
+/**
+ * Where a day sits in the range, which is the whole of what a cell needs.
+ *
+ * `single` is its own answer rather than "start and end at once": the two ends of a one-day
+ * range are the same cell, and a cell told it is both would have to decide which half of its
+ * own shape to draw.
+ */
+export declare function rangePosition(day: Date, range: DateRange): RangePosition;
+/** Whether two ranges name the same two days, either of which may be absent. */
+export declare function isSameRange(a: DateRange, b: DateRange): boolean;