@openreachtech/furo-vue 1.3.1

package/lib/components/atoms/FuroSwitch/FuroSwitch.vue

@@ -0,0 +1,165 @@
+<script>
+import {
+  defineComponent,
+} from 'vue'
+
+import {
+  Switch as RekaSwitch,
+} from 'reka-ui/namespaced'
+
+import FuroSwitchContext from './FuroSwitchContext.js'
+
+export default defineComponent({
+  name: 'FuroSwitch',
+
+  components: {
+    SwitchRoot: RekaSwitch.Root,
+    SwitchThumb: RekaSwitch.Thumb,
+  },
+
+  inheritAttrs: false,
+
+  props: {
+    parcel: {
+      /** @type {import('vue').PropType<import('./FuroSwitchContext.js').Props['parcel']>} */
+      type: [
+        Object,
+        null,
+      ],
+      default: null,
+    },
+  },
+
+  emits: FuroSwitchContext.EMIT_EVENT_HASH,
+
+  /**
+   * Setup of this component.
+   *
+   * @type {import('./FuroSwitchContext.js').FuroSwitchSetup}
+   */
+  setup (
+    props,
+    componentContext
+  ) {
+    const context = FuroSwitchContext.create({
+      props,
+      componentContext,
+    })
+      .setupComponent()
+
+    return {
+      context,
+    }
+  },
+})
+</script>
+
+<template>
+  <SwitchRoot
+    :ref="context.switchRootElementRef"
+    v-bind="{
+      ...context.extractRootAttributes(),
+      ...$attrs,
+    }"
+    :class="context.extractRootClassNames()"
+    :disabled="context.isDisabled()"
+    :required="context.isRequired()"
+    :model-value="context.internalValueRef.value"
+    @update:model-value="context.onChangeValue({
+      rawValue: $event,
+    })"
+  >
+    <SwitchThumb class="knob" />
+  </SwitchRoot>
+</template>
+
+<style scoped>
+@layer furo {
+  .unit-form-control.switch {
+    --furo-switch-track-inset: 0.125rem;
+
+    display: inline-flex;
+    align-items: center;
+
+    flex-shrink: 0;
+
+    box-sizing: border-box;
+    width: var(--furo-switch-track-width);
+    height: var(--furo-switch-track-height);
+
+    border: none;
+    border-radius: var(--size-border-radius-full);
+
+    padding-block: var(--furo-switch-track-inset);
+    padding-inline: var(--furo-switch-track-inset);
+
+    background-color: var(--color-input);
+
+    cursor: pointer;
+
+    transition-duration: var(--transition-timer);
+    transition-property: background-color, box-shadow;
+  }
+
+  .unit-form-control.switch.size-medium {
+    --furo-switch-track-width: 2.25rem;
+    --furo-switch-track-height: 1.25rem;
+    --furo-switch-knob-size: 1rem;
+    --furo-switch-knob-travel: 1rem;
+  }
+
+  .unit-form-control.switch.size-small {
+    --furo-switch-track-width: 1.75rem;
+    --furo-switch-track-height: 1rem;
+    --furo-switch-knob-size: 0.75rem;
+    --furo-switch-knob-travel: 0.75rem;
+  }
+
+  .unit-form-control.switch[data-state="checked"] {
+    background-color: var(--color-selected);
+  }
+
+  /* :not(.disabled) so a bare :hover cannot outrank the disabled rule below. */
+  .unit-form-control.switch:not(.disabled)[data-state="checked"]:hover {
+    background-color: var(--color-selected-lighter);
+  }
+
+  .unit-form-control.switch:not(.disabled)[data-state="checked"]:active {
+    background-color: var(--color-selected-darker);
+  }
+
+  .unit-form-control.switch:focus-visible {
+    outline: none;
+
+    box-shadow: 0 0 0 0.125rem var(--color-ring);
+  }
+
+  /* The design gives the disabled track a colour of its own rather than dimming
+     the live one, so this repaints instead of lowering opacity. */
+  .unit-form-control.switch.disabled {
+    background-color: var(--color-secondary);
+
+    cursor: not-allowed;
+  }
+
+  .unit-form-control.switch > .knob {
+    flex-shrink: 0;
+
+    width: var(--furo-switch-knob-size);
+    height: var(--furo-switch-knob-size);
+
+    border-radius: var(--size-border-radius-full);
+
+    background-color: var(--color-selected-foreground);
+
+    transform: translateX(0);
+
+    transition-duration: var(--transition-timer);
+    transition-property: transform;
+  }
+
+  .unit-form-control.switch[data-state="checked"] > .knob {
+    transform: translateX(var(--furo-switch-knob-travel));
+  }
+}
+</style>

package/lib/components/atoms/FuroSwitch/FuroSwitchContext.js

