[META] Roadmap to stabilize Media Library

@samuel.mortenson Fantastic work! :) Thank you for helping to move this issue forward!

+++ b/core/modules/media_library/src/Plugin/Field/FieldWidget/MediaLibraryWidget.php
@@ -317,15 +317,15 @@ public static function addItems($form, FormStateInterface $form_state) {
-            ++$field_state['items_count'];

I realize that, this is not correct. items_count and delta should match. I think we should init items_count with 0 and increase it similar to $delta. or use $delta for the comparison.

Anyway, i added and remove media entities in the widget and the field state was not correct after a few iterations.

We should decide if we want to replace the existing selection or always add new items. Its an odd mix atm.

@samuel.mortenson: re the remove icon, we use libricons for admin facing styling, see https://github.com/ry5n/libricons -- if that has a useful icon for your needs, that would be the most consistent pick.

Tried applying this patch with https://www.drupal.org/node/2831274 #162 and it says

Fatal error: Class 'Drupal\system\Plugin\views\field\SelectFormBase' not found in /home/d1dti/www/core/modules/media_library/src/Plugin/views/field/SelectMedia.php on line 23

upon installing the modules. Should one also apply #2834777: Refactor Drupal\system\Plugin\views\field\BulkForm to support a select form as well or that is not the latest of what to apply?

+++ b/core/modules/media_library/tests/modules/media_library_test/media_library_test.info.yml
@@ -0,0 +1,9 @@
+package: Testing

If you can make this not be in the testing package, drive-by testers using simplytest.me could run with the patch and try it out with the test types. That would not be kept for the final version of the patch of course.

#16: Doesn't work like that, it is not the package that is being excluded. Drupal doesn't look for modules in tests folder unless some flag is setting settings.php or we're actually running a test. So if you want to make it available, you have to move it to a separate folder, outside of tests.

@Berdir: thanks. I think it would be useful to have it in a regular module location then to facilitate testing. Alternatively if the document/image/video patches are in a good enough shape, we maybe want to have a compound testing issue for all of them somewhere :) Asking that now on #drupal-media in IRC.

Youtube recording from UX meeting today: http://youtu.be/hf8AovBZflo

Your views argument includes a view access check for the passed in media type. But media_type only has an admin permission (administer media types), which your test user doesn't have.

It is an interesting feature obviously, but per-type view access is not something that the current media patch/module provides.

@samuel.morteson: the embedding problem has its issue at #2801307: [META] Support WYSIWYG embedding of media entities, I see how it needs to be integrated with the library, but it also needs its own components, eg. markup decisions for the embed code, etc.

Crossed out github link in summary because it seems patches are more recent.

Also added link to #2834777: Refactor Drupal\system\Plugin\views\field\BulkForm to support a select form as well in the summary so that it is obvious you need to apply this patch too.

#2830691: Improve out of the box UI / UX for Media handling from the contrib Media module is related and could be useful.

