openproject-primer_view_components 0.6.3

data/app/components/primer/alpha/toggle_switch.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Primer
+  module Alpha
+    # The ToggleSwitch component is a button that toggles between two boolean states. It is meant to be used for
+    # settings that should cause an immediate update. If configured with a "src" attribute, the component will
+    # make a POST request containing data of the form "value: 0 | 1".
+    class ToggleSwitch < Primer::Component
+      SIZE_DEFAULT = :medium
+      SIZE_MAPPINGS = {
+        SIZE_DEFAULT => nil,
+        :small => "ToggleSwitch--small"
+      }.freeze
+      SIZE_OPTIONS = SIZE_MAPPINGS.keys.freeze
+
+      STATUS_LABEL_POSITION_DEFAULT = :start
+      STATUS_LABEL_POSITION_MAPPINGS = {
+        STATUS_LABEL_POSITION_DEFAULT => nil,
+        :end => "ToggleSwitch--statusAtEnd"
+      }.freeze
+      STATUS_LABEL_POSITION_OPTIONS = STATUS_LABEL_POSITION_MAPPINGS.keys.freeze
+
+      # @example Default
+      #   <%= render(Primer::Alpha::ToggleSwitch.new(src: "/view-components/rails-app/toggle_switch")) %>
+      #
+      # @example Checked
+      #   <%= render(Primer::Alpha::ToggleSwitch.new(src: "/view-components/rails-app/toggle_switch", checked: true)) %>
+      #
+      # @example Disabled
+      #   <%= render(Primer::Alpha::ToggleSwitch.new(src: "/view-components/rails-app/toggle_switch", enabled: false)) %>
+      #
+      # @example Checked and Disabled
+      #   <%= render(Primer::Alpha::ToggleSwitch.new(src: "/view-components/rails-app/toggle_switch", checked: true, enabled: false)) %>
+      #
+      # @example Small
+      #   <%= render(Primer::Alpha::ToggleSwitch.new(src: "/view-components/rails-app/toggle_switch", size: :small)) %>
+      #
+      # @example With status label positioned at the end
+      #   <%= render(Primer::Alpha::ToggleSwitch.new(src: "/view-components/rails-app/toggle_switch", status_label_position: :end)) %>
+      #
+      # @param src [String] The URL to POST to when the toggle switch is toggled. If `nil`, the toggle switch will not make any requests.
+      # @param csrf_token [String] A CSRF token that will be sent to the server as "authenticity_token" when the toggle switch is toggled. Unused if `src` is `nil`.
+      # @param checked [Boolean] Whether the toggle switch is on or off.
+      # @param enabled [Boolean] Whether or not the toggle switch responds to user input.
+      # @param size [Symbol] What size toggle switch to render. <%= one_of(Primer::Alpha::ToggleSwitch::STATUS_LABEL_POSITION_OPTIONS) %>
+      # @param status_label_position [Symbol] Which side of the toggle switch to render the status label. <%= one_of(Primer::Alpha::ToggleSwitch::SIZE_OPTIONS) %>
+      # @param system_arguments [Hash] <%= link_to_system_arguments_docs %>
+      def initialize(src: nil, csrf_token: nil, checked: false, enabled: true, size: SIZE_DEFAULT, status_label_position: STATUS_LABEL_POSITION_DEFAULT, **system_arguments)
+        @src = src
+        @csrf_token = csrf_token
+        @checked = checked
+        @enabled = enabled
+        @system_arguments = system_arguments
+
+        @size = fetch_or_fallback(SIZE_OPTIONS, size, SIZE_DEFAULT)
+        @status_label_position = fetch_or_fallback(
+          STATUS_LABEL_POSITION_OPTIONS, status_label_position, STATUS_LABEL_POSITION_DEFAULT
+        )
+
+        @system_arguments[:classes] = class_names(
+          @system_arguments.delete(:classes),
+          "ToggleSwitch",
+          on? ? "ToggleSwitch--checked" : nil,
+          enabled? ? nil : "ToggleSwitch--disabled",
+          STATUS_LABEL_POSITION_MAPPINGS[@status_label_position],
+          SIZE_MAPPINGS[@size]
+        )
+
+        @aria_arguments = {
+          aria: merge_aria(
+            @system_arguments,
+            aria: { pressed: on? }
+          )
+        }
+
+        @system_arguments[:src] = @src if @src
+
+        return unless @src && @csrf_token
+
+        @system_arguments[:csrf] = @csrf_token
+      end
+
+      def on?
+        @checked
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def disabled?
+        !enabled?
+      end
+    end
+  end
+end

data/app/components/primer/alpha/toggle_switch.ts

