@openreachtech/furo-vue 1.3.1

package/lib/components/atoms/FuroFileField/FuroFileFieldContext.js

@@ -0,0 +1,195 @@
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import FileFieldEmitPayload from './FileFieldEmitPayload.js'
+
+/**
+ * Context class for managing FuroFileField component.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroFileFieldContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroFileFieldContextParams} params
+   */
+  constructor ({
+    props,
+    componentContext,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroFileFieldContext ? X : never} T, X
+   * @override
+   * @param {FuroFileFieldContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+      })
+    )
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   CHANGE_VALUE: 'change-value'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      CHANGE_VALUE: 'change-value',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./FileFieldEmitPayload.js').default) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.CHANGE_VALUE]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of `EmitPayload`.
+   *
+   * @returns {typeof FileFieldEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return FileFieldEmitPayload
+  }
+
+  /**
+   * Create an instance of `FileFieldEmitPayload`.
+   *
+   * @param {{
+   *   rawEvent: import('./FileFieldEmitPayload.js').FileFieldRawEvent
+   * }} params - Parameters.
+   * @returns {InstanceType<typeof FileFieldEmitPayload>}
+   */
+  static createEmitPayload ({
+    rawEvent,
+  }) {
+    return this.EmitPayloadCtor.create({
+      rawEvent,
+    })
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroFileFieldContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroFileFieldContext} */ (this.constructor)
+  }
+
+  /**
+   * Generate input attributes without type attribute.
+   *
+   * @returns {Omit<import('vue').InputHTMLAttributes, 'type'>}
+   */
+  generateInputAttributes () {
+    const {
+      type,
+      ...restAttributes
+    } = this.attrs
+
+    return restAttributes
+  }
+
+  /**
+   * Whether the file field is invalid.
+   *
+   * @returns {boolean}
+   */
+  isInvalid () {
+    return Boolean(this.parcel?.invalid)
+  }
+
+  /**
+   * Respond to change event from the native file input.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params - Parameters.
+   */
+  onChangeValue ({
+    rawEvent,
+  }) {
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent,
+    })
+
+    this.emit(
+      this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      payload
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ * }} FuroFileFieldContextParams
+ */
+
+/**
+ * @typedef {FuroFileFieldContextParams} FuroFileFieldContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroFileFieldContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {Omit<import('vue').InputHTMLAttributes, 'type'> & {
+ *   parcel?: FuroFileFieldParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroFileFieldEmitHash>} ComponentContext
+ */
+
+/**
+ * @typedef {{
+ *   invalid?: boolean
+ * }} FuroFileFieldParcel
+ */
+
+/**
+ * @typedef {typeof FuroFileFieldContext.EMIT_EVENT_HASH} FuroFileFieldEmitHash
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroFileFieldContext
+ * }} FuroFileFieldSetup
+ */

package/lib/components/atoms/FuroIcon/FuroIcon.vue

@@ -0,0 +1,74 @@
+<script>
+import {
+  defineComponent,
+} from 'vue'
+
+import FuroIconContext from './FuroIconContext.js'
+
+export default defineComponent({
+  name: 'FuroIcon',
+  inheritAttrs: false,
+
+  props: {
+    name: {
+      /** @type {import('vue').PropType<import('./FuroIconContext.js').Props['name']>} */
+      type: String,
+      required: true,
+    },
+    size: {
+      /** @type {import('vue').PropType<import('./FuroIconContext.js').Props['size']>} */
+      type: [
+        String,
+        Number,
+        null,
+      ],
+      default: null,
+    },
+  },
+
+  /**
+   * Setup of this component.
+   *
+   * @param {import('./FuroIconContext.js').Props} props - Props.
+   * @param {import('vue').SetupContext} componentContext - Setup context.
+   * @returns {{ context: FuroIconContext }} Render context.
+   */
+  setup (
+    props,
+    componentContext
+  ) {
+    const context = FuroIconContext.create({
+      props,
+      componentContext,
+    })
+      .setupComponent()
+
+    return {
+      context,
+    }
+  },
+})
+</script>
+
+<template>
+  <component
+    :is="context.extractRendererComponent()"
+    :class="context.extractRootClassNames()"
+    v-bind="{
+      ...context.extractRendererAttributes(),
+      ...$attrs,
+    }"
+  />
+</template>
+
+<style>
+@layer furo {
+  .unit-icon {
+    flex-shrink: 0;
+  }
+
+  .unit-icon.unresolved {
+    color: var(--color-warning);
+  }
+}
+</style>

package/lib/components/atoms/FuroIcon/FuroIconContext.js

