# Web Components Introduction

## General Information

HOOPS Visualize Web includes a customizable user interface that you can use in your application. The framework is based on Web Components and is currently in a beta state. Web Components are a suite of technologies that allow developers to create custom HTML elements with encapsulated functionality, which enhance modularity and reusability in web development. Each component encapsulates a piece of functionality based on HOOPS Visualize Web.

Three key innovations are introduced: a new demo app, a comprehensive library of Web Components, and a UI-kit with the most common elements.

Web Components offer a modular and reusable approach to building web interfaces, enhancing both development efficiency and the user experience. This aims to satisfy users discovering our technology with ready-to-use modules, as well as web developers who wish to slightly modify the interface or fully control every detail and integrate it into their existing projects.

By adopting these modern standards, we ensure that our user interface remains flexible, scalable, and easier to maintain, ultimately providing a more robust and user-friendly experience for all stakeholders.

For more information on Web Components, please refer to the Mozilla documentation here.

Our Web Components reference page can be found here.

## Introduction

### Demo App

The user interface based on Web Components is demonstrated in our Web Viewer demo app, providing a practical example of how the new components can be utilized. The Web Viewer is built using React but can be easily modified to accept various frameworks. It reproduces the features of the previous UI with additional features such as a layout, a top menu with new interactivity, new dropdown menus, custom buttons, and icons.

Web Viewer with example model:

Requirements:

The Demo app is using import maps. Import maps are supported in the following browser versions and above:

Browser | Minimum supported version
--- | ---
Chrome | 89
Edge | 89
Firefox | 108
Opera | 76

Each of the components listed below is available as an HTML element. More information can be found in our API reference.

#### Viewer Components and Utilities:

- <hoops-web-viewer>: Encapsulated HoopsWebViewer object within an HTML tag. It provides a seamless way to integrate the Viewer into your web application.
- <hoops-model-tree>: Displays the assembly tree structure. Can be bound to the Viewer for selection events and visibility management, enhancing interaction with the model hierarchy.
- <hoops-layer-tree>: Displays the layers from the assembly tree with associated nodes. Can be bound to the Viewer for selection events and visibility management, allowing for detailed layer control.
- <hoops-view-tree>: Displays the views from the assembly tree with associated nodes. Can be bound to the Viewer for selection events and visibility management, facilitating view management.
- <hoops-web-viewer-context-manager>: A state manager for shared behavior between components. It is necessary for managing the state of toolbar buttons and other shared functionalities.
- <hoops-service-registry>: Manages service instances and their lifecycles within the viewer. It is necessary for establishing links between components and the Viewer.
- <hoops-cad-configuration-list>: Displays the CAD Configuration list. Can be bound to the Viewer for selection events and visibility management, enhancing interaction with the model configurations.
- <hoops-context-menu>: Provides a customizable context menu that can be triggered on right-click within the viewer. It supports actions like isolate, hide, and show properties.
- <hoops-ifc-relationship>: Displays IFC-specific relationships between elements, such as spatial or property set associations. Useful for navigating and understanding BIM data structures.
- <hoops-types-tree>: Displays a categorized list of types present in the model. Can be bound to the Viewer for filtering, selection, and visibility control based on object types.
- <hoops-tools-panel>: Hosts measurement tools, redline markup, and selection modes for model interaction.
- <hoops-tools-select-group>: Selection section of the tools panel.
- <hoops-tools-measurement-group>: Measurement section of the tools panel.
- <hoops-tools-redline-group>: Redline markup section of the tools panel.
- <hoops-tools-markup-group>: Markup section of the tools panel.
- <hoops-settings-panel>: Manages viewer settings across three areas — Graphics (rendering), Controls (navigation, selection), and Interface (UI preferences).
- <hoops-toolbar-camera-operator>: A standalone dropdown to enable different camera operators.
- <hoops-toolbar-camera>: A standalone dropdown to control the camera view (projection and builtin views).
- <hoops-toolbar-drawmode>: A standalone dropdown to change the draw mode of the viewer.
- <hoops-toolbar-explode>: A standalone dropdown with a slider to control the explode factor.
- <hoops-toolbar-home>: A simple button that will reset the viewer to its initial state on click.
- <hoops-toolbar-layers>: A simple button to toggle the layers view, logic needs to be implemented at application level.
- <hoops-toolbar-model-tree>: A simple button to toggle the model tree, logic needs to be implemented at application level.
- <hoops-toolbar-properties>: A simple button to show the properties panel, logic needs to be implemented at application level.
- <hoops-toolbar-snapshot>: A simple button to trigger a snapshot, logic needs to be implemented at application level.
- <hoops-toolbar-views>: A simple button to toggle the views panel, logic needs to be implemented at application level.
- <hoops-info-button>: A simple button to toggle an information panel, logic needs to be implemented at application level.
- <hoops-toolbar-cad-configuration>: A simple button to toggle a cad configuration panel, logic needs to be implemented at application level.
- <hoops-toolbar-redlines>: A simple button to toggle a redlines panel, logic needs to be implemented at application level.
- <hoops-toolbar-tools>: A simple button to toggle a tools panel, logic needs to be implemented at application level.
- <hoops-toolbar-settings>: A simple button to toggle a settings panel, logic needs to be implemented at application level.
- <hoops-toolbar-types>: A simple button to toggle a generic types panel, logic needs to be implemented at application level.

