affora 0.1.0

package/cli/affora.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+
+import { access, copyFile, mkdir, readFile } from "node:fs/promises"
+import { constants } from "node:fs"
+import path from "node:path"
+import process from "node:process"
+import { fileURLToPath } from "node:url"
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const manifest = JSON.parse(await readFile(path.join(packageRoot, "registry.json"), "utf8"))
+const items = manifest.items
+
+function usage() {
+  return `Affora copy-in component CLI
+
+Usage:
+  affora list
+  affora add <item...> [--cwd <directory>] [--path <directory>] [--force] [--dry-run]
+  affora add --all [--cwd <directory>] [--path <directory>] [--force] [--dry-run]
+
+Examples:
+  npx affora add combobox
+  npx affora add product-card dialog --path src/ui
+  npx affora add --all
+  npx affora add themes --path src/styles
+
+Components automatically include the Affora theme tokens. Existing files are
+never overwritten unless --force is passed.`
+}
+
+function fail(message) {
+  console.error(`affora: ${message}`)
+  process.exitCode = 1
+}
+
+function parse(argv) {
+  const [command, ...rest] = argv
+  const options = { cwd: process.cwd(), path: "src", force: false, dryRun: false, all: false }
+  const names = []
+  for (let i = 0; i < rest.length; i += 1) {
+    const arg = rest[i]
+    if (arg === "--force") options.force = true
+    else if (arg === "--dry-run") options.dryRun = true
+    else if (arg === "--all") options.all = true
+    else if (arg === "--cwd" || arg === "--path") {
+      const value = rest[++i]
+      if (!value || value.startsWith("--")) throw new Error(`${arg} requires a value`)
+      options[arg.slice(2)] = value
+    } else if (arg.startsWith("--")) throw new Error(`unknown option ${arg}`)
+    else names.push(arg)
+  }
+  return { command, names, options }
+}
+
+function resolveNames(requested) {
+  const resolved = []
+  const visiting = new Set()
+  const add = (name) => {
+    if (!items[name]) throw new Error(`unknown item "${name}"; run \`affora list\``)
+    if (visiting.has(name)) return
+    visiting.add(name)
+    for (const dependency of items[name].requires) add(dependency)
+    resolved.push(name)
+  }
+  for (const name of requested) add(name)
+  return resolved
+}
+
+async function exists(filename) {
+  try {
+    await access(filename, constants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function add(requested, options) {
+  if (requested.length === 0) throw new Error("add requires at least one item")
+  const names = resolveNames(requested)
+  const base = path.resolve(options.cwd, options.path)
+  const planned = names.map((name) => ({
+    name,
+    source: path.join(packageRoot, items[name].source),
+    destination: path.join(base, items[name].target),
+  }))
+
+  if (!options.force) {
+    const conflicts = []
+    for (const file of planned) if (await exists(file.destination)) conflicts.push(file.destination)
+    if (conflicts.length > 0) {
+      throw new Error(`refusing to overwrite ${conflicts.map((file) => path.relative(options.cwd, file)).join(", ")}; pass --force to replace`)
+    }
+  }
+
+  for (const file of planned) {
+    const shown = path.relative(options.cwd, file.destination)
+    if (options.dryRun) console.log(`would add ${file.name} -> ${shown}`)
+    else {
+      await mkdir(path.dirname(file.destination), { recursive: true })
+      await copyFile(file.source, file.destination)
+      console.log(`added ${file.name} -> ${shown}`)
+    }
+  }
+}
+
+async function main() {
+  let parsed
+  try {
+    parsed = parse(process.argv.slice(2))
+    if (!parsed.command || parsed.command === "help" || parsed.command === "--help" || parsed.command === "-h") {
+      console.log(usage())
+      return
+    }
+    if (parsed.command === "list") {
+      for (const [name, item] of Object.entries(items)) console.log(`${name.padEnd(14)} ${item.description}`)
+      return
+    }
+    if (parsed.command === "add") {
+      if (parsed.options.all && parsed.names.length) throw new Error("use item names or --all, not both")
+      const requested = parsed.options.all ? Object.keys(items).filter((name) => name !== "themes") : parsed.names
+      await add(requested, parsed.options)
+      return
+    }
+    throw new Error(`unknown command "${parsed.command}"`)
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error))
+  }
+}
+
+await main()

package/design.md

@@ -0,0 +1,113 @@
+# Designing with Affora
+
+Affora is a design system for interfaces with two readers: a person who sees
+the page and an agent that enumerates the document. Its central contract is:
+
+> What an interface declares is fixed and checked. What it paints is free.
+
+Affora calls the declared document the **substrate** and its visual expression
+the **skin**. A skin may change colour, typography, shape, spacing, layout,
+motion, and effects. It must not remove or rename the controls, facts, state,
+or relationships on which either reader depends.
+
+## Three layers
+
+Use one vocabulary throughout product and code:
+
+1. **Primitive** — a single native interaction such as a button, input, or
+   select. Prefer the native element and give it a persistent accessible name.
+2. **Composition** — several primitives that express one coherent object, such
+   as a product card, data table, or settings form.
+3. **Flow pattern** — state and actions across time, such as a multi-step form,
+   gated action, recoverable deletion, or error-remedy sequence.
+
+The current registry contains Affora's native primitive layer, five
+compositions, and five flow patterns. Affora does not rebrand the project's
+shadcn control condition as its primitive layer; each published item uses
+native controls and has no experiment-harness dependency.
+
+## The substrate rules
+
+### State is stated
+
+Render task-relevant state as document text or native state, not only as
+colour, position, or styling. Say which item is selected, which page is current,
+what was saved, and which actions have completed. A count alone is not a
+receipt: name the completed items when identity matters.
+
+### Answers are present
+
+If content can answer the reader's question, keep it in the document. It may be
+visually collapsed, clipped, or progressively revealed, but interaction must
+not be the only way for a document reader to discover that it exists.
+
+### Affordances are real and named
+
+Use native controls. Give every control a stable name, preferably visible text.
+An icon can accompany the name but must not be its only carrier. The visible
+and operable target must occupy the same place.
+
+### Meaning has more than one carrier
+
+Colour, geometry, motion, and position may reinforce meaning; none may be the
+only source of it. Status, severity, destructive consequence, and selection
+must also be stated.
+
+### Structure matches hierarchy
+
+Use headings for headings, labels for fields, fieldsets for grouped choices,
+tables for tabular relationships, and lists for lists. Visual rank may vary by
+theme; semantic rank must remain truthful.
+
+### Constraints precede failure
+
+State required values, formats, ranges, and unlocking conditions before the
+reader attempts an action. A disabled control must name why it is disabled and
+the control or action that resolves the condition.
+
+### Feedback persists
+
+Keep outcomes readable after the action completes. Toasts may provide immediate
+feedback, but durable state must also remain in the document. Error messages
+must say what failed, why, and what named action corrects it.
+
+### Vocabulary and shape stay stable
+
+Use one name for one concept and one semantic shape for one pattern. This helps
+people learn the product and lets agents reuse a successful action recipe.
+
+## Flow rules
+
+- Minimise interaction depth. Each required step adds an observation cycle and
+  another place to lose context.
+- Make each screen self-describing. Restate task facts and progress needed to
+  continue; do not assume access to the previous screen.
+- Offer a direct path beside guided presentation. Visual staging must not require
+  serial interaction when the underlying task can be submitted directly.
+- Prefer cheap reversal to routine confirmation. Mark irreversible actions
+  explicitly; use undo where recovery is possible.
+- State completion and leave a durable result the reader can verify.
+
+## Skin contract
+
+Components consume semantic custom properties from `themes.css`; they do not
+choose a theme. Apply a style and layout at an ancestor:
+
+```html
+<html data-flagship="swiss" data-layout="saas" data-mode="light">
+```
+
+Changing those attributes may change the skin, never the substrate. When adding
+a theme, define the complete token vocabulary and preserve token meaning across
+light and dark modes. Do not target a component's internal classes from a theme.
+
+## Review gate
+
+Before accepting a component or rewrite, verify all three statements:
+
+1. The page still **says** every task-relevant fact and state.
+2. The page still **has** every required affordance with a stable name.
+3. Using an affordance still **causes** the same product effect.
+
+Then run Affora's executable checks. A passing check suite establishes document
+conformance; it does not guarantee that every agent will complete every task.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "affora",
+  "version": "0.1.0",
+  "description": "Components for interfaces with two readers: a person, and an agent that reads the page",
+  "keywords": [
+    "react",
+    "components",
+    "design-system",
+    "accessibility",
+    "agents",
+    "copy-in"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://affora.design",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/srcJin/Agent_Friendly_Web_Design.git",
+    "directory": "library"
+  },
+  "bugs": {
+    "url": "https://github.com/srcJin/Agent_Friendly_Web_Design/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "affora": "cli/affora.mjs"
+  },
+  "files": [
+    "cli/affora.mjs",
+    "registry.json",
+    "src/primitives/",
+    "src/components/",
+    "src/patterns/",
+    "src/tokens/",
+    "checks/",
+    "rules/",
+    "README.md",
+    "design.md",
+    "agent.md",
+    "CHANGELOG.md",
+    "CHECKS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "demo": "vite demo --port 5280 --strictPort",
+    "build:demo": "vite build demo --config demo/vite.config.js",
+    "check": "node checks/cli.mjs",
+    "typecheck": "tsc -p tsconfig.json",
+    "test:cli": "node --test cli/affora.test.mjs",
+    "test": "npm run typecheck && npm run test:cli"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^4.3.3",
+    "playwright": "^1.63.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^7.0.2",
+    "vite": "^5.4.10"
+  }
+}

