@frame-kit/ui-ng 0.0.1

package/layouts/app-shell/README.md

@@ -0,0 +1,357 @@
+# fk-app-shell
+
+A responsive application shell layout with a header, collapsible sidebar, an opt-in right-side end panel, overlay support, and a main content area. The shell handles positioning and transitions — consumers own the internal structure of each panel.
+
+---
+
+## API
+
+### Inputs
+
+#### Sidebar
+
+| Input            | Type                             | Default               | Description                                                                                 |
+| ---------------- | -------------------------------- | --------------------- | ------------------------------------------------------------------------------------------- |
+| mode             | `'side'` \| `'over'` \| `'icon'` | `'side'`              | Sidebar behavior: push content, overlay, or icon rail                                       |
+| sidenavWidth     | `string`                         | `'260px'`             | Width of the expanded sidebar                                                               |
+| collapsedWidth   | `string`                         | `'64px'`              | Width of the collapsed icon rail (icon mode only)                                           |
+| breakpoint       | `string`                         | `'(min-width: 48em)'` | Media query that separates mobile from desktop layout                                       |
+| sticky           | `boolean`                        | `true`                | Adds the `fk-app-shell--sticky` class for sticky layout                                     |
+| collapseOnMobile | `boolean`                        | `false`               | In `icon` mode, show the collapsed strip on mobile instead of hiding the sidebar off-screen |
+
+#### End Panel
+
+| Input             | Type                             | Default   | Description                                             |
+| ----------------- | -------------------------------- | --------- | ------------------------------------------------------- |
+| endMode           | `'side'` \| `'over'` \| `'icon'` | `'over'`  | End panel behavior: push content, overlay, or icon rail |
+| endWidth          | `string`                         | `'320px'` | Width of the expanded end panel                         |
+| endCollapsedWidth | `string`                         | `'64px'`  | Width of the collapsed icon rail (icon mode only)       |
+
+### Methods
+
+#### Sidebar
+
+| Method           | Description                                                      |
+| ---------------- | ---------------------------------------------------------------- |
+| openSidenav()    | Opens the sidebar (on mobile, opens as temporary overlay)        |
+| closeSidenav()   | Closes the sidebar and persists the closed preference            |
+| toggleSidenav()  | Toggles between open and closed                                  |
+| dismissSidenav() | Closes the mobile overlay without persisting a closed preference |
+
+#### End Panel
+
+| Method       | Description                                                 |
+| ------------ | ----------------------------------------------------------- |
+| openEnd()    | Opens the end panel (on mobile, opens as temporary overlay) |
+| closeEnd()   | Closes the end panel and persists the closed preference     |
+| toggleEnd()  | Toggles between open and closed                             |
+| dismissEnd() | Closes the end panel and persists the closed preference     |
+
+### Computed (read-only)
+
+#### Sidebar
+
+| Property    | Type              | Description                                         |
+| ----------- | ----------------- | --------------------------------------------------- |
+| sidenavOpen | `Signal<boolean>` | Whether the sidebar is currently visible            |
+| showOverlay | `Signal<boolean>` | Whether the backdrop overlay is visible             |
+| isCollapsed | `Signal<boolean>` | Whether the sidebar is in collapsed icon-rail state |
+| isMobile    | `Signal<boolean>` | Whether the viewport is below the breakpoint        |
+
+#### End Panel
+
+| Property       | Type              | Description                                           |
+| -------------- | ----------------- | ----------------------------------------------------- |
+| endOpen        | `Signal<boolean>` | Whether the end panel is currently visible            |
+| showEndOverlay | `Signal<boolean>` | Whether the end panel backdrop overlay is visible     |
+| isEndCollapsed | `Signal<boolean>` | Whether the end panel is in collapsed icon-rail state |
+
+### Content Projection Slots
+
+| Attribute         | Description                                       |
+| ----------------- | ------------------------------------------------- |
+| `appShellHeader`  | Top-level header bar (sticky, full width)         |
+| `appShellSidenav` | Sidebar content — consumer owns internal layout   |
+| `appShellContent` | Main content area                                 |
+| `appShellFooter`  | Page-level footer bar (full width, below content) |
+| `appShellEnd`     | End panel content — consumer owns internal layout |
+
+---
+
+## Features
+
+- Three sidebar modes: side (push), over (overlay), icon (collapsible rail)
+- Opt-in right-side end panel with the same three mode options
+- Responsive breakpoint detection via `BreakpointObserver`
+- Mobile overlay with backdrop dismiss
+- Single content projection slot per panel — consumers define their own internal structure
+- Smooth CSS transitions with `prefers-reduced-motion` support
+- Token-driven styling
+
+---
+
+## Quick Start
+
+```html
+<fk-app-shell mode="icon">
+  <div appShellHeader>Header</div>
+  <div appShellSidenav>Nav links</div>
+  <div appShellContent>Page content</div>
+  <footer appShellFooter>© 2026 Company</footer>
+</fk-app-shell>
+```
+
+---
+
+## Import
+
+```ts
+import { AppShellComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-dashboard',
+  imports: [AppShellComponent],
+  templateUrl: './dashboard.component.html',
+})
+export class DashboardComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-app-shell></fk-app-shell>
+```
+
+---
+
+## Examples
+
+### Side Mode (default)
+
+Sidebar pushes the main content over. Collapses to zero width when closed.
+
+```html
+<fk-app-shell mode="side">
+  <div appShellHeader>
+    <button (click)="shell.toggleSidenav()">Toggle</button>
+  </div>
+
+  <nav appShellSidenav>
+    <fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+    <fk-sidenav-link icon="organization" label="Properties" />
+  </nav>
+
+  <div appShellContent>
+    <router-outlet />
+  </div>
+</fk-app-shell>
+```
+
+### Over Mode
+
+Sidebar slides over the content with a backdrop overlay.
+
+```html
+<fk-app-shell mode="over">
+  <div appShellHeader>
+    <button (click)="shell.toggleSidenav()">Menu</button>
+  </div>
+
+  <nav appShellSidenav>
+    <fk-sidenav-link icon="email" label="Notifications" />
+  </nav>
+
+  <div appShellContent>
+    <router-outlet />
+  </div>
+</fk-app-shell>
+```
+
+### Icon Mode (collapsible rail)
+
+Sidebar collapses to a narrow icon rail on desktop. On mobile, it behaves as an overlay. The consumer provides the internal header/nav/footer layout.
+
+```html
+<fk-app-shell mode="icon">
+  <div appShellHeader>
+    <button (click)="shell.toggleSidenav()">Toggle</button>
+  </div>
+
+  <div appShellSidenav style="display: flex; flex-direction: column; height: 100%;">
+    <div class="sidenav-header">
+      <button (click)="shell.toggleSidenav()">Collapse</button>
+    </div>
+
+    <nav class="sidenav-nav" style="flex: 1; overflow-y: auto;">
+      <fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+      <fk-sidenav-link icon="organization" label="Properties" />
+      <fk-sidenav-link icon="email" label="Notifications" />
+    </nav>
+
+    <div class="sidenav-footer">
+      <fk-sidenav-link icon="info" label="Help & Support" />
+    </div>
+  </div>
+
+  <div appShellContent>
+    <router-outlet />
+  </div>
+</fk-app-shell>
+```
+
+### End Panel
+
+The end panel is opt-in and starts closed. The consumer provides their own toggle button, panel content, and internal layout.
+
+```html
+<fk-app-shell mode="icon" endMode="over">
+  <div appShellHeader>
+    <button (click)="shell.toggleSidenav()">Toggle</button>
+  </div>
+
+  <nav appShellSidenav>
+    <fk-sidenav-link icon="chart-activity-fill" label="Overview" routerLink="/app" [exact]="true" />
+  </nav>
+
+  <div appShellContent>
+    <button (click)="shell.toggleEnd()">Open Details</button>
+    <router-outlet />
+  </div>
+
+  <div appShellEnd>
+    <div class="panel-header">Detail View</div>
+    <div class="panel-content">Detail content goes here</div>
+    <div class="panel-footer">Actions</div>
+  </div>
+</fk-app-shell>
+```
+
+### Collapse on Mobile
+
+Keep the icon rail visible on mobile instead of hiding the sidebar. Tapping an item in the rail can call `shell.openSidenav()` to slide in the full sidebar as an overlay; tapping the backdrop returns to the rail.
+
+```html
+<fk-app-shell #shell mode="icon" [collapseOnMobile]="true">
+  <div appShellHeader>Header</div>
+
+  <nav appShellSidenav>
+    <button (click)="shell.openSidenav()">
+      <fk-icon name="menu-outline" />
+    </button>
+    <fk-sidenav-link icon="home" label="Home" routerLink="/" />
+  </nav>
+
+  <div appShellContent>
+    <router-outlet />
+  </div>
+</fk-app-shell>
+```
+
+### Custom Widths
+
+```html
+<fk-app-shell mode="icon" sidenavWidth="300px" collapsedWidth="80px" endWidth="400px"> ... </fk-app-shell>
+```
+
+---
+
+## Accessibility
+
+- The overlay backdrop dismisses the sidebar or end panel on click
+- All interactive elements within projected content should follow standard keyboard and focus practices
+- `prefers-reduced-motion: reduce` disables all sidebar and end panel transitions
+- Mobile mode ensures the sidebar is reachable via a toggle button in the header
+
+---
+
+## Design Tokens
+
+### Layout Tokens
+
+```
+--fk-app-shell-sidenav-width           (set via sidenavWidth input)
+--fk-app-shell-collapsed-width         (set via collapsedWidth input)
+--fk-app-shell-end-width               (set via endWidth input)
+--fk-app-shell-end-collapsed-width     (set via endCollapsedWidth input)
+```
+
+### Appearance Tokens — Sidebar
+
+```
+--fk-app-shell-header-z-index        (default: 100)
+--fk-app-shell-overlay-z-index       (default: 200)
+--fk-app-shell-aside-z-index         (default: 201)
+--fk-app-shell-overlay-bg            (default: var(--fk-black-50, rgba(0, 0, 0, 0.5)))
+--fk-app-shell-aside-bg              (default: var(--fk-color-surface, #ffffff))
+--fk-app-shell-mobile-sidenav-width  (default: 100% — mobile overlay width)
+```
+
+### Appearance Tokens — End Panel
+
+```
+--fk-app-shell-end-bg              (default: var(--fk-color-surface))
+--fk-app-shell-end-z-index         (default: 201)
+--fk-app-shell-end-radius          (default: var(--fk-radius-lg) 0 0 var(--fk-radius-lg))
+--fk-app-shell-end-shadow          (default: -4px 0 16px rgba(0, 0, 0, 0.08))
+```
+
+### Customizing Tokens
+
+```css
+:root {
+  --fk-app-shell-overlay-bg: rgba(0, 0, 0, 0.3);
+  --fk-app-shell-aside-bg: #f8fafc;
+  --fk-app-shell-end-bg: #f8fafc;
+  --fk-app-shell-end-shadow: -2px 0 12px rgba(0, 0, 0, 0.12);
+
+  /* Make the mobile sidenav a peek-style drawer instead of full-screen: */
+  --fk-app-shell-mobile-sidenav-width: 20rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- On viewport resize, transitions are disabled to prevent layout flash
+- Transitions are only enabled after explicit user interaction (toggle, open, close)
+- `dismissSidenav()` closes the mobile overlay without persisting a closed preference — on the next desktop resize the sidebar will reappear
+- `closeSidenav()` persists the closed preference across mobile/desktop transitions
+- In `icon` mode, when collapsed, the aside shrinks to `collapsedWidth` and child components (like `fk-sidenav-link`) can detect collapse state to hide labels
+- By default, the sidebar is hidden off-screen on mobile and reachable via a toggle. Set `collapseOnMobile="true"` (icon mode only) to keep the collapsed rail visible on mobile; opening the sidenav still slides it in as a full-width overlay that can be dismissed via the backdrop
+- The mobile overlay defaults to the full viewport width (`--fk-app-shell-mobile-sidenav-width: 100%`). Override the token for a peek-style drawer. The input `sidenavWidth` only drives the desktop width
+- The end panel starts closed by default — the consumer must explicitly open it via `openEnd()` or `toggleEnd()`
+- Both `dismissEnd()` and `closeEnd()` persist the closed preference, since the end panel's default state is closed
+
+---
+
+## CSS Classes
+
+The component applies state classes to its root wrapper for consumer styling:
+
+### Sidebar
+
+| Class                     | Condition                         |
+| ------------------------- | --------------------------------- |
+| `fk-app-shell--side`      | mode is `'side'`                  |
+| `fk-app-shell--over`      | mode is `'over'`                  |
+| `fk-app-shell--icon`      | mode is `'icon'`                  |
+| `fk-app-shell--sticky`    | `sticky` is `true`                |
+| `fk-app-shell--open`      | sidebar is open                   |
+| `fk-app-shell--collapsed` | sidebar is in collapsed icon rail |
+| `fk-app-shell--mobile`    | viewport is below breakpoint      |
+| `fk-app-shell--animate`   | transitions are currently enabled |
+
+### End Panel
+
+| Class                         | Condition                           |
+| ----------------------------- | ----------------------------------- |
+| `fk-app-shell--end-side`      | endMode is `'side'`                 |
+| `fk-app-shell--end-over`      | endMode is `'over'`                 |
+| `fk-app-shell--end-icon`      | endMode is `'icon'`                 |
+| `fk-app-shell--end-open`      | end panel is open                   |
+| `fk-app-shell--end-collapsed` | end panel is in collapsed icon rail |

package/layouts/content-split/README.md

@@ -0,0 +1,180 @@
+# fk-content-split
+
+A container-aware split-pane layout component for Angular. In wide containers, renders two side-by-side panels. In narrow containers, a rail strip with a toggle button appears and the left panel becomes an overlay drawer that slides in over the content.
+
+---
+
+## API
+
+### Inputs
+
+| Input        | Type             | Default   | Description                                       |
+| ------------ | ---------------- | --------- | ------------------------------------------------- |
+| `leftWidth`  | `string`         | `'280px'` | CSS width of the left panel                       |
+| `railWidth`  | `string`         | `'64px'`  | Width of the rail strip in narrow mode            |
+| `breakpoint` | `number`         | `700`     | Host width (px) below which drawer mode activates |
+| `collapsed`  | `model<boolean>` | `false`   | Two-way binding for drawer open/closed state      |
+| `className`  | `string`         | `''`      | Additional CSS classes for the host               |
+
+### Methods
+
+| Method      | Description                             |
+| ----------- | --------------------------------------- |
+| `open()`    | Opens the drawer (sets collapsed=false) |
+| `close()`   | Closes the drawer (sets collapsed=true) |
+| `toggle()`  | Toggles between open and closed         |
+| `dismiss()` | Closes the drawer (alias for close)     |
+
+### Content Projection
+
+| Slot                  | Description                         |
+| --------------------- | ----------------------------------- |
+| `[contentSplitLeft]`  | Content for the left panel / drawer |
+| `[contentSplitRight]` | Content for the main right panel    |
+
+### Types
+
+```ts
+type ContentSplitLayout = 'wide' | 'narrow';
+```
+
+---
+
+## Features
+
+- Side-by-side flex layout in wide containers
+- Overlay drawer with rail toggle in narrow containers
+- Container-aware layout switching via `ResizeObserver` (not viewport)
+- Overlay backdrop with click-to-dismiss
+- Smart animation (transitions only after user action, disabled on layout switches)
+- Two-way `[(collapsed)]` binding via Angular `model()`
+- Token-driven styling with two-tier fallbacks
+
+---
+
+## Quick Start
+
+```html
+<fk-content-split [(collapsed)]="collapsed">
+  <nav contentSplitLeft>Filters / Tree</nav>
+  <main contentSplitRight>Detail View</main>
+</fk-content-split>
+```
+
+---
+
+## Import
+
+```ts
+import { FkContentSplitComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [FkContentSplitComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+## Selector
+
+```html
+<fk-content-split></fk-content-split>
+```
+
+---
+
+## Examples
+
+### Basic
+
+```html
+<fk-content-split>
+  <div contentSplitLeft>Left panel</div>
+  <div contentSplitRight>Right panel</div>
+</fk-content-split>
+```
+
+### Programmatic Toggle
+
+```html
+<fk-content-split #split [(collapsed)]="collapsed">
+  <div contentSplitLeft>Sidebar content</div>
+  <div contentSplitRight>
+    <button (click)="split.toggle()">Toggle Panel</button>
+    <p>Main content</p>
+  </div>
+</fk-content-split>
+```
+
+### Custom Widths and Breakpoint
+
+```html
+<fk-content-split leftWidth="360px" railWidth="48px" [breakpoint]="500">
+  <div contentSplitLeft>Wide sidebar</div>
+  <div contentSplitRight>Content</div>
+</fk-content-split>
+```
+
+---
+
+## Accessibility
+
+- Rail toggle button uses a native `<button>` with dynamic `aria-label` (`"Open panel"` / `"Close panel"`)
+- Overlay backdrop is click-to-dismiss
+- `prefers-reduced-motion: reduce` disables all transitions
+- Focus ring on the rail toggle uses `--fk-focus-ring` token
+
+---
+
+## Design Tokens
+
+`fk-content-split` is styled entirely through design tokens.
+
+### Token Reference
+
+| Token                                        | Default                            | Description                              |
+| -------------------------------------------- | ---------------------------------- | ---------------------------------------- |
+| `--fk-content-split-left-width`              | `280px`                            | Left panel width (capped in narrow mode) |
+| `--fk-content-split-rail-width`              | `64px`                             | Rail strip width in narrow mode          |
+| `--fk-content-split-left-bg`                 | `var(--fk-color-surface)`          | Left panel / rail background             |
+| `--fk-content-split-left-border`             | `1px solid var(--fk-color-border)` | Left panel / rail border                 |
+| `--fk-content-split-overlay-bg`              | `rgba(0, 0, 0, 0.5)`               | Overlay backdrop color                   |
+| `--fk-content-split-rail-toggle-color`       | `var(--fk-color-muted)`            | Rail toggle icon color                   |
+| `--fk-content-split-rail-toggle-color-hover` | `var(--fk-color-text)`             | Rail toggle hover color                  |
+| `--fk-content-split-rail-toggle-bg-hover`    | `var(--fk-color-surface-muted)`    | Rail toggle hover background             |
+| `--fk-content-split-rail-toggle-padding`     | `var(--fk-rhythm-3)`               | Rail toggle button padding               |
+| `--fk-content-split-rail-toggle-color-hover` | `var(--fk-color-text)`             | Rail toggle text color on hover          |
+
+### Customizing Tokens
+
+Override tokens in your application's global stylesheet or a scoped selector:
+
+```css
+:root {
+  --fk-content-split-left-bg: #f8fafc;
+  --fk-content-split-overlay-bg: rgba(0, 0, 0, 0.7);
+}
+```
+
+Or scope overrides to a specific context:
+
+```css
+.dark-theme fk-content-split {
+  --fk-content-split-left-bg: #1e293b;
+  --fk-content-split-rail-toggle-color: #94a3b8;
+}
+```
+
+---
+
+## Behavior Notes
+
+- **Container-aware, not viewport-aware**: Layout switches based on the host element's width via `ResizeObserver`. The breakpoint accounts for sibling layout (e.g., app-shell sidebar being open or closed).
+- **Auto-collapse on narrow**: When the host shrinks below the breakpoint, the left panel automatically collapses. The consumer controls reopening via the rail toggle or programmatic methods.
+- **Drawer width capping**: In narrow mode, the drawer width is capped at `100% - rail width` so it never overflows the viewport on small devices (e.g., phones).
+- **No auto-expand**: When the host grows past the breakpoint, it switches to wide mode. The consumer controls the collapsed state.
+- **Animation is opt-in**: Transitions apply only after user actions (`open()`, `close()`, `toggle()`). Layout switches skip animation to avoid jank.
+- **Rail strip**: Only visible in narrow mode. Contains a built-in hamburger toggle button. Hidden via CSS `display: none` in wide mode.