@toa.io/extensions.configuration 1.0.0-alpha.272 → 1.0.0-alpha.274

package/ui/src/lib/tools/convert.ts

@@ -0,0 +1,32 @@
+export function base64urlToUint8Array(base64Url: string): Uint8Array {
+  const padding = '='.repeat((4 - (base64Url.length % 4)) % 4)
+  const base64 = (base64Url + padding).replace(/-/g, '+').replace(/_/g, '/')
+  const rawData = atob(base64)
+
+  return new Uint8Array([...rawData].map((char) => char.charCodeAt(0)))
+}
+
+export function stringToUint8Array(str: string): Uint8Array {
+  return new TextEncoder().encode(str)
+}
+
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  return btoa(String.fromCharCode(...new Uint8Array(buffer)))
+}
+
+export function bufferToBase64url(buffer: ArrayBuffer): string {
+  return arrayBufferToBase64(buffer)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '')
+}
+
+export function toBase64Url(string: string): string {
+  return btoa(string).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+export function fromBase64Url(base64Url: string): string {
+  const base64 = base64Url.replace(/-/g, '+').replace(/_/g, '/')
+
+  return atob(base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '='))
+}

package/ui/src/lib/tools/currency.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest'
+import { unit } from './currency'
+
+describe('unit', () => {
+  it('converts major units to cents as integer', () => {
+    expect(unit(18.6, 'en-US')).toBe(1860)
+    expect(unit(0.1, 'en-US')).toBe(10)
+    expect(unit(0.01, 'en-US')).toBe(1)
+  })
+})

package/ui/src/lib/tools/currency.ts

@@ -0,0 +1,55 @@
+import type { Locale } from './types'
+
+/**
+ * Formats a balance value expressed in the currency's ISO 4217 smallest unit
+ * (e.g., cents for USD, yen for JPY) into a properly formatted currency string.
+ *
+ * @param amount - The balance value in the currency's smallest unit (integer)
+ * @param locale - Locale for formatting
+ * @param currency - Optional ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY').
+ * @returns Formatted currency string (e.g., "$1.00", "€1.00", "¥100")
+ */
+export function currency(amount: number, locale: Locale, currency?: string): string {
+  if (currency === undefined) {
+    const value = amount / 100
+    const precision = value > 500 ? 0 : 2
+
+    return Number.isInteger(value) ? value.toString() : value.toFixed(precision)
+  }
+
+  const formatter = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  })
+
+  const options = formatter.resolvedOptions()
+  const decimalPlaces = options.minimumFractionDigits ?? 2
+  const divisor = Math.pow(10, decimalPlaces)
+  const majorUnit = amount / divisor
+
+  return formatter.format(majorUnit)
+}
+
+/**
+ * Converts a currency value expressed in the currency's ISO 4217 smallest unit
+ * (e.g., cents for USD, yen for JPY) into a number.
+ *
+ * @param amount - The currency value in the currency's smallest unit (integer)
+ * @param locale - Locale for formatting
+ * @param currency - Optional ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY'). Defaults to 'USD'
+ * @returns Number value (e.g., 100 for $1.00, 10000 for ¥100)
+ */
+export function unit(amount: number, locale: Locale, currency?: string): number {
+  if (currency === undefined) return Math.round(amount * 100)
+
+  const tempFormatter = new Intl.NumberFormat(locale, {
+    style: 'currency',
+    currency,
+  })
+
+  const options = tempFormatter.resolvedOptions()
+  const decimalPlaces = options.minimumFractionDigits ?? 2
+  const divisor = Math.pow(10, decimalPlaces)
+
+  return Math.round(amount * divisor)
+}

package/ui/src/lib/tools/date.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { date, formatISODuration } from './date'
+
+describe('date', () => {
+  afterEach(() => { vi.useRealTimers() })
+
+  it('carries the year only outside the current one', () => {
+    vi.useFakeTimers().setSystemTime(new Date('2026-08-05'))
+
+    expect(date('2026-02-17', 'en-US')).toBe('Feb 17')
+    expect(date('2024-02-17', 'en-US')).toBe('Feb 17, 2024')
+  })
+})
+
+describe('formatISODuration', () => {
+  it('formats ISO duration', () => {
+    expect(formatISODuration('P1Y', 'en-US')).toBe('1 year')
+    expect(formatISODuration('P1W', 'en-US')).toBe('1 week')
+    expect(formatISODuration('P1M', 'ru-RU')).toBe('1 месяц')
+  })
+})

package/ui/src/lib/tools/date.ts

