# epigraph-ar

Epigraph's custom web component for AR based on Google's `<model-viewer>`.
As such, it mostly follows their coding conventions except for public APIs.
For more information, @see https://github.com/google/model-viewer/wiki/Code-conventions

## Examples

<caption>Quick Start with the latest stable version</caption>

```html
<!-- include this in your `<head>` -->
<script async type="module" src='https://unpkg.com/%40epigraph/ar/dist/epigraph-ar.min.js'></script>
```

<caption>Quick Start with a Specific Version</caption>

```html
<!-- include this in your `<head>`, replace version-number with a specified version -->
<script async type="module" src='https://unpkg.com/%40epigraph/ar%40{version-number}/dist/epigraph-ar.min.js'></script>
```

<caption>epigraph-ar as an AR button</caption>

```html
<epigraph-ar sku="some-valid-sku" ua-code="some-valid-ua-code" ar-modes="scene-viewer quick-look"></epigraph-ar>
```

<caption>epigraph-ar as a standalone 3D viewer</caption>

```html
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" button-mode="none"></epigraph-ar>
```

<caption>epigraph-ar as a standalone 3D viewer with material variant selector</caption>

```html
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" button-mode="none" material-variant-selector-visible></epigraph-ar>
```

<caption>epigraph-ar as a standalone 3D viewer with material variant selector and AR</caption>

```html
<!-- NOTE: only supported on Android Devices compatible with WebXR -->
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" ar-modes="webxr scene-viewer quick-look" material-variant-selector-visible></epigraph-ar>
```

<caption>epigraph-ar as a standalone 3D viewer with product tour</caption>

```html
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" button-mode="none" product-tour-visible></epigraph-ar>
```

<caption>epigraph-ar with product tour and AR</caption>

```html
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" product-tour-visible></epigraph-ar>
```

<caption>Using a slot</caption>

```html
<epigraph-ar>
<element slot="slot-name"></element>
<epigraph-ar>
```

<caption>Using a CSS Shadow Part</caption>

```css
epigraph-ar::part(part-name) {
some-rule: some-value;
}
```

<caption>Using a CSS Custom Property</caption>

```css
epigraph-ar {
--some-css-property: some-new-value;
}
```

<caption>Listening to Events</caption>

```JavaScript
const epigraphAR = document.querySelector('epigraph-ar');

epigraphAR.addEventListener('event-name', () => {
doSomething();
})
```

## Properties

