lucent-ui 0.19.1 → 0.21.0

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

@@ -0,0 +1,33 @@
+export const COMPONENT_MANIFEST = {
+    id: 'progress',
+    name: 'Progress',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'A horizontal bar indicating completion, progress, or resource usage.',
+    designIntent: 'Use Progress to visualise a bounded numeric value — task completion, disk usage, health bars, etc. ' +
+        'Set warnAt/dangerAt thresholds for automatic colour shifts instead of hardcoding variants. ' +
+        'Ascending thresholds (warnAt < dangerAt) suit "high is bad" metrics like CPU; ' +
+        'descending thresholds (warnAt > dangerAt) suit "low is bad" metrics like battery.',
+    props: [
+        { name: 'value', type: 'number', required: true, description: 'Current progress value.' },
+        { name: 'max', type: 'number', required: false, default: '100', description: 'Maximum value.' },
+        { name: 'variant', type: 'enum', required: false, default: 'accent', description: 'Colour variant. Overridden when thresholds are set.', enumValues: ['accent', 'success', 'warning', 'danger'] },
+        { name: 'size', type: 'enum', required: false, default: 'md', description: 'Bar height.', enumValues: ['sm', 'md', 'lg'] },
+        { name: 'warnAt', type: 'number', required: false, description: 'Value at which variant auto-switches to warning.' },
+        { name: 'dangerAt', type: 'number', required: false, description: 'Value at which variant auto-switches to danger.' },
+        { name: 'label', type: 'union', required: false, description: 'true shows percentage; ReactNode shows custom label.' },
+    ],
+    usageExamples: [
+        { title: 'Basic', code: `<Progress value={60} />` },
+        { title: 'With label', code: `<Progress value={42} label />` },
+        { title: 'Thresholds', code: `<Progress value={85} warnAt={70} dangerAt={90} label />` },
+        { title: 'Danger variant', code: `<Progress value={95} variant="danger" size="lg" label />` },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        role: 'progressbar',
+        ariaAttributes: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax'],
+        notes: 'Uses native progressbar role. Add aria-label on the wrapping element for screen-reader context.',
+    },
+};

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

@@ -0,0 +1,102 @@
+export const COMPONENT_MANIFEST = {
+    id: 'row',
+    name: 'Row',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'Horizontal flex layout primitive that spaces children using design-system gap tokens.',
+    designIntent: 'Row is the primary horizontal layout container. Use it any time you need to arrange elements ' +
+        'side by side — button groups, label-value pairs, icon + text combos, toolbar actions. ' +
+        'Default align is "center" (vertical centering), which is the most common horizontal layout need. ' +
+        'Use justify="between" for space-between patterns like a header with title on the left and actions ' +
+        'on the right. Set wrap=true when items should flow to the next line on narrow screens. ' +
+        'Row does not add padding — wrap it in a Card or apply padding on a parent container instead. ' +
+        'For vertical arrangement, use Stack instead.',
+    props: [
+        {
+            name: 'gap',
+            type: 'enum',
+            required: false,
+            default: '3',
+            description: 'Spacing between children. Maps to --lucent-space-{n} tokens.',
+            enumValues: ['0', '1', '2', '3', '4', '5', '6', '8', '10', '12', '16', '20', '24'],
+        },
+        {
+            name: 'align',
+            type: 'enum',
+            required: false,
+            default: 'center',
+            description: 'Cross-axis alignment (alignItems). "center" vertically centers items, which is the most common need.',
+            enumValues: ['start', 'center', 'end', 'stretch', 'baseline'],
+        },
+        {
+            name: 'justify',
+            type: 'enum',
+            required: false,
+            default: 'start',
+            description: 'Main-axis distribution (justifyContent). Use "between" for label/action pairs.',
+            enumValues: ['start', 'center', 'end', 'between', 'around'],
+        },
+        {
+            name: 'as',
+            type: 'enum',
+            required: false,
+            default: 'div',
+            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, form for forms).',
+            enumValues: ['div', 'section', 'nav', 'form', 'fieldset', 'ul', 'ol'],
+        },
+        {
+            name: 'wrap',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Whether children should wrap to the next line when they exceed the container width.',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The elements to arrange horizontally.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides. Applied after computed layout styles.',
+        },
+        {
+            name: 'className',
+            type: 'string',
+            required: false,
+            description: 'CSS class name passthrough.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Settings toggle',
+            code: `<Row gap="3" justify="between">\n  <Text size="sm">Push notifications</Text>\n  <Toggle />\n</Row>`,
+        },
+        {
+            title: 'Button group',
+            code: `<Row gap="2">\n  <Button variant="primary">Save</Button>\n  <Button variant="outline">Cancel</Button>\n</Row>`,
+        },
+        {
+            title: 'Stats row',
+            code: `<Row gap="6" wrap>\n  <Stack gap="1">\n    <Text size="2xl" weight="bold">1,234</Text>\n    <Text size="xs" color="secondary">Users</Text>\n  </Stack>\n  <Stack gap="1">\n    <Text size="2xl" weight="bold">56.7%</Text>\n    <Text size="xs" color="secondary">Conversion</Text>\n  </Stack>\n</Row>`,
+        },
+        {
+            title: 'Icon + text',
+            code: `<Row gap="2" align="center">\n  <Icon name="check" size={16} />\n  <Text size="sm" color="success">Verified</Text>\n</Row>`,
+        },
+        {
+            title: 'Header with actions',
+            code: `<Row justify="between">\n  <Text as="h2" size="xl" weight="semibold">Dashboard</Text>\n  <Row gap="2">\n    <Button variant="outline" size="sm">Export</Button>\n    <Button variant="primary" size="sm">New report</Button>\n  </Row>\n</Row>`,
+        },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        notes: 'Row renders a <div> by default, which has no implicit ARIA role. Use the `as` prop to render ' +
+            'semantic elements (nav, section) when the content has a specific structural purpose. ' +
+            'For toolbar patterns, consider adding role="toolbar" via the role prop.',
+    },
+};

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

