@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroEditableField/processors/EditorCollisionProcessor.js

@@ -0,0 +1,236 @@
+/**
+ * Processor for calculating floating editor position within a collision boundary.
+ */
+export default class EditorCollisionProcessor {
+  /**
+   * Constructor.
+   *
+   * @param {EditorCollisionProcessorParams} params - Parameters.
+   */
+  constructor ({
+    anchorRect,
+    boundaryRect,
+    editorWidth,
+    editorHeight,
+  }) {
+    this.anchorRect = anchorRect
+    this.boundaryRect = boundaryRect
+    this.editorWidth = editorWidth
+    this.editorHeight = editorHeight
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof EditorCollisionProcessor ? X : never} T, X
+   * @param {EditorCollisionProcessorFactoryParams} params - Parameters.
+   * @returns {InstanceType<T>}
+   * @this {T}
+   */
+  static create ({
+    anchorRect,
+    boundaryRect,
+    editorWidth,
+    editorHeight,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        anchorRect,
+        boundaryRect,
+        editorWidth,
+        editorHeight,
+      })
+    )
+  }
+
+  /**
+   * Extract viewport collision boundary edges.
+   *
+   * @returns {CollisionBoundaryEdges}
+   */
+  static extractViewportCollisionBoundaryEdges () {
+    return {
+      leftBoundary: 0,
+      rightBoundary: document.documentElement.clientWidth,
+      topBoundary: 0,
+      bottomBoundary: document.documentElement.clientHeight,
+    }
+  }
+
+  /**
+   * Extract collision boundary edges.
+   *
+   * @param {{
+   *   boundaryRect?: DOMRect
+   * }} params - Parameters.
+   * @returns {CollisionBoundaryEdges}
+   */
+  static extractCollisionBoundaryEdges ({
+    boundaryRect,
+  }) {
+    if (!boundaryRect) {
+      return EditorCollisionProcessor.extractViewportCollisionBoundaryEdges()
+    }
+
+    return {
+      leftBoundary: boundaryRect.left,
+      rightBoundary: boundaryRect.right,
+      topBoundary: boundaryRect.top,
+      bottomBoundary: boundaryRect.bottom,
+    }
+  }
+
+  /**
+   * Normalize editor offset within boundary range.
+   *
+   * @param {{
+   *   preferredOffset: number
+   *   boundaryStart: number
+   *   boundaryEnd: number
+   *   editorSize: number
+   * }} params - Parameters.
+   * @returns {number}
+   */
+  static normalizeEditorOffsetWithinBoundary ({
+    preferredOffset,
+    boundaryStart,
+    boundaryEnd,
+    editorSize,
+  }) {
+    const maximumOffset = boundaryEnd - editorSize
+
+    if (maximumOffset < boundaryStart) {
+      return boundaryStart
+    }
+
+    return Math.min(
+      Math.max(boundaryStart, preferredOffset),
+      maximumOffset
+    )
+  }
+
+  /**
+   * Extract collision boundary edges for this processor.
+   *
+   * @returns {CollisionBoundaryEdges}
+   */
+  extractCollisionBoundaryEdges () {
+    return EditorCollisionProcessor.extractCollisionBoundaryEdges({
+      boundaryRect: this.boundaryRect,
+    })
+  }
+
+  /**
+   * Calculate editor left offset.
+   *
+   * @param {{
+   *   leftBoundary: number
+   *   rightBoundary: number
+   * }} params - Parameters.
+   * @returns {string}
+   */
+  calculateEditorLeftOffset ({
+    leftBoundary,
+    rightBoundary,
+  }) {
+    const shouldFlipLeft = this.anchorRect.left + this.editorWidth > rightBoundary
+
+    const preferredLeft = shouldFlipLeft
+      ? this.anchorRect.right - this.editorWidth
+      : this.anchorRect.left
+
+    const normalizedLeft = EditorCollisionProcessor.normalizeEditorOffsetWithinBoundary({
+      preferredOffset: preferredLeft,
+      boundaryStart: leftBoundary,
+      boundaryEnd: rightBoundary,
+      editorSize: this.editorWidth,
+    })
+
+    return `${normalizedLeft}px`
+  }
+
+  /**
+   * Calculate editor top offset.
+   *
+   * @param {{
+   *   topBoundary: number
+   *   bottomBoundary: number
+   * }} params - Parameters.
+   * @returns {string}
+   */
+  calculateEditorTopOffset ({
+    topBoundary,
+    bottomBoundary,
+  }) {
+    const shouldFlipUp = this.anchorRect.top + this.editorHeight > bottomBoundary
+
+    const preferredTop = shouldFlipUp
+      ? this.anchorRect.bottom - this.editorHeight
+      : this.anchorRect.top
+
+    const normalizedTop = EditorCollisionProcessor.normalizeEditorOffsetWithinBoundary({
+      preferredOffset: preferredTop,
+      boundaryStart: topBoundary,
+      boundaryEnd: bottomBoundary,
+      editorSize: this.editorHeight,
+    })
+
+    return `${normalizedTop}px`
+  }
+
+  /**
+   * Generate editor position style.
+   *
+   * @returns {{
+   *   position: 'fixed'
+   *   top: string
+   *   left: string
+   *   width: string
+   *   zIndex: string
+   * }}
+   */
+  generateEditorPositionStyle () {
+    const {
+      leftBoundary,
+      rightBoundary,
+      topBoundary,
+      bottomBoundary,
+    } = this.extractCollisionBoundaryEdges()
+
+    return {
+      position: 'fixed',
+      top: this.calculateEditorTopOffset({
+        topBoundary,
+        bottomBoundary,
+      }),
+      left: this.calculateEditorLeftOffset({
+        leftBoundary,
+        rightBoundary,
+      }),
+      width: `${this.anchorRect.width}px`,
+      zIndex: 'calc(var(--value-z-index-layer-overlay) + 0)',
+    }
+  }
+}
+
+/**
+ * @typedef {{
+ *   leftBoundary: number
+ *   rightBoundary: number
+ *   topBoundary: number
+ *   bottomBoundary: number
+ * }} CollisionBoundaryEdges
+ */
+
+/**
+ * @typedef {{
+ *   anchorRect: DOMRect
+ *   boundaryRect?: DOMRect
+ *   editorWidth: number
+ *   editorHeight: number
+ * }} EditorCollisionProcessorParams
+ */
+
+/**
+ * @typedef {EditorCollisionProcessorParams} EditorCollisionProcessorFactoryParams
+ */

