Skip to content

UC: Create Holon

Jump to bottom
Steve Melville edited this page Jun 20, 2025 · 13 revisions

Description: This use case enables a Human Agent to create a new Holon of a specified holon type, supplying values for its various properties and (via Issue #132) adding related holons via one or more holon relationships. In the future, the Human Agent will also be able to invoke dances offered by this Holon Type.

Actor: Human Agent

Preconditions:

  • Human Agent has selected Create Holon from the MAP Home Page.

Post-conditions:

  • A new holon has been persisted in the system and Holons have been added to relationships that the newly created holon is the SOURCE_FOR
  • OR... The request to create a new holon has been canceled and there are no changes to the persistent state.

Assumptions:

Main Flow

  1. This use case starts when a Human Agent selects Create Holon from the MAP Home Page.
  2. The system responds by presenting a Select Holon Type Dialog Box. This dialog box presents a scrollable list of HolonTypes and prompts the agents to select one as well as a Create New Type option
  3. The Human Agent selects the desired Holon Type.
  4. If the Human Agent selected Create New Type, follow Alternate Flow: Create New Type to create a new Holon Type. Otherwise, The system responds by presenting a Holon Node Visualizer that:
  • displays the various properties of the selected Holon Type and makes them available for editing via type-specific Property Visualizers
  • displays the various relationship types that the selected HolonType is a SOURCE_FOR and offers an Add Related Holons command for each. Issue #132
  1. The agent can add values for one or more properties or selects Add Related Holons for a relationship. If the latter, follow Alternate Flow: Add Related Holon. When all desired properties have been added, the agent selects Submit
  2. The system saves the definition of the Holon, including any of its relationships, and confirms the save.
  3. This use case ends.

Alternate Flows

Alternate Flow: Create New Type

This flow is followed when the Human Agent selects Create New Type. The context will make it clear what kind of new type (HolonType, PropertyType, ValueType, RelationshipType, ActionType) is being created.

THIS FLOW NEEDS TO BE DEFINED (PROBABLY AS AN INCLUDED USE CASE)

Alternate Flow: Add Related Holon -- Issue #132

This flow is followed when the Human Agent selects Add Related Holons for a specific relationship.

  1. The system responds by presenting a Select Related Holons Form for the specified relationship. This form presents a multi-select list of the available holons that are of a type eligible to be the target of the specified relationship. This form also offers Cancel and Submit buttons.
  2. The Human Agent selects one or more holons and hits Submit. If instead they hit Cancel, follow Alternate Flow: Abandon Adding Related Holons.
  3. The system validates that at least one holon was selected. If not, the system presents the "Select At Least One Related Holon Error Message" and returns to Step 1. Otherwise, the system stages (but does not commit) the specified target holonsrelationship change and resumes the Main Flow.

Alternate Flow: Abandon Adding Related Holons -- Issue #132

This flow is followed when the Human Agent selects Cancel from the Select Related Holons Form.

  1. The system responds by dismissing the Select Related Holons Form and resume the Main Flow at Step 4.

Wireframes

Select Holon Type Dialog Box

Holon Node Visualizer

Select Related Holons Form

Implementation Notes

🔧 Implementation Notes – Create Holon Use Case

🎯 Architectural Purpose

This use case serves as the first complete end-to-end demonstration of the DAHN dynamic, adaptive interface architecture. It exercises the full visualizer hierarchy and the DAHN Selector Function, and it introduces runtime composition of views based on holon metadata.

Specifically, this use case will:

  • Instantiate all major visualizer types (Canvas, Node, Property, Action, Value Type)
  • Drive UI construction using the DAHN Selector Function
  • Use a HolonType descriptor with its PropertyTypes (which reference ValueTypes) to generate an appropriate interface for editing and submitting a new holon
  • Set the groundwork for dynamic personalization and future integration with holon dances

🧩 Visualizer Usage Overview

Visualizer Type Usage in This Flow
Canvas Visualizer Already instantiated by View MAP Home Page; persists through this flow
Action Visualizer Renders form-level actions like "Submit", "Cancel", and "Add Related Holons"
Node Visualizer Renders the editable holon instance based on selected HolonType
Property Visualizer Used for each editable property; wraps and contextualizes the Value Type Visualizer
Value Type Visualizer Renders the input control based on the property's referenced ValueType
Collection Visualizer Used for selecting related holons in 1-to-many relationships (Issue #132)
Graph Visualizer Not required for MVP but relevant for future visual graph context

Visualizer Hierarchy

Canvas Visualizer (DAHN-2D Canvas Visualizer) │ ├── Action Visualizer (Page-Level Actions) │ ├── "Cancel" │ └── "Submit" │ └── Node Visualizer (HolonNodeVisualizer or Type-Specific) │ ├── Property Visualizer: "name" │ └── Value Type Visualizer: ShortString (TextInput) │ ├── Property Visualizer: "description" │ └── Value Type Visualizer: MarkdownString (MarkdownEditor) │ ├── Property Visualizer: "isActive" │ └── Value Type Visualizer: Boolean (RadioButtons or Toggle) │ ├── Property Visualizer: "createdOn" │ └── Value Type Visualizer: Date (DatePicker) │ ├── Property Visualizer: "profileImage" │ └── Value Type Visualizer: Image (ImageUploader/Preview) │ ├── Collection Visualizer: "tags" (if multi-valued) │ └── Value Type Visualizer: Enum/String (MultiSelectDropdown) │ └── Related Holon Section(s) ├── Action Visualizer: "Add Related Holons" └── Collection Visualizer: Related Holon Selector

🧠 Selector Function Behavior

Once the user selects a HolonType, the DAHN Selector Function is invoked to:

  • Choose the appropriate Node Visualizer for the holon type
  • For each PropertyType:
    • Select a Property Visualizer to contextualize the field (labeling, layout, etc.)
    • Select a Value Type Visualizer based on the referenced ValueType (e.g., ShortString, MarkdownString, Boolean)
  • Choose Action Visualizers for available form commands
  • (Optionally) Choose a Collection Visualizer for adding related holons

This runtime selection ensures the interface is assembled from modular parts based on metadata — no hardcoded form layouts or static UI definitions.

🏗 Runtime Construction Flow (Simplified)

  1. From the MAP Home Page, the user selects “Create New Holon”
    → Action Visualizer triggers the start of this use case

  2. System presents the Select Holon Type Dialog
    → A Collection Visualizer displays available HolonTypes with Action Visualizer buttons for selection

  3. User selects a HolonType
    → System fetches its descriptor and uses the Selector Function to:

    • Choose a Node Visualizer for the form layout
    • For each property:
      • Choose a Property Visualizer
      • Choose and embed the appropriate Value Type Visualizer
    • Choose Action Visualizers for “Submit” and “Cancel”
    • Optionally display “Add Related Holons” controls for applicable relationships

  4. User enters property values, optionally adds related holons (see Alternate Flow)

  5. User clicks Submit
    → Action Visualizer collects values, validates them, and invokes the appropriate MAP API to create the holon

  6. System persists the new holon and any staged relationships, then confirms success

🧪 Initial Visualizer Selection Example 

{
  "nodeVisualizers": {
    "default": "HolonNodeVisualizer"
  },
  "propertyVisualizers": {
    "default": "LabeledFormFieldPropertyVisualizer"
  },
  "valueTypeVisualizers": {
    "ShortString": "TextInputValueTypeVisualizer",
    "MarkdownString": "MarkdownEditorValueTypeVisualizer",
    "Boolean": "ToggleSwitchValueTypeVisualizer",
    "Integer": "NumericInputValueTypeVisualizer",
    "Date": "DatePickerValueTypeVisualizer",
    "Image": "ImageUploaderValueTypeVisualizer"
  },
  "actionVisualizers": {
    "default": "MaterialActionBar"
  },
  "collectionVisualizers": {
    "default": "HolonSelectorList"
  }
}

🔄 Alternate Flow Support (Issue #132)

When the user selects “Add Related Holons”:

  • The system presents a Collection Visualizer of eligible related holons
  • The user multi-selects one or more entries (or cancels)
  • The system stages the selected relationships but does not persist until the main form is submitted

This allows us to demonstrate dynamic subview injection and relationship-aware selection logic.

🛠 Personalization/Adaptivity (Optional for MVP)

Scaffold for future expansion:

  • Selector Function may optionally check for:
    • Agent-specific visualizer preferences
    • Crowd-sourced visualizer affinity data
  • Property ordering may be influenced by salience scores
  • Personalization controls may appear in the Node or Canvas Visualizers, even if not fully functional

🔗 Preceding and Downstream Use Cases

  • Preceded by: View MAP Home Page
  • May lead to: View Holon Details, Edit Holon, or other post-creation flows

Github Issues

MAP Holons

Clone this wiki locally