@shamar/core 1.0.6 → 1.0.8

package/dist/dashboard-page.d.ts

@@ -1,5 +1,7 @@
 import { Page } from './page.js';
+import { FormBuilder } from './form.js';
 import type { WidgetClass } from './widget.js';
+import type { FormSchema, SchemaNode } from './types.js';
 /** Reserved slug — dashboard pages are not registered as `/:slug` routes. */
 export declare const DASHBOARD_PAGE_SLUG = "__dashboard__";
 /**
@@ -13,8 +15,33 @@ export declare abstract class DashboardPage extends Page {
     /** Responsive grid columns for widget layout (1–4). */
     static columns: number;
     static widgets(): WidgetClass[];
+    /**
+     * Optional filters form (Filament `HasFiltersForm` / `getFiltersForm`).
+     * Submitted via GET on the dashboard; values land in `WidgetRequestContext.filters`.
+     *
+     * @example
+     * ```ts
+     * static override filtersForm(form: FormBuilder) {
+     *   return form.schema([
+     *     Select.make('period').options([
+     *       { label: 'Today', value: 'today' },
+     *       { label: 'MTD', value: 'mtd' },
+     *     ]).default('today'),
+     *   ])
+     * }
+     * ```
+     */
+    static filtersForm(_form: FormBuilder): FormBuilder | FormSchema | void;
 }
 export type DashboardPageClass = typeof DashboardPage;
 /** True when `value` is DashboardPage or a subclass. */
 export declare function isDashboardPage(value: unknown): value is DashboardPageClass;
+/** Resolve the optional filters form schema for a dashboard page. */
+export declare function resolveDashboardFiltersForm(DashboardClass: DashboardPageClass): FormSchema | undefined;
+/** Flatten filter field names from a filters form schema. */
+export declare function dashboardFilterFieldNames(schema: FormSchema | undefined): string[];
+/** Collect filter values from a query/body bag for known filter fields. */
+export declare function pickDashboardFilters(source: Record<string, unknown>, schema: FormSchema | undefined): Record<string, unknown>;
+/** Schema nodes for rendering the filters form. */
+export declare function dashboardFilterSchemaNodes(schema: FormSchema | undefined): SchemaNode[];
 //# sourceMappingURL=dashboard-page.d.ts.map

