import type { ElementLink } from './data'; /** * Most {@link IElementSDK | `reactElements`} `select*` methods accept one of two types of arguments: * a manifest key for automatic editor handling, or explicit options to manage the value yourself. * Use manifest-key mode to let the editor connect the picker to a manifest-backed data or style field. * Use explicit-options mode when your panel owns the selected value and handles callbacks itself. * Some picker methods are currently manifest-key only. * * @see IElementSDK.selectFont * @see IElementSDK.selectFontFamily * @see IElementSDK.selectFontWeight * @see IElementSDK.selectMedia * @see IElementSDK.selectLink * @see IElementSDK.selectColor */ export interface IPickerModes { } /** A font family and weight selection returned from {@link SelectFontParams} or {@link SelectFontFamilyParams}. */ export interface IFontFamily { /** * The font family name. Font options vary depending on site theme, custom uploads, and which fonts are available in the editor, such as Google fonts. Call {@link SelectFontParams} or * {@link SelectFontFamilyParams} to get the `family` from the Wix user's selection rather * than hard coding names in your panel. */ family: string; /** * The font weight. Either a numeric string from `'100'`–`'900'` or a named value such as `'normal'` or `'bold'`. * Available weight options depend on the selected font family. Call {@link SelectFontParams} or {@link SelectFontWeightParams} * to get the available weight options based on the Wix user's selection. */ weight: string; } /** Represents a font weight value. */ export interface IFontWeight { /** * The font weight. Either a numeric string from `'100'`–`'900'` or a named value such as `'normal'` or `'bold'`. * Available weight options depend on the selected font family. Call {@link SelectFontParams} or {@link SelectFontWeightParams} * to get the available weight options based on the Wix user's selection. */ weight: string; } /** Combination of font family and weight properties. */ export type IFontFamilyAndWeight = IFontFamily & IFontWeight; /** * Extra settings passed as `options` when calling `reactElements.selectLink`. */ export type ISelectLinkSharedOptions = { /** * Optional BI tag for where the link picker was opened from in the panel. Use a * kebab-case string specific to your app, for example `header-cta` or `settings-link`. */ origin?: string; }; /** * Options for `inputs.selectLink()`. * The selected value is returned to the caller and isn't persisted automatically. */ export type SelectLinkInputParams = { /** Existing link to pre-populate the picker with. */ value?: ElementLink; /** Optional settings such as BI attribution and allowed link types. */ options?: ISelectLinkSharedOptions & { /** * Restricts the picker to specific link types. * For example: `['ExternalLink', 'PageLink']`. */ linkTypes?: string[]; }; }; /** * How the editor positions a floating picker popup relative to the element in the panel that caused the picker to open. */ export type IPanelOptions = { /** Preferred side or corner for the picker popup to appear relative to the element in the panel that caused the picker to open. */ placement?: 'top' | 'bottom' | 'top-start' | 'bottom-start' | 'top-end' | 'bottom-end'; /** Extra vertical offset in pixels from the default position beside the element in the panel that caused the picker to open. */ YShift?: number; }; /** * Options for {@link IElementSDK.selectFont | `reactElements.selectFont()`}. * Pass either a manifest key or explicit options. See {@link IPickerModes}. */ export type SelectFontParams = { /** Pass a manifest key: field connected to `styleItemKey` in the manifest. See {@link IPickerModes}. */ styleItemKey: string; } | { /** Font family and weight shown when the picker opens. See {@link IPickerModes}. */ selectedFontFamily?: IFontFamilyAndWeight; /** DOM element in your panel that caused the picker to open. */ target?: HTMLElement; /** Where the picker popup appears relative to `target`. */ panelOptions?: IPanelOptions; /** Called when the user confirms a selection. */ onChange?: (value: IFontFamilyAndWeight) => void; /** Called while the user is hovering over options before confirming. */ onPreview?: (value: IFontFamilyAndWeight) => void; }; /** * Options for {@link IElementSDK.selectFontFamily | `reactElements.selectFontFamily()`}. * Pass either a manifest key or explicit options. See {@link IPickerModes}. */ export type SelectFontFamilyParams = { /** Pass a manifest key: field connected to `styleItemKey` in the manifest. See {@link IPickerModes}. */ styleItemKey: string; } | { /** Font family shown when the picker opens. See {@link IPickerModes}. */ selectedFontFamily?: IFontFamily; /** DOM element in your panel that caused the picker to open. */ target?: HTMLElement; /** Where the picker popup appears relative to `target`. */ panelOptions?: IPanelOptions; /** Called when the user confirms a selection. */ onChange?: (value: IFontFamily) => void; /** Called while the user is hovering over options before confirming. */ onPreview?: (value: IFontFamily) => void; }; /** * Options for {@link IElementSDK.selectFontWeight | `reactElements.selectFontWeight()`}. * Pass either a manifest key or explicit options. See {@link IPickerModes}. */ export type SelectFontWeightParams = { /** Pass a manifest key: field connected to `fontFamilyStyleItemKey` in the manifest. See {@link IPickerModes}. */ fontFamilyStyleItemKey: string; /** Pass a manifest key: field connected to `fontWeightStyleItemKey` in the manifest. See {@link IPickerModes}. */ fontWeightStyleItemKey: string; } | { /** Pass a manifest key: field connected to `fontStyleItemKey` in the manifest. See {@link IPickerModes}. */ fontStyleItemKey: string; } | { /** Font family used to filter available weights. Omit to show all weights. See {@link IPickerModes}. */ fontFamily?: IFontFamily; /** DOM element in your panel that caused the picker to open. */ target?: HTMLElement; /** Called when the user selects a weight. */ onChange?: (value: IFontWeight) => void; }; /** * Options for {@link IElementSDK.selectMedia | `reactElements.selectMedia()`}. * Pass either a manifest key or explicit options. See {@link IPickerModes}. */ export type SelectMediaParams = { /** Pass a manifest key: field connected to `dataItemKey` in the manifest. See {@link IPickerModes}. */ dataItemKey: string; } | { /** Whether the user can select multiple media items at once. See {@link IPickerModes}. */ isMultiSelect?: boolean; /** Restricts the media library to a specific category, for example `'image'`. */ category?: string; }; /** * Options for {@link IElementSDK.selectLink | `reactElements.selectLink()`}. * Pass either a manifest key or explicit options. See {@link IPickerModes}. */ export type SelectLinkParams = { /** Pass a manifest key: field connected to `dataItemKey` in the manifest. See {@link IPickerModes}. */ dataItemKey: string; /** Optional settings. See {@link ISelectLinkSharedOptions}. */ options?: ISelectLinkSharedOptions; } | { /** Existing link to pre-populate the picker with. See {@link IPickerModes}. */ value?: ElementLink; /** Optional settings such as BI attribution and allowed link types. See {@link ISelectLinkSharedOptions}. */ options?: ISelectLinkSharedOptions & { /** * Restricts the picker to specific link types. * For example: `['ExternalLink', 'PageLink']`. */ linkTypes?: string[]; /** * Restricts dynamic-page link results to specific installed apps. * Pass the app definition IDs assigned to those apps in the Wix Dev Center. */ appIds?: string[]; /** Whether to hide the option to link to an inner route of a dynamic page, showing only the page itself. */ hideInnerRoute?: boolean; }; }; /** * Options for {@link IElementSDK.selectSort | `reactElements.selectSort()`}. * Pass a manifest key for automatic editor handling. See {@link IPickerModes}. */ export type SelectSortParams = { /** Pass a manifest key: field connected to `dataItemKey` in the manifest. See {@link IPickerModes}. */ dataItemKey: string; }; /** * Options for {@link IElementSDK.selectFilter | `reactElements.selectFilter()`}. * Pass a manifest key for automatic editor handling. See {@link IPickerModes}. */ export type SelectFilterParams = { /** Pass a manifest key: field connected to `dataItemKey` in the manifest. See {@link IPickerModes}. */ dataItemKey: string; }; /** * Options for {@link IElementSDK.selectColor | `reactElements.selectColor()`}. * Pass either a manifest key or explicit options. See {@link IPickerModes}. */ export type SelectColorParams = { /** Pass a manifest key: field connected to `styleItemKey` in the manifest. See {@link IPickerModes}. */ styleItemKey: string; } | { /** Initial color when the picker opens, as a CSS color string. See {@link IPickerModes}. */ initialValue?: string; /** * Color modes to offer. Defaults to `['solid']`. * Include `'gradient'` to enable gradient selection. */ mode?: ('solid' | 'gradient')[]; /** Whether to show the site's brand color palette. */ showBrand?: boolean; /** Whether to show the custom color input. */ showCustom?: boolean; /** Whether to show the advanced settings panel. */ showAdvancedSettings?: boolean; /** Whether to show the opacity / alpha slider. */ showOpacity?: boolean; /** Screen-space position `{ x, y }` where the color picker should open. */ position?: { x: number; y: number; }; /** BI tracking metadata. `origin` identifies the UI surface that opened the picker. */ biData?: { origin: string; }; /** Called on every color change while the picker is open. */ onChange?: (color: string) => void; /** Called when the user explicitly confirms a color selection. */ onApply?: (color: string) => void; /** Called when the picker is closed, whether or not a color was confirmed. */ onClose?: () => void; /** Called when the user cancels without confirming. */ onCancel?: () => void; }; /** * Options for `reactElements.selectTextTheme()` from a custom panel. */ export type SelectTextThemeParams = { /** DOM element in your panel that caused the picker to open. */ target?: HTMLElement; /** Initial values to pre-populate the picker with. */ initialValue?: { /** Initial font value, as CSS font shorthand or a theme token. */ font?: string; /** Initial color value, as a CSS color string or a theme token. */ color?: string; }; }; export type SelectedTextTheme = { /** Selected font, as CSS font shorthand or a theme token. */ font?: string; /** Selected color, as a CSS color string or a theme token. */ color?: string; /** Selected text-decoration-line, as a canonical CSS value (e.g. `'none'`, `'underline'`, `'line-through'`). */ textDecorationLine?: string; /** Selected letter-spacing, as a CSS length or `'normal'` (e.g. `'0.5px'`). */ letterSpacing?: string; };