@contember/utilities 0.0.0

package/src/class-name/filterThemedClassName.ts

@@ -0,0 +1,86 @@
+import { KebabCase } from 'type-fest'
+import { isColorSchemeClassName } from './colorSchemeClassName'
+import { THEME_CLASS_NAME_REG_EXP } from './constants'
+import { flatClassNameList } from './flatClassNameList'
+import { contentThemeClassName, controlsThemeClassName } from './themeClassName'
+import { ColorSchemeClassName, NestedClassName } from './types'
+
+export type ThemeConfig = { content: string | undefined, controls: string | undefined }
+
+export function filterThemedClassName(
+	nestedClassName: NestedClassName,
+	defaultColorSchemeContext: ColorSchemeClassName,
+) {
+	const theme: ThemeConfig = { content: undefined, controls: undefined }
+	const stateThemes: Record<string, ThemeConfig> = {}
+	let colorScheme: ColorSchemeClassName | undefined = undefined
+
+	const flatClassName = flatClassNameList(nestedClassName).map(className => {
+		if (isColorSchemeClassName(className)) {
+			colorScheme = className
+			return undefined
+		}
+
+		const match = className.match(THEME_CLASS_NAME_REG_EXP)
+
+		if (match) {
+			const name = match.groups!.name as KebabCase<string>
+			const scope = match.groups!.scope as KebabCase<string>
+			const state = match.groups!.state as `:${KebabCase<string>}`
+
+			if (state) {
+				stateThemes[state] = stateThemes[state] ?? { content: undefined, controls: undefined }
+
+				if (!scope) {
+					stateThemes[state].content = name
+					stateThemes[state].controls = name
+				} else if (scope === 'content') {
+					stateThemes[state].content = name
+				} else if (scope === 'controls') {
+					stateThemes[state].controls = name
+				} else {
+					throw new Error(`Unknown theme scope: ${scope}`)
+				}
+			} else {
+				if (!scope) {
+					theme.content = name
+					theme.controls = name
+				} else if (scope === 'content') {
+					theme.content = name
+				} else if (scope === 'controls') {
+					theme.controls = name
+				} else {
+					throw new Error(`Unknown theme scope: ${scope}`)
+				}
+			}
+
+			return undefined
+		} else {
+			return className
+		}
+	}).filter(Boolean) as string[]
+
+	const themeClassNames: (string | undefined)[] = []
+
+	const content = contentThemeClassName(theme.content)
+	const controls = controlsThemeClassName(theme.controls)
+
+	themeClassNames.push(content, controls)
+
+	for (const state in stateThemes) {
+		const { content, controls } = stateThemes[state]
+
+		const contentClassName = contentThemeClassName(content, state as `:${KebabCase<string>}`)
+		const controlsClassName = controlsThemeClassName(controls, state as `:${KebabCase<string>}`)
+
+		themeClassNames.push(contentClassName, controlsClassName)
+	}
+
+	const flatThemedClassName = flatClassNameList(themeClassNames)
+
+	if (flatThemedClassName.length > 0 || colorScheme) {
+		return [colorScheme ?? defaultColorSchemeContext, ...flatThemedClassName, ...flatClassName]
+	} else {
+		return flatClassName
+	}
+}

package/src/class-name/flatClassNameList.ts

@@ -0,0 +1,18 @@
+import { assertNever } from '../assert-types'
+import { NestedClassName } from './types'
+
+export function flatClassNameList(className: NestedClassName): string[] {
+	if (!className) {
+		return []
+	} else if (typeof className === 'string') {
+		return className.split(' ').filter(Boolean)
+	} else if (Array.isArray(className)) {
+		return className.flatMap(flatClassNameList)
+	} else {
+		if (import.meta.env.DEV) {
+			console.error(`Unexpected className: ${JSON.stringify(className)}`)
+		}
+
+		assertNever(className)
+	}
+}

package/src/class-name/index.ts

@@ -0,0 +1,9 @@
+export * from './colorSchemeClassName'
+export * from './constants'
+export * from './deduplicateClassName'
+export * from './filterThemedClassName'
+export * from './flatClassNameList'
+export * from './listClassName'
+export * from './stateClassName'
+export * from './themeClassName'
+export * from './types'