@@ -0,0 +1,440 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import SwitchEmitPayload from './SwitchEmitPayload.js'
+
+/**
+ * Furo-owned parcel keys (not forwarded to the underlying primitive).
+ */
+const FURO_SWITCH_PARCEL_KEYS = new Set([
+  'value',
+  'size',
+  'disabled',
+  'required',
+])
+
+/**
+ * Context class for managing FuroSwitch component.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroSwitchContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroSwitchContextParams} params - Parameters.
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroSwitchContext ? X : never} T, X
+   * @override
+   * @param {FuroSwitchContextFactoryParams} 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 {{
+   *   internalValueRef: import('vue').Ref<FuroSwitchValue>
+   *   switchRootElementRef: import('vue').Ref<HTMLElement | null>
+   * }} Ref hash.
+   */
+  static buildRefHash () {
+    return {
+      internalValueRef: ref(false),
+      switchRootElementRef: ref(null),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   CHANGE_VALUE: 'change-value'
+   *   UPDATE_VALUE: 'update:value'
+   * }>} Emit event names.
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      CHANGE_VALUE: 'change-value',
+      UPDATE_VALUE: 'update:value',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./SwitchEmitPayload.js').default) => void
+   *   'update:value': (value: FuroSwitchValue) => void
+   * }} Emit event hash.
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.CHANGE_VALUE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_VALUE]: value => {},
+    }
+  }
+
+  /**
+   * Sizes the switch can take.
+   *
+   * @returns {Array<FuroSwitchSize>} Sizes, largest first.
+   */
+  static get SIZES () {
+    return [
+      'medium',
+      'small',
+    ]
+  }
+
+  /**
+   * Default size.
+   *
+   * @returns {FuroSwitchSize} Default size.
+   */
+  static get DEFAULT_SIZE () {
+    return 'medium'
+  }
+
+  /**
+   * get: Constructor of `EmitPayload`.
+   *
+   * @returns {typeof SwitchEmitPayload} Constructor of the emit payload.
+   */
+  static get EmitPayloadCtor () {
+    return SwitchEmitPayload
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroSwitchContext} Constructor of this class.
+   */
+  get Ctor () {
+    return /** @type {typeof FuroSwitchContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal value ref.
+   *
+   * @returns {import('vue').Ref<FuroSwitchValue>} Internal on/off model.
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Get switch root element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>} Root element of the switch.
+   */
+  get switchRootElementRef () {
+    return this.refHash.switchRootElementRef
+  }
+
+  /**
+   * Parcel passed from parent via props (merged with defaults).
+   *
+   * @override
+   * @returns {FuroSwitchParcel} Parcel with defaults applied.
+   */
+  get parcel () {
+    return {
+      disabled: false,
+      required: false,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * get: size of the switch.
+   *
+   * @returns {FuroSwitchSize} Size; defaults to medium.
+   */
+  get size () {
+    return this.parcel.size
+      ?? this.Ctor.DEFAULT_SIZE
+  }
+
+  /**
+   * Whether the parent controls `parcel.value`.
+   *
+   * @returns {boolean} Whether the parent owns the value.
+   */
+  isControlled () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'value')
+  }
+
+  /**
+   * Resolve synced on/off value from parcel or fallthrough attrs.
+   *
+   * @returns {FuroSwitchValue} Value the parent currently declares.
+   */
+  resolveSyncedValue () {
+    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
+  }
+
+  /**
+   * Whether the switch is disabled.
+   *
+   * @returns {boolean} Whether the switch is disabled.
+   */
+  isDisabled () {
+    return Boolean(this.parcel.disabled)
+      || this.hasBooleanAttribute({ name: 'disabled' })
+  }
+
+  /**
+   * Whether the switch is required.
+   *
+   * @returns {boolean} Whether the switch is required.
+   */
+  isRequired () {
+    return Boolean(this.parcel.required)
+      || this.hasBooleanAttribute({ name: 'required' })
+  }
+
+  /**
+   * Extract CSS class map for the root.
+   *
+   * @returns {Record<string, boolean>} Class map for the root element.
+   */
+  extractRootClassNames () {
+    return Object.fromEntries([
+      ['unit-form-control', true],
+      ['switch', true],
+      [`size-${this.size}`, true],
+      ['disabled', this.isDisabled()],
+    ])
+  }
+
+  /**
+   * Extract attributes forwarded to the underlying primitive.
+   *
+   * @returns {Record<string, unknown>} Attributes for the root element.
+   */
+  extractRootAttributes () {
+    const parcelEntries = Object.entries(this.parcel)
+
+    return Object.fromEntries(
+      parcelEntries.filter(([key]) => !FURO_SWITCH_PARCEL_KEYS.has(key))
+    )
+  }
+
+  /**
+   * Build a custom event for switch value changes.
+   *
+   * @param {{
+   *   name: string
+   *   value: FuroSwitchValue
+   * }} params - Parameters.
+   * @returns {import('./SwitchEmitPayload.js').SwitchRawEvent} Raw event carrying the new value.
+   */
+  buildCustomEvent ({
+    name,
+    value,
+  }) {
+    return new CustomEvent(
+      name,
+      {
+        detail: {
+          target: this.switchRootElementRef.value,
+          value,
+        },
+      }
+    )
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroSwitchContext ? 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,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Handle a value update emitted by the underlying primitive.
+   *
+   * @param {{
+   *   rawValue: FuroSwitchValue
+   * }} params - Parameters.
+   */
+  onChangeValue ({
+    rawValue,
+  }) {
+    const value = Boolean(rawValue)
+
+    this.internalValueRef.value = value
+
+    const customEvent = this.buildCustomEvent({
+      name: this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      value,
+    })
+
+    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,
+      value
+    )
+  }
+
+  /**
+   * Whether the switch is on.
+   *
+   * @returns {boolean} Whether the switch is on.
+   */
+  isChecked () {
+    return this.internalValueRef.value === true
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     internalValueRef: import('vue').Ref<FuroSwitchValue>
+ *     switchRootElementRef: import('vue').Ref<HTMLElement | null>
+ *   }
+ * }} FuroSwitchContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroSwitchContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     internalValueRef: import('vue').Ref<FuroSwitchValue>
+ *     switchRootElementRef: import('vue').Ref<HTMLElement | null>
+ *   }
+ * }} FuroSwitchContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroSwitchContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * Public on/off model (`v-model:value`, `parcel.value`).
+ *
+ * @typedef {boolean} FuroSwitchValue
+ */
+
+/**
+ * @typedef {'medium' | 'small'} FuroSwitchSize
+ */
+
+/**
+ * @typedef {{
+ *   parcel?: FuroSwitchParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {{
+ *   value?: FuroSwitchValue
+ *   size?: FuroSwitchSize
+ *   disabled?: boolean
+ *   required?: boolean
+ * }} FuroSwitchParcel
+ */
+
+/**
+ * @typedef {typeof FuroSwitchContext.EMIT_EVENT_HASH} FuroSwitchEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroSwitchEmitHash>} ComponentContext
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroSwitchContext
+ * }} FuroSwitchSetup
+ */

