ui docs

docs/index.rst

@@ -20,5 +20,6 @@ Welcome to the EdgeDB |version| documentation.
     stdlib/index
     clients/index
     cli/index
+    ui/index
     reference/index
     changelog/index

docs/ui/auth_admin.rst

@@ -0,0 +1,16 @@
+.. _ref_ui_auth_admin:
+
+==========
+Auth Admin
+==========
+
+The Auth page inside the EdgeDB is used to set up authentication for
+your app built into the EdgeDB server. The details for setting up auth
+admin via are in their own guide :ref:`here <ref_guide_auth>`.
+
+.. image:: ../guides/auth/images/ui-auth.png
+    :alt: The EdgeDB local development server UI highlighting the auth admin
+          icon in the left-hand toolbar. The icon is two nested shield
+          outlines, the inner being a light pink color and the outer being
+          a light blue when selected.
+    :width: 100%

docs/ui/client_settings.rst

@@ -0,0 +1,57 @@
+===============
+Client settings
+===============
+
+.. image:: images/client_settings.png
+    :alt: The EdgeDB client settings dropdown bar showing two sample settings
+          that can be set: apply access policies, and implicit limit. Apply
+          access policies is set to false, and implicit limit is set to 100.
+    :width: 100%
+
+The UI exposes a number of :ref:`configuration parameters <ref_std_cfg>`
+in a dropdown bar at the top of all database dashboard screens when the
+Client Settings button is clicked. They can be modified by double
+clicking on the bar.
+
+The parameters are as follows:
+
+Globals
+-------
+
+- Nothing by default. Any globals defined in your schema will show up and
+  can be modified here.
+
+Config
+------
+
+- ``allow_bare_ddl``: Whether DDL is allowed to be used outside the normal
+  migration flow. Default: ``NeverAllow``, can be set to ``AlwaysAllow``.
+  Note: This parameter accepts enum values, not booleans.
+- ``allow_user_specified_id``: Whether users are allowed to manually set the
+  'id' property. Default: ``false``.
+- ``apply_access_policies``: Whether
+  :ref:`access policies <ref_datamodel_access_policies>` will be applied
+  when running queries. Default: ``true``. When set to ``false``, any
+  and all operations can be used on any object in the database.
+- ``force_database_error``: A hook to force all queries to produce an error.
+  Default: ``'false'`` (note: a string ``'false'``, not a boolean). This 
+  parameter takes a ``str`` instead of a ``bool`` to allow more verbose
+  messages. The database will attempt to deserialize this ``str`` into a 
+  JSON object that must include a ``type`` (which must be an EdgeDB error
+  type name), and may also include ``message``, ``hint``, and ``details`` 
+  which can be set ad-hoc by the user. For example, the following is
+  valid input: ``'{ "type": "QueryError", "message": "Did not
+  work", "hint": "Try doing something else", "details": "Indeed, something
+  went really wrong" }'``
+- ``query_execution_timeout``: How long an individual query can run before
+  being aborted. Disabled when set to zero seconds (``<datetime>'PT0S'``),
+  which is the default.
+- ``session_idle_transaction_timeout``: How long client connections can
+  stay active while in a transaction. Disabled when set to zero seconds
+  (``<datetime>'PT0S'``). Default: 10 seconds.
+
+Query Options
+-------------
+
+- Implicit Limit (``int64``): The maximum number of results to display 
+  per query. Default: 100.

docs/ui/data_explorer.rst

@@ -0,0 +1,25 @@
+.. _ref_ui_data_explorer:
+
+=============
+Data Explorer
+=============
+
+.. image:: images/data_explorer.png
+    :alt: The Data Explorer page in the EdgeDB UI. The icon is three bars
+          stacked on top of each other: blue, purple, and orange. A sample
+          query via the Data Explorer shows information about a user-defined
+          object type called a Booking.
+    :width: 100%
+
+The data explorer is similar to the UI editor in facilitating queries on
+database objects, but involves no direct query building (aside from filters,
+which by nature must be specified manually). Instead, the data explorer gives
+point-and-click access to the database's objects, including inserting
+new objects and modifying existing ones.
+
+This makes the data explorer the ideal solution for any users of an EdgeDB
+database who lack a technical background or the time needed to learn
+the ins and outs of a new database. It is also useful for skilled users
+who are looking to explore the links between multiple object types in
+possible multiple levels of depth without having to continually modify a
+query to do so.

docs/ui/database_dashboard.rst

