@vroxal/vd-angular 1.0.1 → 1.1.0

package/README.md

@@ -1,63 +1,274 @@
-# AngularComponents
+# @vroxal/vd-angular
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.0.0.
+Angular component library for the Vroxal Design.
 
-## Code scaffolding
+## What This Package Includes
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+`@vroxal/vd-angular` provides Vroxal UI building blocks for Angular applications, including:
+
+- actions and inputs
+- date and time pickers
+- dropdowns, tooltips, dialogs, drawers, and confirmation flows
+- navigation and layout components
+- data display and feedback states
+
+The package is designed to be used together with:
+
+- `@vroxal/vd-tokens`
+- `@vroxal/vd-icons`
+
+## Requirements
+
+- Angular 21
+- `@angular/cdk`
+- `@vroxal/vd-tokens`
+- `@vroxal/vd-icons`
+
+## Installation
+
+Install the package and its peer dependencies:
 
 ```bash
-ng generate component component-name
+npm install @vroxal/vd-angular @vroxal/vd-tokens @vroxal/vd-icons @angular/cdk
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+## Required Global Styles
 
-```bash
-ng generate --help
+Add the Vroxal tokens, icons, and library stylesheet to your app's global styles.
+
+Example `angular.json` configuration:
+
+```json
+{
+  "projects": {
+    "your-app": {
+      "architect": {
+        "build": {
+          "options": {
+            "styles": [
+              "node_modules/@vroxal/vd-tokens/dist/index.css",
+              "node_modules/@vroxal/vd-icons/dist/vd-icon.css",
+              "node_modules/@vroxal/vd-angular/styles/style.css",
+              "src/styles.css"
+            ]
+          }
+        }
+      }
+    }
+  }
+}
 ```
 
-## Building
+Without these styles, tokens, icons, and some shared component styles will be missing.
 
-To build the library, run:
+## Quick Start
 
-```bash
-ng build angular-components
+Import standalone components from the package root:
+
+```ts
+import { Component } from '@angular/core';
+import { VdButton, VdInput } from '@vroxal/vd-angular';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [VdButton, VdInput],
+  template: `
+    <vd-input label="Email" placeholder="Enter your email"></vd-input>
+    <vd-button label="Continue"></vd-button>
+  `,
+})
+export class ExampleComponent {}
+```
+
+## NgModule Support
+
+If your app still uses NgModules, import the bundled module:
+
+```ts
+import { NgModule } from '@angular/core';
+import { VdAngularComponentsModule } from '@vroxal/vd-angular';
+
+@NgModule({
+  imports: [VdAngularComponentsModule],
+})
+export class SharedUiModule {}
+```
+
+## Overlay Services
+
+Some library features are used through services instead of direct template composition.
+
+### Toast
+
+Add a single toast host near the app shell:
+
+```html
+<router-outlet></router-outlet> <vd-toast></vd-toast>
+```
+
+Trigger toasts from any injected service consumer:
+
+```ts
+import { Component } from '@angular/core';
+import { VdButton, VdToast, VdToastService } from '@vroxal/vd-angular';
+
+@Component({
+  selector: 'app-toast-example',
+  standalone: true,
+  imports: [VdButton, VdToast],
+  template: `
+    <vd-button label="Show toast" (click)="showToast()"></vd-button>
+    <vd-toast></vd-toast>
+  `,
+})
+export class ToastExampleComponent {
+  constructor(private readonly toastService: VdToastService) {
+    this.toastService.configure({ placement: 'bottom-right', maxStack: 3 });
+  }
+
+  showToast(): void {
+    this.toastService.show({
+      color: 'success',
+      title: 'Saved',
+      description: 'Your changes were saved successfully.',
+    });
+  }
+}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+### Dialog
 
-### Publishing the Library
+`VdDialogService.open()` renders an Angular `TemplateRef` and resolves a promise with `'primary'`, `'secondary'`, or `'close'`.
 
