@qilin-agent/client-ui-layout 0.0.0-stage → 3.1.4

package/lib/types/client/columns.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Normal column geometry: the right column shrinks, then loses its track,
+ * before the center drops below its minimum. The sidebar never concedes here;
+ * AppFrame supplies its effective preference after responsive collapse.
+ */
+/** Resolved widths for one frame. */
+export interface Columns {
+    sidebar: number;
+    center: number;
+    rightbar: number;
+}
+/** Center width protected while the normal right column is open. */
+export declare const CENTER_MIN = 400;
+/** Sidebar drag clamp floor. */
+export declare const SIDEBAR_MIN = 264;
+/** Sidebar drag clamp ceiling. */
+export declare const SIDEBAR_MAX = 420;
+/** Sidebar width before any user drag. */
+export declare const SIDEBAR_DEFAULT = 280;
+/** Closed-sidebar rail: a 24px icon column between 16px horizontal paddings. */
+export declare const SIDEBAR_COLLAPSED = 56;
+/** Viewport width below which the sidebar auto-collapses to the rail (deepsuite
+ * LG breakpoint); a manual toggle below it re-expands over the squeezed center
+ * (stores.ts narrowExpanded). */
+export declare const SIDEBAR_AUTO_COLLAPSE = 1024;
+/** Right column drag clamp floor. */
+export declare const RIGHTBAR_MIN = 300;
+/** Maximum normal right panel width as a fraction of the frame. */
+export declare const RIGHTBAR_MAX_RATIO = 0.7;
+/** First-open right panel preference as a fraction of the frame. */
+export declare const RIGHTBAR_DEFAULT_RATIO = 0.35;
+/**
+ * Clamp a panel width into its contract range.
+ * @param px - requested width.
+ * @param min - range lower bound.
+ * @param max - range upper bound.
+ * @returns the clamped width.
+ */
+export declare function clampWidth(px: number, min: number, max: number): number;
+/**
+ * Solve the three column widths for one viewport frame.
+ * @param viewport - available frame width in px.
+ * @param sidebar - sidebar width preference in px (0 = closed).
+ * @param rightbar - requested right panel width in px (0 = no track).
+ * @param collapsedWidth - track width of the closed sidebar; the default keeps
+ *   the icon rail, 0 hides the column entirely (macOS desktop).
+ * @returns actual widths after shrinking or removing the right track; only
+ *   without that track may the center fall below its minimum, down to zero.
+ */
+export declare function computeColumns(viewport: number, sidebar: number, rightbar: number, collapsedWidth?: number): Columns;
+//# sourceMappingURL=columns.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Layout plugin, browser half: one register() call contributes AppFrame into
+ * the runtime's built-in 'root' slot and, in the same breath, declares the
+ * four child slots (declaration = exclusive render authority), seats the
+ * layout store (panel geometry), and wires the panel-action service face.
+ * ctx.layout selects the main panel and controls column geometry; Session
+ * selection belongs to the Session Controller. A second effect seats the theme
+ * presenter, which projects ctx.theme snapshots onto document.body.
+ */
+import type { Context as ClientContext } from '@qilin-agent/kylin';
+import type { SnapshotSelectorHook } from '@qilin-agent/client-ui-slots';
+import type { PanelInfo } from './service.ts';
+import { zh } from './shortcut-locales.ts';
+export { LayoutController } from './service.ts';
+export type { ILayout, MainPanelId, PanelInfo } from './service.ts';
+/** Selector hook over root-scoped panel selection. */
+export type UsePanelInfo = SnapshotSelectorHook<PanelInfo>;
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** The outward face only; the concrete service stays inside this plugin. */
+        layout: import('./service.ts').ILayout;
+    }
+}
+declare module '@qilin-agent/client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Layout keyboard command labels. */
+        'shortcuts.layout': keyof typeof zh;
+    }
+    interface GlobalStandardProps {
+        /** Subscribe to the selected main panel independently of parent renders. */
+        usePanelInfo: UsePanelInfo;
+    }
+    interface SlotMap {
+        /**
+         * The whole left column. OCCUPIED by ui-sidebar's SidebarRoot, which
+         * declares the workspace and settings seats inside it — registering here
+         * replaces the navigation column outright rather than adding to it, and
+         * the seats it declares disappear with it. To add something to the
+         * sidebar, register into one of those inner seats instead.
+         *
+         * The occupant receives the frame's live column state (collapsed, width)
+         * and is expected to render the compact control rail while collapsed.
+         */
+        'sidebar': {
+            kind: 'single';
+            scope: 'root';
+            owner: SidebarOwnerProps;
+        };
+        /**
+         * Central panel selected by sidebar entry id. The reserved `conversation`
+         * key hosts the Conversation; other keys receive no Session binding.
+         */
+        'main': {
+            kind: 'keyed';
+            scope: 'root';
+        };
+        /**
+         * The right column: a track the centre makes room for, or nothing. OCCUPIED
+         * by the right Sidebar, which uses the resolved column width in normal
+         * mode and covers the viewport in fullscreen, retaining the wide-screen
+         * column reservation underneath.
+         *
+         * Whether the panel is shown, and whether it takes a track, is the
+         * occupant's own recorded business — it reports the composition of its
+         * expanded and presentation state through `ctx.layout`, and the frame sizes
+         * the track and places the resize handle from that. The expand control is
+         * not this column's: it is a button in the conversation header. The root
+         * occupant decides when to render its Session-bound content.
+         */
+        'rightbar': {
+            kind: 'single';
+            scope: 'root';
+            owner: RightbarOwnerProps;
+        };
+        /**
+         * Full-width bottom content below all three columns. Its rendered height
+         * reduces the columns' available height; empty content reserves no space.
+         * The occupant owns its height, visibility, and controls. It receives no
+         * Session binding and remains mounted across main-panel navigation.
+         */
+        'shell.bottom': {
+            kind: 'single';
+            scope: 'root';
+        };
+        /**
+         * Frame-wide floating layer, above every column and outside their scroll
+         * containers. Deliberately generic and unowned by any feature: a badge, a
+         * toast stack or a status pill all belong here, and entries order among
+         * themselves. The layer itself is click-through — entries opt back into
+         * pointer events — so an occupant never blocks the app underneath.
+         *
+         * This is the additive seat for a frame-wide surface of your own: a fresh
+         * `id` is added beside the shipped entries instead of replacing them.
+         */
+        'shell.overlay': {
+            kind: 'list';
+            scope: 'root';
+        };
+    }
+}
+/** Sidebar owner share: live column state from the frame's concession solve. */
+export interface SidebarOwnerProps {
+    /** True when the sidebar is closed (the column renders the compact control rail). */
+    collapsed: boolean;
+    /** Rendered column width in px (SIDEBAR_COLLAPSED when collapsed). */
+    width: number;
+}
+/** Right column owner share: resolved normal geometry and opening eligibility. */
+export interface RightbarOwnerProps {
+    /** Resolved normal panel width in px, not the saved preference; zero if it cannot fit. */
+    width: number;
+    /** Current frame width in px. */
+    viewportWidth: number;
+    /**
+     * Whether a normal right panel can retain 300px beside a 400px center.
+     * Before a narrow opening, includes the space from collapsing the left sidebar.
+     */
+    canShow: boolean;
+}
+/** Required services (cordis fiber inject — the loader passes all module exports as an object plugin). */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide ctx.layout, then one register() call — AppFrame
+ * into 'root' with the four child-slot declarations, the layout store seat,
+ * and the shared root instance supplying commands and the panel-info source.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/service.d.ts

