Flexbox story sidebar #9532

BurningTreeC · 2025-12-28T23:09:21Z

This PR makes the sidebar move out of the viewport with css transitions
It works in fluid-fixed and fixed-fluid mode

Bildschirmaufzeichnung.vom.2025-12-28.23-54-50.mp4

It uses flexbox on the.tc-page-container and the .tc-page-container > dropzone
Above the dropzone the menubar gets transcluded so that the scrollbar of the story-river and sidebar don't get hidden below it
The pageScroller gets some adjustments so that it can scroll a scrollContainer and so that it accomodates for possible scroll-margins
There are also some adjustments for spacebar-scroll-trapping, too

Just to discuss it, maybe something finds its way into the core

netlify · 2025-12-28T23:09:26Z

✅ Deploy Preview for tiddlywiki-previews ready!

Name	Link
🔨 Latest commit	`0ecddfc`
🔍 Latest deploy log	https://app.netlify.com/projects/tiddlywiki-previews/deploys/6953ddc6c23e000008ac4566
😎 Deploy Preview	https://deploy-preview-9532--tiddlywiki-previews.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2025-12-28T23:09:30Z

Confirmed: BurningTreeC has already signed the Contributor License Agreement (see contributing.md)

github-actions · 2025-12-28T23:09:33Z

📊 Build Size Comparison: `empty.html`

Branch	Size
Base (master)	2451.4 KB
PR	2506.6 KB

Diff: ⬆️ Increase: +55.2 KB

⚠️ Warning: Size increased significantly.

✅ Change Note Status

All change notes are properly formatted and validated!

📝 $:/changenotes/5.4.0/#9532

Type: enhancement | Category: usability
Release: 5.4.0

The sidebar moves out of view and into view

🔗 #9532

👥 Contributors: BurningTreeC

📖 Change Note Guidelines

Change notes help track and communicate changes effectively. See the full documentation for details.

pmario · 2025-12-29T04:14:51Z

I like it

This change note details an enhancement to the sidebar behavior in version 5.4.0, allowing it to move smoothly when hiding and showing.

Refactor focus management for sidebar layout, ensuring focusable elements are correctly set and tab navigation is trapped within main content. Improved spacebar scrolling prevention and click refocusing behavior.

Refactor focus handler to manage secondary containers and update sidebar focus behavior.

Remove outline from secondary container on focus.

Removed unnecessary div wrapper from the story template.

Added a helper function to check for active text selection and updated focus handling logic to prevent refocusing when text is selected.

core/modules/startup/focus-handler.js

Add order styles for secondary container elements.

Updated focus handler module to improve focus management and scrolling functionality.

…erytracker.js

BurningTreeC · 2025-12-30T09:46:54Z

Overview

This pull request introduces a modern flexbox-based layout system for TiddlyWiki5's story river and sidebar, replacing the traditional CSS positioning approach. The most visible change is that the sidebar now smoothly slides in and out of view using CSS transitions, providing a more polished and responsive user experience.

Key Features

1. Flexbox Layout Architecture

The PR restructures the .tc-page-container and its child dropzone to use CSS flexbox, enabling:

More predictable and maintainable layout behavior
Better support for dynamic content sizing
Cleaner separation between the menubar, story river, and sidebar
The menubar is now transcluded above the main dropzone, preventing scrollbars from being hidden beneath it

2. Animated Sidebar Transitions

The sidebar now slides out of and into the viewport using CSS transitions rather than simply appearing/disappearing. This works in both layout modes:

Fluid-fixed mode: Story river fills available space, sidebar has fixed width
Fixed-fluid mode: Story river has fixed width, sidebar fills remaining space

3. New Infrastructure Components

Filter Tracker (`filter-tracker.js`)

A new utility module that monitors tiddlers matching a filter expression and triggers callbacks when tiddlers enter, leave, or change. This provides a reactive foundation for tracking dynamic sets of tiddlers.

Media Query Tracker (`mediaquerytracker.js`)

A new info module that bridges CSS media queries with TiddlyWiki's tiddler system. It:

Monitors tiddlers tagged with $:/tags/MediaQueryTracker
Reads the media-query field and evaluates it against window.matchMedia()
Updates info tiddlers (specified via info-tiddler field) with "yes" or "no" based on whether the media query matches
Supports wikitext transclusions in the media-query field (e.g., (min-width: {{$:/themes/tiddlywiki/vanilla/metrics/sidebarbreakpoint}}))
Reactively updates when the viewport changes

Background Actions (`background-actions.js`)

Infrastructure for executing actions in response to system events.

4. Enhanced Focus Management (`focus-handler.js`)

A new startup module that improves keyboard navigation and accessibility:

