@maxal_studio/kratosjs-react 1.0.0

package/src/slots/SlotCluster.test.tsx

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { SlotCluster } from './SlotCluster';
+import { SlotRegistryProvider } from '../contexts/SlotRegistryContext';
+import type { ResolvedSlots } from './types';
+
+function item(id: string, label: string) {
+	return { id, render: () => <button data-testid="cluster-item">{label}</button> };
+}
+
+function renderCluster(slots: ResolvedSlots, maxInline?: number) {
+	return render(
+		<SlotRegistryProvider slots={slots}>
+			<SlotCluster name="header.right" maxInline={maxInline} />
+		</SlotRegistryProvider>,
+	);
+}
+
+/** Trigger buttons are the overflow ("…") menu toggles, marked aria-haspopup="menu". */
+function overflowTriggers(container: HTMLElement): HTMLButtonElement[] {
+	return Array.from(container.querySelectorAll<HTMLButtonElement>('button[aria-haspopup="menu"]'));
+}
+
+describe('SlotCluster', () => {
+	it('renders nothing when the slot is empty', () => {
+		const { container } = renderCluster({});
+		expect(container).toBeEmptyDOMElement();
+	});
+
+	it('renders the first maxInline contributions inline', () => {
+		renderCluster(
+			{
+				'header.right': [item('a', 'one'), item('b', 'two'), item('c', 'three')],
+			},
+			2,
+		);
+		// Only the two inline items are mounted up-front; overflow lives in closed menus.
+		const inline = screen.getAllByTestId('cluster-item');
+		expect(inline.map(el => el.textContent)).toEqual(['one', 'two']);
+	});
+
+	it('collapses extras into a dropdown that opens and closes', () => {
+		const { container } = renderCluster(
+			{
+				'header.right': [item('a', 'one'), item('b', 'two'), item('c', 'three')],
+			},
+			2,
+		);
+
+		// The third item is not shown until an overflow menu opens.
+		expect(screen.queryByText('three')).not.toBeInTheDocument();
+
+		// The desktop overflow trigger is the first haspopup button.
+		const [desktopTrigger] = overflowTriggers(container);
+		expect(desktopTrigger).toBeTruthy();
+
+		fireEvent.click(desktopTrigger);
+		expect(screen.getByText('three')).toBeInTheDocument();
+		expect(desktopTrigger).toHaveAttribute('aria-expanded', 'true');
+
+		// Escape closes it.
+		fireEvent.keyDown(document, { key: 'Escape' });
+		expect(screen.queryByText('three')).not.toBeInTheDocument();
+	});
+
+	it('closes the menu on an outside click', () => {
+		const { container } = renderCluster(
+			{
+				'header.right': [item('a', 'one'), item('b', 'two'), item('c', 'three')],
+			},
+			2,
+		);
+		const [desktopTrigger] = overflowTriggers(container);
+		fireEvent.click(desktopTrigger);
+		expect(screen.getByText('three')).toBeInTheDocument();
+
+		fireEvent.mouseDown(document.body);
+		expect(screen.queryByText('three')).not.toBeInTheDocument();
+	});
+
+	it('still exposes a mobile overflow menu even when nothing overflows', () => {
+		// With maxInline >= count there are no desktop extras, but the < sm menu
+		// holds everything so a phone-width row never overflows.
+		const { container } = renderCluster({ 'header.right': [item('a', 'one')] }, 5);
+		const triggers = overflowTriggers(container);
+		// Desktop overflow has no items (renders null); only the mobile menu trigger remains.
+		expect(triggers.length).toBe(1);
+
+		// 'one' already renders inline for sm+; opening the mobile menu mounts a second copy.
+		expect(screen.getAllByText('one')).toHaveLength(1);
+		fireEvent.click(triggers[0]);
+		expect(triggers[0]).toHaveAttribute('aria-expanded', 'true');
+		expect(screen.getAllByText('one')).toHaveLength(2);
+	});
+});

package/src/slots/SlotCluster.tsx

