@xeplr/ui-factory 1.8.1 → 1.8.3

package/README.md

@@ -117,6 +117,21 @@ If `onSave` throws an error with `fields: [{ field, message }]` (what `createFac
 
 Values arrive typed: numbers as numbers, checkboxes as booleans, dates as `"YYYY-MM-DD"`, a date and time as `"YYYY-MM-DDTHH:MM"`, a dropdown or radio group as the option's own `id` (a table's numeric id stays a number), a multi-select as an **array** of ids, and a file as the stored file's **path**.
 
+### On a phone
+
+Below **640px wide** (the viewport, not the box the screen sits in) a screen stops being a scaled-down canvas and **stacks**: every control takes the full width, one per row, in reading order — top to bottom, left to right across a row, the same order `inputNodes` reads. Nothing to set and nothing to design twice: the positions you placed are simply not used there.
+
+- Controls are drawn at their real size, not shrunk. Inputs are at least **16px** (smaller makes iOS zoom the page when a field is focused) and **44px** tall; tick boxes, radio buttons and Remove are thumb-sized.
+- Error messages sit under their field and wrap, rather than being cut off at the screen's edge.
+- The footer wraps: what the save is doing on its own line, the buttons under it sharing the width.
+- A popup (a list's Edit / New) fills the screen.
+- A list keeps its table, which scrolls sideways inside its card; its row buttons stay pinned at the right edge (that part is `@xeplr/ui-table`, 1.1.3 or later).
+- An identifier still to be numbered takes no space.
+
+Above 640px nothing changes: a screen is shown at its design width, scaled down only when its box is narrower. A screen in a narrow side panel on a desktop keeps its designed layout. The builder and the flow designer are not for phones and are left as they are.
+
+How: `ScreenSample` hands each control's position to CSS as variables (`--xf-x`, `--xf-y`, `--xf-w`, `--xf-h`) and its reading-order place as `--xf-order`; `factory.css` uses the positions on a desktop and the order on a phone. A design of your own can do the same.
+
 ### Where each value is kept
 
 A record is columns in a real table, never JSON — so the two types that are not
@@ -879,6 +894,13 @@ npm test
 
 `test/urlState.test.js` covers the URL state: the key format, and the three controllers reading their places back from a real `MemoryRouter` and being clicked through in memory, rendered with `react-dom/server`.
 
+```sh
+npx playwright install chromium-headless-shell   # once
+npm run test:phone
+```
+
+`test/phone.check.js` opens the dev app (`dev/`) in a real browser at 360, 390 and 430px wide and holds every screen to the phone rules: the page never scrolls sideways; fields are one per row, full width, in reading order, none overlapping; inputs are 16px or larger and 44px tall; the footer's buttons are 44px and on screen; a list's row buttons are on screen without scrolling the table; a popup fills the screen. At 1280px it checks that the designed layout is untouched. It is not part of `npm test` — it needs a browser and starts a dev server — so run it before releasing anything that changes how a screen is drawn. The list checks use the `@xeplr/ui-table` installed here.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "description": "Design data-entry screens on @xeplr/ui-canvas, save them as JSON, run them as auto-saving forms with lists of saved records — built for Claude to draft and people to refine",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,8 @@
   ],
   "scripts": {
     "dev": "vite",
-    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done"
+    "test": "for f in test/*.test.js; do node \"$f\" || exit 1; done",
+    "test:phone": "node test/phone.check.js"
   },
   "keywords": [
     "form-builder",
@@ -56,7 +57,8 @@
     "@vitejs/plugin-react": "^5.2.0",
     "@xeplr/schema-handler": "^1.0.5",
     "@xeplr/ui-canvas": "^1.0.1",
-    "@xeplr/ui-table": "^1.0.6",
+    "@xeplr/ui-table": "^1.1.3",
+    "playwright": "^1.64.1",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router-dom": "^7.18.4",

package/src/designs/ScreenModal.jsx

@@ -29,7 +29,8 @@ export default function ScreenModal({ title, width, onClose, children }) {
         aria-modal="true"
         aria-label={title}
         tabIndex={-1}
-        style={{ width: width ? `min(${width + 48}px, 96vw)` : undefined }}
+        // A variable, not a width: on a phone factory.css makes it the full screen.
+        style={width ? { '--xf-modal-w': `min(${width + 48}px, 96vw)` } : undefined}
       >
         <header className="xeplr-factory-modal-head">
           <span className="xeplr-factory-modal-title">{title}</span>

package/src/designs/ScreenSample.jsx

@@ -1,5 +1,5 @@
 import ControlView from './ControlView.jsx'
-import { contentBottom, inputNodes, MARGIN } from '../document.js'
+import { contentBottom, inputNodes, readingOrder, MARGIN } from '../document.js'
 import { screenStyle } from './styles.js'
 import { CHOICE_TYPES } from '../controls.js'
 
@@ -11,6 +11,12 @@ import { CHOICE_TYPES } from '../controls.js'
 // The screen is never wider than the width it was designed at, so what was
 // designed at 800px is shown at 800px, and only a narrower screen scales it.
 //
+// ON A PHONE IT STACKS. Positions are handed to CSS as variables (--xf-x, …),
+// not as left/top, so factory.css can drop them below 640px and lay the fields
+// out one per row in reading order (--xf-order) — full width, at real sizes.
+// Scaled down instead, an 800px design on a 360px phone is text in boxes too
+// small to tap. The desktop layout does not change.
+//
 // SAVE IS A BUTTON, AND AN AJAX CALL — never a form submit. The <form> below
 // exists for semantics only: its submit is swallowed, so Enter in a field
 // posts nothing and saves nothing. Only the Save button saves.
@@ -30,7 +36,12 @@ const STATUS = {
 
 /** What the background save is doing, in words. */
 function SaveStatus({ ctrl }) {
-  const text = ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]
+  // A screen with no table of its own (a review in a workflow) saves nothing,
+  // so "Unsaved changes" and "Saved" would describe something that is not
+  // happening. What still matters there is a field left wrong.
+  const keeps = Boolean(ctrl.document && ctrl.document.source)
+  const quiet = !keeps && (ctrl.status === 'pending' || ctrl.status === 'saved' || ctrl.status === 'saving')
+  const text = quiet ? '' : ctrl.status === 'error' ? `Not saved — ${ctrl.saveError}` : STATUS[ctrl.status]
   return (
     <span className={`xeplr-factory-footer-status xeplr-factory-footer-status--${ctrl.status}`} role="status" aria-live="polite">
       {text}
@@ -159,6 +170,9 @@ export default function ScreenSample({ ctrl, className, style, renderPopup, rend
   // filled in, not as tall as every step stacked up.
   const shown = ctrl.visibleNodes && ctrl.visibleNodes.length ? ctrl.visibleNodes : doc.nodes
   const pageHeight = (contentBottom(doc, shown) + MARGIN) * aspect * 100
+  // Where each control comes when the screen stacks (phones): read top to
+  // bottom, left to right across a row — the order the design is read in.
+  const order = new Map(readingOrder(shown).map((n, i) => [n.id, i]))
   const fieldNodes = inputNodes(doc)
   // A screen with no fields of its own (a list screen) has nothing to save —
   // and no sheet: its list is the card (factory.css, --bare).
@@ -177,7 +191,7 @@ export default function ScreenSample({ ctrl, className, style, renderPopup, rend
     >
       <Page
         className="xeplr-factory-page"
-        style={{ height: `${pageHeight}cqw` }}
+        style={{ '--xf-page-h': `${pageHeight}cqw` }}
         // Never a submit: Enter posts nothing and saves nothing. Save is a button.
         {...(ctrl.embedded ? { role: 'group' } : { onSubmit: (e) => e.preventDefault(), noValidate: true })}
         aria-label={doc.name}
@@ -187,10 +201,11 @@ export default function ScreenSample({ ctrl, className, style, renderPopup, rend
             key={node.id}
             className={`xeplr-factory-node xeplr-factory-node--${node.type}`}
             style={{
-              left: `${node.x * 100}%`,
-              top: `${node.y * aspect * 100}cqw`,
-              width: `${node.w * 100}%`,
-              height: `${node.h * aspect * 100}cqw`
+              '--xf-x': `${node.x * 100}%`,
+              '--xf-y': `${node.y * aspect * 100}cqw`,
+              '--xf-w': `${node.w * 100}%`,
+              '--xf-h': `${node.h * aspect * 100}cqw`,
+              '--xf-order': order.get(node.id)
             }}
           >
             <ControlView

package/src/designs/factory.css

@@ -65,8 +65,11 @@
    its own card, and a sheet around it is a second frame with a block of empty
    paper under the rows. */
 .xeplr-factory-screen--bare { background: none; border: none; }
-.xeplr-factory-page { position: relative; width: 100%; margin: 0; }
-.xeplr-factory-node { position: absolute; box-sizing: border-box; }
+.xeplr-factory-page { position: relative; width: 100%; margin: 0; height: var(--xf-page-h); }
+.xeplr-factory-node {
+  position: absolute; box-sizing: border-box;
+  left: var(--xf-x); top: var(--xf-y); width: var(--xf-w); height: var(--xf-h);
+}
 
 .xeplr-factory-invalid {
   border: 1px solid var(--xeplr-danger, #c2372e); border-radius: 8px; padding: 12px 16px;
@@ -433,6 +436,7 @@
   background: var(--xeplr-bg-overlay, rgba(20, 20, 18, .45));
 }
 .xeplr-factory-modal {
+  width: var(--xf-modal-w);
   max-width: 96vw; background: var(--xf-surface); color: var(--xf-ink);
   border-radius: 10px; box-shadow: 0 12px 40px rgba(0, 0, 0, .25); outline: none;
 }
@@ -645,3 +649,57 @@
 .xeplr-factory-table td.is-number { text-align: right; font-variant-numeric: tabular-nums; }
 .xeplr-factory-table tr.is-ticked td { background: var(--xeplr-accent-soft, rgba(47, 91, 211, 0.07)); }
 .xeplr-factory-table-tick { width: 28px; }
+
+/* ── on a phone: one column ────────────────────────────────────────────────
+   Below 640px a screen stops being a scaled-down canvas. An 800px design
+   shrunk to a 360px phone is 14px text squeezed into boxes under half their
+   size, side-by-side fields too narrow to read and targets too small to tap.
+   So here every control takes the full width, one per row, in reading order
+   (--xf-order, from ScreenSample), at its real size: --xf-u is a pixel again
+   and the positions (--xf-x, …) are simply not used. A phone, not a narrow
+   panel: the viewport decides, so a screen in a side panel on a desktop keeps
+   its designed layout. Designers (builder, flow designer) are not for phones
+   and are left as they are. */
+@media (max-width: 640px) {
+  .xeplr-factory-screen { --xf-u: 1px; }
+  .xeplr-factory-page {
+    display: flex; flex-direction: column; gap: 18px;
+    height: auto; padding: 16px; box-sizing: border-box;
+  }
+  .xeplr-factory-node { position: static; width: auto; height: auto; order: var(--xf-order); }
+  /* An identifier still to be numbered draws nothing: no gap for it either. */
+  .xeplr-factory-node:empty { display: none; }
+
+  .xeplr-factory-field { height: auto; }
+  /* 16px or more, or iOS zooms the page when a field is focused; 44px tall,
+     the smallest target a thumb hits reliably. */
+  .xeplr-factory-input { --xf-min-font: 16px; font-size: max(16px, 1em); flex: none; min-height: 44px; }
+  .xeplr-factory-textarea { min-height: 112px; }
+  .xeplr-factory-file-input { min-height: 0; }
+  /* In the flow now: a message may push the next field down, and wraps
+     rather than being cut off at the edge of a narrow screen. */
+  .xeplr-factory-error { position: static; white-space: normal; }
+  .xeplr-factory-check, .xeplr-factory-choice { min-height: 40px; }
+  .xeplr-factory-check input { width: 22px; height: 22px; }
+  .xeplr-factory-choice input { width: 20px; height: 20px; }
+  .xeplr-factory-choices { overflow: visible; }
+  .xeplr-factory-file-clear { min-height: 40px; padding-inline: 14px; }
+  .xeplr-factory-text { height: auto; overflow: visible; }
+  .xeplr-factory-stepper { height: auto; }
+  .xeplr-factory-list { max-height: none; }
+  .xeplr-factory-table-wrap { max-height: 60vh; }
+  .xeplr-factory-subform { height: auto; overflow: visible; }
+
+  /* The footer wraps: what the save is doing on a line of its own, the
+     buttons under it, sharing the width. */
+  .xeplr-factory-footer { flex-wrap: wrap; padding: 12px 16px; }
+  .xeplr-factory-footer-mid { flex-basis: 100%; order: -1; align-items: flex-start; text-align: left; }
+  .xeplr-factory-footer button { flex: 1; min-height: 44px; }
+  .xeplr-factory-list-new { min-height: 36px; }
+
+  /* A popup is the whole screen. */
+  .xeplr-factory-modal-backdrop { padding: 0; }
+  .xeplr-factory-modal { width: 100%; max-width: none; min-height: 100%; border-radius: 0; }
+  .xeplr-factory-modal-body { padding: 0; }
+  .xeplr-factory-modal-close { min-width: 44px; min-height: 44px; }
+}

package/src/designs/styles.js

@@ -6,6 +6,9 @@
 // shrinks to keep the layout's proportions.
 
 const u = (n) => `calc(${n} * var(--xf-u))`
+// A floor the stylesheet can raise: on a phone an input under 16px makes iOS
+// zoom the page on focus, so factory.css sets --xf-min-font on inputs there.
+const font = (n) => `max(var(--xf-min-font, 0px), ${u(n)})`
 
 /** Wrapper-level: the font the whole control uses. */
 export function fieldStyle(style) {
@@ -27,7 +30,7 @@ export function labelStyle(style) {
 export function boxStyle(style) {
   const s = style || {}
   return clean({
-    fontSize: s.fontSize != null ? u(s.fontSize) : undefined,
+    fontSize: s.fontSize != null ? font(s.fontSize) : undefined,
     fontWeight: s.fontWeight,
     fontStyle: s.fontStyle,
     textAlign: s.textAlign,