@frame-kit/ui-ng-patterns 0.2.12 → 0.2.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frame-kit/ui-ng-patterns",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "description": "Opinionated, dashboard-ready Angular component patterns composed from @frame-kit/ui-ng.",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
     "@angular/forms": "^21.2.0",
     "@angular/platform-browser": "^21.2.0",
     "@angular/router": "^21.2.0",
-    "@frame-kit/ui-ng": "0.2.12",
+    "@frame-kit/ui-ng": "0.2.14",
     "rxjs": "^7.0.0"
   },
   "sideEffects": false,

package/types/frame-kit-ui-ng-patterns-dashboard.d.ts

@@ -2,6 +2,7 @@ import * as _angular_core from '@angular/core';
 import { TemplateRef } from '@angular/core';
 import { HeadlineLevel } from '@frame-kit/ui-ng/core/headline';
 import * as i1 from '@angular/cdk/drag-drop';
+import { AppShellMode } from '@frame-kit/ui-ng/layouts/app-shell';
 
 /**
  * Page-level dashboard header: title + optional description on the left, up to
@@ -1231,5 +1232,287 @@ declare class ContentDetailPageComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContentDetailPageComponent, "fk-content-detail-page", never, { "heading": { "alias": "heading"; "required": false; "isSignal": true; }; "subtitle": { "alias": "subtitle"; "required": false; "isSignal": true; }; "backLabel": { "alias": "backLabel"; "required": false; "isSignal": true; }; "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "back": "back"; }, never, ["[backIcon]", "[headline]", "[subtitle]", "[actions]", "*"], true, never>;
 }
 
-export { BackNavComponent, ColumnsComponent, ContentColumnComponent, ContentColumnHeadlineComponent, ContentDetailHeaderComponent, ContentDetailPageComponent, ContentPageSectionComponent, ContentRowComponent, ContentSplitLayoutComponent, DetailPanelComponent, DialogFooterComponent, DialogHeaderComponent, DialogShellComponent, OnboardingGuideComponent, PageHeaderComponent, SearchBarLayoutComponent, SidebarNavComponent, SidebarNavItemDirective, TableEmptyStateComponent };
-export type { ColumnsEmptyTracks, DialogConfirmVariant, DialogHeaderTint, OnboardingStep, OnboardingSubstep, OnboardingSubstepToggle, SidebarNavChild, SidebarNavGroup, SidebarNavItem, SidebarNavLink, SidebarNavModel };
+/**
+ * The line a region shows while it fetches something of its own: a small
+ * spinner beside a label, centered where the content will be.
+ *
+ * Sits in place of the content so a section that is still resolving reads as
+ * working rather than as empty. Mono and faint because it is machinery
+ * reporting itself, not content that has arrived.
+ *
+ * Not for a whole page — a page has its own loading state. This is for a
+ * section whose data comes separately from the rest: a drawer panel, a
+ * capability list, an audit page inside a detail view.
+ *
+ *   <fk-inline-loader label="Loading capabilities…" />
+ *
+ * The label doubles as the spinner's accessible name — one string, so the two
+ * cannot drift.
+ */
+declare class InlineLoaderComponent {
+    /** What is being fetched, already translated. Also the spinner's aria-label. */
+    readonly label: _angular_core.InputSignal<string>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly id: _angular_core.InputSignal<string | null>;
+    readonly classes: _angular_core.Signal<string>;
+    get hostClass(): string;
+    get hostId(): string | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<InlineLoaderComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<InlineLoaderComponent, "fk-inline-loader", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** One selectable row in a column. */
+interface ContextSwitcherOption {
+    id: string;
+    label: string;
+}
+/**
+ * A titled list of options. Most switchers have one; a two-column switcher
+ * (say, Applications beside Environments) is the only structural variation.
+ */
+interface ContextSwitcherColumn {
+    /** Identifies the column in the `select` event — the parent acts on it. */
+    key: string;
+    title: string;
+    options: readonly ContextSwitcherOption[];
+    /** The row to paint as current, if any. */
+    activeId: string | null;
+}
+/** Which row was chosen, and which column it came from. */
+interface ContextSwitcherSelection {
+    columnKey: string;
+    option: ContextSwitcherOption;
+}
+/** Badge treatment: tinted (default) or solid, for the darker of two stacked controls. */
+type ContextSwitcherIconTone = 'brand' | 'solid';
+/** Sub-label treatment: a static category, or live context worth reading at a glance. */
+type ContextSwitcherSublabelTone = 'muted' | 'primary';
+
+/**
+ * The sidebar control for "which context am I working in": a trigger showing
+ * the current name over a small category line, and a panel of one or more
+ * titled option columns.
+ *
+ * Several of these stack in a rail (an account, an application, an
+ * environment), and any visible difference between them reads as a mistake
+ * rather than a distinction — so the chrome lives here once, and the meaning
+ * stays with the caller. This holds no data, fetches nothing, and knows
+ * nothing about what the options are; it reports what was clicked.
+ *
+ *   <fk-context-switcher
+ *     [name]="accountName()"
+ *     sublabel="Account"
+ *     ariaLabel="Switch account"
+ *     [columns]="columns()"
+ *     (optionSelect)="onSelect($event)"
+ *   >
+ *     <fk-icon contextSwitcherIcon name="organization" />
+ *   </fk-context-switcher>
+ *
+ * Closing is the caller's call: choosing an account commits and should close,
+ * while choosing an application in a two-column switcher only re-focuses the
+ * second column and must stay open. Call `close()` when you mean to.
+ */
+declare class ContextSwitcherComponent {
+    /**
+     * The trigger's headline — the context you are in. Null renders a
+     * skeleton rather than an empty row, for a first load with nothing cached.
+     */
+    readonly name: _angular_core.InputSignal<string | null>;
+    /**
+     * The small mono line beneath the name — the kind of thing the name is
+     * ("Account"), or a second piece of live context. Null renders a skeleton;
+     * empty renders nothing.
+     */
+    readonly sublabel: _angular_core.InputSignal<string | null>;
+    readonly iconTone: _angular_core.InputSignal<ContextSwitcherIconTone>;
+    readonly sublabelTone: _angular_core.InputSignal<ContextSwitcherSublabelTone>;
+    /** Icon-rail mode — the trigger collapses to its badge. */
+    readonly collapsed: _angular_core.InputSignal<boolean>;
+    /**
+     * The collapsed trigger shows no text, so it carries the current context in
+     * its label instead. Falls back to `ariaLabel`.
+     */
+    readonly collapsedAriaLabel: _angular_core.InputSignal<string>;
+    /** One column, or several. Empty columns render nothing. */
+    readonly columns: _angular_core.InputSignal<readonly ContextSwitcherColumn[]>;
+    readonly optionSelect: _angular_core.OutputEmitterRef<ContextSwitcherSelection>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly id: _angular_core.InputSignal<string | null>;
+    /** Describes the control itself. */
+    readonly ariaLabel: _angular_core.InputSignal<string>;
+    private readonly dropdown;
+    /** Two columns sit side by side; one fills the panel. */
+    readonly multiColumn: _angular_core.Signal<boolean>;
+    readonly triggerAriaLabel: _angular_core.Signal<string>;
+    readonly classes: _angular_core.Signal<string>;
+    get hostClass(): string;
+    get hostId(): string | null;
+    /** Close the panel. The caller decides when a selection is final. */
+    close(): void;
+    protected onSelect(column: ContextSwitcherColumn, option: ContextSwitcherOption): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ContextSwitcherComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ContextSwitcherComponent, "fk-context-switcher", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "sublabel": { "alias": "sublabel"; "required": false; "isSignal": true; }; "iconTone": { "alias": "iconTone"; "required": false; "isSignal": true; }; "sublabelTone": { "alias": "sublabelTone"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "collapsedAriaLabel": { "alias": "collapsedAriaLabel"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": true; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "optionSelect": "optionSelect"; }, never, ["[contextSwitcherIcon]"], true, never>;
+}
+
+/** A child destination that may be hidden by the caller's authority. */
+type DashboardNavChild = SidebarNavChild & {
+    /** `false` drops the row. Absent counts as visible. */
+    visible?: boolean;
+};
+/** A top-level destination, or a parent whose children may be hidden. */
+type DashboardNavItem = Omit<SidebarNavItem, 'children'> & {
+    visible?: boolean;
+    children?: DashboardNavChild[];
+};
+interface DashboardNavGroup {
+    /** Stable identity, used for tracking and for anchoring the projected slots. */
+    id: string;
+    /** Section heading; rendered by `fk-sidebar-nav`. Omit for an unlabelled group. */
+    label?: string;
+    items: DashboardNavItem[];
+    /**
+     * Draw a hairline above this group. For a group whose neighbours change
+     * with capabilities, the gap alone reads as a boundary only while the
+     * earlier group is tall — the line keeps it legible in every state.
+     * Suppressed when the group renders first.
+     */
+    separatorBefore?: boolean;
+}
+
+interface NavSegment {
+    id: string;
+    before: boolean;
+    after: boolean;
+    separated: boolean;
+    model: SidebarNavModel;
+}
+/**
+ * A dashboard's sidebar navigation: the caller's groups, with items the
+ * caller may not open already removed, rendered as one `fk-sidebar-nav` per
+ * group so that projected controls — an account switcher, an environment
+ * switcher — can sit between groups.
+ *
+ *   <fk-dashboard-nav
+ *     [groups]="groups()"
+ *     [collapsed]="collapsed()"
+ *     slotBeforeGroupId="workspace"
+ *     slotAfterGroupId="access"
+ *   >
+ *     <div navSlotBefore><fk-context-switcher … /></div>
+ *     <div><fk-context-switcher … /></div>
+ *   </fk-dashboard-nav>
+ *
+ * Visibility is a plain boolean on each item, decided by the caller from
+ * whatever authority it has; this component only removes what is hidden. A
+ * parent whose children have all been removed goes too — it would expand to
+ * nothing. Disclosure, active state and the collapsed-rail flyout are owned
+ * by `fk-sidebar-nav`.
+ */
+declare class DashboardNavComponent {
+    readonly groups: _angular_core.InputSignal<DashboardNavGroup[]>;
+    /** Icon-rail mode, passed through to every segment. */
+    readonly collapsed: _angular_core.InputSignal<boolean>;
+    /** Project `[navSlotBefore]` content immediately before this group. */
+    readonly slotBeforeGroupId: _angular_core.InputSignal<string | null>;
+    /** Project default `<ng-content>` immediately after this group. */
+    readonly slotAfterGroupId: _angular_core.InputSignal<string | null>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly id: _angular_core.InputSignal<string | null>;
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Visible groups sliced into render segments, each carrying a single-group
+     * `SidebarNavModel`.
+     */
+    private readonly segments;
+    /**
+     * Groups above the projected `[navSlotBefore]` content, and those below it.
+     * Split rather than conditionally projecting inside the loop: the slot's
+     * position is expressed by what is emitted around it, so the template needs
+     * exactly one outlet — Angular projects to the first matching `ng-content`,
+     * and a second copy (or one inside a false `@if`) swallows the content.
+     */
+    readonly segmentsBeforeSlot: _angular_core.Signal<NavSegment[]>;
+    readonly segmentsAfterSlot: _angular_core.Signal<NavSegment[]>;
+    readonly classes: _angular_core.Signal<string>;
+    get hostClass(): string;
+    get hostId(): string | null;
+    get hostAriaLabel(): string | null;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DashboardNavComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DashboardNavComponent, "fk-dashboard-nav", never, { "groups": { "alias": "groups"; "required": true; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "slotBeforeGroupId": { "alias": "slotBeforeGroupId"; "required": false; "isSignal": true; }; "slotAfterGroupId": { "alias": "slotAfterGroupId"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, ["[navSlotBefore]", "*"], true, never>;
+}
+
+/**
+ * The chrome of a signed-in dashboard, built on `fk-app-shell`: a full-height
+ * aside with a brand header and collapse toggle, a sticky frosted topbar with
+ * a mobile hamburger, a capped page area with an optional loading veil, and a
+ * footer. Every dashboard that uses it gets the identical structure — the
+ * same hamburger, the same collapse, the same scroll behaviour — and differs
+ * only in what it projects.
+ *
+ *   <fk-dashboard-layout [pageLoading]="navigating()">
+ *     <fk-nav-brand layoutBrand brandText="Acme" />
+ *     <fk-dashboard-nav layoutAside [groups]="groups()" [collapsed]="collapsed()" />
+ *     <nav layoutTopbarStart>Acme / Overview</nav>
+ *     <fk-user-menu layoutTopbarEnd … />
+ *     <router-outlet />
+ *     <span layoutFooter>© Acme</span>
+ *   </fk-dashboard-layout>
+ *
+ * A dashboard that needs a trailing panel — a documentation reader, a detail
+ * inspector — projects it into `[layoutEnd]` and chooses its `endMode`. One
+ * that needs a panel beside the page, such as a secondary navigation, projects
+ * it into `[layoutContentPanel]`, which sits in the content row ahead of the
+ * scroll container so the page scrolls under it rather than with it.
+ *
+ * The aside's toggle and the topbar's hamburger drive the underlying shell;
+ * `collapsed` reports the rail state so projected controls can follow it.
+ * The toggle glyphs are projection slots with a built-in fallback, so no icon
+ * registry is required.
+ */
+declare class DashboardLayoutComponent {
+    /** Passed to `fk-app-shell`. `icon` collapses to a rail; `side` hides entirely. */
+    readonly mode: _angular_core.InputSignal<AppShellMode>;
+    readonly sidenavWidth: _angular_core.InputSignal<string>;
+    readonly collapsedWidth: _angular_core.InputSignal<string>;
+    /** Layout mode for the trailing panel, when `[layoutEnd]` is projected. */
+    readonly endMode: _angular_core.InputSignal<AppShellMode>;
+    readonly endWidth: _angular_core.InputSignal<string>;
+    readonly endCollapsedWidth: _angular_core.InputSignal<string>;
+    /** Veil the page area with the projected `[layoutPageLoader]` content. */
+    readonly pageLoading: _angular_core.InputSignal<boolean>;
+    /** Accessible name for the aside's collapse toggle. */
+    readonly toggleAriaLabel: _angular_core.InputSignal<string>;
+    /** Accessible name for the topbar's mobile hamburger. */
+    readonly menuAriaLabel: _angular_core.InputSignal<string>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly id: _angular_core.InputSignal<string | null>;
+    private readonly shell;
+    /** Whether the aside is in its icon rail. Projected controls follow this. */
+    readonly collapsed: _angular_core.Signal<boolean>;
+    /** Whether the trailing panel is showing. Projected controls follow this. */
+    readonly endOpen: _angular_core.Signal<boolean>;
+    readonly classes: _angular_core.Signal<string>;
+    get hostClass(): string;
+    get hostId(): string | null;
+    /** The aside header's toggle: collapse or expand the rail. */
+    toggleSidenav(): void;
+    /** The topbar hamburger: open the off-canvas aside on narrow viewports. */
+    openSidenav(): void;
+    /**
+     * Collapse the rail from outside the header's own toggle — what a dashboard
+     * calls when it opens the trailing panel and wants the room.
+     */
+    closeSidenav(): void;
+    /** Show the projected `[layoutEnd]` panel. */
+    openEnd(): void;
+    /** Hide it. */
+    closeEnd(): void;
+    /** Hide it if it is showing, show it if it is not. */
+    toggleEnd(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DashboardLayoutComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DashboardLayoutComponent, "fk-dashboard-layout", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "sidenavWidth": { "alias": "sidenavWidth"; "required": false; "isSignal": true; }; "collapsedWidth": { "alias": "collapsedWidth"; "required": false; "isSignal": true; }; "endMode": { "alias": "endMode"; "required": false; "isSignal": true; }; "endWidth": { "alias": "endWidth"; "required": false; "isSignal": true; }; "endCollapsedWidth": { "alias": "endCollapsedWidth"; "required": false; "isSignal": true; }; "pageLoading": { "alias": "pageLoading"; "required": false; "isSignal": true; }; "toggleAriaLabel": { "alias": "toggleAriaLabel"; "required": false; "isSignal": true; }; "menuAriaLabel": { "alias": "menuAriaLabel"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, ["[layoutBanner]", "[layoutBrand]", "[layoutToggleIcon]", "[layoutAside]", "[layoutAsideFooter]", "[layoutContentPanel]", "[layoutMenuIcon]", "[layoutTopbarStart]", "[layoutTopbarEnd]", "*", "[layoutPageLoader]", "[layoutEnd]", "[layoutFooter]"], true, never>;
+}
+
+export { BackNavComponent, ColumnsComponent, ContentColumnComponent, ContentColumnHeadlineComponent, ContentDetailHeaderComponent, ContentDetailPageComponent, ContentPageSectionComponent, ContentRowComponent, ContentSplitLayoutComponent, ContextSwitcherComponent, DashboardLayoutComponent, DashboardNavComponent, DetailPanelComponent, DialogFooterComponent, DialogHeaderComponent, DialogShellComponent, InlineLoaderComponent, OnboardingGuideComponent, PageHeaderComponent, SearchBarLayoutComponent, SidebarNavComponent, SidebarNavItemDirective, TableEmptyStateComponent };
+export type { ColumnsEmptyTracks, ContextSwitcherColumn, ContextSwitcherIconTone, ContextSwitcherOption, ContextSwitcherSelection, ContextSwitcherSublabelTone, DashboardNavChild, DashboardNavGroup, DashboardNavItem, DialogConfirmVariant, DialogHeaderTint, OnboardingStep, OnboardingSubstep, OnboardingSubstepToggle, SidebarNavChild, SidebarNavGroup, SidebarNavItem, SidebarNavLink, SidebarNavModel };