@greendrake/ui-data 0.1.0

package/src/MasterDetail.vue

@@ -0,0 +1,191 @@
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import { TabBar, type TabDef } from '@greendrake/ui'
+
+const props = withDefaults(
+    defineProps<{
+        initialWidth?: number
+        minWidth?: number
+        fullWidthUntilTab?: boolean
+    }>(),
+    {
+        initialWidth: 150,
+        minWidth: 100,
+        fullWidthUntilTab: false
+    }
+)
+
+const emit = defineEmits<{
+    'tab-open': [tab: TabDef]
+    'tab-close': [tab: TabDef]
+    'tab-activate': [tab: TabDef]
+}>()
+
+const tabs = ref<TabDef[]>([])
+const activeTabId = ref<string | null>(null)
+const masterWidth = ref(props.initialWidth)
+
+const activeTab = computed(() => tabs.value.find(t => t.id === activeTabId.value) ?? null)
+
+const hasTabs = computed(() => tabs.value.length > 0)
+
+const masterStyle = computed(() => {
+    if (props.fullWidthUntilTab && !hasTabs.value) {
+        return { flex: '1 1 0', width: 0 }
+    }
+    return { width: masterWidth.value + 'px' }
+})
+
+function openTab(id: string, label?: string): void {
+    let tab = tabs.value.find(t => t.id === id)
+    if (!tab) {
+        tab = { id, label: label ?? id }
+        tabs.value.push(tab)
+        emit('tab-open', tab)
+    }
+    activeTabId.value = id
+    emit('tab-activate', tab)
+}
+
+function closeTab(id: string): void {
+    const index = tabs.value.findIndex(t => t.id === id)
+    if (index === -1) return
+
+    const tab = tabs.value[index]
+    tabs.value.splice(index, 1)
+    emit('tab-close', tab)
+
+    if (activeTabId.value === id) {
+        activeTabId.value = tabs.value[Math.min(index, tabs.value.length - 1)]?.id ?? null
+        if (activeTabId.value) {
+            emit('tab-activate', tabs.value.find(t => t.id === activeTabId.value)!)
+        }
+    }
+}
+
+function activateTab(id: string): void {
+    const tab = tabs.value.find(t => t.id === id)
+    if (tab) {
+        activeTabId.value = id
+        emit('tab-activate', tab)
+    }
+}
+
+function updateTab(id: string, newId?: string, newLabel?: string): void {
+    const tab = tabs.value.find(t => t.id === id)
+    if (!tab) return
+    if (newLabel !== undefined) tab.label = newLabel
+    if (newId !== undefined && newId !== id) {
+        tab.id = newId
+        if (activeTabId.value === id) activeTabId.value = newId
+    }
+}
+
+function onResizeStart(e: MouseEvent): void {
+    const startX = e.clientX
+    const startWidth = masterWidth.value
+
+    function onMouseMove(e: MouseEvent): void {
+        masterWidth.value = Math.max(props.minWidth, startWidth + e.clientX - startX)
+    }
+
+    function onMouseUp(): void {
+        document.removeEventListener('mousemove', onMouseMove)
+        document.removeEventListener('mouseup', onMouseUp)
+    }
+
+    document.addEventListener('mousemove', onMouseMove)
+    document.addEventListener('mouseup', onMouseUp)
+}
+
+defineExpose({
+    openTab,
+    closeTab,
+    activateTab,
+    updateTab,
+    tabs,
+    activeTab,
+    activeTabId
+})
+</script>
+<template>
+    <div class="MasterDetail">
+        <div class="MasterDetail__master" :style="masterStyle">
+            <slot name="master" :open-tab="openTab"></slot>
+        </div>
+        <template v-if="hasTabs || !fullWidthUntilTab">
+            <div class="MasterDetail__resize" @mousedown="onResizeStart"></div>
+            <div class="MasterDetail__detail">
+                <TabBar :tabs="tabs" :model-value="activeTabId" closable @update:model-value="activateTab" @close="closeTab" />
+                <div class="MasterDetail__content">
+                    <template v-for="tab in tabs" :key="tab.id">
+                        <div v-show="tab.id === activeTabId" class="MasterDetail__pane">
+                            <slot name="detail" :tab="tab" :is-active="tab.id === activeTabId"></slot>
+                        </div>
+                    </template>
+                </div>
+            </div>
+        </template>
+    </div>
+</template>
+<style lang="scss">
+.MasterDetail {
+    display: flex;
+    min-width: 0;
+    // Flex item in a column parent: without this the automatic min-height (auto)
+    // keeps it as tall as its content, so it overgrows the viewport and the
+    // master's overflow:auto has nothing to scroll within.
+    min-height: 0;
+
+    &__master {
+        flex-shrink: 0;
+        min-width: v-bind('minWidth + "px"');
+        overflow: auto;
+        display: flex;
+        flex-direction: column;
+
+        > * {
+            flex-grow: 1;
+            min-height: 0;
+        }
+    }
+
+    &__resize {
+        width: 4px;
+        flex-shrink: 0;
+        cursor: col-resize;
+        background-color: var(--border-color-light);
+        &:hover {
+            background-color: var(--accent-color);
+        }
+    }
+
+    &__detail {
+        flex-grow: 1;
+        min-width: 0;
+        min-height: 0;
+        overflow: hidden;
+        display: flex;
+        flex-direction: column;
+    }
+
+    &__content {
+        flex-grow: 1;
+        min-height: 0;
+        min-width: 0;
+        display: flex;
+    }
+
+    &__pane {
+        flex-grow: 1;
+        display: flex;
+        min-height: 0;
+        min-width: 0;
+
+        > * {
+            flex-grow: 1;
+            min-width: 0;
+        }
+    }
+}
+</style>

