@ojiepermana/angular 22.1.10 → 22.1.12

package/component/resizable/README.md

@@ -0,0 +1,178 @@
+# 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 '@ojiepermana/angular/component/resizable';
+```
+
+## Composition
+
+The Angular structure mirrors the shadcn composition while using Angular selectors and standalone imports.
+
+```text
+ResizablePanelGroup
+├── ResizablePanel
+├── ResizableHandle
+└── ResizablePanel
+```
+
+## Basic usage
+
+Use `ResizablePanelGroup` as the root, place `ResizablePanel` elements around each separator, and insert `ResizableHandle` between adjacent panels.
+
+```html
+<ResizablePanelGroup
+  orientation="horizontal"
+  class="h-[200px] max-w-lg rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize="35%">
+    <div class="flex h-full items-center justify-center p-6">Navigation</div>
+  </ResizablePanel>
+
+  <ResizableHandle aria-label="Resize navigation"></ResizableHandle>
+
+  <ResizablePanel defaultSize="65%">
+    <div class="flex h-full items-center justify-center p-6">Content</div>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## 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
+<ResizablePanelGroup orientation="horizontal" class="h-[220px] rounded-lg border border-border">
+  <ResizablePanel defaultSize="50%">
+    <div class="flex h-full items-center justify-center p-6">Threads</div>
+  </ResizablePanel>
+
+  <ResizableHandle withHandle aria-label="Resize thread list"></ResizableHandle>
+
+  <ResizablePanel defaultSize="50%">
+    <ResizablePanelGroup orientation="vertical" class="h-full">
+      <ResizablePanel defaultSize="28%">
+        <div class="flex h-full items-center justify-center p-6">Summary</div>
+      </ResizablePanel>
+      <ResizableHandle withHandle aria-label="Resize summary"></ResizableHandle>
+      <ResizablePanel defaultSize="72%">
+        <div class="flex h-full items-center justify-center p-6">Details</div>
+      </ResizablePanel>
+    </ResizablePanelGroup>
+  </ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### Vertical resizing
+
+Use `orientation="vertical"` when panes stack top-to-bottom.
+
+```html
+<ResizablePanelGroup
+  orientation="vertical"
+  class="h-[220px] max-w-sm rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize="25%">...</ResizablePanel>
+  <ResizableHandle aria-label="Resize header"></ResizableHandle>
+  <ResizablePanel defaultSize="75%">...</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### Visible handle
+
+Add `withHandle` when the splitter should show a grab affordance.
+
+```html
+<ResizableHandle withHandle aria-label="Resize sidebar"></ResizableHandle>
+```
+
+### Size constraints
+
+Use `minSize` and `maxSize` to keep navigation, preview, or inspector panes within useful bounds.
+
+```html
+<ResizablePanel defaultSize="30%" minSize="20%" maxSize="40%">...</ResizablePanel>
+```
+
+### RTL
+
+Set `dir="rtl"` on `ResizablePanelGroup` or an ancestor when the layout should follow right-to-left direction. Pointer and arrow-key resizing adapt to the computed direction.
+
+```html
+<ResizablePanelGroup
+  dir="rtl"
+  orientation="horizontal"
+  class="h-[200px] rounded-lg border border-border"
+>
+  <ResizablePanel defaultSize="50%">...</ResizablePanel>
+  <ResizableHandle withHandle aria-label="تغيير حجم القائمة"></ResizableHandle>
+  <ResizablePanel defaultSize="50%">...</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## 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/component/scroll-area/README.md

