@kingsimba/nc-ui 0.1.0

package/dist/main.d.ts

@@ -0,0 +1,988 @@
+import { ClassValue } from 'clsx';
+import { default as default_2 } from 'react';
+import { i18n } from 'i18next';
+import { JSX as JSX_2 } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * ActivityIndicator - A spinning loading indicator.
+ *
+ * Usage:
+ * 1. Inline spinner: <ActivityIndicator size="small" />
+ * 2. Overlay on parent (parent must have position: relative):
+ *    <div style={{ position: 'relative' }}>
+ *      <Button>Click me</Button>
+ *      {isLoading && <ActivityIndicator overlay />}
+ *    </div>
+ * 3. Cover entire dialog: Place overlay ActivityIndicator inside dialog container
+ */
+export declare function ActivityIndicator({ size, color, overlay, className, }: ActivityIndicatorProps): JSX_2.Element;
+
+declare interface ActivityIndicatorProps {
+    /** Size of the spinner */
+    size?: 'small' | 'default' | 'large';
+    /** Custom color (defaults to --primary) */
+    color?: string;
+    /** If true, renders in an overlay that covers the parent element and blocks clicks */
+    overlay?: boolean;
+    /** Additional class name */
+    className?: string;
+}
+
+export declare function Alert({ code, text, type, button, onAction }: AlertProps): JSX_2.Element;
+
+export declare interface AlertProps {
+    /** Error or warning code to display */
+    code: number;
+    /** Alert message text */
+    text: string;
+    /** Type of alert - determines styling */
+    type: AlertType;
+    /** Optional action button configuration */
+    button?: {
+        text: string;
+        variant?: ButtonVariant;
+    };
+    /** Callback when action button is clicked */
+    onAction?: () => void;
+}
+
+export declare type AlertType = 'warning' | 'error';
+
+/**
+ * Container component that wraps an app with its title bar.
+ * Provides AppContext to the app component, allowing any nested
+ * component to control the title bar dynamically via useApp() hook.
+ */
+export declare function AppContainer({ appId, isActive, onClose }: AppContainerProps): JSX_2.Element | null;
+
+declare interface AppContainerProps {
+    /** The app ID to render */
+    appId: string;
+    /** Whether this app is currently active (visible) */
+    isActive: boolean;
+    /** Called when the close button is clicked */
+    onClose: () => void;
+}
+
+export declare const AppContext: default_2.Context<AppContextValue | null>;
+
+/**
+ * Context value for app components.
+ * Provides functions to control the app container from any nested component.
+ */
+export declare interface AppContextValue {
+    /** Set the title bar text (should be already translated) */
+    setTitle: (title: string) => void;
+    /** Set a back button handler. When set, a back arrow appears in the title bar. */
+    setBackHandler: (handler: () => void) => void;
+    /** Clear the back button handler, hiding the back arrow. */
+    clearBackHandler: () => void;
+    /** Set toolbar content to render in the title bar (right-aligned, before close button) */
+    setToolbar: (toolbar: default_2.ReactNode) => void;
+    /** Clear the toolbar content */
+    clearToolbar: () => void;
+    /** Hide the back button temporarily (useful when in edit mode) */
+    setHideBackButton: (hide: boolean) => void;
+    /** Dynamically hide or show the title bar */
+    setHideTitleBar: (hide: boolean) => void;
+    /** Close the app */
+    close: () => void;
+}
+
+/**
+ * Definition of an application that can be launched in the right toolbar.
+ * App components can use the useApp() hook to access container controls.
+ */
+export declare interface AppDefinition {
+    /** Unique identifier for the app */
+    id: string;
+    /** i18n key for the display title (e.g., 'apps.calculator' or 'apps.maps.name') */
+    titleKey?: string;
+    /** Icon component displayed in the toolbar */
+    icon: default_2.ComponentType<{
+        size?: number;
+        className?: string;
+    }>;
+    /** The main component to render. Use useApp() hook inside to access container controls. */
+    component: default_2.ComponentType;
+    /** Panel width when the app is active (default: 400) */
+    width?: number;
+    /** Padding inside the app container (default: 0) */
+    padding?: number;
+    /** If true, hides the title bar and close button. The app cannot be closed once launched. */
+    hideTitleBar?: boolean;
+}
+
+/**
+ * Renders an app in a fullscreen portal overlay without using the Dialog component.
+ * Uses AppContainer directly to preserve all app functionality (title bar, AppContext, back handlers).
+ */
+export declare function AppDialog({ appId, open, onClose, closeOnBackdrop, className, maxWidth, maxHeight, }: AppDialogProps): default_2.ReactPortal | null;
+
+export declare interface AppDialogProps {
+    /** The app ID to render */
+    appId: string;
+    /** Whether the dialog is open */
+    open: boolean;
+    /** Called when the dialog should close */
+    onClose: () => void;
+    /** Whether clicking the backdrop closes the dialog (default: false) */
+    closeOnBackdrop?: boolean;
+    /** Optional CSS class name for the dialog container */
+    className?: string;
+    /** Maximum width in pixels (default: 1200) */
+    maxWidth?: number;
+    /** Maximum height in pixels (default: 900) */
+    maxHeight?: number;
+}
+
+/**
+ * Type for app-specific i18n resources.
+ * Supports arbitrary nesting of translation keys and objects.
+ * Each key is a language code (e.g., 'en', 'zh'), and the value is an object of translation key-value pairs.
+ */
+export declare type AppI18nResources = Record<string, Record<string, unknown>>;
+
+/**
+ * AppPanel component - Renders the right-side panel that displays running apps.
+ * Each running app is rendered via AppContainer, but only the active app is visible.
+ * On mobile devices, the panel overlays on top of the main area.
+ * On desktop, the panel sits inline next to the main area.
+ */
+export declare function AppPanel(): JSX_2.Element;
+
+/**
+ * Registry for all available applications.
+ * Apps must be registered before they can be launched.
+ */
+declare class AppRegistry {
+    private apps;
+    /**
+     * Register an app definition.
+     * Applies default values (e.g., width: 400) if not specified.
+     */
+    register(app: AppDefinition): void;
+    /**
+     * Unregister an app by its id.
+     */
+    unregister(id: string): void;
+    /**
+     * Get an app definition by id.
+     */
+    get(id: string): AppDefinition | undefined;
+    /**
+     * Get all registered apps.
+     */
+    list(): AppDefinition[];
+    /**
+     * Check if an app is registered.
+     */
+    has(id: string): boolean;
+}
+
+export declare const appRegistry: AppRegistry;
+
+declare interface AppState {
+    activeAppId: string | null;
+}
+
+declare class AppStateStore {
+    private state;
+    private listeners;
+    constructor();
+    private loadState;
+    private saveState;
+    /**
+     * Get the currently active app ID.
+     */
+    getActiveAppId(): string | null;
+    /**
+     * Set the active app ID (internal use by runningAppsStore).
+     */
+    _setActiveAppId(appId: string | null): void;
+    /**
+     * Subscribe to changes of a specific state key.
+     */
+    subscribe<K extends keyof AppState>(key: K, listener: Listener_2<AppState[K]>): () => void;
+    private notify;
+}
+
+export declare const appStateStore: AppStateStore;
+
+/**
+ * AppTaskbar component - A Windows 11-style taskbar for launching and switching apps.
+ * Displays pinned app icons that are always visible, plus any running non-pinned apps.
+ * Clicking an icon launches the app or toggles its active state if already running.
+ */
+export declare function AppTaskbar({ pinnedAppIds, className }: AppTaskbarProps): JSX_2.Element;
+
+export declare interface AppTaskbarProps {
+    /** Array of app IDs to pin to the taskbar (always visible) */
+    pinnedAppIds: string[];
+    /** Optional className for the taskbar container */
+    className?: string;
+}
+
+/**
+ * Title bar component for launched applications.
+ * Displays the app title, optional back button, optional toolbar, and a close button.
+ */
+export declare function AppTitleBar({ title, onClose, onBack, toolbar, hideBackButton }: AppTitleBarProps): JSX_2.Element;
+
+declare interface AppTitleBarProps {
+    title: string;
+    onClose: () => void;
+    /** If provided, shows a back arrow button on the left */
+    onBack?: () => void;
+    /** Optional toolbar content to render on the right side (before close button) */
+    toolbar?: default_2.ReactNode;
+    /** Whether to hide the back button even when onBack is provided (useful for edit mode) */
+    hideBackButton?: boolean;
+}
+
+/**
+ * Registry for back button handlers.
+ * Allows apps to register handlers that are called when the user presses back.
+ * Handlers are called in priority order (higher priority first).
+ */
+declare type BackHandler = () => boolean;
+
+declare class BackHandlerRegistry {
+    private handlers;
+    /**
+     * Register a back handler.
+     * @param id - Unique identifier for this handler
+     * @param priority - Higher priority handlers are called first
+     * @param handler - Function that returns true if it handled the back action
+     * @returns Unsubscribe function
+     */
+    register(id: string, priority: number, handler: BackHandler): () => void;
+    /**
+     * Trigger the back action.
+     * Calls handlers in priority order until one returns true.
+     * @returns true if a handler processed the back action
+     */
+    handleBack(): boolean;
+    /**
+     * Unregister a handler by id.
+     */
+    unregister(id: string): void;
+}
+
+export declare const backHandlerRegistry: BackHandlerRegistry;
+
+export declare function Battery({ percentage, status, darkMode, colored, }: BatteryProps): JSX_2.Element;
+
+export declare interface BatteryProps {
+    /** Battery level from 0.0 to 1.0 */
+    percentage?: number;
+    /** Current battery status */
+    status?: BatteryStatus;
+    /** Use light colors for dark backgrounds */
+    darkMode?: boolean;
+    /** Use threshold-based coloring (danger/warning/success) */
+    colored?: boolean;
+}
+
+export declare type BatteryStatus = 'charging' | 'discharging' | 'full';
+
+export declare function Button({ variant, block, size, className, disabled, textSelectable, loading, onClick, children, ...rest }: ButtonProps): JSX_2.Element;
+
+export declare function ButtonGroup<T extends string>({ value, onChange, options, disabled, labels, size, }: ButtonGroupProps<T>): JSX_2.Element;
+
+export declare interface ButtonGroupProps<T extends string> {
+    /** Currently selected value */
+    value: T | null;
+    /** Callback when selection changes */
+    onChange: (value: T) => void;
+    /** Available options */
+    options: readonly T[];
+    /** Disable all buttons */
+    disabled?: boolean;
+    /** Custom labels for options */
+    labels?: Partial<Record<T, string>>;
+    /** Size variant */
+    size?: ButtonGroupSize;
+}
+
+export declare type ButtonGroupSize = 'default' | 'small';
+
+declare type ButtonProps = default_2.ButtonHTMLAttributes<HTMLButtonElement> & {
+    variant?: ButtonVariant;
+    block?: boolean;
+    size?: 'default' | 'small' | 'large';
+    textSelectable?: boolean;
+    loading?: boolean;
+};
+
+declare type ButtonVariant = 'default' | 'primary' | 'danger' | 'warning' | 'success' | 'ghost';
+
+export declare function Checkbox({ checked, onChange, disabled, label, size, labelColor, style, className }: CheckboxProps): JSX_2.Element;
+
+export declare interface CheckboxProps {
+    /** Whether the checkbox is checked */
+    checked: boolean;
+    /** Callback when checkbox value changes */
+    onChange: (value: boolean) => void;
+    /** Whether the checkbox is disabled */
+    disabled?: boolean;
+    /** Label text to display next to checkbox */
+    label?: string;
+    /** Size variant */
+    size?: CheckboxSize;
+    /** Custom label color */
+    labelColor?: string;
+    /** Custom styles */
+    style?: default_2.CSSProperties;
+    /** Additional CSS class names */
+    className?: string;
+}
+
+export declare type CheckboxSize = 'default' | 'small';
+
+/**
+ * Clear the app from the URL when closing.
+ */
+export declare function clearAppInUrl(): void;
+
+/**
+ * A reusable close button.
+ */
+export declare function CloseButton({ onClick, disabled, size, title, 'aria-label': ariaLabel }: CloseButtonProps): JSX_2.Element;
+
+declare interface CloseButtonProps {
+    onClick: () => void;
+    disabled?: boolean;
+    size?: 'small' | 'default' | 'large';
+    title?: string;
+    'aria-label'?: string;
+}
+
+export declare function cn(...inputs: ClassValue[]): string;
+
+export declare function ComboBox({ value, onChange, placeholder, options, disabled, label, clearable, allowTyping, placement, size, style, className, }: ComboBoxProps): JSX_2.Element;
+
+export declare type ComboBoxOption = {
+    label: string;
+    value: string;
+    default?: boolean;
+};
+
+export declare interface ComboBoxProps {
+    /** Currently selected value */
+    value?: string;
+    /** Callback when selection changes */
+    onChange?: (value: string | undefined) => void;
+    /** Placeholder text when no value selected */
+    placeholder?: string;
+    /** Available options */
+    options: ComboBoxOption[];
+    /** Whether the combobox is disabled */
+    disabled?: boolean;
+    /** Label text */
+    label?: string;
+    /** Whether the selection can be cleared */
+    clearable?: boolean;
+    /** Whether typing to filter is allowed */
+    allowTyping?: boolean;
+    /** Dropdown placement preference */
+    placement?: 'top' | 'bottom';
+    /** Size variant */
+    size?: 'default' | 'small';
+    /** Custom styles */
+    style?: default_2.CSSProperties;
+    /** Additional CSS class names */
+    className?: string;
+}
+
+/**
+ * A context menu component that pops relative to an anchor element.
+ * Automatically detects available space and positions itself accordingly.
+ * Default position is right-down, but switches to right-up when space is limited.
+ */
+export declare function ContextMenu({ open, onClose, options, anchorRef, anchor, preferredDirection, }: ContextMenuProps): default_2.ReactPortal | null;
+
+export declare interface ContextMenuOption {
+    id: string;
+    label: string;
+    icon?: default_2.ReactNode;
+    onClick: () => void;
+    disabled?: boolean;
+    variant?: 'default' | 'danger';
+}
+
+export declare interface ContextMenuProps {
+    /** Whether the context menu is open */
+    open: boolean;
+    /** Called when the menu should close */
+    onClose: () => void;
+    /** Menu options to display */
+    options: ContextMenuOption[];
+    /** Reference element to anchor the menu position, or the element itself */
+    anchorRef?: default_2.RefObject<HTMLElement>;
+    /** Anchor element directly (alternative to anchorRef) */
+    anchor?: HTMLElement | null;
+    /** Preferred direction: 'down' or 'up' (default: 'down') */
+    preferredDirection?: 'down' | 'up';
+}
+
+/**
+ * Factory function to create an isolated i18next instance for an app.
+ * This allows apps to have their own translations independent of the global nc-ui i18n system.
+ *
+ * Features:
+ * - Creates isolated i18next instance using createInstance()
+ * - Syncs language with document.documentElement.lang
+ * - Falls back to English for unsupported languages
+ * - Supports string interpolation like {{variableName}}
+ *
+ * @param resources - Translation resources object with language keys (en, zh, de, th, es, etc.)
+ * @returns Initialized i18next instance ready for use with I18nextProvider
+ *
+ * @example
+ * ```typescript
+ * const resources = {
+ *   en: { hello: 'Hello', greeting: 'Hello {{name}}' },
+ *   zh: { hello: '你好', greeting: '你好 {{name}}' },
+ * };
+ * const appI18n = createAppI18nFactory(resources);
+ *
+ * // Use with react-i18next:
+ * <I18nextProvider i18n={appI18n}>
+ *   <YourApp />
+ * </I18nextProvider>
+ * ```
+ */
+export declare function createAppI18nFactory(resources: AppI18nResources): i18n;
+
+export declare function Dialog({ open, onClose, title, children, width, height, minWidth, minHeight, maxWidth, maxHeight, footerType, footer, onOk, onSave, onDelete, onCancel, onConnect, closeOnOverlay, primaryDisabled, fullScreen, hideTitleBar, }: DialogProps): JSX_2.Element | null;
+
+/**
+ * A button that automatically closes the parent Dialog when clicked.
+ * Accepts all Button props. Default children uses i18n 'common.close'.
+ */
+export declare function DialogClose({ children, onClick, ...props }: ButtonProps): JSX_2.Element;
+
+declare interface DialogContextValue {
+    /** Close the dialog */
+    close: () => void;
+}
+
+export declare type DialogFooterType = 'ok' | 'ok-cancel' | 'save-cancel' | 'delete-cancel' | 'connect' | 'close' | 'gotit' | 'custom' | 'none';
+
+export declare interface DialogProps {
+    /** Whether the dialog is open */
+    open: boolean;
+    /** Called when the dialog should close */
+    onClose: () => void;
+    /** Dialog title */
+    title: string;
+    /** Dialog content */
+    children: default_2.ReactNode;
+    /** Dialog width - number for pixels, string for CSS value (e.g., '50vw', '80%', 'auto') */
+    width?: number | string;
+    /** Dialog height - number for pixels, string for CSS value (e.g., '60vh', '70%', 'auto') */
+    height?: number | string;
+    /** Min width - number for pixels, string for CSS value */
+    minWidth?: number | string;
+    /** Min height - number for pixels, string for CSS value */
+    minHeight?: number | string;
+    /** Max width - number for pixels, string for CSS value (default: '95vw') */
+    maxWidth?: number | string;
+    /** Max height - number for pixels, string for CSS value (default: '95vh') */
+    maxHeight?: number | string;
+    /** Footer button preset type */
+    footerType?: DialogFooterType;
+    /** Custom footer content (used when footerType is 'custom') */
+    footer?: default_2.ReactNode;
+    /** Called when OK button is clicked */
+    onOk?: () => void;
+    /** Called when Save button is clicked */
+    onSave?: () => void;
+    /** Called when Delete button is clicked */
+    onDelete?: () => void;
+    /** Called when Cancel button is clicked */
+    onCancel?: () => void;
+    /** Called when Connect button is clicked */
+    onConnect?: () => void;
+    /** Whether clicking the overlay closes the dialog (default: true) */
+    closeOnOverlay?: boolean;
+    /** Whether the primary action button is disabled */
+    primaryDisabled?: boolean;
+    /**
+     * Whether to render the dialog in a portal covering the full viewport (default: false).
+     * Set to true to use fixed positioning via portal to document.body.
+     * Set to false to render inline with absolute positioning within parent container.
+     */
+    fullScreen?: boolean;
+    /** Whether to hide the title bar (default: false) */
+    hideTitleBar?: boolean;
+}
+
+/**
+ * A reusable edit button.
+ */
+export declare function EditButton({ onClick, disabled, size, title, 'aria-label': ariaLabel }: EditButtonProps): JSX_2.Element;
+
+declare interface EditButtonProps {
+    onClick: () => void;
+    disabled?: boolean;
+    size?: 'small' | 'default' | 'large';
+    title?: string;
+    'aria-label'?: string;
+}
+
+/**
+ * Get the current locale.
+ * Returns manual locale if set, otherwise detects from HTML lang.
+ */
+export declare function getLocale(): SupportedLocale;
+
+/**
+ * A reusable hyperlink component styled as text with primary color.
+ * Useful for text-based actions that look like links.
+ */
+export declare function Hyperlink({ onClick, disabled, children, title, 'aria-label': ariaLabel, size }: HyperlinkProps): JSX_2.Element;
+
+declare interface HyperlinkProps {
+    onClick?: () => void;
+    disabled?: boolean;
+    children: default_2.ReactNode;
+    title?: string;
+    'aria-label'?: string;
+    size?: 'small' | 'default';
+}
+
+export declare function Input({ value, onChange, onEnter, onClear, placeholder, disabled, label, clearable, type, className, size, style, showPasswordToggle, }: InputProps): JSX_2.Element;
+
+export declare interface InputProps {
+    /** Current value of the input */
+    value?: string;
+    /** Callback when value changes */
+    onChange?: (value: string) => void;
+    /** Callback when Enter key is pressed */
+    onEnter?: () => void;
+    /** Callback when input is cleared */
+    onClear?: () => void;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Label text displayed above the input */
+    label?: string;
+    /** Whether to show a clear button when there's a value */
+    clearable?: boolean;
+    /** Input type (text, password, email, etc.) */
+    type?: string;
+    /** Additional CSS class names */
+    className?: string;
+    /** Size variant */
+    size?: 'default' | 'small';
+    /** Additional inline styles */
+    style?: default_2.CSSProperties;
+    /** Whether to show a toggle button for password visibility (only works when type is 'password') */
+    showPasswordToggle?: boolean;
+}
+
+/**
+ * Options for launching an app.
+ */
+export declare interface LaunchAppOptions {
+    /** If true, the app will be launched but not made active. Default: false */
+    launchInBackground?: boolean;
+}
+
+declare type Listener = () => void;
+
+/**
+ * Simple store for persisting app state (like active app ID) across sessions.
+ * Uses localStorage for persistence.
+ */
+declare type Listener_2<T> = (value: T) => void;
+
+/**
+ * A container for grouping list items with a rounded border.
+ * Similar to iOS-style grouped lists or Windows 11 settings groups.
+ */
+export declare function ListGroup({ title, titleTools, children, style }: ListGroupProps): JSX_2.Element;
+
+/**
+ * A single item within a ListGroup.
+ * Can contain any content - fully flexible.
+ */
+export declare function ListGroupItem({ children, onClick, showBorder, selectable, style, }: ListGroupItemProps): JSX_2.Element;
+
+export declare interface ListGroupItemProps {
+    /** Content of the list item */
+    children: default_2.ReactNode;
+    /** Click handler for the item */
+    onClick?: (e: default_2.MouseEvent<HTMLDivElement>) => void;
+    /** Whether to show bottom border (default: true) */
+    showBorder?: boolean;
+    /** Whether text should be selectable (default: false) */
+    selectable?: boolean;
+    /** Optional CSS styles to apply to the item */
+    style?: default_2.CSSProperties;
+}
+
+export declare interface ListGroupProps {
+    /** Optional group title */
+    title?: string;
+    /** Optional tools rendered on the title row (e.g., buttons) */
+    titleTools?: default_2.ReactNode;
+    /** Group content (ListGroupItem components or any other content) */
+    children: default_2.ReactNode;
+    /** Optional CSS styles to apply to the container */
+    style?: default_2.CSSProperties;
+}
+
+export declare function MultiSelect({ values, onChange, options, placeholder, label }: MultiSelectProps): JSX_2.Element;
+
+export declare interface MultiSelectProps {
+    /** Array of currently selected values */
+    values: string[];
+    /** Callback when selection changes */
+    onChange: (values: string[]) => void;
+    /** Available options to select from */
+    options: Option_2[];
+    /** Placeholder text when no items are selected */
+    placeholder?: string;
+    /** Label text displayed above the select */
+    label?: string;
+}
+
+/**
+ * Renders the views in the navigation stack.
+ * All views in the stack remain mounted (hidden with CSS) to preserve state.
+ * Title bar is now handled by AppContainer, so showTitleBar is removed.
+ * Each view is wrapped with NavViewProvider for stack-based toolbar management.
+ */
+export declare function NavStackContainer(): JSX_2.Element;
+
+export declare interface NavStackContextValue {
+    /** Push a new view onto the stack */
+    push: (view: NavView) => void;
+    /** Go back one level (pop the current view) */
+    pop: () => void;
+    /** Reset to root view (clear entire stack) */
+    reset: () => void;
+    /** Current stack depth (1 = root only) */
+    depth: number;
+    /** Whether back navigation is possible */
+    canGoBack: boolean;
+    /** Current view's title */
+    currentTitle: string;
+}
+
+/**
+ * Provides navigation stack context to child components.
+ * Manages the view stack and exposes push/pop/reset operations.
+ * Syncs title and back button with AppContainer via useApp() hook.
+ * Also manages a parallel toolbar stack for stack-based toolbar management.
+ */
+export declare function NavStackProvider({ rootView, children }: NavStackProviderProps): JSX_2.Element;
+
+declare interface NavStackProviderProps {
+    /** The root view (always shown at the bottom of the stack) */
+    rootView: NavView;
+    /** Child components (typically NavStackContainer) */
+    children: default_2.ReactNode;
+}
+
+export declare interface NavView {
+    /** Unique identifier for the view */
+    id: string;
+    /** i18n key for the title (preferred - updates on language change) */
+    titleKey?: string;
+    /** Static title string (used when titleKey is not provided, e.g., for dynamic data like SSID) */
+    title?: string;
+    /** The view component to render */
+    component: default_2.ReactNode;
+}
+
+/**
+ * Per-view context for toolbar management.
+ * Each view gets its own setToolbar/clearToolbar that only affects its stack slot.
+ */
+export declare interface NavViewContextValue {
+    /** Set toolbar for THIS view only */
+    setToolbar: (toolbar: default_2.ReactNode) => void;
+    /** Clear toolbar for THIS view */
+    clearToolbar: () => void;
+}
+
+export declare function NumberInput({ value, onChange, min, max, step, label, disabled, size }: NumberInputProps): JSX_2.Element;
+
+export declare interface NumberInputProps {
+    /** Current numeric value */
+    value: number;
+    /** Callback when value changes */
+    onChange: (value: number) => void;
+    /** Minimum allowed value */
+    min?: number;
+    /** Maximum allowed value */
+    max?: number;
+    /** Step increment/decrement value */
+    step?: number;
+    /** Label text displayed above the input */
+    label?: string;
+    /** Whether the input is disabled */
+    disabled?: boolean;
+    /** Size variant */
+    size?: 'default' | 'small';
+}
+
+declare type Option_2 = {
+    label: string;
+    value: string;
+};
+
+/**
+ * A reusable refresh button with spinning animation.
+ * Shows a spinning refresh icon when loading.
+ */
+export declare function RefreshButton({ onClick, loading, disabled, size, title, 'aria-label': ariaLabel }: RefreshButtonProps): JSX_2.Element;
+
+declare interface RefreshButtonProps {
+    onClick: () => void;
+    loading?: boolean;
+    disabled?: boolean;
+    size?: 'small' | 'default' | 'large';
+    title?: string;
+    'aria-label'?: string;
+}
+
+/**
+ * Represents a running app instance.
+ * @template TRef - The type of the ref object exposed by the app
+ */
+export declare interface RunningApp<TRef = Record<string, unknown>> {
+    /** The app definition id */
+    appId: string;
+    /** Timestamp when the app was launched */
+    launchedAt: number;
+    /** Reference object populated by the app component with methods/state */
+    ref?: TRef;
+}
+
+/**
+ * Store for managing running applications.
+ * Only one instance of each app is allowed.
+ * Apps are not persisted across page refreshes.
+ */
+declare class RunningAppsStore {
+    private apps;
+    private activeAppId;
+    private listeners;
+    private refReadyResolvers;
+    /**
+     * Launch an app and wait for it to be ready (ref populated).
+     * If already running, activates it (unless launchInBackground is true) and returns the existing app.
+     * @template TRef - The type of the ref object exposed by the app (optional, for type safety)
+     * @param appId - The app id to launch
+     * @param options - Launch options
+     * @returns Promise that resolves with the RunningApp when ref is ready, or null if app not found
+     */
+    launchApp<TRef = Record<string, unknown>>(appId: string, options?: LaunchAppOptions): Promise<RunningApp<TRef> | null>;
+    private waitForRef;
+    /**
+     * Called by app components to register their ref.
+     * This resolves any pending launchApp promises.
+     */
+    setAppRef(appId: string, ref: Record<string, any>): void;
+    /**
+     * Get a running app by id.
+     */
+    getApp(appId: string): RunningApp | undefined;
+    /**
+     * Close a running app.
+     */
+    closeApp(appId: string): void;
+    /**
+     * Set the active app by its app id.
+     */
+    setActiveApp(appId: string | null): void;
+    /**
+     * Toggle an app: if active, deactivate; if inactive, activate.
+     */
+    toggleApp(appId: string): void;
+    /**
+     * Get the currently active app id.
+     */
+    getActiveAppId(): string | null;
+    /**
+     * Get the currently active app definition.
+     */
+    getActiveApp(): AppDefinition | null;
+    /**
+     * Get all running apps.
+     */
+    getRunningApps(): RunningApp[];
+    /**
+     * Check if an app is running.
+     */
+    isRunning(appId: string): boolean;
+    /**
+     * Subscribe to changes.
+     */
+    subscribe(listener: Listener): () => void;
+    private notify;
+}
+
+export declare const runningAppsStore: RunningAppsStore;
+
+/**
+ * Push a browser history entry for the app.
+ * This enables the browser back button to close/navigate apps.
+ */
+export declare function setAppInUrl(appId: string): void;
+
+/**
+ * Set the locale for nc-ui components manually.
+ * Pass `null` to use auto-detection from HTML lang attribute.
+ * @param locale - One of: 'en', 'zh', 'de', 'th', 'es', or null for auto
+ */
+export declare function setLocale(locale: SupportedLocale | null): void;
+
+export declare function Slider({ value, onChange, min, max, step, label, disabled, showValue, formatValue, width, }: SliderProps): JSX_2.Element;
+
+export declare interface SliderProps {
+    /** Current value */
+    value: number;
+    /** Callback when value changes */
+    onChange: (value: number) => void;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Step increment */
+    step?: number;
+    /** Label text displayed above the slider */
+    label?: string;
+    /** Whether the slider is disabled */
+    disabled?: boolean;
+    /** Whether to show the current value next to the slider */
+    showValue?: boolean;
+    /** Custom formatter for displaying the value */
+    formatValue?: (value: number) => string;
+    /** Width of the slider track */
+    width?: number | string;
+}
+
+/**
+ * Simple built-in localization for nc-ui components.
+ * Supports: en, zh, de, th, es
+ *
+ * By default, auto-detects locale from document.documentElement.lang.
+ * Can be manually overridden with setLocale().
+ */
+export declare type SupportedLocale = 'en' | 'zh' | 'de' | 'th' | 'es';
+
+/**
+ * Get a translated string by key.
+ * Falls back to English if key not found.
+ */
+export declare function t(key: string): string;
+
+export declare function Tabs({ tabs, active, onChange, className, toolbar, multiline, style }: TabsProps): JSX_2.Element;
+
+export declare interface TabsProps {
+    /** Array of tab labels */
+    tabs: string[];
+    /** Currently active tab label */
+    active: string;
+    /** Callback when a tab is selected */
+    onChange: (tab: string) => void;
+    /** Additional CSS class name for the container */
+    className?: string;
+    /** Optional toolbar content rendered at the end of the tab bar */
+    toolbar?: default_2.ReactNode;
+    /** Whether tabs should wrap to multiple lines */
+    multiline?: boolean;
+    /** Additional inline styles */
+    style?: default_2.CSSProperties;
+}
+
+export declare function Toggle({ checked, onChange, disabled, label }: ToggleProps): JSX_2.Element;
+
+export declare interface ToggleProps {
+    /** Whether the toggle is checked/on */
+    checked: boolean;
+    /** Callback when toggle state changes */
+    onChange: (value: boolean) => void;
+    /** Whether the toggle is disabled */
+    disabled?: boolean;
+    /** Label text displayed next to the toggle */
+    label?: string;
+}
+
+/**
+ * A reusable trash button.
+ */
+export declare function TrashButton({ onClick, disabled, size, title, 'aria-label': ariaLabel }: TrashButtonProps): JSX_2.Element;
+
+declare interface TrashButtonProps {
+    onClick: () => void;
+    disabled?: boolean;
+    size?: 'small' | 'default' | 'large';
+    title?: string;
+    'aria-label'?: string;
+}
+
+/**
+ * Hook to access app context from within an app.
+ * Returns functions to control the app container (setTitle, close, etc.)
+ * Can be called from any component nested inside an app.
+ * @throws Error if used outside of an app component
+ */
+export declare function useApp(): AppContextValue;
+
+/**
+ * Hook to access dialog context from within a Dialog.
+ * Returns the dialog context with close() and other functions.
+ * @throws Error if used outside of a Dialog component
+ */
+export declare function useDialog(): DialogContextValue;
+
+/**
+ * Hook to access navigation stack controls.
+ * Must be used within a NavStackProvider.
+ */
+export declare function useNavStack(): NavStackContextValue;
+
+/**
+ * Hook to access per-view toolbar controls.
+ * Must be used within a NavStack view.
+ */
+export declare function useNavView(): NavViewContextValue;
+
+/**
+ * Hook to access viewport information.
+ */
+export declare function useViewport(): ViewportContextValue;
+
+/**
+ * Viewport context value providing responsive breakpoint information.
+ */
+export declare interface ViewportContextValue {
+    /** True if viewport width < 768px */
+    isMobile: boolean;
+    /** True if viewport width >= 768px and < 1024px */
+    isTablet: boolean;
+    /** True if viewport width >= 1024px */
+    isDesktop: boolean;
+    /** Current viewport width in pixels */
+    width: number;
+    /** Current viewport height in pixels */
+    height: number;
+}
+
+/**
+ * Provider component that tracks viewport size and provides responsive breakpoints.
+ */
+export declare function ViewportProvider({ children }: {
+    children: ReactNode;
+}): JSX_2.Element;
+
+export { }