frappe-ui 1.0.0-beta.2 → 1.0.0-beta.21

package/src/components/Duration/Duration.md

@@ -0,0 +1,98 @@
+# Duration
+
+A text input for entering a length of time. The caller works in **seconds** (via
+`v-model`); the user types a human-readable duration in any common notation and
+the component parses it on commit.
+
+## Playground
+
+<ClientOnly><DurationBuilder /></ClientOnly>
+
+<ComponentPreview name="Duration-Default" layout="stacked" />
+
+## Example
+
+Logging effort against a task: the user enters a duration in any notation and
+the saved seconds roll up into a total.
+
+<ComponentPreview name="Duration-RealWorld" />
+
+## Input notation
+
+The field accepts several notations, case-insensitive, with units in any order.
+Parsing happens when the field is committed (blur or `Enter`):
+
+| Notation     | Example                                | Seconds            |
+| ------------ | -------------------------------------- | ------------------ |
+| Short units  | `1h 30m 45s`, `1h30m45s`, `45s 1h 30m` | `5445`             |
+| Long units   | `1 hour 30 minutes`, `2hrs 15min`      | `5400`, `8100`     |
+| Colon        | `1:30:45`, `1:30`, `:45`               | `5445`, `90`, `45` |
+| Bare integer | `90`                                   | `90`               |
+
+Invalid input keeps the field open with the typed text and an inline error so it
+can be corrected; the saved value is left untouched until a valid commit.
+`Escape` abandons the edit, and clearing the field commits `null`.
+
+## Display format
+
+When the field is not focused, the saved value is rendered using `format`. This
+is either a **named preset** or a **token template string**. The default is the
+`short` preset, which renders `2h 2m 3s` and omits zero parts.
+
+### Presets
+
+Presets are smart — they omit zero components (and `long` pluralizes):
+
+| `format`            | `5445`                         | `90`                  |
+| ------------------- | ------------------------------ | --------------------- |
+| `short` _(default)_ | `1h 30m 45s`                   | `1m 30s`              |
+| `long`              | `1 hour 30 minutes 45 seconds` | `1 minute 30 seconds` |
+| `colon`             | `1:30:45`                      | `1:30`                |
+
+### Token templates
+
+Any other `format` value is a template, rendered literally (no zero-omission).
+`h`/`m`/`s` are unit tokens; double them (`hh`/`mm`/`ss`) to zero-pad to two
+digits. Wrap label text in single quotes so the unit letters render as text.
+
+| `format`         | `7323`     |
+| ---------------- | ---------- |
+| `h'h' m'm' s's'` | `2h 2m 3s` |
+| `hh:mm:ss`       | `02:02:03` |
+| `h':'mm`         | `2:02`     |
+
+Each token renders only its own component — `m` is the minutes-within-the-hour
+(`2`), not the total minutes (`122`). Include every unit you want to keep, or a
+higher unit's value is dropped from the output.
+
+> Editing always switches to the canonical `2h 2m 3s` notation so the typed
+> value round-trips reliably through the parser, whatever the display format.
+
+<ComponentPreview name="Duration-Formats" />
+
+## Sizes
+
+<ComponentPreview name="Duration-Sizes" />
+
+## Labeling
+
+Duration implements the shared input labeling contract (`label`, `description`,
+`error`, `required`), forwarded to the underlying `TextInput`.
+
+<ComponentPreview name="Duration-States" />
+
+## Keyboard
+
+| Keys         | Action                                        |
+| ------------ | --------------------------------------------- |
+| `Enter`      | Commit the typed value                        |
+| `Escape`     | Cancel the edit and revert to the saved value |
+| `Tab` / blur | Commit the typed value                        |
+
+## Customization
+
+Duration renders a `TextInput`, so the same data-attribute styling hooks apply —
+`data-slot="control"`, `data-size`, `data-disabled`, and `data-state="invalid"`
+on error. See TextInput for the full taxonomy.
+
+<!-- @include: ./Duration.api.md -->

