@edsis/ui 0.0.2

package/hover-card/README.md

@@ -0,0 +1,146 @@
+# Hover Card
+
+Preview additional context on hover or keyboard focus without forcing a full click-to-open interaction.
+
+The Angular hover card follows the shadcn composition model with a root container for shared defaults, a trigger directive on the interactive host, and a template-backed content surface rendered through the CDK overlay.
+
+## Import
+
+```ts
+import {
+  HoverCardComponent,
+  HoverCardContentDirective,
+  HoverCardTriggerDirective,
+} from '@your-scope/angular/component/hover-card';
+import { ButtonComponent } from '@your-scope/angular/component/button';
+```
+
+## Composition
+
+```text
+ui-hover-card
+├── [uiHoverCardTrigger]
+└── ng-template[uiHoverCardContent]
+```
+
+## Basic usage
+
+```html
+<ui-hover-card [openDelay]="100" [closeDelay]="150">
+  <button ui-button variant="link" [uiHoverCardTrigger]="profileCard">@nextjs</button>
+
+  <ng-template uiHoverCardContent #profileCard="uiHoverCardContent">
+    <div
+      class="flex w-72 flex-col gap-1 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md">
+      <div class="font-semibold">@nextjs</div>
+      <p class="text-sm text-muted-foreground">The React Framework - created and maintained by @vercel.</p>
+      <p class="text-xs text-muted-foreground">Joined December 2021</p>
+    </div>
+  </ng-template>
+</ui-hover-card>
+```
+
+## Common patterns
+
+### Trigger delays
+
+Use the root or trigger inputs to control when the preview opens and closes.
+
+```html
+<ui-hover-card [openDelay]="150" [closeDelay]="200">
+  <a href="/profiles/vercel" [uiHoverCardTrigger]="card">Hover profile</a>
+  <ng-template uiHoverCardContent #card="uiHoverCardContent">...</ng-template>
+</ui-hover-card>
+```
+
+### Positioning
+
+Set `side`, `align`, and `sideOffset` on the root for shared defaults or override them on an individual trigger.
+
+```html
+<ui-hover-card side="top" align="start" [sideOffset]="12">
+  <button ui-button variant="outline" [uiHoverCardTrigger]="card">Top start</button>
+  <ng-template uiHoverCardContent #card="uiHoverCardContent">...</ng-template>
+</ui-hover-card>
+```
+
+### Interactive content
+
+The overlay remains open while either the trigger or the rendered content is hovered or focused, so links and buttons inside the card remain usable.
+
+```html
+<ui-hover-card>
+  <a href="/products/headphones" [uiHoverCardTrigger]="productCard">Wireless Headphones</a>
+  <ng-template uiHoverCardContent #productCard="uiHoverCardContent">
+    <div
+      class="flex w-64 flex-col gap-3 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md">
+      <div>
+        <div class="font-semibold">Wireless Headphones</div>
+        <p class="text-sm text-muted-foreground">Noise cancelling with 30-hour battery life.</p>
+      </div>
+      <a ui-button href="/products/headphones" size="sm">View product</a>
+    </div>
+  </ng-template>
+</ui-hover-card>
+```
+
+## API reference
+
+### `HoverCardComponent`
+
+| Input        | Type                                     | Default    |
+| ------------ | ---------------------------------------- | ---------- |
+| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` |
+| `align`      | `'start' \| 'center' \| 'end'`           | `'center'` |
+| `sideOffset` | `number`                                 | `8`        |
+| `openDelay`  | `number`                                 | `100`      |
+| `closeDelay` | `number`                                 | `100`      |
+
+### `HoverCardTriggerDirective` (`[uiHoverCardTrigger]`)
+
+| Input                | Type                                     | Default             |
+| -------------------- | ---------------------------------------- | ------------------- |
+| `uiHoverCardTrigger` | `HoverCardContentDirective`              | -                   |
+| `side`               | `'top' \| 'right' \| 'bottom' \| 'left'` | Inherited from root |
+| `align`              | `'start' \| 'center' \| 'end'`           | Inherited from root |
+| `sideOffset`         | `number`                                 | Inherited from root |
+| `openDelay`          | `number`                                 | Inherited from root |
+| `closeDelay`         | `number`                                 | Inherited from root |
+| `disabled`           | `boolean`                                | `false`             |
+
+Exposes `isOpen()` and `openedChange`. The host reflects `aria-expanded` and `aria-haspopup="dialog"`.
+
+### `HoverCardContentDirective`
+
+Use `ng-template[uiHoverCardContent]` with `exportAs="uiHoverCardContent"` to provide the overlay body.
+
+## Styling and theming
+
+The hover card does not force a panel shell. Apply width, border, background, radius, and elevation classes inside the projected template so the content can match compact profile cards, product previews, or custom dashboards.
+
+Use `border-border` for visible borders and `bg-popover text-popover-foreground` for the body shell to stay aligned with the theme tokens used across the library.
+
+## Accessibility
+
+- Open the card from a real interactive host such as `<button>`, `<a>`, or another focusable control.
+- The card opens on hover and keyboard focus, then remains available while the trigger or overlay content stays hovered or focused.
+- Press `Escape` while the trigger or overlay is focused to dismiss the preview.
+- Keep essential actions available outside the hover card as well; hover cards are best for supplemental context, not critical flows.
+
+## Keyboard interactions
+
+- `Tab` moves focus to the trigger and opens the card after the configured `openDelay`.
+- `Tab` continues into focusable content inside the overlay without forcing an immediate close.
+- `Shift+Tab` back to the trigger keeps the preview open.
+- `Escape` closes the preview.
+
+## Angular notes
+
+- The root `ui-hover-card` provides shared defaults. Override placement or timing on an individual trigger only when one example needs different behavior.
+- The content stays template-backed instead of adding a dedicated content component so the overlay body can remain fully custom.
+- Because the content renders through the CDK overlay container, set `dir` on the projected body when an individual card needs RTL behavior independent of the application shell.
+- If you need click-to-open behavior instead of hover and focus, use the Popover primitive instead.
+
+## Source parity
+
+This implementation preserves the shadcn structure, trigger delay inputs, side and alignment controls, and interactive hover path between trigger and content, while adapting the API to Angular selectors and CDK overlay primitives.

package/input/README.md

@@ -0,0 +1,159 @@
+# Input
+
+Text input for forms and user data entry with shadcn-style visual states and Angular-friendly composition.
+
+The input itself stays a native `<input>` element. When the current shadcn docs mention `Field`, `FieldLabel`, or
+`FieldDescription`, the local Angular mapping is the existing form primitives rather than a separate runtime `Form`
+component.
+
+## Import
+
+For the simplest standalone field:
+
+```ts
+import { InputComponent } from '@edsis/ui/input';
+import { LabelComponent } from '@edsis/ui/label';
+```
+
+For the richer field composition used throughout the shadcn Input docs:
+
+```ts
+import {
+  FormControlDirective,
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormLabelComponent,
+  FormMessageComponent,
+} from '@edsis/ui/form';
+import { InputComponent } from '@edsis/ui/input';
+```
+
+## Usage
+
+### Standalone input
+
+```html
+<label ui-label for="email">Email</label> <input id="email" ui-input type="email" placeholder="you@example.com" />
+```
+
+### Field mapping
+
+Use the local form primitives when you need the label, helper text, and invalid-state wiring shown in the upstream
+shadcn examples:
+
+```html
+<ui-form-field>
+  <ui-form-label>Email</ui-form-label>
+  <input ui-input uiFormControl type="email" placeholder="you@example.com" />
+  <ui-form-description>We'll only use this address for account updates.</ui-form-description>
+  <ui-form-message>Enter a valid email address.</ui-form-message>
+</ui-form-field>
+```
+
+## Common Patterns
+
+### Reactive forms
+
+`ui-input` keeps Angular's standard `DefaultValueAccessor`, so reactive forms and `formControlName` work without a
+wrapper component.
+
+```ts
+readonly profileForm = new FormGroup({
+  email: new FormControl('', {
+    nonNullable: true,
+    validators: [Validators.required, Validators.email],
+  }),
+});
+```
+
+```html
+<ui-form-field>
+  <ui-form-label>Email</ui-form-label>
+  <input ui-input uiFormControl formControlName="email" type="email" placeholder="john@example.com" />
+  <ui-form-description>We'll never share your email with anyone.</ui-form-description>
+  <ui-form-message>Enter a valid email address.</ui-form-message>
+</ui-form-field>
+```
+
+### Invalid state without Angular forms
+
+If the field participates in a validation flow outside Angular forms, forward `aria-invalid="true"` manually.
+
+```html
+<input ui-input aria-invalid="true" placeholder="Error" />
+```
+
+### File input
+
+The same directive styles file inputs while preserving the browser-native file picker.
+
+```html
+<ui-form-field>
+  <ui-form-label>Picture</ui-form-label>
+  <input ui-input uiFormControl type="file" />
+  <ui-form-description>Select a picture to upload.</ui-form-description>
+</ui-form-field>
+```
+
+### Inline actions
+
+For search bars or quick actions, compose the input with `ui-button` instead of inventing a synthetic group API.
+
+```html
+<div class="flex max-w-md items-center gap-2">
+  <input ui-input type="search" placeholder="Search..." class="flex-1" />
+  <button ui-button type="button">Search</button>
+</div>
+```
+
+## API Reference
+
+### `InputComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+All native `<input>` attributes such as `type`, `placeholder`, `required`, `disabled`, `autocomplete`, and `value`
+continue to work as usual.
+
+### Field Mapping
+
+- `Field` maps to `ui-form-field`.
+- `FieldLabel` maps to `ui-form-label`.
+- `FieldDescription` maps to `ui-form-description`.
+- Invalid and helper-text wiring come from `[uiFormControl]` plus `ui-form-message`.
+
+## Styling and Theming
+
+Theme tokens used by the input styles include `--border`, `--input`, `--foreground`, `--muted-foreground`, `--ring`,
+and `--destructive`.
+
+When `aria-invalid="true"` is present, the border and focus ring switch to the destructive treatment. Pass `class`
+for layout utilities such as width, flex growth, or spacing around the native control.
+
+## Accessibility
+
+- Pair every input with a visible label or another accessible name source.
+- Use `uiFormControl` inside `ui-form-field` when the control should auto-wire `id`, `aria-describedby`, and invalid
+  state.
+- Keep helper text and validation messages adjacent to the field so screen readers announce the full context.
+- Do not remove the focus ring; the component keeps a visible keyboard-only focus treatment.
+
+## Keyboard Interactions
+
+- The component preserves the browser-native keyboard behavior of the underlying input element.
+- File, search, email, password, and text variants continue to use the interactions defined by their native type.
+- Any adjacent action button, such as a search trigger, remains a separate Tab stop.
+
+## Angular Notes
+
+- `ui-input` is an attribute selector on the native `<input>` element.
+- It works with both `ngModel` and reactive forms because Angular still sees the underlying native control.
+- `uiFormControl` is optional; use it when the field participates in the local form-primitive composition.
+
+## Source Parity
+
+This Angular implementation follows the current shadcn Input information architecture while translating `Field` to the
+local form primitives. Upstream `Input Group` and `Button Group` examples are intentionally left to their own planned
+components instead of being faked inside the input API.

