division-ds 0.2.1 → 0.3.1

package/scripts/lib/agent-docs.mjs

@@ -31,8 +31,29 @@ export function alsoExports(entry) {
     .filter(name => /^[A-Z][a-z]/.test(name) && !name.startsWith(entry.name) && !name.endsWith('Provider'))
 }
 
+/** The docs site's top-bar search reads this, fetched the first time search opens. Slim on purpose:
+ *  the names, the one-line summaries and the prop names and descriptions the shared scorer
+ *  (search-score.mjs) ranks on, and the screen-facing tokens. Primitives are left out, as in the
+ *  MCP search: they are never the answer for a screen. */
+export function searchIndex(entries, tokens) {
+  const index = {
+    generatedBy: 'scripts/build-agent-docs.mjs',
+    components: entries.map(entry => ({
+      name: entry.name,
+      slug: entry.slug,
+      tier: entry.tier,
+      summary: entry.summary,
+      useWhen: entry.useWhen,
+      also: alsoExports(entry),
+      props: entry.props.map(prop => ({ name: prop.name, description: prop.description ?? '' })),
+    })),
+    tokens: tokens.tokens.filter(token => token.layer !== 'primitive').map(token => ({ name: token.name, layer: token.layer, use: token.use ?? '' })),
+  }
+  return JSON.stringify(index) + '\n'
+}
+
 /** Said under every Import block: the paths are the repository's, not an installed project's. */
