tinky-status-message 0.1.0

package/README.md

@@ -0,0 +1,118 @@
+# tinky-status-message
+
+A React status message component for CLI applications, built on the Tinky framework.
+
+## Features
+
+- Four status variants: info, success, warning, error
+- Icon-based visual indicators
+- Customizable colors and styles
+- Theme support via tinky-theme
+- Full TypeScript support
+
+## Installation
+
+```bash
+bun add tinky-status-message
+```
+
+## Usage
+
+```tsx
+import { StatusMessage } from "tinky-status-message";
+import { render } from "tinky";
+
+render(
+  <>
+    <StatusMessage variant="success">
+      Operation completed successfully
+    </StatusMessage>
+    <StatusMessage variant="error">An error occurred</StatusMessage>
+    <StatusMessage variant="warning">This is a warning</StatusMessage>
+    <StatusMessage variant="info">Additional information</StatusMessage>
+  </>,
+);
+```
+
+## API
+
+### StatusMessage
+
+The main status message component.
+
+#### Props
+
+| Prop       | Type                                          | Required | Description                                       |
+| ---------- | --------------------------------------------- | -------- | ------------------------------------------------- |
+| `children` | `ReactNode`                                   | Yes      | The message content to display                    |
+| `variant`  | `'info' \| 'success' \| 'error' \| 'warning'` | Yes      | The status variant that determines color and icon |
+
+#### Examples
+
+```tsx
+// Success message
+<StatusMessage variant="success">File saved successfully</StatusMessage>
+
+// Error message
+<StatusMessage variant="error">Failed to connect to server</StatusMessage>
+
+// Warning message
+<StatusMessage variant="warning">This action cannot be undone</StatusMessage>
+
+// Info message
+<StatusMessage variant="info">Your changes have been queued</StatusMessage>
+```
+
+## Theme Integration
+
+`StatusMessage` integrates with `tinky-theme` for styling:
+
+```tsx
+import { extendTheme } from "tinky-theme";
+
+const theme = extendTheme(defaultTheme, {
+  components: {
+    StatusMessage: {
+      config: (props) => ({
+        icon: customIconMap[props.variant],
+      }),
+      styles: {
+        container: () => ({
+          columnGap: 2, // Increase spacing
+        }),
+      },
+    },
+  },
+});
+```
+
+## Styling
+
+Each variant uses a predefined color:
+
+- `success` - Green (✓)
+- `error` - Red (✗)
+- `warning` - Yellow (⚠)
+- `info` - Blue (ℹ)
+
+You can customize these through the theme system.
+
+### Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Run linter
+bun run lint
+
+# Build the project
+bun run build
+```
+
+## License
+
+MIT

package/lib/components/StatusMessage.d.ts

@@ -0,0 +1,195 @@
+/**
+ * StatusMessage component implementation for terminal UI applications.
+ *
+ * This module provides the StatusMessage component, a message display component for
+ * showing notifications, warnings, errors, and information in terminal interfaces.
+ * The component supports four variants with semantic colors and icons.
+ *
+ * Key features:
+ * - Four semantic variants: info, success, error, warning
+ * - Automatic color mapping for each variant
+ * - Variant-specific icons with Unicode/fallback detection
+ * - Integration with tinky-theme for consistent styling
+ * - Flexible content support via ReactNode
+ *
+ * Variant characteristics:
+ * - info: Blue color with ℹ️ icon (fallback: ℹ) for general information
+ * - success: Green color with ✅ icon (fallback: √) for successful operations
+ * - error: Red color with ❌ icon (fallback: ×) for error notifications
+ * - warning: Yellow color with ⚠️ icon (fallback: ‼) for cautionary messages
+ *
+ * The component uses the tinky-theme system to resolve styling and
+ * configuration, allowing for easy customization through theme extension.
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * import { StatusMessage } from "tinky-status-message";
+ *
+ * <StatusMessage variant="info">
+ *   This is an informational message
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Success message:
+ * ```tsx
+ * import { StatusMessage } from "tinky-status-message";
+ *
+ * <StatusMessage variant="success">
+ *   Your operation completed successfully
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Error message:
+ * ```tsx
+ * import { StatusMessage } from "tinky-status-message";
+ *
+ * <StatusMessage variant="error">
+ *   Failed to connect to the server
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Warning message:
+ * ```tsx
+ * import { StatusMessage } from "tinky-status-message";
+ *
+ * <StatusMessage variant="warning">
+ *   Your session will expire in 5 minutes
+ * </StatusMessage>
+ * ```
+ *
+ * @see {@link StatusMessageProps}
+ * @see {@link statusMessageTheme}
+ */
+import { type JSX, type ReactNode } from "react";
+import { type StatusMessageVariant } from "../types/status-message-types.js";
+/**
+ * Props for the StatusMessage component.
+ *
+ * @interface StatusMessageProps
+ *
+ * @property {ReactNode} children - The message content to display within the status message.
+ *   This is the main body of the status message and can include text or any valid ReactNode.
+ *   The message is rendered in normal text style for readability.
+ *   Must be a valid ReactNode (components, elements, strings, numbers, etc.).
+ *
+ * @property {"info" | "success" | "error" | "warning"} variant - The status variant
+ *   determines the visual appearance including icon color and semantic meaning.
+ *
+ *   Variant options and their meanings:
+ *   - `info`: General information or neutral messages (blue color, ℹ️ icon / ℹ fallback)
+ *   - `success`: Successful operations or confirmations (green color, ✅ icon / √ fallback)
+ *   - `error`: Error messages or failure notifications (red color, ❌ icon / × fallback)
+ *   - `warning`: Warning messages or cautionary notes (yellow color, ⚠️ icon / ‼ fallback)
+ *
+ *   Each variant has associated:
+ *   - Icon color for visual emphasis
+ *   - Icon character displayed alongside the message
+ *   - Semantic meaning for accessibility and understanding
+ *
+ * @example
+ * Info status message:
+ * ```tsx
+ * const infoMessage: StatusMessageProps = {
+ *   variant: "info",
+ *   children: "Your request was received successfully"
+ * };
+ * ```
+ *
+ * @example
+ * Success status message:
+ * ```tsx
+ * const successMessage: StatusMessageProps = {
+ *   variant: "success",
+ *   children: "All systems operational"
+ * };
+ * ```
+ */
+export interface StatusMessageProps {
+    /**
+     * The message content to display within the status message.
+     * This is the main body of the status message and can include text or any valid ReactNode.
+     */
+    readonly children: ReactNode;
+    /**
+     * The status variant that determines the visual appearance including icon color,
+     * and semantic meaning.
+     */
+    readonly variant: StatusMessageVariant;
+}
+/**
+ * StatusMessage component for displaying messages in terminal UIs.
+ *
+ * @param {StatusMessageProps} props - Component props
+ * @param {ReactNode} props.children - Message content to display
+ * @param {"info" | "success" | "error" | "warning"} props.variant - Status variant for styling
+ *
+ * @returns {JSX.Element} The rendered status message component
+ *
+ * This is the main status message component that renders stylized message boxes with
+ * variant-specific colors and icons for terminal applications.
+ *
+ * Component structure:
+ * ```
+ * ┌─────────────────────┐
+ * │  [icon]  Message    │  <- icon container + message text
+ * └─────────────────────┘
+ * ```
+ *
+ * Rendering behavior:
+ * 1. Reads theme configuration for the StatusMessage component
+ * 2. Resolves variant-specific styles from theme
+ * 3. Detects Unicode support in the terminal environment
+ * 4. Displays icon on the left side (non-shrinking)
+ *   - Uses Unicode emoji if terminal supports it
+ *   - Falls back to ASCII character for unsupported terminals
+ * 5. Displays content on the right side
+ *
+ * Theme integration:
+ * - Uses `useComponentTheme` hook to resolve styles
+ * - Styles come from `statusMessageTheme.styles.*` functions
+ * - Styles are applied to Box and Text components from tinky
+ *
+ * Flex layout behavior:
+ * - Icon maintains fixed size (flexShrink: 0)
+ * - Message can expand/shrink as needed
+ *
+ * @example
+ * Simple info message:
+ * ```tsx
+ * <StatusMessage variant="info">
+ *   System maintenance scheduled for tonight
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Success message:
+ * ```tsx
+ * <StatusMessage variant="success">
+ *   Your changes have been saved
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Error message:
+ * ```tsx
+ * <StatusMessage variant="error">
+ *   Unable to reach the server. Please try again later.
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Warning message:
+ * ```tsx
+ * <StatusMessage variant="warning">
+ *   You are using 90% of your available storage
+ * </StatusMessage>
+ * ```
+ *
+ * @see {@link StatusMessageProps}
+ * @see {@link statusMessageTheme}
+ */
+export declare function StatusMessage({ children, variant, }: StatusMessageProps): JSX.Element;

