react-semaphor 0.1.545 → 0.1.547

package/dist/types/shared/dashboard-authoring/semantic-auto-join-card.d.ts

@@ -0,0 +1,22 @@
+import { TFilterValue } from '../../components/surfboard/filter/types.js';
+import { TCard } from '../../lib/types/common-types.js';
+/**
+ * Where relationship filter reach runs (relationship filter reach RF-D18): a
+ * card on a semantic domain with no explicit join plan. The join plan is read
+ * as the card's filter source index reads it: a Matrix card's from its spec,
+ * every other card's from its config. The browser decides only whether to
+ * send a value (`decideDashboardFilterCardTarget`, `relationship`); the server
+ * decides reach through the domain's relationships. Both call this.
+ */
+export declare function isSemanticAutoJoinCard(card: Pick<TCard, 'type' | 'dataSource' | 'config'> & {
+    sql?: string;
+    python?: string;
+}): boolean;
+/**
+ * The one semantic dataset a filter value's field reads, with its domain:
+ * undefined when the value names no dataset, several, or no semantic domain.
+ */
+export declare function filterValueSemanticDataset(value: Pick<TFilterValue, 'fieldMeta' | 'semanticContext'>): {
+    domainId: string;
+    datasetName: string;
+} | undefined;

package/dist/types/shared/dashboard-authoring/validators.d.ts

@@ -1,3 +1,2 @@
-import { DashboardAuthoringValidationResult, DashboardChangePlan, DashboardPlan } from './contracts.js';
+import { DashboardAuthoringValidationResult, DashboardPlan } from './contracts.js';
 export declare function validateDashboardPlan(plan: DashboardPlan): DashboardAuthoringValidationResult;
-export declare function validateDashboardChangePlan(plan: DashboardChangePlan): DashboardAuthoringValidationResult;

package/dist/types/shared/layouts/engine/grid.d.ts

@@ -0,0 +1,25 @@
+import { Breakpoint, CustomizableBreakpoint } from '../../../lib/types/common-types.js';
+/**
+ * The dashboard grid's breakpoints and columns: the only place these values
+ * exist (responsive layouts SPEC §2.1, RL-INV-1).
+ */
+export type { CustomizableBreakpoint };
+/** Breakpoints the editor can edit: Desktop, Tablet, Phone (RL-D11, RL-D14). */
+export type EditableBreakpoint = 'lg' | CustomizableBreakpoint;
+/** Breakpoints a grid edit can arrive at: the editable ones, and `md`, an edit of Desktop at laptop width (RL-D17). */
+export type GridEditBreakpoint = EditableBreakpoint | 'md';
+export declare const DASHBOARD_GRID: {
+    /** Widest first. */
+    readonly breakpoints: readonly Breakpoint[];
+    readonly columns: Readonly<Record<Breakpoint, number>>;
+    /** react-grid-layout's default breakpoint widths, now stated. */
+    readonly minContainerWidthPx: Readonly<Record<Breakpoint, number>>;
+    readonly editable: readonly EditableBreakpoint[];
+    readonly customizable: readonly CustomizableBreakpoint[];
+    /** The preview canvas widths: Laptop, Tablet, Phone, Small phone (Desktop is at least `minContainerWidthPx.lg`; RL-D19). */
+    readonly previewWidthPx: Readonly<Record<Exclude<Breakpoint, "lg">, number>>;
+};
+export declare const LG_COLUMNS: number;
+export declare function isCustomizableBreakpoint(value: unknown): value is CustomizableBreakpoint;
+export declare function isEditableBreakpoint(value: unknown): value is EditableBreakpoint;
+export declare function isGridEditBreakpoint(value: unknown): value is GridEditBreakpoint;

package/dist/types/shared/layouts/engine/index.d.ts

@@ -0,0 +1,4 @@
+export { DASHBOARD_GRID } from './grid.js';
+export type { CustomizableBreakpoint, EditableBreakpoint, GridEditBreakpoint } from './grid.js';
+export type { FramePlacement, FramePosition, FrameWidth, LayoutItem, LayoutKind, SheetLayoutChange, SheetLayoutFailure, SheetLayoutInput, SheetLayoutResult, SheetLayoutRow, SheetLayouts, SheetLayoutTile, SheetLayoutView, } from './types.js';
+export { applySheetLayoutChange, assertSheetLayouts, readSheetLayout } from './sheet-layout.js';

package/dist/types/shared/layouts/engine/sheet-layout.d.ts

@@ -0,0 +1,7 @@
+import { SheetLayoutChange, SheetLayoutInput, SheetLayoutResult, SheetLayouts, SheetLayoutView } from './types.js';
+/** Every layout read (SPEC §3.2): complete, valid layouts; customized breakpoints, stored or inferred; `lg` as rows. Never fails. */
+export declare function readSheetLayout(sheet: SheetLayoutInput): SheetLayoutView;
+/** Every layout write (SPEC §3.1). `sheet` is the sheet before the change. */
+export declare function applySheetLayoutChange(sheet: SheetLayoutInput, change: SheetLayoutChange): SheetLayoutResult;
+/** Throws when layouts break invariants 1 to 4 (complete, in bounds, no overlaps, packed). For tests and development builds. */
+export declare function assertSheetLayouts(layouts: SheetLayouts, frameIds: readonly string[]): void;

package/dist/types/shared/layouts/engine/types.d.ts

