@ojiepermana/angular 22.1.11 → 22.1.12

package/component/dropdown-menu/README.md

@@ -0,0 +1,336 @@
+# Dropdown Menu
+
+Accessible menu rendered in a CDK overlay with keyboard navigation (arrow keys,
+Home/End, type-ahead, Escape).
+
+This Angular implementation follows the shadcn Dropdown Menu information architecture while mapping the React root
+component to an explicit trigger directive and projected menu template.
+
+## Import
+
+```ts
+import {
+  MenuCheckboxItemComponent,
+  MenuTriggerDirective,
+  MenuContentDirective,
+  MenuGroupComponent,
+  MenuSurfaceComponent,
+  MenuItemComponent,
+  MenuRadioGroupComponent,
+  MenuRadioItemComponent,
+  MenuSeparatorComponent,
+  MenuLabelComponent,
+  MenuShortcutComponent,
+} from '@ojiepermana/angular/component/dropdown-menu';
+```
+
+## Usage
+
+```html
+<button
+  Button
+  type="button"
+  variant="outline"
+  #accountTrigger="MenuTrigger"
+  [MenuTrigger]="menu"
+  side="bottom"
+  align="end"
+>
+  Open
+</button>
+
+<ng-template MenuContent #menu="MenuContent">
+  <MenuSurface class="w-56">
+    <MenuGroup>
+      <MenuLabel>My account</MenuLabel>
+      <button MenuItem type="button" (selected)="onProfile()">
+        Profile
+        <span MenuShortcut>⌘P</span>
+      </button>
+      <button MenuItem type="button" (selected)="onSettings()">Settings</button>
+    </MenuGroup>
+    <MenuSeparator />
+    <MenuGroup>
+      <button MenuItem type="button" disabled>Disabled</button>
+      <button MenuItem type="button" variant="destructive" (selected)="onSignOut()">
+        Sign out
+      </button>
+    </MenuGroup>
+  </MenuSurface>
+</ng-template>
+```
+
+Use the trigger export when a standard command row should dismiss the overlay. Checkbox and radio rows can stay open so
+the user can adjust multiple settings in one pass.
+
+## Composition
+
+```text
+button[Button][MenuTrigger]
+└── ng-template[MenuContent]
+    └── MenuSurface
+        ├── MenuGroup
+        │   ├── MenuLabel
+        │   ├── button[MenuItem]
+        │   └── button[MenuItem][MenuTrigger]
+        │       └── ng-template[MenuContent]
+        │           └── MenuSurface
+        ├── MenuSeparator
+        ├── button[MenuCheckboxItem]
+        └── MenuRadioGroup
+            └── button[MenuRadioItem]
+```
+
+## Common patterns
+
+### Basic account menu
+
+```html
+<button Button type="button" variant="outline" #menuTrigger="MenuTrigger" [MenuTrigger]="menu">
+  Open
+</button>
+
+<ng-template MenuContent #menu="MenuContent">
+  <MenuSurface class="w-56">
+    <MenuGroup>
+      <MenuLabel>My Account</MenuLabel>
+      <button MenuItem type="button">Profile</button>
+      <button MenuItem type="button">Billing</button>
+      <button MenuItem type="button">Settings</button>
+    </MenuGroup>
+    <MenuSeparator />
+    <MenuGroup>
+      <button MenuItem type="button">GitHub</button>
+      <button MenuItem type="button">Support</button>
+      <button MenuItem type="button" [disabled]="true">API</button>
+    </MenuGroup>
+  </MenuSurface>
+</ng-template>
+```
+
+### Submenu
+
+Map shadcn `DropdownMenuSub` to `MenuTrigger` on a `button[MenuItem]`.
+
+```html
+<ng-template MenuContent #inviteUsersMenu="MenuContent">
+  <MenuSurface class="w-48">
+    <button MenuItem type="button">Email</button>
+    <button MenuItem type="button">Message</button>
+    <button MenuItem type="button">Calendar invite</button>
+  </MenuSurface>
+</ng-template>
+
+<MenuSurface class="w-56">
+  <MenuGroup>
+    <button MenuItem type="button">Team</button>
+    <button MenuItem type="button" [MenuTrigger]="inviteUsersMenu" side="right" align="start">
+      Invite users
+      <span class="ml-auto text-xs text-muted-foreground">›</span>
+    </button>
+  </MenuGroup>
+</MenuSurface>
+```
+
+### Checkboxes
+
+Use checkbox rows when the menu exposes independent toggles.
+
+```ts
+const showStatusBar = signal(true);
+const showActivityBar = signal(false);
+const showPanel = signal(false);
+```
+
+```html
+<MenuSurface class="w-44">
+  <MenuGroup>
+    <MenuLabel>Appearance</MenuLabel>
+    <button MenuCheckboxItem type="button" [(checked)]="showStatusBar">Status Bar</button>
+    <button MenuCheckboxItem type="button" [(checked)]="showActivityBar">Activity Bar</button>
+    <button MenuCheckboxItem type="button" [(checked)]="showPanel">Panel</button>
+  </MenuGroup>
+</MenuSurface>
+```
+
+### Radio group
+
+Use a radio group for one exclusive choice.
+
+```ts
+const panelPosition = signal<'top' | 'bottom' | 'right'>('bottom');
+```
+
+```html
+<MenuSurface class="w-44">
+  <MenuLabel [inset]="true">Panel Position</MenuLabel>
+  <MenuRadioGroup [(value)]="panelPosition">
+    <button MenuRadioItem type="button" value="top">Top</button>
+    <button MenuRadioItem type="button" value="bottom">Bottom</button>
+    <button MenuRadioItem type="button" value="right">Right</button>
+  </MenuRadioGroup>
+</MenuSurface>
+```
+
+### Shortcuts and icons
+
+Project shortcut text and inline icons directly into the row content.
+
+```html
+<MenuSurface class="w-56">
+  <button MenuItem type="button">
+    <svg aria-hidden="true" class="size-4" viewBox="0 0 24 24">...</svg>
+    Profile
+    <span MenuShortcut>⇧⌘P</span>
+  </button>
+  <button MenuItem type="button">
+    <svg aria-hidden="true" class="size-4" viewBox="0 0 24 24">...</svg>
+    Billing
+    <span MenuShortcut>⌘B</span>
+  </button>
+</MenuSurface>
+```
+
+### Avatar trigger composition
+
+Also import the avatar entrypoint when the trigger should be an account avatar.
+
+```ts
+import {
+  AvatarComponent,
+  AvatarFallbackComponent,
+  AvatarImageComponent,
+} from '@ojiepermana/angular/component/avatar';
+```
+
+```html
+<button
+  Button
+  type="button"
+  variant="ghost"
+  size="icon"
+  class="h-10 w-10 rounded-full p-0"
+  [MenuTrigger]="accountMenu"
+  align="end"
+>
+  <Avatar>
+    <AvatarImage src="https://github.com/shadcn.png" alt="Ada Lovelace" />
+    <AvatarFallback>AL</AvatarFallback>
+  </Avatar>
+</button>
+```
+
+### RTL
+
+Set `dir="rtl"` and `lang` on the surface, and prefer `side="left"` when nested content should open toward the visual
+start edge.
+
+```html
+<ng-template MenuContent #rtlAccountMenu="MenuContent">
+  <MenuSurface dir="rtl" lang="ar" class="w-44 text-right">
+    <button MenuItem type="button">الملف الشخصي</button>
+    <button MenuItem type="button">الفوترة</button>
+  </MenuSurface>
+</ng-template>
+
+<MenuSurface dir="rtl" lang="ar" class="w-56 text-right">
+  <button MenuItem type="button" [MenuTrigger]="rtlAccountMenu" side="left" align="start">
+    الحساب
+    <span class="mr-auto text-xs text-muted-foreground">‹</span>
+  </button>
+</MenuSurface>
+```
+
+## API
+
+### `[MenuTrigger]`
+
+| Input           | Type                                     | Default    |
+| --------------- | ---------------------------------------- | ---------- |
+| `MenuTrigger`   | `MenuContentDirective`                   | _required_ |
+| `side`          | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` |
+| `align`         | `'start' \| 'center' \| 'end'`           | `'start'`  |
+| `disabled`      | `boolean`                                | `false`    |
+| `closeOnSelect` | `boolean`                                | `true`     |
+
+Output: `openedChange: boolean`. Methods: `open()`, `close()`, `toggle()`.
+
+The trigger carries `aria-haspopup="menu"`, `aria-expanded`, and, while open,
+`aria-controls` pointing at the surface. Set `closeOnSelect` to `false` for a menu
+that stays open after a choice, for example a run of checkbox items.
+
+### `ng-template[MenuContent]`
+
+Projected template wrapper for the menu surface that is consumed by `[MenuTrigger]`.
+
+### `MenuSurface`
+
+Container with `role="menu"` and arrow key navigation wired through
+`FocusKeyManager` (wrapping + type-ahead). It carries `aria-labelledby` pointing
+back at the trigger.
+
+Keyboard behavior you get for free, no wiring required:
+
+- choosing an item closes the menu and returns focus to the trigger, unless the
+  trigger sets `closeOnSelect="false"`;
+- `Tab` closes the menu and continues the normal tab order from the trigger;
+- `Escape` closes the menu and returns focus to the trigger.
+
+`closeRequested` still fires on `Tab` for anyone already listening to it, but you
+no longer have to handle it.
+
+### `MenuItem`
+
+`role="menuitem"`. Inputs: `disabled`, `inset`, `class`. Output: `selected`.
+
+### `MenuCheckboxItem`
+
+`role="menuitemcheckbox"`. Inputs: `[(checked)]`, `disabled`, `variant`, `class`.
+
+### `MenuRadioGroup` and `MenuRadioItem`
+
+Use `[(value)]` on the group and `value` on each radio row. Radio items expose `role="menuitemradio"`.
+
+### Auxiliary
+
+- `MenuGroup` → structural wrapper with `role="group"`.
+- `MenuSeparator` → `role="separator"`.
+- `MenuLabel` — non-interactive label row.
+- `MenuShortcut` — right-aligned shortcut badge.
+
+## Styling and theming
+
+Pass `class` to the surface or individual rows to control width, spacing, and emphasis. Borders and separators use the
+shared theme border tokens, destructive rows use the destructive palette, and projected icons inherit the current text
+color.
+
+## Accessibility
+
+- Trigger: `aria-haspopup="menu"`, `aria-expanded` reflects state.
+- Surface: `role="menu"`, items receive `role="menuitem"`, disabled items get
+  `aria-disabled="true"`.
+- Checkbox and radio items expose `aria-checked` semantics through the relevant menuitem roles.
+- Close on outside click, Escape, or Tab. Focus returns to the trigger.
+
+## Keyboard interactions
+
+- Enter, Space, and ArrowDown on the trigger open the menu.
+- Arrow Up and Arrow Down move between enabled rows; Home and End jump to the first or last row.
+- Typing matches a row by its label text, skipping disabled rows. Space is not part of the search: it always activates the focused row, so a label is matched on its first word.
+- `ArrowLeft` in a submenu closes it and returns focus to the row that opened it. A root menu leaves the key alone, so a `Menubar` can use it to walk to the previous menu.
+- Enter and Space activate the focused row.
+
+## Angular notes
+
+- There is no React-style `DropdownMenu` root component; the root behavior is handled by `MenuTrigger` and
+  `ng-template[MenuContent]`.
+- Reuse `MenuTrigger` on `button[MenuItem]` when you need a submenu.
+- Standard command rows can dismiss the overlay explicitly through a `#menuTrigger="MenuTrigger"` template reference,
+  while checkbox and radio rows can stay open for multi-step preference changes.
+
+## Source parity
+
+This Angular entrypoint keeps the main shadcn dropdown-menu patterns: grouped commands, shortcuts, icons, nested menus,
+checkbox items, radio groups, avatar triggers, destructive rows, and RTL guidance. The shadcn page includes additional
+permutations such as checkbox-icons, radio-icons, and a very large complex menu; the local demos cover the same
+primitives through representative compositions instead of duplicating every permutation one-to-one.

