iox-ui — UI component library

This package contains shared UI components, directives and services used across IOX apps. It is built as an Angular library and exported from the projects/iox-ui package.

Overview

• Modular components: IoxUiModule aggregates smaller modules (AOS, Masonry, Page, ViewPosition).
• Individual modules are available and can be imported on demand.
• Includes a PageScrollProvider service (module-scoped) that wraps the Lenis smooth-scrolling library.

Installation

Install the library in your application or workspace (published package name: @iox-dev/iox-ui):

npm install @iox-dev/iox-ui

Note: this library depends on lenis for the PageScrollProvider. The workspace version uses lenis as a dependency; consumers installing the published package will get it automatically.

Public API / Exports

The library exports (important list):

• IoxUiModule — umbrella module that re-exports submodules
• IoxPageModule / IoxPageComponent — page wrapper with scroll events
• IoxAosModule / iox-aos directive and container component — animation-on-scroll helpers
• IoxMasonryModule — masonry layout helpers
• ViewPositionModule / ViewPositionDirective — viewport position utilities
• PageScrollProvider service — Lenis wrapper (module-scoped)

Refer to projects/iox-ui/src/public-api.ts for the full list of exported symbols.

Usage

Import the umbrella module or individual modules in your application module:

import { IoxUiModule } from '@iox-dev/iox-ui';

@NgModule({
  imports: [IoxUiModule]
})
export class AppModule {}

Or import only the page module if you only need the page component and scroll provider:

import { IoxPageModule } from '@iox-dev/iox-ui';

@NgModule({
  imports: [IoxPageModule]
})
export class SomeModule {}

IoxPageComponent

• Selector: iox-page-component
• Inputs:
  • class: string — CSS classes applied to the outer wrapper.
• Outputs:
  • scrollEvent — emits an object with scrollTop, scrollLeft, scrollHeight, scrollWidth, clientHeight, clientWidth, scrollPercentage.

Example:

<iox-page-component class="my-page">
  <div>Page content here</div>
</iox-page-component>

If you need to access the scrolling API programmatically, inject PageScrollProvider in a component that belongs to a module that imports IoxPageModule (the provider is module-scoped and provided by IoxPageModule):

constructor(private pageScroll: PageScrollProvider) {}

ngAfterViewInit() {
  this.pageScroll.init({ wrapper: someEl });
}

Services

• PageScrollProvider — wraps Lenis. Note: it is provided in IoxPageModule providers, so it's available only when the module is imported. This prevents the service from being visible globally unless explicitly included.

Development

Build the workspace and library:

cd /path/to/repo/iox-ui
npm install
npm run build

Run the unit tests (if configured):

npm test

Publishing

The repo includes GitHub Actions workflows to build and publish the library. The publishing workflow will:

• Build the library
• Bump the patch version automatically
• Commit the bumped version to projects/iox-ui/package.json and push to main
• Publish the package to npm (requires NPM_TOKEN secret)

If you prefer manual control of the version, use the manual publish workflow or publish locally (see CONTRIBUTING below).

Contributing

1. Create a feature branch from main.
2. Add tests and ensure npm run build and npm test pass.
3. Open a Pull Request — CI will build the library.

If you add services that should be module-scoped, register them in the module providers array to keep DI scoping predictable.

Troubleshooting

• If you see Cannot find module 'lenis' at runtime, ensure lenis is installed in the consuming project (it should be in the published package dependencies). Locally run npm install lenis.
• Sass @import deprecation warnings are present in the workspace styles; consider migrating to @use/@forward.

For more details, inspect projects/iox-ui/src/public-api.ts and the module files under projects/iox-ui/src/lib/.

IoxUi

This library was generated with Angular CLI version 13.1.0.

Code scaffolding

Run ng generate component component-name --project iox-ui to generate a new component. You can also use ng generate directive|pipe|service|class|guard|interface|enum|module --project iox-ui.

Note: Don't forget to add --project iox-ui or else it will be added to the default project in your angular.json file.

Build

Run ng build iox-ui to build the project. The build artifacts will be stored in the dist/ directory.

Publishing

After building your library with ng build iox-ui, go to the dist folder cd dist/iox-ui and run npm publish.

Running unit tests

Run ng test iox-ui to execute the unit tests via Karma.

Further help

To get more help on the Angular CLI use ng help or go check out the Angular CLI Overview and Command Reference page.