@edsis/ui 0.0.2

package/resizable/README.md

@@ -0,0 +1,164 @@
+# Resizable
+
+Accessible resizable panel groups and layouts with pointer and keyboard support.
+
+Use Resizable for split views, workspace layouts, drill-in dashboards, inspector panes, and settings screens where users should control how much space each pane receives.
+
+## Import
+
+```ts
+import { ResizableHandleComponent, ResizablePanelComponent, ResizablePanelGroupComponent } from '@edsis/ui/resizable';
+```
+
+## Composition
+
+The Angular structure mirrors the shadcn composition while using Angular selectors and standalone imports.
+
+```text
+ui-resizable-panel-group
+├── ui-resizable-panel
+├── ui-resizable-handle
+└── ui-resizable-panel
+```
+
+## Basic usage
+
+Use `ui-resizable-panel-group` as the root, place `ui-resizable-panel` elements around each separator, and insert `ui-resizable-handle` between adjacent panels.
+
+```html
+<ui-resizable-panel-group orientation="horizontal" class="h-[200px] max-w-lg rounded-lg border border-border">
+  <ui-resizable-panel defaultSize="35%">
+    <div class="flex h-full items-center justify-center p-6">Navigation</div>
+  </ui-resizable-panel>
+
+  <ui-resizable-handle aria-label="Resize navigation"></ui-resizable-handle>
+
+  <ui-resizable-panel defaultSize="65%">
+    <div class="flex h-full items-center justify-center p-6">Content</div>
+  </ui-resizable-panel>
+</ui-resizable-panel-group>
+```
+
+## Common patterns
+
+### Nested workspace layout
+
+Nested groups work well for mail, support, or analytics layouts where a secondary area also needs its own split.
+
+```html
+<ui-resizable-panel-group orientation="horizontal" class="h-[220px] rounded-lg border border-border">
+  <ui-resizable-panel defaultSize="50%">
+    <div class="flex h-full items-center justify-center p-6">Threads</div>
+  </ui-resizable-panel>
+
+  <ui-resizable-handle withHandle aria-label="Resize thread list"></ui-resizable-handle>
+
+  <ui-resizable-panel defaultSize="50%">
+    <ui-resizable-panel-group orientation="vertical" class="h-full">
+      <ui-resizable-panel defaultSize="28%">
+        <div class="flex h-full items-center justify-center p-6">Summary</div>
+      </ui-resizable-panel>
+      <ui-resizable-handle withHandle aria-label="Resize summary"></ui-resizable-handle>
+      <ui-resizable-panel defaultSize="72%">
+        <div class="flex h-full items-center justify-center p-6">Details</div>
+      </ui-resizable-panel>
+    </ui-resizable-panel-group>
+  </ui-resizable-panel>
+</ui-resizable-panel-group>
+```
+
+### Vertical resizing
+
+Use `orientation="vertical"` when panes stack top-to-bottom.
+
+```html
+<ui-resizable-panel-group orientation="vertical" class="h-[220px] max-w-sm rounded-lg border border-border">
+  <ui-resizable-panel defaultSize="25%">...</ui-resizable-panel>
+  <ui-resizable-handle aria-label="Resize header"></ui-resizable-handle>
+  <ui-resizable-panel defaultSize="75%">...</ui-resizable-panel>
+</ui-resizable-panel-group>
+```
+
+### Visible handle
+
+Add `withHandle` when the splitter should show a grab affordance.
+
+```html
+<ui-resizable-handle withHandle aria-label="Resize sidebar"></ui-resizable-handle>
+```
+
+### Size constraints
+
+Use `minSize` and `maxSize` to keep navigation, preview, or inspector panes within useful bounds.
+
+```html
+<ui-resizable-panel defaultSize="30%" minSize="20%" maxSize="40%">...</ui-resizable-panel>
+```
+
+### RTL
+
+Set `dir="rtl"` on `ui-resizable-panel-group` or an ancestor when the layout should follow right-to-left direction. Pointer and arrow-key resizing adapt to the computed direction.
+
+```html
+<ui-resizable-panel-group dir="rtl" orientation="horizontal" class="h-[200px] rounded-lg border border-border">
+  <ui-resizable-panel defaultSize="50%">...</ui-resizable-panel>
+  <ui-resizable-handle withHandle aria-label="تغيير حجم القائمة"></ui-resizable-handle>
+  <ui-resizable-panel defaultSize="50%">...</ui-resizable-panel>
+</ui-resizable-panel-group>
+```
+
+## API reference
+
+### `ResizablePanelGroupComponent`
+
+| Input         | Type                         | Default        |
+| ------------- | ---------------------------- | -------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `class`       | `string`                     | `''`           |
+
+### `ResizablePanelComponent`
+
+| Input         | Type                       | Default        |
+| ------------- | -------------------------- | -------------- |
+| `defaultSize` | `string \| number \| null` | `null`         |
+| `minSize`     | `string \| number`         | `'10%'`        |
+| `maxSize`     | `string \| number`         | `'90%'`        |
+| `id`          | `string \| null`           | auto-generated |
+| `class`       | `string`                   | `''`           |
+
+### `ResizableHandleComponent`
+
+| Input        | Type             | Default          |
+| ------------ | ---------------- | ---------------- |
+| `withHandle` | `boolean`        | `false`          |
+| `aria-label` | `string \| null` | `'Resize panel'` |
+| `class`      | `string`         | `''`             |
+
+## Styling and theming
+
+Pass `class` to the group, panel, or handle to tune height, width, backgrounds, borders, and embedded layouts.
+
+The primitives use the shared theme tokens, so utilities such as `border-border`, `bg-card`, `bg-muted/40`, `text-foreground`, and `focus-visible:ring-ring` work as expected.
+
+## Accessibility
+
+- Each handle is a focusable `separator` with `aria-controls`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.
+- Provide a clear `aria-label` for each handle when the surrounding pane label is not already obvious from context.
+- Panels stay in normal page flow, which keeps nested forms and content accessible without extra portals or overlays.
+
+## Keyboard interactions
+
+- Arrow keys resize the adjacent panes.
+- `Home` moves the primary pane to its minimum allowed size.
+- `End` moves the primary pane to its maximum allowed size.
+- `Enter` collapses the primary pane to its minimum and restores the previous size on the next press.
+
+## Angular notes
+
+- The API follows the shadcn `orientation` plus percent-size model, but does not require React or `react-resizable-panels`.
+- `defaultSize`, `minSize`, and `maxSize` accept either percentage strings such as `'25%'` or numeric percentages such as `25`.
+- Custom element hosts are explicitly block-level flex items so nested groups and dashboard panes size correctly inside Angular templates.
+
+## Source parity
+
+This Angular implementation follows the shadcn Resizable composition and examples while translating them to standalone component imports, Angular selectors, and a signal-driven internal layout model.

