@platform-blocks/ui 0.1.2 → 0.3.0

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';
@@ -77,10 +80,12 @@ export { Accordion } from './Accordion';
 export { Gauge } from './Gauge';
 export { GradientText } from './GradientText';
 export { ShimmerText } from './ShimmerText';
+export { Highlight } from './Highlight';
 export { Title } from './Title/Title';
 export { TableOfContents } from './TableOfContents/TableOfContents';
 export { HoverCard } from './HoverCard/HoverCard';
 export { ContextMenu } from './ContextMenu';
+export { Popover } from './Popover';
 export { Gallery } from './Gallery';
 export type { AlertProps } from './Alert';
 export type { AppShellProps } from './AppShell';
@@ -99,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';
@@ -106,6 +112,7 @@ export type { FlexProps } from './Flex';
 export type { GridProps } from './Grid';
 export type { GradientTextProps } from './GradientText';
 export type { ShimmerTextProps } from './ShimmerText';
+export type { HighlightProps } from './Highlight';
 export type { TreeProps, TreeNode } from './Tree/Tree';
 export type { TimePickerProps, TimePickerValue } from './TimePicker/types';
 export type { IconProps, IconSize, IconVariant, IconDefinition, IconRegistry } from './Icon';
@@ -127,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';
@@ -137,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';
@@ -156,6 +165,7 @@ export type { TableOfContentsProps, TocItem } from './TableOfContents/types';
 export type { StepperProps } from './Stepper';
 export type { HoverCardProps } from './HoverCard/types';
 export type { ContextMenuProps, ContextMenuItem } from './ContextMenu/ContextMenu';
+export type { PopoverProps, PopoverTargetProps, PopoverDropdownProps } from './Popover';
 export type { SegmentedControlProps, SegmentedControlItem, SegmentedControlData } from './SegmentedControl';
 export type { GalleryProps, GalleryModalProps, GalleryItem } from './Gallery';
 export * from './Accessibility/AccessibilityHelpers';

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/factory/factory.d.ts

@@ -5,10 +5,10 @@ export interface FactoryPayload {
     ref: any;
     staticComponents?: Record<string, any>;
 }
-export interface ComponentWithProps<Props = {}> {
-    withProps: <T extends Partial<Props>>(fixedProps: T) => React.FC<Omit<Props, keyof T>>;
+export interface ComponentWithProps<Props = {}, RefType = any> {
+    withProps: <T extends Partial<Props>>(fixedProps: T) => any;
 }
-export interface PlatformBlocksComponent<Payload extends FactoryPayload> extends React.FC<Payload['props']>, ComponentWithProps<Payload['props']> {
+export interface PlatformBlocksComponent<Payload extends FactoryPayload> extends React.ForwardRefExoticComponent<React.PropsWithoutRef<Payload['props']> & React.RefAttributes<Payload['ref']>>, ComponentWithProps<Payload['props'], Payload['ref']> {
     extend: any;
     displayName?: string;
 }

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,6 +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;
@@ -29,7 +36,7 @@ export interface PlatformBlocksProviderProps extends Omit<PlatformBlocksThemePro
         actions?: any[];
         placeholder?: string;
         limit?: number;
-        highlightQuery?: boolean;
+        highlightQuery?: boolean | HighlightComponentProps['highlight'];
         /** Render Spotlight even when no actions provided (useful to inject later) */
         alwaysMount?: boolean;
     };
@@ -41,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;

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

@@ -8,5 +8,6 @@ export { useColorScheme } from './useColorScheme';
 export type { ColorScheme } from './useColorScheme';
 export type { PlatformBlocksThemeProviderProps } from './ThemeProvider';
 export * from './sizes';
+export * from './componentSize';
 export * from './radius';
 export * from './shadow';

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

@@ -1,4 +1,5 @@
-export type SizeValue = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | number;
+import { ComponentSizeValue } from './componentSize';
+export type SizeValue = ComponentSizeValue;
 export interface SizeScale {
     xs: number;
     sm: number;

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

@@ -1,6 +1,8 @@
-export type SizeValue = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';
+import type { ComponentSize, ComponentSizeValue } from './componentSize';
+export type SizeToken = ComponentSize;
+export type SizeValue = ComponentSizeValue;
 export type ColorValue = string;
-export type SpacingValue = SizeValue | 'auto' | '0' | number;
+export type SpacingValue = SizeToken | 'auto' | '0' | number;
 import type { DESIGN_TOKENS } from '../design-tokens';
 export interface SpacingProps {
     /** Margin on all sides */