@omnitron-dev/lumen-ui 0.0.0-stage → 0.4.8

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 (89) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +93 -2
  3. package/dist/blocks/backlinks.d.ts +7 -0
  4. package/dist/blocks/backlinks.d.ts.map +1 -0
  5. package/dist/blocks/code-block.d.ts +9 -0
  6. package/dist/blocks/code-block.d.ts.map +1 -0
  7. package/dist/blocks/component-example.d.ts +16 -0
  8. package/dist/blocks/component-example.d.ts.map +1 -0
  9. package/dist/blocks/hover-reference-card.d.ts +11 -0
  10. package/dist/blocks/hover-reference-card.d.ts.map +1 -0
  11. package/dist/blocks/index.d.ts +7 -0
  12. package/dist/blocks/index.d.ts.map +1 -0
  13. package/dist/blocks/index.js +4 -0
  14. package/dist/blocks/index.js.map +1 -0
  15. package/dist/blocks/page-agent-actions.d.ts +7 -0
  16. package/dist/blocks/page-agent-actions.d.ts.map +1 -0
  17. package/dist/blocks/theorem-block.d.ts +15 -0
  18. package/dist/blocks/theorem-block.d.ts.map +1 -0
  19. package/dist/chunk-AQ5PPDEV.js +590 -0
  20. package/dist/chunk-AQ5PPDEV.js.map +1 -0
  21. package/dist/chunk-HCY4QR4M.js +197 -0
  22. package/dist/chunk-HCY4QR4M.js.map +1 -0
  23. package/dist/chunk-HLB7FMNG.js +536 -0
  24. package/dist/chunk-HLB7FMNG.js.map +1 -0
  25. package/dist/chunk-L2KGVOK3.js +21 -0
  26. package/dist/chunk-L2KGVOK3.js.map +1 -0
  27. package/dist/chunk-XUGEOYWY.js +117 -0
  28. package/dist/chunk-XUGEOYWY.js.map +1 -0
  29. package/dist/chunk-ZWYLETDL.js +363 -0
  30. package/dist/chunk-ZWYLETDL.js.map +1 -0
  31. package/dist/hydration/context.d.ts +17 -0
  32. package/dist/hydration/context.d.ts.map +1 -0
  33. package/dist/hydration/document-tabs.d.ts +4 -0
  34. package/dist/hydration/document-tabs.d.ts.map +1 -0
  35. package/dist/hydration/host.d.ts +13 -0
  36. package/dist/hydration/host.d.ts.map +1 -0
  37. package/dist/hydration/index.d.ts +5 -0
  38. package/dist/hydration/index.d.ts.map +1 -0
  39. package/dist/hydration/index.js +5 -0
  40. package/dist/hydration/index.js.map +1 -0
  41. package/dist/hydration/shell.d.ts +19 -0
  42. package/dist/hydration/shell.d.ts.map +1 -0
  43. package/dist/hydration/triggers.d.ts +25 -0
  44. package/dist/hydration/triggers.d.ts.map +1 -0
  45. package/dist/index.d.ts +10 -0
  46. package/dist/index.d.ts.map +1 -0
  47. package/dist/index.js +9 -0
  48. package/dist/index.js.map +1 -0
  49. package/dist/interactive/api-explorer.d.ts +34 -0
  50. package/dist/interactive/api-explorer.d.ts.map +1 -0
  51. package/dist/interactive/index.d.ts +5 -0
  52. package/dist/interactive/index.d.ts.map +1 -0
  53. package/dist/interactive/index.js +5 -0
  54. package/dist/interactive/index.js.map +1 -0
  55. package/dist/interactive/mermaid-diagram.d.ts +7 -0
  56. package/dist/interactive/mermaid-diagram.d.ts.map +1 -0
  57. package/dist/interactive/playground-execution.d.ts +14 -0
  58. package/dist/interactive/playground-execution.d.ts.map +1 -0
  59. package/dist/interactive/playground-worker.d.ts +2 -0
  60. package/dist/interactive/playground-worker.d.ts.map +1 -0
  61. package/dist/interactive/playground.d.ts +32 -0
  62. package/dist/interactive/playground.d.ts.map +1 -0
  63. package/dist/navigation/doc-layout.d.ts +9 -0
  64. package/dist/navigation/doc-layout.d.ts.map +1 -0
  65. package/dist/navigation/footer.d.ts +30 -0
  66. package/dist/navigation/footer.d.ts.map +1 -0
  67. package/dist/navigation/index.d.ts +6 -0
  68. package/dist/navigation/index.d.ts.map +1 -0
  69. package/dist/navigation/index.js +4 -0
  70. package/dist/navigation/index.js.map +1 -0
  71. package/dist/navigation/navbar.d.ts +30 -0
  72. package/dist/navigation/navbar.d.ts.map +1 -0
  73. package/dist/navigation/pagination.d.ts +19 -0
  74. package/dist/navigation/pagination.d.ts.map +1 -0
  75. package/dist/navigation/section-nav.d.ts +18 -0
  76. package/dist/navigation/section-nav.d.ts.map +1 -0
  77. package/dist/playground-worker.js +15 -0
  78. package/dist/playground-worker.js.map +1 -0
  79. package/dist/search/index.d.ts +4 -0
  80. package/dist/search/index.d.ts.map +1 -0
  81. package/dist/search/index.js +4 -0
  82. package/dist/search/index.js.map +1 -0
  83. package/dist/search/netron-adapter.d.ts +25 -0
  84. package/dist/search/netron-adapter.d.ts.map +1 -0
  85. package/dist/search/pagefind-adapter.d.ts +20 -0
  86. package/dist/search/pagefind-adapter.d.ts.map +1 -0
  87. package/dist/search/search-dialog.d.ts +40 -0
  88. package/dist/search/search-dialog.d.ts.map +1 -0
  89. package/package.json +83 -3
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 LuxQuant
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,94 @@
1
- # Temporary Holding Version
1
+ # @omnitron-dev/lumen-ui
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ React components for Lumen documentation: navigation, document blocks, search and interactive islands that share the host's Prism context. Use the Lumen CLI for a complete site, or embed this package in an existing React application.
4
+
5
+ ## Capabilities
6
+
7
+ - A shared document shell and selective island activation.
8
+ - Document tabs preserve labelled sections in static HTML. The shell adds Prism tabs with keyboard selection, fragment navigation and optional same-page synchronization through `syncKey`.
9
+ - Navigation, mathematical blocks, code examples and reference cards.
10
+ - Pagefind and Netron search adapters.
11
+ - Mermaid diagrams and host-controlled API or Netron playgrounds.
12
+
13
+ ## Quick start
14
+
15
+ ```sh
16
+ pnpm add @omnitron-dev/lumen-ui react react-dom
17
+ ```
18
+
19
+ ```tsx
20
+ import { useState } from 'react';
21
+ import { LumenShell, PortalIslandHost } from '@omnitron-dev/lumen-ui/runtime';
22
+
23
+ function Counter({ initial = 0 }: { initial?: number }) {
24
+ const [count, setCount] = useState(initial);
25
+ return <button onClick={() => setCount(value => value + 1)}>{count}</button>;
26
+ }
27
+
28
+ export function Documentation() {
29
+ return (
30
+ <LumenShell theme="dark" locale="en" currentPath="/guide" islands={{ Counter }}>
31
+ <PortalIslandHost
32
+ islandId="guide-counter"
33
+ component="Counter"
34
+ hydrate="visible"
35
+ props={{ initial: 3 }}
36
+ >
37
+ <span>Counter starts at 3.</span>
38
+ </PortalIslandHost>
39
+ </LumenShell>
40
+ );
41
+ }
42
+ ```
43
+
44
+ React and React DOM 19 are required. The Lumen builder supplies default layout styles; embedding applications own their styles. `LumenShell` supplies Prism by default. Set `disablePrismProvider` when the host already owns that provider.
45
+
46
+ ## Current section navigation
47
+
48
+ `DocSectionNav` from `/layout` renders native anchor links on the server. Mount it as an island to track the current section of an existing document:
49
+
50
+ ```tsx
51
+ <PortalIslandHost islandId="page-toc" component="DocSectionNav" hydrate="load" props={{ headings }}>
52
+ <DocSectionNav headings={headings} />
53
+ </PortalIslandHost>
54
+ ```
55
+
56
+ Each heading has `{ id, title, level }` and must refer to a real document anchor. The default Lumen client registers this component; custom clients add `DocSectionNav` to their existing `LumenShell` island registry. Style `[aria-current="location"]` or `.is-active` in the host stylesheet.
57
+
58
+ `DocPagination` from `/layout` renders native previous and next links with the document titles and directional Prism icons. Pass each available neighbour as `{ href, label }`. Set `labels={{ navigation, previous, next }}` to translate the landmark and directions. The links work before hydration and follow the document's reading direction.
59
+
60
+ The shared Prism scrollspy tracks the last section start above the reading line, including long sections and the final short section at the bottom. CSS `scroll-padding-top` on the scrolling element and `scroll-margin-top` on headings account for fixed headers; an explicit `offset` overrides the reading-line padding. Native links retain keyboard behavior and browser history, with no forced smooth scrolling. An explicit anchor destination near the bottom remains selected until the reader scrolls. Supplying `activeId` instead makes the indicator controlled by the host.
61
+
62
+ ## Live component examples
63
+
64
+ `ComponentExample` from `@omnitron-dev/lumen-ui/blocks` displays a trusted component and the source used to build it. With Vite, import that module normally for its preview and with `?raw` for its source.
65
+
66
+ ```tsx
67
+ import { ComponentExample } from '@omnitron-dev/lumen-ui/blocks';
68
+ import Counter from './counter';
69
+ import source from './counter.tsx?raw';
70
+
71
+ <ComponentExample title="Counter" code={source} resettable>
72
+ <Counter />
73
+ </ComponentExample>
74
+ ```
75
+
76
+ Both the preview and source render on the server. The native source disclosure works with a keyboard and with JavaScript disabled. After hydration, `resettable` lets readers restore the preview's initial state while keeping the source open. Set `language` for a non-TSX module and translate the control labels through `labels.source` and `labels.reset`.
77
+
78
+ ## Runtime boundaries
79
+
80
+ Islands mount through portals into static hosts, preserving the shell's context. They do not create independent React roots or hydrate arbitrary third-party HTML. Use one manager per document, unique island IDs and host-owned component registrations. Activation supports `load`, `visible`, `interaction` and `idle`.
81
+
82
+ Props use the shared Lumen AST JSON codec. Invalid metadata reports an error instead of mounting with empty props; unknown components retain their static fallback. Documents cannot register application code or grant network permissions. Live API and Netron playgrounds require explicit host capabilities and server authorization. Mermaid uses strict configuration and sanitized SVG images.
83
+
84
+ A component that throws while rendering shows an alert at its own island with its registered name and the error message. Other islands retain their state. Correcting the failed island's props or replacing its registered component retries that island.
85
+
86
+ ## Documentation
87
+
88
+ [Public API](src/index.ts) · [Package exports](package.json) · [Lumen](../lumen/README.md)
89
+
90
+ The `/runtime`, `/layout`, `/blocks` and `/search` entries expose their corresponding components without requiring a root import.
91
+
92
+ ## License
93
+
94
+ [MIT](../../LICENSE).
@@ -0,0 +1,7 @@
1
+ import React from 'react';
2
+ export interface BacklinksSectionProps {
3
+ backlinks?: string[];
4
+ className?: string;
5
+ }
6
+ export declare function BacklinksSection({ backlinks, className }: BacklinksSectionProps): React.JSX.Element;
7
+ //# sourceMappingURL=backlinks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"backlinks.d.ts","sourceRoot":"","sources":["../../src/blocks/backlinks.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,EAAE,SAAc,EAAE,SAAS,EAAE,EAAE,qBAAqB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAOxG"}
@@ -0,0 +1,9 @@
1
+ import React from 'react';
2
+ export interface CodeBlockProps {
3
+ code?: string;
4
+ language?: string;
5
+ copyable?: boolean;
6
+ className?: string;
7
+ }
8
+ export declare function CodeBlock({ code, language, copyable, className }: CodeBlockProps): React.JSX.Element;
9
+ //# sourceMappingURL=code-block.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"code-block.d.ts","sourceRoot":"","sources":["../../src/blocks/code-block.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAYD,wBAAgB,SAAS,CAAC,EAAE,IAAS,EAAE,QAAe,EAAE,QAAgB,EAAE,SAAS,EAAE,EAAE,cAAc,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAOxH"}
@@ -0,0 +1,16 @@
1
+ import React, { type ReactNode } from 'react';
2
+ export interface ComponentExampleProps {
3
+ title: string;
4
+ /** The build-time source of the trusted component supplied as children. */
5
+ code: string;
6
+ children: ReactNode;
7
+ language?: string;
8
+ resettable?: boolean;
9
+ labels?: {
10
+ source?: string;
11
+ reset?: string;
12
+ };
13
+ }
14
+ /** A rendered example and its exact source, both present in the server HTML. */
15
+ export declare function ComponentExample({ title, code, children, language, resettable, labels, }: ComponentExampleProps): React.JSX.Element;
16
+ //# sourceMappingURL=component-example.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"component-example.d.ts","sourceRoot":"","sources":["../../src/blocks/component-example.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAA6B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAKzE,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C;AAED,gFAAgF;AAChF,wBAAgB,gBAAgB,CAAC,EAC/B,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAgB,EAAE,UAAkB,EAAE,MAAM,GACpE,EAAE,qBAAqB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA6B3C"}
@@ -0,0 +1,11 @@
1
+ import React, { type ReactNode } from 'react';
2
+ export interface HoverReferenceCardProps {
3
+ id: string;
4
+ targetTitle?: string;
5
+ refKind?: 'thm' | 'def' | 'ax' | 'api' | 'doc' | string;
6
+ excerpt?: string;
7
+ children?: ReactNode;
8
+ className?: string;
9
+ }
10
+ export declare function HoverReferenceCard({ id, targetTitle, className }: HoverReferenceCardProps): React.JSX.Element;
11
+ //# sourceMappingURL=hover-reference-card.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hover-reference-card.d.ts","sourceRoot":"","sources":["../../src/blocks/hover-reference-card.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG9C,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,uBAAuB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAM7G"}
@@ -0,0 +1,7 @@
1
+ export * from './theorem-block.js';
2
+ export * from './hover-reference-card.js';
3
+ export * from './code-block.js';
4
+ export * from './component-example.js';
5
+ export * from './backlinks.js';
6
+ export * from './page-agent-actions.js';
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,wBAAwB,CAAC;AACvC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC"}
@@ -0,0 +1,4 @@
1
+ "use client";
2
+ export { BacklinksSection, CodeBlock, ComponentExample, HoverReferenceCard, MathTheoremBlock, PageAgentActions } from '../chunk-XUGEOYWY.js';
3
+ //# sourceMappingURL=index.js.map
4
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"sources":[],"names":[],"mappings":";","file":"index.js"}
@@ -0,0 +1,7 @@
1
+ import React from 'react';
2
+ export interface PageAgentActionsProps {
3
+ path: string;
4
+ className?: string;
5
+ }
6
+ export declare function PageAgentActions({ path, className }: PageAgentActionsProps): React.JSX.Element;
7
+ //# sourceMappingURL=page-agent-actions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"page-agent-actions.d.ts","sourceRoot":"","sources":["../../src/blocks/page-agent-actions.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,qBAAqB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAM9F"}
@@ -0,0 +1,15 @@
1
+ import React, { type ReactNode } from 'react';
2
+ export type MathEnvironmentType = 'axiom' | 'definition' | 'theorem' | 'lemma' | 'proposition' | 'corollary' | 'proof' | 'remark' | 'example' | 'hypothesis';
3
+ export interface MathTheoremBlockProps {
4
+ id: string;
5
+ title?: string;
6
+ envType?: MathEnvironmentType;
7
+ status?: string;
8
+ number?: string;
9
+ dependsOn?: string[];
10
+ proves?: string[];
11
+ children?: ReactNode;
12
+ className?: string;
13
+ }
14
+ export declare function MathTheoremBlock({ id, title, envType, status, number, dependsOn, proves, children, className, }: MathTheoremBlockProps): React.JSX.Element;
15
+ //# sourceMappingURL=theorem-block.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"theorem-block.d.ts","sourceRoot":"","sources":["../../src/blocks/theorem-block.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAG9C,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,YAAY,GACZ,SAAS,GACT,OAAO,GACP,aAAa,GACb,WAAW,GACX,OAAO,GACP,QAAQ,GACR,SAAS,GACT,YAAY,CAAC;AAEjB,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,EAAE,EACF,KAAK,EACL,OAAmB,EACnB,MAAM,EACN,MAAM,EACN,SAAS,EACT,MAAM,EACN,QAAQ,EACR,SAAS,GACV,EAAE,qBAAqB,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAwB3C"}