@openreachtech/furo-vue 1.3.1

package/lib/components/atoms/FuroCheckbox/FuroCheckboxContext.js

@@ -0,0 +1,682 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import CheckboxEmitPayload from './CheckboxEmitPayload.js'
+
+/**
+ * Furo-owned parcel keys (not forwarded to Reka CheckboxRoot).
+ */
+const FURO_CHECKBOX_PARCEL_KEYS = new Set([
+  'value',
+  'indeterminate',
+  'invalid',
+  'disabled',
+  'required',
+  'size',
+])
+
+/**
+ * Context class for managing FuroCheckbox component.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroCheckboxContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroCheckboxContextParams} params
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroCheckboxContext ? X : never} T, X
+   * @override
+   * @param {FuroCheckboxContextFactoryParams} 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
+   */
+  static buildRefHash () {
+    return {
+      internalValueRef: ref(false),
+      checkboxRootElementRef: ref(null),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   CHANGE_VALUE: 'change-value'
+   *   UPDATE_VALUE: 'update:value'
+   *   UPDATE_INDETERMINATE: 'update:indeterminate'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      CHANGE_VALUE: 'change-value',
+      UPDATE_VALUE: 'update:value',
+      UPDATE_INDETERMINATE: 'update:indeterminate',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./CheckboxEmitPayload.js').default) => void
+   *   'update:value': (value: FuroCheckboxValue) => void
+   *   'update:indeterminate': (indeterminate: boolean) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.CHANGE_VALUE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_VALUE]: value => {},
+      [this.EMIT_EVENT_NAME.UPDATE_INDETERMINATE]: indeterminate => {},
+    }
+  }
+
+  /**
+   * Get indeterminate value.
+   *
+   * @returns {'indeterminate'}
+   */
+  static get INDETERMINATE_VALUE () {
+    return 'indeterminate'
+  }
+
+  /**
+   * Default checkbox box size (width and height).
+   *
+   * @returns {string}
+   */
+  static get DEFAULT_CHECKBOX_SIZE () {
+    return '1.125rem'
+  }
+
+  /**
+   * Default indicator icon size (proportional to {@link DEFAULT_CHECKBOX_SIZE}).
+   *
+   * @returns {string}
+   */
+  static get DEFAULT_CHECKBOX_ICON_SIZE () {
+    return '1rem'
+  }
+
+  /**
+   * Icon size as a fraction of box size (1rem / 1.125rem).
+   *
+   * @returns {number}
+   */
+  static get CHECKBOX_ICON_SIZE_RATIO () {
+    return 8 / 9
+  }
+
+  /**
+   * get: Constructor of `EmitPayload`.
+   *
+   * @returns {typeof CheckboxEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return CheckboxEmitPayload
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroCheckboxContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroCheckboxContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get the internal tri-state check state ref.
+   *
+   * @returns {import('vue').Ref<FuroCheckboxState>}
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Get checkbox root element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get checkboxRootElementRef () {
+    return this.refHash.checkboxRootElementRef
+  }
+
+  /**
+   * Parcel passed from parent via props (merged with defaults).
+   *
+   * @override
+   * @returns {FuroCheckboxParcel}
+   */
+  get parcel () {
+    return {
+      indeterminate: false,
+      invalid: false,
+      disabled: false,
+      required: false,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Whether the parent controls `parcel.value`.
+   *
+   * @returns {boolean}
+   */
+  isControlled () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'value')
+  }
+
+  /**
+   * Resolve the check state from parcel, attrs, and indeterminate flag.
+   *
+   * @returns {FuroCheckboxState}
+   */
+  resolveSyncedValue () {
+    if (this.parcel.indeterminate) {
+      return this.Ctor.INDETERMINATE_VALUE
+    }
+
+    if (!this.isControlled()) {
+      return this.resolveUncontrolledSyncedValue()
+    }
+
+    return this.resolveControlledSyncedValue()
+  }
+
+  /**
+   * Resolve controlled checked boolean from parcel or fallthrough attrs.
+   *
+   * @returns {FuroCheckboxValue}
+   */
+  resolveControlledSyncedValue () {
+    const { parcel: parcelSource } = this.props
+
+    const hasParcelValue = parcelSource !== null
+      && Object.hasOwn(parcelSource, 'value')
+
+    if (hasParcelValue) {
+      return parcelSource.value ?? false
+    }
+
+    const { value: attrsValue } = this.attrs ?? {}
+
+    if (attrsValue !== undefined) {
+      return Boolean(attrsValue)
+    }
+
+    return false
+  }
+
+  /**
+   * Resolve uncontrolled checkbox value (unchecked).
+   *
+   * @returns {FuroCheckboxValue}
+   */
+  resolveUncontrolledSyncedValue () {
+    return false
+  }
+
+  /**
+   * Extract checked boolean while internal model is indeterminate.
+   *
+   * @returns {FuroCheckboxValue}
+   */
+  extractCheckedWhileIndeterminate () {
+    if (this.isControlled()) {
+      return this.resolveControlledSyncedValue()
+    }
+
+    return false
+  }
+
+  /**
+   * Whether the given check state is indeterminate.
+   *
+   * @param {{
+   *   checkState: FuroCheckboxState
+   * }} params - Parameters.
+   * @returns {boolean}
+   */
+  isIndeterminateState ({
+    checkState,
+  }) {
+    return checkState === this.Ctor.INDETERMINATE_VALUE
+  }
+
+  /**
+   * Extract the checked boolean from a check state.
+   *
+   * @param {{
+   *   checkState: FuroCheckboxState
+   * }} params - Parameters.
+   * @returns {FuroCheckboxValue}
+   */
+  extractCheckedFromState ({
+    checkState,
+  }) {
+    if (this.isIndeterminateState({
+      checkState,
+    })) {
+      return this.extractCheckedWhileIndeterminate()
+    }
+
+    return /** @type {FuroCheckboxValue} */ (checkState)
+  }
+
+  /**
+   * Normalize a check-state change into public boolean channels.
+   *
+   * @param {{
+   *   rawValue: FuroCheckboxState
+   *   previousCheckState: FuroCheckboxState
+   * }} params - Parameters.
+   * @returns {{
+   *   checkState: FuroCheckboxState
+   *   value: FuroCheckboxValue
+   *   indeterminate: boolean
+   * }}
+   */
+  normalizeStateChange ({
+    rawValue,
+    previousCheckState,
+  }) {
+    const checkedBeforeChange = this.extractCheckedFromState({
+      checkState: previousCheckState,
+    })
+
+    const indeterminate = this.isIndeterminateState({
+      checkState: rawValue,
+    })
+
+    const value = indeterminate
+      ? checkedBeforeChange
+      : this.extractCheckedFromState({
+        checkState: rawValue,
+      })
+
+    return {
+      checkState: rawValue,
+      value,
+      indeterminate,
+    }
+  }
+
+  /**
+   * Whether the checkbox is invalid.
+   *
+   * @returns {boolean}
+   */
+  isInvalid () {
+    return Boolean(this.parcel.invalid)
+  }
+
+  /**
+   * Whether the checkbox is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    return Boolean(this.parcel.disabled)
+      || this.hasBooleanAttribute({ name: 'disabled' })
+  }
+
+  /**
+   * Whether the checkbox is required.
+   *
+   * @returns {boolean}
+   */
+  isRequired () {
+    return Boolean(this.parcel.required)
+      || this.hasBooleanAttribute({ name: 'required' })
+  }
+
+  /**
+   * Parse a simple CSS length (`rem`, `px`, `em`).
+   *
+   * @param {{
+   *   length: string
+   * }} params - Parameters.
+   * @returns {{ amount: number, unit: string } | null}
+   */
+  parseCssLength ({
+    length,
+  }) {
+    const extractUnitRegex = /^([\d.]+)(rem|px|em)$/u
+    const matched = extractUnitRegex.exec(length.trim())
+
+    if (!matched) {
+      return null
+    }
+
+    return {
+      amount: Number(matched.at(1)),
+      unit: matched.at(2) ?? 'rem',
+    }
+  }
+
+  /**
+   * Extract indicator icon size proportional to checkbox box size.
+   *
+   * @returns {string}
+   */
+  extractCheckboxIconSize () {
+    const boxSize = this.parcel.size
+      ?? this.Ctor.DEFAULT_CHECKBOX_SIZE
+
+    const parsedLength = this.parseCssLength({
+      length: boxSize,
+    })
+
+    if (!parsedLength) {
+      return this.Ctor.DEFAULT_CHECKBOX_ICON_SIZE
+    }
+
+    const iconAmount = parsedLength.amount
+      * this.Ctor.CHECKBOX_ICON_SIZE_RATIO
+
+    return `${iconAmount}${parsedLength.unit}`
+  }
+
+  /**
+   * Extract inline style for checkbox dimensions (CSS custom properties).
+   *
+   * @returns {{
+   *   '--furo-checkbox-size': string
+   *   '--furo-checkbox-icon-size': string
+   * }}
+   */
+  extractCheckboxRootStyle () {
+    const boxSize = this.parcel.size
+      ?? this.Ctor.DEFAULT_CHECKBOX_SIZE
+
+    return {
+      '--furo-checkbox-size': boxSize,
+      '--furo-checkbox-icon-size': this.extractCheckboxIconSize(),
+    }
+  }
+
+  /**
+   * Extract root attributes forwarded to Reka CheckboxRoot.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const parcelEntries = Object.entries(this.parcel)
+
+    return Object.fromEntries(
+      parcelEntries.filter(([key]) => !FURO_CHECKBOX_PARCEL_KEYS.has(key))
+    )
+  }
+
+  /**
+   * Build a custom event for checkbox value changes.
+   *
+   * @param {{
+   *   name: string
+   *   value: FuroCheckboxValue
+   *   indeterminate: boolean
+   * }} params - Parameters.
+   * @returns {import('./CheckboxEmitPayload.js').CheckboxRawEvent}
+   */
+  buildCustomEvent ({
+    name,
+    value,
+    indeterminate,
+  }) {
+    return new CustomEvent(
+      name,
+      {
+        detail: {
+          target: this.checkboxRootElementRef.value,
+          value,
+          indeterminate,
+        },
+      }
+    )
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroCheckboxContext ? X : never} T, X
+   * @override
+   * @returns {T} - For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.watch(
+      () => this.resolveSyncedValue(),
+      syncedValue => {
+        if (!this.isControlled()) {
+          return
+        }
+
+        this.internalValueRef.value = syncedValue
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    this.watch(
+      () => this.parcel.indeterminate,
+      () => {
+        if (this.isControlled()) {
+          return
+        }
+
+        this.internalValueRef.value = this.resolveSyncedValue()
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Handle a value update emitted by Reka CheckboxRoot.
+   *
+   * @param {{
+   *   rawValue: FuroCheckboxState
+   * }} params - Parameters.
+   */
+  onChangeValue ({
+    rawValue,
+  }) {
+    const previousCheckState = this.internalValueRef.value
+
+    const normalizedChange = this.normalizeStateChange({
+      rawValue,
+      previousCheckState,
+    })
+
+    this.applyInternalValue({
+      checkState: normalizedChange.checkState,
+    })
+
+    const customEvent = this.buildCustomEvent({
+      name: this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      value: normalizedChange.value,
+      indeterminate: normalizedChange.indeterminate,
+    })
+
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent: customEvent,
+    })
+
+    this.emit(
+      this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      payload
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_VALUE,
+      normalizedChange.value
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_INDETERMINATE,
+      normalizedChange.indeterminate
+    )
+  }
+
+  /**
+   * Apply an interaction result to the internal check state.
+   *
+   * A controlled checkbox only follows its parent, never its own interaction.
+   *
+   * @param {{
+   *   checkState: FuroCheckboxState
+   * }} params - Parameters.
+   */
+  applyInternalValue ({
+    checkState,
+  }) {
+    if (this.isControlled()) {
+      return
+    }
+
+    this.internalValueRef.value = checkState
+  }
+
+  /**
+   * Whether the checkbox is in the indeterminate state.
+   *
+   * @returns {boolean}
+   */
+  isIndeterminate () {
+    return this.internalValueRef.value === this.Ctor.INDETERMINATE_VALUE
+  }
+
+  /**
+   * Whether the checkbox is checked.
+   *
+   * @returns {boolean}
+   */
+  isChecked () {
+    return this.internalValueRef.value === true
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     internalValueRef: import('vue').Ref<FuroCheckboxState>
+ *     checkboxRootElementRef: import('vue').Ref<HTMLElement | null>
+ *   }
+ * }} FuroCheckboxContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroCheckboxContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     internalValueRef: import('vue').Ref<FuroCheckboxState>
+ *     checkboxRootElementRef: import('vue').Ref<HTMLElement | null>
+ *   }
+ * }} FuroCheckboxContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroCheckboxContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * Public checked model (`v-model:value`, `parcel.value`).
+ *
+ * @typedef {boolean} FuroCheckboxValue
+ */
+
+/**
+ * Internal tri-state check state (includes the indeterminate sentinel).
+ *
+ * @typedef {FuroCheckboxValue | typeof FuroCheckboxContext.INDETERMINATE_VALUE} FuroCheckboxState
+ */
+
+/**
+ * @typedef {{
+ *   parcel?: FuroCheckboxParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {{
+ *   value?: FuroCheckboxValue
+ *   indeterminate?: boolean
+ *   invalid?: boolean
+ *   disabled?: boolean
+ *   required?: boolean
+ *   size?: string
+ * }} FuroCheckboxParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<typeof FuroCheckboxContext.EMIT_EVENT_HASH>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroCheckboxContext.EMIT_EVENT_HASH} FuroCheckboxEmitHash
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroCheckboxContext
+ * }} FuroCheckboxSetup
+ */