@threadlabs/looma 0.44.0 → 0.44.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/README.md CHANGED
@@ -12,20 +12,27 @@ In a project with a `package.json`, install Looma and its documentation tools:
12
12
 
13
13
  ```sh
14
14
  pnpm add @threadlabs/looma @nextwebwg/html-next@1.0.0-alpha.69
15
- pnpm add -D 'markupress@>=0.10.3 <1' '@threadlabs/markupkit@>=0.2.0 <1' vite
15
+ pnpm add -D 'markupress@>=0.12.0 <1' '@threadlabs/markupkit@>=0.2.0 <1' vite
16
16
  pnpm exec looma-docs init --title "The Fellowship"
17
17
  pnpm exec looma-docs dev
18
18
  ```
19
19
 
20
- Use the tool versions accepted by Looma's optional peer dependencies. Markupress 0.10.3 and later compatible 0.x releases supply section navigation with category overview links, a full-height sidebar, the shared Looma site header, mobile home-page navigation, and one appearance button that cycles Automatic, Light and Dark. 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.
20
+ Use the tool versions accepted by Looma's optional peer dependencies. Markupress 0.12.0 and later compatible 0.x releases render authored documentation with Expressmark’s standard syntax and supply section navigation with category overview links, a full-height sidebar, the shared Looma site header, mobile home-page navigation, and one appearance button that cycles Automatic, Light and Dark. 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.
21
21
 
22
22
  Initialization creates three project-owned files:
23
23
 
24
- | File | Purpose |
25
- | --- | --- |
26
- | `looma.docs.json` | Documentation title, content, discovery roots and theme paths. |
27
- | `looma.theme.json` | Editable semantic decisions. |
28
- | `looma.theme.css` | Generated theme, including the shared derivation rules. |
24
+ ::: table
25
+
26
+ - File: `looma.docs.json`
27
+ Purpose: Documentation title, content, discovery roots and theme paths.
28
+
29
+ - File: `looma.theme.json`
30
+ Purpose: Editable semantic decisions.
31
+
32
+ - File: `looma.theme.css`
33
+ Purpose: Generated theme, including the shared derivation rules.
34
+
35
+ :::
29
36
 
30
37
  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.
31
38
 
@@ -137,15 +144,30 @@ locally saved CSS. System font uses the operating system and needs no download.
137
144
 
