@xeplr/ui-factory 1.0.1

package/src/controls.js

@@ -0,0 +1,238 @@
+// THE CONTROLS a screen is made of — one entry per type, and nothing about any
+// control lives anywhere else. The palette lists these, the property panel is
+// generated from `properties`, the document checker reads `props`, and the
+// form schema reads `valueType`. Adding a control is adding an entry.
+//
+// Pure data: no React. The renderers are in designs/ControlView.jsx, keyed by
+// the same `type`, so this file also runs in node — the CLI and the tests read
+// it, and so can Claude when it writes a screen.
+//
+// Sizes are FRACTIONS: `w` of the screen's width, `h` of one page's height
+// (width × the screen's aspect). See document.js.
+
+/** A dropdown binds `id` and shows `name` — always. */
+export const OPTION_ID = 'id'
+export const OPTION_LABEL = 'name'
+
+// ── property panel contract ──────────────────────────────────────────────
+// { key, title, fields: [{ path, label, type, options?, help? }] }
+// The same shape as the BI dashboard's widgetProperties.js, so the two panels
+// can become one. `path` points into the node (`props.label`), and the editor
+// for each `type` is in designs/PropertyPanel.jsx.
+
+const FIELD_BASICS = (extra) => ({
+  key: 'field',
+  title: 'Field',
+  fields: [
+    { path: 'props.label', label: 'Label', type: 'text' },
+    { path: 'props.name', label: 'Field name', type: 'text', help: 'The key this value is saved under — letters, digits and _' },
+    ...(extra || []),
+    { path: 'props.required', label: 'Required', type: 'toggle' }
+  ]
+})
+
+const PLACEHOLDER = { path: 'props.placeholder', label: 'Placeholder', type: 'text' }
+
+export const CONTROLS = {
+  text: {
+    type: 'text',
+    label: 'Text',
+    group: 'Inputs',
+    input: true,
+    valueType: 'string',
+    defaultSize: { w: 0.44, h: 0.08 },
+    defaults: { label: 'Text' },
+    props: ['name', 'label', 'placeholder', 'required', 'default', 'validation'],
+    validation: ['minLength', 'maxLength', 'pattern', 'patternMessage'],
+    properties: [
+      FIELD_BASICS([PLACEHOLDER, { path: 'props.default', label: 'Default value', type: 'text' }]),
+      {
+        key: 'validation',
+        title: 'Validation',
+        fields: [
+          { path: 'props.validation.minLength', label: 'Min length', type: 'number' },
+          { path: 'props.validation.maxLength', label: 'Max length', type: 'number' },
+          { path: 'props.validation.pattern', label: 'Pattern (regex)', type: 'text' },
+          { path: 'props.validation.patternMessage', label: 'Pattern message', type: 'text', help: 'Shown when the pattern does not match' }
+        ]
+      }
+    ]
+  },
+
+  textarea: {
+    type: 'textarea',
+    label: 'Text area',
+    group: 'Inputs',
+    input: true,
+    valueType: 'string',
+    defaultSize: { w: 0.92, h: 0.18 },
+    defaults: { label: 'Notes' },
+    props: ['name', 'label', 'placeholder', 'required', 'default', 'validation'],
+    validation: ['minLength', 'maxLength'],
+    properties: [
+      FIELD_BASICS([PLACEHOLDER, { path: 'props.default', label: 'Default value', type: 'textarea' }]),
+      {
+        key: 'validation',
+        title: 'Validation',
+        fields: [
+          { path: 'props.validation.minLength', label: 'Min length', type: 'number' },
+          { path: 'props.validation.maxLength', label: 'Max length', type: 'number' }
+        ]
+      }
+    ]
+  },
+
+  number: {
+    type: 'number',
+    label: 'Number',
+    group: 'Inputs',
+    input: true,
+    valueType: 'number',
+    defaultSize: { w: 0.44, h: 0.08 },
+    defaults: { label: 'Number' },
+    props: ['name', 'label', 'placeholder', 'required', 'default', 'validation'],
+    validation: ['min', 'max', 'integer'],
+    properties: [
+      FIELD_BASICS([PLACEHOLDER, { path: 'props.default', label: 'Default value', type: 'number' }]),
+      {
+        key: 'validation',
+        title: 'Validation',
+        fields: [
+          { path: 'props.validation.min', label: 'Minimum', type: 'number' },
+          { path: 'props.validation.max', label: 'Maximum', type: 'number' },
+          { path: 'props.validation.integer', label: 'Whole numbers only', type: 'toggle' }
+        ]
+      }
+    ]
+  },
+
+  date: {
+    type: 'date',
+    label: 'Date',
+    group: 'Inputs',
+    input: true,
+    valueType: 'date',
+    defaultSize: { w: 0.44, h: 0.08 },
+    defaults: { label: 'Date' },
+    props: ['name', 'label', 'required', 'default', 'validation'],
+    validation: ['min', 'max'],
+    properties: [
+      FIELD_BASICS([{ path: 'props.default', label: 'Default value', type: 'date' }]),
+      {
+        key: 'validation',
+        title: 'Validation',
+        fields: [
+          { path: 'props.validation.min', label: 'Earliest', type: 'date' },
+          { path: 'props.validation.max', label: 'Latest', type: 'date' }
+        ]
+      }
+    ]
+  },
+
+  checkbox: {
+    type: 'checkbox',
+    label: 'Checkbox',
+    group: 'Inputs',
+    input: true,
+    valueType: 'boolean',
+    defaultSize: { w: 0.44, h: 0.06 },
+    defaults: { label: 'Checkbox', default: false },
+    // `required` on a checkbox means it must be ticked — "I accept".
+    props: ['name', 'label', 'required', 'default'],
+    validation: [],
+    properties: [
+      FIELD_BASICS([{ path: 'props.default', label: 'Ticked by default', type: 'toggle' }])
+    ]
+  },
+
+  dropdown: {
+    type: 'dropdown',
+    label: 'Dropdown',
+    group: 'Inputs',
+    input: true,
+    // Whatever the source's ids are — a table's may be numbers or strings.
+    valueType: null,
+    defaultSize: { w: 0.44, h: 0.08 },
+    defaults: { label: 'Dropdown', placeholder: 'Select…', data: { source: 'static', options: [] } },
+    props: ['name', 'label', 'placeholder', 'required', 'default', 'data'],
+    validation: [],
+    properties: [
+      FIELD_BASICS([PLACEHOLDER]),
+      {
+        key: 'data',
+        title: 'Options',
+        fields: [
+          { path: 'props.data', label: 'Options come from', type: 'dataSource' }
+        ]
+      }
+    ]
+  },
+
+  label: {
+    type: 'label',
+    label: 'Label',
+    group: 'Content',
+    input: false,
+    defaultSize: { w: 0.92, h: 0.06 },
+    defaults: { text: 'Label', variant: 'text' },
+    props: ['text', 'variant'],
+    validation: [],
+    properties: [
+      {
+        key: 'content',
+        title: 'Content',
+        fields: [
+          { path: 'props.text', label: 'Text', type: 'textarea' },
+          { path: 'props.variant', label: 'Style', type: 'select', options: [
+            { value: 'heading', label: 'Heading' },
+            { value: 'subheading', label: 'Subheading' },
+            { value: 'text', label: 'Text' }
+          ] }
+        ]
+      }
+    ]
+  },
+
+  button: {
+    type: 'button',
+    label: 'Button',
+    group: 'Actions',
+    input: false,
+    defaultSize: { w: 0.18, h: 0.07 },
+    defaults: { label: 'Save', action: 'submit' },
+    props: ['label', 'action'],
+    validation: [],
+    properties: [
+      {
+        key: 'button',
+        title: 'Button',
+        fields: [
+          { path: 'props.label', label: 'Label', type: 'text' },
+          { path: 'props.action', label: 'Does', type: 'select', options: [
+            { value: 'submit', label: 'Submit the form' },
+            { value: 'reset', label: 'Reset the form' }
+          ] }
+        ]
+      }
+    ]
+  }
+}
+
+export const LABEL_VARIANTS = ['heading', 'subheading', 'text']
+export const BUTTON_ACTIONS = ['submit', 'reset']
+
+/** Palette order: grouped, in declaration order. */
+export function controlGroups(controls = CONTROLS) {
+  const groups = []
+  Object.values(controls).forEach((c) => {
+    let g = groups.find((x) => x.title === c.group)
+    if (!g) { g = { title: c.group, controls: [] }; groups.push(g) }
+    g.controls.push(c)
+  })
+  return groups
+}
+
+/** A registry with extra or replaced controls, leaving the built-ins untouched. */
+export function withControls(extra, base = CONTROLS) {
+  return { ...base, ...extra }
+}

