@edsis/ui 0.0.2

package/tabs/README.md

@@ -0,0 +1,214 @@
+# Tabs
+
+A set of layered sections of content, known as tab panels, that are displayed one at a time.
+
+Use Tabs for compact settings surfaces, dashboards, account forms, and any view where related panels should share the same page location.
+
+## Import
+
+```ts
+import { TabsComponent, TabsContentComponent, TabsListComponent, TabsTriggerComponent } from '@edsis/ui/tabs';
+```
+
+## Composition
+
+The Angular structure mirrors shadcn and Radix while using Angular selectors and native button triggers.
+
+```text
+ui-tabs
+├── ui-tabs-list
+│   ├── button[ui-tabs-trigger]
+│   └── button[ui-tabs-trigger]
+├── ui-tabs-content
+└── ui-tabs-content
+```
+
+## Basic usage
+
+Pair every trigger value with a matching panel value. Bind `[(value)]` when the parent should seed the active tab or observe changes.
+
+```ts
+const activeTab = signal<string | null>('account');
+```
+
+```html
+<ui-tabs [(value)]="activeTab" class="w-full max-w-md">
+  <ui-tabs-list>
+    <button ui-tabs-trigger value="account">Account</button>
+    <button ui-tabs-trigger value="password">Password</button>
+  </ui-tabs-list>
+
+  <ui-tabs-content value="account">Make changes to your account here.</ui-tabs-content>
+  <ui-tabs-content value="password">Change your password here.</ui-tabs-content>
+</ui-tabs>
+```
+
+## Common patterns
+
+### Line variant
+
+Use `variant="line"` on `ui-tabs-list` for the underline treatment from the shadcn examples.
+
+```ts
+const lineTab = signal<string | null>('overview');
+```
+
+```html
+<ui-tabs [(value)]="lineTab">
+  <ui-tabs-list variant="line">
+    <button ui-tabs-trigger value="overview">Overview</button>
+    <button ui-tabs-trigger value="analytics">Analytics</button>
+    <button ui-tabs-trigger value="reports">Reports</button>
+  </ui-tabs-list>
+
+  <ui-tabs-content value="overview">Overview metrics are selected.</ui-tabs-content>
+  <ui-tabs-content value="analytics">Analytics metrics are selected.</ui-tabs-content>
+  <ui-tabs-content value="reports">Reports metrics are selected.</ui-tabs-content>
+</ui-tabs>
+```
+
+### Vertical orientation
+
+Set `orientation="vertical"` on `ui-tabs` when triggers should stack beside the active panel.
+
+```ts
+const verticalTab = signal<string | null>('account');
+```
+
+```html
+<ui-tabs [(value)]="verticalTab" orientation="vertical" class="w-full max-w-2xl">
+  <ui-tabs-list class="min-w-40">
+    <button ui-tabs-trigger value="account">Account</button>
+    <button ui-tabs-trigger value="password">Password</button>
+    <button ui-tabs-trigger value="notifications">Notifications</button>
+  </ui-tabs-list>
+
+  <ui-tabs-content value="account" class="mt-0 flex-1 rounded-lg border border-border p-4">
+    Account preferences and details live in this panel.
+  </ui-tabs-content>
+</ui-tabs>
+```
+
+### Disabled triggers
+
+Disable a trigger with `[disabled]="true"`. Disabled triggers remain visible, expose disabled state, and are skipped by arrow-key navigation.
+
+```ts
+const disabledTab = signal<string | null>('home');
+```
+
+```html
+<ui-tabs [(value)]="disabledTab">
+  <ui-tabs-list>
+    <button ui-tabs-trigger value="home">Home</button>
+    <button ui-tabs-trigger value="settings" [disabled]="true">Disabled</button>
+  </ui-tabs-list>
+
+  <ui-tabs-content value="home">Home content stays reachable.</ui-tabs-content>
+  <ui-tabs-content value="settings">Settings is intentionally unavailable.</ui-tabs-content>
+</ui-tabs>
+```
+
+### Icons
+
+Project icon components or inline SVG before trigger text. The trigger includes icon and label spacing.
+
+```html
+<ui-tabs value="preview">
+  <ui-tabs-list>
+    <button ui-tabs-trigger value="preview">
+      <svg aria-hidden="true" class="size-4" viewBox="0 0 24 24">...</svg>
+      Preview
+    </button>
+    <button ui-tabs-trigger value="code">
+      <svg aria-hidden="true" class="size-4" viewBox="0 0 24 24">...</svg>
+      Code
+    </button>
+  </ui-tabs-list>
+
+  <ui-tabs-content value="preview">Rendered preview is selected.</ui-tabs-content>
+  <ui-tabs-content value="code">Code sample is selected.</ui-tabs-content>
+</ui-tabs>
+```
+
+### RTL
+
+Set `dir="rtl"` on the tabs root or an ancestor container when the surrounding interface runs right to left.
+
+```html
+<ui-tabs value="overview" dir="rtl" lang="ar" class="w-full max-w-md text-right">
+  <ui-tabs-list>
+    <button ui-tabs-trigger value="overview">نظرة عامة</button>
+    <button ui-tabs-trigger value="analytics">التحليلات</button>
+    <button ui-tabs-trigger value="reports">التقارير</button>
+    <button ui-tabs-trigger value="settings">الإعدادات</button>
+  </ui-tabs-list>
+
+  <ui-tabs-content value="overview">لديك ١٢ مشروعًا نشطًا و٣ مهام معلقة.</ui-tabs-content>
+</ui-tabs>
+```
+
+## API reference
+
+### `TabsComponent`
+
+| Input           | Type                         | Default        |
+| --------------- | ---------------------------- | -------------- |
+| `value` (model) | `string \| null`             | `null`         |
+| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `class`         | `string`                     | `''`           |
+
+### `TabsListComponent`
+
+| Input     | Type                  | Default     |
+| --------- | --------------------- | ----------- |
+| `variant` | `'default' \| 'line'` | `'default'` |
+| `class`   | `string`              | `''`        |
+
+### `TabsTriggerComponent`
+
+| Input      | Type      | Default |
+| ---------- | --------- | ------- |
+| `value`    | `string`  | —       |
+| `disabled` | `boolean` | `false` |
+| `class`    | `string`  | `''`    |
+
+### `TabsContentComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `value` | `string` | —       |
+| `class` | `string` | `''`    |
+
+## Styling and theming
+
+The default list uses `bg-muted` and active triggers use `bg-background`, `text-foreground`, and `shadow-sm` to match the shadcn look.
+
+The line variant uses `border-border` on the list and an active `border-foreground` underline on the trigger. Pass `class` to the root, list, trigger, or content to tune width, grid layouts, spacing, and panel framing.
+
+## Accessibility
+
+- `ui-tabs-list` renders `role="tablist"` and `aria-orientation`.
+- `button[ui-tabs-trigger]` renders `role="tab"`, `aria-selected`, roving `tabindex`, `aria-controls`, and `aria-disabled` when disabled.
+- `ui-tabs-content` renders `role="tabpanel"`, `aria-labelledby`, `tabindex="0"`, and `hidden` when inactive.
+- Keep trigger labels concise and unique. Icons inside triggers should be decorative or have their own accessible text outside the icon.
+
+## Keyboard interactions
+
+- `ArrowRight` and `ArrowLeft` move selection and focus through horizontal tabs.
+- `ArrowDown` and `ArrowUp` move selection and focus through vertical tabs.
+- `Home` and `End` jump to the first and last enabled trigger.
+- Disabled triggers are skipped by arrow-key, Home, and End navigation.
+- Enter and Space retain native button activation behavior.
+
+## Angular notes
+
+- The component uses Angular signal-based `model()` binding for `value`.
+- Use `signal<string | null>()` with `[(value)]` as the Angular equivalent of shadcn `defaultValue` when parent state matters.
+- Values are strings and should be unique within a tabs root.
+- `variant="line"` belongs to `ui-tabs-list`, matching the upstream shadcn API.
+- Icons are projected content; bring an app icon component or inline SVG where needed.
+
+## Source parity
+
+This Angular implementation follows the current shadcn Tabs docs: preview card tabs, usage, composition, line, vertical, disabled, icons, RTL, and Radix API guidance. React props are translated to Angular selectors, native buttons, and signal-friendly state.