@@ -0,0 +1,35 @@
+import type { Locale } from './types'
+
+/**
+ * Formats a date into a short localized representation, carrying the year only when the date
+ * falls outside the current one (e.g., "Feb 17" this year, "Feb 17, 2024" earlier).
+ *
+ * @param value - ISO date string or Date
+ * @param locale - Locale for formatting
+ * @returns Formatted date string
+ */
+export function date(value: string | Date | number, locale: Locale): string {
+  const d = new Date(value)
+  const year = d.getFullYear() === new Date().getFullYear() ? undefined : 'numeric'
+
+  return new Intl.DateTimeFormat(locale, { year, month: 'short', day: 'numeric' }).format(d)
+}
+
+/**
+ * Formats an ISO duration string into a localized representation (e.g., "1 year", "1 month").
+ *
+ * @param iso - ISO duration string
+ * @param locale - Locale for formatting
+ * @returns Formatted duration string
+ */
+export function formatISODuration(iso: string, locale: Locale): string {
+  const match = iso.match(/^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/)
+
+  if (match === null) return iso
+
+  const [, y, mo, w, d, h, mi, s] = match.map((v) => Number.isNaN(Number(v)) ? undefined : Number(v))
+
+  // @ts-ignore Intl.DurationFormat — Stage 3 proposal, available at runtime in modern engines
+  return new Intl.DurationFormat(locale, { style: 'long' })
+    .format({ years: y, months: mo, weeks: w, days: d, hours: h, minutes: mi, seconds: s })
+}

package/ui/src/lib/tools/delay.ts

@@ -0,0 +1,7 @@
+export function delay<T>(fn: () => Promise<T> | T, duration: number): Promise<T> {
+  return new Promise((resolve) =>
+    setTimeout(async () => {
+      resolve(await fn())
+    }, duration),
+  )
+}

package/ui/src/lib/tools/image.ts

@@ -0,0 +1,39 @@
+export type DensityMap = Record<`${number}x`, string>
+
+/**
+ * Preload the best-matching image for current pixel density.
+ *
+ * Picks the smallest density `>=` `devicePixelRatio`, or the highest available.
+ *
+ * @param assets - {@link DensityMap}
+ *
+ * @example
+ * ```ts
+ * preload({ '1x': '/img/bg.webp', '2x': '/img/bg@2x.webp' })
+ * ```
+ */
+export function preload(assets: DensityMap) {
+  const densities = Object.keys(assets)
+    .map((key) => parseFloat(key))
+    .sort((a, b) => a - b)
+
+  const match = densities.find((d) => d >= devicePixelRatio) ?? densities.at(-1)!
+
+  new Image().src = assets[`${match}x`]
+}
+
+/**
+ * Build a CSS `image-set()` value from a density map.
+ *
+ * @param assets - {@link DensityMap}
+ * @returns CSS `image-set(…)` string for use in `background-image`.
+ *
+ * @example
+ * ```ts
+ * imageSet({ '1x': '/img/bg.webp', '2x': '/img/bg@2x.webp' })
+ * // → "image-set(url('/img/bg.webp') 1x, url('/img/bg@2x.webp') 2x)"
+ * ```
+ */
+export function imageSet(assets: DensityMap) {
+  return `image-set(${Object.entries(assets).map(([density, url]) => `url('${url}') ${density}`).join(', ')})`
+}

package/ui/src/lib/tools/index.ts

@@ -0,0 +1,20 @@
+export { onsubmit } from './onsubmit'
+export { assert } from './assert'
+export { transit, navigate, takeoff, transition, styles } from './transition'
+export { fragment, query, inAppPopOut } from './location'
+export { timeout } from './timeout'
+export * as convert from './convert'
+export * from './mq'
+export { deterministic } from './random'
+export { currency, unit } from './currency'
+export { date, formatISODuration } from './date'
+export { search } from './search'
+export * from './types'
+export { delay } from './delay'
+export { metronome } from './metronome'
+export { expire, cap } from './cap'
+export { clicks } from './clicks'
+export { ago } from './ago'
+export { suppressContextMenu } from './contextmenu'
+export * as image from './image'
+export { toUuid } from './uuid'

package/ui/src/lib/tools/location.ts

