lucent-ui 0.18.0 → 0.19.0

package/dist-server/src/components/atoms/ColorPicker/ColorPicker.manifest.js

@@ -55,6 +55,13 @@ export const COMPONENT_MANIFEST = {
             default: 'false',
             description: 'Prevents interaction and dims the label.',
         },
+        {
+            name: 'portalContainer',
+            type: 'HTMLElement | null',
+            required: false,
+            description: 'DOM element to portal the popover into. Defaults to document.body. ' +
+                'Set this to a wrapper element to preserve CSS custom property inheritance for per-section theming.',
+        },
         {
             name: 'id',
             type: 'string',

package/dist-server/src/components/molecules/Menu/Menu.manifest.js

@@ -24,9 +24,10 @@ export const COMPONENT_MANIFEST = {
         '`-end`, or centered) is preserved during the flip. Position is computed with `getBoundingClientRect` ' +
         'on mount and rendered via `position: fixed` in a portal.\n\n' +
         '## Portal rendering\n' +
-        'The popover is portaled to `document.body` via `createPortal`. This prevents overflow clipping from ' +
+        'The popover is portaled via `createPortal` (default: `document.body`). This prevents overflow clipping from ' +
         'parent containers with `overflow: hidden`. The trigger wrapper stays inline in the DOM tree so it ' +
-        'participates in layout normally.\n\n' +
+        'participates in layout normally. The `portalContainer` prop lets consumers render the portal inside a ' +
+        'wrapper element that sets `--lucent-*` CSS custom property overrides, preserving per-section theming.\n\n' +
         '## Keyboard navigation\n' +
         'Follows WAI-ARIA Menu Button pattern. Arrow keys cycle through enabled items (wrapping). Enter/Space ' +
         'selects the active item and closes the menu. Escape closes without selection. Tab closes and lets ' +
@@ -88,6 +89,13 @@ export const COMPONENT_MANIFEST = {
             required: false,
             description: 'Callback fired when the menu opens or closes. Receives the new open state.',
         },
+        {
+            name: 'portalContainer',
+            type: 'HTMLElement | null',
+            required: false,
+            description: 'DOM element to portal the popover into. Defaults to document.body. ' +
+                'Set this to a wrapper element to preserve CSS custom property inheritance for per-section theming.',
+        },
         {
             name: 'style',
             type: 'object',
@@ -267,6 +275,6 @@ export const COMPONENT_MANIFEST = {
         notes: 'Focus returns to the trigger element after the menu is dismissed via Escape or selection. ' +
             'Disabled items are skipped during keyboard navigation and have aria-disabled. ' +
             'Selected items use role="menuitemcheckbox" with aria-checked for screen reader announcement. ' +
-            'The popover is portaled to document.body but remains semantically linked to the trigger via aria-controls.',
+            'The popover is portaled to document.body (or portalContainer) but remains semantically linked to the trigger via aria-controls.',
     },
 };

package/dist-server/src/components/molecules/Toast/Toast.manifest.js

@@ -0,0 +1,233 @@
+export const COMPONENT_MANIFEST = {
+    id: 'toast',
+    name: 'Toast',
+    tier: 'molecule',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'Ephemeral notification system with auto-dismiss, cascading card-stack, ' +
+        'hover-to-expand, action buttons/links, and animated enter/exit transitions. ' +
+        'Comprises ToastProvider (context + portal), useToast hook, and toast card rendering.',
+    designIntent: 'Toast provides ephemeral feedback for actions that don\'t require the user to navigate away or ' +
+        'acknowledge inline. It fills the gap between Alert (persistent, inline) and Modal (blocking). ' +
+        '\n\n' +
+        '**Architecture**: ToastProvider wraps the app and manages a queue of toast entries. It renders ' +
+        'toasts into a React portal (document.body by default, configurable via portalContainer) so they ' +
+        'float above all page content regardless of stacking contexts. The useToast() hook exposes an ' +
+        'imperative `toast()` function that returns a dismissible id, and a `dismiss()` function. ' +
+        '\n\n' +
+        '**Positioning**: The viewport is fixed-positioned with a stable anchor edge. For bottom positions, ' +
+        'the toast\'s top edge is pinned 120px from the viewport bottom (ANCHOR_INSET_BOTTOM), so taller ' +
+        'toasts extend downward toward the screen edge — the top never jumps. For top positions, the top ' +
+        'edge is pinned 40px from the viewport top (ANCHOR_INSET), keeping toasts close to the top bar ' +
+        'or header area. Both distances are separate constants to allow independent tuning. Six positions ' +
+        'are supported: top-left, top-center, top-right, bottom-left, bottom-center, bottom-right. ' +
+        '\n\n' +
+        '**Cascading stack**: When multiple toasts are active, only the newest (front) toast shows its full ' +
+        'content. Older toasts render as empty card shells (border + background, no content) that peek ' +
+        'behind the front toast with progressive scaleX reduction and opacity fade. Each shell is ' +
+        'height-matched to the front toast via measurement so the peek gaps are perfectly uniform. ' +
+        'Up to 3 stacked shells are visible behind the front toast. ' +
+        '\n\n' +
+        '**Hover to expand**: Hovering the stack smoothly expands all toasts into a full vertical list ' +
+        'with content fading in, card heights animating to natural size, and shadows appearing. The ' +
+        'expanded stack uses flex column-reverse for bottom positions so older toasts fan upward into ' +
+        'the viewport. A 150ms debounced collapse timer prevents flicker when the cursor moves between ' +
+        'toasts in the expanded list. ' +
+        '\n\n' +
+        '**Enter/exit animations**: New toasts slide in from the screen edge with opacity fade and slight ' +
+        'scale-up (requestAnimationFrame double-raf triggers the CSS transition). Dismissed toasts slide ' +
+        'back toward the edge and fade out over 200ms. ' +
+        '\n\n' +
+        '**Auto-dismiss**: Each toast auto-dismisses after a configurable duration (default 5s). Pass ' +
+        'Infinity to disable. The timer is managed per-toast via useEffect, so each toast dismisses ' +
+        'independently. ' +
+        '\n\n' +
+        '**Actions**: Toasts support an inline action rendered as either a bordered button (default, ' +
+        'matching the Undo pattern from Sonner/Google) or an underlined link. Clicking the action fires ' +
+        'the callback and auto-dismisses the toast. ' +
+        '\n\n' +
+        '**Variants**: default (neutral border), success, warning, danger, info — matching Alert\'s ' +
+        'semantic token usage. Each variant sets border color and icon color from status tokens. ' +
+        'Non-default variants include a built-in 16×16 SVG icon (same as Alert). ' +
+        '\n\n' +
+        '**Multi-line text**: title is always shown (semibold). Optional description supports newlines ' +
+        'via white-space: pre-line. All text uses the Text atom.',
+    props: [
+        // ─── ToastProvider props ──────────────────────────────────────────
+        {
+            name: 'position',
+            type: 'enum',
+            required: false,
+            default: 'bottom-right',
+            description: 'Screen edge and alignment where the toast stack appears.',
+            enumValues: ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'],
+        },
+        {
+            name: 'duration',
+            type: 'number',
+            required: false,
+            default: '5000',
+            description: 'Default auto-dismiss duration in milliseconds. Applies to all toasts unless overridden per-toast.',
+        },
+        {
+            name: 'max',
+            type: 'number',
+            required: false,
+            default: '5',
+            description: 'Maximum number of toasts in the queue. When exceeded, the oldest toast is dismissed with an exit animation.',
+        },
+        {
+            name: 'portalContainer',
+            type: 'object',
+            required: false,
+            description: 'DOM element to render the toast portal into. Defaults to document.body. Useful for scoping toasts to a specific container (e.g. inside an iframe or shadow DOM).',
+        },
+        // ─── ToastOptions (per-toast, passed to toast()) ─────────────────
+        {
+            name: 'title',
+            type: 'string',
+            required: true,
+            description: 'Primary message line, rendered in semibold. Always visible.',
+        },
+        {
+            name: 'description',
+            type: 'string',
+            required: false,
+            description: 'Secondary description text below the title. Supports multi-line via newline characters (\\n). Rendered in secondary color.',
+        },
+        {
+            name: 'variant',
+            type: 'enum',
+            required: false,
+            default: 'default',
+            description: 'Visual variant controlling border color, icon, and icon color. Matches Alert\'s semantic status tokens.',
+            enumValues: ['default', 'success', 'warning', 'danger', 'info'],
+        },
+        {
+            name: 'duration (per-toast)',
+            type: 'number',
+            required: false,
+            default: '5000',
+            description: 'Override the provider-level auto-dismiss duration for this specific toast. Pass Infinity to disable auto-dismiss.',
+        },
+        {
+            name: 'action',
+            type: 'object',
+            required: false,
+            description: 'Inline action rendered beside the dismiss button. Object with { label: string, onClick: () => void, style?: "button" | "link" }. Button style renders a bordered pill button (default). Link style renders an underlined text link. Clicking fires onClick and auto-dismisses the toast.',
+        },
+        {
+            name: 'icon',
+            type: 'ReactNode',
+            required: false,
+            description: 'Custom icon to replace the built-in variant icon. Only used when variant is not "default". Pass null to suppress the icon entirely.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Provider setup',
+            description: 'Wrap your app with ToastProvider inside LucentProvider. Position and duration are configurable at the provider level.',
+            code: `<LucentProvider>
+  <ToastProvider position="bottom-right" duration={5000}>
+    <App />
+  </ToastProvider>
+</LucentProvider>`,
+        },
+        {
+            title: 'Basic toast',
+            description: 'Minimal toast with just a title. Uses the default variant (neutral border, no icon).',
+            code: `const { toast } = useToast();
+toast({ title: 'Changes saved' });`,
+        },
+        {
+            title: 'Success with description',
+            description: 'Two-line toast with a success variant. The description supports newlines via \\n.',
+            code: `toast({
+  title: 'Order placed!',
+  description: 'You\\'ll receive a confirmation email shortly.',
+  variant: 'success',
+});`,
+        },
+        {
+            title: 'Danger with undo button',
+            description: 'Destructive action feedback with an inline undo button. Clicking the action auto-dismisses.',
+            code: `toast({
+  title: 'Message deleted',
+  variant: 'danger',
+  action: {
+    label: 'Undo',
+    onClick: () => restoreMessage(id),
+  },
+});`,
+        },
+        {
+            title: 'Action as link',
+            description: 'Action rendered as an underlined link instead of a bordered button.',
+            code: `toast({
+  title: 'Event created',
+  description: 'Sunday, December 03, 2023 at 9:00 AM',
+  action: {
+    label: 'View',
+    style: 'link',
+    onClick: () => navigate('/events/123'),
+  },
+});`,
+        },
+        {
+            title: 'Multi-line description',
+            description: 'Description with embedded newlines rendered via white-space: pre-line.',
+            code: `toast({
+  title: 'Approaching limit',
+  description: 'You have used 80% of your monthly quota.\\nConsider upgrading your plan.',
+  variant: 'warning',
+});`,
+        },
+        {
+            title: 'Persistent (no auto-dismiss)',
+            description: 'Pass Infinity as duration to keep the toast visible until manually dismissed.',
+            code: `toast({
+  title: 'Upload in progress',
+  description: 'Please do not close this tab.',
+  duration: Infinity,
+});`,
+        },
+        {
+            title: 'Programmatic dismiss',
+            description: 'toast() returns an id that can be passed to dismiss() to remove it programmatically.',
+            code: `const { toast, dismiss } = useToast();
+const id = toast({ title: 'Processing...', duration: Infinity });
+// Later:
+dismiss(id);`,
+        },
+        {
+            title: 'Custom icon',
+            description: 'Override the built-in variant icon with a custom SVG.',
+            code: `toast({
+  title: 'Synced',
+  variant: 'success',
+  icon: <CloudSyncIcon />,
+});`,
+        },
+    ],
+    compositionGraph: [
+        { componentId: 'text', componentName: 'Text', role: 'Renders title and description text with correct typography', required: true },
+        { componentId: 'icon', componentName: 'Icon (built-in SVGs)', role: 'Status variant icons (info, success, warning, danger)', required: false },
+    ],
+    accessibility: {
+        role: 'status',
+        ariaAttributes: ['aria-live', 'aria-hidden', 'aria-label'],
+        keyboardInteractions: [
+            'Tab: focuses the dismiss button and action button within the toast',
+            'Enter/Space: activates the focused dismiss or action button',
+            'Escape: no default behavior (consider adding dismiss-on-escape if needed)',
+        ],
+        notes: 'Each toast uses role="status" with aria-live="polite" so screen readers announce the content ' +
+            'without interrupting the current task. This is appropriate for non-urgent status messages like ' +
+            '"Changes saved" or "Profile updated". For truly urgent errors that must interrupt the user, ' +
+            'consider wrapping the ToastProvider output in a role="alert" region or using the Alert component ' +
+            'instead. The dismiss button carries aria-label="Dismiss" for screen reader clarity. Stacked ' +
+            'toasts behind the front toast are marked aria-hidden="true" to prevent screen readers from ' +
+            'announcing duplicate or hidden content. When the stack expands on hover, aria-hidden is removed ' +
+            'so all toasts become accessible.',
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,18 +25,6 @@
     "dist-server",
     "dist-cli"
   ],
-  "scripts": {
-    "dev": "vite --config vite.dev.config.ts",
-    "build": "vite build",
-    "build:server": "tsc -p server/tsconfig.json",
-    "build:cli": "tsc -p cli/tsconfig.json && cp cli/template.manifest.json dist-cli/cli/template.manifest.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "prepublishOnly": "tsc --noEmit && pnpm build && pnpm build:server && pnpm build:cli",
-    "changeset": "changeset",
-    "version-packages": "changeset version",
-    "release": "pnpm prepublishOnly && changeset publish"
-  },
   "keywords": [
     "react",
     "component-library",
@@ -51,7 +39,6 @@
   },
   "author": "Rozina Szogyenyi",
   "license": "MIT",
-  "packageManager": "pnpm@10.30.3",
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
@@ -73,5 +60,16 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "zod": "^4.3.6"
+  },
+  "scripts": {
+    "dev": "vite --config vite.dev.config.ts",
+    "build": "vite build",
+    "build:server": "tsc -p server/tsconfig.json",
+    "build:cli": "tsc -p cli/tsconfig.json && cp cli/template.manifest.json dist-cli/cli/template.manifest.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm prepublishOnly && changeset publish"
   }
-}
+}

package/dist-server/src/manifest/validate.test.js

@@ -1,28 +0,0 @@
-import { describe, test, expect } from 'vitest';
-import { validateManifest } from './validate.js';
-// Auto-discover all component manifests
-const manifestModules = import.meta.glob('../components/**/*.manifest.ts', { eager: true });
-const manifests = Object.entries(manifestModules).map(([path, mod]) => {
-    const m = mod;
-    const manifest = m['COMPONENT_MANIFEST'];
-    return { path, manifest };
-});
-describe('Component manifests', () => {
-    test('at least one manifest was discovered', () => {
-        expect(manifests.length).toBeGreaterThan(0);
-    });
-    for (const { path, manifest } of manifests) {
-        const label = path.replace('../components/', '').replace('.manifest.ts', '');
-        test(`${label} — exports COMPONENT_MANIFEST`, () => {
-            expect(manifest).toBeDefined();
-        });
-        test(`${label} — passes schema validation`, () => {
-            const result = validateManifest(manifest);
-            if (!result.valid) {
-                const messages = result.errors.map(e => `  ${e.field}: ${e.message}`).join('\n');
-                throw new Error(`Invalid manifest:\n${messages}`);
-            }
-            expect(result.valid).toBe(true);
-        });
-    }
-});