@petrarca/sonnet-core 0.1.0

package/dist/search/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * FilterExpr -- lightweight boolean expression tree for search and filtering.
+ *
+ * Designed to start simple (a flat AND list of terms) and grow to support
+ * full boolean queries (AND, OR, NOT, grouping) without breaking callers.
+ *
+ * The component always emits a FilterExpr. Callers that talk to a flat
+ * server API today use flattenFilterExpr() to extract the terms. When the
+ * server gains AST support, callers drop flattenFilterExpr and pass the
+ * expression directly -- no component changes required.
+ *
+ * Extractable to @petrarca/sonnet-core: no app-specific imports.
+ */
+/** A single field/value filter term -- the leaf node of a FilterExpr. */
+interface FilterTerm {
+    type: "term";
+    /** Schema property key -- used as the query param name sent to the server. */
+    key: string;
+    /** The filter value. */
+    value: string;
+}
+/** Conjunction: all children must match. */
+interface FilterAnd {
+    type: "and";
+    children: FilterExpr[];
+}
+/** Disjunction: at least one child must match. */
+interface FilterOr {
+    type: "or";
+    children: FilterExpr[];
+}
+/** Negation: child must not match. */
+interface FilterNot {
+    type: "not";
+    child: FilterExpr;
+}
+/**
+ * Explicit grouping (parentheses). Semantically identical to its child --
+ * used to preserve user intent when round-tripping the expression.
+ */
+interface FilterGroup {
+    type: "group";
+    child: FilterExpr;
+}
+/** The full expression type. */
+type FilterExpr = FilterTerm | FilterAnd | FilterOr | FilterNot | FilterGroup;
+/** An empty expression -- no filters active. */
+declare const EMPTY_FILTER: FilterExpr;
+
+/**
+ * Utilities for working with FilterExpr trees.
+ *
+ * Extractable to @petrarca/sonnet-core: no app-specific imports.
+ */
+
+/**
+ * Return all term nodes from the expression as FilterTerm objects, depth-first.
+ *
+ * Ignores the boolean structure (AND / OR / NOT / GROUP).
+ */
+declare function collectTerms(expr: FilterExpr): FilterTerm[];
+/**
+ * Collect all term nodes from a FilterExpr tree as flat key/value pairs.
+ *
+ * Use this when talking to a server API that accepts only flat key/value
+ * filter params. When the server gains AST support, pass the raw FilterExpr
+ * instead and drop this call.
+ *
+ * @example
+ * const terms = flattenFilterExpr(expr);
+ * // [{ key: "name", value: "acme" }, { key: "status", value: "active" }]
+ * const params = Object.fromEntries(terms.map(t => [t.key, t.value]));
+ */
+declare function flattenFilterExpr(expr: FilterExpr): {
+    key: string;
+    value: string;
+}[];
+/**
+ * Return true when the expression contains no term nodes.
+ */
+declare function isEmptyFilterExpr(expr: FilterExpr): boolean;
+/**
+ * Serialize a FilterExpr to the server's q= expression syntax.
+ *
+ * Produces strings like `code ~ "aspirin" OR display ~ "aspirin"`.
+ * All terms use the `~` (LIKE / substring) operator -- the FilterTerm
+ * type carries no operator field; callers that need exact-match or other
+ * operators should construct the q= string directly.
+ */
+declare function serializeFilterExpr(expr: FilterExpr): string;
+/**
+ * Build a typed API params object from a FilterExpr and pagination state.
+ *
+ * Used by list and expansion pages to convert Zustand store state into
+ * query params for the server. The base object carries pagination keys
+ * (limit / offset); filter terms from the expression are merged in.
+ *
+ * When the expression is a flat AND of terms, each term becomes a flat
+ * query param (backwards compatible with existing server endpoints).
+ * When the expression contains OR/NOT/Group nodes, it is serialized
+ * as a `q=` string using the server's query expression syntax.
+ *
+ * @example
+ * const params = buildListParams<ValueSetListParams>(
+ *   filterExpr,
+ *   { limit: pagination.pageSize, offset: pagination.pageIndex * pagination.pageSize },
+ * );
+ */
+declare function buildListParams<T extends object>(expr: FilterExpr, base: T): T;
+/**
+ * Build a flat AND expression from an array of key/value pairs.
+ * Convenience for constructing the initial state from existing filter params.
+ */
+declare function termsToFilterExpr(terms: {
+    key: string;
+    value: string;
+}[]): FilterExpr;
+
+export { EMPTY_FILTER, type FilterAnd, type FilterExpr, type FilterGroup, type FilterNot, type FilterOr, type FilterTerm, buildListParams, collectTerms, flattenFilterExpr, isEmptyFilterExpr, serializeFilterExpr, termsToFilterExpr };

