@edsis/ui 0.0.2

package/button/README.md

@@ -0,0 +1,139 @@
+# Button
+
+Displays a native button or anchor that looks like a shadcn-style button, translated to Angular attribute selectors and standalone imports.
+
+Use Button for primary actions, secondary actions, icon-only controls, and semantic links that should share the same visual language.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@edsis/ui/button';
+```
+
+## Usage
+
+```html
+<button ui-button type="button" variant="default">Save</button>
+<button ui-button variant="outline" size="sm">Cancel</button>
+<a ui-button variant="link" href="/learn-more">Learn more</a>
+```
+
+Choose the correct native host for the job: `<button>` for actions and `<a>` for navigation.
+
+## Common patterns
+
+### Variants
+
+Use `variant` for emphasis: `default`, `secondary`, `destructive`, `outline`, `ghost`, or `link`.
+
+```html
+<button ui-button variant="default">Save</button>
+<button ui-button variant="secondary">Duplicate</button>
+<button ui-button variant="destructive">Delete</button>
+<button ui-button variant="outline">Outline</button>
+<button ui-button variant="ghost">Ghost</button>
+<a ui-button variant="link" href="/learn-more">Learn more</a>
+```
+
+### Sizes
+
+Use `size` for compact or icon-only controls: `xs`, `sm`, `default`, `lg`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`.
+
+```html
+<button ui-button size="xs" variant="outline">Extra small</button>
+<button ui-button size="sm" variant="outline">Small</button>
+<button ui-button size="default" variant="outline">Default</button>
+<button ui-button size="lg" variant="outline">Large</button>
+<button ui-button size="icon-xs" variant="outline" aria-label="Extra small icon button">+</button>
+<button ui-button size="icon-sm" variant="outline" aria-label="Small icon button">+</button>
+<button ui-button size="icon" variant="outline" aria-label="Default icon button">+</button>
+<button ui-button size="icon-lg" variant="outline" aria-label="Large icon button">+</button>
+```
+
+### Rounded buttons
+
+Pass `class="rounded-full"` when you want a pill or circular button without changing the base API.
+
+```html
+<button ui-button variant="outline" class="rounded-full px-5">Invite teammate</button>
+<button ui-button variant="outline" size="icon" class="rounded-full" aria-label="Scroll to top">
+  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+    <path d="m12 19 0-14" />
+    <path d="m5 12 7-7 7 7" />
+  </svg>
+</button>
+```
+
+### Loading and disabled states
+
+Project a spinner element into the button and set `disabled` while async work is pending.
+
+```html
+<button ui-button variant="outline" disabled>
+  <span
+    aria-hidden="true"
+    class="inline-block h-3.5 w-3.5 animate-spin rounded-full border-2 border-current border-t-transparent"></span>
+  Generating
+</button>
+```
+
+### Semantic host mapping
+
+React's `asChild` pattern maps to choosing the right native host directly in Angular templates.
+
+```html
+<button ui-button type="button">Save changes</button> <a ui-button href="/account" variant="link">Go to account</a>
+```
+
+## API reference
+
+| Input     | Type                                                                                 | Default     |
+| --------- | ------------------------------------------------------------------------------------ | ----------- |
+| `variant` | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'ghost' \| 'link'`        | `'default'` |
+| `size`    | `'xs' \| 'sm' \| 'default' \| 'lg' \| 'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'default'` |
+| `class`   | `string`                                                                             | `''`        |
+
+The selected variant + size are also exposed via `data-variant` / `data-size`
+attributes on the host for styling overrides.
+
+Hosts: `button[ui-button]` and `a[ui-button]`.
+
+Re-exports: `buttonVariants`, `ButtonVariant`, `ButtonSize`.
+
+## Styling and theming
+
+Tokens: `--primary`, `--primary-foreground`, `--secondary`, `--destructive`,
+`--border`, `--accent`, `--ring`.
+
+Every state (hover, focus-visible, active, disabled) is covered by the variants.
+Focus-visible uses a 2px `ring-ring` outline for keyboard users.
+
+Pass `class` to layer width, shape, and spacing overrides such as `rounded-full`, `w-full`, or responsive layout utilities.
+
+The local primitive already opts into `cursor-pointer` for interactive hosts, so you do not need an extra Tailwind base-layer override to restore button cursors.
+
+## Accessibility
+
+Attribute selectors force you to pick a real semantic element:
+
+- Use `<button ui-button>` for actions that don't navigate.
+- Use `<a ui-button href="…">` for navigation.
+- Add an `aria-label` to icon-only buttons.
+- Use `type="button"` inside forms unless the button should submit.
+
+Avoid faking buttons with `<div>` — keyboard and screen-reader support depend on
+the native element.
+
+## Keyboard interactions
+
+- Native buttons support Tab, Enter, and Space automatically.
+- Anchors with `href` participate in normal link focus and Enter activation.
+
+## Angular notes
+
+- Import `ButtonComponent` into the standalone component that renders the host element.
+- There is no Angular `asChild` input; pick the semantic host element directly.
+
+## Source parity
+
+This Angular version follows the shadcn Button information architecture while translating examples to native hosts, standalone imports, and Angular-friendly template patterns.