-export const INSTALLED_PATHS = 'Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file.'
+export const INSTALLED_PATHS = 'Paths are from the Division DS repository root. Installed with shadcn they start `src/division-ds/` instead of `src/` (`src/division-ds/components/...`); import them relative to your file. An install has no index barrels: import each component from its own file, never from `components/molecules`.'
 
 /** One component as a markdown page. `entry` is a manifest entry (see `manifestEntry`). */
 export function componentMarkdown(entry) {

package/scripts/lib/mcp-tools.mjs

@@ -9,6 +9,7 @@ import { alsoExports, INSTALLED_PATHS } from './agent-docs.mjs'
 import { checkText } from './check-text.mjs'
 import { contrastRatio } from './contrast.mjs'
 import { buildIndex, closest } from './props-validator.mjs'
+import { scorer, words } from './search-score.mjs'
 
 export const REGISTRY_BASE = 'https://raw.githubusercontent.com/Victor-Ilioiu/division-ds/main/public/r'
 const TIERS = ['atoms', 'molecules', 'organisms']
@@ -16,7 +17,6 @@ const LAYERS = ['primitive', 'spacing', 'motion', 'semantic', 'component']
 // WCAG 2.2 minimums: SC 1.4.3 for text, SC 1.4.11 for the boundary of a control or a graphic.
 const MINIMUMS = { normal: 4.5, large: 3, ui: 3 }
 
-const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
 
 /** `context`: { manifest, tokens, version, readDoc(slug) -> string|undefined, readChecklist() -> string|undefined } */
 export function createTools(context) {
@@ -122,19 +122,7 @@ export function createTools(context) {
       run({ query, limit = 10 }) {
         const terms = words(query)
         if (terms.length === 0) throw new ToolError('query has no words to search for.')
-        // `props` is the prop descriptions: a word found there counts once, as a hint, so a long
-        // prop table does not outrank a component or token whose own summary is about the query.
-        const score = (title, body, props = '', propNames = '') => {
-          const t = words(title).join(' ')
-          const b = words(body)
-          const p = words(props)
-          const n = words(propNames)
-          const inMain = term => t.includes(term) || b.some(w => w.startsWith(term))
-          // Every word of the query in the name or summary beats one word found often: "page
-          // background" is the surface token, not PageHeader, whose name matches "page" alone.
-          const all = terms.length > 1 && terms.every(inMain) ? 5 : 0
-          return all + terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + Math.min(b.filter(w => w.startsWith(term)).length, 3) + (inMain(term) ? 0 : n.some(w => w.startsWith(term)) ? 2 : p.some(w => w.startsWith(term)) ? 1 : 0), 0)
-        }
+        const score = scorer(query)
         const hits = [
           // The title holds every name on the page (ChatMessage and ResponseFeedback); the body adds
           // the prop descriptions, where what a part does is written ("helpful", "thumbs up").

package/scripts/lib/props-validator.mjs

@@ -156,7 +156,14 @@ export function buildIndex(manifest) {
     const single = exportNames.length === 1
     for (const name of exportNames) {
       const spec = specs[name]
-      spec.checkUnknown = single && !unresolved && spec.rest?.open !== 'any'
+      // On a page that documents several components, the rows with no part tag are the main
+      // component's own. The main one is checked too when nothing passes through undocumented:
+      // its type is closed (manifest `closed`), or its only pass-through is native attributes,
+      // which the check already allows. Its parts stay unchecked: their rows list only what
+      // differs from the main component.
+      const main = name === entry.name && (entry.closed === true || spec.rest?.open === 'native')
+      spec.checkUnknown = (single || main) && !unresolved && spec.rest?.open !== 'any'
+      spec.namedByFormField = (entry.namedByFormField ?? []).includes(name)
       index.set(name, spec)
     }
   }
@@ -228,7 +235,7 @@ export function scriptKind(path) {
 
 /**
  * Every props violation in one file: `{ path, line, column, rule, component, prop, found, fix }`.
- * `rule` is 'unknown-prop' or 'invalid-value'. `index` comes from `buildIndex`.
+ * `rule` is 'unknown-prop', 'invalid-value' or 'missing-label' (a control FormField names, with no label and no FormField around it). `index` comes from `buildIndex`.
  */
 export function findPropViolations(text, path, index) {
   const source = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path))
@@ -254,11 +261,38 @@ export function findPropViolations(text, path, index) {
     return undefined
   }
 
+  // Inside a Division FormField, which names the control it holds.
+  const insideFormField = element => {
+    for (let node = element.parent; node; node = node.parent) {
+      const opening = ts.isJsxElement(node) ? node.openingElement : ts.isJsxSelfClosingElement(node) ? node : null
+      if (opening && opening !== element && resolve(opening.tagName) === 'FormField') return true
+    }
+    return false
+  }
+
   const check = element => {
     const exportName = resolve(element.tagName)
     const spec = exportName && index.get(exportName)
     if (!spec) return
     const tag = element.tagName.getText(source)
+    const attributes = element.attributes.properties
+    if (
+      spec.namedByFormField &&
+      !attributes.some(a => ts.isJsxSpreadAttribute(a) || a.name.getText(source) === 'label') &&
+      !insideFormField(element)
+    ) {
+      const at = source.getLineAndCharacterOfPosition(element.getStart(source))
+      violations.push({
+        path,
+        line: at.line + 1,
+        column: at.character + 1,
+        rule: 'missing-label',
+        component: tag,
+        prop: 'label',
+        found: `<${tag}>`,
+        fix: `${tag} has no name: give it a label, or put it in a FormField, which names it. See ${spec.docs}.`,
+      })
+    }
     const known = [...spec.props.keys()]
     for (const attribute of element.attributes.properties) {
       if (!ts.isJsxAttribute(attribute)) continue

package/scripts/lib/search-score.mjs

@@ -0,0 +1,24 @@
+// The one ranking for "find me the thing for X". The MCP server's `search` tool and the docs site's
+// top-bar search both call it, so an agent and a person typing the same words get the same order.
+// Pure and dependency-free: it runs in Node and in the browser.
+
+export const words = text => String(text).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+
+/** A scorer for one query. `title` is the names, `body` the summary; `props` (descriptions) and
+ *  `propNames` count once each, as hints, so a long prop table does not outrank a component or
+ *  token whose own summary is about the query. 0 means no match. */
+export function scorer(query) {
+  const terms = words(query)
+  return (title, body, props = '', propNames = '') => {
+    if (terms.length === 0) return 0
+    const t = words(title).join(' ')
+    const b = words(body)
+    const p = words(props)
+    const n = words(propNames)
+    const inMain = term => t.includes(term) || b.some(w => w.startsWith(term))
+    // Every word of the query in the name or summary beats one word found often: "page
+    // background" is the surface token, not PageHeader, whose name matches "page" alone.
+    const all = terms.length > 1 && terms.every(inMain) ? 5 : 0
+    return all + terms.reduce((sum, term) => sum + (t.includes(term) ? 3 : 0) + Math.min(b.filter(w => w.startsWith(term)).length, 3) + (inMain(term) ? 0 : n.some(w => w.startsWith(term)) ? 2 : p.some(w => w.startsWith(term)) ? 1 : 0), 0)
+  }
+}

package/skills/division-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: division-ds
-description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 68 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
+description: Use when building or changing UI with Division DS (React 19, Tailwind 4, Radix; 72 components). Covers which component and token to use, the composition rules prop types cannot express (providers, FormField, button gaps, card borders), planning a screen's states, and how to check the result. Load it before writing any screen or component in a project that has Division DS components.
 ---
 
 # Division DS
@@ -82,7 +82,7 @@ provider. A project that uses the components mounts both itself (step 4 of `inst
 `src/demo/states/` files are not part of the system.
 
 **What the system does not have.** No Popover, no Combobox (single value: use `Select`; several:
-`MultiSelect`), no date picker. Do not reach into `src/demo/` from a component.
+`MultiSelect`). Do not reach into `src/demo/` from a component.
 
 **Vocabulary.** Inside this repository, `npm run check:vocabulary` bans a list of words in `src/`,
 `scripts/` and `e2e/` (the list is `scripts/lib/vocabulary.mjs`; it is not published with the

package/skills/division-ds/topics/forms.md

@@ -11,7 +11,7 @@ renders `ErrorSummary` at the top and focuses it; `useFieldErrors` holds the sta
 `public/docs/helpers.md`).
 
 A `RadioGroup` in a form sits in a `<fieldset>` whose `<legend>` names it (code on the Radio
-page). A date is `<Input type="date">` in a `FormField`.
+page). A date is `DatePicker` in a `FormField`; its value is 'YYYY-MM-DD'.
 
 **Buttons.** Two or more buttons side by side need a parent with a gap
 (`flex flex-wrap gap-3`); `DialogFooter` and `CardFooter` already are one. A `Button` is