Sith/core/static/webpack/utils/select2.ts

/**
 * Builders to use Select2 in our templates.
 *
 * This comes with two flavours : local data or remote data.
 *
 * # Local data source
 *
 * To use local data source, you must define an array
 * in your JS code, having the fields `id` and `text`.
 *
 * ```js
 * const data = [
 *   {id: 1, text: "foo"},
 *   {id: 2, text: "bar"},
 * ];
 * document.addEventListener("DOMContentLoaded", () => sithSelect2({
 *   element: document.getElementById("select2-input"),
 *   dataSource: localDataSource(data)
 * }));
 * ```
 *
 * You can also define a callback that return ids to exclude :
 *
 * ```js
 * const data = [
 *   {id: 1, text: "foo"},
 *   {id: 2, text: "bar"},
 *   {id: 3, text: "to exclude"},
 * ];
 * document.addEventListener("DOMContentLoaded", () => sithSelect2({
 *   element: document.getElementById("select2-input"),
 *   dataSource: localDataSource(data, {
 *     excluded: () => data.filter((i) => i.text === "to exclude").map((i) => parseInt(i))
 *   })
 * }));
 * ```
 *
 * # Remote data source
 *
 * Select2 with remote data sources are similar to those with local
 * data, but with some more parameters, like `resultConverter`,
 * which takes a callback that must return a `Select2Object`.
 *
 * ```js
 * import { makeUrl } from "#core:utils/api";
 * import {userSearchUsers } from "#openapi"
 * document.addEventListener("DOMContentLoaded", () => sithSelect2({
 *   element: document.getElementById("select2-input"),
 *   dataSource: remoteDataSource(await makeUrl(userSearchUsers), {
 *     excluded: () => [1, 2],  // exclude users 1 and 2 from the search
 *     resultConverter: (user: AjaxResponse) => {id: user.id, text: (user.firstName as UserType)}
 *   })
 * }));
 * ```
 *
 * # Overrides
 *
 * Dealing with a select2 may be complex.
 * That's why, when defining a select,
 * you may add an override parameter,
 * in which you can declare any parameter defined in the
 * Select2 documentation.
 *
 * ```js
 * import { makeUrl } from "#core:utils/api";
 * import {userSearchUsers } from "#openapi"
 * document.addEventListener("DOMContentLoaded", () => sithSelect2({
 *   element: document.getElementById("select2-input"),
 *   dataSource: remoteDataSource(await makeUrl(userSearchUsers), {
 *     resultConverter: (user: AjaxResponse) => {id: user.id, text: (user.firstName as UserType)}
 *     overrides: {
 *      delay: 500
 *     }
 *   })
 * }));
 * ```
 *
 * # Caveats with exclude
 *
 * With local data source, select2 evaluates the data only once.
 * Thus, modify the exclude after the initialisation is a no-op.
 *
 * With remote data source, the exclude list will be evaluated
 * after each api response.
 * It makes it possible to bind the data returned by the callback
 * to some reactive data, thus making the exclude list dynamic.
 *
 * # Images
 *
 * Sometimes, you would like to display an image besides
 * the text on the select items.
 * In this case, fill the `pictureGetter` option :
 *
 * ```js
 * import { makeUrl } from "#core:utils/api";
 * import {userSearchUsers } from "#openapi"
 * document.addEventListener("DOMContentLoaded", () => sithSelect2({
 *   element: document.getElementById("select2-input"),
 *   dataSource: remoteDataSource(await makeUrl(userSearchUsers), {
 *     resultConverter: (user: AjaxResponse) => {id: user.id, text: (user.firstName as UserType)}
 *   })
 *   pictureGetter: (user) => user.profilePict,
 * }));
 * ```
 *
 * # Binding with alpine
 *
 * You can declare your select2 component in an Alpine data.
 *
 * ```html
 * <body>
 *   <div x-data="select2_test">
 *     <select x-ref="search" x-ref="select"></select>
 *     <p x-text="currentSelection.id"></p>
 *     <p x-text="currentSelection.text"></p>
 *   </div>
 * </body>
 *
 * <script>
 * document.addEventListener("alpine:init", () => {
 *   Alpine.data("select2_test", () => ({
 *     selector: undefined,
 *     currentSelect: {id: "", text: ""},
 *
 *     init() {
 *       this.selector = sithSelect2({
 *         element: $(this.$refs.select),
 *         dataSource: localDataSource(
 *           [{id: 1, text: "foo"}, {id: 2, text: "bar"}]
 *         ),
 *       });
 *       this.selector.on("select2:select", (event) => {
 *         // select2 => Alpine signals here
 *         this.currentSelect = this.selector.select2("data")
 *       });
 *       this.$watch("currentSelected" (value) => {
 *          // Alpine => select2 signals here
 *       });
 *     },
 *   }));
 * })
 * </script>
 */

