@tachui/primitives
Version:
Basic UI components for tachUI framework
192 lines • 6.5 kB
TypeScript
/**
* Enhanced Image Component (Phase 5.4)
*
* SwiftUI-inspired Image component with loading states, error handling,
* responsive sizing, and advanced image handling capabilities.
*/
import type { ModifiableComponent, ModifierBuilder } from '@tachui/core';
import type { Signal } from '@tachui/core';
import type { ComponentInstance, ComponentProps } from '@tachui/core';
import { ImageAsset } from '@tachui/core';
import type { Concatenatable, ComponentSegment } from '@tachui/core';
import { ConcatenatedComponent } from '@tachui/core';
import { type ElementOverrideProps } from '@tachui/core';
import { ComponentWithCSSClasses, type CSSClassesProps } from '@tachui/core';
/**
* Image loading state
*/
export type ImageLoadingState = 'idle' | 'loading' | 'loaded' | 'error';
/**
* Image content mode (how image fits within bounds)
*/
export type ImageContentMode = 'fit' | 'fill' | 'stretch' | 'center' | 'scaleDown';
/**
* Image resize mode for different screen densities
*/
export type ImageResizeMode = 'cover' | 'contain' | 'fill' | 'none';
/**
* Image loading strategy
*/
export type ImageLoadingStrategy = 'eager' | 'lazy';
/**
* Image component properties with element override support and CSS classes
*/
export interface ImageProps extends ComponentProps, ElementOverrideProps, CSSClassesProps {
src?: string | Signal<string> | ImageAsset;
srcSet?: string | Signal<string>;
alt?: string | Signal<string>;
width?: number | string | Signal<number | string>;
height?: number | string | Signal<number | string>;
aspectRatio?: number | Signal<number>;
contentMode?: ImageContentMode;
resizeMode?: ImageResizeMode;
loadingStrategy?: ImageLoadingStrategy;
placeholder?: string | ComponentInstance;
errorPlaceholder?: string | ComponentInstance;
loadingState?: Signal<ImageLoadingState>;
onLoadingStateChange?: (state: ImageLoadingState) => void;
onLoad?: (event: Event) => void;
onError?: (event: Event) => void;
onLoadStart?: () => void;
crossOrigin?: 'anonymous' | 'use-credentials';
decoding?: 'sync' | 'async' | 'auto';
fetchPriority?: 'high' | 'low' | 'auto';
accessibilityLabel?: string;
accessibilityRole?: string;
blur?: number | Signal<number>;
opacity?: number | Signal<number>;
grayscale?: boolean | Signal<boolean>;
sepia?: boolean | Signal<boolean>;
lowQualitySrc?: string;
highQualitySrc?: string;
}
/**
* Enhanced Image component class with element override support and CSS classes
*/
export declare class EnhancedImage extends ComponentWithCSSClasses implements ComponentInstance<ImageProps>, Concatenatable<ImageProps> {
props: ImageProps;
readonly type: "component";
readonly id: string;
mounted: boolean;
cleanup: (() => void)[];
private effectiveTag;
private validationResult;
private loadingStateSignal;
private setLoadingState;
/**
* Set loading state and notify callback
*/
private setLoadingStateWithCallback;
constructor(props: ImageProps);
/**
* Render the image component with reactive content handling
*/
render(): import("@tachui/core").DOMNode | import("@tachui/core").DOMNode[];
/**
* Set up ImageAsset reactivity for a real DOM element (called from onDOMReady)
*/
private setupImageAssetReactivityForDOMElement;
/**
* Concatenate this image with another concatenatable component
*/
concat<U extends Concatenatable<any>>(other: U): ConcatenatedComponent<ImageProps | U>;
/**
* Convert this image to a segment for concatenation
*/
toSegment(): ComponentSegment;
/**
* Check if this component supports concatenation
*/
isConcatenatable(): boolean;
/**
* Determine accessibility role for concatenation
*/
private determineAccessibilityRole;
/**
* Merge accessibility roles when combining components
*/
private mergeAccessibilityRoles;
}
/**
* Create enhanced Image component with modifier support and SwiftUI-style shorthands
*
* @example
* ```typescript
* // Using aspectRatio modifier
* Image('photo.jpg')
* .aspectRatio(16/9, 'fit')
*
* // Using SwiftUI-style shorthands
* Image('photo.jpg')
* .scaledToFit() // Same as aspectRatio(undefined, 'fit')
*
* Image('photo.jpg')
* .scaledToFill() // Same as aspectRatio(undefined, 'fill')
* ```
*/
/**
* Extended Image component interface with SwiftUI-style shorthands
*/
export interface ImageWithShorthands extends ModifiableComponent<ImageProps> {
modifier: ModifierBuilder<ModifiableComponent<ImageProps>>;
scaledToFit(): ImageWithShorthands;
scaledToFill(): ImageWithShorthands;
}
export declare function Image(src: string | Signal<string> | ImageAsset, props?: Omit<ImageProps, 'src'>): ImageWithShorthands;
/**
* Image loading states for external use
*/
export declare const ImageStates: {
idle: "idle";
loading: "loading";
loaded: "loaded";
error: "error";
};
/**
* Image content modes for external use
*/
export declare const ImageContentModes: {
fit: "fit";
fill: "fill";
stretch: "stretch";
center: "center";
scaleDown: "scaleDown";
};
/**
* Image utility functions
*
* These utilities work seamlessly with the new scaledTo* shorthands:
*
* @example
* ```typescript
* // Combine utilities with shorthands
* ImageUtils.responsive([...])
* .scaledToFit()
* .frame(200, 200)
* ```
*/
export declare const ImageUtils: {
/**
* Create a responsive image with multiple sources
*/
responsive(sources: {
src: string;
width?: number;
media?: string;
}[], fallbackSrc: string, props?: Omit<ImageProps, "src" | "srcSet">): ModifiableComponent<ImageProps> & {
modifier: ModifierBuilder<ModifiableComponent<ImageProps>>;
};
/**
* Create an image with progressive loading
*/
progressive(lowQualitySrc: string, highQualitySrc: string, props?: Omit<ImageProps, "src" | "lowQualitySrc" | "highQualitySrc">): ModifiableComponent<ImageProps> & {
modifier: ModifierBuilder<ModifiableComponent<ImageProps>>;
};
/**
* Create an image with loading placeholder
*/
withPlaceholder(src: string | Signal<string>, placeholderSrc: string, props?: Omit<ImageProps, "src" | "placeholder">): ModifiableComponent<ImageProps> & {
modifier: ModifierBuilder<ModifiableComponent<ImageProps>>;
};
};
//# sourceMappingURL=Image.d.ts.map