package/src/designs/BuilderSample.jsx

@@ -0,0 +1,117 @@
+import { useState } from 'react'
+import { XeplrCanvas } from '@xeplr/ui-canvas'
+import ControlView from './ControlView.jsx'
+import Palette, { DRAG_TYPE } from './Palette.jsx'
+import PropertyPanel from './PropertyPanel.jsx'
+
+// The builder, drawn: name and Save on top, controls on the left, the screen
+// on the canvas in the middle, the selection's properties on the right.
+// Presentation only — everything comes from useFactoryBuilder.
+//
+// The canvas is @xeplr/ui-canvas in fraction units with pageAspect set to the
+// screen's aspect, which is exactly the geometry ScreenSample renders with — so
+// the builder shows the screen at its real proportions.
+
+export default function BuilderSample({ ctrl, renderPreview, className, style }) {
+  const { document: doc } = ctrl
+  const [preview, setPreview] = useState(false)
+  const problemCount = ctrl.validation.errors.length
+
+  function onDrop(e) {
+    const type = e.dataTransfer.getData(DRAG_TYPE) || e.dataTransfer.getData('text/plain')
+    const def = ctrl.controls[type]
+    if (!def) return
+    e.preventDefault()
+    const inner = e.currentTarget.querySelector('.xeplr-canvas-inner')
+    if (!inner) return ctrl.addControl(type)
+    const rect = inner.getBoundingClientRect()
+    const pageH = rect.width * doc.aspect
+    // The pointer is the control's CENTRE — dropping a wide field by its
+    // top-left corner puts it somewhere you did not point at.
+    ctrl.addControl(type, {
+      x: (e.clientX - rect.left) / rect.width - def.defaultSize.w / 2,
+      y: (e.clientY - rect.top) / pageH - def.defaultSize.h / 2
+    })
+  }
+
+  return (
+    <div className={'xeplr-factory-builder' + (className ? ' ' + className : '')} style={style}>
+      <header className="xeplr-factory-bar">
+        <input
+          className="xeplr-factory-name"
+          value={doc.name}
+          onChange={(e) => ctrl.rename(e.target.value)}
+          placeholder="Screen name, e.g. New employee"
+          aria-label="Screen name"
+        />
+        <div className="xeplr-factory-bar-status" aria-live="polite">
+          {ctrl.saving ? 'Saving…' : ctrl.dirty ? 'Unsaved changes' : ''}
+        </div>
+        {problemCount > 0 && (
+          <span className={`xeplr-factory-problems${ctrl.showErrors ? ' is-loud' : ''}`} title={ctrl.validation.errors.map((x) => `${x.path}: ${x.message}`).join('\n')}>
+            {problemCount} problem{problemCount === 1 ? '' : 's'}
+          </span>
+        )}
+        {renderPreview && (
+          <button type="button" className="xeplr-factory-secondary" aria-pressed={preview} onClick={() => setPreview((p) => !p)}>
+            {preview ? 'Back to design' : 'Preview'}
+          </button>
+        )}
+        <button type="button" className="xeplr-factory-primary" onClick={ctrl.save} disabled={ctrl.saving}>
+          Save
+        </button>
+      </header>
+
+      {ctrl.saveError && <div className="xeplr-factory-save-error" role="alert">{ctrl.saveError}</div>}
+      {ctrl.showErrors && ctrl.errorsByNode._document && (
+        <div className="xeplr-factory-save-error" role="alert">
+          {ctrl.errorsByNode._document.map((e, i) => <div key={i}><code>{e.path}</code> {e.message}</div>)}
+        </div>
+      )}
+
+      {preview && renderPreview ? (
+        <div className="xeplr-factory-preview">{renderPreview(doc)}</div>
+      ) : (
+        <div className="xeplr-factory-body">
+          <Palette groups={ctrl.palette} onAdd={(type) => ctrl.addControl(type)} />
+
+          <div
+            className="xeplr-factory-stage"
+            onDragOver={(e) => { if ([...e.dataTransfer.types].includes(DRAG_TYPE)) { e.preventDefault(); e.dataTransfer.dropEffect = 'copy' } }}
+            onDrop={onDrop}
+          >
+            <XeplrCanvas
+              className="xeplr-factory-canvas"
+              items={doc.nodes}
+              units="fraction"
+              pageAspect={doc.aspect}
+              features={{ resize: true, marquee: true }}
+              selection={ctrl.selected}
+              onSelectionChange={ctrl.setSelected}
+              onItemChange={ctrl.moveControl}
+              minSizeFor={() => ({ minWidth: 16, minHeight: 12 })}
+              renderItem={(node, { selected }) => (
+                <div className={`xeplr-factory-design-node${ctrl.showErrors && ctrl.errorsByNode[node.id] ? ' has-error' : ''}${selected ? ' is-selected' : ''}`}>
+                  <ControlView node={node} mode="design" />
+                </div>
+              )}
+              underlay={doc.nodes.length === 0 && (
+                <div className="xeplr-factory-empty">Drag controls here from the left</div>
+              )}
+            />
+          </div>
+
+          <PropertyPanel
+            node={ctrl.selectedNode}
+            control={ctrl.selectedControl}
+            selectionCount={ctrl.selected.size}
+            errors={ctrl.selectedNode ? ctrl.errorsByNode[ctrl.selectedNode.id] : null}
+            tables={ctrl.tables}
+            onChange={(path, value) => ctrl.setProperty(ctrl.selectedNode.id, path, value)}
+            onRemove={ctrl.removeSelected}
+          />
+        </div>
+      )}
+    </div>
+  )
+}

