@greendrake/ui 0.1.0

package/src/CurrencyInput.vue

@@ -0,0 +1,143 @@
+<script lang="ts">
+const isValid = (v: string): boolean => !v || /^[\d,.]+$/.test(v)
+const limitPrecision = (n: string, precision: number): string => {
+    if (!n.includes('.')) {
+        return n
+    }
+    const parts = n.split('.')
+    if (!precision) {
+        return parts[0]
+    }
+    return parts[0] + '.' + parts[1].substring(0, precision)
+}
+const doInsertThousandsSeparators = (n: string): string => n.replace(/\D/g, '').replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+const insertThousandsSeparators = (n: string): string => {
+    if (!n.includes('.')) {
+        return doInsertThousandsSeparators(n)
+    }
+    const parts = n.split('.')
+    return doInsertThousandsSeparators(parts[0]) + '.' + parts[1]
+}
+const ensureDecimals = (n: string, precision: number): string => {
+    const parts = n.split('.')
+    if (!precision) {
+        return parts[0]
+    }
+    return parts[0] + '.' + (parts[1] || '').padEnd(precision, '0')
+}
+</script>
+<script setup lang="ts">
+import { ref, watch, onMounted } from 'vue'
+import { hasFinePointer } from '@greendrake/util'
+
+const props = withDefaults(
+    defineProps<{
+        // Accessible name for the amount input (the visible caption usually
+        // names the composite row, not this control).
+        ariaLabel?: string
+        placeholder?: string
+        autofocus?: boolean
+        symbol?: string
+        hideSymbol?: boolean
+        doNotShowZeroDecimals?: boolean
+        forceDecimals?: boolean
+        disabled?: boolean
+        min?: number | string | null
+        precision?: number
+    }>(),
+    {
+        precision: 2
+    }
+)
+const model = defineModel<string | null>()
+const groomValue = (v: string | null, forceDecimals?: boolean): string => {
+    if (v === null || v === '') {
+        return ''
+    }
+    let result = insertThousandsSeparators(limitPrecision(v, props.precision))
+    if (props.forceDecimals || forceDecimals) {
+        result = ensureDecimals(result, props.precision)
+    }
+    if (props.doNotShowZeroDecimals && result.endsWith(`.${'0'.repeat(props.precision)}`)) {
+        result = result.substring(0, result.length - (1 + props.precision))
+    }
+    return result
+}
+const input = ref<HTMLInputElement | null>(null)
+let previous: string | null = null
+const isFullyValid = (v: string): boolean => {
+    if (!isValid(v)) {
+        return false
+    }
+    if (props.min && Number(props.min) > Number(v)) {
+        return false
+    }
+    return true
+}
+const onInput = () => {
+    const inp = input.value
+    if (!inp) return
+    if (isFullyValid(inp.value)) {
+        previous = inp.value
+        if (inp.value) {
+            const groomed = groomValue(inp.value)
+            if (inp.value !== groomed) {
+                const whole = inp.value.split('.')[0]
+                const caretPos = insertThousandsSeparators(whole).length - whole.length + (inp.selectionStart ?? 0)
+                inp.value = groomed
+                inp.setSelectionRange(caretPos, caretPos)
+            }
+        }
+        model.value = inp.value ? ensureDecimals(inp.value.replace(/,/g, ''), props.precision) : null
+    } else if (previous !== null && input.value) {
+        input.value.value = previous
+    }
+}
+const model2input = () => {
+    if (input.value) {
+        input.value.value = groomValue(model.value ?? null)
+    }
+}
+watch(model, mv => {
+    if (input.value && groomValue(input.value.value, true) !== groomValue(mv ?? null, true)) {
+        model2input()
+    }
+})
+onMounted(() => {
+    if (model.value) {
+        model2input()
+    }
+    // Pointer devices only — see TextField for why touch is excluded.
+    if (props.autofocus && input.value && hasFinePointer()) {
+        input.value.focus()
+    }
+})
+</script>
+<template>
+    <div :data-currency="symbol" class="CurrencyInput" :class="{ 'CurrencyInput--no-symbol': hideSymbol }">
+        <input ref="input" type="text" :aria-label="ariaLabel" :placeholder="placeholder" :disabled="disabled" @input="onInput" />
+    </div>
+</template>
+<style lang="scss">
+.CurrencyInput {
+    position: relative;
+    input {
+        text-align: end;
+        width: 100%;
+    }
+    &:not(.CurrencyInput--no-symbol) {
+        &::before {
+            opacity: 0.8;
+            font-weight: bold;
+            content: attr(data-currency);
+            position: absolute;
+            top: 50%;
+            transform: translateY(-50%);
+            inset-inline-start: 8px;
+        }
+        input {
+            padding-inline-start: 30px;
+        }
+    }
+}
+</style>

