Request ModalManager Documentation for Proper Customization of Default Implementation

Issue — Shortened Version

1. Are lib consumer custom implementations of the default ModalManager module/class discouraged? Root level named imports are available but ignored. Logically, I would say otherwise. So why not remove @ignore tag for discovery and code completion?

2. What is the exact purpose of mui ModalManager class and decision to not provide documentation in component api docs or minimally elaborating class doc comments? Describing its proper default user implementation including the optional manager prop of the Modal component, additionally default class extension uses and/or composition for making utilizing the state mgmt functionality within similar “dialog-like” custom components?

Issue — Elaborate Version

The ModalManager class doc comment specifies the ignore tag since its conception in 2017 as follows @ignore - do not document.. Is there a designated reason why there is no interest in providing support for component api docs detailing appropriate consumption, proper invocation of member functions and public properties to support use by lib consumers for enabling custom modal components, composition or inheritance which desire it as a default implementation?

https://github.com/mui-org/material-ui/blob/4300a41e99f53704ebcd09bcb3c06724ac014171/packages/material-ui-unstyled/src/ModalUnstyled/ModalManager.ts#L153-L160

Contextually, if the decision was based on the styling having been coupled to the component, the upcoming next major release (i.e. v5.*), may now alleviate the problems which lead to the original decision and/or potentially arise a yearning desire from lib consumers when using the new unstyled components. Provided that the consumer is building custom component with overlay/modal-like state mgmt, or overriding its implementations to modify the default modal containers’ style behavior or similar etc.

Note: A probable chance I may have construed a misinterpretation to the key differences of the ModalManager implementation from mui including the modules’ non-exported utility functions, in regard to the doc comment stated inspiration of the ModalManager implementation from react-overlay ; in which case it would be helpful to receive an explanation providing answers to the following and all other relevant information for the purpose of research or investigation from lib consumers in the event it remains undocumented:

1. Intent of separated module existence from Module component? (Seems odd as similarly defined large lib components lack regard for separation solely for the purpose of organization or module size)

2. Reason of re-export within directory barrel files? (i.e. not requiring direct module path import requirement to discourage implementations, therefore supports root level import and extensions)

3. lastly, Is it actually discouraged? being that yes it can be consumed/imported/extended but lacks official support of component api docs, curiosity arises in the purpose of @oliviertassinari opinion to a request of either updating the existing comments, or api docs, or subsequently the position/view of he and other active maintainers which oppose the decision to provide an elaboration in the doc comments of the class implementation at minimum?

Otherwise, while still providing named exports in the module directory barrel which also includes a re-export of the entire module as an alias; then the root lib barrel re-exports the module barrel—consequently, providing a capability to import at root level. Perception: obviously not strictly discouraged. So…why doc comment @ignore tag? Disallowing ease of ModalManager discovery and code completion when importing.

[eps1lon]

Is there a designated reason why there is no interest in providing support for component api docs detailing appropriate consumption, proper invocation of member functions and public properties to support use by lib consumers for enabling custom modal components, composition or inheritance which desire it as a default implementation?

By default, nothing is documented. We only document APIs that are useful to solve a problem.

Using props, classnames, exports etc that are not documented are not part of the public API and can therefore break in any release. So you can use them, but if the next release (be it patch, minor or major) breaks that usage, we don’t plan to resolve that breakage.

Hope that explains some internals.

Is there an actual problem in your application that you think should be solved by Material-UI?

[zgover]

@eps1lon yes, I’m aware now. I’m not asking anything?? My most previous response never presented any questions. I only tried giving clarity which led to my misconception of assumed support accompanied by my misinterpretation of the (above) docs quote. I’d assume internals would be inaccessible or at least removed from top-level imports.

Does that clear up your confusion now?