@threadlabs/looma 0.35.0 → 0.35.1

package/docs/README.md

@@ -17,7 +17,7 @@ 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.
+Use the tool versions accepted by Looma's optional peer dependencies (Markupress 0.8.5 or newer on the supported 0.8 line). 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:
 
@@ -46,6 +46,8 @@ The generated values follow rules. Small and large control heights follow a rati
 
 Choose a coordinated palette to change related paper, ink and action seeds together without changing geometry or motion. Palette seeds remain available for precise edits; the light/dark range previews and resolved values explain readability adjustments.
 
+The customizer uses Starting point, Palette and Material as its controls sidebar, with documentation navigation left out of this workspace. Detailed type, size and motion controls, example selection and exports open when needed.
+
 The main customizer offers Material and Palette presets. **Refine material & light** opens a focused view with a movable light source, real component samples and bounded surface controls. **Refine palette** opens the coordinated light/dark ranges and their four color seeds. Both views edit the same theme as the main customizer. Returning to the overview, navigating to a component, or reloading keeps the result.
 
 A refined preset keeps its name with “customized” beside it. **Restore material preset** resets only material and light; **Restore palette preset** resets only the palette. These family choices are recorded in the recipe's optional `presets` mapping. The `values` mapping remains the complete source of the generated theme; a preset is a named combination of those values.

package/docs/card.html

@@ -1,3 +1,4 @@
+<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">
 <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">
@@ -23,7 +24,7 @@
     <div class="preview"><iframe $ref="frame" from:title="$title" from:src="$src" sandbox="allow-scripts" from:loading="$loading" width="100%" height="208"></iframe></div>
     <section $if="$reference" class="example-code"><h4>Code</h4><slot name="code"></slot></section>
     <div $if="$resizable" class="preview-width">      <ui-form-field><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></div>
-    <div $if="not $reference" class="body">
+    <div $if="not $reference" class="body"><ui-stack gap="xs">
       <div class="meta"><span>{$category}</span><code>{$nativeRoot}</code></div>
       <h3><a from:href="$href">{$title}</a></h3>
       <p class="description">{$description}</p>
@@ -31,7 +32,7 @@
       <p class="example-caption" $if="$exampleTitle">{$exampleTitle}</p>
 
       <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>
+    </ui-stack></div>
   </article>
   <style>
     /* The existing documentation catalog card, shared by the directory, reference and customizer. */
@@ -65,13 +66,13 @@
     footer { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; }
     .preview-width { padding: var(--ui-space-4) !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 { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; margin: 0 !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); }
