tosijs-ui 1.16.31 → 1.16.32

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 1.16.32
+
+Two new components, a doc search that ranks, and live examples whose toolbar no longer covers
+what they draw. Nothing an adopter has to change: the toolbar and the search are doc-site
+behaviour, and both components are new. One thing to know if you embed the doc browser in an
+app: it now opens its search on Cmd/Ctrl-K. If your page owns that key, pass
+`createDocBrowser({ searchShortcut: '' })` (or another key).
+
+`dist/iife.js` grows by about 7 KB gzip (496.4 KB to 503.4 KB, +1.4%): the palette is 9.1 KB
+gzip and the affix 5.0 KB. The ESM path pays only for what it imports.
+
+### New components
+
+- **`<tosi-palette>`** (`tosiPalette`): a command palette. A compact search-field trigger
+  opens a centred modal of ranked results. Results come from `sources` (sync, or async with a
+  spinner and a `timeout`, 10s by default; each keystroke aborts the last search), are drawn
+  per `kind` by `renderers` (or a default row: icon, highlighted title, one-line description,
+  path), ranked by `score` and grouped by `group` (or by your own `rank`), with `quickLinks`
+  before anything is typed. Arrow keys, Enter and Escape drive it, `shortcut: 'mod+k'` opens it
+  from anywhere (a shortcut with an unknown modifier is ignored, with a console warning, rather
+  than binding the bare key), `multiline` makes the query a growing prompt, and choosing fires `action`.
+  `trigger` is `field` (the default, which shrinks to its icon below `compactWidth`, 160px),
+  `icon`, or `none` for a palette opened only by `open()` or its shortcut. Its colours come
+  from the theme's root `--tosi-text` / `--tosi-bg` / `--tosi-accent`, so a recoloured header
+  does not make its results invisible. The dialog sets its own line height, wrapping and font
+  size, so a header's do not reach it. The palette footer's Close is a button, for a phone,
+  which has no Escape key; on a touch screen the arrow/Enter cues and the Esc hint are hidden.
+  The ✕ that clears the query is hidden until something is typed.
+- **`<tosi-affix>`** (`tosiAffix`): fixes a fixture (`slot="fixture"`) to an edge of its
+  content, in the FloatPosition vocabulary: the first letter is the edge, the second the
+  alignment, so `en` is the right edge, top-aligned. Outside (the default) it takes a grid cell
+  beside the content, so it never covers it and an ancestor's overflow cannot clip it; `inside`
+  puts it within the content against that edge. `fallback` (e.g. `"s inside"`) is used while
+  the fixture is longer than its edge. Setting `position`/`inside` sets where it is wanted,
+  reading them gives where it is, the `placed` attribute reflects it, and a `reposition` event
+  fires when it changes. It looks finished with no styling: a flex column on a side edge, a row
+  on top or bottom, the theme's inset background and spacing, outer corners rounded
+  (`--tosi-affix-bg/gap/padding/radius`, `::part(fixture)`).
+
+### Doc system
+
+- **Search ranks pages, in the header.** The sidebar's nav filter (a substring test that hid
+  pages and ranked nothing) is replaced by a palette in the header bar: the site's search
+  field while there is room, its icon when the header is narrow, and Cmd/Ctrl-K on every page,
+  `{"header": false}` pages included. Pages are ranked by rough relevance (title, then
+  headings, keywords, description, opening paragraph, body), and a matching heading becomes a
+  deep link. A query word matches only the start of a word, camelCase split ("date" finds
+  `tosiDate`, not "update"), a whole word or its plural outranks a prefix, and a word used
+  often counts for more than one used once. A word matched in one heading no longer counts for
+  the next query word. The trigger looks like the search field it replaced (the site's
+  pill-shaped input), and the active row is a tint of the theme's accent. The ranking is
+  exported as `buildDocIndex` / `searchDocs` from `tosijs-ui/doc-system/doc-search`, with
+  section anchors taken from the renderer's own heading ids. `createDocBrowser({ searchShortcut })` sets the key
+  that opens the search, `''` for none.
+- **A live example's toolbar sits beside the preview**, outside its outline, instead of a
+  pocket bar over the preview's top-right corner (which covered whatever the example drew
+  there, the crud example's New button for one). It moves inside along the bottom when the
+  column is taller than the preview, and when the example is maximized. The run-tests check
+  shows the test status; the owl handle is gone.
+- Below 600px of header the link icons fold into the settings (⋮) menu, so an upright phone
+  has room for the title and the search.
+
+### Fixed
+
+- `<tosi-crud>` has a Close button (and `close()`) that returns to the list. Under 720px (the
+  doc preview included) an open record replaces the list instead of squeezing into a 210px
+  column beside it, and the component fills a container with a height. A store that can only
+  list no longer shows New, Save and Delete where the page styles `button` with a `display`.
+  Without a schema, New starts from the fields the listed rows have instead of an empty form.
+- Boolean columns from a schema asked for icons named "✓" and "✗", which do not exist; they
+  use `check` and `x`.
+- `<tosi-table>` with no `columns` and data that arrived later showed no columns: it now
+  infers them once there is a row.
+- `<tosi-schema-form>` with no schema kept the schema inferred from an empty value forever, and
+  threw "unobserve failed, listener not found" every time it left the page.
+
+### Dependencies
+
+- The optional `happy-dom` peer is now `^21.0.4` (was `^20.7.0`), and tosijs-ui's own tests
+  run on 21.0.4. Every happy-dom from 17.0.0 to 21.0.3 is affected by
+  [GHSA-834v-8h66-3h79](https://github.com/advisories/GHSA-834v-8h66-3h79) (an unsanitized
+  import alias leads to host code execution), and there is no fixed 20.x. It matters only if
+  you use `tosijs-ui/test-setup` or build ePubs; then upgrade to 21.0.4. Its one breaking
+  change is that CSS and iframe loading are off by default, which neither relies on.
+
+### Tunnel
+
+- A workspace no longer makes a request wait on the box for the revoked-device list. A
+  copy up to ten minutes old is used at once and refreshed behind, and when the list becomes
+  unreadable the dev server says so, and why. `tosijs-tunnel` refuses flag combinations it
+  used to ignore silently: `--share-ttl` with `--global` or without `--link --share`, and
+  `--label` anywhere but on a `--link --global` edit link.
+
 ## 1.16.31
 
 **Tunnel users: each browser needs one new `tosijs-tunnel --link --global`.** The edit cookie