#### Services

The web-viewer-components library provides several services that are initialized and registered within the `<hoops-service-registry>` component. These services allow you to interact with various aspects of the viewer and its functionality. They use the built-in HTML event system to communicate changes and actions, allowing HTML components that use them to react and update their internal states accordingly.

Services can be accessed using various helper functions provided in the library:

- tryGetService<T extends IService>(serviceName: ServiceName): T | undefined: Attempts to retrieve a service by its name. Returns the service instance if found, or undefined if not found.
- getService<T extends IService>(serviceName: ServiceName): T: Retrieves a service by its name. Throws an error if the service is not found.
- getAllServices(): ServiceRegistry: Retrieves all registered services.

Built-in services are provided for common interactions with the viewer:

- CameraService: ICameraService
- CuttingService: ICuttingService
- ExplodeService: IExplodeService
- FloorplanService: IFloorplanService
- IFCRelationshipsService: IIFCRelationshipsService
- MeasurementService: IMeasurementService
- NoteTextService: INoteTextService
- PmiService: IPmiService
- RedlineService: IRedlineService
- RenderOptionsService: IRenderOptionsService
- SelectionService: ISelectionService
- SheetService: ISheetService
- SpaceMouseService: ISpaceMouseService
- ViewService: IViewService
- WalkOperatorService: IWalkOperatorService

It’s also possible to create and manage services by implementing the `IService` interface and registering them using the following helper functions:

- registerService(service: IService): void: Registers a custom service instance.
- unregisterService(serviceName: ServiceName): void: Unregisters a custom service instance.
- clearServices(): void: Clears all registered services.

If a service can be reset to its default state, it should implement the `IResettableConfigurationService` interface, which includes the following method:

``typescript resetConfiguration(obj?: object): Promise<void>; ``

The `obj` parameter allows passing an optional configuration object to customize the default values to reset to.

### UI-kit

A modest yet essential UI-kit has been created to support the development of the Web Components library and the demo app. This kit includes the necessary elements to ensure a cohesive and functional user interface. It provides simple UI widgets, as well as a layout with menus and panels for containers, and a tree generic enough for all components to use. More information can be found in our API reference.

The HOOPS layout

#### UI Components and Utilities:

- <hoops-layout>: A comprehensive layout manager featuring top, down, right, and left panels, toolbars, a menu bar, a status bar, and a central widget. It provides a structured and organized interface for your application.
- <hoops-button>: A customizable button component that includes text. It can be used to trigger actions or navigate within your application.
- <hoops-dropdown>: A dropdown menu component that allows users to select from a list of options. It enhances the interactivity and usability of your application.
- <hoops-icon>: A web component that stores and manages all the icons used in your application. It ensures consistency and easy access to icons.
- <hoops-icon-button>: A button component that includes an icon and text. It combines visual appeal with functionality, making it easy for users to understand its purpose.
- <hoops-list>: This class implements a list view as an HTML custom element. You can integrate it into your application using the hoops-list tag. It provides a structured way to display a list of items.
- <hoops-node-properties>: A panel designed to display properties in a key-value format. It is useful for showing detailed information about selected items in your application.
- <hoops-toolbar>: A basic vertical toolbar that allows you to stack buttons. It provides a convenient way to group and organize tools and actions.
- <hoops-tree>: This class implements a tree view as an HTML custom element. You can integrate it into your application using the hoops-tree tag. It is ideal for displaying hierarchical data.
- <hoops-separator>: A separator component used in toolbars to visually divide groups of buttons or tools. It helps in organizing the toolbar layout.
- <hoops-accordion>: A custom web component that implements an accessible accordion using LitElement.
- <hoops-switch>: An input widget that allows users to choose one of two values: on or off.

