@vroxal/vd-angular 1.0.1

package/guidelines/COMPONENT_REGISTRY.md

@@ -0,0 +1,94 @@
+# Vroxal Component Registry
+
+Human-readable registry of the exported API in `@vroxal/vd-angular`.
+
+## Source of Truth
+
+- Package: `@vroxal/vd-angular`
+
+## Actions and Display
+
+| Component   | Selector         | Angular Symbol | Primary Usage                        |
+| ----------- | ---------------- | -------------- | ------------------------------------ |
+| Button      | `vd-button`      | `VdButton`     | Primary and secondary actions        |
+| Icon Button | `vd-icon-button` | `VdIconButton` | Icon-only actions                    |
+| Icon        | `vd-icon`        | `VdIcon`       | Contextual/decorative icon rendering |
+| Badge       | `vd-badge`       | `VdBadge`      | Compact status labels and counts     |
+
+## Inputs and Selection
+
+| Component               | Selector                     | Angular Symbol            | Primary Usage                     |
+| ----------------------- | ---------------------------- | ------------------------- | --------------------------------- |
+| Input                   | `vd-input`                   | `VdInput`                 | Single-line text input            |
+| Textarea                | `vd-textarea`                | `VdTextarea`              | Multi-line text input             |
+| Select                  | `vd-select`                  | `VdSelect`                | Single-option selection from list |
+| Number Input            | `vd-number-input`            | `VdNumberInput`           | Numeric entry                     |
+| File Input              | `vd-file-input`              | `VdFileInput`             | File selection/upload input       |
+| Verification Code Input | `vd-verification-code-input` | `VdVerificationCodeInput` | OTP/verification code entry       |
+| Checkbox                | `vd-checkbox`                | `VdCheckbox`              | Independent true/false choice     |
+| Checkbox Group          | `vd-checkbox-group`          | `VdCheckboxGroup`         | Grouped multi-select options      |
+| Radio Button            | `vd-radio-button`            | `VdRadioButton`           | Single option item in radio sets  |
+| Radio Group             | `vd-radio-group`             | `VdRadioGroup`            | Exclusive single-choice selection |
+| Switch                  | `vd-switch`                  | `VdSwitch`                | On/off settings toggles           |
+| Tab                     | `vd-tab`                     | `VdTab`                   | Switching sibling content views   |
+
+## Date and Time
+
+| Component          | Selector                | Angular Symbol       | Primary Usage                              |
+| ------------------ | ----------------------- | -------------------- | ------------------------------------------ |
+| Date Time Picker   | `vd-date-time-picker`   | `VdDateTimePicker`   | Unified date/date-range with optional time |
+| Single Date Picker | `vd-single-date-picker` | `VdSingleDatePicker` | Single date selection                      |
+| Range Date Picker  | `vd-range-date-picker`  | `VdRangeDatePicker`  | Start/end date selection                   |
+| Time Picker        | `vd-time-picker`        | `VdTimePicker`       | Time-only selection                        |
+| Single Date Inline | `vd-single-date-inline` | `VdSingleDateInline` | Inline always-visible single calendar      |
+| Range Date Inline  | `vd-range-date-inline`  | `VdRangeDateInline`  | Inline always-visible range calendar       |
+
+## Overlay and Menus
+
+| Component             | Selector                   | Angular Symbol          | Primary Usage                           |
+| --------------------- | -------------------------- | ----------------------- | --------------------------------------- |
+| Dropdown              | `vd-dropdown`              | `VdDropdown`            | Context/action menu container           |
+| Dropdown Item         | `vd-dropdown-item`         | `VdDropdownItem`        | Action row in dropdown                  |
+| Dropdown Item Link    | `vd-dropdown-item-link`    | `VdDropdownItemLink`    | Link row in dropdown                    |
+| Dropdown Item Divider | `vd-dropdown-item-divider` | `VdDropdownItemDivider` | Visual separator in dropdown            |
+| Dropdown Item Group   | `vd-dropdown-item-group`   | `VdDropdownItemGroup`   | Section grouping in dropdown            |
+| Tooltip               | `vd-tooltip`               | `VdTooltip`             | Tooltip host/content rendering          |
+| Tooltip Directive     | `[vdTooltip]`              | `VdTooltipDirective`    | Attach tooltip to existing element      |
+| Dialog                | `vd-dialog`                | `VdDialog`              | Generic modal dialog                    |
+| Drawer                | `vd-drawer`                | `VdDrawer`              | Side-panel workflows                    |
+| Confirmation Dialog   | `vd-confirmation-dialog`   | `VdConfirmationDialog`  | Confirm destructive/high-impact actions |
+
+## Navigation and Layout
+
+| Component  | Selector        | Angular Symbol | Primary Usage                      |
+| ---------- | --------------- | -------------- | ---------------------------------- |
+| Breadcrumb | `vd-breadcrumb` | `VdBreadcrumb` | Hierarchical path navigation       |
+| Navbar     | `vd-navbar`     | `VdNavbar`     | Top-level app/page navigation bar  |
+| Sidebar    | `vd-sidebar`    | `VdSidebar`    | Persistent side navigation         |
+| Accordion  | `vd-accordion`  | `VdAccordion`  | Collapsible sections               |
+| Divider    | `vd-divider`    | `VdDivider`    | Visual separation between sections |
+
+## Data and Feedback
+
+| Component        | Selector              | Angular Symbol      | Primary Usage                |
+| ---------------- | --------------------- | ------------------- | ---------------------------- |
+| Datatable        | `vd-datatable`        | `VdDatatable`       | Structured tabular data      |
+| Pagination       | `vd-pagination`       | `VdPagination`      | Page navigation for datasets |
+| Alert            | `vd-alert`            | `VdAlert`           | Inline status messaging      |
+| Toast            | `vd-toast`            | `VdToast`           | Transient notification host  |
+| Progress Tracker | `vd-progress-tracker` | `VdProgressTracker` | Multi-step progress state    |
+| Empty State      | `vd-empty-state`      | `VdEmptyState`      | No-content and first-use UX  |
+| Loading State    | `vd-loading-state`    | `VdLoadingState`    | In-progress loading feedback |
+
+## Non-Component Exports
+
+### Modules
+
+- `VdAngularComponentsModule`
+
+### Services
+
+- `VdToastService` (`configure`, `setMaxToasts`, `show`, `dismiss`, `pause`, `resume`)
+- `VdDialogService` (`open`)
+- `VdDrawerService` (`open`)
+- `VdConfirmationDialogService` (`confirm`)

