@oicl/openbridge-webcomponents-full-bundle 2.0.0-next.120 → 2.0.0-next.122

package/script/sync-agent-docs.test.ts

@@ -0,0 +1,298 @@
+import {readFileSync} from 'node:fs';
+import {describe, expect, it} from 'vitest';
+import {parseAgentDoc, type AgentDoc} from './agent-docs/frontmatter.js';
+import {
+  ROUTING_MARKER,
+  renderClaudeMd,
+  renderCopilotInstructions,
+  renderCursorRule,
+  renderInstructionsFile,
+  renderRoutingTable,
+  replaceMarkedBlock,
+  rewriteSiblingLinks,
+} from './agent-docs/emitters.js';
+
+const VALID = `---
+name: a11y
+description: Accessibility (WCAG 2.1 AA) — keyboard nav, ARIA, focus
+globs:
+  - packages/openbridge-webcomponents/src/components/**
+  - packages/openbridge-webcomponents/src/automation/**
+---
+
+# Accessibility Instructions
+
+Body text.
+`;
+
+describe('parseAgentDoc', () => {
+  it('parses name, description and globs', () => {
+    const doc = parseAgentDoc(VALID, 'docs/agents/a11y.md');
+    expect(doc.name).toBe('a11y');
+    expect(doc.description).toBe(
+      'Accessibility (WCAG 2.1 AA) — keyboard nav, ARIA, focus'
+    );
+    expect(doc.globs).toEqual([
+      'packages/openbridge-webcomponents/src/components/**',
+      'packages/openbridge-webcomponents/src/automation/**',
+    ]);
+  });
+
+  it('returns the body without the frontmatter', () => {
+    const doc = parseAgentDoc(VALID, 'docs/agents/a11y.md');
+    expect(doc.body).toBe('# Accessibility Instructions\n\nBody text.\n');
+  });
+
+  it('strips single quotes used to escape leading "!"', () => {
+    const raw = `---
+name: jsdoc
+description: JSDoc rules
+globs:
+  - packages/openbridge-webcomponents/src/**/*.ts
+  - '!packages/openbridge-webcomponents/src/icons/**'
+---
+body
+`;
+    expect(parseAgentDoc(raw, 'docs/agents/jsdoc.md').globs[1]).toBe(
+      '!packages/openbridge-webcomponents/src/icons/**'
+    );
+  });
+
+  it('throws when name does not match the filename', () => {
+    expect(() => parseAgentDoc(VALID, 'docs/agents/wrong.md')).toThrow(
+      /name "a11y" does not match filename "wrong"/
+    );
+  });
+
+  it('throws on an unsupported key', () => {
+    const raw = `---
+name: x
+description: d
+globs:
+  - a/**
+alwaysApply: true
+---
+body
+`;
+    expect(() => parseAgentDoc(raw, 'docs/agents/x.md')).toThrow(
+      /unsupported key "alwaysApply" on line 6/
+    );
+  });
+
+  it('throws when globs is empty', () => {
+    const raw = `---
+name: x
+description: d
+globs:
+---
+body
+`;
+    expect(() => parseAgentDoc(raw, 'docs/agents/x.md')).toThrow(
+      /"globs" must list at least one pattern/
+    );
+  });
+
+  it('throws when there is no frontmatter', () => {
+    expect(() =>
+      parseAgentDoc('# no frontmatter\n', 'docs/agents/x.md')
+    ).toThrow(/must start with a "---" frontmatter block/);
+  });
+});
+
+const DOC: AgentDoc = {
+  name: 'a11y',
+  description: 'Accessibility (WCAG 2.1 AA)',
+  globs: ['packages/openbridge-webcomponents/src/components/**'],
+  body: '# Accessibility\n\nBody.\n',
+  sourcePath: 'docs/agents/a11y.md',
+};
+
+describe('renderInstructionsFile', () => {
+  it('writes applyTo from globs and keeps the body verbatim', () => {
+    const out = renderInstructionsFile(DOC);
+    expect(out).toContain(
+      'applyTo: "packages/openbridge-webcomponents/src/components/**"'
+    );
+    expect(out).toContain('# Accessibility\n\nBody.\n');
+  });
+
+  it('joins multiple globs with commas', () => {
+    const out = renderInstructionsFile({...DOC, globs: ['a/**', 'b/**']});
+    expect(out).toContain('applyTo: "a/**,b/**"');
+  });
+
+  it('includes a do-not-edit banner naming the source and the command', () => {
+    const out = renderInstructionsFile(DOC);
+    expect(out).toContain('GENERATED FILE — DO NOT EDIT');
+    expect(out).toContain('docs/agents/a11y.md');
+    expect(out).toContain('npm run agents:sync');
+  });
+
+  it('puts the frontmatter first so Copilot can read applyTo', () => {
+    expect(renderInstructionsFile(DOC).startsWith('---\napplyTo:')).toBe(true);
+  });
+});
+
+describe('renderRoutingTable', () => {
+  it('emits one row per doc with description and globs', () => {
+    const table = renderRoutingTable([DOC]);
+    expect(table).toContain('[a11y](docs/agents/a11y.md)');
+    expect(table).toContain('Accessibility (WCAG 2.1 AA)');
+    expect(table).toContain(
+      '`packages/openbridge-webcomponents/src/components/**`'
+    );
+  });
+
+  it('sorts rows by name regardless of input order', () => {
+    const z: AgentDoc = {
+      ...DOC,
+      name: 'zebra',
+      sourcePath: 'docs/agents/zebra.md',
+    };
+    const table = renderRoutingTable([z, DOC]);
+    expect(table.indexOf('[a11y]')).toBeLessThan(table.indexOf('[zebra]'));
+  });
+});
+
+describe('renderCopilotInstructions', () => {
+  it('points at AGENTS.md and carries the routing table but no bodies', () => {
+    const out = renderCopilotInstructions([DOC]);
+    expect(out).toContain('AGENTS.md');
+    expect(out).toContain('[a11y](docs/agents/a11y.md)');
+    expect(out).not.toContain('Body.');
+  });
+});
+
+describe('replaceMarkedBlock', () => {
+  it('replaces only the content between the markers', () => {
+    const content = [
+      'before',
+      `<!-- ${ROUTING_MARKER}:start -->`,
+      'OLD',
+      `<!-- ${ROUTING_MARKER}:end -->`,
+      'after',
+    ].join('\n');
+    const out = replaceMarkedBlock(content, ROUTING_MARKER, 'NEW');
+    expect(out).toBe(
+      [
+        'before',
+        `<!-- ${ROUTING_MARKER}:start -->`,
+        'NEW',
+        `<!-- ${ROUTING_MARKER}:end -->`,
+        'after',
+      ].join('\n')
+    );
+  });
+
+  it('throws when the markers are missing', () => {
+    expect(() => replaceMarkedBlock('no markers', ROUTING_MARKER, 'x')).toThrow(
+      /markers .* not found/
+    );
+  });
+});
+
+describe('renderClaudeMd', () => {
+  it('points at AGENTS.md and docs/agents', () => {
+    const out = renderClaudeMd();
+    expect(out).toContain('AGENTS.md');
+    expect(out).toContain('docs/agents/');
+    expect(out).toContain('GENERATED FILE — DO NOT EDIT');
+  });
+
+  it('carries no rules of its own — it is a pointer, not a source', () => {
+    const out = renderClaudeMd();
+    expect(out).toContain('intentionally adds nothing of its own');
+    // No numbered rule list: team rules belong in AGENTS.md, path-scoped rules
+    // in docs/agents/. Neither is tool-specific.
+    expect(out).not.toMatch(/^\d+\. \*\*/m);
+  });
+});
+
+describe('CLI failure semantics', () => {
+  const cli = 'script/sync-agent-docs.ts';
+
+  it('write mode never exits non-zero, so `prepare` cannot break npm ci', () => {
+    const src = readFileSync(cli, 'utf8');
+    expect(src).toContain('if (CHECK) process.exit(1);');
+    expect(src).not.toMatch(/^\s*process\.exit\(1\);\s*$/m);
+  });
+
+  it('only skips negative globs in the resolution check', () => {
+    const src = readFileSync(cli, 'utf8');
+    expect(src).toContain("if (g.startsWith('!')) continue;");
+  });
+});
+
+describe('renderCursorRule', () => {
+  it('emits globs + alwaysApply:false — Cursor\'s "Apply to Specific Files" type', () => {
+    const out = renderCursorRule(DOC);
+    expect(out.startsWith('---\n')).toBe(true);
+    expect(out).toContain(
+      'globs: packages/openbridge-webcomponents/src/components/**'
+    );
+    expect(out).toContain('alwaysApply: false');
+  });
+
+  it('omits description, which would select "Apply Intelligently" instead', () => {
+    expect(renderCursorRule(DOC)).not.toContain('description:');
+  });
+
+  it('joins multiple globs with commas', () => {
+    expect(renderCursorRule({...DOC, globs: ['a/**', 'b/**']})).toContain(
+      'globs: a/**,b/**'
+    );
+  });
+
+  it('drops negative globs, which Cursor does not document', () => {
+    const out = renderCursorRule({...DOC, globs: ['a/**', '!b/**', 'c/**']});
+    expect(out).toContain('globs: a/**,c/**');
+    expect(out).not.toContain('!b/**');
+  });
+
+  it('keeps the body verbatim and carries the do-not-edit banner', () => {
+    const out = renderCursorRule(DOC);
+    expect(out).toContain('# Accessibility\n\nBody.\n');
+    expect(out).toContain('GENERATED FILE — DO NOT EDIT');
+  });
+});
+
+describe('rewriteSiblingLinks', () => {
+  const siblings = new Set(['jsdoc', 'a11y', 'css-postcss']);
+
+  it('repoints bare sibling links at the canonical doc', () => {
+    expect(rewriteSiblingLinks('see [`jsdoc.md`](jsdoc.md).', siblings)).toBe(
+      'see [`jsdoc.md`](../../docs/agents/jsdoc.md).'
+    );
+  });
+
+  it('preserves anchors', () => {
+    expect(rewriteSiblingLinks('[x](a11y.md#section-2)', siblings)).toBe(
+      '[x](../../docs/agents/a11y.md#section-2)'
+    );
+  });
+
+  it('leaves ../../ links alone — they already resolve from every adapter dir', () => {
+    const link = '[g](../../IMPLEMENTATION_GUIDELINES.md#-postcss)';
+    expect(rewriteSiblingLinks(link, siblings)).toBe(link);
+  });
+
+  it('leaves external and absolute links alone', () => {
+    const body = '[a](https://example.com/x.md) [b](/abs/y.md)';
+    expect(rewriteSiblingLinks(body, siblings)).toBe(body);
+  });
+
+  it('leaves bare links that are not canonical docs alone', () => {
+    const link = '[r](README.md)';
+    expect(rewriteSiblingLinks(link, siblings)).toBe(link);
+  });
+
+  it('is applied by both adapter renderers', () => {
+    const doc = {...DOC, body: 'see [`jsdoc.md`](jsdoc.md).\n'};
+    expect(renderInstructionsFile(doc, siblings)).toContain(
+      '](../../docs/agents/jsdoc.md)'
+    );
+    expect(renderCursorRule(doc, siblings)).toContain(
+      '](../../docs/agents/jsdoc.md)'
+    );
+  });
+});

