UniPin Angular Applet

UniPin Angular Applet is an internal tool used by UniPin to build consistent and high-quality applets using the Angular framework. UniPin Angular Applet provides a set of reusable components, directives, and services that adhere to UniPin's design system.

UniPin Angular Applet is:

1. Modular, so you can import only what you need.
2. Configurable, allowing you to define applet metadata and structure easily.
3. Integrated, working seamlessly with other UniPin libraries like @unipin/angular-gql.
4. Multi Entry Points, supporting granular imports for better optimization.
5. Tree Shakeable, removing unused code to minimize bundle size.

Versions

| Angular | @unipin/angular-applet | |------------------|:----------------------:| | >=18.0.0 | v21.1.0 |

Table of contents

• Getting started
• API
• Development
• Release

Getting started

Step 1: Install @unipin/angular-applet:

NPM

npm install --save @unipin/angular-applet

Step 2: Provide UniPin Applet configuration (Only if using the applet container) usually in the applet projects

Standalone: Call provideAppletConfig function inside ApplicationConfig providers array:

import { provideAppletConfig } from '@unipin/angular-applet/containers';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAppletConfig({
      icon: 'icon-name',
      name: 'Applet Name',
      version: '1.0.0',
      containers: [
        {
          icon: 'container-icon',
          label: 'Container Label',
          path: '/container-path'
        }
      ]
    }),
  ]
};

Step 3: Use components

import { UpButtonDirective } from '@unipin/angular-applet/buttons';

@Component({
  standalone: true,
  imports: [UpButtonDirective],
  template: `<button upButton>Click me</button>`
})
export class MyComponent {}

Step 4: Style Configuration

Add this configuration to your styles.css:

@import 'tw-animate-css';
@source './../../node_modules/@unipin/angular-applet/';
@custom-variant dark (&:is(.dark *));

@theme inline {
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
}

:root {
  --radius: 0.625rem;
  --background: oklch(0.9911 0 0);
  --foreground: oklch(0.3791 0 0);

  --primary: oklch(0.6769 0.1781 44.42);
  --primary-foreground: oklch(1 0 0);
  --secondary: oklch(0.9714 0.0136 46.23);
  --secondary-foreground: oklch(0.6769 0.1781 44.42);
  --muted: oklch(0.9702 0 0);
  --muted-foreground: oklch(0.4926 0 0);
  --accent: oklch(0.9714 0.0136 46.23);
  --accent-foreground: oklch(0.6769 0.1781 44.42);
  --destructive: oklch(0.6533 0.2305 28.81);

  --ring: oklch(0.6769 0.1781 44.42);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);

  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
}
    
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);

  --primary: oklch(0.6769 0.1781 44.42);
  --primary-foreground: oklch(1 0 0);
  --secondary: oklch(0.9714 0.0136 46.23);
  --secondary-foreground: oklch(0.6769 0.1781 44.42);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.9714 0.0136 46.23);
  --accent-foreground: oklch(0.6769 0.1781 44.42);
  --destructive: oklch(0.704 0.191 22.216);

  --ring: oklch(0.6769 0.1781 44.42);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);

  --popover: oklch(0.269 0 0);
  --popover-foreground: oklch(0.985 0 0);
} 

What this configuration does:

• Enables component animations
• Configures light/dark mode themes
• Sets up color design tokens
• Defines border radius system

API

Applet Configuration

| Input | Type | Default | Required | Description | Example | | :------------- | :------------ | :------ | :------- | :-------------------------- | :-------------------------------------------------------------------------------- | | icon | string | - | true | Applet icon name | icon-name | | name | string | - | true | Applet name | Applet Name | | version | string | - | true | Applet version | 1.0.0 | | containers | Container[] | - | true | List of containers (routes) | [{ icon: 'container-icon', label: 'Container Label', path: '/container-path' }] | | enabledSetting | boolean | false | false | Enable settings menu | true |

Container Interface

| Property | Type | Required | Description | | :---------- | :------- | :------- | :------------------------------------------------------------------------- | | icon | string | true | Container icon | | label | string | true | Container label (displayed in sidebar) | | path | string | true | Route path (must start with /) | | permissions | object | false | Permission configuration { codes: string[], aggregator?: 'AND' \| 'OR' } |

