@dxos/react-ui-form 0.9.1-main.c7dcc2e112 → 0.10.0

package/src/components/Form/FormField/FormFieldWrapper.tsx

@@ -1,179 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { format as formatDate } from 'date-fns';
-import React, { Component, type PropsWithChildren, type ReactNode } from 'react';
-
-import { Format } from '@dxos/echo';
-import { inputTextLabel, Icon, Input, ThemedClassName, Tooltip } from '@dxos/react-ui';
-import { mx } from '@dxos/ui-theme';
-
-import { type FormFieldRendererProps } from '#types';
-
-//
-// FormFieldLabel
-//
-
-export type FormFieldLabelProps = ThemedClassName<
-  {
-    /** Render a plain `<span>` instead of an input-associated `Input.Label`, for labels used outside an `Input.Root` (e.g. section/group headers). */
-    standalone?: boolean;
-    error?: string;
-    /**
-     * JSON path of the field this label describes (e.g. `runtime.client.storage.persistent`).
-     * Field metadata; accepted by callers but not currently rendered.
-     */
-    path?: string;
-    /**
-     * Trailing button rendered at the end of the label row (third grid column).
-     * Used by nested-object field sets to surface a collapse toggle.
-     */
-    button?: ReactNode;
-    onClick?: () => void;
-  } & Pick<FormFieldRendererProps, 'label' | 'readonly'>
->;
-
-export const FormFieldLabel = ({
-  classNames,
-  label,
-  error,
-  readonly,
-  standalone,
-  button,
-  onClick,
-}: FormFieldLabelProps) => {
-  const Label = readonly || standalone ? 'span' : Input.Label;
-  const labelNode = <Label className={mx(inputTextLabel, 'text-sm')}>{label}</Label>;
-
-  return (
-    <div
-      className={mx('grid grid-cols-[1fr_auto_auto] items-center select-none', onClick && 'cursor-pointer', classNames)}
-      onClick={onClick}
-    >
-      {labelNode}
-      {error ? (
-        <Tooltip.Trigger asChild content={error} side='bottom'>
-          <Icon icon='ph--warning--regular' size={4} classNames='text-error-text' />
-        </Tooltip.Trigger>
-      ) : (
-        <span />
-      )}
-      {button}
-    </div>
-  );
-};
-
-FormFieldLabel.displayName = 'Form.FieldLabel';
-
-//
-// FormFieldWrapper
-//
-
-/**
- * Formats a value for `static` (read-only, plain-DOM) presentation based on its
- * type `format`. Dates/times are rendered human-readable; everything else falls
- * back to `String(value)`.
- */
-const formatStaticValue = (value: unknown, format?: Format.TypeFormat): string => {
-  if (value == null) {
-    return '';
-  }
-
-  switch (format) {
-    case Format.TypeFormat.DateTime:
-    case Format.TypeFormat.Date:
-    case Format.TypeFormat.Time: {
-      const date = new Date(value as string);
-      if (Number.isNaN(date.getTime())) {
-        return String(value);
-      }
-      const pattern = format === Format.TypeFormat.DateTime ? 'PPp' : format === Format.TypeFormat.Date ? 'PP' : 'p';
-      return formatDate(date, pattern);
-    }
-    default:
-      return String(value);
-  }
-};
-
-export type FormFieldWrapperProps<T = any> = Pick<
-  FormFieldRendererProps,
-  'readonly' | 'label' | 'layout' | 'getStatus' | 'getValue' | 'jsonPath' | 'format'
-> & {
-  children?: (props: { value: T }) => ReactNode;
-};
-
-export const FormFieldWrapper = <T,>(props: FormFieldWrapperProps<T>) => {
-  const { children, readonly, layout, label, jsonPath, format, getStatus, getValue } = props;
-  const { status, error } = getStatus();
-
-  const value = getValue();
-  if (layout === 'static' && value == null) {
-    return null;
-  }
-
-  const str = formatStaticValue(value, format);
-
-  return (
-    <div className='contents'>
-      <Input.Root validationValence={status}>
-        {layout !== 'inline' && <FormFieldLabel error={error} readonly={readonly} label={label} path={jsonPath} />}
-        {layout === 'static' ? (
-          <p className='truncate min-w-0' title={str}>
-            {str}
-          </p>
-        ) : children ? (
-          children({ value })
-        ) : null}
-        {layout === 'full' && error && (
-          <Input.DescriptionAndValidation>
-            <Input.Validation>{error}</Input.Validation>
-          </Input.DescriptionAndValidation>
-        )}
-      </Input.Root>
-    </div>
-  );
-};
-
-//
-// FormFieldErrorBoundary
-//
-
-type FormFieldErrorState = {
-  error: Error | undefined;
-};
-
-type FormFieldErrorBoundaryProps = PropsWithChildren<{
-  path?: (string | number)[];
-}>;
-
-export class FormFieldErrorBoundary extends Component<FormFieldErrorBoundaryProps, FormFieldErrorState> {
-  static getDerivedStateFromError(error: Error): { error: Error } {
-    return { error };
-  }
-
-  override state = { error: undefined };
-
-  override componentDidUpdate(prevProps: FormFieldErrorBoundaryProps) {
-    if (prevProps.path !== this.props.path) {
-      this.resetError();
-    }
-  }
-
-  override render() {
-    if (this.state.error) {
-      return (
-        <div className='flex gap-2 border border-error-border font-mono text-sm'>
-          <span className='bg-error-bg text-base-fg px-1 font-thin'>ERROR</span>
-          {String(this.props.path?.join('.'))}
-        </div>
-      );
-    }
-
-    return this.props.children;
-  }
-
-  private resetError() {
-    this.setState({ error: undefined });
-  }
-}

