NXT-20677: Added Star Ratings component

CHANGELOG.md

@@ -6,6 +6,7 @@ The following is a curated list of changes in the Enact limestone module, newest
 
 ### Added
 
+- new component `StarRatings`
 - `limestone/VerticalMarquee` to vertically scroll overflowing multi-line text via `ui/Marquee.MarqueeDecorator` configured with `orientation: 'vertical'`
 
 ### Fixed

StarRatings/Star.js

@@ -0,0 +1,210 @@
+import {adaptEvent, forProp, forward, handle} from '@enact/core/handle';
+import kind from '@enact/core/kind';
+import Spottable from '@enact/spotlight/Spottable';
+import PropTypes from 'prop-types';
+import compose from 'ramda/src/compose';
+
+import Icon from '../Icon';
+import iconList from '../Icon/IconList';
+import Skinnable from '../Skinnable';
+
+import css from './Star.module.less';
+
+const SpottableIcon = Spottable(Icon);
+
+// The star glyph, also drawn by the fill layer (`::after`) on top of the focus outline
+const STAR_GLYPH = String.fromCodePoint(iconList.star);
+
+/**
+ * Where the fill edge sits (`--star-fill`, % of the star's box) for each tenth of `value`.
+ *
+ * The glyph only covers about 9%–91% of its box, so plain tenths look wrong: a 10% fill shows
+ * almost nothing and a 90% fill looks full. 0.1 and 0.9 are pinned to 20% and 80%; the steps in
+ * between were measured on the Limestone star glyph so each tenth adds an equal share of the
+ * star's area (symmetric around 50%).
+ *
+ * @type {Number[]}
+ * @private
+ */
+const FILL_STEPS = [0, 20, 33, 39, 45, 50, 55, 61, 67, 80, 100];
+
+/**
+ * A single star of a [StarRatings]{@link limestone/StarRatings.StarRatings}, without any
+ * behaviors applied.
+ *
+ * The star fills from the start of the reading direction (left in LTR, right in RTL) by the
+ * amount set in `value`. While focused, it shows a white outline and a drop shadow that follow
+ * the star's shape. The star is a 108px Icon (Limestone has no preset that size, so the number
+ * is passed to `size`).
+ *
+ * @class StarBase
+ * @memberof limestone/StarRatings
+ * @ui
+ * @private
+ */
+const StarBase = kind({
+	name: 'Star',
+
+	propTypes: /** @lends limestone/StarRatings.StarBase.prototype */ {
+		/**
+		 * Unique identifier for the star.
+		 *
+		 * Also sent to `onClick`, so the parent can tell which star was selected.
+		 *
+		 * @type {String}
+		 * @required
+		 * @public
+		 */
+		id: PropTypes.string.isRequired,
+
+		/**
+		 * Disables the star and makes it non-interactive.
+		 *
+		 * The star is shown at 30% opacity and `onClick` is not called. Like other disabled
+		 * Limestone controls, it can still receive focus with the remote unless `readOnly` is also
+		 * set.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 * @public
+		 */
+		disabled: PropTypes.bool,
+
+		/**
+		 * Called when the star is selected.
+		 *
+		 * Receives an object with the star's `id` and the original event as `ev`.
+		 * Not called while `disabled` or `readOnly` is `true`.
+		 *
+		 * @type {Function}
+		 * @public
+		 */
+		onClick: PropTypes.func,
+
+		/**
+		 * Colors the empty (unselected) part of the star for the surface behind it.
+		 *
+		 * * `false`: `#FFFFFF33` (white at 20%), for dark backgrounds.
+		 * * `true`: `#1111111A` (near-black at 10%), for light overlay surfaces.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 * @public
+		 */
+		overlayMode: PropTypes.bool,
+
+		/**
+		 * Makes the star display-only.
+		 *
+		 * When `false`, the star can be focused with Spotlight and `onClick` is called when it is
+		 * clicked, tapped or selected with the remote. When `true`, the star cannot be focused
+		 * and ignores input.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 * @public
+		 */
+		readOnly: PropTypes.bool,
+
+		/**
+		 * The fill amount, from `0` (empty) to `1` (full).
+		 *
+		 * Rounded half-up to tenths (`0.55` → `0.6`), and each tenth fills the star by an equal
+		 * share of its area. Values outside `0`–`1` are clamped, and `NaN` shows an empty star.
+		 *
+		 * @type {Number}
+		 * @default 0
+		 * @public
+		 */
+		value: PropTypes.number
+	},
+
+	defaultProps: {
+		disabled: false,
+		overlayMode: false,
+		readOnly: false,
+		value: 0
+	},
+
+	styles: {
+		css,
+		className: 'star'
+	},
+
+	handlers: {
+		onClick: handle(
+			forProp('disabled', false),
+			forProp('readOnly', false),
+			adaptEvent(
+				(ev, {id}) => ({id, ev}),
+				forward('onClick')
+			)
+		)
+	},
+
+	computed: {
+		className: ({overlayMode, styler}) => styler.append({overlayMode}),
+		style: ({style, value}) => {
+			// Whole tenths, clamped to 0–10; `|| 0` also turns NaN into an empty star
+			const tenths = Math.min(Math.max(Math.round(value * 10) || 0, 0), 10);
+			return {...style, '--star-fill': FILL_STEPS[tenths] + '%'};
+		}
+	},
+
+	render: ({className, disabled, id, onClick, readOnly, style, ...rest}) => {
+		delete rest.overlayMode;
+		delete rest.value;
+
+		const IconComponent = readOnly ? Icon : SpottableIcon;
+
+		return (
+			<IconComponent
+				{...rest}
+				aria-disabled={disabled}
+				className={className}
+				data-glyph={STAR_GLYPH}
+				disabled={disabled}
+				id={id}
+				onClick={onClick}
+				style={style}
+				size={108}
+			>
+				star
+			</IconComponent>
+		);
+	}
+});
+
+/**
+ * Applies Limestone specific behaviors to
+ * [StarBase]{@link limestone/StarRatings.StarBase} components.
+ *
+ * @hoc
+ * @memberof limestone/StarRatings
+ * @mixes limestone/Skinnable.Skinnable
+ * @private
+ */
+const StarDecorator = compose(
+	Skinnable
+);
+
+/**
+ * A single Limestone styled star, used by
+ * [StarRatings]{@link limestone/StarRatings.StarRatings}.
+ *
+ * @class Star
+ * @memberof limestone/StarRatings
+ * @extends limestone/StarRatings.StarBase
+ * @mixes limestone/StarRatings.StarDecorator
+ * @ui
+ * @private
+ */
+const Star = StarDecorator(StarBase);
+
+export default Star;
+export {
+	FILL_STEPS,
+	Star,
+	StarBase,
+	StarDecorator
+};

