@yoot/yoot/dist/core/html.d.ts

The core library for yoot, providing a CDN-agnostic, chainable API for image URL transformations and adapter integration.

import type { BuildSrcSetOptions, ImgAttrs as _ImgAttrs, ImgAttrsOptions, SourceAttrs as _SourceAttrs, SourceAttrsOptions, WithSrcSetBuilder } from './helpers.ts';
import type { Yoot } from './yoot.ts';
export { buildSrcSet, defineSrcSetBuilder } from './helpers.ts';
export { getImgAttrs, getSourceAttrs, withImgAttrs, withSourceAttrs };
export type { BuildSrcSetOptions, ImgAttrs, ImgAttrsOptions, SourceAttrs, SourceAttrsOptions, WithSrcSetBuilder };
export { propsToHtmlAttrs, toInlineStyle };
/**
 * Returns `<img>` attributes generated from a `Yoot` object, merged with optional custom attributes.
 *
 * @public
 * @param yoot - A `Yoot` object.
 * @param options - Optional `<img>` attributes and `srcSetBuilder`.
 * @returns HTML attributes for an `<img>` element.
 *
 * @example
 * ```ts
 * import {yoot, getImgAttrs} from '@yoot/yoot';
 *
 * const thumbnail = yoot({
 *    src: 'https://cdn.example.com/image.jpg',
 *    alt: 'Thumbnail'
 * }).width(96).aspectRatio(1);
 *
 * const attrs = getImgAttrs(thumbnail);
 * // Output (urls differ between adapters):
 * // { src: 'https://cdn.example.com/image.jpg&w=96&h=96',
 * //   width: 96, height: 96}
 * ```
 *
 * @example
 * ```ts
 * import {yoot, getImgAttrs} from '@yoot/yoot';
 *
 * const thumbnail = yoot({
 *    src: 'https://cdn.example.com/image.jpg',
 *    alt: 'Thumbnail'
 * }).width(96).aspectRatio(1);
 *
 * const attrs = getImgAttrs(thumbnail, {loading: 'lazy', 'data-img': 'thumbnail'});
 * // Output (urls differ between adapters):
 * // { src: 'https://cdn.example.com/image.jpg&w=96&h=96',
 * //   width: 96, height: 96, loading: 'lazy', 'data-img': 'thumbnail'}
 * ```
 */
declare function getImgAttrs(yoot: Yoot, options?: ImgAttrsOptions): ImgAttrs;
/**
 * Returns a function that generates HTML attributes for an `<img>` tag.
 *
 * @remarks Merges provided attributes with derived ones. Supports fallback for `alt`.
 *
 * @public
 * @param options - `<img>` attributes and optional `srcSetBuilder`.
 * @returns A function that accepts a `Yoot` object and returns HTML `<img>` attributes.
 */
declare function withImgAttrs(options: ImgAttrsOptions): (yoot: Yoot, overrideOptions?: ImgAttrsOptions) => ImgAttrs;
/**
 * Returns `<source>` attributes generated from a `Yoot` object, merged with optional custom attributes.
 *
 * @public
 * @param yoot - A `Yoot` object.
 * @param options - Optional `<source>` attributes and `srcSetBuilder`.
 * @returns HTML attributes for a `<source>` element.
 */
declare function getSourceAttrs(yoot: Yoot, options?: SourceAttrsOptions): SourceAttrs;
/**
 * Returns a function that generates HTML attributes for a `<source>` tag.
 *
 * @remarks Merges provided attributes with derived ones.
 *
 * @public
 * @param options - `<source>` attributes and optional `srcSetBuilder`.
 * @returns A function that accepts a `Yoot` object and returns HTML `<source>` attributes.
 *
 * @example
 * ```tsx
 * // yoot-presets.ts
 * import {withSourceAttrs} from '@yoot/yoot';
 *
 * export const thumbnailPreset = yoot().width(96).aspectRatio(1);
 *
 * export const getThumbnailSourceAttrs = withSourceAttrs({
 *   srcSetBuilder: buildSrcSet({widths: [96, 192]}), // Or, buildSrcSet({densities: [1, 2, 3]})
 *   sizes: '96w',
 * });
 *
 * // somewhere else in your app
 * import {yoot, getImgAttrs} from '@yoot/yoot';
 * import {thumbnailPreset, getThumbnailSourceAttrs} from '@/yoot-presets';
 *
 * const thumbnail = thumbnailPreset({src: 'https://cdn.example.com/image.jpg', alt: 'Thumbnail'});
 *
 * <picture>
 *  <source {...getThumbnailSourceAttrs(thumbnail)} />
 *  <img {...getImgAttrs(thumbnail)} />
 * </picture>
 * ```
 */
declare function withSourceAttrs(options: SourceAttrsOptions): (yoot: Yoot, overrideOptions?: SourceAttrsOptions) => SourceAttrs;
/**
 * Converts an object's keys to kebab-case.
 *
 * @remarks Special handling:
 * - `aria*` keys: only the first capital letter is kebabed (e.g., `ariaAutoComplete` → `aria-autocomplete`)
 * - `style` key: value is converted to an inline style string
 * - Nullish values and empty styles are excluded.
 *
 * @internal
 */
declare function propsToHtmlAttrs<T extends Record<string, unknown>>(attributes: T): PropsToHtmlAttrs<T>;
/**
 * Converts a style object to a CSS inline-style string.
 *
 * @example toInlineStyle({ backgroundColor: 'red' }) // 'background-color:red;'
 * @internal
 */
declare function toInlineStyle(props: unknown): string;
type ImgAttrs = PropsToHtmlAttrs<_ImgAttrs>;
type SourceAttrs = PropsToHtmlAttrs<_SourceAttrs>;
/**
 * Converts the keys of type T to kebab-case.
 */
type PropsToHtmlAttrs<T> = {
    [K in keyof T as KebabCase<string & K>]: T[K];
} & {
    style?: string;
};
/**
 * Converts a string literal type to kebab-case.
 *
 * @example KebabCase<'fooBarBaz'> -> 'foo-bar-baz'
 */
type KebabCase<S extends string> = S extends `${infer First}${infer Rest}` ? First extends Lowercase<First> ? `${First}${KebabCase<Rest>}` : `-${Lowercase<First>}${KebabCase<Rest>}` : S;