@ojiepermana/angular 21.3.3 → 22.0.1

package/component/item/README.md

@@ -0,0 +1,247 @@
+# Item
+
+Displays a flexible content row with optional media, title, description, actions, header, and footer.
+
+Use Item when you need to present content such as profile summaries, settings rows, list links, media rows, or menu-like entries without introducing form-field semantics.
+
+## Import
+
+```ts
+import {
+  ItemActionsComponent,
+  ItemComponent,
+  ItemContentComponent,
+  ItemDescriptionComponent,
+  ItemFooterComponent,
+  ItemGroupComponent,
+  ItemHeaderComponent,
+  ItemMediaComponent,
+  ItemSeparatorComponent,
+  ItemTitleComponent,
+} from '@ojiepermana/angular/component/item';
+```
+
+## Usage
+
+Use `<ui-item>` for the default host element. When the row should behave like a native link or button, apply `[ui-item]` directly to the semantic host instead of relying on React-style `asChild` composition.
+
+```html
+<ui-item variant="outline">
+  <ui-item-media variant="icon">
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <path d="M12 5v14" />
+      <path d="M5 12h14" />
+    </svg>
+  </ui-item-media>
+
+  <ui-item-content>
+    <ui-item-title>Security alert</ui-item-title>
+    <ui-item-description>New login detected from an unknown device.</ui-item-description>
+  </ui-item-content>
+
+  <ui-item-actions>
+    <button ui-button variant="outline" size="sm" type="button">Review</button>
+  </ui-item-actions>
+</ui-item>
+```
+
+## Composition
+
+The Angular structure follows the shadcn Item information architecture while translating React-specific patterns to Angular selectors and semantic hosts.
+
+```text
+ItemGroup
+└── Item
+    ├── ItemHeader
+    ├── ItemMedia
+    ├── ItemContent
+    │   ├── ItemTitle
+    │   └── ItemDescription
+    ├── ItemActions
+    └── ItemFooter
+```
+
+## Common patterns
+
+### Variants
+
+Use `variant="outline"` for bordered rows, `variant="muted"` for low-emphasis containers, and the default variant when the item should blend into the surrounding surface.
+
+```html
+<div class="flex max-w-md flex-col gap-4">
+  <ui-item class="px-4 py-3">
+    <ui-item-content>
+      <ui-item-title>Default item</ui-item-title>
+      <ui-item-description>Transparent background with no border.</ui-item-description>
+    </ui-item-content>
+  </ui-item>
+
+  <ui-item variant="outline">
+    <ui-item-content>
+      <ui-item-title>Outline item</ui-item-title>
+      <ui-item-description>Bordered treatment for cards and settings rows.</ui-item-description>
+    </ui-item-content>
+  </ui-item>
+
+  <ui-item variant="muted">
+    <ui-item-content>
+      <ui-item-title>Muted item</ui-item-title>
+      <ui-item-description>Soft background for secondary content.</ui-item-description>
+    </ui-item-content>
+  </ui-item>
+</div>
+```
+
+### Media modes
+
+`ui-item-media` supports three common shadcn-style treatments.
+
+- Default media for avatars or custom projected content.
+- `variant="icon"` for compact icon chips.
+- `variant="image"` for fixed-size artwork or thumbnails.
+
+```html
+<ui-item variant="outline">
+  <ui-item-media>
+    <ui-avatar>
+      <ui-avatar-image src="https://github.com/shadcn.png" alt="@shadcn" />
+      <ui-avatar-fallback>CN</ui-avatar-fallback>
+    </ui-avatar>
+  </ui-item-media>
+
+  <ui-item-content>
+    <ui-item-title>shadcn</ui-item-title>
+    <ui-item-description>Example avatar content</ui-item-description>
+  </ui-item-content>
+</ui-item>
+```
+
+### Size
+
+Set `size` on the root item to scale title and description typography plus the icon and image media wrappers.
+
+```html
+<ui-item variant="outline" size="default">...</ui-item>
+<ui-item variant="outline" size="sm">...</ui-item>
+<ui-item variant="outline" size="xs">...</ui-item>
+```
+
+### Group with separators
+
+Use `ui-item-group` with `ui-item-separator` when you need a vertically stacked list of related rows.
+
+```html
+<ui-item-group class="max-w-sm gap-0 rounded-xl border border-border">
+  <ui-item class="px-4 py-3">
+    <ui-item-content>
+      <ui-item-title>shadcn</ui-item-title>
+      <ui-item-description>shadcn@vercel.com</ui-item-description>
+    </ui-item-content>
+  </ui-item>
+  <ui-item-separator />
+  <ui-item class="px-4 py-3">
+    <ui-item-content>
+      <ui-item-title>evilrabbit</ui-item-title>
+      <ui-item-description>evilrabbit@vercel.com</ui-item-description>
+    </ui-item-content>
+  </ui-item>
+</ui-item-group>
+```
+
+### Link host
+
+shadcn React uses `asChild` for anchors. In Angular, put `[ui-item]` on the anchor directly.
+
+```html
+<a ui-item href="/dashboard" variant="outline">
+  <ui-item-content>
+    <ui-item-title>Dashboard</ui-item-title>
+    <ui-item-description>Overview of your account and activity.</ui-item-description>
+  </ui-item-content>
+  <ui-item-actions>
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="size-4">
+      <path d="m9 18 6-6-6-6" />
+    </svg>
+  </ui-item-actions>
+</a>
+```
+
+### Dropdown composition
+
+The shadcn Item dropdown example maps cleanly to the local menu primitives. Render `ui-item` inside a `ui-menu-item` when you want denser menu rows.
+
+```html
+<button ui-button variant="outline" [uiMenuTrigger]="peopleMenu">Select person</button>
+
+<ng-template uiMenuContent #peopleMenu="uiMenuContent">
+  <ui-menu-surface class="w-64">
+    <ui-menu-label>People</ui-menu-label>
+    <ui-menu-separator />
+
+    <button ui-menu-item class="p-0">
+      <ui-item size="xs" class="w-full p-2">
+        <ui-item-content>
+          <ui-item-title>shadcn</ui-item-title>
+          <ui-item-description>shadcn@vercel.com</ui-item-description>
+        </ui-item-content>
+      </ui-item>
+    </button>
+  </ui-menu-surface>
+</ng-template>
+```
+
+## API reference
+
+### `ItemComponent`
+
+| Input     | Type                                | Default     |
+| --------- | ----------------------------------- | ----------- |
+| `variant` | `'default' \| 'outline' \| 'muted'` | `'default'` |
+| `size`    | `'default' \| 'sm' \| 'xs'`         | `'default'` |
+| `class`   | `string`                            | `''`        |
+
+### `ItemMediaComponent`
+
+| Input     | Type                             | Default     |
+| --------- | -------------------------------- | ----------- |
+| `variant` | `'default' \| 'icon' \| 'image'` | `'default'` |
+| `class`   | `string`                         | `''`        |
+
+### Parts
+
+- `ui-item-group` arranges related items in a vertical stack.
+- `ui-item-separator` renders a full-width divider line between grouped rows.
+- `ui-item-header` and `ui-item-footer` span the full width of the item.
+- `ui-item-actions` stays aligned to the trailing edge with logical spacing, so RTL layouts remain correct.
+
+## Styling and theming
+
+The outline variant uses `border-border` instead of inheriting border color from text, which keeps dividers and item shells consistent with the rest of the library theme.
+
+Pass `class` to the root or individual parts to tune spacing, borders, width, image treatment, or flex behavior. `ui-item-content` can be reused for secondary metadata by overriding it with classes such as `flex-none basis-auto items-end text-right`.
+
+Powered by `class-variance-authority`. Re-exports: `itemVariants`, `itemMediaVariants`, `ItemVariant`, `ItemSize`, `ItemMediaVariant`.
+
+## Accessibility
+
+- Use a semantic anchor or button host when the row is interactive.
+- Keep decorative icons and artwork `aria-hidden` or use empty `alt` text when nearby text already names the content.
+- Do not place nested interactive controls inside an interactive anchor host. When the row contains independent actions, keep the host non-interactive and place buttons inside `ui-item-actions`.
+
+## Keyboard interactions
+
+- Non-interactive items are not focusable.
+- Anchor and button hosts keep native Tab, Enter, and Space behavior.
+- Embedded controls inside `ui-item-actions` follow the natural DOM tab order.
+- When composed inside `ui-menu-item`, keyboard behavior comes from the menu primitives.
+
+## Angular notes
+
+- There is no `asChild` input in Angular. Use semantic hosts such as `<a ui-item>` or `<button ui-item>` directly.
+- `size` and `variant` are Angular `input()` values on the root item.
+- `ui-item-media` reads the parent item size automatically so icon and image wrappers stay in sync.
+- Use `Field` or the local form primitives when the row contains an actual form control such as a checkbox, radio, input, or select.
+
+## Source parity
+
+This Angular implementation follows the shadcn Item information architecture and examples while translating React `asChild` composition to semantic hosts and mapping the dropdown example to the existing Angular menu primitives.

