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

package/icon/README.md

@@ -1,3 +1,240 @@
-# Icon Subpath
+# Icon (`@egose/shadcn-theme-ng/icon`)
 
-This project ships only as `@egose/shadcn-theme-ng/icon` or `@egose/shadcn-theme-ng-tw/icon`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+`HlmIcon` is a thin directive that sizes `@ng-icons/core` icons consistently with the shadcn theme. It applies to `ng-icon` elements (`selector: 'ng-icon[hlm]'`) and maps t-shirt sizes (`xs`–`xl`) to pixel values via the `--ng-icon__size` CSS variable — the shadcn/ui equivalent of the `size-*` icon convention. A global default size can be set once with `provideHlmIconConfig`.
+
+> **Ships as:** `@egose/shadcn-theme-ng/icon` (plain Tailwind) and `@egose/shadcn-theme-ng-tw/icon` (`tw:`-prefixed variant). See the [package README](../../README.md) for installation, peer dependencies, and the Tailwind-variant contract. Do not publish this project directory independently.
+
+## Installation
+
+```bash
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies (Angular, `@ng-icons/core`, …) are documented in the [package README](../../README.md#peer-dependencies). You must also register the icons you use with `provideIcons` from `@ng-icons/core` (see examples).
+
+```ts
+import { HlmIconImports } from '@egose/shadcn-theme-ng/icon';
+// tw variant:
+// import { HlmIconImports } from '@egose/shadcn-theme-ng-tw/icon';
+```
+
+## Imports
+
+```ts
+// Standalone component — spread the imports array:
+import { HlmIconImports } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, ...HlmIconImports], // or just [NgIcon, HlmIcon]
+  providers: [provideIcons({ lucidePlus })],
+  template: `<ng-icon hlm name="lucidePlus" size="sm" />`,
+})
+export class MyComp {}
+```
+
+```ts
+// NgModule-based — import the module:
+import { HlmIconModule } from '@egose/shadcn-theme-ng/icon';
+
+@NgModule({ imports: [HlmIconModule] })
+export class MyModule {}
+```
+
+Exported from `src/public-api.ts`: `HlmIcon`, `IconSize`, `HlmIconConfig`, `provideHlmIconConfig`, `injectHlmIconConfig`, plus `HlmIconImports` and `HlmIconModule`.
+
+> Note: `HlmIcon` decorates `ng-icon` — you still import `NgIcon` itself from `@ng-icons/core` and register glyphs with `provideIcons`.
+
+## Anatomy / Structure
+
+```html
+<!-- hlm attribute activates the sizing directive on any ng-icon -->
+<ng-icon hlm name="lucidePlus" size="sm" />
+```
+
+The directive sets `[style.--ng-icon__size]` from the `size` input; named sizes resolve to pixels, anything else passes through verbatim as CSS.
+
+## API reference
+
+### `ng-icon[hlm]` — `HlmIcon`
+
+| Input  | Type       | Default                 | Description                                                                                                                                              |
+| ------ | ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size` | `IconSize` | config default (`base`) | `xs` → `12px`, `sm` → `16px`, `base` → `24px`, `lg` → `32px`, `xl` → `48px`, `none` → `none`, or any custom CSS size string (e.g. `'20px'`, `'1.5rem'`). |
+
+No outputs. `IconSize = 'xs' | 'sm' | 'base' | 'lg' | 'xl' | 'none' | (string & {})`.
+
+### Config — `HlmIconConfig` / `provideHlmIconConfig` / `injectHlmIconConfig`
+
+| API                                                    | Signature               | Description                                                                           |
+| ------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------- |
+| `HlmIconConfig`                                        | `{ size: IconSize }`    | Global icon config shape (default `{ size: 'base' }`).                                |
+| `provideHlmIconConfig(config: Partial<HlmIconConfig>)` | returns `ValueProvider` | Provide once (root or feature) to change the default `size` for every `ng-icon[hlm]`. |
+| `injectHlmIconConfig()`                                | returns `HlmIconConfig` | Reads the ambient config (falls back to defaults).                                    |
+
+## Examples
+
+### 1. Basic icon with registered glyph
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucidePlus } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucidePlus })],
+  template: `<ng-icon hlm name="lucidePlus" />`,
+})
+export class BasicExample {}
+```
+
+### 2. All named sizes
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideSearch } from '@ng-icons/lucide';
+import { HlmIconImports } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIconImports],
+  providers: [provideIcons({ lucideSearch })],
+  template: `
+    <div class="tw:flex tw:items-center tw:gap-4">
+      <ng-icon hlm name="lucideSearch" size="xs" />
+      <ng-icon hlm name="lucideSearch" size="sm" />
+      <ng-icon hlm name="lucideSearch" size="base" />
+      <ng-icon hlm name="lucideSearch" size="lg" />
+      <ng-icon hlm name="lucideSearch" size="xl" />
+    </div>
+  `,
+})
+export class SizesExample {}
+```
+
+### 3. Custom CSS sizes (any string passes through)
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideBell } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucideBell })],
+  template: `
+    <div class="tw:flex tw:items-center tw:gap-4">
+      <ng-icon hlm name="lucideBell" size="20px" />
+      <ng-icon hlm name="lucideBell" size="1.5rem" />
+      <ng-icon hlm name="lucideBell" size="none" />
+    </div>
+  `,
+})
+export class CustomSizeExample {}
+```
+
+### 4. Global default via `provideHlmIconConfig`
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideCheck, lucideX } from '@ng-icons/lucide';
+import { HlmIcon, provideHlmIconConfig } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucideCheck, lucideX }), provideHlmIconConfig({ size: 'sm' })],
+  template: `
+    <!-- both inherit size="sm" unless overridden -->
+    <ng-icon hlm name="lucideCheck" />
+    <ng-icon hlm name="lucideX" size="lg" />
+  `,
+})
+export class ConfigExample {}
+```
+
+### 5. Icons inside buttons and inputs (composition)
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideSearch, lucidePlus } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon, HlmButton, HlmInputGroupImports],
+  providers: [provideIcons({ lucideSearch, lucidePlus })],
+  template: `
+    <button hlmBtn type="button"><ng-icon hlm name="lucidePlus" size="sm" /> New item</button>
+
+    <div hlmInputGroup>
+      <span hlmInputGroupText><ng-icon hlm name="lucideSearch" size="sm" /></span>
+      <input hlmInputGroupInput placeholder="Search…" aria-label="Search" />
+    </div>
+  `,
+})
+export class CompositionExample {}
+```
+
+> The input-group addon styles (`[&>ng-icon…]` hooks) assume icons sized through this directive — prefer `size="sm"` or smaller inside addons/buttons so text and glyph align.
+
+### 6. Dynamic icon + size with signals
+
+```ts
+import { Component, signal } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideLoaderCircle, lucideCheck } from '@ng-icons/lucide';
+import { HlmIcon, type IconSize } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucideLoaderCircle, lucideCheck })],
+  template: `
+    <p>
+      <ng-icon hlm [name]="saving() ? 'lucideLoaderCircle' : 'lucideCheck'" [size]="iconSize()" />
+      {{ saving() ? 'Saving…' : 'Saved' }}
+    </p>
+    <button type="button" (click)="toggleSize()">Toggle size</button>
+  `,
+})
+export class DynamicExample {
+  readonly saving = signal(true);
+  readonly iconSize = signal<IconSize>('sm');
+
+  toggleSize() {
+    this.iconSize.update((s) => (s === 'sm' ? 'lg' : 'sm'));
+  }
+}
+```
+
+## Accessibility notes
+
+- `ng-icon` renders decorative SVG — screen readers ignore it by default. When an icon is the _only_ content of a button/link, put the accessible name on the control (`aria-label="Search"`), not on the icon.
+- Never convey status by icon alone (e.g. a lone red `x` for errors); pair it with text or an `role="status"` message.
+- Icon buttons need a visible focus indicator and at least a 24px (ideally 44px) hit area — use the button size variants rather than shrinking the control to the glyph.
+
+## Theming / CSS variables
+
+Sizing flows through the `--ng-icon__size` CSS variable set by the directive; color inherits `currentColor`, so icons follow surrounding text/foreground tokens automatically. No component-specific theme variables.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/button` — icon buttons and icon+label composition.
+- `@egose/shadcn-theme-ng/input-group` — addon slots with `ng-icon` styling hooks.
+- `@egose/shadcn-theme-ng/badge` — common icon+text pill composition.
+- `@egose/shadcn-theme-ng/spinner` — animated loading indicator alternative.

