Module views 

Views: the mechanism behind an app’s designed views and its search.

A view is a query over the app’s resources plus a layout. The app’s designed views (a library, a page per album) are crafted and fixed; this module is what they stand on, never something people configure:

• Resource types (KindDecl): each type’s fields, the role a field plays where an item is shown (FieldRole), which fields typed text finds and which narrow by a chip (FilterKind), and how its items are presented in a list of results (Form). Every place an item appears renders through the app’s presentation of its type, so a search result is the same song as in the library.
• A view stack per window (ViewStack): back and forward always work, and returning to a view restores where the person was in it (ViewPlace).
• Search is a view. Typing into the window bar’s search field turns the window’s view into a query view of the app’s resources (QuerySpec): results grouped by type, chips under the field from the filterable fields (facet_offers, facet_bar), typed tokens (artist:ada) mapped onto the same chips, and the app’s actions that match in a trailing “In this app” group as their real controls (action_hits, actions_group). Escape or Back returns to the view before, exactly.
• The query (QueryEngine): local items answered from an index in the frame of the keystroke; remote sources (RemoteSource) streamed into their own sections below, with cancellation, a cache by query, reuse of an earlier answer while a refined query is on the way, and rows that never move under the person’s pointer or keyboard. An app whose search already has entries hands those over (Item::from_entry): one search model feeds the platform search and the app’s query view, and a match inside an entry’s prose is a hit at its passage.
• Keeping (KeptViews): any query view can be kept, and then sits beside the designed views as the person’s own.

Structs

ActionHit

An action that matches a query, as the control it is.

Cancel

Asked by a running request whether it should stop: a newer query took its place.

Chip

One chip: the filterable field it narrows by, and the value for a value chip (none for a toggle that is on).

ControlDecl

FacetMenu

The values of one value filter, opened over its chip: each with how many results share it and a check on those chosen, since any number may be. Choosing one toggles it in the query; the menu closes, and opening it again chooses another. An app that paints its own surface owns one, draws it over its page and routes events to it while it is open.

FacetOffer

The chip of one filterable field.

FacetValue

One value a value filter offers.

FieldDecl

One field of a resource type.

Item

One item of a resource type, as search and views read it: its type, its id, and its fields by key. A field may hold several values (a song by two artists). A remote source attaches what it fetched (payload), so the app can make the item playable or openable before anything is stored.

KeptView

One kept query view.

KeptViews

The query views a person kept in one app, oldest first.

KindDecl

One resource type of an app: what its items are called, how they are presented in results, and their fields.

QueryEngine

The query of one query view: its local index, its remote sources, and what it has found so far.

QueryResults

What a query has found so far.

QuerySpec

What a query view asks for.

QueryTimings

How long a query took to show its results, from the moment it was set.

RemoteError

Why a remote source could not answer, as its section says it.

RemoteSection

What one remote source has found for the query.

ResultGroup

The items of one type in a list of results, best first.

ViewEntry

A view the stack holds and where the person was in it.

ViewPlace

Where a person was in a view: what a return to it restores.

ViewStack

The views of one window: the one shown, the ones Back returns to and the ones Forward goes on to.

Enums

ControlKind

How an action looks as a control.

FieldRole

The part a field plays where an item of its type is shown.

FilterKind

How a filterable field narrows results, which decides the chip it gets.

Form

How a type’s items are presented in a list of results.

Constants

FRESH

How long a remote answer is shown from the cache without asking again.

GROUP_LIMIT

How many items one group of results shows.

THROTTLE

The least time between two requests to one remote source while the person types. A query typed within it goes out when it has passed.

Traits

LocalSource

An index of the app’s own that answers with the local items, in the same frame: matches in what this device does not hold yet, such as a library’s synced index of books whose text is elsewhere. It answers on the UI thread, so within the frame’s budget.

RemoteSource

A source of items that are not local: a streaming catalogue, a store, a collaborator’s library. It keeps its own index; nothing of it is downloaded to be searched.

Functions

action_control

The control hit is, bound to its action through actions; an action the resource no longer publishes shows disabled.

action_hits

The actions of specs that match query, best first, at most limit: each as its declaration in controls says, a button where none does. Only actions a control can run are listed: those asking for nothing more, and those whose declared control asks for it.

actions_group

The trailing “In this app” group of a query view: its heading, then each hit as its real control, with a button that takes the person to where the control lives (show, given the control’s home) for those that have one. heading and show_label are the app’s words for them.

excerpt

The part of passage around the first word of query it holds, the match in its middle, cut at word boundaries and marked where it was cut: what a hit inside prose shows of it.

facet_bar

The chips as a row: a toggle flips, a value filter’s chip opens its values (open), and an active chip’s clear control hands on_change the query without its choice.

facet_offers

The chips for query and what it found: one per filterable field of kinds, in declaration order, each value counted among results.

filters

The filterable fields of kinds, each key once, in declaration order: the chips a query view offers.

Type Aliases

OpenFacet

What a press on a chip asks of the app: a value filter’s chip opens its list of values, the app showing it where it suits (key).