@vectoriox/iox-ui 5.82.2 → 5.83.1

package/src/forms-core/dates.ts

@@ -0,0 +1,299 @@
+/**
+ * DATES — the date picker's pure half (premium components N8) and the date rules' one reading.
+ *
+ * A Date field's value is an ISO day, `YYYY-MM-DD`, compared as a string (the format sorts as the calendar does).
+ * Its `min` / `max` rules take an ISO day OR an offset in days from today (`{ offsetDays: 0 }` = today), so "from
+ * today on" stays true tomorrow without a re-save. ONE reading for the validator (client AND iox-cms), the calendar
+ * (which days it refuses) and the builder's Earliest / Latest controls.
+ *
+ * The calendar model (six rows of seven, roving focus, the APG keys) lives here too, so the DOM runtime only draws
+ * what this decides — the canvas, the engine's component path and its string path draw the SAME month.
+ *
+ * ⚠️ Framework-free, like the rest of forms-core. Local-time `Date` objects are used only to walk the calendar; a
+ * day leaves this file as an ISO string.
+ */
+
+import { ControlType, FieldSpec, RuleName, ValidationRule } from './form.model';
+
+const ISO_DAY = /^(\d{4})-(\d{2})-(\d{2})$/;
+const OFFSET = /^[+-]?\d+$/;
+const DAYS_IN_WEEK = 7;
+/** Always six rows, so the panel never changes size between months (APG; Emil 74 — one object, one size). */
+export const CALENDAR_ROWS = 6;
+
+const pad = (n: number, width = 2) => String(n).padStart(width, '0');
+
+/** The ISO day of a local `Date`. */
+export function isoOfDate(d: Date): string {
+    return `${pad(d.getFullYear(), 4)}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+/** A local `Date` at midnight for an ISO day, or null when it is not one (2026-02-30 is not). */
+export function dateOfIso(iso: unknown): Date | null {
+    const m = typeof iso === 'string' ? ISO_DAY.exec(iso.trim()) : null;
+    if (!m) return null;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const date = new Date(y, mo - 1, d);
+    date.setFullYear(y);
+    return date.getFullYear() === y && date.getMonth() === mo - 1 && date.getDate() === d ? date : null;
+}
+
+/** True for a real calendar day written `YYYY-MM-DD`. */
+export function isIsoDate(value: unknown): boolean {
+    return dateOfIso(value) !== null;
+}
+
+/** Today, as the device that runs this sees it (the visitor's local day in a browser; the server's on iox-cms). */
+export function todayIso(now: Date = new Date()): string {
+    return isoOfDate(now);
+}
+
+/** `iso` moved by `days` (negative goes back). */
+export function addDaysIso(iso: string, days: number): string {
+    const d = dateOfIso(iso);
+    if (!d) return iso;
+    return isoOfDate(new Date(d.getFullYear(), d.getMonth(), d.getDate() + days));
+}
+
+/** `iso` moved by `months`, its day clamped to the target month's last (31 Jan + 1 month = 28/29 Feb). */
+export function addMonthsIso(iso: string, months: number): string {
+    const d = dateOfIso(iso);
+    if (!d) return iso;
+    const first = new Date(d.getFullYear(), d.getMonth() + months, 1);
+    const last = new Date(first.getFullYear(), first.getMonth() + 1, 0).getDate();
+    return isoOfDate(new Date(first.getFullYear(), first.getMonth(), Math.min(d.getDate(), last)));
+}
+
+/** `iso` held inside [min, max] (either may be absent). */
+export function clampIso(iso: string, min?: string | null, max?: string | null): string {
+    if (min && iso < min) return min;
+    if (max && iso > max) return max;
+    return iso;
+}
+
+// ─── bounds: Earliest / Latest ───────────────────────────────────────────────
+
+/** A date rule's parameter: an ISO day, or a number of days from today. */
+export interface DateBoundParams {
+    date?: string;
+    offsetDays?: number;
+}
+
+/**
+ * A Field's `earliest` / `latest` trait → the rule parameter. The trait is one string so the panel and a saved page
+ * stay simple: `''` = any day · an integer = that many days from today (`'0'` = today, `'30'` = a month ahead) · an
+ * ISO day. Anything else reads as no bound.
+ */
+export function parseDateBound(raw: unknown): DateBoundParams | null {
+    if (typeof raw === 'number' && Number.isInteger(raw)) return { offsetDays: raw };
+    if (typeof raw !== 'string') return null;
+    const text = raw.trim();
+    if (!text) return null;
+    if (OFFSET.test(text)) return { offsetDays: Number(text) };
+    return isIsoDate(text) ? { date: text } : null;
+}
+
+/** The `min` / `max` rules a Date field's Earliest / Latest traits give it (none for "any"). */
+export function dateBoundRules(earliest: unknown, latest: unknown): ValidationRule[] {
+    const rules: ValidationRule[] = [];
+    const min = parseDateBound(earliest);
+    const max = parseDateBound(latest);
+    if (min) rules.push({ name: RuleName.Min, params: { ...min } });
+    if (max) rules.push({ name: RuleName.Max, params: { ...max } });
+    return rules;
+}
+
+/** True when a rule's params are a DATE bound (an ISO day or an offset), never a number bound. */
+export function isDateBoundParams(params: Record<string, any> | null | undefined): boolean {
+    return !!params && (typeof params['date'] === 'string' || Number.isInteger(params['offsetDays']));
+}
+
+/** The ISO day a bound names today, or null when it names none. */
+export function resolveDateBound(params: Record<string, any> | null | undefined, today: string): string | null {
+    if (!params) return null;
+    if (typeof params['date'] === 'string' && isIsoDate(params['date'])) return params['date'];
+    if (Number.isInteger(params['offsetDays'])) return addDaysIso(today, params['offsetDays']);
+    return null;
+}
+
+/** The first and last day a Date field accepts today — the calendar's refused days and the validator's range. */
+export function fieldDateRange(field: Pick<FieldSpec, 'rules'> | null | undefined, today: string): { min: string | null; max: string | null } {
+    let min: string | null = null;
+    let max: string | null = null;
+    for (const rule of field?.rules ?? []) {
+        if (rule.name === RuleName.Min) min = resolveDateBound(rule.params, today) ?? min;
+        if (rule.name === RuleName.Max) max = resolveDateBound(rule.params, today) ?? max;
+    }
+    return { min, max };
+}
+
+/** True when the field is a date picker (the control that reads these rules as days). */
+export function isDateField(field: Pick<FieldSpec, 'control'> | null | undefined): boolean {
+    return field?.control === ControlType.Date;
+}
+
+// ─── the week, the month, the keys ───────────────────────────────────────────
+
+/** Regions whose week starts on Sunday when the runtime cannot say (Intl.Locale#getWeekInfo is not everywhere). */
+const SUNDAY_REGIONS: ReadonlySet<string> = new Set(['US', 'CA', 'IL', 'JP', 'BR', 'MX', 'PH', 'IN', 'KR', 'TW', 'ZA', 'AU']);
+const SUNDAY_LANGUAGES: ReadonlySet<string> = new Set(['he', 'iw', 'ja', 'ko']);
+
+/**
+ * The first day of the week for a locale, 0 = Sunday … 6 = Saturday. `Intl.Locale(…).getWeekInfo()` (or the older
+ * `weekInfo` getter) when the runtime has it, else a small region table; a bare `en` reads as the US.
+ */
+export function weekStartFor(locale: string | null | undefined): number {
+    const tag = locale || 'en';
+    try {
+        const Ctor = (Intl as any).Locale;
+        if (Ctor) {
+            const loc = new Ctor(tag);
+            const info = typeof loc.getWeekInfo === 'function' ? loc.getWeekInfo() : loc.weekInfo;
+            const first = Number(info?.firstDay);
+            if (first >= 1 && first <= 7) return first % DAYS_IN_WEEK;
+        }
+    } catch { /* an unknown tag falls through to the table */ }
+    const [language, region] = tag.split(/[-_]/);
+    if (region && SUNDAY_REGIONS.has(region.toUpperCase())) return 0;
+    if (!region && (language === 'en' || SUNDAY_LANGUAGES.has(language))) return 0;
+    return 1;
+}
+
+/** One cell of the month grid. */
+export interface CalendarDay {
+    iso: string;
+    day: number;
+    today: boolean;
+    selected: boolean;
+    /** Outside Earliest / Latest: shown, announced as unavailable, never picked. */
+    disabled: boolean;
+    /** The roving tab stop — exactly one day of the month has it. */
+    focus: boolean;
+}
+
+export interface CalendarMonth {
+    year: number;
+    /** 0-based, as `Date` counts. */
+    month: number;
+    /** `CALENDAR_ROWS` × 7; null where the month has no day. */
+    weeks: Array<Array<CalendarDay | null>>;
+    /** The weekday of each column, 0 = Sunday — the header row reads these. */
+    weekdays: number[];
+    canPrev: boolean;
+    canNext: boolean;
+}
+
+export interface CalendarOptions {
+    weekStart: number;
+    today: string;
+    min?: string | null;
+    max?: string | null;
+    selected?: string | null;
+}
+
+/** The month `focus` sits in, as six rows of seven — the ONE grid every renderer draws. */
+export function calendarMonth(focus: string, options: CalendarOptions): CalendarMonth {
+    const at = dateOfIso(focus) ?? dateOfIso(options.today) ?? new Date();
+    const year = at.getFullYear();
+    const month = at.getMonth();
+    const lead = (new Date(year, month, 1).getDay() - options.weekStart + DAYS_IN_WEEK) % DAYS_IN_WEEK;
+    const days = new Date(year, month + 1, 0).getDate();
+    const weeks: Array<Array<CalendarDay | null>> = [];
+    for (let r = 0; r < CALENDAR_ROWS; r++) {
+        const row: Array<CalendarDay | null> = [];
+        for (let c = 0; c < DAYS_IN_WEEK; c++) {
+            const n = r * DAYS_IN_WEEK + c - lead + 1;
+            if (n < 1 || n > days) { row.push(null); continue; }
+            const iso = isoOfDate(new Date(year, month, n));
+            row.push({
+                iso, day: n,
+                today: iso === options.today,
+                selected: iso === options.selected,
+                disabled: (!!options.min && iso < options.min) || (!!options.max && iso > options.max),
+                focus: iso === focus,
+            });
+        }
+        weeks.push(row);
+    }
+    const monthKey = (iso: string | null | undefined) => (iso ? iso.slice(0, 7) : null);
+    const here = monthKey(isoOfDate(new Date(year, month, 1)))!;
+    const minMonth = monthKey(options.min);
+    const maxMonth = monthKey(options.max);
+    return {
+        year, month, weeks,
+        weekdays: Array.from({ length: DAYS_IN_WEEK }, (_, i) => (options.weekStart + i) % DAYS_IN_WEEK),
+        canPrev: !minMonth || here > minMonth,
+        canNext: !maxMonth || here < maxMonth,
+    };
+}
+
+/** The keys the grid answers (APG date picker dialog). */
+export enum CalendarKey {
+    Left = 'ArrowLeft',
+    Right = 'ArrowRight',
+    Up = 'ArrowUp',
+    Down = 'ArrowDown',
+    Home = 'Home',
+    End = 'End',
+    PageUp = 'PageUp',
+    PageDown = 'PageDown',
+}
+
+const KEY_MOVES: Readonly<Record<CalendarKey, (iso: string, ctx: { ahead: number; dow: number; shift: boolean }) => string>> = {
+    // The arrows follow the READING direction: in RTL "→" is a day back (APG; mirrored).
+    [CalendarKey.Right]: (iso, c) => addDaysIso(iso, c.ahead),
+    [CalendarKey.Left]: (iso, c) => addDaysIso(iso, -c.ahead),
+    [CalendarKey.Down]: iso => addDaysIso(iso, DAYS_IN_WEEK),
+    [CalendarKey.Up]: iso => addDaysIso(iso, -DAYS_IN_WEEK),
+    [CalendarKey.Home]: (iso, c) => addDaysIso(iso, -c.dow),
+    [CalendarKey.End]: (iso, c) => addDaysIso(iso, DAYS_IN_WEEK - 1 - c.dow),
+    // A month; with Shift, a year.
+    [CalendarKey.PageUp]: (iso, c) => addMonthsIso(iso, c.shift ? -12 : -1),
+    [CalendarKey.PageDown]: (iso, c) => addMonthsIso(iso, c.shift ? 12 : 1),
+};
+
+/**
+ * Where a key moves the focused day, held inside [min, max] — or null for a key the grid does not answer (Enter,
+ * Space and Escape are the runtime's: they pick or close, they never move).
+ */
+export function calendarKeyTarget(key: string, focus: string, options: { weekStart: number; rtl?: boolean; shift?: boolean; min?: string | null; max?: string | null }): string | null {
+    const move = KEY_MOVES[key as CalendarKey];
+    const at = dateOfIso(focus);
+    if (!move || !at) return null;
+    const dow = (at.getDay() - options.weekStart + DAYS_IN_WEEK) % DAYS_IN_WEEK;
+    return clampIso(move(focus, { ahead: options.rtl ? -1 : 1, dow, shift: !!options.shift }), options.min, options.max);
+}
+
+// ─── words ───────────────────────────────────────────────────────────────────
+
+/** The date in words, in the site's language: "Thu, 20 November" — the year only when it is not this year's. */
+export function formatDateInWords(iso: string, locale: string | null | undefined, today: string): string {
+    const d = dateOfIso(iso);
+    if (!d) return '';
+    const sameYear = iso.slice(0, 4) === today.slice(0, 4);
+    try {
+        return new Intl.DateTimeFormat(locale || undefined, { weekday: 'short', day: 'numeric', month: 'long', ...(sameYear ? {} : { year: 'numeric' }) }).format(d);
+    } catch {
+        return iso;
+    }
+}
+
+/** The calendar's own words, by the site's language — the media-core `videoWords` precedent (a string-rendered
+ *  site has no translation service; the document's `lang` picks). */
+export interface DatePickerWords {
+    choose: string;
+    previousMonth: string;
+    nextMonth: string;
+    close: string;
+}
+
+export const DATE_PICKER_WORDS: Readonly<Record<'en' | 'he', DatePickerWords>> = Object.freeze({
+    en: { choose: 'Choose a date', previousMonth: 'Previous month', nextMonth: 'Next month', close: 'Close' },
+    he: { choose: 'בחרו תאריך', previousMonth: 'החודש הקודם', nextMonth: 'החודש הבא', close: 'סגירה' },
+});
+
+/** The words for a language tag (`he-IL` → Hebrew); English for anything else. */
+export function datePickerWords(lang: string | null | undefined): DatePickerWords {
+    const language = String(lang ?? '').toLowerCase().split(/[-_]/)[0];
+    return language === 'he' || language === 'iw' ? DATE_PICKER_WORDS.he : DATE_PICKER_WORDS.en;
+}

package/src/forms-core/field-markup.ts

@@ -0,0 +1,159 @@
+/**
+ * A Field as MARKUP — the string renderer's copy of `IoxFieldComponent`'s template, in ONE place (it lived in the
+ * engine's `layout-renderer.service.ts`, a second copy beside the component). The engine's string path writes it; the
+ * component mirrors it element for element, so hydration replaces like with like and the shared CSS (iox-forms.css,
+ * the contract's field baseline) reaches both.
+ *
+ * Choices (premium N1): a `<fieldset>` whose `<legend>` is the label, its options native radios (one answer — the
+ * arrow keys move and pick, with no script) or checkboxes (several), each inside a `<label>` that IS the chip; the
+ * input is visually hidden, never removed. Date (N8): a `<button>` that says the date in words and opens the look's
+ * calendar, with a hidden input carrying the ISO day — the raw SSR is the final markup (nothing shifts on hydrate).
+ *
+ * Framework-free, like the rest of forms-core: `escape` is the caller's.
+ */
+
+import { ChoiceAppearance, ControlType } from './form.model';
+import { datePickerWords } from './dates';
+import { fieldOptionsOf } from './options';
+
+/** The classes the markup carries — the runtimes and the shared CSS key on these, never on a literal. */
+export enum FieldClass {
+    Root = 'iox-field',
+    Label = 'iox-field__label',
+    LabelHidden = 'iox-field__label--hidden',
+    Required = 'iox-field__required',
+    Control = 'iox-field__control',
+    Help = 'iox-field__help',
+    Error = 'iox-field__error',
+    Group = 'iox-field__group',
+    Option = 'iox-field__option',
+    Choices = 'iox-field__choices',
+    ChoicesChips = 'iox-field__choices--chips',
+    ChoicesList = 'iox-field__choices--list',
+    Chips = 'iox-field__chips',
+    Chip = 'iox-field__chip',
+    ChipInput = 'iox-field__control--chip',
+    DateButton = 'iox-field__control--date',
+    DateValue = 'iox-field__date-value',
+    DateIcon = 'iox-field__date-icon',
+    DateInput = 'iox-field__date-input',
+}
+
+/** On the date button: the raw Earliest / Latest (`'0'`, an ISO day), resolved by the visitor's own today. */
+export const DATE_MIN_ATTRIBUTE = 'data-iox-date-min';
+export const DATE_MAX_ATTRIBUTE = 'data-iox-date-max';
+/** On the date's words while no day is chosen (the placeholder's colour keys on it). */
+export const DATE_EMPTY_ATTRIBUTE = 'data-iox-empty';
+
+/** The calendar glyph inside the date button: one path set, drawn in currentColor, never announced. */
+export const DATE_ICON_SVG = '<svg class="iox-field__date-icon" width="20" height="20" viewBox="0 0 24 24" aria-hidden="true" focusable="false">' +
+    '<rect x="3.5" y="5" width="17" height="15.5" rx="2.5" fill="none" stroke="currentColor" stroke-width="1.6"/>' +
+    '<path d="M3.5 10h17M8 3v4M16 3v4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>';
+
+/** The controls that are a plain `<input type=…>`; anything else unknown is a text input. */
+const INPUT_TYPES: ReadonlySet<string> = new Set(['email', 'tel', 'url', 'number', 'password', 'time', 'file', 'hidden']);
+
+/** The `<input type>` of a control that renders as a plain input. */
+export function inputTypeOf(control: string): string {
+    return INPUT_TYPES.has(control) ? control : 'text';
+}
+
+/** A Choices field's appearance; anything unknown reads as chips (the default). */
+export function choiceAppearanceOf(props: Record<string, any> | null | undefined): ChoiceAppearance {
+    return props?.['appearance'] === ChoiceAppearance.List ? ChoiceAppearance.List : ChoiceAppearance.Chips;
+}
+
+export interface FieldMarkupOptions {
+    /** The name the field submits under — its FORM's unique name for it (`formFieldNames`, vectoriox/iox-ui#43). */
+    name: string;
+    /** The control's id; the label, help and error ids derive from it. */
+    id: string;
+    /** The node's classes (`iox-node-…`, the element-style marker…). */
+    cls: string;
+    /** Anything else the host element carries, written verbatim (an entrance's style). */
+    attrs?: string;
+    /** The site's language (the date's words). */
+    lang?: string | null;
+    escape: (value: string) => string;
+}
+
+/** A Field's whole element, as the string renderer writes it. */
+export function fieldHtml(props: Record<string, any> | null | undefined, options: FieldMarkupOptions): string {
+    const p = props ?? {};
+    const { name, id, escape: esc } = options;
+    const control = String(p['control'] ?? ControlType.Text);
+    const required = !!p['required'];
+    const help = p['help'] ? `<p class="${FieldClass.Help}" id="${id}-help">${esc(String(p['help']))}</p>` : '';
+    const describedBy = p['help'] ? ` aria-describedby="${id}-help"` : '';
+    const labelClass = p['labelHidden'] ? `${FieldClass.Label} ${FieldClass.LabelHidden}` : FieldClass.Label;
+    const mark = required ? `<span class="${FieldClass.Required}" aria-hidden="true">*</span>` : '';
+    const text = esc(String(p['label'] ?? ''));
+    const label = `<label class="${labelClass}" id="${id}-label" for="${id}">${text}${mark}</label>`;
+    const hidden = control === ControlType.Hidden ? ' hidden' : '';
+    const open = `<div class="${FieldClass.Root} ${options.cls}" data-iox-field="${esc(name)}"${hidden}${options.attrs ?? ''}>`;
+
+    if (control === ControlType.Choices) {
+        return `${open}${choicesHtml(p, options, `<legend class="${labelClass}" id="${id}-label">${text}${mark}</legend>`, describedBy)}${help}</div>`;
+    }
+    return `${open}${label}${controlHtml(p, control, options, describedBy)}${help}</div>`;
+}
+
+function controlHtml(p: Record<string, any>, control: string, options: FieldMarkupOptions, describedBy: string): string {
+    const { id, escape: esc } = options;
+    const name = esc(options.name);
+    const required = p['required'] ? ' required' : '';
+    const placeholder = p['placeholder'] ? ` placeholder="${esc(String(p['placeholder']))}"` : '';
+    const choices = fieldOptionsOf(p);
+    const option = (o: { value: string; label: string }) => `<option value="${esc(o.value)}">${esc(o.label)}</option>`;
+    const num = (v: unknown, d: number) => (Number.isFinite(Number(v)) && v !== '' && v !== null ? Number(v) : d);
+
+    switch (control) {
+        case ControlType.Textarea:
+            return `<textarea class="${FieldClass.Control}" id="${id}" name="${name}" rows="${num(p['rows'], 4)}"${placeholder}${required}${describedBy}></textarea>`;
+        case ControlType.Select:
+            return `<select class="${FieldClass.Control}" id="${id}" name="${name}"${required}${describedBy}>` +
+                `<option value="">${esc(String(p['placeholder'] ?? ''))}</option>${choices.map(option).join('')}</select>`;
+        case ControlType.Switch:
+            return `<input class="${FieldClass.Control} iox-field__control--switch" type="checkbox" role="switch" id="${id}" name="${name}"${describedBy}>`;
+        case ControlType.Range:
+            return `<input class="${FieldClass.Control} iox-field__control--range" type="range" id="${id}" name="${name}" ` +
+                `min="${num(p['rangeMin'], 0)}" max="${num(p['rangeMax'], 100)}" step="${num(p['rangeStep'], 1)}"${describedBy}>`;
+        case ControlType.Radio:
+            return `<div class="${FieldClass.Group}" role="radiogroup" aria-labelledby="${id}-label">` +
+                choices.map(o => `<label class="${FieldClass.Option}"><input class="${FieldClass.Control} iox-field__control--radio" type="radio" name="${name}" ` +
+                    `value="${esc(o.value)}"><span>${esc(o.label)}</span></label>`).join('') + `</div>`;
+        case ControlType.Checkbox:
+            return `<input class="${FieldClass.Control} iox-field__control--checkbox" type="checkbox" id="${id}" name="${name}"${required}${describedBy}>`;
+        case ControlType.Date:
+            return dateHtml(p, options, describedBy);
+        default:
+            return `<input class="${FieldClass.Control}" id="${id}" name="${name}" type="${inputTypeOf(control)}"${placeholder}${required}${describedBy}>`;
+    }
+}
+
+/** A Choices field's fieldset: the legend, then the options as chips or as a list. */
+function choicesHtml(p: Record<string, any>, options: FieldMarkupOptions, legend: string, describedBy: string): string {
+    const { escape: esc } = options;
+    const name = esc(options.name);
+    const multiple = p['multiple'] === true;
+    const type = multiple ? 'checkbox' : 'radio';
+    const chips = choiceAppearanceOf(p) === ChoiceAppearance.Chips;
+    const items = fieldOptionsOf(p).map(o => chips
+        ? `<label class="${FieldClass.Chip}"><input class="${FieldClass.Control} ${FieldClass.ChipInput}" type="${type}" name="${name}" value="${esc(o.value)}"><span>${esc(o.label)}</span></label>`
+        : `<label class="${FieldClass.Option}"><input class="${FieldClass.Control}" type="${type}" name="${name}" value="${esc(o.value)}"><span>${esc(o.label)}</span></label>`).join('');
+    const look = chips ? FieldClass.ChoicesChips : FieldClass.ChoicesList;
+    const row = chips ? FieldClass.Chips : FieldClass.Group;
+    return `<fieldset class="${FieldClass.Choices} ${look}"${describedBy}>${legend}<div class="${row}">${items}</div></fieldset>`;
+}
+
+/** The date picker's button + hidden input. The calendar itself is the runtime's, opened on press. */
+function dateHtml(p: Record<string, any>, options: FieldMarkupOptions, describedBy: string): string {
+    const { id, escape: esc } = options;
+    const words = datePickerWords(options.lang);
+    const empty = esc(String(p['placeholder'] || words.choose));
+    const bound = (attr: string, raw: unknown) => (typeof raw === 'string' && raw.trim() !== '') || typeof raw === 'number' ? ` ${attr}="${esc(String(raw).trim())}"` : '';
+    return `<button type="button" class="${FieldClass.Control} ${FieldClass.DateButton}" id="${id}" aria-haspopup="dialog" aria-expanded="false" ` +
+        `aria-labelledby="${id}-label ${id}-value"${describedBy}${bound(DATE_MIN_ATTRIBUTE, p['earliest'])}${bound(DATE_MAX_ATTRIBUTE, p['latest'])}>` +
+        `<span class="${FieldClass.DateValue}" id="${id}-value" ${DATE_EMPTY_ATTRIBUTE}>${empty}</span>${DATE_ICON_SVG}</button>` +
+        `<input type="hidden" class="${FieldClass.DateInput}" name="${esc(options.name)}" value="">`;
+}

package/src/forms-core/form-presets.ts

@@ -6,11 +6,16 @@
  * Data only: framework-free, like the rest of forms-core.
  */
 
+import type { ChannelKind } from './channel';
+
 export enum FormPresetId {
     Contact = 'contact',
     Newsletter = 'newsletter',
     Application = 'application',
     Booking = 'booking',
+    /** Premium N2: modelled on Doron's iox.studio brief — name, a phone that is also WhatsApp, the business, what they
+     *  need and a budget as chips, Send with WhatsApp beside it. */
+    Lead = 'lead',
 }
 
 export interface FormPresetField {
@@ -19,9 +24,22 @@ export interface FormPresetField {
     required?: boolean;
     help?: string;
     placeholder?: string;
-    /** Choices for select/radio, `value|Label` per line — the Field's `optionsText` trait. */
+    /** Choices for select/radio/choices, `value|Label` per line — the Field's `optionsText` trait. */
     optionsText?: string;
     rows?: number;
+    /** A Choices field that takes several answers (N1). */
+    multiple?: boolean;
+    /** A Choices field's appearance — `chips` (the default) or `list` (N1). */
+    appearance?: string;
+    /** A Date's first and last day — '' any · an integer: days from today · an ISO day (N8, `dates.ts`). */
+    earliest?: string;
+    latest?: string;
+}
+
+/** The second way to reach the studio, beside Send (N2). Its address is the studio's own and starts EMPTY. */
+export interface FormPresetChannel {
+    kind: `${ChannelKind}`;
+    label: string;
 }
 
 export interface FormPresetDef {
@@ -36,6 +54,15 @@ export interface FormPresetDef {
     submitLabel: string;
     successText: string;
     errorText: string;
+    channel?: FormPresetChannel;
+    /** `false`: the AI plan wire does not offer it yet (the lead preset ships in the builder in M3; generation takes it
+     *  up in premium M8 — the wire's enum is model-facing and does not change before then). */
+    inPlan?: false;
+}
+
+/** The presets a generated plan may name (the plan wire's `form` enum) — every preset not held back by `inPlan`. */
+export function planFormPresetIds(): string[] {
+    return FORM_PRESETS.filter(p => p.inPlan !== false).map(p => p.id);
 }
 
 // forms-core is imported by both renderers (the field runtime), and a renderer that never reads the presets
@@ -93,7 +120,8 @@ export const FORM_PRESETS: readonly FormPresetDef[] = /* @__PURE__ */ Object.fre
         fields: [
             { label: 'Name', control: 'text', required: true },
             { label: 'Email', control: 'email', required: true },
-            { label: 'Date', control: 'date', required: true },
+            // The first day a booking may ask for is today (N8): the calendar refuses the past.
+            { label: 'Date', control: 'date', required: true, earliest: '0' },
             { label: 'People', control: 'number', required: true },
             { label: 'Notes', control: 'textarea', rows: 3, help: 'Allergies, access needs, anything useful' },
         ],
@@ -101,6 +129,27 @@ export const FORM_PRESETS: readonly FormPresetDef[] = /* @__PURE__ */ Object.fre
         successText: 'Request received — we’ll confirm by email.',
         errorText: 'We couldn’t send your request. Please try again.',
     },
+    {
+        id: 'lead', name: 'Lead', icon: 'ph-thin ph-handshake',
+        description: 'Name, phone, the business and what they need, as chips. Stored, with WhatsApp beside Send.',
+        formName: 'Lead form',
+        fields: [
+            { label: 'Name', control: 'text', required: true },
+            { label: 'Phone / WhatsApp', control: 'tel', required: true },
+            { label: 'What is your business?', control: 'text' },
+            // The words ARE the values: what arrives in the inbox and the email reads as the visitor chose it.
+            { label: 'What do you need?', control: 'choices', multiple: true,
+                optionsText: 'Website\nBranding\nPhotos & video\nNot sure yet' },
+            // Neutral sizes the author renames — never a price or a currency a studio could be held to.
+            { label: 'Estimated budget', control: 'choices',
+                optionsText: 'Small project\nMedium\nLarge\nNot sure yet' },
+        ],
+        submitLabel: 'Send',
+        successText: 'Thanks — we’ll get back to you soon.',
+        errorText: 'We couldn’t send your details. Please try again — your answers are still here.',
+        channel: { kind: 'whatsapp', label: 'Message us on WhatsApp' },
+        inPlan: false,
+    },
 ]);
 
 /** The preset with this id, or undefined. */

package/src/forms-core/form.model.ts

@@ -21,6 +21,11 @@ export enum ControlType {
     /** A slider over a numeric range — min/max/step ride the field. */
     Range = 'range',
     Radio = 'radio',
+    /** One or several of a few visible choices — chips (the default) or a list of radios / checkboxes (premium N1).
+     *  Its `multiple` trait picks the value's shape: a string, or a list of strings. */
+    Choices = 'choices',
+    /** A date the visitor picks from the look's calendar (premium N8) — a button that reads the date in words and a
+     *  hidden input carrying the ISO `YYYY-MM-DD` value. Never the browser's own date box. */
     Date = 'date',
     Time = 'time',
     File = 'file',
@@ -42,6 +47,19 @@ export enum RuleName {
     Accepted = 'accepted',
     FileType = 'fileType',
     FileSize = 'fileSize',
+    /** IMPLIED, never authored: an answer of a Choices / Radio / Dropdown must be one of the field's own options
+     *  (premium N1) — a hand-crafted POST cannot file a value the form never offered. */
+    OneOf = 'oneOf',
+    /** IMPLIED, never authored: a Date's answer is a real `YYYY-MM-DD` day (premium N8). */
+    ValidDate = 'validDate',
+}
+
+/** How a Choices field draws its options (premium N1). */
+export enum ChoiceAppearance {
+    /** Each option a chip — the label is the chip; the native input inside it is visually hidden. */
+    Chips = 'chips',
+    /** The options as rows of the look's own radio / checkbox (DS9.1). */
+    List = 'list',
 }
 
 /** Named regexes so an author picks "Email" rather than writing one. */
@@ -100,6 +118,8 @@ export interface FieldSpec {
     options?: FieldOption[];
     optionsSource?: FieldOptionSource;
     defaultValue?: any;
+    /** A Choices field that takes several answers: its value is a list (premium N1). */
+    multiple?: boolean;
 }
 
 /** When a field is validated, once the author has stopped deciding it per field. */
@@ -139,5 +159,17 @@ export const IMPLIED_PATTERN: Readonly<Partial<Record<ControlType, PatternPreset
     [ControlType.Url]: PatternPreset.Url,
 });
 
-/** Controls whose value is a list rather than a scalar. */
-export const MULTI_VALUE_CONTROLS: ReadonlySet<ControlType> = new Set([ControlType.File]);
+/**
+ * Whether this field's answer is a LIST rather than one value — a file list, or a Choices field that takes several
+ * (premium N1). Per FIELD, not per control: the same Choices control is single or multiple by its `multiple` trait.
+ * ONE reading for collect, validate, the runtimes' transport and the server (replaced the control-only
+ * `MULTI_VALUE_CONTROLS`, which nothing read).
+ */
+export function isMultiValueField(field: Pick<FieldSpec, 'control' | 'multiple'> | null | undefined): boolean {
+    if (!field) return false;
+    if (field.control === ControlType.File) return true;
+    return field.control === ControlType.Choices && field.multiple === true;
+}
+
+/** The controls whose answers must be one of the field's own options (the implied `oneOf` rule). */
+export const OPTION_CONTROLS: ReadonlySet<ControlType> = new Set([ControlType.Choices, ControlType.Radio, ControlType.Select]);

package/src/forms-core/messages.ts

@@ -31,6 +31,29 @@ export const RULE_MESSAGE_KEYS: Readonly<Record<RuleName, string>> = Object.free
     [RuleName.Accepted]:  `${MESSAGE_NAMESPACE}.accepted`,
     [RuleName.FileType]:  `${MESSAGE_NAMESPACE}.fileType`,
     [RuleName.FileSize]:  `${MESSAGE_NAMESPACE}.fileSize`,
+    [RuleName.OneOf]:     `${MESSAGE_NAMESPACE}.oneOf`,
+    [RuleName.ValidDate]: `${MESSAGE_NAMESPACE}.validDate`,
+});
+
+/**
+ * What "required" says on a field you CHOOSE rather than type into (premium N1 / N8): "Choose an option", "Choose at
+ * least one", "Choose a date" — never "This field is required" beside a row of chips.
+ */
+export const CHOICE_MESSAGE_KEYS = Object.freeze({
+    One: `${MESSAGE_NAMESPACE}.choose`,
+    Some: `${MESSAGE_NAMESPACE}.chooseSome`,
+    Date: `${MESSAGE_NAMESPACE}.chooseDate`,
+});
+
+/** A Date outside its Earliest / Latest. The calendar refuses those days, so this is a stale page or a hand POST. */
+export const DATE_MESSAGE_KEYS = Object.freeze({
+    Min: `${MESSAGE_NAMESPACE}.dateMin`,
+    Max: `${MESSAGE_NAMESPACE}.dateMax`,
+});
+
+/** The submit button's own words (premium N2): what it says once its form has sent, when the author wrote none. */
+export const SUBMIT_MESSAGE_KEYS = Object.freeze({
+    Sent: 'forms.submit.sent',
 });
 
 /**
@@ -79,4 +102,12 @@ export const DEFAULT_EN_MESSAGES: Readonly<Record<string, string>> = Object.free
     [FORM_ERROR_KEYS.Spam]:        'We couldn’t accept this submission',
     [FORM_ERROR_KEYS.RateLimited]: 'Too many attempts — please wait a moment and try again',
     [FORM_ERROR_KEYS.Server]:      'Something went wrong on our side — your answers are still here',
+    [RULE_MESSAGE_KEYS[RuleName.OneOf]]:     'Choose one of the options',
+    [RULE_MESSAGE_KEYS[RuleName.ValidDate]]: 'Choose a date from the calendar',
+    [CHOICE_MESSAGE_KEYS.One]:  'Choose an option',
+    [CHOICE_MESSAGE_KEYS.Some]: 'Choose at least one',
+    [CHOICE_MESSAGE_KEYS.Date]: 'Choose a date',
+    [DATE_MESSAGE_KEYS.Min]:    'Choose a later date',
+    [DATE_MESSAGE_KEYS.Max]:    'Choose an earlier date',
+    [SUBMIT_MESSAGE_KEYS.Sent]: 'Sent',
 });

package/src/forms-core/public-api.ts

@@ -21,3 +21,6 @@ export * from './transport';
 export * from './submit-lifecycle';
 export * from './form-presets';
 export * from './nesting';
+export * from './dates';
+export * from './channel';
+export * from './field-markup';