package/src/class-name/listClassName.ts

@@ -0,0 +1,13 @@
+import { deduplicateClassName } from './deduplicateClassName'
+import { flatClassNameList } from './flatClassNameList'
+import { NestedClassName } from './types'
+
+/**
+ * Combines a list of class names into a single string, even nested
+ *
+ * @param list - List of class names
+ * @returns Combined class names as string
+ */
+export function listClassName(list: NestedClassName) {
+	return deduplicateClassName(flatClassNameList(list)).join(' ')
+}

package/src/class-name/stateClassName.ts

@@ -0,0 +1,32 @@
+import { toKebabCase } from '../string-utilities'
+import { ClassNameStateMap } from './types'
+
+export interface StateClassNameOptions {
+	glue?: string;
+	removeFalsy?: boolean;
+}
+
+/**
+ * Combines a state map of class names into a single string
+ *
+ * @example
+ * stateClassName({ foo: true, bar: false, baz: 1 }) // => 'foo baz-1'
+ *
+ * @param state - State map object with class names as keys and literals as values.
+ * @param options - Options object
+ * @param options.glue - Glue to use between the class name and the value, default is '-'. Set to '' to disable.
+ * @param options.removeFalsy - Whether to remove falsy class names, default is true.
+ * @returns Combined class names as string
+ */
+export function stateClassName(
+	state: ClassNameStateMap | null = null,
+	{ glue = '-', removeFalsy = true }: StateClassNameOptions = {},
+): string[] {
+	const entries = Object.entries(state ?? []).map(
+		([className, value]) => value || value === 0 || !removeFalsy
+			? (value === true ? toKebabCase(className) : `${toKebabCase(className)}${glue}${value}`)
+			: '',
+	).filter(Boolean)
+
+	return entries
+}

package/src/class-name/themeClassName.ts