package/src/Email.vue

@@ -0,0 +1,17 @@
+<script setup lang="ts">
+import { isEmailValid } from '@greendrake/domains'
+import TextField from './TextField.vue'
+import { messages } from './messages'
+
+const model = defineModel<string>({ default: '' })
+defineProps<{
+    placeholder?: string
+    autofocus?: boolean
+    id?: string
+    validateOnBlur?: boolean
+}>()
+const validator = (v: string): true | string => isEmailValid(v) || messages.invalidEmail
+</script>
+<template>
+    <TextField :id="id" v-model="model" type="email" :validator="validator" :placeholder="placeholder" :autofocus="autofocus" :validate-on-blur="validateOnBlur" v-bind="$attrs" />
+</template>

package/src/Field.vue

@@ -0,0 +1,54 @@
+<script setup lang="ts">
+defineProps<{
+    label?: string
+    // Set when the slot holds a GROUP of controls (radio set, composite row):
+    // the caption then names a role="group" wrapper instead of wrapping the
+    // content in a <label>, which would smear one label across every control.
+    group?: boolean
+    // Set when the slot's control cannot be labelled implicitly — a
+    // contenteditable is not a labelable element. A <label> around one binds to
+    // the first labelable descendant instead, and a rich editor's is its
+    // toolbar's first <button>: the caption would then name that button, and
+    // every click in the field would be FORWARDED to it as a real click, so
+    // clicking into the text would silently press Bold.
+    //
+    // Such a control names itself (RichEditor's ariaLabel puts it on the
+    // contenteditable), so the caption is left as plain text — no role="group",
+    // which would only announce the name a second time.
+    unlabelable?: boolean
+}>()
+</script>
+<template>
+    <div class="Field">
+        <template v-if="label && group">
+            <span class="Field__caption">{{ label }}</span>
+            <div role="group" :aria-label="label" class="Field__group">
+                <slot />
+            </div>
+        </template>
+        <!-- No wrapper at all: .Field is already the column the <label> below
+             would have been, so the caption and control sit exactly where the
+             labelled variant puts them. -->
+        <template v-else-if="label && unlabelable">
+            <span class="Field__caption">{{ label }}</span>
+            <slot />
+        </template>
+        <!-- The single control renders INSIDE the label (implicit association):
+             the caption is the control's accessible name, zero id plumbing. -->
+        <label v-else-if="label">
+            <span class="Field__caption">{{ label }}</span>
+            <slot />
+        </label>
+        <slot v-else />
+    </div>
+</template>
+<style lang="scss" scoped>
+.Field {
+    display: flex;
+    flex-direction: column;
+    > label {
+        display: flex;
+        flex-direction: column;
+    }
+}
+</style>

package/src/FieldTip.scss

