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

package/src/components/Form/FormFieldSet.tsx

@@ -0,0 +1,213 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import React, { useMemo, useState } from 'react';
+
+import { type AnyProperties } from '@dxos/echo/internal';
+import { SchemaEx } from '@dxos/effect';
+import { IconButton, useTranslation } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { translationKey } from '#translations';
+
+import { type FormHandlerProps } from '../../hooks';
+import { getRootFormProperties } from '../../util';
+import { useFormValues } from './Form';
+import { FormField, type FormFieldProps } from './FormField';
+import { FormFieldErrorBoundary, FormFieldLabel } from './FormFieldComponent';
+import { DEFAULT_LAYOUT_NAME, FormLayout, FormLayoutAnnotation } from './Layout';
+
+const FORM_FIELDSET_NAME = 'Form.FieldSet';
+
+export type FormFieldSetProps<T extends AnyProperties> = {
+  label?: string;
+  sort?: string[];
+  /**
+   * When set, renders a toggle button at the end of the label row that
+   * shows/hides the field set body. Used for nested objects.
+   */
+  collapsible?: boolean;
+  exclude?: (props: SchemaEx.SchemaProperty[]) => SchemaEx.SchemaProperty[];
+  /**
+   * Picks a named layout out of `FormLayoutAnnotation` when present.
+   * Falls back to `'default'`. Ignored when the schema has no annotation
+   * (linear rendering then takes over).
+   */
+  layoutName?: string;
+} & Pick<FormHandlerProps<T>, 'schema'> &
+  Pick<
+    FormFieldProps,
+    | 'path'
+    | 'autoFocus'
+    | 'readonly'
+    | 'layout'
+    | 'projection'
+    | 'fieldMap'
+    | 'fieldProvider'
+    | 'createTypename'
+    | 'createOptionLabel'
+    | 'createOptionIcon'
+    | 'createInitialValuePath'
+    | 'createFieldMap'
+    | 'db'
+    | 'useType'
+    | 'getOptions'
+    | 'onCreate'
+  >;
+
+/**
+ * Renders a set of form fields derived from a schema object.
+ */
+export const FormFieldSet = ({
+  label,
+  schema,
+  readonly,
+  path,
+  sort,
+  collapsible,
+  exclude,
+  projection,
+  layout,
+  layoutName = DEFAULT_LAYOUT_NAME,
+  ...props
+}: FormFieldSetProps<any>) => {
+  const { t } = useTranslation(translationKey);
+  const values = useFormValues(FORM_FIELDSET_NAME, path);
+  const properties = useFormFieldSetProperties({ schema, values, exclude, sort, projection });
+  // TODO(burdon): Generalize collapse state (cf. useSelected in react-ui-attention, plugin-markdown cursor state).
+  const [collapsed, setCollapsed] = useState(false);
+  if ((readonly || layout === 'static') && values == null) {
+    return null;
+  }
+
+  // If the schema carries a layout template, hand off to <Form.Layout/> which renders the DSL.
+  // Linear rendering still runs when no annotation is present, so existing call sites are unchanged.
+  const layouts = schema ? Option.getOrUndefined(FormLayoutAnnotation.get(schema)) : undefined;
+  const body =
+    layouts?.[layoutName] !== undefined && schema ? (
+      <FormLayout
+        schema={schema}
+        name={layoutName}
+        path={path}
+        readonly={readonly}
+        layout={layout}
+        projection={projection}
+        {...props}
+      />
+    ) : (
+      properties.map((property) => {
+        const name = property.name.toString();
+        return (
+          <FormFieldErrorBoundary key={name} path={[...(path ?? []), name]}>
+            <FormField
+              type={property.type}
+              name={name}
+              path={[...(path ?? []), name]}
+              readonly={readonly}
+              layout={layout}
+              projection={projection}
+              {...props}
+            />
+          </FormFieldErrorBoundary>
+        );
+      })
+    );
+
+  const showBody = !(collapsible && collapsed);
+  const content = (
+    <>
+      {layout !== 'inline' && label && (
+        <FormFieldLabel
+          asChild
+          classNames='pl-2'
+          label={label}
+          path={SchemaEx.createJsonPath(path ?? [])}
+          button={
+            collapsible && (
+              <IconButton
+                classNames='px-1 mr-0.5'
+                variant='ghost'
+                density='xs'
+                iconOnly
+                icon='ph--caret-right--regular'
+                iconClassNames={mx('transition-transform', !collapsed && 'rotate-90')}
+                label={t(collapsed ? 'expand-fields.label' : 'collapse-fields.label')}
+              />
+            )
+          }
+          onClick={() => setCollapsed((value) => !value)}
+        />
+      )}
+      {showBody && (collapsible ? <div className='px-2 pb-2'>{body}</div> : body)}
+    </>
+  );
+
+  // Nested field sets render inside an indented, bordered container with a collapse toggle.
+  if (collapsible) {
+    return <div className='border border-subdued-separator rounded-sm mt-2'>{content}</div>;
+  }
+
+  return content;
+};
+
+FormFieldSet.displayName = FORM_FIELDSET_NAME;
+
+type UseFormFieldSetPropertiesParams = Pick<FormFieldSetProps<any>, 'schema' | 'exclude' | 'projection' | 'sort'> & {
+  values: AnyProperties | undefined;
+  sort?: string[];
+};
+
+/**
+ * Resolves ordered schema properties for a field set (projection order, exclude, or sort).
+ */
+const useFormFieldSetProperties = ({
+  schema,
+  exclude,
+  projection,
+  values,
+  sort,
+}: UseFormFieldSetPropertiesParams): SchemaEx.SchemaProperty[] => {
+  // TODO(burdon): Updates on every value change.
+  //  Remove values dep if can remove from getSchemaProperties.
+  return useMemo(() => {
+    if (!schema) {
+      return [];
+    }
+
+    // TODO(wittjosiah): Reconcile FormInputAnnotation with projection hidden properties & exclude function.
+    const schemaProps = getRootFormProperties(schema.ast, values);
+    const filteredProps = exclude ? exclude(schemaProps) : schemaProps;
+
+    // Use projection-based field management when view and projection are available.
+    if (projection) {
+      const fieldProjections = projection.getFieldProjections();
+      const hiddenProperties = new Set(projection.getHiddenProperties());
+
+      // Filter properties to only include visible ones and order by projection.
+      const visibleProps = filteredProps.filter((prop) => !hiddenProperties.has(prop.name.toString()));
+      const orderedProps: SchemaEx.SchemaProperty[] = [];
+
+      // Add properties in projection field order.
+      for (const fieldProjection of fieldProjections) {
+        const fieldPath = String(fieldProjection.field.path);
+        const prop = visibleProps.find((prop) => prop.name === fieldPath);
+        if (prop) {
+          orderedProps.push(prop);
+        }
+      }
+
+      // Add any remaining properties not in projection.
+      const projectionPaths = new Set(fieldProjections.map((projection) => String(projection.field.path)));
+      const remainingProps = visibleProps.filter((prop) => !projectionPaths.has(prop.name.toString()));
+      orderedProps.push(...remainingProps);
+      return orderedProps;
+    }
+
+    // Fallback to legacy filter/sort behavior.
+    return sort
+      ? [...filteredProps].sort(({ name: a }, { name: b }) => sort.indexOf(a.toString()) - sort.indexOf(b.toString()))
+      : filteredProps;
+  }, [schema, values, exclude, sort, projection]);
+};

