@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroAttachment/FuroAttachmentContext.js

@@ -0,0 +1,628 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+/**
+ * Furo-owned parcel keys (not forwarded verbatim to the root element).
+ */
+const FURO_ATTACHMENT_PARCEL_KEYS = new Set([
+  'fileName',
+  'fileSize',
+  'imageSource',
+  'imageAlternativeText',
+  'iconName',
+  'uploading',
+  'uploadProgress',
+  'downloadable',
+  'removable',
+  'downloadLabel',
+  'removeLabel',
+  'uploadingLabel',
+])
+
+/**
+ * Context class for FuroAttachment molecule.
+ *
+ * One component covers both shapes the design draws. With no image source it
+ * renders a file row carrying a type glyph; with one it renders the preview at
+ * a single size and crop. A preview that fails to load falls back to the row,
+ * so a dead URL shows the glyph rather than a broken image.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroAttachmentContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroAttachmentContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroAttachmentContext ? X : never} T, X
+   * @override
+   * @param {FuroAttachmentContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    refHash = this.buildRefHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        refHash,
+      })
+    )
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @override
+   * @returns {FuroAttachmentContextParams['refHash']} Ref hash.
+   */
+  static buildRefHash () {
+    return {
+      imagePreviewFailedRef: ref(false),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   DOWNLOAD: 'download'
+   *   REMOVE: 'remove'
+   * }>} Emit event names.
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      DOWNLOAD: 'download',
+      REMOVE: 'remove',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   download: (payload: FuroAttachmentEmitPayload) => void
+   *   remove: (payload: FuroAttachmentEmitPayload) => void
+   * }} Emit hash.
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.DOWNLOAD]: payload => {},
+      [this.EMIT_EVENT_NAME.REMOVE]: payload => {},
+    }
+  }
+
+  /**
+   * The glyph a file row shows when the caller names none.
+   *
+   * @returns {string} Icon name.
+   */
+  static get DEFAULT_ICON_NAME () {
+    return 'ph:file'
+  }
+
+  /**
+   * The lowest share of an upload the bar can report.
+   *
+   * @returns {number} Percentage.
+   */
+  static get MINIMUM_UPLOAD_PROGRESS () {
+    return 0
+  }
+
+  /**
+   * The highest share of an upload the bar can report.
+   *
+   * @returns {number} Percentage.
+   */
+  static get MAXIMUM_UPLOAD_PROGRESS () {
+    return 100
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroAttachmentContext} Constructor.
+   */
+  get Ctor () {
+    return /** @type {typeof FuroAttachmentContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * get: whether the preview of the current source failed to load.
+   *
+   * @returns {import('vue').Ref<boolean>} Ref.
+   */
+  get imagePreviewFailedRef () {
+    return this.refHash.imagePreviewFailedRef
+  }
+
+  /**
+   * get: name of the file.
+   *
+   * @returns {string} File name; empty string when unset.
+   */
+  get fileName () {
+    return this.parcel?.fileName
+      ?? ''
+  }
+
+  /**
+   * get: size of the file, already formatted for reading.
+   *
+   * @returns {string} Formatted size; empty string when unset.
+   */
+  get fileSize () {
+    return this.parcel?.fileSize
+      ?? ''
+  }
+
+  /**
+   * get: source of the preview image.
+   *
+   * @returns {string | null} Source, or null when the file has no preview.
+   */
+  get imageSource () {
+    return this.parcel?.imageSource
+      ?? null
+  }
+
+  /**
+   * get: alternative text for the preview image.
+   *
+   * Falls back to the file name, which is what a caller would otherwise repeat.
+   *
+   * @returns {string} Alternative text.
+   */
+  get imageAlternativeText () {
+    return this.parcel?.imageAlternativeText
+      ?? this.fileName
+  }
+
+  /**
+   * get: name of the glyph a file row shows.
+   *
+   * @returns {string} Icon name.
+   */
+  get iconName () {
+    return this.parcel?.iconName
+      ?? this.Ctor.DEFAULT_ICON_NAME
+  }
+
+  /**
+   * get: share of the upload already sent.
+   *
+   * @returns {number | null} Percentage, or null when the size is unknown.
+   */
+  get uploadProgress () {
+    return this.parcel?.uploadProgress
+      ?? null
+  }
+
+  /**
+   * get: accessible name of the download action.
+   *
+   * @returns {string} Label.
+   */
+  get downloadLabel () {
+    return this.parcel?.downloadLabel
+      ?? 'Download'
+  }
+
+  /**
+   * get: accessible name of the remove action.
+   *
+   * @returns {string} Label.
+   */
+  get removeLabel () {
+    return this.parcel?.removeLabel
+      ?? 'Remove'
+  }
+
+  /**
+   * get: accessible name of the upload bar.
+   *
+   * @returns {string} Label.
+   */
+  get uploadingLabel () {
+    return this.parcel?.uploadingLabel
+      ?? 'Uploading'
+  }
+
+  /**
+   * Setup component.
+   *
+   * @template {X extends FuroAttachmentContext ? X : never} T, X
+   * @override
+   * @returns {T} For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.watch(
+      () => this.imageSource,
+      () => {
+        this.imagePreviewFailedRef.value = false
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Whether the file is still being sent.
+   *
+   * @returns {boolean} true while the upload runs.
+   */
+  isUploading () {
+    return Boolean(this.parcel?.uploading)
+  }
+
+  /**
+   * Whether the caller allows the file to be downloaded.
+   *
+   * @returns {boolean} true when the download action may render.
+   */
+  isDownloadable () {
+    return this.parcel?.downloadable
+      ?? true
+  }
+
+  /**
+   * Whether the caller allows the file to be taken off the record.
+   *
+   * @returns {boolean} true when the remove action may render.
+   */
+  isRemovable () {
+    return this.parcel?.removable
+      ?? true
+  }
+
+  /**
+   * Whether the caller knows how large the upload is.
+   *
+   * @returns {boolean} true when a share was named, false when the size is unknown.
+   */
+  isUploadMeasured () {
+    return this.uploadProgress !== null
+  }
+
+  /**
+   * Whether the preview renders in place of the file row.
+   *
+   * @returns {boolean} true when a source is set and it has loaded.
+   */
+  hasImagePreview () {
+    return this.imageSource !== null
+      && !this.imagePreviewFailedRef.value
+  }
+
+  /**
+   * Whether the row shows the formatted size under the name.
+   *
+   * @returns {boolean} true when a size is set and no upload is running.
+   */
+  hasFileSizeCaption () {
+    return !this.isUploading()
+      && this.fileSize !== ''
+  }
+
+  /**
+   * Whether the row shows the upload bar in place of the size.
+   *
+   * @returns {boolean} true while a file with no preview uploads.
+   */
+  hasProgressBar () {
+    return this.isUploading()
+      && !this.hasImagePreview()
+  }
+
+  /**
+   * Whether the preview is veiled and marked as uploading.
+   *
+   * The preview has no room for a bar, so the design covers it and spins
+   * instead of reporting a share.
+   *
+   * @returns {boolean} true while a file with a preview uploads.
+   */
+  hasUploadingPreview () {
+    return this.isUploading()
+      && this.hasImagePreview()
+  }
+
+  /**
+   * Whether the download action renders.
+   *
+   * @returns {boolean} true when the file is downloadable and settled.
+   */
+  hasDownloadAction () {
+    return this.isDownloadable()
+      && !this.isUploading()
+  }
+
+  /**
+   * Whether the remove action renders.
+   *
+   * It stays through an upload of a file with no preview, where it cancels.
+   *
+   * @returns {boolean} true when the remove action renders.
+   */
+  hasRemoveAction () {
+    return this.isRemovable()
+      && !this.hasUploadingPreview()
+  }
+
+  /**
+   * Whether anything renders in the action cluster.
+   *
+   * @returns {boolean} true when the cluster holds at least one control.
+   */
+  hasActions () {
+    return this.hasDownloadAction()
+      || this.hasRemoveAction()
+      || this.hasUploadingPreview()
+  }
+
+  /**
+   * Clamp the named share to the bar's own range, so a fill cannot outrun its track.
+   *
+   * @returns {number} Percentage between zero and one hundred.
+   */
+  calculateUploadProgress () {
+    const requested = this.uploadProgress
+      ?? this.Ctor.MINIMUM_UPLOAD_PROGRESS
+
+    return Math.min(
+      Math.max(requested, this.Ctor.MINIMUM_UPLOAD_PROGRESS),
+      this.Ctor.MAXIMUM_UPLOAD_PROGRESS
+    )
+  }
+
+  /**
+   * Extract CSS class map for the root.
+   *
+   * @returns {Record<string, boolean>} Class map.
+   */
+  extractRootClassNames () {
+    return Object.fromEntries([
+      ['unit-attachment', true],
+      ['image', this.hasImagePreview()],
+      ['uploading', this.isUploading()],
+    ])
+  }
+
+  /**
+   * Extract attributes forwarded to the root element.
+   *
+   * @returns {Record<string, unknown>} Passthrough attributes.
+   */
+  extractRootAttributes () {
+    const passthroughEntries = Object.entries(this.parcel ?? {})
+      .filter(([key]) => !FURO_ATTACHMENT_PARCEL_KEYS.has(key))
+
+    return Object.fromEntries(passthroughEntries)
+  }
+
+  /**
+   * Extract the attributes that let the bar report its share.
+   *
+   * @returns {{
+   *   role: 'progressbar'
+   *   'aria-label': string
+   *   'aria-valuemin': number
+   *   'aria-valuemax': number
+   *   'aria-valuenow'?: number
+   * }} Progress attributes.
+   */
+  extractProgressAttributes () {
+    return {
+      role: 'progressbar',
+      'aria-label': this.uploadingLabel,
+      'aria-valuemin': this.Ctor.MINIMUM_UPLOAD_PROGRESS,
+      'aria-valuemax': this.Ctor.MAXIMUM_UPLOAD_PROGRESS,
+      ...this.buildOptionalProgressAttributes(),
+    }
+  }
+
+  /**
+   * Build the attributes an upload of unknown size cannot answer.
+   *
+   * @returns {{
+   *   'aria-valuenow'?: number
+   * }} Progress attributes.
+   */
+  buildOptionalProgressAttributes () {
+    if (!this.isUploadMeasured()) {
+      return {}
+    }
+
+    return {
+      'aria-valuenow': this.calculateUploadProgress(),
+    }
+  }
+
+  /**
+   * Extract inline style for the filled part of the bar.
+   *
+   * @returns {{
+   *   width?: string
+   * }} Progress style.
+   */
+  extractProgressStyle () {
+    if (!this.isUploadMeasured()) {
+      return {}
+    }
+
+    return {
+      width: `${this.calculateUploadProgress()}%`,
+    }
+  }
+
+  /**
+   * Extract CSS class map for the filled part of the bar.
+   *
+   * @returns {Record<string, boolean>} Class map.
+   */
+  extractProgressFillClassNames () {
+    return Object.fromEntries([
+      ['fill', true],
+      ['indeterminate', !this.isUploadMeasured()],
+    ])
+  }
+
+  /**
+   * Build the parcel handed to one action button.
+   *
+   * @returns {{
+   *   variant: 'ghost'
+   *   size: 'icon'
+   * }} Button parcel.
+   */
+  buildActionParcel () {
+    return {
+      variant: 'ghost',
+      size: 'icon',
+    }
+  }
+
+  /**
+   * Build the payload an action carries.
+   *
+   * @returns {FuroAttachmentEmitPayload} Payload.
+   */
+  buildEmitPayload () {
+    return {
+      fileName: this.fileName,
+    }
+  }
+
+  /**
+   * Handle the preview failing to load.
+   */
+  onImagePreviewError () {
+    this.imagePreviewFailedRef.value = true
+  }
+
+  /**
+   * Handle a click on the download action.
+   */
+  onDownloadClick () {
+    this.emit(
+      this.EMIT_EVENT_NAME.DOWNLOAD,
+      this.buildEmitPayload()
+    )
+  }
+
+  /**
+   * Handle a click on the remove action.
+   */
+  onRemoveClick () {
+    this.emit(
+      this.EMIT_EVENT_NAME.REMOVE,
+      this.buildEmitPayload()
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     imagePreviewFailedRef: import('vue').Ref<boolean>
+ *   }
+ * }} FuroAttachmentContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroAttachmentContextParams, 'refHash'> & {
+ *   refHash?: FuroAttachmentContextParams['refHash']
+ * }} FuroAttachmentContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroAttachmentContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {{
+ *   fileName: string
+ * }} FuroAttachmentEmitPayload
+ */
+
+/**
+ * @typedef {{
+ *   parcel: FuroAttachmentParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {{
+ *   fileName?: string
+ *   fileSize?: string
+ *   imageSource?: string
+ *   imageAlternativeText?: string
+ *   iconName?: string
+ *   uploading?: boolean
+ *   uploadProgress?: number | null
+ *   downloadable?: boolean
+ *   removable?: boolean
+ *   downloadLabel?: string
+ *   removeLabel?: string
+ *   uploadingLabel?: string
+ * }} FuroAttachmentParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroAttachmentEmitHash, FuroAttachmentSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroAttachmentContext.EMIT_EVENT_HASH} FuroAttachmentEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   glyph: {}
+ *   actions: {}
+ * }>} FuroAttachmentSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroAttachmentContext
+ * }} FuroAttachmentSetup
+ */