@@ -0,0 +1,150 @@
+# 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 '@ojiepermana/angular/component/scroll-area';
+```
+
+Import composed primitives separately when the content needs them:
+
+```ts
+import { ScrollAreaComponent } from '@ojiepermana/angular/component/scroll-area';
+import { SeparatorComponent } from '@ojiepermana/angular/component/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
+<ScrollArea 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>
+    <Separator class="my-2" />
+    }
+  </div>
+</ScrollArea>
+```
+
+## Common Patterns
+
+### Basic List
+
+```html
+<ScrollArea 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>
+</ScrollArea>
+```
+
+### Horizontal Content
+
+```html
+<ScrollArea
+  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>
+</ScrollArea>
+```
+
+### RTL Content
+
+```html
+<ScrollArea
+  dir="rtl"
+  lang="ar"
+  class="h-72 w-48 rounded-md border border-border text-right"
+  viewportAriaLabel="قائمة العلامات"
+>
+  <div class="p-4">...</div>
+</ScrollArea>
+```
+
+## 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:
+
+- `--scrollbar-thumb` for the default scrollbar thumb (overridable via `--tw-scrollbar-thumb`).
+- `--scrollbar-track` for the scrollbar track (overridable via `--tw-scrollbar-track`).
+- `--scrollbar-thumb-hover` for the hover thumb fallback.
+- `--scrollbar-size` (default `0.5rem`) and `--scrollbar-radius` (default `9999px`) size the WebKit scrollbar.
+- `--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/component/select/README.md

