feat(spec): add Field.time builder to close the temporal-field authoring gap (#10048)

The Field convenience object exposed Field.date and Field.datetime but no
Field.time, even though 'time' is a fully declared FieldType and is live
end-to-end. This is the minimal move pre-approved by the hold-release
grading on #8656: add Field.time alone, mirroring the adjacent
Field.datetime builder and producing the identical literal shape an
author could already write - { type: 'time', ...config } - so nothing
about what FieldSchema accepts changes.

Also swaps the showcase field-zoo's f_time from the literal form to
Field.time(...), removing the stale precedent for authors reaching for
the type.

Fixes #8656


Claude-Session: https://claude.ai/code/session_01URCaKuNTuK3BKJvwqM74QU

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/field-time-builder.md

@@ -0,0 +1,18 @@
+---
+"@objectstack/spec": patch
+---
+
+feat(spec): add `Field.time` builder to close the temporal-field authoring gap (#8656)
+
+The `Field` convenience object exposed `Field.date` and `Field.datetime` but no
+`Field.time`, even though `'time'` is a fully declared `FieldType` and is live
+end-to-end (validated by `field-value.zod.ts` as `HH:mm[:ss]`, stored, and
+rendered by the inline grid's time control). The gap split the three temporal
+types two-and-one, forcing authors reaching for `time` to fall back to the
+literal `{ type: 'time', ... }` form — the shape `examples/app-showcase`'s
+`field-zoo.object.ts` already carried, flagged `// no Field.time`.
+
+`Field.time` mirrors the adjacent `Field.datetime` builder exactly and produces
+the identical literal shape an author could already write — `{ type: 'time',
+...config }` — so nothing about what `FieldSchema` accepts changes; this is
+sugar over an already-declared field type, not a schema change.

examples/app-showcase/src/data/objects/field-zoo.object.ts

@@ -54,7 +54,7 @@ export const FieldZoo = ObjectSchema.create({
     // ── Date & time ──────────────────────────────────────────────────────
     f_date: Field.date({ label: 'Date' }),
     f_datetime: Field.datetime({ label: 'Date / Time' }),
-    f_time: { type: 'time', label: 'Time' },
+    f_time: Field.time({ label: 'Time' }),
 
     // ── Logic ────────────────────────────────────────────────────────────
     f_boolean: Field.boolean({ label: 'Boolean' }),

packages/spec/src/data/field.test.ts

@@ -795,10 +795,21 @@ describe('Field Factory Helpers', () => {
 
     it('should create email field', () => {
       const emailField = Field.email({ label: 'Email Address' });
-      
+
       expect(emailField.type).toBe('email');
       expect(emailField.label).toBe('Email Address');
     });
+
+    it('should create time field (#8656)', () => {
+      const timeField = Field.time({ label: 'Time' });
+
+      expect(timeField.type).toBe('time');
+      expect(timeField.label).toBe('Time');
+      expect(() => FieldSchema.parse(timeField)).not.toThrow();
+      // Clause-2 pin: the builder must produce exactly the literal form an
+      // author could already write today — no accept-set change.
+      expect(timeField).toEqual({ type: 'time', label: 'Time' });
+    });
   });
 
   describe('Select Field Factory', () => {

packages/spec/src/data/field.zod.ts

@@ -1548,6 +1548,7 @@ export const Field = {
   boolean: (config: FieldInput = {}) => ({ type: 'boolean', ...config } as const),
   date: (config: FieldInput = {}) => ({ type: 'date', ...config } as const),
   datetime: (config: FieldInput = {}) => ({ type: 'datetime', ...config } as const),
+  time: (config: FieldInput = {}) => ({ type: 'time', ...config } as const),
   currency: (config: FieldInput = {}) => ({ type: 'currency', ...config } as const),
   percent: (config: FieldInput = {}) => ({ type: 'percent', ...config } as const),
   url: (config: FieldInput = {}) => ({ type: 'url', ...config } as const),