@openreachtech/furo-vue 1.3.1

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

@@ -0,0 +1,617 @@
+import {
+  markRaw,
+  reactive,
+} from 'vue'
+
+import {
+  Icon as OfflineIcon,
+  addCollection,
+  addIcon,
+} from '@iconify/vue/offline'
+
+import {
+  FURO_ICON_COLLECTION,
+} from './furoIconData.js'
+
+/**
+ * Realm-wide key, so duplicate copies of this module still reach one registry.
+ */
+const SHARED_INSTANCE_KEY = Symbol.for('@openreachtech/furo-vue/iconRegistry')
+
+const SET_NUMERIC_PROPERTIES = [
+  'width',
+  'height',
+  'left',
+  'top',
+]
+
+const ICON_NUMERIC_PROPERTIES = [
+  ...SET_NUMERIC_PROPERTIES,
+  'rotate',
+]
+
+/**
+ * Registry of every icon name `<FuroIcon>` can draw. Resolution is offline, so
+ * recording what was registered is what makes an undrawable name detectable.
+ */
+export default class FuroIconRegistry {
+  /**
+   * Constructor.
+   *
+   * @param {{
+   *   stateReactive: FuroIconRegistryState
+   *   iconStorage: IconStorage
+   * }} params - Parameters of this constructor.
+   */
+  constructor ({
+    stateReactive,
+    iconStorage,
+  }) {
+    this.stateReactive = stateReactive
+    this.iconStorage = iconStorage
+  }
+
+  /**
+   * Factory method.
+   *
+   * @param {{
+   *   stateReactive?: FuroIconRegistryState
+   *   iconStorage?: IconStorage
+   * }} [params] - Parameters of this factory method.
+   * @returns {FuroIconRegistry} An instance of this class.
+   */
+  static create ({
+    stateReactive = this.buildStateReactive(),
+    iconStorage = this.createIconStorage(),
+  } = {}) {
+    return new this({
+      stateReactive,
+      iconStorage,
+    })
+  }
+
+  /**
+   * Resolve the one registry shared by every copy of this module in the realm.
+   *
+   * @returns {FuroIconRegistry} The shared registry.
+   */
+  static resolveSharedInstance () {
+    globalThis[SHARED_INSTANCE_KEY] ??= this.createSharedInstance()
+
+    return globalThis[SHARED_INSTANCE_KEY]
+  }
+
+  /**
+   * Create the shared registry, the library's own icons already registered.
+   *
+   * @returns {FuroIconRegistry} An instance of this class.
+   */
+  static createSharedInstance () {
+    return this.create()
+      .registerIconSet({
+        iconSet: FURO_ICON_COLLECTION,
+      })
+  }
+
+  /**
+   * Build the reactive state (registered names + the optional resolver and renderer).
+   *
+   * @returns {FuroIconRegistryState} Reactive state.
+   */
+  static buildStateReactive () {
+    return reactive({
+      registeredNames: new Set(),
+      resolver: null,
+      renderer: null,
+    })
+  }
+
+  /**
+   * Create the bridge to the underlying renderer's icon storage.
+   *
+   * @returns {IconStorage} Storage bridge.
+   */
+  static createIconStorage () {
+    return {
+      registerSet: addCollection,
+      registerIcon: addIcon,
+    }
+  }
+
+  /**
+   * Build the set shape the underlying storage accepts, which stores nothing
+   * from a set carrying no `prefix`.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   * }} params - Parameters of this method.
+   * @returns {IconSet} Storable icon set.
+   */
+  static buildStorableIconSet ({
+    iconSet,
+  }) {
+    const prefix = this.extractIconSetPrefix({
+      iconSet,
+    })
+
+    return {
+      ...iconSet,
+      prefix,
+    }
+  }
+
+  /**
+   * Extract the prefix a set is stored under, empty unless it carries one the
+   * storage accepts.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   * }} params - Parameters of this method.
+   * @returns {string} Prefix, empty when the set carries none.
+   */
+  static extractIconSetPrefix ({
+    iconSet,
+  }) {
+    if (typeof iconSet?.prefix !== 'string') {
+      return ''
+    }
+
+    return iconSet.prefix
+  }
+
+  /**
+   * Generate what every name of a set is stored under, empty for a set carrying
+   * no prefix, so its already-prefixed keys stay verbatim.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   * }} params - Parameters of this method.
+   * @returns {string} Storage prefix.
+   */
+  static generateStoragePrefix ({
+    iconSet,
+  }) {
+    const prefix = this.extractIconSetPrefix({
+      iconSet,
+    })
+
+    if (prefix === '') {
+      return ''
+    }
+
+    return `${prefix}:`
+  }
+
+  /**
+   * Extract the full names an icon set carries, its prefix applied.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   * }} params - Parameters of this method.
+   * @returns {Array<string>} Full icon names.
+   */
+  static extractIconSetNames ({
+    iconSet,
+  }) {
+    const bareNames = [
+      ...Object.keys(iconSet?.icons ?? {}),
+      ...Object.keys(iconSet?.aliases ?? {}),
+    ]
+
+    const storagePrefix = this.generateStoragePrefix({
+      iconSet,
+    })
+
+    return bareNames.map(bareName => `${storagePrefix}${bareName}`)
+  }
+
+  /**
+   * Whether the storage keeps the set at all, which it refuses wholesale over
+   * one bodyless icon or one alias pointing outside the set.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   * }} params - Parameters of this method.
+   * @returns {boolean} Whether the set is storable.
+   */
+  static isStorableIconSet ({
+    iconSet,
+  }) {
+    const icons = iconSet?.icons
+      ?? null
+
+    if (icons === null) {
+      return false
+    }
+
+    const hasNumericSetDimensions = this.hasNumericDimensions({
+      shape: iconSet,
+      propertyNames: SET_NUMERIC_PROPERTIES,
+    })
+
+    const isEveryIconDrawable = Object.values(icons)
+      .every(icon => this.isDrawableIcon({
+        icon,
+      }))
+
+    const isEveryAliasResolvable = Object.values(iconSet?.aliases ?? {})
+      .every(alias => this.hasIconSetEntry({
+        iconSet,
+        name: alias?.parent ?? '',
+      }))
+
+    return hasNumericSetDimensions
+      && isEveryIconDrawable
+      && isEveryAliasResolvable
+  }
+
+  /**
+   * Whether every dimension a shape declares is a number, which the storage
+   * demands before it keeps the set carrying it.
+   *
+   * @param {{
+   *   shape: Record<string, *>
+   *   propertyNames: Array<string>
+   * }} params - Parameters of this method.
+   * @returns {boolean} Whether every declared dimension is numeric.
+   */
+  static hasNumericDimensions ({
+    shape,
+    propertyNames,
+  }) {
+    return propertyNames
+      .filter(propertyName => Object.hasOwn(shape ?? {}, propertyName))
+      .every(propertyName => typeof shape[propertyName] === 'number')
+  }
+
+  /**
+   * Whether an icon carries what the renderer draws.
+   *
+   * @param {{
+   *   icon: IconShape
+   * }} params - Parameters of this method.
+   * @returns {boolean} Whether the icon is drawable.
+   */
+  static isDrawableIcon ({
+    icon,
+  }) {
+    if (typeof icon?.body !== 'string') {
+      return false
+    }
+
+    return this.hasNumericDimensions({
+      shape: icon,
+      propertyNames: ICON_NUMERIC_PROPERTIES,
+    })
+  }
+
+  /**
+   * Whether a set carries a name, as an icon or as an alias.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   *   name: string
+   * }} params - Parameters of this method.
+   * @returns {boolean} Whether the set carries the name.
+   */
+  static hasIconSetEntry ({
+    iconSet,
+    name,
+  }) {
+    return Object.hasOwn(iconSet?.icons ?? {}, name)
+      || Object.hasOwn(iconSet?.aliases ?? {}, name)
+  }
+
+  /**
+   * Build the renderer shape the state keeps, a component unproxied so
+   * `reactive()` leaves its identity alone, a global name kept verbatim.
+   *
+   * @param {{
+   *   component: IconRenderer | null
+   * }} params - Parameters of this method.
+   * @returns {IconRenderer | null} Storable renderer.
+   */
+  static buildStorableRenderer ({
+    component,
+  }) {
+    if (!component) {
+      return null
+    }
+
+    if (typeof component === 'string') {
+      return component
+    }
+
+    return markRaw(component)
+  }
+
+  /**
+   * Create the renderer that draws every registered name.
+   *
+   * @returns {import('vue').Component} The library's own renderer.
+   */
+  static createOfflineRenderer () {
+    return OfflineIcon
+  }
+
+  /**
+   * get: the constructor of this instance.
+   *
+   * @returns {typeof FuroIconRegistry} The constructor.
+   */
+  get Ctor () {
+    return /** @type {typeof FuroIconRegistry} */ (this.constructor)
+  }
+
+  /**
+   * Register a whole icon set, so every name it carries becomes drawable. A set
+   * the storage refuses records nothing, since none of its names would draw.
+   *
+   * @param {{
+   *   iconSet: IconSet
+   * }} params - Parameters of this method.
+   * @returns {FuroIconRegistry} For method chaining.
+   */
+  registerIconSet ({
+    iconSet,
+  }) {
+    if (!this.Ctor.isStorableIconSet({ iconSet })) {
+      return this
+    }
+
+    this.iconStorage.registerSet(
+      this.Ctor.buildStorableIconSet({
+        iconSet,
+      }),
+      this.Ctor.generateStoragePrefix({
+        iconSet,
+      })
+    )
+
+    return this.recordNames({
+      names: this.Ctor.extractIconSetNames({
+        iconSet,
+      }),
+    })
+  }
+
+  /**
+   * Register one icon under its full name, prefix included. An icon with no
+   * body records nothing, since the renderer would draw nothing for it.
+   *
+   * @param {{
+   *   name: string
+   *   icon: IconShape
+   * }} params - Parameters of this method.
+   * @returns {FuroIconRegistry} For method chaining.
+   */
+  registerIcon ({
+    name,
+    icon,
+  }) {
+    if (!this.Ctor.isDrawableIcon({ icon })) {
+      return this
+    }
+
+    this.iconStorage.registerIcon(name, icon)
+
+    return this.recordNames({
+      names: [
+        name,
+      ],
+    })
+  }
+
+  /**
+   * Record names as drawable.
+   *
+   * @param {{
+   *   names: Array<string>
+   * }} params - Parameters of this method.
+   * @returns {FuroIconRegistry} For method chaining.
+   */
+  recordNames ({
+    names,
+  }) {
+    this.stateReactive.registeredNames = new Set([
+      ...this.stateReactive.registeredNames,
+      ...names,
+    ])
+
+    return this
+  }
+
+  /**
+   * Install the resolver consulted for a name no registration covers.
+   *
+   * @param {{
+   *   resolver: IconResolver | null
+   * }} params - Parameters of this method.
+   * @returns {FuroIconRegistry} For method chaining.
+   */
+  useIconResolver ({
+    resolver,
+  }) {
+    this.stateReactive.resolver = resolver
+
+    return this
+  }
+
+  /**
+   * Install the renderer for names the registry lacks, `null` to uninstall.
+   *
+   * @param {{
+   *   component: IconRenderer | null
+   * }} params - Parameters of this method.
+   * @returns {FuroIconRegistry} For method chaining.
+   */
+  useIconRenderer ({
+    component,
+  }) {
+    this.stateReactive.renderer = this.Ctor.buildStorableRenderer({
+      component,
+    })
+
+    return this
+  }
+
+  /**
+   * Whether a renderer is installed.
+   *
+   * @returns {boolean} Whether a renderer is installed.
+   */
+  hasIconRenderer () {
+    return this.extractIconRenderer() !== null
+  }
+
+  /**
+   * Extract the installed renderer.
+   *
+   * @returns {IconRenderer | null} Renderer, or null when none is installed.
+   */
+  extractIconRenderer () {
+    return this.stateReactive.renderer
+  }
+
+  /**
+   * Extract the renderer that draws every registered name.
+   *
+   * @returns {import('vue').Component} The library's own renderer.
+   */
+  extractOfflineRenderer () {
+    return this.Ctor.createOfflineRenderer()
+  }
+
+  /**
+   * Whether a name draws anything, whether it was registered or the installed
+   * resolver answers it.
+   *
+   * @param {{
+   *   name: string | null
+   * }} params - Parameters of this method.
+   * @returns {boolean} Whether the name resolves.
+   */
+  hasIcon ({
+    name,
+  }) {
+    return this.findRenderableIcon({
+      name,
+    }) !== null
+  }
+
+  /**
+   * Find what the renderer should draw for a name.
+   *
+   * @param {{
+   *   name: string | null
+   * }} params - Parameters of this method.
+   * @returns {string | IconShape | null} A registered name, resolved icon data, or null.
+   */
+  findRenderableIcon ({
+    name,
+  }) {
+    if (name === null) {
+      return null
+    }
+
+    if (this.hasRegisteredIcon({ name })) {
+      return name
+    }
+
+    return this.resolveIcon({
+      name,
+    })
+  }
+
+  /**
+   * Whether a name was registered, leaving the resolver unasked.
+   *
+   * @param {{
+   *   name: string | null
+   * }} params - Parameters of this method.
+   * @returns {boolean} Whether the name is registered.
+   */
+  hasRegisteredIcon ({
+    name,
+  }) {
+    return this.stateReactive.registeredNames.has(name)
+  }
+
+  /**
+   * Resolve a name through the installed resolver, holding it to the same shape
+   * registration demands, so undrawable data stays detectable as unresolved.
+   *
+   * @param {{
+   *   name: string
+   * }} params - Parameters of this method.
+   * @returns {IconShape | null} Icon data, or null when nothing resolves it.
+   */
+  resolveIcon ({
+    name,
+  }) {
+    const {
+      resolver,
+    } = this.stateReactive
+
+    if (resolver === null) {
+      return null
+    }
+
+    const icon = resolver({ name })
+
+    if (!this.Ctor.isDrawableIcon({ icon })) {
+      return null
+    }
+
+    return icon
+  }
+}
+
+/**
+ * One icon's drawable data.
+ *
+ * @typedef {{
+ *   body: string
+ *   width?: number
+ *   height?: number
+ *   [key: string]: *
+ * }} IconShape
+ */
+
+/**
+ * A set of icons sharing one prefix and one set of defaults.
+ *
+ * @typedef {{
+ *   prefix?: string
+ *   width?: number
+ *   height?: number
+ *   icons: Record<string, IconShape>
+ *   aliases?: Record<string, *>
+ *   [key: string]: *
+ * }} IconSet
+ */
+
+/**
+ * @typedef {(params: { name: string }) => IconShape | null} IconResolver
+ */
+
+/**
+ * A renderer component, or the name one is globally registered under.
+ *
+ * @typedef {import('vue').Component | string} IconRenderer
+ */
+
+/**
+ * @typedef {{
+ *   registerSet: (iconSet: *, storagePrefix: string) => void
+ *   registerIcon: (name: string, icon: *) => void
+ * }} IconStorage
+ */
+
+/**
+ * @typedef {import('vue').Reactive<{
+ *   registeredNames: Set<string>
+ *   resolver: IconResolver | null
+ *   renderer: IconRenderer | null
+ * }>} FuroIconRegistryState
+ */

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

