@funnest/charts-ui 0.4.0 → 0.5.0

package/dist/layouts.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Split layouts for the multi-chart widget, as trees: a leaf is a pane index, a split lays
+ * its children out in a row (side by side) or a column (stacked). Pure data — rendering
+ * lives in multi-chart.tsx.
+ */
+export type SplitNode = number | {
+    dir: 'row' | 'col';
+    children: SplitNode[];
+};
+export type LayoutId = '1' | '2-cols' | '2-rows' | '3-cols' | '3-rows' | '3-left' | '3-top' | '4-grid' | '4-cols' | '4-left' | '6-grid' | '8-grid';
+export declare const LAYOUTS: Record<LayoutId, SplitNode>;
+/** Menu order, grouped by pane count. */
+export declare const LAYOUT_GROUPS: readonly (readonly LayoutId[])[];
+export declare const MAX_PANES = 8;
+export declare function isLayoutId(value: unknown): value is LayoutId;
+export declare function paneCount(node: SplitNode): number;
+/**
+ * Flex weights per split, keyed by `layoutId:path` (path = child indices from the root, e.g.
+ * '4-grid:1' is the bottom row of the 2×2 grid). Missing entries mean equal sizes.
+ */
+export type SplitSizes = Record<string, number[]>;
+export declare function sizesFor(sizes: SplitSizes, key: string, count: number): number[];
+/**
+ * Moves the boundary between children `i` and `i + 1` by `deltaFraction` of the split's
+ * length. Neither side shrinks below `min` of the pair's total.
+ */
+export declare function resizePair(weights: readonly number[], i: number, deltaFraction: number, min?: number): number[];
+/** Small SVG preview of a layout for menus (rects in a 20×16 box). */
+export declare function layoutRects(node: SplitNode, x?: number, y?: number, w?: number, h?: number, gap?: number): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}[];

package/dist/multi-chart.d.ts

@@ -0,0 +1,78 @@
+/** @jsxImportSource preact */
+import { type Chart, type ChartState, type Locale, type Resolution, type ThemeTokens } from '@funnest/charts';
+import type { LayoutSync } from './context';
+import { type LayoutId, type SplitSizes } from './layouts';
+import { type ColorScheme, type TradingChartSlots } from './shell';
+import { type TradingChartOptions } from './trading-chart';
+export interface PaneSpec {
+    symbol: string;
+    /** Default: the widget's `resolution`, else '1D'. */
+    resolution?: Resolution;
+}
+export interface MultiChartOptions extends Omit<TradingChartOptions, 'symbol'> {
+    /**
+     * Initial panes, in layout order (up to 8). Panes the layout needs beyond this list open
+     * the active pane's symbol.
+     */
+    panes: readonly PaneSpec[];
+    /** Initial split. Default '1'. */
+    layout?: LayoutId;
+    /** Default: crosshair on, everything else off. */
+    sync?: Partial<LayoutSync>;
+    /** Below this container width only the active pane shows, with tabs to switch. Default 640. */
+    narrowWidth?: number;
+}
+/** Everything `load()` needs to rebuild the widget: split, sync, sizes and every pane's chart. */
+export interface MultiChartState {
+    version: 1;
+    layout: LayoutId;
+    sync: LayoutSync;
+    active: number;
+    sizes: SplitSizes;
+    panes: ChartState[];
+}
+export interface MultiChartEvents {
+    /** The pane the toolbar acts on changed. */
+    activeChange: {
+        index: number;
+        chart: Chart;
+    };
+    /** Split layout or pane count changed. */
+    layoutChange: {
+        layout: LayoutId;
+        panes: number;
+    };
+    /** Something worth persisting changed in any pane or in the layout — a hook for autosave. */
+    stateChange: void;
+}
+export interface MultiChart {
+    readonly slots: TradingChartSlots;
+    /** Engines of the visible panes, in layout order. */
+    readonly charts: readonly Chart[];
+    /** The pane the toolbar, drawing bar and `setSymbol` act on. */
+    readonly activeChart: Chart;
+    readonly activeIndex: number;
+    readonly layout: LayoutId;
+    readonly sync: LayoutSync;
+    setLayout(layout: LayoutId): void;
+    setSync(patch: Partial<LayoutSync>): void;
+    activate(index: number): void;
+    /** Fill the grid with one pane (default: the active one); call again to go back. */
+    toggleMaximize(index?: number): void;
+    /** Opens a symbol in the active pane (and every pane, with symbol sync on). */
+    setSymbol(symbol: string, resolution?: Resolution): Promise<void>;
+    setResolution(resolution: Resolution): Promise<void>;
+    setLocale(locale: Locale): void;
+    setTheme(theme: Partial<ThemeTokens>): void;
+    setColorScheme(scheme: ColorScheme): void;
+    save(): MultiChartState;
+    load(state: MultiChartState | unknown): Promise<void>;
+    on<K extends keyof MultiChartEvents>(event: K, listener: (payload: MultiChartEvents[K]) => void): () => void;
+    destroy(): void;
+}
+/**
+ * Several linked charts in one split layout (1–8 panes) sharing one toolbar and drawing bar
+ * that act on the active pane. Clicking a pane activates it; Alt+1…8 too, Alt+Enter maximizes.
+ * Crosshair, time range, symbol and interval can be synced across panes.
+ */
+export declare function createMultiChart(container: HTMLElement, options: MultiChartOptions): MultiChart;

