<sl-split-panel> improvements

[SabineWren]

I replaced an in-house split-panel with the Shoelace one. It works well, but could use some minor ergonomic improvements.

Discrete snapping requires specifying every snap point. When points are close together, the panel snaps to position=100 unless lowering the snap threshhold to match. The threshold only accepts pixels, not percents, which may lead to edge cases with nested split-panels.

<sl-split-panel
	.snap=${Iota(99, 1).map(p => p + "%").join(" ")}
	.snapThreshold=${2}
	>
</sl-split-panel>

A small enough threshold breaks snapping when restricting to a windowed range of snap points. For example, 5%-95% doesn't snap from outside the range due to the low snap threshold.

It also warns about its touch listener.

Maybe the API should have a 'discrete' mode with a step size?

[claviska]

Snapping was designed to let the split panel snap at a handful of important points. What's the use case for having it snap at every 5%? That seems excessive and would likely be annoying for users.

Can you show me an example of the API you'd like to see?

[SabineWren]

I'm using split panels for the binary tree mode of a tiling window manager. A 1% step size makes it easy to size adjacent windows exactly the same, instead of having them differ in size by a pixel or so. All window managers I've ever used enforce a minimum window size, but a px measurement makes more sense for min size than the 5% I gave above.

Just spitballing... two new attributes would work. Could also split the padding into pad-start and pad-end.

<sl-split-panel
	step-size="1%"
	padding="40px"
	>
</sl-split-panel>

This would yield a stepped window of [40px, 100% - 40px]. There's the edge case of total padding > space available, but could force position="50%".

[SabineWren]

I just noticed tmux enforces a vertical step size of 1 line height, and a horizontal step size of 1 character. Its min sizes are the same, so there's another use case for discrete sizing if putting text in a split-panel.

[claviska]

Just spitballing... two new attributes would work. Could also split the padding into pad-start and pad-end.

This makes the API confusing, as users now have to wrestle with not one, but three attributes that all affect snapping.

Since snap positions can be specified in pixels and/or percentages, it would probably be better to let users determine which points to snap to based on size, tolerance, and any other variables that are important to them.

The threshold only accepts pixels, not percents, which may lead to edge cases with nested split-panels.

Remember that split panels aren't designed to be a grid where only certain values are allowed. Users should be able to resize a split panel freely — snapping is just used to easily restore a convenient panel position (e.g. snapping to the center).

If you really want to do this, maybe you can grab the size of the container and convert the desired percentages to pixels, then you'll be working completely in pixels for the snap points and the snap threshold. Of course, you'd have to recalculate those values if the component gets resized, but there's a component that can help with that.

[SabineWren]

This makes the API confusing, as users now have to wrestle with not one, but three attributes that all affect snapping.

Just 2, and they'd be mutually exclusive.

type Snapping =
   | ImportantPoints of (percent | px)[]
   | StepSize of (percent | px)

A third padding attribute would affect the range of valid points, rather than snapping behavior of those points. It would default to [0%, 100%].

There might be another solution. Instead of adding properties to handle every split-panel use case, why not expose a validation callback? That would give the developer full control of snapping behaviour:

<sl-split-panel
   .validate=${(percent: number, _px: number, _vertical: boolean) =>
      percent < 5.0 ? 5.0
      : percent > 95.0 ? 95.0
      : Math.round(percent)
   }>
</sl-split-panel>

Giving a user the power to freely resize a panel doesn't always lead to a better UX. For example, Konsole allows arbitrary resizing, but doesn't display partially hidden lines. That means content pops in/out of view when resizing the window. I prefer tmux's stepped resizing.

[claviska]

I'm interested in the idea of a callback. What if snap accepted either a string containing snap points (like it does right now) OR a function that lets the callback determine whether to snap. It could potentially offer some helpful arguments, maybe width/position or something.

splitPanel.snap = (details) => {
  const { positionInPixels, positionInPercentage } = details;
  
  // custom logic here

  return positionToSnapTo;
};

Not sure if this would work without diving back into the source, but it feels like this might be a way to keep the API simple while accommodating more advanced use cases.

[SabineWren]

That would solve my use case. If the details includes width and percentage, I can calculate new position in px from a percentage and snap to it.

[SabineWren]

Is this something I should write and make a pull request for?

[claviska]

You can if you want. I probably won't get to it anytime soon. I'd love to keep the logic as simple as possible, though.

[Aurailus]

Hey @claviska, I'd like to contribute an implementation for this. I've implemented the behaviour where you can specify a string or a function for snap, but it occurs to me that that the function overload wouldn't be accessible when setting the HTML attribute. You can still specify a string of snap points as before, but if you want to specify a function snap point, you'd need to get the custom element and access it's .snap member. I personally don't think this is a problem, but I wanted to check and see what you thought. I that's all good, then I'll clean my side up and create a PR. Thanks!

[Aurailus]

Following up on my post earlier this year, I've created a PR (#2340) for these features. It extends sl-split-panel's snap property to accept a string in the form of repeat(50px) or repeat(10%), which creates uniformly distributed snap points. It also allows SlSplitPanel.snap to be set to a function to fully customize snap behaviour. It also slightly tweaks the existing snapping algorithm to prioritize the closest snap point instead of the first one when there are multiple valid points within the snap threshold, allowing snapThreshold = Infinity to behave as you would intuitively expect it to.