@dtpr/ui/core
@dtpr/ui/core
Import
import {
extract,
extractWithLocale,
interpolate,
interpolateSegments,
groupElementsByCategory,
sortCategoriesByOrder,
findCategoryDefinition,
deriveElementDisplay,
validateDatachain,
HEXAGON_FALLBACK_DATA_URI,
} from '@dtpr/ui/core'
Locale extraction
extract(values, locale)
Return the first LocaleValue matching the requested locale, or an empty string.
function extract(values: readonly LocaleValue[], locale: string): string
extract(
[{ locale: 'en', value: 'Camera' }, { locale: 'fr', value: 'Caméra' }],
'fr',
) // → 'Caméra'
extractWithLocale(values, locale)
Like extract but returns the matched locale too — useful when you want to know whether the extraction fell back.
function extractWithLocale(
values: readonly LocaleValue[],
locale: string,
): ExtractWithLocaleResult // { value: string, locale: string | null }
Interpolation
interpolate(template, vars)
Replace {{variable_id}} tokens in a template string.
function interpolate(template: string, vars: Record<string, string>): string
interpolate('Shared with {{partner}}', { partner: 'Acme' })
// → 'Shared with Acme'
interpolateSegments(template, vars)
Tokenize a template into segments so a renderer can style filled vs missing variables differently.
function interpolateSegments(
template: string,
vars: Record<string, string>,
): readonly InterpolateSegment[]
Each segment is { kind: 'text' | 'variable' | 'missing', value: string, variable_id?: string }. DtprElementDetail uses this helper to highlight filled variables and emphasize missing ones.
Category grouping
groupElementsByCategory(elements)
Bucket a flat element list into { [category_id]: Element[] }.
function groupElementsByCategory(elements: readonly Element[]): Record<string, Element[]>
sortCategoriesByOrder(categories, order)
Order categories according to a reference id sequence (e.g. the one declared on datachainType.categories). Categories not in order land at the end in their natural order.
function sortCategoriesByOrder(
categories: readonly Category[],
order: readonly string[],
): Category[]
findCategoryDefinition(categories, id)
Lookup helper that returns the Category matching id, or undefined.
Display derivation
deriveElementDisplay(element, placement, locale)
Compose the pre-rendered display payload consumed by DtprElement and DtprElementDetail. It resolves the icon URL (including the HEXAGON_FALLBACK_DATA_URI when icon_url is missing), extracts localized strings, and tees up variables with their filled values.
function deriveElementDisplay(
element: Element,
placement: InstanceElement | undefined,
locale: string,
options?: DeriveElementDisplayOptions,
): ElementDisplay
const display = deriveElementDisplay(element, placement, 'en')
// { title, description, citation, icon: {url, alt}, variables: [{id, label, value, type, required}] }
Validation
validateDatachain(instance, source)
Run the same validator used by POST /validate over a DatachainInstance, given a SchemaVersionSource (manifest + categories + elements + datachain-type).
function validateDatachain(
instance: DatachainInstance,
source: SchemaVersionSource,
): ValidationResult // { ok: boolean, errors: SemanticError[], warnings: SemanticError[] }
Use it when you want to run validation client-side without a round-trip.
Constants
HEXAGON_FALLBACK_DATA_URI
Inline data URI for a neutral hexagon fallback icon. Used by deriveElementDisplay when an element lacks an icon_url — pass it to DtprIcon.src wherever you need a safe placeholder.
const HEXAGON_FALLBACK_DATA_URI: string // 'data:image/svg+xml,...'
Type exports
@dtpr/ui/core also re-exports the schema types so consumers don't have to depend on @dtpr/api directly:
| Type | Description |
|---|---|
Element, Category, LocaleValue, Variable, VariableType | Schema primitives. |
InstanceElement, InstanceVariableValue, DatachainInstance | Instance primitives. |
SchemaManifest | Manifest shape. |
InterpolateSegment | Segment type returned by interpolateSegments. |
ElementDisplay, ElementDisplayIcon, ElementDisplayVariable | Derived display payload. |
ExtractWithLocaleResult | { value, locale } from extractWithLocale. |
SchemaVersionSource, SemanticError, Severity, ValidationResult | Validator inputs and outputs. |
DeriveElementDisplayOptions | Options bag for deriveElementDisplay. |