package/src/components/Settings/AUDIT.md

@@ -1,51 +0,0 @@
-# Plugin Settings Audit
-
-Tracks which plugin settings panels use schema-driven `Settings.FieldSet` and which still hand-roll their controls.
-
-The target shape for a plugin settings panel is:
-
-```tsx
-<SettingsForm.Viewport>
-  <SettingsForm.Section title={t('settings.title', { ns: meta.id })}>
-    <SettingsForm.FieldSet
-      readonly={!onSettingsChange}
-      schema={Settings.Settings}
-      values={settings}
-      onValuesChanged={(values) => onSettingsChange?.(() => values)}
-    />
-  </SettingsForm.Section>
-</SettingsForm.Viewport>
-```
-
-Field labels and descriptions come from `.annotations({ title, description })` on each schema field. Use `fieldMap` for runtime-driven option lists (model pickers, etc.). Use the `visible` callback to gate fields on environment or sibling values.
-
-## FieldSet adopters
-
-| Plugin                 | Notes                                                                                                    |
-| ---------------------- | -------------------------------------------------------------------------------------------------------- |
-| `plugin-assistant`     | Nested `modelDefaults` struct; `fieldMap` provides per-provider model selectors via `createSelectField`. |
-| `plugin-crx`           | Two booleans.                                                                                            |
-| `plugin-deck`          | Five booleans; `enableNativeRedirect` hidden via `visible` when `isSocket`.                              |
-| `plugin-inbox`         | Single boolean.                                                                                          |
-| `plugin-markdown`      | Original reference adopter. `snippets` text field gated via `visible`/`fieldMap`.                        |
-| `plugin-meeting`       | Single boolean.                                                                                          |
-| `plugin-observability` | Boolean; info `Message.Root` banner kept above `FieldSet`.                                               |
-| `plugin-presenter`     | Single boolean.                                                                                          |
-| `plugin-sample`        | Single boolean.                                                                                          |
-| `plugin-script`        | Mixed: auth `Button` retained as a manual `SettingsForm.Item`; `editorInputMode` rendered by `FieldSet`. |
-| `plugin-sketch`        | Boolean + `gridType` literal union (rendered as a Select — was previously a Switch).                     |
-
-## Skipped
-
-| Plugin             | Reason                                                                                                                                                               |
-| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plugin-debug`     | Action buttons (download diagnostics, download logs, repair), `Toast`, and a storage-adapter selector wired to `client.config` rather than the plugin settings atom. |
-| `plugin-space`     | Renders a list of spaces with per-space "open settings" buttons — not bound to any schema field.                                                                     |
-| `plugin-spacetime` | Section is currently empty; nothing to render.                                                                                                                       |
-| `plugin-thread`    | Settings schema is `Schema.Struct({})` — nothing to render.                                                                                                          |
-
-## When to extend `SettingsFieldSet` vs. add a custom field
-
-- **Extend `SettingsFieldSet`** when the rendering rule applies generally to a schema construct (e.g. nested structs recursing into sibling fields, literal unions becoming Selects). Keep auto-detection in `detectFieldType`.
-- **Use `fieldMap`** when the schema can't fully describe the rendering — runtime-driven option lists, custom inputs, or override of the auto-rendered control. Use the typed form `SettingsFieldMap<T>` (or `satisfies SettingsFieldMap<Settings>`) so the entries are checked against the values shape.
-- **Drop back to manual `SettingsForm.Item`** when the panel needs UI that isn't bound to a settings field at all (action buttons, info banners, lists of external entities). These coexist as siblings of `FieldSet` inside the same `Section`.

package/src/components/Settings/Settings.stories.tsx

@@ -1,104 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import * as Schema from 'effect/Schema';
-import React from 'react';
-
-import { random } from '@dxos/random';
-import { Button, Input } from '@dxos/react-ui';
-import { withLayout, withTheme } from '@dxos/react-ui/testing';
-
-import { translations } from '#translations';
-
-import { Settings } from './Settings';
-
-random.seed(132);
-
-const DefaultStory = () => {
-  return (
-    <Settings.Viewport>
-      <Settings.Section title='Settings' description={random.lorem.paragraphs(1)}>
-        <Settings.Item title={random.lorem.sentence(2)} description={random.lorem.paragraphs(1)}>
-          <Input.TextInput placeholder='Input' />
-        </Settings.Item>
-        <Settings.Item title={random.lorem.sentence(2)} description={random.lorem.paragraphs(2)}>
-          <Input.Switch />
-        </Settings.Item>
-        <Settings.Item title={random.lorem.sentence(3)} description={random.lorem.paragraphs(2)}>
-          <Button>Test</Button>
-        </Settings.Item>
-      </Settings.Section>
-      <Settings.Section title='Panel Example'>
-        <Settings.Panel>
-          <h3 className='text-lg mb-2'>Members</h3>
-          <p className='text-description'>Content inside a panel.</p>
-        </Settings.Panel>
-      </Settings.Section>
-    </Settings.Viewport>
-  );
-};
-
-const meta = {
-  title: 'ui/react-ui-form/Settings',
-  render: DefaultStory,
-  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
-  parameters: {
-    layout: 'fullscreen',
-    translations,
-  },
-} satisfies Meta;
-
-export default meta;
-
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {};
-
-const TestViewModes = ['preview', 'readonly', 'source'] as const;
-const TestViewMode = Schema.Union(...TestViewModes.map((mode) => Schema.Literal(mode)));
-
-const TestSettings = Schema.mutable(
-  Schema.Struct({
-    viewMode: TestViewMode.annotations({ title: 'View mode', description: 'Default document view mode.' }),
-    toolbar: Schema.optional(
-      Schema.Boolean.annotations({ title: 'Show toolbar', description: 'Display formatting toolbar.' }),
-    ),
-    fontSize: Schema.optional(
-      Schema.Number.annotations({ title: 'Font size', description: 'Editor font size in pixels.' }),
-    ),
-    placeholder: Schema.optional(
-      Schema.String.annotations({ title: 'Placeholder', description: 'Default placeholder text.' }),
-    ),
-    debug: Schema.optional(Schema.Boolean.annotations({ title: 'Debug mode', description: 'Enable debug features.' })),
-  }),
-);
-
-type TestSettings = Schema.Schema.Type<typeof TestSettings>;
-
-const FieldSetStory = () => {
-  const [values, setValues] = React.useState<TestSettings>({
-    viewMode: 'preview',
-    toolbar: true,
-    fontSize: 14,
-    debug: false,
-  });
-
-  return (
-    <Settings.Viewport>
-      <Settings.Section title='Plugin Settings (Auto-generated)'>
-        <Settings.FieldSet
-          schema={TestSettings}
-          values={values}
-          onValuesChanged={setValues}
-          visible={(path, values) => path !== 'placeholder' || !!values.debug}
-        />
-      </Settings.Section>
-    </Settings.Viewport>
-  );
-};
-
-export const FieldSet: Story = {
-  render: FieldSetStory,
-};

package/src/components/Settings/Settings.tsx

@@ -1,81 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import React, { type PropsWithChildren } from 'react';
-
-import { type Label, ScrollArea, type ThemedClassName, toLocalizedString, useTranslation } from '@dxos/react-ui';
-import { composable, composableProps } from '@dxos/react-ui';
-import { mx } from '@dxos/ui-theme';
-
-import { translationKey } from '#translations';
-
-import { SettingsFieldSet } from './SettingsFieldSet';
-import { SettingsItem, SettingsPanel } from './SettingsItem';
-
-const SETTINGS_ROOT_NAME = 'Settings.Root';
-const SETTINGS_VIEWPORT_NAME = 'Settings.Viewport';
-const SETTINGS_SECTION_NAME = 'Settings.Section';
-
-//
-// Root (headless — no styling, no scroll).
-//
-
-type SettingsRootProps = ThemedClassName<PropsWithChildren>;
-
-const SettingsRoot = ({ children, classNames }: SettingsRootProps) => {
-  return <div className={mx('flex flex-col gap-2', classNames)}>{children}</div>;
-};
-
-SettingsRoot.displayName = SETTINGS_ROOT_NAME;
-
-//
-// Viewport (scroll area + padding + document layout).
-//
-
-const SettingsViewport = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
-  return (
-    <ScrollArea.Root {...composableProps(props)} orientation='vertical' centered thin ref={forwardedRef}>
-      <ScrollArea.Viewport classNames='px-4 pointer-coarse:px-2'>
-        <div className='dx-document flex flex-col gap-2 py-4'>{children}</div>
-      </ScrollArea.Viewport>
-    </ScrollArea.Root>
-  );
-});
-
-SettingsViewport.displayName = SETTINGS_VIEWPORT_NAME;
-
-//
-// Section (title + optional description + children with spacing).
-//
-
-type SettingsSectionProps = PropsWithChildren<{
-  title: Label;
-  description?: Label;
-}>;
-
-const SettingsSection = ({ title, description, children }: SettingsSectionProps) => {
-  const { t } = useTranslation(translationKey);
-  return (
-    <>
-      <h2 className='px-trim-md mt-trim-md text-xl'>{toLocalizedString(title, t)}</h2>
-      {description && <p className='px-trim-md text-description'>{toLocalizedString(description, t)}</p>}
-      <div className='w-full pt-trim-md space-y-trim-md'>{children}</div>
-    </>
-  );
-};
-
-SettingsSection.displayName = SETTINGS_SECTION_NAME;
-
-//
-// Settings
-//
-
-export const Settings = {
-  Root: SettingsRoot,
-  Viewport: SettingsViewport,
-  Section: SettingsSection,
-  Panel: SettingsPanel,
-  Item: SettingsItem,
-  FieldSet: SettingsFieldSet,
-};

package/src/components/Settings/SettingsFieldSet.tsx

@@ -1,257 +0,0 @@
-//
-// Copyright 2025 DXOS.org
-//
-
-import * as SchemaAST from 'effect/SchemaAST';
-import * as String from 'effect/String';
-import React, { useCallback, useMemo } from 'react';
-
-import { SchemaEx } from '@dxos/effect';
-import { Input, Select } from '@dxos/react-ui';
-
-import { getFormProperties, type SelectOption, detectFieldType, getSelectOptionsFromAst } from '../../util';
-import { SettingsItem } from './SettingsItem';
-
-//
-// Types
-//
-
-/**
- * Props for a custom field renderer.
- * The renderer provides the control only; SettingsItem wrapper is handled by FieldSet.
- */
-export type SettingsFieldProps<T = any> = {
-  value: T;
-  onChange: (value: T) => void;
-  readonly?: boolean;
-};
-
-/**
- * Map of property names to either a custom field renderer or a nested field map for struct fields.
- * When a value type `T` is provided, the map shape is checked against the schema's value type.
- */
-export type SettingsFieldMap<T extends Record<string, any> = Record<string, any>> = {
-  [K in keyof T]?: NonNullable<T[K]> extends Record<string, any>
-    ? SettingsFieldMap<NonNullable<T[K]>>
-    : React.FC<SettingsFieldProps<T[K]>>;
-};
-
-export type SettingsFieldSetProps<T extends Record<string, any> = Record<string, any>> = {
-  /** Effect Schema for the settings object. */
-  schema: { ast: SchemaAST.AST };
-
-  /** Current settings values. */
-  values: T;
-
-  /** Callback when any value changes. Receives a new complete object. */
-  onValuesChanged?: (values: T) => void;
-
-  /** When true, all controls are disabled. */
-  readonly?: boolean;
-
-  /** Map of property names to custom field renderers. Nested objects map to struct sub-fields. */
-  fieldMap?: SettingsFieldMap<T>;
-
-  /** Control field visibility. Receives the dotted path (e.g. `'modelDefaults.edge'`) at every level. */
-  visible?: (path: string, values: T) => boolean;
-
-  /** Override the order of fields. Fields not listed are appended in schema order. Applied per scope. */
-  sort?: string[];
-
-  /** Internal: dot-path prefix used by recursive struct rendering. */
-  pathPrefix?: string;
-};
-
-//
-// Component
-//
-
-export const SettingsFieldSet = <T extends Record<string, any>>({
-  schema,
-  values,
-  onValuesChanged,
-  readonly,
-  fieldMap,
-  visible,
-  sort,
-  pathPrefix = '',
-}: SettingsFieldSetProps<T>) => {
-  const properties = useMemo(() => {
-    const props = getFormProperties(schema.ast);
-    if (!sort) {
-      return props;
-    }
-    const rank = (name: string) => {
-      const idx = sort.indexOf(name);
-      return idx === -1 ? Number.POSITIVE_INFINITY : idx;
-    };
-    return [...props].sort(({ name: a }, { name: b }) => rank(a.toString()) - rank(b.toString()));
-  }, [schema, sort]);
-
-  const handleChange = useCallback(
-    (name: string, value: unknown) => {
-      onValuesChanged?.({ ...values, [name]: value } as T);
-    },
-    [values, onValuesChanged],
-  );
-
-  return (
-    <>
-      {properties.map((property) => {
-        const name = property.name.toString();
-        const path = pathPrefix ? `${pathPrefix}.${name}` : name;
-        if (visible && !visible(path, values)) {
-          return null;
-        }
-
-        const entry = fieldMap?.[name as keyof typeof fieldMap] as
-          | React.FC<SettingsFieldProps>
-          | SettingsFieldMap
-          | undefined;
-        return (
-          <SettingsFieldItem
-            key={name}
-            path={path}
-            property={property}
-            value={values[name]}
-            onChange={(value) => handleChange(name, value)}
-            readonly={readonly}
-            customField={typeof entry === 'function' ? entry : undefined}
-            nestedFieldMap={typeof entry === 'object' ? entry : undefined}
-            visible={visible as (path: string, values: any) => boolean}
-            sort={sort}
-          />
-        );
-      })}
-    </>
-  );
-};
-
-SettingsFieldSet.displayName = 'Settings.FieldSet';
-
-//
-// Internal: render a single settings field.
-//
-
-type SettingsFieldItemProps = {
-  property: SchemaEx.SchemaProperty;
-  path: string;
-  value: any;
-  onChange: (value: any) => void;
-  readonly?: boolean;
-  customField?: React.FC<SettingsFieldProps>;
-  nestedFieldMap?: SettingsFieldMap;
-  visible?: (path: string, values: any) => boolean;
-  sort?: string[];
-};
-
-const SettingsFieldItem = ({
-  property,
-  path,
-  value,
-  onChange,
-  readonly,
-  customField,
-  nestedFieldMap,
-  visible,
-  sort,
-}: SettingsFieldItemProps) => {
-  const { type } = property;
-  const name = property.name.toString();
-  const title = SchemaEx.getAnnotation<string>(SchemaAST.TitleAnnotationId)(type) ?? String.capitalize(name);
-  const description = SchemaEx.getAnnotation<string>(SchemaAST.DescriptionAnnotationId)(type);
-
-  // Custom field renderer.
-  if (customField) {
-    const CustomField = customField;
-    return (
-      <SettingsItem title={title} description={description}>
-        <CustomField value={value} onChange={onChange} readonly={readonly} />
-      </SettingsItem>
-    );
-  }
-
-  const fieldType = detectFieldType(type);
-
-  switch (fieldType) {
-    case 'struct':
-      return (
-        <SettingsFieldSet
-          schema={{ ast: type }}
-          values={value ?? {}}
-          onValuesChanged={onChange}
-          readonly={readonly}
-          fieldMap={nestedFieldMap}
-          visible={visible}
-          sort={sort}
-          pathPrefix={path}
-        />
-      );
-
-    case 'boolean':
-      return (
-        <SettingsItem title={title} description={description}>
-          <Input.Switch disabled={readonly} checked={!!value} onCheckedChange={(checked) => onChange(!!checked)} />
-        </SettingsItem>
-      );
-
-    case 'select': {
-      const options = getSelectOptionsFromAst(type) ?? [];
-      return (
-        <SettingsItem title={title} description={description}>
-          <Select.Root
-            disabled={readonly}
-            value={value == null ? '' : globalThis.String(value)}
-            onValueChange={(selected) => {
-              const matched = options.find((option) => globalThis.String(option.value) === selected);
-              onChange(matched?.value ?? selected);
-            }}
-          >
-            <Select.TriggerButton disabled={readonly} />
-            <Select.Portal>
-              <Select.Content>
-                <Select.Viewport>
-                  {options.map((option: SelectOption) => (
-                    <Select.Option key={globalThis.String(option.value)} value={globalThis.String(option.value)}>
-                      {option.label ?? globalThis.String(option.value)}
-                    </Select.Option>
-                  ))}
-                </Select.Viewport>
-                <Select.Arrow />
-              </Select.Content>
-            </Select.Portal>
-          </Select.Root>
-        </SettingsItem>
-      );
-    }
-
-    case 'string':
-      return (
-        <SettingsItem title={title} description={description}>
-          <Input.TextInput disabled={readonly} value={value ?? ''} onChange={(event) => onChange(event.target.value)} />
-        </SettingsItem>
-      );
-
-    case 'number':
-      return (
-        <SettingsItem title={title} description={description}>
-          <Input.TextInput
-            disabled={readonly}
-            type='number'
-            value={value ?? ''}
-            onChange={(event) => {
-              if (event.target.value === '') {
-                onChange(undefined);
-                return;
-              }
-              const parsed = Number(event.target.value);
-              onChange(Number.isNaN(parsed) ? undefined : parsed);
-            }}
-          />
-        </SettingsItem>
-      );
-
-    default:
-      return null;
-  }
-};