#### CSS variables

To ensure a consistent and customizable design, our library includes a set of CSS variables. These variables allow you to adjust the appearance of various components to match your application’s style or needs. The variables are defined in themes.css.

- hoops-accent-foreground: Color used for accent elements in the foreground.
- hoops-accent-foreground-active: Color for active accent elements in the foreground.
- hoops-accent-foreground-disabled: Color for disabled accent elements in the foreground.
- hoops-accent-foreground-hover: Color for accent elements in the foreground when hovered.
- hoops-background: Base background color for the application.
- hoops-body-font: Font used for the main body text.
- hoops-foreground: Primary color for foreground elements.
- hoops-foreground-subtle: Subtle color for less prominent foreground elements.
- hoops-sm-icon-button-content-size: Size of the content within small icon buttons.
- hoops-sm-icon-button-size: Overall size of small icon buttons.
- hoops-md-icon-button-content-size: Size of the content within medium icon buttons.
- hoops-md-icon-button-size: Overall size of medium icon buttons.
- hoops-xl-icon-button-content-size: Size of the content within extra-large icon buttons.
- hoops-xl-icon-button-size: Overall size of extra-large icon buttons.
- hoops-svg-stroke-color: Stroke color used for SVG elements.
- hoops-svg-accent-color: Accent color used for SVG elements.
- hoops-svg-fill-color: Fill color used for SVG elements.
- hoops-neutral-background-20: Slightly darker neutral background color.
- hoops-neutral-background-50: Darker neutral background color.
- hoops-neutral-background-hover: Neutral background color when hovered.
- hoops-neutral-foreground: Neutral color for foreground elements.
- hoops-neutral-foreground-active: Neutral color for active foreground elements.
- hoops-neutral-foreground-rest: Neutral color for resting foreground elements.
- hoops-neutral-border: Neutral color for borders.
- hoops-separator-color: Color used for separators.
- hoops-background-canvas: Background color for the canvas area.
- hoops-dropdown-z-index: Z-index value for dropdown elements.
- hoops-dropdown-background-color: Background color for dropdown elements.
- hoops-dropdown-menu-border-color: Border color for dropdown menu elements.
- hoops-dropdown-menu-radius: Border radius for dropdown menu elements.
- hoops-dropdown-menu-border-size: Border size for dropdown menu elements.
- hoops-dropdown-menu-border-style: Border style for dropdown menu elements.
- hoops-dropdown-gap: Gap size for dropdown elements.
- hoops-layout-width: Width of the layout component.
- hoops-layout-height: Height of the layout component.

#### React integration

While React is not required to use the Web Components, some React libraries are necessary if you are using that framework. To integrate our Web Components libraries into a React environment, HOOPS Visualize Web offers components that encapsulate UI Web Components. These components are available in the following dedicated libraries:

- @ts3d-hoops/web-viewer-components-react
- @ts3d-hoops/ui-kit-react

These libraries are essential for React integration and are utilized in our demo application.

## Using Our Demo App

The demo app requires the following conditions:

Requirements:

- node.js 18.20.7 or newer

To launch the demo, in the folder /quick_start/beta-demo-app/:

    npx http-server -c-1 . -o "/?scs=arboleda.scs"

All required dependencies will be downloaded and installed and a web page will be launched in your default web browser.

## Development environment

Important:

The packages are now available through npm registry! You can install them directly using npm. The local installation method from customer packages is still supported for existing workflows.

To get started developing, you can now choose between two installation methods:

Option A: Direct npm installation

- Run `npm install @ts3d-hoops/web-viewer-components`

Option B: Local installation from customer package

- copy <INSTALL_DIR>/web_viewer/@ts3d-hoops to your /dependencies folder from your application project
- Run `npm install ./dependencies/@ts3d-hoops/web-viewer-components` from a command prompt in your project directory

In /web_viewer/@ts3d-hoops/beta-demo-app-src, following commands to manage the project:

Important:

yarn usage is temporary, npm will be the final tool.

    yarn install
    yarn dev

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your Docs generative AI assistant. Ask me anything about HOOPS Visualize Web or choose a sample question below to start a conversation:

What is HOOPS Visualize Web?
What are the latest release notes for HOOPS Visualize Web?
How do I start evaluating HOOPS Visualize Web?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...