# fold-ng

> Accessible, dark-first Angular 22 UI component library and design system —
> signals-first, standalone, zoneless, SSR-ready. A two-tier design-token model
> plus WCAG-minded components, styled against CSS variables (no NgModule, no
> zone.js, no runtime CSS-in-JS).

Status: production-quality, pre-1.0 (0.x) — fully tested and dogfooded in a real
application; it stays 0.x only because the API is not frozen until 1.0.0 (not
because it is unstable). Pin the version; 0.x minor bumps may still refine the API.

fold-ng is consumed as standalone Angular components imported from the package
root (`import { FoldButtonComponent } from "fold-ng"`) plus a token stylesheet
(`@import "fold-ng/tokens.css"`). Dark ("umbra") is the default theme; light
("lumen") and others are opt-in via `data-theme`. Every component ships JSDoc
with a `@selector` and an `@example`.

## Getting started

- [Install & quickstart](https://github.com/hugoheynard/fold-ng#readme): `npm install fold-ng`, import tokens, use standalone components.
- [Design tokens](https://github.com/hugoheynard/fold-ng#the-two-tier-model): two-tier model — primitives (`--fold-ref-*`) → semantic (`--fold-color-*`); components consume the semantic layer only.
- [Theming](https://github.com/hugoheynard/fold-ng#consuming-the-tokens): `data-theme="umbra|lumen|bubbly|navi|titan"`; re-theme by re-pointing the semantic layer, never touching a component.

## Components

- Actions: `[foldButton]` (on a real `<button>`/`<a>`; `emphasis` × `intent` axes; `loading`), `fold-button-icon` (momentary), `fold-toggle-icon` (toggle), `fold-link`.
- Forms: `fold-input` (text), `fold-number-input`, `fold-textarea` (multiline, no resize), `fold-date` (date·datetime-local·month·week) / `fold-time`, `fold-select` (native) / `fold-listbox` (custom rows) / `fold-multiselect` (+ `fold-optgroup` for labelled groups), `fold-checkbox`, `fold-password-field`, `fold-search`, `fold-slider` / `fold-range-slider`, `fold-file-dropzone` (Angular Signal Forms — no `ngModel`/`ReactiveFormsModule`).
- Overlays: `fold-panel-host` / `fold-panel-header` / `fold-panel-footer` (modal side panels with accessible name, `inert` background barrier, focus trap, scroll-lock; imperative `open<TData,TResult>()` → typed `FoldPanelRef`; `side="right|left|bottom|auto|center"` — `bottom` = mobile sheet with grabber, `auto` = right on a wide host / bottom on a narrow one via `@container`, `center` = a modal dialog centred in the viewport over a scrim (the only side that leaves the content region); the footer is the bottom action bar, `align="end|between|start"`).
- Navigation: `fold-menu`, `fold-nav-launcher`, `fold-view-nav` (tab-styled nav bar; items with a `link` render real `<a routerLink>` with `aria-current` + auto active state, else buttons; `direction="auto"`, `collapsed` icon rail), `fold-tabs` + `fold-tab-panel` (the in-page ARIA Tabs widget — `role="tablist"`, roving arrow keys).
- Layout: `fold-app-shell`, `fold-page-layout`, `fold-aside-layout`, `fold-nav-layout` (places a nav/tabs bar + content, folds side↔top), `fold-hero-section`.
- Content: `fold-card`, `fold-hero-card`, `fold-badge`, `fold-status-badge`, `fold-avatar`, `fold-avatar-list`, `fold-timeline`, `fold-data-table`, `fold-paginator`, `fold-field`.
- Feedback: `fold-callout`, `fold-disclosure`, `fold-toast`, `fold-loading`, `fold-empty-state`.
- Foundations: `fold-icon` (~135 built-in SVGs across 7 categories incl. `commerce` + registry), `fold-spinner`.

## Pick by intent (don't hand-roll — fold likely ships it)

You usually know the intent, not the name. Before hand-rolling a label/field/badge/card/overlay, map it here:

- uppercase label / eyebrow over a group → `fold-element-title` (`variant="eyebrow"`); a titled section → `fold-page-section`; read-only label/value pairs → `fold-field-list`.
- multiline note → `fold-textarea`; a date → `fold-date`; a time → `fold-time`; a dropdown → `fold-select` (custom rows → `fold-listbox`, multi → `fold-multiselect`); on/off → `fold-checkbox`.
- inline "are you sure?" → `fold-inline-confirm`; a "delete X" danger block with type-to-confirm → `fold-danger-zone`; a tinted alert row → `fold-callout`; a toast → `FoldToastService`; a status/count pill → `fold-badge` / `fold-status-badge`.
- a side panel → `fold-panel-host`; anchored popover → `fold-popover`; actions menu → `fold-dropdown`; collapsible → `fold-disclosure`; a "what is this?" help bubble → `fold-info` (also the `info` input on every labelled field). a centred modal dialog → the same `fold-panel-host` with `side="center"`.
- in-page tabs → `fold-tabs`; routed nav bar → `fold-view-nav`; a breadcrumb trail → `fold-breadcrumb` (`[items]`, routerLink or href, last = current); a "← Back" link → `fold-back-link` (routerLink / href / history-back button); segmented control → `fold-view-toggle` / `fold-choice-row`.
- empty/loading state → `fold-empty-state` / `fold-loading`; a table → `fold-data-table` (+ `fold-paginator`); a calendar → `fold-calendar-*`; a timeline/stepper → `fold-timeline`.

## Conventions

- Angular 22, standalone, signals (`input()`/`output()`/`computed()`/`effect()`), zoneless, SSR-safe.
- Accessibility: overlays trap focus + `inert` the background + carry an accessible name; icons inherit `currentColor`; forced-colors + reduced-motion honoured.
- Localise strings via inputs / providers (e.g. `provideFoldPanelLabels({ close })`).

## Full API

- [Component & selector table (README)](https://github.com/hugoheynard/fold-ng#components)
- [Release readiness, per component](https://github.com/hugoheynard/fold-ng/blob/main/docs/RELEASE-READINESS.md)
- [Roadmap](https://github.com/hugoheynard/fold-ng/blob/main/docs/TODO.md)