# @theredhead/lucid-kit Core reusable UI components library for theredhead Angular applications. Every component is **standalone**, uses **signal-based** inputs/state, and **OnPush** change detection. There are no runtime dependencies beyond Angular core and `@angular/cdk`. > **Early-stage — not production ready.** This package is still undergoing > active development and is subject to breaking changes without notice until > a stable `1.0` release. --- ## Components at a glance | Component | Selector | Description | | -------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **UIButton** | `ui-button` | Push button with `filled`, `outlined`, `text`, and `ghost` variants | | **UIInput** | `ui-input` | Styled text input with label and two-way `[(value)]` binding | | **UIDropdownList** | `ui-dropdown-list` | Popup dropdown select with `SelectOption[]` binding and keyboard nav | | **UICheckbox** | `ui-checkbox` | Styled checkbox with label and two-way model | | **UIRadioGroup / UIRadioButton** | `ui-radio-group` / `ui-radio-button` | Radio button group with two-way value binding | | **UISlider** | `ui-slider` | Range slider supporting single-value and range modes | | **UIDatePicker** | `ui-date-picker` | Calendar date picker with locale-aware formatting, min/max constraints | | **UITimePicker** | `ui-time-picker` | Time input supporting 12 h / 24 h modes, step intervals | | **UIDateTimePicker** | `ui-date-time-picker` | Composite control combining date picker + time picker | | **UIAutocomplete** | `ui-autocomplete` | Type-ahead input with popup suggestions, inline chip multi-select, contenteditable-style arrow-key cursor navigation between chips and text, `chipColor` for per-chip theming | | **UIFilter** | `ui-filter` | Predicate builder (AND/OR) emitting `Predicate` for datasource use | | **UITableView** | `ui-table-view` | Virtual-scrolling data table with sortable columns, selection, pagination | | **UITreeView** | `ui-tree-view` | Hierarchical tree with expand/collapse, selection, keyboard navigation | | **UIMapView** | `ui-map-view` | Tile-based map (zero-dep) with markers, polylines, polygons, interactive pan/zoom, editable GeoJSON line/polygon overlays, and feature collection editing | | **UIAccordion** | `ui-accordion` | Expandable/collapsible panels (single, collapsible, multi-expand modes) | | **UITabGroup / UITab** | `ui-tab-group` / `ui-tab` | Tabbed container with lazy-rendered tab panels | | **UIBadge** | `ui-badge` | Small status badge/label with colour variants | | **UIChip** | `ui-chip` | Rounded tag/chip with colour and optional removable | | **UIAvatar** | `ui-avatar` | Circular avatar with image, initials fallback, or Gravatar | | **UIIcon** | `ui-icon` | Inline SVG icon renderer with bundled icon registry | | **UIBreadcrumb** | `ui-breadcrumb` | Horizontal breadcrumb navigation trail | | **UIPagination** | `ui-pagination` | Page navigation bar with page-size selector | | **UIProgress** | `ui-progress` | Progress bar (determinate / indeterminate) with colour variants | | **UIRepeater** | `ui-repeater` | Template repeater with grid, flex-row, flex-column, masonry layouts | | **UIFileUpload** | `ui-file-upload` | Drag-and-drop file upload zone with accept filter and size limits | | **UIDialog** | `ui-dialog` | Modal dialog container with backdrop, size options | | **UIMediaGallery** | `ui-media-gallery` | Fullscreen mixed-media viewer or constrained inline collection viewer | ## Table View Columns The table view supports multiple column types that use Angular's dependency injection (DI) forwarding system for flexible column composition: - `ui-text-column` - Renders text values with optional truncation - `ui-badge-column` - Renders badge status values - `ui-number-column` - Renders formatted numbers - `ui-template-column` - Renders custom templates with projected content All column types extend `UITableViewColumn` and provide themselves via DI forwarding, enabling the parent table to discover all columns through a single `contentChildren()` query on the base class token. This pattern allows for extensibility - new column types can be added without modifying the parent table component. For more information about the column inheritance pattern, see [column-inheritance-pattern.md](src/lib/table-view/column-inheritance-pattern.md). ## Table View Columns The table view supports multiple column types that use Angular's dependency injection (DI) forwarding system for flexible column composition: - `ui-text-column` - Renders text values with optional truncation - `ui-badge-column` - Renders badge status values - `ui-number-column` - Renders formatted numbers - `ui-template-column` - Renders custom templates with projected content All column types extend `UITableViewColumn` and provide themselves via DI forwarding, enabling the parent table to discover all columns through a single `contentChildren()` query on the base class token. This pattern allows for extensibility - new column types can be added without modifying the parent table component. ### Directives | Directive | Selector | Description | | ---------------------- | ------------- | ----------------------------------------------------------- | | **UIDensityDirective** | `[uiDensity]` | Applies density CSS tokens (compact, comfortable, generous) | | **UITooltip** | `[uiTooltip]` | Tooltip popup on hover/focus | | **UIMediaGalleryItem** | `ui-image[gallery]`, `ui-media-player[gallery]` | Registers supported media hosts in a named or shared unnamed collection | ### Services | Service | Description | | ------------------ | -------------------------------------------------- | | **PopoverService** | Opens positioned popover overlays programmatically | | **ModalService** | Opens modal dialogs programmatically | | **MediaGalleryService** | Coordinates registered media collections and fullscreen navigation | --- ## Table View columns All columns extend `UITableViewColumn` and register via DI forwarding: | Column | Selector | Notes | | -------------------- | -------------------- | ---------------------------------- | | **UITextColumn** | `ui-text-column` | Plain text with optional truncate | | **UINumberColumn** | `ui-number-column` | Locale-aware number formatting | | **UIBadgeColumn** | `ui-badge-column` | Badge cell with variant colours | | **UITemplateColumn** | `ui-template-column` | Consumer-projected `` | ## Table View datasources | Class | Description | | --------------------------- | ---------------------------------------------------- | | `ArrayDatasource` | In-memory datasource backed by a plain array | | `FilterableArrayDatasource` | Extends `ArrayDatasource` with client-side filtering | | `RestDatasource` | HTTP-backed datasource for REST APIs | ## Tree View datasources | Class | Description | | --------------------- | -------------------------------------------------- | | `ArrayTreeDatasource` | In-memory tree datasource backed by nested objects | --- ## Quick start ```typescript import { UIButton, UITableView, UITextColumn } from "@theredhead/lucid-kit"; @Component({ selector: "app-demo", standalone: true, imports: [UIButton, UITableView, UITextColumn], template: ` Refresh `, }) export class DemoComponent { datasource = new ArrayDatasource(this.data); } ``` --- ## Features - No external runtime UI dependency — native browser controls - Fully typed with TypeScript - Signal-based reactive state (`input()`, `model()`, `computed()`, `effect()`) - Modern control flow in templates (`@if`, `@for`, `@switch`) - OnPush change detection throughout - Keyboard accessible with ARIA patterns - CSS custom-property theming (`--ui-*` tokens) - Light & dark mode support via three-tier pattern --- ## Cursor theme `@theredhead/lucid-kit` ships an optional cursor layer with semantic cursor tokens and utility classes. The default cursor theme uses the flat cursor set in light mode and switches to the shadow cursor set in dark mode. Enable it alongside the normal theme include: ```scss @use "@theredhead/lucid-theme/styles" as theme; @use "@theredhead/lucid-kit/styles" as ui-kit; @include theme.theredhead-theme(); @include ui-kit.ui-cursor-theme(); ``` The mixin sets semantic tokens such as `--ui-cursor-default`, `--ui-cursor-click`, `--ui-cursor-help`, `--ui-cursor-trash`, `--ui-cursor-external`, and `--ui-cursor-wait`. Common interactive controls in the library use the click token automatically when their styles route through the shared control mixins. You can also opt into explicit utility classes when a component or consumer template needs a specific cursor: - `.ui-cursor-default` - `.ui-cursor-click` - `.ui-cursor-help` - `.ui-cursor-add` - `.ui-cursor-remove` - `.ui-cursor-trash` - `.ui-cursor-external` - `.ui-cursor-wait` Flat and shadow variants are available as explicit classes too, for example: - `.ui-cursor-default-flat` - `.ui-cursor-default-shadow` - `.ui-cursor-click-flat` - `.ui-cursor-click-shadow` - `.ui-cursor-trash-flat` - `.ui-cursor-trash-shadow` - `.ui-cursor-external-flat` - `.ui-cursor-external-shadow` - `.ui-cursor-wait-outlined-flat` - `.ui-cursor-wait-outlined-shadow`