@bitforgehq/ui 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bitforge AG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# @bitforgehq/ui
+
+Bitforge's shared Angular component library: Meadow Sage design, Tailwind CSS v4, signals-first, Angular 22.
+
+- Widgets: `@bitforgehq/ui`
+- Number field: `@bitforgehq/ui/number-input` (`bf-number-input`; loads Angular Forms, peer
+  dependency `@angular/forms`)
+- Icons: `@bitforgehq/ui/icons` (Lucide data, peer dependency `lucide`)
+- Overlay core: `@bitforgehq/ui/overlay` (no Capacitor; peer dependencies `@angular/cdk` and
+  `rxjs`)
+- Mobile shell: `@bitforgehq/ui/mobile` (from v0.2)
+- Test support: `@bitforgehq/ui/testing` (jsdom shims, `provideBfTesting()`, CDK component
+  harnesses; needs `@angular/cdk` as a dev dependency)
+
+Install, theming and every component's API are documented for humans and agents in `ai/UI_GUIDE.md` and `ai/components/*.md` inside this package, and at the docs site (https://bitforge-ui.web.app).
+
+## Install
+
+<!-- install:start -->
+
+### 1. Check the prerequisites
+
+Node 22.22.3 or later in the 22 line, 24.15 or later in the 24 line, or 26 and later (the Angular CLI 22 range `^22.22.3 || ^24.15.0 || >=26.0.0`; it refuses older versions and warns on odd releases such as 23 and 25), Bun 1.3 or later and the Angular CLI 22.
+
+```bash
+node --version # v22.22.3+, v24.15+ or v26+
+bun --version # 1.3 or later
+bun add --global @angular/cli@22
+```
+
+### 2. Create the app
+
+A new Angular 22 app with plain CSS styles. Skip this step in an existing app.
+
+```bash
+ng new my-app --style css --package-manager bun
+cd my-app
+```
+
+### 3. Add Tailwind CSS
+
+The theme is a Tailwind CSS 4 theme. `ng add tailwindcss` installs Tailwind and its PostCSS plugin and writes `.postcssrc.json`.
+
+```bash
+ng add tailwindcss
+```
+
+### 4. Add the packages
+
+`lucide` provides the icon data for `bf-icon`; the two `@fontsource` packages provide the Manrope and JetBrains Mono fonts.
+
+```bash
+bun add @bitforgehq/ui lucide @fontsource/manrope @fontsource/jetbrains-mono
+```
+
+### 5. Wire the theme into styles.css
+
+Replace the contents of `src/styles.css`. Keep `tailwindcss` first: the theme redefines the palette its utilities read, and registers the package as a Tailwind source, so no `tailwind.config.js` is needed.
+
+```css
+@import 'tailwindcss';
+@import '@bitforgehq/ui/theme.css';
+@import '@fontsource/manrope/500.css';
+@import '@fontsource/manrope/600.css';
+@import '@fontsource/manrope/700.css';
+@import '@fontsource/manrope/800.css';
+@import '@fontsource/jetbrains-mono/400.css';
+```
+
+### 6. Theme the page
+
+In `src/index.html`, give `<body>` the theme background and text colour, so the page itself follows light and dark mode.
+
+```html
+<body class="bg-bg text-text">
+  <app-root></app-root>
+</body>
+```
+
+### 7. Switch to dark mode
+
+Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes.
+
+```html
+<html lang="en" class="dark">
+  <!-- head and body stay as they are -->
+</html>
+```
+
+### 8. Use a first component
+
+Import a widget from `@bitforgehq/ui` into the component that uses it. Replace `src/app/app.ts` with the code below and delete the welcome page it no longer uses, `app.html` and `app.css`. `app.spec.ts` tests that welcome page too: delete its `should render title` case (or make it check the button), so `ng test` keeps passing.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+@Component({
+  selector: 'app-root',
+  imports: [BfButtonComponent],
+  template: `<bf-button variant="primary">Save</bf-button>`,
+})
+export class App {}
+```
+
+### 9. Check it
+
+Run the app and open it: you should now see an indigo, pill-shaped **Save** button in Manrope on the theme background. With `class="dark"` on `<html>`, the whole page is dark.
+
+```bash
+ng serve
+```
+
+<!-- install:end -->
+
+## Peer dependencies
+
+`@bitforgehq/ui` (the widgets entry) needs `@angular/common`, `@angular/core`, `@angular/forms`
+and `lucide` (for `@bitforgehq/ui/icons` and `/mobile`); these are required peers. The widgets
+entry loads no `@angular/forms` code at runtime (its form widgets only implement the Signal Forms
+interfaces); `@bitforgehq/ui/number-input` does, since `bf-number-input` parses through Angular's
+`transformedValue()`, so `@angular/forms` is required for it. The overlay entry
+`@bitforgehq/ui/overlay` (the Capacitor-free overlay core) additionally needs `@angular/cdk` and
+`rxjs` (a CDK peer). The mobile entry `@bitforgehq/ui/mobile` needs those plus `@angular/router`
+and `@capacitor/core`. They are declared optional so a desktop-only install stays free of them:
+an app that imports `/overlay` or `/mobile` installs them itself. The Capacitor plugins `@capacitor/app`,
+`@capacitor/keyboard` and `@capacitor/haptics` are optional peers too; install only the ones your
+app uses, and `/mobile` builds and runs without the others.
+
+## Compatibility
+
+`@bitforgehq/ui` 0.x is client-rendered only. SSR, hydration and prerendering of pages that render
+its components are not supported or tested. Component ids come from a module-level counter and can
+differ between server and client, and the shell's theme is read from `localStorage` on the client.
+Render library components only in the browser, for example in a `@defer` block or a client-only
+route. Support will be decided before 1.0.
+
+The one server-side check is a render smoke, not a support test: the library repository's
+`tools/ssr-smoke.ts` renders 28 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`bf-number-input`, a `/mobile` page with `provideBfShell()`, `bf-page`, `bf-header` and
+`bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay` dialog), and all
+of them render without an error. 19 of them render identically twice. The other 9 number their ids
+differently on every render, from a module-level counter, so they could not hydrate: `bf-checkbox`,
+`bf-input`, `bf-radio-group`, `bf-segmented`, `bf-select`, `bf-textarea`, `bf-toggle`,
+`bf-number-input` and the `/overlay` dialog. Hydration itself is still not supported or tested, and
+more stands in its way: `/mobile` writes to `<html>` and adds a keyboard probe to `<body>`, and an
+`/overlay` dialog renders outside the app root and marks it inert.
+
+## Testing
+
+`@bitforgehq/ui/testing` is for your specs only (Vitest, the Angular CLI default, or Jest) and needs
+`@angular/cdk` as a dev dependency (`bun add -d @angular/cdk`) even in an app that never opens an
+overlay. Call `installBfJsdomShims()` in the runner's setup file (the `setupFiles` of the `test`
+target in `angular.json`): it adds the Web Animations API, `PointerEvent` and `matchMedia` where
+jsdom lacks them. `provideBfTesting()` passes defaults and labels to the widgets and cleans up what
+overlays and themes leave on the document after each test (when TestBed destroys the test
+environment, so keep its default `teardown: { destroyAfterEach: true }`), and the CDK harnesses
+(`BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`,
+`BfMenuButtonHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfDesktopToastHarness`) drive the
+widgets whose DOM a spec should not query by hand; overlays come from
+`TestbedHarnessEnvironment.documentRootLoader(fixture)`. An app on the mobile shell uses
+`provideBfShellTesting()` from `@bitforgehq/ui/mobile` instead (router, shell, an in-memory theme
+store and the same cleanup), so `/testing` itself never loads Capacitor.
+
+## Density and labels
+
+Every field and control shares one height scale (`BfSize`: `sm` 32, `md` 40, `lg` 48 px) with a
+compact `md` default for desktop web apps. Set another step once with `provideBfDefaults()` in
+`ApplicationConfig.providers` (`{ size: 'sm' }` for a data-dense app, `{ fieldSize: 'lg' }` for a
+Capacitor app, because under touch the actions and choice controls reach 44 px through an invisible
+extension but text fields get none, so only the fields need the 48 px step) or in a component's
+`providers` for one part of the app, such as a dense toolbar.
+`provideBfLabels()` replaces every built-in English string, including the default error text
+shown for a validator without a message, the same two ways. The docs site's Density and Labels
+guides list the scale and every string.

package/ai/MANIFEST.index.json

@@ -0,0 +1,383 @@
+{
+  "generatedFrom": "tools/gen-ai-docs.ts",
+  "components": [
+    {
+      "name": "action-bar",
+      "selector": "bf-action-bar",
+      "className": "BfActionBarComponent",
+      "category": "Actions",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Floating pill of contextual actions that appears while items are selected",
+      "since": "0.1.0"
+    },
+    {
+      "name": "action-sheet",
+      "selector": "bf-action-sheet",
+      "className": "BfActionSheetComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Bottom panel of labelled actions with a separate cancel button, destructive ones shown in red",
+      "since": "0.2.0"
+    },
+    {
+      "name": "alert",
+      "selector": "bf-alert",
+      "className": "BfAlertComponent",
+      "category": "Feedback",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Inline status message in four tones with a title and an optional dismiss button",
+      "since": "0.1.0"
+    },
+    {
+      "name": "alert-dialog",
+      "selector": "bf-alert-dialog",
+      "className": "BfAlertDialogComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Centred confirmation dialog with a title, message and a row of role-styled buttons",
+      "since": "0.2.0"
+    },
+    {
+      "name": "avatar",
+      "selector": "bf-avatar",
+      "className": "BfAvatarComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Round avatar showing a photo or initials, in three sizes and four color variants",
+      "since": "0.1.0"
+    },
+    {
+      "name": "back-button",
+      "selector": "bf-back-button",
+      "className": "BfBackButtonComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Header back button that pops the page stack or falls back to a default route",
+      "since": "0.2.0"
+    },
+    {
+      "name": "badge",
+      "selector": "bf-badge",
+      "className": "BfBadgeComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Small status label in semantic tones, or a compact numeric pill for counts",
+      "since": "0.1.0"
+    },
+    {
+      "name": "button",
+      "selector": "bf-button",
+      "className": "BfButtonComponent",
+      "category": "Actions",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Pill-shaped action button with five variants, three sizes and a loading state",
+      "since": "0.1.0"
+    },
+    {
+      "name": "card",
+      "selector": "bf-card",
+      "className": "BfCardComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Content surface with an optional header slot, in four visual styles from raised to flat",
+      "since": "0.1.0"
+    },
+    {
+      "name": "checkbox",
+      "selector": "bf-checkbox",
+      "className": "BfCheckboxComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Rounded checkbox with an optional label that binds to Signal Forms",
+      "since": "0.1.0"
+    },
+    {
+      "name": "chip",
+      "selector": "bf-chip",
+      "className": "BfChipComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Toggleable filter chip with a check mark when selected, in tonal or ink style",
+      "since": "0.1.0"
+    },
+    {
+      "name": "chip-group",
+      "selector": "bf-chip-group",
+      "className": "BfChipGroupComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Named row of chips that picks one like radios, or groups independent toggles",
+      "since": "0.3.0"
+    },
+    {
+      "name": "content",
+      "selector": "bf-content",
+      "className": "BfContentComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Page's single scroll container that keeps focused fields clear of the soft keyboard",
+      "since": "0.2.0"
+    },
+    {
+      "name": "desktop-toast",
+      "selector": "bf-desktop-toast",
+      "className": "BfDesktopToastComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Desktop notification card in a bottom corner stack of up to three",
+      "since": "0.3.0"
+    },
+    {
+      "name": "dialog",
+      "selector": "bf-dialog",
+      "className": "BfDialogComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Desktop modal dialog with a title, scrolling body, footer actions and focus trap",
+      "since": "0.3.0"
+    },
+    {
+      "name": "empty-state",
+      "selector": "bf-empty-state",
+      "className": "BfEmptyStateComponent",
+      "category": "Feedback",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Placeholder for an empty screen or list with icon, title, message and action",
+      "since": "0.1.0"
+    },
+    {
+      "name": "field",
+      "selector": "bf-field",
+      "className": "BfFieldComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Label, help text and error text wrapper that wires ids for assistive tech",
+      "since": "0.1.0"
+    },
+    {
+      "name": "header",
+      "selector": "bf-header",
+      "className": "BfHeaderComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Page header toolbar with a large title that collapses into the toolbar on scroll",
+      "since": "0.2.0"
+    },
+    {
+      "name": "icon",
+      "selector": "bf-icon",
+      "className": "BfIconComponent",
+      "category": "Icons",
+      "entryPoint": "@bitforgehq/ui/icons",
+      "summary": "Tree-shakable Lucide icon renderer, decorative by default or labelled when meaningful",
+      "since": "0.1.0"
+    },
+    {
+      "name": "icon-button",
+      "selector": "bf-icon-button",
+      "className": "BfIconButtonComponent",
+      "category": "Actions",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Round icon-only button for toolbars and rows, with a required accessible label",
+      "since": "0.1.0"
+    },
+    {
+      "name": "input",
+      "selector": "bf-input",
+      "className": "BfInputComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Single-line text field with label, help and error text, icon slots and Signal Forms binding",
+      "since": "0.1.0"
+    },
+    {
+      "name": "list",
+      "selector": "bf-list",
+      "className": "BfListComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Container for list rows, inset by default with rounded corners on a warm background",
+      "since": "0.1.0"
+    },
+    {
+      "name": "list-item",
+      "selector": "bf-list-item",
+      "className": "BfListItemComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "List row with leading slot, title, subtitle, trailing slot and an optional chevron",
+      "since": "0.1.0"
+    },
+    {
+      "name": "menu",
+      "selector": "bf-menu",
+      "className": "BfMenuComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus",
+      "since": "0.3.0"
+    },
+    {
+      "name": "menu-button",
+      "selector": "bf-menu-button",
+      "className": "BfMenuButtonComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/overlay",
+      "summary": "Styled button that opens a menu, with outline, text, tonal and icon-only looks",
+      "since": "0.3.0"
+    },
+    {
+      "name": "modal",
+      "selector": "bf-modal",
+      "className": "BfModalComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Modal overlay shown as an inset card over the scaled-down page, or full screen",
+      "since": "0.2.0"
+    },
+    {
+      "name": "number-input",
+      "selector": "bf-number-input",
+      "className": "BfNumberInputComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui/number-input",
+      "summary": "Number field that binds number or null, with native min, max and step",
+      "since": "0.3.0"
+    },
+    {
+      "name": "page",
+      "selector": "bf-page",
+      "className": "BfPageComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Frame for one stacked mobile screen that supplies lifecycle events and shared page state",
+      "since": "0.2.0"
+    },
+    {
+      "name": "progress",
+      "selector": "bf-progress",
+      "className": "BfProgressComponent",
+      "category": "Data display",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Progress bar in two sizes and four tones for completion, quotas and unknown waits",
+      "since": "0.1.0"
+    },
+    {
+      "name": "radio-group",
+      "selector": "bf-radio-group",
+      "className": "BfRadioGroupComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Group of radio buttons for choosing one option, with optional per-option descriptions",
+      "since": "0.1.0"
+    },
+    {
+      "name": "refresher",
+      "selector": "bf-refresher",
+      "className": "BfRefresherComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull",
+      "since": "0.2.0"
+    },
+    {
+      "name": "segmented",
+      "selector": "bf-segmented",
+      "className": "BfSegmentedComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Segmented control for switching between two to four views, keyboard-navigable like radios",
+      "since": "0.1.0"
+    },
+    {
+      "name": "select",
+      "selector": "bf-select",
+      "className": "BfSelectComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Native single-choice dropdown styled like the text field, with Signal Forms binding",
+      "since": "0.1.0"
+    },
+    {
+      "name": "sheet",
+      "selector": "bf-sheet",
+      "className": "BfSheetComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Bottom sheet with snap points, drag to dismiss and a backdrop",
+      "since": "0.2.0"
+    },
+    {
+      "name": "spinner",
+      "selector": "bf-spinner",
+      "className": "BfSpinnerComponent",
+      "category": "Feedback",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Indeterminate loading spinner in three sizes that inherits its parent's text color",
+      "since": "0.1.0"
+    },
+    {
+      "name": "stack-outlet",
+      "selector": "bf-stack-outlet",
+      "className": "BfStackOutletComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Router outlet keeping a live page stack with slide transitions and iOS swipe back",
+      "since": "0.2.0"
+    },
+    {
+      "name": "tab",
+      "selector": "bf-tab",
+      "className": "BfTabComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "One tab bar destination with an icon, a label and an optional count badge",
+      "since": "0.1.0"
+    },
+    {
+      "name": "tab-bar",
+      "selector": "bf-tab-bar",
+      "className": "BfTabBarComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Floating pill tab bar for mobile apps with arrow-key selection and count badges",
+      "since": "0.1.0"
+    },
+    {
+      "name": "tabs",
+      "selector": "bf-tabs",
+      "className": "BfTabsComponent",
+      "category": "Navigation",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Tabs page with one navigation stack per tab, wiring the tab bar to the router",
+      "since": "0.2.0"
+    },
+    {
+      "name": "textarea",
+      "selector": "bf-textarea",
+      "className": "BfTextareaComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "Multi-line text field with label, help and error text, and Signal Forms binding",
+      "since": "0.1.0"
+    },
+    {
+      "name": "toast",
+      "selector": "bf-toast",
+      "className": "BfToastComponent",
+      "category": "Overlays",
+      "entryPoint": "@bitforgehq/ui/mobile",
+      "summary": "Passive status pill with an optional action that never steals focus",
+      "since": "0.2.0"
+    },
+    {
+      "name": "toggle",
+      "selector": "bf-toggle",
+      "className": "BfToggleComponent",
+      "category": "Forms",
+      "entryPoint": "@bitforgehq/ui",
+      "summary": "On/off switch for settings that apply immediately, with Signal Forms binding",
+      "since": "0.1.0"
+    }
+  ]
+}