@egose/shadcn-theme-ng 0.0.28 → 0.2.0

package/basic-alert/README.md

@@ -1,64 +1,354 @@
-# BasicAlert
+# Basic Alert (`@egose/shadcn-theme-ng/basic-alert`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+A one-tag convenience alert in the shadcn/ui Alert style: icon + title + description with zero
+composition boilerplate. Where `@egose/shadcn-theme-ng/alert` asks you to assemble `HlmAlert` /
+`HlmAlertIcon` / `HlmAlertTitle` / `HlmAlertDescription` by hand, `EgBasicAlert` takes `variant`,
+`appearance`, `title`, and `description` inputs and renders the whole banner — picking a matching
+Lucide icon per tone automatically.
 
-## Code scaffolding
+This is a **standalone component with no `*Imports`/`*Module` wrapper** — import `EgBasicAlert`
+itself. Internally it composes the `alert` subpath directives plus `NgIcon`/`HlmIcon`, and maps
+each `VariantType` to an icon name through its `getIconName()` method.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+> **Ships as:** `@egose/shadcn-theme-ng/basic-alert` and `@egose/shadcn-theme-ng-tw/basic-alert`
+> (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). This subpath depends at runtime on
+`@egose/shadcn-theme-ng/alert` (`HlmAlert*`, `VariantType`, `AppearanceType`),
+`@egose/shadcn-theme-ng/icon` (`HlmIcon`), and `@ng-icons/lucide` for its icon set.
 
-```bash
-ng generate --help
+## Imports
+
+`EgBasicAlert` is exported from the subpath root (`projects/basic-alert/src/public-api.ts`). Note
+there is **no** `EgBasicAlertImports` array and **no** `*Module` — import the component directly:
+
+```ts
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+// tw variant: replace with '@egose/shadcn-theme-ng-tw/basic-alert'
 ```
 
-## Building
+Standalone component usage:
 
-To build the library, run:
+```ts
+import { Component } from '@angular/core';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
 
-```bash
-ng build basic-alert
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [EgBasicAlert],
+  template: `<eg-basic-alert variant="info" title="Heads up" description="..." />`,
+})
+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 { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
 
-Once the project is built, you can publish your library by following these steps:
+@NgModule({ imports: [EgBasicAlert] })
+export class DemoModule {}
+```
 
-1. Navigate to the `dist` directory:
+## Anatomy / Structure
 
-   ```bash
-   cd dist/basic-alert
-   ```
+```html
+<eg-basic-alert variant="success" appearance="solid" title="Saved" description="All changes stored." />
+```
 
-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         | Kind      |
+| -------------- | ---------------- | --------- |
+| `EgBasicAlert` | `eg-basic-alert` | Component |
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+Its internal template (from source) is:
 