package/registry.json

@@ -0,0 +1,83 @@
+{
+  "version": 1,
+  "items": {
+    "action-button": {
+      "description": "Named native action with stated loading and destructive consequences.",
+      "source": "src/primitives/actionbutton.tsx",
+      "target": "primitives/affora/action-button.tsx",
+      "requires": ["themes"]
+    },
+    "text-field": {
+      "description": "Native text field with persistent label, constraint, and error remedy.",
+      "source": "src/primitives/textfield.tsx",
+      "target": "primitives/affora/text-field.tsx",
+      "requires": ["themes"]
+    },
+    "combobox": {
+      "description": "Searchable framework picker with enumerable native options.",
+      "source": "src/components/combobox.tsx",
+      "target": "components/affora/combobox.tsx",
+      "requires": ["themes"]
+    },
+    "data-table": {
+      "description": "Sortable semantic data table with named row actions.",
+      "source": "src/components/datatable.tsx",
+      "target": "components/affora/data-table.tsx",
+      "requires": ["themes"]
+    },
+    "dialog": {
+      "description": "Modal dialog with stated constraints and focus management.",
+      "source": "src/components/dialog.tsx",
+      "target": "components/affora/dialog.tsx",
+      "requires": ["themes"]
+    },
+    "product-card": {
+      "description": "Product card whose variant and quantity remain explicit state.",
+      "source": "src/components/productcard.tsx",
+      "target": "components/affora/product-card.tsx",
+      "requires": ["themes"]
+    },
+    "settings-form": {
+      "description": "Settings form with persistent labels, help, and saved state.",
+      "source": "src/components/settingsform.tsx",
+      "target": "components/affora/settings-form.tsx",
+      "requires": ["themes"]
+    },
+    "gated-action": {
+      "description": "Disabled action that persistently names its blocker and remedy.",
+      "source": "src/patterns/gatedaction.tsx",
+      "target": "patterns/affora/gated-action.tsx",
+      "requires": ["themes"]
+    },
+    "error-remedy": {
+      "description": "Persistent form error that names the conflict and corrective action.",
+      "source": "src/patterns/errremedy.tsx",
+      "target": "patterns/affora/error-remedy.tsx",
+      "requires": ["themes"]
+    },
+    "confirm-undo": {
+      "description": "Recoverable destructive action with a persistent named undo.",
+      "source": "src/patterns/confirmundo.tsx",
+      "target": "patterns/affora/confirm-undo.tsx",
+      "requires": ["themes"]
+    },
+    "flow-form": {
+      "description": "Guided form whose complete directly submittable substrate stays mounted.",
+      "source": "src/patterns/flowform.tsx",
+      "target": "patterns/affora/flow-form.tsx",
+      "requires": ["themes"]
+    },
+    "persistent-feedback": {
+      "description": "Action result and returned value that persist until superseded.",
+      "source": "src/patterns/persistentfeedback.tsx",
+      "target": "patterns/affora/persistent-feedback.tsx",
+      "requires": ["themes"]
+    },
+    "themes": {
+      "description": "Affora semantic and layout tokens with sixteen visual themes.",
+      "source": "src/tokens/themes.css",
+      "target": "styles/affora/themes.css",
+      "requires": []
+    }
+  }
+}