package/lib/components/StatusMessage.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text, useApp } from "tinky";
+import { useComponentTheme } from "tinky-theme";
+import { isUnicodeSupported } from "../utils/unicode.js";
+import statusMessageTheme from "../themes/status-message-theme.js";
+/**
+ * StatusMessage component for displaying messages in terminal UIs.
+ *
+ * @param {StatusMessageProps} props - Component props
+ * @param {ReactNode} props.children - Message content to display
+ * @param {"info" | "success" | "error" | "warning"} props.variant - Status variant for styling
+ *
+ * @returns {JSX.Element} The rendered status message component
+ *
+ * This is the main status message component that renders stylized message boxes with
+ * variant-specific colors and icons for terminal applications.
+ *
+ * Component structure:
+ * ```
+ * ┌─────────────────────┐
+ * │  [icon]  Message    │  <- icon container + message text
+ * └─────────────────────┘
+ * ```
+ *
+ * Rendering behavior:
+ * 1. Reads theme configuration for the StatusMessage component
+ * 2. Resolves variant-specific styles from theme
+ * 3. Detects Unicode support in the terminal environment
+ * 4. Displays icon on the left side (non-shrinking)
+ *   - Uses Unicode emoji if terminal supports it
+ *   - Falls back to ASCII character for unsupported terminals
+ * 5. Displays content on the right side
+ *
+ * Theme integration:
+ * - Uses `useComponentTheme` hook to resolve styles
+ * - Styles come from `statusMessageTheme.styles.*` functions
+ * - Styles are applied to Box and Text components from tinky
+ *
+ * Flex layout behavior:
+ * - Icon maintains fixed size (flexShrink: 0)
+ * - Message can expand/shrink as needed
+ *
+ * @example
+ * Simple info message:
+ * ```tsx
+ * <StatusMessage variant="info">
+ *   System maintenance scheduled for tonight
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Success message:
+ * ```tsx
+ * <StatusMessage variant="success">
+ *   Your changes have been saved
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Error message:
+ * ```tsx
+ * <StatusMessage variant="error">
+ *   Unable to reach the server. Please try again later.
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * Warning message:
+ * ```tsx
+ * <StatusMessage variant="warning">
+ *   You are using 90% of your available storage
+ * </StatusMessage>
+ * ```
+ *
+ * @see {@link StatusMessageProps}
+ * @see {@link statusMessageTheme}
+ */
+export function StatusMessage({ children, variant, }) {
+    const { styles } = useComponentTheme("StatusMessage", statusMessageTheme, { variant });
+    const { env } = useApp();
+    const supportsUnicode = isUnicodeSupported(env ?? {});
+    const iconMap = {
+        info: { unicode: "ℹ️", fallback: "ℹ" },
+        success: { unicode: "✅", fallback: "√" },
+        error: { unicode: "❌", fallback: "×" },
+        warning: { unicode: "⚠️", fallback: "‼" },
+    };
+    const icon = supportsUnicode
+        ? iconMap[variant].unicode
+        : iconMap[variant].fallback;
+    return (_jsxs(Box, { ...styles.container, children: [_jsx(Box, { ...styles.iconContainer, children: _jsx(Text, { ...styles.icon, children: icon }) }), _jsx(Text, { ...styles.message, children: children })] }));
+}

