@platform-blocks/ui 0.2.0 → 0.3.0

package/lib/components/Ring/types.d.ts

@@ -0,0 +1,75 @@
+import React from 'react';
+import { ViewStyle, TextStyle } from 'react-native';
+import { SpacingProps } from '../../core/utils';
+export interface RingColorStop {
+    /** Threshold (0-100) that determines when the color becomes active */
+    value: number;
+    /** Stroke color applied once the threshold is reached */
+    color: string;
+}
+export interface RingRenderContext {
+    /** Clamped value within the provided min/max range */
+    value: number;
+    /** Normalized percentage (0-100) for the current value */
+    percent: number;
+    /** Minimum bound used for normalization */
+    min: number;
+    /** Maximum bound used for normalization */
+    max: number;
+}
+export interface RingProps extends SpacingProps {
+    /** Current value represented by the ring */
+    value: number;
+    /** Lower bound for normalization. Defaults to 0. */
+    min?: number;
+    /** Upper bound for normalization. Defaults to 100. */
+    max?: number;
+    /** Diameter of the ring in pixels. Defaults to 100. */
+    size?: number;
+    /** Stroke thickness in pixels. Defaults to 12. */
+    thickness?: number;
+    /** Optional caption rendered beneath the ring */
+    caption?: React.ReactNode;
+    /** Main label rendered in the ring center */
+    label?: React.ReactNode;
+    /** Secondary label rendered below the main label */
+    subLabel?: React.ReactNode;
+    /** Displays the computed percentage when no label/subLabel is provided. Defaults to true. */
+    showValue?: boolean;
+    /** Formats the displayed value or percentage */
+    valueFormatter?: (value: number, percent: number) => React.ReactNode;
+    /** Track color behind the progress stroke */
+    trackColor?: string;
+    /** Progress stroke color or resolver */
+    progressColor?: string | ((value: number, percent: number) => string);
+    /** Optional color stops evaluated against the computed percent */
+    colorStops?: RingColorStop[];
+    /** Forces the ring into a neutral state, disabling the progress stroke */
+    neutral?: boolean;
+    /** Controls whether the progress stroke has rounded caps. Defaults to true. */
+    roundedCaps?: boolean;
+    /** Container style for the outer wrapper */
+    style?: ViewStyle;
+    /** Style applied to the ring wrapper */
+    ringStyle?: ViewStyle;
+    /** Style applied to the center content container */
+    contentStyle?: ViewStyle;
+    /** Style overrides for the main label */
+    labelStyle?: TextStyle;
+    /** Style overrides for the secondary label */
+    subLabelStyle?: TextStyle;
+    /** Style overrides for the caption */
+    captionStyle?: TextStyle;
+    /** Color override for the main label */
+    labelColor?: string;
+    /** Color override for the secondary label */
+    subLabelColor?: string;
+    /** Color override for the caption */
+    captionColor?: string;
+    /** Custom center content. Receives value info when passed as a function */
+    children?: React.ReactNode | ((context: RingRenderContext) => React.ReactNode);
+    /** Test identifier for end-to-end tests */
+    testID?: string;
+    /** Accessibility label describing the ring */
+    accessibilityLabel?: string;
+}

package/lib/components/SegmentedControl/types.d.ts

@@ -37,7 +37,7 @@ export interface SegmentedControlProps extends SpacingProps, LayoutProps, Border
     disabled?: boolean;
     /** Prevent user interaction but keep visual state */
     readOnly?: boolean;
-    /** Adjust text color automatically for filled variant */
+    /** Adjust text color automatically for filled/outline variants */
     autoContrast?: boolean;
     /** Render dividers between items */
     withItemsBorders?: boolean;
@@ -48,7 +48,7 @@ export interface SegmentedControlProps extends SpacingProps, LayoutProps, Border
     /** Optional radio group name hint */
     name?: string;
     /** Visual style variant */
-    variant?: 'default' | 'filled';
+    variant?: 'default' | 'filled' | 'outline' | 'ghost';
     /** Custom style for indicator */
     indicatorStyle?: ViewStyle;
     /** Custom style applied to every item */