import type {
  AjaxOptions,
  DataFormat,
  GroupedDataFormat,
  LoadingData,
  Options,
  PlainObject,
} from "select2";
import "select2/dist/css/select2.css";

export interface Select2Object {
  id: number;
  text: string;
}

// biome-ignore lint/suspicious/noExplicitAny: You have to do it at some point
export type RemoteResult = any;
export type AjaxResponse = AjaxOptions<DataFormat | GroupedDataFormat, RemoteResult>;

interface DataSource {
  ajax?: AjaxResponse | undefined;
  data?: RemoteResult | DataFormat[] | GroupedDataFormat[] | undefined;
}

interface Select2Options {
  element: Element;
  /** the data source, built with `localDataSource` or `remoteDataSource` */
  dataSource: DataSource;
  excluded?: number[];
  /** A callback to get the picture field from the API response */
  pictureGetter?: (element: LoadingData | DataFormat | GroupedDataFormat) => string;
  /** Any other select2 parameter to apply on the config */
  overrides?: Options;
}

/**
 * Create a new select2 with sith presets
 */
export function sithSelect2(options: Select2Options) {
  const elem: PlainObject = $(options.element);
  return elem.select2({
    theme: elem[0].multiple ? "classic" : "default",
    minimumInputLength: 2,
    templateResult: selectItemBuilder(options.pictureGetter),
    ...options.dataSource,
    ...(options.overrides ?? {}),
  });
}

interface LocalSourceOptions {
  excluded: () => number[];
}

/**
 * Build a data source for a Select2 from a local array
 */
export function localDataSource(
  source: Select2Object[] /** Array containing the data */,
  options: LocalSourceOptions,
): DataSource {
  if (options.excluded) {
    const ids = options.excluded();
    return { data: source.filter((i) => !ids.includes(i.id)) };
  }
  return { data: source };
}

interface RemoteSourceOptions {
  /** A callback to the ids to exclude from the search */
  excluded?: () => number[];
  /** A converter for a value coming from the remote api */
  resultConverter?: ((obj: RemoteResult) => DataFormat | GroupedDataFormat) | undefined;
  /** Any other select2 parameter to apply on the config */
  overrides?: AjaxOptions;
}

/**
 * Build a data source for a Select2 from a remote url
 */
export function remoteDataSource(
  source: string /** url of the endpoint */,
  options: RemoteSourceOptions,
): DataSource {
  $.ajaxSetup({
    traditional: true,
  });
  const params: AjaxOptions = {
    url: source,
    dataType: "json",
    cache: true,
    delay: 250,
    data: function (params) {
      return {
        search: params.term,
        exclude: [
          ...(this.val() || []).map((i: string) => Number.parseInt(i)),
          ...(options.excluded ? options.excluded() : []),
        ],
      };
    },
  };
  if (options.resultConverter) {
    params.processResults = (data) => ({
      results: data.results.map(options.resultConverter),
    });
  }
  if (options.overrides) {
    Object.assign(params, options.overrides);
  }
  return { ajax: params };
}

export function itemFormatter(user: { loading: boolean; text: string }) {
  if (user.loading) {
    return user.text;
  }
}

/**
 * Build a function to display the results
 */
