alembic 0.1.0

data/app/controllers/alembic/manage/canvas_controller.rb

@@ -0,0 +1,183 @@
+module Alembic
+  module Manage
+    class CanvasController < BaseController
+      include DrawsCanvas
+      def show
+        render json: canvas_payload(diagnostic)
+      end
+
+      def create
+        objections = Flow::Validator.new(document).violations
+        return render json: { error: refusal(objections) }, status: :unprocessable_entity if objections.any?
+
+        stood_at = diagnostic.current_definition_version&.number
+        diagnostic.create_version
+
+        render json: { notice: created(stood_at) }
+      end
+
+      def publish
+        objections = Flow::Validator.new(document).violations
+        return render json: { error: refusal(objections) }, status: :unprocessable_entity if objections.any?
+
+        ran = diagnostic.live_version&.number
+        diagnostic.publish
+
+        render json: { notice: published(ran) }
+      end
+
+      def details
+        diagnostic.update!(details_params)
+        render json: { notice: "Saved the flow's details." }
+      end
+
+      def undo
+        diagnostic.edit_history.undo_change
+        head :no_content
+      end
+
+      def redo
+        diagnostic.edit_history.redo_change
+        head :no_content
+      end
+
+      def add_step
+        apply(:added, params[:id]) do |flow|
+          next flow.insert(new_step, on: edge_endpoints, leaving: first_port) if placed_on_edge?
+          next flow.add(new_step).connect(from: params[:from], to: params[:id], on: params[:on].presence) if branched_from?
+
+          flow.add(new_step)
+        end
+      end
+
+      def configure_step
+        apply(:updated, params[:step]) { |flow| flow.configure(params[:step], coerced(flow, params[:step])) }
+      end
+
+      def move_step
+        apply(:moved, params[:step]) { |flow| flow.move(params[:step], on: edge_endpoints, leaving: port_for(params[:step])) }
+      end
+
+      def remove_step
+        return render json: { error: refusal_to_remove }, status: :unprocessable_entity if begins_the_flow?(params[:step])
+
+        apply(:removed, params[:step]) { |flow| flow.remove(params[:step]) }
+      end
+
+      def connect
+        apply(:connected, params[:from], params[:to]) { |flow| flow.connect(from: params[:from], to: params[:to], on: params[:on].presence) }
+      end
+
+      def disconnect
+        apply(:disconnected, params[:from], params[:to]) { |flow| flow.disconnect(from: params[:from], to: params[:to]) }
+      end
+
+      private
+
+      def apply(action = nil, *steps)
+        before = document.to_h
+        diagnostic.edit_history.record(yield(document), action, steps, before)
+        head :no_content
+      rescue Flow::InvalidEdit => invalid
+        render json: { error: invalid.message }, status: :unprocessable_entity
+      end
+
+      def diagnostic
+        @diagnostic ||= Flow::Definition.find(params[:flow_id])
+      end
+
+      def document
+        Flow::Document.new(diagnostic.document || diagnostic.definition || {})
+      end
+
+      def details_params
+        params.require(:flow).permit(:title, :summary, :start_label, :persists)
+      end
+
+      def new_step
+        { "id" => params.require(:id), "type" => params.require(:type) }
+      end
+
+      def first_port
+        first_value_of(Flow::Node.new(id: nil, type: params[:type], config: {}))
+      end
+
+      def port_for(id)
+        first_value_of(document.node(id))
+      end
+
+      def first_value_of(node)
+        return unless node && Flow.registry.registered?(node.type)
+
+        step_type = Flow.registry.fetch(node.type)
+        return unless step_type.routes?
+
+        step_type.outputs.flat_map { |output| output.values_for(node) }.first&.fetch("value", nil)&.to_s
+      end
+
+      def begins_the_flow?(id)
+        node = document.node(id)
+
+        node.present? && document.begins_here?(node)
+      end
+
+      def placed_on_edge?
+        params[:from].present? && params[:to].present?
+      end
+
+      def branched_from?
+        params[:from].present?
+      end
+
+      def edge_endpoints
+        [ params[:from], params[:to] ]
+      end
+
+      def configuration
+        params.fetch(:config, {}).permit!.to_h
+      end
+
+      def created(stood_at)
+        now_at = diagnostic.reload.current_definition_version&.number
+        return "Nothing has changed since version #{stood_at}." if now_at == stood_at
+
+        "Created version #{now_at}."
+      end
+
+      def published(ran)
+        now_at = diagnostic.reload.live_version&.number
+        return "Visitors already run version #{now_at}." if now_at == ran
+
+        "Published version #{now_at}. Visitors run it now."
+      end
+
+      def refusal_to_remove
+        "Cannot remove where a flow begins."
+      end
+
+      def refusal(objections)
+        "Cannot publish: #{objections.map { |problem| worded(problem) }.join(', ')}."
+      end
+
+      def worded(problem)
+        trouble = problem.problem.to_s.humanize(capitalize: false)
+
+        problem.node ? "“#{problem.node}” is #{trouble}" : trouble
+      end
+
+      def coerced(flow, id)
+        step_type = Flow::Digest.new(flow).step(id)&.type
+        return configuration unless step_type && Flow.registry.registered?(step_type)
+
+        settled(Flow.registry.fetch(step_type))
+      end
+
+      def settled(step_type)
+        step_type.settings.coerce(configuration).tap do |values|
+          objections = step_type.settings.objections(values)
+          raise Flow::InvalidEdit, objections.join(", ") if objections.any?
+        end
+      end
+    end
+  end
+end