@@ -59,4 +59,10 @@ export interface SegmentedControlProps extends SpacingProps, LayoutProps, Border
     testID?: string;
     /** Accessibility label for the entire control */
     accessibilityLabel?: string;
+    /** Optional label rendered alongside the control */
+    label?: ReactNode;
+    /** Supplementary description text rendered with the label */
+    description?: ReactNode;
+    /** Placement of the label relative to the control */
+    labelPosition?: 'left' | 'right' | 'top' | 'bottom';
 }

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

@@ -3,4 +3,3 @@ export declare const Select: import("../../core/factory/factory").PlatformBlocks
     props: SelectProps;
     ref: any;
 }>;
-export default Select;

package/lib/components/Select/Select.types.d.ts

@@ -1,31 +1,64 @@
 import React from 'react';
 import { SizeValue } from '../../core/theme/sizes';
 import { LayoutProps, SpacingProps } from '../../core/utils';
+/**
+ * Represents a single option exposed by the Select component.
+ */
 export interface SelectOption<T = any> {
+    /** Human-readable text displayed for the option. */
     label: string;
+    /** Value returned when the option is chosen. */
     value: T;
+    /** When true, the option renders but cannot be selected. */
     disabled?: boolean;
 }
+/**
+ * Props accepted by the Select component. Inherits spacing and layout helpers
+ * for consistency with other inputs.
+ */
 export interface SelectProps<T = any> extends SpacingProps, LayoutProps {
+    /** Current value when the component is controlled. */
     value?: T | null;
+    /** Initial value when the component manages its own state. */
     defaultValue?: T | null;
+    /** Callback fired whenever the selection changes. */
     onChange?: (value: T | null, option?: SelectOption<T> | null) => void;
+    /** Collection of options available to choose from. */
     options: SelectOption<T>[];
+    /** Placeholder text shown when no value is selected. */
     placeholder?: string;
+    /** Size token controlling trigger height and typography. */
     size?: SizeValue;
+    /** Corner radius token applied to the trigger and dropdown. */
     radius?: any;
+    /** Disables the control when set to true. */
     disabled?: boolean;
+    /** Optional label rendered above the trigger. */
     label?: string;
     /** Optional short descriptive text shown directly under the label (above the field). */
     description?: string;
+    /** Helper copy displayed beneath the control. */
     helperText?: string;
+    /** Error message shown beneath the control in error state. */
     error?: string;
+    /** Enables client-side filtering of options. */
     searchable?: boolean;
+    /** Custom renderer for an individual option row. */
     renderOption?: (opt: SelectOption<T>, active: boolean, selected: boolean) => React.ReactNode;
+    /** Stretches the trigger to occupy the full width of its container. */
     fullWidth?: boolean;
+    /** Maximum height the dropdown may reach before it scrolls. */
     maxHeight?: number;
+    /** Whether the dropdown should close immediately after selection. */
     closeOnSelect?: boolean;
+    /** Allows the user to clear the current selection. */
     clearable?: boolean;
+    /** Accessible label announced for the clear button when present. */
     clearButtonLabel?: string;
+    /** Handler invoked after the selection is cleared. */
     onClear?: () => void;
+    /** Controls whether the trigger regains focus after selecting an option. */
+    refocusAfterSelect?: boolean;
+    /** Whether dropdown positioning should avoid the on-screen keyboard. */
+    keyboardAvoidance?: boolean;
 }

package/lib/components/Spotlight/DirectSpotlightState.d.ts

@@ -4,7 +4,7 @@
  * This hook bypasses the SpotlightProvider context and uses the global state directly.
  * This should be used in the GlobalSpotlight component to avoid provider re-mounting issues.
  */