package/dist/dashboard-page.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-page.d.ts","sourceRoot":"","sources":["../src/dashboard-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,8BAAsB,aAAc,SAAQ,IAAI;IAC9C,OAAgB,IAAI,SAAuB;IAC3C,OAAgB,KAAK,SAAe;IACpC,OAAgB,gBAAgB,UAAQ;IAExC,uDAAuD;IACvD,MAAM,CAAC,OAAO,SAAK;IAEnB,MAAM,CAAC,OAAO,IAAI,WAAW,EAAE;CAGhC;AAED,MAAM,MAAM,kBAAkB,GAAG,OAAO,aAAa,CAAC;AAEtD,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAQ3E"}
+{"version":3,"file":"dashboard-page.d.ts","sourceRoot":"","sources":["../src/dashboard-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAc,MAAM,WAAW,CAAC;AAEpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEzD,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,kBAAkB,CAAC;AAEnD;;;GAGG;AACH,8BAAsB,aAAc,SAAQ,IAAI;IAC9C,OAAgB,IAAI,SAAuB;IAC3C,OAAgB,KAAK,SAAe;IACpC,OAAgB,gBAAgB,UAAQ;IAExC,uDAAuD;IACvD,MAAM,CAAC,OAAO,SAAK;IAEnB,MAAM,CAAC,OAAO,IAAI,WAAW,EAAE;IAI/B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI;CAGxE;AAED,MAAM,MAAM,kBAAkB,GAAG,OAAO,aAAa,CAAC;AAEtD,wDAAwD;AACxD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAQ3E;AAED,qEAAqE;AACrE,wBAAgB,2BAA2B,CACzC,cAAc,EAAE,kBAAkB,GACjC,UAAU,GAAG,SAAS,CAMxB;AAED,6DAA6D;AAC7D,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,EAAE,CAGlF;AAED,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,UAAU,GAAG,SAAS,GAC7B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUzB;AAED,mDAAmD;AACnD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,EAAE,CAQvF"}

package/dist/dashboard-page.js

@@ -1,4 +1,5 @@
 import { Page } from './page.js';
+import { FormBuilder, acceptForm } from './form.js';
 import { NavigationCardsWidget } from './widgets/navigation-cards-widget.js';
 /** Reserved slug — dashboard pages are not registered as `/:slug` routes. */
 export const DASHBOARD_PAGE_SLUG = '__dashboard__';
@@ -15,6 +16,25 @@ export class DashboardPage extends Page {
     static widgets() {
         return [NavigationCardsWidget];
     }
+    /**
+     * Optional filters form (Filament `HasFiltersForm` / `getFiltersForm`).
+     * Submitted via GET on the dashboard; values land in `WidgetRequestContext.filters`.
+     *
+     * @example
+     * ```ts
+     * static override filtersForm(form: FormBuilder) {
+     *   return form.schema([
+     *     Select.make('period').options([
+     *       { label: 'Today', value: 'today' },
+     *       { label: 'MTD', value: 'mtd' },
+     *     ]).default('today'),
+     *   ])
+     * }
+     * ```
+     */
+    static filtersForm(_form) {
+        return undefined;
+    }
 }
 /** True when `value` is DashboardPage or a subclass. */
 export function isDashboardPage(value) {
@@ -28,4 +48,44 @@ export function isDashboardPage(value) {
     }
     return false;
 }
+/** Resolve the optional filters form schema for a dashboard page. */
+export function resolveDashboardFiltersForm(DashboardClass) {
+    const builder = new FormBuilder();
+    const result = DashboardClass.filtersForm(builder);
+    if (result === undefined)
+        return undefined;
+    const built = acceptForm(result, builder);
+    return built.fields.length || built.schema?.length ? built : undefined;
+}
+/** Flatten filter field names from a filters form schema. */
+export function dashboardFilterFieldNames(schema) {
+    if (!schema)
+        return [];
+    return schema.fields.map((field) => field.name);
+}
+/** Collect filter values from a query/body bag for known filter fields. */
+export function pickDashboardFilters(source, schema) {
+    const names = dashboardFilterFieldNames(schema);
+    if (!names.length)
+        return {};
+    const out = {};
+    for (const name of names) {
+        if (Object.prototype.hasOwnProperty.call(source, name)) {
+            out[name] = source[name];
+        }
+    }
+    return out;
+}
+/** Schema nodes for rendering the filters form. */
+export function dashboardFilterSchemaNodes(schema) {
+    if (!schema)
+        return [];
+    if (schema.schema?.length)
+        return schema.schema;
+    return schema.fields.map((field) => ({
+        kind: 'field',
+        name: field.name,
+        field,
+    }));
+}
 //# sourceMappingURL=dashboard-page.js.map

package/dist/dashboard-page.js.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-page.js","sourceRoot":"","sources":["../src/dashboard-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAG7E,6EAA6E;AAC7E,MAAM,CAAC,MAAM,mBAAmB,GAAG,eAAe,CAAC;AAEnD;;;GAGG;AACH,MAAM,OAAgB,aAAc,SAAQ,IAAI;IAC9C,MAAM,CAAU,IAAI,GAAG,mBAAmB,CAAC;IAC3C,MAAM,CAAU,KAAK,GAAG,WAAW,CAAC;IACpC,MAAM,CAAU,gBAAgB,GAAG,IAAI,CAAC;IAExC,uDAAuD;IACvD,MAAM,CAAC,OAAO,GAAG,CAAC,CAAC;IAEnB,MAAM,CAAC,OAAO;QACZ,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjC,CAAC;;AAKH,wDAAwD;AACxD,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,aAAa;YAAE,OAAO,IAAI,CAAC;QAC3C,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"dashboard-page.js","sourceRoot":"","sources":["../src/dashboard-page.ts"],"names":[],"mappings":"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"}

package/dist/dashboard-widgets.d.ts