package/dist/search/index.js

@@ -0,0 +1,82 @@
+// src/search/types.ts
+var EMPTY_FILTER = { type: "and", children: [] };
+
+// src/search/filterExpr.ts
+function collectTerms(expr) {
+  const out = [];
+  collectTermNodes(expr, out);
+  return out;
+}
+function collectTermNodes(expr, out) {
+  switch (expr.type) {
+    case "term":
+      out.push(expr);
+      break;
+    case "and":
+    case "or":
+      for (const child of expr.children) collectTermNodes(child, out);
+      break;
+    case "not":
+    case "group":
+      collectTermNodes(expr.child, out);
+      break;
+  }
+}
+function flattenFilterExpr(expr) {
+  return collectTerms(expr).map(({ key, value }) => ({ key, value }));
+}
+function isEmptyFilterExpr(expr) {
+  return collectTerms(expr).length === 0;
+}
+function isFlatAnd(expr) {
+  if (expr.type === "term") return true;
+  if (expr.type === "and") return expr.children.every((c) => c.type === "term");
+  return false;
+}
+function serializeFilterExpr(expr) {
+  switch (expr.type) {
+    case "term": {
+      const escaped = expr.value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      return `${expr.key} ~ "${escaped}"`;
+    }
+    case "and":
+      return expr.children.map((c) => serializeFilterExpr(c)).join(" AND ");
+    case "or":
+      return expr.children.map((c) => serializeFilterExpr(c)).join(" OR ");
+    case "not":
+      return `NOT (${serializeFilterExpr(expr.child)})`;
+    case "group":
+      return `(${serializeFilterExpr(expr.child)})`;
+  }
+}
+function buildListParams(expr, base) {
+  if (isEmptyFilterExpr(expr)) return base;
+  if (isFlatAnd(expr)) {
+    const pairs = flattenFilterExpr(expr);
+    const extra = Object.fromEntries(
+      pairs.filter(({ key }) => !(key in base)).map(({ key, value }) => [key, value])
+    );
+    return { ...base, ...extra };
+  }
+  return { ...base, q: serializeFilterExpr(expr) };
+}
+function termsToFilterExpr(terms) {
+  return {
+    type: "and",
+    children: terms.map((t) => ({
+      type: "term",
+      key: t.key,
+      value: t.value
+    }))
+  };
+}
+export {
+  EMPTY_FILTER,
+  buildListParams,
+  collectTerms,
+  flattenFilterExpr,
+  isEmptyFilterExpr,
+  serializeFilterExpr,
+  termsToFilterExpr
+};
+//# sourceMappingURL=index.js.map