package/src/errorMessage.ts

@@ -0,0 +1,2 @@
+/** Human-readable message from a caught value, for local (non-toast) error display. */
+export const errorMessage = (e: unknown): string => (e instanceof Error ? e.message : String(e))

package/src/formatters.ts

@@ -0,0 +1,25 @@
+// Wire timestamps drift between carrying an explicit zone ('Z' or ±hh:mm) and
+// omitting it. JavaScript parses a zoneless date-time string as LOCAL time, so
+// a missing zone is normalized to UTC before parsing. Output is always
+// 'YYYY-MM-DD HH:MM:SSZ' — the value IS UTC and the suffix says so.
+const HAS_ZONE = /(?:Z|[+-]\d{2}:?\d{2})$/i
+
+export const fmtDate = (v: unknown): string => {
+    if (v == null || v === '') return ''
+    let d: Date
+    if (typeof v === 'string') {
+        const iso = v.replace(' ', 'T')
+        d = new Date(iso.includes('T') && !HAS_ZONE.test(iso) ? iso + 'Z' : iso)
+    } else if (typeof v === 'number' || v instanceof Date) {
+        d = new Date(v)
+    } else {
+        throw new TypeError(`fmtDate: unsupported value of type ${typeof v}`)
+    }
+    return d.toISOString().replace('T', ' ').slice(0, 19) + 'Z'
+}
+
+/** Table-cell boolean: a tick for true, blank for false. */
+export const fmtBool = (v: unknown): string => (v ? '✓' : '')
+
+/** Prose boolean for detail views. */
+export const fmtYesNo = (v: unknown): string => (v ? 'yes' : 'no')

package/src/listLoader.ts