@dyannenova is working on a significantly updated patch for this. (I don't have a way to assign this to her but it should be).

Also we discussed the latest version of that on the UX call today. Here is the recording (very short, just reviewed this): https://youtu.be/LbQis7Va8zg

Here are my updates on top of the dependencies from #29. This includes styling changes for the media library, and interaction changes, like the toggle for metadata, and hiding actions on the main library page until items are selected.

Here's an example of attaching new media through the library field widget:

Work that needs to be done

I've added an example button for adding new media to the top of the library widget, but this needs to be built out to load the form in the modal and lead the user through adding media and back to the library with their newly added item selected.

Right now the core dialog javascript moves the views filter submit down to the bottom of the dialog. For clarity, this needs to be overridden to move the "Apply filters" button back to the header. The text on the "Selected items" button could also be clearer. On the ux call we discussed using "Attach selected media" instead.

@DyanneNova: Could you upload the last patch without all the dependencies? Thx.

The local tasks were removed based on one of the ux meeting discussions, where everyone agreed that they should be changed to views filters.

I removed the mask because I couldn't find a case where it was needed. Where is it being used? Is there a reason we can't target only the top level for dragging?

I think this makes more sense in the media system component, probably the issue was created before that existed?

Rerolled since the main patch landed. I tried to create a interdiff for 29-35 and used that for the reroll, uploading that as well. Found a new issue for the main patch #2880199: Revision user not set when saving media which causes this to break. So hopefully we can that fixed asap.

*edit
In the end everything works by the way! The admin/content/media page is a little weird (since you can't seem to do anything like edit or delete media items). But picking stuff from the library looks awesome! Nice work!

Enabling Media library media-library-with-dependencies-2834729-43.patch results in a fatal error:

Fatal error: Class 'Drupal\system\Plugin\views\field\SelectFormBase' not found in /[...]/core/modules/media_library/src/Plugin/views/field/SelectMedia.php on line 23

You need to apply #2834777: Refactor Drupal\system\Plugin\views\field\BulkForm to support a select form as well first. I guess that patch should be added to the dependencies patch.

#44 is right, there was a namespace typo in the base class. The attached patch solves it.

Also, moved the config objects from install to optional to allow easy install/uninstall/install without Drupal complaining that the objects already exist in config.

The "-with-dependencies" patch already includes #2834777-17: Refactor Drupal\system\Plugin\views\field\BulkForm to support a select form as well, the other one is the media library patch only.

So I rerolled this patch and fixed a few coding style issues.
I also added media_library view displays for image and file.

This issue is currently also blocked by #2877383: Add action support to Media module

Forgot the interdiff

#2877383: Add action support to Media module is in. Let's give this a re-roll.

Rerolled patch attached, was well as -with-deps.patch for testing purposes.

Sorry, git mishap, should be applying now.

This should fix some of the test failures.

These changes fix errors that arise when using more than one instance of this new widget per form, and when those instances are on fields with the same field name.

I concur with the plan outlined above, and have committed myself as the one to review this code regularly in order to keep @samuel.mortenson and other contributors unblocked.

Let's do this.

Also, I just realized that we're not postponed anymore, so removing that from the issue title.

This looks really promising.

I've asked @starshaped to review the CSS in various browsers/themes, so I'll tag this for screenshots.

1. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,428 @@
   +          row_class: media-library-item
   

   I'm wondering if we should make this a more generic class (and update the CSS/JS to match) so that other parts of Drupal could use the same pattern we're implementing here. Do you think that would be a lot of work? It's a decision we should make now, since changing existing views in update hooks is a nightmare.

2. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,428 @@
   +      filters:
   

   Should we add "created time" or "author" filters by default here? Not sure how much is too much.

3. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,428 @@
   +      tags:
   +        - 'config:core.entity_view_display.media.audio.default'
   +        - 'config:core.entity_view_display.media.file.default'
   +        - 'config:core.entity_view_display.media.file.media_library'
   +        - 'config:core.entity_view_display.media.image.default'
   +        - 'config:core.entity_view_display.media.image.media_library'
   +        - 'config:core.entity_view_display.media.video.default'
   

   Why don't we have entity view displays for audio and video media types too?

4. +++ b/core/modules/media_library/config/optional/core.entity_view_display.media.audio.media_library.yml
   @@ -0,0 +1,29 @@
   +content:
   +  thumbnail:
   +    type: image
   +    weight: 0
   +    region: content
   +    label: hidden
   +    settings:
   +      image_style: medium
   +      image_link: ''
   +    third_party_settings: {  }
   

   Why is 'name' hidden in this view display, but not the File media type's?

5. +++ b/core/modules/media_library/js/media_library.view.es6.js
   @@ -0,0 +1,73 @@
   +        if ($(this).parents('.media-library-item').hasClass('expanded')) {
   +          $(this).parents('.media-library-item').removeClass('expanded');
   +        }
   +        else {
   +          $(this).parents('.media-library-item').addClass('expanded');
   +        }
   

   Couldn't we use toggleClass() here?

6. +++ b/core/modules/media_library/js/media_library.view.es6.js
   @@ -0,0 +1,73 @@
   +  Drupal.behaviors.MediaLibraryHover = {
   +    attach: function (context) {
   +      $('.media-library-item .media-library-item-preview', context).once('media-library-item').on('mouseover', function () {
   +        $(this).parents('.media-library-item').addClass('is-hover');
   +      }).on('mouseout', function () {
   +        $(this).parents('.media-library-item').removeClass('is-hover');
   +      });
   +    }
   +  };
   

   Is there any way this could be accomplished with CSS only? I guess the fact that we're changing the parent makes it impossible, but it was worth asking again...

7. +++ b/core/modules/media_library/media_library.install
   @@ -0,0 +1,22 @@
   +function media_library_install() {
   +  // Disable the /admin/content view provided by media, so that we can properly
   +  // override it.
   +  /** @var \Drupal\views\Entity\View $view */
   +  if ($view = View::load('media')) {
   +    $display = &$view->getDisplay('media_page_list');
   +    $display['display_options']['enabled'] = FALSE;
   +    $view->save();
   +  }
   +}
   

   Should we provide an uninstall hook to do the inverse?

8. +++ b/core/modules/media_library/media_library.module
   @@ -0,0 +1,71 @@
   + * Contains hook implementation for the media_library module.
   

   "implementation" should be plural.

9. +++ b/core/modules/media_library/media_library.module
   @@ -0,0 +1,71 @@
   + * @todo This might be suitable for core as a Twig function.
   

   Follow-up?

10. +++ b/core/modules/media_library/media_library.views.inc
    @@ -0,0 +1,25 @@
    +  foreach (\Drupal::entityTypeManager()->getDefinitions() as $entity_type => $entity_info) {
    +    $data[$entity_info->getBaseTable()][$entity_type . '_select_media'] = [
    +      'title' => t('Select media'),
    +      'help' => t('Provides a field for selecting media entities in our media library view'),
    +      'real field' => $entity_info->getKey('id'),
    +      'field' => [
    +        'id' => 'select_media',
    +      ],
    +    ];
    +  }
    

    Why are we exposing this for every entity? Shouldn't it just be for media items?

11. +++ b/core/modules/media_library/templates/media--media-library.html.twig
    @@ -0,0 +1,53 @@
    + * Other themes are welcome to override this template, which will not break the
    + * functionality of the library.
    

    I'm wondering if we should prove this with a test, since the JS is heavily class-based. I'm also wondering if it might not be a better idea to use data attributes so that we can wrap important markup in Attributes objects, rather than expecting themes to keep the CSS classes.

We could do this - are you thinking that other Views would want the same click-to-check functionality that this patch provides? Where would this live?

Yes, I'm imagining exactly that, and I imagine it would live in Views. We don't have to put it in Views right now, but let's bear this idea in mind and "groom" it for eventual movement into Views.

I think we based the filters off of what the /admin/content View has, which is why there is no author filter. Maybe in UX review we can determine if there's enough there.

I concur. Let's get UX eyes on that.

We need to create a follow up for this, if we still think it's a good idea for other Twig templates. I can create an issue and update the doc block before RTBC.

Sounds good. Please do!

This is a standard template so overrides should definitely work, I don't think extra test coverage is necessary. That said, anyone overriding the template will need to keep certain classes around for the JS to work, so I updated the doc block.

Okay, that sounds like a good compromise.

Looking excellent!

1. +++ b/core/composer.json
   --- /dev/null
   +++ b/core/misc/icons/787878/check.svg
   

   Do we need additional variants of this icon for other color schemes? (That's probably a question for the UX team.)

2. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,418 @@
   +          row_class: media-library-item
   

   Let's change this class to something more generic, so that we can (ideally) bring this click-to-select functionality into Views. Any ideas for what to call it? Maybe 'click-to-select'?

3. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,418 @@
   +        media_bulk_form:
   

   Again, to groom this functionality for inclusion into Views, let's rename the plugin now (click_to_select or something like that, or maybe just 'selection').

4. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,418 @@
   +          element_class: media-library-item-checkbox
   

   Same here.

5. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,418 @@
   +          element_class: media-library-item-content
   

   Should this also be made "generic"? If so, something like 'selectable-content' might make more sense.

6. +++ b/core/modules/media_library/config/install/views.view.media_library.yml
   @@ -0,0 +1,418 @@
   +      filters:
   

   I will be demoing the library to the UX team today and will ask them about the filters. Specifically, whether we have enough, or should have different ones out of the box.

7. +++ b/core/modules/media_library/config/optional/core.entity_view_display.media.audio.media_library.yml
   @@ -0,0 +1,29 @@
   +    - field.field.media.audio.field_media_audio_file
   

   Why is this dependency here? It's not used in the view display; it's really just a dependency of the media type, no? Can we remove it, or was it automatically calculated?

8. +++ b/core/modules/media_library/config/optional/core.entity_view_display.media.file.media_library.yml
   @@ -0,0 +1,29 @@
   +    - field.field.media.file.field_media_file
   

   Same here.

9. +++ b/core/modules/media_library/config/optional/core.entity_view_display.media.image.media_library.yml
   @@ -0,0 +1,29 @@
   +    - field.field.media.image.field_media_image
   

   Same here.

10. +++ b/core/modules/media_library/config/optional/core.entity_view_display.media.video.media_library.yml
    @@ -0,0 +1,29 @@
    +    - field.field.media.video.field_media_video_file
    

    And here.

11. +++ b/core/modules/media_library/css/media_library.css
    @@ -0,0 +1,144 @@
    +#views-form-media-library-page {
    +  display: flex;
    +  flex-wrap: wrap;
    +  align-content: space-between;
    +}
    

    It's SO nice to be able to use flexbox. However, I wonder if we shouldn't make these into generic classes so as to eventually merge this CSS into Views.

12. +++ b/core/modules/media_library/css/media_library.css
    @@ -0,0 +1,144 @@
    +  font-size: 12px;
    

    I'm not entirely certain we're supposed to size type in pixels. This file needs review from a CSS expert who knows the standard practices for core CSS.

13. +++ b/core/modules/media_library/js/media_library.view.es6.js
    @@ -0,0 +1,63 @@
    +        // Links inside the rendered media item should not be click-able.
    +        event.preventDefault();
    

    I'm not sure this will have the intended effect (to prevent links in the rendered content from being clicked). If it indeed does, we should prove that with a functional JavaScript test.

14. +++ b/core/modules/media_library/js/media_library.view.es6.js
    @@ -0,0 +1,63 @@
    +        $(this).parents('.media-library-item').toggleClass('checked', $input.prop('checked'));
    

    Can we use .closest() here, for clarity?

15. +++ b/core/modules/media_library/js/media_library.view.es6.js
    @@ -0,0 +1,63 @@
    +        if ($('.media-library-item.checked').length) {
    

    Can't we just check $input.prop('checked')?

16. +++ b/core/modules/media_library/js/media_library.view.es6.js
    @@ -0,0 +1,63 @@
    +      // Add the toggle when javascript is available
    

    I don't think we need this comment. Anything in a JavaScript file will only be taking place if JavaScript is available :)

17. +++ b/core/modules/media_library/js/media_library.view.es6.js
    @@ -0,0 +1,63 @@
    +        $(this).parents('.media-library-item').toggleClass('expanded');
    

    I think we can prefer .closest().

18. +++ b/core/modules/media_library/js/media_library.view.es6.js
    @@ -0,0 +1,63 @@
    +      $('.media-library-item .media-library-item-preview', context).once('media-library-item').on('mouseover', function () {
    +        $(this).parents('.media-library-item').addClass('is-hover');
    +      }).on('mouseout', function () {
    +        $(this).parents('.media-library-item').removeClass('is-hover');
    +      });
    

    I think we could use .closest() here too.

19. +++ b/core/modules/media_library/media_library.info.yml
    @@ -0,0 +1,10 @@
    +  - drupal:user
    

    Not a big deal, but why do we have the explicit dependency on User?

20. +++ b/core/modules/media_library/media_library.libraries.yml
    @@ -0,0 +1,17 @@
    +  dependencies:
    +    - core/drupal
    +    - core/jquery
    +    - core/jquery.once
    

    I believe jquery.once already depends on jquery, so we can remove the explicit jquery dependency.

21. +++ b/core/modules/media_library/media_library.links.action.yml
    @@ -0,0 +1,5 @@
    +media_library.add:
    +  route_name: entity.media.add_page
    +  title: 'Add media'
    +  appears_on:
    +    - view.media_library.page
    

    The test should assert that this link actually appears.

22. +++ b/core/modules/media_library/media_library.module
    @@ -0,0 +1,84 @@
    +/**
    + * Displays a timestamp in a human-readable fashion.
    + *
    + * @todo This might be suitable for core as a Twig function.
    + *
    + * @param int $time
    + *   A timestamp.
    + *
    + * @return \Drupal\Core\StringTranslation\TranslatableMarkup
    + *   Markup representing a formatted time.
    + */
    

    If we're going to move this into core as a Twig function, let's also mark it @internal.

23. +++ b/core/modules/media_library/templates/media--media-library.html.twig
    @@ -0,0 +1,52 @@
    + * Other themes are welcome to override this template, as long as the
    + * "media-library-item-preview" and "media-library-item-attributes" classes are
    + * present in the template override.
    

    Would it helpful to use data attributes, and/or Attributes objects, for these purposes? Like <div data-media-library-component="preview"> and <div data-media-library-component="attributes"> or something? It might separate the concerns a little more cleanly.

24. +++ b/core/modules/media_library/templates/media--media-library.html.twig
    @@ -0,0 +1,52 @@
    + * - created_ago: This is a Media Library specific variable that contains a
    

    Nit: need a hyphen between "Library", and "specific", e.g. "Media Library-specific".

25. +++ b/core/modules/media_library/tests/src/FunctionalJavascript/MediaLibraryTest.php
    @@ -0,0 +1,86 @@
    +  public function testAdministrationPage() {
    +    // Visit the administration page.
    +    $this->drupalGet('admin/content/media');
    +
    +    // Verify that media from two separate types is present.
    +    $this->assertSession()->pageTextContains('media_1');
    +    $this->assertSession()->pageTextContains('media_3');
    +
    +    // Test that users can filter by type.
    +    $this->getSession()->getPage()->selectFieldOption('Media type', 'Type One');
    +    $this->getSession()->getPage()->pressButton('Apply Filters');
    +    $this->assertSession()->assertWaitOnAjaxRequest();
    +    $this->assertSession()->pageTextContains('media_2');
    +    $this->assertSession()->pageTextNotContains('media_4');
    +    $this->getSession()->getPage()->selectFieldOption('Media type', 'Type Two');
    +    $this->getSession()->getPage()->pressButton('Apply Filters');
    +    $this->assertSession()->assertWaitOnAjaxRequest();
    +    $this->assertSession()->pageTextNotContains('media_2');
    +    $this->assertSession()->pageTextContains('media_4');
    +
    +    // Test that selecting elements as a part of bulk operations works.
    +    $this->getSession()->getPage()->selectFieldOption('Media type', '- Any -');
    +    $this->getSession()->getPage()->pressButton('Apply Filters');
    +    $this->assertSession()->assertWaitOnAjaxRequest();
    +    $this->getSession()->executeScript('jQuery(".media-library-item").click()');
    +    $this->submitForm([], 'Apply to selected items');
    +    $this->assertSession()->pageTextContains('media_1');
    +  }
    

    Let's call assertSession() once at the top of the method and keep re-using the result of that.

    Also, can we definitively assert that thumbnails are being displayed and names are not? Additionally, let's assert that bulk actions are present and functioning as expected.

EDIT: Redacted. See #74.

Removing screenshots for the bug that wasn't.

Open questions for the UX meeting today:

• Does a grid layout like this one raise any accessibility concerns?
• Is it confusing for bulk actions to only appear if media items are selected? Should we show them at all times instead, and display empty text?
• Do we have too many filters? Too few? Are the ones that we have already very useful?
• Are there any styling problems that stand out?
• Should we visually distinguish between published and unpublished media items?
• The creation time is quite plain (e.g. "18 minutes ago"). Should we say something like "Created 18 minutes ago"? Would update time be more useful? Is there any other metadata we should include?

We discussed this in the UX call today. The takeaways...

• The media library introduces a few new UX patterns in core. That means it needs extra scrutiny from the UX, accessibility, and design teams.
• We'll need to sort their feedback into must-haves (major things that should block commit of this patch), and polish (which we can file major follow-up issues for and incorporate into the Media Initiative's roadmap).
• The media library should incorporate some standard "empty text" when there are no items to display.
• It is very jarring for the bulk actions to only appear when items are selected. Although it's not very pretty, let's just show the actions at all times (they should automatically disappear if the view is empty). Fixing the look n' feel of Views-provided filters and actions is beyond the scope of this patch, and there is prior art concerning that problem space, so we can punt on that for now.
• It's not clear how to distinguish between published and unpublished media items in the media library. This needs design input.
• One accessibility thing we should do is ensure that users can tab between the items in the library, press a key (space?) to select them, and hit another key (enter?) to visit them.
• There is no visual indication that a media item is supposed to be clicked on. One idea is to have an empty circle in the top right of each item, which is filled in with a checkmark when the item is clicked on. The only problem there is that an empty circle may not be visible with certain images, due to low contrast. This is another problem that needs design input, in order to ensure that the "selection target" is foolproof, visually speaking.
• The right-pointing chevron is weird -- it connotes a link to another page, rather than expanding or collapsing the item's metadata. Again, we need design input on this. One existing core pattern we could adopt is how the admin toolbar looks when it’s laid out vertically — collapsible sections use downward-pointing chevrons when they are collapsed, and upward-pointing chevrons when they are expanded.
• It's not clear if the metadata should expand downward (below the thumbnail), or upward (covering the thumbnail). This needs design and UX input.
• The media library has no drop buttons for editing or deleting media items. This is basically a regression compared to the current state of things. How can we integrate drop button actions into the media library? Should we even try? UX and design input is needed here.
• How will we support site builders displaying additional metadata? Do we even plan to support that? If so, will it be part of the collapsible metadata for each item? If it will be, what happens if they stuff a lot of metadata in there? This needs UX input.
• We might want to allow users to toggle between the media library grid, and the old table-based list. This is definitely a follow-up, though.

We discussed this in the weekly Media meeting this morning. We decided to continue this work in a more organized set of child issues and convert this issue into a meta, with an updated issue summary.

Whoops, little typo in the issue title.

Sigh, minor typos in the IS.

A question about testing this module along side Media entity browser. Is this module intended as a 100% replacement for Media entity browser? If so, I will track this issue and test the alpha/beta code. If not, which issue is the right one to track?

@peterx, this is not intended to replace Entity Browser at all. It fulfills a bare-bones use case for reusing media, whereas Entity Browser provides infinitely more opportunities for customization. You're certainly welcome to test it, but bear in mind that the media library has a much smaller scope than Entity Browser, and that's by design. :)

Adding some triage headings for the raodmap: must-have, should-have, could-have. I've filled in a few a11y must-haves, and I hope the main initiative team can update the rest.

re: #78

We might want to allow users to toggle between the media library grid, and the old table-based list. This is definitely a follow-up, though.

Massive +1000 from me. That's a really useful thing for accessibility. Not so much for specific WCAG conformance criteria, but a bunch of benefits that are harder to test objectively...

• Offering users a choice of tools is a recognized principle of inclusive design. If you find one interface awkward, try the other.
• Keeping the familiar interface available while they're still leaning the new one, a good strategy to support users with cognitive/learning impairments.
• Reduce frustration for users who might otherwise be annoyed that you took their old tool away, when it worked just fine.
• Many screen readers provide some power tools for navigating table content. Users who are confident with these can save a lot of time with things like "jump to end of row", or quickly going down the title column while ignoring the other fields.
• Sorting the list can easier to understand with a table.
• Reviewing selections (before running bulk-operations) might be easier with a table, too.
• You can fit more items in the viewport with a table than with a card grid. Less scrolling needed for speech control users.

I filed #2973162: allow users to toggle between the media library grid and the old table-based list as a could-have.

Downgrading #2987924: Define an API for finding media types based on an arbitrary value from a must-have to a should-have, based on #2987924-24: Define an API for finding media types based on an arbitrary value.

Making this a child of #3007166: [META] Stabilise and/or remove experimental modules as appropriate in/before Drupal 9 per Gábor's request. Also removing outdated information from the IS.

IMHO should-have

IMHO critical bug so must-have. Escalated that issue to major only to not bikeshed over the prio.

While sprinting on the media library in Barcelona, the team decided to discuss our assumptions regarding the UX and designs, and make them explicit. So here they are, in no particular order:

• We assume that most of the time, users want to add media to the library, rather than reuse items from it. So, although we need to support reuse, we can optimize the UI for the adding media use case.
• We assume that the media library does not have thousands upon thousands of items in it with tons of complex metadata; in that case, we assume users will use a DAM or other tool more powerful than Media Library.
• When adding media, we assume that users know what media type they are trying to add. So the burden of disambiguation is on the user, not Drupal.
• We assume that most sites don’t have an excessive number of media types. We are designing for a site with maybe 5-10 distinct media types, each of which has a clear and well-defined function.
• We assume that users want to add captions to media that is embedded in formatted text. So we are assuming that if media items have a caption field, users will want to override it on a per-usage basis. We are also assuming that captions are distinct from alt text and serve a different function, which means users will want to override alt text as well.
• We assume people don’t mind clicking a button to bring up a modal, in which they can do media stuff. This is necessary due to technical limitations that are pervasive throughout Drupal core.
• We assume that everything you do in the media library modal affects canonical media items, not individual embeds or references. What happens in the media library “stays in the media library”.
• Conversely, anything you do to media items that are linked in a field widget, or embedded in formatted text (not in the modal) is affecting that particular reference/embed, not the canonical item. Nothing ever crosses this boundary. In other words, we are assuming that users see the media library as the canonical, absolute place where media items “live” in their Drupal site. If something is deleted from there, it’s gone from everywhere. If something is changed from there, it (or at least its defaults) are changed everywhere. And we are assuming that users see individual references/embeds/usages as part of the “host” entity, rather than as a canonical thing unto itself.
• We are assuming that people don’t mind making a few more clicks, as long they are always completely entirely clear on what they’re doing. This is consistent with the “don’t make me think” principle. They’re not counting clicks. If they know at a glance where they need to click, they will click. We will strive to keep the number of clicks as low as possible, but we will favor clarity over a low click count.

Overall, we want to build a terrific media library that offers an excellent out-of-the-box experience for relatively simple use cases. Media management is a very complicated problem space, and it's impossible to build something that will please everyone and work for every situation. Complicated use cases, then, will probably need contrib solutions like Entity Browser, and we're comfortable with that; the points above, then, are what we believe constitutes a "relatively simple" use case, and what we intend to optimize for.

I was asked to provide some feedback on this list as well, so here is my take on it from our perspective. I'm of course entirely aware that our customers might not reflect the vast majority of users out there and some might even be very special cases.

We assume that most of the time, users want to add media to the library, rather than reuse items from it.

The main reasons why our customers want a media library or like the concept, when we suggest it to them, are:

• When they need to update a media item they can do it in one place and the change will be reflected throughout the site.
• It is easy to find and reuse existing media items based on media meta data.
• To facilitate reuse of existing media items over adding new ones (for various reasons, I can go into more detail, if needed).
• To use media from a remote system (e.g. an external asset management system).

For the last two cases I think that a UX that treats reusing existing media as a second class citizen would be far from ideal. On the other hand it would probably depend a lot on the final implementation.

Especially for the last case, we have some systems where content editors can't add media in the CMS at all. If they want to use new media items, they have to add it to the external asset management system and then search and select it in the CMS.

Another common pattern with very large organizations is, that customers ask to have special roles for editors that can add and update media items. Mostly, this is for policy reasons (maintaining a certain quality or a consistent design/marketing message, ensuring accessibility requirements are met, ensuring the customer has copyright for a media item and it is properly set in the metadata, etc.).

The feedback that we receive from customers, also from medium or small customers that start from an empty system, is, that once they have created a certain number of media items, they tend to be using the select feature more often over adding new items and they like that they can just select an item that's already there without having to upload the files again and filling in all the necessary meta data again. It saves valuable time in the editing process. I have to admit that this depends somewhat on how easy it is to add new items, so it might be mitigated by the ideal UX for adding new items ;).

Another example that comes to mind: Some customers require their editors to use at least one image for every piece of content. Again, there are different reasons for that and you can argue if it is a sane policy or not. However, in those cases the customer usually has a large number of stock images in its media library that they can choose from for content that doesn't come with an image, which is often the majority of content. This is especially true for some of our customers from the publishing industry.

In principal, I agree that adding media e.g. through the field widget should be straight forward and is a very important use case, but I would not differentiate between adding and reusing media. From the feedback we receive from our customers, I think they are equally important and common use cases.

We assume that most sites don’t have an excessive number of media types. We are designing for a site with maybe 5-10 distinct media types, each of which has a clear and well-defined function.

I already mentioned that one before in a discussion with seanb: Especially some of our large customers (think of a federal government agency, the website of a large city, a large academic institution, a large NGO) tend to have a requirement for more than 5-10 media bundles. At the field level this is indeed not a problem since we usually only allow a few bundles per field, but when it comes CKEditor integration, we usually allow to embed any type and the interface has to work with that.

We are assuming that people don’t mind making a few more clicks, as long they are always completely entirely clear on what they’re doing.

This is something I personally agree with, however we often get feedback from customers large, medium and small that a click on button x is not needed or why do I have to click on this and then on that, wouldn't it be enough to just click on this and then the action is done automatically? Given how often this comes up, it seems that content editors are very sensible to clicks that could be saved, especially if they work with the system for some time. W/r/t media library for example, a regular request of our customers is to just select a media item as soon as a user clicks on it for fields with a cardinality of just 1 item. "Why do I have to click on 'Select'?" is a regular question. When I explain that this is (probably) done to keep it consistent with fields that have a cardinality greater than 1 and it is more clear to users not as familiar with the system, they insist that they want this. "We will mention it during training, it is more important for us to be able to quickly get things done. As soon as a user uses the feature once, they will learn how it works and expect it the next time", etc.

I can 100% agree with the rest of your assumptions, they are in line with how we think our customers are using the system and with the feedback we receive.

I hope this was helpful to you. If I should elaborate on any of the points or you have any questions, let me know.

When someone decides to use something extra from media, such as EXIF info, is it intended that they install a replacement for media library or should developers look at creating modules to add on to media library?

Conversely, anything you do to media items that are linked in a field widget, or embedded in formatted text (not in the modal) is affecting that particular reference/embed, not the canonical item.

I don't think I understand this. How would this look practically? If users selected a media item from the library on a media reference field, then that media item becomes "detached" from the library?

When someone selects a media item, say an image, and replaces it, every reference will get the new image.
When someone selects a reference and changes it, the reference would point to a difference media item, the original item will remain unchanged, and all other references to the original will continue to point to the original.

what is not defined is what happens when the original is deleted. There would be references pointing to nothing. Presumably there would be a warning about deleting an item before all references to the item are changed. There would also be a list of all references to the item so that you can change or delete all references before deleting the item.

what is not defined is what happens when the original is deleted.

Media fields are simple entity reference fields -- at the data layer, there is nothing different about them at all. The media library is just a nice interface for them, but they are still standard entity reference fields. So the same thing would happen as when you delete a node or taxonomy term (or any other entity) that is referenced from an entity reference field.

And because it is a standard ER field, it means you can use the entity_usage project, which in the latest version, has configurable (per entity type) messages on the edit and delete form that warns users about existing usages.

Some thoughts/questions:

* What is the place of the entity browser project? I don't think media library aims to provide the same extensibility as entity browser does, so there is still a place for that IMHO, e.g. to integrate external DAM systems like we did for e.g. Bynder. Would be really neat if we could update entity browser to benefit from the UX improvements done here. Or do you think the media library will be extensible enough to cover that and entity browser might just become a way to configure it, so similar architecture without the UI to change it?
* You mention a lot of assumptions, the question is whether there will be ways to change them. For example, dropzonejs also doesn't offer any type-detection out of the box, but it does have events which we are using to do exactly that in our distribution.
* I do agree with the library vs local behavior and what affects what, we treat that the same. Question is, how exactly do you plan to achieve per-usage description/alt text? A regular ER field can not handle that, it would need a custom type, actually just like the current image field type which is a reference + per-placement alt/title. Except it is more complex than that, because each media type will have different fields, e.g. a youtube video type will not have an alt text. Also, that isn't really a media library feature as it's actually by definition outside of it :)

