@frame-kit/ui-ng 0.0.1

package/ui/dialog/README.md

@@ -0,0 +1,222 @@
+# fk-dialog
+
+An accessible, token-driven dialog / modal component with focus management, scroll locking, and flexible close behavior.
+
+---
+
+## API
+
+### Inputs
+
+| Input              | Type                 | Default        | Description                                                                         |
+| ------------------ | -------------------- | -------------- | ----------------------------------------------------------------------------------- |
+| `open`             | `boolean`            | `false`        | Whether the dialog is open                                                          |
+| `modal`            | `boolean`            | `true`         | When `true`, locks body scroll while open                                           |
+| `closable`         | `boolean`            | `true`         | Whether the dialog shows close affordances (e.g. close button)                      |
+| `closeOnEscape`    | `boolean`            | `true`         | Close when Escape key is pressed                                                    |
+| `closeOnBackdrop`  | `boolean`            | `false`        | Close when clicking the backdrop                                                    |
+| `size`             | `DialogSize`         | `"md"`         | Size variant (`sm`, `md`, `lg`, `xl`, `fullscreen`)                                 |
+| `position`         | `DialogPosition`     | `"center"`     | Position of the dialog (`center`, `top`)                                            |
+| `header`           | `string \| null`     | `null`         | Default header text; used for `aria-labelledby` when no `ariaLabel` is set          |
+| `restoreFocus`     | `boolean`            | `true`         | Restore focus to the previously focused element on close                            |
+| `autoFocus`        | `boolean`            | `true`         | Auto-focus the dialog content on open                                               |
+| `animation`        | `DialogAnimation`    | `"scale-fade"` | Animation preset (`"none"`, `"scale-fade"`, `"fade"`, `"slide-up"`, `"slide-down"`) |
+| `preventClose`     | `boolean`            | `false`        | When `true`, disables closing entirely                                              |
+| `canClose`         | `CanCloseFn \| null` | `null`         | Optional guard function, sync or async, that must return `true` to allow close      |
+| `fullscreenMobile` | `boolean`            | `false`        | Expand to fullscreen on small viewports                                             |
+| `flexBody`         | `boolean`            | `false`        | Make the body a flex column container (for wizard/complex layouts)                  |
+| `className`        | `string`             | `''`           | Additional CSS classes for the host                                                 |
+| `id`               | `string \| null`     | `null`         | Optional ID for the host                                                            |
+| `ariaLabel`        | `string \| null`     | `null`         | ARIA label when no visible header is used                                           |
+| `ariaDescribedBy`  | `string \| null`     | `null`         | IDs of elements describing the dialog                                               |
+
+**`canClose` can be asynchronous.** Return a `boolean` or a `Promise<boolean>`; returning/resolving to `false` will keep the dialog open.
+
+### Outputs
+
+| Output        | Type      | Description                                    |
+| ------------- | --------- | ---------------------------------------------- |
+| `openChange`  | `boolean` | Emitted when the `open` state should change    |
+| `beforeOpen`  | `void`    | Emitted just before the dialog becomes visible |
+| `opened`      | `void`    | Emitted after the dialog is visible            |
+| `beforeClose` | `void`    | Emitted just before closing logic runs         |
+| `closed`      | `void`    | Emitted after the dialog has closed            |
+
+### Content Slots
+
+| Slot              | Selector            | Description                                                                   |
+| ----------------- | ------------------- | ----------------------------------------------------------------------------- |
+| **Default**       | (none)              | Dialog body content                                                           |
+| **Custom header** | `[fkDialogHeader]`  | Replaces the default header text. Close button is still rendered separately   |
+| **Footer**        | `[libDialogFooter]` | Pinned footer outside the scrollable body, with flex layout and border-top    |
+| **Actions**       | `[fkDialogActions]` | Inline action row inside the body (scrolls with content), equal-width buttons |
+
+---
+
+## Features
+
+- Portalled dialog with backdrop, scroll locking, and focus restoration
+- Configurable size, position, and animation
+- Guardable close behavior (`preventClose`, `canClose`)
+- Escape and backdrop handling
+- Default header via `header` input, or fully custom header via `[fkDialogHeader]` directive
+- Footer slot with built-in flex layout
+
+---
+
+## Quick Start
+
+```html
+<fk-dialog [open]="isOpen" header="Confirm deletion" (openChange)="isOpen = $event">
+  <p>Are you sure you want to delete this record?</p>
+  <div libDialogFooter>
+    <fk-button variant="secondary" (click)="isOpen = false">Cancel</fk-button>
+    <fk-button variant="primary" (click)="confirmDelete()">Delete</fk-button>
+  </div>
+</fk-dialog>
+```
+
+---
+
+## Import
+
+```ts
+import { DialogComponent, FkDialogHeaderDirective } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [DialogComponent, FkDialogHeaderDirective],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+> `FkDialogHeaderDirective` is only needed if you use a custom header.
+
+---
+
+## Selector
+
+```html
+<fk-dialog></fk-dialog>
+```
+
+---
+
+## Examples
+
+### Default header
+
+The `header` input renders centered text in the header area. When no `ariaLabel` is provided, the header text is linked via `aria-labelledby`.
+
+```html
+<fk-dialog [open]="isOpen" header="Edit record" (openChange)="isOpen = $event">
+  <!-- form fields -->
+</fk-dialog>
+```
+
+### Custom header
+
+Use the `[fkDialogHeader]` directive to project fully custom header content. The close button is still rendered separately when `closable` is `true`.
+
+```html
+<fk-dialog [open]="isOpen" (openChange)="isOpen = $event">
+  <div fkDialogHeader>
+    <fk-icon name="settings" size="sm"></fk-icon>
+    <span>Custom Title</span>
+  </div>
+
+  <p>Dialog body content here.</p>
+
+  <div libDialogFooter>
+    <fk-button variant="secondary" (click)="isOpen = false">Cancel</fk-button>
+    <fk-button variant="primary" (click)="save()">Save</fk-button>
+  </div>
+</fk-dialog>
+```
+
+> When using a custom header, the default `header` text input is ignored. Provide an `ariaLabel` for accessibility since `aria-labelledby` won't be set automatically.
+
+### With async `canClose`
+
+```ts
+canClose = async () => {
+  const confirmed = await this.confirmService.open('Unsaved changes, leave?');
+  return confirmed;
+};
+```
+
+```html
+<fk-dialog [open]="isEditing" header="Edit record" [canClose]="canClose" (openChange)="isEditing = $event">
+  <!-- form fields -->
+</fk-dialog>
+```
+
+### Fullscreen on mobile
+
+```html
+<fk-dialog [open]="isOpen" header="Filters" [fullscreenMobile]="true" (openChange)="isOpen = $event">
+  <!-- filter controls -->
+</fk-dialog>
+```
+
+---
+
+## Accessibility
+
+- Uses ARIA dialog patterns with `aria-modal` semantics when `modal` is `true`
+- Focus is trapped inside while open (via CDK `A11yModule`), and restored on close when `restoreFocus` is enabled
+- Title is announced via `aria-label` or `aria-labelledby` (`header` + internal title ID)
+- When using a custom header (`[fkDialogHeader]`), set `ariaLabel` explicitly since `aria-labelledby` is not automatically linked
+
+---
+
+## Design Tokens
+
+`fk-dialog` uses the following design tokens:
+
+```scss
+// Overlay
+--fk-dialog-overlay-bg
+--fk-dialog-overlay-z-index
+
+// Panel
+--fk-dialog-panel-bg
+--fk-dialog-panel-border-radius
+--fk-dialog-panel-shadow
+--fk-dialog-panel-max-height
+--fk-dialog-panel-margin
+--fk-dialog-width-sm
+--fk-dialog-width-md
+--fk-dialog-width-lg
+--fk-dialog-width-xl
+
+// Header
+--fk-dialog-header-padding
+--fk-dialog-header-padding-inline
+--fk-dialog-close-size
+--fk-dialog-close-color
+--fk-dialog-close-color-hover
+
+// Body
+--fk-dialog-body-padding
+
+// Footer
+--fk-dialog-footer-gap
+--fk-dialog-footer-padding
+--fk-dialog-footer-border
+```
+
+Override in your theme to align with your design system.
+
+---
+
+## Behavior Notes
+
+- When `modal` is `true`, body scroll is disabled only while at least one dialog is open.
+- `animation="none"` disables exit animations and hides the dialog immediately on close.
+- The header area renders when any of the following are true: a custom header is projected, the `header` input has a value, or `closable` is `true`.
+- `[libDialogFooter]` works with both declarative usage (`<fk-dialog>`) and imperative usage (`DialogService.open()`). The service runs change detection on the content component, then moves footer elements from the body to the panel root.
+- Footer children are flex-stretched to full width by default. Override with custom styles if needed.

package/ui/drawer/README.md

@@ -0,0 +1,274 @@
+# fk-drawer
+
+An accessible, token-driven slide-out drawer component with focus management, scroll locking, and flexible close behavior.
+
+---
+
+## API
+
+### DrawerComponent
+
+#### Inputs
+
+| Input             | Type                       | Default         | Description                                                                    |
+| ----------------- | -------------------------- | --------------- | ------------------------------------------------------------------------------ |
+| `open`            | `boolean`                  | `false`         | Whether the drawer is open                                                     |
+| `closable`        | `boolean`                  | `true`          | Whether the drawer shows a close button                                        |
+| `closeOnEscape`   | `boolean`                  | `true`          | Close when Escape key is pressed                                               |
+| `closeOnBackdrop` | `boolean`                  | `true`          | Close when clicking the backdrop overlay                                       |
+| `width`           | `DrawerWidth`              | `"md"`          | Width variant (`sm`, `md`, `lg`, `xl`)                                         |
+| `header`          | `string \| null`           | `null`          | Header text; used for `aria-labelledby` when no `ariaLabel` is set             |
+| `restoreFocus`    | `boolean`                  | `true`          | Restore focus to the previously focused element on close                       |
+| `autoFocus`       | `boolean`                  | `true`          | Auto-focus the drawer content on open                                          |
+| `animation`       | `DrawerAnimation`          | `"slide-right"` | Animation preset (`"slide-right"`, `"fade"`, `"none"`)                         |
+| `preventClose`    | `boolean`                  | `false`         | When `true`, disables closing entirely                                         |
+| `canClose`        | `DrawerCanCloseFn \| null` | `null`          | Optional guard function, sync or async, that must return `true` to allow close |
+| `className`       | `string`                   | `''`            | Additional CSS classes for the host                                            |
+| `id`              | `string \| null`           | `null`          | Optional ID for the host element                                               |
+| `ariaLabel`       | `string \| null`           | `null`          | ARIA label when no visible header is used                                      |
+
+**`canClose` can be asynchronous.** Return a `boolean` or a `Promise<boolean>`; returning/resolving to `false` will keep the drawer open.
+
+#### Outputs
+
+| Output        | Type      | Description                                    |
+| ------------- | --------- | ---------------------------------------------- |
+| `openChange`  | `boolean` | Emitted when the `open` state should change    |
+| `beforeOpen`  | `void`    | Emitted just before the drawer becomes visible |
+| `opened`      | `void`    | Emitted after the drawer is visible            |
+| `beforeClose` | `void`    | Emitted just before closing logic runs         |
+| `closed`      | `void`    | Emitted after the drawer has closed            |
+
+#### Content Slots
+
+| Slot        | Selector           | Description                                                                 |
+| ----------- | ------------------ | --------------------------------------------------------------------------- |
+| **Default** | (none)             | Drawer body content                                                         |
+| **Footer**  | `[fkDrawerFooter]` | Footer area, pinned to bottom with border-top separator. Hidden when empty. |
+
+### DrawerService
+
+| Method      | Signature                                                               | Description                                        |
+| ----------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| `open`      | `open<TResult, TData>(content: Type, config?: DrawerConfig): DrawerRef` | Imperatively opens a drawer with the given content |
+| `closeAll`  | `closeAll(): void`                                                      | Closes all open drawers                            |
+| `openCount` | `number` (getter)                                                       | Number of currently open drawers                   |
+
+### DrawerRef
+
+| Method / Property | Signature                                         | Description                              |
+| ----------------- | ------------------------------------------------- | ---------------------------------------- |
+| `close`           | `close(result?: TResult): Promise<void>`          | Close the drawer with an optional result |
+| `beforeOpen`      | `beforeOpen(): Observable<void>`                  | Emits before the drawer opens            |
+| `afterOpened`     | `afterOpened(): Observable<void>`                 | Emits after the drawer is open           |
+| `beforeClose`     | `beforeClose(): Observable<void>`                 | Emits before the drawer closes           |
+| `afterClosed`     | `afterClosed(): Observable<TResult \| undefined>` | Emits the result when the drawer closes  |
+| `data`            | `TData \| undefined` (getter)                     | Data passed via config                   |
+| `setCanClose`     | `setCanClose(guard: DrawerCanCloseFn \| null)`    | Set or clear the close guard at runtime  |
+| `config`          | `DrawerConfig<TData>`                             | The merged configuration object          |
+
+### DrawerConfig
+
+| Property          | Type               | Default         | Description                              |
+| ----------------- | ------------------ | --------------- | ---------------------------------------- |
+| `closable`        | `boolean`          | `true`          | Show close button                        |
+| `closeOnEscape`   | `boolean`          | `true`          | Close on Escape key                      |
+| `closeOnBackdrop` | `boolean`          | `true`          | Close on backdrop click                  |
+| `width`           | `DrawerWidth`      | `"md"`          | Width variant                            |
+| `animation`       | `DrawerAnimation`  | `"slide-right"` | Animation preset                         |
+| `header`          | `string \| null`   | `null`          | Header text                              |
+| `restoreFocus`    | `boolean`          | `true`          | Restore focus on close                   |
+| `autoFocus`       | `boolean`          | `true`          | Auto-focus on open                       |
+| `preventClose`    | `boolean`          | `false`         | Disable closing                          |
+| `canClose`        | `DrawerCanCloseFn` | —               | Close guard function                     |
+| `className`       | `string`           | `''`            | Additional CSS classes                   |
+| `ariaLabel`       | `string \| null`   | `null`          | ARIA label                               |
+| `data`            | `TData`            | —               | Arbitrary data for the content component |
+
+---
+
+## Features
+
+- Slide-out drawer panel with backdrop overlay and scroll locking
+- Configurable width and animation presets
+- Guardable close behavior (`preventClose`, `canClose`)
+- Escape and backdrop click handling
+- Focus trapping and restoration
+- Imperative API via `DrawerService` for dynamic content
+- Stacked drawer support with auto z-index management
+
+---
+
+## Quick Start
+
+### Imperative (via DrawerService)
+
+```ts
+import { DrawerService } from '@frame-kit/ui-ng';
+
+@Component({
+  /* ... */
+})
+export class MyComponent {
+  private readonly drawerService = inject(DrawerService);
+
+  openSettings() {
+    const ref = this.drawerService.open(SettingsPanelComponent, {
+      header: 'Settings',
+      width: 'lg',
+    });
+
+    ref.afterClosed().subscribe((result) => {
+      console.log('Drawer closed with:', result);
+    });
+  }
+}
+```
+
+### Declarative (template-driven)
+
+```html
+<fk-drawer [open]="isOpen" header="Filters" (openChange)="isOpen = $event">
+  <p>Filter controls here.</p>
+</fk-drawer>
+```
+
+---
+
+## Import
+
+```ts
+import { DrawerComponent, DrawerService } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [DrawerComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-drawer></fk-drawer>
+```
+
+---
+
+## Examples
+
+### Basic drawer
+
+```html
+<fk-drawer [open]="isOpen" header="Record details" (openChange)="isOpen = $event">
+  <!-- detail content -->
+</fk-drawer>
+```
+
+### Custom width
+
+```html
+<fk-drawer [open]="isOpen" header="Wide Panel" width="xl" (openChange)="isOpen = $event">
+  <!-- content -->
+</fk-drawer>
+```
+
+### With footer
+
+```html
+<fk-drawer [open]="isOpen" header="Edit User" (openChange)="isOpen = $event">
+  <!-- body content -->
+  <p>Form fields here…</p>
+
+  <!-- footer: pinned to bottom, separated by border -->
+  <div fkDrawerFooter>
+    <button>Save</button>
+    <button>Cancel</button>
+  </div>
+</fk-drawer>
+```
+
+### With close guard
+
+```ts
+canClose = async () => {
+  const confirmed = await this.confirmService.open('Unsaved changes, leave?');
+  return confirmed;
+};
+```
+
+```html
+<fk-drawer [open]="isEditing" header="Edit record" [canClose]="canClose" (openChange)="isEditing = $event">
+  <!-- form fields -->
+</fk-drawer>
+```
+
+---
+
+## Accessibility
+
+- Uses ARIA dialog pattern with `role="dialog"` and `aria-modal="true"`
+- Focus is trapped inside while open (via CDK `A11yModule`), and restored on close when `restoreFocus` is enabled
+- Title is announced via `aria-label` or `aria-labelledby` (`header` + internal title ID)
+- When no header is provided, set `ariaLabel` explicitly for screen reader accessibility
+
+---
+
+## Design Tokens
+
+`fk-drawer` uses the following design tokens:
+
+```scss
+// Overlay
+--fk-drawer-overlay-bg
+--fk-drawer-overlay-z-index
+
+// Panel
+--fk-drawer-bg
+--fk-drawer-border-color
+--fk-drawer-shadow
+--fk-drawer-width-sm
+--fk-drawer-width-md
+--fk-drawer-width-lg
+--fk-drawer-width-xl
+
+// Header
+--fk-drawer-header-padding
+--fk-drawer-header-border-color
+--fk-drawer-title-font-family
+--fk-drawer-title-font-size
+--fk-drawer-title-font-weight
+--fk-drawer-title-color
+
+// Close button
+--fk-drawer-close-size
+--fk-drawer-close-font-size
+--fk-drawer-close-color
+--fk-drawer-close-color-hover
+--fk-drawer-close-bg-hover
+--fk-drawer-close-radius
+--fk-drawer-close-focus-ring
+
+// Body
+--fk-drawer-body-padding
+
+// Footer
+--fk-drawer-footer-padding
+--fk-drawer-footer-border-color
+```
+
+Override in your theme to align with your design system.
+
+---
+
+## Behavior Notes
+
+- Body scroll is disabled while the drawer is open.
+- `animation="none"` disables exit animations and hides the drawer immediately on close.
+- The header area renders when any of the following are true: the `header` input has a value, or `closable` is `true`.
+- The `DrawerService` manages stacked drawers with incrementing z-index values to ensure proper layering.