typo3-typescript-sources 13.4.20

package/backend/settings/enum/settings-mode.enum.ts

@@ -0,0 +1,24 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+export enum SettingsMode {
+  minimal = 'minimal',
+  basic = 'basic',
+  advanced = 'advanced',
+}
+
+export function sanitizeSettingsMode(value: string | undefined | null): SettingsMode {
+  return Object.values(SettingsMode).includes(value as SettingsMode)
+    ? (value as SettingsMode)
+    : SettingsMode.basic;
+}

package/backend/settings/type/base.ts

@@ -0,0 +1,200 @@
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+/* eslint-disable @typescript-eslint/member-ordering */
+
+import { LitElement, type PropertyDeclaration, type ReactiveElement } from 'lit';
+import { defaultConverter } from '@lit/reactive-element';
+import { property } from 'lit/decorators';
+
+export const internals = Symbol('internals');
+const privateInternals = Symbol('privateInternals');
+export const getFormValue = Symbol('getFormValue');
+export const getFormState = Symbol('getFormState');
+
+/**
+ * Base element class for settings type to act as
+ * a form associated custom element.
+ *
+ * See https://web.dev/articles/more-capable-form-controls#defining_a_form-associated_custom_element
+ */
+export abstract class BaseElement<
+  T = string,
+  OptionsType extends Record<string, unknown> = Record<string, unknown>
+> extends LitElement {
+  @property({ type: String }) key: string;
+  @property({ type: String }) formid: string;
+  @property({ type: Boolean }) readonly: boolean = false;
+  @property({ type: Object }) enum: Record<string, string>;
+  @property({ type: Boolean }) debug: boolean = false;
+  @property({ type: Object }) options: OptionsType;
+
+  static readonly formAssociated = true;
+
+  /* @property annotation needs to be provided by extending class */
+  abstract value: T;
+
+  [privateInternals]?: ElementInternals;
+
+  protected override createRenderRoot(): HTMLElement | ShadowRoot {
+    return this;
+  }
+
+  protected get [internals]() {
+    // Create internals in getter so that it can be used in methods called on
+    // construction in `ReactiveElement`, such as `requestUpdate()`.
+    if (!this[privateInternals]) {
+      this[privateInternals] = this.attachInternals();
+    }
+
+    return this[privateInternals];
+  }
+
+  public get form() {
+    return this[internals].form;
+  }
+
+  protected get labels() {
+    return this[internals].labels;
+  }
+
+  // Use @property for the `name` and `disabled` properties to add them to the
+  // `observedAttributes` array and trigger `attributeChangedCallback()`.
+  //
+  // We don't use Lit's default getter/setter (`noAccessor: true`) because
+  // the attributes need to be updated synchronously to work with synchronous
+  // form APIs, and Lit updates attributes async by default.
+  @property({ noAccessor: true })
+  public get name() {
+    return this.getAttribute('name') ?? '';
+  }
+  public set name(name: string) {
+    // Note: setting name to null or empty does not remove the attribute.
+    this.setAttribute('name', name);
+    // We don't need to call `requestUpdate()` since it's called synchronously
+    // in `attributeChangedCallback()`.
+  }
+
+  @property({ type: Boolean, noAccessor: true })
+  public get disabled() {
+    return this.hasAttribute('disabled');
+  }
+
+  public set disabled(disabled: boolean) {
+    this.toggleAttribute('disabled', disabled);
+    // We don't need to call `requestUpdate()` since it's called synchronously
+    // in `attributeChangedCallback()`.
+  }
+
+  public override attributeChangedCallback(
+    name: string,
+    old: string | null,
+    value: string | null,
+  ) {
+    // Manually `requestUpdate()` for `name` and `disabled` when their
+    // attribute or property changes.
+    // The properties update their attributes, so this callback is invoked
+    // immediately when the properties are set. We call `requestUpdate()` here
+    // instead of letting Lit set the properties from the attribute change.
+    // That would cause the properties to re-set the attribute and invoke this
+    // callback again in a loop. This leads to stale state when Lit tries to
+    // determine if a property changed or not.
+    if (name === 'name' || name === 'disabled') {
+      // Disabled's value is only false if the attribute is missing and null.
+      const oldValue = name === 'disabled' ? old !== null : old;
+      // Trigger a lit update when the attribute changes.
+      this.requestUpdate(name, oldValue);
+      return;
+    }
+
+    super.attributeChangedCallback(name, old, value);
+  }
+
+  public override requestUpdate(
+    name?: PropertyKey,
+    oldValue?: unknown,
+    options?: PropertyDeclaration,
+  ) {
+    super.requestUpdate(name, oldValue, options);
+    if (name === 'value') {
+      this.dispatchEvent(new CustomEvent('typo3:setting:changed', { detail: { value: this.value } }));
+      // Update the form value synchronously in `requestUpdate()` rather than
+      // `update()` or `updated()`, which are async. This is necessary to ensure
+      // that form data is updated in time for synchronous event listeners.
+      this[internals].setFormValue(this[getFormValue](), this[getFormState]());
+    }
+  }
+
+  public formDisabledCallback(disabled: boolean) {
+    this.disabled = disabled;
+  }
+
+  /**
+   * Callback triggered when <button type=reset> or form.reset() is triggered.
+   */
+  public formResetCallback() {
+    const oldValue = this.value;
+    const defaultValue = this.getAttribute('value');
+
+    // Workaround to trigger string to property conversion
+    this.attributeChangedCallback('value', this.valueToString(oldValue), null);
+    this.attributeChangedCallback('value', null, defaultValue);
+  }
+
+  /**
+   * Callback triggered when form is (re-)loaded by browser-back button.
+   */
+  public formStateRestoreCallback(state: FormValue): void {
+    if (typeof state === 'string') {
+      this.attributeChangedCallback('value', this.valueToString(this.value), null);
+      this.attributeChangedCallback('value', null, state);
+    } else {
+      throw new Error(`formStateRestoreCallback() needs to be implemented for <${this.localName}> for state type "${typeof state}"`);
+    }
+  }
+
+  protected [getFormState](): FormValue | null {
+    return this[getFormValue]();
+  }
+
+  protected [getFormValue](): string {
+    return this.valueToString(this.value);
+  }
+
+  protected valueToString(value: T): string {
+    const ctor = this.constructor as typeof ReactiveElement;
+    const options = ctor.getPropertyOptions('value');
+    const converter = typeof options.converter === 'object' && typeof options.converter?.toAttribute === 'function' ?
+      options.converter.toAttribute : defaultConverter.toAttribute;
+    return converter(value, options.type) as string;
+  }
+}
+
+export type FormValue = File | string | FormData;
+
+/**
+ * A value to be restored for a component's form value. If a component's form
+ * state is a `FormData` object, its entry list of name and values will be
+ * provided.
+ */
+export type FormRestoreState =
+  | File
+  | string
+  | Array<[string, FormDataEntryValue]>;
+
+/**
+ * The reason a form component is being restored for, either `'restore'` for
+ * browser restoration or `'autocomplete'` for restoring user values.
+ */
+export type FormRestoreReason = 'restore' | 'autocomplete';