Added a bunch of new issues based on the new designs being created in #3019150: Update/improve mockups and designs for the media library.

Also reevaluated the priority of issues with webchick and phenaproxima. The list is now more or less in the right order.

Added a WCAG level-A issue - #3024184: Make the tabbing order match the visual reading order in MediaLibraryWidget. This has a patch to fix the problem, but it still needs a bit of CSS too.

Adding #3023966: Remove unnecessary title attribute from show-row-weights button. as a nice-to-have. That issue is mainly about tabledrag, but the media library widget has a custom version of the show-weights button.

What's the "questionable" category for here? Maybe it belongs in there.

Removing #2987924: Define an API for finding media types based on an arbitrary value from the IS, as it is now closed for good since it was based on outdated assumptions.

Also updating the ones that are done.

Added new issues.

New must-have: #3033943: MediaLibraryWidget selected items count is not conveyed to assistive tech correctly. I put a detailed plan there.

Added #3033960: After adding media, return the user to the media listing they started from. A should-have, I think.

Added #3033442: Use 24 items per page for better responsive grid behavior as a could-have. Simple and small, makes for nicer responsive grid behavior.

Added a few should-have UX issues to the roadmap.

Adding #2973140: Convey AJAX progress messages to assistive technology. as a should-have.

The issue isn't specific to Media Library, however there is a LOT of AJAX going on in in the MediaLibraryWidget. By my count there are at least 3 AJAX behaviours there which can benefit from this: changing tab, changing filters, changing to grid or table.

