@threadlabs/looma 0.33.0 → 0.33.1

package/README.md

@@ -58,3 +58,18 @@ stylesheet is the only stylesheet to include. Without a build, link components o
 Components read design tokens (`--ui-*` custom properties) from `tokens.css` and a theme
 (`theme-light.css`, `theme-dark.css`, `theme-high-contrast.css`), and each exposes its own
 `--ui-<component>-*` properties. Set them on the component or any ancestor.
+
+
+## Weave your design system
+
+The package includes the documentation generator and theme customizer used by Looma's public site. Browse real component cards, generate a theme from shared semantic decisions, and document your own HTML Next components beside Looma's.
+
+Install the optional documentation tools, then initialize your project:
+
+```sh
+pnpm add -D markupress @nextwebwg/htmlkit@1.0.0-alpha.69 vite
+pnpm exec looma-docs init
+pnpm exec looma-docs dev
+```
+
+The local editor saves `looma.theme.json` and generated `looma.theme.css`; import that CSS in your application. Static builds offer CSS and recipe downloads. See the [design-system guide](https://threadlabs.studio/looma/design-system/) for configuration, discovery, saving and recovery. Programmatic tooling is available through `@threadlabs/looma/docs`.

package/bin/looma-docs.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+// Keep the command linkable before the workspace build creates docs/.
+import '../docs/cli.mjs';

package/docs/README.md

@@ -0,0 +1,116 @@
+---
+title: Weave your design system
+---
+
+# Weave your design system
+
+Looma ships the documentation generator and theme customizer used by its public site. Run it in your project to browse Looma and your own HTML Next components as one design system. The customizer uses the same authored component cards as the reference.
+
+## Start a local design system
+
+In a project with a `package.json`, install Looma and its documentation tools:
+
+```sh
+pnpm add @threadlabs/looma @nextwebwg/html-next@1.0.0-alpha.69
+pnpm add -D markupress @nextwebwg/htmlkit@1.0.0-alpha.69 vite
+pnpm exec looma-docs init --title "The Fellowship"
+pnpm exec looma-docs dev
+```
+
+Use the tool versions accepted by Looma's optional peer dependencies. Regular component imports do not load the documentation server. Vue and Tiptap remain optional; install them when your own authored documentation mounts the Vue editor.
+
+Initialization creates three project-owned files:
+
+| File | Purpose |
+| --- | --- |
+| `looma.docs.json` | Documentation title, content, discovery roots and theme paths. |
+| `looma.theme.json` | Editable semantic decisions. |
+| `looma.theme.css` | Generated theme, including the shared derivation rules. |
+
+Import `./looma.theme.css` after Looma's tokens and palette in your application's entry point. The initializer prints that import; it leaves existing application files intact. Commit the configuration, recipe and CSS. Add `.looma/` to your project's ignore file: it contains disposable generated documentation and tooling files.
+
+Open the local address printed by `dev`, choose **Customize**, and save your theme. Saving updates those shared theme files and rebuilds the documentation. Your application consumes the same CSS import. A static or public site instead offers CSS and recipe downloads.
+
+```sh
+pnpm exec looma-docs build
+pnpm exec looma-docs preview
+```
+
+`build` produces a static HTMLKit site in the configured output directory. `preview` serves that output without a repository writer. All commands accept `--root`; `dev` and `preview` also accept `--port`.
+
+## Change the rule, keep the family consistent
+
+The authoring model has twenty shared decisions, grouped as Colour, Type, Size & spacing, Material and Motion. The controls expose shared intent: a control size, spaciousness, corners, inner and outer depth, and response pace.
+
+The generated values follow rules. Small and large control heights follow a ratio around the shared control size. Spacing follows an independent power curve: linear growth at 1, quadratic at 2. Depth generates families of shadows; it does not add motion amplitude. Fields and buttons with the same size setting use the same box height, while content can still grow when it needs more room.
+
+Lengths retain their CSS units, such as `rem`; times retain `ms` or `s`. The downloaded CSS includes the canonical shared recipe as well as your inputs. Import a downloaded JSON recipe to continue editing it. Keep hand-written CSS in a separate overrides file so regenerating the theme does not replace it.
+
+Changes remain a preview until saved. Starting points update all selected cards. Reset returns to the loaded recipe. Invalid input keeps the last valid preview and explains which decision needs attention.
+
+## Add your components
+
+Opt into source directories in `looma.docs.json`:
+
+```json
+{
+  "title": "The Fellowship",
+  "base": "/",
+  "outDir": ".looma/site",
+  "content": "docs",
+  "theme": { "recipe": "looma.theme.json", "css": "looma.theme.css" },
+  "components": [{ "directory": "app/components", "packageName": "fellowship-ui" }],
+  "overrides": ["styles/design-system-overrides.css"]
+}
+```
+
+`content` and `overrides` are optional. Create files you configure before building. Markdown guidance supplements the generated reference; it cannot replace an API page. Relative component and asset dependencies keep their original project locations, and code examples remain literal.
+
+A resource can use any valid HTML Next component tag:
+
+```html
+<template component="office-status">
+  <defs>
+    <prop name="label" type="string" default="Ready">The team's current status.</prop>
+  </defs>
+  <p>{$label}<slot></slot></p>
+</template>
+```
+
+Place a `docs.json` beside it to join a shared category:
+
+```json
+{
+  "title": "Office status",
+  "description": "A status for the Fellowship office.",
+  "group": "display"
+}
+```
+
+Looma's category IDs are listed in its published catalog. Components without a category appear in **Project components**. A discovery root can declare additional `groups` as `{ "id": "…", "label": "…" }` entries. The top-level `categories` mapping explicitly maps category IDs when combining catalogs.
+
+Put authored examples in an `examples/` directory beside the resource. Each `.html` example starts with a metadata comment:
+
+```html
+<!--
+title: Ready for second breakfast
+description: Sam has finished the morning checklist.
+-->
+<office-status label="Ready for second breakfast"></office-status>
+```
+
+The example appears in both the reference and the customizer's selection list. Optional `.behavior.js` or `.behavior.ts` companions export a default setup function receiving the example root; return a cleanup function when needed. Add `preview: resizable` to expose the shared card's width control. Framework-specific `.snippet.html` and `.vue` companions provide literal source views.
+
+Discovery reads definitions and descriptions without executing their controllers. New resources under a selected root appear after the local server rebuilds. External components keep their own contracts and supported token hooks; discovery does not invent a Vue adapter or make arbitrary components respond to Looma's tokens.
+
+## Combine installed catalogs
+
+A library can publish the versioned catalog shape exposed by `@threadlabs/looma/docs/catalog.json`. Add package exports or relative JSON files under `catalogs` in the configuration. Component identities are package-qualified; duplicate tags, conflicting categories and missing compound parents fail with ownership information instead of silently replacing a component.
+
+Use the `@threadlabs/looma/docs` entrypoint for programmatic discovery, catalog merging, theme validation, and build/dev/preview integration. Its TypeScript definitions describe the configuration and catalog interfaces. The browser card renderer, catalog data and compiled example companions ship in the package.
+
+## Saving and recovery
+
+The local editor writes only the configured recipe and CSS inside the project. It rejects symlink paths, generated or dependency directories, cross-origin save requests and stale file revisions. A competing edit leaves your unsaved preview in place; reload and reconcile it before saving again. Examples run in isolated frames and receive theme CSS, never the local editing capability.
+
+The writer stages complete files, serializes saves with a project lock, and rolls back the recipe if replacing the CSS fails. If a process stops during a save or build, close the old editor before removing its `.looma/theme-write.lock` or `.looma/docs-build.lock`; restart and save the loaded recipe to regenerate a consistent pair. Change the server base, output directory or theme-file paths by restarting `dev`.

package/docs/card.html

@@ -0,0 +1,63 @@
+<link rel="component" href="@threadlabs/looma/components/ui-form-field/ui-form-field.html">
+<link rel="component" href="@threadlabs/looma/components/ui-input/ui-input.html">
+<link rel="component" href="@threadlabs/looma/components/ui-button/ui-button.html">
+<template component="looma-example-card" module="./card.js">
+  <defs>
+    <prop name="identity" type="string" default="">Stable catalog example identity.</prop>
+    <prop name="title" type="string" default="Example">The documented component name.</prop>
+    <prop name="description" type="string" default="">The component's authored description.</prop>
+    <prop name="exampleTitle" type="string" default="">The selected authored example.</prop>
+    <prop name="src" type="string" default="">The compiled isolated example page.</prop>
+    <prop name="resizable" type="boolean" default="false">Expose a width control for responsive examples.</prop>
+    <prop name="category" type="string" default="forms">The shared category identity.</prop>
+    <prop name="tag" type="string" default="">The component's authored tag.</prop>
+    <prop name="packageName" type="string" default="">The package that owns this component.</prop>
+    <prop name="nativeRoot" type="string" default="">The component's semantic native root.</prop>
+    <prop name="href" type="string" default="">The component reference page.</prop>
+    <prop name="removable" type="boolean" default="false">Offer removal when this card is selected in the customizer.</prop>
+    <prop name="loading" type="keyword" values="lazy, eager" default="lazy">Load visible catalog cards lazily; selected customizer cards eagerly.</prop>
+  </defs>
+  <article from:data-example-card="$identity" from:data-component-card="$tag" from:data-category="$category">
+    <div class="preview"><iframe $ref="frame" from:title="$title" from:src="$src" sandbox="allow-scripts" from:loading="$loading" width="100%" height="208"></iframe></div>
+    <div class="body">
+      <div class="meta"><span>{$category}</span><code>{$nativeRoot}</code></div>
+      <h3><a from:href="$href">{$title}</a></h3>
+      <p class="description">{$description}</p>
+      <p class="owner" $if="$packageName">{$packageName}</p>
+      <p class="example-caption" $if="$exampleTitle">{$exampleTitle}</p>
+      <ui-form-field $if="$resizable"><label slot="label">Preview width</label><span slot="help">Explore the example at a narrower width.</span><ui-input $ref="width" type="number" min="240" max="1600" value="720" aria-label="Preview width in pixels" size="sm"></ui-input></ui-form-field>
+      <footer><ui-button $if="$href" as="a" from:href="$href" variant="link" size="sm">View component</ui-button><ui-button $if="$removable" $ref="remove" variant="ghost" size="sm">Remove</ui-button><slot name="actions"></slot></footer>
+    </div>
+  </article>
+  <style>
+    /* The existing documentation catalog card, shared by the directory, reference and customizer. */
+    :host {
+      --_card-accent: var(--ui-accent);
+      position: relative;
+      overflow: hidden;
+      background: var(--ui-surface-raised);
+      border: var(--ui-border-width) solid var(--ui-border);
+      border-radius: var(--ui-radius-lg);
+      box-shadow: var(--ui-shadow-sm);
+      transition: border-color var(--ui-motion-fast) var(--ui-motion-ease), box-shadow var(--ui-motion-fast) var(--ui-motion-ease), transform var(--ui-motion-fast) var(--ui-motion-ease);
+    }
+    :host([category="display"]) { --_card-accent: var(--ui-success); }
+    :host([category="overlay"]) { --_card-accent: var(--ui-danger); }
+    :host([category="layout"]) { --_card-accent: var(--ui-info); }
+    :host([category="editor"]) { --_card-accent: var(--ui-warning); }
+    :host:hover { border-color: color-mix(in srgb, var(--_card-accent) 45%, var(--ui-border)); box-shadow: var(--ui-shadow-md); transform: translateY(-2px); }
+    .preview { position: relative; min-block-size: 13rem; overflow: hidden; border-block-end: var(--ui-border-width) solid var(--ui-border); background: color-mix(in srgb, var(--_card-accent) 5%, var(--ui-surface)); }
+    .preview::before { position: absolute; inset-block-start: 0; inset-inline-start: 0; inline-size: 3.5rem; block-size: 3px; background: var(--_card-accent); content: ""; z-index: 1; }
+    iframe { display: block !important; max-inline-size: 100%; border: 0; }
+    footer { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; }
+    .body { padding: var(--ui-space-5) !important; }
+    .meta { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; margin-block-end: var(--ui-space-2) !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); font-weight: var(--ui-font-bold); letter-spacing: .09em; text-transform: uppercase; }
+    .meta code { padding: 0 !important; background: transparent; color: inherit; text-transform: none; }
+    h3 { margin: 0 !important; padding: 0 !important; font-size: var(--ui-font-size-lg); letter-spacing: -.035em; }
+    h3 a { color: var(--ui-text); text-decoration: none; }
+    .description { margin: var(--ui-space-2) 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); line-height: var(--ui-line-height); }
+    .owner { margin: var(--ui-space-2) 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); overflow-wrap: anywhere; }
+    .example-caption { margin: var(--ui-space-2) 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); }
+    @media (prefers-reduced-motion: reduce) { :host { transition: none; } :host:hover { transform: none; } }
+  </style>
+</template>