@@ -0,0 +1,22 @@
+.. _ref_ui_dashboard:
+
+=========
+Dashboard
+=========
+
+.. image:: images/database_dashboard.png
+    :alt: The Database Dashboard page in the EdgeDB UI. Large green buttons
+          give access to other pages such as the REPL, Editor, and
+          Schema Viewer. The total number of objects and object types in
+          the database are displayed below, along with links to parts of the
+          EdgeDB website such as the Quickstart, Tutorial, and Easy EdgeDB
+          book.
+    :width: 100%
+
+The dashboard for each database displays the number of object types and
+total number of objects contained within.
+
+Besides this, the dashboard is simply a minimal set of buttons leading to the
+other parts of the UI (the REPL, Editor, Schema Viewer, and Data Viewer)
+and some parts of the EdgeDB documentation that a new user will find
+most useful.

docs/ui/editor.rst

@@ -0,0 +1,47 @@
+.. _ref_ui_editor:
+
+======
+Editor
+======
+
+.. image:: images/editor.png
+    :alt: The Editor page in the EdgeDB UI, inside which the Query Builder
+          is shown as the user puts together a query to see the name property
+          for a user-defined type called Book. A filter on the object's id
+          and a limit to the number of object types returned are being set.
+          The Editor icon is a blue square resembling a pad, with an orange
+          line resembling a pencil on top.
+    :width: 100%
+
+Query Editor
+------------
+
+.. image:: images/editor.png
+    :alt: The Editor tab in the EdgeDB UI Editor page, showing a query
+          appended with the analyze keyword to analyze performance. The
+          performance results show up in a graph on the right, with separate
+          colored rectangles for each link traversed by the query.
+    :width: 100%
+
+The Query Editor is outwardly similar to the REPL besides some
+auto-completion, but is most useful when paired with the ``analyze``
+keyword. Prepending ``analyze`` to the front of any query will
+display a visual query analyzer to help you tweak performance on your
+EdgeQL queries.
+
+Query Builder
+-------------
+
+The Query Builder is by far the easiest way for new users to EdgeDB to
+put together a ``select`` query, and the second easiest part of the UI
+to use after the Data Explorer. The Query Builder is an entirely
+point-and-click interface that walks you through the steps of a ``select``
+query, including selecting properties and links inside an object,
+``filter``, ``order by``, and setting an ``offset`` and ``limit``
+(the maximum number of items to return from a query).
+
+History
+-------
+
+The History button inside the Editor tab pulls up the most recently used
+queries for both the Query Editor and Query Builder.

docs/ui/index.rst

@@ -0,0 +1,59 @@
+.. _ref_ui_overview:
+
+==
+UI
+==
+
+EdgeDB UI is a beautiful, feature-rich admin panel baked directly into all 
+EdgeDB 2.0+ instances.
+
+The UI automatically opens in your default browser on a ``localhost`` page
+via a single command:
+
+.. code-block:: bash
+
+  $ edgedb ui
+
+Alternatively, you can print a url to paste into the browser instead of
+automatically opening the UI:
+
+.. code-block:: bash
+
+  $ edgedb ui --print-url
+
+The UI interface for :ref:`EdgeDB Cloud <ref_cli_edgedb_cloud>` is nearly
+identical to the standard EdgeDB UI, aside from extra pages on cloud-related
+items such as org settings, billing, and usage metrics.
+
+The command to open the EdgeDB UI is a CLI command, documented
+:ref:`here <ref_cli_edgedb_ui>`.
+
+The UI is served by default by development instances. To enable the UI on a
+production instance, use the ``--admin-ui`` option with ``edgedb-server``
+or set the ``EDGEDB_SERVER_ADMIN_UI`` :ref:`environment variable
+<ref_reference_envvar_admin_ui>` to ``enabled``.
+
+The UI has three similar pages that each allow users to query the database:
+the REPL, the Editor, and the Data Explorer.
+
+Outright new users to EdgeDB who need to query or work with objects in a
+database will find the Data Explorer tab the easiest to use, as it allows
+simple point-and-click access to objects without using any EdgeQL. The next
+easiest page to use is the Query Builder inside the Editor tab, which does
+use EdgeQL but is also point-and-click as it walks users through every step
+of a query. The REPL is the most advanced tab in the UI as it requires the
+user to be able to compose queries in EdgeQL.
+
+.. toctree::
+  :maxdepth: 1
+
+  ui_home
+  database_dashboard
+  client_settings
+  ui_repl
+  editor
+  schema_viewer
+  data_explorer
+  auth_admin
+
+`UI souce code <https://github.com/edgedb/edgedb-ui>`_

