@mosaicajs/components 0.2.0 → 0.4.0

package/README.md

@@ -18,4 +18,6 @@ document.body.append(explorer);
 
 Each element has its own subpath, such as `@mosaicajs/components/map`. A page with no build step can load `dist/mosaica-components.js` instead: every element and its dependencies in one ES module, with its `sha384` integrity hash in `dist/mosaica-components.js.sri` and the notices of the third-party code inside it in `dist/mosaica-components.js.LICENSE.txt`.
 
+Give each map an `aria-label`, and set `lang` on your page. [Accessibility](https://github.com/mosaicadb/mosaica/blob/main/docs/system/accessibility.md) lists the keys the elements take, what a screen reader is told and what is not built yet.
+
 Documentation: [Components reference](https://github.com/mosaicadb/mosaica/blob/main/docs/reference/components.md). Licence: Apache-2.0.

package/dist/aggregate.d.ts

@@ -25,18 +25,12 @@ export declare function countsByKey(entry: AggregateEntry | undefined): Map<stri
 export declare function countedByLevel(layer: Pick<Layer, 'levels'>): boolean;
 /** Whether `layer` is a tree, `nested` or `dag`, whose clusters are ranked at the cut the map draws. */
 export declare function isTree(layer: Pick<Layer, 'hierarchy'>): boolean;
-/**
- * The level of a `stacked` or `tiered` layer that is counted and coloured: `chosen` where the layer
- * declares it, else its top (coarsest) level among those `served` at the camera's zoom, as the
- * map draws it. `undefined` on a layer with no levels to choose.
- */
-export declare function levelOf(layer: Pick<Layer, 'name' | 'hierarchy' | 'levels'>, chosen: number | null, served?: readonly {
-    layer: string;
-    rung: number;
-}[]): number | undefined;
+/** Whether `layer` declares parent edges, `tiered`, `nested` or `dag`, so its artifacts can be walked by their parents and children. */
+export declare function isLinked(layer: Pick<Layer, 'hierarchy'>): boolean;
 /**
  * The grouping ranking a layer's `top` clusters: at the cut the map draws on a tree, else at
- * {@link levelOf} `level`. Each row carries its slot in the palette the map colours clusters from.
+ * `level`, the level already worked out for the layer (`levelOfLayer`), or at no level where it is
+ * `null`. Each row carries its slot in the palette the map colours clusters from.
  */
 export declare function rankedGrouping(layer: Pick<Layer, 'name' | 'hierarchy' | 'levels'>, top: number, level: number | null): AggregateSpecGrouping;
 /**

package/dist/aggregate.js

@@ -1,4 +1,4 @@
-import { jsonBody, topLevelServed } from '@mosaicajs/client/internal';
+import { jsonBody } from '@mosaicajs/client/internal';
 /**
  * The listed groups of `table`, in the server's order: largest count first for a `top` grouping,
  * the order named otherwise. The `rest` and `none` rows are left out.
@@ -49,25 +49,19 @@ export function countedByLevel(layer) {
 export function isTree(layer) {
     return layer.hierarchy.kind === 'nested' || layer.hierarchy.kind === 'dag';
 }
-/**
- * The level of a `stacked` or `tiered` layer that is counted and coloured: `chosen` where the layer
- * declares it, else its top (coarsest) level among those `served` at the camera's zoom, as the
- * map draws it. `undefined` on a layer with no levels to choose.
- */
-export function levelOf(layer, chosen, served = []) {
-    if ((layer.hierarchy.kind !== 'stacked' && layer.hierarchy.kind !== 'tiered') || layer.levels.length === 0)
-        return undefined;
-    return chosen !== null && layer.levels.some((l) => l.level === chosen) ? chosen : topLevelServed(layer, served);
+/** Whether `layer` declares parent edges, `tiered`, `nested` or `dag`, so its artifacts can be walked by their parents and children. */
+export function isLinked(layer) {
+    return layer.hierarchy.kind === 'tiered' || isTree(layer);
 }
 /**
  * The grouping ranking a layer's `top` clusters: at the cut the map draws on a tree, else at
- * {@link levelOf} `level`. Each row carries its slot in the palette the map colours clusters from.
+ * `level`, the level already worked out for the layer (`levelOfLayer`), or at no level where it is
+ * `null`. Each row carries its slot in the palette the map colours clusters from.
  */
 export function rankedGrouping(layer, top, level) {
     if (isTree(layer))
         return { count: true, by: { layer: layer.name, top, cut: 'drawn', paletteSize: 'drawn' } };
-    const at = levelOf(layer, level);
-    return { count: true, by: { layer: layer.name, ...(at === undefined || !countedByLevel(layer) ? {} : { level: at }), top, paletteSize: 'drawn' } };
+    return { count: true, by: { layer: layer.name, ...(level === null || !countedByLevel(layer) ? {} : { level }), top, paletteSize: 'drawn' } };
 }
 /**
  * The groupings that count `artifacts` of `layer` by name: one per level where the route addresses

package/dist/artifact-card.d.ts

@@ -6,7 +6,7 @@ import './count.js';
  * Use the artifact card to show an artifact the viewer has opened on the map, such as a cluster. An
  * artifact is a named group of items in an annotation layer. The card's count covers every member
  * the viewer may see, so it does not change as the map moves. Pressing one of the artifact's
- * parents or children opens that one instead.
+ * parents or children opens that one instead, and moves focus to its name.
  *
  * The card reads the store's opened artifact, or the `artifact` you set.
  *
@@ -25,22 +25,22 @@ import './count.js';
  *   or highlight button added or removed a `member_of` clause.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - The close button was
  *   pressed, with `what` set to `artifact`.
- * @csspart title - The heading, with the level's or layer's title and the close button.
+ * @csspart title - The heading: the level's or layer's title.
  * @csspart close - The close button.
- * @csspart state - The state line, with `data-state`.
+ * @csspart state - The state line, with `data-state`, inside a `role="status"` region.
  * @csspart refusal - The words "Not available", with `data-code` set to the refusal's code.
  * @csspart reason - The server's reason for the refusal, under "Not available".
- * @csspart headline - The artifact's name, with `data-unnamed` if it has none.
+ * @csspart headline - The artifact's name, an `<h3>`, with `data-unnamed` if it has none.
  * @csspart count - The count of items the viewer may see.
  * @csspart content - The artifact's description, or its attached topic.
  * @csspart value - The layer and the key.
  * @csspart shape - How the layer's shapes are made, with `data-kind` (`derived`, `predicate` or
  *   `authored`).
- * @csspart label - The headings above the parents and the children.
+ * @csspart label - The headings above the parents and the children, each an `<h3>`.
  * @csspart parents - The list of parents.
- * @csspart parent - One parent, with `data-id`.
+ * @csspart parent - One parent, a button, with `data-id`.
  * @csspart children - The list of children in this view.
- * @csspart child - One child, with `data-id`.
+ * @csspart child - One child, a button, with `data-id`.
  * @csspart name - A parent's or child's name, with `data-unnamed` if it has none.
  * @csspart fit - The Fit to cluster button.
  * @csspart verbs - The clause buttons.
@@ -65,7 +65,21 @@ export declare class MosaicaArtifactCard extends MosaicaElement {
      * Outside this replace each other, and a highlight is kept beside either.
      */
     private verb;
+    /** The parent or child pressed, its button, and the artifact it was pressed on, until the card shows another. */
+    private opening;
+    /** Open a parent or child in the card's place. */
+    private openRow;
+    /**
+     * Once the card shows the parent or child that was pressed, focus goes to its name, since the
+     * row that had it is gone; where it was refused, to the close button. Focus that has gone
+     * anywhere else meanwhile stays there.
+     */
+    protected updated(): void;
+    /** The parents or the children, each a button that opens it, under a heading that names the list. */
+    private rows;
     render(): TemplateResult | typeof nothing;
+    /** What the card shows of an artifact, under its heading. */
+    private body;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/artifact-card.js

@@ -35,7 +35,7 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
 import { css, html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { artifactName, isFilterLayer, withMember, withoutMember } from '@mosaicajs/client';
-import { MosaicaElement, UNNAMED, emit, idString } from './base.js';
+import { MosaicaElement, UNNAMED, emit, focusLost, idString } from './base.js';
 import { attachContextRoot, defineOnce } from './define.js';
 import { icon } from './icons.js';
 import { reasonOf, refusedState, renderState } from './states.js';
@@ -43,13 +43,6 @@ import { chrome, tokens } from './tokens.js';
 import './count.js';
 /** A parent's or child's name, or {@link UNNAMED}. */
 const nameSpan = (name) => html `<span part="name" class="name" ?data-unnamed=${name === null}>${name ?? UNNAMED}</span>`;
-/** A `role="button"` row's keys: Enter and Space press it. */
-const onKeys = (press) => (e) => {
-    if (e.key !== 'Enter' && e.key !== ' ')
-        return;
-    e.preventDefault();
-    press();
-};
 /** What each kind of drawn shape says on the card. */
 const SHAPE_TEXT = {
     derived: 'Drawn around the members you can see',
@@ -60,7 +53,7 @@ const SHAPE_TEXT = {
  * Use the artifact card to show an artifact the viewer has opened on the map, such as a cluster. An
  * artifact is a named group of items in an annotation layer. The card's count covers every member
  * the viewer may see, so it does not change as the map moves. Pressing one of the artifact's
- * parents or children opens that one instead.
+ * parents or children opens that one instead, and moves focus to its name.
  *
  * The card reads the store's opened artifact, or the `artifact` you set.
  *
@@ -79,22 +72,22 @@ const SHAPE_TEXT = {
  *   or highlight button added or removed a `member_of` clause.
  * @fires {CustomEvent<MosaicaEventDetails['mosaica-close']>} mosaica-close - The close button was
  *   pressed, with `what` set to `artifact`.
- * @csspart title - The heading, with the level's or layer's title and the close button.
+ * @csspart title - The heading: the level's or layer's title.
  * @csspart close - The close button.
- * @csspart state - The state line, with `data-state`.
+ * @csspart state - The state line, with `data-state`, inside a `role="status"` region.
  * @csspart refusal - The words "Not available", with `data-code` set to the refusal's code.
  * @csspart reason - The server's reason for the refusal, under "Not available".
- * @csspart headline - The artifact's name, with `data-unnamed` if it has none.
+ * @csspart headline - The artifact's name, an `<h3>`, with `data-unnamed` if it has none.
  * @csspart count - The count of items the viewer may see.
  * @csspart content - The artifact's description, or its attached topic.
  * @csspart value - The layer and the key.
  * @csspart shape - How the layer's shapes are made, with `data-kind` (`derived`, `predicate` or
  *   `authored`).
- * @csspart label - The headings above the parents and the children.
+ * @csspart label - The headings above the parents and the children, each an `<h3>`.
  * @csspart parents - The list of parents.
- * @csspart parent - One parent, with `data-id`.
+ * @csspart parent - One parent, a button, with `data-id`.
  * @csspart children - The list of children in this view.
- * @csspart child - One child, with `data-id`.
+ * @csspart child - One child, a button, with `data-id`.
  * @csspart name - A parent's or child's name, with `data-unnamed` if it has none.
  * @csspart fit - The Fit to cluster button.
  * @csspart verbs - The clause buttons.
@@ -126,12 +119,27 @@ let MosaicaArtifactCard = (() => {
       :host {
         display: block;
       }
-      [part='title'] .what {
+      .head {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        margin: 0 0 10px;
+      }
+      [part='title'] {
         flex: 1;
         min-width: 0;
+        margin: 0;
       }
-      [part='headline'] {
-        margin-bottom: 6px;
+      h3[part='headline'] {
+        display: block;
+        margin: 0 0 6px;
+        letter-spacing: 0;
+        text-transform: none;
+        color: var(--_mosaica-ink);
+      }
+      /* The name takes focus when the card opens a parent or child in its place; it is no control, so it shows no ring. */
+      [part='headline']:focus {
+        outline: none;
       }
       [part='count'] {
         display: flex;
@@ -151,16 +159,49 @@ let MosaicaArtifactCard = (() => {
         font-size: 12px;
         color: var(--_mosaica-ink-2);
       }
-      .children-label {
+      dl,
+      dd {
+        margin: 0;
+      }
+      h3[part='label'] {
+        display: block;
         margin: 12px 0 4px;
+        font-weight: 400;
+        letter-spacing: 0;
+        text-transform: none;
       }
+      [part='parents'],
       [part='children'] {
         list-style: none;
         margin: 0;
         padding: 0;
       }
+      /* A parent or child: its name on one line, and its count at the right. */
+      [part='parent'],
+      [part='child'] {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        width: 100%;
+        min-height: 30px;
+        padding: 0 6px 0 22px;
+        border-radius: var(--_mosaica-radius-control);
+        text-align: left;
+      }
+      [part='parent']:hover,
+      [part='child']:hover {
+        background: var(--_mosaica-surface-2);
+      }
+      [part='name'] {
+        flex: 1 1 0;
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: var(--_mosaica-long-text);
+        overflow-wrap: anywhere;
+      }
+      [part='parent'] mosaica-count::part(count),
       [part='child'] mosaica-count::part(count) {
-        margin-left: auto;
         color: var(--_mosaica-ink-2);
         font-size: 12px;
         font-weight: 400;
@@ -177,26 +218,14 @@ let MosaicaArtifactCard = (() => {
       [part='verbs'] .btn[aria-pressed='true'] {
         border-color: currentColor;
         background: var(--_mosaica-surface-2);
+        box-shadow: inset 0 -2px 0 currentColor;
       }
       [part='verbs'] [data-verb='highlight'][aria-pressed='true'] {
         background: var(--_mosaica-highlight-soft);
         color: var(--_mosaica-highlight);
       }
-      .parents-label {
-        margin: 12px 0 4px;
-      }
-      [part='parents'] {
-        list-style: none;
-        margin: 0;
-        padding: 0;
-      }
-      [part='parent'] mosaica-count::part(count) {
-        margin-left: auto;
-        color: var(--_mosaica-ink-2);
-        font-size: 12px;
-        font-weight: 400;
-      }
       [part='close'] {
+        flex: none;
         width: 24px;
         height: 24px;
         margin: -4px -4px -4px 0;
@@ -258,6 +287,46 @@ let MosaicaArtifactCard = (() => {
     >
       ${icon(outside ? 'outside' : verb === 'filter' ? 'filter' : 'highlight', 14)}${label}
     </button>`;
+        }
+        /** The parent or child pressed, its button, and the artifact it was pressed on, until the card shows another. */
+        opening = (__runInitializers(this, _refusal_extraInitializers), null);
+        /** Open a parent or child in the card's place. */
+        openRow(id, button) {
+            this.opening = { id, from: this.shown.artifact?.id ?? null, button };
+            void this.resolvedStore?.openArtifact(id);
+        }
+        /**
+         * Once the card shows the parent or child that was pressed, focus goes to its name, since the
+         * row that had it is gone; where it was refused, to the close button. Focus that has gone
+         * anywhere else meanwhile stays there.
+         */
+        updated() {
+            const opening = this.opening;
+            if (!opening)
+                return;
+            const { artifact, refusal } = this.shown;
+            if (!refusal && artifact?.id === opening.from)
+                return;
+            this.opening = null;
+            if (this.shadowRoot?.activeElement !== opening.button && !(focusLost() && !opening.button.isConnected))
+                return;
+            if (refusal)
+                this.renderRoot.querySelector('[part="close"]')?.focus();
+            else if (artifact?.id === opening.id)
+                this.renderRoot.querySelector('[part="headline"]')?.focus();
+        }
+        /** The parents or the children, each a button that opens it, under a heading that names the list. */
+        rows(children, rows, attached, stale) {
+            if (rows.length === 0)
+                return nothing;
+            const id = children ? 'children' : 'parents';
+            return html `<h3 part="label" class="xs muted" id=${id}>${children ? 'Children in this view' : 'Parents'}</h3>
+      <ul part=${children ? 'children' : 'parents'} aria-labelledby=${id}>
+        ${rows.map((a) => html `<li><button part=${children ? 'child' : 'parent'} type="button" data-id=${idString(a.mosaicaId)} @click=${(e) => this.openRow(a.mosaicaId, e.currentTarget)}>
+            ${nameSpan(artifactName(a, attached))}
+            <mosaica-count .masked=${{ value: Number(a.maskedCount), exact: true }} .stale=${stale}></mosaica-count>
+          </button></li>`)}
+      </ul>`;
         }
         render() {
             const { artifact, refusal } = this.shown;
@@ -269,29 +338,40 @@ let MosaicaArtifactCard = (() => {
             const declaredLayer = row?.layer ?? artifact?.detail.layer;
             const decl = declaredLayer === undefined ? undefined : metaLayers.find((l) => l.name === declaredLayer);
             const what = (row && decl?.levels.find((lv) => lv.level === row.rung)?.title) || decl?.title || decl?.name || 'Selected';
-            // The close button appears only while the card shows something to close.
-            const heading = (closable) => html `<h2 part="title"><span class="what">${what}</span>${closable
+            const state = refusal
+                ? refusedState('Not available', refusal.code, null, reasonOf(refusal))
+                : artifact
+                    ? html `<span part="state" data-state="shown"></span>`
+                    : this.resolvedStore
+                        ? html `<span part="state" data-state="empty">Nothing selected</span>`
+                        : renderState('detached', null);
+            // One template whatever the card shows, so the state's region is in the page before its words
+            // change. The close button appears only while the card shows something to close.
+            return html `<div class="panel">
+      <div class="head">
+        <h2 part="title">${what}</h2>
+        ${refusal || artifact
                 ? html `<slot name="actions"></slot><button part="close" type="button" aria-label="Close" @click=${() => emit(this, 'mosaica-close', { what: 'artifact' })}>${icon('close', 14)}</button>`
-                : nothing}</h2>`;
-            if (refusal) {
-                return html `<div class="panel">${heading(true)}${refusedState('Not available', refusal.code, null, reasonOf(refusal))}</div>`;
-            }
-            if (!artifact) {
-                if (!this.resolvedStore)
-                    return html `<div class="panel">${heading(false)}${renderState('detached', null)}</div>`;
-                return html `<div class="panel">${heading(false)}<span part="state" data-state="empty">Nothing selected</span></div>`;
-            }
+                : nothing}
+      </div>
+      <div role="status">${state}</div>
+      ${artifact && !refusal ? this.body(artifact, decl) : nothing}
+    </div>`;
+        }
+        /** What the card shows of an artifact, under its heading. */
+        body(artifact, decl) {
             const s = this.resolvedStore;
             const artifacts = s?.get('artifacts');
             const served = artifacts?.served ?? [];
             const attached = artifacts?.attached ?? new Map();
+            const bySize = (a, b) => (a.maskedCount < b.maskedCount ? 1 : a.maskedCount > b.maskedCount ? -1 : 0);
             // The artifact's row and children are read from the served set now, on every render.
             const here = served.find((a) => a.mosaicaId === artifact.id);
             // On a `dag` layer a child appears on the card of each served parent.
-            const children = served.filter((a) => a.parentIds.includes(artifact.id)).sort((a, b) => (a.maskedCount < b.maskedCount ? 1 : a.maskedCount > b.maskedCount ? -1 : 0));
+            const children = served.filter((a) => a.parentIds.includes(artifact.id)).sort(bySize);
             // Parents from the served set, which holds every parent the map draws. The hierarchy panel
             // asks `POST /v1/artifacts/browse` for the rest.
-            const parents = here ? served.filter((a) => here.parentIds.includes(a.mosaicaId)).sort((a, b) => (a.maskedCount < b.maskedCount ? 1 : a.maskedCount > b.maskedCount ? -1 : 0)) : [];
+            const parents = here ? served.filter((a) => here.parentIds.includes(a.mosaicaId)).sort(bySize) : [];
             const stale = s?.get('status').stale ?? false;
             const count = { value: Number(artifact.detail.maskedCount), exact: true };
             const id = idString(artifact.id);
@@ -300,34 +380,16 @@ let MosaicaArtifactCard = (() => {
             const shape = decl?.shape ? { kind: decl.shape, text: SHAPE_TEXT[decl.shape] } : null;
             // A clause made here carries the drawn name as its label, since nothing downstream can resolve it.
             const clauseName = here ? artifactName(here, attached) : null;
-            return html `<div class="panel">${heading(true)}
-      <span part="state" data-state="shown"></span>
-      <div part="headline" class="card-title" ?data-unnamed=${clauseName === null}>${clauseName ?? UNNAMED}</div>
+            return html `<h3 part="headline" class="card-title" tabindex="-1" ?data-unnamed=${clauseName === null}>${clauseName ?? UNNAMED}</h3>
       <div part="count"><mosaica-count .masked=${count} .stale=${stale} label="members"></mosaica-count></div>
       ${here && here.content.length > 0 && attached.has(here.mosaicaId) ? html `<p part="content">${attached.get(here.mosaicaId)}</p>` : here && here.content.length > 1 ? html `<p part="content">${here.content.slice(1).join(' · ')}</p>` : nothing}
-      <div class="field">
-        <div class="k">Layer</div><div part="value" class="v">${decl?.title || artifact.detail.layer}</div>
-        ${artifact.detail.key ? html `<div class="k">Key</div><div part="value" class="v mono">${artifact.detail.key}</div>` : nothing}
-        ${shape ? html `<div class="k">Shape</div><div part="shape" class="v" data-kind=${shape.kind}>${shape.text}</div>` : nothing}
-      </div>
-      ${parents.length > 0
-                ? html `<div part="label" class="xs muted parents-label">Parents</div>
-            <ul part="parents" class="list">
-              ${parents.map((pnt) => html `<li part="parent" class="item child" role="button" tabindex="0" data-id=${idString(pnt.mosaicaId)} @click=${() => void s?.openArtifact(pnt.mosaicaId)} @keydown=${onKeys(() => void s?.openArtifact(pnt.mosaicaId))}>
-                  ${nameSpan(artifactName(pnt, attached))}
-                  <mosaica-count .masked=${{ value: Number(pnt.maskedCount), exact: true }} .stale=${stale}></mosaica-count>
-                </li>`)}
-            </ul>`
-                : nothing}
-      ${children.length > 0
-                ? html `<div part="label" class="xs muted children-label">Children in this view</div>
-            <ul part="children" class="list">
-              ${children.map((c) => html `<li part="child" class="item child" role="button" tabindex="0" data-id=${idString(c.mosaicaId)} @click=${() => void s?.openArtifact(c.mosaicaId)} @keydown=${onKeys(() => void s?.openArtifact(c.mosaicaId))}>
-                  ${nameSpan(artifactName(c, attached))}
-                  <mosaica-count .masked=${{ value: Number(c.maskedCount), exact: true }} .stale=${stale}></mosaica-count>
-                </li>`)}
-            </ul>`
-                : nothing}
+      <dl class="field">
+        <dt class="k">Layer</dt><dd part="value" class="v">${decl?.title || artifact.detail.layer}</dd>
+        ${artifact.detail.key ? html `<dt class="k">Key</dt><dd part="value" class="v mono">${artifact.detail.key}</dd>` : nothing}
+        ${shape ? html `<dt class="k">Shape</dt><dd part="shape" class="v" data-kind=${shape.kind}>${shape.text}</dd>` : nothing}
+      </dl>
+      ${this.rows(false, parents, attached, stale)}
+      ${this.rows(true, children, attached, stale)}
       ${
             // A filter layer draws nothing, so there is nothing to fit to.
             decl && isFilterLayer(decl)
@@ -337,12 +399,7 @@ let MosaicaArtifactCard = (() => {
         ${this.verb(artifact.detail.layer, artifact.id, false, 'filter', 'Filter to this', clauseName)}
         ${this.verb(artifact.detail.layer, artifact.id, false, 'highlight', 'Highlight this', clauseName)}
         ${this.verb(artifact.detail.layer, artifact.id, true, 'filter', 'Outside this', clauseName)}
-      </div>
-    </div>`;
-        }
-        constructor() {
-            super(...arguments);
-            __runInitializers(this, _refusal_extraInitializers);
+      </div>`;
         }
     };
 })();

package/dist/base.d.ts

@@ -1,5 +1,5 @@
-import { LitElement, type PropertyValues } from 'lit';
-import { type SelectionShape, type Store, type TokenSupplier } from '@mosaicajs/client';
+import { LitElement, type PropertyValues, type TemplateResult } from 'lit';
+import { type ColumnDraft, type Meta, type SelectionShape, type Store, type TokenSupplier } from '@mosaicajs/client';
 import type { SelectionShapeDetail, MosaicaEventDetails } from './events.js';
 /**
  * Where an element's store came from: `property` is its `store` property, `context` a
@@ -99,13 +99,38 @@ export declare abstract class MosaicaElement extends LitElement {
     dispose(): void;
 }
 /**
- * What stands where an artifact has no name, on an element carrying `data-unnamed`, which draws it
- * faint. A key such as `hdb-2422486` is an identifier and would read as a name, so it shows only in
- * the card's key field.
+ * What stands where an artifact has neither a name nor a key, on an element carrying
+ * `data-unnamed`, which draws it faint.
  */
 export declare const UNNAMED = "Unnamed";
+/**
+ * What a list calls an artifact. `from` is `name` for its name, `key` for its publisher's key where
+ * it has no name, and `none` for {@link UNNAMED} where it has neither. A key is drawn on an element
+ * carrying `data-key-name`, in the secondary ink and the identifiers' font, so that it does not read
+ * as a name.
+ */
+export type Called = {
+    text: string;
+    from: 'name' | 'key' | 'none';
+};
+/** What a list calls an artifact with this name and key, either of which may be missing or empty. */
+export declare function called(name: string | null | undefined, key: string | null | undefined): Called;
+/** What a list calls an artifact, as text marked `data-key-name` for a key and `data-unnamed` for {@link UNNAMED}. */
+export declare function calledText(c: Called): TemplateResult;
+/** What a list calls several artifacts, as {@link calledText} marks each, separated by commas. */
+export declare function calledList(cs: readonly Called[]): TemplateResult;
+/** The `label` a `member_of` clause on an artifact carries: what it is called, unless that is {@link UNNAMED}. */
+export declare function labelOf(c: Called): {
+    label?: string;
+};
 /** Emit one of the elements' events, bubbling and composed so it crosses shadow roots. */
 export declare function emit<K extends keyof MosaicaEventDetails>(from: HTMLElement, name: K, detail: MosaicaEventDetails[K]): void;
+/**
+ * Whether focus is on nothing in the page, as it is once the control that had it has left: an
+ * element that removed that control may then place focus. Focus anywhere else is the viewer's to
+ * keep.
+ */
+export declare function focusLost(): boolean;
 /**
  * A count shortened to its first figures and a letter, `250K`, `25.2M`, `3.5B`, where room is
  * short; below a thousand, whole.
@@ -125,6 +150,20 @@ export declare function columnCaption(name: string): string;
  * else the key.
  */
 export declare function keyTitle(store: Store | null, column: string, key: string): string;
+/** A bool's two values, as the keys a bool card's rows carry. */
+export type BoolKey = 'true' | 'false';
+/** A bool's values in the order a card lists them. */
+export declare const BOOL_KEYS: readonly BoolKey[];
+/** A bool's values as the server stores, bins and filters them. */
+export declare const BOOL_NUMBERS: Record<BoolKey, 0 | 1>;
+/** A bool's values as a card, a chip and an item card name them. */
+export declare const BOOL_WORDS: Record<BoolKey, string>;
+/** Whether `column` is declared `bool`. */
+export declare function isBoolColumn(meta: Meta | null | undefined, column: string): boolean;
+/** The values of a bool, true then false, that a clause on it keeps: those whose 1 or 0 lies within its range. */
+export declare function boolKeys(draft: ColumnDraft | undefined): BoolKey[];
+/** The clause on a bool that keeps `keys`: a range over their 1 and 0, or no clause for none. */
+export declare function boolClause(keys: readonly BoolKey[]): ColumnDraft;
 /**
  * A `timestamp_us` value in full, readably and in UTC: `14 March 2024, 12:00 UTC`, with seconds
  * where they are not zero. Fractions of a second are left out.

package/dist/base.js

@@ -33,9 +33,9 @@ var __runInitializers = (this && this.__runInitializers) || function (thisArg, i
     return useValue ? value : void 0;
 };
 import { ContextConsumer } from '@lit/context';
-import { LitElement } from 'lit';
+import { LitElement, html } from 'lit';
 import { property } from 'lit/decorators.js';
-import { createStore } from '@mosaicajs/client';
+import { createStore, isPopulated } from '@mosaicajs/client';
 import { storeContext } from './context.js';
 /**
  * What every element shares: how it finds its store, and how it follows it.
@@ -292,15 +292,42 @@ let MosaicaElement = (() => {
 })();
 export { MosaicaElement };
 /**
- * What stands where an artifact has no name, on an element carrying `data-unnamed`, which draws it
- * faint. A key such as `hdb-2422486` is an identifier and would read as a name, so it shows only in
- * the card's key field.
+ * What stands where an artifact has neither a name nor a key, on an element carrying
+ * `data-unnamed`, which draws it faint.
  */
 export const UNNAMED = 'Unnamed';
+/** What a list calls an artifact with this name and key, either of which may be missing or empty. */
+export function called(name, key) {
+    if (name)
+        return { text: name, from: 'name' };
+    if (key)
+        return { text: key, from: 'key' };
+    return { text: UNNAMED, from: 'none' };
+}
+/** What a list calls an artifact, as text marked `data-key-name` for a key and `data-unnamed` for {@link UNNAMED}. */
+export function calledText(c) {
+    return html `<span ?data-key-name=${c.from === 'key'} ?data-unnamed=${c.from === 'none'}>${c.text}</span>`;
+}
+/** What a list calls several artifacts, as {@link calledText} marks each, separated by commas. */
+export function calledList(cs) {
+    return html `${cs.map((c, i) => html `${i > 0 ? ', ' : ''}${calledText(c)}`)}`;
+}
+/** The `label` a `member_of` clause on an artifact carries: what it is called, unless that is {@link UNNAMED}. */
+export function labelOf(c) {
+    return c.from === 'none' ? {} : { label: c.text };
+}
 /** Emit one of the elements' events, bubbling and composed so it crosses shadow roots. */
 export function emit(from, name, detail) {
     from.dispatchEvent(new CustomEvent(name, { detail, bubbles: true, composed: true }));
 }
+/**
+ * Whether focus is on nothing in the page, as it is once the control that had it has left: an
+ * element that removed that control may then place focus. Focus anywhere else is the viewer's to
+ * keep.
+ */
+export function focusLost() {
+    return document.activeElement === null || document.activeElement === document.body;
+}
 /**
  * A count shortened to its first figures and a letter, `250K`, `25.2M`, `3.5B`, where room is
  * short; below a thousand, whole.
@@ -337,6 +364,28 @@ export function keyTitle(store, column, key) {
     const named = store.get('legend').categories[column]?.find((v) => v.key === key) ?? store.get('filters').suggestions[column]?.values.find((v) => v.key === key);
     return named?.title ?? key;
 }
+/** A bool's values in the order a card lists them. */
+export const BOOL_KEYS = ['true', 'false'];
+/** A bool's values as the server stores, bins and filters them. */
+export const BOOL_NUMBERS = { true: 1, false: 0 };
+/** A bool's values as a card, a chip and an item card name them. */
+export const BOOL_WORDS = { true: 'yes', false: 'no' };
+/** Whether `column` is declared `bool`. */
+export function isBoolColumn(meta, column) {
+    return meta?.declaredScalars.find((c) => c.name === column)?.arrowType === 'bool';
+}
+/** The values of a bool, true then false, that a clause on it keeps: those whose 1 or 0 lies within its range. */
+export function boolKeys(draft) {
+    if (draft?.family !== 'numeric' || !isPopulated(draft))
+        return [];
+    const { gte, lte } = draft;
+    return BOOL_KEYS.filter((k) => (gte === null || BOOL_NUMBERS[k] >= gte) && (lte === null || BOOL_NUMBERS[k] <= lte));
+}
+/** The clause on a bool that keeps `keys`: a range over their 1 and 0, or no clause for none. */
+export function boolClause(keys) {
+    const values = keys.map((k) => BOOL_NUMBERS[k]);
+    return values.length === 0 ? { family: 'numeric', gte: null, lte: null } : { family: 'numeric', gte: Math.min(...values), lte: Math.max(...values) };
+}
 const DATE = new Intl.DateTimeFormat('en-GB', { day: 'numeric', month: 'long', year: 'numeric', timeZone: 'UTC' });
 const pad = (n) => String(n).padStart(2, '0');
 /**