package/src/components/Duration/Duration.vue

@@ -0,0 +1,114 @@
+<template>
+  <TextInput
+    ref="inputRef"
+    :id="id"
+    :model-value="displayValue"
+    :label="label"
+    :description="description"
+    :error="error || internalError"
+    :required="required"
+    :disabled="disabled"
+    :size="size"
+    :variant="variant"
+    :placeholder="placeholder"
+    @focus="handleFocus"
+    @blur="handleBlur"
+    @input="handleInput"
+    @keydown="handleKeydown"
+  />
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref } from 'vue'
+import { TextInput } from '../TextInput'
+import { formatDuration, parseDuration } from './duration'
+import type { DurationProps, DurationExposed } from './types'
+
+const props = withDefaults(defineProps<DurationProps>(), {
+  placeholder: '1h 30m 45s',
+  format: 'short',
+})
+
+const model = defineModel<number | null>({ default: null })
+
+const inputRef = ref<{ el: HTMLInputElement | null } | null>(null)
+const isFocused = ref(false)
+const editValue = ref('')
+const internalError = ref('')
+const cancelled = ref(false)
+
+const displayValue = computed(() =>
+  isFocused.value || internalError.value
+    ? editValue.value
+    : formatDuration(model.value, props.format),
+)
+
+function handleFocus() {
+  // Guard against redundant focus events while already editing so we don't
+  // clobber the in-progress text or re-run the select(). After an invalid
+  // commit isFocused is false, so re-focusing starts a fresh canonical edit.
+  if (isFocused.value) return
+  isFocused.value = true
+  // Always edit in the canonical "1h 30m 45s" notation so the typed value
+  // round-trips through parseDuration regardless of the display `format`.
+  editValue.value = formatDuration(model.value, 'short')
+  internalError.value = ''
+  nextTick(() => inputRef.value?.el?.select())
+}
+
+function handleInput(event: Event) {
+  editValue.value = (event.target as HTMLInputElement).value
+  internalError.value = ''
+}
+
+function handleBlur() {
+  // Escape cancels the edit: skip the commit the blur would otherwise trigger
+  // and leave the saved value untouched.
+  if (cancelled.value) {
+    cancelled.value = false
+    isFocused.value = false
+    internalError.value = ''
+    return
+  }
+  commit()
+}
+
+function handleKeydown(event: KeyboardEvent) {
+  if (event.key === 'Enter') {
+    event.preventDefault()
+    inputRef.value?.el?.blur()
+  } else if (event.key === 'Escape') {
+    cancelled.value = true
+    inputRef.value?.el?.blur()
+  }
+}
+
+function commit() {
+  const raw = editValue.value.trim()
+
+  if (raw === '') {
+    internalError.value = ''
+    isFocused.value = false
+    model.value = null
+    return
+  }
+
+  const seconds = parseDuration(raw)
+  if (seconds === null) {
+    internalError.value =
+      'Invalid format. Try: 1h 30m 45s, 1 hour 30 minutes, 1:30:45, 90s'
+    // Report the error and let focus leave. The rejected text stays visible
+    // (displayValue tracks the error state) as a reminder, but they aren't
+    // trapped in the field. Re-focusing restarts from the canonical saved
+    // value, so the rejected text is discarded rather than edited.
+    isFocused.value = false
+    return
+  }
+
+  internalError.value = ''
+  isFocused.value = false
+  model.value = seconds
+}
+
+defineExpose<DurationExposed>({ focus: () => inputRef.value?.el?.focus() })
+</script>

package/src/components/Duration/duration.ts