package/scroll-area/README.md

@@ -0,0 +1,143 @@
+# Scroll Area
+
+Native scroll viewport with token-styled scrollbars for constrained lists,
+horizontal galleries, and RTL content. It maps the shadcn Scroll Area pattern to
+Angular while keeping scrolling browser-native.
+
+## Import
+
+```ts
+import { ScrollAreaComponent } from '@edsis/ui/scroll-area';
+```
+
+Import composed primitives separately when the content needs them:
+
+```ts
+import { ScrollAreaComponent } from '@edsis/ui/scroll-area';
+import { SeparatorComponent } from '@edsis/ui/separator';
+```
+
+## Usage
+
+Give the host a stable height or width, then place padding on inner content when
+the scrollbar should stay flush with the border.
+
+```html
+<ui-scroll-area class="h-72 w-48 rounded-md border border-border" viewportAriaLabel="Release tags">
+  <div class="p-4">
+    <h4 class="mb-4 text-sm font-medium leading-none">Tags</h4>
+    @for (tag of tags; track tag) {
+    <div class="text-sm">{{ tag }}</div>
+    <ui-separator class="my-2" />
+    }
+  </div>
+</ui-scroll-area>
+```
+
+## Common Patterns
+
+### Basic List
+
+```html
+<ui-scroll-area class="h-64 w-56 rounded-md border border-border" viewportAriaLabel="Activity log">
+  <ol class="space-y-3 p-4 text-sm">
+    @for (event of events; track event.id) {
+    <li>{{ event.label }}</li>
+    }
+  </ol>
+</ui-scroll-area>
+```
+
+### Horizontal Content
+
+```html
+<ui-scroll-area class="w-full max-w-md rounded-md border border-border" viewportAriaLabel="Artwork gallery">
+  <div class="flex w-max gap-4 p-4">
+    @for (artwork of artworks; track artwork.id; let index = $index) {
+    <figure class="shrink-0">
+      <img
+        [ngSrc]="artwork.image"
+        [alt]="artwork.alt"
+        [priority]="index === 0"
+        width="300"
+        height="400"
+        class="aspect-3/4 h-64 w-48 rounded-md object-cover" />
+      <figcaption class="pt-2 text-xs text-muted-foreground">{{ artwork.caption }}</figcaption>
+    </figure>
+    }
+  </div>
+</ui-scroll-area>
+```
+
+### RTL Content
+
+```html
+<ui-scroll-area
+  dir="rtl"
+  lang="ar"
+  class="h-72 w-48 rounded-md border border-border text-right"
+  viewportAriaLabel="قائمة العلامات">
+  <div class="p-4">...</div>
+</ui-scroll-area>
+```
+
+## API Reference
+
+| Input               | Type             | Default | Description                                                                                   |
+| ------------------- | ---------------- | ------- | --------------------------------------------------------------------------------------------- |
+| `class`             | `string`         | `''`    | Classes applied to the custom-element host. Use this for size, border, radius, and placement. |
+| `viewportClass`     | `string`         | `''`    | Classes merged onto the native scroll viewport for axis control, whitespace, or overflow.     |
+| `viewportAriaLabel` | `string \| null` | `null`  | Adds an accessible label and exposes the viewport as a named region.                          |
+| `viewportTabIndex`  | `number`         | `0`     | Keeps the scroll viewport keyboard-focusable. Use `-1` only when focusable children suffice.  |
+
+## Styling and Theming
+
+The host is block-level, relatively positioned, and overflow-hidden. The inner
+viewport uses native `overflow: auto`, `scrollbar-width: thin` for Firefox, and
+WebKit scrollbar pseudo-elements for Chromium/Safari.
+
+Tokens consumed:
+
+- `--border` for the default scrollbar thumb.
+- `--muted-foreground` for the hover thumb fallback.
+- `--ring` for keyboard focus indication.
+
+Pass `class` for host sizing and borders, and `viewportClass` when the viewport
+itself needs adjustments such as `whitespace-nowrap`, custom padding, or axis
+constraints.
+
+## Accessibility
+
+The component keeps native wheel, touch, momentum, and keyboard scrolling. The
+viewport is focusable by default with `tabindex="0"`, so keyboard users can
+scroll overflowing content even when there are no focusable descendants.
+
+Use `viewportAriaLabel` when the scrollable region needs a spoken name. When a
+label is present, the viewport is exposed as `role="region"`. Keep long lists in
+logical DOM order and avoid hiding important content behind custom-only pointer
+controls.
+
+## Keyboard Interactions
+
+When the viewport has focus, the browser handles scrolling keys:
+
+- Arrow keys move in the matching direction.
+- Page Up and Page Down scroll by a larger step.
+- Home and End jump to the start or end where supported.
+- Space follows the browser's scroll behavior for the focused region.
+
+## Angular Notes
+
+`ScrollAreaComponent` is standalone and has no provider setup. Use Angular
+`@for` with stable track expressions for long content. For static artwork inside
+horizontal scroll examples, import `NgOptimizedImage` and use `ngSrc`.
+
+The component intentionally does not add a child `ScrollBar` directive. Native
+scrollbars are styled by CSS and remain visible only when the content overflows.
+
+## Source Parity
+
+The shadcn Scroll Area docs show `ScrollArea` plus a `ScrollBar` part. This
+Angular implementation preserves the same usage goals, examples, RTL guidance,
+and themed scrollbar appearance while mapping `ScrollBar` to browser-native
+scrollbars instead of a separate decorative child component.