data/app/controllers/alembic/manage/definitions_controller.rb

@@ -0,0 +1,15 @@
+module Alembic
+  module Manage
+    class DefinitionsController < BaseController
+      def edit
+        @diagnostic = Flow::Definition.find(params[:flow_id])
+      end
+
+      def update
+        @diagnostic = Flow::Definition.find(params[:flow_id])
+        @diagnostic.edit_history.edit_document(JSON.parse(params.require(:definition)))
+        redirect_to manage_flow_path(@diagnostic), notice: "Definition saved."
+      end
+    end
+  end
+end

data/app/controllers/alembic/manage/flows_controller.rb

@@ -0,0 +1,55 @@
+module Alembic
+  module Manage
+    class FlowsController < BaseController
+      include DrawsCanvas
+      def index
+        @diagnostics = ordered_diagnostics
+      end
+
+      def create
+        @diagnostic = Flow::Definition.new(create_params)
+
+        if @diagnostic.save
+          redirect_to manage_flow_path(@diagnostic), notice: "Flow created."
+        else
+          @diagnostics = ordered_diagnostics
+          render :index, status: :unprocessable_entity
+        end
+      end
+
+      def show
+        @diagnostic = Flow::Definition.find(params[:id])
+        @canvas = canvas_payload(@diagnostic)
+      end
+
+      def edit
+        @diagnostic = Flow::Definition.find(params[:id])
+      end
+
+      def update
+        @diagnostic = Flow::Definition.find(params[:id])
+        @diagnostic.update!(diagnostic_params)
+        redirect_to manage_flow_path(@diagnostic), notice: "Saved."
+      end
+
+      def destroy
+        Flow::Definition.find(params[:id]).destroy!
+        redirect_to manage_flows_path, notice: "Flow removed."
+      end
+
+      private
+
+      def ordered_diagnostics
+        Flow::Definition.order(:slug)
+      end
+
+      def create_params
+        params.require(:flow).permit(:slug, :kind)
+      end
+
+      def diagnostic_params
+        params.require(:flow).permit(:title, :summary, :start_label, :persists)
+      end
+    end
+  end
+end

data/app/controllers/alembic/manage/page_blocks_controller.rb

@@ -0,0 +1,19 @@
+require "ks_blocks/layout_endpoints"
+
+module Alembic
+  module Manage
+    class PageBlocksController < BaseController
+      include KsBlocks::LayoutEndpoints
+
+      private
+
+      def block_layout_record
+        Page.find(params[:page_id])
+      end
+
+      def block_content(block)
+        render_to_string(partial: "alembic/manage/pages/block_content", locals: { block: block }, formats: [ :html ])
+      end
+    end
+  end
+end

data/app/controllers/alembic/manage/pages_controller.rb

