@imfusion/web-ui 0.5.0 → 0.5.1-dev.11.g2e949f6d

package/src/llms/skills/imf-web-ui-ux/SKILL.md

@@ -11,7 +11,7 @@ description:
 Most teams consuming `@imfusion/web-ui` don't have a designer on call. This skill stands in: it encodes the library authors'
 UX experience — the whole experience of a screen, its visual design, and the usability where both meet. Follow it by default;
 deviate when the product has a real reason to. Code-level patterns (tokens, layers, wrappers) live in
-`imf-web-ui-frontend-patterns`; project wiring lives in `imf-web-ui-setup`.
+`imf-web-ui-frontend-conventions`; project wiring lives in `imf-web-ui-library-setup`.
 
 Component names below are real — verify any API against the docgen index (`imf-web-ui-components`) before use. Never invent a
 component this library doesn't ship.
@@ -82,13 +82,13 @@ Every screen ships four states, not one:
 
 Custom UI the library doesn't cover should be indistinguishable from library UI: build it from `--imf-ui-*` tokens and
 compose it with library primitives. The goal lives here; the mechanics (tokens, layers, wrappers) live in
-`imf-web-ui-frontend-patterns`.
+`imf-web-ui-frontend-conventions`.
 
 ## Experimental components
 
 The identity index marks each component `stable` or `experimental`. Experimental ones are fine to use, but expect API
-movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-patterns`) so a breaking change lands in one
-file, not forty call sites.
+movement across releases — prefer wrapping them once (see `imf-web-ui-frontend-conventions`) so a breaking change lands in
+one file, not forty call sites.
 
 ## Deep dives
 

package/src/llms/skills/imf-web-ui-ux/references/forms.md

@@ -6,8 +6,10 @@ The 80/20 of forms, distilled from NN/g's form-design and error-guidelines artic
 most users — a cited CHI study found guideline-compliant forms hit 78% one-try error-free submission vs. 42% for
 non-compliant ones. Read before building any form beyond two fields.
 
-The library ships the controls (`Input`, `Select`, `Checkbox`, `Switch`, `Slider`) but no form or field wrapper — labels,
-grouping, and validation display are composed by you, which is exactly where these rules apply.
+The library ships the controls (`Input`, `Select`, `Checkbox`, `Switch`, `Slider`) but no form or field wrapper, so labels,
+grouping, and where errors appear are composed by you. That's exactly where these rules apply. Composing the markup is not
+the same as owning the state: form state and validation belong to a form library (see `imf-web-ui-frontend-conventions`), and
+these rules govern how its errors get presented.
 
 ## Structure
 

package/bin/install-skill.js

@@ -1,180 +0,0 @@
-#!/usr/bin/env node
-
-// Installs the consumer skill family (../src/llms/skills/imf-web-ui*/)
-// into the consumer project's agent skill directories. Runs in the
-// CONSUMER's environment, so it may only use this package's real runtime
-// dependencies (@clack/prompts). Never wire this into a postinstall hook:
-// ambient script execution on `npm install` is a live supply-chain attack
-// vector — install stays an explicit, user-run command.
-//
-// The skills cross-reference each other, so they install as one bundle.
-// When both targets are selected, .agents/skills/ holds the real copy and
-// .claude/skills/ symlinks it (this repo's own convention) so the two
-// can't drift apart.
-
-import {
-  cpSync,
-  existsSync,
-  lstatSync,
-  mkdirSync,
-  readdirSync,
-  readFileSync,
-  rmSync,
-  symlinkSync,
-  writeFileSync
-} from "node:fs";
-import { dirname, relative, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import * as p from "@clack/prompts";
-
-const SKILL_PREFIX = "imf-web-ui";
-const VERSION_MARKER = ".imf-web-ui-skill-version.json";
-
-const here = dirname(fileURLToPath(import.meta.url));
-// Source is relative to THIS SCRIPT's location (inside node_modules), not
-// the consumer's cwd — the script is invoked from the consumer's project
-// root, but the skills it copies ship alongside this file in the package.
-const skillsRoot = resolve(here, "..", "src", "llms", "skills");
-const packageJson = JSON.parse(readFileSync(resolve(here, "..", "package.json"), "utf-8"));
-const currentVersion = packageJson.version;
-
-// Destination is relative to the consumer's project root (cwd), since
-// that's where their `.claude/` or `.agents/` directory lives.
-const projectRoot = process.cwd();
-
-const TARGETS = {
-  claude: { label: "Claude Code", root: resolve(projectRoot, ".claude", "skills") },
-  agents: { label: "Vendor-neutral (.agents/)", root: resolve(projectRoot, ".agents", "skills") }
-};
-
-function discoverSkills() {
-  if (!existsSync(skillsRoot)) return [];
-  return readdirSync(skillsRoot, { withFileTypes: true })
-    .filter(entry => entry.isDirectory() && entry.name.startsWith(SKILL_PREFIX))
-    .map(entry => entry.name)
-    .sort();
-}
-
-function displayPath(absPath) {
-  return `./${relative(projectRoot, absPath)}`;
-}
-
-function readInstalledVersion(dir) {
-  const markerPath = resolve(dir, VERSION_MARKER);
-  if (!existsSync(markerPath)) return null;
-  try {
-    return JSON.parse(readFileSync(markerPath, "utf-8")).version ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function writeRealCopy(sourceDir, destDir) {
-  mkdirSync(dirname(destDir), { recursive: true });
-  // force: true makes re-running after a version bump overwrite cleanly.
-  cpSync(sourceDir, destDir, { recursive: true, force: true });
-  writeFileSync(resolve(destDir, VERSION_MARKER), JSON.stringify({ version: currentVersion }, null, 2) + "\n");
-}
-
-function writeSymlink(linkPath, targetPath) {
-  mkdirSync(dirname(linkPath), { recursive: true });
-  // lstat (not existsSync, which follows symlinks) catches a broken/stale
-  // symlink left over from a prior run, not just a real file or directory.
-  if (lstatSync(linkPath, { throwIfNoEntry: false })) {
-    rmSync(linkPath, { recursive: true, force: true });
-  }
-  symlinkSync(relative(dirname(linkPath), targetPath), linkPath);
-}
-
-// --target claude|agents (repeatable) selects targets without the
-// interactive prompt — for CI and scripted installs.
-function parseTargetFlags(argv) {
-  const targets = [];
-  for (let i = 0; i < argv.length; i++) {
-    if (argv[i] !== "--target") continue;
-    const value = argv[i + 1];
-    if (!value || !(value in TARGETS)) {
-      console.error(`--target expects one of: ${Object.keys(TARGETS).join(", ")}`);
-      process.exit(1);
-    }
-    targets.push(value);
-    i++;
-  }
-  return targets;
-}
-
-async function main() {
-  const skills = discoverSkills();
-  const flagTargets = parseTargetFlags(process.argv.slice(2));
-
-  p.intro(`@imfusion/web-ui — install the ${SKILL_PREFIX} skills (${skills.length})`);
-
-  if (skills.length === 0) {
-    p.log.error(`No skills found at ${skillsRoot}. Reinstall @imfusion/web-ui and try again.`);
-    p.outro("Nothing installed.");
-    process.exitCode = 1;
-    return;
-  }
-
-  const existingVersions = Object.values(TARGETS)
-    .flatMap(({ root }) => skills.map(name => readInstalledVersion(resolve(root, name))))
-    .filter(Boolean);
-  if (existingVersions.length > 0 && existingVersions.every(v => v === currentVersion)) {
-    p.log.info(`Already up to date (v${currentVersion}). Re-running will overwrite with the same content.`);
-  } else if (existingVersions.some(v => v !== currentVersion)) {
-    const from = existingVersions.find(v => v !== currentVersion);
-    p.log.info(`Updating installed skills from v${from} to v${currentVersion}.`);
-  }
-
-  p.log.message(`Skills in this bundle:\n${skills.map(name => `  - ${name}`).join("\n")}`);
-
-  let selected;
-  if (flagTargets.length > 0) {
-    selected = flagTargets;
-    p.log.info(`Targets from --target flags: ${selected.join(", ")}`);
-  } else {
-    selected = await p.multiselect({
-      message: "Install into which skill directory (or directories)?",
-      options: Object.entries(TARGETS).map(([key, { label, root }]) => ({
-        value: key,
-        label,
-        hint: displayPath(root)
-      })),
-      required: true
-    });
-
-    if (p.isCancel(selected)) {
-      p.cancel("Cancelled — nothing installed.");
-      return;
-    }
-  }
-
-  const both = selected.includes("claude") && selected.includes("agents");
-
-  for (const name of skills) {
-    const sourceDir = resolve(skillsRoot, name);
-    if (both) {
-      // .agents/ is the canonical real copy; .claude/ aliases it via symlink.
-      const realDir = resolve(TARGETS.agents.root, name);
-      writeRealCopy(sourceDir, realDir);
-      writeSymlink(resolve(TARGETS.claude.root, name), realDir);
-    } else {
-      for (const key of selected) {
-        writeRealCopy(sourceDir, resolve(TARGETS[key].root, name));
-      }
-    }
-  }
-
-  if (both) {
-    p.log.success(`Vendor-neutral (.agents/) -> ${displayPath(TARGETS.agents.root)}/${SKILL_PREFIX}*`);
-    p.log.success(`Claude Code -> ${displayPath(TARGETS.claude.root)}/${SKILL_PREFIX}* (symlinks -> .agents/)`);
-  } else {
-    for (const key of selected) {
-      p.log.success(`${TARGETS[key].label} -> ${displayPath(TARGETS[key].root)}/${SKILL_PREFIX}*`);
-    }
-  }
-
-  p.outro(`Done — ${skills.length} skills installed.`);
-}
-
-await main();

package/src/llms/skills/imf-web-ui-frontend-patterns/SKILL.md

@@ -1,67 +0,0 @@
----
-name: imf-web-ui-frontend-patterns
-description:
-  "Raise the quality of frontend code written around @imfusion/web-ui — including quickly vibe-coded frontends. Library
-  boundary contract (tokens, CSS layers, type derivation), component roles, state placement, effects discipline, and stack
-  defaults. Load when writing wrapper components, custom UI, or styling beyond the defaults."
----
-
-# imf-web-ui-frontend-patterns
-
-One guard, once: **if the host project already has a convention — a styling system, a state library, a folder shape — the
-project wins.** These defaults fill vacuums. They are not a license to refactor a consumer codebase toward this document.
-
-Everything else below is how to build.
-
-## Stay behind the library
-
-Never import Base UI (or any other upstream this library wraps) directly — no upstream stylesheets, no upstream components,
-even when upstream docs show it that way. Everything a component needs ships in `@imfusion/web-ui`. If the library is missing
-something upstream has, report the gap (see `imf-web-ui-components`); don't reach around it.
-
-## Style through the sanctioned seams
-
-All library styles live in the `imf-ui.components` CSS layer, so **any plain selector you write wins** — that's the whole
-override contract:
-
-- Target the stable hooks: `data-imf-ui-component` attributes and your own classes/wrappers.
-- Never target the library's internal class names — they are generated and change without notice.
-- Never `!important` — if you think you need it, you're targeting the wrong thing.
-
-## Build custom UI from tokens
-
-Anything you build that the library doesn't cover — a stat widget, a custom panel — uses `--imf-ui-*` variables for color,
-spacing, radius, and type instead of hardcoded values. That's what makes custom UI look native next to library components,
-and what keeps it correct when the theme changes. A hex code or a magic `px` next to a concept the tokens already name is a
-defect.
-
-## Derive types, don't import them
-
-Prop types come from the components themselves: `React.ComponentProps<typeof Button>`. The library deliberately exports no
-`Props` types — don't look for them, and don't re-declare prop shapes by hand.
-
-## Integrations own their peers
-
-Components under `@imfusion/web-ui/integrations/*` depend on optional peers (e.g. `@tanstack/highlight` for `CodeHighlight`).
-Add the peer explicitly to the consumer's `package.json` — never rely on hoisting.
-
-## React patterns
-
-The full treatment — component roles with an example, state placement, effects discipline, and the react.dev sources to
-consult while building — lives in [references/react-patterns.md](references/react-patterns.md). Read it before writing new
-screens or wrappers. The core in one breath:
-
-- **Three roles.** Dumb components own how things look, layout components own arrangement, smart containers own data and
-  logic. Styling never lives in containers.
-- **State lives where its truth lives.** URL → query cache → context → store → local state; walk the list, stop at the first
-  match.
-- **Effects are a last resort**, and always extracted into purpose-named hooks.
-- **Compose, don't configure.** If a component's prop list reads like a settings page, it wanted to be two or three
-  components.
-
-## Starting a frontend from scratch
-
-When the consumer app is greenfield, default to the TanStack suite: **Router** (URL state, type-safe search params),
-**Query** (server state), **Form** (form state), and **Table** for data grids, which you pair with web-ui's styled `Table`
-parts (`Table.SortableHeaderCell` carries the sort glue). Documentation is available straight from the terminal via
-`npx tanstack`. This is the stack the state ladder assumes.

package/src/llms/skills/imf-web-ui-setup/SKILL.md

@@ -1,30 +0,0 @@
----
-name: imf-web-ui-setup
-description:
-  "One-time wiring of @imfusion/web-ui into a consumer project: the styles import and the WebUIProvider wrapper. Load when
-  installing the library for the first time, or when its components render unstyled or without theme context."
----
-
-# imf-web-ui-setup
-
-Every consumer entry point needs exactly two lines, in this order:
-
-```tsx
-import "@imfusion/web-ui/styles.css";
-import { WebUIProvider, Button } from "@imfusion/web-ui";
-```
-
-Wrap the app root in `<WebUIProvider>` once. Components rendered outside it won't have the theme/CSS-variable context they
-expect.
-
-Never import a Base UI (or other upstream) stylesheet or component directly — everything a web-ui component needs is already
-inside `styles.css` and the package's own exports; reaching around web-ui to the upstream library is always wrong, even if
-the upstream docs show it that way.
-
-## Symptoms of a broken setup
-
-- **Components render but look unstyled** — the `styles.css` import is missing from the entry point.
-- **Components render but ignore the theme (wrong colors, no CSS variables resolving)** — they're mounted outside
-  `<WebUIProvider>`.
-- **An integration component throws on import** — its optional peer dependency isn't installed; check the component's
-  description in the docgen index (`imf-web-ui-components`) for which peer to add to your `package.json`.