-Once the project is built, you can publish your library by following these steps:
+```ts
+import { Component, TemplateRef, ViewChild } from '@angular/core';
+import { VdButton, VdDialogService, VdInput } from '@vroxal/vd-angular';
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/angular-components
-   ```
+@Component({
+  selector: 'app-dialog-example',
+  standalone: true,
+  imports: [VdButton, VdInput],
+  template: `
+    <ng-template #dialogContent>
+      <vd-input label="Name" placeholder="Enter name"></vd-input>
+    </ng-template>
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+    <vd-button label="Open dialog" (click)="openDialog()"></vd-button>
+  `,
+})
+export class DialogExampleComponent {
+  @ViewChild('dialogContent', { static: true }) dialogContent!: TemplateRef<unknown>;
 
-## Running unit tests
+  constructor(private readonly dialogService: VdDialogService) {}
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+  openDialog(): void {
+    this.dialogService
+      .open({
+        title: 'Edit Details',
+        contentTemplate: this.dialogContent,
+        primaryActionLabel: 'Save',
+        secondaryActionLabel: 'Cancel',
+      })
+      .then((result) => {
+        if (result === 'primary') {
+          // persist changes
+        }
+      });
+  }
+}
+```
+
+### Drawer
+
+`VdDrawerService.open()` also accepts a `TemplateRef` and resolves `'primary'`, `'secondary'`, or `'close'`.
+
+```ts
+this.drawerService.open({
+  title: 'Customer Details',
+  size: 'md',
+  contentTemplate: this.drawerContent,
+  primaryActionLabel: 'Save Changes',
+  secondaryActionLabel: 'Cancel',
+});
+```
+
+Available sizes:
+
+- `'sm'`
+- `'md'`
+- `'lg'`
+
+### Confirmation Dialog
+
+Use `VdConfirmationDialogService` for confirm/cancel flows:
+
+```ts
+this.confirmationDialogService.confirm({
+  title: 'Delete item?',
+  description: 'This action cannot be undone.',
+  color: 'error',
+  confirmLabel: 'Delete',
+  cancelLabel: 'Cancel',
+});
+```
+
+The returned promise resolves to `'confirm'` or `'cancel'`.
+
+## Import Rules
+
+- Import from `@vroxal/vd-angular` only
+- Do not deep-import files from `src/`, `fesm2022/`, or internal folders
+- Prefer the standalone component exports unless your app is still module-based
+
+## Available Component Areas
+
+- Actions: button, icon button, icon, badge
+- Inputs and selection: input, textarea, select, number input, file input, checkbox, checkbox group, radio button, radio group, switch, verification code input
+- Date and time: single date, range date, inline date, date-time, time picker
+- Overlays and feedback: tooltip, dropdown, dialog, drawer, confirmation dialog, toast, alert
+- Navigation and layout: breadcrumb, navbar, sidebar, accordion, divider, tab
+- Data and states: datatable, pagination, progress tracker, empty state, loading state
+
+## Package References
+
+The published package includes usage guidance and the exported API inventory:
+
+- `node_modules/@vroxal/vd-angular/guidelines/COMPONENT_REGISTRY.md`
+- `node_modules/@vroxal/vd-angular/guidelines/USAGE_GUIDELINES.md`
+- `node_modules/@vroxal/vd-angular/guidelines/component-registry.json`
+
+These files are useful if you want the full selector list and service/component reference beyond the quick-start examples above.
+
+## Development
+
+From the workspace root:
 
 ```bash
-ng test
+npm run build:lib
 ```
 
-## Running end-to-end tests
+Or with Angular CLI:
 
-For end-to-end (e2e) testing, run:
+```bash
+ng build angular-components
+```
+
+The packaged output is generated in `dist/angular-components`.
+
+## Testing
+
+Run workspace unit tests from the repo root:
 
 ```bash
-ng e2e
+npm test
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+## Publishing
 
-## Additional Resources
+After building:
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+```bash
+cd dist/angular-components
+npm publish
+```