@ojiepermana/angular 22.1.11 → 22.1.13

package/component/form/README.md

@@ -0,0 +1,216 @@
+# Form primitives
+
+The shadcn `Field` family maps to this entrypoint. Use it to compose labels,
+descriptions, grouped sections, separators, validation messages, and responsive
+field rows around the existing `input`, `textarea`, `select`, `checkbox`,
+`radio`, `switch`, and `button` primitives.
+
+## Import
+
+```ts
+import {
+  FormContentComponent,
+  FormControlDirective,
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormFieldsetComponent,
+  FormGroupComponent,
+  FormLabelComponent,
+  FormLegendComponent,
+  FormMessageComponent,
+  FormSeparatorComponent,
+  FormTitleComponent,
+  defaultFormErrorMessageResolver,
+  type FormErrorMessageResolver,
+} from '@ojiepermana/angular/component/form';
+```
+
+## Composition
+
+Use the primitives in these roles:
+
+| Upstream concept   | Local Angular surface                                                                           |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| `Field`            | `FormField`                                                                                     |
+| `FieldSet`         | `fieldset[FormFieldset]`                                                                        |
+| `FieldLegend`      | `legend[FormLegend]`                                                                            |
+| `FieldGroup`       | `FormGroup`                                                                                     |
+| `FieldContent`     | `FormContent`                                                                                   |
+| `FieldLabel`       | `label[FormLabel]` for native controls, `label[Label]` wrappers for checkbox/radio/switch cards |
+| `FieldTitle`       | `FormTitle`                                                                                     |
+| `FieldDescription` | `p[FormDescription]`                                                                            |
+| `FieldSeparator`   | `FormSeparator`                                                                                 |
+| `FieldError`       | `p[FormMessage]`                                                                                |
+
+## Basic Usage
+
+For native inputs and textareas, pair `label[FormLabel]` with
+`[FormControl]` so ids and helper text stay synchronized.
+
+```html
+<FormField>
+  <label FormLabel>Email</label>
+  <input Input FormControl type="email" placeholder="you@example.com" />
+  <p FormDescription>We'll only use this address for account updates.</p>
+  <p FormMessage>Enter a valid email address.</p>
+</FormField>
+```
+
+## Common Patterns
+
+### Grouped sections
+
+Use semantic fieldsets and legends when several controls belong to the same
+question or form section.
+
+```html
+<fieldset FormFieldset>
+  <legend FormLegend>Address information</legend>
+  <p FormDescription>We need your address to deliver your order.</p>
+
+  <FormGroup>
+    <FormField>
+      <label FormLabel>Street address</label>
+      <input Input FormControl placeholder="123 Main St" />
+    </FormField>
+
+    <div class="grid gap-4 sm:grid-cols-2">
+      <FormField>
+        <label FormLabel>City</label>
+        <input Input FormControl placeholder="New York" />
+      </FormField>
+
+      <FormField>
+        <label FormLabel>Postal code</label>
+        <input Input FormControl placeholder="10001" />
+      </FormField>
+    </div>
+  </FormGroup>
+</fieldset>
+```
+
+### Horizontal checkbox, radio, and switch rows
+
+For grouped controls, wrap the row in `label[Label]` so the entire card can
+toggle the control, then use `FormContent` for the title and helper copy.
+
+```html
+<label Label class="block rounded-xl border border-border p-4">
+  <FormField orientation="horizontal" class="gap-4">
+    <Checkbox [(ngModel)]="syncDesktop" aria-label="Sync Desktop and Documents folders" />
+    <FormContent>
+      <FormTitle>Sync Desktop & Documents folders</FormTitle>
+      <p FormDescription>Your Desktop & Documents folders are being synced with iCloud Drive.</p>
+    </FormContent>
+  </FormField>
+</label>
+```
+
+### Select rows
+
+Select keeps its own trigger and listbox behavior. Use `FormTitle` and
+`p[FormDescription]` around it instead of relying on a generated `for`
+relationship.
+
+```html
+<FormField>
+  <FormTitle>Department</FormTitle>
+  <SelectField aria-label="Department" class="block w-full" placeholder="Choose department">
+    <SelectItem value="engineering">Engineering</SelectItem>
+    <SelectItem value="design">Design</SelectItem>
+    <SelectItem value="marketing">Marketing</SelectItem>
+  </SelectField>
+  <p FormDescription>Select your department or area of work.</p>
+</FormField>
+```
+
+### Responsive layout
+
+Set `orientation="responsive"` on `FormField` when the label and content
+should stack on narrow widths and move into columns on wider screens.
+
+```html
+<FormField orientation="responsive">
+  <FormContent>
+    <label FormLabel>Display name</label>
+    <p FormDescription>Provide the public name shown in comments and invoices.</p>
+  </FormContent>
+  <input Input FormControl placeholder="Evil Rabbit" />
+</FormField>
+```
+
+### Validation and errors
+
+`[FormControl]` will reflect Angular form state automatically. For external
+validation flows or static examples, use the `invalid` input on
+`FormField`.
+
+Without projected text, `FormMessage` converts Angular's built-in validator
+keys into human-readable copy. Bind `[errorMessageResolver]` when a product
+needs custom wording while retaining the field's ARIA wiring.
+
+```html
+<FormField invalid>
+  <label FormLabel>Email</label>
+  <input Input FormControl type="email" aria-invalid="true" placeholder="name@example.com" />
+  <p FormMessage>Enter a valid email address.</p>
+</FormField>
+```
+
+## API Reference
+
+| Primitive                  | Selector                               | Inputs                            | Notes                                                                                  |
+| -------------------------- | -------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------------- |
+| `FormFieldComponent`       | `FormField`                            | `class`, `orientation`, `invalid` | Core field wrapper. `orientation` supports `vertical`, `horizontal`, and `responsive`. |
+| `FormFieldsetComponent`    | `FormFieldset, fieldset[FormFieldset]` | `class`                           | Semantic fieldset reset with spacing presets.                                          |
+| `FormLegendComponent`      | `FormLegend, legend[FormLegend]`       | `class`, `variant`                | Uses either standard legend sizing or label-sized copy.                                |
+| `FormGroupComponent`       | `FormGroup`                            | `class`                           | Stacks related fields and separators.                                                  |
+| `FormContentComponent`     | `FormContent`                          | `class`                           | Secondary text column for horizontal fields and card layouts.                          |
+| `FormLabelComponent`       | `FormLabel, label[FormLabel]`          | `class`                           | Visible label tied to the generated control id inside a field.                         |
+| `FormTitleComponent`       | `FormTitle`                            | `class`                           | Non-label heading for grouped controls.                                                |
+| `FormDescriptionComponent` | `FormDescription, p[FormDescription]`  | `class`                           | Helper text inside a field or at the fieldset level.                                   |
+| `FormSeparatorComponent`   | `FormSeparator`                        | `class`                           | Divider between stacked sections.                                                      |
+| `FormMessageComponent`     | `FormMessage, p[FormMessage]`          | `class`, `errorMessageResolver`   | Human-readable error text shown when the field is invalid.                             |
+| `FormControlDirective`     | `[FormControl]`                        | none                              | Auto-wires `id`, `aria-describedby`, and invalid state for native controls.            |
+
+## Styling and Theming
+
+- Field primitives use the same design tokens as the rest of the library:
+  `border-border`, `text-foreground`, `text-muted-foreground`, `ring-ring`,
+  and `text-destructive`.
+- Pass `class` to widen or tighten the layout around a specific field.
+- `FormSeparator` uses the border token rather than current text color so
+  dividers remain consistent across themes.
+
+## Accessibility
+
+- Prefer real `fieldset` and `legend` elements for grouped questions.
+- Keep native controls on `[FormControl]` when they need synchronized labels,
+  descriptions, and message ids.
+- Use `label[Label]` wrappers when the entire checkbox, radio, or switch row
+  should toggle the control.
+- `p[FormMessage]` emits `role="alert"` and `aria-live="polite"`.
+
+## Keyboard Interactions
+
+- Input and textarea fields preserve browser-native editing behavior.
+- Select, checkbox, radio, and switch rows keep the interaction model of their
+  own entrypoints.
+- Field wrappers add structure and semantics but do not create extra tab stops.
+
+## Angular Notes
+
+- `FormLabel` is best for native controls that participate in
+  `[FormControl]`.
+- Use `FormTitle` when the primary text is descriptive rather than a direct
+  form label.
+- The local `responsive` orientation uses breakpoint-based layout instead of the
+  upstream container-query API.
+
+## Source Parity
+
+This package is the durable Angular-first mapping for the shadcn `Field`
+documentation. It mirrors the same information architecture while staying
+honest about local differences: there is no dedicated `field` entrypoint, and
+grouped controls continue to use the runtime behavior of the existing input,
+textarea, select, checkbox, radio, switch, and button packages.

