30:Tb19,// main (and the only mandatory) definition of this diagram's story myStory = new Story( ` # # Usecase 1: simple case of a linear timeline # Linear_Entity EventA EventB - UseCase # # Usecase 2: time-anchored timeline: events are written in _ syntax # Historic_Entity Event1990_1990 Event2000_2000 Event2020May_2020_05 - UseCase Future_Entity Event2050_2050 - UseCase # # Usecase 3: recurring visitor: if the same topic is referenced more than once, then a (dotted) line will be drawn between those references # Recurring_Visitor FavouritePlace FavouritePlace_a FavouritePlace_b - UseCase # # Usecase 4: Two Timelines merging (and branching) at a common event # Partner_A BothMeet2000_2000 - UseCase Partner_B BothMeet2000_2000 - UseCase # # Edge Case: Entity without Events, shall be shown as a single entity box; # # Note: this does not make much sense in a proper Timeline diagram # but could be a transitional state while you are writing a Timeline story and introduce a new Entity # Boring_Entity - UseCase # # Special Case: duplicate entity names receive distinct internal keys # Same_Name - rdfType: UseCase, labelPrefix: =, rdfDescription: first entity by the name Same_Name Same_Name - rdfType: UseCase, labelPrefix: =, rdfDescription: second entity by the name Same_Name which is assigned a different ID internally Same_Name - rdfType: UseCase, labelPrefix: =, rdfDescription: third entity by the name Same_Name # # Difficult_attributes (commented out for brevity) # # Difficult_attributes EventWithDash EventWithQuotes # # Syntax Error catches # ErrorEntity - a: b c: d # # testing different RDF types (commented out for brevity) # # aReplacement - replacement # anEducation - edu # aSchool - school # # Story Demo: short boat story, combining most of the features above # Shipyard Construction_1990 Construction_1991 MaidenVoyage - OU Agency Transfer_2000 - OU Boat Construction_1990 Construction_1991 MaidenVoyage Daysailing Transfer_2000 AtlanticCrossing - boat First_Owner MaidenVoyage Daysailing Transfer_2000 - person Second_Owner Transfer_2000 AtlanticCrossing - person Dog AtlanticCrossing - dog sailing MaidenVoyage Daysailing AtlanticCrossing - skill carpentry Construction_1990 Construction_1991 - skill - - - Timelines above / Event details below Transfer_2000: graphvizLabel: Sale/Purchase EventWithDash: rdfLabel: with-Dash htmlTooltip: with-Dash EventWithQuotes: rdfLabel: with"Quote MaidenVoyage: Maiden Voyage Construction_1990: - Construction - | of the boat which can have multiple lines or paragraphs of description Construction_1991: finish ` )31:T27f8,/* * create an instance from a story, then typecast to String or call toString() directly */ class StoryToDotRenderer extends DotRenderer { story constructor( story ) { super() switch( typeof story ) { case 'object': this.story = story break; case 'string': this.story = new Story( story ) break; default: throw( new Error( "invalid datatype of story" ) ) } } /* * render Gryphviz code suitable for "DOT" */ toString() { return ` digraph { ranksep=0.1 nodesep=0.2 node [shape=none tooltip=""] ${ title_dot } # # Events (Time+Space intersections) with labels (other than their ID) or tooltips # ${ this.render_event_details() } # # Timelines from here # edge [color=grey] # default edge color grey to recognize all which are not styled explicitly edge [arrowhead=none] # timelines have not arrowhead in all of their sections, except for the very last one (pointing to the future) # # topics timelines must appear before PEOPLEs' timelines, # so that first appearance (event) of a place can serve as its type anchor; # events are disjunct by definition, because topics can never "meet" each other # { edge [ style=${ diagram_options?.places_edge_style ?? `""` } ] ${ this.render_topics() } } # end topics # # entities (people / beings / things) : typically solid lines; # events may be shared because entities can meet/touch each other at the same place (or topic) + time # { edge [ style=${ diagram_options?.entity_edge_style ? diagram_options?.entity_edge_style : `""` } ] ${ this.render_entities() } } ${ this.render_timescale() } ${ this.render_time_anchors() } }` } // render details for all occuring events (after applying entity filter) render_event_details() { const events_entity_m = this.story.event_entity_map let result = "" Array.from(events_entity_m.keys()).forEach ( k => { if( is_visible( k, this.story ) ) { const event_json = this.story.events_json[k] // which is optional // properties of this event node will be either created from scratch, or extend the explicit event definition const properties = event_json ? this.constructor.translate_nodeValues_to_dotValues( event_json ) : new Map() const entities = Array.from( events_entity_m.get(k) ) // all entities which share this event - guaranteed to be at least one const classlist = new Array(); if ( diagram_toggles.includes( highlight_all_timelines_of_event ) || entities.length === 1 ) { entities.forEach( e => classlist.push( "global_type_" + e ) ); } const tokens = k.split('_'); if( has_date_part(tokens) ) classlist.push( "type_date_" + tokens.slice(1).join('_') ); if( classlist.length > 0 ) properties.set( "class", classlist.join(' ') ); if( ( tokens.length > 1 || properties.size === 0 ) && !properties.has( "label" ) ) properties.set( "label", tokens[0] ); // present event by its topic name if( Array.from( properties.keys() ).length ) { result += ` ${k} [`; properties.forEach( (v,p) => result += `${p}="${ DotRenderer.to_dot_label_raw( v )}" ` ); result += `]`; } } // end if } // end foreach function ) // end foreach return result; } render_topics() { let result = ` # # Topics # `; this.story.topic_events_map.forEach ( (event_map, topic) => { const sorted_events = Array.from( event_map ).sort().reduce ( (a,c) => { if( this.story.event_entity_map.get( c ) ) a.push( c ); return a; } , [] ); if( sorted_events.length > 1 ) result += this.render_timeline( topic, sorted_events, {showExit:false, showEntry:false} ); } ); return result; } render_entities() { return this.story.entity_keys.reduce ( (a,c) => a + this.render_timeline( c, this.story.entity_timelines, diagram_options ) , "" ) } /* * renders timescale as a vertical stack of Date values; * * not possible to pack these Dates in a cluster, * because they are also members of the time_anchor subgraphs * which prevents other subgraph memberships */ render_timescale() { const visible_date_labels = new Set() this.story.event_entity_map.forEach ( (entities, event) => { if( is_visible( event, this.story ) ) harvest_dates_from_event( event, visible_date_labels ) } ) if( visible_date_labels.size === 0 ) return ""; let result = ` # # Time # { time_entity [label=Time style=rounded shape=box color=lightgrey fontcolor=lightgrey] edge [color=lightgrey arrowhead=none] node [fontsize=10] `; let prev = ""; const sorted_dates = Array.from( visible_date_labels ).sort(); sorted_dates.forEach ( date => { const datevalue = new Date(date.replaceAll('_',"-")); const date_dot_format = (datevalue.getTime() > Date.now()) ? " fontcolor=lightgrey" : ""; const tokens = date.split('_'); switch( tokens.length ) { case 1: result += ` D${date} [class=type_date_${date} label=${tokens[0]} fontsize=16${date_dot_format}]` break; // we don't declare years because key = label case 2: result += ` D${date} [class=type_date_${date} label=${ datevalue.toLocaleString('default', { month: 'short' }) }${date_dot_format}]` break; case 3: result += ` D${date} [class=type_date_${date} label=${tokens[2]}.${date_dot_format}]` break; } prev = date; } ); result += ` time_entity -> D` + sorted_dates.join("->D"); result += ` node [style=invis] edge [style=dotted arrowhead="" minlen=2] D${sorted_dates[sorted_dates.length-1]} -> time_entity_future } `; return result; } render_time_anchors() { let result = ""; this.story.topic_events_map.forEach ( event_map => { const sorted_events = Array.from( event_map ).sort(); sorted_events.forEach ( event => { if( is_visible( event, this.story ) ) { const tokens = event.split('_'); if( has_date_part( tokens ) ) { result += ` {rank=same D${ tokens.slice(1).join('_') } ${ event } } `; } } } ); } ); return result; } /* * abstraction for rendering either an entity's timeline, or a topic's */ render_timeline( rdfLabel_or_id, events_or_timelines_object, options = {} ) { let events; let timelines; if( Array.isArray( events_or_timelines_object ) ) events = events_or_timelines_object; else timelines = events_or_timelines_object; let rdfLabel let color="" const structured_timeline = timelines ? timelines[rdfLabel_or_id] : false; if( structured_timeline ) // entity timelines { const index = Object.keys(timelines).indexOf( rdfLabel_or_id ); if( structured_timeline.options ) options = structured_timeline.options; options.id = rdfLabel_or_id; if( Array.isArray( structured_timeline ) ) events = structured_timeline; else events = structured_timeline.events; rdfLabel = structured_timeline?.options?.rdfLabel ? structured_timeline?.options?.rdfLabel : options.id; color = options.color ?? "" let edge_option = options.edge ?? ""; if( ! edge_option.includes( "color=" ) ) options.edge = `${ edge_option } color="${ color }"` } else // topic timelines { rdfLabel = rdfLabel_or_id; } const filtered_events = events.filter( e => is_visible( e, this.story ) ) if( filtered_events.length === 0 && events.length > 0 ) return "" // if the number of events shrank to zero due to filtering: dont show the entity at all / but if the entity's event count has been zero before filtering, then it was the author's intention to show the entity events = filtered_events const id = id_from_options_or_label( rdfLabel, options ); const minlen = options.minlen ?? 2; const dotLabel = options.labelPrefix ? options.labelPrefix + ' ' + rdfLabel : rdfLabel; const shape = options.shape ?? options.labelPrefix ? "none" : "box"; const endNode = options.endNode ?? id + "_future"; const showEntry= options.showEntry ?? diagram_options.showEntry ?? true; const showExit = options.showExit ?? diagram_options.showExit ?? events.length > 0; // don't show future-arrow for entities without events const color_clause = color ? ` color="${ color }"` : "" return ` { node [ class=global_type_${id} ${ options.node ?? "" } ] edge [ class=global_type_${id} ${ options.edge ?? "" } tooltip="${dotLabel}" ] ${ events.length && diagram_options.render_terminal_event_boxed ? ` ${ events[ events.length-1 ] } [shape=box${ color_clause }]` : "" } ${ render_entrynode() }${ events.join("->") }${ render_exitnode() } } `; // end return expression function render_entrynode() { return showEntry ? `${id} [${ id != dotLabel ? `label="${ dotLabel }" `:""}${ options.rdfDescription ? `tooltip="${ options.rdfDescription }" ` : "" }shape=${ shape }${ color_clause }] ` + connect_entrynode_with_first_event() : "" } function connect_entrynode_with_first_event() { return events.length > 0 ? `${id} -> ${events[0]} [penwidth=1${ diagram_options.entryArrowtail ? ` arrowtail=${ diagram_options.entryArrowtail }` : ""}] ` : "" } function render_exitnode() { return showExit ? ` node [style=invis] edge [style=dotted arrowhead=""${diagram_options?.future_pointer_minlen != 1 ? " minlen="+diagram_options?.future_pointer_minlen : ""}] ${ events[events.length-1] }->${endNode}` : "" } } }32:T4569,class Story { // full set of all timelines // never filtered in base class and always constant // entries are parsed from "story" text in parse_timeline() entity_timelines = {} events_json // assigned in constructor, parsed in split_story topic_events_map // assigned in harvest_story event_entity_map // assigned in harvest_story static story_delimiter = /- - -.*/ static color_12_paired = ['#a6cee3','#1f78b4','#b2df8a','#33a02c','#fb9a99','#e31a1c','#fdbf6f','#ff7f00','#cab2d6','#6a3d9a','#ffff99','#b15928'] static color_12_set3 = ['#8dd3c7','#ffffb3','#bebada','#fb8072','#80b1d3','#fdb462','#b3de69','#fccde5','#d9d9d9','#bc80bd','#ccebc5','#ffed6f'] static color_12_set3_minus_yellow = ['#8dd3c7','#bebada','#fb8072','#80b1d3','#fdb462','#b3de69','#fccde5','#d9d9d9','#bc80bd','#ccebc5','#ffed6f'] // found yellow too hard to read on most screens static color_palette = this.color_12_set3_minus_yellow; constructor( story_text_or_object, selected_entities_or_everything_flag = true ) { switch( typeof story_text_or_object ) { case 'string': // initial constructor, reading story via text const story_text = story_text_or_object const story_parts = this.constructor.split_story( story_text ) this.events_json = story_parts[1] story_parts[0].split("\n").forEach( l => this.constructor.parse_timeline( l, this.entity_timelines ) ) this.calculate_entity_keys() this.harvest_story( this, selected_entities_or_everything_flag ) // depends on entity_keys, produces topics and events maps break; case 'object': // "copy constructor" this.events_json = story_text_or_object.events_json this.entity_timelines = story_text_or_object.entity_timelines this.calculate_entity_keys() this.topic_events_map = story_text_or_object.topic_events_map this.event_entity_map = story_text_or_object.event_entity_map break; default: throw( new Error( "invalid argument type" ) ) break; } this.calculate_derived_fields( selected_entities_or_everything_flag ) } calculate_entity_keys() { this.entity_keys = Object.keys( this.entity_timelines ) } calculate_derived_fields( selected_entities_or_everything_flag ) { this.all_entity_types = [... new Set( this.entity_keys.map( e => this.type_of( e ) ) ) ] this.selected_entity_keys = selected_entities_or_everything_flag === true ? this.entity_keys : selected_entities_or_everything_flag // by default (in base Story): all entities are 'selected' this.n_topics = [...this.topic_events_map.keys()].length this.entities_map = new Map ( Object.entries( this.entity_timelines ).filter ( e => this.selected_entity_keys.includes( e[0] ) ) ) } keep_types = type_array => this.constructor.filter_types( type_array, this.entity_timelines, true ) hide_types = type_array => this.constructor.filter_types( type_array, this.entity_timelines, false ) type_of = ( entity ) => this.entity_timelines[entity]?.options?.rdfType date_labels = () => { const result = new Set() this.event_entity_map.forEach ( (entities, event) => { harvest_dates_from_event( event, result ) } ) return result } static split_story = text => { // split the text at a delimiter line that starts with "- - -" and return an array of two elements: // // first array element is the text before the delimiter line (or the full text in absence of delimiter) // second array element is a JSON object, parsed as YAML from the text after the delimiter line // the delimiter line is not returned const split = text.split( this.story_delimiter ) return [ transform_paragraphs_to_lines( split[0] ) , Object.fromEntries( Object.entries( yaml`${ split[1] }` ).map( ([k,v]) => [k,this.substitute(v)] ) ) ] /* * transform "multi-line timeline syntax" (a) into "single-line timeline syntax" (b), where in... * (a) each Timeline can be written as consecutive lines; 2 or more consecutive linebreaks separate Timelines * (b) each Timeline must be written in a single line; Timelines are separated by 1 or more linebreaks */ /*static*/ function transform_paragraphs_to_lines(text) { return text .split("\n\n") .map( block => block.split("\n").join(' ') ) .join("\n\n") } } // end split_story // harvesting Maps of Events and Topics from structured timelines harvest_story( result ) { const topics = new Map(); const u_event_entity_map = new Map(); this.entity_keys.forEach( c => this.constructor.harvest_timeline( c, this.entity_timelines, topics, u_event_entity_map ) ) result.topic_events_map = new Map ( Array.from ( topics.entries() ).sort ( (a, b) => { const e_a = a[1].entries().next().value[0] const e_b = b[1].entries().next().value[0] if( e_a.split('_').length>0 && e_b.split('_').length>0 ) return datepart_from_event( e_b ).localeCompare( datepart_from_event( e_a ) ) else if( this.common_entities( u_event_entity_map, e_a, e_b).length > 0 ) { const common_e = this.common_entities( u_event_entity_map, e_a, e_b)[0] return this.entity_timelines[ common_e ].events.indexOf( e_b ) - this.entity_timelines[ common_e ].events.indexOf( e_a ) } else if( has_date_part(e_a) ) // and not e_b per previous test return -1 else if( has_date_part(e_b) ) // and not e_a per previous tests return +1 return 0; } ) ) result.event_entity_map = new Map ( Array.from ( u_event_entity_map.entries() ).sort ( (a, b) => datepart_from_event( a[0] ).localeCompare( datepart_from_event( b[0] ) ) ) ) } /* harvest information about (shared) events and topics by parsing timeline by timeline */ static harvest_timeline( id, timelines, topics, event_entity_map ) { const structured_timeline = timelines[ id ] const options = structured_timeline.options ?? {} options.id = id; const rdfLabel = options.rdfLabel ?? options.id; if( ! (options.edge ?? "").includes( "color=" ) ) { options.color = this.color_palette [ Object.keys(timelines).indexOf( id ) % this.color_palette.length ] } structured_timeline.events.forEach( e => this.parse_event( e, id, topics, event_entity_map ) ) } // end harvest_timeline // harvest information about event into topics and entities maps static parse_event( event, entity, topics, event_entity_map ) { let entities_for_event = event_entity_map.get( event ); if( entities_for_event ) entities_for_event.add( entity ); else entities_for_event = new Set( [entity] ) event_entity_map.set( event, entities_for_event ) const tokens = event.split('_'); let events_for_topic = topics.get( tokens[0] ); if( events_for_topic ) events_for_topic.add( event ); else events_for_topic = new Set( [event] ) topics.set( tokens[0], events_for_topic ); } first_notice_of = entity => this.entity_timelines[entity].events[0].split('_').slice(1) // return the split datepart of the first event in the given entity's timeline event_details_map() { return new Map ( Object.entries( this.events_json ).map( ( [key, value] ) => [ key, dot_from_event_json( value ) ] ) ) /*static*/ function dot_from_event_json(value) { return '[' + dotFromEntryIfExists( value, "graphvizLabel", "label" ) + dotFromEntryIfExists( value, "graphvizShape", "shape" ) + dotFromEntryIfExists( value, "cssClasslist" , "class" ) + dotFromEntryIfExists( value, "htmlTooltip" , "tooltip" ) + ']' /*static*/ function dotFromEntryIfExists( json, jsonName, graphvizName ) { return json[ jsonName ] ? `${graphvizName}="${ json[ jsonName ] }" ` : "" } } } // end event_details_map create_grouped_input( label = htl.html`selected elements, grouped by type`, values_if_not_passed_in_url ) { const groups = new Set; const format = (d) => { const group = d[1].options.rdfType const name = d[0] const label = html`${name}`; (groups[group] || (groups[group] = [])).push(label); return label; }; function create_input( subjects, defaults = Object.keys(subjects) ) { return Inputs.checkbox ( Object.entries( subjects), { value: get_initial_details( defaults ) , valueof: ([a]) => a , format } ) } const input = create_input( this.entity_timelines, values_if_not_passed_in_url ) const parent = input.lastElementChild; const scope = DOM.uid().id; input.classList.add(`${scope}-input`); const style = html` ` } ) static create_date_text_input = ( label, values_if_not_passed_in_url, index ) => Inputs.text ( { label:label, value: (get_initial_url_param('date_range') ?? [undefined,undefined])[index] ?? values_if_not_passed_in_url[index], maxlength:10, placeholder:"YYYY-MM-DD", pattern:"[0-9]{4}(-[01][0-9](-[0-3][0-9])?)?" } ) /* * * static functions * */ static filter_types( type_array, entities_map, keep_or_hide /* true -> keep; false -> hide*/ ) { return Array.from( Object.entries( entities_map ).reduce ( ( a, [key,value] ) => ( ( type_array.includes( value?.options["rdfType"] ) ) == keep_or_hide ) ? a.add(key) : a , new Set() ).values()) } // return array of common entities which have both events in their timelines static common_entities(event_entity_map, event_a, event_b = event_a) { const entities_a = event_entity_map.get( event_a ) ?? new Set() const entities_b = event_entity_map.get( event_b ) ?? new Set() return [...entities_a].filter( entity => entities_b.has(entity) ) } // parse the text from a single timeline into a structured object // and store under its key in the timelines (container) object static parse_timeline( timeline_text, timelines ) { timeline_text = Text.trim_line( timeline_text ); if( timeline_text == "" || timeline_text.startsWith("#") ) return; let options = {} let timeline_text_options = timeline_text.split(" - "); timeline_text = timeline_text_options[0]; if( timeline_text_options.length > 1 ) { const options_string = timeline_text_options[1].replaceAll("'",`\\"`); if( /^[a-zA-Z]+$/.test(options_string) ) options = { rdfType: options_string }; else try { options = yaml`{ ${options_string} }` } catch( e1 ) { try { options = JSON.parse( "{" + options_string + "}" ); } catch( e2 ) { options = { rdfType:"Syntax_Error", labelPrefix:"⛔", rdfDescription:"YAML and JSON parsing errors, see browser console for details" }; console.error(e1) console.error(e2) } } } options = Object.assign( {}, entity_default_properties_by_type.get( options.rdfType ) ?? {}, options ) // assigning default properties first, so that explicit properties in the options object may override default properties const tokens = timeline_text.split(' '); const rdfLabel = tokens[0]; tokens.shift(); let id = this.find_available_key( timelines, id_from_options_or_label( rdfLabel, options ) ); if( id !== rdfLabel ) options.rdfLabel = rdfLabel; timelines[ id ] = { events : tokens, options : options }; return timelines[ id ]; } // end parse_timeline /* recursively generate a key which is not in use yet */ static find_available_key( object, key_name, key_suffix = "" ) { return object[ key_name + key_suffix ] ? this.find_available_key( object, key_name, (key_suffix==""?0:key_suffix)+1 ) : key_name + key_suffix } /* expand event-detail JSON shorthands with explicit name-value maps */ static substitute( v ) { switch( typeof v) { case "string": switch( v ) { case "finish" : return { ktsRole : "finish" , graphvizShape : 'none' , graphvizLabel : '🏁' , htmlTooltip : "finish" // of that topic } default : return { rdfLabel : v } } case "object": if (Array.isArray(v)) { return this.create_event_object( ... v ) } return v } } static create_event_object = (label, description ) => { const view_summary = project_lod == "title only"; const rdfDescription = description; const rdfLabel = label; const labelAndDescription = rdfDescription ? `${rdfLabel}: ${rdfDescription}` : rdfLabel const start_event_o = { rdfLabel, graphvizShape : ( label[0].search(/[a-zA-Z0-9]/) // if label begins with non-alpha character (an icon) then don't use boxed shape ? "none" : rdfDescription ? "note" : "none" // if there is NO rdfDescription then we don't render the event with the visually heavier box because the event won't expand to a larger box in "details" mode ) } if( rdfDescription ) start_event_o.rdfDescription = rdfDescription if( view_summary ) { start_event_o.graphvizLabel = rdfLabel if( rdfDescription ) start_event_o.htmlTooltip = labelAndDescription } else { start_event_o.graphvizLabel = labelAndDescription } return start_event_o } get_flavour( type = "skill" ) { const flavours = this.entity_keys.filter( e => this.type_of( e ) == type ) switch( flavours.length ) { case 1: return ", flavour: " + flavours[0] case 2: case 3: return ", featuring " + flavours.join( " + " ) + (type === 'person' ? "" : " " + type + 's') default: return "" } } }33:T529,class EntityReducedStory extends Story { constructor( story, selected_entities ) { super( story, selected_entities ) // now narrow the fields this.entity_timelines = Object.fromEntries( this.entities_map.entries() ) // recreate the reduced timelines object this.calculate_entity_keys() this.harvest_story( this ) // depends on entity_keys, produces topics and events maps this.calculate_derived_fields( selected_entities ) this.all_topics_details = Array.from ( this.topic_events_map.keys() ).map ( topic => get_topic_details( topic, story.entity_timelines, this.topic_events_map, story.events_json ) ) this.all_topicdetails_keys = new Set( this.all_topics_details.reduce( (acc, topicdetails) => acc.concat( [...topicdetails.keys() ] ), [] ) ) } /* is_event_visible = event => (this.event_entity_map.get( event ).size > 1 || !diagram_toggles.includes( only_shared_events ) ) && (date_range[0] == "" || -1 < datepart_from_event( event ).replaceAll('_','-').localeCompare( date_range[0].toISOString ? date_range[0].toISOString() : date_range[0] ) ) && (date_range[1] == "" || 1 > datepart_from_event( event ).replaceAll('_','-').localeCompare( date_range[1].toISOString ? date_range[1].toISOString() : date_range[1] ) ) */ }34:Tb03,function get_topic_details( topic, all_entities, topic_events_map, events_json ) { // making the inner function available for unit testing get_topic_details.group_entities_by_type = group_entities_by_type if( !arguments.length ) return // this call was just to initialize above assignment const events_for_topic = [ ... topic_events_map.get(topic).values() ] const e1 = events_for_topic[0] const e2 = events_for_topic.slice(-1)[0] const result = new Map( Object.entries( events_json[ e1 ] ?? {} ) ) const d1 = has_date_part(e1) ? e1.split('_')[1] : "" result.set( "begin", d1 ) let dx = '' if( has_date_part( e2 ) ) { try { const d2 = e2.split('_')[1] if (d2 > d1) result.set( "end", `→ ${d2}` ) } catch (error) { /* optional end date is defined */ } } const other_entities_for_event = find_entities_by_event( e1, all_entities, central_entity ); const org_un = filter_entities_by_type( "OU", other_entities_for_event, all_entities ) const school = filter_entities_by_type( "school",other_entities_for_event, all_entities ) const related_entities_by_type = group_entities_by_type( other_entities_for_event, all_entities ) let description let label = topic if( events_json[ e1 ] ) { description = events_json[ e1 ].rdfDescription label = events_json[ e1 ].rdfLabel ?? events_json[ e1 ].graphvizLabel ?? events_json[ e1 ].label ?? topic } result.set( "label", label ) if( description ) result.set( "description", description.split( "\n\n" ) ) const client = org_un.concat( school ).map ( e => all_entities[e].options.rdfLabel ?? e ) if( client.length ) result.set( "client", client ) related_entities_by_type.forEach ( (entities, type) => set_map_if_related_entities_of_type( result, type , related_entities_by_type ) ) return result /*static*/ function filter_entities_by_type( type, candidates_array, all_entities ) { return candidates_array.filter ( key => all_entities[key].options.rdfType == type ) } /*static*/ function set_map_if_related_entities_of_type( map, type, related_entities_by_type ) { const related_entities = related_entities_by_type.get( type ) if( related_entities ) map.set( type, related_entities.join(", ") ) } /*static*/ function group_entities_by_type(candidates_array, all_entities) { return candidates_array.reduce ( (map, candidate) => { const key = all_entities[candidate].options.rdfType; map.has( key ) ? map.get( key ).push( candidate ) : map.set( key , [candidate] ); return map; }, new Map()); } }35:Taac,// NOTE: can't refactor this into class myEntityReducedStory because that results in circular definition //(which I could not figure out yet) tabular_view = ( column_names = [], title_names = [] ) => { return d3.create('table').attr( "style", "max-width:100%" ).classed( "timeline_tabular_view", true ) .call(table => { table.append('thead').append('tr').classed('header', true).call(headerline => { if( column_names[0] ) headerline.append('th').text( title_names[0] ?? translate_type(column_names[0]) ) if( myEntityReducedStory.all_topicdetails_keys.has( "begin" ) ) headerline.append('th').text( translate_type( "begin" ) ) if( myEntityReducedStory.all_topicdetails_keys.has( "end" ) ) headerline.append('th').text('End').style( 'text-align','right') headerline.append('th').text( translate_type( "label" ) ) if( myEntityReducedStory.all_topicdetails_keys.has( "description" ) ) headerline.append('th').text('Description').style("width","70%") if( column_names[1] ) headerline.append('th').text( title_names[1] ?? translate_type(column_names.slice(-1)[0]) ) }) }) // end header .call(table => { table.append('tbody') .selectAll('tr') .data ( Array.from ( myEntityReducedStory.topic_events_map.entries() ) .filter( ([topic,events]) => is_visible( [... events.values()][0], myEntityReducedStory ) ) .map ( ([topic, events]) => get_topic_details( topic, myStory.entity_timelines, myEntityReducedStory.topic_events_map, myStory.events_json ) ) ) .join('tr') .call(line => { if( column_names[0] ) line .append('td') .text( topic => topic.get( column_names[0] ) ) if( myEntityReducedStory.all_topicdetails_keys.has( "begin" ) ) line .append('td') .text( topic => topic.get("begin") ) if( myEntityReducedStory.all_topicdetails_keys.has( "end" ) ) line .append('td') .text( topic => topic.get( "end" ) ) line .append('td') .append('b') .text( topic => topic.get( "label" ) ) if( myEntityReducedStory.all_topicdetails_keys.has( "description" ) ) line .append('td') .selectAll('p') .data( topic => topic.get( "description" ) ?? [] ) .join('p') .text(description => description) if( column_names[1] ) line .append('td') .text( topic => topic.get( column_names.slice(-1)[0] ) ) }) // end topic line }) // end tbody .node() // of table, that is }36:Te97,notes = md`## How to read this Timeline diagram Like street maps, a Timeline diagram is typically **large**. That's why it works best with a larger screen (pc / laptop). The diagram may tell a story of _epic_ dimension, so it takes some time to read. All **Lines** in this diagram represent a section of the life of an **entity** (person, place, vehicle or other types), as a chain of **events** over **time**. We could call each entity's timeline its _biography_ or _story_. Similar to a novel, a Timeline diagram may contain a single storyline or it may contain several related stories. _${this_particular_diagram}_ **Time** flows from bottom to top. On the diagram's left edge there is a rough indicator of calendar time. Not all events in the diagram are precisely aligned with a calendar date, and the time axis is certainly not proportional. An entity's timeline typically begins with the **_entity's name_** and ends in a dotted line with an **_ending arrow_**. People's timelines always begin with the name in a rounded box. Other entities may carry a type icon in front of their name (like 🇩🇰 for the country of Denmark or ⛵ for a sailing vessel). Peoples' timelines are shown with a solid line (because life is continuous). Places' lines are dotted (because they are secondary and because places only travel in time - never in location). The travel path of a vehicle is shown as a dashed line (because the vehicle does not have its own intention but is steered by a captain or driver). Some timelines have specific colours (like dark-blue for Maru) or colour sequences (like blue-yellow for Sweden). All other timelines are assigned random colors. ### Events Obviously timelines can meet, cross or depart from each other at a certain **Event**. This happens when people meet people, or people arrive at (or leave) places. An event is always part of one timeline. It may intersect several timelines. An event is always located at some place and it happens at a certain time. Depending on what is most relevant for the story, an event may be presented by its location (like _Ystad_, where Maru has been only once in May 2022). Second visits to the same place may be abbreviated with an ellipsis "..." (like in the case of _Simrishamn_ between November 2021 and May 2022). Or the event may be collapsed to a dot with no text at all (like my return to _Großenbrode_ at the end of October 2021). Events may alternatively be described by a significant activity (like _leaving Simrishamn_), or show the ⚓ icon for anchoring stops, "X" for crossings, the 🔧 icon for repairs and the ${symbol_major_incident} icon for major incidents. Underlined events show a "tooltip" with more explanation when hovering with your mouse _(not available on smartphones or other touch devices without a mouse)_. ### Interaction Timeline diagrams are **interactive**. You can hover with your mouse cursor (on a pc) over any **_entity name_**, **_ending arrow_**, **_connecting lines_** or some **_events_** (no mouse-click needed). Hovering will highlight exactly this one entity's timeline. The console box (lower left corner) will show the entity's name. In addition, you can click on the active elements to make the highlight more permanent. This way, you can click on more than one entity and explore those events which are shared by these entities. _Hovering is not available on touch devices (lacking a pointing device such as a mouse), but you can always click (brief touch) on those devices._ ### Generative Timeline diagrams are automatically generated (in this case by KTS). This is needed for interactive features. Generating the diagram from structured data simplifies editing and extending large diagrams.`37:[] 2e:{"title":"Timelines Library v 3","cells":[{"id":0,"value":"title = md`# Timelines Library v 3`","pinned":false,"hidden":false,"mode":"ojs"},{"id":4136,"value":"flavour = myEntityReducedStory.get_flavour()","pinned":false,"hidden":false,"mode":"ojs"},{"id":1399,"value":"kts_console","pinned":false,"hidden":false,"mode":"ojs"},{"id":5761,"value":"diagram_full_story = dot2svg ( new StoryToDotRenderer( myStory ) )","pinned":false,"hidden":false,"mode":"ojs"},{"id":2573,"value":"bookmark_current = htl.html`

