UnflowUI
Utilities

Utilities

Shared TypeScript utility functions for string manipulation, ID generation, object/array operations, type guards, async helpers, and tenant theming.

The @unflowio/utils package provides small, well-typed utility functions used across the design system and consuming applications.

Installation

bun add @unflowio/utils

Import

import { capitalize, groupBy, isDefined } from '@unflowio/utils';

String utilities

capitalize(str)

Capitalises the first character of a string.

capitalize('hello world') // → 'Hello world'

toKebabCase(str)

Converts camelCase or PascalCase to kebab-case.

toKebabCase('MyComponent')  // → 'my-component'
toKebabCase('camelCase')    // → 'camel-case'

truncate(str, maxLength, suffix?)

Truncates a string to maxLength characters, appending a suffix (defaults to '…').

truncate('Hello, world!', 7)        // → 'Hello, …'
truncate('Hello, world!', 7, '...') // → 'Hello, ...'

ID utilities

generateId(prefix?)

Generates a lightweight unique ID string. Not cryptographically secure — intended for DOM IDs, list keys, and similar non-security use cases.

generateId()          // → 'k7d3m'
generateId('button')  // → 'button-k7d3m'

Object utilities

omit(obj, keys)

Returns a shallow copy of obj with the specified keys removed.

omit({ a: 1, b: 2, c: 3 }, ['b', 'c']) // → { a: 1 }

pick(obj, keys)

Returns a shallow copy of obj with only the specified keys.

pick({ a: 1, b: 2, c: 3 }, ['a', 'c']) // → { a: 1, c: 3 }

Array utilities

groupBy(arr, key)

Groups an array of items by a key function.

groupBy(
  [{ role: 'admin', name: 'Alice' }, { role: 'user', name: 'Bob' }, { role: 'admin', name: 'Carol' }],
  item => item.role
)
// → { admin: [{ role: 'admin', name: 'Alice' }, { role: 'admin', name: 'Carol' }], user: [{ role: 'user', name: 'Bob' }] }

uniqueBy(arr, key)

Removes duplicate items from an array, comparing by a key function.

uniqueBy([{ id: 1 }, { id: 2 }, { id: 1 }], item => item.id)
// → [{ id: 1 }, { id: 2 }]

Number utilities

clamp(value, min, max)

Constrains a number to be between min and max.

clamp(150, 0, 100) // → 100
clamp(-5, 0, 100)  // → 0
clamp(50, 0, 100)  // → 50

formatCurrency(amount, currency?, locale?)

Formats a number as a currency string using the Internationalization API.

formatCurrency(1234.56)              // → '$1,234.56'  (USD, en-US)
formatCurrency(1234.56, 'EUR', 'de') // → '1.234,56 €'

Type guards

isDefined(value)

Returns true if value is neither null nor undefined. Narrows the type to T.

const items = [1, null, 2, undefined, 3];
items.filter(isDefined) // → [1, 2, 3] — typed as number[]

isString(value)

Returns true if value is a string.

isString('hello') // → true
isString(42)      // → false

isObject(value)

Returns true if value is a non-null object (excludes arrays).

isObject({ a: 1 })  // → true
isObject([1, 2])    // → false
isObject(null)      // → false

Async utilities

sleep(ms)

Returns a Promise that resolves after ms milliseconds.

await sleep(500); // pause for 500ms

withRetry(fn, maxAttempts?, baseDelayMs?)

Retries an async function with exponential backoff on failure.

const data = await withRetry(
  () => fetch('/api/data').then(r => r.json()),
  3,    // max 3 attempts (default: 3)
  200   // starting delay 200ms, then 400ms, 800ms… (default: 100ms)
);

Theming utilities

Helpers that set the tenant accent @unflowio/tokens derives every accent shade from. See Semantic tokens for what the accent drives.

TenantTheme

type TenantTheme = {
  accent: string;                            // hex, '#c056ff' or '#c5f'
  accentForeground?: '#ffffff' | '#14141a';  // computed with accentForeground() when omitted
  fontFamily?: string;                       // overrides --uf-font-sans
  mode?: 'light' | 'dark';                   // applyTenantTheme only: sets data-theme
};

tenantThemeStyle(theme)

Returns the CSS custom properties for a theme (--uf-accent, --uf-accent-fg, --uf-font-sans), for server rendering on <html style> so there is no flash. An accent that is not a hex colour is left out, so the default accent applies.

<html style={tenantThemeStyle({ accent: '#0f7c96' })} />
// → style="--uf-accent: #0f7c96; --uf-accent-fg: #ffffff"

mode is not applied here; render data-theme on <html> yourself.

applyTenantTheme(theme, root?)

Applies a theme on the client, on <html> by default or on any element. It clears the previous theme variables first. On an element other than <html> it also sets data-uf-theme, so the accent shades are derived for that subtree, and with mode it sets data-theme.

applyTenantTheme({ accent: '#a6e22e', mode: 'dark' });
applyTenantTheme({ accent: '#c056ff' }, document.getElementById('preview')!);

accentPrimary(hex)

The 600 step primary buttons use: the accent with OKLCH lightness lowered by 0.09, mirroring the CSS derivation. Throws on a value that is not a hex colour.

accentPrimary('#c056ff') // → '#a334e0'

accentForeground(hex)

The text colour for the accent's primary step: white when white text reaches 4.5:1 on it, otherwise near-black.

accentForeground('#c056ff') // → '#ffffff'
accentForeground('#a6e22e') // → '#14141a'