package/lib/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Main entry point for tinky-status-message package.
+ *
+ * This module provides the public API for the tinky-status-message package,
+ * exporting the StatusMessage component and its associated theme configuration.
+ *
+ * The package exports:
+ * - `StatusMessage` - Main status message component for displaying messages in terminal UIs
+ * - `StatusMessageProps` - TypeScript interface for StatusMessage component props
+ * - `statusMessageTheme` - Default theme configuration for StatusMessage components
+ * - `StatusMessageTheme` - TypeScript type for the StatusMessage theme
+ * - `StatusMessageThemeProps` - TypeScript interface for StatusMessage theme functions
+ * - `isUnicodeSupported` - Utility function for detecting Unicode support in terminals
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * import { StatusMessage } from "tinky-status-message";
+ *
+ * <StatusMessage variant="success">
+ *   Operation completed successfully
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * With theme provider:
+ * ```tsx
+ * import { StatusMessage, statusMessageTheme } from "tinky-status-message";
+ * import { ThemeProvider } from "tinky-theme";
+ *
+ * <ThemeProvider theme={{ components: { StatusMessage: statusMessageTheme } }}>
+ *   <StatusMessage variant="info">
+ *     Important information message
+ *   </StatusMessage>
+ * </ThemeProvider>
+ * ```
+ *
+ * @see {@link StatusMessage}
+ * @see {@link statusMessageTheme}
+ */
+export { StatusMessage, type StatusMessageProps, } from "./components/StatusMessage.js";
+export { default as statusMessageTheme, type StatusMessageTheme, type StatusMessageThemeProps, } from "./themes/status-message-theme.js";
+export { type StatusMessageVariant } from "./types/status-message-types.js";
+export { isUnicodeSupported } from "./utils/unicode.js";

