flet-box 1.0.3 → 1.0.5

package/src/index.d.ts

@@ -5,22 +5,46 @@ declare module 'flet-box' {
   // =========================================================================
   // Tipos base
   // =========================================================================
-  type Widget = HTMLElement;
-  type Color = string;
-  type Size = number | string;
-  type Padding = number | string;
-  type Margin = number | string;
+  export type Widget = HTMLElement;
+  export type Color = string;
+  export type Size = number | string;
+  export type Padding = number | string;
+  export type Margin = number | string;
+
+  /**
+   * The element returned by `WidgetFactory()`. It is a real `HTMLElement` with
+   * the factory's imperative API attached (see `src/widget-factory/`).
+   */
+  export interface WidgetFactoryInstance extends Widget {
+    /** Merge new props and re-apply styles, attributes, children and effects. */
+    update(props?: Record<string, any>): WidgetFactoryInstance;
+    /** Shallow copy of the widget's currently stored props. */
+    getProps(): Record<string, any>;
+    /** Register a callback fired when the widget enters the live DOM. */
+    onMount(fn: (widget: WidgetFactoryInstance) => void): void;
+    /** Register a disposer fired on every teardown path. Must be idempotent. */
+    onUnmount(fn: (widget: WidgetFactoryInstance) => void): void;
+    /** Fire mount callbacks immediately when the widget is already connected. */
+    triggerMount(): WidgetFactoryInstance;
+    /** Release the widget's resources and remove it from the lifecycle registry. */
+    _cleanup(): void;
+  }
 
   // =========================================================================
   // Props comunes (heredadas by todos the widgets)
   // =========================================================================
-  interface CommonProps {
+  export interface CommonProps {
     width?: Size;
     height?: Size;
-    size?: number;
+    // `Size`, not `number`: for a Text this is a font size and for a Button it is
+    // the `small | medium | large` preset — the widget decides which it reads.
+    size?: Size;
     padding?: Padding;
     margin?: Margin;
     bgColor?: Color;
+    // Alias kept because the engine routes it and every generated template uses
+    // it: `bgColor` is the Flet-style short name for the same style.
+    backgroundColor?: Color;
     color?: Color;
     borderRadius?: number | string;
     elevation?: number;
@@ -120,18 +144,74 @@ declare module 'flet-box' {
   export function httpPatch<T = any>(url: string, options?: HttpRequestOptions): Promise<T>;
   export function httpDelete<T = any>(url: string, options?: HttpRequestOptions): Promise<T>;
 
+  // =========================================================================
+  // Service namespaces
+  // =========================================================================
+  // Each store is also exported as a namespace object whose members are exactly
+  // the functions above, so both call styles are valid:
+  //   saveRam("k", 1)   |   RamStore.saveRam("k", 1)
+  // Members are typed through `typeof` so a namespace can never drift from the
+  // individual declaration.
+  export const RamStore: {
+    saveRam: typeof saveRam;
+    getRam: typeof getRam;
+    getAllRam: typeof getAllRam;
+    getAllRamKeys: typeof getAllRamKeys;
+    hasRam: typeof hasRam;
+    updateRam: typeof updateRam;
+    deleteRam: typeof deleteRam;
+    clearAllRam: typeof clearAllRam;
+    subscribeRam: typeof subscribeRam;
+    getRamItemCount: typeof getRamItemCount;
+    isRamAvailable: typeof isRamAvailable;
+  };
+
+  export const Session: {
+    saveSession: typeof saveSession;
+    getSession: typeof getSession;
+    getSessionSync: typeof getSessionSync;
+    updateSession: typeof updateSession;
+    deleteSession: typeof deleteSession;
+    clearAllSession: typeof clearAllSession;
+    hasSession: typeof hasSession;
+    getAllSessionKeys: typeof getAllSessionKeys;
+    getAllSessionData: typeof getAllSessionData;
+    getSessionSize: typeof getSessionSize;
+    deleteSessionByPrefix: typeof deleteSessionByPrefix;
+    deleteSessionBySuffix: typeof deleteSessionBySuffix;
+    getSessionItemCount: typeof getSessionItemCount;
+    isSessionAvailable: typeof isSessionAvailable;
+  };
+
+  export const Storage: {
+    saveData: typeof saveData;
+    getData: typeof getData;
+    getDataSync: typeof getDataSync;
+    updateData: typeof updateData;
+    deleteData: typeof deleteData;
+    clearAllData: typeof clearAllData;
+    hasData: typeof hasData;
+    getAllKeys: typeof getAllKeys;
+    getAllData: typeof getAllData;
+    getStorageSize: typeof getStorageSize;
+    deleteDataByPrefix: typeof deleteDataByPrefix;
+    deleteDataBySuffix: typeof deleteDataBySuffix;
+    getItemCount: typeof getItemCount;
+    isStorageAvailable: typeof isStorageAvailable;
+  };
+
   // =========================================================================
   // Layouts
   // =========================================================================
-  interface ContainerProps extends CommonProps {
+  export interface ContainerProps extends CommonProps {
     direction?: 'row' | 'column';
     gap?: number | string;
     justifyContent?: 'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly';
     alignItems?: 'flex-start' | 'center' | 'flex-end' | 'stretch';
-    wrap?: boolean;
+    wrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
     child?: Widget;
     children?: Widget[];
-    expand?: boolean;
+    expand?: boolean | number;
     flex?: number;
     minHeight?: Size;
     maxHeight?: Size;
@@ -141,17 +221,17 @@ declare module 'flet-box' {
   }
   export function Container(props: ContainerProps): Widget;
 
-  interface RowProps extends CommonProps {
+  export interface RowProps extends CommonProps {
     gap?: number | string;
     justifyContent?: ContainerProps['justifyContent'];
     alignItems?: ContainerProps['alignItems'];
-    wrap?: boolean;
+    wrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
     children?: Widget[];
     onPress?: (widget: Widget) => void;
   }
   export function Row(props: RowProps): Widget;
 
-  interface ColumnProps extends CommonProps {
+  export interface ColumnProps extends CommonProps {
     gap?: number | string;
     justifyContent?: ContainerProps['justifyContent'];
     alignItems?: ContainerProps['alignItems'];
@@ -160,14 +240,14 @@ declare module 'flet-box' {
   }
   export function Column(props: ColumnProps): Widget;
 
-  interface StackProps extends CommonProps {
+  export interface StackProps extends CommonProps {
     children?: Widget[];
     position?: 'relative' | 'absolute';
     alignment?: 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
   }
   export function Stack(props: StackProps): Widget;
 
-  interface ListViewProps extends CommonProps {
+  export interface ListViewProps extends CommonProps {
     data?: any[];
     renderItem?: (item: any, index: number) => Widget;
     height?: number | string;
@@ -184,7 +264,7 @@ declare module 'flet-box' {
     ListEmptyComponent?: (() => Widget) | Widget;
     showsScrollIndicator?: boolean;
     bufferSize?: number;
-    expand?: boolean;
+    expand?: boolean | number;
   }
   export function ListView(props: ListViewProps): Widget & {
     data: any[];
@@ -195,7 +275,7 @@ declare module 'flet-box' {
     scrollToEnd(animated?: boolean): void;
   };
 
-  interface GridViewProps extends Omit<ListViewProps, 'wrapItems' | 'crossAxisCount'> {
+  export interface GridViewProps extends Omit<ListViewProps, 'wrapItems' | 'crossAxisCount'> {
     columns?: number;
     spacing?: number;
     itemHeight?: number;
@@ -205,7 +285,7 @@ declare module 'flet-box' {
   // =========================================================================
   // Widgets básicos
   // =========================================================================
-  interface TextProps extends CommonProps {
+  export interface TextProps extends CommonProps {
     text?: string;
     value?: string;
     children?: string;
@@ -223,7 +303,7 @@ declare module 'flet-box' {
   }
   export function Text(props: TextProps): Widget;
 
-  interface ButtonProps extends CommonProps {
+  export interface ButtonProps extends CommonProps {
     text?: string;
     onPress?: () => void;
     variant?: 'filled' | 'outlined' | 'text';
@@ -246,7 +326,7 @@ declare module 'flet-box' {
   }
   export function Button(props: ButtonProps): Widget;
 
-  interface IconProps extends CommonProps {
+  export interface IconProps extends CommonProps {
     name: string;
     size?: number;
     color?: Color;
@@ -254,7 +334,7 @@ declare module 'flet-box' {
   }
   export function Icon(props: IconProps): Widget;
 
-  interface ImageProps extends CommonProps {
+  export interface ImageProps extends CommonProps {
     src: string;
     alt?: string;
     width?: Size;
@@ -267,7 +347,7 @@ declare module 'flet-box' {
   }
   export function Image(props: ImageProps): Widget;
 
-  interface AvatarProps extends CommonProps {
+  export interface AvatarProps extends CommonProps {
     src?: string;
     name?: string;
     icon?: string;
@@ -281,7 +361,7 @@ declare module 'flet-box' {
     updateContent(newProps: Partial<AvatarProps>): void;
   };
 
-  interface CardProps extends CommonProps {
+  export interface CardProps extends CommonProps {
     child?: Widget;
     children?: Widget[];
     elevation?: number;
@@ -295,11 +375,17 @@ declare module 'flet-box' {
   }
   export function Card(props: CardProps): Widget;
 
-  interface ListTileProps extends CommonProps {
+  export interface ListTileProps extends CommonProps {
     leftItem?: Widget;
     title?: string | Widget;
     subtitle?: string | Widget;
     description?: string | Widget;
+    /** Text props merged into the title, e.g. `{ size: 16, weight: "700" }`. */
+    titleProps?: Partial<TextProps>;
+    /** Text props merged into the subtitle. */
+    subtitleProps?: Partial<TextProps>;
+    /** Text props merged into the description line. */
+    descriptionProps?: Partial<TextProps>;
     rightItem?: Widget;
     onPress?: (widget: Widget) => void;
     selected?: boolean;
@@ -315,7 +401,7 @@ declare module 'flet-box' {
   }
   export function ListTile(props: ListTileProps): Widget;
 
-  interface ProgressBarProps extends CommonProps {
+  export interface ProgressBarProps extends CommonProps {
     value?: number;
     max?: number;
     height?: number;
@@ -337,7 +423,7 @@ declare module 'flet-box' {
     setValue(value: number): void;
   };
 
-  interface RatingProps extends CommonProps {
+  export interface RatingProps extends CommonProps {
     value?: number;
     max?: number;
     size?: number;
@@ -360,7 +446,7 @@ declare module 'flet-box' {
     getValue(): number;
   };
 
-  interface ChipProps extends CommonProps {
+  export interface ChipProps extends CommonProps {
     label: string;
     icon?: string;
     onPress?: () => void;
@@ -376,7 +462,7 @@ declare module 'flet-box' {
   }
   export function Chip(props: ChipProps): Widget;
 
-  interface AdSenseProps extends CommonProps {
+  export interface AdSenseProps extends CommonProps {
     client?: string;
     slot?: string;
     format?: string;
@@ -399,7 +485,7 @@ declare module 'flet-box' {
     getElement(): Widget;
   };
 
-  interface AdMobProps extends CommonProps {
+  export interface AdMobProps extends CommonProps {
     adId?: string;
     isTesting?: boolean;
     position?: 'top' | 'bottom';
@@ -430,7 +516,7 @@ declare module 'flet-box' {
     getPlugin(): object | null;
   };
 
-  interface BadgeProps extends CommonProps {
+  export interface BadgeProps extends CommonProps {
     value: string | number;
     child: Widget;
     bgColor?: Color;
@@ -447,7 +533,7 @@ declare module 'flet-box' {
     updateValue(newValue: string | number): void;
   };
 
-  interface SliderProps extends CommonProps {
+  export interface SliderProps extends Omit<CommonProps, 'onPress'> {
     value?: number;
     min?: number;
     max?: number;
@@ -469,6 +555,9 @@ declare module 'flet-box' {
     animatedStripes?: boolean;
     stripeColor?: string;
     glow?: boolean;
+    /** Canonical press/change callback, like every other FletBox widget. */
+    onPress?: (value: number) => void;
+    /** @deprecated Alias of `onPress`. */
     onChanged?: (value: number) => void;
     onChangeEnd?: (value: number) => void;
   }
@@ -482,7 +571,7 @@ declare module 'flet-box' {
     update(props: Partial<SliderProps>): void;
   };
 
-  interface AccordionProps extends CommonProps {
+  export interface AccordionProps extends CommonProps {
     title: string | Widget;
     children: Widget;
     expanded?: boolean;
@@ -513,7 +602,7 @@ declare module 'flet-box' {
     update(props: Partial<AccordionProps>): void;
   };
 
-  interface DividerProps extends CommonProps {
+  export interface DividerProps extends Omit<CommonProps, 'margin'> {
     color?: Color;
     thickness?: number;
     margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
@@ -524,7 +613,7 @@ declare module 'flet-box' {
   // =========================================================================
   // Formularios e interacción
   // =========================================================================
-  interface InputProps extends CommonProps {
+  export interface InputProps extends CommonProps {
     value?: string;
     placeholder?: string;
     type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'search' | 'url';
@@ -566,7 +655,7 @@ declare module 'flet-box' {
     blur(): void;
   };
 
-  interface RadioProps extends CommonProps {
+  export interface RadioProps extends CommonProps {
     selected?: boolean;
     onSelect?: (selected: boolean) => void;
     disabled?: boolean;
@@ -581,7 +670,7 @@ declare module 'flet-box' {
     isSelected(): boolean;
   };
 
-  interface SwitchProps extends CommonProps {
+  export interface SwitchProps extends CommonProps {
     value?: boolean;
     onToggle?: (value: boolean) => void;
     disabled?: boolean;
@@ -594,7 +683,7 @@ declare module 'flet-box' {
     getValue(): boolean;
   };
 
-  interface CheckboxProps extends CommonProps {
+  export interface CheckboxProps extends CommonProps {
     checked?: boolean;
     onCheck?: (checked: boolean) => void;
     disabled?: boolean;
@@ -607,8 +696,8 @@ declare module 'flet-box' {
     getChecked(): boolean;
   };
 
-  type DropdownOption = { label: string; value: any; icon?: string };
-  interface DropdownProps extends CommonProps {
+  export type DropdownOption = { label: string; value: any; icon?: string };
+  export interface DropdownProps extends CommonProps {
     options: (string | DropdownOption)[];
     value?: any;
     placeholder?: string;
@@ -640,7 +729,7 @@ declare module 'flet-box' {
   // =========================================================================
   // Alert dialogs and feedback
   // =========================================================================
-  interface SnackBarOptions {
+  export interface SnackBarOptions {
     message: string;
     action?: string;
     onAction?: () => void;
@@ -662,7 +751,7 @@ declare module 'flet-box' {
   }
   export function SnackBar(options: SnackBarOptions): { close(): void; show(): void; getElement(): Widget };
 
-  interface ModalProps {
+  export interface ModalProps {
     title?: string;
     content?: Widget | string;
     actions?: Widget[];
@@ -709,7 +798,7 @@ declare module 'flet-box' {
     setLoading(loading: boolean, loadingText?: string): void;
   };
 
-  interface BottomSheetProps {
+  export interface BottomSheetProps {
     content: Widget;
     title?: string;
     actions?: Widget[];
@@ -746,7 +835,7 @@ declare module 'flet-box' {
     destroy(): void;
   };
 
-  interface AlertDialogProps {
+  export interface AlertDialogProps {
     title: string;
     message: string;
     confirmText?: string;
@@ -768,7 +857,7 @@ declare module 'flet-box' {
   // =========================================================================
   // Navegación
   // =========================================================================
-  interface ScaffoldProps extends CommonProps {
+  export interface ScaffoldProps extends CommonProps {
     appBar?: Widget | boolean;
     body?: Widget | Record<string, any>;
     bottomBar?: Widget | boolean;
@@ -782,6 +871,7 @@ declare module 'flet-box' {
     navSideBarWidth?: number;
     navSideBarPosition?: 'left' | 'right';
     routes?: Record<string, any>;
+    basePath?: string;
     backgroundColor?: Color;
     closeDrawerOnNavigate?: boolean;
   }
@@ -794,7 +884,7 @@ declare module 'flet-box' {
     closeDrawer?(): void;
   };
 
-  interface AdaptiveScaffoldProps extends CommonProps {
+  export interface AdaptiveScaffoldProps extends CommonProps {
     appBar?: Widget;
     body?: Widget | Record<string, any>;
     bottomBar?: Widget;
@@ -818,7 +908,7 @@ declare module 'flet-box' {
     closeDrawer?(): void;
   };
 
-  interface AppBarProps extends CommonProps {
+  export interface AppBarProps extends Omit<CommonProps, 'shadow'> {
     title?: string | Widget;
     leading?: Widget;
     actions?: Widget[];
@@ -840,7 +930,7 @@ declare module 'flet-box' {
     margin?: Margin;
     padding?: Padding;
     borderRadius?: number;
-    shadow?: boolean;
+    shadow?: boolean | string;
   }
   export function AppBar(props: AppBarProps): Widget & {
     setTitle(title: string): void;
@@ -849,7 +939,7 @@ declare module 'flet-box' {
     hide(): void;
   };
 
-  interface DrawerItemProps extends CommonProps {
+  export interface DrawerItemProps extends CommonProps {
     icon?: string;
     label: string;
     route?: string;
@@ -866,14 +956,14 @@ declare module 'flet-box' {
   }
   export function DrawerItem(props: DrawerItemProps): Widget;
 
-  interface DrawerInstance {
+  export interface DrawerInstance {
     open(): void;
     close(): void;
     toggle(): void;
     destroy(): void;
     element: HTMLElement;
   }
-  interface DrawerProps {
+  export interface DrawerProps {
     header?: Widget;
     body?: Widget[];
     footer?: Widget;
@@ -896,7 +986,7 @@ declare module 'flet-box' {
   export function toggleDrawer(): void;
   export function destroyDrawer(): void;
 
-  interface BottomNavigationProps extends CommonProps {
+  export interface BottomNavigationProps extends Omit<CommonProps, 'shadow'> {
     items: Array<{ icon: string; label?: string; route?: string; onPress?: () => void }>;
     currentIndex?: number;
     onTabChange?: (index: number) => void;
@@ -909,7 +999,7 @@ declare module 'flet-box' {
     margin?: Margin;
     borderRadius?: number;
     padding?: Padding;
-    shadow?: boolean;
+    shadow?: boolean | string;
     elevation?: number;
     useRouter?: boolean;
   }
@@ -919,7 +1009,7 @@ declare module 'flet-box' {
     getCurrentRoute(): string | null;
   };
 
-  interface FloatingActionButtonProps extends CommonProps {
+  export interface FloatingActionButtonProps extends CommonProps {
     icon?: string | Widget;
     label?: string;
     onPress?: () => void;
@@ -933,7 +1023,7 @@ declare module 'flet-box' {
   }
   export function FloatingActionButton(props: FloatingActionButtonProps): Widget;
 
-  interface TabsProps extends CommonProps {
+  export interface TabsProps extends CommonProps {
     tabs: (string | { label: string; icon?: string; badge?: number | string })[];
     children: Widget[];
     activeIndex?: number;
@@ -959,7 +1049,7 @@ declare module 'flet-box' {
     setActiveTab(index: number): void;
   };
 
-  interface CollapsibleSideBarProps extends CommonProps {
+  export interface CollapsibleSideBarProps extends CommonProps {
     children: Widget;
     expanded?: boolean;
     id?: string;
@@ -997,7 +1087,7 @@ declare module 'flet-box' {
   // =========================================================================
   // Animations
   // =========================================================================
-  interface AnimationStep {
+  export interface AnimationStep {
     effect: string;
     from: any;
     to: any;
@@ -1006,7 +1096,7 @@ declare module 'flet-box' {
     loop?: boolean;
     delay?: string;
   }
-  interface AnimatedBoxProps extends CommonProps {
+  export interface AnimatedBoxProps extends CommonProps {
     animations: AnimationStep[];
     child: Widget;
     timing?: string;
@@ -1019,7 +1109,7 @@ declare module 'flet-box' {
   }
   export function AnimatedBox(props: AnimatedBoxProps): Widget;
 
-  interface AnimatedTextProps extends CommonProps {
+  export interface AnimatedTextProps extends CommonProps {
     child: Widget;
     animations: AnimationStep[];
     sameTime?: boolean;
@@ -1028,7 +1118,7 @@ declare module 'flet-box' {
   }
   export function AnimatedText(props: AnimatedTextProps): Widget;
 
-  interface MatrixRainProps extends CommonProps {
+  export interface MatrixRainProps extends CommonProps {
     chars?: string;
     fontSize?: number;
     speed?: number;
@@ -1040,7 +1130,7 @@ declare module 'flet-box' {
   }
   export function MatrixRain(props?: MatrixRainProps): Widget;
 
-  interface ParallaxBoxProps extends CommonProps {
+  export interface ParallaxBoxProps extends CommonProps {
     child: Widget;
     type?: 'scroll' | 'mouse' | 'hover';
     speed?: number;
@@ -1066,7 +1156,8 @@ declare module 'flet-box' {
     to: any,
     duration?: number,
     easing?: string
-  ): void;
+  ): () => boolean;
+  export function stopAnimation(widget: Widget, property?: string): boolean;
   export function animateAsync(
     widget: Widget,
     property: string,
@@ -1075,9 +1166,9 @@ declare module 'flet-box' {
     duration?: number,
     easing?: string
   ): Promise<Widget>;
-  export function fadeOut(widget: Widget, duration?: number): void;
-  export function fadeIn(widget: Widget, duration?: number): void;
-  export function pulse(widget: Widget, duration?: number): void;
+  export function fadeOut(widget: Widget, duration?: number): () => boolean;
+  export function fadeIn(widget: Widget, duration?: number): () => boolean;
+  export function pulse(widget: Widget, duration?: number): () => boolean;
   export function fadeOutAsync(widget: Widget, duration?: number): Promise<Widget>;
   export function fadeInAsync(widget: Widget, duration?: number): Promise<Widget>;
   export function pulseAsync(widget: Widget, duration?: number): Promise<Widget>;
@@ -1085,13 +1176,13 @@ declare module 'flet-box' {
   // =========================================================================
   // Widgets adicionales (Data, Media, Utils)
   // =========================================================================
-  interface DataTableColumn {
+  export interface DataTableColumn {
     key: string;
     label: string;
     align?: 'left' | 'center' | 'right';
     format?: (value: any, row: any) => string;
   }
-  interface DataTableProps extends CommonProps {
+  export interface DataTableProps extends CommonProps {
     columns: (string | DataTableColumn)[];
     rows: Record<string, any>[];
     striped?: boolean;
@@ -1117,7 +1208,7 @@ declare module 'flet-box' {
     updateColumns(columns: DataTableColumn[]): void;
   };
 
-  interface ChartProps extends CommonProps {
+  export interface ChartProps extends Omit<CommonProps, 'padding'> {
     type?: 'bar' | 'line' | 'area' | 'candle';
     data: number[] | Array<{ open: number; high: number; low: number; close: number }>;
     labels?: string[];
@@ -1148,7 +1239,7 @@ declare module 'flet-box' {
     redraw(): void;
   };
 
-  interface QRCodeProps extends CommonProps {
+  export interface QRCodeProps extends CommonProps {
     value: string;
     size?: number;
     bgColor?: Color;
@@ -1164,7 +1255,7 @@ declare module 'flet-box' {
     getValue(): string;
   };
 
-  interface CodeViewerProps extends CommonProps {
+  export interface CodeViewerProps extends CommonProps {
     code: string;
     title?: string;
     maxHeight?: number;
@@ -1186,7 +1277,7 @@ declare module 'flet-box' {
     scrollToEnd(): void;
   };
 
-  interface InspectorProps {
+  export interface InspectorProps {
     widget: Widget;
     indent?: number;
   }
@@ -1194,7 +1285,7 @@ declare module 'flet-box' {
   export function printWidgetCode(widget: Widget): void;
   export function inspectWidget(widget: Widget): Widget;
 
-  interface DraggBoxProps extends CommonProps {
+  export interface DraggBoxProps extends CommonProps {
     child: Widget;
     data?: any;
     group?: string;
@@ -1209,7 +1300,7 @@ declare module 'flet-box' {
   }
   export function DraggBox(props: DraggBoxProps): Widget;
 
-  interface DroppBoxProps extends CommonProps {
+  export interface DroppBoxProps extends CommonProps {
     child: Widget;
     onDrop?: (data: any, group: string, event: DragEvent) => void;
     onDragEnter?: (event: DragEvent) => void;
@@ -1239,7 +1330,7 @@ declare module 'flet-box' {
   }
   export function DroppBox(props: DroppBoxProps): Widget;
 
-  interface CarouselProps extends CommonProps {
+  export interface CarouselProps extends CommonProps {
     items: (Widget | string | { src: string; alt?: string })[];
     autoPlay?: boolean;
     interval?: number;
@@ -1267,7 +1358,7 @@ declare module 'flet-box' {
     getCurrentIndex(): number;
   };
 
-  interface TooltipProps extends CommonProps {
+  export interface TooltipProps extends CommonProps {
     text: string;
     child: Widget;
     position?: 'top' | 'bottom' | 'left' | 'right';
@@ -1296,7 +1387,7 @@ declare module 'flet-box' {
     updatePosition(): void;
   };
 
-  interface PaginationProps extends CommonProps {
+  export interface PaginationProps extends CommonProps {
     totalItems: number;
     pageSize?: number;
     currentPage?: number;
@@ -1313,7 +1404,7 @@ declare module 'flet-box' {
   }
   export function Pagination(props: PaginationProps): Widget;
 
-  interface TreeViewProps extends CommonProps {
+  export interface TreeViewProps extends CommonProps {
     nodes: Array<{
       id: string;
       label: string;
@@ -1362,7 +1453,7 @@ declare module 'flet-box' {
     setSelected(nodeId: string): void;
   };
 
-  interface StepperProps extends CommonProps {
+  export interface StepperProps extends CommonProps {
     steps: Array<{ label: string; content: Widget; icon?: string }>;
     activeStep?: number;
     onStepChange?: (index: number) => void;
@@ -1391,7 +1482,7 @@ declare module 'flet-box' {
     getActiveStep(): number;
   };
 
-  interface SkeletonProps extends CommonProps {
+  export interface SkeletonProps extends CommonProps {
     variant?: 'text' | 'circular' | 'avatar' | 'image' | 'card' | 'listTile' | 'button';
     width?: number | string;
     height?: number | string;
@@ -1407,7 +1498,7 @@ declare module 'flet-box' {
   }
   export function Skeleton(props: SkeletonProps): Widget;
 
-  interface InstallButtonProps extends CommonProps {
+  export interface InstallButtonProps extends CommonProps {
     text?: string;
     variant?: 'filled' | 'outlined' | 'text';
     size?: 'small' | 'medium' | 'large';
@@ -1419,7 +1510,7 @@ declare module 'flet-box' {
   }
   export function InstallButton(props: InstallButtonProps): Widget;
 
-  interface VideoProps extends CommonProps {
+  export interface VideoProps extends Omit<CommonProps, 'ref'> {
     src: string;
     width?: number | string;
     height?: number | string;
@@ -1441,7 +1532,7 @@ declare module 'flet-box' {
     unmuteVideo(): void;
   };
 
-  interface AudioProps extends CommonProps {
+  export interface AudioProps extends Omit<CommonProps, 'ref'> {
     src: string;
     autoplay?: boolean;
     controls?: boolean;
@@ -1472,7 +1563,7 @@ declare module 'flet-box' {
     isPlaying(): boolean;
   };
 
-  interface CircularBarProps extends CommonProps {
+  export interface CircularBarProps extends Omit<CommonProps, 'onClick' | 'ref'> {
     value?: number;
     max?: number;
     size?: number;
@@ -1516,13 +1607,13 @@ declare module 'flet-box' {
     updateValue(newValue: number, newMax?: number): void;
   };
 
-  interface CircularChartSlice {
+  export interface CircularChartSlice {
     value: number;
     label?: string;
     color?: Color;
   }
 
-  interface CircularChartProps extends CommonProps {
+  export interface CircularChartProps extends Omit<CommonProps, 'onClick' | 'ref'> {
     data?: CircularChartSlice[];
     size?: number;
     strokeWidth?: number;
@@ -1559,7 +1650,7 @@ declare module 'flet-box' {
     setCornerRadius(radius: number): void;
   };
 
-  interface MarkdownProps extends CommonProps {
+  export interface MarkdownProps extends CommonProps {
     text?: string;
     source?: string;
     content?: string;
@@ -1612,16 +1703,37 @@ declare module 'flet-box' {
   // =========================================================================
   // Core
   // =========================================================================
-  export function runApp(App: () => Widget, rootId?: string, preventRefresh?: boolean, routes?: any): void;
+  export function runApp(
+    App: (() => Widget) | Widget,
+    rootId?: string,
+    preventRefresh?: boolean,
+    routes?: any
+  ): { destroy(): void };
+
+  /**
+   * Mounts a single widget into `#root`, creating the container when it is
+   * missing. Never clears `document.body`. Returns the root container.
+   */
+  export function App(widget: Widget): Widget;
+
+  /**
+   * The only rendering engine. Turns a tag (or config object) plus props into a
+   * real `HTMLElement` with styles, events, children, lifecycle and reactivity.
+   */
+  export function WidgetFactory(
+    tag: string | { tag?: string; [prop: string]: any },
+    customProps?: Record<string, any>
+  ): WidgetFactoryInstance;
+
   export function createApp(routes: any, options?: { rootId?: string; fallback?: Widget | (() => Widget) }): {
     start(): void;
     destroy(): void;
   };
   export function insertBy(widget: Widget, rootId?: string): Widget;
   export function prependBy(widget: Widget, rootId?: string): Widget;
-  export function insertBefore(widget: Widget, targetId: string | HTMLElement): Widget;
-  export function insertAfter(widget: Widget, targetId: string | HTMLElement): Widget;
-  export function replaceBy(widget: Widget, targetId: string | HTMLElement): Widget;
+  export function insertBefore(widget: Widget, targetId: string): Widget;
+  export function insertAfter(widget: Widget, targetId: string): Widget;
+  export function replaceBy(widget: Widget, targetId: string): Widget;
   export function mountAll(widget: Widget, rootIds: string[]): Widget;
 
   // =========================================================================
@@ -1824,7 +1936,12 @@ declare module 'flet-box' {
   export function padding(value: number | string | { all?: number; horizontal?: number; vertical?: number; top?: number; right?: number; bottom?: number; left?: number }): string;
   export function gradient(type: 'linear' | 'circle' | 'conic', colors: string[], angle?: number): string;
   export function shadow(x: number, y: number, blur: number, spread: number, color: string): string;
-  export const color: (value: string) => {
+  /**
+   * Fluent color instance returned by `color()`. The chained methods mutate this
+   * very instance and return it, which is why their type is `this` and not a
+   * fixed interface name.
+   */
+  export interface ColorInstance {
     hex(): string;
     rgb(): string;
     rgba(): string;
@@ -1835,7 +1952,9 @@ declare module 'flet-box' {
     isDark(): boolean;
     isLight(): boolean;
     contrast(): string;
-  };
+  }
+
+  export const color: (value: string) => ColorInstance;
   export function rgba(r: number, g: number, b: number, a?: number): string;
   export function stackPosition(widget: Widget, props: { top?: any; right?: any; bottom?: any; left?: any }): Widget;
   export function flex(grow: number | { grow?: number; shrink?: number; basis?: string }, shrink?: number, basis?: string): string;
@@ -1890,6 +2009,23 @@ declare module 'flet-box' {
   export function memoWithKey<T extends (...args: any[]) => any>(fn: T, keyFn: (...args: Parameters<T>) => string): T;
   export function clearMemo(memoizedFn: any): void;
 
+  /**
+   * Thin `console` wrapper that adds a level icon plus optional timestamp and
+   * label. The second argument may also be the options object (legacy style).
+   */
+  export function print(
+    message: any,
+    type?:
+      | "log"
+      | "warn"
+      | "error"
+      | "info"
+      | "success"
+      | "debug"
+      | { timestamp?: boolean; label?: string; prefix?: boolean },
+    options?: { timestamp?: boolean; label?: string; prefix?: boolean }
+  ): void;
+
   export function setBaseFontSize(size: number): void;
   export function toREM(value: number | string): string | undefined;
   export function toPX(value: number | string): string | undefined;