Tentatively adding a must-have: #2805219: Some dialogs do not receive focus when opened. This bug isn't actually media library's fault, and it affects dialogs elsewhere. So we can change the status if you like.

We have dialogs in various places in our admin UI, but prior to media library all the instances form part of a site builder task. I asked on Slack, and we believe MediaLibraryWidget is the first use of a dialog as part of a content editor task. (I'm not counting dialogs from CKeditor, as those are a different implementation).

My reason for marking it as a must-have comes down to our value of "prioritize for impact". Content editors outnumber site builders. In a large organization, there can be hundreds or thousands of editors, and a mere handful of site builders. Many users of company intranets may not even know what Drupal is. Smaller organizations may have sites built by agencies, where the site builders are all in the agency, and no-one in the client organization has encountered a Drupal dialog before. The point is the audience for our dialogs is about to increase, and MediaLibraryWidget is affected by this bug, so it has become more important to fix.

We've been doing more accessibility review, and fleshing out #2988431: [Meta] Accessibility plan for Media Library Widget. That issue is already mentioned in the must-haves here. There are many accessibility issues arising from the design updates in #3019150: Update/improve mockups and designs for the media library, notably the tabs in the MediaLibrayWidget dialog. Now the accessibility plan also has some child issues of it's own, which need further triage into must/should/could. I'll bring those over here soon.

#2996029: Add oEmbed support to the media library and #3033100: Media library field widget styles are broken on initial page load just landed. Yay!

A bit more a11y triage. Should have #3035316: ‘Add media’ in MediaLibraryWidget should be a button, not a link

a11y triage - I'd like to treat #3016807: Improve refocus on submit buttons of Media Library Widget modals as a must have. Without that, it's a very disorientating for keyboard users and screen reader users.
It's not really addressed by WCAG though.

During the UX meeting today we discussed an awkward chicken-and-egg problem with #2981044-64: Unify the grid/table views of the media library where we need to fix a level-A WCAG issue, but we have to do it with a template override in Seven (or Classy), and we can't add a template to a core theme until after we have marked media library as a stable module.

So between the product managers (@webchick + Gabor), the media leads (@phenaproxima and @seanb), and myself, we have agreed a special handling of the accessibility gate.

• We can mark media library as stable, knowing it has a WCAG level-A problem, so long as there is a feasible follow-up issue lined up to address this soon after.
• The follow-up will be treated as a release blocker for the minor version of Drupal core as a whole.
• Ideally the follow-up should have a working patch ready to go straight after we mark media library as stable, so we minimize the chance of a gotcha we didn't see coming.

Adding a note about that in the IS.

#3035994: Add a Media Library views template to Seven theme to change to order of the views header and exposed filters was filed as the follow-up mentioned in #126

#2964790: Move formatting code in TimestampAgoFormatter into DateFormatter refers to code which no longer exists (if it ever did) in Media Library. I think this issue arose from an older generation of the design for the Media Library, which displayed creation dates in the grid of media items. Dates were removed from the UI long ago, due to clutter, so that issue no longer needs to be part of this roadmap. I'm removing it.

The bug that #2989503: Add tests to prove that the media library widget works when target_bundles is NULL is testing for was inadvertently fixed in #3020716: Add vertical tabs style menu to media library, so I'm going to de-escalate it to "should-have" priority.

Moving a couple of issues into the "done" list. :)

