# Bone Flow #054 Display Timeline Guide ## What Display Timeline is #054 Display Timeline renders schedules, work hours, breaks and comments on a time axis. It owns the display timeline, bars, Shape Comments, colors, parent fitting, and weekly/monthly display behavior. It does not own #121 Timeline responsibilities such as Delay, Duration, Loop, Repeat, Sequence or Parallel. ## When to use it Use #054 when a UI needs a visible time bar, overlapping schedule bars, Shape Comments, or repeated rows for weekly/monthly reports. ## Test-page workflow 1. Configure properties. 2. Configure each data item. 3. Apply and inspect the Preview. 4. Inspect the #002 Bone Joint connection image. 5. Run Smoke Test and Validation. 6. Open the HTML Functional Class guide at the bottom for implementation examples. ## Theme Formal themes are `light / dark / neon`. The default is `light`. ## Shape Comment Shape Comment keeps both `start` and `end`. The anchor uses the start time and the box displays the full range. ## #040 ColorPicker Background, text and day-frame colors use the formal `BoneColorPicker.attachCaller(...)` pattern. ## #125 Blend Bar items support `normal / multiply / screen / overlay / darken / lighten / difference / add`. ## Weekly / monthly consumer Use `timeAxisMode=group-first` and `groupIndex=0` on the first row to show the axis only once. ## Parent fit With `snapToParent=true`, #054 removes its own frame/padding/background and fits the parent. `parentHeight=0` means content-driven height. ## Connection Image The test page uses formal #002 Bone Joint runtime drawing. ## Smoke / Validation The page does not predeclare ALL PASS. Results are produced only after tests run. ## Completion Completion is enabled only after Smoke and Validation both pass. User localhost confirmation is still required before formal completion. ## HTML Functional Class The normal-use class is `bf-display-timeline`. Bars and Shape Comments are not separate classes. Put a JSON array in `data-timeline-items` and set each item's `displayType`. ### Timeline properties | HTML attribute | JS property | Type / allowed values | Default | Meaning | |---|---|---|---|---| | `data-timeline-orientation` | `orientation` | `horizontal / vertical` | `horizontal` | Timeline orientation. Formal samples use horizontal. | | `data-timeline-start` | `start` | `HH:mm` | `09:00` | Timeline start. | | `data-timeline-end` | `end` | `HH:mm` | `18:00` | Timeline end; must be later than start. | | `data-timeline-step` | `step` | 5–240 | `60` | Tick/grid interval in minutes. | | `data-timeline-snap` | `snap` | 1–240 | `15` | Drag/resize snapping in minutes. | | `data-timeline-bar-height` | `barHeight` | 24–160 | `64` | Bar-row height in px. | | — | `rowGap` | 0–48 | `8` | Row gap for stack layout; JavaScript-only in the current HTML Functional Class. | | `data-timeline-bar-layout` | `barLayout` | `overlap / stack` | `overlap` | overlap keeps bars in one row; stack separates colliding bars. | | `data-timeline-axis-mode` | `timeAxisMode` | `all / group-first / none` | `all` | Axis-label policy. | | `data-timeline-group-index` | `groupIndex` | 0–9999 | `0` | `group-first` shows axis only when this is 0. | | `data-timeline-snap-parent` | `snapToParent` | Boolean | `false` | true fits directly to parent and removes #054 outer frame. | | `data-timeline-parent-height` | `parentHeight` | 0–2000 | `0` | 0 = content height; positive value fixes parent height in px. | | `data-timeline-grid` | `showGrid` | Boolean | `true` | Show/hide grid lines. | | `data-timeline-labels` | `showLabels` | Boolean | `true` | In the current runtime this gates **time-axis labels**; it does not hide bar item text. | | `data-timeline-editable` | `editable` | Boolean | `true` | Enables/disables bar drag/resize and Shape Comment drag. | | `data-timeline-theme` | `theme` | `light / dark / neon` | `light` | Theme. | | `aria-label` | `ariaLabel` | string | `Display Timeline` | Accessible name. | | `data-timeline-items` | `items` | JSON array | `[]` | Bar / Shape Comment items. | ### `kind` values `kind` defaults to `neutral`. Bar kinds are `work`, `break`, `meeting`, `info`, `warning`, and `neutral`. They provide semantic classification and a fallback Bar accent when `backgroundColor` is omitted. Shape Comment stores `kind`, but current comment visuals are controlled by comment colors rather than kind-specific styling. ### Bar item properties - `id`: optional stable ID, auto-generated as `item-N` if omitted; explicit IDs are recommended. - `label`: required, 1–120 chars. - `kind`: optional, one of the six values above; default `neutral`. - `displayType`: `bar` (default). - `start` / `end`: required `HH:mm` inside timeline range. - `backgroundColor` / `textColor`: optional `#RGB` or `#RRGGBB`. - `blendMode`: one of the eight modes above; default `normal`. - `fullHeight`: Boolean, default false. true marks the Bar full-height/foreground (z-index 4); both true and false still use `barHeight` in the current runtime. - `disabled`: Boolean, default false. true disables Bar drag/resize and dims the Bar; selection remains available. ### Shape Comment item properties - `id`, `label`, `kind`: same base contract as Bar. - `displayType`: must be `shapeComment`; omitting it defaults to Bar. - `start`: required and used as the leader-line anchor. - `end`: required and displayed as the range end. - `commentText`: defaults to `label`, max 240 chars. - `commentPosition`: `top / bottom / left / right`, default `bottom`. - `commentOffsetX` / `commentOffsetY`: -1000 to 1000 px, default 0; final position is clamped inside the track. - `commentWidth`: 72–240 px, default 96. - `backgroundColor` / `textColor`: optional hex colors. - `blendMode`: accepted/stored, but current #125 visual blending is applied to Bars, not Shape Comments. - `disabled`: accepted/stored; current Shape Comment drag is disabled with timeline-level `editable:false`. ### Boolean values For HTML attributes, explicitly use `true` or `false`. The Functional Class treats `false`, `0`, `off`, and `no` as false; other present values are true. ### Required runtime files ```html ``` ### Bar example ```html
``` ### Shape Comment example ```html
``` ### Live sample After installation, open `http://localhost/boneflow/sample/054/`. ## Public API - `create(root, options, items)` - `setItems(root, items)` - `setOptions(root, options)` - `getItems(root)` - `getOptions(root)` - `moveItem(root, id, start)` - `resizeItem(root, id, start, end)` - `moveComment(root, id, offsetX, offsetY)` - `getAnchorPoint(root, time)` ## Error / Troubleshooting Check #040 dependency/load order, #125 BoneBlend 1.0.0, valid JSON in `data-timeline-items`, and #002 Bone Joint 1.1.36 when related UI is unavailable. ## Runtime Property Schema API #054 publishes its formal Property Schema so consumers do not need to redefine #054 property names. ```js const schema = BoneDisplayTimeline.getPropertySchema(); const defaults = BoneDisplayTimeline.getPropertyDefaults(); const timeAxis = BoneDisplayTimeline.getPropertyDefinition("timeAxisMode"); ``` `timeAxisMode` is the formal time-axis-label property with `all / group-first / none`. `showLabels` remains a compatibility gate; normal label policy should use `timeAxisMode`. This is separate from each item's `label` text. Consumers such as #048 Table should read this schema instead of hard-coding #054 properties. ### Vertical orientation / v1.0.27 Time increases from top to bottom; ticks are on the left, grids are horizontal, and bar lengths follow the Y-axis. Drag/resize uses Y-axis; horizontal orientation remains available. ### Vertical width and #048 Table columns (v1.0.34) Choose Vertical to enable Column Width (default 140px, 100–480) and Column Count (default 7, 1–31). The vertical preview uses installed #048 Table v1.0.16, its HTML Functional Class bridge and built-in #054 cell renderer. Time flows from top to bottom; columns scroll horizontally. #048 Frozen files are not modified or included. ### v1.0.34 vertical widths and #048 Table The configured vertical column width is the usable track width (default 140px, seven columns). For `group-first`, only the leftmost column gets the additional 62px time-axis label width. Thus seven columns of 140px tracks total 202 + 6 × 140 = 1042px. With `none`, all are 140px (980px total); with `all`, all are 202px (1414px total). The frozen #048 runtime is not modified. ## #054 Overlapping bars (v1.0.34) Default = overlap (full track), vertical options = left / right, horizontal options = top / bottom. Overlapping bars share the same existing track and are split along its cross-axis; no extra rows. Legacy stack values are interpreted as left/top but not offered as a new choice. Vertical shapeComment is displayed in a bar with top-left, center or bottom comment placement. ## v1.0.34: Per-item overlap and first-column time labels Default `timeAxisMode` is `group-first` in both orientations. Only the first vertical column displays the 62px time-label axis. Every vertical time bar fills its configured Table column (140px by default); it never splits to half width. Each Item has `verticalOverlap` (`overlap`, `left`, `right`) and `horizontalOverlap` (`overlap`, `top`, `bottom`); selections bring that Item in front. Global `barLayout` remains only for older data compatibility. ### v1.0.36 — Vertical text fitting and separate preview `verticalTextFitMode`: `shrink` (default) measures actual bar box and glyph widths, automatically scaling from 12px to a 7px floor, or `expand-column` widens the populated #048 Table column while preserving other column widths. The formal preview parent has a bottom-right resize grip, reports its dimensions and snap state, and preserves time-bar geometry with scrolling for constrained sizes. `Separate Preview` opens the preview-only page `bone-display-timeline-preview.html` and receives same-origin live Property updates. The #048 Frozen Runtime is not changed. ### v1.0.38 preview and ColorPicker integration - Restores the missing `gridTicks()` function that caused blank horizontal/vertical previews. - One-hour major grid lines are distinct from editing-snap minor grid lines. - Detects compatible #040 Caller API and prerequisites; reports attachment failures rather than hiding them. ## v1.0.39 #026 TimePicker consumer integration The #054 test UI uses the independently installed #026 `bf-timepicker` HTML Functional Class for Timeline and Item start/end inputs. It listens for `bone-timepicker:select`, commits the value in the #054 consumer, and redraws. #026 Runtime and Functional Class are not distributed or edited by this package.