@@ -0,0 +1,76 @@
+// Styling for the field-validation tooltips FieldTip.ts creates, scoped to the
+// `fieldTip` theme it applies. Self-contained (there is no global tippy.js base
+// stylesheet) so it styles only these tips and never the other themed,
+// arrow-less tippies (menus, async-search): a filled box with a pointer arrow,
+// its box/arrow geometry mirroring tippy.js' own tippy.css. The fill is the
+// --tippy-background-color token, defaulting to violet.
+.tippy-box[data-theme~='fieldTip'] {
+    position: relative;
+    background-color: var(--tippy-background-color, #5335e8);
+    color: #fff;
+    border-radius: var(--border-radius, 4px);
+    font-size: var(--font-md);
+    line-height: 1.4;
+    white-space: normal;
+    outline: 0;
+
+    .tippy-content {
+        position: relative;
+        padding: 5px 9px;
+        z-index: 1;
+    }
+
+    // Arrow: tippy positions the element (inline transform); these rules give it
+    // its triangle shape per placement. `currentColor` picks up the arrow's color
+    // (set to the box fill above) — the same mechanism tippy.css uses.
+    > .tippy-arrow {
+        position: absolute;
+        width: 16px;
+        height: 16px;
+        color: var(--tippy-background-color, #5335e8);
+    }
+    > .tippy-arrow::before {
+        content: '';
+        position: absolute;
+        border-color: transparent;
+        border-style: solid;
+    }
+    &[data-placement^='top'] > .tippy-arrow {
+        bottom: 0;
+    }
+    &[data-placement^='top'] > .tippy-arrow::before {
+        bottom: -7px;
+        left: 0;
+        border-width: 8px 8px 0;
+        border-top-color: currentColor;
+        transform-origin: center top;
+    }
+    &[data-placement^='bottom'] > .tippy-arrow {
+        top: 0;
+    }
+    &[data-placement^='bottom'] > .tippy-arrow::before {
+        top: -7px;
+        left: 0;
+        border-width: 0 8px 8px;
+        border-bottom-color: currentColor;
+        transform-origin: center bottom;
+    }
+    &[data-placement^='left'] > .tippy-arrow {
+        right: 0;
+    }
+    &[data-placement^='left'] > .tippy-arrow::before {
+        right: -7px;
+        border-width: 8px 0 8px 8px;
+        border-left-color: currentColor;
+        transform-origin: center left;
+    }
+    &[data-placement^='right'] > .tippy-arrow {
+        left: 0;
+    }
+    &[data-placement^='right'] > .tippy-arrow::before {
+        left: -7px;
+        border-width: 8px 8px 8px 0;
+        border-right-color: currentColor;
+        transform-origin: center right;
+    }
+}

package/src/FieldTip.ts

@@ -0,0 +1,57 @@
+// The declaration has to reach every program that compiles this file — this
+// package's own check, a sibling package, an app, an outside consumer — and a
+// path reference is what travels with the source. The rule's advice does not
+// apply: an `import` cannot carry an ambient wildcard module declaration.
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference
+/// <reference path="./styles.d.ts" />
+import { watch, onUnmounted, type Ref, type ComponentPublicInstance } from 'vue'
+import { useTippy } from 'vue-tippy'
+// Self-contained box/arrow styling for these tips, scoped to the `fieldTip` theme
+// applied below (the app ships no global tippy.js base stylesheet).
+import './FieldTip.scss'
+
+type Tooltip = ReturnType<typeof useTippy>
+
+const getElement = (ref: string | Ref<HTMLElement | ComponentPublicInstance | null>): HTMLElement | null => {
+    if (typeof ref === 'string') {
+        return document.getElementById(ref)
+    }
+    const val = ref.value
+    if (val === null) {
+        return null
+    }
+    return '$el' in val ? (val.$el as HTMLElement) : val
+}
+
+// Binds a manually-triggered tippy tooltip to a field element, driven by a
+// reactive content source: setting it to a string shows the tip (as text —
+// tip messages are plain strings by contract), setting it to false hides it.
+// The tip also resets the source to false when dismissed by the user, so the
+// field can re-trigger it later.
+export default (toWatchRef: Ref<string | false>, targetRef: string | Ref<HTMLElement | ComponentPublicInstance | null>): void => {
+    let tooltip: Tooltip | undefined
+
+    onUnmounted(() => {
+        if (tooltip && !tooltip.state.value.isDestroyed) {
+            tooltip.destroy()
+        }
+    })
+
+    watch(toWatchRef, content => {
+        const el = getElement(targetRef)
+        if (!content && tooltip) {
+            tooltip.destroy()
+        } else if (content && el) {
+            tooltip = useTippy(el, {
+                content,
+                theme: 'fieldTip',
+                trigger: 'manual',
+                interactive: true,
+                showOnCreate: true,
+                onHidden: () => {
+                    toWatchRef.value = false
+                }
+            })
+        }
+    })
+}

package/src/FixAndroidTyping.ts

@@ -0,0 +1,13 @@
+import type { Ref } from 'vue'
+
+type InputElement = HTMLInputElement | HTMLTextAreaElement
+
+// Some Android keyboards compose text without firing the events Vue's v-model
+// relies on, leaving the model behind the actual input value. Called from an
+// @input handler, this syncs the model from the DOM when they diverge.
+export default (inputRef: Ref<InputElement | null>, modelRef: Ref<string>, isValid?: (value: string) => boolean): void => {
+    const input = inputRef.value
+    if (input && input.value !== modelRef.value && (!isValid || isValid(input.value))) {
+        modelRef.value = input.value
+    }
+}

package/src/Form.ts

@@ -0,0 +1,124 @@
+import { computed, ref, shallowRef, type Ref, type ComputedRef } from 'vue'
+import { Retrier } from '@greendrake/util'
+import { messages } from './messages'
+
+// Rest states derive from validity/dirtiness; dictated states are imposed by
+// an in-flight or just-finished submission.
+type RestState = 'invalid' | 'dirty' | 'saved'
+type DictatedState = 'confirm' | 'inprogress' | 'success' | 'error'
+export type FormState = RestState | DictatedState
+
+export interface FormOptions {
+    valid?: Ref<boolean>
+    dirty?: Ref<boolean>
+    alwaysValid?: boolean
+    alwaysDirty?: boolean
+    // First action() enters the 'confirm' state; the next one (while it lasts)
+    // actually submits.
+    requireConfirmation?: boolean
+    handler?: () => Promise<unknown>
+    // Retry the handler indefinitely (Retrier) until it succeeds or the form
+    // is destroyed; the countdown between attempts is surfaced via statusInfo.
+    tryPersistently?: boolean
+    // How long the respective dictated state lasts before returning to a rest
+    // state: a number of ms, false to keep it forever (or, for success, to
+    // skip the state entirely), undefined for the 2000ms default.
+    successTimeout?: number | false
+    confirmTimeout?: number | false
+    errorTimeout?: number | false
+}
+
+const DEFAULT_STATE_TIMEOUT = 2000
+
+// Form submission state machine: validity/dirtiness flow in as refs, action()
+// runs the handler through the confirm/inprogress/success/error lifecycle.
+export default class Form {
+    readonly isValid: ComputedRef<boolean>
+    readonly isDirty: ComputedRef<boolean>
+    readonly state: ComputedRef<FormState>
+    // Whether action() would do anything: only in the 'dirty' and 'confirm'
+    // states is there something to submit.
+    readonly isActionable: ComputedRef<boolean>
+    // Retry countdown message while a persistent try is between attempts;
+    // empty otherwise.
+    readonly statusInfo: Ref<string> = ref('')
+
+    readonly #options: FormOptions
+    readonly #dictatedState = shallowRef<DictatedState | false>(false)
+    #retrier?: Retrier<unknown>
+    #timeout?: ReturnType<typeof setTimeout>
+    #destroyed = false
+
+    constructor(options: FormOptions = {}) {
+        this.#options = options
+        this.isValid = computed(() => options.alwaysValid || (options.valid ? options.valid.value : true))
+        this.isDirty = computed(() => options.alwaysDirty || (options.dirty ? options.dirty.value : true))
+        this.state = computed((): FormState => {
+            if (this.#dictatedState.value !== false) {
+                return this.#dictatedState.value
+            }
+            return this.isValid.value ? (this.isDirty.value ? 'dirty' : 'saved') : 'invalid'
+        })
+        this.isActionable = computed(() => this.state.value === 'dirty' || this.state.value === 'confirm')
+    }
+
+    async action(): Promise<void> {
+        if (!this.isActionable.value) {
+            return
+        }
+        this.#clearTimeout()
+        if (this.#options.requireConfirmation && this.state.value !== 'confirm') {
+            this.#dictatedState.value = 'confirm'
+        } else {
+            this.#dictatedState.value = 'inprogress'
+            try {
+                if (this.#options.handler) {
+                    if (this.#options.tryPersistently) {
+                        this.#retrier = new Retrier({ attempt: this.#options.handler })
+                        this.#retrier.on('trying', () => (this.statusInfo.value = ''))
+                        this.#retrier.on('waiting', secondsLeft => (this.statusInfo.value = messages.retryCountdown.replace('{seconds}', String(secondsLeft))))
+                        try {
+                            await this.#retrier.run()
+                        } finally {
+                            this.#retrier = undefined
+                            this.statusInfo.value = ''
+                        }
+                    } else {
+                        await this.#options.handler()
+                    }
+                }
+                this.#dictatedState.value = this.#options.successTimeout === false ? false : 'success'
+            } catch {
+                this.#dictatedState.value = 'error'
+            }
+        }
+        if (this.#destroyed) {
+            return
+        }
+        // Schedule the dictated state's expiry back to a rest state. Only
+        // confirm/success/error can be current here: 'inprogress' always ends
+        // when the handler settles (re-entry is barred by isActionable).
+        const dictated = this.#dictatedState.value
+        if (dictated !== false) {
+            const timeoutValue = this.#options[`${dictated}Timeout`]
+            if (timeoutValue !== false) {
+                this.#timeout = setTimeout(() => {
+                    this.#dictatedState.value = false
+                }, timeoutValue ?? DEFAULT_STATE_TIMEOUT)
+            }
+        }
+    }
+
+    #clearTimeout(): void {
+        if (this.#timeout) {
+            clearTimeout(this.#timeout)
+            this.#timeout = undefined
+        }
+    }
+
+    destroy(): void {
+        this.#destroyed = true
+        this.#retrier?.stop()
+        this.#clearTimeout()
+    }
+}