@@ -0,0 +1,116 @@
+import { KebabCase } from 'type-fest'
+import { ThemeContentClassName, ThemeControlsClassName } from './types'
+
+/**
+ * Returns a string with a content theme class name, prefixed with `theme-` and suffixed with `-content`
+ *
+ * IMPORTANT: Make sure to use color scheme class in combination with theme class names.
+ *
+ * @param contentTheme - Theme name basis for content
+ * @param state - State of the theme starting with a ":", e.g. `":hover"`, `":focus"`, `":active"`, `":focus-visible"`
+ * @returns A content theme class name
+ *
+ * @see {@link controlsThemeClassName}
+ * @see {@link (colorSchemeClassName:3)}
+ *
+ * @example
+ * ```tsx
+ * const colorScheme = colorSchemeClassName('system')
+ * //  ^ 'scheme-system'
+ * const contentThemeClassName = contentThemeClassName('default')
+ * //  ^ 'theme-default-content:hover'
+ * const dangerOnMouseOverTheme = controlsThemeClassName('danger', ':hover')
+ * //  ^ 'theme-danger-controls:hover'
+ *
+ * return (
+ * 	<div className={`${colorScheme} ${contentThemeClassName}`}>
+ * 		<button className={`${colorScheme} ${dangerOnMouseOverTheme}`}>Delete</button>
+ * 	</div>
+ * )
+ * ```
+ */
+export function contentThemeClassName<
+	ContentTheme extends KebabCase<string> = KebabCase<string>,
+	State extends `:${KebabCase<string>}` | null | undefined = undefined,
+>(
+	theme: ContentTheme | null | undefined,
+	state?: State | null | undefined,
+) {
+	return theme ? `theme-${theme}-content${state ?? ''}` as ThemeContentClassName<ContentTheme, State> : undefined
+}
+
+/**
+ * Returns a string with a controls theme class name, prefixed with `theme-` and suffixed with `-controls`
+ *
+ * IMPORTANT: Make sure to use color scheme class in combination with theme class names.
+ *
+ * @param theme - Theme name basis for controls
+ * @param state - State of the theme starting with a ":", e.g. `":hover"`, `":focus"`, `":active"`, `":focus-visible"`
+ * @returns A controls theme class name
+ *
+ * @see {@link contentThemeClassName}
+ * @see {@link (colorSchemeClassName:3)}
+ *
+ * @example
+ * ```tsx
+ * const colorScheme = colorSchemeClassName('system')
+ * //  ^ 'scheme-system'
+ * const contentThemeClassName = contentThemeClassName('default')
+ * //  ^ 'theme-default-content:hover'
+ * const dangerOnMouseOverTheme = controlsThemeClassName('danger', ':hover')
+ * //  ^ 'theme-danger-controls:hover'
+ *
+ * return (
+ * 	<div className={`${colorScheme} ${contentThemeClassName}`}>
+ * 		<button className={`${colorScheme} ${dangerOnMouseOverTheme}`}>Delete</button>
+ * 	</div>
+ * )
+ * ```
+ */
+export function controlsThemeClassName<
+	ControlsTheme extends KebabCase<string> = KebabCase<string>,
+	State extends `:${KebabCase<string>}` | null | undefined = undefined,
+>(
+	theme: ControlsTheme | null | undefined,
+	state?: State | null | undefined,
+) {
+	return theme ? `theme-${theme}-controls${state ?? ''}` as ThemeControlsClassName<ControlsTheme, State> : undefined
+}
+
+/**
+ * Returns a tuple with a content theme class name and a controls theme class name, prefixed with `theme-` and suffixed with `-content` and `-controls` respectively
+ *
+ * IMPORTANT: Make sure to use color scheme class in combination with theme class names.
+ *
+ * @param theme - Theme name basis for content and controls
+ * @param state - State of the theme starting with a ":", e.g. `":hover"`, `":focus"`, `":active"`, `":focus-visible"`
+ * @returns A tuple with a content theme class name and a controls theme class name
+ *
+ * @see {@link contentThemeClassName}
+ * @see {@link controlsThemeClassName}
+ * @see {@link (colorSchemeClassName:3)}
+ *
+ * @example
+ * ```tsx
+ * const colorScheme = colorSchemeClassName('system')
+ * //  ^ 'scheme-system'
+ * const errorTheme = themeClassName('danger').join(' ')
+ * //  ^ 'theme-danger-content theme-danger-controls'
+ *
+ * return (
+ * 	<div className={`${colorScheme} ${errorTheme}`}>File not found</div>
+ * )
+ * ```
+ */
+export function themeClassName<
+	Theme extends KebabCase<string> = KebabCase<string>,
+	State extends `:${KebabCase<string>}` | null | undefined = undefined,
+>(
+		theme: Theme | null | undefined,
+		state?: State | null | undefined,
+) {
+	return [
+		contentThemeClassName(theme, state),
+		controlsThemeClassName(theme, state),
+	] as const
+}

package/src/class-name/types.ts

@@ -0,0 +1,17 @@
+import { KebabCase } from 'type-fest'
+
+export type NestedClassName = string | false | null | undefined | (string | false | null | undefined)[] | NestedClassName[]
+export type ClassNameStateMap = { [key: string]: string | number | boolean | null | undefined }
+
+export interface ComponentClassNameProps {
+	className?: NestedClassName;
+	componentClassName?: string | string[];
+}
+
+export type ColorSchemeClassName<T extends KebabCase<string> = KebabCase<string>> = `scheme-${T}`
+export type ThemeContentClassName<T extends KebabCase<string> = KebabCase<string>, S extends `:${KebabCase<string>}` | null | undefined = undefined> = S extends string
+	? `theme-${T}-content${S}`
+	: `theme-${T}-content`
+export type ThemeControlsClassName<T extends KebabCase<string> = KebabCase<string>, S extends `:${KebabCase<string>}` | null | undefined = undefined> = S extends string
+	? `theme-${T}-controls${S}`
+	: `theme-${T}-controls`

package/src/css-utilities/index.ts

@@ -0,0 +1 @@
+export * from './px'

package/src/css-utilities/px.ts

@@ -0,0 +1,16 @@
+export function px<V extends number>(value: V): `${V}px`;
+export function px<V extends false>(value: V): '';
+export function px<V extends null>(value: V): '';
+export function px<V extends undefined>(value: V): '';
+// NOTE: Next overload fixes:
+// The call would have succeeded against this implementation, but implementation signatures of overloads are not externally visible.
+export function px<V extends number | false | null | undefined>(value?: V): string;
+/**
+ * Converts a value to a string in the format '10px'
+ *
+ * @param value - The value to convert to a string.
+ * @returns Returns a string in the format '10px' or '' when value is falsy.
+ */
+export function px<V extends number | false | null | undefined>(value?: V): string {
+	return typeof value === 'number' && !(isNaN(value) || value === Infinity || value === -Infinity) ? value + 'px' : ''
+}

