@nick-skriabin/glyph 0.1.49 → 0.1.51

package/README.md

@@ -40,7 +40,7 @@ Build real terminal applications with React. Glyph provides a full component mod
 | | |
 |---|---|
 | **Flexbox Layout** | Full CSS-like flexbox via Yoga — rows, columns, wrapping, alignment, gaps, padding |
-| **Rich Components** | Box, Text, Input, Button, Checkbox, Radio, Select, ScrollView, List, Menu, Progress, Spinner, Toasts, Dialogs, Portal, JumpNav |
+| **Rich Components** | Box, Text, Input, Button, Checkbox, Radio, Select, ScrollView, List, Menu, Progress, Spinner, Image, Toasts, Dialogs, Portal, JumpNav |
 | **Focus System** | Tab navigation, focus scopes, focus trapping for modals, JumpNav quick-jump hints |
 | **Keyboard Input** | `useInput` hook, declarative `<Keybind>` component, vim-style bindings |
 | **Smart Rendering** | Double-buffered framebuffer with character-level diffing &mdash; only changed cells are written |
@@ -455,6 +455,65 @@ Animated spinner with configurable frames. Cleans up timers on unmount.
 <Spinner frames={["|", "/", "-", "\\"]} intervalMs={100} />
 ```
 
+### `<Image>`
+
+Display images in the terminal with inline rendering or OS preview. Supports local files and remote URLs.
+
+```tsx
+<Image
+  src="./photo.jpg"
+  style={{ width: 40, height: 15 }}
+  autoLoad
+/>
+
+<Image
+  src="https://images.unsplash.com/photo-123"
+  style={{ flexGrow: 1 }}
+/>
+```
+
+**How it works:**
+1. By default, shows a placeholder with the image name
+2. Focus the component and press `Space` to load
+3. Image renders inline (Kitty/iTerm2 protocol) or opens OS preview (Quick Look on macOS)
+4. Press `Escape` to return to placeholder, `R` to reload
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Local path or remote URL |
+| `width` | `number` | auto | Fixed width in cells |
+| `height` | `number` | auto | Fixed height in cells |
+| `style` | `Style` | `{}` | Container style (flexbox) |
+| `focusedStyle` | `Style` | `{}` | Style when focused |
+| `inline` | `boolean` | `true` | Allow inline terminal rendering |
+| `autoLoad` | `boolean` | `false` | Load automatically on mount |
+| `focusable` | `boolean` | `true` | Whether the component is focusable |
+| `placeholder` | `string` | filename | Custom placeholder text |
+| `onStateChange` | `(state) => void` | - | Called when state changes |
+| `onError` | `(error) => void` | - | Called on error |
+
+**Terminal support:**
+- **Inline rendering:** Kitty, Ghostty, WezTerm, iTerm2 (via Kitty Graphics or iTerm2 protocol)
+- **OS preview fallback:** Quick Look (macOS), xdg-open (Linux), start (Windows)
+
+**Remote images** are automatically downloaded and cached. Supported formats: PNG, JPEG, GIF, WebP.
+
+```tsx
+// Inline disabled - always use OS preview
+<Image src="./large-photo.jpg" inline={false} />
+
+// With state callback
+<Image
+  src={imageUrl}
+  onStateChange={(state) => {
+    // "placeholder" | "loading" | "loaded" | "error" | "preview"
+    console.log("Image state:", state);
+  }}
+/>
+```
+
 ### `<ToastHost>` + `useToast()`
 
 Lightweight toast notifications rendered via Portal. Wrap your app in `<ToastHost>`, then push toasts from anywhere with `useToast()`.
@@ -763,6 +822,7 @@ Interactive examples are included in the repo. Each demonstrates different compo
 | **dialog-demo** | Alert and Confirm dialogs | [View →](https://github.com/nick-skriabin/glyph/tree/main/examples/dialog-demo) |
 | **jump-nav** | Quick navigation with keyboard hints | [View →](https://github.com/nick-skriabin/glyph/tree/main/examples/jump-nav) |
 | **ansi-text** | ANSI escape codes and colored output | [View →](https://github.com/nick-skriabin/glyph/tree/main/examples/ansi-text) |
+| **image** | Inline images and OS preview | [View →](https://github.com/nick-skriabin/glyph/tree/main/examples/image) |
 | **showcase** | Progress bars, Spinners, Toasts | [View →](https://github.com/nick-skriabin/glyph/tree/main/examples/showcase) |
 | **dashboard** | Full task manager (all components) | [View →](https://github.com/nick-skriabin/glyph/tree/main/examples/dashboard) |
 

package/dist/index.d.ts

@@ -509,6 +509,42 @@ interface JumpNavProps {
  */
 declare function JumpNav({ children, activationKey, hintStyle, hintBg, hintFg, hintChars, enabled, debug, }: JumpNavProps): React.JSX.Element;
 
+/**
+ * Image component for terminal UIs
+ *
+ * Supports inline rendering via terminal protocols (Kitty, iTerm2)
+ * and OS-level preview (Quick Look on macOS, xdg-open on Linux)
+ */
+
+type ImageState = "placeholder" | "loading" | "loaded" | "error" | "preview";
+interface ImageProps {
+    /** Image source - local path or remote URL */
+    src: string;
+    /** Fixed width in cells (optional, uses flexbox if not set) */
+    width?: number;
+    /** Fixed height in cells (optional, uses flexbox if not set) */
+    height?: number;
+    /** Container style (flexbox) */
+    style?: Style;
+    /** Style when focused */
+    focusedStyle?: Style;
+    /** Style for the placeholder */
+    placeholderStyle?: Style;
+    /** Whether the component is focusable (default: true) */
+    focusable?: boolean;
+    /** Allow inline rendering in terminal (default: true) */
+    inline?: boolean;
+    /** Custom placeholder text (default: image name) */
+    placeholder?: string;
+    /** Called when image state changes */
+    onStateChange?: (state: ImageState) => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Auto-load on mount (default: false - user presses space) */
+    autoLoad?: boolean;
+}
+declare function Image({ src, width, height, style, focusedStyle, placeholderStyle, focusable, inline, placeholder, onStateChange, onError, autoLoad, }: ImageProps): React.JSX.Element;
+
 declare function useInput(handler: (key: Key) => void, deps?: any[]): void;
 
 interface UseFocusResult {
@@ -725,4 +761,22 @@ declare function parseAnsi(input: string): StyledSegment[];
  */
 declare function stripAnsi(input: string): string;
 
-export { type AlertOptions, type AnsiStyle, type AppHandle, type BorderStyle, Box, type BoxProps, Button, type ButtonProps, Checkbox, type CheckboxProps, type Color, type ConfirmOptions, type DialogContextValue, DialogHost, type DialogHostProps, type DimensionValue, type FocusRegistryValue, FocusScope, type FocusScopeProps, type FocusableElement, type HexColor, Input, type InputProps, type InputType, JumpNav, type JumpNavProps, type Key, Keybind, type KeybindProps, type LayoutRect, List, type ListItemInfo, type ListProps, type MaskOptions, Menu, type MenuItem, type MenuProps, type NamedColor, Portal, type PortalProps, Progress, type ProgressProps, type RGBColor, Radio, type RadioItem, type RadioProps, type RenderOptions, ScrollView, type ScrollViewProps, Select, type SelectItem, type SelectProps, Spacer, type SpacerProps, Spinner, type SpinnerProps, type Style, type StyledSegment, Text, type TextAlign, type TextProps, type Toast, ToastHost, type ToastHostProps, type ToastPosition, type ToastVariant, type UseFocusableOptions, type UseFocusableResult, type WrapMode, createMask, masks, parseAnsi, render, stripAnsi, useApp, useDialog, useFocus, useFocusRegistry, useFocusable, useInput, useLayout, useToast };
+/**
+ * Terminal capability detection for image protocols
+ */
+interface TerminalCapabilities {
+    name: string;
+    supportsKittyGraphics: boolean;
+    supportsIterm2Images: boolean;
+    supportsSixel: boolean;
+}
+/**
+ * Detect which terminal we're running in and what image protocols it supports
+ */
+declare function detectTerminalCapabilities(debug?: boolean): TerminalCapabilities;
+/**
+ * Check if the terminal supports any inline image protocol
+ */
+declare function supportsInlineImages(): boolean;
+
+export { type AlertOptions, type AnsiStyle, type AppHandle, type BorderStyle, Box, type BoxProps, Button, type ButtonProps, Checkbox, type CheckboxProps, type Color, type ConfirmOptions, type DialogContextValue, DialogHost, type DialogHostProps, type DimensionValue, type FocusRegistryValue, FocusScope, type FocusScopeProps, type FocusableElement, type HexColor, Image, type ImageProps, type ImageState, Input, type InputProps, type InputType, JumpNav, type JumpNavProps, type Key, Keybind, type KeybindProps, type LayoutRect, List, type ListItemInfo, type ListProps, type MaskOptions, Menu, type MenuItem, type MenuProps, type NamedColor, Portal, type PortalProps, Progress, type ProgressProps, type RGBColor, Radio, type RadioItem, type RadioProps, type RenderOptions, ScrollView, type ScrollViewProps, Select, type SelectItem, type SelectProps, Spacer, type SpacerProps, Spinner, type SpinnerProps, type Style, type StyledSegment, type TerminalCapabilities, Text, type TextAlign, type TextProps, type Toast, ToastHost, type ToastHostProps, type ToastPosition, type ToastVariant, type UseFocusableOptions, type UseFocusableResult, type WrapMode, createMask, detectTerminalCapabilities, masks, parseAnsi, render, stripAnsi, supportsInlineImages, useApp, useDialog, useFocus, useFocusRegistry, useFocusable, useInput, useLayout, useToast };