@octane-xplat/ui 0.3.0 → 0.5.0

package/types/props.d.ts

@@ -32,7 +32,42 @@ export interface LayoutChildProps {
     alignSelf?: string;
     order?: number;
 }
-export interface GridProps {
+/** Flex-container props shared by View/Row/Pressable — RN vocabulary, applied
+ *  to the host flexboxlayout natively and the element's style on web.
+ *  `gap` is a dip number (px on web); NS supports it on FlexboxLayout only
+ *  (GridLayout has no gap). */
+export interface FlexContainerProps {
+    justifyContent?: 'start' | 'center' | 'end' | 'space-between' | 'space-around' | 'space-evenly';
+    alignItems?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    flexWrap?: boolean | 'wrap' | 'nowrap' | 'wrap-reverse';
+    gap?: number | string;
+    rowGap?: number | string;
+    columnGap?: number | string;
+}
+/** Liquid Glass material config. Native maps it to `iosGlassEffect`
+ *  (iOS 26+; inert on Android and older iOS), web to the `vx-glass`
+ *  backdrop-filter approximation. `variant:'clear'` is the faint,
+ *  mostly-transparent glass; `'regular'` is Apple's default. */
+export interface GlassConfig {
+    variant?: 'regular' | 'clear' | 'identity' | 'none';
+    /** Touch-tracking highlight — only meaningful on <LiquidGlass>; the
+     *  per-view glass applied by `glass` never receives touches upstream. */
+    interactive?: boolean;
+    tint?: string;
+    /** (LiquidGlassContainer only) merge distance between glass siblings. */
+    spacing?: number;
+    /** 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 {
     className?: any;
     style?: any;
     children?: any;
@@ -42,22 +77,55 @@ export interface GridProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
-export interface StackProps {
+export interface StackProps extends GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
-export interface AbsoluteProps {
+export interface AbsoluteProps extends GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
+}
+/** Interactive glass surface — the element root IS the platform's glass
+ *  effect view (NS `LiquidGlass`, a UIVisualEffectView hosting children).
+ *  Real material on iOS 26+; inert layout on Android and older iOS;
+ *  backdrop-filter approximation on web. */
+export interface LiquidGlassProps extends LayoutChildProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    variant?: 'regular' | 'clear';
+    interactive?: boolean;
+    tint?: string;
+    animateChangeDuration?: number;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+/** Merged-glass region — sibling glass elements inside morph together
+ *  across `spacing` dips (NS `LiquidGlassContainer`, an AbsoluteLayout:
+ *  children position via left/top). */
+export interface LiquidGlassContainerProps extends LayoutChildProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    spacing?: number;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
 }
 export interface SpacerProps {
     className?: any;
@@ -65,8 +133,9 @@ export interface SpacerProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
-export interface ViewProps extends LayoutChildProps {
+export interface ViewProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
@@ -81,23 +150,31 @@ export interface ViewProps extends LayoutChildProps {
     android?: any;
     web?: any;
 }
-export interface RowProps extends LayoutChildProps {
+export interface RowProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
+    id?: string;
     /** 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. */
@@ -114,7 +191,32 @@ export interface TextProps extends LayoutChildProps {
     android?: any;
     web?: any;
 }
-export interface PressableProps extends LayoutChildProps {
+/** Inline rich text container. Children should be RichTextSpan components so
+ * the native leaf can preserve each run as a NativeScript Span. */
+export interface RichTextProps extends LayoutChildProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+/** One styled or tappable inline run inside RichText. `text` is an explicit
+ * native-safe escape hatch; a single string child is also accepted. */
+export interface RichTextSpanProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    text?: string;
+    onPress?: () => void;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface PressableProps extends LayoutChildProps, FlexContainerProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     children?: any;
@@ -125,7 +227,7 @@ export interface PressableProps extends LayoutChildProps {
     onLongPress?: () => void;
     accessible?: boolean;
     accessibilityLabel?: string;
-    accessibilityRole?: string;
+    accessibilityRole?: Role;
     onPressIn?: () => void;
     onPressOut?: () => void;
     onDoublePress?: () => void;
@@ -177,6 +279,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. */
@@ -200,9 +305,6 @@ export interface ListProps {
     /** 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;
-    /** Metadata hint only in v1. Switch heterogeneous row markup in renderItem;
-     *  the current renderers do not consume this value. */
-    kindFor?: (item: any) => string;
     /** Native iOS row-height estimate. Web virtualization is not enabled in v1. */
     estimatedItemHeight?: number;
     /** Called when the list approaches its end. */
@@ -212,7 +314,7 @@ export interface ListProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-export interface ScrollViewProps extends LayoutChildProps {
+export interface ScrollViewProps extends LayoutChildProps, GlassSurfaceProps {
     className?: any;
     style?: any;
     id?: string;
@@ -223,6 +325,19 @@ export interface ScrollViewProps extends LayoutChildProps {
     android?: any;
     web?: any;
 }
+/** 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 {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    /** Platform-specific properties are applied after the shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
 export interface ImageProps extends LayoutChildProps {
     className?: any;
     style?: any;
@@ -242,6 +357,7 @@ export interface ScreenProps {
     ios?: any;
     android?: any;
     web?: any;
+    id?: string;
 }
 export interface SafeAreaProps {
     className?: any;
@@ -251,6 +367,7 @@ export interface SafeAreaProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
 export interface KeyboardAvoidingProps {
     className?: any;
@@ -259,10 +376,12 @@ export interface KeyboardAvoidingProps {
     ios?: Record<string, any>;
     android?: Record<string, any>;
     web?: Record<string, any>;
+    id?: string;
 }
 export interface DrawerProps {
     className?: any;
     style?: any;
+    id?: string;
     main?: any;
     drawer?: any;
     open?: boolean;
@@ -290,6 +409,19 @@ export interface ActivityIndicatorProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
+export interface MeterProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    children?: any;
+    value: number;
+    max?: number;
+    size?: number;
+    strokeWidth?: number;
+    color?: string;
+    trackColor?: string;
+    accessibilityLabel?: string;
+}
 export interface SliderProps {
     className?: any;
     style?: any;
@@ -313,9 +445,19 @@ export interface IconProps {
     android?: Record<string, any>;
     web?: Record<string, any>;
 }
-/** One registered icon representation. `svg` contains path `d` data. */
+/** 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 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;
+    viewBox?: string;
+    text?: string;
     font?: {
         family: string;
         glyph: string;
@@ -348,11 +490,17 @@ export interface OverlayProps {
     web?: Record<string, any>;
 }
 export type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** A platform-neutral ref to the host view or element that owns a popover. */
+export interface PopoverAnchorRef {
+    readonly current: unknown;
+}
 export interface PopoverProps {
-    /** Native view or web element, commonly a ref object populated by `bind`. */
-    anchor?: any;
+    /** Ref to a native view or web element, commonly populated by `bind`. */
+    anchor: PopoverAnchorRef;
     open?: boolean;
     placement?: PopoverPlacement;
+    dismissOnOutsideTap?: boolean;
+    onDismiss?: () => void;
     className?: any;
     style?: any;
     children?: any;
@@ -360,15 +508,51 @@ 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>;
+}
 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;
@@ -396,6 +580,32 @@ export interface ModalOpenOptions {
 export type ModalOpenResult = unknown;
 /** Public function shape of the imperative modal service. */
 export type OpenModal = (component: any, params?: any, options?: ModalOpenOptions) => Promise<ModalOpenResult>;
+/** Declarative in-window sheet: bottom-anchored panel on the enclosing
+ *  screen's RootLayout (native) or a document-body portal layer (web).
+ *  Unlike `Modal presentation='sheet'` (system modal), content stays
+ *  inside the app window — same window region as the declaring page. */
+export interface SheetProps {
+    open?: boolean;
+    /** Called when the shade is tapped or the sheet is dismissed by the
+     *  platform — not on programmatic `open`→`false` transitions. */
+    onDismiss?: () => void;
+    /** Dim backdrop + tap-to-dismiss (default true). */
+    shadeCover?: boolean;
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+/** Options for the imperative `openSheet` service. */
+export interface SheetOpenOptions {
+    shadeCover?: boolean;
+}
+/** Imperative sheet: mounts `component` on a dedicated root in a bottom
+ *  sheet and resolves with the value passed to `close(result)`. The
+ *  component receives `{ params, close }`. */
+export type OpenSheet = (component: any, params?: any, options?: SheetOpenOptions) => Promise<ModalOpenResult>;
 export interface TabSpec {
     title: string;
     render: () => any;
@@ -419,6 +629,44 @@ export interface Route {
     stack: string;
     name: string;
     params: Record<string, unknown>;
+    /** 'push' (default) pushes onto the stack · 'modal' opens its own root
+     *  (native: `showModal`; web: overlay pane, URL preserved) · 'fade' is a
+     *  push with a fade transition. A `+modal`/`+fade` filename suffix in
+     *  the route dir sets the manifest default; this field overrides it. */
+    presentation?: 'push' | 'modal' | 'fade';
+    /** Loader result supplied to the route screen as `data`. */
+    loaderData?: unknown;
+    /** Loader rejection supplied to the route screen as `error`. */
+    loaderError?: unknown;
+    /** Context returned by the route's `beforeLoad` export. It is merged into
+     * screen props and remains available from `useRoute`. */
+    context?: RouteContext;
+}
+/** Values shared by a route guard and the screen it admits. */
+export type RouteContext = Record<string, unknown>;
+export interface BeforeLoadArgs {
+    params: Record<string, unknown>;
+    context: RouteContext;
+}
+export type BeforeLoad = (args: BeforeLoadArgs) => RouteContext | void | Promise<RouteContext | void>;
+/** The deliberately small cross-platform head surface. `meta` keys become
+ * web `<meta name="..." content="...">` tags; native consumes `title`. */
+export interface RouteHead {
+    title?: string;
+    meta?: Record<string, string>;
+}
+export type RouteHeadExport = RouteHead | ((params: Record<string, unknown>) => RouteHead);
+export interface LinkProps {
+    href: string;
+    target?: string;
+    className?: any;
+    children?: any;
+}
+export interface NavLinkProps {
+    route: Route;
+    activeClassName?: string;
+    className?: any;
+    children?: any;
 }
 /** name → screen component table for `registerScreens` — the app owns the
  *  route table; native `pushRoute` resolves `route.name` through it and
@@ -435,6 +683,19 @@ export interface RouteMeta {
     params: string[];
     /** Source file (glob key) — diagnostics only. */
     file: string;
+    /** Declared default presentation — set by a `+modal`/`+fade` filename
+     *  suffix (`app/settings+modal.tsrx` → route 'settings', modal). */
+    presentation?: 'push' | 'modal' | 'fade';
+    /** Optional `loader` named export — a prefetch hook, not a data layer.
+     *  pushRoute fires it (fire-and-forget) before navigating so the
+     *  screen's `query$` reads hit a warm cache; boot/deep-link routes
+     *  skip it (the screen mounts in the same tick anyway). */
+    loader?: (params: Record<string, unknown>) => unknown;
+    /** Optional guard awaited before a push commits. A thrown `redirect(...)`
+     * short-circuits the attempted route. */
+    beforeLoad?: BeforeLoad;
+    /** Optional route title/meta declaration, or a params-only function. */
+    head?: RouteHeadExport;
 }
 /** Output of `deriveRouteManifest` — `screens` feeds `registerScreens`
  *  (native pushRoute + web outlet fallback), `routes` feeds web URL
@@ -443,7 +704,21 @@ export interface RouteManifest {
     screens: ScreenTable;
     routes: RouteMeta[];
     layouts: Record<string, any>;
-}
+    loaders?: Record<string, (params: Record<string, unknown>) => unknown | Promise<unknown>>;
+}
+export interface OpenWindowOptions {
+    /** Data made available to the native window content resolver. */
+    data?: Record<string, unknown>;
+    /** 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;