@ojiepermana/angular 22.1.10 → 22.1.12

package/component/composer/README.md

@@ -0,0 +1,241 @@
+# Composer
+
+Configurable prompt composer for chat, AI, and message surfaces.
+
+This Angular implementation takes conceptual inspiration from Flux Composer, but the API, styling, and composition model follow the shadcn-style patterns already established in this library.
+
+## Import
+
+```ts
+import {
+  ComposerActionsLeadingComponent,
+  ComposerActionsTrailingComponent,
+  ComposerComponent,
+  ComposerFooterComponent,
+  ComposerHeaderComponent,
+  ComposerInputComponent,
+  ComposerTextareaComponent,
+} from '@ojiepermana/angular/component/composer';
+```
+
+## Composition
+
+```text
+Composer
+├── ComposerHeader (optional)
+├── ComposerActionsLeading (optional)
+├── textarea[ComposerInput] or ComposerInput
+├── ComposerActionsTrailing (optional)
+└── ComposerFooter (optional)
+```
+
+Use `textarea[ComposerInput]` when you want native textarea behavior, template-driven forms, or reactive forms.
+Use `ComposerInput` when you want to project a custom rich-text surface or editor shell.
+
+## Basic Usage
+
+```html
+<form (ngSubmit)="send()">
+  <Composer (submitRequested)="send()">
+    <textarea
+      ComposerInput
+      rows="2"
+      maxRows="6"
+      placeholder="How can I help you today?"
+      [(ngModel)]="prompt"
+      name="prompt"
+    ></textarea>
+
+    <ComposerActionsTrailing>
+      <button Button type="submit" size="icon-sm" aria-label="Send prompt">Send</button>
+    </ComposerActionsTrailing>
+  </Composer>
+</form>
+```
+
+## With Header
+
+Use the header slot for file previews, avatars, upload summaries, or compact context cards.
+
+```html
+<Composer>
+  <ComposerHeader>
+    <div class="flex items-center gap-3 rounded-lg border border-border bg-muted/40 px-3 py-2">
+      <img src="/avatar.png" alt="Uploaded file owner" class="size-10 rounded-md object-cover" />
+      <div class="min-w-0">
+        <p class="truncate text-sm font-medium">profile-shot.png</p>
+        <p class="text-xs text-muted-foreground">2.1 MB</p>
+      </div>
+    </div>
+  </ComposerHeader>
+
+  <textarea ComposerInput rows="2" maxRows="6" placeholder="Ask about this asset..."></textarea>
+
+  <ComposerActionsTrailing>
+    <button Button type="button" size="sm">Send</button>
+  </ComposerActionsTrailing>
+</Composer>
+```
+
+## Inline Layout
+
+Set `inline` when actions and input should share a compact single-row shell.
+
+```html
+<Composer inline submit="enter">
+  <ComposerActionsLeading>
+    <button Button type="button" variant="ghost" size="icon-sm" aria-label="Add attachment">
+      +
+    </button>
+  </ComposerActionsLeading>
+
+  <textarea ComposerInput rows="1" maxRows="4" placeholder="Reply..."></textarea>
+
+  <ComposerActionsTrailing>
+    <button Button type="button" variant="secondary" size="icon-sm" aria-label="Voice input">
+      Mic
+    </button>
+    <button Button type="submit" size="icon-sm" aria-label="Send reply">Send</button>
+  </ComposerActionsTrailing>
+</Composer>
+```
+
+## Input Variant
+
+Set `variant="input"` when the composer should align more closely with the radius and density of other input surfaces.
+
+```html
+<Composer variant="input">
+  <textarea ComposerInput rows="2" maxRows="5" placeholder="What's on your mind?"></textarea>
+</Composer>
+```
+
+## Height And Autosize
+
+`rows` sets the initial height of the native textarea surface.
+`maxRows` caps autosize growth before the textarea begins scrolling.
+
+```html
+<Composer>
+  <textarea ComposerInput rows="3" maxRows="8" placeholder="Write a longer prompt..."></textarea>
+</Composer>
+```
+
+## Submit Behavior
+
+By default, keyboard submission uses `cmd-enter`, which means `Cmd+Enter` on macOS and `Ctrl+Enter` on Windows/Linux.
+
+Use `submit="enter"` when pressing `Enter` should submit immediately. `Shift+Enter` still inserts a new line.
+
+```html
+<Composer submit="enter" (submitRequested)="send()">
+  <textarea ComposerInput rows="1" maxRows="4" placeholder="Quick reply..."></textarea>
+</Composer>
+```
+
+When `submitForm` stays `true`, the composer also calls the nearest native `form.requestSubmit()` after emitting `submitRequested`.
+
+## Rich Text Slot
+
+Project a custom editor shell through `ComposerInput` when you want a richer surface without changing the composer container API.
+
+```html
+<Composer>
+  <ComposerInput>
+    <div
+      contenteditable="true"
+      role="textbox"
+      aria-multiline="true"
+      class="min-h-20 w-full rounded-sm bg-transparent px-2 py-2 outline-none"
+    >
+      Draft a richer message...
+    </div>
+  </ComposerInput>
+
+  <ComposerActionsLeading>
+    <button Button type="button" variant="ghost" size="icon-sm" aria-label="Insert file">+</button>
+  </ComposerActionsLeading>
+
+  <ComposerActionsTrailing>
+    <button Button type="button" size="icon-sm" aria-label="Send rich text message">Send</button>
+  </ComposerActionsTrailing>
+</Composer>
+```
+
+## Disabled And Invalid
+
+Use the root inputs for shared composer state.
+
+```html
+<Composer [disabled]="isSending" [invalid]="promptInvalid">
+  <textarea ComposerInput rows="2" maxRows="6"></textarea>
+</Composer>
+```
+
+For native textarea integrations, `aria-invalid` can still be supplied directly on `textarea[ComposerInput]` when state comes from another layer.
+
+## API Reference
+
+### `ComposerComponent`
+
+| Input        | Type                     | Default       | Notes                                                                 |
+| ------------ | ------------------------ | ------------- | --------------------------------------------------------------------- |
+| `variant`    | `'default' \| 'input'`   | `'default'`   | Controls shell radius and density.                                    |
+| `inline`     | `boolean`                | `false`       | Places leading actions, input, and trailing actions in a compact row. |
+| `disabled`   | `boolean`                | `false`       | Applies shared disabled treatment and prevents keyboard submit.       |
+| `invalid`    | `boolean`                | `false`       | Applies destructive border and ring treatment.                        |
+| `submit`     | `'cmd-enter' \| 'enter'` | `'cmd-enter'` | Controls keyboard submit behavior.                                    |
+| `submitForm` | `boolean`                | `true`        | Requests native form submission after `submitRequested`.              |
+| `class`      | `string`                 | `''`          | Appends classes to the composer host.                                 |
+
+### `ComposerComponent` output
+
+| Output            | Type            | Notes                                                                 |
+| ----------------- | --------------- | --------------------------------------------------------------------- |
+| `submitRequested` | `KeyboardEvent` | Emitted when keyboard submission is triggered from the input surface. |
+
+### `ComposerTextareaComponent`
+
+| Input          | Type             | Default | Notes                                               |
+| -------------- | ---------------- | ------- | --------------------------------------------------- |
+| `rows`         | `number`         | `2`     | Initial line count.                                 |
+| `maxRows`      | `number \| null` | `null`  | Maximum autosize line count before scrolling.       |
+| `disabled`     | `boolean`        | `false` | Disables the textarea even if the root is enabled.  |
+| `aria-invalid` | `boolean`        | `false` | Applies invalid styling on the textarea input slot. |
+| `class`        | `string`         | `''`    | Appends classes to the textarea host.               |
+
+### Slot Components
+
+`ComposerHeaderComponent`, `ComposerFooterComponent`, `ComposerActionsLeadingComponent`, `ComposerActionsTrailingComponent`, and `ComposerInputComponent` each accept a single `class` input.
+
+## Accessibility
+
+- Pair `textarea[ComposerInput]` with an accessible label from surrounding copy, `aria-label`, or form-field composition.
+- Give icon-only buttons inside action slots explicit `aria-label` values.
+- Keep meaningful supporting text in `ComposerFooter` or nearby description content.
+- Use `submit="enter"` carefully in multiline experiences so users still understand `Shift+Enter` for a new line.
+- When projecting a custom editor through `ComposerInput`, provide `role="textbox"`, `aria-multiline="true"`, and clear keyboard handling in the editor surface itself.
+
+## Keyboard Interactions
+
+- `Cmd+Enter` or `Ctrl+Enter` submits by default.
+- `Enter` submits when `submit="enter"`.
+- `Shift+Enter` keeps inserting new lines in `submit="enter"` mode.
+- Standard textarea editing, selection, clipboard, and IME behavior remain native when using `textarea[ComposerInput]`.
+
+## Styling And Theming
+
+The composer uses the shared `border-input`, `bg-background`, `ring-ring`, `text-foreground`, and `placeholder:text-muted-foreground` tokens.
+
+Override layout and density by passing `class` to the root or individual slot components.
+Keep the projected input surface transparent so the composer shell remains the visible boundary.
+
+## Angular Notes
+
+- `textarea[ComposerInput]` remains a native textarea surface and autosizes without replacing native browser editing behavior.
+- `ComposerInput` is intentionally presentational. It is meant for custom editor projection, not as a built-in rich-text editor.
+- The composer shell is presentational and does not import layout or theme services, which keeps the entrypoint compatible with the library's component-layer rules.
+
+## Source Inspiration
+
+This component borrows the high-level idea of a structured prompt composer from Flux Composer, but the Angular API, slot names, styling tokens, keyboard behavior contract, and examples are implemented specifically for this library's shadcn-style component system.