package/backend/settings/type/bool.ts

@@ -0,0 +1,56 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+import { html, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators';
+import { BaseElement } from './base';
+
+export const componentName = 'typo3-backend-settings-type-bool';
+
+@customElement(componentName)
+export class BoolTypeElement extends BaseElement<boolean> {
+
+  @property({
+    type: Boolean,
+    converter: {
+      toAttribute: (value: boolean): string => {
+        return value ? '1' : '0';
+      },
+      fromAttribute: (value: string): boolean => {
+        return value === '1' || value === 'true';
+      }
+    }
+  }) override value: boolean;
+
+  protected override render(): TemplateResult {
+    return html`
+      <div class="form-check form-check-type-toggle">
+        <input
+          type="checkbox"
+          id=${this.formid}
+          class="form-check-input"
+          value="1"
+          ?disabled=${this.readonly}
+          .checked=${this.value}
+          @change=${(e: InputEvent) => this.value = (e.target as HTMLInputElement).checked}
+        />
+      </div>
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'typo3-backend-settings-type-bool': BoolTypeElement;
+  }
+}

package/backend/settings/type/color.ts

@@ -0,0 +1,64 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+import { html, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators';
+import { BaseElement } from './base';
+import '@typo3/backend/color-picker';
+import RegularEvent from '@typo3/core/event/regular-event';
+
+export const componentName = 'typo3-backend-settings-type-color';
+
+@customElement(componentName)
+export class ColorTypeElement extends BaseElement {
+
+  @property({ type: String }) override value: string;
+
+  protected override firstUpdated(): void {
+    const inputElement = this.getInputElement();
+    if (inputElement) {
+      new RegularEvent('blur', (e: Event): void => {
+        this.updateValue((e.target as HTMLInputElement).value);
+      }).bindTo(inputElement);
+    }
+  }
+
+  protected updateValue(value: string) {
+    this.value = value;
+  }
+
+  protected override render(): TemplateResult {
+    return html`
+      <typo3-backend-color-picker>
+        <input
+          type="text"
+          id=${this.formid}
+          class="form-control"
+          ?readonly=${this.readonly}
+          .value=${this.value}
+          @change=${(e: InputEvent) => this.updateValue((e.target as HTMLInputElement).value)}
+        />
+      </typo3-backend-color-picker>
+    `;
+  }
+
+  protected getInputElement(): HTMLInputElement {
+    return this.querySelector<HTMLInputElement>('input');
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'typo3-backend-settings-type-color': ColorTypeElement;
+  }
+}

package/backend/settings/type/int.ts

@@ -0,0 +1,85 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+import { html, nothing, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators';
+import { live } from 'lit/directives/live';
+import { BaseElement } from './base';
+
+export const componentName = 'typo3-backend-settings-type-int';
+
+@customElement(componentName)
+export class IntTypeElement extends BaseElement<
+  number,
+  {
+    min?: number,
+    max?: number,
+    step?: number,
+  }
+> {
+
+  @property({ type: Number }) override value: number;
+
+  protected handleChange(e: InputEvent): void {
+    const input = e.target as HTMLInputElement|HTMLSelectElement;
+    if (input.reportValidity()) {
+      if (input instanceof HTMLInputElement) {
+        this.value = input.valueAsNumber;
+      } else {
+        this.value = parseInt(input.value, 10);
+      }
+    }
+  }
+
+  protected renderEnum(): TemplateResult {
+    return html`
+      <select
+        id=${this.formid}
+        class="form-select"
+        ?readonly=${this.readonly}
+        .value=${live(this.value)}
+        @change=${this.handleChange}
+      >
+        ${Object.entries(this.enum).map(([value, label]) => html`
+          <option ?selected=${this.value.toString() === value} value=${value}>${label}${this.debug ? html` [${value}]` : nothing}</option>
+        `)}
+      </select>
+    `;
+  }
+
+  protected override render(): TemplateResult {
+    if (typeof this.enum === 'object') {
+      return this.renderEnum();
+    }
+    return html`
+      <input
+        type="number"
+        id=${this.formid}
+        class="form-control"
+        ?readonly=${this.readonly}
+        .value=${live(String(this.value))}
+        required
+        min=${this.options.min ?? nothing}
+        max=${this.options.max ?? nothing}
+        step=${this.options.step ?? nothing}
+        @change=${this.handleChange}
+      />
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'typo3-backend-settings-type-int': IntTypeElement;
+  }
+}

package/backend/settings/type/number.ts

@@ -0,0 +1,61 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+import { html, nothing, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators';
+import { live } from 'lit/directives/live';
+import { BaseElement } from './base';
+
+export const componentName = 'typo3-backend-settings-type-number';
+
+@customElement(componentName)
+export class NumberTypeElement extends BaseElement<
+  number,
+  {
+    min?: number,
+    max?: number,
+    step?: number,
+  }
+> {
+  @property({ type: Number }) override value: number;
+
+  protected handleChange(e: InputEvent): void {
+    const input = e.target as HTMLInputElement;
+    if (input.reportValidity()) {
+      this.value = input.valueAsNumber;
+    }
+  }
+
+  protected override render(): TemplateResult {
+    return html`
+      <input
+        type="number"
+        id=${this.formid}
+        class="form-control"
+        ?readonly=${this.readonly}
+        .value=${live(this.value)}
+        required
+        min=${this.options.min ?? nothing}
+        max=${this.options.max ?? nothing}
+        step=${this.options.step ?? '0.01'}
+        @change=${this.handleChange}
+      />
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'typo3-backend-settings-type-number': NumberTypeElement;
+  }
+}

package/backend/settings/type/page.ts

@@ -0,0 +1,100 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+import { html, nothing, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators';
+import { lll } from '@typo3/core/lit-helper';
+import { MessageUtility } from '@typo3/backend/utility/message-utility';
+import { BaseElement } from './base';
+import { default as Modal } from '@typo3/backend/modal';
+import '@typo3/backend/element/icon-element';
+
+export const componentName = 'typo3-backend-settings-type-page';
+
+@customElement(componentName)
+export class PageTypeElement extends BaseElement<number> {
+
+  @property({ type: Number }) override value: number;
+
+  protected override render(): TemplateResult {
+    /* eslint-disable @stylistic/indent */
+    return html`
+      <div class="input-grouped">
+        <input
+          type="number"
+          id=${this.formid}
+          class="form-control"
+          ?readonly=${this.readonly}
+          .value=${this.value}
+          @change=${(e: InputEvent) => this.value = parseInt((e.target as HTMLInputElement).value, 10)}
+        />
+        ${this.canUseElementBrowser()
+          ? html`
+            <button
+              type="button"
+              class="btn btn-default"
+              @click=${() => this.openElementBrowser()}
+            >
+              <typo3-backend-icon identifier="apps-pagetree-page" size="small"></typo3-backend-icon>
+              ${lll('settingseditor.type.page.button') || 'Select page'}
+            </button>
+          `
+          : nothing
+        }
+      </div>
+    `;
+  }
+
+  private canUseElementBrowser(): boolean {
+    return top.TYPO3.settings?.Wizards?.elementBrowserUrl !== undefined;
+  }
+
+  private openElementBrowser() {
+    const mode = 'db';
+    const params = this.formid + '|||pages';
+
+    const modal = Modal.advanced({
+      type: Modal.types.iframe,
+      content: top.TYPO3.settings.Wizards.elementBrowserUrl + '&mode=' + mode + '&bparams=' + params,
+      size: Modal.sizes.large,
+    });
+    window.addEventListener('message', this.elementBrowserListener);
+    modal.addEventListener('typo3-modal-hide', () => {
+      window.removeEventListener('message', this.elementBrowserListener);
+    });
+  }
+
+  private readonly elementBrowserListener = (e: MessageEvent): void => {
+      if (!MessageUtility.verifyOrigin(e.origin)) {
+        throw 'Denied message sent by ' + e.origin;
+      }
+
+      if (e.data.actionName === 'typo3:elementBrowser:elementAdded') {
+        if (typeof e.data.fieldName === 'undefined') {
+          throw 'fieldName not defined in message';
+        }
+
+        if (typeof e.data.value === 'undefined') {
+          throw 'value not defined in message';
+        }
+
+        this.value = e.data.value.split('_').pop();
+      }
+  };
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'typo3-backend-settings-type-page': PageTypeElement;
+  }
+}

package/backend/settings/type/string.ts

@@ -0,0 +1,77 @@
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+import { html, nothing, type TemplateResult } from 'lit';
+import { customElement, property } from 'lit/decorators';
+import { live } from 'lit/directives/live';
+import { BaseElement } from './base';
+
+export const componentName = 'typo3-backend-settings-type-string';
+
+@customElement(componentName)
+export class StringTypeElement extends BaseElement<
+  string,
+  {
+    min?: number,
+    max?: number,
+  }
+> {
+  @property({ type: String }) override value: string;
+
+  protected handleChange(e: InputEvent): void {
+    const input = e.target as HTMLInputElement|HTMLSelectElement;
+    if (input.reportValidity()) {
+      this.value = input.value;
+    }
+  }
+
+  protected renderEnum(): TemplateResult {
+    return html`
+      <select
+        id=${this.formid}
+        class="form-select"
+        ?readonly=${this.readonly}
+        .value=${live(this.value)}
+        @change=${this.handleChange}
+      >
+        ${Object.entries(this.enum).map(([value, label]) => html`
+          <option ?selected=${this.value === value} value=${value}>${label}${this.debug ? html` [${value}]` : nothing}</option>
+        `)}
+      </select>
+    `;
+  }
+
+  protected override render(): TemplateResult {
+    if (typeof this.enum === 'object') {
+      return this.renderEnum();
+    }
+    return html`
+      <input
+        type="text"
+        id=${this.formid}
+        class="form-control"
+        ?readonly=${this.readonly}
+        .value=${live(this.value)}
+        minlength=${this.options.min ?? nothing}
+        maxlength=${this.options.max ?? nothing}
+        @change=${this.handleChange}
+      />
+    `;
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'typo3-backend-settings-type-string': StringTypeElement;
+  }
+}