package/lib/index.js

@@ -0,0 +1,43 @@
+/**
+ * Main entry point for tinky-status-message package.
+ *
+ * This module provides the public API for the tinky-status-message package,
+ * exporting the StatusMessage component and its associated theme configuration.
+ *
+ * The package exports:
+ * - `StatusMessage` - Main status message component for displaying messages in terminal UIs
+ * - `StatusMessageProps` - TypeScript interface for StatusMessage component props
+ * - `statusMessageTheme` - Default theme configuration for StatusMessage components
+ * - `StatusMessageTheme` - TypeScript type for the StatusMessage theme
+ * - `StatusMessageThemeProps` - TypeScript interface for StatusMessage theme functions
+ * - `isUnicodeSupported` - Utility function for detecting Unicode support in terminals
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * import { StatusMessage } from "tinky-status-message";
+ *
+ * <StatusMessage variant="success">
+ *   Operation completed successfully
+ * </StatusMessage>
+ * ```
+ *
+ * @example
+ * With theme provider:
+ * ```tsx
+ * import { StatusMessage, statusMessageTheme } from "tinky-status-message";
+ * import { ThemeProvider } from "tinky-theme";
+ *
+ * <ThemeProvider theme={{ components: { StatusMessage: statusMessageTheme } }}>
+ *   <StatusMessage variant="info">
+ *     Important information message
+ *   </StatusMessage>
+ * </ThemeProvider>
+ * ```
+ *
+ * @see {@link StatusMessage}
+ * @see {@link statusMessageTheme}
+ */
+export { StatusMessage, } from "./components/StatusMessage.js";
+export { default as statusMessageTheme, } from "./themes/status-message-theme.js";
+export { isUnicodeSupported } from "./utils/unicode.js";

