@octane-xplat/ui 0.2.1 → 0.3.0

package/types/index.d.ts

@@ -9,43 +9,99 @@
 import type { UniversalComponent } from 'octane/universal';
 import type {
 	AnimatedValue,
+	AbsoluteProps,
+	ActivityIndicatorProps,
 	ColorScheme,
+	DrawerProps,
+	GridProps,
+	HeadingProps,
+	IconGlyph,
+	IconProps,
 	ImageProps,
+	KeyboardAvoidingProps,
+	LayoutChildProps,
 	ListProps,
 	ModalProps,
+	ModalOpenOptions,
+	ModalOpenResult,
+	OpenModal,
+	OverlayProps,
+	PopoverPlacement,
+	PopoverProps,
 	PlatformBadgeProps,
 	PressableProps,
+	ReadableStore,
 	Route,
+	RouteManifest,
+	RouteMeta,
 	RowProps,
 	ScreenProps,
+	SafeAreaProps,
+	ScreenTable,
 	ScrollViewProps,
+	SliderProps,
+	Store,
+	SpacerProps,
+	StackProps,
 	SwitchProps,
 	TabSpec,
 	TabsProps,
+	TextAreaProps,
 	TextInputProps,
 	TextProps,
+	ToastContent,
+	ToastOptions,
+	ToastPosition,
 	ViewProps,
 } from './props';
 
 export type {
+	AbsoluteProps,
 	AnimatedValue,
+	ActivityIndicatorProps,
 	ColorScheme,
+	DrawerProps,
+	GridProps,
+	HeadingProps,
+	IconGlyph,
+	IconProps,
 	ImageProps,
+	KeyboardAvoidingProps,
+	LayoutChildProps,
 	ListProps,
 	ModalProps,
+	ModalOpenOptions,
+	ModalOpenResult,
+	OpenModal,
+	OverlayProps,
+	PopoverPlacement,
+	PopoverProps,
 	PanEvent,
 	PlatformBadgeProps,
 	PressableProps,
+	ReadableStore,
 	Route,
+	RouteManifest,
+	RouteMeta,
 	RowProps,
 	ScreenProps,
+	SafeAreaProps,
+	ScreenTable,
 	ScrollViewProps,
+	SliderProps,
+	Store,
+	SpacerProps,
+	StackProps,
 	SwipeEvent,
 	SwitchProps,
 	TabSpec,
 	TabsProps,
+	TextAreaProps,
 	TextInputProps,
 	TextProps,
+	ToastContent,
+	ToastOptions,
+	ToastPosition,
 	ViewProps,
 } from './props';
 
@@ -55,19 +111,38 @@ export declare const View: UniversalComponent<ViewProps>;
 /** Column-direction alias of View. */
 export declare const Column: UniversalComponent<ViewProps>;
 export declare const Row: UniversalComponent<RowProps>;
+export declare const Grid: UniversalComponent<GridProps>;
+export declare const Stack: UniversalComponent<StackProps>;
+export declare const Absolute: UniversalComponent<AbsoluteProps>;
+export declare const Spacer: UniversalComponent<SpacerProps>;
 export declare const Text: UniversalComponent<TextProps>;
 export declare const Pressable: UniversalComponent<PressableProps>;
 export declare const TextInput: UniversalComponent<TextInputProps>;
+export declare const TextArea: UniversalComponent<TextAreaProps>;
 export declare const List: UniversalComponent<ListProps>;
 export declare const ScrollView: UniversalComponent<ScrollViewProps>;
 export declare const Image: UniversalComponent<ImageProps>;
 export declare const Screen: UniversalComponent<ScreenProps>;
+export declare const SafeArea: UniversalComponent<SafeAreaProps>;
+export declare const KeyboardAvoiding: UniversalComponent<KeyboardAvoidingProps>;
+export declare const Drawer: UniversalComponent<DrawerProps>;
 export declare const Switch: UniversalComponent<SwitchProps>;
+export declare const ActivityIndicator: UniversalComponent<ActivityIndicatorProps>;
+export declare const Slider: UniversalComponent<SliderProps>;
+export declare const Icon: UniversalComponent<IconProps>;
+export declare const Heading: UniversalComponent<HeadingProps>;
 export declare const PlatformBadge: UniversalComponent<PlatformBadgeProps>;
 