@@ -0,0 +1,125 @@
+import { Breakpoint, TFrame, TSheet } from '../../../lib/types/common-types.js';
+import { CustomizableBreakpoint, GridEditBreakpoint } from './grid.js';
+/** One frame's tile on one breakpoint. The keys the dirty check persists (`PERSISTED_LAYOUT_KEYS`). */
+export type LayoutItem = {
+    /** The frame id. */
+    i: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    static?: boolean;
+    isResizable?: boolean;
+    isDraggable?: boolean;
+};
+/** Complete layouts: every breakpoint present. What the engine returns. */
+export type SheetLayouts = Record<Breakpoint, LayoutItem[]>;
+/** What the engine reads from a sheet. */
+export type SheetLayoutInput = Pick<TSheet, 'id' | 'frames' | 'layouts' | 'layout' | 'customizedBreakpoints'>;
+/** How a frame is sized and grouped (SPEC §2.4). */
+export type LayoutKind = 'kpi' | 'chart' | 'table' | 'text';
+/** A width by intent, as a share of the 48 `lg` columns: full 48, half 24, third 16, quarter 12. */
+export type FrameWidth = 'full' | 'half' | 'third' | 'quarter';
+/** Where a new frame goes on `lg`. Ids are frame ids. */
+export type FramePosition = 'top' | 'end' | {
+    after: string;
+} | {
+    beside: string;
+};
+/** How a caller states a new frame's place. Absent: placed by kind (SPEC §4.2). */
+export type FramePlacement = {
+    position?: FramePosition;
+    width?: FrameWidth;
+};
+export type SheetLayoutChange = 
+/** A new frame, not in `sheet.frames` yet. Without `placement`: by kind. */
+{
+    kind: 'frame_added';
+    frame: TFrame;
+    placement?: FramePlacement;
+}
+/** A frame in `sheet.frames` that leaves the sheet. */
+ | {
+    kind: 'frame_removed';
+    frameId: string;
+}
+/** A frame's content changed: the frame after the change, same id, in `sheet.frames`. */
+ | {
+    kind: 'frame_updated';
+    frame: TFrame;
+    resizeForNewKind: boolean;
+}
+/** The grid's items after a drag or resize stop at the breakpoint being edited. */
+ | {
+    kind: 'grid_edited';
+    breakpoint: GridEditBreakpoint;
+    items: readonly LayoutItem[];
+}
+/** "Back to automatic" for one customized breakpoint. */
+ | {
+    kind: 'reset_to_automatic';
+    breakpoint: CustomizableBreakpoint;
+}
+/** Arrange the sheet. */
+ | {
+    kind: 'arrange';
+    keepOrder?: boolean;
+};
+export type SheetLayoutFailure = {
+    code: 'frame_not_on_sheet';
+    frameId: string;
+    message: string;
+} | {
+    code: 'frame_already_on_sheet';
+    frameId: string;
+    message: string;
+} | {
+    code: 'position_target_not_found';
+    frameId: string;
+    message: string;
+} | {
+    code: 'breakpoint_not_editable';
+    breakpoint: string;
+    message: string;
+};
+export type SheetLayoutResult = {
+    ok: true;
+    /** The sheet's frames in their new order; the input array itself when untouched. */
+    frames: TFrame[];
+    layouts: SheetLayouts;
+    customizedBreakpoints: CustomizableBreakpoint[];
+    /** False when `frames`, `layouts` and `customizedBreakpoints` equal what `readSheetLayout(sheet)` gives. */
+    changed: boolean;
+    /**
+     * False when `layouts` and `customizedBreakpoints` equal the view's. Callers write them only when
+     * true, so a change with no layout effect (a frame update keeping its kind) leaves stored layouts
+     * untouched: a no-op editor Done stays clean (V-50).
+     */
+    layoutsChanged: boolean;
+} | {
+    ok: false;
+    failure: SheetLayoutFailure;
+};
+/** `width`: the `FrameWidth` whose column count is nearest the item's `lg` `w`; a tie goes to the wider. */
+export type SheetLayoutTile = {
+    frameId: string;
+    kind: LayoutKind;
+    width: FrameWidth;
+};
+export type SheetLayoutRow = {
+    tiles: SheetLayoutTile[];
+};
+export type SheetLayoutView = {
+    /** Complete and valid on every breakpoint; what the grid renders. */
+    layouts: SheetLayouts;
+    /** Stored `customizedBreakpoints`, or inferred when absent (SPEC §4.6). */
+    customizedBreakpoints: CustomizableBreakpoint[];
+    /** The `lg` layout as rows, top to bottom, tiles left to right. */
+    rows: SheetLayoutRow[];
+    /** True when `layouts` differs from what is stored. */
+    repaired: boolean;
+};

package/dist/types/shared/layouts/index.d.ts

@@ -1,2 +1 @@
-export * from './create-frame-layouts.js';
-export * from './frame-layouts.js';
+export * from './engine/index.js';

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.545",
+  "version": "0.1.547",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",
@@ -123,7 +123,7 @@
     "build": "node scripts/build.mjs",
     "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
     "lint:regressions": "node scripts/lint-regressions.mjs",
-    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs",
+    "check:guards": "node scripts/card-config-consumers.mjs && node scripts/components-entry-imports.mjs && node scripts/types-entry-imports.mjs && node scripts/card-query-assembly-imports.mjs && node scripts/assistant-chat-imports.mjs && node scripts/filter-model-reads.mjs && node scripts/layout-engine.mjs",
     "preview": "vite preview",
     "test": "vitest run",
     "test:changed": "vitest run --changed",