Available Modules

The library is organized into secondary entry points. Import them as @unipin/angular-applet/<module>.

Accordion (@unipin/angular-applet/accordion)

| Component / Directive | Description | | :---------------------------- | :----------------------------------------------- | | UpAccordionDirective | Directive to create an accordion container. | | UpAccordionItemDirective | Directive for an individual accordion item. | | UpAccordionTriggerDirective | Directive for the accordion item trigger/header. | | UpAccordionContentDirective | Directive for the accordion item content. |

Alert (@unipin/angular-applet/alert)

| Component / Directive | Description | | :---------------------------- | :------------------------------------- | | UpAlertDirective | Directive to display an alert message. | | UpAlertTitleDirective | Directive for the alert title. | | UpAlertDescriptionDirective | Directive for the alert description. |

Alert Dialog (@unipin/angular-applet/alert-dialog)

| Component / Directive | Description | | :----------------------- | :-------------------------------------------- | | UpAlertDialogComponent | Component to display an alert dialog (modal). |

Approval (@unipin/angular-applet/approval)

| Component / Directive | Description | | :------------------------ | :-------------------------------- | | UpApprovalFormComponent | Component for approval workflows. |

Auth (@unipin/angular-applet/auth)

| Component / Directive | Description | | :---------------------- | :-------------------------------------------------------------------------------- | | UpPermissionDirective | Structural directive that conditionally renders content based on user permissions.|

Avatar (@unipin/angular-applet/avatar)

| Component / Directive | Description | | :-------------------- | :--------------------------------- | | UpAvatarDirective | Directive to display user avatars. |

Badge (@unipin/angular-applet/badge)

| Component / Directive | Description | | :-------------------- | :----------------------------------- | | UpBadgeDirective | Directive to display badges or tags. |

Buttons (@unipin/angular-applet/buttons)

| Component / Directive | Description | | :----------------------- | :----------------------------------------------------------------- | | UpButtonDirective | Directive to style standard buttons. | | UpSplitButtonComponent | Component for a split button with a primary action and a dropdown. |

Calendar (@unipin/angular-applet/calendar)

| Component / Directive | Description | | :-------------------- | :------------------------------- | | UpCalendarComponent | Component to display a calendar. |

Collapsible (@unipin/angular-applet/collapsible)

| Component / Directive | Description | | :------------------------------ | :------------------------------------------------------- | | UpCollapsibleDirective | Directive for collapsible content areas. | | UpCollapsibleTriggerDirective | Directive for the trigger to toggle collapsible content. | | UpCollapsibleContentDirective | Directive for the content to be collapsed/expanded. |

Common (@unipin/angular-applet/common)

| Component / Directive | Description | | :----------------------- | :----------------------------------------------- | | UpFileDragNDropDirective | Directive to handle file drag and drop events. |

Containers (@unipin/angular-applet/containers)

| Component / Directive | Description | | :---------------------------- | :-------------------------------------------------------------- | | UpAppletContainerComponent | Main container component for the applet layout. | | UpColumnContainerComponent | Container component for column-based layouts. | | UpContentContainerComponent | Container component for main content areas. | | UpLazyRouteDirective | Directive to lazy load components based on route configuration. |

Dialog (@unipin/angular-applet/dialog)

| Component / Directive | Description | | :------------------------- | :------------------------------------- | | UpDialogWrapperComponent | Wrapper component for dialogs. | | UpDialogTriggerDirective | Directive to trigger a dialog opening. | | UpDialogContentDirective | Directive for the dialog content. | | UpDialogCloseDirective | Directive to close the dialog. |

Forms (@unipin/angular-applet/forms)