| Property                         | Attribute                           | Modifiers | Type      | Default                   | Description                                      |
|----------------------------------|-------------------------------------|-----------|-----------|---------------------------|--------------------------------------------------|
| `arButtonModeAttribute`          | `button-mode`                       |           | `string`  | "mobile desktop"          | sets ar button modes for the ar-button, maps to the enumeration<br /><br />empty string - NONE<br /><br />mobile - MOBILE<br /><br />desktop - DESKTOP<br /><br />mobile desktop - BOTH |
| `arButtonRolloverNudge`          | `ar-button-rollover-nudge`          |           | `boolean` | false                     | toggles the ability to show a<br /><br />rollover nudge when the AR/QR button is hovered |
| `arModes`                        | `ar-modes`                          |           | `string`  | "scene-viewer quick-look" | sets ar modes for the ar experience<br /><br />webxr/scene-viewer - android<br /><br />quick-look - iOS |
| `arPlacement`                    | `ar-placement`                      |           | `string`  | "floor"                   | sets ar placement for the ar experience<br /><br />floor - place ar object on the floor<br /><br />wall - place ar object on the wall |
| `autoStart`                      | `auto-start`                        |           | `boolean` | false                     | used to load the 3D viewer automatically on desktop |
| `cameraOrbit`                    | `camera-orbit`                      |           | `string`  | "-30deg auto auto"        | sets the viewer camera orbit values              |
| `canActivateAR`                  |                                     | readonly  |           |                           | public method to get ar-capability status        |
| `environmentImage`               | `environment-image`                 |           | `string`  | "neutral"                 | sets environmental lighting<br /><br />empty string - default scene optimized for load speed<br /><br />neutral - applies even lighting on all sides<br /><br />HDR Image - supply HDR Image source url to this to apply custom lighting |
| `gaEventLabelType`               | `ga-event-label-type`               |           | `string`  | "name"                    | flag to use different values for GA event label<br /><br />name - use product name or hotspot feature name<br /><br />sku - use product sku<br /><br />name and sku - use '{name} - {sku}'<br /><br />sku and name - use '{sku} - {name}' |
| `interactionPromptThreshold`     | `interaction-prompt-threshold`      |           | `number`  | 3000                      | flag to toggle UserWithArSupport/UserWithQrSupport GA event reporting |
| `internalMeasurementsVisible`    | `internal-measurements-visible`     |           | `boolean` | false                     | sets visibility of internal model measurements   |
| `materialVariantSelectorVisible` | `material-variant-selector-visible` |           | `boolean` | false                     | sets visibility of material variant selector     |
| `maxCameraOrbit`                 | `max-camera-orbit`                  |           | `string`  | "auto 100deg auto"        | sets the maximum camera orbit<br /><br />each part of the string represents the following in order: roll(theta) yaw(phi) radius<br /><br />this uses Euler angles @see https://en.wikipedia.org/wiki/Euler_angles#Proper_Euler_angles_2 for more information |
| `measurementUnit`                | `measurement-unit`                  |           | `string`  | "imperial"                | sets which measurement system to use for internal measurements<br /><br />imperial - uses the imperial system<br /><br />metric - uses the metric system |
| `minCameraOrbit`                 | `min-camera-orbit`                  |           | `string`  | "auto 0deg auto"          | sets the minimum camera orbit<br /><br />each part of the string represents the following in order: roll(theta) yaw(phi) radius<br /><br />this uses Euler angles @see https://en.wikipedia.org/wiki/Euler_angles#Proper_Euler_angles_2 for more information |
| `name`                           |                                     |           | `string`  | "EPIGRAPH-AR"             | name to be used for the internal logging service |
| `posterBackground`               | `poster`                            |           | `string`  | ""                        | sets the source url for the poster background    |
| `posterForeground`               | `poster-foreground`                 |           | `string`  | ""                        | sets the source url for the icon to display on top of the poster |
| `productTourVisible`             | `product-tour-visible`              |           | `boolean` | false                     | sets visibility of product tour                  |
| `shadowIntensity`                | `shadow-intensity`                  |           | `number`  | 1                         | modifies the shadow intensity of the model       |
| `sku`                            | `sku`                               |           | `string`  | ""                        | to be used with epigraph product skus            |
| `theme`                          | `theme`                             |           | `string`  | "default"                 | used to indicate UI/UX themes                    |
| `uaCode`                         | `ua-code`                           |           | `string`  | ""                        | to be used with client ua-code                   |
| `verboseLogging`                 | `verbose-logging`                   |           | `boolean` | false                     | used to log debugging information                |
| `viewerMaximizable`              | `viewer-maximizable`                |           | `boolean` | false                     | sets ability to maximize the 3D viewer on mobile |
| `viewerVisible`                  | `viewer-visible`                    |           | `boolean` | false                     | sets visibility of the 3D viewer<br />TODO: set a method call to toggle this property based on response from mediator |

## Methods

| Method          | Type       | Description                            |
|-----------------|------------|----------------------------------------|
| `dismissPoster` | `(): void` | public method to dismiss viewer poster |
| `showPoster`    | `(): void` | public method to show viewer poster    |

## Events

| Event                               | Type                                   | Description                                      |
|-------------------------------------|----------------------------------------|--------------------------------------------------|
| `epigraph-ar-capability-determined` | `CustomEvent<{ canActivateAr: any; }>` | custom event to indicate whether the device is AR capable |
| `epigraph-experience-type`          | `CustomEvent<ExperienceDetails>`       | custom event to detail what experience is currently being rendered |
| `epigraph-invalid-product`          |                                        | custom event to indicate product associated with the sku is invalid |
| `epigraph-valid-product`            |                                        | custom event to indicate product associated with the sku is valid |