@@ -12,14 +12,27 @@ export interface ResolvedDashboardWidget {
     id: string;
     kind: DashboardWidgetKind;
     heading?: string;
+    description?: string;
     columnSpan: number | 'full';
     sort: number;
     view?: string;
+    /** Parsed polling interval in ms; `null` disables. */
+    pollingIntervalMs: number | null;
+    /** When true, payload may be deferred until the client loads the widget. */
+    isLazy: boolean;
+    /** Panel-relative URL to re-fetch this widget’s HTML fragment. */
+    refreshUrl?: string;
     payload: DashboardWidgetPayload;
 }
 export type DashboardWidgetPayload = StatsOverviewPayload | CardPayload | ListPayload | ChartPayload | NavigationCardsPayload;
 export interface StatsOverviewPayload {
     stats: StatData[];
+    /** Resolved cards-per-row config. */
+    columns: Partial<Record<string, number>>;
+    /** Inline CSS vars for `.shamar-stats-overview__grid`. */
+    gridStyle: string;
+    /** True when stats were not resolved yet (lazy placeholder). */
+    deferred?: boolean;
 }
 export interface CardPayload {
     content: CardWidgetContent;
@@ -28,14 +41,17 @@ export interface ListPayload {
     columns: ListWidgetColumn[];
     records: ListWidgetRecord[];
     limit: number;
+    deferred?: boolean;
 }
 export interface ChartPayload {
     chartType: ChartType;
     library: ChartLibrary;
     data: ChartData;
+    deferred?: boolean;
 }
 export interface NavigationCardsPayload {
     cards: NavigationCardItem[];
     emptyMessage?: string;
+    deferred?: boolean;
 }
 //# sourceMappingURL=dashboard-widgets.d.ts.map

package/dist/dashboard-widgets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-widgets.d.ts","sourceRoot":"","sources":["../src/dashboard-widgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,MAAM,GACN,MAAM,GACN,OAAO,GACP,iBAAiB,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB,GAC9B,oBAAoB,GACpB,WAAW,GACX,WAAW,GACX,YAAY,GACZ,sBAAsB,CAAC;AAE3B,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}
+{"version":3,"file":"dashboard-widgets.d.ts","sourceRoot":"","sources":["../src/dashboard-widgets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,MAAM,GACN,MAAM,GACN,OAAO,GACP,iBAAiB,CAAC;AAEtB,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,sBAAsB,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB,GAC9B,oBAAoB,GACpB,WAAW,GACX,WAAW,GACX,YAAY,GACZ,sBAAsB,CAAC;AAE3B,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,0DAA0D;IAC1D,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,kBAAkB,EAAE,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/widget.d.ts

@@ -5,6 +5,11 @@ export interface WidgetRequestContext {
     panelId?: string;
     /** Panel base path for building widget links. */
     basePath?: string;
+    /**
+     * Dashboard page filters (Filament `$pageFilters` / `InteractsWithPageFilters`).
+     * Populated from the dashboard filters form query string.
+     */
+    filters?: Record<string, unknown>;
 }
 export type WidgetColumnSpan = number | 'full';
 /**
@@ -17,11 +22,29 @@ export declare abstract class Widget {
     static sort: number;
     static columnSpan: WidgetColumnSpan;
     static heading?: string;
+    /** Optional subtitle under the heading (Filament `$description`). */
+    static description?: string;
     /** Optional Edge view override (`shamar::widgets/...` or app view path). */
     static view?: string;
+    /**
+     * Poll interval (Filament `$pollingInterval`), e.g. `'5s'`, `'500ms'`.
+     * `null` disables polling.
+     */
+    static pollingInterval: string | null;
+    /**
+     * When true, defer data until the widget is visible (Filament `$isLazy`).
+     * Base default is `false` (SSR-friendly); {@link StatsOverviewWidget} defaults to `true`.
+     */
+    static isLazy: boolean;
     static canView(_user: ShamarUser | null | undefined): boolean;
 }
 export type WidgetClass = typeof Widget;
+/** Parse Filament-style `'5s'` / `'500ms'` into milliseconds. */
+export declare function parsePollingIntervalMs(value: string | null | undefined): number | null;
+/**
+ * Filament `InteractsWithPageFilters` — read dashboard filter values from context.
+ */
+export declare function pageFilters(ctx: WidgetRequestContext): Record<string, unknown>;
 /** True when `value` extends {@link Widget}. */
 export declare function isWidgetClass(value: unknown): value is WidgetClass;
 //# sourceMappingURL=widget.d.ts.map

package/dist/widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C;;;GAGG;AACH,8BAAsB,MAAM;IAC1B,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,IAAI,SAAK;IAChB,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAK;IACxC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;CAG9D;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,MAAM,CAAC;AAExC,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE"}
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,uDAAuD;AACvD,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,CAAC;AAE/C;;;GAGG;AACH,8BAAsB,MAAM;IAC1B,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,IAAI,SAAK;IAChB,MAAM,CAAC,UAAU,EAAE,gBAAgB,CAAK;IACxC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,MAAM,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IAC7C;;;OAGG;IACH,MAAM,CAAC,MAAM,UAAS;IAEtB,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;CAG9D;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,MAAM,CAAC;AAExC,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAQtF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE9E;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAQlE"}

package/dist/widget.js

@@ -8,12 +8,43 @@ export class Widget {
     static sort = 0;
     static columnSpan = 1;
     static heading;
+    /** Optional subtitle under the heading (Filament `$description`). */
+    static description;
     /** Optional Edge view override (`shamar::widgets/...` or app view path). */
     static view;
+    /**
+     * Poll interval (Filament `$pollingInterval`), e.g. `'5s'`, `'500ms'`.
+     * `null` disables polling.
+     */
+    static pollingInterval = null;
+    /**
+     * When true, defer data until the widget is visible (Filament `$isLazy`).
+     * Base default is `false` (SSR-friendly); {@link StatsOverviewWidget} defaults to `true`.
+     */
+    static isLazy = false;
     static canView(_user) {
         return true;
     }
 }
+/** Parse Filament-style `'5s'` / `'500ms'` into milliseconds. */
+export function parsePollingIntervalMs(value) {
+    if (value == null || value === '')
+        return null;
+    const match = /^(\d+(?:\.\d+)?)\s*(ms|s)?$/i.exec(value.trim());
+    if (!match)
+        return null;
+    const amount = Number(match[1]);
+    if (!Number.isFinite(amount) || amount < 0)
+        return null;
+    const unit = (match[2] ?? 's').toLowerCase();
+    return unit === 'ms' ? Math.round(amount) : Math.round(amount * 1000);
+}
+/**
+ * Filament `InteractsWithPageFilters` — read dashboard filter values from context.
+ */
+export function pageFilters(ctx) {
+    return ctx.filters ?? {};
+}
 /** True when `value` extends {@link Widget}. */
 export function isWidgetClass(value) {
     if (typeof value !== 'function')

package/dist/widget.js.map

@@ -1 +1 @@
-{"version":3,"file":"widget.js","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,MAAM,OAAgB,MAAM;IAC1B,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAU;IACnB,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAChB,MAAM,CAAC,UAAU,GAAqB,CAAC,CAAC;IACxC,MAAM,CAAC,OAAO,CAAU;IACxB,4EAA4E;IAC5E,MAAM,CAAC,IAAI,CAAU;IAErB,MAAM,CAAC,OAAO,CAAC,KAAoC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;;AAKH,gDAAgD;AAChD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,MAAM,OAAgB,MAAM;IAC1B,sFAAsF;IACtF,MAAM,CAAC,EAAE,CAAU;IACnB,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC;IAChB,MAAM,CAAC,UAAU,GAAqB,CAAC,CAAC;IACxC,MAAM,CAAC,OAAO,CAAU;IACxB,qEAAqE;IACrE,MAAM,CAAC,WAAW,CAAU;IAC5B,4EAA4E;IAC5E,MAAM,CAAC,IAAI,CAAU;IACrB;;;OAGG;IACH,MAAM,CAAC,eAAe,GAAkB,IAAI,CAAC;IAC7C;;;OAGG;IACH,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC;IAEtB,MAAM,CAAC,OAAO,CAAC,KAAoC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;;AAKH,iEAAiE;AACjE,MAAM,UAAU,sBAAsB,CAAC,KAAgC;IACrE,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC/C,MAAM,KAAK,GAAG,8BAA8B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChE,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC7C,OAAO,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAyB;IACnD,OAAO,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,IAAI,OAAO,KAAK,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9C,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC;QACpC,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/widgets/stat.d.ts

@@ -1,27 +1,65 @@
 export type StatColor = 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'gray';
+/** Trusted HTML fragment (Filament `Htmlable`). */
+export type HtmlContent = {
+    html: string;
+};
+export declare function html(content: string): HtmlContent;
+export declare function isHtmlContent(value: unknown): value is HtmlContent;
+export type StatScalar = string | number | null | undefined;
 export interface StatData {
     label: string;
+    labelHtml?: string;
     value: string | number;
+    valueHtml?: string;
     description?: string;
+    descriptionHtml?: string;
     descriptionIcon?: string;
     descriptionIconPosition?: 'before' | 'after';
+    descriptionColor?: StatColor;
     color?: StatColor;
+    icon?: string;
     url?: string;
+    openUrlInNewTab?: boolean;
     /** Sparkline values rendered under the stat. */
     chart?: number[];
+    chartColor?: StatColor;
+    placeholder?: string;
+    extraAttributes?: Record<string, string>;
+    /** Pre-escaped HTML attribute string for Edge (built at serialize time). */
+    extraAttributesHtml?: string;
+    /** Cards this stat spans inside the overview grid (Filament Schema columnSpan). */
+    columnSpan?: number;
 }
+export type StatConfigurator = (stat: Stat) => void;
 /**
  * Filament-style stat card descriptor for {@link StatsOverviewWidget}.
  */
 export declare class Stat {
     private readonly data;
+    private rawValue;
+    private placeholderText?;
     private constructor();
-    static make(label: string, value: string | number): Stat;
-    description(text: string): this;
+    static make(label: string | HtmlContent, value?: StatScalar | HtmlContent): Stat;
+    /** Filament `Stat::configureUsing()` — runs on every {@link Stat.make}. */
+    static configureUsing(callback: StatConfigurator): void;
+    /** Test helper — clears global configurators. */
+    static clearConfigureUsing(): void;
+    description(text: string | HtmlContent): this;
     descriptionIcon(icon: string, position?: 'before' | 'after'): this;
+    descriptionColor(color: StatColor): this;
     color(color: StatColor): this;
+    icon(icon: string): this;
     url(href: string): this;
-    chart(values: number[]): this;
+    openUrlInNewTab(value?: boolean): this;
+    chart(values: number[] | null | undefined): this;
+    chartColor(color: StatColor): this;
+    placeholder(text: string): this;
+    extraAttributes(attrs: Record<string, string>, options?: {
+        merge?: boolean;
+    }): this;
+    columnSpan(span: number): this;
+    value(next: StatScalar | HtmlContent): this;
+    private applyValue;
     toJSON(): StatData;
 }
 //# sourceMappingURL=stat.d.ts.map

package/dist/widgets/stat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stat.d.ts","sourceRoot":"","sources":["../../src/widgets/stat.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvF,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC7C,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAEhC,OAAO;IAIP,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIxD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK/B,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAE,QAAQ,GAAG,OAAiB,GAAG,IAAI;IAM3E,KAAK,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAK7B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKvB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI;IAK7B,MAAM,IAAI,QAAQ;CAGnB"}
+{"version":3,"file":"stat.d.ts","sourceRoot":"","sources":["../../src/widgets/stat.ts"],"names":[],"mappings":"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"}

package/dist/widgets/stat.js

@@ -1,16 +1,56 @@
+export function html(content) {
+    return { html: content };
+}
+export function isHtmlContent(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        'html' in value &&
+        typeof value.html === 'string');
+}
+const configurators = [];
+function isBlank(value) {
+    return value == null || value === '';
+}
 /**
  * Filament-style stat card descriptor for {@link StatsOverviewWidget}.
  */
 export class Stat {
     data;
+    rawValue;
+    placeholderText;
     constructor(label, value) {
-        this.data = { label, value };
+        if (isHtmlContent(label)) {
+            this.data = { label: '', labelHtml: label.html, value: '' };
+        }
+        else {
+            this.data = { label: String(label), value: '' };
+        }
+        this.rawValue = value;
+        this.applyValue(value);
     }
-    static make(label, value) {
-        return new Stat(label, value);
+    static make(label, value = null) {
+        const stat = new Stat(label, value);
+        for (const configure of configurators)
+            configure(stat);
+        return stat;
+    }
+    /** Filament `Stat::configureUsing()` — runs on every {@link Stat.make}. */
+    static configureUsing(callback) {
+        configurators.push(callback);
+    }
+    /** Test helper — clears global configurators. */
+    static clearConfigureUsing() {
+        configurators.length = 0;
     }
     description(text) {
-        this.data.description = text;
+        if (isHtmlContent(text)) {
+            this.data.descriptionHtml = text.html;
+            this.data.description = undefined;
+        }
+        else {
+            this.data.description = text;
+            this.data.descriptionHtml = undefined;
+        }
         return this;
     }
     descriptionIcon(icon, position = 'after') {
@@ -18,20 +58,99 @@ export class Stat {
         this.data.descriptionIconPosition = position;
         return this;
     }
+    descriptionColor(color) {
+        this.data.descriptionColor = color;
+        return this;
+    }
     color(color) {
         this.data.color = color;
         return this;
     }
+    icon(icon) {
+        this.data.icon = icon;
+        return this;
+    }
     url(href) {
         this.data.url = href;
         return this;
     }
+    openUrlInNewTab(value = true) {
+        this.data.openUrlInNewTab = value;
+        return this;
+    }
     chart(values) {
+        if (values == null)
+            return this;
         this.data.chart = values;
         return this;
     }
+    chartColor(color) {
+        this.data.chartColor = color;
+        return this;
+    }
+    placeholder(text) {
+        this.placeholderText = text;
+        this.data.placeholder = text;
+        this.applyValue(this.rawValue);
+        return this;
+    }
+    extraAttributes(attrs, options) {
+        this.data.extraAttributes = options?.merge
+            ? { ...this.data.extraAttributes, ...attrs }
+            : { ...attrs };
+        return this;
+    }
+    columnSpan(span) {
+        this.data.columnSpan = Math.max(1, Math.floor(span));
+        return this;
+    }
+    value(next) {
+        this.rawValue = next;
+        this.applyValue(next);
+        return this;
+    }
+    applyValue(value) {
+        if (isHtmlContent(value)) {
+            this.data.valueHtml = value.html;
+            this.data.value = '';
+            return;
+        }
+        this.data.valueHtml = undefined;
+        if (isBlank(value)) {
+            this.data.value = this.placeholderText ?? '';
+            return;
+        }
+        this.data.value = value;
+    }
     toJSON() {
-        return { ...this.data };
+        const out = {
+            label: this.data.label,
+            value: this.data.value,
+        };
+        const copy = (key) => {
+            const value = this.data[key];
+            if (value !== undefined)
+                out[key] = value;
+        };
+        copy('labelHtml');
+        copy('valueHtml');
+        copy('description');
+        copy('descriptionHtml');
+        copy('descriptionIcon');
+        copy('descriptionIconPosition');
+        copy('descriptionColor');
+        copy('color');
+        copy('icon');
+        copy('url');
+        copy('openUrlInNewTab');
+        copy('chartColor');
+        copy('placeholder');
+        copy('columnSpan');
+        if (this.data.extraAttributes)
+            out.extraAttributes = { ...this.data.extraAttributes };
+        if (this.data.chart)
+            out.chart = [...this.data.chart];
+        return out;
     }
 }
 //# sourceMappingURL=stat.js.map

package/dist/widgets/stat.js.map

@@ -1 +1 @@
-{"version":3,"file":"stat.js","sourceRoot":"","sources":["../../src/widgets/stat.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,OAAO,IAAI;IACE,IAAI,CAAW;IAEhC,YAAoB,KAAa,EAAE,KAAsB;QACvD,IAAI,CAAC,IAAI,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,KAAa,EAAE,KAAsB;QAC/C,OAAO,IAAI,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,WAAW,CAAC,IAAY;QACtB,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC7B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,eAAe,CAAC,IAAY,EAAE,WAA+B,OAAO;QAClE,IAAI,CAAC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QACjC,IAAI,CAAC,IAAI,CAAC,uBAAuB,GAAG,QAAQ,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,KAAgB;QACpB,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,MAAgB;QACpB,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM;QACJ,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;CACF"}
+{"version":3,"file":"stat.js","sourceRoot":"","sources":["../../src/widgets/stat.ts"],"names":[],"mappings":"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"}

package/dist/widgets/stats-overview-widget.d.ts

@@ -1,10 +1,44 @@
-import { Widget, type WidgetClass, type WidgetRequestContext } from '../widget.js';
+import { Widget, parsePollingIntervalMs, type WidgetClass, type WidgetRequestContext } from '../widget.js';
 import { Stat, type StatData } from './stat.js';
+export type StatsOverviewBreakpoint = 'default' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/**
+ * Cards-per-row for {@link StatsOverviewWidget} (Filament `getColumns()`).
+ * - `number` — that many columns from the `sm` breakpoint up (1 column on the smallest screens)
+ * - object — responsive map, e.g. `{ sm: 2, lg: 4 }`
+ */
+export type StatsOverviewColumns = number | Partial<Record<StatsOverviewBreakpoint, number>>;
+export type StatsOverviewConfigurator = (widget: typeof StatsOverviewWidget) => void;
+export declare function clampStatsOverviewColumns(value: number): number;
+/** Filament auto `getColumns()` heuristic from stat count. */
+export declare function autoStatsOverviewColumns(statsCount: number): number;
+/**
+ * Normalize widget `columns` into a breakpoint map.
+ * When `columns` is null/undefined, uses Filament’s count-based default.
+ */
+export declare function resolveStatsOverviewColumns(columns: StatsOverviewColumns | null | undefined, statsCount?: number): Partial<Record<StatsOverviewBreakpoint, number>>;
+/** Inline CSS custom properties consumed by `.shamar-stats-overview__grid`. */
+export declare function statsOverviewGridStyle(columns: StatsOverviewColumns | null | undefined, statsCount?: number): string;
 /**
  * Grid of KPI stat cards (Filament StatsOverviewWidget).
  */
 export declare abstract class StatsOverviewWidget extends Widget {
+    /**
+     * Cards per row inside this widget (Filament `getColumns()`).
+     * Leave `null` for Filament’s count-based auto layout (3 or 4).
+     */
+    static columns: StatsOverviewColumns | null;
+    /** Filament default: refresh every 5 seconds. Set `null` to disable. */
+    static pollingInterval: string | null;
+    /** Filament default: lazy-load when visible. */
+    static isLazy: boolean;
     static stats(_ctx: WidgetRequestContext): Stat[] | StatData[] | Promise<Stat[] | StatData[]>;
+    /** Filament-style global defaults for every stats overview widget class. */
+    static configureUsing(callback: StatsOverviewConfigurator): void;
+    /** Test helper. */
+    static clearConfigureUsing(): void;
+    /** Apply {@link configureUsing} callbacks onto a concrete widget class (once). */
+    static applyConfigurators(WidgetClass: typeof StatsOverviewWidget): void;
 }
 export declare function isStatsOverviewWidget(value: WidgetClass): value is typeof StatsOverviewWidget;
+export { parsePollingIntervalMs };
 //# sourceMappingURL=stats-overview-widget.d.ts.map

package/dist/widgets/stats-overview-widget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stats-overview-widget.d.ts","sourceRoot":"","sources":["../../src/widgets/stats-overview-widget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,WAAW,EAAE,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEhD;;GAEG;AACH,8BAAsB,mBAAoB,SAAQ,MAAM;IACtD,MAAM,CAAC,KAAK,CACV,IAAI,EAAE,oBAAoB,GACzB,IAAI,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;CAGtD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,mBAAmB,CAO7F"}
+{"version":3,"file":"stats-overview-widget.d.ts","sourceRoot":"","sources":["../../src/widgets/stats-overview-widget.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAEpF;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAAC;AAe7F,MAAM,MAAM,yBAAyB,GAAG,CAAC,MAAM,EAAE,OAAO,mBAAmB,KAAK,IAAI,CAAC;AAIrF,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG/D;AAED,8DAA8D;AAC9D,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKnE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,EAChD,UAAU,SAAI,GACb,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAsBlD;AAED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,SAAS,EAChD,UAAU,SAAI,GACb,MAAM,CAQR;AAED;;GAEG;AACH,8BAAsB,mBAAoB,SAAQ,MAAM;IACtD;;;OAGG;IACH,MAAM,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAQ;IAEnD,wEAAwE;IACxE,OAAgB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEtD,gDAAgD;IAChD,OAAgB,MAAM,UAAQ;IAE9B,MAAM,CAAC,KAAK,CACV,IAAI,EAAE,oBAAoB,GACzB,IAAI,EAAE,GAAG,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;IAIrD,4EAA4E;IAC5E,MAAM,CAAC,cAAc,CAAC,QAAQ,EAAE,yBAAyB,GAAG,IAAI;IAIhE,mBAAmB;IACnB,MAAM,CAAC,mBAAmB,IAAI,IAAI;IAKlC,kFAAkF;IAClF,MAAM,CAAC,kBAAkB,CAAC,WAAW,EAAE,OAAO,mBAAmB,GAAG,IAAI;CAKzE;AAID,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,WAAW,GAAG,KAAK,IAAI,OAAO,mBAAmB,CAO7F;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/widgets/stats-overview-widget.js

@@ -1,12 +1,103 @@
-import { Widget } from '../widget.js';
+import { Widget, parsePollingIntervalMs, } from '../widget.js';
+const COL_MIN = 1;
+const COL_MAX = 12;
+const BREAKPOINTS = ['default', 'sm', 'md', 'lg', 'xl', '2xl'];
+const CSS_VARS = {
+    default: '--shamar-stats-cols',
+    sm: '--shamar-stats-cols-sm',
+    md: '--shamar-stats-cols-md',
+    lg: '--shamar-stats-cols-lg',
+    xl: '--shamar-stats-cols-xl',
+    '2xl': '--shamar-stats-cols-2xl',
+};
+const widgetConfigurators = [];
+export function clampStatsOverviewColumns(value) {
+    if (!Number.isFinite(value))
+        return COL_MIN;
+    return Math.min(COL_MAX, Math.max(COL_MIN, Math.floor(value)));
+}
+/** Filament auto `getColumns()` heuristic from stat count. */
+export function autoStatsOverviewColumns(statsCount) {
+    const count = Math.max(0, Math.floor(statsCount));
+    if (count < 3)
+        return 3;
+    if (count % 3 !== 1)
+        return 3;
+    return 4;
+}
+/**
+ * Normalize widget `columns` into a breakpoint map.
+ * When `columns` is null/undefined, uses Filament’s count-based default.
+ */
+export function resolveStatsOverviewColumns(columns, statsCount = 0) {
+    if (columns == null) {
+        const n = autoStatsOverviewColumns(statsCount);
+        return { default: 1, sm: n };
+    }
+    if (typeof columns === 'number') {
+        const n = clampStatsOverviewColumns(columns);
+        return { default: 1, sm: n };
+    }
+    const out = {};
+    for (const bp of BREAKPOINTS) {
+        const raw = columns[bp];
+        if (raw != null)
+            out[bp] = clampStatsOverviewColumns(raw);
+    }
+    if (!Object.keys(out).length) {
+        const n = autoStatsOverviewColumns(statsCount);
+        return { default: 1, sm: n };
+    }
+    if (out.default == null)
+        out.default = 1;
+    return out;
+}
+/** Inline CSS custom properties consumed by `.shamar-stats-overview__grid`. */
+export function statsOverviewGridStyle(columns, statsCount = 0) {
+    const resolved = resolveStatsOverviewColumns(columns, statsCount);
+    const parts = [];
+    for (const bp of BREAKPOINTS) {
+        const n = resolved[bp];
+        if (n != null)
+            parts.push(`${CSS_VARS[bp]}: ${n}`);
+    }
+    return parts.join('; ');
+}
 /**
  * Grid of KPI stat cards (Filament StatsOverviewWidget).
  */
 export class StatsOverviewWidget extends Widget {
+    /**
+     * Cards per row inside this widget (Filament `getColumns()`).
+     * Leave `null` for Filament’s count-based auto layout (3 or 4).
+     */
+    static columns = null;
+    /** Filament default: refresh every 5 seconds. Set `null` to disable. */
+    static pollingInterval = '5s';
+    /** Filament default: lazy-load when visible. */
+    static isLazy = true;
     static stats(_ctx) {
         return [];
     }
+    /** Filament-style global defaults for every stats overview widget class. */
+    static configureUsing(callback) {
+        widgetConfigurators.push(callback);
+    }
+    /** Test helper. */
+    static clearConfigureUsing() {
+        widgetConfigurators.length = 0;
+        configuredWidgets = new WeakSet();
+    }
+    /** Apply {@link configureUsing} callbacks onto a concrete widget class (once). */
+    static applyConfigurators(WidgetClass) {
+        if (configuredWidgets.has(WidgetClass))
+            return;
+        for (const configure of widgetConfigurators)
+            configure(WidgetClass);
+        configuredWidgets.add(WidgetClass);
+    }
 }
+let configuredWidgets = new WeakSet();
 export function isStatsOverviewWidget(value) {
     let current = value;
     while (typeof current === 'function') {
@@ -16,4 +107,5 @@ export function isStatsOverviewWidget(value) {
     }
     return false;
 }
+export { parsePollingIntervalMs };
 //# sourceMappingURL=stats-overview-widget.js.map

package/dist/widgets/stats-overview-widget.js.map

@@ -1 +1 @@
-{"version":3,"file":"stats-overview-widget.js","sourceRoot":"","sources":["../../src/widgets/stats-overview-widget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA+C,MAAM,cAAc,CAAC;AAGnF;;GAEG;AACH,MAAM,OAAgB,mBAAoB,SAAQ,MAAM;IACtD,MAAM,CAAC,KAAK,CACV,IAA0B;QAE1B,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAkB;IACtD,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;QACrC,IAAI,OAAO,KAAK,mBAAmB;YAAE,OAAO,IAAI,CAAC;QACjD,OAAO,GAAG,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"stats-overview-widget.js","sourceRoot":"","sources":["../../src/widgets/stats-overview-widget.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shamar/core",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Filament-inspired resource DSL for Shamar admin (ORM-agnostic core).",
   "license": "MIT",
   "type": "module",