@@ -0,0 +1,107 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { MoreHorizontal } from 'lucide-react';
+import { IconButton } from '../components/ui';
+import { cn } from '../utils/classNames';
+import { translate } from '../i18n/activeLocale';
+import { useSlot } from '../contexts/SlotRegistryContext';
+import { renderSlot } from './Slot';
+import type { SlotContext, SlotContribution, SlotName } from './types';
+
+/** A self-contained "…" dropdown holding overflow slot contributions. */
+function OverflowMenu({
+	items,
+	context,
+	className,
+}: {
+	items: SlotContribution[];
+	context: SlotContext;
+	className?: string;
+}) {
+	const [open, setOpen] = useState(false);
+	const ref = useRef<HTMLDivElement>(null);
+
+	useEffect(() => {
+		if (!open) return;
+		const onClick = (event: MouseEvent) => {
+			if (ref.current && !ref.current.contains(event.target as Node)) setOpen(false);
+		};
+		const onEsc = (event: KeyboardEvent) => {
+			if (event.key === 'Escape') setOpen(false);
+		};
+		document.addEventListener('mousedown', onClick);
+		document.addEventListener('keydown', onEsc);
+		return () => {
+			document.removeEventListener('mousedown', onClick);
+			document.removeEventListener('keydown', onEsc);
+		};
+	}, [open]);
+
+	if (items.length === 0) return null;
+
+	return (
+		<div className={cn('relative', className)} ref={ref}>
+			<IconButton
+				variant="ghost"
+				size="sm"
+				aria-label={translate('core:common.more')}
+				aria-expanded={open}
+				aria-haspopup="menu"
+				className="h-9 w-9 shrink-0"
+				onClick={() => setOpen(o => !o)}>
+				<MoreHorizontal className="h-4 w-4" />
+			</IconButton>
+			{open && (
+				<div
+					role="menu"
+					className="absolute right-0 z-50 mt-2 flex w-56 flex-col gap-1 rounded-xl border border-border bg-raised p-2 shadow-soft-lg">
+					{items.map(item => renderSlot(item, context))}
+				</div>
+			)}
+		</div>
+	);
+}
+
+export interface SlotClusterProps {
+	/** The slot to render. */
+	name: SlotName;
+	/** Context passed to each contribution. `slot` is filled in automatically. */
+	context?: Omit<SlotContext, 'slot'>;
+	/**
+	 * How many contributions render inline on `sm`+ screens before the rest
+	 * collapse into a "…" menu. Below `sm`, everything collapses. Default 2.
+	 */
+	maxInline?: number;
+	/** className for the inline flex row. */
+	className?: string;
+}
+
+/**
+ * A responsive slot for tight horizontal areas (header right, table toolbar).
+ * On `sm`+ the first `maxInline` items render inline and any extras fall into a
+ * "…" dropdown; below `sm` every item collapses into the dropdown, so a crowded
+ * slot can never overflow a phone-width row regardless of contributor count.
+ */
+export function SlotCluster({ name, context, maxInline = 2, className }: SlotClusterProps) {
+	const contributions = useSlot(name);
+	if (contributions.length === 0) return null;
+
+	const fullContext: SlotContext = { ...context, slot: name };
+	const inline = contributions.slice(0, maxInline);
+	const overflow = contributions.slice(maxInline);
+
+	return (
+		<>
+			{/* sm+ : inline items + (optional) overflow menu */}
+			<div className={cn('hidden items-center gap-1 sm:flex sm:gap-2', className)}>
+				{inline.map(item => (
+					<div key={item.id} className="shrink-0">
+						{renderSlot(item, fullContext)}
+					</div>
+				))}
+				<OverflowMenu items={overflow} context={fullContext} />
+			</div>
+			{/* < sm : everything in the overflow menu */}
+			<OverflowMenu items={contributions} context={fullContext} className="sm:hidden" />
+		</>
+	);
+}

package/src/slots/index.ts

@@ -0,0 +1,15 @@
+export { Slot, renderSlot } from './Slot';
+export type { SlotProps } from './Slot';
+export { SlotCluster } from './SlotCluster';
+export type { SlotClusterProps } from './SlotCluster';
+export { mergeSlots, appendSlots, sortSlots } from './mergeSlots';
+export { SLOT_NAMES } from './types';
+export type {
+	SlotName,
+	BuiltInSlotName,
+	SlotContext,
+	SlotRender,
+	SlotContribution,
+	SlotMap,
+	ResolvedSlots,
+} from './types';

package/src/slots/mergeSlots.test.ts

