@tai42/studio-sdk 22.4.1 → 24.0.0

package/src/schema-form/date-range-field.tsx

@@ -3,12 +3,14 @@
  * `string`/`format: date` properties where the END names its START in `rangeStart`;
  * the answer stays the two date strings, nothing is recombined. Where a pair is
  * drawable as one control (below), `ObjectFields` renders this {@link DateRangeField}
- * — a group with the two ends' labels over two native date inputs — at the START's
- * slot and skips the END; otherwise the two properties draw as two ordinary date
- * fields (a documented, valid layout).
+ * — a group with one column per end, each the end's labelled native date input and,
+ * when the end has a `timeOf` time, that time's own control under it — at the START's
+ * slot and skips the END and the times; otherwise the properties draw as ordinary
+ * fields, each time right after its date (a documented, valid layout).
  *
- * {@link dateRangePairs} is the ONE definition of "drawable as one control", reused
- * by every surface so each surface's merge decision agrees.
+ * {@link dateRangePairs} is the ONE definition of "drawable as one control", and
+ * {@link fieldDrawingOrder} the one drawing order, both reused by every surface so each
+ * surface's merge decision and field order agree.
  */
 import type { ReactNode } from 'react';
 
@@ -22,6 +24,59 @@ export interface DateRangePair {
   readonly startSchema: JsonSchema;
   readonly endName: string;
   readonly endSchema: JsonSchema;
+  /** The START's `timeOf` time property among the same properties, when it has one. */
+  readonly startTimeName?: string;
+  readonly startTimeSchema?: JsonSchema;
+  /** The END's `timeOf` time property among the same properties, when it has one. */
+  readonly endTimeName?: string;
+  readonly endTimeSchema?: JsonSchema;
+}
+
+/**
+ * `names` in drawing order: each `timeOf` time moved to sit right after the date it
+ * names. `names` is one page's fields, or every property of a page-less form or a
+ * readback, in their given order. A time moves only when the name it points at is in
+ * `names` and does not itself point at another listed name; any other time (its date
+ * not listed, a chain of times, a cycle) keeps its place. Every name appears exactly
+ * once and every other name keeps its relative order. Pure and idempotent, so every
+ * walker that orders the same list draws it the same way.
+ */
+export function fieldDrawingOrder(
+  names: readonly string[],
+  properties: Readonly<Record<string, JsonSchema>>,
+): string[] {
+  const listed = new Set(names);
+  const targetOf = new Map<string, string>();
+  for (const name of names) {
+    const dateName = Object.hasOwn(properties, name) ? properties[name]?.timeOf : undefined;
+    if (typeof dateName === 'string' && dateName !== name && listed.has(dateName)) {
+      targetOf.set(name, dateName);
+    }
+  }
+  const timesOf = new Map<string, string[]>();
+  for (const name of names) {
+    const dateName = targetOf.get(name);
+    if (dateName === undefined || targetOf.has(dateName)) continue;
+    const times = timesOf.get(dateName);
+    if (times === undefined) timesOf.set(dateName, [name]);
+    else times.push(name);
+  }
+  const moved = new Set([...timesOf.values()].flat());
+  const ordered: string[] = [];
+  for (const name of names) {
+    if (moved.has(name)) continue;
+    ordered.push(name);
+    ordered.push(...(timesOf.get(name) ?? []));
+  }
+  return ordered;
+}
+
+/** The `timeOf` time paired with the date `dateName` among `properties`, if any. */
+function pairedTime(
+  dateName: string,
+  properties: readonly (readonly [string, JsonSchema])[],
+): readonly [string, JsonSchema] | undefined {
+  return properties.find(([name, schema]) => schema.timeOf === dateName && name !== dateName);
 }
 
 /** A property's `visibleWhen` as a stable key for deep-equality (absent ⇒ `''`). */