package/component/kanban/README.md

@@ -0,0 +1,81 @@
+# Kanban
+
+Composable kanban board primitives inspired by Flux Kanban and implemented with local shadcn-style Angular patterns.
+
+## Import
+
+```ts
+import {
+  KanbanCardComponent,
+  KanbanCardFooterComponent,
+  KanbanCardHeaderComponent,
+  KanbanColumnActionsComponent,
+  KanbanColumnCardsComponent,
+  KanbanColumnComponent,
+  KanbanColumnFooterComponent,
+  KanbanColumnHeaderComponent,
+  KanbanComponent,
+} from '@ojiepermana/angular/component/kanban';
+```
+
+## Usage
+
+```html
+<ui-kanban>
+  <ui-kanban-column>
+    <ui-kanban-column-header heading="Planned" count="4" />
+    <ui-kanban-column-cards>
+      <ui-kanban-card heading="Update privacy policy in app" />
+      <button ui-kanban-card type="button" heading="Search suggestions are broken"></button>
+    </ui-kanban-column-cards>
+  </ui-kanban-column>
+</ui-kanban>
+```
+
+## Composition
+
+- `ui-kanban` owns horizontal board layout and column width variables.
+- `ui-kanban-column` frames one workflow stage.
+- `ui-kanban-column-header` accepts `heading`, `subheading`, `count`, and `badge` inputs.
+- `ui-kanban-column-actions` projects action buttons into the column header.
+- `ui-kanban-column-cards` contains cards and handles vertical scrolling.
+- `ui-kanban-column-footer` is for add-card forms or secondary actions.
+- `ui-kanban-card` renders a static card; use `button[ui-kanban-card]` or `a[ui-kanban-card]` for clickable cards.
+- `ui-kanban-card-header` and `ui-kanban-card-footer` project tags, metadata, avatars, or actions into a card.
+
+## Inputs
+
+### KanbanComponent
+
+| Input         | Type                        | Default     | Description                               |
+| ------------- | --------------------------- | ----------- | ----------------------------------------- |
+| `columnWidth` | `'sm' \| 'default' \| 'lg'` | `'default'` | Sets the board column width CSS variable. |
+| `dense`       | `boolean`                   | `false`     | Reduces column and card gaps.             |
+| `class`       | `string`                    | `''`        | Additional host classes.                  |
+
+### KanbanColumnHeaderComponent
+
+| Input        | Type                       | Default | Description                                   |
+| ------------ | -------------------------- | ------- | --------------------------------------------- |
+| `heading`    | `string`                   | `''`    | Primary column title.                         |
+| `subheading` | `string`                   | `''`    | Secondary column text.                        |
+| `count`      | `string \| number \| null` | `null`  | Optional card count shown beside the heading. |
+| `badge`      | `string`                   | `''`    | Optional badge text shown beside the heading. |
+| `class`      | `string`                   | `''`    | Additional host classes.                      |
+
+### KanbanCardComponent
+
+| Input      | Type      | Default | Description                                        |
+| ---------- | --------- | ------- | -------------------------------------------------- |
+| `heading`  | `string`  | `''`    | Default card title when no custom body is needed.  |
+| `selected` | `boolean` | `false` | Marks a card as selected/current.                  |
+| `disabled` | `boolean` | `false` | Disables interaction and applies disabled styling. |
+| `class`    | `string`  | `''`    | Additional host classes.                           |
+
+## Accessibility
+
+- Use `button[ui-kanban-card]` for cards that trigger an action.
+- Provide `type="button"` on button cards inside forms.
+- Keep card titles visible and descriptive.
+- Give icon-only column actions an `aria-label`.
+- Preserve DOM order to match the workflow order announced to assistive technology.