package/select/README.md

@@ -0,0 +1,174 @@
+# Select
+
+Material-backed custom select with shadcn styling for overlay-driven single or multiple choice.
+
+## Import
+
+```ts
+import { FormsModule } from '@angular/forms';
+import { OptionComponent, SelectComponent } from '@your-scope/angular/component/select';
+```
+
+## Composition
+
+`ui-select` owns the trigger, overlay, disabled state, and common ARIA passthrough.
+Project `ui-option` children into it for the actual choices.
+
+For grouped menus, the current Angular mapping uses `MatOptgroup` from
+`@angular/material/core` inside `ui-select` rather than publishing separate
+`SelectGroup`, `SelectLabel`, or `SelectSeparator` wrappers.
+
+```text
+ui-select
+├── ui-option
+├── ui-option
+└── mat-optgroup (optional grouping bridge)
+    ├── ui-option
+    └── ui-option
+```
+
+## Basic Usage
+
+```html
+<ui-select class="block w-full max-w-xs" placeholder="Select a plan" [(ngModel)]="plan" aria-label="Plan">
+  <ui-option value="free">Free</ui-option>
+  <ui-option value="pro">Pro</ui-option>
+  <ui-option value="enterprise">Enterprise</ui-option>
+</ui-select>
+```
+
+## Common Patterns
+
+### Grouped options
+
+```ts
+import { MatOptgroup } from '@angular/material/core';
+```
+
+```html
+<ui-select class="block w-full max-w-sm" placeholder="Select produce" [(ngModel)]="produce" aria-label="Produce">
+  <mat-optgroup label="Fruits">
+    <ui-option value="apple">Apple</ui-option>
+    <ui-option value="banana">Banana</ui-option>
+    <ui-option value="blueberry">Blueberry</ui-option>
+  </mat-optgroup>
+
+  <mat-optgroup label="Vegetables">
+    <ui-option value="carrot">Carrot</ui-option>
+    <ui-option value="broccoli">Broccoli</ui-option>
+    <ui-option value="spinach">Spinach</ui-option>
+  </mat-optgroup>
+</ui-select>
+```
+
+### Disabled trigger
+
+```html
+<ui-select placeholder="Disabled" disabled aria-label="Disabled plan">
+  <ui-option value="free">Free</ui-option>
+  <ui-option value="pro">Pro</ui-option>
+  <ui-option value="enterprise">Enterprise</ui-option>
+</ui-select>
+```
+
+### Scrollable overlay
+
+Long lists scroll automatically inside the Material overlay. You do not need a
+separate input for that behavior.
+
+```html
+<ui-select class="block w-full max-w-md" placeholder="Select a timezone" [(ngModel)]="timezone" aria-label="Timezone">
+  <mat-optgroup label="North America">
+    <ui-option value="est">Eastern Standard Time</ui-option>
+    <ui-option value="cst">Central Standard Time</ui-option>
+    <ui-option value="mst">Mountain Standard Time</ui-option>
+    <ui-option value="pst">Pacific Standard Time</ui-option>
+  </mat-optgroup>
+
+  <mat-optgroup label="Europe & Africa">
+    <ui-option value="gmt">Greenwich Mean Time</ui-option>
+    <ui-option value="cet">Central European Time</ui-option>
+    <ui-option value="eet">Eastern European Time</ui-option>
+  </mat-optgroup>
+</ui-select>
+```
+
+### Helper and error text
+
+The wrapper accepts `aria-describedby`, so helper or error text can live next to
+the trigger instead of inside it.
+
+```html
+<ui-select
+  class="block w-full max-w-sm"
+  placeholder="Select department"
+  aria-label="Department"
+  aria-describedby="department-error"
+  [formControl]="departmentControl"
+  required>
+  <ui-option value="engineering">Engineering</ui-option>
+  <ui-option value="sales">Sales</ui-option>
+  <ui-option value="operations">Operations</ui-option>
+</ui-select>
+
+<p id="department-error" class="text-sm font-medium text-destructive">Select a department before continuing.</p>
+```
+
+### Multiple selection
+
+```html
+<ui-select multiple [(ngModel)]="interests" aria-label="Interests">
+  @for (i of all; track i) {
+  <ui-option [value]="i">{{ i }}</ui-option>
+  }
+</ui-select>
+```
+
+## API Reference
+
+| Primitive             | Selector       | Inputs                                                                                                          | Outputs                       |
+| --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `SelectComponent`     | `ui-select`    | `placeholder`, `disabled`, `multiple`, `required`, `aria-label`, `aria-labelledby`, `aria-describedby`, `class` | `valueChange`, `openedChange` |
+| `OptionComponent`     | `ui-option`    | `value`, `disabled`, `class`                                                                                    | none                          |
+| `MatOptgroup` mapping | `mat-optgroup` | `label`, `disabled`                                                                                             | none                          |
+
+Public methods on `SelectComponent`: `open()`, `close()`, `focus()`.
+
+## Styling and Theming
+
+The component inherits Angular Material overlay behavior but applies the local
+shadcn-style bridge tokens through `select.component.css`.
+
+- The trigger uses the local input, ring, radius, and muted-foreground tokens.
+- The overlay panel keeps `panelClass="ui-select-panel"` so the shared Material
+  bridge layer can restyle the menu surface and options.
+- Group labels come from Angular Material `mat-optgroup`, so grouped menus inherit
+  Material spacing while still picking up the surrounding theme tokens.
+
+## Accessibility
+
+Built on `mat-select`, which exposes the listbox/combobox interaction contract.
+
+- Provide an accessible name with surrounding copy or `aria-label`/`aria-labelledby`.
+- Use `aria-describedby` when helper or validation text is rendered next to the trigger.
+- Group options only when the categories make the list easier to scan.
+
+## Keyboard Interactions
+
+- `Enter`, `Space`, or `Alt+ArrowDown` opens the trigger.
+- Arrow keys move through the open option list, and Material typeahead jumps to matching labels.
+- `Enter` or `Space` confirms the active option, and `Escape` closes the panel.
+
+## Angular Notes
+
+- `ui-select` is intentionally a thin Angular wrapper over `mat-select` rather than a one-to-one Radix port.
+- Grouped menus currently rely on `MatOptgroup` from `@angular/material/core`.
+- If you want browser-native pickers, semantic `optgroup` nodes, or mobile-first behavior, use `select[ui-native-select]` instead.
+
+## Source Parity
+
+This Angular slice follows the shadcn Select information architecture while staying honest about the local API.
+
+- The public entrypoint exposes `ui-select` and `ui-option` instead of separate `SelectTrigger`, `SelectContent`, `SelectGroup`, and `SelectItem` components.
+- Group labels map to Angular Material `mat-optgroup`; there is no published `SelectSeparator` wrapper today.
+- Overlay positioning follows Angular Material, so the wrapper does not currently expose the shadcn/Radix `position="item-aligned" | "popper"` switch.

