@ng-native/components 0.0.1 → 0.1.1

package/dist/pressable.d.ts

@@ -0,0 +1,220 @@
+import type { Insets, TouchEvent } from './events.ts';
+import { ViewBase } from './view-base.ts';
+import * as i0 from "@angular/core";
+/** What a press handler receives: RN's `{nativeEvent}` shape, passed straight through. */
+export type PressEvent = TouchEvent;
+/**
+ * Android's ripple, drawn natively. `foreground` paints it over the content rather than behind.
+ */
+export interface AndroidRipple {
+    readonly color?: string | number;
+    readonly borderless?: boolean;
+    readonly radius?: number;
+    readonly foreground?: boolean;
+}
+/** What `rippleDrawable` builds: Android's `RippleAndroid` drawable description. */
+interface RippleDrawable {
+    readonly type: 'RippleAndroid';
+    readonly color: unknown;
+    readonly borderless: boolean;
+    readonly rippleRadius: number | undefined;
+}
+/**
+ * The press machine, and the base of every primitive that takes a touch.
+ *
+ * It declares no host bindings of its own, because `Text` extends it and a host binding runs on
+ * every element that carries it, on every pass. The controls bind theirs through `ControlBase`.
+ */
+export declare abstract class TouchableBase extends ViewBase {
+    /** Ignore touches entirely. */
+    readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    /**
+     * How far outside the hit area a touch may wander before the press is cancelled. Native's
+     * `hitSlop` grows the area a touch can start in; this grows the area it may move within.
+     */
+    readonly pressRetentionOffset: import("@angular/core").InputSignal<number | Insets | undefined>;
+    /** Milliseconds a touch must be held before `(longPress)` fires. */
+    readonly delayLongPress: import("@angular/core").InputSignalWithTransform<number, unknown>;
+    /** Milliseconds between the touch landing and `(pressIn)`, so a scroll can start first. */
+    readonly delayPressIn: import("@angular/core").InputSignalWithTransform<number, unknown>;
+    /** Milliseconds between the touch lifting and `(pressOut)`. */
+    readonly delayPressOut: import("@angular/core").InputSignalWithTransform<number, unknown>;
+    /** The pressed state lasts at least this long, so a quick tap still shows it. */
+    readonly minPressDuration: import("@angular/core").InputSignalWithTransform<number, unknown>;
+    /** Whether a scrolling ancestor may take the gesture away mid-press. */
+    readonly cancelable: import("@angular/core").InputSignalWithTransform<boolean, unknown>;
+    /** Android: a native ripple on press. */
+    readonly androidRipple: import("@angular/core").InputSignal<AndroidRipple | undefined>;
+    /** The touch lifted inside the press area. Not fired after a `(longPress)` that has a listener. */
+    readonly press: import("@angular/core").OutputEmitterRef<TouchEvent>;
+    readonly pressIn: import("@angular/core").OutputEmitterRef<TouchEvent>;
+    readonly pressOut: import("@angular/core").OutputEmitterRef<TouchEvent>;
+    /**
+     * The touch has been held for `delayLongPress`. With no listener there is no long press, as in
+     * React Native, so a slow tap is still a `press`.
+     */
+    readonly longPress: import("@angular/core").OutputEmitterRef<TouchEvent>;
+    /** Whether a press is in progress, for the pressed look. */
+    readonly pressed: import("@angular/core").WritableSignal<boolean>;
+    /**
+     * Whether a pointer is over the control, which on this platform means an iPad with a trackpad
+     * or a mouse. Always false on a phone, because a phone never sends a pointer event.
+     *
+     * Opted into by exactly the elements that opt into being measured, which is the same question
+     * asked twice: is this a control, or is it a piece of text that merely inherits the machinery.
+     * Registering on everything was the first attempt and put two props on every paragraph on
+     * screen, which is the most numerous node in an app paying for a state a label cannot use.
+     */
+    readonly hovered: import("@angular/core").WritableSignal<boolean>;
+    protected rippleBackground(): RippleDrawable | undefined;
+    protected rippleForeground(): RippleDrawable | undefined;
+    private drawn;
+    private drawable;
+    /**
+     * The drawable description Android's `ReactDrawableHelper` reads.
+     *
+     * `color` goes through the engine the way every other colour prop does, and has to: the helper
+     * switches on the value's runtime type and takes a number or a platform-colour map, and anything
+     * else - a `'#ff0000'` written at the call site, say - falls through to `null` and the ripple
+     * draws in the theme's own `colorControlHighlight` instead. Nothing is logged and nothing throws,
+     * so the ripple appears and is simply the wrong colour. RN's own `TouchableNativeFeedback.Ripple`
+     * calls `processColor` here for the same reason.
+     */
+    private rippleDrawable;
+    /** Where the touch started, so a drag can be told apart from a tap. */
+    private origin;
+    /** The control's own size, from its last layout. Null until it has been measured once. */
+    private size;
+    private cancelled;
+    private longPressed;
+    /** How many `(longPress)` listeners there are; the long-press clock only runs with one. */
+    private longPressListeners;
+    private pressedAt;
+    private pressInTimer;
+    private longPressTimer;
+    private pressOutTimer;
+    constructor();
+    /** Called as a press starts and ends, for a subclass that shows it natively. `Text` does. */
+    protected pressedChanged(_pressed: boolean): void;
+    /** Whether a touch starting on this node should be claimed. `Text` narrows it. */
+    protected claims(): boolean;
+    /**
+     * Whether the control's size should be tracked. Native only measures a view that asks, so
+     * this must not be true for every `<text>`: a pressable text opts in, a label never does.
+     */
+    protected measures(): boolean;
+    /**
+     * Whether a touch this far from where it started is still on the control.
+     *
+     * Distance from the origin is the wrong question on anything large: a thumb tap on a full-width
+     * button easily travels twenty points without ever leaving it, and cancelling there reads as
+     * "the button doesn't work", intermittently and only for some people. What matters is whether
+     * the finger is still within the control plus its hit slop, plus the slop RN allows.
+     *
+     * The touch began somewhere inside the control but we do not know where, so the bound is the
+     * full extent rather than half of it. That errs towards keeping the press, which is the right
+     * way to be wrong: a press that survives a drag the user meant as a scroll is a smaller sin
+     * than a tap that does nothing.
+     */
+    private stillOnControl;
+    /**
+     * A lifecycle hook rather than `inject(DestroyRef).onDestroy`: Angular registers a hook once per
+     * directive type, where the callback was a closure and a lookup for every instance - and every
+     * `<text>` on screen is one.
+     */
+    ngOnDestroy(): void;
+    private stopResponding;
+    private stopLayout;
+    private stopHover;
+    ngOnInit(): void;
+    ngOnChanges(): void;
+    /**
+     * Join the responder negotiation, once this is something a touch can press.
+     *
+     * Behind `measures()` for the same reason as layout and hover: a `<text>` is the commonest node
+     * on screen and almost never a control, and registering every one cost a handler object, six
+     * closures and a responder entry apiece for a touch it would have refused anyway.
+     */
+    private respondIfNeeded;
+    /**
+     * `onLayout` is opted into by the engine as soon as something listens for it, which is the only
+     * way the native side reports a view's size at all, and the reason it is only asked for once
+     * `measures()` says so - a `<text>` answers that from an input, and most of them say no.
+     *
+     * Called from the lifecycle rather than watched by an effect. An effect per element is an
+     * allocation and a scheduler entry for every pressable and every piece of text on screen, to
+     * notice a change these two hooks already see.
+     */
+    /**
+     * Hover, on the same terms and behind the same question.
+     *
+     * Fabric will not dispatch a pointer event to a view whose props have not asked for one, and
+     * the engine writes those props when something listens - so listening is the whole opt-in. The
+     * gate is `measures()`, which is not what its name is about but is the right question underneath
+     * it: is this an actual control, or a piece of text that merely inherits the machinery. A label
+     * says no, and two props on every paragraph on screen is not a cost worth paying for a hover
+     * state a label has no use for.
+     *
+     * Never true on a phone, which sends no pointer events at all. This is the one thing an iPad
+     * with a trackpad has that a phone does not.
+     */
+    private hoverIfNeeded;
+    private measureIfNeeded;
+    private onGrant;
+    /** `pressIn`, and the long-press clock starts from here. */
+    private activate;
+    private onMove;
+    private onRelease;
+    private onTerminate;
+    /** `pressOut`, no sooner than `minPressDuration` after `pressIn` and after `delayPressOut`. */
+    private deactivate;
+    private clearTimers;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TouchableBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TouchableBase, never, never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "pressRetentionOffset": { "alias": "pressRetentionOffset"; "required": false; "isSignal": true; }; "delayLongPress": { "alias": "delayLongPress"; "required": false; "isSignal": true; }; "delayPressIn": { "alias": "delayPressIn"; "required": false; "isSignal": true; }; "delayPressOut": { "alias": "delayPressOut"; "required": false; "isSignal": true; }; "minPressDuration": { "alias": "minPressDuration"; "required": false; "isSignal": true; }; "cancelable": { "alias": "cancelable"; "required": false; "isSignal": true; }; "androidRipple": { "alias": "android_ripple"; "required": false; "isSignal": true; }; }, { "press": "press"; "pressIn": "pressIn"; "pressOut": "pressOut"; "longPress": "longPress"; }, never, never, true, never>;
+}
+/**
+ * A touchable that is a control: `Pressable`, `TouchableOpacity` and `PressBehavior`.
+ *
+ * The three host bindings every control needs live here rather than on `TouchableBase`, which
+ * `Text` extends: the state that follows `disabled`, and the Android ripple. Controls are few
+ * enough on a screen to pay for a binding on every pass; texts are not.
+ */
+export declare abstract class ControlBase extends TouchableBase {
+    static ɵfac: i0.ɵɵFactoryDeclaration<ControlBase, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ControlBase, never, never, {}, {}, never, never, true, never>;
+}
+/**
+ * The press machine on its own, for a component that wants to be pressable rather than to
+ * contain something that is.
+ *
+ * No selector: this is only ever a `hostDirectives` entry. A component listing it gets the whole
+ * of `TouchableBase` on its own host node - the responder negotiation, the press rectangle, the
+ * delays and the long-press timer - instead of wrapping a `<pressable>` and paying for a second
+ * native view.
+ *
+ * It provides `TouchableBase`, so a primitive on the same node can `inject(TouchableBase)` and
+ * read `pressed` without caring whether it landed on this or on a real `<pressable>`.
+ */
+export declare class PressBehavior extends ControlBase {
+    protected accessibleByDefault(): boolean;
+    protected focusableByDefault(): boolean;
+    protected disabledForAccessibility(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PressBehavior, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<PressBehavior, never, never, {}, {}, never, never, true, never>;
+}
+/**
+ * A view that responds to presses. RN's `Pressable`, with the same configuration: hit slop,
+ * retention offset, press-in and press-out delays, long press, and an Android ripple.
+ *
+ * `pressed` is a public signal, so a template can style from it through a template reference:
+ * `<pressable #p [style.opacity]="p.pressed() ? 0.5 : 1">`.
+ */
+export declare class Pressable extends ControlBase {
+    /** `Pressable.js`: a control is an accessibility element, and focusable, unless refused. */
+    protected accessibleByDefault(): boolean;
+    protected focusableByDefault(): boolean;
+    protected disabledForAccessibility(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<Pressable, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<Pressable, "pressable", ["pressable"], {}, {}, never, never, true, never>;
+}
+export {};