@trimble-oss/moduswebcomponents-mcp 1.0.1 → 1.2.0

package/versions/1.2.0/component-docs/modus-wc-tooltip.json

@@ -0,0 +1,94 @@
+{
+  "description": "A customizable tooltip component used to create tooltips with different content. The tooltip can be dismissed by pressing the Escape key when hovering over it. When forceOpen is enabled, the tooltip will remain open and can only be closed by setting forceOpen to false.",
+  "properties": [
+    {
+      "name": "content",
+      "type": "string",
+      "description": "The text content of the tooltip.",
+      "default": "''",
+      "mutable": false,
+      "end_line": 36
+    },
+    {
+      "name": "customClass",
+      "type": "string",
+      "description": "Custom CSS class to apply to the inner div.",
+      "default": "''",
+      "mutable": false,
+      "end_line": 39
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "description": "Disables displaying the tooltip on hover",
+      "default": "false",
+      "mutable": false,
+      "end_line": 42
+    },
+    {
+      "name": "forceOpen",
+      "type": "boolean",
+      "description": "Use this attribute to force the tooltip to remain open.",
+      "default": null,
+      "mutable": false,
+      "end_line": 45
+    },
+    {
+      "name": "tooltipId",
+      "type": "string",
+      "description": "The ID of the tooltip element, useful for setting the \"aria-describedby\" attribute of related elements.",
+      "default": null,
+      "mutable": false,
+      "end_line": 48
+    },
+    {
+      "name": "position",
+      "type": "'auto' | 'top' | 'right' | 'bottom' | 'left'",
+      "description": "The position that the tooltip will render in relation to the element.",
+      "default": "'auto'",
+      "mutable": false,
+      "end_line": 51
+    }
+  ],
+  "events": [
+    {
+      "name": "dismissEscape",
+      "detail": "void",
+      "description": "An event that fires when the tooltip is dismissed via Escape key",
+      "end_line": 204
+    }
+  ],
+  "methods": [],
+  "slots": [
+    {
+      "name": "default",
+      "description": "Slot for default content"
+    }
+  ],
+  "examples": {
+    "basic": "<modus-wc-tooltip\n        content=${ifDefined(args.content)}\n        custom-class=\"${ifDefined(args['custom-class'])}\"\n        ?disabled=\"${args.disabled}\"\n        ?force-open=\"${args['force-open']}\"\n        tooltip-id=\"${ifDefined(args['tooltip-id'])}\"\n        position=${ifDefined(args.position)}\n      >\n        <modus-wc-badge>Hover</modus-wc-badge>\n      </modus-wc-tooltip>",
+    "variations": [],
+    "args": {
+      "content": "'Tooltip content'",
+      "position": "'auto'"
+    },
+    "argTypes": {},
+    "usage": [],
+    "events": [
+      "dismissEscape"
+    ]
+  },
+  "tag": "modus-wc-tooltip",
+  "storyExample": {
+    "template": "<modus-wc-tooltip\n        content=${ifDefined(args.content)}\n        custom-class=\"${ifDefined(args['custom-class'])}\"\n        ?disabled=\"${args.disabled}\"\n        ?force-open=\"${args['force-open']}\"\n        tooltip-id=\"${ifDefined(args['tooltip-id'])}\"\n        position=${ifDefined(args.position)}\n      >\n        <modus-wc-badge>Hover</modus-wc-badge>\n      </modus-wc-tooltip>",
+    "args": {
+      "content": "'Tooltip content'",
+      "position": "'auto'"
+    },
+    "argTypes": {},
+    "events": [
+      "dismissEscape"
+    ],
+    "fullContent": "import { Meta, StoryObj } from '@storybook/web-components';\nimport { html } from 'lit';\nimport { ifDefined } from 'lit/directives/if-defined.js';\n\ninterface TooltipArgs {\n  content?: string;\n  'custom-class'?: string;\n  disabled?: boolean;\n  'force-open'?: boolean;\n  'tooltip-id'?: string;\n  position: 'auto' | 'top' | 'right' | 'bottom' | 'left';\n}\n\nconst meta: Meta<TooltipArgs> = {\n  title: 'Components/Tooltip',\n  component: 'modus-wc-tooltip',\n  args: {\n    content: 'Tooltip content',\n    position: 'auto',\n  },\n  argTypes: {\n    position: {\n      control: { type: 'select' },\n      options: ['auto', 'top', 'right', 'left', 'bottom'],\n    },\n  },\n  parameters: {\n    docs: {\n      description: {\n        component: `\nA customizable tooltip component used to create tooltips with different content.\n\\nThe component supports a \\`<slot>\\` for injecting custom tooltip content.\n\n### Features\n- **Escape Key Dismissal**: Tooltips can be dismissed by pressing the Escape key\n- **Auto-positioning**: Automatically positions the tooltip to avoid viewport edges\n- **Customizable**: Supports custom CSS classes and positioning\n\n### Keyboard Interaction\n- Press **Escape** to dismiss the tooltip while it's visible\n- The tooltip will automatically re-enable on mouse enter\n        `,\n      },\n    },\n  },\n};\n\nexport default meta;\n\ntype Story = StoryObj<TooltipArgs>;\n\nconst Template: Story = {\n  parameters: {\n    actions: {\n      handles: ['dismissEscape'],\n    },\n  },\n  render: (args) => {\n    // prettier-ignore\n    return html`\n      <modus-wc-tooltip\n        content=${ifDefined(args.content)}\n        custom-class=\"${ifDefined(args['custom-class'])}\"\n        ?disabled=\"${args.disabled}\"\n        ?force-open=\"${args['force-open']}\"\n        tooltip-id=\"${ifDefined(args['tooltip-id'])}\"\n        position=${ifDefined(args.position)}\n      >\n        <modus-wc-badge>Hover</modus-wc-badge>\n      </modus-wc-tooltip>\n    `;\n  },\n};\n\nexport const Default: Story = { ...Template };\n\nexport const Migration: Story = {\n  parameters: {\n    docs: {\n      description: {\n        story: `\n#### Breaking Changes\n\n  - In 1.0 tooltip positioning was handled by Popper.js. In 2.0, positioning is handled using CSS.\n  - The \\`text\\` prop has been renamed to \\`content\\`.\n\n#### Prop Mapping\n\n| 1.0 Prop    | 2.0 Prop    | Notes                                    |\n|-------------|-------------|------------------------------------------|\n| aria-label  | aria-label  |                                          |\n| disabled    | disabled    |                                          |\n| position    | position    | Added \\`auto\\` option as default value   |\n| text        | content     |                                          |\n        `,\n      },\n    },\n    controls: { disable: true },\n    canvas: { disable: true },\n  },\n  render: () => html`<div></div>`,\n};\n"
+  }
+}

