Markwhen View Container

This repository contains the Markwhen view container, which is responsible for rendering different views such as the timeline and the calendar. It is not the web editor itself. The Markwhen editor (markwhen.com) and the VSCode extension are built on top of this view container.

To create custom views, use the view client library.

To set up the view container locally, clone the repository, install dependencies, and run the development server.

> git clone git@github.com:mark-when/markwhen.git
> cd markwhen
> npm i
> npm run dev

You can build and run a development image of the Markwhen view container using Docker. The container runs on port 8080 and will be available at http://localhost:8080.

> git clone git@github.com:mark-when/markwhen.git
> cd markwhen
> docker build -t markwhen .
> docker run -p8080:8080 markwhen

If you are running Markwhen locally, you may want to host the views (like the timeline) locally as well. To do this, update the url in src/Views/useViewProviders.ts to point to your local instance instead of the default production URL.

/* src/Views/useViewProviders.ts */
...

export const useTimelineExternalProvider = () => ({
  id: "markwhen.timeline",
  name: "Timeline",
- url: "https://timeline.markwhen.com",
+ url: "http://localhost:5173"
...
})

The renderer displays content provided to markwhenStore (src/Markwhen/markwhenStore.ts). To allow editing directly from the timeline view, set editorOrchestrator.editable (src/EditorOrchestrator/editorOrchestratorStore.ts) to true.

const editable = ref(true);

The module provides utilities to convert date ranges into human-friendly strings (e.g., "2 years, 3 months").

• humanDuration(range: DateRange): Returns a human-readable string for a given range. If the range is a single point in time, it returns "instant".
• eventHumanDuration(e: Event): A convenience wrapper that calculates the duration of a Markwhen Event.

The useLpc hook provides a mechanism for cross-frame communication (e.g., between a parent window and an <iframe>) using a request/response pattern. It allows you to send messages and listen for specific event types via a listeners object.

Core Concepts

• post: Sends a fire-and-forget message.
• postRequest: Sends a message and returns a Promise that resolves when the recipient sends a response.
• MessageTypes: A set of built-in message types including state, setHoveringPath, setDetailPath, key, showInEditor, newEvent, editEventDateRange, jumpToPath, and jumpToRange.

To use it, pass a Ref to an HTMLIFrameElement and an object containing listener functions for the message types you wish to handle.

Use dateMidpoint or eventMidpoint to find the center point of a time range. This is typically used for positioning labels or markers in the middle of an event on a timeline.

• dateMidpoint(range: DateRange): Returns the DateTime exactly halfway between fromDateTime and toDateTime.
• eventMidpoint(node: SomeNode): Returns the midpoint of a Markwhen node (Event or other range-based nodes).

To create a custom view for Markwhen, implement the ViewProvider interface. This interface defines the identity, metadata, and capabilities of the view.

Key properties include:

• id: A unique identifier for the provider.
• url: The location of the view (string or any).
• name: The display name.
• description: A description of the view.
• capabilities: An optional ViewCapabilities object defining interaction features.
• uses: An optional ViewUses object defining data usage patterns.
• settings: An optional array of functions returning ViewSetting objects.

export interface ViewProvider {
  id: string,
  url: string | any,
  name: string,
  iconSvg?: string,
  settings?: (() => ViewSetting | any)[]
  capabilities?: ViewCapabilities
  uses?: ViewUses
  active?: boolean
  description: string
  screenshots: string[]
}

Use scaleForDuration to automatically determine the appropriate DisplayScale based on the length of a DateRangePart. This helps in deciding whether to show seconds, minutes, hours, days, months, or years on a timeline.

Scale thresholds:

• < 60s: second
• < 1h: minute
• < 24h: hour
• < 30 days: day
• < 12 months: month
• Otherwise: year

The dateTimeUtilities module provides functions to floor, ceil, and round luxon.DateTime objects to specific DisplayScale increments. This is useful for aligning timeline events to a grid.

Supported DisplayScale values include:

• second
• quarterminute (15s)
• minute
• quarterhour (15m)
• hour
• day
• month
• year
• decade
• cent (100 years)