@coffer-org/sdk 3.0.0 → 3.2.0

package/dist/condition.d.ts

@@ -17,6 +17,15 @@ export interface Condition {
     $or?: Condition[];
 }
 export type Values = Record<string, unknown>;
+export declare const COMPILABLE_SCALAR_OPS: Set<string>;
+export declare const COMPILABLE_ARRAY_OPS: Set<string>;
+export declare const COMPILABLE_MEMBER_OPS: Set<string>;
 export declare function evalCondition(cond: Condition | undefined, values: Values): boolean;
 export declare function resolveFlag(v: boolean | Condition | undefined, values: Values): boolean;
+export declare function conditionKeys(cond: Condition | undefined): string[];
+export declare function conditionOps(cond: Condition | undefined, field: string): string[];
+export declare function visibleOptions<T extends {
+    value?: string;
+    when?: Condition;
+}>(options: T[], values: Values, keep?: string | string[]): T[];
 export declare function describeCondition(cond: Condition | undefined, labelOf: (field: string) => string, valueLabelOf?: (field: string, value: Scalar) => string): string[];

package/dist/condition.js

@@ -1,4 +1,7 @@
 import sift from 'sift';
+export const COMPILABLE_SCALAR_OPS = new Set(['$eq', '$ne', '$gt', '$gte', '$lt', '$lte']);
+export const COMPILABLE_ARRAY_OPS = new Set(['$in', '$nin']);
+export const COMPILABLE_MEMBER_OPS = new Set(['$contains']);
 const createEqualsOperation = sift
     .createEqualsOperation;
 const isScalar = (v) => typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
@@ -62,6 +65,47 @@ function describePredicate(label, pred, vl) {
     }
     return out;
 }