@@ -0,0 +1,189 @@
+import {controller, target} from '@github/catalyst'
+
+@controller
+class ToggleSwitchElement extends HTMLElement {
+  @target switch: HTMLElement
+  @target loadingSpinner: HTMLElement
+  @target errorIcon: HTMLElement
+
+  private toggling = false
+
+  get src(): string | null {
+    const src = this.getAttribute('src')
+    if (!src) return null
+
+    const link = this.ownerDocument.createElement('a')
+    link.href = src
+    return link.href
+  }
+
+  get csrf(): string | null {
+    const csrfElement = this.querySelector('[data-csrf]')
+    return this.getAttribute('csrf') || (csrfElement instanceof HTMLInputElement && csrfElement.value) || null
+  }
+
+  get csrfField(): string {
+    // the authenticity token is passed into the element and is not generated in js land
+
+    return this.getAttribute('csrf-field') || 'authenticity_token'
+  }
+
+  isRemote(): boolean {
+    return this.src != null
+  }
+
+  async toggle() {
+    if (this.toggling) return
+
+    this.toggling = true
+
+    if (this.isDisabled()) {
+      return
+    }
+
+    if (!this.isRemote()) {
+      this.performToggle()
+      this.toggling = false
+      return
+    }
+
+    // toggle immediately to tell screen readers the switch was clicked
+    this.performToggle()
+    this.setLoadingState()
+
+    try {
+      await this.submitForm()
+    } catch (error) {
+      if (error instanceof Error) {
+        // because we toggle immediately when the switch is clicked, toggle back to the
+        // old state on failure
+        this.setErrorState(error.message || 'An error occurred, please try again.')
+        this.performToggle()
+      }
+
+      return
+    } finally {
+      this.toggling = false
+    }
+
+    this.setSuccessState()
+  }
+
+  turnOn(): void {
+    if (this.isDisabled()) {
+      return
+    }
+
+    this.switch.setAttribute('aria-pressed', 'true')
+    this.classList.add('ToggleSwitch--checked')
+  }
+
+  turnOff(): void {
+    if (this.isDisabled()) {
+      return
+    }
+
+    this.switch.setAttribute('aria-pressed', 'false')
+    this.classList.remove('ToggleSwitch--checked')
+  }
+
+  isOn(): boolean {
+    return this.switch.getAttribute('aria-pressed') === 'true'
+  }
+
+  isOff(): boolean {
+    return !this.isOn()
+  }
+
+  isDisabled(): boolean {
+    return this.switch.getAttribute('disabled') != null
+  }
+
+  disable(): void {
+    this.switch.setAttribute('disabled', 'disabled')
+  }
+
+  enable(): void {
+    this.switch.removeAttribute('disabled')
+  }
+
+  private performToggle(): void {
+    if (this.isOn()) {
+      this.turnOff()
+    } else {
+      this.turnOn()
+    }
+  }
+
+  private setLoadingState(): void {
+    this.errorIcon.setAttribute('hidden', 'hidden')
+    this.loadingSpinner.removeAttribute('hidden')
+
+    const event = new CustomEvent('toggleSwitchLoading', {bubbles: true})
+    this.dispatchEvent(event)
+  }
+
+  private setSuccessState(): void {
+    const event = new CustomEvent('toggleSwitchSuccess', {bubbles: true})
+    this.dispatchEvent(event)
+
+    this.setFinishedState(false)
+  }
+
+  private setErrorState(message: string): void {
+    const event = new CustomEvent('toggleSwitchError', {bubbles: true, detail: message})
+    this.dispatchEvent(event)
+
+    this.setFinishedState(true)
+  }
+
+  private setFinishedState(error: boolean): void {
+    if (error) {
+      this.errorIcon.removeAttribute('hidden')
+    }
+
+    this.loadingSpinner.setAttribute('hidden', 'hidden')
+  }
+
+  private async submitForm() {
+    const body = new FormData()
+
+    if (this.csrf) {
+      body.append(this.csrfField, this.csrf)
+    }
+
+    body.append('value', this.isOn() ? '1' : '0')
+
+    if (!this.src) throw new Error('invalid src')
+
+    let response
+
+    try {
+      response = await fetch(this.src, {
+        credentials: 'same-origin',
+        method: 'POST',
+        headers: {
+          'Requested-With': 'XMLHttpRequest'
+        },
+        body
+      })
+    } catch (error) {
+      throw new Error('A network error occurred, please try again.')
+    }
+
+    if (!response.ok) {
+      throw new Error(await response.text())
+    }
+  }
+}
+
+declare global {
+  interface Window {
+    ToggleSwitchElement: typeof ToggleSwitchElement
+  }
+}
+
+if (!window.customElements.get('toggle-switch')) {
+  window.ToggleSwitchElement = ToggleSwitchElement
+  window.customElements.define('toggle-switch', ToggleSwitchElement)
+}

data/app/components/primer/alpha/tool_tip.d.ts

@@ -0,0 +1,26 @@
+import '@oddbird/popover-polyfill';
+type Direction = 'n' | 's' | 'e' | 'w' | 'ne' | 'se' | 'nw' | 'sw';
+declare class ToolTipElement extends HTMLElement {
+    #private;
+    styles(): string;
+    get htmlFor(): string;
+    set htmlFor(value: string);
+    get type(): 'description' | 'label';
+    set type(value: 'description' | 'label');
+    get direction(): Direction;
+    set direction(value: Direction);
+    get control(): HTMLElement | null;
+    set hiddenFromView(value: true | false);
+    get hiddenFromView(): true | false;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    handleEvent(event: Event): Promise<void>;
+    static observedAttributes: string[];
+    attributeChangedCallback(name: string): void;
+}
+declare global {
+    interface Window {
+        ToolTipElement: typeof ToolTipElement;
+    }
+}
+export {};