package/component/hover-card/README.md

@@ -0,0 +1,150 @@
+# Hover Card
+
+Preview additional context on hover or keyboard focus without forcing a full click-to-open interaction.
+
+The Angular hover card follows the shadcn composition model with a root container for shared defaults, a trigger directive on the interactive host, and a template-backed content surface rendered through the CDK overlay.
+
+## Import
+
+```ts
+import {
+  HoverCardComponent,
+  HoverCardContentDirective,
+  HoverCardTriggerDirective,
+} from '@ojiepermana/angular/component/hover-card';
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+```
+
+## Composition
+
+```text
+HoverCard
+├── [HoverCardTrigger]
+└── ng-template[HoverCardContent]
+```
+
+## Basic usage
+
+```html
+<HoverCard [openDelay]="100" [closeDelay]="150">
+  <button Button variant="link" [HoverCardTrigger]="profileCard">@nextjs</button>
+
+  <ng-template HoverCardContent #profileCard="HoverCardContent">
+    <div
+      class="flex w-72 flex-col gap-1 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md"
+    >
+      <div class="font-semibold">@nextjs</div>
+      <p class="text-sm text-muted-foreground">
+        The React Framework - created and maintained by @vercel.
+      </p>
+      <p class="text-xs text-muted-foreground">Joined December 2021</p>
+    </div>
+  </ng-template>
+</HoverCard>
+```
+
+## Common patterns
+
+### Trigger delays
+
+Use the root or trigger inputs to control when the preview opens and closes.
+
+```html
+<HoverCard [openDelay]="150" [closeDelay]="200">
+  <a href="/profiles/vercel" [HoverCardTrigger]="card">Hover profile</a>
+  <ng-template HoverCardContent #card="HoverCardContent">...</ng-template>
+</HoverCard>
+```
+
+### Positioning
+
+Set `side`, `align`, and `sideOffset` on the root for shared defaults or override them on an individual trigger.
+
+```html
+<HoverCard side="top" align="start" [sideOffset]="12">
+  <button Button variant="outline" [HoverCardTrigger]="card">Top start</button>
+  <ng-template HoverCardContent #card="HoverCardContent">...</ng-template>
+</HoverCard>
+```
+
+### Interactive content
+
+The overlay remains open while either the trigger or the rendered content is hovered or focused, so links and buttons inside the card remain usable.
+
+```html
+<HoverCard>
+  <a href="/products/headphones" [HoverCardTrigger]="productCard">Wireless Headphones</a>
+  <ng-template HoverCardContent #productCard="HoverCardContent">
+    <div
+      class="flex w-64 flex-col gap-3 rounded-lg border border-border bg-popover p-4 text-popover-foreground shadow-md"
+    >
+      <div>
+        <div class="font-semibold">Wireless Headphones</div>
+        <p class="text-sm text-muted-foreground">Noise cancelling with 30-hour battery life.</p>
+      </div>
+      <a Button href="/products/headphones" size="sm">View product</a>
+    </div>
+  </ng-template>
+</HoverCard>
+```
+
+## API reference
+
+### `HoverCardComponent`
+
+| Input        | Type                                     | Default    |
+| ------------ | ---------------------------------------- | ---------- |
+| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` |
+| `align`      | `'start' \| 'center' \| 'end'`           | `'center'` |
+| `sideOffset` | `number`                                 | `8`        |
+| `openDelay`  | `number`                                 | `100`      |
+| `closeDelay` | `number`                                 | `100`      |
+
+### `HoverCardTriggerDirective` (`[HoverCardTrigger]`)
+
+| Input              | Type                                     | Default             |
+| ------------------ | ---------------------------------------- | ------------------- |
+| `HoverCardTrigger` | `HoverCardContentDirective`              | -                   |
+| `side`             | `'top' \| 'right' \| 'bottom' \| 'left'` | Inherited from root |
+| `align`            | `'start' \| 'center' \| 'end'`           | Inherited from root |
+| `sideOffset`       | `number`                                 | Inherited from root |
+| `openDelay`        | `number`                                 | Inherited from root |
+| `closeDelay`       | `number`                                 | Inherited from root |
+| `disabled`         | `boolean`                                | `false`             |
+
+Exposes `isOpen()` and `openedChange`. The host reflects `data-state` (`"open"` or `"closed"`).
+
+### `HoverCardContentDirective`
+
+Use `ng-template[HoverCardContent]` with `exportAs="HoverCardContent"` to provide the overlay body.
+
+## Styling and theming
+
+The hover card does not force a panel shell. Apply width, border, background, radius, and elevation classes inside the projected template so the content can match compact profile cards, product previews, or custom dashboards.
+
+Use `border-border` for visible borders and `bg-popover text-popover-foreground` for the body shell to stay aligned with the theme tokens used across the library.
+
+## Accessibility
+
+- Open the card from a real interactive host such as `<button>`, `<a>`, or another focusable control.
+- The card opens on hover and keyboard focus, then remains available while the trigger or overlay content stays hovered or focused.
+- Press `Escape` while the trigger or overlay is focused to dismiss the preview.
+- Keep essential actions available outside the hover card as well; hover cards are best for supplemental context, not critical flows.
+
+## Keyboard interactions
+
+- `Tab` moves focus to the trigger and opens the card after the configured `openDelay`.
+- `Tab` continues into focusable content inside the overlay without forcing an immediate close.
+- `Shift+Tab` back to the trigger keeps the preview open.
+- `Escape` closes the preview.
+
+## Angular notes
+
+- The root `HoverCard` provides shared defaults. Override placement or timing on an individual trigger only when one example needs different behavior.
+- The content stays template-backed instead of adding a dedicated content component so the overlay body can remain fully custom.
+- Because the content renders through the CDK overlay container, set `dir` on the projected body when an individual card needs RTL behavior independent of the application shell.
+- If you need click-to-open behavior instead of hover and focus, use the Popover primitive instead.
+
+## Source parity
+
+This implementation preserves the shadcn structure, trigger delay inputs, side and alignment controls, and interactive hover path between trigger and content, while adapting the API to Angular selectors and CDK overlay primitives.

package/component/icon/README.md

@@ -0,0 +1,25 @@
+# Icon
+
+`@ojiepermana/angular/component/icon` menyediakan primitive icon berbasis Material Symbols untuk library UI ini.
+
+```ts
+import { IconComponent } from '@ojiepermana/angular/component/icon';
+import { provideUiTheme } from '@ojiepermana/angular/theme/styles';
+```
+
+```html
+<Icon name="dashboard" [size]="20" class="text-primary" />
+```
+
+## API Notes
+
+- `name` menerima nama glyph Material Symbols, misalnya `dashboard` atau `left_panel_close`.
+- `size` mengatur `font-size` dan `line-height` host dalam pixel.
+- `fill`, `weight`, `grade`, dan `opticalSize` diteruskan ke `font-variation-settings`.
+- `class` menerima utilitas Tailwind tambahan pada host.
+
+## Font Loading
+
+- `IconComponent` akan memastikan stylesheet Material Symbols tersedia saat icon pertama dirender.
+- `provideUiTheme()` juga mem-bootstrap stylesheet yang sama lebih awal pada level aplikasi.
+- Gunakan `provideUiTheme({ icons: { materialSymbols: false } })` bila consumer ingin menonaktifkan preload global.

package/component/input/README.md

@@ -0,0 +1,160 @@
+# Input
+
+Text input for forms and user data entry with shadcn-style visual states and Angular-friendly composition.
+
+The input itself stays a native `<input>` element. When the current shadcn docs mention `Field`, `FieldLabel`, or
+`FieldDescription`, the local Angular mapping is the existing form primitives rather than a separate runtime `Form`
+component.
+
+## Import
+
+For the simplest standalone field:
+
+```ts
+import { InputComponent } from '@ojiepermana/angular/component/input';
+import { LabelComponent } from '@ojiepermana/angular/component/label';
+```
+
+For the richer field composition used throughout the shadcn Input docs:
+
+```ts
+import {
+  FormControlDirective,
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormLabelComponent,
+  FormMessageComponent,
+} from '@ojiepermana/angular/component/form';
+import { InputComponent } from '@ojiepermana/angular/component/input';
+```
+
+## Usage
+
+### Standalone input
+
+```html
+<label Label for="email">Email</label>
+<input id="email" Input type="email" placeholder="you@example.com" />
+```
+
+### Field mapping
+
+Use the local form primitives when you need the label, helper text, and invalid-state wiring shown in the upstream
+shadcn examples:
+
+```html
+<FormField>
+  <FormLabel>Email</FormLabel>
+  <input Input FormControl type="email" placeholder="you@example.com" />
+  <FormDescription>We'll only use this address for account updates.</FormDescription>
+  <FormMessage>Enter a valid email address.</FormMessage>
+</FormField>
+```
+
+## Common Patterns
+
+### Reactive forms
+
+`Input` keeps Angular's standard `DefaultValueAccessor`, so reactive forms and `formControlName` work without a
+wrapper component.
+
+```ts
+readonly profileForm = new FormGroup({
+  email: new FormControl('', {
+    nonNullable: true,
+    validators: [Validators.required, Validators.email],
+  }),
+});
+```
+
+```html
+<FormField>
+  <FormLabel>Email</FormLabel>
+  <input Input FormControl formControlName="email" type="email" placeholder="john@example.com" />
+  <FormDescription>We'll never share your email with anyone.</FormDescription>
+  <FormMessage>Enter a valid email address.</FormMessage>
+</FormField>
+```
+
+### Invalid state without Angular forms
+
+If the field participates in a validation flow outside Angular forms, forward `aria-invalid="true"` manually.
+
+```html
+<input Input aria-invalid="true" placeholder="Error" />
+```
+
+### File input
+
+The same directive styles file inputs while preserving the browser-native file picker.
+
+```html
+<FormField>
+  <FormLabel>Picture</FormLabel>
+  <input Input FormControl type="file" />
+  <FormDescription>Select a picture to upload.</FormDescription>
+</FormField>
+```
+
+### Inline actions
+
+For search bars or quick actions, compose the input with `Button` instead of inventing a synthetic group API.
+
+```html
+<div class="flex max-w-md items-center gap-2">
+  <input Input type="search" placeholder="Search..." class="flex-1" />
+  <button Button type="button">Search</button>
+</div>
+```
+
+## API Reference
+
+### `InputComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+All native `<input>` attributes such as `type`, `placeholder`, `required`, `disabled`, `autocomplete`, and `value`
+continue to work as usual.
+
+### Field Mapping
+
+- `Field` maps to `FormField`.
+- `FieldLabel` maps to `FormLabel`.
+- `FieldDescription` maps to `FormDescription`.
+- Invalid and helper-text wiring come from `[FormControl]` plus `FormMessage`.
+
+## Styling and Theming
+
+Theme tokens used by the input styles include `--border`, `--input`, `--foreground`, `--muted-foreground`, `--ring`,
+and `--destructive`.
+
+When `aria-invalid="true"` is present, the border and focus ring switch to the destructive treatment. Pass `class`
+for layout utilities such as width, flex growth, or spacing around the native control.
+
+## Accessibility
+
+- Pair every input with a visible label or another accessible name source.
+- Use `FormControl` inside `FormField` when the control should auto-wire `id`, `aria-describedby`, and invalid
+  state.
+- Keep helper text and validation messages adjacent to the field so screen readers announce the full context.
+- Do not remove the focus ring; the component keeps a visible keyboard-only focus treatment.
+
+## Keyboard Interactions
+
+- The component preserves the browser-native keyboard behavior of the underlying input element.
+- File, search, email, password, and text variants continue to use the interactions defined by their native type.
+- Any adjacent action button, such as a search trigger, remains a separate Tab stop.
+
+## Angular Notes
+
+- `Input` is an attribute selector on the native `<input>` element.
+- It works with both `ngModel` and reactive forms because Angular still sees the underlying native control.
+- `FormControl` is optional; use it when the field participates in the local form-primitive composition.
+
+## Source Parity
+
+This Angular implementation follows the current shadcn Input information architecture while translating `Field` to the
+local form primitives. Upstream `Input Group` and `Button Group` examples are intentionally left to their own planned
+components instead of being faked inside the input API.