@nordmanai/nif 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @nordmanai/nif
+
+The Nordman Interface Framework. One UI and UX system for every Nordman product.
+
+The order is fixed: **Base UI > shadcn > NIF**. Each component takes its behaviour and accessibility from a Base UI primitive, follows the shadcn composition, and is styled only by NIF tokens. Colour, spacing, radius, font size and icon size come from the Theming settings, so a product never hardcodes them.
+
+Docs and live examples: https://design.nordman.app
+
+## Install
+
+```bash
+npm install @nordmanai/nif @base-ui/react framer-motion lucide-react react react-dom
+```
+
+## Use
+
+Load the styles once, near the root of the app.
+
+```tsx
+import '@nordmanai/nif/styles.css';
+```
+
+Then import components.
+
+```tsx
+import { NmButton, NmDropdownMenu, NmDropdownMenuContent, NmDropdownMenuItem, NmDropdownMenuTrigger } from '@nordmanai/nif';
+import { nmButtonClassName } from '@nordmanai/nif';
+
+export function Example() {
+  return (
+    <>
+      <NmButton label="Save" tone="filled" icon="check" />
+      <NmDropdownMenu>
+        <NmDropdownMenuTrigger className={nmButtonClassName('outline')}>Open</NmDropdownMenuTrigger>
+        <NmDropdownMenuContent>
+          <NmDropdownMenuItem>Profile</NmDropdownMenuItem>
+        </NmDropdownMenuContent>
+      </NmDropdownMenu>
+    </>
+  );
+}
+```
+
+## Icons and marks
+
+Some components load icons and marks by URL from `/interface/`. Serve the package's `interface` folder at that path.
+
+```bash
+cp -r node_modules/@nordmanai/nif/interface public/interface
+```
+
+## Theming
+
+```tsx
+import { applyAppearanceState, createDefaultAppearanceState } from '@nordmanai/nif';
+
+applyAppearanceState({ ...createDefaultAppearanceState(), uiRadiusPercent: 120, uiSpacePercent: 110 });
+```
+
+## Source of truth
+
+NIF is authored in the Nordman web repo (`ui/` and `assets/tokens.css`). This package is built from that source. Never edit a copy in a product.
+
+## Add one component
+
+Install a component, and only what it is built from, into a product. The files are copied, so you can read them,
+and `nif update` brings them back in line with the kit.
+
+```bash
+npx @nordmanai/nif@latest init            # tokens, base styles and nif.json
+npx @nordmanai/nif@latest add button      # the component, what it needs and its libraries
+npx @nordmanai/nif@latest list            # every component, and which you have
+npx @nordmanai/nif@latest diff button     # what changed in the kit since you copied it
+npx @nordmanai/nif@latest update button   # copy the kit version over
+```
+
+`init` writes `src/nordman-ui/nordman.css`. Import it once, before the app renders. Options: `--dir`, `--alias`,
+`--overwrite`, `--no-install`. A file you changed is kept unless you pass `--overwrite`. The package install above
+stays the default for a product that wants the whole kit.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.

package/bin/nif.mjs

