@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroStepper/FuroStepperContext.js

@@ -0,0 +1,481 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+const DEFAULT_ORIENTATION = 'horizontal'
+const FIRST_STEP = 1
+
+/**
+ * Context class for FuroStepper organism.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroStepperContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroStepperContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroStepperContext ? X : never} T, X
+   * @override
+   * @param {FuroStepperContextFactoryParams} 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 {FuroStepperContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      activeValueRef: ref(null),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   STEP_CHANGE: 'step:change'
+   *   UPDATE_VALUE: 'update:value'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      STEP_CHANGE: 'step:change',
+      UPDATE_VALUE: 'update:value',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'step:change': (payload: {
+   *     value: number
+   *   }) => void
+   *   'update:value': (value: number) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.STEP_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_VALUE]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroStepperContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroStepperContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal active step ref (uncontrolled mode).
+   *
+   * @returns {import('vue').Ref<number | null>}
+   */
+  get activeValueRef () {
+    return this.refHash.activeValueRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {NonNullable<Props['parcel']>}
+   */
+  get parcel () {
+    return {
+      steps: [],
+      orientation: DEFAULT_ORIENTATION,
+      linear: false,
+      showPanels: true,
+      disabled: false,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Normalized per-step entries for rendering. The `step` is the 1-based
+   * position consumed by the underlying primitive; `value` is the stable
+   * identifier used for slot names and keys.
+   *
+   * @returns {Array<StepEntry>}
+   */
+  get stepEntries () {
+    return (this.parcel?.steps ?? [])
+      .map((it, index) => ({
+        step: index + FIRST_STEP,
+        value: it.value,
+        title: it.title ?? '',
+        description: it.description ?? null,
+        disabled: Boolean(it.disabled),
+        panelSlotName: it.slotName ?? String(it.value),
+        indicatorSlotName: `indicator-${it.value}`,
+        titleSlotName: `title-${it.value}`,
+      }))
+  }
+
+  /**
+   * Total number of steps.
+   *
+   * @returns {number}
+   */
+  get stepCount () {
+    return this.stepEntries.length
+  }
+
+  /**
+   * Whether the active step is controlled via `parcel.value`.
+   *
+   * @returns {boolean}
+   */
+  isControlled () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'value')
+  }
+
+  /**
+   * Whether the whole stepper is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    const disabledByParcel = Boolean(this.parcel?.disabled)
+    const disabledByAttrs = this.hasBooleanAttribute({ name: 'disabled' })
+
+    return disabledByParcel || disabledByAttrs
+  }
+
+  /**
+   * Whether the stepper lays out vertically.
+   *
+   * @returns {boolean}
+   */
+  isVertical () {
+    return this.extractOrientation() === 'vertical'
+  }
+
+  /**
+   * Whether steps must be completed in order (no forward jumps).
+   *
+   * @returns {boolean}
+   */
+  isLinear () {
+    return this.parcel?.linear === true
+  }
+
+  /**
+   * Whether step panels render. When false, the component is an indicator
+   * strip only (e.g. the active value drives an external form region).
+   *
+   * @returns {boolean}
+   */
+  shouldShowPanels () {
+    return this.parcel?.showPanels !== false
+  }
+
+  /**
+   * Resolve the layout orientation.
+   *
+   * @returns {'horizontal' | 'vertical'}
+   */
+  extractOrientation () {
+    return this.parcel?.orientation
+      ?? DEFAULT_ORIENTATION
+  }
+
+  /**
+   * Resolve the step number of the first step, if any.
+   *
+   * @returns {number | null}
+   */
+  extractFirstStepValue () {
+    return this.stepEntries[0]?.step
+      ?? null
+  }
+
+  /**
+   * Resolve the active step number for the root host element.
+   * `parcel.value` takes precedence; otherwise the internal ref,
+   * falling back to the first step.
+   *
+   * @returns {number | null}
+   */
+  extractActiveValue () {
+    if (this.isControlled()) {
+      return this.parcel?.value
+        ?? null
+    }
+
+    return this.activeValueRef.value
+      ?? this.extractFirstStepValue()
+  }
+
+  /**
+   * Extract attributes for the root host element.
+   * The `modelValue` key is only included when an active step exists, so the
+   * primitive stays uncontrolled when there are no steps.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const optionalAttributes = this.buildOptionalRootAttributes()
+
+    return {
+      orientation: this.extractOrientation(),
+      linear: this.isLinear(),
+      ...optionalAttributes,
+    }
+  }
+
+  /**
+   * Build the optional root attributes that are only included when present.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  buildOptionalRootAttributes () {
+    const entries = [
+      ['modelValue', this.extractActiveValue()],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Extract root class names.
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractRootClassNames () {
+    return {
+      'unit-stepper': true,
+      vertical: this.isVertical(),
+      linear: this.isLinear(),
+      disabled: this.isDisabled(),
+    }
+  }
+
+  /**
+   * Whether a given step is the active one.
+   *
+   * @param {{
+   *   step: number
+   * }} params
+   * @returns {boolean}
+   */
+  isActiveStep ({
+    step,
+  }) {
+    return this.extractActiveValue() === step
+  }
+
+  /**
+   * Whether a given step precedes the active one (visually completed).
+   *
+   * @param {{
+   *   step: number
+   * }} params
+   * @returns {boolean}
+   */
+  isCompletedStep ({
+    step,
+  }) {
+    const activeValue = this.extractActiveValue()
+
+    if (activeValue === null) {
+      return false
+    }
+
+    return step < activeValue
+  }
+
+  /**
+   * Whether a separator renders after a given index.
+   *
+   * @param {{
+   *   index: number
+   * }} params
+   * @returns {boolean}
+   */
+  hasSeparatorAfter ({
+    index,
+  }) {
+    return index < this.stepCount - 1
+  }
+
+  /**
+   * Handle active-step changes from the root host element.
+   *
+   * @param {{
+   *   value: number
+   * }} params
+   */
+  onStepChange ({
+    value,
+  }) {
+    if (!this.isControlled()) {
+      this.activeValueRef.value = value
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_VALUE,
+      value
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.STEP_CHANGE,
+      {
+        value,
+      }
+    )
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroStepperContext ? X : never} T, X
+   * @override
+   * @returns {T} For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    return this
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     activeValueRef: import('vue').Ref<number | null>
+ *   }
+ * }} FuroStepperContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroStepperContextParams, 'refHash'> & {
+ *   refHash?: FuroStepperContextParams['refHash']
+ * }} FuroStepperContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroStepperContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroStepperParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroStepper>`.
+ * JSON-serializable only. Not an open passthrough to the internal stepper primitive.
+ *
+ * @typedef {{
+ *   steps?: Array<FuroStepperStep>
+ *   value?: number | null
+ *   orientation?: 'horizontal' | 'vertical'
+ *   linear?: boolean
+ *   showPanels?: boolean
+ *   disabled?: boolean
+ * }} FuroStepperParcel
+ */
+
+/**
+ * @typedef {{
+ *   value: string | number
+ *   title?: string
+ *   description?: string
+ *   slotName?: string
+ *   disabled?: boolean
+ * }} FuroStepperStep
+ */
+
+/**
+ * @typedef {{
+ *   step: number
+ *   value: string | number
+ *   title: string
+ *   description: string | null
+ *   disabled: boolean
+ *   panelSlotName: string
+ *   indicatorSlotName: string
+ *   titleSlotName: string
+ * }} StepEntry
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroStepperEmitHash, FuroStepperSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroStepperContext.EMIT_EVENT_HASH} FuroStepperEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<Record<string, {
+ *   value?: string | number
+ *   step?: number
+ *   completed?: boolean
+ * }>>} FuroStepperSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroStepperContext
+ * }} FuroStepperSetup
+ */