@@ -0,0 +1,71 @@
+import { describe, expect, it } from 'vitest';
+import { mergeSlots, appendSlots, sortSlots } from './mergeSlots';
+import { mergePluginClients } from '../plugin';
+import type { SlotContribution, SlotMap } from './types';
+
+const make = (id: string, order?: number): SlotContribution => ({
+	id,
+	render: () => null,
+	order,
+});
+
+describe('mergeSlots', () => {
+	it('concatenates contributions from multiple maps targeting the same slot (no override)', () => {
+		const a: SlotMap = { 'header.right': make('a') };
+		const b: SlotMap = { 'header.right': make('b') };
+
+		const merged = mergeSlots([a, b]);
+
+		expect(merged['header.right'].map(c => c.id)).toEqual(['a', 'b']);
+	});
+
+	it('accepts a single contribution or an array per slot', () => {
+		const merged = mergeSlots([{ 'sidebar.top': [make('x'), make('y')] }, { 'sidebar.top': make('z') }]);
+		expect(merged['sidebar.top'].map(c => c.id)).toEqual(['x', 'y', 'z']);
+	});
+
+	it('sorts by order, keeping registration order on ties', () => {
+		const merged = mergeSlots([
+			{ 'table.toolbar': [make('first-default'), make('low', -10)] },
+			{ 'table.toolbar': [make('high', 10), make('second-default')] },
+		]);
+		expect(merged['table.toolbar'].map(c => c.id)).toEqual(['low', 'first-default', 'second-default', 'high']);
+	});
+
+	it('ignores undefined maps and empty values', () => {
+		const merged = mergeSlots([undefined, {}, { 'panel.footer': make('only') }]);
+		expect(Object.keys(merged)).toEqual(['panel.footer']);
+		expect(merged['panel.footer'].map(c => c.id)).toEqual(['only']);
+	});
+});
+
+describe('appendSlots / sortSlots', () => {
+	it('appendSlots mutates and returns the target', () => {
+		const target = {};
+		const result = appendSlots(target, { 'form.footer': make('a') });
+		expect(result).toBe(target);
+		expect(result['form.footer'].map(c => c.id)).toEqual(['a']);
+	});
+
+	it('sortSlots is stable for equal orders', () => {
+		const resolved = { s: [make('a'), make('b'), make('c')] };
+		expect(sortSlots(resolved).s.map(c => c.id)).toEqual(['a', 'b', 'c']);
+	});
+});
+
+describe('mergePluginClients slot integration', () => {
+	it('stacks plugin slots in plugin order and appends the app manifest last', () => {
+		const pluginA = { name: 'a', slots: { 'header.right': make('from-a') } };
+		const pluginB = { name: 'b', slots: { 'header.right': make('from-b') } };
+		const appManifest = { name: 'app', slots: { 'header.right': make('from-app') } };
+
+		const merged = mergePluginClients([pluginA, pluginB, appManifest]);
+
+		expect(merged.slots['header.right'].map(c => c.id)).toEqual(['from-a', 'from-b', 'from-app']);
+	});
+
+	it('produces an empty slot map when no plugin contributes slots', () => {
+		const merged = mergePluginClients([{ name: 'a' }]);
+		expect(merged.slots).toEqual({});
+	});
+});

package/src/slots/mergeSlots.ts

@@ -0,0 +1,40 @@
+import type { SlotMap, ResolvedSlots, SlotContribution } from './types';
+
+/**
+ * Append the contributions of one `SlotMap` onto an accumulator. Unlike the
+ * override-based component registries, slots are 1:many — every contribution is
+ * kept, preserving the order contributors were applied in.
+ */
+export function appendSlots(target: ResolvedSlots, slots: SlotMap = {}): ResolvedSlots {
+	for (const [name, value] of Object.entries(slots)) {
+		if (!value) continue;
+		const contributions = Array.isArray(value) ? value : [value];
+		(target[name] ??= []).push(...contributions);
+	}
+	return target;
+}
+
+/**
+ * Stable-sort every slot's contributions by `order` (default 0). Equal orders
+ * keep registration order, since `Array.prototype.sort` is stable.
+ */
+export function sortSlots(resolved: ResolvedSlots): ResolvedSlots {
+	for (const name of Object.keys(resolved)) {
+		resolved[name] = [...resolved[name]].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+	}
+	return resolved;
+}
+
+/**
+ * Merge an ordered list of slot maps into a single resolved, sorted map.
+ * Earlier maps contribute first; the app map is appended last by the caller.
+ */
+export function mergeSlots(maps: Array<SlotMap | undefined>): ResolvedSlots {
+	const resolved: ResolvedSlots = {};
+	for (const map of maps) {
+		appendSlots(resolved, map);
+	}
+	return sortSlots(resolved);
+}
+
+export type { SlotContribution };

package/src/slots/slotNames.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { SLOT_NAMES } from './types';
+
+describe('SLOT_NAMES', () => {
+	it('maps camelCase keys to dotted slot names with unique values', () => {
+		const values = Object.values(SLOT_NAMES);
+		expect(new Set(values).size).toBe(values.length);
+		expect(values.every(v => /^[a-z]+\.[A-Za-z]+$/.test(v))).toBe(true);
+	});
+
+	it('includes the additional slots', () => {
+		expect(SLOT_NAMES.sidebarBrand).toBe('sidebar.brand');
+		expect(SLOT_NAMES.tableBulkActions).toBe('table.bulkActions');
+		expect(SLOT_NAMES.tableRowActions).toBe('table.rowActions');
+		expect(SLOT_NAMES.detailTabs).toBe('detail.tabs');
+		expect(SLOT_NAMES.widgetsAppend).toBe('widgets.append');
+		expect(SLOT_NAMES.modalHeaderActions).toBe('modal.headerActions');
+		expect(SLOT_NAMES.modalFooter).toBe('modal.footer');
+		expect(SLOT_NAMES.loginTop).toBe('login.top');
+	});
+});