@@ -0,0 +1,185 @@
+// ---------------------------------------------------------------------------
+// Duration helpers: convert between a seconds value and human-readable text.
+// ---------------------------------------------------------------------------
+
+import type { DurationFormat } from './types'
+
+/**
+ * Format a duration in seconds as text.
+ *
+ * `format` is either a named preset — which applies smart zero-omission and
+ * (for `long`) pluralization — or a token template rendered literally:
+ *
+ *   formatDuration(5445)                    // "1h 30m 45s"   (short preset, default)
+ *   formatDuration(90)                      // "1m 30s"       (preset omits zero parts)
+ *   formatDuration(5445, 'long')            // "1 hour 30 minutes 45 seconds"
+ *   formatDuration(5445, 'colon')           // "1:30:45"
+ *   formatDuration(5445, "h'h' m'm' s's'")  // "1h 30m 45s"   (template, all parts)
+ *   formatDuration(90,   "h'h' m'm' s's'")  // "0h 1m 30s"
+ *   formatDuration(7323, 'hh:mm:ss')        // "02:02:03"
+ */
+export function formatDuration(
+  totalSeconds: number | null | undefined,
+  format: DurationFormat = 'short',
+): string {
+  if (totalSeconds === null || totalSeconds === undefined) return ''
+
+  const seconds = Number(totalSeconds)
+  if (Number.isNaN(seconds)) return ''
+
+  const hours = Math.floor(seconds / 3600)
+  const minutes = Math.floor((seconds % 3600) / 60)
+  const secs = seconds % 60
+
+  if (format === 'short') return formatShort(hours, minutes, secs)
+  if (format === 'long') return formatLong(hours, minutes, secs)
+  if (format === 'colon') return formatColon(hours, minutes, secs)
+  return renderTemplate(format, hours, minutes, secs)
+}
+
+// ---------------------------------------------------------------------------
+// Token template engine.
+//
+// Outside single quotes, runs of h / m / s are unit tokens; a run of length
+// >= 2 zero-pads to two digits (`hh` → "02"). Single-quoted text is emitted
+// literally so the unit letters can appear as labels (`'h'` → "h"); `''` is a
+// literal apostrophe. Any other character passes through unchanged.
+//
+//   "h'h' m'm' s's'" → "1h 30m 45s"
+//   "hh:mm:ss"       → "01:30:45"
+// ---------------------------------------------------------------------------
+function renderTemplate(
+  template: string,
+  hours: number,
+  minutes: number,
+  secs: number,
+): string {
+  const pad = (value: number) => String(value).padStart(2, '0')
+  let out = ''
+  let i = 0
+
+  while (i < template.length) {
+    const ch = template[i]
+
+    if (ch === "'") {
+      i++
+      if (template[i] === "'") {
+        out += "'"
+        i++
+        continue
+      }
+      while (i < template.length && template[i] !== "'") {
+        out += template[i]
+        i++
+      }
+      i++ // skip the closing quote
+      continue
+    }
+
+    if (ch === 'h' || ch === 'm' || ch === 's') {
+      let len = 1
+      while (template[i + len] === ch) len++
+      const value = ch === 'h' ? hours : ch === 'm' ? minutes : secs
+      out += len >= 2 ? pad(value) : String(value)
+      i += len
+      continue
+    }
+
+    out += ch
+    i++
+  }
+
+  return out
+}
+
+function formatShort(hours: number, minutes: number, secs: number): string {
+  const parts: string[] = []
+  if (hours) parts.push(`${hours}h`)
+  if (minutes) parts.push(`${minutes}m`)
+  if (secs) parts.push(`${secs}s`)
+  return parts.length ? parts.join(' ') : '0s'
+}
+
+function formatLong(hours: number, minutes: number, secs: number): string {
+  const parts: string[] = []
+  if (hours) parts.push(hours === 1 ? '1 hour' : `${hours} hours`)
+  if (minutes) parts.push(minutes === 1 ? '1 minute' : `${minutes} minutes`)
+  if (secs) parts.push(secs === 1 ? '1 second' : `${secs} seconds`)
+  return parts.length ? parts.join(' ') : '0 seconds'
+}
+
+function formatColon(hours: number, minutes: number, secs: number): string {
+  const pad = (value: number) => String(value).padStart(2, '0')
+  if (hours) return `${hours}:${pad(minutes)}:${pad(secs)}`
+  return `${minutes}:${pad(secs)}`
+}
+
+// ---------------------------------------------------------------------------
+// Parse: human-readable string → seconds (integer) or null if invalid.
+//
+// Supported formats (case-insensitive, spaces optional, any unit order):
+//   1h 30m 45s | 4m 3h 4s | 4sec 3hour 4min | 1h30m45s
+//   1:30:45    | 1:30     | :45
+//   90         | 90s      (bare integer treated as seconds)
+// ---------------------------------------------------------------------------
+export function parseDuration(str: string): number | null {
+  const input = str.trim().toLowerCase()
+  if (!input) return null
+
+  const colonSeconds = parseColon(input)
+  if (colonSeconds !== null) return colonSeconds
+
+  // Bare integer: treated as seconds.
+  if (/^\d+$/.test(input)) return parseInt(input, 10)
+
+  return parseUnits(input)
+}
+
+// Colon-separated: h:m:s or m:s or :s. Groups are not bounded to 0-59:
+// out-of-range parts overflow by design, so "1:75" parses to 135s (1m + 75s)
+// and "5:99" to 399s. This mirrors stopwatch-style entry and is harmless.
+function parseColon(input: string): number | null {
+  const match = input.match(/^(\d+):(\d+):(\d+)$|^(\d+):(\d+)$|^:(\d+)$/)
+  if (!match) return null
+
+  if (match[1] !== undefined) {
+    return (
+      parseInt(match[1], 10) * 3600 +
+      parseInt(match[2], 10) * 60 +
+      parseInt(match[3], 10)
+    )
+  }
+  if (match[4] !== undefined) {
+    return parseInt(match[4], 10) * 60 + parseInt(match[5], 10)
+  }
+  return parseInt(match[6], 10)
+}
+
+// Named units in any order: scan (number)(unit) tokens left-to-right and
+// verify no unexpected text exists between tokens. Rejects duplicate units.
+function parseUnits(input: string): number | null {
+  const tokenRe = /(\d+)\s*(hours?|hrs?|h|minutes?|mins?|m|seconds?|secs?|s)/g
+  const tokens: { value: number; unit: string }[] = []
+  let lastEnd = 0
+  let match: RegExpExecArray | null
+
+  while ((match = tokenRe.exec(input)) !== null) {
+    if (input.slice(lastEnd, match.index).trim() !== '') return null
+    tokens.push({ value: parseInt(match[1], 10), unit: match[2][0] })
+    lastEnd = match.index + match[0].length
+  }
+
+  if (input.slice(lastEnd).trim() !== '') return null
+  if (tokens.length === 0) return null
+
+  const seen = new Set<string>()
+  let total = 0
+  for (const { value, unit } of tokens) {
+    if (seen.has(unit)) return null
+    seen.add(unit)
+    if (unit === 'h') total += value * 3600
+    else if (unit === 'm') total += value * 60
+    else total += value
+  }
+  return total
+}

