@swiftbrowser/web 0.26.3 → 0.26.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.26.3",
+  "version": "0.26.4",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/layout/engine.ts

@@ -120,6 +120,12 @@ export interface Context {
    * bar, `actions`, when the sheet has one.
    */
   macSheet?: { actions: Rect | null };
+  /**
+   * The Mac idiom: a row of a form in the columns style. A control whose
+   * label went to the label column (a stepper's, a date picker's, a
+   * picker's) draws without it, at the row's leading edge.
+   */
+  formColumn?: boolean;
   /**
    * Phase 8: the y (screen coordinates) where content clears the bars above
    * it: the top safe area at the root, the bottom of a `navscreen`'s bar (and
@@ -392,6 +398,21 @@ const MAC_LIST_HEADER_TOP = 4;
 const MAC_LIST_HEADER_GAP = 9;
 const MAC_LIST_FIRST_ROWS_GAP = 10;
 const MAC_LIST_FOOTER_GAP = 8;
+// A Mac's Form (measured in the Mac app): the columns style, with no
+// insets of its own and centered vertically in the room it gets. The labels
+// (13) right-aligned in a column as wide as the widest, from the leading
+// edge; the controls in a column 10 after it that runs to the trailing
+// edge; a section header and a footer (13 regular, the label color) in the
+// controls column; 8 under a header, rows 7 apart, sections touching, a
+// header 4 under the rows before it (right under a footer), a footer 2
+// under the last row.
+const MAC_FORM_LABEL_GAP = 10;
+const MAC_FORM_HEADER_GAP = 8;
+const MAC_FORM_HEADER_TOP = 4;
+const MAC_FORM_ROW_GAP = 7;
+const MAC_FORM_FOOTER_GAP = 2;
+/** The row kinds whose label goes in a Mac form's label column (a stack with one is shifted to it). */
+const MAC_FORM_LABELED_KINDS = ['textfield', 'picker', 'stepper', 'datepicker', 'slider'];
 /** Under a Mac footer: 5 to its rule, the rule. */
 const MAC_LIST_FOOTER_BOTTOM = 6;
 const MAC_NAVSPLIT_SIDEBAR_WIDTH = 220;
@@ -1449,10 +1470,24 @@ interface ListGroupPlan {
   outlines: { group: LayoutNode; frame: Rect }[];
 }
 
+/** A Mac form's label column entry: text the page draws (`layout`), or a view (`node`) placed at the rect. */
+interface FormLabelPlan {
+  /** Relative to the list origin at scroll 0; a view's rect is its own size, at the column's trailing edge. */
+  rect: Rect;
+  layout: TextLayout | null;
+  node: LayoutNode | null;
+  ctx: Context;
+}
+
 interface ListPlan {
   size: Size;
   contentSize: Size;
   groups: ListGroupPlan[];
+  /** The Mac idiom's columns form: its label column's entries. */
+  labels?: FormLabelPlan[];
+  columns?: boolean;
+  /** The columns form's controls column: where it starts (relative to the list origin) and its width. */
+  column?: { x: number; width: number };
 }
 
 interface ScrollPlan {
@@ -2549,8 +2584,8 @@ export class LayoutPass {
         const font = mac ? makeFont('system', MAC_SEGMENTED_FONT_SIZE, 400) : makeFont('system', PICKER_SEGMENT_FONT_SIZE, 600);
         let natural = 0;
         for (const option of options) natural += this.measurer.measureWidth(option, font) + PICKER_SEGMENT_PAD;
-        // A Mac shows the picker's label before the control.
-        const labelText = mac ? (str(node.props['label']) ?? '') : '';
+        // A Mac shows the picker's label before the control (in a form's row it is in the label column).
+        const labelText = mac && !ctx.formColumn ? (str(node.props['label']) ?? '') : '';
         const labelWidth = labelText.length > 0 && !ctx.navBarItem ? this.measurer.measureWidth(labelText, ctx.font) + MAC_SEGMENTED_LABEL_GAP : 0;
         return {
           size: { width: finite(p.width) ? p.width : natural + labelWidth, height: mac ? MAC_SEGMENTED_HEIGHT : PICKER_SEGMENTED_HEIGHT },
@@ -2564,17 +2599,18 @@ export class LayoutPass {
         };
       }
       const font = ctx.font;
-      const labelWidth = this.measurer.measureWidth(str(node.props['label']) ?? '', font);
+      // In a Mac form's row the label is in the label column and the pop-up spans the controls column.
+      const labelWidth = ctx.formColumn ? 0 : this.measurer.measureWidth(str(node.props['label']) ?? '', font);
       const value = options[selected] ?? '';
       const mac = this.env.platform === 'macos';
       // The Mac's pop-up button holds the value and the chevrons in a bordered button.
-      const popup = mac && !ctx.listRow;
-      const valueWidth = this.measurer.measureWidth(value, font) + PICKER_MENU_CHEVRON_WIDTH + (popup ? 2 * MAC_PICKER_POPUP_PAD : 0);
+      const popup = mac && (!ctx.listRow || ctx.formColumn === true);
+      const valueWidth = ctx.formColumn && finite(p.width) ? p.width : this.measurer.measureWidth(value, font) + PICKER_MENU_CHEVRON_WIDTH + (popup ? 2 * MAC_PICKER_POPUP_PAD : 0);
       const natural = labelWidth + PICKER_MENU_GAP + valueWidth;
       return {
         size: {
           width: finite(p.width) ? p.width : natural,
-          height: ctx.listRow ? (mac ? MAC_PICKER_MENU_ROW_HEIGHT : PICKER_MENU_ROW_HEIGHT) : mac ? MAC_PICKER_MENU_HEIGHT : PICKER_MENU_HEIGHT,
+          height: ctx.listRow && !ctx.formColumn ? (mac ? MAC_PICKER_MENU_ROW_HEIGHT : PICKER_MENU_ROW_HEIGHT) : mac ? MAC_PICKER_MENU_HEIGHT : PICKER_MENU_HEIGHT,
         },
         style: 'menu',
         font,
@@ -2635,7 +2671,8 @@ export class LayoutPass {
       const room = Math.max(0, size.width - PICKER_MENU_GAP);
       let labelWidth = plan.labelWidth;
       let valueWidth = plan.valueWidth;
-      if (labelWidth + valueWidth > room) {
+      // In a Mac form's controls column the pop-up spans the column (its label is in the label column).
+      if (!ctx.formColumn && labelWidth + valueWidth > room) {
         if (labelWidth <= valueWidth) {
           labelWidth = Math.min(labelWidth, room / 2);
           valueWidth = room - labelWidth;
@@ -2648,7 +2685,7 @@ export class LayoutPass {
       chrome['label'] = { x, y, width: labelWidth, height: size.height };
       chrome['value'] = { x: x + size.width - valueWidth, y, width: valueWidth, height: size.height };
       // The page draws the Mac's pop-up button around the value (the engine padded it).
-      if (this.env.platform === 'macos' && !ctx.listRow) chrome['popup'] = chrome['value'];
+      if (this.env.platform === 'macos' && (!ctx.listRow || ctx.formColumn === true)) chrome['popup'] = chrome['value'];
       else delete chrome['popup'];
     }
     this.setChrome(node, chrome);
@@ -3161,6 +3198,7 @@ export class LayoutPass {
 
   private listPlan(node: LayoutNode, ctx: Context, p: Proposal): ListPlan {
     return this.plan(node, ctx, p, () => {
+      if (this.env.platform === 'macos' && node.props['form'] === true) return this.macFormPlan(node, ctx, p);
       const { screen } = this.env;
       const width = finite(p.width) ? p.width : p.width === Infinity ? Infinity : screen.width;
       const layoutWidth = Number.isFinite(width) ? width : screen.width;
@@ -3915,9 +3953,198 @@ export class LayoutPass {
     return { p: { width: p.width, height: size.height + top + bottom }, y: y - top };
   }
 
+  /** The labeled control a form row's stack is shifted to (the form's alignment guide), if it has one. */
+  private macFormGuide(row: LayoutNode): LayoutNode | null {
+    const inner = unwrapStyled(row);
+    if (inner.kind !== 'hstack') return null;
+    return inner.children.find((child) => MAC_FORM_LABELED_KINDS.includes(unwrapStyled(child).kind)) ?? null;
+  }
+
+  /**
+   * The Mac idiom's `Form` (MAC_FORM_* above, docs/notes/macos.md): the
+   * columns style. A row whose control carries a label (a text field's
+   * title, a picker's, a stepper's, a date picker's, a slider's) puts it
+   * in the label column, right-aligned, and the control in the controls
+   * column at the control's own height; a toggle, a button, text and other
+   * rows go in the controls column whole. A stack row with such a control
+   * in it is shifted so the control starts at the controls column, what is
+   * before it reaching into the label column, as the form's alignment guide
+   * does on a Mac. Headers and footers are 13-point text in the controls
+   * column. No cards, no separators.
+   */
+  private macFormPlan(node: LayoutNode, ctx: Context, p: Proposal): ListPlan {
+    const { screen } = this.env;
+    const width = finite(p.width) ? p.width : p.width === Infinity ? Infinity : screen.width;
+    const layoutWidth = Number.isFinite(width) ? width : screen.width;
+    const rowCtx: Context = { ...this.childContext(node, ctx), listRow: true, labelColumn: false, listCell: true, formColumn: true, sidebarList: false };
+    const font = rowCtx.font;
+    const textFont = makeFont('system', textStyleSize('body', this.env.dynamicTypeSize, 'macos'), 400);
+    type Row = { node: LayoutNode; label: string | null; labelNode: LayoutNode | null; guide: LayoutNode | null };
+    type Source = { section: LayoutNode | null; rows: Row[]; headerView: LayoutNode | null; footerView: LayoutNode | null };
+    // The rows, each with what goes in the label column.
+    const classify = (row: LayoutNode): Row => {
+      const inner = unwrapStyled(row);
+      switch (inner.kind) {
+        case 'textfield':
+          return { node: row, label: str(inner.props['placeholder']) || null, labelNode: null, guide: null };
+        case 'picker':
+          return { node: row, label: str(inner.props['label']) || null, labelNode: null, guide: null };
+        case 'stepper':
+        case 'datepicker':
+          return { node: row, label: null, labelNode: inner.props['labelsHidden'] === true ? null : this.contentOf(inner), guide: null };
+        case 'slider': {
+          const names = Array.isArray(inner.props['labels']) ? inner.props['labels'].map(str) : [];
+          const at = names.indexOf('label');
+          return { node: row, label: null, labelNode: at >= 0 ? (inner.children[at] ?? null) : null, guide: null };
+        }
+        default:
+          return { node: row, label: null, labelNode: null, guide: this.macFormGuide(row) };
+      }
+    };
+    const sources: Source[] = [];
+    for (const child of node.children) {
+      if (child.kind === 'section') {
+        const rows = child.children.filter((row) => row.kind !== 'sectionheader' && row.kind !== 'sectionfooter').map(classify);
+        sources.push({ section: child, rows, headerView: child.children.find((row) => row.kind === 'sectionheader') ?? null, footerView: child.children.find((row) => row.kind === 'sectionfooter') ?? null });
+      } else {
+        const last = sources[sources.length - 1];
+        if (last && last.section === null) last.rows.push(classify(child));
+        else sources.push({ section: null, rows: [classify(child)], headerView: null, footerView: null });
+      }
+    }
+    // The label column: as wide as the widest label (a view label at its ideal size).
+    const labelCtx: Context = { ...this.childContext(node, ctx), stackAxis: null, listRow: false, listCell: true };
+    let labelWidth = 0;
+    const labelSizes = new Map<LayoutNode, Size>();
+    for (const source of sources) {
+      for (const row of source.rows) {
+        if (row.label !== null) labelWidth = Math.max(labelWidth, this.measurer.measureWidth(row.label, font));
+        else if (row.labelNode) {
+          const size = this.measure(row.labelNode, labelCtx, { width: null, height: null });
+          labelSizes.set(row.labelNode, size);
+          labelWidth = Math.max(labelWidth, size.width);
+        }
+      }
+    }
+    labelWidth = Math.ceil(labelWidth);
+    const controlX = labelWidth + MAC_FORM_LABEL_GAP;
+    const controlWidth = Math.max(0, layoutWidth - controlX);
+    const textCtx: Context = { ...labelCtx, font: textFont };
+    const makeText = (text: string): { layout: TextLayout; size: Size } => {
+      const wrapped = wrapText(text, textFont, controlWidth, null, this.measurer);
+      return { layout: { font: textFont, lines: wrapped.lines, alignment: 'leading', truncated: false }, size: { width: wrapped.width, height: textHeight(wrapped.lines.length, textFont) } };
+    };
+    const supplement = (view: LayoutNode | null, y: number): ListSupplementPlan | null => {
+      if (!view) return null;
+      const proposal: Proposal = { width: controlWidth, height: null };
+      const size = this.measure(view, textCtx, proposal);
+      return { node: view, ctx: textCtx, proposal, rect: { x: controlX, y, width: size.width, height: size.height } };
+    };
+    // Built from a top, then again centered in the room when the rows are shorter than it.
+    const build = (startY: number): { groups: ListGroupPlan[]; labels: FormLabelPlan[]; end: number } => {
+    const groups: ListGroupPlan[] = [];
+    const labels: FormLabelPlan[] = [];
+    let y = startY;
+    for (let g = 0; g < sources.length; g++) {
+      const source = sources[g] as Source;
+      const previous = groups[g - 1];
+      const headerText = source.section ? str(source.section.props['header']) : null;
+      const footerText = source.section ? str(source.section.props['footer']) : null;
+      const hasHeader = (headerText !== null && headerText.length > 0) || (source.headerView !== null && this.measure(source.headerView, textCtx, { width: controlWidth, height: null }).height > 0);
+      // A header after rows is 4 under them; right under a footer.
+      if (previous && hasHeader && previous.footer === null && !(previous.footerView !== null && previous.footerView.rect.height > 0)) y += MAC_FORM_HEADER_TOP;
+      const top = y;
+      let header: ListGroupPlan['header'] = null;
+      let footer: ListGroupPlan['footer'] = null;
+      const headerView = supplement(source.headerView, y);
+      if (headerView && headerView.rect.height > 0) y += headerView.rect.height + MAC_FORM_HEADER_GAP;
+      if (headerText !== null && headerText.length > 0) {
+        const { layout, size } = makeText(headerText);
+        header = { rect: { x: controlX, y, width: controlWidth, height: size.height }, layout };
+        y += size.height + MAC_FORM_HEADER_GAP;
+      }
+      const cardTop = y;
+      const rows: ListRowPlan[] = [];
+      source.rows.forEach((row, i) => {
+        if (i > 0) y += MAC_FORM_ROW_GAP;
+        if (row.node.kind === 'lazyspacer') {
+          const rect: Rect = { x: controlX, y, width: controlWidth, height: 0 };
+          rows.push({ node: row.node, proposal: { width: controlWidth, height: 0 }, contentSize: ZERO, row: rect, content: rect, badge: null, edit: null });
+          return;
+        }
+        // A shifted stack is proposed the whole row less the trailing inset; its place is set when the list is placed.
+        // A shifted stack is proposed the whole row; its place and width are set when the list is placed.
+        const proposal: Proposal = { width: row.guide ? layoutWidth : controlWidth, height: null };
+        const contentSize = this.measure(row.node, rowCtx, proposal);
+        const labelSize = row.labelNode ? labelSizes.get(row.labelNode) ?? ZERO : row.label !== null ? { width: this.measurer.measureWidth(row.label, font), height: font.lineHeight } : ZERO;
+        const rowHeight = Math.max(contentSize.height, labelSize.height);
+        // A text field's row is the field itself (the page draws the Mac's bezel on the row element); the others span the form.
+        const field = unwrapStyled(row.node).kind === 'textfield';
+        rows.push({
+          node: row.node,
+          proposal,
+          contentSize,
+          row: field ? { x: controlX, y, width: controlWidth, height: rowHeight } : { x: 0, y, width: layoutWidth, height: rowHeight },
+          content: { x: row.guide ? 0 : controlX, y: y + (rowHeight - contentSize.height) / 2, width: contentSize.width, height: contentSize.height },
+          badge: null,
+          edit: null,
+          separatorHidden: { top: true, bottom: true },
+        });
+        if (row.label !== null) {
+          labels.push({
+            rect: { x: 0, y: y + (rowHeight - labelSize.height) / 2, width: labelWidth, height: labelSize.height },
+            layout: { font, lines: [row.label], alignment: 'trailing', truncated: false },
+            node: null,
+            ctx: labelCtx,
+          });
+        } else if (row.labelNode) {
+          labels.push({
+            rect: { x: labelWidth - labelSize.width, y: y + (rowHeight - labelSize.height) / 2, width: labelSize.width, height: labelSize.height },
+            layout: null,
+            node: row.labelNode,
+            ctx: labelCtx,
+          });
+        }
+        y += rowHeight;
+      });
+      // The rows' card spans the form: the label column is drawn in it too.
+      const card: Rect = { x: 0, y: cardTop, width: layoutWidth, height: y - cardTop };
+      if (footerText !== null && footerText.length > 0) {
+        y += MAC_FORM_FOOTER_GAP;
+        const { layout, size } = makeText(footerText);
+        footer = { rect: { x: controlX, y, width: controlWidth, height: size.height }, layout };
+        y += size.height;
+      }
+      let footerView = supplement(source.footerView, y + MAC_FORM_FOOTER_GAP);
+      if (footerView && footerView.rect.height > 0) y += MAC_FORM_FOOTER_GAP + footerView.rect.height;
+      else if (footerView) footerView = { ...footerView, rect: { ...footerView.rect, y } };
+      groups.push({ section: source.section, frame: { x: 0, y: top, width: layoutWidth, height: y - top }, header, footer, headerView, footerView, card, rows, outlines: [] });
+    }
+    return { groups, labels, end: y };
+    };
+    let built = build(0);
+    // Centered in the room under the bar when shorter than it (the Mac's columns form does not scroll).
+    const scrollInset = this.scrollInsets.get(node);
+    const inset = scrollInset ? scrollInset.bar + (scrollInset.largeTitle?.height ?? 0) + (scrollInset.search ?? 0) : 0;
+    const room = finite(p.height) ? p.height - inset : null;
+    if (room !== null && room > built.end) built = build((room - built.end) / 2);
+    const contentHeight = built.end;
+    return {
+      size: { width, height: p.height === null ? contentHeight : p.height },
+      contentSize: { width: layoutWidth, height: contentHeight },
+      groups: built.groups,
+      labels: built.labels,
+      columns: true,
+      column: { x: controlX, width: controlWidth },
+    };
+  }
+
   private placeList(node: LayoutNode, ctx: Context, p: Proposal, x: number, y: number): void {
     const plan = this.listPlan(node, ctx, p);
-    const rowCtx: Context = { ...this.childContext(node, ctx), listRow: true, labelColumn: this.env.platform !== 'macos', listCell: this.env.platform === 'macos', sidebarList: str(node.props['style']) === 'sidebar' };
+    const columns = plan.columns === true;
+    const rowCtx: Context = columns
+      ? { ...this.childContext(node, ctx), listRow: true, labelColumn: false, listCell: true, formColumn: true, sidebarList: false }
+      : { ...this.childContext(node, ctx), listRow: true, labelColumn: this.env.platform !== 'macos', listCell: this.env.platform === 'macos', sidebarList: str(node.props['style']) === 'sidebar' };
     const mac = this.env.platform === 'macos';
     const cellPadding = mac ? MAC_LIST_CELL_PADDING : LIST_CELL_PADDING;
     const covered = this.coveredBottom(ctx, x, y, plan.size);
@@ -3925,14 +4152,27 @@ export class LayoutPass {
     // rows start below them.
     const scrollInset = this.scrollInsets.get(node);
     const listChrome: Record<string, Rect> = {};
+    const listTexts: Record<string, TextLayout> = {};
     if (covered) listChrome['bottomInset'] = covered;
     if (scrollInset) listChrome['topInset'] = { x, y, width: plan.size.width, height: scrollInset.bar };
     if (scrollInset?.largeTitle) listChrome['largeTitle'] = scrollInset.largeTitle;
-    if (Object.keys(listChrome).length > 0) this.setChrome(node, listChrome);
     const inset = scrollInset ? scrollInset.bar + (scrollInset.largeTitle?.height ?? 0) + (scrollInset.search ?? 0) : 0;
     if (node.id >= 0) this.contentSizes.set(node.id, { width: plan.contentSize.width, height: plan.contentSize.height + inset });
     y += inset;
     const offset = (r: Rect): Rect => ({ x: x + r.x, y: y + r.y, width: r.width, height: r.height });
+    // The Mac idiom's columns form: the label column (chrome `formLabel<i>`
+    // with its text, or a view placed there) and the flag for the page.
+    if (columns) {
+      listChrome['columns'] = { x, y, width: plan.size.width, height: plan.size.height };
+      (plan.labels ?? []).forEach((label, i) => {
+        if (label.layout) {
+          listChrome[`formLabel${i}`] = offset(label.rect);
+          listTexts[`formLabel${i}`] = label.layout;
+        }
+      });
+    }
+    if (Object.keys(listChrome).length > 0) this.setChrome(node, listChrome);
+    if (node.id >= 0 && Object.keys(listTexts).length > 0) this.chromeText.set(node.id, listTexts);
     for (const group of plan.groups) {
       if (group.section) {
         const chrome: Record<string, Rect> = { rows: offset(group.card) };
@@ -4004,15 +4244,31 @@ export class LayoutPass {
           if (row.edit.listRow === row.node) Object.assign(chrome, controls);
           else this.setChrome(row.edit.listRow, controls);
         }
-        const rowX = x + row.content.x;
+        let rowX = x + row.content.x;
         const rowY = y + row.content.y;
+        // A columns form's shifted stack: placed, then moved so its labeled
+        // control starts at the controls column (the form's alignment guide).
+        // Placed once to find the control's offset in it, then proposed the
+        // width that ends it at the trailing edge, from where the control
+        // lands at the column.
+        const guide = columns ? this.macFormGuide(row.node) : null;
+        let proposal = row.proposal;
+        if (guide && plan.column) {
+          this.place(row.node, rowCtx, row.proposal, rowX, rowY);
+          const placed = this.frames.get(unwrapStyled(guide).id);
+          if (placed) {
+            const offset = placed.x - rowX;
+            rowX = x + plan.column.x - offset;
+            proposal = { width: Math.max(0, plan.size.width - (plan.column.x - offset)), height: row.proposal.height };
+          }
+        }
         // A row that is skipped keeps the chrome it set itself when it was
         // placed (a link's chevron and label); only the list's keys are new.
-        const own = this.placedAlready(row.node, rowCtx, row.proposal, rowX, rowY) && row.node.id >= 0
+        const own = this.placedAlready(row.node, rowCtx, proposal, rowX, rowY) && row.node.id >= 0
           ? this.chrome.get(row.node.id)
           : undefined;
         this.setChrome(row.node, own ? { ...own, ...chrome } : chrome);
-        this.place(row.node, rowCtx, row.proposal, rowX, rowY);
+        this.place(row.node, rowCtx, proposal, rowX, rowY);
         if (row.badge) this.badgeBeforeChevron(row.node);
         // iOS 26: the separator under a row starts where its first text
         // starts (after a Label's icon), else at the row's content.
@@ -4032,6 +4288,12 @@ export class LayoutPass {
         }
       }
     }
+    // The label column's views (a stepper's, a slider's, a date picker's label) go where the plan put them, after the rows (which do not draw them).
+    if (columns) {
+      for (const label of plan.labels ?? []) {
+        if (label.node) this.place(label.node, label.ctx, { width: null, height: null }, x + label.rect.x, y + label.rect.y);
+      }
+    }
   }
 
   /** The x of the first text (in tree order) placed under `node`, if any. */
@@ -4199,7 +4461,12 @@ export class LayoutPass {
       chrome['keyboardBar'] = { x: x + KEYBOARD_BAR_MARGIN_H, y: y + size.height - keyboard, width: Math.max(0, size.width - 2 * KEYBOARD_BAR_MARGIN_H), height: KEYBOARD_BAR_HEIGHT };
     }
     const title = str(node.props['title']) ?? '';
+    // `.navigationSubtitle`: a second line under the title in a Mac's unified
+    // title bar (11 regular, secondary); after the title in a plain one.
     const { platform } = this.env;
+    const subtitle = mac ? (str(node.props['subtitle']) ?? '') : '';
+    const shownTitle = subtitle.length > 0 && !unified && !sheetBar ? `${title} — ${subtitle}` : title;
+    const subtitleFont = makeFont('system', textStyleSize('subheadline', dynamicTypeSize, platform), 400);
     // A unified title bar's title is the window title (15 semibold on macOS 14); a plain bar's and iOS's is the headline.
     const titleFont = makeFont('system', textStyleSize(unified ? 'title3' : 'headline', dynamicTypeSize, platform), sheetBar ? 700 : 600);
     const largeTitleFont = makeFont('system', textStyleSize('largeTitle', dynamicTypeSize, platform), 700);
@@ -4537,7 +4804,16 @@ export class LayoutPass {
       const titleX = Math.max(leadingStart + (unified && windowButtons && !back && leadingWidth === 0 && (cctx.barLeading ?? 0) === 0 ? MAC_TITLE_INSET : 0), leadingCursor);
       const roomEnd = trailingUsed ? trailingEdge + NAV_GROUP_SPACING - 8 : x + size.width - NAV_ITEM_MARGIN;
       const titleWidth = Math.min(Math.ceil(this.measurer.measureWidth(title, titleFont) - 0.001), Math.floor(Math.max(0, roomEnd - titleX)));
-      chrome['title'] = { x: titleX, y: rowY, width: titleWidth, height: rowHeight };
+      if (subtitle.length > 0) {
+        // The title and the subtitle stacked, centered in the row.
+        const block = titleFont.lineHeight + subtitleFont.lineHeight;
+        const top = rowY + (rowHeight - block) / 2;
+        chrome['title'] = { x: titleX, y: top, width: titleWidth, height: titleFont.lineHeight };
+        const subtitleWidth = Math.min(Math.ceil(this.measurer.measureWidth(subtitle, subtitleFont) - 0.001), Math.floor(Math.max(0, roomEnd - titleX)));
+        chrome['subtitle'] = { x: titleX, y: top + titleFont.lineHeight, width: subtitleWidth, height: subtitleFont.lineHeight };
+      } else {
+        chrome['title'] = { x: titleX, y: rowY, width: titleWidth, height: rowHeight };
+      }
     } else if ((!large || titleScrolls) && !principal && !barHidden) {
       const leftUsed = Math.max(
         back ? back.x + back.width - x : 0,
@@ -4553,7 +4829,7 @@ export class LayoutPass {
       const roomEnd = x + size.width - rightUsed - 8;
       const compactCap = screen.width < REGULAR_WIDTH ? Math.floor(size.width * 0.56) : Infinity;
       const titleWidth = Math.min(
-        Math.ceil(this.measurer.measureWidth(title, titleFont) - 0.001),
+        Math.ceil(this.measurer.measureWidth(shownTitle, titleFont) - 0.001),
         compactCap,
         Math.floor(Math.max(0, roomEnd - roomStart)),
       );
@@ -4566,8 +4842,9 @@ export class LayoutPass {
     if (node.id >= 0) {
       this.fonts.set(node.id, large ? largeTitleFont : titleFont);
       const texts: Record<string, TextLayout> = {
-        title: { font: titleFont, lines: [title], alignment: unified || sheetBar ? 'leading' : 'center', truncated: false },
+        title: { font: titleFont, lines: [shownTitle], alignment: unified || sheetBar ? 'leading' : 'center', truncated: false },
       };
+      if (chrome['subtitle']) texts['subtitle'] = { font: subtitleFont, lines: [subtitle], alignment: 'leading', truncated: false };
       if (depth > 0) texts['back'] = { font: backFont, lines: [backLabel], alignment: 'leading', truncated: false };
       if (large) {
         const wrapped = wrapText(title, largeTitleFont, size.width - 32, 1, this.measurer);
@@ -5157,6 +5434,8 @@ export class LayoutPass {
   private measureStepper(node: LayoutNode, ctx: Context, p: Proposal): Size {
     const label = this.contentOf(node);
     const control = this.stepperMetrics();
+    // A Mac form's row: the label is in the label column; the control alone.
+    if (ctx.formColumn) return { width: control.width, height: control.height };
     const labelSize = label ? this.measure(label, this.childContext(node, ctx), this.stepperLabelProposal(p)) : ZERO;
     return {
       width: finite(p.width) ? p.width : labelSize.width + control.gap + control.width,
@@ -5168,11 +5447,12 @@ export class LayoutPass {
     const cctx = this.childContext(node, ctx);
     const label = this.contentOf(node);
     const labelProposal = this.stepperLabelProposal(p);
-    const labelSize = label ? this.measure(label, cctx, labelProposal) : ZERO;
+    const labelSize = label && !ctx.formColumn ? this.measure(label, cctx, labelProposal) : ZERO;
     const labelY = y + (size.height - labelSize.height) / 2;
-    if (label) this.place(label, cctx, labelProposal, x, labelY);
+    // A Mac form's row: the label is in the label column (the form places it), the control at the leading edge.
+    if (label && !ctx.formColumn) this.place(label, cctx, labelProposal, x, labelY);
     const control = this.stepperMetrics();
-    const controlX = x + size.width - control.width;
+    const controlX = ctx.formColumn ? x : x + size.width - control.width;
     const controlY = y + (size.height - control.height) / 2;
     const existing = node.id >= 0 ? this.chrome.get(node.id) : undefined;
     // iOS: − and + side by side; a Mac: up (increment) over down.
@@ -5232,7 +5512,8 @@ export class LayoutPass {
   private placeSlider(node: LayoutNode, ctx: Context, p: Proposal, x: number, y: number, size: Size): void {
     const plan = this.sliderPlan(node, ctx, p);
     const { cctx } = plan;
-    if (plan.label) this.hide(plan.label, node);
+    // The label is not drawn (a Mac form places it in its label column).
+    if (plan.label && !ctx.formColumn) this.hide(plan.label, node);
     const m = this.sliderMetrics();
     const rowY = y;
     let trackX = x;
@@ -5289,10 +5570,11 @@ export class LayoutPass {
       const dateWidth = capsule(dateText);
       const timeWidth = capsule(timeText);
       const capsulesWidth = dateWidth + timeWidth + (dateText !== null && timeText !== null ? capsuleGap : 0);
-      const label = node.props['labelsHidden'] === true ? null : this.contentOf(node);
+      // A Mac form's row: the label is in the label column; the fields alone.
+      const label = node.props['labelsHidden'] === true || ctx.formColumn ? null : this.contentOf(node);
       const labelProposal: Proposal = { width: shrink(p.width, capsulesWidth + DATEPICKER_GAP), height: p.height };
       const labelSize = label ? this.measure(label, cctx, labelProposal) : ZERO;
-      const width = finite(p.width) ? p.width : labelSize.width + (label ? DATEPICKER_GAP : 0) + capsulesWidth;
+      const width = ctx.formColumn ? capsulesWidth : finite(p.width) ? p.width : labelSize.width + (label ? DATEPICKER_GAP : 0) + capsulesWidth;
       return {
         size: { width, height: Math.max(labelSize.height, mac ? MAC_DATEPICKER_HEIGHT : DATEPICKER_HEIGHT) },
         label,
@@ -5308,8 +5590,8 @@ export class LayoutPass {
 
   private placeDatePicker(node: LayoutNode, ctx: Context, p: Proposal, x: number, y: number, size: Size): void {
     const plan = this.datePickerPlan(node, ctx, p);
-    if (!plan.label) {
-      // `labelsHidden`: the label child exists but is not shown.
+    if (!plan.label && (!ctx.formColumn || node.props['labelsHidden'] === true)) {
+      // `labelsHidden`: the label child exists but is not shown (a Mac form places it in its label column).
       for (const child of node.children) this.hide(child, node);
     }
     const labelY = y + (size.height - plan.labelSize.height) / 2;

package/src/layoutDom.ts

@@ -877,6 +877,27 @@ function applyChrome(
       }
       bindScrollUnderBar(el, frame, chrome?.['topInset'], chrome?.['largeTitle']);
       bindScrollEdgeBottom(el, chrome?.['bottomInset'], extent);
+      // The Mac idiom's columns form (`data-sb-form-columns`, styles.css):
+      // the label column's texts (chrome `formLabel<i>`) as spans in the
+      // content, as many as the engine placed.
+      setFlag(el, 'sbFormColumns', chrome?.['columns'] ? '' : null);
+      if (content) {
+        const texts = result.chromeText.get(node.id);
+        const labels = content.querySelectorAll<HTMLElement>(':scope > .sb-form-label');
+        let i = 0;
+        for (; chrome?.[`formLabel${i}`]; i++) {
+          let label = labels[i] ?? null;
+          if (!label) {
+            label = document.createElement('span');
+            label.className = 'sb-form-label';
+            content.append(label);
+          }
+          placeChrome(label, chrome[`formLabel${i}`], frame);
+          const layout = texts?.[`formLabel${i}`];
+          if (layout) setTextLayout(label, layout);
+        }
+        for (let extra = i; extra < labels.length; extra++) labels[extra]!.remove();
+      }
       return;
     }
     case 'scrollview': {
@@ -976,6 +997,17 @@ function applyChrome(
           if (inlineTitle.style.lineHeight !== lineHeight) inlineTitle.style.lineHeight = lineHeight;
         }
       }
+      // The Mac idiom: the subtitle under the title in a unified title bar (chrome `subtitle`, hidden otherwise).
+      const subtitleEl = el.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-subtitle');
+      if (subtitleEl) {
+        const subtitleRect = chrome?.['subtitle'];
+        placeChrome(subtitleEl, subtitleRect, frame);
+        if (subtitleRect) {
+          if (texts?.['subtitle']) setFont(subtitleEl, texts['subtitle'].font);
+          const lineHeight = `${subtitleRect.height}px`;
+          if (subtitleEl.style.lineHeight !== lineHeight) subtitleEl.style.lineHeight = lineHeight;
+        }
+      }
       // The More button of the collapsed `secondary` items, at the trailing end.
       placeChrome(el.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-more'), chrome?.['more'], frame);
       const back = el.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-back');

package/src/protocol.ts

@@ -623,6 +623,8 @@ export interface ScrollViewProps {
 export type ListStyle = 'plain' | 'insetGrouped' | 'grouped' | 'sidebar';
 export interface ListProps {
   style?: ListStyle;
+  /** A `Form`: on a Mac the page lays its rows out in the columns style (labels in a column before their controls). */
+  form?: boolean;
 }
 export interface SectionProps {
   header: string | null;
@@ -679,6 +681,8 @@ export type NavStackProps = Record<string, never>;
 export type NavDisplayMode = 'automatic' | 'large' | 'inline';
 export interface NavScreenProps {
   title: string;
+  /** `.navigationSubtitle`: a second line under the title in a Mac's unified title bar, after it in a plain one. */
+  subtitle?: string;
   displayMode: NavDisplayMode;
   /** 0 for the root screen; the renderer draws a back button when > 0. */
   depth: number;

package/src/renderer.ts

@@ -3163,6 +3163,9 @@ function createShell(kind: ElementKind): HTMLElement {
       if (chevron) back.append(chevron);
       back.append(span('sb-navbar-back-label'));
       const inlineTitle = span('sb-navbar-title');
+      // `.navigationSubtitle`: under the title in a Mac's unified title bar (chrome.subtitle).
+      const subtitle = span('sb-navbar-subtitle');
+      subtitle.hidden = true;
       // The More button of the collapsed `secondary` items (chrome.more).
       const more = document.createElement('button');
       more.type = 'button';
@@ -3172,7 +3175,7 @@ function createShell(kind: ElementKind): HTMLElement {
       more.hidden = true;
       const ellipsis = renderSymbol('ellipsis');
       if (ellipsis) more.append(ellipsis);
-      bar.append(back, inlineTitle, div('sb-navbar-trailing'), more);
+      bar.append(back, inlineTitle, subtitle, div('sb-navbar-trailing'), more);
       const body = div('sb-navscreen-body');
       const slot = div('sb-slot sb-navscreen-content');
       // The `keyboard` toolbars' bar (chrome `keyboardBar`), under their items.
@@ -4787,6 +4790,11 @@ function applyNavScreen(el: HTMLElement, props: NavScreenProps): void {
   const largeTitle = largeTitleOf(el);
   // A large title that scrolls away collapses into the inline one (shown
   // with `data-sb-collapsed`, src/largeTitle.ts).
+  const subtitleEl = el.querySelector<HTMLElement>(':scope > .sb-navbar > .sb-navbar-subtitle');
+  if (subtitleEl) {
+    const subtitle = props.subtitle ?? '';
+    if (subtitleEl.textContent !== subtitle) subtitleEl.textContent = subtitle;
+  }
   if (inlineTitle) {
     const appearing = inlineTitle.textContent === '' && title !== '' && inlineTitle.isConnected;
     inlineTitle.textContent = title;

package/src/styles.css

@@ -3944,7 +3944,8 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
 .sb-datepicker > [hidden],
 .sb-stepper > [hidden],
 .sb-slider > [hidden],
-.sb-slider-labels > [hidden] {
+.sb-slider-labels > [hidden],
+.sb-picker > .sb-picker-label[hidden] {
   display: none;
 }
 
@@ -4659,7 +4660,8 @@ html[data-sb-platform="macos"] .device[data-theme="light"] {
   --sb-mac-control-shadow:
     0 0 0 0.5px rgba(0, 0, 0, 0.12),
     0 1px 1px rgba(0, 0, 0, 0.08);
-  /* A text field's edges: light at the sides and top, darker at the bottom. */
+  /* A text field: the text background, its edges light at the sides and top, darker at the bottom. */
+  --sb-mac-field: #ffffff;
   --sb-mac-field-shadow:
     inset 0 0 0 1px rgba(0, 0, 0, 0.11),
     inset 0 -1px 0 0 rgba(0, 0, 0, 0.27);
@@ -4682,6 +4684,7 @@ html[data-sb-platform="macos"] .device[data-theme="dark"] {
   --sb-mac-control-shadow:
     0 0 0 0.5px rgba(0, 0, 0, 0.4),
     0 1px 1px rgba(0, 0, 0, 0.2);
+  --sb-mac-field: #333333;
   --sb-mac-field-shadow:
     inset 0 0 0 1px rgba(255, 255, 255, 0.12),
     inset 0 -1px 0 0 rgba(255, 255, 255, 0.2);
@@ -4769,6 +4772,89 @@ html[data-sb-platform="macos"] .sb-navscreen[data-sb-unified] > .sb-navbar > .sb
   font-size: var(--sb-ts-title3-size, 15px);
 }
 
+/* `.navigationSubtitle`: a second line under the title in a unified title
+   bar (the engine's `subtitle` rect; in a plain bar it joins the title). */
+.sb-navbar-subtitle {
+  position: absolute;
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  text-align: start;
+  font-size: 11px;
+  color: var(--sb-color-secondary);
+}
+
+.sb-navbar-subtitle[hidden] {
+  display: none;
+}
+
+/* A `Form` is the columns style (the engine's `columns` plan): on the
+   window background with no cards or separators; the labels (chrome
+   `formLabel<i>`) right-aligned in their column, the label color; a
+   section's header and footer 13 regular, the label color; a text field's
+   title moved to the column shows no placeholder. */
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] {
+  background: var(--sb-color-system-background);
+}
+
+/* The rows' card spans the form (the label column is drawn in it): no card look, nothing clipped. */
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section-rows {
+  border-radius: 0;
+  background: transparent;
+  overflow: visible;
+}
+
+/* A text field's row is the field (the engine's row rect): the Mac's bezel, its text 3 in. */
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-textfield[data-sb-style] {
+  box-sizing: border-box;
+  padding: 0 3px;
+  border-radius: 5px;
+  background: var(--sb-mac-field);
+  box-shadow: var(--sb-mac-field-shadow);
+}
+
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-textfield[data-sb-style]:focus {
+  box-shadow:
+    var(--sb-mac-field-shadow),
+    0 0 0 3.5px color-mix(in srgb, var(--sb-tint, var(--sb-color-accent)) 50%, transparent);
+}
+
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section-rows > ::after,
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] > .sb-list-content > :not(.sb-section)::after,
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section-header::after,
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section-footer::after {
+  display: none;
+}
+
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section-header,
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section-footer {
+  color: var(--sb-color-primary);
+}
+
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-form-label {
+  position: absolute;
+  white-space: pre;
+  text-align: right;
+  color: var(--sb-color-primary);
+}
+
+@supports (text-box: trim-start cap alphabetic) {
+  html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-form-label {
+    text-box: trim-start cap alphabetic;
+    padding-top: var(--sb-cap-inset);
+  }
+}
+
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] input.sb-textfield::placeholder {
+  color: transparent;
+}
+
+/* A pop-up button spanning the controls column: its value at the leading end, the chevrons at the trailing. */
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-picker[data-sb-popup] > .sb-picker-value {
+  justify-content: space-between;
+}
+
 /* The tab bar: a segmented control at the top of the content (the engine's
    Mac tab view), each tab a segment with its title alone, the selected one
    raised; no icons, no glass. */
@@ -4987,11 +5073,15 @@ html[data-sb-platform="macos"] .sb-section-footer::after {
   background: var(--sb-color-row-separator);
 }
 
-/* The rule under a footer only where another section follows. */
+/* The rule under a footer only where another section follows (a columns form has none). */
 html[data-sb-platform="macos"] .sb-section:has(+ .sb-section) > .sb-section-footer::after {
   display: block;
 }
 
+html[data-sb-platform="macos"] .sb-list[data-sb-form-columns] .sb-section:has(+ .sb-section) > .sb-section-footer::after {
+  display: none;
+}
+
 /* A button in a list row is a push button at its own size (the engine's
    `bordered` rect, `data-sb-bordered="inset"`), on the row, not the row
    itself; a destructive one is not tinted. */
@@ -5118,7 +5208,7 @@ html[data-sb-platform="macos"] .sb-textfield:not([data-sb-style="plain"]) {
   padding: 0 6px;
   border: 0;
   border-radius: 5px;
-  background: var(--sb-mac-control);
+  background: var(--sb-mac-field);
   box-shadow: var(--sb-mac-field-shadow);
   font-size: 13px;
 }
@@ -5149,6 +5239,11 @@ html[data-sb-platform="macos"] .sb-stepper[data-sb-arrows] > .sb-stepper-control
   line-height: 0;
 }
 
+/* The arrows stand in for the plus and minus glyphs. */
+html[data-sb-platform="macos"] .sb-stepper[data-sb-arrows] > .sb-stepper-control > .sb-stepper-button > svg {
+  display: none;
+}
+
 html[data-sb-platform="macos"] .sb-stepper[data-sb-arrows] > .sb-stepper-control > .sb-stepper-button::after {
   content: "";
   width: 0;