package/lib/themes/status-message-theme.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Theme configuration and styling for StatusMessage components.
+ *
+ * This module provides the default theme configuration for StatusMessage components,
+ * including variant-specific colors and styling functions.
+ *
+ * The theme system supports:
+ * - Four status message variants: info, success, error, warning
+ * - Automatic color mapping for each variant
+ * - Variant-specific styling
+ * - Consistent styling across all status message elements
+ * - Integration with the tinky-theme system
+ *
+ * Variant configurations:
+ * - info: Blue color with ℹ️ icon (fallback: ℹ)
+ * - success: Green color with ✅ icon (fallback: √)
+ * - error: Red color with ❌ icon (fallback: ×)
+ * - warning: Yellow color with ⚠️ icon (fallback: ‼)
+ *
+ * The module exports:
+ * 1. `statusMessageTheme` - Complete theme with styles
+ * 2. `StatusMessageTheme` - Type definition of the theme
+ * 3. `StatusMessageThemeProps` - Props interface for theme functions
+ *
+ * @example
+ * Using the default theme:
+ * ```tsx
+ * import { StatusMessage, statusMessageTheme } from "tinky-status-message";
+ * import { ThemeProvider } from "tinky-theme";
+ *
+ * <ThemeProvider theme={{ components: { StatusMessage: statusMessageTheme } }}>
+ *   <StatusMessage variant="info">
+ *     Information message
+ *   </StatusMessage>
+ * </ThemeProvider>
+ * ```
+ *
+ * @example
+ * Customizing via theme extension:
+ * ```tsx
+ * import { extendTheme } from "tinky-theme";
+ * import { statusMessageTheme } from "tinky-status-message";
+ *
+ * const customTheme = extendTheme(defaultTheme, {
+ *   components: {
+ *     StatusMessage: {
+ *       styles: {
+ *         container: () => ({
+ *           columnGap: 2
+ *         })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link StatusMessageTheme}
+ * @see {@link StatusMessage}
+ */
+import { type BoxProps, type TextProps } from "tinky";
+import { type StatusMessageVariant } from "../types/status-message-types.js";
+/**
+ * Props interface for StatusMessage theme functions.
+ *
+ * @interface StatusMessageThemeProps
+ *
+ * @property {StatusMessageVariant} variant - The status message variant
+ *   determines the color scheme. Each variant has specific semantic meaning:
+ *   - info: General information or neutral messages
+ *   - success: Successful operations or confirmations
+ *   - error: Error messages or failure notifications
+ *   - warning: Warning messages or cautionary notes
+ *
+ * Variant visual characteristics:
+ * - info: Blue color with ℹ️ icon (fallback: ℹ)
+ * - success: Green color with ✅ icon (fallback: √)
+ * - error: Red color with ❌ icon (fallback: ×)
+ * - warning: Yellow color with ⚠️ icon (fallback: ‼)
+ *
+ * @example
+ * ```typescript
+ * const infoProps: StatusMessageThemeProps = { variant: "info" };
+ * const successProps: StatusMessageThemeProps = { variant: "success" };
+ * const errorProps: StatusMessageThemeProps = { variant: "error" };
+ * const warningProps: StatusMessageThemeProps = { variant: "warning" };
+ * ```
+ */
+export interface StatusMessageThemeProps {
+    variant: StatusMessageVariant;
+}
+/**
+ * Default theme configuration for StatusMessage components.
+ *
+ * This theme provides all necessary style functions for rendering
+ * StatusMessage components in terminal UIs. It follows the tinky-theme
+ * ComponentTheme interface for seamless integration with the theme system.
+ *
+ * Theme structure:
+ * - `styles` - Style functions for each component element
+ *
+ * Style functions:
+ * Each style function returns props for the corresponding component:
+ * - `styles.container(props)` - BoxProps for the status message container
+ * - `styles.iconContainer()` - BoxProps for the icon wrapper
+ * - `styles.icon(props)` - TextProps for the icon character
+ * - `styles.message()` - TextProps for the message text
+ *
+ * @example
+ * Using the theme directly:
+ * ```tsx
+ * import { statusMessageTheme } from "tinky-status-message";
+ *
+ * const { styles } = statusMessageTheme;
+ * const containerProps = styles.container({ variant: "success" });
+ * // containerProps === { columnGap: 1 }
+ *
+ * <Box {...containerProps}>
+ *   Status message content
+ * </Box>
+ * ```
+ *
+ * @example
+ * Integrating with theme provider:
+ * ```tsx
+ * import { ThemeProvider } from "tinky-theme";
+ * import { statusMessageTheme } from "tinky-status-message";
+ *
+ * <ThemeProvider theme={{
+ *   components: {
+ *     StatusMessage: statusMessageTheme
+ *   }
+ * }}>
+ *   <StatusMessage variant="info">Info message</StatusMessage>
+ * </ThemeProvider>
+ * ```
+ *
+ * @see {@link StatusMessageTheme}
+ * @see {@link StatusMessageProps}
+ */
+declare const statusMessageTheme: {
+    styles: {
+        /**
+         * Style function for the status message container.
+         *
+         * @returns {BoxProps} Props for rendering the status message container
+         *
+         * The container provides the main visual structure of the status message with:
+         * - Horizontal layout (default flex direction)
+         * - Spacing between icon and message
+         * - Flexible sizing for responsive behavior
+         *
+         * Applied styles:
+         * - `columnGap: 1` - Horizontal spacing between icon and message
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const containerStyles = statusMessageTheme.styles.container();
+         * // Returns: { columnGap: 1 }
+         * ```
+         */
+        container: () => BoxProps;
+        /**
+         * Style function for the icon container.
+         *
+         * @returns {BoxProps} Props for rendering the icon container
+         *
+         * The icon container wraps the icon character and ensures it maintains
+         * its size regardless of content layout.
+         *
+         * Applied styles:
+         * - `flexShrink: 0` - Prevents icon from shrinking
+         *
+         * This ensures the icon always displays at its full size, even when
+         * the message area needs to shrink to fit constraints.
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const iconContainerStyles = statusMessageTheme.styles.iconContainer();
+         * // Returns: { flexShrink: 0 }
+         * ```
+         */
+        iconContainer: () => BoxProps;
+        /**
+         * Style function for the icon text element.
+         *
+         * @param {StatusMessageThemeProps} props - Props containing the variant
+         * @returns {TextProps} Props for rendering the icon character
+         *
+         * The icon is a variant-specific emoji character selected in the component
+         * based on Unicode support detection.
+         *
+         * Applied styles:
+         * - `color: variant-specific` - Color based on variant
+         *
+         * Icon mapping:
+         *      - info: Blue color
+         *      - success: Green color
+         *      - error: Red color
+         *      - warning: Yellow color
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const successIconStyles = statusMessageTheme.styles.icon({ variant: "success" });
+         * // Returns: { color: "green" }
+         * ```
+         */
+        icon: (props: StatusMessageThemeProps) => TextProps;
+        /**
+         * Style function for the message text element.
+         *
+         * @returns {TextProps} Props for rendering the message text
+         *
+         * The message is the main content of the status message, providing detailed
+         * information about the status message's purpose.
+         *
+         * Applied styles:
+         * - (none) - Default text styling
+         *
+         * The message uses normal text styling, allowing it to be more
+         * readable and less visually demanding than the colored icon.
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const messageStyles = statusMessageTheme.styles.message();
+         * // Returns: {}
+         * ```
+         */
+        message: () => TextProps;
+    };
+};
+export default statusMessageTheme;
+/**
+ * Type definition for the StatusMessage theme.
+ *
+ * @type {typeof statusMessageTheme}
+ *
+ * This type represents the complete theme structure for StatusMessage components,
+ * including all style functions.
+ *
+ * Type structure:
+ * ```typescript
+ * type StatusMessageTheme = {
+ *   styles: {
+ *     container: () => BoxProps;
+ *     iconContainer: () => BoxProps;
+ *     icon: (props: StatusMessageThemeProps) => TextProps;
+ *     message: () => TextProps;
+ *   };
+ * }
+ * ```
+ *
+ * @example
+ * Creating a custom theme that extends the base:
+ * ```typescript
+ * import type { StatusMessageTheme } from "tinky-status-message";
+ *
+ * const customTheme: StatusMessageTheme = {
+ *   ...statusMessageTheme,
+ *   styles: {
+ *     ...statusMessageTheme.styles,
+ *     container: () => ({
+ *       columnGap: 2  // Changed spacing
+ *     })
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link statusMessageTheme}
+ * @see {@link StatusMessageThemeProps}
+ * @see {@link ComponentTheme}
+ */
+export type StatusMessageTheme = typeof statusMessageTheme;

