@zephytiju/prism-search-results 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# PrismSearchResultsMicroUI
+
+Platform Prism search-results micro-UI. Component id: `search-results`.
+Published to npm as [`@zephytiju/prism-search-results`](https://www.npmjs.com/package/@zephytiju/prism-search-results).
+
+Read-only rendering surface for the entity-search contract family: it consumes the channels the
+query-box publishes and never talks to Lattice itself. Render order is fixed — error alert with a
+Retry button, busy-without-results skeletons, guided empty state, then the `{N} MATCHES` header
+and entity cards (dimmed via opacity while a follow-up search is in flight). Composed
+applications (for example Guanlan) consume it as-is; the component is platform-owned.
+
+## Channel contract
+
+| Direction | Kind | Id | Payload |
+| --- | --- | --- | --- |
+| consumes | state | `query-box.entity-results` | `EntityResultsProjection \| null` |
+| consumes | state | `query-box.search-status` | `SearchStatus` (imported from `@zephytiju/prism-query-box`) |
+| publishes | state | `search-results.selected-entity` | `{ id, ontologyInterface: "IEntitySummary", label }` on card click |
+| emits | event | `query-box.search-retry` | `null` — the error Retry button asks the query-box to re-run its last request |
+
+Channel ids are string literals at every call-site so the build-time channel-graph scanner can
+derive the graph. Channel reads use `usePrismStateValue`; the single publication is setter-only.
+
+## Audit rule
+
+Entity search is NOT audit-worthy. This component emits NO audit event. The only event it ever
+emits is the internal `query-box.search-retry` (an error-retry handshake inside the search
+contract family, not an observable domain action).
+
+## Theme
+
+No colors are hardcoded. The component uses Mantine components without color props; the color
+theme comes from the host runtime, which wraps the component in its `MantineProvider`. The
+in-flight dimming uses opacity, not a color.
+
+## Local development
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run dev
+```
+
+`npm install` pulls the platform peers (`@zephytiju/prism-react`,
+`@zephytiju/prism-query-box`, `@zephytiju/lattice-common-interfaces`) from the npm
+registry, along with the host-side peer dependencies (`react`, `react-dom`,
+`@mantine/core`). When consuming the published package, install it directly
+(`npm install @zephytiju/prism-search-results`) and provide those peer dependencies in
+the host application.
+
+The demo (`npm run dev`) plays the host: buttons publish sample results, busy, idle, and error
+states onto the query-box channels so every render branch can be inspected in the browser.
+
+## Design record
+
+https://qcnwge0wy4s0.feishu.cn/wiki/K40nwA5TZiUE7Nk5hK6cE0W8nTe — §7 (channel contracts) and
+§8 (Lattice transport and interface clients).

package/dist/SearchResults.d.ts

@@ -0,0 +1,28 @@
+import type { EntityReference } from "@zephytiju/lattice-common-interfaces";
+/**
+ * Payload published on "search-results.selected-entity" when an entity card is
+ * clicked — an EntityReference pinned to the IEntitySummary interface.
+ */
+export type SelectedEntity = EntityReference & {
+    readonly ontologyInterface: "IEntitySummary";
+    readonly label: string;
+};
+export interface SearchResultsProps {
+    /** Guidance copy for the pre-search empty state. */
+    readonly emptyStateHint?: string;
+    /** Copy for the error alert title. */
+    readonly errorTitle?: string;
+}
+/**
+ * Platform Prism search-results micro-UI (component id "search-results").
+ *
+ * Read-only consumer of the query-box channels; makes NO Lattice calls. Render
+ * order: error alert (with retry), busy-without-results skeletons, guided empty
+ * state, then the "{N} MATCHES" header and entity cards — dimmed via opacity
+ * while a follow-up search is in flight. Selecting a card publishes
+ * "search-results.selected-entity"; the error Retry button emits the internal
+ * "query-box.search-retry" event so the query-box re-runs its last request.
+ * Entity search is NOT audit-worthy: no audit event is ever emitted.
+ */
+export declare function SearchResults({ emptyStateHint, errorTitle, }: SearchResultsProps): import("react").JSX.Element;
+//# sourceMappingURL=SearchResults.d.ts.map

package/dist/SearchResults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchResults.d.ts","sourceRoot":"","sources":["../src/SearchResults.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAA2B,MAAM,sCAAsC,CAAC;AAIrG;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG;IAC7C,QAAQ,CAAC,iBAAiB,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sCAAsC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,EAC5B,cAAyC,EACzC,UAAgC,GACjC,EAAE,kBAAkB,+BA6FpB"}

package/dist/SearchResults.js

@@ -0,0 +1,36 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Alert, Badge, Button, Card, Group, Skeleton, Stack, Text } from "@mantine/core";
+import { emitPrismEvent, usePrismStateSetter, usePrismStateValue } from "@zephytiju/prism-react";
+const DEFAULT_EMPTY_STATE_HINT = "Enter a query in the search box above to find entities. Apply filters to narrow the result set.";
+const DEFAULT_ERROR_TITLE = "Search failed";
+/**
+ * Platform Prism search-results micro-UI (component id "search-results").
+ *
+ * Read-only consumer of the query-box channels; makes NO Lattice calls. Render
+ * order: error alert (with retry), busy-without-results skeletons, guided empty
+ * state, then the "{N} MATCHES" header and entity cards — dimmed via opacity
+ * while a follow-up search is in flight. Selecting a card publishes
+ * "search-results.selected-entity"; the error Retry button emits the internal
+ * "query-box.search-retry" event so the query-box re-runs its last request.
+ * Entity search is NOT audit-worthy: no audit event is ever emitted.
+ */
+export function SearchResults({ emptyStateHint = DEFAULT_EMPTY_STATE_HINT, errorTitle = DEFAULT_ERROR_TITLE, }) {
+    const results = usePrismStateValue("query-box.entity-results");
+    const status = usePrismStateValue("query-box.search-status");
+    const publishSelectedEntity = usePrismStateSetter("search-results.selected-entity");
+    if (status?.phase === "error") {
+        return (_jsx(Alert, { variant: "light", title: errorTitle, "data-testid": "search-results-error", children: _jsxs(Stack, { gap: "sm", children: [_jsx(Text, { size: "sm", "data-testid": "search-results-error-message", children: status.message }), _jsx(Group, { children: _jsx(Button, { variant: "default", "data-testid": "search-results-retry", onClick: () => emitPrismEvent("query-box.search-retry", null), children: "Retry" }) })] }) }));
+    }
+    if (status?.phase === "busy" && results === null) {
+        return (_jsx(Stack, { gap: "sm", "data-testid": "search-results-loading", "aria-busy": "true", children: [0, 1, 2].map((row) => (_jsx(Skeleton, { height: 72, radius: "md" }, row))) }));
+    }
+    if (results === null) {
+        return (_jsx(Card, { withBorder: true, "data-testid": "search-results-empty", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { fw: 500, children: "No results yet" }), _jsx(Text, { size: "sm", children: emptyStateHint })] }) }));
+    }
+    const inFlight = status?.phase === "busy";
+    return (_jsxs(Stack, { gap: "sm", "data-testid": "search-results-list", style: { opacity: inFlight ? 0.5 : 1 }, children: [_jsxs(Group, { justify: "space-between", children: [_jsxs(Text, { fw: 600, "data-testid": "search-results-count", children: [results.resultIds.length, " MATCHES"] }), results.nextCursor !== undefined ? (_jsx(Badge, { variant: "light", size: "sm", children: "more available" })) : null] }), results.items.map((item) => (_jsx(Card, { withBorder: true, "data-testid": `search-result-card-${item.id}`, style: { cursor: "pointer" }, onClick: () => publishSelectedEntity({
+                    id: item.id,
+                    ontologyInterface: "IEntitySummary",
+                    label: item.label,
+                }), children: _jsxs(Group, { justify: "space-between", wrap: "nowrap", children: [_jsxs("div", { children: [_jsx(Text, { fw: 500, children: item.label }), _jsx(Text, { size: "sm", children: item.id })] }), _jsx(Badge, { variant: "light", children: item.type })] }) }, item.id)))] }));
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SearchResults } from "./SearchResults.js";
+export type { SearchResultsProps, SelectedEntity } from "./SearchResults.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { SearchResults } from "./SearchResults.js";

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@zephytiju/prism-search-results",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Platform Prism search-results micro-UI (component id \"search-results\"): renders the entity-results and search-status channels published by the query-box — empty, busy, error-with-retry, and match-list states — and publishes the selected entity. No Lattice calls.",
+  "license": "UNLICENSED",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": { "access": "public" },
+  "files": ["dist"],
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "@mantine/core": "^8.1.1",
+    "@zephytiju/lattice-common-interfaces": ">=0.1.0",
+    "@zephytiju/prism-query-box": ">=0.1.0",
+    "@zephytiju/prism-react": ">=0.1.0",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "devDependencies": {
+    "@mantine/core": "8.1.1",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "@zephytiju/lattice-common-interfaces": "0.1.0",
+    "@zephytiju/prism-query-box": "0.1.0",
+    "@zephytiju/prism-react": "0.1.0",
+    "jsdom": "^25.0.1",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "typescript": "^5.7.2",
+    "vite": "6.0.5",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}