@@ -0,0 +1,76 @@
+/**
+ * LayoutController: the cross-plugin panel-action face behind ctx.layout.
+ * Panel geometry and main-panel selection live in the root layout store;
+ * the current-session selection lives with the runtime sessions service, and
+ * the per-session active view dissolved into ui-conversation's session store
+ * (its only consumer). What remains here is the contract other plugins'
+ * apply worlds reach for panel transitions (main-panel selection and sidebar toggle,
+ * right-panel show/hide from ui-sidebar-right) — writes stay inside the
+ * store's declared action set, shared with the root registration.
+ */
+import type { BoundActions, HostObservable } from '@qilin-agent/client-ui-slots';
+import type { Branded } from '@qilin-agent/brand';
+import type { createLayoutStore } from './stores.ts';
+/** Identity shared by a sidebar panel entry and its main-slot occupant. */
+export type MainPanelId = Branded<'MainPanelId'>;
+/** Root-scoped navigation state exposed to panel-aware components. */
+export interface PanelInfo {
+    /** Selected global panel; null displays the current Conversation. */
+    readonly activePanelId: MainPanelId | null;
+}
+/** The layout store's bound action set (framework-baked, draft params peeled). */
+export type PanelActions = BoundActions<ReturnType<typeof createLayoutStore>>;
+/** Panel navigation and geometry actions exposed through ctx.layout. */
+export interface ILayout {
+    /** Selected central panel from the same root store used by `usePanelInfo`. */
+    readonly panelInfo: HostObservable<PanelInfo>;
+    /**
+     * Select a global central panel without changing the current Session.
+     * @param panelId - registered main key, or null to show the Conversation.
+     * @throws if the selected main key is not registered; preserves the current selection.
+     */
+    selectPanel(panelId: MainPanelId | null): void;
+    /**
+     * Start an asynchronous navigation, superseding any earlier pending navigation.
+     * @returns a signal aborted by the next navigation or layout disposal; check it before committing UI state.
+     */
+    beginNavigation(): AbortSignal;
+    /** Toggle the sidebar panel (closed ⟷ contract default width). */
+    toggleSidebar(): void;
+    /**
+     * Report the right panel's presentation without changing its expanded state.
+     * @param track - whether the normal panel width reserves a grid track,
+     *   including beneath a fullscreen overlay.
+     * @param fullscreen - whether the panel covers the frame and hides its outer
+     *   resize handle; independent of the underlying grid track.
+     */
+    openRightbar(track: boolean, fullscreen: boolean): void;
+    /** Report the right panel as hidden: no track, no handle. */
+    closeRightbar(): void;
+}
+/** Cross-plugin panel-action face (ctx.layout). */
+export declare class LayoutController implements ILayout {
+    private readonly panels;
+    private readonly hasMainPanel;
+    readonly panelInfo: HostObservable<PanelInfo>;
+    private navigation;
+    /**
+     * @param panels - actions of the instance shared with the root entry.
+     * @param hasMainPanel - checks the live main-slot registry for a panel id.
+     * @param panelInfo - root store's shared central-panel selection source.
+     */
+    constructor(panels: PanelActions, hasMainPanel: (id: MainPanelId) => boolean, panelInfo: HostObservable<PanelInfo>);
+    /** Select a global panel or return to the Conversation. */
+    selectPanel(panelId: MainPanelId | null): void;
+    /** @returns the new pending navigation's cancellation signal. */
+    beginNavigation(): AbortSignal;
+    /** Invalidate pending navigations when the layout owner is unloaded. */
+    dispose(): void;
+    /** Toggle the sidebar panel (closed ⟷ contract default width). */
+    toggleSidebar(): void;
+    /** Report the right panel's track and fullscreen presentation. */
+    openRightbar(track: boolean, fullscreen: boolean): void;
+    /** Report the right panel as hidden: no track, no handle. */
+    closeRightbar(): void;
+}
+//# sourceMappingURL=service.d.ts.map

