@dxos/react-ui-form 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/components/ObjectProperties/ObjectProperties.tsx

@@ -0,0 +1,146 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import * as Function from 'effect/Function';
+import * as Option from 'effect/Option';
+import React, { type PropsWithChildren, useCallback, useMemo } from 'react';
+
+import { Obj, Ref, Tag, Type } from '@dxos/echo';
+import { useType } from '@dxos/echo-react';
+import { SchemaEx } from '@dxos/effect';
+import { invariant } from '@dxos/invariant';
+import { composable, composableProps } from '@dxos/react-ui';
+import { HuePicker } from '@dxos/react-ui-pickers';
+import { FactoryAnnotation } from '@dxos/schema';
+
+import { translationKey } from '#translations';
+
+import { Form, type FormFieldMap, META_TAGS_KEY, withMetaTags } from '../Form';
+
+export type ObjectPropertiesProps = PropsWithChildren<{ object: Obj.Unknown }>;
+
+// TODO(wittjosiah): Reconcile w/ ObjectForm.
+export const ObjectProperties = composable<HTMLDivElement, ObjectPropertiesProps>(
+  ({ children, object, ...props }, forwardedRef) => {
+    const db = Obj.getDatabase(object);
+    const meta = Obj.getMeta(object);
+    // `meta.tags` already holds `Ref<Tag>`s (materialized by the database handler).
+    const tags = [...meta.tags];
+    const values = useMemo(() => ({ [META_TAGS_KEY]: tags, ...object }), [object, tags]);
+
+    // Obj.getType fails for database-registered (dynamic) schemas due to DXN mismatch;
+    // useType queries by the object's stored type URI, resolving both static and dynamic schemas.
+    const typeUri = Obj.getTypeURI(object);
+    const typeFromRegistry = useType(db, typeUri);
+    const type = Obj.getType(object) ?? typeFromRegistry;
+
+    const formSchema = useMemo(() => {
+      return Function.pipe(
+        type,
+        Option.fromNullable,
+        Option.map((type) => Type.getSchema(type)),
+        Option.map((schema) => withMetaTags(schema)),
+        Option.getOrUndefined,
+      );
+    }, [type]);
+
+    // Persist a newly-created object referenced by one of the form's ref
+    // fields and return it. The calling RefField wires the new Ref into its
+    // own slot's form value; for the synthetic `_tags` array, the resulting
+    // form change is then synced back to `Obj.getMeta(object).tags` by
+    // `handleChange` below — so Tag.Tag follows the same generic path as any
+    // other ref-array field, no type-specific branching required here.
+    //
+    // Schemas whose required structure can't be produced by `Obj.make(schema,
+    // values)` alone (e.g. types with a required ref to a backing object) can
+    // declare a `FactoryAnnotation` to take over construction.
+    const handleCreate = useCallback(
+      (type: Type.AnyEntity, values: any): Obj.Unknown => {
+        invariant(db);
+        invariant(Type.isObject(type));
+        const factory = Option.getOrUndefined(FactoryAnnotation.get(Type.getSchema(type)));
+        const newObject = factory ? (factory(values) as Obj.Unknown) : Obj.make(type, values);
+        return db.add(newObject) as Obj.Unknown;
+      },
+      [db],
+    );
+
+    // TODO(wittjosiah): Use FormRootProps type.
+    const handleChange = useCallback(
+      (
+        { [META_TAGS_KEY]: metaTags, ...values }: any,
+        { isValid, changed }: { isValid: boolean; changed: Record<SchemaEx.JsonPath, boolean> },
+      ) => {
+        if (!isValid) {
+          return;
+        }
+
+        const changedPaths = Object.keys(changed).filter(
+          (path) => changed[path as SchemaEx.JsonPath],
+        ) as SchemaEx.JsonPath[];
+
+        // Handle meta-tags separately using Obj.update.
+        const hasTagsChange = changedPaths.some((path) => SchemaEx.splitJsonPath(path)[0] === META_TAGS_KEY);
+        if (hasTagsChange) {
+          Obj.update(object, (object) => {
+            // Copy so later in-place form mutations don't bypass the `Obj.update` boundary.
+            Obj.getMeta(object).tags = Array.isArray(metaTags) ? [...(metaTags as Ref.Ref<Tag.Tag>[])] : [];
+          });
+        }
+
+        // Handle other property changes.
+        const nonTagPaths = changedPaths.filter((path) => SchemaEx.splitJsonPath(path)[0] !== META_TAGS_KEY);
+        if (nonTagPaths.length > 0) {
+          Obj.update(object, () => {
+            for (const path of nonTagPaths) {
+              const parts = SchemaEx.splitJsonPath(path);
+              const value = Obj.getValue(values as any, parts);
+              Obj.setValue(object, parts, value);
+            }
+          });
+        }
+      },
+      [object],
+    );
+
+    if (!formSchema) {
+      return null;
+    }
+
+    return (
+      <Form.Root
+        schema={formSchema}
+        defaultValues={values as any}
+        createTypename={Type.getTypename(Tag.Tag)}
+        createOptionIcon='ph--plus--regular'
+        createOptionLabel={['add-tag.label', { ns: translationKey }]}
+        createInitialValuePath='label'
+        createFieldMap={createFieldMap}
+        db={db}
+        onValuesChanged={handleChange}
+        onCreate={handleCreate}
+      >
+        <Form.Viewport {...composableProps(props)} ref={forwardedRef}>
+          <Form.Content>
+            <Form.FieldSet />
+            {children}
+          </Form.Content>
+        </Form.Viewport>
+      </Form.Root>
+    );
+  },
+);
+
+const createFieldMap: FormFieldMap = {
+  hue: ({ type, label, layout, getValue, onValueChange }) => {
+    const handleChange = useCallback((nextHue: string) => onValueChange(type, nextHue), [onValueChange, type]);
+    const handleReset = useCallback(() => onValueChange(type, undefined), [onValueChange, type]);
+    return (
+      <>
+        {layout !== 'inline' && <Form.Label label={label} />}
+        <HuePicker value={getValue()} onChange={handleChange} onReset={handleReset} />
+      </>
+    );
+  },
+};