## Slots

| Name                         | Description                                      |
|------------------------------|--------------------------------------------------|
| `ar-button`                  | replaces the ar-button but maintains the onclick function |
| `ar-button-rollover-nudge`   | replaces the rollover nudge that appears onhover, if enabled |
| `mobile-product-tour-button` | replaces the mobile product tour launch button   |
| `poster`                     | replaces the viewer poster                       |
| `progress-bar`               | replaces the progress indicator                  |
| `qr-modal-close`             | replaces the qr-modal close button               |
| `qr-modal-done`              | replaces the qr-modal done button                |
| `qr-modal-instruction`       | replaces the qr-modal instruction                |
| `qr-modal-requirement`       | replaces the qr-modal requirement                |
| `qr-modal-title`             | replaces the qr-modal title                      |
| `viewer-modal-exit-button`   | replaces the button that exits the fullscreen viewer |

## CSS Shadow Parts

| Part                                     | Description                                      |
|------------------------------------------|--------------------------------------------------|
| `ar-button-container`                    | points to the ar button container                |
| `ar-button-rollover-nudge`               | points to the rollover nudge that displays on hover |
| `default-ar-button`                      | points to the default ar button                  |
| `default-poster-background`              | points to the default poster background          |
| `default-poster-foreground`              | points to the default poster icon                |
| `hotspot-button`                         | points to the hotspot buttons                    |
| `hotspot-button-annotation`              | points to the hotspot button annotation          |
| `hotspot-button-inner-circle`            | points to the inner circle of the hotspot button |
| `material-variant-selector`              | points to the `<material-variant-selector>` element |
| `material-variant-selector-button`       | points to the selector buttons themselves        |
| `material-variant-selector-container`    | points to the container housing the selectors    |
| `mobile-product-tour-button-default`     | points to the default mobile product tour launch button |
| `model-viewer`                           | points to the `<model-viewer>` element           |
| `poster-foreground`                      | points to the poster icon                        |
| `product-tour`                           | points to the `<product-tour>` element           |
| `product-tour-carousel-media`            | points to the media housed inside media carousels |
| `product-tour-close-container`           | points to the side panel close button container  |
| `product-tour-close-default`             | points to the side panel default close button    |
| `product-tour-container`                 | points to the side panel container               |
| `product-tour-feature-content-container` | points to the side panel feature content containers |
| `product-tour-feature-description`       | points to the description of the feature text    |
| `product-tour-feature-media-container`   | points to the containers housing feature media   |
| `product-tour-feature-text-container`    | points to the container housing the feature text |
| `product-tour-feature-title`             | points to the title of the feature text          |
| `product-tour-inner-content-container`   | points to the side panel inner content container |
| `product-tour-media-carousel`            | points to the feature media carousels            |
| `product-tour-media-carousel-dot`        | points to the control buttons for the media carousels |
| `product-tour-media-controls-container`  | points to the containers housing the control buttons for the media carousels |
| `product-tour-media-title`               | points to the feature media titles               |
| `qr-modal`                               | points to the `<qr-modal>` element               |
| `qr-modal-background`                    | points to the modal background                   |
| `qr-modal-close-default`                 | points to the default close button in the qr-modal |
| `qr-modal-container`                     | points to the main modal                         |
| `qr-modal-done-default`                  | points to the default done button in the qr-modal |
| `qr-modal-instruction-default`           | points to the default instruction in the qr-modal |
| `qr-modal-qr-container`                  | points to the qr container within the qr-modal   |
| `qr-modal-qr-image`                      | points to the qr image in the modal              |
| `qr-modal-requirement-default`           | points to the default requirement in the qr-modal |
| `qr-modal-title-default`                 | points to the default title in the qr-modal      |
| `viewer-modal-exit-button`               | points to the button that exits the fullscreen viewer on mobile |
| `webxr-banner`                           | points to the webxr banner                       |
| `webxr-banner-name`                      | points to the product name in the text portion   |
| `webxr-banner-pdp`                       | points to the the url text below the name in the text portion |
| `webxr-banner-text`                      | points to the text portion of the webxr banner   |
| `webxr-banner-visit-button`              | points to the visit button in the banner         |