package/lib/components/molecules/FuroEditableField/processors/ObjectProcessor.js

@@ -0,0 +1,101 @@
+/**
+ * Processor for comparing two values with deep equality semantics.
+ */
+export default class ObjectProcessor {
+  /**
+   * Constructor.
+   *
+   * @param {ObjectProcessorParams} params - Parameters.
+   */
+  constructor ({
+    leftValue,
+    rightValue,
+  }) {
+    this.leftValue = leftValue
+    this.rightValue = rightValue
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof ObjectProcessor ? X : never} T, X
+   * @param {ObjectProcessorFactoryParams} params - Parameters.
+   * @returns {InstanceType<T>}
+   * @this {T}
+   */
+  static create ({
+    leftValue,
+    rightValue,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        leftValue,
+        rightValue,
+      })
+    )
+  }
+
+  /**
+   * Whether left and right values are deeply equal.
+   *
+   * @returns {boolean}
+   */
+  areDeepEqual () {
+    if (Object.is(this.leftValue, this.rightValue)) {
+      return true
+    }
+
+    if (!this.areBothObjects()) {
+      return false
+    }
+
+    return this.haveSameDeepObjectEntries()
+  }
+
+  /**
+   * Whether both values are non-null objects.
+   *
+   * @returns {boolean}
+   */
+  areBothObjects () {
+    return typeof this.leftValue === 'object'
+      && typeof this.rightValue === 'object'
+      && this.leftValue !== null
+      && this.rightValue !== null
+  }
+
+  /**
+   * Whether both objects have the same entries with deep equality.
+   *
+   * @returns {boolean}
+   */
+  haveSameDeepObjectEntries () {
+    const leftObject = /** @type {Record<string, unknown>} */ (this.leftValue)
+    const rightObject = /** @type {Record<string, unknown>} */ (this.rightValue)
+    const keys = Object.keys(leftObject)
+
+    if (keys.length !== Object.keys(rightObject).length) {
+      return false
+    }
+
+    return keys.every(key =>
+      Object.hasOwn(rightObject, key)
+      && ObjectProcessor.create({
+        leftValue: leftObject[key],
+        rightValue: rightObject[key],
+      })
+        .areDeepEqual()
+    )
+  }
+}
+
+/**
+ * @typedef {{
+ *   leftValue: unknown
+ *   rightValue: unknown
+ * }} ObjectProcessorParams
+ */
+
+/**
+ * @typedef {ObjectProcessorParams} ObjectProcessorFactoryParams
+ */

