When there are no definitions open the URL shouldn't include the identifiers of a definition. This works when using the "x" keybind to close open definitions, but does not work when clicking the x icon.

But it's also weirdly missing the FQN info. What namespace is iterate in?

Using the toggle icons the user should be able to expand and close a definition.

Using the spacebar key should toggle the zoom level.

In Firefox, the alignment of the name with the left side icons of off:

Guessing this is firefox only? I'm on 89.0 for Ubuntu.

Moving up and down the workspace with arrow keys and j/k has stopped working for some reason. X still works fine to close open definitions.

When requesting data constructors they come back as a missingDefinition.

Here's base.Map.Map:

{ 
  "termDefinitions": {},
  "typeDefinitions": {}, 
  "missingDefinitions": [ 
"#7di5ureqgi60ue42886240kbovfhko0fg85rp2thpkl8af699upsl0os1btk27te1cjdmuerad5oi9bdd04me6mjh2m25djbj236fbo#d0" 
  ] 
}

The frontend should request either by name base.Map.Map (which the backend will return the type base.Map for) or for right now; request by the hash of the data construct with the last segment removed. A data constructor hash has this format: #abc#d0 where the #abc part is the hash of the type and the #d0 part is a reference to the position of the constructor.

Previous discussion here: unisonweb/unison#1876

Clicking "Help & Keybindings" in the bottom of the sidebar should show a modal that gives instructions of all the keybindings that currently exists.

This is not meant to replace inline keybinding instructions, but to act as another way to learn about them.

The keybind ? should also show this.

Unison Share should give instructions on how a project can be downloaded and used in ucm.

Design

Users can select and copy from this input field, the .> will not be selectable. The button copies in the same fashion.
The question mark gives a short description of ucm.

When share.unison-lang.org is shared (no pun intended) in things like slack and on twitter, we should show the Unison logo and a small description

All but the first of the links in the bottom left of the codebase UI are broken, because the path gets stripped during the redirect from unison-lang.org to unisonweb.org, so you end up on the unison homepage for all of them (or at least, you do on firefox 89.0 for ubuntu).

Using the toggle icons the user should be able to expand and close the source of a definition.

This should support cycling through the zoom levels of a definition with "spacebar".

Open questions:

How do we best separate signature and full source? Right now we get back 2 fields:

• signature: The signature of a term.
• definition: The full definition of a term including it's signature.

These are pre-rendered into syntax, so separating the signature and the function body from the definition could perhaps be done more easily on the backend.

Notes

This feature makes more sense when docs are rendered.

With a successful merge to the main branch, a production release should be cut with 2 separate targets: hub (public hosted codebase server and ui) and ucm.

Related: unisonweb/unison#1880

When using Firefox the "/" sometimes (randomly; not always) brings up the Firefox Quick Find window instead of the app's Finder.

Other commands like Cmd+k, Firefox uses to focus the address bar. If on mac the user can use Ctrl+k instead of Cmd+k, but it's likely that Ctrl+k replaces Cmd+k for address bar focus on Linux and Windows.

See screenshot for an example.