package/src/components/Duration/index.ts

@@ -0,0 +1,8 @@
+export { default as Duration } from './Duration.vue'
+export { formatDuration, parseDuration } from './duration'
+export type {
+  DurationProps,
+  DurationEmits,
+  DurationExposed,
+  DurationFormat,
+} from './types'

package/src/components/Duration/stories/Default.vue

@@ -0,0 +1,10 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Duration } from 'frappe-ui'
+
+const value = ref<number | null>(5445)
+</script>
+
+<template>
+  <Duration v-model="value" label="Time spent" />
+</template>

package/src/components/Duration/stories/Formats.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Duration } from 'frappe-ui'
+
+const value = ref<number | null>(7323)
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 items-start">
+    <Duration v-model="value" format="short" label="short (default)" />
+    <Duration v-model="value" format="long" label="long" />
+    <Duration v-model="value" format="colon" label="colon" />
+    <Duration v-model="value" format="h'h' m'm' s's'" label="template: h'h' m'm' s's'" />
+    <Duration v-model="value" format="hh:mm:ss" label="template: hh:mm:ss" />
+  </div>
+</template>

package/src/components/Duration/stories/RealWorld.vue

@@ -0,0 +1,50 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { Button, Duration, formatDuration } from 'frappe-ui'
+
+// Logging effort against a CRM task: the user types a duration in any
+// notation, "Log time" appends it, and the entries roll up into a total.
+const entries = ref<{ label: string; seconds: number }[]>([
+  { label: 'Discovery call', seconds: 2700 },
+  { label: 'Proposal draft', seconds: 5445 },
+])
+
+const draft = ref<number | null>(null)
+
+const total = computed(() =>
+  entries.value.reduce((sum, entry) => sum + entry.seconds, 0),
+)
+
+function logTime() {
+  if (!draft.value) return
+  entries.value.push({ label: 'Follow-up', seconds: draft.value })
+  draft.value = null
+}
+</script>
+
+<template>
+  <div class="flex w-80 flex-col gap-4">
+    <div class="flex flex-col gap-2">
+      <div
+        v-for="(entry, index) in entries"
+        :key="index"
+        class="flex items-center justify-between text-base text-ink-gray-7"
+      >
+        <span>{{ entry.label }}</span>
+        <span class="text-ink-gray-9">{{ formatDuration(entry.seconds) }}</span>
+      </div>
+    </div>
+
+    <div class="flex items-end gap-2">
+      <Duration v-model="draft" label="Log time" placeholder="e.g. 45m" />
+      <Button label="Log time" @click="logTime" />
+    </div>
+
+    <div
+      class="flex items-center justify-between border-t border-outline-gray-1 pt-3 text-base font-medium text-ink-gray-9"
+    >
+      <span>Total logged</span>
+      <span>{{ formatDuration(total, 'long') }}</span>
+    </div>
+  </div>
+</template>