@@ -40,7 +95,8 @@ function isDateString(schema: JsonSchema): boolean {
  * no OTHER field's `visibleWhen` names either end — otherwise merging the pair would
  * leave that field's predicate pointing at a control that no longer draws on its own,
  * so the pair stays two date fields (the documented degrade). `properties` is ONE
- * page's ordered list; a field is used in at most one pair.
+ * page's ordered list; a field is used in at most one pair. Each pair also names each
+ * end's `timeOf` time among the same properties, which draws inside the group.
  */
 export function dateRangePairs(
   properties: readonly (readonly [string, JsonSchema])[],
@@ -65,7 +121,18 @@ export function dateRangePairs(
         (schema.visibleWhen.field === startName || schema.visibleWhen.field === endName),
     );
     if (dependedOn) continue;
-    pairs.push({ startName, startSchema, endName, endSchema });
+    const startTime = pairedTime(startName, properties);
+    const endTime = pairedTime(endName, properties);
+    pairs.push({
+      startName,
+      startSchema,
+      endName,
+      endSchema,
+      ...(startTime === undefined
+        ? {}
+        : { startTimeName: startTime[0], startTimeSchema: startTime[1] }),
+      ...(endTime === undefined ? {} : { endTimeName: endTime[0], endTimeSchema: endTime[1] }),
+    });
     paired.add(startName);
     paired.add(endName);
   }
@@ -77,7 +144,10 @@ function titleOf(schema: JsonSchema, name: string): string {
   return typeof schema.title === 'string' && schema.title.length > 0 ? schema.title : name;
 }
 
-/** One end of the range: a labelled native date input emitting the date string. */
+/**
+ * One end of the range, one column: a labelled native date input emitting the date
+ * string, then the end's time control (when it has a `timeOf` time) under it.
+ */
 function RangeEnd({
   heading,
   schema,
@@ -85,6 +155,7 @@ function RangeEnd({
   required,
   error,
   onChange,
+  time,
 }: {
   heading: string;
   schema: JsonSchema;
@@ -92,26 +163,34 @@ function RangeEnd({
   required: boolean;
   error: string | undefined;
   onChange: (value: unknown) => void;
+  time: ReactNode;
 }): ReactNode {
   const current = typeof value === 'string' ? value : '';
   return (
-    <Field label={heading} error={error}>
-      <TextInput
-        type="date"
-        // The native control enforces its inclusive bounds; the validator enforces
-        // the rest (unavailable days, the range span) that the control cannot draw.
-        min={typeof schema.minDate === 'string' ? schema.minDate : undefined}
-        max={typeof schema.maxDate === 'string' ? schema.maxDate : undefined}
-        required={required}
-        value={current}
-        onChange={(event) => {
-          const next = event.target.value;
-          // An empty optional end drops its key; a required one keeps the empty
-          // string so the validator can flag it.
-          onChange(next === '' && !required ? undefined : next);
-        }}
-      />
-    </Field>
+    <div className="tai-stack tai-stack-3">
+      <Field
+        label={heading}
+        description={typeof schema.description === 'string' ? schema.description : undefined}
+        error={error}
+      >
+        <TextInput
+          type="date"
+          // The native control enforces its inclusive bounds; the validator enforces
+          // the rest (unavailable days, the range span) that the control cannot draw.
+          min={typeof schema.minDate === 'string' ? schema.minDate : undefined}
+          max={typeof schema.maxDate === 'string' ? schema.maxDate : undefined}
+          required={required}
+          value={current}
+          onChange={(event) => {
+            const next = event.target.value;
+            // An empty optional end drops its key; a required one keeps the empty
+            // string so the validator can flag it.
+            onChange(next === '' && !required ? undefined : next);
+          }}
+        />
+      </Field>
+      {time}
+    </div>
   );
 }
 
@@ -126,6 +205,8 @@ export function DateRangeField({
   endError,
   onChangeStart,
   onChangeEnd,
+  startTime,
+  endTime,
 }: {
   readonly pair: DateRangePair;
   readonly startValue: unknown;
@@ -137,6 +218,10 @@ export function DateRangeField({
   readonly endError: string | undefined;
   readonly onChangeStart: (value: unknown) => void;
   readonly onChangeEnd: (value: unknown) => void;
+  /** The START's time control, drawn under its date; `null` when the end has no time. */
+  readonly startTime: ReactNode;
+  /** The END's time control, drawn under its date; `null` when the end has no time. */
+  readonly endTime: ReactNode;
 }): ReactNode {
   const startTitle = titleOf(pair.startSchema, pair.startName);
   const endTitle = titleOf(pair.endSchema, pair.endName);
@@ -152,6 +237,7 @@ export function DateRangeField({
           required={startRequired}
           error={startError}
           onChange={onChangeStart}
+          time={startTime}
         />
         <RangeEnd
           heading={mark(endTitle, endRequired)}
@@ -160,6 +246,7 @@ export function DateRangeField({
           required={endRequired}
           error={endError}
           onChange={onChangeEnd}
+          time={endTime}
         />
       </div>
     </Field>

package/src/schema-form/field-node.tsx

@@ -21,7 +21,7 @@ import { ObjectFields } from './object-fields';
 import { RecordField } from './record-field';
 import { scalarLabel } from './resolve';
 import { StringField } from './string-field';
-import type { JsonSchema, SchemaFormErrors } from './types';
+import type { FieldWords, JsonSchema, SchemaFormErrors } from './types';
 import { UnionField } from './union-field';
 
 interface FieldNodeProps {
@@ -43,13 +43,15 @@ interface FieldNodeProps {
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
   /**
-   * Per-field picker placeholders keyed by property name, handed to an OBJECT node so
-   * its direct `enum`-select children draw their placeholder. Carried by the root form
-   * only; nested objects receive none.
+   * Per-field words keyed by property name, handed to an OBJECT node so its direct
+   * children draw them (an `enum` select's placeholder, a list's words). Carried by the
+   * root form only; nested objects receive none.
    */
-  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string; invalid?: string }>>;
+  readonly fieldWording?: Readonly<Record<string, FieldWords>>;
   /** This field's own picker placeholder, when it draws as an `enum` select. */
   readonly choiceLabel?: string;
+  /** This field's own list words, when it draws as a list. */
+  readonly listWords?: FieldWords;
 }
 
 function labelText(explicit: string | undefined, label: string | undefined): string {
@@ -84,6 +86,7 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
     idPrefix,
     fieldWording: props.fieldWording,
     choiceLabel: props.choiceLabel,
+    listWords: props.listWords,
   });
 }
 
@@ -101,8 +104,9 @@ interface RenderFieldArgs {
   readonly required: boolean;
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
-  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string; invalid?: string }>>;
+  readonly fieldWording?: Readonly<Record<string, FieldWords>>;
   readonly choiceLabel?: string;
+  readonly listWords?: FieldWords;
 }
 
 /** Render the field component matching the classified model kind. */
@@ -220,6 +224,7 @@ function renderCompositeField(
           path={path}
           errors={errors}
           idPrefix={idPrefix}
+          words={args.listWords}
         />
       );
     case 'object':

package/src/schema-form/index.ts

@@ -39,7 +39,7 @@ export type {
 export { RecordEntryRendererContext } from './context';
 export { ExpressionFieldContext } from './context';
 export type { DateRangePair } from './date-range-field';
-export { dateRangePairs } from './date-range-field';
+export { dateRangePairs, fieldDrawingOrder } from './date-range-field';
 export { defaultValueForSchema } from './default-value';
 export { resolveRef } from './resolve';
 export type { CompletionProvider, SchemaFormProps } from './SchemaForm';
@@ -48,6 +48,7 @@ export type { SecretRef, SecretRefFieldProps } from './SecretRefField';
 export { SecretRefField } from './SecretRefField';
 export type {
   Discriminator,
+  FieldWords,
   FormControl,
   FormInputMode,
   JsonSchema,

package/src/schema-form/object-fields.tsx

@@ -7,10 +7,10 @@
 import type { ReactNode } from 'react';
 
 import { ownValue } from '../guards';
-import { DateRangeField, dateRangePairs } from './date-range-field';
+import { DateRangeField, dateRangePairs, fieldDrawingOrder } from './date-range-field';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
-import type { JsonSchema, SchemaFormErrors } from './types';
+import type { FieldWords, JsonSchema, SchemaFormErrors } from './types';
 import { isFieldVisible } from './visibility';
 
 function isPlainObject(value: unknown): value is Record<string, unknown> {
@@ -42,11 +42,12 @@ export function ObjectFields({
   /** Mark each required property's label with the DS required marker. */
   markRequired?: boolean;
   /**
-   * Per-property picker placeholders, keyed by property name. Handed to the root form's
-   * object only; a property whose `enum` draws as a select shows its entry's
-   * `choiceLabel` as the select placeholder. Absent for nested objects.
+   * Per-property words, keyed by property name. Handed to the root form's object only;
+   * a property whose `enum` draws as a select shows its entry's `choiceLabel` as the
+   * select placeholder, and a list property draws its entry's list words. Absent for
+   * nested objects.
    */
-  fieldWording?: Readonly<Record<string, { choiceLabel?: string; invalid?: string }>>;
+  fieldWording?: Readonly<Record<string, FieldWords>>;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
   const changeFor = useKeyedCallbacks<string, unknown>(
@@ -58,15 +59,49 @@ export function ObjectFields({
   // A drawable date-range pair renders as ONE DateRangeField at the START's slot; the
   // END is skipped. The pairing is `dateRangePairs`, the one definition every surface
   // shares. Properties here are one page's, so the "same page" rule holds by construction.
+  // A pair's `timeOf` times draw inside its group, so they are skipped too. The fields
+  // walk in `fieldDrawingOrder`: each time right after its date, wherever it is declared.
   const pairs = dateRangePairs(properties);
   const pairByStart = new Map(pairs.map((pair) => [pair.startName, pair]));
-  const skippedEnds = new Set(pairs.map((pair) => pair.endName));
+  const skipped = new Set(
+    pairs.flatMap((pair) =>
+      [pair.endName, pair.startTimeName, pair.endTimeName].filter(
+        (name): name is string => name !== undefined,
+      ),
+    ),
+  );
+  const schemaByName = new Map(properties);
+  const drawn = fieldDrawingOrder(
+    properties.map(([name]) => name),
+    Object.fromEntries(properties),
+  );
   const childPathOf = (name: string): string => (path === '' ? name : `${path}.${name}`);
+  const fieldOf = (name: string, propSchema: JsonSchema): ReactNode => (
+    <FieldNode
+      key={name}
+      schema={propSchema}
+      root={root}
+      value={ownValue(obj, name)}
+      onChange={changeFor(name)}
+      path={childPathOf(name)}
+      label={name}
+      required={requiredKeys.has(name)}
+      markRequired={markRequired}
+      errors={errors}
+      idPrefix={idPrefix}
+      choiceLabel={ownValue(fieldWording, name)?.choiceLabel}
+      listWords={ownValue(fieldWording, name)}
+    />
+  );
+  const timeOf = (name: string | undefined, propSchema: JsonSchema | undefined): ReactNode =>
+    name === undefined || propSchema === undefined ? null : fieldOf(name, propSchema);
   return (
     <>
-      {properties.map(([name, propSchema]) => {
+      {drawn.map((name) => {
+        const propSchema = schemaByName.get(name);
+        if (propSchema === undefined) return null;
         if (skip !== undefined && name === skip) return null;
-        if (skippedEnds.has(name)) return null;
+        if (skipped.has(name)) return null;
         // A field hidden by its `visibleWhen` predicate is not rendered; the
         // validator skips it in step, so a hidden field is neither shown nor required.
         if (!isFieldVisible(propSchema, obj)) return null;
@@ -85,25 +120,12 @@ export function ObjectFields({
               endError={ownValue(errors, childPathOf(pair.endName))}
               onChangeStart={changeFor(pair.startName)}
               onChangeEnd={changeFor(pair.endName)}
+              startTime={timeOf(pair.startTimeName, pair.startTimeSchema)}
+              endTime={timeOf(pair.endTimeName, pair.endTimeSchema)}
             />
           );
         }
-        return (
-          <FieldNode
-            key={name}
-            schema={propSchema}
-            root={root}
-            value={ownValue(obj, name)}
-            onChange={changeFor(name)}
-            path={childPathOf(name)}
-            label={name}
-            required={requiredKeys.has(name)}
-            markRequired={markRequired}
-            errors={errors}
-            idPrefix={idPrefix}
-            choiceLabel={fieldWording?.[name]?.choiceLabel}
-          />
-        );
+        return fieldOf(name, propSchema);
       })}
     </>
   );

package/src/schema-form/types.ts

@@ -115,6 +115,13 @@ export interface JsonSchema {
   readonly rangeStart?: string;
   readonly minDays?: number;
   readonly maxDays?: number;
+  /**
+   * On a `string`/`format: time` property: the name of the range-end `date` property this
+   * is the time of. The time draws right after its date (inside the range group when the
+   * pair merges), and two ends on the same date are then ordered by their times. Absent =
+   * a time field of its own.
+   */
+  readonly timeOf?: string;
   /**
    * A declarative visibility predicate on a property: the field shows only when the
    * predicate holds against the current form values. Static form description evaluated by
@@ -146,3 +153,26 @@ export interface VisibleWhen {
  * each entry is a loud, human-readable message. Empty object = valid.
  */
 export type SchemaFormErrors = Readonly<Record<string, string>>;
+
+/**
+ * A form field's own words, keyed by the root object's property name in a form's
+ * `fieldWording`. Every member is optional; an unset one draws the SDK's own word.
+ *
+ * - `choiceLabel`: the placeholder of the field's `enum` select (in place of `Select…`).
+ * - `invalid`: the sentence that replaces every shape error on the field and anything
+ *   inside it (a format, pattern, length, bound, type or item error).
+ * - `required`: the sentence shown when the field's required value is missing, at the
+ *   field or anywhere inside it (in place of `"<name>" is required`).
+ * - `addItem` / `removeItem` / `itemLabel` / `noItems`: a list field's add button, each
+ *   item's remove button, each item's heading (its `{n}` token takes the item's number),
+ *   and the line shown while the list is empty.
+ */
+export interface FieldWords {
+  readonly choiceLabel?: string;
+  readonly invalid?: string;
+  readonly required?: string;
+  readonly addItem?: string;
+  readonly removeItem?: string;
+  readonly itemLabel?: string;
+  readonly noItems?: string;
+}