package/lib/types/client/shortcut-locales.d.ts

@@ -0,0 +1,7 @@
+/** Layout command labels. */
+export declare const zh: {
+    toggle: string;
+};
+/** English labels for the same layout commands. */
+export declare const en: Record<keyof typeof zh, string>;
+//# sourceMappingURL=shortcut-locales.d.ts.map

package/lib/types/client/stores.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Root-owned frame measurement, panel preferences, and presentation reports.
+ * The registration supplies a fresh store and binds its actions to ctx.layout.
+ */
+import { type EngineStoreHandle } from '@qilin-agent/client-store';
+import type { MainPanelId } from './service.ts';
+/**
+ * Transient layout preferences. Responsive concessions never rewrite widths;
+ * the right panel's expanded state belongs to its occupant.
+ */
+type LayoutState = {
+    panelInfo: {
+        /** Null selects the Conversation; global panels keep the current Session intact. */
+        activePanelId: MainPanelId | null;
+    };
+    layoutInfo: LayoutInfo;
+};
+type LayoutInfo = {
+    sidebar: number;
+    /** Last positive frame measurement; window width bootstraps the first render. */
+    viewportWidth: number;
+    narrowExpanded: boolean;
+    /**
+     * Saved right panel width in px, or null before its first opening. Resizing
+     * the frame and closing the panel preserve this preference.
+     */
+    rightbar: number | null;
+    /**
+     * Whether the right panel is drawn at all, in either presentation.
+     *
+     * Derived chrome, not a source of truth: whether the right surface is
+     * expanded is a recorded fact owned by that surface, reported here so the
+     * frame can place the panel's resize handle. The occupant reports it; nothing
+     * else writes it.
+     */
+    rightbarShown: boolean;
+    /**
+     * Whether the normal panel width reserves a grid track, including beneath
+     * fullscreen. Reported by the occupant; always false while hidden.
+     */
+    rightbarTrack: boolean;
+    /** Reported fullscreen presentation; hides the outer resize handle. */
+    rightbarFullscreen: boolean;
+    /** Suppress transitions for a fullscreen exit until another geometry action. */
+    rightbarInstant: boolean;
+};
+/**
+ * Annotation twin of the actions literal below (the export needs a declared
+ * return type); drift fails assignability at the defineStore call.
+ */
+type LayoutActions = {
+    selectPanel: (draft: LayoutState, panelId: MainPanelId | null) => void;
+    retainMainPanels: (draft: LayoutState, panelIds: readonly string[]) => void;
+    setSidebar: (draft: LayoutState, px: number) => void;
+    toggleSidebar: (draft: LayoutState) => void;
+    setViewportWidth: (draft: LayoutState, width: number) => void;
+    setRightbar: (draft: LayoutState, px: number) => void;
+    openRightbar: (draft: LayoutState, track: boolean, fullscreen: boolean) => void;
+    closeRightbar: (draft: LayoutState) => void;
+};
+/**
+ * Create the layout panel store handle. For the sidebar the preference IS the
+ * width, so closing it forgets its drag width — reopening restores the contract
+ * default. The right panel initializes at 35% of the frame on first opening
+ * and keeps that px preference across resizes and close. Drag writes clamp to
+ * the current frame's range. Narrow sidebar toggles change only the expansion
+ * override; opening the right panel clears that override.
+ * @returns the store handle (spec + type + identity + factory in one).
+ */
+export declare function createLayoutStore(): EngineStoreHandle<LayoutState, LayoutActions>;
+export {};
+//# sourceMappingURL=stores.d.ts.map

