Site Admin: introduce package

[retrofox]

This package provides the necessary resources to implement a modern administrative interface within the WordPress admin.

It includes components for UI construction, a routing system that allows dynamic management and decoration of different layout sections based on active routes, and other resources designed to create a consistent and modular administrative experience.

It is inspired by (if not directly copied from) the core implementation, particularly the Site Editor, replicating its structure and behavior to ensure coherence and compatibility within the existing ecosystem.

Remaining tasks

• Remove @wordpress/edit-site dependency
• Add documentation
• Add basic storybook
• ...

Related to #

Proposed Changes

Why are these changes being made?

Testing Instructions

Pre-merge Checklist

• Has the general commit checklist been followed? (PCYsg-hS-p2)
• Have you written new tests for your changes?
• Have you tested the feature in Simple (P9HQHe-k8-p2), Atomic (P9HQHe-jW-p2), and self-hosted Jetpack sites (PCYsg-g6b-p2)?
• Have you checked for TypeScript, React or other console errors?
• Have you used memoizing on expensive computations? More info in Memoizing with create-selector and Using memoizing selectors and Our Approach to Data
• Have we added the "[Status] String Freeze" label as soon as any new strings were ready for translation (p4TIVU-5Jq-p2)?
  • For UI changes, have we tested the change in various languages (for example, ES, PT, FR, or DE)? The length of text and words vary significantly between languages.
• For changes affecting Jetpack: Have we added the "[Status] Needs Privacy Updates" label if this pull request changes what data or activity we track or use (p4TIVU-aUh-p2)?

[github-actions]

Calypso Live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-132416

Jetpack Cloud live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-132416&env=jetpack

Automattic for Agencies live (direct link)

https://calypso.live?image=registry.a8c.com/calypso/app:build-132416&env=a8c-for-agencies

[matticbot]

This PR modifies the release build for the following Calypso Apps:

For info about this notification, see here: PCYsg-OT6-p2

• notifications
• wpcom-block-editor

To test WordPress.com changes, run install-plugin.sh $pluginSlug update/introduce-site-admin-package on your sandbox.

[matticbot]

This PR does not affect the size of JS and CSS bundles shipped to the user's browser.

Generated by performance advisor bot at iscalypsofastyet.com.

[youknowriad]

The biggest missing thing here IMO is the documentation.

• How do people discover this package? Do we have a package reference or something?
• When should people use this package and how? What are the public APIs of this package.

Some of this would help with reviews too.

[retrofox]

The biggest missing thing here IMO is the documentation.

• How do people discover this package? Do we have a package reference or something?
• When should people use this package and how? What are the public APIs of this package.

Some of this would help with reviews too.

I don’t fully understand the question 😓. Would it simply be a matter of improving the documentation? For example, we could add a section explaining how to discover the package within the codebase and when it should be used. We could also include details about the available public APIs and usage examples to facilitate adoption.

If that’s what you mean, and just for your information, we’re still in the development process. These aspects haven’t been addressed yet. The main goal of this draft PR is to evaluate how much sense its implementation makes.

[youknowriad]

For the first question, yeah it's a more general question and not specific to this particular package. Like do we need a package reference like there is one for the block editor https://developer.wordpress.org/block-editor/reference-guides/packages/

And how do we raise awareness about the different available packages and possibilities among all engineers to avoid recreating the same things over and over again. I'm sure @tyxla and his team might have thoughts here.

---

The second question is more practical, like I'm not really sure from the PR description what this PR does and the README of the package is empty. I think we should have a README with all the available APIs and how to use them. Like I'm a Woo developer and I want to build a new "section/page" with the proposed framework, how should I do that.

[retrofox]

Oh yes, sure thing 👍
I wasn't concerned about it because this is still a DRAFT PR in the middle of the dev process.
Going to update it soon.

[tyxla]

If we decide to go with this "copy from Gutenberg" approach, I'd expect we keep a meticulous documentation, including wha, where, and from which hash/version we copied, plus a thorough changelog of all changes so we keep track of any potential divergence from core in the future.

[retrofox]

I couldn't agree more. I'd like to edit all commits or create a new branch from scratch to register all changes properly.

[tyxla]

And how do we raise awareness about the different available packages and possibilities among all engineers to avoid recreating the same things over and over again. I'm sure @tyxla and his team might have thoughts here.

This is a hard one IMHO. We can't stop folks from doing the same thing (copying the same components in their local copies), and that's one of the main reasons why we want to be extra careful. If we go that way, let's make sure to do all the due internal developer advocacy so folks are aware this exists, what it offers, and what it exposes from core. We need to make it clear that anyone who wants to use these APIs ideally needs to use this package, and not reinvent their own local version.

[retrofox]

This is a hard one IMHO. We can't stop folks from doing the same thing (copying the same components in their local copies), and that's one of the main reasons why we want to be extra careful.

In case dev folks need a resource that is provided by this package, we should just let them know. Basically, to avoid a new copy. In other words, this package should be the primary source.

If we go that way, let's make sure to do all the due internal developer advocacy so folks are aware this exists, what it offers, and what it exposes from core. We need to make it clear that anyone who wants to use these APIs ideally needs to use this package, and not reinvent their own local version.

This is a somewhat exhausting effort since it relies a lot on personal commitment and responsibility from each developer. This creates a high chance of introducing errors and bad practices simply due to human nature.

The good news is that I’ve seen some pretty ugly things lately, so as long as we handle this correctly, I don’t think it can get much worse 😄. Anyway, you never know.

That said, clear and effective communication will be key here.

[tyxla]

This creates a high chance of introducing errors and bad practices simply due to human nature.

I'm glad we agree on the potential fragility and change for introducing technical debt here.

That said, clear and effective communication will be key here.

That, as well as ownership and responsibility - specifically, following up on what we agreed upon when making those compromises - when the time comes.

[retrofox]

@youknowriad @tyxla, for the sake of the development, I suggest closing this (kinda PoC) PR.

We can split and register the tasks in this EPIC issue: #99473

I will add sub-tasks, but please feel free to add/comment as well on whatever you consider appropriate.