-```bash
-ng test
+```html
+<div hlmAlert [variant]="variant()" [appearance]="appearance()" class="">
+  <ng-icon hlm hlmAlertIcon [name]="getIconName(variant())" />
+  <h4 hlmAlertTitle class="tw:capitalize">{{ title() }}</h4>
+  <p hlmAlertDescription>{{ description() }}</p>
+</div>
 ```
 
-## Running end-to-end tests
+So the rendered output is a standard `HlmAlert` banner whose title is auto-capitalized
+(`tw:capitalize`) and whose icon is chosen by `getIconName(variant())`.
 
-For end-to-end (e2e) testing, run:
+## API reference
 
-```bash
-ng e2e
+### `EgBasicAlert` — `eg-basic-alert`
+
+| Input         | Type                                            | Default   | Description                                       |
+| ------------- | ----------------------------------------------- | --------- | ------------------------------------------------- |
+| `variant`     | `VariantType` (re-exported from `.../alert`)    | `'info'`  | Color tone; also selects the icon (see table).    |
+| `appearance`  | `AppearanceType` (re-exported from `.../alert`) | `'solid'` | `'solid'` or `'light'` — forwarded to `HlmAlert`. |
+| `title`       | `string`                                        | `''`      | Banner heading (rendered capitalized).            |
+| `description` | `string`                                        | `''`      | Banner body text.                                 |
+
+| Method        | Signature                                   | Description                                                                                                              |
+| ------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `getIconName` | `getIconName(variant: VariantType): string` | Returns the `ng-icon` name for a tone. Public — call it in your own templates to keep custom alerts visually consistent. |
+
+Variant → icon mapping (read from `getIconName` source):
+
+| `variant`                      | Icon                   |
+| ------------------------------ | ---------------------- |
+| `success`                      | `lucideCircleCheck`    |
+| `info`                         | `lucideInfo`           |
+| `warning`                      | `lucideBatteryWarning` |
+| `danger`, `destructive`        | `lucideCircleAlert`    |
+| `muted`                        | `lucideBell`           |
+| `accent`                       | `lucideStar`           |
+| `primary`                      | `lucideThumbsUp`       |
+| `secondary`                    | `lucideZap`            |
+| `link`                         | `lucideLink`           |
+| `ghost`                        | `lucideGhost`          |
+| `light`, `dark`, anything else | `lucideInfo` (default) |
+
+`VariantType` values (from `.../alert`): `primary` · `secondary` · `success` · `warning` ·
+`danger` · `info` · `light` · `dark` · `accent` · `destructive` · `muted` · `link` · `ghost`.
+
+## Examples
+
+### 1. Basic usage
+
+```ts
+import { Component } from '@angular/core';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+
+@Component({
+  selector: 'app-basic-alert-basic',
+  standalone: true,
+  imports: [EgBasicAlert],
+  template: `
+    <eg-basic-alert
+      variant="info"
+      title="Maintenance scheduled"
+      description="The dashboard will be offline Sunday 02:00–04:00 UTC."
+    />
+  `,
+})
+export class BasicAlertBasicComponent {}
+```
+
+```html
+<app-basic-alert-basic />
+```
+
+### 2. Semantic tones (success / warning / danger)
+
+```ts
+import { Component } from '@angular/core';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+
+@Component({
+  selector: 'app-basic-alert-tones',
+  standalone: true,
+  imports: [EgBasicAlert],
+  template: `
+    <eg-basic-alert variant="success" title="Payment confirmed" description="Receipt emailed." class="tw:mb-3" />
+    <eg-basic-alert variant="warning" title="Storage almost full" description="9.2 of 10 GB used." class="tw:mb-3" />
+    <eg-basic-alert variant="danger" title="Sync failed" description="Retrying in 30 seconds." />
+  `,
+})
+export class BasicAlertTonesComponent {}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+(`class` on the host works because every Angular component host accepts a `class` attribute;
+inner banner styling still comes from the alert subpath.)
+
+### 3. Light appearance across variants
+
+```ts
+import { Component } from '@angular/core';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+import type { VariantType } from '@egose/shadcn-theme-ng/alert';
+
+@Component({
+  selector: 'app-basic-alert-light',
+  standalone: true,
+  imports: [EgBasicAlert],
+  template: `
+    @for (v of variants; track v) {
+      <eg-basic-alert
+        [variant]="v"
+        appearance="light"
+        [title]="v"
+        [description]="'The ' + v + ' tone in light appearance.'"
+        class="tw:mb-3 tw:block"
+      />
+    }
+  `,
+})
+export class BasicAlertLightComponent {
+  readonly variants: VariantType[] = ['primary', 'success', 'warning', 'danger', 'info', 'muted'];
+}
+```
+
+### 4. Signal-driven form feedback
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+
+@Component({
+  selector: 'app-basic-alert-form',
+  standalone: true,
+  imports: [EgBasicAlert, ReactiveFormsModule],
+  template: `
+    <label class="tw:mb-1 tw:block tw:text-sm tw:font-medium" for="email">Email</label>
+    <input id="email" [formControl]="email" placeholder="you@example.com" class="tw:mb-3 tw:block" />
+    @if (banner(); as b) {
+      <eg-basic-alert [variant]="b.variant" [title]="b.title" [description]="b.description" />
+    }
+  `,
+})
+export class BasicAlertFormComponent {
+  readonly email = new FormControl('', { validators: [Validators.required, Validators.email], nonNullable: true });
+  private readonly submitted = signal(false);
+
+  readonly banner = computed(() => {
+    if (!this.submitted()) return null;
+    return this.email.valid
+      ? { variant: 'success' as const, title: 'Looks good', description: 'We will send the receipt there.' }
+      : {
+          variant: 'destructive' as const,
+          title: 'Invalid email',
+          description: 'Enter an address like you@example.com.',
+        };
+  });
+
+  constructor() {
+    this.email.valueChanges.subscribe(() => this.submitted.set(true));
+  }
+}
+```
+
+### 5. Dismissible + async loading pattern
+
+```ts
+import { Component, signal } from '@angular/core';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+
+@Component({
+  selector: 'app-basic-alert-async',
+  standalone: true,
+  imports: [EgBasicAlert],
+  template: `
+    <button (click)="save()" [disabled]="saving()">Save settings</button>
+    @if (saving()) {
+      <eg-basic-alert variant="muted" title="Saving" description="Writing your settings…" class="tw:mt-3 tw:block" />
+    } @else if (saved()) {
+      <eg-basic-alert
+        variant="success"
+        title="Saved"
+        description="Settings updated just now."
+        class="tw:mt-3 tw:block"
+      />
+    } @else if (failed()) {
+      <eg-basic-alert
+        variant="destructive"
+        title="Save failed"
+        description="Check your connection and retry."
+        class="tw:mt-3 tw:block"
+      />
+    }
+  `,
+})
+export class BasicAlertAsyncComponent {
+  readonly saving = signal(false);
+  readonly saved = signal(false);
+  readonly failed = signal(false);
+
+  async save() {
+    this.saving.set(true);
+    this.saved.set(false);
+    this.failed.set(false);
+    try {
+      await fetch('/api/settings', { method: 'POST' });
+      this.saved.set(true);
+    } catch {
+      this.failed.set(true);
+    } finally {
+      this.saving.set(false);
+    }
+  }
+}
+```
+
+### 6. Advanced: reusing `getIconName` for a custom banner
+
+Because `getIconName` is public, custom compositions can stay icon-consistent with the built-in
+mapping. Grab the component with a template ref (or `@ViewChild`) and call it:
+
+```ts
+import { Component, viewChild } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import * as lucide from '@ng-icons/lucide';
+import { EgBasicAlert } from '@egose/shadcn-theme-ng/basic-alert';
+import { HlmAlertImports, type VariantType } from '@egose/shadcn-theme-ng/alert';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  selector: 'app-basic-alert-custom',
+  standalone: true,
+  imports: [...HlmAlertImports, EgBasicAlert, NgIcon, HlmIcon],
+  providers: [provideIcons({ ...lucide })],
+  template: `
+    <!-- hidden helper instance purely as an icon-name resolver -->
+    <eg-basic-alert #helper variant="info" title="" description="" class="tw:hidden" />
+    <div hlmAlert [variant]="variant">
+      <ng-icon hlm hlmAlertIcon [name]="helper.getIconName(variant)" />
+      <h4 hlmAlertTitle>Custom layout, stock icon</h4>
+      <p hlmAlertDescription>Extra actions or rich content here — the icon still matches the {{ variant }} tone.</p>
+    </div>
+  `,
+})
+export class BasicAlertCustomComponent {
+  readonly variant: VariantType = 'accent';
+  private readonly helper = viewChild<EgBasicAlert>('helper');
+}
+```
+
+> Prefer importing the `alert` subpath directly for hand-built banners; the helper-instance trick
+> above is only for teams that want a single source of truth for the icon map.
+
+## Accessibility notes
+
+- Inherits everything from `HlmAlert`: the banner carries `role="alert"`, so dynamically shown
+  instances (after save/fail) are announced. Do not render empty `title` + `description`
+  instances permanently — screen readers would announce an empty alert region.
+- Titles render with `tw:capitalize` — keep them short, human-phrased headings ("Save failed",
+  not "ERR_SAVE_500"). The description should state the consequence and next step.
+- The icon is decorative; all meaning must be in the text since icon names/tones alone are not
+  announced.
+
+## Theming / CSS variables
+
+No variables of its own — theming flows through the composed `HlmAlert` (`variant` /
+`appearance` + shadcn tokens). For layouts beyond icon/title/description, drop down to
+`@egose/shadcn-theme-ng/alert` and compose the directives yourself.
 