@@ -0,0 +1,228 @@
+# 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 '@ojiepermana/angular/component/select';
+```
+
+## Composition
+
+`SelectField` owns the trigger, overlay, disabled state, and common ARIA passthrough.
+Project `SelectItem` children into it for the actual choices.
+
+For grouped menus, the current Angular mapping uses `MatOptgroup` from
+`@angular/material/core` inside `SelectField` rather than publishing separate
+`SelectGroup`, `SelectLabel`, or `SelectSeparator` wrappers.
+
+```text
+SelectField
+├── SelectItem
+├── SelectItem
+└── mat-optgroup (optional grouping bridge)
+    ├── SelectItem
+    └── SelectItem
+```
+
+## Basic Usage
+
+```html
+<SelectField
+  class="block w-full max-w-xs"
+  placeholder="Select a plan"
+  [(ngModel)]="plan"
+  aria-label="Plan"
+>
+  <SelectItem value="free">Free</SelectItem>
+  <SelectItem value="pro">Pro</SelectItem>
+  <SelectItem value="enterprise">Enterprise</SelectItem>
+</SelectField>
+```
+
+## Common Patterns
+
+### Searchable options (opt-in)
+
+Search is disabled by default. Add the boolean `search` input when a longer list
+benefits from filtering; no extra component or dependency is required.
+
+```html
+<SelectField
+  search
+  searchPlaceholder="Search fruit"
+  searchEmptyText="No fruit found."
+  placeholder="Select a fruit"
+  [(ngModel)]="fruit"
+  aria-label="Select a fruit"
+>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+  <SelectItem value="blueberry">Blueberry</SelectItem>
+</SelectField>
+```
+
+### Grouped options
+
+```ts
+import { MatOptgroup } from '@angular/material/core';
+```
+
+```html
+<SelectField
+  class="block w-full max-w-sm"
+  placeholder="Select produce"
+  [(ngModel)]="produce"
+  aria-label="Produce"
+>
+  <mat-optgroup label="Fruits">
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+    <SelectItem value="blueberry">Blueberry</SelectItem>
+  </mat-optgroup>
+
+  <mat-optgroup label="Vegetables">
+    <SelectItem value="carrot">Carrot</SelectItem>
+    <SelectItem value="broccoli">Broccoli</SelectItem>
+    <SelectItem value="spinach">Spinach</SelectItem>
+  </mat-optgroup>
+</SelectField>
+```
+
+### Disabled trigger
+
+```html
+<SelectField placeholder="Disabled" disabled aria-label="Disabled plan">
+  <SelectItem value="free">Free</SelectItem>
+  <SelectItem value="pro">Pro</SelectItem>
+  <SelectItem value="enterprise">Enterprise</SelectItem>
+</SelectField>
+```
+
+### Scrollable overlay
+
+Long lists scroll automatically inside the Material overlay. You do not need a
+separate input for that behavior.
+
+```html
+<SelectField
+  class="block w-full max-w-md"
+  placeholder="Select a timezone"
+  [(ngModel)]="timezone"
+  aria-label="Timezone"
+>
+  <mat-optgroup label="North America">
+    <SelectItem value="est">Eastern Standard Time</SelectItem>
+    <SelectItem value="cst">Central Standard Time</SelectItem>
+    <SelectItem value="mst">Mountain Standard Time</SelectItem>
+    <SelectItem value="pst">Pacific Standard Time</SelectItem>
+  </mat-optgroup>
+
+  <mat-optgroup label="Europe & Africa">
+    <SelectItem value="gmt">Greenwich Mean Time</SelectItem>
+    <SelectItem value="cet">Central European Time</SelectItem>
+    <SelectItem value="eet">Eastern European Time</SelectItem>
+  </mat-optgroup>
+</SelectField>
+```
+
+### 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
+<SelectField
+  class="block w-full max-w-sm"
+  placeholder="Select department"
+  aria-label="Department"
+  aria-describedby="department-error"
+  [formControl]="departmentControl"
+  required
+>
+  <SelectItem value="engineering">Engineering</SelectItem>
+  <SelectItem value="sales">Sales</SelectItem>
+  <SelectItem value="operations">Operations</SelectItem>
+</SelectField>
+
+<p id="department-error" class="text-sm font-medium text-destructive">
+  Select a department before continuing.
+</p>
+```
+
+### Multiple selection
+
+```html
+<SelectField multiple [(ngModel)]="interests" aria-label="Interests">
+  @for (i of all; track i) {
+  <SelectItem [value]="i">{{ i }}</SelectItem>
+  }
+</SelectField>
+```
+
+## API Reference
+
+| Primitive             | Selector       | Inputs                                                                                                                                                            | Outputs                       |
+| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `SelectComponent`     | `SelectField`  | `placeholder`, `disabled`, `multiple`, `required`, `search`, `searchPlaceholder`, `searchEmptyText`, `aria-label`, `aria-labelledby`, `aria-describedby`, `class` | `valueChange`, `openedChange` |
+| `OptionComponent`     | `SelectItem`   | `value`, `disabled`, `class`                                                                                                                                      | none                          |
+| `MatOptgroup` mapping | `mat-optgroup` | `label`, `disabled`                                                                                                                                               | none                          |
+
+Public methods on `SelectComponent`: `open()`, `close()`, `focus()`.
+
+## Styling and Theming
+
+The component keeps Angular Material overlay interaction while applying local
+item-aligned positioning and shadcn-style bridge tokens through
+`select.component.css`.
+
+- The trigger, overlay panel, and option state backgrounds use the same
+  `--radius-base` value, so global `theme-radius` and component-level `radius`
+  overrides reshape the complete control consistently.
+- The panel covers the trigger and matches its horizontal bounds. It grows
+  downward when space permits and falls back upward near the viewport edge.
+- While the listbox is open, the active ring moves from the covered trigger to
+  the overlay panel. Closing the panel restores the ring to the focused trigger.
+- Adjacent option state backgrounds keep a subtle half-`--spacing-base` gap, so
+  hovered and selected rows remain visually distinct without changing density.
+- The overlay panel keeps `panelClass="select-panel"` so the shared Material
+  bridge layer can restyle the menu surface and options.
+- Opt-in search uses the same input, radius, spacing, foreground, and ring tokens
+  as the surrounding panel.
+- 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.
+- Localize `searchPlaceholder` and `searchEmptyText` when search is enabled.
+- Group options only when the categories make the list easier to scan.
+
+## Keyboard Interactions
+
+- `Enter`, `Space`, or `Alt+ArrowDown` opens the trigger.
+- Without search, Arrow keys move through the open option list and Material typeahead jumps to matching labels.
+- With search enabled, typing filters labels and Arrow keys move only through matching options.
+- `Enter` or `Space` confirms the active option, and `Escape` closes the panel.
+
+## Angular Notes
+
+- `SelectField` 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[NativeSelect]` instead.
+
+## Source Parity
+
+This Angular slice follows the shadcn Select information architecture while staying honest about the local API.
+
+- The public entrypoint exposes `SelectField` and `SelectItem` 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 is item-aligned: the panel covers the trigger, stays on
+  its horizontal axis, and chooses a downward or upward opening direction from
+  the available viewport space. The wrapper does not expose a separate
+  `position="item-aligned" | "popper"` switch.