package/input-group/README.md

@@ -0,0 +1,234 @@
+# Input Group
+
+Grouped input primitives for prefixes, suffixes, stacked helper rows, and inline actions.
+
+Use Input Group when the field and its addon content should read as a single control boundary instead of separate neighboring elements.
+
+## Import
+
+```ts
+import { FormControlDirective, FormDescriptionComponent, FormFieldComponent, FormLabelComponent } from '@edsis/ui/form';
+import {
+  InputGroupAddonComponent,
+  InputGroupButtonComponent,
+  InputGroupComponent,
+  InputGroupInputComponent,
+  InputGroupTextComponent,
+  InputGroupTextareaComponent,
+} from '@edsis/ui/input-group';
+```
+
+## Usage
+
+Keep the input or textarea first in the DOM, then append one or more addons after it.
+Use the `align` input on `ui-input-group-addon` to place the addon at the inline or block edge.
+
+```html
+<ui-form-field>
+  <ui-form-label>Search</ui-form-label>
+  <ui-input-group>
+    <input ui-input-group-input uiFormControl placeholder="Search documentation..." />
+    <ui-input-group-addon>
+      <span aria-hidden="true">⌕</span>
+    </ui-input-group-addon>
+    <ui-input-group-addon align="inline-end">
+      <ui-input-group-text>12 results</ui-input-group-text>
+    </ui-input-group-addon>
+  </ui-input-group>
+  <ui-form-description
+    >Keep addons after the control in the DOM and use align for visual placement.</ui-form-description
+  >
+</ui-form-field>
+```
+
+## Composition
+
+```text
+ui-input-group
+├── input[ui-input-group-input] or textarea[ui-input-group-textarea]
+├── ui-input-group-addon
+│   ├── ui-input-group-text
+│   └── button[ui-input-group-button]
+└── ui-input-group-addon
+```
+
+## Common Patterns
+
+### Inline search
+
+```html
+<ui-input-group class="max-w-md">
+  <input ui-input-group-input placeholder="Search..." />
+  <ui-input-group-addon>
+    <span aria-hidden="true">⌕</span>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <ui-input-group-text>12 results</ui-input-group-text>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Text addons
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="0.00" />
+  <ui-input-group-addon>
+    <ui-input-group-text>$</ui-input-group-text>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <ui-input-group-text>USD</ui-input-group-text>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Textarea footer
+
+```html
+<ui-input-group>
+  <textarea ui-input-group-textarea placeholder="Write a comment..."></textarea>
+  <ui-input-group-addon align="block-end">
+    <ui-input-group-text>0/280</ui-input-group-text>
+    <button ui-input-group-button type="button" size="sm" variant="default" class="ml-auto">Post</button>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Custom control
+
+```html
+<ui-input-group>
+  <textarea
+    data-slot="input-group-control"
+    class="min-h-20 w-full resize-none bg-transparent px-3 py-2.5 text-sm outline-none placeholder:text-muted-foreground"
+    placeholder="Use any custom control that matches the group contract..."></textarea>
+  <ui-input-group-addon align="block-end">
+    <button ui-input-group-button type="button" variant="default" size="sm" class="ml-auto">Submit</button>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Keyboard shortcut badge
+
+```html
+<ui-input-group class="max-w-sm">
+  <input ui-input-group-input placeholder="Search..." />
+  <ui-input-group-addon>
+    <span aria-hidden="true">⌕</span>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <span
+      aria-hidden="true"
+      class="inline-flex h-6 items-center rounded-md border border-border bg-background px-2 font-mono text-[11px] font-medium text-foreground shadow-sm">
+      ⌘K
+    </span>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Dropdown composition
+
+Use the local menu primitives when the grouped field needs scoped actions or search destinations.
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="Enter file name" />
+  <ui-input-group-addon align="inline-end">
+    <button
+      ui-input-group-button
+      type="button"
+      size="icon-xs"
+      aria-label="Open file actions"
+      [uiMenuTrigger]="fileActionsMenu">
+      ⋯
+    </button>
+  </ui-input-group-addon>
+</ui-input-group>
+
+<ng-template uiMenuContent #fileActionsMenu="uiMenuContent">
+  <ui-menu-surface>
+    <ui-menu-label>File actions</ui-menu-label>
+    <button ui-menu-item type="button">Settings</button>
+    <button ui-menu-item type="button">Copy path</button>
+    <ui-menu-separator />
+    <button ui-menu-item type="button">Open location</button>
+  </ui-menu-surface>
+</ng-template>
+```
+
+### Spinner status row
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="Saving changes..." />
+  <ui-input-group-addon align="inline-end">
+    <ui-input-group-text>Saving...</ui-input-group-text>
+    <span
+      aria-hidden="true"
+      class="inline-flex size-4 animate-spin rounded-full border-2 border-muted border-t-foreground"></span>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+## API Reference
+
+### `InputGroupComponent`
+
+| Input   | Type     | Default      |
+| ------- | -------- | ------------ |
+| `class` | `string` | empty string |
+
+### `InputGroupAddonComponent`
+
+| Input   | Type                                                          | Default          |
+| ------- | ------------------------------------------------------------- | ---------------- |
+| `align` | `'inline-start', 'inline-end', 'block-start', or 'block-end'` | `'inline-start'` |
+| `class` | `string`                                                      | empty string     |
+
+### `InputGroupButtonComponent`
+
+| Input     | Type                                  | Default      |
+| --------- | ------------------------------------- | ------------ |
+| `variant` | `ButtonVariant`                       | `'ghost'`    |
+| `size`    | `'xs', 'icon-xs', 'sm', or 'icon-sm'` | `'xs'`       |
+| `class`   | `string`                              | empty string |
+
+### `InputGroupInputComponent` and `InputGroupTextareaComponent`
+
+| Input   | Type     | Default      |
+| ------- | -------- | ------------ |
+| `class` | `string` | empty string |
+
+All other native input and textarea attributes pass through unchanged.
+
+## Styling And Theming
+
+- `ui-input-group` owns the shared border, focus ring, radius, and background surface.
+- `ui-input-group-addon` uses logical separators so start and end alignments still read correctly in RTL layouts.
+- Override `--radius` on the group root when the grouped field should be sharper or more pill-shaped.
+- Add spacing or typography utilities through `class` on any primitive without breaking the core layout contract.
+
+## Accessibility
+
+- Keep the input or textarea before addons in the DOM so tab order and assistive reading order stay predictable.
+- Provide a visible label with `ui-form-label`, `ui-label`, or another accessible name source.
+- Give icon-only `ui-input-group-button` elements an `aria-label`.
+- Use `uiFormControl` inside `ui-form-field` when labels, descriptions, and invalid messaging should auto-wire to the grouped control.
+
+## Keyboard Interactions
+
+- Text input and textarea editing remain native.
+- Buttons inside addons participate in the normal tab sequence after the text control.
+- Changing `align` only affects visual placement; it does not change keyboard order.
+
+## Angular Notes
+
+- `ui-input-group-input` and `ui-input-group-textarea` are attribute selectors on native controls, so native input and textarea behavior remains intact.
+- For custom controls, set `data-slot="input-group-control"` and provide your own spacing utilities so the wrapper can still coordinate focus and addon layout.
+- Upstream shadcn `Field` examples map to the local `ui-form-field`, `ui-form-label`, and `ui-form-description` primitives rather than a separate `field` runtime component.
+
+## Source Parity
+
+This Angular implementation covers the core shadcn Input Group primitives, all four addon alignments, textarea support, custom control guidance, and RTL composition.
+
+Keyboard shortcut badges, dropdown triggers, and spinner/status rows are composed from the same primitives plus the local menu surface and inline status markup instead of requiring input-group-specific wrappers.