package/lib/types/client/theme-presenter.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Global theme DOM applier: projects the resolved ThemeSnapshot onto the
+ * document — `html { color-scheme }` for native UA chrome (scrollbars, form
+ * controls), `body[data-ds-dark-theme]` for the token palette, the active
+ * theme's alias-token overrides as inline CSS variables on body, the content
+ * font-size axis (`--qilin-content-font-size`), `html[data-ds-theme-source]` for native-chrome
+ * mirroring, and one presenter-owned `meta[name="theme-color"]` for surrounding
+ * browser UI. Pure DOM writes, no
+ * React involvement; the presenter only ever retracts what it wrote itself,
+ * so foreign attributes, metadata, and inline styles survive.
+ */
+import type { ThemeSnapshot } from '@qilin-agent/client-ui-theme/client';
+/** Body attribute selecting the dark base palette in the token stylesheets. */
+export declare const DARK_ATTRIBUTE = "data-ds-dark-theme";
+/**
+ * Root attribute publishing the theme source (`light`, `dark`, or `system`)
+ * for host shells that mirror it into native window chrome (the Electron
+ * preload forwards it to `nativeTheme.themeSource` so macOS vibrancy follows
+ * the app theme). `system` only when the preference is `system`; a fixed
+ * preference (including registered theme ids) publishes its resolved scheme.
+ */
+export declare const THEME_SOURCE_ATTRIBUTE = "data-ds-theme-source";
+/** Body variable carrying the user's content font size in px. */
+export declare const CONTENT_FONT_SIZE_VARIABLE = "--qilin-content-font-size";
+/** Applies theme snapshots to the document; one instance per plugin fiber. */
+export declare class ThemePresenter {
+    /** Token names this presenter wrote in the last apply (its retraction set). */
+    private appliedTokens;
+    /** The single metadata node this presenter inserts and removes. */
+    private readonly themeColorMeta;
+    /** Create the presenter-owned metadata node before the first snapshot arrives. */
+    constructor();
+    /**
+     * Project a snapshot onto the document: set root `color-scheme` and the body
+     * palette attribute from `active.colorScheme` (never the id — `system` is
+     * resolved upstream), publish the content font-size axis, then
+     * replace the previously applied token variables with `active.tokens`.
+     * Browser theme-color metadata follows the computed body background after
+     * those writes, so the rendered palette remains the color authority.
+     * @param snapshot - resolved theme snapshot from ctx.theme.
+     */
+    apply(snapshot: ThemeSnapshot): void;
+    /**
+     * Retract root color-scheme, the theme-source attribute, the palette attribute, token variables,
+     * the content axes, and the owned metadata node.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=theme-presenter.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,4 @@
+/** Host loader entry for the browser-only layout plugin. */
+/** Provides no host-side behavior. */
+export declare function apply(): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@qilin-agent/client-ui-layout",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Shell plugin: three-column AppFrame with drag handles, ctx.layout viewing-state service (navigation + panels)",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/client/ui-layout"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "qilin": {
+    "client": {
+      "inject": [
+        "@qilin-agent/client-locale",
+        "@qilin-agent/client-shortcuts",
+        "@qilin-agent/client-ui-renderer",
+        "@qilin-agent/client-ui-session",
+        "@qilin-agent/client-ui-theme"
+      ],
+      "platform": "web"
+    }
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@qilin-agent/brand": "3.1.4",
+    "@qilin-agent/client-locale": "3.1.4",
+    "@qilin-agent/client-store": "3.1.4",
+    "@qilin-agent/client-ui-session": "3.1.4",
+    "@qilin-agent/client-ui-slots": "3.1.4",
+    "@qilin-agent/client-ui-renderer": "3.1.4",
+    "@qilin-agent/client-ui-theme": "3.1.4",
+    "@qilin-agent/client-shortcuts": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
 }