package/src/deprecate/deprecate.ts

@@ -0,0 +1,31 @@
+import { SemverString } from './types'
+
+/**
+ * Logs a deprecation warning if the assertion is `false`.
+ * @internal
+ *
+ * @param removal - Version when the deprecated feature will be removed
+ * @param condition - Condition under which the deprecation warning will be logged
+ * @param deprecated - Name of the deprecated feature
+ * @param replacement - Name of the feature that replaces the deprecated feature
+ *
+ * @example
+ * ```ts
+ * const { visible } = props
+ * deprecate(visible !== 'default', '1.3.0', '"default"', '"hidden"')
+ * // Logs: Use of "default" is deprecated and might be removed in the next release. Use "hidden" instead.
+ * ```
+ */
+export function deprecate(removal: SemverString, condition: boolean, deprecated: string, replacement: string | null): void {
+	if (condition === true) {
+		if (import.meta.env.DEV) {
+			const shouldThrow = Boolean(import.meta.env.VITE_CONTEMBER_ADMIN_STRICT_DEPRECATIONS)
+
+			if (shouldThrow) {
+				throw new Error(`Support for ${deprecated} was planned to be removed in the ${removal} release.${replacement ? ` Replace it with ${replacement} instead.` : 'Remove it.'}`)
+			} else {
+				console.warn(`Use of ${deprecated} is deprecated and might be removed in the next release.${replacement ? ` Use ${replacement} instead.` : 'There is no replacement.'}`)
+			}
+		}
+	}
+}

package/src/deprecate/fallback.ts

@@ -0,0 +1,7 @@
+export function fallback<R>(current: R, condition: boolean, mapped: R): R {
+	if (condition === true) {
+		return mapped
+	} else {
+		return current
+	}
+}

package/src/deprecate/index.ts

@@ -0,0 +1,3 @@
+export * from './deprecate'
+export * from './fallback'
+export * from './types'

package/src/deprecate/types.ts

@@ -0,0 +1,2 @@
+
+export type SemverString = `${number}.${number}.${number}`

package/src/dom/dataAttribute.ts

@@ -0,0 +1,11 @@
+export function dataAttribute(value: unknown): string | true | undefined {
+	if (value === false || value === undefined || value === null) {
+		return undefined
+	} else if (value === true) {
+		// Closest to HTML: https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#boolean-attributes
+		// React issue: https://github.com/facebook/react/issues/24812
+		return ''
+	} else {
+		return String(value)
+	}
+}

package/src/dom/getElementDimensions.ts

@@ -0,0 +1,36 @@
+/**
+ * Calls the callback with the element's dimensions.
+ *
+ * @param element - The element to observe for dimensions
+ * @param callback - The callback to call with the element's dimensions
+ */
+export function getElementDimensionsCallback(
+	element: HTMLElement,
+	callback: (dimensions: DOMRectReadOnly) => void,
+) {
+	const observer = new IntersectionObserver((entries, observer) => {
+		if (entries.length === 1) {
+			callback(entries[0].boundingClientRect)
+		} else {
+			const entry = entries.find(entry => entry.boundingClientRect.width > 0 || entry.boundingClientRect.height > 0) || entries[0]
+			callback(entry.boundingClientRect)
+		}
+
+		observer.disconnect()
+	})
+
+	observer.observe(element)
+}
+
+/**
+ * Returns a promise that resolves with the element's dimensions.
+ * @param element - The element to observe for dimensions
+ * @returns A promise that resolves with the element's dimensions
+ */
+export function getElementDimensions(
+	element: HTMLElement,
+): Promise<DOMRectReadOnly> {
+	return new Promise(resolve => {
+		getElementDimensionsCallback(element, resolve)
+	})
+}

package/src/dom/getMatchingParentElement.ts

