@frame-kit/ui-ng 0.0.1

package/COMPONENTS.md

@@ -0,0 +1,683 @@
+## FrameKit UI-ng Component Library
+
+FrameKit UI-ng is a token-driven Angular component library that provides a consistent set of building blocks for data entry, layout, navigation, and complex form workflows, all designed to be themeable via `--fk-*` design tokens.
+
+Organized by **purpose** (not Atomic Design) into seven layers with strict dependency rules — see [the development guide](./DEVELOPMENT_GUIDE.md) for the architecture overview.
+
+---
+
+## Table of Contents
+
+### Core — raw primitives
+
+- [fk-headline](#fk-headline)
+- [fk-icon](#fk-icon)
+- [fk-image](#fk-image)
+- [fk-link](#fk-link)
+- [fk-separator](#fk-separator)
+- [fk-text](#fk-text)
+
+### UI — composed reusable components
+
+- [fk-accordion](#fk-accordion)
+- [fk-alert](#fk-alert)
+- [fk-avatar](#fk-avatar)
+- [fk-avatar-stack](#fk-avatar-stack)
+- [fk-badge](#fk-badge)
+- [fk-breadcrumb](#fk-breadcrumb)
+- [fk-button](#fk-button)
+- [fk-callout](#fk-callout)
+- [fk-card](#fk-card)
+- [fk-copyable-field](#fk-copyable-field)
+- [fk-data-table](#fk-data-table)
+- [fk-dialog](#fk-dialog)
+- [fk-drawer](#fk-drawer)
+- [fk-dropdown-menu](#fk-dropdown-menu)
+- [fk-editable-field](#fk-editable-field)
+- [fk-icon-badge](#fk-icon-badge)
+- [fk-icon-list](#fk-icon-list)
+- [fk-inline-edit](#fk-inline-edit)
+- [fk-list-editor](#fk-list-editor)
+- [fk-loader](#fk-loader)
+- [fk-menu-item](#fk-menu-item)
+- [fk-nav-brand](#fk-nav-brand)
+- [fk-nav-group](#fk-nav-group)
+- [fk-nav-separator](#fk-nav-separator)
+- [fk-node-tree](#fk-node-tree)
+- [fk-node-tree-breadcrumb](#fk-node-tree-breadcrumb)
+- [fk-note](#fk-note)
+- [fk-numbered-list](#fk-numbered-list)
+- [fk-pagination](#fk-pagination)
+- [fk-progress-bar](#fk-progress-bar)
+- [fk-sidenav-link](#fk-sidenav-link)
+- [fk-tabs](#fk-tabs)
+- [fk-timeline](#fk-timeline)
+- [fk-toast](#fk-toast)
+- [fk-user-menu](#fk-user-menu)
+- [fk-wizard-dialog](#fk-wizard-dialog)
+
+### Directives — standalone behaviors
+
+- [fkInfiniteScroll](#fkinfinitescroll)
+- [fkSpotlightTrigger / fkSpotlightTarget](#fkspotlighttrigger--fkspotlighttarget)
+- [fkTooltip](#fktooltip)
+
+### Forms / Fields — registered form inputs
+
+- [fk-autocomplete](#fk-autocomplete)
+- [fk-checkbox](#fk-checkbox)
+- [fk-date-input](#fk-date-input)
+- [fk-datetime-input](#fk-datetime-input)
+- [fk-file-dropzone](#fk-file-dropzone)
+- [fk-file-upload](#fk-file-upload)
+- [fk-input](#fk-input)
+- [fk-number-input](#fk-number-input)
+- [fk-password-input](#fk-password-input)
+- [fk-radio](#fk-radio)
+- [fk-segmented-bar](#fk-segmented-bar)
+- [fk-select](#fk-select)
+- [fk-slider](#fk-slider)
+- [fk-switch](#fk-switch)
+- [fk-tag-input](#fk-tag-input)
+- [fk-textarea](#fk-textarea)
+- [fk-time-input](#fk-time-input)
+
+### Services — runtime services with no UI
+
+- [OverlayOrchestrator](#overlayorchestrator)
+- [SpotlightService](#spotlightservice)
+- [ToastService](#toastservice)
+
+### Forms / Composition — form wrappers and renderer
+
+- [fk-error](#fk-error)
+- [fk-field-group](#fk-field-group)
+- [fk-form](#fk-form)
+- [fk-form-field](#fk-form-field)
+- [fk-form-renderer](#fk-form-renderer)
+- [fk-form-section](#fk-form-section)
+- [fk-hint](#fk-hint)
+- [fk-label](#fk-label)
+
+### Layouts — structural page scaffolding
+
+- [fk-app-shell](#fk-app-shell)
+- [fk-content-split](#fk-content-split)
+
+### Docs — API-reference UI
+
+- [fk-endpoint-link](#fk-endpoint-link)
+- [fk-method-badge](#fk-method-badge)
+
+---
+
+## Core
+
+---
+
+### fk-headline
+
+A heading/typography atom for consistent section titles and page headings.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/core/headline/README.md)
+
+---
+
+### fk-icon
+
+A token-driven icon wrapper for rendering and styling icon glyphs.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/core/icon/README.md)
+
+---
+
+### fk-image
+
+An image atom with sensible defaults for layout, sizing, and accessibility.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/core/image/README.md)
+
+---
+
+### fk-link
+
+A flexible, accessible link component that supports router navigation and external URLs.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/core/link/README.md)
+
+---
+
+### fk-separator
+
+A horizontal rule component for visually dividing content sections.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/core/separator/README.md)
+
+---
+
+### fk-text
+
+A typography atom for body copy and supporting text.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/core/text/README.md)
+
+---
+
+## UI
+
+---
+
+### fk-accordion
+
+A token-driven accordion / collapsible-panel component for stacking expand-on-click sections.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/accordion/README.md)
+
+---
+
+### fk-alert
+
+A token-driven alert component for displaying contextual messages such as info notices, success confirmations, warnings, and errors.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/alert/README.md)
+
+---
+
+### fk-avatar
+
+A token-driven avatar that displays a user image with an initials fallback and an optional presence status indicator.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/avatar/README.md)
+
+---
+
+### fk-avatar-stack
+
+A token-driven avatar stack that displays a row of overlapping user avatars with an overflow badge for additional users.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/avatar-stack/README.md)
+
+---
+
+### fk-badge
+
+A small, token-driven label for status, counts, and metadata.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/badge/README.md)
+
+---
+
+### fk-breadcrumb
+
+A generic route-driven breadcrumb that renders an ordered list of crumbs with `routerLink` navigation on ancestors and `aria-current="page"` on the current location.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/breadcrumb/README.md)
+
+---
+
+### fk-button
+
+A token-driven button that supports variants, sizes, and loading states.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/button/README.md)
+
+---
+
+### fk-callout
+
+A token-driven callout for highlighting supplementary information such as tips, notices, or contextual messages.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/callout/README.md)
+
+---
+
+### fk-card
+
+A token-driven container component for grouping related content with consistent padding, background, border, and alignment.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/card/README.md)
+
+---
+
+### fk-copyable-field
+
+A read-only value paired with a copy-to-clipboard button. Use for API keys, tokens, IDs, and any value the user needs to copy.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/copyable-field/README.md)
+
+---
+
+### fk-data-table
+
+A token-driven, responsive data table with sorting, virtual scrolling, column resizing, column pinning, and a mobile stacked card view.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/data-table/README.md)
+
+---
+
+### fk-dialog
+
+A modal dialog for confirmations, forms, and complex interactions.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/dialog/README.md)
+
+---
+
+### fk-drawer
+
+An accessible, token-driven slide-out drawer component with focus management, scroll locking, and flexible close behavior.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/drawer/README.md)
+
+---
+
+### fk-dropdown-menu
+
+A compound dropdown menu that orchestrates a trigger, floating panel, and projected menu items with full keyboard navigation and viewport-aware positioning.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/dropdown-menu/README.md)
+
+---
+
+### fk-editable-field
+
+A bordered single-line field that toggles between a display read-out and a live editable input, with a pencil/cancel affordance anchored inside the trailing edge — built for form-shaped surfaces (billing details, profile rows).
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/editable-field/README.md)
+
+---
+
+### fk-icon-badge
+
+An icon paired with a badge-style label for compact status and metadata display.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/icon-badge/README.md)
+
+---
+
+### fk-icon-list
+
+List primitives (`fk-icon-list` and `fk-icon-list-item`) for rendering rows that pair a label with an icon marker — usable data-driven via the list's `items` input, with projected `<fk-icon-list-item>` children, or as standalone items outside any list wrapper.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/icon-list/README.md)
+
+---
+
+### fk-inline-edit
+
+An in-place editing pattern that toggles between display and edit modes on a single value, with save, cancel, and validation support.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/inline-edit/README.md)
+
+---
+
+### fk-list-editor
+
+A token-driven list editor for building ordered string lists with add, remove, inline edit, and drag-to-reorder.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/list-editor/README.md)
+
+---
+
+### fk-loader
+
+A loading indicator for showing progress or pending state.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/loader/README.md)
+
+---
+
+### fk-menu-item
+
+Menu primitives (`fk-menu-item` and `fk-menu-separator`) for rendering actionable items and visual dividers inside menu-like containers.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/menu-item/README.md)
+
+---
+
+### fk-nav-brand
+
+A brand/logo element used within navigation bars.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/nav-brand/README.md)
+
+---
+
+### fk-nav-group
+
+An expandable nav group that pairs a clickable trigger row (icon + label, optionally routed) with projected child links revealed when expanded. Designed to sit inside a collapsible shell so collapsed clicks request the outer shell to open.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/nav-group/README.md)
+
+---
+
+### fk-nav-separator
+
+A token-driven separator for visually dividing groups of navigation items, with vertical/horizontal orientation and decorative/semantic accessibility modes.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/nav-separator/README.md)
+
+---
+
+### fk-node-tree
+
+A hierarchical tree view for rendering and interacting with nested nodes, with expand/collapse, selection, drag-reorder, and keyboard navigation.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/node-tree/README.md)
+
+---
+
+### fk-node-tree-breadcrumb
+
+A breadcrumb that displays the ancestry path from root to a selected node in a tree hierarchy. Pairs with `fk-node-tree`. Not route-driven — for route-based crumbs use a separate component.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/node-tree-breadcrumb/README.md)
+
+---
+
+### fk-note
+
+A lightweight, token-driven inline callout that draws attention to a line of prose with a colored left rail — no box chrome, no background, no border radius.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/note/README.md)
+
+---
+
+### fk-numbered-list
+
+Numbered list primitives (`fk-numbered-list` and `fk-numbered-list-item`) for ordered procedures and step-by-step instructions, with automatic CSS-counter numbering — usable data-driven via the list's `items` input or with projected `<fk-numbered-list-item>` children.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/numbered-list/README.md)
+
+---
+
+### fk-pagination
+
+A table/list pagination control with page navigation, page-size selector, and range summary.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/pagination/README.md)
+
+---
+
+### fk-progress-bar
+
+A token-driven progress bar for indicating how far along a single task or process is, with determinate and indeterminate modes.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/progress-bar/README.md)
+
+---
+
+### fk-sidenav-link
+
+A token-driven sidebar navigation link that renders an icon and label, automatically hiding the label when the parent app-shell is collapsed.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/sidenav-link/README.md)
+
+---
+
+### fk-tabs
+
+A compound component system for building accessible, keyboard-navigable tabbed interfaces. Supports underline, pill, and contained variants, controlled and uncontrolled modes, lazy rendering, closable tabs, and full WAI-ARIA Tabs pattern compliance.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/tabs/README.md)
+
+---
+
+### fk-timeline
+
+A token-driven timeline for displaying ordered steps, resolution chains, audit trails, and workflow progress with status indicators, connectors, and support for vertical and horizontal orientations.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/timeline/README.md)
+
+---
+
+### fk-toast
+
+A transient notification message paired with the `ToastService`, supporting success/error/warning/info severities and custom component content.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/toast/README.md)
+
+---
+
+### fk-user-menu
+
+A token-driven user menu that composes an avatar trigger with a dropdown panel of configurable menu items, supporting keyboard navigation, status indicators, and multiple display variants.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/user-menu/README.md)
+
+---
+
+### fk-wizard-dialog
+
+A service-driven wizard dialog for multi-step workflows. Opens its own dialog via `DialogService`, placing the stepper and scrollable content in the body and action buttons in the pinned footer.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/ui/wizard-dialog/README.md)
+
+---
+
+## Directives
+
+---
+
+### fkInfiniteScroll
+
+A directive that emits events when the scroll position of a scrollable container approaches its end, used to trigger "load more" patterns in lists and tables.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/directives/infinite-scroll/README.md)
+
+---
+
+### fkSpotlightTrigger / fkSpotlightTarget
+
+A directive pair that pulses one or more target elements while a trigger zone is hovered or focused — wires unrelated parts of the DOM together for "find this thing" onboarding cues, with optional `pulse` ring or `overlay` tint treatments.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/directives/spotlight/README.md)
+
+---
+
+### fkTooltip
+
+A directive that shows a positioned tooltip on hover, focus, or long-press, with viewport-aware placement and full accessibility.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/directives/tooltip/README.md)
+
+---
+
+## Forms / Fields
+
+---
+
+### fk-autocomplete
+
+A text input with a suggestions dropdown for quickly selecting from large option sets.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/autocomplete/README.md)
+
+---
+
+### fk-checkbox
+
+An accessible checkbox control for boolean choices and multi-select lists.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/checkbox/README.md)
+
+---
+
+### fk-date-input
+
+A date entry field optimized for forms that need precise, locale-aware dates.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/date-input/README.md)
+
+---
+
+### fk-datetime-input
+
+A combined date and time input for capturing full timestamps in a single control.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/datetime-input/README.md)
+
+---
+
+### fk-file-dropzone
+
+A drag-and-drop file input with a click-to-browse fallback, sized like a card and tokenized for theming.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/file-dropzone/README.md)
+
+---
+
+### fk-file-upload
+
+An accessible file picker for uploading documents and attachments.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/file-upload/README.md)
+
+---
+
+### fk-input
+
+A text input component for Angular with reactive forms support and token-driven styling.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/input/README.md)
+
+---
+
+### fk-number-input
+
+A numeric input optimized for quantities, currency, and other number-only fields.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/number-input/README.md)
+
+---
+
+### fk-password-input
+
+A password field with secure entry behavior and form integration.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/password-input/README.md)
+
+---
+
+### fk-radio
+
+An accessible radio button for mutually exclusive choices.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/radio/README.md)
+
+---
+
+### fk-segmented-bar
+
+A token-driven segmented bar for visualizing how a whole is divided into parts, such as task status distributions or resource allocation.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/segmented-bar/README.md)
+
+---
+
+### fk-select
+
+A styled select/dropdown control for choosing a single option from a list.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/select/README.md)
+
+---
+
+### fk-slider
+
+A slider control for selecting values along a continuous or stepped range.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/slider/README.md)
+
+---
+
+### fk-switch
+
+A toggle switch for binary on/off settings.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/switch/README.md)
+
+---
+
+### fk-tag-input
+
+An input for entering and managing multiple tags or chips.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/tag-input/README.md)
+
+---
+
+### fk-textarea
+
+A multi-line text field for longer freeform input.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/textarea/README.md)
+
+---
+
+### fk-time-input
+
+A time-only input for capturing hours and minutes.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/fields/time-input/README.md)
+
+---
+
+## Forms / Composition
+
+---
+
+### fk-error
+
+An inline error message component designed to pair with form fields.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/error/README.md)
+
+---
+
+### fk-field-group
+
+Groups closely related fields together inside a form for better scanning and layout.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/field-group/README.md)
+
+---
+
+### fk-form
+
+Provides a structured container and patterns for building robust, validated forms.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/form/README.md)
+
+---
+
+### fk-form-field
+
+A wrapper that coordinates labels, hints, errors, and state for a single form control.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/form-field/README.md)
+
+---
+
+### fk-form-renderer
+
+Drives dynamic, schema-based forms where fields and sections are defined by configuration.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/form-renderer/README.md)
+
+---
+
+### fk-form-section
+
+Segments a form into clear, labeled sections for larger data entry experiences.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/form-section/README.md)
+
+---
+
+### fk-hint
+
+A helper text component for surfacing non-blocking guidance under form controls.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/hint/README.md)
+
+---
+
+### fk-label
+
+An accessible label for associating text with a specific form control.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/forms/composition/label/README.md)
+
+---
+
+## Layouts
+
+---
+
+### fk-app-shell
+
+A responsive application shell layout with a header, collapsible sidebar (with header, nav, and footer zones), overlay support, and a main content area.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/layouts/app-shell/README.md)
+
+---
+
+### fk-content-split
+
+A container-aware split-pane layout with a side-by-side mode for wide containers and an overlay drawer with rail toggle for narrow containers.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/layouts/content-split/README.md)
+
+---
+
+## Services
+
+> Color and date helpers are no longer services in this library — they moved to **`@frame-kit/utils`** (`Color` / `DateUtil`), framework-agnostic and Angular-free.
+
+---
+
+### OverlayOrchestrator
+
+Centralized priority stack for dialogs, drawers, popovers, and navigation panels — opening a higher-priority overlay auto-closes the lower-priority ones underneath. `DialogService` and `DrawerService` register automatically.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/services/overlay-orchestrator/README.md)
+
+---
+
+### SpotlightService
+
+Coordinates a single global "active key" with reference-counted holders, so unrelated parts of the DOM can pulse together when the same key is activated. The `fkSpotlightTrigger` / `fkSpotlightTarget` directives are the typical consumers.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/services/spotlight/README.md)
+
+---
+
+### ToastService
+
+Global notification queue. Severity helpers (`success` / `error` / `warning` / `info`) for default toasts, plus `open()` for custom-component toasts with embedded actions like retry buttons.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/services/toast/README.md)
+
+---
+
+## Docs
+
+---
+
+### fk-endpoint-link
+
+A sidebar row for an API endpoint in developer documentation — pairs an HTTP method badge with the endpoint path.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/docs/endpoint-link/README.md)
+
+---
+
+### fk-method-badge
+
+A token-driven HTTP method badge for developer documentation — a colored GET/POST/PUT/DELETE pill.
+[README](https://github.com/frame-kit/packages/blob/main/packages/ui-ng/docs/method-badge/README.md)