package/src/Form.vue

@@ -0,0 +1,78 @@
+<script lang="ts">
+import type { Ref } from 'vue'
+
+export interface FormRefs {
+    dirty?: Ref<boolean>
+    valid?: Ref<boolean>
+}
+</script>
+<script setup lang="ts">
+import { computed, onUnmounted } from 'vue'
+import Form from './Form'
+
+// A <form> whose submit button doubles as the submission status display,
+// walking the Form state machine: dirty → (confirm →) inprogress →
+// success/error → back to rest. The *Text props label the button per state;
+// missing ones fall back to the raw state name (a dev-time default — real
+// consumers pass their own labels).
+const props = defineProps<{
+    savedText?: string
+    successText?: string
+    inprogressText?: string
+    dirtyText?: string
+    invalidText?: string
+    confirmText?: string
+    errorText?: string
+    action?: () => Promise<unknown> | unknown
+    askToConfirm?: boolean
+    refs?: FormRefs
+    // Render an empty button (status conveyed by CSS classes only).
+    noContent?: boolean
+    tryPersistently?: boolean
+    // true/undefined → default success display duration; a number → that many
+    // ms; false → skip the success state entirely.
+    successTimeout?: boolean | number
+}>()
+
+const form = new Form({
+    requireConfirmation: props.askToConfirm,
+    handler: async () => {
+        await props.action?.()
+    },
+    dirty: props.refs?.dirty,
+    valid: props.refs?.valid,
+    successTimeout: props.successTimeout === true ? undefined : props.successTimeout,
+    tryPersistently: props.tryPersistently
+})
+const content = computed(() => {
+    if (form.statusInfo.value) {
+        return form.statusInfo.value
+    }
+    if (props.noContent) {
+        return ''
+    }
+    return props[`${form.state.value}Text` as const] || form.state.value
+})
+const computeCls = (baseCls: string): string => {
+    let str = `${baseCls} ${baseCls}-${form.state.value}`
+    if (form.statusInfo.value) {
+        str += ` ${baseCls}-error`
+    }
+    return str
+}
+const fCls = computed(() => computeCls('form'))
+const bCls = computed(() => computeCls('button'))
+onUnmounted(() => form.destroy())
+const onSubmit = async () => await form.action()
+</script>
+<template>
+    <form :class="fCls" @submit.prevent="onSubmit">
+        <slot />
+        <button type="submit" :class="bCls" :disabled="!form.isActionable.value">{{ content }}</button>
+    </form>
+</template>
+<style scoped lang="scss">
+button[type='submit'] {
+    width: 100%;
+}
+</style>