UI: Add an experimental API for adding sidebar filter functions at runtime

[ndelangen]

Telescoped off: #23802

What I did

I introduced a new manager API!
It's marked as experimental for now.

The purpose is to allow users and addon-creators to inject (dynamically at runtime) filter functions that filter the list of stories in the sidebar. I know this has been a feature that has been requested many times for a varied use-cases.

I've implemented the actual filtering in the sidebar, but this code will likely need optimization.
And with this optimization there will be assumptions in when the filters are re-evaluated.

A FilterFunction receives an (with status extended) IndexHash_Item and returns a boolean.
Storybook will only ask to filter leaf-items (story and docs).
Storybook will filter out empty components/groups/roots for you.

How to test

This API can be used via from manager.ts:

import { addons } from '@storybook/manager-api';
import startCase from 'lodash/startCase.js';

addons.setConfig({
  sidebar: {
    filters: {
      a: (item) => item.depth === 2,
    },
  },
});

The expected result is that the sidebar stories are filtered.

Checklist

• Make sure your changes are tested (stories and/or unit, integration, or end-to-end tests)
• Make sure to add/update documentation regarding your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts
• Make sure this PR contains one of the labels below.

["cleanup", "BREAKING CHANGE", "feature request", "bug", "build", "documentation", "maintenance", "dependencies", "other"]

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

[tmeasday]

Can we have some tests please!

Some questions:

1. How do you remove a filter?
2. What do you do when some external variable that affects the filter changes? Should you remove the filter and re-add it?

[tmeasday]

Maybe it should return an off function.

[ndelangen]

I had imagined you cannot remove the filter, I figured that you'd set a new filter that just always return true.
I did this to minimize the amount & complexity of APIs being added as experimental.

I added tests!

[tmeasday]

I had imagined you cannot remove the filter, I figured that you'd set a new filter that just always return true.
I did this to minimize the amount & complexity of APIs being added as experimental.

I don't really understand though. If you set >1 filter, don't they both apply? So wouldn't adding a ()=>true filter have no effect?

When adding the API to set this from manager.ts I discovered the setConfig API seems broken due to a race condition between the manager UI rendering async and the manager being initiated before the manager.ts file is executed.

Can we split the PR up and just do this bit first?

---

I'd like to go over this one together in more detail because as I said elsewhere, I think the approach of doing the filtering in the nodes isn't the right approach, we should filter right at the top in the store. Otherwise we'll constantly be having to refilter everytime we interact with the stories hash, eg in keyboard shortcuts or when addons get the story list, etc.

[tmeasday]

I added tests!

Did you forget to push this bit?

[ndelangen]

I split the PRs apart @tmeasday

[yannbf]

Can result be called something more explicit?