@threadlabs/looma 0.33.1 → 0.35.0

package/docs/README.md

@@ -40,16 +40,68 @@ pnpm exec looma-docs preview
 
 ## 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 authoring model groups shared decisions 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.
+The generated values follow rules. Small and large control heights follow a ratio around the shared control size. Spacing follows an independent curve: linear at 1, increasingly curved toward 2, with stable endpoints so the largest gaps do not grow without bound. 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.
+
+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 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.
+
+Number controls accept arithmetic such as `42px / 1.2` or `150ms * 2`, calculate on entry and show the result. Unit changes preserve the quantity. Sliders include exact entry, and curve handles support dragging and arrow keys alongside numeric coordinates.
 
 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.
+Changes apply throughout the documentation and remain in this browser across navigation and reload until reset. Repository files change only when you save locally. Starting points update the shell and all selected cards. Reset returns to the repository baseline. Invalid input keeps the last valid preview and explains which decision needs attention.
+
+Text offers body, display, heading, label, caption, eyebrow and code roles. Choose a heading's document level with `as` independently from its visual role. Button and IconButton keep appearance and tone independent, with four optional shortcuts: primary (solid accent), standard (solid neutral), quiet (ghost neutral) and destructive (solid danger). A named preset takes precedence over the separate choices; `preset="none"` preserves their existing defaults.
+
+## Describe material and light
+
+Light position is relative to each surface: horizontal and vertical positions run from 0 to 1, with 0.5, 0 at top centre. Drag the source, use its arrow keys (Shift moves faster), or enter exact percentages. Home returns it to top centre. Spread runs from a concentrated spot to broad illumination; strength controls its intensity. The source influences reflections, illuminated edges and the direction of depth shadows throughout the theme.
+
+Finish controls how strongly a material catches a reflection, from matte to polished. Edge light catches its boundary; glow spills softly beyond it. Glassiness and surface separation govern the decorative material around floating content, scaled by popup purpose and rendered size. The content plane stays opaque. Reflection peaks are bounded for readable text, and reduced transparency disables the ornamental reflection and glow as well as backdrop blur.
+
+Card keeps surface structure and decorative treatment independent:
+
+```html
+<ui-card variant="elevated">Standard subtle lift</ui-card>
+<ui-card variant="elevated" treatment="expressive">Lift with the theme's material</ui-card>
+<ui-card treatment="expressive">Material treatment without added lift</ui-card>
+```
+
+`treatment="standard"` is the default. Expressive treatment follows the theme: a matte theme stays opaque, while Bookish can use a light-catching frame. Card tones change colors without changing corners or adding a stripe. Solid neutral actions use quiet mode-appropriate surface fills with readable text, instead of inverted text-color fills.
+
+To add a sample to the preview, search **Choose a component example**, select a result, then choose **Add to preview**. Existing component cards still link to the full reference.
+
+## Use light, dark, or both
+
+Every generated theme includes a coordinated light/dark pair. The type, geometry and motion decisions stay shared. Both palettes derive readable text, outlines, focus and action states from the same identity; the generator may adjust requested color seeds to maintain contrast.
+
+Load the generated CSS after Looma's tokens and palette. Choose how it runs:
+
+- **System preference:** leave `data-theme` off the document root. The CSS follows the operating system automatically.
+- **Light only:** set `<html data-theme="light">`.
+- **Dark only:** set `<html data-theme="dark">`.
+- **User switch:** set the root attribute to `light` or `dark`, and remove it to return to system preference. Persist that choice in your application if desired.
+
+Fixed-mode applications still receive both palettes. A mode boundary applies to its descendants, so a dark panel can contain a light subsection without changing the page or its siblings:
+
+```html
+<section data-theme="dark">
+  <h2>After-hours Fellowship office</h2>
+  <div data-theme="light">Sam's daylight reading area</div>
+</section>
+```
+
+Use the public semantic color properties inside those regions. A floating surface moved elsewhere in the DOM must retain its originating mode boundary; Looma's isolated documentation previews receive their card's mode automatically.
 
 ## Add your components
 
+Build your design-system components in HTML Next. Their definitions, description attributes, controllers and HTML examples are the source for the generated documentation and customizer cards. Use Looma’s public semantic properties to make your components respond to the same theme.
+
 Opt into source directories in `looma.docs.json`:
 
 ```json
@@ -64,7 +116,7 @@ Opt into source directories in `looma.docs.json`:
 }
 ```
 