@@ -0,0 +1,196 @@
+#!/usr/bin/env node
+// nif: put NIF components into a product, one at a time, the way shadcn does.
+//   nif init                 the tokens, the base styles and nif.json
+//   nif add button field     the component, everything it is built from, and the libraries it needs
+//   nif list                 every component, and which are installed
+//   nif diff button          what changed in the kit since you copied it
+//   nif update [button ...]  copy the kit version over (all installed components when none are named)
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const registryDir = path.join(path.dirname(fileURLToPath(import.meta.url)), '../registry');
+const registry = JSON.parse(readFileSync(path.join(registryDir, 'index.json'), 'utf8'));
+const cwd = process.cwd();
+const configPath = path.join(cwd, 'nif.json');
+
+const HEADER = `/* @nordmanai/nif ${registry.version}. Copied by "nif add". Update it with "nif update". Do not edit it by hand. */\n`;
+const HEADER_LINE = /^\/\* @nordmanai\/nif [^\n]* \*\/\n/;
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const valueOf = (name) => {
+  const at = args.indexOf(name);
+  return at >= 0 ? args[at + 1] : undefined;
+};
+const positional = args.filter((a, i) => !a.startsWith('--') && !(i > 0 && ['--dir', '--alias'].includes(args[i - 1])));
+const [command, ...names] = positional;
+
+const say = (text = '') => console.log(text);
+const fail = (text) => {
+  console.error(`nif: ${text}`);
+  process.exit(1);
+};
+
+const readConfig = () => {
+  if (!existsSync(configPath)) fail('there is no nif.json here. Run "nif init" first.');
+  return JSON.parse(readFileSync(configPath, 'utf8'));
+};
+const writeConfig = (config) => writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+
+const itemFor = (name) => {
+  const key = name.replace(/^nm-/, '');
+  const item = registry.items[key];
+  if (!item) fail(`there is no component called "${name}". Run "nif list" to see them.`);
+  return [key, item];
+};
+
+const withHeader = (text) => HEADER + text;
+const withoutHeader = (text) => text.replace(HEADER_LINE, '');
+const targetOf = (config, rel) => path.join(cwd, config.dir, 'ui', rel);
+const sourceOf = (rel) => readFileSync(path.join(registryDir, 'ui', rel), 'utf8');
+
+/** Copy a file out of the registry. Returns what happened. */
+function place(config, rel, { overwrite }) {
+  const to = targetOf(config, rel);
+  const text = sourceOf(rel);
+  if (existsSync(to) && !overwrite) {
+    return withoutHeader(readFileSync(to, 'utf8')) === text ? 'same' : 'kept';
+  }
+  mkdirSync(path.dirname(to), { recursive: true });
+  writeFileSync(to, withHeader(text));
+  return 'copied';
+}
+
+function packageManager() {
+  if (existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return ['pnpm', 'add'];
+  if (existsSync(path.join(cwd, 'yarn.lock'))) return ['yarn', 'add'];
+  if (existsSync(path.join(cwd, 'bun.lockb')) || existsSync(path.join(cwd, 'bun.lock'))) return ['bun', 'add'];
+  return ['npm', ['install']].flat();
+}
+
+function installLibs(libs) {
+  const manifest = existsSync(path.join(cwd, 'package.json')) ? JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8')) : {};
+  const have = { ...manifest.dependencies, ...manifest.devDependencies, ...manifest.peerDependencies };
+  const missing = [...new Set(libs)].filter((lib) => !(lib in have));
+  if (missing.length === 0) return;
+  const [bin, ...rest] = packageManager();
+  say(`Installing ${missing.join(', ')} with ${bin}`);
+  if (flags.has('--no-install')) {
+    say(`  Skipped. Run: ${[bin, ...rest, ...missing.map((lib) => (registry.versions[lib] ? `${lib}@${registry.versions[lib]}` : lib))].join(' ')}`);
+    return;
+  }
+  // The kit is tested against these versions, so ask for the same range.
+  const wanted = missing.map((lib) => (registry.versions[lib] ? `${lib}@${registry.versions[lib]}` : lib));
+  execFileSync(bin, [...rest, ...wanted], { cwd, stdio: 'inherit' });
+}
+
+/** components.css imports the CSS of every installed component, in the order the kit uses. */
+function writeComponentsCss(config) {
+  const css = new Set();
+  for (const name of config.installed) {
+    for (const rel of registry.items[name]?.files ?? []) if (rel.startsWith('components/') && rel.endsWith('.css')) css.add(rel);
+  }
+  const rank = (rel) => {
+    const index = registry.cssOrder.indexOf(rel.split('/')[1].replace(/^nm-/, ''));
+    return index < 0 ? registry.cssOrder.length : index;
+  };
+  const lines = [...css].sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).map((rel) => `@import '../${rel}';`);
+  const to = targetOf(config, 'styles/components.css');
+  mkdirSync(path.dirname(to), { recursive: true });
+  writeFileSync(to, `${HEADER}${lines.join('\n')}\n`);
+}
+
+function init() {
+  const config = { dir: valueOf('--dir') ?? 'src/nordman-ui', alias: valueOf('--alias') ?? '@/nordman-ui', version: registry.version, installed: [] };
+  for (const rel of registry.core.files) place(config, rel, { overwrite: flags.has('--overwrite') });
+  const tokens = path.join(cwd, config.dir, 'tokens.css');
+  mkdirSync(path.dirname(tokens), { recursive: true });
+  writeFileSync(tokens, withHeader(readFileSync(path.join(registryDir, 'tokens.css'), 'utf8')));
+  const fonts = [400, 500, 600, 700].map((w) => `@import '@fontsource/poppins/latin-${w}.css';`).concat([400, 500].map((w) => `@import '@fontsource/geist-mono/latin-${w}.css';`));
+  writeFileSync(
+    path.join(cwd, config.dir, 'nordman.css'),
+    `${fonts.join('\n')}\n@import './tokens.css';\n@import './ui/styles/tokens.css';\n@import './ui/styles/interface-theme.css';\n@import './ui/styles/light-appearance.css';\n@import './ui/styles/utilities.css';\n@import './ui/styles/components.css';\n`,
+  );
+  writeComponentsCss(config);
+  writeConfig(config);
+  installLibs(registry.core.libs);
+  say(`NIF is set up in ${config.dir}.`);
+  say(`Load the styles once, before the app renders:\n  import '${config.alias}/nordman.css';`);
+  say('Then add components: nif add button');
+}
+
+function add(list) {
+  if (list.length === 0) fail('name a component, for example "nif add button".');
+  const config = readConfig();
+  const libs = [];
+  for (const name of list) {
+    const [key, item] = itemFor(name);
+    const outcome = { copied: [], same: [], kept: [] };
+    for (const rel of [...registry.core.files, ...item.files]) outcome[place(config, rel, { overwrite: flags.has('--overwrite') })].push(rel);
+    libs.push(...item.libs);
+    if (!config.installed.includes(key)) config.installed.push(key);
+    say(`${key}: ${outcome.copied.length} copied${outcome.kept.length ? `, ${outcome.kept.length} kept because you changed them (use --overwrite to replace)` : ''}`);
+    const main = item.dir ? item.files.find((f) => f === `components/${item.dir}/${item.dir}.tsx`) : undefined;
+    if (main) say(`  import { ... } from '${config.alias}/ui/${main.replace(/\.tsx$/, '')}';`);
+  }
+  config.version = registry.version;
+  writeComponentsCss(config);
+  writeConfig(config);
+  installLibs(libs);
+}
+
+function changes(config, key) {
+  const [, item] = itemFor(key);
+  const out = [];
+  for (const rel of item.files) {
+    const to = targetOf(config, rel);
+    if (!existsSync(to)) out.push([rel, 'missing']);
+    else if (withoutHeader(readFileSync(to, 'utf8')) !== sourceOf(rel)) out.push([rel, 'changed']);
+  }
+  return out;
+}
+
+function diff(list) {
+  const config = readConfig();
+  for (const name of list.length ? list : config.installed) {
+    const rows = changes(config, name);
+    say(rows.length === 0 ? `${name}: up to date` : `${name}:\n${rows.map(([rel, state]) => `  ${state}  ${rel}`).join('\n')}`);
+  }
+}
+
+function update(list) {
+  const config = readConfig();
+  const targets = list.length ? list : config.installed;
+  add(targets.map((n) => n), config) ;
+}
+
+function listAll() {
+  const config = existsSync(configPath) ? readConfig() : { installed: [] };
+  for (const [name, item] of Object.entries(registry.items)) {
+    say(`${config.installed.includes(name) ? '●' : '○'} ${name.padEnd(22)} ${item.libs.join(' ')}`);
+  }
+}
+
+switch (command) {
+  case 'init':
+    init();
+    break;
+  case 'add':
+    add(names);
+    break;
+  case 'list':
+    listAll();
+    break;
+  case 'diff':
+    diff(names);
+    break;
+  case 'update':
+    flags.add('--overwrite');
+    update(names);
+    break;
+  default:
+    say('nif init | add <component…> | list | diff [component…] | update [component…]');
+    say('Options: --dir <folder>  --alias <import path>  --overwrite  --no-install');
+}

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import './styles.css';
+export * from './ui/components/nm-ai/nm-ai.tsx';
+export * from './ui/components/nm-avatar/nm-avatar.tsx';
+export * from './ui/components/nm-bar-overflow/nm-bar-overflow.tsx';
+export * from './ui/components/nm-bar-overflow/use-bar-overflow.ts';
+export * from './ui/components/nm-brand-logo/nm-brand-logo.tsx';
+export * from './ui/components/nm-breadcrumb/nm-breadcrumb.tsx';
+export * from './ui/components/nm-button/nm-button.tsx';
+export * from './ui/components/nm-button-group/nm-button-group.tsx';
+export * from './ui/components/nm-calendar/nm-calendar.tsx';
+export * from './ui/components/nm-card/nm-card.tsx';
+export * from './ui/components/nm-chatbox/nm-chatbox-icon.tsx';
+export * from './ui/components/nm-chatbox/nm-chatbox.tsx';
+export * from './ui/components/nm-checkbox/nm-checkbox.tsx';
+export * from './ui/components/nm-chip/nm-chip.tsx';
+export * from './ui/components/nm-code-block/nm-code-block.tsx';
+export * from './ui/components/nm-collection/nm-collection-bar.tsx';
+export * from './ui/components/nm-collection/nm-collection-grid.tsx';
+export * from './ui/components/nm-collection/nm-collection-query.tsx';
+export * from './ui/components/nm-collection/nm-collection-row-menu.tsx';
+export * from './ui/components/nm-collection/nm-collection-table.tsx';
+export * from './ui/components/nm-collection/nm-collection-tile-actions.tsx';
+export * from './ui/components/nm-collection/nm-collection-title.tsx';
+export * from './ui/components/nm-collection/use-collection-scroll-reveal.ts';
+export * from './ui/components/nm-color-picker/nm-color-picker.tsx';
+export * from './ui/components/nm-combobox/nm-combobox.tsx';
+export * from './ui/components/nm-command/nm-command.tsx';
+export * from './ui/components/nm-composer/nm-composer.tsx';
+export * from './ui/components/nm-context-menu/nm-context-menu.tsx';
+export * from './ui/components/nm-date-picker/nm-date-picker.tsx';
+export * from './ui/components/nm-dialog/nm-dialog.tsx';
+export * from './ui/components/nm-dropdown/nm-dropdown-item.ts';
+export * from './ui/components/nm-dropdown/nm-dropdown-options.tsx';
+export * from './ui/components/nm-dropdown/nm-dropdown-panel.tsx';
+export * from './ui/components/nm-dropdown/nm-dropdown-placement.ts';
+export * from './ui/components/nm-dropdown/nm-dropdown.tsx';
+export * from './ui/components/nm-dropdown-menu/nm-dropdown-menu.tsx';
+export * from './ui/components/nm-field/nm-field.tsx';
+export * from './ui/components/nm-form-field/nm-form-field.tsx';
+export * from './ui/components/nm-gallery/nm-gallery.tsx';
+export * from './ui/components/nm-hover-card/nm-hover-card.tsx';
+export * from './ui/components/nm-icon/nm-icon.tsx';
+export * from './ui/components/nm-icon/nm-lucide.tsx';
+export * from './ui/components/nm-icon-border/nm-icon-border.tsx';
+export * from './ui/components/nm-input/nm-input.tsx';
+export * from './ui/components/nm-input-group/nm-input-group.tsx';
+export * from './ui/components/nm-label/nm-label.tsx';
+export * from './ui/components/nm-list-item/nm-list-item.tsx';
+export * from './ui/components/nm-menubar/nm-menubar.tsx';
+export * from './ui/components/nm-message/nm-message-actions.tsx';
+export * from './ui/components/nm-message/nm-message-meta.tsx';
+export * from './ui/components/nm-message/nm-text-shimmer.tsx';
+export * from './ui/components/nm-message/nm-trace.tsx';
+export * from './ui/components/nm-modal/nm-modal.tsx';
+export * from './ui/components/nm-native-select/nm-native-select.tsx';
+export * from './ui/components/nm-panel/nm-panel.tsx';
+export * from './ui/components/nm-panel-bar/nm-panel-bar.tsx';
+export * from './ui/components/nm-popover/nm-popover.tsx';
+export * from './ui/components/nm-progress/nm-progress.tsx';
+export * from './ui/components/nm-prose/nm-prose.tsx';
+export * from './ui/components/nm-questionnaire/nm-questionnaire.tsx';
+export * from './ui/components/nm-radio-group/nm-radio-group.tsx';
+export * from './ui/components/nm-rail-icon/nm-rail-icon.tsx';
+export * from './ui/components/nm-resize-handle/nm-resize-handle.tsx';
+export * from './ui/components/nm-segmented/nm-segmented.tsx';
+export * from './ui/components/nm-select/nm-select.tsx';
+export * from './ui/components/nm-separator/nm-separator.tsx';
+export * from './ui/components/nm-side-panel/nm-side-panel.tsx';
+export * from './ui/components/nm-slider/nm-slider.tsx';
+export * from './ui/components/nm-small-icon-button/nm-small-icon-button.tsx';
+export * from './ui/components/nm-status-bar/nm-status-bar.tsx';
+export * from './ui/components/nm-switch/nm-switch.tsx';
+export * from './ui/components/nm-table/nm-table.tsx';
+export * from './ui/components/nm-tabs/nm-tabs.tsx';
+export * from './ui/components/nm-textarea/nm-textarea.tsx';
+export * from './ui/components/nm-toggle/nm-toggle.tsx';
+export * from './ui/components/nm-toolbar/nm-toolbar.tsx';
+export * from './ui/components/nm-tooltip/nm-tooltip.tsx';
+export * from './ui/components/nm-top-bar/nm-top-bar.tsx';
+export * from './ui/components/nordman-icon-button/nordman-icon-button.tsx';
+export * from './ui/components/nordman-login/nordman-login.tsx';
+export * from './ui/components/nordman-login-field/nordman-login-field.tsx';
+export * from './ui/components/nordman-login-forgot/nordman-login-forgot.tsx';
+export * from './ui/components/nordman-login-google/nordman-login-google.tsx';
+export * from './ui/components/nordman-login-hero/nordman-login-hero.tsx';
+export * from './ui/components/nordman-login-register/nordman-login-register.tsx';
+export * from './ui/components/nordman-login-reset/nordman-login-reset.tsx';
+export * from './ui/components/nordman-login-reveal/nordman-login-reveal.tsx';
+export * from './ui/components/nordman-login-sign-in/nordman-login-sign-in.tsx';
+export * from './ui/components/nordman-toggle/nordman-toggle.tsx';
+export * from './ui/config/nm-ai.ts';
+export * from './ui/config/nm-app-panel.ts';
+export * from './ui/config/nm-appearance.ts';
+export * from './ui/config/nm-bar-overflow.ts';
+export * from './ui/config/nm-button.ts';
+export * from './ui/config/nm-chatbox-icons.ts';
+export * from './ui/config/nm-chatbox.ts';
+export * from './ui/config/nm-collection.ts';
+export * from './ui/config/nm-composer.ts';
+export * from './ui/config/nm-dropdown.ts';
+export * from './ui/config/nm-fade.ts';
+export * from './ui/config/nm-field.ts';
+export * from './ui/config/nm-header-icons.ts';
+export * from './ui/config/nm-icon-border.ts';
+export * from './ui/config/nm-icon-button.ts';
+export * from './ui/config/nm-icons.ts';
+export * from './ui/config/nm-list-item.ts';
+export * from './ui/config/nm-message.ts';
+export * from './ui/config/nm-modal.ts';
+export * from './ui/config/nm-panel-bar.ts';
+export * from './ui/config/nm-questionnaire.ts';
+export * from './ui/config/nm-radius.ts';
+export * from './ui/config/nm-rail-icons.ts';
+export * from './ui/config/nm-rail.ts';
+export * from './ui/config/nm-segmented.ts';
+export * from './ui/config/nm-side-panel.ts';
+export * from './ui/config/nm-site-palette.ts';
+export * from './ui/config/nm-small-icon-button.ts';
+export * from './ui/config/nm-tabs.ts';
+export * from './ui/config/nm-top-bar.ts';
+export * from './ui/config/nordman-chrome.ts';
+export * from './ui/config/nordman-login.ts';
+export * from './ui/lib/appearance/index.ts';
+export * from './ui/lib/nm-class.ts';