fold-ng 0.0.0 → 0.2.0

package/llms.txt

@@ -0,0 +1,45 @@
+# 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"`; 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`, `fold-number-input`, `fold-select`, `fold-search`, `fold-slider`, `fold-range-slider`, `fold-file-dropzone` (Angular Signal Forms — no `ngModel`/`ReactiveFormsModule`).
+- Overlays: `fold-panel-host` / `fold-panel-header` (modal side panels with accessible name, `inert` background barrier, focus trap, scroll-lock; imperative `open<TData,TResult>()` → typed `FoldPanelRef`).
+- Navigation: `fold-menu`, `fold-nav-launcher`, `fold-tab-nav`.
+- Layout: `fold-app-shell`, `fold-page-layout`, `fold-aside-layout`, `fold-tab-layout`, `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` (114 built-in SVGs + registry), `fold-spinner`.
+
+## 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)

package/package.json

@@ -1,20 +1,70 @@
 {
   "name": "fold-ng",
-  "version": "0.0.0",
-  "description": "A dark-first Angular design system — signals-first, standalone, zoneless, SSR-ready. Coming soon.",
-  "author": "Hugo Heynard",
-  "license": "MIT",
+  "version": "0.2.0",
+  "description": "Accessible, dark-first Angular 22 UI component library & design system — signals-first, standalone, zoneless, SSR-ready. Design tokens + WCAG-minded components, themeable to the bone.",
   "keywords": [
     "angular",
-    "design-system",
+    "angular-22",
+    "angular-components",
+    "ui-library",
+    "ui-components",
     "component-library",
+    "design-system",
+    "design-tokens",
+    "css-variables",
     "signals",
     "zoneless",
+    "standalone",
     "ssr",
-    "dark-theme"
+    "dark-theme",
+    "theme",
+    "theming",
+    "accessible",
+    "a11y",
+    "wcag",
+    "overlay",
+    "dialog",
+    "angular-ui",
+    "signals-first"
+  ],
+  "author": "Hugo Heynard",
+  "license": "MIT",
+  "homepage": "https://hugoheynard.github.io/fold-ng/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hugoheynard/fold-ng.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hugoheynard/fold-ng/issues"
+  },
+  "type": "module",
+  "private": false,
+  "packageManager": "pnpm@10.12.1",
+  "sideEffects": [
+    "**/*.css"
   ],