export function selectItemBuilder(pictureGetter?: (item: RemoteResult) => string) {
  return (item: RemoteResult) => {
    const picture = typeof pictureGetter === "function" ? pictureGetter(item) : null;
    const imgHtml = picture
      ? `<img 
          src="${pictureGetter(item)}" 
          alt="${item.text}" 
          onerror="this.src = '/static/core/img/unknown.jpg'" 
        />`
      : "";

    return $(`<div class="select-item">
        ${imgHtml}
         <span class="select-item-text">${item.text}</span>
         </div>`);
  };
}
select 2 builder 2024-08-01 16:43:27 +00:00			`/**`
			`* Builders to use Select2 in our templates.`
			`*`
			`* This comes with two flavours : local data or remote data.`
			`*`
			`* # Local data source`
			`*`
			`* To use local data source, you must define an array`
			* in your JS code, having the fields `id` and `text`.
			`*`
			* ```js
			`* const data = [`
			`* {id: 1, text: "foo"},`
			`* {id: 2, text: "bar"},`
			`* ];`
			`* document.addEventListener("DOMContentLoaded", () => sithSelect2({`
			`* element: document.getElementById("select2-input"),`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* dataSource: localDataSource(data)`
select 2 builder 2024-08-01 16:43:27 +00:00			`* }));`
			* ```
			`*`
			`* You can also define a callback that return ids to exclude :`
			`*`
			* ```js
			`* const data = [`
			`* {id: 1, text: "foo"},`
			`* {id: 2, text: "bar"},`
			`* {id: 3, text: "to exclude"},`
			`* ];`
			`* document.addEventListener("DOMContentLoaded", () => sithSelect2({`
			`* element: document.getElementById("select2-input"),`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* dataSource: localDataSource(data, {`
select 2 builder 2024-08-01 16:43:27 +00:00			`* excluded: () => data.filter((i) => i.text === "to exclude").map((i) => parseInt(i))`
			`* })`
			`* }));`
			* ```
			`*`
			`* # Remote data source`
			`*`
			`* Select2 with remote data sources are similar to those with local`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			* data, but with some more parameters, like `resultConverter`,
select 2 builder 2024-08-01 16:43:27 +00:00			* which takes a callback that must return a `Select2Object`.
			`*`
			* ```js
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* import { makeUrl } from "#core:utils/api";`
			`* import {userSearchUsers } from "#openapi"`
select 2 builder 2024-08-01 16:43:27 +00:00			`* document.addEventListener("DOMContentLoaded", () => sithSelect2({`
			`* element: document.getElementById("select2-input"),`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* dataSource: remoteDataSource(await makeUrl(userSearchUsers), {`
select 2 builder 2024-08-01 16:43:27 +00:00			`* excluded: () => [1, 2], // exclude users 1 and 2 from the search`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* resultConverter: (user: AjaxResponse) => {id: user.id, text: (user.firstName as UserType)}`
select 2 builder 2024-08-01 16:43:27 +00:00			`* })`
			`* }));`
			* ```
			`*`
			`* # Overrides`
			`*`
			`* Dealing with a select2 may be complex.`
			`* That's why, when defining a select,`
			`* you may add an override parameter,`
			`* in which you can declare any parameter defined in the`
			`* Select2 documentation.`
			`*`
			* ```js
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* import { makeUrl } from "#core:utils/api";`
			`* import {userSearchUsers } from "#openapi"`
select 2 builder 2024-08-01 16:43:27 +00:00			`* document.addEventListener("DOMContentLoaded", () => sithSelect2({`
			`* element: document.getElementById("select2-input"),`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* dataSource: remoteDataSource(await makeUrl(userSearchUsers), {`
			`* resultConverter: (user: AjaxResponse) => {id: user.id, text: (user.firstName as UserType)}`
select 2 builder 2024-08-01 16:43:27 +00:00			`* overrides: {`
			`* delay: 500`
			`* }`
			`* })`
			`* }));`
			* ```
			`*`
			`* # Caveats with exclude`
			`*`
			`* With local data source, select2 evaluates the data only once.`
			`* Thus, modify the exclude after the initialisation is a no-op.`
			`*`
			`* With remote data source, the exclude list will be evaluated`
			`* after each api response.`
			`* It makes it possible to bind the data returned by the callback`
			`* to some reactive data, thus making the exclude list dynamic.`
			`*`
			`* # Images`
			`*`
			`* Sometimes, you would like to display an image besides`
			`* the text on the select items.`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			* In this case, fill the `pictureGetter` option :
