@y-media/ring-builder

Reusable Ring Builder widget package with adapters for Magento PWA Studio. The package ships three public submodules:

• RingBuilderWidget
• ...

Quick Start

yarn add @y-media/ring-builder

import { RingBuilderWidget } from "@y-media/ring-builder";

export function ProductPage() {
  return (
    <RingBuilderWidget
      ringBuilderUrl="https://erb.example.com"
      ringBuilderAssetsUrl="https://erb.example.com/assets"
      apiEndpoint="https://api-ringbuilderapp.example.com"
      baseUrl="/ring-builder"
      defaultConfigurationId="XXXXX"
      onReady={() => {
        console.log("Ring Builder is ready");
      }}
      onError={(error) => {
        console.error("Ring Builder error", error);
      }}
      onAddToCart={() => {
        console.log("Ring Builder add to cart");
      }}
      onExitHandler={() => {
        console.log("Ring Builder exit handler");
      }}
    />
  );
}

Props reference

| Prop | Type | Required | Description | | ------------------------ | -------------------------- | -------- | ------------------------------------------------------------------------ | | ringBuilderUrl | string | Yes | Public Ring Builder entry point. | | ringBuilderAssetsUrl | string | No | Override assets origin for embedded.js and CSS. | | apiEndpoint | string | Yes | REST or GraphQL endpoint used by the widget. | | baseUrl | string | Yes | Storefront base URL passed to the widget bootstrapper. | | defaultConfigurationId | string | No | Configuration SKU to preselect on first load. | | containerId | string | No | DOM id for the injected container (ring-builder-container by default). | | onReady | () => void | No | Fired after a successful mount in the browser. | | onError | (error: unknown) => void | No | Fired when embedded.js fails to load or export mount. | | onAddToCart | (data: unknown) => void | No | Fired when the user adds a product to the cart. | | onExitHandler | () => void | No | Fired when the user exits the widget. | | themeConfig | object | No | Theme configuration for the widget. |

SSR-safe rendering is handled internally; the widget only loads in the browser. Repeated mounts reuse the same script asset and call unmount when exposed by the widget runtime.

Theme Configuration Properties

| Property | Type | Description | | --------------------------------------- | -------------------- | ------------------------------------------------------------------------- | | primaryColor | string | Primary brand color used throughout the widget for accents and highlights | | primaryTextColor | string | Primary text color used throughout the widget | | stickyTopPosition.desktop | string | Top offset for sticky positioning on desktop viewports (e.g., '100px') | | stickyTopPosition.mobile | string | Top offset for sticky positioning on mobile viewports (e.g., '80px') | | fonts.heading | string | Font family name for headings | | fonts.body | string | Font family name for body text | | fonts.families | string[] | Google Fonts families with weights (e.g., ['Roboto:400,700']) | | fonts.url | string \| string[] | Custom font stylesheet URL(s) from Google Fonts, Adobe Fonts, etc. | | buttons.primary.* | object | Styling for primary buttons | | buttons.secondary.* | object | Styling for secondary buttons | | buttons.outlined.* | object | Styling for outlined buttons | | buttons.ghost.* | object | Styling for ghost buttons | | buttons.*.bgColor | string | Button background color | | buttons.*.textColor | string | Button text color | | buttons.*.hoverColor | string | Button background color on hover | | buttons.*.borderColor | string | Button border color | | buttons.*.roundSize | string | Button border radius (e.g., '4px') | | productCards.borderColor | string | Border color for product cards | | productCards.borderRoundSize | string | Border radius for product cards | | filtersAndOptions.roundSize | string | Border radius for filter and option elements | | filtersAndOptions.borderColor | string | Border color for filter and option elements | | filtersAndOptions.selectedBorderColor | string | Border color for selected filter and option elements | | panels.bgColor | string | Background color for panels | | panels.roundSize | string | Border radius for panels | | panels.borderColor | string | Border color for panels |

Magento PWA Studio usage (WIP)

Install the package inside your Venia project and wire the intercept target:

{
  "pwa-studio": {
    "targets": {
      "intercept": "./node_modules/@y-media/ring-builder/dist/magento-pwa-plugin/intercept.js"
    }
  }
}

Add the plugin to local-intercept.js if you prefer local overrides:

module.exports = (targets) => {
  const {
    intercept,
  } = require("@y-media/ring-builder/dist/magento-pwa-plugin/intercept.cjs");
  intercept(targets);
};

After running yarn build or yarn watch, Venia registers /ring-builder routed to the bundled Route component which renders RingBuilderWidgetMagento.

Magento adapter (WIP)

The adapter performs a single ringBuilderConfig GraphQL query and pipes values into the base widget. Extend the GraphQL document (src/magento-pwa-adapter/query.graphql) if your storefront exposes additional fields.

import { RingBuilderWidgetMagento } from "@y-media/ring-builder/magento-pwa-adapter";

export default function RingBuilderPage() {
  return <RingBuilderWidgetMagento />;
}

Override the loading or error experience by wrapping the component and inspecting the Apollo state (useQuery options are public in the source).