@@ -0,0 +1,31 @@
+import type { Ref } from 'vue'
+import type { LoaderParams, LoaderResponse } from './InfiniteScrollTable.types'
+import type { SortState } from './useSortState'
+
+// The standard admin list-method argument shape (q, limit, offset, sort_by,
+// sort_dir) — the wire counterpart of LoaderParams + SortState.
+export type PageArgs = {
+    q?: string
+    offset?: number
+    limit?: number
+    sort_by?: string
+    sort_dir?: string
+}
+
+// Adapts InfiniteScrollTable's LoaderParams to the admin list-method argument
+// shape. Passing `sort` includes the search box's `q` and the sort filters —
+// exactly the methods with server-side search/sort support; the rest get the
+// bare offset/limit window. Extra filter fields ride the `fetch` closure, and
+// so does what a background read costs — the flag is handed on verbatim:
+//     listLoader((args, background) => api.call('admin.thread.list', [{ ...args, type }], backgroundCall(background)))
+export const listLoader =
+    <T>(fetch: (args: PageArgs, background: boolean) => Promise<LoaderResponse<T>>, sort?: SortState) =>
+    (params: LoaderParams, _loading: Ref<boolean>, background: boolean): Promise<LoaderResponse<T>> =>
+        fetch(
+            {
+                offset: params.offset,
+                limit: params.limit,
+                ...(sort ? { q: typeof params.q === 'string' ? params.q : undefined, ...sort.sortFilters.value } : {})
+            },
+            background
+        )

package/src/localFilterDebounce.ts

@@ -0,0 +1,21 @@
+import type { Ref } from 'vue'
+
+// A SearchField filtering an InfiniteScrollTable should react swiftly when the
+// table can satisfy the change from its in-memory set (no API call), but coalesce
+// keystrokes when the change triggers a remote fetch. These are the two delays.
+const LOCAL_MS = 250
+const REMOTE_MS = 600
+
+// The slice of an InfiniteScrollTable's exposed surface this helper needs: its
+// own answer to whether a prospective text filter resolves locally.
+export interface LocalFilterable {
+    willFilterLocally(value: string | undefined): boolean
+}
+
+// Builds SearchField's per-keystroke `debounce` resolver from the table's template
+// ref. Before the table mounts (ref still empty), and whenever the table reports it
+// can't serve the change locally, it yields the longer remote delay.
+export const localFilterDebounce =
+    <T extends LocalFilterable>(table: Ref<T | undefined>) =>
+    (value: string | undefined): number =>
+        table.value?.willFilterLocally(value) ? LOCAL_MS : REMOTE_MS

package/src/main.ts

@@ -0,0 +1,15 @@
+export { default as InfiniteScrollTable } from './InfiniteScrollTable.vue'
+export type { ColumnDefinition, LoaderParams, LoaderResponse, LoaderFunction, Filters, RowKey, DropTarget, RowPosition, VisibleRange, InfiniteScrollTableExposed } from './InfiniteScrollTable.types'
+export { localFilterDebounce, type LocalFilterable } from './localFilterDebounce'
+export { default as MasterDetail } from './MasterDetail.vue'
+export { default as CrudPanel } from './CrudPanel.vue'
+export type { CrudPanelExposed } from './CrudPanel.vue'
+export { default as useRecordEditor, type RecordEditor, type RecordEditorOptions } from './useRecordEditor'
+export { useSortState, type SortState, type SortDir, type ColumnOptions } from './useSortState'
+export { listLoader, type PageArgs } from './listLoader'
+export { fmtDate, fmtBool, fmtYesNo } from './formatters'
+export { useDetailLoader, type DetailLoader } from './useDetailLoader'
+export { useAsyncAction, type AsyncAction } from './useAsyncAction'
+export { errorMessage } from './errorMessage'
+export { default as DescriptionList } from './DescriptionList.vue'
+export type { DescriptionItem } from './DescriptionList.vue'

package/src/useAsyncAction.ts