@@ -0,0 +1,38 @@
+module Alembic
+  module Manage
+    class PagesController < BaseController
+      def index
+        @pages = Page.order(:name)
+      end
+
+      def show
+        @page = Page.find(params[:id])
+        @payload = payload(@page)
+
+        respond_to do |format|
+          format.html
+          format.json { render json: @payload }
+        end
+      end
+
+      def create
+        page = Page.create!(page_params)
+        redirect_to manage_page_path(page)
+      end
+
+      private
+
+      def payload(page)
+        {
+          base: manage_page_path(page),
+          pages: manage_pages_path,
+          name: page.name
+        }.merge(page.layout_data)
+      end
+
+      def page_params
+        params.require(:page).permit(:name)
+      end
+    end
+  end
+end

data/app/controllers/alembic/manage/previews_controller.rb

@@ -0,0 +1,38 @@
+module Alembic
+  module Manage
+    class PreviewsController < ::Alembic::FlowsController
+      include AuthenticatesAdmin
+
+      def show
+        @diagnostic = previewed
+        render template: "alembic/flows/show"
+      end
+
+      private
+
+      def flow_start_path(_slug)
+        alembic.manage_flow_preview_path(previewed)
+      end
+
+      def flow_step_path(_slug)
+        alembic.step_manage_flow_preview_path(previewed)
+      end
+
+      def previewing?
+        true
+      end
+
+      def flowing_definition(diagnostic)
+        diagnostic.document
+      end
+
+      def previewed
+        @previewed ||= Flow::Definition.find(params[:flow_id])
+      end
+
+      def admit(_diagnostic)
+        previewed
+      end
+    end
+  end
+end

data/app/controllers/alembic/manage/versions_controller.rb

@@ -0,0 +1,22 @@
+module Alembic
+  module Manage
+    class VersionsController < BaseController
+      def index
+        @diagnostic = diagnostic
+        @versions = @diagnostic.definition_versions.order(number: :desc)
+      end
+
+      def return
+        diagnostic.return_to(diagnostic.definition_versions.find(params[:id]))
+
+        redirect_to manage_flow_path(diagnostic), notice: "The flow is back to that version."
+      end
+
+      private
+
+      def diagnostic
+        @diagnostic ||= Flow::Definition.find(params[:flow_id])
+      end
+    end
+  end
+end

data/app/controllers/concerns/alembic/manage/authenticates_admin.rb

@@ -0,0 +1,19 @@
+module Alembic
+  module Manage
+    module AuthenticatesAdmin
+      extend ActiveSupport::Concern
+
+      included do
+        before_action :authenticate_admin
+      end
+
+      private
+
+      def authenticate_admin
+        return unless Alembic.admin_authentication_method
+
+        send(Alembic.admin_authentication_method)
+      end
+    end
+  end
+end

data/app/controllers/concerns/alembic/manage/draws_canvas.rb

@@ -0,0 +1,35 @@
+module Alembic
+  module Manage
+    module DrawsCanvas
+      extend ActiveSupport::Concern
+
+      private
+
+      def canvas_payload(diagnostic)
+        Flow::Canvas.new(canvas_document(diagnostic)).to_h
+          .merge("undoable" => diagnostic.edit_history.undoable?, "redoable" => diagnostic.edit_history.redoable?,
+                 "changes" => listed_changes(diagnostic), "flow" => flow_details(diagnostic))
+      end
+
+      def canvas_document(diagnostic)
+        Flow::Document.new(diagnostic.document || diagnostic.definition || {})
+      end
+
+      def listed_changes(diagnostic)
+        diagnostic.changes_since_version.to_a.map { |change| Flow::Change.phrase(change) }
+      end
+
+      def flow_details(diagnostic)
+        { "title" => diagnostic.title,
+          "slug" => diagnostic.slug,
+          "summary" => diagnostic.summary,
+          "start_label" => diagnostic.start_label,
+          "version" => diagnostic.current_definition_version&.number,
+          "published" => diagnostic.live_version&.number,
+          "definition_url" => edit_manage_flow_definition_path(diagnostic),
+          "details_url" => edit_manage_flow_path(diagnostic),
+          "history_url" => manage_flow_versions_path(diagnostic) }
+      end
+    end
+  end
+end