package/separator/README.md

@@ -0,0 +1,170 @@
+# Separator
+
+Visually or semantically separates content. Use Separator for subtle section
+breaks, split navigation rows, compact menu metadata, and stacked definition
+lists.
+
+## Import
+
+```ts
+import { SeparatorComponent } from '@edsis/ui/separator';
+```
+
+## Basic usage
+
+Use the default separator for purely visual breaks. When the divider carries
+structure that assistive technology should announce, set
+`[decorative]="false"`.
+
+```html
+<ui-separator class="my-4" /> <ui-separator [decorative]="false" class="my-4" />
+```
+
+## Common patterns
+
+### Preview card
+
+This mirrors the upstream shadcn hero example: title block, separator, then the
+supporting description.
+
+```html
+<div class="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card/40 p-5 text-sm">
+  <div class="flex flex-col gap-1.5">
+    <div class="leading-none font-medium">shadcn/ui</div>
+    <div class="text-muted-foreground">The Foundation for your Design System</div>
+  </div>
+  <ui-separator />
+  <div class="text-muted-foreground">
+    A set of beautifully designed components that you can customize, extend, and build on.
+  </div>
+</div>
+```
+
+### Vertical row
+
+Use `orientation="vertical"` when the separator sits inside a horizontal flex
+row. Give the host an explicit height, or inherit it from a parent with defined
+cross-axis size.
+
+```html
+<div class="flex h-5 items-center gap-4 text-sm">
+  <div>Blog</div>
+  <ui-separator orientation="vertical" class="h-5" />
+  <div>Docs</div>
+  <ui-separator orientation="vertical" class="h-5" />
+  <div>Source</div>
+</div>
+```
+
+### Menu metadata
+
+Vertical separators work well between compact description groups.
+
+```html
+<div class="flex w-full max-w-2xl items-center gap-2 text-sm md:gap-4">
+  <div class="flex flex-col gap-1">
+    <span class="font-medium">Settings</span>
+    <span class="text-xs text-muted-foreground">Manage preferences</span>
+  </div>
+  <ui-separator orientation="vertical" class="h-10" />
+  <div class="flex flex-col gap-1">
+    <span class="font-medium">Account</span>
+    <span class="text-xs text-muted-foreground">Profile &amp; security</span>
+  </div>
+  <ui-separator orientation="vertical" class="hidden h-10 md:block" />
+  <div class="hidden flex-col gap-1 md:flex">
+    <span class="font-medium">Help</span>
+    <span class="text-xs text-muted-foreground">Support &amp; docs</span>
+  </div>
+</div>
+```
+
+### List rows
+
+Horizontal separators are the lightest-weight way to split dense stacked rows.
+
+```html
+<div class="flex w-full max-w-sm flex-col gap-2 text-sm">
+  <dl class="flex items-center justify-between gap-4">
+    <dt class="font-medium">Item 1</dt>
+    <dd class="text-muted-foreground">Value 1</dd>
+  </dl>
+  <ui-separator />
+  <dl class="flex items-center justify-between gap-4">
+    <dt class="font-medium">Item 2</dt>
+    <dd class="text-muted-foreground">Value 2</dd>
+  </dl>
+  <ui-separator />
+  <dl class="flex items-center justify-between gap-4">
+    <dt class="font-medium">Item 3</dt>
+    <dd class="text-muted-foreground">Value 3</dd>
+  </dl>
+</div>
+```
+
+### RTL
+
+The separator itself does not need an RTL-specific API. Set `dir="rtl"` on the
+surrounding container and translate neighboring content.
+
+```html
+<section
+  dir="rtl"
+  lang="ar"
+  class="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card/40 p-5 text-right text-sm">
+  <div class="flex flex-col gap-1.5">
+    <div class="leading-none font-medium">shadcn/ui</div>
+    <div class="text-muted-foreground">الأساس لنظام التصميم الخاص بك</div>
+  </div>
+  <ui-separator />
+  <div class="text-muted-foreground">مجموعة من المكونات المصممة بشكل جميل يمكنك تخصيصها وتوسيعها والبناء عليها.</div>
+</section>
+```
+
+## API reference
+
+| Input         | Type                         | Default        | Description                                                    |
+| ------------- | ---------------------------- | -------------- | -------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of the divider.                                           |
+| `decorative`  | `boolean`                    | `true`         | When `false`, sets `role="separator"` plus `aria-orientation`. |
+| `class`       | `string`                     | `''`           | Width, height, spacing, and visibility utilities.              |
+
+Native host attributes such as `dir`, `data-*`, and `id` still pass through to
+the custom element host.
+
+## Styling and theming
+
+Tokens consumed:
+
+- `bg-border` for the rule itself.
+
+Horizontal mode applies `h-px w-full`. Vertical mode applies `h-full w-px`.
+The host renders as a block-level custom element so width and height utilities
+behave predictably on the separator itself.
+
+## Accessibility
+
+- Separators are decorative by default and render with `role="none"`.
+- When the divider carries structure, set `[decorative]="false"` so assistive
+  technology sees a real `separator` with the correct `aria-orientation`.
+- Keep accessible names on the surrounding content; separators themselves do not
+  require labels.
+
+## Keyboard interactions
+
+Separator is not interactive and has no keyboard behavior of its own.
+
+## Angular notes
+
+- Because `ui-separator` is a custom element, vertical examples need a height
+  source from the parent or the host `class` input.
+- The block-level host class is intentional. It ensures horizontal separators
+  honor `w-full` and other layout utilities that would otherwise be unreliable
+  on an inline custom element.
+
+## Source parity
+
+This Angular implementation follows the shadcn separator preview plus the
+vertical, menu, list, and RTL examples. It adds Angular-specific guidance for
+semantic separators and for the custom-element host layout behavior needed to
+match the upstream visuals.