@redseed/redseed-ui-vue3 8.52.1 → 8.54.0

package/index.js

@@ -25,6 +25,7 @@ export * from './src/components/GridContainer'
 export * from './src/components/HTML'
 export * from './src/components/Icon'
 export * from './src/components/Image'
+export * from './src/components/InlineEditableText'
 export * from './src/components/Layout'
 export * from './src/components/Link'
 export * from './src/components/LinkedList'
@@ -35,6 +36,7 @@ export * from './src/components/MessageBox'
 export * from './src/components/MetaInfo'
 export * from './src/components/Modal'
 export * from './src/components/Pagination'
+export * from './src/components/Pill'
 export * from './src/components/Progress'
 export * from './src/components/Section'
 export * from './src/components/Skeleton'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@redseed/redseed-ui-vue3",
-    "version": "8.52.1",
+    "version": "8.54.0",
     "description": "RedSeed UI Vue 3 components",
     "main": "index.js",
     "repository": "https://github.com/redseedtraining/redseed-ui",

package/src/components/InlineEditableText/InlineEditableText.vue

@@ -0,0 +1,295 @@
+<script setup>
+/**
+ * InlineEditableText — click-to-edit text that edits in place.
+ *
+ *   - Persistence is delegated to the parent via `@save` — the component owns
+ *     the interaction + save-state, the parent owns the request.
+ *   - ALL typography is inherited from context (`font`/`color`/`line-height`),
+ *     so it renders as a page heading in one place and a card title in another
+ *     with zero per-consumer config.
+ *   - Icons come in through slots, so the component has no icon dependency.
+ *
+ * SAVE CONTRACT — `@save` is called as
+ * `save(value, { onSuccess, onError, onFinish })` and the parent MUST call
+ * `onFinish` when the request settles: it is the ONLY thing that clears the
+ * saving state and makes the field editable again, so a parent that forgets it
+ * wedges the field (permanent spinner, no re-edit). In development a
+ * `console.warn` fires if `onFinish` hasn't run a few seconds after a save
+ * begins. `onSuccess` confirms the write — the component only then emits
+ * `update:modelValue`, so the bound value never holds an unsaved edit. `onError`
+ * reopens the editor with the typed value preserved for retry, and the parent
+ * can surface a failure message through the optional `#error` slot (rendered in
+ * an assertive live region).
+ *
+ * Structural styles live in `@redseed/redseed-ui-tailwindcss`
+ * (`components/inline_editable_text.css`, `rsui-inline-editable-text` BEM). The
+ * component deliberately sets no typography/colour — those are inherited.
+ *
+ * @example
+ *   <InlineEditableText
+ *       v-model="title"
+ *       :editable="canEdit"
+ *       placeholder="Untitled"
+ *       ariaLabel="Edit title"
+ *       @save="(value, callbacks) =>
+ *           router.put(url, { title: value }, { preserveScroll: true, ...callbacks })"
+ *   >
+ *       <template #edit-affordance><PencilSquareIcon /></template>
+ *       <template #saving><SpinnerIcon /></template>
+ *       <template #saved><CheckIcon /></template>
+ *       <template #error>{{ form.errors.title }}</template>
+ *   </InlineEditableText>
+ */
+import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
+
+const props = defineProps({
+    modelValue: {
+        type: String,
+        default: '',
+    },
+    // When false the text is read-only: no click-to-edit, no affordance.
+    editable: {
+        type: Boolean,
+        default: true,
+    },
+    placeholder: {
+        type: String,
+        default: '',
+    },
+    ariaLabel: {
+        type: String,
+        default: 'Edit',
+    },
+    // Display-only decoration (e.g. a completed item) — never affects editing.
+    strikethrough: {
+        type: Boolean,
+        default: false,
+    },
+})
+
+const emit = defineEmits(['update:modelValue', 'save'])
+
+const isEditing = ref(false)
+
+const isSaving = ref(false)
+
+const isSaved = ref(false)
+
+// Local buffer while editing, so Escape can revert and an onError reopen keeps
+// the typed value on screen. The bound value only changes on a confirmed save
+// (see commit's onSuccess), so it stays untouched while editing, saving, or
+// after a failure — which is what lets a same-value retry re-fire the save.
+const draft = ref(props.modelValue)
+
+const inputRef = ref(null)
+
+// Id of the 1500ms "saved tick" timer and the dev-only save watchdog, tracked
+// so they can be cleared before a re-arm and on unmount (RSUI cleanup idiom —
+// see Tooltip / CardGroup).
+let savedTimeoutId = null
+
+let saveWatchdogId = null
+
+// Idle-and-editable — the only state a click opens the editor from. While a save
+// is settling (spinner/tick) the text isn't re-openable, so rapid clicks can't
+// stack saves.
+const canEnterEdit = computed(() => props.editable && !isSaving.value && !isSaved.value)
+
+// Show the optimistic draft while saving so the typed value stays on screen
+// through the round-trip; otherwise the committed value.
+const displayValue = computed(() => (isSaving.value ? draft.value : props.modelValue))
+
+// Collapse whitespace runs + trim — a sensible default for a title-like field so
+// stored values stay clean. Parents can normalise further in their save handler.
+function normalise(value) {
+    return value.replace(/\s+/g, ' ').trim()
+}
+
+function startEditing() {
+    if (!canEnterEdit.value) {
+        return
+    }
+
+    draft.value = props.modelValue
+    isEditing.value = true
+}
+
+// Focus + select-all whenever the editor opens (first open and onError reopen)
+// so a single click lets the user type over the value immediately.
+watch(isEditing, (editing) => {
+    if (editing) {
+        nextTick(() => inputRef.value?.select())
+    }
+})
+
+// A permission revocation mid-edit (editable flips to false) must not be
+// ignored: close the open editor and revert to the bound value.
+watch(() => props.editable, (editable) => {
+    if (!editable && isEditing.value) {
+        cancel()
+    }
+})
+
+// Dev-only backstop for the mandatory onFinish contract. The saving state is
+// cleared solely by the parent's onFinish, so a forgetful parent wedges the
+// field. Rather than a production watchdog that would fight legitimately slow
+// saves, mirror ButtonSlot's dev-mode warning idiom and surface the contract
+// violation in development only.
+function startSaveWatchdog() {
+    if (process.env.NODE_ENV === 'production') {
+        return
+    }
+
+    clearSaveWatchdog()
+    saveWatchdogId = window.setTimeout(() => {
+        console.warn('[RSUI] InlineEditableText: a save has not called onFinish. The @save(value, { onSuccess, onError, onFinish }) contract requires onFinish to clear the saving state.')
+    }, 5000)
+}
+
+function clearSaveWatchdog() {
+    clearTimeout(saveWatchdogId)
+    saveWatchdogId = null
+}
+
+function commit() {
+    // Re-entrancy guard: pressing Enter commits and closes the editor, and the
+    // browser then fires `blur` as the focused textarea unmounts — which would
+    // re-invoke commit() and emit a second `save` (a duplicate PUT). Once the
+    // editor is closed, a commit is a no-op.
+    if (!isEditing.value) {
+        return
+    }
+
+    const value = normalise(draft.value)
+
+    // No-op when nothing changed — opening then leaving must not fire a save.
+    if (value === props.modelValue) {
+        isEditing.value = false
+        return
+    }
+
+    // Close immediately so the display (showing the draft) carries the spinner
+    // then tick; the parent drives these via the callbacks below.
+    isEditing.value = false
+    isSaving.value = true
+    startSaveWatchdog()
+    emit('save', value, {
+        onSuccess: () => {
+            // Emit the new bound value ONLY on a confirmed write. Emitting
+            // optimistically at commit would leave the parent bound to an
+            // unsaved value after a failure, so a same-value retry would hit the
+            // no-op guard above and silently drop the edit. `value` is captured
+            // in this closure, so no separate optimistic emit is needed.
+            emit('update:modelValue', value)
+            isSaved.value = true
+            clearTimeout(savedTimeoutId)
+            savedTimeoutId = window.setTimeout(() => { isSaved.value = false }, 1500)
+        },
+        onError: () => {
+            // Reopen so the typed value survives (rather than silently
+            // reverting) and the user can retry. The bound value was never
+            // updated, so re-committing the same text fires a fresh save. The
+            // parent can surface the reason via the #error slot.
+            draft.value = value
+            isEditing.value = true
+        },
+        onFinish: () => {
+            clearSaveWatchdog()
+            isSaving.value = false
+        },
+    })
+}
+
+function cancel() {
+    draft.value = props.modelValue
+    isEditing.value = false
+}
+
+onBeforeUnmount(() => {
+    clearTimeout(savedTimeoutId)
+    clearSaveWatchdog()
+})
+</script>
+
+<template>
+    <!-- Collapsed control. When editable it is exposed as a real interactive
+         control for keyboard + screen-reader users: role="button" + tabindex +
+         Enter/Space + aria-label. A span (not a native <button>) is used
+         deliberately — the component MUST keep flowing inline and inheriting
+         typography, which a <button> would reset/box; this is the documented
+         RSUI fallback for that constraint. Attributes are gated on canEnterEdit
+         so a read-only or mid-save field is inert (no focus, no role). -->
+    <span
+        v-if="!isEditing"
+        class="rsui-inline-editable-text"
+        :class="{ 'rsui-inline-editable-text--editable': canEnterEdit }"
+        :role="canEnterEdit ? 'button' : undefined"
+        :tabindex="canEnterEdit ? 0 : undefined"
+        :aria-label="canEnterEdit ? ariaLabel : undefined"
+        @click="startEditing"
+        @keydown.enter.prevent="startEditing"
+        @keydown.space.prevent="startEditing"
+    >
+        <span
+            class="rsui-inline-editable-text__value"
+            :class="{ 'rsui-inline-editable-text__value--placeholder': !displayValue }"
+        ><s v-if="strikethrough">{{ displayValue || placeholder }}</s><template v-if="!strikethrough">{{ displayValue || placeholder }}</template></span>
+
+        <!-- Reserved-width adornment (min-width floor) so the affordance/spinner/
+             tick swapping never shifts the text. The three states are mutually
+             exclusive; each branch carries its own explicit condition (no
+             v-else) per house style. -->
+        <span
+            class="rsui-inline-editable-text__adornment"
+            aria-hidden="true"
+        >
+            <span v-if="isSaving">
+                <slot name="saving" />
+            </span>
+
+            <span v-if="!isSaving && isSaved">
+                <slot name="saved" />
+            </span>
+
+            <span
+                v-if="!isSaving && !isSaved && canEnterEdit"
+                class="rsui-inline-editable-text__affordance"
+            >
+                <slot name="edit-affordance" />
+            </span>
+        </span>
+    </span>
+
+    <!-- Auto-grow: an inline-grid sizer whose hidden ::after mirror carries the
+         value drives the width; the textarea fills the same cell. -->
+    <span
+        v-if="isEditing"
+        class="rsui-inline-editable-text__sizer"
+        :data-value="draft || placeholder"
+    >
+        <textarea
+            ref="inputRef"
+            v-model="draft"
+            rows="1"
+            :placeholder="placeholder"
+            :aria-label="ariaLabel"
+            class="rsui-inline-editable-text__input"
+            @blur="commit"
+            @keydown.enter.prevent="commit"
+            @keydown.esc.prevent="cancel"
+        ></textarea>
+    </span>
+
+    <!-- Optional parent-surfaced failure message (e.g. set in @save's onError,
+         cleared on success). Rendered only when the parent populates the slot,
+         in an assertive live region so screen-reader users get the failure that
+         the aria-hidden adornment can't convey. Mirrors the RSUI form-field
+         error pattern (FormFieldSlot). -->
+    <span
+        v-if="$slots.error"
+        class="rsui-inline-editable-text__error"
+        role="alert"
+    >
+        <slot name="error" />
+    </span>
+</template>

