@meshmakers/shared-ui

Angular UI component library for OctoMesh Platform applications.

Provides reusable components, dialog services, data sources, pipes, and guards for building consistent UIs across OctoMesh frontend applications.

Note: This library requires a Kendo UI for Angular license.

Part of the @meshmakers package ecosystem.

Installation

npm install @meshmakers/shared-ui

Environment Setup

Register all services via the environment provider:

import { provideMmSharedUi } from '@meshmakers/shared-ui';

export const appConfig: ApplicationConfig = {
  providers: [
    provideMmSharedUi(),
    // ...
  ]
};

Build & Test

# Build
npm run build:shared-ui

# Lint
npm run lint:shared-ui

# Run tests
npm run test:shared-ui

Architecture

shared-ui/
├── src/
│   ├── public-api.ts                          # Public API exports
│   └── lib/
│       ├── list-view/                         # Configurable grid/table
│       │   ├── list-view.component.ts|html|scss
│       │   └── list-view.model.ts             # TableColumn, StatusIconMapping
│       ├── base-form/                         # Form wrapper with save/cancel
│       │   └── base-form.component.ts|html|scss
│       ├── base-tree-detail/                  # Tree + detail panel layout
│       │   └── base-tree-detail.component.ts|scss
│       ├── tree/                              # Hierarchical tree view
│       │   └── tree.component.ts|html|scss
│       ├── cron-builder/                      # Visual cron expression editor
│       │   ├── cron-builder.component.ts|html|scss
│       │   ├── cron-builder.models.ts
│       │   ├── cron-parser.service.ts
│       │   ├── cron-humanizer.service.ts
│       │   └── cron-builder.constants.ts
│       ├── time-range-picker/                 # Flexible time range selector
│       │   ├── time-range-picker.component.ts|html|scss
│       │   ├── time-range-picker.models.ts
│       │   └── time-range-utils.ts
│       ├── copyable-text/                     # Text with copy-to-clipboard
│       │   └── copyable-text.component.ts|html|scss
│       ├── entity-select-input/               # Entity autocomplete input
│       │   └── entity-select-input.component.ts
│       ├── entity-select-dialog/              # Entity selection modal
│       │   ├── entity-select-dialog.component.ts
│       │   ├── entity-select-dialog.service.ts
│       │   └── entity-select-dialog-data-source.ts
│       ├── confirmation-window/               # Confirmation dialog
│       │   └── confirmation-window.component.ts|html
│       ├── input-dialog/                      # Text input dialog
│       │   └── input-dialog.component.ts|html|scss
│       ├── progress-window/                   # Progress dialog
│       │   ├── progress-window.component.ts|html|scss
│       │   ├── progress-window.service.ts
│       │   └── USAGE.md
│       ├── upload-file-dialog/                # File upload dialog
│       │   └── upload-file-dialog.component.ts|html
│       ├── save-as-dialog/                    # Save-as dialog
│       │   ├── save-as-dialog.component.ts
│       │   ├── save-as-dialog.service.ts
│       │   └── save-as-dialog-data-source.ts
│       ├── import-strategy-dialog/            # Import strategy dialog
│       │   ├── import-strategy-dialog.component.ts|html
│       │   └── import-strategy-dialog.service.ts
│       ├── message-details-dialog/            # Message details dialog
│       │   ├── message-details-dialog.component.ts
│       │   └── message-details-dialog.service.ts
│       ├── data-sources/                      # Base data source classes
│       │   ├── data-source-base.ts
│       │   ├── data-source-typed.ts
│       │   ├── hierarchy-data-source-base.ts
│       │   └── hierarchy-data-source.ts
│       ├── guards/                            # Unsaved changes protection
│       │   ├── unsaved-changes.interface.ts
│       │   ├── unsaved-changes.guard.ts
│       │   └── unsaved-changes.directive.ts
│       ├── directives/
│       │   └── mm-list-view-data-binding.directive.ts
│       ├── pipes/
│       │   ├── pascal-case.pipe.ts
│       │   └── bytes-to-size.pipe.ts
│       ├── models/
│       │   ├── fetchResult.ts                 # FetchResult, FetchResultTyped<T>
│       │   ├── confirmation.ts                # ConfirmationWindowData, DialogType
│       │   ├── progressValue.ts               # ProgressValue
│       │   ├── inputDialogResult.ts
│       │   ├── importStrategyDto.ts
│       │   └── node-dropped-event.ts
│       ├── services/
│       │   ├── confirmation.service.ts
│       │   ├── file-upload.service.ts
│       │   ├── input.service.ts
│       │   ├── notification-display.service.ts
│       │   └── message-listener.service.ts
│       └── svg-icons.ts                       # Kendo SVG icon re-exports
├── docs/
│   ├── time-range-picker.md                   # Time Range Picker guide
│   └── unsaved-changes-guard.md               # Unsaved Changes Guard guide