package/input/README.md

@@ -1,3 +1,270 @@
-# Input Subpath
+# Input (`@egose/shadcn-theme-ng/input`)
 
-This project ships only as `@egose/shadcn-theme-ng/input` or `@egose/shadcn-theme-ng-tw/input`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+`HlmInput` is a thin styling directive that gives any native `<input>` (or `<textarea>`) the shadcn/ui _Input_ look — the Angular counterpart of shadcn/ui's `<Input />`. Behavior comes from spartan-ng's `BrnInput` (plus field `aria-describedby` propagation); this directive adds the theme classes, `data-slot="input"`, invalid-state rings, and disabled/file styles.
+
+> **Ships as:** `@egose/shadcn-theme-ng/input` (plain Tailwind) and `@egose/shadcn-theme-ng-tw/input` (`tw:`-prefixed variant). See the [package README](../../README.md) for installation, peer dependencies, and the Tailwind-variant contract. Do not publish this project directory independently.
+
+## Installation
+
+```bash
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies (Angular, `@angular/forms`, CDK, `@spartan-ng/brain`, `rxjs`) are documented in the [package README](../../README.md#peer-dependencies).
+
+```ts
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+// tw variant:
+// import { HlmInputImports } from '@egose/shadcn-theme-ng-tw/input';
+```
+
+## Imports
+
+```ts
+// Standalone component — spread the imports array:
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInputImports],
+  template: `<input hlmInput formControlName="email" type="email" />`,
+})
+export class MyComp {}
+```
+
+```ts
+// NgModule-based — import the module:
+import { HlmInputModule } from '@egose/shadcn-theme-ng/input';
+
+@NgModule({ imports: [HlmInputModule] })
+export class MyModule {}
+```
+
+Exported from `src/public-api.ts`: `HlmInput`, plus `HlmInputImports` and `HlmInputModule`. Import the directive class directly (`import { HlmInput } from '…'`) when you only need the one symbol.
+
+## Anatomy / Structure
+
+```html
+<label for="email">Email</label> <input hlmInput id="email" type="email" placeholder="you@example.com" />
+```
+
+The directive matches `input[hlmInput]` usage in practice (selector `[hlmInput]`), sets `data-slot="input"`, binds `[attr.aria-describedby]` from its own input, and composes `BrnInput` (`id`, `forceInvalid`) + `BrnFieldControlDescribedBy` via `hostDirectives`. It is also the class hook reused by `textarea[hlmInput]` (see `form-textarea`) and by `input[hlmInputGroupInput]`.
+
+## API reference
+
+### `[hlmInput]` — `HlmInput`
+
+| Input             | Type             | Default | Description                                                                                                         |
+| ----------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `ariaDescribedby` | `string \| null` | `null`  | Bound to `aria-describedby`. Combine with `<hlm-error>`/`<hlm-hint>` ids (the form wrappers do this automatically). |
+| `id`              | (via `BrnInput`) | —       | Forwarded to the `BrnInput` host directive.                                                                         |
+| `forceInvalid`    | (via `BrnInput`) | —       | Forwarded to the `BrnInput` host directive; forces the `data-matches-spartan-invalid` error styles.                 |
+
+No outputs. Visual states are attribute-driven: `data-matches-spartan-invalid=true` switches the border/ring to destructive; `disabled` applies `pointer-events-none`, `cursor-not-allowed`, `opacity-50`. Base geometry: `h-9`, `rounded-md`, `text-base` (`md:text-sm`), full width.
+
+## Examples
+
+### 1. Basic text + reactive form
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInputImports],
+  template: `
+    <form [formGroup]="form">
+      <label for="username">Username</label>
+      <input hlmInput id="username" formControlName="username" placeholder="jane_doe" />
+    </form>
+  `,
+})
+export class BasicExample {
+  readonly form = new FormGroup({
+    username: new FormControl<string>('', { nonNullable: true }),
+  });
+}
+```
+
+### 2. Template-driven with `ngModel`
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [FormsModule, HlmInput],
+  template: `
+    <label for="nickname">Nickname</label>
+    <input hlmInput id="nickname" name="nickname" [(ngModel)]="nickname" placeholder="janey" />
+    <p>Hello, {{ nickname || 'stranger' }}!</p>
+  `,
+})
+export class NgModelExample {
+  nickname = '';
+}
+```
+
+### 3. Types: email, password, number, search, file
+
+```ts
+import { Component } from '@angular/core';
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [HlmInputImports],
+  template: `
+    <div class="tw:grid tw:gap-3">
+      <input hlmInput type="email" placeholder="Email" aria-label="Email" autocomplete="email" />
+      <input hlmInput type="password" placeholder="Password" aria-label="Password" autocomplete="current-password" />
+      <input hlmInput type="number" placeholder="0" aria-label="Amount" min="0" />
+      <input hlmInput type="search" placeholder="Search…" aria-label="Search" />
+      <input hlmInput type="file" aria-label="Upload avatar" />
+    </div>
+  `,
+})
+export class TypesExample {}
+```
+
+> File inputs inherit the directive's `file:` styles (sized button text, transparent track) — no extra markup needed.
+
+### 4. Disabled + invalid states
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInput],
+  template: `
+    <form [formGroup]="form">
+      <input hlmInput formControlName="email" type="email" placeholder="you@example.com" aria-label="Email" />
+      @if (form.controls.email.invalid && form.controls.email.touched) {
+        <p class="tw:text-sm tw:text-red-600">Enter a valid email.</p>
+      }
+      <input hlmInput placeholder="Disabled field" aria-label="Disabled field" [disabled]="true" />
+      <!-- force the error ring regardless of touch state -->
+      <input hlmInput placeholder="Forced invalid" aria-label="Forced invalid" [forceInvalid]="true" />
+    </form>
+  `,
+})
+export class StatesExample {
+  readonly form = new FormGroup({
+    email: new FormControl<string>('', { nonNullable: true, validators: [Validators.email] }),
+  });
+}
+```
+
+### 5. Manual `aria-describedby` with hint + error (no form wrapper)
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmError, HlmHint } from '@egose/shadcn-theme-ng/form-field';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInput, HlmError, HlmHint],
+  template: `
+    <form [formGroup]="form">
+      <label for="handle">Handle</label>
+      <input
+        hlmInput
+        id="handle"
+        formControlName="handle"
+        placeholder="@jane"
+        [ariaDescribedby]="describedBy()"
+      />
+      @if (showError()) {
+        <hlm-error id="handle-error">Use 3+ lowercase letters.</hlm-error>
+      } @else {
+        <hlm-hint id="handle-hint">Your public @name.</hlm-hint>
+      }
+    </form>
+  `,
+})
+export class DescribedByExample {
+  readonly form = new FormGroup({
+    handle: new FormControl<string>('', {
+      nonNullable: true,
+      validators: [Validators.minLength(3), Validators.pattern(/^[a-z]+$/)],
+    }),
+  });
+
+  showError(): boolean {
+    const c = this.form.controls.handle;
+    return c.invalid && (c.dirty || c.touched);
+  }
+
+  describedBy(): string {
+    return this.showError() ? 'handle-error' : 'handle-hint';
+  }
+}
+```
+
+### 6. Composition: search row with button (input + button)
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  standalone: true,
+  imports: [HlmInput, HlmButton],
+  template: `
+    <div class="tw:flex tw:gap-2">
+      <input
+        hlmInput
+        aria-label="Search docs"
+        placeholder="Search docs…"
+        [value]="query()"
+        (input)="query.set($any($event.target).value)"
+        (keydown.enter)="search()"
+      />
+      <button hlmBtn type="button" (click)="search()">Search</button>
+    </div>
+    @if (searched()) {
+      <p role="status" class="tw:text-sm">Searching for “{{ query() }}”…</p>
+    }
+  `,
+})
+export class SearchRowExample {
+  readonly query = signal('');
+  readonly searched = signal(false);
+
+  search() {
+    this.searched.set(true);
+  }
+}
+```
+
+## Accessibility notes
+
+- Always pair the input with a `<label for>` (or `aria-label`/`aria-labelledby` when the design is label-less). The directive does not generate labels.
+- Wire `ariaDescribedby` to hint/error ids so screen readers announce help and validation together with the field. The `eg-form-*` wrappers automate this — copy their pattern when hand-rolling.
+- Invalid styling is visual only until you expose the message text (e.g. `<hlm-error>` or `role="alert"`); use `forceInvalid` sparingly and only alongside a message.
+- Keep native semantics: correct `type`, `autocomplete`, `required`, and `disabled` (not `aria-disabled` + click-guard) so AT and password managers behave.
+
+## Theming / CSS variables
+
+No component-specific CSS variables; colors/spacing come from the shared theme tokens (`--input`, `--ring`, `--destructive`, `--radius`, …). Taller fields: add `tw:h-11`; monospace/code looks: add `tw:font-mono`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/form-text-input` — labeled + validated reactive-forms wrapper (prefer for forms).
+- `@egose/shadcn-theme-ng/form-textarea` — multiline sibling reusing the same class hook.
+- `@egose/shadcn-theme-ng/input-group` — joined prefix/input/suffix compositions.
+- `@egose/shadcn-theme-ng/label` — `HlmLabel` for the `<label>` side.