Closes #27521

What I did

This PR adds a new option to the storySort config called weights. This is a simple map of page titles to numbers. Its purpose is to provide an alternate syntax for situations where pages with a certain title (e.g. "Introduction" or "Appendix") should be sorted to the top or bottom of the story list, regardless of how deeply nested they are.

For example, the following is a simplified version of the storySort config for my team's monorepo:

storySort: {
    order: [
        'Introduction',
        'Team Docs',
        [
            'Onboarding',
            ['Introduction', ['*', ['Introduction']]],
            'Monorepo',
            ['Introduction', ['*', ['Introduction']]],
        ],
        'Apps',
        [
            'App1',
            ['Introduction', ['*', ['Introduction']]],
            'App2',
            ['Introduction', ['*', ['Introduction']]],
        ],
        'Services',
        [
            'API 1',
            ['Introduction', ['*', ['Introduction']]],
            'API 2',
            ['Introduction', ['*', ['Introduction']]],
        ],
        'Libraries',
        ['Introduction', ['*', ['Introduction']]],
        'Design System',
        ['Introduction', ['*', ['Introduction']]],
        'Component Library',
        ['Introduction', ['*', ['Introduction']]],
    ],
},

With this PR, we should be able to replace that config with the following:

storySort: {
    weights: { 'Introduction': -1 },
    order: [
        'Team Docs',
        [ 'Onboarding', 'Monorepo' ],
        'Apps',
        [ 'App1', 'App2' ],
        'Services',
        [ 'API 1', 'API 2' ],
        'Libraries',
        'Design System',
        'Component Library',
    ],
},

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

I tested this manually by building the core package and using it in a local Storybook application (the one mentioned in the discussion above).

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for 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:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 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>

Greptile Summary

This PR introduces a new weights option to the storySort configuration, allowing for more flexible and intuitive story sorting based on numerical weights assigned to specific story titles.

• Enhanced Sorting Logic: Modified code/core/src/preview-api/modules/store/storySort.ts to incorporate weighted sorting logic.
• New Test Cases: Added tests in code/core/src/csf-tools/getStorySortParameter.test.ts and code/core/src/preview-api/modules/store/storySort.test.ts to validate the new weights option.
• Type Definitions: Updated code/core/src/types/modules/addons.ts to include the new weights property in the Addon_StorySortObjectParameter interface.
• Documentation Updates: Modified docs/writing-stories/naming-components-and-hierarchy.mdx and added new snippets to demonstrate the usage of the weights option.
• Security Consideration: The use of eval in code/core/src/csf-tools/getStorySortParameter.ts could pose security risks if not properly sanitized.