package/script/sync-agent-docs.ts

@@ -0,0 +1,156 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {globSync} from 'glob';
+import * as prettier from 'prettier';
+import {parseAgentDoc, type AgentDoc} from './agent-docs/frontmatter.js';
+import {
+  ROUTING_MARKER,
+  renderClaudeMd,
+  renderCopilotInstructions,
+  renderCursorRule,
+  renderInstructionsFile,
+  renderRoutingTable,
+  replaceMarkedBlock,
+} from './agent-docs/emitters.js';
+
+const ROOT = path.resolve(import.meta.dirname, '../../..');
+const AGENTS_DIR = path.join(ROOT, 'docs/agents');
+const INSTRUCTIONS_DIR = path.join(ROOT, '.github/instructions');
+const CURSOR_RULES_DIR = path.join(ROOT, '.cursor/rules');
+const CHECK = process.argv.includes('--check');
+
+const problems: string[] = [];
+const writes = new Map<string, string>();
+
+function plan(absPath: string, content: string): void {
+  writes.set(absPath, content);
+}
+
+function loadDocs(): AgentDoc[] {
+  if (!fs.existsSync(AGENTS_DIR)) {
+    throw new Error(
+      `docs/agents does not exist at ${AGENTS_DIR} — nothing to sync`
+    );
+  }
+  return fs
+    .readdirSync(AGENTS_DIR)
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+    .map((f) => {
+      const rel = path.posix.join('docs/agents', f);
+      return parseAgentDoc(
+        fs.readFileSync(path.join(AGENTS_DIR, f), 'utf8'),
+        rel
+      );
+    });
+}
+
+/** Check 1 — every positive glob must match at least one real path. */
+function checkGlobs(docs: AgentDoc[]): void {
+  for (const doc of docs) {
+    for (const g of doc.globs) {
+      if (g.startsWith('!')) continue;
+      if (globSync(g, {cwd: ROOT, dot: true}).length === 0) {
+        problems.push(`${doc.sourcePath}: glob matches nothing → ${g}`);
+      }
+    }
+  }
+}
+
+/** Check 4 — no generated adapter without a canonical source. */
+function checkOrphans(docs: AgentDoc[]): void {
+  const adapters: [string, string, string][] = [
+    [INSTRUCTIONS_DIR, '.instructions.md', '.github/instructions'],
+    [CURSOR_RULES_DIR, '.mdc', '.cursor/rules'],
+  ];
+  for (const [dir, ext, rel] of adapters) {
+    if (!fs.existsSync(dir)) continue;
+    const expected = new Set(docs.map((d) => `${d.name}${ext}`));
+    for (const f of fs.readdirSync(dir)) {
+      if (f.endsWith(ext) && !expected.has(f)) {
+        problems.push(
+          `${rel}/${f}: no matching docs/agents/ source (delete it or add the source)`
+        );
+      }
+    }
+  }
+}
+
+const docs = loadDocs();
+checkGlobs(docs);
+checkOrphans(docs);
+
+const routable = docs;
+const docNames = new Set(docs.map((d) => d.name));
+
+for (const doc of routable) {
+  plan(
+    path.join(INSTRUCTIONS_DIR, `${doc.name}.instructions.md`),
+    renderInstructionsFile(doc, docNames)
+  );
+  plan(
+    path.join(CURSOR_RULES_DIR, `${doc.name}.mdc`),
+    renderCursorRule(doc, docNames)
+  );
+}
+plan(
+  path.join(ROOT, '.github/copilot-instructions.md'),
+  renderCopilotInstructions(routable)
+);
+
+const agentsPath = path.join(ROOT, 'AGENTS.md');
+plan(
+  agentsPath,
+  replaceMarkedBlock(
+    fs.readFileSync(agentsPath, 'utf8'),
+    ROUTING_MARKER,
+    renderRoutingTable(routable)
+  )
+);
+
+plan(path.join(ROOT, 'CLAUDE.md'), renderClaudeMd());
+
+/**
+ * Runs generated Markdown through Prettier before writing or comparing.
+ *
+ * Without this the generator's compact tables would differ from what
+ * `npm run format:check` (and the lint-staged `.md` hook) demand, so every
+ * sync would leave the repo format-dirty and CI would fail. Formatting here
+ * makes generator output and Prettier output the same artefact by
+ * construction, and keeps `--check` comparing like with like.
+ */
+async function format(content: string, absPath: string): Promise<string> {
+  const config = await prettier.resolveConfig(absPath);
+  return prettier.format(content, {
+    ...config,
+    filepath: absPath,
+    parser: 'markdown',
+  });
+}
+
+for (const [absPath, raw] of writes) {
+  const rel = path.relative(ROOT, absPath);
+  const content = await format(raw, absPath);
+  const current = fs.existsSync(absPath)
+    ? fs.readFileSync(absPath, 'utf8')
+    : null;
+  if (current === content) continue;
+  if (CHECK) {
+    problems.push(`${rel}: out of date — run \`npm run agents:sync\``);
+  } else {
+    fs.mkdirSync(path.dirname(absPath), {recursive: true});
+    fs.writeFileSync(absPath, content);
+    console.log(`${current === null ? 'created' : 'updated'} ${rel}`);
+  }
+}
+
+if (problems.length > 0) {
+  console.error(`\nagent-docs: ${problems.length} problem(s)`);
+  for (const p of problems) console.error(`  ${CHECK ? '✗' : 'warning:'} ${p}`);
+  // Write mode reports but never fails. `agents:sync` runs from the root
+  // `prepare` script, so a stale glob or a missing source must not be able to
+  // break `npm ci` for everyone. `lint:agents` is the gate; it runs in CI after
+  // the build steps, when any generated paths actually exist.
+  if (CHECK) process.exit(1);
+}
+console.log(CHECK ? 'agent-docs: up to date' : 'agent-docs: sync complete');