package/dist/pane.d.ts

@@ -0,0 +1,33 @@
+/** @jsxImportSource preact */
+import { type Chart, type ChartOptions, type ChartType, type Datafeed, type Resolution } from '@funnest/charts';
+import type { IntervalGroup, MultiControls, SearchCategory, UiState, WidgetContext } from './context';
+import { type Shell } from './shell';
+import { Store } from './store';
+export interface PaneConfig {
+    datafeed: Datafeed;
+    chartOptions: Omit<ChartOptions, 'datafeed' | 'theme'>;
+    displayTimezone: string;
+    resolution: Resolution;
+    chartType: ChartType;
+    intervalGroups: readonly IntervalGroup[];
+    searchCategories: readonly SearchCategory[];
+    symbolLogo: boolean;
+    drawingToolbar: boolean;
+    attribution: boolean;
+    multi?: MultiControls | undefined;
+}
+/**
+ * One chart with its legend/navigation overlay and UI state. The toolbar and drawing bar
+ * belong to the shell and are pointed at whichever pane is active.
+ */
+export interface Pane {
+    /** `.fnc-stage`: chart canvas + overlay. The owner places it in the layout. */
+    readonly stage: HTMLElement;
+    readonly chart: Chart;
+    readonly store: Store<UiState>;
+    readonly ctx: WidgetContext;
+    readonly canSearch: boolean;
+    load(symbol: string, resolution: Resolution): Promise<void>;
+    destroy(): void;
+}
+export declare function createPane(shell: Shell, config: PaneConfig): Pane;

package/dist/shell.d.ts

@@ -0,0 +1,77 @@
+import { type Resolution, type ThemeTokens } from '@funnest/charts';
+import type { UiState } from './context';
+import { type WidgetStorage } from './storage';
+import type { Store } from './store';
+export type ColorScheme = 'light' | 'dark' | 'system';
+/**
+ * Empty elements inside the widget layout where the host app mounts its own UI (any framework):
+ * market stats, account info, status bars… They inherit the widget's `--fnc-*` theme variables
+ * and collapse when empty.
+ */
+export interface TradingChartSlots {
+    /** In the toolbar row, after the interval buttons. */
+    readonly toolbar: HTMLElement;
+    /** Right end of the toolbar, next to the settings (gear) button — for extra icon buttons. */
+    readonly toolbarEnd: HTMLElement;
+    /** A full-width row under the toolbar. */
+    readonly belowToolbar: HTMLElement;
+    /**
+     * Under the chart, right of the drawing bar — for an account/positions panel that should
+     * line up with the chart while the drawing bar keeps the full height (TradingView-style).
+     * The host sets its height.
+     */
+    readonly bottom: HTMLElement;
+    /** A full-width row under everything (status bar). */
+    readonly footer: HTMLElement;
+}
+export declare function div(className: string, parent?: HTMLElement): HTMLDivElement;
+/** What the shell needs from a chart pane (see pane.tsx). */
+export interface ShellPane {
+    readonly store: Store<UiState>;
+    readonly chart: {
+        setTheme(theme: Partial<ThemeTokens>): void;
+    };
+}
+export interface ShellOptions {
+    colorScheme: ColorScheme;
+    theme: Partial<ThemeTokens> | undefined;
+    storageKey: string | null;
+    drawingToolbar: boolean;
+    favoriteIntervals: readonly Resolution[];
+    onFavoriteIntervalsChange?: ((intervals: Resolution[]) => void) | undefined;
+}
+/**
+ * The frame around one or more chart panes: root element with theme variables, toolbar host,
+ * slots, drawing-bar host, fullscreen, and the preferences every pane shares (favorite
+ * intervals, folded drawing bar). Panes register through `setPanes`.
+ */
+export interface Shell {
+    readonly root: HTMLElement;
+    readonly toolbarHost: HTMLElement;
+    readonly body: HTMLElement;
+    readonly drawbarHost: HTMLElement | null;
+    /** Column right of the drawing bar: put the chart stage (or pane grid) here, before `slots.bottom`. */
+    readonly main: HTMLElement;
+    readonly slots: TradingChartSlots;
+    readonly storage: WidgetStorage;
+    theme(): ThemeTokens;
+    /** Initial UI-state fields owned by the shell (same for every pane). */
+    sharedState(): Pick<UiState, 'fullscreen' | 'favoriteIntervals' | 'drawbarCollapsed'>;
+    setPanes(panes: () => readonly ShellPane[]): void;
+    setTheme(patch: Partial<ThemeTokens>): void;
+    setColorScheme(scheme: ColorScheme): void;
+    isFullscreen(): boolean;
+    toggleFullscreen(): void;
+    setDrawbarCollapsed(collapsed: boolean): void;
+    toggleFavoriteInterval(resolution: Resolution): void;
+    destroy(): void;
+}
+export declare function createShell(container: HTMLElement, options: ShellOptions): Shell;
+/**
+ * Ctrl/⌘+K and Escape handling for the pane that currently owns the toolbar.
+ * Returns a cleanup function.
+ */
+export declare function bindWidgetKeys(shell: Shell, active: () => {
+    store: Store<UiState>;
+    canSearch: boolean;
+} | null, searchHotkey: boolean, extra?: (e: KeyboardEvent) => boolean): () => void;

