@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 +38 -16
- package/docs/catalog.json +1 -1
- package/docs/render.mjs +16 -5
- package/package.json +4 -3
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.
|
|
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.
|
|
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
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
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
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 {
|
|
3
|
+
import { parse } from 'expressmark';
|
|
4
|
+
import { renderHtml } from 'expressmark/render';
|
|
5
|
+
import { parseFragment } from 'parse5';
|
|
4
6
|
|
|
5
|
-
const
|
|
6
|
-
|
|
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', ' ');
|
|
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>${
|
|
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"
|
|
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.
|
|
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.
|
|
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.
|
|
131
|
+
"markupress": ">=0.12.0 <1",
|
|
131
132
|
"@threadlabs/markupkit": ">=0.2.0 <1",
|
|
132
133
|
"vite": ">=7.2.7 <9"
|
|
133
134
|
},
|