@@ -0,0 +1,101 @@
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+/**
+ * Context class for the catalogue renderer adapter, holding the one place its
+ * `name` / `size` map onto the underlying renderer's own properties.
+ *
+ * @extends {BaseFuroContext<null, Props, null>}
+ */
+export default class FuroIconifyRendererContext extends BaseFuroContext {
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroIconifyRendererContext ? X : never} T, X
+   * @override
+   * @param {FuroIconifyRendererContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      super.create({
+        props,
+        componentContext,
+      })
+    )
+  }
+
+  /**
+   * get: the icon name, collection prefix included.
+   *
+   * @returns {string | null} Icon name such as `mdi:home`, 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 attributes the underlying renderer expects.
+   *
+   * @returns {{
+   *   icon: string | null
+   *   width?: string | number
+   *   height?: string | number
+   * }} Renderer attributes.
+   */
+  extractRendererAttributes () {
+    return {
+      icon: this.name, // re-applied as the renderer's `icon` property, the ONE allowed mention
+      ...this.buildOptionalSizeAttributes(),
+    }
+  }
+
+  /**
+   * 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,
+      }
+  }
+}
+
+/**
+ * @typedef {{
+ *   name: string
+ *   size?: string | number | null
+ * }} Props
+ */
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams<Props>} FuroIconifyRendererContextParams
+ */
+
+/**
+ * @typedef {FuroIconifyRendererContextParams} FuroIconifyRendererContextFactoryParams
+ */