@openreachtech/furo-vue 1.3.1

package/lib/contexts/BaseFuroContext.js

@@ -0,0 +1,318 @@
+import {
+  watch,
+} from 'vue'
+
+/**
+ * Furo Component Context.
+ *
+ * @template {typeof import('./BaseFuroContextAccessor').default<*> | null} [A = null] - ContextAccessor class.
+ * @template {import('vue').ComponentCustomProps} [P = {}] - Props.
+ * @template {string | null} [EE = null] - emit() event names.
+ */
+export default class BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {BaseFuroContextParams<P>} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    reactiveHash,
+    refHash,
+    shallowRefHash,
+    modelRefHash,
+  }) {
+    this.props = props
+    this.componentContext = componentContext
+
+    this.reactiveHash = reactiveHash
+    this.refHash = refHash
+    this.shallowRefHash = shallowRefHash
+    this.modelRefHash = modelRefHash
+
+    this.accessor = this.createContextAccessor()
+  }
+
+  /**
+   * Factory method to create a new instance of this class.
+   *
+   * @template {X extends typeof BaseFuroContext ? X : never} T, X
+   * @param {BaseFuroContextFactoryParams<{}>} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} - New instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+  }) {
+    const reactiveHash = this.buildReactiveHash()
+    const refHash = this.buildRefHash()
+    const shallowRefHash = this.buildShallowRefHash()
+    const modelRefHash = this.buildModelRefHash()
+
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+        reactiveHash,
+        refHash,
+        shallowRefHash,
+        modelRefHash,
+      })
+    )
+  }
+
+  /**
+   * get: ContextAccessor for this class.
+   *
+   * @returns {typeof import('./BaseFuroContextAccessor').default<*> | null} - ContextAccessor class of this class.
+   */
+  static get ContextAccessor () {
+    return null
+  }
+
+  /**
+   * emit() event name.
+   *
+   * @abstract
+   * @returns {Record<string, string>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {}
+  }
+
+  /**
+   * Build reactive hash.
+   *
+   * @returns {Record<string, import('vue').Reactive<*>>}
+   */
+  static buildReactiveHash () {
+    return {}
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @returns {Record<string, import('vue').Ref<*>>}
+   */
+  static buildRefHash () {
+    return {}
+  }
+
+  /**
+   * Build shallow ref hash.
+   *
+   * @returns {Record<string, import('vue').ShallowRef<*>>}
+   */
+  static buildShallowRefHash () {
+    return {}
+  }
+
+  /**
+   * Build model value hash.
+   *
+   * @returns {Record<string, import('vue').ModelRef<*>>}
+   */
+  static buildModelRefHash () {
+    return {}
+  }
+
+  /**
+   * Create MutationObserver.
+   *
+   * @param {{
+   *   handler: MutationCallback
+   * }} args - Arguments of this method.
+   * @returns {MutationObserver} - New instance of MutationObserver.
+   */
+  static createMutationObserver ({
+    handler,
+  }) {
+    return new MutationObserver(handler)
+  }
+
+  /**
+   * Get the constructor of this class.
+   *
+   * @returns {typeof BaseFuroContext<*, *, *>}
+   */
+  get Ctor () {
+    return /** @type {typeof BaseFuroContext<*, *, *>} */ (this.constructor)
+  }
+
+  /**
+   * get: ContextAccessor for this class.
+   *
+   * @returns {import('./BaseFuroContextAccessor').default<*> | null} - ContextAccessor class of this class.
+   */
+  createContextAccessor () {
+    if (!this.Ctor.ContextAccessor) {
+      return null
+    }
+
+    return this.Ctor.ContextAccessor
+      .create({
+        context: this,
+      })
+  }
+
+  /**
+   * get: An instance of ContextAccessor.
+   *
+   * @returns {InstanceType<A>} - An instance of ContextAccessor.
+   */
+  get $ () {
+    return /** @type {*} */ (this.accessor)
+  }
+
+  /**
+   * get: emit() event name.
+   *
+   * @returns {Record<string, EE>} - emit() event name.
+   */
+  get EMIT_EVENT_NAME () {
+    return /** @type {*} */ (this.Ctor.EMIT_EVENT_NAME)
+  }
+
+  /**
+   * get: parcel of props.
+   *
+   * @returns {P['parcel'] | null} - Parcel from props.
+   */
+  get parcel () {
+    return this.props.parcel
+      ?? null
+  }
+
+  /**
+   * get: attrs of component context.
+   *
+   * @returns {import('vue').SetupContext['attrs']} - Attributes of component context.
+   */
+  get attrs () {
+    return this.componentContext.attrs
+  }
+
+  /**
+   * get: slots of component context.
+   *
+   * @returns {(
+   *   event: EE,
+   *   ...args: Array<any>
+   * ) => void} - emit() function of component context.
+   */
+  get emit () {
+    return /** @type {*} */ (this.componentContext.emit)
+  }
+
+  /**
+   * get: expose() of component context.
+   *
+   * @returns {import('vue').SetupContext['expose']} - Listeners of component context.
+   */
+  get expose () {
+    return this.componentContext.expose
+  }
+
+  /**
+   * get: slots of component context.
+   *
+   * @returns {import('vue').SetupContext['slots']} - Slots of component context.
+   */
+  get slots () {
+    return this.componentContext.slots
+  }
+
+  /**
+   * get: watch() of component context.
+   *
+   * @returns {import('vue').watch} - Watch of component context.
+   */
+  get watch () {
+    return watch
+  }
+
+  /**
+   * Whether a fallthrough attribute is on. Presence decides, as in HTML: every value
+   * reads as on, the bare attribute's '' and 0 included, except false and absent.
+   *
+   * @param {{
+   *   name: string
+   * }} params - Parameters of this method.
+   * @returns {boolean} - Whether the attribute is on.
+   */
+  hasBooleanAttribute ({
+    name,
+  }) {
+    const attributeValue = this.attrs?.[name]
+      ?? null
+
+    return attributeValue !== null
+      && attributeValue !== false
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template T
+   * @param {object} [args] - Arguments of this method.
+   * @returns {T} - For method chaining.
+   * @this {T}
+   * @example
+   * ```
+   * setupComponent (args) {
+   *   this..expose(
+   *     this.generateExposeHash()
+   *   )
+   *
+   *   watch(
+   *     [
+   *       this.rootElementRef,
+   *     ],
+   *     this.generateWatchRootElementHandler()
+   *   )
+   *
+   *   return this
+   * }
+   * ```
+   */
+  setupComponent (args = {}) {
+    return this
+  }
+
+  /**
+   * Generate expose() hash.
+   *
+   * @returns {Record<string, Function>} - expose() hash.
+   */
+  generateExposeHash () {
+    return {}
+  }
+}
+
+/**
+ * @typedef {{
+ *   props: P & {
+ *     parcel?: *
+ *   }
+ *   componentContext: import('vue').SetupContext<EE>
+ *   reactiveHash?: ReactiveHash
+ *   refHash?: RefHash
+ *   shallowRefHash?: ShallowRefHash
+ *   modelRefHash?: ModelRefHash
+ * }} BaseFuroContextParams
+ * @template {import('vue').ComponentCustomProps | {}} [P = {}] - Props.
+ * @template {string | null} [EE = null] - emit() event names.
+ * @template {Record<string, import('vue').Reactive<*>>} [ReactiveHash = {}] - Reactive hash.
+ * @template {Record<string, import('vue').Ref<*>>} [RefHash = {}] - Ref hash.
+ * @template {Record<string, import('vue').ShallowRef<*>>} [ShallowRefHash = {}] - ShallowRef hash.
+ * @template {Record<string, import('vue').ModelRef<*>>} [ModelRefHash = {}] - ModelRef hash.
+ */
+
+/**
+ * @typedef {BaseFuroContextParams<P>} BaseFuroContextFactoryParams
+ * @template {import('vue').ComponentCustomProps | {}} [P = {}] - Props.
+ * @template {string | null} [EE = null] - emit() event names.
+ */

package/lib/contexts/BaseFuroContextAccessor.js

@@ -0,0 +1,47 @@
+/**
+ * Base class for all context accessors.
+ *
+ * @template {import('./BaseFuroContext').default<*>} C
+ * @property {C} context - Context.
+ */
+export default class BaseFuroContextAccessor {
+  /**
+   * Constructor.
+   *
+   * @param {BaseFuroContextAccessorParams<C>} params - Parameters of this constructor.
+   */
+  constructor ({
+    context,
+  }) {
+    this.context = context
+  }
+
+  /**
+   * Factory method to create a new instance of this class.
+   *
+   * @template {X extends typeof BaseFuroContextAccessor<*> ? X : never} T, X
+   * @param {BaseFuroContextAccessorFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} - New instance of this class.
+   * @this {T}
+   */
+  static create ({
+    context,
+  }) {
+    return /** @type {*} */ (
+      new this({
+        context,
+      })
+    )
+  }
+}
+
+/**
+ * @typedef {{
+ *   context: C
+ * }} BaseFuroContextAccessorParams
+ * @template {import('./BaseFuroContext').default<*>} C
+ */
+
+/**
+ * @typedef {BaseFuroContextAccessorParams<*>} BaseFuroContextAccessorFactoryParams
+ */

package/lib/emit-payload/BaseEmitPayload.js

@@ -0,0 +1,91 @@
+/**
+ * BaseEmitPayload.
+ *
+ * @template {Event} [E = Event] - Event.
+ * @template {HTMLElement} [C = HTMLElement] - Control element.
+ */
+export default class BaseEmitPayload {
+  /**
+   * Constructor of this class.
+   *
+   * @param {BaseEmitPayloadParams<E>} params - Parameters of this constructor.
+   */
+  constructor ({
+    rawEvent,
+  }) {
+    this.rawEvent = rawEvent
+  }
+
+  /**
+   * Factory method of this class.
+   *
+   * @template {X extends typeof BaseEmitPayload ? X : never} T, X
+   * @param {BaseEmitPayloadFactoryParams<*>} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} - A new instance of this class.
+   * @this {T}
+   */
+  static create ({
+    rawEvent,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        rawEvent,
+      })
+    )
+  }
+
+  /**
+   * Get the control element from the raw event.
+   *
+   * @returns {C | null} - The control element from the raw event.
+   */
+  get controlElement () {
+    return /** @type {C} */ (this.rawEvent?.target)
+      ?? null
+  }
+
+  /**
+   * Read a DOM attribute from the control element.
+   *
+   * @param {{
+   *   key: string
+   * }} params - Parameters of this method.
+   * @returns {string | null} - Attribute value, or `null` when the control or attribute is missing.
+   */
+  getElementAttribute ({
+    key,
+  }) {
+    return this.controlElement?.getAttribute(key)
+      ?? null
+  }
+
+  /**
+   * Parse a string as a number (e.g. after reading an attribute).
+   *
+   * @param {{
+   *   stringValue: string | null
+   * }} params - Parameters of this method.
+   * @returns {number | null} - Parsed number, or `null` when `stringValue` is `null`.
+   */
+  parseStringAsNumber ({
+    stringValue,
+  }) {
+    if (stringValue === null) {
+      return null
+    }
+
+    return Number(stringValue)
+  }
+}
+
+/**
+ * @typedef {{
+ *   rawEvent: E
+ * }} BaseEmitPayloadParams<E>
+ * @template {Event} E
+ */
+
+/**
+ * @typedef {BaseEmitPayloadParams<E>} BaseEmitPayloadFactoryParams<E>
+ * @template {Event} E
+ */

