@threadlabs/looma 0.51.6 → 0.52.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.
Files changed (374) hide show
  1. package/README.md +4 -4
  2. package/components/shared/overlay.js +7 -2
  3. package/components/ui-breadcrumb-item/ui-breadcrumb-item.html +1 -0
  4. package/components/ui-calendar/ui-calendar.js +11 -7
  5. package/components/ui-date-field/ui-date-field.js +0 -5
  6. package/components/ui-disclosure/ui-disclosure.js +19 -4
  7. package/components/ui-editor-link-form/ui-editor-link-form.js +5 -0
  8. package/components/ui-editor-mention-menu-item/ui-editor-mention-menu-item.html +2 -3
  9. package/components/ui-editor-table-context-menu/ui-editor-table-context-menu.html +10 -1
  10. package/components/ui-file-input/ui-file-input.js +0 -2
  11. package/components/ui-status-message/ui-status-message.html +1 -0
  12. package/components/ui-tabs/ui-tabs.html +1 -0
  13. package/components/ui-tooltip/ui-tooltip.html +11 -32
  14. package/components/ui-wizard/ui-wizard.html +137 -0
  15. package/components/ui-wizard/ui-wizard.js +19 -0
  16. package/dist/index.js +15 -8
  17. package/docs/catalog.json +876 -131
  18. package/editor/components.css +530 -551
  19. package/editor/index.js +72 -47
  20. package/package.json +30 -35
  21. package/styles/ui-action-bar.css +8 -8
  22. package/styles/ui-affordance-scope.css +10 -10
  23. package/styles/ui-avatar-group.css +11 -11
  24. package/styles/ui-avatar.css +14 -14
  25. package/styles/ui-badge.css +67 -67
  26. package/styles/ui-breadcrumb-item.css +10 -10
  27. package/styles/ui-breadcrumbs.css +8 -8
  28. package/styles/ui-button.css +99 -99
  29. package/styles/ui-calendar.css +1 -1
  30. package/styles/ui-callout.css +14 -14
  31. package/styles/ui-card-group.css +11 -11
  32. package/styles/ui-card.css +36 -36
  33. package/styles/ui-checkbox.css +28 -28
  34. package/styles/ui-cluster.css +30 -30
  35. package/styles/ui-color-picker.css +16 -16
  36. package/styles/ui-combobox.css +50 -50
  37. package/styles/ui-compact-content.css +1 -1
  38. package/styles/ui-compact-editor.css +1 -1
  39. package/styles/ui-compact-mark.css +1 -1
  40. package/styles/ui-compact-node.css +1 -1
  41. package/styles/ui-container.css +14 -14
  42. package/styles/ui-context-menu.css +8 -8
  43. package/styles/ui-cover.css +9 -9
  44. package/styles/ui-curve-editor.css +9 -9
  45. package/styles/ui-cycle-button.css +10 -10
  46. package/styles/ui-date-field.css +1 -1
  47. package/styles/ui-date-picker.css +1 -1
  48. package/styles/ui-date-range-picker.css +1 -1
  49. package/styles/ui-description-item.css +8 -8
  50. package/styles/ui-description-list.css +18 -18
  51. package/styles/ui-dialog.css +37 -37
  52. package/styles/ui-disclosure.css +26 -26
  53. package/styles/ui-editable.css +13 -13
  54. package/styles/ui-editor-block-actions.css +1 -1
  55. package/styles/ui-editor-chip-editor.css +1 -1
  56. package/styles/ui-editor-code-language.css +1 -1
  57. package/styles/ui-editor-footnote-editor.css +1 -1
  58. package/styles/ui-editor-formatting-tools.css +1 -1
  59. package/styles/ui-editor-image-toolbar.css +1 -1
  60. package/styles/ui-editor-insert-table-grid.css +9 -9
  61. package/styles/ui-editor-link-card.css +1 -1
  62. package/styles/ui-editor-link-form.css +1 -1
  63. package/styles/ui-editor-mention-menu-item.css +13 -15
  64. package/styles/ui-editor-mention-menu.css +12 -12
  65. package/styles/ui-editor-slash-menu-group.css +7 -7
  66. package/styles/ui-editor-slash-menu-item.css +12 -12
  67. package/styles/ui-editor-slash-menu.css +13 -13
  68. package/styles/ui-editor-surface.css +8 -8
  69. package/styles/ui-editor-table-context-menu.css +19 -15
  70. package/styles/ui-editor-table-overlay.css +15 -15
  71. package/styles/ui-editor-table-toolbar.css +19 -19
  72. package/styles/ui-editor-toolbar.css +16 -16
  73. package/styles/ui-editor.css +1 -1
  74. package/styles/ui-file-input.css +1 -1
  75. package/styles/ui-floating-action-button.css +14 -14
  76. package/styles/ui-form-field.css +9 -9
  77. package/styles/ui-grid.css +19 -19
  78. package/styles/ui-icon-button.css +73 -73
  79. package/styles/ui-icon.css +11 -11
  80. package/styles/ui-image.css +23 -23
  81. package/styles/ui-input-group.css +26 -26
  82. package/styles/ui-input.css +23 -23
  83. package/styles/ui-light-editor.css +15 -15
  84. package/styles/ui-list-item.css +25 -25
  85. package/styles/ui-list.css +16 -16
  86. package/styles/ui-listbox.css +22 -22
  87. package/styles/ui-menu-group.css +7 -7
  88. package/styles/ui-menu-item.css +20 -20
  89. package/styles/ui-menu.css +20 -20
  90. package/styles/ui-meter.css +32 -32
  91. package/styles/ui-nav-item.css +18 -18
  92. package/styles/ui-number-input.css +12 -12
  93. package/styles/ui-page-header.css +10 -10
  94. package/styles/ui-pagination.css +1 -1
  95. package/styles/ui-popover.css +17 -17
  96. package/styles/ui-radio-group.css +10 -10
  97. package/styles/ui-radio.css +25 -25
  98. package/styles/ui-reel.css +21 -21
  99. package/styles/ui-scroll-area.css +20 -20
  100. package/styles/ui-search-result-row.css +16 -16
  101. package/styles/ui-search-shell.css +10 -10
  102. package/styles/ui-section.css +18 -18
  103. package/styles/ui-select.css +22 -22
  104. package/styles/ui-separator.css +12 -12
  105. package/styles/ui-sidebar.css +26 -26
  106. package/styles/ui-site-header.css +65 -65
  107. package/styles/ui-skeleton.css +18 -18
  108. package/styles/ui-slider.css +11 -11
  109. package/styles/ui-spinner.css +9 -9
  110. package/styles/ui-stack.css +22 -22
  111. package/styles/ui-status-message.css +12 -12
  112. package/styles/ui-swatch.css +14 -14
  113. package/styles/ui-switch.css +23 -23
  114. package/styles/ui-switcher.css +20 -20
  115. package/styles/ui-table.css +12 -12
  116. package/styles/ui-tabs.css +18 -17
  117. package/styles/ui-text.css +40 -40
  118. package/styles/ui-textarea.css +21 -21
  119. package/styles/ui-time-field.css +1 -1
  120. package/styles/ui-time-picker.css +1 -1
  121. package/styles/ui-toast-region.css +29 -29
  122. package/styles/ui-toast.css +19 -19
  123. package/styles/ui-tooltip.css +37 -58
  124. package/styles/ui-top-bar.css +8 -8
  125. package/styles/ui-tree-item.css +112 -112
  126. package/styles/ui-tree.css +11 -11
  127. package/styles/ui-wizard.css +162 -0
  128. package/vanilla/UiActionBar.d.ts +1 -1
  129. package/vanilla/UiActionBar.js +2 -2
  130. package/vanilla/UiAffordanceScope.d.ts +1 -1
  131. package/vanilla/UiAffordanceScope.js +2 -2
  132. package/vanilla/UiAvatar.d.ts +1 -1
  133. package/vanilla/UiAvatar.js +2 -2
  134. package/vanilla/UiAvatarGroup.d.ts +1 -1
  135. package/vanilla/UiAvatarGroup.js +2 -2
  136. package/vanilla/UiBadge.d.ts +1 -1
  137. package/vanilla/UiBadge.js +2 -2
  138. package/vanilla/UiBreadcrumbItem.d.ts +1 -1
  139. package/vanilla/UiBreadcrumbItem.js +2 -2
  140. package/vanilla/UiBreadcrumbs.d.ts +1 -1
  141. package/vanilla/UiBreadcrumbs.js +2 -2
  142. package/vanilla/UiButton.d.ts +1 -1
  143. package/vanilla/UiButton.js +5 -5
  144. package/vanilla/UiCalendar.d.ts +1 -1
  145. package/vanilla/UiCalendar.js +10 -10
  146. package/vanilla/UiCallout.d.ts +1 -1
  147. package/vanilla/UiCallout.js +2 -2
  148. package/vanilla/UiCard.d.ts +1 -1
  149. package/vanilla/UiCard.js +5 -5
  150. package/vanilla/UiCardGroup.d.ts +1 -1
  151. package/vanilla/UiCardGroup.js +2 -2
  152. package/vanilla/UiCheckbox.d.ts +1 -1
  153. package/vanilla/UiCheckbox.js +2 -2
  154. package/vanilla/UiCluster.d.ts +1 -1
  155. package/vanilla/UiCluster.js +2 -2
  156. package/vanilla/UiColorPicker.d.ts +1 -1
  157. package/vanilla/UiColorPicker.js +2 -2
  158. package/vanilla/UiCombobox.d.ts +1 -1
  159. package/vanilla/UiCombobox.js +8 -8
  160. package/vanilla/UiCompactContent.d.ts +1 -1
  161. package/vanilla/UiCompactContent.js +4 -4
  162. package/vanilla/UiCompactEditor.d.ts +1 -1
  163. package/vanilla/UiCompactEditor.js +2 -2
  164. package/vanilla/UiCompactMark.d.ts +1 -1
  165. package/vanilla/UiCompactMark.js +5 -5
  166. package/vanilla/UiCompactNode.d.ts +1 -1
  167. package/vanilla/UiCompactNode.js +8 -8
  168. package/vanilla/UiContainer.d.ts +1 -1
  169. package/vanilla/UiContainer.js +2 -2
  170. package/vanilla/UiContextMenu.d.ts +1 -1
  171. package/vanilla/UiContextMenu.js +2 -2
  172. package/vanilla/UiCover.d.ts +1 -1
  173. package/vanilla/UiCover.js +2 -2
  174. package/vanilla/UiCurveEditor.d.ts +1 -1
  175. package/vanilla/UiCurveEditor.js +2 -2
  176. package/vanilla/UiCycleButton.d.ts +1 -1
  177. package/vanilla/UiCycleButton.js +2 -2
  178. package/vanilla/UiDateField.d.ts +1 -1
  179. package/vanilla/UiDateField.js +2 -2
  180. package/vanilla/UiDatePicker.d.ts +1 -1
  181. package/vanilla/UiDatePicker.js +2 -2
  182. package/vanilla/UiDateRangePicker.d.ts +1 -1
  183. package/vanilla/UiDateRangePicker.js +4 -4
  184. package/vanilla/UiDescriptionItem.d.ts +1 -1
  185. package/vanilla/UiDescriptionItem.js +2 -2
  186. package/vanilla/UiDescriptionList.d.ts +1 -1
  187. package/vanilla/UiDescriptionList.js +2 -2
  188. package/vanilla/UiDialog.d.ts +1 -1
  189. package/vanilla/UiDialog.js +2 -2
  190. package/vanilla/UiDisclosure.d.ts +1 -1
  191. package/vanilla/UiDisclosure.js +2 -2
  192. package/vanilla/UiEditable.d.ts +1 -1
  193. package/vanilla/UiEditable.js +2 -2
  194. package/vanilla/UiEditor.d.ts +1 -1
  195. package/vanilla/UiEditor.js +6 -6
  196. package/vanilla/UiEditorBlockActions.d.ts +1 -1
  197. package/vanilla/UiEditorBlockActions.js +2 -2
  198. package/vanilla/UiEditorChipEditor.d.ts +1 -1
  199. package/vanilla/UiEditorChipEditor.js +2 -2
  200. package/vanilla/UiEditorCodeLanguage.d.ts +1 -1
  201. package/vanilla/UiEditorCodeLanguage.js +4 -4
  202. package/vanilla/UiEditorFootnoteEditor.d.ts +1 -1
  203. package/vanilla/UiEditorFootnoteEditor.js +2 -2
  204. package/vanilla/UiEditorFormattingTools.d.ts +1 -1
  205. package/vanilla/UiEditorFormattingTools.js +4 -4
  206. package/vanilla/UiEditorImageToolbar.d.ts +1 -1
  207. package/vanilla/UiEditorImageToolbar.js +2 -2
  208. package/vanilla/UiEditorInsertTableGrid.d.ts +1 -1
  209. package/vanilla/UiEditorInsertTableGrid.js +4 -4
  210. package/vanilla/UiEditorLinkCard.d.ts +1 -1
  211. package/vanilla/UiEditorLinkCard.js +2 -2
  212. package/vanilla/UiEditorLinkForm.d.ts +1 -1
  213. package/vanilla/UiEditorLinkForm.js +4 -4
  214. package/vanilla/UiEditorMentionMenu.d.ts +1 -1
  215. package/vanilla/UiEditorMentionMenu.js +4 -4
  216. package/vanilla/UiEditorMentionMenuItem.d.ts +1 -1
  217. package/vanilla/UiEditorMentionMenuItem.js +2 -2
  218. package/vanilla/UiEditorSlashMenu.d.ts +1 -1
  219. package/vanilla/UiEditorSlashMenu.js +4 -4
  220. package/vanilla/UiEditorSlashMenuGroup.d.ts +1 -1
  221. package/vanilla/UiEditorSlashMenuGroup.js +2 -2
  222. package/vanilla/UiEditorSlashMenuItem.d.ts +1 -1
  223. package/vanilla/UiEditorSlashMenuItem.js +2 -2
  224. package/vanilla/UiEditorSurface.d.ts +1 -1
  225. package/vanilla/UiEditorSurface.js +2 -2
  226. package/vanilla/UiEditorTableContextMenu.d.ts +1 -1
  227. package/vanilla/UiEditorTableContextMenu.js +7 -6
  228. package/vanilla/UiEditorTableOverlay.d.ts +1 -1
  229. package/vanilla/UiEditorTableOverlay.js +5 -5
  230. package/vanilla/UiEditorTableToolbar.d.ts +1 -1
  231. package/vanilla/UiEditorTableToolbar.js +8 -8
  232. package/vanilla/UiEditorToolbar.d.ts +1 -1
  233. package/vanilla/UiEditorToolbar.js +2 -2
  234. package/vanilla/UiFileInput.d.ts +1 -1
  235. package/vanilla/UiFileInput.js +4 -4
  236. package/vanilla/UiFloatingActionButton.d.ts +1 -1
  237. package/vanilla/UiFloatingActionButton.js +2 -2
  238. package/vanilla/UiFormField.d.ts +1 -1
  239. package/vanilla/UiFormField.js +2 -2
  240. package/vanilla/UiGrid.d.ts +1 -1
  241. package/vanilla/UiGrid.js +4 -4
  242. package/vanilla/UiIcon.d.ts +1 -1
  243. package/vanilla/UiIcon.js +4 -4
  244. package/vanilla/UiIconButton.d.ts +1 -1
  245. package/vanilla/UiIconButton.js +2 -2
  246. package/vanilla/UiImage.d.ts +1 -1
  247. package/vanilla/UiImage.js +2 -2
  248. package/vanilla/UiInput.d.ts +1 -1
  249. package/vanilla/UiInput.js +2 -2
  250. package/vanilla/UiInputGroup.d.ts +1 -1
  251. package/vanilla/UiInputGroup.js +2 -2
  252. package/vanilla/UiLightEditor.d.ts +1 -1
  253. package/vanilla/UiLightEditor.js +2 -2
  254. package/vanilla/UiList.d.ts +1 -1
  255. package/vanilla/UiList.js +3 -3
  256. package/vanilla/UiListItem.d.ts +1 -1
  257. package/vanilla/UiListItem.js +2 -2
  258. package/vanilla/UiListbox.d.ts +1 -1
  259. package/vanilla/UiListbox.js +5 -5
  260. package/vanilla/UiMenu.d.ts +1 -1
  261. package/vanilla/UiMenu.js +2 -2
  262. package/vanilla/UiMenuGroup.d.ts +1 -1
  263. package/vanilla/UiMenuGroup.js +2 -2
  264. package/vanilla/UiMenuItem.d.ts +1 -1
  265. package/vanilla/UiMenuItem.js +3 -3
  266. package/vanilla/UiMeter.d.ts +1 -1
  267. package/vanilla/UiMeter.js +4 -4
  268. package/vanilla/UiNavItem.d.ts +1 -1
  269. package/vanilla/UiNavItem.js +3 -3
  270. package/vanilla/UiNumberInput.d.ts +1 -1
  271. package/vanilla/UiNumberInput.js +2 -2
  272. package/vanilla/UiPageHeader.d.ts +1 -1
  273. package/vanilla/UiPageHeader.js +2 -2
  274. package/vanilla/UiPagination.d.ts +1 -1
  275. package/vanilla/UiPagination.js +4 -4
  276. package/vanilla/UiPopover.d.ts +1 -1
  277. package/vanilla/UiPopover.js +2 -2
  278. package/vanilla/UiRadio.d.ts +1 -1
  279. package/vanilla/UiRadio.js +2 -2
  280. package/vanilla/UiRadioGroup.d.ts +1 -1
  281. package/vanilla/UiRadioGroup.js +2 -2
  282. package/vanilla/UiReel.d.ts +1 -1
  283. package/vanilla/UiReel.js +2 -2
  284. package/vanilla/UiScrollArea.d.ts +1 -1
  285. package/vanilla/UiScrollArea.js +2 -2
  286. package/vanilla/UiSearchResultRow.d.ts +1 -1
  287. package/vanilla/UiSearchResultRow.js +2 -2
  288. package/vanilla/UiSearchShell.d.ts +1 -1
  289. package/vanilla/UiSearchShell.js +2 -2
  290. package/vanilla/UiSection.d.ts +1 -1
  291. package/vanilla/UiSection.js +3 -3
  292. package/vanilla/UiSelect.d.ts +1 -1
  293. package/vanilla/UiSelect.js +2 -2
  294. package/vanilla/UiSeparator.d.ts +1 -1
  295. package/vanilla/UiSeparator.js +2 -2
  296. package/vanilla/UiSidebar.d.ts +1 -1
  297. package/vanilla/UiSidebar.js +2 -2
  298. package/vanilla/UiSiteHeader.d.ts +1 -1
  299. package/vanilla/UiSiteHeader.js +2 -2
  300. package/vanilla/UiSkeleton.d.ts +1 -1
  301. package/vanilla/UiSkeleton.js +2 -2
  302. package/vanilla/UiSlider.d.ts +1 -1
  303. package/vanilla/UiSlider.js +2 -2
  304. package/vanilla/UiSpinner.d.ts +1 -1
  305. package/vanilla/UiSpinner.js +2 -2
  306. package/vanilla/UiStack.d.ts +1 -1
  307. package/vanilla/UiStack.js +2 -2
  308. package/vanilla/UiStatusMessage.d.ts +1 -1
  309. package/vanilla/UiStatusMessage.js +2 -2
  310. package/vanilla/UiSwatch.d.ts +1 -1
  311. package/vanilla/UiSwatch.js +2 -2
  312. package/vanilla/UiSwitch.d.ts +1 -1
  313. package/vanilla/UiSwitch.js +2 -2
  314. package/vanilla/UiSwitcher.d.ts +1 -1
  315. package/vanilla/UiSwitcher.js +2 -2
  316. package/vanilla/UiTable.d.ts +1 -1
  317. package/vanilla/UiTable.js +2 -2
  318. package/vanilla/UiTabs.d.ts +1 -1
  319. package/vanilla/UiTabs.js +4 -4
  320. package/vanilla/UiText.d.ts +1 -1
  321. package/vanilla/UiText.js +13 -13
  322. package/vanilla/UiTextarea.d.ts +1 -1
  323. package/vanilla/UiTextarea.js +2 -2
  324. package/vanilla/UiTimeField.d.ts +1 -1
  325. package/vanilla/UiTimeField.js +2 -2
  326. package/vanilla/UiTimePicker.d.ts +1 -1
  327. package/vanilla/UiTimePicker.js +6 -6
  328. package/vanilla/UiToast.d.ts +1 -1
  329. package/vanilla/UiToast.js +2 -2
  330. package/vanilla/UiToastRegion.d.ts +1 -1
  331. package/vanilla/UiToastRegion.js +4 -4
  332. package/vanilla/UiTooltip.d.ts +1 -1
  333. package/vanilla/UiTooltip.js +2 -2
  334. package/vanilla/UiTopBar.d.ts +1 -1
  335. package/vanilla/UiTopBar.js +2 -2
  336. package/vanilla/UiTree.d.ts +1 -1
  337. package/vanilla/UiTree.js +2 -2
  338. package/vanilla/UiTreeItem.d.ts +1 -1
  339. package/vanilla/UiTreeItem.js +2 -2
  340. package/vanilla/UiWizard.d.ts +27 -0
  341. package/vanilla/UiWizard.js +165 -0
  342. package/vanilla/index.js +1 -0
  343. package/bin/looma-docs.mjs +0 -3
  344. package/docs/README.md +0 -323
  345. package/docs/card.html +0 -79
  346. package/docs/card.js +0 -18
  347. package/docs/catalog-view.js +0 -24
  348. package/docs/catalog-view.mjs +0 -13
  349. package/docs/catalog.mjs +0 -131
  350. package/docs/cli.mjs +0 -26
  351. package/docs/commands.mjs +0 -94
  352. package/docs/customizer-render.mjs +0 -157
  353. package/docs/customizer.js +0 -494
  354. package/docs/documentation.css +0 -14
  355. package/docs/example-invocations.mjs +0 -63
  356. package/docs/fonts.mjs +0 -73
  357. package/docs/framework-examples.d.mts +0 -9
  358. package/docs/framework-examples.mjs +0 -195
  359. package/docs/index.d.ts +0 -59
  360. package/docs/index.mjs +0 -4
  361. package/docs/local-server.mjs +0 -65
  362. package/docs/navigation.mjs +0 -26
  363. package/docs/palette.mjs +0 -68
  364. package/docs/pastoral.svg +0 -54
  365. package/docs/portrait.svg +0 -15
  366. package/docs/reference.html +0 -1
  367. package/docs/reference.js +0 -36
  368. package/docs/render.mjs +0 -97
  369. package/docs/site.mjs +0 -237
  370. package/docs/store.mjs +0 -92
  371. package/docs/theme-session.mjs +0 -72
  372. package/docs/theme.mjs +0 -669
  373. package/docs/value-editors.mjs +0 -37
  374. package/docs/workspace.mjs +0 -32