-`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.
+`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. Local web fonts referenced by override CSS are embedded in the documentation's theme stylesheet so isolated examples render the same fonts on static hosts. Load your chosen web fonts in the consuming application; downloaded theme CSS selects their font families.
 
 A resource can use any valid HTML Next component tag:
 
@@ -101,7 +153,9 @@ description: Sam has finished the morning checklist.
 
 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.
+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 make arbitrary components respond to Looma's tokens.
+
+The planned HTML Next-only distribution will use the HTML Next Vite plugin or converter for Vue consumption. Author components and documentation examples in HTML Next; framework conversion belongs in the consuming application. The current package still includes Vue exports while that packaging migration is pending.
 
 ## Combine installed catalogs
 

package/docs/card.html

@@ -7,6 +7,7 @@
     <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="reference" type="boolean" default="false">Use the spacious full-reference example presentation.</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>
@@ -18,14 +19,17 @@
     <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">
+    <header $if="$reference" class="example-heading"><slot name="heading"><h3>{$exampleTitle}</h3><p>{$description}</p></slot></header>
     <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">
+    <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 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>
@@ -46,10 +50,20 @@
     :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); }
+    :host([reference]):hover { transform: none; border-color: var(--ui-border); box-shadow: var(--ui-shadow-sm); }
+    .example-heading { padding: var(--ui-space-5) !important; border-block-end: var(--ui-border-width) solid var(--ui-border); }
+    .example-code { padding: var(--ui-space-5) !important; border-block-start: var(--ui-border-width) solid var(--ui-border); }
+    .example-code h4 { margin: 0 0 var(--ui-space-3) !important; font-size: var(--ui-font-size-md); }
+    .example-heading p { margin: var(--ui-space-2) 0 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); }
+    :host([reference]) .preview { min-block-size: 11rem; display: grid !important; align-items: center !important; border-block-end: 0; }
+    :host([reference]) iframe { min-block-size: 11rem; }
+    :host([reference][category="overlay"]) iframe { min-block-size: 26rem; }
+    :host([reference]) .preview::before { display: none; }
     .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; }
+    .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 code { padding: 0 !important; background: transparent; color: inherit; text-transform: none; }

package/docs/card.js

@@ -1,3 +1,4 @@
+import { documentationTheme, themeEvent } from './theme-session.mjs';
 /** Only theme data and measured height cross the opaque preview boundary. */
 export function connect(host) {
   const frame = host.refs.frame;
@@ -5,8 +6,17 @@ export function connect(host) {
   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 }, '*');
+  let theme = documentationTheme(view)?.css ?? '';
+  const documentTheme = () => { theme = documentationTheme(view)?.css ?? ''; send(); };
+  const preference = view.matchMedia('(prefers-color-scheme: dark)');
+  const send = () => {
+    const scheme = view.getComputedStyle(host.element).colorScheme;
+    const mode = scheme === 'dark' || (scheme.includes('dark') && scheme.includes('light') && preference.matches) ? 'dark' : 'light';
+    frame.contentWindow?.postMessage({ type: 'looma-theme', css: theme, mode, reference: Boolean(host.props.reference.value) }, '*');
+  };
+  // Observe only this card's ancestors: an opposite-mode boundary belongs to its own subtree.
+  const modes = new view.MutationObserver(send);
+  for (let ancestor = host.element; ancestor; ancestor = ancestor.parentElement) modes.observe(ancestor, { attributes: true, attributeFilter: ['data-theme', 'style', 'class'] });
   const message = event => {
     if (event.source !== frame.contentWindow) return;
     if (event.data?.type === 'looma-preview-ready') send();
@@ -21,12 +31,17 @@ export function connect(host) {
   width?.addEventListener('input', resize);
   remove?.addEventListener('click', removeCard);
   view.addEventListener('message', message);
+  view.addEventListener(themeEvent, documentTheme);
   frame.addEventListener('load', send);
+  preference.addEventListener('change', send);
   return () => {
     host.element.removeEventListener('looma-theme-preview', update);
     width?.removeEventListener('input', resize);
     remove?.removeEventListener('click', removeCard);
     view.removeEventListener('message', message);
+    view.removeEventListener(themeEvent, documentTheme);
     frame.removeEventListener('load', send);
+    preference.removeEventListener('change', send);
+    modes.disconnect();
   };
 }