@kinetis/vector-ui 0.0.0-stage → 0.9.0

package/app/types/vector.ts

@@ -0,0 +1,438 @@
+/**
+ * The descriptor `GET /vector/schema` publishes, as the layer consumes it.
+ * Mirrors packages/vector's ResourceDescriptor::toArray().
+ */
+
+export type VectorFieldType =
+    | 'id' | 'string' | 'text' | 'markdown' | 'number' | 'money' | 'boolean'
+    | 'enum' | 'date' | 'datetime' | 'email' | 'url' | 'password' | 'slug'
+    | 'color' | 'json' | 'keyValue' | 'currency' | 'file' | 'image'
+    | 'belongsTo' | 'hasOne' | 'hasMany' | 'manyToMany' | 'computed' | 'richtext'
+
+/** A rich-text feature: a node or mark type the field's schema allows (or one a runtime extension added). */
+export type VectorRichTextFeature = 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'heading' | 'list' | 'blockquote' | 'codeBlock' | 'horizontalRule' | 'link' | 'table' | 'image' | 'mention' | (string & {})
+
+/** A rich-text field's schema and sources. */
+export interface VectorRichText {
+    features: VectorRichTextFeature[]
+    /** The file or image field whose uploads images come from. */
+    imageField: string | null
+    /** The relation whose records `@` mentions. */
+    mentions: string | null
+    /** The stored value is HTML rendered through the schema, not the document. */
+    storesHtml: boolean
+    maxBytes: number
+}
+
+/** What a computed field is shown as. */
+export type VectorComputedAs = 'text' | 'number' | 'money' | 'boolean' | 'date' | 'datetime' | 'enum'
+
+export type VectorView = 'index' | 'show' | 'create' | 'update'
+
+export interface VectorEnumOption {
+    value: string | number
+    label: string
+    color: string | null
+}
+
+export interface VectorRule {
+    constraint: string
+    args: unknown[]
+}
+
+export interface VectorRelation {
+    /** hasOne/hasMany: the target's field that points back at the owner */
+    inverse?: string
+    kind: 'belongsTo' | 'hasOne' | 'hasMany' | 'manyToMany'
+    resource: string
+    titleField: string | null
+    /** belongsTo: the choices are the target records whose `on` equals this form's `field` */
+    dependsOn?: { field: string, on: string, label: string } | null
+}
+
+export type VectorOperator = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'in' | 'nin' | 'like' | 'nlike' | 'between' | 'null' | 'nnull'
+
+export interface VectorField {
+    name: string
+    type: VectorFieldType
+    label: string
+    sortable: boolean
+    searchable: boolean
+    filterable: boolean
+    readonly: boolean
+    /** Editable in place in the list (inlineEditable()). */
+    inline?: boolean
+    /** Unique among the resource's records: a duplicate starts without it; an import may match by it. */
+    unique?: boolean
+    /** hasMany: the owned rows edited inside the parent's form */
+    repeater?: { fields: string[], min: number, max: number } | null
+    help: string | null
+    component: string | null
+    views: VectorView[]
+    rules: VectorRule[]
+    props: Record<string, unknown> | []
+    summary: 'sum' | 'avg' | 'min' | 'max' | 'count' | null
+    default: unknown
+    hasDefault: boolean
+    operators: VectorOperator[]
+    nullable?: boolean
+    valueType?: 'string' | 'int' | 'float' | 'bool' | 'timestamp' | 'date'
+    options?: VectorEnumOption[]
+    relation?: VectorRelation
+    conditions?: VectorFieldConditions
+    /** A computed field: shown as `as`, computed on the server from the `from` fields. */
+    computed?: { as: VectorComputedAs, from: string[] }
+    /** A rich-text field's schema. */
+    richtext?: VectorRichText
+    /** A Markdown field's toolbar. */
+    markdown?: { toolbar: string[] }
+}
+
+/** One comparison against another field of the same form. */
+export interface VectorCondition {
+    field: string
+    op: 'eq' | 'ne' | 'in' | 'nin' | 'null' | 'nnull'
+    value: unknown
+}
+
+/** Form behaviour that depends on other fields; every condition of a kind must hold. */
+export interface VectorFieldConditions {
+    visible: VectorCondition[]
+    required: VectorCondition[]
+    disabled: VectorCondition[]
+}
+
+export interface VectorFieldState {
+    visible: boolean
+    required: boolean
+    disabled: boolean
+}
+
+export interface VectorAction {
+    name: string
+    label: string
+    icon: string | null
+    confirmation: string | null
+    destructive: boolean
+    standalone: boolean
+    showOnIndex: boolean
+    showOnDetail: boolean
+    fields: VectorField[]
+}
+
+export interface VectorActionResponse {
+    type: 'message' | 'danger' | 'redirect' | 'url' | 'download' | 'job'
+    message: string | null
+    url: string | null
+    affected: number
+    jobId?: number | null
+}
+
+export type VectorWidgetType = 'stat' | 'trend' | 'partition' | 'progress' | 'table'
+
+export interface VectorWidget {
+    name: string
+    label: string
+    type: VectorWidgetType
+    icon: string | null
+    ranges: Record<string, string>
+    width: 3 | 4 | 6 | 12
+    cacheSeconds: number
+    /** Whether the cached result is shared by every user, or kept per user. */
+    cacheShared?: boolean
+}
+
+export interface VectorWidgetData {
+    type: VectorWidgetType
+    range: string
+    cached: boolean
+    format?: string
+    value?: number | null
+    previous?: number | null
+    caption?: string | null
+    points?: { x: string, y: number }[]
+    total?: number | null
+    slices?: { label: string, value: number, color?: string | null }[]
+    target?: number
+    columns?: { key: string, label: string, align?: 'start' | 'end' }[]
+    rows?: Record<string, unknown>[]
+    link?: string | null
+}
+
+export interface VectorDashboard {
+    name: string
+    label: string
+    icon: string | null
+    widgets: VectorWidget[]
+}
+
+export interface VectorJob {
+    id: number
+    kind: 'action' | 'export' | 'import'
+    resource: string
+    name: string
+    actorId: string
+    status: 'queued' | 'running' | 'done' | 'failed' | 'stalled'
+    total: number | null
+    processed: number
+    result: Record<string, unknown> | null
+    failure: string | null
+    hasFile: boolean
+    fileName: string | null
+    createdAt: string
+    updatedAt: string
+    finishedAt: string | null
+}
+
+export interface VectorNotification {
+    id: number
+    kind: 'info' | 'success' | 'warning' | 'error'
+    title: string
+    body: string | null
+    link: string | null
+    readAt: string | null
+    createdAt: string
+}
+
+export interface VectorAuditEntry {
+    id: number
+    event: string
+    actorId: string
+    impersonatorId: string | null
+    changes: Record<string, { from: unknown, to: unknown }>
+    createdAt: string
+}
+
+export type VectorExportFormat = 'csv' | 'xlsx'
+
+/** A language the admin can be shown in: its tag, its name in itself, and its direction. */
+export interface VectorLocale {
+    code: string
+    name: string
+    dir: 'ltr' | 'rtl'
+}
+
+export interface VectorSchemaI18n {
+    locale: string
+    locales: VectorLocale[]
+}
+
+/** create adds every row; update changes the records a key column finds; upsert does either. */
+export type VectorImportMode = 'create' | 'update' | 'upsert'
+
+export interface VectorImportPreview {
+    headers: string[]
+    rows: number
+    sample: Record<string, string>[]
+    mapping: Record<string, string>
+}
+
+/** One condition set, `filter[field][op] = value`, all of which must hold; values as the query string carries them. */
+export type VectorFilters = Record<string, Partial<Record<VectorOperator, string>>>
+
+/** Alternatives: any one of these condition sets may hold. */
+export type VectorFilterGroup = VectorFilters[]
+
+/**
+ * The list grammar's whole filter object: field conditions, `trashed`,
+ * and `or` / `and` holding more filter objects — `(a or b) and c` is
+ * `{c: …, or: [{a: …}, {b: …}]}`.
+ */
+export interface VectorFilterQuery {
+    [key: string]: Partial<Record<VectorOperator, string>> | string | VectorFilterQuery[] | undefined
+}
+
+/** The list grammar a saved view stores and a bulk "all matching" selection sends. */
+export interface VectorListState {
+    filter?: VectorFilterQuery
+    q?: string
+    sort?: string
+    group?: string
+    columns?: string
+    perPage?: number
+    summaries?: boolean
+}
+
+export interface VectorSelection {
+    ids?: (number | string)[]
+    all?: { filter?: VectorFilterQuery, q?: string }
+}
+
+export interface VectorSavedView {
+    id: number
+    resource: string
+    ownerId: string
+    name: string
+    shared: boolean
+    isDefault: boolean
+    /** the default of everyone who has none of their own */
+    resourceDefault: boolean
+    state: VectorListState
+    mine: boolean
+}
+
+export interface VectorSettingsGroup {
+    name: string
+    label: string
+    icon: string | null
+    fields: VectorField[]
+    values: Record<string, unknown>
+}
+
+export interface VectorBranding {
+    title: string
+    logoUrl: string | null
+    primaryColor: string | null
+    primaryColorDark: string | null
+    theme: 'system' | 'light' | 'dark' | null
+    footerText: string | null
+}
+
+export interface VectorSearchResult {
+    resource: string
+    resourceLabel: string
+    id: number | string
+    title: string
+    /** the resource's searchSubtitle() field, as stored */
+    subtitle?: string | null
+    /** the image field to fetch the thumbnail from, when the record has one */
+    image?: string | null
+}
+
+export interface VectorSort {
+    field: string
+    order: 'asc' | 'desc'
+}
+
+/**
+ * One node of a resource's layout. Every key is present; the ones a kind
+ * does not use are null or false. A `field` node names a field of the
+ * resource; the others hold `children`.
+ */
+export interface VectorLayoutNode {
+    kind: 'section' | 'tabs' | 'tab' | 'field'
+    label: string | null
+    description: string | null
+    collapsible: boolean
+    collapsed: boolean
+    /** A section's or tab's grid columns (1 to 4). */
+    columns: number | null
+    /** A field's width: 1 or 2 columns, or the whole row; null sizes it by its type. */
+    span: 1 | 2 | 'full' | null
+    name: string | null
+    children: VectorLayoutNode[] | null
+}
+
+/** How the form and the show page group the fields, per view. */
+export interface VectorLayout {
+    form: VectorLayoutNode[]
+    show: VectorLayoutNode[]
+}
+
+export interface VectorResource {
+    slug: string
+    label: string
+    labelSingular: string
+    group: string | null
+    icon: string | null
+    primaryKey: { field: string, column?: string, type: 'int' | 'string' }
+    titleField: string
+    version: string | null
+    fields: VectorField[]
+    table: {
+        columns: string[]
+        defaultSort: VectorSort[]
+        perPage: number
+        perPageOptions: number[]
+        maxPerPage: number
+        search: string[]
+        groupable: string[]
+        summaries: string[]
+        exportLimit: number
+        bulkLimit: number
+    }
+    show: { fields: string[] }
+    /** Whether a record may be duplicated into a new one's form. */
+    replicable?: boolean
+    /** Sections, tabs and spans; null when the resource declares none. Optional for a descriptor from before layout existed. */
+    layout?: VectorLayout | null
+    softDelete: { field: string } | null
+    /** what a global search result shows besides its title */
+    searchResult?: { subtitle: string | null, image: string | null }
+    /** Whether global search covers this resource. */
+    globallySearchable?: boolean
+    actions: VectorAction[]
+    widgets: VectorWidget[]
+    permissions: { viewAny: boolean, create: boolean, update: boolean, delete: boolean, export: boolean, setDefaultView?: boolean }
+}
+
+export interface VectorRecordPermissions {
+    update: boolean
+    delete: boolean
+    restore: boolean
+    forceDelete: boolean
+    actions: string[]
+}
+
+export interface VectorMenuGroup {
+    label: string
+    resources: string[]
+}
+
+export interface VectorSchema {
+    version: number
+    resources: Record<string, VectorResource>
+    menu: VectorMenuGroup[]
+    settings: { name: string, label: string, icon: string | null }[]
+    dashboards: { name: string, label: string, icon: string | null }[]
+    /** `exportFormats`: what the export menu offers — csv always, xlsx where the server can write it (in the queue). */
+    capabilities: { impersonation: boolean, queue: boolean, uploads?: boolean, exportFormats?: VectorExportFormat[] }
+    branding: VectorBranding | null
+    /** The language this descriptor is in, and the ones this user may switch to. */
+    i18n?: VectorSchemaI18n
+    /** ISO 4217 exponents of the currencies whose minor unit is not a hundredth */
+    minorUnits?: Record<string, number>
+}
+
+export interface VectorMe {
+    id: number | string
+    name: string | null
+    preferences: Record<string, unknown>
+    impersonator: number | string | null
+    unreadNotifications: number
+}
+
+export interface VectorRelationValue {
+    id: number | string
+    label: string
+    /** A choice list's option only: the target's search subtitle, when declared and visible. */
+    subtitle?: string | null
+    /** A choice list's option only: the image field to fetch its thumbnail from, when the record has one. */
+    image?: string | null
+}
+
+export interface VectorUploaded {
+    key: string
+    name: string | null
+    size: number
+    type: string
+}
+
+export interface VectorCountValue {
+    count: number
+}
+
+export type VectorRecord = Record<string, unknown> & { id: number | string }
+
+export interface VectorPage {
+    data: VectorRecord[]
+    currentPage: number
+    perPage: number
+    total: number
+    lastPage: number
+    summaries?: Record<string, number | null>
+}
+
+export function fieldProps(field: VectorField): Record<string, unknown> {
+    return Array.isArray(field.props) ? {} : field.props
+}