package/lib/components/molecules/FuroEmptyState/FuroEmptyState.vue

@@ -0,0 +1,124 @@
+<script>
+import {
+  defineComponent,
+} from 'vue'
+
+import FuroEmptyStateContext from './FuroEmptyStateContext.js'
+
+export default defineComponent({
+  name: 'FuroEmptyState',
+  inheritAttrs: false,
+
+  props: {
+    parcel: {
+      /** @type {import('vue').PropType<import('./FuroEmptyStateContext.js').Props['parcel']>} */
+      type: [
+        Object,
+        null,
+      ],
+      default: null,
+    },
+  },
+
+  /**
+   * Setup of this component.
+   *
+   * @param {import('./FuroEmptyStateContext.js').Props} props - Props.
+   * @param {import('vue').SetupContext} componentContext - Setup context.
+   * @returns {{ context: FuroEmptyStateContext }} Render context.
+   */
+  setup (
+    props,
+    componentContext
+  ) {
+    const context = FuroEmptyStateContext.create({
+      props,
+      componentContext,
+    })
+      .setupComponent()
+
+    return {
+      context,
+    }
+  },
+})
+</script>
+
+<template>
+  <div
+    class="unit-empty-state"
+    v-bind="$attrs"
+  >
+    <div
+      v-if="$slots.icon"
+      class="icon"
+    >
+      <slot name="icon" />
+    </div>
+
+    <p
+      v-if="context.title"
+      class="title"
+    >
+      {{ context.title }}
+    </p>
+
+    <p
+      v-if="context.description"
+      class="description"
+    >
+      {{ context.description }}
+    </p>
+
+    <div
+      v-if="$slots.action"
+      class="actions"
+    >
+      <slot name="action" />
+    </div>
+  </div>
+</template>
+
+<style>
+@layer furo {
+  .unit-empty-state {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--size-space-small);
+
+    padding-block: var(--size-space-2x-large);
+    padding-inline: var(--size-space-large);
+
+    color: var(--color-muted-foreground);
+    text-align: center;
+  }
+
+  .unit-empty-state > .icon {
+    display: flex;
+
+    color: var(--color-muted-foreground);
+    font-size: 2rem;
+  }
+
+  .unit-empty-state > .title {
+    margin: 0;
+
+    color: var(--color-foreground);
+    font: var(--font-headline-small);
+  }
+
+  .unit-empty-state > .description {
+    margin: 0;
+
+    font: var(--font-body-small);
+  }
+
+  .unit-empty-state > .actions {
+    display: flex;
+    gap: var(--size-space-small);
+
+    margin-block-start: var(--size-space-small);
+  }
+}
+</style>

package/lib/components/molecules/FuroEmptyState/FuroEmptyStateContext.js

@@ -0,0 +1,42 @@
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+/**
+ * Context class for FuroEmptyState molecule.
+ *
+ * Presentational placeholder shown when a region has no content to display
+ * (no views, no records, nothing found). Title and description text come from
+ * the parcel so the consumer owns the wording; an icon and action controls are
+ * supplied via slots. It carries no value and emits nothing.
+ *
+ * @extends {BaseFuroContext<null, Props, null>}
+ */
+export default class FuroEmptyStateContext extends BaseFuroContext {
+  /**
+   * get: heading text.
+   *
+   * @returns {string | null} Title, or null when the consumer supplies none.
+   */
+  get title () {
+    return this.parcel?.title
+      ?? null
+  }
+
+  /**
+   * get: supporting description text.
+   *
+   * @returns {string | null} Description, or null when the consumer supplies none.
+   */
+  get description () {
+    return this.parcel?.description
+      ?? null
+  }
+}
+
+/**
+ * @typedef {{
+ *   parcel: {
+ *     title?: string
+ *     description?: string
+ *   } | null
+ * }} Props
+ */