package/bin/resolve-site-config.ts

@@ -422,6 +422,35 @@ export interface Argv {
   rest: string[]
 }
 
+/**
+ * `tosijs-tunnel` flag combinations that would otherwise be silently ignored, each with what to
+ * do instead (1.16.31 review). A flag that changes nothing is a promise the bin does not keep.
+ */
+export function tunnelFlagProblems(args: {
+  has: (name: string) => boolean
+  flag: (name: string) => string | undefined
+}): string[] {
+  const problems: string[] = []
+  const link = args.has('link')
+  const share = args.has('share')
+  const global = args.has('global')
+  if (args.flag('share-ttl') !== undefined) {
+    if (global)
+      problems.push(
+        '--share-ttl does not apply to --global links: they always expire after 5 minutes. For a longer-lived view link, use --link --share --share-ttl=… without --global.'
+      )
+    else if (!(link && share))
+      problems.push('--share-ttl only applies to --link --share.')
+  }
+  if (args.flag('label') !== undefined) {
+    if (!(link && global) || share)
+      problems.push(
+        '--label names the device a --link --global EDIT link is for; it does nothing elsewhere.'
+      )
+  }
+  return problems
+}
+
 /**
  * Parse `argv` against `spec`. Prints usage and exits on `--help` (0) or on an
  * unrecognised flag (1); returns a reader otherwise.

package/bin/tunnel.ts

@@ -48,6 +48,7 @@ import {
   parseDeviceListing,
   DEVICE_LISTING_SEPARATOR,
   DEVICE_ID_PATTERN,
+  tunnelFlagProblems,
 } from './resolve-site-config.ts'
 
 const { has, flag } = parseArgv(process.argv.slice(2), {
@@ -81,6 +82,15 @@ const { has, flag } = parseArgv(process.argv.slice(2), {
     `  --port= --local-port= --remote-port= override the resolved ports`,
 })
 
+{
+  const problems = tunnelFlagProblems({ has, flag })
+  if (problems.length) {
+    for (const problem of problems) console.error(`\n${problem}`)
+    console.error('')
+    process.exit(1)
+  }
+}
+
 const siteConfig = await resolveSiteConfig()
 
 const preview = siteConfig.preview

package/dist/affix.d.ts

@@ -0,0 +1,97 @@
+import { Component, ElementCreator, PartsMap } from 'tosijs';
+export type AffixPosition = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw' | 'en' | 'wn' | 'es' | 'ws';
+export interface AffixPlacement {
+    position: AffixPosition;
+    inside: boolean;
+}
+/** `position` as written, or the default when it is not one. */
+export declare function affixPosition(value: unknown): AffixPosition;
+/** `"s inside"` → `{position: 's', inside: true}`; '' → null (no fallback). */
+export declare function parsePlacement(value: unknown): AffixPlacement | null;
+/** `{position: 's', inside: true}` → `"s inside"`. */
+export declare const describePlacement: ({ position, inside }: AffixPlacement) => string;
+type Track = 1 | 2 | 3;
+type Align = 'start' | 'center' | 'end';
+/**
+ * The grid cell and alignment for a placement. Outside, the fixture takes the cell on its
+ * edge, hugging the content; inside, it shares the content's cell, against that edge.
+ */
+export declare function affixCell({ position, inside }: AffixPlacement): {
+    row: Track;
+    column: Track;
+    alignSelf: Align;
+    justifySelf: Align;
+    direction: string;
+    edge: "n" | "s" | "e" | "w";
+};
+interface AffixParts extends PartsMap {
+    content: HTMLSlotElement;
+    fixture: HTMLSlotElement;
+}
+export declare class TosiAffix extends Component<AffixParts> {
+    static initAttributes: Record<string, unknown>;
+    /** Where the fixture goes when the wanted place does not fit: `"s inside"`, or '' for nowhere. */
+    fallback: string;
+    static preferredTagName: string;
+    static shadowStyleSpec: {
+        ':host': {
+            display: string;
+            gridTemplateColumns: string;
+            gridTemplateRows: string;
+            '--tosi-affix-direction': string;
+        };
+        ':host([hidden])': {
+            display: string;
+        };
+        ':host > [part="content"]': {
+            display: string;
+            gridArea: string;
+            minWidth: string;
+            minHeight: string;
+            position: string;
+        };
+        ':host > [part="fixture"]': {
+            display: string;
+            flexDirection: string;
+            alignItems: string;
+            zIndex: string;
+            gap: string;
+            padding: string;
+            background: string;
+            color: string;
+        };
+        ':host > [part="fixture"][hidden]': {
+            display: string;
+        };
+    };
+    content: () => HTMLSlotElement[];
+    private _wanted;
+    private _placed;
+    private _wantedLength;
+    private _observer;
+    /** Where the fixture is (set: where it should be). */
+    get position(): AffixPosition;
+    set position(value: string);
+    /** Whether the fixture is inside the content (set: whether it should be). */
+    get inside(): boolean;
+    set inside(value: boolean | string);
+    /** Where the fixture should be, whatever fits. */
+    get wanted(): AffixPlacement;
+    /** An empty fixture slot is hidden, so it takes no room and draws no background. */
+    private syncEmpty;
+    handleSlotChange: () => void;
+    connectedCallback(): void;
+    private _observed;
+    observeContent: () => void;
+    disconnectedCallback(): void;
+    /** The fixture's and the content's lengths along `edge`, as laid out now. */
+    private lengths;
+    /** Choose where the fixture goes, lay it out there, and announce a change. */
+    place: () => void;
+    /** Lay the fixture out at `placement`, and announce it if that is a change. */
+    private layout;
+    private apply;
+    render(): void;
+}
+export declare const tosiAffix: ElementCreator<TosiAffix>;
+export {};