bookmark current set of details

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3405,"value":"viewof selected_entities = myStory.create_grouped_input()","pinned":false,"hidden":false,"mode":"ojs"},{"id":3443,"value":"viewof type_buttons = myStory.create_type_buttons( viewof selected_entities, selected_entities, 9 )","pinned":false,"hidden":false,"mode":"ojs"},{"id":5784,"value":"quick_select_buttons = Inputs.button\n( \n [\n [ \"none\", () => set_input_value( viewof selected_entities, [] ) ]\n ,\n [ \"all\", () => set_input_value( viewof selected_entities, myStory.entity_keys ) ]\n ]\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3559,"value":"viewof date_range = myStory.create_date_range( /* optional defaults like [ \"1999\", \"2050\" ] */)","pinned":false,"hidden":false,"mode":"ojs"},{"id":2598,"value":"viewof diagram_toggles = Inputs.checkbox( [only_shared_events,highlight_all_timelines_of_event] )","pinned":false,"hidden":false,"mode":"ojs"},{"id":3032,"value":"viewof project_lod = Inputs.radio([\"title only\", \"full description\"], {label: \"level of detail\", value: \"title only\"})","pinned":false,"hidden":false,"mode":"ojs"},{"id":713,"value":"diagram_reduced_story = dot2svg\n(\n new StoryToDotRenderer( myEntityReducedStory )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3278,"value":"⇧ above: Timeline Diagram in visual language\n\n⇩ below: tabular view of events, some of their details and related entities","pinned":false,"hidden":false,"mode":"md"},{"id":5007,"value":"topics_count = md`showing ${ myEntityReducedStory.n_topics } out of total ${ myStory.n_topics } topics`","pinned":false,"hidden":false,"mode":"ojs"},{"id":3256,"value":"timeline_tabular = tabular_view( [\"person\",\"OU\"] )","pinned":false,"hidden":false,"mode":"ojs"},{"id":1027,"value":"## Story Definition","pinned":false,"hidden":false,"mode":"md"},{"id":1621,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":1300,"value":"// shows up in the notes cell\nthis_particular_diagram = \"This particular diagram has examples and testcases for the Timelines Library\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":3408,"value":"// customization of the table view's headers\nroles_dict = \n{ return { // this brace must be on same line as return statement !!\n \"OU\" : \"Organization\"\n ,\n \"begin\" : \"Start\"\n ,\n \"label\" : \"Place / Topic / Project\"\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3029,"value":"## Implementation","pinned":false,"hidden":false,"mode":"md"},{"id":2433,"value":"maximap = render_maximap_div()","pinned":true,"hidden":false,"mode":"ojs"},{"id":5021,"value":"### Classes","pinned":false,"hidden":false,"mode":"md"},{"id":4817,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":5591,"value":"class DotRenderer\n{\n static to_dot_label_raw = string => string.replace(/(?:\\r\\n|\\r|\\n)/g, '\\\\n').replace(/\"/g, '\\\\\"')\n \n static translate_nodeValues_to_dotValues( node_o )\n {\n const result = new Map( Object.entries( node_o ) )\n remap( \"rdfLabel\", \"label\" )\n remap( \"graphvizLabel\", \"label\" )\n \n remap( \"graphvizShape\", \"shape\" )\n remap( \"rdfDescription\",\"tooltip\" )\n remap( \"htmlTooltip\" , \"tooltip\" )\n return result\n \n function remap(from_name, to_name)\n {\n if( result.has( from_name ) )\n result.set( to_name ,\n result.get( from_name )\n )\n }\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":5708,"value":"class Text\n{\n static trim_line = string => string.trim().replace(/\\s+/g, ' ')\n \n static truncate = (string, length = 12) => (\"\"+string).length < length+4 ? (\"\"+string) : (\"\"+string).slice(0, length) + '…' \n \n static capitalizeString = str => (\"\"+str).charAt(0).toUpperCase() + (\"\"+str).slice(1);\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":4143,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":4525,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":5054,"value":"### Instances","pinned":false,"hidden":false,"mode":"md"},{"id":3626,"value":"myEntityReducedStory = new EntityReducedStory( myStory, selected_entities )","pinned":false,"hidden":false,"mode":"ojs"},{"id":3547,"value":"### (String) constants","pinned":false,"hidden":false,"mode":"md"},{"id":1292,"value":"symbol_major_incident = '⚠️' // '💀' // '💥'","pinned":false,"hidden":false,"mode":"ojs"},{"id":3441,"value":"only_shared_events = \"only shared events\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":3440,"value":"highlight_all_timelines_of_event = \"highlight all timelines of event\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":2244,"value":"### functions","pinned":false,"hidden":false,"mode":"md"},{"id":3518,"value":"#### 'static' (no dependencies)","pinned":false,"hidden":false,"mode":"md"},{"id":1514,"value":"/*static*/ function id_from_options_or_label( rdfLabel, options = {} )\n{\n return options.id ?? rdfLabel.replaceAll( ' ',\"\" )\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":2680,"value":"/*static*/ datepart_from_event = event => event.split('_').slice(1).join('_')","pinned":false,"hidden":false,"mode":"ojs"},{"id":3431,"value":"/*static*/ harvest_dates_from_event = (event_key, dates ) =>\n{\n const tokens = event_key.split('_')\n\n if( has_date_part( tokens ) ) \n {\n const date_tokens = tokens.slice(1);\n dates.add( date_tokens.join('_') ); // joining '_' for valid DOT format\n switch( date_tokens.length )\n {\n case 3: // day precision\n dates.add( date_tokens[0] + '_' + date_tokens[1] ); // also add month\n case 2: // month precision\n dates.add( date_tokens[0] ); // also add year\n case 1: // year precision\n // nothing else to do\n }\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1605,"value":"/*static*/ function has_date_part( event ) // datepart of event = all tokens starting at the 2nd, if any\n{\n const tokenized_event = typeof event === \"string\" ? event.split('_') : event\n return ! isNaN( Date.parse( tokenized_event.slice(1).join(\"-\") ) ) // joining \"-\" for valid date format\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3136,"value":"/*static*/ function find_entities_by_event( event, entities, except )\n{\n return Object.keys( entities ).filter\n ( key => \n {\n if( key === except ) return false;\n const valueArray = entities[key].events;\n return valueArray.some( value => value === event );\n })\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3499,"value":"#### 'member' candidates","pinned":false,"hidden":false,"mode":"md"},{"id":3530,"value":"// NOTE could not refactor this into (EntityReduced)Story because circular reference\nis_event_visible = (event, event_entity_map, diagram_toggles, ) =>\n event_entity_map.get( event )\n &&\n (event_entity_map.get( event ).size > 1 || !diagram_toggles.includes( only_shared_events ) )\n &&\n (date_range[0] == \"\" || -1 < datepart_from_event( event ).replaceAll('_','-').localeCompare( date_range[0].toISOString ? date_range[0].toISOString() : date_range[0] ) )\n &&\n (date_range[1] == \"\" || 1 > datepart_from_event( event ).replaceAll('_','-').localeCompare( date_range[1].toISOString ? date_range[1].toISOString() : date_range[1] ) )","pinned":false,"hidden":false,"mode":"ojs"},{"id":3498,"value":"is_visible = (element, story) => is_event_visible( element, story.event_entity_map, diagram_toggles )","pinned":false,"hidden":false,"mode":"ojs"},{"id":3134,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":3409,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":3591,"value":"/* translate type names into role names if that is easier for the reader to comprehend */\ntranslate_type = (typename, fallback) => roles_dict[typename] ?? fallback ?? Text.capitalizeString( typename )","pinned":false,"hidden":false,"mode":"ojs"},{"id":2634,"value":"## Exports","pinned":false,"hidden":false,"mode":"md"},{"id":3368,"value":"### with {...} (meant to be overridden in import)","pinned":false,"hidden":false,"mode":"md"},{"id":1669,"value":"diagram_options = \n{\n return {\n future_pointer_minlen: 1\n ,\n places_edge_style : \"dotted\"\n\n , entryArrowtail : \"crow\" // for a nicer distinction between the entity's name and its first event along the timeline\n \n //, entity_edge_style : \"dashed\"\n \n //, showExit : false // a river e.g. never extends beyond its estuary\n\n //, render_terminal_event_boxed : true\n }\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":3649,"value":"entity_default_properties_by_type = new Map(\n [\n [ \"replacement\", { labelPrefix : \"⚙\" ,showExit : false } ]\n ,\n [ \"dog\" , { labelPrefix : \"🐕\" } ]\n ,\n [ \"skill\" , { labelPrefix : \"🔧\" , edge : \"style=dotted\" } ]\n ,\n [ \"boat\" , { labelPrefix : \"⛵\" , edge : \"style=dashed\" } ]\n ,\n [ \"car\" , { labelPrefix : \"🚗\" , edge : \"style=dashed\" } ]\n ,\n [ \"education\" , { labelPrefix : \"🎓\" } ]\n ,\n [ \"school\" , { labelPrefix : \"🏢\" } ]\n ,\n [ \"OU\" , { labelPrefix : \"🏢\" } ]\n ]\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3367,"value":"// for a CV: the \"central entity\" will not get listed e.g. in \"related entities\" because it is implicit \ncentral_entity = \"\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":3040,"value":"title_dot = \"\" ","pinned":false,"hidden":false,"mode":"ojs"},{"id":1033,"value":"## Imports","pinned":false,"hidden":false,"mode":"md"},{"id":3314,"value":"style","pinned":false,"hidden":false,"mode":"ojs"},{"id":3313,"value":"import {style} from \"@bogo/css-for-print\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":3061,"value":"hpcc_js_wasm_version = '@2.8.0'","pinned":false,"hidden":false,"mode":"ojs"},{"id":5,"value":"import { get_initial_url_param, get_initial_details, digraph2svg, dot2svg, kts_console, visco, init, set_input_value}\nwith {selected_entities, hpcc_js_wasm_version}\nfrom \"@bogo/kxfm\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":2428,"value":"import { render_maximap_div } from \"@bogo/maximap\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":3597,"value":"import { yaml, YAML } from \"@bogo/yaml\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":5816,"value":"import {createSuite, expect} from '@tomlarkworthy/testing'","pinned":false,"hidden":false,"mode":"ojs"},{"id":1031,"value":"## Initialization","pinned":false,"hidden":false,"mode":"md"},{"id":2542,"value":"init_statement = \n{\n diagram_full_story;\n diagram_reduced_story;\n maximap; \n \n init();\n\n yield \"Timeline ready\";\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1127,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":5815,"value":"","pinned":true,"hidden":false,"mode":"html"},{"id":3300,"value":"viewof suite = createSuite()","pinned":false,"hidden":false,"mode":"ojs"},{"id":5812,"value":"suite.test( \"all_entity_types\", () => \n expect\n (\n myStory.all_entity_types\n ).toEqual\n (\n [\"UseCase\", \"Syntax_Error\", \"OU\", \"boat\", \"person\", \"dog\", \"skill\"]\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":5811,"value":"suite.test\n( \"group_entities_by_type\", ()=>\n {\n get_topic_details() // initialize access to inner function \n return expect\n (\n get_topic_details.group_entities_by_type\n (\n myStory.entity_keys\n ,\n myStory.entity_timelines \n )\n .get(\"Syntax_Error\")\n ).toEqual\n (\n [\"ErrorEntity\"]\n )\n }\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3305,"value":"suite.test( \"common_entities\", () => \n expect\n (\n Story.common_entities( myStory.event_entity_map, \"AtlanticCrossing\", \"Daysailing\" )\n ).toEqual\n (\n [\"Boat\", \"sailing\"]\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3299,"value":"suite.test( \"compare array lengths ( all == keep_types + hide_types )\", () => \n expect\n (\n myStory.entity_keys.length\n ).toBe\n (\n myStory.keep_types( \"person\" ).length\n + \n myStory.hide_types( \"person\" ).length\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3296,"value":"suite.test( \"keep_types person\", () => \n expect\n (\n myStory.keep_types( \"person\" )\n ).toEqual\n (\n [\"First_Owner\", \"Second_Owner\"] \n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3295,"value":"suite.test( \"number of all entities minus type person\", () => \n expect\n (\n myStory.hide_types( \"person\" ).length\n ).toBe\n (\n 17\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3298,"value":"suite.test( \"keep_types dog\", () => \n expect\n (\n myStory.keep_types( \"dog\" )\n ).toEqual\n (\n [\"Dog\"]\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":3424,"value":"suite.test( \"first_notice_of\", () => \n expect\n (\n myStory.first_notice_of( \"Historic_Entity\" )[0]\n ).toBe\n (\n \"1990\"\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":5798,"value":"suite.test( \"flavor 0 entries\", () => expect\n (\n new Story( `\na - skill\n\nb - skill\n\nc - person\n`\n ).get_flavour( 'notfound' )\n ).toEqual(\n \"\"\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":5797,"value":"suite.test( \"flavor 2 skills\", () => expect\n (\n new Story( `\na - skill\n\nb - skill\n\nc - person\n`\n ).get_flavour( 'skill' )\n ).toEqual(\n \", featuring a + b skills\"\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":5796,"value":"suite.test( \"flavor 1 person\", () => expect\n (\n new Story( `\na - skill\n\nb - skill\n\nc - person\n`\n ).get_flavour( 'person' )\n ).toEqual(\n \", flavour: c\"\n )\n)","pinned":false,"hidden":false,"mode":"ojs"},{"id":5795,"value":"suite.test( \"flavor 2 people\", () => expect\n (\n new Story( `\na - skill\n\nb - skill\n\nc - person\n\nd - person\n`\n ).get_flavour( 'person' )\n ).toEqual(\n \", featuring c + d\"\n )\n)","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W37","stdlib":"1","titling":"auto"}