package/lib/index.components.js

@@ -0,0 +1,61 @@
+/**
+ * Components - Atoms
+ */
+export { default as FuroAvatar } from './components/atoms/FuroAvatar/FuroAvatar.vue'
+export { default as FuroBadge } from './components/atoms/FuroBadge/FuroBadge.vue'
+export { default as FuroButton } from './components/atoms/FuroButton/FuroButton.vue'
+export { default as FuroCheckbox } from './components/atoms/FuroCheckbox/FuroCheckbox.vue'
+export { default as FuroEmailField } from './components/atoms/FuroEmailField/FuroEmailField.vue'
+export { default as FuroFileField } from './components/atoms/FuroFileField/FuroFileField.vue'
+export { default as FuroIcon } from './components/atoms/FuroIcon/FuroIcon.vue'
+export { default as FuroNumberField } from './components/atoms/FuroNumberField/FuroNumberField.vue'
+export { default as FuroPasswordField } from './components/atoms/FuroPasswordField/FuroPasswordField.vue'
+export { default as FuroRadio } from './components/atoms/FuroRadio/FuroRadio.vue'
+export { default as FuroSwitch } from './components/atoms/FuroSwitch/FuroSwitch.vue'
+export { default as FuroTextField } from './components/atoms/FuroTextField/FuroTextField.vue'
+export { default as FuroTextarea } from './components/atoms/FuroTextarea/FuroTextarea.vue'
+export { default as FuroToggle } from './components/atoms/FuroToggle/FuroToggle.vue'
+
+/**
+ * Components - Molecules
+ */
+export { default as FuroAccordion } from './components/molecules/FuroAccordion/FuroAccordion.vue'
+export { default as FuroAttachment } from './components/molecules/FuroAttachment/FuroAttachment.vue'
+export { default as FuroAutocompleteField } from './components/molecules/FuroAutocompleteField/FuroAutocompleteField.vue'
+export { default as FuroAvatarGroup } from './components/molecules/FuroAvatarGroup/FuroAvatarGroup.vue'
+export { default as FuroBreadcrumb } from './components/molecules/FuroBreadcrumb/FuroBreadcrumb.vue'
+export { default as FuroCollapsible } from './components/molecules/FuroCollapsible/FuroCollapsible.vue'
+export { default as FuroControlBlock } from './components/molecules/FuroControlBlock/FuroControlBlock.vue'
+export { default as FuroDatePicker } from './components/molecules/FuroDatePicker/FuroDatePicker.vue'
+export { default as FuroDateTimePicker } from './components/molecules/FuroDateTimePicker/FuroDateTimePicker.vue'
+export { default as FuroDropdownMenu } from './components/molecules/FuroDropdownMenu/FuroDropdownMenu.vue'
+export { default as FuroEditableField } from './components/molecules/FuroEditableField/FuroEditableField.vue'
+export { default as FuroEmptyState } from './components/molecules/FuroEmptyState/FuroEmptyState.vue'
+export { default as FuroErrorState } from './components/molecules/FuroErrorState/FuroErrorState.vue'
+export { default as FuroPagination } from './components/molecules/FuroPagination/FuroPagination.vue'
+export { default as FuroPopover } from './components/molecules/FuroPopover/FuroPopover.vue'
+export { default as FuroScrollArea } from './components/molecules/FuroScrollArea/FuroScrollArea.vue'
+export { default as FuroSearchField } from './components/molecules/FuroSearchField/FuroSearchField.vue'
+export { default as FuroSectionHeader } from './components/molecules/FuroSectionHeader/FuroSectionHeader.vue'
+export { default as FuroSelect } from './components/molecules/FuroSelect/FuroSelect.vue'
+export { default as FuroSeparator } from './components/molecules/FuroSeparator/FuroSeparator.vue'
+export { default as FuroSkeleton } from './components/molecules/FuroSkeleton/FuroSkeleton.vue'
+export { default as FuroSplitter } from './components/molecules/FuroSplitter/FuroSplitter.vue'
+export { default as FuroTimeField } from './components/molecules/FuroTimeField/FuroTimeField.vue'
+export { default as FuroToggleGroup } from './components/molecules/FuroToggleGroup/FuroToggleGroup.vue'
+export { default as FuroToolBar } from './components/molecules/FuroToolBar/FuroToolBar.vue'
+export { default as FuroTooltip } from './components/molecules/FuroTooltip/FuroTooltip.vue'
+
+/**
+ * Components - Organisms
+ */
+export { default as FuroAlertDialog } from './components/organisms/FuroAlertDialog/FuroAlertDialog.vue'
+export { default as FuroDialog } from './components/organisms/FuroDialog/FuroDialog.vue'
+export { default as FuroDrawer } from './components/organisms/FuroDrawer/FuroDrawer.vue'
+export { default as FuroEditor } from './components/organisms/FuroEditor/FuroEditor.vue'
+export { default as FuroSidebar } from './components/organisms/FuroSidebar/FuroSidebar.vue'
+export { default as FuroStepper } from './components/organisms/FuroStepper/FuroStepper.vue'
+export { default as FuroTable } from './components/organisms/FuroTable/FuroTable.vue'
+export { default as FuroTabs } from './components/organisms/FuroTabs/FuroTabs.vue'
+export { default as FuroToast } from './components/organisms/FuroToast/FuroToast.vue'
+export { default as FuroToaster } from './components/organisms/FuroToast/FuroToaster.vue'

