@ui5/webcomponents-base 0.0.0-d0bcf47c7 → 0.0.0-d4d43327a

package/src/UI5ElementMetadata.ts

@@ -0,0 +1,389 @@
+import DataType from "./types/DataType.js";
+import { camelToKebabCase } from "./util/StringHelper.js";
+import { getSlottedNodes } from "./util/SlotsHelper.js";
+import { getEffectiveScopingSuffixForTag } from "./CustomElementsScopeUtils.js";
+
+type SlotInvalidation = {
+	properties: boolean | Array<string>,
+	slots: boolean | Array<string>,
+}
+
+type Slot = {
+	type: typeof Node | typeof HTMLElement,
+	default?: boolean,
+	propertyName?: string,
+	individualSlots?: boolean,
+	invalidateOnChildChange?: boolean | SlotInvalidation,
+};
+
+type SlotValue = Node;
+
+type Property = {
+	type?: BooleanConstructor | StringConstructor | ObjectConstructor | DataType
+	validator?: DataType,
+	defaultValue?: PropertyValue,
+	noAttribute?: boolean,
+	multiple?: boolean,
+	compareValues?: boolean,
+}
+
+type PropertyValue = boolean | number | string | object | undefined | null | DataType;
+
+type EventData = Record<string, object>;
+
+type Metadata = {
+	tag?: string,
+	managedSlots?: boolean,
+	properties?: Record<string, Property>,
+	slots?: Record<string, Slot>,
+	events?: EventData,
+	fastNavigation?: boolean,
+	themeAware?: boolean,
+	languageAware?: boolean,
+};
+
+type State = Record<string, PropertyValue | Array<SlotValue>>;
+
+/**
+ *
+ * @class
+ * @public
+ */
+class UI5ElementMetadata {
+	metadata: Metadata;
+	_initialState: State | undefined;
+
+	constructor(metadata: Metadata) {
+		this.metadata = metadata;
+	}
+
+	getInitialState() {
+		if (Object.prototype.hasOwnProperty.call(this, "_initialState")) {
+			return this._initialState!;
+		}
+		const initialState: State = {};
+		const slotsAreManaged = this.slotsAreManaged();
+
+		// Initialize properties
+		const props = this.getProperties();
+		for (const propName in props) { // eslint-disable-line
+			const propType = props[propName].type;
+			const propDefaultValue = props[propName].defaultValue;
+
+			if (propType === Boolean) {
+				initialState[propName] = false;
+
+				if (propDefaultValue !== undefined) {
+					console.warn("The 'defaultValue' metadata key is ignored for all booleans properties, they would be initialized with 'false' by default"); // eslint-disable-line
+				}
+			} else if (props[propName].multiple) {
+				initialState[propName] = [];
+			} else if (propType === Object) {
+				initialState[propName] = "defaultValue" in props[propName] ? props[propName].defaultValue : {};
+			} else if (propType === String) {
+				initialState[propName] = "defaultValue" in props[propName] ? props[propName].defaultValue : "";
+			} else {
+				initialState[propName] = propDefaultValue;
+			}
+		}
+
+		// Initialize slots
+		if (slotsAreManaged) {
+			const slots = this.getSlots();
+			for (const [slotName, slotData] of Object.entries<Slot>(slots)) { // eslint-disable-line
+				const propertyName = slotData.propertyName || slotName;
+				initialState[propertyName] = [];
+			}
+		}
+
+		this._initialState = initialState;
+		return initialState;
+	}
+
+	/**
+	 * Validates the property's value and returns it if correct
+	 * or returns the default value if not.
+	 * <b>Note:</b> Only intended for use by UI5Element.js
+	 * @public
+	 */
+	static validatePropertyValue(value: PropertyValue, propData: Property) {
+		const isMultiple = propData.multiple;
+		if (isMultiple && value) {
+			return (value as Array<PropertyValue>).map((propValue: PropertyValue) => validateSingleProperty(propValue, propData));
+		}
+		return validateSingleProperty(value, propData);
+	}
+
+	/**
+	 * Validates the slot's value and returns it if correct
+	 * or throws an exception if not.
+	 * <b>Note:</b> Only intended for use by UI5Element.js
+	 * @pubic
+	 */
+	static validateSlotValue(value: Node, slotData: Slot) {
+		return validateSingleSlot(value, slotData);
+	}
+
+	/**
+	 * Returns the tag of the UI5 Element without the scope
+	 * @public
+	 */
+	getPureTag() {
+		return this.metadata.tag || "";
+	}
+
+	/**
+	 * Returns the tag of the UI5 Element
+	 * @public
+	 */
+	getTag() {
+		const pureTag = this.metadata.tag;
+
+		if (!pureTag) {
+			return "";
+		}
+
+		const suffix = getEffectiveScopingSuffixForTag(pureTag);
+		if (!suffix) {
+			return pureTag;
+		}
+
+		return `${pureTag}-${suffix}`;
+	}
+
+	/**
+	 * Determines whether a property should have an attribute counterpart
+	 * @public
+	 * @param propName
+	 * @returns {boolean}
+	 */
+	hasAttribute(propName: string) {
+		const propData = this.getProperties()[propName];
+		return propData.type !== Object && !propData.noAttribute && !propData.multiple;
+	}
+
+	/**
+	 * Returns an array with the properties of the UI5 Element (in camelCase)
+	 * @public
+	 * @returns {string[]}
+	 */
+	getPropertiesList() {
+		return Object.keys(this.getProperties());
+	}
+
+	/**
+	 * Returns an array with the attributes of the UI5 Element (in kebab-case)
+	 * @public
+	 * @returns {string[]}
+	 */
+	getAttributesList() {
+		return this.getPropertiesList().filter(this.hasAttribute.bind(this)).map(camelToKebabCase);
+	}
+
+	/**
+	 * Determines whether this UI5 Element has a default slot of type Node, therefore can slot text
+	 * @returns {boolean}
+	 */
+	canSlotText() {
+		const defaultSlot = this.getSlots().default;
+		return defaultSlot && defaultSlot.type === Node;
+	}
+
+	/**
+	 * Determines whether this UI5 Element supports any slots
+	 * @public
+	 */
+	hasSlots() {
+		return !!Object.entries(this.getSlots()).length;
+	}
+
+	/**
+	 * Determines whether this UI5 Element supports any slots with "individualSlots: true"
+	 * @public
+	 */
+	hasIndividualSlots() {
+		return this.slotsAreManaged() && Object.values(this.getSlots()).some(slotData => slotData.individualSlots);
+	}
+
+	/**
+	 * Determines whether this UI5 Element needs to invalidate if children are added/removed/changed
+	 * @public
+	 */
+	slotsAreManaged() {
+		return !!this.metadata.managedSlots;
+	}
+
+	/**
+	 * Determines whether this control supports F6 fast navigation
+	 * @public
+	 */
+	supportsF6FastNavigation() {
+		return !!this.metadata.fastNavigation;
+	}
+
+	/**
+	 * Returns an object with key-value pairs of properties and their metadata definitions
+	 * @public
+	 */
+	getProperties() {
+		if (!this.metadata.properties) {
+			this.metadata.properties = {};
+		}
+		return this.metadata.properties;
+	}
+
+	/**
+	 * Returns an object with key-value pairs of events and their metadata definitions
+	 * @public
+	 */
+	getEvents() {
+		if (!this.metadata.events) {
+			this.metadata.events = {};
+		}
+		return this.metadata.events;
+	}
+
+	/**
+	 * Returns an object with key-value pairs of slots and their metadata definitions
+	 * @public
+	 */
+	 getSlots() {
+		if (!this.metadata.slots) {
+			this.metadata.slots = {};
+		}
+		return this.metadata.slots;
+	}
+
+	/**
+	 * Determines whether this UI5 Element has any translatable texts (needs to be invalidated upon language change)
+	 * @returns {boolean}
+	 */
+	isLanguageAware() {
+		return !!this.metadata.languageAware;
+	}
+
+	/**
+	 * Determines whether this UI5 Element has any theme dependant carachteristics.
+	 * @returns {boolean}
+	 */
+	 isThemeAware() {
+		return !!this.metadata.themeAware;
+	}
+
+	/**
+	 * Matches a changed entity (property/slot) with the given name against the "invalidateOnChildChange" configuration
+	 * and determines whether this should cause and invalidation
+	 *
+	 * @param slotName the name of the slot in which a child was changed
+	 * @param type the type of change in the child: "property" or "slot"
+	 * @param name the name of the property/slot that changed
+	 * @returns {boolean}
+	 */
+	shouldInvalidateOnChildChange(slotName: string, type: "property" | "slot", name: string) {
+		const config = this.getSlots()[slotName].invalidateOnChildChange;
+
+		// invalidateOnChildChange was not set in the slot metadata - by default child changes do not affect the component
+		if (config === undefined) {
+			return false;
+		}
+
+		// The simple format was used: invalidateOnChildChange: true/false;
+		if (typeof config === "boolean") {
+			return config;
+		}
+
+		// The complex format was used: invalidateOnChildChange: { properties, slots }
+		if (typeof config === "object") {
+			// A property was changed
+			if (type === "property") {
+				// The config object does not have a properties field
+				if (config.properties === undefined) {
+					return false;
+				}
+
+				// The config object has the short format: properties: true/false
+				if (typeof config.properties === "boolean") {
+					return config.properties;
+				}
+
+				// The config object has the complex format: properties: [...]
+				if (Array.isArray(config.properties)) {
+					return config.properties.includes(name);
+				}
+
+				throw new Error("Wrong format for invalidateOnChildChange.properties: boolean or array is expected");
+			}
+
+			// A slot was changed
+			if (type === "slot") {
+				// The config object does not have a slots field
+				if (config.slots === undefined) {
+					return false;
+				}
+
+				// The config object has the short format: slots: true/false
+				if (typeof config.slots === "boolean") {
+					return config.slots;
+				}
+
+				// The config object has the complex format: slots: [...]
+				if (Array.isArray(config.slots)) {
+					return config.slots.includes(name);
+				}
+
+				throw new Error("Wrong format for invalidateOnChildChange.slots: boolean or array is expected");
+			}
+		}
+
+		throw new Error("Wrong format for invalidateOnChildChange: boolean or object is expected");
+	}
+}
+
+const validateSingleProperty = (value: PropertyValue, propData: Property) => {
+	const propertyType = propData.type;
+	let propertyValidator = propData.validator;
+
+	if (propertyType && (propertyType as typeof DataType).isDataTypeClass) {
+		propertyValidator = propertyType as typeof DataType;
+	}
+
+	if (propertyValidator) {
+		return (propertyValidator as typeof DataType).isValid(value) ? value : propData.defaultValue;
+	}
+
+	if (!propertyType || propertyType === String) {
+		return (typeof value === "string" || typeof value === "undefined" || value === null) ? value : value.toString();
+	}
+
+	if (propertyType === Boolean) {
+		return typeof value === "boolean" ? value : false;
+	}
+
+	if (propertyType === Object) {
+		return typeof value === "object" ? value : propData.defaultValue;
+	}
+
+	// Check if "value" is part of the enum (propertyType) values and return the defaultValue if not found.
+	return value as string in propertyType ? value : propData.defaultValue;
+};
+
+const validateSingleSlot = (value: Node, slotData: Slot) => {
+	value && getSlottedNodes(value).forEach(el => {
+		if (!(el instanceof slotData.type)) {
+			throw new Error(`The element is not of type ${slotData.type.toString()}`);
+		}
+	});
+
+	return value;
+};
+
+export default UI5ElementMetadata;
+export type {
+	Property,
+	PropertyValue,
+	Slot,
+	SlotValue,
+	EventData,
+	State,
+	Metadata,
+};