package/textarea/README.md

@@ -0,0 +1,154 @@
+# Textarea
+
+Displays a multiline native `<textarea>` with the shared Angular theme tokens and shadcn-style field composition.
+
+Use Textarea for feedback, notes, comments, support messages, and any form surface that needs multi-line entry while keeping browser-native editing behavior.
+
+## Import
+
+```ts
+import { TextareaComponent } from '@edsis/ui/textarea';
+```
+
+Import the `form`, `label`, or `button` entrypoints separately when the page also needs structured field copy or submit actions.
+
+## Composition
+
+Textarea stays intentionally small because it styles the native control instead of wrapping it in a custom value accessor.
+
+```text
+label[ui-label]
+└── textarea[ui-textarea]
+```
+
+For the richer shadcn field pattern, compose it with the existing form primitives.
+
+```text
+ui-form-field
+├── ui-form-label
+├── textarea[ui-textarea][uiFormControl]
+└── ui-form-description or ui-form-message
+```
+
+## Basic Usage
+
+Use a visible label plus the styled native textarea when you only need the base multiline control.
+
+```html
+<label ui-label for="bio">Bio</label>
+<textarea id="bio" ui-textarea rows="4" placeholder="Tell us about yourself"></textarea>
+```
+
+When the textarea lives inside `ui-form-field`, add `uiFormControl` so labels, descriptions, and invalid state stay wired together.
+
+```html
+<ui-form-field>
+  <ui-form-label>Message</ui-form-label>
+  <textarea ui-textarea uiFormControl rows="4" placeholder="Type your message here."></textarea>
+  <ui-form-description>Enter your message below.</ui-form-description>
+</ui-form-field>
+```
+
+## Common Patterns
+
+### Field Composition
+
+The upstream shadcn `Field`, `FieldLabel`, and `FieldDescription` helpers map to the local `form` entrypoint.
+
+```html
+<ui-form-field>
+  <ui-form-label>Feedback</ui-form-label>
+  <textarea ui-textarea uiFormControl rows="4" placeholder="Your feedback helps us improve..."></textarea>
+  <ui-form-description>Share your thoughts about our service.</ui-form-description>
+</ui-form-field>
+```
+
+### Disabled and Invalid States
+
+Use the native `disabled` attribute for disabled state and `aria-invalid="true"` for validation styling.
+
+```html
+<ui-form-field>
+  <ui-form-label>Message</ui-form-label>
+  <textarea ui-textarea uiFormControl rows="4" disabled></textarea>
+  <ui-form-description>This field is currently disabled.</ui-form-description>
+</ui-form-field>
+
+<ui-form-field>
+  <ui-form-label>Message</ui-form-label>
+  <textarea ui-textarea uiFormControl rows="4" aria-invalid="true"></textarea>
+  <ui-form-description>Please enter a valid message.</ui-form-description>
+</ui-form-field>
+```
+
+### Submit Row
+
+Pair the textarea with `button[ui-button]` to create feedback and messaging layouts.
+
+```html
+<div class="grid w-full max-w-md gap-2">
+  <textarea ui-textarea rows="5" class="min-h-[140px]" placeholder="Type your message here."></textarea>
+  <button ui-button type="button" class="w-fit">Send message</button>
+</div>
+```
+
+### RTL
+
+Set `dir="rtl"` on a wrapping container or manage direction globally in your layout. The textarea stays native while labels and helper text follow the document direction.
+
+```html
+<div dir="rtl" lang="ar" class="max-w-md text-right">
+  <ui-form-field>
+    <ui-form-label>التعليقات</ui-form-label>
+    <textarea ui-textarea uiFormControl rows="4" placeholder="تعليقاتك تساعدنا على التحسين..."></textarea>
+    <ui-form-description>شاركنا أفكارك حول خدمتنا.</ui-form-description>
+  </ui-form-field>
+</div>
+```
+
+## API Reference
+
+### `TextareaComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+### Native Attributes
+
+All standard `<textarea>` attributes such as `rows`, `placeholder`, `disabled`, `required`, `readonly`, `dir`, and `aria-invalid` pass through unchanged.
+
+The component also exposes a `focus()` instance method when accessed through `ViewChild(TextareaComponent)`.
+
+## Styling and Theming
+
+The component uses the shared `border-input`, `ring-ring`, `text-foreground`, `placeholder:text-muted-foreground`, and `aria-[invalid=true]:border-destructive` tokens.
+
+Base styling includes a `min-h-[60px]` guard to avoid collapsed textareas and `resize-y` so users can increase the writing area without breaking width-constrained layouts.
+
+Pass `class` to tune height, spacing, or layout while keeping the base focus, disabled, invalid, and resize treatment.
+
+## Accessibility
+
+- Pair the textarea with a visible label using `label[ui-label]` or `ui-form-label`.
+- Use `uiFormControl` inside `ui-form-field` so helper and error text participate in the same accessible description chain.
+- Mark validation failures with `aria-invalid="true"` and provide descriptive helper or error text nearby.
+- Keep the native resize handle available so pointer and touch users can increase the input area when needed.
+
+## Keyboard Interactions
+
+- `Tab` and `Shift+Tab` move focus in and out using the normal browser order.
+- `Enter` inserts a new line instead of submitting by itself.
+- Arrow keys, Home, End, selection, and clipboard shortcuts stay browser-native.
+
+## Angular Notes
+
+- Textarea styles the native `<textarea>`, so it works with both `ngModel` and reactive forms.
+- Prefer using `uiFormControl` when the textarea lives inside `ui-form-field`.
+- Let Angular form state drive invalid styling when possible, but `aria-invalid="true"` also works for externally managed validation.
+
+## Source Parity
+
+This Angular implementation follows the shadcn Textarea page closely for the core textarea, disabled and invalid states, button layout, and RTL guidance.
+
+The upstream `Field` helper family intentionally maps to the existing Angular `form` entrypoint instead of adding a separate `field` runtime surface.