package/lib/index.core.js

@@ -0,0 +1,18 @@
+/**
+ * Furo Context
+ */
+export { default as BaseFuroContext } from './contexts/BaseFuroContext.js'
+
+export { default as BaseFuroContextAccessor } from './contexts/BaseFuroContextAccessor.js'
+
+/**
+ * Icons: consumer icon registration (also exposed at the `furo-vue/icons` subpath)
+ */
+export { furoIconRegistry } from './components/atoms/FuroIcon/icons.js'
+export { default as FuroIconRegistry } from './components/atoms/FuroIcon/FuroIconRegistry.js'
+
+/**
+ * Toast: imperative global helper, the supported import path
+ */
+export { toast, toastQueue } from './components/organisms/FuroToast/toast.js'
+export { default as ToastQueue } from './components/organisms/FuroToast/ToastQueue.js'

package/lib/tools/TimerClerk.js

@@ -0,0 +1,75 @@
+/**
+ * Timer Clerk
+ *
+ * @property {NodeJS.Timeout | number | null} lastTimer - Last timer
+ */
+export default class TimerClerk {
+  /**
+   * Constructor.
+   *
+   * @param {{
+   *   onTick: Function
+   *   timeInMilliseconds: number
+   * }} params - Parameters
+   */
+  constructor ({
+    onTick,
+    timeInMilliseconds,
+  }) {
+    this.onTick = onTick
+    this.timeInMilliseconds = timeInMilliseconds
+
+    this.lastTimer = null
+  }
+
+  /**
+   * Factory method to create a new instance of this class.
+   *
+   * @template {X extends typeof TimerClerk ? X : never} T, X
+   * @param {{
+   *   onTick: Function
+   *   timeInMilliseconds: number
+   * }} params - Parameters
+   * @returns {InstanceType<T>} - New instance of this class
+   * @this {T}
+   */
+  static create ({
+    onTick,
+    timeInMilliseconds,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        onTick,
+        timeInMilliseconds,
+      })
+    )
+  }
+
+  /**
+   * Start the timer.
+   *
+   * @param {Array<*>} args - Arguments
+   * @returns {void}
+   */
+  startTimer (...args) {
+    this.stopTimer()
+
+    this.lastTimer = setTimeout(
+      () => this.onTick(...args),
+      this.timeInMilliseconds
+    )
+  }
+
+  /**
+   * Stop the timer.
+   *
+   * @returns {void}
+   */
+  stopTimer () {
+    if (!this.lastTimer) {
+      return
+    }
+
+    clearTimeout(this.lastTimer)
+  }
+}