@webority/mobile-ui 0.9.1 → 0.11.0

package/lib/typescript/module/hooks/useRefreshControl.d.ts

@@ -0,0 +1,75 @@
+import type React from 'react';
+import type { AccessibilityActionEvent, RefreshControlProps } from 'react-native';
+import type { HapticType } from '../utils/hapticUtils.js';
+export type UseRefreshControlLabels = {
+    /** Name of the refresh accessibility action. Default `'Refresh'`. */
+    refresh?: string;
+    /** Spoken when a button or accessibility-action refresh starts. Default `'Refreshing'`. */
+    refreshing?: string;
+    /** Spoken when that refresh ends. Default `'Updated'`. */
+    refreshed?: string;
+};
+export type UseRefreshControlOptions = {
+    /**
+     * Reloads the data. Return the promise (an RTK Query `refetch` already does)
+     * and the spinner stays until it settles. A rejection is logged and ends the
+     * spinner; show the user a curated message from the call itself.
+     */
+    onRefresh: () => unknown;
+    /**
+     * The screen's own loading flag, when the data is already tracked elsewhere.
+     * The spinner shows while this is true or a refresh started here is running.
+     */
+    refreshing?: boolean;
+    /**
+     * Haptic when a pull starts the refresh. Default: `'gestureStart'` on Android
+     * and none on iOS or web (no iOS haptic until a device check shows whether the
+     * system already taps). `false` turns it off; a type fires on every native
+     * platform.
+     */
+    haptic?: HapticType | false;
+    /**
+     * iOS only: the line under the spinner, for what changed ("Updated 2 minutes
+     * ago"). Never use it to explain how to refresh.
+     */
+    title?: string;
+    /** A refresh started here keeps the spinner at least this long. Default 400. */
+    minVisibleMs?: number;
+    labels?: UseRefreshControlLabels;
+};
+export type UseRefreshControlResult = {
+    /** Pass as `refreshControl` to a FlatList, SectionList, ScrollView or KeyboardAwareScrollView. */
+    refreshControl: React.ReactElement<RefreshControlProps>;
+    /** True while the spinner shows. Give an AppBar action or IconButton this as `loading`. */
+    refreshing: boolean;
+    /**
+     * Starts a refresh without a pull: the single-pointer path for an AppBar
+     * action or a button. Ignored while one is running. Fires no haptic (the
+     * button gives its own) and announces the start and the end. Never rejects.
+     */
+    refresh: () => Promise<void>;
+    /** Spread on a focusable element so a screen reader offers Refresh in its actions menu. */
+    accessibilityProps: {
+        accessibilityActions: {
+            name: 'refresh';
+            label: string;
+        }[];
+        onAccessibilityAction: (event: AccessibilityActionEvent) => void;
+    };
+};
+/**
+ * Themed pull to refresh plus the way to refresh without pulling.
+ *
+ * React Native's RefreshControl reports only that a refresh started, never that
+ * the pull crossed the trigger, so the haptic fires at that start. Web draws no
+ * pull at all, and a swipe is not available to everyone: pair the control with
+ * an AppBar action that calls `refresh()` so a person on any platform, or with a
+ * screen reader or keyboard, can reload.
+ *
+ *   const { refreshControl, refresh, refreshing } = useRefreshControl({ onRefresh: refetch });
+ *   <FlatList refreshControl={refreshControl} ... />
+ *   <AppBar rightActions={[{ icon: <AppIcon name="refresh" />, onPress: refresh,
+ *     accessibilityLabel: 'Refresh' }]} />
+ */
+export declare const useRefreshControl: (options: UseRefreshControlOptions) => UseRefreshControlResult;
+//# sourceMappingURL=useRefreshControl.d.ts.map

package/lib/typescript/module/hooks/useScrollDirection.d.ts