package/src/designs/ControlView.jsx

@@ -0,0 +1,192 @@
+// How each control LOOKS — the one renderer, used both on the builder's
+// canvas (mode 'design': inert, so a press drags it) and on a live screen
+// (mode 'live'). Sharing it is what makes the builder honest: what you place is
+// what the form shows.
+//
+// Presentation only. Values, options and errors arrive as props.
+
+const ids = (node) => `xeplr-factory-${node.id}`
+
+export default function ControlView({ node, mode = 'live', value, error, options, onChange, onAction, disabled }) {
+  const View = VIEWS[node.type]
+  if (!View) {
+    return <div className="xeplr-factory-unknown">Unknown control “{node.type}”</div>
+  }
+  const design = mode === 'design'
+  return (
+    <View
+      node={node}
+      p={node.props || {}}
+      design={design}
+      value={value}
+      error={design ? null : error}
+      options={options || { loading: false, items: [], error: null }}
+      onChange={onChange || (() => {})}
+      onAction={onAction || (() => {})}
+      disabled={design || disabled}
+    />
+  )
+}
+
+function Field({ node, p, error, children, inline }) {
+  return (
+    <div className={`xeplr-factory-field${inline ? ' xeplr-factory-field--inline' : ''}${error ? ' has-error' : ''}`}>
+      {!inline && (
+        <label className="xeplr-factory-label" htmlFor={ids(node)}>
+          {p.label}{p.required && <span className="xeplr-factory-required" aria-hidden="true"> *</span>}
+        </label>
+      )}
+      {children}
+      {error && <div className="xeplr-factory-error" id={`${ids(node)}-error`} role="alert">{error}</div>}
+    </div>
+  )
+}
+
+function inputProps(node, p, error, disabled) {
+  return {
+    id: ids(node),
+    name: p.name,
+    disabled,
+    required: undefined, // validation is ours, with our messages — not the browser's bubbles
+    'aria-invalid': error ? true : undefined,
+    'aria-describedby': error ? `${ids(node)}-error` : undefined,
+    tabIndex: disabled ? -1 : undefined
+  }
+}
+
+function TextView({ node, p, value, error, onChange, disabled }) {
+  return (
+    <Field node={node} p={p} error={error}>
+      <input
+        className="xeplr-factory-input"
+        type="text"
+        placeholder={p.placeholder || ''}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        {...inputProps(node, p, error, disabled)}
+      />
+    </Field>
+  )
+}
+
+function TextareaView({ node, p, value, error, onChange, disabled }) {
+  return (
+    <Field node={node} p={p} error={error}>
+      <textarea
+        className="xeplr-factory-input xeplr-factory-textarea"
+        placeholder={p.placeholder || ''}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        {...inputProps(node, p, error, disabled)}
+      />
+    </Field>
+  )
+}
+
+function NumberView({ node, p, value, error, onChange, disabled }) {
+  const v = p.validation || {}
+  return (
+    <Field node={node} p={p} error={error}>
+      <input
+        className="xeplr-factory-input"
+        type="number"
+        inputMode={v.integer ? 'numeric' : 'decimal'}
+        step={v.integer ? 1 : 'any'}
+        placeholder={p.placeholder || ''}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        {...inputProps(node, p, error, disabled)}
+      />
+    </Field>
+  )
+}
+
+function DateView({ node, p, value, error, onChange, disabled }) {
+  const v = p.validation || {}
+  return (
+    <Field node={node} p={p} error={error}>
+      <input
+        className="xeplr-factory-input"
+        type="date"
+        min={v.min}
+        max={v.max}
+        value={value ?? ''}
+        onChange={(e) => onChange(e.target.value)}
+        {...inputProps(node, p, error, disabled)}
+      />
+    </Field>
+  )
+}
+
+function CheckboxView({ node, p, value, error, onChange, disabled }) {
+  return (
+    <Field node={node} p={p} error={error} inline>
+      <label className="xeplr-factory-check" htmlFor={ids(node)}>
+        <input
+          type="checkbox"
+          checked={Boolean(value ?? p.default)}
+          onChange={(e) => onChange(e.target.checked)}
+          {...inputProps(node, p, error, disabled)}
+        />
+        <span>{p.label}{p.required && <span className="xeplr-factory-required" aria-hidden="true"> *</span>}</span>
+      </label>
+    </Field>
+  )
+}
+
+function DropdownView({ node, p, design, value, error, options, onChange, disabled }) {
+  const data = p.data || {}
+  const items = data.source === 'static' ? (data.options || []) : options.items
+  return (
+    <Field node={node} p={p} error={error || (!design && options.error) || null}>
+      <select
+        className="xeplr-factory-input xeplr-factory-select"
+        value={value === undefined || value === null ? '' : String(value)}
+        onChange={(e) => onChange(e.target.value)}
+        {...inputProps(node, p, error, disabled || (!design && options.loading))}
+      >
+        <option value="">{!design && options.loading ? 'Loading…' : (p.placeholder || 'Select…')}</option>
+        {!design && items.map((o) => <option key={String(o.id)} value={String(o.id)}>{o.name}</option>)}
+      </select>
+      {design && (
+        <div className="xeplr-factory-hint">
+          {data.source === 'table'
+            ? (data.table ? `from table ${data.table}` : 'no table chosen')
+            : `${(data.options || []).length} option${(data.options || []).length === 1 ? '' : 's'}`}
+        </div>
+      )}
+    </Field>
+  )
+}
+
+function LabelView({ p }) {
+  const variant = p.variant || 'text'
+  const Tag = variant === 'heading' ? 'h2' : variant === 'subheading' ? 'h3' : 'p'
+  return <Tag className={`xeplr-factory-text xeplr-factory-text--${variant}`}>{p.text}</Tag>
+}
+
+function ButtonView({ p, design, onAction, disabled }) {
+  const action = p.action || 'submit'
+  return (
+    <button
+      className={`xeplr-factory-button xeplr-factory-button--${action}`}
+      type={design ? 'button' : action === 'reset' ? 'button' : 'submit'}
+      disabled={disabled}
+      tabIndex={design ? -1 : undefined}
+      onClick={action === 'reset' && !design ? () => onAction('reset') : undefined}
+    >
+      {p.label}
+    </button>
+  )
+}
+
+export const VIEWS = {
+  text: TextView,
+  textarea: TextareaView,
+  number: NumberView,
+  date: DateView,
+  checkbox: CheckboxView,
+  dropdown: DropdownView,
+  label: LabelView,
+  button: ButtonView
+}