-  "files": [
-    "README.md",
-    "LICENSE"
-  ]
+  "exports": {
+    "./tokens.css": "./tokens/index.css",
+    "./tokens/primitives.css": "./tokens/primitives.css",
+    "./tokens/scales.css": "./tokens/scales.css",
+    "./tokens/semantic.css": "./tokens/semantic.css",
+    ".": {
+      "types": "./types/fold-ng.d.ts",
+      "default": "./fesm2022/fold-ng.mjs"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "peerDependencies": {
+    "@angular/common": "^22",
+    "@angular/core": "^22",
+    "@angular/forms": "^22",
+    "@angular/platform-browser": "^22"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "module": "fesm2022/fold-ng.mjs",
+  "typings": "types/fold-ng.d.ts"
 }

package/tokens/index.css

@@ -0,0 +1,14 @@
+/* ============================================================
+   SH3PHERD · Design tokens — entry point
+   ------------------------------------------------------------
+   The single file an app imports to get the whole token set:
+
+     @import 'fold-ng/tokens.css';
+
+   Order matters: primitives first (they define the raw palette),
+   then the semantic layer that points at them.
+   ============================================================ */
+
+@import "./primitives.css";
+@import "./scales.css";
+@import "./semantic.css";

package/tokens/primitives.css

@@ -0,0 +1,113 @@
+/* ============================================================
+   SH3PHERD · Design tokens — TIER 1: PRIMITIVES
+   ------------------------------------------------------------
+   The raw palette. These are the ONLY place a literal colour
+   value is allowed to live. They are theme-INVARIANT: the same
+   ink/teal/cloud values in dark and light — it is the semantic
+   layer (semantic.css) that decides which primitive a role
+   points to per theme.
+
+   Never reference a --fold-ref-* token from a component.
+   Components consume the semantic layer only.
+   ============================================================ */
+
+:root {
+  /* ── Ink — the dark chrome family (deep blue-black) ───────────
+     Ordered by depth: 950 is the darkest, 850 the lightest.      */
+  --fold-ref-ink-950: #0a0e14; /* header bar               */
+  --fold-ref-ink-925: #090d13; /* rail 1 · app menu        */
+  --fold-ref-ink-900: #0c1018; /* rail 2 · workspace menu  */
+  --fold-ref-ink-850: #11161e; /* page background          */
+  --fold-ref-ink-800: #1f2733; /* raised card surface      */
+  --fold-ref-ink-700: #28323f; /* raised hover surface     */
+
+  /* ── Cloud — the light chrome family ──────────────────────────
+     Ordered by depth too: 50 is the lightest, 200 the darkest.   */
+  --fold-ref-white: #ffffff; /* header bar                  */
+  --fold-ref-cloud-50: #f9fafb; /* rail 2 · workspace menu   */
+  --fold-ref-cloud-100: #f4f5f7; /* page background          */
+  --fold-ref-cloud-150: #f0f1f3; /* rail 1 · app menu        */
+
+  /* ── Teal — the brand / primary family ────────────────────── */
+  --fold-ref-teal-400: #2dd4d4; /* lightest — hover on dark    */
+  --fold-ref-teal-500: #06a4a4; /* brand base (dark theme)     */
+  --fold-ref-teal-550: #069090; /* muted — brand on light      */
+  --fold-ref-teal-600: #057a7a; /* darkest — hover on light    */
+
+  /* ── Amber — the warning family ───────────────────────────── */
+  --fold-ref-amber-300: #e8b84a; /* light tint (dark theme)     */
+  --fold-ref-amber-500: #d4a017; /* base (dark theme)           */
+  --fold-ref-amber-550: #d4940e; /* light tint (light theme)    */
+  --fold-ref-amber-600: #b8860b; /* base (light theme)          */
+
+  /* ── Red — the alert family ───────────────────────────────── */
+  --fold-ref-red-400: #e06450; /* light tint (dark theme)       */
+  --fold-ref-red-450: #d4493a; /* light tint (light theme)      */
+  --fold-ref-red-500: #c44230; /* base (dark theme)             */
+  --fold-ref-red-600: #b33a2a; /* base (light theme)            */
+
+  /* ── Purple — the info family ─────────────────────────────── */
+  --fold-ref-purple-300: #b794f4; /* light tint (dark theme)    */
+  --fold-ref-purple-400: #9f7aea; /* surface/border base (dark) */
+  --fold-ref-purple-500: #7c5bbf; /* base (dark) · text (light) */
+  --fold-ref-purple-600: #6c4ab6; /* base (light theme)         */
+
+  /* ── Green — the success family ───────────────────────────── */
+  --fold-ref-green-300: #4bd6a0; /* light tint (dark theme)      */
+  --fold-ref-green-500: #1a9e6a; /* base (both themes)           */
+  --fold-ref-green-550: #38a169; /* light tint (light theme)     */
+
+  /* ── Slate — the neutral text family ──────────────────────── */
+  --fold-ref-slate-50: #eef1ff; /* primary text (dark theme)   */
+  --fold-ref-slate-350: #9ca3af; /* faded text (light theme)    */
+  --fold-ref-slate-400: #8892b0; /* secondary text (dark)       */
+  --fold-ref-slate-500: #5e6a86; /* muted text (dark)           */
+  --fold-ref-slate-550: #6b7280; /* muted text (light)          */
+  --fold-ref-slate-600: #5f6b7a; /* secondary text (light)      */
+  --fold-ref-slate-700: #4a5470; /* faded text (dark theme)     */
+  --fold-ref-slate-900: #1a1d23; /* primary text (light theme)  */
+
+  /* ── Azure — a cyan, BUBBLY's info family ──────────────────────
+     Moved bubbly's info off its violet brand's hue, the way a status
+     that collides with the brand always must.                        */
+  --fold-ref-azure-500: #0ea5e9; /* base — bubbly info          */
+
+  /* ── Navy — the NAVI theme family ─────────────────────────────
+     One corporate midnight-blue family serving both jobs: the brand
+     on the light page (500/600) and the dark chrome behind it
+     (800→950), so rails, header and primary are visibly related.
+     300/400 are the tints readable ON the dark chrome.             */
+  --fold-ref-navy-300: #9db8ea; /* text tint on dark chrome     */
+  --fold-ref-navy-400: #5a7fd0; /* hover tint on dark chrome    */
+  --fold-ref-navy-500: #24448f; /* brand base (light page)      */
+  --fold-ref-navy-600: #1b3573; /* hover / readable brand text  */
+  --fold-ref-navy-750: #1a3157; /* header — set apart from the rails */
+  --fold-ref-navy-800: #16294f; /* raised surface on the chrome */
+  --fold-ref-navy-850: #13233f; /* rail 2 · workspace menu      */
+  --fold-ref-navy-900: #101d3a; /* rail 1 · app menu (deepest)  */
+  --fold-ref-navy-950: #0b152b; /* sunken surface on the chrome */
+
+  /* ── Ivory — the NAVI page ────────────────────────────────────
+     White, off by two points of blue. The opposition is the point: a
+     cool page beside a cool rail is merely consistent, where warm-on-
+     cool is what makes navy read as navy — and it works at a very low
+     dose. Any warmer and the page starts looking like cream, a whole
+     warm theme rather than a warm page.                              */
+  --fold-ref-ivory-50: #fdfcfb; /* page background (navi)        */
+
+  /* ── Bubble / Grape — the BUBBLY theme families ────────────────
+     Festive light: soft lavender-white chrome and a joyful violet
+     brand, rounded off. Text reuses slate, info reuses azure (cyan)
+     so it never blurs into the violet brand.                       */
+  --fold-ref-bubble-0: #ffffff; /* header · card · text on solid */
+  --fold-ref-bubble-50: #faf7ff; /* rail 2 · workspace menu      */
+  --fold-ref-bubble-100: #f4eefe; /* page background             */
+  --fold-ref-bubble-150: #ebe1fd; /* rail 1 · app menu           */
+
+  --fold-ref-grape-500: #a855f7; /* brand base                  */
+  --fold-ref-grape-600: #9333ea; /* hover / strong              */
+  --fold-ref-grape-700: #7e22ce; /* readable brand text         */
+
+  /* ── Pure black — pairs with white for neutral alpha overlays */
+  --fold-ref-black: #000000;
+}

package/tokens/scales.css

@@ -0,0 +1,106 @@
+/* ============================================================
+   SH3PHERD · Design tokens — SCALES (radius, type)
+   ------------------------------------------------------------
+   Sizing + elevation scales. Single-tier: a radius or a font size
+   IS its value, so there is no primitive/semantic split — just the
+   scale, on :root. Elevation is the one exception that touches
+   colour, but stays theme-invariant (black-ink shadows via the black
+   primitive, legible on every theme).
+
+   RADIUS is the one scale a theme may re-declare. Corner softness is
+   a brand axis, not a measurement: the same product reads friendly
+   or institutional on the same layout. Type, space, motion and
+   elevation stay theme-invariant — retheming must never re-flow a
+   page, and only radius can change without moving a single box. The
+   contract test enforces exactly that split.
+   ============================================================ */
+
+:root {
+  /* Radius scale.
+     NB: `lg` is a real large radius and `pill` is the capsule —
+     two separate tokens. (The app historically overloaded a single
+     `--radius-lg` as the pill, which left no token for a card's
+     ~14px corner. Fixed here.) */
+  --fold-radius-xs: 3px;
+  --fold-radius-sm: 6px;
+  --fold-radius-md: 10px;
+  --fold-radius-lg: 14px;
+  --fold-radius-pill: 9999px;
+  --fold-radius-round: 50%;
+
+  /* Type scale — absolute px, matching claudeDesign-ref exactly (the app root
+     is 14px, so rem would render ~12% small; px is root-independent). */
+  --fold-text-xs: 11px;
+  --fold-text-sm: 12px;
+  --fold-text-md: 14px;
+  --fold-text-lg: 16px;
+  --fold-text-xl: 20px;
+
+  /* Icon size scale — the length a `fold-icon` renders at (width = height),
+     selected by its size preset. A measurement, so theme-invariant like type
+     and space. The component keeps a px fallback, so icons still render if a
+     consumer loads components without the token layer. */
+  --fold-icon-size-xs: 12px;
+  --fold-icon-size-sm: 16px;
+  --fold-icon-size-md: 20px;
+  --fold-icon-size-lg: 24px;
+  --fold-icon-size-xl: 32px;
+
+  /* Space scale — the shared spacing rhythm (gap / padding / margin). Promoted
+     once a 2nd+ component needed it (icon, paginator, panel-header, data-table);
+     the app's `--gap-*` bridge onto these 1:1. */
+  --fold-space-xs: 4px;
+  --fold-space-sm: 8px;
+  --fold-space-md: 12px;
+  --fold-space-lg: 16px;
+  --fold-space-xl: 20px;
+
+  /* Motion scale — transition shorthands (duration + easing bundled, matching
+     the app so `--t-*` bridge onto these 1:1). One knob per interaction speed. */
+  --fold-motion-fast: 0.1s ease;
+  --fold-motion-base: 0.18s ease;
+  --fold-motion-slow: 0.28s ease;
+
+  /* Backdrop-blur radii (for frosted `--fold-color-glass` surfaces). */
+  --fold-blur-glass: 20px;
+
+  /* Elevation scale — the shared depth language. Components name a level, never
+     spell their own shadow. Theme-invariant: the ink is the black primitive via
+     color-mix (no raw rgba), which reads acceptably on dark and light.
+     `panel-*` are the directional side-panel shadows (+ inset glass highlight). */
+  --fold-shadow-sm: 0 1px 2px
+    color-mix(in srgb, var(--fold-ref-black) 20%, transparent);
+  --fold-shadow-md: 0 10px 30px -12px
+    color-mix(in srgb, var(--fold-ref-black) 50%, transparent);
+  --fold-shadow-lg:
+    0 12px 32px color-mix(in srgb, var(--fold-ref-black) 50%, transparent),
+    0 4px 12px color-mix(in srgb, var(--fold-ref-black) 35%, transparent);
+  --fold-shadow-panel-right:
+    -12px 0 40px color-mix(in srgb, var(--fold-ref-black) 45%, transparent),
+    inset 1px 0 0 color-mix(in srgb, var(--fold-ref-white) 4%, transparent);
+  --fold-shadow-panel-left:
+    12px 0 40px color-mix(in srgb, var(--fold-ref-black) 45%, transparent),
+    inset -1px 0 0 color-mix(in srgb, var(--fold-ref-white) 4%, transparent);
+}
+
+/* ── Theme shape override: NAVI ───────────────────────────────
+   Back-office corporate: corners nearly squared off. `pill` and
+   `round` are shapes, not scale steps — flattening them would turn
+   avatars into squares and capsules into slabs — so they stay. */
+[data-theme="navi"] {
+  --fold-radius-xs: 1px;
+  --fold-radius-sm: 2px;
+  --fold-radius-md: 3px;
+  --fold-radius-lg: 4px;
+}
+
+/* ── Theme shape override: BUBBLY ─────────────────────────────
+   The opposite of navi: corners rounded right up, so every surface
+   reads soft and pill-like. `pill` and `round` stay — they are
+   shapes, not scale steps. */
+[data-theme="bubbly"] {
+  --fold-radius-xs: 6px;
+  --fold-radius-sm: 12px;
+  --fold-radius-md: 16px;
+  --fold-radius-lg: 24px;
+}