package/src/components/ObjectProperties/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './ObjectProperties';

package/src/components/ObjectTree/ObjectTree.stories.tsx

@@ -0,0 +1,134 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React from 'react';
+
+import { parseProto } from '@dxos/effect-proto';
+import { log } from '@dxos/log';
+import { type Config as ConfigProto, Runtime } from '@dxos/protocols/proto/dxos/config';
+// Raw .proto source resolved through `@dxos/protocols`'s `./proto/dxos/*.proto`
+// exports entry. Vite's `?raw` query suffix returns the file as a string so we
+// can hand it straight to `parseProto` -- the same flow the unit test uses.
+import configProto from '@dxos/protocols/proto/dxos/config.proto?raw';
+import { Syntax } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+
+import { translations } from '#translations';
+
+import { Form } from '../Form';
+import { ObjectTree } from './ObjectTree';
+
+const registry = parseProto(configProto);
+const ConfigSchema = registry.get('dxos.config.Config');
+
+// A representative Config value that exercises nested messages, arrays, enums
+// (rendered as their string names by the proto codec), and `google.protobuf.Any`.
+const value: ConfigProto = {
+  version: 1,
+  runtime: {
+    client: {
+      log: { filter: 'info', prefix: 'app' },
+      storage: {
+        persistent: true,
+        sqliteMode: Runtime.Client.Storage.SqliteMode.OPFS,
+        dataRoot: '/var/lib/dxos',
+      },
+      edgeFeatures: {
+        echoReplicator: true,
+        subductionReplicator: true,
+        signaling: true,
+      },
+      servicesMode: Runtime.Client.ServicesMode.SHARED_WORKER,
+      enableSnapshots: false,
+      snapshotInterval: 60_000,
+    },
+    app: {
+      org: 'DXOS',
+      theme: 'dark',
+      website: 'https://dxos.org',
+      build: {
+        timestamp: '2026-05-22T12:00:00Z',
+        commitHash: 'abc1234',
+        version: '0.8.3',
+        branch: 'main',
+      },
+    },
+    services: {
+      edge: { url: 'wss://edge.dxos.org' },
+      signaling: [
+        { server: 'wss://signal-1.dxos.org', api: 'v1' },
+        { server: 'wss://signal-2.dxos.org', api: 'v1' },
+      ],
+      iceProviders: [{ urls: 'turn:turn.dxos.org' }],
+    },
+    keys: [
+      { name: 'OPENAI_API_KEY', value: 'sk-...' },
+      { name: 'ANTHROPIC_API_KEY', value: 'ant-...' },
+    ],
+  },
+};
+
+const meta = {
+  title: 'ui/react-ui-form/ObjectTree',
+  component: ObjectTree,
+  decorators: [withTheme(), withLayout({ layout: 'column', scroll: true })],
+  parameters: {
+    layout: 'fullscreen',
+    translations,
+  },
+} satisfies Meta<typeof ObjectTree>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    schema: ConfigSchema,
+    value: value,
+  },
+};
+
+export const JSON = () => (
+  <Syntax.Root data={value}>
+    <Syntax.Content>
+      <Syntax.Filter />
+      <Syntax.Viewport>
+        <Syntax.Code />
+      </Syntax.Viewport>
+    </Syntax.Content>
+  </Syntax.Root>
+);
+
+// Renders the same proto-derived `ConfigSchema` + `value` through the
+// interactive `Form` component, for side-by-side comparison with the
+// read-only ObjectTree above. `db` is intentionally omitted -- the proto
+// schema is not an ECHO type, so there's no space/database in play.
+export const WithForm = () => (
+  <Form.Root
+    schema={ConfigSchema as any}
+    defaultValues={value as any}
+    onSave={(next) => log.info('save', { next })}
+    onCancel={() => log.info('cancel')}
+  >
+    <Form.Viewport>
+      <Form.Content>
+        <Form.FieldSet />
+        <Form.Actions />
+      </Form.Content>
+    </Form.Viewport>
+  </Form.Root>
+);
+
+export const WithReadOnlyForm = () => (
+  <Form.Root schema={ConfigSchema as any} defaultValues={value as any} readonly={true}>
+    <Form.Viewport>
+      <Form.Content>
+        <Form.FieldSet />
+        <Form.Actions />
+      </Form.Content>
+    </Form.Viewport>
+  </Form.Root>
+);