package/src/animations/AnimationQueue.ts

@@ -0,0 +1,43 @@
+type TaskType =	() => Promise<void>;
+const tasks = new WeakMap<HTMLElement, Array<TaskType>>();
+
+class AnimationQueue {
+	static get tasks() {
+		return tasks;
+	}
+
+	static enqueue(element: HTMLElement, task: TaskType) {
+		if (!tasks.has(element)) {
+			tasks.set(element, []);
+		}
+
+		tasks.get(element)!.push(task);
+	}
+
+	static run(element: HTMLElement, task: TaskType): Promise<void> {
+		if (!tasks.has(element)) {
+			tasks.set(element, []);
+		}
+
+		return task().then(() => {
+			const elementTasks = tasks.get(element);
+
+			if (elementTasks!.length > 0) {
+				return AnimationQueue.run(element, elementTasks!.shift()!);
+			}
+			tasks.delete(element);
+		});
+	}
+
+	static push(element: HTMLElement, task: TaskType) {
+		const elementTasks = tasks.get(element);
+
+		if (elementTasks) {
+			AnimationQueue.enqueue(element, task);
+		} else {
+			AnimationQueue.run(element, task);
+		}
+	}
+}
+
+export default AnimationQueue;

package/src/animations/animate.ts

@@ -0,0 +1,64 @@
+import AnimationQueue from "./AnimationQueue.js";
+
+type AnimateOptions = {
+	beforeStart?: () => void,
+	duration: number,
+	element: HTMLElement,
+	advance: (p: number) => void,
+};
+
+const animate = (options: AnimateOptions) => {
+	let start: number | null = null;
+	let stopped = false;
+	let animationFrame: number;
+	let stop: () => void;
+	let advanceAnimation: (timestamp: number) => void;
+
+	const promise = new Promise<void>((resolve, reject) => {
+		advanceAnimation = timestamp => {
+			start = start || timestamp;
+
+			const timeElapsed = timestamp - start;
+			const remaining = options.duration - timeElapsed;
+
+			if (timeElapsed <= options.duration) {
+				const currentAdvance = 1 - remaining / options.duration; // easing formula (currently linear)
+				options.advance(currentAdvance);
+				if (!stopped) {
+					animationFrame = requestAnimationFrame(advanceAnimation);
+				}
+			} else {
+				options.advance(1);
+				resolve();
+			}
+		};
+
+		stop = () => {
+			stopped = true;
+			cancelAnimationFrame(animationFrame);
+			reject(new Error("animation stopped"));
+		};
+	}).catch((reason: Error) => reason);
+
+	AnimationQueue.push(options.element, () => {
+		if (typeof options.beforeStart === "function") {
+			options.beforeStart();
+		}
+
+		requestAnimationFrame(advanceAnimation);
+
+		return new Promise(resolve => {
+			promise.then(() => resolve());
+		});
+	});
+
+	return {
+		promise: () => promise,
+		stop: () => stop,
+	};
+};
+const duration = 400;
+
+export { duration };
+export type { AnimateOptions };
+export default animate;

