@dxos/react-ui-query 0.12.0

package/src/components/QueryForm/QueryForm.tsx

@@ -0,0 +1,77 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { Filter, Obj, Query, type QueryAST, type Tag } from '@dxos/echo';
+import { URI } from '@dxos/keys';
+import { type ThemedClassName } from '@dxos/react-ui';
+import { useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+import { Picker } from './Picker.tsx';
+import { extractTag, extractTypename } from './query.ts';
+
+export type QueryFormProps = ThemedClassName<{
+  initialQuery?: QueryAST.Query;
+  types?: { value: URI.URI; label: string }[];
+  tags?: Tag.Tag[];
+  onChange?: (query: Query.Any) => void;
+}>;
+
+// TODO(wittjosiah): Support more complex queries and traversals.
+export const QueryForm = ({ classNames, initialQuery, types, tags, onChange }: QueryFormProps) => {
+  const { t } = useTranslation(translationKey);
+
+  const initialType = initialQuery ? Option.getOrUndefined(extractTypename(initialQuery)) : undefined;
+  const initialTag = initialQuery ? Option.getOrUndefined(extractTag(initialQuery)) : undefined;
+
+  const [type, setType] = useState<URI.URI | null>(initialType ?? null);
+  const [tag, setTag] = useState<string | null>(initialTag ?? null);
+
+  const tagOptions = useMemo(() => tags?.map((tag) => ({ value: Obj.getURI(tag), label: tag.label })), [tags]);
+
+  const handleChange = useCallback(
+    ({ type, tag }: { type: URI.URI | null; tag: string | null }) => {
+      const typeFilter = type ? Filter.type(type) : null;
+      const tagFilter = tag ? Filter.tag(tag) : null;
+      const combined =
+        typeFilter && tagFilter ? Filter.and(typeFilter, tagFilter) : (typeFilter ?? tagFilter ?? Filter.nothing());
+      onChange?.(Query.select(combined));
+    },
+    [onChange],
+  );
+
+  const handleTypeChange = useCallback(
+    (value: string | null) => {
+      // Select.onValueChange returns bare string; values come from types[].value which are URI.URI.
+      const uri = value as URI.URI | null;
+      setType(uri);
+      handleChange({ type: uri, tag });
+    },
+    [handleChange, tag],
+  );
+
+  const handleTagChange = useCallback(
+    (tag: string | null) => {
+      setTag(tag);
+      handleChange({ type, tag });
+    },
+    [handleChange, type],
+  );
+
+  return (
+    <div className={mx('grid grid-cols-2 gap-2', classNames)}>
+      {types && (
+        <Picker placeholder={t('picker-type.placeholder')} values={types} value={type} onChange={handleTypeChange} />
+      )}
+      {tags && (
+        <Picker placeholder={t('picker-tag.placeholder')} values={tagOptions} value={tag} onChange={handleTagChange} />
+      )}
+    </div>
+  );
+};

package/src/components/QueryForm/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './QueryForm.tsx';

package/src/components/QueryForm/query.ts

@@ -0,0 +1,91 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Match from 'effect/Match';
+import * as Option from 'effect/Option';
+
+import { type QueryAST } from '@dxos/echo';
+import { type URI } from '@dxos/keys';
+
+// Helper to extract type URI from query AST
+export const extractTypename = (query: QueryAST.Query): Option.Option<URI.URI> => {
+  return Match.value(query).pipe(
+    Match.withReturnType<Option.Option<URI.URI>>(),
+    Match.when({ type: 'select' }, (q) => extractTypenameFromFilter(q.filter)),
+    Match.when({ type: 'filter' }, (q) => {
+      const selectionTypename = extractTypename(q.selection);
+      const filterTypename = extractTypenameFromFilter(q.filter);
+      return Option.isSome(selectionTypename) ? selectionTypename : filterTypename;
+    }),
+    Match.when({ type: 'options' }, (q) => extractTypename(q.query)),
+    Match.when({ type: 'from' }, (q) => extractTypename(q.query)),
+    Match.when({ type: 'order' }, (q) => extractTypename(q.query)),
+    Match.when({ type: 'limit' }, (q) => extractTypename(q.query)),
+    Match.orElse(() => Option.none()),
+  );
+};
+
+// Helper to extract tag from query AST
+export const extractTag = (query: QueryAST.Query): Option.Option<string> => {
+  return Match.value(query).pipe(
+    Match.withReturnType<Option.Option<string>>(),
+    Match.when({ type: 'select' }, (q) => extractTagFromFilter(q.filter)),
+    Match.when({ type: 'filter' }, (q) => {
+      const selectionTag = extractTag(q.selection);
+      const filterTag = extractTagFromFilter(q.filter);
+      return Option.isSome(filterTag) ? filterTag : selectionTag;
+    }),
+    Match.when({ type: 'options' }, (q) => extractTag(q.query)),
+    Match.when({ type: 'from' }, (q) => extractTag(q.query)),
+    Match.when({ type: 'order' }, (q) => extractTag(q.query)),
+    Match.when({ type: 'limit' }, (q) => extractTag(q.query)),
+    Match.orElse(() => Option.none()),
+  );
+};
+
+// Helper to extract type URI from filter AST
+const extractTypenameFromFilter = (filter: QueryAST.Filter): Option.Option<URI.URI> => {
+  return Match.value(filter).pipe(
+    Match.withReturnType<Option.Option<URI.URI>>(),
+    Match.when({ type: 'object' }, (f) => Option.fromNullishOr(f.typename)),
+    Match.when({ type: 'and' }, (f) =>
+      f.filters.reduce(
+        (acc: Option.Option<URI.URI>, filterItem: QueryAST.Filter) =>
+          Option.isSome(acc) ? acc : extractTypenameFromFilter(filterItem),
+        Option.none<URI.URI>(),
+      ),
+    ),
+    Match.when({ type: 'or' }, (f) =>
+      f.filters.reduce(
+        (acc: Option.Option<URI.URI>, filterItem: QueryAST.Filter) =>
+          Option.isSome(acc) ? acc : extractTypenameFromFilter(filterItem),
+        Option.none<URI.URI>(),
+      ),
+    ),
+    Match.orElse(() => Option.none()),
+  );
+};
+
+// Helper to extract tag from filter AST
+const extractTagFromFilter = (filter: QueryAST.Filter): Option.Option<string> => {
+  return Match.value(filter).pipe(
+    Match.withReturnType<Option.Option<string>>(),
+    Match.when({ type: 'tag' }, (f) => Option.some(f.tag)),
+    Match.when({ type: 'and' }, (f) =>
+      f.filters.reduce(
+        (acc: Option.Option<string>, filterItem: QueryAST.Filter) =>
+          Option.isSome(acc) ? acc : extractTagFromFilter(filterItem),
+        Option.none<string>(),
+      ),
+    ),
+    Match.when({ type: 'or' }, (f) =>
+      f.filters.reduce(
+        (acc: Option.Option<string>, filterItem: QueryAST.Filter) =>
+          Option.isSome(acc) ? acc : extractTagFromFilter(filterItem),
+        Option.none<string>(),
+      ),
+    ),
+    Match.orElse(() => Option.none()),
+  );
+};

package/src/components/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './QueryEditor/index.ts';
+export * from './QueryForm/index.ts';

package/src/hooks/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+export * from './useQueryBuilder.ts';

package/src/hooks/useQueryBuilder.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useMemo, useState } from 'react';
+
+import { Filter } from '@dxos/echo';
+import { QueryBuilder } from '@dxos/echo-query';
+/**
+ * Creates a filter from a query string.
+ */
+export const useQueryBuilder = (query?: string): Filter.Any => {
+  const builder = useMemo(() => new QueryBuilder(), []);
+  const [filter, setFilter] = useState<Filter.Any>(Filter.everything());
+  useEffect(() => {
+    if (query) {
+      const { filter } = builder.build(query);
+      setFilter(filter ?? Filter.everything());
+    } else {
+      setFilter(Filter.everything());
+    }
+  }, [builder, query]);
+
+  return filter;
+};

package/src/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './components/index.ts';
+export * from './hooks/index.ts';

package/src/translations.ts

@@ -0,0 +1,22 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Resource } from '@dxos/react-ui';
+
+export const translationKey = '@dxos/react-ui-query';
+
+export const translations = [
+  {
+    'en-US': {
+      [translationKey]: {
+        'query-editor.placeholder': 'Enter text to filter, or a query (e.g., "#tag")',
+
+        'picker-select.label': 'Select',
+        'picker-none.label': 'None',
+        'picker-type.placeholder': 'Type',
+        'picker-tag.placeholder': 'Tag',
+      },
+    },
+  },
+] as const satisfies Resource[];