@octane-xplat/ui 0.4.0 → 0.6.0

package/types/props.d.ts

@@ -17,6 +17,11 @@ export interface PanEvent {
 export interface SwipeEvent {
     direction: number;
 }
+/** Public shape of `setTranslate` — the imperative translate write on a
+ *  bound view (a leaf's `bind` target). Web composes into the element's
+ *  `transform`; native sets the view's translateX/translateY props.
+ *  Both axes default to 0, so `setTranslate(el)` resets. */
+export type SetTranslate = (el: any, x?: number, y?: number) => void;
 /** Metadata read by parent layouts. Native forwards NativeScript attached
  *  attributes; web folds the CSS equivalents into the child's style. */
 export interface LayoutChildProps {
@@ -59,27 +64,18 @@ export interface GlassConfig {
     /** Effect-change animation in ms (default 300). */
     animateChangeDuration?: number;
 }
-/** `glass` surface prop value: `true`/string shorthand or a config object.
- *  `'none'`/`'identity'`/`false` mean no glass. */
-export type GlassProp = boolean | 'regular' | 'clear' | 'identity' | 'none' | GlassConfig;
-/** Static glass material on container primitives — background glass behind
- *  the view's content. Interactive glass needs <LiquidGlass>. */
-export interface GlassSurfaceProps {
-    glass?: GlassProp;
-}
-export interface GridProps extends GlassSurfaceProps {
+export interface GridProps extends AccessibilityProps {
     className?: any;
     style?: any;
     children?: any;
     rows?: string;
     columns?: string;
-    gap?: number | string;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
     id?: string;
 }
-export interface StackProps extends GlassSurfaceProps {
+export interface StackProps extends AccessibilityProps {
     className?: any;
     style?: any;
     children?: any;
@@ -88,7 +84,7 @@ export interface StackProps extends GlassSurfaceProps {
     web?: Record<string, any>;
     id?: string;
 }
-export interface AbsoluteProps extends GlassSurfaceProps {
+export interface AbsoluteProps extends AccessibilityProps {
     className?: any;
     style?: any;
     children?: any;
@@ -135,7 +131,23 @@ export interface SpacerProps {
     web?: Record<string, any>;
     id?: string;
 }
-export interface ViewProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
+/** The shared accessibility prop set — `Role` and friends are declared
+ *  below; containers and leaf components carry the same names so ARIA on
+ *  web and NativeScript's accessibility properties stay aligned. */
+export interface AccessibilityProps {
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    accessibilityRole?: Role;
+    accessibilityHint?: string;
+    accessibilityValue?: string;
+    accessibilityState?: {
+        disabled?: boolean;
+        selected?: boolean;
+        checked?: boolean;
+    };
+    accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
+}
+export interface ViewProps extends LayoutChildProps, FlexContainerProps, AccessibilityProps {
     className?: any;
     style?: any;
     children?: any;
@@ -150,34 +162,40 @@ export interface ViewProps extends LayoutChildProps, FlexContainerProps, GlassSu
     android?: any;
     web?: any;
 }
-export interface RowProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
+export interface RowProps extends LayoutChildProps, FlexContainerProps, AccessibilityProps {
     className?: any;
     style?: any;
     children?: any;
     id?: string;
+    /** `ref` is runtime-reserved on component elements — leaves expose
+     *  `bind` to reach the native/DOM node. */
+    bind?: (el: any) => void;
+    onPan?: (e: PanEvent) => void;
+    onSwipe?: (e: SwipeEvent) => void;
     /** Platform-specific properties are applied after shared props. */
     ios?: any;
     android?: any;
     web?: any;
 }
+/** Shared accessibility roles. The native leaf maps the ARIA spellings that
+ * NativeScript names differently (for example `heading` → `header`). */
+export type Role = 'button' | 'link' | 'search' | 'image' | 'heading' | 'adjustable' | 'summary' | 'text' | 'none' | 'progressbar' | 'checkbox' | 'switch' | 'radio' | 'spinbutton' | 'tab';
 export interface TextProps extends LayoutChildProps {
     className?: any;
     style?: any;
     children?: any;
     id?: string;
     numberOfLines?: number;
-    /** Native Label does not expose text selection; implemented with CSS on web. */
-    selectable?: boolean;
     ellipsize?: boolean;
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    accessibilityRole?: Role;
     accessibilityHint?: string;
     accessibilityValue?: string;
-    /** NativeScript supports one state at a time (disabled/selected/checked); busy and expanded are web-only. */
     accessibilityState?: {
         disabled?: boolean;
         selected?: boolean;
         checked?: boolean;
-        busy?: boolean;
-        expanded?: boolean;
     };
     accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
     /** Platform-specific properties are applied after shared props. */
@@ -210,33 +228,33 @@ export interface RichTextSpanProps {
     android?: any;
     web?: any;
 }
-export interface PressableProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
+export interface PressableProps extends LayoutChildProps, FlexContainerProps {
     className?: any;
     style?: any;
     children?: any;
     id?: string;
     disabled?: boolean;
+    /** `ref` is runtime-reserved on component elements — leaves expose
+     *  `bind` to reach the native/DOM node. */
+    bind?: (el: any) => void;
+    onPan?: (e: PanEvent) => void;
+    onSwipe?: (e: SwipeEvent) => void;
     onPress?: () => void;
     /** ~500ms press-and-hold (web: timer over pointerdown/up). */
     onLongPress?: () => void;
     accessible?: boolean;
     accessibilityLabel?: string;
-    accessibilityRole?: string;
+    accessibilityRole?: Role;
     onPressIn?: () => void;
     onPressOut?: () => void;
     onDoublePress?: () => void;
     hitSlop?: number;
-    /** NativeScript supports a per-view TouchManager animation opt-out; web has no press scaling. */
-    ignoreTouchAnimation?: boolean;
     accessibilityHint?: string;
     accessibilityValue?: string;
-    /** NativeScript supports one state at a time (disabled/selected/checked); busy and expanded are web-only. */
     accessibilityState?: {
         disabled?: boolean;
         selected?: boolean;
         checked?: boolean;
-        busy?: boolean;
-        expanded?: boolean;
     };
     accessibilityLiveRegion?: 'none' | 'polite' | 'assertive';
     /** Platform-specific properties are applied after shared props. */
@@ -255,8 +273,6 @@ export interface TextInputProps {
     id?: string;
     value?: string;
     placeholder?: string;
-    /** NativeScript's term for placeholder — web maps hint → placeholder. */
-    hint?: string;
     onChange?: (value: string) => void;
     bind?: (h: TextInputHandle) => void;
     secure?: boolean;
@@ -273,6 +289,9 @@ export interface TextInputProps {
     web?: any;
 }
 export interface TextAreaProps extends TextInputProps {
+    /** Submit on native only when `returnKeyType` is `done` or `send`; other
+     * returns insert newlines because TextView emits returnPress per newline.
+     * Web submits on Cmd/Ctrl+Enter. */
     /** Height in text rows. Web: the `rows` attr (fixed box); native:
      *  minHeight at the widget's measured line height. With `autoGrow` it
      *  becomes the starting height instead of a fixed one. */
@@ -286,17 +305,64 @@ export interface TextAreaProps extends TextInputProps {
      *  sets truncation on iOS — not a cap). */
     maxRows?: number;
 }
-export interface ListProps {
+/** Chrome-reset search field — TextInput with a leading glyph and a clear
+ *  affordance, normalized: the web leaf is `<input type="search">` with the
+ *  engine's own clear button hidden (the leaf draws the same one native
+ *  gets), the native leaf is a styled TextField with `returnKeyType`
+ *  `'search'`. Not UISearchBar — OS search chrome is deliberately absent. */
+export interface SearchInputProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    /** Controlled text — pair with `onChange`. */
+    value?: string;
+    /** Initial text for uncontrolled use. */
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Enter on web, the keyboard's `search` return key on native. */
+    onSubmit?: () => void;
+    /** The clear button tapped — fires after `onChange('')`. */
+    onClear?: () => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    placeholder?: string;
+    editable?: boolean;
+    /** Leading glyph — a registered icon name. Defaults to the built-in
+     *  `'xplat-search'` glyph; `false` renders no glyph. */
+    icon?: string | false;
+    bind?: (h: TextInputHandle) => void;
+    accessibilityLabel?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Pull-to-refresh contract — shared by `ScrollView` and the platform
+ *  lists (`UITableView`/`RecyclerView`). The indicator is self-drawn (the
+ *  `vx-spinner` ring), not the OS spinner, so the affordance is the same
+ *  pixels on every target. The pull gesture is enabled by `onRefresh`;
+ *  `refreshing` is controlled — set it true while reloading to keep the
+ *  indicator docked, false to collapse it. */
+export interface RefreshProps {
+    /** True while a refresh is in flight — docks the indicator strip above
+     *  the content. Read-only after the initial pull: the app owns it. */
+    refreshing?: boolean;
+    /** Enables the pull gesture; fires when the user pulls past
+     *  `refreshThreshold` and releases. */
+    onRefresh?: () => void;
+    /** Pull distance past the top edge (px on web, dip on native) whose
+     *  release fires `onRefresh`. Defaults to the indicator strip height
+     *  (64). */
+    refreshThreshold?: number;
+}
+export interface ListProps extends RefreshProps {
     className?: any;
     style?: any;
     id?: string;
     items: any[];
     renderItem: (item: any, index: number) => any;
     renderEmpty?: () => any;
-    /** Stable item key for web reconciliation. Falls back to `item.id`; native
-     *  ListView recycles by index and does not consume keys. */
-    keyFor?: (item: any) => string | number;
-    /** Native iOS row-height estimate. Web virtualization is not enabled in v1. */
+    /** iOS row-height estimate (UITableView only). */
     estimatedItemHeight?: number;
     /** Called when the list approaches its end. */
     onEndReached?: () => void;
@@ -305,7 +371,33 @@ export interface ListProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-export interface ScrollViewProps extends LayoutChildProps, GlassSurfaceProps {
+/** Paged horizontal swipe container — onboarding flows, media galleries.
+ *  Chrome-reset OS paging on native (ViewPager2 / UICollectionView paging via
+ *  @nativescript-community/ui-pager), a scroll-snap scroller on web. Follows
+ *  the platform-list contract: `items` + `renderItem`, no children — each
+ *  page is a full-host-size cell. No indicator is built in; compose dots
+ *  from `Row` + `View` driven by `page`/`onPageChange`. */
+export interface PagerProps extends LayoutChildProps, AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: any[];
+    renderItem: (item: any, index: number) => any;
+    renderEmpty?: () => any;
+    /** Controlled page index — pass with `onPageChange` to own the page.
+     *  Writes scroll/settle to the page; user swipes call `onPageChange`. */
+    page?: number;
+    /** Starting page for uncontrolled use (default 0). */
+    defaultPage?: number;
+    /** Fires when the settled page changes — a completed swipe on both
+     *  targets. Programmatic `page` writes do not echo back through it. */
+    onPageChange?: (index: number) => void;
+    /** Platform escape hatches, applied after the shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface ScrollViewProps extends LayoutChildProps, AccessibilityProps, RefreshProps {
     className?: any;
     style?: any;
     id?: string;
@@ -319,7 +411,7 @@ export interface ScrollViewProps extends LayoutChildProps, GlassSurfaceProps {
 /** Scrollable ordinary content on web. Native is an inline flex container so
  * a child ListView can own the scrolling without nesting recycling views in a
  * native ScrollView. */
-export interface ScrollBoxProps extends LayoutChildProps, GlassSurfaceProps {
+export interface ScrollBoxProps extends LayoutChildProps, AccessibilityProps {
     className?: any;
     style?: any;
     id?: string;
@@ -329,6 +421,70 @@ export interface ScrollBoxProps extends LayoutChildProps, GlassSurfaceProps {
     android?: any;
     web?: any;
 }
+export interface WebViewHandle {
+    /** Re-request the current document. */
+    reload(): void;
+    /** Frame-local history navigation. */
+    goBack(): void;
+    goForward(): void;
+    stopLoading(): void;
+    /** The platform view (`HTMLIFrameElement` / NS `WebView`). */
+    native: any;
+}
+export interface WebViewLoadEvent {
+    /** The loaded document URL when the platform reports one — absent for
+     *  `html` documents. */
+    url?: string;
+    /** Failure description; present only on the `onError` path. */
+    error?: string;
+}
+/** Embedded web document — chrome-reset bucket: web renders a sandboxed
+ *  `<iframe>`, native renders the OS web view (`webview` → WKWebView /
+ *  android.webkit.WebView). The *frame* is normalized; the document's
+ *  pixels belong to each platform's engine, same as TextInput's IME.
+ *  No JS bridge: iframe `postMessage`, WKScriptMessageHandler, and
+ *  `addJavascriptInterface` have different page-side contracts, so a
+ *  shared one would be fake parity — reach it through the escape bags. */
+export interface WebViewProps extends LayoutChildProps, AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    /** Remote document URL. Native also accepts `~/` bundle paths and
+     *  absolute file paths (NS `src` grammar). */
+    src?: string;
+    /** Inline HTML document — web `srcdoc`; native loads it through the
+     *  `src` property's data path (`loadHTMLString`/`loadDataWithBaseURL`).
+     *  Takes precedence over `src` when both are set. Treated as trusted
+     *  content — the default web sandbox keeps `allow-same-origin`, so a
+     *  srcdoc document can reach the embedding page. */
+    html?: string;
+    /** After each successful document load (web `load`; native
+     *  `loadFinished` without an error). */
+    onLoad?: (e: WebViewLoadEvent) => void;
+    /** On load failure. Native reports the NS `loadFinished` error string;
+     *  web maps the iframe `error` event, which does not fire reliably
+     *  cross-browser — treat as best-effort there. */
+    onError?: (e: WebViewLoadEvent) => void;
+    /** Default true. `false` freezes inner scrolling: web writes
+     *  `scrolling="no"`, iOS clears the WKWebView scrollView's
+     *  `scrollEnabled`, Android eats move touch events on the view (link
+     *  taps still pass; drag text selection inside the frame is lost). */
+    scrollEnabled?: boolean;
+    /** Web only — the iframe `sandbox` token list. Defaults to
+     *  `'allow-scripts allow-same-origin allow-forms allow-modals'`: the
+     *  capabilities NS WebView content already has, while top navigation,
+     *  popups, and downloads stay contained. Pass a token list to tighten,
+     *  `false` for no sandbox attribute. Ignored on native — the OS web
+     *  views are already isolated processes. */
+    sandbox?: string | false;
+    /** Imperative handle — reload/back/forward/stop plus `native` for
+     *  anything the shared props don't cover. */
+    bind?: (h: WebViewHandle) => void;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
 export interface ImageProps extends LayoutChildProps {
     className?: any;
     style?: any;
@@ -376,6 +532,8 @@ export interface DrawerProps {
     main?: any;
     drawer?: any;
     open?: boolean;
+    /** Backdrop tap — the self-drawn leaf fires it on both platforms. */
+    onDismiss?: () => void;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
@@ -439,8 +597,11 @@ export interface IconProps {
 /** One registered icon representation. `svg` contains path `d` data;
  *  `markup` is full inner-SVG markup (groups, transforms, several paths)
  *  rendered inside an `<svg viewBox>` shell on web and through `svgview`
- *  (ui-svg) on native. `font`, `src`, and `text` are per-platform
- *  fallbacks, in that order. */
+ *  (ui-svg) on native. `font`, `src`, and `text` are fallback
+ *  representations, in that order after SVG. `src` may be a raster source or
+ *  an SVG source; SVG is auto-detected for inline markup, SVG data URIs, and
+ *  `.svg` paths/URLs. Opaque resource names need `markup`/`svg` when their
+ *  format cannot be inferred from the string. */
 export interface IconGlyph {
     svg?: string;
     markup?: string;
@@ -462,9 +623,6 @@ export interface HeadingProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-export interface PlatformBadgeProps {
-    className?: any;
-}
 export interface OverlayProps {
     open?: boolean;
     onDismiss?: () => void;
@@ -496,15 +654,71 @@ export interface PopoverProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
+export interface HoverableProps {
+    /** Content shown after the pointer rests over the children on web. */
+    card: any;
+    /** Styling for the card's wrapper view inside the popover — e.g. a
+     *  pointer bridge covering the anchor↔card gap or a positional offset. */
+    cardClassName?: any;
+    cardStyle?: any;
+    children?: any;
+    openDelay?: number;
+    closeDelay?: number;
+    placement?: PopoverPlacement;
+    className?: any;
+    style?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+/** Web-only tooltip (`@octane-xplat/ui/web`, decision #47) — `trigger` is
+ *  the anchor content, `content` the tooltip body. Hover-intent delay plus
+ *  keyboard focus; wires `aria-describedby` onto the focusable trigger and
+ *  dismisses on Escape, blur, or scroll. */
+export interface TooltipProps {
+    trigger: any;
+    content: any;
+    /** Styling for the tooltip panel inside the popover. */
+    contentClassName?: any;
+    contentStyle?: any;
+    openDelay?: number;
+    closeDelay?: number;
+    placement?: PopoverPlacement;
+    disabled?: boolean;
+    className?: any;
+    style?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
 export type ToastContent = string | (() => any);
-export type ToastPosition = 'top' | 'bottom';
+export type ToastPosition = 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end';
 export interface ToastOptions {
     duration?: number;
     position?: ToastPosition;
+    /** When set, the toast is positioned by Popover relative to this view. */
+    anchor?: PopoverAnchorRef;
+    /** Placement used with `anchor`; `position` supplies the top/bottom default. */
+    placement?: PopoverPlacement;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
+export interface MeasureBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface UseMeasureOptions {
+    /** Re-measure on layout, resize, scroll, and content-size changes. Defaults to true. */
+    observe?: boolean;
+}
+export interface MeasureResult {
+    /** Pass to a View's `bind` prop. */
+    bind: (element: any) => void;
+    bounds: MeasureBounds | null;
+}
 export interface ModalProps {
     open?: boolean;
     onClose?: (result?: ModalOpenResult) => void;
@@ -543,6 +757,14 @@ export interface SheetProps {
     onDismiss?: () => void;
     /** Dim backdrop + tap-to-dismiss (default true). */
     shadeCover?: boolean;
+    /** Snap heights as viewport-height fractions, e.g. `[0.25, 0.5, 1]` —
+     *  sorted ascending; the sheet opens at the smallest and drags between
+     *  detents via the grabber strip, releasing below half of the smallest
+     *  dismisses (same dismissal as a shade tap — `onDismiss` / resolve).
+     *  Absent → the panel keeps its content-sized height. In-window on
+     *  every target; OS sheet presentations stay in the platform
+     *  subpaths. */
+    detents?: number[];
     className?: any;
     style?: any;
     children?: any;
@@ -553,6 +775,8 @@ export interface SheetProps {
 /** Options for the imperative `openSheet` service. */
 export interface SheetOpenOptions {
     shadeCover?: boolean;
+    /** Same contract as `SheetProps.detents`. */
+    detents?: number[];
 }
 /** Imperative sheet: mounts `component` on a dedicated root in a bottom
  *  sheet and resolves with the value passed to `close(result)`. The
@@ -560,10 +784,18 @@ export interface SheetOpenOptions {
 export type OpenSheet = (component: any, params?: any, options?: SheetOpenOptions) => Promise<ModalOpenResult>;
 export interface TabSpec {
     title: string;
+    /** Registered icon name (see `registerIcons`). The shared self-drawn
+     *  `Tabs` renders the glyph through `Icon` on every platform. The
+     *  platform tab bars (`UITabBar`/`BottomNavigationView` in the ios/
+     *  android subpaths) consume the glyph's `src` (a NativeScript
+     *  iconSource URI — `sys://` SF Symbol, `res://`, `font://`, file
+     *  path) or `font`/`text` representation; `svg`/`markup`-only glyphs
+     *  warn and render title-only there. */
+    icon?: string;
     render: () => any;
-    /** Named parallel stack — native hosts a Frame per such pane; on web
-     *  the pane is the route outlet for `stack` (pushed screens render in
-     *  place). navigate(name, params, {into: spec.stack}) targets it. */
+    /** Named parallel stack — the pane is the route outlet for `stack`
+     *  (pushed screens render in place). The platform tab bars host a real
+     *  Frame per such pane. */
     stack?: string;
 }
 export interface TabsProps {
@@ -664,6 +896,13 @@ export interface OpenWindowOptions {
     /** Optional URL used by the web window. */
     url?: string;
 }
+/**
+ * Value returned by `useAnimation(initial, prop)`. On web, `prop` supports
+ * translateX/translateY/translateZ, scale/scaleX/scaleY, rotate/rotateX/
+ * rotateY, and skewX/skewY as CSS transforms, plus `opacity` and other CSS
+ * style properties. On NativeScript, `prop` is the name of a NativeScript
+ * view property (for example, `translateX` or `opacity`).
+ */
 export interface AnimatedValue {
     readonly value: number;
     bind(el: any): void;
@@ -676,6 +915,712 @@ export interface AnimatedValue {
     }): void;
     stop(): void;
 }
+/** Button composes Pressable — same-props/same-pixels, self-drawn. `loading`
+ *  shows the spinner and blocks presses. */
+export interface ButtonProps extends PressableProps {
+    loading?: boolean;
+    /** Content rendered before children (e.g. an Icon). */
+    leading?: any;
+    /** Content rendered after children. */
+    trailing?: any;
+}
+/** Collapsible shows/hides `children` behind a `trigger`. Controlled via
+ *  `open`/`onOpenChange` or uncontrolled via `defaultOpen`. */
+export interface CollapsibleProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    trigger?: any;
+    children?: any;
+    open?: boolean;
+    defaultOpen?: boolean;
+    disabled?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    accessibilityLabel?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface AccordionItemSpec {
+    key: string;
+    header?: any;
+    content?: any;
+    disabled?: boolean;
+}
+/** Accordion — a list of Collapsibles. `open` is the open key (or keys with
+ *  `multiple`); omit it for uncontrolled via `defaultOpen`. */
+export interface AccordionProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: AccordionItemSpec[];
+    multiple?: boolean;
+    open?: string | string[];
+    defaultOpen?: string | string[];
+    onOpenChange?: (open: string | string[]) => void;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Self-drawn checkbox — box + check mark, identical pixels across targets. */
+export interface CheckboxProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    checked?: boolean;
+    disabled?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    label?: string;
+    accessibilityLabel?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface RadioOption {
+    value: string;
+    label?: string;
+    disabled?: boolean;
+}
+/** Self-drawn radio group — dot options in a column/row. */
+export interface RadioGroupProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    options: RadioOption[];
+    value?: string;
+    disabled?: boolean;
+    horizontal?: boolean;
+    onValueChange?: (value: string) => void;
+    accessibilityLabel?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Self-drawn segmented control — a row of equal-width segments in a track,
+ *  one selected (UISegmentedControl / Material segmented-button shape, no OS
+ *  chrome). `value`/`onValueChange` for controlled, `defaultValue` for
+ *  uncontrolled; `disabled` on the group or per-option. Sizes come from
+ *  className, matching the Button family. */
+export interface SegmentedControlProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    options: RadioOption[];
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+    disabled?: boolean;
+    accessibilityLabel?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface MenuItem {
+    key: string;
+    label?: string;
+    icon?: string;
+    disabled?: boolean;
+    onSelect?: () => void;
+}
+/** DropdownMenu — `trigger` anchored to a self-drawn item list via Popover.
+ *  Same anchored listbox on every target (decision #48). */
+export interface DropdownMenuProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    /** Anchor content — rendered inside the trigger Pressable. */
+    trigger?: any;
+    items: MenuItem[];
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    placement?: PopoverPlacement;
+    disabled?: boolean;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** ContextMenu — same anchored list as DropdownMenu, opened by right-click
+ *  on web and long-press on native. */
+export interface ContextMenuProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: MenuItem[];
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children?: any;
+    disabled?: boolean;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Badge — inline label chip. Pure composition, unstyled beyond layout. */
+export interface BadgeProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Separator — hairline rule between content. */
+export interface SeparatorProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    orientation?: 'horizontal' | 'vertical';
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Skeleton — placeholder block shown while content loads. */
+export interface SkeletonProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    width?: number;
+    height?: number;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Avatar — circular image with a text fallback. */
+export interface AvatarProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    src?: string;
+    alt?: string;
+    /** Fallback text (initials) shown when `src` is missing/fails. */
+    fallback?: string;
+    size?: number;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** AvatarGroup — overlapping row of avatars with an optional `+N` overflow. */
+export interface AvatarGroupProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    /** Max avatars rendered; the rest collapse into a `+N` avatar. */
+    max?: number;
+    size?: number;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** FormField wraps a control with a label, hint, and error text. The error
+ *  replaces the hint when present. Children is the control element. */
+export interface FormFieldProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    label?: string;
+    hint?: string;
+    error?: string;
+    required?: boolean;
+    children?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** FieldGroup — labeled group of related fields (role=group). */
+export interface FieldGroupProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    label?: string;
+    children?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** InputNumber — normalized TextInput (number keyboard) flanked by −/+
+ *  steppers. `value`/`onValueChange` for controlled, `defaultValue` for
+ *  uncontrolled. `step` defaults to 1; `min`/`max` clamp. */
+export interface InputNumberProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    value?: number;
+    defaultValue?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    placeholder?: string;
+    onValueChange?: (value: number) => void;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** PinInput — a row of single-character cells that auto-advance on entry.
+ *  `onComplete` fires when all `length` cells are filled. */
+export interface PinInputProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    length?: number;
+    value?: string;
+    onValueChange?: (value: string) => void;
+    onComplete?: (value: string) => void;
+    secure?: boolean;
+    disabled?: boolean;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface SelectOption {
+    value: string;
+    label?: string;
+    disabled?: boolean;
+}
+/** Select — anchored self-drawn listbox on every target (decision #48).
+ *  `multiple` keeps the listbox open and reports string[]; `searchable`
+ *  puts a normalized TextInput filter at the top of the listbox. */
+export interface SelectProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    options: SelectOption[];
+    value?: string | string[];
+    defaultValue?: string | string[];
+    multiple?: boolean;
+    searchable?: boolean;
+    placeholder?: string;
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    onValueChange?: (value: string | string[]) => void;
+    disabled?: boolean;
+    placement?: PopoverPlacement;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** InputTags — chip list + trailing normalized TextInput. Enter commits a
+ *  tag, Backspace on an empty field removes the last tag. */
+export interface InputTagsProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (tags: string[]) => void;
+    placeholder?: string;
+    max?: number;
+    disabled?: boolean;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** InputRating — row of tappable glyphs reporting a 1..max score. */
+export interface InputRatingProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    value?: number;
+    defaultValue?: number;
+    max?: number;
+    /** Glyph per cell — a Text character (default ★) or a registered Icon name. */
+    icon?: string;
+    onValueChange?: (value: number) => void;
+    disabled?: boolean;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** CheckboxGroup — multi-select list of self-drawn checkboxes. */
+export interface CheckboxGroupProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    options: RadioOption[];
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (values: string[]) => void;
+    disabled?: boolean;
+    horizontal?: boolean;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface BreadcrumbItem {
+    label: string;
+    onSelect?: () => void;
+}
+/** Breadcrumb — ancestor trail. Items render as pressable links separated
+ *  by `separator` (default /). */
+export interface BreadcrumbProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: BreadcrumbItem[];
+    separator?: string;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Pagination — prev/next + a windowed run of page buttons around `page`. */
+export interface PaginationProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    page: number;
+    pageCount: number;
+    /** Pages shown to each side of `page` (default 1). */
+    siblingCount?: number;
+    onPageChange?: (page: number) => void;
+    disabled?: boolean;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface StepperStep {
+    key: string;
+    label?: string;
+    icon?: string;
+    disabled?: boolean;
+}
+/** Stepper — numbered step row. Steps before `current` show a done mark;
+ *  tapping a non-disabled step calls `onStepChange`. */
+export interface StepperProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    steps: StepperStep[];
+    current?: number;
+    onStepChange?: (index: number) => void;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface NavigationMenuItem {
+    key: string;
+    label?: string;
+    icon?: string;
+    active?: boolean;
+    disabled?: boolean;
+    onSelect?: () => void;
+}
+/** NavigationMenu — row (or column) of nav items; mostly a desktop/web
+ *  idiom — the mobile equivalent is Tabs/Drawer. */
+export interface NavigationMenuProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: NavigationMenuItem[];
+    horizontal?: boolean;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** CommandPalette — overlay with a search field over a filtered action
+ *  list. Esc/outside dismisses, Enter selects the highlighted match. */
+export interface CommandPaletteProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    items: MenuItem[];
+    placeholder?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface TableColumn {
+    key: string;
+    label?: string;
+    /** Column width in dips; omit to share the remaining space evenly. */
+    width?: number;
+    align?: 'left' | 'center' | 'right';
+}
+/** Table — self-drawn grid via rows + cells. Bounded and unvirtualized:
+ *  large datasets belong to the platform UITableView/RecyclerView
+ *  subpaths, not this component. */
+export interface TableProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    columns: TableColumn[];
+    rows: Record<string, any>[];
+    /** Cell override — default renders row[col.key] as text. */
+    renderCell?: (row: Record<string, any>, column: TableColumn, rowIndex: number) => any;
+    /** Row key; defaults to the row index. */
+    keyFor?: (row: Record<string, any>, rowIndex: number) => string;
+    onRowPress?: (row: Record<string, any>, rowIndex: number) => void;
+    empty?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface TimelineItem {
+    key: string;
+    title?: string;
+    description?: string;
+    time?: string;
+    icon?: string;
+}
+/** Timeline — vertical list of events with dot + connector. */
+export interface TimelineProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: TimelineItem[];
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface TreeNode {
+    key: string;
+    label?: string;
+    children?: TreeNode[];
+    disabled?: boolean;
+}
+/** Tree — recursive indent + collapse. `defaultExpanded` seeds the open
+ *  set; `onToggle` reports changes. */
+export interface TreeProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    nodes: TreeNode[];
+    defaultExpanded?: string[];
+    onToggle?: (key: string, open: boolean) => void;
+    onSelect?: (node: TreeNode) => void;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Alert — status callout. `tone` maps to a class modifier; error tone
+ *  gets role=alert on web, others role=status. */
+export interface AlertProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    tone?: 'info' | 'success' | 'warning' | 'error';
+    icon?: string;
+    title?: string;
+    children?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Card — container with optional header/footer slots. */
+export interface CardProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    header?: any;
+    footer?: any;
+    children?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Chip — small action/filter element: pressable, optional selected state,
+ *  optional ✕ remove affordance. */
+export interface ChipProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    selected?: boolean;
+    disabled?: boolean;
+    onSelect?: () => void;
+    onRemove?: () => void;
+    accessibilityLabel?: string;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Kbd — keyboard key glyph (⌘K styling hook). */
+export interface KbdProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Empty — empty-state block: icon + title + description + actions. */
+export interface EmptyProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    icon?: string;
+    title?: string;
+    description?: string;
+    children?: any;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** Banner — inline notice strip with optional dismiss. */
+export interface BannerProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    icon?: string;
+    children?: any;
+    onDismiss?: () => void;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** User — avatar + name/description row. */
+export interface UserProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    name?: string;
+    description?: string;
+    src?: string;
+    fallback?: string;
+    size?: number;
+    onSelect?: () => void;
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** ProgressGroup — stacked labeled Meter rows. */
+export interface ProgressGroupProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    items: {
+        key: string;
+        label?: string;
+        value: number;
+        max?: number;
+    }[];
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export type VideoFit = 'contain' | 'cover' | 'fill';
+export interface VideoEvent {
+    /** Playback position in milliseconds. */
+    position?: number;
+    /** Clip duration in milliseconds, once known (0 before then). */
+    duration?: number;
+    /** Failure description. */
+    message?: string;
+}
+export interface VideoHandle {
+    play(): void;
+    pause(): void;
+    /** Seek to a position in milliseconds. */
+    seekTo(ms: number): void;
+    /** Current playback position in ms (0 before metadata loads). */
+    currentTime(): number;
+    /** Clip duration in ms (0 before metadata loads). */
+    duration(): number;
+    /** The platform surface (`HTMLVideoElement` / plugin `Video`). */
+    native: any;
+}
+/** Embedded video — surface-hosted bucket: the OS engine owns the pixels
+ *  (web `<video>` / `@nstudio/nativescript-exoplayer` → AVPlayerViewController
+ *  + ExoPlayer2), all chrome is self-drawn so `controls` looks identical on
+ *  every target. Times are milliseconds on every platform. */
+export interface VideoProps extends LayoutChildProps, AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    /** Remote URL; native also accepts `~/` bundle paths and absolute files. */
+    src: string;
+    /** Frame shown until playback starts. */
+    poster?: string;
+    /** Controlled playback — pair with `onPlayingChange`. Leave unset for
+     *  uncontrolled playback (the transport and `bind` handle still work). */
+    playing?: boolean;
+    /** Uncontrolled start-playing shorthand. Browsers block unmuted
+     *  autoplay — pair with `muted` when `autoPlay` matters on web. */
+    autoPlay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    /** Self-drawn transport overlay (play/pause, scrubber, time, mute) —
+     *  tap the surface to show/hide. Default true. */
+    controls?: boolean;
+    /** Content fitting inside the frame: `contain` (letterbox, default),
+     *  `cover` (crop to fill), `fill` (stretch). */
+    fit?: VideoFit;
+    /** Playback metadata is loaded; `e.duration` is the clip length in ms. */
+    onReady?: (e: VideoEvent) => void;
+    onEnded?: () => void;
+    /** Fires on user toggles and controlled `playing` writes. */
+    onPlayingChange?: (playing: boolean) => void;
+    /** Fires when the transport's mute button toggles. */
+    onMutedChange?: (muted: boolean) => void;
+    /** Web only — the plugin players surface no error event on native. */
+    onError?: (e: VideoEvent) => void;
+    /** Imperative handle — play/pause/seek/time plus `native` for anything
+     *  the shared props don't cover. */
+    bind?: (h: VideoHandle) => void;
+    /** Platform escape hatches, applied after the shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface CameraViewHandle {
+    /** The platform view (`HTMLVideoElement` / plugin `CameraPlus`). */
+    native: any;
+}
+/** Live camera preview — surface-hosted: web runs `getUserMedia` into a
+ *  `<video>`, native embeds `CameraPlus` (@nstudio/nativescript-camera-plus;
+ *  AVCaptureSession preview / CameraX FancyCamera) with its built-in
+ *  buttons switched off. Still capture is deliberately not on the handle —
+ *  `media.capturePhoto` in `@octane-xplat/platform` owns that; reach the
+ *  preview's own capture (e.g. `CameraPlus.takePicture`) through `bind`'s
+ *  `native` when the intent UI won't do. The leaf owns the permission
+ *  request on both platforms. */
+export interface CameraViewProps extends LayoutChildProps, AccessibilityProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    /** Lens — default `'back'`. */
+    facing?: 'front' | 'back';
+    /** Default true. `false` tears down the preview stream/session. */
+    active?: boolean;
+    /** The preview surface is live (web: first frame; native: view loaded
+     *  after permission — the sensor may still be warming). */
+    onReady?: () => void;
+    onError?: (e: {
+        message?: string;
+    }) => void;
+    /** Imperative handle — `native` for anything the shared props don't
+     *  cover (torch, zoom, preview-frame capture). */
+    bind?: (h: CameraViewHandle) => void;
+    /** Platform escape hatches, applied after the shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
 export type ColorScheme = 'light' | 'dark';
 /** Minimal external-store contract `useStore` subscribes to. */
 export interface ReadableStore<T> {