## CSS Custom Properties

| Property                                         | Description                                      |
|--------------------------------------------------|--------------------------------------------------|
| `--ar-button-active-background-color`            | edits ar-button background color when clicked    |
| `--ar-button-background-color`                   | edits ar-button background color                 |
| `--ar-button-border-color`                       | edits ar-button border color                     |
| `--ar-button-hover-background-color`             | edits ar-button background color when hovered    |
| `--ar-button-hover-text-color`                   | edits ar-button text color when hovered          |
| `--ar-button-text-color`                         | edits ar-button text color                       |
| `--ar-icon-frame-color`                          | edits ar-icon frame color                        |
| `--ar-icon-hover-frame-color`                    | edits ar-icon frame color when hovered           |
| `--ar-icon-hover-vector-1-color`                 | edits ar-icon vector 1 color when hovered        |
| `--ar-icon-hover-vector-2-color`                 | edits ar-icon vector 2 color when hovered        |
| `--ar-icon-hover-vector-3-color`                 | edits ar-icon vector 3 color when hovered        |
| `--ar-icon-vector-1-color`                       | edits ar-icon vector 1 (top face) color          |
| `--ar-icon-vector-2-color`                       | edits ar-icon vector 2 (left face) color         |
| `--ar-icon-vector-3-color`                       | edits ar-icon vector 3 (right face) color        |
| `--hotspot-button-background-color`              | edits hotspot button background color            |
| `--hotspot-button-border-color`                  | edits hotspot button border color                |
| `--hotspot-button-focus-border-color`            | edits hotspot button border color when focused   |
| `--hotspot-inner-circle-border-color`            | edits hotspot button inner circle border color   |
| `--hotspot-inner-circle-viewed-border-color`     | edits hotspot button inner circle border color when viewed |
| `--mobile-product-tour-button-background-color`  | edits product-tour mobile button background color |
| `--mobile-product-tour-button-text-color`        | edits product-tour mobile button text color      |
| `--product-tour-background-color`                | edits product-tour background color              |
| `--product-tour-close-button-fill-color`         | edits product-tour close button fill color       |
| `--product-tour-close-button-hover-fill-color`   | edits product-tour close button fill color when hovered |
| `--product-tour-close-button-hover-stroke-color` | edits product-tour close-button stroke color when hovered |
| `--product-tour-close-button-stroke-color`       | edits product-tour close-button stroke color     |
| `--product-tour-current-dot-background-color`    | edits product-tour control dot background color when it points to a current image |
| `--product-tour-dot-background-color`            | edits product-tour control dot background color  |
| `--product-tour-mobile-close-button-outline-color` | edits product-tour mobile close button outline color |
| `--product-tour-mobile-close-button-stroke-color` | edits product-tour mobile close button stroke color |
| `--progress-ring-color`                          | edits the progress ring color                    |
| `--progress-ring-radius`                         | edits the progress ring radius                   |
| `--progress-ring-thickness`                      | edits the progress ring thickness                |
| `--qr-modal-close-button-stroke-color`           | edits qr-modal close button stroke color         |
| `--qr-modal-done-button-active-background-color` | edits qr-modal done button background color when clicked |
| `--qr-modal-done-button-background-color`        | edits qr-modal done button background color      |
| `--qr-modal-done-button-border-color`            | edits qr-modal done button border color          |
| `--qr-modal-done-button-hover-background-color`  | edits qr-modal done button background color when hovered |
| `--qr-modal-done-button-hover-text-color`        | edits qr-modal done button text color when hovered |
| `--qr-modal-done-button-text-color`              | edits qr-modal done button text color            |
| `--qr-modal-instruction-color`                   | edits qr-modal instruction text color            |
| `--qr-modal-requirement-color`                   | edits qr-modal requirement text color            |
| `--qr-modal-title-color`                         | edits qr-modal title text color                  |