138
145
  The [public token reference](https://github.com/threadlabs-studio/looma/blob/main/apps/docs-next/docs/03.%28Foundations%29/tokens.md#optional-semantic-theme-recipe) lists defaults, customizer ranges, dependencies and derived outputs for every family. The recipe's `values` keys map to public CSS properties or generator decisions as follows. Values are strings; omitted keys take defaults and unknown keys are rejected.
139
146
 
140
- | Family | Recipe decisions → CSS properties |
141
- | --- | --- |
142
- | Base colors | `action` → `--ui-accent`; `canvas` → `--ui-surface`; `surface` → `--ui-surface-raised`; `text` → `--ui-text` |
143
- | Palette generation (recipe only) | `warmth`, `color-intensity`, `palette-relationship`, optional `secondary-action`/`tertiary-action`, `neutral-source`, `neutral-strength`, `neutral-border-contrast`, `status-chroma`, each status’s `*-source`, and `selection-accent`/`focus-accent`/`link-accent`; compiled into resolved color roles, with no matching CSS custom properties |
144
- | Type | `body-font` → `--ui-font-sans`; `display-font` → `--ui-font-display`; `text-size` → `--ui-font-size`; `label-size` → `--ui-field-label-font-size` (`inherit` follows body); `text-weight` → `--ui-font-medium` |
145
- | Rhythm & spacing | `rhythm` → `--ui-rhythm`; `control-roominess` → `--ui-control-roominess`; `spacing` → `--ui-spacing`; `scale-contrast` → `--ui-scale-ratio`; `space-curve` → `--ui-space-curve`; `corner-roundness` → `--ui-radius-md`; `line-weight` → `--ui-border-width` |
146
- | Depth and transmission | `outer-depth` → `--ui-outer-depth`; `inner-depth` → `--ui-inner-depth`; `glassiness` → `--ui-glassiness`; `surface-separation` → `--ui-surface-separation`; `translucency` → `--ui-overlay-translucency` |
147
- | Finish and illumination | `finish` → `--ui-finish`; `edge-light` → `--ui-edge-light`; `glow` → `--ui-glow`; `light-x` → `--ui-light-x`; `light-y` → `--ui-light-y`; `light-spread` → `--ui-light-spread`; `light-strength` → `--ui-light-strength` |
148
- | Motion | `response-time` → `--ui-motion-fast`; `response-curve` → `--ui-motion-ease` |
147
+ ::: table
148
+
149
+ - Family: Base colors
150
+ Recipe decisions → CSS properties: `action` → `--ui-accent`; `canvas` → `--ui-surface`; `surface` → `--ui-surface-raised`; `text` → `--ui-text`
151
+
152
+ - Family: Palette generation (recipe only)
153
+ Recipe decisions → CSS properties: `warmth`, `color-intensity`, `palette-relationship`, optional `secondary-action`/`tertiary-action`, `neutral-source`, `neutral-strength`, `neutral-border-contrast`, `status-chroma`, each status’s `*-source`, and `selection-accent`/`focus-accent`/`link-accent`; compiled into resolved color roles, with no matching CSS custom properties
154
+
155
+ - Family: Type
156
+ Recipe decisions → CSS properties: `body-font` → `--ui-font-sans`; `display-font` → `--ui-font-display`; `text-size` → `--ui-font-size`; `label-size` → `--ui-field-label-font-size` (`inherit` follows body); `text-weight` → `--ui-font-medium`
157
+
158
+ - Family: Rhythm & spacing
159
+ Recipe decisions → CSS properties: `rhythm` → `--ui-rhythm`; `control-roominess` → `--ui-control-roominess`; `spacing` → `--ui-spacing`; `scale-contrast` → `--ui-scale-ratio`; `space-curve` → `--ui-space-curve`; `corner-roundness` → `--ui-radius-md`; `line-weight` → `--ui-border-width`
160
+
161
+ - Family: Depth and transmission
162
+ Recipe decisions → CSS properties: `outer-depth` → `--ui-outer-depth`; `inner-depth` → `--ui-inner-depth`; `glassiness` → `--ui-glassiness`; `surface-separation` → `--ui-surface-separation`; `translucency` → `--ui-overlay-translucency`
163
+
164
+ - Family: Finish and illumination
165
+ Recipe decisions → CSS properties: `finish` → `--ui-finish`; `edge-light` → `--ui-edge-light`; `glow` → `--ui-glow`; `light-x` → `--ui-light-x`; `light-y` → `--ui-light-y`; `light-spread` → `--ui-light-spread`; `light-strength` → `--ui-light-strength`
166
+
167
+ - Family: Motion
168
+ Recipe decisions → CSS properties: `response-time` → `--ui-motion-fast`; `response-curve` → `--ui-motion-ease`
169
+
170
+ :::
149
171
 
150
172
  Palette generation decisions exist only in the JSON recipe; edit it and regenerate to change resolved colors. Geometry, material and motion properties feed the included CSS recipe. `--ui-control-size` remains a derived public height role: author numeric roominess (default 2.5, range 2–4) instead of an absolute control size. Spacing (default 1, range 0.75–1.5) changes space without changing heights. Base text defaults to `16px` and sets the document root. Type and geometry derive from `1rem` once; the base editor accepts only px. Other relative length inputs preserve their units; editor ranges convert through the chosen root, and generated guards keep the documented pixel bounds. Visible size samples report actual rem/px heights. Set the base on `:root`; opposite-mode boundaries retain that same rem root.
151
173
 
package/docs/catalog.json CHANGED
@@ -463,7 +463,7 @@
463
463
  ],
