feat(star-rating): new component (#12102)

### Related Ticket(s)

[JIRA](https://jsw.ibm.com/browse/ADCMS-6667)

### Description

Migrates the`star-rating` component from `carbon-for-aem` into `carbon-for-ibmdotcom`.

### Changelog

**New**

- adds new `c4d-star-rating` component


<!-- React and Web Component deploy previews are enabled by default. -->
<!-- To enable additional available deploy previews, apply the following -->
<!-- labels for the corresponding package: -->
<!-- *** "test: e2e": Codesandbox examples and e2e integration tests -->
<!-- *** "package: services": Services -->
<!-- *** "package: utilities": Utilities -->
<!-- *** "RTL": React / Web Components (RTL) -->
<!-- *** "feature flag": React / Web Components (experimental) -->

packages/web-components/examples/stackblitz/components/dotcom-shell/src/index.scss

@@ -16,9 +16,9 @@ $feature-flags: (
 @import 'carbon-components/scss/globals/grid/grid';
 @import 'carbon-components/scss/components/ui-shell/content';
 
-@media (min-width: 66rem) {
+@media (width >= 66rem) {
   .cds--offset-lg-3 {
-    margin-left: 0;
+    margin-inline-start: 0;
   }
 }
 
@@ -27,7 +27,7 @@ $feature-flags: (
     margin: 30px 0;
 
     &:first-of-type {
-      margin-top: 0;
+      margin-block-start: 0;
     }
   }
 }

packages/web-components/examples/stackblitz/components/masthead-l1/src/index.scss

@@ -17,12 +17,13 @@ $feature-flags: (
 @import 'carbon-components/scss/components/ui-shell/content';
 
 body {
-  padding: calc(#{$spacing-09} + #{mini-units(6)} + 1px) $spacing-09 $spacing-09 $spacing-09;
+  padding: calc(#{$spacing-09} + #{mini-units(6)} + 1px) $spacing-09 $spacing-09
+    $spacing-09;
 }
 
-@media (min-width: 66rem) {
+@media (width >= 66rem) {
   .cds--offset-lg-3 {
-    margin-left: 0;
+    margin-inline-start: 0;
   }
 }
 
@@ -31,7 +32,7 @@ body {
     margin: 30px 0;
 
     &:first-of-type {
-      margin-top: 0;
+      margin-block-start: 0;
     }
   }
 }

packages/web-components/examples/stackblitz/components/masthead/src/index.scss

@@ -17,20 +17,22 @@ $feature-flags: (
 @import 'carbon-components/scss/components/ui-shell/content';
 
 body {
-  padding: calc(#{$spacing-09} + #{mini-units(6)} + 1px) $spacing-09 $spacing-09 $spacing-09;
+  padding: calc(#{$spacing-09} + #{mini-units(6)} + 1px) $spacing-09 $spacing-09
+    $spacing-09;
 }
 
 .cds--content.dds-ce-demo--ui-shell-content {
-  @media (min-width: 66rem) {
+  @media (width >= 66rem) {
     .cds--offset-lg-3 {
-      margin-left: 0;
+      margin-inline-start: 0;
     }
   }
+
   h2 {
     margin: 30px 0;
 
     &:first-of-type {
-      margin-top: 0;
+      margin-block-start: 0;
     }
   }
 }

packages/web-components/examples/stackblitz/components/table-of-contents/src/index.scss

@@ -21,6 +21,5 @@ body {
 }
 
 h3 {
-  padding-top: $spacing-05;
-  padding-bottom: $spacing-07;
+  padding-block: $spacing-05 $spacing-07;
 }

packages/web-components/examples/stackblitz/components/tabs-extended/src/styles.scss

@@ -11,6 +11,7 @@
 
 :root {
   @include theme.theme(themes.$white);
+
   background-color: var(--cds-background);
   color: var(--cds-text-primary);
 }

packages/web-components/examples/stackblitz/usage/webpack-handlebars/src/index.scss

@@ -16,16 +16,16 @@
 @include carbon--font-face-sans();
 
 body {
-  visibility: inherit; // Initially hidden to avoid FOUC
   padding: calc(#{mini-units(6)} + 1px) 0 0 0;
+  visibility: inherit; // Initially hidden to avoid FOUC
 }
 
 .bx--content.cds-ce-demo--ui-shell-content {
   h2 {
     margin: 30px 0;
 
     &:first-of-type {
-      margin-top: 0;
+      margin-block-start: 0;
     }
   }
 }

packages/web-components/examples/stackblitz/usage/webpack-sass/src/index.scss

@@ -30,12 +30,12 @@ h2 {
   margin: $spacing-07 0;
 
   &:first-of-type {
-    margin-top: 0;
+    margin-block-start: 0;
   }
 }
 
 main {
-  margin: calc(#{mini-units(6)} + 1px) auto 0 auto;
+  max-inline-size: 99rem;
   padding: $spacing-09;
-  max-width: 99rem;
+  margin: calc(#{mini-units(6)} + 1px) auto 0 auto;
 }

packages/web-components/src/components/star-rating/__stories__/README.stories.mdx

@@ -0,0 +1,17 @@
+import { Meta, Props, Story, Canvas, Description } from '@storybook/addon-docs';
+import { cdnJs } from '../../../globals/internal/storybook-cdn';
+import '../index';
+
+<Meta title="Star Rating" />
+
+# Star Rating
+
+<Canvas withToolbar>
+  <Story id="components-star-rating--default" height="100px" />
+</Canvas>
+
+<Description markdown={`${cdnJs({ components: ['star-rating'] })}`} />
+
+## `<c4d-star-rating>` attributes, properties, and events
+
+<Props of="c4d-star-rating" />

packages/web-components/src/components/star-rating/__stories__/star-rating.stories.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2020, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import '../index';
+import readme from './README.stories.mdx';
+import { grid8ColCentered } from '../../../globals/internal/storybook-decorators';
+import { boolean, number, text } from '@storybook/addon-knobs';
+
+export const Default = (args) => {
+  const { disableTooltip, label, labelHref, rating, starCount, tooltipText } =
+    args?.StarRating ?? {};
+  return html`
+    <c4d-star-rating
+      ?disableTooltip="${disableTooltip}"
+      label="${ifDefined(label || undefined)}"
+      label-href="${ifDefined(labelHref || undefined)}"
+      rating="${rating}"
+      star-count="${starCount}"
+      tooltip="${tooltipText}"></c4d-star-rating>
+  `;
+};
+
+export const NoLabel = (args) => {
+  const { disableTooltip, rating, starCount, tooltipText } = (args =
+    args?.StarRating ?? {});
+
+  return html`
+    <c4d-star-rating
+      ?disableTooltip="${disableTooltip}"
+      rating="${rating}"
+      star-count="${starCount}"
+      tooltip="${tooltipText}"></c4d-star-rating>
+  `;
+};
+
+export default {
+  title: 'Components/Star Rating',
+  parameters: {
+    ...readme.parameters,
+    hasStoryPadding: true,
+    knobs: {
+      StarRating: () => {
+        const rating = number('Star Rating', 4.5);
+        const label = text('Label text (optional)', '42 G2 reviews');
+        const labelHref = text('Label link (optional)', '');
+        const starCount = number('Max number of stars (optional)', 5);
+        const tooltipText = text('Tooltip text (optional)', '');
+        const disableTooltip = boolean('Disable tooltip (optional)', false);
+        return {
+          rating,
+          label,
+          labelHref,
+          starCount,
+          tooltipText,
+          disableTooltip,
+        };
+      },
+    },
+  },
+  decorators: [
+    (story) => grid8ColCentered(story),
+    (story) => html` <div style="margin-block-start: 2rem;">${story()}</div> `,
+  ],
+};

packages/web-components/src/components/star-rating/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ *
+ * Copyright IBM Corp. 2020, 2024
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import './star-rating';

packages/web-components/src/components/star-rating/star-rating.scss

@@ -0,0 +1,76 @@
+//
+// Copyright IBM Corp. 2024
+//
+// This source code is licensed under the Apache-2.0 license found in the
+// LICENSE file in the root directory of this source tree.
+//
+
+@use '@carbon/styles/scss/config' as *;
+@use '@carbon/styles/scss/spacing' as *;
+@use '@carbon/styles/scss/type' as *;
+@use '@carbon/styles/scss/themes' as *;
+@use '@carbon/styles/scss/theme' as *;
+@use '@carbon/styles/scss/utilities/tooltip' as *;
+@use '@carbon/styles/scss/components/button/tokens' as *;
+@use '@carbon/ibmdotcom-styles/scss/globals/vars' as *;
+
+:host(#{$c4d-prefix}-star-rating) {
+  display: inline-block;
+
+  .#{$prefix}-star-rating {
+    display: flex;
+    flex-wrap: wrap;
+    gap: $spacing-03 $spacing-05;
+  }
+
+  .#{$prefix}-star-rating__stars {
+    display: inline-flex;
+    align-items: center;
+    margin: 0;
+
+    &:not([disableTooltip]) {
+      @include tooltip--trigger('definition', top);
+      @include tooltip--placement('definition', 'top', 'center');
+    }
+  }
+
+  .#{$prefix}-star-count__star {
+    svg {
+      display: block;
+      fill: $button-primary;
+    }
+  }
+
+  .#{$prefix}-star-count__star--half {
+    position: relative;
+
+    svg {
+      position: absolute;
+      inset: 0;
+    }
+
+    svg:nth-of-type(1) {
+      position: initial;
+    }
+
+    svg:nth-of-type(2):dir(rtl) {
+      transform: scaleX(-1);
+    }
+  }
+
+  .#{$prefix}-star-rating__label,
+  .#{$prefix}-star-rating__label a {
+    @include type-style('body-compact-02');
+
+    color: $border-inverse;
+  }
+
+  .#{$prefix}-star-rating__label a {
+    text-decoration: none;
+
+    &:hover,
+    &:focus {
+      text-decoration: underline;
+    }
+  }
+}