@bitstack/ng-boundary

A responsive boundary component for Angular applications with built-in orientation support and SCSS utilities for pixel-perfect responsive design.

Features

• Responsive boundary container with automatic aspect ratio management
• Portrait and landscape orientation support with auto-detection
• CSS custom properties for responsive sizing
• Comprehensive SCSS utilities for responsive design
• Standalone component architecture (Angular 14+)

Installation

npm install @bitstack/ng-boundary

Usage

1. Using the Component

Import and use the BsBoundary component in your Angular application:

import { Component } from '@angular/core';
import { BsBoundary } from '@bitstack/ng-boundary';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [BsBoundary],
  template: `
    <bs-boundary
      [isDebug]="false"
      [bgColor]="'transparent'"
      [contentClickable]="true"
      [orientationMode]="'auto'"
      (afterBoundaryInit)="onBoundaryInit($event)"
      (orientationChange)="onOrientationChange($event)">
      <!-- Your content here -->
      <div class="my-content">
        Hello World
      </div>
    </bs-boundary>
  `
})
export class AppComponent {
  onBoundaryInit(boundary: ElementRef<HTMLDivElement>) {
    console.log('Boundary initialized:', boundary);
  }

  onOrientationChange(mode: 'portrait' | 'landscape') {
    console.log('Orientation changed to:', mode);
  }
}

Component Inputs

• isDebug: (boolean) Enable debug mode with background color - default: false
• bgColor: (string) Background color for the boundary
• contentClickable: (boolean) Whether content is clickable - default: true
• orientationMode: ('auto' | 'portrait' | 'landscape') Orientation mode - default: 'auto'
• injectStyle: (IInjectStyle) Custom styles to inject

Component Outputs

• afterBoundaryInit: Emits after boundary initialization with ElementRef
• orientationChange: Emits when orientation changes

2. Using SCSS Utilities

The boundary component provides CSS custom properties that you can use with the included SCSS utilities:

Import SCSS Utilities

In your component SCSS file or global styles:

@use '@bitstack/ng-boundary/styles' as boundary;

.my-component {
  // Use the px2vw function for responsive sizing
  // This automatically adapts to portrait/landscape mode
  width: boundary.px2vw(100);
  height: boundary.px2vw(200);
  padding: boundary.px2vw(20);

  // Or use mixins for specific properties
  @include boundary.width(100);
  @include boundary.height(200);
  @include boundary.padding-left(20);
}

Available SCSS Functions

• px2vw($px) - Converts px to responsive units based on boundary
• px2vw-unbounded($px) - Converts px to viewport units (not bounded)
• vw($w) - Returns viewport width unit (dvw or vw)
• vh($h) - Returns viewport height unit (dvh or vh)

Available SCSS Mixins

Responsive sizing mixins:

• @include width($px) - Set responsive width
• @include height($px) - Set responsive height
• @include padding-left($px) - Set responsive left padding
• @include padding-right($px) - Set responsive right padding
• @include padding-top($px) - Set responsive top padding
• @include padding-bottom($px) - Set responsive bottom padding
• @include px2vw($property, $px) - Set any property with responsive value

Utility mixins:

• @include flexCenter - Flex center alignment
• @include hideScrollbar - Hide scrollbars
• @include bg-contain - Background contain
• @include bg-cover - Background cover
• @include text-center - Center text
• @include text-shadow($color) - Text shadow
• @include size($w, $h: $w) - Set width and height

Responsive breakpoint mixins:

• @include s { ... } - Small devices and up
• @include landscape { ... } - Mobile landscape
• @include portrait { ... } - Mobile portrait
• @include pc_landscape { ... } - PC landscape
• @include pc_portrait { ... } - PC portrait

CSS Custom Properties

The boundary component sets these CSS variables that the SCSS utilities use:

• --boundary-width - Current boundary width
• --boundary-height - Current boundary height
• --design-base-width - Design base width (portrait: 540, landscape: 960)
• --design-base-height - Design base height (portrait: 960, landscape: 540)
• --px2vw-ratio - Ratio for px to responsive unit conversion

3. Complete Example

// app.component.ts
import { Component } from '@angular/core';
import { BsBoundary } from '@bitstack/ng-boundary';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [BsBoundary],
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.scss']
})
export class AppComponent {}

<!-- app.component.html -->
<bs-boundary [orientationMode]="'auto'">
  <div class="game-container">
    <h1 class="title">My Game</h1>
    <button class="play-button">Play</button>
  </div>
</bs-boundary>

// app.component.scss
@use '@bitstack/ng-boundary/styles' as boundary;

.game-container {
  @include boundary.flexCenter;
  flex-direction: column;
  width: 100%;
  height: 100%;
  gap: boundary.px2vw(20);
}

.title {
  font-size: boundary.px2vw(48);
  @include boundary.padding-top(40);
}

.play-button {
  @include boundary.width(200);
  @include boundary.height(60);
  font-size: boundary.px2vw(24);
  border-radius: boundary.px2vw(12);
}

Design System

The component is designed with these base dimensions:

• Portrait mode: 540px × 960px
• Landscape mode: 960px × 540px

The px2vw() function automatically scales your design to fit within the boundary while maintaining aspect ratio.

Requirements

• Angular 14.0.0 or higher
• @angular/cdk 14.0.0 or higher
• SCSS support in your Angular project

Building

To build the library:

ng build bitstack-ng-boundary

License

MIT