@@ -0,0 +1,13 @@
+export function getMatchingParentElement(element: HTMLElement | null, predicate: (element: HTMLElement | null) => boolean | Promise<boolean>): HTMLElement {
+  if (!element || !element.parentElement) {
+    if (document.scrollingElement instanceof HTMLElement) {
+      return document.scrollingElement
+    } else {
+      return document.body
+    }
+  } else if (predicate(element.parentElement)) {
+    return element.parentElement
+  } else {
+    return getMatchingParentElement(element.parentElement, predicate)
+  }
+}

package/src/dom/getSizeFromResizeObserverEntry.ts

@@ -0,0 +1,26 @@
+export function getSizeFromResizeObserverEntryFactory(box: ResizeObserverOptions['box']) {
+	return function getSizeFromResizeObserverEntry(entry: ResizeObserverEntry): { height: number, width: number } {
+		const boxSize = box === 'border-box'
+			? entry.borderBoxSize
+			: box === 'content-box'
+				? entry.contentBoxSize
+				: entry.devicePixelContentBoxSize
+
+		if (boxSize) {
+			const formatBoxSize: ResizeObserverSize[] = Array.isArray(boxSize) ? boxSize : [boxSize]
+
+			return formatBoxSize.reduce(
+				(previous, { inlineSize, blockSize }) => ({
+					width: previous.width + inlineSize,
+					height: previous.height + blockSize,
+				}),
+				{ height: 0, width: 0 },
+			)
+		} else {
+			return {
+				width: entry.contentRect.width,
+				height: entry.contentRect.height,
+			}
+		}
+	}
+}

package/src/dom/index.ts

@@ -0,0 +1,8 @@
+export * from './dataAttribute'
+export * from './getElementDimensions'
+export * from './getMatchingParentElement'
+export * from './getSizeFromResizeObserverEntry'
+export * from './isScrollable'
+export * from './parseTransformMatrix'
+export * from './stateDataAttributes'
+export * from './svgSizeProps'

package/src/dom/isScrollable.ts

@@ -0,0 +1,24 @@
+/**
+ * Checks if an element is scrollable
+ * @param element - Element to check
+ * @returns Boolean indicating if the element is scrollable
+ */
+export function isScrollable(element: HTMLElement | null) {
+	if (element === document.scrollingElement) {
+		return true
+	} else if (element instanceof HTMLElement) {
+		const contentOverflows = element.scrollHeight > element.clientHeight || element.scrollWidth > element.clientWidth
+
+		if (contentOverflows) {
+			if ((getComputedStyle(element)).overflow === 'hidden') {
+				return false
+			} else {
+				return contentOverflows
+			}
+		} else {
+			return false
+		}
+	} else {
+		return false
+	}
+}

package/src/dom/parseTransformMatrix.ts

@@ -0,0 +1,35 @@
+import { assert, isNumber } from '../assert-types'
+
+const MATRIX_REG_EXP = /^matrix\((.+)\)/
+
+function isTransformMatrixTuple(value: unknown): value is [number, number, number, number, number, number] {
+	if (Array.isArray(value) && value.length === 6 && value.filter(isNumber).length === 6) {
+		return true
+	} else {
+		return false
+	}
+}
+
+/**
+ * Parses a CSS transform matrix string into an object.
+ *
+ * @param transform - CSS transform matrix string.
+ * @returns Object with the transform matrix values or undefined.
+ */
+export function parseTransformMatrix(transform = '') {
+	let matches: RegExpMatchArray | null = null
+
+	if (matches = transform.match(MATRIX_REG_EXP)) {
+		const vector = matches[1].split(',').map(value => parseFloat(value))
+		assert('transform matrix is tuple of six numbers', vector, isTransformMatrixTuple)
+
+		return {
+			scaleX: vector[0],
+			skewY: vector[1],
+			skewX: vector[2],
+			scaleY: vector[3],
+			translateX: vector[4],
+			translateY: vector[5],
+		}
+	}
+}

package/src/dom/stateDataAttributes.ts

@@ -0,0 +1,8 @@
+import { toKebabCase } from '../string-utilities'
+import { dataAttribute } from './dataAttribute'
+
+export function stateDataAttributes(state: Record<string, unknown>) {
+	return Object.fromEntries(Object.entries(state).map(
+		([key, value]) => [`data-${toKebabCase(key).toLowerCase()}`, dataAttribute(value)],
+	))
+}

