@public-ui/sample-react 4.3.1-rc.1 → 4.3.1-rc.4

package/src/components/toolbar/disabled.tsx

@@ -1,6 +1,7 @@
 import { KolToolbar } from '@public-ui/react-v19';
 import type { FC } from 'react';
 import React from 'react';
+import { SampleBlock } from '../SampleBlock';
 import { SampleDescription } from '../SampleDescription';
 
 export const ToolbarDisabled: FC = () => {
@@ -10,48 +11,50 @@ export const ToolbarDisabled: FC = () => {
 				<p>This sample shows KolToolbars with some of the elements disabled.</p>
 			</SampleDescription>
 
-			<KolToolbar
-				_label="Toolbar"
-				class="block w-fit"
-				_items={[
-					{
-						type: 'button',
-						_label: 'Back',
-						_disabled: true,
-						_hideLabel: true,
-						_icons: {
-							left: {
-								icon: 'kolicon-chevron-left',
+			<SampleBlock id="disabled" fitContent>
+				<KolToolbar
+					_label="Toolbar"
+					class="block w-fit"
+					_items={[
+						{
+							type: 'button',
+							_label: 'Back',
+							_disabled: true,
+							_hideLabel: true,
+							_icons: {
+								left: {
+									icon: 'kolicon-chevron-left',
+								},
 							},
 						},
-					},
-					{
-						type: 'button',
-						_label: 'Next',
-						_hideLabel: true,
-						_icons: {
-							right: {
-								icon: 'kolicon-chevron-right',
+						{
+							type: 'button',
+							_label: 'Next',
+							_hideLabel: true,
+							_icons: {
+								right: {
+									icon: 'kolicon-chevron-right',
+								},
 							},
 						},
-					},
-					{
-						type: 'link',
-						_href: '#/back-page',
-						_label: 'Simple Link 1',
-					},
-					{
-						type: 'link',
-						_href: '#/back-page',
-						_disabled: true,
-						_label: 'Simple Link 3',
-					},
-					{
-						type: 'button',
-						_label: 'Bold',
-					},
-				]}
-			/>
+						{
+							type: 'link',
+							_href: '#/back-page',
+							_label: 'Simple Link 1',
+						},
+						{
+							type: 'link',
+							_href: '#/back-page',
+							_disabled: true,
+							_label: 'Simple Link 3',
+						},
+						{
+							type: 'button',
+							_label: 'Bold',
+						},
+					]}
+				/>
+			</SampleBlock>
 		</>
 	);
 };

package/src/components/tree/basic.tsx

@@ -4,6 +4,7 @@ import React, { useContext, useState } from 'react';
 import { useParams } from 'react-router';
 import { HideMenusContext } from '../../shares/HideMenusContext';
 import { getRandomEmoji } from '../../shares/randomEmoji';
+import { SampleBlock } from '../SampleBlock';
 import { SampleDescription } from '../SampleDescription';
 
 export const TreeBasic: FC = () => {
@@ -30,38 +31,40 @@ export const TreeBasic: FC = () => {
 				<p>KolTree renders a keyboard accessible nested navigation. Branches of the tree can be collapsed or expanded.</p>
 			</SampleDescription>
 
-			<KolTree _label="Sitemap" class="block w-fit">
-				<KolTreeItem _label={homeLabel} {...getItemProps('home')}></KolTreeItem>
-				<KolTreeItem _label="2 About (open initially)" {...getItemProps('about')} _open>
-					<KolTreeItem _label="2.0 Legal" {...getItemProps('legal')}></KolTreeItem>
-					<KolTreeItem _label="2.1 Team" {...getItemProps('team')}>
-						<KolTreeItem _label="2.1.1. Values" {...getItemProps('values')}></KolTreeItem>
-						<KolTreeItem _label="2.1.2. Members" {...getItemProps('members')}>
-							<KolTreeItem _label="2.1.2.1 Humans" {...getItemProps('humans')}></KolTreeItem>
-							{showPets && <KolTreeItem _label="2.1.2.2 Pets" {...getItemProps('pets')}></KolTreeItem>}
-						</KolTreeItem>
-						<KolTreeItem _label="2.1.3 Locations" {...getItemProps('locations')}>
-							{showEurope && (
-								<KolTreeItem _label="2.1.3.1 Europe" {...getItemProps('europe')}>
-									<KolTreeItem _label="2.1.3.1.1 Denmark" {...getItemProps('denmark')} />
-									<KolTreeItem _label="2.1.3.1.2 Netherlands" {...getItemProps('netherlands')} />
-								</KolTreeItem>
-							)}
+			<SampleBlock id="tree" fitContent>
+				<KolTree _label="Sitemap" class="block w-fit">
+					<KolTreeItem _label={homeLabel} {...getItemProps('home')}></KolTreeItem>
+					<KolTreeItem _label="2 About (open initially)" {...getItemProps('about')} _open>
+						<KolTreeItem _label="2.0 Legal" {...getItemProps('legal')}></KolTreeItem>
+						<KolTreeItem _label="2.1 Team" {...getItemProps('team')}>
+							<KolTreeItem _label="2.1.1. Values" {...getItemProps('values')}></KolTreeItem>
+							<KolTreeItem _label="2.1.2. Members" {...getItemProps('members')}>
+								<KolTreeItem _label="2.1.2.1 Humans" {...getItemProps('humans')}></KolTreeItem>
+								{showPets && <KolTreeItem _label="2.1.2.2 Pets" {...getItemProps('pets')}></KolTreeItem>}
+							</KolTreeItem>
+							<KolTreeItem _label="2.1.3 Locations" {...getItemProps('locations')}>
+								{showEurope && (
+									<KolTreeItem _label="2.1.3.1 Europe" {...getItemProps('europe')}>
+										<KolTreeItem _label="2.1.3.1.1 Denmark" {...getItemProps('denmark')} />
+										<KolTreeItem _label="2.1.3.1.2 Netherlands" {...getItemProps('netherlands')} />
+									</KolTreeItem>
+								)}
+							</KolTreeItem>
 						</KolTreeItem>
 					</KolTreeItem>
-				</KolTreeItem>
-				{showProducts && (
-					<KolTreeItem _label="3. Products" {...getItemProps('products')}>
-						<KolTreeItem _label="3.1 Home" {...getItemProps('home-products')}>
-							<KolTreeItem _label="3.1.1 Refrigerators" {...getItemProps('fridges')}></KolTreeItem>
-							<KolTreeItem _label="3.1.2 Coffee makers" {...getItemProps('coffee-makers')}></KolTreeItem>
-						</KolTreeItem>
-						<KolTreeItem _label="3.1 Office" {...getItemProps('office-products')}>
-							<KolTreeItem _label="3.2.1 Printers" {...getItemProps('printers')}></KolTreeItem>
+					{showProducts && (
+						<KolTreeItem _label="3. Products" {...getItemProps('products')}>
+							<KolTreeItem _label="3.1 Home" {...getItemProps('home-products')}>
+								<KolTreeItem _label="3.1.1 Refrigerators" {...getItemProps('fridges')}></KolTreeItem>
+								<KolTreeItem _label="3.1.2 Coffee makers" {...getItemProps('coffee-makers')}></KolTreeItem>
+							</KolTreeItem>
+							<KolTreeItem _label="3.1 Office" {...getItemProps('office-products')}>
+								<KolTreeItem _label="3.2.1 Printers" {...getItemProps('printers')}></KolTreeItem>
+							</KolTreeItem>
 						</KolTreeItem>
-					</KolTreeItem>
-				)}
-			</KolTree>
+					)}
+				</KolTree>
+			</SampleBlock>
 
 			<p>Current tree item: {subPage ?? 'none'}</p>
 

package/src/components/version/basic.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { KolVersion } from '@public-ui/react-v19';
 
 import type { FC } from 'react';
+import { SampleBlock } from '../SampleBlock';
 import { SampleDescription } from '../SampleDescription';
 export const VersionBasic: FC = () => (
 	<>
@@ -10,6 +11,8 @@ export const VersionBasic: FC = () => (
 			<p>KolVersion renders a label showing the given version number.</p>
 		</SampleDescription>
 
-		<KolVersion _label="1.1.1" />
+		<SampleBlock id="basic" fitContent>
+			<KolVersion _label="1.1.1" />
+		</SampleBlock>
 	</>
 );

package/src/components/version/context.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import { KolVersion } from '@public-ui/react-v19';
 
 import type { FC } from 'react';
+import { SampleBlock } from '../SampleBlock';
 import { SampleDescription } from '../SampleDescription';
 
 export const VersionContext: FC = () => (
@@ -11,10 +12,12 @@ export const VersionContext: FC = () => (
 			<p>This sample shows KolVersion inline with text paragraph content.</p>
 		</SampleDescription>
 
-		<p>
-			<KolVersion _label="1.0.0" /> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna
-			aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem
-			ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor.
-		</p>
+		<SampleBlock id="context">
+			<p>
+				<KolVersion _label="1.0.0" /> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna
+				aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem
+				ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor.
+			</p>
+		</SampleBlock>
 	</>
 );

package/src/hooks/useVisualBlockOutline.ts

@@ -0,0 +1,38 @@
+import { useEffect } from 'react';
+import { useSearchParams } from 'react-router';
+
+import { readStoredVisualBlockOutline, setVisualBlockOutline, toggleVisualBlockOutline } from '../shares/visualBlockOutline';
+
+const SEARCH_PARAM = 'visualBlocks';
+const DISABLED_VALUES = ['0', 'false', 'off'];
+
+/**
+ * Makes the `data-visual-block` outline (see `shares/visualBlockOutline`) switchable at runtime:
+ * - `?visualBlocks` enables it for the current URL, `?visualBlocks=0` disables it – combinable with `?hideMenus`,
+ * - `Ctrl+Alt+B` toggles it without a reload and remembers the choice for the next visit.
+ *
+ * Without the URL parameter the remembered choice applies; the parameter always wins.
+ */
+export const useVisualBlockOutline = () => {
+	const [searchParams] = useSearchParams();
+	const param = searchParams.get(SEARCH_PARAM);
+
+	useEffect(() => {
+		if (param === null) {
+			setVisualBlockOutline(readStoredVisualBlockOutline(), false);
+		} else {
+			setVisualBlockOutline(!DISABLED_VALUES.includes(param.toLowerCase()), false);
+		}
+	}, [param]);
+
+	useEffect(() => {
+		const handleKeyDown = (event: KeyboardEvent) => {
+			if (event.ctrlKey && event.altKey && !event.shiftKey && event.key.toLowerCase() === 'b') {
+				event.preventDefault();
+				toggleVisualBlockOutline();
+			}
+		};
+		document.addEventListener('keydown', handleKeyDown);
+		return () => document.removeEventListener('keydown', handleKeyDown);
+	}, []);
+};

package/src/scenarios/button-shortkey-table.tsx

@@ -1,8 +1,9 @@
 import type { KoliBriTableHeaders } from '@public-ui/components';
 import { ToasterService } from '@public-ui/components';
-import { createReactRenderElement, KolButton, KolHeading, KolTableStateful } from '@public-ui/react-v19';
+import { createReactRenderElement, KolButton, KolTableStateful } from '@public-ui/react-v19';
 import type { FC } from 'react';
 import React, { useRef } from 'react';
+import { SampleBlock } from '../components/SampleBlock';
 import { SampleDescription } from '../components/SampleDescription';
 import { getRoot } from '../shares/react-roots';
 
@@ -113,8 +114,7 @@ export const ButtonShortkeyTable: FC = () => {
 			</SampleDescription>
 
 			<div className="grid gap-8">
-				<section className="grid gap-4">
-					<KolHeading _level={2} _label="Interactive Table with Button Shortkeys" />
+				<SampleBlock id="interactive-table-button" heading="Interactive Table with Button Shortkeys">
 					<KolTableStateful
 						_label={`Interactive table with shortkey buttons in each row`}
 						_data={DATA}
@@ -123,7 +123,7 @@ export const ButtonShortkeyTable: FC = () => {
 							_page: 1,
 						}}
 					/>
-				</section>
+				</SampleBlock>
 			</div>
 		</>
 	);

package/src/shares/store.ts

@@ -94,7 +94,3 @@ export const getThemeName = (theme: string) => {
 export const setCustomThemes = (themes: Theme[] | undefined) => {
 	STORE.customThemes = themes;
 };
-
-export const getCustomThemes = (): Theme[] | undefined => {
-	return STORE.customThemes;
-};

package/src/shares/visualBlockOutline.ts

@@ -0,0 +1,75 @@
+/**
+ * Debug aid for the visual tests: draws an outline around every `data-visual-block` container
+ * (see `components/SampleBlock`) so you can see what an element screenshot actually captures.
+ * Blocks excluded via SampleBlock's `skipSnapshot` prop are outlined red instead of blue, so it is
+ * visible at a glance which sample is captured and which one is only there to be looked at.
+ *
+ * It is off by default and never ends up in a snapshot:
+ * - it is drawn as an `outline`, which takes no space – the layout is identical whether it is on or off,
+ * - Playwright starts each run with a fresh browser context, so the stored preference can't leak into it.
+ *
+ * See `hooks/useVisualBlockOutline` for the URL parameter and the keyboard shortcut.
+ */
+
+const ROOT_ATTRIBUTE = 'data-visual-blocks';
+const STORAGE_KEY = 'public-ui.sample.visual-blocks';
+const SKIPPED_ATTRIBUTE = 'data-visual-block-skipped';
+const STYLE_ELEMENT_ID = 'visual-block-outline-style';
+const STYLE_CONTENT = `
+	html[${ROOT_ATTRIBUTE}] [data-visual-block] {
+		outline: 2px solid darkblue;
+		outline-offset: 0;
+	}
+	html[${ROOT_ATTRIBUTE}] [${SKIPPED_ATTRIBUTE}] {
+		outline: 2px solid orangered;
+		outline-offset: 0;
+	}
+`;
+
+/**
+ * The rule lives here instead of in the host apps' stylesheets (visual-tests app, presentation app),
+ * so this debug feature stays in the single package that owns `data-visual-block`.
+ */
+function ensureStyleElement(): void {
+	if (document.getElementById(STYLE_ELEMENT_ID)) {
+		return;
+	}
+	const style = document.createElement('style');
+	style.id = STYLE_ELEMENT_ID;
+	style.textContent = STYLE_CONTENT;
+	document.head.appendChild(style);
+}
+
+function isVisualBlockOutlineEnabled(): boolean {
+	return document.documentElement.hasAttribute(ROOT_ATTRIBUTE);
+}
+
+export function setVisualBlockOutline(enabled: boolean, persist = true): void {
+	ensureStyleElement();
+	if (enabled) {
+		document.documentElement.setAttribute(ROOT_ATTRIBUTE, '');
+	} else {
+		document.documentElement.removeAttribute(ROOT_ATTRIBUTE);
+	}
+	if (persist) {
+		try {
+			localStorage.setItem(STORAGE_KEY, enabled ? '1' : '0');
+		} catch {
+			// Storage can be unavailable (private mode, blocked cookies) – the outline just won't be remembered.
+		}
+	}
+}
+
+export function toggleVisualBlockOutline(): boolean {
+	const enabled = !isVisualBlockOutlineEnabled();
+	setVisualBlockOutline(enabled);
+	return enabled;
+}
+
+export function readStoredVisualBlockOutline(): boolean {
+	try {
+		return localStorage.getItem(STORAGE_KEY) === '1';
+	} catch {
+		return false;
+	}
+}

package/src/components/badge/button.tsx

@@ -1,35 +0,0 @@
-import type { FC } from 'react';
-import React from 'react';
-
-import { KolBadge } from '@public-ui/react-v19';
-import { SampleDescription } from '../SampleDescription';
-
-const createBadgeProps = (label: string) => ({
-	_label: label,
-	_smartButton: {
-		_ariaDescription: label,
-		_icons: 'kolicon-cross',
-		_label: `Remove`,
-		_on: {
-			onClick: () => alert('clicked'),
-		},
-	},
-});
-
-export const BadgeButton: FC = () => (
-	<>
-		<SampleDescription>
-			<p>
-				This sample shows KolBadge with an optional <code>smartButton</code>. The sample defines a &quot;close&quot; button with X-icon a click event listener.
-			</p>
-		</SampleDescription>
-
-		<div className="flex flex-wrap gap-2">
-			<KolBadge {...createBadgeProps('black')}></KolBadge>
-			<KolBadge _color="#86ffc6" {...createBadgeProps('teal')}></KolBadge>
-			<KolBadge _color="#06539e" {...createBadgeProps('blue')}></KolBadge>
-			<KolBadge _color="#ae0000" _icons="kolicon-house" {...createBadgeProps('red with icon')}></KolBadge>
-			<KolBadge _color="#8b008b" _icons="kolicon-kolibri" {...createBadgeProps('purple with icon')}></KolBadge>
-		</div>
-	</>
-);

package/src/components/badge/formatted-label.tsx

@@ -1,19 +0,0 @@
-import { KolBadge } from '@public-ui/react-v19';
-import * as React from 'react';
-import { SampleDescription } from '../SampleDescription';
-
-export const FormattedLabel = () => {
-	return (
-		<>
-			<SampleDescription>
-				<p>This sample demonstrates the possibility of formatted text in badges via markdown syntax.</p>
-			</SampleDescription>
-
-			<div className="flex flex-col gap-4">
-				<KolBadge _color="#7db4ebff" _label="**Bold** and _italic_ Markdown label" />
-				<KolBadge _color="#8feb7dff" _label="This is ~~strikethrough~~ text" />
-				<KolBadge _color="#e6ee8eff" _label="Source code like `y = mx + n` is possible" />
-			</div>
-		</>
-	);
-};

package/src/components/spin/custom.tsx

@@ -1,23 +0,0 @@
-import { SampleDescription } from '../SampleDescription';
-import './custom.css';
-
-import React from 'react';
-
-import { KolSpin } from '@public-ui/react-v19';
-
-import type { FC } from 'react';
-
-export const SpinCustom: FC = () => (
-	<>
-		<SampleDescription>
-			<p>
-				This sample shows a custom loading animation. Using the expert slot, it is possible to insert custom animations. Custom animations are not necessarily
-				barrier-free.
-			</p>
-		</SampleDescription>
-
-		<KolSpin _show _variant="none">
-			<span slot="expert" className="loader"></span>
-		</KolSpin>
-	</>
-);

package/src/components/spin/cycle.tsx

@@ -1,16 +0,0 @@
-import React from 'react';
-
-import { KolSpin } from '@public-ui/react-v19';
-
-import type { FC } from 'react';
-import { SampleDescription } from '../SampleDescription';
-
-export const SpinCycle: FC = () => (
-	<>
-		<SampleDescription>
-			<p>This sample shows the KolSpin variant &quot;cycle&quot; and that you can change its color and size.</p>
-		</SampleDescription>
-
-		<KolSpin _show _variant="cycle" />
-	</>
-);

package/src/components/spin/label.tsx

@@ -1,23 +0,0 @@
-import { KolSpin } from '@public-ui/react-v19';
-import type { FC } from 'react';
-import React, { useEffect, useState } from 'react';
-import { SampleDescription } from '../SampleDescription';
-
-export const SpinLabel: FC = () => {
-	const [show, setShow] = useState(true);
-
-	useEffect(() => {
-		const id = setInterval(() => setShow((value) => !value), 3000);
-		return () => clearInterval(id);
-	}, []);
-
-	return (
-		<>
-			<SampleDescription>
-				<p>This sample shows KolSpin with a label.</p>
-			</SampleDescription>
-
-			<KolSpin _show={show} _label={show ? 'Loading data...' : 'Data loaded.'} />
-		</>
-	);
-};

package/src/components/spin/variables.tsx

@@ -1,16 +0,0 @@
-import React from 'react';
-
-import { KolSpin } from '@public-ui/react-v19';
-
-import type { FC } from 'react';
-import { SampleDescription } from '../SampleDescription';
-
-export const SpinVariables: FC = () => (
-	<>
-		<SampleDescription>
-			<p>You can change the color and size of the spinners with CSS properties.</p>
-		</SampleDescription>
-
-		<KolSpin _show style={{ '--kol-spin-color': 'green', '--kol-spin-size': '80' }} />
-	</>
-);