Adding #3037666: Consider renaming the grid display of the media library and #3037668: Improve visual coherence of the media library as could-haves.

Adding some new issues that were created.

Added some more follow ups and re-ordered the must haves. Also added a group of issues that are blocked on the module becoming stable.

#3037767: Improve responsive styling of grid items in the media library and #3035316: ‘Add media’ in MediaLibraryWidget should be a button, not a link are in. Yay!

Moved #3023801: Allow newly uploaded files to be deleted from the media library without saving them to the "done" list. :)

And #3016807: Improve refocus on submit buttons of Media Library Widget modals :)

Crossing #3023797: Let users choose what to do after selecting and/or adding items in the media library off the list! :)

^ That officially marks Media Library "UI complete" for 8.7!! If you haven't given it a whirl in awhile, please do! (Clone from Git, or wait until 8.7.0-alpha2/beta1).

Here's a demo video by @seanB showing off the AMAZING progress!

So can we assume that this will be available in 8.7 when released?

@Christopher Riley: In a word, yes. Everything in the demo video will be in Drupal 8.7.0 alpha2 and beyond.

Yep, though note that the module is still experimental and not yet stable... targeting that for 8.8.

#3019150: Update/improve mockups and designs for the media library is now marked Fixed, so I'm moving it into the "Done" list.

