@egose/shadcn-theme-ng-tw 0.0.28 → 0.2.0

package/badge/README.md

@@ -1,64 +1,319 @@
-# Badge
+# Badge (`@egose/shadcn-theme-ng/badge`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.2.0.
+A compact status/count chip in the shadcn/ui Badge style: a small pill for labels like "New",
+"Beta", unread counts, or role tags. Use it inline in headings, list rows, tabs, and buttons where
+a full [Alert](https://ui.shadcn.com/docs/components/alert) would be too heavy.
 
-## Code scaffolding
+This is a **standalone component with no brain primitive and no `*Imports`/`*Module` wrapper** —
+import `HlmBadge` itself. Variants come from a `cva` table (`badgeVariants`), merged with
+`hlm()`; the `outline` / `outline-filled` appearances add per-tone border/hover classes computed
+by private helpers. An imperative `setClass()` escape hatch appends extra classes.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+> **Ships as:** `@egose/shadcn-theme-ng/badge` and `@egose/shadcn-theme-ng-tw/badge`
+> (the `tw:`-prefixed Tailwind variant). Both expose the identical TypeScript surface; only the
+> emitted Tailwind class strings differ. See the [package README](../../README.md) for install
+> steps, peer dependencies, and Tailwind setup. Do not publish this project directory independently.
+
+## Installation
 
 ```bash
-ng generate component component-name
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# tw:-prefixed Tailwind variant
+npm install @egose/shadcn-theme-ng-tw
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+Peer dependencies (Angular, `@spartan-ng/brain`, `@ng-icons/*`, `rxjs`, …) are documented in the
+[package README](../../README.md#peer-dependencies). Runtime styling helper:
+`@egose/shadcn-theme-ng/utils` (`hlm()`).
 
-```bash
-ng generate --help
+## Imports
+
+`HlmBadge` is exported from the subpath root (`projects/badge/src/public-api.ts`). Note there is
+**no** `HlmBadgeImports` array and **no** `HlmBadgeModule` — import the component directly:
+
+```ts
+import {
+  HlmBadge,
+  badgeVariants,
+  type BadgeVariants,
+  type BadgeVariantType,
+  type BadgeSizeType,
+  type BadgeAppearanceType,
+} from '@egose/shadcn-theme-ng/badge';
+// tw variant: replace with '@egose/shadcn-theme-ng-tw/badge'
 ```
 
-## Building
+Standalone component usage:
 
-To build the library, run:
+```ts
+import { Component } from '@angular/core';
+import { HlmBadge } from '@egose/shadcn-theme-ng/badge';
 
-```bash
-ng build badge
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [HlmBadge],
+  template: `<span hlmBadge>New</span>`,
+})
+export class DemoComponent {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+NgModule-based consumer — list the component in the module imports (it is standalone):
 
-### Publishing the Library
+```ts
+import { NgModule } from '@angular/core';
+import { HlmBadge } from '@egose/shadcn-theme-ng/badge';
 
-Once the project is built, you can publish your library by following these steps:
+@NgModule({ imports: [HlmBadge] })
+export class DemoModule {}
+```
 
-1. Navigate to the `dist` directory:
+## Anatomy / Structure
 
-   ```bash
-   cd dist/badge
-   ```
+```html
+<span hlmBadge variant="success" size="default" appearance="solid">Active</span>
+<a hlmBadge variant="link" href="/changelog">v2.4.1</a>
+```
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+Real selector (from source):
 
-## Running unit tests
+| Class      | Selector(s)                   | Kind      |
+| ---------- | ----------------------------- | --------- |
+| `HlmBadge` | `span[hlmBadge], a[hlmBadge]` | Component |
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+Only `<span>` and `<a>` hosts match — the component projects its content (`<ng-content>`) and
+computes its host class from `variant` + `size` + `appearance` + `userClass`.
 
-```bash
-ng test
+## API reference
+
+### `HlmBadge` — `span[hlmBadge], a[hlmBadge]`
+
+| Input        | Type                  | Default     | Description                                                                                                                                            |
+| ------------ | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant`    | `BadgeVariantType`    | `'primary'` | Color tone (13 values, see below).                                                                                                                     |
+| `size`       | `BadgeSizeType`       | `'default'` | `sm` (`h-5 px-2 text-xs`), `default` (`h-6 px-3 text-sm`), `lg` (`h-7 px-4 text-base`).                                                                |
+| `appearance` | `BadgeAppearanceType` | `'solid'`   | `solid` (filled), `outline` (white bg + tone border/text), `outline-filled` (outline + fills with the tone on hover).                                  |
+| `userClass`  | `ClassValue`          | `''`        | Extra classes merged into the `cva` call. **Note:** unlike most `hlm*` pieces this input has **no `class` alias** — bind `[userClass]`, not `[class]`. |
+
+| Method     | Signature                         | Description                                                                      |
+| ---------- | --------------------------------- | -------------------------------------------------------------------------------- |
+| `setClass` | `setClass(classes: string): void` | Imperatively appends extra classes (stored in a private signal and merged last). |
+
+`variant` values: `primary` · `secondary` · `success` · `warning` · `danger` · `info` ·
+`light` · `dark` · `accent` · `destructive` · `muted` · `link` · `ghost`.
+
+Exported helpers: `badgeVariants` (the `cva` table — reuse it for custom badge-like hosts),
+`BadgeVariants`, `BadgeVariantType`, `BadgeSizeType`, `BadgeAppearanceType`.
+
+## Examples
+
+### 1. Basic badge
+
+```ts
+import { Component } from '@angular/core';
+import { HlmBadge } from '@egose/shadcn-theme-ng/badge';
+
+@Component({
+  selector: 'app-badge-basic',
+  standalone: true,
+  imports: [HlmBadge],
+  template: `<span hlmBadge>New</span>`,
+})
+export class BadgeBasicComponent {}
 ```
 
-## Running end-to-end tests
+```html
+<app-badge-basic />
+```
 
-For end-to-end (e2e) testing, run:
+### 2. All variants × solid
 
-```bash
-ng e2e
+```ts
+import { Component } from '@angular/core';
+import { HlmBadge, type BadgeVariantType } from '@egose/shadcn-theme-ng/badge';
+
+@Component({
+  selector: 'app-badge-variants',
+  standalone: true,
+  imports: [HlmBadge],
+  template: `
+    <div class="tw:flex tw:flex-wrap tw:gap-2">
+      @for (v of variants; track v) {
+        <span hlmBadge [variant]="v">{{ v }}</span>
+      }
+    </div>
+  `,
+})
+export class BadgeVariantsComponent {
+  readonly variants: BadgeVariantType[] = [
+    'primary',
+    'secondary',
+    'success',
+    'warning',
+    'danger',
+    'info',
+    'light',
+    'dark',
+    'accent',
+    'destructive',
+    'muted',
+    'link',
+    'ghost',
+  ];
+}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+### 3. Sizes and outline appearances
+
+```ts
+import { Component } from '@angular/core';
+import { HlmBadge } from '@egose/shadcn-theme-ng/badge';
+
+@Component({
+  selector: 'app-badge-sizes',
+  standalone: true,
+  imports: [HlmBadge],
+  template: `
+    <div class="tw:flex tw:items-center tw:gap-2">
+      <span hlmBadge size="sm">small</span>
+      <span hlmBadge size="default">default</span>
+      <span hlmBadge size="lg">large</span>
+    </div>
+    <div class="tw:mt-3 tw:flex tw:items-center tw:gap-2">
+      <span hlmBadge variant="success" appearance="outline">outline</span>
+      <span hlmBadge variant="destructive" appearance="outline-filled">outline-filled (hover me)</span>
+    </div>
+  `,
+})
+export class BadgeSizesComponent {}
+```
+
+### 4. Link badge + count badge composed with other components
+
+`a[hlmBadge]` is a real link host; badges also sit naturally inside buttons and headings:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmBadge } from '@egose/shadcn-theme-ng/badge';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-badge-composed',
+  standalone: true,
+  imports: [HlmBadge, ...HlmButtonImports],
+  template: `
+    <h2 class="tw:flex tw:items-center tw:gap-2 tw:text-lg tw:font-semibold">
+      Inbox <span hlmBadge variant="secondary" size="sm">{{ unread() }}</span>
+    </h2>
+    <p class="tw:mt-2">
+      <a hlmBadge variant="link" href="/changelog">v2.4.1 — see what's new</a>
+    </p>
+    <button hlmButton variant="outline" size="sm" class="tw:mt-3" (click)="unread.set(0)">
+      Mark all read <span hlmBadge variant="muted" size="sm">{{ unread() }}</span>
+    </button>
+  `,
+})
+export class BadgeComposedComponent {
+  readonly unread = signal(7);
+}
+```
+
+### 5. Status mapping from domain state (signal-driven)
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { HlmBadge, type BadgeVariantType } from '@egose/shadcn-theme-ng/badge';
+
+type OrderState = 'pending' | 'shipped' | 'delivered' | 'cancelled';
+
+const tone: Record<OrderState, BadgeVariantType> = {
+  pending: 'warning',
+  shipped: 'info',
+  delivered: 'success',
+  cancelled: 'destructive',
+};
+
+@Component({
+  selector: 'app-badge-status',
+  standalone: true,
+  imports: [HlmBadge],
+  template: `
+    <ul class="tw:flex tw:flex-col tw:gap-2">
+      @for (o of orders(); track o.id) {
+        <li class="tw:flex tw:items-center tw:gap-2 tw:text-sm">
+          Order #{{ o.id }}
+          <span hlmBadge [variant]="toneFor(o.state)" [userClass]="'tw:capitalize'">
+            {{ o.state }}
+          </span>
+        </li>
+      }
+    </ul>
+  `,
+})
+export class BadgeStatusComponent {
+  readonly orders = signal<{ id: number; state: OrderState }[]>([
+    { id: 101, state: 'pending' },
+    { id: 102, state: 'shipped' },
+    { id: 103, state: 'delivered' },
+    { id: 104, state: 'cancelled' },
+  ]);
+  toneFor = (s: OrderState) => tone[s];
+}
+```
+
+### 6. Advanced: `badgeVariants()` for custom hosts + imperative `setClass`
+
+Reuse the exported `cva` table for elements that cannot host the directive, and use `setClass`
+for runtime class injection (e.g. from a directive or test harness):
+
+```ts
+import { Component, viewChild } from '@angular/core';
+import { HlmBadge, badgeVariants } from '@egose/shadcn-theme-ng/badge';
+
+@Component({
+  selector: 'app-badge-advanced',
+  standalone: true,
+  imports: [HlmBadge],
+  template: `
+    <!-- custom host styled identically without the directive -->
+    <mark [class]="markClass">review</mark>
+    <!-- imperative escape hatch -->
+    <span hlmBadge #imp variant="info">runtime-tinted</span>
+    <button (click)="tint()">Tint via setClass()</button>
+  `,
+})
+export class BadgeAdvancedComponent {
+  readonly markClass = badgeVariants({ variant: 'warning', size: 'sm' });
+  private readonly badge = viewChild<HlmBadge>('imp');
+
+  tint() {
+    this.badge()?.setClass('tw:tracking-widest tw:uppercase');
+  }
+}
+```
+
+## Accessibility notes
+
+- Badges are visual labels, not live regions: dynamic counts ("7 unread") should live next to
+  properly labelled content (e.g. an `aria-label="Inbox, 7 unread"` heading) rather than relying
+  on the badge text alone.
+- Never convey state by color only — the examples above pair each tone with explicit text
+  ("delivered", "cancelled"). The `light`/`ghost` tones are low-contrast by design; reserve them
+  for large/bold text or decorative contexts.
+- `a[hlmBadge]` must have a real `href` (or be replaced by a `<button>`); do not use a link badge
+  as a click-handler span — keyboard users lose focusability.
+
+## Theming / CSS variables
+
+Class-based `cva` theming over shadcn tokens (`bg-*/text-*`); no component-specific CSS variables.
+Extend per-instance with `[userClass]` (note: no `class` alias on this component) or reuse
+`badgeVariants()` for custom hosts.
 
-## Additional Resources
+## Related subpaths
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+- `@egose/shadcn-theme-ng/alert` — full banner alerts for non-inline feedback
+- `@egose/shadcn-theme-ng/basic-alert` — ready-made icon + title + description alert
+- `@egose/shadcn-theme-ng/button` — action buttons badges decorate
+- `@egose/shadcn-theme-ng/avatar` — identity visuals that pair with role/status badges

package/badge/fesm2022/badge.mjs

@@ -115,10 +115,10 @@ class HlmBadge {
         };
         return colors[variant];
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmBadge, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.0.7", type: HlmBadge, isStandalone: true, selector: "span[hlmBadge], a[hlmBadge]", inputs: { variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, appearance: { classPropertyName: "appearance", publicName: "appearance", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "userClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "_computedClass()" } }, ngImport: i0, template: `<ng-content></ng-content>`, isInline: true });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmBadge, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmBadge, isStandalone: true, selector: "span[hlmBadge], a[hlmBadge]", inputs: { variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, appearance: { classPropertyName: "appearance", publicName: "appearance", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "userClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "_computedClass()" } }, ngImport: i0, template: `<ng-content></ng-content>`, isInline: true });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmBadge, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmBadge, decorators: [{
             type: Component,
             args: [{
                     selector: 'span[hlmBadge], a[hlmBadge]',
@@ -140,4 +140,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 
 export { HlmBadge, badgeVariants };
-//# sourceMappingURL=badge.mjs.map
+