464
464
  "schemaVersion": 1,
465
465
  "package": "@threadlabs/looma",
466
- "version": "0.44.0",
466
+ "version": "0.44.1",
467
467
  "groups": [
468
468
  {
469
469
  "id": "layout",
package/docs/render.mjs CHANGED
@@ -1,12 +1,23 @@
1
1
  import { createHash } from 'node:crypto';
2
2
  import { escapeHtml as escape } from './catalog.mjs';
3
- import { createLoomaMarkdownIt } from '@threadlabs/looma/markdown/markdown-it';
3
+ import { parse } from 'expressmark';
4
+ import { renderHtml } from 'expressmark/render';
5
+ import { parseFragment } from 'parse5';
4
6
 
5
- const descriptions = createLoomaMarkdownIt().set({ html: false });
6
- export const cardDescription = description => (descriptions.parseInline(description ?? '', {})[0]?.children ?? []).map(token => token.content).join('').split(/(?<=[.!?])\s/)[0];
7
+ const descriptionDocument = description => parse(description ?? '', { syntax: 'standard' });
8
+ // This HTML enters Markdown again. Entities protect rendered text from a second
9
+ // interpretation; existing entities stay intact. Markupress owns final HTML Next escaping.
10
+ const descriptionHtml = description => renderHtml(descriptionDocument(description), { escapeText: html => html.replace(/[!-/:-@[-`{-~]/g, character => character === '&' || character === ';' ? character : `&#${character.codePointAt(0)};`) }).replaceAll('\n', '&#10;');
11
+ function descriptionText(node) {
12
+ if (node.nodeName === '#text') return node.value;
13
+ if (node.tagName === 'img') return node.attrs.find(attribute => attribute.name === 'alt')?.value ?? '';
14
+ if (node.tagName === 'br') return '\n';
15
+ return (node.childNodes ?? []).map(descriptionText).join(node.nodeName === '#document-fragment' ? ' ' : '');
16
+ }
17
+ export const cardDescription = description => descriptionText(parseFragment(renderHtml(descriptionDocument(description)))).split(/(?<=[.!?])\s/)[0];
7
18
 
8
19
  const literal = value => escape(value).replaceAll('{', '\\{');
9
- const code = value => `<code>${literal(value ?? '—')}</code>`;
20
+ const code = value => `<code>${escape(value ?? '—')}</code>`;
10
21
  const table = (head, rows) => `<table><thead><tr>${head.map(h => `<th>${literal(h)}</th>`).join('')}</tr></thead><tbody>${rows.map(row => `<tr>${row.map(value => `<td>${value}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
11
22
  export const exampleKey = id => createHash('sha256').update(id).digest('hex').slice(0, 20);
12
23
  export const componentPath = component => `/${component.group === 'editor' ? 'editor' : 'components'}/${component.navigationParent ?? component.tag}/` + (component.navigationParent ? `#${component.tag}-api` : '');
@@ -119,5 +130,5 @@ export function referencePage(component, catalog, cardResource, base) {
119
130
  return `<ui-tabs slot="code" label="Example syntax" group="syntax" style="--ui-tabs-panel-padding: 0px">${tabs}</ui-tabs>`;
120
131
  };
121
132
  const body = `<div class="looma-reference-examples"><ui-stack gap="xl">${examples.map(example => `<ui-card as="section" variant="subtle" padding="lg">${cardMarkup(example, base, catalog.components.find(c => c.examples.some(e => e.id === example.id)) ?? component, { reference: true, code: codes(example) })}</ui-card>`).join('')}</ui-stack></div>`;
122
- return `---\ntitle: ${JSON.stringify(component.title)}\ndescription: ${JSON.stringify(component.description || `${component.title} component reference.`)}\nid: ${JSON.stringify(component.id)}\n---\n\n# ${escape(component.title)}\n\n<div class="component-description"><p>${descriptions.renderInline(component.description).replaceAll('{', '\\{').replaceAll('\n', '&#10;')}</p></div>\n\n<link rel="component" href="${cardResource}">\n${exampleResources(examples, catalog)}\n<link rel="component" href="${cardResource.replace(/card\.html$/, 'reference.html')}">\n<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">\n<link rel="component" href="@threadlabs/looma/components/ui-tabs/ui-tabs.html">\n<link rel="component" href="@threadlabs/looma/components/ui-disclosure/ui-disclosure.html">\n<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">\n\n<looma-reference>\n\n<div class="looma-reference-tabs"><ui-tabs label="Component reference" style="--ui-tabs-panel-padding: 0px; --ui-tabs-tab-min-block-size: var(--ui-control-size-lg)"><section aria-label="Examples">${body}</section><section aria-label="API"><h2 id="api">API</h2>\n${apiBody(component)}\n${parts.map(part => `<h2 id="${part.tag}-api">${literal(part.title)} API</h2><p>${literal(part.description)}</p>${apiBody(part, part.tag + '-')}`).join('\n')}</section></ui-tabs></div>\n\n</looma-reference>\n`;
133
+ return `---\ntitle: ${JSON.stringify(component.title)}\ndescription: ${JSON.stringify(component.description || `${component.title} component reference.`)}\nid: ${JSON.stringify(component.id)}\n---\n\n# ${escape(component.title)}\n\n<div class="component-description">${descriptionHtml(component.description)}</div>\n\n<link rel="component" href="${cardResource}">\n${exampleResources(examples, catalog)}\n<link rel="component" href="${cardResource.replace(/card\.html$/, 'reference.html')}">\n<link rel="component" href="@threadlabs/looma/components/ui-card/ui-card.html">\n<link rel="component" href="@threadlabs/looma/components/ui-tabs/ui-tabs.html">\n<link rel="component" href="@threadlabs/looma/components/ui-disclosure/ui-disclosure.html">\n<link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">\n\n<looma-reference>\n\n<div class="looma-reference-tabs"><ui-tabs label="Component reference" style="--ui-tabs-panel-padding: 0px; --ui-tabs-tab-min-block-size: var(--ui-control-size-lg)"><section aria-label="Examples">${body}</section><section aria-label="API"><h2 id="api">API</h2>\n${apiBody(component)}\n${parts.map(part => `<h2 id="${part.tag}-api">${literal(part.title)} API</h2><p>${literal(part.description)}</p>${apiBody(part, part.tag + '-')}`).join('\n')}</section></ui-tabs></div>\n\n</looma-reference>\n`;
123
134
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@threadlabs/looma",
3
- "version": "0.44.0",
3
+ "version": "0.44.1",
4
4
  "type": "module",
5
5
  "description": "Looma components as HTML, Vue, and plain DOM, with design tokens.",
6
6
  "license": "MIT",
@@ -119,7 +119,8 @@
119
119
  "lowlight": "^3.3.0",
120
120
  "markdown-it": "14.3.1",
121
121
  "lucide": "~0.554.0",
122
- "expressmark": ">=0.2.0 <1"
122
+ "expressmark": ">=0.2.2 <1",
123
+ "parse5": "^8.0.1"
123
124
  },
124
125
  "peerDependencies": {
125
126
  "@nextwebwg/html-next": "1.0.0-alpha.69",
@@ -127,7 +128,7 @@
127
128
  "@tiptap/pm": ">=2 <3",
128
129
  "@tiptap/vue-3": ">=2 <3",
129
130
  "vue": "^3.5.43",
130
- "markupress": ">=0.10.3 <1",
131
+ "markupress": ">=0.12.0 <1",
131
132
  "@threadlabs/markupkit": ">=0.2.0 <1",
132
133
  "vite": ">=7.2.7 <9"
133
134
  },