package/src/animations/scroll.ts

@@ -0,0 +1,21 @@
+import animate, { duration } from "./animate.js";
+
+const scroll = (element: HTMLElement, dx: number, dy: number) => {
+	let scrollLeft: number;
+	let scrollTop: number;
+
+	return animate({
+		beforeStart: () => {
+			scrollLeft = element.scrollLeft;
+			scrollTop = element.scrollTop;
+		},
+		duration,
+		element,
+		advance: progress => {
+			element.scrollLeft = scrollLeft + (progress * dx); // easing - linear
+			element.scrollTop = scrollTop + (progress * dy); // easing - linear
+		},
+	});
+};
+
+export default scroll;

package/src/animations/slideDown.ts

@@ -0,0 +1,72 @@
+import animate, { duration } from "./animate.js";
+
+const slideDown = (element: HTMLElement) => {
+	let computedStyles: CSSStyleDeclaration,
+		paddingTop: number,
+		paddingBottom: number,
+		marginTop: number,
+		marginBottom: number,
+		height: number;
+	let storedOverflow: string,
+		storedPaddingTop: string,
+		storedPaddingBottom: string,
+		storedMarginTop: string,
+		storedMarginBottom: string,
+		storedHeight: string;
+
+	const animation = animate({
+		beforeStart: () => {
+			// Show the element to measure its properties
+			element.style.display = "block";
+
+			// Get Computed styles
+			computedStyles = getComputedStyle(element);
+			paddingTop = parseFloat(computedStyles.paddingTop);
+			paddingBottom = parseFloat(computedStyles.paddingBottom);
+			marginTop = parseFloat(computedStyles.marginTop);
+			marginBottom = parseFloat(computedStyles.marginBottom);
+			height = parseFloat(computedStyles.height);
+
+			// Store inline styles
+			storedOverflow = element.style.overflow;
+			storedPaddingTop = element.style.paddingTop;
+			storedPaddingBottom = element.style.paddingBottom;
+			storedMarginTop = element.style.marginTop;
+			storedMarginBottom = element.style.marginBottom;
+			storedHeight = element.style.height;
+
+			element.style.overflow = "hidden";
+			element.style.paddingTop = "0";
+			element.style.paddingBottom = "0";
+			element.style.marginTop = "0";
+			element.style.marginBottom = "0";
+			element.style.height = "0";
+		},
+		duration,
+		element,
+		advance: progress => {
+			// WORKAROUND
+			element.style.display = "block";
+			// END OF WORKAROUND
+
+			element.style.paddingTop = `${(paddingTop * progress)}px`;
+			element.style.paddingBottom = `${(paddingBottom * progress)}px`;
+			element.style.marginTop = `${(marginTop * progress)}px`;
+			element.style.marginBottom = `${(marginBottom * progress)}px`;
+			element.style.height = `${(height * progress)}px`;
+		},
+	});
+
+	animation.promise().then(() => {
+		element.style.overflow = storedOverflow;
+		element.style.paddingTop = storedPaddingTop;
+		element.style.paddingBottom = storedPaddingBottom;
+		element.style.marginTop = storedMarginTop;
+		element.style.marginBottom = storedMarginBottom;
+		element.style.height = storedHeight;
+	});
+
+	return animation;
+};
+
+export default slideDown;