package/component/kanban/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../../fesm2022/ojiepermana-angular-component-kanban.mjs",
+  "typings": "../../types/ojiepermana-angular-component-kanban.d.ts"
+}

package/component/kbd/README.md

@@ -0,0 +1,139 @@
+# Kbd
+
+Keyboard key primitive for shortcuts, inline command hints, and compact keycap groups.
+
+Use Kbd when the UI needs to display the key or shortcut that triggers an action, not to capture keyboard input itself.
+
+## Import
+
+```ts
+import { KbdComponent, KbdGroupComponent } from '@ojiepermana/angular/component/kbd';
+```
+
+## Composition
+
+The Angular structure mirrors shadcn's `Kbd` and `KbdGroup` composition while keeping the host choice flexible.
+
+```text
+kbd[ui-kbd] or ui-kbd
+ui-kbd-group or [ui-kbd-group]
+├── kbd[ui-kbd] or ui-kbd
+└── kbd[ui-kbd] or ui-kbd
+```
+
+## Basic usage
+
+Prefer a native `<kbd>` host when you want built-in keyboard-input semantics in the DOM.
+
+```html
+<p class="inline-flex items-center gap-2 text-sm text-muted-foreground">
+  Press <kbd ui-kbd>Ctrl</kbd> <kbd ui-kbd>K</kbd> to open search.
+</p>
+```
+
+## Common patterns
+
+### Key groups
+
+Use `ui-kbd-group` when several keycaps should read as one shortcut cluster or one family of related commands.
+
+```html
+<ui-kbd-group>
+  <kbd ui-kbd>Ctrl + B</kbd>
+  <kbd ui-kbd>Ctrl + K</kbd>
+</ui-kbd-group>
+```
+
+### Button companion
+
+Use Kbd inside the button label when the shortcut is part of the visible affordance.
+
+```html
+<button ui-button type="button" variant="outline">
+  Accept
+  <kbd ui-kbd class="translate-x-0.5">⏎</kbd>
+</button>
+```
+
+### Input group shortcut hint
+
+Pair Kbd with the existing input-group primitives for launcher shortcuts and command-palette patterns.
+
+```html
+<ui-input-group class="max-w-sm">
+  <input ui-input-group-input placeholder="Search..." />
+  <ui-input-group-addon>
+    <span aria-hidden="true">⌕</span>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <ui-kbd-group>
+      <kbd ui-kbd>⌘</kbd>
+      <kbd ui-kbd>K</kbd>
+    </ui-kbd-group>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Tooltip mapping
+
+The local tooltip primitive is a thin string-based wrapper around `matTooltip`, so rich tooltip content with embedded Kbd chips maps to plain tooltip text plus optional visible shortcut chips in adjacent markup.
+
+```html
+<button ui-button type="button" variant="outline" [uiTooltip]="'Save changes (S)'">Save</button>
+<button ui-button type="button" variant="outline" [uiTooltip]="'Print document (Ctrl + P)'">Print</button>
+```
+
+### RTL
+
+Set `dir="rtl"` on an ancestor container when the shortcut rows live in a right-to-left layout.
+
+```html
+<div dir="rtl" lang="ar" class="flex flex-col items-center gap-4">
+  <ui-kbd-group>
+    <kbd ui-kbd>⌘</kbd>
+    <kbd ui-kbd>⇧</kbd>
+    <kbd ui-kbd>⌥</kbd>
+    <kbd ui-kbd>⌃</kbd>
+  </ui-kbd-group>
+
+  <ui-kbd-group>
+    <kbd ui-kbd>Ctrl</kbd>
+    <span aria-hidden="true">+</span>
+    <kbd ui-kbd>B</kbd>
+  </ui-kbd-group>
+</div>
+```
+
+## API reference
+
+| Primitive           | Input   | Type     | Default | Notes                                         |
+| ------------------- | ------- | -------- | ------- | --------------------------------------------- |
+| `KbdComponent`      | `class` | `string` | `''`    | Extra Tailwind classes merged onto the keycap |
+| `KbdGroupComponent` | `class` | `string` | `''`    | Extra Tailwind classes merged onto the group  |
+
+## Styling and theming
+
+`ui-kbd` uses `border-border`, `bg-background`, `text-foreground`, and the shared `rounded-md` radius token so it stays aligned with buttons, inputs, and tooltip surfaces.
+
+The default typography is mono, compact, and non-selectable to match shadcn's keycap treatment without introducing a separate icon or badge variant system.
+
+## Accessibility
+
+- Prefer `<kbd ui-kbd>` when you want native keyboard-input semantics in the markup.
+- Keep decorative separators such as `+` or `/` `aria-hidden` when the surrounding sentence already communicates the shortcut clearly.
+- Kbd is presentational. The actionable control still needs the accessible name, tooltip text, and focus behavior.
+
+## Keyboard interactions
+
+Kbd and KbdGroup do not add keyboard behavior. Buttons, links, inputs, tooltip triggers, and menu items composed with them keep their native keyboard model.
+
+## Angular notes
+
+- There is no React-style `data-icon="inline-end"` API. Use the normal `class` input for spacing or alignment adjustments.
+- Import neighboring primitives such as Button, Input Group, or Tooltip separately. The Kbd entrypoint stays intentionally focused.
+
+## Source parity
+
+This Angular slice covers the shadcn Kbd preview, grouped keycaps, button companion usage, input-group shortcut hints, RTL examples, and API/accessibility guidance.
+
+The upstream tooltip example uses rich tooltip content with embedded keycaps. In this repo that maps to the existing string-based tooltip directive, so the shortcut lives in the tooltip message instead of projected tooltip markup.

package/component/kbd/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../../fesm2022/ojiepermana-angular-component-kbd.mjs",
+  "typings": "../../types/ojiepermana-angular-component-kbd.d.ts"
+}

package/component/label/README.md

@@ -0,0 +1,136 @@
+# Label
+
+Renders accessible labels for native form controls and provides the wrapper-label pattern for checkbox, radio, and switch rows where the entire copy block should toggle the control.
+
+Use `ui-label` when a lightweight visible label is enough. For richer form-field layouts with descriptions, grouped sections, and generated id wiring, use the `form` entrypoint and `label[ui-form-label]` instead.
+
+## Import
+
+```ts
+import { LabelComponent } from '@ojiepermana/angular/component/label';
+```
+
+## Composition
+
+The label primitive supports three common structures:
+
+```text
+ui-label[for] + native control[id]
+label[ui-label] + native control[id]
+label[ui-label]
+├── ui-checkbox | ui-radio | ui-switch
+└── descriptive copy
+```
+
+For full form-field composition, map the shadcn `Field` guidance to `ui-form-field`, `label[ui-form-label]`, and `[uiFormControl]` from `@ojiepermana/angular/component/form`.
+
+## Basic usage
+
+Use `for` when the target control exposes a stable native `id`, such as an input or textarea.
+
+```html
+<div class="grid gap-2">
+  <ui-label for="email">Email address</ui-label>
+  <input ui-input id="email" type="email" placeholder="you@example.com" />
+</div>
+```
+
+You can also decorate a native label host when that fits the surrounding markup more naturally.
+
+```html
+<label ui-label for="email">Email address</label>
+<input ui-input id="email" type="email" placeholder="you@example.com" />
+```
+
+## Common patterns
+
+### Checkbox, radio, and switch rows
+
+When the entire row should toggle the control, wrap the control and copy in `label[ui-label]`. This is the closest Angular equivalent to the upstream shadcn checkbox-plus-label preview.
+
+```html
+<label ui-label class="inline-flex max-w-md items-start gap-3 rounded-xl border border-border p-4">
+  <ui-checkbox class="mt-0.5" />
+  <span class="grid gap-1 leading-none">
+    <span>Email me product updates</span>
+    <span class="text-sm font-normal leading-5 text-muted-foreground">
+      Wrap checkbox, radio, and switch rows in label[ui-label] when the whole row should toggle the control.
+    </span>
+  </span>
+</label>
+```
+
+### Label in Field
+
+The shadcn docs route richer field composition to `Field`. In this library, use the `form` entrypoint instead.
+
+```html
+<ui-form-field class="max-w-md">
+  <label ui-form-label>Email address</label>
+  <input ui-input uiFormControl type="email" placeholder="you@example.com" />
+  <p ui-form-description>We will only use this address for account updates.</p>
+</ui-form-field>
+```
+
+`label[ui-form-label]` automatically targets the generated control id from `[uiFormControl]`, so helper text and invalid state remain synchronized without manual `for` wiring.
+
+### RTL
+
+The label primitive is direction-agnostic. Apply `dir="rtl"` on a wrapper and reverse the row layout when the label and control should read from right to left.
+
+```html
+<div dir="rtl" lang="ar" class="max-w-md text-right">
+  <label ui-label class="flex flex-row-reverse items-start gap-3">
+    <ui-checkbox class="mt-0.5" />
+    <span class="grid gap-1 leading-none">
+      <span>قبول الشروط والأحكام</span>
+      <span class="text-sm font-normal leading-5 text-muted-foreground">
+        يظل نمط التسمية نفسه، فقط ضع الصف داخل حاوية تدعم الاتجاه من اليمين إلى اليسار.
+      </span>
+    </span>
+  </label>
+</div>
+```
+
+## API reference
+
+### `LabelComponent`
+
+| Input   | Type             | Default |
+| ------- | ---------------- | ------- |
+| `for`   | `string \| null` | `null`  |
+| `class` | `string`         | `''`    |
+
+Selectors: `ui-label`, `label[ui-label]`
+
+Related mapping: for shadcn `FieldLabel`, use `label[ui-form-label]` from `@ojiepermana/angular/component/form`.
+
+## Styling and theming
+
+Base classes: `text-sm font-medium leading-none text-foreground`.
+
+- Pass `class` to tune spacing, layout, or typography for a specific label row.
+- `peer-disabled:cursor-not-allowed peer-disabled:opacity-70` dims the label when a peer-marked control is disabled.
+- Standard library theme tokens such as `text-foreground`, `text-muted-foreground`, `border-border`, and spacing utilities compose cleanly with the label host.
+
+## Accessibility
+
+- Set `for` only when the target control exposes a real native id.
+- Wrap checkbox, radio, and switch rows in `label[ui-label]` instead of relying on `for` to reach an internal input element.
+- Inside `ui-form-field`, prefer `label[ui-form-label]` so helper text and invalid state stay synchronized with `[uiFormControl]`.
+- Keep label text specific so screen readers and voice-control software announce useful control names.
+
+## Keyboard interactions
+
+- Labels themselves are not the main keyboard target; focus moves to the associated control in normal tab order.
+- Once the control has focus, keyboard behavior belongs to that control, such as `Space` toggling a checkbox.
+
+## Angular notes
+
+- Use `ui-label` or `label[ui-label]` for lightweight labeling only.
+- Use the `form` entrypoint when the surface also needs descriptions, errors, grouped sections, or generated `for` wiring.
+- The checkbox, radio, and switch families work best with wrapper labels because those controls own their internal focusable element.
+
+## Source parity
+
+This Angular slice keeps the shadcn Label guidance around installation, usage, field composition, RTL behavior, and API shape while mapping the upstream `Field` recommendation to the local `form` entrypoint and expressing checkbox-like examples with a wrapper-label pattern that fits the existing Angular primitives.