package/dist/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/search/types.ts","../../src/search/filterExpr.ts"],"sourcesContent":["/**\n * FilterExpr -- lightweight boolean expression tree for search and filtering.\n *\n * Designed to start simple (a flat AND list of terms) and grow to support\n * full boolean queries (AND, OR, NOT, grouping) without breaking callers.\n *\n * The component always emits a FilterExpr. Callers that talk to a flat\n * server API today use flattenFilterExpr() to extract the terms. When the\n * server gains AST support, callers drop flattenFilterExpr and pass the\n * expression directly -- no component changes required.\n *\n * Extractable to @petrarca/sonnet-core: no app-specific imports.\n */\n\n/** A single field/value filter term -- the leaf node of a FilterExpr. */\nexport interface FilterTerm {\n  type: \"term\";\n  /** Schema property key -- used as the query param name sent to the server. */\n  key: string;\n  /** The filter value. */\n  value: string;\n}\n\n/** Conjunction: all children must match. */\nexport interface FilterAnd {\n  type: \"and\";\n  children: FilterExpr[];\n}\n\n/** Disjunction: at least one child must match. */\nexport interface FilterOr {\n  type: \"or\";\n  children: FilterExpr[];\n}\n\n/** Negation: child must not match. */\nexport interface FilterNot {\n  type: \"not\";\n  child: FilterExpr;\n}\n\n/**\n * Explicit grouping (parentheses). Semantically identical to its child --\n * used to preserve user intent when round-tripping the expression.\n */\nexport interface FilterGroup {\n  type: \"group\";\n  child: FilterExpr;\n}\n\n/** The full expression type. */\nexport type FilterExpr =\n  | FilterTerm\n  | FilterAnd\n  | FilterOr\n  | FilterNot\n  | FilterGroup;\n\n/** An empty expression -- no filters active. */\nexport const EMPTY_FILTER: FilterExpr = { type: \"and\", children: [] };\n","/**\n * Utilities for working with FilterExpr trees.\n *\n * Extractable to @petrarca/sonnet-core: no app-specific imports.\n */\n\nimport type { FilterExpr, FilterTerm } from \"./types\";\n\n/**\n * Return all term nodes from the expression as FilterTerm objects, depth-first.\n *\n * Ignores the boolean structure (AND / OR / NOT / GROUP).\n */\nexport function collectTerms(expr: FilterExpr): FilterTerm[] {\n  const out: FilterTerm[] = [];\n  collectTermNodes(expr, out);\n  return out;\n}\n\nfunction collectTermNodes(expr: FilterExpr, out: FilterTerm[]): void {\n  switch (expr.type) {\n    case \"term\":\n      out.push(expr);\n      break;\n    case \"and\":\n    case \"or\":\n      for (const child of expr.children) collectTermNodes(child, out);\n      break;\n    case \"not\":\n    case \"group\":\n      collectTermNodes(expr.child, out);\n      break;\n  }\n}\n\n/**\n * Collect all term nodes from a FilterExpr tree as flat key/value pairs.\n *\n * Use this when talking to a server API that accepts only flat key/value\n * filter params. When the server gains AST support, pass the raw FilterExpr\n * instead and drop this call.\n *\n * @example\n * const terms = flattenFilterExpr(expr);\n * // [{ key: \"name\", value: \"acme\" }, { key: \"status\", value: \"active\" }]\n * const params = Object.fromEntries(terms.map(t => [t.key, t.value]));\n */\nexport function flattenFilterExpr(\n  expr: FilterExpr,\n): { key: string; value: string }[] {\n  return collectTerms(expr).map(({ key, value }) => ({ key, value }));\n}\n\n/**\n * Return true when the expression contains no term nodes.\n */\nexport function isEmptyFilterExpr(expr: FilterExpr): boolean {\n  return collectTerms(expr).length === 0;\n}\n\n/**\n * Check whether a FilterExpr is a flat AND of terms only (no OR/NOT/Group).\n * When true, the expression can be serialized as simple key=value params.\n * When false, it must be serialized as a `q=` expression string.\n */\nfunction isFlatAnd(expr: FilterExpr): boolean {\n  if (expr.type === \"term\") return true;\n  if (expr.type === \"and\") return expr.children.every((c) => c.type === \"term\");\n  return false;\n}\n\n/**\n * Serialize a FilterExpr to the server's q= expression syntax.\n *\n * Produces strings like `code ~ \"aspirin\" OR display ~ \"aspirin\"`.\n * All terms use the `~` (LIKE / substring) operator -- the FilterTerm\n * type carries no operator field; callers that need exact-match or other\n * operators should construct the q= string directly.\n */\nexport function serializeFilterExpr(expr: FilterExpr): string {\n  switch (expr.type) {\n    case \"term\": {\n      const escaped = expr.value.replace(/\\\\/g, \"\\\\\\\\\").replace(/\"/g, '\\\\\"');\n      return `${expr.key} ~ \"${escaped}\"`;\n    }\n    case \"and\":\n      return expr.children.map((c) => serializeFilterExpr(c)).join(\" AND \");\n    case \"or\":\n      return expr.children.map((c) => serializeFilterExpr(c)).join(\" OR \");\n    case \"not\":\n      return `NOT (${serializeFilterExpr(expr.child)})`;\n    case \"group\":\n      return `(${serializeFilterExpr(expr.child)})`;\n  }\n}\n\n/**\n * Build a typed API params object from a FilterExpr and pagination state.\n *\n * Used by list and expansion pages to convert Zustand store state into\n * query params for the server. The base object carries pagination keys\n * (limit / offset); filter terms from the expression are merged in.\n *\n * When the expression is a flat AND of terms, each term becomes a flat\n * query param (backwards compatible with existing server endpoints).\n * When the expression contains OR/NOT/Group nodes, it is serialized\n * as a `q=` string using the server's query expression syntax.\n *\n * @example\n * const params = buildListParams<ValueSetListParams>(\n *   filterExpr,\n *   { limit: pagination.pageSize, offset: pagination.pageIndex * pagination.pageSize },\n * );\n */\nexport function buildListParams<T extends object>(\n  expr: FilterExpr,\n  base: T,\n): T {\n  if (isEmptyFilterExpr(expr)) return base;\n\n  // Flat AND of terms: serialize as individual key=value params.\n  if (isFlatAnd(expr)) {\n    const pairs = flattenFilterExpr(expr);\n    const extra = Object.fromEntries(\n      pairs\n        .filter(({ key }) => !(key in base))\n        .map(({ key, value }) => [key, value]),\n    );\n    return { ...base, ...extra } as T;\n  }\n\n  // Complex expression: serialize as q= string.\n  return { ...base, q: serializeFilterExpr(expr) } as T;\n}\n\n/**\n * Build a flat AND expression from an array of key/value pairs.\n * Convenience for constructing the initial state from existing filter params.\n */\nexport function termsToFilterExpr(\n  terms: { key: string; value: string }[],\n): FilterExpr {\n  return {\n    type: \"and\",\n    children: terms.map((t) => ({\n      type: \"term\",\n      key: t.key,\n      value: t.value,\n    })),\n  };\n}\n"],"mappings":";AA2DO,IAAM,eAA2B,EAAE,MAAM,OAAO,UAAU,CAAC,EAAE;;;AC9C7D,SAAS,aAAa,MAAgC;AAC3D,QAAM,MAAoB,CAAC;AAC3B,mBAAiB,MAAM,GAAG;AAC1B,SAAO;AACT;AAEA,SAAS,iBAAiB,MAAkB,KAAyB;AACnE,UAAQ,KAAK,MAAM;AAAA,IACjB,KAAK;AACH,UAAI,KAAK,IAAI;AACb;AAAA,IACF,KAAK;AAAA,IACL,KAAK;AACH,iBAAW,SAAS,KAAK,SAAU,kBAAiB,OAAO,GAAG;AAC9D;AAAA,IACF,KAAK;AAAA,IACL,KAAK;AACH,uBAAiB,KAAK,OAAO,GAAG;AAChC;AAAA,EACJ;AACF;AAcO,SAAS,kBACd,MACkC;AAClC,SAAO,aAAa,IAAI,EAAE,IAAI,CAAC,EAAE,KAAK,MAAM,OAAO,EAAE,KAAK,MAAM,EAAE;AACpE;AAKO,SAAS,kBAAkB,MAA2B;AAC3D,SAAO,aAAa,IAAI,EAAE,WAAW;AACvC;AAOA,SAAS,UAAU,MAA2B;AAC5C,MAAI,KAAK,SAAS,OAAQ,QAAO;AACjC,MAAI,KAAK,SAAS,MAAO,QAAO,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM;AAC5E,SAAO;AACT;AAUO,SAAS,oBAAoB,MAA0B;AAC5D,UAAQ,KAAK,MAAM;AAAA,IACjB,KAAK,QAAQ;AACX,YAAM,UAAU,KAAK,MAAM,QAAQ,OAAO,MAAM,EAAE,QAAQ,MAAM,KAAK;AACrE,aAAO,GAAG,KAAK,GAAG,OAAO,OAAO;AAAA,IAClC;AAAA,IACA,KAAK;AACH,aAAO,KAAK,SAAS,IAAI,CAAC,MAAM,oBAAoB,CAAC,CAAC,EAAE,KAAK,OAAO;AAAA,IACtE,KAAK;AACH,aAAO,KAAK,SAAS,IAAI,CAAC,MAAM,oBAAoB,CAAC,CAAC,EAAE,KAAK,MAAM;AAAA,IACrE,KAAK;AACH,aAAO,QAAQ,oBAAoB,KAAK,KAAK,CAAC;AAAA,IAChD,KAAK;AACH,aAAO,IAAI,oBAAoB,KAAK,KAAK,CAAC;AAAA,EAC9C;AACF;AAoBO,SAAS,gBACd,MACA,MACG;AACH,MAAI,kBAAkB,IAAI,EAAG,QAAO;AAGpC,MAAI,UAAU,IAAI,GAAG;AACnB,UAAM,QAAQ,kBAAkB,IAAI;AACpC,UAAM,QAAQ,OAAO;AAAA,MACnB,MACG,OAAO,CAAC,EAAE,IAAI,MAAM,EAAE,OAAO,KAAK,EAClC,IAAI,CAAC,EAAE,KAAK,MAAM,MAAM,CAAC,KAAK,KAAK,CAAC;AAAA,IACzC;AACA,WAAO,EAAE,GAAG,MAAM,GAAG,MAAM;AAAA,EAC7B;AAGA,SAAO,EAAE,GAAG,MAAM,GAAG,oBAAoB,IAAI,EAAE;AACjD;AAMO,SAAS,kBACd,OACY;AACZ,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU,MAAM,IAAI,CAAC,OAAO;AAAA,MAC1B,MAAM;AAAA,MACN,KAAK,EAAE;AAAA,MACP,OAAO,EAAE;AAAA,IACX,EAAE;AAAA,EACJ;AACF;","names":[]}

