panelui-native 0.81.0 → 0.82.0

package/lib/typescript/src/components/slide-button/index.d.ts

@@ -0,0 +1,317 @@
+/**
+ * SlideButton — drag across to confirm, with the distance drawn on the button.
+ *
+ * ```tsx
+ * <SlideButton onComplete={ship}>
+ *   <SlideButton.Label>Slide to ship</SlideButton.Label>
+ * </SlideButton>
+ * ```
+ *
+ * For an action worth a moment's deliberation, where a hold is the wrong
+ * shape. A hold asks for time and shows a clock; a slide asks for a movement
+ * and shows a distance — so the reader can go as fast as they like, and still
+ * cannot arrive by tapping. Pair it with [ProgressButton](../progress-button)
+ * rather than choosing between them: the hold suits an action that should feel
+ * expensive, the slide one that should feel deliberate.
+ *
+ * ## The far end is the promise
+ *
+ * Nothing fires until the thumb clears `threshold`, which defaults to nine
+ * tenths of the rail. Released short, it springs home and the fill goes with
+ * it. Released short but travelling, it is honoured — a flick that had
+ * plainly committed is not worth refusing on a technicality, and the velocity
+ * is projected forward to decide.
+ *
+ * ## How it is drawn
+ *
+ * A track, a fill that follows the thumb, and a label that fades as the thumb
+ * reaches it. The label fades rather than sliding out of the way because the
+ * thumb is about to be where the label is, and two things moving toward each
+ * other at different speeds reads as a collision.
+ *
+ * The thumb is translated and the fill's width animated, both on the UI thread
+ * off one shared value, so a drag never re-renders React.
+ *
+ * ## Sliding without a finger
+ *
+ * A drag is not available to a screen reader, so the rail is also a button:
+ * it takes an `activate` accessibility action and completes on it. This is not
+ * a lesser path bolted on — a confirmation control that can only be reached by
+ * dragging is a confirmation control some people cannot use.
+ */
+import { type ReactNode } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { type SharedValue } from 'react-native-reanimated';
+import { type VariantProps } from 'tailwind-variants';
+declare const slideButtonVariants: import("tailwind-variants").TVReturnType<{
+    variant: {
+        secondary: {
+            label: string;
+            fill: string;
+        };
+        destructive: {
+            label: string;
+            fill: string;
+        };
+        success: {
+            label: string;
+            fill: string;
+        };
+    };
+    size: {
+        sm: {
+            root: string;
+            label: string;
+        };
+        md: {
+            root: string;
+            label: string;
+        };
+        lg: {
+            root: string;
+            label: string;
+        };
+    };
+    fullWidth: {
+        true: {
+            root: string;
+        };
+    };
+    disabled: {
+        true: {
+            root: string;
+        };
+    };
+}, {
+    root: string;
+    /**
+     * The ground the handle has covered.
+     *
+     * Inset on every side by the same padding the handle sits in, so at rest
+     * it is exactly zero wide and there is nothing to see — a trail with a
+     * sliver of colour in it before anything has been dragged is a control
+     * that looks part-finished.
+     */
+    fill: string;
+    /** The label, centred in the rail rather than in the space beside it. */
+    label: string;
+    /**
+     * The draggable handle. Wider than it is tall, so it reads as something to
+     * push rather than as a dot that happens to be on a track — and the extra
+     * width is what gives the chevron room to sit in without crowding the
+     * curve at either end.
+     */
+    thumb: string;
+    /** What the thumb holds — a chevron at rest, a tick once it has arrived. */
+    thumbContent: string;
+}, undefined, {
+    variant: {
+        secondary: {
+            label: string;
+            fill: string;
+        };
+        destructive: {
+            label: string;
+            fill: string;
+        };
+        success: {
+            label: string;
+            fill: string;
+        };
+    };
+    size: {
+        sm: {
+            root: string;
+            label: string;
+        };
+        md: {
+            root: string;
+            label: string;
+        };
+        lg: {
+            root: string;
+            label: string;
+        };
+    };
+    fullWidth: {
+        true: {
+            root: string;
+        };
+    };
+    disabled: {
+        true: {
+            root: string;
+        };
+    };
+}, {
+    root: string;
+    /**
+     * The ground the handle has covered.
+     *
+     * Inset on every side by the same padding the handle sits in, so at rest
+     * it is exactly zero wide and there is nothing to see — a trail with a
+     * sliver of colour in it before anything has been dragged is a control
+     * that looks part-finished.
+     */
+    fill: string;
+    /** The label, centred in the rail rather than in the space beside it. */
+    label: string;
+    /**
+     * The draggable handle. Wider than it is tall, so it reads as something to
+     * push rather than as a dot that happens to be on a track — and the extra
+     * width is what gives the chevron room to sit in without crowding the
+     * curve at either end.
+     */
+    thumb: string;
+    /** What the thumb holds — a chevron at rest, a tick once it has arrived. */
+    thumbContent: string;
+}, import("tailwind-variants").TVReturnType<{
+    variant: {
+        secondary: {
+            label: string;
+            fill: string;
+        };
+        destructive: {
+            label: string;
+            fill: string;
+        };
+        success: {
+            label: string;
+            fill: string;
+        };
+    };
+    size: {
+        sm: {
+            root: string;
+            label: string;
+        };
+        md: {
+            root: string;
+            label: string;
+        };
+        lg: {
+            root: string;
+            label: string;
+        };
+    };
+    fullWidth: {
+        true: {
+            root: string;
+        };
+    };
+    disabled: {
+        true: {
+            root: string;
+        };
+    };
+}, {
+    root: string;
+    /**
+     * The ground the handle has covered.
+     *
+     * Inset on every side by the same padding the handle sits in, so at rest
+     * it is exactly zero wide and there is nothing to see — a trail with a
+     * sliver of colour in it before anything has been dragged is a control
+     * that looks part-finished.
+     */
+    fill: string;
+    /** The label, centred in the rail rather than in the space beside it. */
+    label: string;
+    /**
+     * The draggable handle. Wider than it is tall, so it reads as something to
+     * push rather than as a dot that happens to be on a track — and the extra
+     * width is what gives the chevron room to sit in without crowding the
+     * curve at either end.
+     */
+    thumb: string;
+    /** What the thumb holds — a chevron at rest, a tick once it has arrived. */
+    thumbContent: string;
+}, undefined, unknown, unknown, undefined>>;
+type SlideButtonVariantProps = VariantProps<typeof slideButtonVariants>;
+/** How a slide button looks. */
+export type SlideButtonVariant = NonNullable<SlideButtonVariantProps['variant']>;
+/** How big a slide button is. */
+export type SlideButtonSize = NonNullable<SlideButtonVariantProps['size']>;
+/** The slide's progress and whether it has completed, for a custom part. */
+export declare function useSlideButton(): {
+    progress: SharedValue<number>;
+    completed: boolean;
+};
+export interface SlideButtonProps extends Omit<ViewProps, 'children'>, Omit<SlideButtonVariantProps, 'disabled'> {
+    /** Extra classes for the rail — the box the button occupies in your layout. */
+    className?: string;
+    /**
+     * The fraction of the rail the thumb has to cover for the slide to count.
+     * Defaults to `0.9`, clamped to between `0.1` and `1`.
+     */
+    threshold?: number;
+    /** Fires once the thumb has been taken past the threshold and released. */
+    onComplete?: () => void;
+    /** Fires whenever the completed state changes, including on a reset. */
+    onCompletedChange?: (completed: boolean) => void;
+    /** Controlled completion. Leave unset to let the button own it. */
+    completed?: boolean;
+    /** Return to the unslid state after `autoResetDelay`. */
+    autoReset?: boolean;
+    /** Milliseconds to stay completed before resetting. Defaults to `1000`. */
+    autoResetDelay?: number;
+    /** Dim the button and refuse the drag outright. */
+    disabled?: boolean;
+    /**
+     * A tick as the thumb arms and a knock when it commits. Off by default,
+     * because a control used several times in a row is one a reader may not want
+     * buzzing every time.
+     */
+    haptics?: boolean;
+    /**
+     * What a screen reader is told the button does, in the imperative — it is
+     * announced as the action of a button rather than as an instruction to drag,
+     * since dragging is not available there. Defaults to `'Confirm'`.
+     */
+    accessibilityActionLabel?: string;
+    children?: ReactNode;
+}
+export interface SlideButtonLabelProps extends ViewProps {
+    /** Extra classes for the label's text. */
+    className?: string;
+    children?: ReactNode;
+}
+/**
+ * What the button says.
+ *
+ * Centred in the whole rail rather than in the space beside the thumb, and it
+ * does not move or fade — the thumb simply passes over it, and the rail's own
+ * clip takes the rest.
+ *
+ * Fading it out was worse in a way that only shows on a device: the label
+ * disappears while there is still most of a rail left to cross, so the button
+ * spends the second half of the gesture saying nothing at all. Covered
+ * instead, the text is legible right up to the moment the handle reaches it,
+ * which is also the moment the reader no longer needs it.
+ */
+declare function SlideButtonLabel({ className, style, children, ...props }: SlideButtonLabelProps): import("react").JSX.Element;
+declare namespace SlideButtonLabel {
+    var displayName: string;
+}
+export interface SlideButtonThumbProps extends ViewProps {
+    /** Extra classes for the thumb — its fill and shape. Its size comes from `size`. */
+    className?: string;
+    /** Replaces the chevron. The tick that lands on completion is unaffected. */
+    children?: ReactNode;
+}
+/**
+ * The disc the finger moves.
+ *
+ * Translated rather than laid out at a position, so a drag costs no layout
+ * pass. It sits absolutely at the rail's leading inset and travels from there.
+ */
+declare function SlideButtonThumb({ className, style, children, ...props }: SlideButtonThumbProps): import("react").JSX.Element;
+declare namespace SlideButtonThumb {
+    var displayName: string;
+}
+export declare const SlideButton: import("react").ForwardRefExoticComponent<SlideButtonProps & import("react").RefAttributes<View>> & {
+    Label: typeof SlideButtonLabel;
+    Thumb: typeof SlideButtonThumb;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/components/slide-button/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/components/slide-button/index.tsx"],"names":[],"mappings":"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"}

package/lib/typescript/src/components/slide-button/slide-button-track.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The arithmetic behind a slide, kept out of the component so it can be tested
+ * without a renderer — the same split `progress-button-hold` uses.
+ *
+ * The gesture's worklets carry their own copies of these three lines rather
+ * than calling in here. A pan handler is the one place in the library that
+ * cannot afford a surprise: a worklet reaching across a module boundary for a
+ * helper that reaches across again for another is a chain with more ways to go
+ * wrong than the arithmetic is long. What lives here is the definition, and
+ * the tests hold the component to it.
+ */
+/** The fraction of the rail that has to be covered for the slide to count. */
+export declare const DEFAULT_THRESHOLD = 0.9;
+/** Milliseconds before an `autoReset` button offers itself again. */
+export declare const DEFAULT_AUTO_RESET_DELAY = 1000;
+/**
+ * Seconds of fling counted as distance already travelled.
+ *
+ * A slide released at speed near the end was going to arrive, and stopping it
+ * dead a few points short is the control arguing with a gesture that had
+ * plainly committed. Small, because the reverse mistake — a flick from
+ * halfway completing an action the reader was only playing with — is the
+ * worse one.
+ */
+export declare const VELOCITY_LOOKAHEAD = 0.12;
+/**
+ * How far past the end the thumb can be pushed, as a divisor on the overshoot.
+ *
+ * The rail has an end and the finger does not, so the distance past it is
+ * given back at an eighth. Without this the thumb parks under the finger with
+ * a gap opening behind it, which reads as the control having come loose.
+ */
+export declare const OVERSHOOT_FRICTION = 8;
+/**
+ * A threshold that cannot produce a button which fires on contact.
+ *
+ * Zero would complete the moment the thumb moved, which is a button with a
+ * gesture in front of it rather than a slide. One is allowed: it means the
+ * thumb has to reach the far end exactly, which is a legitimate ask for
+ * something destructive.
+ */
+export declare function resolveThreshold(threshold: number | undefined): number;
+/**
+ * How far along the rail the thumb has been dragged, as `0` to `1`.
+ *
+ * `travel` is the rail minus the thumb — the distance the thumb's own leading
+ * edge can actually cover. Measuring against the full rail width instead would
+ * make the last thumb-width of the track unreachable, so a slide could never
+ * finish.
+ */
+export declare function progressFor(translation: number, travel: number): number;
+/**
+ * The thumb's offset in points, rubber-banded once it passes the end.
+ *
+ * Before the end it follows the finger exactly. There is no easing on the way
+ * out, because a thumb that lags its own finger reads as a slow app rather
+ * than as a heavy control.
+ */
+export declare function offsetFor(translation: number, travel: number): number;
+/**
+ * Whether a released slide should be honoured.
+ *
+ * Where it got to, plus where its speed was about to carry it. A slide let go
+ * short and still is refused; a slide let go short and travelling is not,
+ * because the reader has already made the movement that finishes it.
+ */
+export declare function isCommitted(progress: number, velocity: number, travel: number, threshold: number): boolean;
+/** Keeps a number inside a range. Exported because the tests read it. */
+export declare function clamp(value: number, low: number, high: number): number;
+//# sourceMappingURL=slide-button-track.d.ts.map

package/lib/typescript/src/components/slide-button/slide-button-track.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"slide-button-track.d.ts","sourceRoot":"","sources":["../../../../../src/components/slide-button/slide-button-track.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,qEAAqE;AACrE,eAAO,MAAM,wBAAwB,OAAO,CAAC;AAE7C;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,OAAO,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGtE;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGvE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAKrE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAIT;AAED,yEAAyE;AACzE,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtE"}