package/dist/trading-chart.d.ts

@@ -1,6 +1,8 @@
 /** @jsxImportSource preact */
 import { type Chart, type ChartOptions, type ChartType, type Datafeed, type Locale, type ChartState, type Resolution, type ThemeTokens } from '@funnest/charts';
 import type { IntervalGroup, SearchCategory } from './context';
+import { type ColorScheme, type TradingChartSlots } from './shell';
+export type { ColorScheme, TradingChartSlots } from './shell';
 /** Interval menu: 분 | 시간 | 일. '12M' is shown as 1년. */
 export declare const DEFAULT_INTERVAL_GROUPS: readonly IntervalGroup[];
 /** Toolbar chips until the user stars their own. */
@@ -44,22 +46,6 @@ export interface TradingChartOptions extends Omit<ChartOptions, 'datafeed'> {
      */
     colorScheme?: ColorScheme;
 }
-export type ColorScheme = 'light' | 'dark' | 'system';
-/**
- * Empty elements inside the widget layout where the host app mounts its own UI (any framework):
- * market stats, account info, status bars… They inherit the widget's `--fnc-*` theme variables
- * and collapse when empty.
- */
-export interface TradingChartSlots {
-    /** In the toolbar row, after the interval buttons. */
-    readonly toolbar: HTMLElement;
-    /** Right end of the toolbar, next to the settings (gear) button — for extra icon buttons. */
-    readonly toolbarEnd: HTMLElement;
-    /** A full-width row under the toolbar. */
-    readonly belowToolbar: HTMLElement;
-    /** A full-width row under the chart. */
-    readonly footer: HTMLElement;
-}
 export interface TradingChart {
     /** The underlying engine, for anything the widget doesn't wrap. */
     readonly chart: Chart;
@@ -76,6 +62,8 @@ export interface TradingChart {
     load(state: ChartState | unknown): Promise<void>;
     destroy(): void;
 }
+/** Korean users read every time in KST unless told otherwise. */
+export declare function defaultDisplayTimezone(locale: Locale, explicit?: string): string;
 /**
  * Full trading chart widget: toolbar (symbol search, intervals, screenshot, fullscreen),
  * legend, navigation controls and the canvas engine. Framework-agnostic: mount into any element.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@funnest/charts-ui",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pro trading UI (toolbar, drawing tools, sheets) for Funnest Charts. Framework-agnostic.",
   "keywords": [
     "chart",
@@ -42,7 +42,7 @@
     "NOTICE"
   ],
   "dependencies": {
-    "@funnest/charts": "0.4.0"
+    "@funnest/charts": "0.5.0"
   },
   "devDependencies": {
     "preact": "^11.2.0"