noecosystem-design 0.1.3 → 0.2.1

package/packages/ui/src/card.tsx

@@ -2,13 +2,25 @@ import type * as React from 'react';
 
 import { cn } from './lib/cn';
 
-export function Card({ className, ...props }: React.ComponentProps<'section'>) {
+export type CardAppearance = 'raised' | 'outlined';
+
+export interface CardProps extends React.ComponentProps<'section'> {
+  /**
+   * Raised surfaces are separated from the page by a semantic surface tone only.
+   * Use outlined only where a visible boundary conveys data-entry or selection state.
+   */
+  appearance?: CardAppearance;
+}
+
+export function Card({ appearance = 'raised', className, ...props }: CardProps) {
   return (
     <section
       className={cn(
-        'flex flex-col overflow-hidden rounded-lg border border-border bg-surface-raised text-foreground',
+        'flex flex-col overflow-hidden rounded-lg bg-surface-raised text-foreground',
+        appearance === 'outlined' && 'border border-border',
         className,
       )}
+      data-appearance={appearance}
       data-slot="card"
       {...props}
     />

package/packages/ui/src/theme-provider.browser.test.tsx

@@ -1,4 +1,3 @@
-import * as React from 'react';
 import { expect, test } from 'vitest';
 import { render } from 'vitest-browser-react';
 
@@ -13,13 +12,14 @@ function PaletteProbe({ storageKey }: { storageKey?: string }) {
       <button type="button" onClick={() => setPalette('graphite' as never)}>
         set graphite
       </button>
-      {storageKey && <span data-testid="storageKey">{storageKey}</span>}
+      {storageKey ? <span data-testid="storageKey">{storageKey}</span> : null}
     </div>
   );
 }
 
 test('default Graphite with no preference', async () => {
   localStorage.clear();
+  // biome-ignore lint/suspicious/noDocumentCookie: Test setup must exercise the cookie fallback path.
   document.cookie = 'noecosystem-palette=; Max-Age=0; path=/';
   document.documentElement.removeAttribute('data-noe-palette');
   const screen = await render(
@@ -45,6 +45,7 @@ test('valid stored preference restoration', async () => {
 
 test('invalid storage and cookie fallback to Graphite', async () => {
   localStorage.setItem('noecosystem-palette', 'invalid-palette');
+  // biome-ignore lint/suspicious/noDocumentCookie: This test needs an invalid cookie value for fallback coverage.
   document.cookie = 'noecosystem-palette=invalid-palette; path=/';
   const screen = await render(
     <ThemeProvider>

package/scripts/generate-manifest.mjs

@@ -10,6 +10,28 @@ const schemaPath = path.join(root, 'packages/registry/manifest.schema.json');
 const audit = JSON.parse(await readFile(auditPath, 'utf8'));
 const _schema = JSON.parse(await readFile(schemaPath, 'utf8'));
 
+async function writeJsonIfChanged(filePath, value, { preserveGeneratedAt = false } = {}) {
+  let existingText = null;
+  let existingValue = null;
+
+  try {
+    existingText = await readFile(filePath, 'utf8');
+    existingValue = JSON.parse(existingText);
+  } catch {}
+
+  let output = value;
+  if (preserveGeneratedAt && existingValue?.generatedAt) {
+    const { generatedAt: _previousGeneratedAt, ...previousPayload } = existingValue;
+    const { generatedAt: _nextGeneratedAt, ...nextPayload } = value;
+    if (JSON.stringify(previousPayload) === JSON.stringify(nextPayload)) {
+      output = { ...value, generatedAt: existingValue.generatedAt };
+    }
+  }
+
+  const nextText = `${JSON.stringify(output, null, 2)}\n`;
+  if (nextText !== existingText) await writeFile(filePath, nextText);
+}
+
 function toExportName(id) {
   const map = {
     'bidi-text': 'BidiText',
@@ -196,6 +218,41 @@ const enrichments = {
       notes: 'Variants parity full; loading and destructive covered',
     },
   },
+  card: {
+    description:
+      'Flat raised section primitive. It separates content from its page canvas through semantic surface tone, spacing and radius—not decorative borders or shadows. Use outlined only where a boundary conveys selection or data-entry state.',
+    capabilityAliases: ['flat card', 'raised surface', 'borderless section', 'outlined card'],
+    searchTerms: [
+      'card',
+      'raised surface',
+      'flat section',
+      'borderless panel',
+      'outlined boundary',
+    ],
+    useWhen: [
+      'grouping a top-level application region with a semantic raised surface',
+      'separating sections by color tone rather than elevation or decorative chrome',
+      'using appearance="outlined" only for selection, data-entry or comparison boundaries',
+    ],
+    doNotUseWhen: [
+      'adding a nested card solely to create visual depth',
+      'using an outlined boundary when spacing and surface tone already express grouping',
+    ],
+    alternatives: ['SectionHeader', 'Field'],
+    variants: ['raised', 'outlined'],
+    states: ['default'],
+    tokenContracts: ['color.background', 'color.surface', 'color.surfaceRaised', 'radius.lg'],
+    accessibility: {
+      keyboard: [],
+      announcements: [],
+      focusBehavior: ['not focusable unless its content contains an interactive control'],
+    },
+    internationalization: {
+      rtl: 'required',
+      bidiNotes: ['logical spacing; no directional layout override'],
+    },
+    relatedPatterns: ['app-frame', 'dashboard-shell', 'section-header'],
+  },
   dialog: {
     description:
       'Direction-preserving modal primitive with native focus semantics and portal propagation. Share foundation with Modal/Slideout.',
@@ -804,7 +861,7 @@ function defaultEnrichment(auditItem) {
     dependencies: deps,
     registryDependencies: registryDeps,
     peerDependencies: peerDeps,
-    propsSummary: { label: 'string | ReactNode', children: 'ReactNode' },
+    propsSummary: base.propsSummary ?? { label: 'string | ReactNode', children: 'ReactNode' },
     variants,
     sizes,
     slots,
@@ -1045,14 +1102,15 @@ for (const item of cinematicEnrichments) {
   if (!manifest.items.find((i) => i.id === item.id)) manifest.items.push(item);
 }
 
-await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+await writeJsonIfChanged(manifestPath, manifest, { preserveGeneratedAt: true });
 console.log(`manifest.json written: ${manifest.items.length} items`);
 
 // Also generate derived files for backward compat
 // 1. Update component-audit.json to be derived (keep minimal fields but now from manifest)
 const auditDerived = {
   $schema: audit.$schema,
-  generatedNote: `${audit.generatedNote} (derived from manifest.json)`,
+  generatedNote:
+    'Canonical NOE public-component inventory. status=available requires a public export, a Storybook story at storyId, and (where distributable) a registry entry. Do not mark an item available without all three. (derived from manifest.json)',
   items: manifest.items
     .filter((i) => !i.category.startsWith('Cinematic'))
     .map((i) => ({
@@ -1064,7 +1122,7 @@ const auditDerived = {
       registryItem: i.registryItem,
     })),
 };
-await writeFile(auditPath, `${JSON.stringify(auditDerived, null, 2)}\n`);
+await writeJsonIfChanged(auditPath, auditDerived);
 console.log(`component-audit.json derived: ${auditDerived.items.length} items`);
 
 // 2. Generate search index
@@ -1085,9 +1143,10 @@ const searchIndex = manifest.items.map((i) => ({
   registryItem: i.registryItem,
   maturity: i.maturity,
 }));
-await writeFile(
+await writeJsonIfChanged(
   path.join(root, 'packages/registry/search-index.json'),
-  `${JSON.stringify({ generatedAt: new Date().toISOString(), items: searchIndex }, null, 2)}\n`,
+  { generatedAt: new Date().toISOString(), items: searchIndex },
+  { preserveGeneratedAt: true },
 );
 console.log(`search-index.json written`);
 
@@ -1107,47 +1166,41 @@ for (const item of registry.items) {
     item.searchTerms = m.searchTerms;
   }
 }
-await writeFile(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+await writeJsonIfChanged(registryPath, registry);
 console.log(`registry.json enriched`);
 
 // 4. Generate catalog index (JSON for agents)
-await writeFile(
+await writeJsonIfChanged(
   path.join(root, 'packages/registry/catalog-index.json'),
-  `${JSON.stringify(
-    {
-      generatedAt: new Date().toISOString(),
-      items: manifest.items.map((i) => ({
-        id: i.id,
-        title: i.title,
-        category: i.category,
-        package: i.package,
-        status: i.status,
-        maturity: i.maturity,
-        description: i.description,
-        registryItem: i.registryItem,
-      })),
-    },
-    null,
-    2,
-  )}\n`,
+  {
+    generatedAt: new Date().toISOString(),
+    items: manifest.items.map((i) => ({
+      id: i.id,
+      title: i.title,
+      category: i.category,
+      package: i.package,
+      status: i.status,
+      maturity: i.maturity,
+      description: i.description,
+      registryItem: i.registryItem,
+    })),
+  },
+  { preserveGeneratedAt: true },
 );
 console.log(`catalog-index.json written`);
 
 // 5. Generate docs index
-await writeFile(
+await writeJsonIfChanged(
   path.join(root, 'packages/registry/docs-index.json'),
-  `${JSON.stringify(
-    {
-      generatedAt: new Date().toISOString(),
-      items: manifest.items.map((i) => ({
-        id: i.id,
-        title: i.title,
-        category: i.category,
-        examples: i.examples,
-      })),
-    },
-    null,
-    2,
-  )}\n`,
+  {
+    generatedAt: new Date().toISOString(),
+    items: manifest.items.map((i) => ({
+      id: i.id,
+      title: i.title,
+      category: i.category,
+      examples: i.examples,
+    })),
+  },
+  { preserveGeneratedAt: true },
 );
 console.log(`docs-index.json written`);

package/scripts/validate-manifest.mjs

@@ -276,7 +276,7 @@ if (errors === 0) pass('semantic search fields');
     .map((i) => i.registryItem);
   const counts = new Map();
   for (const n of regItems) counts.set(n, (counts.get(n) || 0) + 1);
-  const dups = [...counts.entries()].filter(([name, c]) => c > 1).map(([name]) => name);
+  const dups = [...counts.entries()].filter(([, c]) => c > 1).map(([name]) => name);
   const allowedShared = new Set(['input']); // field shares input payload
   const illegalDups = dups.filter((n) => !allowedShared.has(n));
   if (illegalDups.length) {
@@ -368,17 +368,6 @@ if (errors === 0) pass('semantic search fields');
           errors++;
           closureErrors++;
         } else if (!fileSet.has(resolved)) {
-          // Allow if resolved is provided via registryDependencies payload (check if in dep payload)
-          const depPayloads = (payload.registryDependencies || [])
-            .map((d) => d.replace('@noe/', ''))
-            .map((n) => {
-              try {
-                return { name: n, exists: true };
-              } catch {
-                return null;
-              }
-            });
-          // For simplicity, if not in current payload, check if it's in any other payload that is a dependency (we already include via files)
           fail(
             `closure: ${item.registryItem} ${f.path} imports '${imp}' -> ${resolved} not in payload`,
           );
@@ -394,7 +383,6 @@ if (errors === 0) pass('semantic search fields');
 // 15. Story existence for every available/partial
 {
   let missingStory = 0;
-  const storyFiles = new Set();
   // Collect story ids from filesystem (reusing earlier logic would duplicate, but we check file existence directly)
   for (const item of manifest.items.filter(
     (i) => i.status === 'available' || i.status === 'partial',
@@ -470,22 +458,8 @@ if (errors === 0) pass('semantic search fields');
   if (plannedLeak === 0) pass('no public registry item for planned');
 }
 
-// 18. Preview contract — every available must have a preview that is not a fake control for planned
-{
-  // We check catalog-index preview contract via manifest status: planned must not have registryItem and must be spec-only in UI (verified via Playwright)
-  // This check ensures manifest correctly marks preview contract via status
-  let badPreview = 0;
-  for (const item of manifest.items) {
-    if (
-      item.status === 'planned' &&
-      item.examples.some((e) => e.files.some((f) => f.includes('stories')))
-    ) {
-      // Planned items should not have interactive story files that imply implementation
-      // We allow story files for planned only if they are spec placeholders — currently all planned share generic stories, so we skip
-    }
-  }
-  if (badPreview === 0) pass('preview contract');
-}
+// 18. Preview contract — planned entries must remain spec-only, as validated by Playwright.
+pass('preview contract');
 
 if (errors) {
   console.error(`${errors} validation errors`);

package/tests/e2e/catalog-typography.spec.ts

@@ -89,8 +89,7 @@ test.describe('Catalog locale typography', () => {
     for (let i = 0; i < Math.min(3, count); i++) {
       const card = availableCards.nth(i);
       await expect(card).toBeVisible();
-      // Preview container should have at least one element
-      const previewContainer = card.locator('div').filter({ hasText: '' }).first();
+      // Preview container should have at least one element.
       await expect(card.locator('div').nth(2)).not.toBeEmpty();
     }
     // Spot check Button

package/tests/icons.test.mjs

@@ -3,7 +3,7 @@ import { readFile } from 'node:fs/promises';
 import test from 'node:test';
 
 const iconSource = await readFile(
-  new URL('../packages/icons/src/index.tsx', import.meta.url),
+  new URL('../packages/icons/src/iconsax.tsx', import.meta.url),
   'utf8',
 );
 const baseCss = await readFile(
@@ -11,10 +11,10 @@ const baseCss = await readFile(
   'utf8',
 );
 
-test('the vetted Icons8 chevron uses the logical icon contract', () => {
-  assert.match(iconSource, /export const icons8Source/);
-  assert.match(iconSource, /provider: 'Icons8'/);
-  assert.match(iconSource, /data-icon-source="icons8"/);
+test('the vetted Iconsax wrapper uses the logical icon contract', () => {
+  assert.match(iconSource, /export const iconsaxFreeSource/);
+  assert.match(iconSource, /provider: 'Iconsax Free'/);
+  assert.match(iconSource, /data-icon-source="iconsax-free"/);
   assert.match(iconSource, /data-logical-direction=\{direction\}/);
   assert.match(baseCss, /\.noe-logical-icon\[data-logical-direction="backward"\]/);
   assert.match(baseCss, /\[dir="rtl"\] \.noe-logical-icon\[data-logical-direction="forward"\]/);

package/tests/tokens.test.mjs

@@ -22,3 +22,17 @@ test('token CSS includes theme and reduced-motion contracts', async () => {
   assert.match(css, /--noe-primitive-color-paper-100:\s*#[0-9a-f]{6}/i);
   assert.match(css, /--noe-primitive-color-mint-100:\s*#[0-9a-f]{6}/i);
 });
+
+test('surface elevation is intentionally shadow-free in both themes', async () => {
+  assert.equal(tokens.shadow.light.raised, 'none');
+  assert.equal(tokens.shadow.light.overlay, 'none');
+  assert.equal(tokens.shadow.dark.raised, 'none');
+  assert.equal(tokens.shadow.dark.overlay, 'none');
+
+  const css = await readFile(
+    new URL('../packages/design-tokens/src/tokens.css', import.meta.url),
+    'utf8',
+  );
+  assert.match(css, /\[data-theme="light"\][\s\S]*?--noe-shadow-raised:\s*none/);
+  assert.match(css, /\[data-theme="dark"\][\s\S]*?--noe-shadow-overlay:\s*none/);
+});