+export declare function registerIcon(name: string, glyph: IconGlyph): void;
+export declare function registerIcons(record: Record<string, IconGlyph>): void;
+
 // ---------- overlays / shells ----------
 
 export declare const Modal: UniversalComponent<ModalProps>;
+export declare const openModal: OpenModal;
+export declare const Overlay: UniversalComponent<OverlayProps>;
+export declare const Popover: UniversalComponent<PopoverProps>;
+export declare function showToast(content: ToastContent, options?: ToastOptions): void;
 export declare const Tabs: UniversalComponent<TabsProps>;
 
 // ---------- stacks (native registry; no-op on web) ----------
@@ -76,18 +151,44 @@ export declare function registerStack(name: string, frame: any): void;
 export declare function getStack(name: string): any;
 export declare function stackEntries(): IterableIterator<[string, any]>;
 
-// ---------- routes (web store; no-op on native) ----------
+// ---------- routes (real on both: URL store on web, Frame stacks on native) ----------
 
 export declare function pushRoute(r: Route): void;
+export declare function popRoute(stack?: string): void;
 export declare function routeFor(stack: string): Route | null;
 export declare function currentRoute(): Route | null;
 export declare function useRoute(stack: string): Route | null;
+/** name → screen table; native pushRoute resolves `route.name` through
+ *  it, web outlets fall back to it via `screenFor`. `manifest` (from
+ *  deriveRouteManifest) enables path-param URL matching on web. Call
+ *  once at boot. */
+export declare function registerScreens(table: ScreenTable, manifest?: RouteMeta[]): void;
+/** One-call registration for route-dir apps — screens + URL patterns +
+ *  layouts all come from deriveRouteManifest. */
+export declare function registerRoutes(manifest: RouteManifest): void;
+export declare function screenFor(name: string): any;
+/** Canonical /<stack>/<path> for a Route — Link's href on web. */
+export declare function hrefFor(r: Route): string;
+
+// ---------- route dir (file → route manifest; docs/navigation-notes.md) ----------
+
+/** Turn an `import.meta.glob` module map of the route dir into
+ *  {screens, routes, layouts}: `demo/[id].tsrx` → 'demo/:id',
+ *  `_layout.tsrx` → layouts[''], platform suffixes deduped by `prefer`
+ *  rank (web: ['web']; native: ['ios'|'android','native']). */
+export declare function deriveRouteManifest(
+	files: Record<string, any>,
+	prefer: readonly string[],
+	dir?: string,
+): RouteManifest;
 
 // ---------- animation / theme ----------
 
 export declare function useAnimation(initial?: number, prop?: string): AnimatedValue;
 export declare function getColorScheme(): ColorScheme;
 export declare function useColorScheme(): ColorScheme;
+export interface SafeAreaInsets { top: number; right: number; bottom: number; left: number; }
+export declare function useSafeAreaInsets(): SafeAreaInsets;
 
 // ---------- styled ----------
 
@@ -95,3 +196,9 @@ export declare function styled<P extends { className?: any }, V extends Record<s
 	Base: (props: P) => any,
 	def: { base?: any; variants?: V },
 ): UniversalComponent<P & { [K in keyof V]?: boolean }>;
+
+// ---------- stores ----------
+
+export declare function createStore<T>(initial: T): Store<T>;
+export declare function useStore<T>(store: ReadableStore<T>): T;
+export declare function useStore<T, S>(store: ReadableStore<T>, select: (state: T) => S): S;

package/types/props.d.ts

