@tai42/studio-sdk 21.0.0 → 22.0.0

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

@@ -41,6 +41,14 @@ interface FieldNodeProps {
   readonly markRequired?: boolean;
   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.
+   */
+  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  /** This field's own picker placeholder, when it draws as an `enum` select. */
+  readonly choiceLabel?: string;
 }
 
 function labelText(explicit: string | undefined, label: string | undefined): string {
@@ -73,6 +81,8 @@ function FieldNodeImpl(props: FieldNodeProps): ReactNode {
     required,
     errors,
     idPrefix,
+    fieldWording: props.fieldWording,
+    choiceLabel: props.choiceLabel,
   });
 }
 
@@ -90,6 +100,8 @@ interface RenderFieldArgs {
   readonly required: boolean;
   readonly errors: SchemaFormErrors | undefined;
   readonly idPrefix: string;
+  readonly fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
+  readonly choiceLabel?: string;
 }
 
 /** Render the field component matching the classified model kind. */
@@ -126,6 +138,7 @@ function renderField(args: RenderFieldArgs): ReactNode {
           model={model}
           value={value}
           onChange={onChange}
+          choiceLabel={args.choiceLabel}
         />
       );
     case 'string':
@@ -135,6 +148,10 @@ function renderField(args: RenderFieldArgs): ReactNode {
           description={description}
           error={error}
           format={model.format}
+          inputMode={model.inputMode}
+          multiline={model.multiline}
+          maxLength={model.maxLength}
+          minLength={model.minLength}
           media={model.media}
           expression={model.expression}
           date={model.date}
@@ -187,6 +204,7 @@ function renderCompositeField(
   model: Extract<FieldModel, { kind: 'array' | 'object' | 'record' | 'union' }>,
 ): ReactNode {
   const { heading, description, error, root, value, onChange, path, errors, idPrefix } = args;
+  const { fieldWording } = args;
   switch (model.kind) {
     case 'array':
       return (
@@ -216,6 +234,7 @@ function renderCompositeField(
             errors={errors}
             idPrefix={idPrefix}
             skip={undefined}
+            fieldWording={fieldWording}
           />
         </FieldGroup>
       );

package/src/schema-form/index.ts

@@ -38,12 +38,21 @@ export type {
 } from './context';
 export { RecordEntryRendererContext } from './context';
 export { ExpressionFieldContext } from './context';
+export type { DateRangePair } from './date-range-field';
+export { dateRangePairs } from './date-range-field';
 export { defaultValueForSchema } from './default-value';
 export { resolveRef } from './resolve';
 export type { CompletionProvider, SchemaFormProps } from './SchemaForm';
 export { SchemaForm } from './SchemaForm';
 export type { SecretRef, SecretRefFieldProps } from './SecretRefField';
 export { SecretRefField } from './SecretRefField';
-export type { Discriminator, JsonSchema, JsonSchemaType, SchemaFormErrors } from './types';
+export type {
+  Discriminator,
+  FormControl,
+  FormInputMode,
+  JsonSchema,
+  JsonSchemaType,
+  SchemaFormErrors,
+} from './types';
 export { validateAgainstSchema } from './validate';
 export { isFieldVisible } from './visibility';

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

@@ -8,6 +8,7 @@
 import type { ReactNode } from 'react';
 
 import { Checkbox } from '../components/checkbox';
+import { ChipGroup } from '../components/chip-group';
 import { Field } from '../components/field';
 import type { FieldModel } from './field-model';
 
@@ -38,6 +39,26 @@ export function MultiSelectField({
       .filter((candidate) => next.includes(candidate));
     onChange(ordered);
   };
+
+  // `control: chips` draws the multi-select as a toggle-chip grid in place of the
+  // checkbox group. The chips emit the selection in the OPTIONS' declared order.
+  if (model.control === 'chips') {
+    return (
+      <Field label={heading} description={description} error={error} group>
+        <ChipGroup
+          mode="multi"
+          options={model.options.map((option) => ({
+            value: String(option.value),
+            label: option.label,
+          }))}
+          value={selected}
+          onValueChange={(next) => {
+            onChange([...next]);
+          }}
+        />
+      </Field>
+    );
+  }
   return (
     <Field label={heading} description={description} error={error} group>
       {model.options.map((option, index) => {

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

@@ -6,6 +6,7 @@
  */
 import type { ReactNode } from 'react';
 
+import { DateRangeField, dateRangePairs } from './date-range-field';
 import { FieldNode } from './field-node';
 import { useKeyedCallbacks } from './keyed-callbacks';
 import type { JsonSchema, SchemaFormErrors } from './types';
@@ -26,6 +27,7 @@ export function ObjectFields({
   idPrefix,
   skip,
   markRequired = false,
+  fieldWording,
 }: {
   properties: readonly (readonly [string, JsonSchema])[];
   requiredKeys: ReadonlySet<string>;
@@ -38,6 +40,12 @@ export function ObjectFields({
   skip: string | undefined;
   /** 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.
+   */
+  fieldWording?: Readonly<Record<string, { choiceLabel?: string }>>;
 }): ReactNode {
   const obj = isPlainObject(value) ? value : {};
   const changeFor = useKeyedCallbacks<string, unknown>(
@@ -46,14 +54,39 @@ export function ObjectFields({
     },
     properties.map(([name]) => name),
   );
+  // 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.
+  const pairs = dateRangePairs(properties);
+  const pairByStart = new Map(pairs.map((pair) => [pair.startName, pair]));
+  const skippedEnds = new Set(pairs.map((pair) => pair.endName));
+  const childPathOf = (name: string): string => (path === '' ? name : `${path}.${name}`);
   return (
     <>
       {properties.map(([name, propSchema]) => {
         if (skip !== undefined && name === skip) return null;
+        if (skippedEnds.has(name)) return null;
         // A field hidden by its `visibleWhen` predicate (scope B) is not rendered; the
         // validator skips it in step, so a hidden field is neither shown nor required.
         if (!isFieldVisible(propSchema, obj)) return null;
-        const childPath = path === '' ? name : `${path}.${name}`;
+        const pair = pairByStart.get(name);
+        if (pair !== undefined) {
+          return (
+            <DateRangeField
+              key={name}
+              pair={pair}
+              startValue={obj[pair.startName]}
+              endValue={obj[pair.endName]}
+              startRequired={requiredKeys.has(pair.startName)}
+              endRequired={requiredKeys.has(pair.endName)}
+              markRequired={markRequired}
+              startError={errors?.[childPathOf(pair.startName)]}
+              endError={errors?.[childPathOf(pair.endName)]}
+              onChangeStart={changeFor(pair.startName)}
+              onChangeEnd={changeFor(pair.endName)}
+            />
+          );
+        }
         return (
           <FieldNode
             key={name}
@@ -61,12 +94,13 @@ export function ObjectFields({
             root={root}
             value={obj[name]}
             onChange={changeFor(name)}
-            path={childPath}
+            path={childPathOf(name)}
             label={name}
             required={requiredKeys.has(name)}
             markRequired={markRequired}
             errors={errors}
             idPrefix={idPrefix}
+            choiceLabel={fieldWording?.[name]?.choiceLabel}
           />
         );
       })}

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

@@ -31,12 +31,17 @@ import { CompletionProviderContext, ExpressionFieldContext } from './context';
 import type { DateConstraints, ExpressionAnnotation, MediaUpload } from './field-model';
 import { MediaField } from './media-field';
 import type { CompletionProvider } from './SchemaForm';
+import type { FormInputMode } from './types';
 
 export function StringField({
   heading,
   description,
   error,
   format,
+  inputMode,
+  multiline,
+  maxLength,
+  minLength,
   media,
   expression,
   date,
@@ -49,6 +54,10 @@ export function StringField({
   description: string | undefined;
   error: string | undefined;
   format: string | undefined;
+  inputMode: FormInputMode | undefined;
+  multiline: boolean;
+  maxLength: number | undefined;
+  minLength: number | undefined;
   media: MediaUpload | undefined;
   expression: ExpressionAnnotation | undefined;
   date: DateConstraints | undefined;
@@ -57,6 +66,7 @@ export function StringField({
   required: boolean;
   onChange: (value: unknown) => void;
 }): ReactNode {
+  const control = stringControl(format, inputMode);
   const completionProvider = useContext(CompletionProviderContext);
   const expressionField = useContext(ExpressionFieldContext);
   const current = typeof value === 'string' ? value : '';
@@ -114,24 +124,58 @@ export function StringField({
           onChange={emit}
           provider={completionProvider}
         />
+      ) : multiline ? (
+        // `control: textarea` draws a multi-line control; the length bounds draw
+        // natively, and a live counter shows the maximum (below).
+        <Textarea
+          maxLength={maxLength}
+          minLength={minLength}
+          value={current}
+          onChange={(event) => {
+            emit(event.target.value);
+          }}
+        />
       ) : (
         <TextInput
-          type={stringInputType(format)}
+          type={control.type}
+          // The keyboard hint for a `numeric`/`decimal` mode (a text box with a
+          // numeric/decimal keyboard); `undefined` for every other control, which
+          // selects its kind through `type` instead.
+          inputMode={control.inputMode}
           // A native date control enforces its inclusive bounds (scope C); on a
           // non-date input the browser ignores these, and the validator enforces the
           // rest (unavailable days, range span) that the control cannot draw.
           min={date?.min}
           max={date?.max}
+          // The length bounds draw natively (the control caps input at `maxLength`)
+          // and the validator enforces them; a counter shows the maximum (below).
+          maxLength={maxLength}
+          minLength={minLength}
           value={current}
           onChange={(event) => {
             emit(event.target.value);
           }}
         />
       )}
+      {/* The live length counter, shown whenever a maximum is declared — on both the
+          text box and the text area. It counts code points, matching the validator's
+          own `maxLength` check. */}
+      {completionProvider === undefined && maxLength !== undefined ? (
+        <LengthCounter current={current} max={maxLength} />
+      ) : null}
     </Field>
   );
 }
 
+/** The `n / max` length hint under a bounded string control. */
+function LengthCounter({ current, max }: { current: string; max: number }): ReactNode {
+  return (
+    <p className="tai-field-hint" style={{ margin: 0 }} aria-live="polite">
+      {`${String(Array.from(current).length)} / ${String(max)}`}
+    </p>
+  );
+}
+
 /**
  * A string field backed by argument completions. Split out so its memoised
  * hooks stay unconditional (they cannot live behind the provider check in
@@ -360,3 +404,30 @@ function stringInputType(format: string | undefined): string {
   if (format === undefined) return 'text';
   return FORMAT_INPUT_TYPES[format] ?? 'text';
 }
+
+/** The native control each `inputMode` draws. `tel`/`email`/`url` select the
+ *  matching input `type`; `numeric`/`decimal` keep a text box and set the HTML
+ *  `inputmode` keyboard hint; `text` is a plain text box. */
+const INPUT_MODE_CONTROLS: Record<
+  FormInputMode,
+  { readonly type: string; readonly inputMode: 'numeric' | 'decimal' | undefined }
+> = {
+  text: { type: 'text', inputMode: undefined },
+  numeric: { type: 'text', inputMode: 'numeric' },
+  decimal: { type: 'text', inputMode: 'decimal' },
+  tel: { type: 'tel', inputMode: undefined },
+  email: { type: 'email', inputMode: undefined },
+  url: { type: 'url', inputMode: undefined },
+};
+
+// The native control for a string field: the `inputMode` keyword OUTRANKS
+// `format` when present; otherwise the format mapping stands as before. The value
+// is always the typed string — `numeric`/`decimal` set only the keyboard, never a
+// number coercion.
+function stringControl(
+  format: string | undefined,
+  inputMode: FormInputMode | undefined,
+): { readonly type: string; readonly inputMode: 'numeric' | 'decimal' | undefined } {
+  if (inputMode !== undefined) return INPUT_MODE_CONTROLS[inputMode];
+  return { type: stringInputType(format), inputMode: undefined };
+}

package/src/schema-form/types.ts

@@ -11,6 +11,24 @@
 export type JsonSchemaType =
   'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
 
+/**
+ * The input KIND a `string` field collects, drawn as the matching keyboard or
+ * native control. The vocabulary is the HTML `inputmode`/control naming of the
+ * concept: `numeric`/`decimal` set a text box's keyboard hint; `tel`/`email`/`url`
+ * select the matching native control. It draws, it does not validate.
+ */
+export type FormInputMode = 'text' | 'numeric' | 'decimal' | 'tel' | 'email' | 'url';
+
+/**
+ * The CONTROL a surface draws for a property in place of the default for the
+ * property's shape. `chips` draws a choice (a `string` with an `enum`, or an
+ * `array` of such strings) as a tap-to-select chip grid instead of the
+ * radio/select or checkbox group. `textarea` draws a `string` as a multi-line
+ * text control instead of a single-line box. It changes what is DRAWN, never what
+ * is accepted — the value and its validation stay the property's own.
+ */
+export type FormControl = 'chips' | 'textarea';
+
 /** A Pydantic-style discriminated-union tag: which property selects the variant. */
 export interface Discriminator {
   readonly propertyName: string;
@@ -61,6 +79,26 @@ export interface JsonSchema {
   readonly minItems?: number;
   readonly maxItems?: number;
   readonly pattern?: string;
+  /**
+   * The input KIND a `string` field collects — a platform keyword (see {@link
+   * FormInputMode}). The renderer draws the matching keyboard or native control:
+   * `numeric`/`decimal` a text box with that keyboard hint (the value stays the
+   * typed string, so `"007"` keeps its leading zeros), `tel`/`email`/`url` the
+   * matching native control, `text` or absent a plain text box. It DRAWS, it does
+   * not validate — the answer door still enforces `type`, `pattern` and `format`.
+   * When present it OUTRANKS `format` for the control. A value outside the set is
+   * read as absent (the server ask door is the authority that refuses it).
+   */
+  readonly inputMode?: FormInputMode;
+  /**
+   * The CONTROL to draw for this property in place of its shape's default — a
+   * platform keyword (see {@link FormControl}). `chips` draws a `string`-with-`enum`
+   * or an `array` of such strings as a chip grid; `textarea` draws a `string` as a
+   * multi-line text control. It DRAWS, it does not validate — the answer door still
+   * enforces the property's `type`, `enum`, `maxLength` and the rest. A value outside
+   * the set is read as absent (the server ask door is the authority that refuses it).
+   */
+  readonly control?: FormControl;
   /**
    * Platform date-constraint keys on a `string`/`date` (or `date-time`) property. They
    * are NOT the JSON-Schema numeric keywords (which are inert on a string): `minDate`/