package/button-group/README.md

@@ -0,0 +1,204 @@
+# Button Group
+
+Groups related action buttons, text pills, inputs, and nested control clusters into a single visual control boundary.
+
+Use Button Group for toolbars, split actions, search bars, and compact action clusters where neighboring controls should read as one control family rather than isolated buttons.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@edsis/ui/button';
+import { ButtonGroupComponent, ButtonGroupSeparatorComponent, ButtonGroupTextComponent } from '@edsis/ui/button-group';
+import { InputComponent } from '@edsis/ui/input';
+import {
+  InputGroupAddonComponent,
+  InputGroupComponent,
+  InputGroupInputComponent,
+  InputGroupTextComponent,
+} from '@edsis/ui/input-group';
+```
+
+## Composition
+
+The Angular structure mirrors the shadcn composition while translating `asChild` to normal Angular content projection.
+
+```text
+ui-button-group
+├── button[ui-button] or a[ui-button]
+├── input[ui-input] or textarea[ui-textarea]
+├── ui-button-group-text
+├── ui-button-group-separator
+└── ui-button-group
+```
+
+## Basic usage
+
+Label the group with `aria-label` or `aria-labelledby` whenever the buttons act as a single tool cluster.
+
+```html
+<ui-button-group aria-label="Search actions" class="w-full max-w-md">
+  <input ui-input placeholder="Search..." />
+  <button ui-button type="button" variant="outline" aria-label="Run search">Search</button>
+</ui-button-group>
+```
+
+## Common patterns
+
+### Orientation
+
+Use `orientation="vertical"` when the group should stack actions instead of lining them up horizontally.
+
+```html
+<ui-button-group orientation="vertical" aria-label="Zoom controls" class="h-fit">
+  <button ui-button type="button" variant="outline" size="icon">+</button>
+  <button ui-button type="button" variant="outline" size="icon">-</button>
+</ui-button-group>
+```
+
+### Text and field pairing
+
+`ui-button-group-text` is the Angular translation of shadcn's `ButtonGroupText`. Project any semantic content inside it, including a native label.
+
+```html
+<ui-button-group class="w-full max-w-lg">
+  <ui-button-group-text>
+    <label for="project-name">Project</label>
+  </ui-button-group-text>
+  <input ui-input id="project-name" placeholder="Type a name..." />
+</ui-button-group>
+```
+
+### Separator
+
+Use `ui-button-group-separator` when filled or secondary buttons still need a visible division.
+
+```html
+<ui-button-group aria-label="Clipboard actions">
+  <button ui-button type="button" variant="secondary" size="sm">Copy</button>
+  <ui-button-group-separator />
+  <button ui-button type="button" variant="secondary" size="sm">Paste</button>
+</ui-button-group>
+```
+
+### Split action
+
+Split buttons are just two neighboring buttons with a separator between the primary action and the disclosure or icon action.
+
+```html
+<ui-button-group aria-label="Create actions">
+  <button ui-button type="button" variant="secondary">Create</button>
+  <ui-button-group-separator />
+  <button ui-button type="button" variant="secondary" size="icon" aria-label="Open create menu">+</button>
+</ui-button-group>
+```
+
+### Search input
+
+Button Group works directly with the local `ui-input` primitive because both controls own their border on the host element.
+
+```html
+<ui-button-group aria-label="Repository search" class="w-full max-w-lg">
+  <input ui-input placeholder="Search repositories..." />
+  <button ui-button type="button" variant="outline" aria-label="Search">Search</button>
+</ui-button-group>
+```
+
+### Nested groups
+
+Nest `ui-button-group` when you want separate clusters with spacing between them while keeping each inner cluster visually fused.
+
+```html
+<ui-button-group aria-label="Message composer" class="w-full max-w-xl">
+  <ui-button-group>
+    <button ui-button type="button" variant="outline" size="icon" aria-label="Add attachment">+</button>
+  </ui-button-group>
+
+  <ui-button-group class="min-w-0 flex-1">
+    <ui-input-group>
+      <input ui-input-group-input placeholder="Send a message..." />
+      <ui-input-group-addon align="inline-end">
+        <ui-input-group-text>⌘↵</ui-input-group-text>
+      </ui-input-group-addon>
+    </ui-input-group>
+  </ui-button-group>
+</ui-button-group>
+```
+
+### Popover companion
+
+Use a neighboring popover trigger when the primary button opens a short follow-up form or assistant prompt.
+
+```html
+<ui-button-group aria-label="Copilot actions">
+  <button ui-button type="button" variant="outline">Copilot</button>
+  <button ui-button type="button" variant="outline" size="icon" aria-label="Open Copilot options">⋯</button>
+</ui-button-group>
+```
+
+## API reference
+
+### `ButtonGroupComponent`
+
+| Input         | Type                         | Default        |
+| ------------- | ---------------------------- | -------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `class`       | `string`                     | `''`           |
+
+Host behavior:
+
+- Renders `role="group"`.
+- Adds `data-orientation` and `data-slot="button-group"`.
+- Collapses adjoining corner radius and internal border width with RTL-safe logical properties.
+
+### `ButtonGroupSeparatorComponent`
+
+| Input         | Type                         | Default      |
+| ------------- | ---------------------------- | ------------ |
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` |
+| `class`       | `string`                     | `''`         |
+
+### `ButtonGroupTextComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+Angular mapping note: there is no `asChild` input. Project the semantic element you need, such as `<label>` or `<span>`, inside `ui-button-group-text`.
+
+## Styling and theming
+
+- The root collapses adjacent corners and borders with logical start/end utilities so the same component works in LTR and RTL layouts.
+- Nested `ui-button-group` children automatically create spacing between groups while preserving the fused inner boundaries of each nested group.
+- `ui-button-group-text` uses `border-border`, `bg-muted`, and shared radius tokens so it matches the rest of the component package.
+- `ui-input` and `ui-input-group` compose cleanly inside Button Group because their border and radius live on the visible host. The current Material-backed `ui-select` does not expose the same host-level border contract yet, so the upstream Select example is intentionally not shipped as a parity demo.
+
+## Accessibility
+
+- `ui-button-group` renders with `role="group"`; provide an accessible name with `aria-label` or `aria-labelledby` when the controls act as one tool cluster.
+- Button Group is for actions. If the clustered controls represent pressed or selected state, use a toggle-group style pattern instead.
+- Add `aria-label` to icon-only buttons inside the group.
+- `ui-button-group-text` is non-interactive content. Keep labels, helper text, or status copy inside it and leave action handling to the actual button or input controls.
+
+## Keyboard interactions
+
+- Tab order follows the DOM order of the projected controls.
+- Native buttons keep their built-in Enter and Space activation behavior.
+- Inputs and textareas keep their native editing behavior.
+- Popover and menu triggers inside a group keep the keyboard behavior of their own directives; the group container does not intercept those interactions.
+
+## Button Group vs Toggle Group
+
+- Use Button Group when each item performs an immediate action.
+- Use Toggle Group when each item represents persistent pressed, selected, or filter state.
+
+## Angular notes
+
+- Import `ButtonGroupComponent` plus only the child primitives you render on the page.
+- There is no React-style `asChild` prop. Angular templates already let you choose the semantic element directly.
+- Use nested `ui-button-group` elements for spacing between related clusters rather than adding gap utilities to a single fused group.
+
+## Source parity
+
+This Angular implementation follows the shadcn Button Group surface with a grouped root, text pill, separator, nested-group spacing, dropdown and popover composition, and RTL-friendly border collapsing.
+
+The main documented deviation is the upstream Select example: the local `ui-select` remains Material-backed, so it is better composed next to the group in surrounding layout for now instead of being presented as a fused host-level group item.