package/rules/antd.js

@@ -0,0 +1,173 @@
+// Ant Design rules — developed and verified against NATIVE antd projects
+// (ant.design's own component demos), never against our benchmark re-creations,
+// which would make the validation circular.
+//
+// Empirically probed idioms, and they differ from every other library here:
+//   Select    the focusable element is an <input role="combobox"> whose VALUE is
+//             not in the input at all — it is rendered in a sibling
+//             .ant-select-selection-item, and the options portal into
+//             .ant-select-dropdown only once opened.
+//   Tabs      the tab is a DIV (.ant-tabs-tab-btn[role=tab]), not a button, and
+//             inactive panels are unmounted like Radix's.
+//   Collapse  .ant-collapse-header carries aria-expanded and the content lives in
+//             a sibling panel — .ant-collapse-panel in v6, .ant-collapse-content in
+//             v5 — which stays mounted once opened.
+({
+  antd_select: {
+    find: () => [...document.querySelectorAll('input.ant-select-selection-search-input, input.ant-select-input, .ant-select input[role="combobox"]')],
+    extract: (el) => {
+      const wrap = el.closest('.ant-select');
+      if (!wrap) return null;
+      const owned = el.getAttribute('aria-controls');
+      let box = owned && document.getElementById(owned);
+      if (!box) box = document.querySelector('.ant-select-dropdown:not(.ant-select-dropdown-hidden)');
+      const opts = box ? [...box.querySelectorAll('.ant-select-item-option, [role="option"]')]
+        .map(o => ({ value: o.getAttribute('data-value') || rsRendered(o), label: rsRendered(o) }))
+        .filter(o => o.label) : [];
+      if (!opts.length) {
+        const tries = +(el.getAttribute('data-rs-probe') || 0);
+        if (tries >= 3) return null;
+        el.setAttribute('data-rs-probe', String(tries + 1));
+        // antd opens on mousedown on the SELECTOR, not on the inner input
+        const sel = wrap.querySelector('.ant-select-selector') || wrap;
+        sel.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+        sel.dispatchEvent(new MouseEvent('mouseup', { bubbles: true }));
+        return 'retry';
+      }
+      // The chosen value is rendered beside the input, never inside it, so reading
+      // el.value returns empty on a select that plainly shows a selection. In
+      // multiple/tags mode there is one item PER selection, and reading only the
+      // first silently deleted every other chosen value — 17 lost facts on the
+      // demo page.
+      const chosen = [...wrap.querySelectorAll('.ant-select-selection-item')]
+        .map(n => rsRendered(n)).filter(Boolean);
+      const multi = wrap.classList.contains('ant-select-multiple') || chosen.length > 1;
+      const shown = chosen.join(', ');
+      const placeholder = rsRendered(wrap.querySelector('.ant-select-selection-placeholder'));
+      document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+      return { label: rsLabel(wrap), opts, current: shown, chosen, multi, placeholder,
+               wrap, id: el.getAttribute('id') || '' };
+    },
+    anchor: (el, d) => d.wrap,
+    render: (d) => {
+      const id = d.id || ('rs-' + (++window.__rsSeq));
+      const chosen = new Set(d.chosen || []);
+      // Options the page shows as chosen but that are not in the harvested list
+      // (a tags-mode select accepts free text) must still be stated, or the swap
+      // deletes what the user picked.
+      const extra = (d.chosen || []).filter(c => !d.opts.some(o => o.label === c));
+      return `<div class="rs rs-field">
+        ${d.label ? `<label class="rs-label" for="${id}">${rsEsc(d.label)}</label>` : ''}
+        ${d.multi && chosen.size ? `<p class="rs-label">Selected: ${rsEsc(d.current)}</p>` : ''}
+        <select class="rs-select" id="${id}"${d.multi ? ' multiple' : ''}>
+          ${chosen.size ? '' : `<option value="" selected>${rsEsc(d.placeholder || 'Select…')}</option>`}
+          ${extra.map(c => `<option value="${rsEsc(c)}" selected>${rsEsc(c)}</option>`).join('')}
+          ${d.opts.map(o => `<option value="${rsEsc(o.value)}"${chosen.has(o.label) ? ' selected' : ''}>${rsEsc(o.label)}</option>`).join('')}
+        </select>
+      </div>`;
+    },
+  },
+
+  antd_tabs: {
+    // flattening: the tab/section controls exist to reveal content this
+    // output reveals structurally, so they are subsumed, not lost
+    subsumes: true,
+    find: () => {
+    // A NAVIGATION switcher is not a content tab strip. Atomic CRM renders its
+    // top navigation as MUI Tabs whose tabs are links; probing one navigated
+    // the application to its root and the flattening then replaced the page,
+    // costing the rewritten arm 25 of 36 tasks it could otherwise do. The
+    // generic tabs rule has carried this guard since Magento's mobile nav.
+    const contentTabs = (el) => !el.closest('nav,[role="navigation"]')
+      && ![...el.querySelectorAll('[role="tab"]')].some(t => t.tagName === 'A' && t.getAttribute('href'));
+      return [...document.querySelectorAll('.ant-tabs-nav-list, [role="tablist"]')]
+        .filter(t => t.querySelector('[role="tab"]'))
+        .filter(contentTabs)
+    },
+    extract: (el) => {
+      const trigs = [...el.querySelectorAll('[role="tab"]')];
+      if (trigs.length < 2) return null;
+      const st = el.__rsCap || (el.__rsCap = { caps: {} });
+      let missing = null;
+      trigs.forEach(t => {
+        const key = rsRendered(t);
+        if (!key) return;
+        const id = t.getAttribute('aria-controls');
+        const panel = id ? document.getElementById(id) : null;
+        if (panel && rsRendered(panel)) st.caps[key] = { title: key, html: panel.innerHTML, panel };
+        else if (!(key in st.caps) && !missing) missing = t;
+      });
+      if (missing) {
+        const tries = +(el.getAttribute('data-rs-probe') || 0);
+        if (tries < trigs.length * 2 + 2) {
+          el.setAttribute('data-rs-probe', String(tries + 1));
+          // a DIV tab responds to click, not to form activation
+          missing.dispatchEvent(new MouseEvent('mousedown', { bubbles: true }));
+          missing.click();
+          return 'retry';
+        }
+      }
+      // Keep EVERY tab's title, not only the ones whose panel we captured. A demo
+      // with an overflow menu never mounts the hidden tabs' panels, so filtering
+      // to captured ones deleted the names 'Tab-28' and 'Tab-29' from a page that
+      // plainly lists them. A title with no body asserts that the tab exists and
+      // says nothing about its contents, which is exactly what we know.
+      const tabs = trigs.map(t => {
+        const key = rsRendered(t);
+        return key ? (st.caps[key] || { title: key, html: '', panel: null }) : null;
+      }).filter(Boolean);
+      return tabs.filter(t => t.html).length >= 1 && tabs.length >= 2 ? { tabs } : null;
+    },
+    render: (d) => `<div class="rs rs-sections">` + d.tabs.map(t =>
+        `<section class="rs-section"><h3 class="rs-section-title">${rsEsc(t.title)}</h3>
+         ${t.html ? `<div class="rs-section-body">${t.html}</div>` : ''}</section>`).join('')
+        + `</div>`,
+    removes: (d) => d.tabs.map(t => t.panel).filter(Boolean),
+    after: (d) => d.tabs.forEach(t => t.panel && t.panel.isConnected && t.panel.remove()),
+  },
+
+  antd_collapse: {
+    // flattening: the tab/section controls exist to reveal content this
+    // output reveals structurally, so they are subsumed, not lost
+    subsumes: true,
+    find: () => {
+      const roots = new Set();
+      document.querySelectorAll('.ant-collapse').forEach(c => {
+        if (c.querySelectorAll('.ant-collapse-header').length >= 2) roots.add(c);
+      });
+      return [...roots];
+    },
+    extract: (el) => {
+      const heads = [...el.querySelectorAll('.ant-collapse-header')];
+      const st = el.__rsCap || (el.__rsCap = { caps: {} });
+      let missing = null;
+      heads.forEach(h => {
+        const key = rsRendered(h);
+        if (!key) return;
+        const item = h.closest('.ant-collapse-item') || h.parentElement;
+        // antd renamed this between majors — v5 ships .ant-collapse-content, v6
+        // ships .ant-collapse-panel — so a single-name selector matched nothing on
+        // the current site and the rule reported zero instances on a page full of
+        // them. Accept both rather than pinning a version.
+        const body = item && item.querySelector('.ant-collapse-panel, .ant-collapse-content');
+        if (body && rsRendered(body)) st.caps[key] = { title: key, html: body.innerHTML, panel: body };
+        else if (!(key in st.caps) && !missing) missing = h;
+      });
+      if (missing) {
+        const tries = +(el.getAttribute('data-rs-probe') || 0);
+        if (tries < heads.length * 2 + 2) {
+          el.setAttribute('data-rs-probe', String(tries + 1));
+          missing.click();
+          return 'retry';
+        }
+      }
+      const secs = heads.map(h => st.caps[rsRendered(h)]).filter(Boolean);
+      return secs.length >= 2 ? { secs } : null;
+    },
+    render: (d) => `<div class="rs rs-sections">` + d.secs.map(t =>
+        `<section class="rs-section"><h3 class="rs-section-title">${rsEsc(t.title)}</h3>
+         <div class="rs-section-body">${t.html}</div></section>`).join('') + `</div>`,
+    removes: (d) => d.secs.map(t => t.panel),
+    after: (d) => d.secs.forEach(t => t.panel && t.panel.isConnected && t.panel.remove()),
+  },
+})