StarRatings/Star.module.less

@@ -0,0 +1,147 @@
+@import "../styles/mixins.less";
+@import "../styles/variables.less";
+@import "../styles/skin.less";
+
+@star-active-color: #FFCA28;              // filled part of a star
+@star-inactive-color: #FFFFFF33;          // empty part of a star (white at 20%)
+@star-inactive-color-overlay: #1111111A;  // empty part with `overlayMode` (near-black at 10%)
+
+// Focus sizes are in `em`, relative to the star's size (Icon sets font-size to the icon size), so
+// they keep the mockup's proportions at any star size and resolution. They were measured on the
+// focus mockup with the star at 180px: `(17 * @star-px)` is 17px on a 180px star, ~10px on 108px.
+@star-px: (1em / 180);
+
+// Focus: white outline fully outside the star, and a soft shadow (matched to the design mockup)
+@star-focus-outline-color: #FFFFFF;
+@star-focus-outline-width: (17 * @star-px);
+@star-focus-shadow: drop-shadow(0 (24 * @star-px) (10 * @star-px) rgba(0, 0, 0, 0.3));
+
+// Room around the glyph for the outline layer, so its mask does not cut off the outline or shadow
+@star-focus-layer-space: (40 * @star-px);
+@star-focus-layer-space-bottom: (72 * @star-px); // the shadow falls downwards
+
+// The outline layer draws its own glyph in this key color; the knockout filter below turns every
+// pixel of that color transparent, leaving only the outline outside the star (and its shadow).
+@star-knockout-key: #FF0000;
+
+// SVG filter: red key pixels become transparent; white (outline) and black (shadow) are kept.
+// Color matrix: R' = G' = B' = R, A' = A - R + G. It expects a white outline color.
+// (A filter is used instead of a CSS mask because `-webkit-mask-clip: text` does not survive the
+// CSS re-serialization Storybook's pseudo-states addon does; a `url()` filter does.)
+@star-knockout-filter: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='knockout' color-interpolation-filters='sRGB'%3E%3CfeColorMatrix type='matrix' values='1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 -1 1 0 1 0'/%3E%3C/filter%3E%3C/svg%3E#knockout");
+
+// A round outline made of 16 copies of the glyph, moved @w in every direction around a circle
+.star-outline-shadows(@w; @color) {
+	text-shadow:
+		@w 0 0 @color,
+			(@w * 0.9239) (@w * 0.3827) 0 @color,
+			(@w * 0.7071) (@w * 0.7071) 0 @color,
+			(@w * 0.3827) (@w * 0.9239) 0 @color,
+		0 @w 0 @color,
+			(@w * -0.3827) (@w * 0.9239) 0 @color,
+			(@w * -0.7071) (@w * 0.7071) 0 @color,
+			(@w * -0.9239) (@w * 0.3827) 0 @color,
+		-@w 0 0 @color,
+			(@w * -0.9239) (@w * -0.3827) 0 @color,
+			(@w * -0.7071) (@w * -0.7071) 0 @color,
+			(@w * -0.3827) (@w * -0.9239) 0 @color,
+			0 -@w 0 @color,
+			(@w * 0.3827) (@w * -0.9239) 0 @color,
+			(@w * 0.7071) (@w * -0.7071) 0 @color,
+			(@w * 0.9239) (@w * -0.3827) 0 @color;
+}
+
+// How a star is drawn:
+// - the element's own glyph is transparent (it only sets the size and position);
+// - `::after` draws the fill on top: the same glyph, colored by the fill gradient;
+// - while focused, `::before` draws the outline and its shadow behind the fill. A filter cuts the
+//   glyph's own shape out of that layer, so the fill's colors look the same with or without focus.
+.star {
+	// Empty-part color, switched by the `overlayMode` prop
+	--star-inactive-color: @star-inactive-color;
+
+	&.overlayMode {
+		--star-inactive-color: @star-inactive-color-overlay;
+	}
+
+	// Touch handling
+	touch-action: manipulation;               // no double-tap-zoom delay
+	-webkit-tap-highlight-color: transparent; // no grey flash on tap
+	-webkit-user-select: none;                // a long press won't select the glyph
+	user-select: none;
+	-webkit-touch-callout: none;              // no long-press context menu
+
+	// Inside applySkins so these beat Icon's own `.icon` rules regardless of CSS load order
+	.applySkins({
+		// Design: a 108px box (size={108} in Star.js) with 4px/2px padding inside it.
+		// The visible layers are positioned on the padding box, so the glyph stays centered.
+		box-sizing: border-box;
+		// 2px is written in rem: Enact pins px values this small to a fixed 1px at every resolution
+		padding: 4px (2rem / 48);
+		margin: 0; // Icon's own margin would add to the row's 60px gap
+		position: relative;
+		overflow: visible; // Icon clips by default; the focus outline extends past the glyph's box
+		color: transparent;
+		// The star's own glyph must never paint: `-webkit-text-fill-color` wins over any `color`
+		// a theme sets on focused elements (that would show through the translucent empty color)
+		-webkit-text-fill-color: transparent;
+
+		// Fill layer: partial stars fill from the reading direction's start (flipped for RTL below)
+		&::after {
+			content: attr(data-glyph);
+			position: absolute;
+			top: 0;
+			right: 0;
+			bottom: 0;
+			left: 0;
+			background: linear-gradient(
+				var(--star-direction, to right),
+				@star-active-color var(--star-fill, 0%),
+				var(--star-inactive-color) var(--star-fill, 0%)
+			);
+			-webkit-background-clip: text;
+			background-clip: text;
+			color: transparent;
+		}
+
+		// Focused star only (remote, pointer, tap or drag)
+		&:focus {
+			outline: none; // no browser focus ring around the box
+		}
+
+		// While focused, the fill reaches 0.5px past the glyph's edge (a transparent stroke is still
+		// painted by the clipped background), covering the outline's anti-aliased inner edge.
+		// Otherwise the background shows through as a thin dark seam around a filled star.
+		&:focus::after {
+			-webkit-text-stroke: 1px transparent;
+		}
+
+		// Outline layer: a larger box, padded so its glyph sits exactly where the star's glyph is
+		&:focus::before {
+			content: attr(data-glyph);
+			position: absolute;
+			top: -@star-focus-layer-space;
+			right: -@star-focus-layer-space;
+			bottom: -@star-focus-layer-space-bottom;
+			left: -@star-focus-layer-space;
+			padding: @star-focus-layer-space @star-focus-layer-space @star-focus-layer-space-bottom;
+			color: @star-knockout-key;
+			-webkit-text-fill-color: @star-knockout-key;
+			.star-outline-shadows(@star-focus-outline-width; @star-focus-outline-color);
+			// Shadow first (from the whole shape), then remove the glyph's own shape. The shadow
+			// under the glyph is removed with it, so nothing changes inside the star.
+			filter: @star-focus-shadow @star-knockout-filter;
+		}
+
+		// Disabled: 30% opacity (Limestone's @lime-disabled-opacity), also while focused
+		.disabled({
+			.lime-disabled-colors();
+		});
+	});
+}
+
+// RTL locales: the row of stars is already mirrored by flex,
+// so partial stars must also fill from the right
+:global(.enact-locale-right-to-left) .star {
+	--star-direction: to left;
+}