@@ -0,0 +1,41 @@
+import { apple, inApp } from './mq'
+
+const hash: URLSearchParams = new URLSearchParams()
+const search: URLSearchParams = new URLSearchParams()
+
+export function fragment(name: string): string | null {
+  return hash.get(name)
+}
+
+export function query(name: string): string | null {
+  return search.get(name)
+}
+
+// function debug() {
+//   if (hash.size > 0)
+//     console.debug('Hash', Object.fromEntries(hash.entries()))
+
+//   if (search.size > 0)
+//     console.debug('Search', Object.fromEntries(search.entries()))
+// }
+
+// if (typeof window !== 'undefined') (() => {
+//   hash = new URLSearchParams(window.location.hash.slice(1))
+//   search = new URLSearchParams(window.location.search.slice(1))
+
+//   if (dev)
+//     debug()
+
+//   // window.history.replaceState({}, '', window.location.pathname)
+// })()
+
+export function inAppPopOut() {
+  if (!inApp) return
+
+  const url = window.location.href
+
+  if (apple)
+    window.location.href = `x-safari-${url}`
+  else
+    window.location.href = `intent://${url.replace(/^https?:\/\//, '')}#Intent;scheme=https;action=android.intent.action.VIEW;category=android.intent.category.BROWSABLE;end`
+}

package/ui/src/lib/tools/metronome.ts

@@ -0,0 +1,11 @@
+import { readable } from 'svelte/store'
+
+function metronome(interval = 1000) {
+  return readable(Date.now(), (set) => {
+    const id = setInterval(() => set(Date.now()), interval)
+
+    return () => clearInterval(id)
+  })
+}
+
+export { metronome }

package/ui/src/lib/tools/mq.ts

@@ -0,0 +1,84 @@
+import { browser } from '$app/environment'
+
+export const windows = browser && navigator.userAgent.toLowerCase().includes('windows')
+
+export const apple = browser
+  ? /mac ?os|ios|ipad ?os/i.test((navigator as any).userAgentData?.platform ?? '') ||
+  /(Mac|iPhone|iPad|iPod)/.test(navigator.userAgent)
+  : false
+
+export const android = browser ? /android/i.test(navigator.userAgent) : false
+
+export const ios = browser ? /(iPhone|iPad|iPod)/.test(navigator.userAgent) : false
+
+export const safari = browser ? /^((?!chrome|android).)*safari/i.test(navigator.userAgent) : false
+
+export const touch = browser ? 'ontouchstart' in window : false
+
+export const standalone = browser ? window.matchMedia('(display-mode: standalone)').matches : false
+
+export const shell = browser ? /PWAShell/i.test(navigator.userAgent) : false
+
+// PWAShell/<version>
+export const shellVersion = navigator.userAgent.match(/PWAShell\/(\S+)/)?.[1] ?? null
+
+// do not autofocus on touch devices, as it's annoying
+export const autofocus = browser ? !('ontouchstart' in window) : false
+
+export const units = {
+  lbs: ['en-US', 'en-LR', 'en-MM'].includes(navigator.language),
+  inches: ['en-US', 'en-GB', 'en-CA', 'en-AU', 'en-NZ', 'en-IE', 'en-IN', 'en-LR', 'en-MM'].includes(navigator.language),
+} as const
+
+export function isInAppWebView(ua: string = navigator.userAgent): boolean {
+  const inAppBrowserPatterns = [
+    /FBAN|FBAV|FB_IAB/i, // Facebook
+    /Instagram/i, // Instagram
+    /Twitter/i, // Twitter
+    /Line/i, // LINE Messenger
+    /LinkedIn/i, // LinkedIn
+    /Snapchat/i, // Snapchat
+    /WhatsApp/i, // WhatsApp
+    /WeChat/i, // WeChat
+    /Messenger/i, // Facebook Messenger
+    /QQ/i, // QQ Browser
+    /Reddit/i, // Reddit
+    /Puffin/i, // Puffin Browser
+    /TikTok/i, // TikTok
+    /musical.ly/i, // TikTok (older)
+    /YouTube/i, // YouTube
+    /Pinterest/i, // Pinterest
+    /Discord/i, // Discord
+    /Telegram/i, // Telegram
+    /Viber/i, // Viber
+    /Slack/i, // Slack
+    /Signal/i, // Signal
+    /KakaoTalk/i, // KakaoTalk (Popular in South Korea)
+    /Baidu/i, // Baidu (Popular in China)
+  ]
+
+  const isInAppBrowser = () => inAppBrowserPatterns.some((pattern) => pattern.test(ua))
+
+  const isGenericWebView = () => {
+    const rules = [
+      'WebView', // Generic WebView detection
+      '(iPhone|iPod|iPad)(?!.*Safari/)', // iOS WebView without Safari
+      'Android.*(wv)', // Android WebView
+      '(AppleWebKit)(?!.*Safari)', // iOS Safari WebView (missing Safari in UA)
+    ]
+
+    const regex = new RegExp(`(${rules.join('|')})`, 'ig')
+
+    return ua.match(regex) !== null
+  }
+
+  const isTelegram = () => (
+    'TelegramWebviewProxy' in window ||
+    'TelegramWebviewProxyProto' in window ||
+    'TelegramWebview' in window
+  )
+
+  return browser && (isInAppBrowser() || isGenericWebView() || isTelegram())
+}
+
+export const inApp = isInAppWebView(navigator.userAgent)

