@wral/studio.ui.search-filter 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# @wral/studio.ui.search-filter
+
+`<studio-search-filter>` — a visual Lucene query builder for WRAL Studio
+apps (DEV-1121). Extracted from Curator's embedded query builder so any
+Studio app can build search-index queries with the same UI.
+
+It edits a query string through a rule/group/if-then tree with
+include/exclude and all/any toggles, drag-to-reorder, and a raw
+"Advanced" editor. When an incoming query uses syntax the visual model
+cannot round-trip losslessly (unknown fields, withheld operators, mixed
+AND/OR precedence, `+` prefixes, positive implicit joins), the component
+automatically stays in raw mode so production queries are never silently
+rewritten.
+
+## Host contract
+
+```html
+<studio-search-filter
+	.value=${queryString}
+	@change=${e => save(e.detail.value)}
+></studio-search-filter>
+```
+
+- **`value`** (String property/attribute) — the Lucene query string in.
+- **`change`** (CustomEvent, `detail.value`) — the edited query string
+  out, fired on every committed edit. The event does not bubble and does
+  not cross shadow boundaries: listen directly on the element.
+
+The component only *builds* the query string. Executing searches stays
+in the host app (e.g. via `@wral/sdk-search`).
+
+## Configuration (all JSON)
+
+The component cannot know which fields a consumer's search index allows,
+so the field dropdown, operator dropdowns, and boolean joiners are all
+supplied by the consumer as JSON — as properties or as JSON-encoded
+attributes. Everything defaults to the bundled **publication preset**
+(story search against `api.wral.com/search`), which is exactly Curator's
+original catalog and copy.
+
+### `fields` — the field catalog
+
+```json
+{
+	"tag":   { "label": "Tag", "path": "tags.name", "type": "text",
+	           "hint": "e.g. UNC sports" },
+	"uri":   { "label": "Article URL", "path": "uri", "type": "url" },
+	"date":  { "label": "Published", "path": "metadata.articlePublishedTime",
+	           "type": "date" },
+	"video": { "label": "Has hero video", "path": "metadata.ogVideo",
+	           "type": "video", "durationPath": "metadata.ogVideoDuration" },
+	"any":   { "label": "Any field", "path": "", "type": "text" }
+}
+```
+
+- `path` is the actual search-index field name. `""` marks the backend's
+  default full-text field: bare terms (no `field:` prefix) parse to it
+  and it serializes without a prefix.
+- `type` is one of `text`, `url`, `date`, `number`, `video`.
+  - `url` gets `is exactly` (matches `path.keyword`) and
+    `is anywhere under` (quoted contains on the analyzed field).
+  - `video` models an existence flag plus a numeric companion field:
+    `has a …` tests `_exists_:path`; the duration operators range over
+    `durationPath` (required for this type).
+- `hint` is the value input's placeholder.
+- `ops` (optional) overrides the operator list for just this field.
+
+`parseLucene` and the round-trip check key off the active catalog: a
+query naming a field outside it will not open in the visual editor.
+
+### `operators` — per-type operator dropdowns
+
+```json
+{ "text": [ { "id": "phrase", "label": "contains the phrase" },
+            { "id": "term", "label": "matches the word" } ] }
+```
+
+Consumers may subset and relabel, but not invent ids — serialization is
+keyed on the id. Known ids per type:
+
+| type   | ids |
+|--------|-----|
+| text   | `phrase`, `term`, `starts`, `fuzzy`, `exists` |
+| url    | `is`, `under` |
+| date   | `after`, `before`, `between` |
+| number | `gte`, `lte`, `between` |
+| video  | `exists`, `longer`, `shorter`, `between` |
+
+A query using a withheld operator stays in raw mode.
+
+### `booleans` — the group joiners (all/any toggle)
+
+```json
+[ { "id": "AND", "label": "all" }, { "id": "OR", "label": "any" } ]
+```
+
+Only `AND` and `OR` exist in the Lucene subset. Restricting to one
+joiner keeps queries using the other in raw mode, and withdraws the
+If/then action (conditionals desugar to OR-of-ANDs).
+
+### `defaults` — seed rules
+
+```json
+{
+	"field": "title",
+	"conditional": {
+		"if":   { "field": "tag", "op": "term" },
+		"then": { "field": "uri", "op": "under", "negate": true },
+		"else": { "field": "uri", "op": "under" }
+	}
+}
+```
+
+The field a new rule starts on, and the three seed rules of a new
+If/then. Falls back to the catalog's first field.
+
+### `labels` — copy
+
+```json
+{ "itemNoun": "asset", "itemNounPlural": "assets" }
+```
+
+All copy defaults to the publication preset's story wording
+("Stories must match…", "No rules yet, so every story can appear…").
+`itemNoun`/`itemNounPlural` rewrite the noun-bearing strings; every
+individual string can also be overridden — see `src/labels.mjs` for the
+full key list.
+
+### Presets
+
+`import { publicationPreset } from '@wral/studio.ui.search-filter'` —
+`{ fields, defaults, labels }` for publication search. New presets
+(system search, DAM, Content assets) are plain data modules under
+`src/presets/`; nothing in the component needs to change to add one.
+
+## Installing
+
+```sh
+npm install @wral/studio.ui.search-filter lit
+```
+
+```js
+import '@wral/studio.ui.search-filter';        // registers the tag too
+// or, registration only:
+import '@wral/studio.ui.search-filter/define';
+// model utilities for host apps:
+import { equivalent, createQueryModel } from '@wral/studio.ui.search-filter';
+// DOM-free (servers, workers, node tests — no lit/component):
+import { equivalent } from '@wral/studio.ui.search-filter/model';
+```
+
+Or drop in from the CDN (lit bundled, nothing else needed):
+
+```html
+<script type="module"
+	src="https://cdn.wral.com/@wral/studio.ui.search-filter/latest/define.standalone.js"></script>
+```
+
+`equivalent(a, b)` tells hosts whether two query strings differ only by
+representational noise the builder normalizes (implicit vs explicit AND,
+`NOT`/`-`, redundant parens, …) — Curator uses it to avoid marking a
+collection dirty when the builder re-serializes an equivalent query.
+
+## Host expectations
+
+- `lit` is a peer dependency in the npm build (external, host-provided);
+  only `define.standalone.js` bundles it.
+- The templates render **studio-ui** elements (`studio-button`,
+  `studio-button-group`, `studio-select`, `studio-input`, `studio-icon`,
+  `studio-tooltip`). They are global custom elements the host page must
+  provide — in Studio, the shell loads
+  `https://cdn.wral.studio/ui/components/core/latest-v0/studio-ui.bundle.js`.
+  They are deliberately not imported or bundled here.
+- Theming is via CSS custom properties, every one consumed with a
+  fallback: `--studio-primary/secondary/surface/bg/fg/muted/subtle/
+  border/line` and `--wral-red/green/green-deep/purple` plus
+  `--wral-font-body/ui/mono`.
+
+## Developing
+
+```sh
+npm run dev    # vite demo (index.html)
+npm test       # jest (ESM), jsdom for component tests
+npm run lint
+npm run build  # dist/index.mjs + dist/define.mjs (lit external)
+               # + dist/define.standalone.js (self-contained)
+```
+
+## Releasing
+
+Tag `vX.Y.Z` and push. Bitbucket Pipelines lints/tests, builds, publishes
+to npm, uploads `dist/` to
+`${S3_BUCKET}/${S3_PREFIX}/vX.Y.Z` (immutable) and refreshes the
+`vX.Y`, `vX` and `latest` aliases (+ CloudFront invalidation), matching
+the `web-components.*` convention. Required repo variables: `NPM_TOKEN`,
+`AWS_*`, `S3_BUCKET`, `S3_PREFIX` (e.g. `@wral/studio.ui.search-filter`),
+`AWS_DISTRIBUTION_ID`.

package/dist/define.mjs

@@ -0,0 +1,11 @@
+import { S as i } from "./search-filter-B-aiJCKp.js";
+const t = "studio-search-filter";
+function o() {
+  const e = globalThis?.customElements;
+  e && (e.get(t) || e.define(t, i));
+}
+typeof window < "u" && globalThis.customElements && o();
+export {
+  t as TAG_NAME,
+  o as defineAll
+};