package/timeline/README.md

@@ -0,0 +1,94 @@
+# Timeline
+
+Display a series of events or steps in a vertical or horizontal timeline.
+
+This component is conceptually inspired by Flux Timeline. The Angular API, slot names, styling tokens, and examples are implemented for this library's shadcn-style component system.
+
+## Import
+
+```ts
+import {
+  TimelineBlockComponent,
+  TimelineComponent,
+  TimelineContentComponent,
+  TimelineIndicatorComponent,
+  TimelineItemComponent,
+  TimelineSubgridComponent,
+} from '@edsis/ui/timeline';
+```
+
+## Usage
+
+```html
+<ui-timeline>
+  <ui-timeline-item status="complete">
+    <ui-timeline-indicator>1</ui-timeline-indicator>
+    <ui-timeline-content>
+      <h3 class="text-sm font-medium">Submit</h3>
+      <p class="text-muted-foreground">Complete the form and provide all necessary assets.</p>
+    </ui-timeline-content>
+  </ui-timeline-item>
+</ui-timeline>
+```
+
+## Composition
+
+```text
+ui-timeline
+|-- ui-timeline-item
+|   |-- ui-timeline-indicator
+|   `-- ui-timeline-content
+|-- ui-timeline-item
+|   `-- ui-timeline-block
+|       `-- ui-timeline-subgrid
+```
+
+## Horizontal Status
+
+```html
+<ui-timeline horizontal>
+  <ui-timeline-item status="complete">
+    <ui-timeline-indicator>1</ui-timeline-indicator>
+    <ui-timeline-content>Order confirmed</ui-timeline-content>
+  </ui-timeline-item>
+  <ui-timeline-item status="current">
+    <ui-timeline-indicator>2</ui-timeline-indicator>
+    <ui-timeline-content>On its way</ui-timeline-content>
+  </ui-timeline-item>
+  <ui-timeline-item status="incomplete">
+    <ui-timeline-indicator>3</ui-timeline-indicator>
+    <ui-timeline-content>Delivered</ui-timeline-content>
+  </ui-timeline-item>
+</ui-timeline>
+```
+
+## Inputs
+
+| Part                         | Input        | Type                                 | Default    |
+| ---------------------------- | ------------ | ------------------------------------ | ---------- |
+| `TimelineComponent`          | `horizontal` | `boolean`                            | `false`    |
+| `TimelineComponent`          | `align`      | `start \| baseline \| center \| end` | `center`   |
+| `TimelineComponent`          | `size`       | `default \| lg`                      | `default`  |
+| `TimelineItemComponent`      | `status`     | `complete \| current \| incomplete`  | `null`     |
+| `TimelineItemComponent`      | `align`      | `start \| baseline \| center \| end` | root value |
+| `TimelineItemComponent`      | `size`       | `default \| lg`                      | root value |
+| `TimelineIndicatorComponent` | `variant`    | `default \| bare`                    | `default`  |
+| `TimelineIndicatorComponent` | `status`     | `complete \| current \| incomplete`  | item value |
+| `TimelineIndicatorComponent` | `color`      | standard color token                 | `null`     |
+
+## Spacing
+
+The root exposes CSS variables for spacing and indicator sizing.
+
+```html
+<ui-timeline class="[--timeline-item-gap:3rem] [--timeline-content-gap:1rem]">
+  <!-- timeline items -->
+</ui-timeline>
+```
+
+## Accessibility
+
+- Use semantic headings and text inside `ui-timeline-content`.
+- Give icon-only indicators an accessible label when the icon communicates meaning.
+- Keep chronological order in DOM order for screen readers.
+- Do not rely on color alone; pair status indicators with text content.