@@ -0,0 +1,47 @@
+import { ref, type Ref } from 'vue'
+import { errorMessage } from './errorMessage'
+
+export interface AsyncAction<Args extends unknown[]> {
+    /** True while the action runs; `run` is re-entry-guarded on it. */
+    acting: Ref<boolean>
+    error: Ref<string | null>
+    /** Success notice — the string the action resolved to, if any. */
+    notice: Ref<string | null>
+    run: (...args: Args) => Promise<void>
+}
+
+/**
+ * In-flight/error/notice bookkeeping around an async action — the repeated
+ * action-button skeleton. `run` ignores re-entry while acting, clears
+ * error/notice, and captures a rejection's message locally (no global
+ * handling), so pass a silent api call inside `fn`. When `fn` resolves to a
+ * string, that string becomes the success notice. Buttons that share one
+ * in-flight state parameterise `fn` and pass the variant to `run`.
+ */
+export const useAsyncAction = <Args extends unknown[]>(fn: (...args: Args) => Promise<string | void>): AsyncAction<Args> => {
+    const acting = ref(false)
+    const error = ref<string | null>(null)
+    const notice = ref<string | null>(null)
+
+    const run = async (...args: Args): Promise<void> => {
+        if (acting.value) return
+        acting.value = true
+        error.value = null
+        notice.value = null
+        try {
+            const result = await fn(...args)
+            if (typeof result === 'string') notice.value = result
+        } catch (e) {
+            error.value = errorMessage(e)
+        } finally {
+            acting.value = false
+        }
+    }
+
+    return {
+        acting,
+        error,
+        notice,
+        run
+    }
+}

package/src/useDetailLoader.ts

@@ -0,0 +1,57 @@
+import { ref, watch, toValue, type Ref, type WatchSource } from 'vue'
+import { errorMessage } from './errorMessage'
+
+export interface DetailLoader<T> {
+    data: Ref<T | null>
+    loading: Ref<boolean>
+    error: Ref<string | null>
+    reload: () => Promise<void>
+    // Patch the loaded value in place (a no-op before the first load). Lets a
+    // caller fold a known local change — an appended item, a status flip — into
+    // the pane without a full re-fetch, while the loader stays the sole writer.
+    mutate: (fn: (cur: T) => void) => void
+}
+
+/**
+ * The detail-pane fetch skeleton: load on mount, re-load whenever the id
+ * changes, expose data/loading/error. Error handling stays local — the
+ * fetcher's rejection message lands in the `error` ref for in-pane display,
+ * never in a global toast — so pass a silent api call as the fetcher.
+ * Responses that arrive after the id has moved on are discarded.
+ */
+export const useDetailLoader = <T, Id>(id: WatchSource<Id>, fetcher: (id: Id) => Promise<T>): DetailLoader<T> => {
+    const data = ref(null) as Ref<T | null>
+    const loading = ref(false)
+    const error = ref<string | null>(null)
+    let seq = 0
+
+    const reload = async (): Promise<void> => {
+        const token = ++seq
+        loading.value = true
+        error.value = null
+        try {
+            const result = await fetcher(toValue(id))
+            if (token !== seq) return
+            data.value = result
+        } catch (e) {
+            if (token !== seq) return
+            error.value = errorMessage(e)
+        } finally {
+            if (token === seq) loading.value = false
+        }
+    }
+
+    const mutate = (fn: (cur: T) => void): void => {
+        if (data.value !== null) fn(data.value)
+    }
+
+    watch(id, reload, { immediate: true })
+
+    return {
+        data,
+        loading,
+        error,
+        reload,
+        mutate
+    }
+}

package/src/useRecordEditor.ts