package/ui/src/lib/tools/onsubmit.ts

@@ -0,0 +1,21 @@
+export function onsubmit(callback: Callback) {
+  return async (event: Event) => {
+    event.preventDefault()
+
+    const form = event.target as HTMLFormElement
+    const fieldsets = form.querySelectorAll('fieldset') as NodeListOf<HTMLFieldSetElement>
+    const disabled: HTMLFieldSetElement[] = []
+
+    for (const fieldset of fieldsets) {
+      fieldset.disabled = true
+      disabled.push(fieldset)
+    }
+
+    await callback(event)
+
+    for (const fieldset of disabled)
+      fieldset.disabled = false
+  }
+}
+
+type Callback = (event: Event) => Promise<void> | void

package/ui/src/lib/tools/random.ts

@@ -0,0 +1,15 @@
+export function deterministic(id: string, max: number): number {
+  if (max <= 0) return 0
+
+  if (id.length === 0) return 0
+
+  let hash = 0
+
+  for (let i = 0; i < id.length; i++) {
+    const char = id.charCodeAt(i)
+
+    hash = ((hash << 5) - hash + char) | 0 // djb2 hash with 32-bit conversion
+  }
+
+  return Math.abs(hash) % max
+}

package/ui/src/lib/tools/search.ts

@@ -0,0 +1,25 @@
+/**
+ * Filters an array of items by a search string.
+ * The search is case-insensitive and checks if the stringified item includes the search term.
+ *
+ * @param items - Array of items to filter
+ * @param search - Search string (optional)
+ * @param stringify - Function to extract the searchable text from each item
+ * @returns Filtered array of items
+ */
+export function search<T>(
+  items: T[],
+  search: string | undefined,
+  stringify: (item: T) => string | null | undefined = JSON.stringify,
+): T[] {
+  if (search === undefined || search === '')
+    return items
+
+  const lowercase = search.toLowerCase()
+
+  return items.filter((item) => {
+    const text = stringify(item)
+
+    return text?.toLowerCase().includes(lowercase) ?? false
+  })
+}

package/ui/src/lib/tools/timeout.ts

@@ -0,0 +1,26 @@
+import { readable } from 'svelte/store'
+
+/**
+ * Create a Readable<number> that counts down from ms to 0
+ */
+export function timeout(ms: number, fps = 24) {
+  return readable(ms, (set) => {
+    const then = Date.now()
+    const interval = setInterval(() => tick(), 1000 / fps)
+
+    function tick() {
+      const remaining = ms - (Date.now() - then)
+
+      if (remaining > 0)
+        set(remaining)
+      else {
+        set(0)
+        clearInterval(interval)
+      }
+    }
+
+    tick()
+
+    return () => clearInterval(interval)
+  })
+}

package/ui/src/lib/tools/transition.ts

