fiboui 2.8.5 → 2.9.0

package/dist/server.d.ts

@@ -131,7 +131,27 @@ declare class Observable<T> implements Subscribable<T> {
 	unsubscribeEffect(effect: Effect): void;
 	private notify;
 }
+type GestureMask = "all" | "gesture" | "subviews" | "none";
+type TapLocation = {
+	x: number;
+	y: number;
+};
 declare abstract class GestureBuilder {
+	protected _enabled: boolean;
+	protected _including: GestureMask;
+	/** When true, wrappers must not stopPropagation (simultaneous). */
+	protected _bubble: boolean;
+	/** @internal Fired when the gesture successfully recognizes (Sequence / Exclusive). */
+	protected _onRecognized?: () => void;
+	enabled(value?: boolean): this;
+	/** SwiftUI `gesture(_:including:)`. */
+	including(mask: GestureMask): this;
+	/** Internal — set by SimultaneousGesture / `.simultaneousGesture`. */
+	bubble(value?: boolean): this;
+	/** @internal Used by SequenceGesture / ExclusiveGesture. */
+	onRecognized(callback: () => void): this;
+	/** @internal */
+	protected notifyRecognized(): void;
 	abstract wrap(children: React$1.ReactNode): React$1.ReactNode;
 }
 interface AnimationOptions {
@@ -360,6 +380,144 @@ declare const When: {
 };
 type When = (typeof When)[keyof typeof When];
 type WhenStyle = React$1.CSSProperties | string | ((builder: any) => void);
+declare const Size: {
+	readonly full: "full";
+	readonly screen: "screen";
+	readonly fit: "fit";
+	readonly min: "min";
+	readonly max: "max";
+	/** SwiftUI `.infinity` — expand to the space the parent proposes (`100%`). */
+	readonly infinity: "infinity";
+};
+type Size = (typeof Size)[keyof typeof Size];
+declare const StackAlign: {
+	readonly center: "center";
+	readonly top: "top";
+	readonly bottom: "bottom";
+	readonly left: "left";
+	readonly right: "right";
+	readonly topLeft: "topLeft";
+	readonly topRight: "topRight";
+	readonly bottomLeft: "bottomLeft";
+	readonly bottomRight: "bottomRight";
+	/** SwiftUI `leading` → `left` */
+	readonly leading: "left";
+	/** SwiftUI `trailing` → `right` */
+	readonly trailing: "right";
+	/** SwiftUI `topLeading` → `topLeft` */
+	readonly topLeading: "topLeft";
+	/** SwiftUI `topTrailing` → `topRight` */
+	readonly topTrailing: "topRight";
+	/** SwiftUI `bottomLeading` → `bottomLeft` */
+	readonly bottomLeading: "bottomLeft";
+	/** SwiftUI `bottomTrailing` → `bottomRight` */
+	readonly bottomTrailing: "bottomRight";
+};
+type StackAlign = (typeof StackAlign)[keyof typeof StackAlign];
+type FrameSize = number | string | Size;
+interface FrameSpec {
+	width?: FrameSize;
+	height?: FrameSize;
+	minWidth?: FrameSize;
+	idealWidth?: FrameSize;
+	maxWidth?: FrameSize;
+	minHeight?: FrameSize;
+	idealHeight?: FrameSize;
+	maxHeight?: FrameSize;
+	alignment?: StackAlign | keyof typeof StackAlign;
+}
+type ClipShapeName = "circle" | "rounded" | "square";
+interface OffsetSpec {
+	x?: number;
+	y?: number;
+}
+interface FixedSizeSpec {
+	horizontal?: boolean;
+	vertical?: boolean;
+}
+interface LayerSpec {
+	kind: "overlay" | "background";
+	child: FiboChild | (() => FiboChild);
+	alignment: StackAlign | keyof typeof StackAlign;
+}
+type ContentShapeName = "rectangle" | ClipShapeName;
+type GeometryRect = {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+};
+type ContainerRelativeFrameSpec = {
+	axis?: "horizontal" | "vertical" | "both";
+	/** Divisions of the container (SwiftUI `count`). Default 1. */
+	count?: number;
+	/** Spans claimed (SwiftUI `span`). Default 1. */
+	span?: number;
+};
+type AlignmentGuideName = "leading" | "trailing" | "top" | "bottom" | "centerX" | "centerY" | string;
+type AlignmentGuideDims = {
+	width: number;
+	height: number;
+};
+type AlignmentGuideSpec = {
+	guide: AlignmentGuideName;
+	/** Absolute guide position, or compute from own size (SwiftUI `ViewDimensions`). */
+	compute: number | ((dims: AlignmentGuideDims) => number);
+};
+type MatchedGeometrySpec = {
+	id: string;
+	namespace?: string;
+	/** SwiftUI `isSource` — source owns the shared geometry. Default true. */
+	isSource?: boolean;
+};
+type PreferenceKeyDef<T> = {
+	readonly __preferenceKey: true;
+	readonly id: string | symbol;
+	readonly defaultValue: T;
+	reduce: (value: T, nextValue: T) => T;
+};
+type PreferenceWriteSpec = {
+	key: PreferenceKeyDef<any>;
+	value: unknown;
+};
+type PreferenceReadSpec = {
+	key: PreferenceKeyDef<any>;
+	onChange: (value: any) => void;
+};
+declare const Edge: {
+	readonly top: "top";
+	readonly bottom: "bottom";
+	readonly leading: "leading";
+	readonly trailing: "trailing";
+};
+type Edge = (typeof Edge)[keyof typeof Edge];
+declare const EdgeSet: {
+	readonly top: "top";
+	readonly bottom: "bottom";
+	readonly leading: "leading";
+	readonly trailing: "trailing";
+	readonly horizontal: "horizontal";
+	readonly vertical: "vertical";
+	readonly all: "all";
+};
+type EdgeSet = (typeof EdgeSet)[keyof typeof EdgeSet];
+type EdgeInsetsValue = {
+	top?: number | string;
+	bottom?: number | string;
+	leading?: number | string;
+	trailing?: number | string;
+	/** CSS left — alias of leading in LTR */
+	left?: number | string;
+	/** CSS right — alias of trailing in LTR */
+	right?: number | string;
+};
+type SafeAreaInsetEdge = Edge | "top" | "bottom" | "leading" | "trailing" | "left" | "right";
+type SafeAreaInsetSpec = {
+	edge: SafeAreaInsetEdge;
+	content: FiboChild | (() => FiboChild);
+	/** Gap between inset bar and content. Default 0. */
+	spacing?: number;
+};
 interface SpringOptions {
 	stiffness?: number;
 	damping?: number;
@@ -569,7 +727,29 @@ declare abstract class FiboBuilder {
 	/** @internal Direct `method(signal.value)` calls replayed when that signal changes. */
 	protected _replays: Array<() => void>;
 	protected _isObserver: boolean;
-	protected _gesture?: GestureBuilder;
+	/** Normal-priority gestures (SwiftUI `.gesture`). Last = outermost. */
+	protected _gestures: GestureBuilder[];
+	/** SwiftUI `.simultaneousGesture` — bubble / no stopPropagation. */
+	protected _simultaneousGestures: GestureBuilder[];
+	/** SwiftUI `.highPriorityGesture` — wrapped last (outermost / capture wins). */
+	protected _highPriorityGestures: GestureBuilder[];
+	protected _offset?: OffsetSpec;
+	protected _clipped: boolean;
+	protected _clipShape?: ClipShapeName | string;
+	protected _contentShape?: ContentShapeName | string;
+	protected _fixedSize?: FixedSizeSpec;
+	protected _layoutPriority?: number;
+	protected _layers: LayerSpec[];
+	protected _onGeometryChange?: (rect: GeometryRect) => void;
+	protected _compositingGroup: boolean;
+	protected _viewMask?: string;
+	protected _containerRelativeFrame?: ContainerRelativeFrameSpec;
+	protected _alignmentGuide?: AlignmentGuideSpec;
+	protected _matchedGeometry?: MatchedGeometrySpec;
+	protected _preferences: PreferenceWriteSpec[];
+	protected _preferenceReaders: PreferenceReadSpec[];
+	protected _safeAreaInsets: SafeAreaInsetSpec[];
+	protected _navigationTitle?: string;
 	protected _animationConfig?: Partial<AnimationOptions>;
 	protected _animatedProps: Map<string, Signal<any>>;
 	protected _transforms: string[];
@@ -598,6 +778,11 @@ declare abstract class FiboBuilder {
 	protected _explicitScrollMargin: boolean;
 	/** Shrink-wrap: skip the default `w-full` / `self-stretch` on Row and Column. */
 	protected _hug: boolean;
+	/**
+	 * SwiftUI `.frame(...)` wrappers (outer → inner order of application).
+	 * Applied in `assembleBuilder` so every widget gets the same DX.
+	 */
+	protected _frames: FrameSpec[];
 	/**
 	 * Unset every CSS property on this component and what it renders inside.
 	 * Chain `.style()`, `.px()`, `.flex()` and the rest after this to put back only what you want.
@@ -609,6 +794,109 @@ declare abstract class FiboBuilder {
 	protected isReset(): boolean;
 	hug(): this;
 	protected isHug(): boolean;
+	/**
+	 * SwiftUI `View.frame` — invisible box around this view.
+	 *
+	 * ```ts
+	 * Image(url).frame({ width: 300, height: 400 })
+	 * Text('★★★★').frame({
+	 *   maxWidth: Size.infinity,
+	 *   maxHeight: Size.infinity,
+	 *   alignment: StackAlign.topTrailing,
+	 * })
+	 * ```
+	 *
+	 * Chainable: each `.frame()` wraps the previous (same as SwiftUI).
+	 */
+	frame(spec: FrameSpec): this;
+	/**
+	 * SwiftUI `.offset(x:y:)` — visual translate; layout size stays.
+	 * `.offset(8)` ≡ `{ x: 8, y: 8 }`; `.offset({ x: 4 })` only horizontal.
+	 */
+	offset(value: number | OffsetSpec): this;
+	/** SwiftUI `.clipped()` — overflow hidden to bounds. */
+	clipped(): this;
+	/**
+	 * SwiftUI `.clipShape` — `'circle' | 'rounded' | 'square'` or any CSS radius
+	 * (`'8px'`, `'50%'`). Clips drawing; hit-testing still follows layout unless
+	 * you also set {@link contentShape}.
+	 */
+	clipShape(shape: ClipShapeName | string): this;
+	/**
+	 * SwiftUI `.contentShape` — region used for hit-testing (tap / long-press).
+	 * Default `'rectangle'` = full frame box, even over transparent pixels.
+	 *
+	 * ```ts
+	 * ZStack()…frame({ width: 300, height: 400 })
+	 *   .clipShape('8px')
+	 *   .contentShape('rectangle')
+	 *   .onTapGesture(open)
+	 * ```
+	 */
+	contentShape(shape?: ContentShapeName | string): this;
+	/**
+	 * SwiftUI `.fixedSize(horizontal:vertical:)` — hug content on those axes.
+	 * Defaults both axes when called with no args.
+	 */
+	fixedSize(spec?: FixedSizeSpec | boolean): this;
+	/**
+	 * SwiftUI `.layoutPriority` — higher resists compression and claims free space.
+	 * Web: flex-grow / flex-shrink (not a full multi-axis proposal solver).
+	 */
+	layoutPriority(value: number): this;
+	/** SwiftUI `.compositingGroup()`. */
+	compositingGroup(): this;
+	/** SwiftUI `.mask` — shape name or CSS mask-image value. */
+	mask(shapeOrCss: ClipShapeName | "rectangle" | string): this;
+	/** SwiftUI `containerRelativeFrame`. */
+	containerRelativeFrame(axis?: ContainerRelativeFrameSpec["axis"] | ContainerRelativeFrameSpec, count?: number, span?: number): this;
+	/**
+	 * SwiftUI `alignmentGuide` — named guide + absolute value or compute from size.
+	 * ```ts
+	 * Text('Hi').alignmentGuide('leading', (d) => d.width / 2)
+	 * ```
+	 */
+	alignmentGuide(guide: AlignmentGuideName, compute: number | ((dims: {
+		width: number;
+		height: number;
+	}) => number)): this;
+	/**
+	 * SwiftUI `matchedGeometryEffect` — shared view-transition id + measured rect.
+	 * ```ts
+	 * Image(url).matchedGeometryEffect('hero', { namespace: 'gallery', isSource: true })
+	 * ```
+	 */
+	matchedGeometryEffect(id: string, namespaceOrOpts?: string | {
+		namespace?: string;
+		isSource?: boolean;
+	}): this;
+	/** SwiftUI `.preference(key:value:)` — contribute upward to `.onPreferenceChange`. */
+	preference<T>(key: PreferenceKeyDef<T>, value: T): this;
+	/** SwiftUI `.onPreferenceChange` — reduce descendant preferences. */
+	onPreferenceChange<T>(key: PreferenceKeyDef<T>, onChange: (value: T) => void): this;
+	/**
+	 * SwiftUI `.safeAreaInset(edge:)` — reserve a bar on one edge; content fills the rest.
+	 * Distinct from `SafeArea` (notch padding) and `proxy.safeAreaInsets` (read-only).
+	 */
+	safeAreaInset(edge: SafeAreaInsetEdge, content: SafeAreaInsetSpec["content"], spacing?: number): this;
+	/**
+	 * SwiftUI `.navigationTitle` — stores title for Scaffold (see `Scaffold.navigationTitle`).
+	 * On non-Scaffold builders, sets `aria-label` / data attribute only (no extra chrome bar).
+	 */
+	navigationTitle(title: string): this;
+	/**
+	 * SwiftUI `.overlay(alignment:) { }` — layer above this view.
+	 * ```ts
+	 * Image(url).overlay(Text('NEW'), StackAlign.topTrailing)
+	 * ```
+	 */
+	overlay(child: FiboChild | (() => FiboChild), alignment?: StackAlign | keyof typeof StackAlign): this;
+	/**
+	 * SwiftUI `.background(alignment:) { }` — layer behind this view.
+	 */
+	background(child: FiboChild | (() => FiboChild), alignment?: StackAlign | keyof typeof StackAlign): this;
+	/** SwiftUI `onGeometryChange` — fires on mount + resize. */
+	onGeometryChange(handler: (rect: GeometryRect) => void): this;
 	id(value: string): this;
 	/**
 	 * Scroll target. Same as `.id()`, plus `scroll-margin-top` so the section
@@ -632,7 +920,18 @@ declare abstract class FiboBuilder {
 	private setBoxShorthand;
 	paddingHorizontal(value: string | number): this;
 	paddingVertical(value: string | number): this;
+	/**
+	 * SwiftUI `.padding`:
+	 * - `.padding(8)` — all sides
+	 * - `.padding(EdgeSet.horizontal, 12)` — Edge.Set + value
+	 * - `.padding({ top: 8, leading: 12 })` — EdgeInsets
+	 */
 	padding(value: string | number): this;
+	padding(edges: EdgeSet, value: string | number): this;
+	padding(insets: EdgeInsetsValue): this;
+	/** SwiftUI `.padding` with {@link EdgeSet} — alias clarity. */
+	/** @deprecated Prefer `.padding(EdgeSet, n)` — same implementation. */
+	paddingEdges(edges: EdgeSet, value: string | number): this;
 	marginHorizontal(value: string | number): this;
 	marginVertical(value: string | number): this;
 	margin(value: string | number): this;
@@ -742,6 +1041,9 @@ declare abstract class FiboBuilder {
 	 * (the Scaffold body) cannot divide the viewport across these children.
 	 * `400`, `'320px'`, `Size.full`, and `Space.md` all count. `flex(1)` afterwards
 	 * opts back into sharing space.
+	 *
+	 * Percentages / `auto` do not lock `min-*` — `minWidth: 100%` on a flex
+	 * child fights clamping and lets long text blow past the ZStack box.
 	 */
 	private lockAxis;
 	width(value: string | number): this;
@@ -772,8 +1074,58 @@ declare abstract class FiboBuilder {
 	translateX(value: Signal<number> | number): this;
 	translateY(value: Signal<number> | number): this;
 	scale(value: Signal<number> | number): this;
+	/** SwiftUI `scaleEffect` — alias of {@link scale}. */
+	scaleEffect(value: Signal<number> | number): this;
 	rotate(degrees: Signal<number> | number): this;
+	/** SwiftUI `rotationEffect` — alias of {@link rotate} (degrees). */
+	rotationEffect(degrees: Signal<number> | number): this;
+	/**
+	 * SwiftUI `.allowsHitTesting` — when `false`, this view and descendants
+	 * ignore pointer hits (`pointer-events: none`).
+	 */
+	allowsHitTesting(value?: boolean): this;
+	/**
+	 * SwiftUI scroll target id — used by {@link ScrollViewReader} `.scrollTo(id)`.
+	 * Sets `data-scroll-id` on the host.
+	 */
+	scrollTarget(id: string): this;
+	/**
+	 * SwiftUI: taps on *containers* (ZStack / Column / …) only hit drawn content
+	 * unless `.contentShape(Rectangle())` is set. We default that shape when the
+	 * first gesture is attached and the caller did not set one — same as the
+	 * usual SwiftUI fix, without forcing it on chrome-only views.
+	 */
+	protected ensureGestureContentShape(): void;
+	/**
+	 * SwiftUI `.gesture` — attach Tap / LongPress / Drag / Magnify / Rotate / …
+	 * Chainable: each call wraps the previous (outermost = last).
+	 */
 	gesture(gesture: GestureBuilder): this;
+	/** SwiftUI `.simultaneousGesture` — runs alongside other gestures (no steal). */
+	simultaneousGesture(gesture: GestureBuilder): this;
+	/** SwiftUI `.highPriorityGesture` — recognized before the view's own gestures. */
+	highPriorityGesture(gesture: GestureBuilder): this;
+	/**
+	 * Sugar for {@link TapGesture}`.onEnd(handler)`.
+	 * Note: `Button` / `List` / `ListTile` keep domain-specific `.onPress`.
+	 */
+	onPress(handler: () => void): this;
+	/** Flutter-style alias of {@link onPress}. */
+	onTap(handler: () => void): this;
+	/**
+	 * SwiftUI `onTapGesture(count:perform:)` — default count 1.
+	 * Pass a location callback for SpatialTap behavior.
+	 */
+	onTapGesture(countOrHandler: number | ((location?: TapLocation) => void) | (() => void), handler?: ((location?: TapLocation) => void) | (() => void)): this;
+	/**
+	 * SwiftUI `onLongPressGesture(minimumDuration:perform:onPressingChanged:)`.
+	 */
+	onLongPressGesture(handlerOrOpts: (() => void) | {
+		minimumDuration?: number;
+		maximumDistance?: number;
+		perform: () => void;
+		onPressingChanged?: (pressing: boolean) => void;
+	}, onPressingChanged?: (pressing: boolean) => void): this;
 	animation(config: Partial<AnimationOptions>): this;
 	protected hasStateManagement(): boolean;
 	className(className: string): this;
@@ -1003,6 +1355,8 @@ declare class ContainerBuilder extends FiboBuilder {
 	children(children: FiboChildren): this;
 	props(value: Record<string, any>): this;
 	padding(value: string | number): this;
+	padding(edges: EdgeSet, value: string | number): this;
+	padding(insets: EdgeInsetsValue): this;
 	paddingHorizontal(value: string | number): this;
 	paddingVertical(value: string | number): this;
 	paddingLeft(value: string | number): this;
@@ -1122,6 +1476,12 @@ declare class ScaffoldBuilder extends FiboBuilder {
 	headerBar(config: FiboChild | LayoutBarConfig): this;
 	/** Flutter `Scaffold.appBar`. Same slot as `.headerBar()`. */
 	appBar(config: FiboChild | LayoutBarConfig): this;
+	/**
+	 * SwiftUI `.navigationTitle` — fills the header bar via existing `Header` chrome.
+	 * Does **not** add a sixth title component; if `.headerBar()` / `.appBar()` is already
+	 * set, this is a no-op (explicit chrome wins).
+	 */
+	navigationTitle(title: string | FiboChild): this;
 	footerBar(config: FiboChild | LayoutBarConfig): this;
 	sideBarLeft(config: FiboChild | LayoutBarConfig): this;
 	sideBarRight(config: FiboChild | LayoutBarConfig): this;