Manages focus between main content and secondary containers (sidebar, menubar)
Implements tab-trapping within logical content regions
Prevents spacebar from scrolling the page when focus is on non-interactive elements
Handles click-to-refocus behavior
Respects text selection (doesn't refocus when user is selecting text)
Properly handles focus within iframes

5. PageScroller Improvements

The PageScroller has been updated to:

Support scrolling within specific scroll containers (not just the window)
Account for scroll-margin CSS properties on tiddler frames
Work correctly with the new flexbox layout where the story river itself may be the scroll container

6. CSS Modernization

Uses logical CSS properties (padding-block-start, margin-inline-end, etc.) for better RTL language support
Adds scroll-margin to tiddler frames for better scroll-into-view behavior
Implements popup clamping to keep popups within the viewport
Fixes for SVG color transitions in the Snow White theme

7. Dropzone Widget Updates

The dropzone widget has been updated to work correctly with the new layout structure, ensuring drag-and-drop imports still function properly.

Technical Details

Metric	Value
Files Changed	25
Lines Added	+1,607
Lines Removed	−577
Build Size Impact	+38.0 KB to empty.html

New Tiddler Tags

Tag	Description
`$:/tags/MediaQueryTracker`	Tag tiddlers with this to register them as media query trackers

New Tiddler Fields

For media query tracker tiddlers:

Field	Description
`media-query`	The CSS media query to evaluate (supports wikitext transclusions)
`info-tiddler`	The info tiddler to update with the result
`info-tiddler-alt`	Optional secondary info tiddler to update

Compatibility

This is a significant change to TiddlyWiki's core layout system. While designed to be backward compatible with existing content, themes and plugins that heavily customize the page layout may require updates.

Status

This PR is currently in Draft status, submitted for discussion and feedback from the TiddlyWiki community.

BurningTreeC · 2025-12-30T09:48:32Z

To fix: indentation and unused variables

core/modules/info/mediaquerytracker.js

pmario · 2025-12-30T11:02:45Z

core/modules/startup/load-modules.js

+	// The rest of the startup process here is not strictly to do with loading modules, but are needed before other startup
+	// modules are executed. It is easier to put them here than to introduce a new startup module
+	// --------------------------
+	// Create a root widget for attaching event handlers. By using it as the parentWidget for another widget tree, one can reuse the event handlers


Since TW ships JS comments with the source code. If we have multiline comments it usually looks like this. The dashes --- increase code size for no real win

/* Multiline comments */

pmario · 2025-12-30T11:05:50Z

core/modules/startup/load-modules.js

+		wiki: $tw.wiki,
+		document: $tw.browser ? document : $tw.fakeDocument
+	});
+	// Set up the performance framework


IMO the next 3 comments are redundant, since the function names eg: $tw.Performance() should speak for itself.

pmario · 2025-12-30T11:11:30Z

core/modules/widgets/dropzone.js