package/docs/card.js

@@ -0,0 +1,32 @@
+/** Only theme data and measured height cross the opaque preview boundary. */
+export function connect(host) {
+  const frame = host.refs.frame;
+  const width = host.refs.width;
+  const remove = host.refs.remove;
+  const removeCard = () => host.element.dispatchEvent(new CustomEvent("looma-example-remove", { bubbles: true, detail: { id: host.props.identity.value } }));
+  const view = frame.ownerDocument.defaultView;
+  let theme = '';
+  const send = () => frame.contentWindow?.postMessage({ type: 'looma-theme', css: theme }, '*');
+  const message = event => {
+    if (event.source !== frame.contentWindow) return;
+    if (event.data?.type === 'looma-preview-ready') send();
+    if (event.data?.type === 'looma-preview-height' && Number.isFinite(event.data.height)) frame.height = String(Math.max(120, Math.min(2400, Math.ceil(event.data.height))));
+  };
+  const update = event => { theme = event.detail.css; send(); };
+  const resize = event => {
+    const value = Number(event.detail?.value ?? event.target.value);
+    if (value >= 240 && value <= 1600) frame.width = String(value);
+  };
+  host.element.addEventListener('looma-theme-preview', update);
+  width?.addEventListener('input', resize);
+  remove?.addEventListener('click', removeCard);
+  view.addEventListener('message', message);
+  frame.addEventListener('load', send);
+  return () => {
+    host.element.removeEventListener('looma-theme-preview', update);
+    width?.removeEventListener('input', resize);
+    remove?.removeEventListener('click', removeCard);
+    view.removeEventListener('message', message);
+    frame.removeEventListener('load', send);
+  };
+}

