@webority/mobile-ui 0.10.0 → 0.11.1

package/lib/typescript/module/components/Descriptions/Descriptions.d.ts

@@ -4,9 +4,16 @@ import type { TextColor } from '../Text/Text.js';
 export type DescriptionsSize = 'sm' | 'md';
 export type DescriptionsVariant = 'list' | 'summary';
 export interface DescriptionItem {
-    /** A string renders as text; a node (a symbol with a subscript, say) renders as-is. */
+    /**
+     * A string renders as text. A node (a symbol with a subscript, say) sits in the label's Text, so
+     * its base and subscript take the label's size and colour; a string inside a node list is fine.
+     */
     label: React.ReactNode;
-    /** A string renders as text; a node renders as-is. Empty renders as a plain hyphen, "-". */
+    /**
+     * A string, a number, a `sym()` / `Notation` or a list of those renders as text in the value's
+     * size, weight and colour (`strong`, `tone`), the subscript included. Any other node (a badge, a
+     * Text of your own) renders as-is in a View and owns its type. Empty renders as a plain hyphen, "-".
+     */
     value?: React.ReactNode;
     /** Make this row span both columns. Ignored when `columns` is 1. */
     full?: boolean;

package/lib/typescript/module/components/FileViewer/FileViewer.d.ts

@@ -25,7 +25,7 @@ export interface FileViewerProps {
     accessibilityLabel?: string;
 }
 /**
- * Renders a PDF via our own native rasterizer (PDFKit on iOS, PdfRenderer on
+ * Renders a PDF via our own native rasterizer (Core Graphics on iOS, PdfRenderer on
  * Android) — no third-party PDF dependency. Pages are paged through a plain
  * `ScrollView` with manual windowed mounting (render the visible page ±
  * `RENDER_WINDOW`), not a `FlatList` — a `VirtualizedList`-based component

package/lib/typescript/module/components/Notation/Notation.d.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { ColorValue } from 'react-native';
+import type { ColorValue, StyleProp, TextStyle } from 'react-native';
 export interface NotationRun {
     text: string;
     /** The subscript that follows `text`, when the run is a symbol. */
@@ -24,8 +24,8 @@ export interface NotationProps {
     /** Follows the symbol after a space. */
     desc?: string;
     /**
-     * Subscript ink. Inside a field label it defaults to the label's ink, elsewhere to
-     * `colors.text.primary`; pass the parent's colour when it differs.
+     * Subscript ink. Inside a field's or choice's label or message line it defaults to that line's
+     * ink, elsewhere to `colors.text.primary`; pass the parent's colour when it differs.
      */
     color?: string;
     testID?: string;
@@ -37,8 +37,14 @@ export interface NotationInk {
     fontSize: number;
     color: ColorValue;
 }
-/** Provided by a label Text (FieldLabel) so a subscript inside it scales and inks with the label. */
+/**
+ * Provided by a field's text lines (FieldLabel, the floating label, FieldMessage, the FormField
+ * label, helper and error, and the Checkbox, Radio and Switch label, description and error) so a
+ * subscript inside one scales and inks with that line.
+ */
 export declare const NotationInkContext: React.Context<NotationInk | null>;
+/** The ink for a line's provider: the line's own `style` size and colour win over its defaults. */
+export declare const useNotationInk: (style: StyleProp<TextStyle>, fontSize: number, color: ColorValue) => NotationInk;
 /** A symbol of a standard with its subscript drawn small and lowered below the baseline. */
 export declare const Notation: React.FC<NotationProps>;
 /** A symbol as the standard prints it: `sym('C', 'IP')` is C with a small IP, then `desc` if given. */

package/lib/typescript/module/components/OptionSheet/OptionSheet.d.ts

@@ -45,6 +45,8 @@ export interface OptionSheetProps {
      * earlier, iOS attaches it to the closing window and dismisses it with it.
      */
     onAfterClose?: () => void;
+    /** Called with `true` when `open` turns on and `false` when it turns off, not again while it stays the same. */
+    onOpenChange?: (open: boolean) => void;
     /** Sheet heading. Also the modal's a11y label fallback. */
     title?: string;
     options: ReadonlyArray<unknown>;

package/lib/typescript/module/components/PermissionPrompt/PermissionPrompt.d.ts

@@ -0,0 +1,39 @@
+import type { PermissionKind, PermissionStatus } from '@webority/mobile-core/permissions';
+import type React from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { HapticType } from '../../utils/hapticUtils.js';
+import type { SlotIcon } from '../AppIcon/slotIcon.js';
+export interface PermissionPromptFallback {
+    /** Names the other way to do the job ("Enter address instead"). */
+    label: string;
+    onPress: () => void;
+}
+export interface PermissionPromptProps {
+    kind: PermissionKind;
+    /** What the feature is ("Scan a receipt"). Read first by a screen reader. */
+    title: string;
+    /** One sentence: what the app does with the access, ending in a full stop. */
+    reason: string;
+    /** An AppIcon name or any node, drawn in a tinted disc above the title. */
+    icon?: SlotIcon;
+    /** The status each time it settles: after the first check finds nothing to ask, and after each request or Cancel. */
+    onResult: (status: PermissionStatus) => void;
+    /** The way to carry on without the access, shown in the unavailable state. */
+    fallback?: PermissionPromptFallback;
+    /** Haptic on each button press. Default `'selection'`. */
+    haptic?: HapticType | false;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * Explains why the app needs a permission before the system prompt, in the way
+ * each platform's review accepts. iOS gets one Continue button that opens the
+ * system prompt, with no way to leave first (App Review rejects a "Not now").
+ * Android asks straight away the first time and explains only after one
+ * refusal, with Cancel. Once access is refused or the device lacks it, the
+ * prompt becomes an inline state with the fallback, and Open Settings only
+ * when it was already off on arrival, never straight after a refusal.
+ */
+export declare const PermissionPrompt: React.FC<PermissionPromptProps>;
+export default PermissionPrompt;
+//# sourceMappingURL=PermissionPrompt.d.ts.map

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

@@ -0,0 +1,5 @@
+export type { PermissionPromptFallback, PermissionPromptProps } from './PermissionPrompt.js';
+export { default, PermissionPrompt } from './PermissionPrompt.js';
+export type { PermissionPromptView, UsePermissionPromptOptions, UsePermissionPromptResult } from './usePermissionPrompt.js';
+export { usePermissionPrompt } from './usePermissionPrompt.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/components/PermissionPrompt/usePermissionPrompt.d.ts

@@ -0,0 +1,44 @@
+import type { PermissionKind, PermissionStatus } from '@webority/mobile-core/permissions';
+/**
+ * - `pending`: the first status read, or on Android the system prompt asked straight away.
+ * - `explain`: the explainer with Continue (and Cancel on Android).
+ * - `unavailable`: the feature cannot work; offer the fallback.
+ * - `authorized`: granted or limited; the feature can run.
+ */
+export type PermissionPromptView = 'pending' | 'explain' | 'unavailable' | 'authorized';
+export interface UsePermissionPromptOptions {
+    /**
+     * Called each time the status settles with no question left open: when the first
+     * check finds nothing to ask (granted, limited, blocked or unavailable), and after
+     * each request or Cancel.
+     */
+    onResult?: (status: PermissionStatus) => void;
+}
+export interface UsePermissionPromptResult {
+    view: PermissionPromptView;
+    /** The latest status, `null` until the first check returns. */
+    status: PermissionStatus | null;
+    /** True while the system prompt is up. */
+    requesting: boolean;
+    /** Android only: the explainer offers Cancel, as Android requires; iOS and web never do. */
+    cancellable: boolean;
+    /**
+     * True only when the status was already `blocked` when this prompt opened, so
+     * Open Settings never appears straight after the person refused.
+     */
+    showSettings: boolean;
+    /** Shows the system prompt. Resolves the new status, or `null` when one is already up. */
+    request: () => Promise<PermissionStatus | null>;
+    /** Leaves the explainer for the unavailable state without asking. */
+    cancel: () => void;
+    openSettings: () => Promise<boolean>;
+}
+/**
+ * Decides what a permission prompt shows, by platform:
+ * - iOS and web explain first whenever a request can still show the system prompt.
+ * - Android asks straight away the first time, and explains only after one refusal
+ *   (`denied`), the case Android's rationale flow covers.
+ * - `blocked` or `unavailable` goes to the unavailable state.
+ */
+export declare const usePermissionPrompt: (kind: PermissionKind, { onResult }?: UsePermissionPromptOptions) => UsePermissionPromptResult;
+//# sourceMappingURL=usePermissionPrompt.d.ts.map

package/lib/typescript/module/components/PhoneNumberInput/PhoneNumberInput.d.ts

@@ -159,7 +159,10 @@ export interface PhoneNumberInputProps extends Pick<TextInputProps, 'returnKeyTy
     labelStyle?: StyleProp<TextStyle>;
     placeholder?: string;
     helperText?: string;
-    /** The app's own error text. Always wins over the built-in invalid-number message. */
+    /**
+     * The app's own error text, a string or a node; it replaces the built-in invalid-number message.
+     * `true` shows the error state and keeps the built-in message; `false` and `''` change nothing.
+     */
     error?: ReactNode;
     /**
      * Text under the field once the typed number is not a real number for the
@@ -169,7 +172,7 @@ export interface PhoneNumberInputProps extends Pick<TextInputProps, 'returnKeyTy
      * a cleared field earns that grace again. Default `'Enter a valid mobile
      * number'` under `validation="mobile"`, else `'Enter a valid number'`;
      * a string replaces the text, `false` turns the message off. Nothing shows
-     * under `validation={false}`, and `error` always wins.
+     * under `validation={false}`, and an `error` text always wins.
      */
     invalidMessage?: string | false;
     required?: boolean;

package/lib/typescript/module/components/Radio/Radio.d.ts

@@ -8,6 +8,8 @@ export interface RadioGroupContextValue {
     selectedValue: RadioValue | undefined;
     onChange: (value: RadioValue) => void;
     disabled: boolean;
+    /** The group is in error: every radio draws its empty ring in the error colour. */
+    error?: boolean;
 }
 export declare const RadioGroupContext: import("react").Context<RadioGroupContextValue | null>;
 export declare const useRadioGroup: () => RadioGroupContextValue | null;
@@ -16,10 +18,17 @@ export interface RadioProps extends Omit<PressableProps, 'style' | 'children' |
     selected?: boolean;
     onChange?: (value: RadioValue) => void;
     disabled?: boolean;
-    label?: string;
-    /** Secondary line under the label. */
-    description?: string;
-    /** Error line under the label (and description); also draws the empty ring in the error colour. */
+    /**
+     * A string, or a node for a symbol with a subscript. A node label needs an
+     * explicit `accessibilityLabel` (the radio's screen-reader name).
+     */
+    label?: ReactNode;
+    /** Secondary line under the label. A string or a node; a node description adds nothing to the accessibility hint. */
+    description?: ReactNode;
+    /**
+     * Error line under the label (and description); also draws the empty ring in the error colour.
+     * A string or a node; `true` shows the error state without a message.
+     */
     error?: ReactNode;
     size?: RadioSize;
     tone?: RadioTone;

package/lib/typescript/module/components/Radio/RadioGroup.d.ts

@@ -7,6 +7,11 @@ export interface RadioGroupProps {
     onChange?: (value: RadioValue) => void;
     children: React.ReactNode;
     disabled?: boolean;
+    /**
+     * One error line under the group, and every radio's empty ring in the error colour. A string or
+     * a node; `true` shows the error state without a message.
+     */
+    error?: React.ReactNode;
     accessibilityLabel?: string;
     style?: StyleProp<ViewStyle>;
     testID?: string;

package/lib/typescript/module/components/SegmentedControl/SegmentedControl.d.ts

@@ -46,7 +46,11 @@ export interface SegmentedControlProps {
     label?: ReactNode;
     /** Helper line under the control. */
     helperText?: ReactNode;
-    /** Error line under the control, in the error colour. Replaces `helperText`. */
+    /**
+     * Error line under the control, in the error colour, with the control outlined (the underline
+     * look recolours its divider). Replaces `helperText`; `true` shows the error state without a
+     * message.
+     */
     error?: ReactNode;
     value?: SegmentValue;
     defaultValue?: SegmentValue;

package/lib/typescript/module/components/Select/Select.d.ts

@@ -34,6 +34,8 @@ interface BaseSelectProps<T = SelectOption> {
     /** Defaults to `(o) => (o as SelectOption).icon`. */
     getOptionIcon?: (option: T) => React.ReactNode;
     placeholder?: string;
+    /** Called with `true` when the option sheet opens and `false` when it closes. */
+    onOpenChange?: (open: boolean) => void;
     searchable?: boolean;
     /**
      * Haptic feedback for interactions. Pass false to disable; pass a HapticType

package/lib/typescript/module/components/Switch/Switch.d.ts

@@ -12,10 +12,17 @@ export interface SwitchProps extends Omit<PressableProps, 'style' | 'children' |
     disabled?: boolean;
     size?: SwitchSize;
     tone?: SwitchTone;
-    label?: string;
-    /** Secondary line under the label. */
-    description?: string;
-    /** Error line under the label (and description). */
+    /**
+     * A string, or a node for a symbol with a subscript. A node label needs an
+     * explicit `accessibilityLabel` (the switch's screen-reader name).
+     */
+    label?: ReactNode;
+    /** Secondary line under the label. A string or a node; a node description adds nothing to the accessibility hint. */
+    description?: ReactNode;
+    /**
+     * Error line under the label (and description); also outlines the off track in the error colour.
+     * A string or a node; `true` shows the error state without a message.
+     */
     error?: ReactNode;
     /**
      * Lines the label (and the description) may take before truncating with an

package/lib/typescript/module/components/TagInput/TagInput.d.ts

@@ -10,6 +10,10 @@ export interface TagInputProps {
     placeholder?: string;
     label?: string;
     helperText?: string;
+    /**
+     * A string or a node puts the field in the error state and shows it below in place of the
+     * helper; `true` shows the error state without a message.
+     */
     error?: ReactNode;
     required?: boolean;
     disabled?: boolean;

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

@@ -114,6 +114,8 @@ export type { OTPInputProps, OTPInputRef, OTPInputSize } from './OTPInput/index.
 export { OTPInput } from './OTPInput/index.js';
 export type { PaymentResultProps, PaymentResultStatus } from './PaymentResult/index.js';
 export { PaymentResult } from './PaymentResult/index.js';
+export type { PermissionPromptFallback, PermissionPromptProps, PermissionPromptView, UsePermissionPromptOptions, UsePermissionPromptResult } from './PermissionPrompt/index.js';
+export { PermissionPrompt, usePermissionPrompt } from './PermissionPrompt/index.js';
 export type { CallingCode, PhoneNumberInfo, PhoneNumberInputLabelMode, PhoneNumberInputProps, PhoneNumberInputRef, PhoneNumberValidation, PhoneNumberValue } from './PhoneNumberInput/index.js';
 export { ALL_CALLING_CODES, DEFAULT_CALLING_CODES, formatE164, PhoneNumberInput, parseE164 } from './PhoneNumberInput/index.js';
 export type { PickerTriggerProps, PickerTriggerSize, PickerTriggerVariant } from './PickerTrigger/index.js';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webority/mobile-ui",
-  "version": "0.10.0",
+  "version": "0.11.1",
   "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.10.0 <0.11.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.10.0"
+    "@webority/mobile-core": "0.11.1"
   },
   "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;
 }