@trimble-oss/moduswebcomponents-mcp 1.0.0

package/versions/1.0.7/docs/angular.mdx

@@ -0,0 +1,374 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Frameworks/Angular" />
+
+# Angular Framework Integration
+
+This guide will help you get started with consuming the Modus Angular Web Component library in your Angular project.
+
+We highly recommend using the Modus Angular Components library for Angular based projects.
+These components are automatically generated using the Stencil Angular Framework Integration.
+
+Follow the steps outlined below to integrate and use Modus Angular Web Components effectively.
+
+Please refer to the [official stencil documentation](https://stenciljs.com/docs/angular#consumer-usage) for more information on how to integrate with your Angular project.
+
+## Angular with modules
+
+Modus Angular Components have a peer dependency with Modus Web Components and require the
+installation of both packages.
+
+### 1. Install both `modus-wc` and `modus-wc-angular` dependencies:
+
+Ensure that you specify the target version of Angular for the `modus-wc-angular` package (e.g., `ng18` for Angular 18).
+
+<b>
+  Lock the installed package versions to avoid unintended breakages on future
+  npm installs.
+</b>
+
+```bash
+npm install @trimble-oss/moduswebcomponents @trimble-oss/moduswebcomponents-angular@<latest-version>-ng<target-version>
+```
+
+### 2. Set up the styling:
+
+You will need to import our styling in your main JavaScript or CSS file:
+
+```js
+import '@trimble-oss/moduswebcomponents/modus-wc-styles.css';
+```
+
+### 3. Configure asset copying in `angular.json`:
+
+For components that use static assets (like `modus-wc-logo`), you need to configure Angular to copy the assets to your build output.
+
+Add this to your `angular.json` under `projects > your-app > architect > build > options`:
+
+```json
+{
+  "projects": {
+    "your-app": {
+      "architect": {
+        "build": {
+          "options": {
+            "assets": [
+              {
+                "glob": "**/*",
+                "input": "node_modules/@trimble-oss/moduswebcomponents/assets",
+                "output": "/assets"
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### 4. Import Modus Angular Web Components library into your Angular app's module:
+
+```ts
+// app.module.ts
+import { ModusAngularComponentsModule } from '@trimble-oss/moduswebcomponents-angular';
+
+@NgModule({
+  ...
+  imports: [ComponentLibraryModule],
+  ...
+})
+export class AppModule {}
+```
+
+### 4. Use Modus Angular Web Components while leveraging Angular template binding syntax:
+
+```ts
+// app.component.html
+<modus-wc-button label="Click Me" />
+```
+
+## Angular with standalone components
+
+Modus Angular Components have a peer dependency with Modus Web Components and require the
+installation of both packages.
+
+### 1. Install both `modus-wc` and `modus-wc-angular` dependencies:
+
+Ensure that you specify the target version of Angular for the `modus-wc-angular` package (e.g., `ng18` for Angular 18).
+
+<b>
+  Lock the installed package versions to avoid unintended breakages on future
+  npm installs.
+</b>
+
+```bash
+npm install @trimble-oss/moduswebcomponents @trimble-oss/moduswebcomponents-angular@<latest-version>-ng<target-version>
+```
+
+### 2. Set up the styling:
+
+You will need to import our styling in your main JavaScript or CSS file:
+
+```js
+import '@trimble-oss/moduswebcomponents/modus-wc-styles.css';
+```
+
+### 3. Import your component library into your component.
+
+You must distribute your components through a primary `NgModule` to use your components in a standalone component.
+
+```ts
+// app.component.ts
+import { Component } from '@angular/core';
+import { ModusAngularComponentsModule } from '@trimble-oss/moduswebcomponents-angular';
+
+@Component({
+  selector: 'app-root',
+  standalone: true,
+  imports: [ModusAngularComponentsModule],
+  templateUrl: './app.component.html',
+})
+export class AppComponent {}
+```
+
+### 4. Use Modus Angular Web Components while leveraging Angular template binding syntax:
+
+```ts
+// app.component.html
+<modus-wc-button label="Click Me" />
+```
+
+### Custom Elements Schema
+
+In the `app.module.ts` file, you need to tell angular that you are using custom element schemas
+so that it does not throw errors when unknown element names are used in the markup.
+
+Import `CUSTOM_ELEMENTS_SCHEMA` and add it to your `@NgModule`'s schemas:
+
+```ts
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
+
+@NgModule({
+  ...
+  schemas: [CUSTOM_ELEMENTS_SCHEMA]
+  ...
+})
+```
+
+### Wrapping Components
+
+When using Modus Web Components directly, it is recommended to wrap it in corresponding Angular components within your application. This will abstract away from the library dependency, allowing more flexibility for you and your application in the future. Each part of the component is able to be abstracted, leaving you with an Angular-native component.
+
+Notice Angular allows `[]` and `()` markup syntax for the web component's inputs and outputs, respectively.
+
+Wrapped Modus Button Example:
+
+```ts
+import { Component, EventEmitter, Input, Output } from '@angular/core';
+
+@Component({
+  selector: 'button-component',
+  template: `
+    <modus-wc-button
+      [buttonStyle]="buttonStyle"
+      [color]="color"
+      [disabled]="disabled"
+      [size]="size"
+      (buttonClick)="onButtonClick.emit()"
+    >
+      <ng-content></ng-content>
+    </modus-wc-button>
+  `,
+})
+export class ButtonComponent {
+  @Input() buttonStyle: 'borderless' | 'fill' | 'outline' = 'fill';
+  @Input() color: 'danger' | 'default' | 'primary' | 'secondary' | 'warning' =
+    'default';
+  @Input() disabled: boolean;
+  @Input() size: 'small' | 'medium' | 'large' = 'medium';
+
+  @Output() onButtonClick = new EventEmitter();
+}
+```
+
+### Reactive Forms
+
+Working with a web component's inputs/outputs works great but these components do not integrate with Angular's reactive forms quite as easily. Since web components do not know about Angular's form APIs, we must extend form-compatible components' behavior with simple directives. These directives are applied to the web component selectors, giving the components Angular form functionality.
+
+Let's take a look at a directive implementation for a Modus Select's form functionality.
+
+#### Wrapper
+
+You'll notice the `modus-select` in the markup is taking extra inputs, such as `formControl` and `optionsDisplayProp`, these inputs are provided by the directive below. Here is what our wrapper looks like:
+
+```ts
+import { Component, EventEmitter, Input, Output } from '@angular/core';
+import { FormControl } from '@angular/forms';
+
+@Component({
+  selector: 'select-component',
+  template: `
+    <modus-wc-select
+      #select
+      [disabled]="disabled"
+      [errorText]="errorText"
+      [formControl]="formControl"
+      [helperText]="helperText"
+      [label]="label"
+      [options]="options"
+      [optionsDisplayProp]="optionsDisplayProp"
+      [required]="required"
+      [selectValue]="value"
+      [size]="size"
+      [validText]="validText"
+      (valueChange)="onSelectValueChange.emit(select.value)"
+    >
+    </modus-wc-select>
+  `,
+})
+export class SelectComponent {
+  @Input() disabled: boolean;
+  @Input() errorText: string;
+  @Input() formControl: FormControl;
+  @Input() helperText: string;
+  @Input() label: string;
+  @Input() options: unknown[] = [];
+  @Input() optionsDisplayProp: string;
+  @Input() required: boolean;
+  @Input() size: 'medium' | 'large' = 'medium';
+  @Input() validText: string;
+  @Input() value: unknown;
+
+  @Output() onSelectValueChange = new EventEmitter<unknown>();
+}
+```
+
+#### Directive
+
+Moving onto the directive, there are a few things to keep in mind.
+
+- The directive's selector is set to the web component's tag, not the wrapper's.
+- Implementing the `ControlValueAccessor` interface helps Angular understand when the form control has been updated or changed.
+  - When the value is set, `onChange()` notifies that the control has been updated.
+  - Calling `onTouched()` lets Angular know the component has been touched, which is needed for form validation.
+- The `get value()`, and `set value()` are used by Angular's form control.
+- Using the `@HostListener` decorator lets you listen to events from the web component, and execute appropriate logic.
+
+Here is what our directive looks like:
+
+```ts
+import {
+  Directive,
+  forwardRef,
+  ElementRef,
+  HostListener,
+  Input,
+  OnInit,
+  Output,
+  EventEmitter,
+} from '@angular/core';
+import {
+  ControlValueAccessor,
+  FormControl,
+  NG_VALUE_ACCESSOR,
+} from '@angular/forms';
+
+@Directive({
+  selector: 'modus-wc-select',
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      useExisting: forwardRef(() => ModusSelectDirective),
+      multi: true,
+    },
+  ],
+})
+export class ModusSelectDirective implements ControlValueAccessor, OnInit {
+  @Input() disabled: boolean;
+  @Input() errorText: string;
+  @Input() formControl: FormControl;
+  @Input() helperText: string;
+  @Input() label: string;
+  @Input() options: unknown[];
+  @Input() optionsDisplayProp: string;
+  @Input() required: boolean;
+  @Input() selectValue: unknown;
+  @Input() size: 'medium' | 'large';
+  @Input() validText: string;
+
+  @Output() valueChange = new EventEmitter<string>();
+
+  onChange: any = () => {};
+  onTouched: any = () => {};
+
+  private _value: string;
+
+  get value() {
+    return this._value;
+  }
+
+  set value(value) {
+    if (value !== this._value) {
+      this._value = value;
+      this.onChange(this._value);
+      this.onTouched();
+      this.elementRef.nativeElement.value = value;
+    }
+  }
+
+  constructor(private elementRef: ElementRef) {}
+
+  ngOnInit(): void {
+    const modusSelect = this.elementRef.nativeElement as HTMLModusSelectElement;
+    modusSelect.disabled = this.disabled;
+    modusSelect.errorText = this.errorText;
+    modusSelect.helperText = this.helperText;
+    modusSelect.label = this.label;
+    modusSelect.options = this.options;
+    modusSelect.optionsDisplayProp = this.optionsDisplayProp;
+    modusSelect.required = this.required;
+    modusSelect.size = this.size;
+    modusSelect.validText = this.validText;
+    modusSelect.value = this.selectValue;
+
+    if (!this.formControl) {
+      this.formControl = new FormControl(null);
+    }
+  }
+
+  @HostListener('valueChange', ['$event.detail'])
+  listenForValueChange(value: string): void {
+    this.value = value;
+  }
+
+  registerOnChange(fn: Function): void {
+    this.onChange = fn;
+  }
+
+  registerOnTouched(fn: Function): void {
+    this.onTouched = fn;
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    this.disabled = isDisabled;
+  }
+
+  writeValue(value: string): void {
+    if (value) {
+      this.value = value;
+    }
+  }
+}
+```
+
+Now adding the Modus Select as a form control is as easy as:
+
+```ts
+<select-component
+  [formControl]="$any(form).controls['select1']"
+  [label]="'Select Form Demo'"
+  [options]="options"
+  [optionsDisplayProp]="'display'">
+</select-component>
+```

package/versions/1.1.0/component-docs/_all_components.json

@@ -0,0 +1,56 @@
+{
+  "total": 50,
+  "components": [
+    "modus-wc-accordion",
+    "modus-wc-alert",
+    "modus-wc-autocomplete",
+    "modus-wc-avatar",
+    "modus-wc-badge",
+    "modus-wc-breadcrumbs",
+    "modus-wc-button",
+    "modus-wc-button-group",
+    "modus-wc-card",
+    "modus-wc-checkbox",
+    "modus-wc-chip",
+    "modus-wc-collapse",
+    "modus-wc-date",
+    "modus-wc-divider",
+    "modus-wc-dropdown-menu",
+    "modus-wc-file-dropzone",
+    "modus-wc-handle",
+    "modus-wc-icon",
+    "modus-wc-input-feedback",
+    "modus-wc-input-label",
+    "modus-wc-loader",
+    "modus-wc-logo",
+    "modus-wc-menu",
+    "modus-wc-menu-item",
+    "modus-wc-modal",
+    "modus-wc-navbar",
+    "modus-wc-number-input",
+    "modus-wc-pagination",
+    "modus-wc-panel",
+    "modus-wc-profile-menu",
+    "modus-wc-progress",
+    "modus-wc-radio",
+    "modus-wc-rating",
+    "modus-wc-select",
+    "modus-wc-side-navigation",
+    "modus-wc-skeleton",
+    "modus-wc-slider",
+    "modus-wc-stepper",
+    "modus-wc-switch",
+    "modus-wc-table",
+    "modus-wc-tabs",
+    "modus-wc-text-input",
+    "modus-wc-textarea",
+    "modus-wc-theme-switcher",
+    "modus-wc-time-input",
+    "modus-wc-toast",
+    "modus-wc-toolbar",
+    "modus-wc-tooltip",
+    "modus-wc-typography",
+    "modus-wc-utility-panel"
+  ],
+  "last_updated": "1774599204.292"
+}