# NgStarter UI NgStarter UI is an AI-friendly Angular component kit for admin panels and product dashboards. Package: `@ngstarter-ui/components` Angular: 21 Primary docs: https://ngstarter.com AI registry: https://ngstarter.com/ai/component-registry.json ## Usage Rules - Import components from secondary entry points: `@ngstarter-ui/components/`. - Import theme styles once in the app stylesheet. - Use `provideNgsTheme` from `@ngstarter-ui/components/core` for runtime theming. - Prefer `--ngs-*` CSS custom properties when customizing styles. - Treat TailwindCSS utility classes in templates as the primary styling surface for layout, spacing, sizing, flex, grid, alignment, and routine visual styling; prefer classes like `mt-10` and `p-6` over custom SCSS such as `margin-top: 2.5rem` or `padding: 1.5rem`. - Use local SCSS only when TailwindCSS cannot express the styling cleanly, or when overriding CSS custom properties/tokens such as `--ngs-*` component variables. - Put global component style overrides and global CSS variable overrides only in `styles.scss`; for component-scoped overrides, define them in that component's stylesheet so they apply only there. - In component SCSS files, all component-local styling must be nested under the `:host` selector. Do not write top-level component-local selectors outside `:host`. - In component SCSS files, nested element/state styles must use nested SCSS blocks instead of flat descendant selectors. Write `:host-context(.state) { .child { ... } }`, never `:host-context(.state) .child { ... }`; write `:host(.state) { .child { ... } }`, never `:host(.state) .child { ... }`. - Do not set `encapsulation: ViewEncapsulation.None` when creating components unless the user explicitly requests global style encapsulation behavior. - Standalone `ngs-form-field` controls outside forms, such as header, toolbar, or compact filter fields, do not require `ngs-label` when they have clear placeholder text or an `aria-label`/`aria-labelledby` context. Form fields inside actual forms should still use `ngs-label`. - When implementing a screenshot or mockup that shows a chart, build the chart with ECharts in a dedicated standalone component instead of drawing it inline or with ad hoc markup. - When placing an icon or other leading shape inside `ngs-chip`, project it through `ngsChipShape` (or `ngs-chip-shape`) instead of inserting the icon directly in the chip content. - Use `ngs-logo-shape` only for compact square or near-square logo marks/emblems. Do not use it for long wordmark images or full-width brand logos; place those directly inside `ngs-logo` or compose them with `ngs-logo-text`. - Do not import from private `src` paths in application code. ## Setup ```scss @use '@ngstarter-ui/components/styles/themes/default'; ``` ```ts import { provideNgsTheme } from '@ngstarter-ui/components/core'; export const appConfig = { providers: [provideNgsTheme({ theme: 'modern', colorScheme: 'auto' })], }; ``` ## Common Imports ```ts import { Button } from '@ngstarter-ui/components/button'; import { Dialog } from '@ngstarter-ui/components/dialog'; import { Input } from '@ngstarter-ui/components/input'; import { Select } from '@ngstarter-ui/components/select'; import { Table } from '@ngstarter-ui/components/table'; ``` ## Recipes ### admin-dashboard Build admin dashboards from NgStarter UI primitives instead of hand-rolled shell, cards, forms, datatables, static tables, and pagination. Verification: `npm run verify:admin:components` Must use: - `@ngstarter-ui/components/sidenav` - `@ngstarter-ui/components/navigation` - `@ngstarter-ui/components/card` - `@ngstarter-ui/components/data-view` - `@ngstarter-ui/components/table` - `@ngstarter-ui/components/form-field` - `@ngstarter-ui/components/input` - `@ngstarter-ui/components/paginator` - `@ngstarter-ui/components/button` - `@ngstarter-ui/components/icon` - `@ngstarter-ui/components/checkbox` - `@ngstarter-ui/components/progress-bar` Must not: - Do not build datatables or operational admin datasets with role="table", plain table markup, or div grids when DataView fits. - Do not use DataView for purely static/read-only tabular content when ngs-table fits. - Do not build static/read-only tables with role="table" div grids when ngs-table fits. - Do not build search fields with plain input when ngs-form-field and ngsInput fit. - Do not build navigation menus with plain button lists when ngs-navigation fits. - Do not build KPI cards with plain article/div cards when ngs-card fits. - Do not restyle NgStarter components through wrapper-only classes when component selectors and component tokens fit. - Do not make ordinary table rows, labels, descriptions, sidebar items, or status text bold to imitate a screenshot. Typography: - Normal text weights: 400 - Navigation weights: 400 - Button weights: 500, 600 - Heading weights: 600, 650 - Reserve heavy weights for: brand marks, hero headings, primary KPI numbers, deliberate emphasis ## Components - action-required: `@ngstarter-ui/components/action-required` docs: /components/action-required purpose: Prompt users to resolve required account, setup, billing, or workflow actions. use when: Use for dashboard notices that require user action before work can continue. example topics: Basic action required selectors: `ngs-action-required` exports: `ActionRequired` inputs: `actionText`, `buttonText`, `description`, `iconName` outputs: `buttonClicked` tokens: `--ngs-action-action-text-bg`, `--ngs-action-required-bg`, `--ngs-action-text-color`, `--ngs-color-danger-container`, `--ngs-color-danger-container-highest`, `--ngs-color-on-danger-container`, `--ngs-color-surface`, `--ngs-radius-xl` - alert: `@ngstarter-ui/components/alert` docs: /components/alert purpose: Show inline status messages, warnings, errors, confirmations, or contextual notices. use when: Use inside page content when the message should remain visible near the affected workflow. example topics: Basic Alert, Alert Variants, Alert with icon, Alert with title, Alert actions selectors: `[ngsAlertAction]`, `[ngsAlertClose]`, `[ngsAlertIcon]`, `[ngsAlertTitle]`, `ngs-alert`, `ngs-alert-title` exports: `Alert`, `ALERT`, `AlertActionDirective`, `AlertCloseDirective`, `AlertIconDirective`, `AlertTitleDirective`, `AlertVariant` inputs: `autoClose`, `bordered`, `variant` outputs: `closed` tokens: `--ngs-alert-action-border-radius`, `--ngs-alert-action-font-weight`, `--ngs-alert-action-height`, `--ngs-alert-action-hover-bg`, `--ngs-alert-action-hover-color`, `--ngs-alert-action-padding`, `--ngs-alert-action-with-icon-padding`, `--ngs-alert-actions-gap`, `--ngs-alert-bg-color`, `--ngs-alert-border-color`, `--ngs-alert-border-radius`, `--ngs-alert-border-width`, `--ngs-alert-color`, `--ngs-alert-font-size`, `--ngs-alert-gap`, `--ngs-alert-has-thumbnail-padding` - announcement: `@ngstarter-ui/components/announcement` docs: /components/announcement purpose: Show prominent product, system, or marketing announcements with optional title, icon, and actions. use when: Use for broadcast-style messages that should stand apart from normal form or page content. example topics: Show/Hide announcement dynamically, Basic announcement, Announcement with title, Announcement with icons selectors: `[ngsAnnouncementTitle]`, `ngs-announcement`, `ngs-announcement-global` exports: `Announcement`, `AnnouncementData`, `AnnouncementGlobal`, `AnnouncementLinkTo`, `AnnouncementState`, `AnnouncementStore`, `AnnouncementTitle`, `AnnouncementVariant` inputs: `closable`, `iconName`, `linkTo`, `title`, `variant` outputs: `announcementClose`, `closed` tokens: `--ngs-color-danger-container`, `--ngs-color-info-container`, `--ngs-color-on-danger-container`, `--ngs-color-on-info-container`, `--ngs-color-on-secondary-container`, `--ngs-color-on-success-container`, `--ngs-color-on-warning-container`, `--ngs-color-secondary-container`, `--ngs-color-success-container`, `--ngs-color-warning-container`, `--ngs-font-size-sm` - autocomplete: `@ngstarter-ui/components/autocomplete` docs: /forms/autocomplete purpose: Let users search and choose from suggestions while typing. use when: Use for large option lists where a select would be too slow or crowded. example topics: Simple autocomplete, Custom Filter, Separate control and display values, Automatically highlighting the first option, Autocomplete with option groups, Autocomplete filter, Separate controls and display values, Auto highlight first person selectors: `[ngsAutocomplete]`, `ngs-autocomplete` exports: `Autocomplete`, `AutocompleteActivatedEvent`, `AutocompleteSelectedEvent`, `AutocompleteTrigger` inputs: `aria-label`, `aria-labelledby`, `autoActiveFirstOption`, `autoSelectActiveOption`, `class`, `disableRipple`, `hideSingleSelectionIndicator`, `ngsAutocomplete`, `panelWidth`, `requireSelection` outputs: `closed`, `opened`, `optionActivated`, `optionSelected` tokens: `--ngs-autocomplete-panel-bg`, `--ngs-autocomplete-panel-border`, `--ngs-autocomplete-panel-max-height`, `--ngs-autocomplete-panel-padding`, `--ngs-autocomplete-panel-shadow`, `--ngs-dropdown-bg`, `--ngs-dropdown-border`, `--ngs-dropdown-max-height`, `--ngs-dropdown-padding`, `--ngs-dropdown-radius`, `--ngs-dropdown-shadow` - avatar: `@ngstarter-ui/components/avatar` docs: /components/avatar purpose: Represent users, teams, or entities with images, initials, icons, generated key-based avatar appearances, and presence. use when: Use in account menus, lists, comments, assignees, collaborators, and activity feeds. Use the default appearance for normal image, label, or icon avatars. Use appearance="identicon" or appearance="initials" with a stable key for deterministic generated placeholders, optionally with backgroundColors and foregroundColors. Set a global default with provideAvatar({ appearance }) and override individual avatars with appearance="default" when generated placeholders should be disabled. example topics: Basic Avatar, Avatar Variants, Presence Indicator, Avatar Sizes, Avatar With Images, Avatar With Icons, Grouped Avatars, Grouped and Total Avatars selectors: `[ngs-avatar-more]`, `[ngs-avatar-total]`, `[ngs-avatar]`, `ngs-avatar`, `ngs-avatar-group`, `ngs-avatar-more`, `ngs-avatar-total` exports: `Avatar`, `AVATAR_ACCESSOR`, `AVATAR_CONFIG`, `AvatarAppearance`, `AvatarConfig`, `AvatarGenerator`, `AvatarGeneratorOptions`, `AvatarGroup`, `AvatarKey`, `AvatarMore`, `AvatarPresenceIndicator`, `AvatarTotal` inputs: `alt`, `appearance`, `automaticColor`, `backgroundColors`, `clickable`, `foregroundColors`, `image`, `key`, `label`, `presenceIndicator`, `variant` tokens: `--ngs-avatar-bg`, `--ngs-avatar-border-color`, `--ngs-avatar-border-color-auto`, `--ngs-avatar-border-radius`, `--ngs-avatar-border-width`, `--ngs-avatar-color`, `--ngs-avatar-font-weight`, `--ngs-avatar-group-item-border`, `--ngs-avatar-group-item-offset`, `--ngs-avatar-inner-border`, `--ngs-avatar-presence-indicator-away-bg`, `--ngs-avatar-presence-indicator-offline-bg`, `--ngs-avatar-presence-indicator-online-bg`, `--ngs-avatar-presence-indicator-outline`, `--ngs-avatar-presence-indicator-position-end`, `--ngs-avatar-presence-indicator-position-top` - badge: `@ngstarter-ui/components/badge` docs: /components/badge purpose: Attach compact counts, statuses, or labels to another UI element. use when: Use for notification counts, unread states, status dots, or small metadata on icons and avatars. example topics: Basic Badges selectors: `[ngsBadge]`, `ngs-badge-content` exports: `Badge`, `BadgeContent`, `BadgePosition`, `BadgeSize` inputs: `ngsBadge`, `ngsBadgeColor`, `ngsBadgeDescription`, `ngsBadgeDisabled`, `ngsBadgeHidden`, `ngsBadgeOverlap`, `ngsBadgePosition`, `ngsBadgeSize` tokens: `--ngs-badge-background`, `--ngs-badge-background-color`, `--ngs-badge-font-size`, `--ngs-badge-large-size`, `--ngs-badge-size`, `--ngs-badge-small-size`, `--ngs-badge-text-color`, `--ngs-color-danger`, `--ngs-color-on-danger`, `--ngs-color-on-primary`, `--ngs-color-on-secondary`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-secondary`, `--ngs-color-surface-container-high` - block-loader: `@ngstarter-ui/components/block-loader` docs: /components/block-loader purpose: Indicate that a bounded area of the UI is loading while preserving the surrounding page. use when: Use when a panel, table, modal section, or card is refreshing independently. example topics: Basic block loader, Block loader in a dialog, Block loader in modal, _modals selectors: `[ngsBlockLoaderContainer]`, `ngs-block-loader` exports: `BlockLoader`, `BlockLoaderContainerDirective` inputs: `loading`, `spinnerDiameter`, `spinnerStrokeWidth` tokens: `--ngs-block-loader-bg`, `--ngs-font-size-sm` - bottom-sheet: `@ngstarter-ui/components/bottom-sheet` docs: /components/bottom-sheet purpose: Present mobile-friendly contextual actions or short forms from the bottom of the viewport. use when: Use for temporary choices, mobile action menus, and lightweight task flows. example topics: Basic Bottom Sheet, Bottom sheet selectors: `ngs-bottom-sheet-container` exports: `BOTTOM_SHEET_DATA`, `BOTTOM_SHEET_DEFAULT_OPTIONS`, `BottomSheet`, `BottomSheetConfig`, `BottomSheetContainer`, `BottomSheetRef` tokens: `--ngs-bottom-sheet-container-background-color`, `--ngs-bottom-sheet-container-shape`, `--ngs-bottom-sheet-container-text-color` - breadcrumbs: `@ngstarter-ui/components/breadcrumbs` docs: /navigation/breadcrumbs purpose: Show the user's current location in a hierarchy and provide parent navigation. use when: Use in admin sections with nested routes, folders, projects, or record detail pages. example topics: Basic breadcrumbs, Breadcrumbs with icons, Breadcrumbs with titles, Breadcrumbs with datasource, Breadcrumbs with last item as link, Breadcrumbs global (set breadcrumbs dynamically), Breadcrumbs global selectors: `[ngs-breadcrumb-item]`, `[ngsBreadcrumbActiveItemDef]`, `[ngsBreadcrumbItemDef]`, `[ngsBreadcrumbItemIcon]`, `[ngsBreadcrumbItemIconDef]`, `[ngsBreadcrumbItemNameDef]`, `[ngsBreadcrumbItemTitleDef]`, `[ngsBreadcrumbSeparatorDef]`, `ngs-breadcrumb-item`, `ngs-breadcrumb-separator`, `ngs-breadcrumb-title`, `ngs-breadcrumbs`, `ngs-breadcrumbs-global` exports: `Breadcrumb`, `BreadcrumbActiveItemDefDirective`, `BreadcrumbItem`, `BreadcrumbItemDefDirective`, `BreadcrumbItemIconDefDirective`, `BreadcrumbItemIconDirective`, `BreadcrumbItemNameDefDirective`, `BreadcrumbItemTitleDefDirective`, `Breadcrumbs`, `BreadcrumbSeparator`, `BreadcrumbSeparatorDefDirective`, `BreadcrumbsGlobal` inputs: `dataSource`, `lastItemAsLink`, `separator` tokens: `--ngs-breadcrumbs-active-item-color`, `--ngs-breadcrumbs-gap`, `--ngs-breadcrumbs-item-color`, `--ngs-breadcrumbs-item-font-size`, `--ngs-breadcrumbs-item-font-weight`, `--ngs-breadcrumbs-item-hover-color`, `--ngs-breadcrumbs-separator-color`, `--ngs-breadcrumbs-separator-font-size`, `--ngs-breadcrumbs-separator-position-top`, `--ngs-breadcrumbs-title-color`, `--ngs-breadcrumbs-title-font-size`, `--ngs-color-neutral-400`, `--ngs-color-neutral-800`, `--ngs-color-primary`, `--ngs-color-secondary`, `--ngs-font-size-md` - button: `@ngstarter-ui/components/button` docs: /forms/buttons purpose: Trigger actions with filled, outlined, text, tonal, loading, disabled, and icon button states. use when: Use for commands, form submission, toolbar actions, and navigation-like calls to action. example topics: Basic Button, Outlined Button, Tonal Button, Flat Button, Icon Button, Button Loading, Hide text on mobile, Interactive disabled buttons selectors: `a[ngsButton]`, `a[ngsIconButton]`, `button[ngsButton]`, `button[ngsIconButton]` exports: `Button`, `ButtonVariant` inputs: `disabled`, `disabledInteractive`, `disableRipple`, `fullWidth`, `hideTextOnMobile`, `loading`, `ngsButton`, `ngsIconButton`, `reverse` tokens: `--ngs-button-bg`, `--ngs-button-border-radius`, `--ngs-button-color`, `--ngs-button-content-gap`, `--ngs-button-filled-bg`, `--ngs-button-filled-color`, `--ngs-button-font-size`, `--ngs-button-font-weight`, `--ngs-button-height`, `--ngs-button-hover-bg`, `--ngs-button-outlined-border`, `--ngs-button-outlined-color`, `--ngs-button-padding`, `--ngs-button-padding-x`, `--ngs-button-radius`, `--ngs-button-tonal-bg` - button-toggle: `@ngstarter-ui/components/button-toggle` docs: /forms/button-toggle purpose: Let users choose one or more options from a compact segmented button group. use when: Use for mode switching, view density, filters, or mutually exclusive short choices. example topics: Basic Button Toggle, Icon Only Button Toggle, Selection Mode, Button toggle selection mode selectors: `ngs-button-toggle`, `ngs-button-toggle-group` exports: `ButtonToggle`, `ButtonToggleAppearance`, `ButtonToggleGroup` inputs: `appearance`, `checked`, `disabled`, `hideSelectionIndicator`, `id`, `multiple`, `name`, `onlyIcon`, `value`, `vertical` outputs: `change` tokens: `--ngs-button-height`, `--ngs-button-radius`, `--ngs-button-toggle-button-font-size`, `--ngs-button-toggle-button-font-weight`, `--ngs-button-toggle-button-only-icon-padding`, `--ngs-button-toggle-button-padding`, `--ngs-button-toggle-checked-bg-color`, `--ngs-button-toggle-checked-text-color`, `--ngs-button-toggle-group-bg`, `--ngs-button-toggle-group-border-color`, `--ngs-button-toggle-group-border-radius`, `--ngs-button-toggle-hover-bg-color`, `--ngs-button-toggle-selection-indicator-color`, `--ngs-button-toggle-text-color`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant` - calendar: `@ngstarter-ui/components/calendar` docs: /components/calendar purpose: The NgStarter Angular Calendar component renders an inline month calendar for dashboards, scheduling widgets, event summaries, availability previews, and date-driven product surfaces. use when: Choose Calendar when the workflow matches examples such as Basic Calendar, Calendar With Events, Calendar With Min And Max Dates, Calendar min max. example topics: Basic Calendar, Calendar With Events, Calendar With Min And Max Dates, Calendar min max selectors: `ngs-calendar` exports: `Calendar`, `CalendarDateInput`, `CalendarEvent`, `CalendarEventColor` inputs: `events`, `firstDayOfWeek`, `locale`, `maxDate`, `minDate`, `selected`, `showAdjacentDays`, `showEventTitles`, `showTodayButton`, `startAt` outputs: `eventSelected`, `monthChange`, `selectedChange` tokens: `--ngs-button-bg`, `--ngs-button-border-radius`, `--ngs-button-height`, `--ngs-button-padding`, `--ngs-button-padding-x`, `--ngs-calendar-day-bg`, `--ngs-calendar-day-hover-bg`, `--ngs-calendar-day-min-height`, `--ngs-calendar-day-muted-color`, `--ngs-calendar-day-radius`, `--ngs-calendar-day-selected-bg`, `--ngs-calendar-day-selected-color`, `--ngs-calendar-day-today-outline`, `--ngs-calendar-event-blue`, `--ngs-calendar-event-danger`, `--ngs-calendar-event-green` - card: `@ngstarter-ui/components/card` docs: /components/card purpose: Group related content, controls, media, and actions in a bordered or elevated container. use when: Use for repeated dashboard widgets, previews, summaries, or compact content modules. example topics: Basic Card, Card Appearance, Card Actions, Card Multiple Sections, Card Footer Loading selectors: `[ngs-card-actions]`, `[ngs-card-aside]`, `[ngs-card-avatar]`, `[ngs-card-content]`, `[ngs-card-footer]`, `[ngs-card-image]`, `[ngs-card-lg-image]`, `[ngs-card-md-image]`, `[ngs-card-sm-image]`, `[ngs-card-subtitle]`, `[ngs-card-title]`, `[ngs-card-xl-image]`, `[ngsCardActions]`, `[ngsCardAvatar]`, `[ngsCardContent]`, `[ngsCardFooter]`, `[ngsCardImage]`, `[ngsCardImageLarge]`, `[ngsCardImageMedium]`, `[ngsCardImageSmall]`, `[ngsCardImageXLarge]`, `[ngsCardSubtitle]`, `[ngsCardTitle]`, `ngs-card`, `ngs-card-actions`, `ngs-card-aside`, `ngs-card-avatar`, `ngs-card-content`, `ngs-card-footer`, `ngs-card-header`, `ngs-card-image`, `ngs-card-subtitle`, `ngs-card-title`, `ngsCardAside` exports: `Card`, `CARD_CONFIG`, `CardActions`, `CardActionsPosition`, `CardAppearance`, `CardAside`, `CardAvatar`, `CardConfig`, `CardContent`, `CardFooter`, `CardHeader`, `CardImage` inputs: `align`, `appearance`, `withoutPadding` tokens: `--ngs-card-bg`, `--ngs-card-border-color`, `--ngs-card-color`, `--ngs-card-content-font-size`, `--ngs-card-content-letter-spacing`, `--ngs-card-content-line-height`, `--ngs-card-padding`, `--ngs-card-radius`, `--ngs-card-shadow`, `--ngs-card-subtitle-color`, `--ngs-card-subtitle-font-size`, `--ngs-card-subtitle-font-weight`, `--ngs-card-subtitle-letter-spacing`, `--ngs-card-subtitle-line-height`, `--ngs-card-title-font-size`, `--ngs-card-title-font-weight` - card-overlay: `@ngstarter-ui/components/card-overlay` docs: /components/card-overlay purpose: Reveal overlay content or actions on top of a card-like surface, often on hover or interaction. use when: Use for media cards, galleries, previews, and quick actions over visual content. example topics: Basic card overlay, Card overlay with translate, Card overlay with blur selectors: `[ngsCardOverlayContainer]`, `ngs-card-overlay` exports: `CardOverlay`, `CardOverlayContainerDirective` inputs: `disabled`, `withBlur`, `withTranslate` - carousel: `@ngstarter-ui/components/carousel` docs: /components/carousel purpose: Display a sequence of slides or panels that users can browse horizontally. use when: Use for featured content, image galleries, onboarding panels, or compact previews. example topics: Basic Carousel, Carousel controls with custom position, Carousel with fade effect, Carousel controls custom position, Carousel fade effect selectors: `[ngs-carousel-card]`, `[ngsCarouselControls]`, `[ngsCarouselNext]`, `[ngsCarouselPrevious]`, `[ngsDraggableCarousel]`, `ngs-carousel`, `ngs-carousel-card` exports: `Carousel`, `CAROUSEL`, `CAROUSEL_CARD`, `CarouselApiInterface`, `CarouselCard`, `CarouselCardInterface`, `CarouselControlsDirective`, `CarouselInterface`, `CarouselNextDirective`, `CarouselPreviousDirective`, `DraggableCarouselDirective` inputs: `cardSelector`, `carousel`, `fade`, `resistanceFactor`, `snapDebounceTime`, `snapDuration`, `snapToCenter`, `stopPropagation`, `velocityThreshold`, `visibilityDebounceTime` outputs: `indexChange` tokens: `--ngs-carousel-gap` - checkbox: `@ngstarter-ui/components/checkbox` docs: /forms/checkbox purpose: Capture independent boolean choices or multi-select options. use when: Use for forms, preferences, tables, and filter groups where multiple values can be selected. example topics: Basic Checkboxes, Checkbox with Description, Checkbox Group, Checkbox description selectors: `[ngsCheckboxDescription]`, `ngs-checkbox`, `ngs-checkbox-group` exports: `Checkbox`, `CheckboxChange`, `CheckboxDescription`, `CheckboxGroup`, `TransitionCheckState` inputs: `aria-controls`, `aria-describedby`, `aria-expanded`, `aria-label`, `aria-labelledby`, `aria-owns`, `checked`, `color`, `disabled`, `disabledInteractive`, `disableRipple`, `id`, `indeterminate`, `labelPosition`, `name`, `required`, `tabIndex`, `value` outputs: `change`, `indeterminateChange` tokens: `--ngs-checkbox-checked-color`, `--ngs-checkbox-checkmark-color`, `--ngs-checkbox-description-color`, `--ngs-checkbox-description-font-size`, `--ngs-checkbox-disabled-color`, `--ngs-checkbox-gap`, `--ngs-checkbox-group-gap`, `--ngs-checkbox-label-font-size`, `--ngs-checkbox-size`, `--ngs-checkbox-unchecked-color`, `--ngs-color-danger`, `--ngs-color-neutral-500`, `--ngs-color-on-danger`, `--ngs-color-on-primary`, `--ngs-color-on-secondary`, `--ngs-color-on-surface` - chips: `@ngstarter-ui/components/chips` docs: /components/chips purpose: Display compact tokens for tags, selected values, filters, or removable items. use when: Use for tag entry, selected people/items, active filters, and small categorical metadata. example topics: Basic Chips, Chips Appearance, Chips With Input, Chips Autocomplete, Chips With Icons, Chips Drag and Drop, Stacked Chips selectors: `[ngsChipAvatar]`, `[ngsChipControl]`, `[ngsChipEdit]`, `[ngsChipRemove]`, `[ngsChipShape]`, `input[ngsChipInputFor]`, `ngs-chip`, `ngs-chip-avatar`, `ngs-chip-edit`, `ngs-chip-grid`, `ngs-chip-listbox`, `ngs-chip-option`, `ngs-chip-remove`, `ngs-chip-row`, `ngs-chip-set`, `ngs-chip-shape` exports: `Chip`, `ChipAvatar`, `ChipControl`, `ChipEdit`, `ChipEditedEvent`, `ChipGrid`, `ChipInput`, `ChipInputEvent`, `ChipListbox`, `ChipOption`, `ChipRemove`, `ChipRow` inputs: `appearance`, `disabled`, `editable`, `id`, `multiple`, `ngsChipInputAddOnBlur`, `ngsChipInputFor`, `placeholder`, `required`, `selected`, `value` outputs: `chipInputTokenEnd`, `destroyed`, `edited`, `removed`, `selectionChange`, `valueChange` tokens: `--ngs-avatar-size`, `--ngs-chip-background`, `--ngs-chip-border-color`, `--ngs-chip-color`, `--ngs-chip-font-size`, `--ngs-chip-font-weight`, `--ngs-chip-height`, `--ngs-chip-input-height`, `--ngs-chip-listbox-gap`, `--ngs-chip-outline-color`, `--ngs-chip-padding`, `--ngs-chip-radius`, `--ngs-chip-selected-background`, `--ngs-chip-selected-color`, `--ngs-chip-set-gap`, `--ngs-chip-set-spacing` - code-highlighter: `@ngstarter-ui/components/code-highlighter` docs: /components/code-highlighter purpose: Render formatted source code snippets with syntax highlighting. use when: Use in docs, developer tools, examples, and configuration previews. example topics: Basic Code Highlighter, With Title, Diff, Highlight Lines, With Language and Copy, Code highlighter with title, Code highlighter diff, Code highlighter highlight lines selectors: `ngs-code-highlighter` exports: `CodeHighlighter` inputs: `appearance`, `code`, `diff`, `disableOverflow`, `highlightLines`, `language`, `showCopyButton`, `showLanguage`, `theme`, `title` tokens: `--ngs-code-highlighter-bg`, `--ngs-code-highlighter-border`, `--ngs-code-highlighter-margin`, `--ngs-code-highlighter-padding`, `--ngs-code-highlighter-radius`, `--ngs-code-highlighter-title-color`, `--ngs-code-highlighter-title-padding`, `--ngs-color-background`, `--ngs-color-border`, `--ngs-color-danger`, `--ngs-color-neutral-500`, `--ngs-color-primary`, `--ngs-color-success`, `--ngs-font-size-sm`, `--ngs-font-size-xs`, `--ngs-radius-xl` - color-picker: `@ngstarter-ui/components/color-picker` docs: /components/color-picker purpose: Let users choose or edit a color value. use when: Use in branding, theme customization, design tools, and visual editors. example topics: Basic Color Picker, Color Picker With Popover, Input With Color Picker selectors: `[inputChange]`, `[ngs-color-picker-thumbnail]`, `[ngsColorPickerTriggerFor]`, `ngs-alpha`, `ngs-color-picker`, `ngs-color-picker-thumbnail`, `ngs-hue`, `ngs-saturation` exports: `Alpha`, `BaseComponent`, `ChunksPipe`, `ColorPicker`, `ColorPickerInputDirective`, `ColorPickerPosition`, `ColorPickerResultFormat`, `ColorPickerThumbnail`, `ColorPickerTriggerForDirective`, `Hue`, `PositionManager`, `ReversePipe` inputs: `asDropdown`, `color`, `colorFromHue`, `disabled`, `max`, `min`, `position`, `resultFormat`, `showOpacity`, `tinyColor` outputs: `alphaChange`, `closed`, `colorChange`, `inputChange`, `opened`, `rawColorChange` tokens: `--ngs-color-picker-alpha-height`, `--ngs-color-picker-alpha-pointer-border`, `--ngs-color-picker-alpha-pointer-shadow`, `--ngs-color-picker-alpha-pointer-size`, `--ngs-color-picker-alpha-width`, `--ngs-color-picker-as-dropdown-shadow`, `--ngs-color-picker-bg`, `--ngs-color-picker-border`, `--ngs-color-picker-border-radius`, `--ngs-color-picker-gap`, `--ngs-color-picker-hue-height`, `--ngs-color-picker-hue-pointer-border`, `--ngs-color-picker-hue-pointer-shadow`, `--ngs-color-picker-hue-pointer-size`, `--ngs-color-picker-hue-width`, `--ngs-color-picker-margin-offset` - color-scheme: `@ngstarter-ui/components/color-scheme` purpose: Switch the application color scheme between light, dark, and auto. use when: Use anywhere in the UI where users need to control the global light, dark, or auto theme mode. Do not use it for brand colors, accent colors, object colors, statuses, or palettes. selectors: `[ngsColorSchemeAuto]`, `[ngsColorSchemeDark]`, `[ngsColorSchemeLight]`, `ngs-color-scheme-switcher` exports: `COLOR_SCHEME_LOCAL_KEY`, `ColorScheme`, `ColorSchemeAutoDirective`, `ColorSchemeDarkDirective`, `ColorSchemeLightDirective`, `ColorSchemeStore`, `ColorSchemeSwitcher`, `ResolvedColorScheme` outputs: `colorSchemeChanged` - color-switcher: `@ngstarter-ui/components/color-switcher` docs: /components/color-switcher purpose: Let users choose one color from a fixed allowed palette. use when: Use for brand color presets, accent color presets, project colors, category colors, tag colors, tenant branding, and theme playground controls. Use ColorPicker for arbitrary custom colors and ColorScheme for light, dark, or auto theme mode. example topics: Basic Color Switcher, Custom Palette, Disabled State, Form Control, Basic brand colors, Brand colors custom colors, Brand colors disabled, Brand colors as form control selectors: `ngs-color-switcher` exports: `ColorSwitcher` inputs: `colors`, `disabled`, `selectedColor` outputs: `colorChange` tokens: `--ngs-brand-colors-color-size`, `--ngs-brand-colors-gap`, `--ngs-shadow-sm` - command-bar: `@ngstarter-ui/components/command-bar` docs: /components/command-bar purpose: Show a floating contextual action bar for selected items or temporary page state. use when: Use when rows, files, cards, canvas objects, or other page items are selected and users need quick actions such as edit, delete, archive, move, export, or share. Do not use it as a command palette, search UI, dropdown menu, header toolbar, navigation bar, autocomplete, or normal form action row. example topics: Basic Command Bar selectors: `[ngs-command-bar-command]`, `ngs-command-bar`, `ngs-command-bar-command`, `ngs-command-bar-divider` exports: `CommandBar`, `CommandBarCommand`, `CommandBarDivider`, `CommandBarPosition` inputs: `open`, `position`, `shortcut` tokens: `--ngs-color-neutral-100`, `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-600`, `--ngs-color-neutral-700`, `--ngs-color-neutral-800`, `--ngs-color-neutral-950`, `--ngs-color-primary-200`, `--ngs-command-bar-bg`, `--ngs-command-bar-border`, `--ngs-command-bar-border-radius`, `--ngs-command-bar-color`, `--ngs-command-bar-command-color`, `--ngs-command-bar-command-font-size`, `--ngs-command-bar-command-gap`, `--ngs-command-bar-command-height` - comment-editor: `@ngstarter-ui/components/comment-editor` docs: /components/comment-editor purpose: Provide a simplified text editor for quick messages, comments, threads, and replies. use when: Use in tasks, projects, activity feeds, reviews, support threads, and conversation replies where users write a short or medium message and send it immediately. Do not use for long-form documents, CMS pages, complex content editing, markdown editing, code editing, search, or display-only comments. example topics: Basic Comment Editor, Toolbar Always Visible, Cancel Button Always Visible, Custom Button Labels, Full View Mode, Upload Error, Max Content Height, Custom Icons selectors: `[ngsCommentEditorCommand]`, `[ngsCommentEditorCommandBlockquote]`, `[ngsCommentEditorCommandBold]`, `[ngsCommentEditorCommandBulletList]`, `[ngsCommentEditorCommandCode]`, `[ngsCommentEditorCommandCodeBlock]`, `[ngsCommentEditorCommandEditLink]`, `[ngsCommentEditorCommandImage]`, `[ngsCommentEditorCommandItalic]`, `[ngsCommentEditorCommandLink]`, `[ngsCommentEditorCommandOrderedList]`, `[ngsCommentEditorCommandStrike]`, `[ngsCommentEditorCommandToggleToolbar]`, `[ngsCommentEditorCommandUnsetLink]`, `[ngsCommentEditorCommandYoutube]`, `ngs-comment-editor`, `ngs-comment-editor-bubble-menu`, `ngs-comment-editor-divider`, `ngs-comment-editor-footer-bar`, `ngs-comment-editor-toolbar`, `ngs-image-uploading-placeholder`, `ngs-link`, `ngs-youtube` exports: `AngularNodeView`, `AngularNodeViewRenderer`, `AngularRenderer`, `COMMENT_EDITOR`, `COMMENT_EDITOR_BUBBLE_MENU`, `CommentEditor`, `CommentEditorAPI`, `CommentEditorBubbleMenu`, `CommentEditorCommandBlockquoteDirective`, `CommentEditorCommandBoldDirective`, `CommentEditorCommandBulletListDirective`, `CommentEditorCommandCodeBlockDirective` inputs: `allowEmptyContent`, `autoClear`, `buttonCancelLabel`, `buttonSendLabel`, `cancelButtonAlwaysVisible`, `contentMaxHeight`, `decorations`, `deleteNode`, `editor`, `extension`, `fullViewMode`, `getPos`, `innerDecorations`, `loading`, `node`, `placeholder`, `selected`, `toolbarAlwaysVisible`, `updateAttributes`, `view` outputs: `canceled`, `fileSelected`, `sent` tokens: `--ngs-color-border`, `--ngs-color-neutral-100`, `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-500`, `--ngs-color-neutral-650`, `--ngs-color-neutral-700`, `--ngs-color-neutral-900`, `--ngs-color-neutral-950`, `--ngs-color-primary`, `--ngs-color-tertiary-100`, `--ngs-color-tertiary-200`, `--ngs-color-tertiary-300`, `--ngs-color-tertiary-700`, `--ngs-color-tertiary-800`, `--ngs-comment-editor-bg` - comparison-slider: `@ngstarter-ui/components/comparison-slider` docs: /components/comparison-slider purpose: Compare two aligned visual layers with a draggable before-and-after divider. use when: Use for before-and-after images, photo edits, design changes, product variations, UI state diffs, image processing results, maps, reports, and other visual diffs. Give the component a stable width and height or aspect ratio, and do not use it as a gallery, carousel, image viewer, range input, data comparison table, or text comparison tool. example topics: Basic Comparison Slider selectors: `[ngsComparisonSliderAfterImage]`, `[ngsComparisonSliderBeforeImage]`, `ngs-comparison-slider` exports: `ComparisonSlider`, `ComparisonSliderAfterImageDirective`, `ComparisonSliderBeforeImageDirective` inputs: `initialPosition` - confirm: `@ngstarter-ui/components/confirm` docs: /components/confirm purpose: Show a standardized confirmation dialog for a short binary decision before an important action. use when: Use through ConfirmManager.open({ title, description }) before delete, unpublish, archive, reset, discard changes, leave with unsaved changes, bulk, destructive, irreversible, or high-impact operations. Do not use for long forms, custom modal layouts, wizards, informational dialogs, settings panels, or choices with more than two outcomes; use Dialog for custom modal content. example topics: Basic Confirm, Confirm From Dialog, Confirm form modal, Dialog with confirmation selectors: `ngs-confirm` exports: `Confirm`, `ConfirmManager`, `ConfirmOptions`, `ConfirmRef` - content-editor: `@ngstarter-ui/components/content-editor` docs: /libraries/content-editor purpose: Provide a block-based builder for structured long-form content. use when: Use ngs-content-editor-builder for articles, pages, documentation, knowledge base entries, rich notes, editable descriptions, landing content, and CMS-like editing workflows built from blocks such as paragraph, heading, list, quote, code, divider, table, image, video, and embed. Use ngs-content-editor-renderer for saved block previews and display-only content. Do not use for quick messages, comments, threads, or reply composers; use CommentEditor for that. Do not use for a simple text field or small rich text input; use TextEditor, Input, or Textarea depending on the task. example topics: Content Editor selectors: `[ngsBlockSelection]`, `[ngsContentChangesObserver]`, `[ngsContentEditorContentEditable]`, `[ngsContentObserver]`, `[ngsFocusMonitor]`, `[ngsTableColumnsManager]`, `[ngsTableRowsManager]`, `[ngsTextSelectionPopup]`, `app-embed-block`, `ngs-add-link`, `ngs-audio-recorder`, `ngs-code-block`, `ngs-command-bar`, `ngs-content-editor-builder`, `ngs-content-editor-code-renderer`, `ngs-content-editor-divider-renderer`, `ngs-content-editor-embed-renderer`, `ngs-content-editor-heading-renderer`, `ngs-content-editor-image-renderer`, `ngs-content-editor-list-renderer`, `ngs-content-editor-paragraph-renderer`, `ngs-content-editor-quote-renderer`, `ngs-content-editor-renderer`, `ngs-content-editor-table-renderer`, `ngs-content-editor-video-renderer`, `ngs-divider-block`, `ngs-draggable-table`, `ngs-edit-link`, `ngs-heading-block`, `ngs-image-block`, `ngs-list-block`, `ngs-paragraph-block`, `ngs-quote-block`, `ngs-table-block`, `ngs-text-color`, `ngs-video-block`, `table[ngsResizableTable]` exports: `AddLinkDialog`, `AudioRecorderComponent`, `BaseErrorHandler`, `BlockSelectionDirective`, `Change`, `Changeset`, `CodeBlockComponent`, `CodeBlockDef`, `CommandBarComponent`, `compare`, `CONTENT_BUILDER`, `CONTENT_EDITOR_BLOCK` inputs: `_alt`, `_caption`, `_settings`, `autoScrollContainerSelector`, `backgroundColors`, `block`, `blockSelector`, `captionPlaceholder`, `closestContentObserverClass`, `content`, `contentChangedDelay`, `detectAddedNode`, `disabled`, `id`, `ignoreClasses`, `index`, `insertAtCursor`, `minColumnWidth`, `mutationObserverDebounceTime`, `ngsContentEditorContentEditable`, `observedElement`, `options`, `persistDraft`, `placeholder` outputs: `backgroundColorChanged`, `columnAdded`, `columnDeleted`, `columnManagingEnd`, `columnManagingStart`, `columnMoved`, `columnWidthChange`, `columnWidthChangeEnd`, `columnWidthChangeStart`, `contentChanged`, `displayTranscriptChange`, `initialized`, `moveEnd`, `moveStart`, `nodeAdded`, `pressedEnter`, `propsChanged`, `rowAdded`, `rowDeleted`, `rowManagingEnd`, `rowManagingStart`, `rowMoved`, `tagSelected`, `textColorChanged` tokens: `--ngs-color-border`, `--ngs-color-neutral-200`, `--ngs-color-neutral-50`, `--ngs-color-neutral-500`, `--ngs-color-neutral-600`, `--ngs-color-on-surface`, `--ngs-color-primary`, `--ngs-color-primary-100`, `--ngs-color-primary-300`, `--ngs-color-primary-400`, `--ngs-color-secondary-fixed`, `--ngs-color-surface-container`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-highest`, `--ngs-color-surface-container-low`, `--ngs-content-editor-builder-content-width` - content-fade: `@ngstarter-ui/components/content-fade` docs: /components/content-fade purpose: Add a visual gradient fade at the edge of clipped or scrollable content. use when: Use for horizontal preview text, teaser rows, chips, compact lists, or cropped inline content when an edge should fade out instead of ending abruptly. The parent container must provide width, height, scroll behavior, or overflow-hidden; ContentFade does not manage overflow, expansion, truncation, or scrolling by itself. Do not use for loading skeletons, collapsed content logic, tooltips, pagination, modal clipping, ellipsis truncation, or long article reading. example topics: Basic Content Fade, Custom Width, Custom Position, Content fade custom width, Content fade custom position selectors: `ngs-content-fade` exports: `ContentFade`, `ContentFadePosition` inputs: `color`, `position`, `width` tokens: `--ngs-color-background`, `--ngs-content-fade-color`, `--ngs-content-fade-width` - cookie-popup: `@ngstarter-ui/components/cookie-popup` docs: /components/cookie-popup purpose: Collect a non-blocking cookie or privacy consent choice. use when: Use on public pages or apps when users need to accept all cookies or only necessary cookies and see a short cookie/privacy message with a policy link. The consumer must persist the accepted choice in a cookie, localStorage, or backend and control visible state. Do not use as a normal Dialog, Alert, Announcement, snackbar, or settings panel. example topics: Basic Cookie Popup selectors: `[ngsCookiePopupAcceptAllButton]`, `[ngsCookiePopupAcceptNecessaryOnlyButton]`, `[ngsCookiePopupTitle]`, `ngs-cookie-popup` exports: `CookiePopup`, `CookiePopupAcceptAllButtonDirective`, `CookiePopupAcceptNecessaryOnlyButtonDirective`, `CookiePopupAcceptType`, `CookiePopupTitleDirective` inputs: `cookiePolicyUrl`, `visible` outputs: `cookieAccepted` tokens: `--ngs-color-surface-container-lowest`, `--ngs-font-size-sm`, `--ngs-radius-xl`, `--ngs-shadow-lg` - core: `@ngstarter-ui/components/core` purpose: Provide infrastructure primitives, theme setup, services, directives, pipes, tokens, and low-level utilities. use when: Use @ngstarter-ui/components/core for infrastructure, not for building screens directly. Use provideNgsTheme in app config to set theme, colorScheme, radius, primaryColor, persistence, and storageKey. Inject ThemeManagerService for runtime theme, color scheme, radius, and primary color changes. Use utility directives such as ngsRipple, ngsAutoFocus, ngsFocusElement, ngsTextareaAutoSize, and ngsDebounceTime when a specific low-level behavior is needed. Use pipes such as InitialsPipe, FormatFileSizePipe, SafeHtmlPipe, SafeResourceUrlPipe, OrderByPipe, FilterByPropertyPipe, and SearchByPropertyPipe when they fit. Use ErrorStateMatcher or ShowOnDirtyErrorStateMatcher for form error behavior, and observer/services/utils only for low-level infrastructure. Do not use core as a replacement for real UI components. Do not build admin screens from core primitives; choose concrete components such as Button, Card, DataView, Table, FormField, Dialog, Navigation, Layout, or other component entry points. Do not import Option from core directly for ordinary option lists when Select, Autocomplete, or another component owns the option pattern. selectors: `[ngsAutoFocus]`, `[ngsDebounceTime][ngModel]`, `[ngsFocusElement]`, `[ngsRipple]`, `[ngsSoundEffect]`, `ngs-optgroup`, `ngs-option`, `textarea[ngsTextareaAutoSize]` exports: `_Option`, `_OptionParent`, `AnalyticsService`, `arrayShallowEquals`, `Autofocusable`, `AUTOFOCUSABLE`, `AutoFocusDirective`, `DebounceTimeDirective`, `defaultRippleAnimationConfig`, `ENVIRONMENT`, `EnvironmentService`, `ErrorStateMatcher` inputs: `checkChildren`, `debounceTime`, `disabled`, `label`, `maxRows`, `minRows`, `ngsAutoFocus`, `ngsRippleAnimation`, `ngsRippleCentered`, `ngsRippleColor`, `ngsRippleDisabled`, `ngsRippleRadius`, `ngsRippleTrigger`, `ngsRippleUnbounded`, `selected`, `soundSrc`, `value` outputs: `elementBlurred`, `elementFocused`, `onSelectionChange` tokens: `--ngs-color-on-primary-container`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary-container`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-highest`, `--ngs-control-radius`, `--ngs-dropdown-height`, `--ngs-dropdown-item-active-bg`, `--ngs-dropdown-item-color`, `--ngs-dropdown-item-disabled-color`, `--ngs-dropdown-item-font-size`, `--ngs-dropdown-item-gap`, `--ngs-dropdown-item-hover-bg`, `--ngs-dropdown-item-nested-padding-start`, `--ngs-dropdown-item-padding` - country-select: `@ngstarter-ui/components/country-select` docs: /forms/country purpose: Let users choose a country from the built-in country list and store its ISO country code. use when: Use in addresses, user profiles, billing, shipping, legal forms, tax forms, tenant settings, and locale settings where the form value should be a country code such as US, PL, or DE. The component shows country flags and names, supports search by name or ISO code, and integrates with FormField. Do not use for phone dialing codes; use PhoneInput. Do not use for currency selection; use CurrencySelect. Do not use for custom region, city, office, or location lists; use Select or Autocomplete. example topics: Unselected country, Basic country select, Unselected country select selectors: `ngs-country-select` exports: `countries`, `Country`, `CountrySelect`, `CountrySelectValue` inputs: `aria-describedby`, `aria-label`, `clearable`, `disabled`, `hideCheckIcon`, `id`, `multiple`, `placeholder`, `required`, `searchTerm`, `showCountryCode`, `tabIndex`, `value` outputs: `closed`, `opened`, `selectionChange` tokens: `--ngs-color-neutral-500`, `--ngs-color-on-surface-variant`, `--ngs-dropdown-item-gap`, `--ngs-font-size-sm` - crop: `@ngstarter-ui/components/crop` docs: /components/crop purpose: Let users choose a rectangle or circle crop area on top of an existing image or visual preview. use when: Use for avatar dialogs, cover image forms, thumbnail preparation, media management screens, and content editor flows where the user chooses the visible crop area. Crop emits selectionApplied with pixel coordinates, percentages, and container size. It does not upload files, save images, zoom the image, open a gallery, compare images, or process the final bitmap; handle those steps outside the component. example topics: Basic image crop selectors: `ngs-crop` exports: `Crop`, `CropSelection` inputs: `minHeight`, `minWidth`, `shape` outputs: `selectionApplied` - currency-select: `@ngstarter-ui/components/currency-select` docs: /forms/currency-select purpose: Let users choose a currency from the built-in currency list and store its ISO currency code. use when: Use for billing, pricing, invoices, checkout, marketplace, finance settings, reporting settings, tenant settings, and locale settings where the form value should be a currency code such as USD, EUR, or PLN. The component shows a flag, ISO code, and symbol, supports search by currency name or code, and can show country names with showCountryName. Do not use for country selection; use CountrySelect. Do not use for entering a money amount; pair it with Input/FormField. Do not use for exchange calculators, rate tables, or number formatting. example topics: Basic currency select, Currency select with country name, Currency with country name selectors: `ngs-currency-select` exports: `currencies`, `Currency`, `CurrencySelect` inputs: `disabled`, `placeholder`, `required`, `searchTerm`, `showCountryName` outputs: `closed`, `opened` tokens: `--ngs-color-neutral-500`, `--ngs-color-on-surface-variant`, `--ngs-dropdown-item-gap`, `--ngs-font-size-sm` - data-view: `@ngstarter-ui/components/data-view` docs: /libraries/data-view purpose: Build operational data grids for records that users need to inspect, organize, select, and act on. use when: Use for datatables and working data surfaces in admin screens, CRM and ERP records, users, orders, invoices, logs, tasks, assets, and any dataset where the table is the main interactive work surface. Choose DataView when users need row actions, selection, sorting, search/filter state, pagination, loading or empty states, column resizing, column visibility/order, pinned or sticky columns, custom cell renderers, refresh, snapshots, server-side data, or ngsDataViewActionBar. DataView is configured with columnDefs plus local data or a server-side datasource. Do not use for small static tables or simple read-only tabular content; use Table. Do not use as a card list, layout grid, chart widget, report summary, or form editor. example topics: Basic dataview, Data view column pinning, Data view column settings, Data view custom cell renderers, Data view custom empty state, Data view embedded, Data view filter data, Data view height test selectors: `[ngsDataViewActionBar]`, `[ngsDataViewEmptyData]`, `[ngsDataViewEmptyFilterResults]`, `ngs-data-view`, `ngs-data-view-action-bar`, `ngs-data-view-column-settings-dialog` exports: `cellRenderer`, `ColumnSettingsDialogData`, `ColumnSettingsDialogResult`, `DATA_VIEW`, `DATA_VIEW_CONFIG`, `DataView`, `DataViewActionBar`, `DataViewActionBarAPI`, `DataViewActionBarDirective`, `DataViewAPI`, `DataViewCellRenderer`, `DataViewCellRendererDef` inputs: `allowSingleRowSelectionByClick`, `autoHeight`, `bodyScroll`, `bufferRows`, `cellRenderers`, `columnDefs`, `data`, `datasource`, `embedded`, `emptyFilterResultsIcon`, `emptyFilterResultsText`, `emptyIcon`, `emptyText`, `forceVisible`, `headerHeight`, `highlightHeader`, `hoverRows`, `loading`, `minColumnWidth`, `ngsDataViewActionBarWidth`, `pageIndex`, `pageSize`, `pageSizeOptions`, `paginator` outputs: `allRowsSelectionChanged`, `loadEnd`, `refreshEnd`, `selectionChanged`, `sortChange` tokens: `--ngs-color-background`, `--ngs-color-border`, `--ngs-color-neutral-500`, `--ngs-color-on-background`, `--ngs-color-primary`, `--ngs-color-surface-container`, `--ngs-color-surface-container-low`, `--ngs-content-fade-color`, `--ngs-data-view-bg`, `--ngs-data-view-body-bg`, `--ngs-data-view-border-color`, `--ngs-data-view-cell-padding`, `--ngs-data-view-header-bg`, `--ngs-data-view-header-height`, `--ngs-data-view-hl-header-row-bg`, `--ngs-data-view-min-height` - date-format-select: `@ngstarter-ui/components/date-format-select` docs: /forms/date-format-select purpose: Let users choose a preferred date display format string from a predefined list. use when: Use in account settings, profile settings, tenant settings, localization preferences, and reporting settings where users choose how dates should appear in the UI or exported reports. The form value is a format string such as MM/dd/yyyy, dd.MM.yyyy, or yyyy-MM-dd; override the available options with dateFormats when needed. Do not use to pick an actual date; use Datepicker. Do not use for date ranges, calendars, schedules, period filters, or direct date formatting in a template. example topics: Basic date format select selectors: `ngs-date-format-select` exports: `DateFormat`, `DateFormatSelect` inputs: `dateFormats`, `placeholder` - datepicker: `@ngstarter-ui/components/datepicker` docs: /components/datepicker purpose: Let users choose a concrete date or date range through an input connected to a calendar overlay. use when: Use input[ngsDatepicker], ngs-datepicker, and usually ngs-datepicker-toggle for single date fields in forms, filters, deadlines, birth dates, publish dates, schedules, reporting, invoices, and order dates. Use ngs-date-range-input with ngs-date-range-picker for start/end ranges, report periods, booking windows, analytics ranges, and quick presets. The form value is a date object handled by the configured DateAdapter, not a date format string. Do not use to choose a date display format; use DateFormatSelect. Do not use to choose only a time; use Timepicker. Do not use as a static event calendar, scheduler, timeline, or date formatter. example topics: Basic Datepicker, Datepicker With Custom Icon, Datepicker With Custom Header, Datepicker Action Buttons, Basic Date Range Picker, Extended Date Range Picker, Date Range Picker With Quick Presets, Datepicker custom icon selectors: `[ngsDatepickerApply]`, `[ngsDatepickerCancel]`, `[ngsDatepickerToggleIcon]`, `input[ngsDatepicker]`, `input[ngsEndDate]`, `input[ngsStartDate]`, `ngs-calendar`, `ngs-date-range-input`, `ngs-date-range-picker`, `ngs-datepicker`, `ngs-datepicker-actions`, `ngs-datepicker-toggle`, `ngs-month-view`, `ngs-multi-year-view`, `ngs-year-view` exports: `Calendar`, `DateAdapter`, `Datepicker`, `DatepickerActions`, `DatepickerApply`, `DatepickerCancel`, `DatepickerInput`, `DatepickerIntl`, `DatepickerPreset`, `DatepickerToggle`, `DatepickerToggleIcon`, `DateRange` inputs: `activeDate`, `calendarCount`, `extended`, `maxDate`, `minDate`, `rangePreviewDate`, `selected`, `separator`, `sharedRangePreview`, `showQuickPresets`, `startAt`, `visibleCalendars` outputs: `monthSelected`, `rangePreviewDateChange`, `selectedChange`, `yearSelected` tokens: `--ngs-calendar-cell-hover-bg`, `--ngs-calendar-cell-in-range-bg`, `--ngs-calendar-cell-radius`, `--ngs-calendar-cell-selected-bg`, `--ngs-calendar-cell-selected-color`, `--ngs-calendar-cell-size`, `--ngs-calendar-cell-today-border`, `--ngs-calendar-header-padding`, `--ngs-calendar-padding`, `--ngs-color-border`, `--ngs-color-on-primary`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-outline`, `--ngs-color-primary`, `--ngs-color-primary-container` - dialog: `@ngstarter-ui/components/dialog` docs: /components/dialog purpose: Open custom focused modal workflows above the current page. use when: Use Dialog.open(ComponentOrTemplate, config) for forms, editing records, creating objects, settings, detail views, wizard-like steps, scrollable content, and custom modal workflows where users must complete or close the task before returning to the page. Structure custom dialog components with ngs-dialog-title, ngs-dialog-content, ngs-dialog-actions, DialogRef.close(...), ngs-dialog-close, and optional DIALOG_DATA. Use DialogConfig for data, sizing, disableClose, autofocus, backdrop, panel classes, accessibility labels, and showCloseButton when the dialog should render the built-in icon close button. Do not use for a short binary destructive confirmation; use Confirm. Do not use for global messages; use Announcement, Alert, or SnackBar. Do not use for mobile bottom action panels; use BottomSheet. Do not use for side inspectors, filters, or detail panels; use Drawer or SidePanel. example topics: Basic Dialog, Dialog Close, Dialog With Scrollable Content, Dialog Sizing (height, min-height), Dialog scrollable content, Dialog sizing, Basic selectors: `[ngs-dialog-actions]`, `[ngs-dialog-close]`, `[ngs-dialog-content]`, `[ngs-dialog-title]`, `[ngsDialogActions]`, `[ngsDialogClose]`, `[ngsDialogContent]`, `[ngsDialogTitle]`, `ngs-dialog-actions`, `ngs-dialog-container`, `ngs-dialog-content`, `ngs-dialog-header`, `ngs-dialog-title` exports: `Dialog`, `DIALOG_DATA`, `DIALOG_DEFAULT_OPTIONS`, `DialogActions`, `DialogClose`, `DialogConfig`, `DialogContainer`, `DialogContent`, `DialogHeader`, `DialogRef`, `DialogTitle` inputs: `align`, `ariaLabel`, `id`, `ngs-dialog-close`, `ngsDialogClose`, `type` config options: `data`, `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`, `hasBackdrop`, `backdropClass`, `panelClass`, `disableClose`, `autoFocus`, `restoreFocus`, `ariaDescribedBy`, `ariaLabelledBy`, `ariaLabel`, `role`, `closeOnNavigation`, `showCloseButton` tokens: `--ngs-color-on-surface`, `--ngs-control-height-lg`, `--ngs-dialog-actions-gap`, `--ngs-dialog-actions-padding`, `--ngs-dialog-background`, `--ngs-dialog-bg`, `--ngs-dialog-border-radius`, `--ngs-dialog-box-shadow`, `--ngs-dialog-color`, `--ngs-dialog-container-max-width`, `--ngs-dialog-container-min-width`, `--ngs-dialog-header-padding`, `--ngs-dialog-headline-padding`, `--ngs-dialog-radius`, `--ngs-dialog-shadow`, `--ngs-dialog-title-font-size` - digit-roller: `@ngstarter-ui/components/digit-roller` docs: /components/digit-roller purpose: The NgStarter Angular Digit Roller component animates individual digits in formatted numbers with a slot-machine style reel effect. use when: Choose Digit Roller when the workflow matches examples such as Number Sizes, Social Actions, Progress Bar, Gauge, Digit roller dashboard. example topics: Number Sizes, Social Actions, Progress Bar, Gauge, Digit roller dashboard, Digit roller social actions, Digit roller progress bar, Digit roller gauge selectors: `[ngsDigitRollerGroup]`, `ngs-digit-roller` exports: `canAnimateDigitRoller`, `DIGIT_ROLLER_EMPTY_FORMATTED`, `DIGIT_ROLLER_GROUP`, `DigitRoller`, `DigitRollerCapabilityOptions`, `DigitRollerDigitConfig`, `DigitRollerDigits`, `DigitRollerEasing`, `DigitRollerFormattedNumber`, `DigitRollerGlyph`, `DigitRollerGroupCoordinator`, `DigitRollerGroupDirective` inputs: `animated`, `colorOnDecrease`, `colorOnIncrease`, `continuous`, `digits`, `duration`, `flipEasing`, `format`, `locales`, `opacityDuration`, `opacityTiming`, `prefix`, `respectMotionPreference`, `spinEasing`, `spinTiming`, `stagger`, `suffix`, `transformTiming`, `trend`, `value` outputs: `animationsFinish`, `animationsStart` tokens: `--ngs-digit-roller-mask-height`, `--ngs-digit-roller-mask-width`, `--ngs-digit-roller-min-digit-width` - divider: `@ngstarter-ui/components/divider` docs: /components/divider purpose: Separate related groups of content or actions with a visual rule. use when: Use ngs-divider in lists, forms, panels, cards, toolbars, popovers, settings screens, and dense layouts where a clear boundary between groups helps scanning. Use vertical dividers between inline actions or columns, horizontal dividers between sections, inset when the line should align with content, and fixedHeight for compact vertical dividers. Use ngs-text-divider when the separator needs a short label such as “or”. Do not use Divider to create empty space or layout structure; use Tailwind spacing and layout classes. Prefer specialized divider components inside systems that provide them, such as MenuDivider, NavigationDivider, SidebarDivider, and CommandBarDivider. example topics: Basic Divider, Text Divider, Divider overview selectors: `ngs-divider`, `ngs-text-divider` exports: `Divider`, `TextDivider` inputs: `fixedHeight`, `inset`, `vertical` tokens: `--ngs-color-border`, `--ngs-divider-vertical-fixed-height` - drawer: `@ngstarter-ui/components/drawer` docs: /components/drawer purpose: Show custom side content in a right-side overlay while keeping the current page as context. use when: Use for any secondary side content or workflow that should open beside the current screen without navigating away: forms, filters, record details, settings, previews, history, activity feeds, help content, quick actions, inspectors, or other custom panels. Open with #drawer="ngsDrawer" and drawer.open()/drawer.close(), or control with [isOpen]. Use [showBackdrop]="false" for a non-blocking side panel. Do not use for centered modal workflows; use Dialog. Do not use for short confirmations; use Confirm. Do not use for mobile bottom action panels; use BottomSheet. Do not use as the primary persistent app navigation; use navigation/sidebar components. example topics: Basic drawer, Drawer without backdrop selectors: `[ngsDrawerIgnoreOutsideClick]`, `ngs-drawer` exports: `Drawer`, `DRAWER`, `DrawerIgnoreOutsideClickDirective` inputs: `isOpen`, `showBackdrop` outputs: `closed`, `opened` tokens: `--ngs-color-surface-container-lowest`, `--ngs-drawer-transition`, `--ngs-drawer-transition-duration`, `--ngs-dropdown-border` - emoji-picker: `@ngstarter-ui/components/emoji-picker` docs: /components/emoji-picker purpose: Let users choose one Unicode emoji from an overlay picker. use when: Use in comments, chats, quick messages, reactions, comment/editor toolbars, social features, and any text entry flow where users need to insert or choose an emoji. Open from a button or toolbar action with [ngsEmojiPickerTriggerFor], then handle emojiSelected as the selected emoji string. It supports categorized emoji data, language from LOCALE_ID or the language input, hover preview, and loading skeletons. Do not use for interface icons; use Icon. Do not use for normal action menus; use Menu. Do not use as a full editor; use CommentEditor or TextEditor. Do not use for custom stickers, GIFs, or media pickers unless the value is a Unicode emoji. example topics: Basic emoji picker selectors: `[ngsEmojiPickerTriggerFor]`, `ngs-emoji-picker` exports: `EMOJI_PICKER_TRIGGER_FOR`, `EmojiPicker`, `EmojiPickerTriggerForDirective` inputs: `language`, `position`, `selectEmojiLabel` outputs: `closed`, `emojiSelected`, `opened` tokens: `--ngs-color-neutral-500`, `--ngs-color-subtle`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-highest`, `--ngs-color-surface-container-low`, `--ngs-color-surface-container-lowest`, `--ngs-dropdown-bg`, `--ngs-dropdown-border`, `--ngs-dropdown-radius`, `--ngs-dropdown-shadow`, `--ngs-emoji-picker-bg`, `--ngs-emoji-picker-border`, `--ngs-emoji-picker-border-radius`, `--ngs-emoji-picker-list-height`, `--ngs-emoji-picker-list-width`, `--ngs-emoji-picker-margin` - empty-state: `@ngstarter-ui/components/empty-state` docs: /components/empty-state purpose: Explain why an expected content area is empty and optionally offer a next action. use when: Use for empty tables, lists, folders, dashboard sections, first-run screens, no search results, no filtered data, no projects yet, no messages yet, and similar no-content states. Compose with ngs-empty-state, ngs-empty-state-title, ngs-empty-state-content, optional ngs-empty-state-icon or ngs-empty-state-image, and ngs-empty-state-actions for useful next steps such as Create, Clear filters, Invite, or Upload. In DataView, prefer EmptyState inside empty templates for custom dataset empty states. Do not use for loading states; use BlockLoader, Skeleton, or ProgressSpinner. Do not use for critical errors; use Alert or ActionRequired. Do not use as a decorative placeholder, hero block, or marketing section. example topics: Basic empty state, Empty state with image, Empty state with icon, Empty state with custom icon, Empty state with actions selectors: `[ngs-empty-state-title]`, `ngs-empty-state`, `ngs-empty-state-actions`, `ngs-empty-state-content`, `ngs-empty-state-icon`, `ngs-empty-state-image`, `ngs-empty-state-title` exports: `EmptyState`, `EmptyStateActions`, `EmptyStateContent`, `EmptyStateIcon`, `EmptyStateImage`, `EmptyStateTitle` tokens: `--ngs-color-neutral-500`, `--ngs-color-neutral-600`, `--ngs-color-surface-container`, `--ngs-empty-state-padding`, `--ngs-empty-state-title-font-size`, `--ngs-empty-state-title-font-weight`, `--ngs-font-size-sm`, `--ngs-icon-size` - events: `@ngstarter-ui/components/events` docs: /components/events purpose: The NgStarter Angular Events components let you build grouped schedule lists with day markers, event cards, inline statuses, time ranges, status tones, and attendee actions. use when: Choose Events when the workflow matches examples such as Basic Events, Weekly Grouping, Weekly events. example topics: Basic Events, Weekly Grouping, Weekly events selectors: `[ngs-event-date]`, `[ngs-event-description]`, `[ngs-event-status]`, `[ngs-event-time]`, `[ngs-event-title]`, `[ngsEventActions]`, `ngs-event`, `ngs-event-date`, `ngs-event-description`, `ngs-event-status`, `ngs-event-time`, `ngs-event-title`, `ngs-events-list`, `ngs-events-section` exports: `Event`, `EventActionsDirective`, `EventDate`, `EventDescription`, `EventsList`, `EventsListGroupBy`, `EventsSection`, `EventStatus`, `EventTime`, `EventTitle`, `EventTone` inputs: `day`, `groupBy`, `label`, `tone`, `weekday` tokens: `--ngs-color-border`, `--ngs-color-danger`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-success`, `--ngs-color-warning`, `--ngs-event-bg`, `--ngs-event-border-color`, `--ngs-event-date-border-color`, `--ngs-event-date-day-color`, `--ngs-event-date-day-font-size`, `--ngs-event-date-day-font-weight`, `--ngs-event-date-divider-height`, `--ngs-event-date-height`, `--ngs-event-date-weekday-color` - expand: `@ngstarter-ui/components/expand` docs: /components/expand purpose: Collapse one long content block to a limited-height preview with a fade and show-more control. use when: Use for long descriptions, comments, changelog entries, release notes, activity text, terms snippets, card descriptions, and compact summaries where the page should stay scannable but users can reveal the full content inline. Supports expanded, expandedChange, height, color, expandLabel, collapseLabel, and showButtonIfExpanded. Do not use for independent collapsible sections; use ExpansionPanel or accordion. Do not use for hierarchical expandable nodes; use Tree. Do not use for read-more navigation to another page, tabs, steppers, form disclosure logic, or as a generic container/card. example topics: Basic Expand, Show button if expanded, Custom button labels, Expand show button if expanded, Expand custom button labels selectors: `ngs-expand` exports: `Expand` inputs: `collapseLabel`, `color`, `expanded`, `expandLabel`, `height`, `showButtonIfExpanded` outputs: `expandedChange` tokens: `--ngs-color-background`, `--ngs-color-on-surface`, `--ngs-color-surface-container`, `--ngs-color-surface-container-high`, `--ngs-expand-button-bg`, `--ngs-expand-button-border-radius`, `--ngs-expand-button-box-shadow`, `--ngs-expand-button-color`, `--ngs-expand-button-font-size`, `--ngs-expand-button-hover-bg`, `--ngs-expand-button-hover-opacity`, `--ngs-expand-button-padding`, `--ngs-expand-expanded-height`, `--ngs-expand-fade-color`, `--ngs-shadow-md` - expansion: `@ngstarter-ui/components/expansion` docs: /components/expansion-panel purpose: Group independent collapsible sections with headers and bodies. use when: Use ngs-expansion-panel for one collapsible section and ngs-accordion for a coordinated group of panels. Use for settings groups, FAQs, advanced options, filters, grouped form sections, detail sections, onboarding or setup steps, and inspector groups where each section has its own title and content. Supports expanded, expandedChange, opened, closed, disabled, hideToggle, ngs-expansion-panel-header, ngs-expansion-panel-title, ngs-expansion-panel-description, ngs-action-row, accordion multi, openAll(), and closeAll(). Do not use to truncate one long text block; use Expand. Do not use for hierarchical nodes; use Tree. Do not use as tabs, a strict stepper flow, or a plain card/container without collapse behavior. example topics: Basic Expansion Panel, Expansion Panel with expand/collapse all toggles, Expansion Panel as Accordion, Expansion panel expand collapse toggles selectors: `ngs-accordion`, `ngs-action-row`, `ngs-expansion-panel`, `ngs-expansion-panel-description`, `ngs-expansion-panel-header`, `ngs-expansion-panel-title` exports: `Accordion`, `ActionRow`, `ExpansionPanel`, `ExpansionPanelDescription`, `ExpansionPanelHeader`, `ExpansionPanelTitle` inputs: `disabled`, `expanded`, `hideToggle`, `multi` outputs: `closed`, `expandedChange`, `opened` tokens: `--ngs-color-neutral-300`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-subtle`, `--ngs-color-surface`, `--ngs-expansion-panel-background`, `--ngs-expansion-panel-color`, `--ngs-expansion-panel-content-padding`, `--ngs-expansion-panel-description-color`, `--ngs-expansion-panel-disabled-color`, `--ngs-expansion-panel-divider-color`, `--ngs-expansion-panel-header-expanded-height`, `--ngs-expansion-panel-header-height`, `--ngs-expansion-panel-radius`, `--ngs-radius-xl` - file-type: `@ngstarter-ui/components/file-type` docs: /components/file-type purpose: The NgStarter Angular File Type component renders built-in SVG file icons from a MIME type, extension, or file name. use when: Choose File Type when the workflow matches examples such as Basic File Type, Icon Sizes, MIME Type Detection, File Type Gallery, File type sizes. example topics: Basic File Type, Icon Sizes, MIME Type Detection, File Type Gallery, File type sizes, File type mime selectors: `ngs-file-type` exports: `FileType`, `FileTypeName` inputs: `decorative`, `extension`, `fallback`, `fileName`, `label`, `mimeType` tokens: `--ngs-file-type-size` - filter-builder: `@ngstarter-ui/components/filter-builder` docs: /components/filter-builder purpose: Let users construct a structured tree of filtering rules from fields, operations, and values. use when: Use for advanced filters, saved views, report builders, admin datasets, CRM or ERP records, audit logs, catalogs, product filtering, and segmentation workflows where a simple search field is not enough. Configure fields with fieldDefs using dataField, name, dataType, optional lookup, and filterOperations. Users can build conditions and nested groups with and/or, and valueChanged emits FilterBuilderGroup[]. The app must translate that emitted tree into an API query, SQL or DSL condition, DataView datasource params, or local filtering logic. Do not use for ordinary text search; use Input or a search field. Do not use for a simple table filter string; use DataView/Table filtering. Do not use as a data-editing form, query-language editor, chart filter chip bar, or full report builder with visualizations. example topics: Basic filter builder selectors: `[ngsFilterBuilderOperationDef]`, `[ngsFilterBuilderOperationIcon]`, `[ngsFilterBuilderOperationName]`, `ngs-filter-builder` exports: `FilterBuilder`, `FilterBuilderCondition`, `FilterBuilderFieldDataSourceItem`, `FilterBuilderFieldDef`, `FilterBuilderGroup`, `FilterBuilderItemType`, `FilterBuilderOperationDefDirective`, `FilterBuilderOperationIconDirective`, `FilterBuilderOperationNameDirective` inputs: `allowedDataTypes`, `categories`, `customOperations`, `fieldDefs`, `groupOperations`, `ngsFilterBuilderOperationDef`, `value` outputs: `valueChanged` tokens: `--ngs-color-border`, `--ngs-color-danger`, `--ngs-color-neutral-100`, `--ngs-color-neutral-200`, `--ngs-color-neutral-50`, `--ngs-color-neutral-600`, `--ngs-color-neutral-650`, `--ngs-color-on-primary`, `--ngs-color-on-primary-container`, `--ngs-color-on-secondary`, `--ngs-color-on-secondary-container`, `--ngs-color-on-surface`, `--ngs-color-primary`, `--ngs-color-primary-400`, `--ngs-color-primary-container`, `--ngs-color-secondary` - form-builder: `@ngstarter-ui/components/form-builder` docs: /libraries/form-builder purpose: The NgStarter Angular Form Builder library provides a drag-and-drop form designer, schema model, runtime renderer, and provider registration API for custom field types and field-specific settings. use when: Choose Form Builder when the workflow matches examples such as Basic form builder, Custom field registration, External renderer flow, Form builder renderer. example topics: Basic form builder, Custom field registration, External renderer flow, Form builder renderer selectors: `ngs-basic-form-builder-field-settings`, `ngs-basic-form-builder-layout-settings`, `ngs-basic-form-builder-section-settings`, `ngs-form-builder`, `ngs-form-builder-field-host`, `ngs-form-builder-settings-host`, `ngs-form-logic`, `ngs-form-renderer`, `ngs-plain-text-form-builder-settings` exports: `asyncValidatorsFromRules`, `BasicFormBuilderFieldSettings`, `BasicFormBuilderLayoutSettings`, `BasicFormBuilderSectionSettings`, `createDefaultFormBuilderSchema`, `DEFAULT_FORM_BUILDER_CALCULATION_ENGINE`, `DEFAULT_FORM_BUILDER_FIELDS`, `DEFAULT_FORM_BUILDER_ITEMS`, `DEFAULT_FORM_BUILDER_LOGIC_ENGINE`, `DEFAULT_FORM_BUILDER_VALIDATORS`, `FORM_BUILDER_CALCULATION_ENGINE`, `FORM_BUILDER_FIELD_BASE_SETTINGS_SCHEMA` inputs: `canvasDropPlaceholderDelay`, `control`, `definitions`, `description`, `editableCanvas`, `field`, `flow`, `inspectorTitle`, `items`, `logic`, `paletteTitle`, `readonly`, `schema`, `section`, `settingsDefinitions`, `showSubmit`, `submitLabel`, `title`, `uploadCallback` outputs: `fieldAdded`, `fieldRemoved`, `fieldSelected`, `formReady` tokens: `--ngs-alert-border-radius`, `--ngs-avatar-font-weight`, `--ngs-avatar-size`, `--ngs-card-padding`, `--ngs-color-border`, `--ngs-color-danger`, `--ngs-color-on-primary-container`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-outline-variant`, `--ngs-color-primary`, `--ngs-color-primary-container`, `--ngs-color-surface`, `--ngs-color-surface-container-lowest`, `--ngs-field-container-height`, `--ngs-field-font-size` schema format: - FormBuilderSchema shape: { title?: string; fields?: FormBuilderField[]; layout?: FormBuilderLayoutItem[]; sections: FormBuilderSection[] }. - Root-level fields live in schema.fields and can be placed outside sections. Sections live in schema.sections and contain section.fields. The optional schema.layout array controls top-level canvas order with items like { kind: "field" | "section", id }. - FormBuilderSection shape: { id: string; title: string; description?: string; collapsed?: boolean; fields: FormBuilderField[] }. - FormBuilderField shape: { id: string; name: string; type: string; kind?: "field" | "layout" | "static"; label: string; placeholder?: string; hint?: string; defaultValue?: any; width?: 1..12; multiple?: boolean; clearable?: boolean; required?: boolean; disabled?: boolean; readonly?: boolean; options?: FormBuilderOption[]; validation?: FormBuilderValidationRule[]; settings?: Record; children?: FormBuilderField[] }. - Layout blocks are represented as fields with kind: "layout". The built-in group block uses type: "group", width: 12, and children: FormBuilderField[]. Section is a top-level FormBuilderSection, not a child field, and should not be nested inside another section/group. - Static blocks are represented as fields with kind: "static". The built-in spacer block uses type: "spacer", width: 12, and settings.height with one of 8, 16, 24, 32, 48, or 64. - Use width as a 12-column span. Default fields are 12 columns unless a narrower width is set. Nested children in group are sorted and rendered inside that group container. - Option fields use options entries { label: string; value: any; selected?: boolean }. For select, multiple controls array values; clearable enables the clear action. For radio, settings.orientation is "vertical" by default and can be "horizontal". Hidden fields use type: "hidden" and render as native controls included in raw form values. Date and time fields include type: "date" for a single date, type: "time" for HH:mm time values, and type: "date-range" for a DateRange-like value with start/end dates. Upload fields use type: "upload", multiple for File[] values, and settings.accept for comma-separated MIME types such as "*/*" or "image/*,application/pdf". Upload handling can be provided with [uploadCallback] on ngs-form-builder/ngs-form-renderer or globally through provideFormBuilder({ uploadCallback }). The callback receives { field, control, event, files, fileList, multiple } and may return sync/async value stored in the form control. - Use from @ngstarter-ui/components/form-builder to render a saved FormBuilderSchema as a runtime form. The Angular class export is FormRenderer. - Register custom placeholders through provideFormBuilder({ fields/items/settings }) using formBuilderField(), formBuilderItem(), and formBuilderSettings(). Custom field definitions can provide defaults, renderer, settings, validators, acceptsChildren, group, icon, and kind. - form-field: `@ngstarter-ui/components/form-field` purpose: Wrap one form control with the standard NgStarter field layout, label, hint, error, and prefix/suffix slots. use when: Use one ngs-form-field around one form control: input ngsInput, textarea ngsInput, ngs-select, ngs-autocomplete input, datepicker input, CountrySelect, CurrencySelect, DateFormatSelect, PhoneInput, NumberInput, and custom controls that implement FormFieldControl. Use ngs-label for labels, ngs-hint for helper text, ngs-error for validation messages, and ngsIconPrefix/ngsIconButtonPrefix/ngsTextPrefix/ngsIconSuffix/ngsIconButtonSuffix/ngsTextSuffix for field adornments. For groups of fields, use TailwindCSS grid/flex/layout classes around multiple form fields; each individual control still gets its own ngs-form-field. Do not use ngs-form-field as a layout container, card, spacing wrapper, or wrapper around non-form UI. Do not wrap checkbox, radio, button, or toggle controls when they have their own label pattern. selectors: `[ngsIconButtonPrefix]`, `[ngsIconButtonSuffix]`, `[ngsIconPrefix]`, `[ngsIconSuffix]`, `[ngsPrefix]`, `[ngsSuffix]`, `[ngsTextPrefix]`, `[ngsTextSuffix]`, `ngs-error`, `ngs-form-field`, `ngs-hint`, `ngs-label` exports: `Error`, `FORM_FIELD`, `FORM_FIELD_DEFAULT_OPTIONS`, `FormField`, `FormFieldControl`, `FormFieldDefaultOptions`, `Hint`, `IconButtonPrefix`, `IconButtonSuffix`, `IconPrefix`, `IconSuffix`, `Label` inputs: `align`, `sameHeightAsButton`, `subscriptHiddenIfEmpty` tokens: `--ngs-button-height`, `--ngs-field-bg`, `--ngs-field-border-color`, `--ngs-field-border-focus-color`, `--ngs-field-border-width`, `--ngs-field-color`, `--ngs-field-container-height`, `--ngs-field-disabled-bg`, `--ngs-field-error-color`, `--ngs-field-font-size`, `--ngs-field-height`, `--ngs-field-infix-padding-bottom`, `--ngs-field-infix-padding-top`, `--ngs-field-input-height`, `--ngs-field-label-color`, `--ngs-field-label-float-font-size` - gauge: `@ngstarter-ui/components/gauge` docs: /components/gauge purpose: Visualize one compact 0–100 percentage-like value as a circular radial metric. use when: Use in dashboard cards, sidebar widgets, KPI panels, usage or quota blocks, storage usage, completion score, health score, capacity, and utilization indicators. Use ngs-gauge-value to show a number or short label inside the gauge, and customize size with Tailwind size classes or strokeWidth/radius. Do not use for linear process progress; use ProgressBar. Do not use for loading; use ProgressSpinner, BlockLoader, or Skeleton. Do not use for full analytical charts with axes, legends, multiple series, or trends. Do not use for small table-row statuses; use Badge or Status. example topics: Basic Gauge, Gauge With Value, Gauge Custom Size, Gauge Custom Stroke Width selectors: `ngs-gauge`, `ngs-gauge-value` exports: `Gauge`, `GaugeValue` inputs: `radius`, `strokeWidth`, `value` tokens: `--ngs-color-neutral-300`, `--ngs-color-neutral-600`, `--ngs-color-neutral-700`, `--ngs-color-primary`, `--ngs-gauge-bg`, `--ngs-gauge-fill`, `--ngs-gauge-size`, `--ngs-gauge-value-color` - grid: `@ngstarter-ui/components/grid` docs: /components/grid purpose: Render static dashboard widgets in a predefined 12-column layout. use when: Use ngs-grid when the application defines a static dashboard or widget layout and users do not need to rearrange, customize, or save the dashboard order. Provide configs that map item types to components and items with id, type, columns, optional responsive columnsSm/columnsMd/columnsLg/columnsXl, height, optional responsive heightSm/heightMd/heightLg/heightXl, content, skeletonHeight, and children. Widgets can inject GRID and call markItemAsLoaded(id), especially with waitWhenAllItemsLoaded. Use Grid for fixed analytics sections, portal start pages, and nested dashboard sections where the structure is known. Do not use Grid as a normal CSS layout helper for forms, pages, cards, or repeated elements; use TailwindCSS grid/flex classes. Do not use Grid for dashboards users can rearrange or change; use Tiles. Do not use for tables or datasets; use Table or DataView. Do not use for file/media grids; use upload/media components. selectors: `ngs-grid` exports: `Grid`, `GRID`, `GridItem`, `GridItemAware`, `GridItemConfig` inputs: `configs`, `items`, `plain`, `waitWhenAllItemsLoaded` tokens: `--ngs-color-border`, `--ngs-grid-gap`, `--ngs-grid-item-colspan`, `--ngs-grid-item-colspan-lg`, `--ngs-grid-item-colspan-md`, `--ngs-grid-item-colspan-sm`, `--ngs-grid-item-colspan-xl`, `--ngs-grid-item-effective-colspan`, `--ngs-grid-item-effective-height`, `--ngs-grid-item-height`, `--ngs-grid-item-height-lg`, `--ngs-grid-item-height-md`, `--ngs-grid-item-height-sm`, `--ngs-grid-item-height-xl`, `--ngs-grid-item-skeleton-min-height`, `--ngs-radius-xl` - guided-tour: `@ngstarter-ui/components/guided-tour` docs: /components/guided-tour purpose: Guide users through the real UI with ordered steps attached to existing elements. use when: Use for first-run onboarding, feature discovery, setup guidance, new feature education, and complex screen walkthroughs where each step points at a real element through ngsTourAnchor, a selector, or an element callback. Use withBackdrop to highlight the current element, waitFor for dynamic content, route for tours that continue across pages, and template/htmlContent for richer step content. Do not use for simple hover hints; use Tooltip. Do not use for anchored menus or arbitrary floating content; use Popover. Do not use for confirmations or modal workflows; use Confirm or Dialog. Do not use for form wizards or multi-step data entry; use Stepper or HeadlessStepper. Do not use for documentation pages or marketing onboarding screens; use normal page content. example topics: Basic Guided Tour, Backdrop Guided Tour, Wait For Guided Tour, Close On Backdrop Click, HTML and Template Support, Custom Buttons, Global Configuration, Keyboard Navigation selectors: `[ngsTourAnchor]`, `ngs-tour-backdrop`, `ngs-tour-step` exports: `provideTourConfig`, `TOUR_CONFIG`, `TOUR_STEP_COMPONENT`, `TourAnchorDirective`, `TourBackdrop`, `TourConfig`, `TourService`, `TourState`, `TourStep`, `TourStepConfig`, `TourStepPosition` inputs: `animateEnterClass`, `animateLeaveClass`, `isFirst`, `isLast`, `ngsTourAnchor`, `position`, `step` outputs: `backdropClick` tokens: `--ngs-button-height`, `--ngs-button-padding`, `--ngs-color-primary`, `--ngs-color-subtle`, `--ngs-color-surface-container-lowest`, `--ngs-guided-tour-arrow-border-color`, `--ngs-guided-tour-step-bg`, `--ngs-guided-tour-step-border`, `--ngs-guided-tour-step-max-width`, `--ngs-guided-tour-step-radius`, `--ngs-guided-tour-step-shadow`, `--ngs-guided-tour-step-step-padding`, `--ngs-overlay-backdrop-bg`, `--ngs-radius-xl`, `--ngs-shadow-lg` - headless-stepper: `@ngstarter-ui/components/headless-stepper` docs: /components/headless-stepper purpose: Provide stepper state and validation logic without rendering a fixed visual stepper UI. use when: Use for custom multi-step workflows where the product needs its own header, progress indicator, buttons, layout, or responsive presentation while keeping standard NgStarter step behavior. Use ngs-headless-stepper with ngs-headless-step when you need selectedIndex, selected step state, progressPercent, canMoveNext, next(), previous(), reset(), linear mode, optional steps, and stepControl validation. Good for custom wizards, onboarding forms, checkout flows, setup flows, and complex forms with a bespoke layout. Do not use when the standard visual Stepper fits; use Stepper. Do not use for guided tours over existing UI; use GuidedTour. Do not use as Tabs, Accordion, or for a simple single-page form without steps. example topics: Basic Headless Stepper, Linear Headless Stepper selectors: `ngs-headless-step`, `ngs-headless-stepper` exports: `HeadlessStep`, `HeadlessStepper`, `StepperSelectionEvent` inputs: `linear`, `optional`, `selectedIndex`, `stepControl` - icon: `@ngstarter-ui/components/icon` docs: /components/icon purpose: Render consistent SVG interface icons from installed Iconify icon sets. use when: Use ngs-icon with a full Iconify name such as fluent:grid-24-regular or circle-flags:us for icons in NgStarter buttons, navigation, menus, form field prefixes and suffixes, statuses, metadata, empty states, alerts, announcements, table actions, toolbar actions, and compact flag markers. Size icons with Tailwind classes such as size-4, w-5, or h-5, or use the default --ngs-icon-size. Color icons with text color classes or --ngs-icon-color. Do not use ngs-icon as a clickable action by itself; wrap it in an NgStarter button such as button[ngsIconButton]. Do not use Icon for people or entities; use Avatar. Do not use Icon for counters or small labels; use Badge. Do not use Icon for large artwork, product illustrations, screenshots, or logos. Do not hand-roll inline SVG when an approved Iconify icon exists. example topics: Symbols Icons (Default), Phosphor Icons, Circle Flags Icons, Material symbols icons, Circle flags selectors: `ngs-icon` exports: `Icon`, `IconData`, `IconRegistry` inputs: `name` tokens: `--ngs-icon-color`, `--ngs-icon-size` - image-designer: `@ngstarter-ui/components/image-designer` docs: /libraries/image-designer purpose: Provide a full canvas-based image composition editor with layers, assets, text, backgrounds, effects, and snapshots. use when: Use when users need to create or customize an image by composing multiple layers such as text, photos, uploaded assets, shapes, patterns, gradients, backgrounds, effects, opacity, typography, fit, flip, lock, and resize presets. Use for banner designers, social image builders, thumbnail editors, promo card creators, template-based creative tools, and embedded product design studios. Persist and restore work with ImageDesignerSnapshot, provide asset libraries with assetsDataSource or photosDataSource, handle uploads with uploadFn, and listen to snapshotChanged. Do not use for simple image viewing; use ImageViewer. Do not use for zoom/pan inspection; use ImageZoomViewer. Do not use for crop-only work; use Crop. Do not use for resize-only flows; use ImageResizer. Do not use for loading or missing-image placeholders; use ImagePlaceholder. Do not use for plain upload previews, color picking, or simple avatar/banner settings; use the smaller dedicated components or a normal form. example topics: Visual Builder, Image Designer selectors: `ngs-effects`, `ngs-image-designer`, `ngs-settings` exports: `AssetsDataSource`, `AssetsGetRowsParams`, `createDefaultPhotosDataSource`, `Effects`, `ElementConfig`, `GradientConfig`, `IMAGE_DESIGNER`, `ImageDesigner`, `ImageDesignerPhoto`, `ImageDesignerService`, `ImageDesignerSnapshot`, `ImageDesignerUploadFn` inputs: `assetsDataSource`, `defaultFont`, `guidelineColor`, `historyLimit`, `imageSize`, `maxScale`, `minScale`, `photosDataSource`, `scale`, `showDownloadButton`, `showGuidelines`, `snapRange`, `snapshot`, `snapToShapes`, `snapToStageBorders`, `snapToStageCenter`, `title`, `uploadFn` outputs: `snapshotChanged` tokens: `--ngs-color-picker-thumbnail-bg`, `--ngs-list-item-radius`, `--ngs-list-padding`, `--ngs-slider-thumb-size`, `--ngs-slider-track-height`, `--ngs-tab-label-padding`, `--ngs-tab-panel-aside-width`, `--ngs-tab-panel-nav-padding` - image-placeholder: `@ngstarter-ui/components/image-placeholder` docs: /components/image-placeholder purpose: Render a simple SVG placeholder inside an image slot when the real image is not available yet. use when: Use for image cards, media grids, upload slots, attachment previews, product thumbnails, gallery cells, banner areas, and image preview areas when an image is loading, missing, unavailable, or failed to load and the layout should keep a stable size. Give ngs-image-placeholder an explicit width, height, or aspect ratio with Tailwind classes. The component does not load images, handle upload state, or manage errors; it only renders a visual placeholder. Do not use for full empty states; use EmptyState. Do not use for skeleton loading of a full block; use Skeleton. Do not use for spinners or blocking progress; use ProgressSpinner or BlockLoader. Do not use for viewing, crop, resize, or editing; use ImageViewer, Crop, ImageResizer, or ImageDesigner. Do not use for user or team identity fallback; use Avatar. example topics: Basic image placeholder selectors: `ngs-image-placeholder` exports: `ImagePlaceholder` tokens: `--ngs-color-neutral-100`, `--ngs-color-neutral-300`, `--ngs-color-neutral-400`, `--ngs-color-surface-container` - image-resizer: `@ngstarter-ui/components/image-resizer` docs: /components/image-resizer purpose: Let users interactively change the displayed width of an img element with side drag handles. use when: Use ngs-image-resizer around a standard img marked with ngsImageResizerImage when users need to manually choose how large an image appears in an editor, content form, thumbnail preview, banner preview, or media preparation flow. Configure imageMinWidth and imageMaxWidth and listen to imageResized for rendered width, rendered height, naturalWidth, and naturalHeight. The component changes the displayed CSS width of the image; it does not crop, compress, upload, optimize, or rewrite the source file. Do not use for crop selection; use Crop. Do not use for zoom and pan inspection; use ImageZoomViewer. Do not use for simple viewing; use ImageViewer. Do not use for full canvas/layer editing; use ImageDesigner. Do not use for resizing panels or layout containers; use ResizableContainer. Do not use for backend image processing or placeholders. example topics: Basic image resizer selectors: `[ngsImageResizeHandler]`, `[ngsImageResizerImage]`, `ngs-image-resizer` exports: `ImageResizedEvent`, `ImageResizeHandlerDirective`, `ImageResizer`, `ImageResizerImageDirective` inputs: `direction`, `imageMaxWidth`, `imageMinWidth`, `maxWidth`, `minWidth`, `targetElement` outputs: `dimensionsChanged`, `imageResized` tokens: `--ngs-color-on-secondary-fixed`, `--ngs-color-white` - image-viewer: `@ngstarter-ui/components/image-viewer` docs: /components/image-viewer purpose: Open a full-size image in a focused lightbox-style overlay from a thumbnail, card, or gallery item. use when: Use ngsImageViewer on a group and ngsImageViewerPicture on each clickable preview item when users should click a thumbnail or card to inspect a full-size image from sourceUrl. The overlay supports close, loading spinner, zoom in/out, drag and pan when zoomed, and optional title, caption, and description via inputs or templates. Use for galleries, attachment previews, product images, media detail previews, portfolio images, and image cards. Do not use for inline zoom inspection without an overlay; use ImageZoomViewer. Do not use for image editing, layers, crop, or resizing; use ImageDesigner, Crop, or ImageResizer. Do not use for before/after comparison; use ComparisonSlider. Do not use for static non-clickable images; use normal img. Do not use for video previews; use VideoViewer. Do not use for missing or loading placeholders; use ImagePlaceholder. example topics: Basic image viewer, Image viewer with caption and description, Image viewer with title selectors: `[ngsImageViewer]`, `[ngsImageViewerPicture]`, `[ngsImageViewerPictureCaption]`, `[ngsImageViewerPictureDescription]`, `[ngsImageViewerPictureTitle]`, `ngs-image-viewer` exports: `IMAGE_VIEWER`, `IMAGE_VIEWER_PICTURE_DATA`, `IMAGE_VIEWER_PICTURE_REF`, `ImageViewer`, `ImageViewerDirective`, `ImageViewerPictureCaptionDirective`, `ImageViewerPictureDescriptionDirective`, `ImageViewerPictureDirective`, `ImageViewerPictureTitleDirective`, `PictureOptions`, `PictureRef` inputs: `caption`, `description`, `sourceUrl`, `title` tokens: `--ngs-color-neutral-100`, `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-400`, `--ngs-color-neutral-50`, `--ngs-color-neutral-600`, `--ngs-color-neutral-700`, `--ngs-color-neutral-800`, `--ngs-color-neutral-900`, `--ngs-color-neutral-950`, `--ngs-font-size-sm`, `--ngs-image-viewer-picture-scale`, `--ngs-shadow-sm` - image-zoom-viewer: `@ngstarter-ui/components/image-zoom-viewer` docs: /components/image-zoom-viewer purpose: Give an inline image a Medium-style click-to-zoom overlay animation from its current page position. use when: Use ngs-image-zoom-viewer around a normal image marked with ngsImageZoomViewerImage when users should quickly enlarge one inline image without a gallery structure. Good for articles, product pages, portfolios, documentation screenshots, reports, and image-rich content. The component clones the same image into an overlay, animates it from the original position to a larger centered view, closes on backdrop click or Escape, and recalculates zoom on window resize. Do not use for thumbnail galleries that need full-size sourceUrl, title, caption, or description; use ImageViewer. Do not use for image editing, crop selection, displayed-width resizing, or before/after comparison; use ImageDesigner, Crop, ImageResizer, or ComparisonSlider. Do not use for plain static images or placeholders. example topics: Basic image zoom viewer selectors: `[ngsImageZoomViewerImage]`, `ngs-image-zoom-viewer`, `ngs-image-zoom-viewer-style` exports: `ImageZoomViewer`, `ImageZoomViewerImage`, `ImageZoomViewerStyle` tokens: `--ngs-overlay-backdrop-bg` - incidents: `@ngstarter-ui/components/incidents` docs: /components/incidents purpose: Show an application-level service incident or operational notice with a compact bar and expandable incident updates. use when: Use for service outages, degraded service, maintenance windows, global system status, and important operational notices that users should see across the app or portal. Compose manually with ngs-incidents, ngs-incidents-bar, ngs-incidents-title, ngs-incidents-description, ngs-incidents-list, ngs-incident, ngs-incident-title, ngs-incident-details, ngsIncidentIcon, ngsIncidentButton, and ngsIncidentClose. For global dynamic incidents, place ngs-incidents-global near the app root and call IncidentsStore.show({ title, description, incidents }) or hide(). Do not use for local inline messages; use Alert. Do not use for user-required critical actions; use ActionRequired. Do not use for toast notifications, table row statuses, empty states, or full incident management/history pages; use notification components, Badge, Status, EmptyState, Table, or DataView. example topics: Basic Incidents, Show/Hide Dynamicly, Incidents show hide dynamicly selectors: `[ngs-incident]`, `[ngsIncidentButton]`, `[ngsIncidentClose]`, `[ngsIncidentIcon]`, `[ngsIncidentsToggleIcon]`, `ngs-incident`, `ngs-incident-details`, `ngs-incident-title`, `ngs-incidents`, `ngs-incidents-bar`, `ngs-incidents-container`, `ngs-incidents-description`, `ngs-incidents-global`, `ngs-incidents-list`, `ngs-incidents-title` exports: `Incident`, `IncidentButtonDirective`, `IncidentCloseDirective`, `IncidentDetails`, `IncidentIconDirective`, `Incidents`, `INCIDENTS`, `IncidentsBar`, `IncidentsContainer`, `IncidentsDescription`, `IncidentsList`, `IncidentsState` inputs: `fixed`, `incidentId` tokens: `--ngs-color-neutral-500`, `--ngs-color-neutral-700`, `--ngs-color-neutral-900`, `--ngs-color-on-orange-container`, `--ngs-color-orange-container`, `--ngs-font-size-sm`, `--ngs-incident-bg`, `--ngs-incident-border-radius`, `--ngs-incident-border-start`, `--ngs-incident-close-color`, `--ngs-incident-close-hover-color`, `--ngs-incident-color`, `--ngs-incident-details-color`, `--ngs-incident-details-font-size`, `--ngs-incident-gap`, `--ngs-incident-padding` - inline-text-edit: `@ngstarter-ui/components/inline-text-edit` docs: /forms/inline-text-edit purpose: Let users edit already visible plain text directly in place with a contenteditable host. use when: Use for quick rename and edit-in-place flows such as project names, task names, card titles, table labels, short descriptions, headings, and other small text values where opening a separate form would be too heavy. It saves on Enter or blur, cancels on Escape, emits the trimmed value through contentChanged, supports placeholder, and can delay emissions with delay. Do not use for normal labeled forms, validation-heavy fields, or textarea workflows; use ngs-form-field with ngsInput or textarea. Do not use for rich text, long content, comments, replies, or documents; use TextEditor, ContentEditor, or CommentEditor. Do not use for value selection or complex save/cancel flows with explicit buttons. example topics: Basic inline text edit selectors: `[ngs-inline-text-edit]`, `ngs-inline-text-edit` exports: `InlineTextEdit` inputs: `delay`, `enabled`, `placeholder` outputs: `contentChanged` tokens: `--ngs-color-neutral-500`, `--ngs-color-on-surface`, `--ngs-color-outline`, `--ngs-color-primary`, `--ngs-field-radius`, `--ngs-form-field-outlined-caret-color`, `--ngs-form-field-outlined-input-text-color`, `--ngs-form-field-outlined-outline-color`, `--ngs-form-field-outlined-outline-width` - input: `@ngstarter-ui/components/input` docs: /forms/input purpose: Apply NgStarter form styling and FormField integration to native input and textarea controls. use when: Use input[ngsInput] or textarea[ngsInput] for regular text entry such as search, email, password, URL, plain phone-like text, textarea values in forms, filters, settings forms, profile forms, and admin forms. Usually place exactly one ngsInput control inside one ngs-form-field with ngs-label, ngs-hint, ngs-error, and optional prefix or suffix. It supports placeholder, required, disabled, readonly, focus behavior, Angular forms, and ErrorStateMatcher. Do not use for numeric controls with step/min/max UX; use NumberInput. Do not use for phone country/dial-code input; use PhoneInput. Do not use for masked formats by itself; pair ngsInput with InputMask directives. Do not use for Select, Autocomplete, Datepicker, Timepicker, CurrencySelect, CountrySelect, checkbox, radio, toggle, or buttons. Do not use for inline rename; use InlineTextEdit. Do not use for comments/replies or rich/block content; use CommentEditor, TextEditor, or ContentEditor. Do not use ngsInput as a layout wrapper or standalone replacement for FormField when label, hint, and error behavior are needed. example topics: Basic Inputs, Disabled Inputs, Textarea Autosize, Clear Button, Error Messages, Input with Hints, Input with Prefixes and Suffixes, Disabled selectors: `input[ngsInput]`, `textarea[ngsInput]` exports: `Input` inputs: `disabled`, `errorStateMatcher`, `id`, `placeholder`, `readonly`, `required` - input-mask: `@ngstarter-ui/components/input-mask` docs: /forms/input-mask purpose: Format credit card input fields while the user types with ready-made mask directives. use when: Use on native inputs, usually with ngsInput inside ngs-form-field, for payment or billing fields that need credit card formatting. Available directives are ngsCreditCardNumberMask for grouped card numbers, ngsCreditCardExpiryDateMask for MM/YY expiry, and ngsCreditCardCvvMask for CVV/CVC. The directives format the visible input, set useful mobile keyboard and autocomplete attributes where applicable, and keep the Angular form value cleaned for card number and expiry. Do not use as a universal mask engine, validator, payment security layer, or compliance solution. Do not use for phone numbers; use PhoneInput. Do not use for custom IDs, tax numbers, IBAN, postal codes, arbitrary structured text, date pickers, selects, currency fields, country fields, or formatting saved display values; use dedicated components, validators, backend checks, or a custom mask directive. example topics: Credit card number input mask, Credit card expiry date input mask, Credit card cvv input mask, Credit card input mask, Credit card expiry input mask selectors: `[ngsCreditCardCvvMask]`, `[ngsCreditCardExpiryDateMask]`, `[ngsCreditCardNumberMask]` exports: `CreditCardCvvMaskDirective`, `CreditCardExpiryDateMaskDirective`, `CreditCardNumberMaskDirective` inputs: `placeholder` - input-validator: `@ngstarter-ui/components/input-validator` docs: /forms/input-validator purpose: Provide ready-made Angular ValidatorFn helpers for common reusable form validation rules. use when: Use in reactive forms with ngs-form-field, ngsInput, Angular Validators, and ngs-error when a preset client-side validator fits. Current payment presets include creditCardNumberValidator() for cleaned card number length and Luhn checksum, expiryDateValidator() for MMYY expiry format, valid month, and not-in-past checks, and creditCardCvvValidator() for numeric CVV/CVC length with optional minLength and maxLength. Pair these validators with InputMask directives when the user also needs formatted payment input. Do not use InputValidator as a UI component, input formatter, input mask, replacement for Angular built-in validators, backend validation, payment processor validation, or security/compliance layer. Do not use for arbitrary custom business rules unless a dedicated preset exists; write a project validator. example topics: Credit card input validators exports: `creditCardCvvValidator`, `CreditCardCvvValidatorOptions`, `creditCardNumberValidator`, `expiryDateValidator` - kanban-board: `@ngstarter-ui/components/kanban-board` docs: /libraries/kanban-board purpose: Render a horizontal workflow board with status columns and draggable cards. use when: Use ngs-kanban-board for tasks, issues, CRM deals, hiring pipelines, content workflows, support tickets, and other status-based boards where users drag items within a column or between columns. Provide columns with id, name, color, and items; each item should include at least name and position. Render cards through a custom ngsKanbanItemDef template and compose card content with NgStarter components such as Avatar, Badge, Icon, Button, and text. The board mutates local arrays with CDK moveItemInArray and transferArrayItem and emits itemSorted, itemTransferred, itemDropped, itemClick, itemAdd, columnEdit, and columnDelete; the app must persist the new order, status, and business data to the backend. Do not use for simple record tables; use Table or DataView. Do not use for static lists; use List. Do not use for dashboard widget layouts; use Grid. Do not use for calendars, timelines, arbitrary drag-and-drop builders, or screens without real workflow/status columns. example topics: Kanban Board selectors: `[ngsKanbanItemDef]`, `ngs-kanban-board` exports: `KanbanBoard`, `KanbanColumn`, `KanbanItem`, `KanbanItemDefDirective`, `KanbanItemSortedEvent`, `KanbanItemTransferredEvent` inputs: `colors`, `columns` outputs: `columnDelete`, `columnEdit`, `itemAdd`, `itemClick`, `itemSorted` tokens: `--ngs-color-surface-container-lowest`, `--ngs-kanban-board-col-width`, `--ngs-kanban-board-column-gap`, `--ngs-kanban-board-padding-x`, `--ngs-radius-xl`, `--ngs-shadow-sm` - kbd: `@ngstarter-ui/components/kbd` docs: /components/kbd purpose: Display visual keyboard keys and shortcut hints. use when: Use ngs-kbd for a single key such as Cmd, Shift, K, Esc, or an arrow key, and ngs-kbd-group for key combinations with plus signs between keys. Use in menus, command palettes, toolbars, help text, onboarding, documentation, and shortcut hints next to commands. Kbd is visual only: it does not register shortcuts, handle keyboard events, trigger actions, or provide command logic. Do not use as a clickable button; use Button or IconButton. Do not use for statuses or counts; use Badge. Do not use for tags or categories; use Chips. Do not use as normal body text or for actions that do not have a real shortcut handled elsewhere. example topics: Basic Keyboard, Keyboard group, Keyboard in menu, Basic kbd, Kbd group, Kbd with menu selectors: `ngs-kbd`, `ngs-kbd-group` exports: `Kbd`, `KbdGroup` tokens: `--ngs-color-surface-container`, `--ngs-font-size-xs`, `--ngs-radius-lg` - layout: `@ngstarter-ui/components/layout` docs: /components/layout purpose: Provide the base top-level shell for an application, admin area, dashboard, or large workspace page. use when: Use ngs-layout as the outer structural frame when the whole screen needs topbar, header, sidebar, scrollable content, aside, or footer regions. Use root for a full viewport application shell. Use ngs-layout-content for the main scroll container, and LayoutApiService with layoutId when the sidebar must be shown, hidden, or toggled. Nested layouts are appropriate when a large app shell contains another structured workspace with its own header/content/footer. Do not use Layout as a small wrapper, card, spacing helper, form grouping tool, or generic grid system. Use TailwindCSS grid, flex, and spacing classes inside layout regions. Use Grid for static dashboard widgets, Tiles for dashboards users can rearrange or customize, DataView or Table for datasets, Drawer for overlay side panels, and Navigation, Sidebar, or Sidenav components inside sidebars. example topics: Layout header, Layout sidebar, Layout header with sidebar, Layout header with topbar, Layout footer, Layout header with footer, Layout aside, Layout with nested layouts example selectors: `ngs-layout`, `ngs-layout-aside`, `ngs-layout-content`, `ngs-layout-footer`, `ngs-layout-header`, `ngs-layout-sidebar`, `ngs-layout-topbar` exports: `Layout`, `LAYOUT`, `LAYOUT_CONTENT`, `LayoutApiService`, `LayoutAside`, `LayoutContent`, `LayoutContentInterface`, `LayoutFooter`, `LayoutHeader`, `LayoutSidebar`, `LayoutSidebarStore`, `LayoutSidebarVisibilityChange` inputs: `autoscrollToTop`, `layoutId`, `root` tokens: `--ngs-layout-aside-width` - list: `@ngstarter-ui/components/list` docs: /components/list purpose: Display a vertical group of related rows with consistent icon, avatar, title, line, meta, action, and selection structure. use when: Use ngs-list with ngs-list-item for settings rows, files, messages, activity feed items, compact collections, simple action rows, and small repeated row groups. Use ngs-selection-list with ngs-list-option when users choose one or more rows. Use ngs-nav-list for simple navigation rows in sidebars or compact navigation areas. Use ngs-action-list for vertical action groups that are not dropdown menus. Compose each row with ngsListItemIcon or ngsListItemAvatar, ngsListItemTitle, ngsListItemLine, and ngsListItemMeta. Do not use List for large tabular datasets, columns, sorting, pagination, or bulk operations; use Table or DataView. Do not use for trigger-based dropdown or context actions; use Menu. Do not use as a full app navigation system when Navigation fits better. Do not use as a generic layout container. example topics: Basic List, List With Sections, List With Selection, List With Single Selection, List Variants, Nav List selectors: `[ngsLine]`, `[ngsListItemAvatar]`, `[ngsListItemIcon]`, `[ngsListItemLine]`, `[ngsListItemMeta]`, `[ngsListItemTitle]`, `[ngsSubheader]`, `a[ngs-list-item]`, `button[ngs-list-item]`, `ngs-action-list`, `ngs-list`, `ngs-list-item`, `ngs-list-option`, `ngs-nav-list`, `ngs-selection-list` exports: `ActionList`, `List`, `ListItem`, `ListItemAvatar`, `ListItemIcon`, `ListItemLine`, `ListItemMeta`, `ListItemTitle`, `ListOption`, `NavList`, `SelectionList`, `Subheader` inputs: `disabled`, `disableRipple`, `lines`, `multiple`, `ngsRippleDisabled`, `selected`, `value` outputs: `selectedChange`, `selectionChange` tokens: `--ngs-color-neutral`, `--ngs-list-gap`, `--ngs-list-item-active-bg`, `--ngs-list-item-active-color`, `--ngs-list-item-color`, `--ngs-list-item-disabled-opacity`, `--ngs-list-item-font-size`, `--ngs-list-item-gap`, `--ngs-list-item-hover-bg`, `--ngs-list-item-hover-color`, `--ngs-list-item-line-color`, `--ngs-list-item-line-font-size`, `--ngs-list-item-min-height`, `--ngs-list-item-padding`, `--ngs-list-item-radius`, `--ngs-list-item-title-font-size` - logo: `@ngstarter-ui/components/logo` purpose: Render a product or brand logo as a composed mark, name, and optional description. use when: Use ngs-logo or a[ngs-logo] in app shells, headers, sidebars, auth screens, splash screens, and branding areas. Compose it with ngs-logo-shape for the brand mark or image, ngs-logo-text for the product name with size small, default, or large, and ngs-logo-description for a short subtitle, version, or status. Use a[ngs-logo] when the logo navigates to the home page. Do not use Logo for user or team identity; use Avatar. Do not use for standalone action icons; use Icon inside Button or IconButton. Do not use for product thumbnails, decorative images, empty states, arbitrary SVG illustrations, or general image display. selectors: `[ngs-logo]`, `ngs-logo`, `ngs-logo-description`, `ngs-logo-shape`, `ngs-logo-text` exports: `Logo`, `LogoDescription`, `LogoShape`, `LogoText`, `LogoTextSize` inputs: `size` tokens: `--ngs-color-primary`, `--ngs-color-tertiary`, `--ngs-font-size-sm`, `--ngs-font-size-xl`, `--ngs-font-size-xs`, `--ngs-logo-text-color`, `--ngs-logo-text-font-size`, `--ngs-logo-text-font-weight` - marquee: `@ngstarter-ui/components/marquee` docs: /components/marquee purpose: Display an infinite horizontal stream of repeated non-critical content. use when: Use ngs-marquee for motion content that can move and repeat without losing meaning: promo text, short highlights, logos, badges, partner names, compact news, and decorative content showcases. Use reverse to change direction. Use pauseOnHover when users may need more time to read or interact with the moving content. Do not use Marquee for important system notices, errors, warnings, required actions, or content the user must read; use Announcement, Alert, ActionRequired, or Incidents. Do not use for navigation, tables, task lists, precise ticker data, forms, or interactive work surfaces. example topics: Basic marquee, Marquee reverse, Marquee with pause on hover, Marquee pause on hover selectors: `[ngsMarqueeItem]`, `ngs-marquee` exports: `Marquee`, `MarqueeItemDirective` inputs: `pauseOnHover`, `reverse` tokens: `--ngs-marquee-animation-duration`, `--ngs-marquee-gap`, `--ngs-marquee-item-width`, `--ngs-marquee-pause`, `--ngs-marquee-repeat-gap`, `--ngs-marquee-reverse` - menu: `@ngstarter-ui/components/menu` docs: /components/menu purpose: Show a short contextual set of commands in an overlay opened from a trigger or right-click area. use when: Use ngs-menu for row actions, overflow more actions, user menus, context menus, toolbar actions, and nested command groups. Put ngsMenuTriggerFor on a button ngsButton, button ngsIconButton, row action, or toolbar control. Use ngsContextMenuTriggerFor for right-click menus. Use button ngs-menu-item for commands, and ngs-menu-divider, ngs-menu-heading, ngs-menu-header, and ngs-menu-footer for structure. Use nested menus when a command opens a secondary command group. Use ngsMenuContent with ngsMenuTriggerData when the same menu template must render lazily for a specific row, user, or item. Do not use Menu for selecting form values; use Select, Autocomplete, ColorSwitcher, Datepicker, or another dedicated form control. Do not use for persistent navigation; use Navigation, Sidebar, Sidenav, or NavList. Do not use for long lists, tables, filters, forms, modal workflows, command palettes, or bulk action bars; use List, Table/DataView, Dialog, CommandBar, or Overlay/Popover as appropriate. example topics: Basic Menu, Menu With Icons, Menu Divider, Menu Heading, Data Driven Menu, Menu Header & Footer, Nested Menu, Menu Positioning selectors: `[ngs-menu-item]`, `[ngsContextMenuTriggerFor]`, `[ngsMenuContent]`, `[ngsMenuOptionGroup]`, `[ngsMenuTriggerFor]`, `ngs-menu`, `ngs-menu-divider`, `ngs-menu-footer`, `ngs-menu-header`, `ngs-menu-heading`, `ngs-menu-item` exports: `ContextMenuTrigger`, `Menu`, `MENU_ITEM`, `MENU_TRIGGER`, `MenuCloseReason`, `MenuContent`, `MenuDivider`, `MenuFooter`, `MenuHeader`, `MenuHeading`, `MenuItem`, `MenuOptionGroupDirective` inputs: `classList`, `disabled`, `multiple`, `ngsContextMenuTriggerData`, `ngsContextMenuTriggerFor`, `ngsMenuDisabled`, `ngsMenuTriggerData`, `ngsMenuTriggerFor`, `ngsMenuTriggerRestoreFocus`, `role`, `selected`, `xPosition`, `yPosition` outputs: `_triggered`, `closed`, `menuClosed`, `menuOpened`, `valueChange` tokens: `--ngs-color-neutral-500`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-subtle`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-highest`, `--ngs-control-radius`, `--ngs-dropdown-bg`, `--ngs-dropdown-border`, `--ngs-dropdown-height`, `--ngs-dropdown-item-active-bg`, `--ngs-dropdown-item-color`, `--ngs-dropdown-item-disabled-color`, `--ngs-dropdown-item-font-size`, `--ngs-dropdown-item-gap`, `--ngs-dropdown-item-hover-bg` - micro-chart: `@ngstarter-ui/components/micro-chart` docs: /micro-charts purpose: Render compact line, bar, and pie charts for small trends, comparisons, and proportional breakdowns. use when: Use ngs-mchart-line for a small trend over time or ordered values, ngs-mchart-bar for a compact comparison of several numeric values, and ngs-mchart-pie for a small proportional breakdown. Use MicroChart inside KPI cards, dashboard summaries, table cells, list rows, reports, and dense admin panels. It can also be used as a simple standalone dashboard chart when the chart type and level of detail match what MicroChart can display. Provide fixed dimensions with TailwindCSS classes such as w-*, h-*, or size-* because the chart renders inside its container. Use ngs-mchart-tooltip, ngs-mchart-tooltip-title, and ngs-mchart-tooltip-body when hover context is needed. Do not use MicroChart for complex analytics, detailed axes, advanced legends, drilldown, zooming, financial charting, or advanced interactions; use ECharts for complex charts. Do not use instead of ProgressBar or Gauge for a single progress percentage, Badge for status, or DataView/Table for tabular data. selectors: `ngs-mchart-bar`, `ngs-mchart-line`, `ngs-mchart-pie`, `ngs-mchart-tooltip`, `ngs-mchart-tooltip-body`, `ngs-mchart-tooltip-title` exports: `BaseChartTooltip`, `MchartBar`, `MchartLine`, `MchartLineCurveType`, `MchartPie`, `MchartTooltip`, `MchartTooltipBody`, `MchartTooltipTitle` inputs: `compact`, `curve`, `data`, `dataItemStrokeWidth`, `fillAreaGradient`, `fillGradient`, `gap`, `highlight`, `labels`, `legendContainerWidth`, `legendItemFontSize`, `legendItemHeight`, `legendItemSymbolBorderRadius`, `legendItemSymbolSize`, `legendOffset`, `markerDotSize`, `radius`, `responsive`, `showArea`, `showDataAnimation`, `showLegend`, `showMarkers`, `showValueOnSlices`, `strokeWidth` tokens: `--ngs-color-background`, `--ngs-color-neutral`, `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-700`, `--ngs-color-neutral-800`, `--ngs-color-neutral-900`, `--ngs-color-neutral-950`, `--ngs-color-primary`, `--ngs-color-primary-200`, `--ngs-color-primary-500`, `--ngs-color-tertiary-200`, `--ngs-font-size-xs`, `--ngs-mchart-bar-bar-bg`, `--ngs-mchart-bar-bar-gradient-end-color`, `--ngs-mchart-bar-bar-gradient-start-color` - motion: `@ngstarter-ui/components/motion` purpose: Use Motion when an Angular admin or dashboard screen needs this UI pattern. use when: Use Motion as the standard NgStarter component for this UI need. selectors: `ngs-motion-player`, `ngs-motion-studio` exports: `MotionPlayer`, `MotionStudio` - navigation: `@ngstarter-ui/components/navigation` docs: /navigation/navigation purpose: Render a persistent product navigation structure when ngs-sidebar is not used. use when: Use ngs-navigation for custom navigation areas, section navigation, settings navigation, admin navigation, and nested navigation groups when the screen needs product links but does not use ngs-sidebar. ngs-sidebar has its own navigation model, so do not duplicate ngs-navigation inside ngs-sidebar. Use ngs-navigation-item or [ngs-navigation-item] for destinations, key with activeKey for active state, activateByRoute for URL-based activation, autoScrollToActiveItem for long navigation, ngs-navigation-heading for sections, ngs-navigation-divider for group separation, and ngs-navigation-group with ngs-navigation-group-toggle and ngs-navigation-group-menu for expandable nested destinations. Use ngsNavigationItemIcon, ngsNavigationGroupToggleIcon, and ngsNavigationItemBadge for icons, toggles, and badges. Use dataSource with ngsNavigationItemDef when navigation comes from config or backend data. Do not use Navigation for trigger-based action menus; use Menu. Do not use for ordinary row lists; use List or NavList. Do not use for breadcrumbs, tabs, wizard steps, command palettes, form selection, table row actions, or bulk actions. example topics: Basic Navigation, Navigation with heading, Navigation with divider, Navigation with icons, Navigation with nested menu, Navigation with badges selectors: `[ngs-navigation-item]`, `[ngsNavigationGroupToggleIcon]`, `[ngsNavigationItemBadge]`, `[ngsNavigationItemDef]`, `[ngsNavigationItemIcon]`, `ngs-navigation`, `ngs-navigation-divider`, `ngs-navigation-group`, `ngs-navigation-group-menu`, `ngs-navigation-group-toggle`, `ngs-navigation-heading`, `ngs-navigation-item` exports: `Navigation`, `NAVIGATION`, `NAVIGATION_GROUP`, `NavigationDivider`, `NavigationGroup`, `NavigationGroupInterface`, `NavigationGroupMenu`, `NavigationGroupToggle`, `NavigationGroupToggleIconDirective`, `NavigationHeading`, `NavigationItem`, `NavigationItemBadgeDirective` inputs: `activateByRoute`, `activeKey`, `appearance`, `badgeTextOnly`, `dataSource`, `forceActive`, `itemTypeProperty`, `key` outputs: `itemClicked` tokens: `--ngs-color-on-primary`, `--ngs-color-on-surface-variant`, `--ngs-color-outline`, `--ngs-color-primary`, `--ngs-color-subtle`, `--ngs-font-size-xs`, `--ngs-nav-arrow-size`, `--ngs-nav-badge-padding`, `--ngs-nav-badge-size`, `--ngs-nav-divider-height`, `--ngs-nav-divider-margin`, `--ngs-nav-group-toggle-icon-position-end`, `--ngs-nav-group-toggle-icon-size`, `--ngs-nav-group-toggle-padding-end`, `--ngs-nav-heading-after-margin`, `--ngs-nav-heading-font-size` - notifications: `@ngstarter-ui/components/notifications` docs: /components/notifications purpose: Display user-facing notification events in a structured feed or inbox. use when: Use Notifications for events addressed to the current user: comments, mentions, invitations, assignments, access requests, status changes, completed processes, and user-specific updates. Use ngs-notification for one event, ngsNotificationAvatar for the source avatar or icon, ngs-notification-message for the main sentence, ngs-notification-actor for the actor, ngs-notification-content for nested context such as a comment, file, quote, card, or preview, and ngs-notification-time for time. Use isUnread for unread state. Use ngs-notification-list with ngsNotificationDef when notifications come from an array and each type needs its own template. Use ngsNotificationControlsDef for per-notification controls such as mute, delete, or mark as read, often with Menu. Do not use Notifications for page-level system messages; use Alert or Announcement. Do not use for critical required actions; use ActionRequired. Do not use for service health; use Incidents. Do not use for generic activity feeds that are not user notifications; use List. Do not use for transient toast/snackbar messages. example topics: Basic notifications, Notification variants, Notification list selectors: `[ngs-notification-actor]`, `[ngs-notification-content]`, `[ngs-notification-time]`, `[ngs-notification]`, `[ngsNotificationAvatar]`, `[ngsNotificationControlsDef]`, `[ngsNotificationDef]`, `[ngsNotificationProps]`, `ngs-notification`, `ngs-notification-actor`, `ngs-notification-content`, `ngs-notification-list`, `ngs-notification-message`, `ngs-notification-skeleton`, `ngs-notification-time` exports: `Notification`, `NotificationActor`, `NotificationActorLike`, `NotificationAvatarDirective`, `NotificationContent`, `NotificationControlsDefDirective`, `NotificationDefDirective`, `NotificationInterface`, `NotificationList`, `NotificationMessage`, `NotificationPropsDirective`, `NotificationSkeleton` inputs: `isUnread`, `ngsNotificationDef`, `notifications`, `static` outputs: `notificationClick` tokens: `--ngs-color-neutral-900`, `--ngs-color-neutral-950`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-surface-container`, `--ngs-color-surface-container-low`, `--ngs-color-surface-container-lowest`, `--ngs-font-size-sm`, `--ngs-font-size-xs`, `--ngs-notification-bg`, `--ngs-notification-content-margin`, `--ngs-notification-gap`, `--ngs-notification-hover-bg`, `--ngs-notification-is-unread-bg`, `--ngs-notification-is-unread-hover-bg` - number-input: `@ngstarter-ui/components/number-input` docs: /forms/number-input purpose: Capture a numeric form value with typing, stepper controls, min/max limits, and Angular forms integration. use when: Use ngs-number-input inside one ngs-form-field when users need to type a number or adjust it with increase/decrease controls. Good for quantities, limits, thresholds, durations, percentages, ratings, numeric settings, seat counts, day counts, and budget-like numeric values. Use ngModel or formControlName, min and max for allowed bounds, step for increment/decrement size, readonly/disabled/required as normal form states, and ngsDecreaseControl or ngsIncreaseControl only when custom control icons are needed. Use TailwindCSS classes on ngs-form-field or surrounding layout for width and grouping. Do not use for normal text; use ngsInput. Do not use for phone numbers; use PhoneInput. Do not use for OTP, MFA, passcodes, or invite codes; use PinInput. Do not use for selecting currency; use CurrencySelect plus a numeric amount field when needed. Do not use for sliders/ranges, display-only KPI values, progress, or charts; use the dedicated component such as Gauge, ProgressBar, MicroChart, or a text/KPI layout. example topics: Basic Number Input, Custom Controls, Min, Max Value, Number input custom controls, Number input min max selectors: `[ngsDecreaseControl]`, `[ngsIncreaseControl]`, `[ngsNumberInputPrefix]`, `[ngsNumberInputSuffix]`, `ngs-number-input` exports: `DecreaseControlDirective`, `IncreaseControlDirective`, `NumberInput`, `NumberInputPrefixDirective`, `NumberInputSuffixDirective` inputs: `disabled`, `max`, `min`, `placeholder`, `readonly`, `required`, `step` outputs: `valueChange` tokens: `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-500`, `--ngs-color-neutral-600`, `--ngs-color-neutral-700`, `--ngs-color-surface-container`, `--ngs-color-surface-container-high`, `--ngs-icon-size`, `--ngs-number-input-control-active-bg`, `--ngs-number-input-control-active-color`, `--ngs-number-input-control-bg`, `--ngs-number-input-control-border`, `--ngs-number-input-control-border-radius`, `--ngs-number-input-control-color`, `--ngs-number-input-control-font-size`, `--ngs-number-input-control-hover-bg` - option: `@ngstarter-ui/components/option` purpose: Provide a low-level selectable option primitive for Select, Autocomplete, and other option-parent controls. use when: Use ngs-option inside ngs-select, ngs-autocomplete, and other NgStarter dropdown/listbox controls that explicitly expect options, such as CountrySelect, CurrencySelect, DateFormatSelect, Timepicker, FilterBuilder, and similar controls. Use [value] for the form value and disabled when the option cannot be selected. Use ngs-optgroup to group related options under a label. Keep option text short and readable because the viewValue is derived from the rendered text. Do not use ngs-option as a generic list row, button, menu item, navigation item, table row, card, or custom layout block. Use MenuItem or Button for actions, Navigation/List/NavList for navigation and lists, RadioCard for rich card selection, and ColorSwitcher for fixed color choices. Agents usually should not import Option separately unless they are composing Select, Autocomplete, or another option-based component. selectors: `ngs-optgroup`, `ngs-option` exports: `_Option`, `_OptionParent`, `Optgroup`, `Option`, `OPTION`, `OPTION_PARENT` inputs: `data`, `disabled`, `label`, `selected`, `value` outputs: `onSelectionChange` tokens: `--ngs-color-on-primary-container`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary-container`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-highest`, `--ngs-control-radius`, `--ngs-dropdown-height`, `--ngs-dropdown-item-active-bg`, `--ngs-dropdown-item-color`, `--ngs-dropdown-item-disabled-color`, `--ngs-dropdown-item-font-size`, `--ngs-dropdown-item-gap`, `--ngs-dropdown-item-hover-bg`, `--ngs-dropdown-item-nested-padding-start`, `--ngs-dropdown-item-padding` - overlay: `@ngstarter-ui/components/overlay` purpose: Provide low-level shared positioning utilities for components that create Angular CDK floating overlays. use when: Use Overlay only when implementing a new NgStarter component or custom directive that directly manages Angular CDK Overlay, portal rendering, backdrop or outside-click behavior, close behavior, keyboard/focus handling, and anchored positioning. Use OverlayPosition values such as below-start, below-center, below-end, above-*, before-*, and after-*. Use new PositionManager().build(position) to create fallback ConnectedPosition[] pairs. Do not use Overlay directly when building a normal admin page or feature screen. Prefer higher-level components: Menu for action dropdowns and context menus, Popover for lightweight anchored content, Dialog for modal workflows, Drawer for side overlays, Select/Autocomplete/Datepicker/ColorPicker for form dropdowns, and Tooltip for simple hints. exports: `OverlayPosition`, `PositionManager` - page-loading-bar: `@ngstarter-ui/components/page-loading-bar` purpose: Show a global thin loading bar during Angular Router navigation. use when: Use ngs-page-loading-bar once in the top-level app shell or root layout, usually near the root layout or router outlet, to provide navigation feedback. It listens to Angular Router events automatically: NavigationStart shows the bar, and NavigationEnd, NavigationCancel, or NavigationError finish it. Use fixed when the bar should stay attached to the viewport. Do not use PageLoadingBar for loading a specific block, table, card, form, submit/save/upload operation, or async work inside a page. Use ProgressBar, ProgressSpinner, BlockLoader, Skeleton, ScreenLoader, or the component-specific loading state for local loading. Do not use it as a real task completion percentage; it is route navigation feedback only. selectors: `ngs-page-loading-bar` exports: `PageLoadingBar` inputs: `fixed` tokens: `--ngs-loading-bar-bg`, `--ngs-loading-bar-height` - paginator: `@ngstarter-ui/components/paginator` docs: /components/paginator purpose: Control pages of a dataset with range label, previous/next navigation, optional first/last buttons, and page size selection. use when: Use ngs-paginator next to paged tables, DataView screens, search results, record lists, and server-side browsing. Provide length for total records, pageSize for records per page, zero-based pageIndex for the current page, and pageSizeOptions for allowed page sizes. Handle the page event to update local data or request the next page from an API; PageEvent includes previousPageIndex, pageIndex, pageSize, and length. Use hidePageSize when the page size is fixed. Use showFirstLastButtons when users need quick first/last navigation. Use PaginatorIntl to localize labels and range text. Do not use Paginator for app route navigation; use Navigation, Tabs, or Breadcrumbs. Do not use for wizard or onboarding steps; use Stepper or HeadlessStepper. Do not use for carousel slides, media browsing, or standalone UI without a paged dataset. If DataView already owns pagination, use its pagination model instead of adding a separate paginator. example topics: Basic Paginator, Configurable Paginator selectors: `ngs-paginator` exports: `DEFAULT_PAGE_SIZE`, `PageEvent`, `Paginator`, `PAGINATOR_DEFAULT_OPTIONS`, `PaginatorDefaultOptions`, `PaginatorIntl` inputs: `disabled`, `hidePageSize`, `length`, `pageIndex`, `pageSize`, `pageSizeOptions`, `showFirstLastButtons` outputs: `page` tokens: `--ngs-color-on-surface`, `--ngs-font-size-sm`, `--ngs-form-field-container-min-height`, `--ngs-form-field-infix-min-height`, `--ngs-form-field-infix-padding-bottom`, `--ngs-form-field-infix-padding-top`, `--ngs-paginator-container-background`, `--ngs-paginator-container-background-color`, `--ngs-paginator-container-text-color`, `--ngs-paginator-container-text-font`, `--ngs-paginator-container-text-line-height`, `--ngs-paginator-container-text-size`, `--ngs-paginator-container-text-tracking`, `--ngs-paginator-container-text-weight`, `--ngs-paginator-items-per-page-label-margin`, `--ngs-paginator-page-size-margin-right` - panel: `@ngstarter-ui/components/panel` docs: /components/panel purpose: Create a local structured work area with header, subheader, sidebar, scrollable content, aside, and footer regions. use when: Use ngs-panel inside a page or workspace for admin modules, settings areas, editors, detail panes, inspectors, dashboard sections, and local surfaces that need their own header, footer, side columns, and scrollable body. Use ngs-panel-header for local title, toolbar, or actions; ngs-panel-subheader for filters or secondary status; ngs-panel-sidebar for a local left column; ngs-panel-content for the main scrollable area; ngs-panel-aside for a local right column; and ngs-panel-footer for local footer actions or status. Use absolute when the panel should fill the parent bounds. Use TailwindCSS classes for sizing, borders, spacing, and inner layout. Do not use Panel as the top-level application shell; use Layout. Do not use for small content blocks; use Card. Do not use for overlay side panels; use Drawer. Do not use as a generic spacing wrapper or form grid; use TailwindCSS grid/flex and FormField. example topics: Basic panel, Basic with extra columns (sidebar and aside), Panel with extra columns selectors: `ngs-panel`, `ngs-panel-aside`, `ngs-panel-content`, `ngs-panel-footer`, `ngs-panel-header`, `ngs-panel-sidebar`, `ngs-panel-subheader` exports: `Panel`, `PANEL_CONTENT`, `PanelAside`, `PanelContent`, `PanelContentInterface`, `PanelFooter`, `PanelHeader`, `PanelSidebar`, `PanelSubheader` inputs: `absolute`, `autoHeight`, `block`, `flex` tokens: `--ngs-panel-footer-height`, `--ngs-panel-header-height`, `--ngs-panel-subheader-height` - password-strength: `@ngstarter-ui/components/password-strength` docs: /forms/password-strength purpose: Show real-time password strength feedback and requirement status while users create or change a password. use when: Use PasswordStrength in signup, reset password, change password, account security, and credential setup forms. Use input type="password" ngsInput inside one ngs-form-field for the actual password field, then place ngs-password-strength [password]="password.value" below it for the strength bar. Use ngs-password-strength-info with a template reference to the strength component when users need to see requirement status for lowercase, uppercase, digit, special character, min length, or custom rules. Use ngs-pass-toggle-visibility as a suffix control inside the password form field when users need show/hide password behavior. Configure min, max, enableLengthRule, enableDigitRule, enableSpecialCharRule, and customValidator as needed, and listen to strengthChanged when the screen needs the score. Do not use PasswordStrength for OTP, MFA, invite codes, or passcodes; use PinInput. Do not use for generic text validation. Do not use for a login password field unless the user is creating or changing a password and strength feedback is useful. Do not rely on it as the only password security policy; backend validation is still required. example topics: Basic password strength, Password strength info, Password toggle visibility selectors: `ngs-pass-toggle-visibility`, `ngs-password-strength`, `ngs-password-strength-info` exports: `Colors`, `Criteria`, `PassToggleVisibility`, `PasswordStrength`, `PasswordStrengthInfo`, `PasswordStrengthValidator`, `RegExpValidator` inputs: `accentThreshold`, `customCharsCriteriaMessage`, `customValidator`, `digitsCriteriaMessage`, `enableDigitRule`, `enableLengthRule`, `enableLowerCaseLetterRule`, `enableScoreInfo`, `enableSpecialCharRule`, `enableUpperCaseLetterRule`, `externalError`, `lowerCaseCriteriaMessage`, `max`, `min`, `minCharsCriteriaMessage`, `ngsIconDone`, `ngsIconError`, `password`, `passwordComponent`, `specialCharsCriteriaMessage`, `tabindex`, `upperCaseCriteriaMessage`, `visible`, `warnThreshold` outputs: `strengthChanged` tokens: `--ngs-color-danger`, `--ngs-color-green-500`, `--ngs-color-warning`, `--ngs-progress-bar-active-indicator-color`, `--ngs-progress-bar-active-indicator-height`, `--ngs-progress-bar-track-height` - pdf-builder: `@ngstarter-ui/components/pdf-builder` docs: /libraries/pdf-builder purpose: The NgStarter Angular PDF Builder component provides a contract document builder workspace with a block palette, layers, editable PDF canvas, selected-block toolbar, and inspector panel for document automation interfaces. use when: Choose Pdf Builder when the workflow matches examples such as PDF Builder, Basic pdf builder. example topics: PDF Builder, Basic pdf builder selectors: `ngs-pdf-builder`, `ngs-pdf-builder-signature-dialog`, `ngs-pdf-builder-stamp-dialog` exports: `PDF_BUILDER_DEFAULT_FIELD_METRICS`, `PDF_BUILDER_DEFAULT_TEXT_FONT_COLOR`, `PDF_BUILDER_DEFAULT_TEXT_FONT_FAMILY`, `PDF_BUILDER_DEFAULT_TEXT_FONT_SIZE`, `PDF_BUILDER_MAX_TEXT_FONT_SIZE`, `PDF_BUILDER_MIN_TEXT_FONT_SIZE`, `PdfBuilder`, `PdfBuilderCanvasTool`, `PdfBuilderDrawnSignatureUploadCallback`, `PdfBuilderDrawnSignatureUploadContext`, `PdfBuilderField`, `PdfBuilderFieldMetrics` inputs: `annotations`, `drawnSignatureUploadCallback`, `initialsImageUploadCallback`, `recipients`, `schema`, `signatureImageUploadCallback`, `signers`, `stamps`, `uploadedInitials`, `uploadedSignatures` outputs: `addRecipient`, `createBlankPdf`, `createRecipientContact`, `editRecipientDetails`, `exportPdf`, `initialsSelected`, `initialsTyped`, `initialsUploaded`, `recipientSearchChanged`, `recipientSelected`, `removeRecipient`, `replaceRecipient`, `schemaChange`, `signatureDrawn`, `signatureSelected`, `signatureTyped`, `signatureUploaded`, `stampSelected`, `stampUploaded` tokens: `--ngs-button-bg`, `--ngs-button-border-radius`, `--ngs-button-content-gap`, `--ngs-button-font-size`, `--ngs-button-height`, `--ngs-button-hover-bg`, `--ngs-button-outlined-border`, `--ngs-button-outlined-color`, `--ngs-button-padding`, `--ngs-color-border`, `--ngs-color-border-strong`, `--ngs-color-danger`, `--ngs-color-on-primary-container`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-on-warning-container` - pdf-signer: `@ngstarter-ui/components/pdf-signer` docs: /libraries/pdf-signer purpose: The NgStarter Angular PDF Signer renders a prepared PDF Builder schema as a signing workspace. use when: Choose Pdf Signer when the workflow matches examples such as PDF Signer, Basic pdf signer. example topics: PDF Signer, Basic pdf signer selectors: `ngs-pdf-signer` exports: `PdfSigner`, `PdfSignerFieldValueChange` inputs: `drawnSignatureUploadCallback`, `initialsImageUploadCallback`, `schema`, `showOtherSignerFields`, `showPageList`, `signatureImageUploadCallback`, `signer`, `stamps`, `uploadedInitials`, `uploadedSignatures` outputs: `fieldValueChange`, `initialsSelected`, `initialsTyped`, `initialsUploaded`, `schemaChange`, `signatureDrawn`, `signatureSelected`, `signatureTyped`, `signatureUploaded`, `stampSelected`, `stampUploaded` tokens: `--ngs-button-bg`, `--ngs-button-border-radius`, `--ngs-button-color`, `--ngs-button-height`, `--ngs-button-hover-bg`, `--ngs-button-padding`, `--ngs-color-border-strong`, `--ngs-color-on-primary`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-on-warning-container`, `--ngs-color-primary`, `--ngs-color-surface`, `--ngs-color-warning`, `--ngs-color-warning-container`, `--ngs-color-white` - pdf-viewer: `@ngstarter-ui/components/pdf-viewer` docs: /libraries/pdf-viewer purpose: Import PDF Viewer from @ngstarter-ui/components/pdf-viewer . use when: Choose Pdf Viewer when the workflow matches examples such as Basic pdf viewer. example topics: Basic pdf viewer selectors: `[ngsPdfViewerAnnotation]`, `[ngsPdfViewerAnnotationDef]`, `ngs-pdf-viewer`, `ngs-pdf-viewer-annotations`, `ngs-pdf-viewer-search` exports: `PdfViewer`, `PdfViewerAnnotationDataSource`, `PdfViewerAnnotationDataSourceContext`, `PdfViewerAnnotationDataSourceParams`, `PdfViewerAnnotationDataSourceResult`, `PdfViewerAnnotationDef`, `PdfViewerAnnotations`, `PdfViewerAnnotationTemplateContext`, `PdfViewerAnnotationView`, `PdfViewerAnnotationWhen`, `PdfViewerEngineService`, `PdfViewerLoadedEvent` inputs: `annotationDefs`, `annotations`, `annotationsDataSource`, `annotationTypeProperty`, `documentName`, `enableCommandWheelZoom`, `maxRenderDimension`, `maxRenderPixels`, `maxScale`, `minScale`, `ngsPdfViewerAnnotation`, `ngsPdfViewerAnnotationDef`, `ngsPdfViewerAnnotationWhen`, `page`, `query`, `renderAll`, `results`, `scale`, `searchQuery`, `showAnnotationsPanel`, `showPageList`, `showSearchPanel`, `showToolbar`, `src` outputs: `closed`, `error`, `loaded`, `pageChanged`, `pageRendered`, `pageSelected`, `resultSelected`, `searchChanged` tokens: `--ngs-color-primary`, `--ngs-color-white`, `--ngs-pdf-viewer-aside-width`, `--ngs-pdf-viewer-height`, `--ngs-pdf-viewer-min-height`, `--ngs-pdf-viewer-page-gap`, `--ngs-pdf-viewer-page-padding`, `--ngs-pdf-viewer-sidebar-width`, `--ngs-pdf-viewer-spread-gap` - phone-input: `@ngstarter-ui/components/phone-input` docs: /forms/phone-input purpose: Capture real phone numbers with country selection, flag, dial code, formatting, and libphonenumber-js validation. use when: Use ngs-phone-input inside one ngs-form-field for profile, contact, billing, onboarding, checkout, support, invite, and contact forms when the value must be a real phone number. Use formControlName or ngModel, show invalidPhone with ngs-error, set defaultSelectedCountryCode when the initial country should not be us, use onlyCountries to restrict available countries, preferredCountries to pin common countries to the top, format="default | national | international" for display formatting, and countryChanged when the screen needs to react to country changes. Do not use plain ngsInput, NumberInput, or InputMask for country-aware phone numbers. Do not use CountrySelect instead of PhoneInput; CountrySelect chooses a country but does not capture a phone number. Do not use for OTP, MFA, passcodes, or invite codes; use PinInput. example topics: Basic phone input, Phone input with custom country list, Phone input with preferred country list, Phone input only countries, Phone input preferred countries selectors: `ngs-phone-input` exports: `Country`, `CountryCode`, `PhoneInput`, `PhoneNumberFormat`, `phoneValidator`, `SearchPipe` inputs: `autocomplete`, `defaultSelectedCountryCode`, `disabled`, `errorStateMatcher`, `format`, `onlyCountries`, `placeholder`, `preferredCountries` outputs: `countryChanged` tokens: `--ngs-color-neutral-500`, `--ngs-color-neutral-600`, `--ngs-color-on-surface-variant`, `--ngs-font-size-sm`, `--ngs-phone-input-color`, `--ngs-phone-input-flag-display`, `--ngs-phone-input-opacity` - pin-input: `@ngstarter-ui/components/pin-input` docs: /forms/pin-input purpose: Capture short one-character-per-cell codes for verification and secure access flows. use when: Use ngs-pin-input as a standalone form control for OTP, MFA, SMS or email verification codes, invite codes, passcodes, payment verification, and secure access codes. Use ngModel or formControlName, length for the number of cells, placeholder for the empty-cell hint, acceptOnly for allowed symbols with digits as the default, and disabled for disabled state. The component manages one-character cells and focus movement between them. Do not use PinInput for phone numbers; use PhoneInput. Do not use for creating or changing passwords; use ngsInput with PasswordStrength. Do not use for numeric settings or quantities; use NumberInput. Do not use for long codes, serial numbers, coupons, or arbitrary text; use a normal ngsInput. Do not wrap it in ngs-form-field as if it were a single text input; the component renders its own internal form fields. example topics: Basic Pin Input, Placeholder, Custom Length, Custom Symbols, Pin input with placeholder, Pin input length, Pin input accept custom symbols selectors: `[ngsPinInput]`, `ngs-pin-input` exports: `PinInput`, `PinInputDirective` inputs: `acceptOnly`, `disabled`, `index`, `length`, `placeholder` outputs: `valuePaste` tokens: `--ngs-form-field-input-text-align`, `--ngs-form-field-width`, `--ngs-pin-gap`, `--ngs-pin-input-width` - popover: `@ngstarter-ui/components/popover` docs: /components/popover purpose: Show lightweight contextual content in an overlay anchored to a trigger element. use when: Use Popover for short details, previews, small interactive content, compact forms, and richer explanations that need more than a plain tooltip but do not require a modal workflow. Put ngsPopoverTriggerFor on the trigger element and point it to ngs-popover or a TemplateRef. Use trigger="click" for explicit opening and trigger="hover" only for preview-style content that can disappear safely. Use position for below/above/before/after placement. Use ngsPopoverContext with ngsPopoverContent for lazy content that needs trigger data. Use a raw TemplateRef only when the standard ngs-popover-panel wrapper should be replaced. Use hasBackdrop, closeOnOriginClick, closeOnOriginMouseLeave, and origin only when custom close or anchoring behavior is needed. Do not use Popover for command lists; use Menu. Do not use for short plain hints; use Tooltip. Do not use for modal workflows, confirmations, or complex forms; use Dialog or Confirm. Do not use for side panels; use Drawer. Do not use for form dropdowns; use Select, Autocomplete, Datepicker, or ColorPicker. Do not use low-level Overlay directly when Popover fits. example topics: Basic Popover, Show popover by hover, Popover custom position, Popover lazy content, Popover with TemplateRef, Popover hover, Popover with custom position, Popover template ref selectors: `[ngsPopoverContent]`, `[ngsPopoverOrigin]`, `[ngsPopoverTriggerFor]`, `ngs-popover` exports: `Popover`, `POPOVER_TRIGGER`, `PopoverContent`, `PopoverOriginDirective`, `PopoverPosition`, `PopoverTrigger`, `PopoverTriggerFor`, `PopoverTriggerForDirective` inputs: `closeOnOriginClick`, `closeOnOriginMouseLeave`, `delay`, `hasBackdrop`, `ngsPopoverContext`, `origin`, `position`, `trigger` outputs: `closed`, `opened` tokens: `--ngs-dropdown-bg`, `--ngs-dropdown-border`, `--ngs-dropdown-radius`, `--ngs-dropdown-shadow`, `--ngs-popover-bg`, `--ngs-popover-border`, `--ngs-popover-border-radius`, `--ngs-popover-margin`, `--ngs-popover-shadow` - progress-bar: `@ngstarter-ui/components/progress-bar` docs: /components/progress-bar purpose: Show linear progress for an operation or process. use when: Use ngs-progress-bar for uploads, downloads, imports, setup completion, sync, processing, form completion, buffering, and other horizontal progress states. Use mode="determinate" with value from 0 to 100 when the percentage is known. Use mode="indeterminate" when work is happening but the percentage is unknown. Use mode="buffer" with value and bufferValue when both primary and buffered progress should be visible. Use mode="query" while waiting before known progress starts. Use animationEnd only when the screen must react after the transition finishes. Do not use ProgressBar for Angular Router navigation; use PageLoadingBar. Do not use to block a whole area; use BlockLoader. Do not use for skeleton content loading; use Skeleton. Do not use for circular KPI or percent metrics; use Gauge. Do not use for mini trends or charts; use MicroChart. Do not use as a status label; use Badge or text. example topics: Basic Progress Bar, Intermediate Progress Bar, Buffer Progress Bar, Query Progress Bar selectors: `ngs-progress-bar` exports: `ProgressBar`, `ProgressBarMode` inputs: `bufferValue`, `color`, `mode`, `value` outputs: `animationEnd` tokens: `--ngs-color-primary`, `--ngs-color-surface-container-highest`, `--ngs-progress-bar-animation-multiplier`, `--ngs-progress-bar-height`, `--ngs-progress-bar-indicator-color`, `--ngs-progress-bar-track-color` - radio: `@ngstarter-ui/components/radio` docs: /forms/radio purpose: Let users choose exactly one option from a small visible set of mutually exclusive choices. use when: Use ngs-radio-group with ngs-radio-button for simple text options in forms, settings, filters, and preference screens where all options should be visible and the user can choose only one. Put value on each radio button and bind the group value with value, ngModel, or formControlName. Use name when native form grouping matters, disabled on the group or individual radio button when needed, and change when the screen must react to selection changes. Do not use Radio for multiple selection; use Checkbox. Do not use for long option lists; use Select or Autocomplete. Do not use for rich options with descriptions, icons, or large clickable blocks; use RadioCard. Do not use as a segmented view switcher; use Segmented or ButtonToggle. Do not use for yes/no boolean settings when SlideToggle or Checkbox better matches the meaning. example topics: Basic Radios, Radio Orientation, Radio Card, Basic radio selectors: `ngs-radio-button`, `ngs-radio-group` exports: `RadioButton`, `RadioGroup`, `RadioGroupOrientation` inputs: `checked`, `disabled`, `id`, `name`, `orientation`, `value` outputs: `change` tokens: `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-field-border-color`, `--ngs-radio-button-border-width`, `--ngs-radio-button-checked-color`, `--ngs-radio-button-disabled-color`, `--ngs-radio-button-disabled-label-color`, `--ngs-radio-button-gap`, `--ngs-radio-button-inner-circle-size`, `--ngs-radio-button-label-color`, `--ngs-radio-button-size`, `--ngs-radio-button-unchecked-color`, `--ngs-radio-group-gap` - radio-card: `@ngstarter-ui/components/radio-card` purpose: Let users choose exactly one option from a small set of rich card-like choices. use when: Use ngs-radio-card-group as a form control group and ngs-radio-card for each option when every option needs a large clickable card with title, icon, description, or supporting content. Use ngs-radio-card-title for the option name and optional icon, ngs-radio-card-content for details, value on each card, and formControlName or ngModel on the group. Use TailwindCSS grid or flex around the group to lay cards out in columns or rows. Good for plan selection, privacy modes, template choices, payment methods, layout options, delivery methods, onboarding choices, and settings choices with explanation. Do not use for simple short text options; use Radio. Do not use for multiple selection; use Checkbox or a dedicated checkbox-card pattern when available. Do not use for long lists; use Select or Autocomplete. Do not use as a normal content card without selection; use Card. Do not use as a segmented mode switch; use Segmented or ButtonToggle. selectors: `ngs-radio-card`, `ngs-radio-card-content`, `ngs-radio-card-group`, `ngs-radio-card-title` exports: `RadioCard`, `RadioCardContent`, `RadioCardGroup`, `RadioCardTitle` inputs: `value` tokens: `--ngs-color-border`, `--ngs-color-neutral-600`, `--ngs-color-primary`, `--ngs-color-primary-100`, `--ngs-font-size-sm`, `--ngs-radio-card-border-radius`, `--ngs-radio-card-color-border-hover`, `--ngs-radio-card-color-selected-bg`, `--ngs-radio-card-color-selected-border`, `--ngs-radio-card-content-color`, `--ngs-radio-card-content-font-size`, `--ngs-radio-card-group-gap`, `--ngs-radio-card-padding`, `--ngs-radio-card-title-font-size`, `--ngs-radio-card-title-gap`, `--ngs-radio-card-transition` - rail-nav: `@ngstarter-ui/components/rail-nav` docs: /navigation/rail-nav purpose: Provide a compact vertical navigation rail with icons and short labels. use when: Use ngs-rail-nav when an app or workspace shell needs compact vertical navigation but there is not enough space for a full sidebar. Use ngs-rail-nav-item or [ngs-rail-nav-item] for destinations, ngsRailNavItemIcon for icons, key on each item, activeKey on the rail, and railNav.api.isActive(key) when the active item should change icon or styling. Good for narrow editor or workspace navigation, secondary product navigation, compact admin shells, and switching between primary sections. Do not use when you need a full sidebar with groups, nested navigation, or supporting content; use Sidebar or Sidenav. Do not use inside ngs-sidebar because Sidebar has its own navigation. Do not use for normal section navigation in content; use Navigation. Do not use for tabs, breadcrumbs, menu actions, segmented controls, or one-off icon buttons. example topics: Basic rail navigation, Rail navigation customization, Basic rail nav, Rail nav customization selectors: `[ngs-rail-nav-item]`, `[ngsRailNavItemIcon]`, `ngs-rail-nav`, `ngs-rail-nav-item` exports: `RAIL_NAV`, `RailNav`, `RailNavAPI`, `RailNavComponent`, `RailNavItem`, `RailNavItemIconDirective` inputs: `activeKey`, `key` tokens: `--ngs-font-size-xs`, `--ngs-icon-color`, `--ngs-nav-item-active-bg`, `--ngs-nav-item-active-color`, `--ngs-nav-item-active-icon-color`, `--ngs-nav-item-color`, `--ngs-nav-item-hover-bg`, `--ngs-nav-item-icon-color`, `--ngs-nav-items-gap`, `--ngs-radius-full`, `--ngs-rail-nav-bg`, `--ngs-rail-nav-bg-item-active-color`, `--ngs-rail-nav-bg-item-color`, `--ngs-rail-nav-bg-item-icon-active-bg`, `--ngs-rail-nav-bg-item-icon-color`, `--ngs-rail-nav-bg-item-icon-hover-bg` - resizable-container: `@ngstarter-ui/components/resizable-container` docs: /components/resizable-container purpose: Let users manually resize the width of one container with a vertical drag handle. use when: Use ngs-resizable-container around content when the user should manually adjust the width of a single block. Good for resizable preview panes, editor canvas or containers, inspector or detail panels, side content areas, responsive demo areas, chart previews, and docs playgrounds. Use minWidth for the minimum allowed width, resized to persist or synchronize the new width, and TailwindCSS classes for border, height, initial width, layout, and inner content. Do not use as a full split layout between two panels; use Split or a dedicated splitter when available. Do not use for image resizing; use ImageResizer. Do not use for table or DataView column resizing; use the table/DataView resizing feature. Do not use as a normal responsive container when users should not manually resize it; use TailwindCSS responsive utilities or container queries. Do not use for Drawer or Sidebar resizing when those components own their sizing model. example topics: Basic Resizable Container selectors: `ngs-resizable-container` exports: `ResizableContainer` inputs: `minWidth` outputs: `resized` tokens: `--ngs-color-secondary`, `--ngs-color-surface-container-highest` - screen-loader: `@ngstarter-ui/components/screen-loader` docs: /components/screen-loader purpose: Show a full-screen blocking loading state for large global operations. use when: Use ScreenLoader when the user must wait and should not interact with the app: initial app load, major route or page data loading, account switching, tenant switching, auth or session restore, heavy backend tasks, and large global operations. Prefer ScreenLoaderService.open(messageOrTemplate) for programmatic full-screen overlays, keep the returned ScreenLoaderRef, and always call ref.close() when the operation finishes. Use afterOpened() and afterClosed() only for side effects. Use ngs-screen-loader with opened and message only when the open state is controlled directly in a template. message can be a short string or TemplateRef. Do not use ScreenLoader for local block, card, table, or form loading; use BlockLoader, Skeleton, ProgressSpinner, ProgressBar, or component-specific loading states. Do not use for route navigation progress; use PageLoadingBar. Do not use for known percentage progress; use ProgressBar. Do not leave a service-opened loader without closing its ref. example topics: Basic screen loader selectors: `ngs-screen-loader` exports: `ScreenLoader`, `ScreenLoaderRef`, `ScreenLoaderService` inputs: `opened` tokens: `--ngs-color-background`, `--ngs-screen-loader-bg` - scroll-spy: `@ngstarter-ui/components/scroll-spy` purpose: Provide in-page navigation for sections inside a long scrollable page or local scroll container. use when: Use ScrollSpy when a long page or panel has stable section ids and needs a table-of-contents style navigation that highlights the active section while scrolling and smooth-scrolls to sections on click. Use ngs-scroll-spy-nav as the nav container, ngs-scroll-spy-on with targetId matching a section id, ngs-scroll-spy-title for the nav heading, and ngs-scroll-spy-back-to-top for a top shortcut. It uses ngs-layout-content or ngs-panel-content as the scroll container when present, otherwise document body. Good for docs pages, long settings pages, profile or detail pages with many sections, policy/help pages, long form review pages, and article-like admin pages. Do not use for primary product navigation; use Navigation, Sidebar, Sidenav, or RailNav. Do not use for tabs between views; use Tabs. Do not use for route breadcrumbs; use Breadcrumbs. Do not use for wizard steps; use Stepper or HeadlessStepper. Do not use on short pages without real scrolling or without stable section ids. selectors: `[ngs-scroll-spy-back-to-top]`, `[ngs-scroll-spy-nav]`, `[ngs-scroll-spy-on]`, `[ngs-scroll-spy-title]`, `[ngsScrollSpyContainer]`, `ngs-scroll-spy-back-to-top`, `ngs-scroll-spy-nav`, `ngs-scroll-spy-on`, `ngs-scroll-spy-title` exports: `SCROLL_SPY_NAV`, `ScrollSpyBackToTop`, `ScrollSpyContainerDirective`, `ScrollSpyNav`, `ScrollSpyOn`, `ScrollSpyTitle` inputs: `targetId` tokens: `--ngs-color-primary`, `--ngs-color-subtle`, `--ngs-font-size-sm`, `--ngs-font-size-xl`, `--ngs-icon-size` - scrollbar-area: `@ngstarter-ui/components/scrollbar-area` purpose: Provide a styled scroll container for bounded UI regions. use when: Use ngs-scrollbar-area when a sized panel, grid body, editor sidebar, asset list, menu, or similar surface needs consistent NgStarter scrollbars instead of native browser scrollbars. It hides native scrollbars, renders vertical and horizontal thumbs, supports auto-hide, thumb dragging, resize and mutation tracking, scrollbarWidth, autoHide, absolute fill mode, and scrolled output. Use [absolute]="true" when the scroll area should fill a positioned parent region such as ngs-panel-content or a DataView viewport; make sure the parent already has a stable height and width. Do not use as a generic layout wrapper, spacing helper, page-level replacement for normal browser scrolling, carousel or scroll-snap component, virtualization engine, or a workaround for missing parent sizing. selectors: `[ngsScrollContainerFixed]`, `ngs-scrollbar-area` exports: `ScrollbarArea`, `ScrollContainerFixed` inputs: `absolute`, `autoHide`, `ngsScrollContainerFixed`, `ngsScrollContainerFixedBottomOffset`, `ngsScrollContainerFixedMinHeight`, `scrollbarWidth` outputs: `scrolled` tokens: `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-radius-sm`, `--ngs-scrollbar-area-scroll-track-bg`, `--ngs-scrollbar-area-thumb-active-bg`, `--ngs-scrollbar-area-thumb-bg`, `--ngs-scrollbar-area-thumb-hover-bg`, `--ngs-scrollbar-area-width` - segmented: `@ngstarter-ui/components/segmented` docs: /forms/segmented purpose: Let users choose one value from a compact set of mutually exclusive modes or options. use when: Use ngs-segmented with ngs-segmented-button when a short set of options should stay visible and only one value can be selected. Good for view modes, time ranges, display density, selection mode, chart or table mode, compact filters, and short settings. It works as an Angular form control through value, valueChange, ngModel, or formControlName, supports disabled state, sizes, text buttons, icons with ngsSegmentedIcon, and iconOnly buttons. Do not use Segmented for route or page navigation; use Tabs, Navigation, Sidebar, Sidenav, or RailNav. Do not use for independent on/off toggles; use ButtonToggle or SlideToggle. Do not use for long lists, rich option cards, dropdown choices, or fixed color palettes; use Radio, RadioCard, Select, Autocomplete, or ColorSwitcher. example topics: Basic segmented control, Segmented control sizes, Segmented control disabled, Segmented control with icons, Segmented control with icons only, Segmented control with FormControl, Segmented control with ngModel, Basic segmented selectors: `[ngs-segmented-button]`, `[ngsSegmentedIcon]`, `ngs-segmented`, `ngs-segmented-button` exports: `Segmented`, `SEGMENTED`, `SegmentedButton`, `SegmentedIconDirective`, `SegmentedTriggerSize` inputs: `disabled`, `iconOnly`, `size`, `value` outputs: `valueChange` tokens: `--ngs-button-radius`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-surface`, `--ngs-color-surface-container`, `--ngs-color-surface-container-highest`, `--ngs-font-size-sm`, `--ngs-font-size-xs`, `--ngs-icon-size`, `--ngs-segmented-bg`, `--ngs-segmented-button-color`, `--ngs-segmented-button-font-size`, `--ngs-segmented-button-gap`, `--ngs-segmented-button-height`, `--ngs-segmented-button-hover-bg` - select: `@ngstarter-ui/components/select` docs: /forms/select purpose: Let users choose one or multiple values from a known dropdown list. use when: Use ngs-select inside one ngs-form-field when a form, filter, setting, table filter, DataView filter, or admin configuration field should choose from predefined options. Use ngs-option for options, ngs-optgroup for visible grouping, multiple for array values, placeholder, required, disabled, Angular forms, value, and selectionChange for state. Use ngs-select-trigger to customize the closed label, and ngs-select-header, ngs-select-body, or ngs-select-footer when the dropdown panel needs search, custom scrolling, or supporting controls. Do not use Select as a command menu or action list; use Menu. Do not use for route or page navigation; use Navigation, Tabs, Sidebar, Sidenav, or RailNav. Do not use for compact visible mode switching; use Segmented. Do not use for simple visible choices or rich card choices; use Radio or RadioCard. Do not use for arbitrary free text or large remote search suggestion flows; use Autocomplete or a dedicated async picker. Do not use generic Select when a domain-specific control exists, such as CountrySelect, CurrencySelect, DateFormatSelect, or TimezoneSelect. example topics: Basic Select, Clearable Select, Getting and setting the select value, Form Field Features, Disabled, Resetting the select value, Groups of Options, Multiple Selection selectors: `ng-template[ngsFilterTriggerValue]`, `ng-template[ngsOptionContentDef]`, `ng-template[ngsSelectValueDef]`, `ngs-filter-trigger`, `ngs-select`, `ngs-select-body`, `ngs-select-footer`, `ngs-select-header`, `ngs-select-trigger` exports: `_Select`, `FilterTrigger`, `FilterTriggerValueDirective`, `Select`, `SELECT`, `SelectBody`, `SelectChange`, `SelectDataSource`, `SelectDataSourceOption`, `SelectDataSourceRequest`, `SelectDataSourceResult`, `SelectFooter` inputs: `aria-describedby`, `aria-label`, `clearable`, `dataSource`, `disabled`, `hideCheckIcon`, `id`, `loadOnOpen`, `maxCount`, `minSearchLength`, `multiple`, `pageSize`, `placeholder`, `required`, `searchable`, `searchDebounce`, `showZero`, `tabIndex`, `value` outputs: `closed`, `opened`, `selectionChange` tokens: `--ngs-color-danger`, `--ngs-color-on-primary`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-outline`, `--ngs-color-outline-variant`, `--ngs-color-primary`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-lowest`, `--ngs-dropdown-bg`, `--ngs-dropdown-border`, `--ngs-dropdown-item-gap`, `--ngs-dropdown-max-height`, `--ngs-dropdown-padding`, `--ngs-dropdown-radius`, `--ngs-dropdown-shadow` - side-panel: `@ngstarter-ui/components/side-panel` docs: /navigation/side-panel purpose: Provide an embedded side utility panel with tabbed tools beside the main content. use when: Use ngs-side-panel inside an app or workspace layout when the page needs persistent secondary tools or inspectors next to the primary content. Add ngs-side-panel-tab for each tab with tabId, label, and an optional Iconify icon name or custom icon TemplateRef. Good for info, outline, layers, activity, comments, assets, properties, preview settings, contextual inspectors, and quick tools in editors or admin workspaces. It can be positioned left or right and emits opened and closed. Do not use SidePanel as a temporary overlay; use Drawer. Do not use for modal workflows or confirmations; use Dialog or Confirm. Do not use as a generic page section; use Panel or Card. Do not use for primary app navigation; use Sidebar, Sidenav, Navigation, or RailNav. Do not use for tabs inside normal content; use Tabs. Do not use for simple action lists; use Menu. example topics: Basic side panel selectors: `ngs-side-panel`, `ngs-side-panel-tab` exports: `PanelPosition`, `SidePanel`, `SidePanelTab`, `SidePanelTabConfig` inputs: `label`, `position`, `tabId` outputs: `closed`, `opened` tokens: `--ngs-nav-item-active-bg`, `--ngs-nav-item-active-color`, `--ngs-side-panel-button-active-bg`, `--ngs-side-panel-button-active-color`, `--ngs-side-panel-button-strip-width`, `--ngs-side-panel-content-bg`, `--ngs-side-panel-content-width`, `--ngs-side-panel-offset-y`, `--ngs-side-panel-transition-timing` - sidebar: `@ngstarter-ui/components/sidebar` docs: /navigation/sidebar purpose: Provide a complete vertical app or workspace sidebar with its own navigation system. use when: Use ngs-sidebar as the content inside a shell sidebar region, usually inside Sidenav or LayoutSidebar, when an admin app or workspace needs persistent sidebar navigation and supporting sidebar content. Compose it with ngs-sidebar-header, ngs-sidebar-body, ngs-sidebar-footer, ngs-sidebar-nav, ngs-sidebar-nav-item, ngs-sidebar-nav-group, ngs-sidebar-nav-group-toggle, ngs-sidebar-nav-group-menu, ngs-sidebar-heading, ngs-sidebar-divider, ngsSidebarNavItemIcon, ngsSidebarNavItemBadge, and ngsSidebarNavGroupToggleIcon. Good for brand or workspace header, main app navigation, grouped routes, badges, active item state through activeKey, autoScrollToActiveItem, and data-driven nav templates. Sidebar owns navigation; when ngs-sidebar is not used and persistent navigation is needed, use Navigation. Do not use Sidebar as a generic left column, card, drawer content, inspector, page section, tabs, menu, or compact icon rail. Use Sidenav for responsive open, collapse, or overlay shell behavior, RailNav for compact icon navigation, SidePanel for secondary tabbed tools, Drawer for temporary overlay side content, and Panel or Card for content grouping. example topics: Basic sidebar, Sidebar structure helpers, Dynamic compact sidebar, Only compact sidebar, Sidebar with custom icons selectors: `[ngs-sidebar-nav-item]`, `[ngsSidebarNavGroupToggleIcon]`, `[ngsSidebarNavItemBadge]`, `[ngsSidebarNavItemDef]`, `[ngsSidebarNavItemIcon]`, `ngs-sidebar`, `ngs-sidebar-body`, `ngs-sidebar-content`, `ngs-sidebar-divider`, `ngs-sidebar-footer`, `ngs-sidebar-header`, `ngs-sidebar-heading`, `ngs-sidebar-nav`, `ngs-sidebar-nav-group`, `ngs-sidebar-nav-group-menu`, `ngs-sidebar-nav-group-toggle`, `ngs-sidebar-nav-item`, `ngs-sidebar-spacer` exports: `Sidebar`, `SIDEBAR_NAVIGATION`, `SIDEBAR_NAVIGATION_GROUP`, `SidebarBody`, `SidebarDivider`, `SidebarFooter`, `SidebarHeader`, `SidebarHeading`, `SidebarNav`, `SidebarNavGroup`, `SidebarNavGroupMenu`, `SidebarNavGroupToggle` inputs: `activeKey`, `autoScrollToActiveItem`, `block`, `dataSource`, `forceActive`, `itemTypeProperty`, `key`, `onlyCompact` outputs: `itemClicked` tokens: `--ngs-color-border`, `--ngs-color-emphasis`, `--ngs-color-on-primary`, `--ngs-color-on-surface-variant`, `--ngs-color-outline`, `--ngs-color-primary`, `--ngs-color-subtle`, `--ngs-font-size-xs`, `--ngs-nav-arrow-size`, `--ngs-nav-badge-padding`, `--ngs-nav-badge-size`, `--ngs-nav-divider-height`, `--ngs-nav-divider-margin`, `--ngs-nav-group-toggle-icon-position-end`, `--ngs-nav-group-toggle-icon-size`, `--ngs-nav-group-toggle-padding-end` - sidenav: `@ngstarter-ui/components/sidenav` docs: /components/sidenav purpose: Provide a responsive shell container for side surfaces that can open, close, collapse, overlay, or push content. use when: Use ngs-sidenav-container with ngs-sidenav and ngs-sidenav-content when a page or app shell needs a side region with behavior: opened state, open/close/toggle methods, mode over/push/side, position start/end, collapsed icon-width state, disableClose, backdrop and backdropClick, adaptive mobile mode through adaptive and adaptiveBreakpoint, fixedWidth, autosize, and autoFocus. Use ngsSidenavCollapsed and ngsSidenavExpanded templates to render different content while collapsed or expanded. In admin shells, put ngs-sidebar inside ngs-sidenav when the side region is primary navigation; Sidebar owns the actual navigation items. Do not use Sidenav as the navigation structure itself; use Sidebar or Navigation inside it. Do not use for temporary task panels; use Drawer. Do not use for persistent tabbed utility tools; use SidePanel. Do not use for static local columns or content sections; use LayoutSidebar, Panel, or Tailwind layout. Do not use for modal workflows, confirmations, or action menus; use Dialog, Confirm, or Menu. example topics: Basic sidenav selectors: `[ngsSidenavCollapsed]`, `[ngsSidenavExpanded]`, `ngs-sidenav`, `ngs-sidenav-container`, `ngs-sidenav-content` exports: `AutoFocusTarget`, `Sidenav`, `SIDENAV`, `SidenavCollapsed`, `SidenavContainer`, `SidenavContent`, `SidenavExpanded`, `SidenavMode`, `SidenavPosition` inputs: `adaptive`, `adaptiveBreakpoint`, `autoFocus`, `autosize`, `collapsed`, `disableClose`, `fixedWidth`, `hasBackdrop`, `mode`, `opened`, `position` outputs: `backdropClick` tokens: `--ngs-color-background`, `--ngs-overlay-backdrop-bg`, `--ngs-sidenav-backdrop-color`, `--ngs-sidenav-background-color`, `--ngs-sidenav-collapsed-width`, `--ngs-sidenav-divider-color`, `--ngs-sidenav-transition-duration`, `--ngs-sidenav-transition-timing-function`, `--ngs-sidenav-width`, `--ngs-sidenav-z-index` - signature-pad: `@ngstarter-ui/components/signature-pad` docs: /components/signature-pad purpose: Capture a handwritten signature and emit it as a PNG data URL. use when: Use ngs-signature-pad in approval, contract, consent, delivery confirmation, onboarding, checkout, legal acknowledgement, or internal workflow forms where the user must draw a signature. It supports mouse, touch, or pen input, penColor, colors for the fixed allowed pen palette, lineWidth, backgroundColor, lazy brush smoothing through lazyRadius/lazyFriction/lazyEnabled, clear(), save(), signatureSaved with a base64 PNG data URL, and signatureCleared. Use the emitted PNG in app code to store or attach the signature to the workflow or document. Do not use SignaturePad as a general drawing canvas, image editor, annotation tool, sketch board, whiteboard, file upload, typed-name field, or legal validation system by itself. App code still needs to require the signature when needed, persist it, and enforce backend or legal rules. example topics: Basic signature pad selectors: `ngs-signature-pad`, `ngs-typed-signature-pad` exports: `LazyBrush`, `LazyBrushOptions`, `LazyBrushUpdateOptions`, `LazyPoint`, `Point`, `SignaturePad`, `TypedSignatureFont`, `TypedSignaturePad`, `TypedSignaturePadValue` inputs: `backgroundColor`, `colors`, `fontFamily`, `fonts`, `lazyEnabled`, `lazyFriction`, `lazyRadius`, `lineWidth`, `penColor`, `placeholder`, `value` outputs: `signatureCleared`, `signatureSaved`, `signatureTyped` tokens: `--ngs-brand-colors-color-size`, `--ngs-brand-colors-gap`, `--ngs-button-content-gap`, `--ngs-button-height`, `--ngs-button-hover-bg`, `--ngs-button-padding`, `--ngs-button-text-color`, `--ngs-color-on-surface`, `--ngs-color-surface-container-highest`, `--ngs-color-surface-container-low`, `--ngs-color-surface-container-lowest`, `--ngs-font-family`, `--ngs-font-size-lg`, `--ngs-font-size-sm`, `--ngs-icon-button-size`, `--ngs-icon-size` - skeleton: `@ngstarter-ui/components/skeleton` docs: /components/skeleton purpose: Show placeholder blocks for loading content when the final layout is already known. use when: Use ngs-skeleton to preserve layout while cards, lists, table rows, dashboard widgets, chart areas, avatars, text lines, or media blocks are loading. Shape and size each skeleton with TailwindCSS utilities such as h-*, w-*, size-*, flex, grid, gap, and wrapper layouts so it roughly matches the UI that will replace it. Use roundedFull for circular placeholders such as avatars or icon circles. Do not use Skeleton for unknown long operations where progress matters; use ProgressBar. Do not use for global route or app loading; use PageLoadingBar or ScreenLoader. Do not use for blocking a local section; use BlockLoader. Do not use for empty results; use EmptyState. Do not use for image fallback after load failure; use ImagePlaceholder. Do not use random grey blocks that do not resemble the final content. example topics: Basic Skeleton selectors: `ngs-skeleton` exports: `Skeleton` inputs: `roundedFull` tokens: `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-500`, `--ngs-color-neutral-600`, `--ngs-radius-xl`, `--ngs-skeleton-from-bg`, `--ngs-skeleton-item-border-radius`, `--ngs-skeleton-to-bg` - slide-toggle: `@ngstarter-ui/components/slide-toggle` docs: /forms/slide-toggle purpose: Capture a boolean on/off setting where checked means enabled. use when: Use ngs-slide-toggle for settings and preferences where checked=true means the feature or state is enabled. Good for live updates, notifications, dark mode option, visibility, sidebar expanded or collapsed, animation on/off, table options, enable Wi-Fi, show archived, and allow comments. It is an Angular form control with checked, disabled, required, ngModel, formControlName, change, and toggleChange, and has its own label pattern, so do not wrap it in ngs-form-field. Do not use SlideToggle for choosing one value from many; use Radio, Segmented, or Select. Do not use for multiple independent selections in a list; use Checkbox. Do not use for button-like mode groups; use ButtonToggle. Do not use for actions, commands, navigation, or rich option cards; use Button, Navigation, or RadioCard. For “I agree” or “accept terms” confirmations, prefer Checkbox because the user is confirming, not enabling a setting. example topics: Basic Slide Toggle, Disabled Slide Toggle, Slide Toggle with Forms, Slide toggle disabled selectors: `ngs-slide-toggle`, `ngs-slide-toggle-group` exports: `SlideToggle`, `SlideToggleChange`, `SlideToggleGroup` inputs: `aria-describedby`, `aria-label`, `aria-labelledby`, `checked`, `color`, `disabled`, `disableRipple`, `hideIcon`, `id`, `labelPosition`, `name`, `required`, `tabIndex` outputs: `change`, `toggleChange` tokens: `--ngs-color-on-primary`, `--ngs-color-primary`, `--ngs-color-surface`, `--ngs-color-surface-container-highest`, `--ngs-slide-toggle-bar-checked-color`, `--ngs-slide-toggle-bar-color`, `--ngs-slide-toggle-group-gap`, `--ngs-slide-toggle-height`, `--ngs-slide-toggle-thumb-checked-color`, `--ngs-slide-toggle-thumb-color`, `--ngs-slide-toggle-thumb-size`, `--ngs-slide-toggle-transition-duration`, `--ngs-slide-toggle-width` - slider: `@ngstarter-ui/components/slider` docs: /components/slider purpose: Let users choose one numeric value or a start/end range by dragging thumb controls. use when: Use ngs-slider when approximate visual numeric adjustment is better than typing. Good for volume, opacity, zoom, size, threshold, percentage, rating or score, price range, numeric date or age range, chart settings, visual tuning, and filter ranges. Use input ngsSliderThumb for one value, or input ngsSliderStartThumb plus input ngsSliderEndThumb for a range. Configure min, max, step, disabled, discrete, showTickMarks, displayWith, Angular forms, and valueChange on thumbs. Do not use Slider to show progress or status; use ProgressBar or Gauge. Do not use when exact numeric entry is primary; use NumberInput or pair NumberInput with Slider. Do not use for named categories; use Select, Radio, or Segmented. Do not use for before/after image comparison; use ComparisonSlider. Do not use for pagination or table sorting/filter builder logic; use Paginator, Sort, or FilterBuilder. example topics: Basic Slider, Custom Thumb Label Formatting, Range Slider, Configurable Slider selectors: `input[ngsSliderEndThumb]`, `input[ngsSliderStartThumb]`, `input[ngsSliderThumb]`, `ngs-slider` exports: `Slider`, `SliderEndThumb`, `SliderStartThumb`, `SliderThumb` inputs: `disabled`, `discrete`, `max`, `min`, `showTickMarks`, `step`, `value` outputs: `valueChange` tokens: `--ngs-color-on-primary`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-primary-100`, `--ngs-color-surface`, `--ngs-color-surface-container-high`, `--ngs-slider-thumb-color`, `--ngs-slider-thumb-ripple-color`, `--ngs-slider-thumb-size`, `--ngs-slider-tick-mark-active-color`, `--ngs-slider-tick-mark-color`, `--ngs-slider-track-active-color`, `--ngs-slider-track-active-height`, `--ngs-slider-track-color`, `--ngs-slider-track-height` - snack-bar: `@ngstarter-ui/components/snack-bar` docs: /components/snackbar purpose: Show short transient overlay feedback after an action or background result. use when: Use the SnackBar service for brief non-blocking messages such as Saved, Copied, Invite sent, Refresh complete, Export started, or Deleted, with an optional quick action such as Undo or View. Open with snackBar.open(message, action?, config?), openFromComponent, or openFromTemplate. Configure duration, horizontalPosition, verticalPosition, data, panelClass, custom component or template content, and use SnackBarRef.dismiss(), afterOpened(), and afterDismissed() for lifecycle handling. SnackBar should be short, temporary, and safe to miss. Do not use for field validation errors; use FormField errors. Do not use for persistent inline messages; use Alert. Do not use for global important header messages; use Announcement. Do not use for critical required actions; use ActionRequired. Do not use for confirmations before destructive actions; use Confirm. Do not use for modal workflows; use Dialog. Do not use for long-lived notification inboxes or event feeds; use Notifications. Do not use for incident/status banners or loading/progress states; use Incidents, ProgressBar, ScreenLoader, BlockLoader, or PageLoadingBar. example topics: Basic Snackbar, Snackbar With Custom Component, Configurable Snackbar, Snackbar with custom, Snackbar selectors: `ngs-simple-snack-bar`, `ngs-snack-bar-container` exports: `provideSnackBarConfig`, `SimpleSnackBar`, `SNACK_BAR_CONFIG`, `SNACK_BAR_DATA`, `SnackBar`, `SnackBarConfig`, `SnackBarContainer`, `SnackBarHorizontalPosition`, `SnackBarRef`, `SnackBarVerticalPosition` tokens: `--ngs-color-neutral-100`, `--ngs-color-neutral-950`, `--ngs-font-size-sm` - sort: `@ngstarter-ui/components/sort` docs: /components/sort purpose: Provide sortable header behavior and sort state for table-like data. use when: Use ngsSort on a sortable table/list/data container and ngs-sort-header="fieldName" on header cells that should cycle through sort states. Sort tracks active column and direction (asc, desc, or cleared), supports ngsSortActive, ngsSortDirection, ngsSortStart, ngsSortDisableClear, ngsSortDisabled, per-header disabled state, sortActionDescription, and emits ngsSortChange with { active, direction }. Use it with Table sortable column headers, custom table-like data surfaces, and when wiring sort state into a local TableDataSource or server/API query. For DataView, usually prefer its built-in sortable column config and sortChange instead of manually adding ngs-sort-header. Do not use Sort as a visual sort icon only, filter builder, search, grouping, drag reorder, tab sorting, or generic “sort these cards” button. Sort only manages header state and emits the selected sort; the app/data source still applies local sorting or sends the sort state to the backend. example topics: Basic Sort selectors: `[ngs-sort-header]`, `[ngsSort]` exports: `NgsSort`, `Sort`, `SORT`, `SortDirection`, `SortDirective`, `SortHeader`, `SortModule` inputs: `disabled`, `ngs-sort-header`, `ngsSortActive`, `ngsSortDirection`, `ngsSortDisableClear`, `ngsSortDisabled`, `ngsSortStart`, `sortActionDescription` outputs: `ngsSortChange` - spinner: `@ngstarter-ui/components/spinner` docs: /components/progress-spinner purpose: Show a circular indicator for an ongoing operation. use when: Use ngs-progress-spinner when a compact circular loading indicator is needed inside a button, overlay, media viewer, widget, small page area, or next to an action. Use mode="indeterminate" when the remaining time or amount of work is unknown. Use mode="determinate" with value from 0 to 100 when progress is known. Configure diameter, strokeWidth, and color for the surface. Do not use ProgressSpinner for linear progress; use ProgressBar. Do not use it for known loading layouts; use Skeleton. Do not use it for router or page transition loading; use PageLoadingBar. Do not use it as a full-screen or blocking state by itself; use ScreenLoader or BlockLoader. Do not use it as a KPI or metric display; use Gauge or ProgressBar based on context. example topics: Basic Progress Spinner, Configurable Progress Spinner, Configurable spinner selectors: `ngs-progress-spinner` exports: `ProgressSpinner`, `ProgressSpinnerModule`, `SpinnerMode` inputs: `color`, `diameter`, `mode`, `strokeWidth`, `value` tokens: `--ngs-color-danger`, `--ngs-color-primary`, `--ngs-color-secondary`, `--ngs-progress-spinner-active-indicator-width`, `--ngs-progress-spinner-animation-multiplier`, `--ngs-progress-spinner-color` - splash-screen: `@ngstarter-ui/components/splash-screen` purpose: Show one full-screen branded startup overlay during the initial app bootstrap moment. use when: Use ngs-splash-screen once near the root app template while Angular, routing, theme, auth/session, tenant, or essential startup data initializes. Project ngs-logo or custom branded content into it. It hides automatically after the first NavigationEnd with hideDelay, fades with animationDuration, and can be controlled through SplashScreenStore.show() and SplashScreenStore.hide(). Do not use SplashScreen for normal page loading after startup; use PageLoadingBar. Do not use for full-screen blocking operations after the app is running; use ScreenLoader. Do not use for local card, table, form, or widget loading; use BlockLoader, Skeleton, ProgressBar, or component-specific loading states. Do not use for empty states, route skeletons, modal workflows, or marketing hero screens. SplashScreen should be one per app and short-lived at the beginning, not shown for every action. selectors: `ngs-splash-screen` exports: `SplashScreen`, `SplashScreenState`, `SplashScreenStore` inputs: `animationDuration`, `hideDelay` tokens: `--ngs-color-background`, `--ngs-splash-screen-bg`, `--ngs-splash-screen-hide-animation-duration` - split: `@ngstarter-ui/components/split` docs: /components/split-pane purpose: Create a resizable multi-pane layout with draggable gutters between panes. use when: Use ngs-split with multiple ngs-split-pane regions when a workspace needs two or more panes that users can manually resize. Good for editors, IDE-like screens, analytics workspaces, master-detail-detail layouts, source and preview views, inspector plus canvas plus logs, and dense multi-pane tools. Supports horizontal or vertical direction, nested splits, unit percent or pixel, size, minSize, maxSize, lockSize, visible, order, withHandle dotted gutter affordance, restrictMove, disabled, gutterSize, gutterStep, dragStart, dragEnd, gutterClick, gutterDblClick, transitionEnd, getVisibleAreaSizes(), and setVisibleAreaSizes() for persistence. Do not use Split for ordinary responsive layout or static two-column admin pages; use TailwindCSS grid or flex. Do not use for one manually resized box; use ResizableContainer. Do not use for side navigation shells; use Sidenav or Sidebar. Do not use for temporary side overlays; use Drawer. Do not use for local structured page sections; use Panel. Do not use for table column resizing or image resizing; use table features or ImageResizer. The parent must have a stable height and width. example topics: Basic Split Pane, Split Pane with Handle, Vertical Split Pane with Handle, Split Pane with 3 Columns and Minimum Sizes, Split Pane with Restricted Move, Basic split, Split handle, Split vertical handle selectors: `[ngs-split-pane]`, `ngs-split`, `ngs-split-pane` exports: `getAreaAbsorptionCapacity`, `getAreaAbsorptionCapacityPercent`, `getAreaAbsorptionCapacityPixel`, `getAreaMaxSize`, `getAreaMinSize`, `getElementPixelSize`, `getGutterSideAbsorptionCapacity`, `getInputPositiveNumber`, `getPointFromEvent`, `isUserSizesValid`, `provideSplit`, `Split` inputs: `dir`, `direction`, `disabled`, `gutterDblClickDuration`, `gutterSize`, `gutterStep`, `lockSize`, `maxSize`, `minSize`, `order`, `restrictMove`, `size`, `unit`, `useTransition`, `visible`, `withHandle` outputs: `dragEnd`, `dragStart`, `gutterClick`, `gutterDblClick`, `transitionEnd` tokens: `--ngs-color-on-surface`, `--ngs-color-primary`, `--ngs-color-surface-container-high`, `--ngs-split-gutter-bg`, `--ngs-split-gutter-hover-bg`, `--ngs-split-gutter-size`, `--ngs-split-handle-offset`, `--ngs-split-handle-size` - step-tracker: `@ngstarter-ui/components/step-tracker` docs: /components/step-tracker purpose: Show the status of related steps without owning wizard navigation, validation, or routed content. use when: Use ngs-step-tracker with ngs-step-tracker-item when users need passive visibility into process stages such as completed, current, pending, error, or disabled. Good for payroll review stages, onboarding checklists, fulfillment status, setup status, approval flows, and compact progress summaries in cards, sidebars, drawers, and page headers. Use StepTracker when steps are status display only. Configure global completed/error indicator icon names with provideStepTracker or STEP_TRACKER_CONFIG; use ngsStepTrackerCompletedIcon and ngsStepTrackerErrorIcon templates for per-tracker overrides. Do not use it for wizard navigation, next/previous buttons, linear validation, or projected step content; use Stepper or HeadlessStepper for those workflows. Do not use it for chronological audit/event history; use Timeline. Do not use it for a single percentage; use ProgressBar. example topics: Basic Step Tracker, Horizontal Step Tracker, Step Tracker With Custom Icons, Step Tracker With Projected Content, Step Tracker States, Step tracker icons, Step tracker projected content selectors: `[ngsStepTrackerCompletedIcon]`, `[ngsStepTrackerDescription]`, `[ngsStepTrackerErrorIcon]`, `[ngsStepTrackerLabel]`, `ngs-step-tracker`, `ngs-step-tracker-description`, `ngs-step-tracker-item`, `ngs-step-tracker-label` exports: `provideStepTracker`, `STEP_TRACKER_CONFIG`, `STEP_TRACKER_DEFAULT_CONFIG`, `StepTracker`, `StepTrackerCompletedIcon`, `StepTrackerConfig`, `StepTrackerDescription`, `StepTrackerErrorIcon`, `StepTrackerItem`, `StepTrackerItemState`, `StepTrackerLabel`, `StepTrackerOrientation` inputs: `activeIndex`, `description`, `label`, `orientation`, `state` tokens: `--ngs-color-danger`, `--ngs-color-neutral-400`, `--ngs-color-neutral-500`, `--ngs-color-neutral-800`, `--ngs-color-on-danger`, `--ngs-color-on-success`, `--ngs-color-outline`, `--ngs-color-primary`, `--ngs-color-success`, `--ngs-color-surface`, `--ngs-color-surface-container-high`, `--ngs-font-size-base`, `--ngs-font-size-sm`, `--ngs-icon-size`, `--ngs-step-tracker-completed-bg`, `--ngs-step-tracker-completed-color` - stepper: `@ngstarter-ui/components/stepper` docs: /components/stepper purpose: Render a ready-made visual wizard for several connected steps in one process. use when: Use ngs-stepper with ngs-step when users must move through related steps and see their current progress. Good for onboarding, checkout, setup, import/export flows, account or tenant creation, review flows, and multi-step forms. Use linear mode with stepControl when each step must be valid before the user continues. Use ngsStepperNext and ngsStepperPrevious on NgStarter buttons for standard wizard navigation, ngsStepLabel or label for step labels, optional/completed/error states for step status, and horizontal or vertical orientation for responsive layouts. Do not use Stepper when you only need step state and validation logic without the default visual UI; use HeadlessStepper. Do not use for independent page sections; use Tabs or ExpansionPanel. Do not use for app route navigation; use Navigation, Breadcrumbs, Sidebar, or routing. Do not use for showing only a percentage; use ProgressBar. Do not use for product tours over existing UI; use GuidedTour. example topics: Basic Stepper, Stepper In Dialog, Stepper Vertical, Stepper Header Position, Stepper Without Header Border, Stepper That Displays Errors In The Steps, Stepper Responsive, Stepper Label Bottom Position selectors: `[ngsStepLabel]`, `button[ngsStepperNext]`, `button[ngsStepperPrevious]`, `ngs-step`, `ngs-stepper` exports: `Step`, `StepLabel`, `Stepper`, `StepperNext`, `StepperPrevious` inputs: `headerPosition`, `hideHeaderBorder`, `labelPosition`, `stickyHeader` tokens: `--ngs-color-border`, `--ngs-color-on-primary`, `--ngs-color-on-success`, `--ngs-color-on-surface`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-success`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-highest`, `--ngs-color-surface-container-lowest`, `--ngs-stepper-content-padding`, `--ngs-stepper-header-border-color`, `--ngs-stepper-header-gap`, `--ngs-stepper-header-padding`, `--ngs-stepper-icon-active-bg`, `--ngs-stepper-icon-active-color` - suggestions: `@ngstarter-ui/components/suggestions` docs: /components/suggestions purpose: Render a grouped visual list of contextual suggestions, search results, recent items, or shortcuts. use when: Use ngs-suggestions as the visual list inside search dropdowns, assistant inputs, command-like panels, or contextual suggestion popovers. Group related rows with ngs-suggestion-block, use ngs-suggestion for each clickable row, place icons with ngsSuggestionIcon, thumbnails or avatars with ngsSuggestionThumb, and use inline blocks for quick actions such as create buttons. Good for recently viewed items, users, files, pages, matching search results, and quick create shortcuts. Do not use Suggestions as a form value picker; use Autocomplete or Select. Do not use it for a short contextual command menu; use Menu. Do not use it for persistent app navigation; use Navigation, Sidebar, Sidenav, or RailNav. Do not use it as a complete command palette by itself; it can provide the grouped visual result list, but search state, keyboard handling, filtering, and command execution belong to the surrounding feature. Do not use it for page-level empty-state recommendations or assistant cards; compose those with EmptyState, Card, Alert, or the page layout. example topics: Basic suggestions selectors: `[ngs-suggestion]`, `[ngsSuggestionIcon]`, `[ngsSuggestionThumb]`, `ngs-suggestion`, `ngs-suggestion-block`, `ngs-suggestions` exports: `Suggestion`, `SuggestionBlock`, `SuggestionIconDirective`, `Suggestions`, `SuggestionThumbDirective` inputs: `heading`, `inline`, `showDivider` tokens: `--ngs-avatar-size`, `--ngs-color-on-surface`, `--ngs-color-surface-bright`, `--ngs-color-surface-container-high`, `--ngs-color-surface-container-low`, `--ngs-color-surface-container-lowest`, `--ngs-font-size-sm`, `--ngs-font-size-xs`, `--ngs-suggestion-block-content-padding`, `--ngs-suggestion-block-font-size`, `--ngs-suggestion-block-font-weight`, `--ngs-suggestion-block-heading-color`, `--ngs-suggestion-border-radius`, `--ngs-suggestion-height`, `--ngs-suggestion-hover-bg`, `--ngs-suggestion-padding` - tab-panel: `@ngstarter-ui/components/tab-panel` docs: /navigation/tab-panel purpose: Create a compact vertical tool or navigation panel with a linked aside content area. use when: Use ngs-tab-panel when a workspace or editor needs a vertical set of icon/text items that controls adjacent aside content. Use ngs-tab-panel-content with ngs-tab-panel-nav and ngs-tab-panel-item for the rail, bind items to content with matching for values and ngsTabPanelAsideContent ids inside ngs-tab-panel-aside, and use activeItemId to choose the active item. Good for image editors, design tools, asset panels, layers, inspectors, workspace switchers, tool palettes, and settings/tools inside dense work surfaces. Use compact for icon-only rails with tooltips, header/content/footer regions to group items, and ngs-tab-panel-custom-item for custom items such as avatars, workspaces, or add actions. Do not use TabPanel for ordinary horizontal page tabs; use Tabs. Do not use it for primary app navigation; use Sidebar, Navigation, Sidenav, or RailNav. Do not use it for temporary overlay side content; use Drawer. Do not use it for a structured page section; use Panel. Do not use it for workflow steps; use Stepper. Do not use it for contextual command lists; use Menu. example topics: Basic tab panel, Tab panel with panel inside, Tab panel compact state, Tab panel with panels inside, Tab panel compact selectors: `[ngsTabPanelAsideContent]`, `[ngsTabPanelItemIcon]`, `ngs-tab-panel`, `ngs-tab-panel-aside`, `ngs-tab-panel-content`, `ngs-tab-panel-custom-item`, `ngs-tab-panel-footer`, `ngs-tab-panel-header`, `ngs-tab-panel-item`, `ngs-tab-panel-item-text`, `ngs-tab-panel-nav` exports: `TAB_PANEL_ASIDE`, `TAB_PANEL_NAV`, `TabPanel`, `TabPanelApiService`, `TabPanelAside`, `TabPanelAsideContentDirective`, `TabPanelContent`, `TabPanelCustomItem`, `TabPanelFooter`, `TabPanelHeader`, `TabPanelItem`, `TabPanelItemIconDirective` inputs: `activeItemId`, `compact`, `for`, `hideContentIfTabNotSelected`, `ngsTabPanelAsideContent` outputs: `itemIdChanged` tokens: `--ngs-font-size-xs`, `--ngs-nav-item-active-bg`, `--ngs-nav-item-active-color`, `--ngs-nav-item-color`, `--ngs-nav-item-hover-bg`, `--ngs-nav-item-hover-color`, `--ngs-nav-item-radius`, `--ngs-tab-panel-aside-width`, `--ngs-tab-panel-compact-item-height`, `--ngs-tab-panel-compact-item-width`, `--ngs-tab-panel-compact-width`, `--ngs-tab-panel-item-active-bg`, `--ngs-tab-panel-item-active-color`, `--ngs-tab-panel-item-border-radius`, `--ngs-tab-panel-item-color`, `--ngs-tab-panel-item-gap` - table: `@ngstarter-ui/components/table` docs: /components/table purpose: Render static or simple template-defined tabular data with known columns. use when: Use table[ngs-table] or ngs-table for static or simple tabular data where columns are known in Angular templates: read-only tables, documentation tables, settings summaries, static comparison rows, lightweight report tables, and small non-interactive admin tables. Define columns with ngsColumnDef, header/body/footer cells with ngsHeaderCellDef, ngsCellDef, and ngsFooterCellDef, and rows with ngsHeaderRowDef, ngsRowDef, and ngsFooterRowDef. Use TableDataSource only for lightweight local table behavior, not as a replacement for a real datatable. Use sticky/stickyEnd for fixed columns and sticky row defs for sticky header or footer. Use table[ngs-native-table] only for static HTML tables without a data source. Do not build tables with div role="table" or custom grid markup when ngs-table fits. Use DataView instead when the UI is a datatable or working data surface with row actions, selection, sorting, search/filter state, pagination, column sizing/settings, saved views, server-driven data, or complex record management. Use List for simple vertical rows without real columns. Use Tree for hierarchical rows. Use Grid or Tiles for dashboard layouts. Use Sort only for sort state behavior; it does not replace Table. example topics: Native Table, Basic Table, Table With Pagination, Table With Sorting, Table With Filtering, Table With Selection, Table With Fixed Columns, Table With Fixed Header selectors: `[ngs-cell]`, `[ngs-footer-cell]`, `[ngs-footer-row]`, `[ngs-header-cell]`, `[ngs-header-row]`, `[ngs-row]`, `[ngsCellDef]`, `[ngsColumnDef]`, `[ngsFooterCellDef]`, `[ngsFooterRowDef]`, `[ngsHeaderCellDef]`, `[ngsHeaderRowDef]`, `[ngsRowDef]`, `ng-template[ngsNoDataRow]`, `ngs-cell`, `ngs-footer-cell`, `ngs-footer-row`, `ngs-header-cell`, `ngs-header-row`, `ngs-row`, `ngs-table`, `ngs-text-column`, `table[ngs-native-table]`, `table[ngs-table]`, `td[ngs-cell]`, `td[ngs-footer-cell]`, `th[ngs-header-cell]`, `tr[ngs-footer-row]`, `tr[ngs-header-row]`, `tr[ngs-row]` exports: `Cell`, `CellDef`, `ColumnDef`, `FooterCell`, `FooterCellDef`, `FooterRow`, `FooterRowDef`, `HeaderCell`, `HeaderCellDef`, `HeaderRow`, `HeaderRowDef`, `NativeTable` inputs: `columns`, `hideBody`, `hideFooter`, `hideHeader`, `name`, `sticky`, `when` tokens: `--ngs-color-surface-container`, `--ngs-data-view-header-bg`, `--ngs-data-view-hl-header-margin`, `--ngs-data-view-hl-header-row-bg`, `--ngs-data-view-row-bg`, `--ngs-radius-lg`, `--ngs-table-background`, `--ngs-table-border-color`, `--ngs-table-cell-font-size`, `--ngs-table-cell-padding`, `--ngs-table-header-bg`, `--ngs-table-header-cell-background`, `--ngs-table-header-cell-color`, `--ngs-table-header-cell-font-size`, `--ngs-table-header-cell-font-weight`, `--ngs-table-header-row-height` - tabs: `@ngstarter-ui/components/tabs` docs: /components/tabs purpose: Switch between peer views inside one page or section context, with only one panel visible at a time. use when: Use ngs-tab-group with ngs-tab for local content tabs that do not require routing. Use ngs-tab-nav-bar with a[ngs-tab-link] and ngs-tab-nav-panel for route-linked tabs inside one section, such as documentation overview/API pages or detail subsections. Good for entity details, settings subsections, overview/activity/files/settings pages, alternate views of one object, or peer panels that share the same context. Supports selectedIndex, selectedIndexChange, selectedTabChange, disabled tabs, custom ngsTabLabel templates, explicit ngsTabContent templates, preserveContent, stretchTabs, alignTabs, headerPosition above/below, overflow pagination controls, and animationDuration/custom animations. Do not use Tabs for compact mode or value switches; use Segmented. Do not use for wizard or process steps; use Stepper. Do not use for vertical tool panels with linked aside content; use TabPanel. Do not use for primary app navigation; use Navigation, Sidebar, Sidenav, or RailNav. Do not use for collapsible sections; use ExpansionPanel. Do not use for route paths; use Breadcrumbs. Do not use for choosing a form value; use Select, Radio, RadioCard, Checkbox, or ButtonToggle depending on the interaction. example topics: Basic Tabs, Tabs with aligned labels, Tabs with custom label template, Tabs with the headers on the bottom, Paginated Tabs, Sortable Tabs, Tabs with custom animations, Tabs with headers on the bottom selectors: `[ngs-tab-content]`, `[ngs-tab-label]`, `[ngs-tab-nav-bar]`, `[ngsTabContent]`, `[ngsTabLabel]`, `a[ngs-tab-link]`, `ngs-tab`, `ngs-tab-group`, `ngs-tab-nav-bar`, `ngs-tab-nav-panel` exports: `Tab`, `TAB_CONTENT`, `TAB_LABEL`, `TabChangeEvent`, `TabContent`, `TabGroup`, `TabLabel`, `TabLink`, `TabNavBar`, `TabNavPanel` inputs: `animate.enter`, `animate.leave`, `animationDuration`, `aria-label`, `aria-labelledby`, `disabled`, `disableRipple`, `headerPosition`, `label`, `ngs-align-tabs`, `ngs-stretch-tabs`, `ngsRippleDisabled`, `preserveContent`, `selectedIndex`, `tabPanel` outputs: `focusChange`, `selectedIndexChange`, `selectedTabChange` tokens: `--ngs-color-border`, `--ngs-color-on-surface-variant`, `--ngs-color-primary`, `--ngs-color-surface-container-high`, `--ngs-tab-content-padding`, `--ngs-tab-group-animation-duration`, `--ngs-tab-group-header-border-bottom`, `--ngs-tab-group-header-border-top`, `--ngs-tab-group-header-height`, `--ngs-tab-group-pagination-control-after-border-left`, `--ngs-tab-group-pagination-control-before-border-right`, `--ngs-tab-label-active-border-bottom`, `--ngs-tab-label-active-border-top`, `--ngs-tab-label-active-color`, `--ngs-tab-label-color`, `--ngs-tab-label-cursor` - text-editor: `@ngstarter-ui/components/text-editor` docs: /components/text-editor purpose: Provide a full Tiptap-based WYSIWYG rich text editor for formatted HTML content. use when: Use ngs-text-editor when users need to create or edit rich HTML content with headings, bold, italic, strike, lists, blockquotes, inline code, code blocks, horizontal rules, links, images, YouTube embeds, toolbar commands, bubble menus, or floating menus. Good for product descriptions, project/task descriptions, CMS-like fields, articles, notes, changelog entries, release notes, knowledge base content, help content, and rich admin content bodies. Provide initial HTML through content, listen to contentChange for updated HTML, add custom Tiptap extensions through extensions, and use imageUploadFn to upload images and resolve a URL. Compose controls with ngs-text-editor-toolbar, ngs-text-editor-bubble-menu, ngs-text-editor-floating-menu, ngs-text-editor-divider, and ngsTextEditorCommand* directives. Do not use TextEditor for short comments, threads, or quick replies; use CommentEditor. Do not use it for block-based CMS/page building; use ContentEditor. Do not use it for plain text fields; use ngsInput inside FormField. Do not use it for inline renaming; use InlineTextEdit. Do not use it for read-only code or snippets; use CodeHighlighter. example topics: Basic Text Editor, Text Editor with floating menu, Text editor floating menu selectors: `[ngsTextEditorCommand]`, `[ngsTextEditorCommandBlockquote]`, `[ngsTextEditorCommandBold]`, `[ngsTextEditorCommandBulletList]`, `[ngsTextEditorCommandCode]`, `[ngsTextEditorCommandCodeBlock]`, `[ngsTextEditorCommandEditLink]`, `[ngsTextEditorCommandHeading]`, `[ngsTextEditorCommandHorizontalRule]`, `[ngsTextEditorCommandImage]`, `[ngsTextEditorCommandItalic]`, `[ngsTextEditorCommandLink]`, `[ngsTextEditorCommandOrderedList]`, `[ngsTextEditorCommandStrike]`, `[ngsTextEditorCommandUnsetLink]`, `[ngsTextEditorCommandYoutube]`, `ngs-image-uploading-placeholder`, `ngs-link`, `ngs-text-editor`, `ngs-text-editor-bubble-menu`, `ngs-text-editor-divider`, `ngs-text-editor-floating-menu`, `ngs-text-editor-toolbar`, `ngs-youtube` exports: `AngularNodeView`, `AngularNodeViewRenderer`, `AngularRenderer`, `ImageUploadingPlaceholder`, `LinkDialog`, `TEXT_EDITOR`, `TEXT_EDITOR_BUBBLE_MENU`, `TextEditor`, `TextEditorAPI`, `TextEditorBubbleMenu`, `TextEditorCommandBlockquoteDirective`, `TextEditorCommandBoldDirective` inputs: `content`, `contentMaxHeight`, `decorations`, `deleteNode`, `editor`, `extension`, `extensions`, `getPos`, `innerDecorations`, `level`, `node`, `placeholder`, `selected`, `updateAttributes`, `view` outputs: `contentChange`, `fileSelected` tokens: `--ngs-color-border`, `--ngs-color-neutral-100`, `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-500`, `--ngs-color-neutral-650`, `--ngs-color-neutral-700`, `--ngs-color-neutral-900`, `--ngs-color-neutral-950`, `--ngs-color-tertiary-100`, `--ngs-color-tertiary-200`, `--ngs-color-tertiary-300`, `--ngs-color-tertiary-700`, `--ngs-color-tertiary-800`, `--ngs-font-size-sm`, `--ngs-font-size-xl` - thumbnail-maker: `@ngstarter-ui/components/thumbnail-maker` docs: /components/thumbnail-maker purpose: Create a square 300x300 thumbnail bitmap from an image with drag positioning and zoom controls. use when: Use ngs-thumbnail-maker when users need to position and zoom an image inside a fixed square frame, then save the finished thumbnail as a data URL, Blob, or canvas. Good for avatars, profile images, CMS thumbnails, media library previews, product/user/project card images, and simple square preview generation. Provide the image URL or data URL through src, add helperText when users need drag instructions, and call api.getDataUrl(), api.toBlob(callback), or api.getCanvas() when saving. Combine with Upload or ngsUploadTrigger when users must select a local image first. Do not use ThumbnailMaker when the app needs arbitrary crop shapes, crop rectangles, circles, or crop coordinates; use Crop. Do not use it only to change displayed image width; use ImageResizer. Do not use it to view images; use ImageViewer or ImageZoomViewer. Do not use it as an image placeholder; use ImagePlaceholder. Do not use it for full canvas editing, layers, text, effects, or templates; use ImageDesigner. Do not use it as a plain upload picker without editing; use Upload. example topics: Basic thumbnail maker, Thumbnail maker with helper text, Thumbnail maker with file select selectors: `[ngsDragImage]`, `ngs-thumbnail-maker` exports: `DragImageDirective`, `ThumbnailMaker`, `ThumbnailMakerApi` inputs: `content`, `helperText`, `scale`, `src` tokens: `--ngs-color-neutral-950`, `--ngs-font-size-xs`, `--ngs-radius-lg`, `--ngs-thumbnail-height`, `--ngs-thumbnail-width` - tiles: `@ngstarter-ui/components/tiles` docs: /components/tiles purpose: Lay out responsive dashboard tiles and support user-driven tile reordering/customization. use when: Use ngs-tiles with ngs-tile when users can rearrange dashboard cards or widgets, customize a dashboard, or save a changed widget order. Good for editable dashboards, portal home pages, workspace widgets, configurable analytics cards, media/card boards, and dashboard builders. Tiles can be the layout host for config-driven dashboard renderers: the app can render lazy widget components inside each ngs-tile, show Skeleton while widgets load, and persist the final item order from orderChanged or layoutChanged. Use width, height, width.sm/md/lg/xl, and height.sm/md/lg/xl to define responsive tile spans, and ngsTileHandle for drag handles. Provide items so reorder events can map visual order back to app data. Use Grid only for static predefined dashboard/widget layouts that users do not rearrange. Do not use Tiles for ordinary static responsive page layout; use TailwindCSS grid/flex. Do not use for split panes with gutters; use Split. Do not use for one manually resized box; use ResizableContainer. Do not use for simple cards, lists, tables, or datasets without tile reordering; use Card, List, Table, or DataView. Do not use for status-column workflows; use KanbanBoard. example topics: Basic tiles selectors: `[ngsTileHandle]`, `ngs-tile`, `ngs-tiles` exports: `ReorderFunction`, `Tile`, `TileHandleDirective`, `Tiles`, `TILES_REORDER`, `TileService`, `tilesShift`, `tilesSwap` inputs: `columns`, `gap`, `height`, `height.lg`, `height.md`, `height.sm`, `height.xl`, `items`, `width`, `width.lg`, `width.md`, `width.sm`, `width.xl` outputs: `layoutChanged`, `orderChanged` tokens: `--ngs-color-border`, `--ngs-color-surface-container`, `--ngs-radius-xl`, `--ngs-tile-h`, `--ngs-tile-h-lg`, `--ngs-tile-h-md`, `--ngs-tile-h-sm`, `--ngs-tile-h-xl`, `--ngs-tile-w`, `--ngs-tile-w-lg`, `--ngs-tile-w-md`, `--ngs-tile-w-sm`, `--ngs-tile-w-xl`, `--ngs-tiles-columns`, `--ngs-tiles-gap`, `--ngs-tiles-row-height` - timeline: `@ngstarter-ui/components/timeline` docs: /components/timeline purpose: Show a vertical chronological history of events. use when: Use ngs-timeline when users need to understand a sequence of events over time: audit logs, activity history, entity change history, project milestones, order or shipment history, workflow history, tracking events, and user actions. Use ngs-timeline-header to group events by date, month, phase, or period. Use ngs-timeline-item with ngs-timeline-timestamp, ngs-timeline-title, ngs-timeline-subtitle, ngs-timeline-description, ngs-timeline-attributes, and ngs-timeline-content to structure each event. Use ngsTimelineItemIndicator when the marker should show an actor, icon, status, or event type. Do not use Timeline for a realtime notification inbox or actionable notification feed; use Notifications. Do not use for a simple vertical collection without time/order meaning; use List. Do not use for tabular audit logs that need sorting, filtering, or many columns; use Table or DataView. Do not use for workflow steps the user must complete; use Stepper. Do not use for status columns; use KanbanBoard. Do not use for calendar/scheduler views or for a single operation status; use ProgressBar, Badge, or Status as appropriate. example topics: Basic Timeline, Timeline With Timestamp, Timeline With Custom Indicator, Timeline timestamp, Timeline with cutsom indicator selectors: `[ngsTimelineItemIndicator]`, `ngs-timeline`, `ngs-timeline-attributes`, `ngs-timeline-content`, `ngs-timeline-description`, `ngs-timeline-header`, `ngs-timeline-item`, `ngs-timeline-subtitle`, `ngs-timeline-timestamp`, `ngs-timeline-title` exports: `Timeline`, `TimelineAttributes`, `TimelineContent`, `TimelineDescription`, `TimelineHeader`, `TimelineItem`, `TimelineItemIndicatorDirective`, `TimelineSubtitle`, `TimelineTimestamp`, `TimelineTitle` tokens: `--ngs-color-muted`, `--ngs-color-neutral-500`, `--ngs-color-neutral-800`, `--ngs-font-size-sm`, `--ngs-font-size-xs`, `--ngs-timeline-header-bg`, `--ngs-timeline-header-color`, `--ngs-timeline-header-font-size`, `--ngs-timeline-header-font-weight`, `--ngs-timeline-header-height`, `--ngs-timeline-header-padding`, `--ngs-timeline-header-text-transform`, `--ngs-timeline-indicator-bg`, `--ngs-timeline-indicator-border`, `--ngs-timeline-indicator-line-offset`, `--ngs-timeline-indicator-offset` - timepicker: `@ngstarter-ui/components/timepicker` docs: /components/timepicker purpose: Let users choose or type a time of day in a form field. use when: Use input[ngsTimepicker] inside one ngs-form-field, connected to an ngs-timepicker instance, when a form needs a time of day: meeting time, event time, booking time, reminder time, deadline time, availability slot, report time filter, or schedule setting. Add ngs-timepicker-toggle as an icon suffix when users should open the dropdown explicitly. Use interval to control option steps such as 15, 30, or 60 minutes. Use min and max to limit selectable times. The input supports manual typing and localized display, while the model value can be a HH:mm-like string or a Date with the selected time merged into it. Combine Datepicker and Timepicker as separate controls when users need both date and time. Do not use Timepicker to choose a date; use Datepicker. Do not use it to choose a timezone; use TimezoneSelect. Do not use it for duration or numeric amounts of hours/minutes; use NumberInput or Slider. Do not use it for plain text without time validation; use ngsInput. Do not use it as a calendar, scheduler, or day-slot planner. example topics: Basic time picker, Integration with Datepicker, Customizing the toggle icon, Timepicker with interval, Basic timepicker, Timepicker with datepicker, Timepicker custom toggle icon, Timepicker interval selectors: `[ngsTimepickerToggleIcon]`, `input[ngsTimepicker]`, `ngs-timepicker`, `ngs-timepicker-toggle` exports: `Timepicker`, `TIMEPICKER_CONFIG`, `TimepickerConfig`, `TimepickerInput`, `TimepickerIntl`, `TimepickerToggle`, `TimepickerToggleIcon` inputs: `disabled`, `for`, `interval`, `max`, `min`, `ngsTimepicker`, `openOnClick` outputs: `closed`, `opened` tokens: `--ngs-dropdown-bg`, `--ngs-dropdown-border`, `--ngs-dropdown-padding`, `--ngs-dropdown-radius`, `--ngs-dropdown-shadow`, `--ngs-timepicker-content-padding` - timezone-select: `@ngstarter-ui/components/timezone-select` docs: /forms/timezone purpose: Let users choose an IANA time zone id in a form field. use when: Use ngs-timezone-select inside one ngs-form-field when a form must store a real time zone id such as Europe/Warsaw or America/New_York. Good for profile timezone, account preferences, organization or tenant default timezone, scheduling settings, calendar settings, report default timezone, localization preferences, and admin settings where backend data needs an IANA timezone string. The control is searchable, groups time zones by region, supports Angular forms, required, disabled, placeholder, locale-aware labels, opened, and closed. Do not use TimezoneSelect to choose a time of day; use Timepicker. Do not use it to choose a date; use Datepicker. Do not use it to choose a country or region; use CountrySelect. Do not use it for language or locale selection; use a dedicated locale/language control or Select. Do not use it for generic custom options; use Select. Do not use it for durations, numeric offsets, or timezone math; use NumberInput, Slider, or app logic. Do not use timezone as a date format setting; use DateFormatSelect for display formats. example topics: Basic timezone select selectors: `ngs-timezone-select` exports: `FilterTimezonesPipe`, `LocalizedTimezone`, `TimezoneGroup`, `TimezoneSelect`, `TimezoneUtils` inputs: `aria-describedby`, `disabled`, `locale`, `placeholder`, `required`, `searchTerm`, `value` outputs: `closed`, `opened` - toolbar: `@ngstarter-ui/components/toolbar` docs: /components/toolbar purpose: Provide a persistent command area for a page, panel, table, editor, canvas, or workspace surface. use when: Use ngs-toolbar when a local surface needs a title, short local navigation, and frequently used actions in a stable horizontal or multi-row command area. Use ngs-toolbar-title for the local title, ngs-toolbar-spacer to separate groups, ngs-toolbar-row for multi-row command areas, ngs-toolbar-item for actions that should participate in responsive overflow, and ngs-toolbar-nav with ngs-toolbar-nav-link for short local links inside the toolbar. Good places include table headers, panel headers, admin page headers, editor surfaces, dashboards, canvas tools, and workspace tool surfaces. Do not use Toolbar as a generic flex layout for arbitrary content. Do not use it for floating contextual actions on selected rows or objects; use CommandBar. Do not use it for dropdown command lists; use Menu. Do not use it for primary application navigation; use Sidebar, Sidenav, or Navigation. Do not replace specialized TextEditor or CommentEditor toolbars with the generic Toolbar. example topics: Basic Toolbar, Multi-row Toolbar, Toolbar with items, Responsive Toolbar with Overflow Menu, Responsive Toolbar Navigation, Toolbar overflow, Toolbar nav selectors: `a[ngs-toolbar-nav-link]`, `ngs-toolbar`, `ngs-toolbar-item`, `ngs-toolbar-nav`, `ngs-toolbar-nav-link`, `ngs-toolbar-row`, `ngs-toolbar-spacer`, `ngs-toolbar-subtitle`, `ngs-toolbar-title` exports: `Toolbar`, `ToolbarBaseItem`, `ToolbarItem`, `ToolbarNav`, `ToolbarNavLink`, `ToolbarRow`, `ToolbarSpacer`, `ToolbarSubtitle`, `ToolbarTitle`, `ToolbarTitleAppearance` inputs: `active`, `appearance`, `hidden` tokens: `--ngs-color-secondary`, `--ngs-font-size-lg`, `--ngs-font-size-sm`, `--ngs-nav-item-active-color`, `--ngs-nav-item-color`, `--ngs-nav-item-font-size`, `--ngs-nav-item-height`, `--ngs-nav-item-hover-color`, `--ngs-nav-item-padding`, `--ngs-nav-item-radius`, `--ngs-toolbar-gap`, `--ngs-toolbar-nav-link-active-color`, `--ngs-toolbar-nav-link-color`, `--ngs-toolbar-nav-link-font-size`, `--ngs-toolbar-nav-link-hover-color`, `--ngs-toolbar-nav-link-overflow-height` - tooltip: `@ngstarter-ui/components/tooltip` docs: /components/tooltip purpose: Show a short helper message for one interface element on hover, focus, or touch. use when: Use ngsTooltip as a directive on a trigger element when a short non-interactive helper message should explain an icon button, abbreviation, disabled state, dense control, compact label, or unclear affordance. Configure ngsTooltipPosition, ngsTooltipShowDelay, ngsTooltipHideDelay, ngsTooltipOffset, ngsTooltipDisabled, ngsTooltipClass, or ngsTooltipPositionAtOrigin when placement and timing need tuning. Export the directive as ngsTooltip when app logic must call show(), hide(), or toggle(). Keep tooltip text short and plain. Do not use Tooltip for interactive content, forms, action lists, rich previews, or long explanations; use Popover. Do not use it for command menus; use Menu. Do not use it for visible page messages; use Alert, Announcement, ActionRequired, or Incidents based on scope. Do not use it for form helper or validation text; use FormField hint and error. Do not use it for onboarding flows; use GuidedTour. example topics: Basic Tooltip, Tooltip With a Custom Position, Tooltip show and hide delay, Tooltip manually showing and hiding, Tooltip disabled, Tooltip position at origin, Tooltip show hide delay, Tooltip manually show hide selectors: `[ngsTooltip]`, `ngs-tooltip-content` exports: `Tooltip`, `TOOLTIP_DEFAULT_OPTIONS`, `TooltipContent`, `TooltipDefaultOptions`, `TooltipPosition`, `TooltipVisibility` inputs: `ngsTooltip`, `ngsTooltipClass`, `ngsTooltipDisabled`, `ngsTooltipHideDelay`, `ngsTooltipOffset`, `ngsTooltipPosition`, `ngsTooltipPositionAtOrigin`, `ngsTooltipShowDelay` tokens: `--ngs-color-neutral-100`, `--ngs-color-neutral-950`, `--ngs-font-size-xs`, `--ngs-radius-md`, `--ngs-tooltip-border-radius`, `--ngs-tooltip-container-color`, `--ngs-tooltip-font-size`, `--ngs-tooltip-handset-font-size`, `--ngs-tooltip-handset-padding`, `--ngs-tooltip-line-height`, `--ngs-tooltip-max-width`, `--ngs-tooltip-padding`, `--ngs-tooltip-supporting-text-color` - tree: `@ngstarter-ui/components/tree` docs: /components/tree purpose: Display hierarchical data with expandable parent and child nodes. use when: Use ngs-tree when users need to inspect or navigate hierarchical data where parent and child levels matter: folders and files, categories, permissions, taxonomies, organization structures, nested settings, product/entity hierarchies, and other expandable trees. Use dataSource with childrenAccessor for nested/static data, or treeControl with a custom DataSource for flat trees and dynamic loading. Define node templates with *ngsTreeNodeDef and use when for different node types. Use ngsTreeNodePadding for indentation and ngsTreeNodeToggle for expand/collapse controls. Use ProgressBar or Skeleton inside node templates when children load on demand. Do not use Tree for a simple vertical collection; use List. Do not use it for primary application navigation; use Sidebar, Sidenav, Navigation, or RailNav. Do not use it for FAQ or settings sections; use ExpansionPanel. Do not use it for dense row data with columns, sorting, filters, or bulk actions; use Table or DataView. Do not use it for step-by-step workflows; use Stepper. example topics: Basic tree, Selectable tree, Checkable tree, Draggable tree, Searchable tree, Tree with dynamic data selectors: `[ngsTreeNodeDef]`, `[ngsTreeNodeOutlet]`, `[ngsTreeNodePadding]`, `[ngsTreeNodeToggle]`, `ng-template[ngsTreeDragPlaceholder]`, `ngs-nested-tree-node`, `ngs-tree`, `ngs-tree-node` exports: `NestedTreeNode`, `Tree`, `TreeDragPlaceholder`, `TreeDragPreview`, `TreeFilterMode`, `TreeFilterPredicate`, `TreeNode`, `TreeNodeDef`, `TreeNodeDragPlaceholderContext`, `TreeNodeDragPredicate`, `TreeNodeDrop`, `TreeNodeDropContext` inputs: `checkable`, `childrenKey`, `disabled`, `draggable`, `dragPreview`, `filterMode`, `filterValue`, `ngsNestedTreeNode`, `ngsTreeNode`, `ngsTreeNodeDefWhen`, `ngsTreeNodePadding`, `ngsTreeNodePaddingIndent`, `ngsTreeNodeToggleRecursive`, `nodePaddingIndent`, `recursive`, `reorderOnDrop`, `selectable`, `tabIndex`, `value`, `when` outputs: `activation`, `checkedChange`, `expandedChange`, `selectedChange` tokens: `--ngs-checkbox-gap`, `--ngs-color-neutral`, `--ngs-color-primary`, `--ngs-color-surface`, `--ngs-nav-item-active-bg`, `--ngs-nav-item-active-color`, `--ngs-nav-item-color`, `--ngs-nav-item-font-size`, `--ngs-nav-item-gap`, `--ngs-nav-item-height`, `--ngs-nav-item-hover-bg`, `--ngs-nav-item-hover-color`, `--ngs-nav-item-radius`, `--ngs-shadow-md`, `--ngs-tree-container-background-color`, `--ngs-tree-gap` - upload: `@ngstarter-ui/components/upload` docs: /components/upload purpose: Provide UI for selecting files, drag-and-drop upload areas, and file progress displays. use when: Use Upload components when users need to choose local files, drop files into an upload area, or see selected/uploading files with progress, errors, retry, remove, or cancel actions. Use ngsUploadTrigger on a button or clickable element to open the native file picker. Use ngs-upload-area for drag-and-drop with ngsUploadAreaMainState, ngsUploadAreaDropState, ngsUploadAreaInvalidState, and ngsUploadAreaIcon. Use accept and multiple to control allowed file types and multi-select. Use ngs-upload-container with ngs-upload-allowed-types and ngs-upload-max-file-size for upload hints. Use ngs-file-list with ngs-file for vertical file rows, or ngs-files-grid with ngs-grid-file for compact file cards. Use ngs-file-control and ngsGridFileControl for file-level actions. The component emits fileSelected with the selected File objects; the application must perform validation, backend upload, retry, deletion, persistence, and security checks. Do not treat Upload as a backend uploader, storage manager, or import wizard by itself. Do not use it for editing selected images; use Crop, ImageResizer, ThumbnailMaker, or ImageDesigner after selection. Do not use it for rich editor image upload flows; use the TextEditor or CommentEditor upload APIs. Do not use it to manage an existing document table with sorting and filtering; use Table or DataView. example topics: Basic Upload, Upload area, File list, File grid selectors: `[ngs-file-control]`, `[ngsFileIcon]`, `[ngsGridFileControl]`, `[ngsUploadAreaDropState]`, `[ngsUploadAreaIcon]`, `[ngsUploadAreaInvalidState]`, `[ngsUploadAreaMainState]`, `[ngsUploadTrigger]`, `ngs-file`, `ngs-file-control`, `ngs-file-list`, `ngs-files-grid`, `ngs-grid-file`, `ngs-list-file`, `ngs-upload-allowed-types`, `ngs-upload-area`, `ngs-upload-container`, `ngs-upload-max-file-size` exports: `File`, `FileControl`, `FileIconDirective`, `FileList`, `FilesGrid`, `GridFile`, `GridFileControlDirective`, `ListFile`, `UploadAllowedTypes`, `UploadArea`, `UploadAreaDropStateDirective`, `UploadAreaIconDirective` inputs: `accept`, `allowHover`, `errorMessage`, `multiple`, `name`, `progress`, `progressingMessage`, `remainingTime`, `size`, `state` outputs: `fileSelected` tokens: `--ngs-color-danger`, `--ngs-color-danger-container-high`, `--ngs-color-danger-container-low`, `--ngs-color-neutral-300`, `--ngs-color-neutral-500`, `--ngs-color-neutral-600`, `--ngs-color-primary`, `--ngs-color-subtle`, `--ngs-color-surface-container`, `--ngs-color-surface-container-highest`, `--ngs-file-bg`, `--ngs-file-border-radius`, `--ngs-file-control-color`, `--ngs-file-control-font-size`, `--ngs-file-control-hover-color`, `--ngs-file-controls-gap` - video-player: `@ngstarter-ui/components/video-player` docs: /libraries/video-player purpose: Play video inline inside the current page, card, carousel, media preview, lesson, or workspace layout. use when: Use ngs-video-player when video should stay embedded in the current layout with NgStarter-controlled playback UI. Pass src for the video source, optional thumbnailUrl for the poster preview, and orientation or payload.orientation for landscape, portrait, or square aspect ratio. Configure autoPlay, muted, disableClickToPlay, withCredentials, showPlayButton, showSpeaker, showFullscreen, and showDurationSlider to match the surface. Listen to play, pause, ended, loaded, and error for application state. Good for media previews, lessons, product videos, content previews, cards, carousel slides, and dashboard/workspace media blocks. The player wraps video.js and supports HLS m3u8 sources through video.js. Do not use VideoPlayer when the video should open as a focused overlay or lightbox; use VideoViewer. Do not use it as a gallery or list by itself; compose it with Carousel, Card, Grid, VideoViewer, or a layout component. Do not use it for YouTube, Vimeo, or other iframe-provider embeds when the provider player is required. Do not use it as a content editing API directly; use the ContentEditor video block for editable content. example topics: Video Player selectors: `ngs-video-player` exports: `VideoPlayer`, `VideoPlayerInterface`, `VideoPlayerOrientation`, `VideoPlayerService` inputs: `autoPlay`, `disableClickToPlay`, `muted`, `orientation`, `payload`, `showDurationSlider`, `showFullscreen`, `showPlayButton`, `showSpeaker`, `src`, `thumbnailUrl`, `withCredentials` outputs: `ended`, `error`, `loaded`, `pause`, `play` - video-viewer: `@ngstarter-ui/components/video-viewer` docs: /components/video-viewer purpose: Open videos in a focused overlay or lightbox above the current page. use when: Use VideoViewer when a thumbnail, preview card, compact inline player, attachment, gallery item, or media library item should open a larger focused video viewing experience. Put ngsVideoViewer on the preview container and ngsVideoViewerVideo on each clickable preview item. Pass sourceUrl for the video source, plus optional title, caption, description, or template directives ngsVideoViewerVideoTitle, ngsVideoViewerVideoCaption, and ngsVideoViewerVideoDescription. Configure orientation, payload, autoPlay, muted, showPlayButton, showSpeaker, showFullscreen, and showDurationSlider to control the underlying VideoPlayer in the overlay. Good for video attachments, media previews, galleries, lessons, product videos, and media detail flows. Do not use VideoViewer when video should stay inline in the current layout; use VideoPlayer. Do not use it as a carousel, grid, or gallery layout by itself; compose previews with Card, Grid, Carousel, or another layout. Do not use it as a generic modal or form dialog; use Dialog or Drawer. Do not use it for YouTube, Vimeo, or iframe-provider embeds when the provider player is required. example topics: Basic Video Viewer selectors: `[ngsVideoViewer]`, `[ngsVideoViewerVideo]`, `[ngsVideoViewerVideoCaption]`, `[ngsVideoViewerVideoDescription]`, `[ngsVideoViewerVideoTitle]`, `ngs-video-viewer` exports: `VIDEO_VIEWER`, `VIDEO_VIEWER_DATA`, `VIDEO_VIEWER_REF`, `VideoViewer`, `VideoViewerDirective`, `VideoViewerOptions`, `VideoViewerOrientation`, `VideoViewerRef`, `VideoViewerVideoCaptionDirective`, `VideoViewerVideoDescriptionDirective`, `VideoViewerVideoDirective`, `VideoViewerVideoTitleDirective` inputs: `autoPlay`, `caption`, `description`, `muted`, `orientation`, `payload`, `showDurationSlider`, `showFullscreen`, `showPlayButton`, `showSpeaker`, `sourceUrl`, `title` tokens: `--ngs-color-neutral-100`, `--ngs-color-neutral-200`, `--ngs-color-neutral-300`, `--ngs-color-neutral-400`, `--ngs-color-neutral-50`, `--ngs-color-neutral-600`, `--ngs-color-neutral-700`, `--ngs-color-neutral-800`, `--ngs-color-neutral-900`, `--ngs-color-neutral-950`, `--ngs-font-size-sm`, `--ngs-shadow-sm` - visual-builder: `@ngstarter-ui/components/visual-builder` docs: /libraries/visual-builder purpose: Experimental scaffold for a future no-code or low-code visual workspace. use when: Do not use ngs-visual-builder for production admin screens, dashboards, visual editors, page builders, or real no-code/low-code workflows yet. The current component is only a placeholder: it has no inputs, outputs, layout regions, canvas, drag and drop, inspector, persistence, or editable block model. Mention it only as an experimental scaffold for future visual builder work. Use ContentEditor for block-based CMS/page content, ImageDesigner for creative image composition, Tiles for editable dashboard widgets or config-driven dashboard renderers, Grid for static dashboard layouts, Form Builder for schema-driven forms, KanbanBoard for workflow columns, and normal NgStarter layout/components for admin screens. example topics: Visual Builder selectors: `ngs-visual-builder` exports: `VisualBuilder`