@frame-kit/ui-ng 0.0.1

package/ui/menu-item/README.md

@@ -0,0 +1,204 @@
+# fk-menu-item / fk-menu-separator
+
+Atom-level menu primitives for rendering actionable items and visual dividers inside menu-like containers such as `fk-dropdown-menu`.
+
+---
+
+## API
+
+### fk-menu-item
+
+#### Inputs
+
+| Input      | Type             | Default | Description                               |
+| ---------- | ---------------- | ------- | ----------------------------------------- |
+| `icon`     | `string \| null` | `null`  | Optional icon name shown before the label |
+| `danger`   | `boolean`        | `false` | Applies destructive/danger styling        |
+| `disabled` | `boolean`        | `false` | Disables the item                         |
+
+#### Outputs
+
+| Output      | Type   | Description                        |
+| ----------- | ------ | ---------------------------------- |
+| `itemClick` | `void` | Emitted when the item is activated |
+
+#### Content
+
+The item label is provided through content projection.
+
+```html
+<fk-menu-item>Save Changes</fk-menu-item>
+```
+
+### fk-menu-separator
+
+A visual divider between menu item groups. No inputs or outputs.
+
+```html
+<fk-menu-separator />
+```
+
+---
+
+## Features
+
+- Icon + label layout with flexible content projection
+- Danger variant for destructive actions
+- Disabled state with `aria-disabled` and keyboard exclusion
+- Keyboard activation via Enter and Space
+- Dispatches `fkmenuitemselect` bubbling event for parent auto-close
+- Token-driven styling with two-tier fallbacks
+- Reusable across any menu-like context (dropdown menus, context menus, command palettes)
+
+---
+
+## Quick Start
+
+```html
+<fk-menu-item icon="eye" (itemClick)="onView()">View Details</fk-menu-item>
+<fk-menu-separator />
+<fk-menu-item icon="gear-outline" [disabled]="true">Settings</fk-menu-item>
+<fk-menu-item [danger]="true" (itemClick)="onDelete()">Delete</fk-menu-item>
+```
+
+---
+
+## Import
+
+```ts
+import { MenuItemComponent, MenuSeparatorComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [MenuItemComponent, MenuSeparatorComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selectors
+
+```html
+<fk-menu-item></fk-menu-item> <fk-menu-separator></fk-menu-separator>
+```
+
+---
+
+## Examples
+
+### With icon
+
+```html
+<fk-menu-item icon="eye">View</fk-menu-item>
+```
+
+### Without icon
+
+```html
+<fk-menu-item>Copy</fk-menu-item>
+```
+
+### Danger variant
+
+```html
+<fk-menu-item [danger]="true">Delete</fk-menu-item>
+```
+
+### Disabled
+
+```html
+<fk-menu-item [disabled]="true">Settings (locked)</fk-menu-item>
+```
+
+### With separator
+
+```html
+<fk-menu-item icon="eye">View</fk-menu-item>
+<fk-menu-item icon="gear-outline">Edit</fk-menu-item>
+<fk-menu-separator />
+<fk-menu-item icon="open-rect-arrow-out-fill" [danger]="true">Delete</fk-menu-item>
+```
+
+### Handling clicks
+
+```html
+<fk-menu-item (itemClick)="onEdit()">Edit</fk-menu-item>
+```
+
+Disabled items do not emit `itemClick`.
+
+---
+
+## Accessibility
+
+### fk-menu-item
+
+- Host element has `role="menuitem"`
+- `tabindex="-1"` for roving focus management (parent container controls focus)
+- `aria-disabled="true"` set when disabled; disabled items are skipped by keyboard navigation
+- Activates on Enter and Space keydown
+
+### fk-menu-separator
+
+- Host element has `role="separator"`
+
+---
+
+## Design Tokens
+
+### fk-menu-item tokens
+
+```
+--fk-menu-item-gap
+--fk-menu-item-padding
+--fk-menu-item-radius
+--fk-menu-item-font-family
+--fk-menu-item-font-size
+--fk-menu-item-color
+--fk-menu-item-bg-hover
+--fk-menu-item-focus-ring
+--fk-menu-item-opacity-disabled
+--fk-menu-item-transition-duration
+--fk-menu-item-transition-easing
+--fk-menu-item-danger-color
+--fk-menu-item-danger-bg-hover
+```
+
+### fk-menu-separator tokens
+
+```
+--fk-menu-separator-color
+```
+
+### Customizing tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```css
+:root {
+  --fk-menu-item-radius: 0;
+  --fk-menu-item-bg-hover: #f5f3ff;
+  --fk-menu-item-danger-color: #dc2626;
+}
+```
+
+Or scope overrides to a specific container:
+
+```css
+.custom-menu fk-menu-item {
+  --fk-menu-item-font-size: 1rem;
+  --fk-menu-item-padding: 0.75rem 1rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- `fk-menu-item` dispatches a custom `fkmenuitemselect` DOM event with `bubbles: true` on activation, allowing parent containers like `fk-dropdown-menu` to auto-close without tight coupling
+- `fk-menu-item` and `fk-menu-separator` are standalone atoms designed for reuse across any menu-like context, not just dropdown menus
+- Disabled items suppress click/keyboard activation and are excluded from focus navigation by parent containers querying `[role="menuitem"]:not([aria-disabled="true"])`

package/ui/nav-brand/README.md

@@ -0,0 +1,111 @@
+# fk-nav-brand
+
+A navigation brand component for displaying your app or company name (and optional logo) in the header with router integration.
+
+---
+
+## API
+
+### Inputs
+
+| Input       | Type                | Default | Description                                              |
+| ----------- | ------------------- | ------- | -------------------------------------------------------- |
+| `brandText` | `string` (required) | —       | Brand text to display (for example `"FrameKit"`)         |
+| `href`      | `string`            | `"/"`   | Navigation target (router link or plain href)            |
+| `id`        | `string \| null`    | `null`  | Optional ID for the root element                         |
+| `className` | `string`            | `''`    | Additional CSS classes for the host element              |
+| `ariaLabel` | `string \| null`    | `null`  | Accessible label when the brand text alone is not enough |
+
+Internally, `fk-nav-brand` uses Angular’s router to navigate when `href` is a client-side route.
+
+---
+
+## Features
+
+- Consistent brand placement in navigation bars
+- Works with Angular Router via `routerLink`
+- Token-driven typography and spacing
+
+---
+
+## Quick Start
+
+```html
+<fk-nav-brand brandText="Acme App" href="/"></fk-nav-brand>
+```
+
+---
+
+## Import
+
+```ts
+import { NavBrandComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-header',
+  imports: [NavBrandComponent],
+  templateUrl: './header.component.html',
+})
+export class HeaderComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-nav-brand></fk-nav-brand>
+```
+
+---
+
+## Examples
+
+### Basic header usage
+
+```html
+<header class="app-header">
+  <fk-nav-brand brandText="My Application" href="/"></fk-nav-brand>
+</header>
+```
+
+### With ARIA label
+
+```html
+<fk-nav-brand brandText="AA" href="/" ariaLabel="Acme App Home"></fk-nav-brand>
+```
+
+---
+
+## Accessibility
+
+- Use `ariaLabel` when abbreviations or logos alone might not be clear to screen readers.
+- Typically placed within a `<header>` or `<nav>` landmark to help assistive tech users orient themselves.
+
+---
+
+## Design Tokens
+
+`fk-nav-brand` uses navigation/brand tokens such as:
+
+```scss
+--fk-nav-brand-font-size;
+--fk-nav-brand-font-weight;
+--fk-nav-brand-color;
+```
+
+Override in your theme:
+
+```scss
+:root {
+  --fk-nav-brand-font-weight: 700;
+}
+```
+
+---
+
+## Behavior Notes
+
+- The component is unopinionated about layout; pair it with your header/nav layout components for full navigation experiences.

package/ui/nav-group/README.md

@@ -0,0 +1,145 @@
+# fk-nav-group
+
+An expandable sidenav group — renders a clickable trigger row (icon + label, optionally routed) and reveals projected child nav items when expanded. Designed to sit inside a collapsible shell so that clicks on a collapsed rail pop the shell open and auto-expand the group.
+
+---
+
+## API
+
+### Inputs
+
+| Input        | Type                         | Default | Description                                                                                                                  |
+| ------------ | ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`                     | —       | **Required.** Text rendered on the trigger row.                                                                              |
+| `icon`       | `string \| null`             | `null`  | Icon name rendered before the label.                                                                                         |
+| `iconSize`   | `IconSize`                   | `"sm"`  | Size passed through to the trigger's `fk-sidenav-link`.                                                                      |
+| `routerLink` | `string \| string[] \| null` | `null`  | Destination for the trigger's anchor. Active in both expanded and collapsed states.                                          |
+| `collapsed`  | `boolean`                    | `false` | Set this to `true` when the outer sidenav is in its collapsed rail state — clicks then both navigate AND emit `requestOpen`. |
+| `className`  | `string`                     | `''`    | Additional CSS classes merged onto the host element.                                                                         |
+
+### Models
+
+| Model      | Type      | Default | Description                                                                 |
+| ---------- | --------- | ------- | --------------------------------------------------------------------------- |
+| `expanded` | `boolean` | `false` | Two-way bound expansion state. Flipped by the built-in toggle on row click. |
+
+### Outputs
+
+| Output        | Type   | Description                                                                                                                                                                                                                                                               |
+| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requestOpen` | `void` | Emitted only when the trigger is clicked while `collapsed` is `true`. Hosts typically listen to open their collapsible outer shell. The trigger also navigates via `routerLink` on the same click, so the user lands on the group's route with the shell already opening. |
+
+### Content
+
+`fk-nav-group` projects its child nav items into the expanded body:
+
+```html
+<fk-nav-group label="Integrations" icon="integrations">
+  <fk-sidenav-link icon="integrations" label="API Keys" routerLink="/integrations/api-keys" />
+  <fk-sidenav-link icon="integrations" label="Webhooks" routerLink="/integrations/webhooks" />
+</fk-nav-group>
+```
+
+---
+
+## Features
+
+- Click-to-toggle expansion with two-way `expanded` model (suppressed by `lockedOpen`)
+- Router integration via `routerLink` — navigates in both expanded and collapsed states
+- `requestOpen` output bridges to a collapsible outer shell (`fk-app-shell` and friends) — fires alongside navigation when clicked in rail mode
+- Content projection for arbitrary child rows — `fk-sidenav-link`, section titles, custom markers
+- Token-driven spacing (`--fk-nav-group-row-gap`, `--fk-nav-group-children-gap`, `--fk-nav-group-children-indent`, `--fk-nav-group-children-offset`)
+
+---
+
+## Quick Start
+
+```html
+<fk-nav-group label="Integrations" icon="integrations" iconSize="md" [routerLink]="['/integrations']" [collapsed]="sidenavCollapsed()" [(expanded)]="integrationsExpanded" (requestOpen)="openSidenav()">
+  <fk-sidenav-link icon="integrations" label="API Keys" [routerLink]="['/integrations/api-keys']" />
+  <fk-sidenav-link icon="integrations" label="Applications" [routerLink]="['/integrations/applications']" />
+</fk-nav-group>
+```
+
+---
+
+## Import
+
+```ts
+import { NavGroupComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [NavGroupComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-nav-group></fk-nav-group>
+```
+
+---
+
+## Examples
+
+### Flat list with auto-expansion
+
+```html
+<fk-nav-group label="Core Concepts" icon="book-outline" [(expanded)]="expanded">
+  <fk-sidenav-link icon="book-outline" label="Authentication" routerLink="/docs/authentication" />
+  <fk-sidenav-link icon="book-outline" label="Roles" routerLink="/docs/roles" />
+  <fk-sidenav-link icon="book-outline" label="Permissions" routerLink="/docs/permissions" />
+</fk-nav-group>
+```
+
+### Inside a collapsible sidenav
+
+```html
+<fk-nav-group label="Docs" icon="book-outline" [collapsed]="shellCollapsed()" [(expanded)]="docsExpanded" (requestOpen)="shellCollapsed.set(false)">
+  <fk-sidenav-link label="Getting started" routerLink="/docs" />
+</fk-nav-group>
+```
+
+---
+
+## Accessibility
+
+- Trigger row is a `role="presentation"` wrapper containing a keyboard-navigable `fk-sidenav-link` — the sidenav-link handles focus and keyboard activation
+- Expansion state is reflected through the host class `fk-nav-group--expanded`; consumers can add further ARIA attributes via `className` if needed
+- Keyboard activation (Enter on the focused trigger) follows the same path as a mouse click — navigates via `routerLink` and, when `collapsed` is `true`, also emits `requestOpen` so screen-reader users land on the destination with the rail expanding behind them
+
+---
+
+## Design Tokens
+
+```scss
+--fk-nav-group-row-gap;
+--fk-nav-group-children-gap;
+--fk-nav-group-children-indent;
+--fk-nav-group-children-offset;
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-nav-group-children-indent: 1rem;
+  --fk-nav-group-children-gap: var(--fk-rhythm-2);
+}
+```
+
+---
+
+## Behavior Notes
+
+- The built-in `toggle()` decides what happens to `expanded` on click: in rail mode it leaves `expanded` alone and only emits `requestOpen` (children must not render inside the rail); in expanded mode it flips `expanded` unless `lockedOpen` is `true`. Navigation via `routerLink` happens independently on the inner sidenav-link's anchor in both states. If you want custom behavior, listen to `(requestOpen)` and drive `[(expanded)]` yourself.
+- The trigger row composes `fk-sidenav-link` — you get the same active-route styling and keyboard semantics for free.
+- No opinionated max-width — the trigger fills the row. Cap the width at the consumer level if you need it (e.g., docs shells clamp their top-level items to 18rem).

package/ui/nav-separator/README.md

@@ -0,0 +1,44 @@
+# fk-nav-separator
+
+A token-driven separator atom for visually dividing groups of navigation items. Supports vertical and horizontal orientation with decorative/semantic accessibility modes.
+
+## Usage
+
+```html
+<!-- Default: vertical, decorative -->
+<fk-nav-separator />
+
+<!-- Horizontal -->
+<fk-nav-separator orientation="horizontal" />
+
+<!-- Semantic (accessible to screen readers) -->
+<fk-nav-separator [decorative]="false" />
+
+<!-- Custom styling -->
+<fk-nav-separator length="2rem" thickness="2px" color="var(--fk-color-primary)" />
+```
+
+## Inputs
+
+| Input         | Type                         | Default      | Description                                                               |
+| ------------- | ---------------------------- | ------------ | ------------------------------------------------------------------------- |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | Line axis                                                                 |
+| `length`      | `string \| null`             | `null`       | Line length (height when vertical, width when horizontal)                 |
+| `thickness`   | `string \| null`             | `null`       | Line thickness                                                            |
+| `margin`      | `string \| null`             | `null`       | Margin around separator                                                   |
+| `color`       | `string \| null`             | `null`       | Custom color override                                                     |
+| `decorative`  | `boolean`                    | `true`       | If true: `aria-hidden="true"`. If false: `role="separator"` + orientation |
+| `className`   | `string`                     | `""`         | Additional CSS classes                                                    |
+
+## Tokens
+
+| Token                          | Fallback                 | Description    |
+| ------------------------------ | ------------------------ | -------------- |
+| `--fk-nav-separator-color`     | `var(--fk-color-border)` | Line color     |
+| `--fk-nav-separator-length`    | `1.5rem` / `auto`        | Line length    |
+| `--fk-nav-separator-thickness` | `1px`                    | Line thickness |
+| `--fk-nav-separator-margin`    | `0 0.75rem` / `0.5rem 0` | Spacing around |
+
+## Accessibility
+
+By default, the separator is decorative (`aria-hidden="true"`). Set `[decorative]="false"` to expose it as a semantic separator with `role="separator"` and `aria-orientation`.