docs/ui/schema_viewer.rst

@@ -0,0 +1,64 @@
+.. _ref_ui_schema_viewer:
+
+=============
+Schema Viewer
+=============
+
+.. image:: images/schema_viewer.png
+    :alt: The Schema Viewer page in the EdgeDB UI. The icon is two small
+          squares of blue and orange, connected by a purple line. A small
+          user-defined sample schema is shown with two concrete types
+          called Book and Library, along with an abstract type called
+          HasAddress that is extended by the Library type.
+    :width: 100%
+
+The UI schema viewer allows you to see your schema either as text, graph,
+or both.
+
+Text view
+---------
+
+The UI's text view is similar to what is produced in the CLI through the
+``describe schema as sdl`` command, but includes inherited properties and
+links.
+
+The schema viewer shows the user's defined schema by default under the
+name ``User``, and also includes ``Stdlib`` and ``System`` as a convenience.
+Along with the schema viewer's built-in search function, this makes
+the schema viewer often even more convenient than searching through EdgeDB's
+online documentation.
+
+For example, a search for 'max val' immediately shows the following output:
+
+.. code-block:: sdl
+
+    abstract constraint std::max_value(max: anytype) {
+    using ((__subject__ <= max));
+    }  errmessage := 
+        'Maximum allowed value for {__subject__} is {max}.';
+    annotation std::description := 
+        'Specifies the maximum value for the subject.';
+    ;
+
+    abstract constraint std::max_ex_value(max: anytype) {
+    using ((__subject__ < max));
+    }  errmessage := 
+        '{__subject__} must be less than {max}.';
+    annotation std::description := 
+        'Specifies the maximum value (as an open interval) for the subject.';
+    ;
+
+    abstract constraint std::max_len_value(max: std::int64) on (std::len(<std::str>__subject__)) {
+    using ((__subject__ <= max));
+    }  errmessage := 
+        '{__subject__} must be no longer than {max} characters.';
+    annotation std::description := 
+        'Specifies the maximum length of subject string representation.';
+    ;
+
+Graph view
+----------
+
+- Types are shown as boxes with 
+- Links are shown as arrows from one type to another, with any link
+  properties shown tucked inside the arrow.

docs/ui/ui_home.rst

@@ -0,0 +1,64 @@
+.. _ref_ui_schema_viewer:
+
+=============
+Schema Viewer
+=============
+
+.. image:: images/schema_viewer.png
+    :alt: The Schema Viewer page in the EdgeDB UI. The icon is two small
+          squares of blue and orange, connected by a purple line. A small
+          user-defined sample schema is shown with two concrete types
+          called Book and Library, along with an abstract type called
+          HasAddress that is extended by the Library type.
+    :width: 100%
+
+The UI schema viewer allows you to see your schema either as text, graph,
+or both.
+
+Text view
+---------
+
+The UI's text view is similar to what is produced in the CLI through the
+``describe schema as sdl`` command, but includes inherited properties and
+links.
+
+The schema viewer shows the user's defined schema by default under the
+name ``User``, and also includes ``Stdlib`` and ``System`` as a convenience.
+Along with the schema viewer's built-in search function, this makes
+the schema viewer often even more convenient than searching through EdgeDB's
+online documentation.
+
+For example, a search for 'max val' immediately shows the following output:
+
+.. code-block:: sdl
+
+    abstract constraint std::max_value(max: anytype) {
+    using ((__subject__ <= max));
+    }  errmessage := 
+        'Maximum allowed value for {__subject__} is {max}.';
+    annotation std::description := 
+        'Specifies the maximum value for the subject.';
+    ;
+
+    abstract constraint std::max_ex_value(max: anytype) {
+    using ((__subject__ < max));
+    }  errmessage := 
+        '{__subject__} must be less than {max}.';
+    annotation std::description := 
+        'Specifies the maximum value (as an open interval) for the subject.';
+    ;
+
+    abstract constraint std::max_len_value(max: std::int64) on (std::len(<std::str>__subject__)) {
+    using ((__subject__ <= max));
+    }  errmessage := 
+        '{__subject__} must be no longer than {max} characters.';
+    annotation std::description := 
+        'Specifies the maximum length of subject string representation.';
+    ;
+
+Graph view
+----------
+
+- Types are shown as boxes with 
+- Links are shown as arrows from one type to another, with any link
+  properties shown tucked inside the arrow.