data/app/helpers/alembic/application_helper.rb

@@ -0,0 +1,11 @@
+module Alembic
+  module ApplicationHelper
+    def alembic_output_lines(value)
+      case value
+      when Hash then value.map { |name, share| "#{name}: #{share}" }
+      when Array then value
+      else [ value ]
+      end
+    end
+  end
+end

data/app/javascript/alembic/canvas/Canvas.jsx

@@ -0,0 +1,197 @@
+import React, { useEffect, useMemo, useRef, useState } from "react"
+import StepCard from "./StepCard"
+import Inspector from "./Inspector"
+import Placeholder from "./Placeholder"
+import { offeredTo } from "./choices"
+import TypePicker from "./TypePicker"
+import Toolbar from "./Toolbar"
+import Panel from "./Panel"
+import ConnectorLayer from "./ConnectorLayer"
+import useFlow from "./useFlow"
+import useConnectors from "./useConnectors"
+import { CARD, GAP_X, GAP_Y } from "./styles"
+import { nextId } from "./ids"
+
+const page = { display: "flex", height: "100%", minHeight: 0, fontSize: 13 }
+const scroll = { flex: 1, overflow: "auto", position: "relative" }
+const waiting = { position: "absolute", top: 56, left: 16, zIndex: 5, width: CARD + 24, padding: 12, borderRadius: 8 }
+
+const grid = { display: "grid", rowGap: GAP_Y, columnGap: 0, padding: 40, justifyContent: "center", position: "relative" }
+const notice = { position: "sticky", zIndex: 8, top: 8, margin: "8px auto 0", width: "fit-content", padding: "6px 12px", borderRadius: 6, fontSize: 12 }
+
+export const Choosing = ({ port, onCancel }) => (
+  <div className="bg-accent-100 text-accent-800 dark:bg-accent-900 dark:text-accent-100" style={notice}>
+    Choose the step “{port || "next"}” should lead to — <button onClick={onCancel} className="text-accent-800 underline dark:text-accent-100" style={{ border: "none", background: "none", cursor: "pointer", fontSize: 12, padding: 0 }}>cancel</button>
+  </div>
+)
+
+const Canvas = ({ base, token, initial }) => {
+  const { flow, error, notice, send } = useFlow(base, token, initial)
+  const [ selected, setSelected ] = useState(null)
+  const [ adding, setAdding ] = useState(null)
+  const [ armed, setArmed ] = useState(null)
+  const [ dragging, setDragging ] = useState(null)
+  const [ showing, setShowing ] = useState(false)
+  const cards = useRef({})
+  const surface = useRef(null)
+
+  useEffect(() => {
+    const open = () => { setSelected(null); setShowing(true) }
+    document.addEventListener("alembic:open-flow", open)
+    return () => document.removeEventListener("alembic:open-flow", open)
+  }, [])
+
+  useEffect(() => {
+    if (!showing) return
+
+    const away = (event) => {
+      if (!event.target.closest("[data-builder-panel], [data-open-panel]")) setShowing(false)
+    }
+    document.addEventListener("click", away)
+    return () => document.removeEventListener("click", away)
+  }, [ showing ])
+
+  useEffect(() => {
+    document.dispatchEvent(new CustomEvent("alembic:flow-named", { detail: flow.flow?.title || flow.flow?.slug }))
+  }, [ flow.flow?.title, flow.flow?.slug ])
+
+  const byId = useMemo(() => Object.fromEntries(flow.nodes.map((node) => [ node.id, node ])), [ flow.nodes ])
+  const { links, extent } = useConnectors(flow, surface, cards, [ flow, selected, byId ])
+
+  const violationsFor = useMemo(() => {
+    const grouped = {}
+    flow.violations.forEach((violation) => (grouped[violation.node] ||= []).push(violation))
+    return grouped
+  }, [ flow.violations ])
+
+  const attached = flow.nodes.filter((node) => !node.loose)
+  const loose = flow.nodes.filter((node) => node.loose)
+  const rows = Math.max(0, ...attached.map((node) => node.row)) + 1
+  const columns = Math.max(0, ...attached.map((node) => node.column)) + 1
+
+  const connectTo = (target) => {
+    if (!armed) return
+
+    const [ source, port ] = armed
+    setArmed(null)
+    if (source !== target) send("/edges", "POST", { from: source, to: target, on: port || null })
+  }
+
+  const selectedNode = flow.nodes.find((node) => node.id === selected)
+  const entryFor = flow.palette.find((entry) => entry.type === selectedNode?.type)
+
+  return (
+    <div className="text-gray-900 dark:text-gray-100" style={page} onMouseUp={() => setDragging(null)}
+         onKeyDown={(event) => { if (event.key === "Escape") { setSelected(null); setArmed(null); setAdding(null) } }}
+         tabIndex={-1}>
+      <div ref={surface} className="bg-surface-50 dark:bg-surface-950" style={scroll}
+           onClick={(event) => { if (event.target === surface.current) { setSelected(null); setArmed(null); setShowing(false) } }}>
+        {armed && (
+          <Choosing port={armed[1]} onCancel={() => setArmed(null)} />
+        )}
+        <Toolbar undoable={flow.undoable} redoable={flow.redoable}
+                 onAdd={() => setAdding({ at: { x: 16, y: 52 } })}
+                 onUndo={() => { setSelected(null); send("/undo", "POST") }}
+                 onRedo={() => { setSelected(null); send("/redo", "POST") }} />
+
+        <ConnectorLayer links={links} extent={extent} dragging={dragging}
+                        onInsert={(link) => setAdding({ from: link.source, to: link.target, at: { x: link.midX + 30, y: link.midY } })}
+                        onRemove={(link) => { setSelected(null); send("/edges", "DELETE", { from: link.source, to: link.target }) }}
+                        onDrop={(link) => { const held = dragging; setDragging(null); send("/steps/" + held + "/move", "PATCH", { from: link.source, to: link.target }) }} />
+
+        {loose.length > 0 && (
+          <div data-loose className="border border-dashed border-gray-300 bg-gray-50 dark:border-zinc-700 dark:bg-zinc-900" style={waiting}>
+            <div className="text-gray-500 dark:text-gray-400" style={{ fontSize: 11, marginBottom: 6 }}>Not in the flow yet — drag one onto a connection</div>
+            {loose.map((node) => (
+              <div key={node.id} style={{ marginBottom: 8 }}>
+                <StepCard
+                  node={{
+                    ...node,
+                    ref: (element) => { cards.current[node.id] = element },
+                    violations: violationsFor[node.id] || [],
+                    connected: []
+                  }}
+                  selected={selected === node.id}
+                  armed={armed && armed[0] === node.id ? armed[1] : null}
+                  connecting={Boolean(armed)}
+                  onSelect={() => (armed ? connectTo(node.id) : setSelected(node.id))}
+                  onArm={(port, event) => { event.stopPropagation(); setArmed([ node.id, port ]) }}
+                  onDragStart={() => setDragging(node.id)}
+                  onDragEnd={() => setDragging(null)} />
+              </div>
+            ))}
+          </div>
+        )}
+
+        <div style={{ ...grid, gridTemplateColumns: `repeat(${columns + 1}, ${(CARD + GAP_X) / 2}px)`, gridTemplateRows: `repeat(${rows}, auto)` }}>
+          {attached.map((node) => (
+            <div key={node.id} style={{ gridRow: node.row + 1, gridColumn: `${node.column + 1} / span 2`, zIndex: 2 }}>
+              {node.placeholder && (
+                <Placeholder node={{ ...node, ref: (element) => { cards.current[node.id] = element } }}
+                             dragging={Boolean(dragging)}
+                             onFill={() => setAdding({ from: node.from, on: node.on, at: { x: 16, y: 52 } })}
+                             onDrop={() => {
+                               const held = dragging
+                               setDragging(null)
+                               if (held) send("/edges", "POST", { from: node.from, to: held, on: node.on })
+                             }} />
+              )}
+              {!node.placeholder && <StepCard
+                node={{
+                  ...node,
+                  ref: (element) => { cards.current[node.id] = element },
+                  violations: violationsFor[node.id] || [],
+                  connected: flow.edges.filter((edge) => edge.source === node.id).map((edge) => edge.label || null)
+                }}
+                selected={node.id === selected}
+                armed={armed && armed[0] === node.id ? armed[1] : null}
+                connecting={Boolean(armed) && armed[0] !== node.id}
+                onSelect={() => (armed ? connectTo(node.id) : setSelected(node.id))}
+                onArm={(port, event) => {
+                  const frame = surface.current.getBoundingClientRect()
+                  setAdding({
+                    from: node.id, on: port,
+                    at: { x: event.clientX - frame.left + surface.current.scrollLeft + 8,
+                          y: event.clientY - frame.top + surface.current.scrollTop + 8 }
+                  })
+                }}
+                onDragEnd={() => setDragging(null)}
+                onDragStart={() => setDragging(node.id)}
+              />}
+            </div>
+          ))}
+        </div>
+
+        {adding && (
+          <TypePicker entries={flow.palette} at={adding.at} onDismiss={() => setAdding(null)}
+                      onConnect={adding.on !== undefined ? () => { setArmed([ adding.from, adding.on ]); setAdding(null) } : null}
+                      onPick={(entry) => {
+                        const where = adding
+                        setAdding(null)
+                        send("/steps", "POST", { id: nextId(entry.type, flow.nodes.map((node) => node.id)), type: entry.type, from: where.from, to: where.to, on: where.on })
+                      }} />
+        )}
+      </div>
+
+      {showing && !selectedNode && (
+        <Panel flow={flow.flow || {}} changes={flow.changes || []} problems={flow.violations} refusal={error} notice={notice}
+               onClose={() => setShowing(false)}
+               onCreate={() => send("/versions", "POST")}
+               onPublish={() => send("/publish", "POST")}
+               onSaveDetails={(details) => send("/details", "PATCH", { flow: details })} />
+      )}
+
+      {selectedNode && (
+        <Inspector node={selectedNode}
+                   fields={entryFor?.fields || {}} holds={entryFor?.records || {}}
+                   labels={entryFor?.labels || {}} recordLabels={entryFor?.record_labels || {}}
+                   choices={offeredTo(selectedNode, entryFor)}
+                   onClose={() => setSelected(null)}
+                   onSave={(config) => send(`/steps/${selectedNode.id}`, "PATCH", { config })}
+                   onDelete={() => { setSelected(null); send(`/steps/${selectedNode.id}`, "DELETE") }} />
+      )}
+    </div>
+  )
+}
+
+export default Canvas