+    .description { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); line-height: var(--ui-line-height); }
+    .owner { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); overflow-wrap: anywhere; }
+    .example-caption { margin: 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/catalog-view.mjs

@@ -6,6 +6,7 @@ export function catalogResource(groups) {
 <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">
+<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.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>`;
+<ui-stack gap="xl"><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></ui-stack></template>`;
 }

package/docs/catalog.json

@@ -443,7 +443,7 @@
   ],
   "schemaVersion": 1,
   "package": "@threadlabs/looma",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "groups": [
     {
       "id": "layout",
@@ -17970,7 +17970,7 @@
         {
           "name": "snap",
           "property": "snap",
-          "description": "Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel scrolls freely.",
+          "description": "Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel scrolls freely. Wrap a component item in a plain element when snapping: the wrapper receives snap alignment while the component keeps ownership of its root styles.",
           "type": "keyword",
           "options": [
             "start",
@@ -18003,7 +18003,7 @@
         },
         {
           "name": "snap",
-          "description": "Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel scrolls freely.",
+          "description": "Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel scrolls freely. Wrap a component item in a plain element when snapping: the wrapper receives snap alignment while the component keeps ownership of its root styles.",
           "type": "\"start\" | \"center\"",
           "options": [
             "start",
@@ -18031,8 +18031,8 @@
           "id": "@threadlabs/looma/ui-reel/01-default",
           "name": "01-default",
           "title": "Default",
-          "description": "With no layout properties supplied, Reel uses its base gap, item width, and snap behavior.",
-          "markup": "<ui-reel item-width=\"sm\" aria-label=\"Items\">\n  <ui-card padding=\"sm\">Frodo</ui-card>\n  <ui-card padding=\"sm\">Sam</ui-card>\n  <ui-card padding=\"sm\">Sméagol</ui-card>\n  <ui-card padding=\"sm\">Merry</ui-card>\n</ui-reel>",
+          "description": "Scroll through the office desks. Small fixed-width items overflow the preview and scroll freely.",
+          "markup": "<ui-reel item-width=\"sm\" aria-label=\"Fellowship office desks\">\n  <div><ui-card padding=\"sm\">Frodo</ui-card></div>\n  <div><ui-card padding=\"sm\">Sam</ui-card></div>\n  <div><ui-card padding=\"sm\">Sméagol</ui-card></div>\n  <div><ui-card padding=\"sm\">Merry</ui-card></div>\n  <div><ui-card padding=\"sm\">Pippin</ui-card></div>\n  <div><ui-card padding=\"sm\">Gandalf</ui-card></div>\n  <div><ui-card padding=\"sm\">Aragorn</ui-card></div>\n  <div><ui-card padding=\"sm\">Legolas</ui-card></div>\n</ui-reel>",
           "resizable": false,
           "bindings": "",
           "frameworks": {}
@@ -18041,8 +18041,8 @@
           "id": "@threadlabs/looma/ui-reel/02-gap-item-width-and-snap",
           "name": "02-gap-item-width-and-snap",
           "title": "Gap, item width, and snap",
-          "description": "These three properties control spacing, each child's basis, and the scroll snap position.",
-          "markup": "<ui-reel gap=\"m\" item-width=\"md\" snap=\"center\" aria-label=\"Items\">\n  <ui-card padding=\"sm\">Frodo</ui-card>\n  <ui-card padding=\"sm\">Sam</ui-card>\n  <ui-card padding=\"sm\">Sméagol</ui-card>\n  <ui-card padding=\"sm\">Merry</ui-card>\n</ui-reel>",
+          "description": "Scroll the office desks sideways: medium-width items snap to the center when you release.",
+          "markup": "<ui-reel gap=\"m\" item-width=\"md\" snap=\"center\" aria-label=\"Fellowship office desks\">\n  <div><ui-card padding=\"sm\">Frodo</ui-card></div>\n  <div><ui-card padding=\"sm\">Sam</ui-card></div>\n  <div><ui-card padding=\"sm\">Sméagol</ui-card></div>\n  <div><ui-card padding=\"sm\">Merry</ui-card></div>\n  <div><ui-card padding=\"sm\">Pippin</ui-card></div>\n  <div><ui-card padding=\"sm\">Gandalf</ui-card></div>\n  <div><ui-card padding=\"sm\">Aragorn</ui-card></div>\n  <div><ui-card padding=\"sm\">Legolas</ui-card></div>\n</ui-reel>",
           "resizable": false,
           "bindings": "",
           "frameworks": {}
@@ -19473,8 +19473,8 @@
           "id": "@threadlabs/looma/ui-separator/01-default-horizontal",
           "name": "01-default-horizontal",
           "title": "Default horizontal",
-          "description": "With orientation omitted, Separator renders horizontally.",
-          "markup": "<div>\n  <span>Above</span>\n  <ui-separator> </ui-separator>\n  <span>Below</span>\n</div>",
+          "description": "Stack supplies breathing room around a horizontal divider.",
+          "markup": "<ui-stack gap=\"s\">\n  <span>Above</span>\n  <ui-separator> </ui-separator>\n  <span>Below</span>\n</ui-stack>",
           "resizable": false,
           "bindings": "",
           "frameworks": {}
@@ -19484,7 +19484,7 @@
           "name": "02-orientation-vertical",
           "title": "orientation=\"vertical\"",
           "description": "Vertical orientation divides inline content; the parent supplies the row layout and height.",
-          "markup": "<div style=\"display: flex; align-items: center; height: 3rem; gap: 1rem\">\n  <span>Before</span>\n  <ui-separator orientation=\"vertical\"> </ui-separator>\n  <span>After</span>\n</div>",
+          "markup": "<ui-cluster gap=\"s\">\n  <span>Before</span>\n  <ui-separator orientation=\"vertical\"> </ui-separator>\n  <span>After</span>\n</ui-cluster>",
           "resizable": false,
           "bindings": "",
           "frameworks": {}

package/docs/customizer-render.mjs

@@ -32,13 +32,13 @@ export function customizerResource(site, input = defaultRecipe()) {
   };
   const paletteDetails = `<ui-cluster>${['light', 'dark'].map(mode => `<ui-card data-theme="${mode}" padding="sm"><ui-text variant="label">${mode === 'light' ? 'Light' : 'Dark'} range</ui-text><div class="palette-range" role="img" aria-label="${mode} canvas, content and action range"><span class="palette-canvas"></span><span class="palette-content"></span><span class="palette-action"></span></div><ui-text variant="caption">Fellowship office</ui-text></ui-card>`).join('')}</ui-cluster><p data-palette-adjustments role="status" aria-live="polite"></p><ui-disclosure summary="Resolved palette values"><p data-palette-adjustment-details></p></ui-disclosure>`;
   const supplements = {
-    'Colour': `${renderPreset('palette', 'overview')}<p>One coordinated palette generates readable light and dark ranges.</p><ui-button data-action="refine-palette">Refine palette</ui-button>`,
-    'Material': `${renderPreset('material', 'overview')}<p>Shared material and light shape the whole design system.</p><ui-button data-action="refine-material">Refine material & light</ui-button>`,
+    'Colour': `${renderPreset('palette', 'overview')}<ui-text variant="caption">Coordinated light and dark ranges.</ui-text><ui-button data-action="refine-palette">Refine palette</ui-button>`,
+    'Material': `${renderPreset('material', 'overview')}<ui-text variant="caption">Material and light, shared everywhere.</ui-text><ui-button data-action="refine-material">Refine material & light</ui-button>`,
     'Size & spacing': `<ui-cluster><ui-button size="sm">Small</ui-button><ui-button>Medium</ui-button><ui-button size="lg">Large</ui-button></ui-cluster><ui-disclosure summary="How the scale grows"><ui-stack><p>Control size anchors one shared height. Size ratio separates small from large. Density and spacing curve change breathing room independently.</p>${themeFields.filter(item => ['scale-contrast','space-curve'].includes(item.id)).map(renderField).join('')}</ui-stack></ui-disclosure>`,
   };
-  const families = [...new Set(themeFields.map(field => field.family))].map(family => `<ui-disclosure summary="${family}"${family === 'Colour' ? ' open' : ''}><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve'].includes(item.id) && !['Colour','Material'].includes(family)).map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
+  const families = [...new Set(themeFields.map(field => field.family))].filter(family => !['Colour', 'Material'].includes(family)).map(family => `<ui-disclosure summary="${family}"><ui-stack>${themeFields.filter(item => item.family === family && !['scale-contrast', 'space-curve'].includes(item.id)).map(renderField).join('')}${supplements[family] ?? ''}</ui-stack></ui-disclosure>`).join('');
   const refinement = (family, content) => `<section data-refinement-view="${family}" hidden tabindex="-1" aria-label="${family === 'material' ? 'Material and light refinement' : 'Palette refinement'}"><ui-stack gap="xl"><ui-cluster justify="between"><ui-button data-action="back">Back to customization</ui-button><ui-button data-action="restore-${family}">Restore ${family} preset</ui-button></ui-cluster><ui-text variant="heading" as="h2">${family === 'material' ? 'Refine material & light' : 'Refine your palette'}</ui-text><p>These are advanced refinements of the same persistent theme. Every change applies throughout your documentation.</p>${renderPreset(family, 'refinement')}${content}</ui-stack></section>`;
-  const materialView = refinement('material', `<div class="refinement-layout"><ui-stack><ui-light-editor data-light-editor x="${recipe.values['light-x']}" y="${recipe.values['light-y']}" label="Theme light position"><ui-stack gap="sm"><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="standard">Read memo</ui-button></ui-cluster><ui-input label="Office search" placeholder="Search the Fellowship office"></ui-input></ui-stack></ui-light-editor><ui-card variant="elevated" treatment="expressive"><ui-text variant="eyebrow">Fellowship office</ui-text><ui-text variant="heading" as="h3">Second breakfast briefing</ui-text><ui-text>Sam has prepared the agenda. Frodo has the maps, and Sméagol is taking minutes.</ui-text><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="quiet">Read agenda</ui-button></ui-cluster></ui-card><ui-card variant="elevated"><ui-text variant="label">Standard elevated surface</ui-text><ui-text>Subtle lift stays independent from expressive treatment.</ui-text></ui-card></ui-stack><ui-stack><ui-text variant="label">Surface response</ui-text>${themeFields.filter(field => ['finish','edge-light','glow'].includes(field.id)).map(renderField).join('')}<ui-text variant="label">Light source</ui-text>${themeFields.filter(field => ['light-spread','light-strength'].includes(field.id)).map(renderField).join('')}<ui-disclosure summary="Depth, glass and separation"><ui-stack>${themeFields.filter(field => ['outer-depth','inner-depth','glassiness','surface-separation','translucency'].includes(field.id)).map(renderField).join('')}</ui-stack></ui-disclosure></ui-stack></div>`);
+  const materialView = refinement('material', `<div class="refinement-layout"><ui-stack><ui-light-editor data-light-editor x="${recipe.values['light-x']}" y="${recipe.values['light-y']}" label="Theme light position"><ui-stack gap="s"><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="standard">Read memo</ui-button></ui-cluster><ui-input label="Office search" placeholder="Search the Fellowship office"></ui-input></ui-stack></ui-light-editor><ui-card variant="elevated" treatment="expressive"><ui-text variant="eyebrow">Fellowship office</ui-text><ui-text variant="heading" as="h3">Second breakfast briefing</ui-text><ui-text>Sam has prepared the agenda. Frodo has the maps, and Sméagol is taking minutes.</ui-text><ui-cluster><ui-button preset="primary">Join briefing</ui-button><ui-button preset="quiet">Read agenda</ui-button></ui-cluster></ui-card><ui-card variant="elevated"><ui-text variant="label">Standard elevated surface</ui-text><ui-text>Subtle lift stays independent from expressive treatment.</ui-text></ui-card></ui-stack><ui-stack><ui-text variant="label">Surface response</ui-text>${themeFields.filter(field => ['finish','edge-light','glow'].includes(field.id)).map(renderField).join('')}<ui-text variant="label">Light source</ui-text>${themeFields.filter(field => ['light-spread','light-strength'].includes(field.id)).map(renderField).join('')}<ui-disclosure summary="Depth, glass and separation"><ui-stack>${themeFields.filter(field => ['outer-depth','inner-depth','glassiness','surface-separation','translucency'].includes(field.id)).map(renderField).join('')}</ui-stack></ui-disclosure></ui-stack></div>`);
   const paletteView = refinement('palette', `<div class="refinement-layout"><ui-stack>${paletteDetails}<ui-card><ui-text variant="eyebrow">Fellowship office</ui-text><ui-text variant="heading" as="h3">There and back by Friday</ui-text><ui-text>Choose a coordinated range, then refine action, paper and ink. Readable roles follow automatically in both modes.</ui-text><ui-cluster><ui-button preset="primary">Share route</ui-button><ui-button preset="standard">Save draft</ui-button></ui-cluster></ui-card></ui-stack><ui-stack>${themeFields.filter(field => field.family === 'Colour').map(renderField).join('')}</ui-stack></div>`);
   const options = site.catalog.groups.map(group => `<optgroup label="${escape(group.label)}">${examples.filter(example => example.category === group.id).map(example => `<option value="${escape(example.id)}" data-description="${escape(example.category + ' · ' + example.tag)}" data-example="${escape(JSON.stringify(example))}" data-search="${escape(`${example.title} ${example.tag} ${example.description} ${example.exampleTitle}`.toLocaleLowerCase())}">${escape(example.title)} · ${escape(example.exampleTitle)}</option>`).join('')}</optgroup>`).join('');
   const links = ['ui-stack','ui-grid','ui-cluster','ui-form-field','ui-input','ui-select','ui-color-picker','ui-button','ui-disclosure','ui-textarea','ui-number-input','ui-slider','ui-curve-editor','ui-card','ui-text','ui-light-editor','ui-combobox'].map(tag => `<link rel="component" href="@threadlabs/looma/components/${tag}/${tag}.html">`).join('\n');
@@ -46,19 +46,21 @@ export function customizerResource(site, input = defaultRecipe()) {
   <state name="cards" type="list" value="${escape(JSON.stringify(initial))}"><prop type="object">${cardFields.map(name => `<prop name="${name}" required type="${name === 'resizable' ? 'boolean' : 'string'}"></prop>`).join('')}</prop></state>
   </defs>
   <div data-looma-customizer data-recipe="${escape(JSON.stringify(recipe))}" data-base="${escape(site.base)}" data-mode="${site.config.local ? 'local' : 'public'}" data-revision="${escape(site.config.revision ?? '')}">
-  <ui-stack gap="xl"><p>Shape your design system through shared decisions. These are the actual examples from the component documentation. Changes apply throughout your documentation and are remembered in this browser until reset. Save to repository writes the theme to your project; downloads let you use it elsewhere.</p>
-  <p role="status" aria-live="polite" data-message>Your theme is remembered in this browser. Repository files change only when you save.</p>
+  <ui-stack gap="l"><ui-text>Choose a starting point, refine shared decisions, and see them on real documentation examples.</ui-text>
+  <ui-text variant="caption" role="status" aria-live="polite" data-message>Changes are remembered across the documentation.</ui-text>
   ${materialView}${paletteView}
   <div class="customizer-layout" data-customizer-overview>
-  <aside><ui-stack><ui-form-field><label slot="label" for="theme-start">Starting point</label><ui-select id="theme-start" data-preset value="${startingPointFor(recipe)}"><option value="custom" disabled>Your theme</option>${Object.entries(startingPointLabels).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}</ui-select></ui-form-field>
-  ${families}
-  <ui-cluster><ui-button data-action="css" variant="solid">Download CSS</ui-button><ui-button data-action="recipe">Download recipe</ui-button><ui-button data-action="import">Import recipe</ui-button><ui-button data-action="reset" variant="ghost">Reset changes</ui-button></ui-cluster>
+  <aside aria-label="Theme controls"><ui-stack><ui-form-field><label slot="label" for="theme-start">Starting point</label><ui-select id="theme-start" data-preset value="${startingPointFor(recipe)}"><option value="custom" disabled>Your theme</option>${Object.entries(startingPointLabels).map(([id,label]) => `<option value="${id}">${label}</option>`).join('')}</ui-select></ui-form-field>
+  ${supplements.Colour}${supplements.Material}
+  <ui-disclosure summary="Type, size & motion"><ui-stack>${families}</ui-stack></ui-disclosure>
+  <ui-button data-action="reset" variant="ghost">Reset changes</ui-button>
+  <ui-disclosure summary="Export & save"><ui-stack><ui-cluster><ui-button data-action="css" variant="solid">Download CSS</ui-button><ui-button data-action="recipe">Download recipe</ui-button><ui-button data-action="import">Import recipe</ui-button></ui-cluster>
   <input type="file" accept="application/json,.json" hidden data-recipe-file>
   <ui-button data-action="save" variant="solid" hidden>Save to repository</ui-button>
   <ui-disclosure summary="Use your theme"><p>Every export includes light and dark. Leave data-theme off the page to follow system preference, or set it to light or dark on the page or a section. <a href="${escape(site.base)}design-system/">Installation and mode guidance</a></p></ui-disclosure>
-  <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure>
+  <ui-disclosure summary="Theme CSS"><ui-textarea data-css readonly rows="12" aria-label="Generated theme CSS" value="${escape(themeCSS(recipe))}"></ui-textarea></ui-disclosure></ui-stack></ui-disclosure>
   </ui-stack></aside>
-  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Find components and examples</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><p role="status" aria-live="polite" data-example-count></p><ui-combobox id="example-choice" data-add-example label="Choose a component example" placeholder="Search buttons, fields, dialogs…" disclosure clearable>${options}</ui-combobox><ui-button data-action="add" disabled>Add to preview</ui-button>
+  <section class="examples"><ui-stack><ui-form-field><label slot="label" for="example-query">Filter previews</label><ui-input id="example-query" type="search" data-example-query placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-text variant="caption" role="status" aria-live="polite" data-example-count></ui-text><ui-disclosure summary="Add an example"><ui-stack><ui-combobox id="example-choice" data-add-example label="Choose a component example" placeholder="Search buttons, fields, dialogs…" disclosure clearable>${options}</ui-combobox><ui-button data-action="add" disabled>Add to preview</ui-button></ui-stack></ui-disclosure>
   <ui-grid columns="2" min="sm"><section $each="card of $cards" $key="$card.id"><looma-example-card ${cardFields.filter(name => name !== 'id').map(name => `from:${name.replace(/[A-Z]/g, letter => '-' + letter.toLowerCase())}="$card.${name}"`).join(' ')} from:identity="$card.id" loading="eager" removable></looma-example-card></section></ui-grid>
   <noscript>Enable JavaScript to edit the theme. The component reference and example previews remain available.</noscript>
   </ui-stack></section></div></ui-stack></div>

package/docs/customizer.js

@@ -71,10 +71,13 @@ export function connect(host) {
   };
   const filterExamples = () => {
     const words = root.querySelector('[data-example-query]').value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
-    const options = [...root.querySelectorAll('[data-add-example] option')];
-    for (const card of root.querySelectorAll('[data-example-card]')) card.closest('section').hidden = !words.every(word => card.textContent.toLocaleLowerCase().includes(word) || card.dataset.componentCard.includes(word));
-    const matches = options.filter(option => words.every(word => option.dataset.search.includes(word))).length;
-    root.querySelector('[data-example-count]').textContent = matches ? `${matches} matching examples` : 'No examples match. Try another name or purpose.';
+    let visible = 0;
+    for (const card of root.querySelectorAll('[data-example-card]')) {
+      const matches = words.every(word => card.textContent.toLocaleLowerCase().includes(word) || card.dataset.componentCard.includes(word));
+      card.closest('section').hidden = !matches;
+      if (matches) visible++;
+    }
+    root.querySelector('[data-example-count]').textContent = visible ? `${visible} example${visible === 1 ? '' : 's'} in preview` : 'No previews match. Clear the filter or add another example.';
     componentRegistry.update(root.querySelector('[data-action="add"]'), { disabled: !selectedExample || host.state.cards.some(item => item.id === selectedExample) });
   };
   const refinedRecipe = values => {

package/docs/site.mjs

@@ -120,11 +120,12 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   }
   const gallery = combined.groups.map(group => {
     const components = combined.components.filter(c => c.group === group.id && !c.navigationParent);
-    return components.length ? `<section data-catalog-group="${escapeHtml(group.id)}">\n\n## ${escapeHtml(group.label)}\n\n<ui-grid columns="3" min="sm">${components.map(component => `<div data-category="${escapeHtml(component.group)}" data-catalog-search="${escapeHtml(`${component.tag} ${component.title} ${component.description}`)}">${cardMarkup(component.examples[0], base, component)}</div>`).join('')}</ui-grid>\n\n</section>` : '';
+    // A standalone opening tag makes this a Markdown HTML block, keeping native card wrappers inside Grid.
+    return components.length ? `<section data-catalog-group="${escapeHtml(group.id)}">\n\n## ${escapeHtml(group.label)}\n\n<ui-grid columns="3" min="sm">\n${components.map(component => `<div data-category="${escapeHtml(component.group)}" data-catalog-search="${escapeHtml(`${component.tag} ${component.title} ${component.description}`)}">${cardMarkup(component.examples[0], base, component)}</div>`).join('\n')}\n</ui-grid>\n\n</section>` : '';
   }).join('\n\n');
   await write(path.join(content, 'components/index.md'), `---\ntitle: Components\n---\n\n# Components\n\nExplore the live examples that also power your theme customizer.\n\n<link rel="component" href="${relativeHref(path.join(content, 'components/index.md'), card)}">\n<link rel="component" href="@threadlabs/looma/components/ui-grid/ui-grid.html">\n<link rel="component" href="${relativeHref(path.join(content, 'components/index.md'), path.join(generated, 'catalog-view.html'))}">\n\n<looma-catalog>\n\n${gallery}\n\n</looma-catalog>\n`);
   await write(path.join(content, 'index.md'), `---\ntitle: ${JSON.stringify(config.title ?? 'Your design system')}\n---\n\n# ${config.title ?? 'Your design system'}\n\nWeave your design system from Looma and your own HTML Next components.\n\n[Explore components](/components/) · [Customize your theme](/customize/)\n`);
-  if (combined.components.some(component => component.group === 'editor')) await write(path.join(content, 'editor.md'), `---\ntitle: Editor\n---\n\n# Editor\n\nWriting tools and editor components, separate from the general component reference.\n\n${combined.components.filter(component => component.group === 'editor' && !component.navigationParent).map(component => `- [${component.title}](${componentPath(component)})`).join('\n')}\n`);
+  if (combined.components.some(component => component.group === 'editor')) await write(path.join(content, 'editor.md'), `---\ntitle: Editor\nsidebar: false\n---\n\n# Editor\n\nWriting tools and editor components, separate from the general component reference.\n\n${combined.components.filter(component => component.group === 'editor' && !component.navigationParent).map(component => `- [${component.title}](${componentPath(component)})`).join('\n')}\n`);
   await write(path.join(content, 'design-system.md'), await readFile(own('README.md'), 'utf8'));
   if (config.content) {
     const authored = path.resolve(root, config.content);
@@ -143,7 +144,7 @@ export async function prepareDocumentation({ root, config = {}, catalog }) {
   const customizer = path.join(generated, 'customizer.html');
   await write(customizer, customizerResource({ catalog: combined, config, base }, config.recipe));
   const customizerPage = path.join(content, 'customize.md');
-  await write(customizerPage, `---\ntitle: Customize\n---\n\n# Weave your design system\n\n<link rel="component" href="${relativeHref(customizerPage, customizer)}">\n<looma-customizer></looma-customizer>\n`);
+  await write(customizerPage, `---\ntitle: Customize\nsidebar: false\noutline: false\nprevious: false\nnext: false\n---\n\n# Weave your design system\n\n<link rel="component" href="${relativeHref(customizerPage, customizer)}">\n<looma-customizer></looma-customizer>\n`);
   await write(path.join(generated, 'catalog.json'), JSON.stringify(combined));
   const redirects = {};
   for (const component of combined.components) {

package/docs/theme.mjs

@@ -227,6 +227,8 @@ export function deriveTheme(input, { mode } = {}) {
   tokens['--ui-selection-text'] = tokens['--ui-accent-subtle-text'];
   tokens['--ui-selection-border'] = mix(tokens['--ui-accent'], tokens['--ui-surface-raised'], .2);
   tokens['--ui-control-surface'] = tokens['--ui-surface-raised'];
+  // A hint is quieter than body copy; resolve it against its field, not every tinted content surface.
+  tokens['--ui-control-placeholder'] = readableColour(mix(tokens['--ui-text'], tokens['--ui-control-surface'], .5), [tokens['--ui-control-surface']], 4.5, ink);
   tokens['--ui-control-border'] = readableColour(mix(tokens['--ui-text'], tokens['--ui-surface-raised'], .43), readingSurfaces, 3, ink);
   tokens['--ui-control-border-hover'] = tokens['--ui-control-border'];
   tokens['--ui-border-strong'] = tokens['--ui-control-border'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadlabs/looma",
-  "version": "0.35.0",
+  "version": "0.35.1",
   "type": "module",
   "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
   "license": "MIT",
@@ -127,7 +127,7 @@
     "@tiptap/pm": ">=2 <3",
     "@tiptap/vue-3": ">=2 <3",
     "vue": "^3.5.43",
-    "markupress": "^0.8.4",
+    "markupress": "^0.8.5",
     "@nextwebwg/htmlkit": "1.0.0-alpha.69",
     "vite": "^8.3.4"
   },

package/styles/ui-tabs.css

@@ -59,10 +59,9 @@
       max-inline-size: 100%;
       /* Tabs that do not fit scroll sideways rather than wrapping or squeezing. */
       overflow-x: auto;
-      /* overflow-x: auto would make the block axis scrollable too; a sideways swipe must not scroll the
-         strip or the page vertically. */
+      /* Contain sideways overscroll without trapping vertical page scrolling. */
       overflow-y: hidden;
-      overscroll-behavior: contain;
+      overscroll-behavior-inline: contain;
       scrollbar-width: thin;
       border-block-end: var(--ui-border-width) solid var(--ui-border-divider);
     }

package/styles/ui-tooltip.css

@@ -204,7 +204,8 @@
       border-inline-end-width: var(--ui-border-width);
       border-block-end-width: var(--ui-border-width);
       border-end-end-radius: var(--ui-border-width);
-      transform: rotate(45deg) scaleX(1.25) scaleY(0.85);
+      /* Stretch in screen axes after rotation so both arrow shoulders stay level. */
+      transform: scale(1.25, 0.85) rotate(45deg);
     }
 
     :scope:where([data-component~="ui-tooltip"])[data-ui-actual-placement="bottom"] .surface:where(:not([data-component], [data-slotted]))::after {

package/tokens.css

@@ -251,7 +251,7 @@
     --ui-control-surface: var(--ui-surface);
     --ui-control-surface-disabled: var(--ui-surface-muted);
     --ui-control-border-hover: color-mix(in oklab, var(--ui-text) 50%, var(--ui-surface));
-    --ui-control-placeholder: var(--ui-text-secondary);
+    --ui-control-placeholder: color-mix(in oklab, var(--ui-text) 58%, var(--ui-control-surface));
     --ui-control-focus: var(--ui-focus-ring);
     /* Derived from the ring, not a near-white tint, so the halo shows on any surface. */
     --ui-control-focus-halo: color-mix(in srgb, var(--ui-focus-ring) 24%, transparent);

package/vue/UiReel.vue

@@ -40,7 +40,7 @@ const propValidityContract = {
       required: false,
       target: { attribute: 'snap' },
       description:
-        'Snaps scrolling to items: start comes to rest with an item\'s start edge at the reel\'s start, and center with an item centred in the reel. Unset, the reel\n      scrolls freely.',
+        'Snaps scrolling to items: start comes to rest with an item\'s start edge at the reel\'s start, and center with an item centred in the reel. Unset, the reel\n      scrolls freely. Wrap a component item in a plain element when snapping: the wrapper receives snap alignment while the component keeps ownership of its\n      root styles.',
       values: ['start', 'center'],
     },
   },

package/vue/UiTabs.vue

@@ -395,10 +395,9 @@ useComponentHost(() => import('../components/ui-tabs/ui-tabs.js'), {
     max-inline-size: 100%;
     /* Tabs that do not fit scroll sideways rather than wrapping or squeezing. */
     overflow-x: auto;
-    /* overflow-x: auto would make the block axis scrollable too; a sideways swipe must not scroll the
-       strip or the page vertically. */
+    /* Contain sideways overscroll without trapping vertical page scrolling. */
     overflow-y: hidden;
-    overscroll-behavior: contain;
+    overscroll-behavior-inline: contain;
     scrollbar-width: thin;
     border-block-end: var(--ui-border-width) solid var(--ui-border-divider);
   }

package/vue/UiTooltip.vue

@@ -580,7 +580,8 @@ useComponentHost(() => import('../components/ui-tooltip/ui-tooltip.js'), {
     border-inline-end-width: var(--ui-border-width);
     border-block-end-width: var(--ui-border-width);
     border-end-end-radius: var(--ui-border-width);
-    transform: rotate(45deg) scaleX(1.25) scaleY(0.85);
+    /* Stretch in screen axes after rotation so both arrow shoulders stay level. */
+    transform: scale(1.25, 0.85) rotate(45deg);
   }
 
   :global(:scope[data-ui-actual-placement="bottom"] .surface:where([data-hn-ui-tooltip])::after) {

package/vue/chunks/UiReel.js

@@ -58,7 +58,7 @@ var UiReel_default = /*#__PURE__*/ _plugin_vue_export_helper_default(/* @__PURE_
 				},
 				required: false,
 				target: { attribute: "snap" },
-				description: "Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel\n      scrolls freely.",
+				description: "Snaps scrolling to items: start comes to rest with an item's start edge at the reel's start, and center with an item centred in the reel. Unset, the reel\n      scrolls freely. Wrap a component item in a plain element when snapping: the wrapper receives snap alignment while the component keeps ownership of its\n      root styles.",
 				values: ["start", "center"]
 			}
 		} };
@@ -128,6 +128,6 @@ var UiReel_default = /*#__PURE__*/ _plugin_vue_export_helper_default(/* @__PURE_
 			}]]);
 		};
 	}
-}), [["__scopeId", "data-v-ace220e1"]]);
+}), [["__scopeId", "data-v-fbdba47c"]]);
 //#endregion
 export { UiReel_default as t };

package/vue/chunks/UiTabs.js

@@ -329,6 +329,6 @@ var UiTabs_default = /*#__PURE__*/ _plugin_vue_export_helper_default(/* @__PURE_
 			}]]);
 		};
 	}
-}), [["__scopeId", "data-v-f1705832"]]);
+}), [["__scopeId", "data-v-502b66c9"]]);
 //#endregion
 export { UiTabs_default as t };

package/vue/chunks/UiTooltip.js

@@ -292,6 +292,6 @@ var UiTooltip_default = /*#__PURE__*/ _plugin_vue_export_helper_default(/* @__PU
 			}]]);
 		};
 	}
-}), [["__scopeId", "data-v-4cc4aab6"]]);
+}), [["__scopeId", "data-v-21fb192b"]]);
 //#endregion
 export { UiTooltip_default as t };

package/vue/components.css

@@ -2726,7 +2726,8 @@ input[type="range"] {
     border-inline-end-width: var(--ui-border-width);
     border-block-end-width: var(--ui-border-width);
     border-end-end-radius: var(--ui-border-width);
-    transform: rotate(45deg) scaleX(1.25) scaleY(0.85);
+    /* Stretch in screen axes after rotation so both arrow shoulders stay level. */
+    transform: scale(1.25, 0.85) rotate(45deg);
 }
 :scope[data-ui-actual-placement="bottom"] .surface:where([data-hn-ui-tooltip])::after {
     inset-block-start: calc(
@@ -10934,10 +10935,9 @@ input:where([data-hn-ui-switch]),input:where([data-hn-ui-switch])::after {
     max-inline-size: 100%;
     /* Tabs that do not fit scroll sideways rather than wrapping or squeezing. */
     overflow-x: auto;
-    /* overflow-x: auto would make the block axis scrollable too; a sideways swipe must not scroll the
-       strip or the page vertically. */
+    /* Contain sideways overscroll without trapping vertical page scrolling. */
     overflow-y: hidden;
-    overscroll-behavior: contain;
+    overscroll-behavior-inline: contain;
     scrollbar-width: thin;
     border-block-end: var(--ui-border-width) solid var(--ui-border-divider);
 }
@@ -16093,7 +16093,8 @@ html[data-ui-input-modality="touch"]
       border-inline-end-width: var(--ui-border-width);
       border-block-end-width: var(--ui-border-width);
       border-end-end-radius: var(--ui-border-width);
-      transform: rotate(45deg) scaleX(1.25) scaleY(0.85);
+      /* Stretch in screen axes after rotation so both arrow shoulders stay level. */
+      transform: scale(1.25, 0.85) rotate(45deg);
     }
 
     :scope:where([data-component~="ui-tooltip"])[data-ui-actual-placement="bottom"] .surface:where(:not([data-component], [data-slotted]))::after {