package/src/components/ObjectTree/ObjectTree.tsx

@@ -0,0 +1,190 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// A minimal, read-only schema-driven viewer. Walks an Effect Schema and a
+// matching value and produces a flat list of indented key/value rows -- one
+// per leaf field, with nested Struct fields contributing a header row plus
+// recursively-indented children, and arrays expanded as `[index]` rows.
+//
+// Designed to drive a hierarchical editor over schemas produced by
+// `@dxos/effect-proto` (e.g. the proto-generated `dxos.config.Config`
+// schema), but works for any Effect Struct schema.
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import React, { type ReactElement, type ReactNode, type RefAttributes } from 'react';
+
+import { composable, composableProps } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+import { type ComposableProps } from '@dxos/ui-types';
+
+export type ObjectTreeProps<T> = {
+  schema: Schema.Schema<T, any, never>;
+  value: T;
+};
+
+/**
+ * Render a value as a sequence of key/value rows whose shape and order are
+ * driven by `schema`. Object-typed properties become a header row whose
+ * children are indented under it; arrays expand element-by-element.
+ *
+ * Composable: spreads unknown props (incl. `className` / `classNames` /
+ * `style` / `role`) onto its root `<div>` and forwards its ref, so it can
+ * be slotted into themed parents like `Panel.Content`.
+ */
+const ObjectTreeImpl = composable<HTMLDivElement, ObjectTreeProps<any>>(({ schema, value, ...props }, forwardedRef) => (
+  <div {...composableProps(props, { role: 'table', classNames: 'font-mono text-sm w-full' })} ref={forwardedRef}>
+    <Node ast={schema.ast} value={value} label={null} depth={0} />
+  </div>
+));
+
+ObjectTreeImpl.displayName = 'ObjectTree';
+
+// `composable<HTMLDivElement, ObjectTreeProps<any>>` erases the `T` type
+// parameter inside the factory; the cast restores the generic signature for
+// consumers without changing the underlying component (the COMPOSABLE marker
+// stays attached). This is the pattern documented on `composable()` itself.
+export const ObjectTree = ObjectTreeImpl as unknown as <T>(
+  props: ComposableProps<ObjectTreeProps<T>> & RefAttributes<HTMLDivElement>,
+) => ReactElement | null;
+
+/**
+ * Peel wrappers that don't affect the runtime shape: Refinements pass their
+ * `from`, Suspends resolve via `f()`, and Transformations expose the encoded
+ * (input) side. Repeated unwrapping handles chains like `Schema.suspend ->
+ * Refinement -> TypeLiteral`.
+ */
+const unwrap = (ast: SchemaAST.AST): SchemaAST.AST => {
+  if (SchemaAST.isRefinement(ast)) {
+    return unwrap(ast.from);
+  }
+  if (SchemaAST.isSuspend(ast)) {
+    return unwrap(ast.f());
+  }
+  if (SchemaAST.isTransformation(ast)) {
+    return unwrap(ast.from);
+  }
+  return ast;
+};
+
+/**
+ * Effect models `Schema.optional(X)` as a property whose type AST is
+ * `Union(X, UndefinedKeyword)`. For walking purposes we want X -- the
+ * undefined branch carries no schema information for the viewer.
+ */
+const stripOptional = (ast: SchemaAST.AST): SchemaAST.AST => {
+  if (!SchemaAST.isUnion(ast)) {
+    return ast;
+  }
+  const nonUndef = ast.types.filter((t) => !SchemaAST.isUndefinedKeyword(t));
+  return nonUndef.length === 1 ? nonUndef[0] : ast;
+};
+
+type NodeProps = {
+  ast: SchemaAST.AST;
+  value: unknown;
+  /** Row label; `null` means render children directly without a header row. */
+  label: ReactNode | null;
+  depth: number;
+};
+
+const Node = ({ ast, value, label, depth }: NodeProps) => {
+  const inner = unwrap(stripOptional(ast));
+
+  // Struct: header row + indented children. Skipping the header at depth 0
+  // keeps the root flush-left.
+  if (SchemaAST.isTypeLiteral(inner) && isPlainObject(value)) {
+    const childDepth = label === null ? depth : depth + 1;
+    return (
+      <>
+        {label !== null && <Row label={label} value={null} depth={depth} kind='group' />}
+        {inner.propertySignatures.map((prop) => (
+          <Node
+            key={String(prop.name)}
+            ast={prop.type}
+            value={(value as Record<string, unknown>)[String(prop.name)]}
+            label={String(prop.name)}
+            depth={childDepth}
+          />
+        ))}
+      </>
+    );
+  }
+
+  // Array (`Schema.Array(X)` -> TupleType with single rest element).
+  if (SchemaAST.isTupleType(inner) && Array.isArray(value)) {
+    const elemType = inner.rest[0]?.type;
+    return (
+      <>
+        {label !== null && <Row label={label} value={`Array(${value.length})`} depth={depth} kind='group' />}
+        {value.map((item, index) => (
+          <Node
+            key={index}
+            ast={elemType ?? SchemaAST.unknownKeyword}
+            value={item}
+            label={`[${index}]`}
+            depth={depth + 1}
+          />
+        ))}
+      </>
+    );
+  }
+
+  // Leaf (scalars, unions of literals, unknown, etc.).
+  return <Row label={label ?? ''} value={formatLeaf(value)} depth={depth} kind='leaf' />;
+};
+
+type RowProps = {
+  label: ReactNode;
+  value: ReactNode;
+  depth: number;
+  kind: 'group' | 'leaf';
+};
+
+const Row = ({ label, value, depth }: RowProps) => (
+  <div role='row' className={mx('flex items-baseline gap-3 py-1')} style={{ paddingInlineStart: 8 + depth * 16 }}>
+    <div role='cell' className='text-subdued'>
+      {label}
+    </div>
+    <div role='cell' className={mx('break-all text-base-fg')}>
+      {value}
+    </div>
+  </div>
+);
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * Format a leaf value for display. Strings are quoted so empty strings are
+ * visible; missing values surface as an em-dash so the row stays present.
+ */
+const formatLeaf = (value: unknown): ReactNode => {
+  if (value === undefined) {
+    return null;
+  }
+
+  if (value === null) {
+    return <span className='text-description'>null</span>;
+  }
+
+  switch (typeof value) {
+    case 'string':
+      // Quote strings so empty strings remain visible (`""` rather than blank).
+      return <span className='text-blue-text'>{JSON.stringify(value)}</span>;
+    case 'number':
+    case 'bigint':
+      return <span className='text-green-text'>{String(value)}</span>;
+    case 'boolean':
+      return <span className='text-purple-text'>{String(value)}</span>;
+    default:
+      // Objects we couldn't expand via schema (e.g. `google.protobuf.Any` -> Unknown)
+      // are rendered as compact JSON.
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return String(value);
+      }
+  }
+};

