tosijs-ui 1.5.24 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # tosijs-ui
 
-<!--{ "pin": "top" }-->
+<!--{ "pin": "top", "headTitle": "tosijs-ui — robust, dependency-free web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
 
 [ui.tosijs.net live demo](https://ui.tosijs.net) | [tosijs](https://tosijs.net) | [discord](https://discord.gg/ramJ9rgky5) | [github](https://github.com/tonioloewald/tosijs-ui#readme) | [npm](https://www.npmjs.com/package/tosijs-ui)
 
@@ -122,7 +122,9 @@ as globals which contain all the things exported by `tosijs` and `tosijs-ui`.
 </script>
 ```
 
-[Click here to see a simple iife demo](https://ui.tosijs.net/iife.html)
+The entire [live documentation site](https://ui.tosijs.net) is built with the iife
+bundle — every page is static HTML that loads `iife.js` and hydrates, so it doubles
+as a working iife example (view source on any page).
 
 ## custom-elements
 

package/bin/docs.ts

@@ -1,233 +1,9 @@
-/*#
-# docs
-
-Utility for extracting documentation from markdown files and inline comments in source code.
-
-> `docs.ts` is intended to be run directly using `bun`. You can transpile it to javascript if you
-want to run it using node.
-
-This is used by the `doc-browser` component to build searchable, navigable documentation
-from your project's source files.
-
-## Usage
-
-    import { extractDocs } from 'docs'
-
-    extractDocs({
-      paths: ['src', 'README.md'],
-      ignore: ['node_modules', 'dist', 'build']
-      path: 'public/docs.json'
-    })
-
-## API
-
-### `extractDocs(options)`
-
-Scans directories for markdown files and source code comments.
-
-**Options:**
-- `paths`: Array of directory paths or file paths to scan
-- `ignore`: Array of directory names to ignore (default: ['node_modules', 'dist'])
-- `output`: if provided, path to write json result.
-
-**Returns:** Array of `Doc` objects
-
-### `Doc` object structure
-
-    {
-      text: string,        // Markdown content
-      title: string,       // First heading or filename
-      filename: string,    // Just the filename
-      path: string,        // Full file path
-      pin?: 'top' | 'bottom'  // Optional pinning for sort order
-    }
-
-## Documentation Format
-
-### Markdown files
-
-Any `.md` file will be included in its entirety.
-
-### Source code comments
-
-Multi-line comments that start with `/*#` will be extracted as markdown:
-
-    /*#
-    # My Component
-
-    This is documentation for my component.
-
-    ```html
-    <my-component></my-component>
-    ```
-    ```js
-    console.log('hello world')
-    ```
-    ```css
-    my-componet {
-      color: blue
-    }
-    ```
-    *‎/
-
-    export class MyComponent extends Component {
-      // implementation
-    }
-    ...
-
-The [doc-browser](/?doc-browser.ts) will render the output as a test-bed project with documentation and live examples.
-
-### Metadata
-
-You can include JSON metadata in comments to control sorting:
-
-html:
-    <!--{ "pin": "bottom" }-->
-
-ts, js, css:
-    /*{ "pin": "bottom" }*‎/
-
-This will pin the document to the top or bottom of the navigation list.
-*/
-/*{ "pin": "bottom" }*/
-
-// TODO CLI options
-
-import * as fs from 'fs'
-import * as path from 'path'
-
-export interface Doc {
-  text: string
-  title: string
-  filename: string
-  path: string
-  pin?: 'top' | 'bottom'
-  hidden?: boolean
-}
-
-export interface ExtractDocsOptions {
-  paths: string[]
-  ignore?: string[]
-  output?: string
-}
-
-const TRIM_REGEX = /^#+ |`/g
-
-function metadata(content: string, filePath: string): Partial<Doc> {
-  const source = content.match(/<\!\-\-(\{.*\})\-\->|\/\*(\{.*\})\*\//)
-  let data: Partial<Doc> = {}
-  if (source) {
-    try {
-      data = JSON.parse(source[1] || source[2])
-    } catch (e) {
-      console.error('bad metadata in doc', filePath)
-    }
-  }
-  return data
-}
-
-function pinnedSort(a: Doc, b: Doc): number {
-  const aKey =
-    (a.pin === 'top' ? 'A' : a.pin === 'bottom' ? 'Z' : 'M') +
-    a.title.toLocaleLowerCase()
-  const bKey =
-    (b.pin === 'top' ? 'A' : b.pin === 'bottom' ? 'Z' : 'M') +
-    b.title.toLocaleLowerCase()
-  return aKey > bKey ? 1 : bKey > aKey ? -1 : 0
-}
-
-function findMarkdownFiles(paths: string[], ignore: string[]): Doc[] {
-  const markdownFiles: Doc[] = []
-
-  function traverseDirectory(dir: string, ignore: string[]) {
-    console.log(dir)
-    const files = fs.readdirSync(dir)
-    const baseName = path.basename(dir)
-
-    if (ignore.includes(baseName)) {
-      return
-    }
-
-    files.forEach((file) => {
-      const filePath = path.join(dir, file)
-      let stats
-
-      try {
-        stats = fs.statSync(filePath)
-      } catch (err) {
-        return
-      }
-
-      if (stats.isDirectory()) {
-        traverseDirectory(filePath, ignore)
-      } else if (path.extname(file) === '.md') {
-        const content = fs.readFileSync(filePath, 'utf8')
-        markdownFiles.push({
-          text: content,
-          title: content.split('\n')[0].replace(TRIM_REGEX, ''),
-          filename: file,
-          path: filePath,
-          ...metadata(content, filePath),
-        })
-      } else if (['.ts', '.js', '.css'].includes(path.extname(file))) {
-        const content = fs.readFileSync(filePath, 'utf8')
-        const docs = content.match(/\/\*#[\s\S]+?\*\//g) || []
-        if (docs.length) {
-          const markdown = docs.map((s) => s.substring(3, s.length - 2).trim())
-          const text = markdown.join('\n\n')
-          markdownFiles.push({
-            text,
-            title: text.split('\n')[0].replace(TRIM_REGEX, ''),
-            filename: file,
-            path: filePath,
-            ...metadata(content, filePath),
-          })
-        }
-      }
-    })
-  }
-
-  paths.forEach((dir) => {
-    try {
-      const stats = fs.statSync(dir)
-      if (stats.isDirectory()) {
-        traverseDirectory(dir, ignore)
-      } else if (stats.isFile()) {
-        const file = path.basename(dir)
-        if (path.extname(file) === '.md') {
-          const content = fs.readFileSync(dir, 'utf8')
-          markdownFiles.push({
-            text: content,
-            title: content.split('\n')[0].replace(TRIM_REGEX, ''),
-            filename: file,
-            path: dir,
-            ...metadata(content, dir),
-          })
-        }
-      }
-    } catch (err) {
-      console.error(`Could not read ${dir}:`, err)
-    }
-  })
-
-  return markdownFiles.sort(pinnedSort)
-}
-
-export function extractDocs(options: ExtractDocsOptions): Doc[] {
-  const {
-    paths,
-    ignore = ['node_modules', 'dist', 'build', 'docs'],
-    output,
-  } = options
-  const docs = findMarkdownFiles(paths, ignore)
-  if (output) {
-    saveDocsJSON(docs, output)
-  }
-  return docs
-}
-
-export function saveDocsJSON(docs: Doc[], outputPath: string): void {
-  const jsonData = JSON.stringify(docs, null, 2)
-  fs.writeFileSync(outputPath, jsonData, 'utf8')
-  console.log(`Documentation saved to ${outputPath}`)
-}
+// Back-compat shim. The doc-extraction implementation now lives in the
+// importable doc-site system at src/doc-system/site/docs.ts (shipped as
+// `tosijs-ui/site`). This path is kept (package.json#files lists /bin/docs.ts)
+// so existing `import { extractDocs } from 'tosijs-ui/bin/docs'` consumers and
+// the `bun bin/docs.ts` CLI keep working.
+//
+// No `/*#` doc block here on purpose: the documented copy lives in the real
+// module, so the doc extractor surfaces it once (avoiding a slug collision).
+export * from '../src/doc-system/site/docs'

package/dist/ab-test.js

@@ -75,6 +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" }*/
 import { Component } from 'tosijs';
 const abTestConditions = {};
 export class AbTest extends Component {

package/dist/babylon-3d.js

@@ -177,6 +177,7 @@ be used to load `.glb` files.
 
 `<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" }*/
 import { Component as WebComponent, elements } from 'tosijs';
 import { scriptTag } from './via-tag';
 import { icons, svg2DataUrl } from './icons';

package/dist/bodymovin-player.js

@@ -101,6 +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" }*/
 import { Component as WebComponent } from 'tosijs';
 import { scriptTag } from './via-tag';
 export class BodymovinPlayer extends WebComponent {

package/dist/carousel.js

@@ -55,6 +55,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" }*/
 import { Component as WebComponent, elements, vars, } from 'tosijs';
 import { icons } from './icons';
 const { button, slot, div } = elements;

package/dist/code-editor.js

@@ -20,6 +20,7 @@ The `<tosi-code>` element has an `editor` property that gives you its ACE editor
 and an `ace` property that returns the `ace` module, giving you complete access to the
 [Ace API](https://ace.c9.io/api/index.html).
 */
+/*{ "parent": "Components" }*/
 import { Component as WebComponent } from 'tosijs';
 import { scriptTag } from './via-tag';
 const ACE_BASE_URL = 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.23.2/';

package/dist/color-input.js

@@ -27,6 +27,7 @@ colorInput.addEventListener('change', () => {
 
 <tosi-css-var-editor element-selector="tosi-color"></tosi-css-var-editor>
 */
+/*{ "parent": "Form Components" }*/
 import { Component, elements, Color, vars, } from 'tosijs';
 const { input } = elements;
 const defaultColor = Color.fromCss('#8888');

package/dist/data-table.js

@@ -509,6 +509,7 @@ You'll need to make sure your localized strings include:
 
 As well as any column names you want localized.
 */
+/*{ "parent": "Components" }*/
 import { Component as WebComponent, elements, vars, varDefault, tosiValue, getListItem, getListBinding, tosi, } from 'tosijs';
 import { trackDrag } from './track-drag';
 import { icons } from './icons';

package/dist/dialog.js

@@ -117,6 +117,7 @@ preview.append(
 ```
 
 */
+/*{ "parent": "Components" }*/
 import { Component, elements, on, vars, varDefault } from 'tosijs';
 import { findHighestZ } from './track-drag';
 const { dialog, button, header, footer, tosiSlot, h3, p, label, input, div } = elements;

package/dist/doc-browser.d.ts

@@ -34,6 +34,20 @@ export interface ProjectLinks {
     cdn?: string;
     [key: string]: string | undefined;
 }
+/** A configurable link for the header bar or the overflow menu. */
+export interface LinkItem {
+    href: string;
+    label: string;
+    /** optional icon name (from `icons`); falls back to the text label if unknown */
+    icon?: string;
+}
+/**
+ * How the doc browser maps docs to URLs.
+ * - 'query' (default, legacy): single-page app, links are `?filename`.
+ * - 'path': clean per-page URLs (`/slug/`), for the static pre-rendered site
+ *   driven by <tosi-doc-system>. Requires a real page to exist at each path.
+ */
+export type DocRoutingMode = 'query' | 'path';
 export interface DocBrowserOptions {
     docs: Doc[];
     context?: Record<string, any>;
@@ -41,5 +55,19 @@ export interface DocBrowserOptions {
     projectLinks?: ProjectLinks;
     navSize?: number;
     minSize?: number;
+    routing?: DocRoutingMode;
+    /**
+     * 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
+     * as its text label). `projectLinks` is still used for the logo and view-source.
+     */
+    navbarLinks?: LinkItem[];
+    /**
+     * Pre-rendered content for the landing doc to ADOPT in place (true hydration).
+     * When provided, the current page's already-rendered markdown is left untouched
+     * — only live examples are wired up — instead of being re-rendered from text.
+     * Used by <tosi-doc-system>. Subsequent navigation renders from doc text.
+     */
+    contentElement?: HTMLElement;
 }
 export declare function createDocBrowser(options: DocBrowserOptions): HTMLElement;