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

package/src/util/field-type.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { SchemaEx } from '@dxos/effect';
+
+/**
+ * Detected field type for a schema property.
+ */
+export type SettingsFieldType = 'boolean' | 'string' | 'number' | 'select' | 'struct';
+
+export type SelectOption = {
+  value: string | number;
+  label?: string;
+};
+
+/**
+ * Detect the field type from an Effect Schema AST node.
+ */
+export const detectFieldType = (ast: SchemaAST.AST): SettingsFieldType | undefined => {
+  if (SchemaEx.isLiteralUnion(ast)) {
+    return 'select';
+  }
+  if (SchemaAST.isTypeLiteral(ast)) {
+    return 'struct';
+  }
+
+  switch (ast._tag) {
+    case 'BooleanKeyword':
+      return 'boolean';
+    case 'StringKeyword':
+      return 'string';
+    case 'NumberKeyword':
+      return 'number';
+  }
+
+  return undefined;
+};
+
+/**
+ * Extract select options from a literal union AST node.
+ * Reads title annotations from individual literals for labels.
+ */
+export const getSelectOptionsFromAst = (ast: SchemaAST.AST): SelectOption[] | undefined => {
+  if (!SchemaEx.isLiteralUnion(ast)) {
+    return undefined;
+  }
+
+  return (ast as SchemaAST.Union<SchemaAST.Literal>).types.flatMap((literalNode) => {
+    const value = literalNode.literal;
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      return [];
+    }
+    const title = SchemaEx.getAnnotation<string>(SchemaAST.TitleAnnotationId, false)(literalNode);
+    const label = title ?? (typeof value === 'string' ? value.charAt(0).toUpperCase() + value.slice(1) : String(value));
+    return [{ value, label }];
+  });
+};

package/src/util/field.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { FormatEnum, GeoLocation, TypeEnum } from '@dxos/echo-schema';
+import { Format, GeoLocation, TypeEnum } from '@dxos/echo/Format';
 import { type ValidationError } from '@dxos/schema';
 
 /**
@@ -13,7 +13,7 @@ import { type ValidationError } from '@dxos/schema';
  */
 export type ParseProps = {
   type?: TypeEnum;
-  format?: FormatEnum;
+  format?: Format.TypeFormat;
   value: any;
 };
 