package/src/components/InlineEditableText/index.js

@@ -0,0 +1,5 @@
+import InlineEditableText from './InlineEditableText.vue'
+
+export {
+    InlineEditableText,
+}

package/src/components/Pill/Pill.vue

@@ -0,0 +1,103 @@
+<script setup>
+import { ref, computed, onMounted, watchEffect } from 'vue'
+
+const props = defineProps({
+    selected: {
+        type: Boolean,
+        default: false,
+    },
+    disabled: {
+        type: Boolean,
+        default: false,
+    },
+    // The name of a RUNTIME CSS custom property to use as the accent — applied as
+    // `var(--<color>, <neutral>)`, driving the icon-badge fill and the selected
+    // ring/tint. Pass a real runtime theme variable, e.g. the consuming app's
+    // palette (`color7` → `var(--color7)`). NOTE: RSUI's own Tailwind `@theme`
+    // color tokens (e.g. `--color-brand-500`) are inlined into utilities, not
+    // exposed as runtime vars, so they will NOT resolve here. An UNRESOLVABLE
+    // (undefined) token degrades to a neutral grey rather than an invisible pill;
+    // a token that *resolves* to `transparent`/empty is not caught — passing a
+    // real colour is the consumer's responsibility. Optional — falls back to a
+    // neutral accent when omitted, so RSUI stays theme-agnostic.
+    color: {
+        type: String,
+        default: '',
+    },
+})
+
+const emit = defineEmits(['click'])
+
+// The single accent token colours both the icon badge and the selected
+// treatment. When no color is supplied we leave the property unset so the CSS
+// neutral fallback applies. When a color IS supplied it carries an inline
+// fallback to the neutral grey, so an UNRESOLVABLE (undefined) token degrades to
+// grey rather than an invisible badge/selection. Note: var()'s fallback does not
+// fire for a token that *resolves* to transparent/empty — passing a real colour
+// is the consumer's responsibility.
+const accentStyle = computed(() =>
+    props.color
+        ? { '--rsui-pill-accent': `var(--${props.color}, var(--Colors-Grey-500))` }
+        : {},
+)
+
+const pillClass = computed(() => [
+    'rsui-pill',
+    {
+        'rsui-pill--selected': props.selected && !props.disabled,
+        'rsui-pill--disabled': props.disabled,
+    },
+])
+
+function handleClick(event) {
+    // Guarded — a disabled pill emits nothing even if a click reaches it.
+    if (props.disabled) return
+
+    emit('click', event)
+}
+
+// button element ref, used for the icon-only accessibility check
+const pillElementRef = ref(null)
+
+// an icon-only pill has no visible label text
+const iconOnly = computed(
+    () => pillElementRef.value && !pillElementRef.value.textContent.trim(),
+)
+
+// warn in development when an icon-only pill lacks an accessible name
+onMounted(() => {
+    watchEffect(() => {
+        if (
+            process.env.NODE_ENV !== 'production' &&
+            iconOnly.value &&
+            !pillElementRef.value.getAttribute('aria-label') &&
+            !pillElementRef.value.getAttribute('aria-labelledby')
+        ) {
+            console.warn(
+                '[RSUI] Icon-only Pill detected without aria-label. Add aria-label for accessibility.',
+            )
+        }
+    })
+})
+
+defineExpose({
+    pillElementRef,
+})
+</script>
+<template>
+<button
+    ref="pillElementRef"
+    :class="pillClass"
+    :style="accentStyle"
+    :disabled="props.disabled"
+    :aria-pressed="props.selected && !props.disabled"
+    type="button"
+    @click="handleClick"
+>
+    <span v-if="$slots.icon" class="rsui-pill__icon" aria-hidden="true">
+        <slot name="icon"></slot>
+    </span>
+
+    <slot></slot>
+</button>
+</template>

package/src/components/Pill/index.js

@@ -0,0 +1,5 @@
+import Pill from './Pill.vue'
+
+export {
+    Pill,
+}