package/lib/components/atoms/FuroSwitch/SwitchEmitPayload.js

@@ -0,0 +1,86 @@
+import BaseEmitPayload from '../../../emit-payload/BaseEmitPayload.js'
+
+/**
+ * SwitchEmitPayload.
+ *
+ * @extends {BaseEmitPayload<SwitchRawEvent, HTMLElement>}
+ */
+export default class SwitchEmitPayload extends BaseEmitPayload {
+  /**
+   * Get the event detail.
+   *
+   * @returns {SwitchRawEvent['detail'] | null} Detail of the raw event, or null when absent.
+   */
+  get eventDetail () {
+    return this.rawEvent?.detail
+      ?? null
+  }
+
+  /**
+   * Get the control element from the raw event.
+   *
+   * @override
+   * @returns {HTMLElement | null} Root element of the switch, or null when absent.
+   */
+  get controlElement () {
+    return this.eventDetail?.target
+      ?? null
+  }
+
+  /**
+   * Current checked state after the change.
+   *
+   * @returns {FuroSwitchValue | null} Checked state, or null when absent.
+   */
+  get value () {
+    return this.eventDetail?.value
+      ?? null
+  }
+
+  /**
+   * Whether the switch is on after the change.
+   *
+   * @returns {boolean | null} Whether the switch is on, or null when the value is absent.
+   */
+  isChecked () {
+    if (typeof this.value !== 'boolean') {
+      return null
+    }
+
+    return this.value
+  }
+
+  /**
+   * Whether the switch is off after the change.
+   *
+   * @returns {boolean | null} Whether the switch is off, or null when the value is absent.
+   */
+  isUnchecked () {
+    if (typeof this.value !== 'boolean') {
+      return null
+    }
+
+    return !this.value
+  }
+}
+
+/**
+ * @typedef {import('./FuroSwitchContext.js').FuroSwitchValue} FuroSwitchValue
+ */
+
+/**
+ * @typedef {{
+ *   rawEvent: SwitchRawEvent
+ * }} SwitchEmitPayloadParams
+ */
+
+/**
+ * @typedef {CustomEvent<{
+ *   target: HTMLElement | null
+ *   value: FuroSwitchValue | null
+ * }>} SwitchRawEvent
+ */
+
+/**
+ * @typedef {SwitchEmitPayloadParams} SwitchEmitPayloadFactoryParams
+ */