package/docs/catalog-view.js

@@ -0,0 +1,18 @@
+/** Native catalog entries own their visibility; component previews keep their own layout. */
+export function connect(host) {
+  const { query, category, count } = host.refs;
+  const groups = [...host.element.querySelectorAll('[data-catalog-group]')];
+  const items = [...host.element.querySelectorAll('[data-catalog-search]')];
+  const filter = () => {
+    const words = query.value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+    let visible = 0;
+    for (const item of items) {
+      item.hidden = Boolean(category.value && item.dataset.category !== category.value) || !words.every(word => item.dataset.catalogSearch.toLocaleLowerCase().includes(word));
+      if (!item.hidden) visible++;
+    }
+    for (const group of groups) group.hidden = ![...group.querySelectorAll('[data-catalog-search]')].some(item => !item.hidden);
+    count.textContent = visible === 0 ? 'No components match. Try another name or category.' : `${visible} component${visible === 1 ? '' : 's'}`;
+  };
+  query.addEventListener('input', filter); category.addEventListener('change', filter); filter();
+  return () => { query.removeEventListener('input', filter); category.removeEventListener('change', filter); };
+}

package/docs/catalog-view.mjs

@@ -0,0 +1,11 @@
+import { escapeHtml as escape } from './catalog.mjs';
+
+/** Catalog filtering wraps the same server-rendered documentation cards. */
+export function catalogResource(groups) {
+  return `<link rel="component" href="@threadlabs/looma/components/ui-form-field/ui-form-field.html">
+<link rel="component" href="@threadlabs/looma/components/ui-input/ui-input.html">
+<link rel="component" href="@threadlabs/looma/components/ui-select/ui-select.html">
+<link rel="component" href="@threadlabs/looma/components/ui-cluster/ui-cluster.html">
+<template component="looma-catalog" module="./catalog-view.js"><defs></defs>
+<div><ui-cluster align="end"><ui-form-field><label slot="label" for="catalog-query">Find a component</label><ui-input id="catalog-query" $ref="query" type="search" placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-form-field><label slot="label" for="catalog-category">Category</label><ui-select id="catalog-category" $ref="category"><option value="">All categories</option>${groups.map(group => `<option value="${escape(group.id)}">${escape(group.label)}</option>`).join('')}</ui-select></ui-form-field></ui-cluster><p $ref="count" role="status" aria-live="polite"></p><slot></slot></div></template>`;
+}