@@ -0,0 +1,148 @@
+import { reactive, computed, ref, type Ref, type ComputedRef } from 'vue'
+
+/**
+ * Record-edit pattern for CRUD detail editors.
+ *
+ * Convention (matches what CrudPanel and patchRow expect):
+ *
+ *   1. The detail editor receives the full record it's editing (loaded by the
+ *      caller from a list row, an API call, etc.).
+ *   2. It keeps two parallel objects:
+ *        - `data`     — the canonical state acknowledged by the backend.
+ *        - `workData` — a reactive working copy bound to inputs.
+ *   3. On save, only fields that differ between `workData` and `data` are
+ *      sent. Sending the entire record on every save is wasteful and risks
+ *      clobbering server-side changes to fields the user didn't touch.
+ *   4. The `save(patch)` callback returns the FULL updated record. The
+ *      backend may modify fields beyond what the user changed (timestamps,
+ *      derived fields, server-side defaults); the editor must acknowledge
+ *      those by overwriting its local state with the response. This makes
+ *      the next diff correct and surfaces server changes in the UI.
+ *   5. The caller wires `('saved', key, record)` → `CrudPanel.applySaved(key,
+ *      record, tab.id)` to update the row in place — no list re-fetch.
+ *
+ * Field shapes supported: strings, numbers, booleans, arrays, plain objects.
+ * Equality is by canonical JSON — sufficient for typical CRUD payloads.
+ *
+ * What this composable does NOT do:
+ *   - HTTP. The caller supplies `save(patch)`.
+ *   - Validation. Caller-side concern; gate `submit()` behind your own checks.
+ *   - File uploads, multi-step save flows. Build those around `changes` /
+ *     `data` / `workData` and call `applyResponse(updated)` manually instead
+ *     of `submit()` for those cases.
+ */
+export interface RecordEditor<T extends Record<keyof T & string, unknown>> {
+    /** Canonical state acknowledged by the backend. Mutates after each save. */
+    data: T
+    /** Reactive working copy bound to inputs. Edit this freely. */
+    workData: T
+    /** Diff of workData vs data, or null when nothing has changed. */
+    changes: ComputedRef<Partial<T> | null>
+    /** True when there are unsaved changes. */
+    dirty: ComputedRef<boolean>
+    /** True while a `submit()` call is in flight. */
+    saving: Ref<boolean>
+    /**
+     * Send the current diff via `save(patch)`, then assign the response onto
+     * both `data` and `workData`. No-op (returns null) when not dirty.
+     */
+    submit: () => Promise<T | null>
+    /** Discard local edits, reverting workData to data. */
+    reset: () => void
+    /**
+     * Manually acknowledge a server-side update (useful when the save flow
+     * is custom — e.g. file uploads — and `submit()` isn't called).
+     */
+    applyResponse: (updated: T) => void
+}
+
+export interface RecordEditorOptions<T extends Record<keyof T & string, unknown>> {
+    /** Initial record snapshot. Deep-cloned into both data and workData. */
+    initial: T
+    /** Sends the diff to the backend; must resolve to the full updated record. */
+    save: (patch: Partial<T>) => Promise<T>
+    /**
+     * Restrict which keys are considered editable / diffed. Defaults to the
+     * keys present on `initial`. Useful when the record contains read-only
+     * fields (e.g. id, created_at) that should never be sent in a patch.
+     */
+    fields?: readonly (keyof T)[]
+    /**
+     * Canonicalise a record before it enters the editor — applied to `initial`
+     * and to every save response. Use it to collapse irrelevant wire
+     * differences (`undefined` vs `null`, absent vs empty string) so the diff
+     * doesn't oscillate on them.
+     */
+    normalise?: (record: T) => T
+}
+
+export default function useRecordEditor<T extends Record<keyof T & string, unknown>>(options: RecordEditorOptions<T>): RecordEditor<T> {
+    const fields = (options.fields ?? Object.keys(options.initial)) as (keyof T)[]
+    const normalise = options.normalise ?? ((record: T): T => record)
+    const pick = (src: T): T => {
+        const out = {} as T
+        for (const k of fields) out[k] = src[k]
+        return out
+    }
+
+    // JSON clone — matches the diff equality function below and handles Vue
+    // proxies (structuredClone chokes on them) without an extra `toRaw` step.
+    const clone = <V>(v: V): V => JSON.parse(JSON.stringify(v)) as V
+    const initial = normalise(clone(options.initial))
+    const data = reactive(initial) as T
+    const workData = reactive(clone(pick(initial))) as T
+    const saving = ref(false)
+
+    const changes = computed<Partial<T> | null>(() => {
+        const diff: Partial<T> = {}
+        let any = false
+        for (const k of fields) {
+            if (!equal(workData[k], data[k])) {
+                diff[k] = workData[k]
+                any = true
+            }
+        }
+        return any ? diff : null
+    })
+
+    const dirty = computed(() => changes.value !== null)
+
+    function applyResponse(updated: T): void {
+        const normalised = normalise(updated)
+        Object.assign(data, normalised)
+        Object.assign(workData, pick(normalised))
+    }
+
+    async function submit(): Promise<T | null> {
+        const patch = changes.value
+        if (!patch) return null
+        saving.value = true
+        try {
+            const updated = await options.save(patch)
+            applyResponse(updated)
+            return updated
+        } finally {
+            saving.value = false
+        }
+    }
+
+    function reset(): void {
+        Object.assign(workData, pick(data))
+    }
+
+    return {
+        data,
+        workData,
+        changes,
+        dirty,
+        saving,
+        submit,
+        reset,
+        applyResponse
+    }
+}
+
+function equal(a: unknown, b: unknown): boolean {
+    if (a === b) return true
+    return JSON.stringify(a) === JSON.stringify(b)
+}

