@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<T> 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 | | UIThemeToggle | ui-theme-toggle | Light/dark mode toggle button with inline SVG icons |

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.

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 |

Services

| Service | Description | | ------------------ | -------------------------------------------------- | | PopoverService | Opens positioned popover overlays programmatically | | ModalService | Opens modal dialogs programmatically |

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 <ng-template> |

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

import { UIButton, UITableView, UITextColumn } from "@theredhead/lucid-kit";

@Component({
  selector: "app-demo",
  standalone: true,
  imports: [UIButton, UITableView, UITextColumn],
  template: `
    <ui-button variant="filled" (click)="load()">Refresh</ui-button>

    <ui-table-view [datasource]="datasource">
      <ui-text-column key="name" headerText="Name" [sortable]="true" />
      <ui-text-column key="email" headerText="Email" [truncate]="true" />
    </ui-table-view>
  `,
})
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:

@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