flet-box 1.1.2 → 1.1.3

package/src/index.d.ts

@@ -1,13 +1,13 @@
 // index.d.ts - FletBox Type Declarations
-// Versión completa con todos los widgets, animaciones, servicios y utilidades
+// Full version with every widget, animation, service and utility
 
 declare module 'flet-box' {
   // =========================================================================
-  // Tipos base
+  // Base types
   // =========================================================================
   export type Widget = HTMLElement;
   // A Scaffold slot: an element, a factory it re-runs on each route change (so a
-  // nav can relight the active item), a boolean show/hide, or null for absent.
+  // nav can re-render the active item), a boolean show/hide, or null for absent.
   export type Slot = Widget | (() => Widget) | boolean | null;
   export type Color = string;
   export type Size = number | string;
@@ -35,6 +35,14 @@ declare module 'flet-box' {
     _cleanup(): void;
   }
 
+  /**
+   * The live element every widget constructor returns. It is the factory
+   * instance: a real `HTMLElement` that also carries `update()`, `getProps()`,
+   * `onMount()` and `onUnmount()`. Typing widgets as bare `HTMLElement` made
+   * `estado.update({ text })` — the documented reactive call — an editor error.
+   */
+  export type FletWidget = WidgetFactoryInstance;
+
   // =========================================================================
   // Posicionamiento
   // =========================================================================
@@ -74,7 +82,7 @@ declare module 'flet-box' {
   }
 
   // =========================================================================
-  // Props comunes (heredadas by todos the widgets)
+  // Common props (inherited by every widget)
   // =========================================================================
   export interface CommonProps extends StackPositionProps {
     width?: Size;
@@ -99,7 +107,30 @@ declare module 'flet-box' {
     // The engine routes `display` untouched; `Stack` sets it internally and an
     // app that overrides it is doing something the type must not forbid.
     display?: string;
+    // The rest of the layout and border styles the engine already routes on
+    // every widget (`translateProps.js`). Declaring them only on `Container`
+    // made `Column({ flexDirection: "row", flexGrow: 1 })` — the recipe the
+    // layout skill teaches — a false error in a JS editor.
+    boxSizing?: 'border-box' | 'content-box';
+    flexDirection?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+    flexGrow?: number;
+    flexShrink?: number;
+    gap?: number | string;
+    fontSize?: number;
+    borderColor?: Color;
+    borderWidth?: number;
     padding?: Padding;
+    // The engine routes each padding side, and the `pt/pr/pb/pl` aliases, as rem
+    // lengths on every widget, exactly like the margins below: `AppBar` reads
+    // the top one to keep its title clear of a notch.
+    paddingTop?: Size;
+    paddingRight?: Size;
+    paddingBottom?: Size;
+    paddingLeft?: Size;
+    pt?: Size;
+    pr?: Size;
+    pb?: Size;
+    pl?: Size;
     margin?: Margin;
     // The engine routes each margin side, and the `mt/mr/mb/ml` aliases, as rem
     // lengths on every widget: `Text({ marginTop: 4 })` is legal at runtime.
@@ -125,28 +156,58 @@ declare module 'flet-box' {
     filter?: string;
     backdropFilter?: string;
     maskImage?: string;
+    // The engine routes these four on every widget (`bgImage` → `backgroundImage`
+    // in translateProps.js). They are the only way to bias a crop: an `Image`
+    // with `fit: 'cover'` centres on its own, while a full-bleed background can
+    // be pinned to `center top` so a face stays out from under the copy.
+    bgImage?: string;
+    bgSize?: string;
+    bgPosition?: string;
+    bgRepeat?: string;
     opacity?: number;
     visible?: boolean;
     disabled?: boolean;
-    onPress?: (widget: Widget) => void;
-    onClick?: (widget: Widget) => void;
+    // The handler receives a DOM Event on every widget that forwards the click
+    // through the engine (Container, Row, Column, Text, Button, Icon, Image,
+    // Avatar, Card, ListTile). A widget that answers with a value declares its
+    // own: Switch/Checkbox/Radio pass the new boolean, Accordion the expanded
+    // state. `(widget: Widget)` named an argument no call site ever received,
+    // so a correct `onPress: (checked: boolean) => ...` was underlined.
+    onPress?: (event?: Event) => void;
+    onClick?: (event?: Event) => void;
     // The lowercase alias the engine also routes (`{ prop: "onclick" }` in
     // translateProps); the generated AppBar reaches for it.
-    onclick?: (widget: Widget) => void;
+    onclick?: (event?: Event) => void;
     // A child's own cross-axis answer to its parent's `alignItems`. It belongs on
     // `CommonProps` rather than on the layouts because the widget that needs it is
     // the *child* — a chip centred inside a row whose other children stretch.
     alignSelf?: AlignSelf;
     // Alias of `alignSelf`, matching the `justify` / `alignItems` shorthand style.
     selfAlign?: AlignSelf;
+    // Text-clamping trio. The engine routes all three on any widget
+    // (`translateProps.js`), and the one-line ellipsis recipe
+    // (`overflow: 'hidden'` + `textOverflow: 'ellipsis'` + `whiteSpace: 'nowrap'`)
+    // is written on a `Text`, which used to reject it as an unknown prop.
+    overflow?: 'auto' | 'hidden' | 'visible' | 'scroll' | 'clip';
+    overflowX?: 'auto' | 'hidden' | 'visible' | 'scroll' | 'clip';
+    overflowY?: 'auto' | 'hidden' | 'visible' | 'scroll' | 'clip';
+    textOverflow?: 'clip' | 'ellipsis' | string;
+    whiteSpace?: 'normal' | 'nowrap' | 'pre' | 'pre-wrap' | 'pre-line' | string;
     id?: string;
     className?: string;
     ref?: (widget: Widget) => void;
     disableTransform?: boolean;
+    // Every `data-*` and `aria-*` prop is forwarded to the DOM untouched —
+    // `PASSTHROUGH_PREFIXES` in translateProps.js is the engine's own list — so
+    // the type has to allow what the engine honours. An icon-only control has no
+    // other way to say what it is, and a declaration that forbids `aria-label`
+    // teaches an editor to flag the one line that makes a widget accessible.
+    [attribute: `aria-${string}`]: string | number | undefined;
+    [attribute: `data-${string}`]: string | number | boolean | undefined;
   }
 
   // =========================================================================
-  // useState Hook (persistente with RamStore)
+  // useState Hook (persistent across page reloads with RamStore)
   // =========================================================================
   export function useState<T>(
     key: string,
@@ -306,7 +367,7 @@ declare module 'flet-box' {
     maxWidth?: Size;
     overflow?: 'auto' | 'hidden' | 'visible' | 'scroll';
   }
-  export function Container(props: ContainerProps): Widget;
+  export function Container(props: ContainerProps): FletWidget;
 
   export interface RowProps extends CommonProps {
     gap?: number | string;
@@ -314,18 +375,18 @@ declare module 'flet-box' {
     alignItems?: ContainerProps['alignItems'];
     wrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
     children?: Widget[];
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Row(props: RowProps): Widget;
+  export function Row(props: RowProps): FletWidget;
 
   export interface ColumnProps extends CommonProps {
     gap?: number | string;
     justifyContent?: ContainerProps['justifyContent'];
     alignItems?: ContainerProps['alignItems'];
     children?: Widget[];
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Column(props: ColumnProps): Widget;
+  export function Column(props: ColumnProps): FletWidget;
 
   /**
    * Layers its children in the same box.
@@ -343,7 +404,7 @@ declare module 'flet-box' {
     position?: 'relative' | 'absolute' | 'stack';
     alignment?: 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
   }
-  export function Stack(props: StackProps): Widget;
+  export function Stack(props: StackProps): FletWidget;
 
   export interface ListViewProps extends CommonProps {
     data?: any[];
@@ -364,7 +425,7 @@ declare module 'flet-box' {
     bufferSize?: number;
     expand?: boolean | number;
   }
-  export function ListView(props: ListViewProps): Widget & {
+  export function ListView(props: ListViewProps): FletWidget & {
     data: any[];
     refreshing: boolean;
     updateData(newData: any[]): void;
@@ -384,7 +445,7 @@ declare module 'flet-box' {
      */
     children?: Widget[] | Widget;
   }
-  export function GridView(props: GridViewProps): Widget;
+  export function GridView(props: GridViewProps): FletWidget;
 
   // =========================================================================
   // Widgets básicos
@@ -395,17 +456,24 @@ declare module 'flet-box' {
     children?: string;
     size?: number;
     color?: Color;
-    weight?: 'normal' | 'bold' | number;
+    // CSS `font-weight`: the two keywords, the numeric scale as a number or as
+    // the same scale written as a string (`'600'` is what a design token table
+    // prints), and the relative keywords the engine forwards untouched.
+    weight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | number;
     align?: 'left' | 'center' | 'right' | 'justify';
     italic?: boolean;
     decoration?: 'underline' | 'line-through' | 'overline';
     lineHeight?: number | string;
     letterSpacing?: number | string;
+    /** Glyph outline, e.g. `"4px #fff"` (-webkit-text-stroke). Pair with paintOrder. */
+    textStroke?: string;
+    /** `"stroke fill"` puts the textStroke rim behind the fill so the centre keeps its colour. */
+    paintOrder?: string;
     type?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p';
     styles?: Array<'bold' | 'italic' | 'underline' | 'strikethrough' | 'mark' | 'small' | 'code'>;
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Text(props: TextProps): Widget;
+  export function Text(props: TextProps): FletWidget;
 
   export interface ButtonProps extends CommonProps {
     text?: string;
@@ -428,15 +496,18 @@ declare module 'flet-box' {
     padding?: Padding;
     margin?: Margin;
   }
-  export function Button(props: ButtonProps): Widget;
+  export function Button(props: ButtonProps): FletWidget;
 
   export interface IconProps extends CommonProps {
-    name: string;
+    // `icon` is the runtime alias the widget reads first (`icon || name`), so
+    // both spellings describe a glyph and neither is the odd one out.
+    name?: string;
+    icon?: string;
     size?: number;
     color?: Color;
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Icon(props: IconProps): Widget;
+  export function Icon(props: IconProps): FletWidget;
 
   export interface ImageProps extends CommonProps {
     src: string;
@@ -449,9 +520,9 @@ declare module 'flet-box' {
     downloadFileName?: string;
     onLoad?: (widget: Widget) => void;
     onError?: (widget: Widget) => void;
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Image(props: ImageProps): Widget;
+  export function Image(props: ImageProps): FletWidget;
 
   export interface AvatarProps extends CommonProps {
     src?: string;
@@ -463,9 +534,9 @@ declare module 'flet-box' {
     shape?: 'circle' | 'rounded' | 'square';
     online?: boolean;
     badgeColor?: Color;
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Avatar(props: AvatarProps): Widget & {
+  export function Avatar(props: AvatarProps): FletWidget & {
     updateContent(newProps: Partial<AvatarProps>): void;
   };
 
@@ -479,9 +550,9 @@ declare module 'flet-box' {
     borderWidth?: number;
     borderStyle?: 'solid' | 'dashed' | 'dotted';
     borderColor?: Color;
-    onPress?: (widget: Widget) => void;
+    onPress?: (event?: Event) => void;
   }
-  export function Card(props: CardProps): Widget;
+  export function Card(props: CardProps): FletWidget;
 
   export interface ListTileProps extends CommonProps {
     leftItem?: Widget;
@@ -495,7 +566,9 @@ declare module 'flet-box' {
     /** Text props merged into the description line. */
     descriptionProps?: Partial<TextProps>;
     rightItem?: Widget;
-    onPress?: (widget: Widget) => void;
+    /** Space between the left item, the text column and the right item. */
+    gap?: number;
+    onPress?: (event?: Event) => void;
     selected?: boolean;
     disabled?: boolean;
     divider?: boolean;
@@ -507,7 +580,7 @@ declare module 'flet-box' {
     elevation?: number;
     borderRadius?: number;
   }
-  export function ListTile(props: ListTileProps): Widget;
+  export function ListTile(props: ListTileProps): FletWidget;
 
   export interface ProgressBarProps extends CommonProps {
     value?: number;
@@ -524,7 +597,7 @@ declare module 'flet-box' {
     striped?: boolean;
     animatedStripes?: boolean;
   }
-  export function ProgressBar(props: ProgressBarProps): Widget & {
+  export function ProgressBar(props: ProgressBarProps): FletWidget & {
     value: number;
     updateProgress(value: number): void;
     getValue(): number;
@@ -548,7 +621,7 @@ declare module 'flet-box' {
     iconHalf?: string;
     onChange?: (value: number) => void;
   }
-  export function Rating(props: RatingProps): Widget & {
+  export function Rating(props: RatingProps): FletWidget & {
     value: number;
     setValue(value: number): void;
     getValue(): number;
@@ -570,7 +643,7 @@ declare module 'flet-box' {
     elevation?: number;
     gap?: number;
   }
-  export function Chip(props: ChipProps): Widget;
+  export function Chip(props: ChipProps): FletWidget;
 
   export interface AdSenseProps extends CommonProps {
     client?: string;
@@ -589,7 +662,7 @@ declare module 'flet-box' {
     onError?: (error: Error, widget: Widget) => void;
     children?: Widget[];
   }
-  export function AdSense(props: AdSenseProps): Widget & {
+  export function AdSense(props: AdSenseProps): FletWidget & {
     refresh(): Widget;
     load(): void;
     getElement(): Widget;
@@ -618,7 +691,7 @@ declare module 'flet-box' {
     onFailed?: (error: Error, widget: Widget) => void;
     onDismissed?: () => void;
   }
-  export function AdMob(props: AdMobProps): Widget & {
+  export function AdMob(props: AdMobProps): FletWidget & {
     show(): Promise<unknown>;
     hide(): Promise<unknown>;
     showInterstitial(): Promise<unknown>;
@@ -639,7 +712,7 @@ declare module 'flet-box' {
     showZero?: boolean;
     max?: number;
   }
-  export function Badge(props: BadgeProps): Widget & {
+  export function Badge(props: BadgeProps): FletWidget & {
     updateValue(newValue: string | number): void;
   };
 
@@ -653,6 +726,8 @@ declare module 'flet-box' {
     height?: number;
     thumbSize?: number;
     color?: Color;
+    /** Colour of the knob alone, when it must differ from the filled track. */
+    thumbColor?: Color;
     trackColor?: Color;
     orientation?: 'horizontal' | 'vertical';
     inverted?: boolean;
@@ -671,7 +746,7 @@ declare module 'flet-box' {
     onChanged?: (value: number) => void;
     onChangeEnd?: (value: number) => void;
   }
-  export function Slider(props: SliderProps): Widget & {
+  export function Slider(props: SliderProps): FletWidget & {
     value: number;
     min: number;
     max: number;
@@ -681,16 +756,23 @@ declare module 'flet-box' {
     update(props: Partial<SliderProps>): void;
   };
 
-  export interface AccordionProps extends CommonProps {
+  export interface AccordionProps extends Omit<CommonProps, 'onPress'> {
     title: string | Widget;
     children: Widget;
     expanded?: boolean;
+    /**
+     * @deprecated Use `onPress` instead — it receives the same boolean.
+     */
     onToggle?: (expanded: boolean) => void;
+    /** Fired with the new expanded state when a panel opens or closes. */
+    onPress?: (expanded: boolean) => void;
     variant?: 'contained' | 'outlined' | 'ghost';
     borderRadius?: number;
     bgColor?: Color;
     expandedColor?: Color;
     titleColor?: Color;
+    /** Colour of the rule between the header and the panel. */
+    dividerColor?: Color;
     titleSize?: number;
     titleWeight?: string;
     titlePadding?: string;
@@ -705,7 +787,7 @@ declare module 'flet-box' {
     animationDuration?: number;
     elevation?: number;
   }
-  export function Accordion(props: AccordionProps): Widget & {
+  export function Accordion(props: AccordionProps): FletWidget & {
     expanded: boolean;
     setExpanded(exp: boolean, triggerCallback?: boolean): void;
     toggle(): void;
@@ -718,7 +800,7 @@ declare module 'flet-box' {
     margin?: number | { top?: number; right?: number; bottom?: number; left?: number };
     orientation?: 'horizontal' | 'vertical';
   }
-  export function Divider(props?: DividerProps): Widget;
+  export function Divider(props?: DividerProps): FletWidget;
 
   // =========================================================================
   // Formularios e interacción
@@ -755,7 +837,9 @@ declare module 'flet-box' {
     onBlur?: (event: Event) => void;
     onEnter?: (value: string, event: Event) => void;
   }
-  export function Input(props: InputProps): Widget & {
+  export function Input(props: InputProps): FletWidget & {
+    /** The native `<input>` the widget painted: the only place `placeholder` and `value` are visible. */
+    _input: HTMLInputElement;
     getValue(): string;
     setValue(value: string): void;
     isValid(): boolean;
@@ -765,37 +849,52 @@ declare module 'flet-box' {
     blur(): void;
   };
 
-  export interface RadioProps extends CommonProps {
+  export interface RadioProps extends Omit<CommonProps, 'onPress'> {
     selected?: boolean;
+    /**
+     * @deprecated Use `onPress` instead — it receives the same boolean.
+     */
     onSelect?: (selected: boolean) => void;
+    /** Fired with the new state when the radio is picked. */
+    onPress?: (selected: boolean) => void;
     disabled?: boolean;
     size?: number;
     activeColor?: Color;
     label?: string;
     name?: string;
   }
-  export function Radio(props: RadioProps): Widget & {
+  export function Radio(props: RadioProps): FletWidget & {
     select(): void;
     unselect(): void;
     isSelected(): boolean;
   };
 
-  export interface SwitchProps extends CommonProps {
+  export interface SwitchProps extends Omit<CommonProps, 'onPress'> {
     value?: boolean;
+    /**
+     * @deprecated Use `onPress` instead — it receives the same boolean.
+     */
     onToggle?: (value: boolean) => void;
+    /** Fired with the new state when the switch is flipped. */
+    onPress?: (value: boolean) => void;
     disabled?: boolean;
     size?: 'small' | 'medium' | 'large';
     activeColor?: Color;
     label?: string;
   }
-  export function Switch(props: SwitchProps): Widget & {
+  export function Switch(props: SwitchProps): FletWidget & {
     updateValue(value: boolean): void;
     getValue(): boolean;
   };
 
-  export interface CheckboxProps extends CommonProps {
+  export interface CheckboxProps extends Omit<CommonProps, 'onPress'> {
     checked?: boolean;
+    /**
+     * @deprecated Use `onPress` instead — it receives the same boolean.
+     */
     onCheck?: (checked: boolean) => void;
+    /** Fired with the new state when the box is ticked or cleared. */
+    onPress?: (checked: boolean) => void;
     disabled?: boolean;
     size?: number;
     activeColor?: Color;
@@ -807,20 +906,23 @@ declare module 'flet-box' {
      */
     variant?: 'outlined' | 'filled';
   }
-  export function Checkbox(props: CheckboxProps): Widget & {
+  export function Checkbox(props: CheckboxProps): FletWidget & {
     setChecked(checked: boolean, triggerCallback?: boolean): void;
     getChecked(): boolean;
   };
 
   export type DropdownOption = { label: string; value: any; icon?: string };
-  export interface DropdownProps extends CommonProps {
+  export interface DropdownProps extends Omit<CommonProps, 'onPress'> {
     options: (string | DropdownOption)[];
     value?: any;
     placeholder?: string;
     disabled?: boolean;
     label?: string;
     error?: boolean;
-    variant?: 'outlined' | 'filled';
+    // `text` is not a preset the widget styles — it is the honest name for
+    // "no chrome": transparent, borderless, just the label and the chevron,
+    // which is how an inline model picker inside a composer is built.
+    variant?: 'outlined' | 'filled' | 'text';
     size?: 'small' | 'medium' | 'large';
     borderRadius?: number;
     color?: Color;
@@ -830,9 +932,18 @@ declare module 'flet-box' {
     clearable?: boolean;
     width?: number | string;
     portal?: boolean;
-    onChange?: (value: any, label: string) => void;
+    /**
+     * @deprecated Use `onPress` instead — it receives the same value.
+     */
+    onChange?: (value: any) => void;
+    /**
+     * Fired when the selection changes, with the chosen value; `null` when the
+     * selection is cleared. Only the value is sent — read the label from the
+     * option that carries it.
+     */
+    onPress?: (value: any) => void;
   }
-  export function Dropdown(props: DropdownProps): Widget & {
+  export function Dropdown(props: DropdownProps): FletWidget & {
     value: any;
     options: DropdownOption[];
     disabled: boolean;
@@ -984,15 +1095,27 @@ declare module 'flet-box' {
     leftNavBarWidth?: number;
     rightNavBar?: Slot;
     rightNavBarWidth?: number;
+    /**
+     * @deprecated Use `leftNavBar` (or `rightNavBar`) instead.
+     */
     navSideBar?: Slot;
+    /**
+     * @deprecated Use `leftNavBarWidth` (or `rightNavBarWidth`) instead. The
+     * legacy name was accepted and then ignored — the panel kept the default
+     * width, so a width written here never reached the screen.
+     */
     navSideBarWidth?: number;
+    /**
+     * @deprecated The legacy sidebar needed this to say which side it was on.
+     * `leftNavBar` and `rightNavBar` say it with their own name.
+     */
     navSideBarPosition?: 'left' | 'right';
     routes?: Record<string, any>;
     basePath?: string;
     backgroundColor?: Color;
     closeDrawerOnNavigate?: boolean;
   }
-  export function Scaffold(props: ScaffoldProps): Widget & {
+  export function Scaffold(props: ScaffoldProps): FletWidget & {
     updateLeftNavBar(cfg: any): void;
     updateRightNavBar(cfg: any): void;
     setLeftNavBarWidth(width: number): void;
@@ -1016,7 +1139,7 @@ declare module 'flet-box' {
     forceMobile?: boolean;
     forceDesktop?: boolean;
   }
-  export function AdaptiveScaffold(props: AdaptiveScaffoldProps): Widget & {
+  export function AdaptiveScaffold(props: AdaptiveScaffoldProps): FletWidget & {
     updateLeftNavBar(cfg: any): void;
     updateRightNavBar(cfg: any): void;
     setLeftNavBarWidth(width: number): void;
@@ -1049,7 +1172,7 @@ declare module 'flet-box' {
     borderRadius?: number;
     shadow?: boolean | string;
   }
-  export function AppBar(props: AppBarProps): Widget & {
+  export function AppBar(props: AppBarProps): FletWidget & {
     setTitle(title: string): void;
     setBackgroundColor(color: string): void;
     show(): void;
@@ -1060,6 +1183,8 @@ declare module 'flet-box' {
     icon?: string;
     label: string;
     route?: string;
+    /** Space between the icon, the label and the trailing icon. */
+    gap?: number;
     onPress?: () => void;
     onSelect?: () => void;
     trailingIcon?: string;
@@ -1071,7 +1196,7 @@ declare module 'flet-box' {
     closeOnPress?: boolean;
     disableTransform?: boolean;
   }
-  export function DrawerItem(props: DrawerItemProps): Widget;
+  export function DrawerItem(props: DrawerItemProps): FletWidget;
 
   export interface DrawerInstance {
     open(): void;
@@ -1120,7 +1245,7 @@ declare module 'flet-box' {
     elevation?: number;
     useRouter?: boolean;
   }
-  export function BottomNavigation(props: BottomNavigationProps): Widget & {
+  export function BottomNavigation(props: BottomNavigationProps): FletWidget & {
     setActiveIndex(index: number): void;
     getActiveIndex(): number;
     getCurrentRoute(): string | null;
@@ -1138,7 +1263,7 @@ declare module 'flet-box' {
     disabled?: boolean;
     margin?: number;
   }
-  export function FloatingActionButton(props: FloatingActionButtonProps): Widget;
+  export function FloatingActionButton(props: FloatingActionButtonProps): FletWidget;
 
   export interface TabsProps extends CommonProps {
     tabs: (string | { label: string; icon?: string; badge?: number | string })[];
@@ -1161,7 +1286,7 @@ declare module 'flet-box' {
     badges?: (number | string)[];
     alignment?: 'left' | 'center' | 'right';
   }
-  export function Tabs(props: TabsProps): Widget & {
+  export function Tabs(props: TabsProps): FletWidget & {
     activeIndex: number;
     setActiveTab(index: number): void;
   };
@@ -1177,7 +1302,7 @@ declare module 'flet-box' {
     bgColor?: Color;
     borderRight?: string;
   }
-  export function CollapsibleSideBar(props: CollapsibleSideBarProps): Widget & {
+  export function CollapsibleSideBar(props: CollapsibleSideBarProps): FletWidget & {
     updateWidth(width: number): void;
   };
 
@@ -1228,7 +1353,7 @@ declare module 'flet-box' {
     bottom?: number | string;
     left?: number | string;
   }
-  export function AnimatedBox(props: AnimatedBoxProps): Widget;
+  export function AnimatedBox(props: AnimatedBoxProps): FletWidget;
 
   export interface AnimatedTextProps extends CommonProps {
     child: Widget;
@@ -1238,7 +1363,7 @@ declare module 'flet-box' {
     delayBetween?: number;
     orientation?: 'row' | 'column';
   }
-  export function AnimatedText(props: AnimatedTextProps): Widget;
+  export function AnimatedText(props: AnimatedTextProps): FletWidget;
 
   export interface MatrixRainProps extends CommonProps {
     chars?: string;
@@ -1250,7 +1375,7 @@ declare module 'flet-box' {
     position?: 'fixed' | 'absolute';
     zIndex?: number;
   }
-  export function MatrixRain(props?: MatrixRainProps): Widget;
+  export function MatrixRain(props?: MatrixRainProps): FletWidget;
 
   export interface ParallaxBoxProps extends CommonProps {
     child: Widget;
@@ -1264,7 +1389,7 @@ declare module 'flet-box' {
     duration?: number;
     easing?: string;
   }
-  export function ParallaxBox(props: ParallaxBoxProps): Widget & {
+  export function ParallaxBox(props: ParallaxBoxProps): FletWidget & {
     updateSpeed(speed: number): void;
     updateDirection(direction: string): void;
     setPosition(x: number, y: number, animate?: boolean): void;
@@ -1442,7 +1567,7 @@ declare module 'flet-box' {
     cellPadding?: Padding;
     headerCellPadding?: Padding;
   }
-  export function DataTable(props: DataTableProps): Widget & {
+  export function DataTable(props: DataTableProps): FletWidget & {
     updateData(rows: any[]): void;
     updateColumns(columns: DataTableColumn[]): void;
   };
@@ -1473,7 +1598,7 @@ declare module 'flet-box' {
     showValues?: boolean;
     borderRadius?: number;
   }
-  export function Chart(props: ChartProps): Widget & {
+  export function Chart(props: ChartProps): FletWidget & {
     updateData(newData: any[], newLabels?: string[]): void;
     redraw(): void;
   };
@@ -1486,7 +1611,7 @@ declare module 'flet-box' {
     errorCorrection?: 'L' | 'M' | 'Q' | 'H';
     margin?: number;
   }
-  export function QRCode(props: QRCodeProps): Widget & {
+  export function QRCode(props: QRCodeProps): FletWidget & {
     updateValue(value: string): void;
     download(filename?: string): void;
     getDataURL(): string;
@@ -1508,7 +1633,7 @@ declare module 'flet-box' {
     lineNumberWidth?: number;
     lineNumberColor?: Color;
   }
-  export function CodeViewer(props: CodeViewerProps): Widget & {
+  export function CodeViewer(props: CodeViewerProps): FletWidget & {
     updateCode(code: string): void;
     updateTitle(title: string): void;
     scrollTo(x: number, y: number): void;
@@ -1523,7 +1648,7 @@ declare module 'flet-box' {
     indent?: number;
   }
   /** Paints the reconstructed call of a widget tree. */
-  export function Inspector(props: InspectorProps): Widget;
+  export function Inspector(props: InspectorProps): FletWidget;
   /** Rebuilds the call that made a widget, as a string. */
   export function Inspector(widget: Widget, indent?: number): string;
   export function printWidgetCode(widget: Widget): void;
@@ -1542,7 +1667,7 @@ declare module 'flet-box' {
     dragOverlayColor?: Color;
     dragBorderColor?: Color;
   }
-  export function DraggBox(props: DraggBoxProps): Widget;
+  export function DraggBox(props: DraggBoxProps): FletWidget;
 
   export interface DroppBoxProps extends CommonProps {
     child: Widget;
@@ -1572,7 +1697,7 @@ declare module 'flet-box' {
     transitionTiming?: string;
     showFeedback?: boolean;
   }
-  export function DroppBox(props: DroppBoxProps): Widget;
+  export function DroppBox(props: DroppBoxProps): FletWidget;
 
   export interface CarouselProps extends CommonProps {
     items: (Widget | string | { src: string; alt?: string })[];
@@ -1595,7 +1720,7 @@ declare module 'flet-box' {
     buttonTop?: number | string;
     onIndexChange?: (index: number) => void;
   }
-  export function Carousel(props: CarouselProps): Widget & {
+  export function Carousel(props: CarouselProps): FletWidget & {
     next(): void;
     prev(): void;
     goTo(index: number): void;
@@ -1626,13 +1751,44 @@ declare module 'flet-box' {
     borderWidth?: number;
     shadow?: string;
   }
-  export function Tooltip(props: TooltipProps): Widget & {
+  export function Tooltip(props: TooltipProps): FletWidget & {
     showTooltip(): void;
     hideTooltip(): void;
     updateContent(newText: string): void;
     updatePosition(): void;
   };
 
+  export type MenuItem = {
+    text: string;
+    icon?: string;
+    onPress?: () => void;
+    disabled?: boolean;
+    danger?: boolean;
+  };
+
+  export interface MenuProps extends CommonProps {
+    items: MenuItem[];
+    /** Accessible name of the trigger and of the menu it opens. */
+    label?: string;
+    icon?: string;
+    /** Width of the open panel. The trigger is a square `size` wide. */
+    width?: number | string;
+    /** Which edge of the trigger the panel aligns to. */
+    align?: 'start' | 'end';
+    disabled?: boolean;
+    /** Mount the panel on `document.body` so no ancestor can clip it. */
+    portal?: boolean;
+    bgColor?: Color;
+    borderRadius?: number;
+    size?: number;
+  }
+
+  export function Menu(props: MenuProps): FletWidget & {
+    open(): void;
+    close(): void;
+    update(props: Partial<MenuProps>): void;
+  };
+
   export interface PaginationProps extends CommonProps {
     totalItems: number;
     pageSize?: number;
@@ -1648,18 +1804,22 @@ declare module 'flet-box' {
     showTotal?: boolean;
     label?: string;
   }
-  export function Pagination(props: PaginationProps): Widget;
-
-  export interface TreeViewProps extends CommonProps {
-    nodes: Array<{
-      id: string;
-      label: string;
-      icon?: string;
-      iconColor?: Color;
-      children?: any[];
-      badge?: string | number;
-    }>;
-    onSelect?: (node: any) => void;
+  export function Pagination(props: PaginationProps): FletWidget;
+
+  export interface TreeViewNode {
+    id: string;
+    label: string;
+    icon?: string;
+    iconColor?: Color;
+    children?: TreeViewNode[];
+    badge?: string | number;
+  }
+  export interface TreeViewProps extends Omit<CommonProps, 'onPress'> {
+    nodes: TreeViewNode[];
+    /** Fired with the node the reader selected. */
+    onSelect?: (node: TreeViewNode) => void;
+    /** The framework's spelling of `onSelect`, fired with the same node; `onSelect` wins when both are given. */
+    onPress?: (node: TreeViewNode) => void;
     onToggle?: (nodeId: string, expanded: boolean) => void;
     expandedNodes?: string[];
     indent?: number;
@@ -1688,7 +1848,7 @@ declare module 'flet-box' {
     iconSize?: number;
     transitionDuration?: string;
   }
-  export function TreeView(props: TreeViewProps): Widget & {
+  export function TreeView(props: TreeViewProps): FletWidget & {
     updateNodes(nodes: any[], selectedId?: string | null): void;
     expandAll(): void;
     collapseAll(): void;
@@ -1721,13 +1881,46 @@ declare module 'flet-box' {
     margin?: Margin;
     width?: number | string;
   }
-  export function Stepper(props: StepperProps): Widget & {
+  export function Stepper(props: StepperProps): FletWidget & {
     goTo(index: number): void;
     next(): void;
     back(): void;
     getActiveStep(): number;
   };
 
+  /**
+   * One selectable accent: the two stops a single hue wears, one per theme.
+   * `light` is the deep end (it carries white words on a light page) and `dark`
+   * the lifted end (it carries a dark page's own ink). A swatch paints both
+   * because an accent is the pair, never one of them.
+   */
+  export interface Accent {
+    id: string;
+    label: string;
+    light: string;
+    dark: string;
+  }
+
+  export interface ThemePickerProps extends CommonProps {
+    /** Families to offer. Defaults to `listAccents()`, i.e. everything registered. */
+    accents?: Accent[];
+    /** Edge of one swatch, in framework units. Defaults to 40 — the tap minimum. */
+    size?: number;
+    /** Print each family's name under its swatch. Defaults to false. */
+    showLabels?: boolean;
+    /**
+     * Offer the families as themes: picking one also paints the page, the panels,
+     * the cards and the hairlines. Defaults to false — brand only.
+     */
+    surfaces?: boolean;
+    /** Accessible name of the group. Defaults to `"Accent color"`. */
+    label?: string;
+    disabled?: boolean;
+    /** Called with the id after the accent has been applied to the screen. */
+    onChange?: (id: string) => void;
+  }
+  export function ThemePicker(props?: ThemePickerProps): FletWidget;
+
   export interface SkeletonProps extends CommonProps {
     variant?: 'text' | 'circular' | 'avatar' | 'image' | 'card' | 'listTile' | 'button';
     width?: number | string;
@@ -1742,7 +1935,7 @@ declare module 'flet-box' {
     pulseDuration?: string;
     waveDuration?: string;
   }
-  export function Skeleton(props: SkeletonProps): Widget;
+  export function Skeleton(props: SkeletonProps): FletWidget;
 
   export interface InstallButtonProps extends CommonProps {
     text?: string;
@@ -1755,7 +1948,7 @@ declare module 'flet-box' {
     onInstalled?: () => void;
     onClick?: () => void;
   }
-  export function InstallButton(props: InstallButtonProps): Widget;
+  export function InstallButton(props: InstallButtonProps): FletWidget;
 
   export interface VideoProps extends Omit<CommonProps, 'ref'> {
     src: string;
@@ -1828,7 +2021,7 @@ declare module 'flet-box' {
     animationDuration?: number;
     onComplete?: () => void;
     ref?: (canvas: HTMLCanvasElement) => void;
-    // Nuevas props
+    // New props
     valueFormat?: 'percent' | 'value' | 'custom';
     valueSuffix?: string;
     valuePrefix?: string;
@@ -1850,7 +2043,7 @@ declare module 'flet-box' {
     subtitleSize?: number;
     tooltip?: string;
   }
-  export function CircularBar(props: CircularBarProps): Widget & {
+  export function CircularBar(props: CircularBarProps): FletWidget & {
     updateValue(newValue: number, newMax?: number): void;
   };
 
@@ -1891,7 +2084,7 @@ declare module 'flet-box' {
     sliceBorderWidth?: number;
     sliceBorderColor?: Color;
   }
-  export function CircularChart(props: CircularChartProps): Widget & {
+  export function CircularChart(props: CircularChartProps): FletWidget & {
     updateData(data: CircularChartSlice[], animate?: boolean): void;
     redraw(): void;
     setCornerRadius(radius: number): void;
@@ -1936,12 +2129,15 @@ declare module 'flet-box' {
     imageBorderRadius?: number;
     padding?: Padding;
     maxHeight?: number;
-    overflow?: string;
+    // Same value as the engine routes on every widget: the scroll container of the
+    // document. Declared as a bare `string` it was incompatible with the base
+    // interface, which a declaration reader reports as a broken inheritance.
+    overflow?: 'auto' | 'hidden' | 'visible' | 'scroll' | 'clip';
     backgroundColor?: Color;
     borderRadius?: number;
     allowDangerousHtml?: boolean;
   }
-  export function Markdown(props: MarkdownProps): Widget & {
+  export function Markdown(props: MarkdownProps): FletWidget & {
     updateContent(newText: string): void;
     getContent(): string;
     getSource(): string;
@@ -2049,7 +2245,7 @@ declare module 'flet-box' {
     /** Fires on each watched fix, including the ones while `followUser` is off. */
     onUserUpdate?: (fix: MapFix) => void;
   }
-  export function Maps(props: MapsProps): Widget & {
+  export function Maps(props: MapsProps): FletWidget & {
     setCenter(position: LatLng, zoom?: number): Widget;
     getCenter(): { lat: number; lng: number };
     getZoom(): number;
@@ -2089,14 +2285,31 @@ declare module 'flet-box' {
    */
   export function App(widget: Widget): Widget;
 
+  /**
+   * The element the factory returns for a native `<input type="file">`: the
+   * factory instance plus the HTML input surface. The framework has no file
+   * control, so an app that needs one builds it with `WidgetFactory` and must be
+   * able to say so:
+   *
+   * ```js
+   * const entrada = WidgetFactory<FletInput>({ tag: 'input' });
+   * entrada.type = 'file';
+   * ```
+   */
+  export type FletInput = WidgetFactoryInstance & HTMLInputElement;
+
   /**
    * The only rendering engine. Turns a tag (or config object) plus props into a
    * real `HTMLElement` with styles, events, children, lifecycle and reactivity.
+   *
+   * The return type is the generic `T`, defaulting to the factory instance. Pass
+   * `FletInput` when the element is a native input the code will drive directly —
+   * otherwise an editor reads `entrada.type` as a missing property.
    */
-  export function WidgetFactory(
+  export function WidgetFactory<T extends WidgetFactoryInstance = WidgetFactoryInstance>(
     tag: string | { tag?: string; [prop: string]: any },
     customProps?: Record<string, any>
-  ): WidgetFactoryInstance;
+  ): T;
 
   export function createApp(routes: any, options?: { rootId?: string; fallback?: Widget | (() => Widget) }): {
     start(): void;
@@ -2120,7 +2333,7 @@ declare module 'flet-box' {
   export function getHMR(): WebSocket | null;
 
   // =========================================================================
-  // Utils (temas, dimensiones, aleatorios, etc.)
+  // Utils (themes, dimensions, random, etc.)
   // =========================================================================
   export const colors: Record<string, string>;
   export const palettes: Record<string, Record<string, string>>;
@@ -2129,6 +2342,49 @@ declare module 'flet-box' {
     themeName: string,
     palette: Record<string, string>
   ): Record<string, string>;
+  /**
+   * Adds or replaces one selectable accent. Each end of the pair may be a single
+   * hex or a five-stop ramp, in which case the accent and its wash are read off
+   * the stops the shipped families use. Repaints only when that id is on screen.
+   */
+  export function registerAccent(accent: {
+    id: string;
+    label?: string;
+    light: string | string[];
+    dark: string | string[];
+  }): Accent | null;
+  /**
+   * Lays an accent over the live palette and persists the choice. `null` (or an
+   * unknown id) takes it back off, and the screen returns to the palette's own
+   * `primary`.
+   *
+   * `{ surfaces: true }` wears it as a theme instead of only as a brand: the page,
+   * the panels, the cards and the hairlines are derived from the same ramp. The
+   * plate (`primaryBg`) keeps coming from the accent's measured wash stop either
+   * way, and the ink scale never moves.
+   */
+  export function setAccent(
+    id: string | null,
+    options?: { surfaces?: boolean },
+  ): Record<string, string>;
+  /** Applies an accent only when the reader has never picked one. Never persists. */
+  export function applyAccentPreference(
+    id: string,
+    options?: { surfaces?: boolean },
+  ): string | null;
+  /** The accent on screen, or `null` when the palette's own `primary` is showing. */
+  export function getAccent(): string | null;
+  /** Whether the live accent also paints the surfaces. */
+  export function getAccentSurfaces(): boolean;
+  /** Every selectable accent, in registration order. */
+  export function listAccents(): Accent[];
+  /** The same list with each family's five stops beside it, for a swatch that shows the ramp. */
+  export function listAccentRamps(): Array<{
+    id: string;
+    label: string;
+    light: string[];
+    dark: string[];
+  }>;
   export function getTheme(): string;
   export function toggleTheme(): string;
   export function getColor(colorName: string, opacity?: number): string;
@@ -2143,6 +2399,9 @@ declare module 'flet-box' {
     toggleTheme: typeof toggleTheme;
     getColor: typeof getColor;
     applySystemTheme: typeof applySystemTheme;
+    setAccent: typeof setAccent;
+    getAccent: typeof getAccent;
+    listAccents: typeof listAccents;
   };
 
   export const clipboard: {
@@ -2462,7 +2721,10 @@ declare module 'flet-box' {
   }): void;
   export function injectKeyframes(name: string, keyframes: string): void;
 
-  export function border(width?: number | string, style?: string, color?: string): string;
+  // `color` is required (a colorless border is invisible) and the first two have
+  // runtime defaults, so the type admits `undefined` in their place: a required
+  // parameter cannot simply follow an optional one in a declaration.
+  export function border(width: number | string | undefined, style: string | undefined, color: string): string;
   export function margin(value: number | string | { all?: number; horizontal?: number; vertical?: number; top?: number; right?: number; bottom?: number; left?: number }): string;
   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;
@@ -2490,7 +2752,7 @@ declare module 'flet-box' {
 
   export const color: (value: string | ColorInstance) => 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 stackPosition(widget: Widget, props?: StackPositionProps): Widget;
   export function flex(grow: number | { grow?: number; shrink?: number; basis?: string }, shrink?: number, basis?: string): string;
   export function grid(options: { columns?: number | string; rows?: number | string; gap?: number | string | { row?: number; column?: number } }): string;
   export function transition(options: { property?: string; duration?: number; timing?: string; delay?: number } | Array<{ property?: string; duration?: number; timing?: string; delay?: number }>): string;
@@ -2533,7 +2795,18 @@ declare module 'flet-box' {
   export function fromJSON(jsonStr: string): any;
   export function fromEntries(entries: [string, any][]): any;
 
-  export function ref<T extends Widget = Widget>(): (widget: T) => T & { update(props: Partial<any>): void };
+  /**
+   * What `ref()` hands back: the callback the framework calls with the widget,
+   * plus the live handle the docs use (`display.update({ text })`). Typing it as
+   * a bare function is why `display.update(...)` was an editor error even though
+   * the helper defines it.
+   */
+  export type Ref<T extends Widget = Widget> = ((widget: T | null) => T | null) & {
+    /** The bound widget, or null before the framework mounts it. */
+    current?: T | null;
+    update(props?: Record<string, any>): void;
+  };
+  export function ref<T extends Widget = Widget>(): Ref<T>;
   export function uuid(): string;
   export function shortId(): string;
   export function numericId(length?: number): string;