Removed #2113931: File Field design update: Upload field. from the must have list. While it is important for the media library, it is not actually solved in the media library module, and can not be a stable blocker imho.

Added #3020907: Avoid horizontal scrollbar in media library dialog when using small viewports to the list of fixed items. This has been solved in #2981044: Unify the grid/table views of the media library.

Removed #2805219: Some dialogs do not receive focus when opened from the list. This has been solved in #3035316: ‘Add media’ in MediaLibraryWidget should be a button, not a link for the media library and the solution has been added to the issue to hopefully help that move forward.

I guess the issue with #2113931: File Field design update: Upload field. being removed from the "must-have" list is that until that's done, the media library does not match the designs. And it's not a little quibbly on-the-margin thing in the designs (like, say, the "X of 5 uploaded" bit) but THE interface through which one uploads new media. :\

until that's done, the media library does not match the designs...THE interface through which one uploads new media

That's true if you interpret the media library to include the interface through which one uploads new media. However, media_library.info.yml says:

Enhances the media list with additional features to more easily find and use existing media items.

Which does not include uploading new items.

It's a product management decision as to whether adding new media is sufficiently part of or adjacent to the media library to warrant keeping the module experimental until that's done. But from my perspective, I think it's reasonable to call it stable if everything related to the scope of "finding and using existing media items" is stable.