@@ -0,0 +1,207 @@
+import { derived, writable, type Readable } from 'svelte/store'
+import type { OnNavigate } from '@sveltejs/kit'
+
+export function transit(fn?: (() => void) | (() => Promise<void>)): Promise<void> {
+  if (document.startViewTransition === undefined)
+    return Promise.resolve(fn?.())
+
+  const fly = fn !== undefined
+
+  if (fly) depart()
+
+  return new Promise((resolve) => {
+    const transition = document.startViewTransition(async () => {
+      land()
+      resolve(await fn?.())
+    })
+
+    // An aborted transition rejects `finished`, and the flight has to be unwound either
+    // way: leaving `flying` set keeps view-transition-names on every flyer and breaks the
+    // next transition. Handling both settlements also keeps the rejection from escaping.
+    transition.finished.then(done, done)
+
+    // and so does `ready`, which nothing here waits on: it rejects whenever the transition
+    // is skipped — a hidden tab, a second one started on top of this — and an unhandled
+    // rejection is not what a page should show for an animation it merely did without
+    transition.ready.catch(ignore)
+
+    function done() {
+      if (fly) arrive()
+
+      touchdown()
+    }
+  })
+}
+
+function ignore(): void {}
+
+/**
+ * SvelteKit navigation, wrapped. The update callback has to outlive the navigation it
+ * lets through: it resolves to unblock the router, and only then waits for the new page
+ * to be there. Returning any sooner captures the outgoing page as both the old state and
+ * the new one, and the transition animates nothing at all.
+ */
+export function navigate(nav: OnNavigate): Promise<void> | void {
+  if (nav.type === 'popstate' && nav.event.hasUAVisualTransition) return
+
+  if (document.startViewTransition === undefined) return
+
+  return new Promise((resolve) => {
+    // typed `route`, so a page can style what a navigation does to the whole screen
+    // without styling what every in-page `transit` does to it
+    const transition = document.startViewTransition({
+      types: ['route'],
+      update: async () => {
+        land()
+        resolve()
+
+        await nav.complete
+      },
+    })
+
+    // the same unwinding `transit` does, and for the same reason: an aborted transition
+    // rejects, and a name left on a departed element breaks the next one
+    transition.finished.then(touchdown, touchdown)
+    transition.ready.catch(ignore)
+  })
+}
+
+let launch: Launch | null = null
+
+export function takeoff(id: string, name: string, classes?: string) {
+  if (launch !== null) clearInline(launch)
+
+  const el = document.getElementById(id)
+
+  if (el === null) {
+    console.warn('No element to depart from', id)
+    launch = null
+
+    return
+  }
+
+  el.style.viewTransitionName = name
+
+  if (classes !== undefined)
+    el.style.viewTransitionClass = classes
+
+  launch = { el, name, classes }
+}
+
+function land() {
+  if (launch === null) return
+
+  const clear = launch.el.style.viewTransitionName === launch.name
+
+  launch.el.style.viewTransitionName = clear ? '' : launch.name
+  launch.el.style.viewTransitionClass = clear ? '' : (launch.classes ?? '')
+}
+
+function touchdown() {
+  if (launch === null) return
+
+  // Keep `launch` alive after forward pass so land() can re-apply the name
+  // on return transit (source → target → source morph).
+  if (launch.el.style.viewTransitionName !== launch.name) return
+
+  clearInline(launch)
+  launch = null
+}
+
+function clearInline(launch: Launch) {
+  launch.el.style.viewTransitionName = ''
+  launch.el.style.viewTransitionClass = ''
+}
+
+const flying = writable<boolean>(false)
+const flyers = new Set<Flyer>()
+
+/**
+ * Action to include an element in the non-navigation view transitions.
+ *
+ * @param node
+ * @param options
+ * @returns
+ */
+export function transition(node: HTMLElement, options: FlyOptions) {
+  const flyer = {
+    node,
+    options,
+    original: {
+      name: node.style.viewTransitionName,
+      classes: node.style.viewTransitionClass,
+    },
+  }
+
+  flyers.add(flyer)
+
+  return {
+    destroy: () => flyers.delete(flyer),
+  }
+}
+
+/**
+ * Create a readable store that has `style` value when in non-navigation view transition.
+ *
+ * @param name
+ * @param classes
+ * @returns Readable<string | undefined>
+ */
+export function styles(name: string, classes?: string): Readable<string | undefined> {
+  let value = `view-transition-name: ${name};`
+
+  if (classes !== undefined)
+    value += ` view-transition-class: ${classes};`
+
+  return derived(flying, (flying) => flying ? value : undefined)
+}
+
+function depart() {
+  flying.set(true)
+
+  for (const flyer of flyers) {
+    // could have changed
+    flyer.original = {
+      name: flyer.node.style.viewTransitionName,
+      classes: flyer.node.style.viewTransitionClass,
+    }
+
+    flyer.node.style.viewTransitionName = flyer.options.name
+
+    if (flyer.options.classes !== undefined)
+      flyer.node.style.viewTransitionClass = flyer.options.classes
+  }
+}
+
+function arrive() {
+  for (const flyer of flyers) {
+    if (flyer.original === undefined) continue
+
+    flyer.node.style.viewTransitionName = flyer.original.name
+    flyer.node.style.viewTransitionClass = flyer.original.classes
+  }
+
+  flying.set(false)
+}
+
+interface Flyer {
+  node: HTMLElement
+  options: FlyOptions
+  original?: {
+    name: string
+    classes: string
+  }
+}
+
+interface FlyOptions {
+  /** view-transition-name */
+  name: string
+  /** view-transition-class */
+  classes?: string
+}
+
+interface Launch {
+  el: HTMLElement
+  name: string
+  classes?: string
+}

package/ui/src/lib/tools/types.ts

@@ -0,0 +1,3 @@
+export type Exact<A, B> = A extends B ? (B extends A ? A : never) : never
+
+export type Locale = string