package/lib/themes/status-message-theme.js

@@ -0,0 +1,236 @@
+/**
+ * Theme configuration and styling for StatusMessage components.
+ *
+ * This module provides the default theme configuration for StatusMessage components,
+ * including variant-specific colors and styling functions.
+ *
+ * The theme system supports:
+ * - Four status message variants: info, success, error, warning
+ * - Automatic color mapping for each variant
+ * - Variant-specific styling
+ * - Consistent styling across all status message elements
+ * - Integration with the tinky-theme system
+ *
+ * Variant configurations:
+ * - info: Blue color with ℹ️ icon (fallback: ℹ)
+ * - success: Green color with ✅ icon (fallback: √)
+ * - error: Red color with ❌ icon (fallback: ×)
+ * - warning: Yellow color with ⚠️ icon (fallback: ‼)
+ *
+ * The module exports:
+ * 1. `statusMessageTheme` - Complete theme with styles
+ * 2. `StatusMessageTheme` - Type definition of the theme
+ * 3. `StatusMessageThemeProps` - Props interface for theme functions
+ *
+ * @example
+ * Using the default theme:
+ * ```tsx
+ * import { StatusMessage, statusMessageTheme } from "tinky-status-message";
+ * import { ThemeProvider } from "tinky-theme";
+ *
+ * <ThemeProvider theme={{ components: { StatusMessage: statusMessageTheme } }}>
+ *   <StatusMessage variant="info">
+ *     Information message
+ *   </StatusMessage>
+ * </ThemeProvider>
+ * ```
+ *
+ * @example
+ * Customizing via theme extension:
+ * ```tsx
+ * import { extendTheme } from "tinky-theme";
+ * import { statusMessageTheme } from "tinky-status-message";
+ *
+ * const customTheme = extendTheme(defaultTheme, {
+ *   components: {
+ *     StatusMessage: {
+ *       styles: {
+ *         container: () => ({
+ *           columnGap: 2
+ *         })
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @see {@link StatusMessageTheme}
+ * @see {@link StatusMessage}
+ */
+/**
+ * Color mapping for status message variants.
+ *
+ * Maps each variant to its corresponding terminal color:
+ * - info → blue
+ * - success → green
+ * - error → red
+ * - warning → yellow
+ *
+ * These colors are used for:
+ * - Icon color for visual emphasis
+ * - Any other variant-specific styling
+ *
+ * @constant {Record<StatusMessageVariant, string>}
+ * @private
+ */
+const colorByVariant = {
+    success: "green",
+    error: "red",
+    warning: "yellow",
+    info: "blue",
+};
+/**
+ * Default theme configuration for StatusMessage components.
+ *
+ * This theme provides all necessary style functions for rendering
+ * StatusMessage components in terminal UIs. It follows the tinky-theme
+ * ComponentTheme interface for seamless integration with the theme system.
+ *
+ * Theme structure:
+ * - `styles` - Style functions for each component element
+ *
+ * Style functions:
+ * Each style function returns props for the corresponding component:
+ * - `styles.container(props)` - BoxProps for the status message container
+ * - `styles.iconContainer()` - BoxProps for the icon wrapper
+ * - `styles.icon(props)` - TextProps for the icon character
+ * - `styles.message()` - TextProps for the message text
+ *
+ * @example
+ * Using the theme directly:
+ * ```tsx
+ * import { statusMessageTheme } from "tinky-status-message";
+ *
+ * const { styles } = statusMessageTheme;
+ * const containerProps = styles.container({ variant: "success" });
+ * // containerProps === { columnGap: 1 }
+ *
+ * <Box {...containerProps}>
+ *   Status message content
+ * </Box>
+ * ```
+ *
+ * @example
+ * Integrating with theme provider:
+ * ```tsx
+ * import { ThemeProvider } from "tinky-theme";
+ * import { statusMessageTheme } from "tinky-status-message";
+ *
+ * <ThemeProvider theme={{
+ *   components: {
+ *     StatusMessage: statusMessageTheme
+ *   }
+ * }}>
+ *   <StatusMessage variant="info">Info message</StatusMessage>
+ * </ThemeProvider>
+ * ```
+ *
+ * @see {@link StatusMessageTheme}
+ * @see {@link StatusMessageProps}
+ */
+const statusMessageTheme = {
+    styles: {
+        /**
+         * Style function for the status message container.
+         *
+         * @returns {BoxProps} Props for rendering the status message container
+         *
+         * The container provides the main visual structure of the status message with:
+         * - Horizontal layout (default flex direction)
+         * - Spacing between icon and message
+         * - Flexible sizing for responsive behavior
+         *
+         * Applied styles:
+         * - `columnGap: 1` - Horizontal spacing between icon and message
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const containerStyles = statusMessageTheme.styles.container();
+         * // Returns: { columnGap: 1 }
+         * ```
+         */
+        container: () => ({
+            columnGap: 1,
+        }),
+        /**
+         * Style function for the icon container.
+         *
+         * @returns {BoxProps} Props for rendering the icon container
+         *
+         * The icon container wraps the icon character and ensures it maintains
+         * its size regardless of content layout.
+         *
+         * Applied styles:
+         * - `flexShrink: 0` - Prevents icon from shrinking
+         *
+         * This ensures the icon always displays at its full size, even when
+         * the message area needs to shrink to fit constraints.
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const iconContainerStyles = statusMessageTheme.styles.iconContainer();
+         * // Returns: { flexShrink: 0 }
+         * ```
+         */
+        iconContainer: () => ({
+            flexShrink: 0,
+        }),
+        /**
+         * Style function for the icon text element.
+         *
+         * @param {StatusMessageThemeProps} props - Props containing the variant
+         * @returns {TextProps} Props for rendering the icon character
+         *
+         * The icon is a variant-specific emoji character selected in the component
+         * based on Unicode support detection.
+         *
+         * Applied styles:
+         * - `color: variant-specific` - Color based on variant
+         *
+         * Icon mapping:
+         *      - info: Blue color
+         *      - success: Green color
+         *      - error: Red color
+         *      - warning: Yellow color
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const successIconStyles = statusMessageTheme.styles.icon({ variant: "success" });
+         * // Returns: { color: "green" }
+         * ```
+         */
+        icon: (props) => ({
+            color: colorByVariant[props.variant],
+        }),
+        /**
+         * Style function for the message text element.
+         *
+         * @returns {TextProps} Props for rendering the message text
+         *
+         * The message is the main content of the status message, providing detailed
+         * information about the status message's purpose.
+         *
+         * Applied styles:
+         * - (none) - Default text styling
+         *
+         * The message uses normal text styling, allowing it to be more
+         * readable and less visually demanding than the colored icon.
+         *
+         * @example
+         * ```typescript
+         * import { statusMessageTheme } from "tinky-status-message";
+         *
+         * const messageStyles = statusMessageTheme.styles.message();
+         * // Returns: {}
+         * ```
+         */
+        message: () => ({}),
+    },
+};
+export default statusMessageTheme;