package/lib/components/molecules/FuroErrorState/FuroErrorState.vue

@@ -0,0 +1,125 @@
+<script>
+import {
+  defineComponent,
+} from 'vue'
+
+import FuroErrorStateContext from './FuroErrorStateContext.js'
+
+export default defineComponent({
+  name: 'FuroErrorState',
+  inheritAttrs: false,
+
+  props: {
+    parcel: {
+      /** @type {import('vue').PropType<import('./FuroErrorStateContext.js').Props['parcel']>} */
+      type: [
+        Object,
+        null,
+      ],
+      default: null,
+    },
+  },
+
+  /**
+   * Setup of this component.
+   *
+   * @param {import('./FuroErrorStateContext.js').Props} props - Props.
+   * @param {import('vue').SetupContext} componentContext - Setup context.
+   * @returns {{ context: FuroErrorStateContext }} Render context.
+   */
+  setup (
+    props,
+    componentContext
+  ) {
+    const context = FuroErrorStateContext.create({
+      props,
+      componentContext,
+    })
+      .setupComponent()
+
+    return {
+      context,
+    }
+  },
+})
+</script>
+
+<template>
+  <div
+    class="unit-error-state"
+    role="alert"
+    v-bind="$attrs"
+  >
+    <div
+      v-if="$slots.icon"
+      class="icon"
+    >
+      <slot name="icon" />
+    </div>
+
+    <p
+      v-if="context.title"
+      class="title"
+    >
+      {{ context.title }}
+    </p>
+
+    <p
+      v-if="context.description"
+      class="description"
+    >
+      {{ context.description }}
+    </p>
+
+    <div
+      v-if="$slots.action"
+      class="actions"
+    >
+      <slot name="action" />
+    </div>
+  </div>
+</template>
+
+<style>
+@layer furo {
+  .unit-error-state {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--size-space-small);
+
+    padding-block: var(--size-space-2x-large);
+    padding-inline: var(--size-space-large);
+
+    color: var(--color-muted-foreground);
+    text-align: center;
+  }
+
+  .unit-error-state > .icon {
+    display: flex;
+
+    color: var(--color-destructive);
+    font-size: 2rem;
+  }
+
+  .unit-error-state > .title {
+    margin: 0;
+
+    color: var(--color-foreground);
+    font: var(--font-headline-small);
+  }
+
+  .unit-error-state > .description {
+    margin: 0;
+
+    font: var(--font-body-small);
+  }
+
+  .unit-error-state > .actions {
+    display: flex;
+    gap: var(--size-space-small);
+
+    margin-block-start: var(--size-space-small);
+  }
+}
+</style>

package/lib/components/molecules/FuroErrorState/FuroErrorStateContext.js

@@ -0,0 +1,42 @@
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+/**
+ * Context class for FuroErrorState molecule.
+ *
+ * Presentational placeholder shown when a region fails to load (a fetch error,
+ * a failed request). Title and description text come from the parcel so the
+ * consumer owns the wording; an icon and action controls (typically a retry
+ * button) are supplied via slots. It carries no value and emits nothing.
+ *
+ * @extends {BaseFuroContext<null, Props, null>}
+ */
+export default class FuroErrorStateContext extends BaseFuroContext {
+  /**
+   * get: heading text.
+   *
+   * @returns {string | null} Title, or null when the consumer supplies none.
+   */
+  get title () {
+    return this.parcel?.title
+      ?? null
+  }
+
+  /**
+   * get: supporting description text.
+   *
+   * @returns {string | null} Description, or null when the consumer supplies none.
+   */
+  get description () {
+    return this.parcel?.description
+      ?? null
+  }
+}
+
+/**
+ * @typedef {{
+ *   parcel: {
+ *     title?: string
+ *     description?: string
+ *   } | null
+ * }} Props
+ */