-var DropZoneWidget = function(parseTreeNode,options) {
-	this.initialise(parseTreeNode,options);
+var DropZoneWidget = function(parseTreeNode, options) {
+	this.initialise(parseTreeNode, options);


I think those extra spaces should not be there. If ESLint styling did this, we probably need to adjust the settings there

pmario · 2025-12-30T11:17:56Z

core/ui/PageTemplate/bottom-toolbar.tid

+\whitespace trim
+\define lingo-base() $:/language/BottomToolbar/
+\procedure tooltip-lingo(suffix) {{{ [<lingo-base>addsuffix<suffix>get[text]] }}}
+<nav class="tc-bottom-toolbar tc-secondary-container tc-secondary-container-bottom" role="navigation" aria-label=<<lingo Hint>>>


IMO the file should have proper indentation to make it human readable

pmario · 2025-12-30T11:19:07Z

core/ui/PageTemplate/story.tid

+\function tf.story-river.tabindex() [{$:/info/mediaquery/min-width}match[no]then[]] :else[[-1]]
 \whitespace trim
-<section class="tc-story-river" role="main">
+<section class=<<tf.story-river.classes>> role="main" tabindex=<<tf.story-river.tabindex>>>


tf. function name should only have 1 dot. imo for consistency reasons it should be tf.story-river-classes

pmario · 2025-12-30T11:20:03Z

core/ui/PageTemplate.tid

 icon: $:/core/images/standard-layout
 code-body: yes

+\function tf.primary-container.classes() [{$:/info/mediaquery/min-width}match[no]then[tc-primary-container tc-inner-container-wrapper]] :else[[tc-inner-container-wrapper]]


Is it plural or singular?

pmario · 2025-12-30T11:29:47Z

core/modules/info/platform.js

- 		infoTiddlerFields.push(getDarkModeTiddler());
- 		mqList.addListener(function(event) {
- 			updateInfoTiddlersCallback([getDarkModeTiddler()]);
- 		});


Why was this removed without a replacement?

pmario · 2025-12-31T06:22:28Z

I know that's not exactly part of this PR, but there are some unwanted side effects.

There is a baseline problem. HelloThere and TiddlyWiki v... Should have the same baseline.

Similar to the other PR. If we fix the underling vertical alignment problem, we should not get a baseline problem here too.

Jermolene

Thanks @BurningTreeC the animation is helpful. It's a lot of code, much of which looks like it might be of wider utility. Are there other fixes or enhancements that could be built on top of the new design?

core/ui/PageTemplate/bottom-toolbar.tid

Leilei332 · 2026-01-07T11:15:03Z

themes/tiddlywiki/snowwhite/base.tid


 .tc-page-controls button svg, .tc-tiddler-controls button svg, .tc-topbar button svg {
-	transition: fill 150ms ease-in-out;
+	transition: color 150ms ease-in-out;


IMO this change is redundant for this PR. It should be in the PR that fixes #9521

Leilei332 · 2026-01-07T11:17:15Z

themes/tiddlywiki/vanilla/base.tid

 	display: block;
-	margin-top: 1em;
-	margin-bottom: 1em;
+	margin-block-start: 1em;


margin-block-* are 2020 baseline. IMO we don't need block properties ATM, since there isn't urgent need to support vertical writing mode in the core.

Leilei332 · 2026-01-07T11:25:11Z

themes/tiddlywiki/vanilla/base.tid

 	white-space: pre-wrap;
-	padding: 0 3px 2px;
+	padding-block-start: 0;
+	padding-inline: 3px;


padding-inline is 2021 baseline. To support 2017 baseline, it's suggested to use the macros introduced in 9148

Leilei332 · 2026-01-07T11:25:57Z

themes/tiddlywiki/vanilla/base.tid

-	border-left: 5px solid <<colour blockquote-bar>>;
-	margin-left: 25px;
-	padding-left: 10px;
+	border-inline-start: 5px solid <<colour blockquote-bar>>;


border-inline-* properties are 2020 baseline. Fallbacks are required. And IMO bidirectional support for blockquotes are also redundant for this PR.

Leilei332 · 2026-01-07T11:27:28Z

themes/tiddlywiki/vanilla/base.tid

-	top: -1000px;
-	left: -1000px;
+	inset-block-start: -1000px;
+	inset-inline-start: -1000px;


inset-inline-* are 2021 baseline.

Leilei332 · 2026-01-07T11:28:12Z

themes/tiddlywiki/vanilla/bottom-toolbar.tid

+/* Bottom Toolbar Base */
+.tc-bottom-toolbar {
+    position: fixed;
+    inset-inline: 0;


inset-inline is 2021 baseline.

Leilei332 · 2026-01-07T11:30:36Z

plugins/tiddlywiki/menubar/items/topleftbar.tid

 description: Items from $:/tags/TopLeftBar
 caption: Legacy Top Left Bar
 custom-menu-content: <$transclude tiddler="$:/plugins/tiddlywiki/menubar/items/topleftbar" mode="inline"/>
+custom-menu-styles-wide: float: inline-start;


float: inline-start is 2023 baseline. We may need to intergrate CSS feature query mechanism to filters.

Leilei332 · 2026-01-07T11:39:42Z

I think it's better to split changes that enhance bidirectional support to another PR. Including too many changes for many aspects in one PR may make it troublesome for maintaining and testing.

BurningTreeC added 8 commits December 28, 2025 09:13

Create focus-handler.js

788003f

add functionality

0655630

remove flex.tid

ad97de8

make sidebar slide out

7cedc8c

make it work for fixed-fluid

04f6a32

no changed order in rtl

f4c3496

reduce padding-top of story-river

0449b7d

also scroll-margin-left

f052b2d

BurningTreeC added 14 commits December 29, 2025 09:13

Refactor focus-handler.js for consistency

9c32080

Refactor focus-handler.js for consistent spacing

bc2106e

Fix string quotes in getBounds function

fb00b69

Add change note for sidebar movement enhancement

d5513ba

This change note details an enhancement to the sidebar behavior in version 5.4.0, allowing it to move smoothly when hiding and showing.

Update flexbox-story-sidebar.tid in release notes

b43d26c

Refactor focus handling and prevent spacebar scrolling

ec14a79

Refactor focus management for sidebar layout, ensuring focusable elements are correctly set and tab navigation is trapped within main content. Improved spacebar scrolling prevention and click refocusing behavior.

Update focus handler for sidebar and secondary containers

ddf6062

Refactor focus handler to manage secondary containers and update sidebar focus behavior.

Update sidebar class for secondary container

0852590

Change menubar class to secondary container

9c188d8

Remove outline from secondary container

d39a142

Remove outline from secondary container on focus.

Refactor focus-handler for iframe and selector updates

f558c5f

Refactor PageTemplate by removing div wrapper

75427e6

Removed unnecessary div wrapper from the story template.

Enhance focus handling with text selection check

62c2b3e

Added a helper function to check for active text selection and updated focus handling logic to prevent refocusing when text is selected.

Update menubar class for improved styling

ce7df68

pmario reviewed Dec 29, 2025

View reviewed changes

core/modules/startup/focus-handler.js Show resolved Hide resolved

core/modules/startup/focus-handler.js Outdated Show resolved Hide resolved

core/modules/startup/focus-handler.js Outdated Show resolved Hide resolved

BurningTreeC added 3 commits December 29, 2025 10:38

Define order for secondary container positions

7ee54ae

Add order styles for secondary container elements.

Refactor focus-handler module for sidebar layout

32b06fd

Updated focus handler module to improve focus management and scrolling functionality.

Fix sidebar HTML structure

a6a527a

BurningTreeC added 8 commits December 30, 2025 10:11

Create filter-tracker.js

ae2fb0b

Create background-actions.js

bc0966a

Rename core/modules/mediaquerytracker.js to core/modules/info/mediaqu…

dec2a90

…erytracker.js

Create MinWidth.tid

5f5b9aa

Update PageTemplate.tid

a3ba6e6

Update story.tid

72d7960

Update mediaquerytracker.js

fb56dc2

Update filter-tracker.js

7a16901

BurningTreeC added 3 commits December 30, 2025 11:00

Merge branch 'TiddlyWiki:master' into flexbox-story-sidebar

7bf6d54

Create BottomToolbar.multids

cd20b61

Create bottom-toolbar.tid

8e527e5

pmario reviewed Dec 30, 2025

View reviewed changes

core/modules/info/mediaquerytracker.js Show resolved Hide resolved

BurningTreeC added 4 commits December 30, 2025 11:12

Create bottom-toolbar.tid

873cb2c

Update bottom-toolbar.tid

11e65fb

Update bottom-toolbar.tid

bf6331e

Update bottom-toolbar.tid

ec0ea1a

pmario reviewed Dec 30, 2025

View reviewed changes

BurningTreeC added 6 commits December 30, 2025 13:26

Update bottom-toolbar.tid

493dfe1

Update focus-handler.js

a517c9a

Update base.tid

816fd5b

Update dropzone.js

98d100d

Update PageTemplate.tid

c1b706d

Update bottom-toolbar.tid

0ecddfc

Jermolene reviewed Jan 4, 2026

View reviewed changes

core/ui/PageTemplate/bottom-toolbar.tid Show resolved Hide resolved

BurningTreeC mentioned this pull request Jan 7, 2026

[BUG] Sidebar position issue when using bidrectional language with fluid-fixed sidebar layout #9544

Open

Leilei332 reviewed Jan 7, 2026

View reviewed changes

Flexbox story sidebar #9532

Are you sure you want to change the base?

Flexbox story sidebar #9532

Uh oh!

Conversation

BurningTreeC commented Dec 28, 2025

Uh oh!

netlify bot commented Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for tiddlywiki-previews ready!

Uh oh!

github-actions bot commented Dec 28, 2025

Uh oh!

github-actions bot commented Dec 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Build Size Comparison: empty.html

✅ Change Note Status

📝 $:/changenotes/5.4.0/#9532

Uh oh!

pmario commented Dec 29, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BurningTreeC commented Dec 30, 2025

Overview

Key Features

1. Flexbox Layout Architecture

2. Animated Sidebar Transitions

3. New Infrastructure Components

Filter Tracker (filter-tracker.js)

Media Query Tracker (mediaquerytracker.js)

Background Actions (background-actions.js)

4. Enhanced Focus Management (focus-handler.js)

5. PageScroller Improvements

6. CSS Modernization

7. Dropzone Widget Updates

Technical Details

New Tiddler Tags

New Tiddler Fields

Compatibility

Status

Uh oh!

BurningTreeC commented Dec 30, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pmario commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Jermolene left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Leilei332 Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

netlify bot commented Dec 28, 2025 •

edited

Loading

github-actions bot commented Dec 28, 2025 •

edited

Loading

📊 Build Size Comparison: `empty.html`

Filter Tracker (`filter-tracker.js`)

Media Query Tracker (`mediaquerytracker.js`)

Background Actions (`background-actions.js`)

4. Enhanced Focus Management (`focus-handler.js`)

pmario commented Dec 31, 2025 •

edited

Loading

Leilei332 Jan 7, 2026 •

edited

Loading