package/calendar/README.md

@@ -0,0 +1,132 @@
+# Calendar
+
+Inline single-date calendar built on Angular Material `MatCalendar` and wrapped with shadcn-style theme tokens.
+
+Use Calendar when the date grid should stay visible in the page. Use `DatePickerComponent` when the same selection should live behind an input and popover trigger.
+
+## Import
+
+```ts
+import { CalendarComponent } from '@edsis/ui/calendar';
+```
+
+## Requires a date adapter
+
+The consumer app must provide an Angular Material date adapter. The demo app uses the native adapter:
+
+```ts
+// app.config.ts
+import { provideNativeDateAdapter } from '@angular/material/core';
+
+export const appConfig = {
+  providers: [provideNativeDateAdapter()],
+};
+```
+
+## Usage
+
+Bind `[(value)]` to a `Date | null` signal or component field. Use `startAt` when the first visible month should differ from the selected value.
+
+```html
+<ui-calendar [(value)]="selectedDate" [startAt]="selectedDate()" />
+```
+
+```ts
+protected readonly selectedDate = signal<Date | null>(new Date(2026, 4, 22));
+```
+
+## Common patterns
+
+### Constrained range
+
+Use `min` and `max` to disable dates outside an allowed window.
+
+```html
+<ui-calendar [(value)]="billingDate" [min]="minDate" [max]="maxDate" [startAt]="billingDate()" />
+```
+
+```ts
+protected readonly billingDate = signal<Date | null>(new Date(2026, 4, 15));
+protected readonly minDate = new Date(2026, 4, 5);
+protected readonly maxDate = new Date(2026, 4, 25);
+```
+
+### Disabled or booked dates
+
+Pass a `dateFilter` function. Angular Material expects the function to return `true` for selectable dates and `false` for disabled dates.
+
+```html
+<ui-calendar [(value)]="visitDate" [dateFilter]="availableDateFilter" [startAt]="visitDate()" />
+```
+
+```ts
+protected readonly bookedDates = [new Date(2026, 1, 12), new Date(2026, 1, 13)];
+
+protected readonly availableDateFilter = (candidate: Date | null): boolean =>
+  !!candidate && !this.bookedDates.some((bookedDate) => this.isSameDay(bookedDate, candidate));
+```
+
+### Presets
+
+Compose preset buttons around the calendar and update the same `value` model.
+
+```html
+<ui-calendar [(value)]="presetDate" [startAt]="presetDate()" class="border-0" />
+
+<button ui-button type="button" variant="outline" size="sm" (click)="selectPreset(7)">In a week</button>
+```
+
+### Date and time
+
+Calendar owns the date. Native time inputs or `InputGroupComponent` can own the time value next to it.
+
+```html
+<ui-calendar [(value)]="meetingDate" [startAt]="meetingDate()" />
+
+<ui-input-group>
+  <input ui-input-group-input type="time" [value]="startTime()" (input)="updateStartTime($event)" />
+</ui-input-group>
+```
+
+## API reference
+
+| Input / Model | Type                                | Default   |
+| ------------- | ----------------------------------- | --------- |
+| `value`       | `Date \| null`                      | `null`    |
+| `min`         | `Date \| null`                      | `null`    |
+| `max`         | `Date \| null`                      | `null`    |
+| `startAt`     | `Date \| null`                      | `null`    |
+| `startView`   | `'month' \| 'year' \| 'multi-year'` | `'month'` |
+| `dateFilter`  | `(date: Date \| null) => boolean`   | `null`    |
+| `disabled`    | `boolean`                           | `false`   |
+| `class`       | `string`                            | `''`      |
+
+Implements `ControlValueAccessor` — usable with `[(ngModel)]` and reactive forms.
+
+## Styling and theming
+
+The host uses `--border`, `--background`, `--foreground`, and `--radius`. Pass `class` for layout utilities such as `shadow-sm`, `border-0`, or `[--ui-calendar-width:20rem]`.
+
+The inner Material calendar keeps Angular Material's a11y and navigation behavior while sitting inside the shadcn token wrapper. Use `DatePickerComponent` for popover input flows; this primitive intentionally stays inline.
+
+## Accessibility
+
+`MatCalendar` supplies the ARIA grid semantics, focus management, active date state, and disabled date handling. Provide a visible label or surrounding section heading when the calendar appears in a form-like surface.
+
+## Keyboard interactions
+
+- Arrow keys move between dates.
+- Page Up and Page Down move by month.
+- Home and End move to the start or end of the row.
+- Enter selects the focused date.
+
+## Angular notes
+
+- Provide a date adapter once at app bootstrap.
+- `dateFilter` returns `true` for enabled dates, unlike some predicate APIs that return `true` for blocked dates.
+- `disabled` marks the host as inert and updates the CVA disabled state.
+- This component is a single-date primitive. Range selection is best modeled as a separate range primitive or by composing two calendars with application state.
+
+## Source parity
+
+The shadcn Calendar is built on React DayPicker. This Angular implementation maps the same inline calendar concept to `MatCalendar`, standalone imports, signal-friendly `[(value)]` binding, `min` and `max` constraints, `dateFilter` disabled dates, preset composition, and RTL-friendly container usage.