package/src/components/ObjectTree/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './ObjectTree';

package/src/components/RefEditor/RefEditor.stories.tsx

@@ -0,0 +1,148 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import React, { Fragment, useState } from 'react';
+
+import { type Database, Filter, Obj } from '@dxos/echo';
+import { random } from '@dxos/random';
+import { useQuery } from '@dxos/react-client/echo';
+import { useClientStory, withClientProvider } from '@dxos/react-client/testing';
+import { JsonHighlighter } from '@dxos/react-ui-syntax-highlighter';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
+import { type ValueGenerator, createObjectFactory } from '@dxos/schema/testing';
+import { Person } from '@dxos/types';
+
+import { translations } from '#translations';
+
+import { EMAIL_REGEX } from './ref-editor-extension';
+import { RefEditor, type RefEditorProps } from './RefEditor';
+
+const generator: ValueGenerator = random as any;
+
+random.seed(7);
+
+/**
+ * Generate Person objects into the space. The generator does not populate array fields, so derive
+ * email addresses from each person's name (every other person gets a second work alias so the
+ * email-mode picker shows multiple entries per person).
+ */
+const generatePeople = async (db: Database.Database, count: number) => {
+  const people = await createObjectFactory(db, generator)([{ type: Person.Person, count }]);
+  people.forEach((person, index) => {
+    Obj.update(person, (person: Obj.Mutable<Person.Person>) => {
+      const slug = (person.fullName ?? 'user')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '.')
+        .replace(/^\.+|\.+$/g, '');
+      person.emails = [
+        { value: `${slug}@example.com` },
+        ...(index % 2 === 0 ? [{ label: 'work', value: `${slug}@work.example.com` }] : []),
+        ...(index % 4 === 0 ? [{ label: 'private', value: `${random.lorem.word()}@gmail.com` }] : []),
+      ];
+    });
+  });
+  return people;
+};
+
+/** Person email addresses (the values a person can be captured as in email mode). */
+const getPersonValues = (object: Obj.Unknown): readonly string[] =>
+  Obj.instanceOf(Person.Person, object) ? (object.emails ?? []).map(({ value }) => value) : [];
+
+/**
+ * Dense reference grid of the generated people and their email addresses.
+ */
+const PeopleGrid = ({ db }: { db?: Database.Database }) => {
+  const people = useQuery(db, Filter.type(Person.Person));
+  return (
+    <div className='grid grid-cols-[max-content_1fr] gap-x-4 text-sm text-description'>
+      {people.flatMap((person) =>
+        (person.emails ?? []).map(({ value }) => (
+          <Fragment key={`${person.id}-${value}`}>
+            <span className='truncate'>{person.fullName}</span>
+            <span className='truncate'>{value}</span>
+          </Fragment>
+        )),
+      )}
+    </div>
+  );
+};
+
+type StoryProps = Partial<Pick<RefEditorProps, 'value' | 'mode' | 'activateOnTyping' | 'autoFocus'>>;
+
+// NOTE: The Person config (type/match/getValues) is supplied in render, not args — Storybook's
+// arg traversal attempts to mutate the proxied ECHO schema and crashes.
+const DefaultStory = ({ value: initialValue, ...args }: StoryProps) => {
+  const { space } = useClientStory();
+  const [value, setValue] = useState(initialValue ?? '');
+
+  return (
+    <div className='flex flex-col gap-2'>
+      <RefEditor
+        {...args}
+        value={initialValue}
+        type={Person.Person}
+        match={EMAIL_REGEX}
+        getValues={getPersonValues}
+        icon='ph--user--regular'
+        db={space?.db}
+        onChange={setValue}
+        classNames='border'
+      />
+      <JsonHighlighter data={{ value }} classNames='text-xs' />
+      <PeopleGrid db={space?.db} />
+    </div>
+  );
+};
+
+const meta = {
+  title: 'ui/react-ui-form/RefEditor',
+  render: DefaultStory,
+  decorators: [
+    withTheme(),
+    withLayout({ layout: 'column', classNames: 'p-2', scroll: true }),
+    withClientProvider({
+      types: [Person.Person],
+      createIdentity: true,
+      createSpace: true,
+      onCreateSpace: async ({ space }) => {
+        await generatePeople(space.db, 8);
+      },
+    }),
+  ],
+  parameters: {
+    translations,
+  },
+} satisfies Meta<typeof DefaultStory>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    autoFocus: true,
+  },
+};
+
+export const ActivateOnTyping: Story = {
+  args: {
+    autoFocus: true,
+    activateOnTyping: true,
+  },
+};
+
+export const EmailMode: Story = {
+  args: {
+    autoFocus: true,
+    mode: 'email',
+    activateOnTyping: true,
+  },
+};
+
+export const WithEmail: Story = {
+  args: {
+    value: 'someone@example.com ',
+  },
+};