package/src/slots/types.ts

@@ -0,0 +1,119 @@
+import type { ReactNode, ComponentType } from 'react';
+
+/**
+ * Built-in slot ids — the named injection points the framework renders in the
+ * panel chrome. Plugins may also use arbitrary strings to declare their own
+ * slots inside components they render.
+ */
+export type BuiltInSlotName =
+	| 'header.left'
+	| 'header.right'
+	| 'header.userMenu'
+	| 'sidebar.brand'
+	| 'sidebar.top'
+	| 'sidebar.bottom'
+	| 'panel.footer'
+	| 'table.toolbar'
+	| 'table.aboveTable'
+	| 'table.belowTable'
+	| 'table.bulkActions'
+	| 'table.rowActions'
+	| 'form.header'
+	| 'form.footer'
+	| 'detail.actions'
+	| 'detail.tabs'
+	| 'detail.afterDetails'
+	| 'page.top'
+	| 'page.bottom'
+	| 'widgets.append'
+	| 'modal.headerActions'
+	| 'modal.footer'
+	| 'login.top'
+	| 'login.belowForm';
+
+/**
+ * A slot name. The built-in names give autocomplete; the `string & {}` arm keeps
+ * the union open so plugins can define and target their own slots.
+ */
+export type SlotName = BuiltInSlotName | (string & {});
+
+/**
+ * Context passed to every slot render. The base shape is always present; each
+ * placement widens it with the data it can supply (e.g. the current record for
+ * detail/form slots, the resource slug for table slots).
+ */
+export interface SlotContext {
+	/** The slot being rendered. */
+	slot: SlotName;
+	/** Slug of the resource in scope, when the slot sits inside a resource view. */
+	resourceSlug?: string;
+	/** Resource/page schema in scope, when available. */
+	schema?: unknown;
+	/** The record in scope, for detail/form slots. */
+	record?: Record<string, unknown>;
+	/** Current router pathname. */
+	location?: string;
+	/** Authenticated user, for header/userMenu slots. Cast to your `AuthUser`. */
+	user?: unknown;
+	/** Slot-specific extras (e.g. `{ selectedIds }` for `table.bulkActions`, `{ rowId }` for `table.rowActions`). */
+	data?: Record<string, unknown>;
+}
+
+/**
+ * A slot's renderable: either a React component that receives the slot context
+ * as props, or a plain function of the context returning a node.
+ */
+export type SlotRender<C extends SlotContext = SlotContext> = ComponentType<C> | ((ctx: C) => ReactNode);
+
+/**
+ * A single contribution to a slot. Multiple contributions stack into one slot,
+ * unlike the override-based component registries.
+ */
+export interface SlotContribution<C extends SlotContext = SlotContext> {
+	/** Stable id — used as the React key and to dedupe across contributors. */
+	id: string;
+	/** Component or function that produces the slot content. */
+	render: SlotRender<C>;
+	/** Lower renders first. Defaults to 0; ties keep registration order. */
+	order?: number;
+}
+
+/**
+ * What a plugin/app contributes: a single contribution or an array per slot.
+ * Authored on `KratosPluginClient.slots` and `mountAdminPanel({ slots })`.
+ */
+export type SlotMap = Partial<Record<SlotName, SlotContribution | SlotContribution[]>>;
+
+/** Internal resolved form: every slot maps to a sorted array of contributions. */
+export type ResolvedSlots = Record<string, SlotContribution[]>;
+
+/**
+ * Built-in slot names as a const object, for autocomplete and refactor-safe
+ * references without losing the open `SlotName` string union.
+ */
+export const SLOT_NAMES = {
+	headerLeft: 'header.left',
+	headerRight: 'header.right',
+	headerUserMenu: 'header.userMenu',
+	sidebarBrand: 'sidebar.brand',
+	sidebarTop: 'sidebar.top',
+	sidebarBottom: 'sidebar.bottom',
+	panelFooter: 'panel.footer',
+	tableToolbar: 'table.toolbar',
+	tableAboveTable: 'table.aboveTable',
+	tableBelowTable: 'table.belowTable',
+	tableBulkActions: 'table.bulkActions',
+	tableRowActions: 'table.rowActions',
+	formHeader: 'form.header',
+	formFooter: 'form.footer',
+	detailActions: 'detail.actions',
+	detailTabs: 'detail.tabs',
+	detailAfterDetails: 'detail.afterDetails',
+	pageTop: 'page.top',
+	pageBottom: 'page.bottom',
+	widgetsAppend: 'widgets.append',
+	modalHeaderActions: 'modal.headerActions',
+	modalFooter: 'modal.footer',
+	loginTop: 'login.top',
+	loginBelowForm: 'login.belowForm',
+} as const satisfies Record<string, BuiltInSlotName>;