feat(evo-marko): evo-star-rating (#633)

Author: LuLaValva

.changeset/young-snakes-bet.md

@@ -0,0 +1,5 @@
+---
+"@evo-web/marko": patch
+---
+
+Add evo-star-rating component

packages/evo-marko/src/tags/evo-star-rating/README.md

@@ -0,0 +1,12 @@
+<h1 style='display: flex; justify-content: space-between; align-items: center;'>
+    <span>evo-star-rating</span>
+    <span style='font-weight: normal; font-size: medium; margin-bottom: -15px;'>DS v1.0.0</span>
+</h1>
+
+Displays a read-only star rating from 0 to 5, with half-star support.
+
+## Examples and Documentation
+
+- [Storybook](https://ebay.github.io/evo-web/ebayui-core/?path=/story/graphics-icons-evo-star-rating)
+- [Storybook Docs](https://ebay.github.io/evo-web/ebayui-core/?path=/docs/graphics-icons-evo-star-rating)
+- [Code Examples](https://github.com/eBay/evo-web/tree/main/packages/evo-marko/src/tags/evo-star-rating/examples)

packages/evo-marko/src/tags/evo-star-rating/examples/all-values.marko

@@ -0,0 +1,22 @@
+<style>
+    .star-rating-examples {
+        display: flex;
+        row-gap: 10px;
+        flex-direction: column;
+        align-items: flex-start;
+    }
+</style>
+
+<div class="star-rating-examples">
+    <evo-star-rating value=0 a11yText="0 stars"/>
+    <evo-star-rating value=0.5 a11yText="0.5 stars"/>
+    <evo-star-rating value=1 a11yText="1 star"/>
+    <evo-star-rating value=1.5 a11yText="1.5 stars"/>
+    <evo-star-rating value=2 a11yText="2 stars"/>
+    <evo-star-rating value=2.5 a11yText="2.5 stars"/>
+    <evo-star-rating value=3 a11yText="3 stars"/>
+    <evo-star-rating value=3.5 a11yText="3.5 stars"/>
+    <evo-star-rating value=4 a11yText="4 stars"/>
+    <evo-star-rating value=4.5 a11yText="4.5 stars"/>
+    <evo-star-rating value=5 a11yText="5 stars"/>
+</div>

packages/evo-marko/src/tags/evo-star-rating/examples/default.marko

@@ -0,0 +1,3 @@
+import type { Input as StarRatingInput } from "<evo-star-rating>";
+export interface Input extends StarRatingInput {}
+<evo-star-rating ...input/>

packages/evo-marko/src/tags/evo-star-rating/index.marko

@@ -0,0 +1,30 @@
+static function toDataStars(value: number): string {
+    const clamped = Math.max(0, Math.min(5, value));
+    const rounded = Math.round(clamped * 2) / 2;
+    const whole = Math.floor(rounded);
+    const half = rounded % 1 !== 0;
+    return half ? `${whole}-5` : `${whole}`;
+}
+
+export interface Input extends Omit<Marko.HTML.Div, "aria-label" | "role"> {
+    value?: number;
+    /**
+     * Accessible label for the star rating.
+     *
+     * English default to be overridden is `"Rating: ${value} out of 5"`.
+     */
+    a11yText: string;
+}
+
+<const/{ class: inputClass, value = 0, a11yText = `Rating: ${value} out of 5`, ...htmlInput }=input>
+
+<div
+    ...htmlInput
+    role="img"
+    aria-label=a11yText
+    class=["star-rating", inputClass]
+    data-stars=toDataStars(value)>
+    <for until=5>
+        <evo-icon-star-dynamic class="star-rating__icon"/>
+    </for>
+</div>

packages/evo-marko/src/tags/evo-star-rating/star-rating.stories.ts

@@ -0,0 +1,46 @@
+import { buildExtensionTemplate } from "../../common/storybook/utils";
+import { type Meta } from "@storybook/marko";
+import Readme from "./README.md";
+import Component, { type Input } from "./index.marko";
+import DefaultTemplate from "./examples/default.marko";
+import DefaultCode from "./examples/default.marko?raw";
+import AllValuesTemplate from "./examples/all-values.marko";
+import AllValuesCode from "./examples/all-values.marko?raw";
+
+export default {
+  title: "graphics & icons/evo-star-rating",
+  component: Component,
+  parameters: {
+    docs: {
+      description: { component: Readme },
+    },
+  },
+  argTypes: {
+    value: {
+      type: "number",
+      control: { type: "range", min: 0, max: 5, step: 0.5 },
+      description:
+        "The star rating value from 0 to 5. Supports half values (e.g. 2.5).",
+    },
+    a11yText: {
+      type: { name: "string", required: true },
+      control: "text",
+      description:
+        'Accessible label for the star rating. English default to be overridden is `"Rating: ${value} out of 5"`.',
+    },
+    ["<div> attributes" as any]: {
+      description:
+        "All attributes and event handlers from [the native HTML `<div>` tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div) will be passed through",
+    },
+  },
+} satisfies Meta<Input>;
+
+export const Default = buildExtensionTemplate(DefaultTemplate, DefaultCode);
+Default.args = {
+  value: 3.5,
+};
+
+export const AllValues = buildExtensionTemplate(
+  AllValuesTemplate,
+  AllValuesCode,
+);

packages/evo-marko/src/tags/evo-star-rating/style.ts

@@ -0,0 +1 @@
+import "@ebay/skin/star-rating";

packages/evo-marko/src/tags/evo-star-rating/test/test.browser.ts

@@ -0,0 +1,36 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { render, cleanup } from "@marko/testing-library";
+import { composeStories } from "@storybook/marko";
+import * as stories from "../star-rating.stories";
+
+const { Default } = composeStories(stories);
+
+afterEach(cleanup);
+
+describe("evo-star-rating", () => {
+  let component: Awaited<ReturnType<typeof render>>;
+
+  beforeEach(async () => {
+    component = await render(Default);
+  });
+
+  it("should render with role img", () => {
+    expect(component.getByRole("img")).toBeTruthy();
+  });
+
+  it("should have correct data-stars attribute", () => {
+    const el = component.getByRole("img");
+    expect(el.getAttribute("data-stars")).toBe("3-5");
+  });
+
+  it("should have default aria-label", () => {
+    const el = component.getByRole("img");
+    expect(el.getAttribute("aria-label")).toBe("3.5 out of 5 stars");
+  });
+
+  it("should render 5 star icons", () => {
+    const el = component.getByRole("img");
+    const svgs = el.querySelectorAll("svg");
+    expect(svgs.length).toBe(5);
+  });
+});

packages/evo-marko/src/tags/evo-star-rating/test/test.server.ts

@@ -0,0 +1,16 @@
+import { describe, it } from "vitest";
+import { composeStories } from "@storybook/marko";
+import { snapshotHTML } from "../../../common/test-utils/snapshots";
+import * as stories from "../star-rating.stories";
+
+const { Default, AllValues } = composeStories(stories);
+
+describe("evo-star-rating SSR", () => {
+  it("renders default", async () => {
+    await snapshotHTML(Default);
+  });
+
+  it("renders all values", async () => {
+    await snapshotHTML(AllValues);
+  });
+});