+export function conditionKeys(cond) {
+    if (!cond)
+        return [];
+    const out = [];
+    for (const [key, spec] of Object.entries(cond)) {
+        if (spec === undefined)
+            continue;
+        if (key === '$and' || key === '$or') {
+            for (const c of spec)
+                out.push(...conditionKeys(c));
+            continue;
+        }
+        out.push(key);
+    }
+    return [...new Set(out)];
+}
+export function conditionOps(cond, field) {
+    if (!cond)
+        return [];
+    const out = [];
+    for (const [key, spec] of Object.entries(cond)) {
+        if (spec === undefined)
+            continue;
+        if (key === '$and' || key === '$or') {
+            for (const c of spec)
+                out.push(...conditionOps(c, field));
+            continue;
+        }
+        if (key !== field)
+            continue;
+        if (typeof spec === 'object' && spec !== null && !Array.isArray(spec))
+            out.push(...Object.keys(spec));
+        else
+            out.push('$eq');
+    }
+    return [...new Set(out)];
+}
+export function visibleOptions(options, values, keep) {
+    const kept = keep === undefined ? undefined : new Set(Array.isArray(keep) ? keep : [keep]);
+    return options.filter((o) => (kept !== undefined && o.value !== undefined && kept.has(o.value)) || (o.when ? evalCondition(o.when, values) : true));
+}
 export function describeCondition(cond, labelOf, valueLabelOf) {
     if (!cond)
         return [];

package/dist/field-presets.js

@@ -375,7 +375,7 @@ export function source(raw) {
         required,
         prim: 'text',
         column: 'text',
-        hints: { ext, maxBytes, noEditControl: true },
+        hints: { ext, maxBytes, noEditControl: true, ...(o.key ? { fileName: o.key } : {}) },
         zod: optionalize(s, required),
     };
     return wrapKey(o, meta);

package/dist/fields.d.ts

@@ -24,6 +24,7 @@ export interface OptionItem {
     title: string;
     icon?: OptionIcon;
     subtitle?: string;
+    when?: Condition;
 }
 declare const __fieldItemBrand: unique symbol;
 export interface FieldItem {
@@ -96,6 +97,7 @@ export interface FieldClient {
     relation?: {
         library: string;
         shelf: string;
+        filter?: Condition;
     };
     virtual?: boolean;
     default?: string | number | boolean | null;
@@ -377,6 +379,7 @@ export interface RelationOpts extends FieldCoreOpts {
     options: {
         library: string;
         shelf: string;
+        filter?: Condition;
     };
 }
 export declare function relation(o: RelationOpts & {

package/dist/fields.js

@@ -453,10 +453,20 @@ export function select(raw) {
     const meta = applyMultiple(base, o.multiple ?? false);
     return wrapKey(o, meta);
 }
+function assertFlatEqualityFilter(filter) {
+    for (const [key, value] of Object.entries(filter)) {
+        if (key.startsWith('$'))
+            throw new Error(`[relation] filter key '${key}' is an operator — only flat equality is allowed here`);
+        if (value === undefined || (value !== null && typeof value === 'object'))
+            throw new Error(`[relation] filter key '${key}' has a non-scalar value — only flat equality is allowed here`);
+    }
+}
 export function relation(raw) {
     const o = normalizeOpts(raw);
     const required = o.required ?? false;
     const multi = o.multiple ?? false;
+    if (raw.options.filter)
+        assertFlatEqualityFilter(raw.options.filter);
     let s;
     if (multi) {
         s = z.unknown().superRefine((raw, ctx) => {
@@ -478,7 +488,11 @@ export function relation(raw) {
         prim: 'relation',
         column: multi ? 'text' : 'integer',
         hints: { multi, displayKey: o.displayKey ?? 'name' },
-        relation: { library: raw.options.library, shelf: raw.options.shelf },
+        relation: {
+            library: raw.options.library,
+            shelf: raw.options.shelf,
+            ...(raw.options.filter && { filter: raw.options.filter }),
+        },
         ...(multi && { json: true }),
         zod: optionalize(s, required),
     };

package/dist/plugin.d.ts

@@ -3,6 +3,7 @@ import type { ShelfDef } from './shelf.ts';
 import type { ExtendDef } from './extend.ts';
 import type { OptionItem } from './fields.ts';
 import type { SettingsDef } from './settings.ts';
+import type { ShowcaseDef } from './showcase.ts';
 export interface FieldContrib {
     library: string;
     shelf: string;
@@ -24,6 +25,7 @@ export interface PluginManifest {
     fieldContribs?: FieldContrib[];
     optionLists?: NamedOptionList[];
     settings?: SettingsDef;
+    showcases?: ShowcaseDef[];
 }
 export declare const BASE_PLUGIN = "core";
 export declare function definePlugin(p: PluginManifest): PluginManifest;

package/dist/showcase.d.ts

@@ -0,0 +1,15 @@
+import type { Condition } from './condition.ts';
+export interface ShowcaseDef {
+    id: string;
+    library: string;
+    label: string;
+    icon: string;
+    source: {
+        library: string;
+        shelf: string;
+    };
+    filter: Condition;
+    columns: string[];
+    createDefaults?: Record<string, unknown>;
+}
+export declare function defineShowcase(s: ShowcaseDef): ShowcaseDef;

package/dist/showcase.js

@@ -0,0 +1,39 @@
+import { COMPILABLE_SCALAR_OPS, COMPILABLE_ARRAY_OPS, COMPILABLE_MEMBER_OPS } from "./condition.js";
+const COMPILABLE_OPS = new Set([
+    ...COMPILABLE_SCALAR_OPS,
+    ...COMPILABLE_ARRAY_OPS,
+    ...COMPILABLE_MEMBER_OPS,
+]);
+function assertCompilableOps(cond, id) {
+    for (const [key, spec] of Object.entries(cond)) {
+        if (spec === undefined)
+            continue;
+        if (key === '$and' || key === '$or') {
+            for (const c of spec)
+                assertCompilableOps(c, id);
+            continue;
+        }
+        if (typeof spec === 'object' && spec !== null) {
+            for (const op of Object.keys(spec)) {
+                if (!COMPILABLE_OPS.has(op)) {
+                    throw new Error(`[showcase] ${id}: operator '${op}' on '${key}' does not compile to SQL`);
+                }
+            }
+        }
+    }
+}
+export function defineShowcase(s) {
+    if (!s.id)
+        throw new Error('[showcase] missing id');
+    if (!s.library)
+        throw new Error(`[showcase] ${s.id}: missing library`);
+    if (!s.source?.library || !s.source?.shelf)
+        throw new Error(`[showcase] ${s.id}: missing source library/shelf`);
+    if (!s.columns?.length)
+        throw new Error(`[showcase] ${s.id}: columns must not be empty`);
+    if (!s.filter || Object.keys(s.filter).length === 0) {
+        throw new Error(`[showcase] ${s.id}: filter must not be empty — an unfiltered showcase is the shelf itself`);
+    }
+    assertCompilableOps(s.filter, s.id);
+    return s;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/sdk",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -17,6 +17,10 @@
       "types": "./dist/derive.d.ts",
       "default": "./dist/derive.js"
     },
+    "./showcase": {
+      "types": "./dist/showcase.d.ts",
+      "default": "./dist/showcase.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"