@@ -0,0 +1,293 @@
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import {
+  furoIconRegistry,
+} from './icons.js'
+
+const FALLBACK_ICON_NAME = 'ph:warning'
+
+/**
+ * Context class for FuroIcon atom.
+ *
+ * @extends {BaseFuroContext<null, Props, null>}
+ */
+export default class FuroIconContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroIconContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    iconRegistry,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.iconRegistry = iconRegistry
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroIconContext ? X : never} T, X
+   * @override
+   * @param {FuroIconContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    iconRegistry = furoIconRegistry,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        iconRegistry,
+      })
+    )
+  }
+
+  /**
+   * get: the icon name, collection prefix included.
+   *
+   * @returns {string | null} Icon name such as `ph:check`, or null.
+   */
+  get name () {
+    return this.props
+      ?.name
+      ?? null
+  }
+
+  /**
+   * get: the length of the icon's box, applied to both axes.
+   *
+   * @returns {string | number | null} A CSS length, or null to inherit the font size.
+   */
+  get size () {
+    return this.props
+      ?.size
+      ?? null
+  }
+
+  /**
+   * Extract the component that draws this icon.
+   *
+   * @returns {import('./FuroIconRegistry.js').IconRenderer} Renderer component.
+   */
+  extractRendererComponent () {
+    if (this.isDelegatedIcon()) {
+      return this.iconRegistry.extractIconRenderer()
+    }
+
+    return this.iconRegistry.extractOfflineRenderer()
+  }
+
+  /**
+   * Whether a consumer-installed renderer draws this name.
+   *
+   * @returns {boolean} Whether the name is delegated.
+   */
+  isDelegatedIcon () {
+    if (!this.iconRegistry.hasIconRenderer()) {
+      return false
+    }
+
+    return this.isUnregisteredIcon()
+  }
+
+  /**
+   * Whether the registry draws nothing for the name.
+   *
+   * @returns {boolean} Whether the name is unregistered.
+   */
+  isUnregisteredIcon () {
+    if (this.name === null) {
+      return false
+    }
+
+    return this.iconRegistry.findRenderableIcon({
+      name: this.name,
+    }) === null
+  }
+
+  /**
+   * Extract the attributes the drawing component expects.
+   *
+   * @returns {Record<string, *>} Renderer attributes.
+   */
+  extractRendererAttributes () {
+    if (this.isDelegatedIcon()) {
+      return this.buildDelegatedRendererAttributes()
+    }
+
+    return this.buildOfflineRendererAttributes()
+  }
+
+  /**
+   * Build the attributes a consumer-installed renderer expects.
+   *
+   * @returns {{
+   *   name: string | null
+   *   size?: string | number
+   * }} Renderer attributes.
+   */
+  buildDelegatedRendererAttributes () {
+    return {
+      name: this.name,
+      ...this.buildOptionalDelegatedSizeAttribute(),
+    }
+  }
+
+  /**
+   * Build the size attribute a consumer-installed renderer expects.
+   *
+   * @returns {{
+   *   size?: string | number
+   * }} Size attribute, omitted when no size was given.
+   */
+  buildOptionalDelegatedSizeAttribute () {
+    return this.size === null
+      ? {}
+      : {
+        size: this.size,
+      }
+  }
+
+  /**
+   * Build the attributes the library's own renderer expects.
+   *
+   * @returns {{
+   *   icon: string | object | null
+   *   width?: string | number
+   *   height?: string | number
+   * }} Renderer attributes.
+   */
+  buildOfflineRendererAttributes () {
+    return {
+      icon: this.extractRenderableIcon(), // re-applied as the renderer's `icon` property, the ONE allowed mention
+      ...this.buildOptionalSizeAttributes(),
+    }
+  }
+
+  /**
+   * Extract what the renderer draws, substituting a visible glyph for a name
+   * nothing resolves.
+   *
+   * @returns {string | object | null} A registered name, resolved icon data, or the fallback name.
+   */
+  extractRenderableIcon () {
+    if (this.name === null) {
+      return null
+    }
+
+    const icon = this.iconRegistry.findRenderableIcon({
+      name: this.name,
+    })
+
+    this.throwOnUnresolvedIcon({
+      icon,
+    })
+
+    return icon
+      ?? FALLBACK_ICON_NAME
+  }
+
+  /**
+   * Fail on a name nothing resolves, which the fallback glyph would otherwise leave
+   * to a visual check. Production draws the glyph instead.
+   *
+   * @param {{
+   *   icon: string | object | null
+   * }} params - Parameters of this method.
+   * @returns {void}
+   * @throws {Error} When no icon data resolves the name.
+   */
+  throwOnUnresolvedIcon ({
+    icon,
+  }) {
+    if (process.env.NODE_ENV === 'production') {
+      return
+    }
+
+    if (icon !== null) {
+      return
+    }
+
+    if (this.iconRegistry.hasIconRenderer()) {
+      return
+    }
+
+    throw new Error(`[FuroIcon] no icon data is registered for "${this.name}". Register its icon set with \`furoIconRegistry.registerIconSet()\`, register the single icon with \`furoIconRegistry.registerIcon()\`, install a resolver with \`furoIconRegistry.useIconResolver()\`, or hand every unregistered name to your own renderer with \`furoIconRegistry.useIconRenderer()\`.`)
+  }
+
+  /**
+   * Build the size attributes, omitted rather than nulled when no size was
+   * given, so the glyph keeps the renderer's `1em` default and scales with text.
+   *
+   * @returns {{
+   *   width?: string | number
+   *   height?: string | number
+   * }} Size attributes.
+   */
+  buildOptionalSizeAttributes () {
+    return this.size === null
+      ? {}
+      : {
+        width: this.size,
+        height: this.size,
+      }
+  }
+
+  /**
+   * Extract the CSS class map of the root host element.
+   *
+   * @returns {Record<string, boolean>} Class map.
+   */
+  extractRootClassNames () {
+    return {
+      'unit-icon': true,
+      unresolved: this.isUnresolvedIcon(),
+    }
+  }
+
+  /**
+   * Whether the name resolves to no icon at all.
+   *
+   * @returns {boolean} Whether the name is unresolved.
+   */
+  isUnresolvedIcon () {
+    if (this.iconRegistry.hasIconRenderer()) {
+      return false
+    }
+
+    return this.isUnregisteredIcon()
+  }
+}
+
+/**
+ * @typedef {{
+ *   name: string
+ *   size?: string | number | null
+ * }} Props
+ */
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams<Props> & {
+ *   iconRegistry: import('./FuroIconRegistry.js').default
+ * }} FuroIconContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroIconContextParams, 'iconRegistry'> & {
+ *   iconRegistry?: import('./FuroIconRegistry.js').default
+ * }} FuroIconContextFactoryParams
+ */