package/lib/types/status-message-types.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Status message variant types.
+ */
+export type StatusMessageVariant = "info" | "success" | "error" | "warning";

package/lib/types/status-message-types.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/unicode.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Utility functions for Unicode support detection.
+ *
+ * Provides functionality to detect Unicode support in terminal environments
+ * and provide appropriate fallback characters for unsupported environments.
+ */
+export declare function isUnicodeSupported(env?: Record<string, string | undefined>): boolean;

package/lib/utils/unicode.js

@@ -0,0 +1,20 @@
+/**
+ * Utility functions for Unicode support detection.
+ *
+ * Provides functionality to detect Unicode support in terminal environments
+ * and provide appropriate fallback characters for unsupported environments.
+ */
+export function isUnicodeSupported(env = {}) {
+    const lang = env.LANG || "";
+    const hasUtf8Locale = lang.toLowerCase().includes("utf-8");
+    const colorterm = env.COLORTERM || "";
+    const termProgram = env.TERM_PROGRAM || "";
+    const hasModernTerminal = colorterm.includes("truecolor") ||
+        colorterm.includes("24bit") ||
+        termProgram.includes("vscode") ||
+        termProgram.includes("iTerm.app") ||
+        termProgram.includes("Terminal.app");
+    const platform = env.platform || "";
+    const isWindows = platform === "win32";
+    return hasUtf8Locale || hasModernTerminal || !isWindows;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "tinky-status-message",
+  "version": "0.1.0",
+  "description": "React status message component for terminal UIs",
+  "keywords": [
+    "react",
+    "cli",
+    "terminal",
+    "tinky",
+    "status",
+    "message",
+    "notification",
+    "variant"
+  ],
+  "homepage": "https://github.com/ByteLandTechnology/tinky-status-message#readme",
+  "bugs": {
+    "url": "https://github.com/ByteLandTechnology/tinky-status-message/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ByteLandTechnology/tinky-status-message.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "ByteLandTechnology"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc && npm run docs",
+    "lint": "eslint src tests",
+    "prepublish": "npm run build",
+    "prepare": "husky",
+    "docs": "typedoc && prettier --write docs/api"
+  },
+  "files": [
+    "./lib/*"
+  ],
+  "typings": "./lib/index.d.ts",
+  "dependencies": {
+    "tinky-theme": "^1.0.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/bun": "^1.3.8",
+    "bun": "^1.3.8",
+    "conventional-changelog-conventionalcommits": "^9.1.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "semantic-release": "^25.0.2",
+    "tinky-test": "^1.0.0",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript-eslint": "^8.54.0"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write"
+  }
+}