package/src/useSortState.ts

@@ -0,0 +1,67 @@
+import { ref, computed, type Ref, type ComputedRef } from 'vue'
+import type { ColumnDefinition } from './InfiniteScrollTable.types'
+
+export type SortDir = 'asc' | 'desc'
+
+export type ColumnOptions<T = Record<string, unknown>> = Omit<ColumnDefinition<T>, 'field' | 'label' | 'sortable' | 'sortIcon' | 'onHeaderClick'> & {
+    /**
+     * Sort field sent to the backend when it differs from `field`
+     * (e.g. field 'asking_price' sorting by 'price'); `false` makes the
+     * column unsortable. Defaults to `field`.
+     */
+    sortKey?: string | false
+}
+
+export interface SortState {
+    sortBy: Ref<string>
+    sortDir: Ref<SortDir>
+    /** Same field flips direction; a new field takes over with its default direction. */
+    toggleSort: (field: string) => void
+    sortIcon: (field: string) => string | undefined
+    /** `{ sort_by, sort_dir }` in the wire shape InfiniteScrollTable filters / LoaderParams carry. */
+    sortFilters: ComputedRef<{ sort_by: string; sort_dir: SortDir }>
+    /**
+     * ColumnDefinition factory wired to this sort state (header click toggles,
+     * icon reflects). Build the columns array inside a `computed` so the icons
+     * track state changes.
+     */
+    column: <T = Record<string, unknown>>(field: string, label: string, options?: ColumnOptions<T>) => ColumnDefinition<T>
+}
+
+export const useSortState = (initialBy: string, initialDir: SortDir = 'desc', defaultDir: SortDir | ((field: string) => SortDir) = 'asc'): SortState => {
+    const sortBy = ref(initialBy)
+    const sortDir = ref<SortDir>(initialDir)
+
+    const toggleSort = (field: string): void => {
+        if (sortBy.value === field) {
+            sortDir.value = sortDir.value === 'asc' ? 'desc' : 'asc'
+        } else {
+            sortBy.value = field
+            sortDir.value = typeof defaultDir === 'function' ? defaultDir(field) : defaultDir
+        }
+    }
+
+    const sortIcon = (field: string): string | undefined => (sortBy.value === field ? (sortDir.value === 'asc' ? '▲' : '▼') : undefined)
+
+    const sortFilters = computed(() => ({ sort_by: sortBy.value, sort_dir: sortDir.value }))
+
+    const column = <T = Record<string, unknown>>(field: string, label: string, options: ColumnOptions<T> = {}): ColumnDefinition<T> => {
+        const { sortKey = field, ...rest } = options
+        return {
+            field,
+            label,
+            sortable: sortKey !== false,
+            ...(sortKey === false ? {} : { onHeaderClick: () => toggleSort(sortKey), sortIcon: sortIcon(sortKey) }),
+            ...rest
+        }
+    }
+
+    return {
+        sortBy,
+        sortDir,
+        toggleSort,
+        sortIcon,
+        sortFilters,
+        column
+    }
+}