@frame-kit/ui-ng 0.0.1

package/ui/accordion/README.md

@@ -0,0 +1,261 @@
+# fk-accordion
+
+A token-driven accordion/disclosure component for collapsible sections. A single-header trigger toggles a projected panel body.
+
+## API
+
+### Inputs
+
+| Input             | Type             | Default | Description                                                             |
+| ----------------- | ---------------- | ------- | ----------------------------------------------------------------------- |
+| `title`           | `string`         | `""`    | First line of the header — vertically centered with the leading icon.   |
+| `description`     | `string \| null` | `null`  | Optional second line rendered below the title.                          |
+| `leadingText`     | `string \| null` | `null`  | Optional label rendered immediately before the chevron (e.g. "Scopes"). |
+| `size`            | `AccordionSize`  | `"md"`  | `"sm"` or `"md"` — controls header padding and title font size.         |
+| `disabled`        | `boolean`        | `false` | Disables interaction and dims the entry.                                |
+| `defaultExpanded` | `boolean`        | `false` | When `true`, the accordion starts in the expanded state.                |
+| `className`       | `string`         | `""`    | Additional CSS classes merged onto the host.                            |
+| `id`              | `string \| null` | `null`  | Optional host id.                                                       |
+| `ariaLabel`       | `string \| null` | `null`  | Accessible label applied to the header button.                          |
+
+### Outputs
+
+| Output           | Type                    | Description                                         |
+| ---------------- | ----------------------- | --------------------------------------------------- |
+| `expandedChange` | `EventEmitter<boolean>` | Emits the new expanded state when the user toggles. |
+
+### Content
+
+Three projection targets:
+
+- **Default slot** — panel body (rendered only while expanded).
+- **`[fkAccordionLeadingIcon]`** — icon slot before the title/description stack.
+- **`[fkAccordionChevron]`** — replaces the default chevron SVG.
+
+```html
+<fk-accordion title="API key" description="Management API key" leadingText="Scopes">
+  <fk-icon fkAccordionLeadingIcon name="law-shield" size="md" />
+  <p>read:users, write:users</p>
+</fk-accordion>
+```
+
+## Features
+
+- Title + optional description, both vertically centered with the leading icon.
+- Optional leading-text label immediately before the chevron.
+- Built-in inline chevron SVG — no icon-library dependency.
+- Chevron rotates 180° (down → up) on expand.
+- Consumer may override the chevron via the `[fkAccordionChevron]` slot.
+- Panel body is content-projected and only mounted while expanded.
+- Fully token-driven — no brand styling in the component.
+
+## Quick Start
+
+```html
+<fk-accordion title="API key" description="Management API key">
+  <p>Panel content goes here.</p>
+</fk-accordion>
+```
+
+## Import
+
+```ts
+import { AccordionComponent, FkAccordionChevronDirective, FkAccordionLeadingIconDirective } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [AccordionComponent, FkAccordionChevronDirective, FkAccordionLeadingIconDirective],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+## Selector
+
+`fk-accordion`
+
+## Examples
+
+### Title only
+
+```html
+<fk-accordion title="API key"></fk-accordion>
+```
+
+### Title + description
+
+```html
+<fk-accordion title="API key" description="Management API key"></fk-accordion>
+```
+
+### With a leading icon
+
+```html
+<fk-accordion title="API key" description="Management API key">
+  <fk-icon fkAccordionLeadingIcon name="law-shield" size="md" />
+</fk-accordion>
+```
+
+### With a leading-text label (auth-summary "Scopes" pattern)
+
+```html
+<fk-accordion title="API key" description="Management API key" leadingText="Scopes">
+  <fk-icon fkAccordionLeadingIcon name="law-shield" size="md" />
+  <p>read:users, write:users</p>
+</fk-accordion>
+```
+
+### Custom chevron
+
+```html
+<fk-accordion title="API key">
+  <fk-icon fkAccordionChevron name="lock-password" size="sm" />
+</fk-accordion>
+```
+
+> Rotation of a custom chevron is the consumer's responsibility — style against the host class `fk-accordion--expanded` if needed.
+
+## Accessibility
+
+- The header is a native `<button type="button">`, keyboard-reachable and operable with `Enter` / `Space`.
+- `aria-expanded` tracks the current state.
+- `aria-controls` links the trigger to the panel; `aria-labelledby` on the panel links back to the trigger.
+- The panel uses `role="region"` only when expanded.
+- Leading icon and default chevron are marked `aria-hidden="true"` (decorative).
+- Disabled state sets the native `disabled` attribute on the trigger.
+
+## Design Tokens
+
+```scss
+--fk-accordion-color
+--fk-accordion-border-color
+--fk-accordion-border-width
+--fk-accordion-radius
+--fk-accordion-header-bg
+--fk-accordion-header-bg-hover
+--fk-accordion-header-bg-expanded
+--fk-accordion-header-padding-block
+--fk-accordion-header-padding-inline
+--fk-accordion-leading-icon-gap
+--fk-accordion-trailing-gap
+--fk-accordion-title-color
+--fk-accordion-title-font-size
+--fk-accordion-title-font-weight
+--fk-accordion-description-color
+--fk-accordion-description-font-size
+--fk-accordion-description-gap
+--fk-accordion-leading-text-color
+--fk-accordion-leading-text-font-size
+--fk-accordion-leading-text-font-weight
+--fk-accordion-leading-text-gap
+--fk-accordion-chevron-color
+--fk-accordion-panel-color
+--fk-accordion-panel-gap
+--fk-accordion-panel-padding-block
+--fk-accordion-panel-padding-inline
+--fk-accordion-focus-ring
+--fk-accordion-sm-header-padding-block
+--fk-accordion-sm-header-padding-inline
+--fk-accordion-sm-title-font-size
+--fk-accordion-sm-description-font-size
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-accordion-header-padding-inline: 1.25rem;
+  --fk-accordion-chevron-color: var(--fk-color-primary);
+}
+```
+
+## Behavior Notes
+
+- Internal `expanded` state — pass `defaultExpanded` for initial value; listen to `expandedChange` to observe user toggles.
+- The panel is **only mounted when expanded** — queries, event listeners, and child lifecycle hooks inside the panel fire on open.
+- Disabled accordions cannot toggle (neither via click nor keyboard) and are rendered at reduced opacity.
+
+---
+
+# fk-accordion-group
+
+A wrapper that enforces single-open behavior across a set of `<fk-accordion>` children. Opening one accordion auto-collapses the previously active one.
+
+## API
+
+### Inputs
+
+| Input       | Type     | Default | Description                         |
+| ----------- | -------- | ------- | ----------------------------------- |
+| `className` | `string` | `""`    | Additional CSS classes on the host. |
+
+### Outputs
+
+None.
+
+### Content
+
+Project any number of `<fk-accordion>` elements. Non-accordion content is allowed but only `<fk-accordion>` children participate in the single-open enforcement.
+
+## Features
+
+- Opening any accordion collapses whichever sibling was previously open.
+- Zero API change on the child: existing `<fk-accordion>` elements opt in just by being projected.
+- `defaultExpanded` still honored — if more than one child sets it, only the first wins; the rest are force-collapsed on mount.
+- Closing the active accordion leaves the group with nothing open.
+- Standard top-margin rhythm between children via `--fk-accordion-group-gap`.
+
+## Quick Start
+
+```html
+<fk-accordion-group>
+  <fk-accordion title="API key" description="Management API key">…</fk-accordion>
+  <fk-accordion title="Bearer token" description="Authorization header">…</fk-accordion>
+</fk-accordion-group>
+```
+
+## Import
+
+```ts
+import { AccordionComponent, AccordionGroupComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [AccordionGroupComponent, AccordionComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+## Selector
+
+`fk-accordion-group`
+
+## Accessibility
+
+- The group adds no extra landmark role — each child accordion retains its native `<button>` trigger, `aria-expanded`, and `aria-controls` wiring.
+- Single-open is enforced imperatively; assistive tech announces each accordion's individual state change.
+
+## Design Tokens
+
+```scss
+--fk-accordion-group-gap
+```
+
+Override:
+
+```scss
+:root {
+  --fk-accordion-group-gap: 0.5rem;
+}
+```
+
+## Behavior Notes
+
+- **Single-open**: exactly one (or zero) child accordion is expanded at any time.
+- **Groups are independent**: nesting groups is supported — each group has its own scoped coordinator.
+- **Accordions outside a group** behave normally — no coordination, any number may be open simultaneously.

package/ui/alert/README.md

@@ -0,0 +1,211 @@
+# fk-alert
+
+A token-driven alert component for displaying contextual messages such as info notices, success confirmations, warnings, and errors.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type             | Default  | Description                                                 |
+| ----------------- | ---------------- | -------- | ----------------------------------------------------------- |
+| `variant`         | `AlertVariant`   | `'info'` | Visual style: `'info'`, `'success'`, `'warning'`, `'error'` |
+| `color`           | `string \| null` | `null`   | Custom text color (inline override)                         |
+| `backgroundColor` | `string \| null` | `null`   | Custom background color (inline override)                   |
+| `borderColor`     | `string \| null` | `null`   | Custom border color (inline override)                       |
+| `className`       | `string`         | `''`     | Additional CSS classes merged onto the host element         |
+
+### Outputs
+
+None.
+
+### Content
+
+Alert text is provided through content projection. An optional leading icon can be projected using the `fkAlertIconStart` directive:
+
+```html
+<!-- Simple -->
+<fk-alert variant="info">Your changes have been saved.</fk-alert>
+
+<!-- With icon -->
+<fk-alert variant="warning">
+  <fk-icon fkAlertIconStart name="alert-triangle" />
+  Please review before continuing.
+</fk-alert>
+```
+
+---
+
+## Features
+
+- Four semantic variants: info, success, warning, error
+- Optional leading icon slot via `fkAlertIconStart` directive
+- Per-instance color, background, and border overrides
+- Token-driven styling
+- Self-sufficient rendering without any theme file loaded
+
+---
+
+## Quick Start
+
+```html
+<fk-alert variant="success">Operation completed successfully.</fk-alert>
+```
+
+---
+
+## Import
+
+```ts
+import { AlertComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [AlertComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+To use the icon directive:
+
+```ts
+import { AlertComponent, FkAlertIconStartDirective } from '@frame-kit/ui-ng';
+```
+
+---
+
+## Selector
+
+```html
+<fk-alert></fk-alert>
+```
+
+---
+
+## Examples
+
+### Info (default)
+
+```html
+<fk-alert>This is an informational message.</fk-alert>
+```
+
+### Success
+
+```html
+<fk-alert variant="success">Your changes have been saved.</fk-alert>
+```
+
+### Warning
+
+```html
+<fk-alert variant="warning">Please review before submitting.</fk-alert>
+```
+
+### Error
+
+```html
+<fk-alert variant="error">Something went wrong. Please try again.</fk-alert>
+```
+
+### With icon
+
+```html
+<fk-alert variant="error">
+  <fk-icon fkAlertIconStart name="x-circle" />
+  Failed to save changes.
+</fk-alert>
+```
+
+### Custom colors
+
+```html
+<fk-alert color="#1e3a5f" backgroundColor="#e8f4fd" borderColor="#b6e0fe"> Custom styled alert. </fk-alert>
+```
+
+---
+
+## Accessibility
+
+`fk-alert` renders an inline alert container.
+
+Accessibility behavior:
+
+- Icons projected via `fkAlertIconStart` are automatically marked `aria-hidden="true"`
+- Content is readable by screen readers
+- Semantic color contrast is maintained through token defaults
+
+---
+
+## Design Tokens
+
+`fk-alert` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-alert-padding
+--fk-alert-border-radius
+--fk-alert-font-size
+--fk-alert-icon-gap
+```
+
+### Variant tokens
+
+```
+--fk-alert-info-bg
+--fk-alert-info-border-color
+--fk-alert-info-color
+
+--fk-alert-success-bg
+--fk-alert-success-border-color
+--fk-alert-success-color
+
+--fk-alert-warning-bg
+--fk-alert-warning-border-color
+--fk-alert-warning-color
+
+--fk-alert-error-bg
+--fk-alert-error-border-color
+--fk-alert-error-color
+```
+
+### Shared tokens
+
+```
+--fk-rhythm-4
+--fk-radius-md
+--fk-typography-small-font-size
+```
+
+### Customizing Tokens
+
+Override tokens in your application's stylesheet:
+
+```scss
+:root {
+  --fk-alert-padding: 1.25rem;
+  --fk-alert-border-radius: 0.5rem;
+  --fk-alert-info-bg: #dbeafe;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.dark-theme fk-alert {
+  --fk-alert-info-bg: #1e3a5f;
+  --fk-alert-info-color: #93c5fd;
+}
+```
+
+---
+
+## Behavior Notes
+
+- The `color`, `backgroundColor`, and `borderColor` inputs apply inline styles, overriding token values for that instance
+- The `fkAlertIconStart` directive automatically sets `aria-hidden="true"` on the projected element

package/ui/avatar/README.md

@@ -0,0 +1,167 @@
+# fk-avatar
+
+A token-driven avatar atom that displays a user image with an initials fallback and an optional presence status indicator.
+
+---
+
+## API
+
+### Inputs
+
+| Input      | Type                                                        | Default | Description                                           |
+| ---------- | ----------------------------------------------------------- | ------- | ----------------------------------------------------- |
+| name       | `string`                                                    | —       | **Required.** User's display name                     |
+| avatarUrl  | `string` \| `null`                                          | `null`  | URL to the user's avatar image                        |
+| initials   | `string` \| `null`                                          | `null`  | Custom initials — auto-derived from `name` if absent  |
+| size       | `"sm"` \| `"md"` \| `"lg"`                                  | `"md"`  | Avatar diameter                                       |
+| status     | `"online"` \| `"offline"` \| `"away"` \| `"busy"` \| `null` | `null`  | Presence status                                       |
+| showStatus | `boolean`                                                   | `false` | Show the status indicator dot                         |
+| className  | `string`                                                    | `""`    | Additional CSS classes merged with hook classes       |
+| id         | `string` \| `null`                                          | `null`  | Sets the host `id` attribute                          |
+| ariaLabel  | `string` \| `null`                                          | `null`  | Custom `aria-label` (defaults to "Avatar for {name}") |
+
+---
+
+## Features
+
+- Displays an image when `avatarUrl` is provided, gracefully falling back to initials on load error
+- Auto-derives initials from `name` (first + last initial for multi-word names, first two characters for single names)
+- Status indicator dot positioned at the bottom-right corner, color-coded by status
+- Three size presets (`sm`, `md`, `lg`) controlled via tokens
+- Fully token-driven — all colors, sizes, typography, and radii are overridable
+
+---
+
+## Quick Start
+
+```html
+<fk-avatar name="Jane Doe" avatarUrl="/assets/jane.jpg" />
+```
+
+---
+
+## Import
+
+```ts
+import { AvatarComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-header',
+  imports: [AvatarComponent],
+  templateUrl: './header.component.html',
+})
+export class HeaderComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-avatar />
+```
+
+---
+
+## Examples
+
+### Initials Fallback
+
+```html
+<fk-avatar name="Jane Doe" />
+```
+
+Renders a circle with "JD" inside.
+
+### With Image
+
+```html
+<fk-avatar name="Jane Doe" avatarUrl="/assets/jane.jpg" />
+```
+
+### With Status Indicator
+
+```html
+<fk-avatar name="Jane Doe" [showStatus]="true" status="online" />
+```
+
+### Sizes
+
+```html
+<fk-avatar name="JD" size="sm" />
+<fk-avatar name="JD" size="md" />
+<fk-avatar name="JD" size="lg" />
+```
+
+### Custom Initials
+
+```html
+<fk-avatar name="Jane Doe" initials="J" />
+```
+
+---
+
+## Accessibility
+
+- Circle element has `role="img"` with an `aria-label` (defaults to "Avatar for {name}")
+- Status indicator has `role="status"` with an `aria-label` describing the status
+- Initials span is `aria-hidden="true"` since the circle's label already describes the user
+
+---
+
+## Design Tokens
+
+### Component Tokens
+
+```
+--fk-avatar-radius
+--fk-avatar-bg
+--fk-avatar-color
+--fk-avatar-font-family
+--fk-avatar-font-weight
+--fk-avatar-size-sm
+--fk-avatar-size-md
+--fk-avatar-size-lg
+--fk-avatar-font-size-sm
+--fk-avatar-font-size-md
+--fk-avatar-font-size-lg
+--fk-avatar-status-border
+--fk-avatar-status-online
+--fk-avatar-status-offline
+--fk-avatar-status-away
+--fk-avatar-status-busy
+```
+
+Each component token falls back to a semantic token, then a raw value. For example:
+
+```
+--fk-avatar-bg → --fk-color-surface-muted → #f7f9fb
+--fk-avatar-color → --fk-color-muted → #8a98a8
+--fk-avatar-radius → --fk-radius-full → 9999px
+--fk-avatar-status-online → --fk-color-success → #10b981
+--fk-avatar-status-busy → --fk-color-danger → #e02424
+```
+
+### Customizing Tokens
+
+Override tokens at any scope:
+
+```css
+:root {
+  --fk-avatar-bg: #e0e7ff;
+  --fk-avatar-color: #4338ca;
+  --fk-avatar-radius: 0.5rem;
+  --fk-avatar-size-md: 2.5rem;
+}
+```
+
+Or scope to a specific context:
+
+```css
+.compact-header fk-avatar {
+  --fk-avatar-size-md: 1.75rem;
+  --fk-avatar-font-size-md: 0.625rem;
+}
+```