package/component/editor/README.md

@@ -0,0 +1,152 @@
+# Editor
+
+Rich text editor shell with an accessible toolbar, configurable toolbar items, contenteditable form control support, and shadcn-style tokens.
+
+This component is conceptually inspired by Flux Editor. It does not bundle Tiptap or Flux JavaScript; instead, it provides a lightweight Angular primitive that applications can compose, bind, and extend.
+
+## Import
+
+```ts
+import { FormsModule } from '@angular/forms';
+import {
+  EditorButtonComponent,
+  EditorComponent,
+  EditorContentComponent,
+  EditorSeparatorComponent,
+  EditorSpacerComponent,
+  EditorToolbarComponent,
+} from '@ojiepermana/angular/component/editor';
+```
+
+## Usage
+
+```html
+<Editor>
+  <EditorToolbar items="heading | bold italic underline | align ~ undo redo" />
+  <EditorContent placeholder="Write something..." aria-label="Article body">
+    <h3>What's changed</h3>
+    <p>Draft release notes, article copy, or support responses here.</p>
+  </EditorContent>
+</Editor>
+```
+
+## Forms
+
+`EditorContent` implements `ControlValueAccessor`, so it can bind to Angular forms as an HTML string.
+
+```html
+<Editor>
+  <EditorToolbar />
+  <EditorContent [(ngModel)]="content" name="content" aria-label="Article body" />
+</Editor>
+```
+
+`EditorContent` sanitizes both values written into the control and edited HTML
+before emitting it. Applications can provide a stricter allow-list by overriding
+`EDITOR_HTML_SANITIZER`; sanitize again at any unrelated rendering boundary.
+
+```ts
+import { EDITOR_HTML_SANITIZER } from '@ojiepermana/angular/component/editor';
+
+const providers = [
+  {
+    provide: EDITOR_HTML_SANITIZER,
+    useValue: (html: string) => applicationAllowList.sanitize(html),
+  },
+];
+```
+
+## Toolbar Items
+
+The toolbar accepts a space-separated `items` string. Use `|` for a separator and `~` for a spacer.
+
+```html
+<EditorToolbar
+  items="heading | bold italic strike underline | bullet ordered blockquote link align ~ undo redo"
+/>
+```
+
+Supported item names:
+
+| Item          | Behavior                                             |
+| ------------- | ---------------------------------------------------- |
+| `heading`     | Text, heading 1, heading 2, and heading 3 selector.  |
+| `bold`        | Bold formatting.                                     |
+| `italic`      | Italic formatting.                                   |
+| `strike`      | Strikethrough formatting.                            |
+| `underline`   | Underline formatting.                                |
+| `bullet`      | Bulleted list.                                       |
+| `ordered`     | Numbered list.                                       |
+| `blockquote`  | Block quote block.                                   |
+| `subscript`   | Subscript formatting.                                |
+| `superscript` | Superscript formatting.                              |
+| `highlight`   | Highlight selected text.                             |
+| `link`        | Create a placeholder link for the current selection. |
+| `code`        | Code block.                                          |
+| `align`       | Left, center, and right alignment selector.          |
+| `undo`        | Undo last edit.                                      |
+| `redo`        | Redo last edit.                                      |
+
+## Custom Toolbar
+
+Pass `items=""` and project custom toolbar controls.
+
+```html
+<Editor>
+  <EditorToolbar items="">
+    <button EditorButton command="bold" aria-label="Bold">B</button>
+    <button EditorButton command="italic" aria-label="Italic">I</button>
+    <EditorSeparator />
+    <button EditorButton command="highlight" aria-label="Highlight">H</button>
+    <EditorSpacer />
+    <button EditorButton command="undo" aria-label="Undo">
+      <svg
+        aria-hidden="true"
+        class="size-4"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="1.75"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
+        <path d="M9 14 4 9l5-5" />
+        <path d="M4 9h10a6 6 0 0 1 0 12h-2" />
+      </svg>
+    </button>
+  </EditorToolbar>
+  <EditorContent aria-label="Custom editor" />
+</Editor>
+```
+
+## Keyboard Shortcuts
+
+| Action        | Shortcut          |
+| ------------- | ----------------- |
+| Bold          | Cmd/Ctrl+B        |
+| Italic        | Cmd/Ctrl+I        |
+| Underline     | Cmd/Ctrl+U        |
+| Strikethrough | Cmd/Ctrl+Shift+X  |
+| Ordered list  | Cmd/Ctrl+Shift+7  |
+| Bulleted list | Cmd/Ctrl+Shift+8  |
+| Heading 1-3   | Cmd/Ctrl+Alt+1..3 |
+| Undo          | Cmd/Ctrl+Z        |
+| Redo          | Cmd/Ctrl+Shift+Z  |
+
+## Styling
+
+The editor uses `border-input`, `bg-background`, `ring-ring`, `text-foreground`, `text-muted-foreground`, and `bg-muted` tokens. Pass sizing classes directly to the content slot when adjusting height.
+
+```html
+<Editor>
+  <EditorToolbar />
+  <EditorContent class="min-h-30 max-h-60" aria-label="Compact editor" />
+</Editor>
+```
+
+## Accessibility
+
+- `EditorToolbar` renders `role="toolbar"`.
+- `EditorContent` renders `role="textbox"` and `aria-multiline="true"`.
+- Provide a clear `aria-label` for each editor content surface.
+- Give terse or icon-only custom toolbar buttons an explicit `aria-label`.