package/src/animations/slideUp.ts

@@ -0,0 +1,67 @@
+import animate, { duration } from "./animate.js";
+
+const slideUp = (element: HTMLElement) => {
+	// Get Computed styles
+	let computedStyles: CSSStyleDeclaration,
+		paddingTop: number,
+		paddingBottom: number,
+		marginTop: number,
+		marginBottom: number,
+		height: number;
+
+	// Store inline styles
+	let storedOverflow: string,
+		storedPaddingTop: string,
+		storedPaddingBottom: string,
+		storedMarginTop: string,
+		storedMarginBottom: string,
+		storedHeight: string;
+
+	const animation = animate({
+		beforeStart: () => {
+			// Get Computed styles
+			const el = element;
+			computedStyles = getComputedStyle(el);
+			paddingTop = parseFloat(computedStyles.paddingTop);
+			paddingBottom = parseFloat(computedStyles.paddingBottom);
+			marginTop = parseFloat(computedStyles.marginTop);
+			marginBottom = parseFloat(computedStyles.marginBottom);
+			height = parseFloat(computedStyles.height);
+
+			// Store inline styles
+			storedOverflow = el.style.overflow;
+			storedPaddingTop = el.style.paddingTop;
+			storedPaddingBottom = el.style.paddingBottom;
+			storedMarginTop = el.style.marginTop;
+			storedMarginBottom = el.style.marginBottom;
+			storedHeight = el.style.height;
+
+			el.style.overflow = "hidden";
+		},
+		duration,
+		element,
+		advance: progress => {
+			element.style.paddingTop = `${paddingTop - (paddingTop * progress)}px`;
+			element.style.paddingBottom = `${paddingBottom - (paddingBottom * progress)}px`;
+			element.style.marginTop = `${marginTop - (marginTop * progress)}px`;
+			element.style.marginBottom = `${marginBottom - (marginBottom * progress)}px`;
+			element.style.height = `${height - (height * progress)}px`;
+		},
+	});
+
+	animation.promise().then(reason => {
+		if (!(reason instanceof Error)) {
+			element.style.overflow = storedOverflow;
+			element.style.paddingTop = storedPaddingTop;
+			element.style.paddingBottom = storedPaddingBottom;
+			element.style.marginTop = storedMarginTop;
+			element.style.marginBottom = storedMarginBottom;
+			element.style.height = storedHeight;
+			element.style.display = "none";
+		}
+	});
+
+	return animation;
+};
+
+export default slideUp;