tosijs-ui 1.16.39 → 1.16.41

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 1.16.41
+
+- **A `noindex` page is left out of `llms.txt`.** The sitemap and the markdown copies already
+  left it out, but `llms.txt` still listed it, so an agent reading the index was sent to pages
+  the author had asked not to be found.
+- **Every page on ui.tosijs.net has a written description, and the terse titles say what the
+  component is.** 63 pages described themselves with whatever their first paragraph said ("A
+  mapboxgl wrapper.", sentences cut off at 155 characters), which is what search results, link
+  previews and `llms.txt` showed. Short nav labels such as "map" and "table" keep their place in
+  the nav and get a fuller `<title>` through `headTitle`. The kitchen sink and the two layout
+  demo pages are `noindex`. The practice behind the rewrite is proposed for the shared coding
+  practices (tosijs-coding-practices #3561).
+
+## 1.16.40
+
+- **An example with no script runs under a strict CSP (#245, #246).** A pure-HTML example still
+  built an `AsyncFunction` from its empty script, and a dialect that runs its own source (`run`)
+  had one built before its `run` was called. Under a Content Security Policy without
+  `'unsafe-eval'` (`script-src 'self'`) the constructor throws, so each such example showed an
+  error and filed a violation report every time it ran. Neither now constructs a function at
+  all, so HTML examples, and `run` dialects that only sanitize and bind markup, work on a
+  CSP-protected host. Script examples still need `'unsafe-eval'`; a CSP-compatible path for
+  them, and an HTML-only example mode, are planned for 1.17.0.
+- **The doc header's search says "Search", and a site can set it.** `searchPlaceholder` in the
+  site config (or `createDocBrowser`) sets the hint in the header's search field, and the
+  trigger's accessible name; the default was "Search documentation" (set
+  `searchPlaceholder: 'Search documentation'` to keep it, and update any test that looks the
+  field up by that name). It is localized through the site's strings, and its placeholder
+  follows the locale the reader picks. `<tosi-palette>` gained a `localizer` property for this: a function its placeholder
+  goes through, such as `localize`. It is a function rather than a `localized` attribute so the
+  palette does not import the localization module, and `<tosi-select>` with it, wherever it is
+  used.
+- **The ⌘K hint in the search field has no outline.** An outline inside the field's own outline
+  read as a second control. The hints inside the open palette keep theirs.
+
 ## 1.16.39
 
 - **The doc-site frame passes WCAG 2.2 AA where an axe scan said it did not (#3520).** An

package/bin/make-icon-data.js

@@ -86,7 +86,7 @@ byte-identical files, so it never shows up as spurious diff noise.
 > your prettier config, which it now honours) — not the output.
 */
 
-/*{ "parent": "icons", "order": 30 }*/
+/*{ "parent": "icons", "order": 30, "description": "A build tool that turns folders of SVG files into the icon-data module behind the tosijs-ui icon system, optimizing the paths as it goes." }*/
 
 import fs from 'fs'
 import path from 'path'

package/bin/release-notes.ts

@@ -60,7 +60,7 @@ commit whose diff never touched the file it named. Cheap to detect, and the fail
 catches is expensive.
 */
 
-/*{ "parent": "Appendices" }*/
+/*{ "parent": "Appendices", "description": "tosijs-release-notes builds CHANGELOG sections from tagged bullets in commit messages, and fails a release when one is left unwritten." }*/
 
 import { $ } from 'bun'
 import {

package/dist/ab-test.js

@@ -75,7 +75,7 @@ randomize()
 - `condition` attribute determines which value in `AbTest.conditions` controls the element
 - `not` reverses the condition (so `<tosi-ab not condition="foo">` will be visible if `conditions.foo` is `false`)
 */
-/*{ "parent": "Helper Libraries" }*/
+/*{ "parent": "Helper Libraries", "description": "<tosi-ab> shows or hides content by condition, so you can run A/B tests or feature flags by setting AbTest.conditions." }*/
 import { withAttributes } from 'tosijs';
 const abTestConditions = {};
 export class AbTest extends withAttributes({

package/dist/affix.js

@@ -142,7 +142,7 @@ and `describePlacement({ position, inside })` convert between the attribute and
 `{ position, inside }`, and `affixCell(placement)` gives the grid cell and alignment a
 placement takes.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-affix> attaches a toolbar, badge or caption to one edge of its content, laid out beside it rather than floated, so it never covers it." }*/
 import { Component, elements } from 'tosijs';
 const { slot } = elements;
 const POSITIONS = new Set([

package/dist/babylon-3d.js

@@ -220,7 +220,7 @@ be used to load `.glb` files. Setting `src` calls this for you on connect.
 
 `<tosi-3d>.loadUI(options: B3dUIOptions)` loads babylonjs guis, which you can create programmatically or using the [babylonjs gui tool](https://gui.babylonjs.com/).
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-3d> Babylon.js wrapper (deprecated) — tosijs-ui", "description": "Deprecated: <tosi-3d> is a thin Babylon.js wrapper kept for compatibility. New 3D work should use the tosijs-3d package." }*/
 import { elements, withAttributes } from 'tosijs';
 import { scriptTag } from './via-tag.js';
 import { icons, svg2DataUrl } from './icons.js';

package/dist/bodymovin-player.js

@@ -101,7 +101,7 @@ And of course just access the element's `animation` property to [use the bodymov
 
 Also see the [documentation for advanced interactions](https://lottiefiles.github.io/lottie-docs/advanced_interactions/)
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-lottie> Lottie animation player — tosijs-ui", "description": "<tosi-lottie> plays Lottie (bodymovin) animations like an <img>: set src or json, and use the bodymovin API through its animation property." }*/
 import { withAttributes } from 'tosijs';
 import { scriptTag } from './via-tag.js';
 export class BodymovinPlayer extends withAttributes({

package/dist/carousel.js

@@ -68,7 +68,7 @@ This is a minimalist carousel component that supports the usual stuff.
 
 <tosi-css-var-editor element-selector="tosi-carousel"></tosi-css-var-editor>
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "A minimal carousel with optional arrows and dots, several items per page, looping, and auto-advance that holds still while someone is looking." }*/
 import { elements, vars, withAttributes } from 'tosijs';
 import { icons } from './icons.js';
 import { prefersReducedMotion } from './reduced-motion.js';

package/dist/code-editor.js

@@ -111,7 +111,7 @@ Only `@codemirror/state` and `@codemirror/view` are re-exported — the two you
 view. The language, lint and search packages are internal composition details; ask if you need
 one exposed.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-code> CodeMirror 6 code editor — tosijs-ui", "description": "<tosi-code> embeds a CodeMirror 6 editor for JavaScript, TypeScript, CSS, HTML and Markdown, with undo, a diff view and a change event." }*/
 import { elements, varDefault, withAttributes, } from 'tosijs';
 import { tosiDiff } from './diff.js';
 const { div } = elements;

package/dist/color-input.js

@@ -27,7 +27,7 @@ colorInput.addEventListener('change', () => {
 
 <tosi-css-var-editor element-selector="tosi-color"></tosi-css-var-editor>
 */
-/*{ "parent": "Form Components" }*/
+/*{ "parent": "Form Components", "description": "<tosi-color> is a colour input that also edits opacity, so it can produce translucent colours that the native colour picker cannot." }*/
 import { Component, elements, Color, vars, } from 'tosijs';
 const { input } = elements;
 const defaultColor = Color.fromCss('#8888');

package/dist/crud.js

@@ -304,7 +304,7 @@ for every instance; each one re-checks it the next time it is resized.
 - `change` — the selection or the saved record changed.
 - `error` — a store operation failed.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-crud> pairs a searchable table with a schema-driven form over a store you supply (REST, IndexedDB or an array) for list-and-edit screens." }*/
 import { elements, withAttributes } from 'tosijs';
 import { tosiTable } from './data-table.js';
 import { tosiSchemaForm } from './schema-form.js';

package/dist/data-table.js

@@ -1241,7 +1241,7 @@ As well as any column names you want localized — these are also used as the ac
 (`aria-label`) of each editable cell, so an editable table wants them present even if you are
 happy with the untranslated headers.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "headTitle": "<tosi-table> virtual data table — tosijs-ui", "description": "A virtual data table for very large datasets: sortable, resizable, pinnable columns inferred from the data, keyboard navigation and row detail." }*/
 import { elements, vars, varDefault, tosiValue, getListItem, getListBinding, tosi, withAttributes, } from 'tosijs';
 import { trackDrag } from './track-drag.js';
 import { naturalSorter } from './natural-compare.js';

package/dist/dialog.js

@@ -143,7 +143,7 @@ preview.append(
 ```
 
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-dialog> wraps the native <dialog> element with an OK button, a footer slot, and promise-based alert, confirm and prompt helpers." }*/
 import { Component, elements, on, vars, varDefault } from 'tosijs';
 import { findHighestZ } from './track-drag.js';
 const { dialog, button, header, footer, tosiSlot, h3, p, label, input, div } = elements;

package/dist/diff.js

@@ -101,7 +101,7 @@ and writable if you want to drive it yourself. Resolutions **reset when either t
 changes** — decisions belong to the diff they were made about.
 
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-diff> shows a unified, line-by-line diff between two strings, with removed and added lines marked, as in a code review." }*/
 import { elements, vars, varDefault, withAttributes, } from 'tosijs';
 const { div, span, button } = elements;
 /** Group a line diff into context runs and change blocks, in display order. */

package/dist/doc-browser.d.ts

@@ -118,6 +118,11 @@ export interface DocBrowserOptions {
      * for a host page that owns that key or embeds more than one browser.
      */
     searchShortcut?: string;
+    /**
+     * The hint in the header's search field (default `'Search'`). Localized through the site's
+     * strings, like every other piece of the doc system's own text.
+     */
+    searchPlaceholder?: string;
     /**
      * Header-bar links. When provided, these replace the legacy `projectLinks` icon
      * set in the header (each renders as an icon if `icon` names a known icon, else

package/dist/doc-browser.js

@@ -98,7 +98,7 @@ The search opens on Cmd-K (Ctrl-K off a Mac) anywhere on the page. A host that o
 or embeds more than one browser, passes `searchShortcut: ''` (or another key in
 `<tosi-palette>`'s `shortcut` form).
 */
-/*{ "parent": "Documentation System", "order": 50 }*/
+/*{ "parent": "Documentation System", "order": 50, "description": "createDocBrowser() renders a documentation corpus as a searchable browser with live, self-testing examples: a lighter alternative to Storybook." }*/
 import { elements, vars, varDefault, bindings, getListItem, tosi, StyleSheet, } from 'tosijs';
 import { buildSlugMap, pathForSlug, filenameForPath, homeDoc, wikilinkTargets, } from './doc-system/routing.js';
 import { buildNavTree } from './doc-system/nav-tree.js';
@@ -115,7 +115,7 @@ import { tosiSidenav, TosiSidenav } from './side-nav.js';
 import { icons } from './icons.js';
 import { tosiPalette } from './palette.js';
 import { buildDocIndex, searchDocs } from './doc-system/doc-search.js';
-import { tosiLocalized } from './localize.js';
+import { tosiLocalized, localize, i18n } from './localize.js';
 import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
@@ -395,7 +395,7 @@ let docBrowserSeq = 0;
 // Likewise for the nav's aria-controls ids.
 let navIdCounter = 0;
 export function createDocBrowser(options) {
-    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', searchPlaceholder = 'Search', navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
     // window.history/location, so an embedded or nested browser can't hijack the
     // host page's URL (or recurse into it).
@@ -750,11 +750,14 @@ export function createDocBrowser(options) {
     // In the header bar (see headerContent); the nav no longer holds a search field.
     const searchBox = tosiPalette({
         class: 'doc-search',
-        placeholder: 'Search documentation',
+        placeholder: searchPlaceholder,
+        localizer: localize,
         shortcut: searchShortcut,
         sources: [docSearchSource],
         quickLinks,
     });
+    // The hint follows the reader's language, like the rest of the doc system's own text.
+    i18n.locale.observe(() => searchBox.queueRender());
     // Memory routing is decoupled from the page URL, so it ignores browser
     // back/forward (the host owns history, if any).
     if (!memoryRouting) {

package/dist/doc-system/data-client.js

@@ -1,4 +1,4 @@
-/*{ "parent": "Documentation System", "order": 85 }*/
+/*{ "parent": "Documentation System", "order": 85, "description": "Open and save a project's data files from a dev-server page, for in-browser tools such as level or scene editors, optionally committing each save." }*/
 /*#
 # data client
 

package/dist/doc-system/doc-system-styles.js

@@ -66,7 +66,7 @@ export function docSystemColors(theme = {}) {
         /*
         Readable, not faint (#3520). This was the brand at 40% opacity, which an axe scan measured
         at 1.88:1 on the input (#eda7c5 on #fdfdfd) where AA asks 4.5:1, and it colours the doc
-        header's "Search documentation" trigger, a real label, not just a hint.
+        header's search trigger, a real label, not just a hint.
         */
         _placeholderColor: readableOn(brandColor, Color.fromCss(theme.inputBg ?? '#fdfdfd')),
         /*

package/dist/doc-system/doc-system.js

@@ -55,7 +55,7 @@ A self-contained, controllable embed (e.g. docs in a floating panel):
 </tosi-doc-system>
 ```
 */
-/*{ "parent": "Documentation System", "order": 40 }*/
+/*{ "parent": "Documentation System", "order": 40, "description": "<tosi-doc-system> hydrates pre-rendered static doc pages into a fast single-page doc browser, keeping full HTML for search engines and no-JS readers." }*/
 import { StyleSheet, elements, tosi, vars, withAttributes, } from 'tosijs';
 import * as tosijsModule from 'tosijs';
 import { createDocBrowser, } from '../doc-browser.js';
@@ -608,6 +608,7 @@ export class TosiDocSystem extends withAttributes({
             projectLinks: config.projectLinks,
             logo: config.logo,
             navbarLinks: navbarLinks.length ? navbarLinks : undefined,
+            searchPlaceholder: config.searchPlaceholder,
             contentElement,
         });
         // Add the settings (theme + language) menu — except in a nested demo, where

package/dist/doc-system/highlight-styles.js

@@ -1,4 +1,4 @@
-/*{ "parent": "Documentation System", "order": 80 }*/
+/*{ "parent": "Documentation System", "order": 80, "description": "The syntax-highlighting token colours as a stylesheet you can import and retheme, for code highlighted outside <tosi-highlight>." }*/
 /*#
 # highlight-styles
 

package/dist/doc-system/site/docs.js

@@ -37,7 +37,7 @@ whatever metadata the doc declares (`pin`, `order`, `parent`, `layout`, `descrip
 Metadata blocks (`<!--{ … }-->` in markdown, `/*{ … }*‎/` in code), nav order, sections and
 which code fences run live are described under [Doc format](/doc-site-system/#doc-format).
 */
-/*{ "parent": "Documentation System", "order": 60 }*/
+/*{ "parent": "Documentation System", "order": 60, "description": "extractDocs() collects markdown files and doc comments from source code into one docs.json corpus, the input to the doc browser and static site." }*/
 // TODO CLI options
 import * as fs from 'fs';
 import * as path from 'path';

package/dist/doc-system/site/generate-site.d.ts

@@ -8,6 +8,8 @@ export interface GenerateSiteConfig {
     docs: Doc[];
     /** `SiteConfig.aliases`: { alias path -> slug } (board #3513) */
     aliases?: Record<string, string>;
+    /** `SiteConfig.searchPlaceholder` */
+    searchPlaceholder?: string;
     /**
      * Mirrors `SiteConfig.liveExamples`. The static highlighter needs it so it skips the
      * fences that will become live examples — a highlighted block hands the example markup

package/dist/doc-system/site/generate-site.js

@@ -368,6 +368,7 @@ export async function generateSite(config) {
         logo: config.logo,
         bookVolumes: config.bookVolumes,
         ebooks: config.ebooks,
+        searchPlaceholder: config.searchPlaceholder,
     }));
     // The theme stylesheet (config.stylesUrl) is written separately by
     // ./generate-css.ts; pages here just <link> to it.

package/dist/doc-system/site/make-llms-txt.d.ts

@@ -6,6 +6,7 @@ interface CorpusDoc {
     text?: string;
     description?: string;
     hidden?: boolean;
+    noindex?: boolean;
 }
 interface LlmsEntry {
     title: string;

package/dist/doc-system/site/make-llms-txt.js

@@ -44,14 +44,16 @@ function extractDescription(text) {
 export function entriesFromCorpus(corpus, meta) {
     const slugMap = buildSlugMap(corpus);
     const base = (meta.baseUrl ?? '').replace(/\/$/, '');
-    return corpus
-        .filter((doc) => doc.title && !doc.hidden)
+    return (corpus
+        // A noindex page is one the author asked not to be found; the sitemap and the markdown
+        // copies already leave it out, and an index for agents is no different.
+        .filter((doc) => doc.title && !doc.hidden && !doc.noindex)
         .map((doc) => ({
         title: doc.title,
         description: doc.description?.trim() || extractDescription(doc.text ?? ''),
         link: base + withBase(meta.basePath, pathForSlug(slugMap[doc.filename])),
     }))
-        .sort((a, b) => a.title.localeCompare(b.title));
+        .sort((a, b) => a.title.localeCompare(b.title)));
 }
 /**
  * Legacy fallback when no corpus is passed (e.g. running this file directly):

package/dist/doc-system/site/orchestrator.js

@@ -1497,6 +1497,7 @@ export async function buildSite(config, opts = {}) {
                 liveExamples: config.liveExamples,
                 docs,
                 aliases: config.aliases,
+                searchPlaceholder: config.searchPlaceholder,
                 outputDir: PUBLIC,
                 projectName: config.name,
                 bookVolumes: printCoverManifestUrl(config),

package/dist/doc-system/site/site-config.d.ts

@@ -71,6 +71,11 @@ export interface SiteConfig {
      * on one that is not, that takes a page's own path or a static folder's, or that names no page.
      */
     aliases?: Record<string, string>;
+    /**
+     * The hint in the header's search field. Default `'Search'`. It is localized like the rest
+     * of the doc system's own text, so a site with translations can translate it.
+     */
+    searchPlaceholder?: string;
     /**
      * Directories to skip while scanning `docPaths` — by basename (skipped wherever it
      * appears) or by path (skipped only at that location). Added to the built-in

package/dist/drag-and-drop.js

@@ -291,7 +291,7 @@ preview.append(
 > `data-drop` in this example.
 )
 */
-/*{ "parent": "Helper Libraries" }*/
+/*{ "parent": "Helper Libraries", "description": "Make HTML5 drag and drop usable: one init() call highlights compatible drop zones as a drag starts, including zones added mid-drag." }*/
 const dragInProgress = () => !!document.querySelector('.drag-source');
 export const isTypeAllowed = (allowedTypes, type) => {
     if (!allowedTypes) {

package/dist/editable-rect.js

@@ -65,7 +65,7 @@ Similarly `EditableRect.snapAngle === true` or the shift-key will snap rotation
 
 After an element's position, size, or rotation are adjusted a `change` event is triggered on the element.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-editable> adds handles to an absolutely positioned element to move, resize and rotate it, with optional grid and angle snapping." }*/
 import { elements, vars, withAttributes } from 'tosijs';
 import { icons } from './icons.js';
 import { trackDrag } from './track-drag.js';

package/dist/filter-builder.js

@@ -143,7 +143,7 @@ interface FilterMaker {
 }
 ```
 */
-/*{ "parent": "Form Components" }*/
+/*{ "parent": "Form Components", "description": "<tosi-filter> builds array filter functions from a Finder-style query editor, with extensible filter types and a state you can save as JSON." }*/
 import { Component as WebComponent, elements, withAttributes, } from 'tosijs';
 import { icons } from './icons.js';
 import { tosiSelect } from './select.js';

package/dist/float.js

@@ -90,7 +90,7 @@ moment it opened. A float with no anchor still reacts to any scroll outside itse
 To prevent dragging for an interior element (e.g. if you want a floating palette with buttons or input fields)
 just add the `no-drag` class to an element or its container.
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-float> is a minimally styled floating element that can be dragged, and that hides, stays or is removed when the window resizes." }*/
 import { elements, withAttributes } from 'tosijs';
 import { trackDrag, bringToFront } from './track-drag.js';
 const { slot } = elements;

package/dist/form.js

@@ -401,7 +401,7 @@ preview.querySelector('.set-values-btn').addEventListener('click', () => {
 })
 ```
 */
-/*{ "parent": "Form Components" }*/
+/*{ "parent": "Form Components", "description": "<tosi-form> and <tosi-field> build forms with native client-side validation and a submit callback that receives the form's values." }*/
 import { Component as XinComponent, elements, varDefault, withAttributes, } from 'tosijs';
 import { colorInput } from './color-input.js';
 const { form, slot, tosiSlot, label, input, span } = elements;

package/dist/header.js

@@ -87,7 +87,7 @@ preview.append(
 }
 ```
 */
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "<tosi-header> is a flex header bar; compose it with elastic() and spacer() to place a title, links and menus where you want them." }*/
 import { Component, elements, varDefault } from 'tosijs';
 import { icons } from './icons.js';
 const { a } = elements;

package/dist/highlight-block.js

@@ -1,4 +1,4 @@
-/*{ "parent": "Documentation System", "order": 70 }*/
+/*{ "parent": "Documentation System", "order": 70, "description": "<tosi-highlight> syntax-highlights code that arrives at runtime, such as a fetched snippet or a chat message, without loading a code editor." }*/
 /*#
 # highlight-block
 

package/dist/icon-svg.js

@@ -1,4 +1,4 @@
-/*{ "parent": "icons", "order": 20 }*/
+/*{ "parent": "icons", "order": 20, "description": "iconSvg() returns an icon's SVG markup as a string and iconNames() lists them, with no DOM, for build scripts, server templates and ePubs." }*/
 /*#
 # `iconSvg` — icon markup without a DOM
 

package/dist/icons.js

@@ -1,4 +1,4 @@
-/*{ "parent": "Components" }*/
+/*{ "parent": "Components", "description": "SVG icons as element creators (icons.chevronDown()), themeable with CSS variables, with a small language for composing new icons from old." }*/
 /*#
 # icons