Perhaps we should truncate the text better and allow a hover to show the full name (it'd be nice if a hover showed signatures too).

The width of name column in the Finder is sometimes not right and clips the names when it shouldn't:

(in this example the Nonempty.flatMap entry)

So if you start typing, then hit down arrow, then up arrow, then continue typing, your characters get inserted at the start of the line. Up and down arrow should have no effect on cursor position I'd say - the user can use home/end to move to the start or end of the line, or left/right arrow keys.

We want to support URL schemes like so:

/[latest|:namespace-hash]/[namespaces|types|terms]/[:definition-name|:definition-hash]

When we have a namespace hash (either for the top level codebase or for a sub namespace), any term or type name in the url will be relative to that and does not need to be identified by hash unless that definition sits outside of the enclosing RelativeTo namespace.

Aside: Unison hashes in URLs use @ instead of # to conform to the URL specification.

Relative URL example

A relative URL refers to URLs that point to the latest version of codebase or definition. It's addressing by name instead of by hash.

Relative URLs will be turned into absolutes as soon as the page loads by exchanging latest for the latest hash of the codebase. We want to encourage absolute linking over relative, but support relative for things like a project website linking to the latest of a codebase.

• Toplevel of a Codebase: /latest
• Workspace namespace: /latest/namespaces/base/List
• Definitions: /latest/[types|terms]/base/List
• Ambiguous definitions:/latest/[types|terms]/base/List@je2wR6

Absolute URL examples

Absolute URLs link directly to the version of a codebase or definition by using hashes.

• Workspace namespace: /@785shikvuihsdfd
• Definitions:/@785shikvuihsdfd/[types|terms]/base/List
• Ambiguous definitions:/@785shikvuihsdfd/[types|terms]/Nonempty/map@dkqA42
• Definitions outside of workspace:/@785shikvuihsdfd/[types|terms]/@jf615sgdkvuihskrt
• Definitions outside of workspace:/latest/[types|terms]/@jf615sgdkvuihskrt—Only supported URL currently

Absolute URL notes

• @785shikvuihsdfd refers to a specific namespace hash in the codebase. In this case base.List , but could also be the hash of the top level codebase. @jf615sgdkvuihskrt refers to a definition outside of base.List
• With this it is not possible to relatively link to a definition in where the workspace is also set relatively. The user would instead link with an absolute workspace: /@785shikvuihsdfd/[types|terms]/Nonempty

Implications

• This feature requires a way to exchange a namespace name or "latest" to a hash.
• The frontend will make a request to the server when it is first initiated with a relative URL to exchange it for a hash and rewrite the URL.
• This feature allows nice URLs on Unison Share, allowing users to see what they are being linked before clicking through

Additional reading: https://github.com/unisonweb/codebase-ui/blob/main/docs/design/relative-to-changing-fetching-by-name-vs-hash-indexing-and-urls.md

To make serving the ui simpler with regards to supporting the pushState routing, put all assets (images, fonts, css etc) in an assets subfolder that can be targeted by the server (since all other routes regardless of depth should render index.html for pushState support).

With no open definitions the UI should show an Empty State that instructs how to open the finder and use the sidebar to open and view definitions.

When rendering types and namespace in the sidebar codebase tree sort them such that the type Either is adjacent to the namespace Either, strengthening the connection between the 2 concepts.

http://localhost:1234/latest/terms/@@Bytes.toList results in

Cannot GET /latest/terms/@@Bytes.toList

Trying to load a definition from a URL like so http://localhost:1234/latest/types/@onbcm0qctbnuctpm57tkc5p16b8gfke8thjf19p4r4laokji0b606rd0frnhj103qb90lve3fohkoc1eda70491hot656s1m6kk3cn0 results in load definition fetched.

It is likely routing related, meaning that routes are created correctly, but seemlingly incorrect matched. Likely connect with the <base> tag and the basePath being passed in from the JS world.

When using the Finder in larger codebases, the lack of feedback when searching for a couple of seconds isn't great. We should indicate to the user that something is happening.

We're quickly outgrowing the simple css file and should move to something like elm-css.

We want to make sure we keep theming support.

A good time to take this on is for dark mode support.

This happens in Firefox only:

Fira Mono/Fira Code will allow users to enable ligatures if they'd like to

When the Finder shows an error or the sidebar shows a loading error or even the workspace definition, it's quite crude. Even though getting errors should be rare, they are highly disruptive and good UX in this area has a big impact.

Render docs (format2 only) for open definitions

• Render the doc AST
• Style docs
• Support state changes like fold/unfold.
• Parse doc JSON
• Fine-tune rendering

We should explore a better loading animation for the Finder, as it is too subtle and appear as if nothing is happening when data is being fetched.

I move my mouse pointer around the finder results, and it flips between a little hand (that tells me it's something I can click to go somewhere) and an arrow (which suggests I needn't bother).

Actually everywhere is clickable, which is good.

But having the zones that show the arrow are distracting.

Those zones seem to be name of the definition, and any accompanying 'in base' (or wherever) note.

This is firefox 89.0 on ubuntu.

Ubuntu doesn't seem to want to include the mouse pointer in screenshots. I've shaded the areas below in one of the results, that have the arrow.

With a type open like Either, the constructors Left and Right should be clickable.

Right now they are modelled as Constructor String, we should expand that to be Constructor String Hash. (Alternatively we could use TermReference, but we'd loose the ability to target constructors for syntax highlighting).

I open finder, type something to get some results showing, and try and work out how to use the 'semicolon plus number' selection system. After one false start (lifting the semicolon key too soon) I realize I probably need to hold down the semicolon key as if it were a key like shift.

I try holding down semicolon and I see all the semicolon keys in the finder UI change color to encourage me (great, nice touch!)

But after a couple of seconds holding it down, the color of those semicolons starts to flicker very fast in an unsightly way.

Firefox 89.0 on ubuntu.

When scrolling down through definitions in the main codebase UI pane using the down arrow (or j), the pane scrolls too soon.

Scroll up through the definitions, initially the pane stays still, until you get to the top term on the screen being highlighted. Only then does the pane scroll (so a new definition appearing at the top, and some disappearing off the bottom). That's good and what I feel used to.

But scrolling down, that first phase is absent: it's immediately scrolling the pane (pulling in new definitions at the bottom, scrolling some off the top), even with the highlighted term still the top one on the screen. Feels surprising.

Firefox 89.0 on ubuntu.

We should debounce the Finder query such that we only request the server after a short lull in typing. This problem is especially bad on Unison Share where many users will be querying at the same time and the server will be hit hard.

For some reason, examples.elems and input.lower in this screenshot show without a namespace. They most certainly have one.

Design

The sidebar should support collapsing on smaller screens and should adjust its width on larger screens and correctly clip items (as opposed to wrap or downscale icons #147 )

Restarting the dev server fixes this issue, but this is quite annoying to have to do constantly.

For some reason when clicking a type from a term source it gets a term reference instead of a type reference and thus a wrong url and making it possible for a type to appear twice in the list.

Steps:

(namespaces are examples, this is a problem for all):

1. Expand base
2. Expand Boolean
3. Close base
4. Open base

Notice Boolean is rendered as if it is expanded, but showing no data.

Hi, I'm having some trouble getting started.

The README.md says:

Start ucm and copy the API URL and API Token (this URL is uniquely generated by ucm at start-up) from the ucm start-up output (It's formatted as a single URL with a query string. Get the token by from the query string).

Then start the development server, run:

    API_URL="<API URL FROM UCM>" API_TOKEN="<API TOKEN FROM UCM>" npm start

Then visit http://localhost:8000 to use the UI.

So:

arya@jrrr unison-trunk % stack exec unison

  I've started a codebase API server at 


  http://127.0.0.1:55484?X%2FkGfCrT2RUerJpU0x6bibwQsA0410dv

I'm guessing everything before the ? is the URL and everything after it is the TOKEN? But I'm not too confident.

arya@jrrr codebase-ui % API_URL="http://127.0.0.1:55484" API_TOKEN="X%2FkGfCrT2RUerJpU0x6bibwQsA0410dv" npm start

> [email protected] start
> npm run makeElmEnv; elm-live src/Main.elm --path-to-elm=node_modules/.bin/elm --dir=public --pushstate --verbose --proxy-prefix=/api --proxy-host=${API_URL} -- --output public/bundle.js


> [email protected] makeElmEnv
> node ./scripts/makeElmEnv.mjs

sh: elm-live: command not found
npm notice 
npm notice New minor version of npm available! 7.0.14 -> 7.6.0
npm notice Changelog: https://github.com/npm/cli/releases/tag/v7.6.0
npm notice Run npm install -g [email protected] to update!
npm notice 
npm ERR! code 127
npm ERR! path /Users/arya/codebase-ui
npm ERR! command failed
npm ERR! command sh -c npm run makeElmEnv; elm-live src/Main.elm --path-to-elm=node_modules/.bin/elm --dir=public --pushstate --verbose --proxy-prefix=/api --proxy-host=${API_URL} -- --output public/bundle.js

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/arya/.npm/_logs/2021-03-03T23_07_22_508Z-debug.log
arya@jrrr codebase-ui % 

I guess I need to install something Elm-related? But it would be great if the specifics could be added to the README when you have a chance.

Thanks in advance!

The sidebar should look like the design (disregarding the help & keybindings section, handled by: #80)