react-semaphor 0.1.544 → 0.1.546

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/format-utils/exporters/index.d.ts

@@ -2,6 +2,8 @@ export { CSV_ENCODINGS, DEFAULT_CSV_ENCODING, CSV_DELIMITERS, CSV_RECORD_SEPARAT
 export type { CsvEncoding, CsvDelimiter, CsvCell } from './csv-utils.js';
 export { EXPORT_FILE_FORMATS, XLSX_CONTENT_TYPE, parseExportFileFormat, exportFileTraits, exportFileFormatFromStored, exportFileFormatFromContentType, exportFileName, } from './export-file-format.js';
 export type { ExportFileFormat, ExportFileTraits } from './export-file-format.js';
+export { EMAIL_IMAGE_DASHBOARD_WIDTH, IMAGE_CAPTURE_LIMITS, RENDERED_FILE_KINDS, cardImageSize, parseImageCaptureRequest, writeImageCaptureRequest, planImageViewport, renderedFileTraits, renderedFileName, sheetImageEntryName, } from './rendered-file.js';
+export type { ImageCaptureRequest, ImageViewport, ImageViewportPlan, RenderedFileKind, RenderedFileTraits, } from './rendered-file.js';
 export { resolveXlsxColumn, exportCellText } from './export-cells.js';
 export type { ExportDataType, XlsxColumnInput, XlsxColumnPresentation, XlsxColumn, ExportCell, ExportWallClock, } from './export-cells.js';
 export { XlsxLimitError, isXlsxLimitError, XLSX_LIMIT_FAILURE_REASONS, xlsxLimitFailureReason, assertXlsxColumnCount, defineXlsxSheet, serializeXlsxSheet, parseXlsxSheet, withXlsxSheetColumns, serializeXlsxColumns, parseXlsxColumns, xlsxColumnsFingerprint, encodeXlsxFile, encodeXlsxRows, streamXlsxFile, } from './xlsx-file.js';

package/dist/types/shared/format-utils/exporters/rendered-file.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The rendered file contract: what a file the renderer draws from the print
+ * view (a PDF or a PNG image, or a zip of sheet images) is called and typed
+ * as, and how big an image is. The browser, the app and the renderer (through
+ * its generated bundle) all read and write the image size through this module,
+ * so its limits and URL parameter names have one owner. See the PNG exports
+ * plan (semaphor-app docs/implementation-plans/png-exports, SPEC §2.1 to §2.3).
+ * IMPORTANT: No React or browser-specific imports allowed
+ */
+/** How big the image is. Every number is CSS pixels. */
+export type ImageCaptureRequest = 
+/** A downloaded card: its size on the viewer's screen, measured at the click. */
+{
+    fit: 'card';
+    cssWidth: number;
+    cssHeight: number;
+}
+/** An emailed card: the print page sizes it from its saved layout on a dashboard this wide (PN-D13). */
+ | {
+    fit: 'layout';
+    dashboardWidth: number;
+}
+/** A dashboard sheet: the width is the viewer's (or the reference width); the renderer measures the height. */
+ | {
+    fit: 'sheet';
+    cssWidth: number;
+};
+/** The dashboard width an emailed card or sheet is drawn at (PN-D13). */
+export declare const EMAIL_IMAGE_DASHBOARD_WIDTH = 1280;
+export declare const IMAGE_CAPTURE_LIMITS: {
+    readonly minCssWidth: 320;
+    readonly minCssHeight: 120;
+    readonly maxCardCssWidth: 4096;
+    readonly maxCardCssHeight: 4096;
+    readonly maxSheetCssWidth: 4096;
+    /** Chromium's largest capture in device pixels, either side. */
+    readonly maxDevicePixels: 16384;
+};
+type ParamSource = URLSearchParams | Readonly<Record<string, string | undefined>>;
+/** A card image's size, rounded and clamped to the card limits: the clamp the browser, the page and the renderer share. */
+export declare function cardImageSize(input: {
+    cssWidth: number;
+    cssHeight: number;
+}): {
+    cssWidth: number;
+    cssHeight: number;
+};
+/**
+ * Reads a request from URL parameters (`imageFit`, `imageWidth`, `imageHeight`;
+ * `imageWidth` is the dashboard width for `layout`)
+ * and clamps it. Null when a parameter is missing, not an integer, or does
+ * not match the fit. The browser, the app and the renderer read and write
+ * these parameters through this module only.
+ */
+export declare function parseImageCaptureRequest(params: ParamSource): ImageCaptureRequest | null;
+export declare function writeImageCaptureRequest(request: ImageCaptureRequest, params: URLSearchParams): void;
+export type ImageViewport = {
+    width: number;
+    height: number;
+    deviceScaleFactor: 1 | 2;
+};
+export type ImageViewportPlan = {
+    status: 'ready';
+    viewport: ImageViewport;
+}
+/** Even at scale 1 a side is over `maxDevicePixels`. */
+ | {
+    status: 'too_large';
+    cssWidth: number;
+    cssHeight: number;
+};
+/**
+ * The renderer's viewport. For `card`, the request's own size. For `layout`,
+ * the dashboard width by 1,024; the page sizes the card and the renderer
+ * captures the card's element. For `sheet`, `measuredCssHeight` is the
+ * sheet's full height after every card loaded; required for a sheet (throws
+ * without it), ignored otherwise.
+ */
+export declare function planImageViewport(request: ImageCaptureRequest, measuredCssHeight?: number): ImageViewportPlan;
+/** The kind of file a render produces. CSV keeps its own traits (`exportFileTraits`). */
+export type RenderedFileKind = 'pdf' | 'png' | 'zip';
+export type RenderedFileTraits = {
+    kind: RenderedFileKind;
+    extension: 'pdf' | 'png' | 'zip';
+    contentType: 'application/pdf' | 'image/png' | 'application/zip';
+    /** The customer's name for the format in dialogs and attachment lists. */
+    label: 'PDF' | 'PNG image' | 'PNG images (zip)';
+};
+export declare const RENDERED_FILE_KINDS: readonly ["pdf", "png", "zip"];
+export declare function renderedFileTraits(kind: RenderedFileKind): RenderedFileTraits;
+/**
+ * The saved file's name: `<title>-<ISO instant>.<extension>`, `Report` for an
+ * empty title. For kind `pdf` it equals today's inline name in
+ * `download-pdf.ts`. Used by the browser for every rendered file.
+ */
+export declare function renderedFileName(input: {
+    kind: RenderedFileKind;
+    title: string | null | undefined;
+    at: Date;
+}): string;
+/** One sheet's entry in an all-sheets zip: `01 Revenue.png`; position is 1-based, at least two digits; the title sanitized for a file name. */
+export declare function sheetImageEntryName(input: {
+    position: number;
+    title: string | null | undefined;
+}): string;
+export {};

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.544",
+  "version": "0.1.546",
   "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",
+    "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",

package/dist/chunks/_commonjsHelpers-BkfeUUK-.js

@@ -1,28 +0,0 @@
-var u = typeof globalThis < "u" ? globalThis : typeof window < "u" ? window : typeof global < "u" ? global : typeof self < "u" ? self : {};
-function f(e) {
-  return e && e.__esModule && Object.prototype.hasOwnProperty.call(e, "default") ? e.default : e;
-}
-function l(e) {
-  if (e.__esModule) return e;
-  var r = e.default;
-  if (typeof r == "function") {
-    var t = function o() {
-      return this instanceof o ? Reflect.construct(r, arguments, this.constructor) : r.apply(this, arguments);
-    };
-    t.prototype = r.prototype;
-  } else t = {};
-  return Object.defineProperty(t, "__esModule", { value: !0 }), Object.keys(e).forEach(function(o) {
-    var n = Object.getOwnPropertyDescriptor(e, o);
-    Object.defineProperty(t, o, n.get ? n : {
-      enumerable: !0,
-      get: function() {
-        return e[o];
-      }
-    });
-  }), t;
-}
-export {
-  l as a,
-  u as c,
-  f as g
-};