package/src/designs/Palette.jsx

@@ -0,0 +1,34 @@
+// The controls you can put on a screen. Drag one onto the canvas to place it
+// where it lands, or click it to add it below everything else.
+
+export const DRAG_TYPE = 'application/x-xeplr-factory-control'
+
+export default function Palette({ groups, onAdd }) {
+  return (
+    <nav className="xeplr-factory-palette" aria-label="Controls">
+      {groups.map((g) => (
+        <section key={g.title} className="xeplr-factory-palette-group">
+          <h4 className="xeplr-factory-palette-title">{g.title}</h4>
+          {g.controls.map((c) => (
+            <button
+              key={c.type}
+              type="button"
+              className="xeplr-factory-palette-item"
+              draggable
+              onDragStart={(e) => {
+                e.dataTransfer.setData(DRAG_TYPE, c.type)
+                e.dataTransfer.setData('text/plain', c.type)
+                e.dataTransfer.effectAllowed = 'copy'
+              }}
+              onClick={() => onAdd(c.type)}
+              title={`Drag onto the screen, or click to add ${c.label.toLowerCase()} at the bottom`}
+            >
+              <span className={`xeplr-factory-palette-icon xeplr-factory-palette-icon--${c.type}`} aria-hidden="true" />
+              {c.label}
+            </button>
+          ))}
+        </section>
+      ))}
+    </nav>
+  )
+}