@stanfordspezi/spezi-web-design-system/dist/src/utils/misc/misc.d.ts

Stanford Biodesign Digital Health Spezi Web Design System

import { UrlObject } from 'url';
/**
 * When `true`, the component will render its child as the root element
 * instead of creating a new DOM element. This allows passing the component's
 * props and styling to a custom child component using Radix UI's Slot pattern.
 *
 * Two major use cases:
 *  - to reuse styles of a component, but render it using different element
 *  - to inject event handlers without passing them manually
 *
 * @example
 * ```tsx
 * // Renders a link as a badge
 * <Badge asChild>
 *   <a href="https://example.com">Link Badge</a>
 * </Badge>
 * ```
 *
 * @default false
 */
export type AsChildProp = boolean;
/**
 * Negates value.
 * Useful for functional patterns and state callbacks.
 */
export declare const not: (value: unknown) => boolean;
/**
 * Type representing a value that can be either a direct value or a function that returns that value.
 * Useful for lazy initialization of state values.
 */
export type InitialState<T> = T | (() => T);
/**
 * Type representing a value that can be null or undefined.
 * Shorthand for `T | null | undefined`.
 */
export type Nil<T> = T | null | undefined;
/**
 * Type representing a URL that can be either a string or a URL object.
 */
export type Url = string | UrlObject;
/**
 * Make some fields in the object partial.
 *
 * @example
 * ```ts
 * PartialSome<{ a: string, b: string, c: string }, 'a'> => { a?: string, b: string, c: string }
 * ```
 */
export type PartialSome<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
/**
 * Make provided fields in the object required and the rest of fields partial.
 *
 * @example
 * ```ts
 * RequiredSome<{ a: string, b: string, c: string }, 'a'> => { a: string, b?: string, c?: string }
 * ```
 */
export type RequiredSome<T, K extends keyof T> = Partial<Omit<T, K>> & Required<Pick<T, K>>;
/**
 * Prettify makes complex object types easier to read by flattening intersections.
 * Use this when you export or inspect inferred types. This only affects type presentation in tooling.
 *
 * @example
 * ```ts
 * type A = { a: string };
 * type B = { b: number };
 * type Mixed = A & B;
 * type Readable = Prettify<Mixed>; // { a: string; b: number }
 * ```
 */
export type Prettify<T> = {
    [K in keyof T]: T[K];
} & {};
/**
 * Handles copying to clipboard and show confirmation toast.
 */
export declare const copyToClipboard: (value: string) => Promise<void>;
/**
 * Makes first letter uppercased.
 * @example
 * ```ts
 * upperFirst("lorem ipsum") => "Lorem ipsum"
 * ```
 */
export declare const upperFirst: (value: string) => string;
/**
 * Generates an array with a specified length.
 */
export declare const times: <T>(length: number, callback: (index: number) => T) => T[];
/**
 * Utility to dynamically resolve a strategy pattern.
 *
 * Provides correct types for enums, guaranteeing that `record` provides every enum key.
 *
 * @example
 * ```ts
 * enum Message {
 *   success
 *   error
 * }
 * strategy({
 *   [Message.success]: "Saving file worked!",
 *   [Message.error]: "Saving file failed. Please try again later!",
 * }, Message.error) // "Saving file failed. Please try again later!"
 * ```
 */
export declare const strategy: <T extends string | number | symbol, F>(record: Record<T, F>, enumValue: T) => Record<T, F>[T];
/**
 * Ensures a value is a string, returning undefined if it's not.
 *
 * @example
 * ```ts
 * ensureString("hello"); // "hello"
 * ensureString(123); // undefined
 * ```
 */
export declare const ensureString: (value: unknown) => string | undefined;
/**
 * Type guard to check if a value is an object (and not null).
 *
 * @example
 * ```ts
 * isObject({}); // true
 * isObject([]); // true
 * isObject(null); // false
 * isObject("string"); // false
 * ```
 */
export declare const isObject: (value: unknown) => value is object;
interface IsEmptyFunction {
    (value: string): value is "";
    (value: null | undefined): value is null | undefined;
    (value: unknown): boolean;
}
/**
 * Checks if a value is empty.
 * Handles strings, null/undefined, arrays, objects, and collections with size property.
 *
 * @example
 * ```ts
 * isEmpty(""); // true
 * isEmpty(null); // true
 * isEmpty([]); // true
 * isEmpty({}); // true
 * isEmpty(new Set()); // true
 * isEmpty("hello"); // false
 * isEmpty([1, 2, 3]); // false
 * ```
 */
export declare const isEmpty: IsEmptyFunction;
/**
 * Formats a boolean value into a string representation.
 * Returns "true" or "false" based on the boolean value.
 *
 * @example
 * ```ts
 * formatBoolean(true); // "true"
 * formatBoolean(false); // "false"
 * ```
 */
export declare const formatBoolean: (value: boolean) => "true" | "false";
/**
 * Formats a boolean like {@link formatBoolean}, but returns `null` for nil values.
 *
 * @example
 * ```ts
 * formatNilBoolean(true); // "true"
 * formatNilBoolean(false); // "false"
 * formatNilBoolean(null); // null
 * formatNilBoolean(undefined); // null
 * ```
 */
export declare const formatNilBoolean: (value: Nil<boolean>) => "true" | "false" | null;
/**
 * Joins path segments, handling leading/trailing slashes between segments.
 * It accepts strings and numbers; ignores null/undefined/empty segments.
 *
 * @example
 * ```ts
 * joinPaths("/api/v1/", "/users", "123"); // "/api/v1/users/123"
 * ```
 *
 * @example
 * ```ts
 * joinPaths("api", "users"); // "api/users"
 * ```
 *
 * @example
 * ```ts
 * joinPaths("https://example.com/", "/users/", "123"); // "https://example.com/users/123"
 * ```
 *
 * @example
 * ```ts
 * joinPaths("/a", "b?x=1#top"); // "/a/b?x=1#top"
 * ```
 */
export declare const joinPaths: (...segments: Array<Nil<string | number>>) => string;
export {};