Components

ListViewComponent (mm-list-view)

Configurable data grid with Kendo Grid integration.

Features: Pagination, sorting, filtering, row selection, search, context menus, action menus, Excel/PDF export, toolbar actions, column types (text, numeric, boolean, date, bytes, status icons, cron expressions).

Empty state (AB#3444): [emptyState]="{ title, text }" shows the shared mm-empty-state (OctoBot idle) for a list without records and the "no results" variant (OctoBot look) while a search or filter is active; [emptyTemplate] replaces it. Without either the list keeps the plain "No records available." line.

Toolbar actions (leftToolbarActions / rightToolbarActions, AB#6211) render flat and neutral by default: a page has exactly one solid primary action and it sits in the page header ([mmPageActions], Studio action guideline §9). Set primary: true on a CommandItem only for a list without a page header (the list is the page). A toolbar action with isDisabled + disabledReason — plain, split or dropdown button — stays focusable (aria-disabled), announces the reason (aria-describedby), shows it in the tooltip ("Run scripts — No fixup scripts to run") and as a hint bubble on keyboard focus; clicks and the menu are blocked. A disabledReason callback receives the current selection.

The toolbar's "Reset Filters" button only appears while something narrows the default view: a row filter, a column sort, a free-text search, or host-side filters. Hosts with their own quick-view/bar filters announce them via [hasExternalFilters]="myBarFilterIsSet" so the button shows (and (resetFilters) lets them clear those filters when it is clicked).

<mm-list-view
  appMyDataSource
  #dir="appMyDataSource"
  [sortable]="true"
  [rowFilterEnabled]="true"
  [searchTextBoxEnabled]="true"
  [selectable]="{mode: 'single', enabled: true}"
  [pageable]="{buttonCount: 3, pageSizes: [10, 20, 50, 100]}"
  [pageSize]="20"
  [columns]="columns"
  [contextMenuCommandItems]="contextMenu"
  [leftToolbarActions]="toolbarActions"
  (rowClicked)="onRowClicked($event)">
</mm-list-view>

BaseFormComponent (mm-base-form)

Form wrapper with save/cancel buttons, title, validation, and unsaved changes detection.

<mm-base-form [form]="form" [config]="formConfig" (saveForm)="onSave()" (cancelForm)="onCancel()">
  <!-- Form fields -->
</mm-base-form>

CronBuilderComponent (mm-cron-builder)

Visual cron expression editor with 6-field format support, preset quick-selects, human-readable descriptions, next execution preview, and ControlValueAccessor integration.

TimeRangePickerComponent (mm-time-range-picker)

Flexible time range selector with Year, Quarter, Month, Relative, and Custom modes. Outputs both Date objects and ISO 8601 strings.

See Time Range Picker Documentation for detailed API and examples.

TreeComponent (mm-tree)

Hierarchical tree view with Kendo TreeView, drag-drop support, and expandable nodes.

CopyableTextComponent (mm-copyable-text)

Display text with a one-click copy-to-clipboard button.

Actions (mm-row-actions, mm-action-button)

Row, toolbar and page actions from one shared MmAction definition (id, label, icon, danger, disabled reason, visible): icon buttons with tooltip and a row-specific accessible name, max. 3 inline slots with a "More actions" menu, focusable disabled actions that announce their reason, and a canonical verb→icon map (MM_ACTION_ICONS). See Actions.

<mm-row-actions [actions]="actionsFor(row)" [rowLabel]="row.name" (triggered)="onAction($event, row)" />
<mm-action-button [action]="refresh" context="toolbar" (triggered)="reload()" />

OctoBot (mm-octobot, mm-empty-state)

The meshmakers mascot as a small animated pixel-art image (idle, blink, look, swim, thinking, wave; sm/md/lg), loaded by URL from the library assets (copy node_modules/@meshmakers/shared-ui/assets/octobot to /assets/octobot in angular.json; base URL via OCTOBOT_ASSET_BASE_URL). Decorative unless labelled; still frame under prefers-reduced-motion. mm-empty-state is the shared empty / no-results / error block, and mm-list-view [emptyState] renders it once per list. Placement rules (never in rows, tiles, buttons, toasts or errors): see OctoBot.

<mm-octobot animation="wave" size="md" playOnce />
<mm-list-view [emptyState]="{ title: 'No data flows yet', text: 'Create your first data flow.' }" ...></mm-list-view>

EntitySelectInputComponent (mm-entity-select-input)

Autocomplete input for entity selection with dialog fallback.

Dialog Services

All complex dialogs are opened via injected services:

| Service | Method | Description | |---------|--------|-------------| | ConfirmationService | showYesNoConfirmationDialog() | Yes/No confirmation | | | showYesNoCancelConfirmationDialog() | Yes/No/Cancel with result | | | showOkCancelConfirmationDialog() | Ok/Cancel confirmation | | | showOkDialog() | Ok-only information dialog | | | showDestructiveConfirmationDialog(title, message, confirmLabel, cancelLabel = 'Cancel') | Destructive action: verb labels (e.g. Rotate / Cancel), confirming button styled as danger |

All confirmation dialogs are min(320px, 100vw − 32px) to min(560px, 100vw − 32px) wide, so a long message wraps instead of stretching the dialog across the viewport. | InputService | — | Text input dialog | | FileUploadService | — | File upload dialog | | ProgressWindowService | showDeterminateProgress() | Progress bar with percentage | | | showIndeterminateProgress() | Spinning loader | | NotificationDisplayService | showSuccess(), showError(), showWarning(), showInfo() | Toast notifications | | EntitySelectDialogService | — | Entity selection modal | | SaveAsDialogService | — | Save-as dialog with path navigation | | ImportStrategyDialogService | — | Import strategy selection | | MessageDetailsDialogService | — | Detailed message/error display |

Toast stacking is configurable with NOTIFICATION_DISPLAY_OPTIONS: identical visible toasts (same type, text and details) are never stacked twice (dedupe, default on); errorHideAfter / warningHideAfter (ms, default 0 = until interaction or navigation) auto-hide non-critical errors and warnings — a caller passing hideAfter: 0 still gets a sticky one, and stickyWithDetails keeps every error/warning that has details; a timed toast pauses while hovered or focused; maxVisible (default 0 = unlimited) hides the oldest toast of the lowest severity, so an error or warning is never dropped for a success or info.

{ provide: NOTIFICATION_DISPLAY_OPTIONS, useValue: { errorHideAfter: 10000, warningHideAfter: 8000, stickyWithDetails: true, maxVisible: 3 } }

See Progress Window Usage for progress dialog examples.

Data Sources

Base classes for data binding with ListViewComponent:

| Class | Description | |-------|-------------| | DataSourceBase | Abstract base with pagination, filtering, sorting | | DataSourceTyped<T> | Generic typed data source | | HierarchyDataSourceBase | Base for tree/hierarchical data | | HierarchyDataSource | Implementation for tree structures |

Guards & Directives

Unsaved Changes Protection

Two-level protection against accidental data loss:

| Component | Protects Against | |-----------|-----------------| | UnsavedChangesDirective | Browser back/refresh/close (beforeunload) | | UnsavedChangesGuard | In-app navigation (Angular Router canDeactivate) | | HasUnsavedChanges | Interface for components to implement |

See Unsaved Changes Guard Documentation for implementation guide.

MmListViewDataBindingDirective

Data binding directive for ListViewComponent, managing data source and pagination.

Pipes

| Pipe | Usage | Example | |------|-------|---------| | PascalCasePipe | {{ value \| pascalCase }} | "my_field" → "MyField" | | BytesToSizePipe | {{ value \| bytesToSize }} | 1048576 → "1.0 MB" |

Models

| Model | Description | |-------|-------------| | FetchResult / FetchResultTyped<T> | Paginated query result wrapper | | TableColumn / ColumnDefinition | Column definitions for ListViewComponent | | StatusIconMapping / StatusFieldConfig | Status icon configuration | | ProgressValue | Progress status text + percentage | | TimeRange / TimeRangeISO / TimeRangeSelection | Time range types | | CronBuilderConfig / CronSchedule / CronFields | Cron builder types | | ImportStrategyDto | Import configuration | | NodeDroppedEvent | Tree drag-drop event data | | ConfirmationWindowData / ConfirmationWindowResult | Dialog configuration |

Dependencies

• Angular 21 with standalone components and signals
• Kendo UI Angular 21 (Grid, Buttons, Dialog, Dropdowns, Inputs, Indicators, Layout, Notifications, TreeView)
• @meshmakers/shared-services (sibling library)

Detailed Documentation

• Actions — mm-row-actions, mm-action-button, MmAction, canonical icons
• OctoBot — mm-octobot, mm-empty-state, assets, placement rules
• Time Range Picker — Full API reference, configuration, examples
• Unsaved Changes Guard — Implementation guide with checklists
• Progress Window Usage — Progress dialog examples, migration from Angular Material

Documentation and Testing Standards

• All developer documentation must be written in English
• Every code change must include updated documentation — update README.md, CLAUDE.md, or inline docs when adding, modifying, or removing features
• Unit tests and integration tests must be executed after every code change
• Existing tests must be updated when the behavior of tested code changes
• New tests must be added when new features, components, or services are implemented
• Never commit code with failing tests