@@ -17,7 +17,56 @@ export interface PanEvent {
 export interface SwipeEvent {
     direction: number;
 }
-export interface ViewProps {
+/** Metadata read by parent layouts. Native forwards NativeScript attached
+ *  attributes; web folds the CSS equivalents into the child's style. */
+export interface LayoutChildProps {
+    row?: number;
+    col?: number;
+    rowSpan?: number;
+    colSpan?: number;
+    dock?: 'left' | 'top' | 'right' | 'bottom';
+    left?: number;
+    top?: number;
+    flexGrow?: number;
+    flexShrink?: number;
+    alignSelf?: string;
+    order?: number;
+}
+export interface GridProps {
+    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>;
+}
+export interface StackProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface AbsoluteProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface SpacerProps {
+    className?: any;
+    style?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface ViewProps extends LayoutChildProps {
     className?: any;
     style?: any;
     children?: any;
@@ -27,18 +76,45 @@ export interface ViewProps {
     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;
 }
-export interface RowProps {
+export interface RowProps extends LayoutChildProps {
     className?: any;
     style?: any;
     children?: any;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
 }
-export interface TextProps {
+export interface TextProps extends LayoutChildProps {
     className?: any;
     style?: any;
     children?: any;
+    numberOfLines?: number;
+    /** Native Label does not expose text selection; implemented with CSS on web. */
+    selectable?: boolean;
+    ellipsize?: 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. */
+    ios?: any;
+    android?: any;
+    web?: any;
 }
-export interface PressableProps {
+export interface PressableProps extends LayoutChildProps {
     className?: any;
     style?: any;
     children?: any;
@@ -50,42 +126,149 @@ export interface PressableProps {
     accessible?: boolean;
     accessibilityLabel?: string;
     accessibilityRole?: string;
+    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. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface TextInputHandle {
+    focus(): void;
+    blur(): void;
+    native: any;
 }
 export interface TextInputProps {
     className?: any;
     style?: any;
+    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;
+    keyboardType?: 'default' | 'email' | 'number' | 'decimal' | 'phone' | 'url';
+    returnKeyType?: 'done' | 'next' | 'go' | 'search' | 'send';
+    onSubmit?: () => void;
+    onFocus?: () => void;
+    onBlur?: () => void;
+    editable?: boolean;
+    placeholderTextColor?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface TextAreaProps extends TextInputProps {
+    /** 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. */
+    rows?: number;
+    /** Grow to fit content, capped by `maxRows`. Native TextView grows by
+     *  default — this prop exists so web (<textarea> is fixed-rows) matches;
+     *  without it, native gets a fixed `rows`-high box like web. */
+    autoGrow?: boolean;
+    /** Growth cap in rows — past it the field scrolls internally. Native:
+     *  maxHeight at measured line height (TextView's own `maxLines` only
+     *  sets truncation on iOS — not a cap). */
+    maxRows?: number;
 }
 export interface ListProps {
     className?: any;
     style?: any;
     id?: string;
     items: any[];
-    renderItem: (item: any) => 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;
+    /** 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. */
+    onEndReached?: () => void;
+    /** Platform escape hatches, applied after the shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
 }
-export interface ScrollViewProps {
+export interface ScrollViewProps extends LayoutChildProps {
     className?: any;
     style?: any;
     id?: string;
     horizontal?: boolean;
     children?: any;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
 }
-export interface ImageProps {
+export interface ImageProps extends LayoutChildProps {
     className?: any;
     style?: any;
     id?: string;
     src: string;
     alt?: string;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
 }
 export interface ScreenProps {
     className?: any;
     style?: any;
     children?: any;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface SafeAreaProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    /** NativeScript props applied to the host after shared props. */
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface KeyboardAvoidingProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface DrawerProps {
+    className?: any;
+    style?: any;
+    main?: any;
+    drawer?: any;
+    open?: boolean;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
 }
 export interface SwitchProps {
     className?: any;
@@ -93,16 +276,126 @@ export interface SwitchProps {
     id?: string;
     checked?: boolean;
     onCheckedChange?: (checked: boolean) => void;
+    /** Platform-specific properties are applied after shared props. */
+    ios?: any;
+    android?: any;
+    web?: any;
+}
+export interface ActivityIndicatorProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    busy?: boolean;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface SliderProps {
+    className?: any;
+    style?: any;
+    id?: string;
+    value: number;
+    minValue?: number;
+    maxValue?: number;
+    disabled?: boolean;
+    onValueChange?: (value: number) => void;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export interface IconProps {
+    className?: any;
+    id?: string;
+    name: string;
+    size?: number;
+    color?: string;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+/** One registered icon representation. `svg` contains path `d` data. */
+export interface IconGlyph {
+    svg?: string;
+    font?: {
+        family: string;
+        glyph: string;
+    };
+    src?: string;
+}
+export interface HeadingProps {
+    className?: any;
+    style?: any;
+    children?: any;
+    id?: string;
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
 }
 export interface PlatformBadgeProps {
     className?: any;
 }
+export interface OverlayProps {
+    open?: boolean;
+    onDismiss?: () => void;
+    /** Enables a RootLayout shade that dismisses when tapped. */
+    shadeCover?: boolean;
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
+export interface PopoverProps {
+    /** Native view or web element, commonly a ref object populated by `bind`. */
+    anchor?: any;
+    open?: boolean;
+    placement?: PopoverPlacement;
+    className?: any;
+    style?: any;
+    children?: any;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
+export type ToastContent = string | (() => any);
+export type ToastPosition = 'top' | 'bottom';
+export interface ToastOptions {
+    duration?: number;
+    position?: ToastPosition;
+    ios?: Record<string, any>;
+    android?: Record<string, any>;
+    web?: Record<string, any>;
+}
 export interface ModalProps {
     open?: boolean;
-    onClose?: () => void;
+    onClose?: (result?: ModalOpenResult) => void;
     fullscreen?: boolean;
+    /** Native: sheet uses fullscreen=false (iOS form sheet; Android centered
+     *  dialog), fullscreen uses fullscreen=true. Web: dialog is a centered
+     *  card, sheet is bottom-anchored, fullscreen is the default dialog size. */
+    presentation?: 'sheet' | 'fullscreen' | 'dialog';
+    /** Component reference rendered inside the modal's separate root. When
+     *  both component and children are set, component takes precedence. */
+    component?: any;
+    /** Props passed to component. Context and theme do not cross modal roots. */
+    params?: any;
     children?: any;
 }
+/** Options for `openModal`. `fullscreen` is retained for callers using the
+ *  NativeScript option directly; `presentation` takes precedence when set.
+ *  Android's non-fullscreen modal is a centered dialog, not a bottom sheet. */
+export interface ModalOpenOptions {
+    presentation?: 'sheet' | 'fullscreen' | 'dialog';
+    fullscreen?: boolean;
+    animated?: boolean;
+}
+/** Value supplied to a modal close callback and returned by `openModal`. */
+export type ModalOpenResult = unknown;
+/** Public function shape of the imperative modal service. */
+export type OpenModal = (component: any, params?: any, options?: ModalOpenOptions) => Promise<ModalOpenResult>;
 export interface TabSpec {
     title: string;
     render: () => any;
@@ -127,6 +420,30 @@ export interface Route {
     name: string;
     params: Record<string, unknown>;
 }
+/** name → screen component table for `registerScreens` — the app owns the
+ *  route table; native `pushRoute` resolves `route.name` through it and
+ *  web outlets fall back to it via `screenFor`. Values are component
+ *  functions (`() => Element` / UniversalComponent shapes both fit). */
+export type ScreenTable = Record<string, any>;
+/** One route file's entry in the derived manifest. `name` is the file
+ *  path under the route dir with `[param]` segments normalized to
+ *  `:param` (`app/demo/[id].tsrx` → `demo/:id`); `segments` is the URL
+ *  pattern used for web path matching/substitution. */
+export interface RouteMeta {
+    name: string;
+    segments: string[];
+    params: string[];
+    /** Source file (glob key) — diagnostics only. */
+    file: string;
+}
+/** Output of `deriveRouteManifest` — `screens` feeds `registerScreens`
+ *  (native pushRoute + web outlet fallback), `routes` feeds web URL
+ *  matching, `layouts` catalogs `_layout` files by directory ('' = root). */
+export interface RouteManifest {
+    screens: ScreenTable;
+    routes: RouteMeta[];
+    layouts: Record<string, any>;
+}
 export interface AnimatedValue {
     readonly value: number;
     bind(el: any): void;
@@ -140,3 +457,11 @@ export interface AnimatedValue {
     stop(): void;
 }
 export type ColorScheme = 'light' | 'dark';
+/** Minimal external-store contract `useStore` subscribes to. */
+export interface ReadableStore<T> {
+    get(): T;
+    subscribe(notify: () => void): () => void;
+}
+export interface Store<T> extends ReadableStore<T> {
+    set(next: T | ((prev: T) => T)): void;
+}