package/src/automation/automation-tank/automation-tank.css

@@ -77,6 +77,39 @@
   min-width: 0;
   min-height: 0;
 }
+
+/* Indefinite-axis fallback.
+ *
+ * `width`/`height: 100%` only resolve when the parent's corresponding axis is
+ * definite. In a flex/grid dashboard slot one axis is very often left to
+ * content — `align-self: center` makes the cross axis shrink-to-fit, and a
+ * parent sized with `min-height`/`max-height` (rather than `height`) leaves the
+ * block axis indefinite. In those cases the percentage computes to `auto` and
+ * the tank would size to its own content, which includes the chart cell — and
+ * the chart sizes itself from the cell it was measured in. That is a circular
+ * constraint, and it resolves as a collapsed cell, unbounded growth or
+ * pixel-level ringing depending on the loop gain (issue #1121).
+ *
+ * `aspect-ratio` supplies the missing axis from the design footprint the
+ * `point` variant uses above, so an indefinite axis lands on a definite value
+ * that no longer depends on the tank's own content. It is inert when the parent
+ * makes both axes definite, so the normal "fill my slot" behavior is unchanged.
+ */
+:host([positioning="button"]) {
+  aspect-ratio: 256 / 376;
+}
+:host([positioning="button"][orientation="horizontal"]) {
+  aspect-ratio: 420 / 256;
+}
+:host([positioning="button"][compact]),
+:host([positioning="button"][static]) {
+  aspect-ratio: 170 / 282;
+}
+:host([positioning="button"][orientation="horizontal"][compact]),
+:host([positioning="button"][orientation="horizontal"][static]) {
+  aspect-ratio: 244 / 208;
+}
+
 :host([positioning="button"]) .root {
   position: static;
   top: auto;
@@ -134,10 +167,30 @@
   display: flex;
   flex-direction: column;
   gap: 4px;
+}
+
+/* Interactive (`clickable`, the default): the full six-state flat mixin —
+ * enabled, activated, hover, pressed, focus-visible, disabled — painted on
+ * `.halo`. */
+.root.clickable {
   cursor: pointer;
   /* prettier-ignore */
   @mixin style style=flat visibleWrapperClass=.halo;
 }