@@ -57,31 +57,31 @@ export const parseValue = ({ type, format, value }: ParseProps) => {
   }
 
   switch (format) {
-    case FormatEnum.Boolean:
+    case Format.TypeFormat.Boolean:
       return parseScalar(TypeEnum.Boolean);
 
-    case FormatEnum.Number:
-    case FormatEnum.Percent:
-    case FormatEnum.Currency:
+    case Format.TypeFormat.Number:
+    case Format.TypeFormat.Percent:
+    case Format.TypeFormat.Currency:
       return parseScalar(TypeEnum.Number);
 
-    case FormatEnum.String:
-    case FormatEnum.Markdown: {
+    case Format.TypeFormat.String:
+    case Format.TypeFormat.Markdown: {
       return parseScalar(TypeEnum.String);
     }
 
-    case FormatEnum.Ref:
-      throw new Error(`unexpected format: ${FormatEnum.Ref}`);
+    case Format.TypeFormat.Ref:
+      throw new Error(`unexpected format: ${Format.TypeFormat.Ref}`);
 
-    case FormatEnum.DateTime:
-    case FormatEnum.Date:
-    case FormatEnum.Time:
-    case FormatEnum.Timestamp: {
+    case Format.TypeFormat.DateTime:
+    case Format.TypeFormat.Date:
+    case Format.TypeFormat.Time:
+    case Format.TypeFormat.Timestamp: {
       const date = new Date(value as string | number);
       return isNaN(date.getTime()) ? null : date;
     }
 
-    case FormatEnum.GeoPoint: {
+    case Format.TypeFormat.GeoPoint: {
       // Parse string in format "lat,long" to GeoPoint [longitude, latitude].
       if (typeof value === 'string') {
         // Only keep digits, decimal points, minus signs, and commas.
@@ -108,41 +108,31 @@ export const parseValue = ({ type, format, value }: ParseProps) => {
 // TODO(burdon): Type and format.
 export type CellClassesForFieldTypeProps = {
   type?: TypeEnum;
-  format?: FormatEnum;
+  format?: Format.TypeFormat;
 };
 
 export const cellClassesForFieldType = ({ type, format }: CellClassesForFieldTypeProps): string[] | undefined => {
-  if (!format) {
-    switch (type) {
-      case TypeEnum.Number:
-        return ['text-right', 'font-mono'];
-      case TypeEnum.Boolean:
-        return ['text-right', 'font-mono'];
-      case TypeEnum.String:
-        return undefined;
-      case TypeEnum.Ref:
-        return undefined;
-
-      default: {
-        return undefined;
-      }
-    }
-  }
-
-  switch (format) {
-    case FormatEnum.Markdown:
+  switch (format || type) {
+    case Format.TypeFormat.Markdown:
       return undefined;
-    case FormatEnum.Time:
-    case FormatEnum.Timestamp:
-    case FormatEnum.DateTime:
-    case FormatEnum.Date:
-    case FormatEnum.Duration:
+    case Format.TypeFormat.Time:
+    case Format.TypeFormat.Timestamp:
+    case Format.TypeFormat.DateTime:
+    case Format.TypeFormat.Date:
+    case Format.TypeFormat.Duration:
       return ['font-mono', 'text-right'];
-    case FormatEnum.Currency:
+    case Format.TypeFormat.Currency:
       return ['text-right'];
-    case FormatEnum.JSON:
-    case FormatEnum.DID:
+    case Format.TypeFormat.JSON:
+    case Format.TypeFormat.DID:
       return ['font-mono'];
+    case TypeEnum.Number:
+    case TypeEnum.Boolean:
+      return ['text-right', 'font-mono'];
+    case TypeEnum.String:
+      return undefined;
+    case TypeEnum.Ref:
+      return undefined;
     default:
       return undefined;
   }

package/src/util/formatting.ts

@@ -4,11 +4,11 @@
 
 import { format as formatDate } from 'date-fns/format';
 
-import { FormatEnum, GeoLocation, TypeEnum } from '@dxos/echo-schema';
+import { Format, GeoLocation, TypeEnum } from '@dxos/echo/Format';
 
 type ValueFormatProps = {
   type: TypeEnum;
-  format?: FormatEnum | undefined;
+  format?: Format.TypeFormat | undefined;
   value: any;
   locale?: string | undefined;
 };
@@ -41,20 +41,20 @@ export const formatForDisplay = ({ type, format, value, locale = undefined }: Va
   }
 
   switch (format) {
-    case FormatEnum.Boolean: {
+    case Format.TypeFormat.Boolean: {
       return formatScalar(TypeEnum.Boolean);
     }
-    case FormatEnum.Number: {
+    case Format.TypeFormat.Number: {
       return formatScalar(TypeEnum.Number);
     }
-    case FormatEnum.String:
-    case FormatEnum.Ref: {
+    case Format.TypeFormat.String:
+    case Format.TypeFormat.Ref: {
       return formatScalar(TypeEnum.String);
     }
-    case FormatEnum.Percent: {
+    case Format.TypeFormat.Percent: {
       return `${(value as number) * 100}%`;
     }
-    case FormatEnum.Currency: {
+    case Format.TypeFormat.Currency: {
       // TODO(burdon): Get from property annotation.
       return (value as number).toLocaleString(locale, {
         style: 'currency',
@@ -63,28 +63,28 @@ export const formatForDisplay = ({ type, format, value, locale = undefined }: Va
         maximumFractionDigits: 2,
       });
     }
-    case FormatEnum.Date: {
+    case Format.TypeFormat.Date: {
       try {
         return formatDate(new Date(value as number), 'yyyy-MM-dd');
       } catch (error) {
         return 'Invalid Date';
       }
     }
-    case FormatEnum.Time: {
+    case Format.TypeFormat.Time: {
       try {
         return formatDate(new Date(value as number), 'HH:mm:ss');
       } catch (error) {
         return 'Invalid Time';
       }
     }
-    case FormatEnum.DateTime: {
+    case Format.TypeFormat.DateTime: {
       try {
         return formatDate(new Date(value as number), 'yyyy-MM-dd HH:mm:ss');
       } catch (error) {
         return 'Invalid DateTime';
       }
     }
-    case FormatEnum.GeoPoint: {
+    case Format.TypeFormat.GeoPoint: {
       if (value === null || value === undefined) {
         return '';
       }
@@ -125,31 +125,31 @@ export const formatForEditing = ({ type, format, value, locale = undefined }: Va
   }
 
   switch (format) {
-    case FormatEnum.Boolean:
-    case FormatEnum.Number:
-    case FormatEnum.String:
-    case FormatEnum.Ref: {
+    case Format.TypeFormat.Boolean:
+    case Format.TypeFormat.Number:
+    case Format.TypeFormat.String:
+    case Format.TypeFormat.Ref: {
       return formatScalar(type);
     }
-    case FormatEnum.Percent: {
+    case Format.TypeFormat.Percent: {
       return String(value * 100);
     }
-    case FormatEnum.Currency: {
+    case Format.TypeFormat.Currency: {
       return String(value);
     }
-    case FormatEnum.DateTime: {
+    case Format.TypeFormat.DateTime: {
       const date = new Date(value as number);
       return date.toISOString();
     }
-    case FormatEnum.Date: {
+    case Format.TypeFormat.Date: {
       const date = new Date(value as number);
       return date.toISOString().split('T')[0];
     }
-    case FormatEnum.Time: {
+    case Format.TypeFormat.Time: {
       const date = new Date(value as number);
       return date.toISOString().split('T')[1].split('.')[0];
     }
-    case FormatEnum.GeoPoint: {
+    case Format.TypeFormat.GeoPoint: {
       // Handle null or undefined
       if (value === null || value === undefined) {
         return '';

package/src/util/index.ts

@@ -3,6 +3,7 @@
 //
 
 export * from './field';
+export * from './field-type';
 export * from './formatting';
+export * from './properties';
 export * from './refs';
-export * from './schema';

package/src/util/properties.test.ts

@@ -0,0 +1,153 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Schema from 'effect/Schema';
+import * as SchemaAST from 'effect/SchemaAST';
+import { describe, test } from 'vitest';
+
+import { DXN, Annotation, JsonSchema, Type } from '@dxos/echo';
+import { Format } from '@dxos/echo/Format';
+import { SchemaEx } from '@dxos/effect';
+
+import { getFormProperties, getRootFormProperties } from './properties';
+
+describe('getFormProperties', () => {
+  test('filters out keyword fields annotated FormInputAnnotation.set(false)', ({ expect }) => {
+    const TestSchema = Schema.Struct({
+      name: Schema.optional(Schema.String),
+      hidden: Schema.String.pipe(Annotation.FormInputAnnotation.set(false)),
+    }).pipe(Type.makeObject(DXN.make('org.dxos.test.keywordHidden', '0.1.0')));
+
+    const names = getFormProperties(Type.getSchema(TestSchema).ast).map((prop) => prop.name);
+    expect(names).toContain('name');
+    expect(names).not.toContain('hidden');
+  });
+
+  test('filters out struct fields annotated FormInputAnnotation.set(false)', ({ expect }) => {
+    // Regression: JsonSchema fields are a Schema.Struct; encodedBoundAST strips
+    // annotations from non-keyword inner types, which previously bypassed the
+    // form-input filter (e.g., Routine.input).
+    const TestSchema = Schema.Struct({
+      name: Schema.optional(Schema.String),
+      schema: JsonSchema.JsonSchema.pipe(Annotation.FormInputAnnotation.set(false)),
+    }).pipe(Type.makeObject(DXN.make('org.dxos.test.structHidden', '0.1.0')));
+
+    const names = getFormProperties(Type.getSchema(TestSchema).ast).map((prop) => prop.name);
+    expect(names).toContain('name');
+    expect(names).not.toContain('schema');
+  });
+
+  test('filters out array fields annotated FormInputAnnotation.set(false)', ({ expect }) => {
+    const TestSchema = Schema.Struct({
+      name: Schema.optional(Schema.String),
+      context: Schema.Array(Schema.Any).pipe(Annotation.FormInputAnnotation.set(false)),
+    }).pipe(Type.makeObject(DXN.make('org.dxos.test.arrayHidden', '0.1.0')));
+
+    const names = getFormProperties(Type.getSchema(TestSchema).ast).map((prop) => prop.name);
+    expect(names).toContain('name');
+    expect(names).not.toContain('context');
+  });
+
+  test('filters out optional fields annotated FormInputAnnotation.set(false)', ({ expect }) => {
+    // Regression: optional fields' `prop.type` is the union `T | undefined`; the
+    // annotation lives on the inner `T`. Without unwrapping, the filter would
+    // miss the annotation and the hidden field would render. Covers the
+    // conventional pattern `Schema.X.pipe(FormInputAnnotation.set(false), Schema.optional)`.
+    const TestSchema = Schema.Struct({
+      name: Schema.optional(Schema.String),
+      userId: Schema.String.pipe(Annotation.FormInputAnnotation.set(false), Schema.optional),
+    }).pipe(Type.makeObject(DXN.make('org.dxos.test.optionalHidden', '0.1.0')));
+
+    const names = getFormProperties(Type.getSchema(TestSchema).ast).map((prop) => prop.name);
+    expect(names).toContain('name');
+    expect(names).not.toContain('userId');
+  });
+
+  test('preserves a deeply-nested FormInputAnnotation through unions and arrays', ({ expect }) => {
+    // Regression: a hidden field nested below a discriminated union and arrays of structs (e.g.
+    // Segment.details(road).routes[].legs[].geometry). `encodedBoundAST` strips annotations from
+    // non-keyword inner types, so without keeping container types raw the annotation is lost by
+    // the time the form recurses to the leaf field. The transformation element (GeoPoint) is the
+    // trigger that forces the encode rebuild.
+    const Leg = Schema.Struct({
+      distance: Schema.Number,
+      geometry: Schema.Array(Format.GeoPoint).pipe(Annotation.FormInputAnnotation.set(false)),
+    });
+    const Route = Schema.Struct({ legs: Schema.Array(Leg) });
+    const TestSchema = Schema.Struct({
+      details: Schema.Union(
+        Schema.TaggedStruct('road', { routes: Schema.optional(Schema.Array(Route)) }),
+        Schema.TaggedStruct('other', { note: Schema.optional(Schema.String) }),
+      ),
+    }).pipe(Type.makeObject(DXN.make('org.dxos.test.nestedHidden', '0.1.0')));
+
+    // Drill as the form does: getFormProperties at each level, descending via the property type
+    // (array element / type literal) returned by the previous level.
+    const findTypeLiteralWith = (ast: SchemaAST.AST, prop: string) =>
+      SchemaEx.findNode(
+        ast,
+        (node) => SchemaAST.isTypeLiteral(node) && SchemaAST.getPropertySignatures(node).some((p) => p.name === prop),
+      )!;
+    const propType = (ast: SchemaAST.AST, name: string) => getFormProperties(ast).find((p) => p.name === name)!.type;
+
+    const detailsType = propType(Type.getSchema(TestSchema).ast, 'details');
+    const roadTypeLiteral = findTypeLiteralWith(detailsType, 'routes');
+    const routeTypeLiteral = SchemaEx.findNode(
+      SchemaEx.getArrayElementType(propType(roadTypeLiteral, 'routes'))!,
+      SchemaAST.isTypeLiteral,
+    )!;
+    const legTypeLiteral = SchemaEx.findNode(
+      SchemaEx.getArrayElementType(propType(routeTypeLiteral, 'legs'))!,
+      SchemaAST.isTypeLiteral,
+    )!;
+
+    const names = getFormProperties(legTypeLiteral).map((prop) => prop.name);
+    expect(names).toContain('distance');
+    expect(names).not.toContain('geometry');
+  });
+
+  test('preserves annotation when chained with .annotations()', ({ expect }) => {
+    // Regression: `.pipe(FormInputAnnotation.set(false)).annotations({...})` must
+    // not lose the form-input annotation.
+    const TestSchema = Schema.Struct({
+      name: Schema.optional(Schema.String),
+      hidden: JsonSchema.JsonSchema.pipe(Annotation.FormInputAnnotation.set(false)).annotations({
+        description: 'Hidden field',
+      }),
+    }).pipe(Type.makeObject(DXN.make('org.dxos.test.chainedHidden', '0.1.0')));
+
+    const names = getFormProperties(Type.getSchema(TestSchema).ast).map((prop) => prop.name);
+    expect(names).toContain('name');
+    expect(names).not.toContain('hidden');
+  });
+});
+
+describe('getRootFormProperties', () => {
+  const Timer = Schema.Struct({ kind: Schema.Literal('timer'), cron: Schema.String });
+  const Feed = Schema.Struct({ kind: Schema.Literal('feed'), feed: Schema.String });
+  const Union = Schema.Union(Timer, Feed);
+
+  test('renders a non-union root unchanged', ({ expect }) => {
+    const ast = Schema.Struct({ a: Schema.String, b: Schema.Number }).ast;
+    expect(getRootFormProperties(ast, {}).map((prop) => prop.name)).toEqual(['a', 'b']);
+  });
+
+  test('expands a top-level discriminated union to the active member by discriminator value', ({ expect }) => {
+    // `getPropertySignatures` on the union alone yields only the common `kind`; the active member's
+    // variant field (`cron`/`feed`) must also render.
+    expect(getRootFormProperties(Union.ast, { kind: 'timer' }).map((prop) => prop.name)).toEqual(['kind', 'cron']);
+    expect(getRootFormProperties(Union.ast, { kind: 'feed' }).map((prop) => prop.name)).toEqual(['kind', 'feed']);
+  });
+
+  test('keeps the discriminator field switchable (union-wide literals, not the matched single literal)', ({
+    expect,
+  }) => {
+    const kind = getRootFormProperties(Union.ast, { kind: 'feed' }).find((prop) => prop.name === 'kind');
+    expect(kind && SchemaEx.getLiteralValues(Schema.make(kind.type))).toEqual(['timer', 'feed']);
+  });
+
+  test('falls back to the discriminator alone when no value selects a member', ({ expect }) => {
+    expect(getRootFormProperties(Union.ast, {}).map((prop) => prop.name)).toEqual(['kind']);
+  });
+});

package/src/util/properties.ts

@@ -0,0 +1,100 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import * as Option from 'effect/Option';
+import * as SchemaAST from 'effect/SchemaAST';
+
+import { Annotation } from '@dxos/echo';
+import { type AnyProperties } from '@dxos/echo/internal';
+import { SchemaEx } from '@dxos/effect';
+
+/** The property's type with an optional `T | undefined` union unwrapped to its inner `T`. */
+const unwrapOptional = (prop: SchemaAST.PropertySignature): SchemaAST.AST => {
+  if (!prop.isOptional || !SchemaAST.isUnion(prop.type)) {
+    return prop.type;
+  }
+  // Drop the `undefined` member, preserving the remaining union (don't collapse `A | B | undefined` to `A`).
+  const defined = prop.type.types.filter((type) => type._tag !== 'UndefinedKeyword');
+  if (defined.length === 0) {
+    return prop.type;
+  }
+  return defined.length === 1 ? defined[0] : SchemaAST.Union.make(defined, prop.type.annotations);
+};
+
+/**
+ * Resolve the properties to render for a field set's *root* schema, given the current form values.
+ *
+ * A top-level discriminated union is rendered flat: the fields of the member selected by the current
+ * discriminator value, with the discriminator field keeping the union-wide set of literals so it stays
+ * switchable. (`SchemaAST.getPropertySignatures` on a union returns only the common discriminator, so a
+ * union root would otherwise render just that one field.) Non-union roots are unchanged. Nested unions are
+ * unaffected — those are expanded per-field by `FormField`, which passes a single-member type literal here.
+ */
+export const getRootFormProperties = (
+  ast: SchemaAST.AST,
+  values: AnyProperties | undefined,
+): SchemaEx.SchemaProperty[] => {
+  if (!SchemaEx.isDiscriminatedUnion(ast)) {
+    return getFormProperties(ast);
+  }
+
+  const activeType = SchemaEx.getDiscriminatedType(ast, values ?? {});
+  if (!activeType) {
+    return getFormProperties(ast);
+  }
+  const activeProps = getFormProperties(activeType);
+
+  const discriminators = new Set((SchemaEx.getDiscriminatingProps(ast) ?? []).map((name) => name.toString()));
+  if (discriminators.size === 0) {
+    return activeProps;
+  }
+  // The matched member types its discriminator as a single literal; swap in the union-wide literal so the
+  // field renders as a full select rather than a fixed value.
+  const fullType = SchemaEx.getDiscriminatedType(ast, {});
+  const fullDiscriminatorProps = fullType ? getFormProperties(fullType) : activeProps;
+  return activeProps.map((prop) =>
+    discriminators.has(prop.name.toString())
+      ? (fullDiscriminatorProps.find((candidate) => candidate.name === prop.name) ?? prop)
+      : prop,
+  );
+};
+
+/**
+ * Get the property types of an AST and filter out properties that are not form inputs.
+ *
+ * The `FormInputAnnotation` is read from the raw property signature's AST (before
+ * `encodedBoundAST` is applied by `SchemaEx.getProperties`), because `encodedBoundAST` strips
+ * annotations from non-keyword inner types (e.g., `Schema.Struct`, `Schema.Array`).
+ * Without this, fields like `Routine.input` (a JsonSchema struct) annotated
+ * `FormInputAnnotation.set(false)` would still render in the form.
+ *
+ * For optional fields, `prop.type` is the union `T | undefined` — the annotation
+ * lives on the inner `T`. Unwrap before reading so that the conventional pattern
+ * `Schema.String.pipe(FormInputAnnotation.set(false), Schema.optional)` works.
+ *
+ * Container properties (nested structs, unions, arrays) keep their *raw* AST rather than
+ * the `encodedBoundAST` produced by `SchemaEx.getProperties`. `encodedBoundAST` strips annotations
+ * from non-keyword inner types, so a `FormInputAnnotation` nested beneath an encoded container
+ * (e.g. `RouteLeg.geometry`, reached via `Segment → details → routes → Route → legs`) would
+ * otherwise be lost by the time recursion reaches it. Leaf/transformation fields stay encoded
+ * (e.g. a `DateTime` still renders as its encoded string input).
+ */
+export const getFormProperties = (ast: SchemaAST.AST): SchemaEx.SchemaProperty[] => {
+  const signatures = SchemaAST.getPropertySignatures(ast);
+  const rawByName = new Map<PropertyKey, SchemaAST.AST>(signatures.map((prop) => [prop.name, unwrapOptional(prop)]));
+  const hidden = new Set(
+    signatures
+      .filter(
+        (prop) =>
+          Annotation.FormInputAnnotation.getFromAst(unwrapOptional(prop)).pipe(Option.getOrElse(() => true)) === false,
+      )
+      .map((prop) => prop.name),
+  );
+  return SchemaEx.getProperties(ast)
+    .filter((prop) => !hidden.has(prop.name))
+    .map((prop) => {
+      const raw = rawByName.get(prop.name);
+      return raw && (SchemaEx.isNestedType(raw) || SchemaEx.isArrayType(raw)) ? { ...prop, type: raw } : prop;
+    });
+};

package/src/util/refs.ts

@@ -2,37 +2,38 @@
 // Copyright 2025 DXOS.org
 //
 
-import { type SchemaAST } from 'effect';
+import type * as SchemaAST from 'effect/SchemaAST';
 
-import { FormatEnum, ReferenceAnnotationId } from '@dxos/echo-schema';
-import { findAnnotation } from '@dxos/effect';
-import { type SchemaProperty } from '@dxos/schema';
-
-import { findArrayElementType } from './schema';
+import { Ref } from '@dxos/echo';
+import { type ReferenceAnnotationValue, ReferenceAnnotationId } from '@dxos/echo/Annotation';
+import { SchemaEx } from '@dxos/effect';
 
 type RefProps = {
   ast: SchemaAST.AST;
   isArray: boolean;
+  typename?: string;
 };
 
-export const getRefProps = (property: SchemaProperty<any>): RefProps | undefined => {
-  const { ast, format, array } = property;
-
-  // Direct reference.
-  if (format === FormatEnum.Ref) {
-    return { ast, isArray: false };
-  }
-
+export const getRefProps = (ast: SchemaAST.AST): RefProps | undefined => {
   // Array of references.
-  if (array) {
-    const elementType = findArrayElementType(ast);
+  if (SchemaEx.isArrayType(ast)) {
+    const elementType = SchemaEx.getArrayElementType(ast);
     if (elementType) {
-      const annotation = findAnnotation(elementType, ReferenceAnnotationId);
-      if (annotation) {
-        return { ast: elementType, isArray: true };
+      if (Ref.isRefType(elementType)) {
+        const typename = SchemaEx.findAnnotation<ReferenceAnnotationValue>(
+          elementType,
+          ReferenceAnnotationId,
+        )?.typename;
+        return { ast: elementType, isArray: true, typename };
       }
     }
   }
 
+  // Direct reference.
+  if (Ref.isRefType(ast)) {
+    const typename = SchemaEx.findAnnotation<ReferenceAnnotationValue>(ast, ReferenceAnnotationId)?.typename;
+    return { ast, isArray: false, typename };
+  }
+
   return undefined;
 };

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+
+//
+// Copyright 2026 DXOS.org
+//
+
+declare module '*?raw' {
+  const content: string;
+  export default content;
+}

package/dist/types/src/components/ControlSection/ControlSection.d.ts

@@ -1,23 +0,0 @@
-import React, { type ComponentPropsWithoutRef, type PropsWithChildren } from 'react';
-import { type ButtonProps, type Label, type ThemedClassName } from '@dxos/react-ui';
-export type ControlPageProps = ThemedClassName<ComponentPropsWithoutRef<'div'>>;
-export declare const ControlPage: ({ children, classNames, ...props }: ControlPageProps) => React.JSX.Element;
-export type ControlSectionProps = PropsWithChildren<{
-    title: Label;
-    description?: Label;
-}>;
-export declare const ControlSection: ({ title, description, children }: ControlSectionProps) => React.JSX.Element;
-export declare const ControlSectionHeading: ({ title, description }: Omit<ControlSectionProps, "children">) => React.JSX.Element;
-export declare const ControlGroupButton: ({ classNames, ...props }: ButtonProps) => React.JSX.Element;
-export type ControlGroupProps = ThemedClassName<PropsWithChildren<{}>>;
-export declare const ControlGroup: ({ children, classNames }: ControlGroupProps) => React.JSX.Element;
-export declare const ControlFrame: ({ children }: ControlGroupProps) => React.JSX.Element;
-export type ControlItemProps = PropsWithChildren<{
-    title: Label;
-    description?: Label;
-}>;
-export declare const controlItemClasses = "pli-trimMd plb-trimMd container-max-width grid md:col-span-2 grid-cols-subgrid items-center gap-trimSm border border-separator rounded-md *:first:!mbs-0 *:last:!mbe-0";
-export declare const ControlItem: ({ title, description, children }: ControlItemProps) => React.JSX.Element;
-export declare const ControlItemInput: ({ title, description, children }: ControlItemProps) => React.JSX.Element;
-export declare const ControlFrameItem: ({ title, description, children }: ControlItemProps) => React.JSX.Element;
-//# sourceMappingURL=ControlSection.d.ts.map

package/dist/types/src/components/ControlSection/ControlSection.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ControlSection.d.ts","sourceRoot":"","sources":["../../../../../src/components/ControlSection/ControlSection.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAC;AAErF,OAAO,EAEL,KAAK,WAAW,EAEhB,KAAK,KAAK,EACV,KAAK,eAAe,EAGrB,MAAM,gBAAgB,CAAC;AAKxB,MAAM,MAAM,gBAAgB,GAAG,eAAe,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAC;AAEhF,eAAO,MAAM,WAAW,GAAI,oCAAoC,gBAAgB,sBAM/E,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,iBAAiB,CAAC;IAClD,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB,CAAC,CAAC;AAEH,eAAO,MAAM,cAAc,GAAI,kCAAkC,mBAAmB,sBAOnF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,wBAAwB,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,sBAYlG,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,0BAA0B,WAAW,sBAEvE,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,eAAe,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,CAAC;AAEvE,eAAO,MAAM,YAAY,GAAI,0BAA0B,iBAAiB,sBAOvE,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,cAAc,iBAAiB,sBAO3D,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,CAAC;IAC/C,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB,CAAC,CAAC;AAEH,eAAO,MAAM,kBAAkB,2KAC2I,CAAC;AAK3K,eAAO,MAAM,WAAW,GAAI,kCAAkC,gBAAgB,sBAY7E,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,kCAAkC,gBAAgB,sBAoBlF,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,kCAAkC,gBAAgB,sBAUlF,CAAC"}

package/dist/types/src/components/ControlSection/ControlSection.stories.d.ts

@@ -1,8 +0,0 @@
-import '@dxos-theme';
-import { type Meta, type StoryObj } from '@storybook/react-vite';
-import { type ControlSectionProps } from './ControlSection';
-declare const meta: Meta<ControlSectionProps>;
-export default meta;
-type Story = StoryObj<ControlSectionProps>;
-export declare const Default: Story;
-//# sourceMappingURL=ControlSection.stories.d.ts.map