Well, uploading new things is included in the Media Library directly these days; here's a screenshot from the above video:

We probably need a follow-up to change the module description (and hook_help()?) accordingly.

Compare/contrast with mocks at #3019150: Update/improve mockups and designs for the media library:

As to whether it's worth blocking... I'm not sure. If it was the only issue remaining, I can see the logic for letting it through as stable, since it's not introducing "new" ugliness. But OTOH, the drop zone is a significant part of the new designs, so seems kinda like shipping a three-wheeled car without it. :\

Added #3042407: Add access checking for the passed selection IDs in the Media Library. as a must-have.

Added the issues related to implementing #2801307: [META] Support WYSIWYG embedding of media entities.
Moved #3023809: Add a selection overview to the media library widget modal to the list of should haves, since this came up a couple of times during the UX and A11Y reviews.
Also added #2113931: File Field design update: Upload field. back to the list of must haves. Even though this is not something that is solved in the media library module, we agree that that having this makes a big difference.

#3033653: InvalidArgumentException when adding reference field without Media type has landed!

#3033943: MediaLibraryWidget selected items count is not conveyed to assistive tech correctly landed! Another one bites the dust...

I moved 3 completed issues that were crossed out into the `Done` section from other sections to help readability of what's left to do.

#3037668: Improve visual coherence of the media library is in!