package/docs/README.md DELETED
@@ -1,323 +0,0 @@
1
- ---
2
- title: Weave your design system
3
- ---
4
-
5
- # Weave your design system
6
-
7
- 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. Framework examples for local components import their authored HTML files; those paths are relative to the project root. The customizer uses the same authored component cards as the reference.
8
-
9
- ## Start a local design system
10
-
11
- In a project with a `package.json`, install Looma and its documentation tools:
12
-
13
- ```sh
14
- pnpm add @threadlabs/looma '@tiptap/core@>=2 <3' '@tiptap/pm@>=2 <3'
15
- pnpm add -D 'markupress@>=0.14.6' '@threadlabs/markupkit@>=0.4.3' vite
16
- pnpm exec looma-docs init --title "The Fellowship"
17
- pnpm exec looma-docs dev
18
- ```
19
-
20
- Looma installs its HTML Next runtime automatically. Use the tool versions accepted by Looma's optional peer dependencies. Markupress renders authored documentation with Expressmark’s standard syntax and supplies 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. The full built-in catalog includes document and compact editor examples; the commands above install their supported Tiptap 2 peers. Tiptap remains optional for applications and catalogs using only controls.
21
-
22
- Initialization creates three project-owned files:
23
-
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
- :::
36
-
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.
38
-
39
- The CSS includes generated derivation rules as well as values. Re-export or save your recipe after a Looma upgrade to adopt updated rules.
40
-
41
- Component navigation keeps every category linked and lists reference pages only beneath the current category. Category links open galleries with the matching filter selected; individual links open their references. Section selection survives reload and browser history, and overview cards render before JavaScript. The Section dropdown navigates between galleries; Filter components narrows only the cards on the current page, and changing sections starts with a fresh filter. Markupress supplies the section navigation and its continuous sidebar background. The Editor guide documents its composed editing tools; implementation controls stay out of the component catalog.
42
-
43
- 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.
44
-
45
- Starting points set a complete identity across color, typography, shape, spacing,
46
- material and motion. Looma is the default identity; Gold pairs a warm action color with Lato/Fraunces and restrained polished surfaces. Minimal remains a neutral starting point. Palette and material refinements then change only their own
47
- families. The compact sampler includes heading, body and supporting text beside
48
- the controls. Search components searches your whole discovered catalog; nine
49
- previews render initially, and **Show more components** reveals the next group.
50
-
51
- ```sh
52
- pnpm exec looma-docs build
53
- pnpm exec looma-docs preview
54
- ```
55
-
56
- `build` produces a static MarkupKit site in the configured output directory. `preview` serves that output without a repository writer. All commands accept `--root`; `dev` and `preview` also accept `--port`.
57
-
58
- ## Name your local design system
59
-
60
- `looma-docs init --title "Fellowship UI"` sets your site's name. To rename an
61
- existing local documentation site, edit `title` in `looma.docs.json`; the local
62
- server rebuilds the header, generated landing page and page titles with that
63
- name. You do not need to fork Looma or change component imports.
64
-
65
- You can also supply your logo and navigation:
66
-
67
- ```json
68
- {
69
- "title": "Fellowship UI",
70
- "logo": {
71
- "light": "/assets/fellowship-light.svg",
72
- "dark": "/assets/fellowship-dark.svg"
73
- },
74
- "nav": [{ "label": "Our application", "href": "https://example.com" }]
75
- }
76
- ```
77
-
78
- Merge these fields into your existing configuration. Serve the logo URLs from
79
- your application's public assets, such as `public/assets/`. Leave `logo` unset
80
- for a text-only brand. To author your own introduction, set `content` to your
81
- Markdown directory and add its `index.md`; it replaces the generated landing
82
- page without replacing component reference pages.
83
-
84
- The site name is yours. Component ownership stays accurate: built-in cards
85
- still identify `@threadlabs/looma`, while your discovered components identify
86
- the `packageName` you configure below. That is package attribution, not the
87
- name of your design system. Shared CSS and recipe filenames are configured
88
- under `theme`; changing a site title does not require renaming those files.
89
-
90
- A navigation link with `"position": "start"` appears before the generated component and
91
- editor sections. Other links keep their order after those sections:
92
-
93
- ```json
94
- { "nav": [{ "label": "Get started", "href": "/getting-started/", "position": "start" }] }
95
- ```
96
-
97
- For documentation-site Markdown syntax and publishing options, see the
98
- [Markupress documentation](https://threadlabs-studio.github.io/markupress/).
99
-
100
- ## Change the rule, keep the family consistent
101
-
102
- The authoring model groups shared decisions as Colour, Type, Size & spacing, Material and Motion. The controls expose shared intent: control roominess relative to text, rhythm, spacing, corners, inner and outer depth, and response pace.
103
-
104
- The generated values follow rules. The medium control height is base text size times control roominess; small and large heights follow the size ratio. Touch does not inflate the visible size ladder. Hit-area guidance is contextual and adjustable; 44px is a comfort preference for expanded targets, not a mandatory visible height. Invisible targets must not steal neighbouring controls. Rhythm coordinates vertical Stack gaps and unitless line-height multipliers. It leaves horizontal navigation and control-row gaps alone. Spacing adjusts gaps and padding independently of text ratios. Spacing derives from base text independently of control roominess and follows its own 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.
105
-
106
- Choose a coordinated palette, then refine surface warmth, color intensity and palette relationship. Warmth runs from cool to warm paper and ink, with 0.5 neutral; intensity runs from quiet to vivid, with 0.5 retaining original seed intensity. Keep my colors preserves the base hues; Related colors and Contrasting colors tint quiet surfaces toward neighboring and opposite hues. These decisions regenerate paired light/dark colors through Oklab/OKLCH operations, gamut repair and readability checks. They do not transform existing CSS colors live. Four base colors remain visible for precise edits. Supporting accents optionally adds second and third brand seeds. They feed `tone="accent-secondary"` and `tone="accent-tertiary"` on Button, IconButton, Badge, Card, Meter and Text, with the same derived readable text, states and material response as the primary. Unset supporting accents follow primary; the primary remains the normal action voice.
107
-
108
- Palette details expose relationships rather than arbitrary status colors. **Neutrals & shared borders** derives restrained neutrals from text, an accent family or untinted gray, with fill strength and a shared minimum boundary contrast (default 2:1). Neutral solid/outline actions and form fields all consume `--ui-control-border` and its hover role. Colored outlines resolve from their pigment against the same minimum over the finished wash and material gradient in light and dark modes, independently of readable text; outline hover retains that boundary color. Button and IconButton washes use translucent tone pigment rather than contextual text ink. Their shared wash roles lift deep pigment before compositing, then calibrate opacity against the material plate for a restrained perceptual hover step. Solid states change lightness while preserving hue and chroma, with extra lift for deep pigments; their reflections move with the fill. Outline hover keeps the same material layer, and ghost feedback uses the same paint in text and icon actions. **Status colors** lets each role retain its semantic hue, harmonize toward the primary hue by at most 15 degrees, or use one of the three brand families. Perceptual saturation is coordinated with the primary; readability and material stops are resolved for both modes. Dark derivation separates canvas and content elevations, compensates quiet neutral fills and borders, and derives selection washes from readable contextual pigment. Subtle badges, toned cards, callouts, toasts and generated notifications share semantic background, foreground and border roles. Composed Text inherits the containing foreground; the document root supplies the normal body color. These roles provide paler light fills and visible dark tints. Optional overlay group overrides remain explicit choices instead of masking semantic defaults. There are no per-status color pickers. Words and icons preserve meaning when all statuses use one family. **Accent assignments** selects families for links, focus rings and selected rows. Light/dark specimens show these roles together, including an actual field beside the shared neutral actions.
109
-
110
- Documentation navigation stays out of the customization workspace. **Material & light** opens a movable light source, real component samples and bounded surface controls. **Palette** opens light/dark specimens, base seeds and advanced relationship controls. Each editor changes the same persistent theme. Returning to the overview, navigating to a component, or reloading keeps the result.
111
-
112
- Material groups finish, transparency, frosting, lighting and depth in a compact control panel. The grid appears only behind material specimens; editing controls and the persistent summary have opaque backing panels. Help buttons preserve explanations without showing them all up front. Transparency mostly affects decorative rims and overlays; at maximum, content plates also reveal a little of the scene.
113
-
114
- The starting themes make different choices within the same controls:
115
-
116
- - **Minimal:** gray neutrals, restrained status tints and minimal depth.
117
- - **Gold:** warm primary actions, readable amber links and plum selection, rounded polished surfaces, and Lato/Fraunces.
118
- - **Bookish:** wine guidance and confirmations, coral and leather accents, restrained risk colors, and Open Sans/Newsreader.
119
- - **Editorial:** flat ink-and-paper surfaces, rust links, serif type, and primary-color statuses distinguished by icons and labels.
120
- - **Night:** cool supporting accents, amber warnings, glass material, and IBM Plex Sans/Mono.
121
- - **Garden:** forest, clay and gold, soft rounded surfaces, and Nunito Sans/Lora.
122
-
123
- The summary stays above the editor and updates as decisions change; Undo, Redo and Reset remain available there. Optional accent swatches offer None inside the picker, without a separate mode selector.
124
-
125
- A refined preset keeps its name with “customized” beside it. The shared toolbar provides Undo, Redo, and a single Reset for the theme. Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z also undo and redo theme changes, including while a dropdown has focus; text fields retain their native editing history. Status color relationships offer **Semantic colors**, **Less color**, and **Primary + icons**, with advanced per-status relationships available. 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.
126
-
127
- Number controls accept arithmetic such as `1rem / 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. LightEditor keeps its coordinate fields under **Exact position**. Light and curve drags preserve the grab offset; Escape or pointer cancellation restores the gesture start without creating a saved edit.
128
-
129
- Lengths retain their CSS units, such as `rem`; times retain `ms` or `s`. The downloaded CSS includes the canonical shared CSS derivation rules as well as resolved theme values. Download JSON separately to retain editable decisions and font/preset provenance. 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.
130
-
131
- The customizer opens on a dashboard summarizing the current starting theme, palette,
132
- material, typography, spacing and motion. Open a summary to edit that subject; use
133
- **Overview** to return to the same dashboard position. Only the active editor shows
134
- its controls. Precise adjustments sit inside the relevant editor's detail sections.
135
-
136
- Typography pairs font selection with headings and body text. Field labels follow body size by default; choose a separate label size to keep labels independent while help stays smaller. Size & spacing shows
137
- the shared control ladder and grouped content. Motion keeps a replayable study and
138
- a real popover beside duration and curve editing; the study follows the shared
139
- curve, travels at three times the feedback duration, and respects reduced motion.
140
- **Browse components** searches the complete catalog, with previews loaded in batches.
141
- **Export & save** contains downloads, recipe import and local repository saving.
142
-
143
- Edits apply immediately. Undo and Redo move through completed changes; Reset restores
144
- the current starting theme. There is no separate variation preview or apply step.
145
-
146
- 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 restores the selected starting theme’s values and remains undoable. Removing the header’s Custom theme chip instead clears the browser override and restores the repository baseline. Invalid input keeps the last valid preview and explains which decision needs attention.
147
-
148
- 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"` uses the separate choices. Both default to neutral; choose `tone="accent"` or `preset="primary"` explicitly for emphasis.
149
-
150
- **Font** sets body text and controls. Headings follow it while **Heading font** is
151
- **Same as main font**; choose a second face there for headings and display text.
152
- Google selections preview real faces and include their import in downloaded or
153
- locally saved CSS. System font uses the operating system and needs no download.
154
-
155
- ## Theme decisions and public properties
156
-
157
- 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.
158
-
159
- ::: table
160
-
161
- - Family: Base colors
162
- Recipe decisions → CSS properties: `action` → `--ui-accent`; `canvas` → `--ui-surface`; `surface` → `--ui-surface-raised`; `text` → `--ui-text`
163
-
164
- - Family: Palette generation (recipe only)
165
- 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
166
-
167
- - Family: Type
168
- 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`
169
-
170
- - Family: Rhythm & spacing
171
- 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`
172
-
173
- - Family: Depth and transmission
174
- 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`
175
-
176
- - Family: Finish and illumination
177
- 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`
178
-
179
- - Family: Motion
180
- Recipe decisions → CSS properties: `response-time` → `--ui-motion-fast`; `response-curve` → `--ui-motion-ease`
181
-
182
- :::
183
-
184
- 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.
185
-
186
- Before 1.0 there are no compatibility aliases. Migrate recipe `density` to `spacing` and CSS `--ui-density` to `--ui-spacing`. Replace length-valued recipe `control-size` with numeric `control-roominess` by dividing the desired medium height by base text size: `40px / 16px` becomes `2.5`. Base `text-size` is now px-only and sets the document root. Replace older relative base values with an explicit px value using their original root; no compatibility conversion guesses it.
187
-
188
- ## Choose fonts
189
-
190
- **System font** is the default and uses the operating system's native `system-ui` face without a download. Search the curated Google Fonts collection for body and display roles; selected faces load in the previews. Generated/downloaded CSS and locally saved CSS include the selected Google Fonts `@import` before rules, so the consuming application loads the same faces.
191
-
192
- An optional recipe `fonts` mapping records Google family names by `body-font` and/or `display-font`, while `values` keeps their matching CSS stacks. Import/export preserves both. The advanced **Custom font stack** field is for already loaded or self-hosted faces; it does not download fonts. Load those faces in the consuming application.
193
-
194
- ## Describe material and light
195
-
196
- 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.
197
-
198
- Depth controls elevation and recession independently from finish, transmission and motion. Finish controls how strongly a material catches a reflection, from matte to polished; it needs nonzero light strength. Light spread shapes that reflection, while position also directs shadows. A light strength of zero does not remove depth shadows. Edge light catches its boundary; glow spills beyond it. Glassiness and glow use a gently increasing lower range and an expressive upper response (`g + 2g⁴`), so the maximum can be exuberant without raising restrained defaults. Glassiness and surface separation govern the decorative material around floating content, scaled by popup purpose and rendered size. The content plane stays nearly opaque, with slight transmission at maximum transparency. Overlay translucency changes the shared overlay fill and decorative glass; the content paint accounts for its reflection so stacked layers do not erase that slight transmission. Separation can create a rim even with glassiness at zero. Reflection peaks are bounded for readable text, and reduced transparency disables the ornamental reflection and glow as well as backdrop blur.
199
-
200
- Card keeps surface structure and decorative treatment independent:
201
-
202
- ```html
203
- <ui-card variant="elevated">Standard subtle lift</ui-card>
204
- <ui-card variant="elevated" treatment="expressive">Lift with the theme's material</ui-card>
205
- <ui-card treatment="expressive">Material treatment without added lift</ui-card>
206
- ```
207
-
208
- `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.
209
-
210
- 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.
211
-
212
- ## Use light, dark, or both
213
-
214
- 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 base colors to maintain contrast.
215
-
216
- Load the generated CSS after Looma's tokens and palette. Choose how it runs:
217
-
218
- - **System preference:** leave `data-theme` off the document root. The CSS follows the operating system automatically.
219
- - **Light only:** set `<html data-theme="light">`.
220
- - **Dark only:** set `<html data-theme="dark">`.
221
- - **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.
222
-
223
- 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:
224
-
225
- ```html
226
- <section data-theme="dark">
227
- <h2>After-hours Fellowship office</h2>
228
- <div data-theme="light">Sam's daylight reading area</div>
229
- </section>
230
- ```
231
-
232
- 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.
233
-
234
- ## Add your components
235
-
236
- Build your design-system components in HTML Next. Their definitions, description attributes, modules 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.
237
-
238
- 1. Create a directory for your HTML Next component resources, such as `app/components`.
239
- 2. Opt that directory into `components` in `looma.docs.json`, with your package's name.
240
- 3. Put `docs.json` and an `examples/` directory beside each resource, as shown below.
241
- 4. Run `looma-docs dev`. Your components appear beside Looma's in the reference,
242
- search and customizer example picker. Resources under registered directories
243
- are rediscovered when the local server rebuilds.
244
-
245
- The configuration can combine your name, authored guides and discovery roots:
246
-
247
- ```json
248
- {
249
- "title": "The Fellowship",
250
- "base": "/",
251
- "outDir": ".looma/site",
252
- "content": "docs",
253
- "theme": { "recipe": "looma.theme.json", "css": "looma.theme.css" },
254
- "components": [{ "directory": "app/components", "packageName": "fellowship-ui" }],
255
- "overrides": ["styles/design-system-overrides.css"]
256
- }
257
- ```
258
-
259
- `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. Google font selections travel in the generated CSS import. Load custom or self-hosted faces in the consuming application; their stacks only select families.
260
-
261
- A resource can use any valid HTML Next component tag:
262
-
263
- ```html
264
- <template component="office-status">
265
- <defs>
266
- <prop name="label" type="string" default="Ready">The team's current status.</prop>
267
- </defs>
268
- <p>{$label}<slot></slot></p>
269
- </template>
270
- ```
271
-
272
- Place a `docs.json` beside it to join a shared category:
273
-
274
- ```json
275
- {
276
- "title": "Office status",
277
- "summary": "The office’s current status.",
278
- "description": "A status for the Fellowship office.",
279
- "group": "display"
280
- }
281
- ```
282
-
283
- An optional `summary` supplies the short card text; `description` supplies the full reference introduction. Cards use `description` when no summary is authored.
284
-
285
- 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.
286
-
287
- A component card should demonstrate its defining feature, including a non-default configuration when that makes the behavior clear. A feature demonstration does not require changing the component’s default.
288
-
289
- Put authored examples in an `examples/` directory beside the resource. Each `.html` example starts with a metadata comment:
290
-
291
- ```html
292
- <!--
293
- title: Ready for second breakfast
294
- description: Sam has finished the morning checklist.
295
- -->
296
- <office-status label="Ready for second breakfast"></office-status>
297
- ```
298
-
299
- The first example also appears in the component directory, so keep it representative at a narrow card width. Full variations belong in the later reference examples. Optional `.behavior.js` or `.behavior.ts` companions export a default setup function receiving the example root; return a cleanup function when needed. Select controls through example-local data attributes: generated IDs and their label, trigger and command references are namespaced for each instance. Add `preview: resizable` to expose the shared card's width control, or `preview: stretch` when the sample needs the available inline width, such as percentage-based loading placeholders. Framework-specific `.snippet.html` and `.vue` companions provide literal source views.
300
-
301
- 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.
302
-
303
- Author components and documentation examples in HTML Next. Vue, React and Svelte applications compile those definitions with the HTML Next Vite plugin or converter; framework conversion belongs in the consuming application. See the [loading guide](https://threadlabs.studio/looma/getting-started/) for framework setup, imports and styles.
304
-
305
- The shared example generator parses HTML invocations into props, children and named slots, then prints each framework's public API. Catalog attributes carry the HTML Next parser's `valueType` node alongside the displayed `type`; the generator uses HTML Next's public value parser for booleans, numbers, collections and types selected by another prop. Svelte snippets use their slot's role as a name, with component names disambiguating repeated roles. React examples use slot objects and only the fragments required for multiple children. Vue named templates retain their position in the authored example. Vue object and array bindings print single-quoted JavaScript strings inside double-quoted attributes. Structural indentation is rebuilt while inline spacing and preformatted text are preserved. The framework consumer tests compile and render representative generated examples through the actual adapters.
306
-
307
- ## Combine installed catalogs
308
-
309
- 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.
310
-
311
- 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.
312
-
313
- ## Saving and recovery
314
-
315
- 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 are pre-rendered directly in the documentation page and share its styles and HTML Next runtime. Project component roots and example companions are trusted application code, so opt in only to sources you would run in your application. Example IDs and their label, trigger and command relationships are namespaced per specimen; companions can select stable authored hooks such as data-example-id. Width controls resize the inline stage; viewport media queries follow the documentation window.
316
-
317
- 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`.
318
-
319
- The starting theme is selectable directly in the persistent summary bar. Font options preview their names using separate font faces loaded on visibility with Google Fonts’ [`text=` subsets](https://developers.google.com/fonts/docs/css2#optimizing_for_latency_and_file_size). Selecting a font loads its unrestricted family and supported weights; preview subsets never supply document text.
320
-
321
- Preset choices use the styled, searchable dropdown already used for fonts and component examples. Palette choices include four color swatches for the accent, neutral fill, canvas and text; the selected field previews the current theme. An inherited default keeps muted text while its options remain readable.
322
-
323
- Filled-action colors keep their supplied pigment. Readable on-fill ink is chosen independently from contextual text, outlines and focus. Neutral action and field boundaries derive from one contrast decision against their surfaces; their quiet fills are independent of primary pigment. Supporting brand families are separate from neutral secondary actions. Reflection preserves chromatic light and shade within that chosen foreground’s readability bounds.
package/docs/card.html DELETED
@@ -1,79 +0,0 @@
1
- <link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">
2
- <link rel="component" href="@threadlabs/looma/components/ui-form-field/ui-form-field.html">
3
- <link rel="component" href="@threadlabs/looma/components/ui-input/ui-input.html">
4
- <link rel="component" href="@threadlabs/looma/components/ui-button/ui-button.html">
5
- <template component="looma-example-card" module="./card.js">
6
- <defs>
7
- <prop name="identity" type="string" default="">Stable catalog example identity.</prop>
8
- <prop name="title" type="string" default="Example">The documented component name.</prop>
9
- <prop name="description" type="string" default="">The component's authored description.</prop>
10
- <prop name="exampleTitle" type="string" default="">The selected authored example.</prop>
11
- <prop name="previewOnly" type="boolean" default="false">Show only the live example, for compact theme samplers whose host supplies the heading.</prop>
12
- <prop name="reference" type="boolean" default="false">Use the spacious full-reference example presentation.</prop>
13
- <prop name="resizable" type="boolean" default="false">Expose a width control for responsive examples.</prop>
14
- <prop name="category" type="string" default="forms">The shared category identity.</prop>
15
- <prop name="tag" type="string" default="">The component's authored tag.</prop>
16
- <prop name="packageName" type="string" default="">The package that owns this component.</prop>
17
- <prop name="nativeRoot" type="string" default="">The component's semantic native root.</prop>
18
- <prop name="href" type="string" default="">The component reference page.</prop>
19
- <prop name="removable" type="boolean" default="false">Offer removal when this card is selected in the customizer.</prop>
20
- </defs>
21
- <article from:data-example-card="$identity" from:data-component-card="$tag" from:data-category="$category">
22
- <header $if="$reference" class="example-heading"><slot name="heading"><h3>{$exampleTitle}</h3><p>{$description}</p></slot></header>
23
- <div class="preview"><div class="stage" $ref="stage"><slot name="preview"></slot></div></div>
24
- <section $if="$reference" class="example-code"><h4>Code</h4><slot name="code"></slot></section>
25
- <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>
26
- <div $if="not $reference and not $previewOnly" class="body"><ui-stack gap="xs">
27
- <div class="meta"><span>{$category}</span><code>{$nativeRoot}</code></div>
28
- <h3><a class="destination" from:href="$href">{$title}</a></h3>
29
- <p class="description">{$description}</p>
30
- <p class="owner" $if="$packageName">{$packageName}</p>
31
- <p class="example-caption" $if="$exampleTitle">{$exampleTitle}</p>
32
-
33
- <footer><span $if="$href" class="view-link">View component</span><div class="secondary-actions"><ui-button $if="$removable" $ref="remove" variant="ghost" size="sm">Remove</ui-button><slot name="actions"></slot></div></footer>
34
- </ui-stack></div>
35
- </article>
36
- <style>
37
- /* The existing documentation catalog card, shared by the directory, reference and customizer. */
38
- :host {
39
- --_card-accent: var(--ui-accent);
40
- position: relative;
41
- overflow: hidden;
42
- background: var(--ui-surface-raised);
43
- border: var(--ui-border-width) solid var(--ui-border);
44
- border-radius: var(--ui-radius-lg);
45
- box-shadow: var(--ui-shadow-sm);
46
- }
47
- :host([category="display"]) { --_card-accent: var(--ui-success); }
48
- :host([category="overlay"]) { --_card-accent: var(--ui-danger); }
49
- :host([category="layout"]) { --_card-accent: var(--ui-info); }
50
- :host([category="editor"]) { --_card-accent: var(--ui-warning); }
51
- .example-heading { padding: var(--ui-space-5) !important; border-block-end: var(--ui-border-width) solid var(--ui-border); }
52
- .example-code { padding: var(--ui-space-5) !important; border-block-start: var(--ui-border-width) solid var(--ui-border); }
53
- .example-code h4 { margin: 0 0 var(--ui-space-3) !important; font-size: var(--ui-font-size-md); }
54
- .example-heading p { margin: var(--ui-space-2) 0 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); }
55
- :host([reference]) .preview { min-block-size: 11rem; display: grid !important; align-items: center !important; border-block-end: 0; }
56
- :host([reference]) .preview::before { display: none; }
57
- .preview { position: relative; min-block-size: 13rem; overflow: hidden; border-block-end: var(--ui-border-width) solid var(--ui-border); background: var(--ui-surface-raised); }
58
- .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; }
59
- .stage { inline-size: var(--_preview-width, 100%); max-inline-size: 100%; min-inline-size: 0; }
60
- footer { display: flex !important; align-items: center !important; justify-content: space-between !important; gap: var(--ui-space-2) !important; }
61
- .preview-width { padding: var(--ui-space-4) !important; }
62
- .body { position: relative; isolation: isolate; padding: var(--ui-space-5) !important; background: var(--ui-surface-raised); transition: background-color var(--ui-motion-fast) var(--ui-motion-ease); }
63
- .body:has(.destination[href]:hover), .body:has(.destination[href]:focus-visible) { background: var(--ui-accent-subtle); }
64
- .body:has(.destination[href]:active) { background: color-mix(in srgb, var(--ui-accent) 16%, var(--ui-surface-raised)); }
65
- .destination[href]::after { position: absolute; inset: 0; z-index: 1; content: ""; cursor: pointer; }
66
- .destination:focus-visible { outline: none; }
67
- .destination:focus-visible::after { outline: var(--ui-focus-width) solid var(--ui-focus-ring); outline-offset: calc(-1 * var(--ui-focus-width)); }
68
- .view-link { color: var(--ui-link-color); font-size: var(--ui-font-size-sm); font-weight: var(--ui-font-semibold); text-decoration: underline; text-underline-offset: .2em; }
69
- .secondary-actions { position: relative; z-index: 2; display: flex !important; align-items: center !important; gap: var(--ui-space-2) !important; }
70
- .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; }
71
- .meta code { padding: 0 !important; background: transparent; color: inherit; text-transform: none; }
72
- h3 { margin: 0 !important; padding: 0 !important; font-size: var(--ui-font-size-lg); letter-spacing: -.035em; }
73
- h3 a { color: var(--ui-text); text-decoration: none; }
74
- .description { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-sm); line-height: var(--ui-line-height); }
75
- .owner { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); overflow-wrap: anywhere; }
76
- .example-caption { margin: 0 !important; color: var(--ui-text-secondary); font-size: var(--ui-font-size-xs); }
77
- @media (prefers-reduced-motion: reduce) { .body { transition: none; } }
78
- </style>
79
- </template>
package/docs/card.js DELETED
@@ -1,18 +0,0 @@
1
- import { exampleBehaviors } from './example-behaviors.js';
2
- /** Cards share their document's theme and runtime; width controls size only this stage. */
3
- export function connect(host) {
4
- const { stage, width, remove } = host.refs;
5
- const stopExample = exampleBehaviors[host.props.identity.value]?.(host.element.querySelector('[data-preview]'));
6
- const removeCard = () => host.element.dispatchEvent(new CustomEvent('looma-example-remove', { bubbles: true, detail: { id: host.props.identity.value } }));
7
- const resize = event => {
8
- const value = Number(event.detail?.value ?? event.target.value);
9
- if (value >= 240 && value <= 1600) stage.style.setProperty('--_preview-width', `${value}px`);
10
- };
11
- width?.addEventListener('input', resize);
12
- remove?.addEventListener('click', removeCard);
13
- return () => {
14
- stopExample?.();
15
- width?.removeEventListener('input', resize);
16
- remove?.removeEventListener('click', removeCard);
17
- };
18
- }
@@ -1,24 +0,0 @@
1
- /** Native catalog entries own their visibility; component previews keep their own layout. */
2
- export function connect(host) {
3
- const { query, category, count, filters } = host.refs;
4
- const groups = [...host.element.querySelectorAll('[data-catalog-group]')];
5
- const items = [...host.element.querySelectorAll('[data-catalog-search]')];
6
- query.value = '';
7
- const filter = () => {
8
- const words = query.value.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
9
- let visible = 0;
10
- for (const item of items) {
11
- item.hidden = !words.every(word => item.dataset.catalogSearch.toLocaleLowerCase().includes(word));
12
- if (!item.hidden) visible++;
13
- }
14
- for (const group of groups) group.hidden = ![...group.querySelectorAll('[data-catalog-search]')].some(item => !item.hidden);
15
- count.textContent = visible === 0 ? 'No components match. Try another name or section.' : `${visible} component${visible === 1 ? '' : 's'}`;
16
- };
17
- const chooseCategory = () => {
18
- const destination = new URL(category.selectedOptions[0].dataset.href, location.href);
19
- location.assign(destination.href);
20
- };
21
- query.addEventListener('input', filter); category.addEventListener('change', chooseCategory); filter();
22
- filters.hidden = false;
23
- return () => { query.removeEventListener('input', filter); category.removeEventListener('change', chooseCategory); };
24
- }
@@ -1,13 +0,0 @@
1
- import { escapeHtml as escape } from './catalog.mjs';
2
-
3
- /** Catalog filtering wraps the same server-rendered documentation cards. */
4
- export function catalogResource(groups, base = '/') {
5
- return `<link rel="component" href="@threadlabs/looma/components/ui-form-field/ui-form-field.html">
6
- <link rel="component" href="@threadlabs/looma/components/ui-input/ui-input.html">
7
- <link rel="component" href="@threadlabs/looma/components/ui-select/ui-select.html">
8
- <link rel="component" href="@threadlabs/looma/components/ui-cluster/ui-cluster.html">
9
- <link rel="component" href="@threadlabs/looma/components/ui-grid/ui-grid.html">
10
- <link rel="component" href="@threadlabs/looma/components/ui-stack/ui-stack.html">
11
- <template component="looma-catalog" module="./catalog-view.js"><defs><prop name="category" type="string" default="">The category represented by this gallery.</prop><prop name="total" type="number" default="0">Number of cards before text filtering.</prop></defs>
12
- <ui-stack gap="xl"><div $ref="filters" hidden><ui-grid columns="2" min="md"><ui-form-field><label slot="label" for="catalog-query">Filter components</label><ui-input id="catalog-query" $ref="query" type="search" placeholder="Name, tag or purpose"></ui-input></ui-form-field><ui-cluster align="end"><ui-form-field><label slot="label" for="catalog-category">Section</label><ui-select id="catalog-category" $ref="category"><option value="" data-href="${escape(base)}components/" from:selected="$category = ''">All sections</option>${groups.map(group => `<option value="${escape(group.id)}" data-href="${escape(base)}components/${escape(group.id)}/" from:selected="${escape(`$category = ${JSON.stringify(group.id)}`)}">${escape(group.label)}</option>`).join('')}</ui-select></ui-form-field></ui-cluster></ui-grid></div><p $ref="count" role="status" aria-live="polite">{$total} components</p><slot></slot></ui-stack></template>`;
13
- }
package/docs/catalog.mjs DELETED
@@ -1,131 +0,0 @@
1
- import { readFile, readdir } from 'node:fs/promises';
2
- import path from 'node:path';
3
- import { fileURLToPath } from 'node:url';
4
-
5
- export const catalogVersion = 1;
6
- export const escapeHtml = value => String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;');
7
- export const titleOf = tag => tag.replace(/^ui-/, '').split('-').map(word => word[0].toUpperCase() + word.slice(1)).join(' ');
8
- export async function readJson(file, fallback) {
9
- try { return JSON.parse(await readFile(file, 'utf8')); }
10
- catch (error) { if (error.code === 'ENOENT' && fallback !== undefined) return fallback; throw error; }
11
- }
12
-
13
- /** Authored examples are data during discovery; controllers are never evaluated. */
14
- export async function readExamples(directory, componentId) {
15
- let files;
16
- try { files = (await readdir(directory)).sort(); } catch (error) { if (error.code === 'ENOENT') return []; throw error; }
17
- return Promise.all(files.filter(file => /^[^.]+\.html$/.test(file)).map(async file => {
18
- const name = file.slice(0, -5);
19
- const source = await readFile(path.join(directory, file), 'utf8');
20
- const meta = /^<!--\r?\n([\s\S]*?)\r?\n-->\s*/.exec(source);
21
- if (!meta) throw new Error(`${path.join(directory, file)}: example requires title/description metadata.`);
22
- const fields = Object.fromEntries(meta[1].split(/\r?\n/).map(line => {
23
- const at = line.indexOf(':'); return at < 0 ? [] : [line.slice(0, at).trim(), line.slice(at + 1).trim()];
24
- }).filter(pair => pair.length));
25
- const frameworks = {};
26
- for (const [target, extension, language] of [['html-next', '.snippet.html', 'html'], ['vue', '.vue', 'vue'], ['react', '.tsx', 'tsx'], ['svelte', '.svelte', 'svelte']]) {
27
- if (files.includes(name + extension)) frameworks[target] = { language, code: await readFile(path.join(directory, name + extension), 'utf8') };
28
- }
29
- const behavior = files.includes(name + '.behavior.ts') ? path.join(directory, name + '.behavior.ts') : files.includes(name + '.behavior.js') ? path.join(directory, name + '.behavior.js') : undefined;
30
- return { id: `${componentId}/${name}`, name, title: fields.title ?? name, description: fields.description ?? '', markup: source.slice(meta[0].length).trim(), resizable: fields.preview === 'resizable', ...(fields.preview === 'stretch' ? { stretch: true } : {}), bindings: fields.bind ?? '', frameworks, ...(behavior ? { behavior } : {}) };
31
- }));
32
- }
33
-
34
- async function resources(directory) {
35
- const result = [];
36
- for (const entry of (await readdir(directory, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
37
- if (entry.name.startsWith('.') || entry.name === 'node_modules' || entry.name === 'examples') continue;
38
- const file = path.join(directory, entry.name);
39
- if (entry.isDirectory()) result.push(...await resources(file));
40
- else if (entry.name.endsWith('.html')) result.push(file);
41
- }
42
- return result;
43
- }
44
-
45
- /** Discover only explicitly selected roots through HTML Next's public parser. */
46
- export async function discoverComponents({ root, directory, packageName, groups = [] }) {
47
- if (!packageName || !directory) throw new Error('A discovery root requires packageName and directory.');
48
- const { parseComponentResource, typeScriptType, normalizeType } = await import('@nextwebwg/html-next');
49
- const components = [];
50
- for (const source of await resources(path.resolve(root, directory))) {
51
- const html = await readFile(source, 'utf8');
52
- if (!/<template\b[^>]*\bcomponent=/.test(html)) continue;
53
- const parsed = parseComponentResource(html, source);
54
- const metadata = await readJson(path.join(path.dirname(source), 'docs.json'), {});
55
- for (const definition of parsed.definitions) {
56
- const contract = definition.contract;
57
- const docs = metadata.components?.[contract.tag] ?? metadata;
58
- const id = `${packageName}/${contract.tag}`;
59
- const properties = Object.entries(contract.props).map(([name, prop]) => ({ name, type: typeScriptType(prop.type), description: prop.description ?? '', ...(Object.hasOwn(prop, 'default') ? { default: prop.default } : {}), ...(prop.values ? { options: prop.values } : {}) }));
60
- const attributes = properties.map(prop => ({ ...prop, property: prop.name, name: prop.name.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`), valueType: normalizeType(contract.props[prop.name].type) }));
61
- const events = (definition.declarations ?? []).filter(item => item.kind === 'event').map(event => ({ name: event.name, detailType: event.shape ? typeScriptType(event.shape) : String(event.type), detailDocs: docs.events?.[event.name] ?? '' }));
62
- const slots = (definition.slots ?? []).map(slot => ({ name: slot.name ?? 'default', description: docs.slots?.[slot.name ?? 'default'] ?? '' }));
63
- const tokens = [...new Set([...definition.css.matchAll(/var\(\s*(--[\w-]+)/g)].map(match => match[1]))].sort();
64
- components.push({ id, package: packageName, tag: contract.tag, title: docs.title ?? titleOf(contract.tag), description: docs.description ?? contract.summary ?? '', ...(docs.summary ? { summary: docs.summary } : {}), group: docs.group ?? 'project', ...(docs.navigationParent ? { navigationParent: docs.navigationParent } : {}), root: contract.nativeElement, source, resource: source, importSource: './' + path.relative(root, source).split(path.sep).join('/'), targets: ['html-next', 'vue', 'react', 'svelte'], attributes, properties, events, slots, designTokens: { sources: [path.relative(root, source)], component: [], shared: tokens.map(name => ({ name, fallbacks: [] })) }, examples: await readExamples(path.join(path.dirname(source), 'examples'), id) });
65
- }
66
- }
67
- const categories = components.some(component => component.group === 'project') && !groups.some(group => group.id === 'project') ? [...groups, { id: 'project', label: 'Project components' }] : groups;
68
- return { schemaVersion: catalogVersion, package: packageName, groups: categories, components };
69
- }
70
-
71
- /** Merge deterministically, reporting both owners instead of silently shadowing resources. */
72
- export function mergeCatalogs(catalogs, { categories = {} } = {}) {
73
- const resourceByTag = new Map();
74
- const exampleOwners = new Map();
75
- const groups = new Map(); const byId = new Map(); const byTag = new Map();
76
- for (const catalog of catalogs) {
77
- if (catalog.schemaVersion !== catalogVersion) throw new Error(`Unsupported documentation catalog version ${catalog.schemaVersion} for ${catalog.package}.`);
78
- for (const group of catalog.groups ?? []) {
79
- const mapped = categories[group.id] ?? group.id;
80
- if (typeof mapped !== 'string' || !/^[a-z][a-z0-9-]*$/.test(mapped)) throw new Error(`Invalid category identity ${JSON.stringify(mapped)} in ${catalog.package}.`);
81
- const previous = groups.get(mapped);
82
- if (previous && previous.label !== group.label && mapped === group.id) throw new Error(`Conflicting category ${mapped}: ${previous.label} and ${group.label}. Configure a category mapping explicitly.`);
83
- if (!previous) groups.set(mapped, { ...group, id: mapped });
84
- }
85
- for (const entry of catalog.components) {
86
- // HTML Next's public component-tag grammar also keeps generated filenames inside their tree.
87
- if (typeof entry.tag !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)+$/.test(entry.tag)) throw new Error(`Invalid component tag ${JSON.stringify(entry.tag)} in ${catalog.package}.`);
88
- if (typeof entry.id !== 'string' || !entry.id) throw new Error(`Missing component identity for ${entry.tag} in ${catalog.package}.`);
89
- const component = { ...entry, group: categories[entry.group] ?? entry.group };
90
- const previous = byTag.get(component.tag) ?? byId.get(component.id);
91
- if (previous) throw new Error(`Duplicate component ${component.tag}: ${previous.id} (${previous.source ?? previous.resource}) and ${component.id} (${component.source ?? component.resource}).`);
92
- byId.set(component.id, component); byTag.set(component.tag, component);
93
- if (!Array.isArray(component.examples)) throw new Error(`Component ${component.id} requires an examples array.`);
94
- for (const example of component.examples) {
95
- if (typeof example.id !== 'string' || !example.id || typeof example.markup !== 'string') throw new Error(`Invalid example identity or markup in ${component.id}.`);
96
- if (!example.id.startsWith(component.id + '/')) throw new Error(`Example ${example.id} must belong to ${component.id}.`);
97
- const previous = exampleOwners.get(example.id);
98
- if (previous) throw new Error(`Duplicate example ${example.id}: ${previous} and ${component.id}.`);
99
- exampleOwners.set(example.id, component.id);
100
- }
101
- }
102
- for (const entry of [...catalog.resources ?? [], ...catalog.components]) {
103
- const previous = resourceByTag.get(entry.tag);
104
- if (previous && (previous.package !== entry.package || previous.resource !== entry.resource)) throw new Error(`Conflicting resource ${entry.tag}: ${previous.resource} and ${entry.resource}.`);
105
- resourceByTag.set(entry.tag, { tag: entry.tag, package: entry.package, resource: entry.resource });
106
- }
107
- }
108
- const ownerOf = (component, trail = []) => {
109
- if (trail.includes(component.id)) throw new Error(`Compound parent cycle: ${[...trail, component.id].join(' → ')}.`);
110
- if (!component.navigationParent) return component;
111
- const parent = byId.get(component.navigationParent) ?? byTag.get(component.navigationParent);
112
- if (!parent) throw new Error(`Missing compound parent ${component.navigationParent} for ${component.id}.`);
113
- return ownerOf(parent, [...trail, component.id]);
114
- };
115
- for (const component of byId.values()) {
116
- if (component.navigationParent) {
117
- const owner = ownerOf(component);
118
- component.navigationParent = owner.tag;
119
- component.group = owner.group;
120
- }
121
- if (!groups.has(component.group)) throw new Error(`Unknown category ${component.group} for ${component.id}. Declare its category or map it to an existing one.`);
122
- }
123
- return { schemaVersion: catalogVersion, resources: [...resourceByTag.values()], groups: [...groups.values()], components: [...byId.values()].sort((a, b) => a.id.localeCompare(b.id)) };
124
- }
125
-
126
- /** Read a published catalog without importing the optional documentation server. */
127
- export async function readCatalog(specifier = new URL('./catalog.json', import.meta.url)) {
128
- const catalog = await readJson(specifier instanceof URL ? fileURLToPath(specifier) : specifier);
129
- if (catalog.schemaVersion !== catalogVersion) throw new Error(`Unsupported documentation catalog version ${catalog.schemaVersion}.`);
130
- return catalog;
131
- }