package/src/components/Form/FormTooltipsContext.ts

@@ -0,0 +1,25 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { createContext, useContext } from 'react';
+
+/**
+ * A standalone context for the `tooltips` flag (Form.Root's only label
+ * decoration today: a JSON-path hover tooltip rendered by
+ * `FormFieldLabel`).
+ *
+ * Lives in its own module so that `FormFieldComponent.tsx` -- imported at
+ * the top of `Form.tsx` -- can read the flag without re-importing from
+ * `Form.tsx`. That round-trip used to create a circular module-eval
+ * dependency that intermittently hit a TDZ ("Cannot access 'FormFieldLabel'
+ * before initialization") in browser-mode storybook tests.
+ *
+ * Defaults to `true` both when `Form.Root` doesn't pass an explicit value
+ * AND when there is no enclosing `Form.Root` (e.g. `FormFieldWrapper`
+ * stories that render an input without a Form provider).
+ */
+export const FormTooltipsContext = createContext<boolean>(true);
+
+/** Returns whether the enclosing `Form.Root` has field tooltips enabled. */
+export const useFormTooltips = (): boolean => useContext(FormTooltipsContext);

package/src/components/Form/Layout/FormLayout.stories.test.tsx

@@ -0,0 +1,51 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { composeStories } from '@storybook/react';
+import { act, cleanup, screen, within } from '@testing-library/react';
+import { afterEach, describe, expect, test } from 'vitest';
+
+import * as stories from './FormLayout.stories';
+
+const { NestedLabel, NestedLabelStatic } = composeStories(stories);
+
+describe('FormLayout — nested fields', () => {
+  afterEach(async () => {
+    // Flush pending React scheduler work before teardown to prevent
+    // "window is not defined" errors from setImmediate callbacks firing after happy-dom cleanup.
+    await act(async () => {});
+    cleanup();
+  });
+
+  test('renders nested struct labels and dotted sub-fields', { timeout: 30_000 }, async () => {
+    await NestedLabel.run();
+
+    // `<field name="origin"/>` / `<field name="destination"/>` auto-convert to the
+    // place's `LabelAnnotation` label (the `name` field), rendered as read-only text.
+    // `findByText` retries while the async client provider initializes.
+    expect(await screen.findByText('John F. Kennedy Intl')).toBeInTheDocument();
+    expect(await screen.findByText('Charles de Gaulle')).toBeInTheDocument();
+
+    // `<field name="origin.code"/>` / `<field name="destination.code"/>` drill into the
+    // leaf sub-field, rendered as editable inputs holding the code.
+    expect(await screen.findByDisplayValue('JFK')).toBeInTheDocument();
+    expect(await screen.findByDisplayValue('CDG')).toBeInTheDocument();
+  });
+
+  test('static layout formats dates and renders labels as read-only text', { timeout: 30_000 }, async () => {
+    await NestedLabelStatic.run();
+
+    // Scope assertions to the form: the debug panel echoes the raw values JSON.
+    const form = await screen.findByRole('form');
+
+    // The depart date renders human-readable (contains the year) rather than the raw ISO
+    // string. Match `2026` and assert no ISO time fragment leaks through — timezone-robust.
+    expect(within(form).getByText(/2026/)).toBeInTheDocument();
+    expect(within(form).queryByText(/T\d\d:\d\d/)).toBeNull();
+
+    // Nested struct labels and dotted sub-fields render as static text (not inputs).
+    expect(within(form).getByText('John F. Kennedy Intl')).toBeInTheDocument();
+    expect(within(form).getByText('JFK')).toBeInTheDocument();
+  });
+});