data/app/javascript/alembic/canvas/Connector.jsx

@@ -0,0 +1,30 @@
+import React, { useState } from "react"
+import Button from "keystone_ui-react/src/Button.jsx"
+const round = { width: 24, height: 24, padding: 0, fontSize: 15, lineHeight: "15px" }
+
+const Connector = ({ link, onInsert, onRemove, onDrop, dragging }) => {
+  const [ over, setOver ] = useState(false)
+  const showing = over || dragging
+
+  return (
+    <div data-connector={`${link.source}-${link.target}`}
+         style={{ position: "absolute", left: link.midX - 34, top: link.midY - 20, width: 68, height: 40, zIndex: 4 }}
+         onMouseEnter={() => setOver(true)} onMouseLeave={() => setOver(false)}
+         onDragEnter={() => setOver(true)} onDragLeave={() => setOver(false)}
+         onDragOver={(event) => { event.preventDefault(); event.dataTransfer.dropEffect = "move" }}
+         onDrop={(event) => { event.preventDefault(); setOver(false); onDrop() }}>
+      <div style={{ display: "flex", gap: 4, justifyContent: "center", alignItems: "center", height: "100%",
+                    opacity: showing ? 1 : 0, transition: "opacity .12s" }}>
+        <Button variant="secondary" title={dragging ? "Move the step here" : "Insert a step here"} onClick={onInsert}
+                className="rounded-full data-[over=true]:ring-2 data-[over=true]:ring-accent-600"
+                data-over={Boolean(dragging && over)} style={round}>+</Button>
+        {!dragging && (
+          <Button variant="danger" title="Remove this connection" onClick={onRemove}
+                  className="rounded-full" style={round}>×</Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export default Connector