+
+/* Non-interactive (`clickable` is `false`, and `static`, which is display-only
+ * by definition): the mixin's `noClick` variant emits the enabled state ONLY, so
+ * the halo keeps exactly the same resting colors and the same 1px border box
+ * — no layout shift, nothing else in the tank changes — while hover, pressed
+ * and focus-visible disappear. The root is a `<div>` in this case, so there is
+ * no focus ring or tab stop to suppress either. Same split as
+ * `obc-elevated-card`'s `.not-clickable` / `:not(.not-clickable)` pair. */
+.root:not(.clickable) {
+  cursor: default;
+  /* prettier-ignore */
+  @mixin style style=flat noClick visibleWrapperClass=.halo;
+}
+
 .root:focus {
   outline: none;
 }
@@ -156,10 +209,12 @@
   top: auto;
 }
 
-/* Static is display-only: not focusable (rendered as <div>) and not
- * interactive — disable :hover/:active visuals from the flat-mixin rules. */
+/* Static is display-only, so it never gets the `.clickable` class and the
+ * hover/pressed visuals are already gone via the `noClick` rule above. Static
+ * additionally refuses pointer events outright — unlike a non-clickable tank,
+ * which still lets clicks reach the host so a consumer can opt into handling
+ * them. */
 :host([static]) .root {
-  cursor: default;
   pointer-events: none;
 }
 
@@ -510,9 +565,21 @@
   overflow: hidden;
 }
 
+/* The renderers are taken out of flow so the cell sizes them, never the other
+ * way round. Both of them derive a pixel size from the box they are measured
+ * in — `obc-gauge-trend` publishes an inline `--chart-height` computed from its
+ * own measured width, and `obc-bar-vertical` writes `height: 100%; width: auto`
+ * onto its own host — so while they are in flow the cell's content height is a
+ * function of the cell's own height. Absolute positioning severs that return
+ * path: `.bar-container` is `position: relative`, so `inset: 0` pins the
+ * renderer to the cell the tank's grid/flex layout already decided on, and a
+ * rounding difference between the two can no longer relayout the tank
+ * (issue #1121). */
 .bar-container > obc-gauge-trend,
 .bar-container > obc-bar-vertical {
   display: block;
+  position: absolute;
+  inset: 0;
   width: 100%;
   height: 100%;
 }