| Component / Directive | Description | | :------------------------------- | :--------------------------------------------------------------- | | UpCheckboxDirective | Directive for checkbox inputs. | | UpCountrySelectComponent | Component to select a country. | | UpCurrencySelectComponent | Component to select a currency. | | UpDateRangePickerComponent | Component to pick a date range. | | UpDatepickerComponent | Component to pick a single date. | | UpFormFieldComponent | Wrapper component for form fields with labels and error messages.| | UpImagePickerComponent | Component to pick/upload an image. | | UpInputDirective | Directive for standard text inputs. | | UpNumberDirective | Directive for numeric inputs. | | UpPasswordComponent | Component for password inputs with visibility toggle. | | UpRateGroupCodeSelectComponent | Component to select rate group codes. | | UpSearchableSelectComponent | Select component with search functionality. | | UpSelectComponent | Standard select dropdown component. | | UpSwitchComponent | Toggle switch component. |

Froala (@unipin/angular-applet/froala)

| Component / Directive | Description | | :-------------------- | :----------------------------------------------- | | UpFroalaComponent | Wrapper component for the Froala WYSIWYG editor. |

Infinite Scroll (@unipin/angular-applet/infinite-scroll)

| Component / Directive | Description | | :-------------------------- | :------------------------------------------------------------------------ | | UpInfiniteScrollDirective | Directive to trigger events when scrolling near the bottom of a container.|

JSON Viewer (@unipin/angular-applet/json-viewer)

| Component / Directive | Description | | :---------------------- | :-------------------------------------------------- | | UpJsonViewerComponent | Component to display JSON data in a readable format. |

KBD (@unipin/angular-applet/kbd)

| Component / Directive | Description | | :-------------------- | :------------------------------------------------------ | | UpKbdDirective | Directive to style keyboard shortcuts (e.g., Ctrl + C). |

Loading Dialog (@unipin/angular-applet/loading-dialog)

| Component / Directive | Description | | :------------------------- | :---------------------------------------------------- | | UpLoadingDialogComponent | Component to display a loading indicator in a dialog. |

Markdown (@unipin/angular-applet/markdown)

| Component / Directive | Description | | :------------------------- | :------------------------------------ | | UpMarkdownInputComponent | Component for markdown input/editing. | | UpMarkdownDirective | Directive to render markdown content. |

Popover (@unipin/angular-applet/popover)

| Component / Directive | Description | | :-------------------------- | :--------------------------------- | | UpPopoverComponent | Component to display a popover. | | UpPopoverTriggerDirective | Directive to trigger a popover. | | UpPopoverContentDirective | Directive for the popover content. | | UpPopoverCloseDirective | Directive to close the popover. |

Progress Bar (@unipin/angular-applet/progress-bar)

| Component / Directive | Description | | :----------------------- | :----------------------------------- | | UpProgressBarDirective | Directive to display a progress bar. |

Skeleton (@unipin/angular-applet/skeleton)

| Component / Directive | Description | | :-------------------- | :-------------------------------------------- | | UpSkeletonDirective | Directive to display loading skeleton states. |

Spinner (@unipin/angular-applet/spinner)

| Component / Directive | Description | | :-------------------- | :-------------------------------------- | | UpSpinnerComponent | Component to display a loading spinner. |

Swipeable (@unipin/angular-applet/swipeable)

| Component / Directive | Description | | :---------------------------- | :------------------------------------------------ | | UpSwipeableDirective | Directive to make an element swipeable. | | UpSwipeableButtonDirective | Directive for buttons within a swipeable element. | | UpSwipeableButtonsDirective | Container directive for swipeable buttons. | | UpSwipeableContentDirective | Directive for the content of a swipeable element. |

Tabs (@unipin/angular-applet/tabs)

| Component / Directive | Description | | :----------------------- | :---------------------------------- | | UpTabsComponent | Component to display tabs. | | UpTabsTriggerDirective | Directive for a tab trigger/header. | | UpTabsContentDirective | Directive for the content of a tab. |

Tooltip (@unipin/angular-applet/tooltip)

| Component / Directive | Description | | :-------------------- | :--------------------------------------- | | UpTooltipDirective | Directive to display a tooltip on hover. |

Development

Perform the clone-to-launch steps with these terminal commands.

Run storybook

git clone [email protected]:MobileArts/unipin-applet-lib.git
cd unipin-applet-lib
npm run storybook

Release

To release to npm just run npm run publish, of course if you have permissions ;)