@omnitron-dev/prism 0.3.0 → 0.3.1

package/README.md

@@ -39,6 +39,154 @@ function App() {
 }
 ```
 
+## Research documents
+
+`@omnitron-dev/prism/components/research` adds a source-preserving Markdown → typed document → React path. Import `@omnitron-dev/prism/components/research/styles.css` once. It supports GFM, stable Unicode heading anchors, admonitions, tabs, KaTeX and strict Mermaid diagrams. `parseResearchMarkdown(source, documentId)` returns the document tree, heading outline and diagnostics; node attributes retain source positions.
+
+```tsx
+import { ResearchDocument, defineResearchWidget } from '@omnitron-dev/prism/components/research';
+import '@omnitron-dev/prism/components/research/styles.css';
+import { z } from 'zod';
+
+const props = z.object({ value: z.number().finite() }).strict();
+const widgets = {
+  quantity: defineResearchWidget(
+    1,
+    (input) => props.parse(input),
+    ({ value }) => <output aria-label="Quantity">{value}</output>
+  ),
+};
+<ResearchDocument source={markdown} documentId="paper-overview" widgets={widgets} contents />;
+```
+
+Use `$...$` / `$$...$$` for math, a `mermaid` fence for diagrams, and a `prism` fence containing `{"type":"quantity","version":1,"props":{"value":3}}` for a registered widget. `:::note`, `:::warning`, and `:::tabs` with nested `:::tab{label="..."}` use directive syntax. Custom widgets are ordinary host-owned React components with explicit versioned prop validation. The source cannot import JavaScript, register components or grant access. Registries belong to each document, not to process-wide state. `TipTapRenderer` also exposes `nodeRenderers` and `inheritRegisteredNodes`; existing global registrations remain supported by default, while `ResearchDocument` disables inheritance.
+
+Raw HTML and unsupported constructs remain inert with source diagnostics. Unsupported diagram engines retain their source; Pintora is not interpreted as Mermaid. TeX runs with trust disabled and expansion/size limits. Mermaid source cannot change renderer configuration; rendered SVG is sanitized and displayed as an isolated SVG image, preserving the layout styles without inserting document-controlled CSS into the page. Active elements and links are removed; the browser image boundary disables scripting and external resources. Theme changes are serialized. Source/AST/block/edge limits bound accepted input, **not execution time**: Mermaid runs on the browser main thread. Host-owned widgets must independently obey the host's accessibility, resource, network and permission policies. This renderer provides presentation, not proof checking or Noesis semantics. The host owns immutable revision identity, digest verification, authorization and publication. Unknown or failing blocks preserve source rather than masquerading as successful verification.
+
 ## License
 
 MIT
+
+### Theme-native UI primitives
+
+`@omnitron-dev/prism/ui` is a separately built, tree-shakeable entry for MUI
+composition primitives (`Button`, `TextField`, `Tabs`, `Drawer`, `Typography`,
+`ListItemButton`, etc.). It preserves upstream props, slots and keyboard semantics;
+it does not introduce a second set of controls. Use these primitives alongside
+Prism's research editor and knowledge graph under the **same** theme.
+
+```tsx
+import { PrismThemeProvider, Button, TextField } from '@omnitron-dev/prism/ui';
+import { createPrismTheme } from '@omnitron-dev/prism/theme';
+const theme = createPrismTheme({ mode: 'light' });
+<PrismThemeProvider theme={theme}>
+  <TextField label="Title" size="small" />
+  <Button variant="contained">Save</Button>
+</PrismThemeProvider>;
+```
+
+The lightweight provider is appropriate for applications which already own their
+appearance preferences. `PrismProvider` supplies the larger settings/localization
+stack. Do not apply global `button`, `input` or `:focus-visible` appearance rules
+to either provider's controls: configure state styles through the shared theme.
+Keep a visible keyboard-focus indication when integrating legacy stylesheets.
+
+`ResearchDocument` also accepts `sourceProfile="docusaurus"` for explicit
+`{#heading-id}` anchors and namespaced local fragment links. The default research
+profile leaves that syntax literal. This is an inert rendering profile, not an MDX
+runtime or a Docusaurus configuration executor. Corpus routes and semantic metadata
+are supplied by the host's source adapter; Prism does not infer knowledge status.
+
+## Corpus navigation
+
+`@omnitron-dev/prism/components/doc-layout` exposes `DocSidebar`, `DocLayout`
+and `DocSectionNav` without the full component barrel. Sidebar items carry
+stable IDs, labels, optional native hrefs and children. Native hrefs preserve
+modified-click and new-tab navigation; `onItemClick` may route ordinary clicks
+through the host router. Categories announce expansion and remove collapsed
+children from keyboard navigation. No source-format or authorization semantics
+belong in these presentation components.
+
+### Application icon families
+
+Wrap the application (including its theme provider) in `PrismIconProvider` from
+`@omnitron-dev/prism/icons`. Supply components accepting `SvgIconProps`, forwarding
+an SVG ref and retaining MUI's decorative/accessibly labelled behaviour. A partial
+set overrides selected slots; a complete `Record<PrismIconName, PrismIconComponent>`
+provides compile-time coverage. `prismIconNames` enumerates the public slots.
+
+The same context reaches layout controls, search, scientific and rich-text editors,
+graph controls and native MUI slots through portals. Nested providers inherit the
+parent set. Unconfigured slots retain bundled artwork; applications own and license
+their supplied assets. No network icon lookup or DOM replacement is performed.
+Local MUI `slots`, `IconComponent` and `icon` props still take precedence.
+
+```tsx
+import { PrismIconProvider, type PrismIconSet } from '@omnitron-dev/prism/icons';
+const icons = { search: ApplicationSearchIcon } satisfies PrismIconSet;
+<PrismIconProvider icons={icons}>
+  <PrismThemeProvider theme={theme}>{children}</PrismThemeProvider>
+</PrismIconProvider>;
+```
+
+### Scrollbar visibility
+
+Prism's baseline and `Scrollbar` share native, theme-aware scrollbars. On a fine
+pointer they reveal on container hover or `focus-within`, and become transparent
+when idle. Thumb visibility changes neither overflow nor scrollport dimensions.
+Touch input and forced-colors mode retain visible native controls. No mouse
+listener, overlay, delayed timer or scroll-position state is introduced.
+
+Set `<Scrollbar autoHide={false}>` for a persistent thumb, or use
+`mixins.scrollbarStyles(theme, { autoHide: false })` for a custom scrollport.
+`hideScrollbar` remains the explicit fully-hidden option.
+
+
+### Mode-aware application palettes
+
+`PrismProvider.themeOverrides` accepts a static object or a function receiving
+`{ mode: 'light' | 'dark' }`. The provider resolves the operating-system setting
+before calling this function, so an application does not need a second theme
+store or a synchronisation effect. Keep the callback stable when possible.
+
+```tsx
+const appTheme = ({ mode }: PrismThemeOverrideContext) => ({
+  palette: {
+    primary: { main: mode === 'dark' ? '#C9B2FF' : '#7446A6' },
+    background: { paper: mode === 'dark' ? '#241E2C' : '#FFFCF8' },
+  },
+});
+
+<PrismProvider themeOverrides={appTheme}>{children}</PrismProvider>
+```
+
+Import `PrismProvider` and the `PrismThemeOverrideContext` type from
+`@omnitron-dev/prism/core`. The callback is evaluated again when the resolved
+mode changes; existing object overrides retain their behavior.
+
+
+Palette overrides replace dependent tones and channels together: changing `main`
+rebuilds its tonal family; changing an individual colour rebuilds only that
+colour's channel. Explicit shades and channel expressions retain precedence.
+This includes Prism's `lighter`/`darker` and `text.disabledChannel` extensions.
+Opaque static colours receive the higher-contrast black/white `contrastText`
+when none is supplied. Authored contrast colours remain the application's
+responsibility.
+
+For runtime CSS colours (`var(...)`, `oklch(...)`, wide-gamut colours), use
+`themeOverrides={{ cssVariables: { nativeColor: true }, palette: ... }}`. MUI resolves tones and
+contrast in the browser; Prism channels use relative RGB expressions instead
+of guessed numeric values. This requires browser support for CSS relative
+colours and MUI native colour mode. Without native colour mode, an unresolved
+`main` requires explicit `light`, `dark` and `contrastText`; Prism reports this
+contract before MUI's JavaScript colour parser runs. Static presets and
+explicit channel overrides remain supported.
+
+
+### Compact navigation identity
+
+`DashboardLayout` and `Sidenav` accept `compactLogo` for the collapsed or mini
+sidebar. Pass a compact symbol that fits beside the collapse control; the full
+`logo` remains visible in expanded and mobile navigation. Omitting the prop
+preserves the existing logo behavior. The sidebar control stays centred on its
+boundary in either text direction, including enlarged accessible hit targets.

package/dist/blocks/index.js

@@ -1,5 +1,7 @@
-import { ErrorBoundary, Field, EmptyContent, SearchInput } from '../chunk-OBJ244BO.js';
+import { ErrorBoundary, Field, EmptyContent, SearchInput } from '../chunk-GMIE6III.js';
 import { useBoolean } from '../chunk-BRDWQVRT.js';
+import '../chunk-PGHEP4JD.js';
+import '../chunk-BJE2AKD4.js';
 import { createContext, useContext, useCallback, useMemo, useState, useRef, useEffect } from 'react';
 import Box2 from '@mui/material/Box';
 import Paper from '@mui/material/Paper';