package/app/utils/files.ts

@@ -0,0 +1,14 @@
+/**
+ * A file's bytes as a `data:` URL, for an <img>. The hosted shell's strict
+ * Content Security Policy admits `data:` images (`img-src 'self' data: https:`)
+ * but not `blob:` ones, so every image the admin fetches with its credentials
+ * is shown this way; a download may still use a blob link.
+ */
+export function dataUrl(blob: Blob): Promise<string> {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader()
+        reader.onload = () => resolve(String(reader.result))
+        reader.onerror = () => reject(reader.error)
+        reader.readAsDataURL(blob)
+    })
+}

package/app/utils/format.ts

@@ -0,0 +1,100 @@
+const currencyFormatters = new Map<string, Intl.NumberFormat>()
+
+// The UI's language, which dates, numbers and money format in; undefined (the
+// browser's) until the i18n plugin sets it. The UI runs in the browser only,
+// one app per page, so a module-level value is safe.
+let formatLocale: string | undefined
+
+/** Formats in `locale` from now on: the admin's current language. */
+export function setFormatLocale(locale: string | undefined): void {
+    if (locale === formatLocale) return
+    formatLocale = locale
+    currencyFormatters.clear()
+    dateTime = null
+    date = null
+}
+
+// The server's ISO 4217 exponents for the codes that are not hundredths. The
+// server stores minor units, so its table — not the browser's CLDR data, which
+// differs for a few codes — decides where the decimal point goes.
+const minorUnitExceptions = new Map<string, number>()
+
+/** Takes the exponents the schema publishes. */
+export function adoptMinorUnits(exponents: Record<string, number>): void {
+    minorUnitExceptions.clear()
+    for (const [code, digits] of Object.entries(exponents)) minorUnitExceptions.set(code, digits)
+}
+
+/** How many decimals a money value in this currency has: 2 unless ISO 4217 says otherwise. */
+export function minorDigits(currency: string | null | undefined): number {
+    if (!currency) return 2
+    return minorUnitExceptions.get(currency.toUpperCase()) ?? 2
+}
+
+export function formatMoney(minorUnits: number, currency: string): string {
+    const digits = minorDigits(currency)
+    const key = `${currency}:${digits}`
+    let formatter = currencyFormatters.get(key)
+
+    if (!formatter) {
+        formatter = new Intl.NumberFormat(formatLocale, { style: 'currency', currency, minimumFractionDigits: digits, maximumFractionDigits: digits })
+        currencyFormatters.set(key, formatter)
+    }
+
+    return formatter.format(minorUnits / 10 ** digits)
+}
+
+let dateTime: Intl.DateTimeFormat | null = null
+let date: Intl.DateTimeFormat | null = null
+
+export function formatDateTime(iso: string): string {
+    dateTime ??= new Intl.DateTimeFormat(formatLocale, { dateStyle: 'medium', timeStyle: 'short' })
+    return dateTime.format(new Date(iso))
+}
+
+export function formatDate(iso: string): string {
+    // A date-only value is a calendar date, not an instant: keep it out of the local zone.
+    const [y, m, d] = iso.slice(0, 10).split('-').map(Number)
+
+    date ??= new Intl.DateTimeFormat(formatLocale, { dateStyle: 'medium' })
+    return date.format(new Date(y!, m! - 1, d!))
+}
+
+export function formatNumber(value: number, decimals?: number): string {
+    return new Intl.NumberFormat(formatLocale, decimals === undefined ? {} : { minimumFractionDigits: decimals, maximumFractionDigits: decimals }).format(value)
+}
+
+/**
+ * A money field's currency: its fixed one, or the one its currencyField
+ * names in the record — through a relation for `order.currency`, whose
+ * value is the related record (or `{id, label, currency}`). Null when the
+ * record does not say.
+ */
+export function currencyOf(field: { props?: Record<string, unknown> | unknown[] | null }, record: Record<string, unknown> | undefined): string | null {
+    const props = field.props && !Array.isArray(field.props) ? field.props : {}
+    if (typeof props.currency === 'string') return props.currency
+    if (typeof props.currencyField !== 'string') return null
+    const value = props.currencyField.split('.').reduce<unknown>(
+        (current, key) => (current && typeof current === 'object' ? (current as Record<string, unknown>)[key] : undefined),
+        record,
+    )
+    return typeof value === 'string' && value !== '' ? value : null
+}
+
+const currencyNames = new Map<string, Intl.DisplayNames>()
+
+/** A currency code with its name in the given language: `EUR · Euro`. */
+export function currencyLabel(code: string, locale: string | undefined = formatLocale): string {
+    const key = locale ?? ''
+    let names = currencyNames.get(key)
+    if (!names) {
+        try {
+            names = new Intl.DisplayNames(locale ? [locale] : undefined, { type: 'currency' })
+        } catch {
+            return code
+        }
+        currencyNames.set(key, names)
+    }
+    const name = names.of(code)
+    return name && name !== code ? `${code} · ${name}` : code
+}