@xeplr/ui-factory 1.1.0 → 1.2.0

package/README.md

@@ -44,10 +44,10 @@ Most internal apps are a long tail of forms, and every one of them is hand-built
 ## Install
 
 ```sh
-npm i @xeplr/ui-factory @xeplr/ui-canvas @xeplr/ui-table @tanstack/react-table
+npm i @xeplr/ui-factory @xeplr/ui-canvas @xeplr/ui-table @tanstack/react-table react-router-dom
 ```
 
-Peer dependencies: `react ^18 || ^19`, [`@xeplr/ui-canvas`](https://www.npmjs.com/package/@xeplr/ui-canvas) (the canvas the builder places controls on) and [`@xeplr/ui-table`](https://www.npmjs.com/package/@xeplr/ui-table) (lists of saved records). Your bundler must compile JSX and import CSS from the package (Vite does both).
+Peer dependencies: `react ^18 || ^19`, [`@xeplr/ui-canvas`](https://www.npmjs.com/package/@xeplr/ui-canvas) (the canvas the builder places controls on), [`@xeplr/ui-table`](https://www.npmjs.com/package/@xeplr/ui-table) (lists of saved records) and `react-router-dom ^6 || ^7` (imported by [`@xeplr/ui-utils`](https://www.npmjs.com/package/@xeplr/ui-utils)' `useUrlState`, a dependency, for the URL state below; with no router above, everything stays in memory). Your bundler must compile JSX and import CSS from the package (Vite does both).
 
 ## The builder
 
@@ -486,6 +486,26 @@ npx xeplr-factory controls                   # controls, props and rules
 
 Layout is **proportional**, like `@xeplr/ui-canvas` dashboards: `x` and `w` are fractions of the width, `y` and `h` fractions of a page (`width × aspect`). The screen is shown at its design `width`; on a narrower display everything — positions and text — scales down together.
 
+## Where you are lives in the URL: `urlKey`
+
+The control whose properties are open, the step a stepper is open at, and the flow step being edited are places a person navigates to. Give a controller (or its ready-made page) a `urlKey` and they are written to the URL's query, so a refresh or a shared link lands on them again:
+
+| controller / page | key | holds | history |
+|---|---|---|---|
+| `useFactoryBuilder` / `<FactoryBuilder>` | `<urlKey>Selected` | the id of the one selected control | opening or closing its properties adds an entry (Back closes them); moving to another control replaces it |
+| `useFactoryBuilder` / `<FactoryBuilder>` | `<urlKey>Steps` | the step each stepper is open at: `stepperId:index`, comma-separated, step 0 left out | replaces |
+| `useFactoryScreen` / `<FactoryScreen>`, `<FlowRunner>` | `<urlKey>Steps` | as above | replaces |
+| `useFlowBuilder` / `<FlowBuilder>` | `<urlKey>Selected` | the key of the selected flow step | as for a control |
+
+```jsx
+<FactoryBuilder urlKey="form" document={doc} onSave={save} />    // ?formSelected=email&formSteps=stepper:1
+```
+
+- **The key is the host's, never a default.** A builder, its Preview and a list's Edit popup can share a page, and the host has keys of its own, so nothing is written to the URL without a `urlKey` — give each its own. **Without one the state stays in memory**, as before. The Preview and the Edit popup are never given one.
+- **A multi-selection is not a place.** Several controls selected is a working set for Delete and Duplicate, not somewhere a person goes, so it stays in memory and the URL then names nothing. Only a single selection — the one whose properties are open — is in the URL.
+- **Ids, found again.** The selected control is looked up in the document; one that is not there selects nothing. A document handed in after mounting keeps the URL's control, so a host that loads the screen late still lands on it. A step past the last is pulled back to the last, and steppers not in the document (a screen still loading) are left alone.
+- The rule is in `src/urlState.js` (`factoryUrlKeys`, `encodeSteps`, `decodeSteps`, `replacesHistory`, `selectionPlace`); the hooks that keep it are `src/useUrlPlaces.js`.
+
 ## Three ways to use it
 
 1. **Ready-made** — `<FactoryBuilder>` and `<FactoryScreen>`.
@@ -523,6 +543,9 @@ src/
   model.js               ─ everything above, React-free
   useFactoryBuilder.js   ─ builder controller
   useFactoryScreen.js    ─ screen controller
+  useFlowBuilder.js      ─ flow designer controller
+  urlState.js            ─ the URL keys and values for selection and steps (React-free)
+  useUrlPlaces.js        ─ useUrlSteps, useUrlSelection: those places, in the URL or in memory
   useScreenSource.js     ─ { screens, screenEditor } for @xeplr/ui-workflow's Screen step
   designs/               ─ BuilderSample, ScreenSample, ScreenEditorSample, ControlView, ListView, Palette, PropertyPanel, styles.js, factory.css
   pages.jsx              ─ FactoryBuilder, FactoryScreen
@@ -537,6 +560,8 @@ dev/                     ─ the stand-in app for `npm run dev` (not published)
 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`.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xeplr/ui-factory",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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",
@@ -48,7 +48,8 @@
     "@tanstack/react-table": "^8.0.0",
     "@xeplr/ui-canvas": "^1.0.2",
     "@xeplr/ui-table": "^1.0.6",
-    "react": "^18.0.0 || ^19.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
     "@tanstack/react-table": "^8.21.3",
@@ -58,6 +59,10 @@
     "@xeplr/ui-table": "^1.0.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
+    "react-router-dom": "^7.18.4",
     "vite": "^7.3.1"
+  },
+  "dependencies": {
+    "@xeplr/ui-utils": "^1.1.2"
   }
 }

package/src/pages.jsx

@@ -19,6 +19,7 @@ import { BuilderSample, ScreenSample, ScreenModal, FlowRunnerSample, FlowBuilder
  * @prop lockedNames  field names that are already columns of the table — shown read-only
  * @prop screens      [{ id, name, document? }] — other screens: "Edit in" choices, and Preview's popups
  * @prop controls     control registry (default: built-ins)
+ * @prop urlKey       keep the selected control and open steps in the URL (<urlKey>Selected, <urlKey>Steps)
  */
 export function FactoryBuilder(props) {
   const ctrl = useFactoryBuilder(props)
@@ -57,6 +58,7 @@ export function FactoryBuilder(props) {
  * @prop loadScreen   async (id) → document — for screens not in `screens`
  * @prop controls     control registry (default: built-ins)
  * @prop hooks        your FactoryHooks subclass (get / save / delete / actions) — also used by the popup
+ * @prop urlKey       keep the open step of each stepper in the URL (<urlKey>Steps); never passed to the popup
  */
 export function FactoryScreen(props) {
   const ctrl = useFactoryScreen(props)
@@ -166,6 +168,7 @@ const EMPTY_SCREEN = {
  * @prop onSave     async (flow) → void
  * @prop onPublish  async (key) → void
  * @prop onChange   (flow) → void
+ * @prop urlKey     keep the selected step in the URL (<urlKey>Selected)
  */
 export function FlowBuilder(props) {
   const ctrl = useFlowBuilder(props)

package/src/urlState.js

@@ -0,0 +1,71 @@
+// WHERE YOU ARE LIVES IN THE URL — the pure half, no React.
+//
+// The step a stepper is open at, and the control (or flow step) whose
+// properties are open, are places a person navigates to: a refresh or a
+// shared link must land on them again. This file is how they are named in the
+// URL's query; useUrlPlaces.js reads and writes them.
+//
+// THE KEYS ARE THE HOST'S. A builder, a running screen and the preview inside
+// the builder can share one page, and the host app has keys of its own, so a
+// hook writes the URL only when given a `urlKey`. Without one it keeps the
+// same values in memory, exactly as before.
+
+/**
+ * The query keys under a host's `urlKey`, or null (in memory).
+ *   factoryUrlKeys('form') → { steps: 'formSteps', selected: 'formSelected' }
+ */
+export function factoryUrlKeys(urlKey) {
+  if (!urlKey) return null
+  return { steps: `${urlKey}Steps`, selected: `${urlKey}Selected` }
+}
+
+/**
+ * Which step each stepper is open at → one query value. Step 0 is where a
+ * stepper starts, so it is left out — a screen on its first steps has a
+ * clean URL. Ids are URI-encoded, so one holding ':' or ',' splits back.
+ *   { s1: 2, s2: 0 } → 's1:2'
+ */
+export function encodeSteps(open) {
+  return Object.keys(open || {})
+    .filter((id) => Number.isInteger(open[id]) && open[id] > 0)
+    .map((id) => `${encodeURIComponent(id)}:${open[id]}`)
+    .join(',') || null
+}
+
+/** The query value back to { stepper id: index }; anything unreadable is dropped. */
+export function decodeSteps(value) {
+  const open = {}
+  if (!value || typeof value !== 'string') return open
+  value.split(',').forEach((pair) => {
+    const at = pair.lastIndexOf(':')
+    if (at <= 0) return
+    if (!/^\d+$/.test(pair.slice(at + 1))) return
+    const index = Number(pair.slice(at + 1))
+    let id
+    try { id = decodeURIComponent(pair.slice(0, at)) } catch { return }
+    open[id] = index
+  })
+  return open
+}
+
+/**
+ * Selecting adds a history entry when it opens or closes the properties
+ * (nothing → something, something → nothing), so Back closes them; moving
+ * from one selected thing to another is a switch and replaces the entry.
+ */
+export function replacesHistory(previous, next) {
+  const had = previous !== null && previous !== undefined && previous !== ''
+  const has = next !== null && next !== undefined && next !== ''
+  return had && has
+}
+
+/**
+ * A multi-selection is NOT a place: it is a working set for Delete or
+ * Duplicate, not somewhere a person goes. Only a single selection — the one
+ * whose properties are open — is named in the URL.
+ *   one id → that id      none, or several → null
+ */
+export function selectionPlace(ids) {
+  const list = ids ? [...ids] : []
+  return list.length === 1 ? list[0] : null
+}

package/src/useFactoryBuilder.js

@@ -7,6 +7,8 @@ import {
 } from './document.js'
 import { validateDocument } from './validateDocument.js'
 import { presetFor, presetProps, presetGroup, presetHints, convertField } from './presets.js'
+import { useUrlSteps, useUrlSelection } from './useUrlPlaces.js'
+import { selectionPlace } from './urlState.js'
 
 // The builder's controller: the document being edited, what is selected, and
 // every change the builder can make. No JSX — designs/BuilderSample.jsx draws
@@ -36,10 +38,29 @@ import { presetFor, presetProps, presetGroup, presetHints, convertField } from '
  *                    shown); throw with `confirm: [{ column, records }]` when removed fields would drop
  *                    columns — the builder asks, and calls again with confirmDrop naming them.
  * @param controls    the control registry (default: the built-ins)
+ * @param urlKey      where the selected control and the open steps live in the URL:
+ *                    `<urlKey>Selected` and `<urlKey>Steps`, so a refresh or a shared
+ *                    link lands on the same control. Omitted → kept in memory.
  */
-export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800 } = {}) {
+export function useFactoryBuilder({ document: given, name, onSave, onChange, onPublish, listTables, screens, lockedNames, controls = CONTROLS, autosaveDelay = 800, urlKey } = {}) {
   const [doc, setDoc] = useState(() => given || createScreen({ name }))
-  const [selected, setSelected] = useState(() => new Set())
+
+  // ── selection ─────────────────────────────────────────────────────────
+  // ONE selected control is a place — its properties are open — so it is
+  // named in the URL (by id, found again in the document). Several selected
+  // is a working set for Delete or Duplicate, not a place: it stays here, and
+  // the URL then names nothing.
+  const [placeId, selectPlace] = useUrlSelection(urlKey)
+  const [several, setSeveral] = useState(null)
+  const placeNode = placeId === null ? null : doc.nodes.find((n) => String(n.id) === placeId) || null
+  const placeNodeId = placeNode ? placeNode.id : null
+  const selected = useMemo(() => several || new Set(placeNodeId === null ? [] : [placeNodeId]), [several, placeNodeId])
+  const selectedRef = useRef(selected); selectedRef.current = selected
+  const setSelected = useCallback((next) => {
+    const ids = [...((typeof next === 'function' ? next(selectedRef.current) : next) || [])]
+    setSeveral(ids.length > 1 ? new Set(ids) : null)
+    selectPlace(selectionPlace(ids))
+  }, [selectPlace])
   const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [saveError, setSaveError] = useState(null)
@@ -57,7 +78,10 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     if (JSON.stringify(given) === JSON.stringify(docRef.current)) return
     docRef.current = given
     setDoc(given)
-    setSelected(new Set())
+    // A multi-selection belongs to the old document. The URL's control is
+    // kept: a host that loads the screen after mounting hands it in here, and
+    // the link's control is found in it — or, if it is not there, nothing is.
+    setSeveral(null)
     setDirty(false)
   }, [given])
 
@@ -104,7 +128,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   // Which step of each stepper is open on the canvas. Everything dropped while
   // a step is open belongs to that step, and the canvas shows only that step —
   // so one screen holds as many little screens as it has steps.
-  const [openSteps, setOpenSteps] = useState({})
+  const [openSteps, setOpenSteps] = useUrlSteps(urlKey)
   const stepperNodes = useMemo(() => steppers(doc, controls), [doc, controls])
   const [building, setBuilding] = useState(null)      // the stepper being built
   const activeStepper = stepperNodes.find((n) => n.id === building) || stepperNodes[stepperNodes.length - 1] || null
@@ -113,7 +137,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
   const goToStep = useCallback((id, index) => {
     setBuilding(id)
     setOpenSteps((o) => ({ ...o, [id]: index }))
-  }, [])
+  }, [setOpenSteps])
 
   /** The step a new control lands on: the one open on the stepper being built. */
   const dropStep = useCallback(() => (
@@ -142,7 +166,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     })
     if (added) setSelected(new Set([added.id]))
     return added
-  }, [update, controls, dropStep])
+  }, [update, controls, dropStep, setSelected])
 
   const moveControl = useCallback((id, patch) => update((d) => moveNode(d, id, patch)), [update])
 
@@ -164,13 +188,12 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
     return dropped
   }, [update, controls])
 
-  const selectedRef = useRef(selected); selectedRef.current = selected
   const removeSelected = useCallback(() => {
     const ids = [...selectedRef.current]
     if (!ids.length) return
     update((d) => removeNodes(d, ids))
     setSelected(new Set())
-  }, [update])
+  }, [update, setSelected])
 
   /** Everything selected moves to a copy, just below the original. */
   const duplicateSelected = useCallback(() => {
@@ -191,7 +214,7 @@ export function useFactoryBuilder({ document: given, name, onSave, onChange, onP
       return next
     })
     setSelected(new Set(created))
-  }, [update, controls])
+  }, [update, controls, setSelected])
 
   // ── validation + save ─────────────────────────────────────────────────
   const validation = useMemo(() => validateDocument(doc, controls), [doc, controls])

package/src/useFactoryScreen.js

@@ -4,6 +4,7 @@ import { inputNodes, nodesForSteps, steppers, stepsOf, stepOf, resolveStep, reac
 import { validateDocument } from './validateDocument.js'
 import { initialValues, parseInput, saveState, fieldError, optionValue, recordValues, listSource } from './values.js'
 import { hookMethod } from './hooks.js'
+import { useUrlSteps } from './useUrlPlaces.js'
 
 // A saved screen, running. No JSX — designs/ScreenSample.jsx draws it.
 //
@@ -48,10 +49,12 @@ import { hookMethod } from './hooks.js'
  * @param onDirtyChange (dirty) → void — whether there are unsaved changes, as that changes
  * @param controls      the control registry (default: the built-ins)
  * @param hooks         a FactoryHooks (or an object with some of its methods) — get / save / delete / actions
+ * @param urlKey        where the open step of each stepper lives in the URL (`<urlKey>Steps`),
+ *                      so a refresh or a shared link lands on the same step. Omitted → in memory.
  */
 export function useFactoryScreen({
   document: doc, record, recordKey = 'id', onSave, fetchOptions, fetchRecords, fetchRecord, onDelete, onChange, screens, loadScreen, hooks, uploadFile, fileUrl,
-  onOpenRecord, onDone, onDirtyChange,
+  onOpenRecord, onDone, onDirtyChange, urlKey,
   controls = CONTROLS
 } = {}) {
   const check = useMemo(() => validateDocument(doc, controls), [doc, controls])
@@ -161,7 +164,7 @@ export function useFactoryScreen({
   // A stepper shows one step at a time. Which step each is open at lives here;
   // the fields of the steps not showing are still filled in, still checked and
   // still saved — a step is what the person sees, not a separate form.
-  const [openSteps, setOpenSteps] = useState({})
+  const [openSteps, setOpenSteps] = useUrlSteps(urlKey)
   // Steps the app has switched off — { stepper id: [index, …] }. A screen may
   // have branches; which of them apply is the app's to say, from its hooks.
   const [disabledSteps, setDisabledSteps] = useState({})
@@ -169,20 +172,20 @@ export function useFactoryScreen({
   const visibleNodes = useMemo(() => (check.ok ? nodesForSteps(doc, openSteps, controls) : []), [check.ok, doc, openSteps, controls])
 
   // A screen whose steps changed under it (a field moved to another step, a
-  // step removed) must not stay open at a step that is gone.
+  // step removed) must not stay open at a step that is gone. Steppers this
+  // document does not have are left alone: a screen still loading has none,
+  // and dropping them would lose the step a link was opened at.
   useEffect(() => {
     setOpenSteps((open) => {
-      let changed = false
-      const next = {}
+      const next = { ...open }
       stepperNodes.forEach((n) => {
         const count = stepsOf(n).length
         const at = Number.isInteger(open[n.id]) ? open[n.id] : 0
         next[n.id] = Math.min(Math.max(at, 0), Math.max(count - 1, 0))
-        if (next[n.id] !== open[n.id]) changed = true
       })
-      return changed || Object.keys(next).length !== Object.keys(open).length ? next : open
+      return next
     })
-  }, [stepperNodes])
+  }, [stepperNodes, setOpenSteps])
 
   const stepControl = useMemo(() => {
     const at = (id) => (Number.isInteger(openSteps[id]) ? openSteps[id] : 0)
@@ -274,7 +277,7 @@ export function useFactoryScreen({
       })
     }
     return control
-  }, [stepperNodes, openSteps, disabledSteps, doc, controls])
+  }, [stepperNodes, openSteps, setOpenSteps, disabledSteps, doc, controls])
 
   live.current.steps = stepControl
 

package/src/useFlowBuilder.js

@@ -4,6 +4,7 @@ import {
   addTransition, setTransition, removeTransition, validateFlow, firstStep, layoutFlow, FLOW_END
 } from './flow.js'
 import { inputNodes } from './document.js'
+import { useUrlSelection } from './useUrlPlaces.js'
 
 // DESIGNING a flow: which screens, in what order, and what decides the order.
 //
@@ -23,10 +24,12 @@ export const FLOW_AUTOSAVE_DELAY = 800
  * @param onSave      async (flow) → void — called after edits, only with a flow that makes sense
  * @param onPublish   async (key) → void — shows a Publish button
  * @param onChange    (flow) → void — every edit
+ * @param urlKey      where the selected step lives in the URL (`<urlKey>Selected`), so a
+ *                    refresh or a shared link opens the same step. Omitted → in memory.
  */
-export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, onSave, onPublish, onChange } = {}) {
+export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, onSave, onPublish, onChange, urlKey } = {}) {
   const [flow, setFlow] = useState(() => given || createFlow({ name }))
-  const [selected, setSelected] = useState(null)          // a step key
+  const [selected, setSelected] = useUrlSelection(urlKey)  // a step key
   const [dirty, setDirty] = useState(false)
   const [saving, setSaving] = useState(false)
   const [saveError, setSaveError] = useState(null)
@@ -102,13 +105,13 @@ export function useFlowBuilder({ flow: given, name, screens = [], loadScreen, on
     })
     if (added) setSelected(added.stepKey)
     return added
-  }, [update])
+  }, [update, setSelected])
   const move = useCallback((stepKey, at) => update((f) => moveStep(f, stepKey, at)), [update])
   const change = useCallback((stepKey, patch) => update((f) => setStep(f, stepKey, patch)), [update])
   const remove = useCallback((stepKey) => {
     update((f) => removeStep(f, stepKey))
     setSelected((s) => (s === stepKey ? null : s))
-  }, [update])
+  }, [update, setSelected])
   const connect = useCallback((fromKey, target, when = null) => update((f) => addTransition(f, fromKey, target, when)), [update])
   const changeTransition = useCallback((fromKey, index, patch) => update((f) => setTransition(f, fromKey, index, patch)), [update])
   const disconnect = useCallback((fromKey, index) => update((f) => removeTransition(f, fromKey, index)), [update])

package/src/useUrlPlaces.js

@@ -0,0 +1,48 @@
+import { useCallback, useMemo, useRef } from 'react'
+import { useUrlState } from '@xeplr/ui-utils/src/url/useUrlState.js'
+import { factoryUrlKeys, encodeSteps, decodeSteps, replacesHistory } from './urlState.js'
+
+// The two places the factory's controllers keep, each in useState's shape so
+// a controller swaps one line. In the URL under the host's `urlKey`; without
+// one, in memory with the same rules (see urlState.js).
+
+/**
+ * [openSteps, setOpenSteps] — which step each stepper is open at,
+ * { stepper id: index }. Moving between steps is a switch, so it replaces the
+ * history entry rather than adding one.
+ */
+export function useUrlSteps(urlKey) {
+  const keys = factoryUrlKeys(urlKey)
+  const [value, setValue] = useUrlState(keys ? keys.steps : 'steps', { inUrl: Boolean(keys), replace: true })
+  const open = useMemo(() => decodeSteps(value), [value])
+  // Two moves in one event build on each other, as useState's updater would.
+  const openRef = useRef(open); openRef.current = open
+  const setOpen = useCallback((next) => {
+    const resolved = typeof next === 'function' ? next(openRef.current) : next
+    const encoded = encodeSteps(resolved)
+    if (encoded === encodeSteps(openRef.current)) return
+    openRef.current = decodeSteps(encoded)
+    setValue(encoded)
+  }, [setValue])
+  return [open, setOpen]
+}
+
+/**
+ * [selected, setSelected] — the one thing whose properties are open (a
+ * control's id, a flow step's key), or null. Opening or closing the
+ * properties adds a history entry; moving to another thing replaces it.
+ * Read back from the URL it is a string.
+ */
+export function useUrlSelection(urlKey) {
+  const keys = factoryUrlKeys(urlKey)
+  const [value, setValue] = useUrlState(keys ? keys.selected : 'selected', { inUrl: Boolean(keys) })
+  const valueRef = useRef(value); valueRef.current = value
+  const select = useCallback((next) => {
+    const resolved = typeof next === 'function' ? next(valueRef.current) : next
+    const v = resolved === undefined || resolved === '' ? null : resolved
+    if ((v === null ? null : String(v)) === valueRef.current) return
+    setValue(v, { replace: replacesHistory(valueRef.current, v) })
+    valueRef.current = v === null ? null : String(v)
+  }, [setValue])
+  return [value, select]
+}