package/component/context-menu/README.md

@@ -0,0 +1,268 @@
+# Context Menu
+
+Displays a menu of actions triggered by a right click. The Angular version maps the
+shadcn `ContextMenuTrigger` to a directive on any focusable host and reuses the
+shared menu primitives from [Dropdown Menu](../dropdown-menu/README.md) for the
+overlay content.
+
+## Import
+
+```ts
+import { ContextMenuTriggerDirective } from '@ojiepermana/angular/component/context-menu';
+import {
+  MenuCheckboxItemComponent,
+  MenuContentDirective,
+  MenuGroupComponent,
+  MenuItemComponent,
+  MenuLabelComponent,
+  MenuRadioGroupComponent,
+  MenuRadioItemComponent,
+  MenuSeparatorComponent,
+  MenuShortcutComponent,
+  MenuSurfaceComponent,
+  MenuTriggerDirective,
+} from '@ojiepermana/angular/component/dropdown-menu';
+```
+
+## Composition
+
+The Angular composition stays close to shadcn while exposing the root behavior
+through directives and shared menu primitives.
+
+```text
+div[ContextMenuTrigger]
+└── ng-template[MenuContent]
+    └── MenuSurface
+        ├── MenuGroup
+        │   └── button[MenuItem]
+        ├── MenuSeparator
+        ├── button[MenuCheckboxItem]
+        ├── MenuLabel
+        ├── MenuRadioGroup
+        │   └── button[MenuRadioItem]
+        └── button[MenuItem][MenuTrigger]
+            └── ng-template[MenuContent]
+                └── MenuSurface
+```
+
+## Basic usage
+
+Prefer a focusable trigger so pointer users can right-click and keyboard users can
+open the same menu with Shift+F10 or the context-menu key.
+
+```html
+<div
+  [ContextMenuTrigger]="menu"
+  tabindex="0"
+  aria-label="Open file actions"
+  class="flex h-32 w-full max-w-sm items-center justify-center rounded-xl border border-dashed border-border"
+>
+  Right-click here
+</div>
+
+<ng-template MenuContent #menu="MenuContent">
+  <MenuSurface class="w-56">
+    <MenuGroup>
+      <button MenuItem>Profile</button>
+      <button MenuItem>Billing</button>
+      <button MenuItem>Team</button>
+    </MenuGroup>
+  </MenuSurface>
+</ng-template>
+```
+
+## Common patterns
+
+### Browser-style actions
+
+Use grouped commands and shortcuts for browser or editor surfaces.
+
+```html
+<MenuSurface class="w-60">
+  <MenuGroup>
+    <button MenuItem>
+      Back
+      <span MenuShortcut>⌘[</span>
+    </button>
+    <button MenuItem [disabled]="true">
+      Forward
+      <span MenuShortcut>⌘]</span>
+    </button>
+    <button MenuItem>
+      Reload
+      <span MenuShortcut>⌘R</span>
+    </button>
+  </MenuGroup>
+</MenuSurface>
+```
+
+### Nested tools menu
+
+Map shadcn `ContextMenuSub` to `MenuTrigger` on a menu item. This keeps submenu
+composition explicit and works with the same overlay primitive used by dropdown menus.
+
+```html
+<ng-template MenuContent #moreTools="MenuContent">
+  <MenuSurface class="w-48">
+    <button MenuItem>Save Page...</button>
+    <button MenuItem>Create Shortcut...</button>
+    <button MenuItem>Name Window...</button>
+  </MenuSurface>
+</ng-template>
+
+<MenuSurface class="w-56">
+  <button MenuItem [MenuTrigger]="moreTools" side="right" align="start">
+    More tools
+    <span class="ml-auto text-xs text-muted-foreground">›</span>
+  </button>
+</MenuSurface>
+```
+
+### Checkbox rows
+
+Use checkbox rows for independent toggles such as browser preferences.
+
+```ts
+const showBookmarks = signal(true);
+const showFullUrls = signal(false);
+```
+
+```html
+<MenuSurface class="w-56">
+  <MenuGroup>
+    <button MenuCheckboxItem [(checked)]="showBookmarks">Show bookmarks</button>
+    <button MenuCheckboxItem [(checked)]="showFullUrls">Show full URLs</button>
+  </MenuGroup>
+</MenuSurface>
+```
+
+### Radio groups
+
+Use `MenuRadioGroup` when the menu exposes an exclusive choice.
+
+```ts
+const selectedTheme = signal<'light' | 'dark' | 'system'>('system');
+```
+
+```html
+<MenuSurface class="w-56">
+  <MenuLabel [inset]="true">Theme</MenuLabel>
+  <MenuRadioGroup [(value)]="selectedTheme">
+    <button MenuRadioItem value="light">Light</button>
+    <button MenuRadioItem value="dark">Dark</button>
+    <button MenuRadioItem value="system">System</button>
+  </MenuRadioGroup>
+</MenuSurface>
+```
+
+### Destructive rows
+
+Pass `variant="destructive"` when the row should read as irreversible.
+
+```html
+<MenuSurface class="w-56">
+  <MenuGroup>
+    <button MenuItem>Edit</button>
+    <button MenuItem>Share</button>
+  </MenuGroup>
+  <MenuSeparator />
+  <MenuGroup>
+    <button MenuItem variant="destructive">Delete</button>
+  </MenuGroup>
+</MenuSurface>
+```
+
+### RTL
+
+Set `dir="rtl"` on the surface and prefer `side="left"` for nested menus so the
+submenu opens toward the visual start edge.
+
+```html
+<ng-template MenuContent #rtlTools="MenuContent">
+  <MenuSurface dir="rtl" lang="ar" class="w-44 text-right">
+    <button MenuItem>حفظ الصفحة...</button>
+    <button MenuItem>إنشاء اختصار...</button>
+  </MenuSurface>
+</ng-template>
+
+<MenuSurface dir="rtl" lang="ar" class="w-56 text-right">
+  <button MenuItem [MenuTrigger]="rtlTools" side="left" align="start">
+    المزيد من الأدوات
+    <span class="mr-auto text-xs text-muted-foreground">‹</span>
+  </button>
+</MenuSurface>
+```
+
+## API reference
+
+### `[ContextMenuTrigger]`
+
+| Input                | Type                   | Default    |
+| -------------------- | ---------------------- | ---------- |
+| `ContextMenuTrigger` | `MenuContentDirective` | _required_ |
+| `disabled`           | `boolean`              | `false`    |
+
+Output: `openedChange: boolean`
+
+Methods:
+
+- `openAt(x, y)` opens the projected surface at the given viewport coordinates.
+- `close()` closes the active overlay.
+
+### Shared menu parts
+
+| Part                       | Purpose                                                                                  |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `MenuSurface`              | Overlay container with roving focus, typeahead, Escape close, and Tab-to-close behavior. |
+| `MenuGroup`                | Lightweight grouping wrapper for related rows.                                           |
+| `button[MenuItem]`         | Standard command row with optional `variant="destructive"`.                              |
+| `button[MenuCheckboxItem]` | Toggle row with `[(checked)]` and `role="menuitemcheckbox"`.                             |
+| `MenuRadioGroup`           | Exclusive-selection container with signal-friendly `[(value)]`.                          |
+| `button[MenuRadioItem]`    | Exclusive option row with `role="menuitemradio"`.                                        |
+| `MenuLabel`                | Non-interactive label row.                                                               |
+| `MenuShortcut`             | Right-aligned shortcut hint.                                                             |
+| `MenuSeparator`            | Visual divider between command groups.                                                   |
+
+For lower-level behavior details, see the Radix Context Menu API reference:
+<https://www.radix-ui.com/docs/primitives/components/context-menu#api-reference>.
+
+## Styling and theming
+
+Pass `class` to `MenuSurface`, `MenuGroup`, labels, and items to tune width,
+spacing, alignment, and emphasis. Destructive rows use the shared `destructive` theme
+tokens. Visible dividers and borders follow the shared border tokens rather than the
+current text color.
+
+## Accessibility
+
+- Make the trigger focusable if keyboard users need access to the menu.
+- Native `contextmenu` is captured and its default prevented.
+- Menu rows expose the expected `menuitem`, `menuitemcheckbox`, and `menuitemradio`
+  roles plus `aria-checked` and `aria-disabled` where appropriate.
+- Keep item labels short and descriptive, and avoid placing unrelated interactive
+  controls inside a menu row.
+
+## Keyboard interactions
+
+- Right click opens the menu at the pointer location.
+- Shift+F10 and the context-menu key open the menu at the trigger center when the
+  trigger is focusable.
+- Arrow Up and Arrow Down move between enabled items.
+- Home and End jump to the start or end of the list.
+- Typeahead matches row text.
+- Enter and Space activate the focused row.
+- Escape and Tab close the surface.
+
+## Angular notes
+
+- There is no dedicated `context-menu` root component. The root behavior lives on the
+  `[ContextMenuTrigger]` directive plus `ng-template[MenuContent]`.
+- Use signals with `[(checked)]` and `[(value)]` for checkbox and radio rows.
+- Reuse `MenuTrigger` when a submenu is needed.
+- Long-press support depends on the browser firing the native `contextmenu` event.
+
+## Source parity
+
+This implementation keeps the shadcn information architecture while mapping the trigger
+to Angular directives, submenu behavior to nested `MenuTrigger` composition, and
+checkbox or radio state to signal-friendly APIs.