package/guidelines/USAGE_GUIDELINES.md

@@ -0,0 +1,70 @@
+# Vroxal Design System Usage Guidelines
+
+This guide is for agentic AI and developers using `@vroxal/vd-angular`.
+
+## Source of Truth
+
+- Package import path: `@vroxal/vd-angular`
+- Full selector inventory with all the available inputs and outputs: `projects/angular-components/component-registry.json`
+
+## Required Rules
+
+1. If a component exists in the registry, use it instead of building custom UI.
+2. Import only from the package root (`@vroxal/vd-angular`).
+3. Do not override the styles of the components.
+4. Preserve built-in accessibility behavior. Do not override focus handling, keyboard semantics, or ARIA semantics provided by components.
+5. For overlays and transient feedback, prefer service-driven APIs where provided:
+   - `VdToastService` with `<vd-toast>`
+   - `VdDialogService`
+   - `VdDrawerService`
+   - `VdConfirmationDialogService`
+
+## Selection Guide By Intent
+
+- Actions: `vd-button`, `vd-icon-button`
+- Form input: `vd-input`, `vd-textarea`, `vd-select`, `vd-number-input`, `vd-file-input`, `vd-verification-code-input`
+- Choice controls: `vd-checkbox`, `vd-checkbox-group`, `vd-radio-button`, `vd-radio-group`, `vd-switch`, `vd-tab`
+- Date and time: `vd-date-time-picker`, `vd-single-date-picker`, `vd-range-date-picker`, `vd-time-picker`, `vd-single-date-inline`, `vd-range-date-inline`
+- Navigation: `vd-breadcrumb`, `vd-navbar`, `vd-sidebar`, `vd-pagination`
+- Data display and structure: `vd-datatable`, `vd-accordion`, `vd-divider`, `vd-icon`
+- Feedback and status: `vd-alert`, `vd-toast`, `vd-badge`, `vd-progress-tracker`, `vd-empty-state`, `vd-loading-state`
+- Menus, hints, and overlays: `vd-dropdown`, `vd-dropdown-item`, `vd-dropdown-item-link`, `vd-dropdown-item-divider`, `vd-dropdown-item-group`, `vd-tooltip`, `[vdTooltip]`, `vd-dialog`, `vd-drawer`, `vd-confirmation-dialog`
+
+## Feedback Component Notes
+
+- `vd-empty-state`
+  - Use for empty data views, first-use screens, or when guiding users to a next step.
+  - Do not use for loading flows or transient progress.
+- `vd-loading-state`
+  - Use while async content is being fetched or prepared.
+  - Keep messaging concise (`title` required, optional `description`).
+  - Do not use for empty-result or error messaging.
+
+## Import Patterns
+
+Preferred (standalone imports):
+
+```ts
+import { VdButton, VdInput } from '@vroxal/vd-angular';
+```
+
+NgModule bulk import option:
+
+```ts
+import { AngularComponentsModule } from '@vroxal/vd-angular';
+```
+
+## When No Component Exists
+
+When no suitable Vroxal Design component exists, state this explicitly:
+
+`No Vroxal Design component available for this requirement.`
+
+Then build a custom solution using Vroxal Design tokens and document why the existing component set was insufficient.
+
+## Pre-Output Checklist
+
+- Selector/API exists in `component-registry.json`
+- Imports come from `@vroxal/vd-angular`
+- No deep imports
+- Service APIs used for modal/drawer/toast flows when applicable