-import { SpotlightState } from './SpotlightStore';
+import type { SpotlightState } from './SpotlightStore';
 interface GlobalSpotlightState {
     opened: boolean;
     query: string;

package/lib/components/Spotlight/Spotlight.d.ts

@@ -1,7 +1,7 @@
 import React from 'react';
 import type { SpotlightProps, SpotlightRootProps, SpotlightSearchProps, SpotlightActionsListProps, SpotlightActionProps, SpotlightActionsGroupProps, SpotlightEmptyProps } from './types';
 declare function SpotlightRoot({ query, onQueryChange, children, opened, onClose, shortcut, style, }: SpotlightRootProps): React.JSX.Element;
-declare function SpotlightSearch({ value, onChangeText, leftSection, placeholder, onNavigateUp, onNavigateDown, onSelectAction, onClose, ...props }: SpotlightSearchProps): React.JSX.Element;
+declare function SpotlightSearch({ value, onChangeText, leftSection, placeholder, onNavigateUp, onNavigateDown, onSelectAction, onClose, autoFocus, inputRef: forwardedRef, ...props }: SpotlightSearchProps): React.JSX.Element;
 declare function SpotlightActionsList({ children, scrollable, maxHeight, style, scrollRef, onScrollChange, }: SpotlightActionsListProps): React.JSX.Element;
 declare function SpotlightAction({ label, description, leftSection, rightSection, onPress, disabled, selected, children, style, innerRef, highlightQuery, }: SpotlightActionProps): React.JSX.Element;
 declare function SpotlightActionsGroup({ label, children, style, }: SpotlightActionsGroupProps): React.JSX.Element;

package/lib/components/Spotlight/types.d.ts

@@ -1,4 +1,4 @@
-import { ViewStyle } from 'react-native';
+import type { ViewStyle, TextInput } from 'react-native';
 import React from 'react';
 import { SpotlightItem } from './SpotlightTypes';
 import type { HighlightProps as HighlightComponentProps } from '../Highlight';
@@ -34,6 +34,8 @@ export interface SpotlightSearchProps {
     onNavigateDown?: () => void;
     onSelectAction?: () => void;
     onClose?: () => void;
+    autoFocus?: boolean;
+    inputRef?: React.RefObject<TextInput | null>;
 }
 export interface SpotlightActionsListProps {
     children: React.ReactNode;

package/lib/components/Stepper/types.d.ts

@@ -1,4 +1,11 @@
 import { ReactNode } from 'react';
+import type { ComponentSizeValue } from '../../core/theme/componentSize';
+export interface StepperMetrics {
+    iconSize: number;
+    fontSize: number;
+    spacing: number;
+    descriptionFontSize: number;
+}
 export interface StepperStepProps {
     /** Step content */
     children?: ReactNode;
@@ -37,7 +44,7 @@ export interface StepperProps {
     /** Icon size */
     iconSize?: number;
     /** Component size */
-    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    size?: ComponentSizeValue;
     /** Component color */
     color?: string;
     /** Icon to display when step is completed */
@@ -61,7 +68,8 @@ export interface StepperContextValue {
     orientation: 'horizontal' | 'vertical';
     iconPosition: 'left' | 'right';
     iconSize: number;
-    size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    size: ComponentSizeValue;
+    metrics: StepperMetrics;
     color: string;
     completedIcon?: ReactNode;
     allowNextStepsSelect: boolean;

package/lib/components/TextArea/styles.d.ts

@@ -56,40 +56,10 @@ export declare const useTextAreaStyles: (props: TextAreaProps & {
         textInput: any;
     };
     getSizeStyles: (size: SizeValue, rows?: number) => {
-        fontSize: 12;
-        padding: 4;
+        fontSize: number;
+        padding: number;
         minHeight: number;
-        lineHeight: 16;
-    } | {
-        fontSize: 14;
-        padding: 8;
-        minHeight: number;
-        lineHeight: 20;
-    } | {
-        fontSize: 16;
-        padding: 12;
-        minHeight: number;
-        lineHeight: 24;
-    } | {
-        fontSize: 18;
-        padding: 16;
-        minHeight: number;
-        lineHeight: 28;
-    } | {
-        fontSize: 20;
-        padding: 20;
-        minHeight: number;
-        lineHeight: 32;
-    } | {
-        fontSize: 24;
-        padding: 24;
-        minHeight: number;
-        lineHeight: 36;
-    } | {
-        fontSize: 30;
-        padding: 32;
-        minHeight: number;
-        lineHeight: 42;
+        lineHeight: number;
     };
 };
 export {};

package/lib/components/TextArea/types.d.ts

@@ -1,5 +1,6 @@
 import { TextInputProps } from 'react-native';
 import { BaseInputProps } from '../Input/types';
+import { SizeValue } from '../../core/theme/types';
 export interface TextAreaProps extends BaseInputProps {
     /** Default value for uncontrolled mode */
     defaultValue?: string;
@@ -23,7 +24,7 @@ export interface TextAreaProps extends BaseInputProps {
     textInputProps?: Omit<TextInputProps, keyof BaseInputProps>;
 }
 export interface TextAreaStyleProps {
-    size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+    size: SizeValue;
     focused?: boolean;
     disabled?: boolean;
     error?: boolean;

package/lib/components/TimePicker/TimePicker.d.ts

@@ -1,3 +1 @@
-import React from 'react';
-import type { TimePickerProps } from './types';
-export declare const TimePicker: React.FC<TimePickerProps>;
+export { TimePickerInput as TimePicker } from '../TimePickerInput/TimePickerInput';

package/lib/components/TimePickerInput/TimePickerInput.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import type { TimePickerInputProps } from './types';
+export declare const TimePickerInput: React.FC<TimePickerInputProps>;

package/lib/components/TimePickerInput/index.d.ts

@@ -1,2 +1,2 @@
-export { TimePicker as TimePickerInput } from '../TimePicker/TimePicker';
-export type { TimePickerProps as TimePickerInputProps } from '../TimePicker/types';
+export { TimePickerInput } from './TimePickerInput';
+export type { TimePickerInputProps, TimePickerValue } from './types';

package/lib/components/TimePickerInput/types.d.ts

@@ -0,0 +1,3 @@
+import type { TimePickerProps, TimePickerValue } from '../TimePicker/types';
+export type TimePickerInputProps = TimePickerProps;
+export type { TimePickerValue };

package/lib/components/Timeline/types.d.ts

@@ -1,5 +1,12 @@
 import { ReactNode } from 'react';
 import { ViewProps } from 'react-native';
+import { type ComponentSizeValue } from '../../core/theme/componentSize';
+export interface TimelineSizeMetrics {
+    bulletSize: number;
+    lineWidth: number;
+    fontSize: number;
+    spacing: number;
+}
 export interface TimelineItemProps extends Omit<ViewProps, 'children'> {
     /** Item content */
     children?: ReactNode;
@@ -36,7 +43,7 @@ export interface TimelineProps extends Omit<ViewProps, 'children'> {
     /** Reverse active highlighting */
     reverseActive?: boolean;
     /** Component size */
-    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    size?: ComponentSizeValue;
     /** Center mode renders a single central spine allowing items on both sides via itemAlign prop */
     centerMode?: boolean;
 }
@@ -47,7 +54,8 @@ export interface TimelineContextValue {
     bulletSize: number;
     align: 'left' | 'right';
     reverseActive: boolean;
-    size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    size: ComponentSizeValue;
+    metrics: TimelineSizeMetrics;
     /** Whether layout is split with centered vertical line */
     centerMode?: boolean;
 }

package/lib/components/Tree/types.d.ts

@@ -13,6 +13,11 @@ export interface TreeProps {
     data: TreeNode[];
     /** Called when a leaf (no children) or any node with href is pressed */
     onNavigate?: (node: TreeNode) => void;
+    /** Called when a node row is pressed. Return false to prevent default handling (selection, expand). */
+    onNodePress?: (node: TreeNode, context: {
+        isBranch: boolean;
+        event?: any;
+    }) => boolean | void;
     /** Allow collapsing/expanding */
     collapsible?: boolean;
     /** Indent size in px for each depth level */
@@ -62,4 +67,6 @@ export interface TreeProps {
     noResultsFallback?: React.ReactNode;
     /** Custom highlight function for labels (return ReactNode) */
     highlight?: (label: string, query: string) => React.ReactNode;
+    /** Apply alternating background stripes to rows */
+    striped?: boolean;
 }

package/lib/components/index.d.ts

@@ -15,6 +15,7 @@ export { CodeBlock } from './CodeBlock';
 export { CopyButton } from './CopyButton/CopyButton';
 export { ColorPicker } from './ColorPicker';
 export { Container } from './Container';
+export { KeyboardAwareLayout } from './KeyboardAwareLayout';
 export { DataTable } from './DataTable';
 export { Disclaimer, ComponentWithDisclaimer, useDisclaimer, withDisclaimer, extractDisclaimerProps } from './Disclaimer';
 export { Dialog, DialogProvider, DialogRenderer, useDialog, useSimpleDialog } from './Dialog';
@@ -47,6 +48,7 @@ export { YearPickerInput } from './YearPickerInput';
 export { Pagination } from './Pagination';
 export { PinInput } from './PinInput';
 export { Slider, RangeSlider } from './Slider';
+export { Knob } from './Knob';
 export { AutoComplete } from './AutoComplete';
 export { FileInput } from './FileInput';
 export { RichTextEditor } from './RichTextEditor';
@@ -60,6 +62,7 @@ export { NavigationProgress, navigationProgress } from './NavigationProgress';
 export { Radio, RadioGroup } from './Radio';
 export { Rating } from './Rating';
 export { Reveal } from './Reveal';
+export { Ring } from './Ring';
 export { Skeleton } from './Skeleton';
 export { Loader } from './Loader';
 export { LoadingOverlay } from './LoadingOverlay';
@@ -82,7 +85,7 @@ export { Title } from './Title/Title';
 export { TableOfContents } from './TableOfContents/TableOfContents';
 export { HoverCard } from './HoverCard/HoverCard';
 export { ContextMenu } from './ContextMenu';
-export { Popover, PopoverTarget, PopoverDropdown } from './Popover';
+export { Popover } from './Popover';
 export { Gallery } from './Gallery';
 export type { AlertProps } from './Alert';
 export type { AppShellProps } from './AppShell';
@@ -101,6 +104,7 @@ export type { CodeBlockProps } from './CodeBlock/types';
 export type { CopyButtonProps } from './CopyButton/types';
 export type { ColorPickerProps } from './ColorPicker';
 export type { ContainerProps } from './Container';
+export type { KeyboardAwareLayoutProps } from './KeyboardAwareLayout';
 export type { DialogProps, DialogConfig, UseSimpleDialogOptions } from './Dialog';
 export type { DividerProps } from './Divider';
 export type { SpaceProps } from './Space';
@@ -130,6 +134,7 @@ export type { TimePickerInputProps } from './TimePickerInput';
 export type { PaginationProps } from './Pagination';
 export type { PinInputProps } from './PinInput';
 export type { SliderProps, RangeSliderProps } from './Slider';
+export type { KnobProps, KnobMark } from './Knob';
 export type { AutoCompleteProps, AutoCompleteOption } from './AutoComplete';
 export type { FileInputProps, FileInputFile } from './FileInput';
 export type { RichTextEditorProps, RichTextEditorContent, RichTextEditorFormat, RichTextEditorSelection } from './RichTextEditor';
@@ -140,6 +145,7 @@ export type { ProgressProps } from './Progress';
 export type { QRCodeProps } from './QRCode';
 export type { RadioProps, RadioGroupProps } from './Radio';
 export type { RatingProps } from './Rating';
+export type { RingProps, RingColorStop, RingRenderContext } from './Ring';
 export type { SkeletonProps } from './Skeleton';
 export type { LoaderProps } from './Loader';
 export type { LoadingOverlayProps } from './LoadingOverlay';

package/lib/components/optimized.d.ts

@@ -12,6 +12,7 @@ export type { SwitchProps } from './Switch/types';
 export type { NumberInputProps } from './NumberInput/types';
 export type { PinInputProps } from './PinInput/types';
 export type { SliderProps, RangeSliderProps } from './Slider/types';
+export type { KnobProps, KnobMark } from './Knob/types';
 export declare const LazyPasswordInput: React.LazyExoticComponent<React.FC<import("./Input/types").PasswordInputProps>>;
 export declare const LazyNumberInput: React.LazyExoticComponent<import("../core").PlatformBlocksComponent<{
     props: import("./NumberInput/types").NumberInputProps;
@@ -29,6 +30,10 @@ export declare const LazyRangeSlider: React.LazyExoticComponent<import("../core"
     props: import("./Slider/types").RangeSliderProps;
     ref: import("react-native").View;
 }>>;
+export declare const LazyKnob: React.LazyExoticComponent<import("../core").PlatformBlocksComponent<{
+    props: import("./Knob/types").KnobProps;
+    ref: import("react-native").View;
+}>>;
 export declare const LazyCheckbox: React.LazyExoticComponent<React.ForwardRefExoticComponent<import("./Checkbox/types").CheckboxProps & React.RefAttributes<import("react-native").View>>>;
 export declare const LazyRadio: React.LazyExoticComponent<import("../core").PlatformBlocksComponent<{
     props: import("./Radio/types").RadioProps;

package/lib/components/types.d.ts

@@ -11,6 +11,7 @@ export type { CodeBlockProps } from './CodeBlock/types';
 export type { CopyButtonProps } from './CopyButton/types';
 export type { ColorPickerProps } from './ColorPicker';
 export type { ContainerProps } from './Container';
+export type { KeyboardAwareLayoutProps } from './KeyboardAwareLayout';
 export type { DialogProps } from './Dialog';
 export type { DividerProps } from './Divider';
 export type { SpaceProps } from './Space';
@@ -32,6 +33,7 @@ export type { YearPickerInputProps } from './YearPickerInput';
 export type { PaginationProps } from './Pagination';
 export type { PinInputProps } from './PinInput';
 export type { SliderProps, RangeSliderProps } from './Slider';
+export type { KnobProps, KnobMark } from './Knob';
 export type { AutoCompleteProps, AutoCompleteOption } from './AutoComplete';
 export type { FileInputProps, FileInputFile } from './FileInput';
 export type { RichTextEditorProps } from './RichTextEditor';
@@ -41,6 +43,7 @@ export type { ProgressProps } from './Progress';
 export type { QRCodeProps } from './QRCode';
 export type { RadioProps, RadioGroupProps } from './Radio';
 export type { RatingProps } from './Rating';
+export type { RingProps, RingColorStop, RingRenderContext } from './Ring';
 export type { SkeletonProps } from './Skeleton';
 export type { LoaderProps } from './Loader';
 export type { SpotlightProps } from './Spotlight';

package/lib/core/hooks/usePopoverPositioning.d.ts

@@ -4,6 +4,8 @@ export interface UsePopoverPositioningOptions extends PositioningOptions {
     autoUpdate?: boolean;
     /** Debounce delay for resize/scroll updates in ms */
     updateDelay?: number;
+    /** Adjust viewport height when on-screen keyboard is visible (default: true) */
+    keyboardAvoidance?: boolean;
 }
 export interface UsePopoverPositioningReturn {
     /** Current position result */
@@ -26,8 +28,3 @@ export declare function usePopoverPositioning(isOpen: boolean, options?: UsePopo
  * (simplified version with tooltip-specific defaults)
  */
 export declare function useTooltipPositioning(isOpen: boolean, placement?: PositioningOptions['placement']): UsePopoverPositioningReturn;
-/**
- * Hook for managing dropdown/menu positioning
- * (optimized for dropdown behavior)
- */
-export declare function useDropdownPositioning(isOpen: boolean, placement?: PositioningOptions['placement']): UsePopoverPositioningReturn;

package/lib/core/keyboard/selection.d.ts

@@ -0,0 +1,42 @@
+import { Platform } from 'react-native';
+import type { KeyboardManagerContextValue } from '../providers/KeyboardManagerProvider';
+export type SelectionMode = 'single' | 'multiple';
+export interface SelectionFocusCallbacks {
+    focusPrimary?: () => void;
+    focusModal?: () => void;
+    blurPrimary?: () => void;
+    blurModal?: () => void;
+}
+export interface HandleSelectionCompleteOptions {
+    mode: SelectionMode;
+    preferRefocus?: boolean;
+    useModal?: boolean;
+    keyboardManager?: KeyboardManagerContextValue | null;
+    focusCallbacks?: SelectionFocusCallbacks;
+    onRefocus?: () => void;
+    onBlur?: () => void;
+    interactionScheduler?: (cb: () => void) => void;
+    focusTargetId?: string;
+}
+export interface SelectionCompleteResult {
+    refocused: boolean;
+}
+export interface SelectionContractConfig extends Omit<HandleSelectionCompleteOptions, 'onRefocus' | 'onBlur' | 'focusCallbacks'> {
+    focusCallbacks?: SelectionFocusCallbacks;
+}
+export interface SelectionContractRunOptions {
+    focusCallbacks?: SelectionFocusCallbacks;
+    onRefocus?: () => void;
+    onBlur?: () => void;
+    preferRefocus?: boolean;
+    focusTargetId?: string;
+    keyboardManager?: KeyboardManagerContextValue | null;
+}
+export type SelectionContract = (options?: SelectionContractRunOptions) => SelectionCompleteResult;
+export declare function resolveRefocusBehavior(options: {
+    mode: SelectionMode;
+    preferRefocus?: boolean;
+    platform?: typeof Platform.OS;
+}): boolean;
+export declare function handleSelectionComplete(options: HandleSelectionCompleteOptions): SelectionCompleteResult;
+export declare function createSelectionContract(config: SelectionContractConfig): SelectionContract;

package/lib/core/providers/KeyboardManagerProvider.d.ts

@@ -0,0 +1,45 @@
+import React from 'react';
+import { KeyboardEvent } from 'react-native';
+export interface KeyboardManagerProviderProps {
+    children: React.ReactNode;
+    /**
+     * Optional flag to disable native listeners (primarily for tests).
+     */
+    disabled?: boolean;
+}
+export interface KeyboardManagerContextValue {
+    /** Indicates if the on-screen keyboard is currently visible */
+    isKeyboardVisible: boolean;
+    /** Height of the keyboard in pixels when visible */
+    keyboardHeight: number;
+    /** Native end coordinates from the last keyboard event */
+    keyboardEndCoordinates?: KeyboardEvent['endCoordinates'];
+    /** Reported animation duration (ms) from the native keyboard event */
+    keyboardAnimationDuration: number;
+    /** Reported animation easing from the native keyboard event */
+    keyboardAnimationEasing?: KeyboardEvent['easing'];
+    /** Latest focus target requested via `setFocusTarget`; null when none pending */
+    pendingFocusTarget: string | null;
+    /** Imperative helper for dismissing the keyboard */
+    dismissKeyboard: () => void;
+    /**
+     * Sets an optional focus target that can be consumed by an input after the keyboard closes.
+     * Passing null clears the stored target.
+     */
+    setFocusTarget: (componentId: string | null) => void;
+    /**
+     * Returns true when the provided component id matches the stored focus target.
+     * The focus target is cleared after a successful match.
+     */
+    consumeFocusTarget: (componentId: string) => boolean;
+    /**
+     * Helper that records a focus target so the next mounted input can restore focus.
+     * Consumers can call `dismissKeyboard` separately when they need to drop the keyboard.
+     */
+    refocus: (componentId: string, options?: {
+        dismiss?: boolean;
+    }) => void;
+}
+export declare const KeyboardManagerProvider: React.FC<KeyboardManagerProviderProps>;
+export declare function useKeyboardManager(): KeyboardManagerContextValue;
+export declare function useKeyboardManagerOptional(): KeyboardManagerContextValue | null;

package/lib/core/providers/index.d.ts

@@ -1,5 +1,7 @@
-export { OverlayProvider, useOverlay } from './OverlayProvider';
+export { OverlayProvider, useOverlay, useOverlayApi, useOverlays } from './OverlayProvider';
 export { OverlayRenderer } from './OverlayRenderer';
 export type { OverlayConfig } from './OverlayProvider';
 export { DirectionProvider, useDirection, useDirectionSafe, DirectionContext } from './DirectionProvider';
 export type { Direction, DirectionContextValue, DirectionProviderProps, StorageController } from './DirectionProvider';
+export { KeyboardManagerProvider, useKeyboardManager, useKeyboardManagerOptional, } from './KeyboardManagerProvider';
+export type { KeyboardManagerProviderProps, KeyboardManagerContextValue, } from './KeyboardManagerProvider';

package/lib/core/theme/PlatformBlocksProvider.d.ts

@@ -1,7 +1,13 @@
 import React from 'react';
 import { PlatformBlocksThemeProviderProps } from './ThemeProvider';
+import type { DirectionProviderProps } from '../providers';
 import type { HighlightProps as HighlightComponentProps } from '../../components/Highlight';
+import type { HapticsProviderProps } from '../haptics/HapticsProvider';
+import type { PermissionProviderProps } from '../../components/Can';
 import { ThemeModeConfig } from './ThemeModeProvider';
+type DirectionProviderConfig = Omit<DirectionProviderProps, 'children'>;
+type HapticsProviderConfig = Omit<HapticsProviderProps, 'children'>;
+type PermissionProviderConfig = Omit<PermissionProviderProps, 'children'>;
 export interface PlatformBlocksProviderProps extends Omit<PlatformBlocksThemeProviderProps, 'children'> {
     /** Your application */
     children: React.ReactNode;
@@ -42,12 +48,19 @@ export interface PlatformBlocksProviderProps extends Omit<PlatformBlocksThemePro
     i18nResources?: Record<string, {
         translation: Record<string, any>;
     }>;
+    /** Direction context configuration (pass false to opt out) */
+    direction?: false | DirectionProviderConfig;
+    /** Haptics context configuration (pass false to opt out) */
+    haptics?: false | HapticsProviderConfig;
+    /** Permission context configuration (pass false to opt out) */
+    permissions?: false | PermissionProviderConfig;
 }
 /**
  * Main provider component for Platform Blocks library
  * Provides theme context and injects CSS variables
  */
-export declare function PlatformBlocksProvider({ children, theme, inherit, withCSSVariables, cssVariablesSelector, colorSchemeMode, withOverlays, withSpotlight, withGlobalCSS, themeModeConfig, spotlightConfig, locale, fallbackLocale, i18nResources }: PlatformBlocksProviderProps): React.JSX.Element;
+export declare function PlatformBlocksProvider({ children, theme, inherit, withCSSVariables, cssVariablesSelector, colorSchemeMode, withOverlays, withSpotlight, withGlobalCSS, themeModeConfig, spotlightConfig, locale, fallbackLocale, i18nResources, direction, haptics, permissions }: PlatformBlocksProviderProps): React.JSX.Element;
 export declare namespace PlatformBlocksProvider {
     var displayName: string;
 }
+export {};

package/lib/core/theme/componentSize.d.ts

@@ -0,0 +1,10 @@
+export declare const COMPONENT_SIZE_ORDER: readonly ["xs", "sm", "md", "lg", "xl", "2xl", "3xl"];
+export type ComponentSize = (typeof COMPONENT_SIZE_ORDER)[number];
+export type ComponentSizeValue = ComponentSize | number;
+export declare const DEFAULT_COMPONENT_SIZE: ComponentSize;
+export declare function isComponentSize(value: unknown): value is ComponentSize;
+export declare function clampComponentSize(value: ComponentSizeValue | undefined, allowedSizes?: ReadonlyArray<ComponentSize>, fallback?: ComponentSize): ComponentSizeValue;
+export declare function resolveComponentSize<T>(value: ComponentSizeValue | undefined, scale: Partial<Record<ComponentSize, T>>, options?: {
+    fallback?: ComponentSize;
+    allowedSizes?: ComponentSize[];
+}): T | number;