select 2 builder 2024-08-01 16:43:27 +00:00			`*`
			* ```js
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* import { makeUrl } from "#core:utils/api";`
			`* import {userSearchUsers } from "#openapi"`
select 2 builder 2024-08-01 16:43:27 +00:00			`* document.addEventListener("DOMContentLoaded", () => sithSelect2({`
			`* element: document.getElementById("select2-input"),`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* dataSource: remoteDataSource(await makeUrl(userSearchUsers), {`
			`* resultConverter: (user: AjaxResponse) => {id: user.id, text: (user.firstName as UserType)}`
select 2 builder 2024-08-01 16:43:27 +00:00			`* })`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* pictureGetter: (user) => user.profilePict,`
select 2 builder 2024-08-01 16:43:27 +00:00			`* }));`
			* ```
			`*`
			`* # Binding with alpine`
			`*`
			`* You can declare your select2 component in an Alpine data.`
			`*`
			* ```html
			`* <body>`
			`* <div x-data="select2_test">`
			`* <select x-ref="search" x-ref="select"></select>`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* <p x-text="currentSelection.id"></p>`
			`* <p x-text="currentSelection.text"></p>`
select 2 builder 2024-08-01 16:43:27 +00:00			`* </div>`
			`* </body>`
			`*`
			`* <script>`
			`* document.addEventListener("alpine:init", () => {`
			`* Alpine.data("select2_test", () => ({`
			`* selector: undefined,`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* currentSelect: {id: "", text: ""},`
select 2 builder 2024-08-01 16:43:27 +00:00			`*`
			`* init() {`
			`* this.selector = sithSelect2({`
			`* element: $(this.$refs.select),`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* dataSource: localDataSource(`
select 2 builder 2024-08-01 16:43:27 +00:00			`* [{id: 1, text: "foo"}, {id: 2, text: "bar"}]`
			`* ),`
			`* });`
			`* this.selector.on("select2:select", (event) => {`
			`* // select2 => Alpine signals here`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* this.currentSelect = this.selector.select2("data")`
select 2 builder 2024-08-01 16:43:27 +00:00			`* });`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`* this.$watch("currentSelected" (value) => {`
select 2 builder 2024-08-01 16:43:27 +00:00			`* // Alpine => select2 signals here`
			`* });`
			`* },`
			`* }));`
			`* })`
			`* </script>`
			`*/`

Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`import type {`
			`AjaxOptions,`
			`DataFormat,`
			`GroupedDataFormat,`
			`LoadingData,`
			`Options,`
			`PlainObject,`
			`} from "select2";`
			`import "select2/dist/css/select2.css";`
select 2 builder 2024-08-01 16:43:27 +00:00
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`export interface Select2Object {`
			`id: number;`
			`text: string;`
			`}`

			`// biome-ignore lint/suspicious/noExplicitAny: You have to do it at some point`
			`export type RemoteResult = any;`
			`export type AjaxResponse = AjaxOptions<DataFormat \| GroupedDataFormat, RemoteResult>;`

			`interface DataSource {`
			`ajax?: AjaxResponse \| undefined;`
			`data?: RemoteResult \| DataFormat[] \| GroupedDataFormat[] \| undefined;`
			`}`

			`interface Select2Options {`
			`element: Element;`
			/** the data source, built with `localDataSource` or `remoteDataSource` */
			`dataSource: DataSource;`
			`excluded?: number[];`
			`/** A callback to get the picture field from the API response */`
			`pictureGetter?: (element: LoadingData \| DataFormat \| GroupedDataFormat) => string;`
			`/** Any other select2 parameter to apply on the config */`
			`overrides?: Options;`
			`}`
select 2 builder 2024-08-01 16:43:27 +00:00
			`/**`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`* Create a new select2 with sith presets`
select 2 builder 2024-08-01 16:43:27 +00:00			`*/`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`export function sithSelect2(options: Select2Options) {`
			`const elem: PlainObject = $(options.element);`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`return elem.select2({`
			`theme: elem[0].multiple ? "classic" : "default",`
			`minimumInputLength: 2,`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`templateResult: selectItemBuilder(options.pictureGetter),`
			`...options.dataSource,`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`...(options.overrides ?? {}),`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`});`
select 2 builder 2024-08-01 16:43:27 +00:00			`}`

Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`interface LocalSourceOptions {`
			`excluded: () => number[];`
			`}`
select 2 builder 2024-08-01 16:43:27 +00:00
			`/**`
			`* Build a data source for a Select2 from a local array`
			`*/`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`export function localDataSource(`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`source: Select2Object[] /** Array containing the data */,`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`options: LocalSourceOptions,`
			`): DataSource {`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`if (options.excluded) {`
			`const ids = options.excluded();`
			`return { data: source.filter((i) => !ids.includes(i.id)) };`
			`}`
			`return { data: source };`
select 2 builder 2024-08-01 16:43:27 +00:00			`}`

Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`interface RemoteSourceOptions {`
			`/** A callback to the ids to exclude from the search */`
			`excluded?: () => number[];`
			`/** A converter for a value coming from the remote api */`
			`resultConverter?: ((obj: RemoteResult) => DataFormat \| GroupedDataFormat) \| undefined;`
			`/** Any other select2 parameter to apply on the config */`
			`overrides?: AjaxOptions;`
			`}`
select 2 builder 2024-08-01 16:43:27 +00:00
			`/**`
			`* Build a data source for a Select2 from a remote url`
			`*/`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`export function remoteDataSource(`
Update select2 documentation 2024-10-12 22:26:43 +00:00			`source: string /** url of the endpoint */,`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`options: RemoteSourceOptions,`
			`): DataSource {`
			`$.ajaxSetup({`
			`traditional: true,`
			`});`
			`const params: AjaxOptions = {`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`url: source,`
			`dataType: "json",`
			`cache: true,`
			`delay: 250,`
			`data: function (params) {`
			`return {`
			`search: params.term,`
			`exclude: [`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`...(this.val() \|\| []).map((i: string) => Number.parseInt(i)),`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`...(options.excluded ? options.excluded() : []),`
			`],`
			`};`
			`},`
			`};`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`if (options.resultConverter) {`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`params.processResults = (data) => ({`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`results: data.results.map(options.resultConverter),`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`});`
			`}`
			`if (options.overrides) {`
			`Object.assign(params, options.overrides);`
			`}`
			`return { ajax: params };`
select 2 builder 2024-08-01 16:43:27 +00:00			`}`

Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`export function itemFormatter(user: { loading: boolean; text: string }) {`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`if (user.loading) {`
			`return user.text;`
			`}`
select 2 builder 2024-08-01 16:43:27 +00:00			`}`

			`/**`
			`* Build a function to display the results`
			`*/`
Remove select2 from vendored * Make core/utils/select2.ts * Convert viewer-index.js to typescript 2024-10-12 22:28:21 +00:00			`export function selectItemBuilder(pictureGetter?: (item: RemoteResult) => string) {`
			`return (item: RemoteResult) => {`
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`const picture = typeof pictureGetter === "function" ? pictureGetter(item) : null;`
			`const imgHtml = picture`
use spaces for indentation 2024-10-08 11:54:44 +00:00			? `<img
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`src="${pictureGetter(item)}"`
apply review comments 2024-09-10 20:55:39 +00:00			`alt="${item.text}"`
			`onerror="this.src = '/static/core/img/unknown.jpg'"`
			/>`
use spaces for indentation 2024-10-08 11:54:44 +00:00			`: "";`
select 2 builder 2024-08-01 16:43:27 +00:00
use spaces for indentation 2024-10-08 11:54:44 +00:00			return $(`<div class="select-item">
Apply all biomejs fixes 2024-10-08 15:14:22 +00:00			`${imgHtml}`
select 2 builder 2024-08-01 16:43:27 +00:00			`<span class="select-item-text">${item.text}</span>`
Format with biome instead of standard 2024-10-07 23:33:21 +00:00			</div>`);
use spaces for indentation 2024-10-08 11:54:44 +00:00			`};`
select 2 builder 2024-08-01 16:43:27 +00:00			`}`