@@ -0,0 +1,101 @@
+export const COMPONENT_MANIFEST = {
+    id: 'stack',
+    name: 'Stack',
+    tier: 'atom',
+    domain: 'neutral',
+    specVersion: '0.1',
+    description: 'Vertical flex layout primitive that spaces children using design-system gap tokens.',
+    designIntent: 'Stack is the primary vertical layout container. Use it any time you need to arrange elements ' +
+        'in a column with consistent spacing — form fields, card content, page sections, sidebar navigation. ' +
+        'The gap prop maps to spacing tokens (--lucent-space-*), enforcing consistent vertical rhythm ' +
+        'without manual margin management. Prefer Stack over raw inline flex styles for maintainability ' +
+        'and readability. Use Row (the horizontal counterpart) when items should flow left-to-right. ' +
+        'Stack does not add padding — wrap it in a Card or apply padding on a parent container instead.',
+    props: [
+        {
+            name: 'gap',
+            type: 'enum',
+            required: false,
+            default: '4',
+            description: 'Spacing between children. Maps to --lucent-space-{n} tokens.',
+            enumValues: ['0', '1', '2', '3', '4', '5', '6', '8', '10', '12', '16', '20', '24'],
+        },
+        {
+            name: 'align',
+            type: 'enum',
+            required: false,
+            default: 'stretch',
+            description: 'Cross-axis alignment (alignItems). "stretch" fills the container width.',
+            enumValues: ['start', 'center', 'end', 'stretch', 'baseline'],
+        },
+        {
+            name: 'justify',
+            type: 'enum',
+            required: false,
+            default: 'start',
+            description: 'Main-axis distribution (justifyContent).',
+            enumValues: ['start', 'center', 'end', 'between', 'around'],
+        },
+        {
+            name: 'as',
+            type: 'enum',
+            required: false,
+            default: 'div',
+            description: 'HTML element to render. Use semantic elements when appropriate (nav for navigation, form for forms).',
+            enumValues: ['div', 'section', 'nav', 'form', 'fieldset', 'ul', 'ol'],
+        },
+        {
+            name: 'wrap',
+            type: 'boolean',
+            required: false,
+            default: 'false',
+            description: 'Whether children should wrap to the next line when they exceed the container width.',
+        },
+        {
+            name: 'children',
+            type: 'ReactNode',
+            required: true,
+            description: 'The elements to arrange vertically.',
+        },
+        {
+            name: 'style',
+            type: 'object',
+            required: false,
+            description: 'Inline style overrides. Applied after computed layout styles.',
+        },
+        {
+            name: 'className',
+            type: 'string',
+            required: false,
+            description: 'CSS class name passthrough.',
+        },
+    ],
+    usageExamples: [
+        {
+            title: 'Form layout',
+            code: `<Stack gap="4">\n  <FormField label="Name"><Input /></FormField>\n  <FormField label="Email"><Input type="email" /></FormField>\n  <Button variant="primary">Submit</Button>\n</Stack>`,
+        },
+        {
+            title: 'Card content',
+            code: `<Card padding="lg">\n  <Stack gap="3">\n    <Text as="h3" size="lg" weight="semibold">Title</Text>\n    <Text size="sm" color="secondary">Description goes here.</Text>\n    <Button variant="outline" size="sm">Learn more</Button>\n  </Stack>\n</Card>`,
+        },
+        {
+            title: 'Tight spacing',
+            code: `<Stack gap="1">\n  <Text size="sm" weight="medium">Label</Text>\n  <Text size="xs" color="secondary">Helper text</Text>\n</Stack>`,
+        },
+        {
+            title: 'Centered content',
+            code: `<Stack gap="4" align="center" justify="center" style={{ minHeight: 200 }}>\n  <Spinner />\n  <Text color="secondary">Loading...</Text>\n</Stack>`,
+        },
+        {
+            title: 'Semantic nav',
+            code: `<Stack as="nav" gap="1">\n  <NavLink href="/home">Home</NavLink>\n  <NavLink href="/settings">Settings</NavLink>\n</Stack>`,
+        },
+    ],
+    compositionGraph: [],
+    accessibility: {
+        notes: 'Stack renders a <div> by default, which has no implicit ARIA role. Use the `as` prop to render ' +
+            'semantic elements (nav, section, form) when the content has a specific structural purpose. ' +
+            'Add aria-label or aria-labelledby when using landmark elements.',
+    },
+};

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

@@ -0,0 +1,28 @@
+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);
+        });
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lucent-ui",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "An AI-first React component library with machine-readable manifests.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,6 +25,18 @@
     "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",
@@ -39,6 +51,7 @@
   },
   "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"
@@ -60,16 +73,5 @@
   "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"
   }
-}
+}