package/src/components/Duration/stories/Sizes.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Duration } from 'frappe-ui'
+
+const value = ref<number | null>(5445)
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 items-start">
+    <Duration v-model="value" size="sm" />
+    <Duration v-model="value" size="md" />
+    <Duration v-model="value" size="lg" />
+    <Duration v-model="value" size="xl" />
+  </div>
+</template>

package/src/components/Duration/stories/States.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import { Duration } from 'frappe-ui'
+</script>
+
+<template>
+  <div class="flex flex-col gap-4 items-start">
+    <Duration label="Default" :model-value="5445" />
+    <Duration
+      label="With description"
+      description="Time spent on this task."
+      :model-value="5445"
+    />
+    <Duration label="Required" required :model-value="5445" />
+    <Duration label="Disabled" disabled :model-value="5445" />
+    <Duration
+      label="With error"
+      error="Please enter a duration."
+      :model-value="5445"
+    />
+  </div>
+</template>

package/src/components/Duration/types.ts

@@ -0,0 +1,52 @@
+import type { InputSize, InputVariant } from '../../composables/inputTypes'
+import type { InputLabelingProps } from '../../composables/useInputLabeling'
+
+/**
+ * Named display presets (smart zero-omission; `long` also pluralizes):
+ *   short — "1h 30m 45s"
+ *   long  — "1 hour 30 minutes 45 seconds"
+ *   colon — "1:30:45"
+ */
+export type DurationFormatPreset = 'short' | 'long' | 'colon'
+
+/**
+ * How a duration is rendered: a named preset, or a token template string
+ * rendered literally — `h`/`hh`, `m`/`mm`, `s`/`ss`, with single-quoted text
+ * taken as a literal (e.g. `h'h' m'm' s's'` → "2h 2m 3s", `hh:mm:ss` → "02:02:03").
+ */
+// `string & {}` keeps preset autocomplete while still accepting any template.
+export type DurationFormat = DurationFormatPreset | (string & {})
+
+export interface DurationProps extends InputLabelingProps {
+  /** The duration value in seconds (two-way via `v-model`). */
+  modelValue?: number | null
+
+  /** Placeholder shown when the input is empty. Defaults to `1h 30m 45s`. */
+  placeholder?: string
+
+  /**
+   * How the saved value is rendered when not focused: a named preset
+   * (`short` | `long` | `colon`) or a token template (e.g. `h'h' m'm' s's'`,
+   * `hh:mm:ss`). Defaults to `short`.
+   */
+  format?: DurationFormat
+
+  /** Visual size of the input. Forwarded to the underlying `TextInput`. */
+  size?: InputSize
+
+  /** Style variant of the input. Forwarded to the underlying `TextInput`. */
+  variant?: InputVariant
+
+  /** Disables the input when true. */
+  disabled?: boolean
+}
+
+export interface DurationEmits {
+  /** Fired when the model value changes. */
+  'update:modelValue': [value: number | null]
+}
+
+export interface DurationExposed {
+  /** Focuses the underlying text input. */
+  focus: () => void
+}

