@trimble-oss/moduswebcomponents-mcp 1.0.0

package/versions/base/docs/_all_docs.json

@@ -0,0 +1,15 @@
+{
+  "total": 10,
+  "docs": [
+    "accessibility",
+    "angular",
+    "form-inputs",
+    "getting-started",
+    "modus-figma-mcp-integration-guide",
+    "modus-icon-usage",
+    "react",
+    "styling",
+    "testing",
+    "vue"
+  ]
+}

package/versions/base/docs/accessibility.mdx

@@ -0,0 +1,32 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Accessibility" />
+
+# Accessibility
+
+The Modus Web Components package is designed to be accessible by default. This means that the components are built with accessibility in mind and are tested to ensure they meet the [Web Content Accessibility Guidelines (WCAG)](https://www.w3.org/WAI/standards-guidelines/wcag/).
+
+Features:
+
+- Meet [minimum contrast requirements (Level AA)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html).
+- Keyboard navigable where applicable.
+- Screen reader accessible.
+- Supports the [prefers-reduced-motion media query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to minimize the amount of non-essential motion.
+
+Found an accessibility issue? Please [report it at GitHub](https://github.com/trimble-oss/modus-wc-2.0/issues/new?assignees=&labels=accessibility&template=accessibility-issue-report.md&title=).
+
+## For contributors
+
+The Storybook site has an Accessibility tab that can be used to test the components for accessibility issues. If you are contributing to the Modus Web Components package please ensure that your changes do not introduce accessibility issues. If there are any violations please address them before submitting your changes. If you are unsure, please reach out to the team for guidance.
+
+## Useful tools for testing your sites
+
+### Browser extensions
+
+- [axe DevTools](https://chromewebstore.google.com/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd)
+- [Lighthouse](https://chromewebstore.google.com/detail/lighthouse/blipmdconlkpinefehnmjammfjpmpbjk)
+- [Microsoft Accessibility Insights](https://accessibilityinsights.io/downloads/)
+
+## Further Reading
+
+You can find more information on accessibility on the [Modus website](https://modus.trimble.com/foundations/accessibility/).

package/versions/base/docs/angular.mdx

@@ -0,0 +1,346 @@
+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. 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/base/docs/form-inputs.mdx

@@ -0,0 +1,86 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Form Inputs" />
+
+# Form Inputs
+
+## Controlled Input Pattern
+
+The controlled input pattern is a design pattern where the form element's value is controlled by the application state rather than the DOM element itself. This pattern offers several benefits:
+
+- Single source of truth for input values
+- Ability to validate and transform input data in real-time
+- Simplified form state management
+- Improved testability and debugging
+
+### Angular
+
+Angular uses two-way data binding with ngModel to implement the controlled input pattern efficiently.
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'controlled-text-input',
+  template: `
+    <modus-wc-text-input
+      (inputChange)="onInputChange($event)"
+      [value]="inputValue"
+    >
+    </modus-wc-text-input>
+  `,
+})
+export class ControlledTextInput {
+  inputValue: string = '';
+
+  onInputChange(event: CustomEvent) {
+    this.inputValue = event.detail.target.value;
+
+    // You can add validation or transformation logic here
+  }
+}
+```
+
+### React
+
+React's controlled input pattern binds form elements to state values and handlers, making React a natural fit for controlled inputs.
+
+```typescript jsx
+import { useState } from 'react';
+
+function ControlledTextInput() {
+  const [value, setValue] = useState('');
+
+  // Handle input changes
+  const handleChange = (event: CustomEvent) => {
+    setValue(event.detail.target.value);
+  };
+
+  return <ModusWcTextInput onInputChange={handleChange} value={value} />;
+}
+```
+
+### Web Components
+
+Web Components can implement the controlled input pattern by exposing properties and events that allow parent applications to manage state externally.
+
+```javascript
+// Example of using the Modus Text Input as a controlled component
+const textInput = document.getElementById('first-name');
+let inputValue = ''; // State lives in the parent application
+
+// Set initial value
+textInput.value = inputValue;
+
+// Listen for changes
+textInput.addEventListener('inputChange', (event) => {
+  // Update our state
+  inputValue = event.detail.target.value;
+
+  // You can perform validation or transformations here
+
+  // Update the input to reflect the new state
+  // This step is only needed if you transform the value
+  textInput.value = inputValue;
+});
+```

package/versions/base/docs/getting-started.mdx

@@ -0,0 +1,91 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Getting Started" />
+
+# Getting Started
+
+## Installation
+
+<b>
+  Lock the installed package version to avoid unintended breakages on future npm
+  installs.
+</b>
+
+```bash
+npm install @trimble-oss/moduswebcomponents
+```
+
+## Usage
+
+### 1. 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';
+```
+
+### 2. Set the theme:
+
+The theme can be set manually or by using the `ThemeSwitcher` component. See the "Use a Theme" section of [Styling](/docs/documentation-styling--docs) for guidance.
+
+Available themes are:
+
+- `modus-classic-light`
+- `modus-classic-dark`
+- `modus-modern-light` (default)
+- `modus-modern-dark`
+
+### 3. Register custom elements:
+
+```javascript
+import { defineCustomElements } from '@trimble-oss/moduswebcomponents/loader';
+
+// Call during the initial loading of your application
+const Root = () => {
+  defineCustomElements();
+
+  return <App />;
+};
+```
+
+### 4. Use the components:
+
+```javascript
+// Use in HTML
+<modus-wc-button variant="primary">Click me</modus-wc-button>
+```
+
+## Types
+
+Types are a crucial part of our component library, providing robust type safety and enhanced developer experience through comprehensive TypeScript definitions for all components.
+
+```javascript
+import { ISelectOption, ModusWcSelectCustomEvent } from '@trimble-oss/moduswebcomponents';
+
+const options: ISelectOption[] = [
+  {
+    label: 'Option 1',
+    value: '1',
+  },
+  {
+    label: 'Option 2',
+    value: '2',
+  },
+];
+
+const handleEvent = (e: ModusWcSelectCustomEvent<ISelectOption>) => {}
+```
+
+## Framework Integrations
+
+- ### [Angular](?path=/docs/documentation-frameworks-angular--docs)
+
+- ### [React](?path=/docs/documentation-frameworks-react--docs)
+
+- ### [Vue](?path=/docs/documentation-frameworks-vue--docs)
+
+---
+
+Need help? Check out our [GitHub repository](https://github.com/trimble-oss/modus-wc-2.0)
+or [raise an issue](https://github.com/trimble-oss/modus-wc-2.0/issues).