@@ -0,0 +1,21 @@
+import type { NativeScrollEvent, NativeSyntheticEvent } from 'react-native';
+export type ScrollDirection = 'up' | 'down' | 'idle';
+export type UseScrollDirectionOptions = {
+    /** Points of travel in one direction before the direction flips. Default 8. */
+    threshold?: number;
+};
+export type UseScrollDirectionResult = {
+    direction: ScrollDirection;
+    onScroll: (e: NativeSyntheticEvent<NativeScrollEvent>) => void;
+};
+/**
+ * Direction of the user's scroll, for bars that hide on scroll down and return
+ * on scroll up. `'idle'` until the list has moved past the top; it returns to
+ * `'idle'` when the offset reaches the top. Rubber-band overscroll at either
+ * end is clamped away, so a bounce never reads as a reversal. State changes
+ * only when the direction changes, not on every scroll event.
+ *
+ * Pass `onScroll` to a ScrollView or FlatList with `scrollEventThrottle={16}`.
+ */
+export declare const useScrollDirection: (options?: UseScrollDirectionOptions) => UseScrollDirectionResult;
+//# sourceMappingURL=useScrollDirection.d.ts.map

package/lib/typescript/module/index.d.ts

@@ -3,14 +3,14 @@ export type { AppIconName, AppIconProps, AppIconSize, CuratedIconName, IconName,
 export { APP_ICON_SIZES, AppIcon, CURATED_ICON_NAMES, defaultIcons, ICON_NAMES, ICONSAX_SUFFIX, renderSlotIcon } from './components/AppIcon/index.js';
 export type { FieldArrayApi, FieldInputProps, FieldRules, FieldState, FocusableNode, FormApi, FormCompletion, FormConfig, FormErrors, FormTouched, FormValidateFn, FormValues, HookFieldProps, HookFormFieldProps, SubmitHelpers, UseFormCompletionOptions, ValidateOn, ValidationResult, ValidationRule, ValidationSchema } from './form/index.js';
 export { deletePath, Form, getPath, HookFormField, isFieldFilled, rules, setPath, useField, useFieldArray, useForm, useFormCompletion, useFormContext, useHookFormField, useOptionalFormContext } from './form/index.js';
-export type { PressAnimationPreset, UseControllableStateOptions, UsePressAnimationOptions, UsePressAnimationResult, UseToggleResult } from './hooks/index.js';
-export { FLICK_TOLERANCE, PRESS_ANIMATION_PRESETS, useControllableState, useDebounce, useFlickGuard, usePressAnimation, useReducedMotion, useToggle } from './hooks/index.js';
+export type { PressAnimationPreset, ScrollDirection, UseControllableStateOptions, UsePressAnimationOptions, UsePressAnimationResult, UseRefreshControlLabels, UseRefreshControlOptions, UseRefreshControlResult, UseScrollDirectionOptions, UseScrollDirectionResult, UseToggleResult } from './hooks/index.js';
+export { FLICK_TOLERANCE, PRESS_ANIMATION_PRESETS, useControllableState, useDebounce, useFlickGuard, usePressAnimation, useReducedMotion, useRefreshControl, useScrollDirection, useToggle } from './hooks/index.js';
 export type { InitUIOptions } from './initUI.js';
 export { initUI } from './initUI.js';
 export type { NetworkStatusBannerProps } from './network/index.js';
 export { NetworkStatusBanner } from './network/index.js';
 export type { ColorMode, ColorPalette, ColorSchemePreference, DeepPartial, IconRegistry, IconRenderer, MotionScale, RadiusScale, ShadowDefinition, ShadowScale, SpacingScale, TextVariantSpec, Theme, ThemeOverrides, ThemeProviderProps, TypographyScale } from './theme/index.js';
 export { darkTheme, getColorMode, getTheme, lightTheme, mergeTheme, resetTheme, setColorMode, setTheme, subscribeTheme, ThemeProvider, useTheme, useThemeMode } from './theme/index.js';
-export type { BreakpointKey, FeedbackIntent, HapticType, ResponsiveScales, ScreenInfo, SpacingToken, SquirclePathParams } from './utils/index.js';
-export { Breakpoints, configureFeedback, feedback, hapticForIntent, isFeedbackEnabled, isScreenSize, isTablet, Margin, Padding, Responsive, ScreenDimensions, Spacing, SQUIRCLE_MIN_RADIUS, SQUIRCLE_SMOOTHING, setHapticImplementation, shadowStyle, smoothCorners, squircleApplies, squircleHostRadius, squirclePath, triggerHaptic, useScreenDimensions, warnUnknownProps } from './utils/index.js';
+export type { AnnounceOptions, BreakpointKey, FeedbackIntent, HapticType, ResponsiveScales, ScreenInfo, SpacingToken, SquirclePathParams } from './utils/index.js';
+export { announce, Breakpoints, configureFeedback, feedback, hapticForIntent, isFeedbackEnabled, isScreenSize, isTablet, Margin, Padding, Responsive, ScreenDimensions, Spacing, SQUIRCLE_MIN_RADIUS, SQUIRCLE_SMOOTHING, setHapticImplementation, shadowStyle, smoothCorners, squircleApplies, squircleHostRadius, squirclePath, triggerHaptic, useScreenDimensions, warnUnknownProps } from './utils/index.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/specs/NativePdfRasterizer.d.ts

@@ -3,7 +3,7 @@ export interface PdfDocumentInfo {
     /** Opaque handle for every subsequent call (getPageInfo/renderPage/close) — NOT the file path. */
     handle: string;
     pageCount: number;
-    /** Points (1/72 in), the unrotated page size of page 0 — a per-page size read happens in renderPage. */
+    /** Points (1/72 in), the page size of page 0 as displayed (after the page's /Rotate) — a per-page size read happens in renderPage. */
     pageWidth: number;
     pageHeight: number;
 }

package/lib/typescript/module/utils/announce.d.ts

@@ -0,0 +1,14 @@
+export type AnnounceOptions = {
+    /** Polite (default) waits for current speech; `false` interrupts. Use `false` only for errors. */
+    polite?: boolean;
+};
+/**
+ * Speaks `message` through the screen reader without moving focus.
+ *
+ * iOS: queued behind current speech when polite, high priority and interrupting
+ * when not. Android: React Native exposes one announcement path with no
+ * priority, so polite and assertive both go through it. Web: a hidden
+ * `aria-live` region, `polite` or `assertive` (role `alert`).
+ */
+export declare const announce: (message: string, options?: AnnounceOptions) => void;
+//# sourceMappingURL=announce.d.ts.map

package/lib/typescript/module/utils/hapticUtils.d.ts

@@ -1,4 +1,4 @@
-export type HapticType = 'selection' | 'impactLight' | 'impactMedium' | 'impactHeavy' | 'notificationSuccess' | 'notificationWarning' | 'notificationError';
+export type HapticType = 'selection' | 'impactLight' | 'impactMedium' | 'impactHeavy' | 'notificationSuccess' | 'notificationWarning' | 'notificationError' | 'longPress' | 'tick' | 'denseTick' | 'confirm' | 'reject' | 'gestureStart';
 export declare const triggerHaptic: (type?: HapticType) => void;
 /**
  * Replace the haptic backend. Intended for TESTS and for the showcase; an app

package/lib/typescript/module/utils/index.d.ts

@@ -1,3 +1,5 @@
+export type { AnnounceOptions } from './announce.js';
+export { announce } from './announce.js';
 export { blendOf, tintOf } from './color.js';
 export { smoothCorners } from './corners.js';
 export type { FeedbackIntent } from './feedback.js';

package/lib/typescript/module/utils/placement.d.ts

@@ -0,0 +1,55 @@
+import type { LayoutRectangle } from 'react-native';
+import type { EdgeInsets } from 'react-native-safe-area-context';
+/**
+ * The anchored-surface engine: where a menu, a context menu or a tooltip sits
+ * against the view that opened it. Pure geometry in window coordinates (what
+ * `measureInWindow` reports), so it runs the same on iOS, Android and web.
+ */
+export type PlacementPreference = 'top' | 'bottom' | 'auto';
+export type ResolvedPlacement = 'top' | 'bottom';
+export type PlacementAlign = 'center' | 'start' | 'end';
+export interface PlacementViewport {
+    width: number;
+    height: number;
+    insets: EdgeInsets;
+}
+export interface PlacementOptions {
+    /** Space between the anchor and the surface. Default 8. */
+    gap?: number;
+    /** Least distance from each safe edge of the viewport. Default 8. */
+    margin?: number;
+    /** Horizontal alignment against the anchor, in left-to-right terms. Default `'center'`. */
+    align?: PlacementAlign;
+}
+export interface PlacementResult {
+    x: number;
+    y: number;
+    placement: ResolvedPlacement;
+}
+export interface PlacementRoom {
+    above: number;
+    below: number;
+}
+export declare const PLACEMENT_GAP = 8;
+export declare const PLACEMENT_MARGIN = 8;
+/** Height free above and below the anchor, inside the safe area and the margin. */
+export declare const placementRoom: (anchor: LayoutRectangle, viewport: PlacementViewport, options?: PlacementOptions) => PlacementRoom;
+/**
+ * Places a surface of `content` size against `anchor`. `'top'` and `'bottom'`
+ * are preferences that flip when the surface does not fit and the other side
+ * has more room; `'auto'` takes the side with more room. The surface never
+ * covers a visible anchor: when it is taller than the room on its side the
+ * caller caps its height to `placementRoom(...)` and lets it scroll. The
+ * horizontal position is clamped inside the safe area.
+ */
+export declare const computePlacement: (anchor: LayoutRectangle, content: {
+    width: number;
+    height: number;
+}, viewport: PlacementViewport, preferred: PlacementPreference, options?: PlacementOptions) => PlacementResult;
+/**
+ * Where along a surface's edge an arrow sits so it points at the anchor's
+ * centre, kept `cornerPadding` away from the surface's corners.
+ */
+export declare const arrowOffset: (anchorCenter: number, surfaceStart: number, surfaceLength: number, cornerPadding: number) => number;
+export declare const claimAnchoredSurface: (close: () => void) => (() => void);
+//# sourceMappingURL=placement.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority/mobile-ui",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "Beautiful, animated, accessible React Native components, theme and form engine for Webority projects.",
   "keywords": [
     "react-native",
@@ -60,7 +60,7 @@
     }
   },
   "peerDependencies": {
-    "@webority/mobile-core": ">=0.9.0 <0.10.0",
+    "@webority/mobile-core": ">=0.11.0 <0.12.0",
     "expo": ">=57.0.0",
     "expo-file-system": ">=57.0.0",
     "expo-haptics": ">=57.0.0",
@@ -107,7 +107,7 @@
     ]
   },
   "devDependencies": {
-    "@webority/mobile-core": "0.9.1"
+    "@webority/mobile-core": "0.11.0"
   },
   "scripts": {
     "build": "bob build && node ../../scripts/minify-lib.mjs",

package/src/specs/NativePdfRasterizer.ts

@@ -5,7 +5,7 @@ export interface PdfDocumentInfo {
   /** Opaque handle for every subsequent call (getPageInfo/renderPage/close) — NOT the file path. */
   handle: string;
   pageCount: number;
-  /** Points (1/72 in), the unrotated page size of page 0 — a per-page size read happens in renderPage. */
+  /** Points (1/72 in), the page size of page 0 as displayed (after the page's /Rotate) — a per-page size read happens in renderPage. */
   pageWidth: number;
   pageHeight: number;
 }