package/component/empty/README.md

@@ -0,0 +1,193 @@
+# Empty
+
+Displays a reusable empty state with header, media, title, description, and content slots.
+
+Use Empty for onboarding gaps, no-results screens, no-notification panels, and 404-like recovery surfaces that need a clear next action.
+
+## Import
+
+```ts
+import {
+  EmptyComponent,
+  EmptyContentComponent,
+  EmptyDescriptionComponent,
+  EmptyHeaderComponent,
+  EmptyMediaComponent,
+  EmptyTitleComponent,
+} from '@ojiepermana/angular/component/empty';
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+```
+
+## Composition
+
+The Angular structure follows the shadcn Empty information architecture while keeping actions on native buttons and anchors.
+
+```text
+Empty
+├── EmptyHeader
+│   ├── EmptyMedia
+│   ├── EmptyTitle
+│   └── EmptyDescription
+└── EmptyContent
+```
+
+## Basic usage
+
+```html
+<Empty class="max-w-xl rounded-2xl border border-border bg-card/40">
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <svg
+        aria-hidden="true"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+      >
+        <path d="M12 6v12" />
+        <path d="M6 12h12" />
+      </svg>
+    </EmptyMedia>
+    <EmptyTitle>No projects yet</EmptyTitle>
+    <EmptyDescription>
+      You have not created any projects yet. Start by creating a new project or importing an
+      existing one.
+    </EmptyDescription>
+  </EmptyHeader>
+
+  <EmptyContent class="sm:flex-row">
+    <button Button type="button">Create project</button>
+    <button Button type="button" variant="outline">Import project</button>
+  </EmptyContent>
+
+  <a Button href="/docs/getting-started" variant="link" class="text-muted-foreground">Learn more</a>
+</Empty>
+```
+
+## Common patterns
+
+### Outline shell
+
+Use border utilities on the root when the empty state should read like an inset card or dashboard panel.
+
+```html
+<Empty class="rounded-2xl border border-dashed border-border">
+  <EmptyHeader>
+    <EmptyMedia variant="icon">...</EmptyMedia>
+    <EmptyTitle>Cloud storage empty</EmptyTitle>
+    <EmptyDescription>Upload files to your cloud storage to access them anywhere.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <button Button type="button" variant="outline" size="sm">Upload files</button>
+  </EmptyContent>
+</Empty>
+```
+
+### Avatar media
+
+Leave `EmptyMedia` on the default variant when projecting an avatar, avatar group, or any other custom artwork.
+
+```html
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia>
+      <Avatar class="size-12">
+        <AvatarImage src="https://github.com/shadcn.png" alt="shadcn" />
+        <AvatarFallback>CN</AvatarFallback>
+      </Avatar>
+    </EmptyMedia>
+    <EmptyTitle>User offline</EmptyTitle>
+    <EmptyDescription
+      >Leave a message and they will be notified when they come back online.</EmptyDescription
+    >
+  </EmptyHeader>
+  <EmptyContent>
+    <button Button type="button" size="sm">Leave message</button>
+  </EmptyContent>
+</Empty>
+```
+
+### Input group recovery
+
+Compose `EmptyContent` with the existing input-group primitives when the empty state should immediately guide recovery or search.
+
+```html
+<Empty class="max-w-xl rounded-2xl border border-border">
+  <EmptyHeader>
+    <EmptyTitle>404 - Not found</EmptyTitle>
+    <EmptyDescription>
+      The page you are looking for does not exist. Try searching for what you need below.
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent class="max-w-md">
+    <InputGroup class="w-full">
+      <input InputGroupInput aria-label="Search pages" placeholder="Try searching for pages..." />
+      <InputGroupAddon>
+        <span aria-hidden="true">⌕</span>
+      </InputGroupAddon>
+      <InputGroupAddon align="inline-end">
+        <span
+          aria-hidden="true"
+          class="inline-flex h-6 items-center rounded-md border border-border bg-background px-2 font-mono text-[11px] font-medium text-foreground shadow-sm"
+        >
+          /
+        </span>
+      </InputGroupAddon>
+    </InputGroup>
+  </EmptyContent>
+</Empty>
+```
+
+## API reference
+
+### `EmptyComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+### `EmptyMediaComponent`
+
+| Input     | Type                  | Default     |
+| --------- | --------------------- | ----------- |
+| `variant` | `'default' \| 'icon'` | `'default'` |
+| `class`   | `string`              | `''`        |
+
+### Parts
+
+- `EmptyHeader` centers the media, title, and description stack.
+- `EmptyTitle` provides the primary heading.
+- `EmptyDescription` renders supporting copy with muted foreground color.
+- `EmptyContent` groups actions, inputs, or recovery affordances under the header.
+
+All Empty parts also accept a `class` input.
+
+## Styling and theming
+
+The primitive keeps styling neutral by default: the root controls spacing and alignment, while visual shells such as borders, gradients, and muted backgrounds are layered through `class`.
+
+`EmptyMedia` uses `border-border` and `bg-muted/40` for the icon variant so the icon chip matches the rest of the theme without inheriting text color for borders.
+
+Use `class` on the root or parts to add panel borders, gradient backgrounds, tighter widths, or horizontal action layouts.
+
+## Accessibility
+
+- Keep the title and description visible so the empty state communicates both the missing content and the next step.
+- Put actions on native `<button>` or `<a Button>` hosts instead of faking interactivity with generic elements.
+- Mark decorative icons inside `EmptyMedia` as `aria-hidden="true"` unless the icon itself provides unique meaning.
+
+## Keyboard interactions
+
+- The Empty primitives themselves are passive layout containers and do not enter the tab order.
+- Projected buttons, anchors, and inputs keep their native Tab, Enter, and Space behavior.
+- When `EmptyContent` contains an input group, the control remains first in the DOM so tab order stays predictable.
+
+## Angular notes
+
+- `Empty` is a reusable content primitive, separate from application route-shell layout concerns.
+- The link action from the upstream shadcn preview maps cleanly to `<a Button variant="link">` in Angular.
+- Project any custom artwork into `EmptyMedia`; only the `icon` variant applies a circular icon shell.
+
+## Source parity
+
+This Angular implementation follows the shadcn Empty page structure, examples, and API reference while translating React composition to Angular selectors and keeping page-shell layout concerns separate from the reusable empty-state primitive.