package/src/dom/svgSizeProps.ts

@@ -0,0 +1,21 @@
+export interface SvgSizeProps {
+	width: number;
+	height: number;
+	viewBox: string;
+}
+
+export function svgSizeProps(
+	width: number,
+	height?: number,
+	crop: number = 0,
+): SvgSizeProps {
+	const viewBoxWidth = width - crop * 2
+	const viewBoxHeight = (height ?? width) - crop * 2
+	const viewBoxX = crop
+	const viewBoxY = crop
+	return {
+		width: viewBoxWidth,
+		height: viewBoxHeight,
+		viewBox: `${viewBoxX} ${viewBoxY} ${viewBoxWidth} ${viewBoxHeight}`,
+	}
+}

package/src/functional/extend.ts

@@ -0,0 +1,37 @@
+/** @internal */
+export function extend<B, E>(
+	base: B,
+	extension: E,
+) {
+	base = Object.freeze(base)
+	extension = Object.freeze(extension)
+
+	if (typeof base !== typeof extension) {
+		return extension === undefined ? base : extension
+	} else {
+		if (typeof base === 'object' && typeof extension === 'object') {
+			if (Array.isArray(base) && Array.isArray(extension)) {
+				return Object.freeze([...base, ...extension])
+			} else if (base && extension) {
+				if ('$$typeof' in extension) {
+					return extension
+				}
+
+				const keys = [...new Set([
+					...Object.keys(base),
+					...Object.keys(extension),
+				])]
+
+				const entries: [string, unknown][] = keys.map(
+					key => [key, extend((base as Record<string, unknown>)[key], (extension as Record<string, unknown>)[key])],
+				)
+
+				return Object.freeze(Object.fromEntries(entries))
+			} else {
+				return extension
+			}
+		} else {
+			return extension
+		}
+	}
+}

package/src/functional/index.ts

@@ -0,0 +1,5 @@
+export * from './extend'
+export * from './omit'
+export * from './pick'
+export * from './range'
+export * from './setHasOneOf'

package/src/functional/omit.ts

@@ -0,0 +1,13 @@
+export function omit<T extends Object, K extends keyof T>(object: T, properties: ReadonlyArray<K>, strict: boolean = false): Omit<T, K> {
+  const next: Partial<T> = { ...object }
+
+  for (let key of properties) {
+    if (key in object) {
+      delete next[key]
+    } else if (strict) {
+      throw new Error(`Key "${String(key)}" does not exist in object ${JSON.stringify(object)}`)
+    }
+  }
+
+  return next as Omit<T, K>
+}

package/src/functional/pick.ts

@@ -0,0 +1,13 @@
+export function pick<T extends Object, K extends keyof T>(object: T, properties: ReadonlyArray<K>): Pick<T, K> {
+	const next: Partial<Pick<T, K>> = {}
+
+	for (let key of properties) {
+		if (key in object) {
+			next[key] = object[key]
+		} else {
+			throw new Error(`Key "${String(key)}" does not exist in object ${JSON.stringify(object)}`)
+		}
+	}
+
+	return next as Pick<T, K>
+}

package/src/functional/range.ts

@@ -0,0 +1,11 @@
+
+/**
+ * Get a list of numbers between start and end, inclusive, with the given step size (defaulting to 1)
+ * @param start - The starting number.
+ * @param end - The ending number.
+ * @param step - The step size, optional, defaults to 1.
+ * @returns A list of numbers between start and end, inclusive, with the given step size (defaulting to 1)
+ */
+export function range(start: number, end: number, step = 1): number[] {
+	return Array.from({ length: Math.floor(Math.abs(end - start) / step) + 1 }, (_, i) => start + i * (end > start ? 1 : -1) * Math.abs(step))
+}

package/src/functional/setHasOneOf.ts

@@ -0,0 +1,3 @@
+export function setHasOneOf<T>(set: Set<T>, values: T[]): boolean {
+  return values.some(value => set.has(value))
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './assert-types'
+export * from './class-name'
+export * from './css-utilities'
+export * from './deprecate'
+export * from './dom'
+export * from './functional'
+export * from './string-utilities'
+export * from './types'