-## 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` — hand-composed banners (`HlmAlert*`) and the `VariantType` / `AppearanceType` types
+- `@egose/shadcn-theme-ng/badge` — inline chips for compact status
+- `@egose/shadcn-theme-ng/sonner` — transient toasts for fire-and-forget feedback
+- `@egose/shadcn-theme-ng/icon` — `HlmIcon` and icon configuration

package/basic-alert/fesm2022/basic-alert.mjs

@@ -43,8 +43,8 @@ class EgBasicAlert {
                 return 'lucideInfo';
         }
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: EgBasicAlert, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.0.7", type: EgBasicAlert, isStandalone: true, selector: "eg-basic-alert", inputs: { variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, appearance: { classPropertyName: "appearance", publicName: "appearance", isSignal: true, isRequired: false, transformFunction: null }, title: { classPropertyName: "title", publicName: "title", isSignal: true, isRequired: false, transformFunction: null }, description: { classPropertyName: "description", publicName: "description", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgBasicAlert, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: EgBasicAlert, isStandalone: true, selector: "eg-basic-alert", inputs: { variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, appearance: { classPropertyName: "appearance", publicName: "appearance", isSignal: true, isRequired: false, transformFunction: null }, title: { classPropertyName: "title", publicName: "title", isSignal: true, isRequired: false, transformFunction: null }, description: { classPropertyName: "description", publicName: "description", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
             provideIcons({
                 lucideCircleCheck,
                 lucideInfo,
@@ -57,15 +57,9 @@ class EgBasicAlert {
                 lucideLink,
                 lucideGhost,
             }),
-        ], ngImport: i0, template: `
-    <div hlmAlert [variant]="variant()" [appearance]="appearance()" class="">
-      <ng-icon hlm hlmAlertIcon [name]="getIconName(variant())" />
-      <h4 hlmAlertTitle class="capitalize">{{ title() }}</h4>
-      <p hlmAlertDescription>{{ description() }}</p>
-    </div>
-  `, isInline: true, dependencies: [{ kind: "directive", type: HlmAlert, selector: "[hlmAlert]", inputs: ["class", "variant", "appearance"] }, { kind: "directive", type: HlmAlertIcon, selector: "[hlmAlertIcon]" }, { kind: "directive", type: HlmAlertTitle, selector: "[hlmAlertTitle]", inputs: ["class"] }, { kind: "directive", type: HlmAlertDescription, selector: "[hlmAlertDesc],[hlmAlertDescription]", inputs: ["class"] }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }, { kind: "directive", type: HlmIcon, selector: "ng-icon[hlm]", inputs: ["size"] }] });
+        ], ngImport: i0, template: "\n    <div hlmAlert [variant]=\"variant()\" [appearance]=\"appearance()\" class=\"\">\n      <ng-icon hlm hlmAlertIcon [name]=\"getIconName(variant())\" />\n      <h4 hlmAlertTitle class=\"capitalize\">{{ title() }}</h4>\n      <p hlmAlertDescription>{{ description() }}</p>\n    </div>\n  ", isInline: true, dependencies: [{ kind: "directive", type: HlmAlert, selector: "[hlmAlert]", inputs: ["class", "variant", "appearance"] }, { kind: "directive", type: HlmAlertIcon, selector: "[hlmAlertIcon]" }, { kind: "directive", type: HlmAlertTitle, selector: "[hlmAlertTitle]", inputs: ["class"] }, { kind: "directive", type: HlmAlertDescription, selector: "[hlmAlertDesc],[hlmAlertDescription]", inputs: ["class"] }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }, { kind: "directive", type: HlmIcon, selector: "ng-icon[hlm]", inputs: ["size"] }] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: EgBasicAlert, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgBasicAlert, decorators: [{
             type: Component,
             args: [{
                     selector: 'eg-basic-alert',
@@ -85,13 +79,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                             lucideGhost,
                         }),
                     ],
-                    template: `
-    <div hlmAlert [variant]="variant()" [appearance]="appearance()" class="">
-      <ng-icon hlm hlmAlertIcon [name]="getIconName(variant())" />
-      <h4 hlmAlertTitle class="capitalize">{{ title() }}</h4>
-      <p hlmAlertDescription>{{ description() }}</p>
-    </div>
-  `,
+                    template: "\n    <div hlmAlert [variant]=\"variant()\" [appearance]=\"appearance()\" class=\"\">\n      <ng-icon hlm hlmAlertIcon [name]=\"getIconName(variant())\" />\n      <h4 hlmAlertTitle class=\"capitalize\">{{ title() }}</h4>\n      <p hlmAlertDescription>{{ description() }}</p>\n    </div>\n  ",
                 }]
         }], propDecorators: { variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], appearance: [{ type: i0.Input, args: [{ isSignal: true, alias: "appearance", required: false }] }], title: [{ type: i0.Input, args: [{ isSignal: true, alias: "title", required: false }] }], description: [{ type: i0.Input, args: [{ isSignal: true, alias: "description", required: false }] }] } });
 
@@ -104,4 +92,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 
 export { EgBasicAlert };
-//# sourceMappingURL=basic-alert.mjs.map
+