package/versions/1.2.0/component-docs/modus-wc-typography.json

@@ -0,0 +1,78 @@
+{
+  "description": "A customizable typography component used to render text with different sizes, hierarchy, and weights. Note: - When using heading elements (h1-h6), the default heading CSS styling can be accessed without modifying the default size (size=\"md\") and weight (weight=\"normal\") properties. Default styling can be overridden by providing your own custom values for the size or weight properties from the available options. - If both slot content and `label` are provided, only the slot content will be rendered - Use the `label` prop when you need to dynamically update the text.",
+  "properties": [
+    {
+      "name": "customClass",
+      "type": "string",
+      "description": "Custom CSS class to apply to the typography element.",
+      "default": "''",
+      "mutable": false,
+      "end_line": 34
+    },
+    {
+      "name": "hierarchy",
+      "type": "TypographyHierarchy",
+      "description": "The hierarchy of the typography component.",
+      "default": "'p'",
+      "mutable": false,
+      "end_line": 37
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "description": "The text label to display.",
+      "default": null,
+      "mutable": false,
+      "end_line": 40
+    },
+    {
+      "name": "size",
+      "type": "TypographySize",
+      "description": "The size of the font.",
+      "default": "'md'",
+      "mutable": false,
+      "end_line": 43
+    },
+    {
+      "name": "weight",
+      "type": "TypographyWeight",
+      "description": "The weight of the text.",
+      "default": "'normal'",
+      "mutable": false,
+      "end_line": 46
+    }
+  ],
+  "events": [],
+  "methods": [],
+  "slots": [
+    {
+      "name": "default",
+      "description": "Slot for default content"
+    }
+  ],
+  "examples": {
+    "basic": "<modus-wc-typography\n  custom-class=${ifDefined(args['custom-class'])}\n  hierarchy=${args.hierarchy}\n  label=${args.label}\n  size=${ifDefined(args.size)}\n  weight=${ifDefined(args.weight)}\n  ></modus-wc-typography>",
+    "variations": [],
+    "args": {
+      "hierarchy": "'p'",
+      "label": "content",
+      "size": "'md'",
+      "weight": "'normal'"
+    },
+    "argTypes": {},
+    "usage": []
+  },
+  "tag": "modus-wc-typography",
+  "storyExample": {
+    "template": "<modus-wc-typography\n  custom-class=${ifDefined(args['custom-class'])}\n  hierarchy=${args.hierarchy}\n  label=${args.label}\n  size=${ifDefined(args.size)}\n  weight=${ifDefined(args.weight)}\n  ></modus-wc-typography>",
+    "args": {
+      "hierarchy": "'p'",
+      "label": "content",
+      "size": "'md'",
+      "weight": "'normal'"
+    },
+    "argTypes": {},
+    "events": [],
+    "fullContent": "import { Meta, StoryObj } from '@storybook/web-components';\nimport { html } from 'lit';\nimport { ifDefined } from 'lit/directives/if-defined.js';\nimport {\n  TypographyHierarchy,\n  TypographySize,\n  TypographyWeight,\n} from './modus-wc-typography';\n\nconst content = 'The quick brown fox jumps over the lazy dog';\n\ninterface TypographyArgs {\n  'custom-class'?: string;\n  hierarchy: TypographyHierarchy;\n  label: string;\n  size?: TypographySize;\n  weight?: TypographyWeight;\n}\n\nconst meta: Meta<TypographyArgs> = {\n  title: 'Components/Typography',\n  component: 'modus-wc-typography',\n  args: {\n    hierarchy: 'p',\n    label: content,\n    size: 'md',\n    weight: 'normal',\n  },\n  argTypes: {\n    hierarchy: {\n      control: { type: 'select' },\n      options: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p'],\n    },\n    size: {\n      control: { type: 'select' },\n      options: [\n        'xs',\n        'sm',\n        'md',\n        'lg',\n        'xl',\n        '2xl',\n        '3xl',\n        '4xl',\n        '5xl',\n        '6xl',\n        '7xl',\n        '8xl',\n        '9xl',\n      ],\n    },\n    weight: {\n      control: { type: 'select' },\n      options: ['light', 'normal', 'semibold', 'bold'],\n    },\n  },\n};\n\nexport default meta;\n\ntype Story = StoryObj<TypographyArgs>;\n\nconst Template: Story = {\n  render: (args) => {\n    // prettier-ignore\n    return html`\n<modus-wc-typography\n  custom-class=${ifDefined(args['custom-class'])}\n  hierarchy=${args.hierarchy}\n  label=${args.label}\n  size=${ifDefined(args.size)}\n  weight=${ifDefined(args.weight)}\n  ></modus-wc-typography>\n   `;\n  },\n};\n\nexport const Default: Story = { ...Template };\n\nexport const Heading1: Story = {\n  ...Template,\n  args: { hierarchy: 'h1', label: content },\n};\n\nexport const Heading2: Story = {\n  ...Template,\n  args: { hierarchy: 'h2', label: content },\n};\n\nexport const Heading3: Story = {\n  ...Template,\n  args: { hierarchy: 'h3', label: content },\n};\n\nexport const Heading4: Story = {\n  ...Template,\n  args: { hierarchy: 'h4', label: content },\n};\n\nexport const Heading5: Story = {\n  ...Template,\n  args: { hierarchy: 'h5', label: content },\n};\n\nexport const Heading6: Story = {\n  ...Template,\n  args: { hierarchy: 'h6', label: content },\n};\n\nexport const Paragraph: Story = {\n  ...Template,\n  args: { hierarchy: 'p', label: content },\n};\n\nexport const WithLabel: Story = {\n  ...Template,\n  args: {\n    hierarchy: 'p',\n    label: 'This text is set via the label prop',\n  },\n};\n\nexport const WithSlot: Story = {\n  render: (args) => {\n    // prettier-ignore\n    return html`\n<modus-wc-typography\n  custom-class=${ifDefined(args['custom-class'])}\n  hierarchy=${args.hierarchy}\n  size=${ifDefined(args.size)}\n  weight=${ifDefined(args.weight)}\n>\n  This <u>text</u> is set using <em>slot</em>\n</modus-wc-typography>\n  `;\n  },\n};\n"
+  }
+}

package/versions/1.2.0/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/1.2.0/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>
+```