Manage Projects UI

[dannysmith]

I think the most sensible solution to all this stuff is to build a proper project manager into the settings which:

• Shows all projects which have been opened (ie those stored in the project registry) in a nice UI.
• Shows settings for each project (and it's collections) to be edited regardless of the currently open project.
• Allows users to visually map schema content collections to content folders etc, with auto-mapping based on common paths and the glob loader paths in the schema.
• Allows visual mapping of fields to the UI behaviours they control, per collection (eg "draft filter/label", "default sidebar sort", "field to use as title", "field to use as description", "date field to show in file sidebar".
• Clearly shows any errors when reading or merging the schemas for a given project.
• Allows the deletion of projects from the registry.

Originally posted by @dannysmith in #81

This is a fairly large task which will probably fundamentally touch a number of areas and require us to solidify and adjust the mental model of how data works in this system, in particular the entities which represent:

• An Astro project, as it is on disk
• A content file on disk
• A folder on disk, containing content files
• An Astro content collection (as defined in content.config.ts, which may or may not have a schema, and may not be named or mapped neatly to a folder)
• A schema (for a given content collection), as defined in content.config.ts
• A Project in AE (including it's persisted settings etc)
• A Collection in AE (including its persisted settings etc)

Thoughts on the Project Manager UI

Should show all projects stored in the registry and allow adding and deleting them. Those which are "corrupted" somehow should be shown as such (ie the files have moved on disk).

As few settings as possible should be stored at the project level (maybe just root path and path to content.config.ts?). Pushing all the settings down to the collection level removes the complex default → global setting → project override → collection override thing.

Content Collection Settings

Each collection should own its setting for:

• Content directory path (discovering content)
• Assets directory path (creating/previewing assets)
• MDX components directory path (finding MDX components)
• Absolute vs relative path for assets/links setting
• Field to use as "draft" (draft label and draft filter only)
• Field to use as "title" (search, sidebar title, top frontmatter field etc)
• Field to use as "description" (search, special frontmatter treatment etc)
• Default sort field (ie current "pubdate") and order (desc/asc)- any sortable field should work: date, string, integer etc.
• Default filetype for new files (MD/MDX)
• Default filename pattern for new files [new setting for Better "New" File Naming #87]
• Ignore List [new setting a la gitignore]

The UI should show how each of these settings is used in AE and whether it is:

1. Set - Stored in the AE settings on disk because the user has set it here.
2. Unset - Not present in the AE settings on disk and so falling back to something else.

If unset, it should show clearly what AE is currently using. This may be a hard-coded default, Astro convention, or a value inferred from the schema. Eg for a content collection with a boolean field named "draft" in the schema it should show that that's being used. For a content collection without such a field, it should show a warning and make it clear that no draft-related functionality will work.

The UI should also very clearly show the full schema as read by AE (ie from the generated schema file, enriched for things like image() and references(). Each schema field should show it's name, type, description, optionality, constraints, default etc and describe how these are being used by AE. Where possible, schema fields which can't be read by AE should have a warning explaining how they'll be handled in the UI.

Both these should work together (or possibly be one thing) to explain how things currently are, and how to configure a collection in AE as desired.

Making it not rubbish to get set up

The current model is basically: It should work out the box; if not then you can override some settings at the project level to make it work; and if that doesn't help you can override them at a collection level.

Pushing most settings down to the collection simplifies things in many ways, but makes things more complicated when the user has either a standard way of doing things across all collections in a project, or a standard way of setting up all their Astro projects.

I think the best solution here is to provide a way to "copy this collection's settings to all other collections in this project. But this might need more thought.

[dannysmith]

@louisescher and @Snugug - I'd value your thoughts on this whole thing if you have any 🙏

[louisescher]

Should show all projects stored in the registry and allow adding and deleting them. Those which are "corrupted" somehow should be shown as such (ie the files have moved on disk).

I'd go with the approach of VSC, Zed and other IDEs here. Provide a modal in which you can search for and select a project, then open or delete it. Opening a new project should also be possible from this modal. We don't check all folders on startup for if they exist or not, as that would create disk overhead. We simply try to open a project when the user clicks on it, then show an error saying that no project has been found should the project no longer be there.

As few settings as possible should be stored at the project level (maybe just root path and path to content.config.ts?). Pushing all the settings down to the collection level removes the complex default → global setting → project override → collection override thing.

Fully agreed.

For a content collection without such a field, it should show a warning and make it clear that no draft-related functionality will work.

I think that this is a good idea. The warning could be a pop-up. I think it's important to allow the user to either dismiss it once or permanently, because some projects simply may never need a draft functionality and this would mess with the UX.

copy this collection's settings to all other collections in this project.

Maybe there could be a .astro-editor file users can place in the repository, which stores these settings? If such a file is detected, AE can respect it and use it as the default. There could then be a setting to write the currently modified settings to this file to allow for good portability, even across different systems.

[dannysmith]

Thanks - appreciate it 🙏

I think it's important to allow the user to either dismiss it once or permanently, because some projects simply may never need a draft functionality and this would mess with the UX.

I think I'd probably wanna keep this all tucked away in some "project settings" place and not have any of this encroach on normal use except when a) opening a fresh install or b) adding a new project.

Maybe there could be a .astro-editor file users can place in the repository, which stores these settings?

I've thought about this (#57) multiple times and it always feels icky to me because AE should just be a nicer interface for interacting with an existing project. Writing files like that feels too intrusive somehow. It'd only really make sense if multiple folks are using AE to work on the same project.

I guess I've also been trying to avoid the need to store any settings where possible, but that hasn't really worked out as I've started to support a wider range of Astro setups 😂

[louisescher]

except when a) opening a fresh install or b) adding a new project

Agreed. Show it once and have the settings be greyed out, maybe with a warning message.

AE should just be a nicer interface for interacting with an existing project

It can still be that! Just means that users who need to can export their settings into a nice, portable format.

[nickradford]

Hi @dannysmith, would you be open to a PR that adds a temporary Open Project button to the Welcome Screen?

It's unclear what the first action for a new user should be currently and I almost bounced from this cool project until I watched your youtube demo and saw that ghost folder icon in the left sidebar.

Something like this:

Obviously the full projects UI would replace this, but could help other users like me who were confused on how to actually open a project.