Adding #3060603: Live preview is broken when editing the media_library view as a must-have stable blocker. My justification for this is that part of Media Library's flexibility is the fact that it's built around a view, and live preview is very important for customizing that view. If live preview is broken, Media Library is automatically much harder to configure.

#3038350: Deny access to all media library View Displays if there is no valid state object is in. :)

#3035446: Inform assistive tech users about the outcome of using the MediaLibraryWidget dialog just landed. Yay!

Making #2994702: Allow editors to alter embed-specific metadata, as well as `data-align` and `data-caption` and #3023807: Override media fields from the reference field into strong should-haves for this roadmap.
The detailed reasons are in comments 8-10 at #2994702-8: Allow editors to alter embed-specific metadata, as well as `data-align` and `data-caption`.

Heyo! #2990664: Media library does not work when Drupal is installed into a sub-directory landed :) Another stable blocker bites the dust!

Sorry -- accidentally moved that to the wrong list.

Removing #3019201: Improve UX of the 'Remote video' media type which is now obsolete. Also removing some duplicates.

Removed #2985168: [PP-1] Allow media items to be edited in a modal when using the field widget from the roadmap after wontfixing it following discussion with @seanB and @xjm at Drupal Dev Days Cluj.

Removing #3023767: Reuse or build on vertical tabs styling in media library and #2988215: Use #element_validate for the upload element in the MediaLibraryUploadForm from the roadmap.

Moving #2969678: Integrate Media Library with Content Moderation to the must-have list after discussion with @xjm.

Removing #2973124: Provide better context in accessible names of EntityOperation views plugin drop-button operations from the roadmap. The media library view/widget itself, which is the most author-facing part of the Media system, is not affected by this issue because it does not expose any dropbuttons, and this is a wider problem in core. I'm moving it to the Media Initiative roadmap instead, because it affects that aspect of things much more severely.

Moving to #3003150: Media library causes validation errors when it is used in a required field of a nested form to should-have list per discussion with @xjm.

EDIT: Also removed the item about adding "carousels for multi-value wizardmagick" because, as we recall it, the UX team did not like this idea, and it can certainly be done in contrib.

Following a discussion with @seanB and @xjm, I need to update this roadmap with issues that have been created since late March, 2019, which is the last time our queue was properly triaged.

I am adding:

• #3041147: Preserve the selected items across multiple uses of the media library (could-have)
• #3049943: Media library should not use js- prefixed CSS classes for styling (should-have)
• #3050508: Media library loads front-end theme when invoked from settings tray (should-have)
• #3055048: Media Library insert doesn't show custom fields (should-have)
• #3055516: Notice: Undefined index: target_bundles when new reference media field created (should-have)

Ta-da! #3019202: Rename "File" media type to "Document" is in.

#3044649: Delegate media library selection handling to the "thing" that opened the library is in. Awwww yeah!

#3060603: Live preview is broken when editing the media_library view bites the dust.

Added the A11Y must-haves to the roadmap for better visibility of the remaining work.

#3035408: Identify purpose of vertical tabs in MediaLibraryWidget dialog for assistive tech users. is in!

I just had a quick call with @phenaproxima and discussed what he raised earlier in chat as well. Unfortunately #2113931: File Field design update: Upload field. turned out to be a no-go in terms of implementing the widget as designed. Unfortunately it needs to go back to the drawing board in terms of accessible markup and visual design that goes with it so it looks unlikely to be ready soon. It is my understanding that this is a massive UI improvement but it does not degrade accessibility or other requirements to not have this feature update in place. So while I would really love to have this UI improvement in, it sounds unrealistic to hold the stability of the whole of media library to this pre-existing UI component issue. That said, I support moving the successors of that issue to the top of the should have list from the must have list.

Thanks, Gábor. Fixing the issue summary as agreed.

#3038254: Delegate media library access to the "thing" that opened the library is in, completing #2983179: [META] Implement stricter access checking for the media library. All RIGHT!

Added two more must-have WYSIWYG issues to the IS.

Removing #3039829: Remove link to media item from media library view. from the should-have list; it is a must-have and is listed as such.

Adding #3059955: It is possible to overflow the number of items allowed in Media Library to the should-have list, since it is a major UX bug; adding #3065677: Create a media_library form element to the could-have list, since it'd be a lovely feature for DX.

We landed #3039829: Remove link to media item from media library view. so that means the meta issue #2988431: [Meta] Accessibility plan for Media Library Widget now only contains should-haves and could-haves.

#184:
The a11y plan still has some points listed as "needs triage". Now that the a11y is much further along, it would be good to do another triage pass over that list, just in case we missed any must-haves.

#2940029: Add an input filter to display embedded Media entities landed; that's one step closer to WYSIWYG support in core!

Added #3063216: Inaccessible Media entities still have rows generated for them in the Media Library view, containing form wrapper markup *and* the media label.

#2994696: Render embedded media items in CKEditor is in! Adding #2994702: Allow editors to alter embed-specific metadata, as well as `data-align` and `data-caption` to replace it.

Adjusting the issues linked the IS per product manager feedback in #2801307-94: [META] Support WYSIWYG embedding of media entities.

Adding #3077756: Improve description of the Media Embed filter as a stable blocker.

Removing #3077756: Improve description of the Media Embed filter as Must-have, as it's been decided to fold that back into #2994702: Allow editors to alter embed-specific metadata, as well as `data-align` and `data-caption`.