@shamar/core 1.0.7 → 1.0.9

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.7",
+  "version": "1.0.9",
   "description": "Filament-inspired resource DSL for Shamar admin (ORM-agnostic core).",
   "license": "MIT",
   "type": "module",