package/dist/types-B29bSeIg.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Entity option fetcher contract.
+ *
+ * Defines the transport-agnostic interface for fetching selectable options
+ * from a backend data source (REST, GraphQL, or any async provider).
+ * Extractable to @petrarca/sonnet-core -- no app-specific imports.
+ */
+/** A single selectable option. */
+interface EntityOption {
+    value: string;
+    label: string;
+}
+/** Parameters passed to the fetcher on each request. */
+interface EntityFetchParams {
+    /** Search string from the combobox input (debounced). */
+    search?: string;
+    /** Maximum number of options to return. */
+    limit?: number;
+}
+/**
+ * A function that fetches entity options from a data source.
+ *
+ * Implementations are transport-specific (REST, GraphQL, static, etc.)
+ * but all return the same shape. The hook and component never know
+ * which transport is used.
+ */
+type EntityOptionFetcher = (params: EntityFetchParams) => Promise<EntityOption[]>;
+/**
+ * Configuration for creating a REST-backed fetcher.
+ * Passed via x-ui-options when the data source is a REST list endpoint.
+ */
+interface RestFetcherConfig {
+    /** REST endpoint path (e.g. "/organizations"). Relative to API base URL. */
+    endpoint: string;
+    /** Property key used as the option value (e.g. "org_id"). */
+    valueKey: string;
+    /** Property key used as the option label (e.g. "name"). */
+    labelKey: string;
+    /**
+     * Query parameter name for the search term (default: "search").
+     * Override when the endpoint uses a different filter key (e.g. "name").
+     */
+    searchKey?: string;
+}
+/**
+ * Configuration for creating a GraphQL-backed fetcher.
+ * Passed via x-ui-options when the data source is a GraphQL query.
+ */
+interface GraphqlFetcherConfig {
+    /** GraphQL query document (a gql`` tagged template or raw string). */
+    query: string;
+    /** Dot path into the response data where the array lives (e.g. "organizations"). */
+    dataPath: string;
+    /** Property key used as the option value (e.g. "org_id"). */
+    valueKey: string;
+    /** Property key used as the option label (e.g. "name"). */
+    labelKey: string;
+}
+/**
+ * Factory function that creates an EntityOptionFetcher from widget options.
+ *
+ * The FetcherProvider supplies this factory via React context. The widget
+ * calls it with the x-ui-options to get a fetcher instance, without knowing
+ * which transport client is used.
+ */
+type EntityFetcherFactory = (options: RestFetcherConfig | GraphqlFetcherConfig) => EntityOptionFetcher;
+
+export type { EntityOptionFetcher as E, GraphqlFetcherConfig as G, RestFetcherConfig as R, EntityOption as a, EntityFetcherFactory as b, EntityFetchParams as c };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@petrarca/sonnet-core",
+  "version": "0.1.0",
+  "description": "Shared utilities, schema tools, and hooks for the Petrarca Sonnet component library",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./schema": {
+      "import": "./dist/schema/index.js",
+      "types": "./dist/schema/index.d.ts"
+    },
+    "./search": {
+      "import": "./dist/search/index.js",
+      "types": "./dist/search/index.d.ts"
+    },
+    "./hooks": {
+      "import": "./dist/hooks/index.js",
+      "types": "./dist/hooks/index.d.ts"
+    },
+    "./entityOptions": {
+      "import": "./dist/entityOptions/index.js",
+      "types": "./dist/entityOptions/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "nanoid": "^5.1.6",
+    "tailwind-merge": "3.3.1",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "@tanstack/react-query": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}