package/src/components/ErrorMessage/ErrorMessage.cy.ts

@@ -10,6 +10,6 @@ describe('ErrorMessage', () => {
 
     cy.get('[role=alert]')
       .should('have.text', 'Invalid value')
-      .should('have.class', 'text-ink-red-4')
+      .should('have.class', 'text-ink-red-8')
   })
 })

package/src/components/ErrorMessage/ErrorMessage.md

@@ -2,6 +2,10 @@
 
 Displays a clear message to indicate errors or issues. Helps users understand problems and take corrective action quickly.
 
+## Playground
+
+<ClientOnly><ErrorMessageBuilder /></ClientOnly>
+
 ## String Message
 <ComponentPreview name="ErrorMessage-Examples" />
 

package/src/components/ErrorMessage/ErrorMessage.vue

@@ -1,7 +1,7 @@
 <template>
   <div
     v-if="message"
-    class="whitespace-pre-line text-sm text-ink-red-4"
+    class="whitespace-pre-line text-sm text-ink-red-8"
     role="alert"
     v-html="errorMessage"
   ></div>

package/src/components/FileUploader/FileUploader.api.md

@@ -6,27 +6,52 @@
 
   const propsData = [
   {
-    name: 'validateFile',
-    description: '',
+    name: 'fileTypes',
+    description: 'Accepted file types passed to the native file input.',
     required: false,
-    type: 'Function',
-    default: 'null'
+    type: 'string | string[]'
   },
   {
-    name: 'fileTypes',
-    description: '',
+    name: 'uploadArgs',
+    description: 'Additional upload options passed to Frappe\'s upload endpoint.\n`private` / `is_private` override the component\'s `isPrivate` default.',
     required: false,
-    type: 'string | unknown[]'
+    type: 'UploadOptions',
+    default: 'undefined'
   },
   {
-    name: 'uploadArgs',
-    description: '',
+    name: 'validateFile',
+    description: 'Optional validation hook. Return a message or Error to block upload.',
     required: false,
-    type: 'Record<string, any>'
+    type: '((file: File) => FileUploaderValidationResult | Promise<FileUploaderValidationResult>)',
+    default: 'undefined'
+  }
+]
+
+  const slotsData = [
+  {
+    name: 'default',
+    description: '',
+    type: 'FileUploaderSlotProps'
+  }
+]
+
+  const emitsData = [
+  {
+    name: 'success',
+    description: '',
+    type: '[data: any]'
+  },
+  {
+    name: 'failure',
+    description: '',
+    type: '[error: any]'
   }
 ]
 </script>
 ## API Reference
 
-<PropsTable name="FileUploader" :data="propsData"/> 
+<PropsTable name="FileUploader" :data="propsData"/>
+
+<SlotsTable :data="slotsData"/>
 
+<EmitsTable :data="emitsData"/>